From 13427ecd8ba5bfa7892fc90d1e3f0ef59514870f Mon Sep 17 00:00:00 2001
From: Shpetim <32248437+ShpetimA@users.noreply.github.com>
Date: Fri, 4 Sep 2026 21:37:26 +0200
Subject: [PATCH 01/56] fix(web): restore file comment focus in editable
 preview (#9061)

---
 .../diffs/DiffCommentAnnotation.tsx           | 18 ++++-
 .../src/components/files/FilePreviewPanel.tsx | 75 ++++++++++---------
 2 files changed, 55 insertions(+), 38 deletions(-)

diff --git a/apps/web/src/components/diffs/DiffCommentAnnotation.tsx b/apps/web/src/components/diffs/DiffCommentAnnotation.tsx
index d210732b6b60..bce9f7e55f58 100644
--- a/apps/web/src/components/diffs/DiffCommentAnnotation.tsx
+++ b/apps/web/src/components/diffs/DiffCommentAnnotation.tsx
@@ -1,5 +1,5 @@
 import { MessageCircle, Trash2 } from "lucide-react";
-import { useState, type ReactNode } from "react";
+import { useLayoutEffect, useRef, useState, type ReactNode } from "react";
 
 import { Button } from "~/components/ui/button";
 import { Textarea } from "~/components/ui/textarea";
@@ -25,6 +25,7 @@ interface DiffCommentAnnotationProps {
   submitLabel?: string;
   pending?: boolean;
   secondaryAction?: DiffCommentSecondaryAction;
+  focusOnMount?: boolean;
 }
 
 /** The shared inline comment treatment for file previews, thread diffs, and pull-request diffs. */
@@ -40,10 +41,20 @@ export function DiffCommentAnnotation({
   submitLabel = "Comment",
   pending = false,
   secondaryAction,
+  focusOnMount = true,
 }: DiffCommentAnnotationProps) {
   const [localDraftText, setLocalDraftText] = useState("");
   const displayedText = kind === "draft" && !onTextChange ? localDraftText : text;
   const trimmedText = displayedText.trim();
+  const textareaRef = useRef<HTMLTextAreaElement | null>(null);
+
+  useLayoutEffect(() => {
+    if (kind !== "draft" || !focusOnMount) return;
+    const frame = window.requestAnimationFrame(() => {
+      textareaRef.current?.focus({ preventScroll: true });
+    });
+    return () => window.cancelAnimationFrame(frame);
+  }, [focusOnMount, kind]);
 
   if (kind === "comment") {
     return (
@@ -78,9 +89,10 @@ export function DiffCommentAnnotation({
       onPointerDown={(event) => event.stopPropagation()}
     >
       <Textarea
-        autoFocus
+        ref={textareaRef}
+        autoFocus={focusOnMount}
         unstyled
-        className="relative inline-flex w-full rounded-md border border-border/50 bg-background/20 font-sans text-foreground transition-colors focus-within:border-border/70 [&_[data-slot=textarea]]:min-h-12 [&_[data-slot=textarea]]:cursor-text [&_[data-slot=textarea]]:px-2.5 [&_[data-slot=textarea]]:py-1.5 [&_[data-slot=textarea]]:font-sans [&_[data-slot=textarea]]:text-xs [&_[data-slot=textarea]]:leading-5 max-sm:[&_[data-slot=textarea]]:min-h-12"
+        className="relative inline-flex w-full rounded-md border border-border/50 bg-background/20 font-sans text-foreground transition-colors focus-within:border-border/70 [&_[data-slot=textarea]]:min-h-12 [&_[data-slot=textarea]]:cursor-text [&_[data-slot=textarea]]:caret-foreground [&_[data-slot=textarea]]:px-2.5 [&_[data-slot=textarea]]:py-1.5 [&_[data-slot=textarea]]:font-sans [&_[data-slot=textarea]]:text-xs [&_[data-slot=textarea]]:leading-5 max-sm:[&_[data-slot=textarea]]:min-h-12"
         size="sm"
         value={displayedText}
         placeholder={placeholder}
diff --git a/apps/web/src/components/files/FilePreviewPanel.tsx b/apps/web/src/components/files/FilePreviewPanel.tsx
index a702c4c1abd7..5e11abe85771 100644
--- a/apps/web/src/components/files/FilePreviewPanel.tsx
+++ b/apps/web/src/components/files/FilePreviewPanel.tsx
@@ -774,42 +774,47 @@ function EditableFileSurface({
     ],
   );
 
-  const beginComment = useCallback((range: SelectedLineRange) => {
-    const { startLine, endLine } = normalizeFileCommentRange(range);
-    const draftEntry: FileCommentAnnotationEntry = {
-      id: nextFileCommentId(),
-      kind: "draft",
-      startLine,
-      endLine,
-      text: "",
-    };
-    setLineAnnotations((current) => {
-      const withoutDraft = current.flatMap((annotation) => {
-        const entries = annotation.metadata.entries.filter((entry) => entry.kind !== "draft");
-        return entries.length > 0 ? [{ ...annotation, metadata: { entries } }] : [];
+  const beginComment = useCallback(
+    (range: SelectedLineRange) => {
+      editor.setSelections([]);
+      editor.blur();
+      const { startLine, endLine } = normalizeFileCommentRange(range);
+      const draftEntry: FileCommentAnnotationEntry = {
+        id: nextFileCommentId(),
+        kind: "draft",
+        startLine,
+        endLine,
+        text: "",
+      };
+      setLineAnnotations((current) => {
+        const withoutDraft = current.flatMap((annotation) => {
+          const entries = annotation.metadata.entries.filter((entry) => entry.kind !== "draft");
+          return entries.length > 0 ? [{ ...annotation, metadata: { entries } }] : [];
+        });
+        const existingIndex = withoutDraft.findIndex(
+          (annotation) => annotation.lineNumber === endLine,
+        );
+        if (existingIndex < 0) {
+          return [
+            ...withoutDraft,
+            {
+              lineNumber: endLine,
+              metadata: { entries: [draftEntry] },
+            },
+          ];
+        }
+        return withoutDraft.map((annotation, index) =>
+          index === existingIndex
+            ? {
+                ...annotation,
+                metadata: { entries: [...annotation.metadata.entries, draftEntry] },
+              }
+            : annotation,
+        );
       });
-      const existingIndex = withoutDraft.findIndex(
-        (annotation) => annotation.lineNumber === endLine,
-      );
-      if (existingIndex < 0) {
-        return [
-          ...withoutDraft,
-          {
-            lineNumber: endLine,
-            metadata: { entries: [draftEntry] },
-          },
-        ];
-      }
-      return withoutDraft.map((annotation, index) =>
-        index === existingIndex
-          ? {
-              ...annotation,
-              metadata: { entries: [...annotation.metadata.entries, draftEntry] },
-            }
-          : annotation,
-      );
-    });
-  }, []);
+    },
+    [editor],
+  );
   const hasOpenCommentForm = lineAnnotations.some((annotation) =>
     annotation.metadata.entries.some((entry) => entry.kind === "draft"),
   );

From 2e688a53cf8fc7a9caa9fd5070148bfcd3d5a741 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 12:45:04 -0700
Subject: [PATCH 02/56] docs: keep internal guides focused on architecture
 (#9755)

---
 AGENTS.md                                     |   15 +-
 CONTRIBUTING.md                               |    6 +-
 apps/mobile/README.md                         |   12 +-
 docs/README.md                                |   21 +-
 docs/architecture/terminal-renderers.md       |   42 -
 docs/internals/assistant-citations.md         |  160 +--
 docs/internals/ci.md                          |   44 -
 docs/internals/connection-runtime.md          |  271 +---
 docs/internals/environment-auth.md            |  257 +---
 docs/internals/glossary.md                    |  254 +---
 docs/internals/mobile-development.md          |   71 +-
 docs/internals/mobile-navigation.md           |  184 +--
 docs/internals/model-manifest.md              |   63 +-
 docs/internals/overview.md                    |  242 +---
 docs/internals/product-analytics.md           |  222 +---
 docs/internals/providers.md                   |  483 ++-----
 docs/internals/remote.md                      |  315 +----
 docs/internals/resource-telemetry.md          |  444 +------
 docs/internals/scripts.md                     |  215 ---
 docs/internals/server-updates.md              |  164 +--
 docs/internals/t3-code-connect-auth-flow.html | 1160 -----------------
 docs/internals/t3-connect.md                  |  350 ++---
 docs/internals/terminal-runtime.md            |   92 +-
 docs/internals/voice-input.md                 |  118 +-
 docs/internals/work-artifacts.md              |   25 -
 docs/internals/workspace-layout.md            |   63 -
 docs/operations/connect-setup.md              |  126 ++
 docs/operations/development.md                |  140 ++
 docs/operations/release.md                    |    2 +-
 infra/relay/README.md                         |    8 +-
 scripts/build-desktop-artifact.ts             |    4 +-
 31 files changed, 1104 insertions(+), 4469 deletions(-)
 delete mode 100644 docs/architecture/terminal-renderers.md
 delete mode 100644 docs/internals/ci.md
 delete mode 100644 docs/internals/scripts.md
 delete mode 100644 docs/internals/t3-code-connect-auth-flow.html
 delete mode 100644 docs/internals/work-artifacts.md
 delete mode 100644 docs/internals/workspace-layout.md
 create mode 100644 docs/operations/connect-setup.md
 create mode 100644 docs/operations/development.md

diff --git a/AGENTS.md b/AGENTS.md
index 48a6374ab0af..e3b5771d797c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -72,7 +72,7 @@ The most common defect in this repo is a change that works on the path you teste
 - **Contracts.** Anything crossing the wire is typed in `packages/contracts`. Change the schema and the server, web, mobile, and desktop all follow.
 - **Reverse states.** If you added a way in, add the way out and the way to see it. Snooze needs unsnooze. Close needs reopen. A one-way door is a bug.
 - **Connection modes.** Local, remote/relay, and tunnel behave differently. Multi-device and multi-environment cases are real.
-- **Docs.** `docs/` splits by audience. Behavior changes that a user would notice belong in `docs/user/` (shipped-product voice, no repo tooling or source paths); architecture and contributor changes in `docs/internals/`; runbooks in `docs/operations/`; new vocabulary in `docs/internals/glossary.md`.
+- **Docs.** Check whether the change makes existing guidance inaccurate. Apply the [documentation rules](#documentation) before adding anything.
 
 ## Dev servers
 
@@ -120,11 +120,22 @@ An empty database is a bad test. Seed your worktree's `.t3` with a copy of real
 - One concern per PR. If the description says "also", split it.
 - When babysitting: poll checks and comments newer than the last push, verify each bot finding against the source, fix real ones, dismiss false positives with a written reason. Stay quiet when nothing is new. Stop when the bots are green on the latest commit.
 
+## Documentation
+
+Most code changes do not need an internal documentation change. Agents can read the code.
+
+- `docs/internals/` is for architectural decisions and their reasons, constraints that span components, and implementation traps that are hard to discover from the source. Before adding a paragraph, ask what a maintainer would get wrong without it. If reading the relevant code answers the question, leave it out.
+- Do not document every feature, enumerate fields or methods, narrate control flow, maintain file catalogs, or append PR summaries. Types, tests, and code already record the implementation. The glossary defines shared vocabulary; it is not a feature index.
+- Keep a local implementation explanation in a nearby code comment. Use an internal doc when the reasoning crosses boundaries or needs context the code cannot carry well. Link to the relevant source instead of copying it.
+- When a documented decision or constraint changes, rewrite or remove the affected text. Do not append another account of the new behavior. A new internal page needs a distinct, durable reason to exist.
+- `docs/user/` helps users accomplish tasks. Give each major feature a concise section explaining what it does, how to start, and anything unintuitive. A settings path is useful; descriptions of visible buttons, icons, layouts, animations, or every UI state are not. Before adding text, ask what task or decision it helps the user with.
+- Keep user docs in the shipped product's voice, without implementation details or contributor tooling. Update the relevant feature section when how to use it changes. A UI tweak does not need a documentation entry, and a new control does not need its own page.
+- `docs/operations/` holds maintainer setup, release, and debugging procedures. Keep instructions for operating an installed T3 Code server in the user guides.
+
 ## Plans and work artifacts
 
 - Do not commit implementation plans, research notes, or agent scratch files. Keep temporary working material outside the worktree. `.plans/` is gitignored only as a safety net for legacy tooling.
 - Track active maintainer work in the GitHub issue or project item that owns it. External proposals follow `CONTRIBUTING.md` and belong in Ideas discussions.
-- Put durable architecture, constraints, and decisions in `docs/internals/`. Update those docs when the product changes so agents find current facts instead of abandoned intentions.
 - A merged PR is the implementation record. Close or update its tracking item when the work lands; do not preserve a second checklist in the repository.
 
 ## How it works
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5cd75ef96edb..caa8f8309bb9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,7 +2,7 @@
 
 ## Developer Setup
 
-See the [maintainer scripts guide](docs/internals/scripts.md#first-checkout) for the initial checkout,
+See the [development runbook](docs/operations/development.md#first-checkout) for the initial checkout,
 development commands, tests, and platform-specific desktop packaging prerequisites.
 
 ## Read This First
@@ -49,6 +49,10 @@ Explain exactly what changed.
 
 Explain exactly why the change should exist.
 
+Follow the [documentation rules](AGENTS.md#documentation). Keep internal docs for decisions and
+hard-to-discover constraints. Update user guides when how to use a feature changes; skip descriptions
+of obvious controls and cosmetic changes.
+
 Do not mix unrelated fixes together.
 
 If the PR makes anything resembling a UI change, include clear before/after images.
diff --git a/apps/mobile/README.md b/apps/mobile/README.md
index ed95b060fe3a..a9a8177c4ece 100644
--- a/apps/mobile/README.md
+++ b/apps/mobile/README.md
@@ -38,12 +38,8 @@ vp run dev:client:reset
 Run that reset once after installing or changing the Uniwind dependency patch. Cached transforms
 can otherwise reference its previous pnpm package path. Ordinary Metro starts still keep the cache.
 
-Component edits use Fast Refresh. Connection-runtime edits replace the active Effect layer through
-a stable atom runtime, preserving navigation and existing atom subscribers. Replaced registries
-and managed runtimes dispose their resources; the app does not force a JavaScript reload. The Uniwind patch
-skips global style invalidation when generated styles and themes are unchanged, while real style
-changes still refresh. See [mobile development lifecycle](../../docs/internals/mobile-development.md)
-for the lifetime boundaries.
+Component edits use Fast Refresh. See [mobile development lifecycle](../../docs/internals/mobile-development.md)
+before changing runtime ownership or refresh behavior.
 
 Build and run the local iOS dev client:
 
@@ -51,6 +47,10 @@ Build and run the local iOS dev client:
 vp run ios:dev
 ```
 
+After changing a native dependency patch, rerun CocoaPods before rebuilding an existing iOS
+project. pnpm gives each patch hash a new package path; Pods can otherwise keep compiling the
+previous directory.
+
 If your Xcode account only has a Personal Team, use a bundle identifier you control and opt into the
 reduced-capability local build. Personal Team builds omit the widget and share extensions, push
 entitlement, and native Sign in with Apple entitlement; builds without this opt-in are unchanged.
diff --git a/docs/README.md b/docs/README.md
index ce2187ee865f..fe159931b656 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -23,27 +23,34 @@ Mobile app: [apps/mobile/README.md](../apps/mobile/README.md)
 
 ## Working on T3 Code
 
-Everything below is for maintainers. Setup lives in the [root README](../README.md);
-policy in [CONTRIBUTING.md](../CONTRIBUTING.md); agent rules in [AGENTS.md](../AGENTS.md).
+Start with the [development runbook](./operations/development.md) and
+[contribution policy](../CONTRIBUTING.md).
+
+Internal notes preserve architectural decisions, constraints, and implementation traps that the
+source alone does not explain. Most code changes do not need an internal documentation update. Follow the
+[documentation rules](../AGENTS.md#documentation) before adding one.
 
 - [Architecture overview](./internals/overview.md)
-- [Workspace layout](./internals/workspace-layout.md)
 - [Glossary](./internals/glossary.md)
-- [Scripts](./internals/scripts.md)
 - [Connection runtime](./internals/connection-runtime.md)
-- [Voice input](./internals/voice-input.md)
 - [Providers](./internals/providers.md)
+- [Model classification](./internals/model-manifest.md)
 - [Remote environments](./internals/remote.md)
 - [Server updates](./internals/server-updates.md)
 - [Resource telemetry](./internals/resource-telemetry.md)
 - [Product analytics](./internals/product-analytics.md)
 - [Environment auth](./internals/environment-auth.md)
 - [T3 Connect](./internals/t3-connect.md)
-- [CI gates](./internals/ci.md)
-- [Engineering work artifacts](./internals/work-artifacts.md)
+- [Assistant citations](./internals/assistant-citations.md)
+- [Mobile navigation](./internals/mobile-navigation.md)
+- [Mobile development lifecycle](./internals/mobile-development.md)
+- [Terminal runtime](./internals/terminal-runtime.md)
+- [Voice input](./internals/voice-input.md)
 
 ### Runbooks
 
+- [Development and local builds](./operations/development.md)
+- [T3 Connect setup](./operations/connect-setup.md)
 - [Release](./operations/release.md)
 - [Observability](./operations/observability.md)
 - [Relay observability](./operations/relay-observability.md)
diff --git a/docs/architecture/terminal-renderers.md b/docs/architecture/terminal-renderers.md
deleted file mode 100644
index 4b66a13f68c4..000000000000
--- a/docs/architecture/terminal-renderers.md
+++ /dev/null
@@ -1,42 +0,0 @@
-# Terminal renderers
-
-Terminal sessions remain server-owned PTYs. Clients receive the existing raw byte stream and send
-input and resize events over the existing terminal contracts; renderer choices never cross the
-wire.
-
-## Ghostty alignment
-
-Android and web use the official `libghostty-vt` C ABI for parsing, terminal state, grapheme
-boundaries, keyboard encoding, selection, and scrollback:
-
-- Android links the native shared library and converts render state into a compact JNI snapshot.
-- Web loads a separately cached WebAssembly build and reads render state into a Canvas 2D surface.
-- Both artifacts are built from the revision in
-  `native/libghostty-vt/VERSION`.
-
-The platform adapters deliberately own only platform behavior. Android owns its Kotlin Canvas and
-touch integration. Web owns browser font shaping, the hidden IME textarea, clipboard and DOM input,
-and its Canvas renderer. The web adapter also delegates application mouse encoding, word and line
-selection, and OSC 8 hyperlink metadata to the official ABI. Browser conventions remain available:
-holding Shift bypasses application mouse capture, and the platform link modifier opens hyperlinks.
-React does not participate in terminal frames.
-
-The web runtime is singleton-scoped per browser tab so split terminals share one compiled module
-and memory. Each visible terminal owns and frees its own terminal, render state, row iterator, cell
-iterator, key and mouse encoder, and input event handles. Restoring captured scrollback temporarily
-detaches the PTY callback so historical device queries cannot emit replies into the current shell.
-
-## Updating Ghostty
-
-Update and rebuild Android first, because mobile's `VERSION` file is the single source of truth for
-the upstream pin (the upstream `LICENSE` lives beside it). Then run:
-
-```sh
-pnpm --dir apps/web build:ghostty-wasm
-```
-
-Commit the regenerated web `wasm` artifacts. The build embeds the pinned revision into the binary as
-semver build metadata, and the focused web ABI test reads it back through `ghostty_build_info` and
-compares it against mobile's `VERSION` — so the web vendor directory holds only the artifacts, drift
-cannot hide, and there is no second pin to keep in sync. The same test enforces the artifact budget
-and exercises repeated create/write/free cycles with multi-codepoint graphemes.
diff --git a/docs/internals/assistant-citations.md b/docs/internals/assistant-citations.md
index 77bd53dff8d9..2c49163fadb4 100644
--- a/docs/internals/assistant-citations.md
+++ b/docs/internals/assistant-citations.md
@@ -1,135 +1,29 @@
 # Assistant citations
 
-> For maintainers. Using T3 Code? See [Quote an assistant response](../user/composer.md#quote-an-assistant-response).
-
-Assistant citations store a selected excerpt and its source in ordinary message text. They need
-no database migration, citation table, or sidecar draft metadata. The saved excerpt remains
-available even when the source response is missing or has changed.
-
-## Serialized form
-
-[`AssistantCitation`][contract] defines version 1. [`assistantCitations.ts`][shared] serializes it
-as a Markdown link with the literal label `Assistant quote`:
-
-```text
-[Assistant quote](t3-citation://v1/<environmentId>/<threadId>/<messageId>?text=<quote>&start=<start>&end=<end>&prefix=<prefix>&suffix=<suffix>&comment=<optional-user-comment>)
-```
-
-The formatter percent-encodes each path segment and uses `URLSearchParams` for the query. The
-environment, thread, and message IDs identify the source without a browser origin, so local,
-remote, and tunnel clients share one form. Opening the source still requires access to its
-environment.
-
-The parser accepts only version 1 with exactly three source IDs and one of each selector field;
-`comment` is optional and links without one keep their original format. It rejects credentials,
-ports, malformed encoding, and extra or duplicate query fields. IDs have a 512-character limit,
-the quote and comment each fit in 8,000 UTF-16 code units, offsets are nonnegative safe integers
-with `end > start`, prefix and suffix each fit in 32 code units, and the URI itself is capped at
-160,000 characters. Malformed or unsupported links remain ordinary prompt text everywhere:
-collectors, provider expansion, and readable fallbacks all skip them. Parsing validates the
-payload, not the existence of its source.
-
-## Selection and source matching
-
-[`assistantTextSelection.ts`][selection] captures one native DOM range inside one assistant
-response, including backward and paragraph selections. Empty range endpoints at neighboring blocks
-are narrowed to the first and last selected text nodes before validating the source, so
-triple-click selections that end at the next block still resolve. The text stream follows DOM
-order, inserts line breaks between blocks and at `<br>`, and includes displayed code and link
-text. Controls, hidden subtrees, CSS-generated content, and soft wrapping do not contribute.
-
-`text` keeps the exact selected excerpt, including line breaks and indentation. `start`, `end`,
-`prefix`, and `suffix` use the rendered-text stream after each JavaScript whitespace run collapses
-to one space, without trimming, in UTF-16 code units. Context boundaries avoid splitting
-surrogate pairs.
-
-Resolution uses the same normalization and case-sensitive matching. It checks the saved offsets
-against the quote and context, then searches for a context-matching occurrence if positions have
-moved. A unique quote can still match after its context changes. Multiple context-matching
-occurrences are ambiguous, even if one remains at the saved offsets; the resolver does not guess.
-
-## Composer and clients
-
-[`AssistantSelectionToolbar`][toolbar] offers **Cite in composer** for a selection within one
-response and disables it above the quote limit. It shares [`selectionActions.ts`][actions] with
-the terminal's selection menu: the observer opens actions only after a primary-button release from
-a gesture that started inside the surface, waits out the 500 ms repeat-click window so
-double/triple clicks can finish, anchors to the release point (or the text end for keyboard
-selections), and dismisses on outside interaction, scrolling, or `Escape`. The toolbar registers
-its own element with the observer so interacting with it cannot replace the captured quote.
-
-`ChatView` inserts the serialized link at the last composer cursor. A one-shot editor request then
-opens the comment editor beside the cited source text, carrying the live DOM range for positioning
-and an editing highlight; that range is transient and never becomes part of the citation.
-`withAssistantCitationComment` trims outer whitespace and removes the field when blank; it never
-changes the saved quote or selector. Restoring or pasting a citation does not reopen the editor.
-
-[`ComposerCitationNode`][node] is an inline Lexical `DecoratorNode` holding the quote and comment
-as one atomic chip. Its label shows the comment when present, otherwise a short quote preview; the
-node retains the full serialized source and returns it from `getTextContent()`. Comment edits
-update the citation and serialized source together as one undoable change. The token parser,
-clipboard handling, and cursor mapping treat citations as inline tokens alongside mentions and
-skills, so drafts, stashes, and pastes reconstruct chips from the prompt string alone. Sent
-messages keep the same links; `ChatMarkdown` renders valid citation URIs as read-only
-[`AssistantCitationChip`][chip]s, and the whole chip supplies its serialized value to Markdown
-copy so the displayed label is not duplicated as text.
-
-## Source navigation
-
-[`assistantCitationNavigation.ts`][navigation] routes to the source thread with
-`#assistant-citation=<base64url-encoded citation URI>`; the encoding keeps router hash
-normalization from decoding quote whitespace or source IDs. Each click adds a fresh activation ID
-to navigation state so the same link can reveal its source again after dismissal.
-
-[`useAssistantCitationTarget`][target] loads earlier history (bounded at 20 pages or a repeated
-cursor, with a warning past that), expands a folded turn, and asks the virtual list to mount the
-source row. While positioning, the timeline disables initial end-scroll and scroll maintenance and
-keeps the cited row mounted until measured; the activation ID doubles as the list's data version
-so pinning rows recalculates a stationary Legend list without discarding measurements.
-
-[`AssistantCitationSource`][source] resolves the DOM range, smoothly scrolls to it, and pulses
-only that text through the CSS Highlight API: two 650 ms pulses driven by a registered opacity
-property, with the second settling into a held highlight before fading out. Navigation owns the
-highlight's start time and completion state: range repairs keep the original clock, remounting
-resumes only the remaining time, and an expired or dismissed highlight cannot revive. Reduced
-motion scrolls instantly and holds the highlight without pulsing. Browsers
-without the Highlight API temporarily select the range and remove only that owned selection.
-User navigation or `Escape` cancels pending positioning; missing messages or unmatched text
-produce warnings without changing the saved quote. The separate comment-editing highlight uses
-the same range-repair observer while its editor is open.
-
-Desktop shares the web implementation. Mobile's `ThreadFeed` uses `renderAssistantCitationsAsText`
-to show sent quotes as readable Markdown blockquotes with each user comment below its quote; it
-does not create citations or navigate to sources.
-
-## Provider input and titles
-
-[`ProviderService.sendTurn`][provider] calls `expandAssistantCitationsForProvider` before routing
-to any adapter; persisted messages keep their links. Each distinct serialized link becomes an
-inline `[assistant-quote-N]` marker, and one `<assistant_citations>` block carries JSON entries
-with an `id` and the complete `citation`. The block identifies `citation.text` as quoted reference
-material, not new instructions, and `citation.comment` as the user's comment about that quote.
-JSON encoding escapes `<`, `>`, and `&` so content cannot close the wrapper. The expansion is
-shared by all providers; there is no per-adapter citation handling or source lookup at send time.
-
-The 120,000-character provider input limit applies both before and after expansion:
-[`composerSubmission.ts`][submission] checks the larger length client-side and keeps an over-limit
-draft editable, and the server revalidates the expanded input before dispatch. Expansion does not
-apply to pending user-input answers.
-
-`assistantCitationsToPlainText` supplies readable input for title seeds, stash previews, and the
-server's title and branch-name helpers, which see the quoted text and comment rather than an
-encoded URI.
-
-[contract]: ../../packages/contracts/src/assistantCitations.ts
-[shared]: ../../packages/shared/src/assistantCitations.ts
-[selection]: ../../apps/web/src/lib/assistantTextSelection.ts
-[toolbar]: ../../apps/web/src/components/chat/AssistantSelectionToolbar.tsx
-[actions]: ../../apps/web/src/lib/selectionActions.ts
-[node]: ../../apps/web/src/components/ComposerCitationNode.tsx
-[chip]: ../../apps/web/src/components/chat/AssistantCitationChip.tsx
-[navigation]: ../../apps/web/src/lib/assistantCitationNavigation.ts
-[target]: ../../apps/web/src/components/chat/useAssistantCitationTarget.ts
-[source]: ../../apps/web/src/components/chat/AssistantCitationSource.tsx
-[provider]: ../../apps/server/src/provider/Layers/ProviderService.ts
-[submission]: ../../apps/web/src/components/chat/composerSubmission.ts
+Citations carry the selected excerpt and source identity in ordinary message text.
+Drafts, clipboard copies, stashes, and sent messages keep that representation
+without a separate citation store. The saved quote remains usable when its source
+disappears or changes. The [shared format](../../packages/shared/src/assistantCitations.ts) uses
+stable environment IDs without a browser origin, so moving between local, remote,
+and tunnel connections does not change a citation's identity.
+
+Source navigation is best effort. [Text selectors](../../apps/web/src/lib/assistantTextSelection.ts)
+refer to rendered text after whitespace normalization, measured in UTF-16 units.
+They cannot be applied to raw Markdown. The original excerpt keeps its whitespace;
+normalization is only for locating it. Repeated text needs an unambiguous context
+match, even if one occurrence still sits at the saved offsets. Guessing could
+highlight the wrong claim.
+
+Navigation owns the highlight's lifetime across virtual-row remounts. The source
+row must be fetched, unfolded, mounted, and measured before quote positioning
+takes over from normal timeline scrolling. Remounting must not revive a dismissed
+highlight. The [navigation hash](../../apps/web/src/lib/assistantCitationNavigation.ts)
+uses base64url because router normalization otherwise decodes whitespace and
+source IDs inside the citation URI.
+
+[ProviderService](../../apps/server/src/provider/Layers/ProviderService.ts) expands
+citations before dispatch to any provider adapter. It sends the saved excerpt
+without looking up the source, distinguishes quoted reference material from the
+user's comment, and leaves persisted messages in their original form. Input
+limits apply after expansion as well as before it. A draft that fits as encoded
+links can exceed the provider limit once expanded.
diff --git a/docs/internals/ci.md b/docs/internals/ci.md
deleted file mode 100644
index 67851009f5c2..000000000000
--- a/docs/internals/ci.md
+++ /dev/null
@@ -1,44 +0,0 @@
-# CI quality gates
-
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-[`.github/workflows/ci.yml`](../../.github/workflows/ci.yml) runs these quality gates on pull requests
-and pushes to `main`:
-
-- **Check**: `vp check` (format and lint; this repo sets `typeCheck: false` in its lint options),
-  then `vpr typecheck` for the workspace type check. The same job
-  builds the desktop pipeline (`vp run build:desktop`) and verifies the preload bundle exists and
-  uses only imports that Electron's sandbox can load. The verifier parses imports, then executes the
-  trusted artifact with controlled bridge stubs to confirm that its required APIs are callable.
-- **Test**: `vp run test` across the workspace.
-- **Mobile Native Static Analysis**: `vp run lint:mobile` on macOS, wrapping
-  `scripts/mobile-native-static-check.ts`. A cheap Linux **Mobile Native Changes** job gates it:
-  the macOS runner only boots when the diff touches `apps/mobile` Swift/Kotlin sources, the
-  SwiftLint/detekt/ktlint configuration, the `Brewfile`, the check script, the root `package.json`
-  that defines `lint:mobile`, or `ci.yml`. Otherwise the job is skipped, which GitHub reports as
-  success for the required check. Renames are matched on both their old and new path. The gate fails
-  open in every other case: if the changed-file list cannot be resolved, GitHub truncates it, or the
-  gate job itself fails, the lint runs.
-- **Release Smoke**: exercises release-only workflow steps through `scripts/release-smoke.ts`, so
-  release breakage surfaces on PRs rather than at tag time.
-
-[`.github/workflows/windows-tests.yml`](../../.github/workflows/windows-tests.yml) is a manual
-Windows lane (`workflow_dispatch` only) on a Blacksmith Windows 2025 runner. The suite does not
-pass on Windows yet, so it is not a required check; it exists so the work to get there can be
-iterated against a real Windows box without one on hand. Dispatch it with `gh workflow run
-windows-tests.yml --ref <branch>`, optionally with `-f package=<dir>` to run one workspace package
-and `-f files="<paths>"` to run specific test files inside it. Once it is green, fold it into
-`ci.yml`.
-
-`.github/workflows/release.yml` builds macOS (`arm64` and `x64`), Linux (`x64`), and Windows (`x64`)
-desktop artifacts from a single `v*.*.*` tag and publishes one GitHub release. It auto-enables
-signing only when platform credentials are present. macOS passkey builds additionally require
-`APPLE_TEAM_ID` and the `MACOS_PROVISIONING_PROFILE` secret; Windows uses Azure Trusted Signing.
-Without the core signing credentials, it still releases unsigned artifacts.
-
-Preflight shares pnpm's lockfile verification results with the desktop build jobs through a small
-artifact. This avoids repeating dependency checks, especially on Windows, without transferring the
-large registry metadata cache. pnpm checks the current lockfile and policy before it reuses a result.
-If the artifact is unavailable, installation runs the checks again.
-
-See [Release Checklist](../operations/release.md) for the full release/signing setup checklist.
diff --git a/docs/internals/connection-runtime.md b/docs/internals/connection-runtime.md
index e84d9ed4d703..21baaa4def06 100644
--- a/docs/internals/connection-runtime.md
+++ b/docs/internals/connection-runtime.md
@@ -1,211 +1,60 @@
-# Connection Runtime
-
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-The connection runtime is shared by web and mobile. It owns connectivity,
-authentication, retries, transport lifetime, cached environment data, and
-environment-scoped operations.
-
-Web and mobile mount this runtime once at the application root and compose it
-identically: `apps/web/src/connection/runtime.ts` and
-`apps/mobile/src/connection/runtime.ts` differ only in the platform layer they
-supply. There is no legacy connection owner or supported mixed mode.
-
-## Composition
-
-[`connection/layer.ts`][layer] assembles the runtime:
-
-- `ConnectionResolver` ([resolver.ts][resolver]) resolves a catalog entry into a
-  prepared, authenticated endpoint for primary, bearer, relay, or SSH targets.
-- `ConnectionDriver` ([driver.ts][driver]) prepares through the resolver, opens
-  one RPC session, and reports `preparing`, `opening`, and `synchronizing`.
-- `RpcSessionFactory` ([rpc/session.ts][session]) performs one transport
-  attempt. It does not retry. `RpcSession` is the interface it returns,
-  exposing `client`, `initialConfig`, `ready`, `probe`, and `closed`.
-- `EnvironmentRegistry` ([registry.ts][registry]) owns the catalog and the
-  per-environment scopes.
-- `ConnectionOnboarding` and `RelayEnvironmentDiscovery` sit alongside the
-  registry. Startup calls `EnvironmentRegistry.start` and streams platform
-  registrations into `reconcilePlatform`.
-
-The registry creates one environment-scoped supervisor per environment.
-`acquireSupervisor` serializes access per environment, reuses an existing
-supervisor when the catalog entry is unchanged, and closes and recreates the
-scope when it changed. `createServiceScope` builds an `EnvironmentSupervisor`
-bound to a closeable scope and connects it; `run` and `runStream` execute caller
-effects with that supervisor provided.
-
-`EnvironmentSupervisor` owns desired state, retry scheduling, and the active
-session scope. React components do not create connections, transports, retry
-loops, or RPC clients.
-
-## Connection State
-
-The supervisor is the only retry owner.
-
-1. A persisted or platform registration marks an environment as desired.
-2. If the device is offline, the supervisor releases the active session and
-   waits for a signal without consuming retry attempts or running a timer.
-3. When online, it asks the driver for one prepared connection and one RPC
-   session.
-4. Transient failures retry forever with exponential backoff capped at 16
-   seconds (`RETRY_DELAYS_MS`). A connection stable for 30 seconds resets
-   accumulated backoff.
-5. Authentication or configuration failures remain blocked until an external
-   wakeup changes the relevant input.
-6. An involuntary session close keeps the registration and cache, then retries.
-7. Explicit removal closes the session and deletes the registration,
-   credentials, shell cache, and thread cache.
-
-### Wakeups
-
-Wakeup handling differs by phase, in [supervisor.ts][supervisor]:
-
-- During establishment, `waitForEstablishmentInterrupt` consumes and **ignores**
-  plain application activation. Restarting an in-flight attempt because the app
-  came to the foreground would only delay it. The exception is
-  `application-active-reconnect`, which mobile emits after a meaningful
-  background suspension; it interrupts establishment and resets the retry
-  ladder, because the OS may have silently killed the socket underneath the
-  attempt.
-- Credential changes interrupt establishment only for relay targets, where a new
-  credential changes what is being established.
-- Explicit disconnect, explicit retry, and going offline interrupt establishment
-  in every case.
-- While waiting out backoff, application activation resets the retry ladder so a
-  foregrounded app reconnects immediately instead of serving the remaining
-  delay.
-- Once connected, `monitorConnectedLease` handles plain activation by probing
-  the existing session (`lease.session.probe`, with a shorter timeout for
-  mobile's `application-active-probe`) rather than reconnecting; a healthy
-  session survives foregrounding. `application-active-reconnect` skips the probe
-  and replaces the lease outright.
-
-The UI derives `available`, `offline`, `connecting`, `reconnecting`,
-`connected`, and `error` from supervisor state plus explicit data-sync state.
-It does not infer connection health from cached data or the existence of a
-transport object. An environment becomes `connected` after the socket opens and
-the initial config RPC succeeds, proving that the server is responsive. Shell
-and thread synchronization are independent data states. A healthy RPC transport
-with a failed shell subscription is shown as connected with a synchronization
-error, not as a reconnect that is not actually scheduled.
-
-## Data Boundary
-
-Finite requests, durable subscriptions, and commands are separate APIs:
-
-- Query atoms revalidate when the RPC generation changes.
-- Subscription atoms switch to replacement sessions.
-- Subscription failure handling in [rpc/client.ts][client] distinguishes two
-  cases. A transport failure (`isTransportFailure`: every failure is an RPC
-  client error) ends the inner subscription without resubscribing, so the outer
-  stream waits for the supervisor to supply a replacement session. A handled
-  domain failure runs `onExpectedFailure` and, when
-  `retryExpectedFailureAfter` is set, sleeps and resubscribes on the **same**
-  session. A healthy transport is never torn down for a domain failure.
-- Mutations resolve the current environment runtime at execution time.
-- Shell and thread snapshots are available while offline.
-- Sync status is explicit and independent per domain. Shell status is `empty`,
-  `cached`, `synchronizing`, or `live`, with a separate `error` field; there is
-  no `failed` status. Thread status adds `deleted`.
-- Cached shell and thread projections are never allowed to overwrite newer live
-  data during a fast reconnect.
-- Domain atom factories route effects through the environment registry and
-  resolve the current scoped service at execution time. Project and thread
-  commands are Atom factories under `src/state`
-  (`createProjectEnvironmentAtoms`, `createThreadEnvironmentAtoms`), as are the
-  shell and thread state factories (`createEnvironmentShellAtoms`,
-  `createEnvironmentThreadStateAtoms`).
-- Web and mobile own their Atom runtimes, React hooks, and feature composition.
-
-The Promise bridge exists only at the React/Atom boundary. Runtime and business
-logic remain Effect-native.
-
-## Platform Layers
-
-Web and mobile provide:
-
-- network status and network-change streams;
-- application lifecycle wakeups;
-- cloud session credentials;
-- device identity;
-- platform registrations;
-- persistent catalog, credential, shell, and thread stores;
-- HTTP, crypto, and telemetry layers.
-
-Platform layers adapt operating-system capabilities. They do not implement
-connection policy. `EnvironmentOwnedDataCleanup` is part of this contract: on
-removal the registry clears its cache and calls the platform implementation, so
-web clears composer drafts and mobile clears drafts plus the thread outbox.
-
-Mobile cloud sign-out first saves relay drafts and queued messages in the local
-composer store under the owning account. These saved copies retain attachment
-files during cleanup and remain outside the active composer and upload queue.
-Signing back into that account restores them before relay credentials activate.
-Directly paired environments keep their drafts and outbox when cloud sign-out runs.
-
-Mobile composer attachments upload over HTTP while their environment is connected,
-with at most three concurrent transfers. Drafts retain local image data or an owned
-file URI alongside the pending upload ID. Sending verifies and reuses that ID, or
-uploads the local bytes again if it expired. Disconnecting cancels active transfers
-without discarding drafts; reconnecting resumes preparation. Older servers without
-attachment-upload support continue to receive inline images.
-
-## Source Boundaries
-
-Applications must import explicit package subpaths; the package intentionally
-has no root export. The subpaths are documented in
-[packages/client-runtime/README.md](../../packages/client-runtime/README.md),
-with the `exports` map in that package's `package.json` as the authoritative
-list. Files that are not exported are implementation details.
-
-## Application Boundary
-
-The application root mounts the shared connection layer, creates its own Atom
-runtime, and selects the domain atom factories required by that platform. Web
-and mobile may expose different hooks and features without changing connection
-ownership.
-
-Application code must not construct RPC clients, retry loops, or raw
-orchestration commands. Persistence paths belong to the platform registration
-and cache stores, with explicit migration or invalidation policy.
-
-### Thread detail ownership
-
-Mounted detail consumers share one live thread subscription. The subscription
-ends when the last consumer leaves. Hidden routes that remain mounted still
-count as consumers.
-
-A separate registry-local atom retains the last thread state and replay cursor
-for five idle minutes. A warm mount renders that state and resumes the stream
-without another snapshot download. The cache holds completed state and cursor
-updates together. It retains pagination data but clears canceled loading state.
-An ownership token prevents an old scope from replacing its successor's cache.
-Closing a thread skips snapshots that were already saved. Changed snapshots and
-failed background writes still get a final save attempt.
-
-## Verification
-
-Core state-machine tests use `@effect/vitest` and deterministic service layers.
-Required coverage includes:
-
-- offline startup and online wakeup;
-- forever retry with the 16-second cap;
-- explicit retry interrupting backoff;
-- authentication wakeups;
-- involuntary close and reconnect;
-- explicit removal clearing all owned state;
-- relay token reuse and refresh;
-- progressive relay discovery;
-- shell and thread cache hydration;
-- thread stream shutdown, warm resume, and snapshot expiry;
-- durable subscriptions switching sessions;
-- command metadata and idempotent queued-command metadata.
-
-[layer]: ../../packages/client-runtime/src/connection/layer.ts
-[resolver]: ../../packages/client-runtime/src/connection/resolver.ts
-[driver]: ../../packages/client-runtime/src/connection/driver.ts
-[registry]: ../../packages/client-runtime/src/connection/registry.ts
-[supervisor]: ../../packages/client-runtime/src/connection/supervisor.ts
-[session]: ../../packages/client-runtime/src/rpc/session.ts
-[client]: ../../packages/client-runtime/src/rpc/client.ts
+# Connection runtime
+
+Web, the desktop renderer, and mobile share one connection owner per environment
+in `packages/client-runtime`. Platform code supplies storage, credentials, network
+signals, and application lifecycle events. React views consume the runtime.
+Keeping retries and session lifetime here prevents competing reconnect loops when
+several views need the same environment.
+
+## One retry owner
+
+The [supervisor](../../packages/client-runtime/src/connection/supervisor.ts) owns
+retry policy; resolving an endpoint and opening an RPC session are single
+attempts. Transient failures retry with capped backoff. Offline states and
+authentication failures wait for a wakeup instead of spending attempts on
+unchanged conditions.
+
+Foregrounding needs different treatment depending on the connection's state.
+It wakes a retry immediately, leaves an ordinary in-flight attempt alone, and
+probes an established session before replacing it. A long mobile background
+suspension forces replacement because the OS can kill a socket without reporting
+closure. Treating every foreground event as a reconnect delays healthy attempts;
+treating every resume as harmless leaves suspended sockets stuck.
+
+The [registry](../../packages/client-runtime/src/connection/registry.ts) scopes
+connections by environment. An involuntary disconnect retains the registration
+and cached data. Explicit removal closes the scope and clears credentials,
+projections, and platform-owned state such as drafts. Cloud-account changes apply
+to relay registrations; they must not discard directly paired environments.
+
+## Transport health and data freshness are separate
+
+A socket opening is insufficient evidence that the environment is usable. The
+[RPC session](../../packages/client-runtime/src/rpc/session.ts) waits for the
+initial server configuration before becoming ready. Shell and thread data then
+have their own synchronization state. A failed shell subscription can coexist
+with a healthy connection; labeling that state "reconnecting" promises a
+transport retry that will never happen.
+
+Cached projections remain readable offline. They must neither imply a live
+connection nor overwrite newer live data during a reconnect. Loading and
+resuming snapshots belongs to the shared state services, so every view agrees
+on which data is current.
+
+[Thread detail](../../packages/client-runtime/src/state/threads.ts) separates
+subscription lifetime from cache lifetime. Mounted consumers share one live
+stream, which stops when the last consumer unmounts; hidden mounted routes still
+count. A registry-local cache retains state and its replay cursor for five idle
+minutes so back navigation can resume without another snapshot download.
+
+Retain state and cursor together only after an update finishes. Cancellation must
+not advance the cached cursor beyond the applied data, and an old scope must not
+overwrite its successor's cache. Preserve pagination data on reuse, but clear
+canceled loading state.
+
+The [RPC boundary](../../packages/client-runtime/src/rpc/client.ts) resolves
+requests against the current session at execution time. Durable subscriptions
+follow replacement sessions. After a transport failure they wait for the
+supervisor; an expected domain failure may resubscribe on the same healthy
+session. Reconnection does not automatically replay mutations, whose retry and
+idempotency rules belong to the operation.
diff --git a/docs/internals/environment-auth.md b/docs/internals/environment-auth.md
index 068fcfa68a90..dc43b4d45c03 100644
--- a/docs/internals/environment-auth.md
+++ b/docs/internals/environment-auth.md
@@ -1,197 +1,60 @@
-# Environment Authentication Profile
-
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-The environment server and the relay use separate credentials, issuers, and trust
-boundaries. They intentionally use a similar OAuth-shaped model so that permission
-checks and token exchange behavior can be audited against established concepts.
-
-## Authorization Model
-
-Environment authorization is capability-based. A session carries zero or more
-OAuth-style scope strings:
-
-| Scope                   | Permission                                                               |
-| ----------------------- | ------------------------------------------------------------------------ |
-| `orchestration:read`    | Read snapshots, status, events, configuration, and filesystem/VCS state. |
-| `orchestration:operate` | Dispatch user operations and mutate environment-side workspace state.    |
-| `terminal:operate`      | Create, attach, input, resize, clear, restart, and terminate terminals.  |
-| `review:write`          | Read review diff previews used to compose review feedback.               |
-| `access:read`           | Inspect pairing links and client sessions.                               |
-| `access:write`          | Create or revoke pairing links and client sessions.                      |
-| `relay:read`            | Inspect managed relay connectivity.                                      |
-| `relay:write`           | Link, configure, or unlink managed relay connectivity.                   |
-
-Pairing-link lists and access-stream snapshots and updates contain metadata only.
-The raw credential is returned only by the creation request, after the server checks
-`access:write` and the delegated scopes. Web and desktop clients keep that response
-in memory for sharing. They do not recover credentials from access read models.
-
-Ordinary pairing links grant the four client-operation scopes and read access to
-managed relay connectivity:
-`orchestration:read orchestration:operate terminal:operate review:write relay:read`.
-The desktop bootstrap credential and command-line administrative bootstrap
-credentials additionally grant `access:read access:write relay:write`.
-
-## Host file access
-
-Clients with `orchestration:read` can read files anywhere the environment's server account can
-read, following the environment-wide authorization model rather than introducing per-project
-filesystem permissions. `projects.readFile` accepts an absolute path and returns the text of that
-host file; only workspace-relative paths pass its root check, and `projects.writeFile` never
-accepts an absolute path. Clients use this to show files an agent wrote outside the workspace, such
-as a report in a temp directory, read-only.
-
-## Media preview access
-
-Clients with `orchestration:read` can request a `media-file` URL through `assets.createUrl` for
-supported images, videos, HTML, and PDF files anywhere the environment's server account can read.
-A thread ID supplies the workspace for relative paths; absolute paths refer to the environment
-host, not the client.
-
-[`AssetAccess.ts`](../../apps/server/src/assets/AssetAccess.ts) resolves symlinks, requires a regular
-file, and validates the resolved file's literal extension. It opens the file and signs its canonical
-path and device/inode identity for one hour. The token grants access to that exact file, not adjacent
-files or its containing directory. Serving rechecks the canonical path, media type, and opened
-descriptor's identity, then streams full or partial responses from that descriptor. Replacing a
-file atomically requires a freshly signed URL; editing it in place does not. Because the token names
-one file, an HTML document served this way cannot load sibling assets; the directory-scoped
-`workspace-file` resource remains the route for HTML inside the workspace. Uploaded attachments keep
-their separate asset resource.
-
-Signed asset URLs are bearer credentials. Anyone who obtains a URL and can reach the environment
-can fetch that file until it expires. Clients should copy the authored reference, not the temporary
-URL. Responses use `nosniff`; SVG responses retain their restrictive sandbox policy. Video reads
-support byte ranges so playback does not require a complete download first.
-
-Host videos can change in place, so their responses use `private, no-store` and omit `ETag`
-and `Last-Modified`. File metadata cannot prove byte-for-byte identity for `If-Range`; advertising
-those validators would encourage native players to send conditional seeks that require a full
-response. Ordinary range requests receive partial responses. An explicitly supplied `If-Range`
-still falls back to a full response because no strong validator is available. Host image previews
-keep their private cache policy and weak metadata validators.
-
-The server serves media in place without importing it into attachment storage. Deletion makes
-future server reads fail, though an already loaded client or its cache can retain bytes. Native
-viewers may use temporary client-side files for display or explicit sharing; those are not durable
-environment copies.
-
-## Authentication Flows
-
-### Browser Session
-
-`POST /api/auth/browser-session` consumes a one-time bootstrap credential and creates a
-browser session cookie. The cookie is an HTTP transport adapter for the same
-scoped session model; the response never exposes the session secret to browser
-JavaScript.
-
-### Bearer Access Token
-
-Non-browser clients use `POST /oauth/token` with an
-`application/x-www-form-urlencoded` body:
-
-```text
-grant_type=urn:ietf:params:oauth:grant-type:token-exchange
-subject_token=<bootstrap credential>
-subject_token_type=urn:t3:params:oauth:token-type:environment-bootstrap
-requested_token_type=urn:ietf:params:oauth:token-type:access_token
-scope=orchestration:read orchestration:operate terminal:operate review:write relay:read
-```
-
-Clients may additionally submit `client_label`, `client_device_type`, and
-`client_os` extension parameters so the authorized-clients UI can identify the
-device that established the session. These are presentation hints only; the
-environment derives transport metadata such as IP address and user agent from
-the request and does not use these fields for authorization.
-
-The response has the token-exchange shape:
-
-```json
-{
-  "access_token": "<opaque session token>",
-  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
-  "token_type": "Bearer",
-  "expires_in": 2592000,
-  "scope": "orchestration:read orchestration:operate terminal:operate review:write relay:read"
-}
-```
-
-Sessions issued from a plain bearer exchange use the store's
-`DEFAULT_SESSION_TTL` of 30 days. The shorter one-hour `expires_in: 3600` applies
-only to DPoP-bound exchanges, where the token is additionally constrained by a
-proof key. See `SessionStore.ts` and `EnvironmentAuth.ts`.
-
-The reusable `desktop-bootstrap` grant replaces active sessions with the same
-subject and authentication method. Revocation and insertion share one database
-transaction, so a failed insertion preserves the previous credential. This also
-removes stale local desktop entries from earlier launches. Browser-cookie sessions
-and sessions issued through pairing links are not replaced.
-
-Requested scopes must be a subset of the one-time bootstrap credential grant.
-An ordinary paired client therefore cannot exchange its grant for
-`access:read`, `access:write`, or `relay:write`.
-
-### DPoP-Bound Access Token
-
-The same `/oauth/token` exchange supports proof-of-possession tokens. A client
-that sends a `DPoP` header has its proof verified by `verifyRequestDpopProof`;
-the resulting JWK thumbprint is stored on the session, which is then issued with
-method `dpop-access-token` and a one-hour TTL instead of the bearer default. An
-invalid proof gets a DPoP challenge header and a credential error rather than a
-bearer token. Newer servers include a safe `dpopFailureReason` category in that
-error. When an older server omits the category, clients mention clock skew as
-one possible cause rather than presenting it as confirmed.
-
-`dpop-access-token` is advertised alongside `browser-session-cookie` and
-`bearer-access-token` in the descriptor's `sessionMethods`
-(`EnvironmentAuthPolicy.ts`), so clients can discover support rather than
-assume it. Relay-brokered clients use this mode so that a leaked token cannot be
-replayed without the corresponding key.
-
-### WebSocket Ticket
-
-`POST /api/auth/websocket-ticket` accepts any authenticated session and returns
-a short-lived, single-purpose WebSocket ticket, issued through
-`EnvironmentAuth.issueWebSocketTicket` with a five-minute default TTL. The
-client presents its bearer or DPoP credential in headers to get the ticket, then
-appends only that ticket to the socket URL as `wsTicket`. This keeps long-lived
-tokens and browser cookies out of WebSocket URLs while letting the handshake
-authenticate.
-
-The ticket carries its session's scopes; each RPC method then enforces
-`orchestration:read`, `orchestration:operate`, `terminal:operate`,
-`review:write`, `relay:write`, or `access:read` as appropriate, through
-`RPC_REQUIRED_SCOPES` in `apps/server/src/auth/RpcAuthorization.ts`. Review feedback submission currently dispatches
-an orchestration operation, so clients performing it also need
-`orchestration:operate`. Creating a ticket is not authorization to call every
-RPC method.
-
-## Standards Alignment
-
-- Bearer access tokens are used through the `Authorization: Bearer` scheme from
-  RFC 6750.
-- The token endpoint profiles the request and response vocabulary from OAuth 2.0
-  Token Exchange (RFC 8693), including `subject_token`, `requested_token_type`,
-  `access_token`, `issued_token_type`, and `token_type`.
-- Scope values follow the OAuth 2.0 scope model from RFC 6749: space-delimited,
-  unordered capabilities with subset checking during exchange.
-
-This is intentionally not a general-purpose OAuth authorization server. The
-environment bootstrap token type is private, the bootstrap cookie and WebSocket
-connection-token routes are product-specific adapters, and the API returns its
-typed `HttpApi` errors rather than implementing every OAuth error response
-surface.
-
-## Upgrade Behavior
-
-Migration `031_AuthAuthorizationScopes` is a hard cutover from role-bearing auth
-records to scoped records. It deletes existing pairing links and sessions while
-leaving non-authentication environment state unchanged. Upgraded clients must
-pair again; old `owner` or `client` credentials are never silently mapped to new
-capabilities.
-
-## Relay Boundary
-
-Relay-managed tunnels use their own tokens and keys. The relay can reuse scope
-parsing and token-exchange conventions, but an environment access token is not a
-relay token and cannot be presented to the relay.
+# Environment authentication
+
+The environment issues its own sessions and enforces their capabilities. Cloud
+identity and relay credentials belong to a separate trust boundary, described in
+[T3 Connect](./t3-connect.md). A relay token is never an environment login.
+
+## Authority survives transport changes
+
+Pairing delegates a set of scopes. Exchanging a bootstrap credential can narrow
+that grant but cannot widen it. Ordinary pairing does not grant access-management
+or relay-management authority. Creating another pairing link requires both
+`access:write` and every scope being delegated. The
+[auth handlers](../../apps/server/src/auth/http.ts) enforce this at issuance;
+client labels and device metadata have no authorization role.
+
+The access read model contains pairing metadata, never recoverable pairing
+secrets. Only the creation response returns the raw credential. Otherwise read
+access to the connections list would become a way to acquire another client's
+authority.
+
+Browser cookies, bearer tokens, and DPoP tokens adapt the same scoped session
+model. DPoP binds a token to a client's proof key; an invalid proof must fail
+rather than fall back to bearer authentication. The OAuth token-exchange
+vocabulary gives these grants a familiar meaning, but the environment does not
+implement a general-purpose OAuth authorization server.
+
+Bearer and DPoP clients obtain short-lived WebSocket tickets through authenticated
+HTTP so long-lived tokens stay out of socket URLs. Browser sessions can
+authenticate the upgrade with their cookie. A successful handshake grants no
+extra authority: [every RPC declares a required
+scope](../../apps/server/src/auth/RpcAuthorization.ts).
+
+Desktop restarts forget the previous local bearer token, so its reusable
+bootstrap grant replaces earlier sessions for the same subject and method.
+Revocation and insertion share a [database
+transaction](../../apps/server/src/persistence/AuthSessions.ts); a failed
+replacement must leave the old credential usable. Pairing and browser sessions
+do not follow this replacement rule.
+
+## The environment is the filesystem boundary
+
+Projects are organizational boundaries, not filesystem sandboxes.
+`orchestration:read` permits reading files the server account can read, including
+absolute paths outside a project. This lets clients display artifacts that an
+agent writes in a temporary directory. Relative paths and writes still follow
+the [workspace path rules](../../apps/server/src/workspace/WorkspaceFileSystem.ts).
+
+Signed asset URLs are bearer credentials. A URL for media on the host grants
+access to one canonical file and its device/inode identity, not its containing directory.
+[Asset access](../../apps/server/src/assets/AssetAccess.ts) rechecks the opened
+file's identity when serving it, so atomic replacement requires a new URL while
+editing the same file in place does not. An HTML file authorized this way cannot
+load sibling assets; directory-scoped workspace previews are a separate grant.
+Clients should share the authored file reference so they do not disclose the
+temporary URL's credential.
+
+Host videos can change in place. Their [HTTP
+responses](../../apps/server/src/http.ts) omit cache validators because file
+metadata cannot prove byte-for-byte identity for `If-Range`. Adding weak
+validators would turn native-player seeks into full downloads.
diff --git a/docs/internals/glossary.md b/docs/internals/glossary.md
index b69c78db3298..f7cb61259c0e 100644
--- a/docs/internals/glossary.md
+++ b/docs/internals/glossary.md
@@ -1,211 +1,47 @@
 # Glossary
 
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-This is a living glossary for T3 Code. It explains what common terms mean in this codebase.
-
-## Table of contents
-
-- [Project and workspace](#project-and-workspace)
-- [Thread timeline](#thread-timeline)
-- [Orchestration](#orchestration)
-- [Provider runtime](#provider-runtime)
-- [Checkpointing](#checkpointing)
-- [Appearance](#appearance)
-
-## Concepts
-
-### Project and workspace
-
-#### Project
-
-The top-level workspace record in the app. In [the orchestration contracts][1], a project has a `workspaceRoot` and a title. It does not contain threads: `OrchestrationProject` and `OrchestrationThread` are separate arrays on the read model, and a project can have zero threads. See [workspace-layout.md][2].
-
-#### Workspace root
-
-The root filesystem path for a project. In [the orchestration model][1], it is the base directory for branches and optional worktrees. See [workspace-layout.md][2].
-
-#### Worktree
-
-A Git worktree used as an isolated workspace for a thread. If a thread has a `worktreePath` in [the contracts][1], it runs there instead of in the main working tree. Git operations live behind the VCS driver contract in `apps/server/src/vcs/VcsDriver.ts`, implemented by [GitVcsDriverCore.ts][3].
-
-### Thread timeline
-
-#### Thread
-
-The main durable unit of conversation and workspace history. In [the orchestration contracts][1], a thread holds messages, activities, checkpoints, and session-related state. See [projector.ts][4].
-
-#### Turn
-
-A single user-to-assistant work cycle inside a thread. It starts with user input and ends when the session leaves `running` status, which [projector.ts][4] treats as the authoritative completion signal (`settledTurnStateForSessionStatus`). Checkpoint and diff work may settle afterward without changing when the turn ended. See [the contracts][1] and [ProviderRuntimeIngestion.ts][5].
-
-#### Activity
-
-A user-visible log item attached to a thread. In [the contracts][1], activities cover important non-message events like approvals, tool actions, and failures. They are projected into thread state in [projector.ts][4].
-
-### Orchestration
-
-Orchestration is the server-side domain layer that turns runtime activity into stable app state. The main entry point is [OrchestrationEngine.ts][7], with core logic in [decider.ts][8] and [projector.ts][4].
-
-#### Aggregate
-
-The domain object a command or event belongs to. In [the contracts][1], that is usually `project` or `thread`. See [decider.ts][8].
-
-#### Command
-
-A typed request to change domain state. In [the contracts][1], commands are validated in [commandInvariants.ts][9] and turned into events by [decider.ts][8].
-Examples include `thread.create`, `thread.turn.start`, and `thread.checkpoint.revert`.
-
-#### Domain Event
-
-A persisted fact that something already happened. In [the contracts][1], events are the source of truth, and [projector.ts][4] shows how they are applied.
-Examples include `thread.created`, `thread.message-sent`, and `thread.turn-diff-completed`.
-
-#### Decider
-
-The pure orchestration logic that turns commands plus current state into events. The core implementation is in [decider.ts][8], with preconditions in [commandInvariants.ts][9].
-
-#### Projection
-
-A read-optimized view derived from events. See [projector.ts][4], [ProjectionPipeline.ts][11], and [ProjectionSnapshotQuery.ts][10].
-
-#### Projector
-
-The logic that applies domain events to the read model or projection tables. See [projector.ts][4] and [ProjectionPipeline.ts][11].
-
-#### Read model
-
-The current materialized view of orchestration state. In [the contracts][1], it holds projects, threads, messages, activities, checkpoints, and session state. See [ProjectionSnapshotQuery.ts][10] and [OrchestrationEngine.ts][7].
-
-#### Reactor
-
-A side-effecting service that handles follow-up work after events or runtime signals. Examples include [CheckpointReactor.ts][6], [ProviderCommandReactor.ts][12], and [ProviderRuntimeIngestion.ts][5].
-
-#### Receipt
-
-A typed signal emitted when an async milestone completes, such as `checkpoint.baseline.captured`, `checkpoint.diff.finalized`, or `turn.processing.quiesced`. Receipts are a test-only mechanism: the production `RuntimeReceiptBusLive` publish is a no-op and only the test layer is PubSub-backed. Do not build production behavior on them. See [RuntimeReceiptBus.ts][13] and [CheckpointReactor.ts][6].
-
-#### Quiesced
-
-"Quiesced" means a turn has gone quiet and stable: follow-up work such as [CheckpointReactor.ts][6] has settled. It appears in [the receipt schema][13], so in practice it is something tests wait on rather than a production signal.
-
-### Provider runtime
-
-The live backend agent implementation and its event stream. The main service is [ProviderService.ts][14], the adapter contract is [ProviderAdapter.ts][15], and the overview is in [providers.md][16].
-
-#### Provider
-
-The backend agent runtime that actually performs work. Six drivers ship built in: Codex, Claude, Cursor, Grok, OpenCode, and Antigravity. See [ProviderService.ts][14], [ProviderAdapter.ts][15], and [CodexAdapter.ts][17] as a representative adapter.
-
-#### Session
-
-The live provider-backed runtime attached to a thread. Session shape is in [the orchestration contracts][1], and lifecycle is managed in [ProviderService.ts][14].
-
-#### Runtime mode
-
-The safety/access mode for a thread or session. [The contracts][1] define four values: `approval-required`, `auto-accept-edits`, `auto`, and `full-access`. See [permission modes][18].
-
-#### Interaction mode
-
-The agent interaction style for a thread. In [the contracts][1], the values are `default` and `plan`.
-
-#### Assistant delivery mode
-
-Controls how assistant text reaches the thread timeline. In [the contracts][1], `streaming` updates incrementally and `buffered` accumulates text. Buffered delivery is not held until the turn completes: it spills once accumulated text would exceed 24,000 characters, and flushes at approval and user-input boundaries. See [ProviderRuntimeIngestion.ts][5].
-
-#### Snapshot
-
-A point-in-time view of state. The word is used in multiple layers, including orchestration, provider, and checkpointing. See [ProjectionSnapshotQuery.ts][10], [ProviderAdapter.ts][15], and [CheckpointStore.ts][19].
-
-#### Usage limits
-
-The rolling subscription quota windows a provider reports for its signed-in account, such as Claude's five-hour and weekly windows or Codex's primary and secondary allowances. Each driver decides in its own `checkProvider` whether it has any and returns them on the snapshot as `usageLimits`; drivers with no notion of subscription usage leave the field absent. Adapters that receive rate-limit telemetry during a turn normalise it into a `ProviderUsageLimitsUpdate` at the boundary, and `ProviderUsageLimitsIngestion` folds it onto the owning instance's snapshot through `ServerProviderShape.applyUsageLimits`, so no central service needs to know a driver kind. See [providerUsageLimits.ts](../../packages/contracts/src/providerUsageLimits.ts) and [makeManagedServerProvider.ts](../../apps/server/src/provider/makeManagedServerProvider.ts).
-
-#### Usage limit source
-
-A read-only quota feed outside this environment's provider CLIs, configured under `settings.usageLimitSources`. The only kind today is a CLIProxyAPI hub, whose `quota-scheduler/status` reports the windows of every pooled account. `UsageLimitSources` polls each source on the provider health interval and publishes `UsageLimitSourceSnapshot`s over the config stream as `usageLimitSourcesUpdated`, gated by a client capability flag the way environment themes are. The management key round-trips through the secret store with a redaction marker on disk. See [UsageLimitSources.ts](../../apps/server/src/usage/UsageLimitSources.ts).
-
-#### Model manifest
-
-The per-driver list of current model slugs that decides which models land in the model picker's legacy section. Bundled at `apps/server/src/provider/model-manifest.json` and refreshed at runtime from the same file on `main`, so classification updates ship as commits instead of releases. See the [provider architecture][16] model manifest section.
-
-### Checkpointing
-
-Checkpointing captures workspace state over time so the app can diff turns and restore earlier points. The main pieces are [CheckpointStore.ts][19], [CheckpointDiffQuery.ts][20], and [CheckpointReactor.ts][6].
-
-#### Checkpoint
-
-A saved snapshot of a thread workspace at a particular turn. In practice it is a hidden Git ref in [CheckpointStore.ts][19] plus a projected summary from [ProjectionCheckpoints.ts][21]. Capture and lifecycle work happen in [CheckpointReactor.ts][6].
-
-#### Checkpoint ref
-
-The durable identifier for a filesystem checkpoint, stored as a Git ref. It is typed in [the contracts][1], constructed in [Utils.ts][22], and used by [CheckpointStore.ts][19].
-
-#### Checkpoint baseline
-
-The starting checkpoint for diffing a thread timeline. This flow is surfaced through [RuntimeReceiptBus.ts][13], coordinated in [CheckpointReactor.ts][6], and supported by [Utils.ts][22].
-
-#### Checkpoint diff
-
-The difference between two checkpoints. [CheckpointDiffQuery.ts][20] reads full patches on demand. [CheckpointReactor.ts][6] uses NUL-delimited Git numstat output for automatic file summaries, parsed by [Diffs.ts][23].
-
-#### Turn diff
-
-The file patch and changed-file summary for one turn. It is usually computed in [CheckpointDiffQuery.ts][20], represented in [the contracts][1], and recorded into thread state by [projector.ts][4].
-
-### Appearance
-
-#### Environment theme
-
-A theme an environment's machine publishes for clients to follow, one file per theme under `themes/` in that environment's state directory; the filename is the theme id. [environmentTheme.ts][25] watches the directory and streams the set over `subscribeServerConfig`; clients render each as a library card, generating a full palette when the file carries seed colors and using the palette directly when it is a standard exported theme file. A desktop that retints its apps when the system theme changes rewrites its file, so T3 Code follows along without a restart. See [environment-theme.md][26].
-
-#### Default theme
-
-The environment's theme, held in its `settings.json` as `defaultTheme` (with `defaultThemeSetAt`
-as the set-generation) and set with `t3 theme set <id>`. Web and desktop clients apply each set
-once — live when connected, on the next connect otherwise — so setting it switches them, while a
-theme a user picks in Settings afterwards sticks until the next set; mobile keeps its own
-appearance settings. Naming a published [environment theme](#environment-theme) is how a desktop
-ships T3 Code already matching it.
-
-## Practical Shortcuts
-
-- If you see `requested`, think "intent recorded".
-- If you see `completed`, think "result applied".
-- If you see `receipt`, think "async milestone signal, for tests".
-- If you see `checkpoint`, think "workspace snapshot for diff/restore".
-- If you see `quiesced`, think "all relevant follow-up work has gone idle".
-
-## Related Docs
-
-- [Architecture overview][24]
-- [Provider architecture][16]
-- [Permission modes][18]
-- [Workspace layout][2]
-
-[1]: ../../packages/contracts/src/orchestration.ts
-[2]: ./workspace-layout.md
-[3]: ../../apps/server/src/vcs/GitVcsDriverCore.ts
-[4]: ../../apps/server/src/orchestration/projector.ts
-[5]: ../../apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
-[6]: ../../apps/server/src/orchestration/Layers/CheckpointReactor.ts
-[7]: ../../apps/server/src/orchestration/Layers/OrchestrationEngine.ts
-[8]: ../../apps/server/src/orchestration/decider.ts
-[9]: ../../apps/server/src/orchestration/commandInvariants.ts
-[10]: ../../apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts
-[11]: ../../apps/server/src/orchestration/Layers/ProjectionPipeline.ts
-[12]: ../../apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
-[13]: ../../apps/server/src/orchestration/Services/RuntimeReceiptBus.ts
-[14]: ../../apps/server/src/provider/Layers/ProviderService.ts
-[15]: ../../apps/server/src/provider/Services/ProviderAdapter.ts
-[16]: ./providers.md
-[17]: ../../apps/server/src/provider/Layers/CodexAdapter.ts
-[18]: ../user/permission-modes.md
-[19]: ../../apps/server/src/checkpointing/CheckpointStore.ts
-[20]: ../../apps/server/src/checkpointing/CheckpointDiffQuery.ts
-[21]: ../../apps/server/src/persistence/Services/ProjectionCheckpoints.ts
-[22]: ../../apps/server/src/checkpointing/Utils.ts
-[23]: ../../apps/server/src/checkpointing/Diffs.ts
-[24]: ./overview.md
-[25]: ../../apps/server/src/environmentTheme.ts
-[26]: ../user/environment-theme.md
+Terms whose meaning matters across T3 Code. Architecture and lifecycle constraints belong in the
+[overview](./overview.md), not in these definitions.
+
+## Workspace and conversation
+
+| Term           | Meaning                                                                                           |
+| -------------- | ------------------------------------------------------------------------------------------------- |
+| Environment    | One running server and the machine, credentials, workspace access, and state it owns.             |
+| Client         | A web, desktop, or mobile UI connected to an environment. The desktop app can also host a server. |
+| Project        | An environment-local workspace record rooted at a directory.                                      |
+| Workspace root | The project's base filesystem directory on the environment.                                       |
+| Worktree       | A separate Git checkout a thread can use instead of the project's main checkout.                  |
+| Thread         | The durable conversation and work history for a project. It survives provider process exits.      |
+| Turn           | One user-to-agent work cycle. Provider work can finish before checkpoint and diff work settles.   |
+| Activity       | A non-message timeline item, such as a tool action, approval, or failure.                         |
+| T3 home        | The base data directory. Runtime state normally lives under its `userdata` directory.             |
+
+## Orchestration
+
+| Term                    | Meaning                                                                                      |
+| ----------------------- | -------------------------------------------------------------------------------------------- |
+| Command                 | A request to change domain state. Accepting it does not mean its side effects have finished. |
+| Event                   | A persisted fact produced by a command.                                                      |
+| Decider                 | The pure logic that turns a command and current state into events.                           |
+| Projection / read model | A view of current state derived from persisted events.                                       |
+| Projector               | The logic that applies events to a read model.                                               |
+| Reactor                 | A worker that performs follow-up work in response to recorded intent or runtime signals.     |
+| Command receipt         | A durable record of a command's result, used to make retries idempotent.                     |
+| Runtime receipt         | A test-only signal that an asynchronous milestone completed.                                 |
+| Quiesced                | The relevant follow-up workers have finished, beyond the provider turn merely ending.        |
+
+## Providers and checkpoints
+
+| Term                | Meaning                                                                                                      |
+| ------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Provider            | The agent runtime T3 Code controls, such as Codex or Claude Code.                                            |
+| Driver              | The integration for a provider kind.                                                                         |
+| Provider instance   | One configured provider, with its own settings and lifecycle. Multiple instances can use the same driver.    |
+| Adapter             | The boundary translating a provider's native protocol into T3 Code operations and events.                    |
+| Session             | The provider runtime attached to a thread. A session can be stopped and resumed without deleting the thread. |
+| Runtime mode        | The thread's permission policy. See [permission modes](../user/permission-modes.md).                         |
+| Interaction mode    | How the agent approaches the task, such as planning. Separate from permission policy.                        |
+| Checkpoint          | A saved workspace state used for diffs and restore, stored as a hidden Git ref.                              |
+| Checkpoint baseline | The workspace state captured before the work being compared.                                                 |
+| Turn diff           | The workspace changes attributed to one turn.                                                                |
diff --git a/docs/internals/mobile-development.md b/docs/internals/mobile-development.md
index e8923a4bc844..cf9132579229 100644
--- a/docs/internals/mobile-development.md
+++ b/docs/internals/mobile-development.md
@@ -1,50 +1,25 @@
 # Mobile development lifecycle
 
-Ordinary component changes use Metro Fast Refresh. The connection runtime uses
-a stable development-only atom runtime whose writable layer atom receives the
-newly evaluated Effect layer. Its module accepts the update only after installing
-that layer. Existing subscribers observe the new context, and Effect releases the
-previous runtime scope without restarting React Navigation. Production uses an
-ordinary `Atom.runtime` without this hot-update boundary.
-
-Replacing the atom registry itself disposes its old nodes; replacing the managed
-runtime starts its asynchronous disposal. These modules use normal Metro update
-propagation. The app does not call `DevSettings.reload` during their replacement.
-React can still reset state when its normal Fast Refresh rules require it.
-
-Do not reset the shared registry to clean up a connection-runtime edit: registry
-reset removes listeners from unedited mounted consumers. Do not self-accept a
-runtime module while leaving importers attached to its old implementation. A
-hot-update boundary must install fresh behavior through the existing reactive
-dependencies. These boundaries do not make every module-level atom family in the
-app hot-swappable; new runtime singletons still need explicit ownership. Editing
-the registry or managed runtime can still rebuild a much larger dependency graph
-than an ordinary component or connection-runtime edit.
-
-Environment supervisor scopes are children of the connection registry scope.
-The registry's per-environment map supports targeted shutdown, but it cannot be
-the sole owner: a supervisor created after that map's finalizer has run must
-still inherit the closed parent scope. Otherwise interrupted startup or runtime
-replacement can leave a session and WebSocket alive outside the current registry.
-
-The compact Home list owns its minute-based presentation clock in a focus effect.
-Blur clears the interval without a render-driving focus subscription; focus
-refreshes the clock immediately. Other prop or state changes can still render
-the hidden list. Exact snooze-expiry timers remain active, and the visible iPad
-sidebar keeps its own minute updates.
-
-Connection and runtime projections are shared per environment. Thread selection
-consumers should read those atoms instead of repeatedly parsing the same socket
-URL or constructing new connection objects during each render.
-
-The Uniwind dependency patch still recompiles CSS on Metro updates so newly used
-classes are discovered. It fingerprints the generated native stylesheet and
-theme list, then skips development-only global invalidation when that output is
-unchanged. A changed stylesheet or theme list still resets the style caches and
-notifies subscribers. The digest is committed only after initialization succeeds.
-Web and production retain their existing initialization behavior.
-
-After installing or changing the Uniwind patch, restart Metro once with
-`vp run dev:client:reset` from `apps/mobile`. pnpm gives patched packages new
-filesystem paths, and cached transforms can otherwise retain references to the
-previous package. Ordinary development starts should retain the transform cache.
+The [connection runtime's HMR boundary](../../apps/mobile/src/lib/hot-swappable-atom-runtime.ts)
+keeps a stable atom runtime and replaces its Effect layer through a writable atom.
+It accepts the update only after installing the new layer. Otherwise importers
+retain the old behavior even though Metro reports a successful refresh.
+
+Do not reset the shared atom registry to refresh a connection-runtime edit. Reset
+removes listeners from mounted consumers that Metro has no reason to rerender.
+When the registry or managed-runtime module itself changes, normal Metro propagation
+disposes its old resources. This boundary does not make arbitrary module-level atom
+families safe to hot-swap. Production uses an ordinary atom runtime.
+
+[Environment supervisor scopes](../../packages/client-runtime/src/connection/registry.ts)
+are children of the registry scope. The per-environment map supports targeted
+shutdown, but a supervisor created after its cleanup runs would escape it. A closed
+parent scope also closes late arrivals, preventing interrupted startup or runtime
+replacement from leaving a WebSocket alive outside the new registry.
+
+The [Uniwind patch](../../patches/uniwind@1.11.0.patch) still compiles CSS on Metro
+updates so newly used classes are discovered. It skips global style invalidation
+only when the generated stylesheet and theme list are unchanged. Skipping compilation
+would lose new classes; invalidating every consumer for unchanged output makes an
+ordinary component edit refresh the whole app. The fingerprint is recorded only
+after initialization succeeds.
diff --git a/docs/internals/mobile-navigation.md b/docs/internals/mobile-navigation.md
index c2528219ac6b..94bd550d142d 100644
--- a/docs/internals/mobile-navigation.md
+++ b/docs/internals/mobile-navigation.md
@@ -1,138 +1,56 @@
 # Mobile navigation
 
-The iOS Home and thread routes share the root native stack in
-[`Stack.tsx`](../../apps/mobile/src/Stack.tsx). Keeping them in one navigation
-controller lets UIKit animate the header between routes. The iPad sidebar owns
-a separate, single-screen stack; Android uses its own in-flow headers.
-
-Home and the iPad sidebar render their brand and connection status through
-`headerTitle`, with `Threads` retained as the route title. The editor-style native
-bar aligns that title on the leading side. Do not model the brand as a toolbar
-button: on iOS 26.5 UIKit morphs a background-free custom leading item's rectangle
-into the next screen's glass back button, even with distinct item identifiers.
-Using the title slot lets the brand and native back button animate separately.
-
-The connection-status title has a maximum width based on its header's width and
-trailing actions. A long environment name or larger text must not push Settings
-into UIKit's overflow menu. Keep the full status as the accessibility label
-while visually truncating it. The iPad sidebar uses its pane width, not the full
-window width.
-
-On iOS 26, UIKit does not recognize Fabric's custom text views when shaping the
-native scroll-edge fade. The screens patch gives custom title subviews an empty,
-non-interactive native label matching their bounds. This supplies the fade's
-geometry without drawing anything or turning the title back into a toolbar item.
-Check the top scroll fade as well as push/pop when changing these title views.
-
-The react-native-screens patch caches leading, trailing, and center item groups
-independently. A button can belong to only one group: constructing another group
-with the same button removes it from the previous one. Unrelated menu updates
-must therefore preserve the other groups while UIKit may be animating them.
-
-Each cache includes the owning header config, its item values, and custom native
-item identities, so changed content or remounted event emitters still rebuild.
-
-Custom header identifiers require native code generation and a new mobile build;
-an over-the-air JavaScript update alone is insufficient. The Android view manager
-implements the generated identifier setter as a no-op because this behavior is
-specific to iOS 26 and later.
-
-On iOS 26 the full-screen back swipe is UIKit's `interactiveContentPopGestureRecognizer`,
-and react-native-screens makes it wait for any horizontally scrollable ScrollView to
-fail first. Upstream applies that to every horizontal ScrollView regardless of
-position, so a back swipe on a code block or table that is already at its leading
-edge only bounces. The patch narrows the rule to ScrollViews with content still
-hidden to the left; at the leading edge they yield to the pop gesture like plain
-text does.
-
-After changing a dependency patch, refresh CocoaPods before rebuilding an
-existing iOS project. pnpm installs each patch hash in a different directory;
-an old Pods project can keep compiling the previous directory even though Metro
-and `apps/mobile/node_modules` resolve to the new patch.
-
-`ControlPillMenu` resolves semantic icon colors through `withUniwind` and supplies them to every
-iOS `MenuView` action, including nested actions. The menu library's Fabric bridge converts a missing
-`imageColor` to transparent, so callers should use this wrapper instead of
-rendering `MenuView` directly. Explicit colors are preserved, and destructive
-actions default to the theme's danger foreground color. Native stack header menus
-use a separate implementation and do not need this workaround.
+Home and thread routes share the [root native stack](../../apps/mobile/src/Stack.tsx)
+so UIKit can animate the header within one navigation controller. The iPad sidebar
+has its own stack. Splitting Home and threads between controllers loses that
+continuous transition.
+
+## UIKit constraints
+
+The [react-native-screens patch](../../patches/react-native-screens@4.26.2.patch)
+preserves behavior that is easy to break when changing native headers:
+
+- The brand belongs in `headerTitle`. On iOS 26.5, UIKit morphs a background-free
+  leading toolbar item's rectangle into the next screen's glass back button,
+  even when the items have different identifiers.
+- UIKit's scroll-edge fade does not recognize Fabric text views. An empty native
+  label supplies the custom title's geometry. Removing that apparently unused
+  view changes the fade.
+- Leading, trailing, and center item groups need independent caches. A button can
+  belong to only one group; rebuilding an unchanged group can pull its buttons
+  out of a group UIKit is still animating. Cache ownership also includes the
+  header config, whose event emitter changes on remount.
+- A horizontal ScrollView at its leading edge must yield to the full-screen back
+  gesture. Upstream gives every horizontal ScrollView priority, so swiping back
+  on a code block or table can only bounce its content.
+
+The patch adds native header props that require code generation and a new binary.
+Patch rebuild guidance lives in the
+[mobile development README](../../apps/mobile/README.md#development).
 
 ## Native media presentations
 
-`PresentationSource` in `NativePresentation` registers a thumbnail for AVKit,
-image zoom transitions, and UIKit's share sheet. Wrap the thumbnail as its single child
-and pass the stable identifier to the presentation. The registry keeps weak
-references to source views; recycled or compact composer thumbnails can register
-the same identifier. Identifiers must distinguish simultaneously visible attachments.
-The source registration does not own the preview. Android uses a regular view.
-
-On iOS, video previews mount `AVPlayerViewController` temporarily inside the
-registered source and enter full screen through AVKit. AVKit
-owns that zoom, its playback controls, Close button, and interactive dismissal.
-Do not replace AVKit's transition with `preferredTransition`: in the iOS 27
-simulator, that leaves native Close unable to exit full screen. When the source is unavailable,
-the player uses a standard modal presentation. Programmatic entry uses the same
-guarded `enterFullScreenAnimated:completionHandler:` selector as Expo Video;
-if that selector is unavailable, the player also falls back to a standard modal.
-
-`FilePreviewModal` resolves image and PDF sources from a URI, a signed environment asset,
-or a retained composer file. On iOS, Quick Look owns image and document layout, controls,
-zooming, sharing, and interactive dismissal. Its delegate supplies the registered thumbnail
-and its bounds for Quick Look's source-view zoom. Do not layer `preferredTransition` or
-another image scroll view over that presentation: Quick Look coordinates its image gestures
-with the return to the thumbnail. Missing sources use the standard transition, and Reduce
-Motion disables animation. A pending programmatic Close waits until the current presentation
-or cancelled dismissal has settled before starting another transition.
-
-The shared native presenter copies original bytes into its own temporary directory and
-removes that copy after dismissal. Network downloads write to disk, and sharing never edits
-the source attachment. Draft images use their stored upload data rather than a potentially
-expired picker URI. No React Navigation route or custom transition animator is needed.
-
-The same viewer handles message images, markdown images, PDF attachments and links,
-composer thumbnails, and workspace image previews. The workspace PDF web preview has an
-Open PDF action for the native viewer. Android retains its image viewer and uses the
-system chooser for PDFs. Saving images on iOS uses the add-only photo-library permission.
-
-Every full-screen video preview on iOS is AVKit, playing directly from the signed asset
-URL: sent attachments, composer drafts, and file links that point at a video. Inline
-markdown embeds and the workspace file screen play in place with the Expo Video player.
-AVKit handles buffering; the client does not download the entire file or show a separate
-opening overlay before presentation.
-The URL is captured once per preview so credential refresh does not restart playback.
-Media actions (copy path, open in file viewer, save or share) belong to the surface that
-opened the video, a long-press on the thumbnail, so the player carries no
-menu. AVKit has no retry; a failure alerts and closes, re-mints the URL in the background, and the next open plays from the fresh one.
-
-The native presentation promise completes after dismissal. Local draft previews
-hold their file lease until that promise settles. The iOS preview component requests
-native dismissal when its source screen unmounts. Playback pauses in the background.
-AVPlayer activates audio as playback starts. The presenter pauses and releases
-its own player on close, then restores the previous audio-session configuration
-if no other component changed it during playback. It does not deactivate the
-shared session, which may still serve another player or recorder. Android plays every
-video, attachments included, in its React Native modal with the Expo Video player.
-Composer drafts play and share from their local file; other videos stream from the
-signed URL and download only for save or share.
-
-`shareFileFromSource` uses the same source registration to anchor UIKit's activity
-controller. Its promise completes when the native share flow finishes, keeping
-the existing attachment lease and foreground handoff active for that duration.
-Android uses Expo Sharing. On iOS, received and draft video attachments expose
-Save or share through `VideoAttachmentMenu`. The attachment supplies the source
-identifier, and the native share presentation inherits its appearance. AVKit's
-iOS playback controls do not expose a public custom-share-action API.
-
-Video attachment thumbnails use Expo Video's native frame extraction and Expo Image.
-Received attachments use their signed asset URL; drafts retain and resolve their local file
-until extraction ends. Extraction is serial; temporary players never play or change audio settings. Leaving the screen cancels
-pending work; a 15-second limit prevents an unreachable source from holding up the queue.
-The client keeps at most 32 native images, each bounded to 480 pixels per side, keyed by
-environment and attachment identity rather than expiring URLs. Images still displayed keep
-their own references when evicted from that cache.
-
-The asset HTTP route supports single byte ranges for videos so iOS can read metadata and
-frames without first downloading the whole file. Normal downloads keep their full response;
-unsupported ranges and conditional `If-Range` requests also fall back to the full file.
-An older environment without range support may still show the play-card fallback. Thumbnail
-failure never disables playback or sharing.
+iOS delegates full-screen video to [AVKit](../../apps/mobile/modules/t3-native-controls/ios/T3NativeVideoPresentation.swift)
+and images and documents to [Quick Look](../../apps/mobile/modules/t3-native-controls/ios/T3NativeFilePresentation.swift).
+Each framework owns its controls and transition. A separate UIKit zoom transition
+prevents AVKit's native Close action from exiting full screen and interferes with
+Quick Look's interactive return to its thumbnail. The AVKit entry selector is
+guarded, with standard modal presentation as the fallback.
+
+[Thumbnail registration](../../apps/mobile/modules/t3-native-controls/ios/T3NativePresentation.swift)
+holds weak view references for transition and share-sheet anchors. It does not own
+the preview; a source row can disappear while a native presentation is open.
+Identifiers must distinguish attachments that are visible at the same time.
+Native promises complete after dismissal so callers keep local file leases until
+the preview or share flow has finished.
+
+Treat a dismissal request as pending until UIKit finishes its current transition.
+Starting another dismissal while presentation or an interactive dismissal is
+settling can strand the controller. Video cleanup restores the previous audio
+configuration only if it still matches the preview's configuration. It must not
+deactivate the shared audio session, which may belong to another player or recorder.
+
+Video playback holds the first signed asset URL for the lifetime of the preview.
+Following credential refreshes reactively would restart playback. Quick Look copies
+original bytes into its own temporary directory so preview and sharing cannot
+mutate a draft or workspace file.
diff --git a/docs/internals/model-manifest.md b/docs/internals/model-manifest.md
index d5be97afe92b..3892a1df7277 100644
--- a/docs/internals/model-manifest.md
+++ b/docs/internals/model-manifest.md
@@ -1,42 +1,25 @@
 # Model manifest
 
-`apps/server/src/provider/model-manifest.json` is bundled for offline startup and fetched from
-`main` at runtime. A remote fetch replaces the in-memory and on-disk cache only after generic
-catalog references and provider-owned adapter data validate. A failed or invalid fetch keeps the
-last successful remote manifest. The bundle is used when no valid remote cache exists, or when
-the bundle's `updatedAt` is later than the cached manifest's, so a release that edits the manifest
-takes effect before the next successful fetch. Bump `updatedAt` whenever you edit the file.
-
-The top-level provider catalog is generic: models contain presentation metadata, aliases, status,
-an optional badge, and a reusable capability profile. The profile and model `adapter` fields are
-opaque until the owning provider validates them with its own allowlisted schema.
-
-Claude Code uses the manifest as its complete built-in model catalog. To add a Claude model that
-uses an existing profile, add one object to `providers.claudeAgent.models`. Do not add a test or
-change application code. Add or change a profile in the same JSON file only when the model exposes
-a capability combination that does not already exist.
-
-`currentModels.claudeAgent` is retained as a frozen compatibility field for releases that predate
-catalog discovery. New Claude models do not need to be added there. Codex still discovers models
-from its app server and uses `currentModels.codex` only as a legacy-classification overlay.
-
-Claude model entries support:
-
-- `aliases`, `status`, `badge`, and `profile` for client presentation and selection.
-- `adapter.claudeCode.minVersion` and `maxVersionExclusive` for installed-runtime compatibility.
-- Profile-level effort mappings, model suffixes, and context-window metadata for dispatch.
-
-## Test policy
-
-Changing model data does not require tests. Do not add or update tests for a model slug, display
-name, alias, legacy status, version boundary, badge, or profile assignment. The bundled manifest is
-configuration and is validated by its schema when imported.
-
-Add tests only when implementation behavior changes:
-
-- Fetching, caching, fallback, or schema-version handling changes in the manifest service.
-- Provider-neutral profile resolution gains new semantics.
-- A provider adapter gains a new compatibility or dispatch mapping type.
-
-Resolver tests must use synthetic providers and model names so normal JSON edits never create test
-churn.
+The [bundled manifest](../../apps/server/src/provider/model-manifest.json) allows
+offline startup; fetching it from `main` lets model metadata change between
+releases. Failed fetches or invalid data preserve the last usable manifest.
+Remote data must pass both catalog-reference validation and the owning provider's
+adapter validation before replacing the cache.
+
+A newer bundle outranks the cached remote manifest by `updatedAt`, so a release can
+correct model data before the next successful fetch. Bump `updatedAt` whenever the
+file changes. Fetch time cannot establish which copy contains the newer edit.
+
+Generic catalog data describes presentation and capabilities. Each provider owns
+its adapter schema and dispatch mappings. Claude uses the manifest for its entire
+built-in catalog. Adding a model with an existing capability profile is a JSON
+edit; a new profile is needed only for a new capability combination. Codex still
+gets its model list from its app server.
+
+`currentModels.claudeAgent` is frozen for releases that predate catalog discovery.
+Do not extend it when adding Claude models. Codex uses `currentModels.codex` as a
+legacy-classification overlay for discovered models.
+
+Model data is schema-validated configuration. Tests should cover resolver, cache,
+and adapter semantics with synthetic model names, so adding a model never requires
+tests that repeat the configuration.
diff --git a/docs/internals/overview.md b/docs/internals/overview.md
index 3affe10c48f7..7d4f2d0170e1 100644
--- a/docs/internals/overview.md
+++ b/docs/internals/overview.md
@@ -1,179 +1,67 @@
 # Architecture
 
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-T3 Code is a server runtime that owns agent sessions, workspaces, and version control, plus clients
-(web, desktop, mobile) that talk to it over one authenticated Effect RPC WebSocket. The server is the
-execution boundary: every provider process, terminal, git operation, and filesystem read happens
-there, never in the client.
-
-```
-┌────────────────────────────────────────────────┐
-│ Clients: apps/web, apps/desktop, apps/mobile   │
-│ shared runtime: packages/client-runtime        │
-│  connection supervisor, RPC session, Atom state│
-└──────────────────┬─────────────────────────────┘
-                   │ Effect RPC over WebSocket (/ws)
-                   │ contract: packages/contracts
-┌──────────────────▼─────────────────────────────┐
-│ apps/server                                    │
-│  orchestration engine (event-sourced)          │
-│  provider driver registry (6 built-in drivers) │
-│  checkpointing, VCS, terminals, filesystem     │
-└──────────────────┬─────────────────────────────┘
-                   │ per-driver transport
-┌──────────────────▼─────────────────────────────┐
-│ Agent CLIs: Codex, Claude, Cursor, Grok,       │
-│ OpenCode, Antigravity                          │
-└────────────────────────────────────────────────┘
-```
-
-## The RPC boundary
-
-The client/server contract is an Effect RPC group, not a hand-rolled push protocol. [`rpc.ts`][rpc]
-declares `WS_METHODS` and assembles `WsRpcGroup`; each member is either unary or a server stream
-(`stream: true`). Streaming members such as `orchestration.subscribeShell`,
-`orchestration.subscribeThread`, `subscribeServerConfig`, and `terminal.attach` replace what used to
-be a broadcast push bus: a client subscribes to what it needs and the server pushes only on that
-subscription.
-
-[`ws.ts`][ws] serves the group. `websocketRpcRouteLayer` mounts `GET /ws`, authenticates the upgrade
-through `EnvironmentAuth.authenticateWebSocketUpgrade`, then hands the socket to
-`RpcServer.toHttpEffectWebsocket`. Authorization is per method: `RPC_REQUIRED_SCOPE` maps each method
-to a scope, and `authorizeEffect`/`authorizeStream` enforce it. Holding a valid socket is not
-authorization to call everything on it. See [environment-auth.md](./environment-auth.md).
-
-On the client, [`session.ts`][session] opens the socket and builds the typed client.
-`RpcSessionFactory` is the service; a session exposes `client`, `initialConfig`, `ready`, `probe`,
-and `closed`. It performs one attempt and does not retry. Retry, backoff, and offline policy belong
-to the connection supervisor.
-
-## Shared client runtime
-
-`packages/client-runtime` holds every non-visual client concern: connection lifecycle,
-authentication, RPC, cached environment data, and domain state as Atom factories. Web and mobile
-compose it the same way (`apps/web/src/connection/runtime.ts` and
-`apps/mobile/src/connection/runtime.ts` mirror each other, differing only in platform-specific
-background-activity layers) and differ beyond that only in the platform layer they supply and the
-UI they build on top. React components never construct transports, retry loops,
-or RPC clients. See [connection-runtime.md](./connection-runtime.md).
-
-## Orchestration is event-sourced
-
-The server does not mutate app state directly. Clients dispatch typed commands; the engine turns them
-into persisted events; projections derive the read model.
-
-[`OrchestrationEngine.ts`][engine] serializes this. `dispatch` offers a `CommandEnvelope` onto
-`commandQueue` and awaits its result; a single worker fiber takes envelopes one at a time, so command
-processing is totally ordered. For each envelope `processEnvelope`:
-
-1. checks the durable command receipt, making retries idempotent;
-2. runs `decideOrchestrationCommand` ([`decider.ts`][decider]) to produce events from command plus
-   current state, pure and side-effect free;
-3. inside one SQL transaction, appends events to the event store, applies them to the in-memory read
-   model via [`projector.ts`][projector], projects them into persisted tables, and writes the
-   accepted receipt;
-4. after commit, swaps in the new read model, cleans up attachments, and publishes committed events
-   to subscribers. Attachment cleanup failures are logged and do not reject committed commands.
-
-Because persistence and projection share a transaction, the read model cannot durably disagree with
-the event log. On dispatch failure the engine rereads persisted events past the starting sequence and
-reconciles.
-
-Command and event names live in [`orchestration.ts`][contracts]. Some commands are client
-dispatchable (`thread.create`, `thread.turn.start`, `thread.approval.respond`); others are internal
-and produced only by server-side reactors (`thread.message.assistant.delta`,
-`thread.turn.diff.complete`).
-
-A turn is complete when its session leaves `running` status, projected by
-`settledTurnStateForSessionStatus` in [`projector.ts`][projector]. Checkpoint work settling later
-does not define turn end.
-
-Thread settlement is server-owned. Each server's own settings control PR and inactivity
-settlement. Those keys are user preferences, so clients write them to every shared-settings sync
-target (`SHARED_SERVER_SETTING_KEYS` in `packages/client-runtime/src/state/sharedSettings.ts`) and
-warn when another target drifts. A target must have an active connection and advertise the
-`threadAutoSettlement` capability, which signals that the server can hold every shared key.
-[`ThreadSettlementReactor`][settlement] checks threads at startup, when those settings change, and
-once per minute, including when no client is connected. It dispatches the guarded internal
-`thread.auto-settle` command, which uses the existing settlement event lifecycle. Automatic
-settlement excludes live background work and requires a comparable PR timestamp for immediate PR
-settlement. The command carries the latest activity timestamp and rejects any later event for its
-thread after the reactor's snapshot. The sweep looks a branch up from the thread's worktree when it
-still exists, so it shares the per-cwd PR cache the sidebar polls instead of spending a second host
-request. Clients render the persisted settlement state and do not derive settlement from PR or
-inactivity state. A committed `thread.settled` event also lets `ProviderCommandReactor` stop an idle
-provider session.
-
-At turn completion, `CheckpointReactor` refreshes PR discovery when the checkout matches the
-thread's non-default branch. `VcsStatusBroadcaster` requires loaded remote status and permission
-from background policy. `GitManager` retries only a successful "no PR" cache entry for the current
-branch, preserving known PRs and failure backoff without fetching remotes. Remote status reads
-that write the broadcaster cache share a lock per cwd, including the initial status load.
-
-## Drainable workers
-
-Follow-up work runs asynchronously in queue-backed workers built on [`DrainableWorker`][worker]:
-[`ProviderRuntimeIngestion`][ingest] normalizes provider runtime streams into orchestration commands,
-[`ProviderCommandReactor`][cmd] dispatches provider calls in response to intent events,
-[`CheckpointReactor`][checkpoint] captures and reverts workspace checkpoints, and
-[`ThreadSettlementReactor`][settlement] evaluates server-owned automatic settlement rules.
-
-`DrainableWorker` pairs a transactional queue with a transactional count of outstanding items.
-`enqueue` atomically offers and increments; processing always decrements. `drain` retries until the
-count reaches zero, so a test can await "queue empty and current item finished" instead of sleeping.
-Each of these four services exposes `drain` for exactly this.
-
-Runtime receipts are a test-only mechanism. `RuntimeReceiptBusLive` in
-[`RuntimeReceiptBus.ts`][receipts] publishes nothing; only the test layer is PubSub-backed. Do not
-build production behavior on receipts.
-
-## Provider drivers
-
-Six drivers ship built in, registered in [`builtInDrivers.ts`][drivers] as `BUILT_IN_DRIVERS`:
-Codex, Claude, Cursor, Grok, OpenCode, and Antigravity. A driver declares its kind and config schema and creates a
-scoped adapter; `ProviderInstanceRegistry` owns live instances and `ProviderAdapterRegistry` resolves
-an instance to its adapter, so `ProviderService` routes session and turn operations without knowing
-which agent is behind them. See [providers.md](./providers.md).
-
-## Checkpointing
-
-Each turn is bracketed by workspace checkpoints so diffs and reverts are exact. `CheckpointStore`
-captures state as hidden Git refs through the VCS driver's checkpoint operations;
-`CheckpointDiffQuery` answers turn and full-thread diff requests; `CheckpointReactor` coordinates
-baseline capture, completed-turn capture, diff projection, and reverting both the workspace and the
-provider conversation. The storage contract is `VcsCheckpointOps` in
-[`VcsDriver.ts`](../../apps/server/src/vcs/VcsDriver.ts), implemented for Git in the same directory.
-
-## Startup
-
-[`serverRuntimeStartup.ts`][startup] runs a fixed lifecycle: start keybindings, settings, and
-reactors; publish welcome; signal command readiness (logged as `Accepting commands`); wait for the
-HTTP listener via `markHttpListening`; publish ready; fork the heartbeat; then either print headless
-output or open the browser. Command readiness precedes the listener, so a socket that opens can
-already dispatch.
-
-## Related
-
-- [Workspace layout](./workspace-layout.md), [Glossary](./glossary.md)
-- [Mobile navigation headers](./mobile-navigation.md)
-- [Remote environments](./remote.md), [Server updates](./server-updates.md)
-- [Resource telemetry](./resource-telemetry.md)
-- [Product analytics](./product-analytics.md)
-- [Scripts](./scripts.md), [CI gates](./ci.md)
-
-[rpc]: ../../packages/contracts/src/rpc.ts
-[contracts]: ../../packages/contracts/src/orchestration.ts
-[ws]: ../../apps/server/src/ws.ts
-[session]: ../../packages/client-runtime/src/rpc/session.ts
-[startup]: ../../apps/server/src/serverRuntimeStartup.ts
-[engine]: ../../apps/server/src/orchestration/Layers/OrchestrationEngine.ts
-[decider]: ../../apps/server/src/orchestration/decider.ts
-[projector]: ../../apps/server/src/orchestration/projector.ts
-[worker]: ../../packages/shared/src/DrainableWorker.ts
-[ingest]: ../../apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
-[cmd]: ../../apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
-[checkpoint]: ../../apps/server/src/orchestration/Layers/CheckpointReactor.ts
-[settlement]: ../../apps/server/src/orchestration/ThreadSettlementReactor.ts
-[receipts]: ../../apps/server/src/orchestration/Layers/RuntimeReceiptBus.ts
-[drivers]: ../../apps/server/src/provider/builtInDrivers.ts
+T3 Code keeps execution in the environment that owns the workspace. Web, desktop, and mobile
+clients control it over authenticated RPC. A remote client must never substitute its own filesystem,
+provider credentials, or machine state for the environment's. The desktop app bundles a server,
+but its renderer follows the same boundary.
+
+## Ownership boundaries
+
+Provider processes, terminals, Git, and project files belong to the server. Shared connection and
+domain state belongs in `packages/client-runtime`; clients supply platform services and UI.
+Keeping that logic shared prevents reconnect and multi-environment behavior from diverging between
+web and mobile. See [connection runtime](./connection-runtime.md) and
+[remote environments](./remote.md).
+
+The [RPC contract](../../packages/contracts/src/rpc.ts) is the boundary between independently
+versioned clients and servers. Subscriptions send the state a client needs, so a client viewing one
+thread does not pay for every thread's history. Authentication of a socket does not authorize every
+method on it. See [environment auth](./environment-auth.md).
+
+Provider-specific behavior belongs behind an adapter. Orchestration works with normalized commands
+and events, so adding a provider should not require branches throughout the domain or clients.
+See [provider constraints](./providers.md).
+
+## Durable intent and side effects
+
+The event log is the source of truth for orchestration state. The
+[engine](../../apps/server/src/orchestration/Layers/OrchestrationEngine.ts) serializes commands;
+the [decider](../../apps/server/src/orchestration/decider.ts) produces events without performing
+provider or filesystem work. Events, persisted projections, and the accepted command receipt commit
+in one database transaction. The in-memory state changes and subscribers receive events after that
+commit. This keeps command retries idempotent and prevents a persisted projection from getting
+ahead of the event log.
+
+Reactors perform side effects after intent has been recorded, then feed results back through
+commands. A command acknowledgement therefore means the intent committed, not that the provider,
+checkpoint, or other follow-up work finished. Keep external I/O out of the decider and the database
+transaction.
+
+Persisted events must remain decodable on replay. Changing a schema affects old environments at
+startup as well as live RPC traffic. Compatibility work must account for stored history, not just
+what the newest client sends.
+
+## Turn completion and checkpoints
+
+A turn ending and its follow-up work settling are separate milestones. The
+[projector](../../apps/server/src/orchestration/projector.ts) settles the turn from its session
+status. A late checkpoint or diff must not extend the recorded turn duration or keep the client
+showing provider work as active.
+
+[Checkpoints](../../apps/server/src/checkpointing/CheckpointStore.ts) use hidden Git refs to
+capture workspace state without adding commits to the user's branch. A revert must coordinate
+workspace state with the provider conversation. A provider that cannot roll back its conversation
+must reject that operation before changing the filesystem.
+
+## Waiting for asynchronous work
+
+Tests use [drainable workers](../../packages/shared/src/DrainableWorker.ts) to wait until both the
+queue and its current item have finished. An empty queue alone does not prove the worker is idle.
+
+Runtime receipts mark specific test milestones. Their
+[production layer](../../apps/server/src/orchestration/Layers/RuntimeReceiptBus.ts) is a no-op;
+production behavior must use persisted state and events. These test signals are separate from the
+durable command receipts that make dispatch idempotent.
+
+See the [glossary](./glossary.md) for shared terms and the
+[development runbook](../operations/development.md) for setup and checks.
diff --git a/docs/internals/product-analytics.md b/docs/internals/product-analytics.md
index b1116986bf32..0e88610ada99 100644
--- a/docs/internals/product-analytics.md
+++ b/docs/internals/product-analytics.md
@@ -1,177 +1,49 @@
 # Product analytics
 
-T3 Code sends anonymous product events from the server to PostHog. The server
-uses the first available hashed Codex account ID, hashed Claude user ID, or
-installation-scoped anonymous ID as the distinct ID. It also keeps the
-telemetry opt-out, event buffer, and batch delivery. Clients do not load the
-PostHog browser SDK.
-
-## Client events
-
-These events use the metadata from the WebSocket connection that caused them.
-The metadata is not a person property or server-global current-client value.
-Two clients connected to one server can report different values at the same
-time.
-
-| Event                   | Description                                                                                                                                          |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `client.connected`      | The server accepted an authenticated WebSocket connection. Reconnects count again. Use this event for connection diagnostics, not active-use counts. |
-| `client.thread.started` | The server accepted a command that created a thread.                                                                                                 |
-| `client.turn.requested` | The server accepted a turn request. This is the standard active-use event.                                                                           |
-
-`provider.turn.sent` stays a provider execution event. It does not receive
-client metadata because a provider turn can continue after the requesting
-client disconnects.
-
-## Provider turn events
-
-`provider.turn.completed` records one anonymous event when a provider emits a
-canonical completed or aborted turn. The event reports normalized main-agent
-token counts when the provider supplies enough data.
-
-| Property              | Values and meaning                                                                                                              |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `provider`            | Provider driver, such as `codex`, `claudeAgent`, or `opencode`. Use this as the harness breakdown.                              |
-| `model`               | Selected or provider-reported model when known. This is metadata, not proof that one model produced every token.                |
-| `effort`              | Selected or provider-reported reasoning effort when known.                                                                      |
-| `interactionMode`     | Turn interaction mode, `default` or `plan`, when known.                                                                         |
-| `runtimeMode`         | Session permission mode when known.                                                                                             |
-| `mixedModels`         | `true` when T3 Code observed `model.rerouted` during the turn. This does not split token counts by model.                       |
-| `durationMs`          | Time from the observed turn start or accepted send request to the terminal event. Omitted when start metadata is not available. |
-| `terminalStatus`      | `completed`, `failed`, `interrupted`, or `cancelled`.                                                                           |
-| `usageStatus`         | `complete`, `partial`, or `unavailable`.                                                                                        |
-| `usageScope`          | `main_agent`. Child-agent token use is not included.                                                                            |
-| `hasSubagents`        | Whether the adapter observed child agents during the turn. Omitted when the adapter does not provide a normalized usage report. |
-| `inputTokens`         | Total main-agent input tokens. This includes uncached input, cache reads, and cache creation or writes.                         |
-| `cachedInputTokens`   | Cache-read tokens. This is a subset of `inputTokens`.                                                                           |
-| `cacheCreationTokens` | Cache creation or write tokens. This is a subset of `inputTokens`.                                                              |
-| `outputTokens`        | Total main-agent output tokens, including reasoning tokens.                                                                     |
-| `reasoningTokens`     | Reasoning tokens when the provider reports them separately. This is a subset of `outputTokens`.                                 |
-
-`complete` means the provider supplied full input and output totals for the
-turn. `partial` means each included count is valid, but T3 Code did not observe
-the full turn. This can happen after an interruption, provider failure, or
-reconnect. `unavailable` means the provider did not supply trustworthy counts.
-Numeric properties are omitted when their values are unknown. They are not set
-to zero.
-
-Codex uses deltas from its cumulative token totals, and falls back to the
-newest response's `last` usage when no prior total exists or the total was
-reset. Claude uses the final result's per-turn `usage` value and does not use
-cumulative `modelUsage`.
-OpenCode sums unique main-session step totals. Cursor, Grok, and Antigravity
-usage stays `unavailable` until their ACP token fields and scope are verified.
-
-The completed event count does not have to match `provider.turn.sent`. For
-example, Claude can emit synthetic turns without a matching send request.
-Duplicate terminal events for the same provider instance, thread, and turn
-produce one analytics event.
-
-Collection is best effort and starts with the first server release that
-contains this event. T3 Code does not scan provider history or backfill older
-turns.
-
-## Recommended properties
-
-Client properties appear on the three client events when the connected client
-reports them. Older clients can omit every client property.
-
-| Property               | Values and meaning                                                                                                                                                                              |
-| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `surface`              | Product client: `web`, `desktop`, or `mobile`.                                                                                                                                                  |
-| `webDeployment`        | Web delivery: `hosted` for the hosted app or `server` for web files served by a T3 server. Web only. This does not describe connection distance.                                                |
-| `clientOs`             | `macOS`, `Windows`, `Linux`, `iOS`, `Android`, `ChromeOS`, `other`, or `unknown`.                                                                                                               |
-| `clientDeviceType`     | `desktop`, `phone`, `tablet`, or `unknown`. This is separate from `surface`.                                                                                                                    |
-| `clientBrowser`        | Normalized browser family. Web only. Browser detection is best effort.                                                                                                                          |
-| `clientAppVersion`     | Version of the connected client.                                                                                                                                                                |
-| `clientOsMajorVersion` | Client OS major version when the native client reports it. Initially mobile only.                                                                                                               |
-| `clientDeviceModel`    | Hardware model when the native client reports it. Initially mobile only. This is not a user-assigned device name.                                                                               |
-| `connectionMethod`     | `direct`, `ssh`, `relay`, or `unknown`. `direct` means that the client connected to the server endpoint without an SSH or relay connection. It does not mean both processes run on one machine. |
-
-Server properties appear on all events, including server boot and background
-events.
-
-| Property           | Values and meaning                                             |
-| ------------------ | -------------------------------------------------------------- |
-| `serverOs`         | Server process OS, normalized to the same names as `clientOs`. |
-| `serverArch`       | Server process architecture.                                   |
-| `serverWslDistro`  | WSL distribution from `WSL_DISTRO_NAME`, when present.         |
-| `serverAppVersion` | T3 server version.                                             |
-| `serverMode`       | Server runtime mode: `desktop` or `web`.                       |
-
-## Legacy properties
-
-Existing property meanings do not change:
-
-- `clientType` describes how the server runs. It is `desktop-app` for a desktop
-  server and `cli-web-client` for a CLI web server. It does not describe the
-  connected client. Use `surface` and `webDeployment` for new reports.
-- `platform`, `arch`, `wsl`, and `t3CodeVersion` describe the server. Use the
-  new `server*` names for new reports.
-- `appVersion` describes the connected client. Use `clientAppVersion` for new
-  reports.
-- Mobile connection events keep `os`, `osMajorVersion`, and `deviceModel`.
-  Use the new `client*` names for new reports.
-
-## PostHog dashboard
-
-Create one saved dashboard named `Client and platform usage`. Set
-`client.turn.requested` as the event for active-use reports. A user can appear
-in several client groups during one period, so do not add breakdown values to
-calculate a total.
-
-Save these insights:
-
-| Insight                         | Configuration                                                                                                                                                                                                                                                                           |
-| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Active users, daily             | Trends, `client.turn.requested`, unique users, daily interval.                                                                                                                                                                                                                          |
-| Active users, weekly            | Trends, `client.turn.requested`, unique users, weekly interval.                                                                                                                                                                                                                         |
-| Active users, monthly           | Trends, `client.turn.requested`, unique users, monthly interval.                                                                                                                                                                                                                        |
-| Client usage                    | Trends, `client.turn.requested`, unique users. Save four filtered series: `surface = desktop`, `surface = mobile`, `surface = web` and `webDeployment = hosted`, and `surface = web` and `webDeployment = server`. Name them Desktop, Native mobile, Hosted web, and Server-served web. |
-| Client OS, active users         | Trends, `client.turn.requested`, unique users, breakdown by `clientOs`.                                                                                                                                                                                                                 |
-| Client OS, turns                | Trends, `client.turn.requested`, total events, breakdown by `clientOs`.                                                                                                                                                                                                                 |
-| Client versus server OS         | Table, `client.turn.requested`, breakdown by `clientOs` and `serverOs`.                                                                                                                                                                                                                 |
-| Connection method, active users | Trends, `client.turn.requested`, unique users, breakdown by `connectionMethod`.                                                                                                                                                                                                         |
-| Connection method, turns        | Trends, `client.turn.requested`, total events, breakdown by `connectionMethod`.                                                                                                                                                                                                         |
-| Mobile devices                  | Table, `client.turn.requested`, filter `surface = mobile`, breakdown by `clientOs`, `clientOsMajorVersion`, and `clientDeviceType`.                                                                                                                                                     |
-| Client version adoption         | Trends, `client.turn.requested`, unique users, breakdown by `clientAppVersion`.                                                                                                                                                                                                         |
-| Server version adoption         | Trends, `client.turn.requested`, unique users, breakdown by `serverAppVersion`.                                                                                                                                                                                                         |
-| Missing metadata                | Table or SQL insight that shows the percentage of `client.turn.requested` events where each of `surface`, `clientOs`, `clientDeviceType`, `clientAppVersion`, and `connectionMethod` is absent. Track `webDeployment` and `clientBrowser` only within `surface = web`.                  |
-
-In PostHog Data management, use the event and property descriptions from this
-document. Mark the recommended properties as verified. Keep `clientType`
-visible with its legacy description so old reports remain understandable.
-
-Create a second saved dashboard named `Provider token efficiency`. Start each
-token insight with these filters:
-
-- `usageStatus = complete`
-- `hasSubagents = false`
-- `mixedModels = false`
-
-Break down input tokens, output tokens, and their ratio by `provider`. Compare
-the same `model`, `effort`, `interactionMode`, and `terminalStatus`. Without
-these filters, model choice, reasoning level, plan mode, failures, and child
-agents can look like harness differences. Keep separate views for median turn
-usage and aggregate `sum(outputTokens) / sum(inputTokens)`. Do not average each
-turn's ratio because small-input turns can dominate that result.
-
-## Collection and release boundary
-
-Client values are best effort. Invalid values are ignored and never reject a
-connection. Browser clients use user-agent data for broad OS, browser, phone,
-and tablet groups. They do not infer CPU architecture or an exact OS version
-from `navigator.platform`.
-
-This change does not collect URLs, authentication tokens, prompts, IP
-addresses, or user-assigned device names. The token event does not include
-thread IDs, turn IDs, provider instance IDs, event IDs, request IDs, raw
-provider payloads, or child-agent output. It does not scan provider history on
-disk or start external work. It measures authenticated product use. It does
-not measure a person who visits the hosted app without connecting to a server.
-
-The new fields start with the first client and server release that contains
-this metadata path. Historical events cannot reliably identify the client OS,
-hosted web use, device type, or connection method when the old client did not
-send those fields. Reports must treat missing values as pre-release or older
-client data instead of backfilling them from server fields.
+The server owns PostHog delivery, opt-out, and identity for every connected client.
+[Identity selection](../../apps/server/src/telemetry/Identify.ts) hashes an available
+provider account ID, falling back to an installation-scoped ID. This identity can
+span several clients; it does not identify a browser session. Clients do not load
+the PostHog browser SDK. Client-use events require an authenticated connection, so
+visiting the hosted app without connecting does not count as product use.
+
+## Attribution boundaries
+
+Client dimensions belong to the event's WebSocket connection. A server-global
+"current client" would misattribute simultaneous web, desktop, and mobile use.
+Provider execution has its own events because a turn can outlive the requesting
+connection.
+
+Keep client and server dimensions separate. A desktop host can serve a phone or a
+remote browser, and a direct connection can cross a network. Older clients omit
+metadata. Missing client values must stay unknown rather than being backfilled
+from server properties. The legacy `clientType` property describes how the server
+runs; use `surface` for the connected client.
+
+## Interpreting events
+
+Use `client.turn.requested` for active-use reports. `client.connected` counts
+reconnects, so network behavior can inflate it. One identity can appear in several
+client groups during a period; adding those groups double-counts users.
+
+Provider send and completion counts need not match. Providers can emit synthetic
+turns without a send request. Collection is best effort, with no scan or backfill
+of provider history.
+
+Token totals cover the main agent. Child agents and model rerouting prevent a turn
+from representing one provider/model combination's full cost. For provider
+comparisons, require complete usage, no observed subagents, and no mixed models;
+compare matching model, effort, interaction mode, and terminal status. Aggregate
+output/input ratios should divide the summed totals. Averaging per-turn ratios
+lets small-input turns dominate.
+
+Unknown counts stay absent. Partial usage contains valid observed counts but
+cannot establish a whole-turn total. Keep these distinctions when changing token
+normalization or building reports.
+
+## Collection boundary
+
+Keep analytics payloads to product metadata and normalized measurements. Do not
+send prompts, authentication material, raw provider payloads, user-assigned device
+names, or conversation identifiers. Client metadata is best effort; invalid values
+must not reject a connection. PostHog person profiles remain disabled.
diff --git a/docs/internals/providers.md b/docs/internals/providers.md
index bfd294532c74..30c1d00802cb 100644
--- a/docs/internals/providers.md
+++ b/docs/internals/providers.md
@@ -1,395 +1,88 @@
-# Provider architecture
-
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-A provider is the agent runtime that does the actual work. T3 Code supports several, and the
-orchestration layer does not know which one is behind a thread.
-
-## Built-in drivers
-
-[`builtInDrivers.ts`][drivers] exports `BUILT_IN_DRIVERS` with six entries:
-
-| Driver kind   | Driver source                                 |
-| ------------- | --------------------------------------------- |
-| `codex`       | [`Drivers/CodexDriver.ts`][codex]             |
-| `claudeAgent` | [`Drivers/ClaudeDriver.ts`][claude]           |
-| `cursor`      | [`Drivers/CursorDriver.ts`][cursor]           |
-| `grok`        | [`Drivers/GrokDriver.ts`][grok]               |
-| `opencode`    | [`Drivers/OpenCodeDriver.ts`][opencode]       |
-| `antigravity` | [`Drivers/AntigravityDriver.ts`][antigravity] |
-
-Each driver declares its `driverKind`, a `configSchema`, and a `create` function that builds an
-adapter in a child scope. Adapter implementations live beside them in
-`apps/server/src/provider/Layers/` (`CodexAdapter.ts`, `ClaudeAdapter.ts`, and so on) and conform to
-[`ProviderAdapter.ts`][adapter]. Read the driver plus its adapter to see how a specific agent's
-transport, config, and event shapes are mapped.
-
-## Runtime context
-
-Every adapter uses `apps/server/src/provider/RuntimeInstructions.ts` to identify T3 Code and
-the harness, and describe Markdown image/video embeds. Codex includes it in developer
-instructions; Claude appends it to its system preset; OpenCode sends it in each prompt's
-`system` field. Cursor, Grok, and Antigravity append a separate text block to ACP prompts,
-which have no system-message field. This does not change the stored user message.
-
-Per-turn context includes the current model when known. Codex includes reasoning effort;
-Grok includes it when explicitly selected for the turn. Claude's session-level context omits model and effort because they can
-change during a session. OpenCode variants are not assumed to be reasoning-effort levels.
-
-## Codex async questions
-
-Codex 0.153 exposes `request_user_input_async` through `item/started` and `item/completed`
-notifications. The item has `type: "agentMessage"`, `delivery: "async"`, and a `questions` array.
-Each question has a `title` and an optional `options` array of strings. The tool returns `{"accepted":true}`
-without waiting. This is separate from the `item/tool/requestUserInput` server request.
-See the [Codex tool handler](https://github.com/openai/codex/blob/d979df154cf60e13eafb5453e75b6d84f21c67bf/codex-rs/core/src/tools/handlers/request_user_input_async.rs).
-
-The Codex adapter maps completed question items to `user-input.requested` with
-`responseMode: "message"` and stable request and event IDs. Questions use the existing web,
-desktop, and mobile panels. They stay pending while the turn runs and after it finishes.
-
-The engine reads the request's latest stored activity before deciding a reply. This works after
-startup, when the command snapshot has no activities, and after a resolution leaves the recent
-activity window. The query returns one activity, not the full thread history.
-
-For these requests, the decider saves the resolution and a user message in one transaction.
-The standard turn path delivers the message, including session resume and active-turn input.
-It does not send a JSON-RPC response to Codex. Other providers and blocking Codex questions
-keep their existing response paths.
-
-## Registry and routing
-
-Two registries separate configuration from live processes:
-
-- [`ProviderInstanceRegistry`][instances] keys configured instances by `ProviderInstanceId`. Creating
-  one looks up the driver by `driverKind`, decodes `entry.config` with that driver's schema, opens a
-  child scope, and calls `driver.create`.
-- [`ProviderAdapterRegistry`][registry] resolves an instance ID to its live adapter via
-  `getByInstance`.
-
-[`ProviderService`][service] sits on top. It combines the adapter registry with the provider session
-directory to route session and turn operations for a thread, so callers name a thread, not an agent.
-
-`ProviderService.sendTurn` expands [assistant citations](./assistant-citations.md) into quoted
-reference data before dispatching to any adapter. Bound user comments remain distinct from the quoted
-assistant text. Persisted messages keep their serialized links.
-
-Adding a driver means writing the driver plus adapter and adding it to `BUILT_IN_DRIVERS`. No
-orchestration, contract, or client change is required for the common case.
-
-### Grok health check
-
-`checkGrokProviderStatus` never opens an ACP session. It runs `grok --version`, then `grok models`
-for login state and model slugs, then a single ACP `initialize` and reads models from
-`_meta.modelState`. `authenticate` and `session/new` are skipped on purpose: `authenticate` can open
-a browser login and `session/new` boots every configured MCP server, both of which made background
-probes hang or surprise the user. A failed `initialize` degrades to `warning` with the CLI's model
-list instead of persisting `error` over a working install. The built-in `grok-build` slug is the
-CLI's product name, not an ACP model id. `applyGrokAcpModelSelection` treats it as "keep the
-session's current model" and never sends it in `session/set_model`.
-
-## Antigravity ownership and protocol
-
-[`AntigravityDriver`][antigravity] uses Google's official ACP executable. The instance config
-selects the ACP auth method: `oauth-personal` (default), `oauth-business`, `gemini-api-key`, or
-`agent-platform`. The two OAuth methods share the loopback sign-in flow below. The API key
-methods pass the configured key to the agent as `GEMINI_API_KEY` or `GOOGLE_API_KEY` and never
-open a browser. A GCP project and location are written to the profile's `settings.json` on each
-launch. The driver never reuses CLI credentials or ambient `GOOGLE_*` variables and never falls
-back to another method. Antigravity is disabled by default and supports multiple provider
-instances. The open driver and instance identifiers require no database migration.
-
-### Runtime installation
-
-[`AntigravityInstallation`][antigravity-installation] belongs to the environment, outside
-WebSocket and provider-instance scopes. Instances share an explicit download operation and the
-completed runtime. Client disconnects and instance rebuilds do not cancel installation.
-
-The fixed [release table][antigravity-release] contains official Google URLs, SHA-256 hashes,
-archive sizes, and the exact executable pair for each published host. Downloads stream to disk.
-Lazy `yauzl` entry streams extract only that pair, with member names, types, duplicates, and
-sizes checked. Validation runs ACP `initialize` in a temporary profile without authentication
-or a session. Progress updates are bounded, not sent for every network chunk.
-
-Complete releases live in immutable version directories under the T3 home
-`tools/antigravity-acp/<platform>-<arch>/versions`. An atomic `active.json` change selects the
-release for new processes. Each process holds a version lease until it exits. Updates do not
-replace running executables. Removal refuses active leases or explicit binary paths that still
-reference the managed files. Failure or cancellation removes owned partial files, not the
-previous release or account data.
-
-Resolution order is explicit `binaryPath`, active managed release, then the instance's `PATH`.
-An invalid explicit path fails without fallback. Manual installations are never changed by the
-installer. Every launch pins `ANTIGRAVITY_HARNESS_PATH` to the selected executable's sibling.
-
-### Google profiles and sign-in
-
-Each instance owns a stable profile at
-`<stateDir>/providers/antigravity/<sha256(instanceId)>`.
-[`antigravityAuthSupport.ts`][antigravity-auth-support] sets `GEMINI_HOME` to this directory and
-`AGY_ACP_FORCE_FILE_STORAGE=1` after merging instance environment variables. File storage avoids
-the official macOS keychain entry being shared across instances. Profile directories use mode
-`0700` on POSIX. This is file storage, not an encrypted keychain. Windows uses the host profile's
-filesystem permissions.
-
-The launch environment removes API-key and cloud-billing variables, disables inherited
-environment extension, sets `PYTHONUNBUFFERED=1`, and controls `BROWSER`. A tested Node or
-Electron-as-Node helper prevents the official agent from opening a browser on the environment.
-The same launch factory serves setup, health checks, chat, and text generation.
-
-The official agent prints a non-JSON OAuth line on stderr in version 1.1.1. Earlier versions
-print it on stdout. T3 accepts the exact native prefix on either stream and its browser-helper
-marker on stderr. Fragmented lines are joined and bounded. Other malformed protocol output
-remains fatal. Authorization URLs are validated before use. Other stderr is discarded because
-it can contain OAuth data. Normal work rejects an interactive login request with a
-sign-in-required error instead of waiting for consent. A rejected stderr callback fails pending
-ACP requests and closes the owned process.
-
-[`AntigravityAuth`][antigravity-auth] owns each sign-in process and deadline in the instance
-scope. Only the initiating T3 auth session receives its URL and flow ID or can complete or
-cancel it. Other clients receive busy state without those values. Subscriptions follow
-controller replacement when settings rebuild an instance.
-
-For remote completion, the client sends the full return URL through the typed setup RPC.
-The server validates the pending loopback origin, port, root path, and single matching state
-before forwarding once to the owned listener. It does not probe the listener or follow
-redirects. Google's process owns PKCE, token exchange, refresh, and storage. Callback HTTP
-success is not authentication success. The controller waits for authenticated session setup
-and catalog discovery. Cancellation closes the process instead of sending a synthetic denial.
-
-Auth RPCs `provider.auth.start`, `complete`, `cancel`, `logout`, and `subscribe` require
-`orchestration:operate`. Install `start`, `cancel`, and `remove` use that scope too.
-`provider.install.subscribe` and public provider snapshots require `orchestration:read`.
-[`providerSetup.ts`][provider-setup] defines the operation IDs, states, and safe errors.
-
-Sign-out closes process admission for the instance, stops provider bindings through
-[`ProviderAuthService`][provider-auth-service], then stops owned startup and helper processes.
-A fresh official process calls `initialize` and native `logout` without authenticating.
-Only then does the provider clear auth, models, commands, skills, and workspace metadata.
-Thread history and native session files remain. Settings sign-out and a text-only `/logout`
-use this same path. The command is handled before model prompting or title generation.
-Disabling an instance closes its processes but keeps credentials. Account replacement is
-explicit sign-out followed by sign-in.
-
-### Sessions, models, and client capabilities
-
-[`AntigravityAdapter`][antigravity-adapter] owns one ACP process per active thread. It uses
-native `session/resume` without transcript replay and reapplies the persisted model and
-permission mode after new or resumed setup. An unavailable explicit model fails instead of
-accepting the native default. Steering cancels the previous prompt, waits for its result and
-event drain, then sends the replacement. Native background commands use T3's existing
-background-task state.
-
-The permission mapping is `approval-required` and `auto` to `default`, `auto-accept-edits` to
-`auto_edit`, and `full-access` to `yolo`. Native requests still need replies in `yolo`.
-`interaction_` requests are user questions, not approvals. T3 keeps opaque option IDs in
-`UserInputQuestion.options[].value` and sets `allowCustomAnswer=false`. Both clients preserve
-these values. Ordinary approval replies use only offered option IDs, including `allow_always`
-only when present. Existing providers keep their prior behavior when the optional fields are
-absent.
-
-`showInteractionModeToggle=false` keeps native `/plan` separate from T3 Plan mode.
-`supportsConversationRollback=false` hides unsupported client actions and makes checkpoint
-revert fail before filesystem changes. Checkpoint capture and diffs remain supported.
-
-Automatic status refreshes, reconnects, and workspace checks do not open catalog sessions.
-Health probes use `initialize` only. Disabled instances do not run background probes.
-An explicit `serverRefreshProviders` request with `refreshModels: true` calls the driver's
-optional `refreshModels` operation. Antigravity opens a short-lived catalog session under the
-instance's process admission guard, uses saved credentials, publishes models and commands,
-then closes the process. An interactive login request fails with sign-in required. Web's
-**Refresh provider status** and mobile's **Refresh models** actions request this operation.
-Account access starts unknown and becomes authenticated after successful session setup,
-including an explicit model refresh.
-The [provider snapshot][antigravity-provider] takes models and commands from setup and native
-updates. It preserves returned Gemini model IDs, labels, order, and thinking-level choices.
-ACP `config_option_update` notifications and `session/set_config_option` responses replace
-the instance's model catalog. Child session notifications do not change the root catalog.
-The registry treats a successful empty catalog as authoritative and clears cached metadata
-after sign-out. It must not retain a previous account's models. Cached models do not prove
-current access. The auth response does not supply an email, plan tier, or reliable quota.
-
-Some upstream failures arrive as assistant text followed by `end_turn`. Preserve that message
-without treating model-written text as a structured error or successful task completion.
-
-### Text generation
-
-[`AntigravityTextGeneration`][antigravity-text] implements titles, branch names, commit text,
-and PR text through the same instance and Google sign-in. Each helper uses a temporary empty
-workspace, no injected MCP servers, native `default` mode, and explicit denial of tools and
-questions. Output is bounded, parsed against the existing schemas, and sanitized. Cancellation,
-timeout, and sign-out close the process. Cleanup removes only that helper's verified temporary
-native session files.
-
-The official agent has no verified hard no-tools setting. Global hooks and MCP configuration
-can run before a prompt. Helpers check the profile's `config/hooks.json` and
-`config/mcp_config.json` before launch and reject nonempty, malformed, or oversized
-configuration. `supportsTextGeneration=false` keeps such an instance out of system-model
-pickers. Empty managed profiles are supported. Do not describe prompt-time denial as a native
-sandbox.
-
-## OpenCode server ownership and catalog
-
-Native OpenCode event logs skip text deltas and running tool snapshots. Pending, completed,
-and failed tool states remain, including final output and errors. This filter does not change
-events sent to clients or orchestration storage.
-
-Each OpenCode provider instance owns one lazy local server for catalog discovery and
-text-generation helpers through [`OpenCodeServerOwner.ts`][opencode-server-owner]. Concurrent
-borrowers share startup. The server closes 30 seconds after the last borrower releases it, or
-when the provider instance closes. A failed or exited process can be started again on the next
-use. An externally configured OpenCode server remains externally owned.
-
-The local server and its SDK clients use one resolved password. An explicit provider password
-overrides `OPENCODE_SERVER_PASSWORD` in the spawned environment. Without an explicit password,
-the client uses the password from the environment that the process inherits. External servers use
-only their explicit provider password and never inherit the host's local password.
-
-Every server connection must pass the authenticated `/global/health` check before inventory or
-session operations start. The response must contain a valid version at or above 1.14.19. Local
-owners cache this result for the lifetime of the spawned process. External actions check once when
-they create their server connection, not for each model or SDK request.
-
-Chat adapters keep their own server per thread. They register a thread-specific `t3-code` MCP
-connection, while OpenCode stores MCP connections by directory. Sharing these chat servers
-without changing MCP routing would let two threads in one directory replace each other's
-connection.
-
-Chat adapters send the runtime mode as a session ruleset, but upstream OpenCode evaluates
-doom-loop and subagent asks against the agent ruleset only. In full access the adapter answers
-those asks itself so the user never sees an approval they already granted. It replies `once`
-rather than `always` because OpenCode stores `always` grants per directory, and on a shared
-external server that would widen what a supervised thread in the same directory may do.
-
-OpenCode loads its catalog through the HTTP API when an enabled provider instance starts. The
-provider registry keeps the snapshot in memory and persists it in the existing per-instance cache.
-Each `subscribeServerConfig` connection refreshes all providers, so a client reconnect reloads the
-OpenCode catalog from the current helper. The `serverRefreshProviders` request also refreshes it.
-Periodic OpenCode probes remain disabled. OpenCode reads credentials for each inventory request,
-but its native configuration files can remain cached for the lifetime of the helper process. The
-helper closes 30 seconds after its last inventory or text-generation borrower releases it. A
-refresh after that idle period starts a new helper and reads file changes. Repeated refreshes and
-active text-generation work can extend process reuse. Changes to the provider configuration or
-environment replace the instance and start a new discovery. Changes to unrelated settings only
-update snapshot enrichment. Other providers retain their existing refresh policy.
-
-T3 Code does not own an external OpenCode process. Native configuration changes there can require
-an external reload or restart before T3 Code's next refresh sees them.
-
-The shared server's idle shutdown does not clear the catalog. Failed discovery keeps the last
-known models, slash commands, and skills through the registry's existing merge rules. A successful
-empty inventory is authoritative. Existing threads keep their explicit model identifier and
-options when catalog metadata is missing; the catalog is not permission to choose a different
-model for a thread.
-
-## Model manifest
-
-The model picker's legacy section is driven by `apps/server/src/provider/model-manifest.json`, which
-lists the current (non-legacy) model slugs per driver kind. The `ModelManifest` service
-(`apps/server/src/provider/ModelManifest.ts`) refreshes that data from the same file on `main` via
-raw.githubusercontent.com, so moving a model in or out of the legacy section is a commit, not a
-release. Preference order is remote fetch, then the on-disk copy of the last successful fetch (in
-the state directory), then the bundled copy. Fetches are TTL-gated, run concurrently with provider
-probes, respect the `enableProviderUpdateChecks` setting, and never fail a provider check. The
-Codex and Claude drivers apply the classification to every snapshot with `applyModelManifest`;
-driver kinds absent from the manifest have no legacy concept.
-
-## Attachment access
-
-The server stores uploaded attachments in its attachment directory, outside the project workspace.
-`ProviderService` adds the absolute path of each attachment to the turn text, then passes every
-attachment to the provider adapter. Each adapter decides what its provider ingests natively:
-
-- Codex, Claude, Cursor, and Grok send images as native image inputs and skip generic files. For
-  these providers, generic files reach the agent only as file paths in the turn text.
-- Antigravity sends BMP, JPEG, PNG, and WebP images and common audio formats as native blocks,
-  text files as embedded resources, and PDFs as resource links. Other files are rejected with an
-  error instead of being dropped. The session advertises the ACP client file system capability,
-  so workspace reads and writes come back through `fs/read_text_file` and `fs/write_text_file`
-  and are confined to the workspace and the attachments directory.
-- OpenCode sends PNG/JPEG/GIF/WebP images, text files, and PDFs up to 20 MB as native file parts
-  with their real mime type. Everything else (ZIP and other binaries, image formats model APIs
-  reject, oversized files) falls back to the file path in the turn text, like the other providers.
-- Antigravity sends BMP/JPEG/PNG/WebP images as native image blocks, UTF-8 text as embedded
-  resources, and PDFs as local resource links. Text is limited to 1 MiB per file, images to
-  10 MiB each, and all attachments to 50 MiB per turn. Unsupported formats or oversized inputs
-  fail explicitly. Native path permissions still apply to PDFs.
-
-Claude receives the attachment directory as an allowed additional directory. Codex keeps its
-configured sandbox policy, so access depends on that policy and the selected runtime mode. OpenCode
-allows all paths in full-access mode and requests approval for directories outside the workspace in
-restricted modes. Cursor and Grok use their own provider permission rules.
-
-The server does not copy attachments into a project or bypass provider approval rules. If an agent
-cannot read an attachment, the user must approve the access or select a runtime mode that permits it.
-
-Updated attachment schemas tolerate unknown attachment members, but old image-only clients still
-cannot decode messages that contain file attachments. Client file-picking rollouts must account for
-this limit.
-
-Do not run an old image-only server against state that contains file attachments. Replay decodes
-each persisted event before projection. A file-bearing event can make `ProjectionPipeline` bootstrap
-and `OrchestrationEngine` startup fail for the entire environment, not only the affected thread.
-
-## How provider work is requested
-
-Clients never call a provider directly. They dispatch orchestration commands over the RPC method
-`orchestration.dispatchCommand`, defined with the rest of the orchestration surface in
-[`orchestration.ts`][contracts]. The client-dispatchable provider-facing commands are
-`thread.turn.start`, `thread.turn.interrupt`, `thread.approval.respond`,
-`thread.user-input.respond`, `thread.checkpoint.revert`, and `thread.session.stop`, plus the mode
-setters `thread.runtime-mode.set` and `thread.interaction-mode.set`.
-
-The engine persists an event for the command, and a server-side reactor performs the provider call.
-Provider output comes back as internal commands such as `thread.message.assistant.delta` and
-`thread.session.set`, which clients observe through `orchestration.subscribeThread`. See
-[overview.md](./overview.md) for the command/event loop.
-
-## Server-side workers
-
-Provider work flows through three queue-backed workers. All three are built with
-`makeDrainableWorker` from [`DrainableWorker.ts`][worker] and expose `drain` for deterministic test
-synchronization.
-
-1. [`ProviderRuntimeIngestion`][ingest] consumes provider runtime streams and emits orchestration
-   commands.
-2. [`ProviderCommandReactor`][cmd] reacts to orchestration intent events and dispatches provider
-   calls.
-3. [`CheckpointReactor`][checkpoint] captures workspace checkpoints on turn start and completion, and
-   performs reverts.
-
-### Buffered assistant delivery
-
-A thread in `buffered` assistant delivery mode accumulates assistant text instead of streaming each
-delta. The buffer is not held until turn completion. In [`ProviderRuntimeIngestion`][ingest],
-`MAX_BUFFERED_ASSISTANT_CHARS` is 24,000: the append that would exceed it invalidates the buffer and
-spills the whole accumulated text as one delta. The buffer also flushes at interaction boundaries,
-when a request opens (approval) or user input is requested, via
-`flushBufferedAssistantMessagesForTurn`.
-
-[drivers]: ../../apps/server/src/provider/builtInDrivers.ts
-[codex]: ../../apps/server/src/provider/Drivers/CodexDriver.ts
-[claude]: ../../apps/server/src/provider/Drivers/ClaudeDriver.ts
-[cursor]: ../../apps/server/src/provider/Drivers/CursorDriver.ts
-[grok]: ../../apps/server/src/provider/Drivers/GrokDriver.ts
-[opencode]: ../../apps/server/src/provider/Drivers/OpenCodeDriver.ts
-[antigravity]: ../../apps/server/src/provider/Drivers/AntigravityDriver.ts
-[antigravity-adapter]: ../../apps/server/src/provider/Layers/AntigravityAdapter.ts
-[antigravity-provider]: ../../apps/server/src/provider/Layers/AntigravityProvider.ts
-[antigravity-installation]: ../../apps/server/src/provider/AntigravityInstallation.ts
-[antigravity-release]: ../../apps/server/src/provider/antigravityRelease.ts
-[antigravity-auth]: ../../apps/server/src/provider/AntigravityAuth.ts
-[antigravity-auth-support]: ../../apps/server/src/provider/antigravityAuthSupport.ts
-[antigravity-text]: ../../apps/server/src/textGeneration/AntigravityTextGeneration.ts
-[provider-auth-service]: ../../apps/server/src/provider/Layers/ProviderAuthService.ts
-[provider-setup]: ../../packages/contracts/src/providerSetup.ts
-[opencode-server-owner]: ../../apps/server/src/provider/OpenCodeServerOwner.ts
-[adapter]: ../../apps/server/src/provider/Services/ProviderAdapter.ts
-[instances]: ../../apps/server/src/provider/Services/ProviderInstanceRegistry.ts
-[registry]: ../../apps/server/src/provider/Services/ProviderAdapterRegistry.ts
-[service]: ../../apps/server/src/provider/Layers/ProviderService.ts
-[contracts]: ../../packages/contracts/src/orchestration.ts
-[worker]: ../../packages/shared/src/DrainableWorker.ts
-[ingest]: ../../apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
-[cmd]: ../../apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
-[checkpoint]: ../../apps/server/src/orchestration/Layers/CheckpointReactor.ts
+# Provider constraints
+
+Orchestration records intent and state without knowing which provider runs a thread. Provider
+protocols, account ownership, permissions, and capabilities belong at the
+[adapter boundary](../../apps/server/src/provider/Services/ProviderAdapter.ts). Normalize there
+instead of spreading provider checks through reactors and clients.
+
+A driver kind identifies an integration; an instance identifies one configuration and account
+lifecycle. Route work by instance, so two accounts using the same driver do not share mutable
+session or catalog state.
+
+## Process and account isolation
+
+T3-managed OpenCode chat uses one server per thread. Its MCP registrations are directory-scoped, while
+T3's MCP connection is thread-scoped. Sharing a chat server between threads in one directory would
+let them replace each other's connection. Catalog and text-generation work can share the
+[instance-owned helper](../../apps/server/src/provider/OpenCodeServerOwner.ts), which closes
+after an idle period. External OpenCode servers remain externally owned and can require an
+external restart to pick up configuration changes.
+
+OpenCode also stores persistent approval grants per directory. Automatic full-access replies use
+`once` so they cannot widen a supervised thread's permissions on a shared external server.
+See the [adapter](../../apps/server/src/provider/Layers/OpenCodeAdapter.ts).
+
+Antigravity separates account profiles per instance while sharing installed executables across the
+environment. It forces file-based credential storage because the native macOS keychain entry would
+otherwise be shared across instances. The launch environment removes ambient Google credentials,
+so an instance cannot silently use another account or billing project.
+See [profile isolation](../../apps/server/src/provider/antigravityAuthSupport.ts).
+
+The [Antigravity installer](../../apps/server/src/provider/AntigravityInstallation.ts) outlives
+client connections and provider-instance rebuilds. Releases are immutable, with an atomic pointer
+selecting the version for new processes. Running processes hold leases on their version. Updates
+and removal must respect those leases instead of replacing executables under a running agent.
+
+## Setup must not happen as a health-check side effect
+
+Opening a provider session can start MCP servers, run hooks, or launch a login browser.
+[Grok probes](../../apps/server/src/provider/Layers/GrokProvider.ts) avoid authentication and
+session creation for this reason. Antigravity likewise reserves authenticated catalog sessions for
+explicit setup or model refresh; background checks use initialization only.
+
+[Antigravity sign-in](../../apps/server/src/provider/AntigravityAuth.ts) belongs to the initiating
+T3 auth session. The client carries the return URL back to the environment because the provider's
+loopback listener may be on another machine. Forward only the callback for the owned pending flow;
+a successful callback HTTP request is not proof that provider authentication finished. The native
+process owns token exchange and storage.
+
+Antigravity sign-out closes admission to new processes and stops existing processes before clearing account
+metadata. Otherwise a helper or resumed session could retain the old account. Cached model lists
+do not establish current access, and an authoritative empty catalog must clear the old list.
+
+Antigravity text-generation helpers deny tool requests, but native hooks and MCP configuration can
+run before the prompt. They reject profiles with such configuration before launch. Prompt
+instructions and tool denial do not create a native sandbox.
+See [helper constraints](../../apps/server/src/textGeneration/AntigravityTextGeneration.ts).
+
+## Protocol traps
+
+Codex async questions arrive as notifications and are answered with a new user message. There is
+no pending RPC response to send. Blocking questions still use the request/response path. The
+[adapter](../../apps/server/src/provider/Layers/CodexAdapter.ts) distinguishes them; the
+[decider](../../apps/server/src/orchestration/decider.ts) records an async answer and its user
+message together.
+
+An async question can outlive the turn or a server restart. The engine reads that request's
+durable activity before resolving it because the in-memory command snapshot omits old activities.
+Do not infer that a request has disappeared merely because it is outside the recent window.
+
+Capabilities must describe what the provider can actually do. Antigravity can capture workspace
+checkpoints but cannot roll back its conversation. The [checkpoint boundary](./overview.md#turn-completion-and-checkpoints)
+therefore rejects revert before touching files. Native permission and question option IDs must
+also survive normalization; a display label is not necessarily a valid reply.
+
+## Attachments and stored history
+
+Attachments live outside the project workspace. [ProviderService](../../apps/server/src/provider/Layers/ProviderService.ts)
+puts their environment-local paths in turn input and lets adapters choose native input formats.
+A path in the prompt does not grant filesystem access. Keep provider sandbox and approval rules
+in force; copying uploads into the project to bypass them changes that boundary.
+
+File attachments introduced a replay compatibility limit. Image-only clients cannot decode
+file-bearing messages, and an image-only server can fail the entire environment's startup when
+replaying one such event. Rollouts and downgrades must account for persisted history as well as
+current client support.
+
+Model classification has its own [manifest constraints](./model-manifest.md). Assistant-reference
+handling is documented under [citations](./assistant-citations.md).
diff --git a/docs/internals/remote.md b/docs/internals/remote.md
index d27a0741c2ad..2faf1e930eef 100644
--- a/docs/internals/remote.md
+++ b/docs/internals/remote.md
@@ -1,256 +1,59 @@
-# Remote Architecture
-
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-Remote environments are shipped, not planned. Direct, bearer-paired, relay-tunneled, Tailscale, and
-desktop-managed SSH access all exist today. This document describes the model they share and where
-each piece lives. For the user-facing setup guide see
-[remote access](../user/remote-access.md).
-
-## The model
-
-T3 has one runtime boundary: a client talks to a T3 server over HTTP and WebSocket, and the server
-owns orchestration, providers, terminals, git, and filesystem operations. Remoteness is expressed at
-the connection layer, never by splitting the runtime.
-
-```text
-┌──────────────────────────────────────────────┐
-│ Client (desktop / mobile / web)              │
-│  known environments, connection supervisor   │
-└───────────────┬──────────────────────────────┘
-                │ resolves one access endpoint
-┌───────────────▼──────────────────────────────┐
-│ Access method                                │
-│  direct ws/wss, relay tunnel,                │
-│  Tailscale serve, desktop-managed ssh        │
-└───────────────┬──────────────────────────────┘
-                │ connects to one T3 server
-┌───────────────▼──────────────────────────────┐
-│ Execution environment = one T3 server        │
-│  identity, providers, projects/threads,      │
-│  terminals, git, filesystem                  │
-└──────────────────────────────────────────────┘
-```
-
-### ExecutionEnvironment
-
-One running T3 server instance. It owns provider availability and auth, model availability, projects
-and threads, terminal processes, filesystem access, git operations, and server settings.
-
-It is identified by a stable `environmentId`, persisted by the server at `<stateDir>/environment-id`
-and generated on first start (`apps/server/src/environment/ServerEnvironment.ts`). Desktop, mobile,
-and web all reason about the same concept.
-
-Initialization publishes a complete ID atomically. Empty or whitespace-only ID files are repaired
-using a retained `<stateDir>/environment-id.recovery` file so concurrent and delayed repairs choose
-the same ID. Existing nonempty ID files remain authoritative.
-
-### Known environments and connection targets
-
-A saved client-side entry for an environment the client knows how to reach. It is not
-server-authored; it is local to a device or client profile. In the hosted web app these entries are
-browser-local. A hosted pairing URL can create one, but it does not give the hosted app a server-side
-control plane or a copy of session state.
-
-[`connection/model.ts`][model] defines four target tags, which are the real access taxonomy:
-
-| Target                    | Used for                                                                 |
-| ------------------------- | ------------------------------------------------------------------------ |
-| `PrimaryConnectionTarget` | The platform-managed local server (desktop backend, CLI-served web app). |
-| `BearerConnectionTarget`  | Any manually paired endpoint reached over direct HTTP/WebSocket.         |
-| `RelayConnectionTarget`   | Managed T3 Connect relay tunnels.                                        |
-| `SshConnectionTarget`     | Desktop-managed SSH environments.                                        |
-
-Bearer, relay, and SSH are persisted; primary is platform-managed. Note that Tailscale is not a
-separate target kind. A Tailscale URL is paired through the ordinary bearer path in
-[`onboarding.ts`][onboarding] (`preparePairingRegistration`), which accepts either a pairing URL or a
-host plus pairing code. Tailscale is an endpoint provider and transport, not a distinct runtime
-concept.
-
-### AdvertisedEndpoint
-
-A server- or desktop-authored candidate endpoint for an environment: a concrete HTTP and WebSocket
-base URL pair, a default/available/unavailable marker, reachability hints (loopback, LAN, private,
-public, tunnel), and compatibility hints such as whether the hosted HTTPS app can use it.
-
-Clients treat advertised endpoints as hints, not proof that a route works from the current device.
-The connection attempt decides.
-
-The UI shows one default endpoint in the network-access summary and keeps the rest behind an advanced
-list. `selectPairingEndpoint` in
-[`ConnectionsSettings.tsx`](../../apps/web/src/components/settings/ConnectionsSettings.tsx) excludes
-unavailable endpoints and then picks, in order:
-
-1. the saved `defaultEndpointKey` override;
-2. the first endpoint marked `isDefault`;
-3. the first endpoint whose reachability is not `loopback`;
-4. the first endpoint compatible with the hosted HTTPS app;
-5. otherwise nothing.
-
-There is no unconditional loopback fallback. A loopback endpoint only wins through an explicit saved
-override or `isDefault`. Persist the override by stable endpoint kind rather than raw URL where
-possible, since LAN addresses change with networks; Tailscale endpoints use provider-specific stable
-keys (`tailscale-ip:`, `tailscale-magicdns:`).
-
-### Endpoint providers
-
-Endpoint providers contribute advertised endpoints without becoming part of the core environment
-model: core owns environments, pairing, and connection lifecycle, and providers return normalized
-`AdvertisedEndpoint` records.
-
-Tailscale is the first provider, and T3 manages more than discovery. When `tailscaleServeEnabled` is
-set, the server acquires a Tailscale serve mapping for its actual listening port at startup with
-`ensureTailscaleServe` and releases it with `disableTailscaleServe` on scope close
-(`apps/server/src/server.ts`, using [`@t3tools/tailscale`](../../packages/tailscale/src/tailscale.ts)).
-Endpoint identifiers are synthesized in `apps/desktop/src/backend/tailscaleEndpointProvider.ts` with
-`private-network` reachability.
-
-### Hosted pairing request
-
-A hosted pairing request is a bootstrap URL for the static web app, not a transport:
-
-```text
-https://app.t3.codes/pair?host=https://backend.example.com:3773#token=PAIRCODE
-```
-
-The hosted app reads `host`, takes the token from the URL hash, exchanges it directly with that
-backend, strips the token from browser history, and saves the environment record locally. Helpers
-live in [`shared/remote.ts`](../../packages/shared/src/remote.ts) (`setPairingTokenOnUrl`,
-`getPairingTokenFromUrl`, `stripPairingTokenFromUrl`) and `apps/web/src/hostedPairing.ts`.
-
-Constraints:
-
-- the hosted app does not proxy HTTP or WebSocket traffic;
-- the backend must be directly reachable from the browser;
-- HTTPS pages can only reach HTTPS/WSS backends;
-- HTTP LAN endpoints keep using direct desktop or CLI pairing URLs;
-- the token belongs in the hash so it is never sent to the hosted app origin.
-
-### RepositoryIdentity and Project
-
-`RepositoryIdentity` is a best-effort logical repo grouping across environments, used for UI grouping
-and correlation only, never for routing. `Project` remains environment-local: a local clone and a
-remote clone are different projects that may share a `RepositoryIdentity`, and threads bind to one
-project in one environment.
-
-## Access methods
-
-Access answers one question: how does the client speak WebSocket to a T3 server? It does not answer
-how the server got started or who manages the process.
-
-### Direct WebSocket access
-
-`wss://t3.example.com` or `ws://10.0.0.15:3773`, paired as a bearer target. This is the base model.
-It works for desktop, mobile, and web with no client-side process management. Browser security rules
-are part of it: a hosted HTTPS client cannot connect to plain `ws://` or `http://` LAN backends.
-
-### Relay-tunneled access
-
-Managed T3 Connect relay tunnels use `RelayConnectionTarget` and are the answer when the host is
-behind NAT, inbound ports are unavailable, or mobile must reach a desktop-hosted environment. From
-the client's perspective this is still an ordinary WebSocket connection; the route is mediated. The
-relay Worker only brokers credentials and a managed endpoint; application traffic then flows over
-the provisioned Cloudflare tunnel hostname for the life of the connection, not through the relay
-Worker itself. See [t3-connect.md](./t3-connect.md).
-
-### Tailscale access
-
-A T3-managed `tailscale serve` mapping exposes the server on the tailnet over HTTPS, and the
-resulting private-network endpoints are advertised for pairing. Connection then follows the ordinary
-bearer path.
-
-### Desktop-managed SSH access
-
-SSH is an access and launch helper, not a separate environment type. `DesktopSshEnvironment`
-([apps/desktop/src/ssh/DesktopSshEnvironment.ts][sshenv]) exposes `discoverHosts`,
-`ensureEnvironment`, and `disconnectEnvironment`. It discovers targets from SSH config and known
-hosts, owns password/askpass prompts, and delegates lifecycle to `SshEnvironmentManager` in
-[packages/ssh/src/tunnel.ts][sshtunnel], which resolves the target, launches or reuses the remote T3
-server, opens a local tunnel, checks HTTP readiness, optionally issues a remote pairing token, and
-returns local HTTP/WS endpoints. Disconnect closes the tunnel and stops the remote server if the
-launcher started it; a server that was already running (marked `external`) is left running.
-
-The desktop main process owns this because it can spawn SSH, manage prompts, write launch scripts,
-and clean up forwards. The renderer connects through the forwarded URL like any other environment and
-needs no SSH-specific RPC path.
-
-Failure handling is explicit: SSH auth failure surfaces before an environment is saved, remote launch
-failure includes launcher output where available, forwarded-port failure leaves the environment
-disconnected rather than falling back to an unrelated endpoint, and reconnect restores the SSH bridge
-before reconnecting the WebSocket client.
-
-## Launch methods
-
-Launch answers a different question: how does a T3 server come to exist on the target machine? Keep
-it separate from access.
-
-- **Pre-existing server.** The operator already runs T3 and the client connects directly or through a
-  tunnel.
-- **Desktop-managed remote launch over SSH.** Desktop probes the machine, launches or reuses a remote
-  server, forwards a port, and the renderer connects normally. The saved environment records that it
-  came from SSH launch for reconnect and lifecycle UX only; that metadata never changes the protocol
-  or the identity model.
-- **Client-managed local publish.** A local server is published through the relay with
-  `t3 connect link`, exposing a desktop-hosted environment to mobile without router or firewall
-  changes.
-
-The same `ExecutionEnvironment` can be reached several of these ways. Only the launch and access
-paths differ.
-
-## Security model
-
-Some environments are reachable over untrusted networks, so remote-capable environments require
-explicit authentication, tunnel exposure never relies on obscurity, and saved endpoints carry enough
-auth metadata to reconnect safely.
-
-WebSocket authentication is a dedicated short-lived ticket, not a token in a query string. The client
-presents its long-lived bearer or DPoP credential in HTTP headers to
-`POST /api/auth/websocket-ticket` ([authorization/remote.ts][authremote]), and appends only the
-returned ticket as `wsTicket` on the socket URL. The server issues it through
-`EnvironmentAuth.issueWebSocketTicket`; tickets are tagged `kind: "websocket"` and default to a
-five-minute TTL (`DEFAULT_WEBSOCKET_TOKEN_TTL` in `apps/server/src/auth/SessionStore.ts`). The
-handshake verifies the ticket, and each RPC method still enforces its own scope. See
-[environment-auth.md](./environment-auth.md).
-
-Hosted pairing is a client-side convenience only. The hosted app must not receive pairing tokens
-through query parameters, must not store pairing state server-side, and must not imply that an HTTP
-backend is reachable from an HTTPS browser context.
-
-## Version coordination
-
-Remote environments stay online while clients move to newer releases. The environment descriptor
-carries the running server version and may advertise a safe replacement path, so the UI can show the
-right action without making the transport responsible for process management. The connection
-supervisor owns the resulting disconnect and reconnect like any other involuntary close. See
-[server-updates.md](./server-updates.md).
-
-## Machine identity
-
-Every environment is drawn with one of a fixed set of machine glyphs (`EnvironmentMachineKind` in
-contracts: server, cloud, desktop, laptop, mac-mini, mac-studio). Two inputs feed it, and the
-precedence lives in one helper, `resolveEnvironmentMachineKind`, so web and mobile cannot drift:
-
-1. `settings.environmentIcon`, a nullable server setting the user picks in Settings → Connections.
-   It is server state rather than client state so every device connecting to that server agrees.
-2. `environment.platform.machine`, detected once at startup by [ServerEnvironmentMachine.ts][machine]
-   (IOKit product name / `hw.model` on macOS, `/sys/class/dmi/id` on Linux with virtualization
-   markers mapped to "cloud"). Absent when there is no signal, so older servers, Windows hosts, and
-   containers decode without it.
-3. A generic server otherwise.
-
-Clients treat the field like any other capability: absent means "use the fallback", never "wait".
-
-## Future work
-
-These remain unbuilt and are listed to keep the model honest:
-
-- third-party tunnel products as additional endpoint providers;
-- a relay-hosted OAuth callback broker (see [t3-connect.md](./t3-connect.md));
-- richer multi-environment UI beyond the current connections list.
-
-[model]: ../../packages/client-runtime/src/connection/model.ts
-[onboarding]: ../../packages/client-runtime/src/connection/onboarding.ts
-[authremote]: ../../packages/client-runtime/src/authorization/remote.ts
-[sshenv]: ../../apps/desktop/src/ssh/DesktopSshEnvironment.ts
-[sshtunnel]: ../../packages/ssh/src/tunnel.ts
-[machine]: ../../apps/server/src/environment/ServerEnvironmentMachine.ts
+# Remote architecture
+
+Each connection joins a client to one environment over HTTP and WebSocket. The
+environment owns providers, execution, files, and durable state. Direct access,
+Tailscale, SSH, and T3 Connect change how the client reaches that server; they do
+not introduce another execution model. See
+[remote access](../user/remote-access.md) for setup.
+
+## Identity is independent of the route
+
+An environment keeps its ID across server restarts and endpoint changes. Saved
+connections are local to a client profile; the server's identity and state are
+not. A repository identity can correlate clones across environments, but never
+routes work between them. A project and its threads belong to one environment.
+
+[Environment ID initialization](../../apps/server/src/environment/ServerEnvironment.ts)
+must publish a complete ID atomically. Repair of an empty ID file retains a
+recovery file so concurrent or delayed initializers choose the same winner.
+Removing that recovery state as ordinary temporary-file cleanup can change the
+identity underneath an already-running server.
+
+Advertised endpoints are reachability hints. Only the connecting device can
+prove that a route works. In particular, a host's loopback address refers to a
+different machine when another device opens it. Endpoint selection must not
+silently fall back to loopback when a shareable endpoint is unavailable.
+
+## Hosted web is a client
+
+The hosted web app stores its connection catalog in the browser and connects
+directly to each environment. It does not proxy traffic or hold server-side
+pairing state. Hosting the UI over HTTPS therefore cannot make a plain HTTP LAN
+backend accessible from that browser context.
+
+A [hosted pairing URL](../../apps/web/src/hostedPairing.ts) identifies the backend
+in its query and carries the pairing secret in its fragment. Fragments stay out
+of requests to the hosted origin. The browser exchanges the secret with the
+environment and strips it from its history. Moving the token into a query
+parameter would disclose it to the wrong origin.
+
+## Access and process ownership are different
+
+Tailscale supplies an endpoint for ordinary pairing, so it needs no separate
+environment type. Authentication remains the environment's responsibility for
+every route. See [environment authentication](./environment-auth.md) and the
+[T3 Connect trust boundary](./t3-connect.md).
+
+SSH can launch a server as well as forward a port. Desktop main owns that
+lifecycle because it can spawn SSH and handle authentication prompts. The
+renderer uses the forwarded endpoint through the shared connection runtime.
+[SSH cleanup](../../packages/ssh/src/tunnel.ts) stops a remote server only if the
+launcher owns it; a server it discovered already running must survive a client
+disconnect. Reconnection restores the forward before opening the application
+transport.
+
+Remote servers can outlive several client releases. Clients must use advertised
+capabilities and handle their absence, rather than assume their own version
+describes the server. Process replacement belongs to the launcher's
+[update protocol](./server-updates.md); the connection runtime handles the
+resulting disconnect.
diff --git a/docs/internals/resource-telemetry.md b/docs/internals/resource-telemetry.md
index 0f3e6674ff79..3ce3a6071948 100644
--- a/docs/internals/resource-telemetry.md
+++ b/docs/internals/resource-telemetry.md
@@ -1,394 +1,50 @@
-# Resource telemetry architecture
-
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-Status: implemented
-
-## Purpose
-
-Resource telemetry replaces recurring `ps`, PowerShell, `ioreg`, and `pmset`
-subprocess probes with two persistent, direct data sources:
-
-1. a standalone Rust resource-monitor executable that reads process counters
-   through operating-system APIs via `sysinfo`;
-2. Electron main-process APIs for Electron process metrics and host power state.
-
-The native monitor owns bounded in-memory history. The server only merges and
-summarizes that history when diagnostics requests it. Telemetry history is not
-persisted to disk or continuously copied into Node.
-
-## Why a standalone executable
-
-The monitor is intentionally not a Node native addon.
-
-- No N-API, `ffi-rs`, or dynamic-library ABI is loaded into the server process.
-- A monitor crash cannot corrupt the Node runtime.
-- The server can supervise, restart, version-check, and measure the monitor as a
-  normal child process.
-- The same protocol works for the desktop app and the published CLI.
-- Packaging is a single platform executable instead of an addon toolchain plus
-  Node/Electron ABI matrix.
-
-The cost is one persistent child process and NDJSON serialization. That is a
-better failure boundary than repeatedly spawning shell utilities or loading
-native code into Node.
-
-## Runtime topology
-
-### Desktop
-
-```text
-Electron main
-  ├─ powerMonitor
-  ├─ app.getAppMetrics() while diagnostics is open
-  ├─ inherited fd 4, telemetry NDJSON ─────────────┐
-  └─ inherited fd 5, demand-control NDJSON ◀──────┤
-                                                   ▼
-Node server ── stdin/stdout NDJSON ── Rust resource monitor
-     │
-     ├─ ResourceTelemetry Effect service
-     ├─ background power policy projection
-     └─ WebSocket RPC/subscription ── diagnostics UI
-```
-
-### Web, headless, and remote server
-
-Electron telemetry is unavailable. The native monitor still runs beside the
-server and tracks the server process tree. Power fields degrade to `unknown`
-instead of invoking platform shell commands.
-
-### WSL backend limitation
-
-Windows desktop packages currently ship the Windows resource-monitor executable.
-That executable cannot run inside the Linux WSL backend, so a WSL-only backend
-does not receive `resourceMonitorPath` and reports native process telemetry as
-unavailable. Electron host-power telemetry remains available over the inherited
-desktop pipe. Supporting native WSL process telemetry requires publishing a
-Linux sidecar for each supported architecture in the Windows artifact and
-converting its packaged path into the selected distro; the configuration
-deliberately does not pass the Windows `.exe` into WSL as a false fallback.
-
-## Native monitor
-
-The executable lives in `native/resource-monitor`.
-
-It receives schema-compatible commands on stdin and emits one JSON object per
-line on stdout:
-
-- `configure`
-- `setExternalProcesses`
-- `setSampleInterval`
-- `setStreaming`
-- `sampleNow`
-- `readHistory`
-- `shutdown`
-- `hello`
-- `snapshot`
-- `historyChunk`
-- `error`
-
-The protocol version is defined by
-`RESOURCE_MONITOR_PROTOCOL_VERSION` in
-`packages/contracts/src/resourceTelemetry.ts`.
-
-### Collection
-
-The monitor keeps one `sysinfo::System` instance and refreshes it at the
-power-adaptive interval selected by the server. It collects:
-
-- PID and parent PID;
-- process start time and run time;
-- process name and command line;
-- current and cumulative CPU usage;
-- resident and virtual memory;
-- cumulative process I/O counters.
-
-On Linux, task/thread enumeration is disabled. Command lines are refreshed with
-each sample so process replacements remain visible. Disabling task enumeration
-avoids walking every `/proc/<pid>/task/<tid>` directory on each refresh.
-
-### Process-tree selection
-
-Each sample scans the accessible process table, builds the PID/PPID graph, and
-retains:
-
-- the server process;
-- every descendant of the server, including provider-spawned grandchildren such
-  as shells, `node`, `tsgo`, language servers, and other tools;
-- Electron processes supplied as explicit external roots;
-- descendants of those Electron roots;
-- the resource monitor itself, because it is a server child.
-
-Process identity is `(pid, startTimeMs)`, not PID alone. Electron and native
-start times are matched with a two-second tolerance because native start times
-can have coarser platform resolution.
-
-The process list is emitted in depth-first tree order so renderer collapse and
-expansion preserves complete subtrees.
-
-### Native history and streaming
-
-Every native sample is appended to a one-hour in-memory ring bounded to 3,600
-snapshots, 20,000 retained process rows, and 64 MiB of retained history bytes.
-History stays in the sidecar until a `readHistory` request and is returned in
-bounded chunks. The first bound reached wins, so high process counts or large
-process names and command lines shorten the effective history window.
-
-Periodic snapshot streaming is disabled by default. The server enables it only
-while at least one diagnostics subscription is retained. `sampleNow` remains
-available for explicit refreshes and identity validation.
-
-The server adjusts native sampling without restarting the sidecar:
-
-- suspended, locked, low-power, or serious/critical thermal state: 15 seconds;
-- battery: 5 seconds;
-- normal AC: 5 seconds in the background and 1 second while live diagnostics is
-  open;
-- unknown or stale power: 5 seconds in the background and 1 second while live
-  diagnostics is open.
-
-### Sampling limits
-
-This is counter sampling, not syscall tracing.
-
-- A process that starts and exits entirely between samples may not be observed.
-- Cumulative CPU and I/O counters still provide accurate deltas for processes
-  that survive across samples.
-- Exact file paths, individual write syscalls, ETW events, eBPF events, and
-  Endpoint Security events are outside this implementation.
-
-Those deeper tracing systems can be added later as opt-in diagnostic modes
-without changing the public `ResourceTelemetry` model.
-
-## I/O semantics
-
-The monitor preserves platform semantics instead of presenting all counters as
-equivalent:
-
-- Unix-like platforms report storage I/O counters exposed by `sysinfo`.
-- Windows reports all process I/O bytes, not only disk bytes.
-- Operating-system caches can prevent logical application reads or writes from
-  appearing as physical storage bytes.
-
-The UI therefore labels these values as I/O reads and writes and exposes the
-per-process `ioSemantics` value.
-
-Group totals are observed deltas since telemetry startup. Per-process total
-columns are the operating system's cumulative counters for that process.
-
-## Electron telemetry
-
-Electron main owns `DesktopTelemetryPublisher`.
-
-Power events trigger an immediate snapshot. While diagnostics is closed, the
-server sends the configured active and idle host-power intervals to Electron
-(30 seconds and 2 minutes in the balanced profile). During those heartbeats
-Electron reads:
-
-- `powerMonitor.isOnBatteryPower()`;
-- `powerMonitor.getSystemIdleTime()`;
-- `powerMonitor.getSystemIdleState()`;
-- `powerMonitor.getCurrentThermalState()`.
-
-`app.getAppMetrics()` is only called while diagnostics demand is active. Its
-live cadence is 1 second on AC, 5 seconds on battery, and 15 seconds while
-locked, suspended, or thermally constrained.
-
-It also listens for:
-
-- lock and unlock;
-- suspend and resume;
-- AC and battery transitions;
-- thermal-state changes;
-- CPU speed-limit changes.
-
-Suspension stays latched across event-driven snapshots. An explicit resume
-clears it immediately; a periodic heartbeat also clears a stale latch so a
-missed resume event cannot leave telemetry permanently constrained.
-
-Electron does not expose a cross-platform low-power-mode getter, so that field
-remains `unknown`.
-
-The desktop backend is spawned with:
-
-- fd 3 for the existing bootstrap payload;
-- fd 4 for Electron-to-server telemetry NDJSON;
-- fd 5 for server-to-Electron diagnostics-demand NDJSON.
-
-These are private Electron-main/server pipes. They do not use the renderer
-WebSocket and are recreated for every backend restart.
-
-## Server Effect services
-
-The implementation is under `apps/server/src/resourceTelemetry`.
-
-### `ResourceMonitorBinary`
-
-Resolves an executable from:
-
-1. `T3CODE_RESOURCE_MONITOR_PATH`;
-2. desktop bootstrap configuration;
-3. bundled CLI resources;
-4. local Cargo build outputs.
-
-Unsupported platforms, missing binaries, and non-executable binaries use
-schema-backed tagged errors with descriptive messages.
-
-### `NativeTelemetryClient`
-
-Owns the resource-monitor process and protocol.
-
-- validates the hello/version handshake;
-- sends configuration and external process roots;
-- adapts the native interval from host power state;
-- enables streaming only for scoped live subscribers;
-- reads chunked native history on demand;
-- exposes `sampleNow`;
-- serializes commands;
-- supervises process exit and protocol failure;
-- restarts with bounded exponential backoff;
-- opens a circuit after repeated failures;
-- supports explicit retry;
-- publishes health changes immediately.
-
-Snapshot sequence numbers are scoped to a monitor generation. Server ingestion
-uses the monitor restart count as the generation key, so sequence reset after a
-restart cannot freeze telemetry.
-
-### `DesktopTelemetryReceiver`
-
-Reads fd 4, decodes schema-validated messages, stores the latest Electron
-snapshot, and publishes desktop health. It writes diagnostics demand to fd 5
-and gives the first sample a 90-second startup deadline. Once samples arrive,
-the stale deadline stays beyond the slower configured host-power interval with
-30 seconds of scheduling grace, so intentional 2–10 minute idle polling does
-not oscillate the policy between constrained and unconstrained states. Decode
-errors, protocol mismatch, control-write failure, stream failure, stale input,
-and normal stream closure are represented explicitly.
-
-### `ResourceTelemetry`
-
-Merges native and Electron data and owns public telemetry semantics.
-
-- calculates CPU and I/O rates from cumulative native counters;
-- preserves the last native rates during desktop-only updates;
-- classifies backend, Electron, and monitor processes;
-- computes process depth and child relationships;
-- tracks starts, exits, CPU time, and observed I/O;
-- projects power data;
-- acquires native streaming and Electron process metrics only for scoped live
-  subscribers;
-- queries and replays native history only when requested;
-- validates `(pid, startTimeMs)` before process signaling;
-- updates history health even when no further native sample arrives.
-
-Electron and monitor processes are visible but are not valid targets for the
-existing process-signal RPC.
-
-### History projection
-
-`ResourceTelemetryHistory` is a pure on-demand projection. It replays raw native
-snapshots to derive rates, lifecycle counters, buckets, and process summaries.
-Current Electron process metrics are intentionally excluded from historical
-replay so they cannot overwrite older native CPU or memory samples.
-
-### `ResourceAttribution`
-
-Tracks known logical application I/O separately from OS counters. Current
-integration points record successful writes for:
-
-- provider native and canonical event logs;
-- the local server trace sink.
-
-Entries contain component, operation, logical bytes, count, and elapsed time.
-Future persistence paths should call `ResourceAttribution.record` rather than
-adding diagnostics-specific counters.
-
-## Background policy integration
-
-`HostPowerMonitor` consumes `DesktopTelemetryReceiver` directly; observing host
-power does not retain live resource diagnostics or invoke shell probes.
-
-The monitor updates its latest timestamp on every Electron sample but only
-publishes semantic state changes. Increasing idle seconds alone does not cause a
-background-policy broadcast every second.
-
-## Public API and UI
-
-The WebSocket RPC surface provides:
-
-- current snapshot;
-- bounded history;
-- explicit monitor retry;
-- a live snapshot subscription.
-
-The diagnostics page displays:
-
-- aggregate CPU, memory, I/O, and process counts;
-- backend, Electron, and monitor overhead groups;
-- power and thermal state;
-- collector health and restart information;
-- CPU and I/O history;
-- a collapsible live process tree;
-- safe process signaling for backend descendants;
-- instrumented logical application I/O.
-
-Legacy process diagnostics RPCs are projected from the same service so they no
-longer start recurring process-table commands.
-
-## Packaging
-
-Desktop artifact builds compile the Rust target, stage it as
-`resources/resource-monitor/t3-resource-monitor[.exe]`, and pass its path to the
-backend bootstrap.
-
-CLI release jobs upload each active platform monitor artifact and copy it into:
-
-```text
-apps/server/dist/resource-monitor/<platform>-<arch>/
-```
-
-The published server package already includes `dist`, so those executables ship
-with the CLI. Missing platform artifacts degrade native telemetry to
-`unavailable`; the server continues running.
-
-## Resource and failure behavior
-
-Steady state uses:
-
-- one native process;
-- power-adaptive native counter sampling with no periodic Node snapshot stream;
-- event-driven Electron power updates plus profile-driven heartbeats (30–60
-  seconds while active and 2–10 minutes while idle);
-- no `app.getAppMetrics()` calls while diagnostics is closed;
-- no telemetry database;
-- no recurring shell probes;
-- bounded PubSub queues and native ring history.
-
-The diagnostics page exposes the monitor's own process resource usage and
-collection duration so the observer's cost is measurable.
-
-Failures are isolated:
-
-- native failure does not stop the server;
-- Electron telemetry loss does not stop native telemetry;
-- schema/version errors are visible in health;
-- repeated native failures stop automatic restart churn until explicit retry;
-- server and desktop shutdown close their respective streams and child process
-  scopes.
-
-## Future integration points
-
-High-value follow-up work can use the existing service boundaries:
-
-- opt-in file-path attribution through platform-specific tracing;
-- process lifecycle events to reduce the chance of missing very short-lived
-  children;
-- additional `ResourceAttribution` instrumentation for databases, checkpoints,
-  caches, and file synchronization;
-- exported diagnostic bundles;
-- adaptive sample intervals based on diagnostics visibility and active work.
-
-These additions should preserve the current rules: direct platform APIs,
-schema-validated boundaries, explicit metric semantics, bounded retention, and
-no mandatory telemetry persistence.
+# Resource telemetry
+
+Process counters come from a [standalone Rust monitor](../../native/resource-monitor/src/main.rs)
+using `sysinfo`. Electron main supplies host power and Electron process metrics.
+Keeping native collection outside Node isolates collector crashes and avoids a
+Node/Electron addon ABI matrix. Desktop and CLI servers use the same child-process
+protocol. A missing or failed collector leaves the server running.
+
+## Collection cost
+
+The native child owns sampling and bounded in-memory history. The server requests
+continuous snapshots only while diagnostics has live subscribers and fetches
+history on demand. Consuming host power for background scheduling must not retain
+live diagnostics. There is no telemetry database or recurring shell-probe fallback.
+
+History has independent bounds for age, snapshot count, process rows, and retained
+bytes. A count limit alone cannot bound memory when command lines vary in size.
+Large process trees therefore shorten the available history window. Linux task
+enumeration is disabled because walking every `/proc/<pid>/task/<tid>` directory
+makes sampling itself expensive.
+
+Electron power updates travel over private inherited pipes, independent of the
+renderer connection. Power events and slow heartbeats continue with diagnostics
+closed; `app.getAppMetrics()` runs only on live demand. The receiver's stale deadline
+must exceed the slowest configured heartbeat plus scheduling grace, or intentional
+idle polling makes background policy oscillate between constrained and
+unconstrained states. Headless servers leave unavailable power data unknown.
+
+## Measurement traps
+
+- Process identity includes start time because operating systems reuse PIDs.
+  Electron and native start times have different precision, so merging allows a
+  small tolerance. Process signaling rechecks the native identity with a fresh
+  sample.
+- Snapshot sequence numbers belong to a monitor generation. Comparing them across
+  restarts would discard the new monitor's samples until its sequence caught up.
+- Sampling can miss a process that starts and exits between samples. Cumulative
+  counters still yield deltas for processes observed across samples.
+- Windows process I/O includes more than disk traffic. Unix counters report storage
+  I/O, which can differ from logical application reads and writes because of OS
+  caching. Keep instrumented logical I/O separate from these counters.
+- Group totals accumulate observed deltas since telemetry started. Per-process
+  cumulative counters cover the operating system's lifetime for that process.
+- Historical replay uses native samples without current Electron CPU or memory
+  metrics. Merging the latest Electron values would overwrite the past.
+
+A WSL backend needs a Linux monitor even though Electron runs on Windows. Windows
+desktop packages currently supply only the Windows executable, so native process
+telemetry for the WSL backend is unavailable. The inherited Electron power feed
+still works.
diff --git a/docs/internals/scripts.md b/docs/internals/scripts.md
deleted file mode 100644
index 3f8c58601e7f..000000000000
--- a/docs/internals/scripts.md
+++ /dev/null
@@ -1,215 +0,0 @@
-# Scripts
-
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-## First checkout
-
-T3 Code uses [Vite+](https://viteplus.dev/guide/). Install the global `vp` command, install
-dependencies, then start the dev stack:
-
-```bash
-curl -fsSL https://vite.plus | bash   # Windows: irm https://vite.plus/ps1 | iex
-vp i
-vp run dev
-```
-
-Node 24 is required. Bun is not: the server picks Bun adapters when it detects Bun and falls back to
-Node otherwise, and nothing in contributor setup needs it.
-
-`vp run dev` prints a one-time pairing URL. Open it so the first browser navigation is
-authenticated.
-
-## Dev
-
-- `vp run dev`: Starts contracts, server, and web in watch mode.
-- `vp run dev --share`: Also publishes the web port over HTTPS on this machine's tailnet. The
-  startup pairing URL is built against the shared origin, and the mapping is removed on exit.
-  Shared runs default to Vite's bundled dev mode (`T3CODE_BUNDLED_DEV=1`): a remote browser pays a
-  network round trip per import level in unbundled dev, which turns a cold module graph into
-  minutes of waterfall. Set `T3CODE_BUNDLED_DEV=0` to opt a shared run back out.
-  The web entry loads the app with a dynamic import so React refresh starts before shared UI
-  chunks run. Keep app imports out of that entry. A static import can work on the first load
-  and then fail on reload after Vite splits code for lazy routes.
-  Bundled dev uses Tailwind's watched files to rebuild CSS. Its Vite-only hot-update hook is
-  disabled in this mode because Rolldown does not supply the Vite server or module graph.
-- `vp run dev --browser`: Auto-opens a browser. Off by default. The dev runner writes
-  `T3CODE_NO_BROWSER` itself from this flag, so setting `T3CODE_NO_BROWSER=0` in your environment has
-  no effect; use `--browser`.
-- `vp run dev:server`: Starts just the server. It runs on Node (`node --watch src/bin.ts`), so
-  without Bun present it selects `NodePtyAdapter` and `NodeHttpServer`.
-- `vp run dev:web`: Starts just the Vite dev server for the web app.
-- `vp run dev:desktop`: Starts the Electron shell against the dev server.
-- `vp run dev:marketing`: Starts the Astro marketing site.
-- Pass dev-runner flags directly after the root task name, for example:
-  `vp run dev --home-dir /tmp/t3code-dev`
-
-### Dev state directories
-
-- Dev commands run from a linked **git worktree** default to that worktree's gitignored `.t3`, even
-  when `T3CODE_HOME` is set, storing state in `<worktree>/.t3/userdata`. Pass `--home-dir <path>` to
-  choose another isolated directory explicitly. Submodules are not worktrees and keep the normal
-  precedence.
-- From the **main checkout**, dev commands implicitly use `~/.t3/dev`, keeping development state
-  separate from `~/.t3/userdata`. An explicit `--home-dir <path>` stores state under
-  `<path>/userdata`; the base directory remains available for caches, worktrees, and other shared
-  data.
-
-## Build, check, test
-
-- `vp run build`: Fans out over `apps/*`, `packages/*`, `oxlint-plugin-t3code`, and `scripts`.
-  Workspaces that define a build task run one: desktop, marketing, server (which depends on web), and
-  web. Shared packages are consumed and bundled transitively rather than built separately.
-- `vp run build:desktop`: Builds the desktop pipeline (desktop plus server).
-- `vp run start`: Runs the production server (serves the built web app as static files).
-- `vp check`: Vite+ format, lint, and type checks. This repo sets `typeCheck: false` in its lint
-  options, so workspace type checking runs separately.
-- `vp run typecheck`: Strict TypeScript checks for all packages.
-- `vp run test`: Runs workspace tests.
-- `vp run lint:mobile`: Mobile native static analysis (`scripts/mobile-native-static-check.ts`).
-- `node apps/server/scripts/t3-sqlite-state.ts <query|exec> --base-dir <path> ...`: Inspects or seeds
-  an isolated T3 SQLite database; writes create a private backup first.
-
-## Desktop artifacts
-
-- `vp run dist:desktop:artifact --platform <mac|linux|win> --target <target> --arch <arch>`: Builds a desktop artifact for a specific platform/target/arch.
-- `vp run dist:desktop:dmg`: Builds a shareable macOS `.dmg` into `./release`. Architecture defaults
-  to the host, so this produces an arm64 DMG on Apple Silicon. Use `dist:desktop:dmg:arm64` or
-  `dist:desktop:dmg:x64`, or pass `--arch <arm64|x64|universal>`, to force one.
-- `vp run dist:desktop:linux`: Builds a Linux AppImage into `./release`.
-- `vp run dist:desktop:win`: Builds a Windows NSIS installer into `./release`. `:arm64` and `:x64`
-  variants exist.
-
-### Linux AppImage prerequisites
-
-Linux AppImage packaging compiles the Rust resource monitor and the libsecret browser import
-helper. Install a Rust toolchain, the standard C/C++ build tools, libsecret development headers,
-pkg-config, and ImageMagick before running `vp run dist:desktop:linux`.
-
-Ubuntu and Debian:
-
-```bash
-sudo apt-get update
-sudo apt-get install cargo rustc build-essential libsecret-1-dev pkg-config imagemagick
-```
-
-Fedora:
-
-```bash
-sudo dnf install rust cargo gcc gcc-c++ make libsecret-devel pkgconf-pkg-config ImageMagick
-```
-
-Arch Linux:
-
-```bash
-sudo pacman -S rust base-devel libsecret pkgconf imagemagick
-```
-
-Linux desktop development also needs the C compiler, pkg-config, and libsecret headers. Its build
-and launch commands compile `native/browser-secret/main.c` into the gitignored native build
-directory. Releases place the executable in `resources/browser-secret`, outside `app.asar`.
-The helper performs a read-only Chromium schema lookup through libsecret and writes the exact
-secret bytes to its stdout pipe. Exit codes are 2 for a missing key, 3 for denied/locked access,
-and 4 for other keyring failures; the desktop importer preserves these distinctions.
-
-The artifact script checks these capabilities before starting the web and desktop builds. If
-anything is unavailable, it reports every failed check together and prints the Ubuntu/Debian
-installation command. The check compiles and links tiny temporary programs, so it also catches
-installed runtime X11 libraries that are missing their development headers or linker symlinks.
-
-### macOS DMG prerequisites
-
-Install the Xcode Command Line Tools and Rust before building a DMG:
-
-```bash
-xcode-select --install
-```
-
-Install Rust from [rustup.rs](https://rustup.rs). The artifact script checks Cargo, Clang, Make,
-`sips`, and `iconutil`. Universal builds additionally require `lipo`. It also verifies that Rust
-has every requested target; add missing targets with:
-
-```bash
-rustup target add aarch64-apple-darwin x86_64-apple-darwin
-```
-
-Unsigned local builds need no Apple credentials. Builds using `--signed` additionally require the
-certificate, provisioning profile, team ID, and notarization configuration described below.
-
-### Windows installer prerequisites
-
-Install Rust from [rustup.rs](https://rustup.rs), Python 3, and Visual Studio Build Tools. In the
-Visual Studio Installer, select **Desktop development with C++** and include:
-
-- MSVC x64/x86 build tools
-- A Windows 10 or Windows 11 SDK
-- MSVC Spectre-mitigated libraries
-
-ARM64 installers require the corresponding MSVC ARM64 build tools and Spectre-mitigated libraries
-instead of the x64/x86 components.
-
-Add the Rust target matching the installer architecture:
-
-```powershell
-rustup target add x86_64-pc-windows-msvc
-# For an arm64 installer:
-rustup target add aarch64-pc-windows-msvc
-```
-
-Windows supplies `tar.exe`; it is checked when `--wsl-prebuild` makes the artifact include the WSL
-runtime. NSIS is downloaded by electron-builder and does not need a separate installation.
-When `T3CODE_DESKTOP_REUSE_RESOURCE_MONITOR=true` points the build at an existing resource monitor,
-the artifact script skips the Rust and Visual Studio checks because it does not compile the monitor.
-Unsigned local builds need no Azure credentials. Builds using `--signed` additionally require the
-Azure Trusted Signing configuration described below.
-
-### Desktop `.dmg` packaging notes
-
-- Default build is unsigned/not notarized for local sharing.
-- The DMG build uses `assets/prod/black-macos-1024.png` as the production app icon source.
-- The DMG chrome follows the release channel: neutral for Latest and the Nightly sky artwork for
-  Nightly. Blueprint artwork remains exclusive to Dev builds. Packaging rasterizes the selected
-  SVG into standard and Retina PNGs inside the disposable staging directory.
-- The Finder window is 540×412 while its background is 540×380; the extra 32px accounts for the
-  title bar included in Finder's window bounds.
-- Desktop production windows load the bundled UI from the `t3code://app/` root URL (not a
-  `127.0.0.1` document URL, and not an explicit `index.html` path).
-- Desktop packaging includes `apps/server/dist` (the `t3` backend) and starts it on loopback with an
-  auth token for WebSocket/API traffic.
-- Your tester can still open it on macOS by right-clicking the app and choosing **Open** on first
-  launch.
-- To keep staging files for debugging package contents, run: `vp run dist:desktop:dmg --keep-stage`
-- To allow code-signing/notarization when configured in CI/secrets, add: `--signed`.
-- Signed macOS builds also require `T3CODE_APPLE_TEAM_ID` and
-  `T3CODE_MACOS_PROVISIONING_PROFILE`. The passkey RP domain is derived from
-  `T3CODE_CLERK_PUBLISHABLE_KEY` unless `T3CODE_CLERK_PASSKEY_RP_DOMAINS` overrides it.
-- Windows `--signed` uses Azure Trusted Signing and expects:
-  `AZURE_TRUSTED_SIGNING_ENDPOINT`, `AZURE_TRUSTED_SIGNING_ACCOUNT_NAME`,
-  `AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE_NAME`, and `AZURE_TRUSTED_SIGNING_PUBLISHER_NAME`.
-- Azure authentication env vars are also required (for example service principal with secret):
-  `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`.
-
-## Browser development
-
-`dev` and `dev:web` leave `VITE_HTTP_URL` and `VITE_WS_URL` unset so the browser resolves the backend
-from `window.location.origin`. Vite proxies `/api`, `/ws`, `/oauth`, and `/.well-known` to the
-server, allowing the same bundle to work from localhost or a tailnet hostname.
-
-## Running multiple dev instances
-
-Worktrees derive a preferred port offset from their path.
-
-- Default ports: server `13773`, web `5733`
-- Shifted ports: `base + offset`
-- Example: `T3CODE_DEV_INSTANCE=branch-a vp run dev:desktop`
-
-Offset resolution, in order:
-
-1. `T3CODE_PORT_OFFSET`, which must be a non-negative integer. Negative values are rejected.
-2. `T3CODE_DEV_INSTANCE`. An all-digit value is used directly as the offset; any other non-empty
-   value is hashed into one.
-3. The worktree path hash.
-
-Collision scanning depends on the mode. `dev:web` scans only the web port and shifts only the web
-offset. `dev:server` scans only the server port. `dev` and `dev:desktop` scan both and shift them
-together as one shared offset. Explicit server or dev-URL overrides remove the corresponding port
-from the availability check. Treat the `[dev-runner]` output as authoritative.
diff --git a/docs/internals/server-updates.md b/docs/internals/server-updates.md
index 693a240bbc79..db24428ce54d 100644
--- a/docs/internals/server-updates.md
+++ b/docs/internals/server-updates.md
@@ -1,107 +1,57 @@
-# Server Update Architecture
-
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-Remote server updates use one stable launcher selected by the platform service manager (systemd on
-Linux, launchd on macOS). Foreground CLI processes do not self-update, and a running server never
-edits its service definition or durable service state.
-
-## Ownership
-
-The service files under `<baseDir>/runtime` are:
-
-- `service-launcher.mjs`, the stable process selected by the service manager;
-- `service-state.json`, the launcher's durable selection state;
-- `versions/<version>`, immutable exact-version npm installs.
-
-The launcher is the only runtime writer of `service-state.json`. `t3 service install` and
-`t3 service update` may replace the launcher and state while the unit is stopped. Server children
-only communicate with the launcher over their inherited IPC channel.
-
-The state contains one active version and, at most, one update record:
-
-- `pending A → B` selects B as a retryable trial;
-- `committed A → B` selects B for ordinary restarts;
-- `rolled-back A → B` or `failed A → B` selects A;
-- invalid state fails closed so the service manager cannot guess at a runtime.
-
-Every write uses same-directory replacement plus file and directory fsync.
-
-## Remote Update
-
-1. The active server installs `t3@<target>` into a unique staging directory.
-2. The target runs `__service-preflight` and verifies that the stable launcher supports its update
-   protocol.
-3. The staging directory is renamed to its immutable version path only after preflight succeeds.
-4. The active child sends `request-update`. The launcher validates the child and target, writes
-   pending state, generates the update ID, then replies `update-accepted`.
-5. After a short response-flush grace period, the launcher stops the active child.
-6. With SQLite quiescent, the launcher snapshots the database, WAL, and shared-memory files.
-7. The launcher starts the target as a trial and gives it the pending update over IPC.
-8. The trial runs migrations, acquires dependencies, binds HTTP, starts every long-running root
-   fiber, and verifies that each root is parked at the activation gate.
-9. The trial sends `prepared`. The launcher durably commits B, deletes the snapshot, then replies
-   `committed`.
-10. The child opens the existing activation gate, accepts commands, and publishes lifecycle ready
-    with the terminal update outcome.
-
-Post-commit startup does not call service `start`, `initialize`, `connect`, `load`, or `acquire`
-operations. It only opens prepared gates and publishes prepared lifecycle state.
-
-The launcher serializes child exits, IPC messages, and timers. A trial must report prepared within
-120 seconds. If the trial exits or times out before prepared, the launcher stops it, restores the
-snapshot, records rollback, and starts A. A durable restore marker makes an interrupted restore
-resume before either version can boot. After commit, B is active and the service manager's normal
-restart policy applies.
-
-## Database Rollback
-
-The launcher snapshots `state.sqlite`, `state.sqlite-wal`, and `state.sqlite-shm` after the old
-server stops and before the trial starts. This makes trial migrations and writes reversible without
-requiring down migrations. The snapshot is retained across launcher restarts and is removed only
-after commit or after both restore and the terminal rollback state are durable.
-
-The protocol version is part of the safety boundary. A target that requires database snapshots is
-blocked when the installed launcher is too old. Upgrade the launcher once with:
-
-```sh
-npx t3@<version> service update
-```
-
-The local command stops the unit, selects the new launcher and exact runtime, then restarts the
-service. Later releases, including releases with migrations, can use the remote trial path.
-
-Snapshots briefly require enough free disk for another copy of the SQLite files. Attachments and
-other files under the state directory are outside this rollback boundary.
-
-## Client Correlation
-
-The update acknowledgement includes the launcher-generated update ID. After reconnecting, clients
-wait for a lifecycle ready event carrying that same ID. `committed` completes the operation only
-when the ready server is the target version. `rolled-back` and `failed` end it immediately with the
-recorded reason. Older servers without an ID retain version-only reconnect behavior.
-
-## Capability and Compatibility
-
-The existing additive RPC and lifecycle schemas remain compatible with older clients. New servers
-advertise remote self-update only when they have valid launcher context and a live IPC channel.
-Desktop-managed servers advertise `desktopAppUpdate` when the desktop telemetry control fd is
-attached. The progress RPC asks the desktop app to check and download, then returns a preparation
-token while the backend is still connected. Only after the client receives that result does it send
-`server.commitDesktopUpdate`. A successful commit closes the connection and must reconnect at the
-prepared version. The desktop app and bundled server versions stay equal because
-`scripts/update-release-package-versions.ts` bumps them together. If install fails, the desktop keeps its windows, restarts stopped backends, and
-replays the failure for the same token. This two-phase handoff prevents backend shutdown from
-dropping the only successful RPC result. Desktop servers without the capability direct the user to
-update the desktop app locally. Other process shapes provide a manual command; the old detached
-foreground respawn path no longer exists.
-
-## Source Map
-
-- Launcher and state machine: `apps/server/src/serviceLauncher.ts`
-- IPC and durable state types: `apps/server/src/cloud/serviceProtocol.ts`
-- Child IPC adapter: `apps/server/src/cloud/serviceLauncherClient.ts`
-- Staging and preflight: `apps/server/src/cloud/pinnedRuntime.ts` and `servicePreflight.ts`
-- Service installation: `apps/server/src/cloud/bootService.ts`
-- Activation boundary: `apps/server/src/serverRuntimeStartup.ts` and `serverActivation.ts`
-- Client outcome correlation: `packages/client-runtime/src/state/server.ts`
+# Server updates
+
+A [stable launcher](../../apps/server/src/serviceLauncher.ts) owns the runtime
+selected by systemd or launchd. It is the only runtime writer of durable service
+state. Server children request updates over inherited IPC; they never rewrite
+their service definition or select their own replacement. Local service commands
+may replace the launcher and state while the service is stopped. Foreground CLI
+processes do not self-update.
+
+Exact-version installs keep restarts independent of npm cache eviction or a moving
+release tag. Installation and preflight happen in staging before publishing an
+immutable runtime. Preflight checks the launcher protocol because a target that
+needs new rollback guarantees cannot safely run under an older launcher. Upgrading
+that launcher requires a local service update.
+
+## Commit boundary
+
+The launcher durably records the pending update before acknowledging it, then
+stops the old child and starts the target as a trial. Service-state writes use
+same-directory replacement with file and directory fsync. Invalid state stops
+startup rather than guessing which runtime to boot.
+
+The trial must finish migrations, acquire dependencies, bind HTTP, and park every
+long-running root at the activation gate before reporting `prepared`. The launcher
+then commits the target version durably and replies `committed`. Only then may the
+child release its gates, accept commands, and publish ready. Keep fallible startup
+acquisitions before this boundary. A listener alone does not prove the runtime is
+ready to commit.
+
+A failed or timed-out trial returns to the old version. After commit, the target
+is authoritative and the service manager's ordinary restart policy applies.
+
+## Database rollback
+
+After the old child exits, the launcher snapshots SQLite's main file, WAL, and
+shared-memory file. This makes trial migrations reversible without down
+migrations. The snapshot is made once per update and survives launcher restarts;
+replacing it during a retry could capture changes from the failed trial.
+
+Rollback stops the trial before restoring. A durable restore marker makes an
+interrupted restore finish before either version boots. Keep the snapshot until
+commit, or until both restoration and the terminal rollback state are durable.
+Attachments and other files outside SQLite are outside this rollback boundary.
+
+## Client acknowledgement
+
+An accepted update is still pending. Clients correlate the launcher's update ID
+with the ready event after reconnecting, then check the outcome and target version.
+A reconnect alone cannot distinguish successful replacement from rollback. Older
+servers without an update ID retain version-only correlation.
+
+Desktop updates have a separate two-phase handoff because installing the app stops
+its bundled backend. Preparation returns a token while the connection is alive;
+the client commits that token only after receiving it. Otherwise backend shutdown
+could lose the only successful RPC result. The client must then observe the
+prepared version after reconnecting. If installation fails, desktop restarts the
+stopped backends and replays the failure for the same token.
diff --git a/docs/internals/t3-code-connect-auth-flow.html b/docs/internals/t3-code-connect-auth-flow.html
deleted file mode 100644
index 038132ee5cbf..000000000000
--- a/docs/internals/t3-code-connect-auth-flow.html
+++ /dev/null
@@ -1,1160 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>T3 Connect Architecture</title>
-    <style>
-      :root {
-        color-scheme: light;
-        --ink: #171717;
-        --muted: #62646b;
-        --hairline: #d8d8dd;
-        --panel: #ffffff;
-        --paper: #f5f5f2;
-        --blue: #1457d9;
-        --green: #1d7d4d;
-        --amber: #a65f00;
-        --red: #b8242c;
-        --violet: #6150b8;
-        --shadow: 0 18px 55px rgba(25, 25, 28, 0.08);
-      }
-
-      * {
-        box-sizing: border-box;
-      }
-
-      body {
-        margin: 0;
-        background:
-          linear-gradient(90deg, rgba(0, 0, 0, 0.035) 1px, transparent 1px),
-          linear-gradient(rgba(0, 0, 0, 0.035) 1px, transparent 1px), var(--paper);
-        background-size: 34px 34px;
-        color: var(--ink);
-        font-family:
-          ui-sans-serif,
-          -apple-system,
-          BlinkMacSystemFont,
-          "Segoe UI",
-          sans-serif;
-        line-height: 1.48;
-      }
-
-      .shell {
-        width: min(1540px, calc(100vw - 40px));
-        margin: 0 auto;
-        padding: 38px 0 72px;
-      }
-
-      header {
-        border-bottom: 2px solid var(--ink);
-        padding-bottom: 24px;
-        margin-bottom: 28px;
-      }
-
-      .eyebrow {
-        color: var(--blue);
-        font-size: 12px;
-        font-weight: 800;
-        letter-spacing: 0.08em;
-        text-transform: uppercase;
-      }
-
-      h1 {
-        max-width: 980px;
-        margin: 8px 0 12px;
-        font-size: clamp(34px, 5vw, 66px);
-        line-height: 0.98;
-      }
-
-      h2 {
-        margin: 0 0 14px;
-        font-size: 26px;
-        line-height: 1.08;
-      }
-
-      h3 {
-        margin: 22px 0 8px;
-        font-size: 17px;
-      }
-
-      p {
-        margin: 0 0 12px;
-      }
-
-      code,
-      .mono {
-        font-family:
-          ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
-      }
-
-      code {
-        border-radius: 4px;
-        background: #f0f0ed;
-        padding: 1px 4px;
-        font-size: 0.92em;
-      }
-
-      .lede {
-        max-width: 1000px;
-        margin: 0;
-        color: var(--muted);
-        font-size: 18px;
-      }
-
-      .grid {
-        display: grid;
-        grid-template-columns: repeat(12, 1fr);
-        gap: 18px;
-      }
-
-      .panel {
-        grid-column: span 12;
-        border: 1px solid var(--hairline);
-        border-radius: 10px;
-        background: var(--panel);
-        box-shadow: var(--shadow);
-        padding: 22px;
-      }
-
-      .half {
-        grid-column: span 6;
-      }
-
-      .callout {
-        border-left: 5px solid var(--blue);
-        background: #eef4ff;
-        padding: 14px 16px;
-        margin-top: 14px;
-      }
-
-      .callout.warning {
-        border-left-color: var(--amber);
-        background: #fff6e6;
-      }
-
-      .badge-row {
-        display: flex;
-        flex-wrap: wrap;
-        gap: 8px;
-        margin-top: 14px;
-      }
-
-      .badge {
-        border: 1px solid var(--hairline);
-        border-radius: 999px;
-        background: #fff;
-        padding: 5px 9px;
-        font-size: 12px;
-        font-weight: 700;
-      }
-
-      .badge.user {
-        border-color: rgba(20, 87, 217, 0.3);
-        color: var(--blue);
-      }
-
-      .badge.env {
-        border-color: rgba(29, 125, 77, 0.3);
-        color: var(--green);
-      }
-
-      .badge.local {
-        border-color: rgba(166, 95, 0, 0.35);
-        color: var(--amber);
-      }
-
-      .diagram {
-        overflow-x: auto;
-        margin: 12px 0 0;
-        border: 1px solid var(--hairline);
-        border-radius: 8px;
-        background: #fbfbf8;
-        color: var(--ink);
-        padding: 18px;
-      }
-
-      .diagram svg {
-        display: block;
-        width: auto !important;
-        min-width: 100%;
-        max-width: none !important;
-        height: auto;
-        margin: 0 auto;
-      }
-
-      table {
-        width: 100%;
-        border-collapse: collapse;
-        font-size: 14px;
-      }
-
-      th,
-      td {
-        border-bottom: 1px solid var(--hairline);
-        padding: 11px 9px;
-        text-align: left;
-        vertical-align: top;
-      }
-
-      th {
-        color: var(--muted);
-        font-size: 12px;
-        letter-spacing: 0.05em;
-        text-transform: uppercase;
-      }
-
-      ul {
-        margin: 8px 0 0;
-        padding-left: 20px;
-      }
-
-      li + li {
-        margin-top: 6px;
-      }
-
-      .flow {
-        display: grid;
-        gap: 10px;
-        margin-top: 12px;
-      }
-
-      .step {
-        border: 1px solid var(--hairline);
-        border-left: 5px solid var(--green);
-        border-radius: 8px;
-        background: #fff;
-        padding: 12px 14px;
-      }
-
-      .step strong {
-        display: block;
-        margin-bottom: 3px;
-      }
-
-      .source-list a {
-        color: var(--blue);
-        font-weight: 700;
-      }
-
-      @media (max-width: 860px) {
-        .half {
-          grid-column: span 12;
-        }
-
-        .shell {
-          width: min(100vw - 24px, 1540px);
-          padding-top: 24px;
-        }
-      }
-    </style>
-  </head>
-  <body>
-    <main class="shell">
-      <header>
-        <div class="eyebrow">Implemented architecture</div>
-        <h1>T3 Connect Control Plane and Managed Endpoint Flow</h1>
-        <p class="lede">
-          T3 Connect links a locally authorized T3 environment to a signed-in cloud user, provisions
-          a managed HTTPS/WSS endpoint for that environment, and brokers proof-bound remote
-          connections. The local environment remains the authority that issues environment access
-          credentials. The hosted relay stores links, reconciles managed endpoint resources,
-          validates signed proofs, and delivers agent-activity notifications.
-        </p>
-        <div class="badge-row">
-          <span class="badge user">Client -> Relay: Clerk bearer or relay DPoP</span>
-          <span class="badge env">Relay -> Environment: relay-signed health and mint proofs</span>
-          <span class="badge env"
-            >Environment -> Relay: environment bearer plus signed activity proof</span
-          >
-          <span class="badge local">Client -> Environment: environment access token plus DPoP</span>
-        </div>
-      </header>
-
-      <section class="grid" aria-label="Architecture summary">
-        <article class="panel half">
-          <h2>Security Invariant</h2>
-          <p>
-            A cloud identity is not an environment login. Remote access requires all of the
-            following:
-          </p>
-          <ul>
-            <li>a Clerk-authenticated T3 Connect user;</li>
-            <li>an active relay link for that user and environment;</li>
-            <li>a DPoP proof key held by the remote client;</li>
-            <li>a relay-signed mint request accepted by the linked local environment; and</li>
-            <li>an environment-issued credential bound to the remote client's DPoP thumbprint.</li>
-          </ul>
-          <div class="callout">
-            The relay cannot mint an environment access token by itself. It can only ask the local
-            environment to mint a short-lived bootstrap credential for an authorized cloud user.
-          </div>
-          <p>During an honest connection flow, the relay cannot act as the remote client:</p>
-          <ul>
-            <li>
-              Normal environment API traffic goes directly from the remote client through the
-              managed endpoint. The relay does not receive the resulting environment access token.
-            </li>
-            <li>
-              The one-time bootstrap credential and resulting environment access token are bound to
-              the remote client's DPoP public-key thumbprint. Redeeming or using them requires
-              request proofs signed by the corresponding private key, which stays on the client.
-            </li>
-            <li>
-              Relay-signed health and mint proofs are short-lived, audience-bound, scoped, and
-              replay-guarded. They are accepted only by the narrow cloud endpoints, not as normal
-              environment API credentials.
-            </li>
-            <li>
-              Environment health and mint responses are signed by the linked environment and bound
-              to the request nonce, so a different process behind the tunnel cannot impersonate the
-              linked environment.
-            </li>
-          </ul>
-          <div class="callout warning">
-            The hosted relay remains a trusted mint broker: it holds the cloud-mint signing key.
-            DPoP prevents credential reuse by the relay or tunnel transport during an honest flow,
-            but it does not make compromise of the relay signing authority harmless.
-          </div>
-        </article>
-
-        <article class="panel half">
-          <h2>Product Boundaries</h2>
-          <p>
-            The generic local connector is called the <strong>relay client</strong>. The current
-            implementation layer uses <code>cloudflared</code>, but that is an internal transport
-            detail rather than the product contract.
-          </p>
-          <ul>
-            <li>
-              The relay Worker owns cloud links, managed endpoint allocations, and notifications.
-            </li>
-            <li>
-              The environment server owns local sessions, environment keys, and access tokens.
-            </li>
-            <li>The relay client exposes only the environment's loopback HTTP server.</li>
-            <li>
-              Web and mobile clients connect directly to the managed environment endpoint after
-              bootstrap.
-            </li>
-          </ul>
-        </article>
-      </section>
-
-      <section class="panel" aria-label="Topology">
-        <h2>Current Topology</h2>
-        <pre class="diagram mermaid">
-flowchart LR
-  subgraph Clients["User-facing clients"]
-    Web["Desktop / hosted web UI"]
-    Mobile["Mobile app"]
-    CLI["Headless CLI"]
-  end
-
-  Clerk["Clerk<br/>user identity and OAuth"]
-
-  subgraph Relay["T3 Code Relay on Cloudflare"]
-    Worker["Relay Worker<br/>HTTP API"]
-    Queue["APNs delivery queue<br/>with dead-letter queue"]
-    Hyperdrive["Hyperdrive"]
-    CF["Cloudflare tunnel + DNS APIs"]
-  end
-
-  DB["PlanetScale Postgres<br/>prod database + stage branches"]
-  APNs["Apple Push Notification service"]
-  Traces["Axiom OTLP traces"]
-
-  subgraph Local["Linked T3 environment"]
-    Env["Environment server<br/>local auth authority"]
-    RelayClient["Relay client<br/>cloudflared implementation"]
-    Secrets["Server secret store<br/>keys + relay config"]
-  end
-
-  Endpoint["Managed HTTPS/WSS endpoint"]
-
-  Web -->|"Clerk bearer / relay DPoP"| Worker
-  Mobile -->|"Clerk bearer / relay DPoP"| Worker
-  CLI -->|"Clerk OAuth bearer"| Worker
-  Web --> Clerk
-  Mobile --> Clerk
-  CLI -->|"PKCE authorization code flow"| Clerk
-  Worker --> Hyperdrive --> DB
-  Worker --> Traces
-  Worker --> CF
-  Worker --> Queue --> APNs
-  Worker --> Endpoint
-  Endpoint --> RelayClient -->|"http://127.0.0.1:port"| Env
-  Env --> Secrets
-  Web -->|"environment token + DPoP<br/>HTTPS / WSS"| Endpoint
-  Mobile -->|"environment token + DPoP<br/>HTTPS / WSS"| Endpoint
-  Env -->|"environment bearer + signed activity proof"| Worker
-        </pre>
-      </section>
-
-      <section class="panel" aria-label="Authentication matrix">
-        <h2>Authentication and Transport Matrix</h2>
-        <table>
-          <thead>
-            <tr>
-              <th>Boundary</th>
-              <th>Transport</th>
-              <th>Authentication</th>
-              <th>Purpose</th>
-            </tr>
-          </thead>
-          <tbody>
-            <tr>
-              <td>Web or mobile -> relay link management</td>
-              <td>HTTPS</td>
-              <td>Clerk session-template bearer token</td>
-              <td>Create a link challenge, submit an environment proof, list links, or unlink.</td>
-            </tr>
-            <tr>
-              <td>CLI -> relay link management</td>
-              <td>HTTPS</td>
-              <td>Clerk OAuth access token obtained with PKCE</td>
-              <td>Reconcile the desired headless cloud link when the server starts.</td>
-            </tr>
-            <tr>
-              <td>Web or mobile -> relay protected client endpoints</td>
-              <td>HTTPS</td>
-              <td>Relay-issued DPoP token plus per-request DPoP proof</td>
-              <td>
-                Check environment status, request a remote connection, and register mobile devices.
-              </td>
-            </tr>
-            <tr>
-              <td>Relay -> managed environment endpoint</td>
-              <td>HTTPS over the managed tunnel</td>
-              <td>Short-lived relay-signed JWT request proof</td>
-              <td>
-                Request a signed health response or ask the local environment to mint a credential.
-              </td>
-            </tr>
-            <tr>
-              <td>Environment -> relay activity publication</td>
-              <td>HTTPS</td>
-              <td>Relay-issued environment bearer credential plus environment-signed JWT proof</td>
-              <td>
-                Publish redacted agent-activity state for push notifications and Live Activities.
-              </td>
-            </tr>
-            <tr>
-              <td>Remote client -> environment</td>
-              <td>HTTPS and WSS over the managed tunnel</td>
-              <td>Environment-issued access token bound to the client DPoP key</td>
-              <td>Use the normal environment HTTP APIs and request a one-time WebSocket ticket.</td>
-            </tr>
-          </tbody>
-        </table>
-      </section>
-
-      <section class="panel" aria-label="Credential ownership">
-        <h2>Credential Ownership</h2>
-        <table>
-          <thead>
-            <tr>
-              <th>Credential</th>
-              <th>Created by</th>
-              <th>Stored by</th>
-              <th>Use</th>
-            </tr>
-          </thead>
-          <tbody>
-            <tr>
-              <td>Clerk session-template JWT</td>
-              <td>Clerk</td>
-              <td>Web or mobile client</td>
-              <td>
-                Authenticate cloud-user relay requests and bootstrap relay DPoP token exchange.
-              </td>
-            </tr>
-            <tr>
-              <td>CLI OAuth access and refresh token</td>
-              <td>Clerk OAuth</td>
-              <td>Local server secret store</td>
-              <td>Authorize headless CLI link reconciliation.</td>
-            </tr>
-            <tr>
-              <td>Environment Ed25519 key pair</td>
-              <td>Local environment server</td>
-              <td>Local server secret store</td>
-              <td>
-                Sign link proofs, health responses, mint responses, and activity publication proofs.
-              </td>
-            </tr>
-            <tr>
-              <td>Relay cloud-mint key pair</td>
-              <td>Relay deployment</td>
-              <td>Private key in relay Worker config; public key installed into the environment</td>
-              <td>Sign relay-to-environment health and mint requests.</td>
-            </tr>
-            <tr>
-              <td>Relay environment bearer credential</td>
-              <td>Relay</td>
-              <td>Hashed in relay Postgres; plaintext in local server secret store</td>
-              <td>Authenticate environment-to-relay agent-activity publication.</td>
-            </tr>
-            <tr>
-              <td>Relay DPoP access token</td>
-              <td>Relay</td>
-              <td>Remote client memory cache</td>
-              <td>
-                Authorize status, connect, and mobile registration endpoints with proof of
-                possession.
-              </td>
-            </tr>
-            <tr>
-              <td>Environment bootstrap credential</td>
-              <td>Local environment server</td>
-              <td>Passed relay -> remote client</td>
-              <td>One-time exchange at the environment <code>/oauth/token</code> endpoint.</td>
-            </tr>
-            <tr>
-              <td>Environment access token</td>
-              <td>Local environment server</td>
-              <td>Remote client</td>
-              <td>Authorize environment HTTP operations and WebSocket ticket issuance.</td>
-            </tr>
-            <tr>
-              <td>WebSocket ticket</td>
-              <td>Local environment server</td>
-              <td>Remote client until consumed</td>
-              <td>Short-lived one-time credential for the WSS upgrade.</td>
-            </tr>
-            <tr>
-              <td>Relay client connector token</td>
-              <td>Cloudflare tunnel API</td>
-              <td>Local server secret store</td>
-              <td>
-                Start the local relay client. It is passed through <code>TUNNEL_TOKEN</code>, not a
-                shell argument.
-              </td>
-            </tr>
-          </tbody>
-        </table>
-      </section>
-
-      <section class="grid" aria-label="Core flows">
-        <article class="panel">
-          <h2>Flow 1: Link From the Desktop Web UI</h2>
-          <pre class="diagram mermaid">
-sequenceDiagram
-  participant U as Signed-in user
-  participant C as Desktop web UI
-  participant E as Local environment
-  participant R as Relay Worker
-  participant CF as Cloudflare APIs
-  participant RC as Local relay client
-
-  U->>C: Enable T3 Connect for a locally paired environment
-  C->>E: Check relay client availability
-  alt relay client is missing
-    C->>U: Prompt before download and install
-    U->>C: Confirm
-    C->>E: Stream relay-client install RPC
-    E-->>C: Progress stages
-  end
-  C->>R: POST /v1/client/environment-link-challenges (Clerk bearer)
-  R-->>C: Short-lived challenge
-  C->>E: POST /api/connect/link-proof (local relay:write bearer)
-  E->>E: Authenticate, reject forwarded authority, get or create key pair, validate loopback origin
-  E-->>C: Environment-signed link proof
-  C->>R: POST /v1/client/environment-links (Clerk bearer + proof)
-  R->>R: Verify challenge, proof, capabilities, nonce, and loopback origin
-  R->>CF: Reconcile tunnel, ingress, and CNAME
-  R->>R: Upsert user/environment link and issue environment bearer
-  R-->>C: Managed endpoint, relay config, and connector token
-  C->>E: POST /api/connect/relay-config (local relay:write bearer)
-  E->>RC: Start relay client with TUNNEL_TOKEN
-          </pre>
-          <div class="callout">
-            The local link-proof endpoint requires <code>relay:write</code>, rejects forwarded
-            authority headers, and accepts only an exact loopback origin. Environment keypair
-            persistence is atomic across concurrent link attempts.
-          </div>
-          <p>
-            A locally paired mobile client uses the same relay challenge, local proof, relay link,
-            and local relay-config endpoints. The desktop web UI is the surface that checks relay
-            client availability and offers the managed install dialog.
-          </p>
-        </article>
-
-        <article class="panel">
-          <h2>Flow 2: Headless CLI Link</h2>
-          <pre class="diagram mermaid">
-sequenceDiagram
-  participant U as Operator
-  participant CLI as t3 connect CLI
-  participant Clerk as Clerk OAuth
-  participant S as Environment server on next start
-  participant R as Relay Worker
-  participant RC as Local relay client
-
-  U->>CLI: t3 connect link
-  CLI->>CLI: Resolve relay client
-  alt relay client is missing
-    CLI->>U: Confirm managed relay-client install
-    U->>CLI: Confirm
-    CLI->>CLI: Install with terminal progress updates
-  end
-  CLI->>Clerk: Browser PKCE authorization-code flow
-  Clerk-->>CLI: OAuth access and refresh tokens
-  CLI->>CLI: Persist desired cloud-link state
-  U->>S: Start T3 environment server
-  S->>R: Create challenge and submit local signed proof
-  R-->>S: Managed endpoint config and connector token
-  S->>RC: Start relay client
-          </pre>
-          <p>
-            <code>t3 connect login</code> stores authorization without enabling exposure.
-            <code>t3 connect unlink</code> disables exposure while retaining authorization.
-            <code>t3 connect logout</code> also removes the stored CLI authorization.
-          </p>
-        </article>
-
-        <article class="panel">
-          <h2>Flow 3: Remote Connect Bootstrap</h2>
-          <pre class="diagram mermaid">
-sequenceDiagram
-  participant C as Web or mobile client
-  participant Clerk as Clerk
-  participant R as Relay Worker
-  participant E as Managed environment endpoint
-
-  C->>Clerk: Get Clerk session-template JWT
-  C->>R: POST /v1/client/dpop-token (Clerk JWT + DPoP proof)
-  R-->>C: Relay DPoP access token
-  C->>R: POST /v1/environments/:id/connect (relay DPoP)
-  R->>E: POST /api/t3-connect/mint-credential (relay-signed proof)
-  E->>E: Verify relay signer, linked user, scope, lifetime, cnf, and replay guards
-  E-->>R: Bootstrap credential + environment-signed proof
-  R->>R: Verify environment signature, nonce, endpoint, and DPoP binding
-  R-->>C: Managed endpoint + bootstrap credential
-  C->>E: POST /oauth/token (bootstrap credential + DPoP proof)
-  E-->>C: Environment DPoP-bound access token
-  C->>E: POST /api/auth/websocket-ticket
-  E-->>C: One-time WebSocket ticket
-  C->>E: WSS /ws with ticket
-          </pre>
-          <div class="callout">
-            Relay-to-environment control requests disable redirects, use only a reconciled managed
-            endpoint allocation, and require a signed environment response before the relay returns
-            data to the client.
-          </div>
-        </article>
-
-        <article class="panel">
-          <h2>Flow 4: Agent Activity Notifications</h2>
-          <pre class="diagram mermaid">
-sequenceDiagram
-  participant E as Local environment
-  participant R as Relay Worker
-  participant DB as Relay Postgres
-  participant Q as APNs queue
-  participant APNs as Apple Push Notification service
-  participant M as Mobile app
-
-  E->>E: Project publishable thread state and redact failure detail
-  E->>R: POST /v1/environments/:environmentId/threads/:threadId/agent-activity
-  Note over E,R: Environment bearer credential + environment-signed per-state proof
-  R->>R: Verify credential, signature, scope, expiry, and nonce
-  R->>DB: Store current activity row
-  R->>Q: Enqueue push or Live Activity delivery jobs
-  Q->>APNs: Deliver signed APNs request
-  APNs-->>M: Push notification or Live Activity update
-          </pre>
-          <p>
-            The local server publishes a deliberately narrow projection. Failed runs use a fixed
-            redacted summary, and detail strings are capped before publication.
-          </p>
-        </article>
-      </section>
-
-      <section class="grid" aria-label="Managed endpoint lifecycle">
-        <article class="panel half">
-          <h2>Managed Endpoint Reconciliation</h2>
-          <p>
-            Managed endpoint resources are keyed by <code>(userId, environmentId)</code>. The relay
-            reserves a stable hostname and tunnel name before provisioning, then checkpoints the
-            tunnel ID, DNS record ID, and ready state in Postgres.
-          </p>
-          <div class="flow">
-            <div class="step">
-              <strong>1. Reserve deterministic allocation</strong>
-              Hostname and tunnel name derive from relay stage, cloud user, and environment ID.
-            </div>
-            <div class="step">
-              <strong>2. Reuse or create tunnel</strong>
-              Existing named tunnels are reused. Tunnel ingress is rewritten to the validated
-              loopback origin.
-            </div>
-            <div class="step">
-              <strong>3. Reconcile DNS</strong>
-              Existing CNAMEs are updated and duplicate records are removed. Create conflicts are
-              recovered by listing and reconciling the winning record.
-            </div>
-            <div class="step">
-              <strong>4. Mark ready</strong>
-              Connect and status requests use only ready allocations whose hostname still matches
-              the relay-managed namespace.
-            </div>
-          </div>
-        </article>
-
-        <article class="panel half">
-          <h2>Unlink Cleanup</h2>
-          <p>
-            Relay unlink removes the user's managed endpoint allocation before revoking the
-            user/environment link:
-          </p>
-          <ul>
-            <li>delete the managed DNS record if present;</li>
-            <li>delete the Cloudflare tunnel if present;</li>
-            <li>remove the allocation row;</li>
-            <li>revoke the user's environment link; and</li>
-            <li>
-              revoke the environment publication credential only after the final active link for
-              that environment key disappears.
-            </li>
-          </ul>
-          <p>
-            Local unlink stops the relay client and removes the locally persisted relay URL, issuer,
-            linked user, environment publication credential, cloud-mint public key, connector
-            config, and agent-activity preference.
-          </p>
-        </article>
-      </section>
-
-      <section class="panel" aria-label="Cloudflare tunnel operational profile">
-        <h2>Cloudflare Tunnel Operational Profile</h2>
-        <p>
-          Managed tunnels are private application backends, not general-purpose public hosting. The
-          relay provisions one named Cloudflare tunnel and one DNS record per active
-          <code>(userId, environmentId)</code> allocation.
-        </p>
-        <ul>
-          <li>
-            <strong>Lifecycle:</strong> the tunnel is created when an environment is linked, reused
-            across retry-safe reconciliation, kept for the lifetime of that link, and deleted on
-            unlink. If teardown fails, the allocation checkpoint remains so cleanup can be retried.
-          </li>
-          <li>
-            <strong>Origin:</strong> tunnel ingress is restricted to the linked environment server's
-            validated loopback HTTP origin. Arbitrary upstream hosts and raw TCP origins are
-            rejected.
-          </li>
-          <li>
-            <strong>Protocols:</strong> managed endpoints carry HTTPS request/response traffic and
-            WSS connections only. Remote clients use the normal environment HTTP APIs and
-            authenticated WebSocket RPC transport through the tunnel.
-          </li>
-          <li>
-            <strong>Relay-generated traffic:</strong> the hosted relay sends sparse HTTPS health
-            checks and credential-mint requests during status checks and remote connection
-            bootstrap. It does not proxy steady-state remote sessions.
-          </li>
-          <li>
-            <strong>Traffic shape:</strong> expected load is interactive and user-driven. Active
-            remote sessions may keep WebSockets open and exchange terminal, agent, and UI updates;
-            inactive linked environments should carry little or no tunnel traffic.
-          </li>
-          <li>
-            <strong>Capacity planning:</strong> the project is pre-launch, so there is not yet a
-            production bandwidth baseline. Tunnel count grows with active linked user/environment
-            allocations, while bandwidth and concurrent WebSockets grow with active remote use.
-          </li>
-        </ul>
-      </section>
-
-      <section class="panel" aria-label="SSRF and tunnel hardening">
-        <h2>SSRF and Tunnel Hardening</h2>
-        <table>
-          <thead>
-            <tr>
-              <th>Risk</th>
-              <th>Implemented control</th>
-            </tr>
-          </thead>
-          <tbody>
-            <tr>
-              <td>A client asks the relay to tunnel an arbitrary host.</td>
-              <td>
-                The environment and relay both accept managed tunnel origins only for loopback hosts
-                and valid ports.
-              </td>
-            </tr>
-            <tr>
-              <td>A forwarded request tricks local origin validation.</td>
-              <td>
-                The local link-proof handler requires an exact loopback request URL and rejects
-                forwarded host or protocol headers.
-              </td>
-            </tr>
-            <tr>
-              <td>A stored endpoint is replaced with an arbitrary external URL.</td>
-              <td>
-                Connect and status resolve a ready allocation from Postgres and require a hostname
-                under the configured managed endpoint zone.
-              </td>
-            </tr>
-            <tr>
-              <td>A managed endpoint redirects relay egress elsewhere.</td>
-              <td>
-                Relay-to-environment status and mint requests set redirect handling to
-                <code>manual</code>.
-              </td>
-            </tr>
-            <tr>
-              <td>A process behind the tunnel returns attacker-controlled data.</td>
-              <td>
-                The relay verifies environment-signed health and mint responses against the linked
-                environment public key, expected nonce, and request binding.
-              </td>
-            </tr>
-            <tr>
-              <td>A stolen remote access token is replayed.</td>
-              <td>
-                Relay and environment access tokens are DPoP-bound; per-request proofs and replay
-                guards are required.
-              </td>
-            </tr>
-            <tr>
-              <td>The relay client token leaks through process listings or shell parsing.</td>
-              <td>
-                The relay client is spawned without a shell and receives its connector token in
-                <code>TUNNEL_TOKEN</code>.
-              </td>
-            </tr>
-          </tbody>
-        </table>
-        <div class="callout warning">
-          Managed tunnel hostnames live under the configured tunnel DNS zone. Serving them from a
-          dedicated registrable domain with a Public Suffix List entry remains an operational
-          isolation requirement before broad untrusted use.
-        </div>
-      </section>
-
-      <section class="panel" aria-label="Relay HTTP API">
-        <h2>Relay HTTP API</h2>
-        <p>
-          The relay publishes an OpenAPI document at <code>/openapi.json</code>, interactive API
-          docs at <code>/docs</code>, and redirects <code>/</code> to the docs.
-        </p>
-        <table>
-          <thead>
-            <tr>
-              <th>Endpoint</th>
-              <th>Authentication</th>
-              <th>Purpose</th>
-            </tr>
-          </thead>
-          <tbody>
-            <tr>
-              <td><code>GET /health</code></td>
-              <td>None</td>
-              <td>Relay health check.</td>
-            </tr>
-            <tr>
-              <td><code>GET /.well-known/oauth-authorization-server</code></td>
-              <td>None</td>
-              <td>Relay OAuth token-exchange discovery metadata.</td>
-            </tr>
-            <tr>
-              <td><code>GET /.well-known/oauth-protected-resource</code></td>
-              <td>None</td>
-              <td>Relay DPoP protected-resource discovery metadata.</td>
-            </tr>
-            <tr>
-              <td><code>GET /v1/environments</code></td>
-              <td>Clerk bearer</td>
-              <td>List environments linked to the signed-in user.</td>
-            </tr>
-            <tr>
-              <td><code>POST /v1/client/environment-link-challenges</code></td>
-              <td>Clerk bearer</td>
-              <td>Create a short-lived user-bound environment link challenge.</td>
-            </tr>
-            <tr>
-              <td><code>POST /v1/client/environment-links</code></td>
-              <td>Clerk bearer</td>
-              <td>
-                Verify a local environment proof, reconcile a managed endpoint, and upsert the user
-                link.
-              </td>
-            </tr>
-            <tr>
-              <td><code>DELETE /v1/client/environment-links/:environmentId</code></td>
-              <td>Clerk bearer</td>
-              <td>Remove managed endpoint resources and revoke the user's link.</td>
-            </tr>
-            <tr>
-              <td><code>POST /v1/client/dpop-token</code></td>
-              <td>Clerk token in token-exchange payload plus DPoP proof</td>
-              <td>Issue a relay DPoP access token for the requested supported scopes.</td>
-            </tr>
-            <tr>
-              <td><code>POST /v1/environments/:environmentId/status</code></td>
-              <td>Relay DPoP</td>
-              <td>Request and validate a signed environment health response.</td>
-            </tr>
-            <tr>
-              <td><code>POST /v1/environments/:environmentId/connect</code></td>
-              <td>Relay DPoP</td>
-              <td>Request and validate an environment bootstrap credential.</td>
-            </tr>
-            <tr>
-              <td><code>POST /v1/mobile/devices</code></td>
-              <td>Relay DPoP</td>
-              <td>Register or update a mobile device for notifications.</td>
-            </tr>
-            <tr>
-              <td><code>POST /v1/mobile/live-activities</code></td>
-              <td>Relay DPoP</td>
-              <td>Register a Live Activity push token.</td>
-            </tr>
-            <tr>
-              <td><code>DELETE /v1/mobile/devices/:deviceId</code></td>
-              <td>Relay DPoP</td>
-              <td>Unregister a mobile device.</td>
-            </tr>
-            <tr>
-              <td>
-                <code>POST /v1/environments/:environmentId/threads/:threadId/agent-activity</code>
-              </td>
-              <td>Environment bearer plus signed publish proof</td>
-              <td>Publish redacted current agent activity for notification delivery.</td>
-            </tr>
-          </tbody>
-        </table>
-      </section>
-
-      <section class="panel" aria-label="Environment HTTP API">
-        <h2>Environment Cloud HTTP API</h2>
-        <table>
-          <thead>
-            <tr>
-              <th>Endpoint</th>
-              <th>Authentication</th>
-              <th>Purpose</th>
-            </tr>
-          </thead>
-          <tbody>
-            <tr>
-              <td><code>POST /api/connect/link-proof</code></td>
-              <td>Local environment token with <code>relay:write</code></td>
-              <td>Validate local origin and sign an environment link proof.</td>
-            </tr>
-            <tr>
-              <td><code>POST /api/connect/relay-config</code></td>
-              <td>Local environment token with <code>relay:write</code></td>
-              <td>Persist linked relay configuration and start the relay client.</td>
-            </tr>
-            <tr>
-              <td><code>GET /api/connect/link-state</code></td>
-              <td>Local environment token with <code>relay:read</code></td>
-              <td>Read the environment's current T3 Connect link state.</td>
-            </tr>
-            <tr>
-              <td><code>POST /api/connect/preferences</code></td>
-              <td>Local environment token with <code>relay:write</code></td>
-              <td>Enable or disable agent-activity publication.</td>
-            </tr>
-            <tr>
-              <td><code>POST /api/connect/unlink</code></td>
-              <td>Local environment token with <code>relay:write</code></td>
-              <td>Stop the relay client and clear local T3 Connect configuration.</td>
-            </tr>
-            <tr>
-              <td><code>POST /api/t3-connect/health</code></td>
-              <td>Relay-signed proof</td>
-              <td>Return a signed environment health response.</td>
-            </tr>
-            <tr>
-              <td><code>POST /api/t3-connect/mint-credential</code></td>
-              <td>Relay-signed proof</td>
-              <td>Mint a DPoP-bound one-time bootstrap credential for a remote client.</td>
-            </tr>
-            <tr>
-              <td><code>POST /oauth/token</code></td>
-              <td>Bootstrap credential plus DPoP proof</td>
-              <td>Exchange a bootstrap credential for an environment access token.</td>
-            </tr>
-            <tr>
-              <td><code>POST /api/auth/websocket-ticket</code></td>
-              <td>Environment access token</td>
-              <td>Issue a one-time ticket for the WSS upgrade.</td>
-            </tr>
-          </tbody>
-        </table>
-      </section>
-
-      <section class="grid" aria-label="Runtime and infrastructure">
-        <article class="panel half">
-          <h2>Relay Client Installation</h2>
-          <p>
-            Desktop web UI availability checks and installs are local WebSocket RPC methods:
-            <code>cloud.getRelayClientStatus</code> and streaming
-            <code>cloud.installRelayClient</code>. The install stream emits the current stage:
-            checking, waiting for lock, downloading, verifying, installing, validating, and
-            activating.
-          </p>
-          <p>
-            The web UI asks for confirmation before installation and displays a custom progress
-            dialog. The CLI invokes the same local relay-client service directly and reports the
-            same progress stages in the terminal.
-          </p>
-        </article>
-
-        <article class="panel half">
-          <h2>Relay Infrastructure</h2>
-          <ul>
-            <li>Cloudflare Worker for the hosted relay HTTP API.</li>
-            <li>PlanetScale Postgres database named <code>t3coderelay</code>.</li>
-            <li>
-              Production uses the shared database; non-production stages use database branches.
-            </li>
-            <li>
-              Cloudflare Hyperdrive with caching disabled and a constrained origin connection limit.
-            </li>
-            <li>Cloudflare tunnel and DNS bindings for managed endpoint reconciliation.</li>
-            <li>Cloudflare APNs delivery queue plus dead-letter queue.</li>
-            <li>A five-minute cron job that prunes expired DPoP replay rows.</li>
-            <li>Axiom OTLP trace dataset, scoped ingest token, and recent-spans view per stage.</li>
-          </ul>
-        </article>
-      </section>
-
-      <section class="panel" aria-label="Deployment configuration">
-        <h2>Deployment Configuration</h2>
-        <table>
-          <thead>
-            <tr>
-              <th>Boundary</th>
-              <th>Configuration</th>
-            </tr>
-          </thead>
-          <tbody>
-            <tr>
-              <td>Relay infrastructure</td>
-              <td>
-                <code>RELAY_API_ZONE_NAME</code>, <code>RELAY_TUNNEL_ZONE_NAME</code>, optional
-                <code>RELAY_DOMAIN</code>, <code>CLERK_PUBLISHABLE_KEY</code>,
-                <code>CLERK_SECRET_KEY</code>, <code>CLERK_JWT_AUDIENCE</code>, and APNs
-                credentials.
-              </td>
-            </tr>
-            <tr>
-              <td>Source-built desktop/server cloud features</td>
-              <td>
-                Optional <code>T3CODE_RELAY_URL</code>, <code>T3CODE_CLERK_PUBLISHABLE_KEY</code>,
-                and <code>T3CODE_CLERK_CLI_OAUTH_CLIENT_ID</code>. Release builds inject public
-                values at build time.
-              </td>
-            </tr>
-            <tr>
-              <td>Web and mobile cloud clients</td>
-              <td>
-                Public Clerk publishable key, Clerk JWT template name, and relay URL. Relay URLs
-                must normalize to an absolute HTTPS origin without credentials, query, fragment, or
-                non-root path.
-              </td>
-            </tr>
-          </tbody>
-        </table>
-      </section>
-
-      <section class="panel" aria-label="Implementation checklist">
-        <h2>Implementation Checklist</h2>
-        <ul>
-          <li>
-            Keep the relay cloud-mint private key hosted-only; install only its public key into
-            environments.
-          </li>
-          <li>
-            Keep environment signing private keys local and persist keypair creation atomically.
-          </li>
-          <li>
-            Require a local <code>relay:write</code> session before linking or changing relay
-            config.
-          </li>
-          <li>Validate relay URLs as secure absolute HTTPS origins before sending credentials.</li>
-          <li>Require loopback-only tunnel origins on both sides of the link-proof boundary.</li>
-          <li>
-            Resolve managed endpoint egress from ready allocation rows, not client-supplied URLs.
-          </li>
-          <li>Disable redirects on relay-to-environment requests.</li>
-          <li>Validate environment-signed response proofs before consuming tunneled responses.</li>
-          <li>Keep tunnel and DNS provisioning retry-safe and deprovision them on unlink.</li>
-          <li>
-            Revoke shared environment publication credentials only after the final active link
-            disappears.
-          </li>
-          <li>Redact and cap local agent failure details before publishing them externally.</li>
-        </ul>
-      </section>
-
-      <section class="panel" aria-label="Standards references">
-        <h2>Standards References</h2>
-        <ul class="source-list">
-          <li>
-            <a href="https://www.rfc-editor.org/rfc/rfc8252">RFC 8252</a>: browser-based OAuth for
-            native apps, used by the CLI PKCE authorization flow.
-          </li>
-          <li>
-            <a href="https://www.rfc-editor.org/rfc/rfc8693">RFC 8693</a>: OAuth token exchange,
-            used for Clerk-token to relay-DPoP-token exchange.
-          </li>
-          <li>
-            <a href="https://www.rfc-editor.org/rfc/rfc9449">RFC 9449</a>: DPoP proof of possession,
-            used for relay and environment access tokens.
-          </li>
-        </ul>
-      </section>
-    </main>
-    <script type="module">
-      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
-
-      mermaid.initialize({
-        startOnLoad: false,
-        securityLevel: "strict",
-        theme: "base",
-        themeVariables: {
-          fontFamily: 'ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
-          primaryColor: "#eef4ff",
-          primaryBorderColor: "#1457d9",
-          primaryTextColor: "#171717",
-          lineColor: "#62646b",
-          signalColor: "#171717",
-          signalTextColor: "#171717",
-          noteBkgColor: "#fff6e6",
-          noteTextColor: "#171717",
-          actorBkg: "#fbfbf8",
-          actorBorder: "#62646b",
-          actorTextColor: "#171717",
-        },
-        flowchart: {
-          htmlLabels: true,
-          curve: "basis",
-          padding: 18,
-        },
-        sequence: {
-          showSequenceNumbers: true,
-          mirrorActors: false,
-          rightAngles: false,
-        },
-      });
-
-      await mermaid.run({ querySelector: ".diagram.mermaid" });
-
-      for (const svg of document.querySelectorAll(".diagram.mermaid svg")) {
-        const viewBox = svg.getAttribute("viewBox");
-        const width = viewBox?.split(/\s+/).map(Number)[2];
-        if (Number.isFinite(width) && width > 0) {
-          svg.style.setProperty("width", `${Math.ceil(width)}px`, "important");
-          svg.style.setProperty("max-width", "none", "important");
-        }
-      }
-    </script>
-  </body>
-</html>
diff --git a/docs/internals/t3-connect.md b/docs/internals/t3-connect.md
index 6f796123e98b..bf02eb3538be 100644
--- a/docs/internals/t3-connect.md
+++ b/docs/internals/t3-connect.md
@@ -1,273 +1,81 @@
 # T3 Connect
 
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-T3 Connect uses one Clerk application for web, desktop, and mobile authentication. The relay verifies
-two kinds of bearer credential: template JWTs generated from the `t3-relay` template with the shared
-`t3-code-relay` audience, and Clerk OAuth tokens issued to the CLI. `verifyRelayClientBearerToken` in
-`infra/relay/src/http/Api.ts` tries the template/session path first and falls back to OAuth
-verification (`acceptsToken: "oauth_token"`), so the CLI's OAuth credential works without a JWT
-template.
-
-For the wider system diagram, see
-[t3-code-connect-auth-flow.html](./t3-code-connect-auth-flow.html).
-
-## Application Keys
-
-T3 Connect is disabled in a fresh clone. To enable it for source builds against the production
-deployment, copy the repository-root example file:
-
-```sh
-cp .env.example .env
-```
-
-`.env.example` carries the production public identifiers (the same values baked into official
-release builds). To target a different Clerk application or relay, set the values yourself in a
-repository-root `.env` or `.env.local` file:
-
-```dotenv
-T3CODE_CLERK_PUBLISHABLE_KEY=<publishable key>
-T3CODE_CLERK_JWT_TEMPLATE=<JWT template name>
-T3CODE_CLERK_CLI_OAUTH_CLIENT_ID=<public OAuth application client ID>
-T3CODE_RELAY_URL=https://relay.example.com
-```
-
-The shared client loader projects these canonical values into framework-specific `VITE_*` and
-`EXPO_PUBLIC_*` aliases. Existing aliases remain accepted as overrides for compatibility, but new
-client configuration should use the canonical names.
-
-Configuration precedence is:
-
-1. Process or CI environment variables.
-2. Repository-root `.env.local`.
-3. Repository-root `.env`.
-
-The Clerk publishable key, JWT template name, CLI OAuth client ID, and relay URL are public
-identifiers, not secrets.
-Web, desktop, mobile, and bundled server builds statically inject the values they consume during
-their build step. A built artifact does not need an environment file at runtime. CI release builds
-should set `T3CODE_CLERK_PUBLISHABLE_KEY`, `T3CODE_CLERK_JWT_TEMPLATE`,
-`T3CODE_CLERK_CLI_OAUTH_CLIENT_ID`, and `T3CODE_RELAY_URL` before building. EAS preview and
-production builds only need the Clerk publishable key, JWT template name, and relay URL in their EAS
-environment.
-
-When any client-facing public value is absent, cloud UI is omitted. The `t3 connect` command group is
-always registered: when the CLI public values are absent, `makeCli` in `apps/server/src/bin.ts`
-registers a hidden fallback `connect` command that reports the missing configuration instead of
-silently vanishing from help. The bundled server still accepts runtime overrides for self-hosted or
-operator-managed deployments.
-
-For a hosted relay deployment, copy `infra/relay/.env.example` to `infra/relay/.env`. The relay
-deployment reads `RELAY_DOMAIN`, `RELAY_API_ZONE_NAME`, `RELAY_TUNNEL_ZONE_NAME`,
-`CLERK_PUBLISHABLE_KEY`, and `CLERK_JWT_AUDIENCE` through Effect `Config`. There are no checked-in
-deployment defaults.
-`vp run --filter t3code-relay deploy` invokes Alchemy from the relay directory, so Alchemy loads
-`infra/relay/.env`. After a successful deployment, the wrapper updates the repository-root `.env`
-with the deployed HTTPS relay URL. The relay still requires
-`CLERK_SECRET_KEY` as an Alchemy secret. Never put `CLERK_SECRET_KEY` in a client application
-environment or commit it to the repository.
-
-The `prod` Alchemy stage owns the retained PlanetScale database. Non-production stages reference
-that database and provision isolated PlanetScale branches, so deploy `prod` before creating a
-personal developer stage.
-
-## Headless CLI OAuth Application
-
-The `t3 connect` commands authorize a headless environment with a separate Clerk OAuth application.
-This uses an OAuth public client with PKCE, so the CLI stores no client secret.
-
-In **Clerk Dashboard > OAuth applications**:
-
-1. Create an OAuth application for the T3 CLI.
-2. Enable the **Public** option so authorization-code exchange uses PKCE.
-3. Add **both** allowed redirect URIs:
-   - `http://127.0.0.1:34338/callback` for the loopback listener;
-   - `https://app.t3.codes/connect/callback` for the hosted out-of-band flow. This is
-     `connectCallbackUrl(DEFAULT_HOSTED_APP_URL)` from `packages/shared/src/connectAuth.ts`, so a
-     custom `T3CODE_HOSTED_APP_URL` means `$T3CODE_HOSTED_APP_URL/connect/callback` instead.
-     Omitting it breaks headless and SSH authorization.
-4. Enable the `openid`, `profile`, and `email` scopes.
-5. Set `T3CODE_CLERK_CLI_OAUTH_CLIENT_ID` in the repository-root `.env` file and release build
-   environment to the generated public client ID.
-
-Both CLI flows start at the hosted `/connect` page (`buildConnectAuthorizeRequestUrl` in
-`packages/shared/src/connectAuth.ts`), which waits for a Clerk session and then forwards the request
-to Clerk's `/oauth/authorize`. The CLI never opens `/oauth/authorize` directly: a signed-out browser
-sent there goes through Clerk's sign-in redirect, which drops the authorize query parameters and
-fails the flow with `unsupported_response_type` or an empty `state` (#5051). The loopback flow marks
-the request with a `port` fragment parameter so the hosted page asks Clerk to redirect the
-authorization code straight to `http://127.0.0.1:<port>/callback`; the out-of-band flow omits it and
-uses the hosted `/connect/callback` page instead. The CLI derives Clerk's frontend API URL from the
-publishable key and calls only the `/oauth/token` endpoint directly. The relay is not involved in
-the OAuth handshake; it only validates the issued Clerk bearer token when the CLI manages an
-environment link.
-
-The connect command group is:
-
-```sh
-t3 connect            # default: onboarding
-t3 connect login
-t3 connect link       # --publish-only
-t3 connect status     # --json
-t3 connect publish    # --disable
-t3 connect unlink
-t3 connect logout
-```
-
-`t3 serve` is a separate top-level command, not a connect subcommand.
-
-`t3 connect login` opens the Clerk authorization flow and stores the CLI credential without enabling
-cloud exposure. `t3 connect link` installs the pinned managed `cloudflared` binary when needed,
-authorizes when needed, and records durable intent to expose the environment. It works without a
-running T3 server. The next `t3 serve` or `t3 start` reconciles the relay link and launches the
-managed tunnel. `t3 connect unlink` records disabled intent immediately, stops a reachable running
-connector, and attempts to revoke the relay-side environment record. It retains the stored CLI
-authorization so `t3 connect link` can re-enable exposure without another browser flow. `t3 connect
-logout` performs the same cleanup and removes the stored CLI authorization.
-
-The background service has an independent lifecycle. Connect setup may offer to install it, but
-logout leaves it running; manage it with `t3 service status`, `install`, `update`, and `uninstall`.
-
-### Headless and SSH authorization
-
-The loopback OAuth callback listener binds to port `34338`. That path only works when a browser on
-the same machine can reach it, so `authorizeCli` in `apps/server/src/cli/connect.ts` automatically
-selects the out-of-band flow when `--headless` is passed or when it detects SSH through
-`SSH_CONNECTION` or `SSH_TTY`. The out-of-band flow prints the hosted `/connect` authorization URL
-and accepts a pasted authorization code, so no port is involved.
-
-Port forwarding is therefore optional, not required. Forward the port only if you specifically want
-the loopback flow over SSH:
-
-```sh
-ssh -L 34338:127.0.0.1:34338 <host>
-```
-
-## JWT Template
-
-In **Clerk Dashboard > JWT templates**, create a template with:
-
-| Setting | Value                        |
-| ------- | ---------------------------- |
-| Name    | `t3-relay`                   |
-| Claims  | `{ "aud": "t3-code-relay" }` |
-
-Set `T3CODE_CLERK_JWT_TEMPLATE=t3-relay` in the repository-root `.env`, and set
-`CLERK_JWT_AUDIENCE=t3-code-relay` in `infra/relay/.env`. Define `CLERK_JWT_TEMPLATE` and
-`CLERK_JWT_AUDIENCE` in the production relay deployment environment as well. The stable `aud` value
-is shared by production and non-production relay stages. The client-facing `T3CODE_RELAY_URL` still
-selects the concrete relay deployment, but changing that URL does not require a JWT template change.
-
-## Desktop OAuth Redirect Allowlist
-
-The desktop app opens OAuth in the system browser and returns to the app with a custom URL scheme.
-In **Clerk Dashboard > Native applications**, enable the Native API and add these entries under the
-mobile SSO redirect allowlist:
-
-```text
-t3code-dev://app/
-t3code://app/
-```
-
-Local desktop development uses `t3code-dev://app`, while packaged builds use `t3code://app`. Add the
-matching origin to each Clerk instance's Backend API `allowed_origins` array as well. The development
-Clerk instance should only need `t3code-dev://app`; the production Clerk instance should only need
-`t3code://app`. `@clerk/electron` owns the native request adapter, encrypted Clerk token persistence,
-external-browser OAuth transport, and callback delivery for initial sign-in and linked-account flows.
-
-There is currently no Dashboard UI for `allowed_origins`. Preserve any existing entries and update
-the instance through the Backend API:
-
-```sh
-curl -X PATCH https://api.clerk.com/v1/instance \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $CLERK_SECRET_KEY" \
-  -d '{"allowed_origins":["t3code://app"]}'
-```
-
-Never put `CLERK_SECRET_KEY` in the desktop app, a client-facing environment file, or a build
-artifact.
-
-## Desktop Passkeys
-
-The production macOS bundle ID is `com.t3tools.t3code`. To enable native passkeys:
-
-1. Create an explicit macOS App ID for `com.t3tools.t3code` in the Apple Developer portal and enable
-   **Associated Domains**.
-2. Create a compatible macOS provisioning profile for that App ID and the certificate used to sign
-   the distributed app.
-3. In Clerk's Native API settings, add an iOS app with the same Apple Team ID and bundle ID. This is
-   also the configuration point for Electron/macOS passkeys.
-4. Confirm Clerk serves `https://<frontend-api>/.well-known/apple-app-site-association` and that
-   `webcredentials.apps` contains `<TEAM_ID>.com.t3tools.t3code`.
-5. Set the local or CI signing configuration described below.
-
-For a local signed build, add these values to `.env.local` or export them before invoking the
-desktop artifact command:
-
-```dotenv
-T3CODE_APPLE_TEAM_ID=ABC1234567
-T3CODE_MACOS_PROVISIONING_PROFILE=/absolute/path/to/t3code.provisionprofile
-# Optional: comma-separated override when Clerk's RP ID differs from the Frontend API hostname.
-T3CODE_CLERK_PASSKEY_RP_DOMAINS=example.clerk.accounts.dev,clerk.example.com
-```
-
-When `T3CODE_CLERK_PASSKEY_RP_DOMAINS` is absent, the build derives the RP domain from
-`T3CODE_CLERK_PUBLISHABLE_KEY`. Signed macOS builds fail early if the Team ID, provisioning profile,
-or RP-domain configuration is missing. The generated main-app entitlements include every configured
-`webcredentials:<domain>` entry; helper apps keep Electron's minimal default entitlements.
-
-The normal `dev:desktop` launcher is unsigned and cannot complete macOS passkey ceremonies. For
-renderer HMR, build and install a signed app first, run the renderer dev server, then launch the
-installed app executable with `VITE_DEV_SERVER_URL` and `T3CODE_PORT` set. Rebuild the signed app
-after native dependency, main-process, preload, entitlement, provisioning, or signing changes;
-renderer-only changes can reuse the installed app.
-
-For the default development ports, run `pnpm dev:web` in one terminal and launch the installed
-binary from another:
-
-```sh
-VITE_DEV_SERVER_URL=http://127.0.0.1:5733 \
-T3CODE_PORT=13773 \
-  "/Applications/T3 Code (Alpha).app/Contents/MacOS/T3 Code (Alpha)"
-```
-
-After changing Associated Domains, bump the build version before rebuilding; macOS may otherwise
-reuse stale Shared Web Credentials metadata for the same app/version pair.
-
-Verify the installed bundle before testing:
-
-```sh
-codesign --verify --deep --strict "/Applications/T3 Code (Alpha).app"
-codesign -d --entitlements :- "/Applications/T3 Code (Alpha).app"
-```
-
-The current mobile UI uses Clerk's native authentication view. If a future mobile browser OAuth
-flow uses a custom redirect URI, add that exact URI to the same allowlist.
-
-## Sign-in Surfaces
-
-Signed-in users manage T3 Connect under **Connections**. The settings sidebar also has dedicated
-controls, rendered by `SettingsSidebarNav.tsx`: `T3ConnectSidebarSignIn` in the footer shows a
-**Sign in to T3 Connect** button while signed out, and `T3ConnectSidebarAvatar` shows a Clerk
-`UserButton` account control while signed in. Both are gated on cloud public configuration.
-Desktop renders the same web bundle, so it has them too. The waitlist enrollment flow from the
-private beta was removed when Connect went GA; sign-up is open unless a Clerk restriction below is
-enabled.
-
-## Restricting Sign-ups: Known-User Allowlist
-
-For a closed deployment where all permitted users are known in advance, restrict sign-up to
-permitted email addresses or domains:
-
-1. In **Clerk Dashboard > Restrictions > Allowlist**, add each permitted email address or email
-   domain.
-2. Enable the allowlist and save.
-3. Alternatively, enable **Restricted mode** when all new users must be explicitly invited or
-   manually created.
-
-Do not enable an empty allowlist: it blocks all new sign-ups.
-
-Clerk allowlists control who can sign up. They do not revoke an existing user's active cloud
-access. To remove an already-created user's access, ban that user in Clerk so their active
-sessions are ended and future sign-ins are rejected.
+T3 Connect uses Clerk for cloud identity. The relay manages environment links,
+credentials for reaching environments, and managed tunnel allocations. After
+bootstrap, clients send application traffic through the environment's tunnel
+hostname; the relay Worker does not proxy their HTTP or WebSocket sessions.
+
+Clerk, deployment, and native authentication setup live in the
+[Connect setup runbook](../operations/connect-setup.md).
+
+## The relay is a trusted broker
+
+An authenticated cloud user still needs an active environment link. The relay
+asks that environment to mint a one-time bootstrap credential bound to the
+client's DPoP key. The client exchanges it directly with the environment for an
+[environment session](./environment-auth.md). The relay never receives that
+session token, and possessing the bootstrap credential alone does not permit
+redeeming it without the client's private key.
+
+Both sides authenticate this exchange. The environment accepts only bounded,
+replay-guarded relay proofs for its own identity, linked user, and requested
+operation. Signed environment responses bind the result to the request nonce;
+mint responses also bind the credential to the client proof key. The relay
+verifies those bindings before returning a credential. This prevents a different
+process behind the tunnel from impersonating the linked environment. The checks
+meet in the
+[environment cloud handlers](../../apps/server/src/cloud/http.ts) and
+[relay connector](../../infra/relay/src/environments/EnvironmentConnector.ts).
+
+The relay holds the signing authority for mint requests. DPoP protects an honest
+exchange from credential reuse; it does not make a compromised relay signing
+key harmless. Keep that trust assumption explicit when changing the protocol.
+
+Managed tunnels expose only a validated loopback HTTP origin. Link proof checks
+reject forwarded authority headers, and the relay resolves endpoints from its
+own managed allocations rather than a caller-supplied URL. Health and mint
+requests must not follow redirects. These restrictions keep endpoint discovery
+from turning into arbitrary relay egress or exposing another service on the
+environment host.
+
+## A link outlives a connector process
+
+CLI authorization, desired exposure, and a running connector have different
+lifetimes. Linking can record intent while the server is stopped. Startup
+reconciles that intent. CLI logout removes the stored cloud credential and
+disables exposure without uninstalling the environment's background service.
+
+Managed allocations belong to a user/environment pair. Provisioning checkpoints
+external tunnel and DNS resources so retries can reconcile partial work. A
+normal shutdown of a CLI-managed link releases its tunnel to avoid paying for
+an idle resource, retaining the hostname reservation for the next startup.
+It also retains the allocation record so the environment remains "offline"
+rather than becoming "not authorized".
+
+Two cases must retain the tunnel across shutdown. A link installed through a
+client has no startup provisioning path and depends on its stored connector
+token. An update handoff immediately starts a replacement server, and replacing
+the tunnel would add routing propagation delay to every update. These exceptions
+belong to [shutdown handling](../../apps/server/src/cloud/http.ts).
+
+Release and unlink claim the allocation generation before deleting external
+resources. A delayed cleanup must not delete a tunnel reused by a concurrent
+restart or relink. Unlink commits authorization revocation before external
+teardown, because a database failure must leave the active link usable. Failed
+teardown retains enough state to retry. See the
+[managed endpoint lifecycle](../../infra/relay/src/environments/ManagedEndpointProvider.ts).
+
+## OAuth traps
+
+Interactive clients and the headless CLI use the same Clerk application but
+different credentials. The relay accepts both session-template JWTs and CLI
+OAuth tokens; requiring a JWT template for the CLI would reject valid logins.
+The CLI is a public OAuth client using PKCE and stores no client secret.
+
+CLI authorization starts on the hosted `/connect` page so sign-in completes
+before entering Clerk's authorize endpoint. Sending a signed-out browser
+straight to that endpoint loses the authorize parameters during the sign-in
+redirect. The [shared flow](../../packages/shared/src/connectAuth.ts) preserves
+PKCE and state for both loopback and pasted-code callbacks. SSH and headless
+sessions use the pasted-code flow because the browser cannot ordinarily reach a
+listener on the remote machine.
diff --git a/docs/internals/terminal-runtime.md b/docs/internals/terminal-runtime.md
index addfa1ce093a..ca5f0d46ead6 100644
--- a/docs/internals/terminal-runtime.md
+++ b/docs/internals/terminal-runtime.md
@@ -1,52 +1,44 @@
 # Terminal runtime
 
-The environment server owns terminal processes, retained output history, and
-session lifecycle. Web, desktop, and mobile clients attach to the same
-server-owned session over the environment RPC connection. The desktop renderer
-does not own a separate PTY. Clients can reconnect to a running PTY or share
-it with another client.
-
-## Output path
-
-PTY output follows this path:
-
-```text
-PTY callback
-  -> ordered process-event drain
-  -> bounded retained-history append
-  -> live terminal output event
-  -> coalesced history persistence
-```
-
-Live output events contain only the new PTY data. Full retained history is
-materialized only when the server returns a snapshot or when the coalescing
-persistence worker writes the latest state.
-
-Retained history is limited to 5,000 lines and 8 MiB of UTF-8 text per terminal.
-The server discards the oldest output when either limit is reached. A byte
-cutoff can shorten the oldest retained line, but does not split a Unicode code
-point. Live output is not truncated.
-
-History uses small chunks with byte and newline counts. Appending output scans
-the new text and any removed chunk prefix, not the full retained history.
-Empty lines, incomplete final lines, and trailing newlines remain unchanged
-within the limits. Split surrogate pairs are joined before byte eviction.
-
-Discard each chunk's string reference as soon as it leaves retained history.
-Array compaction can run later. Shared web and mobile client state retains at
-most 512 KiB, so each client can display less scrollback than the server keeps.
-
-Measure sustained-output changes against a full retained history so terminal
-throughput does not regress unnoticed.
-
-## Persistence
-
-History persistence is keyed by terminal session and coalesces pending writes.
-The worker reads the newest bounded-history state after its debounce instead
-of receiving a newly materialized full string for every PTY callback. Clear,
-restart, close, and final flush operations still force the latest state to
-disk before their lifecycle boundary completes.
-
-Restoration reads at most the last 8 MiB from current and legacy history files.
-It skips an incomplete UTF-8 code point at the start and applies the line limit
-before rewriting oversized files. File handles close before that rewrite.
+The environment server owns PTYs, session lifetime, and retained output. Every
+client, including the desktop renderer, attaches through the environment connection.
+This lets clients reconnect or share a running session. Renderer choices stay local
+to each client and do not change terminal contracts.
+
+## Output and retention
+
+[Terminal history](../../apps/server/src/terminal/Manager.ts) is incremental.
+PTY callbacks append new chunks; live events carry only those chunks. Materializing
+or copying full scrollback on every callback makes output cost grow with retained
+history, so snapshots and coalesced persistence are the materialization boundaries.
+Persistence queues the mutable history buffer and reads its latest value when the
+write runs. Clear, restart, and close must drain writes before completing their
+lifecycle boundary.
+
+Server history is capped at 5,000 lines and 8 MiB of UTF-8 text per terminal, so a
+long unterminated line cannot bypass retention. Eviction removes the oldest output
+without splitting Unicode code points; live output is not truncated. Release
+discarded chunk references immediately, even if array compaction happens later.
+Client buffers have a separate 512 KiB cap. Measure throughput with full scrollback
+when changing this path.
+
+Restoration must read only the bounded tail of current or legacy history files,
+skip any incomplete UTF-8 prefix, and apply the line limit. Close the read handle
+before rewriting the capped file. Reading whole old logs would defeat the memory
+bound during startup.
+
+## Renderer ownership
+
+Android and web use the same `libghostty-vt` C ABI for terminal behavior. Platform
+adapters own drawing and input integration, and React stays out of terminal frames.
+The web adapter shares one WebAssembly instance per browser tab while each terminal
+owns and frees its own handles. The canonical upstream pin is
+[`native/libghostty-vt/VERSION`](../../native/libghostty-vt/VERSION); both native and
+web artifacts must be rebuilt when it changes. Web embeds the revision in its build
+info so the ABI check can detect drift without a second pin.
+
+Restoring scrollback must not send terminal replies to the current shell. Historical
+device queries can otherwise provoke fresh replies that appear as junk at the
+prompt. The server strips query/response traffic from retained history, and the
+[web renderer](../../apps/web/src/terminal/ghostty/core.ts) detaches its PTY writer
+during replay. Preserve both protections when changing retention or renderer code.
diff --git a/docs/internals/voice-input.md b/docs/internals/voice-input.md
index dd37f2a86957..55e3007a4872 100644
--- a/docs/internals/voice-input.md
+++ b/docs/internals/voice-input.md
@@ -1,102 +1,20 @@
 # Voice input
 
-> For maintainers. Using T3 Code? See [voice input on iPhone](../user/composer.md#voice-input-on-iphone).
-
-Voice input produces editable composer text. The current implementation records on the client and
-transcribes locally with Apple's `SpeechAnalyzer` and `SpeechTranscriber` on supported iOS 26+
-devices. Environment-provided transcription and transcription on web and desktop are not implemented.
-
-## Current boundaries
-
-The shared [`VoiceInputController`][controller] in `packages/client-runtime` owns preparation,
-recording, transcription, cancellation, temporary-file cleanup, and insertion into the captured
-draft selection. Applications import it through the [voice-input entry point][voice-input] as
-`@t3tools/client-runtime/voice-input`. Its dependencies separate capture from transcription; the
-controller imports neither React Native nor an Apple transcription API.
-
-The shared [transcription contract][transcription] defines `VoiceTranscriber`,
-`PreparedVoiceTranscription`, and transcription errors. The controller calls `getTranscriber()` once
-at the start of an operation, before asking for microphone permission. Preparation returns a resolved
-locale and a bound `transcribe` function. The controller retains that result for the recording, so a
-selection change cannot prepare with one implementation and transcribe with another.
-
-[`useVoiceInputController`][hook] supplies Expo audio capture, microphone permissions, audio-session
-management, waveform samples, and app and navigation lifecycle handling. It normalizes Expo's
-`mediaServicesDidReset` into a generic recorder error. [`voiceTranscription.ios.ts`][ios] adapts
-`@react-native-ai/apple` through `getLocalVoiceTranscriber()`, capturing the requested device locale
-and binding the prepared transcriber to Apple's resolved locale. The other-platform binding returns
-no local transcriber. That result describes the local implementation, not whether a client could use
-an environment's transcription service.
-
-Mobile's [`voiceInputPresentation.ts`][presentation] maps shared state to toolbar labels and actions.
-Waveform and toolbar rendering stay in mobile. The composer edits draft text without selecting a
-speech vendor.
-Recording captures the draft owner, revision, text, and selection. A late transcript cannot overwrite
-a different or edited draft. Only normal message submission sends the resulting text to an agent.
-
-Each operation passes one `AbortSignal` through preparation and transcription. Cancellation
-invalidates the operation and aborts that signal immediately. Implementations settle their promises
-only after their underlying work stops. The Apple binding checks cancellation between asynchronous
-steps but cannot interrupt an in-flight native request. The controller retains its session until
-that work settles, ignores its result, and cleans up the recording.
-
-## Ownership decisions
-
-The extension boundary distinguishes transcription on the client device from transcription through
-the composer's environment. These constraints apply when adding selectable transcription services:
-
-- Local means the client device, regardless of which machine hosts the environment. A device's lack
-  of local recognition does not prevent it from recording audio for an environment service.
-- Remote service configuration and API keys belong to the environment. The environment calls the
-  external service. Clients receive service identifiers, labels, and availability information, never
-  credential values. Transcription services are independent of coding-agent `providerInstances`;
-  selecting OpenAI for transcription does not select Codex for the thread.
-- The client owns its transcription preference, scoped by stable `environmentId`. Its choices are
-  supported local recognition and the services exposed by the composer's environment. A service ID
-  is meaningful only within that environment. Different clients can make different choices.
-- Resolve and capture the environment, selected service, and locale when an operation starts.
-  Preparation and transcription use the same selection; preference changes affect the next
-  recording. Capture environment identity explicitly rather than recovering it from a draft key.
-  Keep the existing draft-owner and revision checks before inserting text.
-- If the selected option is unavailable, report that state and let the user choose another option.
-  A local failure must not silently upload audio, and a disconnected environment must not redirect
-  a recording to another environment or service.
-- Transcription audio is temporary input, separate from durable chat attachments and messages.
-  Remote adapters need cancellation of upload and transcription where supported, cleanup after
-  success, failure, or cancellation, and the same protection against late results as local transcription.
-
-## Existing integration points
-
-[`ServerSettingsService`][settings] and [`ServerSecretStore`][secrets] provide environment-owned
-configuration and secret persistence. Existing settings redaction handles coding-provider environment
-variables only. Any transcription credential fields need their own explicit separation and redaction
-before settings responses or subscriptions reach client caches.
-
-[`ExecutionEnvironmentCapabilities`][capabilities] handles version skew. Remote transcription must be
-opt-in: a missing transcription capability means unsupported. The authenticated server-config
-subscription and [shared environment state][server-state] already distribute configuration per
-environment. A transcription service catalog belongs behind that capability and authenticated
-boundary. Older servers expose no remote transcription choices.
-
-The [attachment upload contracts][uploads] and [shared upload operations][attachment-state] provide a
-pattern for authorized binary uploads through an environment, including remote connections. Their
-existing chat-attachment retention is not a transcription cleanup policy.
-
-Future service selection and environment requests belong alongside the controller in
-`packages/client-runtime`, with wire contracts in `packages/contracts`. Capture and native local
-recognition remain client-specific. An environment-backed transcriber implements the same shared
-contract, with its environment and service bound when selected. The controller does not own service
-credentials, provider SDKs, or transport selection.
-
-[controller]: ../../packages/client-runtime/src/voice-input/controller.ts
-[voice-input]: ../../packages/client-runtime/src/voice-input/index.ts
-[transcription]: ../../packages/client-runtime/src/voice-input/transcription.ts
-[hook]: ../../apps/mobile/src/features/voice-input/useVoiceInputController.ts
-[presentation]: ../../apps/mobile/src/features/voice-input/voiceInputPresentation.ts
-[ios]: ../../apps/mobile/src/native/voiceTranscription.ios.ts
-[settings]: ../../apps/server/src/serverSettings.ts
-[secrets]: ../../apps/server/src/auth/ServerSecretStore.ts
-[capabilities]: ../../packages/contracts/src/environment.ts
-[server-state]: ../../packages/client-runtime/src/state/server.ts
-[uploads]: ../../packages/contracts/src/assets.ts
-[attachment-state]: ../../packages/client-runtime/src/state/attachments.ts
+Transcription edits a composer draft. It does not submit an agent turn. Audio is
+temporary client input, and only normal message submission sends the resulting
+text. The current implementation transcribes locally on supported iOS devices;
+environment-backed transcription is not implemented.
+
+The [shared controller](../../packages/client-runtime/src/voice-input/controller.ts)
+owns the operation while the client supplies capture and transcription. Preparation
+binds the transcriber and resolved locale for the whole recording. Draft ownership,
+text, and revision are captured before recording and checked before insertion, so
+a late transcript cannot overwrite a draft that was edited or replaced.
+
+Cancellation invalidates a result immediately, but resources stay owned until the
+underlying work settles. Apple's native transcription call cannot be interrupted
+once started. Releasing the session or deleting its recording when the abort signal
+fires would race that work. The [transcription contract](../../packages/client-runtime/src/voice-input/transcription.ts)
+therefore requires implementations to settle only after their work has stopped;
+the [Apple binding](../../apps/mobile/src/native/voiceTranscription.ios.ts) checks
+cancellation between native calls and discards late results.
diff --git a/docs/internals/work-artifacts.md b/docs/internals/work-artifacts.md
deleted file mode 100644
index 157a6174507d..000000000000
--- a/docs/internals/work-artifacts.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# Engineering work artifacts
-
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-Keep planned work out of the source tree. Code search should return the product as it exists, not a mix of current behavior and abandoned intentions.
-
-## Current facts belong in the docs
-
-Put durable architecture, constraints, and operational knowledge in `docs/internals/` or `docs/operations/`. Write these documents in the present tense and update them with the code they describe.
-
-When the reason for a decision will matter after implementation, record it in the relevant internal document. Use a separate decision record under `docs/internals/` only when the rationale does not fit cleanly beside the current architecture.
-
-## Planned work belongs in GitHub
-
-Track active maintainer work in its GitHub issue or project item. The tracking item should state the outcome, constraints, and acceptance criteria, then link the pull requests that implement it. Split large efforts into one durable specification and small work items that can each close independently.
-
-Close completed items. Update or delete invalidated work before starting the next implementation session. External proposals follow [CONTRIBUTING.md](../../CONTRIBUTING.md) and belong in Ideas discussions rather than issues.
-
-## Temporary work stays temporary
-
-Keep agent scratch files, exploratory research, transcripts, and session handoff notes outside the worktree. They are inputs to the work, not project documentation.
-
-`.plans/` is gitignored as a safety net for legacy tools. Its presence does not make it an accepted project artifact. Pull requests must not add implementation plans or temporary research under another name.
-
-A pull request records what changed and why. If a fact must survive after the pull request merges, update the relevant documentation. Otherwise, the tracking item and pull request are the record.
diff --git a/docs/internals/workspace-layout.md b/docs/internals/workspace-layout.md
deleted file mode 100644
index e933e4528915..000000000000
--- a/docs/internals/workspace-layout.md
+++ /dev/null
@@ -1,63 +0,0 @@
-# Workspace layout
-
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-A pnpm workspace driven by [vite-plus](https://vite.plus) (`vp`). See [scripts.md](./scripts.md) for
-the task commands.
-
-## apps
-
-- `apps/server` (`t3`): the execution runtime and the published CLI. Owns orchestration, provider
-  drivers, checkpointing, VCS, terminals, filesystem access, auth, and the HTTP + WebSocket surface.
-  Also serves the built web app.
-- `apps/web` (`@t3tools/web`): React + Vite UI. Consumes the shared client runtime and adds routing,
-  components, and web-specific platform layers.
-- `apps/desktop` (`@t3tools/desktop`): Electron shell. Supervises a desktop-scoped `t3` backend,
-  loads the web bundle over the `t3code://` protocol, and owns SSH-managed remote environments.
-- `apps/mobile` (`@t3tools/mobile`): Expo/React Native client. Same client runtime composition as
-  web, different platform layer and UI.
-- `apps/marketing` (`@t3tools/marketing`): Astro marketing site.
-
-## packages
-
-- `packages/contracts` (`@t3tools/contracts`): shared Effect Schema definitions. RPC group,
-  orchestration commands/events/read model, auth scopes, environment descriptors, settings.
-- `packages/shared` (`@t3tools/shared`): framework-agnostic utilities used by server and clients
-  (`DrainableWorker`, git and source-control helpers, relay auth and signing, DPoP, semver, logging,
-  observability, and more).
-- `packages/client-runtime` (`@t3tools/client-runtime`): connection lifecycle, authorization, RPC
-  session, environment registry, and Atom-based domain state shared by web and mobile. See its
-  [README](../../packages/client-runtime/README.md).
-- `packages/ssh` (`@t3tools/ssh`): SSH config parsing, auth prompts, command execution, and the
-  tunnel/environment manager behind desktop-managed SSH environments.
-- `packages/tailscale` (`@t3tools/tailscale`): Tailscale CLI wrapper, including the
-  `ensureTailscaleServe` / `disableTailscaleServe` serve lifecycle the server drives.
-- `packages/effect-acp` (`effect-acp`): Effect client and agent implementation of the Agent Client
-  Protocol, used by ACP-speaking provider drivers.
-- `packages/effect-codex-app-server` (`effect-codex-app-server`): Effect client for the
-  `codex app-server` JSON-RPC protocol.
-
-## infra
-
-- `infra/relay` (`t3code-relay`): the hosted T3 Connect relay, deployed with Alchemy. Handles
-  environment discovery, cloud-side records, and mobile notifications. It is not in the hot path;
-  after connect, client traffic goes directly to the environment. See
-  [t3-connect.md](./t3-connect.md).
-
-## Other top-level directories
-
-- `scripts/`: workspace tooling run through `vp run`. Dev runner, desktop artifact builds, release
-  helpers, mobile static checks and showcase capture, update-manifest merging.
-- `assets/`: brand and app icon sources per channel (`dev`, `nightly`, `prod`).
-- `patches/`: pnpm patches for pinned upstream dependencies.
-- `oxlint-plugin-t3code/`: repo-specific lint rules.
-- `experiments/`: throwaway prototypes. Not part of the shipped build.
-- `docs/`: this documentation tree.
-
-## Import conventions
-
-`@t3tools/shared` and `@t3tools/client-runtime` use explicit subpath exports with no barrel index and
-no root export. Import the narrow path (`@t3tools/shared/DrainableWorker`,
-`@t3tools/client-runtime/state/threads`) rather than the package root. Files that are not exported
-are implementation details. `@t3tools/contracts` does export a root alongside `./settings` and
-`./relay`.
diff --git a/docs/operations/connect-setup.md b/docs/operations/connect-setup.md
new file mode 100644
index 000000000000..49b93e49c9c4
--- /dev/null
+++ b/docs/operations/connect-setup.md
@@ -0,0 +1,126 @@
+# T3 Connect setup
+
+Deployment and client configuration for T3 Connect. The [architecture note](../internals/t3-connect.md)
+explains the trust boundaries; the [relay README](../../infra/relay/README.md#deployment) owns relay
+provisioning instructions.
+
+## Public application configuration
+
+T3 Connect is disabled in a fresh clone. To build against the production deployment, copy the
+repository-root example:
+
+```sh
+cp .env.example .env
+```
+
+For another deployment, set these values in the repository-root `.env` or `.env.local`:
+
+```dotenv
+T3CODE_CLERK_PUBLISHABLE_KEY=<publishable key>
+T3CODE_CLERK_JWT_TEMPLATE=<JWT template name>
+T3CODE_CLERK_CLI_OAUTH_CLIENT_ID=<public OAuth application client ID>
+T3CODE_RELAY_URL=https://relay.example.com
+```
+
+Process variables take precedence over `.env.local`, then `.env`. Use these canonical names;
+the build loader supplies framework-specific aliases. These values are public identifiers.
+`CLERK_SECRET_KEY` belongs only in the relay's secrets, never in client configuration.
+
+Client and bundled-server builds embed the public values, so set them before building.
+EAS preview and production environments need the publishable key, JWT template name, and relay URL.
+Bundled servers also accept runtime overrides for operator-managed deployments.
+
+Copy `infra/relay/.env.example` to `infra/relay/.env` for relay deployment settings.
+Deploy `prod` before personal stages because it owns the retained database that their branches
+depend on. The deploy wrapper writes the resulting relay URL back to the root `.env`.
+
+## CLI OAuth application
+
+In Clerk's OAuth applications settings:
+
+1. Create a public OAuth application for the T3 CLI, using authorization-code exchange with PKCE.
+2. Allow both redirect URIs: `http://127.0.0.1:34338/callback` and
+   `https://app.t3.codes/connect/callback`. A custom `T3CODE_HOSTED_APP_URL` needs its own
+   `/connect/callback` URL. Headless and SSH authorization depend on the hosted redirect.
+3. Enable the `openid`, `profile`, and `email` scopes.
+4. Set `T3CODE_CLERK_CLI_OAUTH_CLIENT_ID` to the generated public client ID in local and release
+   build environments.
+
+## JWT template
+
+Create a Clerk JWT template named `t3-relay` with claims:
+
+```json
+{ "aud": "t3-code-relay" }
+```
+
+Set `T3CODE_CLERK_JWT_TEMPLATE=t3-relay` for clients and
+`CLERK_JWT_AUDIENCE=t3-code-relay` for the relay. The production relay deployment environment
+also defines `CLERK_JWT_TEMPLATE`. The audience stays the same across relay stages; the relay
+URL selects the deployment.
+
+## Desktop OAuth redirects
+
+Enable Clerk's Native API and add the desktop redirects to its SSO redirect allowlist:
+
+```text
+t3code-dev://app/
+t3code://app/
+```
+
+Add the corresponding origin to the Clerk instance's Backend API `allowed_origins` array.
+Development uses `t3code-dev://app`; production uses `t3code://app`. Update the array with
+`PATCH https://api.clerk.com/v1/instance` using the Clerk secret key, preserving existing entries.
+The Clerk Electron integration handles token
+persistence and system-browser callback delivery.
+
+## Desktop passkeys
+
+For a production macOS app with bundle ID `com.t3tools.t3code`:
+
+1. Create an explicit macOS App ID in the Apple Developer portal with **Associated Domains**.
+2. Create a provisioning profile for that App ID and the distribution signing certificate.
+3. In Clerk's Native API settings, add an iOS app with the same Apple Team ID and bundle ID.
+   This setting also configures Electron/macOS passkeys.
+4. Check `https://<frontend-api>/.well-known/apple-app-site-association`. Its
+   `webcredentials.apps` must include `<TEAM_ID>.com.t3tools.t3code`.
+5. Configure signing as described in the [release runbook](./release.md#2-apple-signing--notarization-setup-macos).
+
+Local signed builds additionally use:
+
+```dotenv
+T3CODE_APPLE_TEAM_ID=ABC1234567
+T3CODE_MACOS_PROVISIONING_PROFILE=/absolute/path/to/t3code.provisionprofile
+# Override only when the RP domain differs from the Clerk Frontend API hostname.
+T3CODE_CLERK_PASSKEY_RP_DOMAINS=example.clerk.accounts.dev,clerk.example.com
+```
+
+Without the override, the build derives the RP domain from the Clerk publishable key.
+After changing Associated Domains, bump the build version before rebuilding. macOS can otherwise
+reuse stale Shared Web Credentials metadata for the same app/version pair.
+
+The ordinary `dev:desktop` launcher is unsigned and cannot exercise macOS passkeys. For renderer
+HMR, install a signed build, start `vp run dev:web`, and launch the installed executable with the
+actual web and server ports. For example, with the default ports:
+
+```sh
+VITE_DEV_SERVER_URL=http://127.0.0.1:5733 \
+T3CODE_PORT=13773 \
+  "/Applications/T3 Code (Alpha).app/Contents/MacOS/T3 Code (Alpha)"
+```
+
+Rebuild the signed app after native dependency, main-process, preload, entitlement, provisioning,
+or signing changes. Renderer edits can reuse it. Verify the installed bundle before testing:
+
+```sh
+codesign --verify --deep --strict "/Applications/T3 Code (Alpha).app"
+codesign -d --entitlements :- "/Applications/T3 Code (Alpha).app"
+```
+
+## Restricting sign-ups
+
+Use Clerk's allowlist for permitted email addresses or domains, or Restricted mode for invitation-only
+sign-up. An enabled empty allowlist blocks all new sign-ups.
+
+Sign-up restrictions do not revoke an existing account's access. Ban the account in Clerk when
+its active sessions and future sign-ins must be disabled.
diff --git a/docs/operations/development.md b/docs/operations/development.md
new file mode 100644
index 000000000000..dec3e8681fd3
--- /dev/null
+++ b/docs/operations/development.md
@@ -0,0 +1,140 @@
+# Development
+
+## First checkout
+
+Install `vp` using the [root README](../../README.md#install-vp). The checkout requires Node 24;
+Bun is optional. From the repository root:
+
+```sh
+vp i
+vp run dev
+```
+
+Open the one-time pairing URL printed by the dev runner. The bare origin does not authenticate
+a new browser.
+
+## Choosing a dev process
+
+Use `vp run dev` for server and web, or `vp run dev:desktop` for the Electron client.
+`dev:server` and `dev:web` start those processes separately.
+See the [mobile README](../../apps/mobile/README.md) for native builds and Metro.
+
+Flags go directly after the task name, for example `vp run dev --home-dir /tmp/t3code-dev`.
+Add `--browser` to open a browser automatically.
+
+### State and ports
+
+Linked worktrees default to their own `.t3/userdata`, even when `T3CODE_HOME` is set.
+The main checkout defaults to `~/.t3/dev/userdata`. An explicit `--home-dir` wins in both cases.
+Never run a development server against the live `~/.t3/userdata`.
+See [test data](../../AGENTS.md#test-data) for copying a consistent database snapshot.
+
+Read ports from the `[dev-runner]` output. Worktrees derive stable preferences from their paths,
+but occupied ports can shift them. `T3CODE_PORT_OFFSET` or `T3CODE_DEV_INSTANCE` can select a
+different preference when needed.
+
+### Sharing and remote debugging
+
+`vp run dev --share` publishes the web port over the machine's tailnet and prints a pairing URL
+for that origin. Give the tester the complete URL, including its token. The dev runner removes
+its mapping on exit.
+
+Leave `VITE_HTTP_URL` and `VITE_WS_URL` unset. Vite proxies the backend through the browser's
+origin so the same build works over localhost and remote connections.
+
+Shared runs enable bundled dev to avoid a network round trip for each import level.
+`T3CODE_BUNDLED_DEV=0` opts out when debugging bundler differences. Two reload traps matter
+when changing this setup:
+
+- The web entry must dynamically import the app so React refresh initializes before application
+  chunks. Static imports can work on first load and fail after a route split.
+- Bundled dev rebuilds Tailwind through watched files. Its ordinary Vite hot-update hook expects
+  a server/module graph that Rolldown does not provide.
+
+The workarounds live in the [web entry](../../apps/web/src/bootstrap.ts) and
+[Tailwind plugin](../../apps/web/vite/tailwind.ts).
+
+## Checks
+
+Run checks for the files and packages you changed:
+
+```sh
+vp test run <files>
+vp lint <files>
+vp run --filter <package> typecheck
+```
+
+Use `vp run lint:mobile` for native mobile changes. CI owns the full suite; see
+[ci.yml](../../.github/workflows/ci.yml) for its current jobs.
+The [manual Windows lane](../../.github/workflows/windows-tests.yml) is available for focused
+Windows investigation while that suite is not a required gate.
+
+## Desktop artifacts
+
+Local artifact builds are unsigned by default and write to `release/`:
+
+```sh
+vp run dist:desktop:dmg
+vp run dist:desktop:linux
+vp run dist:desktop:win
+```
+
+DMGs default to the host architecture. Use `--arch` to choose another target and `--keep-stage`
+to retain packaging files for inspection. Run `vp run dist:desktop:artifact --help` for other
+options.
+
+### Linux AppImage prerequisites
+
+Build on Linux because the browser-secret helper links against the host's libsecret. Install
+Rust, C/C++ build tools, libsecret development headers, pkg-config, and ImageMagick.
+
+Ubuntu and Debian:
+
+```sh
+sudo apt-get update
+sudo apt-get install cargo rustc build-essential libsecret-1-dev pkg-config imagemagick
+```
+
+Fedora:
+
+```sh
+sudo dnf install rust cargo gcc gcc-c++ make libsecret-devel pkgconf-pkg-config ImageMagick
+```
+
+Arch Linux:
+
+```sh
+sudo pacman -S rust base-devel libsecret pkgconf imagemagick
+```
+
+The C toolchain, pkg-config, and libsecret headers are also needed for Linux desktop development.
+
+### macOS DMG prerequisites
+
+Install the Xcode Command Line Tools with `xcode-select --install` and install Rust.
+For a cross-architecture or universal build, add the requested Rust targets:
+
+```sh
+rustup target add aarch64-apple-darwin x86_64-apple-darwin
+```
+
+### Windows installer prerequisites
+
+Install Rust, Python 3, and Visual Studio Build Tools with **Desktop development with C++**.
+Include the Windows SDK and the MSVC build tools and Spectre-mitigated libraries for the target
+architecture. Add its Rust target:
+
+```powershell
+rustup target add x86_64-pc-windows-msvc
+# For an ARM64 installer:
+rustup target add aarch64-pc-windows-msvc
+```
+
+NSIS is downloaded by electron-builder. WSL support additionally needs a Linux node-pty prebuild;
+see the [release runbook](./release.md#windows-payload-topology-and-update-validation).
+
+### Signing and passkeys
+
+Add `--signed` after configuring the platform credentials in the
+[release runbook](./release.md). macOS passkeys need a signed, provisioned app; follow the
+[Connect setup](./connect-setup.md#desktop-passkeys) for local signing and renderer HMR.
diff --git a/docs/operations/release.md b/docs/operations/release.md
index e5a4d3544c35..02f453ab36a5 100644
--- a/docs/operations/release.md
+++ b/docs/operations/release.md
@@ -329,7 +329,7 @@ Checklist:
    - `APPLE_API_KEY`: contents of the downloaded `.p8`
    - `APPLE_API_KEY_ID`: Key ID
    - `APPLE_API_ISSUER`: Issuer ID
-10. Complete the Clerk Native API and AASA setup in [T3 Connect Clerk Setup](../internals/t3-connect.md#desktop-passkeys).
+10. Complete the Clerk Native API and AASA setup in [T3 Connect setup](./connect-setup.md#desktop-passkeys).
 11. Re-run a tag release and confirm macOS artifacts are signed/notarized and contain the expected
     `com.apple.developer.associated-domains` entitlement.
 
diff --git a/infra/relay/README.md b/infra/relay/README.md
index 0085c9c5b6b7..37b1a631970d 100644
--- a/infra/relay/README.md
+++ b/infra/relay/README.md
@@ -9,7 +9,7 @@ optional mobile notifications and Live Activities.
 
 The relay is intentionally not in the hot path for normal T3 Code traffic. After a client connects,
 regular API and WebSocket traffic goes directly between that client and the selected environment.
-See the [T3 Connect architecture overview](../../docs/internals/t3-code-connect-auth-flow.html) for the larger system
+See the [T3 Connect architecture note](../../docs/internals/t3-connect.md) for the larger system
 design.
 
 ## Responsibilities
@@ -159,8 +159,6 @@ and hosted web builds.
 
 See:
 
-- [T3 Connect Clerk Setup](../../docs/internals/t3-connect.md) for Clerk keys, JWT templates, and sign-up restrictions
-  setup.
+- [T3 Connect setup](../../docs/operations/connect-setup.md) for Clerk keys, JWT templates, and sign-up restrictions.
 - [Relay Observability](../../docs/operations/relay-observability.md) for deployment tracing and diagnostics.
-- [T3 Connect Architecture Overview](../../docs/internals/t3-code-connect-auth-flow.html) for the full link,
-  connect, endpoint, and notification flows.
+- [T3 Connect architecture](../../docs/internals/t3-connect.md) for environment linking and trust boundaries.
diff --git a/scripts/build-desktop-artifact.ts b/scripts/build-desktop-artifact.ts
index 3e40d94dc69a..32b090f7a83b 100644
--- a/scripts/build-desktop-artifact.ts
+++ b/scripts/build-desktop-artifact.ts
@@ -348,7 +348,7 @@ export class LinuxDesktopBuildPrerequisitesMissingError extends Schema.TaggedErr
         ? ["Add the requested Rust target with:", `  rustup target add ${this.rustTarget}`]
         : []),
       "",
-      "For other distributions, see docs/internals/scripts.md#linux-appimage-prerequisites.",
+      "For other distributions, see docs/operations/development.md#linux-appimage-prerequisites.",
       "Then rerun `vp run dist:desktop:linux`.",
     ].join("\n");
   }
@@ -420,7 +420,7 @@ export class WindowsDesktopBuildPrerequisitesMissingError extends Schema.TaggedE
       "Install Rust from https://rustup.rs and add the requested target:",
       `  rustup target add ${this.rustTarget}`,
       "Install Python 3 and the Visual Studio Build Tools components listed in",
-      "docs/internals/scripts.md#windows-installer-prerequisites.",
+      "docs/operations/development.md#windows-installer-prerequisites.",
       "",
       "Then rerun the desktop artifact command.",
     ].join("\n");

From 9e1fb459a985d13c1d4e57080f49d70dabf3b681 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 12:45:04 -0700
Subject: [PATCH 03/56] docs: focus user guides on features and workflows
 (#9756)

---
 README.md                          |   4 +-
 docs/README.md                     |  26 +--
 docs/user/appearance.md            |  66 ++++++
 docs/user/background-service.md    | 160 +++++--------
 docs/user/browser-import.md        |  26 +--
 docs/user/composer.md              | 295 ++++++++----------------
 docs/user/environment-theme.md     |  92 --------
 docs/user/install.md               | 185 ++++++----------
 docs/user/keybindings.md           | 139 ++++--------
 docs/user/mobile-appearance.md     |  21 --
 docs/user/permission-modes.md      |  71 ++----
 docs/user/project-settings.md      |  36 +--
 docs/user/providers-antigravity.md | 241 ++++++++------------
 docs/user/providers-claude.md      | 273 ++++++-----------------
 docs/user/providers-codex.md       | 206 ++++-------------
 docs/user/providers-opencode.md    | 114 +++-------
 docs/user/remote-access.md         | 345 +++++++++--------------------
 docs/user/source-control.md        | 232 ++++++-------------
 docs/user/telemetry.md             |  20 +-
 docs/user/thread-sidebar.md        | 161 ++++++--------
 docs/user/tool-activity.md         |  25 ---
 docs/user/updating.md              | 113 ++++------
 docs/user/usage.md                 |  66 +++---
 23 files changed, 955 insertions(+), 1962 deletions(-)
 create mode 100644 docs/user/appearance.md
 delete mode 100644 docs/user/environment-theme.md
 delete mode 100644 docs/user/mobile-appearance.md
 delete mode 100644 docs/user/tool-activity.md

diff --git a/README.md b/README.md
index f1cc79730843..27b5dc491693 100644
--- a/README.md
+++ b/README.md
@@ -79,12 +79,12 @@ Full docs live in [docs/](./docs). There's no docs site yet.
 - [Install and first run](./docs/user/install.md)
 - [Permission modes](./docs/user/permission-modes.md)
 - [Keyboard shortcuts](./docs/user/keybindings.md)
-- [Customize a project icon](./docs/user/project-settings.md)
+- [Project settings](./docs/user/project-settings.md)
 - [Remote access from a phone or another machine](./docs/user/remote-access.md)
 - [Keeping app and server in sync](./docs/user/updating.md)
 - [Source control integrations](./docs/user/source-control.md)
 - Multiple accounts: [Codex](./docs/user/providers-codex.md) · [Claude](./docs/user/providers-claude.md)
-- Linux: [run T3 Code as a background service](./docs/user/background-service.md)
+- [Run T3 Code as a background service](./docs/user/background-service.md)
 
 Building from source? Start at [docs/internals/overview.md](./docs/internals/overview.md).
 
diff --git a/docs/README.md b/docs/README.md
index fe159931b656..4e6f82bfb826 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,22 +2,22 @@
 
 ## Using T3 Code
 
-- [Install and first run](./user/install.md)
+- [Install T3 Code](./user/install.md)
+- [Messages and context](./user/composer.md)
+- [Working with threads](./user/thread-sidebar.md)
 - [Permission modes](./user/permission-modes.md)
+- [Terminal history](./user/terminal.md)
+- [Source control](./user/source-control.md)
+- [Project settings](./user/project-settings.md)
+- [Appearance and themes](./user/appearance.md)
 - [Keyboard shortcuts](./user/keybindings.md)
-- [Organizing threads](./user/thread-sidebar.md)
-- [Review usage](./user/usage.md)
-- [Anonymous usage data](./user/telemetry.md)
-- [Customize a project icon](./user/project-settings.md)
-- [Mobile appearance](./user/mobile-appearance.md)
-- [Environment themes](./user/environment-theme.md)
+- [Import browser sessions](./user/browser-import.md)
+- [Usage and limits](./user/usage.md)
+- [Product usage data](./user/telemetry.md)
 - [Remote access](./user/remote-access.md)
-- [Keeping app and server in sync](./user/updating.md)
-- [Source control integrations](./user/source-control.md)
-- [Background service (Linux)](./user/background-service.md)
-- Providers: [Codex](./user/providers-codex.md) · [Claude](./user/providers-claude.md) · [OpenCode](./user/providers-opencode.md)
-
-Mobile app: [apps/mobile/README.md](../apps/mobile/README.md)
+- [Running in the background](./user/background-service.md)
+- [Updating T3 Code](./user/updating.md)
+- Provider guides: [Codex](./user/providers-codex.md) · [Claude](./user/providers-claude.md) · [OpenCode](./user/providers-opencode.md) · [Antigravity](./user/providers-antigravity.md)
 
 ---
 
diff --git a/docs/user/appearance.md b/docs/user/appearance.md
new file mode 100644
index 000000000000..0126c2495b25
--- /dev/null
+++ b/docs/user/appearance.md
@@ -0,0 +1,66 @@
+# Appearance and themes
+
+Open **Settings → Appearance** to choose a theme and follow the system appearance or stay in light
+or dark mode. To use different themes for light and dark mode, select the corresponding preview
+within each theme. Appearance preferences are saved separately on each device or browser.
+
+Mobile has its own themes and text, code, and terminal preferences. It does not follow environment
+themes or defaults.
+
+## Custom themes
+
+On web and desktop, choose **Create theme** to adjust a palette, or import a T3 Code or VS Code
+theme. The theme editor's color picker lets you select an area of the app to find the color to
+change. Export your theme as JSON to share it.
+
+## Environment themes
+
+Environment themes and defaults come from the server serving your web app or the desktop app's
+main local environment. app.t3.codes and additional connections do not use them.
+
+Select a published theme in **Settings → Appearance** to follow its palette as the server updates
+it. **Duplicate** makes an independent copy you can edit. A saved custom theme with the same ID
+takes precedence. If the server stops publishing the selected theme, T3 Code falls back to its
+standard theme.
+
+Run this on the server to set a default and switch connected clients to it:
+
+```bash
+t3 theme set nightfall
+```
+
+Clients that are offline apply it when they reconnect. Each client applies the setting once;
+choosing another theme afterward sticks until the next `t3 theme set`. Run the command again to
+reapply it, even if the name is unchanged.
+
+`t3 theme clear` removes the default without changing anyone's current theme. `t3 theme show` lists
+the default and published themes.
+
+### Publish a theme
+
+Save a theme exported from T3 Code into `~/.t3/userdata/themes/` on the server, or the `themes`
+directory under your custom state directory. The filename supplies the theme ID: `nightfall.json`
+can be selected with `t3 theme set nightfall`. Keep the filename stable when updating its colors.
+Do not use `system`, `light`, `dark`, or a built-in theme's ID.
+
+For an integration that generates a palette, this shorter format also works:
+
+```json
+{
+  "name": "Nightfall",
+  "appearance": "dark",
+  "canvas": "#1a1b26",
+  "accent": "#7aa2f7",
+  "colors": {
+    "terminalSelection": "#292e42",
+    "error": "#f7768e"
+  }
+}
+```
+
+Set `appearance` to `light` or `dark` and supply hex colors for `canvas` and `accent`. T3 Code
+generates the rest. The optional `colors` overrides use the names in the theme editor's advanced
+view.
+
+Write updates to a temporary file and rename it into place so clients never read a partial theme.
+Invalid files are not published.
diff --git a/docs/user/background-service.md b/docs/user/background-service.md
index a89fc2f7842d..eecd6fa77b3a 100644
--- a/docs/user/background-service.md
+++ b/docs/user/background-service.md
@@ -1,123 +1,81 @@
-# Running T3 Code in the Background
+# Running T3 Code in the background
 
-On Linux and macOS, T3 Code can run as a background service for your user, so it is ready without
-keeping a terminal open.
+On Linux and macOS, T3 Code can run as a service for your user so you do not need
+to keep a terminal open.
 
-## Manage the Service
+## Manage the service
 
-Install it with the latest T3 Code release:
+Run these commands on the machine that will host T3 Code:
 
-```sh
-npx t3@latest service install
-```
-
-Check whether it is installed. On Linux this also checks whether the service is running, enabled
-at startup, and allowed to keep running after logout:
-
-```sh
-npx t3@latest service status
-```
-
-Update or repair it:
-
-```sh
-npx t3@latest service update
-```
-
-The service uses the same T3 Code version as the CLI you run. To install a nightly or an exact
-version, use that version of the CLI:
-
-```sh
-npx t3@nightly service update
-npx t3@1.2.3 service update
-```
-
-The install and update commands refuse to replace a newer service with an older version. Setup
-through T3 Connect leaves a newer service unchanged. To downgrade, select the exact older version
-and pass `--allow-downgrade`:
+| Task                            | Command                           |
+| ------------------------------- | --------------------------------- |
+| Install and start               | `npx t3@latest service install`   |
+| Inspect status and log location | `npx t3@latest service status`    |
+| Update or repair                | `npx t3@latest service update`    |
+| Stop and remove from startup    | `npx t3@latest service uninstall` |
 
-```sh
-npx t3@1.2.3 service update --allow-downgrade
-```
-
-Stop it and remove it from startup:
-
-```sh
-npx t3@latest service uninstall
-```
-
-Updating restarts T3 Code briefly. Let active agent work and terminal commands finish first.
-If a remote update is already in progress, wait for it to finish before retrying a local update.
-
-The service runs a small stable launcher. Exact T3 Code versions are installed separately, so a
-failed remote candidate can return to the previous version without rewriting the service
-definition. The launcher snapshots the database before a remote candidate starts, so database
-updates roll back with the server version. An older launcher may require one local
-`service update` before this is available.
+Uninstalling the service leaves your projects, threads, and settings intact.
 
-## Platform Support
+Install and update use the version of the CLI you invoke. For nightly, use
+`npx t3@nightly service update`; replace `nightly` with an exact version to pin
+one. An older CLI refuses to replace a newer service unless you explicitly add
+`--allow-downgrade`.
 
-**Linux** uses a systemd user unit at `~/.config/systemd/user/t3code.service`. The service starts
-when the machine boots and keeps running after you log out (lingering is enabled during install).
-Setup checks the systemd user manager and enables lingering before installing a runtime or stopping
-an existing service. If that requires administrator permission, setup stops with a recovery command.
+Updating restarts the server. Finish active work first, and wait for any remote
+update already in progress. To match a remote client's version, follow
+[Updating T3 Code](./updating.md).
 
-**macOS** uses a launch agent at `~/Library/LaunchAgents/com.t3tools.t3code.service.plist`. It
-starts when you log in, not when the Mac boots, and it stops when you log out; macOS has no
-equivalent of Linux lingering for user agents. For a Mac that should stay reachable unattended,
-turn on automatic login (System Settings → Users & Groups; unavailable while FileVault is on) and
-keep the Mac from sleeping.
+## Platform support
 
-A few more macOS notes:
+Linux needs systemd user services. Setup enables lingering so T3 Code starts at
+boot and keeps running after logout. If this needs administrator permission,
+setup prints a recovery command before changing the service.
 
-- Installing over SSH needs someone logged in at the Mac's screen to start the agent right away.
-  Without that, the install command reports an error at the final start step, but the agent is
-  fully installed and starts at the next login.
-- macOS may show privacy prompts for protected folders such as Desktop, Documents, or Downloads,
-  attributed to a bare `node` process, or deny access without a prompt. If agent work fails to
-  read those folders, grant Full Disk Access to the node binary listed in the launch agent's
-  `ProgramArguments`.
-- The agent appears under System Settings → General → Login Items. If it was switched off there,
-  or disabled with `launchctl disable`, macOS will not start it at login until you switch it back
-  on.
+macOS starts the service when you log in and stops it when you log out. Keep the
+Mac logged in and awake for unattended remote access. Installing over SSH while
+nobody is logged in at the Mac's screen can fail at the final start step; the
+service is still installed and will start at the next login.
 
-**Windows** is not supported yet.
+Windows background services are not supported.
 
-## Using It with T3 Connect
-
-T3 Connect may offer to install the service during setup so the host stays reachable in the
-background. This is only an onboarding shortcut: the service and T3 Connect are managed separately.
-
-Signing out of T3 Connect does not remove the service. Use `t3 service uninstall` when you no longer
-want T3 Code to start in the background.
+T3 Connect can offer service installation during setup, but the two are managed
+separately. Signing out of T3 Connect does not stop or uninstall the service.
 
 ## Troubleshooting
 
-Run `t3 service status` on the server machine. An installed version alone does not mean the service
-is running or will survive logout. Linux status reports these problems:
+Start with `t3 service status` on the host. It prints the log path and, on Linux,
+checks whether the installed service is running, enabled, and allowed to survive
+logout.
 
-| Code                       | What it means                                                                    | Recovery                                                                                                                                   |
-| -------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `linger-disabled`          | The service stops after your last login session ends and does not start at boot. | Run `sudo loginctl enable-linger "$(id -un)"`, then retry setup as your normal user.                                                       |
-| `linger-unavailable`       | T3 Code could not verify the logout setting.                                     | Run `loginctl show-user "$(id -un)" --property=Linger` and check that systemd-logind is available.                                         |
-| `user-manager-unavailable` | T3 Code cannot reach your systemd user manager.                                  | Run `systemctl --user status` in a login session for the service user. Install your distribution's systemd user-session support if needed. |
-| `service-disabled`         | The service is not enabled to start automatically.                               | Run the repair command shown by `t3 service status`.                                                                                       |
-| `service-stopped`          | The service is installed but is not running.                                     | Read the service log and `systemctl --user status t3code.service`, then run the displayed repair command.                                  |
-
-For an SSH host, run the administrator command in an interactive terminal so sudo can prompt for
-your password:
+If it stops when your SSH session closes, check for `linger-disabled`. An
+administrator can enable lingering with:
 
 ```sh
-ssh -t your-server 'sudo loginctl enable-linger "$(id -un)"'
+sudo loginctl enable-linger "$(id -un)"
 ```
 
-Run only the `loginctl` command with sudo. Running `t3` with sudo creates a separate installation and
-Connect identity for root. If an administrator is unavailable, run `t3 serve` in a terminal and
-keep that session open.
+Over SSH, allow sudo to prompt:
 
-The repair command shown by status uses the CLI version, or the installed service version if that
-is newer. An older stable CLI therefore does not recommend downgrading a nightly installation.
-Setup leaves an existing service running if the user-manager or lingering check fails.
+```sh
+ssh -t your-server 'sudo loginctl enable-linger "$(id -un)"'
+```
 
-`t3 service status` prints the log path. The adjacent `server.trace.ndjson` file contains detailed
-server traces. For failures after authorization, see [T3 Connect troubleshooting](./remote-access.md#t3-connect-troubleshooting).
+Then retry service setup as your normal user. Run only the `loginctl` command
+with sudo; running T3 Code as root creates a separate installation and Connect
+identity. Without administrator access, run `t3 serve` in a terminal and keep
+that session open.
+
+| Status problem                          | Next step                                                                                                                      |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `linger-unavailable`                    | Run `loginctl show-user "$(id -un)" --property=Linger` and check that systemd-logind is available.                             |
+| `user-manager-unavailable`              | Run `systemctl --user status` in a login session for the service user; check your distribution's systemd user-session support. |
+| `service-disabled` or `service-stopped` | Read the log and `systemctl --user status t3code.service`, then use the repair command printed by T3 Code.                     |
+
+On macOS, check **System Settings → General → Login Items** if the service no
+longer starts at login. If agent work cannot access Desktop, Documents, or
+Downloads, it may need Full Disk Access for the Node executable listed in
+`ProgramArguments` in
+`~/Library/LaunchAgents/com.t3tools.t3code.service.plist`.
+
+For failures after signing in to T3 Connect, see
+[connection troubleshooting](./remote-access.md#t3-connect-troubleshooting).
diff --git a/docs/user/browser-import.md b/docs/user/browser-import.md
index 4c911f6262a3..9aa4c6ca0e7f 100644
--- a/docs/user/browser-import.md
+++ b/docs/user/browser-import.md
@@ -1,17 +1,15 @@
-# Import browser logins
+# Import browser sessions
 
-In the desktop app, open **Settings → Integrations → Browser profiles → Add profile**
-and choose a browser under **Import from**. The import copies cookies into a T3 Code browser
-profile so you can use existing logins in the preview browser. Changes made afterward stay
-separate from the source browser.
+The desktop app can import cookies from another browser so you can reuse its signed-in sessions
+in the preview browser.
 
-Linux discovery includes Helium and both native and Snap installations of Firefox. Windows
-discovery includes Firefox and Helium builds that still use Windows' standard profile
-encryption. Other Chromium-based browsers on Windows use app-bound cookie encryption and cannot
-be imported. A browser appears once it has a profile with a cookie database. Close the source
-browser before importing; the import wizard will prompt you if it is still running.
+Open **Settings → Integrations → Browser profiles → Add profile**, then choose a browser under
+**Import from**. Close the source browser before importing, and allow an operating-system keyring
+unlock prompt if one appears.
 
-On Linux, Chromium-based browsers use your desktop keyring to protect their cookies. T3 Code
-includes the keyring reader; no separate command-line tool is needed. Allow the desktop unlock
-prompt if one appears. If the keyring cannot be accessed, T3 Code reports that failure when no
-cookies can be imported. Partitioned cookies are skipped.
+This is a one-time copy. Later login changes stay separate between the two browsers, and some
+sites may still require you to sign in again.
+
+On Windows, import supports Firefox and Helium profiles that use standard profile encryption.
+Other Chromium-based browsers use app-bound encryption and cannot be imported. Partitioned cookies
+are skipped on all platforms.
diff --git a/docs/user/composer.md b/docs/user/composer.md
index f158eb8f185e..740c44b8129d 100644
--- a/docs/user/composer.md
+++ b/docs/user/composer.md
@@ -1,240 +1,119 @@
-# Message composer
-
-Messages can contain up to 120,000 characters. If a draft is longer, T3 Code keeps it in the
-composer and shows how many characters need to be removed. Shorten the draft or split it into
-multiple messages, then send again in the same thread.
-
-On mobile, an empty composer shows an interrupt button while the agent is working. Adding text
-or an attachment replaces it with the send button. This applies to both compact and expanded
-composers.
-
-You can attach images up to 10 MB. On servers that support file uploads, you can also
-attach videos, text files, PDFs, ZIP archives, and other files. Each file can be up to the limit advertised
-by the server, capped at 50 MB. Each message can contain up to eight attachments in total. Files
-upload directly to the environment, where your agent can read, copy, or edit them by their file path.
-
-Attachments upload as soon as you add them while connected to a server that supports uploads.
-The send button becomes available after every upload finishes. Failed uploads can be retried or
-removed. On mobile, tap **+** to open
-the photo library from either the compact or expanded composer. When the connected server supports
-file uploads, **+** opens a menu beside the button with **Photo Library** and **Choose Files**.
-Videos use the server's file upload limit. You can also share photos, videos, and files into
-T3 Code from other apps through the system share sheet. Mobile keeps a local copy of each draft
-attachment, so you can still preview it and queue messages while offline. Uploads resume when
-you reconnect. Drafts and queued messages survive app restarts; signing out of T3 Connect keeps
-them on your device until you sign back into the same account. Select a received file on mobile
-to preview it or open the system share options.
-
-Tap an image or PDF before or after sending to open it. On iOS, images zoom from their thumbnail
-into the native viewer. Pinch or double-tap to zoom, and swipe down or tap Close to return.
-Use Share to save a copy or send it to another app. PDFs support page navigation and search.
-PDF links in assistant responses open the same preview. On Android, images open in the image
-viewer and PDFs open the system chooser.
-
-On web and desktop, select a sent PDF or HTML attachment to open it in the file viewer, or use the
-download button beside it to save a copy. Other attached files download when selected.
-
-Select a video attachment before or after sending to play it. Web and desktop use the browser's
-built-in controls. On mobile, videos open in a full-screen player with native playback controls.
-Supported videos show a thumbnail in the conversation and composer.
-Received videos stream from their environment as they play on every platform. Supported formats and
-codecs depend on the browser or device; you can save an unsupported video to open it in another app.
-
-On iOS, the system player zooms from the attachment. Swipe down or tap Close to return to the
-conversation or draft. Touch and hold a video thumbnail, then choose **Save or share** to open
-the system share options. On Android, the same menu is also available inside the preview.
-
-On web and desktop, if you reload before a file finishes uploading, the draft keeps the file's name
-and shows **Attach again** next to it. Attach the file again or remove it, then send.
-
-On web and desktop, HEIC and HEIF photos are automatically converted to JPEG when you drag them into
-the composer or paste them into a message. On iOS, selecting them from **Photo Library** also
-converts them to JPEG. The 10 MB image limit applies to the converted photo.
-
-On web and desktop, an existing thread settles its composer into a single-line resting state when
-the composer loses focus. At wider sizes, scrolling the conversation also rests a focused composer,
-except when scrolling toward the end while already there. When the thread-context strip has room,
-the model and mode controls stay available beside the thread context; otherwise they return when the
-composer is focused. Focus the composer or start typing to expand it again. The conversation keeps
-the expanded composer's space clear above its last message while the composer rests, so expanding it
-again never covers what you scrolled to. New-thread layouts keep the full composer. **Settings → General → Collapse composer** chooses which triggers rest it:
-**On unfocus**, **On scroll**, both, or neither. With neither selected the composer stays expanded.
-
-At phone-sized web or desktop window widths, existing threads animate between their compact and
-expanded layouts. Up to three image attachments remain visible in either resting layout, followed
-by a count when more are attached. At wider sizes, videos, files, and other draft context remain
-visible at their natural height; the phone-sized compact row reveals those details when expanded.
-
-On mobile, the model picker shows each OpenCode model's upstream provider, such as Anthropic,
-GitHub Copilot, or OpenCode Zen, beneath its name. Search by that provider name to narrow the list
-when starting a thread or changing an existing thread's model.
+# Messages and context
 
-## Model defaults
+Give the agent a task in the composer. Add files, quote a previous response, or
+include a skill when the task needs more context.
 
-T3 Code remembers the last provider, model, and model options you selected and reuses that
-selection for new threads. A model configured in a project's settings overrides the remembered
-selection for that project; resetting the project setting returns it to the remembered selection.
+Messages can contain up to 120,000 characters. Longer drafts stay in the composer
+so you can shorten them or split them into several messages.
 
-Model options shown as provider defaults remain display values until you choose them in T3 Code.
-T3 Code only sends options you selected explicitly, so an unset reasoning level or service tier can
-still come from the provider's own configuration.
+## Attach files
 
-## Quote an assistant response
+Attach up to eight files per message. Images can be up to 10 MB; other files can
+be up to 50 MB, subject to the environment's upload support and limit. The agent
+receives them on the environment's machine.
 
-On web and desktop, select text in an assistant response, then choose **Cite in composer** from the
-menu that appears when you release the selection. This inserts an inline quote chip at your cursor
-and opens an optional comment bubble beside the selected text; press `Enter` or choose **Save** to
-attach the comment, or leave it blank to keep just the quote. You can type before and after the
-chip, such as a quote followed by "what do you mean?". A selection must stay within one response
-and fit in 8,000 characters.
+Uploads begin when you add an attachment. All uploads must finish before the
+message can send. Retry or remove a failed upload. On web and desktop, reloading
+before an upload finishes requires you to attach that file again.
 
-The chip shows your comment when it has one, or a short quote preview otherwise. Use the pencil
-button to add or change the comment, and the remove button to delete the quote and its comment from
-the draft. Copying, reloading, and restoring a [stashed prompt](#prompt-stash) keep each comment
-with its quote, and sending tells the agent which words were quoted and which comment you wrote.
-The quoted text and comment count toward the message limit.
+You can drag or paste images into the web or desktop composer. HEIC and HEIF
+photos are converted to JPEG there and when selected from the iOS photo library;
+the image limit applies after conversion. On mobile, you can also send files to
+T3 Code through another app's system share sheet.
 
-Select a chip in the composer or a sent message to open the source thread, scroll to the response,
-and highlight the quoted passage — including in older history. The
-highlight pulses, holds for a moment, then fades on its own; press `Escape` to stop the navigation
-or clear it early. If the source is unavailable or its text has changed, the saved quote stays
-readable and T3 Code shows a warning.
+See [images and videos](#images-and-videos-in-messages) for previewing and saving media.
 
-Mobile shows the full saved quote and its comment in sent messages. It does not offer
-**Cite in composer** or navigation to a quote's source.
+## Queue messages offline on mobile
 
-## Images and videos in messages
+Mobile keeps local copies of draft attachments, so you can preview them and queue
+messages while disconnected. Uploads resume when you reconnect. Drafts and queued
+messages survive app restarts. Signing out of T3 Connect keeps that work on your
+device until you sign back into the same account.
 
-On web, desktop, and mobile, select a link to an image or video to open it inside T3 Code.
-Workspace image and video links open the file viewer. Links to media outside the workspace
-open a media preview.
-Videos opened from the file explorer or a file-viewer tab also play inside T3 Code. They
-stream from the environment as needed, rather than downloading the entire video before playback.
-Paths in inline code, such as `/tmp/recording.mp4`, work the same way. Image embeds stay inline;
-video embeds show a player with the browser's controls, full screen included. Visible video previews load
-an initial frame when supported, but stay paused until you press Play. Video file references use
-a filmstrip icon.
-
-On web and desktop, hover over a preview to see its full file path or original URL. Right-click
-to copy that reference, save the image or video, or copy an image to the clipboard. The video
-player's built-in controls can download a video too. If the player cannot decode a video, its error message
-offers a link to open the source in the browser. Workspace media also offers **Copy relative
-path** and **Open in file viewer**. These actions are available in expanded previews too.
-
-On mobile, touch and hold an inline image or a video thumbnail to see its source,
-copy the path or URL, or choose **Save or share**. Workspace files can open in the file viewer
-from the same menu. Saving downloads a copy only when you request it; it does not change how
-the video buffers during playback. On iOS, touch and hold a file reference in a message to
-copy its full or relative path or open it in the file viewer.
-
-Use Markdown image syntax to embed either kind of media:
-
-```markdown
-![Screenshot](/tmp/screenshot.png)
-![Recording](/tmp/recording.mp4)
-[Open recording](/tmp/recording.mp4)
-```
-
-Relative paths resolve from the thread's workspace. Absolute paths and `file://` links refer to
-the environment's machine, even when you connect remotely or use your phone. Supported media
-can live outside the workspace, including in Downloads or `/tmp`.
-
-T3 Code serves the original file without adding it to attachment storage. If that file is moved
-or deleted, its preview can no longer load from the environment. A browser or device may still
-have a cached copy. Supported video formats and codecs depend on the browser or device.
-
-Bare paths in ordinary prose and paths inside code blocks stay text. Raw HTML `<video>` tags
-are not supported; use the Markdown embed syntax above.
+## Model defaults
 
-## Files outside the workspace
+T3 Code remembers your provider, model, and model options for new threads. A
+project's configured model takes precedence; resetting that project setting
+returns to the remembered selection.
 
-When an agent links to a file it wrote outside the workspace, such as a Markdown report in
-`/tmp`, select the link to open it in the file viewer. The viewer shows the file read-only, with
-rendered Markdown available as usual; it cannot edit files outside the workspace. The workspace
-file tree stays hidden because it does not describe the open file. HTML and PDF files outside the
-workspace open the same way as ones inside it. Because such a file is served on its own, an HTML
-page outside the workspace cannot load scripts, styles, or images from files beside it.
+Leaving reasoning level or service tier unset uses the provider's own configuration.
 
-## HTML and PDF files in the file viewer
+## Quote an assistant response
 
-On web and desktop, the file viewer shows HTML and PDF files as a rendered page. Use the
-source toggle in the viewer's header to switch an HTML file between the page and its markup; the
-choice persists like the rendered-Markdown toggle. A link to a line always opens the source. HTML
-runs in an isolated frame with no access to your T3 Code session. On desktop, the integrated
-browser remains available from the same header for a full browser view.
+On web and desktop, select text within one assistant response and choose
+**Cite in composer**. You can add a comment about the quote and write instructions
+around it.
 
-## Changing projects
+Select the quote in a draft or sent message to return to its source. If the source
+is unavailable or has changed, the saved quote remains readable.
 
-On web and desktop, changing the project from a new thread keeps the current environment when that
-project exists there. If it does not, T3 Code selects another environment that has the project.
+Mobile displays saved quotes and comments, but does not create citations or
+navigate to their sources.
 
-## Notices above the composer
+## Prompt stash
 
-On web and desktop, loading and syncing statuses fill the available banner width beside the
-stash tab. Task progress appears above the composer, while the timeline's working timer shows
-only elapsed time.
+On web and desktop, press `Cmd+S` on macOS or `Ctrl+S` on Windows and Linux to save
+the current prompt and its attachments for later. Wait for uploads to finish first.
+With an empty composer, the same shortcut restores a single stash or opens the
+stash menu when there are several.
 
-Loading, syncing, and server-update icons are static. Live tool labels do not shimmer.
+Stashes containing uploaded files must be restored in their original environment.
+Those files are retained for 24 hours. After an upload expires, restore the prompt
+and use **Attach again** or remove the missing file before sending.
 
-On web and desktop, additional notices peek out above the attached banner. Hover over the peek
-to reveal them, or focus **Show other notices** with `Tab` and press `Enter` or `Space`. Press
-`Escape` to close the stack and return focus to that control. On a touchscreen, tap the peek to
-open the stack. Interacting with the attached banner or composer does not open the stack.
+## Voice input on iPhone
 
-## Prompt stash
+On supported iPhones with iOS 26 or later, use the composer's microphone to record,
+then confirm to transcribe. Text is inserted where your selection was when
+recording started, ready for you to review and edit before sending.
 
-Use the default shortcut, `Cmd+S` on macOS or `Ctrl+S` on Windows and Linux, to stash the current
-prompt and its attachments after all file uploads finish. When the composer is empty and the stash
-has one entry, press the shortcut again to restore it. The shortcut opens the stash menu if there
-are multiple entries or the entry's images are still saving. You can also open the menu from the
-stash badge. Stashes that contain files must be restored in the environment where those files were
-uploaded. Stashed files stay uploaded on the server for 24 hours. If you restore an entry after
-that, the file comes back with **Attach again** next to it. Attach the file again or remove it, then
-send.
+The first use may download Apple's speech model and needs a network connection.
+Later transcription works offline for that language. Recordings can be up to five
+minutes long. Canceling, leaving the screen, or an audio interruption discards the
+recording and preserves your existing draft.
 
-## Voice input on iPhone
-
-On supported iPhones with iOS 26 or later, tap the microphone in the composer to record a message.
-An expanded composer keeps your draft visible and flips its bottom toolbar into recording controls
-with waves that respond to your voice. A collapsed composer flips into a compact recording strip
-without changing height. Tap the checkmark to finish and transcribe on your device. The waves fade
-into a transcription status, then the usual
-controls return with the text inserted at the selection where recording started. If the keyboard
-is open when you start, it stays open during voice input. You can review and edit the text before
-you send it.
-
-The first use can download Apple's speech model and needs a network connection. Later transcription
-works offline for that language. A recording can be up to five minutes long. Canceling voice input,
-leaving the screen, or an audio interruption discards the new recording and keeps the existing draft
-and attachments. T3 Code deletes the local audio file after transcription or cancellation. It sends
-only the normal message text when you submit the draft.
+Transcription runs on your device. T3 Code deletes the temporary audio after
+transcription or cancellation; only the message text is sent when you submit.
 
 ## Commands and skills
 
-Type `/` to open the command menu. Type `$` to find and add a skill. Skill rows show their source,
-such as System, Personal, Project, or App.
+Type `/` for commands or `$` to add a skill from the selected environment and
+provider. On mobile, both are also available before starting a thread on
+**New task**.
+
+The slash menu also includes skills unless you turn off **Settings → General →
+Show skills in slash menu**. Only skills enabled for the provider are listed.
+
+Provider commands must start the message to run. T3 Code commands such as
+`/model` and `/plan`, and skill mentions, work on any line.
+
+Send `/compact` in an existing conversation to reduce context usage when the
+provider supports it. Web and desktop also offer compaction from the context meter.
+
+## Images and videos in messages
+
+Select an image or video attachment or link to preview it. Playback support depends
+on your browser or device; save an unsupported video to open it in another app.
 
-On mobile, these menus are available on the **New task** screen before you start a thread. They
-use the skills and commands from the selected environment and provider.
+On web and desktop, right-click media to save it or copy its path or URL. On mobile,
+touch and hold an image or video thumbnail and choose **Save or share**. On iOS,
+return to the thumbnail to open this menu after watching a full-screen video.
 
-In a thread with prior conversation context, send `/compact` to reduce context usage. Web and desktop also offer this action from the context meter, and the work log records token counts when the provider reports them.
+File links refer to the environment's machine, including when you connect remotely.
+Previews use the original file, even outside the workspace. Moving or deleting it
+can break the preview, so save a copy if you need to keep it.
 
-By default, the `/` menu includes skills. To keep this menu command-only, turn off **Show skills in
-slash menu** in **Settings → General**. Skill results use the `/skill:Skill Name` label and add the
-same `$name` skill token to your message. The original skill name remains searchable. If the provider
-also reports that skill as a native slash command, T3 Code hides the duplicate native entry and keeps
-the `/skill:Skill Name` label.
+## Files outside the workspace
 
-A skill token runs the skill wherever it sits in your message. T3 Code sends it to each provider in
-the form that provider runs, so the text before and after the token is kept. Skills that only you may
-start, and never the agent on its own, work the same way. A skill you switched off in the provider's
-settings does not appear in either menu.
+Follow an agent's file link to read a report or other file outside the workspace.
+These files open read-only. An HTML file outside the workspace cannot load scripts,
+styles, or images from neighboring files.
+
+## HTML and PDF files in the file viewer
 
-Provider commands such as `/compact` only run when they open the message, so the `/` menu offers
-them only there. T3 Code's own commands, such as `/model` and `/plan`, and skills stay available on
-any line.
+On web and desktop, HTML and PDF files open as rendered pages. Switch an HTML
+file to source view to read its markup; a link to a specific line opens source
+automatically. HTML previews cannot access your T3 Code session.
 
-On desktop, press `Cmd+Enter` on macOS or `Ctrl+Enter` on Windows and Linux from a new thread to
-start it in the background. T3 Code opens another new thread and shows an **Open** action for the
-thread that started. The new thread keeps the selected workspace mode and base branch. If **New
-worktree** is selected, each background thread creates its own worktree.
+On mobile, select a PDF attachment or link to open it. iOS uses the native viewer;
+Android opens the system chooser.
diff --git a/docs/user/environment-theme.md b/docs/user/environment-theme.md
deleted file mode 100644
index 9988b8377fdc..000000000000
--- a/docs/user/environment-theme.md
+++ /dev/null
@@ -1,92 +0,0 @@
-# Environment theme
-
-Some desktops publish the palette they are currently wearing so that apps can match it. When the
-machine running your T3 Code server does that, its themes appear in the theme library alongside
-your own, and T3 Code follows them: change the desktop theme and T3 Code retints with it, without
-a restart.
-
-To use one:
-
-1. Open **Settings**.
-2. Select **Appearance**.
-3. Choose the theme published by your environment.
-
-Like every theme, this is a per-client choice: picking it on your desktop does not change what your
-phone or another browser shows.
-
-The machine can also set the environment's theme:
-
-```bash
-t3 theme set nightfall
-```
-
-Web and desktop clients switch to it — immediately when connected, on their next connect
-otherwise — and a fresh client opens with it. Each client applies a set once, so picking a
-different theme in Settings afterwards sticks until the next `t3 theme set`, and running the same
-set again is how you bring clients back. `t3 theme clear` removes the setting without changing
-what anyone currently has, and `t3 theme show` prints the current theme and everything the
-machine publishes. Only the environment you are anchored to publishes themes, so a remote client
-follows the machine it is connected to, not the device it runs on. T3 Code Mobile keeps its own
-appearance settings and does not follow environment themes.
-
-Select **Duplicate** on a published theme's card to keep a copy you can edit. The published theme
-itself cannot be edited or removed, because the environment rewrites it whenever its own theme
-changes. If the machine stops publishing it, the card disappears and clients using it fall back to
-the standard T3 Code look. A theme you saved always wins over a published one with the same id.
-
-When the theme editor is open, its draft stays visible while published themes change.
-Close the editor to show the latest selected theme.
-
-## Publishing themes
-
-A machine publishes themes by writing files into the `themes` directory of the T3 Code state
-directory (`~/.t3/userdata/themes/` by default). The filename is the theme id — `nightfall.json`
-appears as `nightfall` — and stays stable while the machine rewrites the colors underneath, so
-selections and defaults keep pointing at it.
-
-The filename may not be an appearance keyword (`system`, `light`, `dark`) or a built-in theme's
-id — those names already mean something on every client. Two formats are accepted. A theme
-exported from T3 Code (the **Download** button's output) works as-is, so any theme someone shared
-can be dropped in unchanged. Or, for a desktop that only knows
-its own palette, a short seeded form:
-
-```json
-{
-  "name": "Nightfall",
-  "appearance": "dark",
-  "canvas": "#1a1b26",
-  "accent": "#7aa2f7"
-}
-```
-
-`appearance` is `light` or `dark`, and `canvas` and `accent` are hex colors. T3 Code generates the
-rest of the palette from those two, the same way the guided theme editor does, so the result reads
-as a T3 Code theme wearing your desktop's colors rather than a transplant of another app's.
-
-A machine that knows a role better than a derivation can guess — its terminal palette, its
-semantic colors — can publish that role directly under `colors`, layered over the generated
-palette:
-
-```json
-{
-  "name": "Nightfall",
-  "appearance": "dark",
-  "canvas": "#1a1b26",
-  "accent": "#7aa2f7",
-  "colors": {
-    "terminalSelection": "#292e42",
-    "error": "#f7768e"
-  }
-}
-```
-
-Any of the roles shown in the theme editor's advanced view can be published this way; roles left
-out keep their generated value. A role this version of T3 Code does not know is ignored rather
-than rejected, so publishing a role added by a newer release is safe. An `id` inside the file is
-ignored — the filename decides.
-
-A theme with no usable colors is not listed on that client.
-
-Write each file atomically — write a temporary file beside it and rename — so T3 Code never reads
-a half-written theme. An unreadable or invalid file is simply not published; the machine's other
-themes are unaffected.
diff --git a/docs/user/install.md b/docs/user/install.md
index 7534759fd10c..10f1fdf164c6 100644
--- a/docs/user/install.md
+++ b/docs/user/install.md
@@ -1,142 +1,99 @@
 # Install T3 Code
 
-T3 Code is a web and desktop GUI for running coding agents on your machine.
+T3 Code runs coding agents on your computer and lets you control them from its
+desktop, web, or mobile app. Set up the machine where the agents will work first.
 
 ## Requirements
 
-Node.js `^22.16 || ^23.11 || >=24.10` on the machine that runs the T3 Code server.
+Command-line use, SSH hosts, and WSL backends need Node.js 22.16+ (22.x), 23.11+
+(23.x), or 24.10 and later. The native desktop app includes its server runtime.
 
-At least one provider runtime, installed and authenticated. You can install Antigravity from
-T3 Code settings. See [Providers](#providers) below.
+You need an installed, authenticated provider before starting a thread. You can
+launch T3 Code and configure providers afterwards.
 
-## Run Without Installing
+## Run without installing
 
 ```bash
 npx t3@latest
 ```
 
-This starts the T3 Code server on your machine and opens the local web app. Use
-`npx t3@latest --help` for the full CLI reference.
+This starts the server and opens the local web app. Run
+`npx t3@latest --help` for command-line options.
 
-If the web or desktop app shows "T3 Code could not load", check your connection and select
-**Reload** to try again.
+## Desktop app
 
-## Open a project in the desktop app
+Download a release from [GitHub Releases](https://github.com/pingdotgg/t3code/releases),
+or use a package manager:
 
-When the T3 Code desktop app is running on the same machine, open the current directory with:
+| Platform           | Install                         |
+| ------------------ | ------------------------------- |
+| Windows            | `winget install T3Tools.T3Code` |
+| macOS              | `brew install --cask t3-code`   |
+| Arch Linux         | `yay -S t3code-bin`             |
+| Arch Linux nightly | `yay -S t3code-nightly-bin`     |
 
-```bash
-npx t3 app
-```
-
-Pass a path to open another directory:
-
-```bash
-npx t3 app ../my-project
-```
-
-The command adds the directory as a project when needed, focuses the desktop app, and opens a new
-thread. It does not launch the desktop app, open a browser, or start a T3 Code server. A background
-server does not count as the desktop app. The command also rejects SSH sessions because a remote
-shell cannot focus a local desktop window. The CLI package and the running desktop app must both
-include `t3 app` support.
-
-## Desktop App
-
-Download the latest release from
-[GitHub Releases](https://github.com/pingdotgg/t3code/releases), or install from a package
-registry.
+### Windows Subsystem for Linux
 
-Windows:
+Choose a WSL distro in **Settings → Connections** to run agents and projects
+there. Install Node.js and provider CLIs inside that distro. T3 Code installs its
+matching server runtime there automatically; the first launch after an app
+update can take longer.
 
-```bash
-winget install T3Tools.T3Code
-```
+### Open a project from a terminal
 
-macOS:
+With the desktop app already running on the same machine:
 
 ```bash
-brew install --cask t3-code
+npx t3 app
 ```
 
-Arch Linux:
+This opens a new thread for the current directory, adding the project if needed.
+Pass a path, such as `npx t3 app ../my-project`, to open another directory. It requires
+the desktop app, so a standalone server or an SSH session is not enough. If the
+command cannot reach the app, start or update the desktop app and try again.
 
-Stable:
+## Mobile app
 
-```bash
-yay -S t3code-bin
-```
-
-Nightly:
-
-```bash
-yay -S t3code-nightly-bin
-```
-
-### Windows Subsystem for Linux
-
-When the desktop app runs a WSL backend, it installs the matching server runtime into
-`~/.t3/wsl-runtime` inside the selected distro. The first launch after installing or updating T3
-Code may take a little longer while that release's runtime is extracted. Later launches reuse the
-Linux-local copy so startup does not depend on reading application files through `/mnt/c`. After a
-successful launch, T3 Code keeps the current runtime and one previous runtime for rollback and
-removes older caches automatically. If a cached runtime stops working, T3 Code launches from the
-application files under `/mnt/c` instead and reinstalls the runtime on the next launch.
+Install T3 Code from the
+[App Store](https://apps.apple.com/us/app/t3-code-remote-claude-more/id6787819824) or
+[Google Play](https://play.google.com/store/apps/details?id=com.t3tools.t3code).
+The phone connects to a server on another machine. Follow
+[remote access](./remote-access.md) to link it through T3 Connect or a pairing URL.
 
 ## Providers
 
-T3 Code uses provider runtimes but does not bundle them. Install and authenticate each
-provider's CLI, or use T3 Code's managed setup for Antigravity.
-
-| Provider    | CLI                                                                                                        | Default binary     | Log in with                        |
-| ----------- | ---------------------------------------------------------------------------------------------------------- | ------------------ | ---------------------------------- |
-| Codex       | [Codex CLI](https://developers.openai.com/codex/cli)                                                       | `codex`            | `codex login`                      |
-| Claude      | [Claude Code](https://claude.com/product/claude-code)                                                      | `claude`           | `claude auth login`                |
-| Cursor      | [Cursor CLI](https://cursor.com/cli)                                                                       | `cursor-agent`     | `agent login`                      |
-| Grok Build  | [Grok Build CLI](https://x.ai/cli)                                                                         | `grok`             | `grok login`                       |
-| OpenCode    | [OpenCode](https://opencode.ai)                                                                            | `opencode`         | `opencode auth login`              |
-| Antigravity | [Official ACP agent](https://github.com/agentclientprotocol/registry/blob/main/antigravity-acp/agent.json) | Managed by T3 Code | **Sign in with Google** in T3 Code |
-
-Codex and Claude are on by default. Cursor, Grok Build, OpenCode, and Antigravity are off by
-default. Turn them on in **Settings** > **Providers** when you want to use them.
-
-For Antigravity, select the environment in provider settings, then install and sign in there.
-The runtime and credentials stay on that environment, even when you use a phone or remote
-browser. See [Antigravity setup](./providers-antigravity.md) for Google sign-in, remote callback
-steps, and supported hosts.
-
-Cursor is the one to watch: install Cursor CLI, which provides the `cursor-agent` binary that
-T3 Code looks for, but authenticate with `agent login`, not `cursor-agent login`.
-
-Grok models that support adjustable reasoning show a **Reasoning** control beside the model picker.
-The available levels and default come from the installed Grok Build CLI, so they can vary by model
-and CLI version.
-
-Run CLI login commands on the machine running the T3 Code server, not on the device you browse
-from. Antigravity uses its sign-in controls in T3 Code instead of a CLI login command.
-
-### Binary Discovery
-
-Each provider CLI must be on the server's `PATH`, or have an explicit binary path set in
-**Settings** → the provider instance → **Binary path**. Use the explicit path when a version
-manager or a non-standard install location keeps the CLI off the `PATH` of the shell that
-started T3 Code.
-
-Antigravity can use its managed runtime without a `PATH` entry. Its optional **Binary path**
-overrides the managed runtime and must point to the official ACP executable.
-
-### When Auth Is Needed
-
-Provider auth is required before you start a session with that provider, not before you start
-T3 Code. You can install T3 Code, open it, and add providers afterwards. A provider that is not
-authenticated shows its status and setup instructions in **Settings**.
-
-For multi-account setups, see [Codex](./providers-codex.md), [Claude](./providers-claude.md), and
-[Antigravity](./providers-antigravity.md#accounts-and-removal).
-
-## Next Steps
-
-- [Permission modes](./permission-modes.md): how much T3 Code asks before acting
-- [Remote access](./remote-access.md): connect from a phone, tablet, or another desktop
-- [Keeping T3 Code in sync](./updating.md): client and server version skew
-- [Running in the background](./background-service.md): Linux background service
+Open **Settings → Providers** in the web or desktop app, select the environment,
+and enable the provider you want. Installation, login, and configuration belong
+to that environment's machine, even when you connect from a phone or another
+computer.
+
+| Provider    | Install and authenticate                                                                     |
+| ----------- | -------------------------------------------------------------------------------------------- |
+| Codex       | Install [Codex CLI](https://developers.openai.com/codex/cli), then run `codex login`.        |
+| Claude      | Install [Claude Code](https://claude.com/product/claude-code), then run `claude auth login`. |
+| Cursor      | Install [Cursor CLI](https://cursor.com/cli), then run `agent login`.                        |
+| Grok Build  | Install [Grok Build CLI](https://x.ai/cli), then run `grok login`.                           |
+| OpenCode    | Install [OpenCode](https://opencode.ai), then run `opencode auth login`.                     |
+| Antigravity | Install and sign in with Google from T3 Code's provider settings.                            |
+
+Provider CLIs must be on the server's `PATH`. If T3 Code cannot find one, set its
+**Binary path** in provider settings, especially when using a version manager.
+Cursor's executable is `cursor-agent`, although its login command is
+`agent login`. Antigravity can use its managed runtime without a `PATH` entry.
+
+Add another provider instance for a separate account or configuration. Each
+instance can have its own environment variables, such as API keys or a custom
+base URL. Mark secret values as sensitive; after saving, T3 Code does not display
+their original values.
+
+For provider-specific setup and accounts, see [Codex](./providers-codex.md),
+[Claude](./providers-claude.md), [OpenCode](./providers-opencode.md), and
+[Antigravity](./providers-antigravity.md).
+
+## Next steps
+
+- [Working with threads](./thread-sidebar.md): start tasks and organize parallel work.
+- [Permission modes](./permission-modes.md): choose when agents ask before acting.
+- [Remote access](./remote-access.md): connect from another device.
+- [Running in the background](./background-service.md): keep a Linux or macOS host available.
+- [Updating T3 Code](./updating.md): update the app and connected servers.
diff --git a/docs/user/keybindings.md b/docs/user/keybindings.md
index 303d25131935..1c90b5351d30 100644
--- a/docs/user/keybindings.md
+++ b/docs/user/keybindings.md
@@ -1,14 +1,13 @@
 # Keybindings
 
-Edit keybindings from **Settings** → **Keybindings**. That page lists every command, its current
-shortcut, whether it is a default or your own, and warns about conflicts.
+Customize shortcuts in **Settings → Keybindings** on web and desktop. That page
+also lists the command IDs and defaults available in your version.
 
-The same configuration lives in `~/.t3/userdata/keybindings.json` on the machine running the
-server, if you prefer editing it directly. T3 Code writes the built-in defaults into that file on
-first run, and adds any new defaults on later startups unless a rule of yours already claims the
-command or the shortcut.
+## Edit the configuration file
 
-The file is a JSON array of rules.
+Keybindings live on the environment's machine, in
+`~/.t3/userdata/keybindings.json` by default. You can edit this file directly.
+It is a JSON array of rules:
 
 ```json
 [
@@ -17,109 +16,63 @@ The file is a JSON array of rules.
 ]
 ```
 
-Invalid rules are ignored. An invalid file is ignored entirely, and the server logs a warning.
+T3 Code creates the file with its defaults and adds new defaults on later startups.
+New defaults do not replace commands you customized. If a new default overlaps one
+of your shortcuts, [rule order](#precedence) decides which runs.
+Invalid rules are ignored; if the file cannot be parsed, T3 Code uses defaults.
 
-## Rule Shape
+## Rule shape
 
-- `key` (required): shortcut string, like `mod+j`, `ctrl+k`, `cmd+shift+d`
-- `command` (required): the command ID to run
-- `when` (optional): boolean expression controlling when the shortcut is active
+Each rule requires a `key` shortcut and a `command` ID. An optional `when`
+expression restricts when it runs.
 
-## Key Syntax
+Project scripts use `script.{id}.run`, such as `script.test.run`.
 
-Modifiers: `mod` (`cmd` on macOS, `ctrl` elsewhere), `cmd` / `meta`, `ctrl` / `control`, `shift`,
-`alt` / `option`.
+## Key syntax
 
-Examples: `mod+j`, `mod+shift+d`, `ctrl+l`, `cmd+k`.
+Join modifiers and a key with `+`, such as `mod+shift+d` or `ctrl+l`.
+`mod` means Command on macOS and Control elsewhere. Other modifiers are
+`cmd` / `meta`, `ctrl` / `control`, `alt` / `option`, and `shift`.
 
-## Commands
+## When conditions
 
-Commands are IDs like `terminal.toggle`, `commandPalette.toggle`, `preview.refresh`, and
-`chat.new`. Project scripts are addressable as `script.{id}.run`, for example `script.test.run`.
+Available context keys are `terminalFocus`, `terminalOpen`, `previewFocus`,
+`previewOpen`, and `modelPickerOpen`. Unknown keys evaluate to `false`.
 
-`filePicker.toggle` opens file search for the active project and defaults to `mod+p`.
-`projectSearch.toggle` searches inside the active project's files and defaults to `mod+shift+f`.
-Repeating either shortcut closes that search, and switching shortcuts replaces the open search.
-`themeEditor.toggle` opens or closes the floating theme editor and defaults to
-`mod+alt+shift+t`. Select a color label to spotlight the elements that use it; select the label
-again to clear the spotlight. The swatch and hex field keep that color selected while you edit it.
-Advanced mode groups related app tokens into a smaller set of color families. Changing a family
-updates its paired text and interaction states while leaving every unrelated imported color intact.
-Use **Inspect** to pick an element in the app and reveal its color token. Inspect disarms after one
-successful pick; its hover glow and badge preview the element and color family that click will select.
-**Cancel** or `Escape` exits Inspect and clears its selection and spotlight.
+Combine keys with `!` for not, `&&` for and, `||` for or, and parentheses:
 
-`rightPanel.toggleMaximized` maximizes or restores the open right panel. It has no default shortcut,
-so add one in **Settings** → **Keybindings** if you want to use it.
-
-`rightPanel.close` closes the active right panel tab and defaults to `mod+w`. Press it again to close
-the next tab. With the terminal focused, `mod+w` closes the terminal instead, and with nothing left
-to close it closes the desktop window as before. Browsers reserve `mod+w` for closing their own tab
-and never pass it to the page, so in a browser rebind this command (and `terminal.close`) to a
-shortcut the browser leaves alone, such as `alt+w`.
+```json
+{ "key": "mod+j", "command": "terminal.toggle", "when": "terminalOpen && !terminalFocus" }
+```
 
-`thread.copyReference` copies the active thread's pull request link, or its thread ID when no pull
-request is available. Its default shortcut is `mod+shift+c`, and it does not replace terminal copy
-while the terminal has focus.
+## Precedence
 
-`thread.settle` settles the active thread or restores it when it is already settled. Its default
-shortcut is `mod+shift+s`, and it does not run while the terminal has focus.
+The last rule whose key and condition both match wins, even if it belongs to a
+different command. Put a more specific rule after a general one when they share
+a shortcut.
 
-`thread.pin` pins the active thread to the pinned section of the sidebar, or unpins it when it is
-already pinned. Its default shortcut is `mod+shift+p`, and it does not run while the terminal has
-focus. See [Organizing threads](./thread-sidebar.md) for how pinned threads are ordered.
+## Commands with special behavior
 
-The command palette searches settings, active thread titles, projects, branches, user messages, and
-final agent responses across connected environments. A setting result opens its exact control or
-section. Message matches show one labeled excerpt while keeping the thread's project, branch, and
-machine context visible. Message search begins after two characters and uses SQLite's ASCII
-case-insensitive matching.
+`chat.new` may ask you to choose a project when there is more than one.
+`chat.newLocal` skips that chooser. Both use your
+[new-thread defaults](./thread-sidebar.md#start-a-thread).
 
-The full command list and the current defaults are shown in **Settings** → **Keybindings**, which
-always matches the build you are running. Use that rather than a copied list.
+## Reserved shortcuts
 
-Note that `chat.new` and `chat.newLocal` both create a thread through the same path. A new thread
-inherits the project you were in, along with model and mode selections. Branch, worktree, and
-environment mode always come from your configured defaults, not from the thread you were looking
-at. To keep a worktree, use the explicit "new thread in this worktree" action in the branch
-toolbar. The only difference between the two commands: with the current sidebar and more than one
-project, `chat.new` opens a project chooser first.
+In the desktop app, `mod+w` closes the focused terminal or the active right-panel
+tab. When nothing remains to close, it closes the window. In a browser, `mod+w`
+closes the browser tab; rebind `rightPanel.close` and `terminal.close` to an available
+shortcut such as `alt+w`.
 
-Background submission from a new thread is the exception. `mod+enter` starts that thread and opens
-another new thread with the same workspace mode and base branch. **New worktree** remains selected,
-but the new thread does not reuse the worktree created for the thread that just started.
+Many defaults include `!terminalFocus` so they do not intercept terminal input.
+Keep that condition when remapping them if you want the same behavior.
 
 ## Desktop quit shortcut
 
-Use `Cmd+Q` on macOS or `Ctrl+Q` on Windows and Linux. In the default **Hold** mode, hold the
-shortcut for 1.2 seconds or press it twice within 500 milliseconds. The second press quits
-immediately. You can keep Command or Control held between presses, or release both keys.
-
-Hold mode needs keyboard repeat. If holding does not quit, use two quick presses or choose
-**Quit** from the application menu.
-
-Change **Quit shortcut** in **Settings** → **General** → **Confirmations**. **Direct** quits on
-the first press. **Double press** requires two quick presses and does not accept a hold. The
-application menu's **Quit** action always quits immediately.
-
-## `when` Conditions
-
-A `when` expression is evaluated against context keys describing the current UI state. The keys
-the app supplies today are `terminalFocus`, `terminalOpen`, `previewFocus`, `previewOpen`, and
-`modelPickerOpen`. The set is open and grows over time, so treat that as the current list rather
-than a fixed one. Any key the running app does not supply evaluates to `false`.
-
-Operators: `!` (not), `&&` (and), `||` (or), and parentheses.
-
-Examples:
-
-- `"when": "terminalFocus"`
-- `"when": "terminalOpen && !terminalFocus"`
-- `"when": "!terminalFocus"`
-
-## Precedence
+Use `Cmd+Q` on macOS or `Ctrl+Q` on Windows and Linux. In the default **Hold** mode,
+hold for 1.2 seconds or press twice within 500 milliseconds. Holding requires
+keyboard repeat; if repeat is disabled, use two presses or the application menu.
 
-- Rules are evaluated in array order.
-- For a key event, the last rule where both `key` matches and `when` evaluates to `true` wins.
-- Precedence is across commands, not only within the same command. A later rule for a different
-  command can take a key away from an earlier one.
+Change **Settings → General → Confirmations → Quit shortcut** to **Direct** for a
+single press or **Double press** for two presses only. Choosing **Quit** from the
+application menu always quits immediately.
diff --git a/docs/user/mobile-appearance.md b/docs/user/mobile-appearance.md
deleted file mode 100644
index b7e4d57a6ade..000000000000
--- a/docs/user/mobile-appearance.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# Mobile appearance
-
-T3 Code Mobile includes the T3 Code, T3 Chat, Grove, Ocean, Ember, and Iris themes. Each theme has
-light and dark colors that apply throughout the app, including code reviews, file previews, the
-terminal, native headers, and sheets.
-
-On supported iOS versions, the new-task and thread composers, working timer, and scroll-to-end
-button use the system glass material. Other platforms use a themed background.
-
-To change themes:
-
-1. Open **Settings**.
-2. Select **Appearance**.
-3. Choose a theme.
-4. Select **System**, **Light**, or **Dark**.
-
-Tap a theme card to use it for both light and dark appearance. To mix themes, tap the light or dark
-preview circle inside a card to change only that appearance.
-
-**System** follows the device appearance automatically. Theme, text, code, and terminal appearance
-preferences are stored on the device.
diff --git a/docs/user/permission-modes.md b/docs/user/permission-modes.md
index f7da2fc32164..3d37850c5e20 100644
--- a/docs/user/permission-modes.md
+++ b/docs/user/permission-modes.md
@@ -1,60 +1,31 @@
-# Permission Modes
+# Permission modes
 
-A permission mode controls how much the agent does on its own and when it stops to ask you.
+Permission modes control when an agent needs your approval to act. Choose a mode in the message
+composer; it applies to that thread.
 
-The mode is set per thread, from the mode control in the message composer. Changing it in one
-thread does not change any other thread. A thread created from inside another thread keeps that
-thread's mode; otherwise new threads start in **Full access** unless you pick something else
-before sending.
+New threads start in **Full access** unless you choose another mode before sending. A thread
+created from another thread inherits its mode.
 
-## The Modes
+| Mode                  | Behavior                                                                              |
+| --------------------- | ------------------------------------------------------------------------------------- |
+| **Supervised**        | Requests approval for commands and file changes.                                      |
+| **Auto-accept edits** | Approves file edits automatically; other actions can still require approval.          |
+| **Auto**              | Uses the provider's automatic review to approve routine actions and ask about others. |
+| **Full access**       | Allows commands and edits without approval prompts.                                   |
 
-**Supervised**: ask before commands and file changes. The agent pauses and shows you what it
-wants to run or edit, and waits for approval. Work outside the workspace is restricted.
+Approve or reject requests in the conversation to let the agent continue. Permission modes do
+not prevent the agent from asking questions about the task.
 
-**Auto-accept edits**: auto-approve edits, ask before other actions. File changes go through
-without prompting; commands and anything else still stop for approval.
+## Provider differences
 
-**Auto**: routine actions proceed without you; risky ones still ask. How this is enforced depends
-on the provider: Codex delegates routine approvals to an AI reviewer, Claude uses its own auto
-permission mode, Cursor uses Smart Auto review, and providers without an equivalent (such as
-OpenCode and Antigravity) fall back to asking, like Supervised.
-
-**Full access**: allow commands and edits without prompts. The default. The agent runs
-unattended until it finishes or asks a question of its own.
-
-Approvals appear inline in the conversation. Approve or reject one and the agent continues from
-there.
+Providers enforce permissions differently. Some read-only actions can proceed in **Supervised**.
+**Auto** uses automatic review on Codex, Claude, and Cursor; providers without an equivalent,
+including OpenCode and Antigravity, fall back to asking.
 
 For Grok, **Always allow this session** remembers the matching command or tool input. Other
-actions still ask for approval. It does not change the thread to **Full access**.
-
-Antigravity uses its own permission policy for each mode. T3 Code still shows any approval or
-question the official agent sends in **Full access**. A remembered approval is available only
-when the agent offers it for that action. Fixed-choice questions require one of the offered
-answers and do not accept custom text.
-
-## Choosing a Mode
-
-Use **Full access** for work in a worktree or a sandbox you can throw away.
-
-Use **Supervised** on a repository where an unwanted command is expensive, or the first time you
-run an unfamiliar task.
-
-**Auto-accept edits** suits refactors where the edits are the point and you only care about the
-shell commands.
-
-## Provider Behavior
-
-Each provider maps these modes onto its own approval and sandbox settings. Codex, for example,
-translates the mode into its approval policy and sandbox level, so **Supervised** runs the CLI
-with prompting enabled and a restricted workspace while **Full access** disables both. Grok
-threads do the same: **Supervised** starts Grok in ask mode even if your Grok CLI config is
-set to always-approve, and **Full access** starts Grok with always-approve. The labels above
-describe what you get; the exact per-provider translation is internal and may change.
+actions still require approval.
 
-Mobile offers the same four modes with the same labels and descriptions.
+Antigravity can still send native approval requests in **Full access**. It only offers remembered
+approvals for actions that support them.
 
-Antigravity's native `/plan` command requests a plan. It does not change the permission mode.
-T3 Code's separate Plan mode control is not available for Antigravity. See
-[Antigravity](./providers-antigravity.md) for setup and thread limits.
+See the [provider guides](./install.md#providers) for setup and provider-specific limits.
diff --git a/docs/user/project-settings.md b/docs/user/project-settings.md
index 604de45258b0..747bc52c07ec 100644
--- a/docs/user/project-settings.md
+++ b/docs/user/project-settings.md
@@ -1,32 +1,18 @@
-# Customize a project icon
+# Project settings
 
-T3 Code selects a project icon automatically. It checks `t3.json`, common favicon and app icon
-paths, and icon links in project HTML files. If it does not find an image, it chooses a built-in
-icon from the saved project name. In web and desktop, this icon stays the same when the sidebar
-shows a repository label such as `owner/repo`.
+Open **Settings → Projects** and select a project to change its preferences.
 
-To choose a different icon or emoji:
+## Project icons
 
-1. Open **Settings** and select **Projects**.
-2. Select the project.
-3. Next to **Project icon**, select **Choose icon**.
-4. Search the full Lucide icon set and choose a color, or switch to **Emoji** and choose or paste
-   an emoji.
-
-To use an image from the project instead, select **Choose file**, search for an image, and select
-it.
-
-T3 Code supports SVG, PNG, ICO, JPEG, GIF, AVIF, and WebP files. The selected path applies to
-each checkout in the project group and appears on your connected clients.
-
-To use automatic detection again, select **Automatic**.
+Choose an icon, emoji, or image from the project to make it easier to recognize. The choice applies
+to every checkout in the project group and appears on connected clients. Choose **Automatic** to
+let T3 Code detect an icon again.
 
 ## Keep the default branch current
 
-Turn on **Automatically pull** in a project's settings to keep its default-branch checkout current.
-T3 Code checks in the background and when the server starts. It uses the branch's configured
-upstream and only performs a fast-forward pull when the checkout has no working-tree changes,
-untracked files, or local commits.
+Enable **Automatically pull** to keep the default-branch checkout up to date with its configured
+upstream.
 
-The pull is skipped if the checkout is on another branch, has no upstream, or contains local work.
-Pull failures do not prevent the server from starting.
+T3 Code only pulls when it can fast-forward and the checkout has no changed files, untracked files,
+or local commits. It skips checkouts on another branch or without an upstream. If a checkout has
+local work, resolve it yourself before automatic pulls can resume.
diff --git a/docs/user/providers-antigravity.md b/docs/user/providers-antigravity.md
index db05ccb8ed69..7466cba309ac 100644
--- a/docs/user/providers-antigravity.md
+++ b/docs/user/providers-antigravity.md
@@ -1,198 +1,135 @@
 # Antigravity
 
-T3 Code runs Google's official Antigravity ACP agent. By default it signs in with your personal
-Google account and uses that account's Antigravity access, including access provided by a
-Google AI subscription. It never falls back to a different sign-in method than the one you
-select.
-
-The agent, files, conversation state, and Google credentials stay on the selected environment.
-Your browser or phone controls that environment. Signing in to the Antigravity IDE or CLI does
-not sign in this T3 Code provider.
+T3 Code runs Google's official Antigravity ACP agent on your selected environment.
+It has its own sign-in, separate from the Antigravity IDE or CLI. Google controls
+which models and account access are available through this agent.
 
 ## Set up Antigravity
 
-On web or desktop, open **Settings** > **Providers**, select the device that runs your project,
-then select **Antigravity**. Provider setup is not available in the mobile app.
-
-1. Choose **Enable Antigravity**. Antigravity is off by default.
-2. Choose **Install Antigravity**. T3 Code downloads the official runtime from Google to that
-   environment. Installation continues if you leave the page or reconnect.
-3. Choose **Sign in with Google**.
-4. Choose **Open sign-in page**. You can use **Copy sign-in link** to open it in another browser.
-5. Complete Google sign-in. Use the account you use for Antigravity.
-6. Wait for T3 Code to confirm sign-in and load the model choices. Select an Antigravity model
-   in the thread's model picker.
+On web or desktop, open **Settings > Providers**, choose the environment that runs
+your project, and enable Antigravity. Install its runtime there, then choose
+**Sign in with Google** and complete the browser sign-in. Wait for T3 Code to confirm
+account access and load models before starting a thread. Provider setup is not
+available in the mobile app.
 
-Setup requires a connection with permission to operate the environment. If setup is unavailable
-on an older server, update that environment first.
+Installation continues if you leave settings or reconnect. Setup requires
+permission to operate the environment; update an older server if it does not offer
+Antigravity setup.
 
 ### Sign in from a remote device
 
-Google returns to a `127.0.0.1` address on the device running your browser. If that is the same
-machine as the T3 Code environment, sign-in can finish directly.
+Google returns to a `127.0.0.1` address. It can finish directly when your browser is
+on the environment's machine. From another device, the final page will usually
+fail to load because the sign-in listener is on the environment.
 
-On a phone or another computer, the final page will usually fail to load. This is expected.
-Copy the full address from the browser, including everything after `?`, and paste it into the
-return URL field in the web or desktop client where you started setup. Choose **Continue**. Do not
-change the address to your server's hostname.
+Copy the full return address, including everything after `?`, into the return URL
+field in the web or desktop client where you started setup, then choose
+**Continue**. Keep the original address; do not replace it with the server's
+hostname. Only that T3 Code sign-in session can finish the attempt. If it expires,
+retry sign-in and use the new link.
 
-Return to the same T3 Code client and environment where you started sign-in. Another client
-can see that sign-in is in progress, but cannot complete that attempt. The setup screen shows
-the expiry time. If it expires, choose **Retry Google sign-in** and use the new link.
-
-The return URL contains a temporary sign-in code. Paste it only into the setup field, not into
-a thread or bug report. T3 Code waits for Google's agent to confirm sign-in. A successful
-callback page alone does not prove account access.
+The return URL contains a temporary sign-in code. Paste it only into the setup
+field. A successful callback page alone does not confirm account access; wait for
+T3 Code's confirmation.
 
 ### Other sign-in methods
 
-**Sign-in method** in the Antigravity provider settings on web or desktop selects how the
-agent authenticates.
-
-| Method                     | What you enter                           | How it signs in                 |
-| -------------------------- | ---------------------------------------- | ------------------------------- |
-| Google account             | Nothing                                  | Google sign-in page             |
-| Gemini Enterprise          | GCP project and GCP location             | Google sign-in page             |
-| Gemini API key             | API key                                  | Choose **Connect**. No browser. |
-| Agent Platform (Vertex AI) | API key, or GCP project and GCP location | Choose **Connect**. No browser. |
+Choose **Sign-in method** in the Antigravity provider settings:
 
-Gemini Enterprise resolves your license for the project and location you enter. Agent Platform
-with a project and location uses Application Default Credentials on the environment. API keys
-are stored in plain text in T3 Code settings on that environment and are passed only to the
-Antigravity agent process. Ambient `GEMINI_API_KEY` or `GOOGLE_*` variables on the environment
-are ignored.
+| Method                     | Credentials                                                                                  |
+| -------------------------- | -------------------------------------------------------------------------------------------- |
+| Google account             | Personal Google sign-in in the browser                                                       |
+| Gemini Enterprise          | Browser sign-in, GCP project, and GCP location                                               |
+| Gemini API key             | API key; choose Connect without a browser                                                    |
+| Agent Platform / Vertex AI | API key, or GCP project and location with Application Default Credentials on the environment |
 
-Changing the method stops the instance's sessions. Sign out or disconnect before you switch
-accounts.
+The Antigravity API key field is stored in plain text in settings on the
+environment. The agent uses the method and credentials selected for this instance;
+ambient `GEMINI_API_KEY` and Google credential variables do not override them.
+Changing the method stops the instance's sessions. Sign out before replacing an
+account.
 
 ## Runtime installation
 
-Managed downloads are available for these environment hosts:
-
-| Host    | Architecture  |
-| ------- | ------------- |
-| macOS   | Apple Silicon |
-| Linux   | x64 or ARM64  |
-| Windows | x64 or ARM64  |
-
-Google does not publish a local Intel Mac runtime. Use an Intel Mac as a client connected to
-a supported remote environment.
-
-The current Linux x64 runtime downloads about 682 MB and uses about 2.01 GB after extraction.
-Allow at least 3 GB free for installation. An update keeps the previous runtime too.
-T3 Code does not download it until you choose to install it.
-
-On web or desktop, **Update Antigravity** appears when T3 Code has a newer managed release.
-Running sessions keep their current runtime. New sessions use the installed update.
+Managed installation supports Apple Silicon macOS, Linux x64 or ARM64, and Windows
+x64 or ARM64. Intel Macs can connect to a supported remote environment. Allow
+several GB of free disk space, especially on Linux.
 
 ### Use a manual installation
 
-Download the correct archive from the [official ACP Registry][registry] and extract both the
-ACP executable and its `localharness_external` helper into the same directory. Keep both files
-at the same version and make them executable on macOS or Linux. Windows uses `.exe` files.
+Download the archive for your environment from the [official ACP Registry][registry].
+Extract the ACP executable and its `localharness_external` helper into the same
+directory, at the same version. Make both executable on macOS or Linux; Windows
+uses `.exe` files.
 
-On web or desktop, set **Binary path** in the Antigravity provider settings to the ACP
-executable on the selected environment. Do not point it at the helper or the Antigravity IDE.
-
-A nonempty **Binary path** takes priority. With the field empty, T3 Code uses its managed
-runtime, then an installation on the environment's `PATH`. An invalid explicit path reports
-an error instead of selecting another installation. T3 Code does not update or remove manual
-installations. Clear **Binary path** to use managed installation controls.
+Set **Binary path** to the ACP executable on the environment and update it yourself.
+Leave the field blank to use the managed runtime, or a compatible executable on
+`PATH` if no managed runtime is installed.
 
 ## Models and threads
 
-The current official ACP exposes Gemini models only. T3 Code uses the model IDs and names
-returned for your account, including any model choices with different thinking levels. Models
-available in other Antigravity apps might not be available through this agent.
-The model picker updates when a running session reports new model choices.
-
-New threads use Gemini 3.8 Flash (High) when your account offers it. Older Gemini generations
-stay available under **Legacy models** in the picker.
-
-Threads keep their selected model when you resume them. If that model is no longer available,
-T3 Code asks you to select an available model instead of silently changing it.
-
-Use Antigravity's native `/plan` command to request a plan. T3 Code's separate Plan mode control
-is not available for this provider.
+The model list comes from your Antigravity account and can differ from other
+Antigravity apps. A resumed thread keeps its selected model. If access to that
+model ends, select another available model before continuing.
 
-Project skills should use `.agents/skills`. T3 Code also discovers `.gemini/skills` and the legacy
-`.agent/skills` location. When multiple locations define the same skill name, `.gemini/skills`
-takes precedence, followed by `.agents/skills` and then `.agent/skills`.
+Use Antigravity's native `/plan` command for planning. T3 Code's separate Plan mode
+is unavailable. Tool approvals follow [Permission modes](./permission-modes.md).
+Questions with fixed choices still need one of the offered answers, even in
+**Full access**.
 
-Antigravity reads and edits workspace files through T3 Code. Each write shows up as a file
-change approval with the content, so **Supervised** and **Auto-accept edits** behave the same way
-they do for other providers. Attach images, PDFs, text files, or audio clips to a message and
-the agent receives them directly.
+T3 Code keeps conversation history and file diffs, but Antigravity cannot rewind
+its conversation. Reverting a thread or editing and resubmitting an earlier turn
+is unavailable. Continue with a follow-up message or start a new thread.
 
-When the agent offers **Allow for this thread** on a shell or web tool, T3 Code shows Google's
-prompt injection warning next to that choice. Untrusted content could re-run the same action
-without asking again.
+### Skills and attachments
 
-Antigravity can ask you to choose from a fixed set of answers. Select one of the offered
-choices. These questions do not accept custom text and still appear in **Full access** mode.
-See [Permission modes](./permission-modes.md) for tool approvals.
+Put project skills in `.agents/skills`. T3 Code also reads `.gemini/skills` and the
+legacy `.agent/skills` directory. Among these project locations, the first copy
+wins in this order: `.gemini/skills`, `.agents/skills`, `.agent/skills`. See
+[commands and skills](./composer.md#commands-and-skills) for invoking them.
 
-T3 Code keeps thread history and file diffs. Antigravity does not support conversation rewind,
-so reverting a thread or editing and resubmitting an earlier turn is unavailable. Send a
-follow-up message or start a new thread instead.
+Antigravity accepts images, PDFs, text files, and supported audio formats directly.
+Its limits are 1 MiB per text file, 10 MiB per image, 20 MiB per audio clip, and
+50 MiB total attachments per message. Unsupported formats are rejected. These
+limits can be lower than the general upload limit; uploading a file does not
+mean this provider can use it.
 
 ### Subagents
 
-Subagent launches appear as **Antigravity subagent batch** in **Agents** on web and desktop,
-and in the work log on mobile. One launch can start several agents. The batch stays active
-after launch while the parent turn runs. When that turn ends, the entry becomes idle and
-states that individual agent status is unavailable. Launch errors remain visible.
-The conversation summary counts launches as batches and shows idle or stopped batches
-without a completion checkmark.
-
-The official ACP agent does not send individual child status, names, models, token usage,
-or reply ownership. T3 Code cannot show separate child entries or separate child replies
-from the parent conversation. The launch description is not a child result. Batch entries
-cannot be opened or controlled as separate threads.
+Antigravity groups subagent activity into batches. You cannot open or control
+individual subagents, and an idle batch does not confirm that every child
+succeeded. See [agent work](./thread-sidebar.md#inspect-agent-work) for where to
+inspect activity.
 
 ## Accounts and removal
 
-Each Antigravity provider instance has its own Google sign-in on its environment. Use
-**Add provider** in web or desktop provider settings to create a separate instance for another
-account. To replace an instance's account, sign out first, then sign in again.
-
-| Action                    | Result                                                                                                                        |
-| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| Disable Antigravity       | Stops the instance's sessions. Keeps Google sign-in, thread history, and files.                                               |
-| Sign out of Google        | Stops the instance's sessions and removes its saved Google credentials. Keeps thread history and files.                       |
-| Remove downloaded runtime | Removes the runtime shared by Antigravity instances on that environment. Keeps Google credentials, thread history, and files. |
-
-Send `/logout` by itself in an Antigravity thread to sign out that provider instance. This has
-the same effect as **Sign out of Google**, including stopping its other sessions.
-
-Before removing a managed runtime, disable the instances that use it and cancel any active
-installation. T3 Code refuses removal while the runtime is in use. An explicit **Binary path**
-that points into the managed runtime must be cleared first.
+Add an Antigravity provider instance for each Google account in
+**Settings > Providers** on web or desktop. Each has its own sign-in; downloaded
+runtimes are shared on the environment.
 
-## Account access and errors
+| Action                    | Effect                                                            |
+| ------------------------- | ----------------------------------------------------------------- |
+| Disable                   | Stops the instance's sessions and keeps its Google sign-in.       |
+| Sign out of Google        | Stops the instance's sessions and removes its saved Google login. |
+| Remove downloaded runtime | Removes the shared installation and keeps Google credentials.     |
 
-Google controls account eligibility, models, and usage limits. T3 Code does not report your
-paid-plan tier or remaining subscription quota. See Google's [Antigravity plans][plans] and
-[personal Google sign-in guide][google-setup].
+All three keep thread history and workspace files. Sending `/logout` by itself in
+a thread signs out its instance, including stopping that instance's other sessions.
+Sign out, then sign in again to replace an account.
 
-After an environment restarts, Google sign-in can show as not checked until an authenticated
-session succeeds. You can continue an existing thread. Antigravity checks saved Google sign-in
-when the session starts. An unchecked status does not require signing in again.
+Before removing a managed runtime, disable its instances and cancel any active
+installation. Clear any explicit binary path pointing into that runtime. Removal
+is refused while the runtime is in use.
 
-To check account access and reload models on web or desktop, open **Settings** > **Providers**
-and select the circular arrow beside **Checked** at the top of the page. Its tooltip says
-**Refresh provider status**. On mobile, use **Refresh models** in the model picker.
-Refresh uses saved Google sign-in and does not open a login page. If sign-in is required,
-use the provider's setup controls on web or desktop. Automatic status checks verify the
-installation only.
+## Check access and troubleshoot
 
-The packaged runtime can be slow to start, especially on Windows. Health checks, model refresh,
-and sign-out each allow up to 90 seconds before reporting a timeout.
+To check access and reload models, use **Refresh provider status** in web or desktop
+provider settings, or **Refresh models** in mobile thread settings. If asked to
+sign in again, use setup on web or desktop.
 
-If Google reports `SUBSCRIPTION_REQUIRED`, an account restriction, or a usage limit, read the
-provider's message. A finished turn can contain an upstream error instead of completed work.
-Use any retry time Google supplies. T3 Code does not switch to an API key to get past the limit.
+If Google reports `SUBSCRIPTION_REQUIRED`, an account restriction, or a usage limit,
+follow the provider's message and any retry time. See [Google's account plans][plans]
+for eligibility.
 
 [registry]: https://github.com/agentclientprotocol/registry/blob/main/antigravity-acp/agent.json
 [plans]: https://antigravity.google/docs/plans
-[google-setup]: https://antigravity.google/docs/ide/extensions/zed
diff --git a/docs/user/providers-claude.md b/docs/user/providers-claude.md
index 498fa802474d..707cb5493225 100644
--- a/docs/user/providers-claude.md
+++ b/docs/user/providers-claude.md
@@ -1,236 +1,89 @@
 # Claude
 
-This guide is for people who want to use more than one Claude setup in T3 Code. For Codex, see
-[Codex](./providers-codex.md). For first-time setup, see [Install T3 Code](./install.md).
+T3 Code uses Claude Code's login and configuration. Start with the default provider
+for one account; [provider setup](./install.md#providers) covers installation and
+shared provider settings.
 
-Common reasons:
+## Separate accounts or configurations
 
-- use separate work and personal Claude accounts
-- try a different Claude Code configuration without disturbing your main setup
-- run Claude through a router such as Claude Code Router
-- use external providers exposed through a Claude-compatible workflow
+Use a separate Claude config directory for each account. This also works for named
+presets that need different Claude settings or a router connection.
 
-## I Only Use One Claude Account
-
-Use the default provider.
-
-Log in with Claude Code normally:
-
-```bash
-claude auth login
-```
-
-In T3 Code Settings, your Claude provider can stay like this:
-
-```text
-Display name: Claude
-Binary path: claude
-CLAUDE_CONFIG_DIR path: empty
-```
-
-An empty `CLAUDE_CONFIG_DIR path` means T3 Code uses Claude Code's normal config directory.
-
-When you set this field, T3 Code points Claude Code at that directory with the
-`CLAUDE_CONFIG_DIR` environment variable. It does not change `HOME`, so your system keychain and
-the rest of your environment stay as they are.
-
-## Reduce Context Usage
-
-In Settings, open your Claude provider and set **Auto-compact after** to a token count between
-`100000` and `1000000`. For example, `300000` compacts the conversation into a summary once it
-reaches about 300,000 tokens, without changing the model's context window. Leave the field
-empty to keep Claude Code's default behavior.
-
-On web and desktop, when you return to an older Claude thread with a large context, T3 Code
-offers to compact the conversation before you continue. You can also select **Compact context**
-from the context meter. On every client, you can enter `/compact` in the message composer, and
-Claude can show its own resume prompt when you continue an old session.
-
-## Where Claude Skills Are Loaded
-
-T3 Code looks for Claude skills in the Claude config directory's `skills` folder and
-`<workspace>/.claude/skills`, the two places Claude Code loads them from.
-
-If the same skill name exists in more than one folder, the one in the Claude config directory
-wins, the same way Claude Code resolves it.
-
-A skill set to `off` in Claude Code's `skillOverrides` is left out of both composer menus. A skill
-marked `disable-model-invocation` still appears, because you start it yourself when you pick it.
-Claude Code runs one skill per message; when a message names several, the last one runs directly and
-Claude starts the others through its Skill tool, which refuses skills marked
-`disable-model-invocation`.
-
-## I Want Work And Personal Claude Accounts
-
-Use a different Claude config directory for each account.
-
-Example:
-
-```text
-default config dir           work account
-~/.claude_personal_home      personal account
-```
-
-### Set Up The First Account
-
-Log in normally:
-
-```bash
-claude auth login
-```
-
-In T3 Code Settings:
-
-```text
-Display name: Claude Work
-Binary path: claude
-CLAUDE_CONFIG_DIR path: empty
-```
-
-### Set Up The Second Account
-
-Log in with a separate config directory:
-
-```bash
-mkdir -p ~/.claude_personal_home
-CLAUDE_CONFIG_DIR=~/.claude_personal_home claude auth login
-```
-
-Use `CLAUDE_CONFIG_DIR`, not `HOME`. Setting `HOME` writes the login to
-`~/.claude_personal_home/.claude`, which is not where T3 Code looks.
-
-Then add another Claude provider in T3 Code:
-
-```text
-Display name: Claude Personal
-Binary path: claude
-CLAUDE_CONFIG_DIR path: ~/.claude_personal_home
-```
-
-Use the email shown in Settings to confirm each provider is using the intended account. Emails are
-blurred by default; click the blurred email to reveal it.
-
-## Can I Switch Claude Accounts In An Existing Thread?
-
-Usually, no.
-
-T3 Code only offers Claude providers that use the same config directory for an existing thread. A
-different config directory is treated as a different Claude environment.
-
-This is different from the recommended Codex setup. Claude Code keeps account and local state across
-multiple files under its config directory, so T3 Code keeps separate config directories isolated
-instead of trying to share part of the state.
-
-## I Want To Use OpenRouter
-
-Use this when you want Claude Code to talk to OpenRouter directly, without running a local router.
-This is the simplest external-provider setup.
-
-OpenRouter provides a Claude Code integration through Claude's Anthropic-compatible environment
-variables.
-
-### Configure A Claude OpenRouter Provider
-
-Add or edit a Claude provider in T3 Code Settings:
-
-```text
-Display name: Claude OpenRouter
-Binary path: claude
-CLAUDE_CONFIG_DIR path: ~/.claude_openrouter_home
-```
-
-In that provider's Environment variables section, add:
-
-```text
-ANTHROPIC_BASE_URL   https://openrouter.ai/api
-ANTHROPIC_AUTH_TOKEN sk-or-...                Sensitive
-ANTHROPIC_API_KEY                              Empty value
-```
-
-Mark `ANTHROPIC_AUTH_TOKEN` as sensitive. T3 Code stores the value as a server secret and does not
-send it back to the app after saving.
-
-If you want this setup isolated from your normal Claude account, create that home first:
+Keep your existing account in the default directory. On the environment's machine,
+create the second login:
 
 ```bash
-mkdir -p ~/.claude_openrouter_home
+mkdir -p ~/.claude_personal
+CLAUDE_CONFIG_DIR=~/.claude_personal claude auth login
 ```
 
-If you previously used the same Claude home with a normal Anthropic login, run `/logout` in a Claude
-Code session for that home before using OpenRouter. Otherwise Claude Code may keep using cached
-Anthropic credentials instead of the OpenRouter token.
+Add another Claude instance in **Settings > Providers**:
 
-### Pick OpenRouter Models
+| Instance        | Binary path | CLAUDE_CONFIG_DIR path |
+| --------------- | ----------- | ---------------------- |
+| Claude Work     | `claude`    | Leave empty            |
+| Claude Personal | `claude`    | `~/.claude_personal`   |
 
-OpenRouter can route Claude Code's default model roles to OpenRouter model IDs.
+An empty config-directory setting uses Claude Code's normal configuration. The
+custom setting changes `CLAUDE_CONFIG_DIR`, leaving `HOME` and the system keychain
+location intact. Use the same variable for the login command. Setting `HOME`
+instead can put credentials where this provider will not find them.
 
-Example:
+Check the account reported in provider settings after signing in. Existing
+threads can switch only between Claude instances with the same config directory.
+Separate account directories stay isolated, including their local conversation
+state. Claude does not have Codex's shared-home and shadow-home arrangement.
 
-```text
-ANTHROPIC_DEFAULT_OPUS_MODEL    anthropic/claude-opus-4.6
-ANTHROPIC_DEFAULT_SONNET_MODEL  anthropic/claude-sonnet-4.6
-ANTHROPIC_DEFAULT_HAIKU_MODEL   anthropic/claude-haiku-4.5
-CLAUDE_CODE_SUBAGENT_MODEL      anthropic/claude-sonnet-4.6
-```
-
-Add those to the same provider's Environment variables section if you want stable model choices.
+For presets that differ only in API keys or endpoints, use the instance's
+**Environment variables**. Variable assignments do not belong in **Launch arguments**.
 
-### Verify OpenRouter Is Being Used
+## Compact long conversations
 
-Open a Claude session and run:
+Set **Auto-compact after** in the Claude provider settings to an integer between
+`100000` and `1000000`. For example, `300000` asks Claude to summarize at about
+300,000 tokens. This changes when compaction happens, not the model's context
+window. Leave it empty for Claude Code's default.
 
-```text
-/status
-```
+You can also send `/compact` in an existing conversation. Web and desktop offer
+**Compact context** from the context meter and may suggest it when you return to
+a large older thread. See [commands and skills](./composer.md#commands-and-skills)
+for using composer commands.
 
-You should see the Anthropic base URL set to:
+## Skills
 
-```text
-https://openrouter.ai/api
-```
+Claude skills come from the config directory's `skills` folder and the project's
+`.claude/skills` folder. If both define the same name, the config-directory copy
+wins. Skills disabled in Claude's settings do not appear in the composer.
 
-You can also check the OpenRouter activity dashboard for requests from your API key.
-
-### Common OpenRouter Mistakes
-
-- Use `https://openrouter.ai/api`, not `https://openrouter.ai/api/v1`, for Claude Code.
-- Set `ANTHROPIC_AUTH_TOKEN` to your OpenRouter API key.
-- Set `ANTHROPIC_API_KEY` to an empty string so Claude Code does not try to use an Anthropic login.
-- Put these variables on the Claude provider instance, not in global shell startup files.
-
-OpenRouter's setup can change over time. Use its upstream Claude Code guide for the current details:
-<https://openrouter.ai/docs/guides/guides/claude-code-integration>.
-
-## I Want To Use Claude Code Router
-
-Claude Code Router is useful when you want a local routing layer with more control than a direct
-OpenRouter setup.
-
-T3 Code does not need a special Claude Code Router provider. Treat the router as a Claude
-environment: give a Claude provider its own `CLAUDE_CONFIG_DIR path`, and put whatever variables
-the router tells you to export into that provider's Environment variables section. Mark tokens
-and API keys as sensitive.
-
-```text
-Display name: Claude Router
-Binary path: claude
-CLAUDE_CONFIG_DIR path: ~/.claude_router_home
-```
+Use `$` in the composer to select a skill. Skills marked `disable-model-invocation`
+can still be started by you. Invoke those one per message: Claude directly runs
+only the last named skill and may try to start earlier ones through its Skill
+tool, which refuses skills reserved for manual invocation.
 
-Follow the upstream project's README for the router's own install, startup, and configuration
-steps: <https://github.com/musistudio/claude-code-router>.
+## OpenRouter
 
-## I Want Different Claude Settings, Not A Different Account
+Create a Claude instance with its own config directory, such as
+`~/.claude_openrouter`, and keep **Binary path** set to `claude`. In that instance's
+**Environment variables**, use:
 
-Create another Claude provider with the same account if you want a named preset.
+| Variable               | Value                                     |
+| ---------------------- | ----------------------------------------- |
+| `ANTHROPIC_BASE_URL`   | `https://openrouter.ai/api`               |
+| `ANTHROPIC_AUTH_TOKEN` | Your OpenRouter API key, marked Sensitive |
+| `ANTHROPIC_API_KEY`    | An explicitly empty value                 |
 
-Examples:
+If that Claude config directory has a cached Anthropic login, run `/logout` in a
+Claude Code session using that directory before starting the router setup. Cached
+login credentials can conflict with the router token.
 
-- "Claude Default"
-- "Claude Router"
-- "Claude Experimental"
+Verify requests in OpenRouter's activity dashboard. For model-role overrides and
+current compatibility requirements, use the
+[OpenRouter Claude Code guide](https://openrouter.ai/docs/cookbook/coding-agents/claude-code-integration).
 
-If the preset needs different Claude files, give it a different `CLAUDE_CONFIG_DIR path`. If it needs
-different API keys, base URLs, or router settings, use Environment variables.
+## Other routers
 
-Do not put environment variable assignments in `Launch arguments`.
+A local router uses an ordinary Claude provider instance. Give it a separate
+config directory and put the router's endpoint and credential variables in that
+instance's **Environment variables**. The router must run where the environment
+can reach it. Follow the [Claude Code Router instructions](https://github.com/musistudio/claude-code-router)
+for its installation and routing configuration.
diff --git a/docs/user/providers-codex.md b/docs/user/providers-codex.md
index 5556ef18f119..417287cc0032 100644
--- a/docs/user/providers-codex.md
+++ b/docs/user/providers-codex.md
@@ -1,179 +1,71 @@
 # Codex
 
-This guide is for people who want to use more than one Codex account in T3 Code. For Claude, see
-[Claude](./providers-claude.md). For first-time setup, see [Install T3 Code](./install.md).
+For one account, use the default Codex provider with your normal Codex login.
+[Provider setup](./install.md#providers) covers installation, Settings > Providers,
+and custom binaries or environment variables.
 
-Common reasons:
+## Use multiple accounts
 
-- use a work account for work projects
-- use a personal account for personal projects
-- switch to another account when one account hits limits
-- keep one shared Codex history instead of maintaining two separate Codex setups
+A shared Codex home with a shadow home lets work and personal accounts continue
+the same threads. The accounts share Codex sessions and configuration while keeping
+their own login and available models.
 
-## I Only Use One Codex Account
-
-Use the default provider.
-
-In Settings, your Codex provider can stay like this:
-
-```text
-Display name: Codex
-CODEX_HOME path: ~/.codex
-Shadow home path: empty
-```
-
-Log in with Codex normally:
-
-```bash
-codex login
-```
-
-## Send feedback to OpenAI
-
-In an existing Codex thread, send `/feedback` or `/feedback` followed by a description of the
-issue. T3 Code uploads the thread and Codex logs to OpenAI and shows a thread ID that you can copy
-and share with OpenAI employees.
-
-## Answer questions while Codex works
-
-Codex can ask questions without stopping its work. Choose a suggested answer or enter your own
-in the question panel. Questions without suggested answers accept text.
-
-Your answers are sent as a new message. They reach the current turn while Codex is working, or
-start a new turn if it has finished. Unanswered questions stay available after you reconnect.
-This works in the web, desktop, and mobile apps. Codex must support async questions.
-
-## Sub-agent models
-
-The web and desktop Agents panel shows each sub-agent's model and reasoning effort when Codex
-reports them. If Codex does not report either value, T3 Code leaves it out instead of using the
-parent agent's settings.
-
-## Browser and computer activity
-
-Browser and Computer Use calls show their user-facing task title when Codex provides one. Expanded
-activity groups show an icon for every call. Website calls use the active page's favicon when it is
-available, and desktop app calls use the app's native icon on macOS when available. Other hosts use
-a generic fallback glyph.
-
-Collapsed activity groups are summarized by source, such as `Used Chrome integration`, instead of
-showing the underlying tool name. Website favicons and native app icons keep their original colors;
-integrations that provide separate light and dark logos use the logo for the current appearance.
-
-## Approve access to other apps
-
-When a Codex tool needs access to an app such as Safari, T3 Code shows the app name and asks for
-approval. You can approve, decline, or cancel the request from the desktop app, web app, or mobile
-app. Some tools also offer approval for the current session or permanent approval.
-
-## I Want Work And Personal Codex Accounts
-
-Use one real Codex home and one shadow home.
-
-Recommended setup:
-
-```text
-~/.codex      shared Codex home
-~/.codex_p    second account auth
-```
-
-The idea is:
-
-- both accounts can see the same T3/Codex sessions
-- each account keeps its own login
-- existing threads can continue with either account
-
-### Set Up The First Account
-
-Log in normally:
-
-```bash
-codex login
-```
-
-This is the account used by `~/.codex`.
-
-In T3 Code Settings, name it something obvious:
-
-```text
-Display name: Codex Work
-CODEX_HOME path: ~/.codex
-Shadow home path: empty
-```
-
-### Set Up The Second Account
-
-Log in with a separate Codex home:
+Keep your first account in `~/.codex`. On the environment's machine, sign the
+second account into a fresh directory:
 
 ```bash
-mkdir -p ~/.codex_p
-CODEX_HOME=~/.codex_p codex login
-```
-
-In T3 Code Settings, add another Codex provider:
-
-```text
-Display name: Codex Personal
-CODEX_HOME path: ~/.codex
-Shadow home path: ~/.codex_p
+mkdir -p ~/.codex_personal
+CODEX_HOME=~/.codex_personal codex login
 ```
 
-The important part is that both providers use the same `CODEX_HOME path`, but only the second one
-has a `Shadow home path`.
-
-## Which Account Am I Using?
-
-Open Settings and look at the provider row.
-
-T3 Code shows the authenticated email for providers that report one. Emails are blurred by default;
-click the blurred email to reveal it.
-
-Use display names and accent colors to make accounts easy to tell apart in the model picker.
-
-## I Need A Different API Key Or Endpoint
-
-Use the provider's Environment variables section in Settings.
+Then add a second Codex instance in **Settings > Providers**:
 
-This is useful when a Codex-compatible setup needs account-specific variables. Add the variables to
-the provider instance that should receive them, and mark API keys or tokens as sensitive. Sensitive
-values are stored as server secrets and are not sent back to the app after saving.
+| Instance       | CODEX_HOME path | Shadow home path    |
+| -------------- | --------------- | ------------------- |
+| Codex Work     | `~/.codex`      | Leave empty         |
+| Codex Personal | `~/.codex`      | `~/.codex_personal` |
 
-## Can I Switch Accounts In An Existing Thread?
+Both instances must use the same **CODEX_HOME path**. T3 Code prepares the shared
+state in the shadow directory; do not populate it by copying your whole Codex
+home.
 
-Yes, when both Codex providers share the same `CODEX_HOME path`.
+The shadow account needs its own `auth.json` file. If Codex uses an OS credential
+store, configure file storage for this setup. See
+[OpenAI's credential storage guide](https://learn.chatgpt.com/docs/auth#credential-storage).
 
-For example:
+Use a completely separate **CODEX_HOME path**, with no shadow home, when you want
+separate Codex sessions and configuration. That instance cannot continue threads
+from the other home.
 
-```text
-Codex Work      CODEX_HOME path: ~/.codex
-Codex Personal  CODEX_HOME path: ~/.codex, Shadow home path: ~/.codex_p
-```
+## Switch accounts in an existing thread
 
-Those two providers are considered compatible for continuation, so the locked model picker can show
-both.
+Choose the other account from the thread's model picker. T3 Code offers compatible
+Codex instances that share the thread's **CODEX_HOME path**. Changing accounts does
+not move the conversation into a separate Codex home.
 
-If you add a third Codex provider with a completely different `CODEX_HOME path`, T3 Code treats it
-as a different workspace. It will not be offered for existing threads created under `~/.codex`.
+If the account is missing from the picker, compare the home paths in provider
+settings. If two instances show the same unexpected account or models, check their
+reported accounts, refresh provider status, and confirm the second instance has
+its own shadow path and login. A shadow-home conflict usually means the directory
+contains a copied Codex setup. Use a fresh shadow directory and sign in again.
 
-## If Both Accounts Look The Same
+## Answer questions while Codex works
 
-If two Codex providers show the same account or the same unexpected model list:
+Codex can ask a question and keep working. Answer it in the thread's question
+panel. The answer becomes a new message: it reaches the active turn, or starts
+another turn if Codex has finished. Unanswered questions survive reconnects.
+This requires a Codex version that supports async questions.
 
-1. Check the email in Settings.
-2. Refresh provider status.
-3. Confirm the second provider has `Shadow home path` set.
-4. Confirm the shadow directory has its own `auth.json`.
-5. If you copied `~/.codex` into the shadow directory, remove everything except `auth.json`.
+## Approve app access
 
-Example cleanup:
+Codex tools can request access to another app. Respond to the named app's request
+in the thread on web, desktop, or mobile. Some tools offer access for one request,
+the current session, or permanently. See [Permission modes](./permission-modes.md)
+for command and file approvals.
 
-```bash
-find ~/.codex_p -mindepth 1 ! -name auth.json -exec rm -rf {} +
-```
-
-## When To Use A Separate CODEX_HOME
-
-Use a totally separate `CODEX_HOME path` only when you want a separate Codex workspace.
+## Send feedback to OpenAI
 
-That means separate sessions and less account switching inside old threads. Most dual-account users
-should use the shared-home plus shadow-home setup instead.
+In an existing Codex thread, send `/feedback` with an optional description, for
+example `/feedback The agent stopped before finishing the tests`. This uploads
+the conversation and Codex logs to OpenAI. The returned thread ID can be shared
+with OpenAI support.
diff --git a/docs/user/providers-opencode.md b/docs/user/providers-opencode.md
index 141aa2926add..23de99798956 100644
--- a/docs/user/providers-opencode.md
+++ b/docs/user/providers-opencode.md
@@ -1,93 +1,49 @@
 # OpenCode
 
-T3 Code uses the OpenCode setup on the connected environment. With a remote environment, its
-OpenCode login and configuration apply, not the setup on your desktop or phone.
+Install and authenticate OpenCode on the machine running your environment, then
+enable it in **Settings > Providers**. See [provider setup](./install.md#providers).
+T3 Code requires OpenCode 1.14.19 or newer, including when you connect an existing
+OpenCode server.
 
-T3 Code requires OpenCode 1.14.19 or newer. It checks the server version before it loads models or
-starts work. If the check fails, update OpenCode or fix the server URL and password, then refresh
-the provider status. Reconnecting the client also runs the check again.
+## Local or external server
 
-## Server authentication
+Leave **Server URL** empty to let T3 Code start OpenCode locally. A password in
+provider settings applies to both that server and T3 Code's connection. With no
+password setting, the local server uses `OPENCODE_SERVER_PASSWORD` from its
+environment.
 
-Without a server URL, T3 Code starts a local OpenCode server. The process inherits
-`OPENCODE_SERVER_PASSWORD` from the environment. A password in the provider settings overrides
-that environment value for both the local process and T3 Code.
+To use an existing OpenCode server, set **Server URL** and its password in provider
+settings. T3 Code uses only that configured password for an external server; it
+does not forward a local `OPENCODE_SERVER_PASSWORD`. If connection or version checks
+fail, check the URL, credentials, and OpenCode version, then refresh provider status.
 
-With a server URL, T3 Code connects to that external server and uses only the password in the
-provider settings. It does not send a local `OPENCODE_SERVER_PASSWORD` to an external server.
-OpenCode uses this password for HTTP Basic authentication.
+After a lost connection, send another prompt to reconnect to the same OpenCode
+session.
 
 ## Approvals
 
-In **Supervised** and **Auto** modes, OpenCode can read normal project files, search files, load
-skills, and update its task list without approval. Files such as `.env` and `.env.local` still
-require approval. `.env.example` does not. OpenCode does not have an AI approval reviewer, so
-**Auto** uses the same permission rules as **Supervised**.
+OpenCode follows the shared [permission modes](./permission-modes.md). **Auto** has
+the same rules as **Supervised** because OpenCode has no AI approval reviewer.
+Environment files such as `.env` and `.env.local` need approval in restricted
+modes even though normal file reads do not; `.env.example` is allowed.
 
-OpenCode asks before it runs commands, edits files, accesses the web, or accesses directories
-outside the workspace. **Auto-accept edits** also permits file edits without approval.
-**Full access** permits all these actions. Questions that need your answer can still appear.
+**Allow for workspace** applies to matching requests in other OpenCode sessions
+using the same workspace. It is broader than the current thread, especially on a
+shared external server. Use **Allow once** for a single request. Denying an action
+does not stop the whole turn.
 
-An **Approval** badge means OpenCode needs a decision. Open the thread to see the action and
-choose one of these options:
+## Refresh models, commands, and skills
 
-- **Allow once** permits this request.
-- **Allow for workspace** permits matching requests in other OpenCode sessions in the same
-  workspace. It is not limited to the current thread.
-- **Deny** rejects this request. Use **Stop** to stop the whole turn.
+After changing an OpenCode login or configuration, use **Refresh provider status**
+in **Settings > Providers** for that environment. On mobile, use **Refresh models**
+in the thread settings. Reconnecting also refreshes the catalog; periodic provider
+health checks do not.
 
-If a connection error prevents the reply, the approval stays available so you can try again.
+Credential changes are read on refresh. Native OpenCode configuration can remain
+cached while the local helper is running. Let it sit for 30 seconds without model
+refreshes or text-generation work, then refresh again to reload the files. Repeated
+refreshes keep the helper alive. An external server may need its own reload or
+restart before T3 Code can see configuration changes.
 
-## Progress
-
-T3 Code shows OpenCode's response text and tool results while work runs. The web and desktop apps
-also show its task-list progress. A task-list update does not require approval.
-
-If the OpenCode connection closes unexpectedly, T3 Code shows an error. Send another prompt to
-reconnect to the same OpenCode session.
-
-## Stop a turn
-
-When you select **Stop**, T3 Code stops the main OpenCode session and all nested child sessions.
-T3 Code waits for this cleanup before it marks the turn as stopped or sends the next prompt. It
-does not stop unrelated OpenCode sessions. After Stop succeeds, pending approvals and questions
-are cleared.
-
-Stop reports an error if OpenCode cannot stop the main session or list or stop a child session.
-When T3 Code closes an OpenCode session, it also tries to stop the child sessions, but this
-teardown is best effort.
-
-## Refresh the model list
-
-T3 Code loads the model list when an enabled OpenCode provider starts and keeps the list in its
-cache. Reconnecting a client or using a refresh control asks OpenCode for the list again. The
-periodic provider health setting does not refresh OpenCode's catalog.
-
-After changing an OpenCode login or configuration outside T3 Code, open **Settings > Providers**,
-select the environment, and choose **Refresh provider status**. Changing the provider's
-configuration in T3 Code also replaces that provider connection.
-
-On mobile, open the thread settings and select **Refresh models**. The control stays disabled while
-the refresh runs and shows an error if the refresh fails.
-
-OpenCode reads credential changes on each model-list request. Native OpenCode configuration files
-can stay cached while the local helper is running. The helper closes after 30 seconds with no
-model-list or text-generation work. Refresh after that idle period to start a new helper and read
-the file changes. Repeated refreshes or active helper work can extend this wait.
-
-T3 Code does not own an external OpenCode server. Native configuration changes on that server can
-require its own reload or restart before a refresh returns the new list.
-
-If a refresh fails, T3 Code keeps the last known models, slash commands, and skills. Fix the
-connection, then refresh again. A successful refresh can remove entries that OpenCode no longer
-offers.
-
-## Continue an existing thread
-
-An existing thread keeps its selected model and options when that model is temporarily absent
-from the catalog. The web picker shows an **Unavailable** row and keeps saved option values visible
-until the model metadata returns. T3 Code does not switch the thread to the first model in the
-list.
-
-The stored selection does not guarantee that OpenCode can still run the model. If the provider
-rejects it, select an available model before trying again.
+Existing threads keep their selected model and options even when it disappears
+from the catalog. If OpenCode rejects that model, select an available one and retry.
diff --git a/docs/user/remote-access.md b/docs/user/remote-access.md
index 857bd2153b12..fa1b2a73df54 100644
--- a/docs/user/remote-access.md
+++ b/docs/user/remote-access.md
@@ -1,290 +1,163 @@
-# Remote Access
+# Remote access
 
-Use this when you want to connect to a T3 Code server from another device such as a phone, tablet, or separate desktop app.
+Connect a phone, browser, or another desktop app to T3 Code running on a different
+machine. That machine must stay running and reachable while you work.
 
-## T3 Connect troubleshooting
-
-Run `t3 connect` on the server machine to authorize it and optionally install the background service.
-The authorization message means your sign-in was saved. The server must then start and establish its
-relay link before the machine is reachable.
-
-`t3 connect status` reports saved authorization and link configuration, not a live reachability
-check. If the machine appears offline, run `t3 service status` on it and read the displayed log.
-On Linux, a service that works while SSH is open but stops after logout usually has lingering
-disabled. See [background service troubleshooting](./background-service.md#troubleshooting).
-
-Relay errors include the returned reason and trace ID when available:
-
-| Error                                                            | Next step                                                                                                                                                                   |
-| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `environment_link_limit_exceeded` / managed tunnel limit reached | Unlink an unused environment in T3 Connect, then restart T3 Code on this machine.                                                                                           |
-| `auth_invalid` / `invalid_bearer`                                | Run `t3 connect login`. If the stored credential was revoked, run `t3 connect logout`, then `t3 connect` and restart the server.                                            |
-| Expired or invalid link proof                                    | Check the server's date and time, update T3 Code, and restart it. Include the reason and trace ID if it still fails.                                                        |
-| HTTP 403 without a recognized error response                     | Check relay access and any proxy or firewall restrictions. Include the Cloudflare Ray ID if one was returned; an HTTP status alone does not identify the cause.             |
-| HTTP 408, 429, or 5xx                                            | The server retries temporary failures during startup for up to ten minutes. Check network and relay availability; include the trace ID when reporting a persistent failure. |
+## T3 Connect
 
-Authorization and other permanent 4xx rejections stop the startup link attempt immediately.
-After correcting them, restart the server. For the Linux background service, use
-`systemctl --user restart t3code.service`; for a foreground server, stop it and run `t3 serve` again.
-Keep the diagnostic message and trace ID when reporting a problem. Do not post authorization codes,
-pairing URLs, or the contents of the secrets directory.
+T3 Connect makes an environment available to your other devices without setting
+up router forwarding. In the desktop app on the host, open **Settings →
+Connections**, sign in, and enable **T3 Connect** for that environment.
 
-## Quick Pairing for a Running Server
-
-If a server is already running on this machine, mint a fresh pairing token and QR code without restarting anything:
+For a command-line host, run:
 
 ```bash
-npx t3 pair
+npx t3@latest connect
 ```
 
-`t3 pair` finds the running server (the shared `~/.t3` install, or the current worktree's dev server when run inside one), issues a one-time pairing token, and prints the pairing URL as a QR code you can scan from your phone.
-
-If the server is only bound to loopback, the printed URL is not reachable from another device. Pair over your tailnet instead:
-
-```bash
-npx t3 pair --tailscale
-```
-
-This publishes the server over Tailscale Serve HTTPS (configuring the mapping if needed — it persists until you run `tailscale serve --https=443 off`) and pairs through the `https://machine.tailnet.ts.net/` URL. Use `--tailscale-serve-port` for a different HTTPS port, `--ttl` to change the token lifetime, and `--base-dir` to target a specific data directory.
-
-If no server is running, `t3 pair` says so and points you at `npx t3 serve` or `npx t3 connect`.
-
-## Recommended Setup
-
-Use a trusted private network that meshes your devices together, such as a tailnet.
-
-That gives you:
-
-- a stable address to connect to
-- transport security at the network layer
-- less exposure than opening the server to the public internet
-
-## Enabling Network Access
+Follow the sign-in instructions. Setup offers a
+[background service](./background-service.md); if you decline it, start the
+server with `npx t3 serve`. Saving your sign-in alone does not make the machine
+reachable.
 
-There are three ways to reach your server from another device: expose the desktop app's backend,
-run a headless server from the CLI, or have the desktop app launch T3 Code over SSH.
+On your other device, sign in to the same T3 Connect account and choose the
+environment. Over SSH, the CLI prints a browser link and accepts the returned
+authorization code, so you do not need to forward an OAuth callback port.
 
-### Option 1: Desktop App
+## Pair over a LAN or private network
 
-If you are already running the desktop app and want to make it reachable from other devices:
+Use direct pairing when the other device can reach the host's network address.
 
-1. Open **Settings** → **Connections**.
-2. Under **This environment**, toggle **Network access** on. This will restart the app and run the backend on all network interfaces.
-3. The settings panel will show the default reachable endpoint, with a `+N` control when more endpoints are available. Expand it to inspect alternatives such as loopback, LAN, private-network, or HTTPS endpoints.
-4. Use **Create Link** to generate a pairing link you can share with another device.
+On a desktop host, open **Settings → Connections**, enable **Network access**,
+then create a pairing link using an address the other device can reach. Changing
+network access restarts the desktop app. You can turn it off in the same place.
 
-Pairing codes and share links are available only in the client that created them,
-while its Connections page remains open. After you leave the page or reload it,
-create a new link to share. Other clients can see the active link's name, scopes,
-and expiry, and can revoke it if they have access management permission.
-
-The default endpoint controls the QR code and primary copy action for pairing links. You can change it from the expanded endpoint list. The preference is stored by endpoint type, so choosing the local LAN endpoint survives normal IP address changes when you move between networks.
-
-After an app restart, the desktop app replaces its previous
-local credential. Old local desktop entries are removed from **Authorized clients**
-automatically. Paired phones, browsers, and remote desktop clients keep their access.
-
-When no user default is saved, the app uses the built-in LAN endpoint for pairing links when
-available. You can set another endpoint as the default from the expanded endpoint list.
-
-- HTTPS/WSS-compatible endpoints work from `https://app.t3.codes`, but are not made the default
-  automatically.
-- Non-loopback HTTP endpoints are useful for direct LAN pairing.
-- Loopback-only endpoints are not useful for another device unless that device is the same machine.
-
-If the copied link points directly at `http://192.168.x.y:3773`, open it from a client that can reach that LAN address. If it points at `https://app.t3.codes/pair?...`, the hosted web app will save the environment and connect directly to the backend URL in the link.
-
-In the mobile app's **Add Environment** form, a numeric IP address without a scheme uses HTTP. Include `https://` explicitly when the backend is served over HTTPS.
-
-### Tailscale Endpoints
-
-When the desktop app can detect Tailscale, it adds Tailnet endpoints to the reachable endpoint list.
-
-Depending on your Tailscale setup, this may include:
-
-- the machine's `100.x.y.z` Tailnet IP
-- a MagicDNS name
-- an HTTPS MagicDNS endpoint when Tailscale Serve is configured for this backend
-
-The Tailscale HTTPS endpoint uses the clean MagicDNS URL, such as
-`https://machine.tailnet.ts.net/`, and is off until you opt in. Turn on **Enable Tailscale HTTPS**
-on the **Tailscale HTTPS** row in **Settings** → **Connections**. The desktop app restarts the
-backend with the same server-side behavior as `t3 serve --tailscale-serve`, then the server asks
-Tailscale Serve to proxy HTTPS traffic to the local backend. Turn the same switch off to stop it.
-
-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.
-
-Run the server with `t3 serve`.
+For a command-line host, replace `<private-ip>` with the host's LAN or tailnet
+address:
 
 ```bash
-npx t3 serve --host "$(tailscale ip -4)"
+npx t3 serve --host <private-ip>
 ```
 
-`t3 serve` starts the server without opening a browser and prints:
-
-- a connection string
-- a pairing token
-- a pairing URL
-- a QR code for the pairing URL
-
-From there, connect from another device in either of these ways:
-
-- scan the QR code on your phone
-- in the desktop app, enter the full pairing URL
-- in the desktop app, enter the host and token separately
-- in the hosted web app, open a hosted pairing URL when the backend is reachable over HTTPS
-
-Use `t3 serve --help` for the full flag reference. It supports the same general startup options as the normal server command, including an optional `cwd` argument.
-
-For hosted web pairing over Tailscale HTTPS, opt in to Tailscale Serve:
+If a server is already running, generate a fresh link without restarting it:
 
 ```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
+npx t3 pair
 ```
 
-Once paired, add projects normally: open the Command Palette and choose **Add Project**, then pick
-the environment the project lives on. Every saved environment is offered, not only the local one.
+Scan the QR code on your phone or paste the pairing URL into **Add environment**
+in the receiving app. Connection settings are under **Settings → Connections**
+on web and desktop and **Settings → Environments** on mobile. A loopback address
+such as `127.0.0.1` reaches only the device opening the link.
 
-### Option 3: Desktop-Managed SSH Launch
+Pairing authorizes that device for future connections. Use a fresh one-time link
+for each new device; you do not need the original token to reconnect. Links
+created in Settings can only be copied from the client that created them while
+its Connections page stays open. If you leave or reload that page, create
+another link to share.
 
-Use this when you want the desktop app to start or reuse T3 Code on another machine over SSH.
+### Tailscale HTTPS
 
-1. Open **Settings** → **Connections**.
-2. Under **Remote Environments**, choose **Add environment**.
-3. Select the SSH launch flow.
-4. Enter the SSH target, such as `user@example.com`.
-5. Confirm the launch. The desktop app probes the host, starts or reuses a remote T3 server, opens a local port forward, and saves the environment.
+Join both devices to the same tailnet. In the desktop app, enable **Tailscale
+HTTPS** in **Settings → Connections**. Turn it off there to remove that route.
 
-After setup, the renderer connects to a local forwarded HTTP/WebSocket endpoint. The remote host still owns the actual T3 server, projects, files, git state, terminals, and provider sessions.
+To start a command-line server with Tailscale HTTPS:
 
-SSH launch is a desktop feature because it needs local process and SSH access. Once the environment is paired and saved, it uses the same environment list and connection model as direct LAN, Tailscale, HTTPS, or future tunnel-backed environments.
-
-#### SSH Launch Troubleshooting
-
-The desktop SSH launcher connects with a non-interactive `sh` session, writes a small launcher script under `~/.t3/ssh-launch/<host-key>/`, starts or reuses a remote T3 server, and forwards the remote loopback port back to your desktop.
-
-The remote host must have a compatible Node.js runtime. T3 Code uses the server package's `engines.node` requirement:
-
-```text
-^22.16 || ^23.11 || >=24.10
+```bash
+npx t3 serve --tailscale-serve
 ```
 
-During SSH launch, T3 Code first checks whether `node` is on `PATH`. If it is missing, the launcher
-looks in the usual install directories and tries to activate a version manager if it finds one
-(Volta, asdf, mise, fnm, nodenv, nvm). That covers most setups, but a version manager that only
-initializes from an interactive shell profile will not be picked up.
-
-If launch fails with `node: command not found`, a port-scan failure, or a message that the remote Node version does not satisfy the required range, SSH into the host and check the same non-interactive shell path T3 Code uses:
+For an already-running server:
 
 ```bash
-ssh user@example.com 'sh -lc "command -v node && node --version"'
+npx t3 pair --tailscale
 ```
 
-If that does not print a compatible Node version, configure your version manager for non-interactive shells or install a compatible Node binary in one of the searched locations. For example, with nvm you may need a default alias:
+The pairing link uses an address such as `https://machine.tailnet.ts.net/`.
+The mapping created by `pair --tailscale` persists across restarts. Remove its
+default-port mapping with:
 
 ```bash
-nvm alias default 24
+tailscale serve --https=443 off
 ```
 
-With mise, asdf, fnm, or nodenv, make sure the tool's shim directory is installed and resolves to a Node version satisfying the range above without an interactive shell.
+If that port is already in use, choose another with
+`--tailscale-serve-port`. See `npx t3 pair --help` for other pairing options.
 
-If reconnecting after an app update fails, retry the SSH launch once. The launcher now compares its generated runner script, stops stale launcher-managed remote servers, clears the SSH launch PID/port state, and starts a fresh remote server. You should not normally need to delete `~/.t3/ssh-launch` or kill `t3` processes manually.
+### Hosted web app
 
-## Antigravity Google sign-in
+[app.t3.codes](https://app.t3.codes) needs an HTTPS endpoint. It connects directly
+to your server; a hosted pairing link does not make an unreachable backend
+reachable or convert HTTP to HTTPS.
 
-Antigravity runs and saves its Google credentials on the selected environment. You can install
-it and sign in from a remote web or desktop client without an SSH login.
+For a plain HTTP LAN endpoint, use the direct pairing URL in a browser that can
+open it, or pair from the desktop app. On mobile, an IP address entered without a
+scheme uses HTTP, so include `https://` when your server uses HTTPS.
 
-Start in **Settings** > **Providers**, select the environment, then choose **Antigravity**.
-Provider setup is not available in the mobile app.
+## Desktop-managed SSH
 
-After Google sign-in, a remote browser usually reaches a `127.0.0.1` page that cannot load.
-Copy that full address into the return URL field in the same T3 Code client and choose
-**Continue**. Keep the address unchanged. Do not paste the return URL into a thread or bug report.
+In the desktop app, open **Settings → Connections → Add environment**, choose
+**SSH**, and enter a host or SSH alias such as `user@example.com`. T3 Code starts
+or reuses a server there and opens the port forward for you. Projects, provider
+credentials, and agent work stay on the remote machine.
 
-See [Antigravity setup](./providers-antigravity.md) for installation, expiry, and account changes.
+The remote host needs a compatible [Node.js installation](./install.md#requirements)
+and [provider setup](./install.md#providers). If launch cannot find Node or reports
+an incompatible version, check it through a non-interactive SSH session:
 
-## Updating a Remote Server
-
-When the T3 Code web or desktop app and a remote server use different versions, a warning appears in
-the conversation and in **Settings** → **Connections**. Follow the action shown there: T3 Code may
-be able to update and reconnect the server for you, or it may ask you to update the desktop app or
-run a copied command on the server machine.
-
-If T3 Connect cannot connect, check the date and time on both devices, then try again.
-
-Finish active work before updating because the server restarts briefly. For step-by-step guidance,
-see [Keeping T3 Code in Sync](./updating.md).
-
-On a Linux host, you can keep the server running after logout and manage it independently of the
-connection method. See [Running T3 Code in the Background](./background-service.md).
-
-## How Pairing Works
-
-The remote device does not need a long-lived secret up front.
-
-Instead:
-
-1. `t3 serve` issues a one-time owner pairing token.
-2. The remote device exchanges that token with the server.
-3. The server creates an authenticated session for that device.
-
-After pairing, future access is session-based. You do not need to keep reusing the original token unless you are pairing a new device.
-
-## Hosted Web App Pairing
-
-The hosted web app at `https://app.t3.codes` can save a remote backend in browser local storage from a URL like:
-
-```text
-https://app.t3.codes/pair?host=https://backend.example.com:3773#token=PAIRCODE
+```bash
+ssh user@example.com 'sh -lc "command -v node && node --version"'
 ```
 
-Use hosted pairing when the backend is reachable from the browser over HTTPS/WSS. This includes a backend behind a trusted HTTPS tunnel or another HTTPS endpoint you operate.
+Configure your version manager for non-interactive shells if this differs from
+your normal terminal. With nvm, setting a compatible default, such as
+`nvm alias default 24`, can resolve the problem.
 
-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.
+If SSH reconnecting fails after an app update, retry the launch once. Removing
+the connection stops a server that T3 Code launched; a server that was already
+running is left alone.
 
-Hosted pairing does not proxy traffic through T3 Code. The browser still connects directly to the backend URL in the pairing link.
+For Antigravity's Google callback on a remote host, see
+[remote sign-in](./providers-antigravity.md#sign-in-from-a-remote-device).
 
-## Managing Access Later
+## Manage or revoke access
 
-Use `t3 auth` to manage access after the initial pairing flow.
+On the host, **Settings → Connections** lets authorized administrators create
+pairing links and revoke client sessions. Revoking an unused link prevents new
+pairings; revoke a device's session to remove its existing access. Command-line
+management is available through `npx t3 auth --help`.
 
-Typical uses:
+To remove an environment from T3 Connect, open your account menu's **T3 Connect**
+page, or **Settings → T3 Connect** on mobile, and choose **Deregister**. This
+revokes its cloud access and frees its host space even when the environment is
+offline or has been wiped.
 
-- issue additional pairing credentials
-- inspect active sessions
-- revoke old pairing links or sessions
+On a command-line host, `t3 connect unlink` disables exposure while retaining
+your login; `t3 connect logout` also clears that login. Background-service
+[removal](./background-service.md#manage-the-service) is separate.
 
-Use `t3 auth --help` and the nested subcommand help pages for the full reference.
+Treat pairing URLs and authorization codes as passwords. Do not include them in
+screenshots, logs, or bug reports.
 
-### Deregister a T3 Connect Environment
-
-Open your account menu and choose **T3 Connect** to see every environment registered to your
-account. On mobile, open **Settings** → **T3 Connect**. Choose **Deregister** to revoke an
-environment's T3 Connect access, remove any managed tunnel, and free its host space.
-
-Deregistration is an account action and does not need a connection to the environment, so it also
-works for a server that was wiped or is no longer reachable. Device-local connect and disconnect
-controls remain in **Settings** → **Connections** on web and desktop or **Settings** →
-**Environments** on mobile.
-
-## Security Notes
+## T3 Connect troubleshooting
 
-- Treat pairing URLs and pairing tokens like passwords.
-- Prefer binding `--host` to a trusted private address, such as a Tailnet IP, instead of exposing the server broadly.
-- Anyone with a valid pairing credential can create a session until that credential expires or is revoked.
-- Hosted pairing links keep the credential in the URL hash so it is not sent to the hosted app server, but it can still be exposed through browser history, screenshots, logs, or copy/paste.
-- Use `t3 auth` to revoke credentials or sessions you no longer trust.
+Run `t3 connect status` on the host to inspect saved authorization and link
+configuration. It is not a live reachability check. If the environment appears
+offline, run `t3 service status` and read the displayed log. If it disappears
+when SSH closes, see [background-service troubleshooting](./background-service.md#troubleshooting).
+
+| Error                                                     | Recovery                                                                                                                                    |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `environment_link_limit_exceeded` or managed tunnel limit | Deregister an unused environment, then restart T3 Code on the host.                                                                         |
+| `auth_invalid` or `invalid_bearer`                        | Run `t3 connect login`. If credentials were revoked, run `t3 connect logout`, then `t3 connect` again. Restart the server after signing in. |
+| Expired or invalid link proof                             | Check the host's date and time, update T3 Code, then restart it.                                                                            |
+| HTTP 403 without a recognized error                       | Check relay access, proxies, and firewall rules. Keep any Cloudflare Ray ID for a bug report.                                               |
+| HTTP 408, 429, or 5xx                                     | Check network and relay availability. Startup retries temporary failures for up to ten minutes.                                             |
+
+After fixing a permanent rejection, restart the host's server. On Linux, use
+`systemctl --user restart t3code.service` for the background service. For a
+foreground server, stop it and run `t3 serve` again with your usual options.
+Include the diagnostic message and trace ID when reporting a persistent failure.
+
+For a connection that still fails after linking, check the date and time on both
+devices. For server version warnings, follow [Updating T3 Code](./updating.md).
diff --git a/docs/user/source-control.md b/docs/user/source-control.md
index 71f6548dd6b9..2d7ed8badbec 100644
--- a/docs/user/source-control.md
+++ b/docs/user/source-control.md
@@ -1,181 +1,93 @@
-# Source Control Integrations
-
-T3 Code connects to your Git hosting provider so you can create pull requests, review code, and manage repositories without leaving the app.
-
-## Supported Providers
-
-T3 Code works with the platforms your team already uses:
-
-- **GitHub** – Pull requests, repository creation, and clone integration
-- **GitLab** – Merge requests, repository publishing, and hosted clones
-- **Bitbucket** – Pull request workflows (via API token authentication)
-- **Azure DevOps** – Pull request support for Microsoft-hosted repositories
-
-## What You Can Do
-
-### Start Projects from Anywhere
-
-**Clone repositories directly**
-
-- Open the Command Palette (`Cmd/Ctrl + K`) → **Add Project**
-- Choose **GitHub repository**, **GitLab repository**, **Bitbucket repository**, **Azure DevOps repository**, or paste any **Git URL**
-- Enter the repository path (`owner/repo`, `group/project`, `workspace/repository`, or `project/repository`) or a full Git URL, pick a destination, and start coding
-
-**Publish local projects to the cloud**
-
-- Have a local Git repository without a remote?
-- Use the **Publish Repository** action to create a new hosted repository (GitHub, GitLab, Bitbucket, or Azure DevOps), add it as your origin remote, and push, in one flow
-- If the local repository has no commits yet, publishing creates the remote and wires it up but does not push. Make a commit, then push normally.
-
-### Manage Code Reviews Without Context Switching
-
-**Create pull requests while you work**
-
-- Push a branch and create a pull request from the Git actions controls in the toolbar
-- T3 Code can suggest titles and descriptions based on your commits
-- With **Repository conventions** selected, generated source control text follows the project's
-  `AGENTS.md` along with recent commit subjects. Claude writers also follow `CLAUDE.md`
-- Supports GitHub Pull Requests, GitLab Merge Requests, Bitbucket Pull Requests, and Azure DevOps Pull Requests
-
-**Stay on top of open reviews**
-
-- See if your current branch already has an open PR/MR
-- When an agent finishes a turn on your thread's branch, T3 Code checks for a newly opened
-  PR/MR if background activity is enabled for that repository. Known reviews keep their normal
-  refresh schedule.
-- Open several reviews from the **Pull requests** page as tabs in the right panel
-- Your authored reviews stay at the top and use the selected sort within their group. By default,
-  see passing and approved reviews first, passing reviews awaiting approval next, and conflicting
-  reviews last. Smaller changes come first within each readiness group, and finished reviews follow
-  open work when all states are visible.
-- Filter the list by author or labels, rank authors by merges in the loaded results, see label and
-  change-size context on each row, and sort the results currently shown by readiness, update time,
-  creation time, or change size. Your filters, search, scope, and sort are restored when you return.
-- Merge now, or on GitHub, GitLab, and Azure DevOps, leave an auto-merge instruction with a chosen
-  strategy while checks are outstanding; see the completed state in the same control after the
-  pull request merges
-- On GitHub, approve fork workflows that are waiting to run and open a revert pull request for a
-  merged change
-- Timeline line counts stay hidden on merge commits, where GitHub's totals include upstream changes
-  brought in from the base branch
-- While working in a thread, open linked reviews in the same compact right-panel tabs without
-  leaving the conversation
-- Show a file tree next to a review's **Code** tab, or a thread's **Diff** panel, to browse the
-  changed files as folders and jump straight to any of them. The toolbar toggle remembers your
-  choice.
-- Enable **Settings → General → Proactive panels** to open a newly linked review automatically and
-  switch to the completed turn's diff when agent work changes files. An open review stays in front
-- Open the review directly in your browser with one click
-- If T3 Code cannot load a GitHub pull request, including when GitHub rate limits requests, use
-  **Open on GitHub** in the error view
-- Command-click (Control-click on Windows and Linux) a pull request number in the sidebar to open it in your browser instead of in T3 Code
-- Check out a teammate's branch to review code locally
-
-**Fix what you wrote, in place**
-
-- Comment while closing an open pull request or reopening a closed one when the host offers that
-  action
-- Rewrite a pull request's title and description from the review itself, in Markdown, with a
-  preview before you save
-- Rewrite your own comments the same way, wherever they are shown
-- Works on GitHub, GitLab, and Bitbucket. Azure DevOps takes a new title and description; its
-  comments stay read-only here, as they already were
-- On GitHub, put a label on a pull request or take one off from the **Labels** row of the review.
-  Changing labels needs triage access or better on the repository
-
-### Know Your Setup at a Glance
-
-The **Source Control settings** page shows you exactly what's connected:
-
-- ✅ Which providers are authenticated and ready
-- ⚠️ What's missing and how to fix it
-- 👤 Which account is signed in (when available)
-
-Run a quick **Rescan** after setting up a new machine or changing credentials.
-
-## Getting Started
-
-### For GitHub (Recommended for most users)
-
-1. Install the GitHub CLI (version 2.81.0 or newer) on the machine running T3 Code:
-   ```bash
-   brew install gh
-   ```
-2. Sign in:
-   ```bash
-   gh auth login
-   ```
-3. Open **Settings → Source Control** in T3 Code and verify GitHub shows as authenticated
-
-You can now clone, publish, and create pull requests.
-
-### For GitLab
-
-1. Install the GitLab CLI:
-   ```bash
-   brew install glab
-   ```
-2. Authenticate:
-   ```bash
-   glab auth login
-   ```
-3. Check **Settings → Source Control** to confirm the connection
-
-### For Bitbucket
-
-Bitbucket uses tokens instead of a CLI tool. Two options, both set as environment variables on the
-machine running T3 Code.
-
-Recommended, a Bitbucket access token:
+# Source control
+
+T3 Code integrates with GitHub, GitLab, Bitbucket, and Azure DevOps to clone and publish
+repositories, create pull requests, and review changes.
+
+## Connect an account
+
+Install Git and configure authentication on the machine running your T3 Code server. For a remote
+environment, do this on the remote machine. After signing in, open **Settings → Source Control**
+and choose **Rescan**.
+
+### GitHub
+
+Install [GitHub CLI](https://cli.github.com/) 2.81.0 or newer, then sign in:
+
+```bash
+gh auth login
+```
+
+### GitLab
+
+Install [GitLab CLI](https://gitlab.com/gitlab-org/cli), then sign in:
+
+```bash
+glab auth login
+```
+
+### Bitbucket
+
+Set an access token in the server's environment:
 
 ```bash
 export T3CODE_BITBUCKET_ACCESS_TOKEN="your-access-token"
 ```
 
-Or an Atlassian account email plus API token, with read/write access to pull requests and
-repositories, plus read access to your user account (`read:user:bitbucket`, used to verify the
-connection):
+Or use an Atlassian account email and API token with read/write access to repositories and pull
+requests, plus user read access (`read:user:bitbucket`):
 
 ```bash
 export T3CODE_BITBUCKET_EMAIL="you@example.com"
 export T3CODE_BITBUCKET_API_TOKEN="your-token"
 ```
 
-If both are set, the access token wins. Restart T3 Code and verify the connection in **Source
-Control settings**.
+The access token takes precedence if both are configured. Restart the server after changing these
+variables.
+
+### Azure DevOps
+
+Install [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/), add the DevOps extension, and sign in:
+
+```bash
+az extension add --name azure-devops
+az login
+```
+
+## Clone or publish a project
+
+Use **Add Project** in the command palette (`Cmd/Ctrl+K`) to clone a repository. Choose a hosting
+provider or paste a Git URL, then choose where to save it.
 
-### For Azure DevOps
+For a local Git repository without a remote, **Publish Repository** creates a hosted repository,
+adds it as `origin`, and pushes your commits. If there are no commits yet, it creates the remote;
+make your first commit before pushing.
 
-1. Install Azure CLI:
-   ```bash
-   brew install azure-cli
-   ```
-2. Add the DevOps extension:
-   ```bash
-   az extension add --name azure-devops
-   ```
-3. Sign in:
-   ```bash
-   az login
-   ```
+## Create a pull request
 
----
+Use a thread's Git actions to commit, push, and create a pull request. T3 Code can generate commit
+messages, review titles, and descriptions from your changes.
 
-## Requirements & Troubleshooting
+Choose the writing style and model in **Settings → Source Control**. **Repository conventions**
+uses the project's instructions and recent commit subjects.
 
-**Git is required** – T3 Code uses Git for all local operations. Ensure `git` is installed on your server.
+## Review and merge
 
-**Server-side setup** – Authentication happens on the machine running T3 Code (the server), not your local browser. If you're using a hosted or team instance, your administrator may have already configured providers.
+Open **Pull requests** to review changes and comments, request reviewers, check out a branch,
+or merge. You can edit review titles and descriptions and your own comments where the host allows it.
+GitLab calls these merge requests.
 
-**Common issues:**
+GitHub, GitLab, and Azure DevOps support auto-merge while checks are outstanding. GitHub also
+supports approving waiting fork workflows and opening a revert pull request for a merged change.
 
-- **Provider shows "Not authenticated"** – Run the login command for that provider (e.g., `gh auth login`) in a terminal on the server, then rescan in Settings
-- **GitHub says it could not verify sign-in status** – T3 Code needs GitHub CLI 2.81.0 or newer to check sign-in status. Update `gh` (e.g., `brew upgrade gh`), then rescan
-- **Bitbucket not connecting** – Double-check your environment variables are set in the correct shell profile and the server was restarted
-- **Can't push to a remote** – Verify your Git remote URL matches the provider you've authenticated with (SSH vs HTTPS remotes may need different credentials)
+For Azure DevOps, use the host website to view diffs or change comments. Bitbucket does not support
+reopening a declined pull request.
 
-**Need more help?** Check your provider's CLI documentation:
+## Troubleshooting
 
-- [GitHub CLI](https://cli.github.com/)
-- [GitLab CLI](https://gitlab.com/gitlab-org/cli)
-- [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/)
+- **Not authenticated:** run the provider's login command on the server, then rescan. For Bitbucket,
+  confirm the running server received the environment variables.
+- **GitHub sign-in cannot be verified:** update GitHub CLI to at least 2.81.0.
+- **Push fails despite a connected account:** check the Git remote's credentials. SSH and HTTPS
+  remotes can require separate setup from the hosting provider's API access.
+- **A review cannot load:** open it on the host website while resolving connectivity, permissions,
+  or rate limits.
diff --git a/docs/user/telemetry.md b/docs/user/telemetry.md
index c8726202bf35..5fd4f91c9327 100644
--- a/docs/user/telemetry.md
+++ b/docs/user/telemetry.md
@@ -1,15 +1,11 @@
-# Anonymous usage data
+# Product usage data
 
-The T3 server sends anonymous product events to PostHog. These events include
-the provider, model, reasoning effort, permission mode, turn result, duration,
-and normalized main-agent token totals when the provider reports them.
+The T3 Code server sends product usage events to PostHog, associated with a hashed account or
+installation identifier. Events include the provider, model, reasoning effort, permission mode,
+turn result, duration, and main-agent token totals when available.
 
-T3 Code does not send prompts, responses, file contents, raw provider events,
-thread IDs, turn IDs, provider instance IDs, authentication tokens, or child
-agent output. Token totals can be complete, partial, or unavailable. Child
-agent token use is not included.
+Events do not include prompts, responses, file contents, authentication tokens, conversation IDs,
+raw provider events, or child-agent output. Child-agent token use is excluded from the totals.
 
-Set `T3CODE_TELEMETRY_ENABLED=false` before you start the T3 server to stop
-product events from being recorded or sent. The server still derives an
-anonymous identifier during startup and can create its local fallback
-identifier file.
+To disable collection, set `T3CODE_TELEMETRY_ENABLED=false` in the server's environment before
+starting it. This stops product events from being recorded or sent.
diff --git a/docs/user/thread-sidebar.md b/docs/user/thread-sidebar.md
index 1932e9ce2a45..e6c89c0343e7 100644
--- a/docs/user/thread-sidebar.md
+++ b/docs/user/thread-sidebar.md
@@ -1,88 +1,73 @@
-# Organizing threads
-
-Pin a thread from its context menu to keep it in the pinned section above your active work.
-`mod+shift+p` pins or unpins the thread you have open. Pinned threads are shown independently of
-their project, including when you connect to more than one environment.
-
-To require confirmation before unpinning, enable **Settings → General → Unpin confirmation**. The
-confirmation applies to the sidebar controls, thread menus, and the `mod+shift+p` shortcut.
-
-Pinned threads still move to **Settled** when they become inactive. They also move when their pull
-request merges if **Auto-settle merged threads** is enabled.
-
-Each server stores its own copy of the automatic settlement settings and checks them even when no
-web, desktop, or mobile client is connected. By default, it settles threads after three days without
-activity and when their pull request merges. An eligible idle thread also settles when its pull
-request closes. An open pull request does not block inactivity settlement. Active work, pending
-input, and live background work keep the thread active. T3 Code settles from a closed or merged
-pull request only when its timestamp is not older than the user's latest activity. If that timestamp
-is not available, the inactivity rule still applies. A manual un-settle also keeps the thread active.
-
-**Settled** lists threads by when their work finished, newest first. A thread you settle yourself
-sorts by the moment you settled it. A thread that settled on its own sorts by its last message or
-turn, not by when the server noticed it was inactive.
-
-Change these rules in **Settings > General**. The change is written to every connected environment
-whose server supports shared settings. An environment that is offline or needs a server update
-keeps its old value and does not appear in mismatch warnings. When a connected environment whose
-server supports shared settings holds a different value, **Settings > General** shows a warning
-that names it. Choose **Apply to all** to write your current values to the environments named in
-the warning. The same applies to the new-thread workspace mode and the source control writing
-style.
-
-A settings change affects future settlement and does not reopen a settled thread. Settings saved
-by older clients on one device no longer control this behavior.
-
-When you un-settle a thread, it returns to the top of the active list so you can find it right
-away. Its timestamps do not change. Other threads keep their positions.
-
-A thread whose composer holds unsent text or attachments shows an amber tint and a pen icon in the
-sidebar, the same marks a new-thread draft uses. On web and desktop, hover the row and choose the
-**X** to discard that draft without opening the thread.
-
-Right-click a pull request link in a thread and choose **Link to thread** to show that pull request
-in the sidebar. The thread settles when the linked pull request merges if **Auto-settle merged
-threads** is enabled. Right-click the same link and choose **Unlink from thread** to remove it.
-
-On web and desktop, drag a pinned thread to change its position. On mobile, open the thread's menu
-and choose **Move up** or **Move down**. The order is stored by the server and appears on your
-other connected devices.
-
-If reordering is unavailable for one environment, update the T3 Code server running in that
-environment. Older servers can still pin and unpin threads, but do not understand synced ordering;
-their pinned threads keep the default newest-first order below the ones you have arranged.
-
-## Panel motion
-
-The main sidebar, right panel, and terminal drawer open and close immediately by default. Under
-**Settings → Appearance → Motion**, move the **Panel animations** slider above 0 ms to add motion.
-The duration can be set up to 400 ms. Clicking the preview replays all three panel transitions; at
-0 ms, it snaps between the same open and closed states.
-
-## Environment icons
-
-When you are connected to more than one environment, every thread that lives somewhere other than
-the machine you are on wears a small icon for that machine at the end of its row: a server, a cloud
-VM, a desktop, a laptop, a Mac mini, or a Mac Studio. In the hosted web app and the mobile app,
-where every environment is remote, each row wears its machine so you can tell them apart at a
-glance. The same icon appears wherever an environment is named: the thread tooltip, the command
-palette, the "Run on" picker, the pull request server filter, the provider settings device tabs,
-and the environment lists under **Settings → Connections**. On mobile it appears in the thread
-lists, the archive, the new-task environment picker, and the Environments and storage settings.
-
-Servers pick the icon themselves from the hardware they run on. A Mac reports its model, a Linux
-machine reports its chassis type and whether it is a virtual machine, and anything without a usable
-signal shows a generic server. To override it, open **Settings → Connections** and choose an icon
-for that environment; **Automatic** goes back to what the server detected. The choice is stored on
-that server, so every device that connects to it sees the same icon.
-
-## Environment artwork
-
-Dev and Nightly environments can identify themselves with artwork at the top of the sidebar and in
-the send button. Choose **Artwork**, **Version pill**, or **None** in Settings under environment
-identification. Artwork is recolored to match each built-in theme. Custom themes use the **Version
-pill** fallback because their colors are not controlled by T3 Code.
-
-To generate a fresh title from the conversation, open a thread's context menu and choose
-**Regenerate title**. While T3 Code is generating it, the action reads **Regenerating…** and cannot
-be selected again. The option is hidden when the connected environment needs a server update.
+# Working with threads
+
+Use a new thread for a separate task. Choose **New worktree** when its code changes
+need a separate branch and working directory.
+
+## Start a thread
+
+On web and desktop, a new thread keeps the current project and carries your model
+and mode selections, unless the destination project has its own model default.
+Its branch and workspace mode come from your configured defaults. To continue in
+an existing worktree, use **New thread in this worktree** from the branch toolbar.
+
+When you change a new thread's project, T3 Code stays in the current environment
+if that project exists there. Otherwise it selects an environment that has it.
+
+### Start in the background
+
+In a desktop browser or the desktop app, press `Cmd+Enter` on macOS or `Ctrl+Enter`
+on Windows and Linux to start a new thread and immediately open another draft. The
+next draft keeps the workspace mode and base branch you selected. With **New
+worktree**, each background submission creates its own worktree.
+
+## Pin and reorder threads
+
+Pin a thread from its menu to keep it above your active work. Drag pinned threads
+to reorder them on web and desktop, or use **Move up** and **Move down** on mobile.
+The order syncs across devices.
+
+Pinning does not prevent automatic settlement. Settling a thread removes its pin.
+
+## Settle finished work
+
+Choose **Settle thread** from its menu to move finished work out of the active list
+without deleting the conversation. **Un-settle thread** restores it to active work
+and prevents automatic settlement until new activity resumes the usual rules.
+
+By default, environments settle inactive threads after three days and settle
+threads whose pull request merged. A closed pull request can also settle an idle
+thread. Work in progress, pending questions or approvals, and live background work
+prevent automatic settlement. An open pull request does not prevent inactivity
+settlement, but an old closed or merged pull request does not settle work you
+resumed after it closed.
+
+Change these rules in **Settings → General**. They continue to run when your apps
+are closed. Changes apply to connected environments that support shared settings;
+offline environments and older servers keep their previous values. If connected
+environments disagree, **Apply to all** copies your current settings to those named
+in the warning. Changing a rule does not reopen already settled threads.
+
+## Link a pull request
+
+On web and desktop, right-click a pull request link in a thread and choose
+**Link to thread**. Use **Unlink from thread** on the same link to remove it.
+The linked pull request participates in automatic settlement.
+
+## Find and reference work
+
+On web and desktop, open the command palette with `Cmd/Ctrl+K` to search threads
+across connected environments. Message search starts after two characters and
+includes your messages and final agent responses.
+
+Use **Settings → Keybindings** to find or customize shortcuts for searching files
+and copying a thread reference. A copied reference uses the thread's pull request
+link when available, otherwise its thread ID. See [keybindings](./keybindings.md)
+for custom configuration.
+
+## Inspect agent work
+
+On web and desktop, use **Agents** to follow work delegated to subagents.
+
+Expand a tool call in the conversation to see its full command and output.
+Summaries shorten shell wrappers and can still describe the latest call after it
+finishes; the call's own result shows its status.
diff --git a/docs/user/tool-activity.md b/docs/user/tool-activity.md
deleted file mode 100644
index 55477f5107dc..000000000000
--- a/docs/user/tool-activity.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# Tool activity
-
-Open a tool-group summary in the conversation to see its individual calls. Each row has an icon;
-select a row to inspect its details. Select the group summary again to collapse it.
-
-Long groups scroll inside a bounded area without expanding the whole conversation. Faded edges
-indicate more calls above or below. Short groups use only the space they need.
-Collapsing and reopening a group preserves your reading position and any open call details.
-
-Recognized T3 tools use descriptive labels in both the running summary and individual rows.
-The latest live activity stays in the present tense while the turn continues, such as
-"Running vp" or "Clicking in the preview browser", even after that call has completed.
-Expanded rows follow the call's own state, such as "Clicked" after success.
-When a call has not reported a state yet, the label stays in the present tense.
-Failed, declined, and stopped calls say what happened without implying success.
-Failed calls keep their tool icon with a muted red tint, so a failed command still
-looks like a command. App logos and other multicolor icons keep their artwork and
-show a small muted red failure mark beside the row. Expand the call to inspect its
-output. Runtime errors and warnings keep their stronger styling.
-Preview browser actions use a globe icon. Other T3 tools keep the T3 mark.
-Group summaries count browser actions separately, such as "Used browser 18 times" or
-"Ran 4 commands and used browser 15 times". Browser-only groups also use a globe icon.
-
-Command summaries show the program inside a shell wrapper, such as "Running vp" for
-`/bin/zsh -lc 'vp test run'`. Expanded rows keep the full command.
diff --git a/docs/user/updating.md b/docs/user/updating.md
index 18fc82ad202d..8ccefb4e5157 100644
--- a/docs/user/updating.md
+++ b/docs/user/updating.md
@@ -1,95 +1,58 @@
-# Keeping T3 Code in Sync
+# Updating T3 Code
 
-The T3 Code web or desktop app and the server it connects to work best when they use the same
-version. If they do not match, T3 Code shows a warning with the right update option for that server.
+The app you use and the server running your agents can be on different machines.
+When a server is behind your web or desktop app, an update notice appears in the
+conversation and **Settings → Connections**. Update the machine named in that
+notice.
 
-## Where to Find the Update
+## Before you update
 
-You may see the warning in either of these places:
+Server updates restart the connection and can interrupt active agents and
+terminal commands. Saved threads, settings, and project files remain.
 
-- above the message box in the current conversation
-- **Settings** → **Connections**, beside the affected connection
+**Settings → General → Continue threads after server updates** is off by default.
+Enable it to resume supported active threads once the replacement server is
+ready. Terminal commands may still be interrupted.
 
-Dismissing the conversation warning only hides that reminder for those two versions. It does not
-update the server, and the version difference remains visible in Connections.
+## Update a connected server
 
-## Before You Update
+The offered action depends on how the server runs:
 
-Updating restarts the server, so the connection will disappear briefly. **Settings** → **General**
-has a **Continue threads after server updates** preference. It is off by default. When enabled, the
-update buttons automatically resume supported provider threads after the replacement server is
-ready. Providers with native promptless continuation use it; other providers receive a short
-instruction to continue where they left off. Terminal commands and other running work may still be
-interrupted during the update.
+| Action                     | What to do                                                                                                                                                                                      |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Update server**          | Keep the client open while it installs and reconnects. Supported background services update remotely. For a desktop-hosted server, this also closes and relaunches the desktop app on the host. |
+| **Update the desktop app** | Update the desktop app on the machine running the server, then reopen it if needed.                                                                                                             |
+| **Copy update command**    | Stop the command-line server on its host and relaunch with the copied command, keeping your usual startup options.                                                                              |
 
-The update does not remove saved threads, settings, or project files.
-
-## Choose the Action You See
-
-| Action                     | What to do                                                                                                                                                                                                                                                                                                                                                                    |
-| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Update server**          | Available for the T3 Code Linux background service and for servers run by a current T3 Code desktop app. Select the button and leave T3 Code open while it downloads, installs, restarts, and reconnects. For desktop-app servers this closes and relaunches the desktop app on that machine. If installation fails, the desktop app stays open and reconnects to its server. |
-| **Update the desktop app** | Shown for desktop apps that predate remote updates. Open the T3 Code desktop app on the machine that runs the server and install the app update there. Reopen it if needed.                                                                                                                                                                                                   |
-| **Copy update command**    | Copy the command, open a terminal on the server machine, stop the current T3 Code server, and relaunch it with the copied command and any startup options you normally use.                                                                                                                                                                                                   |
-
-The available action depends on how that server was started. T3 Code does not update connected
-servers silently in the background.
-
-An older background-service launcher may ask you to run the exact
-`npx t3@<version> service update` command on the server machine. That one local update installs the
-rollback support needed for later remote updates, including versions that change the database.
-
-After selecting **Update**, the notice becomes a live status line: **Downloading…** while the new
-version is fetched and verified, then **Restarting…** while the server restarts into it. The same
-status appears in the conversation and in Connections, so navigating between them does not lose the
-update. A failure remains visible with its error and an option to retry.
-
-**Copy update command** gives you `npx t3@<client-version>`, which relaunches the server directly
-at the matching version. Add whatever startup options you normally use.
-
-If the server instead runs as the T3 Code background service, update the service on the host and
-pin the same version:
+For a background service, run the matching version's CLI on the host:
 
 ```sh
 npx t3@<client-version> service update
 ```
 
-`service update` installs the version of the CLI that invoked it, so `npx t3@latest service update`
-only resolves the skew when your client happens to be on the latest release. The exact version from
-the warning always works.
-
-See [Running T3 Code in the Background](./background-service.md) for install, status, and removal
-commands.
-
-## Nightly desktop release notes
+Replace `<client-version>` with the version shown in the notice. Using
+`@latest` only resolves the mismatch if your client is on that release. An older
+service launcher may require this local update before it supports remote updates
+and rollback.
 
-The desktop app shows a compact release-notes preview when a nightly update is available. Changes
-appear newest first within each release. Each release links to its exact page on GitHub, even when
-all changes fit in the preview.
+For a foreground server, the copied command is `npx t3@<client-version>`. Add
+`serve` if you normally run without a browser, and preserve options such as
+`--host` or `--tailscale-serve`. See
+[background services](./background-service.md) for service management.
 
-The preview shows up to eight changes from each of six releases. When it leaves out changes or older
-releases, it shows the exact number and links to the rest. Contributor credits do not count as
-changes.
+## If an update fails
 
-## After the Update
-
-Keep the web or desktop app open while the server restarts. The update completes only after the
-service launcher reports that exact update committed and the replacement server is ready to accept
-commands. A rollback is reported immediately instead of waiting for a generic reconnect timeout.
-
-If a step fails:
+Keep the client open until it reconnects or reports a failure. A failed service
+update can roll back to the previous version. If the update still fails:
 
 1. Retry the offered action once.
-2. Make sure you updated the machine named in the warning, not only the device you are using.
-3. For a command-line server, relaunch it with `npx t3@<client-version>`, replacing
-   `<client-version>` with the client version shown in the warning.
-
-## The Mobile App
+2. Check that you updated the server's machine, not only the device you are using.
+3. For a command-line server, stop it and relaunch the exact version shown in the notice.
 
-The mobile app keeps itself current on its own. When it finds a new version, it downloads it in the
-background and installs it automatically the next time you leave the app. Unsent drafts and queued
-messages are saved before the restart. Only if the app stays open long enough that the update never
-gets that chance does it ask whether to install right away; choosing **Later** is safe and keeps the
-automatic install armed.
+## Mobile updates
 
-For remote connection setup and access troubleshooting, see [Remote Access](./remote-access.md).
+Install App Store or Google Play releases as usual. The mobile app can also
+download updates in the background and apply them when you next leave the app.
+It saves drafts and queued messages before restarting. If you keep the app open
+for a long time, it may ask to install immediately; choosing **Later** leaves the
+update queued for the next suitable moment.
diff --git a/docs/user/usage.md b/docs/user/usage.md
index fceedc3c2560..8523ab810991 100644
--- a/docs/user/usage.md
+++ b/docs/user/usage.md
@@ -1,35 +1,31 @@
-# Review usage
-
-The Usage page combines Codex, Claude Code, and Grok Build activity from your connected
-environments. It reads the providers' local session history and shows API-equivalent token cost,
-processed tokens, cache savings, provider shares, and model breakdowns. Subscription billing is
-separate from the raw token cost shown here.
-
-Grok Build totals come from persisted session updates. Interactive turns that never wrote a
-completed-turn record will not appear.
-
-The **Limits** view shows how much of each subscription window you have used on Codex and Claude
-Code, per connected environment: the session and weekly windows, plus a per-model weekly window
-such as Fable when your plan has one. Each window is a bar from the moment it opened to its reset,
-filled by the share of quota spent; a thin line marks how far into the window you are, which is
-also where even spending would have put the fill, and the icon beside the label says whether you
-are ahead of, on, or under that pace. Hover a bar for the exact reset time. Limits refresh on the
-provider health-check interval and update live while a turn runs. API-key accounts have no
-subscription windows and say so; that includes a Claude Code that reaches Anthropic through a proxy
-via `ANTHROPIC_AUTH_TOKEN`, since the CLI then treats itself as an API-key client.
-
-If you pool accounts behind a CLIProxyAPI hub, open **Settings → Providers → Usage providers**
-and choose **Add hub**. Select the device that should connect to the hub; its accounts appear on
-the Limits view. Remove hubs from the same settings section. Each limits row shows its provider
-and instance name, or a small _CLI Proxy_ label for
-hub accounts. When a connected provider reports limits for the same provider and email, its row
-replaces the hub copy, keeping details such as banked reset credits. The hub copy remains visible
-if the connected provider cannot report limits. Enter the hub's URL and management key; the key
-is stored on the server and never sent back to a client. Emails are blurred until clicked, as in
-provider settings.
-
-Use **Past 24h** for an hourly chart covering the exact rolling 24-hour period. The **7 days**,
-**30 days**, and **90 days** ranges use daily resolution. Cost and token toggles update both the
-headline and chart. Refreshing rescans every connected environment and refetches model pricing on
-each of them, so a newly released model that showed $0.00 gets a price without waiting for the daily
-pricing update.
+# Usage and limits
+
+## Understand your usage
+
+**Usage** combines Codex, Claude Code, and Grok Build session history from your connected
+environments. It shows token use, cache savings, model breakdowns, and estimated API-equivalent
+cost. These estimates are not your subscription bill.
+
+Totals depend on the history available on each server. Grok turns without a saved completed-turn
+record are missing from the totals.
+
+If recent work is missing or a new model shows no cost, refresh to rescan session history and
+update model pricing.
+
+## Track subscription limits
+
+**Usage → Limits** shows quota use and reset times for Codex and Claude subscriptions. It also
+compares quota consumed with time elapsed in each window, so you can judge your pace before the
+next reset.
+
+API-key accounts may not report subscription limits. This also applies to Claude connections
+using a proxy through `ANTHROPIC_AUTH_TOKEN`.
+
+## Connect a CLIProxyAPI hub
+
+To see pooled accounts, open **Settings → Providers → Usage providers → Add hub**. Choose the
+environment that will connect to the hub and enter its URL and management key.
+
+The accounts appear under **Usage → Limits**. This connection supplies usage information; configure
+the provider separately to send agent requests through the hub. Remove the hub from the same
+settings section when you no longer need it.

From cd713679bbe06c435823bafc48e5bcfa3266a9aa Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 12:49:52 -0700
Subject: [PATCH 04/56] fix(web): stop panel motion during navigation (#9766)

---
 apps/web/src/components/AppSidebarLayout.tsx | 82 +++++++++++---------
 apps/web/src/panelAnimations.test.tsx        | 64 +++++++++++++++
 apps/web/src/panelAnimations.ts              | 32 +++++++-
 3 files changed, 139 insertions(+), 39 deletions(-)
 create mode 100644 apps/web/src/panelAnimations.test.tsx

diff --git a/apps/web/src/components/AppSidebarLayout.tsx b/apps/web/src/components/AppSidebarLayout.tsx
index 3bef170bcf51..6769586f7fa8 100644
--- a/apps/web/src/components/AppSidebarLayout.tsx
+++ b/apps/web/src/components/AppSidebarLayout.tsx
@@ -15,7 +15,11 @@ import { resolveShortcutCommand, shortcutLabelForCommand } from "../keybindings"
 import { cn, isMacPlatform } from "../lib/utils";
 import { primaryServerKeybindingsAtom } from "../state/server";
 import { useEnvironmentIdentificationMode, useLegacySidebarEnabled } from "../hooks/useSettings";
-import { usePanelAnimationSettings } from "../panelAnimations";
+import {
+  PanelAnimationSuppressionProvider,
+  usePanelAnimationSettings,
+  usePanelNavigationSuppression,
+} from "../panelAnimations";
 import LegacyThreadSidebar from "./LegacySidebar";
 import ThreadSidebar from "./Sidebar";
 import { SettingsSidebarNav } from "./settings/SettingsSidebarNav";
@@ -145,6 +149,8 @@ export function AppSidebarLayout({ children }: { children: ReactNode }) {
   // Settings routes show the settings nav in place of whichever thread
   // sidebar is active.
   const pathname = useLocation({ select: (location) => location.pathname });
+  const panelAnimationsSuppressed = usePanelNavigationSuppression(pathname);
+  const routePanelAnimationsActive = panelAnimationsActive && !panelAnimationsSuppressed;
   const isOnSettings = pathname === "/settings" || pathname.startsWith("/settings/");
   const isMacosDesktop = isElectron && isMacPlatform(navigator.platform);
   const [sidebarWidth, setSidebarWidth] = useState(readInitialThreadSidebarWidth);
@@ -213,42 +219,44 @@ export function AppSidebarLayout({ children }: { children: ReactNode }) {
   }, [navigate, pathname]);
 
   return (
-    <SidebarProvider
-      className="h-dvh! min-h-0!"
-      data-panel-animations={panelAnimationsActive ? "true" : "false"}
-      defaultOpen
-      style={sidebarProviderStyle}
-    >
-      <ProjectProjectionRetention />
-      <Sidebar
-        side="left"
-        collapsible="offcanvas"
-        data-app-sidebar=""
-        className="border-r border-sidebar-border bg-sidebar text-sidebar-foreground"
-        resizable={{
-          maxWidth: sidebarMaximumWidth,
-          minWidth: THREAD_SIDEBAR_MIN_WIDTH,
-          shouldAcceptWidth: ({ currentWidth, nextWidth, wrapper }) =>
-            nextWidth <= currentWidth ||
-            wrapper.clientWidth - nextWidth >= THREAD_MAIN_CONTENT_MIN_WIDTH,
-          storageKey: THREAD_SIDEBAR_WIDTH_STORAGE_KEY,
-          onResize: setSidebarWidth,
-        }}
+    <PanelAnimationSuppressionProvider value={panelAnimationsSuppressed}>
+      <SidebarProvider
+        className="h-dvh! min-h-0!"
+        data-panel-animations={routePanelAnimationsActive ? "true" : "false"}
+        defaultOpen
+        style={sidebarProviderStyle}
       >
-        {isOnSettings ? (
-          <>
-            <SidebarChromeHeader isElectron={isElectron} />
-            <SettingsSidebarNav pathname={pathname} />
-          </>
-        ) : legacySidebarEnabled ? (
-          <LegacyThreadSidebar />
-        ) : (
-          <ThreadSidebar />
-        )}
-        <SidebarRail onDoubleClick={resetSidebarWidth} />
-      </Sidebar>
-      {children}
-      <SidebarControl />
-    </SidebarProvider>
+        <ProjectProjectionRetention />
+        <Sidebar
+          side="left"
+          collapsible="offcanvas"
+          data-app-sidebar=""
+          className="border-r border-sidebar-border bg-sidebar text-sidebar-foreground"
+          resizable={{
+            maxWidth: sidebarMaximumWidth,
+            minWidth: THREAD_SIDEBAR_MIN_WIDTH,
+            shouldAcceptWidth: ({ currentWidth, nextWidth, wrapper }) =>
+              nextWidth <= currentWidth ||
+              wrapper.clientWidth - nextWidth >= THREAD_MAIN_CONTENT_MIN_WIDTH,
+            storageKey: THREAD_SIDEBAR_WIDTH_STORAGE_KEY,
+            onResize: setSidebarWidth,
+          }}
+        >
+          {isOnSettings ? (
+            <>
+              <SidebarChromeHeader isElectron={isElectron} />
+              <SettingsSidebarNav pathname={pathname} />
+            </>
+          ) : legacySidebarEnabled ? (
+            <LegacyThreadSidebar />
+          ) : (
+            <ThreadSidebar />
+          )}
+          <SidebarRail onDoubleClick={resetSidebarWidth} />
+        </Sidebar>
+        {children}
+        <SidebarControl />
+      </SidebarProvider>
+    </PanelAnimationSuppressionProvider>
   );
 }
diff --git a/apps/web/src/panelAnimations.test.tsx b/apps/web/src/panelAnimations.test.tsx
new file mode 100644
index 000000000000..2475425086f2
--- /dev/null
+++ b/apps/web/src/panelAnimations.test.tsx
@@ -0,0 +1,64 @@
+import { act, useLayoutEffect } from "react";
+import { create, type ReactTestRenderer } from "react-test-renderer";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+import { usePanelNavigationSuppression } from "./panelAnimations";
+
+let renderer: ReactTestRenderer | null = null;
+let pendingFrames: FrameRequestCallback[] = [];
+let observed: boolean[] = [];
+
+function SuppressionProbe({ navigationKey }: { navigationKey: string }) {
+  const suppressed = usePanelNavigationSuppression(navigationKey);
+  useLayoutEffect(() => {
+    observed.push(suppressed);
+  }, [suppressed]);
+  return null;
+}
+
+beforeEach(() => {
+  pendingFrames = [];
+  observed = [];
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  vi.stubGlobal("window", {
+    requestAnimationFrame: vi.fn((callback: FrameRequestCallback) => {
+      pendingFrames.push(callback);
+      return pendingFrames.length;
+    }),
+    cancelAnimationFrame: vi.fn(),
+  });
+});
+
+afterEach(async () => {
+  await act(() => renderer?.unmount());
+  vi.unstubAllGlobals();
+});
+
+async function paintPendingFrame() {
+  const callback = pendingFrames.shift();
+  await act(() => callback?.(0));
+}
+
+describe("usePanelNavigationSuppression", () => {
+  it("suppresses initial and navigated panel state until each route has painted", async () => {
+    await act(() => {
+      renderer = create(<SuppressionProbe navigationKey="/thread/one" />);
+    });
+    expect(observed.at(-1)).toBe(true);
+
+    await paintPendingFrame();
+    expect(observed.at(-1)).toBe(true);
+    await paintPendingFrame();
+    expect(observed.at(-1)).toBe(false);
+
+    await act(() => {
+      renderer?.update(<SuppressionProbe navigationKey="/thread/two" />);
+    });
+    expect(observed.at(-1)).toBe(true);
+
+    await paintPendingFrame();
+    expect(observed.at(-1)).toBe(true);
+    await paintPendingFrame();
+    expect(observed.at(-1)).toBe(false);
+  });
+});
diff --git a/apps/web/src/panelAnimations.ts b/apps/web/src/panelAnimations.ts
index f606a3f930d5..11dd597ec561 100644
--- a/apps/web/src/panelAnimations.ts
+++ b/apps/web/src/panelAnimations.ts
@@ -1,9 +1,36 @@
-import { useEffect, useRef, useState } from "react";
+import { createContext, useContext, useEffect, useRef, useState } from "react";
 import { type PanelAnimationDurationMs } from "@t3tools/contracts/settings";
 
 import { useMediaQuery } from "./hooks/useMediaQuery";
 import { useClientSettings } from "./hooks/useSettings";
 
+const PanelAnimationSuppressionContext = createContext(false);
+
+export const PanelAnimationSuppressionProvider = PanelAnimationSuppressionContext.Provider;
+
+/**
+ * Suppresses panel motion for the first painted frame of an initial route or navigation.
+ * State restored by a route must be visible immediately; later user actions can animate.
+ */
+export function usePanelNavigationSuppression(navigationKey: string): boolean {
+  const [paintedNavigationKey, setPaintedNavigationKey] = useState<string | null>(null);
+  const suppressed = paintedNavigationKey !== navigationKey;
+
+  useEffect(() => {
+    if (!suppressed) return;
+    let releaseFrame = 0;
+    const paintFrame = window.requestAnimationFrame(() => {
+      releaseFrame = window.requestAnimationFrame(() => setPaintedNavigationKey(navigationKey));
+    });
+    return () => {
+      window.cancelAnimationFrame(paintFrame);
+      window.cancelAnimationFrame(releaseFrame);
+    };
+  }, [navigationKey, suppressed]);
+
+  return suppressed;
+}
+
 export function observeResponsiveBreakpointFade(options: {
   target: HTMLElement;
   container: HTMLElement;
@@ -47,7 +74,8 @@ export function usePanelAnimationSettings(): {
 } {
   const durationMs = useClientSettings((settings) => settings.panelAnimationDurationMs);
   const prefersReducedMotion = useMediaQuery("(prefers-reduced-motion: reduce)");
-  return { active: durationMs > 0 && !prefersReducedMotion, durationMs };
+  const suppressed = useContext(PanelAnimationSuppressionContext);
+  return { active: durationMs > 0 && !prefersReducedMotion && !suppressed, durationMs };
 }
 
 /** Keeps closing panel content mounted until its opt-in transition ends. */

From 8e056a0e5124775b9439751667bac483d7b5320a Mon Sep 17 00:00:00 2001
From: maria <maria@kuuro.net>
Date: Fri, 4 Sep 2026 15:54:07 -0400
Subject: [PATCH 05/56] fix(web): open composer selectors below controls
 (#9767)

---
 apps/web/src/components/BranchToolbarEnvModeSelector.tsx     | 2 +-
 apps/web/src/components/BranchToolbarEnvironmentSelector.tsx | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/web/src/components/BranchToolbarEnvModeSelector.tsx b/apps/web/src/components/BranchToolbarEnvModeSelector.tsx
index 5a868483b34f..c0fa463fe72a 100644
--- a/apps/web/src/components/BranchToolbarEnvModeSelector.tsx
+++ b/apps/web/src/components/BranchToolbarEnvModeSelector.tsx
@@ -114,7 +114,7 @@ export const BranchToolbarEnvModeSelector = memo(function BranchToolbarEnvModeSe
           </span>
         </span>
       </SelectTrigger>
-      <SelectPopup {...composerFloatingLayerProps}>
+      <SelectPopup alignItemWithTrigger={false} {...composerFloatingLayerProps}>
         <SelectGroup>
           <SelectGroupLabel>Workspace</SelectGroupLabel>
           <SelectItem value="local">
diff --git a/apps/web/src/components/BranchToolbarEnvironmentSelector.tsx b/apps/web/src/components/BranchToolbarEnvironmentSelector.tsx
index fabda55688bc..431805f2174b 100644
--- a/apps/web/src/components/BranchToolbarEnvironmentSelector.tsx
+++ b/apps/web/src/components/BranchToolbarEnvironmentSelector.tsx
@@ -102,7 +102,7 @@ export const BranchToolbarEnvironmentSelector = memo(function BranchToolbarEnvir
           </span>
         </span>
       </SelectTrigger>
-      <SelectPopup {...composerFloatingLayerProps}>
+      <SelectPopup alignItemWithTrigger={false} {...composerFloatingLayerProps}>
         <SelectGroup>
           <SelectGroupLabel>Run on</SelectGroupLabel>
           {availableEnvironments.map((env) => (

From 163d86a78430d23414abde323ca70d8379280c0b Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Fri, 4 Sep 2026 13:06:10 -0700
Subject: [PATCH 06/56] perf(server): skip unused Linux process detail reads
 (#9768)

---
 native/resource-monitor/src/main.rs | 103 ++++++++++++++++++++++++++--
 1 file changed, 96 insertions(+), 7 deletions(-)

diff --git a/native/resource-monitor/src/main.rs b/native/resource-monitor/src/main.rs
index 0596aea977cd..78ba5a271cd3 100644
--- a/native/resource-monitor/src/main.rs
+++ b/native/resource-monitor/src/main.rs
@@ -346,7 +346,7 @@ impl Collector {
         self.system.refresh_processes_specifics(
             ProcessesToUpdate::All,
             true,
-            process_refresh_kind(),
+            process_discovery_refresh_kind(),
         );
         self.cpu_baseline_refreshed_at = Some(Instant::now());
     }
@@ -361,7 +361,7 @@ impl Collector {
         self.system.refresh_processes_specifics(
             ProcessesToUpdate::All,
             true,
-            process_refresh_kind(),
+            process_discovery_refresh_kind(),
         );
         self.cpu_baseline_refreshed_at = Some(Instant::now());
 
@@ -397,15 +397,57 @@ impl Collector {
         roots.insert(config.root_pid);
         let tracked = select_tracked_pids(&rows, &roots);
         let tracked_process_count = tracked.len();
+        let process_details = if cfg!(target_os = "linux") && !tracked.is_empty() {
+            let monitor_pid = Pid::from_u32(std::process::id());
+            let mut detail_pids = tracked
+                .iter()
+                .copied()
+                .map(Pid::from_u32)
+                .collect::<Vec<_>>();
+            if !tracked.contains(&monitor_pid.as_u32()) {
+                detail_pids.push(monitor_pid);
+            }
+            // Detail fields need no baseline. Drop command data and OS handles after each sample.
+            let mut details = System::new();
+            details.refresh_processes_specifics(
+                ProcessesToUpdate::Some(&detail_pids),
+                true,
+                process_refresh_kind().without_cpu(),
+            );
+            // This process cannot be replaced during collection. Its start time
+            // exposes any boot-epoch shift between the two System instances.
+            let start_time_offset = self.system.process(monitor_pid).and_then(|process| {
+                details.process(monitor_pid).map(|detail| {
+                    i128::from(detail.start_time()) - i128::from(process.start_time())
+                })
+            });
+            Some((details, start_time_offset))
+        } else {
+            None
+        };
+        let sample_details = process_details
+            .as_ref()
+            .map_or(&self.system, |(details, _)| details);
+        let start_time_offset = process_details
+            .as_ref()
+            .map_or(Some(0), |(_, offset)| *offset);
         let mut processes = tracked
             .into_iter()
             .filter_map(|pid| {
                 let process = self.system.process(Pid::from_u32(pid))?;
-                let disk_usage = process.disk_usage();
-                let command = if process.cmd().is_empty() {
+                let details = sample_details.process(Pid::from_u32(pid))?;
+                if !matches_process_start_time(
+                    process.start_time(),
+                    details.start_time(),
+                    start_time_offset?,
+                ) {
+                    return None;
+                }
+                let disk_usage = details.disk_usage();
+                let command = if details.cmd().is_empty() {
                     process.name().to_string_lossy().into_owned()
                 } else {
-                    process
+                    details
                         .cmd()
                         .iter()
                         .map(|part| part.to_string_lossy())
@@ -429,14 +471,15 @@ impl Collector {
                     ),
                     cpu_percent: process.cpu_usage(),
                     cpu_time_ms: process.accumulated_cpu_time(),
-                    resident_bytes: process.memory(),
-                    virtual_bytes: process.virtual_memory(),
+                    resident_bytes: details.memory(),
+                    virtual_bytes: details.virtual_memory(),
                     io_read_bytes: disk_usage.total_read_bytes,
                     io_write_bytes: disk_usage.total_written_bytes,
                     io_semantics: io_semantics(),
                 })
             })
             .collect::<Vec<_>>();
+        drop(process_details);
         processes.sort_by_key(|process| process.pid);
         self.sequence = self.sequence.saturating_add(1);
 
@@ -459,6 +502,15 @@ impl Collector {
     }
 }
 
+// Keep CPU baselines separate. Even a metadata refresh resets Linux process times.
+fn process_discovery_refresh_kind() -> ProcessRefreshKind {
+    if cfg!(target_os = "linux") {
+        ProcessRefreshKind::nothing().with_cpu().without_tasks()
+    } else {
+        process_refresh_kind()
+    }
+}
+
 fn process_refresh_kind() -> ProcessRefreshKind {
     ProcessRefreshKind::nothing()
         .with_memory()
@@ -472,6 +524,10 @@ fn inaccessible_process_count(selected: usize, materialized: usize) -> usize {
     selected.saturating_sub(materialized)
 }
 
+fn matches_process_start_time(discovered: u64, detail: u64, epoch_offset: i128) -> bool {
+    i128::from(detail) - epoch_offset == i128::from(discovered)
+}
+
 fn remaining_cpu_measurement_delay(
     baseline_refreshed_at: Option<Instant>,
     now: Instant,
@@ -889,6 +945,39 @@ mod tests {
         assert!(!matches_external_identity(10_000, Some(9_999)));
     }
 
+    #[test]
+    fn loads_details_when_an_existing_process_becomes_selected() {
+        let mut collector = Collector::new();
+        let mut config = CollectorConfig {
+            root_pid: u32::MAX,
+            sample_interval: None,
+            external_processes: HashMap::new(),
+        };
+        assert!(collector.sample(&config, None).processes.is_empty());
+
+        config.root_pid = std::process::id();
+        let snapshot = collector.sample(&config, None);
+        let process = snapshot
+            .processes
+            .iter()
+            .find(|process| process.pid == config.root_pid)
+            .expect("selected process");
+
+        assert!(!process.command.is_empty());
+        assert!(process.resident_bytes > 0);
+        assert!(process.cpu_percent.is_finite());
+    }
+
+    #[test]
+    fn accepts_clock_shifts_without_accepting_reused_process_starts() {
+        assert!(matches_process_start_time(10_000, 13_600, 3_600));
+        assert!(!matches_process_start_time(10_000, 13_601, 3_600));
+        assert!(matches_process_start_time(10_000, 6_400, -3_600));
+        assert!(!matches_process_start_time(10_000, 6_401, -3_600));
+        assert!(matches_process_start_time(10_000, 10_000, 0));
+        assert!(!matches_process_start_time(10_000, 10_001, 0));
+    }
+
     #[test]
     fn decodes_protocol_commands() {
         let configure = serde_json::from_str::<Command>(

From bfef973d9ec64e580fff4197ac53085207471ffd Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 13:24:40 -0700
Subject: [PATCH 07/56] fix(server): remove retired Codex models after refresh
 (#9773)

---
 .../provider/Layers/ProviderRegistry.test.ts  | 183 +++++++++++++++++-
 .../src/provider/Layers/ProviderRegistry.ts   |  10 +-
 2 files changed, 189 insertions(+), 4 deletions(-)

diff --git a/apps/server/src/provider/Layers/ProviderRegistry.test.ts b/apps/server/src/provider/Layers/ProviderRegistry.test.ts
index b961032a7082..d3843829159c 100644
--- a/apps/server/src/provider/Layers/ProviderRegistry.test.ts
+++ b/apps/server/src/provider/Layers/ProviderRegistry.test.ts
@@ -49,7 +49,11 @@ import {
 } from "./ProviderRegistry.ts";
 import * as ServerConfig from "../../config.ts";
 import * as ServerSettingsModule from "../../serverSettings.ts";
-import { readProviderStatusCache, resolveProviderStatusCachePath } from "../providerStatusCache.ts";
+import {
+  readProviderStatusCache,
+  resolveProviderStatusCachePath,
+  writeProviderStatusCache,
+} from "../providerStatusCache.ts";
 import { COMPACT_SLASH_COMMAND } from "../providerSnapshot.ts";
 import type { ProviderInstance } from "../ProviderDriver.ts";
 import * as ProviderInstanceRegistry from "../Services/ProviderInstanceRegistry.ts";
@@ -900,6 +904,183 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
         assert.deepStrictEqual(afterFailure.models, [authoritativeProvider.models[0]!]);
       });
 
+      describe("Codex model inventories", () => {
+        const cachedProvider = {
+          instanceId: ProviderInstanceId.make("codex-personal"),
+          driver: ProviderDriverKind.make("codex"),
+          status: "ready",
+          enabled: true,
+          installed: true,
+          auth: { status: "authenticated" },
+          checkedAt: "2026-09-04T19:00:00.000Z",
+          version: "0.153.3",
+          models: [
+            "vega-alpha",
+            "joule-alpha",
+            "kindle-alpha",
+            "ultima-alpha",
+            "solstice-alpha",
+          ].map((slug) => ({ slug, name: slug, isCustom: false, capabilities: null })),
+          slashCommands: [],
+          skills: [],
+        } satisfies ServerProvider;
+        const customModel = {
+          slug: "custom-model",
+          name: "Custom model",
+          isCustom: true,
+          capabilities: null,
+        } as const;
+        const refreshedProvider = {
+          ...cachedProvider,
+          checkedAt: "2026-09-04T19:01:00.000Z",
+          models: [
+            { slug: "gpt-6-astra", name: "GPT 6 Astra", isCustom: false, capabilities: null },
+            cachedProvider.models[0]!,
+            customModel,
+          ],
+        } satisfies ServerProvider;
+        const pendingProvider = {
+          ...cachedProvider,
+          status: "warning",
+          installed: false,
+          auth: { status: "unknown" },
+          models: [customModel],
+        } satisfies ServerProvider;
+        const failedProvider = {
+          ...pendingProvider,
+          checkedAt: "2026-09-04T19:02:00.000Z",
+          status: "error",
+          installed: true,
+        } satisfies ServerProvider;
+
+        it("drops retired alpha models after discovery, including without OpenAI authentication", () => {
+          for (const authStatus of ["authenticated", "unknown"] as const) {
+            assert.deepStrictEqual(
+              mergeProviderSnapshot(cachedProvider, {
+                ...refreshedProvider,
+                auth: { status: authStatus },
+              }).models,
+              refreshedProvider.models,
+            );
+          }
+        });
+
+        it("keeps discovered models during startup and failed probes without restoring removed custom models", () => {
+          for (const provider of [pendingProvider, failedProvider]) {
+            assert.deepStrictEqual(
+              mergeProviderSnapshot(
+                {
+                  ...cachedProvider,
+                  models: [...cachedProvider.models, { ...customModel, slug: "removed-custom" }],
+                },
+                provider,
+              ).models,
+              [customModel, ...cachedProvider.models],
+            );
+          }
+        });
+
+        it("clears discovered models after sign-out, disable, uninstall, or empty discovery", () => {
+          const emptyProvider = { ...refreshedProvider, models: [customModel] };
+          const clearedProviders = [
+            { ...emptyProvider, status: "error", auth: { status: "unauthenticated" } },
+            { ...emptyProvider, status: "disabled", enabled: false },
+            { ...emptyProvider, status: "error", installed: false, auth: { status: "unknown" } },
+            emptyProvider,
+            { ...emptyProvider, models: [] },
+          ] satisfies ReadonlyArray<ServerProvider>;
+
+          for (const provider of clearedProviders) {
+            assert.deepStrictEqual(
+              mergeProviderSnapshot(cachedProvider, provider).models,
+              provider.models,
+            );
+          }
+        });
+
+        it.effect("persists removals across failed refreshes and registry restarts", () =>
+          Effect.gen(function* () {
+            const config = yield* ServerConfig.ServerConfig;
+            const filePath = yield* resolveProviderStatusCachePath({
+              cacheDir: config.providerStatusCacheDir,
+              instanceId: cachedProvider.instanceId,
+            });
+            yield* writeProviderStatusCache({ filePath, provider: cachedProvider });
+            const nextProvider = yield* Ref.make<ServerProvider>(refreshedProvider);
+            const instance = {
+              instanceId: cachedProvider.instanceId,
+              driverKind: cachedProvider.driver,
+              continuationIdentity: {
+                driverKind: cachedProvider.driver,
+                continuationKey: "codex:instance:codex-personal",
+              },
+              displayName: undefined,
+              enabled: true,
+              snapshot: {
+                maintenanceCapabilities: makeManualOnlyProviderMaintenanceCapabilities({
+                  provider: cachedProvider.driver,
+                  packageName: null,
+                }),
+                getSnapshot: Effect.succeed(pendingProvider),
+                refresh: Ref.get(nextProvider),
+                streamChanges: Stream.empty,
+                applyUsageLimits: () => Effect.void,
+              },
+              adapter: {} as ProviderInstance["adapter"],
+              textGeneration: {} as ProviderInstance["textGeneration"],
+            } satisfies ProviderInstance;
+            const instanceRegistryLayer = Layer.succeed(
+              ProviderInstanceRegistry.ProviderInstanceRegistry,
+              {
+                getInstance: (id) =>
+                  Effect.succeed(id === instance.instanceId ? instance : undefined),
+                listInstances: Effect.succeed([instance]),
+                listUnavailable: Effect.succeed([]),
+                streamChanges: Stream.empty,
+                subscribeChanges: Effect.flatMap(PubSub.unbounded<void>(), PubSub.subscribe),
+              },
+            );
+            const retainedModels = [
+              customModel,
+              ...refreshedProvider.models.filter((model) => !model.isCustom),
+            ];
+
+            for (const restarted of [false, true]) {
+              yield* Effect.gen(function* () {
+                const registry = yield* ProviderRegistry.ProviderRegistry;
+                const expectedModels = restarted
+                  ? retainedModels
+                  : [customModel, ...cachedProvider.models];
+                assert.deepStrictEqual((yield* registry.getProviders)[0]?.models, expectedModels);
+
+                yield* registry.refreshInstance(instance.instanceId);
+                assert.deepStrictEqual(
+                  (yield* readProviderStatusCache(filePath))?.models,
+                  restarted ? retainedModels : refreshedProvider.models,
+                );
+
+                yield* Ref.set(nextProvider, failedProvider);
+                const afterFailure = yield* registry.refreshInstance(instance.instanceId);
+                assert.deepStrictEqual(afterFailure[0]?.models, retainedModels);
+                assert.deepStrictEqual(
+                  (yield* readProviderStatusCache(filePath))?.models,
+                  retainedModels,
+                );
+              }).pipe(
+                Effect.provide(ProviderRegistryLive.pipe(Layer.provide(instanceRegistryLayer))),
+                Effect.scoped,
+              );
+            }
+          }).pipe(
+            Effect.provide(
+              ServerConfig.layerTest(process.cwd(), {
+                prefix: "t3-codex-retired-model-cache-",
+              }).pipe(Layer.provideMerge(NodeServices.layer)),
+            ),
+          ),
+        );
+      });
+
       describe("Antigravity model inventories", () => {
         const previousProvider = {
           instanceId: ProviderInstanceId.make("antigravity-personal"),
diff --git a/apps/server/src/provider/Layers/ProviderRegistry.ts b/apps/server/src/provider/Layers/ProviderRegistry.ts
index 4c8658e38afc..bc972d7a6559 100644
--- a/apps/server/src/provider/Layers/ProviderRegistry.ts
+++ b/apps/server/src/provider/Layers/ProviderRegistry.ts
@@ -102,15 +102,19 @@ export function upsertProviderWorkspaceSnapshot(
 
 const shouldRetainMissingProviderModels = (provider: ServerProvider): boolean => {
   const isAntigravity = provider.driver === ProviderDriverKind.make("antigravity");
-  if (!isAntigravity && provider.driver !== ProviderDriverKind.make("opencode")) {
+  const isCodex = provider.driver === ProviderDriverKind.make("codex");
+  if (!isAntigravity && !isCodex && provider.driver !== ProviderDriverKind.make("opencode")) {
     return true;
   }
 
-  if (isAntigravity && (!provider.enabled || provider.auth.status === "unauthenticated")) {
+  if (
+    (isAntigravity || isCodex) &&
+    (!provider.enabled || provider.auth.status === "unauthenticated")
+  ) {
     return false;
   }
 
-  // Both drivers replace their inventories after successful catalog discovery.
+  // Successful discovery replaces these inventories so cached retired models disappear.
   // Antigravity's local health check does not authenticate or discover models.
   const isPendingAntigravityAuthentication =
     isAntigravity && provider.status === "warning" && provider.auth.status === "unknown";

From cc60753aa2279722149e182fb942ca87f70ff804 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 13:33:19 -0700
Subject: [PATCH 08/56] test: stop path and platform tests depending on the
 host OS (#9564)

Co-authored-by: Claude Code <noreply@anthropic.com>
---
 .../src/app/DesktopAppIdentity.test.ts        |  2 ++
 apps/desktop/src/app/DesktopAssets.test.ts    |  8 +++++-
 .../src/app/DesktopEnvironment.test.ts        |  7 ++++-
 .../server/src/auth/ServerSecretStore.test.ts |  4 +--
 .../project/ProjectFaviconResolver.test.ts    |  5 ++--
 .../src/provider/Drivers/ClaudeSkills.test.ts | 20 +++++++++-----
 packages/ssh/src/config.test.ts               |  3 ++-
 packages/tailscale/src/tailscale.test.ts      | 26 ++++++++++---------
 scripts/mobile-showcase.test.ts               | 20 +++++++++-----
 scripts/mobile-showcase.ts                    |  3 ++-
 10 files changed, 65 insertions(+), 33 deletions(-)

diff --git a/apps/desktop/src/app/DesktopAppIdentity.test.ts b/apps/desktop/src/app/DesktopAppIdentity.test.ts
index 5c39ff304b3b..71bcf5f7aef1 100644
--- a/apps/desktop/src/app/DesktopAppIdentity.test.ts
+++ b/apps/desktop/src/app/DesktopAppIdentity.test.ts
@@ -1,3 +1,4 @@
+import * as NodePath from "@effect/platform-node/NodePath";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, describe, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
@@ -88,6 +89,7 @@ const makeEnvironmentLayer = (overrides: TestEnvironmentInput = {}) => {
     Layer.provide(
       Layer.mergeAll(
         NodeServices.layer,
+        NodePath.layerPosix,
         DesktopConfig.layerTest({
           ...env,
         }),
diff --git a/apps/desktop/src/app/DesktopAssets.test.ts b/apps/desktop/src/app/DesktopAssets.test.ts
index bb118d43d29a..78819d06e6cc 100644
--- a/apps/desktop/src/app/DesktopAssets.test.ts
+++ b/apps/desktop/src/app/DesktopAssets.test.ts
@@ -1,3 +1,4 @@
+import * as NodePath from "@effect/platform-node/NodePath";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, describe, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
@@ -20,7 +21,11 @@ const environmentLayer = DesktopEnvironment.layer({
   isPackaged: true,
   resourcesPath: "/Applications/T3 Code.app/Contents/Resources",
   runningUnderArm64Translation: false,
-}).pipe(Layer.provide(Layer.mergeAll(NodeServices.layer, DesktopConfig.layerTest({}))));
+}).pipe(
+  Layer.provide(
+    Layer.mergeAll(NodeServices.layer, NodePath.layerPosix, DesktopConfig.layerTest({})),
+  ),
+);
 
 describe("DesktopAssets", () => {
   it.effect("uses canonical source-tree icons for unpackaged development", () =>
@@ -39,6 +44,7 @@ describe("DesktopAssets", () => {
         Layer.provide(
           Layer.mergeAll(
             NodeServices.layer,
+            NodePath.layerPosix,
             DesktopConfig.layerTest({ VITE_DEV_SERVER_URL: "http://localhost:5733" }),
           ),
         ),
diff --git a/apps/desktop/src/app/DesktopEnvironment.test.ts b/apps/desktop/src/app/DesktopEnvironment.test.ts
index 218e2c3e4ba2..89cc592831a7 100644
--- a/apps/desktop/src/app/DesktopEnvironment.test.ts
+++ b/apps/desktop/src/app/DesktopEnvironment.test.ts
@@ -1,3 +1,4 @@
+import * as NodePath from "@effect/platform-node/NodePath";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, describe, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
@@ -26,7 +27,11 @@ const makeEnvironmentLayer = (
   DesktopEnvironment.layer({
     ...defaultInput,
     ...overrides,
-  }).pipe(Layer.provide(Layer.mergeAll(NodeServices.layer, DesktopConfig.layerTest(env))));
+  }).pipe(
+    Layer.provide(
+      Layer.mergeAll(NodeServices.layer, NodePath.layerPosix, DesktopConfig.layerTest(env)),
+    ),
+  );
 
 const makeEnvironment = (
   overrides: Partial<DesktopEnvironment.MakeDesktopEnvironmentInput> = {},
diff --git a/apps/server/src/auth/ServerSecretStore.test.ts b/apps/server/src/auth/ServerSecretStore.test.ts
index d4411fb9f3b7..6b7850aa363b 100644
--- a/apps/server/src/auth/ServerSecretStore.test.ts
+++ b/apps/server/src/auth/ServerSecretStore.test.ts
@@ -109,7 +109,7 @@ const ConcurrentReadMissFileSystemLayer = Layer.effect(
     return {
       ...fileSystem,
       readFile: (path) =>
-        String(path).endsWith("/session-signing-key.bin")
+        /[\\/]session-signing-key\.bin$/.test(String(path))
           ? Ref.updateAndGet(readCountRef, (count) => count + 1).pipe(
               Effect.flatMap((count) => {
                 if (count > 2) {
@@ -219,7 +219,7 @@ it.layer(NodeServices.layer)("ServerSecretStore.layer", (it) => {
       yield* secretStore.set("session-signing-key", Uint8Array.from([1, 2, 3]));
 
       assert.isTrue(
-        chmodCalls.some((call) => call.mode === 0o700 && call.path.endsWith("/secrets")),
+        chmodCalls.some((call) => call.mode === 0o700 && /[\\/]secrets$/.test(call.path)),
       );
       assert.isAtLeast(chmodCalls.filter((call) => call.mode === 0o600).length, 2);
     }).pipe(Effect.provide(NodeServices.layer)),
diff --git a/apps/server/src/project/ProjectFaviconResolver.test.ts b/apps/server/src/project/ProjectFaviconResolver.test.ts
index 2c7b0f7bdc62..b8d6b46da088 100644
--- a/apps/server/src/project/ProjectFaviconResolver.test.ts
+++ b/apps/server/src/project/ProjectFaviconResolver.test.ts
@@ -54,11 +54,12 @@ it.layer(TestLayer)("ProjectFaviconResolverLive", (it) => {
     it.effect("serves repeated resolves from cache instead of re-walking candidates", () =>
       Effect.gen(function* () {
         const resolver = yield* ProjectFaviconResolver.ProjectFaviconResolver;
+        const path = yield* Path.Path;
         const cwd = yield* makeTempDir;
         yield* writeTextFile(cwd, "public/favicon.svg", "<svg>public</svg>");
 
         const resolved = yield* resolver.resolvePath(cwd);
-        expect(resolved?.endsWith("public/favicon.svg")).toBe(true);
+        expect(resolved?.endsWith(path.join("public", "favicon.svg"))).toBe(true);
 
         // `favicon.svg` outranks `public/favicon.svg`, so a resolver that walked
         // the candidate list again would switch to it. Staying on the original
@@ -71,7 +72,7 @@ it.layer(TestLayer)("ProjectFaviconResolverLive", (it) => {
 
         yield* TestClock.adjust(Duration.minutes(11));
 
-        expect((yield* resolver.resolvePath(cwd))?.endsWith("/favicon.svg")).toBe(true);
+        expect(yield* resolver.resolvePath(cwd)).toBe(path.join(cwd, "favicon.svg"));
         expect(yield* resolver.resolvePath(cwd)).not.toBe(resolved);
       }).pipe(Effect.provide(TestClock.layer())),
     );
diff --git a/apps/server/src/provider/Drivers/ClaudeSkills.test.ts b/apps/server/src/provider/Drivers/ClaudeSkills.test.ts
index 3e46ba94df03..d126a15c12b8 100644
--- a/apps/server/src/provider/Drivers/ClaudeSkills.test.ts
+++ b/apps/server/src/provider/Drivers/ClaudeSkills.test.ts
@@ -1,3 +1,4 @@
+import * as NodePath from "@effect/platform-node/NodePath";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
@@ -492,7 +493,11 @@ it.layer(NodeServices.layer)("discoverClaudeSkills", (it) => {
 
   it.effect("lets the administrator's managed policy outrank every other settings file", () =>
     Effect.gen(function* () {
-      const path = yield* Path.Path;
+      // The function is pure on its `path` argument, so hand it the
+      // implementation matching each platform under test rather than the
+      // host's.
+      const path = yield* Path.Path.pipe(Effect.provide(NodePath.layerPosix));
+      const win32Path = yield* Path.Path.pipe(Effect.provide(NodePath.layerWin32));
 
       for (const [platform, expected] of [
         ["darwin", "/Library/Application Support/ClaudeCode/managed-settings.json"],
@@ -508,14 +513,15 @@ it.layer(NodeServices.layer)("discoverClaudeSkills", (it) => {
       }
 
       assert.deepEqual(
-        skillOverrideSettingsPaths(path, "/home/.claude", undefined, "win32", {
-          PROGRAMDATA: "C:/ProgramData",
+        skillOverrideSettingsPaths(win32Path, "C:\\Users\\me\\.claude", undefined, "win32", {
+          PROGRAMDATA: "C:\\ProgramData",
         }).at(-1),
-        "C:/ProgramData/ClaudeCode/managed-settings.json",
+        "C:\\ProgramData\\ClaudeCode\\managed-settings.json",
+      );
+      assert.deepEqual(
+        skillOverrideSettingsPaths(win32Path, "C:\\Users\\me\\.claude", undefined, "win32", {}),
+        ["C:\\Users\\me\\.claude\\settings.json"],
       );
-      assert.deepEqual(skillOverrideSettingsPaths(path, "/home/.claude", undefined, "win32", {}), [
-        "/home/.claude/settings.json",
-      ]);
 
       // Only the repository root's local file joins in, after the
       // workspace's own local file so it wins.
diff --git a/packages/ssh/src/config.test.ts b/packages/ssh/src/config.test.ts
index 0446370337ad..4fd3b7636d3f 100644
--- a/packages/ssh/src/config.test.ts
+++ b/packages/ssh/src/config.test.ts
@@ -1,3 +1,4 @@
+import * as NodePath from "@effect/platform-node/NodePath";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, describe, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
@@ -133,6 +134,6 @@ describe("ssh config", () => {
         "/tmp/home",
       );
       assert.equal(pattern, "/tmp/home/.ssh/config.d/*.conf");
-    }).pipe(Effect.provide(NodeServices.layer)),
+    }).pipe(Effect.provide(NodePath.layerPosix)),
   );
 });
diff --git a/packages/tailscale/src/tailscale.test.ts b/packages/tailscale/src/tailscale.test.ts
index 09d9def21066..102153f6e204 100644
--- a/packages/tailscale/src/tailscale.test.ts
+++ b/packages/tailscale/src/tailscale.test.ts
@@ -8,6 +8,7 @@ import * as Sink from "effect/Sink";
 import * as Stream from "effect/Stream";
 import * as TestClock from "effect/testing/TestClock";
 import { ChildProcessSpawner } from "effect/unstable/process";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 
 import {
   buildTailscaleHttpsBaseUrl,
@@ -98,14 +99,22 @@ function neverFinishingMockHandle() {
   });
 }
 
+// The executable name depends on the host platform (`tailscale.exe` on
+// Windows), so pin it: these tests assert the posix spelling.
+function spawnerLayer(spawner: ChildProcessSpawner.ChildProcessSpawner["Service"]) {
+  return Layer.merge(
+    Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, spawner),
+    Layer.succeed(HostProcessPlatform, "linux"),
+  );
+}
+
 function mockSpawnerLayer(
   handler: (
     command: string,
     args: ReadonlyArray<string>,
   ) => { stdout?: string; stderr?: string; code?: number },
 ) {
-  return Layer.succeed(
-    ChildProcessSpawner.ChildProcessSpawner,
+  return spawnerLayer(
     ChildProcessSpawner.make((command) => {
       const childProcess = command as unknown as {
         readonly command: string;
@@ -194,10 +203,7 @@ describe("tailscale", () => {
       method: "spawn",
       cause: systemCause,
     });
-    const layer = Layer.succeed(
-      ChildProcessSpawner.ChildProcessSpawner,
-      ChildProcessSpawner.make(() => Effect.fail(cause)),
-    );
+    const layer = spawnerLayer(ChildProcessSpawner.make(() => Effect.fail(cause)));
 
     return Effect.gen(function* () {
       const error = yield* readTailscaleStatus.pipe(Effect.flip, Effect.provide(layer));
@@ -218,8 +224,7 @@ describe("tailscale", () => {
     // inside an `Effect.callback` registration, so that throw arrives as a
     // defect rather than a typed error - the shape reproduced here.
     const defect = Object.assign(new Error("spawn tailscale ENOTDIR"), { code: "ENOTDIR" });
-    const layer = Layer.succeed(
-      ChildProcessSpawner.ChildProcessSpawner,
+    const layer = spawnerLayer(
       ChildProcessSpawner.make(() =>
         Effect.callback<never, never>(() => {
           throw defect;
@@ -297,10 +302,7 @@ describe("tailscale", () => {
   it.effect("times out tailscale status through TestClock", () => {
     const layer = Layer.merge(
       TestClock.layer(),
-      Layer.succeed(
-        ChildProcessSpawner.ChildProcessSpawner,
-        ChildProcessSpawner.make(() => Effect.succeed(neverFinishingMockHandle())),
-      ),
+      spawnerLayer(ChildProcessSpawner.make(() => Effect.succeed(neverFinishingMockHandle()))),
     );
 
     return Effect.gen(function* () {
diff --git a/scripts/mobile-showcase.test.ts b/scripts/mobile-showcase.test.ts
index 2fd4c1dd8edd..a3f11e3a37c7 100644
--- a/scripts/mobile-showcase.test.ts
+++ b/scripts/mobile-showcase.test.ts
@@ -1,3 +1,5 @@
+// @effect-diagnostics nodeBuiltinImport:off - expectations mirror the host path joins the script under test performs.
+import * as NodePath from "node:path";
 import { assert, it } from "@effect/vitest";
 import { PNG } from "pngjs";
 
@@ -167,8 +169,14 @@ it("expands both appearances into independent upload-ready directories", () => {
       directory: showcaseCaptureDirectory("/captures", capture),
     })),
     [
-      { appearance: "light", directory: "/captures/apple/iphone-test/light/t3-code" },
-      { appearance: "dark", directory: "/captures/apple/iphone-test/dark/t3-code" },
+      {
+        appearance: "light",
+        directory: NodePath.join("/captures", "apple", "iphone-test", "light", "t3-code"),
+      },
+      {
+        appearance: "dark",
+        directory: NodePath.join("/captures", "apple", "iphone-test", "dark", "t3-code"),
+      },
     ],
   );
 });
@@ -192,10 +200,10 @@ it("expands themes into independent upload-ready directories per appearance", ()
       showcaseCaptureDirectory("/captures", capture),
     ),
     [
-      "/captures/apple/iphone-test/light/ocean",
-      "/captures/apple/iphone-test/light/ember",
-      "/captures/apple/iphone-test/dark/ocean",
-      "/captures/apple/iphone-test/dark/ember",
+      NodePath.join("/captures", "apple", "iphone-test", "light", "ocean"),
+      NodePath.join("/captures", "apple", "iphone-test", "light", "ember"),
+      NodePath.join("/captures", "apple", "iphone-test", "dark", "ocean"),
+      NodePath.join("/captures", "apple", "iphone-test", "dark", "ember"),
     ],
   );
 });
diff --git a/scripts/mobile-showcase.ts b/scripts/mobile-showcase.ts
index d6ced75d5db2..6b6adebeb779 100644
--- a/scripts/mobile-showcase.ts
+++ b/scripts/mobile-showcase.ts
@@ -53,7 +53,8 @@ export function resolveAndroidSdkRoot(
   const configured = environment.ANDROID_HOME ?? environment.ANDROID_SDK_ROOT;
   if (configured) return configured;
   const home = environment.HOME ?? environment.USERPROFILE ?? "";
-  return NodePath.join(home, platform === "darwin" ? "Library/Android/sdk" : "Android/Sdk");
+  const path = platform === "win32" ? NodePath.win32 : NodePath.posix;
+  return path.join(home, platform === "darwin" ? "Library/Android/sdk" : "Android/Sdk");
 }
 
 const ANDROID_SDK_ROOT = resolveAndroidSdkRoot(NodeProcess.env);

From 4701041eef6339bbda0d9d9b00a929c4e9e18662 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 13:33:19 -0700
Subject: [PATCH 09/56] test(server): skip posix executable fixtures on a
 Windows host (#9565)

Co-authored-by: Claude Code <noreply@anthropic.com>
---
 .../src/process/externalLauncher.test.ts      | 596 +++++++++---------
 .../provider/AntigravityInstallation.test.ts  | 122 ++--
 .../src/provider/providerMaintenance.test.ts  |  12 +-
 .../ResourceMonitorBinary.test.ts             |   8 +-
 4 files changed, 391 insertions(+), 347 deletions(-)

diff --git a/apps/server/src/process/externalLauncher.test.ts b/apps/server/src/process/externalLauncher.test.ts
index 030453e2f06f..2ae1684b67d4 100644
--- a/apps/server/src/process/externalLauncher.test.ts
+++ b/apps/server/src/process/externalLauncher.test.ts
@@ -20,6 +20,12 @@ import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 import { SpawnExecutableResolution } from "@t3tools/shared/shell";
 import * as ExternalLauncher from "./externalLauncher.ts";
 
+// Tests below write `#!/bin/sh` stubs into a real temp dir and hand that
+// directory to a posix-mocked resolver as PATH. On a Windows host the temp
+// path carries a drive letter, so the posix `:` split shatters it; there is
+// no posix executable to find there anyway.
+const windowsHost = HostProcessPlatform.defaultValue() === "win32";
+
 interface MockSpawnResult {
   readonly exitCode?: number;
   readonly stdout?: string;
@@ -153,7 +159,7 @@ it.effect("launches an installed editor with platform-safe arguments", () =>
   }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
-it.effect("reveals a file in Finder with open -R on macOS", () =>
+it.effect.skipIf(windowsHost)("reveals a file in Finder with open -R on macOS", () =>
   Effect.gen(function* () {
     const fileSystem = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
@@ -336,196 +342,208 @@ it.effect("does not advertise reveal on Windows when PowerShell is missing", ()
   }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
-it.effect("reveals a WSL file in Windows File Explorer through its UNC path", () =>
-  Effect.gen(function* () {
-    const fileSystem = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
-    for (const name of ["explorer.exe", "powershell.exe", "xdg-open"]) {
-      const filePath = path.join(binDir, name);
-      yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
-      yield* fileSystem.chmod(filePath, 0o755);
-    }
+it.effect.skipIf(windowsHost)(
+  "reveals a WSL file in Windows File Explorer through its UNC path",
+  () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
+      for (const name of ["explorer.exe", "powershell.exe", "xdg-open"]) {
+        const filePath = path.join(binDir, name);
+        yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
+        yield* fileSystem.chmod(filePath, 0o755);
+      }
 
-    let spawned: ChildProcess.StandardCommand | undefined;
-    const result = yield* Effect.gen(function* () {
-      const launcher = yield* ExternalLauncher.ExternalLauncher;
-      const kind = yield* launcher.resolveFileManagerRevealKind();
-      const editors = yield* launcher.resolveAvailableEditors();
-      yield* launcher.launchEditor({
-        editor: "file-manager",
-        cwd: "/home/t3/workspace/media/clip.mp4",
-        reveal: true,
-      });
-      return { kind, editors };
-    }).pipe(
-      Effect.provide(
-        testLayer({
-          platform: "linux",
-          env: {
-            PATH: binDir,
-            WSL_DISTRO_NAME: "Ubuntu-24.04",
-            WSL_INTEROP: "/run/WSL/1_interop",
-          },
-          onSpawn: (command) => {
-            spawned = command;
-          },
-        }),
-      ),
-    );
+      let spawned: ChildProcess.StandardCommand | undefined;
+      const result = yield* Effect.gen(function* () {
+        const launcher = yield* ExternalLauncher.ExternalLauncher;
+        const kind = yield* launcher.resolveFileManagerRevealKind();
+        const editors = yield* launcher.resolveAvailableEditors();
+        yield* launcher.launchEditor({
+          editor: "file-manager",
+          cwd: "/home/t3/workspace/media/clip.mp4",
+          reveal: true,
+        });
+        return { kind, editors };
+      }).pipe(
+        Effect.provide(
+          testLayer({
+            platform: "linux",
+            env: {
+              PATH: binDir,
+              WSL_DISTRO_NAME: "Ubuntu-24.04",
+              WSL_INTEROP: "/run/WSL/1_interop",
+            },
+            onSpawn: (command) => {
+              spawned = command;
+            },
+          }),
+        ),
+      );
 
-    assert.equal(result.kind, "file-explorer");
-    assert.equal(result.editors.includes("file-manager"), true);
-    assert.ok(spawned);
-    // The reveal routes through interop PowerShell so Explorer receives its
-    // raw `/select,"<path>"` switch even for spaced paths.
-    assert.equal(spawned.command, "powershell.exe");
-    const encodedCommand = spawned.args[spawned.args.length - 1] ?? "";
-    const decodedCommand = Buffer.from(encodedCommand, "base64").toString("utf16le");
-    assert.equal(
-      decodedCommand,
-      "$ProgressPreference = 'SilentlyContinue'; Start-Process 'explorer.exe' -ArgumentList ('/select,\"' + '\\\\wsl.localhost\\Ubuntu-24.04\\home\\t3\\workspace\\media\\clip.mp4' + '\"')",
-    );
-  }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+      assert.equal(result.kind, "file-explorer");
+      assert.equal(result.editors.includes("file-manager"), true);
+      assert.ok(spawned);
+      // The reveal routes through interop PowerShell so Explorer receives its
+      // raw `/select,"<path>"` switch even for spaced paths.
+      assert.equal(spawned.command, "powershell.exe");
+      const encodedCommand = spawned.args[spawned.args.length - 1] ?? "";
+      const decodedCommand = Buffer.from(encodedCommand, "base64").toString("utf16le");
+      assert.equal(
+        decodedCommand,
+        "$ProgressPreference = 'SilentlyContinue'; Start-Process 'explorer.exe' -ArgumentList ('/select,\"' + '\\\\wsl.localhost\\Ubuntu-24.04\\home\\t3\\workspace\\media\\clip.mp4' + '\"')",
+      );
+    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
-it.effect("does not advertise reveal from WSL when interop PowerShell is missing", () =>
-  Effect.gen(function* () {
-    const fileSystem = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
-    const explorerPath = path.join(binDir, "explorer.exe");
-    yield* fileSystem.writeFileString(explorerPath, "");
-    yield* fileSystem.chmod(explorerPath, 0o755);
+it.effect.skipIf(windowsHost)(
+  "does not advertise reveal from WSL when interop PowerShell is missing",
+  () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
+      const explorerPath = path.join(binDir, "explorer.exe");
+      yield* fileSystem.writeFileString(explorerPath, "");
+      yield* fileSystem.chmod(explorerPath, 0o755);
 
-    const result = yield* Effect.gen(function* () {
-      const launcher = yield* ExternalLauncher.ExternalLauncher;
-      return {
-        kind: yield* launcher.resolveFileManagerRevealKind(),
-        editors: yield* launcher.resolveAvailableEditors(),
-      };
-    }).pipe(
-      Effect.provide(
-        testLayer({
-          platform: "linux",
-          env: {
-            PATH: binDir,
-            WSL_DISTRO_NAME: "Ubuntu-24.04",
-            WSL_INTEROP: "/run/WSL/1_interop",
-          },
-        }),
-      ),
-    );
+      const result = yield* Effect.gen(function* () {
+        const launcher = yield* ExternalLauncher.ExternalLauncher;
+        return {
+          kind: yield* launcher.resolveFileManagerRevealKind(),
+          editors: yield* launcher.resolveAvailableEditors(),
+        };
+      }).pipe(
+        Effect.provide(
+          testLayer({
+            platform: "linux",
+            env: {
+              PATH: binDir,
+              WSL_DISTRO_NAME: "Ubuntu-24.04",
+              WSL_INTEROP: "/run/WSL/1_interop",
+            },
+          }),
+        ),
+      );
 
-    assert.equal(result.editors.includes("file-manager"), true);
-    assert.isUndefined(result.kind);
-  }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+      assert.equal(result.editors.includes("file-manager"), true);
+      assert.isUndefined(result.kind);
+    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
 // When interop PowerShell is missing the capability advertises the Linux
 // "files" kind (or nothing), so the reveal must open the Linux file manager
 // the label promised even though plain open still prefers File Explorer.
-it.effect("reveals through the Linux file manager when WSL lacks interop PowerShell", () =>
-  Effect.gen(function* () {
-    const fileSystem = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
-    for (const name of ["explorer.exe", "xdg-open", "xdg-mime"]) {
-      const filePath = path.join(binDir, name);
-      yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
-      yield* fileSystem.chmod(filePath, 0o755);
-    }
+it.effect.skipIf(windowsHost)(
+  "reveals through the Linux file manager when WSL lacks interop PowerShell",
+  () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
+      for (const name of ["explorer.exe", "xdg-open", "xdg-mime"]) {
+        const filePath = path.join(binDir, name);
+        yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
+        yield* fileSystem.chmod(filePath, 0o755);
+      }
 
-    const spawnedCommands: ChildProcess.StandardCommand[] = [];
-    const kind = yield* Effect.gen(function* () {
-      const launcher = yield* ExternalLauncher.ExternalLauncher;
-      const revealKind = yield* launcher.resolveFileManagerRevealKind();
-      yield* launcher.launchEditor({
-        editor: "file-manager",
-        cwd: "/home/t3/workspace/media/clip.mp4",
-        reveal: true,
-      });
-      return revealKind;
-    }).pipe(
-      Effect.provide(
-        testLayer({
-          platform: "linux",
-          env: {
-            PATH: binDir,
-            WSL_DISTRO_NAME: "Ubuntu-24.04",
-            WSL_INTEROP: "/run/WSL/1_interop",
-            DISPLAY: ":0",
-          },
-          onSpawn: (command) => {
-            spawnedCommands.push(command);
-          },
-          spawnResult: (command) =>
-            command.command === "xdg-mime" ? { stdout: "org.gnome.Nautilus.desktop\n" } : undefined,
-        }),
-      ),
-    );
+      const spawnedCommands: ChildProcess.StandardCommand[] = [];
+      const kind = yield* Effect.gen(function* () {
+        const launcher = yield* ExternalLauncher.ExternalLauncher;
+        const revealKind = yield* launcher.resolveFileManagerRevealKind();
+        yield* launcher.launchEditor({
+          editor: "file-manager",
+          cwd: "/home/t3/workspace/media/clip.mp4",
+          reveal: true,
+        });
+        return revealKind;
+      }).pipe(
+        Effect.provide(
+          testLayer({
+            platform: "linux",
+            env: {
+              PATH: binDir,
+              WSL_DISTRO_NAME: "Ubuntu-24.04",
+              WSL_INTEROP: "/run/WSL/1_interop",
+              DISPLAY: ":0",
+            },
+            onSpawn: (command) => {
+              spawnedCommands.push(command);
+            },
+            spawnResult: (command) =>
+              command.command === "xdg-mime"
+                ? { stdout: "org.gnome.Nautilus.desktop\n" }
+                : undefined,
+          }),
+        ),
+      );
 
-    assert.equal(kind, "files");
-    const launch = spawnedCommands.find((command) => command.command === "xdg-open");
-    assert.ok(launch);
-    assert.deepEqual(launch.args, ["/home/t3/workspace/media"]);
-    assert.isUndefined(spawnedCommands.find((command) => command.command === "explorer.exe"));
-  }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+      assert.equal(kind, "files");
+      const launch = spawnedCommands.find((command) => command.command === "xdg-open");
+      assert.ok(launch);
+      assert.deepEqual(launch.args, ["/home/t3/workspace/media"]);
+      assert.isUndefined(spawnedCommands.find((command) => command.command === "explorer.exe"));
+    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
 // Interop can exist without `explorer.exe` on PATH (appendWindowsPath=false)
 // while WSLg still provides a working Linux file manager; the host must keep
 // the Linux open/reveal path instead of losing the editor entirely.
-it.effect("falls back to the Linux file manager when WSL lacks the Explorer bridge", () =>
-  Effect.gen(function* () {
-    const fileSystem = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
-    for (const name of ["xdg-open", "xdg-mime"]) {
-      const filePath = path.join(binDir, name);
-      yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
-      yield* fileSystem.chmod(filePath, 0o755);
-    }
+it.effect.skipIf(windowsHost)(
+  "falls back to the Linux file manager when WSL lacks the Explorer bridge",
+  () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
+      for (const name of ["xdg-open", "xdg-mime"]) {
+        const filePath = path.join(binDir, name);
+        yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
+        yield* fileSystem.chmod(filePath, 0o755);
+      }
 
-    const spawnedCommands: ChildProcess.StandardCommand[] = [];
-    const result = yield* Effect.gen(function* () {
-      const launcher = yield* ExternalLauncher.ExternalLauncher;
-      const editors = yield* launcher.resolveAvailableEditors();
-      const kind = yield* launcher.resolveFileManagerRevealKind();
-      yield* launcher.launchEditor({
-        editor: "file-manager",
-        cwd: "/home/t3/workspace/media/clip.mp4",
-        reveal: true,
-      });
-      return { editors, kind };
-    }).pipe(
-      Effect.provide(
-        testLayer({
-          platform: "linux",
-          env: {
-            PATH: binDir,
-            WSL_DISTRO_NAME: "Ubuntu-24.04",
-            WSL_INTEROP: "/run/WSL/1_interop",
-            DISPLAY: ":0",
-          },
-          onSpawn: (command) => {
-            spawnedCommands.push(command);
-          },
-          spawnResult: (command) =>
-            command.command === "xdg-mime" ? { stdout: "org.gnome.Nautilus.desktop\n" } : undefined,
-        }),
-      ),
-    );
+      const spawnedCommands: ChildProcess.StandardCommand[] = [];
+      const result = yield* Effect.gen(function* () {
+        const launcher = yield* ExternalLauncher.ExternalLauncher;
+        const editors = yield* launcher.resolveAvailableEditors();
+        const kind = yield* launcher.resolveFileManagerRevealKind();
+        yield* launcher.launchEditor({
+          editor: "file-manager",
+          cwd: "/home/t3/workspace/media/clip.mp4",
+          reveal: true,
+        });
+        return { editors, kind };
+      }).pipe(
+        Effect.provide(
+          testLayer({
+            platform: "linux",
+            env: {
+              PATH: binDir,
+              WSL_DISTRO_NAME: "Ubuntu-24.04",
+              WSL_INTEROP: "/run/WSL/1_interop",
+              DISPLAY: ":0",
+            },
+            onSpawn: (command) => {
+              spawnedCommands.push(command);
+            },
+            spawnResult: (command) =>
+              command.command === "xdg-mime"
+                ? { stdout: "org.gnome.Nautilus.desktop\n" }
+                : undefined,
+          }),
+        ),
+      );
 
-    assert.equal(result.editors.includes("file-manager"), true);
-    assert.equal(result.kind, "files");
-    const launch = spawnedCommands.find((command) => command.command === "xdg-open");
-    assert.ok(launch);
-    assert.deepEqual(launch.args, ["/home/t3/workspace/media"]);
-  }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+      assert.equal(result.editors.includes("file-manager"), true);
+      assert.equal(result.kind, "files");
+      const launch = spawnedCommands.find((command) => command.command === "xdg-open");
+      assert.ok(launch);
+      assert.deepEqual(launch.args, ["/home/t3/workspace/media"]);
+    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
-it.effect(
+it.effect.skipIf(windowsHost)(
   "falls back to opening the containing directory for WSL paths Explorer cannot select",
   () =>
     Effect.gen(function* () {
@@ -570,7 +588,7 @@ it.effect(
     }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
-it.effect("reveals by opening the containing directory on Linux", () =>
+it.effect.skipIf(windowsHost)("reveals by opening the containing directory on Linux", () =>
   Effect.gen(function* () {
     const fileSystem = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
@@ -609,127 +627,137 @@ it.effect("reveals by opening the containing directory on Linux", () =>
   }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
-it.effect("does not advertise a Linux file manager without a graphical session", () =>
-  Effect.gen(function* () {
-    const fileSystem = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
-    const xdgOpenPath = path.join(binDir, "xdg-open");
-    yield* fileSystem.writeFileString(xdgOpenPath, "#!/bin/sh\n");
-    yield* fileSystem.chmod(xdgOpenPath, 0o755);
+it.effect.skipIf(windowsHost)(
+  "does not advertise a Linux file manager without a graphical session",
+  () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
+      const xdgOpenPath = path.join(binDir, "xdg-open");
+      yield* fileSystem.writeFileString(xdgOpenPath, "#!/bin/sh\n");
+      yield* fileSystem.chmod(xdgOpenPath, 0o755);
 
-    const editors = yield* Effect.gen(function* () {
-      const launcher = yield* ExternalLauncher.ExternalLauncher;
-      return yield* launcher.resolveAvailableEditors();
-    }).pipe(Effect.provide(testLayer({ platform: "linux", env: { PATH: binDir } })));
+      const editors = yield* Effect.gen(function* () {
+        const launcher = yield* ExternalLauncher.ExternalLauncher;
+        return yield* launcher.resolveAvailableEditors();
+      }).pipe(Effect.provide(testLayer({ platform: "linux", env: { PATH: binDir } })));
 
-    assert.equal(editors.includes("file-manager"), false);
-  }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+      assert.equal(editors.includes("file-manager"), false);
+    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
-it.effect("advertises a Linux file manager when a directory handler is installed", () =>
-  Effect.gen(function* () {
-    const fileSystem = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
-    for (const name of ["xdg-open", "xdg-mime"]) {
-      const filePath = path.join(binDir, name);
-      yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
-      yield* fileSystem.chmod(filePath, 0o755);
-    }
+it.effect.skipIf(windowsHost)(
+  "advertises a Linux file manager when a directory handler is installed",
+  () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
+      for (const name of ["xdg-open", "xdg-mime"]) {
+        const filePath = path.join(binDir, name);
+        yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
+        yield* fileSystem.chmod(filePath, 0o755);
+      }
 
-    let probe: ChildProcess.StandardCommand | undefined;
-    const editors = yield* Effect.gen(function* () {
-      const launcher = yield* ExternalLauncher.ExternalLauncher;
-      return yield* launcher.resolveAvailableEditors();
-    }).pipe(
-      Effect.provide(
-        testLayer({
-          platform: "linux",
-          env: { PATH: binDir, DISPLAY: ":0" },
-          onSpawn: (command) => {
-            probe = command;
-          },
-          spawnResult: (command) =>
-            command.command === "xdg-mime" ? { stdout: "org.gnome.Nautilus.desktop\n" } : undefined,
-        }),
-      ),
-    );
+      let probe: ChildProcess.StandardCommand | undefined;
+      const editors = yield* Effect.gen(function* () {
+        const launcher = yield* ExternalLauncher.ExternalLauncher;
+        return yield* launcher.resolveAvailableEditors();
+      }).pipe(
+        Effect.provide(
+          testLayer({
+            platform: "linux",
+            env: { PATH: binDir, DISPLAY: ":0" },
+            onSpawn: (command) => {
+              probe = command;
+            },
+            spawnResult: (command) =>
+              command.command === "xdg-mime"
+                ? { stdout: "org.gnome.Nautilus.desktop\n" }
+                : undefined,
+          }),
+        ),
+      );
 
-    assert.equal(editors.includes("file-manager"), true);
-    assert.ok(probe);
-    assert.equal(probe.command, "xdg-mime");
-    assert.deepEqual(probe.args, ["query", "default", "inode/directory"]);
-  }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+      assert.equal(editors.includes("file-manager"), true);
+      assert.ok(probe);
+      assert.equal(probe.command, "xdg-mime");
+      assert.deepEqual(probe.args, ["query", "default", "inode/directory"]);
+    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
 // `xdg-open` with a display variable but no `inode/directory` handler exits
 // nonzero after the launch has already detached: without this gate the server
 // advertises a reveal that is a silent no-op.
-it.effect("does not advertise a Linux file manager without a directory handler", () =>
-  Effect.gen(function* () {
-    const fileSystem = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
-    for (const name of ["xdg-open", "xdg-mime"]) {
-      const filePath = path.join(binDir, name);
-      yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
-      yield* fileSystem.chmod(filePath, 0o755);
-    }
+it.effect.skipIf(windowsHost)(
+  "does not advertise a Linux file manager without a directory handler",
+  () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
+      for (const name of ["xdg-open", "xdg-mime"]) {
+        const filePath = path.join(binDir, name);
+        yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
+        yield* fileSystem.chmod(filePath, 0o755);
+      }
 
-    const editors = yield* Effect.gen(function* () {
-      const launcher = yield* ExternalLauncher.ExternalLauncher;
-      return yield* launcher.resolveAvailableEditors();
-    }).pipe(
-      Effect.provide(
-        testLayer({
-          platform: "linux",
-          env: { PATH: binDir, DISPLAY: ":0" },
-          spawnResult: (command) => (command.command === "xdg-mime" ? { stdout: "" } : undefined),
-        }),
-      ),
-    );
+      const editors = yield* Effect.gen(function* () {
+        const launcher = yield* ExternalLauncher.ExternalLauncher;
+        return yield* launcher.resolveAvailableEditors();
+      }).pipe(
+        Effect.provide(
+          testLayer({
+            platform: "linux",
+            env: { PATH: binDir, DISPLAY: ":0" },
+            spawnResult: (command) => (command.command === "xdg-mime" ? { stdout: "" } : undefined),
+          }),
+        ),
+      );
 
-    assert.equal(editors.includes("file-manager"), false);
-  }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+      assert.equal(editors.includes("file-manager"), false);
+    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
-it.effect("does not advertise a Linux file manager when the handler query fails", () =>
-  Effect.gen(function* () {
-    const fileSystem = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
-    for (const name of ["xdg-open", "xdg-mime"]) {
-      const filePath = path.join(binDir, name);
-      yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
-      yield* fileSystem.chmod(filePath, 0o755);
-    }
+it.effect.skipIf(windowsHost)(
+  "does not advertise a Linux file manager when the handler query fails",
+  () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
+      for (const name of ["xdg-open", "xdg-mime"]) {
+        const filePath = path.join(binDir, name);
+        yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
+        yield* fileSystem.chmod(filePath, 0o755);
+      }
 
-    const editors = yield* Effect.gen(function* () {
-      const launcher = yield* ExternalLauncher.ExternalLauncher;
-      return yield* launcher.resolveAvailableEditors();
-    }).pipe(
-      Effect.provide(
-        testLayer({
-          platform: "linux",
-          env: { PATH: binDir, DISPLAY: ":0" },
-          spawnResult: (command) =>
-            command.command === "xdg-mime"
-              ? { exitCode: 47, stdout: "org.gnome.Nautilus.desktop\n" }
-              : undefined,
-        }),
-      ),
-    );
+      const editors = yield* Effect.gen(function* () {
+        const launcher = yield* ExternalLauncher.ExternalLauncher;
+        return yield* launcher.resolveAvailableEditors();
+      }).pipe(
+        Effect.provide(
+          testLayer({
+            platform: "linux",
+            env: { PATH: binDir, DISPLAY: ":0" },
+            spawnResult: (command) =>
+              command.command === "xdg-mime"
+                ? { exitCode: 47, stdout: "org.gnome.Nautilus.desktop\n" }
+                : undefined,
+          }),
+        ),
+      );
 
-    assert.equal(editors.includes("file-manager"), false);
-  }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+      assert.equal(editors.includes("file-manager"), false);
+    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
 // The handler probe carries its own timeout because the editor scan's outer
 // timeout in server.getConfig degrades to an EMPTY editor list: a wedged
 // xdg-mime must cost only the file manager, never the other editors. Runs on
 // the live clock so the probe's real timeout fires.
-it.live("a stalled handler probe drops only the file manager", () =>
+it.live.skipIf(windowsHost)("a stalled handler probe drops only the file manager", () =>
   Effect.gen(function* () {
     const fileSystem = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
@@ -758,22 +786,26 @@ it.live("a stalled handler probe drops only the file manager", () =>
   }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
-it.effect("does not advertise a Linux file manager when xdg-mime is missing", () =>
-  Effect.gen(function* () {
-    const fileSystem = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
-    const xdgOpenPath = path.join(binDir, "xdg-open");
-    yield* fileSystem.writeFileString(xdgOpenPath, "#!/bin/sh\n");
-    yield* fileSystem.chmod(xdgOpenPath, 0o755);
+it.effect.skipIf(windowsHost)(
+  "does not advertise a Linux file manager when xdg-mime is missing",
+  () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
+      const xdgOpenPath = path.join(binDir, "xdg-open");
+      yield* fileSystem.writeFileString(xdgOpenPath, "#!/bin/sh\n");
+      yield* fileSystem.chmod(xdgOpenPath, 0o755);
 
-    const editors = yield* Effect.gen(function* () {
-      const launcher = yield* ExternalLauncher.ExternalLauncher;
-      return yield* launcher.resolveAvailableEditors();
-    }).pipe(Effect.provide(testLayer({ platform: "linux", env: { PATH: binDir, DISPLAY: ":0" } })));
+      const editors = yield* Effect.gen(function* () {
+        const launcher = yield* ExternalLauncher.ExternalLauncher;
+        return yield* launcher.resolveAvailableEditors();
+      }).pipe(
+        Effect.provide(testLayer({ platform: "linux", env: { PATH: binDir, DISPLAY: ":0" } })),
+      );
 
-    assert.equal(editors.includes("file-manager"), false);
-  }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+      assert.equal(editors.includes("file-manager"), false);
+    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
 it.effect("discovers editors through the service API", () =>
diff --git a/apps/server/src/provider/AntigravityInstallation.test.ts b/apps/server/src/provider/AntigravityInstallation.test.ts
index 8d6b62731cfd..8fb3cbb54f73 100644
--- a/apps/server/src/provider/AntigravityInstallation.test.ts
+++ b/apps/server/src/provider/AntigravityInstallation.test.ts
@@ -681,65 +681,69 @@ it.layer(NodeServices.layer)("Antigravity installation", (it) => {
       }),
   );
 
-  it.effect("honors explicit paths and reports invalid overrides without falling back", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-agy-path-test-" });
-      const externalDirectory = path.join(baseDir, "external");
-      const externalExecutable = path.join(externalDirectory, "agy_acp_server.par");
-      const externalHarness = path.join(externalDirectory, "localharness_external");
-      yield* fs.makeDirectory(externalDirectory);
-      yield* fs.writeFileString(externalExecutable, "external server", { mode: 0o755 });
-      yield* fs.writeFileString(externalHarness, "external harness", { mode: 0o755 });
-      const { installation } = yield* makeHarness({
-        baseDir,
-        path: externalDirectory,
-        previous: true,
-      });
-      yield* expectPreviousRelease(installation);
-      expect(yield* installation.resolve(undefined, { PATH: externalDirectory })).toMatchObject({
-        source: "managed",
-        version: previousVersion,
-      });
-      expect(yield* installation.resolve(externalExecutable)).toMatchObject({
-        executablePath: externalExecutable,
-        source: "override",
-        managedVersionDirectory: null,
-      });
-      expect(yield* installation.resolve("agy_acp_server.par")).toMatchObject({
-        source: "override",
-      });
-      yield* fs.remove(externalHarness);
-      expect(yield* installation.resolve(externalExecutable).pipe(Effect.flip)).toMatchObject({
-        operation: "resolve",
-      });
-      expect(
-        yield* installation.resolve(path.join(baseDir, "missing")).pipe(Effect.flip),
-      ).toMatchObject({
-        operation: "resolve",
-      });
-      yield* expectPreviousRelease(installation);
-      yield* fs.writeFileString(externalHarness, "external harness", { mode: 0o755 });
-      yield* installation.remove();
-      expect(yield* installation.resolve()).toMatchObject({
-        source: "path",
-        executablePath: externalExecutable,
-      });
-      const isolated = yield* makeHarness({ baseDir });
-      expect(yield* isolated.installation.resolve().pipe(Effect.flip)).toMatchObject({
-        operation: "resolve",
-      });
-      expect(
-        yield* isolated.installation.resolve(undefined, { PATH: externalDirectory }),
-      ).toMatchObject({
-        source: "path",
-        executablePath: externalExecutable,
-      });
-      expect(
-        yield* isolated.installation.resolve("agy_acp_server.par", { PATH: externalDirectory }),
-      ).toMatchObject({ source: "override", executablePath: externalExecutable });
-    }),
+  // Real posix executables in a real temp dir, resolved by a linux-mocked
+  // PATH walk; a Windows temp path cannot be split on `:`.
+  it.effect.skipIf(HostProcessPlatform.defaultValue() === "win32")(
+    "honors explicit paths and reports invalid overrides without falling back",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-agy-path-test-" });
+        const externalDirectory = path.join(baseDir, "external");
+        const externalExecutable = path.join(externalDirectory, "agy_acp_server.par");
+        const externalHarness = path.join(externalDirectory, "localharness_external");
+        yield* fs.makeDirectory(externalDirectory);
+        yield* fs.writeFileString(externalExecutable, "external server", { mode: 0o755 });
+        yield* fs.writeFileString(externalHarness, "external harness", { mode: 0o755 });
+        const { installation } = yield* makeHarness({
+          baseDir,
+          path: externalDirectory,
+          previous: true,
+        });
+        yield* expectPreviousRelease(installation);
+        expect(yield* installation.resolve(undefined, { PATH: externalDirectory })).toMatchObject({
+          source: "managed",
+          version: previousVersion,
+        });
+        expect(yield* installation.resolve(externalExecutable)).toMatchObject({
+          executablePath: externalExecutable,
+          source: "override",
+          managedVersionDirectory: null,
+        });
+        expect(yield* installation.resolve("agy_acp_server.par")).toMatchObject({
+          source: "override",
+        });
+        yield* fs.remove(externalHarness);
+        expect(yield* installation.resolve(externalExecutable).pipe(Effect.flip)).toMatchObject({
+          operation: "resolve",
+        });
+        expect(
+          yield* installation.resolve(path.join(baseDir, "missing")).pipe(Effect.flip),
+        ).toMatchObject({
+          operation: "resolve",
+        });
+        yield* expectPreviousRelease(installation);
+        yield* fs.writeFileString(externalHarness, "external harness", { mode: 0o755 });
+        yield* installation.remove();
+        expect(yield* installation.resolve()).toMatchObject({
+          source: "path",
+          executablePath: externalExecutable,
+        });
+        const isolated = yield* makeHarness({ baseDir });
+        expect(yield* isolated.installation.resolve().pipe(Effect.flip)).toMatchObject({
+          operation: "resolve",
+        });
+        expect(
+          yield* isolated.installation.resolve(undefined, { PATH: externalDirectory }),
+        ).toMatchObject({
+          source: "path",
+          executablePath: externalExecutable,
+        });
+        expect(
+          yield* isolated.installation.resolve("agy_acp_server.par", { PATH: externalDirectory }),
+        ).toMatchObject({ source: "override", executablePath: externalExecutable });
+      }),
   );
 
   it.effect("keeps leased releases available while new sessions resolve the new release", () =>
diff --git a/apps/server/src/provider/providerMaintenance.test.ts b/apps/server/src/provider/providerMaintenance.test.ts
index 5683da2c1a82..c80b312b1408 100644
--- a/apps/server/src/provider/providerMaintenance.test.ts
+++ b/apps/server/src/provider/providerMaintenance.test.ts
@@ -22,6 +22,10 @@ import {
 } from "./providerMaintenance.ts";
 
 const driver = (value: string) => ProviderDriverKind.make(value);
+// These write `#!/bin/sh` stubs and resolve them through a darwin-mocked
+// PATH walk; a Windows temp path cannot be split on `:`.
+const windowsHost = HostProcessPlatform.defaultValue() === "win32";
+
 const makeTempDir = (name: string) =>
   Crypto.Crypto.pipe(
     Effect.flatMap((crypto) => crypto.randomUUIDv4),
@@ -199,7 +203,7 @@ it.layer(NodeServices.layer)("providerMaintenance", (it) => {
     });
   });
 
-  it.effect(
+  it.effect.skipIf(windowsHost)(
     "switches package-managed providers to vite-plus updates when the resolved binary lives in vite-plus global bin",
     () =>
       Effect.gen(function* () {
@@ -272,7 +276,7 @@ it.layer(NodeServices.layer)("providerMaintenance", (it) => {
       }),
   );
 
-  it.effect(
+  it.effect.skipIf(windowsHost)(
     "switches package-managed providers to pnpm updates when the resolved binary lives in pnpm's global bin",
     () =>
       Effect.gen(function* () {
@@ -332,7 +336,7 @@ it.layer(NodeServices.layer)("providerMaintenance", (it) => {
     });
   });
 
-  it.effect(
+  it.effect.skipIf(windowsHost)(
     "switches native-package-tool to native updates when the binary resolves through the native installer",
     () =>
       Effect.gen(function* () {
@@ -369,7 +373,7 @@ it.layer(NodeServices.layer)("providerMaintenance", (it) => {
       }),
   );
 
-  it.effect(
+  it.effect.skipIf(windowsHost)(
     "switches scoped-package-tool to native upgrades when the binary resolves through the standalone installer",
     () =>
       Effect.gen(function* () {
diff --git a/apps/server/src/resourceTelemetry/ResourceMonitorBinary.test.ts b/apps/server/src/resourceTelemetry/ResourceMonitorBinary.test.ts
index 243556b6e3b0..7fa23aac3908 100644
--- a/apps/server/src/resourceTelemetry/ResourceMonitorBinary.test.ts
+++ b/apps/server/src/resourceTelemetry/ResourceMonitorBinary.test.ts
@@ -11,6 +11,10 @@ import * as FileSystem from "effect/FileSystem";
 import { ServerConfig } from "../config.ts";
 import * as ResourceMonitorBinary from "./ResourceMonitorBinary.ts";
 
+// The override checks POSIX exec bits on a real file under a linux platform
+// mock; NTFS never reports those bits, so the check cannot be satisfied there.
+const windowsHost = HostProcessPlatform.defaultValue() === "win32";
+
 describe("ResourceMonitorBinary", () => {
   afterEach(() => {
     vi.restoreAllMocks();
@@ -42,7 +46,7 @@ describe("ResourceMonitorBinary", () => {
     }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
   );
 
-  it.effect("resolves an executable override", () =>
+  it.effect.skipIf(windowsHost)("resolves an executable override", () =>
     Effect.gen(function* () {
       const fileSystem = yield* FileSystem.FileSystem;
       const baseDir = yield* fileSystem.makeTempDirectoryScoped({
@@ -66,7 +70,7 @@ describe("ResourceMonitorBinary", () => {
     }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
   );
 
-  it.effect("resolves an executable override on an unsupported platform", () =>
+  it.effect.skipIf(windowsHost)("resolves an executable override on an unsupported platform", () =>
     Effect.gen(function* () {
       const fileSystem = yield* FileSystem.FileSystem;
       const baseDir = yield* fileSystem.makeTempDirectoryScoped({

From 30f128fababb1fea46041d228b6ea52733d2ee09 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 13:33:20 -0700
Subject: [PATCH 10/56] test: skip symlink fixtures where the host cannot
 create symlinks (#9566)

Co-authored-by: Claude Code <noreply@anthropic.com>
---
 .../BrowserImport/BrowserImport.test.ts       |  45 +-
 .../src/preview/BrowserImport/Sources.test.ts | 197 ++++----
 apps/server/scripts/t3-sqlite-state.test.ts   |  79 ++--
 apps/server/src/assets/AssetAccess.test.ts    | 422 ++++++++++--------
 apps/server/src/cli/theme.test.ts             |  83 ++--
 apps/server/src/entrypoint.test.ts            |  32 +-
 apps/server/src/environmentTheme.test.ts      |   3 +-
 .../orchestration/workflowScriptQuery.test.ts |  55 ++-
 .../Drivers/AntigravitySkills.test.ts         |  43 +-
 .../provider/Drivers/CodexHomeLayout.test.ts  | 312 ++++++-------
 .../provider/Layers/OpenCodeAdapter.test.ts   |  51 ++-
 .../src/provider/providerMaintenance.test.ts  | 185 ++++----
 apps/server/src/server.test.ts                |   3 +-
 .../sourceControl/PrTemplateDetection.test.ts | 153 ++++---
 .../src/vcs/VcsStatusBroadcaster.test.ts      | 122 ++---
 .../src/workspace/WorkspaceFileSystem.test.ts |  59 +--
 packages/shared/package.json                  |   4 +
 packages/shared/src/testing/symlinks.ts       |  29 ++
 scripts/build-desktop-artifact.test.ts        |   3 +-
 scripts/mock-update-server.test.ts            |  57 +--
 20 files changed, 1035 insertions(+), 902 deletions(-)
 create mode 100644 packages/shared/src/testing/symlinks.ts

diff --git a/apps/desktop/src/preview/BrowserImport/BrowserImport.test.ts b/apps/desktop/src/preview/BrowserImport/BrowserImport.test.ts
index 9b0a652f09f1..003461085376 100644
--- a/apps/desktop/src/preview/BrowserImport/BrowserImport.test.ts
+++ b/apps/desktop/src/preview/BrowserImport/BrowserImport.test.ts
@@ -14,6 +14,7 @@ import * as Ref from "effect/Ref";
 import * as BrowserSession from "../BrowserSession.ts";
 import * as BrowserImport from "./BrowserImport.ts";
 import { BROWSER_IMPORT_SOURCES, sourcePathContext } from "./Sources.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const helium = BROWSER_IMPORT_SOURCES.find((source) => source.id === "helium")!;
 
@@ -105,28 +106,30 @@ describe("BrowserImport.importCookies", () => {
     }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
   );
 
-  it.effect("refuses to import while the source browser holds its profile", () =>
-    Effect.gen(function* () {
-      const fileSystem = yield* FileSystem.FileSystem;
-      const { importer, root } = yield* withImporter();
-      // The lock Chromium leaves while it is running, dangling target and
-      // all. This must stop the import before it ever asks the keychain.
-      yield* fileSystem.symlink("host-that-does-not-exist-1234", `${root}/SingletonLock`);
-
-      const error = yield* importer
-        .importCookies({
-          input: {
-            sourceId: "helium",
-            sourceProfileDirectory: "Default",
-            targetProfileId: "default",
-          },
-          scope: "persist:t3code-preview-test",
-          persistent: true,
-        })
-        .pipe(Effect.flip);
+  it.effect.skipIf(!symlinksSupported)(
+    "refuses to import while the source browser holds its profile",
+    () =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const { importer, root } = yield* withImporter();
+        // The lock Chromium leaves while it is running, dangling target and
+        // all. This must stop the import before it ever asks the keychain.
+        yield* fileSystem.symlink("host-that-does-not-exist-1234", `${root}/SingletonLock`);
+
+        const error = yield* importer
+          .importCookies({
+            input: {
+              sourceId: "helium",
+              sourceProfileDirectory: "Default",
+              targetProfileId: "default",
+            },
+            scope: "persist:t3code-preview-test",
+            persistent: true,
+          })
+          .pipe(Effect.flip);
 
-      assert.equal(error.reason, "browserRunning");
-    }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
+        assert.equal(error.reason, "browserRunning");
+      }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
   );
 });
 
diff --git a/apps/desktop/src/preview/BrowserImport/Sources.test.ts b/apps/desktop/src/preview/BrowserImport/Sources.test.ts
index feaac842cbef..282bf10d36d3 100644
--- a/apps/desktop/src/preview/BrowserImport/Sources.test.ts
+++ b/apps/desktop/src/preview/BrowserImport/Sources.test.ts
@@ -32,6 +32,7 @@ import {
   sourcePathContext,
   windowsChromiumCookiesAreHeld,
 } from "./Sources.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const helium = BROWSER_IMPORT_SOURCES.find((source) => source.id === "helium")!;
 
@@ -125,7 +126,7 @@ const writeFirefoxCookieDatabase = (
   });
 
 describe("Helium on Linux", () => {
-  it.effect("discovers its profiles and checks the user-data lock", () =>
+  it.effect.skipIf(!symlinksSupported)("discovers its profiles and checks the user-data lock", () =>
     run(
       Effect.gen(function* () {
         const fileSystem = yield* FileSystem.FileSystem;
@@ -221,48 +222,52 @@ describe("isSourceRunning", () => {
     ),
   );
 
-  it.effect("reads Chromium's dangling SingletonLock symlink as a running browser", () =>
-    run(
-      Effect.gen(function* () {
-        const fileSystem = yield* FileSystem.FileSystem;
-        const context = yield* withSourceHome();
-        assert.isFalse(yield* isSourceRunning(helium, context));
-
-        // Chromium points the lock at `<host>-<pid>`, a target that never
-        // exists on disk. A check that follows the link reports a running
-        // browser as closed, letting an import read a live, mid-write database.
-        yield* fileSystem.symlink(
-          "host-that-does-not-exist-1234",
-          `${userDataDirectory(context)}/SingletonLock`,
-        );
+  it.effect.skipIf(!symlinksSupported)(
+    "reads Chromium's dangling SingletonLock symlink as a running browser",
+    () =>
+      run(
+        Effect.gen(function* () {
+          const fileSystem = yield* FileSystem.FileSystem;
+          const context = yield* withSourceHome();
+          assert.isFalse(yield* isSourceRunning(helium, context));
+
+          // Chromium points the lock at `<host>-<pid>`, a target that never
+          // exists on disk. A check that follows the link reports a running
+          // browser as closed, letting an import read a live, mid-write database.
+          yield* fileSystem.symlink(
+            "host-that-does-not-exist-1234",
+            `${userDataDirectory(context)}/SingletonLock`,
+          );
 
-        assert.isTrue(yield* isSourceRunning(helium, context));
-      }),
-    ),
+          assert.isTrue(yield* isSourceRunning(helium, context));
+        }),
+      ),
   );
 
-  it.effect("uses the provided hostname to classify Chromium locks", () =>
-    run(
-      Effect.gen(function* () {
-        const fileSystem = yield* FileSystem.FileSystem;
-        const paths = yield* withSourceHome();
-        yield* fileSystem.symlink(
-          "lock-owner-99999999",
-          `${helium.userDataDirectory(paths)}/SingletonLock`,
-        );
+  it.effect.skipIf(!symlinksSupported)(
+    "uses the provided hostname to classify Chromium locks",
+    () =>
+      run(
+        Effect.gen(function* () {
+          const fileSystem = yield* FileSystem.FileSystem;
+          const paths = yield* withSourceHome();
+          yield* fileSystem.symlink(
+            "lock-owner-99999999",
+            `${helium.userDataDirectory(paths)}/SingletonLock`,
+          );
 
-        assert.isTrue(
-          yield* isSourceRunning(helium, paths).pipe(
-            Effect.provideService(HostProcessHostname, "another-host"),
-          ),
-        );
-        assert.isFalse(
-          yield* isSourceRunning(helium, paths).pipe(
-            Effect.provideService(HostProcessHostname, "lock-owner"),
-          ),
-        );
-      }),
-    ),
+          assert.isTrue(
+            yield* isSourceRunning(helium, paths).pipe(
+              Effect.provideService(HostProcessHostname, "another-host"),
+            ),
+          );
+          assert.isFalse(
+            yield* isSourceRunning(helium, paths).pipe(
+              Effect.provideService(HostProcessHostname, "lock-owner"),
+            ),
+          );
+        }),
+      ),
   );
 });
 
@@ -385,25 +390,27 @@ describe("isSourceInstalled", () => {
     ),
   );
 
-  it.effect("follows cookie database symlinks when detecting profiles", () =>
-    run(
-      Effect.gen(function* () {
-        const fileSystem = yield* FileSystem.FileSystem;
-        const context = yield* withSourceHome();
-        const root = userDataDirectory(context);
-        yield* fileSystem.makeDirectory(`${root}/Default`, { recursive: true });
-        yield* fileSystem.symlink("missing-cookies", `${root}/Default/Cookies`);
+  it.effect.skipIf(!symlinksSupported)(
+    "follows cookie database symlinks when detecting profiles",
+    () =>
+      run(
+        Effect.gen(function* () {
+          const fileSystem = yield* FileSystem.FileSystem;
+          const context = yield* withSourceHome();
+          const root = userDataDirectory(context);
+          yield* fileSystem.makeDirectory(`${root}/Default`, { recursive: true });
+          yield* fileSystem.symlink("missing-cookies", `${root}/Default/Cookies`);
 
-        assert.deepEqual(yield* listSourceProfiles(helium, context), []);
-        assert.isFalse(yield* isSourceInstalled(helium, context));
+          assert.deepEqual(yield* listSourceProfiles(helium, context), []);
+          assert.isFalse(yield* isSourceInstalled(helium, context));
 
-        yield* fileSystem.writeFileString(`${root}/Default/missing-cookies`, "db");
-        assert.deepEqual(yield* listSourceProfiles(helium, context), [
-          { directory: "Default", name: "Default" },
-        ]);
-        assert.isTrue(yield* isSourceInstalled(helium, context));
-      }),
-    ),
+          yield* fileSystem.writeFileString(`${root}/Default/missing-cookies`, "db");
+          assert.deepEqual(yield* listSourceProfiles(helium, context), [
+            { directory: "Default", name: "Default" },
+          ]);
+          assert.isTrue(yield* isSourceInstalled(helium, context));
+        }),
+      ),
   );
 });
 
@@ -660,44 +667,48 @@ describe("cookieDatabaseCandidatePaths", () => {
 const firefox = BROWSER_IMPORT_SOURCES.find((source) => source.id === "firefox")!;
 
 describe("Firefox Snap profiles", () => {
-  it.effect("finds Snap profiles with or without profiles.ini and checks their locks", () =>
-    run(
-      Effect.gen(function* () {
-        const fileSystem = yield* FileSystem.FileSystem;
-        const home = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3code-firefox-snap-" });
-        const context = yield* sourcePathContext.pipe(
-          Effect.provideService(HostProcessEnvironment, { HOME: home }),
-          Effect.provideService(HostProcessPlatform, "linux"),
-        );
-        const root = `${home}/snap/firefox/common/.mozilla/firefox`;
-        const directory = `${root}/abcd.default`;
-        yield* fileSystem.makeDirectory(directory, { recursive: true });
-        yield* writeFirefoxCookieDatabase(`${directory}/cookies.sqlite`, 2, 1);
-        yield* fileSystem.writeFileString(
-          `${root}/profiles.ini`,
-          "[Profile0]\nName=Personal\nIsRelative=1\nPath=abcd.default\n",
-        );
+  it.effect.skipIf(!symlinksSupported)(
+    "finds Snap profiles with or without profiles.ini and checks their locks",
+    () =>
+      run(
+        Effect.gen(function* () {
+          const fileSystem = yield* FileSystem.FileSystem;
+          const home = yield* fileSystem.makeTempDirectoryScoped({
+            prefix: "t3code-firefox-snap-",
+          });
+          const context = yield* sourcePathContext.pipe(
+            Effect.provideService(HostProcessEnvironment, { HOME: home }),
+            Effect.provideService(HostProcessPlatform, "linux"),
+          );
+          const root = `${home}/snap/firefox/common/.mozilla/firefox`;
+          const directory = `${root}/abcd.default`;
+          yield* fileSystem.makeDirectory(directory, { recursive: true });
+          yield* writeFirefoxCookieDatabase(`${directory}/cookies.sqlite`, 2, 1);
+          yield* fileSystem.writeFileString(
+            `${root}/profiles.ini`,
+            "[Profile0]\nName=Personal\nIsRelative=1\nPath=abcd.default\n",
+          );
 
-        assert.isTrue(yield* isSourceInstalled(firefox, context));
-        assert.deepEqual(yield* listSourceProfiles(firefox, context), [
-          { directory, name: "Personal", cookieCount: 2 },
-        ]);
-        assert.equal(
-          yield* resolveCookieDatabase(firefox, context, directory),
-          `${directory}/cookies.sqlite`,
-        );
-        assert.isFalse(yield* isSourceRunning(firefox, context));
-        yield* fileSystem.symlink("foreign-host:+4242", `${directory}/lock`);
-        assert.isTrue(yield* isSourceRunning(firefox, context));
-        yield* fileSystem.remove(`${directory}/lock`);
-        assert.isFalse(yield* isSourceRunning(firefox, context));
+          assert.isTrue(yield* isSourceInstalled(firefox, context));
+          assert.deepEqual(yield* listSourceProfiles(firefox, context), [
+            { directory, name: "Personal", cookieCount: 2 },
+          ]);
+          assert.equal(
+            yield* resolveCookieDatabase(firefox, context, directory),
+            `${directory}/cookies.sqlite`,
+          );
+          assert.isFalse(yield* isSourceRunning(firefox, context));
+          yield* fileSystem.symlink("foreign-host:+4242", `${directory}/lock`);
+          assert.isTrue(yield* isSourceRunning(firefox, context));
+          yield* fileSystem.remove(`${directory}/lock`);
+          assert.isFalse(yield* isSourceRunning(firefox, context));
 
-        yield* fileSystem.remove(`${root}/profiles.ini`);
-        assert.deepEqual(yield* listSourceProfiles(firefox, context), [
-          { directory, name: "abcd.default", cookieCount: 2 },
-        ]);
-      }),
-    ),
+          yield* fileSystem.remove(`${root}/profiles.ini`);
+          assert.deepEqual(yield* listSourceProfiles(firefox, context), [
+            { directory, name: "abcd.default", cookieCount: 2 },
+          ]);
+        }),
+      ),
   );
 
   it.effect("keeps matching profile names in native and Snap installs distinct", () =>
@@ -862,7 +873,7 @@ describe("listSourceProfiles Firefox fallback", () => {
 });
 
 describe("isSourceRunning for Firefox", () => {
-  it.effect("finds the lock inside the profile, not at the root", () =>
+  it.effect.skipIf(!symlinksSupported)("finds the lock inside the profile, not at the root", () =>
     run(
       Effect.gen(function* () {
         const fileSystem = yield* FileSystem.FileSystem;
diff --git a/apps/server/scripts/t3-sqlite-state.test.ts b/apps/server/scripts/t3-sqlite-state.test.ts
index ec236f4a67c0..71e592fafbd7 100644
--- a/apps/server/scripts/t3-sqlite-state.test.ts
+++ b/apps/server/scripts/t3-sqlite-state.test.ts
@@ -7,6 +7,7 @@ import * as SqlClient from "effect/unstable/sql/SqlClient";
 
 import * as NodeSqliteClient from "@t3tools/shared/nodeSqliteClient";
 import { runSqliteState } from "./t3-sqlite-state.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const createFixtureDatabase = Effect.fn("createSqliteStateFixtureDatabase")(function* (
   baseDir: string,
@@ -73,47 +74,49 @@ it.layer(NodeServices.layer)("t3-sqlite-state", (it) => {
     }),
   );
 
-  it.effect("backs up isolated state before writes and refuses the shared home", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-sqlite-state-exec-" });
-      yield* createFixtureDatabase(baseDir);
+  it.effect.skipIf(!symlinksSupported)(
+    "backs up isolated state before writes and refuses the shared home",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-sqlite-state-exec-" });
+        yield* createFixtureDatabase(baseDir);
 
-      const mutation = yield* runSqliteState({
-        operation: "exec",
-        baseDir,
-        sql: "INSERT INTO fixtures (id, label) VALUES (2, 'seeded')",
-      });
-      assert.equal(mutation.operation, "exec");
-      if (mutation.operation === "exec") {
-        assert.equal((yield* fs.stat(mutation.backup)).mode & 0o777, 0o600);
-      }
-
-      const error = yield* runSqliteState(
-        {
+        const mutation = yield* runSqliteState({
           operation: "exec",
           baseDir,
-          sql: "DELETE FROM fixtures",
-        },
-        { sharedHome: baseDir },
-      ).pipe(Effect.flip);
-      assert.equal(error._tag, "SqliteStateSharedHomeMutationError");
+          sql: "INSERT INTO fixtures (id, label) VALUES (2, 'seeded')",
+        });
+        assert.equal(mutation.operation, "exec");
+        if (mutation.operation === "exec") {
+          assert.equal((yield* fs.stat(mutation.backup)).mode & 0o777, 0o600);
+        }
 
-      const aliasParent = yield* fs.makeTempDirectoryScoped({
-        prefix: "t3-sqlite-state-alias-",
-      });
-      const aliasBaseDir = path.join(aliasParent, "shared-home-alias");
-      yield* fs.symlink(baseDir, aliasBaseDir);
-      const aliasError = yield* runSqliteState(
-        {
-          operation: "exec",
-          baseDir: aliasBaseDir,
-          sql: "DELETE FROM fixtures",
-        },
-        { sharedHome: baseDir },
-      ).pipe(Effect.flip);
-      assert.equal(aliasError._tag, "SqliteStateSharedHomeMutationError");
-    }),
+        const error = yield* runSqliteState(
+          {
+            operation: "exec",
+            baseDir,
+            sql: "DELETE FROM fixtures",
+          },
+          { sharedHome: baseDir },
+        ).pipe(Effect.flip);
+        assert.equal(error._tag, "SqliteStateSharedHomeMutationError");
+
+        const aliasParent = yield* fs.makeTempDirectoryScoped({
+          prefix: "t3-sqlite-state-alias-",
+        });
+        const aliasBaseDir = path.join(aliasParent, "shared-home-alias");
+        yield* fs.symlink(baseDir, aliasBaseDir);
+        const aliasError = yield* runSqliteState(
+          {
+            operation: "exec",
+            baseDir: aliasBaseDir,
+            sql: "DELETE FROM fixtures",
+          },
+          { sharedHome: baseDir },
+        ).pipe(Effect.flip);
+        assert.equal(aliasError._tag, "SqliteStateSharedHomeMutationError");
+      }),
   );
 });
diff --git a/apps/server/src/assets/AssetAccess.test.ts b/apps/server/src/assets/AssetAccess.test.ts
index 251a4761705d..aacd37b2b35e 100644
--- a/apps/server/src/assets/AssetAccess.test.ts
+++ b/apps/server/src/assets/AssetAccess.test.ts
@@ -24,6 +24,7 @@ import { assetFileResponse } from "../http.ts";
 import { ASSET_ROUTE_PREFIX, issueAssetUrl, resolveAsset } from "./AssetAccess.ts";
 import * as NativeAppIconResolver from "./NativeAppIconResolver.ts";
 import { openMediaFile } from "./MediaFile.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 vi.mock("node:fs/promises", async (importOriginal) => {
   const actual = await importOriginal<typeof NodeFSP>();
@@ -108,216 +109,241 @@ describe("AssetAccess", () => {
     }).pipe(Effect.provide(testLayer)),
   );
 
-  it.effect("rejects non-previewable files, disguised targets, and directories", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-validation-" });
-      for (const name of ["report.md", "secret.txt", "secret.%70ng", "secret.png#private.txt"]) {
-        const filePath = path.join(root, name);
-        yield* fs.writeFileString(filePath, "not media");
-        const error = yield* issueAssetUrl({
-          resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: filePath },
+  it.effect.skipIf(!symlinksSupported)(
+    "rejects non-previewable files, disguised targets, and directories",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-validation-" });
+        for (const name of ["report.md", "secret.txt", "secret.%70ng", "secret.png#private.txt"]) {
+          const filePath = path.join(root, name);
+          yield* fs.writeFileString(filePath, "not media");
+          const error = yield* issueAssetUrl({
+            resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: filePath },
+          }).pipe(Effect.flip);
+          expect(error).toBeInstanceOf(AssetPreviewTypeValidationError);
+        }
+        const disguisedPath = path.join(root, "disguised.png");
+        yield* fs.symlink(path.join(root, "secret.txt"), disguisedPath);
+        const disguisedError = yield* issueAssetUrl({
+          resource: {
+            _tag: "media-file",
+            threadId: ThreadId.make("thread-1"),
+            path: disguisedPath,
+          },
         }).pipe(Effect.flip);
-        expect(error).toBeInstanceOf(AssetPreviewTypeValidationError);
-      }
-      const disguisedPath = path.join(root, "disguised.png");
-      yield* fs.symlink(path.join(root, "secret.txt"), disguisedPath);
-      const disguisedError = yield* issueAssetUrl({
-        resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: disguisedPath },
-      }).pipe(Effect.flip);
-      expect(disguisedError).toBeInstanceOf(AssetPreviewTypeValidationError);
-      const directoryPath = path.join(root, "directory.png");
-      yield* fs.makeDirectory(directoryPath);
-      const directoryError = yield* issueAssetUrl({
-        resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: directoryPath },
-      }).pipe(Effect.flip);
-      expect(directoryError._tag).toBe("AssetWorkspaceAssetNotFoundError");
-    }).pipe(Effect.provide(testLayer)),
-  );
-
-  it.effect("binds media URLs to the canonical target and rejects symlink substitution", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-symlink-" });
-      const filePath = path.join(root, "actual.svg");
-      const aliasPath = path.join(root, "alias.png");
-      const replacementPath = path.join(root, "other.svg");
-      yield* fs.writeFileString(filePath, "<svg/>");
-      yield* fs.writeFileString(replacementPath, "<svg>private</svg>");
-      yield* fs.symlink(filePath, aliasPath);
-      const canonicalFile = yield* fs.realPath(filePath);
-      const result = yield* issueAssetUrl({
-        resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: aliasPath },
-      });
-      const suffix = result.relativeUrl.slice(`${ASSET_ROUTE_PREFIX}/`.length);
-      const separator = suffix.indexOf("/");
-      const token = suffix.slice(0, separator);
-      const name = suffix.slice(separator + 1);
-      const expected = { kind: "file", path: canonicalFile, mimeType: "image/svg+xml" };
-      expect(yield* resolveAsset(token, name)).toMatchObject(expected);
-      yield* fs.remove(aliasPath);
-      yield* fs.symlink(replacementPath, aliasPath);
-      expect(yield* resolveAsset(token, name)).toMatchObject(expected);
-      yield* fs.remove(filePath);
-      yield* fs.symlink(replacementPath, filePath);
-      expect(yield* resolveAsset(token, name)).toBeNull();
-    }).pipe(Effect.provide(testLayer)),
+        expect(disguisedError).toBeInstanceOf(AssetPreviewTypeValidationError);
+        const directoryPath = path.join(root, "directory.png");
+        yield* fs.makeDirectory(directoryPath);
+        const directoryError = yield* issueAssetUrl({
+          resource: {
+            _tag: "media-file",
+            threadId: ThreadId.make("thread-1"),
+            path: directoryPath,
+          },
+        }).pipe(Effect.flip);
+        expect(directoryError._tag).toBe("AssetWorkspaceAssetNotFoundError");
+      }).pipe(Effect.provide(testLayer)),
   );
 
-  it.effect("keeps full and partial responses bound to the file opened during resolution", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-open-file-" });
-      const filePath = path.join(root, "recording.mp4");
-      const savedPath = path.join(root, "saved.mp4");
-      const secretPath = path.join(root, "secret.txt");
-      yield* fs.writeFileString(filePath, "0123456789");
-      yield* fs.writeFileString(secretPath, "private information");
-      const result = yield* issueAssetUrl({
-        resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: filePath },
-      });
-      const suffix = result.relativeUrl.slice(`${ASSET_ROUTE_PREFIX}/`.length);
-      const separator = suffix.indexOf("/");
-      for (const [range, expected, status] of [
-        [undefined, "0123456789", 200],
-        ["bytes=2-5", "2345", 206],
-      ] as const) {
-        const asset = yield* resolveAsset(suffix.slice(0, separator), suffix.slice(separator + 1));
-        if (!asset) throw new Error("Expected a resolved media file");
-
-        yield* fs.rename(filePath, savedPath);
-        yield* fs.symlink(secretPath, filePath);
-        const response = HttpServerResponse.toWeb(yield* assetFileResponse(asset, range));
-        expect(response.status).toBe(status);
-        expect(response.headers.get("content-length")).toBe(String(expected.length));
-        expect(yield* Effect.promise(() => response.text())).toBe(expected);
+  it.effect.skipIf(!symlinksSupported)(
+    "binds media URLs to the canonical target and rejects symlink substitution",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-symlink-" });
+        const filePath = path.join(root, "actual.svg");
+        const aliasPath = path.join(root, "alias.png");
+        const replacementPath = path.join(root, "other.svg");
+        yield* fs.writeFileString(filePath, "<svg/>");
+        yield* fs.writeFileString(replacementPath, "<svg>private</svg>");
+        yield* fs.symlink(filePath, aliasPath);
+        const canonicalFile = yield* fs.realPath(filePath);
+        const result = yield* issueAssetUrl({
+          resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: aliasPath },
+        });
+        const suffix = result.relativeUrl.slice(`${ASSET_ROUTE_PREFIX}/`.length);
+        const separator = suffix.indexOf("/");
+        const token = suffix.slice(0, separator);
+        const name = suffix.slice(separator + 1);
+        const expected = { kind: "file", path: canonicalFile, mimeType: "image/svg+xml" };
+        expect(yield* resolveAsset(token, name)).toMatchObject(expected);
+        yield* fs.remove(aliasPath);
+        yield* fs.symlink(replacementPath, aliasPath);
+        expect(yield* resolveAsset(token, name)).toMatchObject(expected);
         yield* fs.remove(filePath);
-        yield* fs.rename(savedPath, filePath);
-      }
-    }).pipe(Effect.provide(testLayer)),
+        yield* fs.symlink(replacementPath, filePath);
+        expect(yield* resolveAsset(token, name)).toBeNull();
+      }).pipe(Effect.provide(testLayer)),
   );
 
-  it.effect("rejects a symlink swapped in after canonical validation but before open", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-open-race-" });
-      const filePath = path.join(root, "recording.mp4");
-      const secretPath = path.join(root, "secret.txt");
-      yield* fs.writeFileString(filePath, "video");
-      yield* fs.writeFileString(secretPath, "secret");
-      const canonicalPath = yield* fs.realPath(filePath);
-      const result = yield* issueAssetUrl({
-        resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: filePath },
-      });
-      const suffix = result.relativeUrl.slice(`${ASSET_ROUTE_PREFIX}/`.length);
-      const separator = suffix.indexOf("/");
-      const swappingFileSystem = FileSystem.FileSystem.of({
-        ...fs,
-        stat: Effect.fn(function* (requestedPath) {
-          const info = yield* fs.stat(requestedPath);
-          if (requestedPath === canonicalPath) {
-            yield* fs.remove(filePath);
-            yield* fs.symlink(secretPath, filePath);
-          }
-          return info;
-        }),
-      });
-      expect(
-        yield* resolveAsset(suffix.slice(0, separator), suffix.slice(separator + 1)).pipe(
-          Effect.provideService(FileSystem.FileSystem, swappingFileSystem),
-        ),
-      ).toBeNull();
-    }).pipe(Effect.provide(testLayer)),
+  it.effect.skipIf(!symlinksSupported)(
+    "keeps full and partial responses bound to the file opened during resolution",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-open-file-" });
+        const filePath = path.join(root, "recording.mp4");
+        const savedPath = path.join(root, "saved.mp4");
+        const secretPath = path.join(root, "secret.txt");
+        yield* fs.writeFileString(filePath, "0123456789");
+        yield* fs.writeFileString(secretPath, "private information");
+        const result = yield* issueAssetUrl({
+          resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: filePath },
+        });
+        const suffix = result.relativeUrl.slice(`${ASSET_ROUTE_PREFIX}/`.length);
+        const separator = suffix.indexOf("/");
+        for (const [range, expected, status] of [
+          [undefined, "0123456789", 200],
+          ["bytes=2-5", "2345", 206],
+        ] as const) {
+          const asset = yield* resolveAsset(
+            suffix.slice(0, separator),
+            suffix.slice(separator + 1),
+          );
+          if (!asset) throw new Error("Expected a resolved media file");
+
+          yield* fs.rename(filePath, savedPath);
+          yield* fs.symlink(secretPath, filePath);
+          const response = HttpServerResponse.toWeb(yield* assetFileResponse(asset, range));
+          expect(response.status).toBe(status);
+          expect(response.headers.get("content-length")).toBe(String(expected.length));
+          expect(yield* Effect.promise(() => response.text())).toBe(expected);
+          yield* fs.remove(filePath);
+          yield* fs.rename(savedPath, filePath);
+        }
+      }).pipe(Effect.provide(testLayer)),
   );
 
-  it.effect("closes a descriptor rejected when its path changes during open", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-open-rejected-" });
-      const filePath = path.join(root, "recording.mp4");
-      const secretPath = path.join(root, "secret.txt");
-      yield* fs.writeFileString(filePath, "video");
-      yield* fs.writeFileString(secretPath, "secret");
-      const canonicalPath = yield* fs.realPath(filePath);
-      const originalOpen = (yield* Effect.promise(() =>
-        vi.importActual<typeof NodeFSP>("node:fs/promises"),
-      )).open;
-      let opened: NodeFSP.FileHandle | undefined;
-      const openSpy = vi.mocked(NodeFSP.open).mockImplementation(async (target, flags, mode) => {
-        const handle = await originalOpen(target, flags, mode);
-        if (target === canonicalPath) {
-          opened = handle;
-          await NodeFSP.unlink(filePath);
-          await NodeFSP.symlink(secretPath, filePath);
-        }
-        return handle;
-      });
-      yield* Effect.addFinalizer(() => Effect.sync(() => openSpy.mockImplementation(originalOpen)));
-      expect(yield* openMediaFile(canonicalPath)).toBeNull();
-      expect(opened).toBeDefined();
-      expect(opened?.fd).toBe(-1);
-    }).pipe(Effect.provide(testLayer)),
+  it.effect.skipIf(!symlinksSupported)(
+    "rejects a symlink swapped in after canonical validation but before open",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-open-race-" });
+        const filePath = path.join(root, "recording.mp4");
+        const secretPath = path.join(root, "secret.txt");
+        yield* fs.writeFileString(filePath, "video");
+        yield* fs.writeFileString(secretPath, "secret");
+        const canonicalPath = yield* fs.realPath(filePath);
+        const result = yield* issueAssetUrl({
+          resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: filePath },
+        });
+        const suffix = result.relativeUrl.slice(`${ASSET_ROUTE_PREFIX}/`.length);
+        const separator = suffix.indexOf("/");
+        const swappingFileSystem = FileSystem.FileSystem.of({
+          ...fs,
+          stat: Effect.fn(function* (requestedPath) {
+            const info = yield* fs.stat(requestedPath);
+            if (requestedPath === canonicalPath) {
+              yield* fs.remove(filePath);
+              yield* fs.symlink(secretPath, filePath);
+            }
+            return info;
+          }),
+        });
+        expect(
+          yield* resolveAsset(suffix.slice(0, separator), suffix.slice(separator + 1)).pipe(
+            Effect.provideService(FileSystem.FileSystem, swappingFileSystem),
+          ),
+        ).toBeNull();
+      }).pipe(Effect.provide(testLayer)),
   );
 
-  it.effect("rejects an ancestor symlink race even when canonical path rechecks would pass", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-parent-race-" });
-      const publicDirectory = path.join(root, "public");
-      const privateDirectory = path.join(root, "private");
-      yield* fs.makeDirectory(publicDirectory);
-      yield* fs.makeDirectory(privateDirectory);
-      const filePath = path.join(publicDirectory, "recording.mp4");
-      yield* fs.writeFileString(filePath, "public video");
-      yield* fs.writeFileString(path.join(privateDirectory, "recording.mp4"), "private video");
-      const canonicalPath = yield* fs.realPath(filePath);
-      const result = yield* issueAssetUrl({
-        resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: filePath },
-      });
-      const suffix = result.relativeUrl.slice(`${ASSET_ROUTE_PREFIX}/`.length);
-      const separator = suffix.indexOf("/");
-      const native = yield* Effect.promise(() =>
-        vi.importActual<typeof NodeFSP>("node:fs/promises"),
-      );
-      const savedDirectory = path.join(root, "saved");
-      const realpathSpy = vi.mocked(NodeFSP.realpath).mockImplementationOnce(async () => {
-        // A pathname-only guard can see the original parents during realpath,
-        // but the private file during both lstat calls and open.
-        await native.unlink(publicDirectory);
-        await native.rename(savedDirectory, publicDirectory);
-        const canonical = await native.realpath(canonicalPath);
-        await native.rename(publicDirectory, savedDirectory);
-        await native.symlink(privateDirectory, publicDirectory, "junction");
-        return canonical;
-      });
-      yield* Effect.addFinalizer(() =>
-        Effect.sync(() => realpathSpy.mockReset().mockImplementation(native.realpath)),
-      );
-      const swappingFileSystem = FileSystem.FileSystem.of({
-        ...fs,
-        realPath: Effect.fn(function* (requestedPath) {
-          const canonical = yield* fs.realPath(requestedPath);
-          if (requestedPath === canonicalPath) {
-            yield* fs.rename(publicDirectory, savedDirectory);
-            yield* Effect.promise(() =>
-              NodeFSP.symlink(privateDirectory, publicDirectory, "junction"),
-            );
+  it.effect.skipIf(!symlinksSupported)(
+    "closes a descriptor rejected when its path changes during open",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-open-rejected-" });
+        const filePath = path.join(root, "recording.mp4");
+        const secretPath = path.join(root, "secret.txt");
+        yield* fs.writeFileString(filePath, "video");
+        yield* fs.writeFileString(secretPath, "secret");
+        const canonicalPath = yield* fs.realPath(filePath);
+        const originalOpen = (yield* Effect.promise(() =>
+          vi.importActual<typeof NodeFSP>("node:fs/promises"),
+        )).open;
+        let opened: NodeFSP.FileHandle | undefined;
+        const openSpy = vi.mocked(NodeFSP.open).mockImplementation(async (target, flags, mode) => {
+          const handle = await originalOpen(target, flags, mode);
+          if (target === canonicalPath) {
+            opened = handle;
+            await NodeFSP.unlink(filePath);
+            await NodeFSP.symlink(secretPath, filePath);
           }
+          return handle;
+        });
+        yield* Effect.addFinalizer(() =>
+          Effect.sync(() => openSpy.mockImplementation(originalOpen)),
+        );
+        expect(yield* openMediaFile(canonicalPath)).toBeNull();
+        expect(opened).toBeDefined();
+        expect(opened?.fd).toBe(-1);
+      }).pipe(Effect.provide(testLayer)),
+  );
+
+  it.effect.skipIf(!symlinksSupported)(
+    "rejects an ancestor symlink race even when canonical path rechecks would pass",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-parent-race-" });
+        const publicDirectory = path.join(root, "public");
+        const privateDirectory = path.join(root, "private");
+        yield* fs.makeDirectory(publicDirectory);
+        yield* fs.makeDirectory(privateDirectory);
+        const filePath = path.join(publicDirectory, "recording.mp4");
+        yield* fs.writeFileString(filePath, "public video");
+        yield* fs.writeFileString(path.join(privateDirectory, "recording.mp4"), "private video");
+        const canonicalPath = yield* fs.realPath(filePath);
+        const result = yield* issueAssetUrl({
+          resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: filePath },
+        });
+        const suffix = result.relativeUrl.slice(`${ASSET_ROUTE_PREFIX}/`.length);
+        const separator = suffix.indexOf("/");
+        const native = yield* Effect.promise(() =>
+          vi.importActual<typeof NodeFSP>("node:fs/promises"),
+        );
+        const savedDirectory = path.join(root, "saved");
+        const realpathSpy = vi.mocked(NodeFSP.realpath).mockImplementationOnce(async () => {
+          // A pathname-only guard can see the original parents during realpath,
+          // but the private file during both lstat calls and open.
+          await native.unlink(publicDirectory);
+          await native.rename(savedDirectory, publicDirectory);
+          const canonical = await native.realpath(canonicalPath);
+          await native.rename(publicDirectory, savedDirectory);
+          await native.symlink(privateDirectory, publicDirectory, "junction");
           return canonical;
-        }),
-      });
-      expect(
-        yield* resolveAsset(suffix.slice(0, separator), suffix.slice(separator + 1)).pipe(
-          Effect.provideService(FileSystem.FileSystem, swappingFileSystem),
-        ),
-      ).toBeNull();
-    }).pipe(Effect.provide(testLayer)),
+        });
+        yield* Effect.addFinalizer(() =>
+          Effect.sync(() => realpathSpy.mockReset().mockImplementation(native.realpath)),
+        );
+        const swappingFileSystem = FileSystem.FileSystem.of({
+          ...fs,
+          realPath: Effect.fn(function* (requestedPath) {
+            const canonical = yield* fs.realPath(requestedPath);
+            if (requestedPath === canonicalPath) {
+              yield* fs.rename(publicDirectory, savedDirectory);
+              yield* Effect.promise(() =>
+                NodeFSP.symlink(privateDirectory, publicDirectory, "junction"),
+              );
+            }
+            return canonical;
+          }),
+        });
+        expect(
+          yield* resolveAsset(suffix.slice(0, separator), suffix.slice(separator + 1)).pipe(
+            Effect.provideService(FileSystem.FileSystem, swappingFileSystem),
+          ),
+        ).toBeNull();
+      }).pipe(Effect.provide(testLayer)),
   );
 
   it.effect("keeps in-place edits readable but requires a new URL after atomic replacement", () =>
diff --git a/apps/server/src/cli/theme.test.ts b/apps/server/src/cli/theme.test.ts
index d3dd69b94727..33606565ffc7 100644
--- a/apps/server/src/cli/theme.test.ts
+++ b/apps/server/src/cli/theme.test.ts
@@ -13,6 +13,7 @@ import * as TestConsole from "effect/testing/TestConsole";
 import { Command } from "effect/unstable/cli";
 
 import { cli } from "../bin.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const runCli = (args: ReadonlyArray<string>) =>
   Command.runWith(cli, { version: "0.0.0" })(args).pipe(
@@ -185,27 +186,29 @@ describe("t3 theme", () => {
 
   // A symlink is a normal way to hand this command a theme -- desktop hooks
   // symlink the current palette -- so the source is resolved, not refused.
-  it.effect("publishes a theme file through a symlinked source path", () =>
-    Effect.gen(function* () {
-      const baseDir = makeBaseDir();
-      const realFile = NodePath.join(baseDir, "real-nightfall.json");
-      NodeFS.writeFileSync(realFile, NIGHTFALL_THEME_JSON);
-      const linkPath = NodePath.join(baseDir, "nightfall.json");
-      NodeFS.symlinkSync(realFile, linkPath);
-
-      yield* runCli(["theme", "set", linkPath, "--base-dir", baseDir]);
-
-      assert.equal(
-        NodeFS.existsSync(NodePath.join(baseDir, "userdata", "themes", "nightfall.json")),
-        true,
-      );
-      assert.equal(readSettings(baseDir).defaultTheme, "nightfall");
-    }),
+  it.effect.skipIf(!symlinksSupported)(
+    "publishes a theme file through a symlinked source path",
+    () =>
+      Effect.gen(function* () {
+        const baseDir = makeBaseDir();
+        const realFile = NodePath.join(baseDir, "real-nightfall.json");
+        NodeFS.writeFileSync(realFile, NIGHTFALL_THEME_JSON);
+        const linkPath = NodePath.join(baseDir, "nightfall.json");
+        NodeFS.symlinkSync(realFile, linkPath);
+
+        yield* runCli(["theme", "set", linkPath, "--base-dir", baseDir]);
+
+        assert.equal(
+          NodeFS.existsSync(NodePath.join(baseDir, "userdata", "themes", "nightfall.json")),
+          true,
+        );
+        assert.equal(readSettings(baseDir).defaultTheme, "nightfall");
+      }),
   );
 
   // The staging entry is created fresh with O_EXCL, so a symlink planted at
   // its predictable name is cleared, never followed and written through.
-  it.effect("never writes through a symlink at the staging path", () =>
+  it.effect.skipIf(!symlinksSupported)("never writes through a symlink at the staging path", () =>
     Effect.gen(function* () {
       const baseDir = makeBaseDir();
       const themesDir = NodePath.join(baseDir, "userdata", "themes");
@@ -226,28 +229,30 @@ describe("t3 theme", () => {
   // Rollback moves the previous directory entry aside and back, so even an
   // entry the watcher would never publish -- here a symlink -- comes back
   // exactly as it was when the set fails.
-  it.effect("restores a non-theme destination entry when the set fails", () =>
-    Effect.gen(function* () {
-      const baseDir = makeBaseDir();
-      writeSettings(baseDir, {});
-      const userdataDir = NodePath.dirname(settingsPathFor(baseDir));
-      const themesDir = NodePath.join(userdataDir, "themes");
-      NodeFS.mkdirSync(themesDir, { recursive: true });
-      const outside = NodePath.join(baseDir, "outside.json");
-      NodeFS.writeFileSync(outside, NIGHTFALL_THEME_JSON);
-      const destination = NodePath.join(themesDir, "nightfall.json");
-      NodeFS.symlinkSync(outside, destination);
-      const themeFile = NodePath.join(baseDir, "nightfall.json");
-      NodeFS.writeFileSync(themeFile, NIGHTFALL_THEME_JSON);
-
-      NodeFS.chmodSync(userdataDir, 0o555);
-      try {
-        yield* runCli(["theme", "set", themeFile, "--base-dir", baseDir]).pipe(Effect.flip);
-        assert.equal(NodeFS.lstatSync(destination).isSymbolicLink(), true);
-      } finally {
-        NodeFS.chmodSync(userdataDir, 0o755);
-      }
-    }),
+  it.effect.skipIf(!symlinksSupported)(
+    "restores a non-theme destination entry when the set fails",
+    () =>
+      Effect.gen(function* () {
+        const baseDir = makeBaseDir();
+        writeSettings(baseDir, {});
+        const userdataDir = NodePath.dirname(settingsPathFor(baseDir));
+        const themesDir = NodePath.join(userdataDir, "themes");
+        NodeFS.mkdirSync(themesDir, { recursive: true });
+        const outside = NodePath.join(baseDir, "outside.json");
+        NodeFS.writeFileSync(outside, NIGHTFALL_THEME_JSON);
+        const destination = NodePath.join(themesDir, "nightfall.json");
+        NodeFS.symlinkSync(outside, destination);
+        const themeFile = NodePath.join(baseDir, "nightfall.json");
+        NodeFS.writeFileSync(themeFile, NIGHTFALL_THEME_JSON);
+
+        NodeFS.chmodSync(userdataDir, 0o555);
+        try {
+          yield* runCli(["theme", "set", themeFile, "--base-dir", baseDir]).pipe(Effect.flip);
+          assert.equal(NodeFS.lstatSync(destination).isSymbolicLink(), true);
+        } finally {
+          NodeFS.chmodSync(userdataDir, 0o755);
+        }
+      }),
   );
 
   it.effect("restores the previous theme when a re-publish fails to set", () =>
diff --git a/apps/server/src/entrypoint.test.ts b/apps/server/src/entrypoint.test.ts
index 56f2c119764a..bf8247fd4295 100644
--- a/apps/server/src/entrypoint.test.ts
+++ b/apps/server/src/entrypoint.test.ts
@@ -7,6 +7,7 @@ import * as NodeURL from "node:url";
 import { describe, expect, it } from "vite-plus/test";
 
 import { isEntrypoint } from "./entrypoint.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const makeTempDir = () => NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-entrypoint-test-"));
 
@@ -44,21 +45,24 @@ describe("isEntrypoint", () => {
     ).toBe(true);
   });
 
-  it("matches through a symlinked entrypoint, as npm and npx install it", () => {
-    const dir = makeTempDir();
-    const real = NodePath.join(dir, "bin.mjs");
-    const link = NodePath.join(dir, "t3");
-    NodeFS.writeFileSync(real, "");
-    NodeFS.symlinkSync(real, link);
+  it.skipIf(!symlinksSupported)(
+    "matches through a symlinked entrypoint, as npm and npx install it",
+    () => {
+      const dir = makeTempDir();
+      const real = NodePath.join(dir, "bin.mjs");
+      const link = NodePath.join(dir, "t3");
+      NodeFS.writeFileSync(real, "");
+      NodeFS.symlinkSync(real, link);
 
-    expect(
-      isEntrypoint({
-        moduleUrl: NodeURL.pathToFileURL(real).href,
-        entryPath: link,
-        runtimeMain: undefined,
-      }),
-    ).toBe(true);
-  });
+      expect(
+        isEntrypoint({
+          moduleUrl: NodeURL.pathToFileURL(real).href,
+          entryPath: link,
+          runtimeMain: undefined,
+        }),
+      ).toBe(true);
+    },
+  );
 
   it("stays false for an imported module that is not the entrypoint", () => {
     // This is what keeps `bin.test.ts` from launching the CLI on import.
diff --git a/apps/server/src/environmentTheme.test.ts b/apps/server/src/environmentTheme.test.ts
index 0d50e020098c..3c3f650b4c3c 100644
--- a/apps/server/src/environmentTheme.test.ts
+++ b/apps/server/src/environmentTheme.test.ts
@@ -13,6 +13,7 @@ import * as Stream from "effect/Stream";
 
 import * as ServerConfig from "./config.ts";
 import * as EnvironmentTheme from "./environmentTheme.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const encodeThemeFile = Schema.encodeSync(Schema.fromJsonString(EnvironmentThemeFile));
 
@@ -188,7 +189,7 @@ it.layer(NodeServices.layer)("environment theme", (it) => {
 
   // A symlinked themes directory stays usable, but a symlinked file inside it
   // must not publish whatever it points at.
-  it.effect("ignores a symlinked theme file", () =>
+  it.effect.skipIf(!symlinksSupported)("ignores a symlinked theme file", () =>
     withEnvironmentThemes(
       {},
       Effect.gen(function* () {
diff --git a/apps/server/src/orchestration/workflowScriptQuery.test.ts b/apps/server/src/orchestration/workflowScriptQuery.test.ts
index 47fe888de70c..311b89427697 100644
--- a/apps/server/src/orchestration/workflowScriptQuery.test.ts
+++ b/apps/server/src/orchestration/workflowScriptQuery.test.ts
@@ -5,6 +5,7 @@ import * as NodePath from "node:path";
 import { it as effectIt } from "@effect/vitest";
 import * as Effect from "effect/Effect";
 import { afterAll, assert, describe } from "vite-plus/test";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 import { readWorkflowScript } from "./workflowScriptQuery.ts";
 
 const root = NodePath.join(NodeOS.homedir(), ".claude", "projects", "__wf_script_test__");
@@ -14,19 +15,15 @@ NodeFS.writeFileSync(scriptPath, "export const meta = {};\n");
 const outside = NodePath.join(NodeOS.tmpdir(), "wf-outside.js");
 NodeFS.writeFileSync(outside, "evil\n");
 const link = NodePath.join(root, "sneaky.js");
-try {
+// Planted only where the host allows it; the escape test is skipped
+// otherwise rather than passing vacuously on "not-found".
+if (symlinksSupported) {
+  NodeFS.rmSync(link, { force: true });
   NodeFS.symlinkSync(outside, link);
-} catch (error) {
-  // Tolerate only "already exists" from a prior run — any other failure
-  // (EPERM etc.) must fail setup, or the escape test below would pass
-  // vacuously on "not-found" without testing containment.
-  if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
-    throw error;
+  if (!NodeFS.lstatSync(link).isSymbolicLink()) {
+    throw new Error("test setup: sneaky.js must be a symlink");
   }
 }
-if (!NodeFS.lstatSync(link).isSymbolicLink()) {
-  throw new Error("test setup: sneaky.js must be a symlink");
-}
 
 afterAll(() => {
   NodeFS.rmSync(root, { recursive: true, force: true });
@@ -53,23 +50,25 @@ describe("readWorkflowScript containment", () => {
     }),
   );
 
-  effectIt.effect("rejects paths outside the root and symlink escapes", () =>
-    Effect.gen(function* () {
-      const escaped = yield* Effect.exit(readWorkflowScript({ scriptPath: outside }));
-      assert.equal(escaped._tag, "Failure");
-      // A symlink INSIDE the root pointing outside must fail specifically on
-      // realpath re-containment — a "not-found" would mean the link was
-      // never exercised and the assertion proves nothing.
-      const sneaky = yield* Effect.exit(
-        readWorkflowScript({ scriptPath: link }).pipe(
-          Effect.flip,
-          Effect.map((error) => error.reason),
-        ),
-      );
-      assert.equal(sneaky._tag, "Success");
-      if (sneaky._tag === "Success") {
-        assert.equal(sneaky.value, "outside-root");
-      }
-    }),
+  effectIt.effect.skipIf(!symlinksSupported)(
+    "rejects paths outside the root and symlink escapes",
+    () =>
+      Effect.gen(function* () {
+        const escaped = yield* Effect.exit(readWorkflowScript({ scriptPath: outside }));
+        assert.equal(escaped._tag, "Failure");
+        // A symlink INSIDE the root pointing outside must fail specifically on
+        // realpath re-containment — a "not-found" would mean the link was
+        // never exercised and the assertion proves nothing.
+        const sneaky = yield* Effect.exit(
+          readWorkflowScript({ scriptPath: link }).pipe(
+            Effect.flip,
+            Effect.map((error) => error.reason),
+          ),
+        );
+        assert.equal(sneaky._tag, "Success");
+        if (sneaky._tag === "Success") {
+          assert.equal(sneaky.value, "outside-root");
+        }
+      }),
   );
 });
diff --git a/apps/server/src/provider/Drivers/AntigravitySkills.test.ts b/apps/server/src/provider/Drivers/AntigravitySkills.test.ts
index c5e1faacf237..bb3381216d72 100644
--- a/apps/server/src/provider/Drivers/AntigravitySkills.test.ts
+++ b/apps/server/src/provider/Drivers/AntigravitySkills.test.ts
@@ -5,6 +5,7 @@ import * as FileSystem from "effect/FileSystem";
 import * as Path from "effect/Path";
 
 import { discoverAntigravitySkills } from "./AntigravitySkills.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const writeSkill = Effect.fn("writeSkill")(function* (directory: string, contents: string) {
   const fileSystem = yield* FileSystem.FileSystem;
@@ -239,27 +240,29 @@ it.layer(NodeServices.layer)("discoverAntigravitySkills", (it) => {
     }),
   );
 
-  it.effect("follows directory symlinks used to install shared skills", () =>
-    Effect.gen(function* () {
-      const fileSystem = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const input = yield* makeWorkspace();
-      const sourceDirectory = path.join(input.profileDirectory, "shared-review");
-      yield* writeSkill(sourceDirectory, "---\nname: review\n---\n");
-      const root = path.join(input.cwd, ".agents", "skills");
-      const linkedDirectory = path.join(root, "review");
-      yield* fileSystem.makeDirectory(root, { recursive: true });
-      yield* fileSystem.symlink(sourceDirectory, linkedDirectory);
+  it.effect.skipIf(!symlinksSupported)(
+    "follows directory symlinks used to install shared skills",
+    () =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const input = yield* makeWorkspace();
+        const sourceDirectory = path.join(input.profileDirectory, "shared-review");
+        yield* writeSkill(sourceDirectory, "---\nname: review\n---\n");
+        const root = path.join(input.cwd, ".agents", "skills");
+        const linkedDirectory = path.join(root, "review");
+        yield* fileSystem.makeDirectory(root, { recursive: true });
+        yield* fileSystem.symlink(sourceDirectory, linkedDirectory);
 
-      assert.deepEqual(yield* discoverAntigravitySkills(input), [
-        {
-          name: "review",
-          path: path.join(linkedDirectory, "SKILL.md"),
-          scope: "project",
-          enabled: true,
-        },
-      ]);
-    }),
+        assert.deepEqual(yield* discoverAntigravitySkills(input), [
+          {
+            name: "review",
+            path: path.join(linkedDirectory, "SKILL.md"),
+            scope: "project",
+            enabled: true,
+          },
+        ]);
+      }),
   );
 
   it.effect("rejects an oversized skill instead of returning an incomplete catalog", () =>
diff --git a/apps/server/src/provider/Drivers/CodexHomeLayout.test.ts b/apps/server/src/provider/Drivers/CodexHomeLayout.test.ts
index 03c717abb14d..2c78ffd18662 100644
--- a/apps/server/src/provider/Drivers/CodexHomeLayout.test.ts
+++ b/apps/server/src/provider/Drivers/CodexHomeLayout.test.ts
@@ -13,6 +13,7 @@ import {
   materializeCodexShadowHome,
   resolveCodexHomeLayout,
 } from "./CodexHomeLayout.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 const decodeCodexSettingsValue = Schema.decodeSync(CodexSettings);
 
 const decodeCodexSettings = (input: {
@@ -84,130 +85,139 @@ it.layer(NodeServices.layer)("CodexHomeLayout", (it) => {
   });
 
   describe("materializeCodexShadowHome", () => {
-    it.effect("materializes a shadow home with shared state links and private auth", () =>
-      Effect.gen(function* () {
-        const fileSystem = yield* FileSystem.FileSystem;
-        const path = yield* Path.Path;
-        const sharedHome = yield* makeTempDir("t3code-codex-shared-");
-        const shadowRoot = yield* makeTempDir("t3code-codex-shadow-root-");
-        const shadowHome = path.join(shadowRoot, "shadow");
-
-        yield* fileSystem.makeDirectory(path.join(sharedHome, "sessions"));
-        yield* writeTextFile(path.join(sharedHome, "config.toml"), 'model = "gpt-5-codex"\n');
-        yield* writeTextFile(path.join(sharedHome, "models_cache.json"), '{"models":["shared"]}\n');
-        yield* writeTextFile(path.join(sharedHome, "auth.json"), '{"shared":true}\n');
-        yield* fileSystem.makeDirectory(shadowHome, { recursive: true });
-        yield* writeTextFile(path.join(shadowHome, "auth.json"), '{"shadow":true}\n');
-        yield* fileSystem.symlink(
-          path.join(sharedHome, "models_cache.json"),
-          path.join(shadowHome, "models_cache.json"),
-        );
-
-        const layout = yield* resolveCodexHomeLayout(
-          decodeCodexSettings({
-            homePath: sharedHome,
-            shadowHomePath: shadowHome,
-          }),
-        );
-
-        yield* materializeCodexShadowHome(layout);
-
-        const sessionsTarget = yield* fileSystem.readLink(path.join(shadowHome, "sessions"));
-        const configTarget = yield* fileSystem.readLink(path.join(shadowHome, "config.toml"));
-        const mcpOauthLocksTarget = yield* fileSystem.readLink(
-          path.join(shadowHome, "mcp-oauth-locks"),
-        );
-        const modelsCacheExists = yield* fileSystem.exists(
-          path.join(shadowHome, "models_cache.json"),
-        );
-        const authLinkResult = yield* fileSystem
-          .readLink(path.join(shadowHome, "auth.json"))
-          .pipe(Effect.result);
-        const authContents = yield* fileSystem.readFileString(path.join(shadowHome, "auth.json"));
-
-        expect(sessionsTarget).toBe(path.join(sharedHome, "sessions"));
-        expect(configTarget).toBe(path.join(sharedHome, "config.toml"));
-        expect(mcpOauthLocksTarget).toBe(path.join(sharedHome, "mcp-oauth-locks"));
-        expect(modelsCacheExists).toBe(false);
-        expect(authLinkResult._tag).toBe("Failure");
-        expect(authContents).toContain("shadow");
-      }),
+    it.effect.skipIf(!symlinksSupported)(
+      "materializes a shadow home with shared state links and private auth",
+      () =>
+        Effect.gen(function* () {
+          const fileSystem = yield* FileSystem.FileSystem;
+          const path = yield* Path.Path;
+          const sharedHome = yield* makeTempDir("t3code-codex-shared-");
+          const shadowRoot = yield* makeTempDir("t3code-codex-shadow-root-");
+          const shadowHome = path.join(shadowRoot, "shadow");
+
+          yield* fileSystem.makeDirectory(path.join(sharedHome, "sessions"));
+          yield* writeTextFile(path.join(sharedHome, "config.toml"), 'model = "gpt-5-codex"\n');
+          yield* writeTextFile(
+            path.join(sharedHome, "models_cache.json"),
+            '{"models":["shared"]}\n',
+          );
+          yield* writeTextFile(path.join(sharedHome, "auth.json"), '{"shared":true}\n');
+          yield* fileSystem.makeDirectory(shadowHome, { recursive: true });
+          yield* writeTextFile(path.join(shadowHome, "auth.json"), '{"shadow":true}\n');
+          yield* fileSystem.symlink(
+            path.join(sharedHome, "models_cache.json"),
+            path.join(shadowHome, "models_cache.json"),
+          );
+
+          const layout = yield* resolveCodexHomeLayout(
+            decodeCodexSettings({
+              homePath: sharedHome,
+              shadowHomePath: shadowHome,
+            }),
+          );
+
+          yield* materializeCodexShadowHome(layout);
+
+          const sessionsTarget = yield* fileSystem.readLink(path.join(shadowHome, "sessions"));
+          const configTarget = yield* fileSystem.readLink(path.join(shadowHome, "config.toml"));
+          const mcpOauthLocksTarget = yield* fileSystem.readLink(
+            path.join(shadowHome, "mcp-oauth-locks"),
+          );
+          const modelsCacheExists = yield* fileSystem.exists(
+            path.join(shadowHome, "models_cache.json"),
+          );
+          const authLinkResult = yield* fileSystem
+            .readLink(path.join(shadowHome, "auth.json"))
+            .pipe(Effect.result);
+          const authContents = yield* fileSystem.readFileString(path.join(shadowHome, "auth.json"));
+
+          expect(sessionsTarget).toBe(path.join(sharedHome, "sessions"));
+          expect(configTarget).toBe(path.join(sharedHome, "config.toml"));
+          expect(mcpOauthLocksTarget).toBe(path.join(sharedHome, "mcp-oauth-locks"));
+          expect(modelsCacheExists).toBe(false);
+          expect(authLinkResult._tag).toBe("Failure");
+          expect(authContents).toContain("shadow");
+        }),
     );
 
-    it.effect("replaces Codex-created local MCP OAuth locks with the shared lock directory", () =>
-      Effect.gen(function* () {
-        const fileSystem = yield* FileSystem.FileSystem;
-        const path = yield* Path.Path;
-        const sharedHome = yield* makeTempDir("t3code-codex-shared-");
-        const shadowRoot = yield* makeTempDir("t3code-codex-shadow-root-");
-        const shadowHome = path.join(shadowRoot, "shadow");
-        const sharedLocks = path.join(sharedHome, "mcp-oauth-locks");
-        const shadowLocks = path.join(shadowHome, "mcp-oauth-locks");
-
-        yield* writeTextFile(path.join(sharedLocks, "file-store.lock"), "");
-        yield* writeTextFile(path.join(shadowLocks, "file-store.lock"), "");
-
-        const layout = yield* resolveCodexHomeLayout(
-          decodeCodexSettings({
-            homePath: sharedHome,
-            shadowHomePath: shadowHome,
-          }),
-        );
-
-        yield* materializeCodexShadowHome(layout);
-
-        const locksTarget = yield* fileSystem.readLink(shadowLocks);
-        const sharedLockExists = yield* fileSystem.exists(
-          path.join(sharedLocks, "file-store.lock"),
-        );
-
-        expect(locksTarget).toBe(sharedLocks);
-        expect(sharedLockExists).toBe(true);
-      }),
+    it.effect.skipIf(!symlinksSupported)(
+      "replaces Codex-created local MCP OAuth locks with the shared lock directory",
+      () =>
+        Effect.gen(function* () {
+          const fileSystem = yield* FileSystem.FileSystem;
+          const path = yield* Path.Path;
+          const sharedHome = yield* makeTempDir("t3code-codex-shared-");
+          const shadowRoot = yield* makeTempDir("t3code-codex-shadow-root-");
+          const shadowHome = path.join(shadowRoot, "shadow");
+          const sharedLocks = path.join(sharedHome, "mcp-oauth-locks");
+          const shadowLocks = path.join(shadowHome, "mcp-oauth-locks");
+
+          yield* writeTextFile(path.join(sharedLocks, "file-store.lock"), "");
+          yield* writeTextFile(path.join(shadowLocks, "file-store.lock"), "");
+
+          const layout = yield* resolveCodexHomeLayout(
+            decodeCodexSettings({
+              homePath: sharedHome,
+              shadowHomePath: shadowHome,
+            }),
+          );
+
+          yield* materializeCodexShadowHome(layout);
+
+          const locksTarget = yield* fileSystem.readLink(shadowLocks);
+          const sharedLockExists = yield* fileSystem.exists(
+            path.join(sharedLocks, "file-store.lock"),
+          );
+
+          expect(locksTarget).toBe(sharedLocks);
+          expect(sharedLockExists).toBe(true);
+        }),
     );
 
-    it.effect("accepts Codex-created shadow-local runtime directories", () =>
-      Effect.gen(function* () {
-        const fileSystem = yield* FileSystem.FileSystem;
-        const path = yield* Path.Path;
-        const sharedHome = yield* makeTempDir("t3code-codex-shared-");
-        const shadowRoot = yield* makeTempDir("t3code-codex-shadow-root-");
-        const shadowHome = path.join(shadowRoot, "shadow");
-
-        yield* fileSystem.makeDirectory(path.join(sharedHome, "log"));
-        yield* fileSystem.makeDirectory(path.join(sharedHome, "memories"));
-        yield* fileSystem.makeDirectory(path.join(sharedHome, "tmp"));
-        yield* writeTextFile(path.join(sharedHome, "config.toml"), 'model = "gpt-5-codex"\n');
-        yield* writeTextFile(path.join(shadowHome, "auth.json"), '{"shadow":true}\n');
-        yield* fileSystem.makeDirectory(path.join(shadowHome, "log"), { recursive: true });
-        yield* fileSystem.makeDirectory(path.join(shadowHome, "memories"), { recursive: true });
-        yield* fileSystem.makeDirectory(path.join(shadowHome, "tmp"), { recursive: true });
-
-        const layout = yield* resolveCodexHomeLayout(
-          decodeCodexSettings({
-            homePath: sharedHome,
-            shadowHomePath: shadowHome,
-          }),
-        );
-
-        yield* materializeCodexShadowHome(layout);
-
-        const configTarget = yield* fileSystem.readLink(path.join(shadowHome, "config.toml"));
-        const logLinkResult = yield* fileSystem
-          .readLink(path.join(shadowHome, "log"))
-          .pipe(Effect.result);
-        const memoriesLinkResult = yield* fileSystem
-          .readLink(path.join(shadowHome, "memories"))
-          .pipe(Effect.result);
-        const tmpLinkResult = yield* fileSystem
-          .readLink(path.join(shadowHome, "tmp"))
-          .pipe(Effect.result);
-
-        expect(configTarget).toBe(path.join(sharedHome, "config.toml"));
-        expect(logLinkResult._tag).toBe("Failure");
-        expect(memoriesLinkResult._tag).toBe("Failure");
-        expect(tmpLinkResult._tag).toBe("Failure");
-      }),
+    it.effect.skipIf(!symlinksSupported)(
+      "accepts Codex-created shadow-local runtime directories",
+      () =>
+        Effect.gen(function* () {
+          const fileSystem = yield* FileSystem.FileSystem;
+          const path = yield* Path.Path;
+          const sharedHome = yield* makeTempDir("t3code-codex-shared-");
+          const shadowRoot = yield* makeTempDir("t3code-codex-shadow-root-");
+          const shadowHome = path.join(shadowRoot, "shadow");
+
+          yield* fileSystem.makeDirectory(path.join(sharedHome, "log"));
+          yield* fileSystem.makeDirectory(path.join(sharedHome, "memories"));
+          yield* fileSystem.makeDirectory(path.join(sharedHome, "tmp"));
+          yield* writeTextFile(path.join(sharedHome, "config.toml"), 'model = "gpt-5-codex"\n');
+          yield* writeTextFile(path.join(shadowHome, "auth.json"), '{"shadow":true}\n');
+          yield* fileSystem.makeDirectory(path.join(shadowHome, "log"), { recursive: true });
+          yield* fileSystem.makeDirectory(path.join(shadowHome, "memories"), { recursive: true });
+          yield* fileSystem.makeDirectory(path.join(shadowHome, "tmp"), { recursive: true });
+
+          const layout = yield* resolveCodexHomeLayout(
+            decodeCodexSettings({
+              homePath: sharedHome,
+              shadowHomePath: shadowHome,
+            }),
+          );
+
+          yield* materializeCodexShadowHome(layout);
+
+          const configTarget = yield* fileSystem.readLink(path.join(shadowHome, "config.toml"));
+          const logLinkResult = yield* fileSystem
+            .readLink(path.join(shadowHome, "log"))
+            .pipe(Effect.result);
+          const memoriesLinkResult = yield* fileSystem
+            .readLink(path.join(shadowHome, "memories"))
+            .pipe(Effect.result);
+          const tmpLinkResult = yield* fileSystem
+            .readLink(path.join(shadowHome, "tmp"))
+            .pipe(Effect.result);
+
+          expect(configTarget).toBe(path.join(sharedHome, "config.toml"));
+          expect(logLinkResult._tag).toBe("Failure");
+          expect(memoriesLinkResult._tag).toBe("Failure");
+          expect(tmpLinkResult._tag).toBe("Failure");
+        }),
     );
 
     it.effect("rejects shadow homes that point at the shared home", () =>
@@ -233,36 +243,38 @@ it.layer(NodeServices.layer)("CodexHomeLayout", (it) => {
       }),
     );
 
-    it.effect("rejects shared entries that already exist in the shadow home as real files", () =>
-      Effect.gen(function* () {
-        const path = yield* Path.Path;
-        const sharedHome = yield* makeTempDir("t3code-codex-shared-");
-        const shadowRoot = yield* makeTempDir("t3code-codex-shadow-root-");
-        const shadowHome = path.join(shadowRoot, "shadow");
-        yield* writeTextFile(path.join(sharedHome, "config.toml"), 'model = "gpt-5-codex"\n');
-        yield* writeTextFile(path.join(shadowHome, "config.toml"), 'model = "local"\n');
-
-        const layout = yield* resolveCodexHomeLayout(
-          decodeCodexSettings({
-            homePath: sharedHome,
-            shadowHomePath: shadowHome,
-          }),
-        );
-
-        const error = yield* materializeCodexShadowHome(layout).pipe(Effect.flip);
-
-        expect(error).toBeInstanceOf(CodexShadowHomeEntryConflictError);
-        expect(error).toMatchObject({
-          sharedHomePath: sharedHome,
-          effectiveHomePath: shadowHome,
-          entryName: "config.toml",
-          linkPath: path.join(shadowHome, "config.toml"),
-          targetPath: path.join(sharedHome, "config.toml"),
-        });
-        expect(error.message).toBe(
-          `Cannot create Codex shadow home entry 'config.toml' because '${path.join(shadowHome, "config.toml")}' already exists and is not a symlink.`,
-        );
-      }),
+    it.effect.skipIf(!symlinksSupported)(
+      "rejects shared entries that already exist in the shadow home as real files",
+      () =>
+        Effect.gen(function* () {
+          const path = yield* Path.Path;
+          const sharedHome = yield* makeTempDir("t3code-codex-shared-");
+          const shadowRoot = yield* makeTempDir("t3code-codex-shadow-root-");
+          const shadowHome = path.join(shadowRoot, "shadow");
+          yield* writeTextFile(path.join(sharedHome, "config.toml"), 'model = "gpt-5-codex"\n');
+          yield* writeTextFile(path.join(shadowHome, "config.toml"), 'model = "local"\n');
+
+          const layout = yield* resolveCodexHomeLayout(
+            decodeCodexSettings({
+              homePath: sharedHome,
+              shadowHomePath: shadowHome,
+            }),
+          );
+
+          const error = yield* materializeCodexShadowHome(layout).pipe(Effect.flip);
+
+          expect(error).toBeInstanceOf(CodexShadowHomeEntryConflictError);
+          expect(error).toMatchObject({
+            sharedHomePath: sharedHome,
+            effectiveHomePath: shadowHome,
+            entryName: "config.toml",
+            linkPath: path.join(shadowHome, "config.toml"),
+            targetPath: path.join(sharedHome, "config.toml"),
+          });
+          expect(error.message).toBe(
+            `Cannot create Codex shadow home entry 'config.toml' because '${path.join(shadowHome, "config.toml")}' already exists and is not a symlink.`,
+          );
+        }),
     );
 
     it.effect("preserves filesystem operation, paths, and cause", () =>
diff --git a/apps/server/src/provider/Layers/OpenCodeAdapter.test.ts b/apps/server/src/provider/Layers/OpenCodeAdapter.test.ts
index 93382f842231..fb0e9aa9ef2d 100644
--- a/apps/server/src/provider/Layers/OpenCodeAdapter.test.ts
+++ b/apps/server/src/provider/Layers/OpenCodeAdapter.test.ts
@@ -49,6 +49,7 @@ import {
   makeOpenCodeAdapter,
   mergeOpenCodeAssistantText,
 } from "./OpenCodeAdapter.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 // Test-local service tag so the rest of the file can keep using `yield* OpenCodeAdapter`.
 class OpenCodeAdapter extends Context.Service<OpenCodeAdapter, OpenCodeAdapterShape>()(
@@ -6401,30 +6402,32 @@ it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
     }),
   );
 
-  it.effect("treats lexically or physically identical directories as the same", () =>
-    Effect.gen(function* () {
-      const fileSystem = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const sameDirectory = (left: string, right: string) =>
-        isSameOpenCodeDirectory(fileSystem, path, left, right);
-
-      // Lexical-only differences (trailing slash, dot segments) short-circuit
-      // without touching the filesystem — the paths need not exist.
-      NodeAssert.equal(yield* sameDirectory("/repo/project/", "/repo/project"), true);
-      NodeAssert.equal(yield* sameDirectory("/repo/nested/../project", "/repo/project"), true);
-      // Nonexistent paths degrade to the lexical comparison instead of failing.
-      NodeAssert.equal(yield* sameDirectory("/repo/project", "/repo/other"), false);
-
-      // A symlinked cwd (the macOS `/tmp` → `/private/tmp` shape) resolves to
-      // the directory it points at, so the two spellings compare equal.
-      const base = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-opencode-dir-" });
-      const real = path.join(base, "real");
-      const link = path.join(base, "link");
-      yield* fileSystem.makeDirectory(real);
-      yield* fileSystem.symlink(real, link);
-      NodeAssert.equal(yield* sameDirectory(link, real), true);
-      NodeAssert.equal(yield* sameDirectory(link, path.join(base, "other")), false);
-    }).pipe(Effect.scoped),
+  it.effect.skipIf(!symlinksSupported)(
+    "treats lexically or physically identical directories as the same",
+    () =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const sameDirectory = (left: string, right: string) =>
+          isSameOpenCodeDirectory(fileSystem, path, left, right);
+
+        // Lexical-only differences (trailing slash, dot segments) short-circuit
+        // without touching the filesystem — the paths need not exist.
+        NodeAssert.equal(yield* sameDirectory("/repo/project/", "/repo/project"), true);
+        NodeAssert.equal(yield* sameDirectory("/repo/nested/../project", "/repo/project"), true);
+        // Nonexistent paths degrade to the lexical comparison instead of failing.
+        NodeAssert.equal(yield* sameDirectory("/repo/project", "/repo/other"), false);
+
+        // A symlinked cwd (the macOS `/tmp` → `/private/tmp` shape) resolves to
+        // the directory it points at, so the two spellings compare equal.
+        const base = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-opencode-dir-" });
+        const real = path.join(base, "real");
+        const link = path.join(base, "link");
+        yield* fileSystem.makeDirectory(real);
+        yield* fileSystem.symlink(real, link);
+        NodeAssert.equal(yield* sameDirectory(link, real), true);
+        NodeAssert.equal(yield* sameDirectory(link, path.join(base, "other")), false);
+      }).pipe(Effect.scoped),
   );
 
   it.effect("appends raw assistant text deltas and reconciles part update snapshots", () =>
diff --git a/apps/server/src/provider/providerMaintenance.test.ts b/apps/server/src/provider/providerMaintenance.test.ts
index c80b312b1408..35d0c04bb08e 100644
--- a/apps/server/src/provider/providerMaintenance.test.ts
+++ b/apps/server/src/provider/providerMaintenance.test.ts
@@ -20,6 +20,7 @@ import {
   resolveLatestProviderVersion,
   resolveProviderMaintenanceCapabilitiesEffect,
 } from "./providerMaintenance.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const driver = (value: string) => ProviderDriverKind.make(value);
 // These write `#!/bin/sh` stubs and resolve them through a darwin-mocked
@@ -456,100 +457,110 @@ it.layer(NodeServices.layer)("providerMaintenance", (it) => {
     });
   });
 
-  it.effect("keeps npm updates for binaries symlinked into npm's global node_modules tree", () =>
-    Effect.gen(function* () {
-      const tempDir = yield* makeTempDir("t3-npm-capabilities");
-      const binDir = NodePath.join(tempDir, "bin");
-      const packageBinDir = NodePath.join(
-        tempDir,
-        "lib",
-        "node_modules",
-        "@example",
-        "package-tool",
-        "bin",
-      );
-      NodeFS.mkdirSync(binDir, { recursive: true });
-      NodeFS.mkdirSync(packageBinDir, { recursive: true });
-      const packageBinPath = NodePath.join(packageBinDir, "package-tool.js");
-      const symlinkPath = NodePath.join(binDir, "package-tool");
-      NodeFS.writeFileSync(packageBinPath, "#!/usr/bin/env node\n");
-      NodeFS.chmodSync(packageBinPath, 0o755);
-      NodeFS.symlinkSync(packageBinPath, symlinkPath);
-
-      const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(packageToolUpdate, {
-        binaryPath: symlinkPath,
-        env: {
-          PATH: "",
-        },
-      });
-
-      expect(capabilities).toEqual({
-        provider: driver("packageTool"),
-        packageName: "@example/package-tool",
-        update: {
-          command:
-            "npm install -g --allow-scripts=@example/package-tool @example/package-tool@latest",
-
-          executable: "npm",
-
-          args: [
-            "install",
-            "-g",
-            "--allow-scripts=@example/package-tool",
-            "@example/package-tool@latest",
-          ],
+  it.effect.skipIf(!symlinksSupported)(
+    "keeps npm updates for binaries symlinked into npm's global node_modules tree",
+    () =>
+      Effect.gen(function* () {
+        const tempDir = yield* makeTempDir("t3-npm-capabilities");
+        const binDir = NodePath.join(tempDir, "bin");
+        const packageBinDir = NodePath.join(
+          tempDir,
+          "lib",
+          "node_modules",
+          "@example",
+          "package-tool",
+          "bin",
+        );
+        NodeFS.mkdirSync(binDir, { recursive: true });
+        NodeFS.mkdirSync(packageBinDir, { recursive: true });
+        const packageBinPath = NodePath.join(packageBinDir, "package-tool.js");
+        const symlinkPath = NodePath.join(binDir, "package-tool");
+        NodeFS.writeFileSync(packageBinPath, "#!/usr/bin/env node\n");
+        NodeFS.chmodSync(packageBinPath, 0o755);
+        NodeFS.symlinkSync(packageBinPath, symlinkPath);
 
-          lockKey: "npm-global",
-        },
-      });
-    }),
+        const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(
+          packageToolUpdate,
+          {
+            binaryPath: symlinkPath,
+            env: {
+              PATH: "",
+            },
+          },
+        );
+
+        expect(capabilities).toEqual({
+          provider: driver("packageTool"),
+          packageName: "@example/package-tool",
+          update: {
+            command:
+              "npm install -g --allow-scripts=@example/package-tool @example/package-tool@latest",
+
+            executable: "npm",
+
+            args: [
+              "install",
+              "-g",
+              "--allow-scripts=@example/package-tool",
+              "@example/package-tool@latest",
+            ],
+
+            lockKey: "npm-global",
+          },
+        });
+      }),
   );
 
-  it.effect("uses Effect FileSystem realPath when detecting pnpm global symlinks", () =>
-    Effect.gen(function* () {
-      const tempDir = yield* makeTempDir("t3-pnpm-realpath-capabilities");
-      const binDir = NodePath.join(tempDir, "bin");
-      const packageBinDir = NodePath.join(
-        tempDir,
-        ".local",
-        "share",
-        "pnpm",
-        "global",
-        "5",
-        "node_modules",
-        "@example",
-        "package-tool",
-        "bin",
-      );
-      NodeFS.mkdirSync(binDir, { recursive: true });
-      NodeFS.mkdirSync(packageBinDir, { recursive: true });
-      const packageBinPath = NodePath.join(packageBinDir, "package-tool.js");
-      const symlinkPath = NodePath.join(binDir, "package-tool");
-      NodeFS.writeFileSync(packageBinPath, "#!/usr/bin/env node\n");
-      NodeFS.chmodSync(packageBinPath, 0o755);
-      NodeFS.symlinkSync(packageBinPath, symlinkPath);
-
-      const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(packageToolUpdate, {
-        binaryPath: symlinkPath,
-        env: {
-          PATH: "",
-        },
-      });
+  it.effect.skipIf(!symlinksSupported)(
+    "uses Effect FileSystem realPath when detecting pnpm global symlinks",
+    () =>
+      Effect.gen(function* () {
+        const tempDir = yield* makeTempDir("t3-pnpm-realpath-capabilities");
+        const binDir = NodePath.join(tempDir, "bin");
+        const packageBinDir = NodePath.join(
+          tempDir,
+          ".local",
+          "share",
+          "pnpm",
+          "global",
+          "5",
+          "node_modules",
+          "@example",
+          "package-tool",
+          "bin",
+        );
+        NodeFS.mkdirSync(binDir, { recursive: true });
+        NodeFS.mkdirSync(packageBinDir, { recursive: true });
+        const packageBinPath = NodePath.join(packageBinDir, "package-tool.js");
+        const symlinkPath = NodePath.join(binDir, "package-tool");
+        NodeFS.writeFileSync(packageBinPath, "#!/usr/bin/env node\n");
+        NodeFS.chmodSync(packageBinPath, 0o755);
+        NodeFS.symlinkSync(packageBinPath, symlinkPath);
 
-      expect(capabilities).toEqual({
-        provider: driver("packageTool"),
-        packageName: "@example/package-tool",
-        update: {
-          command: "pnpm add -g @example/package-tool@latest",
+        const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(
+          packageToolUpdate,
+          {
+            binaryPath: symlinkPath,
+            env: {
+              PATH: "",
+            },
+          },
+        );
 
-          executable: "pnpm",
+        expect(capabilities).toEqual({
+          provider: driver("packageTool"),
+          packageName: "@example/package-tool",
+          update: {
+            command: "pnpm add -g @example/package-tool@latest",
 
-          args: ["add", "-g", "@example/package-tool@latest"],
+            executable: "pnpm",
 
-          lockKey: "pnpm-global",
-        },
-      });
-    }),
+            args: ["add", "-g", "@example/package-tool@latest"],
+
+            lockKey: "pnpm-global",
+          },
+        });
+      }),
   );
 
   it("allows the package's own install scripts in npm global updates", () => {
diff --git a/apps/server/src/server.test.ts b/apps/server/src/server.test.ts
index c98bc07fcd28..c853c86e5a6b 100644
--- a/apps/server/src/server.test.ts
+++ b/apps/server/src/server.test.ts
@@ -199,6 +199,7 @@ import {
   type TransferBudgetRun,
   transferBudgetViolations,
 } from "../integration/TransferBudgetReport.integration.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const defaultProjectId = ProjectId.make("project-default");
 const defaultThreadId = ThreadId.make("thread-default");
@@ -6311,7 +6312,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     }).pipe(Effect.provide(NodeHttpServer.layerTest), TestClock.withLive),
   );
 
-  it.effect("preserves structured workspace rpc failures", () =>
+  it.effect.skipIf(!symlinksSupported)("preserves structured workspace rpc failures", () =>
     Effect.gen(function* () {
       const fs = yield* FileSystem.FileSystem;
       const path = yield* Path.Path;
diff --git a/apps/server/src/sourceControl/PrTemplateDetection.test.ts b/apps/server/src/sourceControl/PrTemplateDetection.test.ts
index 34112c9c528c..5b91e631112f 100644
--- a/apps/server/src/sourceControl/PrTemplateDetection.test.ts
+++ b/apps/server/src/sourceControl/PrTemplateDetection.test.ts
@@ -10,6 +10,7 @@ import { ServerConfig } from "../config.ts";
 import * as GitVcsDriver from "../vcs/GitVcsDriver.ts";
 import * as VcsProcess from "../vcs/VcsProcess.ts";
 import { detectPrTemplate } from "./PrTemplateDetection.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const SINGLE_TEMPLATE_PATHS = [
   ".github/pull_request_template.md",
@@ -139,27 +140,29 @@ it.effect.each(TEMPLATE_DIRECTORIES)("recognizes the $0 directory", (relativeDir
   ),
 );
 
-it.effect("skips unusable directory entries and uses the one valid template", () =>
-  runWithTempDirectory((cwd) =>
-    Effect.gen(function* () {
-      const fileSystem = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const templateDirectory = path.join(cwd, ".github", "PULL_REQUEST_TEMPLATE");
-      yield* fileSystem.makeDirectory(path.join(templateDirectory, "b-directory.md"), {
-        recursive: true,
-      });
-      yield* fileSystem.writeFileString(path.join(templateDirectory, "a-empty.md"), " \n");
-      yield* fileSystem.symlink(
-        path.join(templateDirectory, "missing.md"),
-        path.join(templateDirectory, "c-broken.md"),
-      );
-      yield* fileSystem.writeFileString(path.join(templateDirectory, "z-valid.md"), "valid");
-      yield* commitTemplates(cwd);
-
-      const template = yield* detectTemplate(cwd);
-      assert.strictEqual(Option.getOrUndefined(template), "valid");
-    }),
-  ),
+it.effect.skipIf(!symlinksSupported)(
+  "skips unusable directory entries and uses the one valid template",
+  () =>
+    runWithTempDirectory((cwd) =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const templateDirectory = path.join(cwd, ".github", "PULL_REQUEST_TEMPLATE");
+        yield* fileSystem.makeDirectory(path.join(templateDirectory, "b-directory.md"), {
+          recursive: true,
+        });
+        yield* fileSystem.writeFileString(path.join(templateDirectory, "a-empty.md"), " \n");
+        yield* fileSystem.symlink(
+          path.join(templateDirectory, "missing.md"),
+          path.join(templateDirectory, "c-broken.md"),
+        );
+        yield* fileSystem.writeFileString(path.join(templateDirectory, "z-valid.md"), "valid");
+        yield* commitTemplates(cwd);
+
+        const template = yield* detectTemplate(cwd);
+        assert.strictEqual(Option.getOrUndefined(template), "valid");
+      }),
+    ),
 );
 
 it.effect("does not guess between multiple directory templates", () =>
@@ -176,60 +179,64 @@ it.effect("does not guess between multiple directory templates", () =>
   ),
 );
 
-it.effect("rejects a committed template symlink escaping the repository", () =>
-  runWithTempDirectory((cwd) =>
-    Effect.gen(function* () {
-      const fileSystem = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const outsideDirectory = yield* fileSystem.makeTempDirectoryScoped({
-        prefix: "t3-pr-template-outside-",
-      });
-      const outsideTemplate = path.join(outsideDirectory, "secret.md");
-      yield* fileSystem.writeFileString(outsideTemplate, "LOCAL_SECRET_SENTINEL");
-      const escapedTemplatePath = path.join(cwd, ".github", "pull_request_template.md");
-      yield* fileSystem.makeDirectory(path.dirname(escapedTemplatePath), { recursive: true });
-      yield* fileSystem.symlink(outsideTemplate, escapedTemplatePath);
-      yield* writeTemplate(cwd, "pull_request_template.md", "safe template");
-      yield* commitTemplates(cwd);
-
-      const template = yield* detectTemplate(cwd);
-      assert.strictEqual(Option.getOrUndefined(template), "safe template");
-      assert.notInclude(
-        Option.getOrElse(template, () => ""),
-        "LOCAL_SECRET_SENTINEL",
-      );
-    }),
-  ),
+it.effect.skipIf(!symlinksSupported)(
+  "rejects a committed template symlink escaping the repository",
+  () =>
+    runWithTempDirectory((cwd) =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const outsideDirectory = yield* fileSystem.makeTempDirectoryScoped({
+          prefix: "t3-pr-template-outside-",
+        });
+        const outsideTemplate = path.join(outsideDirectory, "secret.md");
+        yield* fileSystem.writeFileString(outsideTemplate, "LOCAL_SECRET_SENTINEL");
+        const escapedTemplatePath = path.join(cwd, ".github", "pull_request_template.md");
+        yield* fileSystem.makeDirectory(path.dirname(escapedTemplatePath), { recursive: true });
+        yield* fileSystem.symlink(outsideTemplate, escapedTemplatePath);
+        yield* writeTemplate(cwd, "pull_request_template.md", "safe template");
+        yield* commitTemplates(cwd);
+
+        const template = yield* detectTemplate(cwd);
+        assert.strictEqual(Option.getOrUndefined(template), "safe template");
+        assert.notInclude(
+          Option.getOrElse(template, () => ""),
+          "LOCAL_SECRET_SENTINEL",
+        );
+      }),
+    ),
 );
 
-it.effect("reads the committed template when a worktree parent is replaced", () =>
-  runWithTempDirectory((cwd) =>
-    Effect.gen(function* () {
-      const fileSystem = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const outsideDirectory = yield* fileSystem.makeTempDirectoryScoped({
-        prefix: "t3-pr-template-outside-",
-      });
-      const templatePath = yield* writeTemplate(
-        cwd,
-        ".github/pull_request_template.md",
-        "committed template",
-      );
-      yield* commitTemplates(cwd);
-      yield* writeTemplate(outsideDirectory, "pull_request_template.md", "LOCAL_SECRET_SENTINEL");
-
-      const templateDirectory = path.dirname(templatePath);
-      yield* fileSystem.rename(templateDirectory, path.join(cwd, ".github-original"));
-      yield* fileSystem.symlink(outsideDirectory, templateDirectory);
-
-      const template = yield* detectTemplate(cwd);
-      assert.strictEqual(Option.getOrUndefined(template), "committed template");
-      assert.notInclude(
-        Option.getOrElse(template, () => ""),
-        "LOCAL_SECRET_SENTINEL",
-      );
-    }),
-  ),
+it.effect.skipIf(!symlinksSupported)(
+  "reads the committed template when a worktree parent is replaced",
+  () =>
+    runWithTempDirectory((cwd) =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const outsideDirectory = yield* fileSystem.makeTempDirectoryScoped({
+          prefix: "t3-pr-template-outside-",
+        });
+        const templatePath = yield* writeTemplate(
+          cwd,
+          ".github/pull_request_template.md",
+          "committed template",
+        );
+        yield* commitTemplates(cwd);
+        yield* writeTemplate(outsideDirectory, "pull_request_template.md", "LOCAL_SECRET_SENTINEL");
+
+        const templateDirectory = path.dirname(templatePath);
+        yield* fileSystem.rename(templateDirectory, path.join(cwd, ".github-original"));
+        yield* fileSystem.symlink(outsideDirectory, templateDirectory);
+
+        const template = yield* detectTemplate(cwd);
+        assert.strictEqual(Option.getOrUndefined(template), "committed template");
+        assert.notInclude(
+          Option.getOrElse(template, () => ""),
+          "LOCAL_SECRET_SENTINEL",
+        );
+      }),
+    ),
 );
 
 it.effect("bounds template reads and marks truncated content", () =>
diff --git a/apps/server/src/vcs/VcsStatusBroadcaster.test.ts b/apps/server/src/vcs/VcsStatusBroadcaster.test.ts
index c7d7b79a12e0..ac21a61ddf78 100644
--- a/apps/server/src/vcs/VcsStatusBroadcaster.test.ts
+++ b/apps/server/src/vcs/VcsStatusBroadcaster.test.ts
@@ -27,6 +27,7 @@ import { GitManagerError } from "@t3tools/contracts";
 import * as VcsStatusBroadcaster from "./VcsStatusBroadcaster.ts";
 import * as BackgroundPolicy from "../background/BackgroundPolicy.ts";
 import * as GitWorkflowService from "../git/GitWorkflowService.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const TEST_EPOCH = DateTime.makeUnsafe("1970-01-01T00:00:00.000Z");
 
@@ -144,7 +145,7 @@ function makeBackgroundPolicyLayer(shouldRunScopeWork: (scope: BackgroundScope)
 }
 
 describe("VcsStatusBroadcaster", () => {
-  it.effect(
+  it.effect.skipIf(!symlinksSupported)(
     "automatically pulls an enabled clean default branch when status detects it is behind",
     () => {
       let remoteStatus: VcsStatusRemoteResult = { ...baseRemoteStatus, behindCount: 2 };
@@ -522,67 +523,70 @@ describe("VcsStatusBroadcaster", () => {
     }).pipe(Effect.provide(makeTestLayer(state)));
   });
 
-  it.effect("normalizes symlinked CWDs before cache lookup and workflow calls", () => {
-    const seenCwds: string[] = [];
-    const state = {
-      currentLocalStatus: baseLocalStatus,
-      currentRemoteStatus: baseRemoteStatus,
-      localStatusCalls: 0,
-      remoteStatusCalls: 0,
-      localInvalidationCalls: 0,
-      remoteInvalidationCalls: 0,
-    };
-    const testLayer = VcsStatusBroadcaster.layer.pipe(
-      Layer.provideMerge(NodeServices.layer),
-      Layer.provide(makeBackgroundPolicyLayer(() => true)),
-      Layer.provide(
-        Layer.mock(GitWorkflowService.GitWorkflowService)({
-          localStatus: (input) =>
-            Effect.sync(() => {
-              seenCwds.push(input.cwd);
-              state.localStatusCalls += 1;
-              return state.currentLocalStatus;
-            }),
-          remoteStatus: (input) =>
-            Effect.sync(() => {
-              seenCwds.push(input.cwd);
-              state.remoteStatusCalls += 1;
-              return state.currentRemoteStatus;
-            }),
-          invalidateLocalStatus: () =>
-            Effect.sync(() => {
-              state.localInvalidationCalls += 1;
-            }),
-          invalidateRemoteStatus: () =>
-            Effect.sync(() => {
-              state.remoteInvalidationCalls += 1;
-            }),
-        } satisfies Partial<GitWorkflowService.GitWorkflowService["Service"]>),
-      ),
-    );
+  it.effect.skipIf(!symlinksSupported)(
+    "normalizes symlinked CWDs before cache lookup and workflow calls",
+    () => {
+      const seenCwds: string[] = [];
+      const state = {
+        currentLocalStatus: baseLocalStatus,
+        currentRemoteStatus: baseRemoteStatus,
+        localStatusCalls: 0,
+        remoteStatusCalls: 0,
+        localInvalidationCalls: 0,
+        remoteInvalidationCalls: 0,
+      };
+      const testLayer = VcsStatusBroadcaster.layer.pipe(
+        Layer.provideMerge(NodeServices.layer),
+        Layer.provide(makeBackgroundPolicyLayer(() => true)),
+        Layer.provide(
+          Layer.mock(GitWorkflowService.GitWorkflowService)({
+            localStatus: (input) =>
+              Effect.sync(() => {
+                seenCwds.push(input.cwd);
+                state.localStatusCalls += 1;
+                return state.currentLocalStatus;
+              }),
+            remoteStatus: (input) =>
+              Effect.sync(() => {
+                seenCwds.push(input.cwd);
+                state.remoteStatusCalls += 1;
+                return state.currentRemoteStatus;
+              }),
+            invalidateLocalStatus: () =>
+              Effect.sync(() => {
+                state.localInvalidationCalls += 1;
+              }),
+            invalidateRemoteStatus: () =>
+              Effect.sync(() => {
+                state.remoteInvalidationCalls += 1;
+              }),
+          } satisfies Partial<GitWorkflowService.GitWorkflowService["Service"]>),
+        ),
+      );
 
-    return Effect.gen(function* () {
-      const fileSystem = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const realDir = yield* fileSystem.makeTempDirectoryScoped({
-        prefix: "t3-vcs-status-real-",
-      });
-      const linkParent = yield* fileSystem.makeTempDirectoryScoped({
-        prefix: "t3-vcs-status-link-",
-      });
-      const linkDir = path.join(linkParent, "repo-link");
-      yield* fileSystem.symlink(realDir, linkDir);
-      const realPath = yield* fileSystem.realPath(realDir);
+      return Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const realDir = yield* fileSystem.makeTempDirectoryScoped({
+          prefix: "t3-vcs-status-real-",
+        });
+        const linkParent = yield* fileSystem.makeTempDirectoryScoped({
+          prefix: "t3-vcs-status-link-",
+        });
+        const linkDir = path.join(linkParent, "repo-link");
+        yield* fileSystem.symlink(realDir, linkDir);
+        const realPath = yield* fileSystem.realPath(realDir);
 
-      const broadcaster = yield* VcsStatusBroadcaster.VcsStatusBroadcaster;
-      yield* broadcaster.getStatus({ cwd: linkDir });
-      yield* broadcaster.getStatus({ cwd: realDir });
+        const broadcaster = yield* VcsStatusBroadcaster.VcsStatusBroadcaster;
+        yield* broadcaster.getStatus({ cwd: linkDir });
+        yield* broadcaster.getStatus({ cwd: realDir });
 
-      assert.deepStrictEqual(seenCwds, [realPath, realPath]);
-      assert.equal(state.localStatusCalls, 1);
-      assert.equal(state.remoteStatusCalls, 1);
-    }).pipe(Effect.provide(testLayer));
-  });
+        assert.deepStrictEqual(seenCwds, [realPath, realPath]);
+        assert.equal(state.localStatusCalls, 1);
+        assert.equal(state.remoteStatusCalls, 1);
+      }).pipe(Effect.provide(testLayer));
+    },
+  );
 
   it.effect("streams a local snapshot first and remote updates later", () => {
     const state = {
diff --git a/apps/server/src/workspace/WorkspaceFileSystem.test.ts b/apps/server/src/workspace/WorkspaceFileSystem.test.ts
index 17c7f0bb050c..591414f85bcf 100644
--- a/apps/server/src/workspace/WorkspaceFileSystem.test.ts
+++ b/apps/server/src/workspace/WorkspaceFileSystem.test.ts
@@ -14,6 +14,7 @@ import * as VcsProcess from "../vcs/VcsProcess.ts";
 import * as WorkspaceEntries from "./WorkspaceEntries.ts";
 import * as WorkspaceFileSystem from "./WorkspaceFileSystem.ts";
 import * as WorkspacePaths from "./WorkspacePaths.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const ProjectLayer = WorkspaceFileSystem.layer.pipe(
   Layer.provide(WorkspacePaths.layer),
@@ -138,34 +139,36 @@ it.layer(TestLayer, { excludeTestServices: true })("WorkspaceFileSystemLive", (i
       }),
     );
 
-    it.effect("rejects symlinks that resolve outside the workspace root", () =>
-      Effect.gen(function* () {
-        const workspaceFileSystem = yield* WorkspaceFileSystem.WorkspaceFileSystem;
-        const fileSystem = yield* FileSystem.FileSystem;
-        const path = yield* Path.Path;
-        const cwd = yield* makeTempDir;
-        const outsideDir = yield* makeTempDir;
-        yield* writeTextFile(outsideDir, "secret.txt", "outside\n");
-        yield* fileSystem.symlink(
-          path.join(outsideDir, "secret.txt"),
-          path.join(cwd, "linked-secret.txt"),
-        );
-
-        const error = yield* workspaceFileSystem
-          .readFile({ cwd, relativePath: "linked-secret.txt" })
-          .pipe(Effect.flip);
-        const resolvedWorkspaceRoot = yield* fileSystem.realPath(cwd);
-        const resolvedPath = yield* fileSystem.realPath(path.join(outsideDir, "secret.txt"));
-
-        expect(error).toBeInstanceOf(WorkspaceFileSystem.WorkspaceFilePathEscapeError);
-        expect(error).toMatchObject({
-          workspaceRoot: cwd,
-          relativePath: "linked-secret.txt",
-          resolvedWorkspaceRoot,
-          resolvedPath,
-        });
-        expect("cause" in error).toBe(false);
-      }),
+    it.effect.skipIf(!symlinksSupported)(
+      "rejects symlinks that resolve outside the workspace root",
+      () =>
+        Effect.gen(function* () {
+          const workspaceFileSystem = yield* WorkspaceFileSystem.WorkspaceFileSystem;
+          const fileSystem = yield* FileSystem.FileSystem;
+          const path = yield* Path.Path;
+          const cwd = yield* makeTempDir;
+          const outsideDir = yield* makeTempDir;
+          yield* writeTextFile(outsideDir, "secret.txt", "outside\n");
+          yield* fileSystem.symlink(
+            path.join(outsideDir, "secret.txt"),
+            path.join(cwd, "linked-secret.txt"),
+          );
+
+          const error = yield* workspaceFileSystem
+            .readFile({ cwd, relativePath: "linked-secret.txt" })
+            .pipe(Effect.flip);
+          const resolvedWorkspaceRoot = yield* fileSystem.realPath(cwd);
+          const resolvedPath = yield* fileSystem.realPath(path.join(outsideDir, "secret.txt"));
+
+          expect(error).toBeInstanceOf(WorkspaceFileSystem.WorkspaceFilePathEscapeError);
+          expect(error).toMatchObject({
+            workspaceRoot: cwd,
+            relativePath: "linked-secret.txt",
+            resolvedWorkspaceRoot,
+            resolvedPath,
+          });
+          expect("cause" in error).toBe(false);
+        }),
     );
 
     it.effect("rejects directories without manufacturing an I/O cause", () =>
diff --git a/packages/shared/package.json b/packages/shared/package.json
index d9233a2c54c4..a5ce349a4c00 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -223,6 +223,10 @@
       "types": "./src/hostProcess.ts",
       "import": "./src/hostProcess.ts"
     },
+    "./testing/symlinks": {
+      "types": "./src/testing/symlinks.ts",
+      "import": "./src/testing/symlinks.ts"
+    },
     "./httpReadiness": {
       "types": "./src/httpReadiness.ts",
       "import": "./src/httpReadiness.ts"
diff --git a/packages/shared/src/testing/symlinks.ts b/packages/shared/src/testing/symlinks.ts
new file mode 100644
index 000000000000..4e76984ca210
--- /dev/null
+++ b/packages/shared/src/testing/symlinks.ts
@@ -0,0 +1,29 @@
+// @effect-diagnostics nodeBuiltinImport:off - one synchronous probe at module load, outside any Effect runtime.
+import * as NodeFS from "node:fs";
+import * as NodeOS from "node:os";
+import * as NodePath from "node:path";
+
+/**
+ * Whether this host lets an unprivileged process create symlinks. Windows
+ * refuses without Developer Mode or elevation, so tests that plant a symlink
+ * to prove containment or escape detection should `skipIf(!symlinksSupported)`
+ * rather than fail at setup. Probed once per process.
+ */
+export const symlinksSupported: boolean = (() => {
+  let directory: string | undefined;
+  try {
+    directory = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-symlink-probe-"));
+    NodeFS.symlinkSync(NodePath.join(directory, "target"), NodePath.join(directory, "link"));
+    return true;
+  } catch {
+    return false;
+  } finally {
+    // Cleanup must not decide the answer: a transient EPERM/EBUSY on the
+    // probe directory would otherwise throw out of module initialisation.
+    try {
+      if (directory !== undefined) NodeFS.rmSync(directory, { recursive: true, force: true });
+    } catch {
+      // Leave the probe directory behind rather than fail every importer.
+    }
+  }
+})();
diff --git a/scripts/build-desktop-artifact.test.ts b/scripts/build-desktop-artifact.test.ts
index 478f6ee2d21b..c3d40a03d3ce 100644
--- a/scripts/build-desktop-artifact.test.ts
+++ b/scripts/build-desktop-artifact.test.ts
@@ -87,6 +87,7 @@ import {
 } from "./build-desktop-artifact.ts";
 import { BRAND_ASSET_PATHS } from "./lib/brand-assets.ts";
 import { HostProcessArchitecture, HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 // A minimal stand-in for the staged sidecar roots packed into the WSL archive.
 const stageWslRuntimeTreeFixture = Effect.fn("stageWslRuntimeTreeFixture")(function* (
@@ -2191,7 +2192,7 @@ it("keeps the prefix of a UNC path instead of going relative", () => {
   assert.deepStrictEqual(paths[0], "\\\\server\\share\\tmp\\node_modules");
 });
 
-it.effect("rebases packaged links into the isolated tree", () =>
+it.effect.skipIf(!symlinksSupported)("rebases packaged links into the isolated tree", () =>
   Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
diff --git a/scripts/mock-update-server.test.ts b/scripts/mock-update-server.test.ts
index 1371ba58f44f..5e060ff9013b 100644
--- a/scripts/mock-update-server.test.ts
+++ b/scripts/mock-update-server.test.ts
@@ -7,6 +7,7 @@ import * as Path from "effect/Path";
 import { HttpClient, HttpRouter } from "effect/unstable/http";
 
 import { makeMockUpdateRouteLayer } from "./mock-update-server.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const withMockUpdateServer = <A, E, R>(rootRealPath: string, effect: Effect.Effect<A, E, R>) =>
   effect.pipe(
@@ -72,35 +73,37 @@ it.layer(NodeServices.layer)("mock-update-server", (it) => {
     }),
   );
 
-  it.effect("rejects symlinked files that escape the configured root", () =>
-    Effect.gen(function* () {
-      const fileSystem = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const root = yield* fileSystem.makeTempDirectoryScoped({
-        prefix: "mock-update-server-root-",
-      });
-      const outside = yield* fileSystem.makeTempDirectoryScoped({
-        prefix: "mock-update-server-outside-",
-      });
-      const rootRealPath = yield* fileSystem.realPath(root);
-      const outsideFile = path.join(outside, "outside.yml");
-      const linksDir = path.join(root, "links");
-      const symlinkPath = path.join(linksDir, "outside.yml");
+  it.effect.skipIf(!symlinksSupported)(
+    "rejects symlinked files that escape the configured root",
+    () =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const root = yield* fileSystem.makeTempDirectoryScoped({
+          prefix: "mock-update-server-root-",
+        });
+        const outside = yield* fileSystem.makeTempDirectoryScoped({
+          prefix: "mock-update-server-outside-",
+        });
+        const rootRealPath = yield* fileSystem.realPath(root);
+        const outsideFile = path.join(outside, "outside.yml");
+        const linksDir = path.join(root, "links");
+        const symlinkPath = path.join(linksDir, "outside.yml");
 
-      yield* fileSystem.writeFileString(outsideFile, "version: outside\n");
-      yield* fileSystem.makeDirectory(linksDir, { recursive: true });
-      yield* fileSystem.symlink(outsideFile, symlinkPath);
+        yield* fileSystem.writeFileString(outsideFile, "version: outside\n");
+        yield* fileSystem.makeDirectory(linksDir, { recursive: true });
+        yield* fileSystem.symlink(outsideFile, symlinkPath);
 
-      yield* withMockUpdateServer(
-        rootRealPath,
-        Effect.gen(function* () {
-          const client = yield* HttpClient.HttpClient;
-          const response = yield* client.get("/links/outside.yml");
+        yield* withMockUpdateServer(
+          rootRealPath,
+          Effect.gen(function* () {
+            const client = yield* HttpClient.HttpClient;
+            const response = yield* client.get("/links/outside.yml");
 
-          assert.equal(response.status, 404);
-          assert.equal(yield* response.text, "Not Found");
-        }),
-      );
-    }),
+            assert.equal(response.status, 404);
+            assert.equal(yield* response.text, "Not Found");
+          }),
+        );
+      }),
   );
 });

From 5c6c1d67d82bb81bddaee6d83e54e8aecd96ec7d Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 13:33:20 -0700
Subject: [PATCH 11/56] test(server): run fake provider CLIs through a Node
 stub on every host (#9567)

Co-authored-by: Claude Code <noreply@anthropic.com>
---
 .gitattributes                                |   3 +
 .../CodexCollabRuntime.integration.test.ts    |   7 +-
 .../src/provider/Layers/CursorAdapter.test.ts |  55 ++--
 .../provider/Layers/CursorProvider.test.ts    |  53 ++--
 .../src/provider/Layers/GrokAdapter.test.ts   |  25 +-
 .../src/provider/Layers/GrokProvider.test.ts  |  61 ++---
 .../testFixtures/codexCollabMockPeer.cmd      |   8 +
 apps/server/src/testUtils/fakeCli.ts          | 106 ++++++++
 .../ClaudeTextGeneration.test.ts              |  42 +--
 .../CodexTextGeneration.test.ts               | 255 +++++++-----------
 .../CursorTextGeneration.test.ts              | 105 ++++----
 .../textGeneration/GrokTextGeneration.test.ts |  33 +--
 12 files changed, 383 insertions(+), 370 deletions(-)
 create mode 100644 apps/server/src/provider/testFixtures/codexCollabMockPeer.cmd
 create mode 100644 apps/server/src/testUtils/fakeCli.ts

diff --git a/.gitattributes b/.gitattributes
index 705bd8f43e00..00b0e5eccb98 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1,2 +1,5 @@
 # git autocrlf=true converts LF to CRLF on Windows, causing issues with oxfmt
 * text=auto eol=lf
+# Batch files need CRLF for cmd.exe to parse them reliably.
+*.cmd text eol=crlf
+*.bat text eol=crlf
diff --git a/apps/server/src/provider/Layers/CodexCollabRuntime.integration.test.ts b/apps/server/src/provider/Layers/CodexCollabRuntime.integration.test.ts
index 5bc5940fe539..7fcbe7b5f334 100644
--- a/apps/server/src/provider/Layers/CodexCollabRuntime.integration.test.ts
+++ b/apps/server/src/provider/Layers/CodexCollabRuntime.integration.test.ts
@@ -23,6 +23,7 @@ import { assert, describe } from "vite-plus/test";
 
 import wireFixture from "../testFixtures/codexMultiAgentWire.json" with { type: "json" };
 import { makeCodexSessionRuntime } from "./CodexSessionRuntime.ts";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 
 const ROOT = wireFixture.rootThreadId;
 const [CHILD_A, CHILD_B] = wireFixture.childThreadIds as [string, string];
@@ -157,7 +158,11 @@ function readRecordedRequests() {
 }
 
 const scriptPath = NodePath.join(import.meta.dirname, "../testFixtures/.collab-script.json");
-const peerPath = NodePath.join(import.meta.dirname, "../testFixtures/codexCollabMockPeer.sh");
+// Windows cannot run the shebang wrapper; the .cmd sibling does the same job.
+const peerPath = NodePath.join(
+  import.meta.dirname,
+  `../testFixtures/codexCollabMockPeer.${HostProcessPlatform.defaultValue() === "win32" ? "cmd" : "sh"}`,
+);
 
 describe("CodexSessionRuntime collab integration", () => {
   it.effect("looks up child model metadata once after activity registration", () =>
diff --git a/apps/server/src/provider/Layers/CursorAdapter.test.ts b/apps/server/src/provider/Layers/CursorAdapter.test.ts
index b952c97ffac8..9881710135ce 100644
--- a/apps/server/src/provider/Layers/CursorAdapter.test.ts
+++ b/apps/server/src/provider/Layers/CursorAdapter.test.ts
@@ -30,6 +30,8 @@ import { buildRuntimeInstructions } from "../RuntimeInstructions.ts";
 import { ServerSettingsService } from "../../serverSettings.ts";
 import type { CursorAdapterShape } from "../Services/CursorAdapter.ts";
 import { makeCursorAdapter } from "./CursorAdapter.ts";
+import { execScriptSource, writeFakeCli } from "../../testUtils/fakeCli.ts";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 const decodeCursorSettings = Schema.decodeSync(CursorSettings);
 
 // Test-local service tag so the rest of the file can keep using `yield* CursorAdapter`.
@@ -39,26 +41,25 @@ class CursorAdapter extends Context.Service<CursorAdapter, CursorAdapterShape>()
 
 const __dirname = NodePath.dirname(NodeURL.fileURLToPath(import.meta.url));
 const mockAgentPath = NodePath.join(__dirname, "../../../scripts/acp-mock-agent.ts");
-const mockAgentCommand = "node";
-const mockAgentArgs = [mockAgentPath] as const;
-
+// Stopping a session kills the agent with SIGTERM; Windows terminates the
+// process instead, so the mock never sees a signal to log.
+const windowsHost = HostProcessPlatform.defaultValue() === "win32";
 async function makeMockAgentWrapper(
   extraEnv?: Record<string, string>,
   options?: { initialDelaySeconds?: number },
 ) {
   const dir = await NodeFSP.mkdtemp(NodePath.join(NodeOS.tmpdir(), "cursor-acp-mock-"));
-  const wrapperPath = NodePath.join(dir, "fake-agent.sh");
-  const envExports = Object.entries(extraEnv ?? {})
-    .map(([key, value]) => `export ${key}=${JSON.stringify(value)}`)
-    .join("\n");
-  const script = `#!/bin/sh
-${envExports}
-${options?.initialDelaySeconds ? `sleep ${JSON.stringify(String(options.initialDelaySeconds))}` : ""}
-exec ${JSON.stringify(mockAgentCommand)} ${mockAgentArgs.map((arg) => JSON.stringify(arg)).join(" ")} "$@"
-`;
-  await NodeFSP.writeFile(wrapperPath, script, "utf8");
-  await NodeFSP.chmod(wrapperPath, 0o755);
-  return wrapperPath;
+  return writeFakeCli({
+    directory: dir,
+    name: "fake-agent",
+    env: extraEnv ?? {},
+    source: execScriptSource({
+      scriptPath: mockAgentPath,
+      ...(options?.initialDelaySeconds === undefined
+        ? {}
+        : { delayMs: Math.round(options.initialDelaySeconds * 1000) }),
+    }),
+  });
 }
 
 async function makeProbeWrapper(
@@ -67,20 +68,12 @@ async function makeProbeWrapper(
   extraEnv?: Record<string, string>,
 ) {
   const dir = await NodeFSP.mkdtemp(NodePath.join(NodeOS.tmpdir(), "cursor-acp-probe-"));
-  const wrapperPath = NodePath.join(dir, "fake-agent.sh");
-  const envExports = Object.entries(extraEnv ?? {})
-    .map(([key, value]) => `export ${key}=${JSON.stringify(value)}`)
-    .join("\n");
-  const script = `#!/bin/sh
-printf '%s\t' "$@" >> ${JSON.stringify(argvLogPath)}
-printf '\n' >> ${JSON.stringify(argvLogPath)}
-export T3_ACP_REQUEST_LOG_PATH=${JSON.stringify(requestLogPath)}
-${envExports}
-exec ${JSON.stringify(mockAgentCommand)} ${mockAgentArgs.map((arg) => JSON.stringify(arg)).join(" ")} "$@"
-`;
-  await NodeFSP.writeFile(wrapperPath, script, "utf8");
-  await NodeFSP.chmod(wrapperPath, 0o755);
-  return wrapperPath;
+  return writeFakeCli({
+    directory: dir,
+    name: "fake-agent",
+    env: { T3_ACP_REQUEST_LOG_PATH: requestLogPath, ...extraEnv },
+    source: execScriptSource({ scriptPath: mockAgentPath, argvLogPath }),
+  });
 }
 
 async function readArgvLog(filePath: string) {
@@ -390,7 +383,7 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
     }),
   );
 
-  it.effect("closes the ACP child process when a session stops", () =>
+  it.effect.skipIf(windowsHost)("closes the ACP child process when a session stops", () =>
     Effect.gen(function* () {
       const adapter = yield* CursorAdapter;
       const settings = yield* ServerSettingsService;
@@ -422,7 +415,7 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
     }),
   );
 
-  it.effect(
+  it.effect.skipIf(windowsHost)(
     "serializes concurrent startSession calls for the same thread and closes the replaced ACP session",
     () =>
       Effect.gen(function* () {
diff --git a/apps/server/src/provider/Layers/CursorProvider.test.ts b/apps/server/src/provider/Layers/CursorProvider.test.ts
index 98983b4b4434..8f1a0c54cf5a 100644
--- a/apps/server/src/provider/Layers/CursorProvider.test.ts
+++ b/apps/server/src/provider/Layers/CursorProvider.test.ts
@@ -30,6 +30,8 @@ import {
   probeCursorSkills,
   rewriteCursorSkillMentions,
 } from "../Drivers/CursorSkills.ts";
+import { execScriptSource, writeFakeCli } from "../../testUtils/fakeCli.ts";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 
 const runNode = <A, E>(
   effect: Effect.Effect<
@@ -39,6 +41,10 @@ const runNode = <A, E>(
   >,
 ): Promise<A> => Effect.runPromise(effect.pipe(Effect.provide(NodeServices.layer)));
 
+// Closing the probe kills the agent with SIGTERM; Windows terminates the
+// process instead, so the mock never sees a signal to log.
+const windowsHost = HostProcessPlatform.defaultValue() === "win32";
+
 const resolveMockAgentPath = Effect.fn("resolveMockAgentPath")(function* () {
   const path = yield* Path.Path;
   return yield* path.fromFileUrl(new URL("../../../scripts/acp-mock-agent.ts", import.meta.url));
@@ -73,47 +79,38 @@ const makeMockAgentWrapper = Effect.fn("makeMockAgentWrapper")(function* (
   extraEnv?: Record<string, string>,
 ) {
   const fileSystem = yield* FileSystem.FileSystem;
-  const path = yield* Path.Path;
   const mockAgentPath = yield* resolveMockAgentPath();
   const dir = yield* fileSystem.makeTempDirectory({
     directory: NodeOS.tmpdir(),
     prefix: "cursor-provider-mock-",
   });
-  const wrapperPath = path.join(dir, "fake-agent.sh");
-  const mockAgentCommand = ["node", mockAgentPath].map((arg) => JSON.stringify(arg)).join(" ");
-  const envExports = Object.entries(extraEnv ?? {})
-    .map(([key, value]) => `export ${key}=${JSON.stringify(value)}`)
-    .join("\n");
-  const script = `#!/bin/sh
-${envExports}
-exec ${mockAgentCommand} "$@"
-`;
-  yield* fileSystem.writeFileString(wrapperPath, script);
-  yield* fileSystem.chmod(wrapperPath, 0o755);
-  return wrapperPath;
+  return writeFakeCli({
+    directory: dir,
+    name: "fake-agent",
+    env: extraEnv ?? {},
+    source: execScriptSource({ scriptPath: mockAgentPath }),
+  });
 });
 
 const makeMockAgentWithAboutWrapper = Effect.fn("makeMockAgentWithAboutWrapper")(function* () {
   const fileSystem = yield* FileSystem.FileSystem;
-  const path = yield* Path.Path;
   const mockAgentPath = yield* resolveMockAgentPath();
   const dir = yield* fileSystem.makeTempDirectory({
     directory: NodeOS.tmpdir(),
     prefix: "cursor-provider-about-mock-",
   });
-  const wrapperPath = path.join(dir, "fake-agent.sh");
-  const mockAgentCommand = ["node", mockAgentPath].map((arg) => JSON.stringify(arg)).join(" ");
-  const script = `#!/bin/sh
-if [ "$1" = "about" ]; then
-  printf 'CLI Version         2026.04.09-f2b0fcd\\n'
-  printf 'User Email          cursor@example.com\\n'
-  exit 0
-fi
-exec ${mockAgentCommand} "$@"
-`;
-  yield* fileSystem.writeFileString(wrapperPath, script);
-  yield* fileSystem.chmod(wrapperPath, 0o755);
-  return wrapperPath;
+  return writeFakeCli({
+    directory: dir,
+    name: "fake-agent",
+    source: [
+      'if (process.argv[2] === "about") {',
+      '  process.stdout.write("CLI Version         2026.04.09-f2b0fcd\\n");',
+      '  process.stdout.write("User Email          cursor@example.com\\n");',
+      "  process.exit(0);",
+      "}",
+      execScriptSource({ scriptPath: mockAgentPath }),
+    ].join("\n"),
+  });
 });
 
 const waitForFileContent = Effect.fn("waitForFileContent")(function* (
@@ -593,7 +590,7 @@ describe("discoverCursorModelsViaAcp", () => {
     ]);
   });
 
-  it("closes the ACP probe runtime after discovery completes", async () => {
+  it.skipIf(windowsHost)("closes the ACP probe runtime after discovery completes", async () => {
     const { exitLogPath, wrapperPath } = await runNode(
       makeExitLogFixture("cursor-provider-exit-log-"),
     );
diff --git a/apps/server/src/provider/Layers/GrokAdapter.test.ts b/apps/server/src/provider/Layers/GrokAdapter.test.ts
index 44a0c7343d22..41fa6ed0f60a 100644
--- a/apps/server/src/provider/Layers/GrokAdapter.test.ts
+++ b/apps/server/src/provider/Layers/GrokAdapter.test.ts
@@ -33,25 +33,24 @@ import {
   nextGrokPlanModeActive,
   selectGrokPermissionOptionId,
 } from "./GrokAdapter.ts";
+import { execScriptSource, writeFakeCli } from "../../testUtils/fakeCli.ts";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 const decodeGrokSettings = Schema.decodeSync(GrokSettings);
 
 const __dirname = NodePath.dirname(NodeURL.fileURLToPath(import.meta.url));
 const mockAgentPath = NodePath.join(__dirname, "../../../scripts/acp-mock-agent.ts");
-const mockAgentCommand = process.execPath;
+// Stopping a session kills the agent with SIGTERM; Windows terminates the
+// process instead, so the mock never sees a signal to log.
+const windowsHost = HostProcessPlatform.defaultValue() === "win32";
 
 async function makeMockGrokWrapper(extraEnv?: Record<string, string>) {
   const dir = await NodeFSP.mkdtemp(NodePath.join(NodeOS.tmpdir(), "grok-acp-mock-"));
-  const wrapperPath = NodePath.join(dir, "fake-grok.sh");
-  const envExports = Object.entries(extraEnv ?? {})
-    .map(([key, value]) => `export ${key}=${JSON.stringify(value)}`)
-    .join("\n");
-  const script = `#!/bin/sh
-${envExports}
-exec ${JSON.stringify(mockAgentCommand)} ${JSON.stringify(mockAgentPath)} "$@"
-`;
-  await NodeFSP.writeFile(wrapperPath, script, "utf8");
-  await NodeFSP.chmod(wrapperPath, 0o755);
-  return wrapperPath;
+  return writeFakeCli({
+    directory: dir,
+    name: "fake-grok",
+    env: extraEnv ?? {},
+    source: execScriptSource({ scriptPath: mockAgentPath }),
+  });
 }
 
 function waitForFileContent(
@@ -340,7 +339,7 @@ it.layer(grokAdapterTestLayer)("GrokAdapterLive", (it) => {
     }),
   );
 
-  it.effect("closes the ACP child process when a session stops", () =>
+  it.effect.skipIf(windowsHost)("closes the ACP child process when a session stops", () =>
     Effect.gen(function* () {
       const threadId = ThreadId.make("grok-stop-session-close");
       const tempDir = yield* Effect.promise(() =>
diff --git a/apps/server/src/provider/Layers/GrokProvider.test.ts b/apps/server/src/provider/Layers/GrokProvider.test.ts
index e7c62f4cbf77..c751919b189a 100644
--- a/apps/server/src/provider/Layers/GrokProvider.test.ts
+++ b/apps/server/src/provider/Layers/GrokProvider.test.ts
@@ -6,7 +6,6 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 import { describe, expect, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
-import * as Path from "effect/Path";
 import * as Schema from "effect/Schema";
 import { GrokSettings } from "@t3tools/contracts";
 
@@ -17,6 +16,7 @@ import {
   checkGrokProviderStatus,
   parseGrokModelsCliOutput,
 } from "./GrokProvider.ts";
+import { execScriptSource, writeFakeCli } from "../../testUtils/fakeCli.ts";
 
 const decodeGrokSettings = Schema.decodeSync(GrokSettings);
 const __dirname = NodePath.dirname(NodeURL.fileURLToPath(import.meta.url));
@@ -308,14 +308,17 @@ it.layer(NodeServices.layer)("checkGrokProviderStatus", (it) => {
       const snapshot = yield* Effect.scoped(
         Effect.gen(function* () {
           const fs = yield* FileSystem.FileSystem;
-          const path = yield* Path.Path;
           const dir = yield* fs.makeTempDirectoryScoped({ prefix: "t3code-grok-version-" });
-          const grokPath = path.join(dir, "grok");
-          yield* fs.writeFileString(
-            grokPath,
-            ["#!/bin/sh", `printf "%s\\n" "${secretStderr}" >&2`, "exit 2", ""].join("\n"),
-          );
-          yield* fs.chmod(grokPath, 0o755);
+          const grokPath = writeFakeCli({
+            directory: dir,
+            name: "grok",
+            source: [
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
+              `process.stderr.write(${JSON.stringify(`${secretStderr}\n`)});`,
+              "process.exit(2);",
+              "",
+            ].join("\n"),
+          });
 
           return yield* checkGrokProviderStatus(
             decodeGrokSettings({ enabled: true, binaryPath: grokPath }),
@@ -331,37 +334,31 @@ it.layer(NodeServices.layer)("checkGrokProviderStatus", (it) => {
     }),
   );
 
-  // Single-quotes a path for /bin/sh. Temp dirs and execPath never contain quotes.
-  const shellQuote = (value: string) => `'${value.replaceAll("'", `'\\''`)}'`;
-
-  // A shell stand-in for the Grok CLI: `--version` and `models` print canned text,
+  // A stand-in for the Grok CLI: `--version` and `models` print canned text,
   // and `agent stdio` execs the mock ACP agent so `initialize` returns model metadata.
   const writeFakeGrokCli = (input: { readonly modelsOutput: string; readonly acp: boolean }) =>
     Effect.gen(function* () {
       const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
       const dir = yield* fs.makeTempDirectoryScoped({ prefix: "t3code-grok-probe-" });
-      const modelsPath = path.join(dir, "models.txt");
-      yield* fs.writeFileString(modelsPath, input.modelsOutput);
-      const grokPath = path.join(dir, "grok");
-      const mockAgentPath = path.resolve(__dirname, "../../../scripts/acp-mock-agent.ts");
-      yield* fs.writeFileString(
-        grokPath,
-        [
-          "#!/bin/sh",
-          'case "$1" in',
-          '  --version) printf "grok 1.0.13\\n"; exit 0;;',
-          `  models) cat ${shellQuote(modelsPath)}; exit 0;;`,
-          input.acp
-            ? `  agent) exec ${shellQuote(process.execPath)} ${shellQuote(mockAgentPath)};;`
-            : "  agent) exit 3;;",
-          "esac",
-          "exit 1",
+      const mockAgentPath = NodePath.resolve(__dirname, "../../../scripts/acp-mock-agent.ts");
+      return writeFakeCli({
+        directory: dir,
+        name: "grok",
+        source: [
+          'if (process.argv[2] === "--version") {',
+          '  process.stdout.write("grok 1.0.13\\n");',
+          "  process.exit(0);",
+          "}",
+          'if (process.argv[2] === "models") {',
+          // @effect-diagnostics-next-line preferSchemaOverJson:off
+          `  process.stdout.write(${JSON.stringify(input.modelsOutput)});`,
+          "  process.exit(0);",
+          "}",
+          'if (process.argv[2] !== "agent") process.exit(1);',
+          ...(input.acp ? [execScriptSource({ scriptPath: mockAgentPath })] : ["process.exit(3);"]),
           "",
         ].join("\n"),
-      );
-      yield* fs.chmod(grokPath, 0o755);
-      return grokPath;
+      });
     });
 
   it.effect("reports ready with ACP-discovered models when logged in", () =>
diff --git a/apps/server/src/provider/testFixtures/codexCollabMockPeer.cmd b/apps/server/src/provider/testFixtures/codexCollabMockPeer.cmd
new file mode 100644
index 000000000000..18220e2c7f69
--- /dev/null
+++ b/apps/server/src/provider/testFixtures/codexCollabMockPeer.cmd
@@ -0,0 +1,8 @@
+@echo off
+rem Wrapper so CodexSessionRuntime can spawn the mock peer on Windows: the
+rem runtime always passes "app-server" as the first argument; drop it and
+rem run the .mjs peer with node. "shift /1" leaves %0 alone so %~dp0 still
+rem names this file's directory.
+shift /1
+node "%~dp0codexCollabMockPeer.mjs" %1 %2 %3 %4 %5 %6 %7 %8 %9
+exit /b %ERRORLEVEL%
diff --git a/apps/server/src/testUtils/fakeCli.ts b/apps/server/src/testUtils/fakeCli.ts
new file mode 100644
index 000000000000..68ab157aed7a
--- /dev/null
+++ b/apps/server/src/testUtils/fakeCli.ts
@@ -0,0 +1,106 @@
+// @effect-diagnostics nodeBuiltinImport:off preferSchemaOverJson:off - synchronous fixture writer used from plain and Effect tests alike.
+import * as NodeFS from "node:fs";
+import * as NodePath from "node:path";
+
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+
+export interface FakeCliOptions {
+  /** Directory the launcher and its stub are written into. */
+  readonly directory: string;
+  /** Command name as callers spawn it, e.g. `codex`. */
+  readonly name: string;
+  /** ES module source the launcher runs with `node`. `process.argv.slice(2)` carries the CLI args. */
+  readonly source: string;
+  /** Environment set for the stub before it runs, on top of the inherited environment. */
+  readonly env?: Readonly<Record<string, string>>;
+  /**
+   * Platform the launcher is shaped for. Effect callers should pass the value
+   * they read from `HostProcessPlatform` so an injected override is honoured;
+   * defaults to the real host for plain tests.
+   */
+  readonly platform?: NodeJS.Platform;
+}
+
+/**
+ * Writes a fake CLI whose behaviour lives in a Node stub. On posix the
+ * launcher is a `#!/bin/sh` script; on Windows it is a `.cmd` shim, since a
+ * shebang file is not executable there and `resolveSpawnCommand` routes
+ * `.cmd` through a shell. Returns the launcher path to hand to the code under
+ * test, which on Windows carries the `.cmd` extension.
+ */
+export function writeFakeCli(options: FakeCliOptions): string {
+  NodeFS.mkdirSync(options.directory, { recursive: true });
+  const stubPath = NodePath.join(options.directory, `${options.name}-stub.mjs`);
+  // The environment rides in a JSON sidecar the stub applies to itself, since
+  // neither sh nor cmd.exe can quote every value (newlines, quotes, `%`) safely.
+  const envPath = NodePath.join(options.directory, `${options.name}-env.json`);
+  NodeFS.writeFileSync(envPath, JSON.stringify(options.env ?? {}), "utf8");
+  NodeFS.writeFileSync(
+    stubPath,
+    [
+      'import { readFileSync as readFakeCliEnv } from "node:fs";',
+      `Object.assign(process.env, JSON.parse(readFakeCliEnv(${JSON.stringify(envPath)}, "utf8")));`,
+      options.source,
+    ].join("\n"),
+    "utf8",
+  );
+
+  if ((options.platform ?? HostProcessPlatform.defaultValue()) === "win32") {
+    const launcherPath = NodePath.join(options.directory, `${options.name}.cmd`);
+    NodeFS.writeFileSync(
+      launcherPath,
+      ["@echo off", `node "%~dp0${options.name}-stub.mjs" %*`, "exit /b %ERRORLEVEL%", ""].join(
+        "\r\n",
+      ),
+      "utf8",
+    );
+    return launcherPath;
+  }
+
+  const launcherPath = NodePath.join(options.directory, options.name);
+  NodeFS.writeFileSync(
+    launcherPath,
+    ["#!/bin/sh", `exec node "$(dirname "$0")/${options.name}-stub.mjs" "$@"`, ""].join("\n"),
+    "utf8",
+  );
+  NodeFS.chmodSync(launcherPath, 0o755);
+  return launcherPath;
+}
+
+/**
+ * Stub source that becomes `scriptPath`: after optionally requiring a leading
+ * argv prefix, it imports the script into its own process so the stub is the
+ * agent. Nothing sits between the code under test and the mock, so a kill or
+ * a closed stdin reaches it directly and its exit log is faithful on every
+ * host. The script must not read `process.argv`; the mock agents are driven
+ * by environment and stdin.
+ */
+export function execScriptSource(options: {
+  readonly scriptPath: string;
+  readonly expectedArgs?: ReadonlyArray<string>;
+  /** Tab-separated argv appended here per invocation, for launch-flag assertions. */
+  readonly argvLogPath?: string;
+  /** Wait before handing over, for tests that race a slow startup. */
+  readonly delayMs?: number;
+}): string {
+  return [
+    'import { appendFileSync } from "node:fs";',
+    'import { pathToFileURL } from "node:url";',
+    "const args = process.argv.slice(2);",
+    ...(options.argvLogPath === undefined
+      ? []
+      : [
+          `appendFileSync(${JSON.stringify(options.argvLogPath)}, args.join(${JSON.stringify("\t")}) + ${JSON.stringify("\n")});`,
+        ]),
+    ...(options.delayMs === undefined
+      ? []
+      : [`Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ${options.delayMs});`]),
+    `const expected = ${JSON.stringify(options.expectedArgs ?? [])};`,
+    "if (expected.some((value, index) => args[index] !== value)) {",
+    '  process.stderr.write(`unexpected args: ${args.join(" ")}\\n`);',
+    "  process.exit(11);",
+    "}",
+    `await import(pathToFileURL(${JSON.stringify(options.scriptPath)}).href);`,
+    "",
+  ].join("\n");
+}
diff --git a/apps/server/src/textGeneration/ClaudeTextGeneration.test.ts b/apps/server/src/textGeneration/ClaudeTextGeneration.test.ts
index 8dcaa3720295..fe95c8649ea3 100644
--- a/apps/server/src/textGeneration/ClaudeTextGeneration.test.ts
+++ b/apps/server/src/textGeneration/ClaudeTextGeneration.test.ts
@@ -1,7 +1,7 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { it } from "@effect/vitest";
 import { ClaudeSettings, ProviderInstanceId } from "@t3tools/contracts";
-import { isHostWindows } from "@t3tools/shared/hostProcess";
+import { HostProcessPlatform, isHostWindows } from "@t3tools/shared/hostProcess";
 import { createModelSelection } from "@t3tools/shared/model";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
@@ -21,27 +21,26 @@ import {
 import * as TextGeneration from "./TextGeneration.ts";
 import { sanitizeThreadTitle } from "./TextGenerationUtils.ts";
 import { makeClaudeTextGeneration } from "./ClaudeTextGeneration.ts";
+import { writeFakeCli } from "../testUtils/fakeCli.ts";
 const decodeClaudeSettings = Schema.decodeSync(ClaudeSettings);
 
 const ClaudeTextGenerationTestLayer = ServerConfig.ServerConfig.layerTest(process.cwd(), {
   prefix: "t3code-claude-text-generation-test-",
 }).pipe(Layer.provideMerge(NodeServices.layer));
 
+// The stub behaviour lives in Node so the same implementation runs on Windows,
+// where a shebang file is not executable and would fall through to the real
+// Claude CLI on PATH; `writeFakeCli` picks the launcher shape per host.
 function makeFakeClaudeBinary(dir: string) {
   return Effect.gen(function* () {
-    const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
-    const isWindows = yield* isHostWindows;
+    const platform = yield* HostProcessPlatform;
     const binDir = path.join(dir, "bin");
-    const stubPath = path.join(binDir, "claude-stub.mjs");
-    yield* fs.makeDirectory(binDir, { recursive: true });
-
-    // The stub behaviour lives in Node rather than a `#!/bin/sh` script so the
-    // same implementation is usable on Windows, where a shebang file is not
-    // executable and would fall through to the real Claude CLI on PATH.
-    yield* fs.writeFileString(
-      stubPath,
-      [
+    writeFakeCli({
+      directory: binDir,
+      name: "claude",
+      platform,
+      source: [
         'const args = process.argv.slice(2).join(" ");',
         "",
         "function fail(message, code) {",
@@ -87,24 +86,7 @@ function makeFakeClaudeBinary(dir: string) {
         "process.exitCode = Number(process.env.T3_FAKE_CLAUDE_EXIT_CODE ?? 0);",
         "",
       ].join("\n"),
-    );
-
-    if (isWindows) {
-      // Windows resolves executables through PATHEXT, so the entry point has to
-      // carry a real extension. `resolveSpawnCommand` spawns `.cmd` via a shell.
-      yield* fs.writeFileString(
-        path.join(binDir, "claude.cmd"),
-        ["@echo off", 'node "%~dp0claude-stub.mjs" %*', "exit /b %ERRORLEVEL%", ""].join("\r\n"),
-      );
-    } else {
-      const claudePath = path.join(binDir, "claude");
-      yield* fs.writeFileString(
-        claudePath,
-        ["#!/bin/sh", 'exec node "$(dirname "$0")/claude-stub.mjs" "$@"', ""].join("\n"),
-      );
-      yield* fs.chmod(claudePath, 0o755);
-    }
-
+    });
     return binDir;
   });
 }
diff --git a/apps/server/src/textGeneration/CodexTextGeneration.test.ts b/apps/server/src/textGeneration/CodexTextGeneration.test.ts
index 657118fff51c..0129136d5e8d 100644
--- a/apps/server/src/textGeneration/CodexTextGeneration.test.ts
+++ b/apps/server/src/textGeneration/CodexTextGeneration.test.ts
@@ -14,6 +14,7 @@ import { CodexSettings, ProviderInstanceId, TextGenerationError } from "@t3tools
 import * as ServerConfig from "../config.ts";
 import * as TextGeneration from "./TextGeneration.ts";
 import { makeCodexTextGeneration } from "./CodexTextGeneration.ts";
+import { writeFakeCli } from "../testUtils/fakeCli.ts";
 const decodeCodexSettings = Schema.decodeSync(CodexSettings);
 
 const DEFAULT_TEST_MODEL_SELECTION = createModelSelection(
@@ -25,170 +26,112 @@ const CodexTextGenerationTestLayer = ServerConfig.ServerConfig.layerTest(process
   prefix: "t3code-codex-text-generation-test-",
 }).pipe(Layer.provideMerge(NodeServices.layer));
 
-function makeFakeCodexBinary(
-  dir: string,
-  input: {
-    output: string;
-    exitCode?: number;
-    stderr?: string;
-    requireImage?: boolean;
-    requireServiceTier?: string;
-    requireReasoningEffort?: string;
-    forbidReasoningEffort?: boolean;
-    requireArg?: string;
-    forbidArg?: string;
-    stdinMustContain?: string;
-    stdinMustNotContain?: string;
-  },
-) {
+interface FakeCodexInput {
+  output: string;
+  exitCode?: number;
+  stderr?: string;
+  requireImage?: boolean;
+  requireServiceTier?: string;
+  requireReasoningEffort?: string;
+  forbidReasoningEffort?: boolean;
+  requireArg?: string;
+  forbidArg?: string;
+  stdinMustContain?: string;
+  stdinMustNotContain?: string;
+}
+
+// The stub walks argv the way the shell script it replaced did: `--image`,
+// `--config key=value`, and `--output-last-message <path>` are consumed, the
+// prompt arrives on stdin, and each check exits with its own code so a
+// failing test names the assertion that tripped.
+function makeFakeCodexBinary(dir: string, input: FakeCodexInput) {
+  const check = JSON.stringify({
+    requireImage: input.requireImage ?? false,
+    requireServiceTier: input.requireServiceTier ?? null,
+    requireReasoningEffort: input.requireReasoningEffort ?? null,
+    forbidReasoningEffort: input.forbidReasoningEffort ?? false,
+    requireArg: input.requireArg ?? null,
+    forbidArg: input.forbidArg ?? null,
+    stdinMustContain: input.stdinMustContain ?? null,
+    stdinMustNotContain: input.stdinMustNotContain ?? null,
+    stderr: input.stderr ?? null,
+    output: input.output,
+    exitCode: input.exitCode ?? 0,
+  });
   return Effect.gen(function* () {
-    const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
-    const binDir = path.join(dir, "bin");
-    const codexPath = path.join(binDir, "codex");
-    yield* fs.makeDirectory(binDir, { recursive: true });
-
-    yield* fs.writeFileString(
-      codexPath,
-      [
-        "#!/bin/sh",
-        'original_args="$*"',
-        'output_path=""',
-        'seen_image="0"',
-        'seen_service_tier=""',
-        'seen_reasoning_effort=""',
-        "while [ $# -gt 0 ]; do",
-        '  if [ "$1" = "--image" ]; then',
-        "    shift",
-        '    if [ -n "$1" ]; then',
-        '      seen_image="1"',
-        "    fi",
-        "    shift",
-        "    continue",
-        "  fi",
-        '  if [ "$1" = "--config" ]; then',
-        "    shift",
-        '    case "$1" in',
-        "      service_tier=*)",
-        '        seen_service_tier="$1"',
-        "        ;;",
-        "    esac",
-        '    case "$1" in',
-        "      model_reasoning_effort=*)",
-        '        seen_reasoning_effort="$1"',
-        "        ;;",
-        "    esac",
-        "    shift",
-        "    continue",
-        "  fi",
-        '  if [ "$1" = "--output-last-message" ]; then',
-        "    shift",
-        '    output_path="$1"',
-        "    shift",
-        "    continue",
-        "  fi",
-        "  shift",
-        "done",
-        'stdin_content="$(cat)"',
-        ...(input.requireArg !== undefined
-          ? [
-              `case " $original_args " in *" ${input.requireArg} "*) ;; *)`,
-              `  printf "%s\\n" "missing arg: ${input.requireArg}" >&2`,
-              `  exit 8`,
-              "esac",
-            ]
-          : []),
-        ...(input.forbidArg !== undefined
-          ? [
-              `case " $original_args " in *" ${input.forbidArg} "*)`,
-              `  printf "%s\\n" "forbidden arg: ${input.forbidArg}" >&2`,
-              `  exit 9`,
-              "esac",
-            ]
-          : []),
-        ...(input.requireImage
-          ? [
-              'if [ "$seen_image" != "1" ]; then',
-              '  printf "%s\\n" "missing --image input" >&2',
-              `  exit 2`,
-              "fi",
-            ]
-          : []),
-        ...(input.requireServiceTier
-          ? [
-              `if [ "$seen_service_tier" != "service_tier=\\"${input.requireServiceTier}\\"" ]; then`,
-              '  printf "%s\\n" "unexpected service tier config: $seen_service_tier" >&2',
-              `  exit 5`,
-              "fi",
-            ]
-          : []),
-        ...(input.requireReasoningEffort !== undefined
-          ? [
-              `if [ "$seen_reasoning_effort" != "model_reasoning_effort=\\"${input.requireReasoningEffort}\\"" ]; then`,
-              '  printf "%s\\n" "unexpected reasoning effort config: $seen_reasoning_effort" >&2',
-              `  exit 6`,
-              "fi",
-            ]
-          : []),
-        ...(input.forbidReasoningEffort
-          ? [
-              'if [ -n "$seen_reasoning_effort" ]; then',
-              '  printf "%s\\n" "reasoning effort config should be omitted: $seen_reasoning_effort" >&2',
-              `  exit 7`,
-              "fi",
-            ]
-          : []),
-        ...(input.stdinMustContain !== undefined
-          ? [
-              // @effect-diagnostics-next-line preferSchemaOverJson:off
-              `if ! printf "%s" "$stdin_content" | grep -F -- ${JSON.stringify(input.stdinMustContain)} >/dev/null; then`,
-              '  printf "%s\\n" "stdin missing expected content" >&2',
-              `  exit 3`,
-              "fi",
-            ]
-          : []),
-        ...(input.stdinMustNotContain !== undefined
-          ? [
-              // @effect-diagnostics-next-line preferSchemaOverJson:off
-              `if printf "%s" "$stdin_content" | grep -F -- ${JSON.stringify(input.stdinMustNotContain)} >/dev/null; then`,
-              '  printf "%s\\n" "stdin contained forbidden content" >&2',
-              `  exit 4`,
-              "fi",
-            ]
-          : []),
-        ...(input.stderr !== undefined
-          ? [
-              // @effect-diagnostics-next-line preferSchemaOverJson:off
-              `printf "%s\\n" ${JSON.stringify(input.stderr)} >&2`,
-            ]
-          : []),
-        'if [ -n "$output_path" ]; then',
-        "  cat > \"$output_path\" <<'__T3CODE_FAKE_CODEX_OUTPUT__'",
-        input.output,
-        "__T3CODE_FAKE_CODEX_OUTPUT__",
-        "fi",
-        `exit ${input.exitCode ?? 0}`,
+    return writeFakeCli({
+      directory: path.join(dir, "bin"),
+      name: "codex",
+      source: [
+        'import * as NodeFS from "node:fs";',
+        `const check = ${check};`,
+        "const args = process.argv.slice(2);",
+        'const originalArgs = ` ${args.join(" ")} `;',
+        "let outputPath = null;",
+        "let seenImage = false;",
+        'let seenServiceTier = "";',
+        'let seenReasoningEffort = "";',
+        "for (let index = 0; index < args.length; index += 1) {",
+        '  if (args[index] === "--image") {',
+        "    index += 1;",
+        "    if (args[index]) seenImage = true;",
+        '  } else if (args[index] === "--config") {',
+        "    index += 1;",
+        '    const value = args[index] ?? "";',
+        '    if (value.startsWith("service_tier=")) seenServiceTier = value;',
+        '    if (value.startsWith("model_reasoning_effort=")) seenReasoningEffort = value;',
+        '  } else if (args[index] === "--output-last-message") {',
+        "    index += 1;",
+        "    outputPath = args[index] ?? null;",
+        "  }",
+        "}",
+        "const chunks = [];",
+        "for await (const chunk of process.stdin) chunks.push(chunk);",
+        'const stdinContent = Buffer.concat(chunks).toString("utf8");',
+        "function fail(message, code) {",
+        '  process.stderr.write(message + "\\n");',
+        "  process.exit(code);",
+        "}",
+        "if (check.requireArg !== null && !originalArgs.includes(` ${check.requireArg} `)) {",
+        '  fail("missing arg: " + check.requireArg, 8);',
+        "}",
+        "if (check.forbidArg !== null && originalArgs.includes(` ${check.forbidArg} `)) {",
+        '  fail("forbidden arg: " + check.forbidArg, 9);',
+        "}",
+        'if (check.requireImage && !seenImage) fail("missing --image input", 2);',
+        "if (",
+        "  check.requireServiceTier !== null &&",
+        '  seenServiceTier !== `service_tier="${check.requireServiceTier}"`',
+        ") {",
+        '  fail("unexpected service tier config: " + seenServiceTier, 5);',
+        "}",
+        "if (",
+        "  check.requireReasoningEffort !== null &&",
+        '  seenReasoningEffort !== `model_reasoning_effort="${check.requireReasoningEffort}"`',
+        ") {",
+        '  fail("unexpected reasoning effort config: " + seenReasoningEffort, 6);',
+        "}",
+        "if (check.forbidReasoningEffort && seenReasoningEffort.length > 0) {",
+        '  fail("reasoning effort config should be omitted: " + seenReasoningEffort, 7);',
+        "}",
+        "if (check.stdinMustContain !== null && !stdinContent.includes(check.stdinMustContain)) {",
+        '  fail("stdin missing expected content", 3);',
+        "}",
+        "if (check.stdinMustNotContain !== null && stdinContent.includes(check.stdinMustNotContain)) {",
+        '  fail("stdin contained forbidden content", 4);',
+        "}",
+        'if (check.stderr !== null) process.stderr.write(check.stderr + "\\n");',
+        'if (outputPath !== null) NodeFS.writeFileSync(outputPath, check.output + "\\n");',
+        "process.exitCode = check.exitCode;",
         "",
       ].join("\n"),
-    );
-    yield* fs.chmod(codexPath, 0o755);
-    return codexPath;
+    });
   });
 }
 
 function withFakeCodexEnv<A, E, R>(
-  input: {
-    output: string;
-    exitCode?: number;
-    stderr?: string;
-    requireImage?: boolean;
-    requireServiceTier?: string;
-    requireReasoningEffort?: string;
-    forbidReasoningEffort?: boolean;
-    requireArg?: string;
-    forbidArg?: string;
-    stdinMustContain?: string;
-    stdinMustNotContain?: string;
+  input: FakeCodexInput & {
     launchArgs?: string;
     environment?: NodeJS.ProcessEnv;
   },
diff --git a/apps/server/src/textGeneration/CursorTextGeneration.test.ts b/apps/server/src/textGeneration/CursorTextGeneration.test.ts
index 2dc4720dcadb..22baa75fb8ed 100644
--- a/apps/server/src/textGeneration/CursorTextGeneration.test.ts
+++ b/apps/server/src/textGeneration/CursorTextGeneration.test.ts
@@ -11,6 +11,7 @@ import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
 import * as Layer from "effect/Layer";
 import * as Schema from "effect/Schema";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 import { createModelSelection } from "@t3tools/shared/model";
 import { expect } from "vite-plus/test";
 
@@ -19,39 +20,26 @@ import { CursorSettings, ProviderInstanceId } from "@t3tools/contracts";
 import * as ServerConfig from "../config.ts";
 import * as TextGeneration from "./TextGeneration.ts";
 import { makeCursorTextGeneration } from "./CursorTextGeneration.ts";
+import { execScriptSource, writeFakeCli } from "../testUtils/fakeCli.ts";
 const decodeCursorSettings = Schema.decodeSync(CursorSettings);
 
 const __dirname = NodePath.dirname(NodeURL.fileURLToPath(import.meta.url));
 const mockAgentPath = NodePath.join(__dirname, "../../scripts/acp-mock-agent.ts");
 
-function shellSingleQuote(value: string): string {
-  return `'${value.replaceAll("'", `'"'"'`)}'`;
-}
-
 const CursorTextGenerationTestLayer = ServerConfig.ServerConfig.layerTest(process.cwd(), {
   prefix: "t3code-cursor-text-generation-test-",
 }).pipe(Layer.provideMerge(NodeServices.layer));
 
 function makeAcpAgentWrapper(dir: string, env: Record<string, string>): string {
-  const binDir = NodePath.join(dir, "bin");
-  const agentPath = NodePath.join(binDir, "agent");
-  NodeFS.mkdirSync(binDir, { recursive: true });
-  NodeFS.writeFileSync(
-    agentPath,
-    [
-      "#!/bin/sh",
-      ...Object.entries(env).map(([key, value]) => `export ${key}=${shellSingleQuote(value)}`),
-      'if [ "$1" != "acp" ]; then',
-      '  printf "%s\\n" "unexpected args: $*" >&2',
-      "  exit 11",
-      "fi",
-      `exec node ${JSON.stringify(mockAgentPath)}`,
-      "",
-    ].join("\n"),
-    "utf8",
-  );
-  NodeFS.chmodSync(agentPath, 0o755);
-  return agentPath;
+  return writeFakeCli({
+    directory: NodePath.join(dir, "bin"),
+    name: "agent",
+    env,
+    source: execScriptSource({
+      scriptPath: mockAgentPath,
+      expectedArgs: ["acp"],
+    }),
+  });
 }
 
 function withFakeAcpAgent<A, E, R>(
@@ -236,41 +224,46 @@ it.layer(CursorTextGenerationTestLayer)("CursorTextGeneration", (it) => {
     ),
   );
 
-  it.effect("closes the ACP child process after text generation completes", () => {
-    const exitLogDir = NodeFS.mkdtempSync(
-      NodePath.join(NodeOS.tmpdir(), "t3code-cursor-text-exit-log-"),
-    );
-    const exitLogPath = NodePath.join(exitLogDir, "exit.log");
+  // Closing the runtime on Windows is taskkill /F, which never lets the mock
+  // agent reach its exit handler, so there is no exit log to assert on.
+  it.effect.skipIf(HostProcessPlatform.defaultValue() === "win32")(
+    "closes the ACP child process after text generation completes",
+    () => {
+      const exitLogDir = NodeFS.mkdtempSync(
+        NodePath.join(NodeOS.tmpdir(), "t3code-cursor-text-exit-log-"),
+      );
+      const exitLogPath = NodePath.join(exitLogDir, "exit.log");
 
-    return withFakeAcpAgent(
-      {
-        T3_ACP_EXIT_LOG_PATH: exitLogPath,
-        T3_ACP_PROMPT_RESPONSE_TEXT: JSON.stringify({
-          subject: "Close runtime after generation",
-          body: "",
-        }),
-      },
-      (textGeneration) =>
-        Effect.gen(function* () {
-          const generated = yield* textGeneration.generateCommitMessage({
-            cwd: process.cwd(),
-            branch: "feature/cursor-runtime-close",
-            stagedSummary: "M apps/server/src/textGeneration/CursorTextGeneration.ts",
-            stagedPatch:
-              "diff --git a/apps/server/src/textGeneration/CursorTextGeneration.ts b/apps/server/src/textGeneration/CursorTextGeneration.ts",
-            modelSelection: {
-              instanceId: ProviderInstanceId.make("cursor"),
-              model: "composer-2",
-            },
-          });
+      return withFakeAcpAgent(
+        {
+          T3_ACP_EXIT_LOG_PATH: exitLogPath,
+          T3_ACP_PROMPT_RESPONSE_TEXT: JSON.stringify({
+            subject: "Close runtime after generation",
+            body: "",
+          }),
+        },
+        (textGeneration) =>
+          Effect.gen(function* () {
+            const generated = yield* textGeneration.generateCommitMessage({
+              cwd: process.cwd(),
+              branch: "feature/cursor-runtime-close",
+              stagedSummary: "M apps/server/src/textGeneration/CursorTextGeneration.ts",
+              stagedPatch:
+                "diff --git a/apps/server/src/textGeneration/CursorTextGeneration.ts b/apps/server/src/textGeneration/CursorTextGeneration.ts",
+              modelSelection: {
+                instanceId: ProviderInstanceId.make("cursor"),
+                model: "composer-2",
+              },
+            });
 
-          expect(generated.subject).toBe("Close runtime after generation");
+            expect(generated.subject).toBe("Close runtime after generation");
 
-          const exitLog = yield* waitForFileContent(exitLogPath);
-          expect(exitLog).toContain("exit:0");
+            const exitLog = yield* waitForFileContent(exitLogPath);
+            expect(exitLog).toContain("exit:0");
 
-          NodeFS.rmSync(exitLogDir, { recursive: true, force: true });
-        }),
-    );
-  });
+            NodeFS.rmSync(exitLogDir, { recursive: true, force: true });
+          }),
+      );
+    },
+  );
 });
diff --git a/apps/server/src/textGeneration/GrokTextGeneration.test.ts b/apps/server/src/textGeneration/GrokTextGeneration.test.ts
index 85127b519b98..e1622c8aaeca 100644
--- a/apps/server/src/textGeneration/GrokTextGeneration.test.ts
+++ b/apps/server/src/textGeneration/GrokTextGeneration.test.ts
@@ -16,39 +16,26 @@ import { GrokSettings, ProviderInstanceId } from "@t3tools/contracts";
 import * as ServerConfig from "../config.ts";
 import * as TextGeneration from "./TextGeneration.ts";
 import { makeGrokTextGeneration } from "./GrokTextGeneration.ts";
+import { execScriptSource, writeFakeCli } from "../testUtils/fakeCli.ts";
 const decodeGrokSettings = Schema.decodeSync(GrokSettings);
 
 const __dirname = NodePath.dirname(NodeURL.fileURLToPath(import.meta.url));
 const mockAgentPath = NodePath.join(__dirname, "../../scripts/acp-mock-agent.ts");
 
-function shellSingleQuote(value: string): string {
-  return `'${value.replaceAll("'", `'"'"'`)}'`;
-}
-
 const GrokTextGenerationTestLayer = ServerConfig.ServerConfig.layerTest(process.cwd(), {
   prefix: "t3code-grok-text-generation-test-",
 }).pipe(Layer.provideMerge(NodeServices.layer));
 
 function makeAcpGrokWrapper(dir: string, env: Record<string, string>): string {
-  const binDir = NodePath.join(dir, "bin");
-  const grokPath = NodePath.join(binDir, "grok");
-  NodeFS.mkdirSync(binDir, { recursive: true });
-  NodeFS.writeFileSync(
-    grokPath,
-    [
-      "#!/bin/sh",
-      ...Object.entries(env).map(([key, value]) => `export ${key}=${shellSingleQuote(value)}`),
-      'if [ "$1" != "agent" ] || [ "$2" != "stdio" ]; then',
-      '  printf "%s\\n" "unexpected args: $*" >&2',
-      "  exit 11",
-      "fi",
-      `exec ${JSON.stringify(process.execPath)} ${JSON.stringify(mockAgentPath)}`,
-      "",
-    ].join("\n"),
-    "utf8",
-  );
-  NodeFS.chmodSync(grokPath, 0o755);
-  return grokPath;
+  return writeFakeCli({
+    directory: NodePath.join(dir, "bin"),
+    name: "grok",
+    env,
+    source: execScriptSource({
+      scriptPath: mockAgentPath,
+      expectedArgs: ["agent", "stdio"],
+    }),
+  });
 }
 
 function withFakeAcpGrok<A, E, R>(

From c251e41b5e5287b786cda44ddc263b8e6a74859c Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 13:33:20 -0700
Subject: [PATCH 12/56] test(desktop): make path fixtures and timeouts
 host-portable (#9568)

Co-authored-by: Claude Code <noreply@anthropic.com>
---
 apps/desktop/scripts/electron-launcher.mjs    |  12 +-
 .../scripts/electron-launcher.test.mjs        |   5 +-
 .../app/DesktopConnectionCatalogStore.test.ts |  31 ++--
 .../src/preview/BrowserImport/Sources.test.ts | 158 ++++++++++--------
 .../settings/DesktopSavedEnvironments.test.ts |  11 +-
 apps/desktop/vite.config.ts                   |   5 +
 6 files changed, 134 insertions(+), 88 deletions(-)

diff --git a/apps/desktop/scripts/electron-launcher.mjs b/apps/desktop/scripts/electron-launcher.mjs
index 07fb87b051f1..496a8a27a7b6 100644
--- a/apps/desktop/scripts/electron-launcher.mjs
+++ b/apps/desktop/scripts/electron-launcher.mjs
@@ -165,10 +165,14 @@ function registerMacLauncherBundle(appBundlePath) {
   }
 }
 
+// Bundle-internal paths are macOS paths whatever host builds them.
 export function resolveMacLauncherIconPaths(runtimeDir, development = isDevelopment) {
   return {
     sourceIconPath: development ? developmentMacIconPngPath : productionMacIconPngPath,
-    generatedIconPath: NodePath.join(runtimeDir, development ? "icon-dev.icns" : "icon-prod.icns"),
+    generatedIconPath: NodePath.posix.join(
+      runtimeDir,
+      development ? "icon-dev.icns" : "icon-prod.icns",
+    ),
   };
 }
 
@@ -280,12 +284,12 @@ function readJson(path) {
 }
 
 export function resolveMacLauncherPaths(appBundlePath, displayName = APP_DISPLAY_NAME) {
-  const executableDir = NodePath.join(appBundlePath, "Contents", "MacOS");
+  const executableDir = NodePath.posix.join(appBundlePath, "Contents", "MacOS");
   const launcherExecutableName = `${displayName} Launcher`;
   return {
     launcherExecutableName,
-    launcherBinaryPath: NodePath.join(executableDir, launcherExecutableName),
-    runtimeElectronBinaryPath: NodePath.join(executableDir, "Electron"),
+    launcherBinaryPath: NodePath.posix.join(executableDir, launcherExecutableName),
+    runtimeElectronBinaryPath: NodePath.posix.join(executableDir, "Electron"),
   };
 }
 
diff --git a/apps/desktop/scripts/electron-launcher.test.mjs b/apps/desktop/scripts/electron-launcher.test.mjs
index 1ed5a1b8ebf9..9d2a907c73d6 100644
--- a/apps/desktop/scripts/electron-launcher.test.mjs
+++ b/apps/desktop/scripts/electron-launcher.test.mjs
@@ -84,9 +84,10 @@ describe("electron development launcher", () => {
     const development = resolveMacLauncherIconPaths("/runtime", true);
     const production = resolveMacLauncherIconPaths("/runtime", false);
 
-    assert.match(development.sourceIconPath, /assets\/dev\/blueprint-macos-1024\.png$/);
+    // The source icons are real repo paths, joined for the host.
+    assert.match(development.sourceIconPath, /assets[\\/]dev[\\/]blueprint-macos-1024\.png$/);
     assert.equal(development.generatedIconPath, "/runtime/icon-dev.icns");
-    assert.match(production.sourceIconPath, /assets\/prod\/black-macos-1024\.png$/);
+    assert.match(production.sourceIconPath, /assets[\\/]prod[\\/]black-macos-1024\.png$/);
     assert.equal(production.generatedIconPath, "/runtime/icon-prod.icns");
   });
 });
diff --git a/apps/desktop/src/app/DesktopConnectionCatalogStore.test.ts b/apps/desktop/src/app/DesktopConnectionCatalogStore.test.ts
index c58830b30a7f..aa28ff8d86eb 100644
--- a/apps/desktop/src/app/DesktopConnectionCatalogStore.test.ts
+++ b/apps/desktop/src/app/DesktopConnectionCatalogStore.test.ts
@@ -4,6 +4,7 @@ import { ConnectionCatalogDocument } from "@t3tools/client-runtime/platform";
 import { EnvironmentId, type PersistedSavedEnvironmentRecord } from "@t3tools/contracts";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import * as PlatformError from "effect/PlatformError";
@@ -226,10 +227,11 @@ describe("DesktopConnectionCatalogStore", () => {
   it.effect("surfaces malformed catalog documents without deleting them", () =>
     withStore(
       Effect.gen(function* () {
+        const path = yield* Path.Path;
         const environment = yield* DesktopEnvironment.DesktopEnvironment;
         const fileSystem = yield* FileSystem.FileSystem;
         const store = yield* DesktopConnectionCatalogStore.DesktopConnectionCatalogStore;
-        const catalogPath = `${environment.stateDir}/connection-catalog.json`;
+        const catalogPath = path.join(environment.stateDir, "connection-catalog.json");
         yield* fileSystem.makeDirectory(environment.stateDir, { recursive: true });
         yield* fileSystem.writeFileString(catalogPath, "{not-json");
 
@@ -247,6 +249,7 @@ describe("DesktopConnectionCatalogStore", () => {
 
   it.effect("surfaces catalog filesystem failures instead of treating them as missing", () =>
     Effect.gen(function* () {
+      const path = yield* Path.Path;
       const baseFileSystem = yield* FileSystem.FileSystem;
       const baseDir = yield* baseFileSystem.makeTempDirectoryScoped({
         prefix: "t3-desktop-connection-catalog-test-",
@@ -255,7 +258,7 @@ describe("DesktopConnectionCatalogStore", () => {
         _tag: "PermissionDenied",
         module: "FileSystem",
         method: "readFileString",
-        pathOrDescriptor: `${baseDir}/userdata/connection-catalog.json`,
+        pathOrDescriptor: path.join(baseDir, "userdata", "connection-catalog.json"),
       });
       const fileSystemLayer = Layer.succeed(
         FileSystem.FileSystem,
@@ -272,11 +275,11 @@ describe("DesktopConnectionCatalogStore", () => {
         error,
         DesktopConnectionCatalogStore.DesktopConnectionCatalogStoreReadError,
       );
-      assert.equal(error.catalogPath, `${baseDir}/userdata/connection-catalog.json`);
+      assert.equal(error.catalogPath, path.join(baseDir, "userdata", "connection-catalog.json"));
       assert.strictEqual(error.cause, permissionError);
       assert.equal(
         error.message,
-        `Failed to read the desktop connection catalog at ${baseDir}/userdata/connection-catalog.json.`,
+        `Failed to read the desktop connection catalog at ${path.join(baseDir, "userdata", "connection-catalog.json")}.`,
       );
       assert.notEqual(error.message, permissionError.message);
     }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
@@ -285,6 +288,7 @@ describe("DesktopConnectionCatalogStore", () => {
   it.effect("reports the failed catalog write operation and path", () =>
     Effect.gen(function* () {
       const baseFileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
       const baseDir = yield* baseFileSystem.makeTempDirectoryScoped({
         prefix: "t3-desktop-connection-catalog-test-",
       });
@@ -292,7 +296,7 @@ describe("DesktopConnectionCatalogStore", () => {
         _tag: "PermissionDenied",
         module: "FileSystem",
         method: "makeDirectory",
-        pathOrDescriptor: `${baseDir}/userdata`,
+        pathOrDescriptor: path.join(baseDir, "userdata"),
       });
       const fileSystemLayer = Layer.succeed(
         FileSystem.FileSystem,
@@ -310,11 +314,11 @@ describe("DesktopConnectionCatalogStore", () => {
         DesktopConnectionCatalogStore.DesktopConnectionCatalogStoreWriteError,
       );
       assert.equal(error.operation, "create-directory");
-      assert.equal(error.path, `${baseDir}/userdata`);
+      assert.equal(error.path, path.join(baseDir, "userdata"));
       assert.strictEqual(error.cause, permissionError);
       assert.equal(
         error.message,
-        `Desktop connection catalog write failed during create-directory at ${baseDir}/userdata.`,
+        `Desktop connection catalog write failed during create-directory at ${path.join(baseDir, "userdata")}.`,
       );
       assert.notEqual(error.message, permissionError.message);
     }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
@@ -323,6 +327,7 @@ describe("DesktopConnectionCatalogStore", () => {
   it.effect("reports the legacy migration stage", () =>
     withStore(
       Effect.gen(function* () {
+        const path = yield* Path.Path;
         const environment = yield* DesktopEnvironment.DesktopEnvironment;
         const fileSystem = yield* FileSystem.FileSystem;
         const store = yield* DesktopConnectionCatalogStore.DesktopConnectionCatalogStore;
@@ -335,7 +340,7 @@ describe("DesktopConnectionCatalogStore", () => {
           DesktopConnectionCatalogStore.DesktopConnectionCatalogStoreMigrationError,
         );
         assert.equal(error.operation, "read-legacy-registry");
-        assert.equal(error.catalogPath, `${environment.stateDir}/connection-catalog.json`);
+        assert.equal(error.catalogPath, path.join(environment.stateDir, "connection-catalog.json"));
         assert.instanceOf(
           error.cause,
           DesktopSavedEnvironments.DesktopSavedEnvironmentsDocumentDecodeError,
@@ -345,7 +350,7 @@ describe("DesktopConnectionCatalogStore", () => {
         assert.exists(registryError.cause);
         assert.equal(
           error.message,
-          `Legacy desktop saved-environment migration failed during read-legacy-registry into ${environment.stateDir}/connection-catalog.json.`,
+          `Legacy desktop saved-environment migration failed during read-legacy-registry into ${path.join(environment.stateDir, "connection-catalog.json")}.`,
         );
         assert.notEqual(error.message, registryError.message);
       }),
@@ -355,10 +360,11 @@ describe("DesktopConnectionCatalogStore", () => {
   it.effect("reports invalid encrypted catalog data without exposing it", () =>
     withStore(
       Effect.gen(function* () {
+        const path = yield* Path.Path;
         const environment = yield* DesktopEnvironment.DesktopEnvironment;
         const fileSystem = yield* FileSystem.FileSystem;
         const store = yield* DesktopConnectionCatalogStore.DesktopConnectionCatalogStore;
-        const catalogPath = `${environment.stateDir}/connection-catalog.json`;
+        const catalogPath = path.join(environment.stateDir, "connection-catalog.json");
         yield* fileSystem.makeDirectory(environment.stateDir, { recursive: true });
         yield* fileSystem.writeFileString(catalogPath, '{"version":1,"encryptedCatalog":"%%%"}\n');
 
@@ -381,6 +387,7 @@ describe("DesktopConnectionCatalogStore", () => {
 
   it.effect("surfaces a catalog that can no longer be decrypted without deleting it", () =>
     Effect.gen(function* () {
+      const path = yield* Path.Path;
       const fileSystem = yield* FileSystem.FileSystem;
       const baseDir = yield* fileSystem.makeTempDirectoryScoped({
         prefix: "t3-desktop-connection-catalog-test-",
@@ -399,14 +406,14 @@ describe("DesktopConnectionCatalogStore", () => {
         DesktopConnectionCatalogStore.DesktopConnectionCatalogStoreProtectionError,
       );
       assert.equal(error.operation, "decrypt-catalog");
-      assert.equal(error.catalogPath, `${baseDir}/userdata/connection-catalog.json`);
+      assert.equal(error.catalogPath, path.join(baseDir, "userdata", "connection-catalog.json"));
       assert.instanceOf(error.cause, ElectronSafeStorage.ElectronSafeStorageDecryptError);
       const decryptError = error.cause as ElectronSafeStorage.ElectronSafeStorageDecryptError;
       assert.instanceOf(decryptError.cause, Error);
       assert.equal(decryptError.cause.message, "invalid encrypted catalog");
       assert.equal(
         error.message,
-        `Desktop connection catalog protection failed during decrypt-catalog at ${baseDir}/userdata/connection-catalog.json.`,
+        `Desktop connection catalog protection failed during decrypt-catalog at ${path.join(baseDir, "userdata", "connection-catalog.json")}.`,
       );
       assert.notEqual(error.message, decryptError.message);
       yield* Ref.set(failDecrypt, false);
diff --git a/apps/desktop/src/preview/BrowserImport/Sources.test.ts b/apps/desktop/src/preview/BrowserImport/Sources.test.ts
index 282bf10d36d3..a83290448a4a 100644
--- a/apps/desktop/src/preview/BrowserImport/Sources.test.ts
+++ b/apps/desktop/src/preview/BrowserImport/Sources.test.ts
@@ -1,5 +1,6 @@
 // @effect-diagnostics nodeBuiltinImport:off - Builds a Chromium-shaped cookie
 // table with the same native bindings the source reads.
+import * as NodePath from "node:path";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, describe, it } from "@effect/vitest";
 import {
@@ -531,7 +532,7 @@ Path=Profiles/wxyz.empty
         yield* fileSystem.makeDirectory(`${root}/Profiles/wxyz.empty`, { recursive: true });
 
         assert.deepEqual(yield* listSourceProfiles(firefox, context), [
-          { directory: "Profiles/abcd.default-release", name: "original" },
+          { directory: context.path.join("Profiles", "abcd.default-release"), name: "original" },
         ]);
       }),
     ),
@@ -612,10 +613,16 @@ describe("cookieDatabaseCandidatePaths", () => {
     run(
       Effect.gen(function* () {
         const context = yield* withSourceHome();
-        const profile = `${context.home}/Library/Application Support/net.imput.helium/Profile 1`;
+        const profile = context.path.join(
+          context.home,
+          "Library",
+          "Application Support",
+          "net.imput.helium",
+          "Profile 1",
+        );
         assert.deepEqual(cookieDatabaseCandidatePaths(helium, context, "Profile 1"), [
-          `${profile}/Network/Cookies`,
-          `${profile}/Cookies`,
+          context.path.join(profile, "Network", "Cookies"),
+          context.path.join(profile, "Cookies"),
         ]);
       }),
     ),
@@ -626,7 +633,7 @@ describe("cookieDatabaseCandidatePaths", () => {
       Effect.gen(function* () {
         const fileSystem = yield* FileSystem.FileSystem;
         const context = yield* withSourceHome();
-        const root = helium.userDataDirectory(context);
+        const root = userDataDirectory(context);
         // Chromium 96+ keeps sessions in Network/; a root Cookies left behind
         // by the move is stale and must not be the one imported.
         yield* fileSystem.makeDirectory(`${root}/Default/Network`, { recursive: true });
@@ -635,7 +642,7 @@ describe("cookieDatabaseCandidatePaths", () => {
 
         assert.equal(
           yield* resolveCookieDatabase(helium, context, "Default"),
-          `${root}/Default/Network/Cookies`,
+          context.path.join(root, "Default", "Network", "Cookies"),
         );
         // A fresh install with only the Network/ jar is installed, not hidden.
         yield* fileSystem.remove(`${root}/Default/Cookies`);
@@ -680,8 +687,8 @@ describe("Firefox Snap profiles", () => {
             Effect.provideService(HostProcessEnvironment, { HOME: home }),
             Effect.provideService(HostProcessPlatform, "linux"),
           );
-          const root = `${home}/snap/firefox/common/.mozilla/firefox`;
-          const directory = `${root}/abcd.default`;
+          const root = context.path.join(home, "snap", "firefox", "common", ".mozilla", "firefox");
+          const directory = context.path.join(root, "abcd.default");
           yield* fileSystem.makeDirectory(directory, { recursive: true });
           yield* writeFirefoxCookieDatabase(`${directory}/cookies.sqlite`, 2, 1);
           yield* fileSystem.writeFileString(
@@ -695,7 +702,7 @@ describe("Firefox Snap profiles", () => {
           ]);
           assert.equal(
             yield* resolveCookieDatabase(firefox, context, directory),
-            `${directory}/cookies.sqlite`,
+            context.path.join(directory, "cookies.sqlite"),
           );
           assert.isFalse(yield* isSourceRunning(firefox, context));
           yield* fileSystem.symlink("foreign-host:+4242", `${directory}/lock`);
@@ -720,8 +727,8 @@ describe("Firefox Snap profiles", () => {
           Effect.provideService(HostProcessEnvironment, { HOME: home }),
           Effect.provideService(HostProcessPlatform, "linux"),
         );
-        const native = `${home}/.mozilla/firefox`;
-        const snap = `${home}/snap/firefox/common/.mozilla/firefox`;
+        const native = context.path.join(home, ".mozilla", "firefox");
+        const snap = context.path.join(home, "snap", "firefox", "common", ".mozilla", "firefox");
         for (const root of [native, snap]) {
           yield* fileSystem.makeDirectory(`${root}/abcd.default`, { recursive: true });
           yield* writeFirefoxCookieDatabase(`${root}/abcd.default/cookies.sqlite`, 1, 0);
@@ -735,14 +742,14 @@ describe("Firefox Snap profiles", () => {
         const profiles = yield* listSourceProfiles(firefox, context);
         assert.deepEqual(
           profiles.map((profile) => profile.directory),
-          ["abcd.default", `${snap}/abcd.default`],
+          ["abcd.default", context.path.join(snap, "abcd.default")],
         );
         const databases = yield* Effect.forEach(profiles, (profile) =>
           resolveCookieDatabase(firefox, context, profile.directory),
         );
         assert.deepEqual(databases, [
-          `${native}/abcd.default/cookies.sqlite`,
-          `${snap}/abcd.default/cookies.sqlite`,
+          context.path.join(native, "abcd.default", "cookies.sqlite"),
+          context.path.join(snap, "abcd.default", "cookies.sqlite"),
         ]);
       }),
     ),
@@ -752,8 +759,8 @@ describe("Firefox Snap profiles", () => {
 describe("listSourceProfiles Firefox fallback", () => {
   const cases = [
     { platform: "linux" as const, profileDirectory: "linux.default" },
-    { platform: "darwin" as const, profileDirectory: "Profiles/macos.default" },
-    { platform: "win32" as const, profileDirectory: "Profiles/windows.default" },
+    { platform: "darwin" as const, profileDirectory: NodePath.join("Profiles", "macos.default") },
+    { platform: "win32" as const, profileDirectory: NodePath.join("Profiles", "windows.default") },
   ];
 
   for (const { platform, profileDirectory } of cases) {
@@ -824,7 +831,11 @@ describe("listSourceProfiles Firefox fallback", () => {
 
         // Returning the empty declared list would hide the browser entirely.
         assert.deepEqual(yield* listSourceProfiles(firefox, context), [
-          { directory: "Profiles/real.default", name: "real.default", cookieCount: 3 },
+          {
+            directory: path.join("Profiles", "real.default"),
+            name: "real.default",
+            cookieCount: 3,
+          },
         ]);
         assert.isTrue(yield* isSourceInstalled(firefox, context));
       }),
@@ -855,7 +866,11 @@ describe("listSourceProfiles Firefox fallback", () => {
         );
 
         assert.deepEqual(yield* listSourceProfiles(firefox, context), [
-          { directory: "Profiles/declared.default", name: "Declared", cookieCount: 2 },
+          {
+            directory: path.join("Profiles", "declared.default"),
+            name: "Declared",
+            cookieCount: 2,
+          },
         ]);
 
         yield* fileSystem.remove(path.join(root, "profiles.ini"));
@@ -864,8 +879,16 @@ describe("listSourceProfiles Firefox fallback", () => {
         yield* writeFirefoxCookieDatabase(path.join(fallbackDirectory, "cookies.sqlite"), 1, 4);
 
         assert.deepEqual(yield* listSourceProfiles(firefox, context), [
-          { directory: "Profiles/declared.default", name: "declared.default", cookieCount: 2 },
-          { directory: "Profiles/fallback.default", name: "fallback.default", cookieCount: 1 },
+          {
+            directory: path.join("Profiles", "declared.default"),
+            name: "declared.default",
+            cookieCount: 2,
+          },
+          {
+            directory: path.join("Profiles", "fallback.default"),
+            name: "fallback.default",
+            cookieCount: 1,
+          },
         ]);
       }),
     ),
@@ -928,53 +951,56 @@ describe("isSourceRunning for Firefox", () => {
     ),
   );
 
-  it.effect("detects a live fcntl lock on .parentlock, as macOS Firefox leaves it", () =>
-    run(
-      Effect.gen(function* () {
-        const fileSystem = yield* FileSystem.FileSystem;
-        const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-        const home = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3code-firefox-" });
-        const context = yield* sourcePathContext.pipe(
-          Effect.provideService(HostProcessEnvironment, { HOME: home }),
-          Effect.provideService(HostProcessPlatform, "darwin"),
-        );
-        const root = firefox.userDataDirectory(context)!;
-        const profile = `${root}/Profiles/abcd.default-release`;
-        yield* fileSystem.makeDirectory(profile, { recursive: true });
-        yield* fileSystem.writeFileString(`${profile}/cookies.sqlite`, "db");
-        const parentLock = `${profile}/.parentlock`;
-        yield* fileSystem.writeFileString(parentLock, "");
-
-        // Hold the lock from a child the way Firefox does (F_SETLK, write),
-        // and keep it until the scope closes.
-        const holder = yield* spawner.spawn(
-          ChildProcess.make(
-            "python3",
-            [
-              "-c",
-              "import fcntl,os,sys,time\n" +
-                "fd=os.open(sys.argv[1],os.O_WRONLY)\n" +
-                "fcntl.lockf(fd,fcntl.LOCK_EX|fcntl.LOCK_NB)\n" +
-                "print('locked',flush=True)\n" +
-                "time.sleep(30)",
-              parentLock,
-            ],
-            { stdin: "ignore" },
-          ),
-        );
-        // Wait for the child to confirm it holds the lock before probing.
-        yield* holder.stdout.pipe(
-          Stream.decodeText(),
-          Stream.splitLines,
-          Stream.filter((line) => line.trim() === "locked"),
-          Stream.take(1),
-          Stream.runDrain,
-        );
+  // Holds the lock with python3's fcntl, which does not exist on Windows.
+  it.effect.skipIf(HostProcessPlatform.defaultValue() === "win32")(
+    "detects a live fcntl lock on .parentlock, as macOS Firefox leaves it",
+    () =>
+      run(
+        Effect.gen(function* () {
+          const fileSystem = yield* FileSystem.FileSystem;
+          const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+          const home = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3code-firefox-" });
+          const context = yield* sourcePathContext.pipe(
+            Effect.provideService(HostProcessEnvironment, { HOME: home }),
+            Effect.provideService(HostProcessPlatform, "darwin"),
+          );
+          const root = firefox.userDataDirectory(context)!;
+          const profile = `${root}/Profiles/abcd.default-release`;
+          yield* fileSystem.makeDirectory(profile, { recursive: true });
+          yield* fileSystem.writeFileString(`${profile}/cookies.sqlite`, "db");
+          const parentLock = `${profile}/.parentlock`;
+          yield* fileSystem.writeFileString(parentLock, "");
+
+          // Hold the lock from a child the way Firefox does (F_SETLK, write),
+          // and keep it until the scope closes.
+          const holder = yield* spawner.spawn(
+            ChildProcess.make(
+              "python3",
+              [
+                "-c",
+                "import fcntl,os,sys,time\n" +
+                  "fd=os.open(sys.argv[1],os.O_WRONLY)\n" +
+                  "fcntl.lockf(fd,fcntl.LOCK_EX|fcntl.LOCK_NB)\n" +
+                  "print('locked',flush=True)\n" +
+                  "time.sleep(30)",
+                parentLock,
+              ],
+              { stdin: "ignore" },
+            ),
+          );
+          // Wait for the child to confirm it holds the lock before probing.
+          yield* holder.stdout.pipe(
+            Stream.decodeText(),
+            Stream.splitLines,
+            Stream.filter((line) => line.trim() === "locked"),
+            Stream.take(1),
+            Stream.runDrain,
+          );
 
-        assert.isTrue(yield* isSourceRunning(firefox, context));
-        yield* holder.kill();
-      }),
-    ),
+          assert.isTrue(yield* isSourceRunning(firefox, context));
+          yield* holder.kill();
+        }),
+      ),
   );
 
   it.effect("reads a Firefox lock symlink's pid to tell live from crashed", () =>
diff --git a/apps/desktop/src/settings/DesktopSavedEnvironments.test.ts b/apps/desktop/src/settings/DesktopSavedEnvironments.test.ts
index 05b1ca144444..348f6cb3843e 100644
--- a/apps/desktop/src/settings/DesktopSavedEnvironments.test.ts
+++ b/apps/desktop/src/settings/DesktopSavedEnvironments.test.ts
@@ -3,6 +3,7 @@ import { assert, describe, it } from "@effect/vitest";
 import { EnvironmentId, type PersistedSavedEnvironmentRecord } from "@t3tools/contracts";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import * as PlatformError from "effect/PlatformError";
@@ -400,11 +401,12 @@ describe("DesktopSavedEnvironments", () => {
 
   it.effect("reports saved environment filesystem reads separately from document decoding", () =>
     Effect.gen(function* () {
+      const path = yield* Path.Path;
       const baseFileSystem = yield* FileSystem.FileSystem;
       const baseDir = yield* baseFileSystem.makeTempDirectoryScoped({
         prefix: "t3-desktop-saved-environments-test-",
       });
-      const registryPath = `${baseDir}/userdata/saved-environments.json`;
+      const registryPath = path.join(baseDir, "userdata", "saved-environments.json");
       const permissionError = PlatformError.systemError({
         _tag: "PermissionDenied",
         module: "FileSystem",
@@ -433,6 +435,7 @@ describe("DesktopSavedEnvironments", () => {
   it.effect("reports the failed saved environment write operation and path", () =>
     Effect.gen(function* () {
       const baseFileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
       const baseDir = yield* baseFileSystem.makeTempDirectoryScoped({
         prefix: "t3-desktop-saved-environments-test-",
       });
@@ -440,7 +443,7 @@ describe("DesktopSavedEnvironments", () => {
         _tag: "PermissionDenied",
         module: "FileSystem",
         method: "makeDirectory",
-        pathOrDescriptor: `${baseDir}/userdata`,
+        pathOrDescriptor: path.join(baseDir, "userdata"),
       });
       const fileSystemLayer = Layer.succeed(
         FileSystem.FileSystem,
@@ -456,11 +459,11 @@ describe("DesktopSavedEnvironments", () => {
       const error = yield* savedEnvironments.setRegistry([savedRegistryRecord]).pipe(Effect.flip);
       assert.instanceOf(error, DesktopSavedEnvironments.DesktopSavedEnvironmentsWriteError);
       assert.equal(error.operation, "create-directory");
-      assert.equal(error.path, `${baseDir}/userdata`);
+      assert.equal(error.path, path.join(baseDir, "userdata"));
       assert.strictEqual(error.cause, permissionError);
       assert.equal(
         error.message,
-        `Desktop saved-environment write failed during create-directory at ${baseDir}/userdata.`,
+        `Desktop saved-environment write failed during create-directory at ${path.join(baseDir, "userdata")}.`,
       );
       assert.notEqual(error.message, permissionError.message);
     }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
diff --git a/apps/desktop/vite.config.ts b/apps/desktop/vite.config.ts
index ce74cf58e0a3..f0829d4e654f 100644
--- a/apps/desktop/vite.config.ts
+++ b/apps/desktop/vite.config.ts
@@ -83,4 +83,9 @@ export default defineConfig({
       entry: ["src/preview-pip-preload.ts"],
     },
   ],
+  test: {
+    // The Windows lane runs workspace suites concurrently; filesystem-heavy
+    // desktop integration tests can exceed Vitest's 5 second default there.
+    testTimeout: 15_000,
+  },
 });

From f083f520fbde1e1bf4332399df47b45c2bd99722 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 13:33:21 -0700
Subject: [PATCH 13/56] fix(server): tolerate the missing directory fsync on
 Windows (#9569)

Co-authored-by: Claude Code <noreply@anthropic.com>
---
 apps/server/src/cloud/bootService.ts | 11 +++++++++--
 apps/server/src/serviceLauncher.ts   | 15 ++++++++-------
 2 files changed, 17 insertions(+), 9 deletions(-)

diff --git a/apps/server/src/cloud/bootService.ts b/apps/server/src/cloud/bootService.ts
index 50ffcedf74b8..a0bd6f30c6ca 100644
--- a/apps/server/src/cloud/bootService.ts
+++ b/apps/server/src/cloud/bootService.ts
@@ -555,9 +555,16 @@ export const make = Effect.fn("cloud.boot_service.make")(function* (input: {
         yield* fs.makeDirectory(directory, { recursive: true });
         const tempPath = yield* fs.makeTempFileScoped({ directory, prefix: ".service-write-" });
         yield* fs.writeFileString(tempPath, contents, { mode: 0o600 });
-        yield* (yield* fs.open(tempPath, { flag: "r" })).sync;
+        // Opened read-write: Windows refuses to flush a handle without write access.
+        yield* (yield* fs.open(tempPath, { flag: "r+" })).sync;
         yield* fs.rename(tempPath, filePath);
-        yield* (yield* fs.open(directory, { flag: "r" })).sync;
+        // Windows has no directory fsync (EPERM); NTFS journals the rename.
+        yield* (yield* fs.open(directory, { flag: "r" })).sync.pipe(
+          Effect.catchIf(
+            (error) => (error.reason.cause as NodeJS.ErrnoException | undefined)?.code === "EPERM",
+            () => Effect.void,
+          ),
+        );
       }),
     ).pipe(Effect.mapError((cause) => new BootServiceInstallError({ cause })));
   const plan: BootServicePlan = {
diff --git a/apps/server/src/serviceLauncher.ts b/apps/server/src/serviceLauncher.ts
index b99f90e0fdf5..e912130c8939 100644
--- a/apps/server/src/serviceLauncher.ts
+++ b/apps/server/src/serviceLauncher.ts
@@ -70,8 +70,9 @@ async function pathExists(target: string): Promise<boolean> {
   }
 }
 
+// Opened read-write: Windows refuses to flush a handle without write access.
 async function syncFile(filePath: string): Promise<void> {
-  const handle = await NodeFSP.open(filePath, "r");
+  const handle = await NodeFSP.open(filePath, "r+");
   try {
     await handle.sync();
   } finally {
@@ -79,10 +80,15 @@ async function syncFile(filePath: string): Promise<void> {
   }
 }
 
+// Flushes a directory entry so a rename into it survives power loss. Windows
+// has no directory fsync: the handle opens but sync fails with EPERM, and
+// NTFS journals the rename on its own.
 async function syncDirectory(directory: string): Promise<void> {
   const handle = await NodeFSP.open(directory, "r");
   try {
     await handle.sync();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EPERM") throw error;
   } finally {
     await handle.close();
   }
@@ -188,12 +194,7 @@ export async function writeServiceState(filePath: string, state: ServiceState):
     await handle.close();
     handle = undefined;
     await NodeFSP.rename(tempPath, filePath);
-    const directoryHandle = await NodeFSP.open(directory, "r");
-    try {
-      await directoryHandle.sync();
-    } finally {
-      await directoryHandle.close();
-    }
+    await syncDirectory(directory);
   } finally {
     await handle?.close().catch(() => undefined);
     await NodeFSP.rm(tempPath, { force: true }).catch(() => undefined);

From 12b6d026bdfba0cc8438fa5e323a8587d65bd2af Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 13:33:21 -0700
Subject: [PATCH 14/56] test(server): pin git config for fixtures and compare
 native realpaths (#9570)

Co-authored-by: Claude Code <noreply@anthropic.com>
---
 .../RepositoryIdentityResolver.test.ts        | 12 ++--
 apps/server/src/testUtils/gitConfig.setup.ts  | 21 +++++++
 apps/server/src/vcs/GitVcsDriverCore.test.ts  | 56 ++++++++++---------
 apps/server/vite.config.ts                    |  1 +
 4 files changed, 61 insertions(+), 29 deletions(-)
 create mode 100644 apps/server/src/testUtils/gitConfig.setup.ts

diff --git a/apps/server/src/project/RepositoryIdentityResolver.test.ts b/apps/server/src/project/RepositoryIdentityResolver.test.ts
index 72232a78b689..7c73752ee831 100644
--- a/apps/server/src/project/RepositoryIdentityResolver.test.ts
+++ b/apps/server/src/project/RepositoryIdentityResolver.test.ts
@@ -1,3 +1,5 @@
+// @effect-diagnostics nodeBuiltinImport:off - realpathSync.native resolves Windows 8.3 short names, which the Effect realPath does not.
+import * as NodeFS from "node:fs";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { expect, it } from "@effect/vitest";
 import * as Duration from "effect/Duration";
@@ -131,9 +133,11 @@ it.layer(NodeServices.layer)("RepositoryIdentityResolverLive", (it) => {
 
       const resolver = yield* RepositoryIdentityResolver.RepositoryIdentityResolver;
       const identity = yield* resolver.resolve(cwd);
+      // Native realpath, since git reports the long form of a directory the
+      // temp dir may name by its 8.3 short form on Windows.
       const resolvedIdentityRoot =
-        identity?.rootPath === undefined ? "" : yield* fileSystem.realPath(identity.rootPath);
-      const resolvedCwd = yield* fileSystem.realPath(cwd);
+        identity?.rootPath === undefined ? "" : NodeFS.realpathSync.native(identity.rootPath);
+      const resolvedCwd = NodeFS.realpathSync.native(cwd);
 
       expect(identity).not.toBeNull();
       expect(identity?.canonicalKey).toBe("github.com/t3tools/t3code");
@@ -161,8 +165,8 @@ it.layer(NodeServices.layer)("RepositoryIdentityResolverLive", (it) => {
       const resolver = yield* RepositoryIdentityResolver.RepositoryIdentityResolver;
       const identity = yield* resolver.resolve(nestedWorkspace);
       const resolvedIdentityRoot =
-        identity?.rootPath === undefined ? "" : yield* fileSystem.realPath(identity.rootPath);
-      const resolvedRepoRoot = yield* fileSystem.realPath(repoRoot);
+        identity?.rootPath === undefined ? "" : NodeFS.realpathSync.native(identity.rootPath);
+      const resolvedRepoRoot = NodeFS.realpathSync.native(repoRoot);
 
       expect(identity).not.toBeNull();
       expect(identity?.canonicalKey).toBe("github.com/t3tools/t3code");
diff --git a/apps/server/src/testUtils/gitConfig.setup.ts b/apps/server/src/testUtils/gitConfig.setup.ts
new file mode 100644
index 000000000000..03bd860bf0d0
--- /dev/null
+++ b/apps/server/src/testUtils/gitConfig.setup.ts
@@ -0,0 +1,21 @@
+// Pins git behaviour for every repository the suite creates, ahead of the
+// host's ~/.gitconfig. Git for Windows installs with core.autocrlf=true,
+// which checks committed LF files out as CRLF and breaks every byte-exact
+// content assertion; a signing key or a non-default init branch on the
+// developer's machine breaks fixtures the same way. Set as environment so
+// each git child the driver spawns sees it without touching the fixtures.
+const entries: ReadonlyArray<readonly [key: string, value: string]> = [
+  ["core.autocrlf", "false"],
+  ["core.filemode", "false"],
+  ["core.longpaths", "true"],
+  ["commit.gpgsign", "false"],
+  ["tag.gpgsign", "false"],
+  ["init.defaultBranch", "main"],
+];
+
+const existing = Number(process.env.GIT_CONFIG_COUNT ?? "0");
+process.env.GIT_CONFIG_COUNT = String(existing + entries.length);
+entries.forEach(([key, value], index) => {
+  process.env[`GIT_CONFIG_KEY_${existing + index}`] = key;
+  process.env[`GIT_CONFIG_VALUE_${existing + index}`] = value;
+});
diff --git a/apps/server/src/vcs/GitVcsDriverCore.test.ts b/apps/server/src/vcs/GitVcsDriverCore.test.ts
index 75f69de952c1..b2400f68779c 100644
--- a/apps/server/src/vcs/GitVcsDriverCore.test.ts
+++ b/apps/server/src/vcs/GitVcsDriverCore.test.ts
@@ -1,4 +1,7 @@
+// @effect-diagnostics nodeBuiltinImport:off - realpathSync.native resolves Windows 8.3 short names, which the Effect realPath does not.
+import * as NodeFS from "node:fs";
 import * as NodeServices from "@effect/platform-node/NodeServices";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 import { assert, it, describe } from "@effect/vitest";
 import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
@@ -570,7 +573,6 @@ it.effect("backs off failed upstream refreshes across linked worktrees", () =>
       const driver = yield* makeGitVcsDriverCore().pipe(
         Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, failingFetchSpawner),
       );
-      const fileSystem = yield* FileSystem.FileSystem;
       const cwd = yield* makeTmpDir();
       const remote = yield* makeTmpDir("git-vcs-driver-remote-");
       const worktreesRoot = yield* makeTmpDir("git-vcs-driver-worktrees-");
@@ -606,9 +608,11 @@ it.effect("backs off failed upstream refreshes across linked worktrees", () =>
         "rev-parse",
         "--git-common-dir",
       ])).stdout.trim();
+      // Native realpath, since git reports the long form of a directory the
+      // temp dir may name by its 8.3 short form on Windows.
       assert.equal(
-        yield* fileSystem.realPath(pathService.resolve(cwd, rootCommonDir)),
-        yield* fileSystem.realPath(pathService.resolve(worktreePath, linkedCommonDir)),
+        NodeFS.realpathSync.native(pathService.resolve(cwd, rootCommonDir)),
+        NodeFS.realpathSync.native(pathService.resolve(worktreePath, linkedCommonDir)),
       );
       yield* Ref.set(fetchAttempts, 0);
 
@@ -1376,31 +1380,33 @@ it.layer(TestLayer)("GitVcsDriver core integration", (it) => {
   });
 
   describe("worktree operations", () => {
-    it.effect("preserves newline characters in worktree paths when listing refs", () =>
-      Effect.gen(function* () {
-        const cwd = yield* makeTmpDir();
-        yield* initRepoWithCommit(cwd);
-        const worktreesRoot = yield* makeTmpDir("git-vcs-driver-worktrees-");
-        const fileSystem = yield* FileSystem.FileSystem;
-        const pathService = yield* Path.Path;
-        const worktreePath = pathService.join(worktreesRoot, "linked\nworktree");
-        const driver = yield* GitVcsDriver.GitVcsDriver;
+    // NTFS rejects a newline in a file name, so there is nothing to preserve there.
+    it.effect.skipIf(HostProcessPlatform.defaultValue() === "win32")(
+      "preserves newline characters in worktree paths when listing refs",
+      () =>
+        Effect.gen(function* () {
+          const cwd = yield* makeTmpDir();
+          yield* initRepoWithCommit(cwd);
+          const worktreesRoot = yield* makeTmpDir("git-vcs-driver-worktrees-");
+          const pathService = yield* Path.Path;
+          const worktreePath = pathService.join(worktreesRoot, "linked\nworktree");
+          const driver = yield* GitVcsDriver.GitVcsDriver;
 
-        yield* git(cwd, ["worktree", "add", "-b", "feature/newline-path", worktreePath]);
+          yield* git(cwd, ["worktree", "add", "-b", "feature/newline-path", worktreePath]);
 
-        const refs = yield* driver.listRefs({ cwd, refresh: true });
-        const listedPath = refs.refs.find(
-          (ref) => ref.name === "feature/newline-path",
-        )?.worktreePath;
+          const refs = yield* driver.listRefs({ cwd, refresh: true });
+          const listedPath = refs.refs.find(
+            (ref) => ref.name === "feature/newline-path",
+          )?.worktreePath;
 
-        if (typeof listedPath !== "string") {
-          return assert.fail("expected the linked branch to include its worktree path");
-        }
-        assert.equal(
-          yield* fileSystem.realPath(listedPath),
-          yield* fileSystem.realPath(worktreePath),
-        );
-      }),
+          if (typeof listedPath !== "string") {
+            return assert.fail("expected the linked branch to include its worktree path");
+          }
+          assert.equal(
+            NodeFS.realpathSync.native(listedPath),
+            NodeFS.realpathSync.native(worktreePath),
+          );
+        }),
     );
 
     it.effect("checks out submodules in a new worktree", () =>
diff --git a/apps/server/vite.config.ts b/apps/server/vite.config.ts
index 647af2a889d5..139373a94dca 100644
--- a/apps/server/vite.config.ts
+++ b/apps/server/vite.config.ts
@@ -78,6 +78,7 @@ export default mergeConfig(
       // The server suite exercises sqlite, git, temp worktrees, and orchestration
       // runtimes heavily. Running files in parallel introduces load-sensitive flakes.
       fileParallelism: false,
+      setupFiles: ["./src/testUtils/gitConfig.setup.ts"],
       // Server integration tests exercise sqlite, git, and orchestration together.
       // Under package-wide runs they can exceed the default budget on loaded CI hosts.
       hookTimeout: 120_000,

From 1108be0fc862d5a95374bf0b96518a20e6351025 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 13:33:21 -0700
Subject: [PATCH 15/56] test: skip POSIX mode-bit assertions on a Windows host
 (#9571)

Co-authored-by: Claude Code <noreply@anthropic.com>
---
 apps/server/scripts/t3-sqlite-state.test.ts |   4 +-
 apps/server/src/cli/theme.test.ts           |  13 +-
 apps/server/src/keybindings.test.ts         |  48 ++--
 packages/shared/src/logging.test.ts         |   7 +-
 packages/shared/src/relayClient.test.ts     | 261 ++++++++++----------
 5 files changed, 180 insertions(+), 153 deletions(-)

diff --git a/apps/server/scripts/t3-sqlite-state.test.ts b/apps/server/scripts/t3-sqlite-state.test.ts
index 71e592fafbd7..fa5471bfa8c4 100644
--- a/apps/server/scripts/t3-sqlite-state.test.ts
+++ b/apps/server/scripts/t3-sqlite-state.test.ts
@@ -7,6 +7,7 @@ import * as SqlClient from "effect/unstable/sql/SqlClient";
 
 import * as NodeSqliteClient from "@t3tools/shared/nodeSqliteClient";
 import { runSqliteState } from "./t3-sqlite-state.ts";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const createFixtureDatabase = Effect.fn("createSqliteStateFixtureDatabase")(function* (
@@ -89,7 +90,8 @@ it.layer(NodeServices.layer)("t3-sqlite-state", (it) => {
           sql: "INSERT INTO fixtures (id, label) VALUES (2, 'seeded')",
         });
         assert.equal(mutation.operation, "exec");
-        if (mutation.operation === "exec") {
+        if (mutation.operation === "exec" && (yield* HostProcessPlatform) !== "win32") {
+          // NTFS has no POSIX mode bits to report.
           assert.equal((yield* fs.stat(mutation.backup)).mode & 0o777, 0o600);
         }
 
diff --git a/apps/server/src/cli/theme.test.ts b/apps/server/src/cli/theme.test.ts
index 33606565ffc7..7935f5e51b42 100644
--- a/apps/server/src/cli/theme.test.ts
+++ b/apps/server/src/cli/theme.test.ts
@@ -14,6 +14,11 @@ import { Command } from "effect/unstable/cli";
 
 import { cli } from "../bin.ts";
 import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+
+// These force a failure with chmod, which Windows ignores for directories and
+// cannot use to make a file unreadable, so the failure never happens there.
+const windowsHost = HostProcessPlatform.defaultValue() === "win32";
 
 const runCli = (args: ReadonlyArray<string>) =>
   Command.runWith(cli, { version: "0.0.0" })(args).pipe(
@@ -161,7 +166,7 @@ describe("t3 theme", () => {
   // rolled back rather than left mutating the environment's theme set. The
   // userdata directory is made read-only while themes stays writable, so the
   // failure lands after the publish -- the case the rollback exists for.
-  it.effect("rolls back a publish when the default cannot be written", () =>
+  it.effect.skipIf(windowsHost)("rolls back a publish when the default cannot be written", () =>
     Effect.gen(function* () {
       const baseDir = makeBaseDir();
       writeSettings(baseDir, {});
@@ -229,7 +234,7 @@ describe("t3 theme", () => {
   // Rollback moves the previous directory entry aside and back, so even an
   // entry the watcher would never publish -- here a symlink -- comes back
   // exactly as it was when the set fails.
-  it.effect.skipIf(!symlinksSupported)(
+  it.effect.skipIf(!symlinksSupported || windowsHost)(
     "restores a non-theme destination entry when the set fails",
     () =>
       Effect.gen(function* () {
@@ -255,7 +260,7 @@ describe("t3 theme", () => {
       }),
   );
 
-  it.effect("restores the previous theme when a re-publish fails to set", () =>
+  it.effect.skipIf(windowsHost)("restores the previous theme when a re-publish fails to set", () =>
     Effect.gen(function* () {
       const baseDir = makeBaseDir();
       writeSettings(baseDir, {});
@@ -352,7 +357,7 @@ describe("t3 theme", () => {
 
   // An unreadable settings file must never read as "no settings": writing a
   // fresh sparse file over it would discard every key the user had.
-  it.effect("refuses to write when the settings file cannot be read", () =>
+  it.effect.skipIf(windowsHost)("refuses to write when the settings file cannot be read", () =>
     Effect.gen(function* () {
       const baseDir = makeBaseDir();
       writeSettings(baseDir, { enableProviderUpdateChecks: false });
diff --git a/apps/server/src/keybindings.test.ts b/apps/server/src/keybindings.test.ts
index 6c32235c27f8..160755a8f9b2 100644
--- a/apps/server/src/keybindings.test.ts
+++ b/apps/server/src/keybindings.test.ts
@@ -12,6 +12,7 @@ import * as Schema from "effect/Schema";
 import * as ServerConfig from "./config.ts";
 import * as Keybindings from "./keybindings.ts";
 import { KeybindingsConfigError } from "@t3tools/contracts";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 
 const KeybindingsConfigJson = Schema.fromJsonString(KeybindingsConfig);
 const encodeKeybindingsConfigJson = Schema.encodeEffect(KeybindingsConfigJson);
@@ -511,31 +512,34 @@ it.layer(NodeServices.layer)("keybindings", (it) => {
     }).pipe(Effect.provide(makeKeybindingsLayer())),
   );
 
-  it.effect("fails when config directory is not writable", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const { keybindingsConfigPath } = yield* ServerConfig.ServerConfig;
-      const { dirname } = yield* Path.Path;
-      yield* writeKeybindingsConfig(keybindingsConfigPath, [
-        { key: "mod+j", command: "terminal.toggle" },
-      ]);
-      yield* fs.chmod(dirname(keybindingsConfigPath), 0o500);
+  // chmod cannot make a directory unwritable on Windows, so the write succeeds.
+  it.effect.skipIf(HostProcessPlatform.defaultValue() === "win32")(
+    "fails when config directory is not writable",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const { keybindingsConfigPath } = yield* ServerConfig.ServerConfig;
+        const { dirname } = yield* Path.Path;
+        yield* writeKeybindingsConfig(keybindingsConfigPath, [
+          { key: "mod+j", command: "terminal.toggle" },
+        ]);
+        yield* fs.chmod(dirname(keybindingsConfigPath), 0o500);
 
-      const result = yield* Effect.gen(function* () {
-        const keybindings = yield* Keybindings.Keybindings;
-        return yield* keybindings.upsertKeybindingRule({
-          key: "mod+shift+r",
-          command: "script.run-tests.run",
-        });
-      }).pipe(toDetailResult);
-      assertFailure(result, "failed to write keybindings config");
+        const result = yield* Effect.gen(function* () {
+          const keybindings = yield* Keybindings.Keybindings;
+          return yield* keybindings.upsertKeybindingRule({
+            key: "mod+shift+r",
+            command: "script.run-tests.run",
+          });
+        }).pipe(toDetailResult);
+        assertFailure(result, "failed to write keybindings config");
 
-      yield* fs.chmod(dirname(keybindingsConfigPath), 0o700);
+        yield* fs.chmod(dirname(keybindingsConfigPath), 0o700);
 
-      const persisted = yield* readKeybindingsConfig(keybindingsConfigPath);
-      const persistedView = persisted.map(({ key, command }) => ({ key, command }));
-      assert.deepEqual(persistedView, [{ key: "mod+j", command: "terminal.toggle" }]);
-    }).pipe(Effect.provide(makeKeybindingsLayer())),
+        const persisted = yield* readKeybindingsConfig(keybindingsConfigPath);
+        const persistedView = persisted.map(({ key, command }) => ({ key, command }));
+        assert.deepEqual(persistedView, [{ key: "mod+j", command: "terminal.toggle" }]);
+      }).pipe(Effect.provide(makeKeybindingsLayer())),
   );
 
   it.effect("caches loaded resolved config across repeated reads", () =>
diff --git a/packages/shared/src/logging.test.ts b/packages/shared/src/logging.test.ts
index 4b19bd291dae..0e294bbe29bf 100644
--- a/packages/shared/src/logging.test.ts
+++ b/packages/shared/src/logging.test.ts
@@ -3,6 +3,7 @@ import * as NodeFS from "node:fs";
 import * as NodeOS from "node:os";
 import * as NodePath from "node:path";
 import { afterEach, describe, expect, it } from "vite-plus/test";
+import { HostProcessPlatform } from "./hostProcess.ts";
 
 import {
   RotatingFileSink,
@@ -10,6 +11,7 @@ import {
   RotatingFileSinkError,
 } from "./logging.ts";
 
+const windowsHost = HostProcessPlatform.defaultValue() === "win32";
 const tempDirectories: string[] = [];
 
 const makeTempDirectory = (): string => {
@@ -69,7 +71,10 @@ describe("RotatingFileSink", () => {
     expect((thrown as RotatingFileSinkError).cause).toBeInstanceOf(Error);
   });
 
-  it("only treats a missing log file as an empty current size", () => {
+  // An over-long name is the one stat failure that is neither ENOENT nor a
+  // permission problem on posix. Windows reports it as ENOENT, so the sink
+  // correctly treats it as an absent file and there is nothing to assert.
+  it.skipIf(windowsHost)("only treats a missing log file as an empty current size", () => {
     const directory = makeTempDirectory();
     const filePath = NodePath.join(directory, "a".repeat(300));
 
diff --git a/packages/shared/src/relayClient.test.ts b/packages/shared/src/relayClient.test.ts
index df39ef0b161d..1d556ed6dc30 100644
--- a/packages/shared/src/relayClient.test.ts
+++ b/packages/shared/src/relayClient.test.ts
@@ -18,6 +18,10 @@ import {
   makeCloudflaredRelayClient,
 } from "./relayClient.ts";
 
+// The suite runs the linux code path against the real filesystem, checking
+// POSIX exec bits that NTFS never reports; the win32 branch skips that check.
+const windowsHost = HostProcessPlatform.defaultValue() === "win32";
+
 const hostRuntimeLayer = (env: Record<string, string> = {}) =>
   Layer.mergeAll(
     Layer.succeed(HostProcessPlatform, "linux"),
@@ -63,102 +67,106 @@ const makeSpawnerLayer = (commands: Array<string>) =>
   );
 
 describe("RelayClient", () => {
-  it.effect("resolves explicit overrides before managed and PATH executables", () =>
-    Effect.gen(function* () {
-      const fileSystem = yield* FileSystem.FileSystem;
-      const baseDir = yield* fileSystem.makeTempDirectoryScoped({
-        prefix: "t3-cloudflared-test-",
-      });
-      const overridePath = `${baseDir}/override-cloudflared`;
-      yield* fileSystem.writeFileString(overridePath, "override");
-      yield* fileSystem.chmod(overridePath, 0o755);
-      const manager = yield* makeCloudflaredRelayClient({
-        baseDir,
-      });
+  it.effect.skipIf(windowsHost)(
+    "resolves explicit overrides before managed and PATH executables",
+    () =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+          prefix: "t3-cloudflared-test-",
+        });
+        const overridePath = `${baseDir}/override-cloudflared`;
+        yield* fileSystem.writeFileString(overridePath, "override");
+        yield* fileSystem.chmod(overridePath, 0o755);
+        const manager = yield* makeCloudflaredRelayClient({
+          baseDir,
+        });
 
-      expect(
-        yield* manager.resolve.pipe(
-          Effect.provideService(
-            ConfigProvider.ConfigProvider,
-            ConfigProvider.fromEnv({
-              env: { PATH: "", T3CODE_CLOUDFLARED_PATH: overridePath },
-            }),
+        expect(
+          yield* manager.resolve.pipe(
+            Effect.provideService(
+              ConfigProvider.ConfigProvider,
+              ConfigProvider.fromEnv({
+                env: { PATH: "", T3CODE_CLOUDFLARED_PATH: overridePath },
+              }),
+            ),
+          ),
+        ).toEqual({
+          status: "available",
+          executablePath: overridePath,
+          source: "override",
+          version: CLOUDFLARED_VERSION,
+        });
+      }).pipe(
+        Effect.scoped,
+        Effect.provide(
+          Layer.mergeAll(
+            NodeServices.layer,
+            makeHttpClientLayer(new Uint8Array()),
+            makeSpawnerLayer([]),
+            hostRuntimeLayer(),
           ),
-        ),
-      ).toEqual({
-        status: "available",
-        executablePath: overridePath,
-        source: "override",
-        version: CLOUDFLARED_VERSION,
-      });
-    }).pipe(
-      Effect.scoped,
-      Effect.provide(
-        Layer.mergeAll(
-          NodeServices.layer,
-          makeHttpClientLayer(new Uint8Array()),
-          makeSpawnerLayer([]),
-          hostRuntimeLayer(),
         ),
       ),
-    ),
   );
 
-  it.effect("downloads, verifies, validates, and atomically installs the managed executable", () =>
-    Effect.gen(function* () {
-      const fileSystem = yield* FileSystem.FileSystem;
-      const baseDir = yield* fileSystem.makeTempDirectoryScoped({
-        prefix: "t3-cloudflared-test-",
-      });
-      const bytes = new TextEncoder().encode("test-cloudflared-binary");
-      const manager = yield* makeCloudflaredRelayClient({
-        baseDir,
-        releaseAsset: {
-          url: "https://example.test/cloudflared",
-          sha256: Encoding.encodeHex(sha256(bytes)),
-          archive: "binary",
-        },
-      });
+  it.effect.skipIf(windowsHost)(
+    "downloads, verifies, validates, and atomically installs the managed executable",
+    () =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+          prefix: "t3-cloudflared-test-",
+        });
+        const bytes = new TextEncoder().encode("test-cloudflared-binary");
+        const manager = yield* makeCloudflaredRelayClient({
+          baseDir,
+          releaseAsset: {
+            url: "https://example.test/cloudflared",
+            sha256: Encoding.encodeHex(sha256(bytes)),
+            archive: "binary",
+          },
+        });
 
-      const progress: Array<string> = [];
-      const installed = yield* manager.installWithProgress((event) =>
-        Effect.sync(() => {
-          if (event.type === "progress") {
-            progress.push(event.stage);
-          }
-        }),
-      );
-      const managedPath = `${baseDir}/tools/cloudflared/${CLOUDFLARED_VERSION}/linux-x64/cloudflared`;
-      expect(installed).toEqual({
-        status: "available",
-        executablePath: managedPath,
-        source: "managed",
-        version: CLOUDFLARED_VERSION,
-      });
-      expect(new TextDecoder().decode(yield* fileSystem.readFile(managedPath))).toBe(
-        "test-cloudflared-binary",
-      );
-      expect(progress).toEqual([
-        "checking",
-        "waiting_for_lock",
-        "downloading",
-        "verifying",
-        "installing",
-        "validating",
-        "activating",
-      ]);
-      expect(yield* manager.resolve).toEqual(installed);
-    }).pipe(
-      Effect.scoped,
-      Effect.provide(
-        Layer.mergeAll(
-          NodeServices.layer,
-          makeHttpClientLayer(new TextEncoder().encode("test-cloudflared-binary")),
-          makeSpawnerLayer([]),
-          hostRuntimeLayer(),
+        const progress: Array<string> = [];
+        const installed = yield* manager.installWithProgress((event) =>
+          Effect.sync(() => {
+            if (event.type === "progress") {
+              progress.push(event.stage);
+            }
+          }),
+        );
+        const managedPath = `${baseDir}/tools/cloudflared/${CLOUDFLARED_VERSION}/linux-x64/cloudflared`;
+        expect(installed).toEqual({
+          status: "available",
+          executablePath: managedPath,
+          source: "managed",
+          version: CLOUDFLARED_VERSION,
+        });
+        expect(new TextDecoder().decode(yield* fileSystem.readFile(managedPath))).toBe(
+          "test-cloudflared-binary",
+        );
+        expect(progress).toEqual([
+          "checking",
+          "waiting_for_lock",
+          "downloading",
+          "verifying",
+          "installing",
+          "validating",
+          "activating",
+        ]);
+        expect(yield* manager.resolve).toEqual(installed);
+      }).pipe(
+        Effect.scoped,
+        Effect.provide(
+          Layer.mergeAll(
+            NodeServices.layer,
+            makeHttpClientLayer(new TextEncoder().encode("test-cloudflared-binary")),
+            makeSpawnerLayer([]),
+            hostRuntimeLayer(),
+          ),
         ),
       ),
-    ),
   );
 
   it.effect("rejects downloads whose checksum does not match the pinned manifest", () =>
@@ -192,7 +200,7 @@ describe("RelayClient", () => {
     ),
   );
 
-  it.effect("serializes concurrent installs within one runtime", () => {
+  it.effect.skipIf(windowsHost)("serializes concurrent installs within one runtime", () => {
     const commands: Array<string> = [];
     const bytes = new TextEncoder().encode("test-cloudflared-binary");
     return Effect.gen(function* () {
@@ -227,45 +235,48 @@ describe("RelayClient", () => {
     );
   });
 
-  it.effect("observes PATH changes after the manager has been constructed", () => {
-    const env = { PATH: "" };
-    return Effect.gen(function* () {
-      const fileSystem = yield* FileSystem.FileSystem;
-      const baseDir = yield* fileSystem.makeTempDirectoryScoped({
-        prefix: "t3-cloudflared-test-",
-      });
-      const binDir = `${baseDir}/bin`;
-      const executablePath = `${binDir}/cloudflared`;
-      const manager = yield* makeCloudflaredRelayClient({
-        baseDir,
-      });
+  it.effect.skipIf(windowsHost)(
+    "observes PATH changes after the manager has been constructed",
+    () => {
+      const env = { PATH: "" };
+      return Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+          prefix: "t3-cloudflared-test-",
+        });
+        const binDir = `${baseDir}/bin`;
+        const executablePath = `${binDir}/cloudflared`;
+        const manager = yield* makeCloudflaredRelayClient({
+          baseDir,
+        });
 
-      expect(yield* manager.resolve).toEqual({
-        status: "missing",
-        version: CLOUDFLARED_VERSION,
-      });
+        expect(yield* manager.resolve).toEqual({
+          status: "missing",
+          version: CLOUDFLARED_VERSION,
+        });
 
-      yield* fileSystem.makeDirectory(binDir);
-      yield* fileSystem.writeFileString(executablePath, "cloudflared");
-      yield* fileSystem.chmod(executablePath, 0o755);
-      env.PATH = binDir;
+        yield* fileSystem.makeDirectory(binDir);
+        yield* fileSystem.writeFileString(executablePath, "cloudflared");
+        yield* fileSystem.chmod(executablePath, 0o755);
+        env.PATH = binDir;
 
-      expect(yield* manager.resolve).toEqual({
-        status: "available",
-        executablePath,
-        source: "path",
-        version: CLOUDFLARED_VERSION,
-      });
-    }).pipe(
-      Effect.scoped,
-      Effect.provide(
-        Layer.mergeAll(
-          NodeServices.layer,
-          makeHttpClientLayer(new Uint8Array()),
-          makeSpawnerLayer([]),
-          hostRuntimeLayer(env),
+        expect(yield* manager.resolve).toEqual({
+          status: "available",
+          executablePath,
+          source: "path",
+          version: CLOUDFLARED_VERSION,
+        });
+      }).pipe(
+        Effect.scoped,
+        Effect.provide(
+          Layer.mergeAll(
+            NodeServices.layer,
+            makeHttpClientLayer(new Uint8Array()),
+            makeSpawnerLayer([]),
+            hostRuntimeLayer(env),
+          ),
         ),
-      ),
-    );
-  });
+      );
+    },
+  );
 });

From 9af5139f5974281a59f5cd62c11d918d62126313 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 13:33:22 -0700
Subject: [PATCH 16/56] test(server): keep provider fixture directories
 host-portable (#9572)

Co-authored-by: Claude Code <noreply@anthropic.com>
---
 .../Layers/ClaudeCapabilitiesProbe.test.ts    | 23 +++++++++++++++++--
 .../CodexCollabRuntime.integration.test.ts    | 15 ++++++------
 2 files changed, 29 insertions(+), 9 deletions(-)

diff --git a/apps/server/src/provider/Layers/ClaudeCapabilitiesProbe.test.ts b/apps/server/src/provider/Layers/ClaudeCapabilitiesProbe.test.ts
index 253118299820..f167955fbaec 100644
--- a/apps/server/src/provider/Layers/ClaudeCapabilitiesProbe.test.ts
+++ b/apps/server/src/provider/Layers/ClaudeCapabilitiesProbe.test.ts
@@ -1,4 +1,6 @@
+// @effect-diagnostics nodeBuiltinImport:off - cleanup uses Node's retrying rm, which the FileSystem service does not expose.
 import { ClaudeSettings } from "@t3tools/contracts";
+import * as NodeFSP from "node:fs/promises";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
@@ -51,8 +53,25 @@ it.layer(NodeServices.layer)("Claude capability probe SDK boundary", (it) => {
       const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-claude-probe-sdk-" });
       const executablePath = path.join(tempDir, "fake-claude.mjs");
       const invocationPath = path.join(tempDir, "invocation.json");
-      const workspaceCwd = path.join(tempDir, "workspace");
-      yield* fs.makeDirectory(workspaceCwd, { recursive: true });
+      // The probe aborts the SDK without awaiting the child's exit, and on
+      // Windows a directory that is still some process's cwd cannot be
+      // removed. Keep the workspace outside the scoped directory and let it
+      // go with a retrying removal once the child has gone.
+      const workspaceCwd = yield* fs.makeTempDirectory({ prefix: "t3-claude-probe-cwd-" });
+      // Node's own retry rather than an Effect schedule: it.effect runs on a
+      // TestClock, so a scheduled retry would wait for time nobody advances.
+      // If the child still holds the directory after that, an empty temp
+      // directory is left behind rather than failing the test for it.
+      yield* Effect.addFinalizer(() =>
+        Effect.promise(() =>
+          NodeFSP.rm(workspaceCwd, {
+            recursive: true,
+            force: true,
+            maxRetries: 20,
+            retryDelay: 250,
+          }).catch(() => undefined),
+        ),
+      );
 
       yield* fs.writeFileString(
         executablePath,
diff --git a/apps/server/src/provider/Layers/CodexCollabRuntime.integration.test.ts b/apps/server/src/provider/Layers/CodexCollabRuntime.integration.test.ts
index 7fcbe7b5f334..02b7a45f33ad 100644
--- a/apps/server/src/provider/Layers/CodexCollabRuntime.integration.test.ts
+++ b/apps/server/src/provider/Layers/CodexCollabRuntime.integration.test.ts
@@ -9,6 +9,7 @@
  */
 // @effect-diagnostics nodeBuiltinImport:off
 import * as NodeFS from "node:fs";
+import * as NodeOS from "node:os";
 import * as NodePath from "node:path";
 
 import * as NodeServices from "@effect/platform-node/NodeServices";
@@ -200,7 +201,7 @@ describe("CodexSessionRuntime collab integration", () => {
       const runtime = yield* makeCodexSessionRuntime({
         threadId: ThreadId.make("thread-collab-model-activity"),
         binaryPath: peerPath,
-        cwd: "/tmp",
+        cwd: NodeOS.tmpdir(),
         runtimeMode: "full-access",
         environment: { ...process.env, T3_CODEX_COLLAB_SCRIPT: scriptPath },
       });
@@ -292,7 +293,7 @@ describe("CodexSessionRuntime collab integration", () => {
       const runtime = yield* makeCodexSessionRuntime({
         threadId: ThreadId.make("thread-collab-model-spawn"),
         binaryPath: peerPath,
-        cwd: "/tmp",
+        cwd: NodeOS.tmpdir(),
         runtimeMode: "full-access",
         environment: { ...process.env, T3_CODEX_COLLAB_SCRIPT: scriptPath },
       });
@@ -371,7 +372,7 @@ describe("CodexSessionRuntime collab integration", () => {
           const runtime = yield* makeCodexSessionRuntime({
             threadId: ThreadId.make(`thread-collab-model-${name}`),
             binaryPath: peerPath,
-            cwd: "/tmp",
+            cwd: NodeOS.tmpdir(),
             runtimeMode: "full-access",
             environment: { ...process.env, T3_CODEX_COLLAB_SCRIPT: scriptPath },
           });
@@ -410,7 +411,7 @@ describe("CodexSessionRuntime collab integration", () => {
       const runtime = yield* makeCodexSessionRuntime({
         threadId: ThreadId.make("thread-collab-integration"),
         binaryPath: peerPath,
-        cwd: "/tmp",
+        cwd: NodeOS.tmpdir(),
         runtimeMode: "full-access",
         environment: { ...process.env, T3_CODEX_COLLAB_SCRIPT: scriptPath },
       });
@@ -552,7 +553,7 @@ describe("CodexSessionRuntime collab integration", () => {
       const runtime = yield* makeCodexSessionRuntime({
         threadId: ThreadId.make("thread-collab-stop"),
         binaryPath: peerPath,
-        cwd: "/tmp",
+        cwd: NodeOS.tmpdir(),
         runtimeMode: "full-access",
         environment: { ...process.env, T3_CODEX_COLLAB_SCRIPT: scriptPath },
       });
@@ -630,7 +631,7 @@ describe("CodexSessionRuntime collab integration", () => {
       const runtime = yield* makeCodexSessionRuntime({
         threadId: ThreadId.make("thread-codex-queued-stop"),
         binaryPath: peerPath,
-        cwd: "/tmp",
+        cwd: NodeOS.tmpdir(),
         runtimeMode: "full-access",
         environment: { ...process.env, T3_CODEX_COLLAB_SCRIPT: scriptPath },
       });
@@ -727,7 +728,7 @@ describe("CodexSessionRuntime collab integration", () => {
         const runtime = yield* makeCodexSessionRuntime({
           threadId: ThreadId.make("thread-codex-mcp-elicitation"),
           binaryPath: peerPath,
-          cwd: "/tmp",
+          cwd: NodeOS.tmpdir(),
           runtimeMode: "auto",
           environment: { ...process.env, T3_CODEX_COLLAB_SCRIPT: scriptPath },
         });

From 9fa54eeb4c481b444c68e38d00066d707af5f677 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 13:33:22 -0700
Subject: [PATCH 17/56] test: resolve the Windows temp directory to its long
 name (#9573)

Co-authored-by: Claude Code <noreply@anthropic.com>
---
 apps/desktop/vite.config.ts                |  2 +
 apps/server/src/bootstrap.test.ts          | 71 ++++++++++++----------
 apps/server/vite.config.ts                 |  1 +
 apps/web/vite.config.ts                    |  1 +
 packages/client-runtime/vite.config.ts     |  1 +
 packages/shared/package.json               |  4 ++
 packages/shared/src/testing/longTempDir.ts | 19 ++++++
 vite.config.ts                             |  5 ++
 8 files changed, 71 insertions(+), 33 deletions(-)
 create mode 100644 packages/shared/src/testing/longTempDir.ts

diff --git a/apps/desktop/vite.config.ts b/apps/desktop/vite.config.ts
index f0829d4e654f..294a02030a83 100644
--- a/apps/desktop/vite.config.ts
+++ b/apps/desktop/vite.config.ts
@@ -1,3 +1,4 @@
+import "vite-plus/test/config";
 import { defineConfig } from "vite-plus";
 
 import { loadRepoEnv } from "../../scripts/lib/public-config.ts";
@@ -87,5 +88,6 @@ export default defineConfig({
     // The Windows lane runs workspace suites concurrently; filesystem-heavy
     // desktop integration tests can exceed Vitest's 5 second default there.
     testTimeout: 15_000,
+    setupFiles: ["../../packages/shared/src/testing/longTempDir.ts"],
   },
 });
diff --git a/apps/server/src/bootstrap.test.ts b/apps/server/src/bootstrap.test.ts
index 05155f32ec4c..722eb21a2461 100644
--- a/apps/server/src/bootstrap.test.ts
+++ b/apps/server/src/bootstrap.test.ts
@@ -55,6 +55,8 @@ vi.mock("node:fs", async (importOriginal) => {
   };
 });
 
+const windowsHost = HostProcessPlatform.defaultValue() === "win32";
+const nullDevice = windowsHost ? "\\\\.\\NUL" : "/dev/null";
 const TestEnvelopeSchema = Schema.Struct({ mode: Schema.String });
 const encodeTestEnvelopeSchema = Schema.encodeEffect(Schema.fromJsonString(TestEnvelopeSchema));
 
@@ -146,7 +148,7 @@ it.layer(NodeServices.layer)("readBootstrapEnvelope", (it) => {
 
   it.effect("returns none when the fd is unavailable", () =>
     Effect.gen(function* () {
-      const fd = NodeFS.openSync("/dev/null", "r");
+      const fd = NodeFS.openSync(nullDevice, "r");
       NodeFS.closeSync(fd);
 
       const payload = yield* readBootstrapEnvelope(TestEnvelopeSchema, fd, { timeoutMs: 100 });
@@ -157,7 +159,7 @@ it.layer(NodeServices.layer)("readBootstrapEnvelope", (it) => {
   it.effect("preserves fd and cause when stat fails for a non-availability reason", () =>
     Effect.gen(function* () {
       const fd = yield* Effect.acquireRelease(
-        Effect.sync(() => NodeFS.openSync("/dev/null", "r")),
+        Effect.sync(() => NodeFS.openSync(nullDevice, "r")),
         (fd) => Effect.sync(() => NodeFS.closeSync(fd)),
       );
 
@@ -201,40 +203,43 @@ it.layer(NodeServices.layer)("readBootstrapEnvelope", (it) => {
     }),
   );
 
-  it.effect("returns none when the bootstrap read times out before any value arrives", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-bootstrap-" });
-      const fifoPath = NodePath.join(tempDir, "bootstrap.pipe");
-
-      yield* Effect.sync(() => NodeChildProcess.execFileSync("mkfifo", [fifoPath]));
-
-      const _writer = yield* Effect.acquireRelease(
-        Effect.sync(() =>
-          NodeChildProcess.spawn("sh", ["-c", 'exec 3>"$1"; sleep 60', "sh", fifoPath], {
-            stdio: ["ignore", "ignore", "ignore"],
-          }),
-        ),
-        (writer) =>
-          Effect.sync(() => {
-            writer.kill("SIGKILL");
-          }),
-      );
+  // Needs a FIFO, which mkfifo creates; Windows has neither.
+  it.effect.skipIf(windowsHost)(
+    "returns none when the bootstrap read times out before any value arrives",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-bootstrap-" });
+        const fifoPath = NodePath.join(tempDir, "bootstrap.pipe");
+
+        yield* Effect.sync(() => NodeChildProcess.execFileSync("mkfifo", [fifoPath]));
+
+        const _writer = yield* Effect.acquireRelease(
+          Effect.sync(() =>
+            NodeChildProcess.spawn("sh", ["-c", 'exec 3>"$1"; sleep 60', "sh", fifoPath], {
+              stdio: ["ignore", "ignore", "ignore"],
+            }),
+          ),
+          (writer) =>
+            Effect.sync(() => {
+              writer.kill("SIGKILL");
+            }),
+        );
 
-      const fd = yield* Effect.acquireRelease(
-        Effect.sync(() => NodeFS.openSync(fifoPath, "r")),
-        (fd) => Effect.sync(() => NodeFS.closeSync(fd)),
-      );
+        const fd = yield* Effect.acquireRelease(
+          Effect.sync(() => NodeFS.openSync(fifoPath, "r")),
+          (fd) => Effect.sync(() => NodeFS.closeSync(fd)),
+        );
 
-      const fiber = yield* readBootstrapEnvelope(TestEnvelopeSchema, fd, {
-        timeoutMs: 100,
-      }).pipe(Effect.forkScoped);
+        const fiber = yield* readBootstrapEnvelope(TestEnvelopeSchema, fd, {
+          timeoutMs: 100,
+        }).pipe(Effect.forkScoped);
 
-      yield* Effect.yieldNow;
-      yield* TestClock.adjust(Duration.millis(100));
+        yield* Effect.yieldNow;
+        yield* TestClock.adjust(Duration.millis(100));
 
-      const payload = yield* Fiber.join(fiber);
-      assertNone(payload);
-    }).pipe(Effect.provide(TestClock.layer())),
+        const payload = yield* Fiber.join(fiber);
+        assertNone(payload);
+      }).pipe(Effect.provide(TestClock.layer())),
   );
 });
diff --git a/apps/server/vite.config.ts b/apps/server/vite.config.ts
index 139373a94dca..88c8c2f4d37f 100644
--- a/apps/server/vite.config.ts
+++ b/apps/server/vite.config.ts
@@ -78,6 +78,7 @@ export default mergeConfig(
       // The server suite exercises sqlite, git, temp worktrees, and orchestration
       // runtimes heavily. Running files in parallel introduces load-sensitive flakes.
       fileParallelism: false,
+      // Appended to the root setup, which mergeConfig concatenates.
       setupFiles: ["./src/testUtils/gitConfig.setup.ts"],
       // Server integration tests exercise sqlite, git, and orchestration together.
       // Under package-wide runs they can exceed the default budget on loaded CI hosts.
diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
index 6661736f062f..702c18840983 100644
--- a/apps/web/vite.config.ts
+++ b/apps/web/vite.config.ts
@@ -80,6 +80,7 @@ const unitTestProject = {
     // run, those async tests can exceed Vitest's default 5s budget.
     hookTimeout: 15_000,
     testTimeout: 15_000,
+    setupFiles: ["../../packages/shared/src/testing/longTempDir.ts"],
   },
 } satisfies TestProjectInlineConfiguration;
 
diff --git a/packages/client-runtime/vite.config.ts b/packages/client-runtime/vite.config.ts
index fcdb97512160..7f4ff74eca29 100644
--- a/packages/client-runtime/vite.config.ts
+++ b/packages/client-runtime/vite.config.ts
@@ -5,5 +5,6 @@ export default defineConfig({
   test: {
     environment: "node",
     include: ["src/**/*.test.ts"],
+    setupFiles: ["../shared/src/testing/longTempDir.ts"],
   },
 });
diff --git a/packages/shared/package.json b/packages/shared/package.json
index a5ce349a4c00..efbc62320a52 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -223,6 +223,10 @@
       "types": "./src/hostProcess.ts",
       "import": "./src/hostProcess.ts"
     },
+    "./testing/longTempDir": {
+      "types": "./src/testing/longTempDir.ts",
+      "import": "./src/testing/longTempDir.ts"
+    },
     "./testing/symlinks": {
       "types": "./src/testing/symlinks.ts",
       "import": "./src/testing/symlinks.ts"
diff --git a/packages/shared/src/testing/longTempDir.ts b/packages/shared/src/testing/longTempDir.ts
new file mode 100644
index 000000000000..8a18abb8ce42
--- /dev/null
+++ b/packages/shared/src/testing/longTempDir.ts
@@ -0,0 +1,19 @@
+// @effect-diagnostics nodeBuiltinImport:off - runs once at test setup, outside any Effect runtime.
+import * as NodeFS from "node:fs";
+import * as NodeOS from "node:os";
+import { HostProcessPlatform } from "../hostProcess.ts";
+
+// GitHub's Windows runners hand out the temp directory by its 8.3 short name
+// (C:\Users\RUNNER~1\...). Anything that canonicalises a path, such as git or
+// realpath, reports the long form, so equality checks between a temp path and
+// its canonical form fail. Node reads TEMP/TMP on every os.tmpdir() call, so
+// pointing them at the long form fixes every temp directory the suite makes.
+if (HostProcessPlatform.defaultValue() === "win32") {
+  try {
+    const longForm = NodeFS.realpathSync.native(NodeOS.tmpdir());
+    process.env.TEMP = longForm;
+    process.env.TMP = longForm;
+  } catch {
+    // Leave the host's value alone if it cannot be resolved.
+  }
+}
diff --git a/vite.config.ts b/vite.config.ts
index d3aec8e9764b..258555e04b5a 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -19,6 +19,11 @@ export default defineConfig({
     ],
     hookTimeout: 60_000,
     testTimeout: 60_000,
+    setupFiles: [
+      NodeURL.fileURLToPath(
+        new URL("./packages/shared/src/testing/longTempDir.ts", import.meta.url),
+      ),
+    ],
   },
   staged: {
     // Formatter only for now — no lint or typecheck on commit.

From 912276bcd9ca258ad9309727df8e279e5ab698f8 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 13:33:22 -0700
Subject: [PATCH 18/56] test(server): run the Antigravity install harness for
 the host platform (#9574)

Co-authored-by: Claude Code <noreply@anthropic.com>
---
 .../provider/AntigravityInstallation.test.ts  | 57 +++++++++++--------
 1 file changed, 32 insertions(+), 25 deletions(-)

diff --git a/apps/server/src/provider/AntigravityInstallation.test.ts b/apps/server/src/provider/AntigravityInstallation.test.ts
index 8fb3cbb54f73..0528cb4972c9 100644
--- a/apps/server/src/provider/AntigravityInstallation.test.ts
+++ b/apps/server/src/provider/AntigravityInstallation.test.ts
@@ -55,9 +55,24 @@ const zipFixtures = {
     "UEsDBBQAAAAIAAAAIl1zEy/oFAAAABQAAAASAAAAYWd5X2FjcF9zZXJ2ZXIuZXhlS8wryUwvSizLLKlUKCoFcnJTuQBQSwMEFAAAAAgAAAAiXV9yAykQAAAADgAAABkAAABsb2NhbGhhcm5lc3NfZXh0ZXJuYWwuZXhly8lPTsxRyEgsykstLuYCAFBLAQIUAxQAAAAIAAAAIl1zEy/oFAAAABQAAAASAAAAAAAAAAAAAADtgQAAAABhZ3lfYWNwX3NlcnZlci5leGVQSwECFAMUAAAACAAAACJdX3IDKRAAAAAOAAAAGQAAAAAAAAAAAAAA7YFEAAAAbG9jYWxoYXJuZXNzX2V4dGVybmFsLmV4ZVBLBQYAAAAAAgACAIcAAACLAAAAAAA=",
 };
 
-const completeArchive = Buffer.from(zipFixtures.complete, "base64");
+// The installation checks POSIX exec bits off the real filesystem unless the
+// platform is win32, so a linux platform mock cannot pass on NTFS. Default to
+// the host and let the fixture names follow; the suite is about install
+// mechanics, which are the same on every platform.
+const hostPlatform: NodeJS.Platform =
+  HostProcessPlatform.defaultValue() === "win32" ? "win32" : "linux";
+const completeArchive = Buffer.from(
+  hostPlatform === "win32" ? zipFixtures.windows : zipFixtures.complete,
+  "base64",
+);
+const executableName = hostPlatform === "win32" ? "agy_acp_server.exe" : "agy_acp_server.par";
+const harnessName =
+  hostPlatform === "win32" ? "localharness_external.exe" : "localharness_external";
 
-function releaseAsset(archive: Uint8Array = completeArchive, platform: NodeJS.Platform = "linux") {
+function releaseAsset(
+  archive: Uint8Array = completeArchive,
+  platform: NodeJS.Platform = hostPlatform,
+) {
   return {
     version: "fixture-new",
     url: "https://dl.google.com/antigravity-test.zip",
@@ -128,7 +143,7 @@ const makeHarness = Effect.fn("test.makeAntigravityInstallation")(function* (
   const path = yield* Path.Path;
   const baseDir =
     options.baseDir ?? (yield* fs.makeTempDirectoryScoped({ prefix: "t3-agy-test-" }));
-  const platform = options.platform ?? "linux";
+  const platform = options.platform ?? hostPlatform;
   const archive = options.archive ?? completeArchive;
   const asset = options.asset === undefined ? releaseAsset(archive, platform) : options.asset;
   const managedDirectory = path.join(baseDir, "tools", "antigravity-acp", `${platform}-x64`);
@@ -472,7 +487,7 @@ it.layer(NodeServices.layer)("Antigravity installation", (it) => {
           ...fs,
           sink: (target, options) =>
             (stage === "download" && target.endsWith("download.zip")) ||
-            (stage === "extract" && target.endsWith("agy_acp_server.par"))
+            (stage === "extract" && target.endsWith(executableName))
               ? fs.sink(target, options).pipe(Sink.mapInputEffect(() => Effect.fail(noSpace)))
               : fs.sink(target, options),
           writeFileString: (target, content, options) =>
@@ -525,7 +540,7 @@ it.layer(NodeServices.layer)("Antigravity installation", (it) => {
           fileSystem: FileSystem.FileSystem.of({
             ...fs,
             sink: (target, options) =>
-              phase === "extracting" && target.endsWith("agy_acp_server.par")
+              phase === "extracting" && target.endsWith(executableName)
                 ? fs
                     .sink(target, options)
                     .pipe(
@@ -691,8 +706,8 @@ it.layer(NodeServices.layer)("Antigravity installation", (it) => {
         const path = yield* Path.Path;
         const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-agy-path-test-" });
         const externalDirectory = path.join(baseDir, "external");
-        const externalExecutable = path.join(externalDirectory, "agy_acp_server.par");
-        const externalHarness = path.join(externalDirectory, "localharness_external");
+        const externalExecutable = path.join(externalDirectory, executableName);
+        const externalHarness = path.join(externalDirectory, harnessName);
         yield* fs.makeDirectory(externalDirectory);
         yield* fs.writeFileString(externalExecutable, "external server", { mode: 0o755 });
         yield* fs.writeFileString(externalHarness, "external harness", { mode: 0o755 });
@@ -711,7 +726,7 @@ it.layer(NodeServices.layer)("Antigravity installation", (it) => {
           source: "override",
           managedVersionDirectory: null,
         });
-        expect(yield* installation.resolve("agy_acp_server.par")).toMatchObject({
+        expect(yield* installation.resolve(executableName)).toMatchObject({
           source: "override",
         });
         yield* fs.remove(externalHarness);
@@ -741,7 +756,7 @@ it.layer(NodeServices.layer)("Antigravity installation", (it) => {
           executablePath: externalExecutable,
         });
         expect(
-          yield* isolated.installation.resolve("agy_acp_server.par", { PATH: externalDirectory }),
+          yield* isolated.installation.resolve(executableName, { PATH: externalDirectory }),
         ).toMatchObject({ source: "override", executablePath: externalExecutable });
       }),
   );
@@ -774,20 +789,12 @@ it.layer(NodeServices.layer)("Antigravity installation", (it) => {
         yield* fs.remove(previous.harnessPath);
         const externalDirectory = path.join(baseDir, "external");
         yield* fs.makeDirectory(externalDirectory);
-        yield* fs.writeFileString(
-          path.join(externalDirectory, "agy_acp_server.par"),
-          "external server",
-          {
-            mode: 0o755,
-          },
-        );
-        yield* fs.writeFileString(
-          path.join(externalDirectory, "localharness_external"),
-          "external harness",
-          {
-            mode: 0o755,
-          },
-        );
+        yield* fs.writeFileString(path.join(externalDirectory, executableName), "external server", {
+          mode: 0o755,
+        });
+        yield* fs.writeFileString(path.join(externalDirectory, harnessName), "external harness", {
+          mode: 0o755,
+        });
         const restarted = yield* makeHarness({ baseDir, path: externalDirectory });
         expect(yield* restarted.installation.state).toMatchObject({
           phase: "failed",
@@ -824,8 +831,8 @@ it.layer(NodeServices.layer)("Antigravity installation", (it) => {
         const profileDirectory = path.join(baseDir, "providers", "antigravity", "profile");
         yield* fs.makeDirectory(externalDirectory);
         yield* fs.makeDirectory(profileDirectory, { recursive: true });
-        const externalExecutable = path.join(externalDirectory, "agy_acp_server.par");
-        const externalHarness = path.join(externalDirectory, "localharness_external");
+        const externalExecutable = path.join(externalDirectory, executableName);
+        const externalHarness = path.join(externalDirectory, harnessName);
         const profilePath = path.join(profileDirectory, "preferences.json");
         yield* fs.writeFileString(externalExecutable, "external server", { mode: 0o755 });
         yield* fs.writeFileString(externalHarness, "external harness", { mode: 0o755 });

From 5f4c7161fa7782ea93b63fe934d43229742e7ec8 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 13:33:23 -0700
Subject: [PATCH 19/56] fix(server): canonicalise media paths the same way
 their callers do (#9575)

Co-authored-by: Claude Code <noreply@anthropic.com>
---
 apps/server/src/assets/AssetAccess.test.ts     |  4 ++--
 apps/server/src/assets/MediaFile.ts            | 11 ++++++++++-
 .../src/project/ProjectFaviconResolver.test.ts | 18 ++++++++++--------
 3 files changed, 22 insertions(+), 11 deletions(-)

diff --git a/apps/server/src/assets/AssetAccess.test.ts b/apps/server/src/assets/AssetAccess.test.ts
index aacd37b2b35e..53e33cf7fd5b 100644
--- a/apps/server/src/assets/AssetAccess.test.ts
+++ b/apps/server/src/assets/AssetAccess.test.ts
@@ -754,7 +754,7 @@ describe("AssetAccess", () => {
         projectFaviconPath: "brand/custom.svg",
       });
 
-      expect(result.sourcePath).toBe("brand/custom.svg");
+      expect(result.sourcePath).toBe(path.join("brand", "custom.svg"));
       expect(result.relativeUrl).toMatch(/\/v[0-9a-f]{64}-custom\.svg$/);
     }).pipe(Effect.provide(testLayer)),
   );
@@ -813,7 +813,7 @@ describe("AssetAccess", () => {
         projectFaviconPath: "brand/saved.svg",
       });
 
-      expect(result.sourcePath).toBe("brand/saved.svg");
+      expect(result.sourcePath).toBe(path.join("brand", "saved.svg"));
       expect(result.relativeUrl).toMatch(/\/v[0-9a-f]{64}-saved\.svg$/);
     }).pipe(Effect.provide(testLayer)),
   );
diff --git a/apps/server/src/assets/MediaFile.ts b/apps/server/src/assets/MediaFile.ts
index f1b63bb659e3..e1053555b052 100644
--- a/apps/server/src/assets/MediaFile.ts
+++ b/apps/server/src/assets/MediaFile.ts
@@ -37,6 +37,11 @@ export interface OpenMediaFile {
   readonly info: NodeFS.BigIntStats;
 }
 
+const realpathLikeFileSystem = (filePath: string) =>
+  new Promise<string>((resolve, reject) => {
+    NodeFS.realpath(filePath, (error, resolved) => (error ? reject(error) : resolve(resolved)));
+  });
+
 /** Opens a canonical media path once. Replacements cannot change the response's source. */
 export const openMediaFile = Effect.fn("openMediaFile")(function* (
   filePath: string,
@@ -71,7 +76,11 @@ export const openMediaFile = Effect.fn("openMediaFile")(function* (
           ) {
             return null;
           }
-          if ((await NodeFSP.realpath(filePath)) !== filePath) return null;
+          // Callers canonicalise with Effect's FileSystem.realPath, which is
+          // Node's JS realpath. fs/promises.realpath is the native binding and
+          // on Windows also expands 8.3 short names, so a path that is already
+          // canonical by the caller's rules would still look swapped here.
+          if ((await realpathLikeFileSystem(filePath)) !== filePath) return null;
           const after = await NodeFSP.lstat(filePath, { bigint: true });
           if (!after.isFile() || info.dev !== after.dev || info.ino !== after.ino) return null;
           accepted = true;
diff --git a/apps/server/src/project/ProjectFaviconResolver.test.ts b/apps/server/src/project/ProjectFaviconResolver.test.ts
index b8d6b46da088..f86e8f8aa399 100644
--- a/apps/server/src/project/ProjectFaviconResolver.test.ts
+++ b/apps/server/src/project/ProjectFaviconResolver.test.ts
@@ -126,6 +126,7 @@ it.layer(TestLayer)("ProjectFaviconResolverLive", (it) => {
     it.effect("prefers a t3.json iconPath over well-known files", () =>
       Effect.gen(function* () {
         const resolver = yield* ProjectFaviconResolver.ProjectFaviconResolver;
+        const path = yield* Path.Path;
         const cwd = yield* makeTempDir;
         yield* writeTextFile(cwd, "t3.json", '{ "iconPath": "brand/mark.svg" }');
         yield* writeTextFile(cwd, "brand/mark.svg", "<svg>mark</svg>");
@@ -134,13 +135,14 @@ it.layer(TestLayer)("ProjectFaviconResolverLive", (it) => {
         const resolved = yield* resolver.resolvePath(cwd);
 
         expect(resolved).not.toBeNull();
-        expect(resolved).toContain("brand/mark.svg");
+        expect(resolved).toBe(path.join(cwd, "brand", "mark.svg"));
       }),
     );
 
     it.effect("uses a saved project favicon override", () =>
       Effect.gen(function* () {
         const resolver = yield* ProjectFaviconResolver.ProjectFaviconResolver;
+        const path = yield* Path.Path;
         const cwd = yield* makeTempDir;
         yield* writeTextFile(cwd, "brand/custom.svg", "<svg>custom</svg>");
         yield* writeTextFile(cwd, "favicon.svg", "<svg>automatic</svg>");
@@ -148,7 +150,7 @@ it.layer(TestLayer)("ProjectFaviconResolverLive", (it) => {
         const resolved = yield* resolver.resolvePath(cwd, "brand/custom.svg");
 
         expect(resolved).not.toBeNull();
-        expect(resolved).toContain("brand/custom.svg");
+        expect(resolved).toBe(path.join(cwd, "brand", "custom.svg"));
       }),
     );
 
@@ -232,7 +234,7 @@ it.layer(TestLayer)("ProjectFaviconResolverLive", (it) => {
         const resolved = yield* resolver.resolvePath(cwd);
 
         expect(resolved).not.toBeNull();
-        expect(resolved).toContain("public/brand/logo.svg");
+        expect(resolved).toBe((yield* Path.Path).join(cwd, "public", "brand", "logo.svg"));
       }),
     );
 
@@ -257,7 +259,7 @@ it.layer(TestLayer)("ProjectFaviconResolverLive", (it) => {
         const resolved = yield* resolver.resolvePath(cwd);
 
         expect(resolved).not.toBeNull();
-        expect(resolved).toContain("public/brand/logo.svg");
+        expect(resolved).toBe((yield* Path.Path).join(cwd, "public", "brand", "logo.svg"));
       }),
     );
 
@@ -275,7 +277,7 @@ it.layer(TestLayer)("ProjectFaviconResolverLive", (it) => {
         const resolved = yield* resolver.resolvePath(cwd);
 
         expect(resolved).not.toBeNull();
-        expect(resolved).toContain("public/brand/logo.svg");
+        expect(resolved).toBe((yield* Path.Path).join(cwd, "public", "brand", "logo.svg"));
       }),
     );
 
@@ -293,7 +295,7 @@ it.layer(TestLayer)("ProjectFaviconResolverLive", (it) => {
         const resolved = yield* resolver.resolvePath(cwd);
 
         expect(resolved).not.toBeNull();
-        expect(resolved).toContain("public/brand/logo.svg");
+        expect(resolved).toBe((yield* Path.Path).join(cwd, "public", "brand", "logo.svg"));
       }),
     );
 
@@ -311,7 +313,7 @@ it.layer(TestLayer)("ProjectFaviconResolverLive", (it) => {
         const resolved = yield* resolver.resolvePath(cwd);
 
         expect(resolved).not.toBeNull();
-        expect(resolved).toContain("public/brand/logo.svg");
+        expect(resolved).toBe((yield* Path.Path).join(cwd, "public", "brand", "logo.svg"));
       }),
     );
 
@@ -459,7 +461,7 @@ it.layer(TestLayer)("ProjectFaviconResolverLive", (it) => {
         const resolved = yield* resolver.resolvePath(cwd);
 
         expect(resolved).not.toBeNull();
-        expect(resolved).toContain("public/brand/logo.svg");
+        expect(resolved).toBe((yield* Path.Path).join(cwd, "public", "brand", "logo.svg"));
       }),
     );
   });

From b123cbb317ca47ff080a15b44c4bc0c99126f729 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 13:33:23 -0700
Subject: [PATCH 20/56] test(server): make Windows path and async fixtures
 deterministic (#9576)

Co-authored-by: Claude Code <noreply@anthropic.com>
---
 apps/server/src/bootstrap.test.ts             | 32 ++++++----
 apps/server/src/cli/config.test.ts            | 19 ++++--
 apps/server/src/cloud/bootService.test.ts     |  9 ++-
 .../Layers/AntigravityAdapter.test.ts         |  3 +-
 .../ProviderInstanceRegistryLive.test.ts      | 17 +++--
 .../provider/Layers/ProviderRegistry.test.ts  | 63 ++++++++++---------
 apps/server/src/server.test.ts                | 11 +++-
 .../SourceControlRepositoryService.test.ts    |  4 +-
 .../src/workspace/WorkspaceFileSystem.test.ts | 42 +++++++------
 9 files changed, 125 insertions(+), 75 deletions(-)

diff --git a/apps/server/src/bootstrap.test.ts b/apps/server/src/bootstrap.test.ts
index 722eb21a2461..d532f71c9fb8 100644
--- a/apps/server/src/bootstrap.test.ts
+++ b/apps/server/src/bootstrap.test.ts
@@ -57,6 +57,22 @@ vi.mock("node:fs", async (importOriginal) => {
 
 const windowsHost = HostProcessPlatform.defaultValue() === "win32";
 const nullDevice = windowsHost ? "\\\\.\\NUL" : "/dev/null";
+const closeIfOpen = (fd: number) => {
+  try {
+    NodeFS.closeSync(fd);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EBADF") throw error;
+  }
+};
+
+// A successful Windows read streams the inherited fd with autoClose. POSIX
+// reopens the fd through /proc or /dev, so the test still owns the original.
+const openBootstrapInputFd = (filePath: string) =>
+  Effect.acquireRelease(
+    Effect.sync(() => NodeFS.openSync(filePath, "r")),
+    (fd) => (windowsHost ? Effect.void : Effect.sync(() => closeIfOpen(fd))),
+  );
+
 const TestEnvelopeSchema = Schema.Struct({ mode: Schema.String });
 const encodeTestEnvelopeSchema = Schema.encodeEffect(Schema.fromJsonString(TestEnvelopeSchema));
 
@@ -71,10 +87,7 @@ it.layer(NodeServices.layer)("readBootstrapEnvelope", (it) => {
         `${yield* encodeTestEnvelopeSchema({ mode: "desktop" })}\n`,
       );
 
-      const fd = yield* Effect.acquireRelease(
-        Effect.sync(() => NodeFS.openSync(filePath, "r")),
-        (fd) => Effect.sync(() => NodeFS.closeSync(fd)),
-      );
+      const fd = yield* openBootstrapInputFd(filePath);
 
       const payload = yield* readBootstrapEnvelope(TestEnvelopeSchema, fd, { timeoutMs: 100 });
       assertSome(payload, {
@@ -119,7 +132,7 @@ it.layer(NodeServices.layer)("readBootstrapEnvelope", (it) => {
       const filePath = yield* fs.makeTempFileScoped({ prefix: "t3-bootstrap-", suffix: ".ndjson" });
       const fd = yield* Effect.acquireRelease(
         Effect.sync(() => NodeFS.openSync(filePath, "r")),
-        (fd) => Effect.sync(() => NodeFS.closeSync(fd)),
+        (fd) => Effect.sync(() => closeIfOpen(fd)),
       );
       const fdPath = `/proc/self/fd/${fd}`;
 
@@ -160,7 +173,7 @@ it.layer(NodeServices.layer)("readBootstrapEnvelope", (it) => {
     Effect.gen(function* () {
       const fd = yield* Effect.acquireRelease(
         Effect.sync(() => NodeFS.openSync(nullDevice, "r")),
-        (fd) => Effect.sync(() => NodeFS.closeSync(fd)),
+        (fd) => Effect.sync(() => closeIfOpen(fd)),
       );
 
       fstatSyncInterceptor.failFd = fd;
@@ -185,10 +198,7 @@ it.layer(NodeServices.layer)("readBootstrapEnvelope", (it) => {
       const filePath = yield* fs.makeTempFileScoped({ prefix: "t3-bootstrap-", suffix: ".ndjson" });
       yield* fs.writeFileString(filePath, '{"mode":42}\n');
 
-      const fd = yield* Effect.acquireRelease(
-        Effect.sync(() => NodeFS.openSync(filePath, "r")),
-        (fd) => Effect.sync(() => NodeFS.closeSync(fd)),
-      );
+      const fd = yield* openBootstrapInputFd(filePath);
       const error = yield* readBootstrapEnvelope(TestEnvelopeSchema, fd, {
         timeoutMs: 100,
       }).pipe(Effect.flip);
@@ -228,7 +238,7 @@ it.layer(NodeServices.layer)("readBootstrapEnvelope", (it) => {
 
         const fd = yield* Effect.acquireRelease(
           Effect.sync(() => NodeFS.openSync(fifoPath, "r")),
-          (fd) => Effect.sync(() => NodeFS.closeSync(fd)),
+          (fd) => Effect.sync(() => closeIfOpen(fd)),
         );
 
         const fiber = yield* readBootstrapEnvelope(TestEnvelopeSchema, fd, {
diff --git a/apps/server/src/cli/config.test.ts b/apps/server/src/cli/config.test.ts
index def63b61fafe..2267a5cb1cc9 100644
--- a/apps/server/src/cli/config.test.ts
+++ b/apps/server/src/cli/config.test.ts
@@ -60,7 +60,16 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
     yield* fs.writeFileString(filePath, `${encoded}\n`);
     return yield* Effect.acquireRelease(
       Effect.sync(() => NodeFS.openSync(filePath, "r")),
-      (fd) => Effect.sync(() => NodeFS.closeSync(fd)),
+      // Without a /proc or /dev/fd path to reopen, the reader consumes the fd
+      // itself (autoClose), so on Windows it is already closed here.
+      (fd) =>
+        Effect.sync(() => {
+          try {
+            NodeFS.closeSync(fd);
+          } catch (error) {
+            if ((error as NodeJS.ErrnoException).code !== "EBADF") throw error;
+          }
+        }),
     );
   });
 
@@ -281,13 +290,15 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
 
   it.effect("uses bootstrap envelope values as fallbacks when flags and env are absent", () =>
     Effect.gen(function* () {
-      const { join } = yield* Path.Path;
-      const baseDir = "/tmp/t3-bootstrap-home";
+      const { join, resolve } = yield* Path.Path;
+      // The resolver absolutises the configured home, so the expectation must
+      // carry the host's drive on Windows.
+      const baseDir = resolve("/tmp/t3-bootstrap-home");
       const fd = yield* openBootstrapFd(
         makeDesktopBootstrap({
           port: 4888,
           host: "127.0.0.2",
-          t3Home: baseDir,
+          t3Home: "/tmp/t3-bootstrap-home",
           noBrowser: true,
           desktopBootstrapToken: "desktop-token",
           desktopTelemetryFd: 4,
diff --git a/apps/server/src/cloud/bootService.test.ts b/apps/server/src/cloud/bootService.test.ts
index c820f93cd212..688617440500 100644
--- a/apps/server/src/cloud/bootService.test.ts
+++ b/apps/server/src/cloud/bootService.test.ts
@@ -529,11 +529,14 @@ it.layer(NodeServices.layer)("boot service install", (it) => {
   it.effect("installs, reports current state, and uninstalls on macOS", () =>
     Effect.gen(function* () {
       const { service, fs, statePath, commands, timeouts } = yield* makeHarness("darwin");
+      const path = yield* Path.Path;
       const plan = yield* service.install();
 
-      expect(plan.unitPath.endsWith("Library/LaunchAgents/com.t3tools.t3code.service.plist")).toBe(
-        true,
-      );
+      expect(
+        plan.unitPath.endsWith(
+          path.join("Library", "LaunchAgents", "com.t3tools.t3code.service.plist"),
+        ),
+      ).toBe(true);
       expect(yield* fs.readFileString(plan.unitPath)).toContain(
         `    <key>PATH</key>\n    <string>${macInstallerPath}:/usr/local/bin:/usr/sbin:/sbin</string>`,
       );
diff --git a/apps/server/src/provider/Layers/AntigravityAdapter.test.ts b/apps/server/src/provider/Layers/AntigravityAdapter.test.ts
index 6020d688cbd4..4bd0bb3e1010 100644
--- a/apps/server/src/provider/Layers/AntigravityAdapter.test.ts
+++ b/apps/server/src/provider/Layers/AntigravityAdapter.test.ts
@@ -421,7 +421,8 @@ it.layer(layer)("AntigravityAdapter", (it) => {
         modelSelection: { instanceId, model: nativeAlternative },
       });
       expect(second.model).toBe(nativeAlternative);
-      expect(second.cwd).toBe("/tmp");
+      // The adapter resolves the cwd it was given through the host Path.
+      expect(second.cwd).toBe((yield* Path.Path).resolve("/tmp"));
       expect(h.launches[1]?.resumeSessionId).toBe(nativeSessionId);
       expect(h.calls).toEqual([
         "start",
diff --git a/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts b/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts
index d750789fde02..af43e039e652 100644
--- a/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts
+++ b/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts
@@ -24,6 +24,7 @@
  */
 import { describe, expect, it } from "@effect/vitest";
 import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as Path from "effect/Path";
 import {
   type ClaudeSettings,
   type CodexSettings,
@@ -214,15 +215,19 @@ describe("ProviderInstanceRegistryLive — multi-instance codex slice", () => {
       expect(personalSnapshot.instanceId).toBe(personalId);
       expect(personalSnapshot.driver).toBe(codexDriverKind);
       expect(personalSnapshot.enabled).toBe(false);
+      // The layout resolves the configured home through the host Path.
+      const path = yield* Path.Path;
       expect(personalSnapshot.continuation?.groupKey).toBe(
-        "codex:home:/home/julius/.codex_personal",
+        `codex:home:${path.resolve("/home/julius/.codex_personal")}`,
       );
 
       const workSnapshot = yield* work!.snapshot.getSnapshot;
       expect(workSnapshot.instanceId).toBe(workId);
       expect(workSnapshot.driver).toBe(codexDriverKind);
       expect(workSnapshot.enabled).toBe(false);
-      expect(workSnapshot.continuation?.groupKey).toBe("codex:home:/home/julius/.codex");
+      expect(workSnapshot.continuation?.groupKey).toBe(
+        `codex:home:${path.resolve("/home/julius/.codex")}`,
+      );
 
       // Nothing goes to the unavailable bucket — both drivers are registered.
       const unavailable = yield* registry.listUnavailable;
@@ -451,13 +456,17 @@ describe("ProviderInstanceRegistryLive — all drivers slice", () => {
       expect(codexSnapshot.instanceId).toBe(codexId);
       expect(codexSnapshot.driver).toBe(codexDriverKind);
       expect(codexSnapshot.enabled).toBe(false);
-      expect(codexSnapshot.continuation?.groupKey).toBe("codex:home:/home/julius/.codex");
+      expect(codexSnapshot.continuation?.groupKey).toBe(
+        `codex:home:${(yield* Path.Path).resolve("/home/julius/.codex")}`,
+      );
 
       const claudeSnapshot = yield* claude!.snapshot.getSnapshot;
       expect(claudeSnapshot.instanceId).toBe(claudeId);
       expect(claudeSnapshot.driver).toBe(claudeDriverKind);
       expect(claudeSnapshot.enabled).toBe(false);
-      expect(claudeSnapshot.continuation?.groupKey).toBe("claude:home:/home/julius/.claude-work");
+      expect(claudeSnapshot.continuation?.groupKey).toBe(
+        `claude:home:${(yield* Path.Path).resolve("/home/julius/.claude-work")}`,
+      );
 
       const cursorSnapshot = yield* cursor!.snapshot.getSnapshot;
       expect(cursorSnapshot.instanceId).toBe(cursorId);
diff --git a/apps/server/src/provider/Layers/ProviderRegistry.test.ts b/apps/server/src/provider/Layers/ProviderRegistry.test.ts
index d3843829159c..c687fc2fe988 100644
--- a/apps/server/src/provider/Layers/ProviderRegistry.test.ts
+++ b/apps/server/src/provider/Layers/ProviderRegistry.test.ts
@@ -3,6 +3,7 @@ import { describe, it, assert } from "@effect/vitest";
 import * as DateTime from "effect/DateTime";
 import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
+import * as Path from "effect/Path";
 import * as Exit from "effect/Exit";
 import * as Fiber from "effect/Fiber";
 import * as Layer from "effect/Layer";
@@ -346,6 +347,21 @@ function makeMutableServerSettingsService(
   });
 }
 
+// The registry writes the status cache and only then publishes the change, so
+// a subscriber that sees `checkedAt` on the stream knows the file is on disk.
+// Subscribed before the publish that triggers it; a spin on the file would
+// race the write and lose on a slow host.
+const awaitPersistedProvider = (
+  registry: ProviderRegistry.ProviderRegistry["Service"],
+  checkedAt: string,
+) =>
+  registry.streamChanges.pipe(
+    Stream.filter((providers) => providers.some((provider) => provider.checkedAt === checkedAt)),
+    Stream.take(1),
+    Stream.runDrain,
+    Effect.forkScoped,
+  );
+
 it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), TestHttpClientLive))(
   "ProviderRegistry",
   (it) => {
@@ -1752,18 +1768,10 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
             assert.deepStrictEqual((yield* registry.getProviders)[0]?.models, [
               ...initialProvider.models,
             ]);
+            const persisted = yield* awaitPersistedProvider(registry, refreshedProvider.checkedAt);
             yield* PubSub.publish(changes, refreshedProvider);
-
-            let cachedProvider = yield* readProviderStatusCache(filePath);
-            for (
-              let attempt = 0;
-              attempt < 50 && cachedProvider?.checkedAt !== refreshedProvider.checkedAt;
-              attempt += 1
-            ) {
-              yield* TestClock.adjust("10 millis");
-              yield* Effect.yieldNow;
-              cachedProvider = yield* readProviderStatusCache(filePath);
-            }
+            yield* Fiber.join(persisted);
+            const cachedProvider = yield* readProviderStatusCache(filePath);
 
             assert.deepStrictEqual(cachedProvider, {
               ...refreshedProvider,
@@ -1878,31 +1886,23 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
                 instanceId: openCodeInstanceId,
               });
 
+              const authoritativePersisted = yield* awaitPersistedProvider(
+                registry,
+                authoritativeProvider.checkedAt,
+              );
               yield* PubSub.publish(changes, authoritativeProvider);
-
+              yield* Fiber.join(authoritativePersisted);
               let cachedProvider = yield* readProviderStatusCache(filePath);
-              for (
-                let attempt = 0;
-                attempt < 50 && cachedProvider?.checkedAt !== authoritativeProvider.checkedAt;
-                attempt += 1
-              ) {
-                yield* TestClock.adjust("10 millis");
-                yield* Effect.yieldNow;
-                cachedProvider = yield* readProviderStatusCache(filePath);
-              }
 
               assert.deepStrictEqual(cachedProvider?.models, [authoritativeProvider.models[0]!]);
 
+              const failedPersisted = yield* awaitPersistedProvider(
+                registry,
+                failedProvider.checkedAt,
+              );
               yield* PubSub.publish(changes, failedProvider);
-              for (
-                let attempt = 0;
-                attempt < 50 && cachedProvider?.checkedAt !== failedProvider.checkedAt;
-                attempt += 1
-              ) {
-                yield* TestClock.adjust("10 millis");
-                yield* Effect.yieldNow;
-                cachedProvider = yield* readProviderStatusCache(filePath);
-              }
+              yield* Fiber.join(failedPersisted);
+              cachedProvider = yield* readProviderStatusCache(filePath);
 
               assert.deepStrictEqual(cachedProvider?.models, [authoritativeProvider.models[0]!]);
               assert.deepStrictEqual((yield* registry.getProviders)[0]?.models, [
@@ -2715,9 +2715,10 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
             claudeCapabilities(),
           );
           assert.strictEqual(status.status, "ready");
+          // The home is resolved through the host Path before it reaches the env.
           assert.deepStrictEqual(
             recorded.commands.map((command) => command.env?.CLAUDE_CONFIG_DIR),
-            [claudeConfigDir],
+            [(yield* Path.Path).resolve(claudeConfigDir)],
           );
         }).pipe(Effect.provide(recorded.layer));
       });
diff --git a/apps/server/src/server.test.ts b/apps/server/src/server.test.ts
index c853c86e5a6b..92def1774e74 100644
--- a/apps/server/src/server.test.ts
+++ b/apps/server/src/server.test.ts
@@ -1855,12 +1855,18 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
       const staticDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-static-replace-" });
       const beforeOpenPath = path.join(staticDir, "before-open.txt");
       const afterOpenPath = path.join(staticDir, "after-open.txt");
+      const afterOpenSnapshotPath = path.join(staticDir, "after-open-snapshot.txt");
+      const windowsHost = HostProcessPlatform.defaultValue() === "win32";
       const original = "original bytes";
       const replacement = "replacement bytes with a different size";
       for (const filePath of [beforeOpenPath, afterOpenPath]) {
         yield* fileSystem.writeFileString(filePath, original);
         yield* fileSystem.writeFileString(`${filePath}.next`, replacement);
       }
+      if (windowsHost) {
+        // Windows cannot replace an open destination, so model the race with its original handle.
+        yield* fileSystem.writeFileString(afterOpenSnapshotPath, original);
+      }
       const replaced = new Set<string>();
       const replaceOnce = Effect.fnUntraced(function* (filePath: string) {
         if (replaced.has(filePath)) return;
@@ -1877,7 +1883,10 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
             ),
         open: (filePath, options) =>
           fileSystem
-            .open(filePath, options)
+            .open(
+              filePath === afterOpenPath && windowsHost ? afterOpenSnapshotPath : filePath,
+              options,
+            )
             .pipe(
               Effect.tap(() => (filePath === afterOpenPath ? replaceOnce(filePath) : Effect.void)),
             ),
diff --git a/apps/server/src/sourceControl/SourceControlRepositoryService.test.ts b/apps/server/src/sourceControl/SourceControlRepositoryService.test.ts
index 861da9a10e05..461bff08668a 100644
--- a/apps/server/src/sourceControl/SourceControlRepositoryService.test.ts
+++ b/apps/server/src/sourceControl/SourceControlRepositoryService.test.ts
@@ -3,6 +3,7 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
 import * as Layer from "effect/Layer";
 import * as PlatformError from "effect/PlatformError";
 import { ChildProcessSpawner } from "effect/unstable/process";
@@ -153,10 +154,11 @@ it.effect("preserves provider failures without deriving the repository message f
 it.effect("clones a looked-up repository into the requested destination", () =>
   Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
     const parent = yield* fs.makeTempDirectoryScoped({
       prefix: "t3-source-control-clone-parent-",
     });
-    const destinationPath = `${parent}/t3code`;
+    const destinationPath = path.join(parent, "t3code");
     const cloneCalls: Array<{ cwd: string; args: ReadonlyArray<string> }> = [];
 
     yield* Effect.gen(function* () {
diff --git a/apps/server/src/workspace/WorkspaceFileSystem.test.ts b/apps/server/src/workspace/WorkspaceFileSystem.test.ts
index 591414f85bcf..5afc212ce172 100644
--- a/apps/server/src/workspace/WorkspaceFileSystem.test.ts
+++ b/apps/server/src/workspace/WorkspaceFileSystem.test.ts
@@ -14,6 +14,7 @@ import * as VcsProcess from "../vcs/VcsProcess.ts";
 import * as WorkspaceEntries from "./WorkspaceEntries.ts";
 import * as WorkspaceFileSystem from "./WorkspaceFileSystem.ts";
 import * as WorkspacePaths from "./WorkspacePaths.ts";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const ProjectLayer = WorkspaceFileSystem.layer.pipe(
@@ -100,28 +101,31 @@ it.layer(TestLayer, { excludeTestServices: true })("WorkspaceFileSystemLive", (i
       }),
     );
 
-    it.effect("rejects a FIFO without blocking on open", () =>
-      Effect.gen(function* () {
-        const workspaceFileSystem = yield* WorkspaceFileSystem.WorkspaceFileSystem;
-        const path = yield* Path.Path;
-        const cwd = yield* makeTempDir;
-        const outsideDir = yield* makeTempDir;
-        const fifoPath = path.join(outsideDir, "pipe");
-        yield* Effect.promise(
-          () =>
-            new Promise<void>((resolve, reject) =>
-              NodeChildProcess.execFile("mkfifo", [fifoPath], (error) =>
-                error ? reject(error) : resolve(),
+    // Needs mkfifo; Windows has no FIFOs to reject.
+    it.effect.skipIf(HostProcessPlatform.defaultValue() === "win32")(
+      "rejects a FIFO without blocking on open",
+      () =>
+        Effect.gen(function* () {
+          const workspaceFileSystem = yield* WorkspaceFileSystem.WorkspaceFileSystem;
+          const path = yield* Path.Path;
+          const cwd = yield* makeTempDir;
+          const outsideDir = yield* makeTempDir;
+          const fifoPath = path.join(outsideDir, "pipe");
+          yield* Effect.promise(
+            () =>
+              new Promise<void>((resolve, reject) =>
+                NodeChildProcess.execFile("mkfifo", [fifoPath], (error) =>
+                  error ? reject(error) : resolve(),
+                ),
               ),
-            ),
-        );
+          );
 
-        const error = yield* workspaceFileSystem
-          .readFile({ cwd, relativePath: fifoPath })
-          .pipe(Effect.flip);
+          const error = yield* workspaceFileSystem
+            .readFile({ cwd, relativePath: fifoPath })
+            .pipe(Effect.flip);
 
-        expect(error).toBeInstanceOf(WorkspaceFileSystem.WorkspacePathNotFileError);
-      }),
+          expect(error).toBeInstanceOf(WorkspaceFileSystem.WorkspacePathNotFileError);
+        }),
     );
 
     it.effect("rejects reads outside the workspace root", () =>

From 781f41ef1f6b5054e75f77237df9eba3b7f61cc9 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 13:33:23 -0700
Subject: [PATCH 21/56] fix(server): refuse symlinked theme files on Windows
 too (#9580)

Co-authored-by: Claude Code <noreply@anthropic.com>
---
 apps/server/src/environmentTheme.ts | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/apps/server/src/environmentTheme.ts b/apps/server/src/environmentTheme.ts
index c038af065bdc..b7eb11940cea 100644
--- a/apps/server/src/environmentTheme.ts
+++ b/apps/server/src/environmentTheme.ts
@@ -95,13 +95,23 @@ export class EnvironmentThemeService extends Context.Service<
  * usable, a symlinked file inside it does not), O_NONBLOCK keeps a FIFO from
  * blocking the open, and the fstat type and size gate examines the open
  * descriptor. Returns null for anything that is not a small regular file.
+ *
+ * Windows has neither flag (the constants are undefined, and OR-ing them in
+ * is a no-op), so the symlink check there is an lstat before the open. That
+ * leaves a window a swap could slip through, which the descriptor-bound
+ * checks below then narrow to "a regular file at that path".
  */
 export const readThemeFileGuarded = (filePath: string, maxBytes: number): string | null => {
   let fd: number;
   try {
+    if (NodeFS.constants.O_NOFOLLOW === undefined && NodeFS.lstatSync(filePath).isSymbolicLink()) {
+      return null;
+    }
     fd = NodeFS.openSync(
       filePath,
-      NodeFS.constants.O_RDONLY | NodeFS.constants.O_NOFOLLOW | NodeFS.constants.O_NONBLOCK,
+      NodeFS.constants.O_RDONLY |
+        (NodeFS.constants.O_NOFOLLOW ?? 0) |
+        (NodeFS.constants.O_NONBLOCK ?? 0),
     );
   } catch {
     return null;

From 0a590fa01af66ec135d2ebf2d5542b08a37dc275 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 13:33:24 -0700
Subject: [PATCH 22/56] test(scripts): keep Windows packaging checks
 host-portable (#9589)

Co-authored-by: Claude Code <noreply@anthropic.com>
---
 scripts/build-desktop-artifact.test.ts    | 14 +++++----
 scripts/lib/cli-external-packages.test.ts | 35 +++++++++++++----------
 2 files changed, 29 insertions(+), 20 deletions(-)

diff --git a/scripts/build-desktop-artifact.test.ts b/scripts/build-desktop-artifact.test.ts
index c3d40a03d3ce..affb83eb7506 100644
--- a/scripts/build-desktop-artifact.test.ts
+++ b/scripts/build-desktop-artifact.test.ts
@@ -1040,6 +1040,9 @@ it.layer(NodeServices.layer)("build-desktop-artifact", (it) => {
     ),
   );
 
+  // The fixture's t3code.exe is a text placeholder, not an executable. These
+  // cases reach the native-load probe, so pin only that host-platform check to
+  // Linux. Host-native paths and the real Windows tar/archive checks still run.
   it.effect("validates every ASAR-unpacked native in the packaged Windows payload", () =>
     Effect.scoped(
       Effect.gen(function* () {
@@ -1068,7 +1071,7 @@ it.layer(NodeServices.layer)("build-desktop-artifact", (it) => {
         assert.isBelow(result.fileCount, WINDOWS_PACKAGED_PAYLOAD_FILE_LIMIT);
         assert.deepStrictEqual(secondAsar, firstAsar);
       }),
-    ),
+    ).pipe(Effect.provideService(HostProcessPlatform, "linux")),
   );
 
   it.effect("validates the emitted WSL archive and its SHA-256 sidecar", () =>
@@ -1087,7 +1090,7 @@ it.layer(NodeServices.layer)("build-desktop-artifact", (it) => {
 
         assert.equal(result.packagedAppDir, fixture.packagedAppDir);
       }),
-    ),
+    ).pipe(Effect.provideService(HostProcessPlatform, "linux")),
   );
 
   it.effect("rejects a Windows package missing its expected WSL runtime", () =>
@@ -1235,11 +1238,12 @@ it.layer(NodeServices.layer)("build-desktop-artifact", (it) => {
         command.args.some((arg) => arg.endsWith("build-browser-secret.mjs")),
       );
       assert.isDefined(helper);
+      const path = yield* Path.Path;
       assert.deepStrictEqual(helper.args.slice(-4), [
         "--arch",
         "x64",
         "--output",
-        "/stage/resources/browser-secret/t3-browser-secret",
+        path.join("/stage/resources", "browser-secret", "t3-browser-secret"),
       ]);
     }).pipe(
       Effect.provide(
@@ -1461,7 +1465,7 @@ it.layer(NodeServices.layer)("build-desktop-artifact", (it) => {
         assert.instanceOf(error, BundleNotSelfContainedError);
         assert.include(error.output, "t3code-deliberately-missing-package");
       }),
-    ),
+    ).pipe(Effect.provideService(HostProcessPlatform, "linux")),
   );
 
   it.effect("preserves both Linux icon resize failures with structural context", () => {
@@ -1701,7 +1705,7 @@ it.layer(NodeServices.layer)("build-desktop-artifact", (it) => {
       assert.equal(config.appId, "com.t3tools.t3code");
       assert.equal(mac.entitlements, "/tmp/entitlements.mac.plist");
       assert.equal(mac.provisioningProfile, "/tmp/t3code.provisionprofile");
-      assert.match(String(mac.sign), /\/scripts\/sign-macos\.ts$/);
+      assert.match(String(mac.sign), /[\\/]scripts[\\/]sign-macos\.ts$/);
       assert.deepStrictEqual(mac.protocols, [
         { name: "T3 Code", schemes: ["t3code", "t3code-dev"] },
       ]);
diff --git a/scripts/lib/cli-external-packages.test.ts b/scripts/lib/cli-external-packages.test.ts
index 754cd646f17d..e894359eccb5 100644
--- a/scripts/lib/cli-external-packages.test.ts
+++ b/scripts/lib/cli-external-packages.test.ts
@@ -153,21 +153,26 @@ it.layer(NodeServices.layer)("external package dependency closure", (it) => {
   const isRuntimeExternal = (name: string) =>
     CLI_RUNTIME_EXTERNAL_PREFIXES.some((prefix) => name.startsWith(prefix));
 
-  it.effect("finds the runtime-external packages on disk", () =>
-    Effect.gen(function* () {
-      const installed = yield* readInstalledPackages;
-      const found = [...installed.keys()].filter(isRuntimeExternal);
-
-      // Without this the closure check below can pass vacuously: if nothing is
-      // read, nothing is checked. These are the packages whose closure actually
-      // broke WSL, so require them by name.
-      for (const required of ["node-pty", "node-gyp-build-optional-packages", "detect-libc"]) {
-        assert.ok(
-          found.includes(required),
-          `expected ${required} in the pnpm store; the closure check is only meaningful if it can read these (found ${found.length})`,
-        );
-      }
-    }),
+  // A cold walk of the pnpm store can exceed the root timeout when the Windows
+  // lane runs four filesystem-heavy workspace suites at once.
+  it.effect(
+    "finds the runtime-external packages on disk",
+    () =>
+      Effect.gen(function* () {
+        const installed = yield* readInstalledPackages;
+        const found = [...installed.keys()].filter(isRuntimeExternal);
+
+        // Without this the closure check below can pass vacuously: if nothing is
+        // read, nothing is checked. These are the packages whose closure actually
+        // broke WSL, so require them by name.
+        for (const required of ["node-pty", "node-gyp-build-optional-packages", "detect-libc"]) {
+          assert.ok(
+            found.includes(required),
+            `expected ${required} in the pnpm store; the closure check is only meaningful if it can read these (found ${found.length})`,
+          );
+        }
+      }),
+    120_000,
   );
 
   it.effect("keeps every runtime dependency of an external package external too", () =>

From b7d6e65021b021207424c56cb32d6d711fd875fb Mon Sep 17 00:00:00 2001
From: Simone <lucenz@proton.me>
Date: Fri, 4 Sep 2026 22:48:00 +0200
Subject: [PATCH 23/56] fix(contracts): include tool.denied in runtime event
 types (#9770)

Co-authored-by: Simone <185146821+Lucenx9@users.noreply.github.com>
---
 packages/contracts/src/providerRuntime.test.ts | 12 ++++++++++--
 packages/contracts/src/providerRuntime.ts      |  1 +
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/packages/contracts/src/providerRuntime.test.ts b/packages/contracts/src/providerRuntime.test.ts
index f7404c66ed6a..9ba30b235fc1 100644
--- a/packages/contracts/src/providerRuntime.test.ts
+++ b/packages/contracts/src/providerRuntime.test.ts
@@ -1,11 +1,19 @@
-import { describe, expect, it } from "vite-plus/test";
+import { describe, expect, expectTypeOf, it } from "vite-plus/test";
 import * as Schema from "effect/Schema";
 
-import { classifyTaskAgentKind, ProviderRuntimeEvent } from "./providerRuntime.ts";
+import {
+  classifyTaskAgentKind,
+  ProviderRuntimeEvent,
+  type ProviderRuntimeEventType,
+} from "./providerRuntime.ts";
 
 const decodeRuntimeEvent = Schema.decodeUnknownSync(ProviderRuntimeEvent);
 
 describe("ProviderRuntimeEvent", () => {
+  it("includes every runtime event in the public event type", () => {
+    expectTypeOf<ProviderRuntimeEvent["type"]>().toEqualTypeOf<ProviderRuntimeEventType>();
+  });
+
   it("requires input and output totals for complete turn usage", () => {
     const completeEvent = {
       type: "turn.completed",
diff --git a/packages/contracts/src/providerRuntime.ts b/packages/contracts/src/providerRuntime.ts
index 1996b17bb4dd..0d17f86e1942 100644
--- a/packages/contracts/src/providerRuntime.ts
+++ b/packages/contracts/src/providerRuntime.ts
@@ -186,6 +186,7 @@ const ProviderRuntimeEventType = Schema.Literals([
   "hook.completed",
   "tool.progress",
   "tool.summary",
+  "tool.denied",
   "auth.status",
   "account.updated",
   "account.rate-limits.updated",

From 24aef0e6c1bd5373a82eeed8054b50fc6e041b76 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 14:10:30 -0700
Subject: [PATCH 24/56] feat(mobile): split the usage page into Usage and
 Limits tabs (#9775)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---
 .../src/features/usage/UsageLimitsSection.tsx | 180 ++++++++++----
 .../src/features/usage/UsageRouteScreen.tsx   | 229 ++++++++++--------
 docs/user/usage.md                            |   2 +
 3 files changed, 274 insertions(+), 137 deletions(-)

diff --git a/apps/mobile/src/features/usage/UsageLimitsSection.tsx b/apps/mobile/src/features/usage/UsageLimitsSection.tsx
index 08e939e9b4bd..0668efa30053 100644
--- a/apps/mobile/src/features/usage/UsageLimitsSection.tsx
+++ b/apps/mobile/src/features/usage/UsageLimitsSection.tsx
@@ -7,6 +7,7 @@ import type {
   ServerProviderResetCredits,
   ServerProviderUsageWindow,
   UsageLimitSourceAccount,
+  UsageProviderKind,
 } from "@t3tools/contracts";
 import {
   collectLimitSources,
@@ -22,30 +23,46 @@ import { type ReactNode, useState } from "react";
 import { Alert, Pressable, View } from "react-native";
 
 import { AppText as Text } from "../../components/AppText";
+import { ProviderIcon } from "../../components/ProviderIcon";
 import { environmentPresentations } from "../../state/presentation";
 import { serverEnvironment } from "../../state/server";
 import { useAtomCommand } from "../../state/use-atom-command";
 import { SettingsSection } from "../settings/components/SettingsSection";
+import { useProviderColors } from "./usageProviders";
 
 const PACE_LABEL = { ahead: "ahead of pace", on: "on pace", under: "under pace" } as const;
 const DRIVER_LABEL: Partial<Record<string, string>> = { codex: "Codex", claudeAgent: "Claude" };
 
+type Driver = ServerProvider["driver"];
+
+/** The series colour the usage chart uses for this driver, so the two views read as one. */
+function useBarColor(driver: Driver): string | null {
+  const colors = useProviderColors();
+  const kind: UsageProviderKind | null =
+    driver === "codex" ? "codex" : driver === "claudeAgent" ? "claude" : null;
+  return kind ? colors[kind] : null;
+}
+
 /**
  * One window as a bar spanning its whole duration: the fill is quota spent,
- * the hairline is how far into the window the clock is.
+ * the hairline is how far into the window the clock is. Pace sits under the
+ * left edge, the countdown under the right, so a row reads in one glance.
  */
-function WindowBar(props: { readonly window: ServerProviderUsageWindow; readonly now: number }) {
+function WindowRow(props: {
+  readonly window: ServerProviderUsageWindow;
+  readonly color: string | null;
+  readonly now: number;
+}) {
   const { window, now } = props;
   const used = Math.round(Math.max(0, Math.min(100, window.usedPercent)));
   const elapsed = elapsedShare(window, now);
   const pace = paceOf(window, now);
   const resetsIn = formatResetsIn(window, now);
-  const detail = [pace ? PACE_LABEL[pace] : null, resetsIn].filter(Boolean).join(" · ");
   return (
-    <View className="gap-1.5">
+    <View className="gap-1">
       <View className="flex-row items-baseline justify-between gap-3">
-        <Text className="text-base text-foreground">{window.label}</Text>
-        <Text className="text-base tabular-nums text-foreground">{used}% used</Text>
+        <Text className="text-sm text-foreground">{window.label}</Text>
+        <Text className="text-sm font-t3-medium tabular-nums text-foreground">{used}%</Text>
       </View>
       <View className="h-3 justify-center">
         <View className="h-1.5 flex-row overflow-hidden rounded-full bg-subtle">
@@ -57,7 +74,10 @@ function WindowBar(props: { readonly window: ServerProviderUsageWindow; readonly
                   ? "h-full rounded-full bg-warning"
                   : "h-full rounded-full bg-foreground"
             }
-            style={{ flex: used }}
+            style={[
+              { flex: used },
+              used < 70 && props.color ? { backgroundColor: props.color } : null,
+            ]}
           />
           <View style={{ flex: 100 - used }} />
         </View>
@@ -68,12 +88,19 @@ function WindowBar(props: { readonly window: ServerProviderUsageWindow; readonly
           />
         ) : null}
       </View>
-      {detail ? <Text className="text-xs text-foreground-tertiary">{detail}</Text> : null}
+      {pace || resetsIn ? (
+        <View className="flex-row justify-between gap-3">
+          <Text className="text-xs text-foreground-tertiary">{pace ? PACE_LABEL[pace] : ""}</Text>
+          <Text className="text-xs tabular-nums text-foreground-tertiary">{resetsIn ?? ""}</Text>
+        </View>
+      ) : null}
     </View>
   );
 }
 
+/** One account: icon, name and plan on a single line, then its windows. */
 function AccountLimits(props: {
+  readonly driver: Driver;
   readonly label: string;
   readonly instanceLabel: string;
   readonly detail: string | undefined;
@@ -83,23 +110,35 @@ function AccountLimits(props: {
   readonly footer?: ReactNode;
 }) {
   const { limits, now } = props;
+  const color = useBarColor(props.driver);
   if (!limits) return null;
   const notice = limitsNotice(limits);
   return (
     <View className={props.first ? "gap-3 p-4" : "gap-3 border-t border-border-subtle p-4"}>
-      <View className="flex-row flex-wrap items-baseline gap-x-2 gap-y-1">
-        <Text className="text-lg text-foreground">{props.label}</Text>
-        {props.instanceLabel !== props.label ? (
-          <Text className="shrink text-xs text-foreground-tertiary">· {props.instanceLabel}</Text>
-        ) : null}
-        {props.detail ? (
-          <Text className="shrink text-sm text-foreground-muted">· {props.detail}</Text>
-        ) : null}
+      <View className="flex-row items-center gap-2">
+        <ProviderIcon provider={props.driver} size={16} />
+        <View className="min-w-0 flex-1 flex-row items-baseline gap-2">
+          <Text className="text-base font-t3-medium text-foreground">{props.label}</Text>
+          {props.instanceLabel !== props.label ? (
+            <Text className="shrink text-xs text-foreground-tertiary" numberOfLines={1}>
+              · {props.instanceLabel}
+            </Text>
+          ) : null}
+          {props.detail ? (
+            <Text className="shrink text-sm text-foreground-muted" numberOfLines={1}>
+              · {props.detail}
+            </Text>
+          ) : null}
+        </View>
       </View>
       {notice ? (
         <Text className="text-sm text-foreground-muted">{notice}</Text>
       ) : (
-        limits.windows.map((window) => <WindowBar key={window.id} window={window} now={now} />)
+        <View className="gap-3">
+          {limits.windows.map((window) => (
+            <WindowRow key={window.id} window={window} color={color} now={now} />
+          ))}
+        </View>
       )}
       {props.footer}
     </View>
@@ -170,7 +209,7 @@ function ResetCredits(props: {
   };
 
   return (
-    <View className="gap-2">
+    <View className="flex-row flex-wrap items-center gap-x-3 gap-y-1">
       <Text className="text-xs tabular-nums text-foreground-tertiary">{summary}</Text>
       {credits.availableCount > 0 ? (
         <Pressable
@@ -178,7 +217,7 @@ function ResetCredits(props: {
           accessibilityState={{ disabled: busy }}
           disabled={busy}
           onPress={confirm}
-          className="self-start rounded-full bg-subtle-strong px-3 py-1.5"
+          className="rounded-full bg-subtle-strong px-3 py-1.5"
         >
           <Text className="text-sm font-t3-medium text-foreground">
             {busy ? "Using credit…" : "Use a reset credit"}
@@ -200,6 +239,7 @@ function ProviderLimits(props: {
   const credits = provider.usageLimits?.resetCredits;
   return (
     <AccountLimits
+      driver={provider.driver}
       label={DRIVER_LABEL[provider.driver] ?? String(provider.driver)}
       instanceLabel={providerLimitsLabel(provider, (driver) => DRIVER_LABEL[driver])}
       detail={provider.auth.label}
@@ -229,6 +269,7 @@ function SourceAccountLimits(props: {
   const { account } = props;
   return (
     <AccountLimits
+      driver={account.driver}
       label={DRIVER_LABEL[account.driver] ?? String(account.driver)}
       instanceLabel="CLI Proxy"
       detail={account.plan}
@@ -239,21 +280,93 @@ function SourceAccountLimits(props: {
   );
 }
 
+/**
+ * Re-probes every provider (and usage-limit source) on each connected
+ * environment; the fresh snapshots then arrive over the config stream.
+ * Countdowns and pace anchor to `now` rather than ticking, so a refresh also
+ * re-anchors the clock: quota and elapsed time move together, or not at all.
+ * Environments whose probe failed are named, since their rows keep showing
+ * the previous quota with nothing else to say so.
+ */
+export function useRefreshLimits() {
+  const presentations = useAtomValue(environmentPresentations.presentationsAtom);
+  const refreshProviders = useAtomCommand(serverEnvironment.refreshProviders, {
+    reportFailure: false,
+  });
+  const [now, setNow] = useState(() => Date.now());
+  const [refreshing, setRefreshing] = useState(false);
+  const [failedLabels, setFailedLabels] = useState<readonly string[]>([]);
+  // Always toggles `refreshing`, even with nothing to probe: Android's
+  // RefreshControl keeps its spinner up until it sees true then false.
+  const refresh = async () => {
+    const connected = [...presentations].filter(
+      ([, presentation]) => presentation.connection.phase === "connected",
+    );
+    setRefreshing(true);
+    try {
+      const results = await Promise.all(
+        connected.map(([environmentId]) => refreshProviders({ environmentId, input: {} })),
+      );
+      setFailedLabels(
+        connected
+          .filter((_, index) => results[index]?._tag === "Failure")
+          .map(([, presentation]) => presentation.entry.target.label),
+      );
+    } finally {
+      setNow(Date.now());
+      setRefreshing(false);
+    }
+  };
+  return { now, refreshing, failedLabels, refresh };
+}
+
 /**
  * Subscription quota windows from every connected environment's providers,
- * read from the config each environment already streams. Countdowns anchor to
- * render time rather than ticking.
+ * read from the config each environment already streams.
  */
-export function UsageLimitsSection() {
+export function UsageLimitsSection(props: {
+  readonly now: number;
+  readonly failedLabels: readonly string[];
+}) {
+  const { now } = props;
   const presentations = useAtomValue(environmentPresentations.presentationsAtom);
   const groups = collectLimitsGroups(presentations);
   const sources = collectLimitSources(presentations);
-  // Anchored once per mount on purpose: countdowns must not tick.
-  const [now] = useState(() => Date.now());
-  if (groups.length === 0 && sources.length === 0) return null;
+
+  if (groups.length === 0 && sources.length === 0) {
+    return (
+      <Text className="py-16 text-center text-base text-foreground-muted">
+        No provider on a connected environment reports subscription limits.
+      </Text>
+    );
+  }
 
   return (
     <>
+      {props.failedLabels.length > 0 ? (
+        <View className="rounded-[16px] border-continuous bg-card px-4 py-3">
+          <Text className="text-sm text-foreground-muted">
+            {props.failedLabels.join(", ")} could not refresh limits. Showing the last known values.
+          </Text>
+        </View>
+      ) : null}
+      {groups.map((group) => (
+        <SettingsSection
+          key={group.environmentId}
+          title={group.environmentLabel ?? "Providers"}
+          card
+        >
+          {group.providers.map((provider, index) => (
+            <ProviderLimits
+              key={provider.instanceId}
+              provider={provider}
+              environmentId={group.environmentId}
+              now={now}
+              first={index === 0}
+            />
+          ))}
+        </SettingsSection>
+      ))}
       {sources.map((source) => (
         <SettingsSection key={source.key} card>
           {source.error ? (
@@ -276,23 +389,6 @@ export function UsageLimitsSection() {
           )}
         </SettingsSection>
       ))}
-      {groups.map((group) => (
-        <SettingsSection
-          key={group.environmentId}
-          title={group.environmentLabel ? `Limits · ${group.environmentLabel}` : "Limits"}
-          card
-        >
-          {group.providers.map((provider, index) => (
-            <ProviderLimits
-              key={provider.instanceId}
-              provider={provider}
-              environmentId={group.environmentId}
-              now={now}
-              first={index === 0}
-            />
-          ))}
-        </SettingsSection>
-      ))}
     </>
   );
 }
diff --git a/apps/mobile/src/features/usage/UsageRouteScreen.tsx b/apps/mobile/src/features/usage/UsageRouteScreen.tsx
index 6e913b4999d8..be7c36173f15 100644
--- a/apps/mobile/src/features/usage/UsageRouteScreen.tsx
+++ b/apps/mobile/src/features/usage/UsageRouteScreen.tsx
@@ -11,32 +11,52 @@ import {
   formatUsd,
   makeWindow,
 } from "@t3tools/shared/usageFormat";
-import { useMemo, useState } from "react";
+import { useMemo, useRef, useState } from "react";
 import { Platform, Pressable, RefreshControl, ScrollView, View } from "react-native";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 
 import { AndroidScreenHeader } from "../../components/AndroidScreenHeader";
 import { AppText as Text } from "../../components/AppText";
+import { cn } from "../../lib/cn";
 import { NativeStackScreenOptions } from "../../native/StackHeader";
 import { useUsage, type EnvironmentUsageStatus } from "../../state/usage";
 import { SettingsSection } from "../settings/components/SettingsSection";
 import { UsageDailyChart } from "./UsageDailyChart";
-import { UsageLimitsSection } from "./UsageLimitsSection";
+import { UsageLimitsSection, useRefreshLimits } from "./UsageLimitsSection";
 import type { UsageChartMetric } from "./usageChartData";
 import { PROVIDER_LABEL, useProviderColors } from "./usageProviders";
 
+type UsageTab = "usage" | "limits";
+const TAB_OPTIONS = [
+  { value: "usage", label: "Usage" },
+  { value: "limits", label: "Limits" },
+] as const satisfies readonly { value: UsageTab; label: string }[];
+
+// Labels are abbreviated to share a row with the metric toggle; screen
+// readers get the full phrase.
 const WINDOW_OPTIONS = [
-  { days: 1, label: "Past 24h" },
-  { days: 7, label: "7 days" },
-  { days: 30, label: "30 days" },
-  { days: 90, label: "90 days" },
+  { value: 1, label: "24h", accessibilityLabel: "Past 24 hours" },
+  { value: 7, label: "7d", accessibilityLabel: "Past 7 days" },
+  { value: 30, label: "30d", accessibilityLabel: "Past 30 days" },
+  { value: 90, label: "90d", accessibilityLabel: "Past 90 days" },
 ] as const;
 
+const METRIC_OPTIONS = [
+  { value: "cost", label: "Cost" },
+  { value: "tokens", label: "Tokens" },
+] as const satisfies readonly { value: UsageChartMetric; label: string }[];
+
 const CHART_HEIGHT = 180;
 
+/**
+ * Two tabs over one screen. Usage is the transcript-derived spend for a
+ * period; Limits is the live subscription quota, which has no period. Both
+ * pull to refresh, each refreshing its own data.
+ */
 export function UsageRouteScreen() {
   const navigation = useNavigation();
   const insets = useSafeAreaInsets();
+  const [tab, setTab] = useState<UsageTab>("usage");
   const [windowSelection, setWindowSelection] = useState(() => ({
     days: 30,
     window: makeWindow(30),
@@ -45,6 +65,7 @@ export function UsageRouteScreen() {
   const { days: windowDays, window } = windowSelection;
   const isPast24Hours = windowDays === 1;
   const { merged, environments, isPending, isPartial, refresh } = useUsage(window);
+  const limits = useRefreshLimits();
 
   const days = useMemo(
     () => enumerateDays(window.sinceDay, window.untilDay),
@@ -73,7 +94,16 @@ export function UsageRouteScreen() {
   // The pull spinner tracks re-scans of environments that have answered
   // before. The initial scan renders its own placeholder, and an unreachable
   // environment stays pending forever — neither may pin the spinner on.
-  const refreshing = environments.some((entry) => entry.isPending && entry.summary !== null);
+  const refreshingUsage = environments.some((entry) => entry.isPending && entry.summary !== null);
+  const showingLimits = tab === "limits";
+  // One ScrollView serves both tabs, so the offset would otherwise carry over
+  // and a short Limits list could open scrolled past its own content.
+  const scrollRef = useRef<ScrollView>(null);
+  const selectTab = (next: UsageTab) => {
+    if (next === tab) return;
+    setTab(next);
+    scrollRef.current?.scrollTo({ y: 0, animated: false });
+  };
   const selectWindow = (days: number) => {
     setWindowSelection({
       days,
@@ -103,46 +133,73 @@ export function UsageRouteScreen() {
         </>
       ) : null}
       <ScrollView
+        ref={scrollRef}
         contentInsetAdjustmentBehavior="automatic"
         showsVerticalScrollIndicator={false}
         className="flex-1"
         contentContainerClassName="gap-6 px-5 pt-4"
         contentContainerStyle={{ paddingBottom: Math.max(insets.bottom, 18) + 18 }}
-        refreshControl={<RefreshControl refreshing={refreshing} onRefresh={refreshWindow} />}
+        refreshControl={
+          <RefreshControl
+            refreshing={showingLimits ? limits.refreshing : refreshingUsage}
+            onRefresh={showingLimits ? () => void limits.refresh() : refreshWindow}
+          />
+        }
       >
-        <SegmentedControl
-          options={WINDOW_OPTIONS.map((option) => ({ value: option.days, label: option.label }))}
-          selected={windowDays}
-          onSelect={selectWindow}
-        />
-
-        <UsageCoverageNotice environments={environments} merged={merged} isPartial={isPartial} />
+        <SegmentedControl options={TAB_OPTIONS} selected={tab} onSelect={selectTab} role="tab" />
 
-        {isPending ? (
-          <Text className="py-16 text-center text-base text-foreground-muted">
-            Scanning provider transcripts…
-          </Text>
-        ) : environments.length === 0 ? (
-          <Text className="py-16 text-center text-base text-foreground-muted">
-            Connect an environment to see usage.
-          </Text>
+        {showingLimits ? (
+          <UsageLimitsSection now={limits.now} failedLabels={limits.failedLabels} />
         ) : (
           <>
-            <ChartCard
+            {/* Period and metric together: neither applies to Limits, and
+                both change every number below, so they share one bar. */}
+            <View className="flex-row items-center gap-3">
+              <SegmentedControl
+                options={WINDOW_OPTIONS}
+                selected={windowDays}
+                onSelect={selectWindow}
+                size="compact"
+                className="flex-1"
+              />
+              <SegmentedControl
+                options={METRIC_OPTIONS}
+                selected={metric}
+                onSelect={setMetric}
+                size="compact"
+                className="w-36"
+              />
+            </View>
+            <UsageCoverageNotice
+              environments={environments}
               merged={merged}
-              days={chartDays}
-              daily={chartTotals}
-              metric={metric}
-              onMetricChange={setMetric}
-              sinceDay={window.sinceDay}
-              untilDay={window.untilDay}
-              isPast24Hours={isPast24Hours}
-              timeZone={window.timeZone}
+              isPartial={isPartial}
             />
-            <ProviderSection merged={merged} metric={metric} />
-            <UsageLimitsSection />
-            <TotalsSection merged={merged} isPast24Hours={isPast24Hours} />
-            <ModelsSection merged={merged} />
+            {isPending ? (
+              <Text className="py-16 text-center text-base text-foreground-muted">
+                Scanning provider transcripts…
+              </Text>
+            ) : environments.length === 0 ? (
+              <Text className="py-16 text-center text-base text-foreground-muted">
+                Connect an environment to see usage.
+              </Text>
+            ) : (
+              <>
+                <ChartCard
+                  merged={merged}
+                  days={chartDays}
+                  daily={chartTotals}
+                  metric={metric}
+                  sinceDay={window.sinceDay}
+                  untilDay={window.untilDay}
+                  isPast24Hours={isPast24Hours}
+                  timeZone={window.timeZone}
+                />
+                <ProviderSection merged={merged} metric={metric} />
+                <TotalsSection merged={merged} isPast24Hours={isPast24Hours} />
+                <ModelsSection merged={merged} />
+              </>
+            )}
           </>
         )}
       </ScrollView>
@@ -151,30 +208,48 @@ export function UsageRouteScreen() {
 }
 
 function SegmentedControl<Value extends number | string>(props: {
-  readonly options: readonly { readonly value: Value; readonly label: string }[];
+  readonly options: readonly {
+    readonly value: Value;
+    readonly label: string;
+    readonly accessibilityLabel?: string;
+  }[];
   readonly selected: Value;
   readonly onSelect: (value: Value) => void;
+  /** The tab bar is full height; filters under it are shorter so it stays primary. */
+  readonly size?: "default" | "compact";
+  /** "tab" for the view switcher; filters stay plain buttons. */
+  readonly role?: "tab" | "button";
+  readonly className?: string;
 }) {
+  const compact = props.size === "compact";
   return (
-    <View className="flex-row overflow-hidden rounded-full border-continuous bg-card">
+    <View
+      accessibilityRole={props.role === "tab" ? "tablist" : undefined}
+      className={cn(
+        "flex-row overflow-hidden rounded-full border-continuous bg-card",
+        props.className,
+      )}
+    >
       {props.options.map((option) => {
         const active = option.value === props.selected;
         return (
           <Pressable
             key={String(option.value)}
-            accessibilityRole="button"
+            accessibilityRole={props.role ?? "button"}
+            accessibilityLabel={option.accessibilityLabel}
             accessibilityState={{ selected: active }}
             onPress={() => props.onSelect(option.value)}
-            className={
-              active
-                ? "flex-1 items-center rounded-full bg-subtle-strong py-2"
-                : "flex-1 items-center py-2"
-            }
+            className={cn(
+              "flex-1 items-center justify-center rounded-full",
+              compact ? "h-9" : "h-11",
+              active && "bg-subtle-strong",
+            )}
           >
             <Text
-              className={
-                active ? "text-sm font-t3-medium text-foreground" : "text-sm text-foreground-muted"
-              }
+              className={cn(
+                compact ? "text-xs" : "text-sm",
+                active ? "font-t3-medium text-foreground" : "text-foreground-muted",
+              )}
             >
               {option.label}
             </Text>
@@ -191,7 +266,6 @@ function ChartCard(props: {
   readonly days: readonly string[];
   readonly daily: readonly DailyTotals[];
   readonly metric: UsageChartMetric;
-  readonly onMetricChange: (metric: UsageChartMetric) => void;
   readonly sinceDay: string;
   readonly untilDay: string;
   readonly isPast24Hours: boolean;
@@ -203,21 +277,18 @@ function ChartCard(props: {
 
   return (
     <View className="gap-4 rounded-[24px] border-continuous bg-card p-4">
-      <View className="flex-row items-start justify-between gap-3">
-        <View className="min-w-0 flex-1 gap-0.5">
-          <Text className="text-sm text-foreground-muted">
-            {metric === "cost" ? "Raw token cost" : "Processed tokens"}
-          </Text>
-          <Text className="text-4xl font-t3-bold tabular-nums text-foreground">
-            {metric === "cost" ? `${formatUsd(merged.costUsd)}*` : formatTokens(merged.totalTokens)}
-          </Text>
-          <Text className="text-sm text-foreground-muted">
-            {metric === "cost"
-              ? "* if billed at full API rate"
-              : `Across ${formatCount(merged.sessions)} sessions`}
-          </Text>
-        </View>
-        <MetricToggle metric={metric} onChange={props.onMetricChange} />
+      <View className="gap-0.5">
+        <Text className="text-sm text-foreground-muted">
+          {metric === "cost" ? "Raw token cost" : "Processed tokens"}
+        </Text>
+        <Text className="text-4xl font-t3-bold tabular-nums text-foreground">
+          {metric === "cost" ? `${formatUsd(merged.costUsd)}*` : formatTokens(merged.totalTokens)}
+        </Text>
+        <Text className="text-sm text-foreground-muted">
+          {metric === "cost"
+            ? "* if billed at full API rate"
+            : `Across ${formatCount(merged.sessions)} sessions`}
+        </Text>
       </View>
 
       {hasActivity ? (
@@ -262,38 +333,6 @@ function ChartCard(props: {
   );
 }
 
-function MetricToggle(props: {
-  readonly metric: UsageChartMetric;
-  readonly onChange: (metric: UsageChartMetric) => void;
-}) {
-  return (
-    <View className="flex-row overflow-hidden rounded-full bg-subtle">
-      {(["cost", "tokens"] as const).map((option) => {
-        const active = option === props.metric;
-        return (
-          <Pressable
-            key={option}
-            accessibilityRole="button"
-            accessibilityState={{ selected: active }}
-            onPress={() => props.onChange(option)}
-            className={active ? "rounded-full bg-subtle-strong px-3 py-1.5" : "px-3 py-1.5"}
-          >
-            <Text
-              className={
-                active
-                  ? "text-xs font-t3-medium uppercase text-foreground"
-                  : "text-xs uppercase text-foreground-muted"
-              }
-            >
-              {option}
-            </Text>
-          </Pressable>
-        );
-      })}
-    </View>
-  );
-}
-
 function ProviderSection(props: {
   readonly merged: MergedUsage;
   readonly metric: UsageChartMetric;
diff --git a/docs/user/usage.md b/docs/user/usage.md
index 8523ab810991..3a61222be82d 100644
--- a/docs/user/usage.md
+++ b/docs/user/usage.md
@@ -18,6 +18,8 @@ update model pricing.
 compares quota consumed with time elapsed in each window, so you can judge your pace before the
 next reset.
 
+If a window looks stale, refresh Limits to re-check every provider and hub.
+
 API-key accounts may not report subscription limits. This also applies to Claude connections
 using a proxy through `ANTHROPIC_AUTH_TOKEN`.
 

From 935917f50a2d9ccdd772464de140c187ca80bb0b Mon Sep 17 00:00:00 2001
From: maria <maria@kuuro.net>
Date: Fri, 4 Sep 2026 17:11:53 -0400
Subject: [PATCH 25/56] fix(web): restore the running tool label shine (#9777)

---
 .../src/components/chat/MessagesTimeline.tsx  |  8 +++++-
 apps/web/src/index.css                        | 28 +++++++++++++++++++
 2 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/apps/web/src/components/chat/MessagesTimeline.tsx b/apps/web/src/components/chat/MessagesTimeline.tsx
index 4e55991f8703..df952aeca382 100644
--- a/apps/web/src/components/chat/MessagesTimeline.tsx
+++ b/apps/web/src/components/chat/MessagesTimeline.tsx
@@ -1918,11 +1918,13 @@ function LiveActivityRow({
   iconName,
   toolIcon,
   failed = false,
+  active = false,
 }: {
   label: string;
   iconName?: WorkEntryIconName;
   toolIcon?: ToolActivityIcon | undefined;
   failed?: boolean;
+  active?: boolean;
 }) {
   return (
     <div className="min-h-6 w-fit max-w-full min-w-0 overflow-hidden rounded-md text-sm leading-relaxed">
@@ -1932,6 +1934,7 @@ function LiveActivityRow({
         toolIcon={toolIcon}
         failed={failed}
         announceFailure={failed}
+        active={active}
       />
     </div>
   );
@@ -1943,12 +1946,14 @@ function LiveActivityContent({
   toolIcon,
   failed = false,
   announceFailure = false,
+  active = false,
 }: {
   label: string;
   iconName: WorkEntryIconName | undefined;
   toolIcon?: ToolActivityIcon | undefined;
   failed?: boolean;
   announceFailure?: boolean;
+  active?: boolean;
 }) {
   const showTrailingFailureMark =
     failed && iconName !== undefined && !toolIconAcceptsTint(iconName, toolIcon);
@@ -1978,7 +1983,7 @@ function LiveActivityContent({
           />
         </span>
       ) : null}
-      <span className="min-w-0 flex-1 truncate">{label}</span>
+      <span className={cn("min-w-0 flex-1 truncate", active && "live-tool-shine")}>{label}</span>
       {showTrailingFailureMark ? (
         <XIcon aria-hidden className={cn("size-3 shrink-0", failedToolIconClassName)} />
       ) : null}
@@ -2004,6 +2009,7 @@ function LiveWorkEntryTimelineRow({ row }: { row: Extract<TimelineRow, { kind: "
         iconName={workEntryIconName(row.entry)}
         toolIcon={row.entry.toolIcon ?? row.entry.toolSource?.icon}
         failed={failed}
+        active={row.active}
       />
     </button>
   );
diff --git a/apps/web/src/index.css b/apps/web/src/index.css
index 54bb5b70d5fa..1369cd31f5b3 100644
--- a/apps/web/src/index.css
+++ b/apps/web/src/index.css
@@ -425,6 +425,34 @@ html[data-mobile-composer-route-transition="true"]::view-transition-old(t3-mobil
   }
 }
 
+@keyframes live-tool-shine {
+  from {
+    background-position:
+      -4.5rem 0,
+      0 0;
+  }
+  to {
+    background-position:
+      calc(100% + 4.5rem) 0,
+      0 0;
+  }
+}
+
+@utility live-tool-shine {
+  @media (prefers-reduced-motion: no-preference) and (forced-colors: none) {
+    color: transparent;
+    background-image:
+      linear-gradient(to right, transparent, var(--contrast-foreground), transparent),
+      linear-gradient(var(--contrast-secondary-label), var(--contrast-secondary-label));
+    background-size:
+      4.5rem 100%,
+      100% 100%;
+    background-repeat: no-repeat;
+    background-clip: text;
+    animation: live-tool-shine 2.2s steps(30) infinite;
+  }
+}
+
 @property --assistant-citation-highlight-opacity {
   syntax: "<number>";
   inherits: true;

From 764946502390845919d974490bc85e87b788c996 Mon Sep 17 00:00:00 2001
From: maria <maria@kuuro.net>
Date: Fri, 4 Sep 2026 17:16:51 -0400
Subject: [PATCH 26/56] fix(web): align provider controls with machine tabs
 (#9769)

---
 .../settings/ProviderSettingsPanel.tsx        | 21 +++++++++----------
 1 file changed, 10 insertions(+), 11 deletions(-)

diff --git a/apps/web/src/components/settings/ProviderSettingsPanel.tsx b/apps/web/src/components/settings/ProviderSettingsPanel.tsx
index bbb6c86de626..1bb1b512e4a2 100644
--- a/apps/web/src/components/settings/ProviderSettingsPanel.tsx
+++ b/apps/web/src/components/settings/ProviderSettingsPanel.tsx
@@ -191,8 +191,10 @@ function ProviderSettingsPlaceholder({
   readonly children?: ReactNode;
 }) {
   return (
-    <SettingsSection {...searchableSetting("providers")} variant="plain">
-      {deviceTabs}
+    <SettingsSection {...searchableSetting("providers")} hideTitle variant="plain">
+      {deviceTabs ? (
+        <div className="flex min-h-11 min-w-0 items-center px-3 sm:px-4">{deviceTabs}</div>
+      ) : null}
       <div
         className={cn(
           providerCardClassName,
@@ -323,7 +325,7 @@ function ProviderSettingsPanelContent(target: ProviderSettingsTarget) {
     options.length === 1 && options[0]?.entry.target._tag === "PrimaryConnectionTarget";
   const deviceTabs =
     !onlyPrimaryDevice && options.length > 0 ? (
-      <ScrollArea hideScrollbars scrollFade className="mx-3 h-11 min-w-0 rounded-none sm:mx-4">
+      <ScrollArea hideScrollbars scrollFade className="h-11 min-w-0 flex-1 rounded-none">
         <div role="group" aria-label="Devices" className="flex h-full w-max min-w-full px-1">
           {options.map((environment) => {
             const machine = resolveEnvironmentMachineKind(environment.serverConfig);
@@ -977,11 +979,10 @@ export function EnvironmentProviderSettings({
 
   return (
     <>
-      <SettingsSection
-        {...searchableSetting("providers")}
-        variant="plain"
-        headerAction={
-          <div className="flex min-w-0 items-center gap-2">
+      <SettingsSection {...searchableSetting("providers")} hideTitle variant="plain">
+        <div className="flex min-h-11 min-w-0 items-center gap-2 px-3 sm:px-4">
+          {deviceTabs}
+          <div className="ml-auto flex min-w-0 shrink-0 items-center gap-2">
             {readOnly ? (
               <span className="min-w-0 truncate text-xs text-muted-foreground">
                 <ProviderLastChecked lastCheckedAt={lastCheckedAt} />
@@ -1030,9 +1031,7 @@ export function EnvironmentProviderSettings({
               </>
             )}
           </div>
-        }
-      >
-        {deviceTabs}
+        </div>
         {readOnly ? (
           <div className={cn(providerCardClassName, "overflow-hidden")}>
             <SettingsRow

From 5e1c23d769b182018f5bd6d3623a7edec13d26bc Mon Sep 17 00:00:00 2001
From: maria <maria@kuuro.net>
Date: Fri, 4 Sep 2026 17:20:14 -0400
Subject: [PATCH 27/56] docs(web): document panel motion during navigation
 (#9778)

Co-authored-by: maria-rcks <254055478+maria-rcks@users.noreply.github.com>
---
 docs/user/appearance.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/user/appearance.md b/docs/user/appearance.md
index 0126c2495b25..0300b8fd9946 100644
--- a/docs/user/appearance.md
+++ b/docs/user/appearance.md
@@ -7,6 +7,13 @@ within each theme. Appearance preferences are saved separately on each device or
 Mobile has its own themes and text, code, and terminal preferences. It does not follow environment
 themes or defaults.
 
+## Motion
+
+The main sidebar, right panel, and terminal drawer open and close immediately by default. Move the
+**Panel animations** slider above 0 ms to add motion, up to 400 ms, unless reduced motion is enabled
+in your operating system. Moving between threads always snaps to the selected thread's panel state
+without replaying its transitions.
+
 ## Custom themes
 
 On web and desktop, choose **Create theme** to adjust a palette, or import a T3 Code or VS Code

From 394e8470c89927a06575e08c434006b2320f1781 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 14:22:21 -0700
Subject: [PATCH 28/56] feat(usage): support custom model prices (#9774)

---
 .../src/environment/ServerEnvironment.test.ts |   1 +
 .../src/environment/ServerEnvironment.ts      |   1 +
 apps/server/src/serverSettings.test.ts        |  26 ++
 apps/server/src/usage/UsageService.test.ts    | 108 +++++-
 apps/server/src/usage/UsageService.ts         |  70 ++--
 apps/server/src/usage/usageAggregation.ts     |   9 +-
 apps/server/src/usage/usagePricing.test.ts    |  76 ++++-
 apps/server/src/usage/usagePricing.ts         |  40 ++-
 .../src/components/usage/UsagePage.test.tsx   |   1 +
 apps/web/src/components/usage/UsagePage.tsx   |   6 +
 .../components/usage/UsagePriceOverrides.tsx  | 318 ++++++++++++++++++
 .../components/usage/usagePriceForm.test.ts   |  73 ++++
 .../src/components/usage/usagePriceForm.ts    |  62 ++++
 docs/user/usage.md                            |  12 +
 packages/client-runtime/src/state/server.ts   |  22 ++
 .../src/state/serverUsage.test.ts             | 263 +++++++++++++++
 packages/contracts/src/environment.ts         |   2 +
 packages/contracts/src/settings.test.ts       |  52 +++
 packages/contracts/src/settings.ts            |  22 ++
 packages/contracts/src/usage.ts               |   2 +-
 packages/shared/src/serverSettings.test.ts    |  22 ++
 packages/shared/src/serverSettings.ts         |  21 +-
 22 files changed, 1165 insertions(+), 44 deletions(-)
 create mode 100644 apps/web/src/components/usage/UsagePriceOverrides.tsx
 create mode 100644 apps/web/src/components/usage/usagePriceForm.test.ts
 create mode 100644 apps/web/src/components/usage/usagePriceForm.ts
 create mode 100644 packages/client-runtime/src/state/serverUsage.test.ts

diff --git a/apps/server/src/environment/ServerEnvironment.test.ts b/apps/server/src/environment/ServerEnvironment.test.ts
index 91895fd5dcfc..141aa405af21 100644
--- a/apps/server/src/environment/ServerEnvironment.test.ts
+++ b/apps/server/src/environment/ServerEnvironment.test.ts
@@ -166,6 +166,7 @@ it.layer(NodeServices.layer)("ServerEnvironmentLive", (it) => {
       expect(second.capabilities.attachmentUploads).toBe(true);
       expect(second.capabilities.fileAttachments).toEqual({ maxUploadBytes: 50 * 1024 * 1024 });
       expect(second.capabilities.pullRequests).toBe(true);
+      expect(second.capabilities.usagePriceOverrides).toBe(true);
       expect(second.capabilities.threadTitleRegeneration).toBe(true);
       expect(second.capabilities.threadPullRequestLinking).toBe(true);
       expect(second.capabilities.agentActivityPublishing).toBe(false);
diff --git a/apps/server/src/environment/ServerEnvironment.ts b/apps/server/src/environment/ServerEnvironment.ts
index d050bde88565..cfecfc00c86d 100644
--- a/apps/server/src/environment/ServerEnvironment.ts
+++ b/apps/server/src/environment/ServerEnvironment.ts
@@ -222,6 +222,7 @@ export const make = Effect.gen(function* () {
       threadSnooze: true,
       environmentThemes: true,
       usageLimitSources: true,
+      usagePriceOverrides: true,
       threadPinning: true,
       threadPinReorder: true,
       threadTitleRegeneration: true,
diff --git a/apps/server/src/serverSettings.test.ts b/apps/server/src/serverSettings.test.ts
index 82ed8525b9b5..4526e2c988a4 100644
--- a/apps/server/src/serverSettings.test.ts
+++ b/apps/server/src/serverSettings.test.ts
@@ -272,6 +272,32 @@ it.layer(NodeServices.layer)("server settings", (it) => {
     ).pipe(Effect.provide(makeServerSettingsLayer())),
   );
 
+  it.effect("persists custom usage prices and removes them from the settings file", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const serverConfig = yield* ServerConfig.ServerConfig;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const serverSettings = yield* ServerSettingsModule.ServerSettingsService;
+        const prices = {
+          inputCostPerMillionTokens: 2,
+          outputCostPerMillionTokens: 8,
+          cacheReadCostPerMillionTokens: 0,
+        };
+        const readPersisted = fileSystem
+          .readFileString(serverConfig.settingsPath)
+          .pipe(Effect.flatMap(Schema.decodeUnknownEffect(Schema.fromJsonString(ServerSettings))));
+
+        yield* serverSettings.updateSettings({ usagePriceOverrides: { "example-model": prices } });
+        const persisted = yield* readPersisted;
+        assert.deepStrictEqual(persisted.usagePriceOverrides, { "example-model": prices });
+
+        yield* serverSettings.updateSettings({ usagePriceOverrides: { "example-model": null } });
+        const restored = yield* readPersisted;
+        assert.deepStrictEqual(restored.usagePriceOverrides, {});
+      }),
+    ).pipe(Effect.provide(makeServerSettingsLayer())),
+  );
+
   it.effect("persists and broadcasts thread settlement settings", () =>
     Effect.scoped(
       Effect.gen(function* () {
diff --git a/apps/server/src/usage/UsageService.test.ts b/apps/server/src/usage/UsageService.test.ts
index 63b74510e29e..9d728c88cf42 100644
--- a/apps/server/src/usage/UsageService.test.ts
+++ b/apps/server/src/usage/UsageService.test.ts
@@ -9,9 +9,11 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 import { HostProcessEnvironment } from "@t3tools/shared/hostProcess";
 import { UsageDay, type UsageSummaryInput } from "@t3tools/contracts";
 import * as Duration from "effect/Duration";
+import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
 import * as Fiber from "effect/Fiber";
+import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
 import * as Scheduler from "effect/Scheduler";
 import * as TestClock from "effect/testing/TestClock";
@@ -21,7 +23,7 @@ import * as ServerConfig from "../config.ts";
 import * as ServerSettings from "../serverSettings.ts";
 import * as UsageService from "./UsageService.ts";
 
-function claudeLine(id: number, outputTokens: number): string {
+function claudeLine(id: number, outputTokens: number, model = "claude-fable-5"): string {
   return `${JSON.stringify({
     type: "assistant",
     timestamp: "2026-08-01T10:00:00Z",
@@ -29,7 +31,7 @@ function claudeLine(id: number, outputTokens: number): string {
     sessionId: "session-1",
     message: {
       id: `msg_${id}`,
-      model: "claude-fable-5",
+      model,
       usage: { input_tokens: 10, output_tokens: outputTokens },
     },
   })}\n`;
@@ -96,6 +98,49 @@ function totalOutputTokens(summary: { buckets: readonly { totals: { outputTokens
 }
 
 describe("UsageService", () => {
+  it.live("reprices unchanged transcripts when custom prices are added, edited, or removed", () =>
+    Effect.gen(function* () {
+      const { transcript, settings, home } = yield* setup;
+      yield* Effect.promise(() => NodeFSP.writeFile(transcript, claudeLine(1, 5, "example-model")));
+
+      yield* Effect.gen(function* () {
+        const settingsService = yield* ServerSettings.ServerSettingsService;
+        const service = yield* UsageService.make;
+
+        const original = yield* service.readSummary(WINDOW);
+        assert.strictEqual(original.buckets[0]?.costUsd, 0);
+        assert.strictEqual(original.buckets[0]?.unpricedRecords, 1);
+
+        yield* settingsService.updateSettings({
+          usagePriceOverrides: {
+            "example-model": { inputCostPerMillionTokens: 2, outputCostPerMillionTokens: 8 },
+          },
+        });
+        const overridden = yield* service.readSummary(WINDOW);
+        assert.closeTo(overridden.buckets[0]?.costUsd ?? -1, 0.00006, 1e-12);
+        assert.strictEqual(overridden.buckets[0]?.costSource, "modelPriced");
+        assert.strictEqual(overridden.buckets[0]?.unpricedRecords, 0);
+        assert.deepStrictEqual(overridden.buckets[0]?.totals, original.buckets[0]?.totals);
+
+        yield* settingsService.updateSettings({
+          usagePriceOverrides: {
+            "example-model": { inputCostPerMillionTokens: 4, outputCostPerMillionTokens: 16 },
+          },
+        });
+        const edited = yield* service.readSummary(WINDOW);
+        assert.closeTo(edited.buckets[0]?.costUsd ?? -1, 0.00012, 1e-12);
+
+        yield* settingsService.updateSettings({ usagePriceOverrides: { "example-model": null } });
+        const restored = yield* service.readSummary(WINDOW);
+        assert.deepStrictEqual(restored.buckets, original.buckets);
+      }).pipe(
+        Effect.provide(
+          serviceLayers({ prefix: "usage-service-price-overrides-test", home, settings }),
+        ),
+      );
+    }).pipe(Effect.scoped),
+  );
+
   it.live("counts appended usage on a rescan of a grown transcript", () =>
     Effect.gen(function* () {
       const { transcript, settings, home } = yield* setup;
@@ -114,6 +159,65 @@ describe("UsageService", () => {
     }).pipe(Effect.scoped),
   );
 
+  it.live("does not share an in-flight scan after custom prices change", () =>
+    Effect.gen(function* () {
+      const { transcript, settings, home } = yield* setup;
+      yield* Effect.promise(() => NodeFSP.writeFile(transcript, claudeLine(1, 5, "example-model")));
+
+      yield* Effect.gen(function* () {
+        const settingsService = yield* ServerSettings.ServerSettingsService;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const firstScanStarted = yield* Deferred.make<void>();
+        const secondScanStarted = yield* Deferred.make<void>();
+        const releaseRates = yield* Deferred.make<void>();
+        let homeProbes = 0;
+        const service = yield* UsageService.make.pipe(
+          Effect.provideService(FileSystem.FileSystem, {
+            ...fileSystem,
+            exists: (path) =>
+              fileSystem.exists(path).pipe(
+                Effect.tap(() => {
+                  if (path !== NodePath.join(home, "claude", ".claude", "projects"))
+                    return Effect.void;
+                  homeProbes += 1;
+                  return Deferred.succeed(
+                    homeProbes === 1 ? firstScanStarted : secondScanStarted,
+                    undefined,
+                  );
+                }),
+              ),
+          }),
+          Effect.provideService(
+            HttpClient.HttpClient,
+            HttpClient.make((request) =>
+              Deferred.await(releaseRates).pipe(
+                Effect.as(HttpClientResponse.fromWeb(request, Response.json({}))),
+              ),
+            ),
+          ),
+        );
+
+        const first = yield* service.readSummary(WINDOW).pipe(Effect.forkChild);
+        yield* Deferred.await(firstScanStarted);
+        yield* settingsService.updateSettings({
+          usagePriceOverrides: {
+            "example-model": { inputCostPerMillionTokens: 2, outputCostPerMillionTokens: 8 },
+          },
+        });
+        const second = yield* service.readSummary(WINDOW).pipe(Effect.forkChild);
+        yield* Deferred.await(secondScanStarted);
+        yield* Deferred.succeed(releaseRates, undefined);
+
+        const original = yield* Fiber.join(first);
+        const updated = yield* Fiber.join(second);
+        assert.strictEqual(original.buckets[0]?.costUsd, 0);
+        assert.closeTo(updated.buckets[0]?.costUsd ?? -1, 0.00006, 1e-12);
+      }).pipe(
+        Effect.provide(serviceLayers({ prefix: "usage-service-price-race-test", home, settings })),
+      );
+    }).pipe(Effect.scoped),
+  );
+
   it.live("shares one scan between concurrent identical requests", () =>
     Effect.gen(function* () {
       const { transcript, settings, home } = yield* setup;
diff --git a/apps/server/src/usage/UsageService.ts b/apps/server/src/usage/UsageService.ts
index 7c446ae14f96..0e6b0c1eecd6 100644
--- a/apps/server/src/usage/UsageService.ts
+++ b/apps/server/src/usage/UsageService.ts
@@ -16,6 +16,7 @@ import * as NodeOS from "node:os";
 
 import {
   USAGE_CONTRACT_VERSION,
+  type ServerSettings as ServerSettingsValue,
   type UsageProviderKind,
   type UsageSource,
   type UsagePricing,
@@ -44,7 +45,7 @@ import * as ServerSettings from "../serverSettings.ts";
 import { resolveClaudeHomePath } from "../provider/Drivers/ClaudeHome.ts";
 import { resolveCodexHomeLayout } from "../provider/Drivers/CodexHomeLayout.ts";
 import { UsageAggregator } from "./usageAggregation.ts";
-import { parseRateTable, type RateTable } from "./usagePricing.ts";
+import { createOverrideRateTable, parseRateTable, type RateTable } from "./usagePricing.ts";
 import {
   listTranscriptFiles,
   readDirectoryVolumeId,
@@ -232,24 +233,22 @@ export const make = Effect.gen(function* () {
       return nestedExists ? nested : path.join(homePath, "projects");
     });
 
-  /** Resolves the transcript directory for each provider. */
-  const resolveTranscriptDirs = Effect.fn("UsageService.resolveTranscriptDirs")(function* () {
-    // A settings failure must surface as an error: swallowing it here would
-    // present "zero usage from every provider" as a valid answer.
-    const settings = yield* settingsService.getSettings.pipe(
-      Effect.catchCause(
-        (cause) =>
-          new UsageReadError({
-            reason: "scanFailed",
-            // Bounded description; the squashed failure travels as the cause.
-            // Squashed, not the Cause tree: a full tree in a Defect field is
-            // the unbounded wire payload the bounded detail exists to avoid.
-            detail: "Server settings could not be read.",
-            cause: Cause.squash(cause),
-          }),
-      ),
-    );
+  // A settings failure must not silently discard custom rates or transcript homes.
+  const readSettings = settingsService.getSettings.pipe(
+    Effect.catchCause(
+      (cause) =>
+        new UsageReadError({
+          reason: "scanFailed",
+          detail: "Server settings could not be read.",
+          cause: Cause.squash(cause),
+        }),
+    ),
+  );
 
+  /** Resolves the transcript directory for each provider. */
+  const resolveTranscriptDirs = Effect.fn("UsageService.resolveTranscriptDirs")(function* (
+    settings: ServerSettingsValue,
+  ) {
     const claudeHome = yield* resolveClaudeHomePath(settings.providers.claudeAgent);
     const claudeDir = yield* resolveClaudeTranscriptDir(claudeHome);
     const codexLayout = yield* resolveCodexHomeLayout(settings.providers.codex);
@@ -379,10 +378,15 @@ export const make = Effect.gen(function* () {
       | null;
   }
 
-  const collectDirs = Effect.fn("UsageService.collectDirs")(function* (windowStartMs: number) {
+  const collectDirs = Effect.fn("UsageService.collectDirs")(function* (
+    windowStartMs: number,
+    settings: ServerSettingsValue,
+  ) {
     // The home resolvers ask for `Path` themselves; satisfy them from the
     // instance we already hold so the scan stays context-free.
-    const dirs = yield* resolveTranscriptDirs().pipe(Effect.provideService(Path.Path, path));
+    const dirs = yield* resolveTranscriptDirs(settings).pipe(
+      Effect.provideService(Path.Path, path),
+    );
     const scanned: ScannedDir[] = [];
     for (const { provider, dir, fileName } of dirs) {
       const volumeId = yield* Effect.promise(() => readDirectoryVolumeId(dir));
@@ -406,7 +410,10 @@ export const make = Effect.gen(function* () {
     return scanned;
   });
 
-  const scanSummary = Effect.fn("UsageService.scanSummary")(function* (input: UsageSummaryInput) {
+  const scanSummary = Effect.fn("UsageService.scanSummary")(function* (
+    input: UsageSummaryInput,
+    settings: ServerSettingsValue,
+  ) {
     if (input.sinceDay > input.untilDay) {
       return yield* new UsageReadError({
         reason: "invalidWindow",
@@ -455,9 +462,10 @@ export const make = Effect.gen(function* () {
     // Pricing only matters once records are aggregated, so the rate table
     // loads while transcripts stream instead of gating them: a cold rates
     // fetch on a slow network no longer delays the scan by its own timeout.
-    const [, scannedDirs] = yield* Effect.all([ensureRates(false), collectDirs(windowStartMs)], {
-      concurrency: 2,
-    });
+    const [, scannedDirs] = yield* Effect.all(
+      [ensureRates(false), collectDirs(windowStartMs, settings)],
+      { concurrency: 2 },
+    );
 
     const aggregator = new UsageAggregator({
       timeZone: input.timeZone,
@@ -466,6 +474,7 @@ export const make = Effect.gen(function* () {
       resolution: input.resolution ?? "day",
       ...hourlyWindow,
       rates,
+      priceOverrides: createOverrideRateTable(settings.usagePriceOverrides),
     });
 
     const sources: UsageSource[] = [];
@@ -547,13 +556,16 @@ export const make = Effect.gen(function* () {
   });
 
   /**
-   * In-flight scans by window, so concurrent identical requests (the usage
+   * In-flight scans by window and custom prices, so concurrent identical requests (the usage
    * page open on two clients at once) share one scan instead of racing over
    * the same corpus twice.
    */
   const inflightScans = new Map<string, Deferred.Deferred<UsageSummary, UsageReadError>>();
 
-  const scanKey = (input: UsageSummaryInput): string =>
+  const scanKey = (
+    input: UsageSummaryInput,
+    priceOverrides: ServerSettingsValue["usagePriceOverrides"],
+  ): string =>
     JSON.stringify([
       input.timeZone,
       input.sinceDay,
@@ -561,10 +573,12 @@ export const make = Effect.gen(function* () {
       input.resolution ?? "day",
       input.sinceTime ?? null,
       input.untilTime ?? null,
+      priceOverrides,
     ]);
 
   const readSummary = Effect.fn("UsageService.readSummary")(function* (input: UsageSummaryInput) {
-    const key = scanKey(input);
+    const settings = yield* readSettings;
+    const key = scanKey(input, settings.usagePriceOverrides);
     const deferred = yield* Effect.uninterruptible(
       Effect.gen(function* () {
         const existing = inflightScans.get(key);
@@ -576,7 +590,7 @@ export const make = Effect.gen(function* () {
         inflightScans.set(key, created);
         // Detached so one departing client cannot tear the scan out from under
         // the fibers awaiting it; a finished scan warms the cache either way.
-        yield* scanSummary(input).pipe(
+        yield* scanSummary(input, settings).pipe(
           Effect.onExit((exit) =>
             Effect.sync(() => inflightScans.delete(key)).pipe(
               Effect.andThen(Deferred.done(created, exit)),
diff --git a/apps/server/src/usage/usageAggregation.ts b/apps/server/src/usage/usageAggregation.ts
index e100be76e979..01a1195efb60 100644
--- a/apps/server/src/usage/usageAggregation.ts
+++ b/apps/server/src/usage/usageAggregation.ts
@@ -61,6 +61,7 @@ export interface AggregateOptions {
   readonly sinceDay: string;
   readonly untilDay: string;
   readonly rates: RateTable;
+  readonly priceOverrides?: RateTable;
   readonly resolution?: UsageResolution;
   readonly sinceTimeMs?: number;
   readonly untilTimeMs?: number;
@@ -165,11 +166,17 @@ export class UsageAggregator {
       record.model,
       record.totals,
       record.reportedCostUsd,
+      this.#options.priceOverrides,
     );
 
     bucket.totals = addTotals(bucket.totals, record.totals);
     bucket.costUsd += priced.costUsd;
-    bucket.cacheSavingsUsd += cacheSavingsUsd(this.#options.rates, record.model, record.totals);
+    bucket.cacheSavingsUsd += cacheSavingsUsd(
+      this.#options.rates,
+      record.model,
+      record.totals,
+      this.#options.priceOverrides,
+    );
     bucket.records += 1;
     if (priced.costSource === "unpriced") bucket.unpricedRecords += 1;
     if (priced.costSource === "providerReported") bucket.providerReportedRecords += 1;
diff --git a/apps/server/src/usage/usagePricing.test.ts b/apps/server/src/usage/usagePricing.test.ts
index 45113414f69c..d45dfe2dd09b 100644
--- a/apps/server/src/usage/usagePricing.test.ts
+++ b/apps/server/src/usage/usagePricing.test.ts
@@ -1,6 +1,13 @@
 import { describe, expect, it } from "@effect/vitest";
 
-import { lookupRate, normalizeModelName, parseRateTable } from "./usagePricing.ts";
+import {
+  cacheSavingsUsd,
+  createOverrideRateTable,
+  lookupRate,
+  normalizeModelName,
+  parseRateTable,
+  priceUsage,
+} from "./usagePricing.ts";
 
 const rate = (input: number, cacheRead?: number) => ({
   input_cost_per_token: input,
@@ -9,6 +16,73 @@ const rate = (input: number, cacheRead?: number) => ({
 });
 
 describe("usage pricing", () => {
+  const totals = {
+    uncachedInputTokens: 1_000_000,
+    cachedInputTokens: 1_000_000,
+    cacheCreationTokens: 1_000_000,
+    outputTokens: 1_000_000,
+    reasoningTokens: 500_000,
+  };
+
+  it("uses custom token rates ahead of public and provider-reported costs", () => {
+    const table = parseRateTable({ "example-model": rate(1) });
+    const overrides = createOverrideRateTable({
+      "example-model": {
+        inputCostPerMillionTokens: 2,
+        outputCostPerMillionTokens: 8,
+        cacheReadCostPerMillionTokens: 0.5,
+        cacheWriteCostPerMillionTokens: 3,
+      },
+    });
+
+    for (const reportedCostUsd of [null, 99]) {
+      expect(priceUsage(table, "example-model", totals, reportedCostUsd, overrides)).toEqual({
+        costUsd: 13.5,
+        costSource: "modelPriced",
+      });
+    }
+    expect(cacheSavingsUsd(table, "example-model", totals, overrides)).toBe(1.5);
+  });
+
+  it("prices unknown models offline and uses input prices for omitted cache rates", () => {
+    const table = parseRateTable({});
+    const overrides = createOverrideRateTable({
+      "example-model": { inputCostPerMillionTokens: 2, outputCostPerMillionTokens: 8 },
+    });
+
+    expect(priceUsage(table, "example-model", totals, null, overrides)).toEqual({
+      costUsd: 14,
+      costSource: "modelPriced",
+    });
+    expect(cacheSavingsUsd(table, "example-model", totals, overrides)).toBe(0);
+  });
+
+  it("preserves explicit zero rates and matches only the exact trimmed model ID", () => {
+    const table = parseRateTable({});
+    const overrides = createOverrideRateTable({
+      " vendor/example-model[1m] ": {
+        inputCostPerMillionTokens: 0,
+        outputCostPerMillionTokens: 0,
+      },
+    });
+    expect(priceUsage(table, " vendor/example-model[1m] ", totals, 99, overrides)).toEqual({
+      costUsd: 0,
+      costSource: "modelPriced",
+    });
+    for (const model of [
+      "example-model[1m]",
+      "vendor/example-model",
+      "vendor/Example-model[1m]",
+      "other/example-model[1m]",
+    ]) {
+      expect(priceUsage(table, model, totals, null, overrides).costSource).toBe("unpriced");
+      expect(priceUsage(table, model, totals, 99, overrides)).toEqual({
+        costUsd: 99,
+        costSource: "providerReported",
+      });
+    }
+  });
+
   it("keeps the existing model-name normalization contract", () => {
     expect(normalizeModelName(" Anthropic/Claude-Opus-5 ")).toBe("claude-opus-5");
   });
diff --git a/apps/server/src/usage/usagePricing.ts b/apps/server/src/usage/usagePricing.ts
index a7beecb1f552..5ca75a68cb32 100644
--- a/apps/server/src/usage/usagePricing.ts
+++ b/apps/server/src/usage/usagePricing.ts
@@ -7,7 +7,11 @@
  *
  * @module usagePricing
  */
-import type { UsageCostSource, UsageTokenTotals } from "@t3tools/contracts";
+import type {
+  UsageCostSource,
+  UsageModelPriceOverride,
+  UsageTokenTotals,
+} from "@t3tools/contracts";
 
 /**
  * The subset of a LiteLLM entry we price against. All values are USD per token.
@@ -26,6 +30,25 @@ export interface ModelRate {
 
 export type RateTable = ReadonlyMap<string, ModelRate>;
 
+/** Custom IDs keep their case, provider prefix, and variant suffix. */
+export function createOverrideRateTable(
+  overrides: Readonly<Record<string, UsageModelPriceOverride>>,
+): RateTable {
+  return new Map(
+    Object.entries(overrides).map(([model, prices]) => [
+      model.trim(),
+      {
+        inputCostPerToken: prices.inputCostPerMillionTokens / 1_000_000,
+        outputCostPerToken: prices.outputCostPerMillionTokens / 1_000_000,
+        cacheReadCostPerToken:
+          (prices.cacheReadCostPerMillionTokens ?? prices.inputCostPerMillionTokens) / 1_000_000,
+        cacheCreationCostPerToken:
+          (prices.cacheWriteCostPerMillionTokens ?? prices.inputCostPerMillionTokens) / 1_000_000,
+      },
+    ]),
+  );
+}
+
 /** Raw shape of one LiteLLM entry, narrowed to the fields we read. */
 interface LiteLlmEntry {
   readonly input_cost_per_token?: unknown;
@@ -168,12 +191,14 @@ export function priceUsage(
   model: string,
   totals: UsageTokenTotals,
   reportedCostUsd: number | null,
+  overrides?: RateTable,
 ): PricedUsage {
-  if (reportedCostUsd !== null && Number.isFinite(reportedCostUsd)) {
+  const override = overrides?.get(model.trim());
+  if (override === undefined && reportedCostUsd !== null && Number.isFinite(reportedCostUsd)) {
     return { costUsd: reportedCostUsd, costSource: "providerReported" };
   }
 
-  const rate = lookupRate(table, model);
+  const rate = override ?? lookupRate(table, model);
   if (rate === null) return { costUsd: 0, costSource: "unpriced" };
 
   const costUsd =
@@ -189,8 +214,13 @@ export function priceUsage(
  * What the cached input would have cost at full input rates, minus what it
  * actually cost. Drives the "cache savings" figure.
  */
-export function cacheSavingsUsd(table: RateTable, model: string, totals: UsageTokenTotals): number {
-  const rate = lookupRate(table, model);
+export function cacheSavingsUsd(
+  table: RateTable,
+  model: string,
+  totals: UsageTokenTotals,
+  overrides?: RateTable,
+): number {
+  const rate = overrides?.get(model.trim()) ?? lookupRate(table, model);
   if (rate === null) return 0;
   return totals.cachedInputTokens * (rate.inputCostPerToken - rate.cacheReadCostPerToken);
 }
diff --git a/apps/web/src/components/usage/UsagePage.test.tsx b/apps/web/src/components/usage/UsagePage.test.tsx
index 8e86b521e890..56bd17073426 100644
--- a/apps/web/src/components/usage/UsagePage.test.tsx
+++ b/apps/web/src/components/usage/UsagePage.test.tsx
@@ -57,6 +57,7 @@ vi.mock("../WorkspaceBreadcrumb", () => ({
 vi.mock("../WorkspacePageContainer", () => ({ WorkspacePageContainer: "main" }));
 vi.mock("../WorkspacePageHeader", () => ({ WorkspacePageHeader: "header" }));
 vi.mock("./UsageProviderChart", () => ({ UsageProviderChart: "div" }));
+vi.mock("./UsagePriceOverrides", () => ({ UsagePriceOverrides: () => null }));
 vi.mock("./usageProviders", async (importOriginal) => {
   const actual = await importOriginal<typeof import("./usageProviders")>();
   return {
diff --git a/apps/web/src/components/usage/UsagePage.tsx b/apps/web/src/components/usage/UsagePage.tsx
index 4b62df374122..a96e4ac37410 100644
--- a/apps/web/src/components/usage/UsagePage.tsx
+++ b/apps/web/src/components/usage/UsagePage.tsx
@@ -36,6 +36,7 @@ import {
 import { WorkspacePageContainer } from "../WorkspacePageContainer";
 import { WorkspacePageHeader } from "../WorkspacePageHeader";
 import { UsageLimitsSection } from "./UsageLimits";
+import { UsagePriceOverrides } from "./UsagePriceOverrides";
 import { UsageProviderChart, type UsageChartMetric } from "./UsageProviderChart";
 import { PROVIDER_ORDER, PROVIDER_PRESENTATION, providersWithUsage } from "./usageProviders";
 
@@ -264,6 +265,11 @@ export function UsagePage() {
 
         <ScrollArea className="min-h-0 flex-1">
           <WorkspacePageContainer width="wide">
+            {!showingLimits ? (
+              <div className="flex justify-end">
+                <UsagePriceOverrides usage={environments} />
+              </div>
+            ) : null}
             {showingLimits ? (
               <UsageLimitsSection />
             ) : settling ? (
diff --git a/apps/web/src/components/usage/UsagePriceOverrides.tsx b/apps/web/src/components/usage/UsagePriceOverrides.tsx
new file mode 100644
index 000000000000..faa161f95329
--- /dev/null
+++ b/apps/web/src/components/usage/UsagePriceOverrides.tsx
@@ -0,0 +1,318 @@
+import { useAtomValue } from "@effect/atom-react";
+import type { EnvironmentId, UsageModelPriceOverride } from "@t3tools/contracts";
+import { useState } from "react";
+
+import { isElectron } from "../../env";
+import {
+  type EnvironmentPresentation,
+  useEnvironments,
+  usePrimaryEnvironmentId,
+} from "../../state/environments";
+import { serverEnvironment } from "../../state/server";
+import { useEnvironmentSessionState } from "../../state/session";
+import { useAtomCommand } from "../../state/use-atom-command";
+import type { EnvironmentUsageStatus } from "../../state/usage";
+import {
+  resolvePrimaryOperateAccess,
+  resolveRemoteOperateAccess,
+} from "../settings/ProviderSettingsPanel.logic";
+import { Button } from "../ui/button";
+import {
+  Dialog,
+  DialogDescription,
+  DialogHeader,
+  DialogPanel,
+  DialogPopup,
+  DialogTitle,
+} from "../ui/dialog";
+import { Input } from "../ui/input";
+import { Label } from "../ui/label";
+import { Select, SelectItem, SelectPopup, SelectTrigger, SelectValue } from "../ui/select";
+import { parseUsagePriceForm, USAGE_PRICE_FIELDS, usagePriceForm } from "./usagePriceForm";
+
+export function UsagePriceOverrides({
+  usage,
+}: {
+  readonly usage: readonly EnvironmentUsageStatus[];
+}) {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button variant="outline" size="sm" onClick={() => setOpen(true)}>
+        Model prices
+      </Button>
+      {open ? <ModelPricesDialog usage={usage} onOpenChange={setOpen} /> : null}
+    </>
+  );
+}
+
+function ModelPricesDialog({
+  usage,
+  onOpenChange,
+}: {
+  readonly usage: readonly EnvironmentUsageStatus[];
+  readonly onOpenChange: (open: boolean) => void;
+}) {
+  const { environments } = useEnvironments();
+  const primaryEnvironmentId = usePrimaryEnvironmentId();
+  const [selectedId, setSelectedId] = useState<EnvironmentId | null>(primaryEnvironmentId);
+  const environment =
+    environments.find((entry) => entry.environmentId === selectedId) ?? environments[0];
+  const summary = usage.find(
+    (entry) => entry.environmentId === environment?.environmentId,
+  )?.summary;
+  const models = [...new Set(summary?.buckets.map((bucket) => bucket.model) ?? [])].sort();
+
+  return (
+    <Dialog open onOpenChange={onOpenChange}>
+      <DialogPopup className="max-w-xl">
+        <DialogHeader>
+          <DialogTitle>Model prices</DialogTitle>
+          <DialogDescription>
+            Override estimated costs using USD per million tokens. Prices apply to all saved history
+            on the selected environment.
+          </DialogDescription>
+        </DialogHeader>
+        <DialogPanel className="grid gap-5 pb-6">
+          {environment ? (
+            <>
+              <div className="grid gap-1.5">
+                <Label htmlFor="usage-prices-environment">Environment</Label>
+                <Select
+                  value={environment.environmentId}
+                  onValueChange={(value) => {
+                    const next = environments.find((entry) => entry.environmentId === value);
+                    if (next) setSelectedId(next.environmentId);
+                  }}
+                >
+                  <SelectTrigger id="usage-prices-environment">
+                    <SelectValue>{environment.label}</SelectValue>
+                  </SelectTrigger>
+                  <SelectPopup>
+                    {environments.map((entry) => (
+                      <SelectItem key={entry.environmentId} value={entry.environmentId}>
+                        {entry.label}
+                      </SelectItem>
+                    ))}
+                  </SelectPopup>
+                </Select>
+              </div>
+              <EnvironmentModelPrices
+                key={environment.environmentId}
+                environment={environment}
+                models={models}
+              />
+            </>
+          ) : (
+            <p className="text-sm text-muted-foreground">
+              Connect an environment to set model prices.
+            </p>
+          )}
+        </DialogPanel>
+      </DialogPopup>
+    </Dialog>
+  );
+}
+
+function EnvironmentModelPrices({
+  environment,
+  models,
+}: {
+  readonly environment: EnvironmentPresentation;
+  readonly models: readonly string[];
+}) {
+  const settings = useAtomValue(serverEnvironment.settingsValueAtom(environment.environmentId));
+  const session = useEnvironmentSessionState(environment.environmentId);
+  const updateSettings = useAtomCommand(serverEnvironment.updateSettings, { reportFailure: false });
+  const [form, setForm] = useState(usagePriceForm());
+  const [editingModel, setEditingModel] = useState<string | null>(null);
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const prices = settings?.usagePriceOverrides ?? {};
+  const isPrimary = environment.entry.target._tag === "PrimaryConnectionTarget";
+  const access = isPrimary
+    ? resolvePrimaryOperateAccess({
+        isPrimary,
+        hasDesktopBridge: isElectron,
+        session: session.data,
+        isPending: session.isPending,
+        hasError: session.hasError,
+      })
+    : resolveRemoteOperateAccess({
+        session: session.data,
+        isPending: session.isPending,
+        hasError: session.hasError,
+      });
+  const supportsOverrides =
+    environment.serverConfig?.environment.capabilities.usagePriceOverrides === true;
+  const unavailable =
+    environment.connection.phase !== "connected"
+      ? "Connect this environment to change its model prices."
+      : settings === null
+        ? "Loading model prices..."
+        : !supportsOverrides
+          ? "Update this environment's server to set model prices."
+          : access === "pending"
+            ? "Checking permissions..."
+            : access === "denied"
+              ? "This session can view model prices but cannot change them."
+              : null;
+  const readOnly = unavailable !== null || pending;
+  const parsed = parseUsagePriceForm(form);
+  const duplicate = editingModel === null && parsed !== null && Object.hasOwn(prices, parsed.model);
+
+  const reset = () => {
+    setEditingModel(null);
+    setForm(usagePriceForm());
+    setError(null);
+  };
+  const save = async (model: string, price: UsageModelPriceOverride | null) => {
+    if (readOnly) return;
+    setPending(true);
+    setError(null);
+    try {
+      const result = await updateSettings({
+        environmentId: environment.environmentId,
+        input: { patch: { usagePriceOverrides: { [model]: price } } },
+      });
+      if (result._tag === "Failure") {
+        setError("Could not save model prices. Try again.");
+      } else if (price !== null || editingModel === model) {
+        reset();
+      }
+    } finally {
+      setPending(false);
+    }
+  };
+
+  return (
+    <>
+      {Object.keys(prices).length > 0 ? (
+        <ul className="divide-y divide-border rounded-lg border border-border">
+          {Object.entries(prices)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([model, price]) => (
+              <li key={model} className="flex flex-wrap items-center gap-3 p-3">
+                <div className="min-w-0 flex-1">
+                  <p className="break-all text-sm font-medium">{model}</p>
+                  <p className="text-xs text-muted-foreground">
+                    Input ${price.inputCostPerMillionTokens} · Output $
+                    {price.outputCostPerMillionTokens}
+                    <br />
+                    Cache read $
+                    {price.cacheReadCostPerMillionTokens ?? price.inputCostPerMillionTokens}
+                    {" · "}Cache write $
+                    {price.cacheWriteCostPerMillionTokens ?? price.inputCostPerMillionTokens}
+                  </p>
+                </div>
+                <Button
+                  variant="ghost"
+                  size="xs"
+                  disabled={readOnly}
+                  aria-label={`Edit price for ${model}`}
+                  onClick={() => {
+                    setEditingModel(model);
+                    setForm(usagePriceForm(model, price));
+                    setError(null);
+                  }}
+                >
+                  Edit
+                </Button>
+                <Button
+                  variant="ghost"
+                  size="xs"
+                  disabled={readOnly}
+                  aria-label={`Remove price for ${model}`}
+                  onClick={() => void save(model, null)}
+                >
+                  Remove
+                </Button>
+              </li>
+            ))}
+        </ul>
+      ) : (
+        <p className="text-sm text-muted-foreground">
+          No custom prices. Public model pricing is used when available.
+        </p>
+      )}
+      {unavailable ? <p className="text-sm text-muted-foreground">{unavailable}</p> : null}
+      <form
+        className="grid gap-4"
+        onSubmit={(event) => {
+          event.preventDefault();
+          if (parsed && !duplicate) void save(parsed.model, parsed.price);
+        }}
+      >
+        <fieldset disabled={readOnly} className="grid min-w-0 gap-4">
+          <legend className="mb-3 text-sm font-medium">
+            {editingModel === null ? "Add model price" : "Edit model price"}
+          </legend>
+          <div className="grid gap-1.5">
+            <Label htmlFor="usage-price-model">Model ID</Label>
+            <Input
+              id="usage-price-model"
+              list="usage-price-models"
+              value={form.model}
+              disabled={editingModel !== null}
+              placeholder="Exact model ID from usage"
+              autoComplete="off"
+              spellCheck={false}
+              required
+              onChange={(event) => setForm({ ...form, model: event.target.value })}
+            />
+            <datalist id="usage-price-models">
+              {models.map((model) => (
+                <option key={model} value={model} />
+              ))}
+            </datalist>
+            {duplicate ? (
+              <p role="alert" className="text-xs text-destructive">
+                This model already has a price. Use Edit to change it.
+              </p>
+            ) : null}
+          </div>
+          <div className="grid grid-cols-2 gap-3">
+            {USAGE_PRICE_FIELDS.map((field) => (
+              <div key={field.key} className="grid gap-1.5">
+                <Label htmlFor={`usage-price-${field.key}`}>
+                  {field.label}
+                  {field.optional ? " (optional)" : ""}
+                </Label>
+                <Input
+                  id={`usage-price-${field.key}`}
+                  type="number"
+                  min="0"
+                  step="any"
+                  inputMode="decimal"
+                  required={!field.optional}
+                  value={form[field.key]}
+                  placeholder={field.optional ? "Use input rate" : "0.00"}
+                  onChange={(event) => setForm({ ...form, [field.key]: event.target.value })}
+                />
+              </div>
+            ))}
+          </div>
+          <p className="text-xs text-muted-foreground">
+            Blank cache rates use the input price. Enter 0 for free tokens. Model IDs match exactly.
+            Remove a price to restore automatic pricing.
+          </p>
+          {error ? (
+            <p role="alert" className="text-sm text-destructive">
+              {error}
+            </p>
+          ) : null}
+          <div className="flex justify-end gap-2">
+            {editingModel !== null ? (
+              <Button variant="outline" onClick={reset}>
+                Cancel
+              </Button>
+            ) : null}
+            <Button type="submit" disabled={parsed === null || duplicate || readOnly}>
+              {pending ? "Saving..." : editingModel === null ? "Add price" : "Save price"}
+            </Button>
+          </div>
+        </fieldset>
+      </form>
+    </>
+  );
+}
diff --git a/apps/web/src/components/usage/usagePriceForm.test.ts b/apps/web/src/components/usage/usagePriceForm.test.ts
new file mode 100644
index 000000000000..47c555651412
--- /dev/null
+++ b/apps/web/src/components/usage/usagePriceForm.test.ts
@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { parseUsagePriceForm, usagePriceForm } from "./usagePriceForm.ts";
+
+describe("model price entry", () => {
+  it("preserves exact model IDs and fractional rates", () => {
+    expect(
+      parseUsagePriceForm({
+        ...usagePriceForm(),
+        model: "  vendor/Example-Model  ",
+        inputCostPerMillionTokens: "2.5",
+        outputCostPerMillionTokens: "10",
+      }),
+    ).toEqual({
+      model: "vendor/Example-Model",
+      price: { inputCostPerMillionTokens: 2.5, outputCostPerMillionTokens: 10 },
+    });
+  });
+
+  it("keeps free cache tokens distinct from blank cache prices", () => {
+    const parsed = parseUsagePriceForm({
+      ...usagePriceForm(),
+      model: "example-model",
+      inputCostPerMillionTokens: "2",
+      outputCostPerMillionTokens: "8",
+      cacheReadCostPerMillionTokens: "0",
+      cacheWriteCostPerMillionTokens: " ",
+    });
+    expect(parsed?.price).toEqual({
+      inputCostPerMillionTokens: 2,
+      outputCostPerMillionTokens: 8,
+      cacheReadCostPerMillionTokens: 0,
+    });
+  });
+
+  it("preserves all prices when editing, including small fractional prices", () => {
+    const price = {
+      inputCostPerMillionTokens: 0,
+      outputCostPerMillionTokens: 8,
+      cacheReadCostPerMillionTokens: 0.0000001,
+      cacheWriteCostPerMillionTokens: 3.5,
+    };
+    expect(parseUsagePriceForm(usagePriceForm("example-model", price))).toEqual({
+      model: "example-model",
+      price,
+    });
+  });
+
+  it.each(["", " ", "-1", "Infinity", "NaN", "1e999", "$2", "0x10"])(
+    "rejects invalid required prices: %j",
+    (inputCostPerMillionTokens) => {
+      expect(
+        parseUsagePriceForm({
+          ...usagePriceForm("example-model", {
+            inputCostPerMillionTokens: 2,
+            outputCostPerMillionTokens: 8,
+          }),
+          inputCostPerMillionTokens,
+        }),
+      ).toBeNull();
+    },
+  );
+
+  it("rejects invalid optional rates and missing model IDs", () => {
+    const form = usagePriceForm("example-model", {
+      inputCostPerMillionTokens: 2,
+      outputCostPerMillionTokens: 8,
+    });
+    expect(parseUsagePriceForm({ ...form, cacheReadCostPerMillionTokens: "-1" })).toBeNull();
+    expect(parseUsagePriceForm({ ...form, cacheWriteCostPerMillionTokens: "invalid" })).toBeNull();
+    expect(parseUsagePriceForm({ ...form, model: " " })).toBeNull();
+  });
+});
diff --git a/apps/web/src/components/usage/usagePriceForm.ts b/apps/web/src/components/usage/usagePriceForm.ts
new file mode 100644
index 000000000000..c52178300cdc
--- /dev/null
+++ b/apps/web/src/components/usage/usagePriceForm.ts
@@ -0,0 +1,62 @@
+import type { UsageModelPriceOverride } from "@t3tools/contracts";
+
+export const USAGE_PRICE_FIELDS = [
+  { key: "inputCostPerMillionTokens", label: "Input", optional: false },
+  { key: "outputCostPerMillionTokens", label: "Output", optional: false },
+  { key: "cacheReadCostPerMillionTokens", label: "Cache read", optional: true },
+  { key: "cacheWriteCostPerMillionTokens", label: "Cache write", optional: true },
+] as const;
+
+export type UsagePriceForm = { model: string } & Record<
+  (typeof USAGE_PRICE_FIELDS)[number]["key"],
+  string
+>;
+
+export function usagePriceForm(model = "", price?: UsageModelPriceOverride): UsagePriceForm {
+  return {
+    model,
+    inputCostPerMillionTokens: price?.inputCostPerMillionTokens.toString() ?? "",
+    outputCostPerMillionTokens: price?.outputCostPerMillionTokens.toString() ?? "",
+    cacheReadCostPerMillionTokens: price?.cacheReadCostPerMillionTokens?.toString() ?? "",
+    cacheWriteCostPerMillionTokens: price?.cacheWriteCostPerMillionTokens?.toString() ?? "",
+  };
+}
+
+/** Blank cache prices use the input rate; explicit zero means free. */
+export function parseUsagePriceForm(
+  form: UsagePriceForm,
+): { model: string; price: UsageModelPriceOverride } | null {
+  const model = form.model.trim();
+  if (model.length === 0) return null;
+  const rates: Partial<Record<(typeof USAGE_PRICE_FIELDS)[number]["key"], number>> = {};
+  for (const field of USAGE_PRICE_FIELDS) {
+    const raw = form[field.key].trim();
+    if (raw === "") {
+      if (field.optional) continue;
+      return null;
+    }
+    if (!/^(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i.test(raw)) return null;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < 0) return null;
+    rates[field.key] = value;
+  }
+  if (
+    rates.inputCostPerMillionTokens === undefined ||
+    rates.outputCostPerMillionTokens === undefined
+  ) {
+    return null;
+  }
+  return {
+    model,
+    price: {
+      inputCostPerMillionTokens: rates.inputCostPerMillionTokens,
+      outputCostPerMillionTokens: rates.outputCostPerMillionTokens,
+      ...(rates.cacheReadCostPerMillionTokens === undefined
+        ? {}
+        : { cacheReadCostPerMillionTokens: rates.cacheReadCostPerMillionTokens }),
+      ...(rates.cacheWriteCostPerMillionTokens === undefined
+        ? {}
+        : { cacheWriteCostPerMillionTokens: rates.cacheWriteCostPerMillionTokens }),
+    },
+  };
+}
diff --git a/docs/user/usage.md b/docs/user/usage.md
index 3a61222be82d..dc79a1e30745 100644
--- a/docs/user/usage.md
+++ b/docs/user/usage.md
@@ -12,6 +12,18 @@ record are missing from the totals.
 If recent work is missing or a new model shows no cost, refresh to rescan session history and
 update model pricing.
 
+## Set custom model prices
+
+On web or desktop, open **Usage → Model prices** to add, edit, or remove a model's estimated
+price. Choose the environment whose history you want to price, then enter the exact model ID and
+USD rates per million input and output tokens. You can enter any model ID, including models
+without public pricing.
+
+Cache read and cache write rates are optional and use the input rate when blank. Enter `0` for
+tokens that are free. Saved prices replace automatic pricing for all of that environment's
+history and are shared with clients connected to it. Set prices on each environment that needs
+them. Removing a price restores automatic pricing.
+
 ## Track subscription limits
 
 **Usage → Limits** shows quota use and reset times for Codex and Claude subscriptions. It also
diff --git a/packages/client-runtime/src/state/server.ts b/packages/client-runtime/src/state/server.ts
index 4a2843abb806..7ba62a681481 100644
--- a/packages/client-runtime/src/state/server.ts
+++ b/packages/client-runtime/src/state/server.ts
@@ -807,6 +807,27 @@ export function createServerEnvironmentAtoms<R, E>(
       Atom.withLabel(`environment-data:server:settings:${environmentId}`),
     ),
   );
+  const usagePricesAtom = Atom.family((environmentId: EnvironmentId) =>
+    Atom.make((get) => {
+      const overrides = get(settingsValueAtom(environmentId))?.usagePriceOverrides ?? {};
+      // Only changed prices should trigger another transcript scan. Settings
+      // snapshots can recreate the same mapping in a different property order.
+      return JSON.stringify(
+        Object.keys(overrides)
+          .sort()
+          .map((model) => {
+            const price = overrides[model]!;
+            return [
+              model,
+              price.inputCostPerMillionTokens,
+              price.outputCostPerMillionTokens,
+              price.cacheReadCostPerMillionTokens,
+              price.cacheWriteCostPerMillionTokens,
+            ];
+          }),
+      );
+    }).pipe(Atom.withLabel(`environment-data:server:usage-prices:${environmentId}`)),
+  );
   const providersValueAtom = Atom.family((environmentId: EnvironmentId) =>
     Atom.make((get) => get(configValueAtom(environmentId))?.providers ?? null).pipe(
       Atom.withLabel(`environment-data:server:providers:${environmentId}`),
@@ -892,6 +913,7 @@ export function createServerEnvironmentAtoms<R, E>(
       label: "environment-data:server:usage-summary",
       tag: WS_METHODS.serverGetUsageSummary,
       staleTimeMs: 60_000,
+      refreshTrigger: ({ environmentId }) => usagePricesAtom(environmentId),
     }),
     configProjection,
     welcome: createEnvironmentRpcSubscriptionAtomFamily(runtime, {
diff --git a/packages/client-runtime/src/state/serverUsage.test.ts b/packages/client-runtime/src/state/serverUsage.test.ts
new file mode 100644
index 000000000000..9cf2667d8bc2
--- /dev/null
+++ b/packages/client-runtime/src/state/serverUsage.test.ts
@@ -0,0 +1,263 @@
+import {
+  DEFAULT_SERVER_SETTINGS,
+  EnvironmentId,
+  UsageDay,
+  USAGE_CONTRACT_VERSION,
+  WS_METHODS,
+  type ServerConfig,
+  type ServerConfigStreamEvent,
+  type ServerSettings,
+  type UsageSummary,
+  type UsageSummaryInput,
+} from "@t3tools/contracts";
+import { expect, it } from "@effect/vitest";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Queue from "effect/Queue";
+import * as Stream from "effect/Stream";
+import * as SubscriptionRef from "effect/SubscriptionRef";
+import { AsyncResult, Atom, AtomRegistry } from "effect/unstable/reactivity";
+
+import {
+  AVAILABLE_CONNECTION_STATE,
+  PrimaryConnectionTarget,
+  type PreparedConnection,
+  type SupervisorConnectionState,
+} from "../connection/model.ts";
+import { EnvironmentRegistry } from "../connection/registry.ts";
+import { EnvironmentSupervisor } from "../connection/supervisor.ts";
+import { EnvironmentCacheStore } from "../platform/persistence.ts";
+import type { WsRpcProtocolClient } from "../rpc/protocol.ts";
+import type { RpcSession } from "../rpc/session.ts";
+import { createServerEnvironmentAtoms } from "./server.ts";
+
+const TARGET = new PrimaryConnectionTarget({
+  environmentId: EnvironmentId.make("usage-environment"),
+  label: "Usage environment",
+  httpBaseUrl: "https://environment.example.test",
+  wsBaseUrl: "wss://environment.example.test",
+});
+
+const INPUT: UsageSummaryInput = {
+  sinceDay: UsageDay.make("2026-09-01"),
+  untilDay: UsageDay.make("2026-09-04"),
+  timeZone: "UTC",
+};
+
+const CONFIG = {
+  settings: DEFAULT_SERVER_SETTINGS,
+  environment: { serverVersion: "0.0.1", capabilities: {} },
+} as ServerConfig;
+
+const makeHarness = Effect.fn("ServerUsageTest.makeHarness")(function* (
+  beforeRead: (request: number) => Effect.Effect<void> = () => Effect.void,
+) {
+  const events = yield* Queue.unbounded<ServerConfigStreamEvent>();
+  let settings = DEFAULT_SERVER_SETTINGS;
+  let requests = 0;
+  const client = {
+    [WS_METHODS.subscribeServerConfig]: () =>
+      Stream.concat(
+        Stream.make({ version: 1 as const, type: "snapshot" as const, config: CONFIG }),
+        Stream.fromQueue(events),
+      ),
+    [WS_METHODS.serverGetUsageSummary]: (input: UsageSummaryInput) =>
+      Effect.gen(function* () {
+        requests += 1;
+        const price = settings.usagePriceOverrides["custom-model"]?.inputCostPerMillionTokens ?? 0;
+        yield* beforeRead(requests);
+        return {
+          contractVersion: USAGE_CONTRACT_VERSION,
+          readAt: "2026-09-04T12:00:00Z",
+          ...input,
+          buckets: [
+            {
+              day: input.sinceDay,
+              provider: "codex",
+              model: "custom-model",
+              totals: {
+                uncachedInputTokens: 1_000_000,
+                cachedInputTokens: 0,
+                cacheCreationTokens: 0,
+                outputTokens: 0,
+                reasoningTokens: 0,
+              },
+              costUsd: price,
+              cacheSavingsUsd: 0,
+              costSource: price === 0 ? "unpriced" : "modelPriced",
+              records: 1,
+              unpricedRecords: price === 0 ? 1 : 0,
+              sessions: 1,
+            },
+          ],
+          sources: [],
+          pricing: { status: "unavailable", source: "test", fetchedAt: null, knownModels: 0 },
+          scanDurationMs: 0,
+        } satisfies UsageSummary;
+      }),
+  } as unknown as WsRpcProtocolClient;
+  const session: RpcSession = {
+    client,
+    initialConfig: Effect.succeed(CONFIG),
+    subscribeServerConfig: (input) => client.subscribeServerConfig(input),
+    ready: Effect.void,
+    probe: Effect.void,
+    closed: Effect.never,
+  };
+  const supervisor = EnvironmentSupervisor.of({
+    target: TARGET,
+    state: yield* SubscriptionRef.make<SupervisorConnectionState>({
+      ...AVAILABLE_CONNECTION_STATE,
+      phase: "connected",
+    }),
+    session: yield* SubscriptionRef.make(Option.some(session)),
+    prepared: yield* SubscriptionRef.make(Option.none<PreparedConnection>()),
+    connect: Effect.void,
+    disconnect: Effect.void,
+    retryNow: Effect.void,
+  });
+  const environments = EnvironmentRegistry.of({
+    run: (_environmentId, effect) =>
+      Effect.provideService(effect, EnvironmentSupervisor, supervisor),
+    followStream: (_environmentId, stream) =>
+      Stream.provideService(stream, EnvironmentSupervisor, supervisor),
+  } as EnvironmentRegistry["Service"]);
+  const cache = EnvironmentCacheStore.of({
+    loadShell: () => Effect.succeed(Option.none()),
+    saveShell: () => Effect.void,
+    loadThread: () => Effect.succeed(Option.none()),
+    saveThread: () => Effect.void,
+    removeThread: () => Effect.void,
+    loadServerConfig: () => Effect.succeed(Option.none()),
+    saveServerConfig: () => Effect.void,
+    loadVcsRefs: () => Effect.succeed(Option.none()),
+    saveVcsRefs: () => Effect.void,
+    removeVcsRefs: () => Effect.void,
+    clearVcsRefs: () => Effect.void,
+    clear: () => Effect.void,
+  });
+  const runtime = Atom.runtime(
+    Layer.merge(
+      Layer.succeed(EnvironmentRegistry, environments),
+      Layer.succeed(EnvironmentCacheStore, cache),
+    ),
+  );
+  const initialConfigValueAtom = Atom.make(CONFIG);
+  const atoms = createServerEnvironmentAtoms(runtime, {
+    initialConfigValueAtom: () => initialConfigValueAtom,
+  });
+  const registry = yield* Effect.acquireRelease(Effect.sync(AtomRegistry.make), (registry) =>
+    Effect.sync(() => registry.dispose()),
+  );
+  const updateSettings = Effect.fn("ServerUsageTest.updateSettings")(function* (
+    next: ServerSettings,
+  ) {
+    settings = next;
+    yield* Queue.offer(events, {
+      version: 1,
+      type: "settingsUpdated",
+      payload: { settings },
+    });
+    yield* AtomRegistry.toStream(registry, atoms.settingsValueAtom(TARGET.environmentId)).pipe(
+      Stream.filter((current) => current === next),
+      Stream.runHead,
+    );
+  });
+  return {
+    registry,
+    requests: () => requests,
+    updateSettings,
+    summary: (input = INPUT) => atoms.usageSummary({ environmentId: TARGET.environmentId, input }),
+  };
+});
+
+function waitForCost<E>(
+  registry: AtomRegistry.AtomRegistry,
+  atom: Atom.Atom<AsyncResult.AsyncResult<UsageSummary, E>>,
+  cost: number,
+) {
+  return AtomRegistry.toStream(registry, atom).pipe(
+    Stream.filter(
+      (result) =>
+        AsyncResult.isSuccess(result) &&
+        !result.waiting &&
+        result.value.buckets[0]?.costUsd === cost,
+    ),
+    Stream.runHead,
+  );
+}
+
+it.effect("refreshes cached usage windows only when override prices change", () =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const harness = yield* makeHarness();
+      const current = harness.summary();
+      const previous = harness.summary({ ...INPUT, sinceDay: UsageDay.make("2026-08-01") });
+      const unmountCurrent = harness.registry.mount(current);
+      const unmountPrevious = harness.registry.mount(previous);
+      yield* waitForCost(harness.registry, current, 0);
+      yield* waitForCost(harness.registry, previous, 0);
+      unmountPrevious();
+      expect(harness.requests()).toBe(2);
+
+      const prices = {
+        "custom-model": { inputCostPerMillionTokens: 3, outputCostPerMillionTokens: 9 },
+        "other-model": { inputCostPerMillionTokens: 1, outputCostPerMillionTokens: 2 },
+      };
+      yield* harness.updateSettings({ ...DEFAULT_SERVER_SETTINGS, usagePriceOverrides: prices });
+      yield* waitForCost(harness.registry, current, 3);
+      yield* waitForCost(harness.registry, previous, 3);
+      expect(harness.requests()).toBe(4);
+
+      yield* harness.updateSettings({
+        ...DEFAULT_SERVER_SETTINGS,
+        usagePriceOverrides: {
+          "other-model": { outputCostPerMillionTokens: 2, inputCostPerMillionTokens: 1 },
+          "custom-model": { outputCostPerMillionTokens: 9, inputCostPerMillionTokens: 3 },
+        },
+      });
+      yield* harness.updateSettings({
+        ...DEFAULT_SERVER_SETTINGS,
+        usagePriceOverrides: prices,
+        defaultTheme: "custom-theme",
+      });
+      yield* harness.updateSettings(DEFAULT_SERVER_SETTINGS);
+      yield* waitForCost(harness.registry, current, 0);
+      yield* waitForCost(harness.registry, previous, 0);
+      expect(harness.requests()).toBe(6);
+      unmountCurrent();
+    }),
+  ),
+);
+
+it.effect("restarts a pending usage read after a price change", () =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const started = yield* Deferred.make<void>();
+      const interrupted = yield* Deferred.make<void>();
+      const harness = yield* makeHarness((request) =>
+        request === 1
+          ? Deferred.succeed(started, undefined).pipe(
+              Effect.andThen(Effect.never),
+              Effect.onInterrupt(() => Deferred.succeed(interrupted, undefined)),
+            )
+          : Effect.void,
+      );
+      const summary = harness.summary();
+      const unmount = harness.registry.mount(summary);
+      yield* Deferred.await(started);
+      yield* harness.updateSettings({
+        ...DEFAULT_SERVER_SETTINGS,
+        usagePriceOverrides: {
+          "custom-model": { inputCostPerMillionTokens: 5, outputCostPerMillionTokens: 10 },
+        },
+      });
+      yield* waitForCost(harness.registry, summary, 5);
+      yield* Deferred.await(interrupted);
+      expect(harness.requests()).toBe(2);
+      unmount();
+    }),
+  ),
+);
diff --git a/packages/contracts/src/environment.ts b/packages/contracts/src/environment.ts
index 8d03a73b0249..38347ebc92b9 100644
--- a/packages/contracts/src/environment.ts
+++ b/packages/contracts/src/environment.ts
@@ -105,6 +105,8 @@ export const ExecutionEnvironmentCapabilities = Schema.Struct({
   /** Server streams quota from configured usage-limit sources. Same
       version-skew contract as environmentThemes. */
   usageLimitSources: Schema.optionalKey(Schema.Boolean),
+  /** Server persists custom model rates and applies them to usage summaries. */
+  usagePriceOverrides: Schema.optionalKey(Schema.Boolean),
   /** Server understands thread.pin / thread.unpin commands. Same
       version-skew contract as threadSettlement. */
   threadPinning: Schema.optionalKey(Schema.Boolean),
diff --git a/packages/contracts/src/settings.test.ts b/packages/contracts/src/settings.test.ts
index 5d4c1573ef7e..bee5c9a3f0d5 100644
--- a/packages/contracts/src/settings.test.ts
+++ b/packages/contracts/src/settings.test.ts
@@ -21,6 +21,58 @@ const decodeServerSettingsPatch = Schema.decodeUnknownSync(ServerSettingsPatch);
 const encodeServerSettings = Schema.encodeSync(ServerSettings);
 const decodeClaudeSettings = Schema.decodeUnknownSync(ClaudeSettings);
 
+describe("ServerSettings usage price overrides", () => {
+  const prices = { inputCostPerMillionTokens: 2, outputCostPerMillionTokens: 8 };
+
+  it("defaults to automatic pricing and round-trips arbitrary model IDs", () => {
+    expect(decodeServerSettings({}).usagePriceOverrides).toEqual({});
+    const settings = decodeServerSettings({
+      usagePriceOverrides: { "  vendor/example-model  ": prices },
+    });
+    expect(encodeServerSettings(settings).usagePriceOverrides).toEqual({
+      "vendor/example-model": prices,
+    });
+  });
+
+  it("accepts zero rates, optional cache rates, and per-model deletion", () => {
+    const overrides = {
+      "example-model": {
+        inputCostPerMillionTokens: 0,
+        outputCostPerMillionTokens: 0,
+        cacheReadCostPerMillionTokens: 0.5,
+        cacheWriteCostPerMillionTokens: 3,
+      },
+      "removed-model": null,
+    };
+    expect(
+      decodeServerSettingsPatch({ usagePriceOverrides: overrides }).usagePriceOverrides,
+    ).toEqual(overrides);
+  });
+
+  it.each([
+    "inputCostPerMillionTokens",
+    "outputCostPerMillionTokens",
+    "cacheReadCostPerMillionTokens",
+    "cacheWriteCostPerMillionTokens",
+  ])("rejects invalid %s rates at the settings boundary", (field) => {
+    for (const value of [-1, Number.NaN, Number.POSITIVE_INFINITY, "2"]) {
+      const usagePriceOverrides = { "example-model": { ...prices, [field]: value } };
+      expect(() => decodeServerSettings({ usagePriceOverrides })).toThrow();
+      expect(() => decodeServerSettingsPatch({ usagePriceOverrides })).toThrow();
+    }
+  });
+
+  it("rejects empty model IDs and incomplete input/output pricing", () => {
+    for (const usagePriceOverrides of [
+      { " ": prices },
+      { "example-model": { inputCostPerMillionTokens: 2 } },
+      { "example-model": { outputCostPerMillionTokens: 8 } },
+    ]) {
+      expect(() => decodeServerSettingsPatch({ usagePriceOverrides })).toThrow();
+    }
+  });
+});
+
 describe("ClaudeSettings auto-compaction", () => {
   it("uses Claude's default threshold when no override is configured", () => {
     expect(decodeClaudeSettings({}).autoCompactWindow).toBe("");
diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts
index fef3b2992f07..cd4b12713edf 100644
--- a/packages/contracts/src/settings.ts
+++ b/packages/contracts/src/settings.ts
@@ -358,6 +358,20 @@ export const DEFAULT_CLIENT_SETTINGS: ClientSettings = Schema.decodeSync(ClientS
 
 // ── Server Settings (server-authoritative) ────────────────────
 
+const UsageModelTokenPrice = Schema.Number.check(
+  Schema.isFinite(),
+  Schema.isGreaterThanOrEqualTo(0),
+);
+
+/** USD per million tokens. Omitted cache rates use the input rate. */
+export const UsageModelPriceOverride = Schema.Struct({
+  inputCostPerMillionTokens: UsageModelTokenPrice,
+  outputCostPerMillionTokens: UsageModelTokenPrice,
+  cacheReadCostPerMillionTokens: Schema.optionalKey(UsageModelTokenPrice),
+  cacheWriteCostPerMillionTokens: Schema.optionalKey(UsageModelTokenPrice),
+});
+export type UsageModelPriceOverride = typeof UsageModelPriceOverride.Type;
+
 const makeBinaryPathSetting = (fallback: string) =>
   TrimmedString.pipe(
     Schema.decodeTo(
@@ -930,6 +944,10 @@ export const ServerSettings = Schema.Struct({
   usageLimitSources: Schema.Record(UsageLimitSourceId, UsageLimitSourceConfig).pipe(
     Schema.withDecodingDefault(Effect.succeed({})),
   ),
+  /** Exact model IDs, applied to past and future usage on this environment. */
+  usagePriceOverrides: Schema.Record(TrimmedNonEmptyString, UsageModelPriceOverride).pipe(
+    Schema.withDecodingDefault(Effect.succeed({})),
+  ),
 });
 export type ServerSettings = typeof ServerSettings.Type;
 
@@ -1141,6 +1159,10 @@ export const ServerSettingsPatch = Schema.Struct({
   usageLimitSources: Schema.optionalKey(
     Schema.Record(UsageLimitSourceId, Schema.NullOr(UsageLimitSourceConfig)),
   ),
+  /** Each entry replaces one model's rates; `null` restores automatic pricing. */
+  usagePriceOverrides: Schema.optionalKey(
+    Schema.Record(TrimmedNonEmptyString, Schema.NullOr(UsageModelPriceOverride)),
+  ),
 });
 export type ServerSettingsPatch = typeof ServerSettingsPatch.Type;
 
diff --git a/packages/contracts/src/usage.ts b/packages/contracts/src/usage.ts
index 8c099ddb33aa..c36a4557c294 100644
--- a/packages/contracts/src/usage.ts
+++ b/packages/contracts/src/usage.ts
@@ -55,7 +55,7 @@ export type UsageResolution = typeof UsageResolution.Type;
  * Why a bucket's cost is what it is.
  *
  * - `providerReported` - the transcript carried an explicit cost figure.
- * - `modelPriced` - we matched the model against the LiteLLM rate table.
+ * - `modelPriced` - we used a custom price override or the LiteLLM rate table.
  * - `unpriced` - tokens are known, rates are not. Counted in totals, excluded
  *   from cost.
  */
diff --git a/packages/shared/src/serverSettings.test.ts b/packages/shared/src/serverSettings.test.ts
index 64b0e1b8337b..1f847412b6c7 100644
--- a/packages/shared/src/serverSettings.test.ts
+++ b/packages/shared/src/serverSettings.test.ts
@@ -322,6 +322,28 @@ describe("serverSettings helpers", () => {
     expect(Object.keys(removed.usageLimitSources)).toEqual([hubB]);
   });
 
+  it("replaces and removes individual usage prices without clobbering other models", () => {
+    const prices = { inputCostPerMillionTokens: 2, outputCostPerMillionTokens: 8 };
+    const current = applyServerSettingsPatch(DEFAULT_SERVER_SETTINGS, {
+      usagePriceOverrides: { "example-model": { ...prices, cacheReadCostPerMillionTokens: 0.5 } },
+    });
+    const added = applyServerSettingsPatch(current, {
+      usagePriceOverrides: { "other-model": prices },
+    });
+    const replaced = applyServerSettingsPatch(added, {
+      usagePriceOverrides: { "example-model": prices },
+    });
+    expect(replaced.usagePriceOverrides).toEqual({
+      "example-model": prices,
+      "other-model": prices,
+    });
+    const removed = applyServerSettingsPatch(replaced, {
+      usagePriceOverrides: { "example-model": null },
+    });
+    expect(removed.usagePriceOverrides).toEqual({ "other-model": prices });
+    expect(current.usagePriceOverrides["example-model"]?.cacheReadCostPerMillionTokens).toBe(0.5);
+  });
+
   it("stores background activity profiles as a versioned object and syncs legacy aliases", () => {
     const next = applyServerSettingsPatch(DEFAULT_SERVER_SETTINGS, {
       backgroundActivity: {
diff --git a/packages/shared/src/serverSettings.ts b/packages/shared/src/serverSettings.ts
index 67f73f84063a..dfd5b742e4e4 100644
--- a/packages/shared/src/serverSettings.ts
+++ b/packages/shared/src/serverSettings.ts
@@ -123,10 +123,10 @@ function mergeModelSelectionOptionsById(input: {
 }
 
 /** Upsert each patched entry; `null` removes it. Entries the patch omits are untouched. */
-function mergeUsageLimitSources(
-  current: ServerSettings["usageLimitSources"],
-  patch: NonNullable<ServerSettingsPatch["usageLimitSources"]>,
-): ServerSettings["usageLimitSources"] {
+function mergeSettingsEntries<Value>(
+  current: Readonly<Record<string, Value>>,
+  patch: Readonly<Record<string, Value | null>>,
+): Record<string, Value> {
   const next = new Map(Object.entries(current));
   for (const [id, config] of Object.entries(patch)) {
     if (config === null) {
@@ -135,7 +135,7 @@ function mergeUsageLimitSources(
       next.set(id, config);
     }
   }
-  return Object.fromEntries(next) as ServerSettings["usageLimitSources"];
+  return Object.fromEntries(next);
 }
 
 export function applyServerSettingsPatch(
@@ -150,6 +150,7 @@ export function applyServerSettingsPatch(
     backgroundActivity,
     // Merged per entry below; its `null` removals must not reach deepMerge.
     usageLimitSources: usageLimitSourcesPatch,
+    usagePriceOverrides: usagePriceOverridesPatch,
     ...patchForMerge
   } = patch;
   const currentBackgroundActivity = normalizeServerBackgroundActivitySettings(current);
@@ -208,12 +209,20 @@ export function applyServerSettingsPatch(
       : {}),
     ...(usageLimitSourcesPatch !== undefined
       ? {
-          usageLimitSources: mergeUsageLimitSources(
+          usageLimitSources: mergeSettingsEntries(
             current.usageLimitSources,
             usageLimitSourcesPatch,
           ),
         }
       : {}),
+    ...(usagePriceOverridesPatch !== undefined
+      ? {
+          usagePriceOverrides: mergeSettingsEntries(
+            current.usagePriceOverrides,
+            usagePriceOverridesPatch,
+          ),
+        }
+      : {}),
     ...(patch.sourceControlWriterModelSelection !== undefined
       ? { sourceControlWriterModelSelection: patch.sourceControlWriterModelSelection }
       : {}),

From 91c66ac43ddad4f8697887009746f4de11736cb9 Mon Sep 17 00:00:00 2001
From: maria <maria@kuuro.net>
Date: Fri, 4 Sep 2026 17:32:40 -0400
Subject: [PATCH 29/56] fix(web): center pull request link previews (#9794)

---
 apps/web/src/components/pullRequest/PullRequestLinkPreview.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/web/src/components/pullRequest/PullRequestLinkPreview.tsx b/apps/web/src/components/pullRequest/PullRequestLinkPreview.tsx
index f7d477e9afad..36a4c8b15c1c 100644
--- a/apps/web/src/components/pullRequest/PullRequestLinkPreview.tsx
+++ b/apps/web/src/components/pullRequest/PullRequestLinkPreview.tsx
@@ -84,7 +84,7 @@ export function PullRequestLinkPreview({
   return (
     <PreviewCard open={open} onOpenChange={setOpen}>
       <PreviewCardTrigger render={trigger} delay={350} closeDelay={120} />
-      <PreviewCardPopup className="w-80 max-w-[calc(100vw-2rem)] p-3">
+      <PreviewCardPopup align="center" className="w-80 max-w-[calc(100vw-2rem)] p-3">
         {detail === null ? (
           <p className="text-xs leading-relaxed text-muted-foreground wrap-anywhere">
             {detailQuery.isPending ? "Loading pull request details…" : originalUrl}

From 98a29cbaa1ccf8d8afb6d35e3e1d925ff9b5fa90 Mon Sep 17 00:00:00 2001
From: maria <maria@kuuro.net>
Date: Fri, 4 Sep 2026 17:46:12 -0400
Subject: [PATCH 30/56] fix: address usage limits and merge settlement
 regressions (#9784)

---
 apps/mobile/src/connection/runtime.ts         |   5 +-
 .../Layers/ClaudeCapabilitiesProbe.test.ts    |  42 ++++
 .../src/provider/Layers/ClaudeProvider.ts     |  63 ++---
 .../pullRequest/PullRequestService.test.ts    |  24 +-
 .../src/pullRequest/PullRequestService.ts     |   9 +
 apps/web/src/components/usage/UsagePage.tsx   |  14 +-
 apps/web/src/connection/runtime.ts            |   2 +-
 .../client-runtime/src/rpc/session.test.ts    | 217 ++++++++++++++----
 packages/client-runtime/src/rpc/session.ts    |  25 +-
 9 files changed, 308 insertions(+), 93 deletions(-)

diff --git a/apps/mobile/src/connection/runtime.ts b/apps/mobile/src/connection/runtime.ts
index ee224ce9f6ed..662a4dcdf70c 100644
--- a/apps/mobile/src/connection/runtime.ts
+++ b/apps/mobile/src/connection/runtime.ts
@@ -30,7 +30,10 @@ type ConnectionLayerSource =
   | typeof mobileBackgroundActivityObserverLayer
   | typeof mobileBackgroundActivityReporterLayer;
 
-const providedClientConnectionLayer = Layer.merge(Connection.layer, snapshotLoaderLayer).pipe(
+const providedClientConnectionLayer = Layer.merge(
+  Connection.layerWithOptions({ usageLimitSources: true }),
+  snapshotLoaderLayer,
+).pipe(
   Layer.provideMerge(
     Layer.mergeAll(
       runtimeContextLayer,
diff --git a/apps/server/src/provider/Layers/ClaudeCapabilitiesProbe.test.ts b/apps/server/src/provider/Layers/ClaudeCapabilitiesProbe.test.ts
index f167955fbaec..232b8cc02d00 100644
--- a/apps/server/src/provider/Layers/ClaudeCapabilitiesProbe.test.ts
+++ b/apps/server/src/provider/Layers/ClaudeCapabilitiesProbe.test.ts
@@ -1,4 +1,9 @@
 // @effect-diagnostics nodeBuiltinImport:off - cleanup uses Node's retrying rm, which the FileSystem service does not expose.
+import * as ClaudeSdk from "@anthropic-ai/claude-agent-sdk";
+import { vi } from "vite-plus/test";
+import * as Deferred from "effect/Deferred";
+import * as Fiber from "effect/Fiber";
+import * as TestClock from "effect/testing/TestClock";
 import { ClaudeSettings } from "@t3tools/contracts";
 import * as NodeFSP from "node:fs/promises";
 import * as NodeServices from "@effect/platform-node/NodeServices";
@@ -14,6 +19,8 @@ import {
   probeClaudeCapabilities,
 } from "./ClaudeProvider.ts";
 
+vi.mock("@anthropic-ai/claude-agent-sdk", { spy: true });
+
 const decodeClaudeSettings = Schema.decodeSync(ClaudeSettings);
 
 it("isolates Claude capability probes without dropping workspace setting sources", () => {
@@ -181,3 +188,38 @@ it.layer(NodeServices.layer)("Claude capability probe SDK boundary", (it) => {
     }).pipe(Effect.scoped),
   );
 });
+
+it.effect("preserves initialized capabilities when optional usage times out", () =>
+  Effect.gen(function* () {
+    const usageStarted = yield* Deferred.make<void>();
+    let abortSignal: AbortSignal | undefined;
+    const query = vi.spyOn(ClaudeSdk, "query").mockImplementation(({ options }) => {
+      abortSignal = options?.abortController?.signal;
+      return {
+        initializationResult: async () => ({
+          account: { email: "dev@example.com", subscriptionType: "pro", tokenSource: "oauth" },
+          commands: [{ name: "review", description: "Review changes", argumentHint: "[path]" }],
+        }),
+        usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET: () => {
+          Deferred.doneUnsafe(usageStarted, Effect.void);
+          return new Promise(() => {});
+        },
+      } as ReturnType<typeof ClaudeSdk.query>;
+    });
+    yield* Effect.addFinalizer(() => Effect.sync(() => query.mockRestore()));
+    const probe = yield* probeClaudeCapabilities(
+      decodeClaudeSettings({ binaryPath: "claude" }),
+    ).pipe(Effect.forkChild);
+    yield* Deferred.await(usageStarted);
+    yield* TestClock.adjust("4 seconds");
+    const capabilities = yield* Fiber.join(probe);
+    assert.equal(capabilities?.email, "dev@example.com");
+    assert.equal(capabilities?.subscriptionType, "pro");
+    assert.equal(capabilities?.tokenSource, "oauth");
+    assert.deepEqual(capabilities?.slashCommands, [
+      { name: "review", description: "Review changes", input: { hint: "[path]" } },
+    ]);
+    assert.equal(capabilities?.usage, undefined);
+    assert.equal(abortSignal?.aborted, true);
+  }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+);
diff --git a/apps/server/src/provider/Layers/ClaudeProvider.ts b/apps/server/src/provider/Layers/ClaudeProvider.ts
index e4ec8c522da7..e3d2c6ab565d 100644
--- a/apps/server/src/provider/Layers/ClaudeProvider.ts
+++ b/apps/server/src/provider/Layers/ClaudeProvider.ts
@@ -355,44 +355,47 @@ const probeClaudeCapabilities = (
         }),
       });
       const init = await q.initializationResult();
-      // Usage is a second control round trip on the same process; a failure
-      // there must not cost the slash commands and account we already have.
-      const usage = await q.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET().then(
-        (response) => ({
-          rate_limits_available: response.rate_limits_available,
-          rate_limits: response.rate_limits,
-        }),
-        () => undefined,
-      );
-      const account = init.account as
-        | {
-            readonly email?: string;
-            readonly subscriptionType?: string;
-            readonly tokenSource?: string;
-            readonly apiProvider?: string;
-          }
-        | undefined;
-      return {
-        email: account?.email,
-        subscriptionType: account?.subscriptionType,
-        tokenSource: account?.tokenSource,
-        apiProvider: account?.apiProvider,
-        slashCommands: parseClaudeInitializationCommands(init.commands),
-        ...(usage ? { usage } : {}),
-      } satisfies ClaudeCapabilitiesProbe;
+      return { q, init };
     });
   }).pipe(
+    Effect.timeout(CAPABILITIES_PROBE_TIMEOUT_MS),
+    Effect.flatMap(({ q, init }) =>
+      Effect.gen(function* () {
+        // Usage has its own deadline so a slow optional request cannot discard initialization.
+        const usageResult = yield* Effect.tryPromise(() =>
+          q.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET(),
+        ).pipe(Effect.timeout(DEFAULT_TIMEOUT_MS), Effect.result);
+        const usage = Result.isSuccess(usageResult)
+          ? {
+              rate_limits_available: usageResult.success.rate_limits_available,
+              rate_limits: usageResult.success.rate_limits,
+            }
+          : undefined;
+        const account = init.account as
+          | {
+              readonly email?: string;
+              readonly subscriptionType?: string;
+              readonly tokenSource?: string;
+              readonly apiProvider?: string;
+            }
+          | undefined;
+        return {
+          email: account?.email,
+          subscriptionType: account?.subscriptionType,
+          tokenSource: account?.tokenSource,
+          apiProvider: account?.apiProvider,
+          slashCommands: parseClaudeInitializationCommands(init.commands),
+          ...(usage ? { usage } : {}),
+        } satisfies ClaudeCapabilitiesProbe;
+      }),
+    ),
     Effect.ensuring(
       Effect.sync(() => {
         if (!abort.signal.aborted) abort.abort();
       }),
     ),
-    Effect.timeoutOption(CAPABILITIES_PROBE_TIMEOUT_MS),
     Effect.result,
-    Effect.map((result) => {
-      if (Result.isFailure(result)) return undefined;
-      return Option.isSome(result.success) ? result.success.value : undefined;
-    }),
+    Effect.map((result) => (Result.isSuccess(result) ? result.success : undefined)),
   );
 };
 
diff --git a/apps/server/src/pullRequest/PullRequestService.test.ts b/apps/server/src/pullRequest/PullRequestService.test.ts
index 1f2ff59a94d3..43ba73d325ef 100644
--- a/apps/server/src/pullRequest/PullRequestService.test.ts
+++ b/apps/server/src/pullRequest/PullRequestService.test.ts
@@ -1005,10 +1005,12 @@ it.effect("refuses an action the host never claimed it could run", () =>
   }),
 );
 
-it.effect("publishes a successful merge for immediate settlement", () =>
+it.effect("publishes a merge for immediate settlement only after host confirmation", () =>
   Effect.scoped(
     Effect.gen(function* () {
       const mergedAt = "2026-09-03T02:00:00.000Z";
+      let state: "open" | "merged" = "open";
+      let confirmationFails = false;
       const reference = { projectId: "p1" as ProjectId, repository: "acme/web", number: 1 };
       const service = yield* makeService({
         projects: [
@@ -1016,7 +1018,17 @@ it.effect("publishes a successful merge for immediate settlement", () =>
         ],
         providers: [
           fakeProvider("github", {
-            runAction: () => TestClock.setTime(Date.parse(mergedAt)),
+            getChangeRequestSummary: () =>
+              confirmationFails
+                ? Effect.fail(
+                    new PullRequestProviderError({
+                      provider: "github",
+                      operation: "getChangeRequestSummary",
+                      reason: "failed",
+                      detail: "HTTP 504",
+                    }),
+                  )
+                : Effect.succeed({ ...changeRequest(1, mergedAt), state }),
           }),
         ],
       });
@@ -1025,6 +1037,13 @@ it.effect("publishes a successful merge for immediate settlement", () =>
         Effect.forkChild({ startImmediately: true }),
       );
 
+      // Queueing succeeds while the host still reports an open PR.
+      yield* service.runAction({ ...reference, action: "merge" });
+      confirmationFails = true;
+      yield* service.runAction({ ...reference, action: "merge" });
+      confirmationFails = false;
+      state = "merged";
+      yield* TestClock.setTime(Date.parse(mergedAt));
       yield* service.runAction({
         ...reference,
         repository: " ACME/WEB ",
@@ -1965,6 +1984,7 @@ it.effect("refuses a merge strategy the host does not offer", () =>
             review: FULL_REVIEW,
             reviewers: FULL_REVIEWERS,
           },
+          getChangeRequestSummary: () => Effect.succeed(changeRequest(1, "2026-07-02T00:00:00Z")),
           runAction: (input) => {
             ranWith = input.mergeMethod ?? "merge";
             return Effect.void;
diff --git a/apps/server/src/pullRequest/PullRequestService.ts b/apps/server/src/pullRequest/PullRequestService.ts
index 6a37ed935848..ceba7ce32e04 100644
--- a/apps/server/src/pullRequest/PullRequestService.ts
+++ b/apps/server/src/pullRequest/PullRequestService.ts
@@ -2432,6 +2432,15 @@ export const make = Effect.gen(function* () {
     bumpRefEpoch({ ...input, repository });
     listingsEpoch = ++epochCounter;
     if (input.action === "merge") {
+      // A successful merge action can merely enqueue the PR or enable auto-merge.
+      const confirmed = yield* summaryUncached({ ...input, repository }).pipe(
+        Effect.catch((error) =>
+          Effect.logWarning("failed to confirm pull request merge", { error }).pipe(
+            Effect.as(null),
+          ),
+        ),
+      );
+      if (confirmed?.state !== "merged") return;
       yield* PubSub.publish(mergedPullRequests, {
         projectId: input.projectId,
         repository,
diff --git a/apps/web/src/components/usage/UsagePage.tsx b/apps/web/src/components/usage/UsagePage.tsx
index a96e4ac37410..c73a9a9ffb39 100644
--- a/apps/web/src/components/usage/UsagePage.tsx
+++ b/apps/web/src/components/usage/UsagePage.tsx
@@ -1,3 +1,4 @@
+import { useAtomValue } from "@effect/atom-react";
 import type { UsageProviderKind } from "@t3tools/contracts";
 import { CheckIcon, RefreshCwIcon, XIcon } from "lucide-react";
 import { useMemo, useState } from "react";
@@ -6,7 +7,7 @@ import type { DailyTotals, HourlyTotals } from "@t3tools/shared/usageMerge";
 
 import { isElectron } from "../../env";
 import { cn } from "../../lib/utils";
-import { usePrimaryEnvironmentId } from "../../state/environments";
+import { environmentPresentations } from "../../state/presentation";
 import { serverEnvironment } from "../../state/server";
 import { useUsage, type EnvironmentUsageStatus } from "../../state/usage";
 import { useAtomCommand } from "../../state/use-atom-command";
@@ -69,7 +70,7 @@ export function UsagePage() {
   const { days: windowDays, window } = windowSelection;
   const isPast24Hours = windowDays === 1;
   const { merged, environments, isPending, isPartial, refresh } = useUsage(window);
-  const primaryEnvironmentId = usePrimaryEnvironmentId();
+  const presentations = useAtomValue(environmentPresentations.presentationsAtom);
   const refreshProviders = useAtomCommand(serverEnvironment.refreshProviders, {
     reportFailure: false,
   });
@@ -115,12 +116,11 @@ export function UsagePage() {
     });
   };
   const refreshWindow = () => {
-    // On Limits the button re-probes every provider (and usage-limit source)
-    // on the primary environment; the live snapshots then flow in over the
-    // config stream, so nothing else needs to move.
     if (showingLimits) {
-      if (primaryEnvironmentId) {
-        void refreshProviders({ environmentId: primaryEnvironmentId, input: {} });
+      for (const [environmentId, presentation] of presentations) {
+        if (presentation.connection.phase === "connected" && presentation.serverConfig !== null) {
+          void refreshProviders({ environmentId, input: {} });
+        }
       }
       return;
     }
diff --git a/apps/web/src/connection/runtime.ts b/apps/web/src/connection/runtime.ts
index 06c8bf0ccfed..eacce33a816c 100644
--- a/apps/web/src/connection/runtime.ts
+++ b/apps/web/src/connection/runtime.ts
@@ -31,7 +31,7 @@ type ConnectionLayerSource =
   | typeof backgroundActivityReporterLayer;
 
 const providedClientConnectionLayer = Layer.merge(
-  Connection.layerWithOptions({ environmentThemes: true }),
+  Connection.layerWithOptions({ environmentThemes: true, usageLimitSources: true }),
   snapshotLoaderLayer,
 ).pipe(
   Layer.provideMerge(
diff --git a/packages/client-runtime/src/rpc/session.test.ts b/packages/client-runtime/src/rpc/session.test.ts
index f8f940bc551f..f463ec280da1 100644
--- a/packages/client-runtime/src/rpc/session.test.ts
+++ b/packages/client-runtime/src/rpc/session.test.ts
@@ -8,6 +8,7 @@ import {
   ServerConfigStreamEvent,
   type ServerConfigStreamEvent as ServerConfigStreamEventType,
   WS_METHODS,
+  UsageLimitSourceId,
 } from "@t3tools/contracts";
 import { describe, expect, it } from "@effect/vitest";
 import * as Cause from "effect/Cause";
@@ -174,6 +175,29 @@ const THEME_SERVER_CONFIG: ServerConfigType = {
   },
 };
 const ENCODED_THEME_SERVER_CONFIG = encodeServerConfig(THEME_SERVER_CONFIG);
+const SOURCE_SERVER_CONFIG: ServerConfigType = {
+  ...THEME_SERVER_CONFIG,
+  environment: {
+    ...THEME_SERVER_CONFIG.environment,
+    capabilities: { ...THEME_SERVER_CONFIG.environment.capabilities, usageLimitSources: true },
+  },
+};
+const SOURCE_EVENT: ServerConfigStreamEventType = {
+  version: 1,
+  type: "usageLimitSourcesUpdated",
+  payload: {
+    sources: [
+      {
+        id: UsageLimitSourceId.make("proxy"),
+        kind: "cliproxy",
+        label: "Proxy",
+        checkedAt: "2026-09-04T00:00:00Z",
+        accounts: [],
+      },
+    ],
+  },
+};
+
 const LEGACY_SERVER_CONFIG = {
   ...ENCODED_SERVER_CONFIG,
   environment: {
@@ -402,52 +426,133 @@ describe("RpcSessionFactory", () => {
     ),
   );
 
-  it.effect("shares only a config subscription with the same theme opt-in", () =>
+  for (const options of [
+    { environmentThemes: true },
+    { usageLimitSources: true },
+    { environmentThemes: true, usageLimitSources: true },
+  ]) {
+    it.effect(
+      `shares only a config subscription with the same opt-ins: ${JSON.stringify(options)}`,
+      () =>
+        Effect.scoped(
+          Effect.gen(function* () {
+            const { factory, sockets } = yield* makeFactory(options);
+            const session = yield* factory.connect(PREPARED);
+            const readyFiber = yield* Effect.forkChild(session.ready);
+            const socket = yield* awaitSocket(sockets);
+            socket.open();
+            yield* completeInitialConfig(socket, ENCODED_THEME_SERVER_CONFIG, options);
+            yield* Fiber.join(readyFiber);
+
+            const shared = yield* session.subscribeServerConfig(options).pipe(Stream.runHead);
+            expect(shared).toMatchObject({ _tag: "Some", value: { type: "snapshot" } });
+            expect(
+              socket.sent.map((message) => decodeJson(message)).filter(isRpcRequest),
+            ).toHaveLength(1);
+
+            const fallbackFiber = yield* session
+              .subscribeServerConfig({})
+              .pipe(Stream.runHead, Effect.forkChild);
+            const fallbackRequest = yield* awaitRequest(socket, 1);
+            expect(fallbackRequest).toMatchObject({
+              tag: WS_METHODS.subscribeServerConfig,
+              payload: {},
+            });
+            socket.serverMessage(
+              encodeJson({
+                _tag: "Chunk",
+                requestId: fallbackRequest.id,
+                values: [
+                  {
+                    version: 1,
+                    type: "snapshot",
+                    config: ENCODED_THEME_SERVER_CONFIG,
+                  },
+                ],
+              }),
+            );
+            expect(yield* Fiber.join(fallbackFiber)).toMatchObject({
+              _tag: "Some",
+              value: { type: "snapshot" },
+            });
+          }),
+        ),
+    );
+  }
+
+  it.effect.each([
+    { usageLimitSources: true },
+    { environmentThemes: true, usageLimitSources: true },
+  ])("replays usage sources, removal, and capability downgrade with %j", (options) =>
     Effect.scoped(
       Effect.gen(function* () {
-        const { factory, sockets } = yield* makeFactory({ environmentThemes: true });
+        const { factory, sockets } = yield* makeFactory(options);
         const session = yield* factory.connect(PREPARED);
-        const readyFiber = yield* Effect.forkChild(session.ready);
+        const ready = yield* Effect.forkChild(session.ready);
         const socket = yield* awaitSocket(sockets);
         socket.open();
-        yield* completeInitialConfig(socket, ENCODED_THEME_SERVER_CONFIG, {
-          environmentThemes: true,
-        });
-        yield* Fiber.join(readyFiber);
-
-        const shared = yield* session
-          .subscribeServerConfig({ environmentThemes: true })
-          .pipe(Stream.runHead);
-        expect(shared).toMatchObject({ _tag: "Some", value: { type: "snapshot" } });
+        yield* completeInitialConfig(socket, encodeServerConfig(SOURCE_SERVER_CONFIG), options);
+        yield* Fiber.join(ready);
+        const observed = yield* Queue.unbounded<ServerConfigStreamEventType>();
+        yield* session.subscribeServerConfig(options).pipe(
+          Stream.runForEach((event) => Queue.offer(observed, event)),
+          Effect.forkChild,
+        );
+        expect((yield* Queue.take(observed)).type).toBe("snapshot");
+        const themes: ServerConfigStreamEventType[] = options.environmentThemes
+          ? [{ version: 1, type: "environmentThemesUpdated", payload: { themes: [] } }]
+          : [];
+        for (const event of themes) {
+          yield* publishConfigEvents(socket, [event]);
+          expect(yield* Queue.take(observed)).toEqual(event);
+        }
+        const events: ServerConfigStreamEventType[] = [
+          SOURCE_EVENT,
+          { version: 1, type: "usageLimitSourcesUpdated", payload: { sources: [] } },
+          SOURCE_EVENT,
+          { version: 1, type: "snapshot", config: THEME_SERVER_CONFIG },
+        ];
+        for (const event of events) {
+          yield* publishConfigEvents(socket, [event]);
+          expect(yield* Queue.take(observed)).toEqual(event);
+          const started = yield* Deferred.make<void>();
+          const replay = yield* session.subscribeServerConfig(options).pipe(
+            Stream.tap(() => Deferred.succeed(started, undefined)),
+            Stream.takeUntil((item) => item.type === "keybindingsUpdated"),
+            Stream.runCollect,
+            Effect.forkChild,
+          );
+          yield* Deferred.await(started);
+          // A live end marker makes a missing or stale replay event fail without a timeout.
+          const marker: ServerConfigStreamEventType = {
+            version: 1,
+            type: "keybindingsUpdated",
+            payload: { keybindings: [], issues: [] },
+          };
+          yield* publishConfigEvents(socket, [marker]);
+          expect(yield* Queue.take(observed)).toEqual(marker);
+          const replayed = Array.from(yield* Fiber.join(replay));
+          expect(replayed.slice(1)).toEqual([
+            ...themes,
+            ...(event.type === "snapshot" ? [] : [event]),
+            marker,
+          ]);
+          let projection = applyServerConfigProjection(Option.none(), {
+            version: 1,
+            type: "snapshot",
+            config: SOURCE_SERVER_CONFIG,
+          });
+          projection = applyServerConfigProjection(projection, SOURCE_EVENT);
+          for (const item of replayed) projection = applyServerConfigProjection(projection, item);
+          expect(Option.getOrThrow(projection).config.usageLimitSources).toEqual(
+            event.type === "usageLimitSourcesUpdated" && event.payload.sources.length > 0
+              ? event.payload.sources
+              : undefined,
+          );
+        }
         expect(socket.sent.map((message) => decodeJson(message)).filter(isRpcRequest)).toHaveLength(
           1,
         );
-
-        const fallbackFiber = yield* session
-          .subscribeServerConfig({})
-          .pipe(Stream.runHead, Effect.forkChild);
-        const fallbackRequest = yield* awaitRequest(socket, 1);
-        expect(fallbackRequest).toMatchObject({
-          tag: WS_METHODS.subscribeServerConfig,
-          payload: {},
-        });
-        socket.serverMessage(
-          encodeJson({
-            _tag: "Chunk",
-            requestId: fallbackRequest.id,
-            values: [
-              {
-                version: 1,
-                type: "snapshot",
-                config: ENCODED_THEME_SERVER_CONFIG,
-              },
-            ],
-          }),
-        );
-        expect(yield* Fiber.join(fallbackFiber)).toMatchObject({
-          _tag: "Some",
-          value: { type: "snapshot" },
-        });
       }),
     ),
   );
@@ -546,16 +651,20 @@ describe("RpcSessionFactory", () => {
     ),
   );
 
-  it.effect("recovers a slow subscriber after it misses theme deletion", () =>
+  it.effect("recovers a slow subscriber after it misses theme and usage-source deletion", () =>
     Effect.scoped(
       Effect.gen(function* () {
-        const { factory, sockets } = yield* makeFactory({ environmentThemes: true });
+        const { factory, sockets } = yield* makeFactory({
+          environmentThemes: true,
+          usageLimitSources: true,
+        });
         const session = yield* factory.connect(PREPARED);
         const readyFiber = yield* Effect.forkChild(session.ready);
         const socket = yield* awaitSocket(sockets);
         socket.open();
-        yield* completeInitialConfig(socket, ENCODED_THEME_SERVER_CONFIG, {
+        yield* completeInitialConfig(socket, encodeServerConfig(SOURCE_SERVER_CONFIG), {
           environmentThemes: true,
+          usageLimitSources: true,
         });
         yield* Fiber.join(readyFiber);
 
@@ -563,7 +672,7 @@ describe("RpcSessionFactory", () => {
         const releaseSlowSubscriber = yield* Deferred.make<void>();
         let firstEvent = true;
         const slowSubscriber = yield* session
-          .subscribeServerConfig({ environmentThemes: true })
+          .subscribeServerConfig({ environmentThemes: true, usageLimitSources: true })
           .pipe(
             Stream.mapEffect((event) => {
               if (!firstEvent) return Effect.succeed(event);
@@ -573,7 +682,7 @@ describe("RpcSessionFactory", () => {
                 Effect.as(event),
               );
             }),
-            Stream.take(3),
+            Stream.take(4),
             Stream.runCollect,
             Effect.forkChild,
           );
@@ -612,12 +721,18 @@ describe("RpcSessionFactory", () => {
           type: "settingsUpdated",
           payload: { settings: DEFAULT_SERVER_SETTINGS },
         }));
-        const allEvents = [...themeEvents, ...settingsEvents];
+        const sourceEvents: ServerConfigStreamEventType[] = [
+          SOURCE_EVENT,
+          { version: 1, type: "usageLimitSourcesUpdated", payload: { sources: [] } },
+        ];
+        const allEvents = [...themeEvents, ...sourceEvents, ...settingsEvents];
         const observedByFastSubscriber = yield* Queue.unbounded<ServerConfigStreamEventType>();
-        yield* session.subscribeServerConfig({ environmentThemes: true }).pipe(
-          Stream.runForEach((event) => Queue.offer(observedByFastSubscriber, event)),
-          Effect.forkChild,
-        );
+        yield* session
+          .subscribeServerConfig({ environmentThemes: true, usageLimitSources: true })
+          .pipe(
+            Stream.runForEach((event) => Queue.offer(observedByFastSubscriber, event)),
+            Effect.forkChild,
+          );
         expect((yield* Queue.take(observedByFastSubscriber)).type).toBe("snapshot");
         for (const event of allEvents) {
           yield* publishConfigEvents(socket, [event]);
@@ -630,19 +745,23 @@ describe("RpcSessionFactory", () => {
           "snapshot",
           "snapshot",
           "environmentThemesUpdated",
+          "usageLimitSourcesUpdated",
         ]);
         expect(recovered[2]).toMatchObject({ payload: { themes: [] } });
+        expect(recovered[3]).toMatchObject({ payload: { sources: [] } });
 
         let projection = applyServerConfigProjection(Option.none(), {
           version: 1,
           type: "snapshot",
-          config: THEME_SERVER_CONFIG,
+          config: SOURCE_SERVER_CONFIG,
         });
         projection = applyServerConfigProjection(projection, themeEvents[0]!);
+        projection = applyServerConfigProjection(projection, SOURCE_EVENT);
         for (const event of recovered.slice(1)) {
           projection = applyServerConfigProjection(projection, event);
         }
         expect(Option.getOrThrow(projection).config.environmentThemes).toBeUndefined();
+        expect(Option.getOrThrow(projection).config.usageLimitSources).toBeUndefined();
       }),
     ),
   );
diff --git a/packages/client-runtime/src/rpc/session.ts b/packages/client-runtime/src/rpc/session.ts
index 7d975be5c9d3..d98a88100daa 100644
--- a/packages/client-runtime/src/rpc/session.ts
+++ b/packages/client-runtime/src/rpc/session.ts
@@ -54,6 +54,7 @@ export interface RpcSession {
 
 export interface RpcSessionOptions {
   readonly environmentThemes?: boolean;
+  readonly usageLimitSources?: boolean;
 }
 
 export class RpcSessionFactory extends Context.Service<
@@ -83,11 +84,16 @@ type EnvironmentThemesUpdatedEvent = Extract<
   ServerConfigStreamEvent,
   { readonly type: "environmentThemesUpdated" }
 >;
+type UsageLimitSourcesUpdatedEvent = Extract<
+  ServerConfigStreamEvent,
+  { readonly type: "usageLimitSourcesUpdated" }
+>;
 
 interface ServerConfigReplayState {
   readonly projection: ServerConfigProjection;
   readonly revision: number;
   readonly themesEvent: EnvironmentThemesUpdatedEvent | undefined;
+  readonly sourcesEvent: UsageLimitSourcesUpdatedEvent | undefined;
 }
 
 interface BufferedServerConfigEvent {
@@ -104,7 +110,11 @@ function serverConfigReplayEvents(
     type: "snapshot" as const,
     config: withoutEnvironmentThemes(state.projection.config),
   };
-  return state.themesEvent === undefined ? [snapshot] : [snapshot, state.themesEvent];
+  return [
+    snapshot,
+    ...(state.themesEvent === undefined ? [] : [state.themesEvent]),
+    ...(state.sourcesEvent === undefined ? [] : [state.sourcesEvent]),
+  ];
 }
 
 function mapSessionRpcError(
@@ -134,8 +144,10 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
   options: RpcSessionOptions = {},
 ) {
   const webSocketConstructor = yield* Socket.WebSocketConstructor;
-  const serverConfigInput: ServerConfigSubscriptionInput =
-    options.environmentThemes === true ? { environmentThemes: true } : {};
+  const serverConfigInput: ServerConfigSubscriptionInput = {
+    ...(options.environmentThemes === true ? { environmentThemes: true } : {}),
+    ...(options.usageLimitSources === true ? { usageLimitSources: true } : {}),
+  };
 
   const connect = Effect.fnUntraced(function* (connection: PreparedConnection) {
     yield* Effect.annotateCurrentSpan({
@@ -218,6 +230,13 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
                       event.config.environment.capabilities.environmentThemes !== true
                     ? undefined
                     : Option.getOrUndefined(current)?.themesEvent,
+              sourcesEvent:
+                event.type === "usageLimitSourcesUpdated"
+                  ? event
+                  : event.type === "snapshot" &&
+                      event.config.environment.capabilities.usageLimitSources !== true
+                    ? undefined
+                    : Option.getOrUndefined(current)?.sourcesEvent,
             } satisfies ServerConfigReplayState;
             return [
               Option.some({ event, replay: next, revision: next.revision }),

From 389bbcc8d9dd5c463668944f7093052301c8a850 Mon Sep 17 00:00:00 2001
From: maria <maria@kuuro.net>
Date: Fri, 4 Sep 2026 17:47:20 -0400
Subject: [PATCH 31/56] fix(web): give toggle thumbs consistent inset spacing
 (#9805)

---
 apps/web/src/components/ui/switch.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/web/src/components/ui/switch.tsx b/apps/web/src/components/ui/switch.tsx
index 0d45c88861e1..267b314caa40 100644
--- a/apps/web/src/components/ui/switch.tsx
+++ b/apps/web/src/components/ui/switch.tsx
@@ -12,7 +12,7 @@ function Switch({
   return (
     <SwitchPrimitive.Root
       className={cn(
-        "inline-flex h-[calc(var(--thumb-size)+2px)] w-[calc(var(--thumb-size)*2-2px)] shrink-0 cursor-pointer items-center rounded-full p-px outline-none transition-[background-color,box-shadow] duration-200 focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background data-checked:bg-primary data-unchecked:bg-input data-disabled:cursor-not-allowed data-disabled:opacity-64",
+        "inline-flex h-[calc(var(--thumb-size)+2px)] w-[calc(var(--thumb-size)*2-2px)] shrink-0 cursor-pointer items-center rounded-full p-[2px] outline-none transition-[background-color,box-shadow] duration-200 focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background data-checked:bg-primary data-unchecked:bg-input data-disabled:cursor-not-allowed data-disabled:opacity-64",
         size === "sm"
           ? "[--thumb-size:--spacing(4)] sm:[--thumb-size:--spacing(3.5)]"
           : "[--thumb-size:--spacing(5)] sm:[--thumb-size:--spacing(4)]",
@@ -24,7 +24,7 @@ function Switch({
     >
       <SwitchPrimitive.Thumb
         className={cn(
-          "pointer-events-none block aspect-square h-full origin-left in-[[role=switch]:active,[data-slot=label]:active,[data-slot=field-label]:active]:not-data-disabled:scale-x-110 in-[[role=switch]:active,[data-slot=label]:active,[data-slot=field-label]:active]:rounded-[var(--thumb-size)/calc(var(--thumb-size)*1.1)] rounded-(--thumb-size) bg-background shadow-sm/5 will-change-transform [transition:translate_.15s,border-radius_.15s,scale_.1s_.1s,transform-origin_.15s] data-checked:origin-[var(--thumb-size)_50%] data-checked:translate-x-[calc(var(--thumb-size)-4px)]",
+          "pointer-events-none block size-[calc(var(--thumb-size)-2px)] shrink-0 origin-left in-[[role=switch]:active,[data-slot=label]:active,[data-slot=field-label]:active]:not-data-disabled:scale-x-110 in-[[role=switch]:active,[data-slot=label]:active,[data-slot=field-label]:active]:rounded-[var(--thumb-size)/calc(var(--thumb-size)*1.1)] rounded-(--thumb-size) bg-background shadow-sm/5 will-change-transform [transition:translate_.15s,border-radius_.15s,scale_.1s_.1s,transform-origin_.15s] data-checked:origin-right data-checked:translate-x-[calc(var(--thumb-size)-4px)]",
         )}
         data-slot="switch-thumb"
       />

From 5a2f3ebf6ee6eab6124ad68272c2fb5d74bc0f5d Mon Sep 17 00:00:00 2001
From: maria <maria@kuuro.net>
Date: Fri, 4 Sep 2026 17:51:40 -0400
Subject: [PATCH 32/56] fix(web): use segmented controls for mode switches
 (#9781)

---
 apps/web/src/components/DiffPanel.tsx         |  9 ++--
 apps/web/src/components/GitActionsControl.tsx | 42 +++++++++----------
 .../pullRequest/PullRequestCodeTab.tsx        |  9 ++--
 .../pullRequest/PullRequestMarkdownEditor.tsx | 32 +++++++-------
 .../settings/DiagnosticsSettings.tsx          | 27 ++++++------
 .../settings/ProviderSettingsPanel.tsx        | 25 ++++++-----
 .../settings/ResourceTelemetryDiagnostics.tsx | 25 +++++------
 .../components/settings/ThemeEditorPanel.tsx  | 31 ++++++++------
 .../settings/providerSettingsTabs.ts          | 10 -----
 apps/web/src/components/ui/toggle-group.tsx   |  2 +-
 10 files changed, 106 insertions(+), 106 deletions(-)
 delete mode 100644 apps/web/src/components/settings/providerSettingsTabs.ts

diff --git a/apps/web/src/components/DiffPanel.tsx b/apps/web/src/components/DiffPanel.tsx
index bad0e1b4ffe0..87f5f1ba56f8 100644
--- a/apps/web/src/components/DiffPanel.tsx
+++ b/apps/web/src/components/DiffPanel.tsx
@@ -800,8 +800,9 @@ export default function DiffPanel({
           </Tooltip>
         )}
         <ToggleGroup
-          className="shrink-0 gap-1"
-          size="sm"
+          aria-label="Diff layout"
+          className="shrink-0"
+          variant="segmented"
           value={[diffLayout]}
           onValueChange={(value) => {
             const next = value[0];
@@ -810,10 +811,10 @@ export default function DiffPanel({
             }
           }}
         >
-          <Toggle aria-label="Stacked diff view" value="stacked" variant="ghost">
+          <Toggle aria-label="Stacked diff view" value="stacked">
             <Rows3Icon className="size-3.5" />
           </Toggle>
-          <Toggle aria-label="Split diff view" value="split" variant="ghost">
+          <Toggle aria-label="Split diff view" value="split">
             <Columns2Icon className="size-3.5" />
           </Toggle>
         </ToggleGroup>
diff --git a/apps/web/src/components/GitActionsControl.tsx b/apps/web/src/components/GitActionsControl.tsx
index 341444324e73..b7fc811d5127 100644
--- a/apps/web/src/components/GitActionsControl.tsx
+++ b/apps/web/src/components/GitActionsControl.tsx
@@ -42,6 +42,7 @@ import { Radio as RadioPrimitive } from "@base-ui/react/radio";
 import { AzureDevOpsIcon, BitbucketIcon, GitHubIcon, GitLabIcon } from "~/components/Icons";
 import { RadioGroup } from "~/components/ui/radio-group";
 import { Spinner } from "~/components/ui/spinner";
+import { toggleVariants } from "~/components/ui/toggle";
 import { cn } from "~/lib/utils";
 import {
   buildGitActionProgressStages,
@@ -831,32 +832,29 @@ function PublishRepositoryDialog(props: PublishRepositoryDialogProps) {
                           Protocol
                         </span>
                         <RadioGroup
+                          className="w-fit flex-row gap-0.5 rounded-lg bg-input/40 p-0.5"
                           value={publishProtocol}
-                          onValueChange={(value) =>
-                            setPublishProtocol(value as SourceControlCloneProtocol)
-                          }
+                          onValueChange={(protocol) => {
+                            if (protocol === "ssh" || protocol === "https") {
+                              setPublishProtocol(protocol);
+                            }
+                          }}
                           aria-labelledby="publish-protocol-label"
                           disabled={publishRepositoryAction.isPending}
-                          className="grid grid-cols-2 gap-2"
                         >
-                          {(["ssh", "https"] as const).map((value) => {
-                            const isSelected = publishProtocol === value;
-                            return (
-                              <RadioPrimitive.Root
-                                key={value}
-                                value={value}
-                                className={cn(
-                                  "rounded-md border px-3 py-1.5 text-center text-sm font-medium outline-none transition",
-                                  "focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
-                                  isSelected
-                                    ? "border-primary bg-background ring-2 ring-primary/35 text-foreground dark:border-transparent dark:bg-primary/10 dark:ring-1 dark:ring-primary/30"
-                                    : "border-border bg-background text-muted-foreground hover:border-foreground/20 hover:text-foreground dark:border-transparent dark:bg-white/[0.035]",
-                                )}
-                              >
-                                {value === "ssh" ? "SSH" : "HTTPS"}
-                              </RadioPrimitive.Root>
-                            );
-                          })}
+                          {(["ssh", "https"] as const).map((protocol) => (
+                            <RadioPrimitive.Root
+                              key={protocol}
+                              value={protocol}
+                              data-pressed={publishProtocol === protocol ? "" : undefined}
+                              className={toggleVariants({
+                                variant: "segmented",
+                                size: "segmented",
+                              })}
+                            >
+                              {protocol.toUpperCase()}
+                            </RadioPrimitive.Root>
+                          ))}
                         </RadioGroup>
                       </div>
                     </div>
diff --git a/apps/web/src/components/pullRequest/PullRequestCodeTab.tsx b/apps/web/src/components/pullRequest/PullRequestCodeTab.tsx
index 506d59dc6457..aa2d278ce249 100644
--- a/apps/web/src/components/pullRequest/PullRequestCodeTab.tsx
+++ b/apps/web/src/components/pullRequest/PullRequestCodeTab.tsx
@@ -1138,8 +1138,9 @@ export function PullRequestCodeTab({
           </Tooltip>
         ) : null}
         <ToggleGroup
-          className="shrink-0 gap-1"
-          size="sm"
+          aria-label="Diff layout"
+          className="shrink-0"
+          variant="segmented"
           value={[diffLayout]}
           onValueChange={(value) => {
             const next = value[0];
@@ -1148,10 +1149,10 @@ export function PullRequestCodeTab({
             }
           }}
         >
-          <Toggle aria-label="Stacked diff view" value="stacked" variant="ghost">
+          <Toggle aria-label="Stacked diff view" value="stacked">
             <Rows3Icon className="size-3.5" />
           </Toggle>
-          <Toggle aria-label="Split diff view" value="split" variant="ghost">
+          <Toggle aria-label="Split diff view" value="split">
             <Columns2Icon className="size-3.5" />
           </Toggle>
         </ToggleGroup>
diff --git a/apps/web/src/components/pullRequest/PullRequestMarkdownEditor.tsx b/apps/web/src/components/pullRequest/PullRequestMarkdownEditor.tsx
index 5fbffdd08d3d..fde29d023774 100644
--- a/apps/web/src/components/pullRequest/PullRequestMarkdownEditor.tsx
+++ b/apps/web/src/components/pullRequest/PullRequestMarkdownEditor.tsx
@@ -5,6 +5,7 @@ import { cn } from "~/lib/utils";
 
 import { Button } from "../ui/button";
 import { Textarea } from "../ui/textarea";
+import { Toggle, ToggleGroup } from "../ui/toggle-group";
 import { PullRequestMarkdown } from "./PullRequestMarkdown";
 
 /**
@@ -64,24 +65,19 @@ export function PullRequestMarkdownEditor({
         onCancel();
       }}
     >
-      <div className="flex items-center gap-1">
-        <Button
-          size="xs"
-          variant={preview ? "ghost" : "outline"}
-          disabled={saving}
-          onClick={() => setPreview(false)}
-        >
-          Write
-        </Button>
-        <Button
-          size="xs"
-          variant={preview ? "outline" : "ghost"}
-          disabled={saving}
-          onClick={() => setPreview(true)}
-        >
-          Preview
-        </Button>
-      </div>
+      <ToggleGroup
+        aria-label="Markdown editor mode"
+        variant="segmented"
+        value={[preview ? "preview" : "write"]}
+        disabled={saving}
+        onValueChange={(next) => {
+          const mode = next[0];
+          if (mode === "write" || mode === "preview") setPreview(mode === "preview");
+        }}
+      >
+        <Toggle value="write">Write</Toggle>
+        <Toggle value="preview">Preview</Toggle>
+      </ToggleGroup>
       {preview ? (
         <div className="rounded-lg border border-border/60 px-3 py-2">
           {empty ? (
diff --git a/apps/web/src/components/settings/DiagnosticsSettings.tsx b/apps/web/src/components/settings/DiagnosticsSettings.tsx
index b53dc5b8cb38..0b23fb2d2072 100644
--- a/apps/web/src/components/settings/DiagnosticsSettings.tsx
+++ b/apps/web/src/components/settings/DiagnosticsSettings.tsx
@@ -36,6 +36,7 @@ import { usePrimaryEnvironment } from "../../state/environments";
 import { useCopyToClipboard } from "../../hooks/useCopyToClipboard";
 import { Button } from "../ui/button";
 import { ScrollArea } from "../ui/scroll-area";
+import { Toggle, ToggleGroup } from "../ui/toggle-group";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
 import { toastManager } from "../ui/toast";
 import { ExpandableText } from "./ExpandableText";
@@ -599,21 +600,23 @@ function ResourceHistoryWindowSelector({
   onSelect: (windowMs: number) => void;
 }) {
   return (
-    <div className="flex items-center rounded-md border border-border/60 p-0.5">
+    <ToggleGroup
+      aria-label="Process history period"
+      variant="segmented"
+      value={[String(selectedWindowMs)]}
+      onValueChange={(next) => {
+        const selected = RESOURCE_HISTORY_WINDOWS.find(
+          (option) => String(option.windowMs) === next[0],
+        );
+        if (selected) onSelect(selected.windowMs);
+      }}
+    >
       {RESOURCE_HISTORY_WINDOWS.map((option) => (
-        <button
-          key={option.windowMs}
-          type="button"
-          className={cn(
-            "cursor-pointer h-6 rounded-sm px-2 text-[11px] font-medium text-muted-foreground hover:text-foreground",
-            selectedWindowMs === option.windowMs && "bg-muted text-foreground",
-          )}
-          onClick={() => onSelect(option.windowMs)}
-        >
+        <Toggle key={option.windowMs} value={String(option.windowMs)}>
           {option.label}
-        </button>
+        </Toggle>
       ))}
-    </div>
+    </ToggleGroup>
   );
 }
 
diff --git a/apps/web/src/components/settings/ProviderSettingsPanel.tsx b/apps/web/src/components/settings/ProviderSettingsPanel.tsx
index 1bb1b512e4a2..e5575ee9f785 100644
--- a/apps/web/src/components/settings/ProviderSettingsPanel.tsx
+++ b/apps/web/src/components/settings/ProviderSettingsPanel.tsx
@@ -72,6 +72,7 @@ import {
   NumberFieldInput,
 } from "../ui/number-field";
 import { ScrollArea } from "../ui/scroll-area";
+import { Toggle, ToggleGroup } from "../ui/toggle-group";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
 import { stackedThreadToast, toastManager } from "../ui/toast";
 import { AddProviderInstanceDialog } from "./AddProviderInstanceDialog";
@@ -80,7 +81,6 @@ import { ProviderInstanceCard } from "./ProviderInstanceCard";
 import { UsageProviderSettings } from "./UsageProviderSettings";
 import { ProviderSetupSection, readAntigravityAuthMethod } from "./ProviderSetupSection";
 import { DRIVER_OPTIONS, getDriverOption } from "./providerDriverMeta";
-import { providerSettingsTabClassName } from "./providerSettingsTabs";
 import { searchableSetting } from "./settingsSearch";
 import {
   backgroundActivityOverrideSettings,
@@ -326,22 +326,25 @@ function ProviderSettingsPanelContent(target: ProviderSettingsTarget) {
   const deviceTabs =
     !onlyPrimaryDevice && options.length > 0 ? (
       <ScrollArea hideScrollbars scrollFade className="h-11 min-w-0 flex-1 rounded-none">
-        <div role="group" aria-label="Devices" className="flex h-full w-max min-w-full px-1">
+        <ToggleGroup
+          aria-label="Devices"
+          variant="segmented"
+          className="my-2"
+          value={effectiveEnvironmentId ? [effectiveEnvironmentId] : []}
+          onValueChange={(next) => {
+            const environment = options.find((option) => option.environmentId === next[0]);
+            if (environment) setSelectedEnvironmentId(environment.environmentId);
+          }}
+        >
           {options.map((environment) => {
             const machine = resolveEnvironmentMachineKind(environment.serverConfig);
-            const selected = environment.environmentId === effectiveEnvironmentId;
             const detail = providerEnvironmentDetail(environment);
             const statusText = connectionStatusTitle(environment.connection);
             return (
               <Tooltip key={environment.environmentId}>
                 <TooltipTrigger
                   render={
-                    <button
-                      type="button"
-                      aria-pressed={selected}
-                      className={cn(providerSettingsTabClassName(selected), "gap-2 text-left")}
-                      onClick={() => setSelectedEnvironmentId(environment.environmentId)}
-                    >
+                    <Toggle value={environment.environmentId} className="gap-2 text-left">
                       <EnvironmentMachineIcon
                         kind={machine}
                         className="size-3.5 shrink-0"
@@ -357,7 +360,7 @@ function ProviderSettingsPanelContent(target: ProviderSettingsTarget) {
                       <span className="sr-only">
                         {detail}, {statusText}
                       </span>
-                    </button>
+                    </Toggle>
                   }
                 />
                 <TooltipPopup side="top">
@@ -366,7 +369,7 @@ function ProviderSettingsPanelContent(target: ProviderSettingsTarget) {
               </Tooltip>
             );
           })}
-        </div>
+        </ToggleGroup>
       </ScrollArea>
     ) : null;
 
diff --git a/apps/web/src/components/settings/ResourceTelemetryDiagnostics.tsx b/apps/web/src/components/settings/ResourceTelemetryDiagnostics.tsx
index 741cd3c3f37f..ca934952f8a9 100644
--- a/apps/web/src/components/settings/ResourceTelemetryDiagnostics.tsx
+++ b/apps/web/src/components/settings/ResourceTelemetryDiagnostics.tsx
@@ -45,6 +45,7 @@ import { useAtomCommand } from "../../state/use-atom-command";
 import { formatRelativeTime } from "../../timestampFormat";
 import { Button } from "../ui/button";
 import { ScrollArea } from "../ui/scroll-area";
+import { Toggle, ToggleGroup } from "../ui/toggle-group";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
 import { toastManager } from "../ui/toast";
 import {
@@ -378,21 +379,21 @@ function HistoryWindowSelector({
   onSelect: (windowMs: number) => void;
 }) {
   return (
-    <div className="flex items-center rounded-md border border-border/60 p-0.5">
+    <ToggleGroup
+      aria-label="Resource history period"
+      variant="segmented"
+      value={[String(selectedWindowMs)]}
+      onValueChange={(next) => {
+        const selected = HISTORY_WINDOWS.find((option) => String(option.windowMs) === next[0]);
+        if (selected) onSelect(selected.windowMs);
+      }}
+    >
       {HISTORY_WINDOWS.map((option) => (
-        <button
-          key={option.windowMs}
-          type="button"
-          className={cn(
-            "cursor-pointer h-6 rounded-sm px-2 text-[11px] font-medium text-muted-foreground hover:text-foreground",
-            selectedWindowMs === option.windowMs && "bg-muted text-foreground",
-          )}
-          onClick={() => onSelect(option.windowMs)}
-        >
+        <Toggle key={option.windowMs} value={String(option.windowMs)}>
           {option.label}
-        </button>
+        </Toggle>
       ))}
-    </div>
+    </ToggleGroup>
   );
 }
 
diff --git a/apps/web/src/components/settings/ThemeEditorPanel.tsx b/apps/web/src/components/settings/ThemeEditorPanel.tsx
index 4e85bc8806e8..02d1dad458f1 100644
--- a/apps/web/src/components/settings/ThemeEditorPanel.tsx
+++ b/apps/web/src/components/settings/ThemeEditorPanel.tsx
@@ -38,6 +38,7 @@ import { cn } from "../../lib/utils";
 import { Button } from "../ui/button";
 import { Input } from "../ui/input";
 import { Switch } from "../ui/switch";
+import { Toggle, ToggleGroup } from "../ui/toggle-group";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
 import { getThemeRoleLabel, ThemeColorField } from "./ThemeColorPicker";
 import {
@@ -942,24 +943,17 @@ export function ThemeEditorPanel({
   );
 
   const renderAppearanceButton = (appearance: ThemeAppearance) => {
-    const isActive = activeAppearance === appearance;
     const lockReason = appearanceLockReason(appearance);
     // A locked mode stays hoverable so the tooltip can say why it is off;
     // a real disabled attribute would swallow the pointer events.
     const button = (
-      <Button
+      <Toggle
         aria-disabled={lockReason !== null}
-        aria-pressed={isActive}
-        size="sm"
+        value={appearance}
         className={lockReason !== null ? "opacity-50" : undefined}
-        style={isActive ? { boxShadow: "inset 0 0 0 1px var(--ring)" } : undefined}
-        variant={isActive ? "secondary" : "outline"}
-        onClick={() => {
-          if (lockReason === null) setActiveAppearance(appearance);
-        }}
       >
         {appearance === "light" ? "Light" : "Dark"}
-      </Button>
+      </Toggle>
     );
     if (lockReason === null) return button;
     return (
@@ -973,10 +967,23 @@ export function ThemeEditorPanel({
   const renderAppearanceButtons = () => (
     <div className="grid grid-cols-[minmax(0,1fr)_minmax(0,2fr)] items-center gap-3">
       <span className="text-sm font-medium">Appearance</span>
-      <div aria-label="Theme appearance" className="grid grid-cols-2 gap-2" role="group">
+      <ToggleGroup
+        aria-label="Theme appearance"
+        variant="segmented"
+        value={[activeAppearance]}
+        onValueChange={(next) => {
+          const appearance = next[0];
+          if (
+            (appearance === "light" || appearance === "dark") &&
+            appearanceLockReason(appearance) === null
+          ) {
+            setActiveAppearance(appearance);
+          }
+        }}
+      >
         {renderAppearanceButton("light")}
         {renderAppearanceButton("dark")}
-      </div>
+      </ToggleGroup>
     </div>
   );
 
diff --git a/apps/web/src/components/settings/providerSettingsTabs.ts b/apps/web/src/components/settings/providerSettingsTabs.ts
deleted file mode 100644
index 1c4e828bacd9..000000000000
--- a/apps/web/src/components/settings/providerSettingsTabs.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-import { cn } from "../../lib/utils";
-
-export function providerSettingsTabClassName(selected: boolean): string {
-  return cn(
-    "relative flex h-full shrink-0 cursor-pointer items-center rounded-sm px-3 text-xs font-medium outline-none transition-colors focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset",
-    selected
-      ? "text-foreground after:absolute after:inset-x-0 after:bottom-0 after:h-0.5 after:bg-primary"
-      : "text-muted-foreground hover:text-foreground",
-  );
-}
diff --git a/apps/web/src/components/ui/toggle-group.tsx b/apps/web/src/components/ui/toggle-group.tsx
index ae10fe81611f..23501ec7a96c 100644
--- a/apps/web/src/components/ui/toggle-group.tsx
+++ b/apps/web/src/components/ui/toggle-group.tsx
@@ -16,7 +16,7 @@ const ToggleGroupContext = React.createContext<VariantProps<typeof toggleVariant
 
 function ToggleGroup({
   className,
-  variant = "default",
+  variant = "segmented",
   size = variant === "segmented" ? "segmented" : "default",
   orientation = "horizontal",
   children,

From b906ce2d73d025e801877f42a35b7a2f5629806f Mon Sep 17 00:00:00 2001
From: maria <maria@kuuro.net>
Date: Fri, 4 Sep 2026 18:35:42 -0400
Subject: [PATCH 33/56] fix(server): recover opted-in threads after machine
 restarts (#9803)

---
 .../settings/DesktopClientSettings.test.ts    |   1 -
 .../provider/Layers/ProviderService.test.ts   | 119 ++++
 .../src/provider/Layers/ProviderService.ts    |  17 +
 .../serverRuntimeStartup.reconcile.test.ts    | 629 +++++++++++++-----
 apps/server/src/serverRuntimeStartup.ts       |  83 ++-
 .../components/ServerUpdateAction.test.tsx    |   3 +-
 .../web/src/components/ServerUpdateAction.tsx |   5 +-
 .../components/settings/SettingsPanels.tsx    |   9 +-
 .../src/components/settings/settingsSearch.ts |   6 +-
 docs/user/updating.md                         |  10 +-
 packages/contracts/src/settings.ts            |   9 +-
 11 files changed, 708 insertions(+), 183 deletions(-)

diff --git a/apps/desktop/src/settings/DesktopClientSettings.test.ts b/apps/desktop/src/settings/DesktopClientSettings.test.ts
index 28cce3cfb507..0d9ddc8fde91 100644
--- a/apps/desktop/src/settings/DesktopClientSettings.test.ts
+++ b/apps/desktop/src/settings/DesktopClientSettings.test.ts
@@ -26,7 +26,6 @@ const clientSettings: ClientSettings = {
   confirmThreadArchive: true,
   confirmThreadDelete: false,
   confirmThreadUnpin: false,
-  continueThreadsAfterServerUpdate: true,
   contextWindowMeterEnabled: false,
   composerCollapseOnBlur: false,
   composerCollapseOnScroll: true,
diff --git a/apps/server/src/provider/Layers/ProviderService.test.ts b/apps/server/src/provider/Layers/ProviderService.test.ts
index 5e59960685a7..95e5a7983346 100644
--- a/apps/server/src/provider/Layers/ProviderService.test.ts
+++ b/apps/server/src/provider/Layers/ProviderService.test.ts
@@ -452,6 +452,125 @@ function makeProviderServiceLayer(
   };
 }
 
+for (const [enabled, completed] of [
+  [false, false],
+  [true, false],
+  [true, true],
+] as const) {
+  it.effect(
+    `persists shutdown recovery before stopping providers when enabled=${enabled}, completed=${completed}`,
+    () =>
+      Effect.gen(function* () {
+        const codex = makeFakeCodexAdapter();
+        const persistence = yield* Layer.build(
+          ProviderSessionDirectoryLive.pipe(
+            Layer.provide(
+              ProviderSessionRuntime.layer.pipe(Layer.provide(SqlitePersistenceMemory)),
+            ),
+          ),
+        );
+        const directory = yield* ProviderSessionDirectory.ProviderSessionDirectory.pipe(
+          Effect.provide(persistence),
+        );
+        const threadId = asThreadId("shutdown-recovery");
+        const turnId = asTurnId("shutdown-recovery-turn");
+        const scope = yield* Scope.make();
+        const services = yield* Layer.build(
+          makeProviderServiceLive().pipe(
+            Layer.provide(
+              Layer.succeed(ProviderSessionDirectory.ProviderSessionDirectory, directory),
+            ),
+            Layer.provide(
+              Layer.succeed(
+                ProviderAdapterRegistry.ProviderAdapterRegistry,
+                makeStaticInstanceRegistry([[codexInstanceId, codex.adapter]]),
+              ),
+            ),
+            Layer.provide(ServerSettings.layerTest({ continueThreadsAfterServerUpdate: enabled })),
+            Layer.provide(serverConfigTestLayer),
+            Layer.provide(AnalyticsService.layerTest),
+            Layer.provide(
+              Layer.succeed(
+                ProviderEventLoggers.ProviderEventLoggers,
+                ProviderEventLoggers.NoOpProviderEventLoggers,
+              ),
+            ),
+          ),
+        ).pipe(Scope.provide(scope));
+        const provider = yield* ProviderService.ProviderService.pipe(Effect.provide(services));
+        const session = yield* provider.startSession(threadId, {
+          provider: CODEX_DRIVER,
+          providerInstanceId: codexInstanceId,
+          threadId,
+          runtimeMode: "full-access",
+        });
+        codex.listSessions.mockReturnValue(
+          Effect.succeed([
+            {
+              ...session,
+              status: completed ? "ready" : "running",
+              activeTurnId: completed ? undefined : turnId,
+            },
+          ]),
+        );
+        const pending = yield* directory.getBinding(threadId);
+        assert(Option.isSome(pending));
+        yield* directory.upsert({
+          ...pending.value,
+          runtimePayload: { activeTurnId: null, continueAfterServerUpdate: turnId },
+        });
+        const accepted = yield* provider.sendTurn({ threadId, continuation: true });
+        const admitted = yield* directory.getBinding(threadId);
+        assert(Option.isSome(admitted));
+        assert.propertyVal(admitted.value.runtimePayload, "activeTurnId", accepted.turnId);
+        assert.propertyVal(admitted.value.runtimePayload, "continueAfterServerUpdate", null);
+        if (completed) {
+          // Updates can mark an already-admitted turn immediately before it finishes.
+          yield* directory.upsert({
+            ...admitted.value,
+            runtimePayload: {
+              continueAfterServerUpdate: accepted.turnId,
+              continueAfterServerUpdatePrepared: null,
+            },
+          });
+        }
+        const markers: unknown[] = [];
+        codex.stopAll.mockImplementation(() =>
+          Effect.gen(function* () {
+            const binding = yield* directory.getBinding(threadId);
+            assert(Option.isSome(binding));
+            markers.push(binding.value.runtimePayload);
+          }).pipe(Effect.orDie),
+        );
+        yield* Scope.close(scope, Exit.void);
+        const binding = yield* directory.getBinding(threadId);
+        assert(Option.isSome(binding));
+        assert.equal(codex.stopAll.mock.calls.length, 1);
+        assert.deepStrictEqual(binding.value.resumeCursor, session.resumeCursor);
+        assert.equal(binding.value.status, "stopped");
+        assert.propertyVal(markers[0], "activeTurnId", completed ? null : turnId);
+        if (enabled && !completed) {
+          assert.propertyVal(markers[0], "continueAfterServerUpdate", turnId);
+          assert.propertyVal(binding.value.runtimePayload, "continueAfterServerUpdate", turnId);
+        } else if (completed) {
+          assert.propertyVal(
+            binding.value.runtimePayload,
+            "continueAfterServerUpdate",
+            accepted.turnId,
+          );
+          assert.propertyVal(
+            binding.value.runtimePayload,
+            "continueAfterServerUpdatePrepared",
+            null,
+          );
+        } else {
+          assert.propertyVal(markers[0], "continueAfterServerUpdate", null);
+          assert.propertyVal(binding.value.runtimePayload, "continueAfterServerUpdate", null);
+        }
+      }).pipe(Effect.provide(NodeServices.layer)),
+  );
+}
+
 it.effect("ProviderServiceLive catches stopAll failures during shutdown", () =>
   Effect.gen(function* () {
     const codex = makeFakeCodexAdapter();
diff --git a/apps/server/src/provider/Layers/ProviderService.ts b/apps/server/src/provider/Layers/ProviderService.ts
index 2098cacda5eb..cf9d9b395d5b 100644
--- a/apps/server/src/provider/Layers/ProviderService.ts
+++ b/apps/server/src/provider/Layers/ProviderService.ts
@@ -223,6 +223,7 @@ function toRuntimePayloadFromSession(
   session: ProviderSession,
   extra?: {
     readonly modelSelection?: unknown;
+    readonly continueAfterServerUpdate?: TurnId;
     readonly lastRuntimeEvent?: string;
     readonly lastRuntimeEventAt?: string;
   },
@@ -232,6 +233,9 @@ function toRuntimePayloadFromSession(
     model: session.model ?? null,
     activeTurnId: session.activeTurnId ?? null,
     lastError: session.lastError ?? null,
+    ...(extra?.continueAfterServerUpdate !== undefined
+      ? { continueAfterServerUpdate: extra.continueAfterServerUpdate }
+      : {}),
     ...(extra?.modelSelection !== undefined ? { modelSelection: extra.modelSelection } : {}),
     ...(extra?.lastRuntimeEvent !== undefined ? { lastRuntimeEvent: extra.lastRuntimeEvent } : {}),
     ...(extra?.lastRuntimeEventAt !== undefined
@@ -831,6 +835,7 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
     threadId: ThreadId,
     extra?: {
       readonly modelSelection?: unknown;
+      readonly continueAfterServerUpdate?: TurnId;
       readonly lastRuntimeEvent?: string;
       readonly lastRuntimeEventAt?: string;
     },
@@ -1433,6 +1438,9 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
         runtimePayload: {
           ...(input.modelSelection !== undefined ? { modelSelection: input.modelSelection } : {}),
           activeTurnId: turn.turnId,
+          // Admission and marker consumption must survive the same restart.
+          continueAfterServerUpdate: null,
+          continueAfterServerUpdatePrepared: null,
           lastRuntimeEvent: "provider.sendTurn",
           lastRuntimeEventAt: yield* nowIso,
         },
@@ -1733,6 +1741,8 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
           status: "stopped",
           runtimePayload: {
             activeTurnId: null,
+            continueAfterServerUpdate: null,
+            continueAfterServerUpdatePrepared: null,
           },
         });
         yield* analytics.record("provider.session.stopped", {
@@ -1942,6 +1952,10 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
   );
 
   const runStopAll = Effect.fn("runStopAll")(function* () {
+    const continueAfterRestart = yield* serverSettings.getSettings.pipe(
+      Effect.map((settings) => settings.continueThreadsAfterServerUpdate),
+      Effect.orElseSucceed(() => false),
+    );
     const properties = yield* Ref.modify(turnAnalytics, (state) => {
       const completed: Array<Readonly<Record<string, unknown>>> = [];
       for (const [sessionKey, session] of state.sessions) {
@@ -1969,6 +1983,9 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
     yield* Effect.forEach(activeSessions, (session) =>
       Effect.flatMap(nowIso, (lastRuntimeEventAt) =>
         upsertSessionBinding(session, session.threadId, {
+          ...(continueAfterRestart && session.status === "running" && session.activeTurnId
+            ? { continueAfterServerUpdate: session.activeTurnId }
+            : {}),
           lastRuntimeEvent: "provider.stopAll",
           lastRuntimeEventAt,
         }),
diff --git a/apps/server/src/serverRuntimeStartup.reconcile.test.ts b/apps/server/src/serverRuntimeStartup.reconcile.test.ts
index 39c284330d46..2c95a6163acd 100644
--- a/apps/server/src/serverRuntimeStartup.reconcile.test.ts
+++ b/apps/server/src/serverRuntimeStartup.reconcile.test.ts
@@ -1,6 +1,7 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import {
   type OrchestrationCommand,
+  type OrchestrationSessionStatus,
   ProviderDriverKind,
   ProviderInstanceId,
   type ProviderSendTurnInput,
@@ -10,15 +11,21 @@ import {
 import { assert, it } from "@effect/vitest";
 import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import * as Stream from "effect/Stream";
 
 import { OrchestrationCommandInvariantError } from "./orchestration/Errors.ts";
 import * as OrchestrationEngine from "./orchestration/Services/OrchestrationEngine.ts";
 import * as ProjectionSnapshotQuery from "./orchestration/Services/ProjectionSnapshotQuery.ts";
-import { ProviderSessionDirectoryPersistenceError } from "./provider/Errors.ts";
+import {
+  ProviderSessionDirectoryPersistenceError,
+  ProviderSessionNotFoundError,
+} from "./provider/Errors.ts";
 import * as ProviderService from "./provider/Services/ProviderService.ts";
 import * as ProviderSessionDirectory from "./provider/Services/ProviderSessionDirectory.ts";
+import { ServerActivation } from "./serverActivation.ts";
+import * as ServerSettings from "./serverSettings.ts";
 import * as ServerRuntimeStartup from "./serverRuntimeStartup.ts";
 
 const providerInstanceId = ProviderInstanceId.make("codex");
@@ -26,7 +33,7 @@ const updatedAt = "2026-08-20T12:00:00.000Z";
 
 const makeThread = (
   id: string,
-  status: "starting" | "running" | "ready" | "stopped" | "error",
+  status: OrchestrationSessionStatus,
   activeTurnId: TurnId | null = null,
   archivedAt: string | null = null,
   deletedAt: string | null = null,
@@ -73,6 +80,7 @@ const queryWithThreads = (threads: ReadonlyArray<ReturnType<typeof makeThread>>)
 
 const runReconciliation = (input: {
   readonly threads: ReadonlyArray<ReturnType<typeof makeThread>>;
+  readonly continueAfterRestart?: boolean;
   readonly liveThreadIds?: ReadonlyArray<ThreadId>;
   readonly providerService?: ProviderService.ProviderService["Service"];
   readonly directory: ProviderSessionDirectory.ProviderSessionDirectory["Service"];
@@ -97,7 +105,14 @@ const runReconciliation = (input: {
       subscribeDomainEvents: Effect.succeed(Stream.empty),
       latestSequence: Effect.succeed(0),
     }),
-    Effect.provide(NodeServices.layer),
+    Effect.provide(
+      Layer.mergeAll(
+        ServerSettings.layerTest({
+          continueThreadsAfterServerUpdate: input.continueAfterRestart ?? false,
+        }),
+        NodeServices.layer,
+      ),
+    ),
   );
 
 it.effect("marks active running sessions that have persisted resume state", () => {
@@ -138,7 +153,7 @@ it.effect("marks active running sessions that have persisted resume state", () =
       upsert: (binding) => Effect.sync(() => upserts.push(binding)),
       getProvider: () => Effect.die("unused"),
       listThreadIds: () => Effect.die("unused"),
-      listBindings: () => Effect.die("unused"),
+      listBindings: () => Effect.succeed([]),
     }),
     Effect.tap((marked) =>
       Effect.sync(() => {
@@ -147,169 +162,186 @@ it.effect("marks active running sessions that have persisted resume state", () =
         assert.deepStrictEqual(upserts[0]?.runtimePayload, {
           activeTurnId: "turn-mark-active",
           continueAfterServerUpdate: active.session.activeTurnId,
+          continueAfterServerUpdatePrepared: null,
         });
       }),
     ),
   );
 });
 
-it.effect("continues marked sessions after activation with provider-specific input", () =>
-  Effect.gen(function* () {
-    const codex = makeThread(
-      "thread-continue-codex",
-      "running",
-      TurnId.make("turn-continue-codex"),
-    );
-    const fallback = makeThread("thread-continue-fallback", "starting");
-    const fallbackContinuationTurnId = TurnId.make("turn-continue-fallback");
-    const fallbackProviderInstanceId = ProviderInstanceId.make("claudeAgent");
-    const continuationSent = yield* Deferred.make<void>();
-    const continuationCleared = yield* Deferred.make<void>();
-    const sends: ProviderSendTurnInput[] = [];
-    const dispatched: OrchestrationCommand[] = [];
-    const upserts: ProviderSessionDirectory.ProviderRuntimeBinding[] = [];
-    const bindings = new Map<ThreadId, ProviderSessionDirectory.ProviderRuntimeBinding>(
-      [codex, fallback].map((thread) => [
-        thread.id,
-        {
-          threadId: thread.id,
-          provider:
-            thread.id === codex.id
-              ? ProviderDriverKind.make("codex")
-              : ProviderDriverKind.make("claudeAgent"),
-          providerInstanceId:
-            thread.id === codex.id ? providerInstanceId : fallbackProviderInstanceId,
-          status: "running" as const,
-          runtimePayload: {
-            continueAfterServerUpdate:
-              thread.id === codex.id ? codex.session.activeTurnId : fallbackContinuationTurnId,
+it.effect.each(["marked update", "opt-in restart"] as const)(
+  "continues %s sessions after activation with provider-specific input",
+  (recovery) =>
+    Effect.gen(function* () {
+      const codex = makeThread(
+        "thread-continue-codex",
+        "running",
+        TurnId.make("turn-continue-codex"),
+      );
+      const fallbackContinuationTurnId = TurnId.make("turn-continue-fallback");
+      const fallback = makeThread(
+        "thread-continue-fallback",
+        recovery === "marked update" ? "starting" : "running",
+        recovery === "marked update" ? null : fallbackContinuationTurnId,
+      );
+      const fallbackProviderInstanceId = ProviderInstanceId.make("claudeAgent");
+      const continuationSent = yield* Deferred.make<void>();
+      const continuationCleared = yield* Deferred.make<void>();
+      const sends: ProviderSendTurnInput[] = [];
+      const dispatched: OrchestrationCommand[] = [];
+      const upserts: ProviderSessionDirectory.ProviderRuntimeBinding[] = [];
+      const bindings = new Map<ThreadId, ProviderSessionDirectory.ProviderRuntimeBinding>(
+        [codex, fallback].map((thread) => [
+          thread.id,
+          {
+            threadId: thread.id,
+            provider:
+              thread.id === codex.id
+                ? ProviderDriverKind.make("codex")
+                : ProviderDriverKind.make("claudeAgent"),
+            providerInstanceId:
+              thread.id === codex.id ? providerInstanceId : fallbackProviderInstanceId,
+            status: "running" as const,
+            resumeCursor: { threadId: thread.id },
+            runtimePayload:
+              recovery === "marked update"
+                ? {
+                    continueAfterServerUpdate:
+                      thread.id === codex.id
+                        ? codex.session.activeTurnId
+                        : fallbackContinuationTurnId,
+                  }
+                : { activeTurnId: thread.session.activeTurnId },
           },
-        },
-      ]),
-    );
-    const providerService: ProviderService.ProviderService["Service"] = {
-      ...makeProviderService(),
-      getCapabilities: (instanceId) =>
-        Effect.succeed({
-          sessionModelSwitch: "in-session",
-          ...(instanceId === providerInstanceId ? { promptlessTurnContinuation: true } : {}),
-        }),
-      sendTurn: (input) =>
-        Effect.gen(function* () {
-          sends.push(input);
-          if (sends.length === 2) {
-            yield* Deferred.succeed(continuationSent, undefined);
-          }
-          return {
-            threadId: input.threadId,
-            turnId: TurnId.make(`continued-${String(input.threadId)}`),
-          };
-        }),
-    };
-
-    yield* runReconciliation({
-      threads: [codex, fallback],
-      providerService,
-      directory: {
-        getBinding: (threadId) =>
-          Effect.sync(() => {
-            const binding = bindings.get(threadId);
-            return binding === undefined ? Option.none() : Option.some(binding);
+        ]),
+      );
+      const providerService: ProviderService.ProviderService["Service"] = {
+        ...makeProviderService(),
+        getCapabilities: (instanceId) =>
+          Effect.succeed({
+            sessionModelSwitch: "in-session",
+            ...(instanceId === providerInstanceId ? { promptlessTurnContinuation: true } : {}),
           }),
-        upsert: (binding) =>
-          Effect.sync(() => {
-            bindings.set(binding.threadId, binding);
-            upserts.push(binding);
-            const clearedCount = upserts.filter((candidate) => {
-              const payload = candidate.runtimePayload;
-              return (
-                payload !== null &&
-                typeof payload === "object" &&
-                !Array.isArray(payload) &&
-                "continueAfterServerUpdate" in payload &&
-                payload.continueAfterServerUpdate === null
-              );
-            }).length;
-            return clearedCount === 1;
-          }).pipe(
-            Effect.flatMap((firstMarkerCleared) =>
-              firstMarkerCleared ? Deferred.succeed(continuationCleared, undefined) : Effect.void,
+        sendTurn: (input) =>
+          Effect.gen(function* () {
+            sends.push(input);
+            if (sends.length === 2) {
+              yield* Deferred.succeed(continuationSent, undefined);
+            }
+            return {
+              threadId: input.threadId,
+              turnId: TurnId.make(`continued-${String(input.threadId)}`),
+            };
+          }),
+      };
+
+      yield* runReconciliation({
+        threads: [codex, fallback],
+        continueAfterRestart: recovery === "opt-in restart",
+        providerService,
+        directory: {
+          getBinding: (threadId) =>
+            Effect.sync(() => {
+              const binding = bindings.get(threadId);
+              return binding === undefined ? Option.none() : Option.some(binding);
+            }),
+          upsert: (binding) =>
+            Effect.sync(() => {
+              bindings.set(binding.threadId, binding);
+              upserts.push(binding);
+              const clearedCount = upserts.filter((candidate) => {
+                const payload = candidate.runtimePayload;
+                return (
+                  payload !== null &&
+                  typeof payload === "object" &&
+                  !Array.isArray(payload) &&
+                  "continueAfterServerUpdate" in payload &&
+                  payload.continueAfterServerUpdate === null
+                );
+              }).length;
+              return clearedCount === 1;
+            }).pipe(
+              Effect.flatMap((firstMarkerCleared) =>
+                firstMarkerCleared ? Deferred.succeed(continuationCleared, undefined) : Effect.void,
+              ),
             ),
+          getProvider: () => Effect.die("unused"),
+          listThreadIds: () => Effect.die("unused"),
+          listBindings: () => Effect.succeed([]),
+        },
+        dispatch: (command) =>
+          Effect.sync(() => dispatched.push(command)).pipe(
+            Effect.as({ sequence: dispatched.length }),
           ),
-        getProvider: () => Effect.die("unused"),
-        listThreadIds: () => Effect.die("unused"),
-        listBindings: () => Effect.die("unused"),
-      },
-      dispatch: (command) =>
-        Effect.sync(() => dispatched.push(command)).pipe(
-          Effect.as({ sequence: dispatched.length }),
-        ),
-    });
-    yield* Deferred.await(continuationSent);
-    yield* Deferred.await(continuationCleared);
+      });
+      yield* Deferred.await(continuationSent);
+      yield* Deferred.await(continuationCleared);
 
-    assert.deepStrictEqual(
-      sends.toSorted((left, right) => String(left.threadId).localeCompare(String(right.threadId))),
-      [
-        { threadId: codex.id, continuation: true, interactionMode: "default" },
-        {
-          threadId: fallback.id,
-          input: "Continue where you left off.",
-          interactionMode: "default",
-        },
-      ],
-    );
-    assert.deepStrictEqual(
-      dispatched.map((command) =>
-        command.type === "thread.session.set"
-          ? {
-              threadId: command.threadId,
-              status: command.session.status,
-              activeTurnId: command.session.activeTurnId,
-            }
-          : null,
-      ),
-      [
-        {
-          threadId: codex.id,
-          status: "starting",
-          activeTurnId: null,
-        },
-        {
-          threadId: fallback.id,
-          status: "starting",
-          activeTurnId: fallback.session.activeTurnId,
-        },
-      ],
-    );
-    for (const [thread, continuationTurnId] of [
-      [codex, codex.session.activeTurnId],
-      [fallback, fallbackContinuationTurnId],
-    ] as const) {
       assert.deepStrictEqual(
-        upserts
-          .filter((binding) => binding.threadId === thread.id)
-          .map((binding) => binding.runtimePayload)[0],
-        {
-          continueAfterServerUpdate: continuationTurnId,
-          activeTurnId: null,
-        },
+        sends.toSorted((left, right) =>
+          String(left.threadId).localeCompare(String(right.threadId)),
+        ),
+        [
+          { threadId: codex.id, continuation: true, interactionMode: "default" },
+          {
+            threadId: fallback.id,
+            input: "Continue where you left off.",
+            interactionMode: "default",
+          },
+        ],
+      );
+      assert.deepStrictEqual(
+        dispatched.map((command) =>
+          command.type === "thread.session.set"
+            ? {
+                threadId: command.threadId,
+                status: command.session.status,
+                activeTurnId: command.session.activeTurnId,
+              }
+            : null,
+        ),
+        [
+          {
+            threadId: codex.id,
+            status: "starting",
+            activeTurnId: null,
+          },
+          {
+            threadId: fallback.id,
+            status: "starting",
+            activeTurnId: null,
+          },
+        ],
       );
-    }
-    assert.equal(
-      upserts.some((binding) => {
-        const payload = binding.runtimePayload;
-        return (
-          payload !== null &&
-          typeof payload === "object" &&
-          !Array.isArray(payload) &&
-          "continueAfterServerUpdate" in payload &&
-          payload.continueAfterServerUpdate === null
+      for (const [thread, continuationTurnId] of [
+        [codex, codex.session.activeTurnId],
+        [fallback, fallbackContinuationTurnId],
+      ] as const) {
+        assert.deepStrictEqual(
+          upserts
+            .filter((binding) => binding.threadId === thread.id)
+            .map((binding) => binding.runtimePayload)[0],
+          {
+            continueAfterServerUpdate: continuationTurnId,
+            continueAfterServerUpdatePrepared: true,
+            activeTurnId: null,
+          },
         );
-      }),
-      true,
-    );
-  }),
+      }
+      assert.equal(
+        upserts.some((binding) => {
+          const payload = binding.runtimePayload;
+          return (
+            payload !== null &&
+            typeof payload === "object" &&
+            !Array.isArray(payload) &&
+            "continueAfterServerUpdate" in payload &&
+            payload.continueAfterServerUpdate === null
+          );
+        }),
+        true,
+      );
+    }),
 );
 
 it.effect("does not continue archived or deleted marked sessions", () => {
@@ -361,7 +393,7 @@ it.effect("does not continue archived or deleted marked sessions", () => {
       upsert: () => Effect.void,
       getProvider: () => Effect.die("unused"),
       listThreadIds: () => Effect.die("unused"),
-      listBindings: () => Effect.die("unused"),
+      listBindings: () => Effect.succeed([]),
     },
     dispatch: (command) =>
       Effect.sync(() => dispatched.push(command)).pipe(Effect.as({ sequence: dispatched.length })),
@@ -416,7 +448,7 @@ it.effect("retries continuation preparation before settling a persistent failure
       upsert: () => Effect.void,
       getProvider: () => Effect.die("unused"),
       listThreadIds: () => Effect.die("unused"),
-      listBindings: () => Effect.die("unused"),
+      listBindings: () => Effect.succeed([]),
     },
     dispatch: (command) => {
       if (command.type !== "thread.session.set") {
@@ -487,7 +519,7 @@ it.effect("reconciles multiple active and archived orphans but skips live sessio
       upsert: (binding) => Effect.sync(() => upserts.push(binding)),
       getProvider: () => Effect.die("unused"),
       listThreadIds: () => Effect.die("unused"),
-      listBindings: () => Effect.die("unused"),
+      listBindings: () => Effect.succeed([]),
     },
     dispatch: (command) =>
       Effect.sync(() => dispatched.push(command)).pipe(Effect.as({ sequence: dispatched.length })),
@@ -521,6 +553,7 @@ it.effect("reconciles multiple active and archived orphans but skips live sessio
                   activeTurnId: null,
                   unrelated: binding.threadId,
                   continueAfterServerUpdate: null,
+                  continueAfterServerUpdatePrepared: null,
                 }
               : { activeTurnId: null, unrelated: binding.threadId },
           );
@@ -565,7 +598,7 @@ it.effect(
         upsert: () => Effect.fail(writeFailure),
         getProvider: () => Effect.die("unused"),
         listThreadIds: () => Effect.die("unused"),
-        listBindings: () => Effect.die("unused"),
+        listBindings: () => Effect.succeed([]),
       },
       dispatch: (command) =>
         Effect.sync(() => dispatched.push(command)).pipe(
@@ -602,7 +635,7 @@ it.effect("retries failed projections and continues after a persistent failure",
       upsert: () => Effect.void,
       getProvider: () => Effect.die("unused"),
       listThreadIds: () => Effect.die("unused"),
-      listBindings: () => Effect.die("unused"),
+      listBindings: () => Effect.succeed([]),
     },
     dispatch: (command) => {
       if (command.type !== "thread.session.set") {
@@ -651,7 +684,7 @@ it.effect("does not fail startup when the live provider session inventory cannot
       upsert: () => Effect.die("unused"),
       getProvider: () => Effect.die("unused"),
       listThreadIds: () => Effect.die("unused"),
-      listBindings: () => Effect.die("unused"),
+      listBindings: () => Effect.succeed([]),
     }),
     Effect.provideService(OrchestrationEngine.OrchestrationEngineService, {
       readEvents: () => Stream.empty,
@@ -662,7 +695,283 @@ it.effect("does not fail startup when the live provider session inventory cannot
       subscribeDomainEvents: Effect.succeed(Stream.empty),
       latestSequence: Effect.succeed(0),
     }),
-    Effect.provide(NodeServices.layer),
+    Effect.provide(Layer.mergeAll(NodeServices.layer, ServerSettings.layerTest())),
     Effect.tap(() => Effect.sync(() => assert.equal(queried, false))),
   );
 });
+
+for (const scenario of [
+  "disabled",
+  "stopped projection",
+  "finished projection",
+  "stopped binding",
+  "finished binding",
+  "missing cursor",
+  "mismatched turn",
+  "marked without cursor",
+  "marked stopped projection",
+  "marked superseded turn",
+] as const) {
+  it.effect(`does not recover an interrupted session with ${scenario}`, () => {
+    const turnId = TurnId.make("turn-excluded-recovery");
+    const thread = makeThread(
+      "thread-excluded-recovery",
+      scenario.includes("stopped projection")
+        ? "stopped"
+        : scenario === "finished projection"
+          ? "ready"
+          : scenario === "marked superseded turn"
+            ? "starting"
+            : "running",
+      scenario === "marked superseded turn" ? null : turnId,
+    );
+    const dispatched: OrchestrationCommand[] = [];
+    const upserts: ProviderSessionDirectory.ProviderRuntimeBinding[] = [];
+    return runReconciliation({
+      threads: [thread],
+      continueAfterRestart: scenario !== "disabled",
+      directory: {
+        getBinding: () =>
+          Effect.succeed(
+            Option.some({
+              threadId: thread.id,
+              provider: ProviderDriverKind.make("codex"),
+              providerInstanceId,
+              status: scenario === "stopped binding" ? "stopped" : "running",
+              ...(scenario.includes("cursor") ? {} : { resumeCursor: { threadId: thread.id } }),
+              runtimePayload: {
+                activeTurnId:
+                  scenario === "finished binding"
+                    ? null
+                    : scenario === "mismatched turn" || scenario === "marked superseded turn"
+                      ? "another-turn"
+                      : turnId,
+                ...(scenario.startsWith("marked") ? { continueAfterServerUpdate: turnId } : {}),
+              },
+            }),
+          ),
+        upsert: (binding) =>
+          Effect.sync(() => {
+            upserts.push(binding);
+          }),
+        getProvider: () => Effect.die("unused"),
+        listThreadIds: () => Effect.die("unused"),
+        listBindings: () => Effect.succeed([]),
+      },
+      dispatch: (command) =>
+        Effect.sync(() => {
+          dispatched.push(command);
+          return { sequence: dispatched.length };
+        }),
+    }).pipe(
+      Effect.tap(() =>
+        Effect.sync(() => {
+          assert.deepStrictEqual(
+            dispatched.map(
+              (command) => command.type === "thread.session.set" && command.session.status,
+            ),
+            ["error"],
+          );
+          assert.deepStrictEqual(
+            upserts.map((binding) => binding.status),
+            ["stopped"],
+          );
+        }),
+      ),
+    );
+  });
+}
+
+for (const preparedStatus of [
+  "starting",
+  "ready",
+  "ready with failed scan",
+  "completed after update marking",
+] as const) {
+  it.effect(`recovers again if startup exits with a prepared ${preparedStatus} session`, () =>
+    Effect.gen(function* () {
+      const turnId = TurnId.make("turn-interrupted-startup");
+      const thread = makeThread("thread-interrupted-startup", "running", turnId);
+      const activation = yield* Deferred.make<void>();
+      const cleared = yield* Deferred.make<void>();
+      const sends: ProviderSendTurnInput[] = [];
+      let binding: ProviderSessionDirectory.ProviderRuntimeBinding = {
+        threadId: thread.id,
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId,
+        status: "running",
+        resumeCursor: { threadId: thread.id },
+        runtimePayload: { activeTurnId: turnId },
+      };
+      const input = {
+        threads: [thread],
+        continueAfterRestart: true,
+        providerService: {
+          ...makeProviderService(),
+          getCapabilities: () =>
+            Effect.succeed({
+              sessionModelSwitch: "in-session" as const,
+              promptlessTurnContinuation: true,
+            }),
+          sendTurn: (input: ProviderSendTurnInput) =>
+            Effect.sync(() => {
+              sends.push(input);
+              return { threadId: input.threadId, turnId: TurnId.make("turn-recovered") };
+            }),
+        },
+        directory: {
+          getBinding: () => Effect.sync(() => Option.some(binding)),
+          upsert: (next: ProviderSessionDirectory.ProviderRuntimeBinding) =>
+            Effect.gen(function* () {
+              binding = next;
+              if (binding.status !== "starting" || sends.length === 0) return;
+              yield* Deferred.succeed(cleared, undefined);
+            }),
+          getProvider: () => Effect.die("unused"),
+          listThreadIds: () => Effect.die("unused"),
+          listBindings: () =>
+            preparedStatus === "ready with failed scan"
+              ? Effect.fail(
+                  new ProviderSessionDirectoryPersistenceError({
+                    operation: "listBindings",
+                    detail: "unreadable unrelated binding",
+                  }),
+                )
+              : Effect.sync(() => [{ ...binding, lastSeenAt: "2026-01-01T00:00:00.000Z" }]),
+        },
+        dispatch: (command: OrchestrationCommand) =>
+          Effect.sync(() => {
+            if (command.type === "thread.session.set") {
+              thread.session.status = command.session.status;
+              thread.session.activeTurnId = command.session.activeTurnId;
+            }
+            return { sequence: 1 };
+          }),
+      };
+
+      yield* runReconciliation(input).pipe(
+        Effect.provideService(ServerActivation, Deferred.await(activation)),
+        Effect.scoped,
+      );
+      assert.deepStrictEqual(sends, []);
+      assert.equal(thread.session.status, "starting");
+      assert.equal(thread.session.activeTurnId, null);
+      assert.deepStrictEqual(binding.runtimePayload, {
+        activeTurnId: null,
+        continueAfterServerUpdate: turnId,
+        continueAfterServerUpdatePrepared: true,
+      });
+
+      if (preparedStatus === "completed after update marking") {
+        thread.session.status = "ready";
+        binding = {
+          ...binding,
+          status: "stopped",
+          runtimePayload: {
+            activeTurnId: null,
+            continueAfterServerUpdate: turnId,
+            continueAfterServerUpdatePrepared: null,
+          },
+        };
+        yield* runReconciliation(input);
+        assert.deepStrictEqual(sends, []);
+        assert.equal(thread.session.status, "ready");
+        return;
+      }
+      thread.session.status =
+        preparedStatus === "ready with failed scan" ? "ready" : preparedStatus;
+      yield* runReconciliation(input);
+      yield* Deferred.await(cleared);
+      assert.deepStrictEqual(sends, [
+        { threadId: thread.id, continuation: true, interactionMode: "default" },
+      ]);
+      assert.deepStrictEqual(binding.runtimePayload, {
+        activeTurnId: null,
+        continueAfterServerUpdate: null,
+        continueAfterServerUpdatePrepared: null,
+      });
+    }),
+  );
+}
+
+it.effect("settles failed opt-in recovery without retrying the provider turn", () =>
+  Effect.gen(function* () {
+    const turnId = TurnId.make("turn-failed-recovery");
+    const thread = makeThread("thread-failed-recovery", "running", turnId);
+    const settled = yield* Deferred.make<void>();
+    const sends: ProviderSendTurnInput[] = [];
+    const dispatched: OrchestrationCommand[] = [];
+    const preparedPayloads: unknown[] = [];
+    let binding: ProviderSessionDirectory.ProviderRuntimeBinding = {
+      threadId: thread.id,
+      provider: ProviderDriverKind.make("codex"),
+      providerInstanceId,
+      status: "running",
+      resumeCursor: { threadId: thread.id },
+      runtimePayload: { activeTurnId: turnId },
+    };
+    yield* runReconciliation({
+      threads: [thread],
+      continueAfterRestart: true,
+      providerService: {
+        ...makeProviderService(),
+        getCapabilities: () =>
+          Effect.succeed({ sessionModelSwitch: "in-session", promptlessTurnContinuation: true }),
+        sendTurn: (input) =>
+          Effect.gen(function* () {
+            sends.push(input);
+            preparedPayloads.push(binding.runtimePayload);
+            return yield* Effect.fail(
+              new ProviderSessionNotFoundError({ threadId: input.threadId }),
+            );
+          }),
+      },
+      directory: {
+        getBinding: () => Effect.sync(() => Option.some(binding)),
+        upsert: (next) =>
+          Effect.sync(() => {
+            binding = next;
+          }),
+        getProvider: () => Effect.die("unused"),
+        listThreadIds: () => Effect.die("unused"),
+        listBindings: () => Effect.succeed([]),
+      },
+      dispatch: (command) =>
+        Effect.gen(function* () {
+          dispatched.push(command);
+          if (command.type === "thread.session.set" && command.session.status === "error") {
+            yield* Deferred.succeed(settled, undefined);
+          }
+          return { sequence: dispatched.length };
+        }),
+    });
+    yield* Deferred.await(settled);
+    assert.equal(sends.length, 1);
+    assert.deepStrictEqual(preparedPayloads, [
+      {
+        activeTurnId: null,
+        continueAfterServerUpdate: turnId,
+        continueAfterServerUpdatePrepared: true,
+      },
+    ]);
+    assert.deepStrictEqual(
+      dispatched.map(
+        (command) =>
+          command.type === "thread.session.set" && {
+            status: command.session.status,
+            activeTurnId: command.session.activeTurnId,
+          },
+      ),
+      [
+        { status: "starting", activeTurnId: null },
+        { status: "error", activeTurnId: null },
+      ],
+    );
+    assert.equal(binding.status, "stopped");
+    assert.deepStrictEqual(binding.runtimePayload, {
+      activeTurnId: null,
+      continueAfterServerUpdate: null,
+      continueAfterServerUpdatePrepared: null,
+    });
+  }),
+);
diff --git a/apps/server/src/serverRuntimeStartup.ts b/apps/server/src/serverRuntimeStartup.ts
index 064796b2810b..a34d1bdbde91 100644
--- a/apps/server/src/serverRuntimeStartup.ts
+++ b/apps/server/src/serverRuntimeStartup.ts
@@ -394,6 +394,7 @@ export const markRunningProviderSessionsForContinuation = Effect.gen(function* (
         runtimePayload: {
           ...readRuntimePayload(binding.value.runtimePayload),
           [SERVER_UPDATE_CONTINUATION_KEY]: activeTurnId,
+          continueAfterServerUpdatePrepared: null,
         },
       });
       marked.push(thread.id);
@@ -423,6 +424,7 @@ const clearContinuationMarkers = (
                 runtimePayload: {
                   ...readRuntimePayload(binding.runtimePayload),
                   [SERVER_UPDATE_CONTINUATION_KEY]: null,
+                  continueAfterServerUpdatePrepared: null,
                 },
               }),
           }),
@@ -443,17 +445,56 @@ export const reconcileProviderSessions = Effect.gen(function* () {
   const orchestrationEngine = yield* OrchestrationEngine.OrchestrationEngineService;
   const providerService = yield* ProviderService.ProviderService;
   const query = yield* ProjectionSnapshotQuery.ProjectionSnapshotQuery;
+  const settings = yield* ServerSettings.ServerSettingsService;
+  const continueAfterRestart = yield* settings.getSettings.pipe(
+    Effect.map((value) => value.continueThreadsAfterServerUpdate),
+    Effect.catch((cause) =>
+      Effect.logWarning("could not read restart continuation preference", { cause }).pipe(
+        Effect.as(false),
+      ),
+    ),
+  );
 
   const liveThreadIds = new Set(
     (yield* providerService.listSessions()).map((session) => session.threadId),
   );
   const { threads } = yield* query.getCommandReadModel();
+  // Provider startup can report ready before the continuation is submitted.
+  // Find those markers in one read rather than querying every idle thread.
+  const preparedThreadIds = new Set(
+    (yield* directory.listBindings().pipe(
+      Effect.catch((cause) =>
+        Effect.logWarning("failed to read prepared provider continuations", { cause }).pipe(
+          Effect.andThen(
+            Effect.forEach(
+              threads.filter(
+                (thread) => thread.session?.status === "ready" && !liveThreadIds.has(thread.id),
+              ),
+              (thread) =>
+                directory.getBinding(thread.id).pipe(Effect.orElseSucceed(() => Option.none())),
+            ),
+          ),
+          Effect.map((bindings) =>
+            bindings.flatMap((binding) => (Option.isSome(binding) ? [binding.value] : [])),
+          ),
+        ),
+      ),
+    ))
+      .filter(
+        (binding) =>
+          readServerUpdateContinuationTurnId(binding.runtimePayload) !== null &&
+          readRuntimePayload(binding.runtimePayload).activeTurnId === null &&
+          readRuntimePayload(binding.runtimePayload).continueAfterServerUpdatePrepared === true,
+      )
+      .map((binding) => binding.threadId),
+  );
   const orphanedThreads = threads.filter(
     (thread) =>
       thread.session !== null &&
       (thread.session.status === "starting" ||
         thread.session.status === "running" ||
-        thread.session.activeTurnId !== null) &&
+        thread.session.activeTurnId !== null ||
+        (thread.session.status === "ready" && preparedThreadIds.has(thread.id))) &&
       !liveThreadIds.has(thread.id),
   );
 
@@ -479,7 +520,27 @@ export const reconcileProviderSessions = Effect.gen(function* () {
       : null;
     const continuationMarked =
       continuationTurnId !== null &&
-      (session.activeTurnId === null || continuationTurnId === session.activeTurnId);
+      (session.activeTurnId === null || continuationTurnId === session.activeTurnId) &&
+      Option.isSome(binding) &&
+      (readRuntimePayload(binding.value.runtimePayload).activeTurnId == null ||
+        readRuntimePayload(binding.value.runtimePayload).activeTurnId === continuationTurnId);
+    const preparedWhileReady =
+      session.status === "ready" &&
+      session.activeTurnId === null &&
+      continuationMarked &&
+      Option.isSome(binding) &&
+      readRuntimePayload(binding.value.runtimePayload).activeTurnId === null &&
+      readRuntimePayload(binding.value.runtimePayload).continueAfterServerUpdatePrepared === true;
+    // Abrupt shutdowns cannot write an update marker. Require both durable
+    // records to agree on an unfinished turn before recovering one implicitly.
+    const interruptedByRestart =
+      continueAfterRestart &&
+      session.status === "running" &&
+      session.activeTurnId !== null &&
+      Option.isSome(binding) &&
+      binding.value.status === "running" &&
+      binding.value.resumeCursor != null &&
+      readRuntimePayload(binding.value.runtimePayload).activeTurnId === session.activeTurnId;
     const settleAsError = (lastError: string) =>
       Effect.gen(function* () {
         yield* Effect.gen(function* () {
@@ -490,7 +551,12 @@ export const reconcileProviderSessions = Effect.gen(function* () {
               runtimePayload: {
                 ...readRuntimePayload(binding.value.runtimePayload),
                 activeTurnId: null,
-                ...(continuationMarkerPresent ? { [SERVER_UPDATE_CONTINUATION_KEY]: null } : {}),
+                ...(continuationMarkerPresent || interruptedByRestart
+                  ? {
+                      [SERVER_UPDATE_CONTINUATION_KEY]: null,
+                      continueAfterServerUpdatePrepared: null,
+                    }
+                  : {}),
               },
             });
           }
@@ -535,7 +601,9 @@ export const reconcileProviderSessions = Effect.gen(function* () {
 
     if (
       Option.isSome(binding) &&
-      continuationMarked &&
+      (continuationMarked || interruptedByRestart) &&
+      (session.status === "running" || session.status === "starting" || preparedWhileReady) &&
+      binding.value.resumeCursor != null &&
       thread.archivedAt === null &&
       thread.deletedAt === null
     ) {
@@ -545,6 +613,9 @@ export const reconcileProviderSessions = Effect.gen(function* () {
           status: "starting",
           runtimePayload: {
             ...readRuntimePayload(binding.value.runtimePayload),
+            // Keep recovery durable if this process also exits before sending.
+            [SERVER_UPDATE_CONTINUATION_KEY]: session.activeTurnId ?? continuationTurnId,
+            continueAfterServerUpdatePrepared: true,
             activeTurnId: null,
           },
         });
@@ -608,12 +679,12 @@ export const reconcileProviderSessions = Effect.gen(function* () {
             }
             return;
           }
-          yield* Effect.logWarning("failed to continue provider session after server update", {
+          yield* Effect.logWarning("failed to continue provider session after server restart", {
             threadId: thread.id,
             cause: continuationExit.cause,
           });
           yield* settleAsError(
-            "Could not continue this thread after the server update. Send a new message to continue.",
+            "Could not continue this thread after the server restart. Send a new message to continue.",
           ).pipe(Effect.ignoreCause);
         }),
       );
diff --git a/apps/web/src/components/ServerUpdateAction.test.tsx b/apps/web/src/components/ServerUpdateAction.test.tsx
index 584078c12bf4..67236361f677 100644
--- a/apps/web/src/components/ServerUpdateAction.test.tsx
+++ b/apps/web/src/components/ServerUpdateAction.test.tsx
@@ -15,7 +15,8 @@ vi.mock("~/hooks/useCopyToClipboard", () => ({
   useCopyToClipboard: () => ({ copyToClipboard: vi.fn() }),
 }));
 vi.mock("~/hooks/useSettings", () => ({
-  useClientSettings: (
+  useEnvironmentSettings: (
+    _environmentId: EnvironmentId,
     selector: (settings: { continueThreadsAfterServerUpdate: boolean }) => unknown,
   ) => selector({ continueThreadsAfterServerUpdate: testState.continueThreadsAfterServerUpdate }),
 }));
diff --git a/apps/web/src/components/ServerUpdateAction.tsx b/apps/web/src/components/ServerUpdateAction.tsx
index 71b974416dd3..1845ada716b6 100644
--- a/apps/web/src/components/ServerUpdateAction.tsx
+++ b/apps/web/src/components/ServerUpdateAction.tsx
@@ -8,7 +8,7 @@ import type { ComponentProps } from "react";
 
 import { requestConfirmDialog } from "~/confirmDialog";
 import { useCopyToClipboard } from "~/hooks/useCopyToClipboard";
-import { useClientSettings } from "~/hooks/useSettings";
+import { useEnvironmentSettings } from "~/hooks/useSettings";
 import { serverEnvironment } from "~/state/server";
 import { useAtomCommand } from "~/state/use-atom-command";
 import { manualServerUpdateCommand } from "~/versionSkew";
@@ -99,7 +99,8 @@ export function ServerUpdateAction({
   readonly size?: ComponentProps<typeof Button>["size"];
 }) {
   const isDesktopAppUpdate = selfUpdate === "desktop-managed";
-  const continueThreadsAfterServerUpdate = useClientSettings(
+  const continueThreadsAfterServerUpdate = useEnvironmentSettings(
+    environmentId,
     (settings) => settings.continueThreadsAfterServerUpdate,
   );
   const updateServer = useAtomCommand(serverEnvironment.updateServer, {
diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index b0344b640393..66f7691a4a07 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -564,7 +564,7 @@ export function useSettingsRestore(onRestored?: () => void) {
         : []),
       ...(settings.continueThreadsAfterServerUpdate !==
       DEFAULT_UNIFIED_SETTINGS.continueThreadsAfterServerUpdate
-        ? ["Continue threads after server updates"]
+        ? ["Continue threads after restarts"]
         : []),
       ...(isBackgroundActivityDirty ? ["Background activity"] : []),
       ...(settings.defaultThreadEnvMode !== DEFAULT_UNIFIED_SETTINGS.defaultThreadEnvMode
@@ -2438,12 +2438,13 @@ export function GeneralSettingsPanel() {
 
         <SettingsRow
           {...searchableSetting("continue-threads-after-server-update")}
-          description="Automatically resume active threads after a server update restarts the environment."
+          serverScoped
+          description="Automatically resume interrupted threads when this environment starts again after an update, crash, or machine restart."
           resetAction={
             settings.continueThreadsAfterServerUpdate !==
             DEFAULT_UNIFIED_SETTINGS.continueThreadsAfterServerUpdate ? (
               <SettingResetButton
-                label="continue threads after server updates"
+                label="continue threads after restarts"
                 onClick={() =>
                   updateSettings({
                     continueThreadsAfterServerUpdate:
@@ -2459,7 +2460,7 @@ export function GeneralSettingsPanel() {
               onCheckedChange={(checked) =>
                 updateSettings({ continueThreadsAfterServerUpdate: Boolean(checked) })
               }
-              aria-label="Continue threads after server updates"
+              aria-label="Continue threads after restarts"
             />
           }
         />
diff --git a/apps/web/src/components/settings/settingsSearch.ts b/apps/web/src/components/settings/settingsSearch.ts
index 22e2204d8a27..7358ed8f9a17 100644
--- a/apps/web/src/components/settings/settingsSearch.ts
+++ b/apps/web/src/components/settings/settingsSearch.ts
@@ -218,9 +218,11 @@ export const SETTINGS_SEARCH_ITEMS = [
   },
   {
     id: "continue-threads-after-server-update",
-    title: "Continue threads after server updates",
+    title: "Continue threads after restarts",
     to: "/settings/general",
-    searchTerms: ["resume running active work restart desktop update automatically"],
+    searchTerms: [
+      "resume running active interrupted work restart reboot machine crash desktop update automatically",
+    ],
   },
   {
     id: "background-activity",
diff --git a/docs/user/updating.md b/docs/user/updating.md
index 8ccefb4e5157..14500cbe4620 100644
--- a/docs/user/updating.md
+++ b/docs/user/updating.md
@@ -10,9 +10,13 @@ notice.
 Server updates restart the connection and can interrupt active agents and
 terminal commands. Saved threads, settings, and project files remain.
 
-**Settings → General → Continue threads after server updates** is off by default.
-Enable it to resume supported active threads once the replacement server is
-ready. Terminal commands may still be interrupted.
+**Settings → General → Continue threads after restarts** is off by default.
+Enable it for each environment to resume supported active threads after an
+update, crash, or machine restart. T3 Code must start again on that machine;
+the setting does not enable automatic startup. Terminal commands may still be
+interrupted, and threads without saved provider resume state need a new message.
+If you previously enabled continuation for updates, enable this environment
+setting once to allow recovery without a connected client.
 
 ## Update a connected server
 
diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts
index cd4b12713edf..51fbc812225c 100644
--- a/packages/contracts/src/settings.ts
+++ b/packages/contracts/src/settings.ts
@@ -255,9 +255,6 @@ export const ClientSettingsSchema = Schema.Struct({
   confirmThreadArchive: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
   confirmThreadDelete: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
   confirmThreadUnpin: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
-  continueThreadsAfterServerUpdate: Schema.Boolean.pipe(
-    Schema.withDecodingDefault(Effect.succeed(false)),
-  ),
   dismissedProviderUpdateNotificationKeys: Schema.Array(TrimmedNonEmptyString).pipe(
     Schema.withDecodingDefault(Effect.succeed([])),
   ),
@@ -835,6 +832,10 @@ export const ServerSettings = Schema.Struct({
     Schema.withDecodingDefault(Effect.succeed(false)),
   ),
   enableProviderUpdateChecks: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
+  // Retain the update-era key; recovery now needs an environment-owned opt-in.
+  continueThreadsAfterServerUpdate: Schema.Boolean.pipe(
+    Schema.withDecodingDefault(Effect.succeed(false)),
+  ),
   /**
    * Whether agents may drive the in-app preview browser. Turning this off
    * withholds the MCP credential, so the `t3-code` server (and with it every
@@ -1105,6 +1106,7 @@ export const ServerSettingsPatch = Schema.Struct({
   // Server settings
   enableLegacyTokenStreaming: Schema.optionalKey(Schema.Boolean),
   enableProviderUpdateChecks: Schema.optionalKey(Schema.Boolean),
+  continueThreadsAfterServerUpdate: Schema.optionalKey(Schema.Boolean),
   enableAgentBrowserAccess: Schema.optionalKey(Schema.Boolean),
   sidebarAutoSettleAfterDays: Schema.optionalKey(Schema.NullOr(SidebarAutoSettleAfterDays)),
   sidebarAutoSettleOnMerge: Schema.optionalKey(Schema.Boolean),
@@ -1181,7 +1183,6 @@ export const ClientSettingsPatch = Schema.Struct({
   confirmThreadArchive: Schema.optionalKey(Schema.Boolean),
   confirmThreadDelete: Schema.optionalKey(Schema.Boolean),
   confirmThreadUnpin: Schema.optionalKey(Schema.Boolean),
-  continueThreadsAfterServerUpdate: Schema.optionalKey(Schema.Boolean),
   diffIgnoreWhitespace: Schema.optionalKey(Schema.Boolean),
   diffLayout: Schema.optionalKey(DiffLayout),
   environmentIdentificationMode: Schema.optionalKey(EnvironmentIdentificationMode),

From dd7bc147f799f290eb58578a7f81643ecf9ad52e Mon Sep 17 00:00:00 2001
From: maria <maria@kuuro.net>
Date: Fri, 4 Sep 2026 19:01:45 -0400
Subject: [PATCH 34/56] fix(web): simplify changed files into a persistent
 folder tree (#9821)

---
 .../components/chat/ChangedFilesTree.test.tsx |  34 ++--
 .../src/components/chat/ChangedFilesTree.tsx  | 158 ++++--------------
 .../components/chat/MessagesTimeline.test.tsx |   3 +-
 .../src/components/chat/MessagesTimeline.tsx  |  16 +-
 apps/web/src/uiStateStore.test.ts             |   7 +-
 apps/web/src/uiStateStore.ts                  |   5 +-
 6 files changed, 57 insertions(+), 166 deletions(-)

diff --git a/apps/web/src/components/chat/ChangedFilesTree.test.tsx b/apps/web/src/components/chat/ChangedFilesTree.test.tsx
index 4998c40b0c55..899714ed55a1 100644
--- a/apps/web/src/components/chat/ChangedFilesTree.test.tsx
+++ b/apps/web/src/components/chat/ChangedFilesTree.test.tsx
@@ -10,26 +10,21 @@ describe("ChangedFilesCard", () => {
       <ChangedFilesCard
         turnId={TurnId.make("turn-1")}
         files={[{ path: "README.md", kind: "modified", additions: 2, deletions: 1 }]}
-        expanded
-        showCompactPreview={false}
         allDirectoriesExpanded
         resolvedTheme="light"
-        onExpandedChange={() => {}}
         onToggleAllDirectories={() => {}}
         onOpenTurnDiff={() => {}}
       />,
     );
 
-    expect(markup).toContain('data-changed-files-state="expanded"');
-    expect(markup).toContain('aria-expanded="true"');
-    expect(markup).toContain('aria-label="Collapse all folders"');
+    expect(markup).toContain('data-changed-files-state="tree"');
     expect(markup).toContain('aria-label="Open diff"');
     expect(markup).toContain('role="group" aria-label="2 additions, 1 deletions"');
     expect(markup).toContain("1 changed file");
     expect(markup).not.toContain("1 changed files");
   });
 
-  it("renders a scope and representative-file preview for a large latest change", () => {
+  it("shows collapsed folders and root files together", () => {
     const markup = renderToStaticMarkup(
       <ChangedFilesCard
         turnId={TurnId.make("turn-1")}
@@ -44,46 +39,39 @@ describe("ChangedFilesCard", () => {
           },
           { path: "README.md", kind: "modified", additions: 3, deletions: 0 },
         ]}
-        expanded={false}
-        showCompactPreview
         allDirectoriesExpanded={false}
         resolvedTheme="light"
-        onExpandedChange={() => {}}
         onToggleAllDirectories={() => {}}
         onOpenTurnDiff={() => {}}
       />,
     );
 
-    expect(markup).toContain('data-changed-files-state="preview"');
+    expect(markup).toContain('data-changed-files-state="tree"');
     expect(markup).toContain('aria-expanded="false"');
-    expect(markup).toContain("apps");
-    expect(markup).toContain("2 files");
-    expect(markup).toContain("packages");
-    expect(markup).toContain("root");
-    expect(markup).toContain("App.tsx");
-    expect(markup).toContain("git.ts");
+    expect(markup).toContain("apps/web/src");
+    expect(markup).not.toContain("App.tsx");
+    expect(markup).toContain("packages/shared/src");
+    expect(markup).not.toContain("git.ts");
     expect(markup).toContain("README.md");
-    expect(markup).toContain("Show all 4 files");
+    expect(markup).not.toContain("Show all");
     expect(markup).not.toContain("App.test.tsx");
   });
 
-  it("keeps older collapsed changes to a one-line receipt", () => {
+  it("keeps the folder tree visible when folders are collapsed", () => {
     const markup = renderToStaticMarkup(
       <ChangedFilesCard
         turnId={TurnId.make("turn-1")}
         files={[{ path: "apps/web/src/App.tsx", kind: "modified", additions: 120, deletions: 20 }]}
-        expanded={false}
-        showCompactPreview={false}
         allDirectoriesExpanded={false}
         resolvedTheme="light"
-        onExpandedChange={() => {}}
         onToggleAllDirectories={() => {}}
         onOpenTurnDiff={() => {}}
       />,
     );
 
-    expect(markup).toContain('data-changed-files-state="collapsed"');
+    expect(markup).toContain('data-changed-files-state="tree"');
     expect(markup).toContain("1 changed file");
+    expect(markup).toContain("apps/web/src");
     expect(markup).not.toContain("Show all");
     expect(markup).not.toContain("App.tsx");
   });
diff --git a/apps/web/src/components/chat/ChangedFilesTree.tsx b/apps/web/src/components/chat/ChangedFilesTree.tsx
index 906bf4c34cb4..5ac9f09613f3 100644
--- a/apps/web/src/components/chat/ChangedFilesTree.tsx
+++ b/apps/web/src/components/chat/ChangedFilesTree.tsx
@@ -19,99 +19,59 @@ import { DiffStatLabel, hasNonZeroStat } from "./DiffStatLabel";
 import { PierreEntryIcon } from "./PierreEntryIcon";
 import { Button } from "../ui/button";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
-import {
-  changedFileName,
-  selectChangedFilePreview,
-  summarizeChangedFileScopes,
-} from "./changedFilesPresentation";
 
 const EMPTY_DIRECTORY_OVERRIDES: Record<string, boolean> = {};
 
 export const ChangedFilesCard = memo(function ChangedFilesCard(props: {
   turnId: TurnId;
   files: ReadonlyArray<TurnDiffFileChange>;
-  expanded: boolean;
-  showCompactPreview: boolean;
   allDirectoriesExpanded: boolean;
   resolvedTheme: "light" | "dark";
-  onExpandedChange: (expanded: boolean) => void;
   onToggleAllDirectories: () => void;
   onOpenTurnDiff: (turnId: TurnId, filePath?: string) => void;
 }) {
   const {
     turnId,
     files,
-    expanded,
-    showCompactPreview,
     allDirectoriesExpanded,
     resolvedTheme,
-    onExpandedChange,
     onToggleAllDirectories,
     onOpenTurnDiff,
   } = props;
   const summaryStat = useMemo(() => summarizeTurnDiffStats(files), [files]);
-  const scopeSummary = useMemo(() => summarizeChangedFileScopes(files), [files]);
-  const previewFiles = useMemo(() => selectChangedFilePreview(files), [files]);
-  const compactPreviewVisible = showCompactPreview && !expanded;
+  const hasDirectories = files.some((file) => /[/\\]/.test(file.path));
 
   return (
     <div
-      className="@container/changed-files mt-4 rounded-2xl border border-border/70 bg-secondary p-2 dark:border-transparent dark:bg-input/32"
-      data-changed-files-state={
-        expanded ? "expanded" : compactPreviewVisible ? "preview" : "collapsed"
-      }
+      className="@container/changed-files mt-4 rounded-lg bg-secondary dark:bg-input/20"
+      data-changed-files-state="tree"
     >
       <div
         data-changed-files-header=""
-        className={cn(
-          "flex items-center justify-between gap-2 rounded-xl",
-          expanded &&
-            "sticky top-2 z-10 mb-2 bg-secondary dark:bg-[color-mix(in_srgb,var(--contrast-foreground)_2.5%,var(--background))]",
-        )}
+        className="sticky top-2 z-10 flex items-center justify-between gap-2 rounded-t-lg bg-secondary px-3 py-2 dark:bg-[color-mix(in_srgb,var(--input)_20%,var(--background))]"
       >
-        <button
-          type="button"
-          aria-expanded={expanded}
-          data-scroll-anchor-ignore
-          className="group flex min-w-0 flex-1 items-center rounded-xl px-2 py-1.5 text-left transition-colors hover:bg-accent/60 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-          onClick={() => onExpandedChange(!expanded)}
-        >
-          <span className="flex min-w-0 flex-1 items-center gap-1.5 overflow-hidden">
-            <ChevronRightIcon
-              aria-hidden="true"
-              className={cn(
-                "size-3.5 shrink-0 text-muted-foreground transition-transform",
-                expanded && "rotate-90",
-              )}
-            />
-            <span className="flex shrink-0 items-center gap-1 whitespace-nowrap font-medium text-foreground text-xs leading-4">
-              <span>
-                {files.length} changed file{files.length === 1 ? "" : "s"}
-              </span>
-              {hasNonZeroStat(summaryStat) && (
-                <DiffStatLabel
-                  additions={summaryStat.additions}
-                  className="text-xs leading-4"
-                  deletions={summaryStat.deletions}
-                  layout="inline"
-                />
-              )}
-            </span>
-            <span className="ml-1 hidden min-w-0 flex-1 truncate text-[11px] text-muted-foreground group-hover:text-foreground/80 @[24rem]/changed-files:inline">
-              {expanded ? "Hide files" : "Show files"}
-            </span>
+        <div className="flex min-w-0 flex-wrap items-center gap-x-3 gap-y-1 text-xs font-medium text-foreground">
+          <span>
+            {files.length} changed file{files.length === 1 ? "" : "s"}
           </span>
-        </button>
-        <div className="flex shrink-0 items-center gap-1.5 pr-1">
-          {expanded ? (
+          {hasNonZeroStat(summaryStat) && (
+            <DiffStatLabel
+              additions={summaryStat.additions}
+              deletions={summaryStat.deletions}
+              layout="inline"
+              className="text-xs leading-4"
+            />
+          )}
+        </div>
+        <div className="flex shrink-0 items-center gap-1">
+          {hasDirectories && (
             <Tooltip>
               <TooltipTrigger
                 render={
                   <Button
                     type="button"
                     size="icon-xs"
-                    variant="outline"
-                    className="!size-[22px]"
+                    variant="ghost-muted"
                     aria-label={
                       allDirectoriesExpanded ? "Collapse all folders" : "Expand all folders"
                     }
@@ -130,14 +90,14 @@ export const ChangedFilesCard = memo(function ChangedFilesCard(props: {
                 {allDirectoriesExpanded ? "Collapse all folders" : "Expand all folders"}
               </TooltipPopup>
             </Tooltip>
-          ) : null}
+          )}
           <Tooltip>
             <TooltipTrigger
               render={
                 <Button
                   type="button"
                   size="xs"
-                  variant="outline"
+                  variant="ghost-muted"
                   aria-label="Open diff"
                   onClick={() => onOpenTurnDiff(turnId, files[0]?.path)}
                 />
@@ -150,61 +110,14 @@ export const ChangedFilesCard = memo(function ChangedFilesCard(props: {
           </Tooltip>
         </div>
       </div>
-      {expanded ? (
-        <ChangedFilesTree
-          key={`changed-files-tree:${turnId}`}
-          turnId={turnId}
-          files={files}
-          allDirectoriesExpanded={allDirectoriesExpanded}
-          resolvedTheme={resolvedTheme}
-          onOpenTurnDiff={onOpenTurnDiff}
-        />
-      ) : compactPreviewVisible ? (
-        <div className="px-2 pb-1.5 pt-1">
-          <p className="flex flex-wrap items-center gap-x-1.5 gap-y-0.5 text-[11px] text-muted-foreground">
-            {scopeSummary.map((scope, index) => (
-              <span key={scope.label} className="inline-flex items-center gap-1">
-                {index > 0 ? <span aria-hidden="true">·</span> : null}
-                <span className="font-mono text-foreground/75">{scope.label}</span>
-                <span>
-                  {scope.fileCount} file{scope.fileCount === 1 ? "" : "s"}
-                </span>
-              </span>
-            ))}
-          </p>
-          <div className="mt-2 flex flex-wrap items-center gap-1.5">
-            {previewFiles.map((file) => (
-              <Tooltip key={file.path}>
-                <TooltipTrigger
-                  render={
-                    <button
-                      type="button"
-                      className="inline-flex max-w-48 items-center gap-1 rounded-md border border-border/70 bg-background/45 px-1.5 py-1 font-mono text-[10px] text-muted-foreground transition-colors hover:bg-accent/60 hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-                      onClick={() => onOpenTurnDiff(turnId, file.path)}
-                    />
-                  }
-                >
-                  <PierreEntryIcon
-                    pathValue={file.path}
-                    kind="file"
-                    theme={resolvedTheme}
-                    className="size-3 shrink-0 text-muted-foreground/70"
-                  />
-                  <span className="truncate">{changedFileName(file.path)}</span>
-                </TooltipTrigger>
-                <TooltipPopup side="top">{file.path}</TooltipPopup>
-              </Tooltip>
-            ))}
-            <button
-              type="button"
-              className="rounded-md px-1.5 py-1 text-[11px] font-medium text-muted-foreground transition-colors hover:bg-accent/60 hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-              onClick={() => onExpandedChange(true)}
-            >
-              Show all {files.length} files
-            </button>
-          </div>
-        </div>
-      ) : null}
+      <ChangedFilesTree
+        key={`${turnId}:${allDirectoriesExpanded}`}
+        turnId={turnId}
+        files={files}
+        allDirectoriesExpanded={allDirectoriesExpanded}
+        resolvedTheme={resolvedTheme}
+        onOpenTurnDiff={onOpenTurnDiff}
+      />
     </div>
   );
 });
@@ -261,7 +174,8 @@ export const ChangedFilesTree = memo(function ChangedFilesTree(props: {
           <button
             type="button"
             data-scroll-anchor-ignore
-            className="group flex w-full items-center gap-1.5 rounded-xl py-1 pr-3 text-left transition-colors hover:bg-accent/60 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background"
+            aria-expanded={isExpanded}
+            className="group flex w-full items-center gap-2 rounded-md py-1.5 pr-2 text-left transition-colors hover:bg-accent/60 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background"
             style={{ paddingLeft: `${leftPadding}px` }}
             onClick={() => toggleDirectory(node.path)}
           >
@@ -287,9 +201,7 @@ export const ChangedFilesTree = memo(function ChangedFilesTree(props: {
             )}
           </button>
           {isExpanded && (
-            <div className="space-y-0.5">
-              {node.children.map((childNode) => renderTreeNode(childNode, depth + 1))}
-            </div>
+            <div>{node.children.map((childNode) => renderTreeNode(childNode, depth + 1))}</div>
           )}
         </div>
       );
@@ -299,7 +211,7 @@ export const ChangedFilesTree = memo(function ChangedFilesTree(props: {
       <button
         key={`file:${node.path}`}
         type="button"
-        className="group flex w-full items-center gap-1.5 rounded-xl py-1 pr-3 text-left transition-colors hover:bg-accent/60 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background"
+        className="group flex w-full items-center gap-2 rounded-md py-1.5 pr-2 text-left transition-colors hover:bg-accent/60 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background"
         style={{ paddingLeft: `${leftPadding}px` }}
         onClick={() => onOpenTurnDiff(turnId, node.path)}
       >
@@ -312,7 +224,7 @@ export const ChangedFilesTree = memo(function ChangedFilesTree(props: {
           theme={resolvedTheme}
           className="size-3.5 text-muted-foreground/70"
         />
-        <span className="truncate font-mono text-[11px] text-muted-foreground/80 group-hover:text-foreground/90">
+        <span className="truncate font-mono text-xs text-foreground/85 group-hover:text-foreground">
           {node.name}
         </span>
         {node.stat && (
@@ -324,7 +236,7 @@ export const ChangedFilesTree = memo(function ChangedFilesTree(props: {
     );
   };
 
-  return <div className="space-y-0.5">{treeNodes.map((node) => renderTreeNode(node, 0))}</div>;
+  return <div className="p-2">{treeNodes.map((node) => renderTreeNode(node, 0))}</div>;
 });
 
 function collectDirectoryPaths(nodes: ReadonlyArray<TurnDiffTreeNode>): string[] {
diff --git a/apps/web/src/components/chat/MessagesTimeline.test.tsx b/apps/web/src/components/chat/MessagesTimeline.test.tsx
index ccf9be69a471..cf2e79a78e53 100644
--- a/apps/web/src/components/chat/MessagesTimeline.test.tsx
+++ b/apps/web/src/components/chat/MessagesTimeline.test.tsx
@@ -379,9 +379,8 @@ describe("MessagesTimeline", () => {
     expect(markup).toContain("sticky top-2 z-10");
     expect(markup).not.toContain("self-start");
     expect(markup).toContain("whitespace-nowrap");
-    expect(markup).toContain("!size-[22px]");
     expect(markup).toContain("size-3");
-    expect(markup).toContain('aria-label="Collapse all folders"');
+    expect(markup).not.toContain('aria-label="Collapse all folders"');
     expect(markup).toContain('aria-label="Open diff"');
     expect(markup).toContain("1 changed file");
   });
diff --git a/apps/web/src/components/chat/MessagesTimeline.tsx b/apps/web/src/components/chat/MessagesTimeline.tsx
index df952aeca382..23807a3b0969 100644
--- a/apps/web/src/components/chat/MessagesTimeline.tsx
+++ b/apps/web/src/components/chat/MessagesTimeline.tsx
@@ -111,7 +111,6 @@ import {
 } from "./ExpandedImagePreview";
 import { ProposedPlanCard } from "./ProposedPlanCard";
 import { ChangedFilesCard } from "./ChangedFilesTree";
-import { shouldAutoExpandChangedFiles } from "./changedFilesPresentation";
 import { CHAT_TIMELINE_ANCHOR_OFFSET } from "./timelineScrollAnchoring";
 import { MessageCopyButton } from "./MessageCopyButton";
 import { PierreEntryIcon } from "./PierreEntryIcon";
@@ -2117,30 +2116,21 @@ function AssistantChangedFilesSectionInner({
   resolvedTheme: "light" | "dark";
   onOpenTurnDiff: (turnId: TurnId, filePath?: string) => void;
 }) {
-  const activity = use(TimelineRowActivityCtx);
-  const isLatestTurn = activity.latestTurnId === turnSummary.turnId;
   const persistedExpanded = useUiStateStore(
     (store) => store.threadChangedFilesExpandedById[routeThreadKey]?.[turnSummary.turnId],
   );
   const setExpanded = useUiStateStore((store) => store.setThreadChangedFilesExpanded);
-  const [autoExpanded] = useState(() =>
-    shouldAutoExpandChangedFiles(checkpointFiles, isLatestTurn),
-  );
-  const [allDirectoriesExpanded, setAllDirectoriesExpanded] = useState(autoExpanded);
-  const expanded = persistedExpanded ?? (isLatestTurn && autoExpanded);
+  const allDirectoriesExpanded = persistedExpanded ?? false;
 
   return (
     <ChangedFilesCard
       turnId={turnSummary.turnId}
       files={checkpointFiles}
-      expanded={expanded}
-      showCompactPreview={isLatestTurn}
       allDirectoriesExpanded={allDirectoriesExpanded}
       resolvedTheme={resolvedTheme}
-      onExpandedChange={(nextExpanded) =>
-        setExpanded(routeThreadKey, turnSummary.turnId, nextExpanded)
+      onToggleAllDirectories={() =>
+        setExpanded(routeThreadKey, turnSummary.turnId, !allDirectoriesExpanded)
       }
-      onToggleAllDirectories={() => setAllDirectoriesExpanded((current) => !current)}
       onOpenTurnDiff={onOpenTurnDiff}
     />
   );
diff --git a/apps/web/src/uiStateStore.test.ts b/apps/web/src/uiStateStore.test.ts
index 304502873539..bd6db865992b 100644
--- a/apps/web/src/uiStateStore.test.ts
+++ b/apps/web/src/uiStateStore.test.ts
@@ -159,7 +159,7 @@ describe("parsePersistedState", () => {
         invalid: "not-a-date",
       },
       defaultAdvertisedEndpointKey: "desktop-core:lan:http",
-      threadChangedFilesExpansionVersion: 1,
+      threadChangedFilesExpansionVersion: 2,
       threadChangedFilesExpandedById: {
         "environment:thread-1": {
           "turn-1": false,
@@ -186,8 +186,9 @@ describe("parsePersistedState", () => {
     });
   });
 
-  it("ignores changed-file expansion values saved with legacy folder semantics", () => {
+  it.each([undefined, 1])("ignores changed-file expansion version %s", (version) => {
     const parsed = parsePersistedState({
+      ...(version === undefined ? {} : { threadChangedFilesExpansionVersion: version }),
       threadChangedFilesExpandedById: {
         "environment:thread-1": {
           "turn-1": false,
@@ -296,7 +297,7 @@ describe("uiStateStore persistence", () => {
         "environment:thread-1": "2026-02-25T12:35:00.000Z",
       },
       defaultAdvertisedEndpointKey: "desktop-core:lan:http",
-      threadChangedFilesExpansionVersion: 1,
+      threadChangedFilesExpansionVersion: 2,
       threadChangedFilesExpandedById: {
         "environment:thread-1": {
           "turn-1": false,
diff --git a/apps/web/src/uiStateStore.ts b/apps/web/src/uiStateStore.ts
index 5d744d540a5a..048055639ce7 100644
--- a/apps/web/src/uiStateStore.ts
+++ b/apps/web/src/uiStateStore.ts
@@ -3,7 +3,8 @@ import { create } from "zustand";
 import { normalizeProjectPathForComparison } from "./lib/projectPaths";
 
 export const PERSISTED_STATE_KEY = "t3code:ui-state:v1";
-const THREAD_CHANGED_FILES_EXPANSION_VERSION = 1;
+// Version 1 stored card visibility, not folder expansion.
+const THREAD_CHANGED_FILES_EXPANSION_VERSION = 2;
 const LEGACY_PERSISTED_STATE_KEYS = [
   "t3code:renderer-state:v8",
   "t3code:renderer-state:v7",
@@ -25,7 +26,7 @@ export interface PersistedUiState {
   expandedProjectCwds?: string[];
   projectOrderCwds?: string[];
   defaultAdvertisedEndpointKey?: string | null;
-  threadChangedFilesExpansionVersion?: typeof THREAD_CHANGED_FILES_EXPANSION_VERSION;
+  threadChangedFilesExpansionVersion?: number;
   threadChangedFilesExpandedById?: Record<string, Record<string, boolean>>;
 }
 

From 5a433244d0b827176df8b76a05959cd1a7a98ce2 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 16:11:20 -0700
Subject: [PATCH 35/56] feat: add custom model names and option descriptors
 (#9807)

---
 .../src/provider/ClaudeModelCatalog.test.ts   |  56 +++
 .../server/src/provider/ClaudeModelCatalog.ts |  67 +--
 .../src/provider/Layers/CodexProvider.ts      |  44 +-
 .../src/provider/Layers/GrokProvider.ts       |   3 +-
 .../src/provider/providerSnapshot.test.ts     |  21 +
 apps/server/src/provider/providerSnapshot.ts  |  23 +-
 .../components/settings/CustomModelEditor.tsx | 387 ++++++++++++++++++
 .../settings/ProviderInstanceCard.test.ts     |  43 +-
 .../settings/ProviderInstanceCard.tsx         |  51 ++-
 .../settings/ProviderModelsSection.tsx        | 103 +++--
 .../settings/customModelEditor.logic.test.ts  | 259 ++++++++++++
 .../settings/customModelEditor.logic.ts       | 258 ++++++++++++
 apps/web/src/modelSelection.ts                |  50 ++-
 docs/user/composer.md                         |   6 +
 packages/contracts/src/model.ts               |  16 +
 packages/contracts/src/settings.test.ts       |  34 ++
 packages/contracts/src/settings.ts            |  25 +-
 packages/shared/src/model.test.ts             |  52 +++
 packages/shared/src/model.ts                  |  75 +++-
 19 files changed, 1423 insertions(+), 150 deletions(-)
 create mode 100644 apps/web/src/components/settings/CustomModelEditor.tsx
 create mode 100644 apps/web/src/components/settings/customModelEditor.logic.test.ts
 create mode 100644 apps/web/src/components/settings/customModelEditor.logic.ts

diff --git a/apps/server/src/provider/ClaudeModelCatalog.test.ts b/apps/server/src/provider/ClaudeModelCatalog.test.ts
index b370c8e24d3d..d5c9d8f53d1e 100644
--- a/apps/server/src/provider/ClaudeModelCatalog.test.ts
+++ b/apps/server/src/provider/ClaudeModelCatalog.test.ts
@@ -7,9 +7,11 @@ import {
   formatClaudeVersionUpgradeMessage,
   normalizeClaudeCatalogEffort,
   resolveClaudeCatalogApiModelId,
+  resolveClaudeCatalogEffort,
   resolveClaudeModelCatalog,
   resolveClaudeModelsForVersion,
   resolveClaudeModelSlug,
+  scopeClaudeModelCatalog,
 } from "./ClaudeModelCatalog.ts";
 
 /**
@@ -134,4 +136,58 @@ describe("Claude model catalog", () => {
     };
     assert.isFalse(hasValidClaudeManifestAdapters(malformed));
   });
+
+  it("appends custom models with their own descriptors and keeps bare slugs opaque", () => {
+    const catalog = scopeClaudeModelCatalog(resolveClaudeModelCatalog(manifest()), [
+      "synthetic",
+      {
+        slug: "claude-custom-tuned",
+        name: "Tuned",
+        capabilities: {
+          optionDescriptors: [
+            {
+              id: "effort",
+              label: "Reasoning",
+              type: "select",
+              options: [
+                { id: "gentle", label: "Gentle", isDefault: true },
+                { id: "brutal", label: "Brutal" },
+              ],
+            },
+          ],
+        },
+      },
+    ]);
+
+    // The bare custom slug shadows the built-in alias, so it no longer resolves to it.
+    assert.strictEqual(resolveClaudeModelSlug(catalog, "synthetic"), "synthetic");
+    assert.strictEqual(resolveClaudeCatalogEffort(catalog, "synthetic", "extreme"), undefined);
+
+    // The entry with descriptors resolves user-defined effort ids and passes
+    // them through untouched (no effortMap, no model suffix).
+    assert.strictEqual(
+      resolveClaudeCatalogEffort(catalog, "claude-custom-tuned", "brutal"),
+      "brutal",
+    );
+    assert.strictEqual(
+      resolveClaudeCatalogEffort(catalog, "claude-custom-tuned", "bogus"),
+      "gentle",
+    );
+    assert.strictEqual(
+      normalizeClaudeCatalogEffort(catalog, "brutal", "claude-custom-tuned"),
+      "brutal",
+    );
+    assert.strictEqual(
+      resolveClaudeCatalogApiModelId(catalog, {
+        instanceId: ProviderInstanceId.make("claudeAgent"),
+        model: "claude-custom-tuned",
+        options: [{ id: "effort", value: "brutal" }],
+      }),
+      "claude-custom-tuned",
+    );
+    assert.deepStrictEqual(
+      resolveClaudeModelsForVersion(catalog, "3.2.0").map((model) => model.slug),
+      ["claude-synthetic-next", "claude-custom-tuned"],
+    );
+  });
 });
diff --git a/apps/server/src/provider/ClaudeModelCatalog.ts b/apps/server/src/provider/ClaudeModelCatalog.ts
index bd554f042f0b..b1fcd6a92bbf 100644
--- a/apps/server/src/provider/ClaudeModelCatalog.ts
+++ b/apps/server/src/provider/ClaudeModelCatalog.ts
@@ -1,4 +1,5 @@
 import {
+  type CustomModelSetting,
   type ModelCapabilities,
   type ModelSelection,
   ProviderDriverKind,
@@ -9,7 +10,7 @@ import {
   getModelSelectionStringOptionValue,
   getProviderOptionCurrentValue,
   getProviderOptionDescriptors,
-  normalizeCustomModelSlug,
+  readCustomModelEntries,
 } from "@t3tools/shared/model";
 import { compareSemverVersions } from "@t3tools/shared/semver";
 
@@ -70,33 +71,51 @@ export function resolveClaudeModelCatalog(manifest: ModelManifestData): ClaudeMo
 
 export const BUNDLED_CLAUDE_MODEL_CATALOG = resolveClaudeModelCatalog(BUNDLED_MODEL_MANIFEST);
 
-/** Keeps custom model aliases opaque while preserving canonical built-in models and capabilities. */
+/**
+ * Scope the catalog to one instance's settings: custom model slugs stay opaque
+ * (a built-in alias they shadow is dropped, canonical slugs and capabilities
+ * are preserved), and custom entries that declare their own capabilities are
+ * appended so the adapter resolves effort / fast mode / thinking against the
+ * user's descriptors instead of the empty default. Custom entries carry no
+ * runtime profile, so option values pass through to Claude Code verbatim.
+ */
 export function scopeClaudeModelCatalog(
   catalog: ClaudeModelCatalog,
-  customModels: ReadonlyArray<string>,
+  customModels: ReadonlyArray<CustomModelSetting>,
 ): ClaudeModelCatalog {
-  const customAliases = new Set(
-    customModels.flatMap((model) => {
-      const slug = normalizeCustomModelSlug(model);
-      return slug ? [slug.toLowerCase()] : [];
-    }),
-  );
-  if (customAliases.size === 0) return catalog;
+  const customEntries = readCustomModelEntries(customModels);
+  if (customEntries.length === 0) return catalog;
+  const customAliases = new Set(customEntries.map((entry) => entry.slug.toLowerCase()));
 
-  return {
-    models: catalog.models.map((entry) => {
-      if (!entry.model.aliases?.some((alias) => customAliases.has(alias.toLowerCase()))) {
-        return entry;
-      }
-      return {
-        ...entry,
-        model: {
-          ...entry.model,
-          aliases: entry.model.aliases.filter((alias) => !customAliases.has(alias.toLowerCase())),
-        },
-      };
-    }),
-  };
+  const builtInModels = catalog.models.map((entry) => {
+    if (!entry.model.aliases?.some((alias) => customAliases.has(alias.toLowerCase()))) {
+      return entry;
+    }
+    return {
+      ...entry,
+      model: {
+        ...entry.model,
+        aliases: entry.model.aliases.filter((alias) => !customAliases.has(alias.toLowerCase())),
+      },
+    };
+  });
+  const builtInSlugs = new Set(builtInModels.map((entry) => entry.model.slug));
+  const customCatalogModels: Array<ClaudeCatalogModel> = [];
+  for (const entry of customEntries) {
+    if (!entry.capabilities || builtInSlugs.has(entry.slug)) continue;
+    customCatalogModels.push({
+      model: {
+        slug: entry.slug,
+        name: entry.name,
+        isCustom: true,
+        capabilities: entry.capabilities,
+      },
+      runtime: {},
+      compatibility: {},
+    });
+  }
+
+  return { models: [...builtInModels, ...customCatalogModels] };
 }
 
 export function resolveClaudeCatalogModel(
diff --git a/apps/server/src/provider/Layers/CodexProvider.ts b/apps/server/src/provider/Layers/CodexProvider.ts
index ac35ee138a8b..d65a09c6d4f9 100644
--- a/apps/server/src/provider/Layers/CodexProvider.ts
+++ b/apps/server/src/provider/Layers/CodexProvider.ts
@@ -15,6 +15,7 @@ import * as CodexErrors from "effect-codex-app-server/errors";
 
 import type {
   CodexSettings,
+  CustomModelSetting,
   ServerProvider,
   ServerProviderState,
   ModelCapabilities,
@@ -24,7 +25,7 @@ import type {
 } from "@t3tools/contracts";
 import { PREFERRED_DEFAULT_CODEX_MODELS, ServerSettingsError } from "@t3tools/contracts";
 
-import { createModelCapabilities } from "@t3tools/shared/model";
+import { createModelCapabilities, readCustomModelEntries } from "@t3tools/shared/model";
 import { resolveSpawnCommand } from "@t3tools/shared/shell";
 import { codexAppServerArgs, resolveCodexLaunchArgs } from "./codexLaunchArgs.ts";
 import {
@@ -244,9 +245,14 @@ export function applyPreferredCodexDefaultModel(
   });
 }
 
+/**
+ * Codex has no static default capability set, so a bare custom slug borrows
+ * the first built-in's descriptors; an entry with its own capabilities keeps
+ * them.
+ */
 function appendCustomCodexModels(
   models: ReadonlyArray<ServerProviderModel>,
-  customModels: ReadonlyArray<string>,
+  customModels: ReadonlyArray<CustomModelSetting>,
 ): ReadonlyArray<ServerProviderModel> {
   if (customModels.length === 0) {
     return models;
@@ -255,17 +261,16 @@ function appendCustomCodexModels(
   const seen = new Set(models.map((model) => model.slug));
   const fallbackCapabilities = models.find((model) => model.capabilities)?.capabilities ?? null;
   const customEntries: ServerProviderModel[] = [];
-  for (const rawModel of customModels) {
-    const slug = rawModel.trim();
-    if (!slug || seen.has(slug)) {
+  for (const entry of readCustomModelEntries(customModels)) {
+    if (seen.has(entry.slug)) {
       continue;
     }
-    seen.add(slug);
+    seen.add(entry.slug);
     customEntries.push({
-      slug,
-      name: slug,
+      slug: entry.slug,
+      name: entry.name,
       isCustom: true,
-      capabilities: fallbackCapabilities,
+      capabilities: entry.capabilities ?? fallbackCapabilities,
     });
   }
   return customEntries.length === 0 ? models : [...models, ...customEntries];
@@ -399,7 +404,7 @@ const probeCodexAppServerProvider = Effect.fn("probeCodexAppServerProvider")(fun
   readonly homePath?: string;
   readonly launchArgs?: string;
   readonly cwd: string;
-  readonly customModels?: ReadonlyArray<string>;
+  readonly customModels?: ReadonlyArray<CustomModelSetting>;
   readonly environment?: NodeJS.ProcessEnv;
 }) {
   const { client, initialize } = yield* withCodexAppServerClient(input);
@@ -470,21 +475,8 @@ export const probeCodexSkillsForCwd = Effect.fn("probeCodexSkillsForCwd")(functi
   return parseCodexSkillsListResponse(skillsResponse, input.cwd);
 });
 
-const emptyCodexModelsFromSettings = (codexSettings: CodexSettings): ServerProvider["models"] => {
-  const models = new Set<string>();
-  for (const model of codexSettings.customModels) {
-    const trimmed = model.trim();
-    if (trimmed.length > 0) {
-      models.add(trimmed);
-    }
-  }
-  return Array.from(models, (model) => ({
-    slug: model,
-    name: model,
-    isCustom: true,
-    capabilities: null,
-  }));
-};
+const emptyCodexModelsFromSettings = (codexSettings: CodexSettings): ServerProvider["models"] =>
+  appendCustomCodexModels([], codexSettings.customModels);
 
 const makePendingCodexProvider = (
   codexSettings: CodexSettings,
@@ -562,7 +554,7 @@ export const checkCodexProviderStatus = Effect.fn("checkCodexProviderStatus")(fu
     readonly homePath?: string;
     readonly launchArgs?: string;
     readonly cwd: string;
-    readonly customModels: ReadonlyArray<string>;
+    readonly customModels: ReadonlyArray<CustomModelSetting>;
     readonly environment?: NodeJS.ProcessEnv;
   }) => Effect.Effect<
     CodexAppServerProviderSnapshot,
diff --git a/apps/server/src/provider/Layers/GrokProvider.ts b/apps/server/src/provider/Layers/GrokProvider.ts
index 50a881f38897..493e46d44352 100644
--- a/apps/server/src/provider/Layers/GrokProvider.ts
+++ b/apps/server/src/provider/Layers/GrokProvider.ts
@@ -1,4 +1,5 @@
 import {
+  type CustomModelSetting,
   type GrokSettings,
   type ModelCapabilities,
   type ServerProvider,
@@ -104,7 +105,7 @@ export function buildInitialGrokProviderSnapshot(
 }
 
 function grokModelsFromSettings(
-  customModels: ReadonlyArray<string> | undefined,
+  customModels: ReadonlyArray<CustomModelSetting> | undefined,
   builtInModels: ReadonlyArray<ServerProviderModel> = GROK_BUILT_IN_MODELS,
 ): ReadonlyArray<ServerProviderModel> {
   return providerModelsFromSettings(builtInModels, customModels ?? [], EMPTY_CAPABILITIES);
diff --git a/apps/server/src/provider/providerSnapshot.test.ts b/apps/server/src/provider/providerSnapshot.test.ts
index 011572780666..399d86f7a133 100644
--- a/apps/server/src/provider/providerSnapshot.test.ts
+++ b/apps/server/src/provider/providerSnapshot.test.ts
@@ -52,6 +52,27 @@ describe("providerModelsFromSettings", () => {
     ]);
   });
 
+  it("keeps an entry's own name and capabilities over the driver default", () => {
+    const capabilities = createModelCapabilities({
+      optionDescriptors: [{ id: "fastMode", label: "Fast Mode", type: "boolean" }],
+    });
+    const models = providerModelsFromSettings(
+      [],
+      ["bare", { slug: "named", name: "Named", capabilities }],
+      OPENCODE_CUSTOM_MODEL_CAPABILITIES,
+    );
+
+    expect(models).toEqual([
+      {
+        slug: "bare",
+        name: "bare",
+        isCustom: true,
+        capabilities: OPENCODE_CUSTOM_MODEL_CAPABILITIES,
+      },
+      { slug: "named", name: "Named", isCustom: true, capabilities },
+    ]);
+  });
+
   it("preserves a custom slug that collides with a provider alias", () => {
     const capabilities = createModelCapabilities({ optionDescriptors: [] });
     const models = providerModelsFromSettings(
diff --git a/apps/server/src/provider/providerSnapshot.ts b/apps/server/src/provider/providerSnapshot.ts
index 55534629d3eb..9663aeacb63f 100644
--- a/apps/server/src/provider/providerSnapshot.ts
+++ b/apps/server/src/provider/providerSnapshot.ts
@@ -1,4 +1,5 @@
 import type {
+  CustomModelSetting,
   ProviderDriverKind,
   ModelCapabilities,
   ServerProvider,
@@ -14,7 +15,7 @@ import * as PlatformError from "effect/PlatformError";
 import * as Schema from "effect/Schema";
 import * as Stream from "effect/Stream";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
-import { normalizeCustomModelSlug } from "@t3tools/shared/model";
+import { readCustomModelEntries } from "@t3tools/shared/model";
 import { isWindowsCommandNotFound } from "../processRunner.ts";
 import { createProviderVersionAdvisory } from "./providerMaintenance.ts";
 import { collectUint8StreamText } from "../stream/collectUint8StreamText.ts";
@@ -145,26 +146,30 @@ export function parseGenericCliVersion(output: string): string | null {
   return match?.[1] ?? null;
 }
 
+/**
+ * Append the user's custom models after the built-ins. A custom entry that
+ * declares its own capabilities keeps them; a bare slug gets the driver's
+ * default set. Slugs that collide with a built-in are dropped.
+ */
 export function providerModelsFromSettings(
   builtInModels: ReadonlyArray<ServerProviderModel>,
-  customModels: ReadonlyArray<string>,
+  customModels: ReadonlyArray<CustomModelSetting>,
   customModelCapabilities: ModelCapabilities,
 ): ReadonlyArray<ServerProviderModel> {
   const resolvedBuiltInModels = [...builtInModels];
   const seen = new Set(resolvedBuiltInModels.map((model) => model.slug));
   const customEntries: ServerProviderModel[] = [];
 
-  for (const candidate of customModels) {
-    const normalized = normalizeCustomModelSlug(candidate);
-    if (!normalized || seen.has(normalized)) {
+  for (const entry of readCustomModelEntries(customModels)) {
+    if (seen.has(entry.slug)) {
       continue;
     }
-    seen.add(normalized);
+    seen.add(entry.slug);
     customEntries.push({
-      slug: normalized,
-      name: normalized,
+      slug: entry.slug,
+      name: entry.name,
       isCustom: true,
-      capabilities: customModelCapabilities,
+      capabilities: entry.capabilities ?? customModelCapabilities,
     });
   }
 
diff --git a/apps/web/src/components/settings/CustomModelEditor.tsx b/apps/web/src/components/settings/CustomModelEditor.tsx
new file mode 100644
index 000000000000..9fa65e0bf23e
--- /dev/null
+++ b/apps/web/src/components/settings/CustomModelEditor.tsx
@@ -0,0 +1,387 @@
+"use client";
+
+import { PlusIcon, XIcon } from "lucide-react";
+import { useMemo, useState } from "react";
+import type { ProviderDriverKind, ServerProviderModel } from "@t3tools/contracts";
+import type { CustomModelDefinition } from "@t3tools/shared/model";
+
+import { cn } from "../../lib/utils";
+import { Button } from "../ui/button";
+import { Input } from "../ui/input";
+import { Select, SelectItem, SelectPopup, SelectTrigger, SelectValue } from "../ui/select";
+import { Switch } from "../ui/switch";
+import {
+  DESCRIPTOR_PRESETS_BY_KIND,
+  type CustomModelDraft,
+  type EditorChoice,
+  type EditorDescriptor,
+  choiceFromPreset,
+  definitionFromDraft,
+  descriptorFromPreset,
+  descriptorsFromCapabilities,
+  draftFromDefinition,
+  emptyEditorChoice,
+  emptyEditorDescriptor,
+  validateDraft,
+} from "./customModelEditor.logic";
+
+const CUSTOM_ID_VALUE = "__custom__";
+const START_FROM_NONE = "__none__";
+
+interface CustomModelEditorProps {
+  readonly instanceId: string;
+  readonly driverKind: ProviderDriverKind | null;
+  readonly entry: CustomModelDefinition;
+  /** Built-in models whose descriptors can be copied as a starting point. */
+  readonly builtInModels: ReadonlyArray<ServerProviderModel>;
+  readonly onSave: (next: CustomModelDefinition) => void;
+  readonly onCancel: () => void;
+}
+
+/**
+ * Inline editor for one custom model: display name plus the option
+ * descriptors the composer should offer for it (Reasoning effort, Fast
+ * mode, ...). Draft state is local; nothing is persisted until Save.
+ */
+export function CustomModelEditor({
+  instanceId,
+  driverKind,
+  entry,
+  builtInModels,
+  onSave,
+  onCancel,
+}: CustomModelEditorProps) {
+  const [draft, setDraft] = useState<CustomModelDraft>(() => draftFromDefinition(entry));
+  const [error, setError] = useState<string | null>(null);
+  const presets = useMemo(
+    () => (driverKind ? (DESCRIPTOR_PRESETS_BY_KIND[driverKind] ?? []) : []),
+    [driverKind],
+  );
+  const startFromCandidates = useMemo(
+    () => builtInModels.filter((model) => (model.capabilities?.optionDescriptors?.length ?? 0) > 0),
+    [builtInModels],
+  );
+  const domId = (suffix: string) => `provider-instance-${instanceId}-custom-model-${suffix}`;
+
+  const updateDescriptor = (key: string, patch: Partial<EditorDescriptor>) => {
+    setError(null);
+    setDraft((current) => ({
+      ...current,
+      descriptors: current.descriptors.map((descriptor) =>
+        descriptor.key === key ? { ...descriptor, ...patch } : descriptor,
+      ),
+    }));
+  };
+
+  const updateChoice = (descriptorKey: string, choiceKey: string, patch: Partial<EditorChoice>) => {
+    setError(null);
+    setDraft((current) => ({
+      ...current,
+      descriptors: current.descriptors.map((descriptor) => {
+        if (descriptor.key !== descriptorKey) return descriptor;
+        return {
+          ...descriptor,
+          choices: descriptor.choices.map((choice) => {
+            if (choice.key === choiceKey) return { ...choice, ...patch };
+            // Only one choice can be the default.
+            return patch.isDefault ? { ...choice, isDefault: false } : choice;
+          }),
+        };
+      }),
+    }));
+  };
+
+  const removeDescriptor = (key: string) => {
+    setError(null);
+    setDraft((current) => ({
+      ...current,
+      descriptors: current.descriptors.filter((descriptor) => descriptor.key !== key),
+    }));
+  };
+
+  const addDescriptor = (descriptor: EditorDescriptor) => {
+    setError(null);
+    setDraft((current) => ({ ...current, descriptors: [...current.descriptors, descriptor] }));
+  };
+
+  // Selecting a preset id replaces the descriptor's label/type/choices so the
+  // usual values are one click away; "Custom…" leaves the row blank to type into.
+  const applyPresetId = (descriptor: EditorDescriptor, value: string | null) => {
+    if (value === null) return;
+    if (value === CUSTOM_ID_VALUE) {
+      updateDescriptor(descriptor.key, { id: "" });
+      return;
+    }
+    const preset = presets.find((candidate) => candidate.id === value);
+    if (!preset) return;
+    updateDescriptor(descriptor.key, {
+      id: preset.id,
+      label: preset.label,
+      type: preset.type,
+      choices: (preset.choices ?? []).map(choiceFromPreset),
+      currentBooleanValue: undefined,
+      description: undefined,
+    });
+  };
+
+  const handleStartFrom = (slug: string | null) => {
+    if (slug === null || slug === START_FROM_NONE) return;
+    const model = startFromCandidates.find((candidate) => candidate.slug === slug);
+    if (!model) return;
+    setError(null);
+    setDraft((current) => ({
+      ...current,
+      descriptors: descriptorsFromCapabilities(model.capabilities, driverKind),
+    }));
+  };
+
+  const handleSave = () => {
+    const problem = validateDraft(draft);
+    if (problem) {
+      setError(problem);
+      return;
+    }
+    onSave(definitionFromDraft(draft));
+  };
+
+  const idSelectValue = (descriptor: EditorDescriptor) =>
+    presets.some((preset) => preset.id === descriptor.id) ? descriptor.id : CUSTOM_ID_VALUE;
+
+  const renderChoice = (descriptor: EditorDescriptor, choice: EditorChoice) => (
+    <div key={choice.key} className="flex items-center gap-2">
+      <Input
+        size="compact"
+        value={choice.id}
+        onChange={(event) => updateChoice(descriptor.key, choice.key, { id: event.target.value })}
+        placeholder="value"
+        className="w-28 font-mono"
+        spellCheck={false}
+        aria-label="Choice value"
+      />
+      <Input
+        size="compact"
+        value={choice.label}
+        onChange={(event) =>
+          updateChoice(descriptor.key, choice.key, { label: event.target.value })
+        }
+        placeholder="Label"
+        className="min-w-0 flex-1"
+        aria-label="Choice label"
+      />
+      <label className="flex shrink-0 items-center gap-1.5 text-[11px] text-muted-foreground">
+        <Switch
+          size="sm"
+          checked={choice.isDefault}
+          onCheckedChange={(checked) =>
+            updateChoice(descriptor.key, choice.key, { isDefault: checked })
+          }
+          aria-label="Default choice"
+        />
+        Default
+      </label>
+      <Button
+        size="icon-micro"
+        variant="ghost-muted"
+        aria-label="Remove choice"
+        onClick={() =>
+          updateDescriptor(descriptor.key, {
+            choices: descriptor.choices.filter((candidate) => candidate.key !== choice.key),
+          })
+        }
+      >
+        <XIcon className="size-3" />
+      </Button>
+    </div>
+  );
+
+  const renderDescriptor = (descriptor: EditorDescriptor, index: number) => (
+    <div
+      key={descriptor.key}
+      className="flex flex-col gap-2 rounded-md border border-border/60 bg-background/40 p-2.5"
+    >
+      <div className="flex flex-wrap items-center gap-2">
+        <span className="w-14 shrink-0 text-[11px] text-muted-foreground">Option {index + 1}</span>
+        {presets.length > 0 ? (
+          <Select
+            value={idSelectValue(descriptor)}
+            onValueChange={(value) => applyPresetId(descriptor, value)}
+          >
+            <SelectTrigger size="compact" className="w-40" aria-label="Option id">
+              <SelectValue>
+                {idSelectValue(descriptor) === CUSTOM_ID_VALUE ? "Custom…" : descriptor.id}
+              </SelectValue>
+            </SelectTrigger>
+            <SelectPopup align="start" alignItemWithTrigger={false}>
+              {presets.map((preset) => (
+                <SelectItem key={preset.id} value={preset.id}>
+                  <span className="flex items-baseline gap-2">
+                    <code className="font-mono text-xs">{preset.id}</code>
+                    <span className="text-muted-foreground">{preset.label}</span>
+                  </span>
+                </SelectItem>
+              ))}
+              <SelectItem value={CUSTOM_ID_VALUE}>Custom…</SelectItem>
+            </SelectPopup>
+          </Select>
+        ) : null}
+        {idSelectValue(descriptor) === CUSTOM_ID_VALUE ? (
+          <Input
+            size="compact"
+            value={descriptor.id}
+            onChange={(event) => updateDescriptor(descriptor.key, { id: event.target.value })}
+            placeholder="optionId"
+            className="w-36 font-mono"
+            spellCheck={false}
+            aria-label="Option id"
+          />
+        ) : null}
+        <Input
+          size="compact"
+          value={descriptor.label}
+          onChange={(event) => updateDescriptor(descriptor.key, { label: event.target.value })}
+          placeholder="Label"
+          className="min-w-0 flex-1"
+          aria-label="Option label"
+        />
+        <Select
+          value={descriptor.type}
+          onValueChange={(value) =>
+            updateDescriptor(descriptor.key, { type: value === "boolean" ? "boolean" : "select" })
+          }
+        >
+          <SelectTrigger size="compact" className="w-24" aria-label="Option type">
+            <SelectValue>{descriptor.type === "boolean" ? "Toggle" : "Choices"}</SelectValue>
+          </SelectTrigger>
+          <SelectPopup align="end" alignItemWithTrigger={false}>
+            <SelectItem value="select">Choices</SelectItem>
+            <SelectItem value="boolean">Toggle</SelectItem>
+          </SelectPopup>
+        </Select>
+        <Button
+          size="icon-micro"
+          variant="ghost-muted"
+          aria-label={`Remove option ${index + 1}`}
+          onClick={() => removeDescriptor(descriptor.key)}
+        >
+          <XIcon className="size-3" />
+        </Button>
+      </div>
+      {descriptor.type === "select" ? (
+        <div className="flex flex-col gap-1.5 pl-16">
+          {descriptor.choices.map((choice) => renderChoice(descriptor, choice))}
+          <Button
+            type="button"
+            size="xs"
+            variant="ghost-muted"
+            className="-ml-2 self-start"
+            onClick={() =>
+              updateDescriptor(descriptor.key, {
+                choices: [...descriptor.choices, emptyEditorChoice()],
+              })
+            }
+          >
+            <PlusIcon className="size-3" />
+            Add choice
+          </Button>
+        </div>
+      ) : null}
+    </div>
+  );
+
+  return (
+    <div
+      className="mx-2 mt-1 mb-2 flex flex-col gap-3 rounded-md border border-border bg-muted/20 p-3"
+      onKeyDown={(event) => {
+        if (event.key === "Escape") {
+          event.preventDefault();
+          onCancel();
+        }
+      }}
+    >
+      <div className="flex flex-col gap-1">
+        <label htmlFor={domId("name")} className="text-xs text-muted-foreground">
+          Display name
+        </label>
+        <Input
+          id={domId("name")}
+          size="sm"
+          autoFocus
+          value={draft.name}
+          onChange={(event) => setDraft((current) => ({ ...current, name: event.target.value }))}
+          placeholder={draft.slug}
+          className="sm:w-72"
+          spellCheck={false}
+        />
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <div className="flex flex-wrap items-center justify-between gap-2">
+          <span className="text-xs text-muted-foreground">Options shown in the composer</span>
+          {startFromCandidates.length > 0 ? (
+            <Select value={START_FROM_NONE} onValueChange={handleStartFrom}>
+              <SelectTrigger
+                size="compact"
+                className="w-44"
+                aria-label="Copy options from a built-in model"
+              >
+                <SelectValue>Copy from…</SelectValue>
+              </SelectTrigger>
+              <SelectPopup align="end" alignItemWithTrigger={false}>
+                {startFromCandidates.map((model) => (
+                  <SelectItem key={model.slug} value={model.slug}>
+                    {model.name}
+                  </SelectItem>
+                ))}
+              </SelectPopup>
+            </Select>
+          ) : null}
+        </div>
+        {draft.descriptors.length === 0 ? (
+          <p className="text-xs text-muted-foreground/70">
+            No custom options. The composer uses the provider's default options.
+          </p>
+        ) : null}
+        {draft.descriptors.map(renderDescriptor)}
+        <div className="flex flex-wrap gap-1">
+          {presets
+            .filter(
+              (preset) => !draft.descriptors.some((descriptor) => descriptor.id === preset.id),
+            )
+            .map((preset) => (
+              <Button
+                key={preset.id}
+                type="button"
+                size="xs"
+                variant="ghost-muted"
+                className={cn("-ml-2 first:ml-0")}
+                onClick={() => addDescriptor(descriptorFromPreset(preset))}
+              >
+                <PlusIcon className="size-3" />
+                {preset.label}
+              </Button>
+            ))}
+          <Button
+            type="button"
+            size="xs"
+            variant="ghost-muted"
+            onClick={() => addDescriptor(emptyEditorDescriptor())}
+          >
+            <PlusIcon className="size-3" />
+            Custom option
+          </Button>
+        </div>
+      </div>
+
+      {error ? <p className="text-xs text-destructive">{error}</p> : null}
+
+      <div className="flex gap-2">
+        <Button size="sm" variant="outline" onClick={handleSave}>
+          Save
+        </Button>
+        <Button size="sm" variant="ghost" onClick={onCancel}>
+          Cancel
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/web/src/components/settings/ProviderInstanceCard.test.ts b/apps/web/src/components/settings/ProviderInstanceCard.test.ts
index ed62ff055b09..a5085774f0c6 100644
--- a/apps/web/src/components/settings/ProviderInstanceCard.test.ts
+++ b/apps/web/src/components/settings/ProviderInstanceCard.test.ts
@@ -36,11 +36,52 @@ describe("deriveProviderModelsForDisplay", () => {
     expect(
       deriveProviderModelsForDisplay({
         liveModels,
-        customModels: ["kept-custom"],
+        customModels: [{ slug: "kept-custom", name: "kept-custom", capabilities: null }],
       }).map((model) => model.slug),
     ).toEqual(["server-model", "kept-custom"]);
   });
 
+  it("prefers the entry's name and capabilities over the stale live custom row", () => {
+    const liveCapabilities = { optionDescriptors: [] };
+    const customCapabilities = {
+      optionDescriptors: [
+        {
+          id: "reasoningEffort",
+          label: "Reasoning",
+          type: "select" as const,
+          options: [{ id: "high", label: "High", isDefault: true }],
+          currentValue: "high",
+        },
+      ],
+    };
+    const liveModels: ReadonlyArray<ServerProviderModel> = [
+      { slug: "bare", name: "bare", isCustom: true, capabilities: liveCapabilities },
+      { slug: "named", name: "named", isCustom: true, capabilities: liveCapabilities },
+    ];
+
+    const display = deriveProviderModelsForDisplay({
+      liveModels,
+      customModels: [
+        { slug: "bare", name: "bare", capabilities: null },
+        { slug: "named", name: "My Model", capabilities: customCapabilities },
+      ],
+    });
+
+    // A bare entry keeps the driver default the server filled in.
+    expect(display[0]).toEqual({
+      slug: "bare",
+      name: "bare",
+      isCustom: true,
+      capabilities: liveCapabilities,
+    });
+    expect(display[1]).toEqual({
+      slug: "named",
+      name: "My Model",
+      isCustom: true,
+      capabilities: customCapabilities,
+    });
+  });
+
   it("shows a redacted provider email in the editor header status line", () => {
     const instanceId = ProviderInstanceId.make("codex");
     const driver = ProviderDriverKind.make("codex");
diff --git a/apps/web/src/components/settings/ProviderInstanceCard.tsx b/apps/web/src/components/settings/ProviderInstanceCard.tsx
index 942d146e929f..5c96de9d0545 100644
--- a/apps/web/src/components/settings/ProviderInstanceCard.tsx
+++ b/apps/web/src/components/settings/ProviderInstanceCard.tsx
@@ -25,6 +25,11 @@ import {
   type ServerProviderModel,
 } from "@t3tools/contracts";
 
+import {
+  type CustomModelDefinition,
+  readCustomModelEntries,
+  toCustomModelSetting,
+} from "@t3tools/shared/model";
 import { cn } from "../../lib/utils";
 import { useCopyToClipboard } from "../../hooks/useCopyToClipboard";
 import { normalizeProviderAccentColor } from "../../providerInstances";
@@ -96,16 +101,13 @@ function providerEnvironmentsEqual(
 }
 
 /**
- * Read a string[] at `key` from the opaque config blob, filtering out
- * non-string entries. Used for `customModels`, which is always typed as
- * `string[]` by the concrete driver schemas but arrives here as
- * `Schema.Unknown`.
+ * Read `customModels` from the opaque config blob. The concrete driver
+ * schemas type it as `CustomModelSetting[]`, but it arrives here as
+ * `Schema.Unknown`, so the shared reader does the shape checking.
  */
-function readConfigStringArray(config: unknown, key: string): ReadonlyArray<string> {
+function readConfigCustomModels(config: unknown): ReadonlyArray<CustomModelDefinition> {
   if (config === null || typeof config !== "object") return [];
-  const value = (config as Record<string, unknown>)[key];
-  if (!Array.isArray(value)) return [];
-  return value.filter((entry): entry is string => typeof entry === "string");
+  return readCustomModelEntries((config as Record<string, unknown>).customModels);
 }
 
 /**
@@ -127,9 +129,14 @@ function nextConfigBlobWithValue(
   return base;
 }
 
+/**
+ * Custom rows come from current settings so name/descriptor edits show
+ * instantly; a bare entry falls back to the live row's driver-default
+ * capabilities (the server fills those in on its next probe).
+ */
 export function deriveProviderModelsForDisplay(input: {
   readonly liveModels: ReadonlyArray<ServerProviderModel> | undefined;
-  readonly customModels: ReadonlyArray<string>;
+  readonly customModels: ReadonlyArray<CustomModelDefinition>;
 }): ReadonlyArray<ServerProviderModel> {
   const liveCustomModelsBySlug = new Map(
     Arr.filterMap(input.liveModels ?? [], (model) =>
@@ -137,15 +144,13 @@ export function deriveProviderModelsForDisplay(input: {
     ),
   );
   const serverModels = input.liveModels?.filter((model) => !model.isCustom) ?? [];
-  const customModels = input.customModels.map(
-    (slug) =>
-      liveCustomModelsBySlug.get(slug) ?? {
-        slug,
-        name: slug,
-        isCustom: true,
-        capabilities: null,
-      },
-  );
+  const customModels = input.customModels.map((entry) => ({
+    slug: entry.slug,
+    name: entry.name,
+    isCustom: true,
+    capabilities:
+      entry.capabilities ?? liveCustomModelsBySlug.get(entry.slug)?.capabilities ?? null,
+  }));
   return [...serverModels, ...customModels];
 }
 
@@ -463,7 +468,7 @@ export function ProviderInstanceCard({
     ? instance.driver
     : null;
   const customModels =
-    instance.driver === "antigravity" ? [] : readConfigStringArray(instance.config, "customModels");
+    instance.driver === "antigravity" ? [] : readConfigCustomModels(instance.config);
   // Server-returned models may lag behind settings writes. Treat probe
   // models as the source for built-ins only; custom rows come directly
   // from the current instance config so add/remove reflects immediately.
@@ -504,8 +509,12 @@ export function ProviderInstanceCard({
     );
   };
 
-  const updateCustomModels = (next: ReadonlyArray<string>) => {
-    const nextConfig = nextConfigBlobWithValue(instance.config, "customModels", [...next]);
+  const updateCustomModels = (next: ReadonlyArray<CustomModelDefinition>) => {
+    const nextConfig = nextConfigBlobWithValue(
+      instance.config,
+      "customModels",
+      next.map(toCustomModelSetting),
+    );
     const { config: _omit, ...rest } = instance;
     onUpdate({ ...rest, config: nextConfig } as ProviderInstanceConfig);
   };
diff --git a/apps/web/src/components/settings/ProviderModelsSection.tsx b/apps/web/src/components/settings/ProviderModelsSection.tsx
index 7b98dbe42991..7866578cfa4a 100644
--- a/apps/web/src/components/settings/ProviderModelsSection.tsx
+++ b/apps/web/src/components/settings/ProviderModelsSection.tsx
@@ -1,13 +1,13 @@
 "use client";
 
-import { ArrowDownIcon, ArrowUpIcon, PlusIcon, StarIcon, XIcon } from "lucide-react";
+import { ArrowDownIcon, ArrowUpIcon, PencilIcon, PlusIcon, StarIcon, XIcon } from "lucide-react";
 import { useEffect, useMemo, useRef, useState } from "react";
 import {
   ProviderDriverKind,
   type ProviderInstanceId,
   type ServerProviderModel,
 } from "@t3tools/contracts";
-import { normalizeCustomModelSlug } from "@t3tools/shared/model";
+import { type CustomModelDefinition, normalizeCustomModelSlug } from "@t3tools/shared/model";
 
 import { cn } from "../../lib/utils";
 import { sortModelsForProviderInstance } from "../../modelOrdering";
@@ -16,6 +16,7 @@ import { Button } from "../ui/button";
 import { Input } from "../ui/input";
 import { Switch } from "../ui/switch";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
+import { CustomModelEditor } from "./CustomModelEditor";
 
 /**
  * Placeholder text for the "add a custom model" input, keyed by driver
@@ -109,11 +110,11 @@ interface ProviderModelsSectionProps {
    */
   readonly models: ReadonlyArray<ServerProviderModel>;
   /**
-   * The persisted custom-model slug list for this instance. Drives dedup,
-   * and is the array we hand back verbatim (with the new slug appended /
+   * The persisted custom-model list for this instance, resolved. Drives
+   * dedup, and is the list we hand back (with an entry appended / replaced /
    * removed) via `onChange`.
    */
-  readonly customModels: ReadonlyArray<string>;
+  readonly customModels: ReadonlyArray<CustomModelDefinition>;
   /** Server-returned model slugs hidden from the model picker. */
   readonly hiddenModels: ReadonlyArray<string>;
   /** Model slugs favorited for this provider instance. */
@@ -125,7 +126,7 @@ interface ProviderModelsSectionProps {
    * write to the correct storage (legacy `settings.providers[kind]` vs.
    * `providerInstances[id].config`).
    */
-  readonly onChange: (next: ReadonlyArray<string>) => void;
+  readonly onChange: (next: ReadonlyArray<CustomModelDefinition>) => void;
   readonly onHiddenModelsChange: (next: ReadonlyArray<string>) => void;
   readonly onFavoriteModelsChange: (next: ReadonlyArray<string>) => void;
   readonly onModelOrderChange: (next: ReadonlyArray<string>) => void;
@@ -159,6 +160,8 @@ export function ProviderModelsSection({
   const [isAdding, setIsAdding] = useState(false);
   const [filter, setFilter] = useState("");
   const [error, setError] = useState<string | null>(null);
+  // Slug of the custom model whose inline editor is open, if any.
+  const [editingSlug, setEditingSlug] = useState<string | null>(null);
   const listRef = useRef<HTMLDivElement>(null);
   // Slug of a just-added custom model, scrolled into view once its row exists.
   const scrollToSlugRef = useRef<string | null>(null);
@@ -177,6 +180,7 @@ export function ProviderModelsSection({
   const hiddenCount = displayModels.filter(
     (model) => !model.isCustom && hiddenModelSet.has(model.slug),
   ).length;
+  const builtInModels = useMemo(() => models.filter((model) => !model.isCustom), [models]);
   const showFilter = models.length > FILTER_THRESHOLD;
   const normalizedFilter = filter.trim().toLowerCase();
   const isFiltering = showFilter && normalizedFilter.length > 0;
@@ -216,7 +220,7 @@ export function ProviderModelsSection({
       setError(`Model slugs must be ${MAX_CUSTOM_MODEL_LENGTH} characters or less.`);
       return;
     }
-    if (customModels.includes(normalized)) {
+    if (customModels.some((entry) => entry.slug === normalized)) {
       setError("That custom model is already saved.");
       return;
     }
@@ -225,7 +229,7 @@ export function ProviderModelsSection({
     // which is also what lets the pending scroll target resolve and clear.
     scrollToSlugRef.current = normalized;
     setFilter("");
-    onChange([...customModels, normalized]);
+    onChange([...customModels, { slug: normalized, name: normalized, capabilities: null }]);
     setInput("");
     setError(null);
     setIsAdding(false);
@@ -238,12 +242,18 @@ export function ProviderModelsSection({
   };
 
   const handleRemove = (slug: string) => {
-    onChange(customModels.filter((model) => model !== slug));
+    if (editingSlug === slug) setEditingSlug(null);
+    onChange(customModels.filter((entry) => entry.slug !== slug));
     onModelOrderChange(modelOrder.filter((model) => model !== slug));
     onFavoriteModelsChange(favoriteModels.filter((model) => model !== slug));
     setError(null);
   };
 
+  const handleSaveEdit = (next: CustomModelDefinition) => {
+    onChange(customModels.map((entry) => (entry.slug === next.slug ? next : entry)));
+    setEditingSlug(null);
+  };
+
   const setHidden = (slug: string, hidden: boolean) => {
     if (hidden === hiddenModelSet.has(slug)) return;
     onHiddenModelsChange(
@@ -355,21 +365,40 @@ export function ProviderModelsSection({
         </>
       ) : null}
       {model.isCustom ? (
-        <Tooltip>
-          <TooltipTrigger
-            render={
-              <Button
-                size="icon-micro"
-                variant="ghost-muted"
-                aria-label={`Remove ${model.slug}`}
-                onClick={() => handleRemove(model.slug)}
-              />
-            }
-          >
-            <XIcon className="size-3" />
-          </TooltipTrigger>
-          <TooltipPopup side="top">Remove custom model</TooltipPopup>
-        </Tooltip>
+        <>
+          <Tooltip>
+            <TooltipTrigger
+              render={
+                <Button
+                  size="icon-micro"
+                  variant="ghost-muted"
+                  aria-label={`Edit ${model.slug}`}
+                  onClick={() =>
+                    setEditingSlug((current) => (current === model.slug ? null : model.slug))
+                  }
+                />
+              }
+            >
+              <PencilIcon className="size-3" />
+            </TooltipTrigger>
+            <TooltipPopup side="top">Edit name and options</TooltipPopup>
+          </Tooltip>
+          <Tooltip>
+            <TooltipTrigger
+              render={
+                <Button
+                  size="icon-micro"
+                  variant="ghost-muted"
+                  aria-label={`Remove ${model.slug}`}
+                  onClick={() => handleRemove(model.slug)}
+                />
+              }
+            >
+              <XIcon className="size-3" />
+            </TooltipTrigger>
+            <TooltipPopup side="top">Remove custom model</TooltipPopup>
+          </Tooltip>
+        </>
       ) : null}
     </span>
   );
@@ -420,20 +449,23 @@ export function ProviderModelsSection({
         key={`${instanceId}:${model.slug}`}
         data-model-slug={model.slug}
         className={cn(
-          "grid h-7 grid-cols-[1.5rem_minmax(0,1fr)_auto_4rem_auto] items-center gap-2 rounded-md px-2 transition-colors hover:bg-muted/30",
+          // Actions column is at least wide enough for the four custom-row
+          // buttons so capability labels line up across built-in and custom rows.
+          "grid h-7 grid-cols-[1.5rem_minmax(0,1fr)_auto_minmax(5.5rem,auto)_auto] items-center gap-2 rounded-md px-2 transition-colors hover:bg-muted/30",
           isHidden && "opacity-50",
         )}
       >
         {starButton(model, isFavorite)}
         <span className="flex min-w-0 items-baseline gap-2">
           <span className={cn(nameClassName, "truncate")}>{model.name}</span>
-          {model.isCustom ? (
-            <span className="text-[11px] text-muted-foreground/70">custom</span>
-          ) : model.name !== model.slug ? (
+          {model.name !== model.slug ? (
             <code className="truncate font-mono text-[11px] text-muted-foreground/70">
               {model.slug}
             </code>
           ) : null}
+          {model.isCustom ? (
+            <span className="text-[11px] text-muted-foreground/70">custom</span>
+          ) : null}
         </span>
         {/*
           Always a grid item so the columns line up across rows; the text
@@ -489,6 +521,10 @@ export function ProviderModelsSection({
           const group = groupOf(model);
           const previous = visibleModels[index - 1];
           const startsGroup = previous === undefined || groupOf(previous) !== group;
+          const editingEntry =
+            model.isCustom && editingSlug === model.slug
+              ? customModels.find((entry) => entry.slug === model.slug)
+              : undefined;
           return (
             <div key={`${instanceId}:${model.slug}:group`}>
               {startsGroup && favoriteCount > 0 && group === "favorite"
@@ -501,6 +537,17 @@ export function ProviderModelsSection({
                 ? groupLabel("Hidden from picker", index === 0)
                 : null}
               {renderRow(model)}
+              {editingEntry ? (
+                <CustomModelEditor
+                  key={`${instanceId}:${model.slug}:editor`}
+                  instanceId={instanceId}
+                  driverKind={driverKind}
+                  entry={editingEntry}
+                  builtInModels={builtInModels}
+                  onSave={handleSaveEdit}
+                  onCancel={() => setEditingSlug(null)}
+                />
+              ) : null}
             </div>
           );
         })}
diff --git a/apps/web/src/components/settings/customModelEditor.logic.test.ts b/apps/web/src/components/settings/customModelEditor.logic.test.ts
new file mode 100644
index 000000000000..dba4d7af7bbd
--- /dev/null
+++ b/apps/web/src/components/settings/customModelEditor.logic.test.ts
@@ -0,0 +1,259 @@
+import { describe, expect, it } from "vite-plus/test";
+import { ProviderDriverKind, type ModelCapabilities } from "@t3tools/contracts";
+
+import {
+  DESCRIPTOR_PRESETS_BY_KIND,
+  descriptorFromPreset,
+  definitionFromDraft,
+  descriptorsFromCapabilities,
+  draftFromDefinition,
+  validateDraft,
+  type CustomModelDraft,
+} from "./customModelEditor.logic";
+
+const draft = (overrides: Partial<CustomModelDraft>): CustomModelDraft => ({
+  slug: "my-model",
+  name: "",
+  descriptors: [],
+  ...overrides,
+});
+
+describe("customModelEditor.logic", () => {
+  it("round-trips a definition through the draft, marking the current value as default", () => {
+    const definition = definitionFromDraft(
+      draft({
+        name: " My Model ",
+        descriptors: [
+          {
+            key: "a",
+            type: "select",
+            id: "reasoningEffort",
+            label: "Reasoning",
+            choices: [
+              { key: "a1", id: "low", label: "Low", isDefault: false },
+              { key: "a2", id: "high", label: "", isDefault: true },
+            ],
+          },
+          { key: "b", type: "boolean", id: "fastMode", label: "Fast Mode", choices: [] },
+        ],
+      }),
+    );
+
+    expect(definition).toEqual({
+      slug: "my-model",
+      name: "My Model",
+      capabilities: {
+        optionDescriptors: [
+          {
+            id: "reasoningEffort",
+            label: "Reasoning",
+            type: "select",
+            options: [
+              { id: "low", label: "Low" },
+              { id: "high", label: "high", isDefault: true },
+            ],
+            currentValue: "high",
+          },
+          { id: "fastMode", label: "Fast Mode", type: "boolean" },
+        ],
+      },
+    });
+
+    const reopened = draftFromDefinition(definition);
+    expect(reopened.name).toBe("My Model");
+    expect(reopened.descriptors.map((descriptor) => descriptor.id)).toEqual([
+      "reasoningEffort",
+      "fastMode",
+    ]);
+    expect(reopened.descriptors[0]!.choices.map((choice) => choice.isDefault)).toEqual([
+      false,
+      true,
+    ]);
+  });
+
+  it("preserves the current choice when it differs from the built-in default", () => {
+    const descriptors = descriptorsFromCapabilities(
+      {
+        optionDescriptors: [
+          {
+            id: "effort",
+            label: "Reasoning",
+            type: "select",
+            currentValue: "high",
+            options: [
+              { id: "low", label: "Low", isDefault: true },
+              { id: "high", label: "High" },
+            ],
+          },
+        ],
+      },
+      ProviderDriverKind.make("claudeAgent"),
+    );
+    expect(descriptors[0]!.choices.map((choice) => choice.isDefault)).toEqual([false, true]);
+    expect(
+      definitionFromDraft(draft({ descriptors })).capabilities?.optionDescriptors?.[0],
+    ).toMatchObject({ currentValue: "high" });
+  });
+
+  it("drops prompt-injected choices when copying a built-in's descriptors", () => {
+    const [copied] = descriptorsFromCapabilities(
+      {
+        optionDescriptors: [
+          {
+            id: "effort",
+            label: "Reasoning",
+            type: "select",
+            options: [
+              { id: "high", label: "High", isDefault: true },
+              { id: "ultrathink", label: "Ultrathink" },
+            ],
+            promptInjectedValues: ["ultrathink"],
+          },
+        ],
+      },
+      ProviderDriverKind.make("claudeAgent"),
+    );
+    expect(copied!.choices.map((choice) => choice.id)).toEqual(["high"]);
+  });
+
+  it.each([true, false, undefined])(
+    "preserves boolean values through copy and edit: %s",
+    (currentValue) => {
+      const capabilities: ModelCapabilities = {
+        optionDescriptors: [
+          {
+            id: "thinking",
+            label: "Thinking",
+            type: "boolean",
+            ...(currentValue !== undefined ? { currentValue } : {}),
+          },
+        ],
+      };
+      const copied = definitionFromDraft(
+        draft({
+          descriptors: descriptorsFromCapabilities(capabilities, ProviderDriverKind.make("cursor")),
+        }),
+      );
+      expect(copied.capabilities).toEqual(capabilities);
+      const reopened = draftFromDefinition(copied);
+      expect(definitionFromDraft({ ...reopened, name: "Renamed" }).capabilities).toEqual(
+        capabilities,
+      );
+    },
+  );
+
+  it("excludes Claude context choices from presets and copies without changing other providers or authored entries", () => {
+    const capabilities: ModelCapabilities = {
+      optionDescriptors: [
+        {
+          id: "contextWindow",
+          label: "Context",
+          type: "select",
+          options: [{ id: "1m", label: "1M", isDefault: true }],
+        },
+        { id: "thinking", label: "Thinking", type: "boolean", currentValue: true },
+      ],
+    };
+    const claude = ProviderDriverKind.make("claudeAgent");
+    const copied = definitionFromDraft(
+      draft({ descriptors: descriptorsFromCapabilities(capabilities, claude) }),
+    );
+    expect(copied.capabilities?.optionDescriptors).toEqual([capabilities.optionDescriptors![1]]);
+    const presets = definitionFromDraft(
+      draft({
+        descriptors: (DESCRIPTOR_PRESETS_BY_KIND[claude] ?? []).map(descriptorFromPreset),
+      }),
+    );
+    expect(
+      presets.capabilities?.optionDescriptors?.some((option) => option.id === "contextWindow"),
+    ).toBe(false);
+    const cursorCopy = descriptorsFromCapabilities(capabilities, ProviderDriverKind.make("cursor"));
+    expect(cursorCopy.map((option) => option.id)).toEqual(["contextWindow", "thinking"]);
+    const authored = { slug: "custom", name: "Custom", capabilities };
+    expect(
+      definitionFromDraft(draftFromDefinition(authored)).capabilities?.optionDescriptors?.[0],
+    ).toMatchObject(capabilities.optionDescriptors![0]!);
+  });
+
+  it("preserves choice descriptions when copying, renaming, and saving", () => {
+    const capabilities: ModelCapabilities = {
+      optionDescriptors: [
+        {
+          id: "effort",
+          label: "Reasoning",
+          description: "Choose a reasoning level.",
+          type: "select",
+          options: [
+            { id: "high", label: "High", isDefault: true },
+            { id: "ultracode", label: "Ultracode", description: "Uses additional reasoning." },
+          ],
+        },
+      ],
+    };
+    const copied = definitionFromDraft(
+      draft({
+        descriptors: descriptorsFromCapabilities(
+          capabilities,
+          ProviderDriverKind.make("claudeAgent"),
+        ),
+      }),
+    );
+    const reopened = draftFromDefinition(copied);
+    const saved = definitionFromDraft({ ...reopened, name: "Renamed" });
+    expect(saved.capabilities?.optionDescriptors?.[0]).toMatchObject(
+      capabilities.optionDescriptors![0]!,
+    );
+    expect(copied.capabilities?.optionDescriptors?.[0]).toMatchObject(
+      capabilities.optionDescriptors![0]!,
+    );
+  });
+
+  it.each(Object.entries(DESCRIPTOR_PRESETS_BY_KIND))(
+    "offers saveable presets for %s",
+    (_driver, presets) => {
+      expect(
+        validateDraft(draft({ descriptors: (presets ?? []).map(descriptorFromPreset) })),
+      ).toBeNull();
+    },
+  );
+
+  it("collapses a blank name and no options back to a bare definition", () => {
+    expect(definitionFromDraft(draft({ name: "  " }))).toEqual({
+      slug: "my-model",
+      name: "my-model",
+      capabilities: null,
+    });
+    expect(draftFromDefinition({ slug: "x", name: "x", capabilities: null }).name).toBe("");
+  });
+
+  it("rejects duplicate ids, blank ids, and selects without choices", () => {
+    const select = (id: string, choices: Array<{ id: string }>) => ({
+      key: id,
+      type: "select" as const,
+      id,
+      label: "Label",
+      choices: choices.map((choice) => ({
+        key: choice.id,
+        label: "",
+        isDefault: false,
+        ...choice,
+      })),
+    });
+
+    expect(validateDraft(draft({ descriptors: [select("", [{ id: "a" }])] }))).toBe(
+      "Option 1 needs an id.",
+    );
+    expect(
+      validateDraft(
+        draft({ descriptors: [select("effort", [{ id: "a" }]), select("effort", [{ id: "b" }])] }),
+      ),
+    ).toBe('Option 2: id "effort" is used twice.');
+    expect(validateDraft(draft({ descriptors: [select("effort", [])] }))).toBe(
+      "Option 1 needs at least one choice.",
+    );
+    expect(
+      validateDraft(draft({ descriptors: [select("effort", [{ id: "a" }, { id: "a" }])] })),
+    ).toBe('Option 1: choice "a" is used twice.');
+    expect(validateDraft(draft({ descriptors: [select("effort", [{ id: "a" }])] }))).toBeNull();
+  });
+});
diff --git a/apps/web/src/components/settings/customModelEditor.logic.ts b/apps/web/src/components/settings/customModelEditor.logic.ts
new file mode 100644
index 000000000000..0d48057206df
--- /dev/null
+++ b/apps/web/src/components/settings/customModelEditor.logic.ts
@@ -0,0 +1,258 @@
+import {
+  type ModelCapabilities,
+  ProviderDriverKind,
+  type ProviderOptionDescriptor,
+} from "@t3tools/contracts";
+import { type CustomModelDefinition, createModelCapabilities } from "@t3tools/shared/model";
+
+/** Editable mirror of a `ProviderOptionChoice`. `key` is only a React key. */
+export interface EditorChoice {
+  readonly key: string;
+  readonly id: string;
+  readonly label: string;
+  readonly isDefault: boolean;
+  readonly description?: string;
+}
+
+/** Editable mirror of a `ProviderOptionDescriptor`. `key` is only a React key. */
+export interface EditorDescriptor {
+  readonly key: string;
+  readonly type: "select" | "boolean";
+  readonly id: string;
+  readonly label: string;
+  readonly choices: ReadonlyArray<EditorChoice>;
+  readonly currentBooleanValue?: boolean | undefined;
+  readonly description?: string | undefined;
+}
+
+export interface CustomModelDraft {
+  readonly slug: string;
+  readonly name: string;
+  readonly descriptors: ReadonlyArray<EditorDescriptor>;
+}
+
+export interface DescriptorPreset {
+  readonly id: string;
+  readonly label: string;
+  readonly type: "select" | "boolean";
+  readonly choices?: ReadonlyArray<{ id: string; label: string; isDefault?: boolean }>;
+}
+
+const EFFORT_CHOICES = [
+  { id: "low", label: "Low" },
+  { id: "medium", label: "Medium", isDefault: true },
+  { id: "high", label: "High" },
+  { id: "xhigh", label: "Extra High" },
+] as const;
+
+/**
+ * Option ids each adapter actually reads off a turn's model selection, with
+ * the usual choices pre-filled. Anything else the user types is stored
+ * verbatim but will be ignored by the driver.
+ */
+export const DESCRIPTOR_PRESETS_BY_KIND: Partial<
+  Record<ProviderDriverKind, ReadonlyArray<DescriptorPreset>>
+> = {
+  [ProviderDriverKind.make("codex")]: [
+    { id: "reasoningEffort", label: "Reasoning", type: "select", choices: EFFORT_CHOICES },
+    {
+      id: "serviceTier",
+      label: "Speed",
+      type: "select",
+      choices: [
+        { id: "default", label: "Standard", isDefault: true },
+        { id: "fast", label: "Fast" },
+      ],
+    },
+  ],
+  [ProviderDriverKind.make("claudeAgent")]: [
+    {
+      id: "effort",
+      label: "Reasoning",
+      type: "select",
+      choices: [
+        { id: "low", label: "Low" },
+        { id: "medium", label: "Medium" },
+        { id: "high", label: "High", isDefault: true },
+        { id: "xhigh", label: "Extra High" },
+        { id: "max", label: "Max" },
+      ],
+    },
+    { id: "fastMode", label: "Fast Mode", type: "boolean" },
+    { id: "thinking", label: "Thinking", type: "boolean" },
+  ],
+  [ProviderDriverKind.make("cursor")]: [
+    { id: "reasoning", label: "Reasoning", type: "select", choices: EFFORT_CHOICES },
+    { id: "fastMode", label: "Fast Mode", type: "boolean" },
+    { id: "thinking", label: "Thinking", type: "boolean" },
+  ],
+  [ProviderDriverKind.make("grok")]: [
+    { id: "reasoningEffort", label: "Reasoning", type: "select", choices: EFFORT_CHOICES },
+  ],
+  [ProviderDriverKind.make("opencode")]: [
+    { id: "variant", label: "Reasoning", type: "select", choices: EFFORT_CHOICES },
+    {
+      id: "agent",
+      label: "Agent",
+      type: "select",
+      choices: [
+        { id: "build", label: "Build", isDefault: true },
+        { id: "plan", label: "Plan" },
+      ],
+    },
+  ],
+};
+
+let nextKey = 0;
+export function newEditorKey(): string {
+  nextKey += 1;
+  return `k${nextKey}`;
+}
+
+export function choiceFromPreset(choice: {
+  id: string;
+  label: string;
+  isDefault?: boolean;
+}): EditorChoice {
+  return { key: newEditorKey(), id: choice.id, label: choice.label, isDefault: !!choice.isDefault };
+}
+
+export function descriptorFromPreset(preset: DescriptorPreset): EditorDescriptor {
+  return {
+    key: newEditorKey(),
+    type: preset.type,
+    id: preset.id,
+    label: preset.label,
+    choices: (preset.choices ?? []).map(choiceFromPreset),
+  };
+}
+
+export function emptyEditorDescriptor(): EditorDescriptor {
+  return { key: newEditorKey(), type: "select", id: "", label: "", choices: [] };
+}
+
+export function emptyEditorChoice(): EditorChoice {
+  return { key: newEditorKey(), id: "", label: "", isDefault: false };
+}
+
+/**
+ * Prompt-injected choices (Claude's `ultrathink`) are delivered as prompt text
+ * by built-in runtime profiles a custom entry does not have, so they are
+ * dropped rather than stored as a plain option value.
+ */
+export function descriptorToEditor(descriptor: ProviderOptionDescriptor): EditorDescriptor {
+  const promptInjected = new Set(
+    descriptor.type === "select" ? (descriptor.promptInjectedValues ?? []) : [],
+  );
+  const choices =
+    descriptor.type === "select"
+      ? descriptor.options.filter((option) => !promptInjected.has(option.id))
+      : [];
+  const defaultChoice =
+    choices.find((option) => option.id === descriptor.currentValue) ??
+    choices.find((option) => option.isDefault);
+  return {
+    key: newEditorKey(),
+    type: descriptor.type,
+    id: descriptor.id,
+    label: descriptor.label,
+    ...(descriptor.description !== undefined ? { description: descriptor.description } : {}),
+    ...(descriptor.type === "boolean" && descriptor.currentValue !== undefined
+      ? { currentBooleanValue: descriptor.currentValue }
+      : {}),
+    choices: choices.map((option) => ({
+      key: newEditorKey(),
+      id: option.id,
+      label: option.label,
+      ...(option.description !== undefined ? { description: option.description } : {}),
+      isDefault: option === defaultChoice,
+    })),
+  };
+}
+
+export function draftFromDefinition(entry: CustomModelDefinition): CustomModelDraft {
+  return {
+    slug: entry.slug,
+    name: entry.name === entry.slug ? "" : entry.name,
+    descriptors: (entry.capabilities?.optionDescriptors ?? []).map(descriptorToEditor),
+  };
+}
+
+/** Claude context choices require runtime suffix mappings that custom entries do not carry. */
+export function descriptorsFromCapabilities(
+  capabilities: ModelCapabilities | null | undefined,
+  driverKind: ProviderDriverKind | null,
+): EditorDescriptor[] {
+  return (capabilities?.optionDescriptors ?? [])
+    .filter((descriptor) => driverKind !== "claudeAgent" || descriptor.id !== "contextWindow")
+    .map(descriptorToEditor);
+}
+
+/**
+ * Validate the draft before saving. Returns the first problem in reading
+ * order so the message is actionable, or `null` when the draft is sound.
+ */
+export function validateDraft(draft: CustomModelDraft): string | null {
+  const seenIds = new Set<string>();
+  for (const [index, descriptor] of draft.descriptors.entries()) {
+    const position = `Option ${index + 1}`;
+    const id = descriptor.id.trim();
+    if (!id) return `${position} needs an id.`;
+    if (seenIds.has(id)) return `${position}: id "${id}" is used twice.`;
+    seenIds.add(id);
+    if (!descriptor.label.trim()) return `${position} needs a label.`;
+    if (descriptor.type !== "select") continue;
+    if (descriptor.choices.length === 0) return `${position} needs at least one choice.`;
+    const seenChoices = new Set<string>();
+    for (const choice of descriptor.choices) {
+      const choiceId = choice.id.trim();
+      if (!choiceId) return `${position} has a choice without a value.`;
+      if (seenChoices.has(choiceId)) {
+        return `${position}: choice "${choiceId}" is used twice.`;
+      }
+      seenChoices.add(choiceId);
+    }
+  }
+  return null;
+}
+
+/** Convert a validated draft back into a definition. Blank name → slug. */
+export function definitionFromDraft(draft: CustomModelDraft): CustomModelDefinition {
+  const descriptors: ProviderOptionDescriptor[] = draft.descriptors.map((descriptor) => {
+    const id = descriptor.id.trim();
+    const label = descriptor.label.trim();
+    if (descriptor.type === "boolean") {
+      return {
+        id,
+        label,
+        type: "boolean",
+        ...(descriptor.description !== undefined ? { description: descriptor.description } : {}),
+        ...(descriptor.currentBooleanValue !== undefined
+          ? { currentValue: descriptor.currentBooleanValue }
+          : {}),
+      };
+    }
+    const options = descriptor.choices.map((choice) => ({
+      id: choice.id.trim(),
+      label: choice.label.trim() || choice.id.trim(),
+      ...(choice.description !== undefined ? { description: choice.description } : {}),
+      ...(choice.isDefault ? { isDefault: true } : {}),
+    }));
+    const currentValue = options.find((option) => option.isDefault)?.id;
+    return {
+      id,
+      label,
+      type: "select",
+      ...(descriptor.description !== undefined ? { description: descriptor.description } : {}),
+      options,
+      ...(currentValue ? { currentValue } : {}),
+    };
+  });
+  const name = draft.name.trim();
+  return {
+    slug: draft.slug,
+    name: name || draft.slug,
+    capabilities:
+      descriptors.length > 0 ? createModelCapabilities({ optionDescriptors: descriptors }) : null,
+  };
+}
diff --git a/apps/web/src/modelSelection.ts b/apps/web/src/modelSelection.ts
index 64937a442e7a..4ff195083d51 100644
--- a/apps/web/src/modelSelection.ts
+++ b/apps/web/src/modelSelection.ts
@@ -10,8 +10,10 @@ import {
   type ServerSettingsPatch,
 } from "@t3tools/contracts";
 import {
+  type CustomModelDefinition,
   createModelSelection,
   normalizeCustomModelSlug,
+  readCustomModelEntries,
   resolveSelectableModel,
 } from "@t3tools/shared/model";
 import { getComposerProviderState } from "./components/chat/composerProviderState";
@@ -55,14 +57,14 @@ function readInstanceCustomModels(
   settings: UnifiedSettings,
   instanceId: ProviderInstanceId,
   driverKind: ProviderDriverKind,
-): ReadonlyArray<string> {
+): ReadonlyArray<CustomModelDefinition> {
   if (driverKind === "antigravity") return [];
   const instance = settings.providerInstances?.[instanceId];
   const config = instance?.config;
   if (config !== null && typeof config === "object") {
     const value = (config as Record<string, unknown>).customModels;
     if (Array.isArray(value)) {
-      return value.filter((entry): entry is string => typeof entry === "string");
+      return readCustomModelEntries(value);
     }
   }
   const defaultInstanceId = defaultInstanceIdForDriver(driverKind);
@@ -71,9 +73,9 @@ function readInstanceCustomModels(
   }
   const legacyProviders = settings.providers as Record<
     string,
-    { readonly customModels: ReadonlyArray<string> } | undefined
+    { readonly customModels: ReadonlyArray<unknown> } | undefined
   >;
-  return legacyProviders[driverKind]?.customModels ?? [];
+  return readCustomModelEntries(legacyProviders[driverKind]?.customModels ?? []);
 }
 
 export interface AppModelOption {
@@ -151,26 +153,24 @@ function applyInstanceModelPreferences(
   );
 }
 
-export function normalizeCustomModelSlugs(
-  models: Iterable<string | null | undefined>,
+export function normalizeCustomModelEntries(
+  models: ReadonlyArray<CustomModelDefinition>,
   builtInModelSlugs: ReadonlySet<string>,
-): string[] {
-  const normalizedModels: string[] = [];
+): CustomModelDefinition[] {
+  const normalizedModels: CustomModelDefinition[] = [];
   const seen = new Set<string>();
 
   for (const candidate of models) {
-    const normalized = normalizeCustomModelSlug(candidate);
     if (
-      !normalized ||
-      normalized.length > MAX_CUSTOM_MODEL_LENGTH ||
-      builtInModelSlugs.has(normalized) ||
-      seen.has(normalized)
+      candidate.slug.length > MAX_CUSTOM_MODEL_LENGTH ||
+      builtInModelSlugs.has(candidate.slug) ||
+      seen.has(candidate.slug)
     ) {
       continue;
     }
 
-    seen.add(normalized);
-    normalizedModels.push(normalized);
+    seen.add(candidate.slug);
+    normalizedModels.push(candidate);
     if (normalizedModels.length >= MAX_CUSTOM_MODEL_COUNT) {
       break;
     }
@@ -205,17 +205,13 @@ export function getAppModelOptions(
   // see the user's authored custom models.
   const defaultInstanceId = defaultInstanceIdForDriver(provider);
   const customModels = readInstanceCustomModels(settings, defaultInstanceId, provider);
-  for (const slug of normalizeCustomModelSlugs(customModels, builtInModelSlugs)) {
-    if (seen.has(slug)) {
+  for (const entry of normalizeCustomModelEntries(customModels, builtInModelSlugs)) {
+    if (seen.has(entry.slug)) {
       continue;
     }
 
-    seen.add(slug);
-    options.push({
-      slug,
-      name: slug,
-      isCustom: true,
-    });
+    seen.add(entry.slug);
+    options.push({ slug: entry.slug, name: entry.name, isCustom: true });
   }
 
   const preferences = readInstanceModelPreferences(settings, defaultInstanceId);
@@ -257,13 +253,13 @@ export function getAppModelOptionsForInstance(
   );
 
   const customModels = readInstanceCustomModels(settings, entry.instanceId, entry.driverKind);
-  for (const slug of normalizeCustomModelSlugs(customModels, builtInModelSlugs)) {
-    if (seen.has(slug)) {
+  for (const custom of normalizeCustomModelEntries(customModels, builtInModelSlugs)) {
+    if (seen.has(custom.slug)) {
       continue;
     }
 
-    seen.add(slug);
-    options.push({ slug, name: slug, isCustom: true });
+    seen.add(custom.slug);
+    options.push({ slug: custom.slug, name: custom.name, isCustom: true });
   }
 
   const preferences = readInstanceModelPreferences(settings, entry.instanceId);
diff --git a/docs/user/composer.md b/docs/user/composer.md
index 740c44b8129d..2220fa53c0ec 100644
--- a/docs/user/composer.md
+++ b/docs/user/composer.md
@@ -30,6 +30,12 @@ messages while disconnected. Uploads resume when you reconnect. Drafts and queue
 messages survive app restarts. Signing out of T3 Connect keeps that work on your
 device until you sign back into the same account.
 
+## Custom models
+
+On web and desktop, use Settings → Providers → **Models** to add an unlisted model with a custom
+name and options. Only options supported by the provider integration affect turns. Antigravity
+uses its account catalog and does not support custom models.
+
 ## Model defaults
 
 T3 Code remembers your provider, model, and model options for new threads. A
diff --git a/packages/contracts/src/model.ts b/packages/contracts/src/model.ts
index d217a0cc2cbb..bce1a766bc9b 100644
--- a/packages/contracts/src/model.ts
+++ b/packages/contracts/src/model.ts
@@ -127,6 +127,22 @@ export const ModelCapabilities = Schema.Struct({
 });
 export type ModelCapabilities = typeof ModelCapabilities.Type;
 
+/**
+ * A user-authored custom model. `name` and `capabilities` are optional so a
+ * bare slug keeps its driver-default presentation; when `capabilities` is
+ * set, its descriptors replace the driver default in the model picker.
+ */
+export const CustomModelEntry = Schema.Struct({
+  slug: TrimmedNonEmptyString,
+  name: Schema.optional(TrimmedNonEmptyString),
+  capabilities: Schema.optional(ModelCapabilities),
+});
+export type CustomModelEntry = typeof CustomModelEntry.Type;
+
+/** On-disk custom model setting: the legacy bare slug, or a full entry. */
+export const CustomModelSetting = Schema.Union([Schema.String, CustomModelEntry]);
+export type CustomModelSetting = typeof CustomModelSetting.Type;
+
 const CODEX_DRIVER_KIND = ProviderDriverKind.make("codex");
 const CLAUDE_DRIVER_KIND = ProviderDriverKind.make("claudeAgent");
 const CURSOR_DRIVER_KIND = ProviderDriverKind.make("cursor");
diff --git a/packages/contracts/src/settings.test.ts b/packages/contracts/src/settings.test.ts
index bee5c9a3f0d5..c5d9c52a7175 100644
--- a/packages/contracts/src/settings.test.ts
+++ b/packages/contracts/src/settings.test.ts
@@ -73,6 +73,40 @@ describe("ServerSettings usage price overrides", () => {
   });
 });
 
+describe("custom model settings", () => {
+  const capabilities = {
+    optionDescriptors: [
+      {
+        id: "effort",
+        label: "Reasoning",
+        type: "select",
+        options: [{ id: "high", label: "High", isDefault: true }],
+      },
+    ],
+  };
+
+  it("accepts legacy bare slugs alongside full entries", () => {
+    const decoded = decodeClaudeSettings({
+      customModels: ["bare-slug", { slug: "named", name: "Named", capabilities }],
+    });
+    expect(decoded.customModels).toEqual([
+      "bare-slug",
+      { slug: "named", name: "Named", capabilities },
+    ]);
+  });
+
+  it("accepts entries at the settings patch boundary", () => {
+    expect(
+      decodeServerSettingsPatch({
+        providers: { codex: { customModels: [{ slug: "x", capabilities }] } },
+      }).providers?.codex?.customModels,
+    ).toEqual([{ slug: "x", capabilities }]);
+    expect(() =>
+      decodeServerSettingsPatch({ providers: { codex: { customModels: [{ name: "no slug" }] } } }),
+    ).toThrow();
+  });
+});
+
 describe("ClaudeSettings auto-compaction", () => {
   it("uses Claude's default threshold when no override is configured", () => {
     expect(decodeClaudeSettings({}).autoCompactWindow).toBe("");
diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts
index 51fbc812225c..cf68dcf62de8 100644
--- a/packages/contracts/src/settings.ts
+++ b/packages/contracts/src/settings.ts
@@ -6,6 +6,7 @@ import { ForwardCompatibleNullable, TrimmedNonEmptyString, TrimmedString } from
 import { UsageLimitSourceId } from "./usageLimitSourceId.ts";
 import { EnvironmentMachineKind, ThreadEnvMode } from "./environment.ts";
 import {
+  CustomModelSetting,
   DEFAULT_TEXT_GENERATION_MODEL,
   DEFAULT_TEXT_GENERATION_REASONING_EFFORT,
   ProviderOptionSelections,
@@ -472,7 +473,7 @@ export const CodexSettings = makeProviderSettingsSchema(
         description: "Additional CLI arguments passed to codex app-server on session start.",
       }),
     ),
-    customModels: Schema.Array(Schema.String).pipe(
+    customModels: Schema.Array(CustomModelSetting).pipe(
       Schema.withDecodingDefault(Effect.succeed([])),
       Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
     ),
@@ -510,7 +511,7 @@ export const ClaudeSettings = makeProviderSettingsSchema(
         providerSettingsForm: { placeholder: "~/.claude", clearWhenEmpty: "omit" },
       }),
     ),
-    customModels: Schema.Array(Schema.String).pipe(
+    customModels: Schema.Array(CustomModelSetting).pipe(
       Schema.withDecodingDefault(Effect.succeed([])),
       Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
     ),
@@ -571,7 +572,7 @@ export const CursorSettings = makeProviderSettingsSchema(
         },
       }),
     ),
-    customModels: Schema.Array(Schema.String).pipe(
+    customModels: Schema.Array(CustomModelSetting).pipe(
       Schema.withDecodingDefault(Effect.succeed([])),
       Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
     ),
@@ -597,7 +598,7 @@ export const GrokSettings = makeProviderSettingsSchema(
         providerSettingsForm: { placeholder: "grok", clearWhenEmpty: "omit" },
       }),
     ),
-    customModels: Schema.Array(Schema.String).pipe(
+    customModels: Schema.Array(CustomModelSetting).pipe(
       Schema.withDecodingDefault(Effect.succeed([])),
       Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
     ),
@@ -682,7 +683,7 @@ export const AntigravitySettings = makeProviderSettingsSchema(
         providerSettingsForm: { placeholder: "Automatic", clearWhenEmpty: "persist" },
       }),
     ),
-    customModels: Schema.Array(Schema.String).pipe(
+    customModels: Schema.Array(CustomModelSetting).pipe(
       Schema.withDecodingDefault(Effect.succeed([])),
       Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
     ),
@@ -732,7 +733,7 @@ export const OpenCodeSettings = makeProviderSettingsSchema(
         },
       }),
     ),
-    customModels: Schema.Array(Schema.String).pipe(
+    customModels: Schema.Array(CustomModelSetting).pipe(
       Schema.withDecodingDefault(Effect.succeed([])),
       Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
     ),
@@ -1055,14 +1056,14 @@ const CodexSettingsPatch = Schema.Struct({
   homePath: Schema.optionalKey(TrimmedString),
   shadowHomePath: Schema.optionalKey(TrimmedString),
   launchArgs: Schema.optionalKey(TrimmedString),
-  customModels: Schema.optionalKey(Schema.Array(Schema.String)),
+  customModels: Schema.optionalKey(Schema.Array(CustomModelSetting)),
 });
 
 const ClaudeSettingsPatch = Schema.Struct({
   enabled: Schema.optionalKey(Schema.Boolean),
   binaryPath: Schema.optionalKey(TrimmedString),
   homePath: Schema.optionalKey(TrimmedString),
-  customModels: Schema.optionalKey(Schema.Array(Schema.String)),
+  customModels: Schema.optionalKey(Schema.Array(CustomModelSetting)),
   launchArgs: Schema.optionalKey(TrimmedString),
   // Validated at the patch boundary so a typo fails the one update with a
   // schema error instead of a generic whole-settings failure.
@@ -1075,13 +1076,13 @@ const CursorSettingsPatch = Schema.Struct({
   enabled: Schema.optionalKey(Schema.Boolean),
   binaryPath: Schema.optionalKey(TrimmedString),
   apiEndpoint: Schema.optionalKey(TrimmedString),
-  customModels: Schema.optionalKey(Schema.Array(Schema.String)),
+  customModels: Schema.optionalKey(Schema.Array(CustomModelSetting)),
 });
 
 const GrokSettingsPatch = Schema.Struct({
   enabled: Schema.optionalKey(Schema.Boolean),
   binaryPath: Schema.optionalKey(TrimmedString),
-  customModels: Schema.optionalKey(Schema.Array(Schema.String)),
+  customModels: Schema.optionalKey(Schema.Array(CustomModelSetting)),
 });
 
 const AntigravitySettingsPatch = Schema.Struct({
@@ -1091,7 +1092,7 @@ const AntigravitySettingsPatch = Schema.Struct({
   gcpProject: Schema.optionalKey(TrimmedString),
   gcpLocation: Schema.optionalKey(TrimmedString),
   binaryPath: Schema.optionalKey(TrimmedString),
-  customModels: Schema.optionalKey(Schema.Array(Schema.String)),
+  customModels: Schema.optionalKey(Schema.Array(CustomModelSetting)),
 });
 
 const OpenCodeSettingsPatch = Schema.Struct({
@@ -1099,7 +1100,7 @@ const OpenCodeSettingsPatch = Schema.Struct({
   binaryPath: Schema.optionalKey(TrimmedString),
   serverUrl: Schema.optionalKey(TrimmedString),
   serverPassword: Schema.optionalKey(TrimmedString),
-  customModels: Schema.optionalKey(Schema.Array(Schema.String)),
+  customModels: Schema.optionalKey(Schema.Array(CustomModelSetting)),
 });
 
 export const ServerSettingsPatch = Schema.Struct({
diff --git a/packages/shared/src/model.test.ts b/packages/shared/src/model.test.ts
index da779442c9c7..d2c64e3d9458 100644
--- a/packages/shared/src/model.test.ts
+++ b/packages/shared/src/model.test.ts
@@ -10,6 +10,8 @@ import {
   getModelSelectionBooleanOptionValue,
   getModelSelectionStringOptionValue,
   getProviderOptionDescriptors,
+  readCustomModelEntries,
+  toCustomModelSetting,
   getProviderOptionBooleanSelectionValue,
   getProviderOptionStringSelectionValue,
 } from "./model.ts";
@@ -192,3 +194,53 @@ describe("applyClaudePromptEffortPrefix", () => {
     );
   });
 });
+
+describe("readCustomModelEntries", () => {
+  const capabilities: ModelCapabilities = {
+    optionDescriptors: [
+      {
+        id: "effort",
+        label: "Reasoning",
+        type: "select",
+        options: [{ id: "high", label: "High", isDefault: true }],
+        currentValue: "high",
+      },
+    ],
+  };
+
+  it("resolves bare slugs and entries, trimming and deduplicating on slug", () => {
+    expect(
+      readCustomModelEntries([
+        " bare ",
+        { slug: "named", name: " Named ", capabilities },
+        "bare",
+        { slug: "named", name: "Second" },
+        "",
+        { name: "no slug" },
+        42,
+      ]),
+    ).toEqual([
+      { slug: "bare", name: "bare", capabilities: null },
+      { slug: "named", name: "Named", capabilities },
+    ]);
+  });
+
+  it("drops unparseable capabilities but keeps the entry", () => {
+    expect(
+      readCustomModelEntries([{ slug: "x", capabilities: { optionDescriptors: "nope" } }]),
+    ).toEqual([{ slug: "x", name: "x", capabilities: null }]);
+    expect(readCustomModelEntries("not a list")).toEqual([]);
+  });
+
+  it("writes the compact stored shape back", () => {
+    expect(toCustomModelSetting({ slug: "x", name: "x", capabilities: null })).toBe("x");
+    expect(
+      toCustomModelSetting({ slug: "x", name: "x", capabilities: { optionDescriptors: [] } }),
+    ).toBe("x");
+    expect(toCustomModelSetting({ slug: "x", name: "X", capabilities })).toEqual({
+      slug: "x",
+      name: "X",
+      capabilities,
+    });
+  });
+});
diff --git a/packages/shared/src/model.ts b/packages/shared/src/model.ts
index cad7c8e8db86..940778fba1ea 100644
--- a/packages/shared/src/model.ts
+++ b/packages/shared/src/model.ts
@@ -1,12 +1,15 @@
 import {
+  type CustomModelSetting,
   MODEL_SLUG_ALIASES_BY_PROVIDER,
-  type ModelCapabilities,
+  ModelCapabilities,
   type ModelSelection,
   ProviderDriverKind,
   ProviderInstanceId,
   type ProviderOptionDescriptor,
   type ProviderOptionSelection,
 } from "@t3tools/contracts";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
 
 const DEFAULT_PROVIDER_DRIVER_KIND = ProviderDriverKind.make("codex");
 
@@ -247,6 +250,76 @@ export function normalizeCustomModelSlug(model: string | null | undefined): stri
   return model.trim() || null;
 }
 
+/** A custom model setting with its optional fields resolved. */
+export interface CustomModelDefinition {
+  readonly slug: string;
+  readonly name: string;
+  readonly capabilities: ModelCapabilities | null;
+}
+
+const decodeCustomModelCapabilities = Schema.decodeUnknownOption(ModelCapabilities);
+
+/**
+ * Read a `customModels` setting into resolved definitions. Accepts the typed
+ * union as well as the opaque `providerInstances[id].config` blob clients see,
+ * so it tolerates bare slugs, malformed rows, and unparseable capabilities
+ * (dropped rather than failing the whole list). Slugs are trimmed and
+ * deduplicated, first occurrence wins; `name` falls back to the slug.
+ */
+export function readCustomModelEntries(value: unknown): CustomModelDefinition[] {
+  if (!Array.isArray(value)) return [];
+  const entries: CustomModelDefinition[] = [];
+  const seen = new Set<string>();
+  for (const raw of value) {
+    const record =
+      typeof raw === "string"
+        ? { slug: raw }
+        : raw !== null && typeof raw === "object"
+          ? (raw as { slug?: unknown; name?: unknown; capabilities?: unknown })
+          : null;
+    if (!record) continue;
+    const slug = normalizeCustomModelSlug(typeof record.slug === "string" ? record.slug : null);
+    if (!slug || seen.has(slug)) continue;
+    seen.add(slug);
+    const name =
+      (typeof record.name === "string" ? normalizeCustomModelSlug(record.name) : null) ?? slug;
+    const capabilities =
+      record.capabilities === undefined || record.capabilities === null
+        ? null
+        : Option.getOrNull(decodeCustomModelCapabilities(record.capabilities));
+    entries.push({
+      slug,
+      name,
+      capabilities: capabilities
+        ? createModelCapabilities({ optionDescriptors: capabilities.optionDescriptors ?? [] })
+        : null,
+    });
+  }
+  return entries;
+}
+
+/** Slugs of a `customModels` setting, in stored order. */
+export function readCustomModelSlugs(value: unknown): string[] {
+  return readCustomModelEntries(value).map((entry) => entry.slug);
+}
+
+/**
+ * Write a definition back to the compact stored shape: a bare slug when it
+ * carries nothing custom, otherwise an entry with only the set fields.
+ */
+export function toCustomModelSetting(entry: CustomModelDefinition): CustomModelSetting {
+  const descriptors = entry.capabilities?.optionDescriptors ?? [];
+  const name = entry.name !== entry.slug ? entry.name : undefined;
+  if (!name && descriptors.length === 0) return entry.slug;
+  return {
+    slug: entry.slug,
+    ...(name ? { name } : {}),
+    ...(descriptors.length > 0
+      ? { capabilities: createModelCapabilities({ optionDescriptors: descriptors }) }
+      : {}),
+  };
+}
+
 export function resolveSelectableModel(
   provider: ProviderDriverKind,
   value: string | null | undefined,

From 087cfb8ae262f344f7e409f5a8c0eda6f0ef12f9 Mon Sep 17 00:00:00 2001
From: Ezra <ibxbit@gmail.com>
Date: Sat, 5 Sep 2026 02:27:27 +0300
Subject: [PATCH 36/56] fix(cursor): discover symlinked skills as package
 boundaries (#9420)

---
 .../src/provider/Drivers/CursorSkills.ts      | 23 +++++----
 .../provider/Layers/CursorProvider.test.ts    | 50 +++++++++++++++++++
 2 files changed, 64 insertions(+), 9 deletions(-)

diff --git a/apps/server/src/provider/Drivers/CursorSkills.ts b/apps/server/src/provider/Drivers/CursorSkills.ts
index 5113fd3d0ca6..7b0637267c80 100644
--- a/apps/server/src/provider/Drivers/CursorSkills.ts
+++ b/apps/server/src/provider/Drivers/CursorSkills.ts
@@ -147,16 +147,18 @@ const discoverSkillsInRoot = Effect.fn("discoverCursorSkillsInRoot")(function* (
     if (!resolvedDirectory) {
       return;
     }
-    if (
-      visitedDirectories.has(resolvedDirectory) ||
-      (resolvedDirectory !== rootDirectory &&
-        !resolvedDirectory.startsWith(`${rootDirectory}${path.sep}`))
-    ) {
+    if (visitedDirectories.has(resolvedDirectory)) {
       return;
     }
     visitedDirectories.add(resolvedDirectory);
+    // A symlink whose target lives outside the root is a skill package
+    // boundary: read its own SKILL.md so linked skill libraries show up, but
+    // never walk the target tree.
+    const insideRoot =
+      resolvedDirectory === rootDirectory ||
+      resolvedDirectory.startsWith(`${rootDirectory}${path.sep}`);
 
-    const skillPath = path.join(resolvedDirectory, "SKILL.md");
+    const skillPath = path.join(directory, "SKILL.md");
     const skillInfo = yield* orUndefined(fileSystem.stat(skillPath), input.budget);
     if (skillInfo?.type === "File") {
       let frontmatter: CursorSkillFrontmatter | undefined = { cliVisible: true };
@@ -167,7 +169,7 @@ const discoverSkillsInRoot = Effect.fn("discoverCursorSkillsInRoot")(function* (
           frontmatter = parseSkillFrontmatter(contents);
         }
       }
-      const name = path.basename(resolvedDirectory).trim();
+      const name = path.basename(directory).trim();
       if (frontmatter?.cliVisible && name) {
         skills.push({
           name,
@@ -184,7 +186,10 @@ const discoverSkillsInRoot = Effect.fn("discoverCursorSkillsInRoot")(function* (
       }
     }
 
-    const entries = yield* orUndefined(fileSystem.readDirectory(resolvedDirectory), input.budget);
+    if (!insideRoot) {
+      return;
+    }
+    const entries = yield* orUndefined(fileSystem.readDirectory(directory), input.budget);
     if (!entries) {
       return;
     }
@@ -194,7 +199,7 @@ const discoverSkillsInRoot = Effect.fn("discoverCursorSkillsInRoot")(function* (
         return;
       }
       input.budget.remainingEntries -= 1;
-      const child = path.join(resolvedDirectory, entry);
+      const child = path.join(directory, entry);
       const info = yield* orUndefined(fileSystem.stat(child), input.budget);
       if (info?.type !== "Directory") continue;
       if (depth >= MAX_SKILL_DEPTH) {
diff --git a/apps/server/src/provider/Layers/CursorProvider.test.ts b/apps/server/src/provider/Layers/CursorProvider.test.ts
index 8f1a0c54cf5a..a01958dcccac 100644
--- a/apps/server/src/provider/Layers/CursorProvider.test.ts
+++ b/apps/server/src/provider/Layers/CursorProvider.test.ts
@@ -395,6 +395,56 @@ describe("Cursor skills", () => {
       }),
     ));
 
+  it("treats a symlinked skill outside the root as a package boundary", async () =>
+    await runNode(
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const userHome = yield* fileSystem.makeTempDirectory({
+          directory: NodeOS.tmpdir(),
+          prefix: "cursor-skills-home-",
+        });
+        const workspace = yield* fileSystem.makeTempDirectory({
+          directory: NodeOS.tmpdir(),
+          prefix: "cursor-skills-workspace-",
+        });
+        const library = yield* fileSystem.makeTempDirectory({
+          directory: NodeOS.tmpdir(),
+          prefix: "cursor-skills-library-",
+        });
+        const writeSkill = Effect.fn("writeCursorSkill")(function* (
+          directory: string,
+          contents: string,
+        ) {
+          yield* fileSystem.makeDirectory(directory, { recursive: true });
+          yield* fileSystem.writeFileString(path.join(directory, "SKILL.md"), contents);
+        });
+
+        // A skill package managed in a config repo and installed by symlink.
+        // Its own SKILL.md must be discovered under the link name, but nothing
+        // below the target may be walked.
+        yield* writeSkill(path.join(library, "shared-review"), "---\ndescription: shared\n---\n");
+        yield* writeSkill(path.join(library, "shared-review", "hidden"), "---\n---\n");
+        const root = path.join(workspace, ".cursor", "skills");
+        yield* fileSystem.makeDirectory(root, { recursive: true });
+        yield* fileSystem.symlink(path.join(library, "shared-review"), path.join(root, "review"));
+
+        const skills = yield* discoverCursorSkills(workspace, { HOME: userHome });
+        expect(skills).toEqual([
+          {
+            name: "review",
+            description: "shared",
+            path: path.join(root, "review", "SKILL.md"),
+            scope: "project",
+            enabled: true,
+          },
+        ]);
+        expect(
+          (yield* probeCursorSkills(workspace, { HOME: userHome }).pipe(Effect.result))._tag,
+        ).toBe("Success");
+      }),
+    ));
+
   it("rewrites only discovered skill mentions into Cursor slash invocations", () => {
     expect(hasCursorSkillMention("use $Review_Pr:V2 here")).toBe(true);
     expect(hasCursorSkillMention("please $review this")).toBe(true);

From f33fdc992488e36ccb70cbb71d55e630b5184cbd Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 16:43:45 -0700
Subject: [PATCH 37/56] fix(ssh): exec managed servers without npm wrappers
 (#9843)

---
 packages/ssh/src/runnerProcess.test.ts | 167 +++++++++++++++++++++++++
 packages/ssh/src/tunnel.test.ts        |   5 +-
 packages/ssh/src/tunnel.ts             |   5 +-
 3 files changed, 171 insertions(+), 6 deletions(-)
 create mode 100644 packages/ssh/src/runnerProcess.test.ts

diff --git a/packages/ssh/src/runnerProcess.test.ts b/packages/ssh/src/runnerProcess.test.ts
new file mode 100644
index 000000000000..7dda675ee95c
--- /dev/null
+++ b/packages/ssh/src/runnerProcess.test.ts
@@ -0,0 +1,167 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, it } from "@effect/vitest";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import * as NodeNet from "node:net";
+
+import { buildRemoteT3RunnerScript } from "./tunnel.ts";
+
+const Started = Schema.Struct({
+  pid: Schema.Number,
+  port: Schema.Number,
+  args: Schema.Array(Schema.String),
+});
+const decodeStarted = Schema.decodeUnknownSync(Schema.fromJsonString(Started));
+
+describe.skipIf(HostProcessPlatform.defaultValue() === "win32")(
+  "remote runner process ownership",
+  () => {
+    it.live.each(["npx", "npm"] as const)(
+      "keeps the server PID and graceful shutdown through the %s fallback",
+      (packageManager) =>
+        Effect.gen(function* () {
+          const fs = yield* FileSystem.FileSystem;
+          const path = yield* Path.Path;
+          const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+          const fixture = yield* fs.makeTempDirectoryScoped({ prefix: "t3-runner-" });
+          const bin = path.join(fixture, "bin");
+          const cliPath = path.join(fixture, "installed cli.mjs");
+          const callsPath = path.join(fixture, "package-manager-calls.jsonl");
+          const packageSpec = "t3@0.0.35";
+          yield* fs.makeDirectory(bin);
+          yield* fs.symlink(process.execPath, path.join(bin, "node"));
+          yield* fs.writeFileString(
+            cliPath,
+            `#!/usr/bin/env node
+import * as net from "node:net";
+const server = net.createServer((socket) => {
+  socket.end();
+  server.close();
+});
+process.on("SIGTERM", () => server.close(() => {
+  process.stdout.write("graceful shutdown\\n");
+}));
+server.listen(Number(process.env.T3_TEST_PORT ?? 0), "127.0.0.1", () => {
+  process.stdout.write(JSON.stringify({
+    pid: process.pid,
+    port: server.address().port,
+    args: process.argv.slice(2),
+  }) + "\\n");
+});
+`,
+          );
+          yield* fs.chmod(cliPath, 0o700);
+          yield* fs.writeFileString(
+            path.join(bin, packageManager),
+            `#!/usr/bin/env node
+const fs = require("node:fs");
+const childProcess = require("node:child_process");
+const args = process.argv.slice(2);
+fs.appendFileSync(process.env.T3_TEST_CALLS, JSON.stringify(args) + "\\n");
+if (args.includes("--package")) {
+  process.stdout.write(process.env.T3_TEST_CLI + "\\n");
+} else {
+  const child = childProcess.spawn(process.execPath, [process.env.T3_TEST_CLI, ...args], { stdio: "inherit" });
+  child.once("exit", (code) => { process.exitCode = code ?? 1; });
+}
+`,
+          );
+          yield* fs.chmod(path.join(bin, packageManager), 0o700);
+
+          const runServer = (port = 0) =>
+            Effect.gen(function* () {
+              const child = yield* spawner.spawn(
+                ChildProcess.make("/bin/sh", ["-s", "--", "serve", "a path with spaces"], {
+                  cwd: fixture,
+                  env: {
+                    PATH: bin,
+                    T3_TEST_CLI: cliPath,
+                    T3_TEST_CALLS: callsPath,
+                    T3_TEST_PORT: String(port),
+                  },
+                  detached: false,
+                  stdin: Stream.make(
+                    new TextEncoder().encode(buildRemoteT3RunnerScript({ packageSpec })),
+                  ),
+                }),
+              );
+              const ready = yield* Deferred.make<typeof Started.Type>();
+              const stdout: string[] = [];
+              const output = yield* child.stdout.pipe(
+                Stream.decodeText(),
+                Stream.splitLines,
+                Stream.runForEach((line) =>
+                  Effect.gen(function* () {
+                    stdout.push(line);
+                    if (stdout.length === 1) {
+                      yield* Deferred.succeed(ready, decodeStarted(line));
+                    }
+                  }),
+                ),
+                Effect.forkScoped,
+              );
+              const stderr = yield* child.stderr.pipe(
+                Stream.decodeText(),
+                Stream.mkString,
+                Effect.forkScoped,
+              );
+              const receipt = yield* Effect.raceFirst(
+                Deferred.await(ready),
+                Fiber.join(output).pipe(
+                  Effect.flatMap(() => Fiber.join(stderr)),
+                  Effect.flatMap((message) =>
+                    Effect.die(new Error(`Runner exited before listening: ${message}`)),
+                  ),
+                ),
+              );
+              // A failed PID assertion must still close the owned fixture server, including an npm child.
+              yield* Effect.addFinalizer(() =>
+                Effect.gen(function* () {
+                  if (yield* child.isRunning) {
+                    yield* Effect.callback<void>((resume) => {
+                      const connection = NodeNet.connect(receipt.port, "127.0.0.1");
+                      connection.on("error", () => undefined);
+                      connection.once("close", () => resume(Effect.void));
+                      return Effect.sync(() => connection.destroy());
+                    });
+                    yield* child.exitCode;
+                  }
+                }).pipe(Effect.orDie),
+              );
+              assert.equal(receipt.pid, child.pid);
+              assert.deepEqual(receipt.args, ["serve", "a path with spaces"]);
+              yield* child.kill({ killSignal: "SIGTERM" });
+              assert.equal(yield* child.exitCode, 0);
+              yield* Fiber.join(output);
+              assert.include(stdout, "graceful shutdown");
+              return receipt.port;
+            }).pipe(Effect.scoped);
+
+          const port = yield* runServer();
+          assert.equal(yield* runServer(port), port);
+          const calls = (yield* fs.readFileString(callsPath))
+            .trim()
+            .split("\n")
+            .map((line) => JSON.parse(line));
+          const expectedCall = [
+            ...(packageManager === "npm" ? ["exec"] : []),
+            "--yes",
+            "--package",
+            packageSpec,
+            "--",
+            "sh",
+            "-c",
+            "command -v t3",
+          ];
+          assert.deepEqual(calls, [expectedCall, expectedCall]);
+        }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
+    );
+  },
+);
diff --git a/packages/ssh/src/tunnel.test.ts b/packages/ssh/src/tunnel.test.ts
index 392885b640c1..4a49cacc2eb8 100644
--- a/packages/ssh/src/tunnel.test.ts
+++ b/packages/ssh/src/tunnel.test.ts
@@ -105,8 +105,7 @@ describe("ssh tunnel scripts", () => {
 
     assert.include(script, "T3_NODE_SCRIPT_PATH=''");
     assert.include(script, 'exec t3 "$@"');
-    assert.include(script, "exec npx --yes 't3@latest' \"$@\"");
-    assert.include(script, "exec npm exec --yes 't3@latest' -- \"$@\"");
+    assert.include(script, 'exec "$T3_CLI_PATH" "$@"');
     assert.include(script, "could not install 't3@latest'");
     assert.include(script, "require_installed_t3_cli npx --yes --package 't3@latest'");
     assert.include(script, "require_installed_t3_cli npm exec --yes --package 't3@latest'");
@@ -141,8 +140,6 @@ describe("ssh tunnel scripts", () => {
       packageSpec: "t3@nightly; touch /tmp/t3-owned",
     });
 
-    assert.include(script, "exec npx --yes 't3@nightly; touch /tmp/t3-owned' \"$@\"");
-    assert.include(script, "exec npm exec --yes 't3@nightly; touch /tmp/t3-owned' -- \"$@\"");
     assert.include(
       script,
       "require_installed_t3_cli npx --yes --package 't3@nightly; touch /tmp/t3-owned'",
diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
index 0afd1007f8ed..04dbce65af60 100644
--- a/packages/ssh/src/tunnel.ts
+++ b/packages/ssh/src/tunnel.ts
@@ -440,13 +440,14 @@ require_installed_t3_cli() {
   printf 'Remote host installed %s but npm produced no t3 executable, which usually means a native dependency (node-pty) failed to build. Install a C toolchain on the remote host (Debian/Ubuntu: build-essential, Fedora/RHEL: gcc-c++ make, macOS: xcode-select --install) and try again.\\n' @@T3_PACKAGE_SPEC@@ >&2
   return 1
 }
+# The launcher records this PID, so exec the CLI without an npm wrapper process.
 if command -v npx >/dev/null 2>&1; then
   require_installed_t3_cli npx --yes --package @@T3_PACKAGE_SPEC@@ || exit 1
-  exec npx --yes @@T3_PACKAGE_SPEC@@ "$@"
+  exec "$T3_CLI_PATH" "$@"
 fi
 if command -v npm >/dev/null 2>&1; then
   require_installed_t3_cli npm exec --yes --package @@T3_PACKAGE_SPEC@@ || exit 1
-  exec npm exec --yes @@T3_PACKAGE_SPEC@@ -- "$@"
+  exec "$T3_CLI_PATH" "$@"
 fi
 printf 'Remote host is missing the t3 CLI and could not install @@T3_PACKAGE_SPEC@@ because node/npm/npx are unavailable on PATH. Install Node or configure a supported version manager for non-interactive shells.\\n' >&2
 exit 1

From 0dd5c64bcfac7974d81bac76740ecd83540077e8 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 16:45:00 -0700
Subject: [PATCH 38/56] fix(server): detect nested Git workspaces for
 checkpoints (#9842)

---
 apps/server/src/git/Utils.ts                  |  7 --
 .../Layers/CheckpointReactor.test.ts          | 77 +++++++++++++++++++
 .../orchestration/Layers/CheckpointReactor.ts |  9 +--
 .../Layers/ProviderRuntimeIngestion.test.ts   | 43 ++++++++++-
 .../Layers/ProviderRuntimeIngestion.ts        | 10 ++-
 5 files changed, 129 insertions(+), 17 deletions(-)
 delete mode 100644 apps/server/src/git/Utils.ts

diff --git a/apps/server/src/git/Utils.ts b/apps/server/src/git/Utils.ts
deleted file mode 100644
index e4a703f44540..000000000000
--- a/apps/server/src/git/Utils.ts
+++ /dev/null
@@ -1,7 +0,0 @@
-// @effect-diagnostics nodeBuiltinImport:off
-import * as NodeFS from "node:fs";
-import * as NodePath from "node:path";
-
-export function isGitRepository(cwd: string): boolean {
-  return NodeFS.existsSync(NodePath.join(cwd, ".git"));
-}
diff --git a/apps/server/src/orchestration/Layers/CheckpointReactor.test.ts b/apps/server/src/orchestration/Layers/CheckpointReactor.test.ts
index a01a938187f2..2f2c4b30525b 100644
--- a/apps/server/src/orchestration/Layers/CheckpointReactor.test.ts
+++ b/apps/server/src/orchestration/Layers/CheckpointReactor.test.ts
@@ -590,6 +590,83 @@ describe("CheckpointReactor", () => {
     }),
   );
 
+  effectIt.effect("captures and reverts checkpoints from a nested Git workspace", () =>
+    Effect.gen(function* () {
+      const repositoryRoot = createGitRepository();
+      tempDirs.push(repositoryRoot);
+      const workspaceRoot = NodePath.join(repositoryRoot, "apps", "server");
+      NodeFS.mkdirSync(workspaceRoot, { recursive: true });
+      const filePath = NodePath.join(workspaceRoot, "index.ts");
+      NodeFS.writeFileSync(filePath, "export const value = 1;\n");
+      runGit(repositoryRoot, ["add", "."]);
+      runGit(repositoryRoot, ["commit", "-m", "Add nested workspace"]);
+      const harness = yield* Effect.promise(() =>
+        createHarness({
+          seedFilesystemCheckpoints: false,
+          projectWorkspaceRoot: workspaceRoot,
+          threadWorktreePath: workspaceRoot,
+          providerSessionCwd: workspaceRoot,
+        }),
+      );
+      const threadId = ThreadId.make("thread-1");
+      const turnId = asTurnId("turn-nested");
+      const createdAt = "2026-01-01T00:00:00.000Z";
+      harness.provider.emit({
+        type: "turn.started",
+        eventId: EventId.make("evt-nested-start"),
+        provider: ProviderDriverKind.make("codex"),
+        createdAt,
+        threadId,
+        turnId,
+      });
+      yield* Effect.promise(harness.drain);
+      expect(gitRefExists(repositoryRoot, checkpointRefForThreadTurn(threadId, 0))).toBe(true);
+      expect(yield* harness.nextReceipt).toMatchObject({
+        type: "checkpoint.baseline.captured",
+      });
+
+      NodeFS.writeFileSync(filePath, "export const value = 2;\n");
+      harness.provider.emit({
+        type: "turn.completed",
+        eventId: EventId.make("evt-nested-complete"),
+        provider: ProviderDriverKind.make("codex"),
+        createdAt,
+        threadId,
+        turnId,
+        payload: { state: "completed" },
+      });
+      yield* Effect.promise(harness.drain);
+      const thread = (yield* Effect.promise(harness.readModel)).threads.find(
+        (entry) => entry.id === threadId,
+      );
+      expect(thread?.checkpoints[0]).toMatchObject({
+        status: "ready",
+        files: [{ path: "apps/server/index.ts", additions: 1, deletions: 1 }],
+      });
+      expect(yield* harness.nextReceipt).toMatchObject({
+        type: "checkpoint.diff.finalized",
+        turnId,
+      });
+      expect(yield* harness.nextReceipt).toMatchObject({ type: "turn.processing.quiesced" });
+
+      yield* harness.engine.dispatch({
+        type: "thread.checkpoint.revert",
+        commandId: CommandId.make("cmd-nested-revert"),
+        threadId,
+        turnCount: 0,
+        createdAt,
+      });
+      yield* Effect.promise(harness.drain);
+      expect(NodeFS.readFileSync(filePath, "utf8")).toBe("export const value = 1;\n");
+      expect(harness.provider.rollbackConversation).toHaveBeenCalledWith({ threadId, numTurns: 1 });
+      expect(gitRefExists(repositoryRoot, checkpointRefForThreadTurn(threadId, 1))).toBe(false);
+      const reverted = (yield* Effect.promise(harness.readModel)).threads.find(
+        (entry) => entry.id === threadId,
+      );
+      expect(reverted?.checkpoints).toEqual([]);
+    }),
+  );
+
   it("refreshes local git status state on turn completion using the session cwd", async () => {
     const gitStatusRefreshCalls: string[] = [];
     const harness = await createHarness({
diff --git a/apps/server/src/orchestration/Layers/CheckpointReactor.ts b/apps/server/src/orchestration/Layers/CheckpointReactor.ts
index 0a56eb840960..108abd5d06bb 100644
--- a/apps/server/src/orchestration/Layers/CheckpointReactor.ts
+++ b/apps/server/src/orchestration/Layers/CheckpointReactor.ts
@@ -35,7 +35,6 @@ import { ProjectionSnapshotQuery } from "../Services/ProjectionSnapshotQuery.ts"
 import { RuntimeReceiptBus } from "../Services/RuntimeReceiptBus.ts";
 import type { CheckpointStoreError } from "../../checkpointing/Errors.ts";
 import type { OrchestrationDispatchError } from "../Errors.ts";
-import { isGitRepository } from "../../git/Utils.ts";
 import { VcsStatusBroadcaster } from "../../vcs/VcsStatusBroadcaster.ts";
 import * as WorkspaceEntries from "../../workspace/WorkspaceEntries.ts";
 import * as PullRequestService from "../../pullRequest/PullRequestService.ts";
@@ -181,8 +180,6 @@ const make = Effect.gen(function* () {
     return project ? [project] : [];
   });
 
-  const isGitWorkspace = (cwd: string) => isGitRepository(cwd);
-
   // Resolves the workspace CWD for checkpoint operations, preferring the
   // active provider session CWD and falling back to the thread/project config.
   // Returns undefined when no CWD can be determined or the workspace is not
@@ -192,7 +189,7 @@ const make = Effect.gen(function* () {
     readonly thread: { readonly projectId: ProjectId; readonly worktreePath: string | null };
     readonly projects: ReadonlyArray<{ readonly id: ProjectId; readonly workspaceRoot: string }>;
     readonly preferSessionRuntime: boolean;
-  }): Effect.fn.Return<string | undefined> {
+  }): Effect.fn.Return<string | undefined, CheckpointStoreError> {
     const fromSession = yield* resolveSessionRuntimeForThread(input.threadId);
     const fromThread = resolveThreadWorkspaceCwd({
       thread: input.thread,
@@ -213,7 +210,7 @@ const make = Effect.gen(function* () {
     if (!cwd) {
       return undefined;
     }
-    if (!isGitWorkspace(cwd)) {
+    if (!(yield* checkpointStore.isGitRepository(cwd))) {
       return undefined;
     }
     return cwd;
@@ -751,7 +748,7 @@ const make = Effect.gen(function* () {
       }).pipe(Effect.catch(() => Effect.void));
       return;
     }
-    if (!isGitWorkspace(sessionRuntime.value.cwd)) {
+    if (!(yield* checkpointStore.isGitRepository(sessionRuntime.value.cwd))) {
       yield* appendRevertFailureActivity({
         threadId: event.payload.threadId,
         turnCount: event.payload.turnCount,
diff --git a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts
index 923e8c16f540..827e14734dc6 100644
--- a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts
+++ b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts
@@ -2,6 +2,7 @@
 import * as NodeFS from "node:fs";
 import * as NodeOS from "node:os";
 import * as NodePath from "node:path";
+import * as NodeChildProcess from "node:child_process";
 
 import {
   OrchestrationReadModel,
@@ -44,6 +45,9 @@ import {
   type ProviderServiceShape,
 } from "../../provider/Services/ProviderService.ts";
 import * as RepositoryIdentityResolver from "../../project/RepositoryIdentityResolver.ts";
+import * as CheckpointStore from "../../checkpointing/CheckpointStore.ts";
+import * as VcsDriverRegistry from "../../vcs/VcsDriverRegistry.ts";
+import * as VcsProcess from "../../vcs/VcsProcess.ts";
 import { OrchestrationEngineLive } from "./OrchestrationEngine.ts";
 import { OrchestrationProjectionPipelineLive } from "./ProjectionPipeline.ts";
 import { OrchestrationProjectionSnapshotQueryLive } from "./ProjectionSnapshotQuery.ts";
@@ -257,9 +261,15 @@ describe("ProviderRuntimeIngestion", () => {
   async function createHarness(options?: {
     serverSettings?: Partial<ServerSettings>;
     threadTitle?: string;
+    workspaceSubdirectory?: string;
   }) {
-    const workspaceRoot = makeTempDir("t3-provider-project-");
-    NodeFS.mkdirSync(NodePath.join(workspaceRoot, ".git"));
+    const repositoryRoot = makeTempDir("t3-provider-project-");
+    NodeChildProcess.execFileSync("git", ["init", "--initial-branch=main"], {
+      cwd: repositoryRoot,
+      stdio: "ignore",
+    });
+    const workspaceRoot = NodePath.join(repositoryRoot, options?.workspaceSubdirectory ?? "");
+    NodeFS.mkdirSync(workspaceRoot, { recursive: true });
     const provider = createProviderServiceHarness();
     const sqlCounter = makeSqlStatementCounter();
     const orchestrationLayer = OrchestrationEngineLive.pipe(
@@ -284,6 +294,8 @@ describe("ProviderRuntimeIngestion", () => {
       Layer.provideMerge(SqlitePersistenceMemory),
       Layer.provideMerge(Layer.succeed(ProviderService, provider.service)),
       Layer.provideMerge(makeTestServerSettingsLayer(options?.serverSettings)),
+      Layer.provideMerge(CheckpointStore.layer.pipe(Layer.provide(VcsDriverRegistry.layer))),
+      Layer.provideMerge(VcsProcess.layer),
       Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
       Layer.provideMerge(NodeServices.layer),
       Layer.provideMerge(Layer.succeed(Tracer.Tracer, sqlCounter.tracer)),
@@ -3177,6 +3189,33 @@ describe("ProviderRuntimeIngestion", () => {
     });
   });
 
+  effectIt.effect("tracks provider diff updates from a nested Git workspace", () =>
+    Effect.gen(function* () {
+      const harness = yield* Effect.promise(() =>
+        createHarness({ workspaceSubdirectory: "apps/server" }),
+      );
+      yield* Effect.promise(() =>
+        harness.emitAndDrain([
+          {
+            type: "turn.diff.updated",
+            eventId: asEventId("evt-nested-diff"),
+            provider: ProviderDriverKind.make("codex"),
+            createdAt: "2026-01-01T00:00:00.000Z",
+            threadId: asThreadId("thread-1"),
+            turnId: asTurnId("nested-turn"),
+            payload: {
+              unifiedDiff: "diff --git a/apps/server/file.ts b/apps/server/file.ts\n+new\n",
+            },
+          },
+        ]),
+      );
+      const snapshot = yield* Effect.promise(harness.readModel);
+      expect(snapshot.threads[0]?.checkpoints).toEqual([
+        expect.objectContaining({ turnId: "nested-turn", status: "missing" }),
+      ]);
+    }),
+  );
+
   it("consumes P1 runtime events into thread metadata, diff checkpoints, and activities", async () => {
     const harness = await createHarness();
     const now = "2026-01-01T00:00:00.000Z";
diff --git a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
index 449123d2e9da..a9be5d5b6e1f 100644
--- a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
+++ b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
@@ -36,7 +36,7 @@ import { formatTokens } from "@t3tools/shared/usageFormat";
 import { ProviderService } from "../../provider/Services/ProviderService.ts";
 import { ProjectionTurnRepository } from "../../persistence/Services/ProjectionTurns.ts";
 import { ProjectionTurnRepositoryLive } from "../../persistence/Layers/ProjectionTurns.ts";
-import { isGitRepository } from "../../git/Utils.ts";
+import * as CheckpointStore from "../../checkpointing/CheckpointStore.ts";
 import { OrchestrationEngineService } from "../Services/OrchestrationEngine.ts";
 import { ThreadBackgroundLivenessService } from "../ThreadBackgroundLiveness.ts";
 import { ThreadPlanProgressService } from "../ThreadPlanProgress.ts";
@@ -956,6 +956,7 @@ const make = Effect.gen(function* () {
   const providerService = yield* ProviderService;
   const projectionTurnRepository = yield* ProjectionTurnRepository;
   const serverSettingsService = yield* ServerSettingsService;
+  const checkpointStore = yield* CheckpointStore.CheckpointStore;
   const providerCommandId = (event: ProviderRuntimeEvent, tag: string) =>
     crypto.randomUUIDv4.pipe(
       Effect.map((uuid) => CommandId.make(`provider:${event.eventId}:${tag}:${uuid}`)),
@@ -2013,7 +2014,12 @@ const make = Effect.gen(function* () {
           : undefined;
         const workspaceCwd =
           checkpointContext?.worktreePath ?? checkpointContext?.workspaceRoot ?? undefined;
-        if (turnId && checkpointContext && workspaceCwd && isGitRepository(workspaceCwd)) {
+        if (
+          turnId &&
+          checkpointContext &&
+          workspaceCwd &&
+          (yield* checkpointStore.isGitRepository(workspaceCwd))
+        ) {
           // Skip if a checkpoint already exists for this turn. A real
           // (non-placeholder) capture from CheckpointReactor should not
           // be clobbered, and dispatching a duplicate placeholder for the

From 4f1092cec2ebaa6ed0e49821238dfe6f1add362d Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 17:04:54 -0700
Subject: [PATCH 39/56] fix(web): keep worktree origin preference visible
 (#9846)

---
 .../components/settings/SettingsPanels.tsx    | 56 +++++++++----------
 1 file changed, 27 insertions(+), 29 deletions(-)

diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index 66f7691a4a07..8482e37440a4 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -2601,37 +2601,35 @@ export function GeneralSettingsPanel() {
           }
         />
 
-        {settings.defaultThreadEnvMode === "worktree" ? (
-          <SettingsRow
-            serverScoped
-            className="bg-muted/20 sm:pl-9"
-            title={searchableSetting("start-from-origin").title}
-            description="Creates the worktree from the latest matching branch on origin instead of your local branch."
-            resetAction={
-              settings.newWorktreesStartFromOrigin !==
-              DEFAULT_UNIFIED_SETTINGS.newWorktreesStartFromOrigin ? (
-                <SettingResetButton
-                  label="new worktrees start from origin"
-                  onClick={() =>
-                    updateSettings({
-                      newWorktreesStartFromOrigin:
-                        DEFAULT_UNIFIED_SETTINGS.newWorktreesStartFromOrigin,
-                    })
-                  }
-                />
-              ) : null
-            }
-            control={
-              <Switch
-                checked={settings.newWorktreesStartFromOrigin}
-                onCheckedChange={(checked) =>
-                  updateSettings({ newWorktreesStartFromOrigin: Boolean(checked) })
+        <SettingsRow
+          serverScoped
+          className="bg-muted/20 sm:pl-9"
+          title={searchableSetting("start-from-origin").title}
+          description="Creates the worktree from the latest matching branch on origin instead of your local branch."
+          resetAction={
+            settings.newWorktreesStartFromOrigin !==
+            DEFAULT_UNIFIED_SETTINGS.newWorktreesStartFromOrigin ? (
+              <SettingResetButton
+                label="new worktrees start from origin"
+                onClick={() =>
+                  updateSettings({
+                    newWorktreesStartFromOrigin:
+                      DEFAULT_UNIFIED_SETTINGS.newWorktreesStartFromOrigin,
+                  })
                 }
-                aria-label="Start new worktrees from origin by default"
               />
-            }
-          />
-        ) : null}
+            ) : null
+          }
+          control={
+            <Switch
+              checked={settings.newWorktreesStartFromOrigin}
+              onCheckedChange={(checked) =>
+                updateSettings({ newWorktreesStartFromOrigin: Boolean(checked) })
+              }
+              aria-label="Start new worktrees from origin by default"
+            />
+          }
+        />
         <SettingsRow
           serverScoped
           {...searchableSetting("add-project-starts-in")}

From 2e61301b1325e30cb9464e193299a7e469f7ec08 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 17:06:27 -0700
Subject: [PATCH 40/56] fix(web): smooth settings sidebar transitions (#9811)

---
 .../settings/SettingsSidebarNav.tsx           | 55 +++++++++++++------
 1 file changed, 39 insertions(+), 16 deletions(-)

diff --git a/apps/web/src/components/settings/SettingsSidebarNav.tsx b/apps/web/src/components/settings/SettingsSidebarNav.tsx
index 2716569c571c..4f851c9b8044 100644
--- a/apps/web/src/components/settings/SettingsSidebarNav.tsx
+++ b/apps/web/src/components/settings/SettingsSidebarNav.tsx
@@ -8,6 +8,7 @@ import {
   useState,
   type ComponentType,
   type KeyboardEvent,
+  type ReactNode,
 } from "react";
 import {
   ArchiveIcon,
@@ -24,6 +25,7 @@ import {
 import { useLocation, useNavigate } from "@tanstack/react-router";
 
 import { Button } from "../ui/button";
+import { Collapsible, CollapsiblePanel } from "../ui/collapsible";
 import { Input } from "../ui/input";
 import { Kbd } from "../ui/kbd";
 import {
@@ -114,6 +116,22 @@ function SettingsSectionIcon({ to }: { to: SettingsPath }) {
   return <Icon className="mt-0.5 size-3.5 shrink-0 text-sidebar-muted-foreground/60" />;
 }
 
+function SettingsSubmenuCollapse({
+  open,
+  children,
+}: {
+  readonly open: boolean;
+  readonly children: ReactNode;
+}) {
+  return (
+    <Collapsible open={open}>
+      <CollapsiblePanel className="duration-150 ease-out motion-reduce:transition-none">
+        {children}
+      </CollapsiblePanel>
+    </Collapsible>
+  );
+}
+
 export function SettingsSidebarNav({ pathname }: { pathname: string }) {
   const navigate = useNavigate();
   const currentHash = useLocation({ select: (location) => location.hash });
@@ -125,6 +143,9 @@ export function SettingsSidebarNav({ pathname }: { pathname: string }) {
   const results = useMemo(() => searchSettings(query, searchableItems), [query, searchableItems]);
   const isSearching = query.trim().length > 0;
   const hasResults = results.length > 0;
+  const activeSettingsPath = SETTINGS_NAV_ITEMS.find(
+    (item) => pathname === item.to || pathname.startsWith(`${item.to}/`),
+  )?.to;
 
   useEffect(() => {
     setActiveResultIndex((index) => Math.min(index, Math.max(results.length - 1, 0)));
@@ -347,8 +368,8 @@ export function SettingsSidebarNav({ pathname }: { pathname: string }) {
             <SidebarMenu className="ps-px">
               {SETTINGS_NAV_ITEMS.map((item) => {
                 const Icon = item.icon;
-                const isActive = pathname === item.to || pathname.startsWith(`${item.to}/`);
                 const pageSections = SETTINGS_PAGE_SECTIONS[item.to];
+                const isActive = activeSettingsPath === item.to;
                 return (
                   <SidebarMenuItem key={item.to}>
                     <SidebarMenuButton
@@ -358,21 +379,23 @@ export function SettingsSidebarNav({ pathname }: { pathname: string }) {
                       <Icon />
                       <span className="truncate">{item.label}</span>
                     </SidebarMenuButton>
-                    {isActive && pageSections ? (
-                      <SidebarMenuSub className="border-l-0">
-                        {pageSections.map((section) => (
-                          <SidebarMenuSubItem key={section.targetId}>
-                            <SidebarMenuSubButton
-                              render={<button type="button" />}
-                              size="sm"
-                              className="w-full text-sidebar-muted-foreground/65"
-                              onClick={() => handlePageSectionClick(item.to, section.targetId)}
-                            >
-                              <span className="ms-0.5">{section.label}</span>
-                            </SidebarMenuSubButton>
-                          </SidebarMenuSubItem>
-                        ))}
-                      </SidebarMenuSub>
+                    {pageSections ? (
+                      <SettingsSubmenuCollapse open={isActive}>
+                        <SidebarMenuSub className="border-l-0">
+                          {pageSections.map((section) => (
+                            <SidebarMenuSubItem key={section.targetId}>
+                              <SidebarMenuSubButton
+                                render={<button type="button" />}
+                                size="sm"
+                                className="w-full text-sidebar-muted-foreground/65"
+                                onClick={() => handlePageSectionClick(item.to, section.targetId)}
+                              >
+                                <span className="ms-0.5">{section.label}</span>
+                              </SidebarMenuSubButton>
+                            </SidebarMenuSubItem>
+                          ))}
+                        </SidebarMenuSub>
+                      </SettingsSubmenuCollapse>
                     ) : null}
                   </SidebarMenuItem>
                 );

From 4d3907f63d71644e1918d76cd104b036535a1173 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 17:06:27 -0700
Subject: [PATCH 41/56] feat(web): highlight visible settings sections (#9812)

---
 .../settings/SettingsSidebarNav.tsx           |  49 +++-
 .../settingsSectionVisibility.test.ts         | 245 ++++++++++++++++++
 .../settings/settingsSectionVisibility.ts     | 186 +++++++++++++
 apps/web/src/routes/settings.tsx              |   5 +-
 4 files changed, 482 insertions(+), 3 deletions(-)
 create mode 100644 apps/web/src/components/settings/settingsSectionVisibility.test.ts
 create mode 100644 apps/web/src/components/settings/settingsSectionVisibility.ts

diff --git a/apps/web/src/components/settings/SettingsSidebarNav.tsx b/apps/web/src/components/settings/SettingsSidebarNav.tsx
index 4f851c9b8044..f8f0254cda61 100644
--- a/apps/web/src/components/settings/SettingsSidebarNav.tsx
+++ b/apps/web/src/components/settings/SettingsSidebarNav.tsx
@@ -22,12 +22,13 @@ import {
   Settings2Icon,
   XIcon,
 } from "lucide-react";
-import { useLocation, useNavigate } from "@tanstack/react-router";
+import { useLocation, useNavigate, useRouterState } from "@tanstack/react-router";
 
 import { Button } from "../ui/button";
 import { Collapsible, CollapsiblePanel } from "../ui/collapsible";
 import { Input } from "../ui/input";
 import { Kbd } from "../ui/kbd";
+import { cn } from "../../lib/utils";
 import {
   SidebarContent,
   SidebarFooter,
@@ -42,6 +43,11 @@ import {
 } from "../ui/sidebar";
 import { SidebarUtilityMenu } from "../sidebar/SidebarChrome";
 import { scrollToSettingsTarget } from "./settingsLayout";
+import {
+  getVisibleSettingsSectionIds,
+  observeSettingsSectionVisibility,
+  type SettingsSectionVisibilityState,
+} from "./settingsSectionVisibility";
 import {
   searchSettings,
   SETTINGS_SECTION_LABELS,
@@ -99,6 +105,7 @@ const SETTINGS_PAGE_SECTIONS: Partial<
   "/settings/appearance": [
     { label: "Colors & themes", targetId: "appearance" },
     { label: "Interface", targetId: "appearance-interface" },
+    { label: "Motion", targetId: "motion" },
     { label: "Typography", targetId: "typography" },
   ],
   "/settings/source-control": [
@@ -135,10 +142,16 @@ function SettingsSubmenuCollapse({
 export function SettingsSidebarNav({ pathname }: { pathname: string }) {
   const navigate = useNavigate();
   const currentHash = useLocation({ select: (location) => location.hash });
+  const resolvedPathname = useRouterState({
+    select: (state) => state.resolvedLocation?.pathname,
+  });
   const { isMobile, setOpenMobile, open, setOpen } = useSidebar();
   const searchInputRef = useRef<HTMLInputElement>(null);
   const [query, setQuery] = useState("");
   const [activeResultIndex, setActiveResultIndex] = useState(0);
+  const [sectionVisibility, setSectionVisibility] = useState<SettingsSectionVisibilityState | null>(
+    null,
+  );
   const searchableItems = useAvailableSettingsSearchItems();
   const results = useMemo(() => searchSettings(query, searchableItems), [query, searchableItems]);
   const isSearching = query.trim().length > 0;
@@ -146,6 +159,33 @@ export function SettingsSidebarNav({ pathname }: { pathname: string }) {
   const activeSettingsPath = SETTINGS_NAV_ITEMS.find(
     (item) => pathname === item.to || pathname.startsWith(`${item.to}/`),
   )?.to;
+  const observedVisibilityScope = useMemo(() => {
+    const path = SETTINGS_NAV_ITEMS.find(
+      (item) =>
+        resolvedPathname === item.to || resolvedPathname?.startsWith(`${item.to}/`) === true,
+    )?.to;
+    const pageSections = path ? SETTINGS_PAGE_SECTIONS[path] : undefined;
+    return path && pageSections ? { path, pageSections } : null;
+  }, [resolvedPathname]);
+  const visiblePageSectionIds = getVisibleSettingsSectionIds({
+    activePath: activeSettingsPath,
+    scope: observedVisibilityScope,
+    visibility: sectionVisibility,
+  });
+
+  useEffect(() => {
+    if (!observedVisibilityScope) return;
+    const container = document.querySelector<HTMLElement>("[data-settings-page-layout]");
+    if (!container) return;
+
+    return observeSettingsSectionVisibility({
+      container,
+      targetIds: observedVisibilityScope.pageSections.map((section) => section.targetId),
+      onChange(targetIds) {
+        setSectionVisibility({ scope: observedVisibilityScope, targetIds: new Set(targetIds) });
+      },
+    });
+  }, [observedVisibilityScope]);
 
   useEffect(() => {
     setActiveResultIndex((index) => Math.min(index, Math.max(results.length - 1, 0)));
@@ -387,7 +427,12 @@ export function SettingsSidebarNav({ pathname }: { pathname: string }) {
                               <SidebarMenuSubButton
                                 render={<button type="button" />}
                                 size="sm"
-                                className="w-full text-sidebar-muted-foreground/65"
+                                data-visible={visiblePageSectionIds.has(section.targetId)}
+                                className={cn(
+                                  "w-full text-sidebar-muted-foreground/65",
+                                  visiblePageSectionIds.has(section.targetId) &&
+                                    "font-medium text-sidebar-foreground",
+                                )}
                                 onClick={() => handlePageSectionClick(item.to, section.targetId)}
                               >
                                 <span className="ms-0.5">{section.label}</span>
diff --git a/apps/web/src/components/settings/settingsSectionVisibility.test.ts b/apps/web/src/components/settings/settingsSectionVisibility.test.ts
new file mode 100644
index 000000000000..90656ad7073a
--- /dev/null
+++ b/apps/web/src/components/settings/settingsSectionVisibility.test.ts
@@ -0,0 +1,245 @@
+import { describe, expect, it, vi } from "vite-plus/test";
+
+import {
+  getVisibleSettingsSectionIds,
+  observeSettingsSectionVisibility,
+  type SettingsSectionVisibilityEnvironment,
+} from "./settingsSectionVisibility";
+
+type VisibilityEntry = Pick<
+  IntersectionObserverEntry,
+  "intersectionRatio" | "isIntersecting" | "target"
+>;
+
+function createHarness(
+  targetIds: ReadonlyArray<string>,
+  initialRoot: Element | null = { name: "initial-root" } as unknown as Element,
+) {
+  const targets = new Map(
+    targetIds.map((targetId) => [targetId, { targetId } as unknown as Element]),
+  );
+  const observed = new Set<Element>();
+  const unobserve = vi.fn((target: Element) => observed.delete(target));
+  const disconnectIntersections = vi.fn();
+  const disconnectMutations = vi.fn();
+  const intersectionCallbacks: Array<(entries: ReadonlyArray<VisibilityEntry>) => void> = [];
+  const intersectionRoots: Element[] = [];
+  let root = initialRoot;
+  let onMutation = () => {};
+
+  const environment: SettingsSectionVisibilityEnvironment = {
+    findRoot: () => root,
+    findTarget: (_root, targetId) => targets.get(targetId) ?? null,
+    createIntersectionObserver(callback, observedRoot) {
+      intersectionCallbacks.push(callback);
+      intersectionRoots.push(observedRoot);
+      return {
+        observe: (target) => observed.add(target),
+        unobserve,
+        disconnect: disconnectIntersections,
+      };
+    },
+    createMutationObserver(callback) {
+      onMutation = callback;
+      return { disconnect: disconnectMutations };
+    },
+  };
+
+  return {
+    environment,
+    targets,
+    observed,
+    unobserve,
+    disconnectIntersections,
+    disconnectMutations,
+    intersectionCallbacks,
+    intersectionRoots,
+    intersect(entries: ReadonlyArray<VisibilityEntry>) {
+      intersectionCallbacks.at(-1)?.(entries);
+    },
+    mutate() {
+      onMutation();
+    },
+    replaceRoot(nextRoot: Element | null) {
+      root = nextRoot;
+      onMutation();
+    },
+  };
+}
+
+function visibleEntry(
+  target: Element,
+  { isIntersecting = true, intersectionRatio = 1 } = {},
+): VisibilityEntry {
+  return { target, isIntersecting, intersectionRatio };
+}
+
+describe("settings section visibility", () => {
+  it("does not reuse visibility when returning to the same sectioned route", () => {
+    const firstGeneralVisit = { path: "/settings/general" };
+    const firstVisibility = {
+      scope: firstGeneralVisit,
+      targetIds: new Set(["text-generation"]),
+    };
+
+    expect(
+      getVisibleSettingsSectionIds({
+        activePath: "/settings/general",
+        scope: firstGeneralVisit,
+        visibility: firstVisibility,
+      }),
+    ).toEqual(new Set(["text-generation"]));
+    expect(
+      getVisibleSettingsSectionIds({
+        activePath: "/settings/providers",
+        scope: null,
+        visibility: firstVisibility,
+      }),
+    ).toEqual(new Set());
+
+    const secondGeneralVisit = { path: "/settings/general" };
+    expect(
+      getVisibleSettingsSectionIds({
+        activePath: "/settings/general",
+        scope: secondGeneralVisit,
+        visibility: firstVisibility,
+      }),
+    ).toEqual(new Set());
+  });
+
+  it("accumulates visible sections and emits them in sidebar order", () => {
+    const harness = createHarness(["one", "two", "three"]);
+    const emissions: ReadonlyArray<string>[] = [];
+    observeSettingsSectionVisibility({
+      container: {} as Element,
+      targetIds: ["one", "two", "three"],
+      onChange: (visible) => emissions.push(visible),
+      environment: harness.environment,
+    });
+
+    harness.intersect([visibleEntry(harness.targets.get("two")!)]);
+    harness.intersect([visibleEntry(harness.targets.get("one")!)]);
+
+    expect(emissions).toEqual([[], ["two"], ["one", "two"]]);
+  });
+
+  it("treats zero-ratio and non-intersecting entries as hidden", () => {
+    const harness = createHarness(["one", "two"]);
+    const emissions: ReadonlyArray<string>[] = [];
+    observeSettingsSectionVisibility({
+      container: {} as Element,
+      targetIds: ["one", "two"],
+      onChange: (visible) => emissions.push(visible),
+      environment: harness.environment,
+    });
+
+    const one = harness.targets.get("one")!;
+    const two = harness.targets.get("two")!;
+    harness.intersect([visibleEntry(one), visibleEntry(two)]);
+    harness.intersect([visibleEntry(one, { intersectionRatio: 0 })]);
+    harness.intersect([visibleEntry(two, { isIntersecting: false })]);
+
+    expect(emissions).toEqual([[], ["one", "two"], ["two"], []]);
+  });
+
+  it("resyncs replaced and removed targets without retaining stale visibility", () => {
+    const harness = createHarness(["dynamic"]);
+    const emissions: ReadonlyArray<string>[] = [];
+    observeSettingsSectionVisibility({
+      container: {} as Element,
+      targetIds: ["dynamic"],
+      onChange: (visible) => emissions.push(visible),
+      environment: harness.environment,
+    });
+
+    const firstTarget = harness.targets.get("dynamic")!;
+    harness.intersect([visibleEntry(firstTarget)]);
+    const replacementTarget = { targetId: "dynamic-replacement" } as unknown as Element;
+    harness.targets.set("dynamic", replacementTarget);
+    harness.mutate();
+
+    expect(harness.unobserve).toHaveBeenCalledWith(firstTarget);
+    expect(harness.observed.has(replacementTarget)).toBe(true);
+    expect(emissions.at(-1)).toEqual([]);
+
+    harness.intersect([visibleEntry(firstTarget)]);
+    expect(emissions.at(-1)).toEqual([]);
+    harness.intersect([visibleEntry(replacementTarget)]);
+    expect(emissions.at(-1)).toEqual(["dynamic"]);
+
+    harness.targets.delete("dynamic");
+    harness.mutate();
+    expect(harness.unobserve).toHaveBeenCalledWith(replacementTarget);
+    expect(emissions.at(-1)).toEqual([]);
+  });
+
+  it("rebinds when navigation replaces the settings scroll root", () => {
+    const harness = createHarness(["section"]);
+    const emissions: ReadonlyArray<string>[] = [];
+    observeSettingsSectionVisibility({
+      container: {} as Element,
+      targetIds: ["section"],
+      onChange: (visible) => emissions.push(visible),
+      environment: harness.environment,
+    });
+
+    const firstTarget = harness.targets.get("section")!;
+    harness.intersect([visibleEntry(firstTarget)]);
+    const firstObserverCallback = harness.intersectionCallbacks[0]!;
+    const nextRoot = { name: "next-root" } as unknown as Element;
+    const nextTarget = { targetId: "next-section" } as unknown as Element;
+    harness.targets.set("section", nextTarget);
+    harness.replaceRoot(nextRoot);
+
+    expect(harness.disconnectIntersections).toHaveBeenCalledOnce();
+    expect(harness.intersectionRoots.at(-1)).toBe(nextRoot);
+    expect(harness.observed.has(nextTarget)).toBe(true);
+    expect(emissions.at(-1)).toEqual([]);
+
+    firstObserverCallback([visibleEntry(firstTarget)]);
+    expect(emissions.at(-1)).toEqual([]);
+    harness.intersect([visibleEntry(nextTarget)]);
+    expect(emissions.at(-1)).toEqual(["section"]);
+  });
+
+  it("starts observing when the settings scroll root mounts later", () => {
+    const harness = createHarness(["section"], null);
+    const emissions: ReadonlyArray<string>[] = [];
+    observeSettingsSectionVisibility({
+      container: {} as Element,
+      targetIds: ["section"],
+      onChange: (visible) => emissions.push(visible),
+      environment: harness.environment,
+    });
+
+    expect(emissions).toEqual([[]]);
+    expect(harness.intersectionRoots).toEqual([]);
+
+    const root = { name: "mounted-root" } as unknown as Element;
+    harness.replaceRoot(root);
+    harness.intersect([visibleEntry(harness.targets.get("section")!)]);
+
+    expect(harness.intersectionRoots).toEqual([root]);
+    expect(emissions.at(-1)).toEqual(["section"]);
+  });
+
+  it("disconnects both observers and ignores callbacks after cleanup", () => {
+    const harness = createHarness(["one"]);
+    const onChange = vi.fn();
+    const cleanup = observeSettingsSectionVisibility({
+      container: {} as Element,
+      targetIds: ["one"],
+      onChange,
+      environment: harness.environment,
+    });
+
+    cleanup();
+    harness.intersect([visibleEntry(harness.targets.get("one")!)]);
+    harness.mutate();
+
+    expect(harness.disconnectIntersections).toHaveBeenCalledOnce();
+    expect(harness.disconnectMutations).toHaveBeenCalledOnce();
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange).toHaveBeenLastCalledWith([]);
+  });
+});
diff --git a/apps/web/src/components/settings/settingsSectionVisibility.ts b/apps/web/src/components/settings/settingsSectionVisibility.ts
new file mode 100644
index 000000000000..76b1fc943256
--- /dev/null
+++ b/apps/web/src/components/settings/settingsSectionVisibility.ts
@@ -0,0 +1,186 @@
+type VisibilityEntry = Pick<
+  IntersectionObserverEntry,
+  "intersectionRatio" | "isIntersecting" | "target"
+>;
+
+export type SettingsSectionVisibilityScope = {
+  readonly path: string;
+};
+
+export type SettingsSectionVisibilityState = {
+  readonly scope: SettingsSectionVisibilityScope;
+  readonly targetIds: ReadonlySet<string>;
+};
+
+const EMPTY_VISIBLE_SETTINGS_SECTION_IDS: ReadonlySet<string> = new Set();
+
+export function getVisibleSettingsSectionIds({
+  activePath,
+  scope,
+  visibility,
+}: {
+  readonly activePath: string | undefined;
+  readonly scope: SettingsSectionVisibilityScope | null;
+  readonly visibility: SettingsSectionVisibilityState | null;
+}): ReadonlySet<string> {
+  if (!scope || activePath !== scope.path || visibility?.scope !== scope) {
+    return EMPTY_VISIBLE_SETTINGS_SECTION_IDS;
+  }
+  return visibility.targetIds;
+}
+
+type ElementObserver = {
+  observe(target: Element): void;
+  unobserve(target: Element): void;
+  disconnect(): void;
+};
+
+type MutationSubscription = {
+  disconnect(): void;
+};
+
+export type SettingsSectionVisibilityEnvironment = {
+  findRoot(container: Element): Element | null;
+  findTarget(root: Element, targetId: string): Element | null;
+  createIntersectionObserver(
+    onEntries: (entries: ReadonlyArray<VisibilityEntry>) => void,
+    root: Element,
+  ): ElementObserver;
+  createMutationObserver(onMutation: () => void, container: Element): MutationSubscription;
+};
+
+function createBrowserEnvironment(): SettingsSectionVisibilityEnvironment {
+  return {
+    findRoot(container) {
+      return container.querySelector("[data-settings-page-scroll]");
+    },
+    findTarget(root, targetId) {
+      const target = root.ownerDocument.getElementById(targetId);
+      return target && root.contains(target) ? target : null;
+    },
+    createIntersectionObserver(onEntries, scrollRoot) {
+      const observer = new IntersectionObserver(onEntries, {
+        root: scrollRoot,
+        threshold: 0,
+      });
+      return observer;
+    },
+    createMutationObserver(onMutation, container) {
+      const observer = new MutationObserver(onMutation);
+      observer.observe(container, { childList: true, subtree: true });
+      return observer;
+    },
+  };
+}
+
+export function observeSettingsSectionVisibility({
+  container,
+  targetIds,
+  onChange,
+  environment = createBrowserEnvironment(),
+}: {
+  readonly container: Element;
+  readonly targetIds: ReadonlyArray<string>;
+  readonly onChange: (visibleTargetIds: ReadonlyArray<string>) => void;
+  readonly environment?: SettingsSectionVisibilityEnvironment;
+}): () => void {
+  const orderedTargetIds = [...new Set(targetIds)];
+  const targetsById = new Map<string, Element>();
+  const targetIdsByElement = new Map<Element, string>();
+  const visibleTargetIds = new Set<string>();
+  let lastEmission: string | null = null;
+  let stopped = false;
+  let root: Element | null = null;
+  let intersectionObserver: ElementObserver | null = null;
+  let observerGeneration = 0;
+
+  const emit = () => {
+    const visibleInOrder = orderedTargetIds.filter((targetId) => visibleTargetIds.has(targetId));
+    const emissionKey = visibleInOrder.join("\0");
+    if (emissionKey === lastEmission) return;
+    lastEmission = emissionKey;
+    onChange(visibleInOrder);
+  };
+
+  const handleEntries = (entries: ReadonlyArray<VisibilityEntry>, generation: number) => {
+    if (stopped || generation !== observerGeneration) return;
+    let changed = false;
+    for (const entry of entries) {
+      const targetId = targetIdsByElement.get(entry.target);
+      if (!targetId || targetsById.get(targetId) !== entry.target) continue;
+      const visible = entry.isIntersecting && entry.intersectionRatio > 0;
+      if (visible === visibleTargetIds.has(targetId)) continue;
+      changed = true;
+      if (visible) {
+        visibleTargetIds.add(targetId);
+      } else {
+        visibleTargetIds.delete(targetId);
+      }
+    }
+    if (changed) emit();
+  };
+
+  const syncTargets = () => {
+    if (stopped) return;
+    let changed = false;
+    const nextRoot = environment.findRoot(container);
+
+    if (nextRoot !== root) {
+      observerGeneration += 1;
+      intersectionObserver?.disconnect();
+      intersectionObserver = null;
+      root = nextRoot;
+      targetsById.clear();
+      targetIdsByElement.clear();
+      changed = visibleTargetIds.size > 0;
+      visibleTargetIds.clear();
+
+      if (root) {
+        const generation = observerGeneration;
+        intersectionObserver = environment.createIntersectionObserver(
+          (entries) => handleEntries(entries, generation),
+          root,
+        );
+      }
+    }
+
+    if (!root || !intersectionObserver) {
+      if (changed) emit();
+      return;
+    }
+
+    for (const targetId of orderedTargetIds) {
+      const previousTarget = targetsById.get(targetId) ?? null;
+      const nextTarget = environment.findTarget(root, targetId);
+      if (previousTarget === nextTarget) continue;
+
+      if (previousTarget) {
+        intersectionObserver.unobserve(previousTarget);
+        targetsById.delete(targetId);
+        targetIdsByElement.delete(previousTarget);
+        changed = visibleTargetIds.delete(targetId) || changed;
+      }
+      if (nextTarget) {
+        targetsById.set(targetId, nextTarget);
+        targetIdsByElement.set(nextTarget, targetId);
+        intersectionObserver.observe(nextTarget);
+      }
+    }
+
+    if (changed) emit();
+  };
+
+  const mutationObserver = environment.createMutationObserver(syncTargets, container);
+  syncTargets();
+  emit();
+
+  return () => {
+    stopped = true;
+    observerGeneration += 1;
+    intersectionObserver?.disconnect();
+    mutationObserver.disconnect();
+    targetsById.clear();
+    targetIdsByElement.clear();
+    visibleTargetIds.clear();
+  };
+}
diff --git a/apps/web/src/routes/settings.tsx b/apps/web/src/routes/settings.tsx
index 5e921fca5c2c..696ad200f3b7 100644
--- a/apps/web/src/routes/settings.tsx
+++ b/apps/web/src/routes/settings.tsx
@@ -69,7 +69,10 @@ function SettingsContentLayout() {
   }, [navigateBackWithinApp]);
 
   return (
-    <SidebarInset className="h-dvh min-h-0 overflow-hidden overscroll-y-none bg-background text-foreground isolate">
+    <SidebarInset
+      className="h-dvh min-h-0 overflow-hidden overscroll-y-none bg-background text-foreground isolate"
+      data-settings-page-layout
+    >
       <div className="flex min-h-0 min-w-0 flex-1 flex-col bg-background text-foreground">
         <WorkspacePageHeader electron={isElectron}>
           <div className="flex w-full items-center gap-3">

From 1963ca0abe07f9b9aac67820bca45ea3b46ce023 Mon Sep 17 00:00:00 2001
From: Igor Makowski <56691628+Mnigos@users.noreply.github.com>
Date: Sat, 5 Sep 2026 02:19:36 +0200
Subject: [PATCH 42/56] fix(web): keep the sidebar project filter across
 navigation (#9416)

Co-authored-by: Julius Marminge <51714798+juliusmarminge@users.noreply.github.com>
---
 apps/web/src/components/Sidebar.tsx |  20 ++++-
 apps/web/src/hostedPairing.ts       |   5 +-
 apps/web/src/state/entities.ts      |   9 +-
 apps/web/src/state/shell.test.ts    | 135 ++++++++++++++++++++++++++++
 apps/web/src/state/shell.ts         |  38 ++++++++
 apps/web/src/uiStateStore.test.ts   |  25 ++++++
 apps/web/src/uiStateStore.ts        |  32 +++++--
 7 files changed, 252 insertions(+), 12 deletions(-)
 create mode 100644 apps/web/src/state/shell.test.ts

diff --git a/apps/web/src/components/Sidebar.tsx b/apps/web/src/components/Sidebar.tsx
index 4509fde6ceb9..2902e238e01e 100644
--- a/apps/web/src/components/Sidebar.tsx
+++ b/apps/web/src/components/Sidebar.tsx
@@ -111,7 +111,11 @@ import { useCopyToClipboard } from "../hooks/useCopyToClipboard";
 import { useLocalStorage } from "../hooks/useLocalStorage";
 import { useNowMinute } from "../hooks/useNowMinute";
 import { useEnvironments, usePrimaryEnvironmentId } from "../state/environments";
-import { useProjects, useThreadShells } from "../state/entities";
+import {
+  useAllEnvironmentProjectSnapshotsReady,
+  useProjects,
+  useThreadShells,
+} from "../state/entities";
 import { environmentServerConfigsAtom, primaryServerKeybindingsAtom } from "../state/server";
 import { vcsEnvironment } from "../state/vcs";
 import { threadEnvironment } from "../state/threads";
@@ -2098,7 +2102,11 @@ export default function Sidebar() {
 
   // Project scope: one menu above the list. Scoping filters the list without
   // making the header width depend on the number or length of project names.
-  const [projectScopeKey, setProjectScopeKey] = useState<string | null>(null);
+  // The selection lives in the persisted UI store next to the other sidebar
+  // project preferences, so routes that unmount the sidebar (Settings) and
+  // app restarts keep it.
+  const projectScopeKey = useUiStateStore((store) => store.sidebarProjectScopeKey);
+  const setProjectScopeKey = useUiStateStore((store) => store.setSidebarProjectScopeKey);
   // {value, label} items let Base UI drive the combobox selection contract
   // while the popup search filters the same collection.
   const projectScopeItems = useMemo(
@@ -2162,11 +2170,15 @@ export default function Sidebar() {
           ),
     [scopedProjectGroup],
   );
+  // A persisted scope whose project is gone falls back to all projects, but
+  // only after every catalog environment has a live project snapshot. Cached
+  // or disconnected environments cannot establish that the project is gone.
+  const allProjectSnapshotsReady = useAllEnvironmentProjectSnapshotsReady();
   useEffect(() => {
-    if (projectScopeKey !== null && scopedProjectGroup === null) {
+    if (projectScopeKey !== null && allProjectSnapshotsReady && scopedProjectGroup === null) {
       setProjectScopeKey(null);
     }
-  }, [projectScopeKey, scopedProjectGroup]);
+  }, [allProjectSnapshotsReady, projectScopeKey, scopedProjectGroup, setProjectScopeKey]);
   // Count-only subscription: the parent needs "are there draft rows" for the
   // empty state, while SidebarDraftBlock owns the per-keystroke content
   // subscription. Selecting a number keeps typing in a draft composer from
diff --git a/apps/web/src/hostedPairing.ts b/apps/web/src/hostedPairing.ts
index 6c5ac58cb35d..87c352244e5f 100644
--- a/apps/web/src/hostedPairing.ts
+++ b/apps/web/src/hostedPairing.ts
@@ -40,8 +40,9 @@ export function isHostedStaticApp(url?: URL): boolean {
     return true;
   }
 
-  // No window (tests, static render) means no origin to be hosted at.
-  if (url === undefined && typeof window === "undefined") {
+  // No window, or a window without a location (tests, static render), means
+  // no origin to be hosted at.
+  if (url === undefined && (typeof window === "undefined" || window.location === undefined)) {
     return false;
   }
 
diff --git a/apps/web/src/state/entities.ts b/apps/web/src/state/entities.ts
index ec1e4c836211..c44c5b437b63 100644
--- a/apps/web/src/state/entities.ts
+++ b/apps/web/src/state/entities.ts
@@ -15,7 +15,10 @@ import { useMemo } from "react";
 import { appAtomRegistry } from "../rpc/atomRegistry";
 import { environmentProjects } from "./projects";
 import { environmentServerConfigsAtom } from "./server";
-import { allEnvironmentShellsBootstrappedAtom } from "./shell";
+import {
+  allEnvironmentProjectSnapshotsReadyAtom,
+  allEnvironmentShellsBootstrappedAtom,
+} from "./shell";
 import { environmentThreadDetails, environmentThreadShells } from "./threads";
 
 const EMPTY_THREAD_REFS: ReadonlyArray<ScopedThreadRef> = Object.freeze([]);
@@ -79,6 +82,10 @@ export function useAllEnvironmentShellsBootstrapped(): boolean {
   return useAtomValue(allEnvironmentShellsBootstrappedAtom);
 }
 
+export function useAllEnvironmentProjectSnapshotsReady(): boolean {
+  return useAtomValue(allEnvironmentProjectSnapshotsReadyAtom);
+}
+
 export function useThreadShellsForProjectRefs(
   refs: ReadonlyArray<ScopedProjectRef>,
 ): ReadonlyArray<EnvironmentThreadShell> {
diff --git a/apps/web/src/state/shell.test.ts b/apps/web/src/state/shell.test.ts
new file mode 100644
index 000000000000..745e674400d3
--- /dev/null
+++ b/apps/web/src/state/shell.test.ts
@@ -0,0 +1,135 @@
+import {
+  BearerConnectionTarget,
+  PrimaryConnectionTarget,
+} from "@t3tools/client-runtime/connection";
+import type { EnvironmentCatalogState } from "@t3tools/client-runtime/state/connections";
+import type { EnvironmentShellState } from "@t3tools/client-runtime/state/shell";
+import { EnvironmentId } from "@t3tools/contracts";
+import * as Option from "effect/Option";
+import { Atom, AtomRegistry } from "effect/unstable/reactivity";
+import { describe, expect, it } from "vite-plus/test";
+
+import { createAllEnvironmentProjectSnapshotsReadyAtom } from "./shell";
+
+const LOCAL = EnvironmentId.make("local");
+const REMOTE = EnvironmentId.make("remote");
+
+function shellState(status: EnvironmentShellState["status"]): EnvironmentShellState {
+  return {
+    status,
+    snapshot:
+      status === "empty"
+        ? Option.none()
+        : Option.some({
+            snapshotSequence: 1,
+            updatedAt: "2026-09-04T00:00:00.000Z",
+            projects: [],
+            threads: [],
+          }),
+    error: Option.none(),
+  };
+}
+
+function catalogState(environmentIds: readonly EnvironmentId[]): EnvironmentCatalogState {
+  return {
+    isReady: true,
+    entries: new Map(
+      environmentIds.map((environmentId) => [
+        environmentId,
+        {
+          target:
+            environmentId === LOCAL
+              ? new PrimaryConnectionTarget({
+                  environmentId,
+                  label: environmentId,
+                  httpBaseUrl: `https://${environmentId}.example.test`,
+                  wsBaseUrl: `wss://${environmentId}.example.test`,
+                })
+              : new BearerConnectionTarget({
+                  environmentId,
+                  connectionId: environmentId,
+                  label: environmentId,
+                }),
+          profile: Option.none(),
+        },
+      ]),
+    ),
+  };
+}
+
+function makeHarness(requiresPrimaryEnvironment = true) {
+  const catalog = Atom.make<EnvironmentCatalogState>({ isReady: false, entries: new Map() });
+  const shells = Atom.family((_environmentId: EnvironmentId) =>
+    Atom.make<EnvironmentShellState>(shellState("empty")),
+  );
+  const ready = createAllEnvironmentProjectSnapshotsReadyAtom({
+    catalogValueAtom: catalog,
+    shellStateValueAtom: shells,
+    requiresPrimaryEnvironment,
+  });
+  const registry = AtomRegistry.make();
+  return { catalog, shells, ready, registry };
+}
+
+describe("project snapshot readiness", () => {
+  it("does not clear a saved scope while the ready catalog is still empty", () => {
+    const { catalog, ready, registry } = makeHarness();
+    expect(registry.get(ready)).toBe(false);
+    registry.set(catalog, catalogState([]));
+    expect(registry.get(ready)).toBe(false);
+    registry.dispose();
+  });
+
+  it("waits for primary discovery even if a persisted remote is already live", () => {
+    const { catalog, shells, ready, registry } = makeHarness();
+    registry.set(catalog, catalogState([REMOTE]));
+    registry.set(shells(REMOTE), shellState("live"));
+    expect(registry.get(ready)).toBe(false);
+
+    registry.set(catalog, catalogState([LOCAL, REMOTE]));
+    expect(registry.get(ready)).toBe(false);
+    registry.set(shells(LOCAL), shellState("live"));
+    expect(registry.get(ready)).toBe(true);
+    registry.dispose();
+  });
+
+  it("allows a hosted client to load projects without a primary environment", () => {
+    const { catalog, shells, ready, registry } = makeHarness(false);
+    registry.set(catalog, catalogState([REMOTE]));
+    expect(registry.get(ready)).toBe(false);
+    registry.set(shells(REMOTE), shellState("live"));
+    expect(registry.get(ready)).toBe(true);
+    registry.dispose();
+  });
+
+  it("waits for live snapshots through offline startup and reconnect", () => {
+    const { catalog, shells, ready, registry } = makeHarness();
+    registry.set(catalog, catalogState([LOCAL, REMOTE]));
+    registry.set(shells(LOCAL), shellState("live"));
+    expect(registry.get(ready)).toBe(false);
+
+    // An old cache and a reconnect in progress can both omit a real project.
+    registry.set(shells(REMOTE), shellState("cached"));
+    expect(registry.get(ready)).toBe(false);
+    registry.set(shells(REMOTE), shellState("synchronizing"));
+    expect(registry.get(ready)).toBe(false);
+    registry.set(shells(REMOTE), shellState("live"));
+    expect(registry.get(ready)).toBe(true);
+
+    registry.set(shells(REMOTE), shellState("cached"));
+    expect(registry.get(ready)).toBe(false);
+    registry.set(shells(REMOTE), shellState("live"));
+    expect(registry.get(ready)).toBe(true);
+    registry.dispose();
+  });
+
+  it("stops waiting for an environment only when it leaves the catalog", () => {
+    const { catalog, shells, ready, registry } = makeHarness();
+    registry.set(catalog, catalogState([LOCAL, REMOTE]));
+    registry.set(shells(LOCAL), shellState("live"));
+    expect(registry.get(ready)).toBe(false);
+    registry.set(catalog, catalogState([LOCAL]));
+    expect(registry.get(ready)).toBe(true);
+    registry.dispose();
+  });
+});
diff --git a/apps/web/src/state/shell.ts b/apps/web/src/state/shell.ts
index dfb104e5c996..1f88da2f971d 100644
--- a/apps/web/src/state/shell.ts
+++ b/apps/web/src/state/shell.ts
@@ -7,12 +7,16 @@ import {
   createEnvironmentShellSummaryAtom,
   createEnvironmentSnapshotAtom,
   createShellEnvironmentAtoms,
+  type EnvironmentShellState,
 } from "@t3tools/client-runtime/state/shell";
+import type { EnvironmentCatalogState } from "@t3tools/client-runtime/state/connections";
+import type { EnvironmentId } from "@t3tools/contracts";
 import * as Option from "effect/Option";
 import { AsyncResult, Atom } from "effect/unstable/reactivity";
 
 import { environmentCatalog } from "../connection/catalog";
 import { connectionAtomRuntime } from "../connection/runtime";
+import { isHostedStaticApp } from "../hostedPairing";
 
 export const shellEnvironment = createShellEnvironmentAtoms(connectionAtomRuntime);
 export const environmentShell = createEnvironmentShellAtoms(connectionAtomRuntime);
@@ -46,3 +50,37 @@ export const allEnvironmentShellsBootstrappedAtom = Atom.make((get) => {
   }
   return true;
 }).pipe(Atom.withLabel("web-all-environment-shells-bootstrapped"));
+
+/** Cached or missing snapshots cannot establish that a saved project no longer exists. */
+export function createAllEnvironmentProjectSnapshotsReadyAtom(input: {
+  readonly catalogValueAtom: Atom.Atom<EnvironmentCatalogState>;
+  readonly shellStateValueAtom: (environmentId: EnvironmentId) => Atom.Atom<EnvironmentShellState>;
+  readonly requiresPrimaryEnvironment: boolean;
+}) {
+  return Atom.make((get) => {
+    const catalog = get(input.catalogValueAtom);
+    // The persisted catalog can emit before platform discovery registers the
+    // primary environment. Neither that gap nor an empty catalog proves absence.
+    if (!catalog.isReady || catalog.entries.size === 0) return false;
+    if (
+      input.requiresPrimaryEnvironment &&
+      !Array.from(catalog.entries.values()).some(
+        (entry) => entry.target._tag === "PrimaryConnectionTarget",
+      )
+    ) {
+      return false;
+    }
+    for (const environmentId of catalog.entries.keys()) {
+      const shell = get(input.shellStateValueAtom(environmentId));
+      if (shell.status !== "live" || Option.isNone(shell.snapshot)) return false;
+    }
+    return true;
+  }).pipe(Atom.withLabel("web-all-environment-project-snapshots-ready"));
+}
+
+export const allEnvironmentProjectSnapshotsReadyAtom =
+  createAllEnvironmentProjectSnapshotsReadyAtom({
+    catalogValueAtom: environmentCatalog.catalogValueAtom,
+    shellStateValueAtom: environmentShell.stateValueAtom,
+    requiresPrimaryEnvironment: !isHostedStaticApp(),
+  });
diff --git a/apps/web/src/uiStateStore.test.ts b/apps/web/src/uiStateStore.test.ts
index bd6db865992b..1a95acbcfbf7 100644
--- a/apps/web/src/uiStateStore.test.ts
+++ b/apps/web/src/uiStateStore.test.ts
@@ -13,6 +13,7 @@ import {
   resolveProjectExpanded,
   setDefaultAdvertisedEndpointKey,
   setProjectExpanded,
+  setSidebarProjectScopeKey,
   setThreadChangedFilesExpanded,
   type UiState,
 } from "./uiStateStore";
@@ -21,6 +22,7 @@ function makeUiState(overrides: Partial<UiState> = {}): UiState {
   return {
     projectExpandedById: {},
     projectOrder: [],
+    sidebarProjectScopeKey: null,
     threadLastVisitedAtById: {},
     threadChangedFilesExpandedById: {},
     defaultAdvertisedEndpointKey: null,
@@ -144,6 +146,15 @@ describe("uiStateStore pure functions", () => {
       defaultAdvertisedEndpointKey: null,
     });
   });
+
+  it("stores the sidebar project scope and resets it to all projects", () => {
+    const scoped = setSidebarProjectScopeKey(makeUiState(), "github.com/pingdotgg/t3code");
+
+    expect(scoped.sidebarProjectScopeKey).toBe("github.com/pingdotgg/t3code");
+    expect(setSidebarProjectScopeKey(scoped, "github.com/pingdotgg/t3code")).toBe(scoped);
+    expect(setSidebarProjectScopeKey(scoped, null).sidebarProjectScopeKey).toBeNull();
+    expect(setSidebarProjectScopeKey(scoped, "").sidebarProjectScopeKey).toBeNull();
+  });
 });
 
 describe("parsePersistedState", () => {
@@ -177,6 +188,7 @@ describe("parsePersistedState", () => {
         "environment:thread-1": "2026-02-25T12:35:00.000Z",
       },
       defaultAdvertisedEndpointKey: "desktop-core:lan:http",
+      sidebarProjectScopeKey: null,
       threadChangedFilesExpandedById: {
         "environment:thread-1": {
           "turn-1": false,
@@ -297,6 +309,7 @@ describe("uiStateStore persistence", () => {
         "environment:thread-1": "2026-02-25T12:35:00.000Z",
       },
       defaultAdvertisedEndpointKey: "desktop-core:lan:http",
+      sidebarProjectScopeKey: null,
       threadChangedFilesExpansionVersion: 2,
       threadChangedFilesExpandedById: {
         "environment:thread-1": {
@@ -310,6 +323,18 @@ describe("uiStateStore persistence", () => {
     });
   });
 
+  it("restores the sidebar project scope across reloads", () => {
+    persistState(makeUiState({ sidebarProjectScopeKey: "github.com/pingdotgg/t3code" }));
+
+    const persisted = JSON.parse(
+      localStorageStub.getItem(PERSISTED_STATE_KEY) ?? "{}",
+    ) as PersistedUiState;
+
+    expect(parsePersistedState(persisted).sidebarProjectScopeKey).toBe(
+      "github.com/pingdotgg/t3code",
+    );
+  });
+
   it("drops the temporary expanded-only migration fallback when rewriting state", () => {
     const migrated = parsePersistedState({
       expandedProjectCwds: ["/repo/a"],
diff --git a/apps/web/src/uiStateStore.ts b/apps/web/src/uiStateStore.ts
index 048055639ce7..b14ce917c861 100644
--- a/apps/web/src/uiStateStore.ts
+++ b/apps/web/src/uiStateStore.ts
@@ -26,6 +26,7 @@ export interface PersistedUiState {
   expandedProjectCwds?: string[];
   projectOrderCwds?: string[];
   defaultAdvertisedEndpointKey?: string | null;
+  sidebarProjectScopeKey?: string | null;
   threadChangedFilesExpansionVersion?: number;
   threadChangedFilesExpandedById?: Record<string, Record<string, boolean>>;
 }
@@ -33,6 +34,10 @@ export interface PersistedUiState {
 export interface UiProjectState {
   projectExpandedById: Record<string, boolean>;
   projectOrder: string[];
+  // Logical project key the sidebar list is scoped to, or null for "all
+  // projects". Lives here so routes that unmount the sidebar (Settings)
+  // cannot reset the filter.
+  sidebarProjectScopeKey: string | null;
 }
 
 export interface UiThreadState {
@@ -49,6 +54,7 @@ export interface UiState extends UiProjectState, UiThreadState, UiEndpointState
 const initialState: UiState = {
   projectExpandedById: {},
   projectOrder: [],
+  sidebarProjectScopeKey: null,
   threadLastVisitedAtById: {},
   threadChangedFilesExpandedById: {},
   defaultAdvertisedEndpointKey: null,
@@ -84,6 +90,10 @@ function sanitizeBooleanRecord(value: unknown): Record<string, boolean> {
   );
 }
 
+function sanitizeOptionalKey(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
 function sanitizeTimestampRecord(value: unknown): Record<string, string> {
   if (!value || typeof value !== "object") {
     return {};
@@ -131,11 +141,8 @@ export function parsePersistedState(parsed: PersistedUiState): UiState {
       parsed.threadChangedFilesExpansionVersion === THREAD_CHANGED_FILES_EXPANSION_VERSION
         ? sanitizePersistedThreadChangedFilesExpanded(parsed.threadChangedFilesExpandedById)
         : {},
-    defaultAdvertisedEndpointKey:
-      typeof parsed.defaultAdvertisedEndpointKey === "string" &&
-      parsed.defaultAdvertisedEndpointKey.length > 0
-        ? parsed.defaultAdvertisedEndpointKey
-        : null,
+    defaultAdvertisedEndpointKey: sanitizeOptionalKey(parsed.defaultAdvertisedEndpointKey),
+    sidebarProjectScopeKey: sanitizeOptionalKey(parsed.sidebarProjectScopeKey),
   };
 }
 
@@ -206,6 +213,7 @@ export function persistState(state: UiState): void {
         projectOrder: state.projectOrder,
         threadLastVisitedAtById: state.threadLastVisitedAtById,
         defaultAdvertisedEndpointKey: state.defaultAdvertisedEndpointKey,
+        sidebarProjectScopeKey: state.sidebarProjectScopeKey,
         threadChangedFilesExpansionVersion: THREAD_CHANGED_FILES_EXPANSION_VERSION,
         threadChangedFilesExpandedById: state.threadChangedFilesExpandedById,
       } satisfies PersistedUiState),
@@ -305,6 +313,17 @@ export function setDefaultAdvertisedEndpointKey(state: UiState, key: string | nu
   };
 }
 
+export function setSidebarProjectScopeKey(state: UiState, projectKey: string | null): UiState {
+  const nextKey = sanitizeOptionalKey(projectKey);
+  if (state.sidebarProjectScopeKey === nextKey) {
+    return state;
+  }
+  return {
+    ...state,
+    sidebarProjectScopeKey: nextKey,
+  };
+}
+
 export function resolveProjectExpanded(
   projectExpandedById: Readonly<Record<string, boolean>>,
   preferenceKeys: readonly string[],
@@ -387,6 +406,7 @@ interface UiStateStore extends UiState {
   markThreadUnread: (threadId: string, latestTurnCompletedAt: string | null | undefined) => void;
   setThreadChangedFilesExpanded: (threadId: string, turnId: string, expanded: boolean) => void;
   setDefaultAdvertisedEndpointKey: (key: string | null) => void;
+  setSidebarProjectScopeKey: (projectKey: string | null) => void;
   setProjectExpanded: (projectIds: string | readonly string[], expanded: boolean) => void;
   reorderProjects: (
     currentProjectOrder: readonly string[],
@@ -405,6 +425,8 @@ export const useUiStateStore = create<UiStateStore>((set) => ({
     set((state) => setThreadChangedFilesExpanded(state, threadId, turnId, expanded)),
   setDefaultAdvertisedEndpointKey: (key) =>
     set((state) => setDefaultAdvertisedEndpointKey(state, key)),
+  setSidebarProjectScopeKey: (projectKey) =>
+    set((state) => setSidebarProjectScopeKey(state, projectKey)),
   setProjectExpanded: (projectIds, expanded) =>
     set((state) => setProjectExpanded(state, projectIds, expanded)),
   reorderProjects: (currentProjectOrder, draggedProjectIds, targetProjectIds) =>

From a5bbad910f78cc14eef8baa94fe6f46676f78d5a Mon Sep 17 00:00:00 2001
From: Darahaas Yajamanyam <63366288+darahaas15@users.noreply.github.com>
Date: Sat, 5 Sep 2026 05:51:15 +0530
Subject: [PATCH 43/56] fix(server): surface Claude safety model fallback
 notices instead of dropping them (#8853)

Co-authored-by: Julius Marminge <51714798+juliusmarminge@users.noreply.github.com>
---
 .../src/provider/Layers/ClaudeAdapter.test.ts | 35 ++++++++++++++-----
 .../src/provider/Layers/ClaudeAdapter.ts      |  9 ++++-
 2 files changed, 34 insertions(+), 10 deletions(-)

diff --git a/apps/server/src/provider/Layers/ClaudeAdapter.test.ts b/apps/server/src/provider/Layers/ClaudeAdapter.test.ts
index 6b02c95f598f..afea9a605084 100644
--- a/apps/server/src/provider/Layers/ClaudeAdapter.test.ts
+++ b/apps/server/src/provider/Layers/ClaudeAdapter.test.ts
@@ -3449,10 +3449,14 @@ describe("ClaudeAdapterLive", () => {
     const harness = makeHarness();
     return Effect.gen(function* () {
       const adapter = yield* ClaudeAdapter;
-      const runtimeEvents: Array<ProviderRuntimeEvent> = [];
-      const runtimeEventsFiber = yield* Stream.runForEach(adapter.streamEvents, (event) =>
-        Effect.sync(() => runtimeEvents.push(event)),
-      ).pipe(Effect.forkChild);
+      const runtimeEventsFiber = yield* adapter.streamEvents.pipe(
+        Stream.takeUntil(
+          (event) =>
+            event.type === "session.state.changed" && event.payload.reason === "api_retry:3/10",
+        ),
+        Stream.runCollect,
+        Effect.forkChild,
+      );
 
       yield* adapter.startSession({
         threadId: THREAD_ID,
@@ -3498,7 +3502,6 @@ describe("ClaudeAdapterLive", () => {
           uuid: "tu",
         },
         { type: "system", subtype: "commands_changed", session_id: "session", uuid: "cc" },
-        { type: "system", subtype: "model_refusal_fallback", session_id: "session", uuid: "mrf" },
         { type: "system", subtype: "local_command_output", session_id: "session", uuid: "lco" },
         { type: "system", subtype: "plugin_install", session_id: "session", uuid: "pi" },
         { type: "system", subtype: "memory_recall", session_id: "session", uuid: "mr" },
@@ -3545,6 +3548,21 @@ describe("ClaudeAdapterLive", () => {
       ]) {
         harness.query.emit(message as unknown as SDKMessage);
       }
+      // Safety model-fallback notices DO surface as a warning row.
+      harness.query.emit({
+        type: "system",
+        subtype: "model_refusal_fallback",
+        trigger: "refusal",
+        direction: "retry",
+        original_model: "claude-fable-5",
+        fallback_model: "claude-opus-4-8",
+        request_id: "req_test",
+        api_refusal_category: "cyber",
+        api_refusal_explanation: null,
+        content: "Safeguards flagged this message. Switched to Opus 4.8.",
+        session_id: "session",
+        uuid: "mrf",
+      } as unknown as SDKMessage);
       // High-priority notifications DO surface as a warning row.
       harness.query.emit({
         type: "system",
@@ -3602,15 +3620,15 @@ describe("ClaudeAdapterLive", () => {
         session_id: "session",
         uuid: "retry",
       } as unknown as SDKMessage);
-      yield* Effect.yieldNow;
-      yield* Effect.yieldNow;
+      const runtimeEvents = Array.from(yield* Fiber.join(runtimeEventsFiber));
 
       const warnings = runtimeEvents.filter((event) => event.type === "runtime.warning");
-      // Exactly three warnings: the high-priority notification, the
+      // Exactly four warnings: the fallback notice, high-priority notification,
       // warning-level informational note, and the refusal. Nothing else.
       assert.deepEqual(
         warnings.map((event) => event.payload.message),
         [
+          "Safeguards flagged this message. Switched to Opus 4.8.",
           "context window nearly full",
           "Stop hook prevented continuation",
           "The request was declined by the API.",
@@ -3638,7 +3656,6 @@ describe("ClaudeAdapterLive", () => {
           event.payload.reason.startsWith("api_retry:"),
       );
       assert.equal(heartbeat?.type, "session.state.changed");
-      runtimeEventsFiber.interruptUnsafe();
     }).pipe(
       Effect.provideService(Random.Random, makeDeterministicRandomService()),
       Effect.provide(harness.layer),
diff --git a/apps/server/src/provider/Layers/ClaudeAdapter.ts b/apps/server/src/provider/Layers/ClaudeAdapter.ts
index 6096fd7cbef7..d295821d8dfa 100644
--- a/apps/server/src/provider/Layers/ClaudeAdapter.ts
+++ b/apps/server/src/provider/Layers/ClaudeAdapter.ts
@@ -3655,6 +3655,14 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
           yield* emitRuntimeWarning(context, message.text, message);
         }
         return;
+      case "model_refusal_fallback":
+        // A safety fallback switched the model mid-session (e.g. Fable 5
+        // retried on Opus 4.8 after a flagged request). The CLI ships the
+        // user-facing notice in `content`; surface it like high-priority
+        // notifications so the rest of the session isn't silently served
+        // by a different model.
+        yield* emitRuntimeWarning(context, message.content, message);
+        return;
       // Inner protocol/UX details with no T3 surface today — consumed
       // deliberately so they don't masquerade as unknown-subtype warnings.
       // `background_tasks_changed` is a roster snapshot ({tasks: [...]}); the
@@ -3663,7 +3671,6 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
       // source. `control_request_progress` is a liveness heartbeat for an
       // in-flight control request. `worker_shutting_down` is a Remote
       // Control worker notice; the session close path reports the outcome.
-      case "model_refusal_fallback":
       case "local_command_output":
       case "plugin_install":
       case "commands_changed":

From caf4981e32f4fd3c9adb8339b5bec2d95d09b7aa Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 17:22:17 -0700
Subject: [PATCH 44/56] fix(web): reload saved colors when reopening the theme
 editor (#9847)

---
 .../settings/ThemeEditorHost.test.tsx         | 191 ++++++++++++++++++
 .../components/settings/ThemeEditorHost.tsx   |  27 ++-
 2 files changed, 209 insertions(+), 9 deletions(-)
 create mode 100644 apps/web/src/components/settings/ThemeEditorHost.test.tsx

diff --git a/apps/web/src/components/settings/ThemeEditorHost.test.tsx b/apps/web/src/components/settings/ThemeEditorHost.test.tsx
new file mode 100644
index 000000000000..eaf0c1b06b2c
--- /dev/null
+++ b/apps/web/src/components/settings/ThemeEditorHost.test.tsx
@@ -0,0 +1,191 @@
+import type { ReactElement } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+import { reactHookHarness as hooks } from "../../test/reactHookHarness";
+import {
+  getThemeDefinition,
+  installCustomTheme,
+  invalidateCustomThemes,
+  parseThemeFile,
+  removeCustomTheme,
+  THEME_FILE_VERSION,
+  themeColorToHex,
+  updateCustomTheme,
+  type ThemeDefinition,
+} from "../../themePalette";
+import type { ThemeEditorSession } from "./themeEditorStore";
+
+const state = vi.hoisted(() => ({
+  session: null as ThemeEditorSession | null,
+  closeThemeEditor: vi.fn(),
+  onStoreChange: vi.fn(),
+  subscriptions: new Set<() => void>(),
+  theme: {
+    theme: "system",
+    themeHalves: null,
+    setTheme: vi.fn(),
+    refreshTheme: vi.fn(),
+  },
+}));
+
+vi.mock("react", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react")>();
+  const { reactHookHarness } = await import("../../test/reactHookHarness");
+  return {
+    ...actual,
+    useCallback: reactHookHarness.useCallback,
+    useSyncExternalStore: (
+      subscribe: (listener: () => void) => () => void,
+      getSnapshot: () => unknown,
+    ) => {
+      const subscription = reactHookHarness.useRef<(() => void) | null>(null);
+      if (!subscription.current) {
+        subscription.current = subscribe(() => state.onStoreChange());
+        state.subscriptions.add(subscription.current);
+      }
+      return getSnapshot();
+    },
+  };
+});
+
+vi.mock("react/compiler-runtime", async () => {
+  const { reactHookHarness } = await import("../../test/reactHookHarness");
+  return { c: reactHookHarness.useMemoCache };
+});
+
+vi.mock("../../hooks/useTheme", () => ({ useTheme: () => state.theme }));
+vi.mock("./themeEditorStore", () => ({
+  useThemeEditorStore: (select: (store: typeof state) => unknown) => select(state),
+}));
+vi.mock("../ui/toast", () => ({
+  toastManager: { add: vi.fn() },
+  stackedThreadToast: (value: unknown) => value,
+}));
+
+import { ThemeEditorHost } from "./ThemeEditorHost";
+
+function renderEditor() {
+  hooks.beginRender();
+  const host = ThemeEditorHost() as ReactElement<{
+    children: ReactElement<{
+      editingTheme: ThemeDefinition | null;
+      seedTheme: ThemeDefinition | null;
+    }>;
+  }> | null;
+  return host?.props.children.props ?? null;
+}
+
+describe("ThemeEditorHost", () => {
+  beforeEach(() => {
+    hooks.reset();
+    state.session = null;
+    state.onStoreChange.mockReset();
+    const storage = new Map<string, string>();
+    vi.stubGlobal("window", {
+      localStorage: {
+        getItem: (key: string) => storage.get(key) ?? null,
+        setItem: (key: string, value: string) => storage.set(key, value),
+      },
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    });
+    invalidateCustomThemes();
+  });
+
+  afterEach(() => {
+    for (const unsubscribe of state.subscriptions) unsubscribe();
+    state.subscriptions.clear();
+    vi.unstubAllGlobals();
+    invalidateCustomThemes();
+  });
+
+  it.each(["editingTheme", "seedTheme"] as const)(
+    "reopens the same %s with its saved colors",
+    (field) => {
+      const theme = installCustomTheme(
+        parseThemeFile({
+          version: THEME_FILE_VERSION,
+          id: "saved-colors",
+          name: "Saved colors",
+          appearance: "dark",
+          colors: { accent: "#1f6e4a" },
+        }),
+      );
+      const session = {
+        id: 1,
+        editingThemeId: field === "editingTheme" ? theme.id : null,
+        seedThemeId: field === "seedTheme" ? theme.id : null,
+        seedName: null,
+        initialAppearance: "dark" as const,
+      };
+      state.session = session;
+      expect(themeColorToHex(renderEditor()?.[field]?.colors.accent ?? "")).toBe("#1f6e4a");
+
+      updateCustomTheme({ ...theme, colors: { ...theme.colors, accent: "#7241b8" } });
+      expect(themeColorToHex(getThemeDefinition(theme.id)?.colors.accent ?? "")).toBe("#7241b8");
+      state.session = null;
+      expect(renderEditor()).toBeNull();
+      state.session = { ...session, id: 2 };
+
+      expect(themeColorToHex(renderEditor()?.[field]?.colors.accent ?? "")).toBe("#7241b8");
+    },
+  );
+
+  it.each(["editingTheme", "seedTheme"] as const)(
+    "refreshes an open %s when the library changes",
+    (field) => {
+      const theme = installCustomTheme(
+        parseThemeFile({
+          version: THEME_FILE_VERSION,
+          id: "updated-theme",
+          name: "Updated theme",
+          appearance: "dark",
+          colors: { accent: "#1f6e4a" },
+        }),
+      );
+      state.session = {
+        id: 1,
+        editingThemeId: field === "editingTheme" ? theme.id : null,
+        seedThemeId: field === "seedTheme" ? theme.id : null,
+        seedName: null,
+        initialAppearance: "dark",
+      };
+      let editor = renderEditor();
+      state.onStoreChange.mockImplementation(() => {
+        editor = renderEditor();
+      });
+
+      updateCustomTheme({ ...theme, colors: { ...theme.colors, accent: "#7241b8" } });
+
+      expect(themeColorToHex(editor?.[field]?.colors.accent ?? "")).toBe("#7241b8");
+    },
+  );
+
+  it("does not keep editing a theme removed from the library", () => {
+    const theme = installCustomTheme(
+      parseThemeFile({
+        version: THEME_FILE_VERSION,
+        id: "removed-theme",
+        name: "Removed theme",
+        appearance: "dark",
+        colors: { accent: "#1f6e4a" },
+      }),
+    );
+    state.session = {
+      id: 1,
+      editingThemeId: theme.id,
+      seedThemeId: null,
+      seedName: null,
+      initialAppearance: "dark",
+    };
+    let editor = renderEditor();
+    expect(editor?.editingTheme?.id).toBe(theme.id);
+    state.onStoreChange.mockImplementation(() => {
+      editor = renderEditor();
+    });
+
+    removeCustomTheme(theme.id);
+
+    expect(editor?.editingTheme).toBeNull();
+  });
+});
diff --git a/apps/web/src/components/settings/ThemeEditorHost.tsx b/apps/web/src/components/settings/ThemeEditorHost.tsx
index 7eca6a2de523..1ffc48fef627 100644
--- a/apps/web/src/components/settings/ThemeEditorHost.tsx
+++ b/apps/web/src/components/settings/ThemeEditorHost.tsx
@@ -1,7 +1,12 @@
-import { lazy, Suspense, useCallback } from "react";
+import { lazy, Suspense, useCallback, useSyncExternalStore } from "react";
 
 import { useTheme } from "../../hooks/useTheme";
-import { getThemeDefinition, type ThemeAppearance, type ThemeDefinition } from "../../themePalette";
+import {
+  getThemeDefinition,
+  subscribeToCustomThemes,
+  type ThemeAppearance,
+  type ThemeDefinition,
+} from "../../themePalette";
 import { stackedThreadToast, toastManager } from "../ui/toast";
 import { useThemeEditorStore } from "./themeEditorStore";
 
@@ -12,6 +17,14 @@ const ThemeEditorPanel = lazy(() =>
   import("./ThemeEditorPanel").then((module) => ({ default: module.ThemeEditorPanel })),
 );
 
+function useThemeDefinition(id: string | null | undefined) {
+  return useSyncExternalStore(
+    subscribeToCustomThemes,
+    () => (id ? (getThemeDefinition(id) ?? null) : null),
+    () => null,
+  );
+}
+
 /**
  * Renders the theme editor above the router. The editor paints its draft on
  * the live app, so it has to outlive the settings route: the point is to walk
@@ -21,6 +34,9 @@ export function ThemeEditorHost() {
   const session = useThemeEditorStore((store) => store.session);
   const closeThemeEditor = useThemeEditorStore((store) => store.closeThemeEditor);
   const { theme, setTheme, themeHalves, refreshTheme } = useTheme();
+  // A saved definition can change without its id changing between sessions.
+  const editingTheme = useThemeDefinition(session?.editingThemeId);
+  const seedTheme = useThemeDefinition(session?.seedThemeId);
 
   // The panel reports which path it actually took: a theme removed while its
   // editor is open resolves to null there, so the save becomes a create even
@@ -95,13 +111,6 @@ export function ThemeEditorHost() {
 
   if (!session) return null;
 
-  // Resolve on every render: an edit or import can change the stored
-  // definitions while a session is open.
-  const editingTheme = session.editingThemeId
-    ? (getThemeDefinition(session.editingThemeId) ?? null)
-    : null;
-  const seedTheme = session.seedThemeId ? (getThemeDefinition(session.seedThemeId) ?? null) : null;
-
   return (
     <Suspense fallback={null}>
       <ThemeEditorPanel

From ed2bdbb278c4fedf6ce79d4925908b759f7fd992 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 17:23:06 -0700
Subject: [PATCH 45/56] feat(desktop): import cookies from Safari (#7262)

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../src/electron/ElectronShell.test.ts        |  14 +
 apps/desktop/src/electron/ElectronShell.ts    |  29 +-
 apps/desktop/src/ipc/DesktopIpcHandlers.ts    |   2 +
 apps/desktop/src/ipc/channels.ts              |   1 +
 apps/desktop/src/ipc/methods/window.ts        |  11 +
 apps/desktop/src/preload.ts                   |   2 +
 .../preview/BrowserImport/BrowserImport.ts    |  50 +-
 .../BrowserImport/SafariCookies.test.ts       | 443 ++++++++++++++++++
 .../preview/BrowserImport/SafariCookies.ts    | 263 +++++++++++
 .../src/preview/BrowserImport/Sources.test.ts | 103 ++++
 .../src/preview/BrowserImport/Sources.ts      |  96 +++-
 apps/desktop/src/window/DesktopWindow.test.ts |   2 +
 .../settings/BrowserImportWizard.tsx          |  88 +++-
 .../IntegrationsSettings.logic.test.ts        |   1 +
 .../settings/IntegrationsSettings.tsx         |  15 +
 .../browserImportWizard.logic.test.ts         |  32 ++
 .../settings/browserImportWizard.logic.ts     |  21 +-
 apps/web/src/localApi.test.ts                 |   8 +
 apps/web/src/localApi.ts                      |  11 +
 docs/user/browser-import.md                   |   6 +
 packages/contracts/src/browserImport.ts       |   4 +
 packages/contracts/src/ipc.ts                 |  14 +
 22 files changed, 1189 insertions(+), 27 deletions(-)
 create mode 100644 apps/desktop/src/preview/BrowserImport/SafariCookies.test.ts
 create mode 100644 apps/desktop/src/preview/BrowserImport/SafariCookies.ts

diff --git a/apps/desktop/src/electron/ElectronShell.test.ts b/apps/desktop/src/electron/ElectronShell.test.ts
index 9ae6f502b000..17f3e06039b6 100644
--- a/apps/desktop/src/electron/ElectronShell.test.ts
+++ b/apps/desktop/src/electron/ElectronShell.test.ts
@@ -36,6 +36,20 @@ describe("ElectronShell", () => {
     }).pipe(Effect.provide(ElectronShell.layer)),
   );
 
+  it.effect("opens the Full Disk Access settings anchor", () =>
+    Effect.gen(function* () {
+      openExternalMock.mockResolvedValue(undefined);
+
+      const electronShell = yield* ElectronShell.ElectronShell;
+      const result = yield* electronShell.openSystemSettings("full-disk-access");
+
+      assert.equal(result, true);
+      assert.deepEqual(openExternalMock.mock.calls, [
+        ["x-apple.systempreferences:com.apple.settings.PrivacySecurity.extension?Privacy_AllFiles"],
+      ]);
+    }).pipe(Effect.provide(ElectronShell.layer)),
+  );
+
   it.effect("opens remote SSH editor URLs", () =>
     Effect.gen(function* () {
       openExternalMock.mockResolvedValue(undefined);
diff --git a/apps/desktop/src/electron/ElectronShell.ts b/apps/desktop/src/electron/ElectronShell.ts
index 2ed13bfebd0f..0ac4f8f9cc6a 100644
--- a/apps/desktop/src/electron/ElectronShell.ts
+++ b/apps/desktop/src/electron/ElectronShell.ts
@@ -1,4 +1,8 @@
-import { REMOTE_CAPABLE_EDITOR_IDS, remoteSchemeForEditor } from "@t3tools/contracts";
+import {
+  REMOTE_CAPABLE_EDITOR_IDS,
+  remoteSchemeForEditor,
+  type SystemSettingsPane,
+} from "@t3tools/contracts";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
@@ -6,6 +10,20 @@ import * as Option from "effect/Option";
 
 import * as Electron from "electron";
 
+/**
+ * Deep links to individual System Settings panes. These are app-fixed, not
+ * renderer-supplied, so they skip `parseSafeExternalUrl` — which exists to keep
+ * arbitrary link schemes from reaching the OS handler — and open through their
+ * own path below. The pane rather than the URL crosses the IPC boundary, so a
+ * renderer can only ask for one of these known destinations.
+ *
+ * Full Disk Access uses the post-Ventura `PrivacySecurity.extension` anchor.
+ */
+const SYSTEM_SETTINGS_URLS: Record<SystemSettingsPane, string> = {
+  "full-disk-access":
+    "x-apple.systempreferences:com.apple.settings.PrivacySecurity.extension?Privacy_AllFiles",
+};
+
 // Remote open-in-editor deep links (`vscode://vscode-remote/ssh-remote+…`)
 // must reach the OS handler; every other non-web scheme stays blocked.
 const SAFE_WEB_PROTOCOLS = new Set(["http:", "https:"]);
@@ -43,6 +61,8 @@ export class ElectronShell extends Context.Service<
   ElectronShell,
   {
     readonly openExternal: (rawUrl: unknown) => Effect.Effect<boolean>;
+    /** Opens a known System Settings pane by identifier, not by URL. */
+    readonly openSystemSettings: (pane: SystemSettingsPane) => Effect.Effect<boolean>;
     readonly copyText: (text: string) => Effect.Effect<void>;
   }
 >()("@t3tools/desktop/electron/ElectronShell") {}
@@ -59,6 +79,13 @@ export const make = ElectronShell.of({
           ),
         ),
     }),
+  openSystemSettings: (pane) =>
+    Effect.promise(() =>
+      Electron.shell.openExternal(SYSTEM_SETTINGS_URLS[pane]).then(
+        () => true,
+        () => false,
+      ),
+    ),
   copyText: (text) =>
     Effect.sync(() => {
       Electron.clipboard.writeText(text);
diff --git a/apps/desktop/src/ipc/DesktopIpcHandlers.ts b/apps/desktop/src/ipc/DesktopIpcHandlers.ts
index 2cdffbefb7ad..3e30083064af 100644
--- a/apps/desktop/src/ipc/DesktopIpcHandlers.ts
+++ b/apps/desktop/src/ipc/DesktopIpcHandlers.ts
@@ -38,6 +38,7 @@ import {
   getSystemLocale,
   getWindowFullscreenState,
   openExternal,
+  openSystemSettings,
   probeRemoteEditors,
   pickFolder,
   pickProjectFavicon,
@@ -94,6 +95,7 @@ export const installDesktopIpcHandlers = Effect.fn("desktop.ipc.installHandlers"
   yield* ipc.handle(setTheme);
   yield* ipc.handle(showContextMenu);
   yield* ipc.handle(openExternal);
+  yield* ipc.handle(openSystemSettings);
   yield* ipc.handle(probeRemoteEditors);
   yield* ipc.handle(getUpdateState);
   yield* ipc.handle(setUpdateChannel);
diff --git a/apps/desktop/src/ipc/channels.ts b/apps/desktop/src/ipc/channels.ts
index 81b50d165d24..5b2c815eaa42 100644
--- a/apps/desktop/src/ipc/channels.ts
+++ b/apps/desktop/src/ipc/channels.ts
@@ -4,6 +4,7 @@ export const PICK_THEME_FILES_CHANNEL = "desktop:pick-theme-files";
 export const SET_THEME_CHANNEL = "desktop:set-theme";
 export const CONTEXT_MENU_CHANNEL = "desktop:context-menu";
 export const OPEN_EXTERNAL_CHANNEL = "desktop:open-external";
+export const OPEN_SYSTEM_SETTINGS_CHANNEL = "desktop:open-system-settings";
 export const PROBE_REMOTE_EDITORS_CHANNEL = "desktop:probe-remote-editors";
 export const MENU_ACTION_CHANNEL = "desktop:menu-action";
 export const QUIT_SHORTCUT_CHANNEL = "desktop:quit-shortcut";
diff --git a/apps/desktop/src/ipc/methods/window.ts b/apps/desktop/src/ipc/methods/window.ts
index edae8394302c..61de1361a311 100644
--- a/apps/desktop/src/ipc/methods/window.ts
+++ b/apps/desktop/src/ipc/methods/window.ts
@@ -9,6 +9,7 @@ import {
   PickFolderOptionsSchema,
   PRIMARY_LOCAL_ENVIRONMENT_ID,
   REMOTE_CAPABLE_EDITOR_IDS,
+  SystemSettingsPaneSchema,
   type DesktopEnvironmentBootstrap,
   type PickedThemeFile,
 } from "@t3tools/contracts";
@@ -298,6 +299,16 @@ export const openExternal = DesktopIpc.makeIpcMethod({
   }),
 });
 
+export const openSystemSettings = DesktopIpc.makeIpcMethod({
+  channel: IpcChannels.OPEN_SYSTEM_SETTINGS_CHANNEL,
+  payload: SystemSettingsPaneSchema,
+  result: Schema.Boolean,
+  handler: Effect.fn("desktop.ipc.window.openSystemSettings")(function* (pane) {
+    const shell = yield* ElectronShell.ElectronShell;
+    return yield* shell.openSystemSettings(pane);
+  }),
+});
+
 export const probeRemoteEditors = DesktopIpc.makeIpcMethod({
   channel: IpcChannels.PROBE_REMOTE_EDITORS_CHANNEL,
   payload: Schema.Undefined,
diff --git a/apps/desktop/src/preload.ts b/apps/desktop/src/preload.ts
index 685a9b1204db..74001dd785d3 100644
--- a/apps/desktop/src/preload.ts
+++ b/apps/desktop/src/preload.ts
@@ -116,6 +116,8 @@ contextBridge.exposeInMainWorld("desktopBridge", {
       ...(position === undefined ? {} : { position }),
     }),
   openExternal: (url: string) => ipcRenderer.invoke(IpcChannels.OPEN_EXTERNAL_CHANNEL, url),
+  openSystemSettings: (pane: string) =>
+    ipcRenderer.invoke(IpcChannels.OPEN_SYSTEM_SETTINGS_CHANNEL, pane),
   probeRemoteEditors: () => ipcRenderer.invoke(IpcChannels.PROBE_REMOTE_EDITORS_CHANNEL, undefined),
   onMenuAction: (listener) => {
     const wrappedListener = (_event: Electron.IpcRendererEvent, action: unknown) => {
diff --git a/apps/desktop/src/preview/BrowserImport/BrowserImport.ts b/apps/desktop/src/preview/BrowserImport/BrowserImport.ts
index e92f2f05e05c..386b3ef6f813 100644
--- a/apps/desktop/src/preview/BrowserImport/BrowserImport.ts
+++ b/apps/desktop/src/preview/BrowserImport/BrowserImport.ts
@@ -27,6 +27,7 @@ import * as BrowserSession from "../BrowserSession.ts";
 import { ChromiumCookieReadError, readChromiumCookies } from "./ChromiumCookies.ts";
 import type { CookieReadResult } from "./CookieDatabase.ts";
 import { FirefoxCookieReadError, readFirefoxCookies } from "./FirefoxCookies.ts";
+import { readSafariCookies, safariAccessDenied, SafariCookieReadError } from "./SafariCookies.ts";
 import {
   BROWSER_IMPORT_SOURCES,
   resolveCookieDatabase,
@@ -92,6 +93,15 @@ const unavailableReason = Effect.fn("BrowserImport.unavailableReason")(function*
   if (!definition.platforms.includes(context.platform)) return "unsupportedPlatform";
   if (!(yield* isSourceInstalled(definition, context))) return "notInstalled";
   if (yield* isSourceRunning(definition, context)) return "browserRunning";
+  // Safari's jar is found by `stat`, which TCC permits without Full Disk
+  // Access — so a Safari that lists as ready may still refuse the read. Probe
+  // the grant here, so the wizard can open on the permission step and a
+  // post-grant recheck can tell granted from still-denied, rather than only
+  // discovering it by attempting the import.
+  if (definition.engine === "safari") {
+    const jar = yield* resolveCookieDatabase(definition, context, ".");
+    if (jar !== undefined && (yield* safariAccessDenied(jar))) return "needsFullDiskAccess";
+  }
   return undefined;
 });
 
@@ -254,25 +264,29 @@ export const make = Effect.gen(function* BrowserImportMake() {
     const userDataDirectory = definition.userDataDirectory(pathContext);
     const read: Effect.Effect<
       CookieReadResult,
-      ChromiumCookieReadError | FirefoxCookieReadError,
+      ChromiumCookieReadError | FirefoxCookieReadError | SafariCookieReadError,
       FileSystem.FileSystem | Path.Path | Scope.Scope | ChildProcessSpawner.ChildProcessSpawner
     > =
-      definition.engine === "firefox"
-        ? readFirefoxCookies(databasePath).pipe(
+      definition.engine === "safari"
+        ? readSafariCookies(databasePath).pipe(
             Effect.map((cookies) => ({ cookies, undecryptable: 0, undecryptableHosts: [] })),
           )
-        : readChromiumCookies({
-            cookieDatabasePath: databasePath,
-            keychainService: definition.keychainService,
-            keychainAccount: definition.keychainAccount,
-            linuxSecretApplication: definition.linuxSecretApplication,
-            ...(platform === "win32" && userDataDirectory !== undefined
-              ? {
-                  windowsLocalStatePath: pathContext.path.join(userDataDirectory, "Local State"),
-                }
-              : {}),
-            platform,
-          });
+        : definition.engine === "firefox"
+          ? readFirefoxCookies(databasePath).pipe(
+              Effect.map((cookies) => ({ cookies, undecryptable: 0, undecryptableHosts: [] })),
+            )
+          : readChromiumCookies({
+              cookieDatabasePath: databasePath,
+              keychainService: definition.keychainService,
+              keychainAccount: definition.keychainAccount,
+              linuxSecretApplication: definition.linuxSecretApplication,
+              ...(platform === "win32" && userDataDirectory !== undefined
+                ? {
+                    windowsLocalStatePath: pathContext.path.join(userDataDirectory, "Local State"),
+                  }
+                : {}),
+              platform,
+            });
 
     const result = yield* read.pipe(
       Effect.scoped,
@@ -289,6 +303,12 @@ export const make = Effect.gen(function* BrowserImportMake() {
           Effect.fail(
             new BrowserImportFailedError({ sourceId: definition.id, reason: "readFailed", cause }),
           ),
+        // Safari's reasons are already user-facing: a TCC refusal is the Full
+        // Disk Access prompt, anything else is a read failure.
+        SafariCookieReadError: (cause) =>
+          Effect.fail(
+            new BrowserImportFailedError({ sourceId: definition.id, reason: cause.reason, cause }),
+          ),
       }),
     );
 
diff --git a/apps/desktop/src/preview/BrowserImport/SafariCookies.test.ts b/apps/desktop/src/preview/BrowserImport/SafariCookies.test.ts
new file mode 100644
index 000000000000..f5d07f765943
--- /dev/null
+++ b/apps/desktop/src/preview/BrowserImport/SafariCookies.test.ts
@@ -0,0 +1,443 @@
+// @effect-diagnostics nodeBuiltinImport:off - Hand-builds Safari's binary jar
+// format byte by byte.
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as PlatformError from "effect/PlatformError";
+
+import {
+  isPermissionDenied,
+  parseBinaryCookies,
+  readSafariCookies,
+  safariAccessDenied,
+  SafariCookieReadError,
+} from "./SafariCookies.ts";
+
+const APPLE_EPOCH_OFFSET_SECONDS = 978_307_200;
+
+interface FixtureCookie {
+  readonly domain: string;
+  readonly name: string;
+  readonly path: string;
+  readonly value: string;
+  readonly flags: number;
+  /** Seconds since 2001-01-01, as Safari stores them. */
+  readonly expiry: number;
+}
+
+/** Encodes one cookie exactly as Safari lays it out. */
+function encodeCookie(cookie: FixtureCookie): Buffer {
+  const strings = [cookie.domain, cookie.name, cookie.path, cookie.value];
+  const headerSize = 56;
+  const offsets: number[] = [];
+  let cursor = headerSize;
+  for (const value of strings) {
+    offsets.push(cursor);
+    cursor += Buffer.byteLength(value) + 1;
+  }
+  const size = cursor;
+
+  const buffer = Buffer.alloc(size);
+  buffer.writeUInt32LE(size, 0);
+  buffer.writeUInt32LE(0, 4);
+  buffer.writeUInt32LE(cookie.flags, 8);
+  buffer.writeUInt32LE(0, 12);
+  buffer.writeUInt32LE(offsets[0]!, 16);
+  buffer.writeUInt32LE(offsets[1]!, 20);
+  buffer.writeUInt32LE(offsets[2]!, 24);
+  buffer.writeUInt32LE(offsets[3]!, 28);
+  buffer.writeUInt32LE(0, 32);
+  buffer.writeUInt32LE(0, 36);
+  buffer.writeDoubleLE(cookie.expiry, 40);
+  buffer.writeDoubleLE(0, 48);
+  strings.forEach((value, index) => {
+    buffer.write(value, offsets[index]!, "utf8");
+  });
+  return buffer;
+}
+
+/** Builds a single-page `Cookies.binarycookies` file. */
+function encodeBinaryCookies(cookies: ReadonlyArray<FixtureCookie>): Buffer {
+  const encoded = cookies.map(encodeCookie);
+  const headerSize = 12 + encoded.length * 4;
+  const offsets: number[] = [];
+  let cursor = headerSize;
+  for (const cookie of encoded) {
+    offsets.push(cursor);
+    cursor += cookie.length;
+  }
+
+  const page = Buffer.alloc(cursor);
+  page.writeUInt32BE(0x0000_0100, 0);
+  page.writeUInt32LE(encoded.length, 4);
+  offsets.forEach((offset, index) => page.writeUInt32LE(offset, 8 + index * 4));
+  encoded.forEach((cookie, index) => cookie.copy(page, offsets[index]!));
+
+  const header = Buffer.alloc(8 + 4);
+  header.write("cook", 0, "latin1");
+  header.writeUInt32BE(1, 4);
+  header.writeUInt32BE(page.length, 8);
+  return Buffer.concat([header, page]);
+}
+
+describe("parseBinaryCookies", () => {
+  it("reads Safari's format and rebases its 2001 epoch", () => {
+    const file = encodeBinaryCookies([
+      {
+        domain: ".apple.com",
+        name: "session",
+        path: "/",
+        value: "abc",
+        // secure | httpOnly
+        flags: 0x1 | 0x4,
+        expiry: 800_000_000,
+      },
+      {
+        domain: "example.test",
+        name: "plain",
+        path: "/app",
+        value: "v",
+        flags: 0,
+        expiry: 0,
+      },
+    ]);
+
+    expect(parseBinaryCookies(file)).toEqual([
+      {
+        url: "https://apple.com/",
+        name: "session",
+        value: "abc",
+        domain: ".apple.com",
+        path: "/",
+        secure: true,
+        httpOnly: true,
+        // Safari counts from 2001-01-01, Electron from 1970.
+        expirationDate: 800_000_000 + APPLE_EPOCH_OFFSET_SECONDS,
+        // The format predates SameSite; Lax is the safe modern default.
+        sameSite: "lax",
+      },
+      {
+        url: "http://example.test/app",
+        name: "plain",
+        value: "v",
+        // Host-only: no leading dot in the jar, so no `domain` for Electron,
+        // which would otherwise re-add the dot and widen it to subdomains.
+        domain: undefined,
+        path: "/app",
+        secure: false,
+        httpOnly: false,
+        expirationDate: undefined,
+        sameSite: "lax",
+      },
+    ]);
+  });
+
+  it("keeps __Host- cookies host-only so Electron accepts them", () => {
+    const file = encodeBinaryCookies([
+      { domain: "example.test", name: "__Host-id", path: "/", value: "v", flags: 0x1, expiry: 0 },
+    ]);
+
+    expect(parseBinaryCookies(file)[0]).toMatchObject({
+      url: "https://example.test/",
+      name: "__Host-id",
+      domain: undefined,
+    });
+  });
+
+  it("brackets IPv6 hosts in the cookie URL", () => {
+    const file = encodeBinaryCookies([
+      { domain: "::1", name: "local", path: "/", value: "v", flags: 0, expiry: 0 },
+    ]);
+
+    expect(parseBinaryCookies(file)[0]).toMatchObject({
+      url: "http://[::1]/",
+      domain: undefined,
+    });
+  });
+
+  it("reads cookies spread across multiple pages", () => {
+    // Safari pages its cookie file, and a single-page reader would silently
+    // return only the first slice.
+    const first = encodeBinaryCookies([
+      { domain: "a.test", name: "one", path: "/", value: "1", flags: 0, expiry: 1 },
+    ]);
+    const second = encodeBinaryCookies([
+      { domain: "b.test", name: "two", path: "/", value: "2", flags: 0, expiry: 1 },
+    ]);
+    // Splice the two single-page files into one two-page file.
+    const firstPage = first.subarray(12);
+    const secondPage = second.subarray(12);
+    const header = Buffer.alloc(16);
+    header.write("cook", 0, "latin1");
+    header.writeUInt32BE(2, 4);
+    header.writeUInt32BE(firstPage.length, 8);
+    header.writeUInt32BE(secondPage.length, 12);
+
+    const parsed = parseBinaryCookies(Buffer.concat([header, firstPage, secondPage]));
+
+    expect(parsed.map((cookie) => cookie.name)).toEqual(["one", "two"]);
+  });
+
+  it("rejects a page that runs past the end of the file", () => {
+    // `Buffer.subarray` clamps rather than throwing, so an overlong first page
+    // swallows the second one's bytes and advances the cursor past the end.
+    // Every cookie after the boundary then vanishes from a "successful" import.
+    const first = encodeBinaryCookies([
+      { domain: "a.test", name: "one", path: "/", value: "1", flags: 0, expiry: 1 },
+    ]);
+    const second = encodeBinaryCookies([
+      { domain: "b.test", name: "two", path: "/", value: "2", flags: 0, expiry: 1 },
+    ]);
+    const firstPage = first.subarray(12);
+    const secondPage = second.subarray(12);
+    const header = Buffer.alloc(16);
+    header.write("cook", 0, "latin1");
+    header.writeUInt32BE(2, 4);
+    // Declares more bytes for page one than the file holds in total.
+    header.writeUInt32BE(firstPage.length + secondPage.length + 32, 8);
+    header.writeUInt32BE(secondPage.length, 12);
+
+    expect(() => parseBinaryCookies(Buffer.concat([header, firstPage, secondPage]))).toThrow(
+      SafariCookieReadError,
+    );
+  });
+
+  it("rejects a record whose declared size runs past its page", () => {
+    const valid = encodeBinaryCookies([
+      { domain: "a.test", name: "n", path: "/", value: "v", expiry: 1_000, flags: 0 },
+    ]);
+    // The record's own length is what bounds its string offsets; an inflated
+    // one lets them read the following record's bytes as this cookie's value.
+    const pageStart = 8 + 4;
+    const recordStart = pageStart + valid.readUInt32LE(pageStart + 8);
+    const corrupt = Buffer.from(valid);
+    corrupt.writeUInt32LE(0xffff, recordStart);
+
+    expect(() => parseBinaryCookies(corrupt)).toThrow(SafariCookieReadError);
+  });
+
+  it("rejects records truncated inside the 56-byte header", () => {
+    const valid = encodeBinaryCookies([
+      { domain: "a.test", name: "n", path: "/", value: "v", expiry: 1_000, flags: 0 },
+    ]);
+    const pageStart = 8 + 4;
+    const recordStart = pageStart + valid.readUInt32LE(pageStart + 8);
+
+    for (let size = 48; size < 56; size += 1) {
+      const corrupt = Buffer.from(valid);
+      corrupt.writeUInt32LE(size, recordStart);
+      expect(() => parseBinaryCookies(corrupt), `record size ${size}`).toThrow(
+        SafariCookieReadError,
+      );
+    }
+  });
+
+  it("rejects record offsets that point into the page header or an earlier record", () => {
+    const valid = encodeBinaryCookies([
+      { domain: "a.test", name: "n", path: "/", value: "v", expiry: 1_000, flags: 0 },
+      { domain: "b.test", name: "m", path: "/", value: "w", expiry: 1_000, flags: 0 },
+    ]);
+    const pageStart = 8 + 4;
+    const firstRecord = valid.readUInt32LE(pageStart + 8);
+
+    // Pointing the second offset at the page's offset table would let those
+    // table bytes parse as a fabricated record.
+    const intoTable = Buffer.from(valid);
+    intoTable.writeUInt32LE(4, pageStart + 12);
+    expect(() => parseBinaryCookies(intoTable)).toThrow(SafariCookieReadError);
+
+    // Pointing it back at the first record makes the same bytes count twice.
+    const overlapping = Buffer.from(valid);
+    overlapping.writeUInt32LE(firstRecord, pageStart + 12);
+    expect(() => parseBinaryCookies(overlapping)).toThrow(SafariCookieReadError);
+
+    // And a well-formed two-record page still parses.
+    expect(parseBinaryCookies(valid)).toHaveLength(2);
+  });
+
+  it("rejects string offsets that point into the record header", () => {
+    const valid = encodeBinaryCookies([
+      { domain: "a.test", name: "n", path: "/", value: "v", expiry: 1_000, flags: 0 },
+    ]);
+    const pageStart = 8 + 4;
+    const recordStart = pageStart + valid.readUInt32LE(pageStart + 8);
+
+    for (const offsetField of [16, 20, 24, 28]) {
+      const corrupt = Buffer.from(valid);
+      corrupt.writeUInt32LE(55, recordStart + offsetField);
+      expect(() => parseBinaryCookies(corrupt), `offset field ${offsetField}`).toThrow(
+        SafariCookieReadError,
+      );
+    }
+  });
+
+  it("accepts the checksum and property-list trailer Safari writes", () => {
+    const file = encodeBinaryCookies([
+      { domain: "a.test", name: "c", path: "/", value: "v", flags: 0, expiry: 0 },
+    ]);
+    const checksum = Buffer.alloc(8);
+    const plist = Buffer.from("bplist00 stub");
+    const plistLength = Buffer.alloc(4);
+    plistLength.writeUInt32BE(plist.length, 0);
+
+    expect(parseBinaryCookies(Buffer.concat([file, checksum]))).toHaveLength(1);
+    expect(parseBinaryCookies(Buffer.concat([file, checksum, plistLength, plist]))).toHaveLength(1);
+  });
+
+  it("rejects a jar whose page table stops short of its contents", () => {
+    // A second, undeclared page after the first would be silently dropped —
+    // the cookies it holds vanish from the import with no error — so a file
+    // the header does not fully describe is refused instead.
+    const first = encodeBinaryCookies([
+      { domain: "a.test", name: "c", path: "/", value: "v", flags: 0, expiry: 0 },
+    ]);
+    const extraPage = encodeBinaryCookies([
+      { domain: "b.test", name: "d", path: "/", value: "w", flags: 0, expiry: 0 },
+    ]).subarray(12);
+
+    expect(() => parseBinaryCookies(Buffer.concat([first, extraPage]))).toThrow(
+      SafariCookieReadError,
+    );
+    // A trailer that claims a property list it doesn't contain is refused too.
+    const badLength = Buffer.alloc(4);
+    badLength.writeUInt32BE(99, 0);
+    expect(() =>
+      parseBinaryCookies(Buffer.concat([first, Buffer.alloc(8), badLength, Buffer.from("x")])),
+    ).toThrow(SafariCookieReadError);
+  });
+
+  it("rejects a file that is not binarycookies", () => {
+    expect(() => parseBinaryCookies(Buffer.from("not a cookie jar"))).toThrow(
+      SafariCookieReadError,
+    );
+  });
+});
+
+describe("readSafariCookies", () => {
+  it.effect("adds the cookie path and parser cause to malformed jar failures", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const directory = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3code-safari-" });
+      const jar = `${directory}/Cookies.binarycookies`;
+      yield* fileSystem.writeFileString(jar, "not a cookie jar");
+
+      const error = yield* readSafariCookies(jar).pipe(Effect.flip);
+
+      assert.equal(error.reason, "readFailed");
+      assert.equal(error.cookieDatabasePath, jar);
+      assert.instanceOf(error.cause, SafariCookieReadError);
+    }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
+  );
+
+  it.effect("reports a TCC denial as a permission the user can grant", () =>
+    Effect.gen(function* () {
+      // What Full Disk Access actually looks like: the file is there, the read
+      // is refused with EPERM. Effect tags that `Unknown`, not
+      // `PermissionDenied`, so the reader has to look at the errno. Reporting
+      // it as a generic failure would send the user looking for a missing
+      // browser instead of a checkbox.
+      const denied = PlatformError.systemError({
+        _tag: "Unknown",
+        module: "FileSystem",
+        method: "readFile",
+        pathOrDescriptor: "/protected/Cookies.binarycookies",
+        cause: Object.assign(new Error("operation not permitted"), { code: "EPERM" }),
+      });
+
+      const error = yield* readSafariCookies("/protected/Cookies.binarycookies").pipe(
+        Effect.flip,
+        Effect.provide(FileSystem.layerNoop({ readFile: () => Effect.fail(denied) })),
+      );
+
+      assert.equal(error.reason, "needsFullDiskAccess");
+    }),
+  );
+
+  it.effect("reports an ordinary permission failure as a plain read failure", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const directory = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3code-safari-" });
+      const jar = `${directory}/Cookies.binarycookies`;
+      yield* fileSystem.writeFile(jar, new Uint8Array([0x63, 0x6f, 0x6f, 0x6b]));
+      // A mode-bits refusal is EACCES: granting Full Disk Access cannot fix
+      // it, so it must not be routed to that grant.
+      yield* fileSystem.chmod(jar, 0o000);
+
+      const error = yield* readSafariCookies(jar).pipe(Effect.flip);
+
+      assert.equal(error.reason, "readFailed");
+    }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
+  );
+
+  it.effect("reports a missing jar as a plain read failure", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const directory = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3code-safari-" });
+
+      const error = yield* readSafariCookies(`${directory}/absent.binarycookies`).pipe(Effect.flip);
+
+      assert.equal(error.reason, "readFailed");
+    }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
+  );
+});
+
+describe("safariAccessDenied", () => {
+  const eperm = PlatformError.systemError({
+    _tag: "Unknown",
+    module: "FileSystem",
+    method: "open",
+    pathOrDescriptor: "/protected/Cookies.binarycookies",
+    cause: Object.assign(new Error("operation not permitted"), { code: "EPERM" }),
+  });
+  const denied = (error: PlatformError.PlatformError) =>
+    FileSystem.layerNoop({ open: () => Effect.fail(error) });
+
+  it.effect("reports TCC's EPERM as a missing Full Disk Access grant", () =>
+    Effect.gen(function* () {
+      // `stat` finds the jar without the grant, so only an open tells the
+      // listing whether the import would actually be allowed.
+      assert.isTrue(
+        yield* safariAccessDenied("/protected/Cookies.binarycookies").pipe(
+          Effect.provide(denied(eperm)),
+        ),
+      );
+    }),
+  );
+
+  it.effect("does not read a readable jar, or any other failure, as denied", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const directory = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3code-safari-" });
+      const jar = `${directory}/Cookies.binarycookies`;
+      yield* fileSystem.writeFile(jar, new Uint8Array([0x63, 0x6f, 0x6f, 0x6b]));
+      assert.isFalse(yield* safariAccessDenied(jar));
+      // Missing entirely is "not installed", not "denied".
+      assert.isFalse(yield* safariAccessDenied(`${directory}/absent.binarycookies`));
+    }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
+  );
+});
+
+describe("isPermissionDenied", () => {
+  // Shapes taken from a real `FileSystem.readFile` failure on macOS — verified
+  // against Safari's TCC-protected jar, whose denial is EPERM, tagged
+  // `Unknown` rather than `PermissionDenied`.
+  const platformError = (reasonTag: string, code: string): PlatformError.PlatformError =>
+    ({ _tag: "PlatformError", reason: { _tag: reasonTag, cause: { code } } }) as never;
+
+  it("treats a TCC EPERM denial as permission denied", () => {
+    // The regression: EPERM is tagged `Unknown`, so checking the tag alone
+    // reported Safari's Full Disk Access refusal as a generic read failure.
+    expect(isPermissionDenied(platformError("Unknown", "EPERM"))).toBe(true);
+  });
+
+  it("does not send an ordinary EACCES failure to the Full Disk Access grant", () => {
+    // A POSIX permission or ACL refusal cannot be fixed by granting Full Disk
+    // Access, so it stays a plain read failure; only TCC's EPERM routes there.
+    expect(isPermissionDenied(platformError("PermissionDenied", "EACCES"))).toBe(false);
+  });
+
+  it("does not treat an unrelated failure as permission denied", () => {
+    expect(isPermissionDenied(platformError("Unknown", "EIO"))).toBe(false);
+  });
+});
diff --git a/apps/desktop/src/preview/BrowserImport/SafariCookies.ts b/apps/desktop/src/preview/BrowserImport/SafariCookies.ts
new file mode 100644
index 000000000000..88aa856b83e9
--- /dev/null
+++ b/apps/desktop/src/preview/BrowserImport/SafariCookies.ts
@@ -0,0 +1,263 @@
+/**
+ * Safari cookie extraction.
+ *
+ * Safari does not encrypt its cookies; it stores them in a proprietary
+ * `Cookies.binarycookies` file inside its app container. The protection is
+ * TCC, not cryptography — the file lives under a path only apps with Full Disk
+ * Access may read, so the gate is a permission the user grants in System
+ * Settings rather than a key to obtain.
+ *
+ * The format, big-endian throughout except the page bodies:
+ *
+ *   magic "cook", u32 pageCount, u32 pageSize[pageCount], then each page:
+ *     u32 0x00000100, u32le cookieCount, u32le cookieOffset[cookieCount],
+ *     then each cookie:
+ *       u32le size, u32le unknown, u32le flags, u32le unknown,
+ *       u32le urlOffset, nameOffset, pathOffset, valueOffset,
+ *       u64 end-of-header, f64 expiry, f64 creation, then NUL-terminated
+ *       strings at the offsets above (relative to the cookie start).
+ *
+ * @module SafariCookies
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as PlatformError from "effect/PlatformError";
+import * as Schema from "effect/Schema";
+
+import { cookieScope, type ImportedCookie } from "./CookieDatabase.ts";
+
+/** Safari's timestamps count seconds from 2001-01-01, not the UNIX epoch. */
+const APPLE_EPOCH_OFFSET_SECONDS = 978_307_200;
+
+/** `u32 0x00000100`, `u32le cookieCount`, then one `u32le` offset per cookie. */
+const COOKIE_PAGE_HEADER_SIZE = 12;
+/** Through the `f64 creation` field; string bytes follow. */
+const COOKIE_RECORD_HEADER_SIZE = 56;
+
+const FLAG_SECURE = 0x1;
+const FLAG_HTTP_ONLY = 0x4;
+
+export const SafariCookieReadFailure = Schema.Literals(["needsFullDiskAccess", "readFailed"]);
+export type SafariCookieReadFailure = typeof SafariCookieReadFailure.Type;
+
+export class SafariCookieReadError extends Schema.TaggedErrorClass<SafariCookieReadError>()(
+  "SafariCookieReadError",
+  {
+    reason: SafariCookieReadFailure,
+    /**
+     * Which jar the read was for. The parser raises this before a path is in
+     * hand, so it is optional rather than required.
+     */
+    cookieDatabasePath: Schema.optional(Schema.String),
+    /** Kept for the log; never surfaced to the user. */
+    cause: Schema.optional(Schema.Defect()),
+  },
+) {
+  override get message(): string {
+    return this.cookieDatabasePath === undefined
+      ? `Could not read Safari cookies: ${this.reason}.`
+      : `Could not read Safari cookies at ${this.cookieDatabasePath}: ${this.reason}.`;
+  }
+}
+
+const isSafariCookieReadError = Schema.is(SafariCookieReadError);
+
+/** Reads a NUL-terminated ASCII string at an offset. */
+function readCString(buffer: Buffer, start: number): string {
+  const end = buffer.indexOf(0, start);
+  return buffer.toString("utf8", start, end === -1 ? buffer.length : end);
+}
+
+export function parseBinaryCookies(buffer: Buffer): ReadonlyArray<ImportedCookie> {
+  if (buffer.length < 8 || buffer.toString("latin1", 0, 4) !== "cook") {
+    throw new SafariCookieReadError({ reason: "readFailed" });
+  }
+
+  const pageCount = buffer.readUInt32BE(4);
+  // Every declared structure is bounds-checked against what the file actually
+  // contains, and a mismatch fails the read. `Buffer.subarray` clamps silently,
+  // so accepting a short page or an overlong record would return a cookie set
+  // that is quietly missing entries or carrying fields read out of the next
+  // record — a partial import the user has no way to notice.
+  if (8 + pageCount * 4 > buffer.length) {
+    throw new SafariCookieReadError({ reason: "readFailed" });
+  }
+  const pageSizes: number[] = [];
+  for (let index = 0; index < pageCount; index += 1) {
+    pageSizes.push(buffer.readUInt32BE(8 + index * 4));
+  }
+
+  const cookies: ImportedCookie[] = [];
+  let pageStart = 8 + pageCount * 4;
+
+  for (const pageSize of pageSizes) {
+    if (pageSize < COOKIE_PAGE_HEADER_SIZE || pageStart + pageSize > buffer.length) {
+      throw new SafariCookieReadError({ reason: "readFailed" });
+    }
+    const page = buffer.subarray(pageStart, pageStart + pageSize);
+    pageStart += pageSize;
+
+    // Page bodies switch to little-endian after the big-endian header.
+    const cookieCount = page.readUInt32LE(4);
+    const offsetTableEnd = COOKIE_PAGE_HEADER_SIZE + cookieCount * 4;
+    if (offsetTableEnd > page.length) {
+      throw new SafariCookieReadError({ reason: "readFailed" });
+    }
+    // Every record accepted so far, so a later offset cannot point back into
+    // one of them: the page header, the offset table, and earlier records are
+    // all bytes that would otherwise parse as a fabricated cookie.
+    const accepted: Array<readonly [start: number, end: number]> = [];
+    for (let index = 0; index < cookieCount; index += 1) {
+      const cookieStart = page.readUInt32LE(8 + index * 4);
+      if (cookieStart < offsetTableEnd || cookieStart + COOKIE_RECORD_HEADER_SIZE > page.length) {
+        throw new SafariCookieReadError({ reason: "readFailed" });
+      }
+      // Bounded by the record's own length so a string offset cannot run past
+      // it into the following record's bytes.
+      const recordSize = page.readUInt32LE(cookieStart);
+      const cookieEnd = cookieStart + recordSize;
+      if (
+        recordSize < COOKIE_RECORD_HEADER_SIZE ||
+        cookieEnd > page.length ||
+        accepted.some(([start, end]) => cookieStart < end && cookieEnd > start)
+      ) {
+        throw new SafariCookieReadError({ reason: "readFailed" });
+      }
+      accepted.push([cookieStart, cookieEnd]);
+      const cookie = page.subarray(cookieStart, cookieEnd);
+
+      const flags = cookie.readUInt32LE(8);
+      const urlOffset = cookie.readUInt32LE(16);
+      const nameOffset = cookie.readUInt32LE(20);
+      const pathOffset = cookie.readUInt32LE(24);
+      const valueOffset = cookie.readUInt32LE(28);
+      const expiry = cookie.readDoubleLE(40);
+
+      // Offsets are relative to the record; one pointing outside it would
+      // otherwise read a neighbouring cookie's bytes as this one's value.
+      if (
+        [urlOffset, nameOffset, pathOffset, valueOffset].some(
+          (offset) => offset < COOKIE_RECORD_HEADER_SIZE || offset >= cookie.length,
+        )
+      ) {
+        throw new SafariCookieReadError({ reason: "readFailed" });
+      }
+      const domain = readCString(cookie, urlOffset);
+      const name = readCString(cookie, nameOffset);
+      const path = readCString(cookie, pathOffset);
+      const value = readCString(cookie, valueOffset);
+      if (domain === "" || name === "") continue;
+
+      const secure = (flags & FLAG_SECURE) !== 0;
+      const expirationDate =
+        expiry > 0 ? Math.floor(expiry) + APPLE_EPOCH_OFFSET_SECONDS : undefined;
+
+      cookies.push({
+        // Safari marks domain cookies with a leading dot like the other
+        // engines, so the shared scope rule applies: host-only cookies keep
+        // `domain` undefined, or Electron widens them to every subdomain.
+        ...cookieScope(domain, path || "/", secure),
+        name,
+        value,
+        path: path || "/",
+        secure,
+        httpOnly: (flags & FLAG_HTTP_ONLY) !== 0,
+        expirationDate,
+        // Bits 3–5 of the flags carry something SameSite-shaped, but no public
+        // description of them agrees and real jars do not match any of them
+        // cleanly. Lax is the modern browser default; claiming "none" would
+        // widen every imported cookie's scope.
+        sameSite: "lax",
+      });
+    }
+  }
+
+  // Safari writes an 8-byte checksum after the pages, then an optional
+  // length-prefixed property list. Anything else past the declared pages —
+  // in particular whole extra pages — means the page table does not describe
+  // the file, and a jar the header lies about is refused rather than
+  // imported with cookies silently missing.
+  const trailer = buffer.length - pageStart;
+  // Legal shapes: nothing, the 8-byte checksum alone, or checksum + u32
+  // length + exactly that many property-list bytes.
+  const validTrailer =
+    trailer === 0 ||
+    trailer === 8 ||
+    (trailer >= 12 && trailer === 8 + 4 + buffer.readUInt32BE(pageStart + 8));
+  if (!validTrailer) {
+    throw new SafariCookieReadError({ reason: "readFailed" });
+  }
+
+  return cookies;
+}
+
+/**
+ * Whether a filesystem error is the OS refusing access.
+ *
+ * A TCC denial arrives as EPERM, which Effect tags `Unknown` rather than
+ * `PermissionDenied` (reserved for EACCES), so the underlying errno is checked
+ * too — otherwise a Full Disk Access refusal is reported as a generic read
+ * failure and the user is never told what to grant.
+ */
+export const isPermissionDenied = (error: PlatformError.PlatformError): boolean => {
+  // TCC denies with EPERM, which Effect tags `Unknown` rather than
+  // `PermissionDenied` — so the errno is what identifies it. EACCES (and the
+  // `PermissionDenied` tag it maps to) is an ordinary POSIX permission or
+  // ACL failure that granting Full Disk Access cannot fix, so it stays a plain
+  // read failure rather than sending the user to a grant that won't help.
+  const code = (error.reason as { cause?: { code?: unknown } }).cause?.code;
+  return code === "EPERM";
+};
+
+/**
+ * Whether reading the jar is refused by TCC. `stat` succeeds on the jar
+ * inside Safari's container even without Full Disk Access — that is what lets
+ * the listing find it — so presence alone cannot tell granted from denied.
+ * Opening it for read is what TCC gates: EPERM means the grant is missing.
+ * Anything else (including a missing jar) is not a permission answer.
+ */
+export const safariAccessDenied = Effect.fnUntraced(function* (cookiePath: string) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  return yield* fileSystem.open(cookiePath, { flag: "r" }).pipe(
+    Effect.as(false),
+    Effect.catch((cause) => Effect.succeed(isPermissionDenied(cause))),
+    Effect.scoped,
+  );
+});
+
+export const readSafariCookies = Effect.fn("SafariCookies.readSafariCookies")(function* (
+  cookiePath: string,
+) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const contents = yield* fileSystem.readFile(cookiePath).pipe(
+    Effect.mapError((cause) => {
+      // TCC denies the read even though the file exists — a permission the user
+      // grants in System Settings rather than a missing browser. macOS never
+      // prompts for Full Disk Access, so there is no dialog to wait on; the
+      // read just fails, and it fails with EPERM, which Effect surfaces as an
+      // `Unknown` system error rather than `PermissionDenied` (that is EACCES).
+      return new SafariCookieReadError({
+        reason: isPermissionDenied(cause) ? "needsFullDiskAccess" : "readFailed",
+        cookieDatabasePath: cookiePath,
+        cause,
+      });
+    }),
+  );
+  // The parser throws on a malformed jar; catch it here so callers see a typed
+  // failure rather than a defect.
+  return yield* Effect.try({
+    try: () => parseBinaryCookies(Buffer.from(contents)),
+    catch: (cause) =>
+      isSafariCookieReadError(cause)
+        ? new SafariCookieReadError({
+            reason: cause.reason,
+            cookieDatabasePath: cookiePath,
+            cause,
+          })
+        : new SafariCookieReadError({
+            reason: "readFailed",
+            cookieDatabasePath: cookiePath,
+            cause,
+          }),
+  });
+});
diff --git a/apps/desktop/src/preview/BrowserImport/Sources.test.ts b/apps/desktop/src/preview/BrowserImport/Sources.test.ts
index a83290448a4a..a867f78497b4 100644
--- a/apps/desktop/src/preview/BrowserImport/Sources.test.ts
+++ b/apps/desktop/src/preview/BrowserImport/Sources.test.ts
@@ -1093,3 +1093,106 @@ describe("listSourceProfiles hardening", () => {
     ),
   );
 });
+
+describe("Safari profiles", () => {
+  const safari = BROWSER_IMPORT_SOURCES.find((source) => source.id === "safari")!;
+  const workUuid = "C561D071-67AD-4537-866F-54F65FB8E8DD";
+  const otherUuid = "2875EB19-B938-4E38-BE92-5AE97C256BDD";
+
+  const fixture = Effect.fnUntraced(function* () {
+    const context = yield* withSourceHome();
+    const fileSystem = yield* FileSystem.FileSystem;
+    const root = safari.userDataDirectory(context)!;
+    const library = context.path.dirname(root);
+    yield* fileSystem.makeDirectory(root, { recursive: true });
+    yield* fileSystem.writeFileString(context.path.join(root, "Cookies.binarycookies"), "default");
+    const store = (uuid: string) =>
+      context.path.join(library, "WebKit", "WebsiteDataStore", uuid.toLowerCase(), "Cookies");
+    for (const uuid of [workUuid, otherUuid]) {
+      yield* fileSystem.makeDirectory(store(uuid), { recursive: true });
+      yield* fileSystem.writeFileString(
+        context.path.join(store(uuid), "Cookies.binarycookies"),
+        uuid,
+      );
+    }
+    yield* fileSystem.makeDirectory(context.path.join(library, "Safari"), { recursive: true });
+    const metadata = context.path.join(library, "Safari", "SafariTabs.db");
+    return { context, root, store, metadata };
+  });
+
+  it.effect("discovers named profiles and resolves only the selected profile's cookies", () =>
+    run(
+      Effect.gen(function* () {
+        const { context, root, store, metadata } = yield* fixture();
+        yield* Effect.sync(() => {
+          const database = new NodeSqlite.DatabaseSync(metadata);
+          try {
+            database.exec(`CREATE TABLE bookmarks (
+            title TEXT, external_uuid TEXT, parent INTEGER DEFAULT 0,
+            type INTEGER DEFAULT 1, subtype INTEGER DEFAULT 2,
+            deleted INTEGER DEFAULT 0, order_index INTEGER DEFAULT 0
+          )`);
+            const insert = database.prepare(
+              "INSERT INTO bookmarks (title, external_uuid, deleted) VALUES (?, ?, ?)",
+            );
+            insert.run("", "DefaultProfile", 0);
+            insert.run("Ping", workUuid, 0);
+            insert.run("Deleted", otherUuid, 1);
+            insert.run("Unsafe", "../../outside", 0);
+            database.exec(
+              "INSERT INTO bookmarks (title, external_uuid, subtype) VALUES ('Tab group', 'group', 1)",
+            );
+          } finally {
+            database.close();
+          }
+        });
+        const profiles = yield* listSourceProfiles(safari, context);
+        assert.deepEqual(profiles, [
+          { directory: ".", name: "Personal" },
+          { directory: store(workUuid), name: "Ping" },
+        ]);
+        assert.strictEqual(
+          yield* resolveCookieDatabase(safari, context, "."),
+          context.path.join(root, "Cookies.binarycookies"),
+        );
+        const selected = yield* resolveCookieDatabase(safari, context, profiles[1]!.directory);
+        assert.strictEqual(selected, context.path.join(store(workUuid), "Cookies.binarycookies"));
+        const fileSystem = yield* FileSystem.FileSystem;
+        assert.strictEqual(yield* fileSystem.readFileString(selected!), workUuid);
+        yield* fileSystem.remove(selected!);
+        assert.isUndefined(yield* resolveCookieDatabase(safari, context, profiles[1]!.directory));
+        assert.deepEqual(yield* listSourceProfiles(safari, context), profiles);
+      }),
+    ),
+  );
+
+  for (const metadataState of ["missing", "corrupt"] as const) {
+    it.effect(`recovers separate cookie stores when metadata is ${metadataState}`, () =>
+      run(
+        Effect.gen(function* () {
+          const { context, store, metadata } = yield* fixture();
+          const fileSystem = yield* FileSystem.FileSystem;
+          if (metadataState === "corrupt") yield* fileSystem.writeFileString(metadata, "invalid");
+          yield* fileSystem.remove(context.path.join(store(otherUuid), "Cookies.binarycookies"));
+          assert.deepEqual(yield* listSourceProfiles(safari, context), [
+            { directory: ".", name: "Safari" },
+            { directory: store(workUuid), name: workUuid.toLowerCase() },
+          ]);
+          assert.isTrue(yield* isSourceInstalled(safari, context));
+        }),
+      ),
+    );
+  }
+
+  it.effect("keeps Safari without profiles available", () =>
+    run(
+      Effect.gen(function* () {
+        const context = yield* withSourceHome();
+        assert.deepEqual(yield* listSourceProfiles(safari, context), [
+          { directory: ".", name: "Safari" },
+        ]);
+        assert.isFalse(yield* isSourceInstalled(safari, context));
+      }),
+    ),
+  );
+});
diff --git a/apps/desktop/src/preview/BrowserImport/Sources.ts b/apps/desktop/src/preview/BrowserImport/Sources.ts
index 702933a432b3..6075f0ad56a3 100644
--- a/apps/desktop/src/preview/BrowserImport/Sources.ts
+++ b/apps/desktop/src/preview/BrowserImport/Sources.ts
@@ -1,10 +1,11 @@
 /**
  * Importable browser sources.
  *
- * Two engines are modelled. Chromium-family browsers keep cookies in an
+ * Chromium-family browsers keep cookies in an
  * encrypted SQLite database whose key lives in an OS credential store; Firefox
  * keeps them in plain SQLite with no key at all, so it needs no keychain and
- * works the same on every platform.
+ * works the same on every platform. Safari uses binary cookie files, with
+ * separate WebKit data stores for named profiles.
  *
  * Each entry pins its own paths and credential-store coordinates rather than
  * deriving them, because the forks do not agree. macOS uses service/account
@@ -31,7 +32,7 @@ import * as Stream from "effect/Stream";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 
-export type BrowserImportEngine = "chromium" | "firefox";
+export type BrowserImportEngine = "chromium" | "firefox" | "safari";
 
 /**
  * Directory roots a definition builds its paths from. Passed in rather than
@@ -177,6 +178,26 @@ export const BROWSER_IMPORT_SOURCES: ReadonlyArray<BrowserImportSourceDefinition
     // Helium retains Chromium's libsecret application name on Linux.
     linuxSecretApplication: "chromium",
   }),
+  {
+    // The default jar lives here; named profiles use WebKit data stores
+    // alongside this directory inside the same app container.
+    id: "safari",
+    name: "Safari",
+    engine: "safari",
+    platforms: ["darwin"],
+    userDataDirectory: (context) =>
+      context.platform === "darwin"
+        ? context.path.join(
+            context.home,
+            "Library",
+            "Containers",
+            "com.apple.Safari",
+            "Data",
+            "Library",
+            "Cookies",
+          )
+        : undefined,
+  },
   {
     id: "firefox",
     name: "Firefox",
@@ -220,6 +241,9 @@ export const cookieDatabaseCandidatePaths = (
   if (definition.engine === "firefox") {
     return [context.path.join(profilePath, "cookies.sqlite")];
   }
+  if (definition.engine === "safari") {
+    return [context.path.join(profilePath, "Cookies.binarycookies")];
+  }
   // Chromium: pre-96 uses `Cookies`, 96+ use `Network/Cookies`. An upgrade
   // leaves the legacy file behind, so prefer the current one and fall back.
   return [
@@ -386,6 +410,64 @@ const withCookieCounts = (
     ),
   );
 
+const SafariProfileRows = Schema.Array(
+  Schema.Struct({ title: Schema.NullOr(Schema.String), external_uuid: Schema.String }),
+);
+const decodeSafariProfiles = Schema.decodeUnknownEffect(SafariProfileRows);
+const isSafariProfileUuid = (value: string) =>
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
+
+const listSafariProfiles = Effect.fnUntraced(function* (
+  context: BrowserImportPathContext,
+  root: string,
+) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const library = context.path.dirname(root);
+  const metadata = context.path.join(library, "Safari", "SafariTabs.db");
+  const declared = yield* Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    return yield* decodeSafariProfiles(
+      yield* sql`
+      select title, external_uuid from bookmarks
+      where parent = 0 and type = 1 and subtype = 2 and deleted = 0
+      order by order_index
+    `,
+    );
+  }).pipe(
+    Effect.provide(NodeSqliteClient.layer({ filename: metadata, readonly: true })),
+    Effect.orElseSucceed(() => []),
+  );
+  const defaultProfile = declared.find((profile) => profile.external_uuid === "DefaultProfile");
+  const profiles: Array<BrowserImportSourceProfile> = [
+    {
+      directory: ".",
+      name: defaultProfile ? defaultProfile.title?.trim() || "Personal" : "Safari",
+    },
+  ];
+  const stores = context.path.join(library, "WebKit", "WebsiteDataStore");
+  const profileDirectory = (uuid: string) =>
+    context.path.join(stores, uuid.toLowerCase(), "Cookies");
+  for (const profile of declared) {
+    if (!isSafariProfileUuid(profile.external_uuid)) continue;
+    profiles.push({
+      directory: profileDirectory(profile.external_uuid),
+      name: profile.title?.trim() || profile.external_uuid,
+    });
+  }
+  // If Safari's metadata is unavailable, recover stores that have cookies.
+  // With readable metadata, avoid resurrecting deleted profiles left on disk.
+  if (declared.length === 0) {
+    const entries = yield* fileSystem.readDirectory(stores).pipe(Effect.orElseSucceed(() => []));
+    for (const entry of entries.filter(isSafariProfileUuid).sort()) {
+      const directory = context.path.join(stores, entry, "Cookies");
+      if (yield* databaseFileExists(context.path.join(directory, "Cookies.binarycookies"))) {
+        profiles.push({ directory, name: entry });
+      }
+    }
+  }
+  return profiles;
+});
+
 /**
  * Profiles the source browser knows about.
  *
@@ -403,6 +485,10 @@ const listSourceProfilesInDirectory = Effect.fnUntraced(function* (
   const root = definition.userDataDirectory(context);
   if (root === undefined) return [];
 
+  if (definition.engine === "safari") {
+    return yield* listSafariProfiles(context, root);
+  }
+
   if (definition.engine === "firefox") {
     const declared = yield* fileSystem.readFileString(context.path.join(root, "profiles.ini")).pipe(
       Effect.map((ini) => parseFirefoxProfiles(ini, context.path, root)),
@@ -773,11 +859,15 @@ export const isSourceRunning = Effect.fn("BrowserImportSources.isSourceRunning")
   const root = definition.userDataDirectory(context);
   if (root === undefined) return false;
   // Probe the source's own lock state rather than scanning the process table.
+  // Safari keeps no lock and writes its jar atomically, so a running instance
+  // is not a hazard there.
+  //
   // Chromium exposes its lock through the cookie jar on Windows and through a
   // user-data SingletonLock on POSIX. Firefox keeps its locks inside each
   // profile under three names across platforms (`lock` on macOS and Linux,
   // `.parentlock` beside it, `parent.lock` on Windows). Looking for Firefox's
   // at the root finds nothing and reports a running browser as importable.
+  if (definition.engine === "safari") return false;
   if (definition.engine !== "firefox") {
     if (context.platform === "win32") {
       return yield* windowsChromiumCookiesAreHeld(definition, context);
diff --git a/apps/desktop/src/window/DesktopWindow.test.ts b/apps/desktop/src/window/DesktopWindow.test.ts
index abf6f220eca4..bdd03865c7bf 100644
--- a/apps/desktop/src/window/DesktopWindow.test.ts
+++ b/apps/desktop/src/window/DesktopWindow.test.ts
@@ -280,6 +280,7 @@ function makeTestLayer(input: {
               input.openedExternalUrls?.push(url);
               return true;
             }),
+          openSystemSettings: () => Effect.succeed(true),
           copyText: () => Effect.void,
         } satisfies ElectronShell.ElectronShell["Service"]),
         electronThemeLayer,
@@ -380,6 +381,7 @@ const makeSplashScenario = (createOutcomes: readonly (Electron.BrowserWindow | n
           electronMenuLayer,
           Layer.succeed(ElectronShell.ElectronShell, {
             openExternal: () => Effect.succeed(true),
+            openSystemSettings: () => Effect.succeed(true),
             copyText: () => Effect.void,
           } satisfies ElectronShell.ElectronShell["Service"]),
           electronThemeLayer,
diff --git a/apps/web/src/components/settings/BrowserImportWizard.tsx b/apps/web/src/components/settings/BrowserImportWizard.tsx
index a18cb9173ff6..a02bb5dab24e 100644
--- a/apps/web/src/components/settings/BrowserImportWizard.tsx
+++ b/apps/web/src/components/settings/BrowserImportWizard.tsx
@@ -23,6 +23,7 @@ import {
   canCloseWizard,
   isRetryableReason,
   formatSkippedDomains,
+  fullDiskAccessRecheckStep,
   outcomeToStep,
   refreshedSourceProfileDirectory,
   refreshedSourceStep,
@@ -55,6 +56,8 @@ interface BrowserImportWizardProps {
   }) => Promise<ImportOutcome>;
   /** Re-checks the source's availability after the user quits the browser. */
   readonly onRefreshSource: () => Promise<BrowserImportSource | undefined>;
+  /** Opens the OS setting that grants access to a protected cookie store. */
+  readonly onOpenFullDiskAccessSettings: () => void;
   readonly onClose: () => void;
 }
 
@@ -72,6 +75,7 @@ export function BrowserImportWizard({
   canCreateProfile,
   onImport,
   onRefreshSource,
+  onOpenFullDiskAccessSettings,
   onClose,
 }: BrowserImportWizardProps) {
   const [source, setSource] = useState(initialSource);
@@ -111,8 +115,13 @@ export function BrowserImportWizard({
       });
   };
 
-  const recheckAfterQuit = () => {
-    setStep({ step: "checking" });
+  // Re-lists the source after the user did something outside the app (quit the
+  // browser, granted access) and routes to wherever the refreshed source says.
+  const recheckSource = (
+    check: "browser" | "fullDiskAccess",
+    nextStep: (refreshed: BrowserImportSource | undefined) => WizardStep,
+  ) => {
+    setStep({ step: "checking", check });
     void onRefreshSource()
       .then((refreshed) => {
         if (refreshed) {
@@ -121,20 +130,30 @@ export function BrowserImportWizard({
             refreshedSourceProfileDirectory(current, refreshed),
           );
         }
-        setStep(refreshedSourceStep(refreshed));
+        setStep(nextStep(refreshed));
       })
       .catch(() => setStep({ step: "blocked", reason: "readFailed" }));
   };
+  const recheckAfterQuit = () => recheckSource("browser", refreshedSourceStep);
+  const recheckFullDiskAccess = () => recheckSource("fullDiskAccess", fullDiskAccessRecheckStep);
 
   return (
     <Dialog open onOpenChange={(open) => (open || !canCloseWizard(step) ? undefined : onClose())}>
       <DialogPopup className="max-w-lg" showCloseButton={canCloseWizard(step)}>
         {step.step === "quit" ? (
           <QuitStep source={source} onCancel={onClose} onRechecked={recheckAfterQuit} />
+        ) : step.step === "fullDiskAccess" ? (
+          <FullDiskAccessStep
+            source={source}
+            onCancel={onClose}
+            onOpenSettings={onOpenFullDiskAccessSettings}
+            onGranted={step.resume === "import" ? runImport : recheckFullDiskAccess}
+            stillRequired={step.checked === true}
+          />
         ) : step.step === "importing" ? (
           <ImportingStep />
         ) : step.step === "checking" ? (
-          <CheckingStep sourceName={source.name} />
+          <CheckingStep sourceName={source.name} check={step.check} />
         ) : step.step === "done" ? (
           <DoneStep
             {...step}
@@ -223,6 +242,49 @@ type ConfigureStepProps = {
   readonly onImport: () => void;
 };
 
+function FullDiskAccessStep({
+  source,
+  onCancel,
+  onOpenSettings,
+  onGranted,
+  stillRequired,
+}: {
+  readonly source: BrowserImportSource;
+  readonly onCancel: () => void;
+  readonly onOpenSettings: () => void;
+  readonly onGranted: () => void;
+  readonly stillRequired: boolean;
+}) {
+  return (
+    <>
+      <DialogHeader>
+        <DialogTitle>Let T3 Code read {source.name}&rsquo;s cookies</DialogTitle>
+        <DialogDescription>
+          To import cookies from {source.name}, T3 Code needs Full Disk Access. Turn it on in System
+          Settings, then come back to finish the import — you can revoke it again once the import is
+          done.
+        </DialogDescription>
+      </DialogHeader>
+      {stillRequired ? (
+        <DialogPanel>
+          <p role="status" className="text-sm text-muted-foreground">
+            Full Disk Access is still required. If you just turned it on, quit and reopen T3 Code,
+            then try again.
+          </p>
+        </DialogPanel>
+      ) : null}
+      <DialogFooter>
+        <Button variant="outline" onClick={onCancel}>
+          Cancel
+        </Button>
+        <Button variant="outline" onClick={onOpenSettings}>
+          Open System Settings
+        </Button>
+        <Button onClick={onGranted}>I&rsquo;ve turned it on</Button>
+      </DialogFooter>
+    </>
+  );
+}
 function ConfigureStep({
   source,
   destinationEnvironmentName,
@@ -382,16 +444,28 @@ function ImportingStep() {
   );
 }
 
-function CheckingStep({ sourceName }: { readonly sourceName: string }) {
+function CheckingStep({
+  sourceName,
+  check,
+}: {
+  readonly sourceName: string;
+  readonly check: "browser" | "fullDiskAccess";
+}) {
   return (
     <>
       <DialogHeader>
         <DialogTitle>Checking {sourceName}</DialogTitle>
-        <DialogDescription>Checking whether the browser has closed.</DialogDescription>
+        <DialogDescription>
+          {check === "fullDiskAccess"
+            ? "Checking Full Disk Access."
+            : "Checking whether the browser has closed."}
+        </DialogDescription>
       </DialogHeader>
       <DialogPanel className="flex items-center gap-3 py-6">
         <Spinner className="size-4 text-muted-foreground" />
-        <span className="text-sm text-muted-foreground">Checking…</span>
+        <span className="text-sm text-muted-foreground">
+          {check === "fullDiskAccess" ? "Checking access…" : "Checking…"}
+        </span>
       </DialogPanel>
     </>
   );
diff --git a/apps/web/src/components/settings/IntegrationsSettings.logic.test.ts b/apps/web/src/components/settings/IntegrationsSettings.logic.test.ts
index 1c839f0cfdf8..c6d091b59e39 100644
--- a/apps/web/src/components/settings/IntegrationsSettings.logic.test.ts
+++ b/apps/web/src/components/settings/IntegrationsSettings.logic.test.ts
@@ -85,6 +85,7 @@ const failure = (reason: string) => ({
 
 describe("importFailureReason", () => {
   it("recovers the reason token from the flattened message", () => {
+    expect(importFailureReason(failure("needsFullDiskAccess"))).toBe("needsFullDiskAccess");
     expect(importFailureReason(failure("browserRunning"))).toBe("browserRunning");
     expect(importFailureReason(failure("readFailed"))).toBe("readFailed");
     expect(importFailureReason(failure("keychainUnavailable"))).toBe("keychainUnavailable");
diff --git a/apps/web/src/components/settings/IntegrationsSettings.tsx b/apps/web/src/components/settings/IntegrationsSettings.tsx
index 5b1d9ba5e21e..a3e96107b29c 100644
--- a/apps/web/src/components/settings/IntegrationsSettings.tsx
+++ b/apps/web/src/components/settings/IntegrationsSettings.tsx
@@ -55,6 +55,8 @@ import {
   MenuSeparator,
   MenuTrigger,
 } from "../ui/menu";
+import { readLocalApi } from "~/localApi";
+
 import { toastManager } from "../ui/toast";
 import {
   AlertDialog,
@@ -1168,6 +1170,19 @@ function BrowserProfilesSetting({ disabled }: { readonly disabled: boolean }) {
             runWizardImport(importSession.source, importSession.environmentId, input)
           }
           onRefreshSource={() => refreshImportSource(importSession.source.id)}
+          onOpenFullDiskAccessSettings={() => {
+            // Rejects outside the desktop shell (and on shells that predate the
+            // method), so the one toast covers every way the link can fail.
+            void readLocalApi()
+              ?.shell.openSystemSettings("full-disk-access")
+              .catch(() => {
+                toastManager.add({
+                  type: "error",
+                  title: "Could not open System Settings",
+                  description: "Open Privacy & Security → Full Disk Access manually.",
+                });
+              });
+          }}
           onClose={() => setImportSession(null)}
         />
       ) : null}
diff --git a/apps/web/src/components/settings/browserImportWizard.logic.test.ts b/apps/web/src/components/settings/browserImportWizard.logic.test.ts
index 64bd94f635c4..3df4a95d6c33 100644
--- a/apps/web/src/components/settings/browserImportWizard.logic.test.ts
+++ b/apps/web/src/components/settings/browserImportWizard.logic.test.ts
@@ -7,6 +7,7 @@ import {
   initialTargetSelection,
   isRetryableReason,
   formatSkippedDomains,
+  fullDiskAccessRecheckStep,
   outcomeToStep,
   refreshedSourceProfileDirectory,
   refreshedSourceStep,
@@ -51,6 +52,15 @@ describe("initialWizardStep", () => {
     expect(initialWizardStep(source())).toEqual({ step: "configure" });
   });
 
+  it("asks for Full Disk Access before choosing an import target", () => {
+    expect(initialWizardStep(source({ profiles: [], unavailable: "needsFullDiskAccess" }))).toEqual(
+      {
+        step: "fullDiskAccess",
+        resume: "configure",
+      },
+    );
+  });
+
   it("blocks on a reason nothing local can fix", () => {
     expect(initialWizardStep(source({ unavailable: "unsupportedPlatform" }))).toEqual({
       step: "blocked",
@@ -103,6 +113,14 @@ describe("outcomeToStep", () => {
     expect(outcomeToStep({ kind: "blocked", reason: "browserRunning" })).toEqual({ step: "quit" });
   });
 
+  it("routes a Full Disk Access refusal to its own screen", () => {
+    expect(outcomeToStep({ kind: "blocked", reason: "needsFullDiskAccess" })).toEqual({
+      step: "fullDiskAccess",
+      resume: "import",
+      checked: true,
+    });
+  });
+
   it("surfaces every other failure on the blocked screen", () => {
     expect(outcomeToStep({ kind: "blocked", reason: "readFailed" })).toEqual({
       step: "blocked",
@@ -134,6 +152,20 @@ describe("refreshedSourceStep", () => {
   });
 });
 
+describe("fullDiskAccessRecheckStep", () => {
+  it("marks a still-denied access check for visible feedback", () => {
+    expect(fullDiskAccessRecheckStep(source({ unavailable: "needsFullDiskAccess" }))).toEqual({
+      step: "fullDiskAccess",
+      resume: "configure",
+      checked: true,
+    });
+  });
+
+  it("moves on once access reveals the source profiles", () => {
+    expect(fullDiskAccessRecheckStep(source())).toEqual({ step: "configure" });
+  });
+});
+
 describe("refreshedSourceProfileDirectory", () => {
   const refreshed = source({
     profiles: [
diff --git a/apps/web/src/components/settings/browserImportWizard.logic.ts b/apps/web/src/components/settings/browserImportWizard.logic.ts
index 5479e307b13a..3b71345b9d5a 100644
--- a/apps/web/src/components/settings/browserImportWizard.logic.ts
+++ b/apps/web/src/components/settings/browserImportWizard.logic.ts
@@ -58,8 +58,13 @@ export type ImportOutcome =
  */
 export type WizardStep =
   | { readonly step: "quit" }
+  | {
+      readonly step: "fullDiskAccess";
+      readonly resume: "configure" | "import";
+      readonly checked?: boolean;
+    }
   | { readonly step: "configure" }
-  | { readonly step: "checking" }
+  | { readonly step: "checking"; readonly check: "browser" | "fullDiskAccess" }
   | { readonly step: "importing" }
   | {
       readonly step: "done";
@@ -82,6 +87,9 @@ export function canCloseWizard(step: WizardStep): boolean {
  */
 export function initialWizardStep(source: BrowserImportSource): WizardStep {
   if (source.unavailable === "browserRunning") return { step: "quit" };
+  if (source.unavailable === "needsFullDiskAccess") {
+    return { step: "fullDiskAccess", resume: "configure" };
+  }
   if (source.unavailable !== undefined) return { step: "blocked", reason: source.unavailable };
   if (source.profiles.length === 0) return { step: "blocked", reason: "unknownSourceProfile" };
   return { step: "configure" };
@@ -102,6 +110,11 @@ export function outcomeToStep(outcome: ImportOutcome): WizardStep {
   // other failure surfaces on the blocked screen, which offers a retry when
   // one could help.
   if (outcome.reason === "browserRunning") return { step: "quit" };
+  if (outcome.reason === "needsFullDiskAccess") {
+    // The failed import already checked access, so explain that it is still
+    // denied instead of returning to an indistinguishable permission screen.
+    return { step: "fullDiskAccess", resume: "import", checked: true };
+  }
   return { step: "blocked", reason: outcome.reason };
 }
 
@@ -111,6 +124,12 @@ export function refreshedSourceStep(source: BrowserImportSource | undefined): Wi
   return initialWizardStep(source);
 }
 
+/** A denied FDA recheck returns to the permission step with visible feedback. */
+export function fullDiskAccessRecheckStep(source: BrowserImportSource | undefined): WizardStep {
+  const next = refreshedSourceStep(source);
+  return next.step === "fullDiskAccess" ? { ...next, checked: true } : next;
+}
+
 /** Preserve the chosen source profile when a post-quit refresh still lists it. */
 export function refreshedSourceProfileDirectory(
   currentDirectory: string,
diff --git a/apps/web/src/localApi.test.ts b/apps/web/src/localApi.test.ts
index 9220252cb20e..33c53a86c4e2 100644
--- a/apps/web/src/localApi.test.ts
+++ b/apps/web/src/localApi.test.ts
@@ -113,6 +113,14 @@ describe("LocalApi", () => {
     await expect(createLocalApi().dialogs.confirm("Delete this thread?")).resolves.toBe(false);
   });
 
+  it("rejects opening System Settings when the desktop bridge is unavailable", async () => {
+    const { createLocalApi } = await import("./localApi");
+
+    await expect(createLocalApi().shell.openSystemSettings("full-disk-access")).rejects.toThrow(
+      "Unable to open System Settings.",
+    );
+  });
+
   it("delegates host capabilities and persistence to the desktop bridge", async () => {
     const showContextMenu = vi.fn().mockResolvedValue("delete");
     const pickFolder = vi.fn().mockResolvedValue("/tmp/project");
diff --git a/apps/web/src/localApi.ts b/apps/web/src/localApi.ts
index 8f55f65e40de..cafd04f9c048 100644
--- a/apps/web/src/localApi.ts
+++ b/apps/web/src/localApi.ts
@@ -29,6 +29,17 @@ function createBrowserLocalApi(): LocalApi {
 
         window.open(url, "_blank", "noopener,noreferrer");
       },
+      // Only the desktop shell can reach the OS; the web build (and older
+      // desktop shells that predate this method) have nothing to open.
+      openSystemSettings: async (pane) => {
+        if (!window.desktopBridge?.openSystemSettings) {
+          throw new Error("Unable to open System Settings.");
+        }
+        const opened = await window.desktopBridge.openSystemSettings(pane);
+        if (!opened) {
+          throw new Error("Unable to open System Settings.");
+        }
+      },
     },
     contextMenu: {
       show: async <T extends string>(
diff --git a/docs/user/browser-import.md b/docs/user/browser-import.md
index 9aa4c6ca0e7f..93f2fad73741 100644
--- a/docs/user/browser-import.md
+++ b/docs/user/browser-import.md
@@ -10,6 +10,12 @@ unlock prompt if one appears.
 This is a one-time copy. Later login changes stay separate between the two browsers, and some
 sites may still require you to sign in again.
 
+On macOS, Safari is also available. Safari protects its cookies with Full Disk Access rather than
+a keychain, so the import wizard asks you to grant it: **Open System Settings** takes you to the
+right pane, and macOS may ask you to quit and reopen T3 Code before the grant applies. You can
+revoke Full Disk Access after the import is done. Only Safari's primary profile is imported; cookies
+kept by additional Safari profiles are not.
+
 On Windows, import supports Firefox and Helium profiles that use standard profile encryption.
 Other Chromium-based browsers use app-bound encryption and cannot be imported. Partitioned cookies
 are skipped on all platforms.
diff --git a/packages/contracts/src/browserImport.ts b/packages/contracts/src/browserImport.ts
index 4448ae37b472..2c7eb24821d3 100644
--- a/packages/contracts/src/browserImport.ts
+++ b/packages/contracts/src/browserImport.ts
@@ -25,6 +25,7 @@ export const BROWSER_IMPORT_SOURCE_IDS = [
   "arc",
   "helium",
   "firefox",
+  "safari",
 ] as const;
 
 export const BrowserImportSourceId = Schema.Literals(BROWSER_IMPORT_SOURCE_IDS);
@@ -42,6 +43,7 @@ export const BrowserImportUnavailableReason = Schema.Literals([
   "notInstalled",
   "needsKeychainApproval",
   "keychainItemMissing",
+  "needsFullDiskAccess",
   "browserRunning",
   "unsupportedPlatform",
 ]);
@@ -144,6 +146,8 @@ export const BROWSER_IMPORT_UNAVAILABLE_COPY: Readonly<
   needsKeychainApproval: "Needs Keychain access to read its cookies.",
   keychainItemMissing:
     "No encryption key in your Keychain — sign in to that browser once, then retry.",
+  needsFullDiskAccess:
+    "Give T3 Code Full Disk Access in System Settings → Privacy & Security, then retry.",
   browserRunning: "Quit the browser first so its cookie database can be read.",
   unsupportedPlatform: "Importing from this browser isn't possible on this platform.",
 };
diff --git a/packages/contracts/src/ipc.ts b/packages/contracts/src/ipc.ts
index 798d5a777d5d..a14a4ed0a08a 100644
--- a/packages/contracts/src/ipc.ts
+++ b/packages/contracts/src/ipc.ts
@@ -1052,6 +1052,13 @@ export const DesktopPreviewAutomationWaitForInputSchema = Schema.Struct({
   input: PreviewAutomationWaitForInput,
 });
 
+/**
+ * A System Settings pane the app can deep-link to. The identifier crosses IPC
+ * rather than a URL, so the renderer can only reach these known destinations.
+ */
+export const SystemSettingsPaneSchema = Schema.Literals(["full-disk-access"]);
+export type SystemSettingsPane = typeof SystemSettingsPaneSchema.Type;
+
 export interface DesktopBridge {
   getAppBranding: () => DesktopAppBranding | null;
   /** The desktop client's OS platform, read from Electron's preload process. */
@@ -1119,6 +1126,11 @@ export interface DesktopBridge {
     position?: { x: number; y: number },
   ) => Promise<T | null>;
   openExternal: (url: string) => Promise<boolean>;
+  /**
+   * Open a System Settings pane by identifier. Optional: older desktop builds
+   * lack it, and callers no-op when it is missing.
+   */
+  openSystemSettings?: (pane: SystemSettingsPane) => Promise<boolean>;
   /**
    * Probe this desktop machine for installed remote-capable editor CLIs
    * (used for remote open-in-editor deep links). Optional: older desktop
@@ -1267,6 +1279,8 @@ export interface LocalApi {
   };
   shell: {
     openExternal: (url: string) => Promise<void>;
+    /** Opens a known System Settings pane; no-ops outside the desktop app. */
+    openSystemSettings: (pane: SystemSettingsPane) => Promise<void>;
   };
   contextMenu: {
     show: <T extends string>(

From 8faf031c2dac4f147c43fe32e326b76678c20c94 Mon Sep 17 00:00:00 2001
From: Michel Liao <107891771+Michel-Liao@users.noreply.github.com>
Date: Fri, 4 Sep 2026 20:27:31 -0400
Subject: [PATCH 46/56] fix(web): respect case in POSIX file links (#9309)

Co-authored-by: Julius Marminge <51714798+juliusmarminge@users.noreply.github.com>
---
 apps/web/src/filePathDisplay.test.ts          |  6 ++
 apps/web/src/filePathDisplay.ts               | 10 +++-
 apps/web/src/markdown-links.test.ts           | 55 +++++++++++++++++++
 .../client-runtime/src/markdownLinks.test.ts  | 12 +++-
 packages/client-runtime/src/markdownLinks.ts  |  5 +-
 5 files changed, 83 insertions(+), 5 deletions(-)

diff --git a/apps/web/src/filePathDisplay.test.ts b/apps/web/src/filePathDisplay.test.ts
index ecceea09ca1e..4c49133a3138 100644
--- a/apps/web/src/filePathDisplay.test.ts
+++ b/apps/web/src/filePathDisplay.test.ts
@@ -38,4 +38,10 @@ describe("formatWorkspaceRelativePath", () => {
       ),
     ).toBe("t3code/apps/web/src/session-logic.ts:501:9");
   });
+
+  it("keeps double-slash POSIX paths case-sensitive", () => {
+    expect(formatWorkspaceRelativePath("//tmp/project/probe.txt", "//tmp/Project")).toBe(
+      "//tmp/project/probe.txt",
+    );
+  });
 });
diff --git a/apps/web/src/filePathDisplay.ts b/apps/web/src/filePathDisplay.ts
index fc197a4092b5..36f5873cf8e0 100644
--- a/apps/web/src/filePathDisplay.ts
+++ b/apps/web/src/filePathDisplay.ts
@@ -4,6 +4,7 @@ import {
   splitFilePathPosition,
   stripSlashPrefixedWindowsDrive,
 } from "@t3tools/client-runtime/markdown-links";
+import { isWindowsAbsolutePath } from "@t3tools/shared/path";
 
 function normalizePathSeparators(path: string): string {
   return path.replaceAll("\\", "/");
@@ -30,10 +31,13 @@ export function formatWorkspaceRelativePath(
       normalizePathSeparators(trimTrailingPathSeparators(workspaceRoot)),
     );
     const workspaceLabel = fileBasename(normalizedWorkspaceRoot);
-    const pathForCompare = normalizedPath.toLowerCase();
-    const workspaceForCompare = normalizedWorkspaceRoot.toLowerCase();
+    const caseInsensitive = isWindowsAbsolutePath(stripSlashPrefixedWindowsDrive(workspaceRoot));
+    const pathForCompare = caseInsensitive ? normalizedPath.toLowerCase() : normalizedPath;
+    const workspaceForCompare = caseInsensitive
+      ? normalizedWorkspaceRoot.toLowerCase()
+      : normalizedWorkspaceRoot;
     const workspaceWithSeparator = `${workspaceForCompare}/`;
-    const workspaceLabelWithSeparator = `${workspaceLabel.toLowerCase()}/`;
+    const workspaceLabelWithSeparator = `${caseInsensitive ? workspaceLabel.toLowerCase() : workspaceLabel}/`;
 
     if (pathForCompare === workspaceForCompare) {
       displayPath = workspaceLabel;
diff --git a/apps/web/src/markdown-links.test.ts b/apps/web/src/markdown-links.test.ts
index e3b1cc5b2249..5421c0d8781d 100644
--- a/apps/web/src/markdown-links.test.ts
+++ b/apps/web/src/markdown-links.test.ts
@@ -254,6 +254,61 @@ describe("resolveMarkdownFileLinkTarget", () => {
     });
   });
 
+  it("does not classify a case-distinct POSIX sibling as a workspace file", () => {
+    expect(
+      resolveMarkdownFileLinkMeta(
+        "/tmp/t3code-case-test/project/probe.txt",
+        "/tmp/t3code-case-test/Project",
+      ),
+    ).toMatchObject({
+      displayPath: "/tmp/t3code-case-test/project/probe.txt",
+      workspaceRelativePath: null,
+    });
+  });
+
+  it("keeps Windows workspace comparisons case-insensitive", () => {
+    expect(
+      resolveMarkdownFileLinkMeta("C:/Users/MIKE/Project/src/main.ts", "c:/users/mike/project"),
+    ).toMatchObject({
+      displayPath: "project/src/main.ts",
+      workspaceRelativePath: "src/main.ts",
+    });
+  });
+
+  it("keeps drive-root workspace comparisons case-insensitive", () => {
+    expect(resolveMarkdownFileLinkMeta("C:/Users/MIKE/project.ts", "c:/")).toMatchObject({
+      displayPath: "c:/Users/MIKE/project.ts",
+      workspaceRelativePath: "Users/MIKE/project.ts",
+    });
+  });
+
+  it("keeps backslash UNC workspace comparisons case-insensitive", () => {
+    expect(
+      resolveMarkdownFileLinkMeta(
+        "\\\\server\\share\\PROJECT\\src\\main.ts",
+        "\\\\Server\\Share\\Project",
+      ),
+    ).toMatchObject({
+      displayPath: "Project/src/main.ts",
+      workspaceRelativePath: "src/main.ts",
+    });
+  });
+
+  it.each([
+    ["/tmp/repo/file.ts", "/", "tmp/repo/file.ts"],
+    ["C:/Users/MIKE/file.ts", "c:/", "Users/MIKE/file.ts"],
+    ["\\\\server\\SHARE\\file.ts", "\\\\Server\\Share\\", "file.ts"],
+    ["/tmp/repo/file.ts%20", "/tmp/repo", "file.ts "],
+  ])("preserves the preview target for %s in workspace %s", (href, cwd, workspaceRelativePath) => {
+    expect(resolveMarkdownFileLinkMeta(href, cwd)).toMatchObject({ workspaceRelativePath });
+  });
+
+  it("keeps an encoded final space in the absolute target", () => {
+    expect(resolveMarkdownFileLinkTarget("/tmp/repo/file.ts%20", "/tmp/repo")).toBe(
+      "/tmp/repo/file.ts ",
+    );
+  });
+
   it("normalizes slash-prefixed windows drive paths before resolving", () => {
     expect(
       resolveMarkdownFileLinkTarget(
diff --git a/packages/client-runtime/src/markdownLinks.test.ts b/packages/client-runtime/src/markdownLinks.test.ts
index cf8f9ae2d16e..42cd7a35e473 100644
--- a/packages/client-runtime/src/markdownLinks.test.ts
+++ b/packages/client-runtime/src/markdownLinks.test.ts
@@ -160,7 +160,17 @@ describe("workspaceRelativeFilePath", () => {
     ["/repo/project/src/main.ts", "/repo/project/", "src/main.ts"],
     ["C:\\Users\\mike\\t3code\\apps\\web\\a.ts", "C:/Users/mike/t3code", "apps/web/a.ts"],
     ["/C:/Users/mike/t3code/apps/web/a.ts", "C:/Users/mike/t3code", "apps/web/a.ts"],
-    ["/Repo/Project/src/main.ts", "/repo/project", "src/main.ts"],
+    ["/Repo/Project/src/main.ts", "/repo/project", null],
+    ["/tmp/case/project/probe.txt", "/tmp/case/Project", null],
+    ["//tmp/case/project/probe.txt", "//tmp/case/Project", null],
+    ["/tmp/case/Project/probe.txt", "/tmp/case/Project", "probe.txt"],
+    ["C:/USERS/mike/t3code/main.ts", "c:/users/MIKE/t3code", "main.ts"],
+    ["/C:/USERS/mike/t3code/main.ts", "/c:/users/MIKE/t3code", "main.ts"],
+    ["\\\\server\\share\\PROJECT\\main.ts", "\\\\Server\\Share\\Project", "main.ts"],
+    ["/tmp/repo/file.ts", "/", "tmp/repo/file.ts"],
+    ["C:/Users/MIKE/main.ts", "c:/", "Users/MIKE/main.ts"],
+    ["\\\\server\\SHARE\\file.ts", "\\\\Server\\Share\\", "file.ts"],
+    ["/tmp/repo/file.ts ", "/tmp/repo", "file.ts "],
     ["/tmp/report.ts", "/repo/project", null],
     ["/repo/project-two/a.ts", "/repo/project", null],
     ["/repo/project/a.ts", undefined, null],
diff --git a/packages/client-runtime/src/markdownLinks.ts b/packages/client-runtime/src/markdownLinks.ts
index 81cce1fd7eee..2e455655d005 100644
--- a/packages/client-runtime/src/markdownLinks.ts
+++ b/packages/client-runtime/src/markdownLinks.ts
@@ -342,6 +342,9 @@ export function workspaceRelativeFilePath(
   const normalizedRoot = stripSlashPrefixedWindowsDrive(
     workspaceRoot.replaceAll("\\", "/"),
   ).replace(/\/+$/, "");
-  if (!normalizedPath.toLowerCase().startsWith(`${normalizedRoot.toLowerCase()}/`)) return null;
+  const caseInsensitive = isWindowsAbsolutePath(stripSlashPrefixedWindowsDrive(workspaceRoot));
+  const pathForCompare = caseInsensitive ? normalizedPath.toLowerCase() : normalizedPath;
+  const rootForCompare = caseInsensitive ? normalizedRoot.toLowerCase() : normalizedRoot;
+  if (!pathForCompare.startsWith(`${rootForCompare}/`)) return null;
   return normalizedPath.slice(normalizedRoot.length + 1);
 }

From fce8508456e7f9218eebb02ecd764f9b3a47df6b Mon Sep 17 00:00:00 2001
From: Joaquin Navarro <joaquin@freedomcodecompliance.com>
Date: Fri, 4 Sep 2026 20:31:05 -0400
Subject: [PATCH 47/56] fix(server): surface a missing workspace folder instead
 of a spawn error (#5040)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Julius Marminge <51714798+juliusmarminge@users.noreply.github.com>
---
 .../providerService.integration.test.ts       |   5 +-
 .../Layers/ProviderCommandReactor.test.ts     |  60 +++++++-
 .../Layers/ProviderCommandReactor.ts          |   5 +
 apps/server/src/provider/Errors.ts            |  17 +++
 .../provider/Layers/ProviderService.test.ts   | 140 ++++++++++++++----
 .../src/provider/Layers/ProviderService.ts    |  24 ++-
 6 files changed, 217 insertions(+), 34 deletions(-)

diff --git a/apps/server/integration/providerService.integration.test.ts b/apps/server/integration/providerService.integration.test.ts
index 3ad85b1a68b9..0d041b36ecb8 100644
--- a/apps/server/integration/providerService.integration.test.ts
+++ b/apps/server/integration/providerService.integration.test.ts
@@ -100,7 +100,10 @@ const makeIntegrationFixture = (options?: { readonly analytics?: Layer.Layer<Ana
       Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers),
     ).pipe(Layer.provide(SqlitePersistenceMemory));
 
-    const layer = makeProviderServiceLive().pipe(Layer.provide(shared));
+    const layer = makeProviderServiceLive().pipe(
+      Layer.provide(NodeServices.layer),
+      Layer.provide(shared),
+    );
 
     return {
       cwd,
diff --git a/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts b/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts
index 38970e45421d..4d35c5b04dd4 100644
--- a/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts
+++ b/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts
@@ -39,7 +39,11 @@ import { afterEach, describe, expect, it, vi } from "vite-plus/test";
 
 import { deriveServerPaths, ServerConfig } from "../../config.ts";
 import { TextGenerationError } from "@t3tools/contracts";
-import { ProviderAdapterRequestError } from "../../provider/Errors.ts";
+import {
+  ProviderAdapterRequestError,
+  ProviderWorkspaceMissingError,
+  type ProviderServiceError,
+} from "../../provider/Errors.ts";
 import { OrchestrationEventStoreLive } from "../../persistence/Layers/OrchestrationEventStore.ts";
 import { OrchestrationCommandReceiptRepositoryLive } from "../../persistence/Layers/OrchestrationCommandReceipts.ts";
 import { SqlitePersistenceMemory } from "../../persistence/Layers/Sqlite.ts";
@@ -181,7 +185,7 @@ describe("ProviderCommandReactor", () => {
     readonly stopSessionEffect?: () => Effect.Effect<void, ProviderAdapterRequestError>;
     readonly startSessionEffect?: (
       session: ProviderSession,
-    ) => Effect.Effect<ProviderSession, ProviderAdapterRequestError>;
+    ) => Effect.Effect<ProviderSession, ProviderServiceError>;
     readonly tryHandlePromptCommandEffect?: ProviderAuthService["Service"]["tryHandlePromptCommand"];
   }) {
     const now = "2026-01-01T00:00:00.000Z";
@@ -1217,6 +1221,58 @@ describe("ProviderCommandReactor", () => {
     }),
   );
 
+  effectIt.effect("shows the missing workspace message without a provider stack trace", () =>
+    Effect.gen(function* () {
+      const attempted = yield* Deferred.make<void>();
+      const missingCwd = "/missing/project/worktree";
+      const missingWorkspace = new ProviderWorkspaceMissingError({
+        threadId: ThreadId.make("thread-1"),
+        cwd: missingCwd,
+      });
+      const harness = yield* Effect.promise(() =>
+        createHarness({
+          startSessionEffect: () =>
+            Deferred.succeed(attempted, undefined).pipe(
+              Effect.andThen(Effect.fail(missingWorkspace)),
+            ),
+        }),
+      );
+
+      yield* harness.engine.dispatch({
+        type: "thread.turn.start",
+        commandId: CommandId.make("cmd-turn-start-missing-workspace"),
+        threadId: ThreadId.make("thread-1"),
+        message: {
+          messageId: asMessageId("user-message-missing-workspace"),
+          role: "user",
+          text: "continue",
+          attachments: [],
+        },
+        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+        runtimeMode: "approval-required",
+        createdAt: "2026-01-01T00:00:00.000Z",
+      });
+      yield* Deferred.await(attempted);
+      yield* Effect.promise(() => harness.drain());
+
+      const thread = (yield* Effect.promise(() => harness.readModel())).threads.find(
+        (entry) => entry.id === ThreadId.make("thread-1"),
+      );
+      expect(thread?.session).toMatchObject({
+        status: "error",
+        activeTurnId: null,
+        lastError: missingWorkspace.message,
+      });
+      const failure = thread?.activities.find(
+        (activity) => activity.kind === "provider.turn.start.failed",
+      );
+      expect(failure?.payload).toMatchObject({ detail: missingWorkspace.message });
+      expect(harness.runtimeSessions).toEqual([]);
+      expect(harness.sendTurn).not.toHaveBeenCalled();
+      expect(yield* Effect.promise(() => harness.readPendingTurnStarts())).toEqual([]);
+    }),
+  );
+
   effectIt.effect("settles a failed provider startup and allows a clean retry", () =>
     Effect.gen(function* () {
       let failStartup = true;
diff --git a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts b/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
index 1589bc94b78b..b8e457e34ebb 100644
--- a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
+++ b/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
@@ -34,6 +34,7 @@ import { increment, orchestrationEventsProcessedTotal } from "../../observabilit
 import {
   ProviderAdapterRequestError,
   ProviderAdapterValidationError,
+  ProviderWorkspaceMissingError,
 } from "../../provider/Errors.ts";
 import type { ProviderServiceError } from "../../provider/Errors.ts";
 import { TextGeneration } from "../../textGeneration/TextGeneration.ts";
@@ -56,6 +57,7 @@ import { VcsStatusBroadcaster } from "../../vcs/VcsStatusBroadcaster.ts";
 import { GitWorkflowService } from "../../git/GitWorkflowService.ts";
 const isProviderAdapterRequestError = Schema.is(ProviderAdapterRequestError);
 const isProviderAdapterValidationError = Schema.is(ProviderAdapterValidationError);
+const isProviderWorkspaceMissingError = Schema.is(ProviderWorkspaceMissingError);
 const isProviderDriverKind = Schema.is(ProviderDriverKind);
 
 type ProviderIntentEvent = Extract<
@@ -394,6 +396,9 @@ const make = Effect.gen(function* () {
     if (isProviderAdapterValidationError(failReason?.error)) {
       return failReason.error.issue;
     }
+    if (isProviderWorkspaceMissingError(failReason?.error)) {
+      return failReason.error.message;
+    }
     return Cause.pretty(cause);
   };
 
diff --git a/apps/server/src/provider/Errors.ts b/apps/server/src/provider/Errors.ts
index 0cf1522399b4..4abb10554462 100644
--- a/apps/server/src/provider/Errors.ts
+++ b/apps/server/src/provider/Errors.ts
@@ -85,6 +85,22 @@ export class ProviderAdapterProcessError extends Schema.TaggedErrorClass<Provide
   }
 }
 
+/**
+ * ProviderWorkspaceMissingError - The session's working directory no longer
+ * exists on disk, so no provider process can start in it.
+ */
+export class ProviderWorkspaceMissingError extends Schema.TaggedErrorClass<ProviderWorkspaceMissingError>()(
+  "ProviderWorkspaceMissingError",
+  {
+    threadId: Schema.String,
+    cwd: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `This thread's workspace folder no longer exists or is not a directory: ${this.cwd}. Restore the folder at this path before retrying.`;
+  }
+}
+
 /**
  * ProviderValidationError - Invalid provider API input.
  */
@@ -197,6 +213,7 @@ export type ProviderAdapterError =
 export type ProviderServiceError =
   | ProviderValidationError
   | ProviderUnsupportedError
+  | ProviderWorkspaceMissingError
   | ProviderInstanceNotFoundError
   | ProviderSessionNotFoundError
   | ProviderSessionDirectoryPersistenceError
diff --git a/apps/server/src/provider/Layers/ProviderService.test.ts b/apps/server/src/provider/Layers/ProviderService.test.ts
index 95e5a7983346..f5b9be91650f 100644
--- a/apps/server/src/provider/Layers/ProviderService.test.ts
+++ b/apps/server/src/provider/Layers/ProviderService.test.ts
@@ -32,6 +32,7 @@ import {
 } from "@t3tools/shared/assistantCitations";
 import { createModelSelection } from "@t3tools/shared/model";
 import { it, assert, describe, vi } from "@effect/vitest";
+import { afterAll } from "vite-plus/test";
 
 import * as Cause from "effect/Cause";
 import * as Deferred from "effect/Deferred";
@@ -54,6 +55,7 @@ import {
   ProviderAdapterSessionNotFoundError,
   ProviderUnsupportedError,
   ProviderValidationError,
+  ProviderWorkspaceMissingError,
   type ProviderAdapterError,
 } from "../Errors.ts";
 import type { ProviderAdapterShape } from "../Services/ProviderAdapter.ts";
@@ -79,6 +81,16 @@ const serverConfigTestLayer = ServerConfig.layerTest(process.cwd(), process.cwd(
   Layer.provide(NodeServices.layer),
 );
 
+// startSession verifies the workspace folder exists before dispatching to an
+// adapter, so session cwd fixtures must be real directories.
+const fixtureCwdRoot = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "provider-service-test-"));
+afterAll(() => NodeFS.rmSync(fixtureCwdRoot, { recursive: true, force: true }));
+function fixtureCwd(name: string): string {
+  const dir = NodePath.join(fixtureCwdRoot, name);
+  NodeFS.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
 const asRequestId = (value: string): ApprovalRequestId => ApprovalRequestId.make(value);
 const asEventId = (value: string): EventId => EventId.make(value);
 const asThreadId = (value: string): ThreadId => ThreadId.make(value);
@@ -425,6 +437,7 @@ function makeProviderServiceLayer(
   const layer = it.layer(
     Layer.mergeAll(
       makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
         Layer.provide(providerAdapterLayer),
         Layer.provide(directoryLayer),
         Layer.provide(defaultServerSettingsLayer),
@@ -477,6 +490,7 @@ for (const [enabled, completed] of [
         const scope = yield* Scope.make();
         const services = yield* Layer.build(
           makeProviderServiceLive().pipe(
+            Layer.provide(NodeServices.layer),
             Layer.provide(
               Layer.succeed(ProviderSessionDirectory.ProviderSessionDirectory, directory),
             ),
@@ -596,6 +610,7 @@ it.effect("ProviderServiceLive catches stopAll failures during shutdown", () =>
     const directoryLayer = ProviderSessionDirectoryLive.pipe(Layer.provide(runtimeRepositoryLayer));
     const providerLayer = Layer.mergeAll(
       makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
         Layer.provide(providerAdapterLayer),
         Layer.provide(directoryLayer),
         Layer.provide(defaultServerSettingsLayer),
@@ -638,6 +653,7 @@ it.effect("ProviderServiceLive flushes deferred completions during shutdown", ()
     const directoryLayer = ProviderSessionDirectoryLive.pipe(Layer.provide(runtimeRepositoryLayer));
     const providerLayer = Layer.mergeAll(
       makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
         Layer.provide(providerAdapterLayer),
         Layer.provide(directoryLayer),
         Layer.provide(defaultServerSettingsLayer),
@@ -774,6 +790,7 @@ it.effect("ProviderServiceLive rejects new sessions for disabled providers", ()
     );
     const directoryLayer = ProviderSessionDirectoryLive.pipe(Layer.provide(runtimeRepositoryLayer));
     const providerLayer = makeProviderServiceLive().pipe(
+      Layer.provide(NodeServices.layer),
       Layer.provide(providerAdapterLayer),
       Layer.provide(directoryLayer),
       Layer.provide(defaultServerSettingsLayer),
@@ -857,6 +874,7 @@ it.effect(
         Layer.provide(runtimeRepositoryLayer),
       );
       const providerLayer = makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
         Layer.provide(providerAdapterLayer),
         Layer.provide(directoryLayer),
         Layer.provide(serverSettingsLayer),
@@ -926,6 +944,7 @@ it.effect("ProviderServiceLive rejects new sessions for disabled custom instance
     );
     const directoryLayer = ProviderSessionDirectoryLive.pipe(Layer.provide(runtimeRepositoryLayer));
     const providerLayer = makeProviderServiceLive().pipe(
+      Layer.provide(NodeServices.layer),
       Layer.provide(providerAdapterLayer),
       Layer.provide(directoryLayer),
       Layer.provide(defaultServerSettingsLayer),
@@ -1044,7 +1063,7 @@ unsupportedRollback.layer("ProviderServiceLive unsupported rewind", (it) => {
         yield* provider.startSession(threadId, {
           providerInstanceId: codexInstanceId,
           threadId,
-          cwd: "/tmp/project",
+          cwd: fixtureCwd("project"),
           runtimeMode: "approval-required",
         });
         if (!active) {
@@ -1098,6 +1117,7 @@ it.effect(
         Layer.provide(runtimeRepositoryLayer),
       );
       const providerLayer = makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
         Layer.provide(Layer.succeed(ProviderAdapterRegistry.ProviderAdapterRegistry, registry)),
         Layer.provide(directoryLayer),
         Layer.provide(defaultServerSettingsLayer),
@@ -1218,6 +1238,7 @@ it.effect("ProviderServiceLive keeps persisted resumable sessions on startup", (
     }).pipe(Effect.provide(directoryLayer));
 
     const providerLayer = makeProviderServiceLive().pipe(
+      Layer.provide(NodeServices.layer),
       Layer.provide(Layer.succeed(ProviderAdapterRegistry.ProviderAdapterRegistry, registry)),
       Layer.provide(directoryLayer),
       Layer.provide(defaultServerSettingsLayer),
@@ -1283,6 +1304,7 @@ it.effect(
         Layer.provide(runtimeRepositoryLayer),
       );
       const firstProviderLayer = makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
         Layer.provide(
           Layer.succeed(ProviderAdapterRegistry.ProviderAdapterRegistry, firstRegistry),
         ),
@@ -1310,7 +1332,7 @@ it.effect(
         const session = yield* provider.startSession(threadId, {
           provider: ProviderDriverKind.make("codex"),
           providerInstanceId: codexInstanceId,
-          cwd: "/tmp/project",
+          cwd: fixtureCwd("project"),
           runtimeMode: "full-access",
           threadId,
         });
@@ -1343,6 +1365,7 @@ it.effect(
         Layer.provide(runtimeRepositoryLayer),
       );
       const secondProviderLayer = makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
         Layer.provide(
           Layer.succeed(ProviderAdapterRegistry.ProviderAdapterRegistry, secondRegistry),
         ),
@@ -1380,7 +1403,7 @@ it.effect(
           threadId?: string;
         };
         assert.equal(startPayload.provider, "codex");
-        assert.equal(startPayload.cwd, "/tmp/project");
+        assert.equal(startPayload.cwd, fixtureCwd("project"));
         assert.deepEqual(startPayload.resumeCursor, updatedResumeCursor);
         assert.equal(startPayload.threadId, startedSession.threadId);
       }
@@ -1394,6 +1417,61 @@ it.effect(
 );
 
 routing.layer("ProviderServiceLive routing", (it) => {
+  it.effect.each([CODEX_DRIVER, CLAUDE_AGENT_DRIVER, CURSOR_DRIVER])(
+    "rejects missing, file, and saved workspace paths before starting %s",
+    (driver) =>
+      Effect.gen(function* () {
+        const provider = yield* ProviderService.ProviderService;
+        const adapter =
+          driver === CODEX_DRIVER
+            ? routing.codex
+            : driver === CLAUDE_AGENT_DRIVER
+              ? routing.claude
+              : routing.cursor;
+        const cwd = fixtureCwd(`missing-workspace-${driver}`);
+        const movedCwd = `${cwd}-moved`;
+        const threadId = asThreadId(`missing-workspace-${driver}`);
+        const input = {
+          provider: driver,
+          providerInstanceId: ProviderInstanceId.make(driver),
+          threadId,
+          runtimeMode: "full-access" as const,
+          cwd,
+        };
+
+        yield* provider.startSession(threadId, input);
+        yield* provider.stopSession({ threadId });
+        adapter.startSession.mockClear();
+        NodeFS.renameSync(cwd, movedCwd);
+
+        const failure = yield* provider.startSession(threadId, input).pipe(Effect.flip);
+        assert.instanceOf(failure, ProviderWorkspaceMissingError);
+        assert.include(failure.message, cwd);
+        assert.equal(adapter.startSession.mock.calls.length, 0);
+
+        const { cwd: _cwd, ...savedInput } = input;
+        const savedFailure = yield* provider.startSession(threadId, savedInput).pipe(Effect.flip);
+        assert.instanceOf(savedFailure, ProviderWorkspaceMissingError);
+        assert.include(savedFailure.message, cwd);
+        assert.equal(adapter.startSession.mock.calls.length, 0);
+
+        NodeFS.writeFileSync(cwd, "not a directory");
+        const fileFailure = yield* provider.startSession(threadId, input).pipe(Effect.flip);
+        assert.instanceOf(fileFailure, ProviderWorkspaceMissingError);
+        assert.include(fileFailure.message, cwd);
+        assert.equal(adapter.startSession.mock.calls.length, 0);
+
+        NodeFS.unlinkSync(cwd);
+        NodeFS.renameSync(movedCwd, cwd);
+        const restored = yield* provider.startSession(threadId, savedInput);
+        assert.equal(restored.cwd, cwd);
+        assert.equal(adapter.startSession.mock.calls.length, 1);
+        yield* provider.stopSession({ threadId });
+        adapter.startSession.mockClear();
+        adapter.stopSession.mockClear();
+      }),
+  );
+
   it.effect("allows promptless continuation only for capable providers", () =>
     Effect.gen(function* () {
       const provider = yield* ProviderService.ProviderService;
@@ -1452,7 +1530,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         provider: ProviderDriverKind.make("codex"),
         providerInstanceId: codexInstanceId,
         threadId: asThreadId("thread-1"),
-        cwd: "/tmp/project",
+        cwd: fixtureCwd("project"),
         runtimeMode: "full-access",
       });
       assert.equal(session.provider, "codex");
@@ -1522,7 +1600,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
           threadId?: string;
         };
         assert.equal(startPayload.provider, "codex");
-        assert.equal(startPayload.cwd, "/tmp/project");
+        assert.equal(startPayload.cwd, fixtureCwd("project"));
         assert.deepEqual(startPayload.resumeCursor, session.resumeCursor);
         assert.equal(startPayload.threadId, session.threadId);
       }
@@ -1799,7 +1877,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         provider: CODEX_DRIVER,
         providerInstanceId: codexInstanceId,
         threadId,
-        cwd: "/tmp/feedback-project",
+        cwd: fixtureCwd("feedback-project"),
         runtimeMode: "full-access",
       });
       yield* routing.codex.stopSession(threadId);
@@ -1862,7 +1940,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         provider: ProviderDriverKind.make("codex"),
         providerInstanceId: codexInstanceId,
         threadId: asThreadId("thread-attach"),
-        cwd: "/tmp/project",
+        cwd: fixtureCwd("project"),
         runtimeMode: "full-access",
       });
 
@@ -1937,7 +2015,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         provider: ProviderDriverKind.make("codex"),
         providerInstanceId: codexInstanceId,
         threadId: asThreadId("thread-1"),
-        cwd: "/tmp/project",
+        cwd: fixtureCwd("project"),
         runtimeMode: "full-access",
       });
       yield* routing.codex.stopSession(initial.threadId);
@@ -1963,7 +2041,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
           threadId?: string;
         };
         assert.equal(startPayload.provider, "codex");
-        assert.equal(startPayload.cwd, "/tmp/project");
+        assert.equal(startPayload.cwd, fixtureCwd("project"));
         assert.deepEqual(startPayload.resumeCursor, initial.resumeCursor);
         assert.equal(startPayload.threadId, initial.threadId);
       }
@@ -1982,7 +2060,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         provider: ProviderDriverKind.make("codex"),
         providerInstanceId: codexInstanceId,
         threadId: asThreadId("thread-reap-preserve"),
-        cwd: "/tmp/project-reap-preserve",
+        cwd: fixtureCwd("project-reap-preserve"),
         runtimeMode: "full-access",
       });
 
@@ -2017,7 +2095,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
           threadId?: string;
         };
         assert.equal(startPayload.provider, "codex");
-        assert.equal(startPayload.cwd, "/tmp/project-reap-preserve");
+        assert.equal(startPayload.cwd, fixtureCwd("project-reap-preserve"));
         assert.deepEqual(startPayload.resumeCursor, initial.resumeCursor);
         assert.equal(startPayload.threadId, initial.threadId);
       }
@@ -2033,7 +2111,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         provider: ProviderDriverKind.make("claudeAgent"),
         providerInstanceId: claudeAgentInstanceId,
         threadId: asThreadId("thread-claude"),
-        cwd: "/tmp/project-claude",
+        cwd: fixtureCwd("project-claude"),
         runtimeMode: "full-access",
       });
 
@@ -2049,7 +2127,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         };
         assert.equal(startPayload.provider, "claudeAgent");
         assert.equal(startPayload.providerInstanceId, claudeAgentInstanceId);
-        assert.equal(startPayload.cwd, "/tmp/project-claude");
+        assert.equal(startPayload.cwd, fixtureCwd("project-claude"));
       }
     }),
   );
@@ -2064,7 +2142,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         provider: ProviderDriverKind.make("codex"),
         providerInstanceId: codexInstanceId,
         threadId,
-        cwd: "/tmp/project-binding-mismatch",
+        cwd: fixtureCwd("project-binding-mismatch"),
         runtimeMode: "full-access",
       });
       yield* directory.upsert({
@@ -2094,7 +2172,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         provider: ProviderDriverKind.make("codex"),
         providerInstanceId: codexInstanceId,
         threadId,
-        cwd: "/tmp/project-provider-replacement",
+        cwd: fixtureCwd("project-provider-replacement"),
         runtimeMode: "full-access",
       });
 
@@ -2105,7 +2183,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         provider: ProviderDriverKind.make("claudeAgent"),
         providerInstanceId: claudeAgentInstanceId,
         threadId,
-        cwd: "/tmp/project-provider-replacement",
+        cwd: fixtureCwd("project-provider-replacement"),
         runtimeMode: "full-access",
       });
 
@@ -2132,7 +2210,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         provider: ProviderDriverKind.make("codex"),
         providerInstanceId: codexInstanceId,
         threadId: asThreadId("thread-1"),
-        cwd: "/tmp/project-send-turn",
+        cwd: fixtureCwd("project-send-turn"),
         runtimeMode: "full-access",
       });
 
@@ -2157,7 +2235,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
           threadId?: string;
         };
         assert.equal(startPayload.provider, "codex");
-        assert.equal(startPayload.cwd, "/tmp/project-send-turn");
+        assert.equal(startPayload.cwd, fixtureCwd("project-send-turn"));
         assert.deepEqual(startPayload.resumeCursor, initial.resumeCursor);
         assert.equal(startPayload.threadId, initial.threadId);
       }
@@ -2173,7 +2251,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         provider: ProviderDriverKind.make("claudeAgent"),
         providerInstanceId: claudeAgentInstanceId,
         threadId: asThreadId("thread-claude-send-turn"),
-        cwd: "/tmp/project-claude-send-turn",
+        cwd: fixtureCwd("project-claude-send-turn"),
         modelSelection: createModelSelection(
           ProviderInstanceId.make("claudeAgent"),
           "claude-opus-4-6",
@@ -2204,7 +2282,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
           threadId?: string;
         };
         assert.equal(startPayload.provider, "claudeAgent");
-        assert.equal(startPayload.cwd, "/tmp/project-claude-send-turn");
+        assert.equal(startPayload.cwd, fixtureCwd("project-claude-send-turn"));
         assert.deepEqual(
           startPayload.modelSelection,
           createModelSelection(ProviderInstanceId.make("claudeAgent"), "claude-opus-4-6", [
@@ -2368,6 +2446,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         Layer.provide(runtimeRepositoryLayer),
       );
       const firstProviderLayer = makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
         Layer.provide(
           Layer.succeed(ProviderAdapterRegistry.ProviderAdapterRegistry, firstRegistry),
         ),
@@ -2389,7 +2468,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
           provider: ProviderDriverKind.make("claudeAgent"),
           providerInstanceId: claudeAgentInstanceId,
           threadId: asThreadId("thread-claude-start"),
-          cwd: "/tmp/project-claude-start",
+          cwd: fixtureCwd("project-claude-start"),
           runtimeMode: "full-access",
         });
       }).pipe(Effect.provide(firstProviderLayer));
@@ -2407,6 +2486,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         Layer.provide(runtimeRepositoryLayer),
       );
       const secondProviderLayer = makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
         Layer.provide(
           Layer.succeed(ProviderAdapterRegistry.ProviderAdapterRegistry, secondRegistry),
         ),
@@ -2430,7 +2510,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
           provider: ProviderDriverKind.make("claudeAgent"),
           providerInstanceId: claudeAgentInstanceId,
           threadId: initial.threadId,
-          cwd: "/tmp/project-claude-start",
+          cwd: fixtureCwd("project-claude-start"),
           runtimeMode: "full-access",
         });
       }).pipe(Effect.provide(secondProviderLayer));
@@ -2446,7 +2526,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
           threadId?: string;
         };
         assert.equal(startPayload.provider, "claudeAgent");
-        assert.equal(startPayload.cwd, "/tmp/project-claude-start");
+        assert.equal(startPayload.cwd, fixtureCwd("project-claude-start"));
         assert.deepEqual(startPayload.resumeCursor, initial.resumeCursor);
         assert.equal(startPayload.threadId, initial.threadId);
       }
@@ -2476,6 +2556,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
           Layer.provide(runtimeRepositoryLayer),
         );
         const firstProviderLayer = makeProviderServiceLive().pipe(
+          Layer.provide(NodeServices.layer),
           Layer.provide(
             Layer.succeed(ProviderAdapterRegistry.ProviderAdapterRegistry, firstRegistry),
           ),
@@ -2497,7 +2578,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
             provider: ProviderDriverKind.make("claudeAgent"),
             providerInstanceId: claudeAgentInstanceId,
             threadId: asThreadId("thread-claude-cwd"),
-            cwd: "/tmp/project-claude-cwd",
+            cwd: fixtureCwd("project-claude-cwd"),
             runtimeMode: "full-access",
           });
         }).pipe(Effect.provide(firstProviderLayer));
@@ -2510,6 +2591,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
           Layer.provide(runtimeRepositoryLayer),
         );
         const secondProviderLayer = makeProviderServiceLive().pipe(
+          Layer.provide(NodeServices.layer),
           Layer.provide(
             Layer.succeed(ProviderAdapterRegistry.ProviderAdapterRegistry, secondRegistry),
           ),
@@ -2548,7 +2630,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
             threadId?: string;
           };
           assert.equal(startPayload.provider, "claudeAgent");
-          assert.equal(startPayload.cwd, "/tmp/project-claude-cwd");
+          assert.equal(startPayload.cwd, fixtureCwd("project-claude-cwd"));
           assert.deepEqual(startPayload.resumeCursor, initial.resumeCursor);
           assert.equal(startPayload.threadId, initial.threadId);
         }
@@ -2742,7 +2824,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
         provider: ProviderDriverKind.make("claudeAgent"),
         providerInstanceId: claudeAgentInstanceId,
         threadId: asThreadId("thread-metrics"),
-        cwd: "/tmp/project",
+        cwd: fixtureCwd("project"),
         runtimeMode: "full-access",
       });
 
@@ -2820,7 +2902,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
           provider: ProviderDriverKind.make("claudeAgent"),
           providerInstanceId: claudeAgentInstanceId,
           threadId: asThreadId("thread-send-metrics"),
-          cwd: "/tmp/project-send-metrics",
+          cwd: fixtureCwd("project-send-metrics"),
           runtimeMode: "full-access",
         });
 
@@ -4155,7 +4237,7 @@ validation.layer("ProviderServiceLive validation", (it) => {
         provider: ProviderDriverKind.make("codex"),
         providerInstanceId: codexInstanceId,
         threadId: asThreadId("thread-missing"),
-        cwd: "/tmp/project",
+        cwd: fixtureCwd("project"),
         runtimeMode: "full-access",
       });
 
@@ -4204,7 +4286,7 @@ boundedListing.layer("ProviderServiceLive session listing", (it) => {
         provider: CODEX_DRIVER,
         providerInstanceId: codexInstanceId,
         threadId: activeSessionThreadId,
-        cwd: "/tmp/project-active-session",
+        cwd: fixtureCwd("project-active-session"),
         runtimeMode: "full-access",
       });
       listThreadIds.mockClear();
diff --git a/apps/server/src/provider/Layers/ProviderService.ts b/apps/server/src/provider/Layers/ProviderService.ts
index cf9d9b395d5b..b853d779763c 100644
--- a/apps/server/src/provider/Layers/ProviderService.ts
+++ b/apps/server/src/provider/Layers/ProviderService.ts
@@ -35,6 +35,7 @@ import { getModelSelectionStringOptionValue } from "@t3tools/shared/model";
 import * as DateTime from "effect/DateTime";
 import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import * as PubSub from "effect/PubSub";
@@ -55,8 +56,12 @@ import {
   providerTurnMetricAttributes,
   withMetrics,
 } from "../../observability/Metrics.ts";
-import { ProviderAdapterRequestError } from "../Errors.ts";
-import { type ProviderAdapterError, ProviderValidationError } from "../Errors.ts";
+import {
+  ProviderAdapterRequestError,
+  type ProviderAdapterError,
+  ProviderValidationError,
+  ProviderWorkspaceMissingError,
+} from "../Errors.ts";
 import type { ProviderAdapterShape } from "../Services/ProviderAdapter.ts";
 import * as ProviderAdapterRegistry from "../Services/ProviderAdapterRegistry.ts";
 import * as ProviderService from "../Services/ProviderService.ts";
@@ -322,6 +327,7 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
     options?.issueMcpCredential ?? McpSessionRegistry.issueActiveMcpCredential;
   const revokeMcpCredential =
     options?.revokeMcpCredential ?? McpSessionRegistry.revokeActiveMcpThread;
+  const fileSystem = yield* FileSystem.FileSystem;
   const runtimeEventPubSub = yield* PubSub.unbounded<ProviderRuntimeEvent>();
   const pendingCompactions = new Map<ThreadId, PendingCompaction>();
   const timedOutNativeCompactions = new Set<ThreadId>();
@@ -1235,6 +1241,20 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
                 : "none",
           "provider.cwd.effective": effectiveCwd ?? "",
         });
+        if (effectiveCwd !== undefined) {
+          // Fail fast with an actionable error when the workspace folder is
+          // gone (e.g. moved, deleted, or replaced by a plain file).
+          // Otherwise every adapter surfaces this as a misleading "failed to
+          // spawn <binary>" process error. Stat failures other than "missing"
+          // fall through to the adapter.
+          const workspaceIsDirectory = yield* fileSystem.stat(effectiveCwd).pipe(
+            Effect.map((workspaceStat) => workspaceStat.type === "Directory"),
+            Effect.catch((statError) => Effect.succeed(statError.reason._tag !== "NotFound")),
+          );
+          if (!workspaceIsDirectory) {
+            return yield* new ProviderWorkspaceMissingError({ threadId, cwd: effectiveCwd });
+          }
+        }
         const adapter = yield* registry.getByInstance(resolvedInstanceId);
         yield* clearTurnAnalyticsSession(resolvedInstanceId, threadId);
         yield* prepareMcpSession(threadId, resolvedInstanceId);

From b6f72681da394369274121c4d1216f5d64a7a4bb Mon Sep 17 00:00:00 2001
From: Felipe Franco <67972456+fe-franco@users.noreply.github.com>
Date: Fri, 4 Sep 2026 21:36:28 -0300
Subject: [PATCH 48/56] fix: stop favicon requests for private link hosts on
 web and mobile (#5838)

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: codex <codex@users.noreply.github.com>
Co-authored-by: Julius Marminge <julius0216@outlook.com>
Co-authored-by: Julius Marminge <51714798+juliusmarminge@users.noreply.github.com>
---
 .../src/features/threads/ThreadFeed.tsx       |  12 +-
 apps/web/src/browser/browserTargetResolver.ts | 156 +-----------------
 apps/web/src/components/ChatMarkdown.test.tsx |  31 ++++
 apps/web/src/components/ChatMarkdown.tsx      |   6 +-
 apps/web/src/lib/favicon.ts                   |  24 +--
 packages/shared/package.json                  |   4 +
 packages/shared/src/favicon.test.ts           |  46 +++++-
 packages/shared/src/favicon.ts                |  16 ++
 .../shared/src/hostClassification.test.ts     | 112 +++++++++++++
 packages/shared/src/hostClassification.ts     | 149 +++++++++++++++++
 10 files changed, 377 insertions(+), 179 deletions(-)
 create mode 100644 packages/shared/src/hostClassification.test.ts
 create mode 100644 packages/shared/src/hostClassification.ts

diff --git a/apps/mobile/src/features/threads/ThreadFeed.tsx b/apps/mobile/src/features/threads/ThreadFeed.tsx
index ab48046fbd96..360b980edc95 100644
--- a/apps/mobile/src/features/threads/ThreadFeed.tsx
+++ b/apps/mobile/src/features/threads/ThreadFeed.tsx
@@ -86,6 +86,7 @@ import { copyTextWithHaptic } from "../../lib/copyTextWithHaptic";
 import { tryOpenExternalUrl } from "../../lib/openExternalUrl";
 import { downloadAndShareAttachment } from "../../lib/attachmentDownload";
 import { hasWideMarkdownBlock } from "../../lib/wideMarkdownBlocks";
+import { faviconUrlForOrigin } from "@t3tools/shared/favicon";
 import {
   hasNativeSelectableMarkdownText,
   SelectableMarkdownText,
@@ -596,7 +597,8 @@ const MarkdownExternalLink = memo(function MarkdownExternalLink(props: {
   readonly href: string;
   readonly onPress: (href: string) => void;
 }) {
-  const [failed, setFailed] = useState(() => failedMarkdownFaviconHosts.has(props.host));
+  const [failedHost, setFailedHost] = useState<string | null>(null);
+  const faviconUrl = faviconUrlForOrigin(`https://${props.host}`);
 
   return (
     <NativeText
@@ -607,15 +609,17 @@ const MarkdownExternalLink = memo(function MarkdownExternalLink(props: {
         textDecorationLine: "none",
       }}
     >
-      {!failed ? (
+      {faviconUrl !== null &&
+      failedHost !== props.host &&
+      !failedMarkdownFaviconHosts.has(props.host) ? (
         <Image
           source={{
-            uri: `https://www.google.com/s2/favicons?domain=${encodeURIComponent(props.host)}&sz=32`,
+            uri: faviconUrl,
           }}
           style={[markdownLinkStyles.inlineIcon, markdownLinkStyles.favicon]}
           onError={() => {
             failedMarkdownFaviconHosts.add(props.host);
-            setFailed(true);
+            setFailedHost(props.host);
           }}
         />
       ) : (
diff --git a/apps/web/src/browser/browserTargetResolver.ts b/apps/web/src/browser/browserTargetResolver.ts
index c06c60b5f740..4acb1e2b487f 100644
--- a/apps/web/src/browser/browserTargetResolver.ts
+++ b/apps/web/src/browser/browserTargetResolver.ts
@@ -4,158 +4,16 @@ import type {
   PreviewUrlResolution,
 } from "@t3tools/contracts";
 import { isLoopbackHost, normalizePreviewUrl } from "@t3tools/shared/preview";
+import { isLocalLoopbackHost, isPrivateNetworkHost } from "@t3tools/shared/hostClassification";
 
 import { readPreparedConnection } from "~/state/session";
 
-export const normalizeHostname = (host: string): string =>
-  host
-    .toLowerCase()
-    .replace(/^\[|\]$/g, "")
-    .replace(/\.+$/u, "");
-
-const parseIpv4Address = (host: string): readonly number[] | null => {
-  const parts = normalizeHostname(host).split(".").map(Number);
-  return parts.length === 4 &&
-    parts.every((part) => Number.isInteger(part) && part >= 0 && part <= 255)
-    ? parts
-    : null;
-};
-
-const parseIpv4MappedIpv6Address = (host: string): readonly number[] | null => {
-  const normalized = normalizeHostname(host);
-  if (!normalized.startsWith("::ffff:")) return null;
-  const suffix = normalized.slice("::ffff:".length);
-  const dotted = parseIpv4Address(suffix);
-  if (dotted) return dotted;
-  const hextets = suffix.split(":");
-  if (hextets.length !== 2 || hextets.some((part) => !/^[\da-f]{1,4}$/u.test(part))) return null;
-  const high = Number.parseInt(hextets[0]!, 16);
-  const low = Number.parseInt(hextets[1]!, 16);
-  return [high >>> 8, high & 0xff, low >>> 8, low & 0xff];
-};
-
-const parseIpv6Address = (host: string): readonly number[] | null => {
-  const normalized = normalizeHostname(host);
-  if (!normalized.includes(":")) return null;
-  const halves = normalized.split("::");
-  if (halves.length > 2) return null;
-  const head = halves[0] ? halves[0].split(":") : [];
-  const tail = halves[1] ? halves[1].split(":") : [];
-  if ([...head, ...tail].some((part) => !/^[\da-f]{1,4}$/u.test(part))) return null;
-  const missing = 8 - head.length - tail.length;
-  if ((halves.length === 1 && missing !== 0) || (halves.length === 2 && missing < 1)) return null;
-  return [...head, ...Array.from({ length: missing }, () => "0"), ...tail].map((part) =>
-    Number.parseInt(part, 16),
-  );
-};
-
-const ipv6PrefixMatches = (
-  address: readonly number[],
-  prefix: readonly number[],
-  prefixLength: number,
-): boolean => {
-  const fullHextets = Math.floor(prefixLength / 16);
-  if (address.slice(0, fullHextets).some((part, index) => part !== prefix[index])) return false;
-  const remainingBits = prefixLength % 16;
-  if (remainingBits === 0) return true;
-  const mask = (0xffff << (16 - remainingBits)) & 0xffff;
-  return (address[fullHextets]! & mask) === (prefix[fullHextets]! & mask);
-};
-
-const isPrivateIpv4Address = (parts: readonly number[]): boolean =>
-  parts[0] === 0 ||
-  parts[0] === 10 ||
-  parts[0] === 127 ||
-  (parts[0] === 100 && parts[1]! >= 64 && parts[1]! <= 127) ||
-  (parts[0] === 172 && parts[1]! >= 16 && parts[1]! <= 31) ||
-  (parts[0] === 192 && parts[1] === 168) ||
-  (parts[0] === 169 && parts[1] === 254) ||
-  (parts[0] === 198 && parts[1]! >= 18 && parts[1]! <= 19);
-
-const isSpecialPurposeIpv4Address = (parts: readonly number[]): boolean =>
-  isPrivateIpv4Address(parts) ||
-  parts[0]! >= 224 ||
-  // Deliberately suppress the whole protocol-assignment block. IANA marks
-  // .9 and .10 globally reachable, but privacy-safe false negatives are
-  // preferable to disclosing another special-purpose address by mistake.
-  (parts[0] === 192 && parts[1] === 0 && parts[2] === 0) ||
-  (parts[0] === 192 && parts[1] === 0 && parts[2] === 2) ||
-  (parts[0] === 192 && parts[1] === 88 && parts[2] === 99) ||
-  (parts[0] === 198 && parts[1] === 51 && parts[2] === 100) ||
-  (parts[0] === 203 && parts[1] === 0 && parts[2] === 113);
-
-export const isLocalLoopbackHost = (host: string): boolean => {
-  const normalized = normalizeHostname(host);
-  if (normalized === "localhost" || normalized === "::1") return true;
-  return parseIpv4Address(normalized)?.[0] === 127;
-};
-
-export const isPrivateNetworkHost = (host: string): boolean => {
-  const normalized = normalizeHostname(host);
-  if (
-    normalized === "::" ||
-    isLocalLoopbackHost(normalized) ||
-    normalized.endsWith(".localhost") ||
-    normalized.endsWith(".local") ||
-    normalized === "home.arpa" ||
-    normalized.endsWith(".home.arpa") ||
-    (!normalized.includes(".") && !normalized.includes(":"))
-  ) {
-    return true;
-  }
-  if (normalized.endsWith(".ts.net")) return true;
-  const parts = parseIpv4Address(normalized) ?? parseIpv4MappedIpv6Address(normalized);
-  if (parts) return isPrivateIpv4Address(parts);
-  const firstIpv6Token = normalized.split(":", 1)[0] ?? "";
-  if (!normalized.includes(":") || !/^[\da-f]{1,4}$/u.test(firstIpv6Token)) return false;
-  const firstIpv6Hextet = Number.parseInt(firstIpv6Token, 16);
-  return (
-    Number.isInteger(firstIpv6Hextet) &&
-    ((firstIpv6Hextet & 0xfe00) === 0xfc00 || (firstIpv6Hextet & 0xffc0) === 0xfe80)
-  );
-};
-
-/** Whether a hostname is eligible to be disclosed to a public favicon provider. */
-export const isPublicFaviconHost = (host: string): boolean => {
-  // A single trailing dot is a valid absolute DNS name. Repeated trailing
-  // dots are malformed and can conceal legacy numeric forms such as 127.1.
-  if (host.endsWith("..")) return false;
-  const normalized = normalizeHostname(host);
-  if (isPrivateNetworkHost(normalized)) return false;
-  if (
-    [".alt", ".example", ".internal", ".invalid", ".onion", ".test"].some(
-      (suffix) => normalized === suffix.slice(1) || normalized.endsWith(suffix),
-    )
-  ) {
-    return false;
-  }
-  const ipv4 = parseIpv4Address(normalized) ?? parseIpv4MappedIpv6Address(normalized);
-  if (ipv4) return !isSpecialPurposeIpv4Address(ipv4);
-  if (!normalized.includes(":")) return true;
-  const ipv6 = parseIpv6Address(normalized);
-  if (!ipv6) return false;
-  if (ipv6PrefixMatches(ipv6, [0x0064, 0xff9b, 0, 0, 0, 0, 0, 0], 96)) {
-    const embeddedIpv4 = [ipv6[6]! >>> 8, ipv6[6]! & 0xff, ipv6[7]! >>> 8, ipv6[7]! & 0xff];
-    return !isSpecialPurposeIpv4Address(embeddedIpv4);
-  }
-  const first = ipv6[0]!;
-  if ((first & 0xe000) !== 0x2000) return false;
-  if (ipv6PrefixMatches(ipv6, [0x2001, 0, 0, 0, 0, 0, 0, 0], 23)) {
-    const publicProtocolAssignment =
-      (ipv6[1] === 1 &&
-        ipv6.slice(2, 7).every((part) => part === 0) &&
-        [1, 2, 3].includes(ipv6[7]!)) ||
-      ipv6PrefixMatches(ipv6, [0x2001, 3, 0, 0, 0, 0, 0, 0], 32) ||
-      ipv6PrefixMatches(ipv6, [0x2001, 4, 0x0112, 0, 0, 0, 0, 0], 48) ||
-      ipv6PrefixMatches(ipv6, [0x2001, 0x20, 0, 0, 0, 0, 0, 0], 28) ||
-      ipv6PrefixMatches(ipv6, [0x2001, 0x30, 0, 0, 0, 0, 0, 0], 28);
-    return publicProtocolAssignment;
-  }
-  if (ipv6PrefixMatches(ipv6, [0x2001, 0x0db8, 0, 0, 0, 0, 0, 0], 32)) return false;
-  if (ipv6PrefixMatches(ipv6, [0x2002, 0, 0, 0, 0, 0, 0, 0], 16)) return false;
-  if (first === 0x3fff && (ipv6[1]! & 0xf000) === 0) return false;
-  return true;
-};
+export {
+  normalizeHostname,
+  isLocalLoopbackHost,
+  isPrivateNetworkHost,
+  isPublicFaviconHost,
+} from "@t3tools/shared/hostClassification";
 
 const readEnvironmentUrl = (environmentId: EnvironmentId): URL => {
   const connection = readPreparedConnection(environmentId);
diff --git a/apps/web/src/components/ChatMarkdown.test.tsx b/apps/web/src/components/ChatMarkdown.test.tsx
index 18a6c5115eeb..28ac42888eef 100644
--- a/apps/web/src/components/ChatMarkdown.test.tsx
+++ b/apps/web/src/components/ChatMarkdown.test.tsx
@@ -72,6 +72,37 @@ function codeButton(renderer: ReactTestRenderer, label: string) {
   return button.props as ComponentProps<typeof Button>;
 }
 
+describe("ChatMarkdown favicon privacy", () => {
+  it("suppresses private link images while preserving public links across updates", async () => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    let renderer: ReactTestRenderer | undefined;
+    const markdown = (url: string) => <ChatMarkdown cwd="/tmp/project" text={`[Link](${url})`} />;
+    try {
+      await act(async () => {
+        renderer = create(markdown("https://github.com"));
+      });
+      expect(renderer!.root.findAllByType("img").map((image) => image.props.src)).toEqual([
+        "https://www.google.com/s2/favicons?domain=github.com&sz=32",
+      ]);
+      for (const url of ["http://192.168.1.10:8080", "http://localhost:3000", "http://home.arpa"]) {
+        await act(async () => {
+          renderer!.update(markdown(url));
+        });
+        expect(renderer!.root.findAllByType("img")).toHaveLength(0);
+      }
+      await act(async () => {
+        renderer!.update(markdown("https://github.com"));
+      });
+      expect(renderer!.root.findAllByType("img")).toHaveLength(1);
+    } finally {
+      await act(async () => {
+        renderer?.unmount();
+      });
+      vi.unstubAllGlobals();
+    }
+  });
+});
+
 describe("ChatMarkdown streaming", () => {
   it("preserves code controls and details without highlighting an unchanged fence again", async () => {
     const highlighter = await getSyntaxHighlighterPromise("text");
diff --git a/apps/web/src/components/ChatMarkdown.tsx b/apps/web/src/components/ChatMarkdown.tsx
index deaa68ebdaee..48fafbd0d76d 100644
--- a/apps/web/src/components/ChatMarkdown.tsx
+++ b/apps/web/src/components/ChatMarkdown.tsx
@@ -28,6 +28,7 @@ import type {
   ServerProviderSkill,
   ThreadLinkedPullRequest,
 } from "@t3tools/contracts";
+import { faviconUrlForOrigin } from "@t3tools/shared/favicon";
 import {
   isAtomCommandInterrupted,
   squashAtomCommandFailure,
@@ -1133,16 +1134,17 @@ const failedFaviconHosts = new Set<string>();
 
 const MarkdownLinkFavicon = memo(function MarkdownLinkFavicon({ host }: { host: string }) {
   const [failedHost, setFailedHost] = useState<string | null>(null);
+  const faviconUrl = faviconUrlForOrigin(`https://${host}`);
   return (
     <span
       className="ms-[0.25em] me-[0.2em] inline-flex size-[14px] [vertical-align:-0.125em]"
       aria-hidden
     >
-      {failedHost === host || failedFaviconHosts.has(host) ? (
+      {faviconUrl === null || failedHost === host || failedFaviconHosts.has(host) ? (
         <GlobeIcon className={MARKDOWN_LINK_FAVICON_CLASS_NAME} />
       ) : (
         <img
-          src={`https://www.google.com/s2/favicons?domain=${encodeURIComponent(host)}&sz=32`}
+          src={faviconUrl}
           alt=""
           loading="lazy"
           draggable={false}
diff --git a/apps/web/src/lib/favicon.ts b/apps/web/src/lib/favicon.ts
index b327146b60bf..c582e0441426 100644
--- a/apps/web/src/lib/favicon.ts
+++ b/apps/web/src/lib/favicon.ts
@@ -1,23 +1 @@
-import { isPublicFaviconHost } from "~/browser/browserTargetResolver";
-
-/**
- * Favicon helpers for the preview tab strip.
- *
- * Uses Google's s2 favicon endpoint (same approach as ami's tab strip).
- * Callers should always render a `<Globe />` fallback when the returned URL
- * fails to load via an `onError` handler.
- */
-const FAVICON_PROVIDER = "https://www.google.com/s2/favicons";
-
-export function faviconUrlForOrigin(rawUrl: string | null | undefined, size = 32): string | null {
-  if (!rawUrl) return null;
-  try {
-    const url = new URL(rawUrl);
-    if (!url.host) return null;
-    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
-    if (!isPublicFaviconHost(url.hostname)) return null;
-    return `${FAVICON_PROVIDER}?domain=${encodeURIComponent(url.host)}&sz=${size}`;
-  } catch {
-    return null;
-  }
-}
+export { faviconUrlForOrigin } from "@t3tools/shared/favicon";
diff --git a/packages/shared/package.json b/packages/shared/package.json
index efbc62320a52..fd932b8b146b 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -266,6 +266,10 @@
     "./nodeSqliteClient": {
       "types": "./src/nodeSqliteClient.ts",
       "import": "./src/nodeSqliteClient.ts"
+    },
+    "./hostClassification": {
+      "types": "./src/hostClassification.ts",
+      "import": "./src/hostClassification.ts"
     }
   },
   "scripts": {
diff --git a/packages/shared/src/favicon.test.ts b/packages/shared/src/favicon.test.ts
index c29727544efa..ce80a079b3fd 100644
--- a/packages/shared/src/favicon.test.ts
+++ b/packages/shared/src/favicon.test.ts
@@ -1,6 +1,50 @@
 import { describe, expect, it } from "@effect/vitest";
 
-import { explicitFaviconUrl, faviconUrlForPage, toolActivityFaviconUrl } from "./favicon.ts";
+import {
+  explicitFaviconUrl,
+  faviconUrlForOrigin,
+  faviconUrlForPage,
+  toolActivityFaviconUrl,
+} from "./favicon.ts";
+
+describe("faviconUrlForOrigin", () => {
+  it.each([
+    "http://192.168.1.10:8080",
+    "http://localhost:3000",
+    "http://home.arpa",
+    "https://printer.local.",
+    "https://api.internal",
+    "https://box.tailnet.ts.net",
+    "http://127.1",
+    "http://0x7f000001",
+    "http://[::]",
+    "http://[::1]",
+    "http://[::ffff:192.168.1.10]",
+    "http://[fd00::1]",
+    "http://[fe80::1]",
+    "http://100.64.0.1",
+    "http://198.51.100.1",
+    "http://[2001:db8::1]",
+    "http://service.test",
+    "http://private.onion",
+    "http://127.1..",
+  ])("does not disclose %s to the favicon provider", (origin) => {
+    expect(faviconUrlForOrigin(origin)).toBeNull();
+  });
+
+  it("keeps the public origin, port and requested size", () => {
+    expect(faviconUrlForOrigin("https://github.com:8443/pingdotgg/t3code?private=query", 64)).toBe(
+      "https://www.google.com/s2/favicons?domain=github.com%3A8443&sz=64",
+    );
+  });
+
+  it.each([null, undefined, "", "invalid URL", "file:///tmp/private", "data:text/plain,private"])(
+    "rejects an invalid or unsupported origin %s",
+    (origin) => {
+      expect(faviconUrlForOrigin(origin)).toBeNull();
+    },
+  );
+});
 
 describe("faviconUrlForPage", () => {
   it("uses the page origin instead of a third-party favicon service", () => {
diff --git a/packages/shared/src/favicon.ts b/packages/shared/src/favicon.ts
index 88bf46a985bc..a3286b28e99a 100644
--- a/packages/shared/src/favicon.ts
+++ b/packages/shared/src/favicon.ts
@@ -1,3 +1,5 @@
+import { isPublicFaviconHost } from "./hostClassification.ts";
+
 /**
  * Mirrors Codex's generic Browser Use fallback: ask the page origin for its
  * conventional favicon and let the image element fall back to a browser glyph.
@@ -79,3 +81,17 @@ export function toolActivityFaviconUrl(
     faviconUrlForPage(icon.pageUrl, size)
   );
 }
+
+/** Return a public favicon URL without disclosing private or reserved hosts. */
+export function faviconUrlForOrigin(rawUrl: string | null | undefined, size = 32): string | null {
+  if (!rawUrl) return null;
+  try {
+    const url = new URL(rawUrl);
+    if (!url.host) return null;
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    if (!isPublicFaviconHost(url.hostname)) return null;
+    return `https://www.google.com/s2/favicons?domain=${encodeURIComponent(url.host)}&sz=${size}`;
+  } catch {
+    return null;
+  }
+}
diff --git a/packages/shared/src/hostClassification.test.ts b/packages/shared/src/hostClassification.test.ts
new file mode 100644
index 000000000000..9fcb1a7667cb
--- /dev/null
+++ b/packages/shared/src/hostClassification.test.ts
@@ -0,0 +1,112 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { isPublicFaviconHost } from "./hostClassification.ts";
+
+describe("isPublicFaviconHost", () => {
+  it("treats public hosts as public", () => {
+    for (const host of [
+      "github.com",
+      "www.google.com",
+      "t3.chat",
+      "sub.domain.example.co.uk",
+      "8.8.8.8",
+      "1.1.1.1",
+      "100.200.1.1",
+      "172.32.0.1",
+      "192.167.1.1",
+      "11.0.0.1",
+    ]) {
+      expect(isPublicFaviconHost(host), host).toBe(true);
+    }
+  });
+
+  it("detects private IPv4 ranges", () => {
+    for (const host of [
+      "0.0.0.0",
+      "10.0.0.1",
+      "10.255.255.255",
+      "127.0.0.1",
+      "192.168.1.10",
+      "172.16.0.1",
+      "172.31.255.255",
+      "169.254.1.1",
+    ]) {
+      expect(isPublicFaviconHost(host), host).toBe(false);
+    }
+  });
+
+  it("detects the Tailscale 100.64.0.0/10 range", () => {
+    for (const host of ["100.64.0.1", "100.100.100.100", "100.126.17.15", "100.127.255.255"]) {
+      expect(isPublicFaviconHost(host), host).toBe(false);
+    }
+    expect(isPublicFaviconHost("100.63.255.255")).toBe(true);
+    expect(isPublicFaviconHost("100.128.0.1")).toBe(true);
+  });
+
+  it("detects private host names and suffixes", () => {
+    for (const host of [
+      "localhost",
+      "air",
+      "printer.local",
+      "api.internal",
+      "router.home.arpa",
+      "home.arpa",
+      "box.tailnet.ts.net",
+      "AIR.TAILE8BEA7.TS.NET",
+    ]) {
+      expect(isPublicFaviconHost(host), host).toBe(false);
+    }
+  });
+
+  it("detects private IPv6 addresses", () => {
+    for (const host of ["::1", "[::1]", "fd00::1", "fc00::1", "fe80::1", "FD12:3456::1"]) {
+      expect(isPublicFaviconHost(host), host).toBe(false);
+    }
+    expect(isPublicFaviconHost("2606:4700:4700::1111")).toBe(true);
+  });
+
+  it("detects IPv4-mapped IPv6 addresses in both spellings", () => {
+    for (const host of [
+      "::ffff:192.168.1.10",
+      "::ffff:10.0.0.1",
+      "::ffff:100.126.17.15",
+      "[::ffff:192.168.1.10]",
+      // c0a8:010a is 192.168.1.10, 0a00:0001 is 10.0.0.1.
+      "::ffff:c0a8:010a",
+      "::ffff:a00:1",
+    ]) {
+      expect(isPublicFaviconHost(host), host).toBe(false);
+    }
+    expect(isPublicFaviconHost("::ffff:8.8.8.8")).toBe(true);
+    expect(isPublicFaviconHost("::ffff:808:808")).toBe(true);
+  });
+
+  it("ignores a trailing DNS root label", () => {
+    for (const host of [
+      "localhost.",
+      "printer.local.",
+      "api.internal.",
+      "box.tailnet.ts.net.",
+      "air.",
+    ]) {
+      expect(isPublicFaviconHost(host), host).toBe(false);
+    }
+    expect(isPublicFaviconHost("github.com.")).toBe(true);
+  });
+
+  it("detects names under .localhost", () => {
+    for (const host of ["app.localhost", "api.app.localhost", "APP.LOCALHOST"]) {
+      expect(isPublicFaviconHost(host), host).toBe(false);
+    }
+  });
+
+  it("treats an empty host as private", () => {
+    expect(isPublicFaviconHost("")).toBe(false);
+    expect(isPublicFaviconHost("   ")).toBe(false);
+  });
+
+  it("rejects malformed IPv4 text as a public host", () => {
+    expect(isPublicFaviconHost("10.0.0.999")).toBe(true);
+    expect(isPublicFaviconHost("10.0.0")).toBe(true);
+  });
+});
diff --git a/packages/shared/src/hostClassification.ts b/packages/shared/src/hostClassification.ts
new file mode 100644
index 000000000000..7191fa78221f
--- /dev/null
+++ b/packages/shared/src/hostClassification.ts
@@ -0,0 +1,149 @@
+export const normalizeHostname = (host: string): string =>
+  host
+    .toLowerCase()
+    .replace(/^\[|\]$/g, "")
+    .replace(/\.+$/u, "");
+
+const parseIpv4Address = (host: string): readonly number[] | null => {
+  const parts = normalizeHostname(host).split(".").map(Number);
+  return parts.length === 4 &&
+    parts.every((part) => Number.isInteger(part) && part >= 0 && part <= 255)
+    ? parts
+    : null;
+};
+
+const parseIpv4MappedIpv6Address = (host: string): readonly number[] | null => {
+  const normalized = normalizeHostname(host);
+  if (!normalized.startsWith("::ffff:")) return null;
+  const suffix = normalized.slice("::ffff:".length);
+  const dotted = parseIpv4Address(suffix);
+  if (dotted) return dotted;
+  const hextets = suffix.split(":");
+  if (hextets.length !== 2 || hextets.some((part) => !/^[\da-f]{1,4}$/u.test(part))) return null;
+  const high = Number.parseInt(hextets[0]!, 16);
+  const low = Number.parseInt(hextets[1]!, 16);
+  return [high >>> 8, high & 0xff, low >>> 8, low & 0xff];
+};
+
+const parseIpv6Address = (host: string): readonly number[] | null => {
+  const normalized = normalizeHostname(host);
+  if (!normalized.includes(":")) return null;
+  const halves = normalized.split("::");
+  if (halves.length > 2) return null;
+  const head = halves[0] ? halves[0].split(":") : [];
+  const tail = halves[1] ? halves[1].split(":") : [];
+  if ([...head, ...tail].some((part) => !/^[\da-f]{1,4}$/u.test(part))) return null;
+  const missing = 8 - head.length - tail.length;
+  if ((halves.length === 1 && missing !== 0) || (halves.length === 2 && missing < 1)) return null;
+  return [...head, ...Array.from({ length: missing }, () => "0"), ...tail].map((part) =>
+    Number.parseInt(part, 16),
+  );
+};
+
+const ipv6PrefixMatches = (
+  address: readonly number[],
+  prefix: readonly number[],
+  prefixLength: number,
+): boolean => {
+  const fullHextets = Math.floor(prefixLength / 16);
+  if (address.slice(0, fullHextets).some((part, index) => part !== prefix[index])) return false;
+  const remainingBits = prefixLength % 16;
+  if (remainingBits === 0) return true;
+  const mask = (0xffff << (16 - remainingBits)) & 0xffff;
+  return (address[fullHextets]! & mask) === (prefix[fullHextets]! & mask);
+};
+
+const isPrivateIpv4Address = (parts: readonly number[]): boolean =>
+  parts[0] === 0 ||
+  parts[0] === 10 ||
+  parts[0] === 127 ||
+  (parts[0] === 100 && parts[1]! >= 64 && parts[1]! <= 127) ||
+  (parts[0] === 172 && parts[1]! >= 16 && parts[1]! <= 31) ||
+  (parts[0] === 192 && parts[1] === 168) ||
+  (parts[0] === 169 && parts[1] === 254) ||
+  (parts[0] === 198 && parts[1]! >= 18 && parts[1]! <= 19);
+
+const isSpecialPurposeIpv4Address = (parts: readonly number[]): boolean =>
+  isPrivateIpv4Address(parts) ||
+  parts[0]! >= 224 ||
+  // Deliberately suppress the whole protocol-assignment block. IANA marks
+  // .9 and .10 globally reachable, but privacy-safe false negatives are
+  // preferable to disclosing another special-purpose address by mistake.
+  (parts[0] === 192 && parts[1] === 0 && parts[2] === 0) ||
+  (parts[0] === 192 && parts[1] === 0 && parts[2] === 2) ||
+  (parts[0] === 192 && parts[1] === 88 && parts[2] === 99) ||
+  (parts[0] === 198 && parts[1] === 51 && parts[2] === 100) ||
+  (parts[0] === 203 && parts[1] === 0 && parts[2] === 113);
+
+export const isLocalLoopbackHost = (host: string): boolean => {
+  const normalized = normalizeHostname(host);
+  if (normalized === "localhost" || normalized === "::1") return true;
+  return parseIpv4Address(normalized)?.[0] === 127;
+};
+
+export const isPrivateNetworkHost = (host: string): boolean => {
+  const normalized = normalizeHostname(host);
+  if (
+    normalized === "::" ||
+    isLocalLoopbackHost(normalized) ||
+    normalized.endsWith(".localhost") ||
+    normalized.endsWith(".local") ||
+    normalized === "home.arpa" ||
+    normalized.endsWith(".home.arpa") ||
+    (!normalized.includes(".") && !normalized.includes(":"))
+  ) {
+    return true;
+  }
+  if (normalized.endsWith(".ts.net")) return true;
+  const parts = parseIpv4Address(normalized) ?? parseIpv4MappedIpv6Address(normalized);
+  if (parts) return isPrivateIpv4Address(parts);
+  const firstIpv6Token = normalized.split(":", 1)[0] ?? "";
+  if (!normalized.includes(":") || !/^[\da-f]{1,4}$/u.test(firstIpv6Token)) return false;
+  const firstIpv6Hextet = Number.parseInt(firstIpv6Token, 16);
+  return (
+    Number.isInteger(firstIpv6Hextet) &&
+    ((firstIpv6Hextet & 0xfe00) === 0xfc00 || (firstIpv6Hextet & 0xffc0) === 0xfe80)
+  );
+};
+
+/** Whether a hostname is eligible to be disclosed to a public favicon provider. */
+export const isPublicFaviconHost = (host: string): boolean => {
+  // A single trailing dot is a valid absolute DNS name. Repeated trailing
+  // dots are malformed and can conceal legacy numeric forms such as 127.1.
+  if (host.endsWith("..")) return false;
+  const normalized = normalizeHostname(host);
+  if (isPrivateNetworkHost(normalized)) return false;
+  if (
+    [".alt", ".example", ".internal", ".invalid", ".onion", ".test"].some(
+      (suffix) => normalized === suffix.slice(1) || normalized.endsWith(suffix),
+    )
+  ) {
+    return false;
+  }
+  const ipv4 = parseIpv4Address(normalized) ?? parseIpv4MappedIpv6Address(normalized);
+  if (ipv4) return !isSpecialPurposeIpv4Address(ipv4);
+  if (!normalized.includes(":")) return true;
+  const ipv6 = parseIpv6Address(normalized);
+  if (!ipv6) return false;
+  if (ipv6PrefixMatches(ipv6, [0x0064, 0xff9b, 0, 0, 0, 0, 0, 0], 96)) {
+    const embeddedIpv4 = [ipv6[6]! >>> 8, ipv6[6]! & 0xff, ipv6[7]! >>> 8, ipv6[7]! & 0xff];
+    return !isSpecialPurposeIpv4Address(embeddedIpv4);
+  }
+  const first = ipv6[0]!;
+  if ((first & 0xe000) !== 0x2000) return false;
+  if (ipv6PrefixMatches(ipv6, [0x2001, 0, 0, 0, 0, 0, 0, 0], 23)) {
+    const publicProtocolAssignment =
+      (ipv6[1] === 1 &&
+        ipv6.slice(2, 7).every((part) => part === 0) &&
+        [1, 2, 3].includes(ipv6[7]!)) ||
+      ipv6PrefixMatches(ipv6, [0x2001, 3, 0, 0, 0, 0, 0, 0], 32) ||
+      ipv6PrefixMatches(ipv6, [0x2001, 4, 0x0112, 0, 0, 0, 0, 0], 48) ||
+      ipv6PrefixMatches(ipv6, [0x2001, 0x20, 0, 0, 0, 0, 0, 0], 28) ||
+      ipv6PrefixMatches(ipv6, [0x2001, 0x30, 0, 0, 0, 0, 0, 0], 28);
+    return publicProtocolAssignment;
+  }
+  if (ipv6PrefixMatches(ipv6, [0x2001, 0x0db8, 0, 0, 0, 0, 0, 0], 32)) return false;
+  if (ipv6PrefixMatches(ipv6, [0x2002, 0, 0, 0, 0, 0, 0, 0], 16)) return false;
+  if (first === 0x3fff && (ipv6[1]! & 0xf000) === 0) return false;
+  return true;
+};

From 2d5464afbc19058be8c125d5ee70481d721d14f4 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 4 Sep 2026 17:39:11 -0700
Subject: [PATCH 49/56] fix(server): preserve native provider executable paths
 during updates (#9850)

---
 .../src/provider/providerMaintenance.test.ts  | 54 +++++++++++++++++--
 .../src/provider/providerMaintenance.ts       |  5 +-
 2 files changed, 53 insertions(+), 6 deletions(-)

diff --git a/apps/server/src/provider/providerMaintenance.test.ts b/apps/server/src/provider/providerMaintenance.test.ts
index 35d0c04bb08e..54ff1b599560 100644
--- a/apps/server/src/provider/providerMaintenance.test.ts
+++ b/apps/server/src/provider/providerMaintenance.test.ts
@@ -1,6 +1,7 @@
 // @effect-diagnostics nodeBuiltinImport:off
 import { expect, it } from "@effect/vitest";
 import * as NodeFS from "node:fs";
+import * as NodeChildProcess from "node:child_process";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import * as NodeOS from "node:os";
 import * as NodePath from "node:path";
@@ -8,6 +9,7 @@ import { ProviderDriverKind, ProviderInstanceId, type ServerProvider } from "@t3
 import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 import * as Crypto from "effect/Crypto";
 import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
 import { HttpClient } from "effect/unstable/http";
 import {
   createProviderVersionAdvisory,
@@ -362,9 +364,9 @@ it.layer(NodeServices.layer)("providerMaintenance", (it) => {
           provider: driver("nativePackageTool"),
           packageName: "@example/native-package-tool",
           update: {
-            command: "native-package-tool update",
+            command: `${nativePackageToolPath} update`,
 
-            executable: "native-package-tool",
+            executable: nativePackageToolPath,
 
             args: ["update"],
 
@@ -399,9 +401,9 @@ it.layer(NodeServices.layer)("providerMaintenance", (it) => {
           provider: driver("scopedPackageTool"),
           packageName: "@example/scoped-package-tool",
           update: {
-            command: "scoped-package-tool upgrade",
+            command: `${scopedPackageToolPath} upgrade`,
 
-            executable: "scoped-package-tool",
+            executable: scopedPackageToolPath,
 
             args: ["upgrade"],
 
@@ -411,6 +413,50 @@ it.layer(NodeServices.layer)("providerMaintenance", (it) => {
       }),
   );
 
+  it.effect.skipIf(windowsHost)("runs an explicit native updater outside PATH", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-native-update-" });
+      const nativeBinDir = NodePath.join(tempDir, "with spaces", ".scoped-package-tool", "bin");
+      yield* fs.makeDirectory(nativeBinDir, { recursive: true });
+      const binaryPath = NodePath.join(nativeBinDir, "scoped-package-tool");
+      yield* fs.writeFileString(binaryPath, "#!/bin/sh\nprintf '%s' \"$1\"\n");
+      yield* fs.chmod(binaryPath, 0o755);
+
+      const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(
+        scopedPackageToolUpdate,
+        { binaryPath, env: { PATH: "" } },
+      );
+      const update = capabilities.update;
+      expect(update).not.toBeNull();
+      if (!update) return;
+      const result = NodeChildProcess.spawnSync(update.executable, update.args, {
+        env: { PATH: "" },
+        encoding: "utf8",
+      });
+      expect(result.error).toBeUndefined();
+      expect(result.status).toBe(0);
+      expect(result.stdout).toBe("upgrade");
+    }).pipe(Effect.scoped),
+  );
+
+  it.each([
+    "/Users/example/.local/bin/native-package-tool",
+    "C:\\Users\\Example User\\.local\\bin\\native-package-tool.exe",
+  ])("preserves a configured native executable path: %s", (binaryPath) => {
+    expect(nativePackageToolUpdate.resolve({ binaryPath }).update?.executable).toBe(binaryPath);
+  });
+
+  it("uses the resolved launcher when its symlink target identifies a native install", () => {
+    const launcher = "/custom tools/native-launcher";
+    const capabilities = nativePackageToolUpdate.resolve({
+      binaryPath: launcher,
+      resolvedCommandPath: launcher,
+      realCommandPath: "/Users/example/.local/bin/native-package-tool",
+    });
+    expect(capabilities.update?.executable).toBe(launcher);
+  });
+
   it("switches native-package-tool to Homebrew updates when the binary resolves through Homebrew", () => {
     expect(
       nativePackageToolUpdate.resolve({
diff --git a/apps/server/src/provider/providerMaintenance.ts b/apps/server/src/provider/providerMaintenance.ts
index 14d17cf365c3..c7a0bb112b69 100644
--- a/apps/server/src/provider/providerMaintenance.ts
+++ b/apps/server/src/provider/providerMaintenance.ts
@@ -209,6 +209,7 @@ function makeHomebrewProviderMaintenanceCapabilities(
 
 function makeNativeProviderMaintenanceCapabilities(
   definition: PackageManagedProviderMaintenanceDefinition,
+  commandPath: string,
 ): ProviderMaintenanceCapabilities | null {
   if (!definition.nativeUpdate) {
     return null;
@@ -217,7 +218,7 @@ function makeNativeProviderMaintenanceCapabilities(
   return makeProviderMaintenanceCapabilities({
     provider: definition.provider,
     packageName: definition.npmPackageName,
-    updateExecutable: definition.nativeUpdate.executable,
+    updateExecutable: commandPath,
     updateArgs: definition.nativeUpdate.args,
     updateLockKey: definition.nativeUpdate.lockKey,
   });
@@ -297,7 +298,7 @@ export function resolvePackageManagedProviderMaintenance(
       commandPaths.some((commandPath) => nativeUpdate.isCommandPath(commandPath))
     ) {
       return (
-        makeNativeProviderMaintenanceCapabilities(definition) ??
+        makeNativeProviderMaintenanceCapabilities(definition, resolvedCommandPath) ??
         makeNpmGlobalProviderMaintenanceCapabilities(definition)
       );
     }

From 720e126b761ba0da112d8c68b589d20ab98a7eb0 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Fri, 4 Sep 2026 17:53:57 -0700
Subject: [PATCH 50/56] fix(web): restore composer expansion after tool calls
 (#9782)

---
 apps/web/src/components/ChatView.tsx          |  5 +
 apps/web/src/components/chat/ChatComposer.tsx | 36 +++++---
 .../components/chat/MessagesTimeline.test.tsx | 92 ++++++++++++++++++-
 .../src/components/chat/MessagesTimeline.tsx  | 71 +++++++++-----
 .../chat/useComposerFocusState.test.tsx       | 87 ++++++++++++++++++
 .../components/chat/useComposerFocusState.ts  | 23 +++++
 6 files changed, 274 insertions(+), 40 deletions(-)
 create mode 100644 apps/web/src/components/chat/useComposerFocusState.test.tsx
 create mode 100644 apps/web/src/components/chat/useComposerFocusState.ts

diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index cfbeb3aa7f72..b79c291fbdac 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -4757,6 +4757,10 @@ export default function ChatView(props: ChatViewProps) {
     requestAnimationFrame(() => positionAnchor(12));
   }, []);
 
+  const onToolOutputCollapsedAtEnd = useCallback(() => {
+    composerRef.current?.restoreAfterTimelineReachedEnd();
+  }, []);
+
   const onIsAtEndChange = useCallback((isAtEnd: boolean) => {
     if (
       !isAtEnd &&
@@ -7828,6 +7832,7 @@ export default function ChatView(props: ChatViewProps) {
                 contentInsetEndAdjustment={composerTimelineInset}
                 liveFollowEnabled={timelineLiveFollowEnabled}
                 onIsAtEndChange={onIsAtEndChange}
+                onToolOutputCollapsedAtEnd={onToolOutputCollapsedAtEnd}
                 onManualNavigation={cancelTimelineLiveFollowForUserNavigation}
                 hideEmptyPlaceholder={isDraftHeroState || threadDetailLoading}
                 topFadeEnabled={!hasTimelineTopBanner}
diff --git a/apps/web/src/components/chat/ChatComposer.tsx b/apps/web/src/components/chat/ChatComposer.tsx
index 5074d8a27c8e..2b19d6ec26ba 100644
--- a/apps/web/src/components/chat/ChatComposer.tsx
+++ b/apps/web/src/components/chat/ChatComposer.tsx
@@ -88,6 +88,7 @@ import {
 import { ComposerStashBadge } from "./ComposerStashBadge";
 import { ComposerStashMenu } from "./ComposerStashMenu";
 import { useComposerMenuState } from "./useComposerMenuState";
+import { useComposerFocusState } from "./useComposerFocusState";
 import {
   ComposerTasksBadge,
   ComposerTasksContent,
@@ -1104,7 +1105,7 @@ const ComposerFooterPrimaryActions = memo(function ComposerFooterPrimaryActions(
 export interface ChatComposerHandle {
   focusAtEnd: () => void;
   focusAt: (cursor: number) => void;
-  /** Undo only a scroll-triggered collapse when the timeline returns to its live edge. */
+  /** Expand the desktop composer at the timeline end without taking focus. */
   restoreAfterTimelineReachedEnd: () => void;
   addDroppedFiles: (files: File[]) => void;
   insertTextAtEnd: (text: string, options?: { ensureLeadingBoundary?: boolean }) => boolean;
@@ -1787,8 +1788,14 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
   const [isComposerFooterCompact, setIsComposerFooterCompact] = useState(false);
   const [isComposerPrimaryActionsCompact, setIsComposerPrimaryActionsCompact] = useState(false);
   const [isComposerModelPickerOpen, setIsComposerModelPickerOpen] = useState(false);
-  const [isComposerFocused, setIsComposerFocused] = useState(false);
-  const [isComposerScrollCollapsed, setIsComposerScrollCollapsed] = useState(false);
+  const isMobileViewport = useMediaQuery("max-sm");
+  const {
+    isComposerFocused,
+    setIsComposerFocused,
+    isComposerScrollCollapsed,
+    setIsComposerScrollCollapsed,
+    restoreAfterTimelineReachedEnd,
+  } = useComposerFocusState(isMobileViewport);
   const [composerSubmissionError, setComposerSubmissionError] = useState<string | null>(null);
   const [providerInputSubmissionError, setProviderInputSubmissionError] = useState<string | null>(
     null,
@@ -1800,7 +1807,6 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
     key: 0,
     active: false,
   });
-  const isMobileViewport = useMediaQuery("max-sm");
   const { active: panelAnimationsActive, durationMs: panelAnimationDurationMs } =
     usePanelAnimationSettings();
   const isComposerCollapsedMobile =
@@ -2351,7 +2357,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
     setComposerTrigger(detectComposerTrigger(promptRef.current, promptRef.current.length));
     setIsDragOverComposer(false);
     setIsComposerScrollCollapsed(false);
-  }, [draftId, activeThreadId, promptRef]);
+  }, [draftId, activeThreadId, promptRef, setIsComposerScrollCollapsed]);
 
   // ------------------------------------------------------------------
   // Footer compact layout observation
@@ -2502,7 +2508,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
       COMPOSER_SCROLL_GESTURE_RESET_MS,
     );
     setIsComposerScrollCollapsed(false);
-  }, []);
+  }, [setIsComposerScrollCollapsed]);
 
   const onPromptChange = useCallback(
     (
@@ -2789,7 +2795,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
       activeElement.blur();
     }
     setIsComposerFocused(false);
-  }, [isMobileViewport]);
+  }, [isMobileViewport, setIsComposerFocused]);
 
   const shouldBlurMobileComposerOnSubmit = useCallback(() => {
     if (!isMobileViewport) return false;
@@ -2949,7 +2955,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
         mobileComposerExpandInFlightRef.current = false;
       });
     });
-  }, []);
+  }, [setIsComposerFocused]);
 
   // ------------------------------------------------------------------
   // Callbacks: command key
@@ -3687,7 +3693,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
     if (!canScrollCollapseComposer) {
       setIsComposerScrollCollapsed(false);
     }
-  }, [canScrollCollapseComposer]);
+  }, [canScrollCollapseComposer, setIsComposerScrollCollapsed]);
 
   // Returning to the window re-fires focus on the element that already held
   // it. That focus arrives after the window's own event, so a window focus
@@ -3776,6 +3782,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
     canTrackComposerScrollGesture,
     getTimelineScrollableNode,
     isTimelineAtLogicalEnd,
+    setIsComposerScrollCollapsed,
   ]);
 
   const restingHiddenBlockCount = composerControlsInStrip ? restingControlsHiddenBlockCount : 0;
@@ -4365,7 +4372,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
       }
       setIsComposerFocused(false);
     });
-  }, [getTimelineScrollableNode, isMobileViewport]);
+  }, [getTimelineScrollableNode, isMobileViewport, setIsComposerFocused]);
 
   // A held collapse settles when the selection goes away, whether the user
   // clicked elsewhere, pressed Escape, or used the selection toolbar.
@@ -4457,7 +4464,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
       }
       desktopOutsidePointerInFlightRef.current = false;
     };
-  }, [isComposerFocused, isMobileViewport, scheduleComposerCollapseCheck]);
+  }, [isComposerFocused, isMobileViewport, scheduleComposerCollapseCheck, setIsComposerFocused]);
 
   useEffect(() => {
     return () => {
@@ -4486,7 +4493,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
       setIsComposerFocused(true);
     }
     setIsComposerModelPickerOpen(true);
-  }, [composerControlsHidden]);
+  }, [composerControlsHidden, setIsComposerFocused, setIsComposerScrollCollapsed]);
 
   useImperativeHandle(
     composerRef,
@@ -4497,9 +4504,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
       focusAt: (cursor: number) => {
         composerEditorRef.current?.focusAt(cursor);
       },
-      restoreAfterTimelineReachedEnd: () => {
-        setIsComposerScrollCollapsed(false);
-      },
+      restoreAfterTimelineReachedEnd,
       addDroppedFiles: (files: File[]) => {
         void addComposerAttachments(files);
         focusComposer();
@@ -4643,6 +4648,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
       interactionMode,
       planModeUiEnabled,
       compactThreadContext,
+      restoreAfterTimelineReachedEnd,
     ],
   );
 
diff --git a/apps/web/src/components/chat/MessagesTimeline.test.tsx b/apps/web/src/components/chat/MessagesTimeline.test.tsx
index cf2e79a78e53..16a0cbd83ce3 100644
--- a/apps/web/src/components/chat/MessagesTimeline.test.tsx
+++ b/apps/web/src/components/chat/MessagesTimeline.test.tsx
@@ -1,9 +1,12 @@
 import { CheckpointRef, EnvironmentId, MessageId, TurnId } from "@t3tools/contracts";
 import { codexFeedbackMessage } from "@t3tools/client-runtime/state/threads";
-import { createRef, type ReactNode, type Ref } from "react";
+import { act, createRef, useLayoutEffect, type ReactNode, type Ref } from "react";
 import { renderToStaticMarkup } from "react-dom/server";
+import { create, type ReactTestRenderer } from "react-test-renderer";
 import { beforeAll, describe, expect, it, vi } from "vite-plus/test";
 import type { LegendListRef, MaintainScrollAtEndOptions } from "@legendapp/list/react";
+import { shouldUseRestingComposerLayout } from "../composerFooterLayout";
+import { useComposerFocusState } from "./useComposerFocusState";
 
 vi.mock("@legendapp/list/react", async () => {
   const legendListTestId = "legend-list";
@@ -237,6 +240,93 @@ function buildAssistantTimelineEntry(text: string) {
 }
 
 describe("MessagesTimeline", () => {
+  it.each([
+    { toolLifecycleStatus: "inProgress", isAtEnd: true },
+    { toolLifecycleStatus: "inProgress", isAtEnd: false },
+    { toolLifecycleStatus: "completed", isAtEnd: true },
+    { toolLifecycleStatus: "completed", isAtEnd: false },
+  ] as const)(
+    "restores the composer after closing $toolLifecycleStatus tool output only at the end: $isAtEnd",
+    async ({ toolLifecycleStatus, isAtEnd }) => {
+      const frames = new Map<number, FrameRequestCallback>();
+      let nextFrame = 0;
+      vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => {
+        frames.set(++nextFrame, callback);
+        return nextFrame;
+      });
+      vi.stubGlobal("cancelAnimationFrame", (frame: number) => frames.delete(frame));
+      vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+      const flushFrame = () =>
+        act(() => {
+          const callbacks = [...frames.values()];
+          frames.clear();
+          callbacks.forEach((callback) => callback(0));
+        });
+      const props = buildProps();
+      let timelineIsAtEnd = isAtEnd;
+      props.listRef.current = {
+        getState: () => ({ isAtEnd: timelineIsAtEnd }),
+        getScrollableNode: () => null,
+      } as unknown as LegendListRef;
+      let isResting = true;
+      function ThreadProbe() {
+        const composer = useComposerFocusState(false);
+        useLayoutEffect(() => {
+          isResting = shouldUseRestingComposerLayout({
+            isExistingThread: true,
+            isMobileViewport: false,
+            isFocused: composer.isComposerFocused,
+            isScrollCollapsed: composer.isComposerScrollCollapsed,
+            hasExpandedChrome: false,
+            collapseOnBlur: true,
+          });
+        });
+        return (
+          <MessagesTimeline
+            {...props}
+            isWorking={toolLifecycleStatus === "inProgress"}
+            onToolOutputCollapsedAtEnd={composer.restoreAfterTimelineReachedEnd}
+            timelineEntries={[
+              {
+                id: "running-tool",
+                kind: "work",
+                createdAt: MESSAGE_CREATED_AT,
+                entry: {
+                  id: "running-tool",
+                  createdAt: MESSAGE_CREATED_AT,
+                  label: "Run command",
+                  tone: "tool",
+                  toolLifecycleStatus,
+                  detail: "Command output",
+                },
+              },
+            ]}
+          />
+        );
+      }
+      let renderer: ReactTestRenderer | undefined;
+      try {
+        await act(() => {
+          renderer = create(<ThreadProbe />);
+        });
+        const toggle = renderer!.root.findByProps({ "aria-expanded": false });
+        await act(() => toggle.props.onClick());
+        await flushFrame();
+        await flushFrame();
+        expect(isResting).toBe(true);
+
+        timelineIsAtEnd = false;
+        await act(() => toggle.props.onClick());
+        await flushFrame();
+        timelineIsAtEnd = isAtEnd;
+        await flushFrame();
+        expect(isResting).toBe(!isAtEnd);
+      } finally {
+        await act(() => renderer?.unmount());
+      }
+    },
+  );
+
   it("renders a feedback command and its pending response as normal thread messages", () => {
     const submission = {
       id: MessageId.make("feedback-command"),
diff --git a/apps/web/src/components/chat/MessagesTimeline.tsx b/apps/web/src/components/chat/MessagesTimeline.tsx
index 23807a3b0969..e399f38a01bd 100644
--- a/apps/web/src/components/chat/MessagesTimeline.tsx
+++ b/apps/web/src/components/chat/MessagesTimeline.tsx
@@ -206,7 +206,7 @@ interface TimelineRowSharedState {
   onOpenTurnDiff: (turnId: TurnId, filePath?: string) => void;
   onToggleTurnFold: (turnId: TurnId) => void;
   onToggleWorkGroup: (groupId: string, anchorKey: string) => void;
-  onToggleWorkEntry: (anchorKey: string) => void;
+  onToggleWorkEntry: (anchorKey: string, collapsed: boolean) => void;
   workGroupViewState: WorkGroupViewState;
   agentPanelModel: AgentPanelModel;
   onOpenAgents: () => void;
@@ -230,7 +230,7 @@ interface WorkGroupViewState {
 
 const WorkGroupViewCtx = createContext<{
   state: WorkGroupViewState;
-  onToggleEntry: () => void;
+  onToggleEntry: (collapsed: boolean) => void;
 } | null>(null);
 const TIMELINE_LIST_HEADER = <div className="h-3 sm:h-4" />;
 const TIMELINE_LIST_FADE_HEADER = (
@@ -333,6 +333,7 @@ interface MessagesTimelineProps {
    */
   liveFollowEnabled: boolean;
   onIsAtEndChange: (isAtEnd: boolean) => void;
+  onToolOutputCollapsedAtEnd?: () => void;
   onManualNavigation: () => void;
   hideEmptyPlaceholder?: boolean;
   topFadeEnabled?: boolean;
@@ -379,6 +380,7 @@ export const MessagesTimeline = memo(function MessagesTimeline({
   contentInsetEndAdjustment,
   liveFollowEnabled,
   onIsAtEndChange,
+  onToolOutputCollapsedAtEnd,
   onManualNavigation,
   hideEmptyPlaceholder = false,
   topFadeEnabled = false,
@@ -413,24 +415,32 @@ export const MessagesTimeline = memo(function MessagesTimeline({
     };
   }, []);
 
-  const suspendEndScrollMaintenanceForDisclosure = useCallback((anchorKey: string) => {
-    disclosureAnchorKeyRef.current = anchorKey;
-    setDisclosureToggleSettling(true);
-    if (disclosureSettleFrameRef.current !== null) {
-      cancelAnimationFrame(disclosureSettleFrameRef.current);
-    }
-    if (disclosureSettleSecondFrameRef.current !== null) {
-      cancelAnimationFrame(disclosureSettleSecondFrameRef.current);
-    }
-    disclosureSettleFrameRef.current = requestAnimationFrame(() => {
-      disclosureSettleSecondFrameRef.current = requestAnimationFrame(() => {
-        disclosureAnchorKeyRef.current = null;
-        setDisclosureToggleSettling(false);
-        disclosureSettleFrameRef.current = null;
-        disclosureSettleSecondFrameRef.current = null;
+  const suspendEndScrollMaintenanceForDisclosure = useCallback(
+    (anchorKey: string, collapsed = false) => {
+      disclosureAnchorKeyRef.current = anchorKey;
+      setDisclosureToggleSettling(true);
+      if (disclosureSettleFrameRef.current !== null) {
+        cancelAnimationFrame(disclosureSettleFrameRef.current);
+      }
+      if (disclosureSettleSecondFrameRef.current !== null) {
+        cancelAnimationFrame(disclosureSettleSecondFrameRef.current);
+      }
+      disclosureSettleFrameRef.current = requestAnimationFrame(() => {
+        disclosureSettleSecondFrameRef.current = requestAnimationFrame(() => {
+          disclosureAnchorKeyRef.current = null;
+          setDisclosureToggleSettling(false);
+          disclosureSettleFrameRef.current = null;
+          disclosureSettleSecondFrameRef.current = null;
+          // Wait for row measurement and the disclosure click's blur check.
+          // Closing output can reveal the end without a scroll event.
+          if (collapsed && resolveTimelineIsAtEnd(listRef.current?.getState()) === true) {
+            onToolOutputCollapsedAtEnd?.();
+          }
+        });
       });
-    });
-  }, []);
+    },
+    [listRef, onToolOutputCollapsedAtEnd],
+  );
 
   const shouldRestoreVisibleContentPosition = useCallback((row: MessagesTimelineRow) => {
     const disclosureAnchorKey = disclosureAnchorKeyRef.current;
@@ -463,7 +473,7 @@ export const MessagesTimeline = memo(function MessagesTimeline({
   );
   const onToggleWorkGroup = useCallback(
     (groupId: string, anchorKey: string) => {
-      suspendEndScrollMaintenanceForDisclosure(anchorKey);
+      suspendEndScrollMaintenanceForDisclosure(anchorKey, expandedWorkGroupIds.has(groupId));
       setExpandedWorkGroupIds((existing) => {
         const next = new Set(existing);
         if (next.has(groupId)) {
@@ -474,7 +484,7 @@ export const MessagesTimeline = memo(function MessagesTimeline({
         return next;
       });
     },
-    [suspendEndScrollMaintenanceForDisclosure],
+    [expandedWorkGroupIds, suspendEndScrollMaintenanceForDisclosure],
   );
 
   // An in-session interrupt leaves its turn expanded so the user keeps their
@@ -1727,7 +1737,11 @@ const WorkGroupSection = memo(function WorkGroupSection({
   isExpandedToolGroup: boolean;
   displayLabel?: string | undefined;
 }) {
-  const { workspaceRoot, routeThreadKey } = use(TimelineRowCtx);
+  const { workspaceRoot, routeThreadKey, onToggleWorkEntry } = use(TimelineRowCtx);
+  const onToggleStandaloneEntry = useCallback(
+    (collapsed: boolean) => onToggleWorkEntry(anchorKey, collapsed),
+    [anchorKey, onToggleWorkEntry],
+  );
   const nonEmptyEntries = useMemo(
     () => groupedEntries.filter((entry) => workEntryIsVisibleInGroup(entry, isExpandedToolGroup)),
     [groupedEntries, isExpandedToolGroup],
@@ -1755,6 +1769,7 @@ const WorkGroupSection = memo(function WorkGroupSection({
             workspaceRoot={workspaceRoot}
             isExpandedToolGroupEntry={false}
             displayLabel={displayLabel}
+            onToggleEntry={onToggleStandaloneEntry}
           />
         ))}
       </div>
@@ -1791,7 +1806,10 @@ function ExpandedWorkGroupEntries({
   }
 
   const groupView = useMemo(
-    () => ({ state: viewState, onToggleEntry: () => onToggleWorkEntry(anchorKey) }),
+    () => ({
+      state: viewState,
+      onToggleEntry: (collapsed: boolean) => onToggleWorkEntry(anchorKey, collapsed),
+    }),
     [anchorKey, onToggleWorkEntry, viewState],
   );
   const updateScrollFades = useCallback(() => {
@@ -3045,6 +3063,7 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
   workspaceRoot: string | undefined;
   isExpandedToolGroupEntry: boolean;
   displayLabel?: string | undefined;
+  onToggleEntry?: ((collapsed: boolean) => void) | undefined;
 }) {
   const { workEntry, workspaceRoot, isExpandedToolGroupEntry, displayLabel } = props;
   // Before any hooks: spawn CTA rows render their own component.
@@ -3057,6 +3076,7 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
       workspaceRoot={workspaceRoot}
       isExpandedToolGroupEntry={isExpandedToolGroupEntry}
       displayLabel={displayLabel}
+      onToggleEntry={props.onToggleEntry}
     />
   );
 });
@@ -3066,6 +3086,7 @@ const PlainWorkEntryRow = memo(function PlainWorkEntryRow(props: {
   workspaceRoot: string | undefined;
   isExpandedToolGroupEntry: boolean;
   displayLabel?: string | undefined;
+  onToggleEntry?: ((collapsed: boolean) => void) | undefined;
 }) {
   const { workEntry, workspaceRoot, isExpandedToolGroupEntry, displayLabel } = props;
   const { threadRef, onImageExpand } = use(TimelineRowCtx);
@@ -3076,9 +3097,11 @@ const PlainWorkEntryRow = memo(function PlainWorkEntryRow(props: {
   const toggleExpanded = () => {
     const next = !expanded;
     if (groupView) {
-      groupView.onToggleEntry();
+      groupView.onToggleEntry(!next);
       if (next) groupView.state.expandedEntries.add(workEntry.id);
       else groupView.state.expandedEntries.delete(workEntry.id);
+    } else {
+      props.onToggleEntry?.(!next);
     }
     setExpanded(next);
   };
diff --git a/apps/web/src/components/chat/useComposerFocusState.test.tsx b/apps/web/src/components/chat/useComposerFocusState.test.tsx
new file mode 100644
index 000000000000..e4bf38430e85
--- /dev/null
+++ b/apps/web/src/components/chat/useComposerFocusState.test.tsx
@@ -0,0 +1,87 @@
+import { act, useLayoutEffect } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+import { shouldUseRestingComposerLayout } from "../composerFooterLayout";
+import { useComposerFocusState } from "./useComposerFocusState";
+
+let root: Root;
+let composer: ReturnType<typeof useComposerFocusState>;
+let isResting: boolean;
+
+function ComposerProbe({ isMobileViewport = false }: { isMobileViewport?: boolean }) {
+  const state = useComposerFocusState(isMobileViewport);
+  useLayoutEffect(() => {
+    composer = state;
+    isResting = shouldUseRestingComposerLayout({
+      isExistingThread: true,
+      isMobileViewport,
+      isFocused: state.isComposerFocused,
+      isScrollCollapsed: state.isComposerScrollCollapsed,
+      hasExpandedChrome: false,
+      collapseOnBlur: true,
+    });
+  });
+  return null;
+}
+
+beforeEach(async () => {
+  // The probe has no DOM output, but ReactDOM needs an event target.
+  const document = {
+    nodeType: 9,
+    addEventListener() {},
+    removeEventListener() {},
+  };
+  const container = {
+    nodeType: 1,
+    tagName: "DIV",
+    namespaceURI: "http://www.w3.org/1999/xhtml",
+    ownerDocument: document,
+    addEventListener() {},
+    removeEventListener() {},
+  };
+  vi.stubGlobal("document", document);
+  vi.stubGlobal("window", { document, HTMLIFrameElement: EventTarget });
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  root = createRoot(container as unknown as HTMLElement);
+  await act(() => root.render(<ComposerProbe />));
+});
+
+afterEach(async () => {
+  await act(() => root.unmount());
+  vi.unstubAllGlobals();
+});
+
+describe("composer focus state", () => {
+  it("expands at the timeline end after a tool call takes focus", async () => {
+    await act(() => composer.setIsComposerFocused(true));
+    expect(isResting).toBe(false);
+
+    // A tool disclosure takes focus before the user scrolls through its output.
+    await act(() => composer.setIsComposerFocused(false));
+    expect(isResting).toBe(true);
+
+    await act(() => composer.restoreAfterTimelineReachedEnd());
+    expect(isResting).toBe(false);
+
+    await act(() => composer.setIsComposerFocused(false));
+    expect(isResting).toBe(true);
+  });
+
+  it("can collapse again on the next scroll after returning to the end", async () => {
+    await act(() => composer.setIsComposerScrollCollapsed(true));
+    expect(isResting).toBe(true);
+
+    await act(() => composer.restoreAfterTimelineReachedEnd());
+    expect(isResting).toBe(false);
+
+    await act(() => composer.setIsComposerScrollCollapsed(true));
+    expect(isResting).toBe(true);
+  });
+
+  it("does not expand the phone composer when the timeline reaches the end", async () => {
+    await act(() => root.render(<ComposerProbe isMobileViewport />));
+    await act(() => composer.restoreAfterTimelineReachedEnd());
+    expect(composer.isComposerFocused).toBe(false);
+  });
+});
diff --git a/apps/web/src/components/chat/useComposerFocusState.ts b/apps/web/src/components/chat/useComposerFocusState.ts
new file mode 100644
index 000000000000..c8858b33fa6b
--- /dev/null
+++ b/apps/web/src/components/chat/useComposerFocusState.ts
@@ -0,0 +1,23 @@
+import { useCallback, useState } from "react";
+
+export function useComposerFocusState(isMobileViewport: boolean) {
+  const [isComposerFocused, setIsComposerFocused] = useState(false);
+  const [isComposerScrollCollapsed, setIsComposerScrollCollapsed] = useState(false);
+
+  const restoreAfterTimelineReachedEnd = useCallback(() => {
+    setIsComposerScrollCollapsed(false);
+    // Restore the expanded layout after a timeline control takes focus too.
+    // This state holds the layout open without moving DOM focus to the editor.
+    if (!isMobileViewport) {
+      setIsComposerFocused(true);
+    }
+  }, [isMobileViewport]);
+
+  return {
+    isComposerFocused,
+    setIsComposerFocused,
+    isComposerScrollCollapsed,
+    setIsComposerScrollCollapsed,
+    restoreAfterTimelineReachedEnd,
+  };
+}

From 2dca7a1eddd27c823e4d9d0a316864c4ad9f95c5 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Fri, 4 Sep 2026 17:54:08 -0700
Subject: [PATCH 51/56] fix(client): explain possible network blocking for T3
 Connect (#9783)

---
 .../settings/ConnectionsSettings.tsx          |  4 +-
 .../src/authorization/service.ts              |  7 ++-
 .../src/connection/errors.test.ts             | 60 ++++++++++++++++++-
 .../client-runtime/src/connection/errors.ts   | 11 ++--
 .../src/connection/supervisor.test.ts         | 32 +++++++++-
 .../src/connection/supervisor.ts              |  8 ++-
 packages/client-runtime/src/errors/network.ts |  4 ++
 .../src/relay/discovery.test.ts               |  3 +-
 .../src/relay/managedRelay.test.ts            | 40 ++++++++++++-
 .../client-runtime/src/relay/managedRelay.ts  |  9 ++-
 .../client-runtime/src/rpc/session.test.ts    | 52 +++++++++-------
 packages/client-runtime/src/rpc/session.ts    | 25 +++++---
 12 files changed, 211 insertions(+), 44 deletions(-)
 create mode 100644 packages/client-runtime/src/errors/network.ts

diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index 1c4e034cf6a1..5a6f3ebd70b0 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -1524,7 +1524,9 @@ function SavedBackendListRow({
           ) : null}
           {environment.connection.error && !resumingServerUpdate ? (
             <p className="flex min-w-0 items-center gap-2 text-destructive text-xs">
-              <span className="truncate">{connectionStatusText(environment.connection)}</span>
+              <span className="min-w-0 break-words">
+                {connectionStatusText(environment.connection)}
+              </span>
               {errorTraceId ? (
                 <button
                   type="button"
diff --git a/packages/client-runtime/src/authorization/service.ts b/packages/client-runtime/src/authorization/service.ts
index d918dcf0613d..d7adc9a99db9 100644
--- a/packages/client-runtime/src/authorization/service.ts
+++ b/packages/client-runtime/src/authorization/service.ts
@@ -80,9 +80,10 @@ function mapDpopSocketError(error: RemoteEnvironmentAuthError | ConnectionAttemp
 
 const fetchDescriptor = Effect.fn("clientRuntime.connection.remote.fetchDescriptor")(function* (
   httpBaseUrl: string,
+  connectionMethod: ClientConnectionMethod,
 ) {
   return yield* fetchRemoteEnvironmentDescriptor({ httpBaseUrl }).pipe(
-    Effect.mapError(mapRemoteEnvironmentError),
+    Effect.mapError((error) => mapRemoteEnvironmentError(error, connectionMethod)),
   );
 });
 
@@ -119,7 +120,7 @@ export const make = Effect.gen(function* () {
         cachedDescriptor.validatedAtEpochMs + BEARER_DESCRIPTOR_CACHE_TTL_MS > now;
       const descriptor = canReuseDescriptor
         ? cachedDescriptor.descriptor
-        : yield* fetchDescriptor(input.httpBaseUrl).pipe(
+        : yield* fetchDescriptor(input.httpBaseUrl, input.connectionMethod).pipe(
             Effect.provideService(HttpClient.HttpClient, httpClient),
           );
       if (descriptor.environmentId !== input.expectedEnvironmentId) {
@@ -252,7 +253,7 @@ export const make = Effect.gen(function* () {
         "connection.remote_token_cache": "miss",
       });
       const bootstrap = yield* input.obtainBootstrap;
-      const descriptor = yield* fetchDescriptor(bootstrap.endpoint.httpBaseUrl).pipe(
+      const descriptor = yield* fetchDescriptor(bootstrap.endpoint.httpBaseUrl, "relay").pipe(
         Effect.provideService(HttpClient.HttpClient, httpClient),
         Effect.withSpan("environment.authorization.descriptor"),
       );
diff --git a/packages/client-runtime/src/connection/errors.test.ts b/packages/client-runtime/src/connection/errors.test.ts
index 771c9490ca3e..a892ceda7767 100644
--- a/packages/client-runtime/src/connection/errors.test.ts
+++ b/packages/client-runtime/src/connection/errors.test.ts
@@ -1,12 +1,40 @@
 import { EnvironmentAuthInvalidError } from "@t3tools/contracts";
-import { RelayAuthInvalidError } from "@t3tools/contracts/relay";
+import {
+  RelayAuthInvalidError,
+  RelayEnvironmentEndpointTimedOutError,
+} from "@t3tools/contracts/relay";
 import { describe, expect, it } from "@effect/vitest";
 
-import { mapManagedRelayError, mapRemoteDpopEnvironmentError } from "./errors.ts";
+import {
+  mapManagedRelayError,
+  mapRemoteDpopEnvironmentError,
+  mapRemoteEnvironmentError,
+} from "./errors.ts";
 import { DPOP_RETRY_HINT, DPOP_UNKNOWN_HINT } from "../relay/errorPresentation.ts";
 import { ManagedRelayRequestFailedError } from "../relay/managedRelay.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
+import { RemoteEnvironmentAuthFetchError, RemoteEnvironmentAuthTimeoutError } from "../rpc/http.ts";
 
 describe("mapManagedRelayError", () => {
+  it("keeps a timeout reported by the relay distinct from a local network failure", () => {
+    const relayError = new RelayEnvironmentEndpointTimedOutError({
+      code: "environment_endpoint_timed_out",
+      traceId: "trace-server-timeout",
+    });
+    const mapped = mapManagedRelayError(
+      new ManagedRelayRequestFailedError({
+        action: "connect relay environment",
+        cause: relayError,
+        relayError,
+      }),
+    );
+    expect(mapped).toMatchObject({
+      reason: "timeout",
+      detail: "Relay timed out while contacting the environment endpoint.",
+      traceId: "trace-server-timeout",
+    });
+  });
+
   it("presents clock skew as one possible cause for a generic DPoP error", () => {
     const mapped = mapManagedRelayError(
       new ManagedRelayRequestFailedError({
@@ -48,6 +76,34 @@ describe("mapManagedRelayError", () => {
 });
 
 describe("mapRemoteDpopEnvironmentError", () => {
+  it("keeps relay descriptor auth failures distinct from DPoP proof failures", () => {
+    const error = new EnvironmentAuthInvalidError({
+      code: "auth_invalid",
+      reason: "invalid_credential",
+      traceId: "trace-descriptor",
+    });
+    expect(mapRemoteEnvironmentError(error, "relay").message).toBe(
+      "The environment credential is invalid.",
+    );
+    expect(mapRemoteDpopEnvironmentError(error).message).toBe(
+      `The environment credential is invalid. ${DPOP_UNKNOWN_HINT}`,
+    );
+  });
+
+  it.each([
+    new RemoteEnvironmentAuthFetchError({
+      message: "Failed to fetch remote environment endpoint.",
+      cause: new TypeError("Failed to fetch"),
+    }),
+    new RemoteEnvironmentAuthTimeoutError("https://environment.example.test", 10_000),
+  ])("suggests another network when the relay endpoint cannot be reached: $_tag", (error) => {
+    const mapped = mapRemoteDpopEnvironmentError(error);
+    expect(mapped).toMatchObject({
+      _tag: "ConnectionTransientError",
+      detail: `${error.message} ${NETWORK_BLOCKING_HINT}`,
+    });
+  });
+
   it("does not present a generic environment auth error as confirmed clock skew", () => {
     const mapped = mapRemoteDpopEnvironmentError(
       new EnvironmentAuthInvalidError({
diff --git a/packages/client-runtime/src/connection/errors.ts b/packages/client-runtime/src/connection/errors.ts
index ed8a117a6f5c..be7a1822cbde 100644
--- a/packages/client-runtime/src/connection/errors.ts
+++ b/packages/client-runtime/src/connection/errors.ts
@@ -1,8 +1,9 @@
-import type { EnvironmentId } from "@t3tools/contracts";
+import type { ClientConnectionMethod, EnvironmentId } from "@t3tools/contracts";
 import type { RelayProtectedError } from "@t3tools/contracts/relay";
 import type { ManagedRelayClientError } from "../relay/managedRelay.ts";
 import { dpopFailureMessage, relayProtectedErrorMessage } from "../relay/errorPresentation.ts";
 import type { RemoteEnvironmentAuthError } from "../authorization/remote.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
 import {
   ConnectionBlockedError,
   type ConnectionAttemptError,
@@ -113,7 +114,9 @@ export function mapManagedRelayError(error: ManagedRelayClientError): Connection
 
 export function mapRemoteEnvironmentError(
   error: RemoteEnvironmentAuthError,
+  connectionMethod: ClientConnectionMethod = "direct",
 ): ConnectionAttemptError {
+  const networkHint = connectionMethod === "relay" ? ` ${NETWORK_BLOCKING_HINT}` : "";
   switch (error._tag) {
     case "EnvironmentAuthInvalidError":
       return new ConnectionBlockedError({
@@ -146,12 +149,12 @@ export function mapRemoteEnvironmentError(
     case "RemoteEnvironmentAuthTimeoutError":
       return new ConnectionTransientError({
         reason: "timeout",
-        detail: error.message,
+        detail: `${error.message}${networkHint}`,
       });
     case "RemoteEnvironmentAuthFetchError":
       return new ConnectionTransientError({
         reason: "network",
-        detail: error.message,
+        detail: `${error.message}${networkHint}`,
       });
     case "EnvironmentInternalError":
       return new ConnectionTransientError({
@@ -185,5 +188,5 @@ export function mapRemoteDpopEnvironmentError(
       traceId: error.traceId,
     });
   }
-  return mapRemoteEnvironmentError(error);
+  return mapRemoteEnvironmentError(error, "relay");
 }
diff --git a/packages/client-runtime/src/connection/supervisor.test.ts b/packages/client-runtime/src/connection/supervisor.test.ts
index 8f38633d55f6..f532e504605a 100644
--- a/packages/client-runtime/src/connection/supervisor.test.ts
+++ b/packages/client-runtime/src/connection/supervisor.test.ts
@@ -30,6 +30,7 @@ import {
 import * as RpcSession from "../rpc/session.ts";
 import * as EnvironmentSupervisor from "./supervisor.ts";
 import * as ConnectionWakeups from "./wakeups.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
 
 const TARGET = new PrimaryConnectionTarget({
   environmentId: EnvironmentId.make("environment-1"),
@@ -467,6 +468,35 @@ describe("EnvironmentSupervisor", () => {
     }).pipe(Effect.provide(TestClock.layer())),
   );
 
+  it.effect(
+    "shows a network hint for a stalled relay connection and clears it after recovery",
+    () =>
+      Effect.gen(function* () {
+        const harness = yield* makeHarness({
+          prepare: (attempt) =>
+            attempt === 1 ? Effect.never : Effect.succeed(PREPARED_CONNECTION),
+        });
+        const supervisor = yield* EnvironmentSupervisor.make(RELAY_ENTRY, {
+          initiallyDesired: true,
+        }).pipe(Effect.provide(harness.dependencies));
+
+        yield* awaitState(supervisor.state, (state) => state.phase === "connecting");
+        yield* TestClock.adjust("15 seconds");
+        const failed = yield* awaitState(supervisor.state, (state) => state.phase === "backoff");
+        expect(failed.lastFailure?.message).toBe(
+          `Test environment did not respond during connection setup. ${NETWORK_BLOCKING_HINT}`,
+        );
+
+        yield* TestClock.adjust("3 seconds");
+        const recovered = yield* awaitState(
+          supervisor.state,
+          (state) => state.phase === "connected",
+        );
+        expect(recovered.lastFailure).toBeNull();
+        expect(yield* Ref.get(harness.prepareCount)).toBe(2);
+      }).pipe(Effect.provide(TestClock.layer())),
+  );
+
   it.effect("converts unexpected driver defects into retryable failures", () =>
     Effect.gen(function* () {
       const harness = yield* makeHarness({
@@ -475,7 +505,7 @@ describe("EnvironmentSupervisor", () => {
             ? Effect.die(new Error("Native transport defect."))
             : Effect.succeed(PREPARED_CONNECTION),
       });
-      const supervisor = yield* EnvironmentSupervisor.make(TARGET_ENTRY, {
+      const supervisor = yield* EnvironmentSupervisor.make(RELAY_ENTRY, {
         initiallyDesired: true,
       }).pipe(Effect.provide(harness.dependencies));
 
diff --git a/packages/client-runtime/src/connection/supervisor.ts b/packages/client-runtime/src/connection/supervisor.ts
index 9d5452344499..0ff7b247a163 100644
--- a/packages/client-runtime/src/connection/supervisor.ts
+++ b/packages/client-runtime/src/connection/supervisor.ts
@@ -28,6 +28,7 @@ import {
 } from "./model.ts";
 import * as RpcSession from "../rpc/session.ts";
 import { safeErrorLogAttributes } from "../errors/safeLog.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
 import * as ConnectionWakeups from "./wakeups.ts";
 
 const RETRY_DELAYS_MS = [3_000, 4_000, 8_000, 16_000] as const;
@@ -241,6 +242,9 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
   | ConnectionWakeups.ConnectionWakeups
 > {
   const target = entry.target;
+  const setupTimeoutDetail = `${target.label} did not respond during connection setup.${
+    target._tag === "RelayConnectionTarget" ? ` ${NETWORK_BLOCKING_HINT}` : ""
+  }`;
   yield* annotateTarget(target);
 
   const connectivity = yield* Connectivity.Connectivity;
@@ -626,7 +630,7 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
       } else {
         replacementError = new ConnectionTransientError({
           reason: "timeout",
-          detail: `${target.label} did not respond during connection setup.`,
+          detail: setupTimeoutDetail,
         });
       }
 
@@ -708,7 +712,7 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
         failure: {
           error: new ConnectionTransientError({
             reason: "timeout",
-            detail: `${target.label} did not respond during connection setup.`,
+            detail: setupTimeoutDetail,
           }),
           attemptSpan: Option.none(),
         },
diff --git a/packages/client-runtime/src/errors/network.ts b/packages/client-runtime/src/errors/network.ts
new file mode 100644
index 000000000000..1e726bdd4d98
--- /dev/null
+++ b/packages/client-runtime/src/errors/network.ts
@@ -0,0 +1,4 @@
+// A failed request cannot distinguish filtering from an outage. Keep this a
+// possible cause, and suggest a way to check without changing server settings.
+export const NETWORK_BLOCKING_HINT =
+  "Your DNS or firewall may be blocking T3 Connect. Try another network, such as a phone hotspot.";
diff --git a/packages/client-runtime/src/relay/discovery.test.ts b/packages/client-runtime/src/relay/discovery.test.ts
index 8cb963000bd3..36dacf82648a 100644
--- a/packages/client-runtime/src/relay/discovery.test.ts
+++ b/packages/client-runtime/src/relay/discovery.test.ts
@@ -19,6 +19,7 @@ import * as Connectivity from "../connection/connectivity.ts";
 import { ConnectionBlockedError, type NetworkStatus } from "../connection/model.ts";
 import * as ConnectionWakeups from "../connection/wakeups.ts";
 import * as RelayEnvironmentDiscovery from "./discovery.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
 
 const environments = [
   {
@@ -305,7 +306,7 @@ describe("RelayEnvironmentDiscovery", () => {
         expect(Option.getOrThrow(state.error)).toMatchObject({
           _tag: "ConnectionTransientError",
           reason: "timeout",
-          message: "Relay environment listing timed out.",
+          message: `Relay environment listing timed out. ${NETWORK_BLOCKING_HINT}`,
         });
       }).pipe(Effect.provide(layer));
     }),
diff --git a/packages/client-runtime/src/relay/managedRelay.test.ts b/packages/client-runtime/src/relay/managedRelay.test.ts
index 4cba8064f207..2699c4ad0803 100644
--- a/packages/client-runtime/src/relay/managedRelay.test.ts
+++ b/packages/client-runtime/src/relay/managedRelay.test.ts
@@ -9,10 +9,15 @@ import * as Effect from "effect/Effect";
 import * as Fiber from "effect/Fiber";
 import * as Layer from "effect/Layer";
 import * as Tracer from "effect/Tracer";
+import * as Schema from "effect/Schema";
 import * as TestClock from "effect/testing/TestClock";
 
 import * as ManagedRelay from "./managedRelay.ts";
 import { remoteHttpClientLayer } from "../rpc/http.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
+
+const encodeRelayError = Schema.encodeEffect(ManagedRelay.ManagedRelayClientError);
+const decodeRelayError = Schema.decodeUnknownEffect(ManagedRelay.ManagedRelayClientError);
 
 function managedRelayTestLayer(
   fetchFn: typeof globalThis.fetch,
@@ -529,11 +534,44 @@ describe("ManagedRelayClient", () => {
         _tag: "ManagedRelayRequestTimeoutError",
         activity: "Relay environment listing",
         timeoutMs: ManagedRelay.MANAGED_RELAY_REQUEST_TIMEOUT_MS,
-        message: "Relay environment listing timed out.",
+        message: `Relay environment listing timed out. ${NETWORK_BLOCKING_HINT}`,
       });
     }).pipe(Effect.provide(Layer.merge(TestClock.layer(), managedRelayTestLayer(fetchFn))));
   });
 
+  it.effect("suggests checking network filtering when fetch fails without a response", () => {
+    const fetchFn = (() =>
+      Promise.reject(new TypeError("Failed to fetch"))) satisfies typeof globalThis.fetch;
+    return Effect.gen(function* () {
+      const relayClient = yield* ManagedRelay.ManagedRelayClient;
+      const error = yield* relayClient
+        .listEnvironments({ clerkToken: "clerk-token" })
+        .pipe(Effect.flip);
+      expect(error).toMatchObject({
+        _tag: "ManagedRelayRequestFailedError",
+        transportFailed: true,
+        message: `Could not list relay-managed environments. ${NETWORK_BLOCKING_HINT}`,
+      });
+      const encoded = yield* encodeRelayError(error);
+      const decoded = yield* decodeRelayError(encoded);
+      expect(decoded.message).toBe(error.message);
+    }).pipe(Effect.provide(managedRelayTestLayer(fetchFn)));
+  });
+
+  it.effect("does not suggest network filtering for an HTTP server error", () => {
+    const fetchFn = (() =>
+      Promise.resolve(
+        new Response("Unavailable", { status: 503 }),
+      )) satisfies typeof globalThis.fetch;
+    return Effect.gen(function* () {
+      const relayClient = yield* ManagedRelay.ManagedRelayClient;
+      const error = yield* relayClient
+        .listEnvironments({ clerkToken: "clerk-token" })
+        .pipe(Effect.flip);
+      expect(error.message).toBe("Could not list relay-managed environments.");
+    }).pipe(Effect.provide(managedRelayTestLayer(fetchFn)));
+  });
+
   it.effect("preserves typed relay trace IDs on client errors", () => {
     const fetchFn = (() =>
       Promise.resolve(
diff --git a/packages/client-runtime/src/relay/managedRelay.ts b/packages/client-runtime/src/relay/managedRelay.ts
index d74130322619..d9f81c356e22 100644
--- a/packages/client-runtime/src/relay/managedRelay.ts
+++ b/packages/client-runtime/src/relay/managedRelay.ts
@@ -44,6 +44,7 @@ import * as SynchronizedRef from "effect/SynchronizedRef";
 import * as HttpClientError from "effect/unstable/http/HttpClientError";
 import type * as HttpMethod from "effect/unstable/http/HttpMethod";
 import * as HttpApiClient from "effect/unstable/httpapi/HttpApiClient";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
 
 export interface ManagedRelayDpopProofInput {
   readonly method: HttpMethod.HttpMethod;
@@ -126,7 +127,7 @@ export class ManagedRelayRequestTimeoutError extends Schema.TaggedErrorClass<Man
   },
 ) {
   override get message(): string {
-    return `${this.activity} timed out.`;
+    return `${this.activity} timed out. ${NETWORK_BLOCKING_HINT}`;
   }
 }
 
@@ -145,13 +146,15 @@ export class ManagedRelayRequestFailedError extends Schema.TaggedErrorClass<Mana
   "ManagedRelayRequestFailedError",
   {
     action: ManagedRelayRequestAction,
+    transportFailed: Schema.optionalKey(Schema.Boolean),
     cause: Schema.Defect(),
     relayError: Schema.optional(RelayProtectedError),
     traceId: Schema.optional(Schema.String),
   },
 ) {
   override get message(): string {
-    return `Could not ${this.action}.`;
+    const message = `Could not ${this.action}.`;
+    return this.transportFailed ? `${message} ${NETWORK_BLOCKING_HINT}` : message;
   }
 }
 
@@ -307,6 +310,8 @@ function relayRequestError(action: ManagedRelayRequestAction) {
   return (cause: RelayHttpRequestError): ManagedRelayClientError =>
     new ManagedRelayRequestFailedError({
       action,
+      transportFailed:
+        HttpClientError.isHttpClientError(cause) && cause.reason._tag === "TransportError",
       cause,
       ...(isRelayProtectedError(cause) ? { relayError: cause, traceId: cause.traceId } : {}),
     });
diff --git a/packages/client-runtime/src/rpc/session.test.ts b/packages/client-runtime/src/rpc/session.test.ts
index f463ec280da1..8fe76e6181b8 100644
--- a/packages/client-runtime/src/rpc/session.test.ts
+++ b/packages/client-runtime/src/rpc/session.test.ts
@@ -30,6 +30,7 @@ import {
   ConnectionBlockedError,
   ConnectionTransientError,
   PrimaryConnectionTarget,
+  RelayConnectionTarget,
   type PreparedConnection,
 } from "../connection/model.ts";
 import * as EnvironmentSupervisor from "../connection/supervisor.ts";
@@ -37,6 +38,7 @@ import * as Persistence from "../platform/persistence.ts";
 import * as RpcSession from "./session.ts";
 import { makeEnvironmentServerConfigState } from "../state/server.ts";
 import { applyServerConfigProjection } from "../state/serverConfigProjection.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
 
 type SocketEventType = "open" | "message" | "close" | "error";
 type SocketEvent = {
@@ -1157,27 +1159,37 @@ describe("RpcSessionFactory", () => {
     ),
   );
 
-  it.effect("fails readiness when the websocket never opens", () =>
-    Effect.gen(function* () {
-      const { factory, sockets } = yield* makeFactory();
+  for (const relay of [false, true]) {
+    it.effect(`fails readiness when the ${relay ? "relay" : "direct"} websocket never opens`, () =>
+      Effect.gen(function* () {
+        const { factory, sockets } = yield* makeFactory();
 
-      const error = yield* Effect.scoped(
-        Effect.gen(function* () {
-          const session = yield* factory.connect(PREPARED);
-          const readyFiber = yield* Effect.forkChild(Effect.flip(session.ready));
-          yield* awaitSocket(sockets);
+        const error = yield* Effect.scoped(
+          Effect.gen(function* () {
+            const session = yield* factory.connect({
+              ...PREPARED,
+              target: relay
+                ? new RelayConnectionTarget({
+                    environmentId: TARGET.environmentId,
+                    label: TARGET.label,
+                  })
+                : TARGET,
+            });
+            const readyFiber = yield* Effect.forkChild(Effect.flip(session.ready));
+            yield* awaitSocket(sockets);
 
-          yield* TestClock.adjust("15 seconds");
-          return yield* Fiber.join(readyFiber);
-        }),
-      );
+            yield* TestClock.adjust("15 seconds");
+            return yield* Fiber.join(readyFiber);
+          }),
+        );
 
-      expect(error).toBeInstanceOf(ConnectionTransientError);
-      expect(error).toMatchObject({
-        reason: "transport",
-        message: "Test environment could not establish a WebSocket connection.",
-      });
-      expect(sockets[0]?.readyState).toBe(TestWebSocket.CLOSED);
-    }).pipe(Effect.provide(TestClock.layer())),
-  );
+        expect(error).toBeInstanceOf(ConnectionTransientError);
+        expect(error).toMatchObject({
+          reason: "transport",
+          message: `Test environment could not establish a WebSocket connection.${relay ? ` ${NETWORK_BLOCKING_HINT}` : ""}`,
+        });
+        expect(sockets[0]?.readyState).toBe(TestWebSocket.CLOSED);
+      }).pipe(Effect.provide(TestClock.layer())),
+    );
+  }
 });
diff --git a/packages/client-runtime/src/rpc/session.ts b/packages/client-runtime/src/rpc/session.ts
index d98a88100daa..aeef14968ff8 100644
--- a/packages/client-runtime/src/rpc/session.ts
+++ b/packages/client-runtime/src/rpc/session.ts
@@ -15,6 +15,7 @@ import * as Option from "effect/Option";
 import * as PubSub from "effect/PubSub";
 import * as Ref from "effect/Ref";
 import * as Schedule from "effect/Schedule";
+import * as Schema from "effect/Schema";
 import type * as Scope from "effect/Scope";
 import * as Stream from "effect/Stream";
 import type * as Rpc from "effect/unstable/rpc/Rpc";
@@ -24,6 +25,7 @@ import * as RpcSerialization from "effect/unstable/rpc/RpcSerialization";
 import * as Socket from "effect/unstable/socket/Socket";
 
 import { makeWsRpcProtocolClient, type WsRpcProtocolClient } from "./protocol.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
 import type {
   ConnectionAttemptError,
   ConnectionTransientError,
@@ -117,8 +119,11 @@ function serverConfigReplayEvents(
   ];
 }
 
+const isSocketErrorReason = Schema.is(Socket.SocketErrorReason);
+
 function mapSessionRpcError(
   error: InitialConfigError | ProbeError | ServerConfigSubscriptionError,
+  networkHint: string,
 ): ConnectionAttemptError {
   switch (error._tag) {
     case "EnvironmentAuthorizationError":
@@ -135,7 +140,7 @@ function mapSessionRpcError(
     case "RpcClientError":
       return new ConnectionTransientErrorClass({
         reason: "transport",
-        detail: error.message,
+        detail: `${error.message}${isSocketErrorReason(error.reason) ? networkHint : ""}`,
       });
   }
 }
@@ -150,6 +155,10 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
   };
 
   const connect = Effect.fnUntraced(function* (connection: PreparedConnection) {
+    const networkHint =
+      connection.target._tag === "RelayConnectionTarget" ? ` ${NETWORK_BLOCKING_HINT}` : "";
+    const mapRpcError = (error: Parameters<typeof mapSessionRpcError>[0]) =>
+      mapSessionRpcError(error, networkHint);
     yield* Effect.annotateCurrentSpan({
       "connection.environment.id": connection.environmentId,
     });
@@ -164,9 +173,11 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
             disconnected,
             new ConnectionTransientErrorClass({
               reason: "transport",
-              detail: wasConnected
-                ? `${connection.label} disconnected.`
-                : `${connection.label} could not establish a WebSocket connection.`,
+              detail: `${
+                wasConnected
+                  ? `${connection.label} disconnected.`
+                  : `${connection.label} could not establish a WebSocket connection.`
+              }${networkHint}`,
             }),
           ),
         ),
@@ -263,7 +274,7 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
         }
         return Effect.all([
           Deferred.failCause(serverConfigExit, exit.cause),
-          Deferred.failCause(configSubscriptionClosed, Cause.map(exit.cause, mapSessionRpcError)),
+          Deferred.failCause(configSubscriptionClosed, Cause.map(exit.cause, mapRpcError)),
         ]).pipe(Effect.asVoid);
       }),
     );
@@ -271,7 +282,7 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
     const initialConfig = Effect.raceFirst(
       Deferred.await(initialConfigDeferred),
       Deferred.await(serverConfigExit).pipe(
-        Effect.mapError(mapSessionRpcError),
+        Effect.mapError(mapRpcError),
         Effect.flatMap(() => Effect.fail(configSubscriptionEndedError)),
       ),
     ).pipe(Effect.withSpan("environment.initialSync"));
@@ -330,7 +341,7 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
         (config.environment.capabilities.connectionProbe === true
           ? protocolClient[WS_METHODS.serverProbe]({})
           : protocolClient[WS_METHODS.serverGetConfig]({})
-        ).pipe(Effect.mapError(mapSessionRpcError)),
+        ).pipe(Effect.mapError(mapRpcError)),
       ),
       Effect.asVoid,
       Effect.withSpan("clientRuntime.connection.rpcSession.probe"),

From b5fb3fba0fb3dbd1bc2e29886232321cc06863d5 Mon Sep 17 00:00:00 2001
From: maria <maria@kuuro.net>
Date: Fri, 4 Sep 2026 21:10:18 -0400
Subject: [PATCH 52/56] fix(desktop): isolate preview keyboard shortcuts from
 the host (#9840)

---
 apps/desktop/src/preview/Manager.test.ts | 83 ++++++++++++++++++++++++
 apps/desktop/src/preview/Manager.ts      | 51 ++-------------
 2 files changed, 87 insertions(+), 47 deletions(-)

diff --git a/apps/desktop/src/preview/Manager.test.ts b/apps/desktop/src/preview/Manager.test.ts
index a7b3afabd3c3..1eb65f0c7400 100644
--- a/apps/desktop/src/preview/Manager.test.ts
+++ b/apps/desktop/src/preview/Manager.test.ts
@@ -272,6 +272,7 @@ const makeTestPreviewWebContents = (
     ipc: { on: vi.fn(), off: vi.fn() },
     send: webviewSend,
     navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+    setIgnoreMenuShortcuts: vi.fn(),
     setWindowOpenHandler: vi.fn(),
     debugger: {
       isAttached: () => false,
@@ -382,6 +383,7 @@ const makeFaviconWebContents = (options?: {
     send: webviewSend,
     session: { fetch },
     navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+    setIgnoreMenuShortcuts: vi.fn(),
     setWindowOpenHandler: vi.fn(),
     executeJavaScriptInIsolatedWorld,
     debugger: {
@@ -474,6 +476,67 @@ describe("PreviewManager", () => {
     webviewSend.mockClear();
   });
 
+  effectIt.effect("keeps preview shortcuts out of the host window", () =>
+    withManager((manager) =>
+      Effect.gen(function* () {
+        const preview = makeFaviconWebContents();
+        const sendInputEvent = vi.fn();
+        const hostWebContents = { sendInputEvent };
+        Object.assign(preview.webContents, { hostWebContents });
+        fromId.mockReturnValue(preview.webContents);
+        yield* manager.setMainWindow({
+          isDestroyed: () => false,
+          once: vi.fn(),
+          webContents: hostWebContents,
+        } as never);
+        yield* manager.createTab("tab_keys");
+        yield* manager.registerWebview("tab_keys", 42);
+
+        expect(
+          (preview.webContents as Electron.WebContents).setIgnoreMenuShortcuts,
+        ).toHaveBeenCalledWith(true);
+        const beforeInput = preview.listeners.get("before-input-event")!;
+        for (const control of [false, true]) {
+          for (const key of ["k", ",", "w", "j", "q", "+", "a", "c", "v", "x"]) {
+            for (const type of ["keyDown", "keyUp"]) {
+              const preventDefault = vi.fn();
+              beforeInput(
+                { preventDefault } as never,
+                { type, key, meta: !control, control, shift: key === "j", alt: false } as never,
+              );
+              yield* Effect.yieldNow;
+              expect(preventDefault).not.toHaveBeenCalled();
+            }
+          }
+        }
+        expect(sendInputEvent).not.toHaveBeenCalled();
+
+        const preventDefault = vi.fn();
+        beforeInput(
+          { preventDefault } as never,
+          {
+            type: "keyDown",
+            key: "r",
+            meta: true,
+            control: false,
+            shift: false,
+            alt: false,
+          } as never,
+        );
+        yield* Effect.yieldNow;
+        expect(preventDefault).toHaveBeenCalledOnce();
+        expect(preview.reload).toHaveBeenCalledOnce();
+        expect(sendInputEvent).not.toHaveBeenCalled();
+
+        const setIgnoreMenuShortcuts = vi.fn();
+        preview.listeners.get("did-create-window")!({
+          webContents: { setIgnoreMenuShortcuts, setWindowOpenHandler: vi.fn() },
+        } as never);
+        expect(setIgnoreMenuShortcuts).toHaveBeenCalledWith(true);
+      }),
+    ),
+  );
+
   effectIt.effect("reports an unregistered webview as temporarily unavailable", () =>
     withManager((manager) =>
       Effect.gen(function* () {
@@ -617,6 +680,7 @@ describe("PreviewManager", () => {
           ipc: { on: vi.fn(), off: vi.fn() },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -718,6 +782,7 @@ describe("PreviewManager", () => {
           ipc: { on: vi.fn(), off: vi.fn() },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           get debugger() {
             if (destroyed) throw new Error("Object has been destroyed");
@@ -1222,6 +1287,7 @@ describe("PreviewManager", () => {
           ipc: { on: vi.fn(), off: vi.fn() },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -1286,6 +1352,7 @@ describe("PreviewManager", () => {
           ipc: { on: vi.fn(), off: vi.fn() },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -1326,6 +1393,7 @@ describe("PreviewManager", () => {
           ipc: { on: vi.fn(), off: vi.fn() },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -1372,6 +1440,7 @@ describe("PreviewManager", () => {
           ipc: { on: vi.fn(), off: vi.fn() },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -1427,6 +1496,7 @@ describe("PreviewManager", () => {
               ipc: { on: vi.fn(), off: vi.fn() },
               send: webviewSend,
               navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+              setIgnoreMenuShortcuts: vi.fn(),
               setWindowOpenHandler: vi.fn(),
               debugger: {
                 isAttached: () => false,
@@ -1524,6 +1594,7 @@ describe("PreviewManager", () => {
         ipc: { on: vi.fn(), off: vi.fn() },
         send: webviewSend,
         navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+        setIgnoreMenuShortcuts: vi.fn(),
         setWindowOpenHandler: vi.fn(),
         debugger: {
           isAttached: () => false,
@@ -1859,6 +1930,7 @@ describe("PreviewManager", () => {
           ipc: { on: vi.fn(), off: vi.fn() },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -1951,6 +2023,7 @@ describe("PreviewManager", () => {
           ipc: { on: vi.fn(), off: vi.fn() },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -2368,6 +2441,7 @@ describe("PreviewManager", () => {
             ipc: { on: vi.fn(), off: vi.fn() },
             send: webviewSend,
             navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+            setIgnoreMenuShortcuts: vi.fn(),
             setWindowOpenHandler: vi.fn(),
             debugger: {
               isAttached: () => false,
@@ -2670,6 +2744,7 @@ describe("PreviewManager", () => {
           ipc: { on: vi.fn(), off: vi.fn() },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -3173,6 +3248,7 @@ describe("PreviewManager", () => {
           ipc: { on: vi.fn(), off: vi.fn(), removeListener: vi.fn() },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -3228,6 +3304,7 @@ describe("PreviewManager", () => {
           },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -3304,6 +3381,7 @@ describe("PreviewManager", () => {
           },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -3389,6 +3467,7 @@ describe("PreviewManager", () => {
             goBack,
             goForward,
           },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -3518,6 +3597,7 @@ describe("PreviewManager", () => {
           },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -3618,6 +3698,7 @@ describe("PreviewManager", () => {
           },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -3773,6 +3854,7 @@ describe("PreviewManager", () => {
           },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -3837,6 +3919,7 @@ describe("PreviewManager", () => {
           ipc: { on: vi.fn(), off: vi.fn() },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
diff --git a/apps/desktop/src/preview/Manager.ts b/apps/desktop/src/preview/Manager.ts
index 324b92034f36..aa149bc9ee1d 100644
--- a/apps/desktop/src/preview/Manager.ts
+++ b/apps/desktop/src/preview/Manager.ts
@@ -465,22 +465,6 @@ interface ExpectedAgentInput {
   readonly expiresAt: number;
 }
 
-const APP_FORWARDED_SHORTCUTS: ReadonlyArray<{
-  key: string;
-  meta: boolean;
-  shift: boolean;
-  control: boolean;
-}> = Object.freeze([
-  // mod+shift+J → preview.toggle
-  { key: "j", meta: true, shift: true, control: false },
-  // mod+K → command palette
-  { key: "k", meta: true, shift: false, control: false },
-  // mod+, → settings (macOS convention)
-  { key: ",", meta: true, shift: false, control: false },
-  // mod+W → close tab/panel
-  { key: "w", meta: true, shift: false, control: false },
-]);
-
 /**
  * Protocols a preview page may open in a real popup window.
  *
@@ -1535,16 +1519,6 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
     }
   });
 
-  const isAppShortcut = (input: Electron.Input): boolean =>
-    input.type === "keyDown" &&
-    APP_FORWARDED_SHORTCUTS.some(
-      (shortcut) =>
-        shortcut.key.toLowerCase() === input.key.toLowerCase() &&
-        shortcut.meta === input.meta &&
-        shortcut.shift === input.shift &&
-        shortcut.control === input.control,
-    );
-
   const computeNavStatus = (wc: Electron.WebContents): PreviewNavStatus => {
     const url = wc.getURL();
     const title = wc.getTitle();
@@ -1819,30 +1793,11 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
         }).pipe(Effect.ignore),
       );
     };
-    const forwardShortcut = Effect.fn("PreviewManager.forwardShortcut")(function* (
-      event: Electron.Event,
-      input: Electron.Input,
-    ) {
-      const mainWindow = yield* Ref.get(mainWindowRef);
-      if (!isAppShortcut(input) || Option.isNone(mainWindow) || mainWindow.value.isDestroyed()) {
-        return;
-      }
-      event.preventDefault();
-      mainWindow.value.webContents.sendInputEvent({
-        type: "keyDown",
-        keyCode: input.key,
-        modifiers: [
-          ...(input.meta ? (["meta"] as const) : []),
-          ...(input.shift ? (["shift"] as const) : []),
-          ...(input.control ? (["control"] as const) : []),
-          ...(input.alt ? (["alt"] as const) : []),
-        ],
-      });
-    });
     // A popup opens with Electron's default handler, so the page inside it could
     // otherwise spawn native windows without limit. Nothing in an OAuth flow
     // opens a second popup, so the chain stops at the first one.
     const windowCreated = (window: Electron.BrowserWindow): void => {
+      window.webContents.setIgnoreMenuShortcuts(true);
       window.webContents.setWindowOpenHandler(() => ({ action: "deny" }));
     };
     const beforeInput = (event: Electron.Event, input: Electron.Input): void => {
@@ -1855,7 +1810,6 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
         );
         return;
       }
-      runFork(forwardShortcut(event, input));
     };
     yield* Scope.addFinalizer(
       scope,
@@ -1878,6 +1832,9 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
     );
     const install = Effect.fn("PreviewManager.installWebContentsListeners")(function* () {
       yield* attempt({ operation: "attachListeners", tabId, webContentsId: wc.id }, () => {
+        // Preview input belongs to the page, including keys injected through CDP.
+        // Never let it invoke the host application's menu accelerators.
+        wc.setIgnoreMenuShortcuts(true);
         wc.on("did-start-navigation", navigationStarted);
         wc.on("did-navigate", syncNavigation);
         wc.on("did-navigate-in-page", syncInPageNavigation);

From 110bbe6b55d684627a2481aebfd7c1ae3396011c Mon Sep 17 00:00:00 2001
From: maria <maria@kuuro.net>
Date: Fri, 4 Sep 2026 21:10:25 -0400
Subject: [PATCH 53/56] fix(prs): reuse GitHub data and defer optional reads
 (#9835)

---
 .../pullRequest/PullRequestService.test.ts    | 123 ++++++++++++++++++
 .../src/pullRequest/PullRequestService.ts     | 103 ++++++++++++---
 .../sourceControl/githubGraphQlBudget.test.ts |  25 +++-
 .../src/sourceControl/githubGraphQlBudget.ts  |  17 ++-
 .../pullRequest/PullRequestDetailPanel.tsx    |  50 +++----
 .../components/pullRequest/PullRequestRow.tsx |  70 +++++-----
 .../pullRequest/pullRequestList.logic.test.ts |  65 +++++++--
 .../pullRequest/pullRequestList.logic.ts      |  16 +--
 apps/web/src/routes/_chat.pull-requests.tsx   | 123 +++++++-----------
 apps/web/src/state/pullRequests.ts            |   6 +-
 .../client-runtime/src/state/pullRequests.ts  |   8 +-
 11 files changed, 420 insertions(+), 186 deletions(-)

diff --git a/apps/server/src/pullRequest/PullRequestService.test.ts b/apps/server/src/pullRequest/PullRequestService.test.ts
index 43ba73d325ef..eb2f913c9206 100644
--- a/apps/server/src/pullRequest/PullRequestService.test.ts
+++ b/apps/server/src/pullRequest/PullRequestService.test.ts
@@ -3057,6 +3057,114 @@ it.effect("fills in the line counts for the rows it is given", () =>
     ]);
   }),
 );
+it.effect(
+  "reuses counts across overlapping pages until expiry, explicit invalidation, or a reference changes",
+  () =>
+    Effect.gen(function* () {
+      const asked: number[][] = [];
+      const ref = (number: number) => ({
+        projectId: "p1" as ProjectId,
+        repository: "acme/web",
+        number,
+      });
+      const service = yield* makeService({
+        projects: [
+          project({ id: "p1", title: "web", workspaceRoot: "/a", repository: "acme/web" }),
+        ],
+        providers: [
+          fakeProvider("github", {
+            listChangeRequestStats: (input) => {
+              asked.push(input.changeRequests.map((ref) => ref.number));
+              return Effect.succeed(
+                input.changeRequests.map((ref) => ({ ...ref, additions: 12, deletions: 3 })),
+              );
+            },
+          }),
+        ],
+      });
+
+      yield* service.listStats({ refs: [ref(1), ref(2)] });
+      const overlapping = yield* service.listStats({ refs: [ref(2), ref(3)] });
+      assert.deepStrictEqual(
+        overlapping.stats.map((stat) => stat.number),
+        [2, 3],
+      );
+      yield* service.listStats({ refs: [ref(1), ref(2), ref(3)] });
+      assert.deepStrictEqual(asked, [[1, 2], [3]]);
+
+      yield* service.invalidate({ reference: ref(2) });
+      yield* service.listStats({ refs: [ref(1), ref(2), ref(3)] });
+      assert.deepStrictEqual(asked, [[1, 2], [3], [2]]);
+
+      yield* TestClock.adjust("61 seconds");
+      yield* service.listStats({ refs: [ref(1), ref(2), ref(3)] });
+      assert.deepStrictEqual(asked, [[1, 2], [3], [2], [1, 2, 3]]);
+
+      yield* service.refreshAfterTurn;
+      yield* service.listStats({ refs: [ref(1)] });
+      assert.deepStrictEqual(asked, [[1, 2], [3], [2], [1, 2, 3], [1]]);
+
+      yield* service.invalidate({});
+      yield* service.listStats({ refs: [ref(1)] });
+      assert.deepStrictEqual(asked, [[1, 2], [3], [2], [1, 2, 3], [1], [1]]);
+    }),
+);
+
+it.effect("reads the fresh diff when detail or summary discovers a changed revision", () =>
+  Effect.gen(function* () {
+    const summaryStarted = yield* Deferred.make<void>();
+    const releaseSummary = yield* Deferred.make<void>();
+    let revision = "2026-07-02T00:00:00Z";
+    let patch = "old patch";
+    let diffCalls = 0;
+    const reference = { projectId: "p1" as ProjectId, repository: "acme/web", number: 1 };
+    const service = yield* makeService({
+      projects: [project({ id: "p1", title: "web", workspaceRoot: "/a", repository: "acme/web" })],
+      providers: [
+        fakeProvider("github", {
+          getChangeRequest: () =>
+            Effect.sync(() => ({ ...hostedChangeRequest("body"), updatedAt: revision })),
+          getChangeRequestSummary: () =>
+            Effect.gen(function* () {
+              const result = changeRequest(1, revision);
+              yield* Deferred.succeed(summaryStarted, undefined);
+              yield* Deferred.await(releaseSummary);
+              return result;
+            }),
+          getDiff: () =>
+            Effect.sync(() => {
+              diffCalls += 1;
+              return { patch, truncated: false, nextCursor: null };
+            }),
+        }),
+      ],
+    });
+
+    const coldSummary = yield* service.summary(reference).pipe(Effect.forkChild());
+    yield* Deferred.await(summaryStarted);
+    yield* service.detail(reference);
+    assert.strictEqual((yield* service.diff(reference)).patch, "old patch");
+    revision = "2026-07-02T00:01:00Z";
+    patch = "new patch";
+    yield* TestClock.adjust("16 seconds");
+    yield* service.detail(reference);
+    yield* Effect.yieldNow;
+    assert.strictEqual((yield* service.detail(reference)).updatedAt, revision);
+    yield* Deferred.succeed(releaseSummary, undefined);
+    yield* Fiber.join(coldSummary);
+    yield* service.summary(reference, { recoverTransientFailure: false });
+    assert.strictEqual((yield* service.diff(reference)).patch, "new patch");
+    assert.strictEqual(diffCalls, 2);
+
+    revision = "2026-07-02T00:02:00Z";
+    patch = "summary-discovered patch";
+    yield* TestClock.adjust("61 seconds");
+    yield* service.summary(reference, { recoverTransientFailure: false });
+    assert.strictEqual((yield* service.diff(reference)).patch, patch);
+    assert.strictEqual(diffCalls, 3);
+  }),
+);
+
 it.effect("keeps the rows when the line counts cannot be read", () =>
   Effect.gen(function* () {
     const service = yield* makeService({
@@ -3080,6 +3188,7 @@ it.effect(
     Effect.gen(function* () {
       let coreCalls = 0;
       let activityCalls = 0;
+      let statsCalls = 0;
       const reference = { projectId: "p1" as ProjectId, repository: "acme/web", number: 1 };
       const service = yield* makeService({
         projects: [
@@ -3087,6 +3196,10 @@ it.effect(
         ],
         providers: [
           fakeProvider("github", {
+            listChangeRequestStats: () => {
+              statsCalls += 1;
+              return Effect.succeed([]);
+            },
             getChangeRequest: () => {
               coreCalls += 1;
               return Effect.succeed({
@@ -3126,6 +3239,16 @@ it.effect(
       assert.strictEqual(coreCalls, 1);
       assert.strictEqual(activityCalls, 0);
 
+      const counts = yield* service.listStats({ refs: [reference] });
+      assert.strictEqual(statsCalls, 0);
+      assert.deepStrictEqual(counts.stats, [
+        {
+          ...reference,
+          additions: core.additions,
+          deletions: core.deletions,
+        },
+      ]);
+
       yield* Effect.all([service.activity(reference), service.activity(reference)], {
         concurrency: 2,
       });
diff --git a/apps/server/src/pullRequest/PullRequestService.ts b/apps/server/src/pullRequest/PullRequestService.ts
index ceba7ce32e04..a8d3dc2fdeaf 100644
--- a/apps/server/src/pullRequest/PullRequestService.ts
+++ b/apps/server/src/pullRequest/PullRequestService.ts
@@ -2136,6 +2136,21 @@ export const make = Effect.gen(function* () {
     Math.max(turnRefreshEpoch, refEpochs.get(refScope(ref)) ?? 0);
   const refCacheKey = (ref: PullRequestRef) =>
     JSON.stringify([refEpoch(ref), ref.projectId, ref.repository, ref.number]);
+  // Counts belong to a PR, not a filtered page. Background reads and filter changes reuse
+  // them; explicit refreshes, mutations, and turns strand old and in-flight results.
+  const statsCacheKey = (key: string) => JSON.stringify([listingsEpoch, key]);
+  const recentStats = new Map<
+    string,
+    { readonly at: number; readonly value: PullRequestDiffStat }
+  >();
+  const recordStats = (key: string, value: PullRequestDiffStat, at: number) => {
+    recentStats.delete(key);
+    recentStats.set(key, { at, value });
+    if (recentStats.size > REF_EPOCH_CAPACITY) {
+      const oldest = recentStats.keys().next().value;
+      if (oldest !== undefined) recentStats.delete(oldest);
+    }
+  };
   const bumpRefEpoch = (ref: PullRequestRef) => {
     const scope = refScope(ref);
     if (!refEpochs.has(scope) && refEpochs.size >= REF_EPOCH_CAPACITY) {
@@ -2175,13 +2190,15 @@ export const make = Effect.gen(function* () {
   const summary: PullRequestService["Service"]["summary"] = (input, options) => {
     const key = refCacheKey(input);
     const cached = Cache.get(summaryCache, key);
-    if (options?.recoverTransientFailure !== false) {
-      return lastGoodSummary.serveHeld(key, cached, "reuse");
-    }
     const held = lastGoodSummary.peek(key);
-    return held?.state === "merged"
+    return held !== undefined &&
+      (options?.recoverTransientFailure !== false || held.state === "merged")
       ? Effect.succeed(held)
-      : cached.pipe(Effect.tap((value) => lastGoodSummary.record(key, value)));
+      : cached.pipe(
+          Effect.tap((value) =>
+            shouldReplaceHeldSummary(key, value) ? lastGoodSummary.record(key, value) : Effect.void,
+          ),
+        );
   };
 
   // Keys serialize positionally and parse back in the lookup, so the cache is the only holder
@@ -2263,8 +2280,25 @@ export const make = Effect.gen(function* () {
 
   const detailCache = yield* Cache.makeWith(
     (key: string) => {
+      const statsKey = statsCacheKey(key);
       const [, projectId, repository, number] = JSON.parse(key) as [number, string, string, number];
-      return detailUncached({ projectId, repository, number } as PullRequestRef);
+      return detailUncached({ projectId, repository, number } as PullRequestRef).pipe(
+        Effect.tap(
+          Effect.fn("PullRequestService.recordDetailStats")(function* (value: PullRequestDetail) {
+            recordStats(
+              statsKey,
+              {
+                projectId: value.projectId,
+                repository: value.repository,
+                number: value.number,
+                additions: value.additions,
+                deletions: value.deletions,
+              },
+              yield* Clock.currentTimeMillis,
+            );
+          }),
+        ),
+      );
     },
     {
       capacity: DETAIL_CACHE_CAPACITY,
@@ -2360,38 +2394,69 @@ export const make = Effect.gen(function* () {
       input.number,
       input.cursor ?? null,
       input.commit ?? null,
+      input.commit === undefined
+        ? (lastGoodSummary.peek(refCacheKey(input))?.updatedAt ?? null)
+        : null,
     ]);
     return staleDiff(key, Cache.get(diffCache, key));
   };
 
   const listStatsCache = yield* Cache.makeWith(
     (key: string) => {
-      const [, refs] = JSON.parse(key) as [number, ReadonlyArray<[string, string, number]>];
+      const [, refs] = JSON.parse(key) as [number, ReadonlyArray<[string, string, number, number]>];
       return listStatsUncached({
         refs: refs.map(([projectId, repository, number]) => ({ projectId, repository, number })),
-      } as unknown as PullRequestListStatsInput);
+      } as unknown as PullRequestListStatsInput).pipe(
+        Effect.flatMap((result) =>
+          Clock.currentTimeMillis.pipe(Effect.map((at) => ({ result, at }))),
+        ),
+      );
     },
     {
       capacity: LIST_STATS_CACHE_CAPACITY,
       timeToLive: (exit) => (Exit.isSuccess(exit) ? LIST_STATS_CACHE_TTL : Duration.zero),
     },
   );
-  // The stats read leans on the host's search API — the scarcest limit of them all — so it
-  // shares between clients like every other read. Refs are sorted so one page's worth of rows
-  // is one key however the client assembled them, and the listings epoch rides along so the
-  // refresh that forgets the listing forgets its decorations with it.
-  const listStats: PullRequestService["Service"]["listStats"] = (input) => {
-    if (input.refs.length === 0) return Effect.succeed({ stats: [] });
-    const key = JSON.stringify([
+  const statsBatchKey = (refs: Iterable<PullRequestRef>) =>
+    JSON.stringify([
       listingsEpoch,
-      input.refs
-        .map((ref) => [ref.projectId, ref.repository, ref.number] as const)
+      [...refs]
+        .map((ref) => [ref.projectId, ref.repository, ref.number, refEpoch(ref)] as const)
         .toSorted((left, right) =>
           `${left[0]} ${left[1]} ${left[2]}`.localeCompare(`${right[0]} ${right[1]} ${right[2]}`),
         ),
     ]);
-    return Cache.get(listStatsCache, key);
-  };
+  // Exact batches share in-flight reads; overlapping pages reuse each row already fetched.
+  const listStats: PullRequestService["Service"]["listStats"] = Effect.fn(
+    "PullRequestService.listStats",
+  )(function* (input: PullRequestListStatsInput) {
+    if (input.refs.length === 0) return { stats: [] };
+    const now = yield* Clock.currentTimeMillis;
+    const held: PullRequestDiffStat[] = [];
+    const missing = new Map<string, PullRequestRef>();
+    for (const ref of input.refs) {
+      const key = statsCacheKey(refCacheKey(ref));
+      const cached = recentStats.get(key);
+      if (cached !== undefined && now - cached.at < Duration.toMillis(LIST_STATS_CACHE_TTL)) {
+        held.push(cached.value);
+      } else {
+        missing.set(key, ref);
+      }
+    }
+    if (missing.size === 0) return { stats: held };
+    const key = statsBatchKey(missing.values());
+    const { result, at } = yield* Cache.get(listStatsCache, key);
+    for (const [key, ref] of missing) {
+      const stat = result.stats.find(
+        (stat) =>
+          stat.projectId === ref.projectId &&
+          stat.repository.toLowerCase() === ref.repository.toLowerCase() &&
+          stat.number === ref.number,
+      );
+      if (stat !== undefined) recordStats(key, stat, at);
+    }
+    return { stats: [...held, ...result.stats] };
+  });
 
   const invalidate: PullRequestService["Service"]["invalidate"] = (input) => {
     const reference = input.reference;
diff --git a/apps/server/src/sourceControl/githubGraphQlBudget.test.ts b/apps/server/src/sourceControl/githubGraphQlBudget.test.ts
index a166bf0dbbaf..a5b0680fafc5 100644
--- a/apps/server/src/sourceControl/githubGraphQlBudget.test.ts
+++ b/apps/server/src/sourceControl/githubGraphQlBudget.test.ts
@@ -9,11 +9,11 @@ const NEXT_RESET_AT = "2026-08-13T15:00:00.000Z";
 const BEFORE_RESET = Date.parse("2026-08-13T13:30:00.000Z");
 const AFTER_RESET = Date.parse("2026-08-13T14:00:01.000Z");
 
-function rateLimit(remaining: number, limit = 5_000, resetAt = RESET_AT): string {
+function rateLimit(remaining: number, limit = 5_000, resetAt = RESET_AT, cost = 14): string {
   return JSON.stringify({
     data: {
       viewer: { login: "bilal" },
-      rateLimit: { cost: 14, limit, remaining, resetAt },
+      rateLimit: { cost, limit, remaining, resetAt },
     },
   });
 }
@@ -86,6 +86,27 @@ describe("GitHub GraphQL budget", () => {
     }).pipe(Effect.provide(GitHubGraphQlBudget.layer)),
   );
 
+  it.effect("learns a cheaper observed cost without restoring reserved quota", () =>
+    Effect.gen(function* () {
+      yield* TestClock.setTime(BEFORE_RESET);
+      const budget = yield* GitHubGraphQlBudget.GitHubGraphQlBudget;
+      const query = "query { viewer { login } }";
+      yield* budget.observe("github.com", rateLimit(512, 5_000, RESET_AT, 8));
+      yield* budget.query("github.com", query);
+      // The admission reserved eight points, but the completed read only cost one.
+      yield* budget.observe("github.com", rateLimit(511, 5_000, RESET_AT, 1));
+
+      for (let count = 0; count < 4; count += 1) {
+        expect(yield* budget.query("github.com", query)).toContain("rateLimit");
+      }
+      const error = yield* Effect.flip(budget.query("github.com", query));
+      expect(error).toMatchObject({
+        _tag: "SourceControlRateLimitPausedError",
+        retryAt: Date.parse(RESET_AT),
+      });
+    }).pipe(Effect.provide(GitHubGraphQlBudget.layer)),
+  );
+
   it.effect("ignores a response from an older reset window", () =>
     Effect.gen(function* () {
       yield* TestClock.setTime(BEFORE_RESET);
diff --git a/apps/server/src/sourceControl/githubGraphQlBudget.ts b/apps/server/src/sourceControl/githubGraphQlBudget.ts
index 9c43de8e0586..9ece27547f5e 100644
--- a/apps/server/src/sourceControl/githubGraphQlBudget.ts
+++ b/apps/server/src/sourceControl/githubGraphQlBudget.ts
@@ -122,15 +122,20 @@ export const make = Effect.gen(function* () {
       const previous = current.get(key);
       // Concurrent reads can finish out of order. Quota only falls within one reset window, and
       // an answer from an older window must not replace the current one.
-      if (
-        previous !== undefined &&
-        (snapshot.resetAtMs < previous.resetAtMs ||
-          (snapshot.resetAtMs === previous.resetAtMs && snapshot.remaining >= previous.remaining))
-      ) {
+      if (previous !== undefined && snapshot.resetAtMs < previous.resetAtMs) {
         return current;
       }
       const next = new Map(current);
-      next.set(key, snapshot);
+      // Keep the conservative balance, but learn the observed cost even when our reservation
+      // was larger. Otherwise one expensive read makes every later cheap read spend its cost.
+      next.set(
+        key,
+        previous !== undefined &&
+          snapshot.resetAtMs === previous.resetAtMs &&
+          snapshot.remaining >= previous.remaining
+          ? { ...previous, cost: snapshot.cost }
+          : snapshot,
+      );
       return next;
     });
   });
diff --git a/apps/web/src/components/pullRequest/PullRequestDetailPanel.tsx b/apps/web/src/components/pullRequest/PullRequestDetailPanel.tsx
index 4a3af4b02c52..76e50b60003b 100644
--- a/apps/web/src/components/pullRequest/PullRequestDetailPanel.tsx
+++ b/apps/web/src/components/pullRequest/PullRequestDetailPanel.tsx
@@ -228,9 +228,8 @@ const TABS: ReadonlyArray<{ value: DetailTab; label: string }> = [
   { value: "code", label: "Code" },
 ];
 
-// The diff viewer pulls in its worker pool, so it stays out of the bundle until Code is opened.
-// Named rather than inlined so the panel can also call it itself, to start the download before
-// anyone has clicked the tab.
+// The diff viewer pulls in its worker pool, so load it only when the reader approaches Code.
+// Start the download on tab hover or focus, before the click, without loading it for every PR.
 const loadCodeTab = () => import("./PullRequestCodeTab");
 const PullRequestCodeTab = lazy(loadCodeTab);
 
@@ -524,14 +523,21 @@ export function PullRequestDetailPanel({
   // summary needs it too — a large description re-parses its whole markdown on every return
   // to the tab. `visibility` keeps boxes, sizes and scroll offsets, and takes hidden content
   // out of the tab order and the accessibility tree.
-  const [mountedTabs, setMountedTabs] = useState<ReadonlySet<DetailTab>>(
-    () => new Set<DetailTab>(["summary"]),
-  );
+  const tabScopeKey = `${environmentId}:${pullRequestKey}`;
+  const [tabMountState, setTabMountState] = useState(() => ({
+    key: tabScopeKey,
+    tabs: new Set<DetailTab>(["summary"]),
+  }));
+  // A previously visited Code tab must not fetch diffs for every later PR while hidden.
+  const mountedTabs =
+    tabMountState.key === tabScopeKey ? tabMountState.tabs : new Set<DetailTab>([tab]);
   useEffect(() => {
-    setMountedTabs((previous) =>
-      previous.has(tab) ? previous : new Set<DetailTab>(previous).add(tab),
-    );
-  }, [tab]);
+    setTabMountState((previous) => {
+      if (previous.key !== tabScopeKey) return { key: tabScopeKey, tabs: new Set([tab]) };
+      if (previous.tabs.has(tab)) return previous;
+      return { key: tabScopeKey, tabs: new Set(previous.tabs).add(tab) };
+    });
+  }, [tab, tabScopeKey]);
   const [chromeCondensed, setChromeCondensed] = useState(false);
   // Each mounted tab remembers its own scroll chrome; short tabs cannot scroll to reopen it.
   const chromeStateByTab = useRef<Partial<Record<DetailTab, boolean>>>({});
@@ -568,12 +574,6 @@ export function PullRequestDetailPanel({
   // Which handoff is preparing, keyed so a per-finding button can say "Preparing..." on itself
   // alone. One at a time whatever the key: they all check the same pull request out.
   const [handoff, setHandoff] = useState<string | null>(null);
-  // The chunk is fetched as soon as the panel exists rather than waiting for the Code tab to be
-  // clicked, so a reader who does click it lands on a chunk already in the module cache.
-  useEffect(() => {
-    void loadCodeTab();
-  }, []);
-
   const detailQuery = useEnvironmentQuery(
     pullRequestEnvironment.detail({ environmentId, input: reference }),
   );
@@ -699,12 +699,13 @@ export function PullRequestDetailPanel({
   );
   useEffect(() => {
     if (!coreDetail) return;
-    const next = { key: pullRequestKey, updatedAt: coreDetail.updatedAt };
+    const next = { key: tabScopeKey, updatedAt: coreDetail.updatedAt };
     if (shouldRefreshPullRequestActivity(activityRevision.current, next)) {
       activityQuery.refresh();
+      setRefreshToken((token) => token + 1);
     }
     activityRevision.current = next;
-  }, [activityQuery.refresh, coreDetail, pullRequestKey]);
+  }, [activityQuery.refresh, coreDetail, tabScopeKey]);
   useLayoutEffect(() => {
     if (!resolvedCoreDetail) return;
     onStateChange?.({
@@ -713,16 +714,14 @@ export function PullRequestDetailPanel({
       state: resolvedCoreDetail.state,
     });
   }, [onStateChange, resolvedCoreDetail]);
-  // Core detail is cheap enough to re-read while this stays open. Activity is heavier, so the
-  // revision effect above reads it only after this same pull request reports a change. Keyed by
+  // Reuse activity and diff until core detail reports a changed revision. Keyed by
   // the pull request rather than by the panel, because this one panel shows a different pull
   // request every time it is opened.
   useLiveRefresh(
     () => {
       detailQuery.refresh();
-      setRefreshToken((token) => token + 1);
     },
-    { key: `pull-request:${reference.projectId}:${reference.repository}#${reference.number}` },
+    { key: `pull-request:${environmentId}:${pullRequestKey}` },
   );
   // The button, on the other hand, goes around the server's cache rather than through it: it is
   // the answer for a reader who can see that what they are looking at is behind. The
@@ -2143,7 +2142,12 @@ export function PullRequestDetailPanel({
               }}
             >
               {visibleTabs.map((item) => (
-                <Toggle key={item.value} value={item.value}>
+                <Toggle
+                  key={item.value}
+                  value={item.value}
+                  onPointerEnter={item.value === "code" ? () => void loadCodeTab() : undefined}
+                  onFocus={item.value === "code" ? () => void loadCodeTab() : undefined}
+                >
                   {item.label}
                 </Toggle>
               ))}
diff --git a/apps/web/src/components/pullRequest/PullRequestRow.tsx b/apps/web/src/components/pullRequest/PullRequestRow.tsx
index 6ee686a9de7e..ae7aee0168f4 100644
--- a/apps/web/src/components/pullRequest/PullRequestRow.tsx
+++ b/apps/web/src/components/pullRequest/PullRequestRow.tsx
@@ -97,11 +97,11 @@ function PullRequestRowImpl({
       aria-current={selected ? "true" : undefined}
       onClick={() => onSelect(entry)}
       className={cn(
-        "grid w-full grid-cols-[auto_minmax(0,1fr)] items-center gap-3 rounded-lg px-3 py-2 text-left transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
+        "@container/pr-row grid w-full grid-cols-[auto_minmax(0,1fr)] items-center gap-3 rounded-lg px-3 py-3 text-left transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
         // Offscreen rows are skipped for style, layout and paint: a long list costs what the
         // viewport shows, not what the pages have loaded. The intrinsic size keeps the
         // scrollbar honest while a row is skipped.
-        "[contain-intrinsic-block-size:54px] [content-visibility:auto]",
+        "[contain-intrinsic-block-size:66px] [content-visibility:auto]",
         selected ? "bg-accent" : "hover:bg-accent/60",
       )}
     >
@@ -111,12 +111,36 @@ function PullRequestRowImpl({
         mergeability={entry.mergeability}
         baseBranch={entry.baseBranch}
       />
-      <span className="grid min-w-0 grid-cols-[minmax(0,1fr)_auto] items-center gap-x-3 gap-y-0.5">
+      <span className="grid min-w-0 grid-cols-[minmax(0,1fr)_auto] items-center gap-x-3 gap-y-1.5">
         <span className="col-start-1 row-start-1 block truncate text-sm font-medium text-foreground">
           {entry.title}
         </span>
-        <span className="col-start-2 row-start-1 justify-self-end whitespace-nowrap text-xs text-muted-foreground/70 tabular-nums">
-          {formatRelativeTimeLabel(entry.updatedAt)}
+        <span className="col-start-2 row-start-1 flex max-w-36 items-center justify-self-end gap-2 text-xs">
+          {/* Only a verdict somebody has actually given: "review required" is the absence of
+              one, and saying so on every unreviewed row would say nothing. */}
+          {entry.reviewDecision === "approved" || entry.reviewDecision === "changes-requested" ? (
+            <span
+              className={cn(
+                "sr-only @md/pr-row:not-sr-only @md/pr-row:min-w-0 @md/pr-row:truncate",
+                entry.reviewDecision === "approved"
+                  ? "text-emerald-600/90 dark:text-emerald-400/80"
+                  : "text-amber-600/90 dark:text-amber-400/80",
+              )}
+            >
+              {entry.reviewDecision === "approved" ? "Approved" : "Changes requested"}
+            </span>
+          ) : null}
+          {entry.checksState === undefined ? null : (
+            <PullRequestChecksPopover
+              checksState={entry.checksState}
+              environmentId={entry.environmentId}
+              reference={{
+                projectId: entry.projectId,
+                repository: entry.repository,
+                number: entry.number,
+              }}
+            />
+          )}
         </span>
         <PullRequestMetaLine className="@container/pr-row-meta col-start-1 row-start-2 overflow-hidden text-xs text-muted-foreground/70">
           {matchedElsewhere ? (
@@ -170,37 +194,13 @@ function PullRequestRowImpl({
             labelClassName="sr-only @xs/pr-row-meta:not-sr-only @xs/pr-row-meta:truncate"
           />
           {entry.labels.length > 0 ? <PullRequestRowLabels labels={entry.labels} /> : null}
-          {/* Only a verdict somebody has actually given: "review required" is the absence of
-              one, and saying so on every unreviewed row would say nothing. */}
-          {entry.reviewDecision === "approved" || entry.reviewDecision === "changes-requested" ? (
-            <span
-              className={cn(
-                "min-w-0 truncate",
-                entry.reviewDecision === "approved"
-                  ? "text-emerald-600/90 dark:text-emerald-400/80"
-                  : "text-amber-600/90 dark:text-amber-400/80",
-              )}
-            >
-              {entry.reviewDecision === "approved" ? "Approved" : "Changes requested"}
-            </span>
-          ) : null}
-          {entry.checksState === undefined ? null : (
-            <PullRequestChecksPopover
-              checksState={entry.checksState}
-              environmentId={entry.environmentId}
-              reference={{
-                projectId: entry.projectId,
-                repository: entry.repository,
-                number: entry.number,
-              }}
-            />
-          )}
         </PullRequestMetaLine>
-        <PullRequestDiffStat
-          additions={entry.additions}
-          deletions={entry.deletions}
-          className="col-start-2 row-start-2 justify-self-end text-xs"
-        />
+        <span className="col-start-2 row-start-2 flex items-center justify-self-end gap-3 whitespace-nowrap text-[11px] text-muted-foreground/70 tabular-nums">
+          <PullRequestDiffStat additions={entry.additions} deletions={entry.deletions} />
+          <span className="hidden @sm/pr-row:inline">
+            {formatRelativeTimeLabel(entry.updatedAt)}
+          </span>
+        </span>
       </span>
     </button>
   );
diff --git a/apps/web/src/components/pullRequest/pullRequestList.logic.test.ts b/apps/web/src/components/pullRequest/pullRequestList.logic.test.ts
index b3fc1da8d0a3..9b0043ef90b4 100644
--- a/apps/web/src/components/pullRequest/pullRequestList.logic.test.ts
+++ b/apps/web/src/components/pullRequest/pullRequestList.logic.test.ts
@@ -69,8 +69,30 @@ function entry(
 }
 
 describe("visible pull request line-count targets", () => {
+  it("reuses counts supplied by the listing and only requests missing counts", () => {
+    const entries = [
+      entry({ number: 1, additions: 12, deletions: 0 }),
+      entry({ number: 2, additions: 0, deletions: 7 }),
+      entry({ number: 3, additions: 0, deletions: 0 }),
+    ];
+    const entriesByKey = new Map(entries.map((item) => [pullRequestEntryKey(item), item]));
+    const keys = pullRequestStatsKeysToRequest(
+      entriesByKey,
+      new Set(entries.map(pullRequestEntryKey)),
+      [],
+      new Map(),
+    );
+
+    expect(pullRequestStatsBatches(entriesByKey, keys)[0]?.input.refs).toEqual([
+      { projectId: "project-1", repository: "pingdotgg/t3code", number: 3 },
+    ]);
+  });
+
   it("does not request a row again after its received batch is pruned", () => {
-    const entries = [entry({ number: 1 }), entry({ number: 2 })];
+    const entries = [
+      entry({ additions: 0, deletions: 0, number: 1 }),
+      entry({ additions: 0, deletions: 0, number: 2 }),
+    ];
     const entriesByKey = new Map(entries.map((item) => [pullRequestEntryKey(item), item]));
     const firstKey = pullRequestEntryKey(entries[0]!);
     const secondKey = pullRequestEntryKey(entries[1]!);
@@ -97,7 +119,9 @@ describe("visible pull request line-count targets", () => {
   });
 
   it("drops historical rows after a long scroll so refresh stays bounded to the viewport", () => {
-    const entries = Array.from({ length: 500 }, (_, index) => entry({ number: index + 1 }));
+    const entries = Array.from({ length: 500 }, (_, index) =>
+      entry({ additions: 0, deletions: 0, number: index + 1 }),
+    );
     const entriesByKey = new Map(entries.map((item) => [pullRequestEntryKey(item), item]));
     const batches = entries.map(
       (item) => pullRequestStatsBatches(entriesByKey, new Set([pullRequestEntryKey(item)]))[0]!,
@@ -112,7 +136,9 @@ describe("visible pull request line-count targets", () => {
   });
 
   it("keeps every per-environment batch within the stats contract limit", () => {
-    const entries = Array.from({ length: 501 }, (_, index) => entry({ number: index + 1 }));
+    const entries = Array.from({ length: 501 }, (_, index) =>
+      entry({ additions: 0, deletions: 0, number: index + 1 }),
+    );
     const entriesByKey = new Map(entries.map((item) => [pullRequestEntryKey(item), item]));
     const batches = pullRequestStatsBatches(
       entriesByKey,
@@ -125,9 +151,9 @@ describe("visible pull request line-count targets", () => {
 
   it("selects visible rows for date modes and every uncached row for size modes", () => {
     const entries = [
-      entry({ number: 1 }),
-      entry({ number: 2 }),
-      entry({ number: 3, environmentId: "env-2" as EnvironmentId }),
+      entry({ additions: 0, deletions: 0, number: 1 }),
+      entry({ additions: 0, deletions: 0, number: 2 }),
+      entry({ additions: 0, deletions: 0, number: 3, environmentId: "env-2" as EnvironmentId }),
     ];
     const entriesByKey = new Map(entries.map((item) => [pullRequestEntryKey(item), item]));
     const [firstKey, secondKey] = entries.map(pullRequestEntryKey);
@@ -162,7 +188,11 @@ describe("visible pull request line-count targets", () => {
   });
 
   it("refreshes only visible rows unless size sorting needs every loaded row", () => {
-    const entries = [entry({ number: 1 }), entry({ number: 2 }), entry({ number: 3 })];
+    const entries = [
+      entry({ additions: 0, deletions: 0, number: 1 }),
+      entry({ additions: 0, deletions: 0, number: 2 }),
+      entry({ additions: 0, deletions: 0, number: 3 }),
+    ];
     const entriesByKey = new Map(entries.map((item) => [pullRequestEntryKey(item), item]));
     const visibleKeys = new Set([pullRequestEntryKey(entries[1]!)]);
     const cachedStats = mergePullRequestDiffStats(
@@ -198,7 +228,10 @@ describe("visible pull request line-count targets", () => {
   });
 
   it("ignores a late refresh after the filter or stats policy changes", () => {
-    const entries = [entry({ number: 1 }), entry({ number: 2 })];
+    const entries = [
+      entry({ additions: 0, deletions: 0, number: 1 }),
+      entry({ additions: 0, deletions: 0, number: 2 }),
+    ];
     const entriesByKey = new Map(entries.map((item) => [pullRequestEntryKey(item), item]));
     const visibleKeys = new Set([pullRequestEntryKey(entries[1]!)]);
     const requestedScope = { key: "open", policy: "visible" } as const;
@@ -217,7 +250,10 @@ describe("visible pull request line-count targets", () => {
   });
 
   it("does not add request batches again while rows are active or cached", () => {
-    const entries = [entry({ number: 1 }), entry({ number: 2 })];
+    const entries = [
+      entry({ additions: 0, deletions: 0, number: 1 }),
+      entry({ additions: 0, deletions: 0, number: 2 }),
+    ];
     const entriesByKey = new Map(entries.map((item) => [pullRequestEntryKey(item), item]));
     const first = pullRequestStatsRequestBatches({
       entriesByKey,
@@ -724,7 +760,7 @@ describe("default merge-readiness ranking", () => {
     ]);
   });
 
-  it("puts the smallest measured change first inside a readiness tier", () => {
+  it("keeps readiness order stable when optional diff counts arrive", () => {
     const larger = entry({
       number: 1,
       checksState: "passing",
@@ -752,7 +788,14 @@ describe("default merge-readiness ranking", () => {
 
     expect(
       rankPullRequestsByMergeReadiness([larger, unknown, smaller]).map((row) => row.number),
-    ).toEqual([2, 1, 3]);
+    ).toEqual([3, 1, 2]);
+    expect(
+      rankPullRequestsByMergeReadiness([
+        larger,
+        { ...unknown, additions: 500, deletions: 200 },
+        smaller,
+      ]).map((row) => row.number),
+    ).toEqual([3, 1, 2]);
   });
 
   it("keeps authored work first and ranks each group by readiness", () => {
diff --git a/apps/web/src/components/pullRequest/pullRequestList.logic.ts b/apps/web/src/components/pullRequest/pullRequestList.logic.ts
index af1bd6ab4fbe..af71c934ad61 100644
--- a/apps/web/src/components/pullRequest/pullRequestList.logic.ts
+++ b/apps/web/src/components/pullRequest/pullRequestList.logic.ts
@@ -469,7 +469,11 @@ export function pullRequestStatsKeysToRequest(
     [...enteredKeys].filter((key) => {
       const entry = entriesByKey.get(key);
       return (
-        entry !== undefined && !requested.has(key) && !statsByRow.has(pullRequestDiffStatKey(entry))
+        entry !== undefined &&
+        entry.additions === 0 &&
+        entry.deletions === 0 &&
+        !requested.has(key) &&
+        !statsByRow.has(pullRequestDiffStatKey(entry))
       );
     }),
   );
@@ -1006,11 +1010,10 @@ export function rankPullRequestMatches<Entry extends PullRequestListEntry>(
  * verdict, then everything else still open. Drafts stay in that third tier because their author
  * has not made them mergeable yet. Finished work follows open work when all states are visible. A
  * known conflict is never ready, whatever its checks, review or state say, so it stays at the
- * bottom. Smaller measured changes come first within a tier; recency only breaks a remaining tie.
+ * bottom. Recency breaks ties, so optional diff counts never move the queue beneath the reader.
  */
 export function rankPullRequestsByMergeReadiness<Entry extends PullRequestListEntry>(
   entries: ReadonlyArray<Entry>,
-  hasMeasuredSize: (entry: Entry) => boolean = (entry) => entry.additions + entry.deletions > 0,
 ): ReadonlyArray<Entry> {
   const tier = (entry: Entry) => {
     if (entry.mergeability === "conflicting") return 4;
@@ -1023,10 +1026,7 @@ export function rankPullRequestsByMergeReadiness<Entry extends PullRequestListEn
   return entries.toSorted((left, right) => {
     const byTier = tier(left) - tier(right);
     if (byTier !== 0) return byTier;
-    const byMeasurement = Number(hasMeasuredSize(right)) - Number(hasMeasuredSize(left));
-    if (byMeasurement !== 0) return byMeasurement;
-    const bySize = left.additions + left.deletions - (right.additions + right.deletions);
-    return bySize !== 0 ? bySize : right.updatedAt.localeCompare(left.updatedAt);
+    return right.updatedAt.localeCompare(left.updatedAt);
   });
 }
 
@@ -1042,7 +1042,7 @@ export function sortPullRequestGroups<Entry extends PullRequestListEntry>(
 
   if (sort === "ready") {
     return searchText.trim().length === 0
-      ? sortWithinGroups((entries) => rankPullRequestsByMergeReadiness(entries, hasMeasuredSize))
+      ? sortWithinGroups(rankPullRequestsByMergeReadiness)
       : groups;
   }
   if (sort === "updated") return groups;
diff --git a/apps/web/src/routes/_chat.pull-requests.tsx b/apps/web/src/routes/_chat.pull-requests.tsx
index bcc22daa4a9d..48a558be8e0e 100644
--- a/apps/web/src/routes/_chat.pull-requests.tsx
+++ b/apps/web/src/routes/_chat.pull-requests.tsx
@@ -292,7 +292,7 @@ function PullRequestsRouteView() {
   const search = Route.useSearch();
   const sort = search.sort ?? "ready";
   const statsPolicy: PullRequestStatsPolicy =
-    sort === "ready" || sort === "largest" || sort === "smallest" ? "eager" : "visible";
+    sort === "largest" || sort === "smallest" ? "eager" : "visible";
   const navigate = useNavigate({ from: Route.fullPath });
   const keybindings = useAtomValue(primaryServerKeybindingsAtom);
   const { environments } = useEnvironments();
@@ -838,11 +838,7 @@ function PullRequestsRouteView() {
     } finally {
       setInvalidating(false);
     }
-    refreshList();
-    baselineQuery.refresh();
-    facetQuery.refresh();
-    authoredQuery.refresh();
-    reviewingQuery.refresh();
+    refreshList(true);
     const visible = visibleStatsKeys.current;
     const batches = pullRequestStatsRefreshBatches({
       requestedScope: requestedStatsScope,
@@ -955,7 +951,7 @@ function PullRequestsRouteView() {
         environmentKey,
         scope: scopeKey,
         query: sentQuery,
-        data,
+        data: { ...data, entries: ordered?.key === filterKey ? ordered.entries : data.entries },
         ...(partitions === undefined ? {} : { partitions }),
       };
     });
@@ -1017,7 +1013,7 @@ function PullRequestsRouteView() {
   // `ordered` is declared above, ahead of the snapshot write, but grown here from this round's
   // own answer.
   useEffect(() => {
-    if (!answered) return;
+    if (!answered || listQuery.isPending || (listQuery.error && listQuery.data === null)) return;
     setOrdered((previous) => {
       if (previous === null || previous.key !== filterKey) {
         return {
@@ -1045,7 +1041,15 @@ function PullRequestsRouteView() {
       // reads, so its order stands; a row that moved was updated, and moving is the news.
       return { key: filterKey, entries: rankPullRequestMatches(answered.entries, sentParsed.text) };
     });
-  }, [answered, filterKey, sentCursors, sentParsed.text]);
+  }, [
+    answered,
+    filterKey,
+    sentCursors,
+    sentParsed.text,
+    listQuery.isPending,
+    listQuery.error,
+    listQuery.data,
+  ]);
 
   // Carrying on where the last answer stopped, and only raising the page size for the hosts that
   // could not say where that was.
@@ -1081,11 +1085,20 @@ function PullRequestsRouteView() {
   // re-reads only its own slice, so the rows loaded before it would never see a merge, a close,
   // or a retitle. Going back to a single page long enough to cover everything on screen lets the
   // merge above bring every row up to date in place.
-  const refreshList = () => {
+  const refreshList = (includeRelated = false) => {
+    const related = includeRelated
+      ? [
+          ...baselineTargets,
+          ...facetTargets,
+          ...partitionTargets.authored,
+          ...partitionTargets.reviewing,
+        ]
+      : [];
     if (sentCursors === null) {
-      listQuery.refresh();
+      listQuery.refresh([...listTargets, ...related]);
       return;
     }
+    if (related.length > 0) listQuery.refresh(related);
     const loadedCount = ordered?.key === filterKey ? ordered.entries.length : pageSize;
     setPage({
       key: filterKey,
@@ -1117,9 +1130,7 @@ function PullRequestsRouteView() {
   // host's rate limit.
   useLiveRefresh(
     () => {
-      refreshList();
-      authoredQuery.refresh();
-      reviewingQuery.refresh();
+      refreshList(true);
     },
     { enabled: pullRequestsSupported },
   );
@@ -1209,54 +1220,6 @@ function PullRequestsRouteView() {
   );
 
   const scrollRef = useRef<HTMLDivElement>(null);
-  const sentinelRef = useRef<HTMLDivElement>(null);
-  useEffect(() => {
-    const sentinel = sentinelRef.current;
-    // A failed page must stop the observer. Retained rows keep the sentinel on screen, so
-    // re-arming it after a failure would ask for the next page again, forever.
-    //
-    // Rows on screen are also what makes reaching the sentinel mean anything: with none, it
-    // sits directly below the empty state and is always in view, so a search that matches
-    // nothing would page through the whole host on its own — one listing of every repository
-    // per step — while the reader looks at an empty page. With nothing to scroll past, the
-    // next page is asked for rather than assumed.
-    if (
-      !sentinel ||
-      entries.length === 0 ||
-      listData?.truncated !== true ||
-      listQuery.isPending ||
-      listQuery.error !== null ||
-      // The rows on screen belong to the previous question, so nothing about them says where
-      // this one carries on from. Growing the page under them would answer neither.
-      showingCarried ||
-      // Asking past the cap is refused, which would strand the list on an error the retry
-      // could never clear, so growth stops here and the rest stays on the host. A continuation
-      // does not grow the page at all, so the cap does not apply to it.
-      (!canContinue && pageSize >= MAX_PAGE_SIZE)
-    ) {
-      return;
-    }
-    const observer = new IntersectionObserver(
-      (observed) => {
-        if (observed.some((entry) => entry.isIntersecting)) {
-          loadMore();
-        }
-      },
-      // Start the next page slightly before the sentinel is on screen.
-      { root: scrollRef.current, rootMargin: "240px" },
-    );
-    observer.observe(sentinel);
-    return () => observer.disconnect();
-  }, [
-    entries.length,
-    filterKey,
-    canContinue,
-    listData?.truncated,
-    listQuery.error,
-    listQuery.isPending,
-    pageSize,
-    showingCarried,
-  ]);
 
   /**
    * The line counts, asked for once the rows are on screen. On GitHub they are forty per cent of
@@ -1633,7 +1596,7 @@ function PullRequestsRouteView() {
         />
       ) : firstLoad ? (
         <PullRequestListGhost rows={7} />
-      ) : listQuery.error && listData === null ? (
+      ) : listQuery.error && entries.length === 0 ? (
         <PullRequestsUnavailableState error={listQuery.error} onRetry={() => listQuery.refresh()} />
       ) : carriedToNothing ? (
         <PullRequestListGhost rows={7} />
@@ -1699,22 +1662,33 @@ function PullRequestsRouteView() {
         </div>
       )}
 
-      {listQuery.error && listData !== null ? (
+      {listQuery.error && entries.length > 0 ? (
         <div className="flex items-center justify-between gap-3 rounded-lg border border-amber-500/30 bg-amber-500/5 px-3 py-2 text-xs">
-          <span>The latest request failed. Showing the last pull requests loaded.</span>
+          <span>{listQuery.error} Showing the last pull requests loaded.</span>
           <Button size="xs" variant="outline" onClick={() => listQuery.refresh()}>
             Retry
           </Button>
         </div>
       ) : null}
       {listData?.truncated && entries.length > 0 ? (
-        <div ref={sentinelRef} className="flex justify-center py-2 text-xs text-muted-foreground">
+        <div className="flex justify-center py-3 text-xs text-muted-foreground">
           {loadingMore ? (
             <span className="flex items-center gap-2">
               <LoaderIcon aria-hidden className="size-3.5 animate-spin" />
-              Loading more
+              {sentCursors === null ? "Updating pull requests" : "Loading more"}
             </span>
-          ) : null}
+          ) : canContinue || pageSize < MAX_PAGE_SIZE ? (
+            <Button
+              size="sm"
+              variant="outline"
+              onClick={loadMore}
+              disabled={listQuery.isPending || showingCarried}
+            >
+              Load more pull requests
+            </Button>
+          ) : (
+            <span>Narrow your search to find more pull requests.</span>
+          )}
         </div>
       ) : null}
     </>
@@ -1979,10 +1953,7 @@ function PullRequestsRouteView() {
               // Merging, closing or reopening changes the row this panel was opened from, so
               // the list behind it is out of date the moment the host takes the action.
               onActed={() => {
-                refreshList();
-                baselineQuery.refresh();
-                authoredQuery.refresh();
-                reviewingQuery.refresh();
+                refreshList(true);
               }}
             />
           </RightPanelTabs>
@@ -2244,7 +2215,7 @@ function PullRequestsColumn({
   return (
     // Painted flat like the chat column: the inset underneath carries the chrome grain, and a
     // content surface that lets it show reads as a different background than every thread.
-    <div className="flex min-h-0 min-w-0 flex-1 flex-col bg-background">
+    <div className="@container/pr-list flex min-h-0 min-w-0 flex-1 flex-col bg-background">
       {/* A closed right panel leaves this column full-width, so the shared header
           reserves native window controls and hosts the controls strip itself: on
           desktop the header is a drag-region, and only a no-drag descendant wins
@@ -2325,8 +2296,10 @@ function PullRequestsColumn({
             content actually passing under the chrome fades. */}
         <WorkspacePageContainer width="expanded" className="gap-4">
           <div className="flex flex-col gap-3">
-            <div ref={inFlowSearchRef} className="flex items-center gap-2">
-              {searchInput}
+            <div ref={inFlowSearchRef} className="flex flex-wrap items-center gap-2">
+              <div className="min-w-0 basis-full @lg/pr-list:basis-0 @lg/pr-list:flex-1">
+                {searchInput}
+              </div>
               {sortMenu}
               {filtersMenu}
               {!condensed ? (
diff --git a/apps/web/src/state/pullRequests.ts b/apps/web/src/state/pullRequests.ts
index 99b2ef37c99a..eaec72066735 100644
--- a/apps/web/src/state/pullRequests.ts
+++ b/apps/web/src/state/pullRequests.ts
@@ -130,8 +130,8 @@ function createMergedEnvironmentQuery<Input, A>(
       (override?: ReadonlyArray<EnvironmentQueryTarget<Input>>) => {
         const refreshTargets =
           override ?? (JSON.parse(key) as ReadonlyArray<EnvironmentQueryTarget<Input>>);
-        for (const target of refreshTargets) {
-          appAtomRegistry.refresh(atomFor(target));
+        for (const atom of new Set(refreshTargets.map(atomFor))) {
+          appAtomRegistry.refresh(atom);
         }
       },
       [key],
@@ -173,7 +173,7 @@ export interface MergedPullRequestListView {
   readonly data: MergedPullRequestList | null;
   readonly error: string | null;
   readonly isPending: boolean;
-  readonly refresh: () => void;
+  readonly refresh: (targets?: ReadonlyArray<EnvironmentQueryTarget<PullRequestListInput>>) => void;
 }
 
 /** One listing per environment, merged into the single list the page renders. */
diff --git a/packages/client-runtime/src/state/pullRequests.ts b/packages/client-runtime/src/state/pullRequests.ts
index 6144d8507a9e..d0da18a7226a 100644
--- a/packages/client-runtime/src/state/pullRequests.ts
+++ b/packages/client-runtime/src/state/pullRequests.ts
@@ -75,8 +75,8 @@ export function pullRequestDetailToVcsStatus(
 }
 
 /**
- * Every read shells out to the GitHub CLI, so results are reused for a short while and
- * refreshed explicitly. Mutations run serially per environment: `gh` actions on the same
+ * Reopening a PR within a minute reuses detail and activity. Explicit refreshes and
+ * turn notifications still revalidate. Mutations run serially per environment: actions on the same
  * pull request are order-sensitive, and the detail view refetches after each one.
  */
 export function createPullRequestEnvironmentAtoms<R, E>(
@@ -91,7 +91,7 @@ export function createPullRequestEnvironmentAtoms<R, E>(
   const activity = createEnvironmentRpcQueryAtomFamily(runtime, {
     label: "environment-data:pull-requests:activity",
     tag: WS_METHODS.pullRequestsActivity,
-    staleTimeMs: 15_000,
+    staleTimeMs: 60_000,
     refreshTrigger: ({ environmentId }) => refreshes({ environmentId, input: {} }),
   });
   return {
@@ -118,7 +118,7 @@ export function createPullRequestEnvironmentAtoms<R, E>(
     detail: createEnvironmentRpcQueryAtomFamily(runtime, {
       label: "environment-data:pull-requests:detail",
       tag: WS_METHODS.pullRequestsDetail,
-      staleTimeMs: 15_000,
+      staleTimeMs: 60_000,
       refreshTrigger: ({ environmentId }) => refreshes({ environmentId, input: {} }),
     }),
     activity,

From c3caceade14ccda0686db0031aca79d7d38a71d0 Mon Sep 17 00:00:00 2001
From: Niklas Westman <niklas@jadeva.se>
Date: Sat, 5 Sep 2026 03:10:46 +0200
Subject: [PATCH 54/56] perf(shared): skip duplicate PATH entries and per-probe
 tracing (#9618)

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Julius Marminge <51714798+juliusmarminge@users.noreply.github.com>
---
 packages/shared/src/shell.test.ts | 121 ++++++++++++++++++++++++++++++
 packages/shared/src/shell.ts      |  12 ++-
 2 files changed, 129 insertions(+), 4 deletions(-)

diff --git a/packages/shared/src/shell.test.ts b/packages/shared/src/shell.test.ts
index e3046c03abed..c98c1c452d4b 100644
--- a/packages/shared/src/shell.test.ts
+++ b/packages/shared/src/shell.test.ts
@@ -2,11 +2,15 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 import { it as effectIt } from "@effect/vitest";
 import { HostProcessEnvironment, HostProcessPlatform } from "@t3tools/shared/hostProcess";
 import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as TestClock from "effect/testing/TestClock";
 import { describe, expect, it, vi } from "vite-plus/test";
 
 import {
   extractPathFromShellOutput,
   CommandAvailability,
+  CommandResolutionCache,
   type CommandAvailabilityChecker,
   isCommandAvailable,
   listLoginShellCandidates,
@@ -375,6 +379,123 @@ effectIt.layer(NodeServices.layer)("resolveCommandPath", (it) => {
       expect(result._tag).toBe("Failure");
     }),
   );
+
+  // Records every path the scan stats, without ever reporting a match, so the
+  // walk runs to exhaustion and the probe set can be inspected. Assertions
+  // below count probes rather than naming paths: `Path` is the host's, so the
+  // separator differs between a Windows and a Linux CI runner.
+  const recordProbes = (env: NodeJS.ProcessEnv) =>
+    Effect.gen(function* () {
+      const probed: Array<string> = [];
+      const result = yield* resolveCommandPath("definitely-not-installed", { env }).pipe(
+        Effect.provideService(HostProcessPlatform, "win32"),
+        Effect.provideService(CommandResolutionCache, new Map()),
+        Effect.provide(
+          FileSystem.layerNoop({
+            stat: (filePath) =>
+              Effect.sync(() => {
+                probed.push(filePath);
+                return { type: "Directory" } as FileSystem.File.Info;
+              }),
+          }),
+        ),
+        Effect.result,
+      );
+
+      expect(result._tag).toBe("Failure");
+      return probed;
+    });
+
+  it.effect("visits a repeated PATH directory only once", () =>
+    Effect.gen(function* () {
+      const probed = yield* recordProbes({
+        PATH: "C:\\bin;C:\\other;C:\\bin;C:\\other",
+        PATHEXT: ".COM;.EXE",
+      });
+
+      // Two directories, two extensions, upper and lowercase spellings.
+      expect(probed).toHaveLength(8);
+      expect(new Set(probed).size).toBe(probed.length);
+    }),
+  );
+
+  it.effect("still visits a PATH entry that differs only in case", () =>
+    Effect.gen(function* () {
+      const probed = yield* recordProbes({
+        PATH: "C:\\bin;C:\\BIN",
+        PATHEXT: ".COM;.EXE",
+      });
+
+      // Deliberately not folded together. Windows 10+ can mark a directory
+      // case-sensitive, so the two spellings are not provably one directory and
+      // skipping the second could hide a command that is really there.
+      expect(probed).toHaveLength(8);
+    }),
+  );
+
+  it.effect.each(["audit-command", "audit-command.CMD"])(
+    "resolves lowercase executable files for %s in a case-sensitive Windows PATH directory",
+    (command) =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const cwd = yield* fs.makeTempDirectoryScoped({ prefix: "t3-case-sensitive-path-" });
+        const executable = path.join(cwd, "audit-command.cmd");
+        yield* fs.writeFileString(executable, "@echo off\n");
+
+        const resolved = yield* resolveCommandPath(command, {
+          env: { PATH: cwd, PATHEXT: ".CMD" },
+        }).pipe(
+          Effect.provideService(HostProcessPlatform, "win32"),
+          Effect.provideService(CommandResolutionCache, new Map()),
+          Effect.provideService(FileSystem.FileSystem, {
+            ...fs,
+            // Keep this case-sensitive fixture portable to case-insensitive hosts.
+            stat: (filePath) =>
+              fs.stat(filePath === executable ? filePath : path.join(cwd, "missing")),
+          }),
+        );
+
+        expect(resolved).toBe(executable);
+      }),
+  );
+
+  it.effect("keeps cached misses until expiry while allowing explicit paths", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const cwd = yield* fs.makeTempDirectoryScoped({ prefix: "t3-path-cache-" });
+      const executable = path.join(cwd, "appeared.CMD");
+      const options = { env: { PATH: `${cwd};${cwd}`, PATHEXT: ".CMD" } };
+
+      expect((yield* resolveCommandPath("appeared", options).pipe(Effect.result))._tag).toBe(
+        "Failure",
+      );
+      yield* fs.writeFileString(executable, "@echo off\n");
+      expect((yield* resolveCommandPath("appeared", options).pipe(Effect.result))._tag).toBe(
+        "Failure",
+      );
+      expect(yield* resolveCommandPath(executable, options)).toBe(executable);
+      yield* TestClock.adjust("30 seconds");
+      expect(yield* resolveCommandPath("appeared", options)).toBe(executable);
+    }).pipe(
+      Effect.provideService(HostProcessPlatform, "win32"),
+      Effect.provideService(CommandResolutionCache, new Map()),
+    ),
+  );
+
+  it.effect("keeps upper and lowercase PATHEXT candidates", () =>
+    Effect.gen(function* () {
+      const probed = yield* recordProbes({
+        PATH: "C:\\bin",
+        PATHEXT: ".COM;.EXE;.BAT;.CMD",
+      });
+
+      expect(probed).toHaveLength(8);
+      expect(probed.filter((filePath) => /\.(COM|EXE|BAT|CMD)$/.test(filePath))).toHaveLength(4);
+      expect(probed.filter((filePath) => /\.(com|exe|bat|cmd)$/.test(filePath))).toHaveLength(4);
+    }),
+  );
 });
 
 effectIt.layer(NodeServices.layer)("resolveSpawnCommand", (it) => {
diff --git a/packages/shared/src/shell.ts b/packages/shared/src/shell.ts
index 4c86c8886312..7d7a7d7b4f41 100644
--- a/packages/shared/src/shell.ts
+++ b/packages/shared/src/shell.ts
@@ -544,7 +544,8 @@ function cacheCommandResolution(
   });
 }
 
-const isExecutableFile = Effect.fn("shell.isExecutableFile")(function* (
+// Trace each command lookup, not every candidate file it probes.
+const isExecutableFile = Effect.fnUntraced(function* (
   filePath: string,
   platform: NodeJS.Platform,
   windowsPathExtensions: ReadonlyArray<string>,
@@ -605,12 +606,15 @@ const resolveCommandPathForPlatform = Effect.fn("shell.resolveCommandPathForPlat
     return cached.resolvedPath;
   }
 
+  // Keep case variants: Windows can make PATH directories case-sensitive.
   const pathEntries: string[] = [];
+  const seenPathEntries = new Set<string>();
   for (const entry of pathValue.split(pathDelimiterForPlatform(platform))) {
     const pathEntry = stripWrappingQuotes(entry.trim());
-    if (pathEntry.length > 0) {
-      pathEntries.push(pathEntry);
-    }
+    if (pathEntry.length === 0 || seenPathEntries.has(pathEntry)) continue;
+
+    seenPathEntries.add(pathEntry);
+    pathEntries.push(pathEntry);
   }
 
   for (const pathEntry of pathEntries) {

From 896fe82f2f191eb8ac0fd620e19c25dd48253592 Mon Sep 17 00:00:00 2001
From: maria <maria@kuuro.net>
Date: Fri, 4 Sep 2026 21:11:01 -0400
Subject: [PATCH 55/56] fix(web): preserve focus and prioritize picker
 shortcuts (#9795)

---
 apps/web/src/components/CommandPalette.tsx    | 11 +++++---
 .../src/components/CommandPaletteContent.tsx  | 13 +++++++--
 apps/web/src/components/LegacySidebar.tsx     |  4 +--
 apps/web/src/components/Sidebar.tsx           |  6 ++--
 .../src/components/ThreadTerminalDrawer.tsx   | 28 ++++++++-----------
 .../components/chat/ModelPickerContent.tsx    | 15 +++++-----
 docs/user/keyboard-focus.md                   |  9 ++++++
 7 files changed, 52 insertions(+), 34 deletions(-)
 create mode 100644 docs/user/keyboard-focus.md

diff --git a/apps/web/src/components/CommandPalette.tsx b/apps/web/src/components/CommandPalette.tsx
index 06813228b8e4..27dddf00ee53 100644
--- a/apps/web/src/components/CommandPalette.tsx
+++ b/apps/web/src/components/CommandPalette.tsx
@@ -508,7 +508,10 @@ export function CommandPalette({ children }: { children: ReactNode }) {
           setOpen(open);
         }}
       >
-        {children}
+        {/* Block background focus calls for the entire time the palette is open. */}
+        <div className="contents" inert={state.open}>
+          {children}
+        </div>
         <CommandPaletteDialog
           mode={state.mode}
           openIntent={state.openIntent}
@@ -2289,15 +2292,15 @@ function OpenCommandPaletteDialog(props: {
       context: { modelPickerOpen: false },
     });
     if (threadJumpIndexFromCommand(command ?? "") !== null) {
+      event.preventDefault();
+      event.stopPropagation();
       const matchingItem = displayedGroups
         .flatMap((group) => group.items)
         .find((item) => item.shortcutCommand === command);
       if (matchingItem) {
-        event.preventDefault();
-        event.stopPropagation();
         executeItem(matchingItem);
-        return;
       }
+      return;
     }
     if (command === "thread.copyReference" && activeThreadReferenceCopyTarget !== null) {
       event.preventDefault();
diff --git a/apps/web/src/components/CommandPaletteContent.tsx b/apps/web/src/components/CommandPaletteContent.tsx
index af3c1b671704..8c1a5b0e3c83 100644
--- a/apps/web/src/components/CommandPaletteContent.tsx
+++ b/apps/web/src/components/CommandPaletteContent.tsx
@@ -1,5 +1,5 @@
 import { ArrowDownIcon, ArrowUpIcon } from "lucide-react";
-import type { ComponentProps, ReactNode } from "react";
+import { type ComponentProps, type ReactNode, useLayoutEffect, useRef } from "react";
 
 import { Command, CommandFooter, CommandInput, CommandPanel } from "./ui/command";
 import { Kbd, KbdGroup } from "./ui/kbd";
@@ -33,11 +33,20 @@ export function CommandPaletteContent({
   testId,
   ...commandProps
 }: CommandPaletteContentProps) {
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  // Direct-open flows replace the initial palette view after the dialog has
+  // already moved focus. Reclaim it when the replacement input mounts so
+  // typing cannot continue in the composer behind the modal.
+  useLayoutEffect(() => {
+    inputRef.current?.focus();
+  }, []);
+
   return (
     <div className="contents" data-testid={testId}>
       <Command {...commandProps}>
         <div className="relative">
-          <CommandInput {...inputProps} />
+          <CommandInput {...inputProps} ref={inputRef} />
           {inputAccessory}
         </div>
         <CommandPanel className={panelClassName}>{children}</CommandPanel>
diff --git a/apps/web/src/components/LegacySidebar.tsx b/apps/web/src/components/LegacySidebar.tsx
index ea910905efe0..650ad12bebcb 100644
--- a/apps/web/src/components/LegacySidebar.tsx
+++ b/apps/web/src/components/LegacySidebar.tsx
@@ -172,7 +172,7 @@ import {
   useSidebar,
 } from "./ui/sidebar";
 import { useThreadSelectionStore } from "../threadSelectionStore";
-import { openCommandPalette } from "../commandPaletteBus";
+import { isCommandPaletteOpen, openCommandPalette } from "../commandPaletteBus";
 import {
   archiveSelectedThreadEntries,
   buildMultiSelectThreadContextMenuItems,
@@ -3510,7 +3510,7 @@ export default function LegacySidebar() {
     const onWindowKeyDown = (event: globalThis.KeyboardEvent) => {
       const shortcutContext = getCurrentSidebarShortcutContext();
 
-      if (event.defaultPrevented || event.repeat) {
+      if (event.defaultPrevented || event.repeat || isCommandPaletteOpen() || isModelPickerOpen()) {
         return;
       }
 
diff --git a/apps/web/src/components/Sidebar.tsx b/apps/web/src/components/Sidebar.tsx
index 2902e238e01e..2e962810d621 100644
--- a/apps/web/src/components/Sidebar.tsx
+++ b/apps/web/src/components/Sidebar.tsx
@@ -104,7 +104,7 @@ import { legacyProjectCwdPreferenceKey, useUiStateStore } from "../uiStateStore"
 import { useThreadSelectionStore } from "../threadSelectionStore";
 import { useThreadActions } from "../hooks/useThreadActions";
 import { useHandleNewThread } from "../hooks/useHandleNewThread";
-import { openCommandPalette } from "../commandPaletteBus";
+import { isCommandPaletteOpen, openCommandPalette } from "../commandPaletteBus";
 import { startNewThreadFromContext } from "../lib/chatThreadActions";
 import { useClientSettings } from "../hooks/useSettings";
 import { useCopyToClipboard } from "../hooks/useCopyToClipboard";
@@ -3505,7 +3505,9 @@ export default function Sidebar() {
   );
   useEffect(() => {
     const onWindowKeyDown = (event: KeyboardEvent) => {
-      if (event.defaultPrevented || event.repeat) return;
+      if (event.defaultPrevented || event.repeat || isCommandPaletteOpen() || isModelPickerOpen()) {
+        return;
+      }
       const command = resolveShortcutCommand(event, keybindings, {
         platform: navigator.platform,
         context: {
diff --git a/apps/web/src/components/ThreadTerminalDrawer.tsx b/apps/web/src/components/ThreadTerminalDrawer.tsx
index 89cdc3649acd..9f4956aae682 100644
--- a/apps/web/src/components/ThreadTerminalDrawer.tsx
+++ b/apps/web/src/components/ThreadTerminalDrawer.tsx
@@ -516,7 +516,10 @@ export function TerminalViewport({
       // never started, so only "exited" triggers the message — as with xterm.)
       synchronizedStatusRef.current = "closed";
       synchronizeTerminalStatus(terminal, latestSession.status);
-      if (autoFocus && visibleRef.current) window.requestAnimationFrame(() => terminal.focus());
+      // Startup may finish after the user has returned to the composer.
+      if (visibleRef.current && mount.contains(document.activeElement)) {
+        terminal.focus();
+      }
 
       const dismissSelectionAction = (supersede = false) => {
         const ownsMenu =
@@ -870,10 +873,10 @@ export function TerminalViewport({
 
     return () => {
       cancelled = true;
+      const hadFocus = mount.contains(document.activeElement);
       teardown?.();
+      if (hadFocus && mount.isConnected) mount.focus({ preventScroll: true });
     };
-    // autoFocus is intentionally omitted;
-    // it is only read at mount time and must not trigger terminal teardown/recreation.
   }, [cwd, environmentId, runtimeEnvKey, terminalId, threadId, worktreePath]);
 
   useEffect(() => {
@@ -904,24 +907,14 @@ export function TerminalViewport({
       writeSystemMessage(terminal, current.error);
     }
 
-    if (previous.version === 0 && autoFocus && visibleRef.current) {
-      window.requestAnimationFrame(() => {
-        terminal.focus();
-      });
-    }
     previousSessionRef.current = current;
-  }, [autoFocus, terminalOutput, terminalError, terminalStatus, terminalVersion]);
+  }, [terminalOutput, terminalError, terminalStatus, terminalVersion]);
 
   useEffect(() => {
     if (!autoFocus || !visible) return;
-    const terminal = terminalRef.current;
-    if (!terminal) return;
-    const frame = window.requestAnimationFrame(() => {
-      terminal.focus();
-    });
-    return () => {
-      window.cancelAnimationFrame(frame);
-    };
+    // Claim focus when requested, then hand it to the terminal once ready only
+    // if the user has not focused something else in the meantime.
+    (terminalRef.current ?? containerRef.current)?.focus();
   }, [autoFocus, focusRequestId, visible]);
 
   useEffect(() => {
@@ -944,6 +937,7 @@ export function TerminalViewport({
   return (
     <div
       ref={containerRef}
+      tabIndex={-1}
       className="relative h-full w-full overflow-hidden bg-[var(--terminal-background)]"
     />
   );
diff --git a/apps/web/src/components/chat/ModelPickerContent.tsx b/apps/web/src/components/chat/ModelPickerContent.tsx
index 8880369a18c9..63dea7844c46 100644
--- a/apps/web/src/components/chat/ModelPickerContent.tsx
+++ b/apps/web/src/components/chat/ModelPickerContent.tsx
@@ -5,6 +5,7 @@ import {
   type ResolvedKeybindingsConfig,
 } from "@t3tools/contracts";
 import { resolveSelectableModel } from "@t3tools/shared/model";
+import { useAtomValue } from "@effect/atom-react";
 import { LegendList, type LegendListRef } from "@legendapp/list/react";
 import { memo, useMemo, useState, useCallback, useEffect, useLayoutEffect, useRef } from "react";
 import { ChevronRightIcon, SearchIcon } from "lucide-react";
@@ -26,6 +27,8 @@ import {
   ComboboxListVirtualized,
 } from "../ui/combobox";
 import { ModelEsque } from "./providerIconUtils";
+import { isCommandPaletteOpen } from "../../commandPaletteBus";
+import { primaryServerKeybindingsAtom } from "../../state/server";
 import {
   modelPickerJumpCommandForIndex,
   modelPickerJumpIndexFromCommand,
@@ -217,10 +220,8 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
           : [],
       ),
   );
-  const keybindings = useMemo<ResolvedKeybindingsConfig>(
-    () => providedKeybindings ?? [],
-    [providedKeybindings],
-  );
+  const serverKeybindings = useAtomValue(primaryServerKeybindingsAtom);
+  const keybindings = providedKeybindings ?? serverKeybindings;
   const updateSettings = useUpdateClientSettings();
 
   const focusSearchInput = useCallback(() => {
@@ -678,7 +679,7 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
 
   useEffect(() => {
     const onWindowKeyDown = (event: globalThis.KeyboardEvent) => {
-      if (event.defaultPrevented || event.repeat) {
+      if (event.defaultPrevented || event.repeat || isCommandPaletteOpen()) {
         return;
       }
 
@@ -690,6 +691,8 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
       if (jumpIndex === null) {
         return;
       }
+      event.preventDefault();
+      event.stopPropagation();
 
       const targetModelKey = modelJumpModelKeys[jumpIndex];
       if (!targetModelKey) {
@@ -699,8 +702,6 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
       if (!model) {
         return;
       }
-      event.preventDefault();
-      event.stopPropagation();
       handleModelSelect(model.slug, model.instanceId);
     };
 
diff --git a/docs/user/keyboard-focus.md b/docs/user/keyboard-focus.md
new file mode 100644
index 000000000000..50b9c87c24f3
--- /dev/null
+++ b/docs/user/keyboard-focus.md
@@ -0,0 +1,9 @@
+# Keyboard focus
+
+The command palette keeps focus while open. Closing it returns focus to the composer.
+While the palette or model picker is open, number shortcuts select its entries instead of
+switching threads. Model shortcuts work in Settings as well as the composer.
+See [Keybindings](./keybindings.md) to customize these shortcuts.
+
+If you return to typing while a terminal is starting, the composer keeps focus when the terminal
+becomes ready. Opening or switching to a terminal explicitly still focuses it.

From 82f64cd8d046ab4ee8588f7bcbc1e66a4a0c80fe Mon Sep 17 00:00:00 2001
From: Amirali Beigi <43336552+amiralibg@users.noreply.github.com>
Date: Sat, 5 Sep 2026 04:43:43 +0330
Subject: [PATCH 56/56] fix(skills): support names beginning with digits
 (#9244)

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Julius Marminge <51714798+juliusmarminge@users.noreply.github.com>
---
 .../src/nativeMarkdownText.ts                 |  3 +-
 .../mobile/src/lib/nativeMarkdownText.test.ts | 23 +++++++++++
 .../Drivers/ClaudeSkillDispatch.test.ts       | 16 +++++++-
 .../provider/Drivers/ClaudeSkillDispatch.ts   |  3 +-
 .../src/provider/Drivers/CursorSkills.ts      |  5 ++-
 .../provider/Layers/CursorProvider.test.ts    | 18 +++++++++
 apps/web/src/components/ChatMarkdown.test.tsx | 40 +++++++++++++++++++
 .../src/components/chat/SkillInlineText.tsx   |  3 +-
 apps/web/src/composer-editor-mentions.test.ts | 23 +++++++++++
 .../shared/src/composerInlineTokens.test.ts   | 20 ++++++++++
 packages/shared/src/composerInlineTokens.ts   | 10 ++++-
 11 files changed, 157 insertions(+), 7 deletions(-)

diff --git a/apps/mobile/modules/t3-markdown-text/src/nativeMarkdownText.ts b/apps/mobile/modules/t3-markdown-text/src/nativeMarkdownText.ts
index 2b39ac201599..4c8a6c4d7cd5 100644
--- a/apps/mobile/modules/t3-markdown-text/src/nativeMarkdownText.ts
+++ b/apps/mobile/modules/t3-markdown-text/src/nativeMarkdownText.ts
@@ -195,7 +195,8 @@ function appendRun(
   return runs;
 }
 
-const SKILL_TOKEN_REGEX = /(^|\s)\$([a-zA-Z][a-zA-Z0-9:_-]*)(?=\s|$)/g;
+const SKILL_TOKEN_REGEX =
+  /(^|\s)\$(?![0-9][0-9_]*(?:[kKmMbBtT]|[eE][0-9]+)?(?:\s|$))(?=[a-zA-Z0-9:_-]*[a-zA-Z])([a-zA-Z0-9][a-zA-Z0-9:_-]*)(?=\s|$)/g;
 
 function formatSkillLabel(skill: SelectableMarkdownSkill): string {
   const displayName = skill.displayName?.trim();
diff --git a/apps/mobile/src/lib/nativeMarkdownText.test.ts b/apps/mobile/src/lib/nativeMarkdownText.test.ts
index 1e7cb5f3164e..c3951c8d81f0 100644
--- a/apps/mobile/src/lib/nativeMarkdownText.test.ts
+++ b/apps/mobile/src/lib/nativeMarkdownText.test.ts
@@ -226,6 +226,29 @@ describe("nativeMarkdownDocumentRuns", () => {
     ]);
   });
 
+  it("decorates known skill references that begin with a digit", () => {
+    const node: MarkdownNode = {
+      type: "document",
+      children: [
+        {
+          type: "paragraph",
+          children: [{ type: "text", content: "Use $2spec for this." }],
+        },
+      ],
+    };
+
+    expect(nativeMarkdownDocumentRuns(node, [{ name: "2spec", displayName: "2Spec" }])).toEqual([
+      { text: "Use ", role: "body" },
+      {
+        text: "$2spec",
+        role: "body",
+        skillName: "2spec",
+        skillLabel: "2Spec",
+      },
+      { text: " for this.", role: "body" },
+    ]);
+  });
+
   it("decorates known skill references inside blockquotes", () => {
     const node: MarkdownNode = {
       type: "blockquote",
diff --git a/apps/server/src/provider/Drivers/ClaudeSkillDispatch.test.ts b/apps/server/src/provider/Drivers/ClaudeSkillDispatch.test.ts
index 99074c8b07ed..e6e6da9d5e9e 100644
--- a/apps/server/src/provider/Drivers/ClaudeSkillDispatch.test.ts
+++ b/apps/server/src/provider/Drivers/ClaudeSkillDispatch.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from "vite-plus/test";
 
 import { planClaudeSkillDispatch } from "./ClaudeSkillDispatch.ts";
 
-const SKILLS = new Set(["implement", "review", "re-release-version"]);
+const SKILLS = new Set(["2spec", "implement", "review", "re-release-version"]);
 
 describe("planClaudeSkillDispatch", () => {
   it("leaves a prompt without a known skill untouched", () => {
@@ -27,6 +27,14 @@ describe("planClaudeSkillDispatch", () => {
     });
   });
 
+  it("dispatches a known skill whose name begins with a digit", () => {
+    expect(planClaudeSkillDispatch("use $2spec for this", SKILLS)).toEqual({
+      leadingText: "use",
+      commandText: "/2spec for this",
+      skillName: "2spec",
+    });
+  });
+
   it("dispatches the last mention and rewrites earlier ones inline", () => {
     expect(planClaudeSkillDispatch("$review the diff, then $implement the fixes", SKILLS)).toEqual({
       leadingText: "/review the diff, then",
@@ -38,4 +46,10 @@ describe("planClaudeSkillDispatch", () => {
   it("ignores a dollar token glued to other text", () => {
     expect(planClaudeSkillDispatch("cost is 5$implement", SKILLS)).toBeUndefined();
   });
+
+  it("ignores currency amounts and compact monetary expressions", () => {
+    const skillsWithCurrency = new Set([...SKILLS, "20", "20k", "100M"]);
+    expect(planClaudeSkillDispatch("pay $20 tomorrow", skillsWithCurrency)).toBeUndefined();
+    expect(planClaudeSkillDispatch("budget is $20k tomorrow", skillsWithCurrency)).toBeUndefined();
+  });
 });
diff --git a/apps/server/src/provider/Drivers/ClaudeSkillDispatch.ts b/apps/server/src/provider/Drivers/ClaudeSkillDispatch.ts
index a008e0f9ec9b..27e7dcf68bdf 100644
--- a/apps/server/src/provider/Drivers/ClaudeSkillDispatch.ts
+++ b/apps/server/src/provider/Drivers/ClaudeSkillDispatch.ts
@@ -29,7 +29,8 @@
  * (`packages/shared/src/composerInlineTokens.ts`), so a rendered chip and a
  * dispatched skill are always the same set.
  */
-const SKILL_MENTION_PATTERN = /(^|\s)\$([a-zA-Z][a-zA-Z0-9:_-]*)(?=\s|$)/g;
+const SKILL_MENTION_PATTERN =
+  /(^|\s)\$(?![0-9][0-9_]*(?:[kKmMbBtT]|[eE][0-9]+)?(?:\s|$))(?=[a-zA-Z0-9:_-]*[a-zA-Z])([a-zA-Z0-9][a-zA-Z0-9:_-]*)(?=\s|$)/g;
 
 export interface ClaudeSkillDispatch {
   /** Text before the dispatched mention, or `undefined` when it opens the prompt. */
diff --git a/apps/server/src/provider/Drivers/CursorSkills.ts b/apps/server/src/provider/Drivers/CursorSkills.ts
index 7b0637267c80..599dc712d46a 100644
--- a/apps/server/src/provider/Drivers/CursorSkills.ts
+++ b/apps/server/src/provider/Drivers/CursorSkills.ts
@@ -19,8 +19,9 @@ import * as Schema from "effect/Schema";
 import { parse as parseYamlDocument } from "yaml";
 
 const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
-const SKILL_MENTION_PATTERN = /(^|\s)\$([a-zA-Z][a-zA-Z0-9:_-]*)(?=\s|$)/g;
-const HAS_SKILL_MENTION_PATTERN = /(^|\s)\$[a-zA-Z][a-zA-Z0-9:_-]*(?=\s|$)/;
+const SKILL_MENTION_PATTERN =
+  /(^|\s)\$(?![0-9][0-9_]*(?:[kKmMbBtT]|[eE][0-9]+)?(?:\s|$))(?=[a-zA-Z0-9:_-]*[a-zA-Z])([a-zA-Z0-9][a-zA-Z0-9:_-]*)(?=\s|$)/g;
+const HAS_SKILL_MENTION_PATTERN = new RegExp(SKILL_MENTION_PATTERN.source);
 const MAX_SKILL_DEPTH = 10;
 const MAX_SKILL_BYTES = FileSystem.Size(1_000_000);
 const MAX_SKILL_SCAN_ENTRIES = 10_000;
diff --git a/apps/server/src/provider/Layers/CursorProvider.test.ts b/apps/server/src/provider/Layers/CursorProvider.test.ts
index a01958dcccac..78edd8acbd45 100644
--- a/apps/server/src/provider/Layers/CursorProvider.test.ts
+++ b/apps/server/src/provider/Layers/CursorProvider.test.ts
@@ -455,6 +455,24 @@ describe("Cursor skills", () => {
       "please /review this",
     );
   });
+
+  it("detects and invokes digit-leading Cursor skills without rewriting money", () => {
+    const names = new Set(["2spec", "20k", "100M", "1e6"]);
+    // Repeated presence checks must not carry a global-regex cursor.
+    expect(hasCursorSkillMention("use $2spec here")).toBe(true);
+    expect(hasCursorSkillMention("use $2spec here")).toBe(true);
+    expect(rewriteCursorSkillMentions("use $2spec here", names)).toBe("use /2spec here");
+    expect(rewriteCursorSkillMentions("use $2spec here", new Set())).toBe("use $2spec here");
+    for (const text of [
+      "pay $20 tomorrow",
+      "budget $20k here",
+      "cost $100M total",
+      "limit $1e6 here",
+    ]) {
+      expect(hasCursorSkillMention(text)).toBe(false);
+      expect(rewriteCursorSkillMentions(text, names)).toBe(text);
+    }
+  });
 });
 
 describe("getCursorFallbackModels", () => {
diff --git a/apps/web/src/components/ChatMarkdown.test.tsx b/apps/web/src/components/ChatMarkdown.test.tsx
index 28ac42888eef..9762506531a8 100644
--- a/apps/web/src/components/ChatMarkdown.test.tsx
+++ b/apps/web/src/components/ChatMarkdown.test.tsx
@@ -293,6 +293,46 @@ describe("hasMarkdownFilePrimaryAction", () => {
   });
 });
 
+describe("ChatMarkdown skill chips", () => {
+  it("updates digit-leading skill labels when discovered skills change", async () => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    let renderer: ReactTestRenderer | undefined;
+    const text = "Use $2spec with a $20k budget.";
+    try {
+      await act(async () => {
+        renderer = create(<ChatMarkdown cwd="/tmp/project" text={text} />);
+      });
+      const mounted = renderer!;
+      const labels = (label: string) =>
+        mounted.root.findAllByType("span").filter((node) => node.children.includes(label));
+      expect(labels("2Spec")).toHaveLength(0);
+
+      await act(async () => {
+        mounted.update(
+          <ChatMarkdown
+            cwd="/tmp/project"
+            text={text}
+            skills={[
+              { name: "2spec", displayName: "2Spec" },
+              { name: "20k", displayName: "MoneySkill" },
+            ]}
+          />,
+        );
+      });
+      expect(labels("2Spec")).toHaveLength(1);
+      expect(labels("MoneySkill")).toHaveLength(0);
+
+      await act(async () => {
+        mounted.update(<ChatMarkdown cwd="/tmp/project" text={text} skills={[]} />);
+      });
+      expect(labels("2Spec")).toHaveLength(0);
+    } finally {
+      await act(async () => renderer?.unmount());
+      vi.unstubAllGlobals();
+    }
+  });
+});
+
 describe("ChatMarkdown file option chips", () => {
   it("keeps the fallback button text selectable", () => {
     const html = renderToStaticMarkup(
diff --git a/apps/web/src/components/chat/SkillInlineText.tsx b/apps/web/src/components/chat/SkillInlineText.tsx
index 6d026ea58cce..b6e398539133 100644
--- a/apps/web/src/components/chat/SkillInlineText.tsx
+++ b/apps/web/src/components/chat/SkillInlineText.tsx
@@ -10,7 +10,8 @@ import {
 } from "../composerInlineChip";
 import { cn } from "~/lib/utils";
 
-const SKILL_TOKEN_REGEX = /(^|\s)\$([a-zA-Z][a-zA-Z0-9:_-]*)(?=\s|$)/g;
+const SKILL_TOKEN_REGEX =
+  /(^|\s)\$(?![0-9][0-9_]*(?:[kKmMbBtT]|[eE][0-9]+)?(?:\s|$))(?=[a-zA-Z0-9:_-]*[a-zA-Z])([a-zA-Z0-9][a-zA-Z0-9:_-]*)(?=\s|$)/g;
 
 type InlineSkill = Pick<ServerProviderSkill, "name" | "displayName">;
 
diff --git a/apps/web/src/composer-editor-mentions.test.ts b/apps/web/src/composer-editor-mentions.test.ts
index 33f37af6802b..337fe7b8ae64 100644
--- a/apps/web/src/composer-editor-mentions.test.ts
+++ b/apps/web/src/composer-editor-mentions.test.ts
@@ -198,6 +198,29 @@ describe("splitPromptIntoComposerSegments", () => {
     ]);
   });
 
+  it("splits digit-leading skill tokens into skill segments", () => {
+    expect(splitPromptIntoComposerSegments("Use $2spec please")).toEqual([
+      { type: "text", text: "Use " },
+      { type: "skill", name: "2spec" },
+      { type: "text", text: " please" },
+    ]);
+  });
+
+  it("keeps digits-only dollar amounts and compact monetary expressions as text", () => {
+    expect(splitPromptIntoComposerSegments("I'll pay $20 tomorrow")).toEqual([
+      { type: "text", text: "I'll pay $20 tomorrow" },
+    ]);
+    expect(splitPromptIntoComposerSegments("Budget is $20k tomorrow")).toEqual([
+      { type: "text", text: "Budget is $20k tomorrow" },
+    ]);
+    expect(splitPromptIntoComposerSegments("Cost is $100M total")).toEqual([
+      { type: "text", text: "Cost is $100M total" },
+    ]);
+    expect(splitPromptIntoComposerSegments("Limit is $1e6 here")).toEqual([
+      { type: "text", text: "Limit is $1e6 here" },
+    ]);
+  });
+
   it("does not convert an incomplete trailing skill token", () => {
     expect(splitPromptIntoComposerSegments("Use $review-follow-up")).toEqual([
       { type: "text", text: "Use $review-follow-up" },
diff --git a/packages/shared/src/composerInlineTokens.test.ts b/packages/shared/src/composerInlineTokens.test.ts
index 81fd6add2056..5ce8f6281184 100644
--- a/packages/shared/src/composerInlineTokens.test.ts
+++ b/packages/shared/src/composerInlineTokens.test.ts
@@ -31,6 +31,26 @@ describe("collectComposerInlineTokens", () => {
     ]);
   });
 
+  it("collects skill names that begin with a digit", () => {
+    expect(collectComposerInlineTokens("Use $2spec next")).toEqual([
+      {
+        type: "skill",
+        value: "2spec",
+        source: "$2spec",
+        start: 4,
+        end: 10,
+      },
+    ]);
+  });
+
+  it("leaves digits-only dollar amounts and compact monetary expressions as text", () => {
+    expect(collectComposerInlineTokens("I'll pay $20 tomorrow")).toEqual([]);
+    expect(collectComposerInlineTokens("Budget is $1_000 total")).toEqual([]);
+    expect(collectComposerInlineTokens("Budget is $20k tomorrow")).toEqual([]);
+    expect(collectComposerInlineTokens("Cost is $100M total")).toEqual([]);
+    expect(collectComposerInlineTokens("Limit is $1e6 here")).toEqual([]);
+  });
+
   it("does not convert incomplete trailing tokens", () => {
     expect(collectComposerInlineTokens("Use $ui")).toEqual([]);
     expect(collectComposerInlineTokens("Inspect @AGENTS.md")).toEqual([]);
diff --git a/packages/shared/src/composerInlineTokens.ts b/packages/shared/src/composerInlineTokens.ts
index 11a5accf37b7..bb39dd599475 100644
--- a/packages/shared/src/composerInlineTokens.ts
+++ b/packages/shared/src/composerInlineTokens.ts
@@ -18,7 +18,15 @@ export interface CollectComposerInlineTokensOptions {
   readonly preserveTrailingFrom?: ReadonlyArray<ComposerInlineToken>;
 }
 
-const SKILL_TOKEN_REGEX = /(^|\s)\$([a-zA-Z][a-zA-Z0-9:_-]*)(?=\s)/g;
+/**
+ * A skill name may start with a digit, but compact monetary amounts and
+ * numeric expressions like "$20", "$20k", "$100M", and "$1e6" must stay prose:
+ * the composer chips any matched `$name` token, known or not. Tokens beginning
+ * with digits must not match numbers with currency/exponent suffixes, and must
+ * contain at least one letter.
+ */
+const SKILL_TOKEN_REGEX =
+  /(^|\s)\$(?![0-9][0-9_]*(?:[kKmMbBtT]|[eE][0-9]+)?(?:\s|$))(?=[a-zA-Z0-9:_-]*[a-zA-Z])([a-zA-Z0-9][a-zA-Z0-9:_-]*)(?=\s)/g;
 const MENTION_TOKEN_REGEX = /(^|\s)@(?:"((?:\\.|[^"\\])*)"|([^\s@"]+))(?=\s)/g;
 /**
  * The label body is bounded rather than `*`. Unbounded, every whitespace in