From 9e3e9bb4f081a6ad331cb94b42b2bd2d93339b81 Mon Sep 17 00:00:00 2001
From: Gabriel De Andrade <30420087+gabrielelpidio@users.noreply.github.com>
Date: Wed, 29 Jul 2026 21:21:16 -0400
Subject: [PATCH 01/34] fix(mobile): reduce thread feed scroll jank (#4874)

---
 .../src/features/threads/ThreadFeed.tsx       | 113 +++++++++++++++++-
 .../src/features/threads/thread-work-log.tsx  |  49 +++++++-
 apps/mobile/src/lib/appearancePreferences.ts  |  17 ++-
 3 files changed, 169 insertions(+), 10 deletions(-)

diff --git a/apps/mobile/src/features/threads/ThreadFeed.tsx b/apps/mobile/src/features/threads/ThreadFeed.tsx
index 37a8639fdbd..8ad117c8635 100644
--- a/apps/mobile/src/features/threads/ThreadFeed.tsx
+++ b/apps/mobile/src/features/threads/ThreadFeed.tsx
@@ -48,7 +48,9 @@ import { useSafeAreaInsets } from "react-native-safe-area-context";
 import Animated, {
   FadeIn,
   FadeInUp,
-  LinearTransition,
+  useSharedValue,
+  withTiming,
+  type LayoutAnimationsValues,
   type SharedValue,
 } from "react-native-reanimated";
 import { useThemeColor } from "../../lib/useThemeColor";
@@ -80,7 +82,9 @@ import { deriveCenteredContentHorizontalPadding, type LayoutVariant } from "../.
 import {
   resolveMarkdownFontSizes,
   resolveNativeMarkdownTypography,
+  scaledTypographyLineHeight,
 } from "../../lib/appearancePreferences";
+import { MOBILE_TYPOGRAPHY } from "../../lib/typography";
 import { useAppearancePreferences } from "../settings/appearance/AppearancePreferencesProvider";
 import { useAppearanceCodeSurface } from "../settings/appearance/useAppearanceCodeSurface";
 import { markdownFileIconSource } from "@t3tools/mobile-markdown-text/file-icons";
@@ -91,7 +95,12 @@ import {
   type ThreadFeedLatestTurn,
 } from "../../lib/threadActivity";
 import type { ThreadContentPresentation } from "./threadContentPresentation";
-import { ThreadWorkGroupToggle, ThreadWorkLog } from "./thread-work-log";
+import {
+  collapsedWorkLogHeight,
+  ThreadWorkGroupToggle,
+  ThreadWorkLog,
+  WORK_GROUP_TOGGLE_HEIGHT,
+} from "./thread-work-log";
 import { useMarkdownCodeHighlight } from "./markdownCodeHighlightState";
 import { useAssetUrl } from "../../state/assets";
 import { resolveWorkspaceRelativeFilePath } from "../files/filePath";
@@ -109,8 +118,22 @@ function formatMessageTime(input: string): string {
 }
 
 // Rows shift when content above them grows (streaming text, work-log folds);
-// animating the container position turns those jumps into slides.
-const FEED_ITEM_LAYOUT_TRANSITION = LinearTransition.duration(180);
+// animating the container position turns those jumps into slides. Applied
+// conditionally — see the gated transition in ThreadFeed: while browsing
+// history the animation must NOT run, or every estimate→actual size
+// correction plays as a visible slide against the instant scroll-offset
+// compensation from maintainVisibleContentPosition.
+const FEED_ITEM_LAYOUT_DURATION_MS = 180;
+
+// Pre-measurement heights for getFixedItemSize, mirroring renderFeedEntry's
+// classNames. The fold row's min-h-11 (44px) stays taller than its single
+// text-sm line at every supported base font size (26px at the 22pt maximum),
+// so its height is a constant; a drifted value costs one correction on
+// measure, not a persistent offset.
+const TURN_FOLD_HEIGHT = 56; // min-h-11 (44) + mb-3 (12)
+// The working row has no min-height clamp — its height follows the scaled
+// text-xs line height (see workingRowHeight in ThreadFeed).
+const WORKING_ROW_VERTICAL_EXTRAS = 24; // py-1 (8) + mb-4 (16)
 
 // Entering animations must only play for rows born just now — LegendList
 // remounts rows when they scroll back into view, and replaying an entrance for
@@ -1301,6 +1324,7 @@ export const ThreadFeed = memo(function ThreadFeed(props: ThreadFeedProps) {
   const headerMaterialVisibleRef = useRef(false);
   const previousLatestTurnRef = useRef(props.latestTurn);
   const { width: windowWidth } = useWindowDimensions();
+  const { appearance } = useAppearancePreferences();
   const [viewportWidth, setViewportWidth] = useState(() =>
     props.layoutVariant === "split" ? 0 : windowWidth,
   );
@@ -1410,6 +1434,11 @@ export const ThreadFeed = memo(function ThreadFeed(props: ThreadFeedProps) {
     },
     [props.onHeaderMaterialVisibilityChange],
   );
+  // True while the viewport sits within ~one screen of the list end — the
+  // only region where layout shifts should animate. Starts true because the
+  // list opens pinned to the end.
+  const nearListEnd = useSharedValue(true);
+
   const handleScroll = useCallback(
     (event: NativeSyntheticEvent<NativeScrollEvent>) => {
       // anchorTopInset, not topContentInset: under automatic insets the list
@@ -1417,9 +1446,40 @@ export const ThreadFeed = memo(function ThreadFeed(props: ThreadFeedProps) {
       // UIKit's adjustedContentInset, so topContentInset is 0 here). Add the
       // header height back or the material toggles a full header too late.
       reportHeaderMaterialVisibility(event.nativeEvent.contentOffset.y + anchorTopInset > 6);
+      const { contentOffset, contentSize, layoutMeasurement } = event.nativeEvent;
+      nearListEnd.value =
+        contentSize.height - layoutMeasurement.height - contentOffset.y < layoutMeasurement.height;
     },
-    [reportHeaderMaterialVisibility, anchorTopInset],
+    [reportHeaderMaterialVisibility, anchorTopInset, nearListEnd],
   );
+
+  // Gated variant of the 180ms feed layout slide. Instant while browsing
+  // history: maintainVisibleContentPosition compensates the scroll offset in
+  // the same frame a row's measured size lands, so an instant reposition is
+  // invisible — animating it is exactly what made cold upward scrolls slide
+  // and jump. Near the end the slide stays on: streaming growth and sends
+  // shift rows at rest, where the animation is the thing preventing a hard
+  // visual snap.
+  const feedItemLayoutTransition = useMemo(() => {
+    return (values: LayoutAnimationsValues) => {
+      "worklet";
+      const duration = nearListEnd.value ? FEED_ITEM_LAYOUT_DURATION_MS : 0;
+      return {
+        initialValues: {
+          originX: values.currentOriginX,
+          originY: values.currentOriginY,
+          width: values.currentWidth,
+          height: values.currentHeight,
+        },
+        animations: {
+          originX: withTiming(values.targetOriginX, { duration }),
+          originY: withTiming(values.targetOriginY, { duration }),
+          width: withTiming(values.targetWidth, { duration }),
+          height: withTiming(values.targetHeight, { duration }),
+        },
+      };
+    };
+  }, [nearListEnd]);
   const handleViewportLayout = useCallback((event: LayoutChangeEvent) => {
     const nextWidth = Math.round(event.nativeEvent.layout.width);
     const nextHeight = Math.round(event.nativeEvent.layout.height);
@@ -1636,6 +1696,38 @@ export const ThreadFeed = memo(function ThreadFeed(props: ThreadFeedProps) {
     setExpandedImage({ uri, headers });
   }, []);
 
+  // Rows whose height is known before they ever render. Without this, every
+  // row above the viewport is assumed to be estimatedItemSize tall, and
+  // scrolling up through unmeasured content corrects each row's height as it
+  // mounts — the feed visibly jumps. Fixed sizes make the small chrome rows
+  // exact; message rows stay undefined and use LegendList's per-type running
+  // average once one of their type has been measured. Text-driven heights
+  // follow the configurable base font size via scaledTypographyLineHeight.
+  const workingRowHeight =
+    WORKING_ROW_VERTICAL_EXTRAS +
+    scaledTypographyLineHeight(MOBILE_TYPOGRAPHY.label, appearance.baseFontSize);
+  const getFixedItemSize = useCallback(
+    (entry: ThreadFeedEntry) => {
+      switch (entry.type) {
+        case "turn-fold":
+          return TURN_FOLD_HEIGHT;
+        case "work-toggle":
+          return WORK_GROUP_TOGGLE_HEIGHT;
+        case "working":
+          return workingRowHeight;
+        case "activity-group":
+          // Expanded rows append a variable detail block — fall back to
+          // measurement for those groups.
+          return entry.activities.some((activity) => expandedWorkRows[activity.id])
+            ? undefined
+            : collapsedWorkLogHeight(entry.activities, appearance.baseFontSize);
+        default:
+          return undefined;
+      }
+    },
+    [expandedWorkRows, workingRowHeight, appearance.baseFontSize],
+  );
+
   const renderItem = useCallback(
     (info: { item: ThreadFeedEntry; index: number }) =>
       renderFeedEntry(info, {
@@ -1725,7 +1817,7 @@ export const ThreadFeed = memo(function ThreadFeed(props: ThreadFeedProps) {
                 }
               : { scrollIndicatorInsets: { top: topContentInset, bottom: 0 } })}
             {...(anchoredEndSpace ? { anchoredEndSpace } : {})}
-            itemLayoutAnimation={FEED_ITEM_LAYOUT_TRANSITION}
+            itemLayoutAnimation={feedItemLayoutTransition}
             // Patched LegendList prop (patches/@legendapp__list@3.2.0.patch):
             // lets its scroll math clamp programmatic scrolls to -headerInset
             // instead of 0, so initialScrollAtEnd/maintainScrollAtEnd on short
@@ -1769,6 +1861,10 @@ export const ThreadFeed = memo(function ThreadFeed(props: ThreadFeedProps) {
             getItemType={(entry) =>
               entry.type === "message" ? `message:${entry.message.role}` : entry.type
             }
+            getFixedItemSize={getFixedItemSize}
+            // Measure rows well before they scroll into view so estimate→actual
+            // corrections land offscreen instead of under the user's finger.
+            drawDistance={500}
             keyboardShouldPersistTaps="always"
             keyboardDismissMode="none"
             keyboardLiftBehavior="whenAtEnd"
@@ -1788,6 +1884,11 @@ export const ThreadFeed = memo(function ThreadFeed(props: ThreadFeedProps) {
             // user overscroll back to the adjusted rest position.
             scrollToOverflowEnabled
             estimatedItemSize={180}
+            // Chat-style bottom alignment: when a thread is shorter than the
+            // viewport, pad above the content so messages rest just above the
+            // composer instead of under the header. No effect on threads that
+            // overflow the viewport (the padding clamps to zero).
+            alignItemsAtEnd
             initialScrollAtEnd
             onScroll={handleScroll}
             scrollEventThrottle={16}
diff --git a/apps/mobile/src/features/threads/thread-work-log.tsx b/apps/mobile/src/features/threads/thread-work-log.tsx
index 0896335ea96..529adac1db3 100644
--- a/apps/mobile/src/features/threads/thread-work-log.tsx
+++ b/apps/mobile/src/features/threads/thread-work-log.tsx
@@ -3,8 +3,10 @@ import { type AppSymbolName, SymbolView } from "../../components/AppSymbol";
 import { LayoutAnimation, Pressable, ScrollView, useColorScheme, View } from "react-native";
 
 import { AppText as Text } from "../../components/AppText";
+import { scaledTypographyLineHeight } from "../../lib/appearancePreferences";
 import { cn } from "../../lib/cn";
 import type { ThreadFeedActivity } from "../../lib/threadActivity";
+import { MOBILE_TYPOGRAPHY } from "../../lib/typography";
 import Animated, { FadeIn } from "react-native-reanimated";
 
 const WORK_LOG_LAYOUT_ANIMATION = {
@@ -77,6 +79,46 @@ function isFreshRow(createdAt: string): boolean {
   return Number.isFinite(timestamp) && Date.now() - timestamp < FRESH_ROW_WINDOW_MS;
 }
 
+// Tool-like activities with a neutral status carry no signal worth a row.
+export function visibleWorkLogActivities(
+  activities: ReadonlyArray<ThreadFeedActivity>,
+): ReadonlyArray<ThreadFeedActivity> {
+  return activities.filter((activity) => !(activity.toolLike && activity.status === "neutral"));
+}
+
+// Pre-measurement heights for the feed's getFixedItemSize. Collapsed work-log
+// rows are single-line (numberOfLines={1}) inside a min-height that stays
+// taller than the text at every supported base font size (text-xs reaches
+// 23px at the 22pt maximum, under the 32px min-h-8), so row height is
+// deterministic. The "work log" label has no such clamp — its height follows
+// the scaled text-2xs line height. Values mirror the classNames below — keep
+// them in sync; a mismatch only costs a one-time correction on measure.
+const WORK_ROW_HEIGHT = 32; // min-h-8
+const WORK_ROW_GAP = 1; // gap-px
+const WORK_LOG_HEADER_PADDING = 2; // pb-0.5 under the "work log" label
+const WORK_LOG_BOTTOM_MARGIN = 4; // mb-1
+
+export const WORK_GROUP_TOGGLE_HEIGHT = 36; // min-h-8 (32) + mb-1 (4)
+
+export function collapsedWorkLogHeight(
+  activities: ReadonlyArray<ThreadFeedActivity>,
+  baseFontSize: number,
+): number {
+  const rows = visibleWorkLogActivities(activities);
+  if (rows.length === 0) {
+    return 0;
+  }
+  const onlyToolRows = rows.every((row) => row.toolLike);
+  const headerHeight =
+    scaledTypographyLineHeight(MOBILE_TYPOGRAPHY.caption, baseFontSize) + WORK_LOG_HEADER_PADDING;
+  return (
+    WORK_LOG_BOTTOM_MARGIN +
+    (onlyToolRows ? 0 : headerHeight) +
+    rows.length * WORK_ROW_HEIGHT +
+    (rows.length - 1) * WORK_ROW_GAP
+  );
+}
+
 export function ThreadWorkLog(props: {
   readonly activities: ReadonlyArray<ThreadFeedActivity>;
   readonly copiedRowId: string | null;
@@ -87,9 +129,10 @@ export function ThreadWorkLog(props: {
 }) {
   const colorScheme = useColorScheme();
   const pressedBackground = colorScheme === "dark" ? "rgba(255,255,255,0.05)" : "rgba(0,0,0,0.035)";
-  const rows = props.activities
-    .filter((activity) => !(activity.toolLike && activity.status === "neutral"))
-    .map((activity) => ({ ...activity, detail: compactActivityDetail(activity.detail) }));
+  const rows = visibleWorkLogActivities(props.activities).map((activity) => ({
+    ...activity,
+    detail: compactActivityDetail(activity.detail),
+  }));
 
   if (rows.length === 0) {
     return null;
diff --git a/apps/mobile/src/lib/appearancePreferences.ts b/apps/mobile/src/lib/appearancePreferences.ts
index 7287eabba7c..d2504a629dd 100644
--- a/apps/mobile/src/lib/appearancePreferences.ts
+++ b/apps/mobile/src/lib/appearancePreferences.ts
@@ -198,12 +198,27 @@ export function resolveTextScaleVariables(baseFontSize: number): Record<string,
 
   for (const [name, role] of Object.entries(TEXT_SCALE_VARIABLE_ROLES)) {
     variables[name] = Math.max(8, Math.round(role.fontSize * scale));
-    variables[`${name}--line-height`] = Math.max(10, Math.round(role.lineHeight * scale));
+    variables[`${name}--line-height`] = scaledTypographyLineHeight(role, baseFontSize);
   }
 
   return variables;
 }
 
+/**
+ * The line height a MOBILE_TYPOGRAPHY role renders at under the given base
+ * font size — the same value resolveTextScaleVariables injects for the role's
+ * `--text-*--line-height` variable. For layout code that must predict
+ * text-driven heights (e.g. the thread feed's fixed item sizes) instead of
+ * measuring them.
+ */
+export function scaledTypographyLineHeight(
+  role: { readonly lineHeight: number },
+  baseFontSize: number,
+): number {
+  const scale = normalizeBaseFontSize(baseFontSize) / DEFAULT_BASE_FONT_SIZE;
+  return Math.max(10, Math.round(role.lineHeight * scale));
+}
+
 export function resolveNativeMarkdownTypography(baseFontSize: number): NativeMarkdownTypography {
   const fontSizes = resolveMarkdownFontSizes(baseFontSize);
   return {

From 35a684000d2aa6d106aed93df52a9105883f9f3f Mon Sep 17 00:00:00 2001
From: Jono Kemball <Noojuno@users.noreply.github.com>
Date: Thu, 30 Jul 2026 13:48:01 +1200
Subject: [PATCH 02/34] fix(web): restore sidebar v2 thread actions and
 terminal icon (#4712)

---
 apps/web/src/components/SidebarV2.tsx | 93 ++++++++++++++++++++++++++-
 1 file changed, 91 insertions(+), 2 deletions(-)

diff --git a/apps/web/src/components/SidebarV2.tsx b/apps/web/src/components/SidebarV2.tsx
index be93f510c97..72ba7ef1baa 100644
--- a/apps/web/src/components/SidebarV2.tsx
+++ b/apps/web/src/components/SidebarV2.tsx
@@ -32,6 +32,7 @@ import {
   SearchIcon,
   ServerIcon,
   SquarePenIcon,
+  TerminalIcon,
   Trash2Icon,
   Undo2Icon,
 } from "lucide-react";
@@ -124,6 +125,8 @@ import {
   prStatusIndicator,
   resolveThreadPr,
   settledPrHoverColorClass,
+  terminalStatusFromRunningIds,
+  type TerminalStatusIndicator,
 } from "./ThreadStatusIndicators";
 import {
   resolveSnoozePresets,
@@ -136,6 +139,7 @@ import { ProviderInstanceIcon } from "./chat/ProviderInstanceIcon";
 import { getTriggerDisplayModelLabel } from "./chat/providerIconUtils";
 import { deriveProviderInstanceEntries, type ProviderInstanceEntry } from "../providerInstances";
 import { primaryServerProvidersAtom } from "../state/server";
+import { useThreadRunningTerminalIds } from "../state/terminalSessions";
 import { stackedThreadToast, toastManager } from "./ui/toast";
 import { CommandDialogTrigger } from "./ui/command";
 import { Button } from "./ui/button";
@@ -220,6 +224,10 @@ function WorkingDuration(props: { startedAt: string | null }) {
   );
 }
 
+function terminalProcessLabel(count: number): string {
+  return `${count} terminal ${count === 1 ? "process" : "processes"} running`;
+}
+
 function SidebarV2ThreadTooltip({
   thread,
   projectTitle,
@@ -229,6 +237,8 @@ function SidebarV2ThreadTooltip({
   modelInstanceId,
   modelLabel,
   branchMismatch,
+  terminalStatus,
+  terminalProcessCount,
 }: {
   thread: SidebarThreadSummary;
   projectTitle: string | null;
@@ -241,6 +251,8 @@ function SidebarV2ThreadTooltip({
     threadBranch: string;
     currentBranch: string;
   } | null;
+  terminalStatus: TerminalStatusIndicator | null;
+  terminalProcessCount: number;
 }) {
   return (
     <TooltipPopup
@@ -295,6 +307,17 @@ function SidebarV2ThreadTooltip({
               <div className="min-w-0 truncate text-foreground/75">{modelLabel}</div>
             </div>
           ) : null}
+          {terminalStatus ? (
+            <div className="flex min-w-0 items-center gap-2">
+              <TerminalIcon
+                aria-hidden
+                className={cn("size-3 shrink-0", terminalStatus.colorClass)}
+              />
+              <div className="min-w-0 truncate text-foreground/75">
+                {terminalProcessLabel(terminalProcessCount)}
+              </div>
+            </div>
+          ) : null}
           {thread.session?.lastError ? (
             <div className="flex min-w-0 items-center gap-2 text-red-600 dark:text-red-400">
               <CircleAlertIcon className="size-3 shrink-0 stroke-current" />
@@ -424,6 +447,12 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
   const lastVisitedAt = useUiStateStore((state) => state.threadLastVisitedAtById[threadKey]);
   const isSelected = useThreadSelectionStore((state) => state.selectedThreadKeys.has(threadKey));
   const openPrLink = useOpenPrLink();
+  const runningTerminalIds = useThreadRunningTerminalIds({
+    environmentId: thread.environmentId,
+    threadId: thread.id,
+  });
+  const terminalStatus = terminalStatusFromRunningIds(runningTerminalIds);
+  const terminalProcessCount = runningTerminalIds.length;
 
   // Same semantics as v1 (never-visited counts as read): flipping the beta
   // flag must not light up every historical thread as unread.
@@ -542,6 +571,8 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
       modelInstanceId={modelInstanceId}
       modelLabel={modelLabel}
       branchMismatch={branchMismatch}
+      terminalStatus={terminalStatus}
+      terminalProcessCount={terminalProcessCount}
     />
   );
 
@@ -735,6 +766,16 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
         #{pr.number}
       </button>
     ) : null;
+  const terminalStatusIcon = terminalStatus ? (
+    <span
+      role="img"
+      aria-label={terminalProcessLabel(terminalProcessCount)}
+      data-testid={`sidebar-v2-terminal-status-${thread.id}`}
+      className={cn("inline-flex shrink-0 items-center justify-center", terminalStatus.colorClass)}
+    >
+      <TerminalIcon className={cn("size-3.5", terminalStatus.pulse && "animate-status-pulse")} />
+    </span>
+  ) : null;
 
   if (variant === "slim") {
     return (
@@ -774,6 +815,7 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
               />
             </span>
             {title}
+            {terminalStatusIcon}
             {/* The PR badge stays outside the hover-fading slot: it must
               remain visible AND clickable while the row is hovered. Only
               the time/jump label yields to the settle affordance. */}
@@ -960,6 +1002,7 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
               ) : (
                 <span className="flex-1" />
               )}
+              {terminalStatusIcon}
               {prBadge}
               {diff ? (
                 <span className="shrink-0 font-mono">
@@ -1028,7 +1071,7 @@ export default function SidebarV2() {
     reportFailure: false,
   });
   const updateSettings = useUpdateClientSettings();
-  const { copyToClipboard: copyProjectPath } = useCopyToClipboard<{ path: string }>({
+  const { copyToClipboard: copyPathToClipboard } = useCopyToClipboard<{ path: string }>({
     onCopy: ({ path }) => {
       toastManager.add({
         type: "success",
@@ -1046,6 +1089,25 @@ export default function SidebarV2() {
       );
     },
   });
+  const { copyToClipboard: copyBranchToClipboard } = useCopyToClipboard<{ branch: string }>({
+    target: "branch name",
+    onCopy: ({ branch }) => {
+      toastManager.add({
+        type: "success",
+        title: "Branch copied",
+        description: branch,
+      });
+    },
+    onError: (error) => {
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Failed to copy branch",
+          description: error instanceof Error ? error.message : "An error occurred.",
+        }),
+      );
+    },
+  });
   const [projectActionsTarget, setProjectActionsTarget] = useState<SidebarProjectSnapshot | null>(
     null,
   );
@@ -1985,6 +2047,10 @@ export default function SidebarV2() {
         }
         const thread = threadByKeyRef.current.get(threadKey);
         if (!thread) return;
+        const threadWorkspacePath =
+          thread.worktreePath ??
+          projectCwdByKey.get(`${thread.environmentId}:${thread.projectId}`) ??
+          null;
         // Un-settle works on every settled row: for explicit settles it
         // clears the override, for auto-settled rows it pins the thread
         // active until real activity clears the pin. Environments without
@@ -2033,6 +2099,8 @@ export default function SidebarV2() {
                 : []),
               { id: "rename", label: "Rename thread" },
               { id: "mark-unread", label: "Mark unread" },
+              { id: "copy-path", label: "Copy path", icon: "copy" },
+              ...(thread.branch ? [{ id: "copy-branch", label: "Copy branch", icon: "copy" }] : []),
               { id: "delete", label: "Delete", destructive: true, icon: "trash" },
             ],
             position,
@@ -2085,6 +2153,24 @@ export default function SidebarV2() {
           case "mark-unread":
             markThreadUnread(threadKey, thread.latestTurn?.completedAt);
             return;
+          case "copy-path":
+            if (!threadWorkspacePath) {
+              toastManager.add(
+                stackedThreadToast({
+                  type: "error",
+                  title: "Path unavailable",
+                  description: "This thread does not have a workspace path to copy.",
+                }),
+              );
+              return;
+            }
+            copyPathToClipboard(threadWorkspacePath, { path: threadWorkspacePath });
+            return;
+          case "copy-branch":
+            if (thread.branch) {
+              copyBranchToClipboard(thread.branch, { branch: thread.branch });
+            }
+            return;
           case "delete": {
             if (confirmThreadDelete) {
               const confirmed = await settlePromise(() =>
@@ -2122,9 +2208,12 @@ export default function SidebarV2() {
       attemptUnsettle,
       attemptUnsnooze,
       confirmThreadDelete,
+      copyBranchToClipboard,
+      copyPathToClipboard,
       deleteThread,
       handleMultiSelectContextMenu,
       markThreadUnread,
+      projectCwdByKey,
       serverConfigs,
       startThreadRename,
     ],
@@ -2600,7 +2689,7 @@ export default function SidebarV2() {
                       aria-label="Copy project path"
                       title="Copy project path"
                       onClick={() =>
-                        copyProjectPath(member.workspaceRoot, { path: member.workspaceRoot })
+                        copyPathToClipboard(member.workspaceRoot, { path: member.workspaceRoot })
                       }
                     >
                       <CopyIcon className="size-3.5" />

From 2d9066e089c241c3befd7a4632efe493fabd70d9 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Wed, 29 Jul 2026 19:01:24 -0700
Subject: [PATCH 03/34] fix(web): settle button now works on hover, not just
 right-click (#4905)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---
 apps/web/src/components/SidebarV2.tsx | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/apps/web/src/components/SidebarV2.tsx b/apps/web/src/components/SidebarV2.tsx
index 72ba7ef1baa..33c2512abf7 100644
--- a/apps/web/src/components/SidebarV2.tsx
+++ b/apps/web/src/components/SidebarV2.tsx
@@ -932,9 +932,12 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
                   the hidden state out of flow lets the project label reclaim
                   space without either state overlapping it. */}
               <span className="group/v2-status-slot relative ml-auto flex h-5 min-w-8 shrink-0 items-stretch justify-end text-xs">
+                {/* pointer-events-none: while hovered this label is absolute
+                    + opacity-0, which paints it ABOVE the in-flow settle/snooze
+                    buttons; without it the invisible label eats their clicks. */}
                 <span
                   className={cn(
-                    "self-center justify-self-end tabular-nums text-muted-foreground/65 transition-opacity group-focus-within/v2-status-slot:absolute group-focus-within/v2-status-slot:right-0 group-hover/v2-row:absolute group-hover/v2-row:right-0 group-hover/v2-row:opacity-0",
+                    "pointer-events-none self-center justify-self-end tabular-nums text-muted-foreground/65 transition-opacity group-focus-within/v2-status-slot:absolute group-focus-within/v2-status-slot:right-0 group-hover/v2-row:absolute group-hover/v2-row:right-0 group-hover/v2-row:opacity-0",
                     snoozeMenuOpen && "absolute right-0 opacity-0",
                   )}
                 >

From 758decaa565f021f85af756669b18bd9f80cacf5 Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Thu, 30 Jul 2026 04:14:06 +0200
Subject: [PATCH 04/34] fix(clients): disable add project while disconnected
 (#4834)

---
 .../projects/AddProjectScreen.logic.test.ts   |  41 ++++++
 .../projects/AddProjectScreen.logic.ts        |  26 ++++
 .../features/projects/AddProjectScreen.tsx    | 119 ++++++++++++------
 .../features/threads/NewTaskRouteScreen.tsx   |  30 +++--
 apps/web/src/components/CommandPalette.tsx    |  66 +++++++++-
 .../src/operations/projects.test.ts           |  10 ++
 .../client-runtime/src/operations/projects.ts |   7 ++
 7 files changed, 243 insertions(+), 56 deletions(-)
 create mode 100644 apps/mobile/src/features/projects/AddProjectScreen.logic.test.ts
 create mode 100644 apps/mobile/src/features/projects/AddProjectScreen.logic.ts

diff --git a/apps/mobile/src/features/projects/AddProjectScreen.logic.test.ts b/apps/mobile/src/features/projects/AddProjectScreen.logic.test.ts
new file mode 100644
index 00000000000..3464bfda260
--- /dev/null
+++ b/apps/mobile/src/features/projects/AddProjectScreen.logic.test.ts
@@ -0,0 +1,41 @@
+import type { EnvironmentConnectionPhase } from "@t3tools/client-runtime/connection";
+import { EnvironmentId } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { resolveAddProjectEnvironment } from "./AddProjectScreen.logic";
+
+const ENVIRONMENT_A = EnvironmentId.make("environment-a");
+const ENVIRONMENT_B = EnvironmentId.make("environment-b");
+
+function environment(environmentId: EnvironmentId, connectionState: EnvironmentConnectionPhase) {
+  return { environmentId, connectionState };
+}
+
+describe("resolveAddProjectEnvironment", () => {
+  it("does not redirect an explicit unavailable environment to another environment", () => {
+    expect(
+      resolveAddProjectEnvironment(
+        [environment(ENVIRONMENT_A, "offline"), environment(ENVIRONMENT_B, "connected")],
+        ENVIRONMENT_A,
+      ),
+    ).toBeNull();
+  });
+
+  it("resolves an explicit connected environment", () => {
+    expect(
+      resolveAddProjectEnvironment(
+        [environment(ENVIRONMENT_A, "connected"), environment(ENVIRONMENT_B, "connected")],
+        ENVIRONMENT_A,
+      )?.environmentId,
+    ).toBe(ENVIRONMENT_A);
+  });
+
+  it("defaults to the first connected environment when no environment is requested", () => {
+    expect(
+      resolveAddProjectEnvironment(
+        [environment(ENVIRONMENT_A, "offline"), environment(ENVIRONMENT_B, "connected")],
+        null,
+      )?.environmentId,
+    ).toBe(ENVIRONMENT_B);
+  });
+});
diff --git a/apps/mobile/src/features/projects/AddProjectScreen.logic.ts b/apps/mobile/src/features/projects/AddProjectScreen.logic.ts
new file mode 100644
index 00000000000..b208a1719ab
--- /dev/null
+++ b/apps/mobile/src/features/projects/AddProjectScreen.logic.ts
@@ -0,0 +1,26 @@
+import { canCreateProjectInEnvironment } from "@t3tools/client-runtime/operations/projects";
+import type { EnvironmentConnectionPhase } from "@t3tools/client-runtime/connection";
+import type { EnvironmentId } from "@t3tools/contracts";
+
+export function resolveAddProjectEnvironment<
+  T extends {
+    readonly environmentId: EnvironmentId;
+    readonly connectionState: EnvironmentConnectionPhase;
+  },
+>(environmentOptions: ReadonlyArray<T>, requestedEnvironmentId: EnvironmentId | null): T | null {
+  if (requestedEnvironmentId !== null) {
+    return (
+      environmentOptions.find(
+        (environment) =>
+          environment.environmentId === requestedEnvironmentId &&
+          canCreateProjectInEnvironment(environment.connectionState),
+      ) ?? null
+    );
+  }
+
+  return (
+    environmentOptions.find((environment) =>
+      canCreateProjectInEnvironment(environment.connectionState),
+    ) ?? null
+  );
+}
diff --git a/apps/mobile/src/features/projects/AddProjectScreen.tsx b/apps/mobile/src/features/projects/AddProjectScreen.tsx
index eef40382b24..39e6bda3c44 100644
--- a/apps/mobile/src/features/projects/AddProjectScreen.tsx
+++ b/apps/mobile/src/features/projects/AddProjectScreen.tsx
@@ -4,12 +4,17 @@ import {
   addProjectRemoteSourceProvider,
   buildAddProjectRemoteSourceReadiness,
   buildProjectCreateCommand,
+  canCreateProjectInEnvironment,
   findExistingAddProject,
   getAddProjectInitialQuery,
   resolveAddProjectPath,
   sortAddProjectProviderSources,
   type AddProjectRemoteSource,
 } from "@t3tools/client-runtime/operations/projects";
+import {
+  connectionStatusText,
+  type EnvironmentConnectionPhase,
+} from "@t3tools/client-runtime/connection";
 import {
   canPreloadBrowsePath,
   createBrowseNavigationCoordinator,
@@ -24,7 +29,7 @@ import {
 import { CommandId, type EnvironmentId, ProjectId } from "@t3tools/contracts";
 import { StackActions, useNavigation } from "@react-navigation/native";
 import { SymbolView } from "../../components/AppSymbol";
-import { useCallback, useEffect, useMemo, useState, type ReactNode } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
 import { ActivityIndicator, Alert, Pressable, ScrollView, View } from "react-native";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 import * as Arr from "effect/Array";
@@ -46,15 +51,20 @@ import { uuidv4 } from "../../lib/uuid";
 import { useAtomCommand } from "../../state/use-atom-command";
 import { useAtomQueryRunner } from "../../state/use-atom-query-runner";
 import {
+  useRemoteConnectionStatus,
   useRemoteEnvironmentRuntime,
   useSavedRemoteConnections,
 } from "../../state/use-remote-environment-registry";
+import { resolveAddProjectEnvironment } from "./AddProjectScreen.logic";
 
 interface EnvironmentOption {
   readonly environmentId: EnvironmentId;
   readonly label: string;
   readonly platform: string;
   readonly baseDirectory: string | null;
+  readonly connectionState: EnvironmentConnectionPhase;
+  readonly connectionError: string | null;
+  readonly connectionErrorTraceId: string | null;
 }
 
 const environmentOptionOrder = Order.mapInput(
@@ -227,10 +237,13 @@ function ProjectPathInput(props: {
 }
 
 function useBrowsePathInput(environment: EnvironmentOption | null) {
+  const environmentId = environment?.environmentId ?? null;
+  const environmentBaseDirectory = environment?.baseDirectory ?? null;
   const [pathInput, commitPathInput] = useState(() =>
-    getAddProjectInitialQuery(environment?.baseDirectory),
+    getAddProjectInitialQuery(environmentBaseDirectory),
   );
-  const environmentRuntime = useRemoteEnvironmentRuntime(environment?.environmentId ?? null);
+  const previousEnvironmentIdRef = useRef(environmentId);
+  const environmentRuntime = useRemoteEnvironmentRuntime(environmentId);
   const loadBrowsePath = useAtomQueryRunner(filesystemEnvironment.browse, {
     reportFailure: false,
     reportDefect: false,
@@ -268,10 +281,11 @@ function useBrowsePathInput(environment: EnvironmentOption | null) {
   );
 
   useEffect(() => {
-    if (environment) {
-      setPathInput(getAddProjectInitialQuery(environment.baseDirectory));
+    if (environmentId !== null && environmentId !== previousEnvironmentIdRef.current) {
+      previousEnvironmentIdRef.current = environmentId;
+      setPathInput(getAddProjectInitialQuery(environmentBaseDirectory));
     }
-  }, [environment, setPathInput]);
+  }, [environmentBaseDirectory, environmentId, setPathInput]);
 
   useEffect(
     () => () => {
@@ -286,19 +300,27 @@ function useBrowsePathInput(environment: EnvironmentOption | null) {
 function useEnvironmentOptions(): ReadonlyArray<EnvironmentOption> {
   const serverConfigByEnvironmentId = useServerConfigs();
   const { savedConnectionsById } = useSavedRemoteConnections();
+  const { connectedEnvironments } = useRemoteConnectionStatus();
 
   return useMemo<ReadonlyArray<EnvironmentOption>>(() => {
+    const runtimeByEnvironmentId = new Map(
+      connectedEnvironments.map((environment) => [environment.environmentId, environment] as const),
+    );
     const options = Object.values(savedConnectionsById).map((connection) => {
       const config = serverConfigByEnvironmentId.get(connection.environmentId);
+      const runtime = runtimeByEnvironmentId.get(connection.environmentId);
       return {
         environmentId: connection.environmentId,
         label: connection.environmentLabel,
         platform: platformFromOs(config?.environment.platform.os ?? null),
         baseDirectory: config?.settings.addProjectBaseDirectory ?? null,
+        connectionState: runtime?.connectionState ?? "available",
+        connectionError: runtime?.connectionError ?? null,
+        connectionErrorTraceId: runtime?.connectionErrorTraceId ?? null,
       };
     });
     return Arr.sort(options, environmentOptionOrder);
-  }, [savedConnectionsById, serverConfigByEnvironmentId]);
+  }, [connectedEnvironments, savedConnectionsById, serverConfigByEnvironmentId]);
 }
 
 function useSelectedEnvironment(): {
@@ -309,8 +331,14 @@ function useSelectedEnvironment(): {
   const [selectedEnvironmentId, setSelectedEnvironmentId] = useState<EnvironmentId | null>(null);
   const environmentOptions = useEnvironmentOptions();
   const selectedEnvironment =
-    environmentOptions.find((environment) => environment.environmentId === selectedEnvironmentId) ??
-    environmentOptions[0] ??
+    environmentOptions.find(
+      (environment) =>
+        environment.environmentId === selectedEnvironmentId &&
+        canCreateProjectInEnvironment(environment.connectionState),
+    ) ??
+    environmentOptions.find((environment) =>
+      canCreateProjectInEnvironment(environment.connectionState),
+    ) ??
     null;
 
   return {
@@ -325,9 +353,9 @@ function EmptyEnvironmentState() {
 
   return (
     <View className="items-center gap-3 rounded-2xl bg-card px-5 py-8">
-      <Text className="text-center text-lg font-t3-bold">No environments connected</Text>
+      <Text className="text-center text-lg font-t3-bold">Environment unavailable</Text>
       <Text className="text-center text-sm leading-normal text-foreground-muted">
-        Add an environment before adding a project.
+        Start or reconnect an environment before adding a project.
       </Text>
       <Pressable
         onPress={() => navigation.dispatch(StackActions.replace("ConnectionsNew"))}
@@ -407,17 +435,25 @@ export function AddProjectSourceScreen() {
 
   return (
     <AddProjectShell>
-      {environmentOptions.length === 0 ? <EmptyEnvironmentState /> : null}
+      {selectedEnvironment === null ? <EmptyEnvironmentState /> : null}
 
       {environmentOptions.length > 1 ? (
         <>
-          <SectionTitle>Connected environments</SectionTitle>
+          <SectionTitle>Environments</SectionTitle>
           <ListSection>
             {environmentOptions.map((environment, index) => (
               <ListRow
                 key={environment.environmentId}
                 title={environment.label}
-                subtitle={environment.environmentId}
+                subtitle={
+                  canCreateProjectInEnvironment(environment.connectionState)
+                    ? environment.environmentId
+                    : connectionStatusText({
+                        phase: environment.connectionState,
+                        error: environment.connectionError,
+                        traceId: environment.connectionErrorTraceId,
+                      })
+                }
                 icon={
                   <SymbolView
                     name="server.rack"
@@ -427,6 +463,7 @@ export function AddProjectSourceScreen() {
                   />
                 }
                 selected={environment.environmentId === selectedEnvironment?.environmentId}
+                disabled={!canCreateProjectInEnvironment(environment.connectionState)}
                 isFirst={index === 0}
                 right={
                   environment.environmentId === selectedEnvironment?.environmentId ? (
@@ -500,7 +537,7 @@ function useCreateProject(environment: EnvironmentOption | null) {
 
   return useCallback(
     async (workspaceRoot: string) => {
-      if (!environment) return;
+      if (!environment || !canCreateProjectInEnvironment(environment.connectionState)) return;
 
       const existing = findExistingAddProject({
         projects,
@@ -551,11 +588,7 @@ function useEnvironmentFromParam(
 ): EnvironmentOption | null {
   const environmentOptions = useEnvironmentOptions();
   const environmentId = stringParam(environmentIdParam) as EnvironmentId | null;
-  return (
-    environmentOptions.find((environment) => environment.environmentId === environmentId) ??
-    environmentOptions[0] ??
-    null
-  );
+  return resolveAddProjectEnvironment(environmentOptions, environmentId);
 }
 
 export function AddProjectRepositoryScreen(props: {
@@ -619,26 +652,32 @@ export function AddProjectRepositoryScreen(props: {
   return (
     <AddProjectShell>
       {error ? <ErrorBanner message={error} /> : null}
-      <TextInput
-        className="h-12 min-h-12 rounded-[24px] px-4 py-0 text-base leading-snug"
-        value={repositoryInput}
-        onChangeText={setRepositoryInput}
-        autoCapitalize="none"
-        autoCorrect={false}
-        placeholder={
-          source === "url"
-            ? "https://github.com/org/repo.git"
-            : addProjectRemoteSourcePathHint(source)
-        }
-        returnKeyType="next"
-        onSubmitEditing={() => void lookupRepository()}
-      />
-      <PrimaryActionButton
-        label={source === "url" ? "Continue" : "Lookup repository"}
-        disabled={isSubmitting || repositoryInput.trim().length === 0}
-        onPress={() => void lookupRepository()}
-        loading={isSubmitting}
-      />
+      {environment ? (
+        <>
+          <TextInput
+            className="h-12 min-h-12 rounded-[24px] px-4 py-0 text-base leading-snug"
+            value={repositoryInput}
+            onChangeText={setRepositoryInput}
+            autoCapitalize="none"
+            autoCorrect={false}
+            placeholder={
+              source === "url"
+                ? "https://github.com/org/repo.git"
+                : addProjectRemoteSourcePathHint(source)
+            }
+            returnKeyType="next"
+            onSubmitEditing={() => void lookupRepository()}
+          />
+          <PrimaryActionButton
+            label={source === "url" ? "Continue" : "Lookup repository"}
+            disabled={isSubmitting || repositoryInput.trim().length === 0}
+            onPress={() => void lookupRepository()}
+            loading={isSubmitting}
+          />
+        </>
+      ) : (
+        <EmptyEnvironmentState />
+      )}
     </AddProjectShell>
   );
 }
diff --git a/apps/mobile/src/features/threads/NewTaskRouteScreen.tsx b/apps/mobile/src/features/threads/NewTaskRouteScreen.tsx
index 99985385ea7..2005196f6bb 100644
--- a/apps/mobile/src/features/threads/NewTaskRouteScreen.tsx
+++ b/apps/mobile/src/features/threads/NewTaskRouteScreen.tsx
@@ -203,13 +203,17 @@ export function NewTaskRouteScreen({ route }: StaticScreenProps<NewTaskRoutePara
             title={screenTitle}
             subtitle={incomingShareSubtitle}
             onBack={layout.usesSplitView ? () => navigation.goBack() : undefined}
-            actions={[
-              {
-                accessibilityLabel: "Add project",
-                icon: "plus",
-                onPress: () => navigation.navigate("NewTaskSheet", { screen: "AddProject" }),
-              },
-            ]}
+            actions={
+              catalogState.hasReadyEnvironment
+                ? [
+                    {
+                      accessibilityLabel: "Add project",
+                      icon: "plus",
+                      onPress: () => navigation.navigate("NewTaskSheet", { screen: "AddProject" }),
+                    },
+                  ]
+                : []
+            }
           />
         </>
       ) : (
@@ -229,11 +233,13 @@ export function NewTaskRouteScreen({ route }: StaticScreenProps<NewTaskRoutePara
                 separateBackground
               />
             ) : null}
-            <NativeHeaderToolbar.Button
-              icon="plus"
-              onPress={() => navigation.navigate("NewTaskSheet", { screen: "AddProject" })}
-              separateBackground
-            />
+            {catalogState.hasReadyEnvironment ? (
+              <NativeHeaderToolbar.Button
+                icon="plus"
+                onPress={() => navigation.navigate("NewTaskSheet", { screen: "AddProject" })}
+                separateBackground
+              />
+            ) : null}
           </NativeHeaderToolbar>
         </>
       )}
diff --git a/apps/web/src/components/CommandPalette.tsx b/apps/web/src/components/CommandPalette.tsx
index b4e874017d4..45b5e117600 100644
--- a/apps/web/src/components/CommandPalette.tsx
+++ b/apps/web/src/components/CommandPalette.tsx
@@ -1,6 +1,8 @@
 "use client";
 
 import { scopeProjectRef, scopeThreadRef } from "@t3tools/client-runtime/environment";
+import { canCreateProjectInEnvironment } from "@t3tools/client-runtime/operations/projects";
+import { connectionStatusText } from "@t3tools/client-runtime/connection";
 import {
   canPreloadBrowsePath,
   createBrowseNavigationCoordinator,
@@ -163,6 +165,8 @@ interface AddProjectEnvironmentOption {
   readonly environmentId: EnvironmentId;
   readonly label: string;
   readonly isPrimary: boolean;
+  readonly isConnected: boolean;
+  readonly status: string;
 }
 
 type AddProjectRemoteProviderKind = Extract<
@@ -620,6 +624,8 @@ function OpenCommandPaletteDialog(props: {
           runtimeLabel: environment.label,
         }),
         isPrimary,
+        isConnected: canCreateProjectInEnvironment(environment.connection.phase),
+        status: connectionStatusText(environment.connection),
       };
     });
 
@@ -632,10 +638,14 @@ function OpenCommandPaletteDialog(props: {
 
     return options;
   }, [environments]);
-  const defaultAddProjectEnvironmentId = addProjectEnvironmentOptions[0]?.environmentId ?? null;
+  const defaultAddProjectEnvironmentId =
+    addProjectEnvironmentOptions.find((option) => option.isConnected)?.environmentId ?? null;
   const wslAddProjectEnvironmentOption = useMemo(
     () =>
       addProjectEnvironmentOptions.find((option) => {
+        if (!option.isConnected) {
+          return false;
+        }
         const environment = environments.find(
           (candidate) => candidate.environmentId === option.environmentId,
         );
@@ -1108,6 +1118,19 @@ function OpenCommandPaletteDialog(props: {
 
   const startAddProjectSourceSelection = useCallback(
     (environmentId: EnvironmentId): void => {
+      const environment = environments.find(
+        (candidate) => candidate.environmentId === environmentId,
+      );
+      if (!canCreateProjectInEnvironment(environment?.connection.phase)) {
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Environment unavailable",
+            description: `${environment?.label ?? "The selected environment"} is not connected.`,
+          }),
+        );
+        return;
+      }
       setAddProjectEnvironmentId(environmentId);
       setAddProjectCloneFlow(null);
       pushPaletteView({
@@ -1123,6 +1146,7 @@ function OpenCommandPaletteDialog(props: {
     [
       browseEnvironmentId,
       buildAddProjectSourceGroups,
+      environments,
       pushPaletteView,
       sourceControlDiscovery.data,
     ],
@@ -1134,7 +1158,12 @@ function OpenCommandPaletteDialog(props: {
       value: `action:add-project:environment:${option.environmentId}`,
       searchTerms: [option.label, option.environmentId, option.isPrimary ? "this device" : ""],
       title: option.label,
-      description: option.isPrimary ? "This device" : option.environmentId,
+      description: option.isConnected
+        ? option.isPrimary
+          ? "This device"
+          : option.environmentId
+        : option.status,
+      disabled: !option.isConnected,
       icon: <FolderPlusIcon className={ITEM_ICON_CLASS} />,
       keepOpen: true,
       run: async () => {
@@ -1155,7 +1184,7 @@ function OpenCommandPaletteDialog(props: {
   );
 
   const openAddProjectFlow = useCallback(() => {
-    if (addProjectEnvironmentOptions.length > 1) {
+    if (addProjectEnvironmentOptions.length > 1 || defaultAddProjectEnvironmentId === null) {
       pushPaletteView({
         addonIcon: <FolderPlusIcon className={ADDON_ICON_CLASS} />,
         groups: addProjectEnvironmentGroups,
@@ -1294,6 +1323,7 @@ function OpenCommandPaletteDialog(props: {
       "environment",
     ],
     title: "Add project",
+    disabled: defaultAddProjectEnvironmentId === null,
     icon: <FolderPlusIcon className={ITEM_ICON_CLASS} />,
     keepOpen: true,
     run: async () => {
@@ -1355,6 +1385,19 @@ function OpenCommandPaletteDialog(props: {
       readonly platform: string;
       readonly currentProjectCwd: string | null;
     }) => {
+      const environment = environments.find(
+        (candidate) => candidate.environmentId === input.environmentId,
+      );
+      if (!canCreateProjectInEnvironment(environment?.connection.phase)) {
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Environment unavailable",
+            description: `${environment?.label ?? "The selected environment"} is not connected.`,
+          }),
+        );
+        return;
+      }
       const rawCwd = input.rawCwd;
 
       if (isUnsupportedWindowsProjectPath(rawCwd.trim(), input.platform)) {
@@ -1507,6 +1550,16 @@ function OpenCommandPaletteDialog(props: {
     if (!addProjectCloneFlow) {
       return;
     }
+    if (!canCreateProjectInEnvironment(browseEnvironment?.connection.phase)) {
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Environment unavailable",
+          description: `${browseEnvironment?.label ?? "The selected environment"} is not connected.`,
+        }),
+      );
+      return;
+    }
 
     if (addProjectCloneFlow.step === "repository") {
       const rawRepository = query.trim();
@@ -1711,7 +1764,10 @@ function OpenCommandPaletteDialog(props: {
     getCommandPaletteInputPlaceholder(paletteMode);
   const isSubmenu = paletteMode === "submenu" || paletteMode === "submenu-browse";
   const hasHighlightedBrowseItem = highlightedItemValue?.startsWith("browse:") ?? false;
-  const canSubmitBrowsePath = isBrowsing && !relativePathNeedsActiveProject;
+  const canSubmitBrowsePath =
+    isBrowsing &&
+    !relativePathNeedsActiveProject &&
+    canCreateProjectInEnvironment(browseEnvironment?.connection.phase);
   const willCreateProjectPath =
     canSubmitBrowsePath &&
     !isBrowsePending &&
@@ -1738,6 +1794,7 @@ function OpenCommandPaletteDialog(props: {
   const canSubmitRemoteProjectFlow =
     addProjectCloneFlow?.step === "repository" &&
     query.trim().length > 0 &&
+    canCreateProjectInEnvironment(browseEnvironment?.connection.phase) &&
     !isRemoteProjectPending;
   const fileManagerName = getLocalFileManagerName(navigator.platform);
   const canOpenProjectFromFileManager =
@@ -2063,6 +2120,7 @@ function OpenCommandPaletteDialog(props: {
                     )}
                     aria-label={`${submitActionLabel} (${addShortcutLabel})`}
                     disabled={
+                      !canCreateProjectInEnvironment(browseEnvironment?.connection.phase) ||
                       relativePathNeedsActiveProject ||
                       (isCloneDestinationStep && isRemoteProjectPending)
                     }
diff --git a/packages/client-runtime/src/operations/projects.test.ts b/packages/client-runtime/src/operations/projects.test.ts
index 11b49742460..4cca703c145 100644
--- a/packages/client-runtime/src/operations/projects.test.ts
+++ b/packages/client-runtime/src/operations/projects.test.ts
@@ -10,6 +10,7 @@ import * as Option from "effect/Option";
 import {
   buildAddProjectRemoteSourceReadiness,
   buildProjectCreateCommand,
+  canCreateProjectInEnvironment,
   findExistingAddProject,
   getAddProjectInitialQuery,
   resolveAddProjectPath,
@@ -18,6 +19,15 @@ import {
 import type { EnvironmentProject } from "../state/models.ts";
 
 describe("add project shared logic", () => {
+  it("only allows project creation in connected environments", () => {
+    expect(canCreateProjectInEnvironment("connected")).toBe(true);
+    expect(canCreateProjectInEnvironment("available")).toBe(false);
+    expect(canCreateProjectInEnvironment("offline")).toBe(false);
+    expect(canCreateProjectInEnvironment("connecting")).toBe(false);
+    expect(canCreateProjectInEnvironment("reconnecting")).toBe(false);
+    expect(canCreateProjectInEnvironment("error")).toBe(false);
+  });
+
   it("resolves initial browse paths from settings", () => {
     expect(getAddProjectInitialQuery("")).toBe("~/");
     expect(getAddProjectInitialQuery("/work")).toBe("/work/");
diff --git a/packages/client-runtime/src/operations/projects.ts b/packages/client-runtime/src/operations/projects.ts
index 6ae6e18baa2..056f96b21de 100644
--- a/packages/client-runtime/src/operations/projects.ts
+++ b/packages/client-runtime/src/operations/projects.ts
@@ -1,3 +1,4 @@
+import type { EnvironmentConnectionPhase } from "../connection/presentation.ts";
 import type {
   CommandId,
   EnvironmentId,
@@ -27,6 +28,12 @@ export type AddProjectRemoteProviderKind = Extract<
 >;
 export type AddProjectRemoteSource = AddProjectRemoteProviderKind | "url";
 
+export function canCreateProjectInEnvironment(
+  connectionPhase: EnvironmentConnectionPhase | null | undefined,
+): boolean {
+  return connectionPhase === "connected";
+}
+
 export type AddProjectRemoteSourceReadiness = Record<
   AddProjectRemoteSource,
   { readonly ready: boolean; readonly hint: string | null }

From b125b7635170ec0c33f8ddf39299155a21f8c9b9 Mon Sep 17 00:00:00 2001
From: Max Katz <me@maxkatz.me>
Date: Thu, 30 Jul 2026 06:35:53 +0400
Subject: [PATCH 05/34] fix(composer): hide default Codex service tier (#4784)

---
 .../src/components/chat/TraitsPicker.test.ts  | 24 +++++++++++++++----
 apps/web/src/components/chat/TraitsPicker.tsx | 14 +++++++++++
 2 files changed, 33 insertions(+), 5 deletions(-)

diff --git a/apps/web/src/components/chat/TraitsPicker.test.ts b/apps/web/src/components/chat/TraitsPicker.test.ts
index 93157490090..0cb199d64ba 100644
--- a/apps/web/src/components/chat/TraitsPicker.test.ts
+++ b/apps/web/src/components/chat/TraitsPicker.test.ts
@@ -1,10 +1,10 @@
 import { describe, expect, it } from "vite-plus/test";
-import type { ProviderOptionDescriptor } from "@t3tools/contracts";
+import { ProviderDriverKind, type ProviderOptionDescriptor } from "@t3tools/contracts";
 import { buildTraitsTriggerDisplay } from "./TraitsPicker";
 
 function selectDescriptor(
   id: string,
-  options: ReadonlyArray<{ id: string; label: string }>,
+  options: ReadonlyArray<{ id: string; label: string; isDefault?: boolean }>,
   currentValue: string,
 ): Extract<ProviderOptionDescriptor, { type: "select" }> {
   return { id, label: id, type: "select", options: [...options], currentValue };
@@ -17,7 +17,7 @@ function fastModeDescriptor(
 }
 
 const EFFORT = selectDescriptor(
-  "effort",
+  "reasoningEffort",
   [
     { id: "high", label: "High" },
     { id: "max", label: "Max" },
@@ -33,10 +33,13 @@ const CONTEXT_WINDOW = selectDescriptor(
   "1m",
 );
 
+const CODEX = ProviderDriverKind.make("codex");
+
 function display(descriptors: ReadonlyArray<ProviderOptionDescriptor>, fastModeEnabled: boolean) {
   return buildTraitsTriggerDisplay({
+    provider: CODEX,
     descriptors,
-    primarySelectDescriptorId: "effort",
+    primarySelectDescriptorId: "reasoningEffort",
     ultrathinkPromptControlled: false,
     fastModeEnabled,
   });
@@ -57,6 +60,16 @@ describe("buildTraitsTriggerDisplay", () => {
     });
   });
 
+  it("omits Codex's default Standard tier beside reasoning", () => {
+    const serviceTier = selectDescriptor(
+      "serviceTier",
+      [{ id: "default", label: "Standard", isDefault: true }],
+      "default",
+    );
+
+    expect(display([EFFORT, serviceTier], false).label).toBe("High");
+  });
+
   it("keeps non-fastMode booleans as text labels", () => {
     const thinking: Extract<ProviderOptionDescriptor, { type: "boolean" }> = {
       id: "thinking",
@@ -100,8 +113,9 @@ describe("buildTraitsTriggerDisplay", () => {
   it("still renders the prompt-controlled ultrathink label alongside the bolt", () => {
     expect(
       buildTraitsTriggerDisplay({
+        provider: CODEX,
         descriptors: [EFFORT, fastModeDescriptor(true)],
-        primarySelectDescriptorId: "effort",
+        primarySelectDescriptorId: "reasoningEffort",
         ultrathinkPromptControlled: true,
         fastModeEnabled: true,
       }),
diff --git a/apps/web/src/components/chat/TraitsPicker.tsx b/apps/web/src/components/chat/TraitsPicker.tsx
index df429e7aca2..f95f3a4c08a 100644
--- a/apps/web/src/components/chat/TraitsPicker.tsx
+++ b/apps/web/src/components/chat/TraitsPicker.tsx
@@ -388,6 +388,7 @@ export const TraitsMenuContent = memo(function TraitsMenuContentImpl({
  * chevron) would leave the trigger unreadable.
  */
 export function buildTraitsTriggerDisplay(input: {
+  provider: ProviderDriverKind;
   descriptors: ReadonlyArray<ProviderOptionDescriptor>;
   primarySelectDescriptorId: string | null;
   ultrathinkPromptControlled: boolean;
@@ -400,6 +401,18 @@ export function buildTraitsTriggerDisplay(input: {
       hasFastMode = true;
       continue;
     }
+    if (
+      input.provider === "codex" &&
+      descriptor.id === "serviceTier" &&
+      descriptor.type === "select" &&
+      input.descriptors.some(({ id }) => id === "reasoningEffort")
+    ) {
+      const currentValue = getProviderOptionCurrentValue(descriptor);
+      const currentOption = descriptor.options.find((option) => option.id === currentValue);
+      if (currentOption?.id === "default" && currentOption.isDefault === true) {
+        continue;
+      }
+    }
     const label =
       input.ultrathinkPromptControlled && descriptor.id === input.primarySelectDescriptorId
         ? "Ultrathink"
@@ -457,6 +470,7 @@ export const TraitsPicker = memo(function TraitsPicker({
   }
 
   const { label: triggerLabel, showFastModeIcon } = buildTraitsTriggerDisplay({
+    provider,
     descriptors,
     primarySelectDescriptorId: primarySelectDescriptor?.id ?? null,
     ultrathinkPromptControlled,

From 748203ea19fb68741709614b33b305079f0f4c05 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Wed, 29 Jul 2026 21:54:08 -0700
Subject: [PATCH 06/34] docs: link iOS and Android app store downloads (#4902)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---
 README.md                               |  2 +-
 apps/marketing/src/layouts/Layout.astro |  9 ++++++-
 apps/marketing/src/lib/site.ts          |  6 +++++
 apps/marketing/src/pages/download.astro | 22 +++++++++++++++-
 apps/marketing/src/pages/index.astro    | 35 ++++++++++++++++++++++++-
 5 files changed, 70 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 9b63f4ac75d..bc34b3f76b4 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # T3 Code
 
-T3 Code is an "agent harness control surface". It enables control of the agents on your machine with a best-in-class mobile app, [web app](https://app.t3.codes) and [Electron-based desktop app](https://t3.codes).
+T3 Code is an "agent harness control surface". It enables control of the agents on your machine with a best-in-class mobile app ([iOS](https://apps.apple.com/us/app/t3-code-remote-claude-more/id6787819824), [Android](https://play.google.com/store/apps/details?id=com.t3tools.t3code)), [web app](https://app.t3.codes) and [Electron-based desktop app](https://t3.codes).
 
 Works with your subscriptions on Claude Code, Codex, Cursor, Grok Build, and OpenCode. If they're set up on your computer, T3 Code can control them.
 
diff --git a/apps/marketing/src/layouts/Layout.astro b/apps/marketing/src/layouts/Layout.astro
index 9c454c4b78b..f5e34d0e048 100644
--- a/apps/marketing/src/layouts/Layout.astro
+++ b/apps/marketing/src/layouts/Layout.astro
@@ -1,5 +1,10 @@
 ---
-import { GITHUB_REPOSITORY_URL, MARKETING_STATS } from "../lib/site";
+import {
+  ANDROID_PLAY_STORE_URL,
+  GITHUB_REPOSITORY_URL,
+  IOS_APP_STORE_URL,
+  MARKETING_STATS,
+} from "../lib/site";
 
 interface Props {
   title?: string;
@@ -69,6 +74,8 @@ const {
             <a href={GITHUB_REPOSITORY_URL} target="_blank" rel="noopener noreferrer">GitHub</a>
             <a href="https://discord.gg/jn4EGJjrvv" target="_blank" rel="noopener noreferrer">Discord</a>
             <a href="/download">Download</a>
+            <a href={IOS_APP_STORE_URL} target="_blank" rel="noopener noreferrer">iOS app</a>
+            <a href={ANDROID_PLAY_STORE_URL} target="_blank" rel="noopener noreferrer">Android app</a>
             <a href="/terms-of-service">Terms</a>
             <a href="/privacy-policy">Privacy</a>
             <a href="/security-policy">Security</a>
diff --git a/apps/marketing/src/lib/site.ts b/apps/marketing/src/lib/site.ts
index 92e491a077a..0bf89db8c0f 100644
--- a/apps/marketing/src/lib/site.ts
+++ b/apps/marketing/src/lib/site.ts
@@ -1,5 +1,11 @@
 export const GITHUB_REPOSITORY_URL = "https://github.com/pingdotgg/t3code";
 
+export const IOS_APP_STORE_URL =
+  "https://apps.apple.com/us/app/t3-code-remote-claude-more/id6787819824";
+
+export const ANDROID_PLAY_STORE_URL =
+  "https://play.google.com/store/apps/details?id=com.t3tools.t3code";
+
 export const MARKETING_STATS = {
   githubStars: "14k+",
   users: "100,000",
diff --git a/apps/marketing/src/pages/download.astro b/apps/marketing/src/pages/download.astro
index 76977ad4ce2..111482208cf 100644
--- a/apps/marketing/src/pages/download.astro
+++ b/apps/marketing/src/pages/download.astro
@@ -1,6 +1,7 @@
 ---
 import Layout from "../layouts/Layout.astro";
 import { RELEASES_URL } from "../lib/releases";
+import { ANDROID_PLAY_STORE_URL, IOS_APP_STORE_URL } from "../lib/site";
 ---
 
 <Layout title="Download — T3 Code" description="Download T3 Code for macOS, Windows, or Linux.">
@@ -57,6 +58,24 @@ import { RELEASES_URL } from "../lib/releases";
         </a>
       </div>
     </section>
+
+    <!-- Mobile -->
+    <section class="platform-section">
+      <div class="platform-header">
+        <svg class="platform-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="7" y="2" width="10" height="20" rx="2.5"/><path d="M11 18.5h2"/></svg>
+        <h2 class="platform-name">Mobile</h2>
+      </div>
+      <div class="download-cards">
+        <a class="download-card" href={IOS_APP_STORE_URL} target="_blank" rel="noopener noreferrer">
+          <span class="card-arch">iPhone &amp; iPad</span>
+          <span class="card-format">App Store</span>
+        </a>
+        <a class="download-card" href={ANDROID_PLAY_STORE_URL} target="_blank" rel="noopener noreferrer">
+          <span class="card-arch">Android</span>
+          <span class="card-format">Google Play</span>
+        </a>
+      </div>
+    </section>
   </div>
 
   <p class="releases-link">
@@ -73,7 +92,8 @@ import { RELEASES_URL } from "../lib/releases";
 
   async function init() {
     const versionLabel = document.getElementById("version-label");
-    const cards = document.querySelectorAll<HTMLAnchorElement>(".download-card");
+    // Only release-asset cards; mobile store cards have no data-asset and keep their href.
+    const cards = document.querySelectorAll<HTMLAnchorElement>(".download-card[data-asset]");
 
     try {
       const release = await fetchLatestRelease();
diff --git a/apps/marketing/src/pages/index.astro b/apps/marketing/src/pages/index.astro
index 9d1cfbdd125..20fae288279 100644
--- a/apps/marketing/src/pages/index.astro
+++ b/apps/marketing/src/pages/index.astro
@@ -1,6 +1,11 @@
 ---
 import Layout from "../layouts/Layout.astro";
-import { GITHUB_REPOSITORY_URL, MARKETING_STATS } from "../lib/site";
+import {
+  ANDROID_PLAY_STORE_URL,
+  GITHUB_REPOSITORY_URL,
+  IOS_APP_STORE_URL,
+  MARKETING_STATS,
+} from "../lib/site";
 import { tweets } from "../lib/tweets";
 
 const desktopEndorsementRows = [
@@ -66,6 +71,12 @@ const mobileEndorsementRows = [
           <span>Steal our code (legally)</span>
           <svg class="hero-source-arrow" width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M7 17L17 7M8 7h9v9"/></svg>
         </a>
+        <p class="hero-mobile-line">
+          Also on your phone:
+          <a href={IOS_APP_STORE_URL} target="_blank" rel="noopener noreferrer">iOS</a>
+          <span aria-hidden="true">·</span>
+          <a href={ANDROID_PLAY_STORE_URL} target="_blank" rel="noopener noreferrer">Android</a>
+        </p>
       </div>
 
       <div class="hero-preview">
@@ -578,6 +589,28 @@ const mobileEndorsementRows = [
     opacity: 1;
   }
 
+  .hero-mobile-line {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    color: var(--fg-dim);
+    font-size: 13px;
+    letter-spacing: -0.005em;
+  }
+
+  .hero-mobile-line a {
+    color: var(--fg-muted);
+    text-decoration: underline;
+    text-decoration-color: rgba(161, 161, 170, 0.4);
+    text-underline-offset: 3px;
+    transition: color 0.18s ease, text-decoration-color 0.18s ease;
+  }
+
+  .hero-mobile-line a:hover {
+    color: var(--fg);
+    text-decoration-color: var(--fg);
+  }
+
   /* Download button icons (platform-aware) */
   .dl-icon {
     display: none;

From 6efcf3e10c02935780af6cc06f7146b8c9731ee2 Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Thu, 30 Jul 2026 07:30:23 +0200
Subject: [PATCH 07/34] fix(web): align remote server update action (#4731)

---
 .../settings/ConnectionsSettings.tsx          | 26 +++++++++----------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index 52b89530127..632221098d2 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -1426,19 +1426,11 @@ function SavedBackendListRow({
             <p className="text-xs text-muted-foreground">{metadataBits.join(" · ")}</p>
           ) : null}
           {versionMismatch ? (
-            <div className="flex flex-wrap items-center gap-2">
-              <p className="flex items-center gap-1 text-warning text-xs">
-                <TriangleAlertIcon className="size-3.5 shrink-0" />
-                Version drift: client {versionMismatch.clientVersion}, server{" "}
-                {versionMismatch.serverVersion}.
-              </p>
-              <ServerUpdateAction
-                environmentId={environmentId}
-                serverLabel={`${environment.label} server`}
-                selfUpdate={resolveServerSelfUpdateCapability(environment.serverConfig)}
-                targetVersion={versionMismatch.clientVersion}
-              />
-            </div>
+            <p className="flex items-center gap-1 text-warning text-xs">
+              <TriangleAlertIcon className="size-3.5 shrink-0" />
+              Version drift: client {versionMismatch.clientVersion}, server{" "}
+              {versionMismatch.serverVersion}.
+            </p>
           ) : null}
           {environment.connection.error ? (
             <p className="flex min-w-0 items-center gap-2 text-destructive text-xs">
@@ -1456,6 +1448,14 @@ function SavedBackendListRow({
           ) : null}
         </div>
         <div className="flex w-full shrink-0 items-center gap-2 sm:w-auto sm:justify-end">
+          {versionMismatch ? (
+            <ServerUpdateAction
+              environmentId={environmentId}
+              serverLabel={`${environment.label} server`}
+              selfUpdate={resolveServerSelfUpdateCapability(environment.serverConfig)}
+              targetVersion={versionMismatch.clientVersion}
+            />
+          ) : null}
           {isWslEnvironment ? (
             <Tooltip>
               <TooltipTrigger

From 6ab2f16809e584449831aa5dba0b0e5ca14a2a54 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Thu, 30 Jul 2026 01:46:10 -0700
Subject: [PATCH 08/34] fix(connect): suggest a serve command that matches how
 you ran connect (#4897)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---
 apps/server/src/cli/connect.ts         | 15 ++++--
 apps/server/src/cli/invocation.test.ts | 74 +++++++++++++++++++++++++
 apps/server/src/cli/invocation.ts      | 75 ++++++++++++++++++++++++++
 3 files changed, 160 insertions(+), 4 deletions(-)
 create mode 100644 apps/server/src/cli/invocation.test.ts
 create mode 100644 apps/server/src/cli/invocation.ts

diff --git a/apps/server/src/cli/connect.ts b/apps/server/src/cli/connect.ts
index 0369d47e4d7..ef15e650a6f 100644
--- a/apps/server/src/cli/connect.ts
+++ b/apps/server/src/cli/connect.ts
@@ -46,6 +46,7 @@ import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
 import * as ExternalLauncher from "../process/externalLauncher.ts";
 import { readPersistedServerRuntimeState } from "../serverRuntimeState.ts";
 import { projectLocationFlags, resolveCliAuthConfig } from "./config.ts";
+import { resolveCliCommand } from "./invocation.ts";
 import {
   bootServiceLayer,
   offerServiceDuringOnboarding,
@@ -526,10 +527,11 @@ const connectLinkCommand = Command.make("link", {
         yield* Console.log("T3 Connect\n");
         const linked = yield* linkEnvironmentForConnect(flags);
         if (linked) {
+          const serveCommand = yield* resolveCliCommand("serve");
           yield* Console.log(
             flags.publishOnly
               ? `✓ Authorized${connectedAs(linked.identity)}\n\nNext\n  Start T3 to publish agent activity (no managed tunnel).`
-              : `✓ Authorized${connectedAs(linked.identity)}\n\nNext\n  Start the server with \`t3 serve\` to make this machine reachable.`,
+              : `✓ Authorized${connectedAs(linked.identity)}\n\nNext\n  Start the server with \`${serveCommand}\` to make this machine reachable.`,
           );
         }
       }),
@@ -691,10 +693,15 @@ export const connectCommand = Command.make("connect", {
         // Connect itself already succeeded; a boot-service failure must not
         // fail the command, just tell the user what happened and move on.
         const background = yield* recoverServiceOnboardingOffer(offerServiceDuringOnboarding);
+        if (background) {
+          yield* Console.log(
+            "\n✓ Background service ready\n\nT3 Code will stay reachable after you log out.",
+          );
+          return;
+        }
+        const serveCommand = yield* resolveCliCommand("serve");
         yield* Console.log(
-          background
-            ? "\n✓ Background service ready\n\nT3 Code will stay reachable after you log out."
-            : "\nNext\n  Start the server with `t3 serve` to make this machine reachable.",
+          `\nNext\n  Start the server with \`${serveCommand}\` to make this machine reachable.`,
         );
       }),
     ),
diff --git a/apps/server/src/cli/invocation.test.ts b/apps/server/src/cli/invocation.test.ts
new file mode 100644
index 00000000000..c01a2caa49b
--- /dev/null
+++ b/apps/server/src/cli/invocation.test.ts
@@ -0,0 +1,74 @@
+import { assert, it } from "@effect/vitest";
+
+import { detectCliRunner, formatCliCommand, suggestedPackageSpec } from "./invocation.ts";
+
+it("detects package runners from their cache entry paths", () => {
+  assert.equal(detectCliRunner("/home/theo/.npm/_npx/abc123/node_modules/t3/dist/bin.mjs"), "npx");
+  assert.equal(
+    detectCliRunner(
+      "C:\\Users\\theo\\AppData\\Local\\npm-cache\\_npx\\abc\\node_modules\\t3\\dist\\bin.mjs",
+    ),
+    "npx",
+  );
+  assert.equal(
+    detectCliRunner("/home/theo/.cache/pnpm/dlx/abc/node_modules/t3/dist/bin.mjs"),
+    "pnpm dlx",
+  );
+  assert.equal(
+    detectCliRunner("/home/theo/.local/share/pnpm/.pnpm/dlx/abc/node_modules/t3/dist/bin.mjs"),
+    "pnpm dlx",
+  );
+  assert.equal(
+    detectCliRunner(
+      "C:\\Users\\theo\\AppData\\Local\\pnpm-cache\\dlx\\abc\\node_modules\\t3\\dist\\bin.mjs",
+    ),
+    "pnpm dlx",
+  );
+  assert.equal(detectCliRunner("/home/theo/.bun/install/cache/t3@0.0.31/dist/bin.mjs"), "bunx");
+  assert.equal(detectCliRunner("/tmp/bunx-1000-t3@latest/node_modules/t3/dist/bin.mjs"), "bunx");
+  assert.equal(
+    detectCliRunner(
+      "C:\\Users\\theo\\AppData\\Local\\Temp\\bunx-0-t3@latest\\node_modules\\t3\\dist\\bin.mjs",
+    ),
+    "bunx",
+  );
+});
+
+it("treats stable installs as direct invocations", () => {
+  assert.isNull(detectCliRunner("/usr/local/lib/node_modules/t3/dist/bin.mjs"));
+  assert.isNull(detectCliRunner("/home/theo/Code/work/t3code/apps/server/dist/bin.mjs"));
+  assert.isNull(detectCliRunner("/home/theo/.t3/runtime/0.0.31/node_modules/t3/dist/bin.mjs"));
+  assert.isNull(detectCliRunner(""));
+});
+
+it("re-suggests the nightly channel only for nightly builds", () => {
+  assert.equal(suggestedPackageSpec("0.0.31-nightly.20260729"), "t3@nightly");
+  assert.equal(suggestedPackageSpec("0.0.31"), "t3");
+});
+
+it("formats serve suggestions to match the launching command", () => {
+  assert.equal(
+    formatCliCommand({
+      subcommand: "serve",
+      entryPath: "/home/theo/.npm/_npx/abc/node_modules/t3/dist/bin.mjs",
+      version: "0.0.31-nightly.20260729",
+    }),
+    "npx t3@nightly serve",
+  );
+  assert.equal(
+    formatCliCommand({
+      subcommand: "serve",
+      entryPath: "/tmp/bunx-1000-t3@latest/node_modules/t3/dist/bin.mjs",
+      version: "0.0.31",
+    }),
+    "bunx t3 serve",
+  );
+  assert.equal(
+    formatCliCommand({
+      subcommand: "serve",
+      entryPath: "/usr/local/lib/node_modules/t3/dist/bin.mjs",
+      version: "0.0.31-nightly.20260729",
+    }),
+    "t3 serve",
+  );
+});
diff --git a/apps/server/src/cli/invocation.ts b/apps/server/src/cli/invocation.ts
new file mode 100644
index 00000000000..e1b03552948
--- /dev/null
+++ b/apps/server/src/cli/invocation.ts
@@ -0,0 +1,75 @@
+import * as Effect from "effect/Effect";
+
+import { HostProcessArguments } from "@t3tools/shared/hostProcess";
+
+import packageJson from "../../package.json" with { type: "json" };
+
+export type CliRunner = "npx" | "pnpm dlx" | "bunx";
+
+/**
+ * How the CLI was launched, judged by where its entry script lives. Each
+ * package runner executes out of a distinctive cache/temp layout:
+ *
+ *   npx      ~/.npm/_npx/<hash>/node_modules/...
+ *   pnpm dlx ~/.cache/pnpm/dlx/..., $PNPM_HOME/.pnpm/dlx/...,
+ *            or %LOCALAPPDATA%/pnpm-cache/dlx/... on Windows
+ *   bunx     ~/.bun/install/cache/... or $TMPDIR/bunx-<uid>-<spec>/...
+ *
+ * Global installs and repo checkouts match none of these and return null.
+ * Detection is best-effort; callers must fail closed to a plain `t3` command.
+ */
+export function detectCliRunner(entryPath: string): CliRunner | null {
+  const path = entryPath.replaceAll("\\", "/");
+  if (path.includes("/_npx/")) {
+    return "npx";
+  }
+  if (
+    path.includes("/pnpm/dlx/") ||
+    path.includes("/.pnpm/dlx/") ||
+    path.includes("/pnpm-cache/dlx/")
+  ) {
+    return "pnpm dlx";
+  }
+  if (path.includes("/.bun/install/cache/") || path.includes("/bunx-")) {
+    return "bunx";
+  }
+  return null;
+}
+
+/**
+ * The `t3` package spec to suggest. The literal spec the user typed (e.g.
+ * `t3@nightly`) is resolved away before our process starts, so re-derive it
+ * from the running version: nightly builds re-suggest the nightly channel,
+ * anything else suggests the bare package.
+ */
+export function suggestedPackageSpec(version: string): string {
+  return version.includes("-nightly.") ? "t3@nightly" : "t3";
+}
+
+/**
+ * Render a `t3 <subcommand>` suggestion that matches how this process was
+ * launched, so copy/pasting it actually works: `npx t3 connect` suggests
+ * `npx t3 serve`, a global install suggests `t3 serve`, and a nightly build
+ * keeps the `@nightly` tag.
+ */
+export function formatCliCommand(input: {
+  readonly subcommand: string;
+  readonly entryPath: string;
+  readonly version: string;
+}): string {
+  const runner = detectCliRunner(input.entryPath);
+  if (runner === null) {
+    return `t3 ${input.subcommand}`;
+  }
+  return `${runner} ${suggestedPackageSpec(input.version)} ${input.subcommand}`;
+}
+
+/** `formatCliCommand` against this process's real entry path and version. */
+export const resolveCliCommand = (subcommand: string) =>
+  Effect.map(HostProcessArguments, (processArguments) =>
+    formatCliCommand({
+      subcommand,
+      entryPath: processArguments[1] ?? "",
+      version: packageJson.version,
+    }),
+  );

From 00da6b57a43aef39162ff9e8205b5441c24298d0 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Thu, 30 Jul 2026 01:48:16 -0700
Subject: [PATCH 09/34] fix(mobile): stop shared content errors in Personal
 Team builds (#4943)

---
 .../sharing/IncomingShareProvider.tsx         |  8 +++-
 .../sharing/incoming-share-native.test.ts     | 46 +++++++++++++++++++
 .../features/sharing/incoming-share-native.ts | 37 +++++++++++++++
 3 files changed, 90 insertions(+), 1 deletion(-)
 create mode 100644 apps/mobile/src/features/sharing/incoming-share-native.test.ts
 create mode 100644 apps/mobile/src/features/sharing/incoming-share-native.ts

diff --git a/apps/mobile/src/features/sharing/IncomingShareProvider.tsx b/apps/mobile/src/features/sharing/IncomingShareProvider.tsx
index 04d371e5d2f..9203e665190 100644
--- a/apps/mobile/src/features/sharing/IncomingShareProvider.tsx
+++ b/apps/mobile/src/features/sharing/IncomingShareProvider.tsx
@@ -15,6 +15,7 @@ import {
   type IncomingShareDestination,
   type IncomingShareDraft,
 } from "./incoming-share-model";
+import { createIncomingSharePayloadReader } from "./incoming-share-native";
 import { IncomingShareInbox } from "./incoming-share-inbox";
 import {
   loadIncomingShareDrafts,
@@ -48,6 +49,11 @@ function receiveSharingEnabled(): boolean {
   return Constants.expoConfig?.extra?.iosPersonalTeamBuild !== true;
 }
 
+const getIncomingSharePayloads = createIncomingSharePayloadReader({
+  platform: Platform.OS,
+  readPayloads: getSharedPayloads,
+});
+
 async function resolvedPayloadsForImages(): Promise<ReadonlyArray<ResolvedSharePayload>> {
   try {
     return await getResolvedSharedPayloadsAsync();
@@ -121,7 +127,7 @@ const incomingShareInbox = new IncomingShareInbox({
   loadDrafts: loadIncomingShareDrafts,
   writeDraft: writeIncomingShareDraft,
   removeDraft: removeIncomingShareDraft,
-  getPayloads: getSharedPayloads,
+  getPayloads: getIncomingSharePayloads,
   clearPayloads: clearSharedPayloads,
   buildDraft: async ({ payloads, id, createdAt }) => {
     const cleanupUris = new Set<string>();
diff --git a/apps/mobile/src/features/sharing/incoming-share-native.test.ts b/apps/mobile/src/features/sharing/incoming-share-native.test.ts
new file mode 100644
index 00000000000..8511f61ffa2
--- /dev/null
+++ b/apps/mobile/src/features/sharing/incoming-share-native.test.ts
@@ -0,0 +1,46 @@
+import { describe, expect, it, vi } from "@effect/vitest";
+import type { SharePayload } from "expo-sharing";
+
+import { createIncomingSharePayloadReader } from "./incoming-share-native";
+
+const PAYLOAD: SharePayload = {
+  shareType: "text",
+  mimeType: "text/plain",
+  value: "Fix this",
+};
+
+describe("createIncomingSharePayloadReader", () => {
+  it("treats a missing iOS App Group as an unavailable inbox", () => {
+    const readPayloads = vi.fn((): ReadonlyArray<SharePayload> => {
+      throw Object.assign(new Error("Expo-sharing has failed to fetch the app group id"), {
+        code: "ERR_FAILED_TO_RESOLVE_APP_GROUP_ID",
+      });
+    });
+    const read = createIncomingSharePayloadReader({ platform: "ios", readPayloads });
+
+    expect(read()).toEqual([]);
+    expect(read()).toEqual([]);
+    expect(readPayloads).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns native payloads when receiving is available", () => {
+    const read = createIncomingSharePayloadReader({
+      platform: "ios",
+      readPayloads: () => [PAYLOAD],
+    });
+
+    expect(read()).toEqual([PAYLOAD]);
+  });
+
+  it("preserves other native errors", () => {
+    const error = new Error("native failure");
+    const read = createIncomingSharePayloadReader({
+      platform: "ios",
+      readPayloads: () => {
+        throw error;
+      },
+    });
+
+    expect(read).toThrow(error);
+  });
+});
diff --git a/apps/mobile/src/features/sharing/incoming-share-native.ts b/apps/mobile/src/features/sharing/incoming-share-native.ts
new file mode 100644
index 00000000000..b6da9534c92
--- /dev/null
+++ b/apps/mobile/src/features/sharing/incoming-share-native.ts
@@ -0,0 +1,37 @@
+import type { SharePayload } from "expo-sharing";
+
+const IOS_APP_GROUP_UNAVAILABLE_ERROR_CODE = "ERR_FAILED_TO_RESOLVE_APP_GROUP_ID";
+
+function errorCode(error: unknown): string | null {
+  if (typeof error !== "object" || error === null || !("code" in error)) {
+    return null;
+  }
+  return typeof error.code === "string" ? error.code : null;
+}
+
+/**
+ * Normalizes the native "share into" capability to an empty inbox. Personal
+ * Team builds cannot include the App Group that expo-sharing reads from.
+ */
+export function createIncomingSharePayloadReader(input: {
+  readonly platform: string;
+  readonly readPayloads: () => ReadonlyArray<SharePayload>;
+}): () => ReadonlyArray<SharePayload> {
+  let isUnavailable = false;
+
+  return () => {
+    if (isUnavailable) {
+      return [];
+    }
+
+    try {
+      return input.readPayloads();
+    } catch (error) {
+      if (input.platform === "ios" && errorCode(error) === IOS_APP_GROUP_UNAVAILABLE_ERROR_CODE) {
+        isUnavailable = true;
+        return [];
+      }
+      throw error;
+    }
+  };
+}

From f0f16e4f6e8e923dcb17fc1c25d4fb1e442f80a5 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Thu, 30 Jul 2026 01:54:59 -0700
Subject: [PATCH 10/34] perf(mobile): sends respond instantly, thread opens
 stop freezing (#4882)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---
 apps/mobile/src/Stack.tsx                     |  11 +-
 apps/mobile/src/features/home/HomeScreen.tsx  |  28 +++--
 .../src/features/shortcuts/useAppShortcuts.ts |   9 +-
 .../features/threads/NewTaskDraftScreen.tsx   |   6 +-
 .../src/features/threads/ThreadComposer.tsx   |  14 ++-
 apps/mobile/src/lib/threadActivity.ts         |  40 ++++---
 .../mobile/src/state/thread-outbox-manager.ts |  29 ++++-
 apps/mobile/src/state/thread-outbox.test.ts   | 105 ++++++++++++++++++
 apps/mobile/src/state/thread-outbox.ts        |   5 +
 .../src/state/use-selected-thread-requests.ts |  14 ++-
 .../src/state/use-thread-composer-state.ts    |  46 +++++---
 .../src/state/use-thread-outbox-drain.ts      |  37 +++++-
 12 files changed, 283 insertions(+), 61 deletions(-)

diff --git a/apps/mobile/src/Stack.tsx b/apps/mobile/src/Stack.tsx
index 3aedb4e4e3e..76a9399772d 100644
--- a/apps/mobile/src/Stack.tsx
+++ b/apps/mobile/src/Stack.tsx
@@ -284,6 +284,15 @@ function workspacePathFromState(state: NavigationState): string {
   return path.startsWith("/") ? path : `/${path}`;
 }
 
+// The drain hook subscribes to the outbox, all thread shells, projects, and
+// connection statuses. Hosting it in a null-rendering leaf keeps those
+// updates from re-rendering RootStackLayout (and with it every screen) on
+// each enqueue, shell change, or reconnect.
+function ThreadOutboxDrainWorker() {
+  useThreadOutboxDrain();
+  return null;
+}
+
 function RootStackLayout(props: {
   readonly children: React.ReactNode;
   readonly state: NavigationState;
@@ -292,7 +301,6 @@ function RootStackLayout(props: {
   const { pendingShare } = useIncomingShare();
   const sharePresentationRef = useRef(EMPTY_INCOMING_SHARE_PRESENTATION_STATE);
   useAgentNotificationNavigation();
-  useThreadOutboxDrain();
   // Presents the T3 Connect onboarding sheet after an in-session sign-in.
   useConnectOnboardingNavigation();
   // Launcher app shortcuts: routes shortcut taps and tracks opened threads.
@@ -320,6 +328,7 @@ function RootStackLayout(props: {
 
   return (
     <HardwareKeyboardCommandProvider pathname={pathname}>
+      <ThreadOutboxDrainWorker />
       <ShowcaseCaptureCoordinator pathname={pathname} />
       <ClerkSettingsSheetDetentProvider initiallyExpanded={false}>
         <AdaptiveWorkspaceLayout pathname={workspacePathname}>
diff --git a/apps/mobile/src/features/home/HomeScreen.tsx b/apps/mobile/src/features/home/HomeScreen.tsx
index 0263e74eade..b96cc862b27 100644
--- a/apps/mobile/src/features/home/HomeScreen.tsx
+++ b/apps/mobile/src/features/home/HomeScreen.tsx
@@ -665,6 +665,26 @@ export function HomeScreen(props: HomeScreenProps) {
   );
   const v2KeyExtractor = useCallback((item: ThreadListV2ListItem) => item.key, []);
 
+  // FlatList treats a changed extraData identity as "re-render every visible
+  // row", so an inline object literal would invalidate all rows on every
+  // HomeScreen render.
+  const v2ExtraData = useMemo(
+    () => ({
+      projectByKey,
+      projectCwdByKey,
+      projectTitleByProjectKey: v2ProjectTitleByProjectKey,
+      serverConfigs,
+      savedConnectionsById: props.savedConnectionsById,
+    }),
+    [
+      projectByKey,
+      projectCwdByKey,
+      props.savedConnectionsById,
+      serverConfigs,
+      v2ProjectTitleByProjectKey,
+    ],
+  );
+
   const extraData = useMemo(
     () => ({ savedConnectionsById: props.savedConnectionsById, projectCwdByKey }),
     [props.savedConnectionsById, projectCwdByKey],
@@ -900,13 +920,7 @@ export function HomeScreen(props: HomeScreenProps) {
             data={threadListV2Items}
             renderItem={renderV2Item}
             keyExtractor={v2KeyExtractor}
-            extraData={{
-              projectByKey,
-              projectCwdByKey,
-              projectTitleByProjectKey: v2ProjectTitleByProjectKey,
-              serverConfigs,
-              savedConnectionsById: props.savedConnectionsById,
-            }}
+            extraData={v2ExtraData}
             ListHeaderComponent={v2ListHeader}
             ListFooterComponent={
               threadListV2Layout.hiddenSettledCount > 0 ? (
diff --git a/apps/mobile/src/features/shortcuts/useAppShortcuts.ts b/apps/mobile/src/features/shortcuts/useAppShortcuts.ts
index 3070a1d54e0..30b4e169889 100644
--- a/apps/mobile/src/features/shortcuts/useAppShortcuts.ts
+++ b/apps/mobile/src/features/shortcuts/useAppShortcuts.ts
@@ -54,7 +54,14 @@ function useShortcutNavigation(): void {
 }
 
 function useRecentThreadShortcutSync(state: NavigationState): void {
-  const threadRef = useMemo(() => activeThreadRef(state), [state]);
+  // Launcher shortcuts are Android-only. A null ref on iOS keeps this hook
+  // (mounted in the root stack layout) from subscribing the root to the
+  // active thread's shell, which would re-render every screen on each
+  // title/status/session change.
+  const threadRef = useMemo(
+    () => (Platform.OS === "android" ? activeThreadRef(state) : null),
+    [state],
+  );
   const threadShell = useThreadShell(threadRef);
   // null until the persisted list loads; recording waits on it so the first
   // thread opened after a cold start cannot clobber older entries.
diff --git a/apps/mobile/src/features/threads/NewTaskDraftScreen.tsx b/apps/mobile/src/features/threads/NewTaskDraftScreen.tsx
index e328bcef00e..f37b5559a4a 100644
--- a/apps/mobile/src/features/threads/NewTaskDraftScreen.tsx
+++ b/apps/mobile/src/features/threads/NewTaskDraftScreen.tsx
@@ -946,7 +946,11 @@ export function NewTaskDraftScreen(props: {
   const promptEditor = (
     <ComposerEditor
       ref={promptInputRef}
-      autoFocus={!isAndroid}
+      // Native autoFocus fires becomeFirstResponder in didMoveToWindow, which
+      // forces the iOS keyboard bring-up during the formSheet present
+      // animation and stalls it. The runAfterInteractions effect above focuses
+      // the editor once the transition settles instead.
+      autoFocus={false}
       editable={!isIncomingShareTransferPending}
       multiline
       scrollEnabled={isExpanded}
diff --git a/apps/mobile/src/features/threads/ThreadComposer.tsx b/apps/mobile/src/features/threads/ThreadComposer.tsx
index 59af7199af7..fc45cba4260 100644
--- a/apps/mobile/src/features/threads/ThreadComposer.tsx
+++ b/apps/mobile/src/features/threads/ThreadComposer.tsx
@@ -518,14 +518,16 @@ export const ThreadComposer = memo(function ThreadComposer(props: ThreadComposer
     const threadKey = scopedThreadKey(props.environmentId, props.selectedThread.id);
     if (inFlightThreadIdsRef.current.has(threadKey)) return;
     inFlightThreadIdsRef.current.add(threadKey);
-    // Sending a prompt starts agent work: arm the lock-screen card now, while
-    // the app is foregrounded and the activity token can be registered.
-    armAgentAwarenessLiveActivityForLocalWork({
-      threadTitle: props.selectedThread.title,
-      projectTitle: props.environmentLabel ?? "T3 Code",
-    });
     try {
       await onSendMessage();
+      // Sending a prompt starts agent work: arm the lock-screen card while the
+      // app is foregrounded and the activity token can be registered. Armed
+      // after the send so its preference read and native Activity start don't
+      // contend with the queued-message feedback on the tap frame.
+      armAgentAwarenessLiveActivityForLocalWork({
+        threadTitle: props.selectedThread.title,
+        projectTitle: props.environmentLabel ?? "T3 Code",
+      });
     } finally {
       inFlightThreadIdsRef.current.delete(threadKey);
     }
diff --git a/apps/mobile/src/lib/threadActivity.ts b/apps/mobile/src/lib/threadActivity.ts
index 0c79217502d..dd568e6f045 100644
--- a/apps/mobile/src/lib/threadActivity.ts
+++ b/apps/mobile/src/lib/threadActivity.ts
@@ -957,6 +957,11 @@ function isEmptyMessage(entry: RawThreadFeedEntry): boolean {
 
 function groupAdjacentActivities(entries: ReadonlyArray<RawThreadFeedEntry>): ThreadFeedEntry[] {
   const grouped: ThreadFeedEntry[] = [];
+  // Mutable backing array for the trailing group so appending an activity is
+  // O(1) instead of re-copying the group (which made this loop quadratic on
+  // long tool runs). The array is only mutated while it is the trailing group.
+  let openGroupActivities: ThreadFeedActivity[] | null = null;
+  let openGroupTurnId: TurnId | null = null;
 
   for (const entry of entries) {
     // Skip empty messages so they don't break activity grouping.
@@ -966,24 +971,23 @@ function groupAdjacentActivities(entries: ReadonlyArray<RawThreadFeedEntry>): Th
 
     if (entry.type !== "activity") {
       grouped.push(entry);
+      openGroupActivities = null;
       continue;
     }
 
-    const previous = grouped.at(-1);
-    if (previous?.type === "activity-group" && previous.turnId === entry.turnId) {
-      grouped[grouped.length - 1] = {
-        ...previous,
-        activities: [...previous.activities, entry.activity],
-      };
+    if (openGroupActivities !== null && openGroupTurnId === entry.turnId) {
+      openGroupActivities.push(entry.activity);
       continue;
     }
 
+    openGroupActivities = [entry.activity];
+    openGroupTurnId = entry.turnId;
     grouped.push({
       type: "activity-group",
       id: entry.id,
       createdAt: entry.createdAt,
       turnId: entry.turnId,
-      activities: [entry.activity],
+      activities: openGroupActivities,
     });
   }
 
@@ -1225,13 +1229,24 @@ function appendPresentedFeedEntry(
   });
 }
 
-export function derivePendingApprovals(
+/**
+ * Sorts activities into lifecycle order. `derivePendingApprovals` and
+ * `derivePendingUserInputs` both expect this ordering; sorting once and
+ * passing the result to both avoids re-sorting the full activity history
+ * per derivation.
+ */
+export function sortThreadActivities(
   activities: ReadonlyArray<OrchestrationThreadActivity>,
+): ReadonlyArray<OrchestrationThreadActivity> {
+  return Arr.sort(activities, activityOrder);
+}
+
+export function derivePendingApprovals(
+  sortedActivities: ReadonlyArray<OrchestrationThreadActivity>,
 ): PendingApproval[] {
   const openByRequestId = new Map<ApprovalRequestId, PendingApproval>();
-  const ordered = Arr.sort(activities, activityOrder);
 
-  for (const activity of ordered) {
+  for (const activity of sortedActivities) {
     const payload =
       activity.payload && typeof activity.payload === "object"
         ? (activity.payload as Record<string, unknown>)
@@ -1273,12 +1288,11 @@ export function derivePendingApprovals(
 }
 
 export function derivePendingUserInputs(
-  activities: ReadonlyArray<OrchestrationThreadActivity>,
+  sortedActivities: ReadonlyArray<OrchestrationThreadActivity>,
 ): PendingUserInput[] {
   const openByRequestId = new Map<ApprovalRequestId, PendingUserInput>();
-  const ordered = Arr.sort(activities, activityOrder);
 
-  for (const activity of ordered) {
+  for (const activity of sortedActivities) {
     const payload =
       activity.payload && typeof activity.payload === "object"
         ? (activity.payload as Record<string, unknown>)
diff --git a/apps/mobile/src/state/thread-outbox-manager.ts b/apps/mobile/src/state/thread-outbox-manager.ts
index 19f89d13c51..f6a20ccffc2 100644
--- a/apps/mobile/src/state/thread-outbox-manager.ts
+++ b/apps/mobile/src/state/thread-outbox-manager.ts
@@ -88,11 +88,23 @@ export function createThreadOutboxManager(options: ThreadOutboxManagerOptions) {
     return loadPromise;
   };
 
-  const enqueue = (message: QueuedThreadMessage): Promise<void> =>
-    serialize(async () => {
+  // The queued atom drives the composer's immediate "queued" feedback, so it
+  // is published synchronously; the durable write happens behind it and rolls
+  // the message back out if it fails (durability only matters for crash
+  // recovery, not for the in-session queue).
+  const enqueue = (message: QueuedThreadMessage): Promise<void> => {
+    setMessages([
+      ...currentMessages().filter((candidate) => candidate.messageId !== message.messageId),
+      message,
+    ]);
+    return serialize(async () => {
       try {
         await options.storage.write(message);
       } catch (cause) {
+        // Roll back by reference, not messageId: a retry enqueue with the same
+        // id may have optimistically replaced this attempt while the write was
+        // in flight, and its entry must survive this attempt's failure.
+        setMessages(currentMessages().filter((candidate) => candidate !== message));
         throw new ThreadOutboxManagerError({
           operation: "enqueue",
           environmentId: message.environmentId,
@@ -101,11 +113,15 @@ export function createThreadOutboxManager(options: ThreadOutboxManagerOptions) {
           cause,
         });
       }
-      setMessages([
-        ...currentMessages().filter((candidate) => candidate.messageId !== message.messageId),
-        message,
-      ]);
     });
+  };
+
+  // Resolves once all pending mutations (including any in-flight enqueue
+  // write) have settled, reporting whether the message is still queued. The
+  // drain awaits this before dispatching so a message whose durable write
+  // later fails can never have been delivered first.
+  const confirmQueued = (message: QueuedThreadMessage): Promise<boolean> =>
+    serialize(async () => currentMessages().some((candidate) => candidate === message));
 
   // Rewrites an already-queued message. A no-op when the message has been
   // removed in the meantime (e.g. deleted or delivered), so a trailing editor
@@ -204,6 +220,7 @@ export function createThreadOutboxManager(options: ThreadOutboxManagerOptions) {
     serialize,
     load,
     enqueue,
+    confirmQueued,
     update,
     remove,
     clearEnvironment,
diff --git a/apps/mobile/src/state/thread-outbox.test.ts b/apps/mobile/src/state/thread-outbox.test.ts
index 6c665c432f4..89f8b26798b 100644
--- a/apps/mobile/src/state/thread-outbox.test.ts
+++ b/apps/mobile/src/state/thread-outbox.test.ts
@@ -294,6 +294,111 @@ describe("thread outbox", () => {
     registry.dispose();
   });
 
+  it("publishes an enqueued message before the durable write resolves", async () => {
+    const registry = AtomRegistry.make();
+    let releaseWrite!: () => void;
+    const writeBlocked = new Promise<void>((resolve) => {
+      releaseWrite = resolve;
+    });
+    const manager = createThreadOutboxManager({
+      registry,
+      storage: {
+        load: async () => [],
+        write: async () => writeBlocked,
+        remove: async () => undefined,
+      },
+    });
+    const message = queuedMessage({
+      messageId: "message-1",
+      createdAt: "2026-06-08T10:00:01.000Z",
+    });
+
+    const enqueueing = manager.enqueue(message);
+    expect(registry.get(manager.queuedMessagesByThreadKeyAtom)).toEqual({
+      "environment-1:thread-1": [message],
+    });
+
+    releaseWrite();
+    await enqueueing;
+    expect(registry.get(manager.queuedMessagesByThreadKeyAtom)).toEqual({
+      "environment-1:thread-1": [message],
+    });
+    registry.dispose();
+  });
+
+  it("rolls an enqueued message back out when the durable write fails", async () => {
+    const registry = AtomRegistry.make();
+    const writeCause = new Error("disk full");
+    const manager = createThreadOutboxManager({
+      registry,
+      storage: {
+        load: async () => [],
+        write: async () => {
+          throw writeCause;
+        },
+        remove: async () => undefined,
+      },
+    });
+    const message = queuedMessage({
+      messageId: "message-1",
+      createdAt: "2026-06-08T10:00:01.000Z",
+    });
+
+    await expect(manager.enqueue(message)).rejects.toEqual(
+      new ThreadOutboxManagerError({
+        operation: "enqueue",
+        environmentId: message.environmentId,
+        threadId: message.threadId,
+        messageId: message.messageId,
+        cause: writeCause,
+      }),
+    );
+    expect(registry.get(manager.queuedMessagesByThreadKeyAtom)).toEqual({});
+    registry.dispose();
+  });
+
+  it("keeps a same-id retry queued when the first attempt's write fails", async () => {
+    const registry = AtomRegistry.make();
+    let failNextWrite = true;
+    let releaseFirstWrite!: () => void;
+    const firstWriteBlocked = new Promise<void>((resolve) => {
+      releaseFirstWrite = resolve;
+    });
+    const manager = createThreadOutboxManager({
+      registry,
+      storage: {
+        load: async () => [],
+        write: async () => {
+          if (failNextWrite) {
+            failNextWrite = false;
+            await firstWriteBlocked;
+            throw new Error("disk full");
+          }
+        },
+        remove: async () => undefined,
+      },
+    });
+    const message = queuedMessage({
+      messageId: "message-1",
+      createdAt: "2026-06-08T10:00:01.000Z",
+    });
+    const retried = { ...message, text: "retried" };
+
+    const first = manager.enqueue(message);
+    const second = manager.enqueue(retried);
+    releaseFirstWrite();
+    await expect(first).rejects.toBeInstanceOf(ThreadOutboxManagerError);
+    await second;
+
+    // The failed first attempt must not roll back the retry that replaced it.
+    expect(registry.get(manager.queuedMessagesByThreadKeyAtom)).toEqual({
+      "environment-1:thread-1": [retried],
+    });
+    await expect(manager.confirmQueued(retried)).resolves.toBe(true);
+    await expect(manager.confirmQueued(message)).resolves.toBe(false);
+    registry.dispose();
+  });
+
   it("replaces an existing message when an enqueue retry uses the same id", async () => {
     const registry = AtomRegistry.make();
     const manager = createThreadOutboxManager({
diff --git a/apps/mobile/src/state/thread-outbox.ts b/apps/mobile/src/state/thread-outbox.ts
index a089c49732c..59287b12e61 100644
--- a/apps/mobile/src/state/thread-outbox.ts
+++ b/apps/mobile/src/state/thread-outbox.ts
@@ -20,6 +20,11 @@ export function enqueueThreadOutboxMessage(message: QueuedThreadMessage): Promis
   return threadOutboxManager.enqueue(message);
 }
 
+/** Waits for pending writes to settle; false if the message was rolled back. */
+export function confirmThreadOutboxMessageQueued(message: QueuedThreadMessage): Promise<boolean> {
+  return threadOutboxManager.confirmQueued(message);
+}
+
 /** Rewrite a queued message; no-op (false) if it was removed in the meantime. */
 export function updateThreadOutboxMessage(message: QueuedThreadMessage): Promise<boolean> {
   return threadOutboxManager.update(message);
diff --git a/apps/mobile/src/state/use-selected-thread-requests.ts b/apps/mobile/src/state/use-selected-thread-requests.ts
index c9e9db12530..82ff42f247a 100644
--- a/apps/mobile/src/state/use-selected-thread-requests.ts
+++ b/apps/mobile/src/state/use-selected-thread-requests.ts
@@ -11,6 +11,7 @@ import {
   derivePendingApprovals,
   derivePendingUserInputs,
   setPendingUserInputCustomAnswer,
+  sortThreadActivities,
   type PendingUserInputDraftAnswer,
 } from "../lib/threadActivity";
 import { appAtomRegistry } from "./atom-registry";
@@ -70,14 +71,19 @@ export function useSelectedThreadRequests() {
     null,
   );
 
-  const activePendingApprovals = useMemo(
-    () => (selectedThread ? derivePendingApprovals(selectedThread.activities) : []),
+  // Sort once; both derivations expect the same lifecycle ordering.
+  const sortedActivities = useMemo(
+    () => (selectedThread ? sortThreadActivities(selectedThread.activities) : []),
     [selectedThread],
   );
+  const activePendingApprovals = useMemo(
+    () => derivePendingApprovals(sortedActivities),
+    [sortedActivities],
+  );
   const activePendingApproval = activePendingApprovals[0] ?? null;
   const activePendingUserInputs = useMemo(
-    () => (selectedThread ? derivePendingUserInputs(selectedThread.activities) : []),
-    [selectedThread],
+    () => derivePendingUserInputs(sortedActivities),
+    [sortedActivities],
   );
   const activePendingUserInput = activePendingUserInputs[0] ?? null;
   const activePendingUserInputDrafts =
diff --git a/apps/mobile/src/state/use-thread-composer-state.ts b/apps/mobile/src/state/use-thread-composer-state.ts
index 90831f8437a..b09aadf7e6b 100644
--- a/apps/mobile/src/state/use-thread-composer-state.ts
+++ b/apps/mobile/src/state/use-thread-composer-state.ts
@@ -30,6 +30,7 @@ import {
   composerDraftsAtom,
   ensureComposerDraftsLoaded,
   getComposerDraftSnapshot,
+  mergeComposerDraftContent,
   removeComposerDraftAttachment,
   setComposerDraftText,
   updateComposerDraftSettings,
@@ -148,27 +149,36 @@ export function useThreadComposerState() {
 
     const metadata = makeQueuedMessageMetadata();
     const messageId = MessageId.make(metadata.messageId);
-    try {
-      await enqueueThreadOutboxMessage({
-        environmentId: selectedThreadShell.environmentId,
-        threadId: selectedThreadShell.id,
-        messageId,
-        commandId: CommandId.make(metadata.commandId),
-        text,
-        attachments,
-        modelSelection: draft.modelSelection ?? thread.modelSelection,
-        runtimeMode: draft.runtimeMode ?? thread.runtimeMode,
-        interactionMode: draft.interactionMode ?? thread.interactionMode,
-        createdAt: metadata.createdAt,
-      });
-      clearComposerDraftContent(threadKey);
-      return messageId;
-    } catch (error) {
+    // Enqueue publishes the queued atom synchronously (the durable write
+    // happens behind it), so clearing the draft here gives send feedback on
+    // the tap frame instead of after file I/O. If the write fails the message
+    // is rolled out of the queue and the content is merged back into the
+    // draft, preserving anything typed since.
+    const enqueuePromise = enqueueThreadOutboxMessage({
+      environmentId: selectedThreadShell.environmentId,
+      threadId: selectedThreadShell.id,
+      messageId,
+      commandId: CommandId.make(metadata.commandId),
+      text,
+      attachments,
+      modelSelection: draft.modelSelection ?? thread.modelSelection,
+      runtimeMode: draft.runtimeMode ?? thread.runtimeMode,
+      interactionMode: draft.interactionMode ?? thread.interactionMode,
+      createdAt: metadata.createdAt,
+    });
+    clearComposerDraftContent(threadKey);
+    enqueuePromise.catch((error: unknown) => {
+      // Restore text via merge (idempotent) but attachments via the uncapped
+      // append: the merge path slots existing attachments first and truncates
+      // at the send limit, which would silently drop this message's images if
+      // the user attached new ones while the write was in flight.
+      void mergeComposerDraftContent(threadKey, { text, attachments: [] });
+      appendComposerDraftAttachments(threadKey, attachments);
       setPendingConnectionError(
         error instanceof Error ? error.message : "Failed to save the queued message.",
       );
-      return null;
-    }
+    });
+    return messageId;
   }, [selectedThreadDetail, selectedThreadShell]);
 
   const onChangeDraftMessage = useCallback(
diff --git a/apps/mobile/src/state/use-thread-outbox-drain.ts b/apps/mobile/src/state/use-thread-outbox-drain.ts
index 3559fa140fe..d06a4098aab 100644
--- a/apps/mobile/src/state/use-thread-outbox-drain.ts
+++ b/apps/mobile/src/state/use-thread-outbox-drain.ts
@@ -21,7 +21,11 @@ import { toUploadChatImageAttachments } from "../lib/composerImages";
 import { randomHex } from "../lib/uuid";
 import { appAtomRegistry } from "./atom-registry";
 import { useProjects, useThreadShells } from "./entities";
-import { ensureThreadOutboxLoaded, removeThreadOutboxMessage } from "./thread-outbox";
+import {
+  confirmThreadOutboxMessageQueued,
+  ensureThreadOutboxLoaded,
+  removeThreadOutboxMessage,
+} from "./thread-outbox";
 import {
   isQueuedThreadCreationSendable,
   modelSelectionsEqual,
@@ -33,7 +37,7 @@ import {
   type QueuedThreadMessage,
   type ThreadOutboxCommandStage,
 } from "./thread-outbox-model";
-import { threadEnvironment } from "./threads";
+import { environmentThreadShells, threadEnvironment } from "./threads";
 import { useAtomCommand } from "./use-atom-command";
 import {
   editingQueuedMessageIdsAtom,
@@ -349,8 +353,32 @@ export function useThreadOutboxDrain(): void {
             return false;
           },
         );
-      const delivery =
-        deliveryAction === "remove"
+      // Enqueues publish optimistically before their durable write settles.
+      // Confirm the write landed (and the message wasn't rolled back) before
+      // sending, so a failed write can never chase an already-delivered turn.
+      const delivery = confirmThreadOutboxMessageQueued(nextQueuedMessage).then((queued) => {
+        if (!queued) {
+          // Rolled back by a failed write; nothing to deliver or retry.
+          return true;
+        }
+        // The guards evaluated before the confirmation await are stale by now:
+        // the thread may have gone busy, or the user may have opened this
+        // message in the editor. Re-read both and defer to the next drain pass
+        // (returning true skips the failure/backoff path) rather than sending
+        // a payload the user is editing or racing an active turn.
+        if (appAtomRegistry.get(editingQueuedMessageIdsAtom)[nextQueuedMessage.messageId]) {
+          return true;
+        }
+        const freshThread = findThread(
+          appAtomRegistry.get(environmentThreadShells.threadShellsAtom),
+          nextQueuedMessage,
+        );
+        const freshThreadBusy =
+          freshThread?.session?.status === "running" || freshThread?.session?.status === "starting";
+        if (deliveryAction === "send" && creation === undefined && freshThreadBusy) {
+          return true;
+        }
+        return deliveryAction === "remove"
           ? removeQueuedMessage("[thread-outbox] failed to remove message for a missing thread")
           : creation !== undefined
             ? creationProjectCwd !== null
@@ -359,6 +387,7 @@ export function useThreadOutboxDrain(): void {
             : thread !== undefined
               ? sendQueuedMessage(nextQueuedMessage, thread)
               : Promise.resolve(false);
+      });
       void delivery
         .then((sent) => {
           if (sent) {

From 9146ed2f49a094aa8afee7d3a66987e2a82aaaf6 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Thu, 30 Jul 2026 02:15:48 -0700
Subject: [PATCH 11/34] fix(web): show Codex fast mode as a bolt (#4947)

---
 .../src/components/chat/TraitsPicker.test.ts  | 32 ++++++++++++-------
 apps/web/src/components/chat/TraitsPicker.tsx | 22 ++++++-------
 2 files changed, 30 insertions(+), 24 deletions(-)

diff --git a/apps/web/src/components/chat/TraitsPicker.test.ts b/apps/web/src/components/chat/TraitsPicker.test.ts
index 0cb199d64ba..b457f515ff7 100644
--- a/apps/web/src/components/chat/TraitsPicker.test.ts
+++ b/apps/web/src/components/chat/TraitsPicker.test.ts
@@ -35,39 +35,48 @@ const CONTEXT_WINDOW = selectDescriptor(
 
 const CODEX = ProviderDriverKind.make("codex");
 
-function display(descriptors: ReadonlyArray<ProviderOptionDescriptor>, fastModeEnabled: boolean) {
+function display(descriptors: ReadonlyArray<ProviderOptionDescriptor>) {
   return buildTraitsTriggerDisplay({
     provider: CODEX,
     descriptors,
     primarySelectDescriptorId: "reasoningEffort",
     ultrathinkPromptControlled: false,
-    fastModeEnabled,
   });
 }
 
 describe("buildTraitsTriggerDisplay", () => {
   it("omits fast mode from the label entirely when it is off", () => {
-    expect(display([EFFORT, fastModeDescriptor(false), CONTEXT_WINDOW], false)).toEqual({
+    expect(display([EFFORT, fastModeDescriptor(false), CONTEXT_WINDOW])).toEqual({
       label: "High · 1M",
       showFastModeIcon: false,
     });
   });
 
   it("shows the bolt instead of a text label when fast mode is on", () => {
-    expect(display([EFFORT, fastModeDescriptor(true), CONTEXT_WINDOW], true)).toEqual({
+    expect(display([EFFORT, fastModeDescriptor(true), CONTEXT_WINDOW])).toEqual({
       label: "High · 1M",
       showFastModeIcon: true,
     });
   });
 
-  it("omits Codex's default Standard tier beside reasoning", () => {
+  it("renders Codex's Standard and Fast service tiers as fast mode", () => {
     const serviceTier = selectDescriptor(
       "serviceTier",
-      [{ id: "default", label: "Standard", isDefault: true }],
+      [
+        { id: "default", label: "Standard", isDefault: true },
+        { id: "priority", label: "Fast" },
+      ],
       "default",
     );
 
-    expect(display([EFFORT, serviceTier], false).label).toBe("High");
+    expect(display([EFFORT, serviceTier])).toEqual({
+      label: "High",
+      showFastModeIcon: false,
+    });
+    expect(display([EFFORT, { ...serviceTier, currentValue: "priority" }])).toEqual({
+      label: "High",
+      showFastModeIcon: true,
+    });
   });
 
   it("keeps non-fastMode booleans as text labels", () => {
@@ -77,18 +86,18 @@ describe("buildTraitsTriggerDisplay", () => {
       type: "boolean",
       currentValue: true,
     };
-    expect(display([EFFORT, thinking], false)).toEqual({
+    expect(display([EFFORT, thinking])).toEqual({
       label: "High · Thinking On",
       showFastModeIcon: false,
     });
   });
 
   it("falls back to a text label when fast mode is the only trait", () => {
-    expect(display([fastModeDescriptor(true)], true)).toEqual({
+    expect(display([fastModeDescriptor(true)])).toEqual({
       label: "Fast",
       showFastModeIcon: false,
     });
-    expect(display([fastModeDescriptor(false)], false)).toEqual({
+    expect(display([fastModeDescriptor(false)])).toEqual({
       label: "Normal",
       showFastModeIcon: false,
     });
@@ -107,7 +116,7 @@ describe("buildTraitsTriggerDisplay", () => {
         { id: "high", label: "High" },
       ],
     };
-    expect(display([unresolved], false)).toEqual({ label: "", showFastModeIcon: false });
+    expect(display([unresolved])).toEqual({ label: "", showFastModeIcon: false });
   });
 
   it("still renders the prompt-controlled ultrathink label alongside the bolt", () => {
@@ -117,7 +126,6 @@ describe("buildTraitsTriggerDisplay", () => {
         descriptors: [EFFORT, fastModeDescriptor(true)],
         primarySelectDescriptorId: "reasoningEffort",
         ultrathinkPromptControlled: true,
-        fastModeEnabled: true,
       }),
     ).toEqual({ label: "Ultrathink", showFastModeIcon: true });
   });
diff --git a/apps/web/src/components/chat/TraitsPicker.tsx b/apps/web/src/components/chat/TraitsPicker.tsx
index f95f3a4c08a..a9f910ec064 100644
--- a/apps/web/src/components/chat/TraitsPicker.tsx
+++ b/apps/web/src/components/chat/TraitsPicker.tsx
@@ -134,8 +134,6 @@ function getSelectedTraits(
       : getDescriptorStringValue(primarySelectDescriptor)) ?? null;
   const thinkingEnabled =
     typeof thinkingDescriptor?.currentValue === "boolean" ? thinkingDescriptor.currentValue : null;
-  const fastModeEnabled =
-    typeof fastModeDescriptor?.currentValue === "boolean" ? fastModeDescriptor.currentValue : false;
   const contextWindow = getDescriptorStringValue(contextWindowDescriptor);
   const selectedAgent = getDescriptorStringValue(agentDescriptor);
   const selectedAgentLabel = agentDescriptor
@@ -154,7 +152,6 @@ function getSelectedTraits(
     thinkingDescriptor,
     effort,
     thinkingEnabled,
-    fastModeEnabled,
     contextWindow,
     ultrathinkPromptControlled,
     ultrathinkInBodyText,
@@ -392,24 +389,26 @@ export function buildTraitsTriggerDisplay(input: {
   descriptors: ReadonlyArray<ProviderOptionDescriptor>;
   primarySelectDescriptorId: string | null;
   ultrathinkPromptControlled: boolean;
-  fastModeEnabled: boolean;
 }): { label: string; showFastModeIcon: boolean } {
   let hasFastMode = false;
+  let fastModeEnabled = false;
   const labels: Array<string> = [];
   for (const descriptor of input.descriptors) {
     if (descriptor.id === "fastMode" && descriptor.type === "boolean") {
       hasFastMode = true;
+      fastModeEnabled = descriptor.currentValue === true;
       continue;
     }
     if (
       input.provider === "codex" &&
       descriptor.id === "serviceTier" &&
-      descriptor.type === "select" &&
-      input.descriptors.some(({ id }) => id === "reasoningEffort")
+      descriptor.type === "select"
     ) {
       const currentValue = getProviderOptionCurrentValue(descriptor);
-      const currentOption = descriptor.options.find((option) => option.id === currentValue);
-      if (currentOption?.id === "default" && currentOption.isDefault === true) {
+      const fastTier = descriptor.options.find(({ label }) => label === "Fast");
+      if (fastTier && (currentValue === "default" || currentValue === fastTier.id)) {
+        hasFastMode = true;
+        fastModeEnabled = currentValue === fastTier.id;
         continue;
       }
     }
@@ -428,9 +427,9 @@ export function buildTraitsTriggerDisplay(input: {
   // off an empty label list alone would also catch descriptors that resolved to
   // no label at all, printing a bogus "Normal" for a model without fast mode.
   if (labels.length === 0 && hasFastMode) {
-    return { label: input.fastModeEnabled ? "Fast" : "Normal", showFastModeIcon: false };
+    return { label: fastModeEnabled ? "Fast" : "Normal", showFastModeIcon: false };
   }
-  return { label: labels.join(" · "), showFastModeIcon: input.fastModeEnabled };
+  return { label: labels.join(" · "), showFastModeIcon: fastModeEnabled };
 }
 
 export const TraitsPicker = memo(function TraitsPicker({
@@ -447,7 +446,7 @@ export const TraitsPicker = memo(function TraitsPicker({
   ...persistence
 }: TraitsMenuContentProps & TraitsPersistence) {
   const [isMenuOpen, setIsMenuOpen] = useState(false);
-  const { descriptors, primarySelectDescriptor, ultrathinkPromptControlled, fastModeEnabled } =
+  const { descriptors, primarySelectDescriptor, ultrathinkPromptControlled } =
     getTraitsSectionVisibility({
       provider,
       models,
@@ -474,7 +473,6 @@ export const TraitsPicker = memo(function TraitsPicker({
     descriptors,
     primarySelectDescriptorId: primarySelectDescriptor?.id ?? null,
     ultrathinkPromptControlled,
-    fastModeEnabled,
   });
   const fastModeIcon = showFastModeIcon ? (
     <>

From 2f466ffc9ca21b2d536082dd821a1f57e0f354b1 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Thu, 30 Jul 2026 02:29:27 -0700
Subject: [PATCH 12/34] docs: seed worktrees with a copy of real userdata
 instead of banning it (#4949)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---
 AGENTS.md | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index b7786ba84b5..066dafe91c4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -59,7 +59,7 @@ We need to be on the same page with terminology. When communicating, use this la
 ## The three ways to hurt yourself
 
 1. **Killing by pattern.** Never `pkill -f`, `pgrep | kill`, or `kill` a PID you found by matching a name, path, or worktree string. Your own agent process has this worktree's path in its argv, and this machine runs several other dev servers at once. Kill only a PID you captured at spawn, or the owner of your port from `ss -H -ltnp` after confirming `/proc/<pid>/cwd` is your worktree.
-2. **Touching the live install.** `~/.t3/userdata` is the developer's real T3 Code database, in use while you work. Read-only inspection is fine. Never start a server against it, never open it read-write, never clean it up.
+2. **Writing to the live install.** `~/.t3/userdata` is the developer's real T3 Code database, in use while you work. Reading it and copying from it are fine, and a good way to get real test data (see Test data). Never start a server against it, never open it read-write, never clean it up.
 3. **Baking in origins.** Never set `VITE_HTTP_URL` or `VITE_WS_URL` for dev. Dev is single-origin and Vite proxies `/api`, `/ws`, `/oauth`, and `/.well-known`. Setting them bakes localhost into the bundle and silently breaks every remote browser.
 
 ## Hit every surface
@@ -85,10 +85,19 @@ The most common defect in this repo is a change that works on the path you teste
 
 ## Test data
 
-An empty database is a bad test. Seed your worktree's `.t3` instead of pointing at live state:
+An empty database is a bad test. Seed your worktree's `.t3` with a copy of real data instead of pointing at live state:
+
+- Copy from `~/.t3/userdata` (the developer's real data, the most realistic test set) or `~/.t3/dev`. Worktree state lives at `<worktree>/.t3/userdata`.
+- Snapshot the database with `VACUUM INTO`, which is safe even while a server has the source open and yields one consistent file:
+
+  ```bash
+  mkdir -p .t3/userdata
+  rm -f .t3/userdata/state.sqlite*  # VACUUM INTO refuses to overwrite
+  bun -e "new (require('bun:sqlite').Database)(process.env.HOME + '/.t3/userdata/state.sqlite', { readonly: true }).run(\"VACUUM INTO '.t3/userdata/state.sqlite'\")"
+  ```
+
+  A plain `cp` is only safe when no server has the source open, and must bring the `-wal` and `-shm` siblings along. A live file copy is a corrupt copy.
 
-- Copy from `~/.t3/dev`, never from `~/.t3/userdata`.
-- Copy `state.sqlite` together with its `-wal` and `-shm` siblings, and only while no server has the source open. A live copy is a corrupt copy.
 - Bring `secrets` and `settings.json` only if the flow under test needs them.
 - Copy in, never symlink. Data flows one way: into your sandbox, never back out.
 

From 2652fee49bdb0a7d286124cd2bd318155d4a7931 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Thu, 30 Jul 2026 03:01:56 -0700
Subject: [PATCH 13/34] fix(mobile): support dragged images in the composer
 (#4953)

---
 .../ios/T3ComposerEditorView.swift            | 40 ++++++++++++++++++-
 1 file changed, 38 insertions(+), 2 deletions(-)

diff --git a/apps/mobile/modules/t3-composer-editor/ios/T3ComposerEditorView.swift b/apps/mobile/modules/t3-composer-editor/ios/T3ComposerEditorView.swift
index 180da203008..ec5b54aa8f1 100644
--- a/apps/mobile/modules/t3-composer-editor/ios/T3ComposerEditorView.swift
+++ b/apps/mobile/modules/t3-composer-editor/ios/T3ComposerEditorView.swift
@@ -141,7 +141,7 @@ private final class ComposerTextView: UITextView {
     replace(textRange, withText: "")
   }
 
-  private func loadImages(from providers: [NSItemProvider]) {
+  func loadImages(from providers: [NSItemProvider]) {
     let group = DispatchGroup()
     let lock = NSLock()
     var images = [UIImage?](repeating: nil, count: providers.count)
@@ -282,7 +282,7 @@ private final class ComposerTextView: UITextView {
   }
 }
 
-public final class T3ComposerEditorView: ExpoView, UITextViewDelegate {
+public final class T3ComposerEditorView: ExpoView, UITextViewDelegate, UITextDropDelegate {
   private let textView = ComposerTextView()
   private let placeholderLabel = UILabel()
   private var value = ""
@@ -326,6 +326,7 @@ public final class T3ComposerEditorView: ExpoView, UITextViewDelegate {
 
     clipsToBounds = false
     textView.delegate = self
+    textView.textDropDelegate = self
     textView.backgroundColor = .clear
     textView.textContainerInset = .zero
     textView.textContainer.lineFragmentPadding = 0
@@ -500,6 +501,41 @@ public final class T3ComposerEditorView: ExpoView, UITextViewDelegate {
     return true
   }
 
+  public func textDroppableView(
+    _ textDroppableView: UIView & UITextDroppable,
+    proposalForDrop drop: UITextDropRequest
+  ) -> UITextDropProposal {
+    guard droppedImageProviders(in: drop) != nil else {
+      return drop.suggestedProposal
+    }
+
+    // The composer owns image drops so UIKit does not insert NSTextAttachments
+    // that the controlled plain-text value cannot represent.
+    let proposal = UITextDropProposal(operation: .copy)
+    proposal.dropAction = .insert
+    proposal.dropPerformer = .delegate
+    return proposal
+  }
+
+  public func textDroppableView(
+    _ textDroppableView: UIView & UITextDroppable,
+    willPerformDrop drop: UITextDropRequest
+  ) {
+    guard let imageProviders = droppedImageProviders(in: drop) else {
+      return
+    }
+    textView.loadImages(from: imageProviders)
+  }
+
+  private func droppedImageProviders(in drop: UITextDropRequest) -> [NSItemProvider]? {
+    let providers = drop.dropSession.items.map(\.itemProvider)
+    guard !providers.isEmpty,
+          providers.allSatisfy({ $0.canLoadObject(ofClass: UIImage.self) }) else {
+      return nil
+    }
+    return providers
+  }
+
   public func textViewDidBeginEditing(_ textView: UITextView) {
     onComposerFocus()
   }

From 90f3913a81380af7aeafac62f8132aeb98345a12 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Thu, 30 Jul 2026 03:05:25 -0700
Subject: [PATCH 14/34] fix(mobile): stop long iOS threads from jumping while
 scrolling up (#4867)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---
 apps/mobile/package.json                      |   2 +-
 ...2.0.patch => @legendapp__list@3.3.3.patch} | 244 ++++++++++++------
 pnpm-lock.yaml                                |  36 ++-
 pnpm-workspace.yaml                           |   2 +-
 4 files changed, 185 insertions(+), 99 deletions(-)
 rename patches/{@legendapp__list@3.2.0.patch => @legendapp__list@3.3.3.patch} (82%)

diff --git a/apps/mobile/package.json b/apps/mobile/package.json
index c99351547be..9a5e64aa46f 100644
--- a/apps/mobile/package.json
+++ b/apps/mobile/package.json
@@ -49,7 +49,7 @@
     "@expo-google-fonts/dm-sans": "^0.4.2",
     "@expo/metro-runtime": "~56.0.15",
     "@expo/ui": "~56.0.18",
-    "@legendapp/list": "3.2.0",
+    "@legendapp/list": "3.3.3",
     "@noble/curves": "catalog:",
     "@noble/hashes": "catalog:",
     "@pierre/diffs": "catalog:",
diff --git a/patches/@legendapp__list@3.2.0.patch b/patches/@legendapp__list@3.3.3.patch
similarity index 82%
rename from patches/@legendapp__list@3.2.0.patch
rename to patches/@legendapp__list@3.3.3.patch
index 8059fbb5f4e..4fa135d5aa0 100644
--- a/patches/@legendapp__list@3.2.0.patch
+++ b/patches/@legendapp__list@3.3.3.patch
@@ -1,8 +1,8 @@
 diff --git a/keyboard.d.ts b/keyboard.d.ts
-index 5a115ea..2c65d31 100644
+index 7bc3bb8..75ec120 100644
 --- a/keyboard.d.ts
 +++ b/keyboard.d.ts
-@@ -269,7 +269,7 @@ type KeyboardChatComposerInsetListRef = {
+@@ -277,7 +277,7 @@ type KeyboardChatComposerInsetListRef = {
  type KeyboardChatComposerRef = {
      current: Pick<View, "measure"> | null;
  };
@@ -11,7 +11,7 @@ index 5a115ea..2c65d31 100644
      contentInsetEndAdjustment: SharedValue<number>;
      onComposerLayout: (event: LayoutChangeEvent) => void;
  };
-@@ -278,8 +278,10 @@ declare function useKeyboardScrollToEnd({ freeze: freezeProp, listRef }: UseKeyb
+@@ -286,8 +286,10 @@ declare function useKeyboardScrollToEnd({ freeze: freezeProp, listRef }: UseKeyb
      scrollMessageToEnd: ({ animated, closeKeyboard }: ScrollMessageToEndOptions) => Promise<void>;
  };
  declare const KeyboardAwareLegendList: <ItemT>(props: Omit<AnimatedLegendListProps<ItemT>, "anchoredEndSpace" | "contentInsetEndAdjustment" | "renderScrollComponent"> & KeyboardChatScrollViewPropsUnique & {
@@ -187,10 +187,10 @@ index c1dd270..cb0d142 100644
        renderScrollComponent: memoList,
        ...rest
 diff --git a/react-native.d.ts b/react-native.d.ts
-index 72d3f59..435a5fc 100644
+index 8204015..cdeaab7 100644
 --- a/react-native.d.ts
 +++ b/react-native.d.ts
-@@ -284,6 +284,12 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
+@@ -293,6 +293,12 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
       * The adjustment is also rendered as real content padding so the browser scroll range includes it.
       */
      contentInsetEndAdjustment?: number;
@@ -204,10 +204,10 @@ index 72d3f59..435a5fc 100644
       * Number of columns to render items in.
       * @default 1
 diff --git a/react-native.js b/react-native.js
-index 8d4ff89..003b2f7 100644
+index 229f09a..2a1ceb6 100644
 --- a/react-native.js
 +++ b/react-native.js
-@@ -1195,7 +1195,7 @@ function setInitialRenderState(ctx, {
+@@ -930,7 +930,7 @@ function setInitialRenderState(ctx, {
    if (didInitialScroll) {
      state.didFinishInitialScroll = true;
    }
@@ -215,8 +215,8 @@ index 8d4ff89..003b2f7 100644
 +  const isReadyToRender = Boolean(state.didContainersLayout && state.didFinishInitialScroll && !state.insetEndRevealHold);
    if (isReadyToRender && !peek$(ctx, "readyToRender")) {
      set$(ctx, "readyToRender", true);
-     setAdaptiveRender(ctx, "normal");
-@@ -1480,18 +1480,23 @@ function calculateOffsetWithOffsetPosition(ctx, offsetParam, params) {
+     setAdaptiveRender(ctx, "normal", "ready");
+@@ -1259,18 +1259,23 @@ function calculateOffsetWithOffsetPosition(ctx, offsetParam, params) {
  }
  
  // src/core/clampScrollOffset.ts
@@ -242,7 +242,7 @@ index 8d4ff89..003b2f7 100644
    return clampedOffset;
  }
  
-@@ -1626,10 +1631,10 @@ function checkFinishedScrollFrame(ctx) {
+@@ -1406,10 +1411,10 @@ function checkFinishedScrollFrame(ctx) {
      finishScrollTo(ctx);
    }
  }
@@ -255,7 +255,7 @@ index 8d4ff89..003b2f7 100644
      x: ctx.state.props.horizontal ? offset : 0,
      y: ctx.state.props.horizontal ? 0 : offset
    });
-@@ -1676,7 +1681,10 @@ function checkFinishedScrollFallback(ctx) {
+@@ -1456,7 +1461,10 @@ function checkFinishedScrollFallback(ctx) {
            });
            scheduleFallbackCheck(SILENT_INITIAL_SCROLL_RETRY_DELAY_MS);
          } else if (shouldRetryUnalignedEndScroll) {
@@ -267,10 +267,10 @@ index 8d4ff89..003b2f7 100644
            scheduleFallbackCheck(100);
          } else if (shouldFinishZeroTarget || shouldFinishAfterObservedScroll || canFinishInitialScrollWithoutNativeProgress || canFinishAfterSilentNativeDispatch || numChecks > maxChecks) {
            finishScrollTo(ctx);
-@@ -1737,9 +1745,18 @@ function doMaintainScrollAtEnd(ctx) {
+@@ -1517,9 +1525,18 @@ function doMaintainScrollAtEnd(ctx) {
    }
-   state.pendingMaintainScrollAtEnd = false;
    if (shouldMaintainScrollAtEnd) {
+     state.pendingMaintainScrollAtEnd = false;
 +    const maintainAnchoredEndSpace = state.props.anchoredEndSpace;
 +    const maintainAnchorIndex = maintainAnchoredEndSpace == null ? void 0 : maintainAnchoredEndSpace.anchorIndex;
 +    if (maintainAnchorIndex !== void 0 && maintainAnchorIndex >= 0 && maintainAnchorIndex < state.props.data.length && !areKnownOrFixedItemSizesAvailable(ctx, maintainAnchorIndex, state.props.data.length - 1)) {
@@ -287,7 +287,7 @@ index 8d4ff89..003b2f7 100644
      }
      if (!state.maintainingScrollAtEnd) {
        const pendingState = maintainScrollAtEnd.animated ? "pending-animated" : "pending-instant";
-@@ -1759,9 +1776,18 @@ function doMaintainScrollAtEnd(ctx) {
+@@ -1539,9 +1556,18 @@ function doMaintainScrollAtEnd(ctx) {
                y: 0
              });
            } else {
@@ -309,7 +309,18 @@ index 8d4ff89..003b2f7 100644
            }
            setTimeout(
              () => {
-@@ -1888,7 +1914,9 @@ function getPredictedNativeClamp(state, unresolvedAmount, totalSize) {
+@@ -1571,6 +1597,10 @@ function doMaintainScrollAtEnd(ctx) {
+ function requestAdjust(ctx, positionDiff, dataChanged) {
+   const state = ctx.state;
+   if (Math.abs(positionDiff) > 0.1) {
++    // Timestamp for ReanimatedPositionView: repositions caused by an MVCP
++    // size adjustment are already compensated by a contentOffset shift, so
++    // animating them would make rows visibly lurch and slide back.
++    state.lastMVCPAdjustTime = Date.now();
+     const needsScrollWorkaround = Platform.OS === "android" && !IsNewArchitecture && dataChanged && state.scroll <= positionDiff;
+     const doit = () => {
+       if (needsScrollWorkaround) {
+@@ -1674,7 +1704,9 @@ function getPredictedNativeClamp(state, unresolvedAmount, totalSize) {
    if (Math.abs(unresolvedAmount) <= MVCP_POSITION_EPSILON) {
      return 0;
    }
@@ -320,7 +331,7 @@ index 8d4ff89..003b2f7 100644
    const clampDelta = maxScroll - state.scroll;
    if (unresolvedAmount < 0) {
      return Math.max(unresolvedAmount, Math.min(0, clampDelta));
-@@ -1950,7 +1978,7 @@ function resolvePendingNativeMVCPAdjust(ctx, newScroll) {
+@@ -1736,7 +1768,7 @@ function resolvePendingNativeMVCPAdjust(ctx, newScroll) {
      settlePendingNativeMVCPAdjust(ctx, remainingAfterManual, nativeDelta);
      return true;
    }
@@ -329,7 +340,7 @@ index 8d4ff89..003b2f7 100644
    const distanceToClamp = Math.abs(newScroll - expectedNativeClampScroll);
    const isAtExpectedNativeClamp = distanceToClamp <= NATIVE_END_CLAMP_EPSILON;
    if (isAtExpectedNativeClamp) {
-@@ -2083,7 +2111,7 @@ function prepareMVCP(ctx, dataChanged) {
+@@ -1869,7 +1901,7 @@ function prepareMVCP(ctx, dataChanged) {
              if (diff > 0) {
                diff = Math.max(0, totalSize - state.scroll - state.scrollLength);
              } else {
@@ -338,7 +349,7 @@ index 8d4ff89..003b2f7 100644
                state.scroll = maxScroll;
                state.scrollPending = maxScroll;
                diff = 0;
-@@ -2374,8 +2402,121 @@ function scrollToIndex(ctx, {
+@@ -2274,8 +2306,121 @@ function scrollToIndex(ctx, {
  }
  
  // src/core/initialScroll.ts
@@ -460,7 +471,7 @@ index 8d4ff89..003b2f7 100644
    const requestedIndex = target.index;
    const index = requestedIndex !== void 0 ? clampScrollIndex(requestedIndex, ctx.state.props.data.length) : void 0;
    const itemSize = getItemSizeAtIndex(ctx, index);
-@@ -2804,7 +2945,9 @@ function clearFinishedBootstrapInitialScrollTargetIfMovedAway(ctx) {
+@@ -2704,7 +2849,9 @@ function clearFinishedBootstrapInitialScrollTargetIfMovedAway(ctx) {
      return;
    }
    if (didFinishedInitialScrollMoveAwayFromTarget(ctx, initialScroll)) {
@@ -471,7 +482,7 @@ index 8d4ff89..003b2f7 100644
      if (!shouldKeepEndTargetAlive) {
        if (shouldPreserveInitialScrollForFooterLayout(initialScroll)) {
          clearPendingInitialScrollFooterLayout(ctx, {
-@@ -4646,7 +4789,8 @@ function maybeUpdateAnchoredEndSpace(ctx) {
+@@ -4637,7 +4784,8 @@ function maybeUpdateAnchoredEndSpace(ctx) {
        }
        contentBelowAnchor += footerSize + stylePaddingBottom;
        isReady = !hasUnknownTailSize;
@@ -481,7 +492,7 @@ index 8d4ff89..003b2f7 100644
      } else if (anchorIndex >= 0) {
        isReady = false;
      }
-@@ -4664,6 +4808,12 @@ function maybeUpdateAnchoredEndSpace(ctx) {
+@@ -4655,6 +4803,12 @@ function maybeUpdateAnchoredEndSpace(ctx) {
        updateScroll(ctx, state.scroll, true);
      }
      (_b = anchoredEndSpace == null ? void 0 : anchoredEndSpace.onReady) == null ? void 0 : _b.call(anchoredEndSpace, { anchorIndex: nextAnchorIndex, anchorKey: nextAnchorKey, size: nextSize });
@@ -494,7 +505,7 @@ index 8d4ff89..003b2f7 100644
    }
    return nextSize;
  }
-@@ -6462,6 +6612,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
+@@ -6960,6 +7114,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
      dataVersion,
      drawDistance = 250,
      contentInsetEndAdjustment,
@@ -502,15 +513,15 @@ index 8d4ff89..003b2f7 100644
      estimatedItemSize = 100,
      estimatedListSize,
      extraData,
-@@ -6492,6 +6643,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
+@@ -6990,6 +7145,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
      onLayout: onLayoutProp,
      onLoad,
      onMomentumScrollEnd,
 +    onScrollBeginDrag,
      onRefresh,
      onScroll: onScrollProp,
-     onStartReached,
-@@ -6577,7 +6729,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
+     onScrollBeginDrag,
+@@ -7076,7 +7232,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
    const combinedRef = useCombinedRef(refScroller, refScrollView);
    const keyExtractor = keyExtractorProp != null ? keyExtractorProp : ((_item, index) => index.toString());
    const stickyHeaderIndices = stickyHeaderIndicesProp;
@@ -519,15 +530,15 @@ index 8d4ff89..003b2f7 100644
    const previousContentInsetEndAdjustmentRef = React2.useRef(contentInsetEndAdjustmentResolved);
    const alwaysRenderIndices = React2.useMemo(() => {
      const indices = getAlwaysRenderIndices(alwaysRender, dataProp, keyExtractor, anchoredEndSpace == null ? void 0 : anchoredEndSpace.anchorIndex);
-@@ -6710,6 +6862,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
+@@ -7215,6 +7371,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
      contentContainerAlignItems: contentContainerStyle.alignItems,
      contentInset,
      contentInsetEndAdjustment: contentInsetEndAdjustmentResolved,
 +    contentInsetStartAdjustment,
      data: dataProp,
+     dataKey,
      dataVersion,
-     drawDistance,
-@@ -6789,6 +6942,13 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
+@@ -7303,6 +7460,13 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
        return void 0;
      }
      const resolvedOffset = (_a4 = initialScroll.contentOffset) != null ? _a4 : resolveInitialScrollOffset(ctx, initialScroll);
@@ -541,20 +552,15 @@ index 8d4ff89..003b2f7 100644
      return usesBootstrapInitialScroll && ((_b2 = state.initialScrollSession) == null ? void 0 : _b2.kind) === "bootstrap" && Platform.OS === "web" ? void 0 : resolvedOffset;
    }, [usesBootstrapInitialScroll]);
    React2.useLayoutEffect(() => {
-@@ -6995,6 +7155,12 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
-           onMomentumScrollEnd(event);
-         }
-       },
-+      onScrollBeginDrag: (event) => {
+@@ -7526,6 +7690,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
+       onScroll: (event) => onScroll(ctx, event),
+       onScrollBeginDrag: (event) => {
+         var _a4, _b2;
 +        ctx.state.didUserDrag = true;
-+        if (onScrollBeginDrag) {
-+          onScrollBeginDrag(event);
-+        }
-+      },
-       onScroll: (event) => onScroll(ctx, event)
-     }),
-     []
-@@ -7019,6 +7185,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
+         prepareReachedEdgeForNextUserScroll(ctx);
+         (_b2 = (_a4 = state.props).onScrollBeginDrag) == null ? void 0 : _b2.call(_a4, event);
+       },
+@@ -7555,6 +7720,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
        onLayout,
        onLayoutFooter,
        onMomentumScrollEnd: fns.onMomentumScrollEnd,
@@ -563,10 +569,10 @@ index 8d4ff89..003b2f7 100644
        recycleItems,
        refreshControl: refreshControlElement ? stylePaddingTopState > 0 ? React2__namespace.cloneElement(refreshControlElement, {
 diff --git a/react-native.mjs b/react-native.mjs
-index 2e96ca7..fc88d4b 100644
+index c2e0f38..5313086 100644
 --- a/react-native.mjs
 +++ b/react-native.mjs
-@@ -1174,7 +1174,7 @@ function setInitialRenderState(ctx, {
+@@ -909,7 +909,7 @@ function setInitialRenderState(ctx, {
    if (didInitialScroll) {
      state.didFinishInitialScroll = true;
    }
@@ -574,8 +580,8 @@ index 2e96ca7..fc88d4b 100644
 +  const isReadyToRender = Boolean(state.didContainersLayout && state.didFinishInitialScroll && !state.insetEndRevealHold);
    if (isReadyToRender && !peek$(ctx, "readyToRender")) {
      set$(ctx, "readyToRender", true);
-     setAdaptiveRender(ctx, "normal");
-@@ -1459,18 +1459,23 @@ function calculateOffsetWithOffsetPosition(ctx, offsetParam, params) {
+     setAdaptiveRender(ctx, "normal", "ready");
+@@ -1238,18 +1238,23 @@ function calculateOffsetWithOffsetPosition(ctx, offsetParam, params) {
  }
  
  // src/core/clampScrollOffset.ts
@@ -601,7 +607,7 @@ index 2e96ca7..fc88d4b 100644
    return clampedOffset;
  }
  
-@@ -1605,10 +1610,10 @@ function checkFinishedScrollFrame(ctx) {
+@@ -1385,10 +1390,10 @@ function checkFinishedScrollFrame(ctx) {
      finishScrollTo(ctx);
    }
  }
@@ -614,7 +620,7 @@ index 2e96ca7..fc88d4b 100644
      x: ctx.state.props.horizontal ? offset : 0,
      y: ctx.state.props.horizontal ? 0 : offset
    });
-@@ -1655,7 +1660,10 @@ function checkFinishedScrollFallback(ctx) {
+@@ -1435,7 +1440,10 @@ function checkFinishedScrollFallback(ctx) {
            });
            scheduleFallbackCheck(SILENT_INITIAL_SCROLL_RETRY_DELAY_MS);
          } else if (shouldRetryUnalignedEndScroll) {
@@ -626,10 +632,10 @@ index 2e96ca7..fc88d4b 100644
            scheduleFallbackCheck(100);
          } else if (shouldFinishZeroTarget || shouldFinishAfterObservedScroll || canFinishInitialScrollWithoutNativeProgress || canFinishAfterSilentNativeDispatch || numChecks > maxChecks) {
            finishScrollTo(ctx);
-@@ -1716,9 +1724,18 @@ function doMaintainScrollAtEnd(ctx) {
+@@ -1496,9 +1504,18 @@ function doMaintainScrollAtEnd(ctx) {
    }
-   state.pendingMaintainScrollAtEnd = false;
    if (shouldMaintainScrollAtEnd) {
+     state.pendingMaintainScrollAtEnd = false;
 +    const maintainAnchoredEndSpace = state.props.anchoredEndSpace;
 +    const maintainAnchorIndex = maintainAnchoredEndSpace == null ? void 0 : maintainAnchoredEndSpace.anchorIndex;
 +    if (maintainAnchorIndex !== void 0 && maintainAnchorIndex >= 0 && maintainAnchorIndex < state.props.data.length && !areKnownOrFixedItemSizesAvailable(ctx, maintainAnchorIndex, state.props.data.length - 1)) {
@@ -646,7 +652,7 @@ index 2e96ca7..fc88d4b 100644
      }
      if (!state.maintainingScrollAtEnd) {
        const pendingState = maintainScrollAtEnd.animated ? "pending-animated" : "pending-instant";
-@@ -1738,9 +1755,18 @@ function doMaintainScrollAtEnd(ctx) {
+@@ -1518,9 +1535,18 @@ function doMaintainScrollAtEnd(ctx) {
                y: 0
              });
            } else {
@@ -668,7 +674,18 @@ index 2e96ca7..fc88d4b 100644
            }
            setTimeout(
              () => {
-@@ -1867,7 +1893,9 @@ function getPredictedNativeClamp(state, unresolvedAmount, totalSize) {
+@@ -1550,6 +1576,10 @@ function doMaintainScrollAtEnd(ctx) {
+ function requestAdjust(ctx, positionDiff, dataChanged) {
+   const state = ctx.state;
+   if (Math.abs(positionDiff) > 0.1) {
++    // Timestamp for ReanimatedPositionView: repositions caused by an MVCP
++    // size adjustment are already compensated by a contentOffset shift, so
++    // animating them would make rows visibly lurch and slide back.
++    state.lastMVCPAdjustTime = Date.now();
+     const needsScrollWorkaround = Platform.OS === "android" && !IsNewArchitecture && dataChanged && state.scroll <= positionDiff;
+     const doit = () => {
+       if (needsScrollWorkaround) {
+@@ -1653,7 +1683,9 @@ function getPredictedNativeClamp(state, unresolvedAmount, totalSize) {
    if (Math.abs(unresolvedAmount) <= MVCP_POSITION_EPSILON) {
      return 0;
    }
@@ -679,7 +696,7 @@ index 2e96ca7..fc88d4b 100644
    const clampDelta = maxScroll - state.scroll;
    if (unresolvedAmount < 0) {
      return Math.max(unresolvedAmount, Math.min(0, clampDelta));
-@@ -1929,7 +1957,7 @@ function resolvePendingNativeMVCPAdjust(ctx, newScroll) {
+@@ -1715,7 +1747,7 @@ function resolvePendingNativeMVCPAdjust(ctx, newScroll) {
      settlePendingNativeMVCPAdjust(ctx, remainingAfterManual, nativeDelta);
      return true;
    }
@@ -688,7 +705,7 @@ index 2e96ca7..fc88d4b 100644
    const distanceToClamp = Math.abs(newScroll - expectedNativeClampScroll);
    const isAtExpectedNativeClamp = distanceToClamp <= NATIVE_END_CLAMP_EPSILON;
    if (isAtExpectedNativeClamp) {
-@@ -2062,7 +2090,7 @@ function prepareMVCP(ctx, dataChanged) {
+@@ -1848,7 +1880,7 @@ function prepareMVCP(ctx, dataChanged) {
              if (diff > 0) {
                diff = Math.max(0, totalSize - state.scroll - state.scrollLength);
              } else {
@@ -697,7 +714,7 @@ index 2e96ca7..fc88d4b 100644
                state.scroll = maxScroll;
                state.scrollPending = maxScroll;
                diff = 0;
-@@ -2353,8 +2381,121 @@ function scrollToIndex(ctx, {
+@@ -2253,8 +2285,121 @@ function scrollToIndex(ctx, {
  }
  
  // src/core/initialScroll.ts
@@ -819,7 +836,7 @@ index 2e96ca7..fc88d4b 100644
    const requestedIndex = target.index;
    const index = requestedIndex !== void 0 ? clampScrollIndex(requestedIndex, ctx.state.props.data.length) : void 0;
    const itemSize = getItemSizeAtIndex(ctx, index);
-@@ -2783,7 +2924,9 @@ function clearFinishedBootstrapInitialScrollTargetIfMovedAway(ctx) {
+@@ -2683,7 +2828,9 @@ function clearFinishedBootstrapInitialScrollTargetIfMovedAway(ctx) {
      return;
    }
    if (didFinishedInitialScrollMoveAwayFromTarget(ctx, initialScroll)) {
@@ -830,7 +847,7 @@ index 2e96ca7..fc88d4b 100644
      if (!shouldKeepEndTargetAlive) {
        if (shouldPreserveInitialScrollForFooterLayout(initialScroll)) {
          clearPendingInitialScrollFooterLayout(ctx, {
-@@ -4625,7 +4768,8 @@ function maybeUpdateAnchoredEndSpace(ctx) {
+@@ -4616,7 +4763,8 @@ function maybeUpdateAnchoredEndSpace(ctx) {
        }
        contentBelowAnchor += footerSize + stylePaddingBottom;
        isReady = !hasUnknownTailSize;
@@ -840,7 +857,7 @@ index 2e96ca7..fc88d4b 100644
      } else if (anchorIndex >= 0) {
        isReady = false;
      }
-@@ -4643,6 +4787,12 @@ function maybeUpdateAnchoredEndSpace(ctx) {
+@@ -4634,6 +4782,12 @@ function maybeUpdateAnchoredEndSpace(ctx) {
        updateScroll(ctx, state.scroll, true);
      }
      (_b = anchoredEndSpace == null ? void 0 : anchoredEndSpace.onReady) == null ? void 0 : _b.call(anchoredEndSpace, { anchorIndex: nextAnchorIndex, anchorKey: nextAnchorKey, size: nextSize });
@@ -853,7 +870,7 @@ index 2e96ca7..fc88d4b 100644
    }
    return nextSize;
  }
-@@ -6441,6 +6591,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
+@@ -6939,6 +7093,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
      dataVersion,
      drawDistance = 250,
      contentInsetEndAdjustment,
@@ -861,15 +878,7 @@ index 2e96ca7..fc88d4b 100644
      estimatedItemSize = 100,
      estimatedListSize,
      extraData,
-@@ -6471,6 +6622,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
-     onLayout: onLayoutProp,
-     onLoad,
-     onMomentumScrollEnd,
-+    onScrollBeginDrag,
-     onRefresh,
-     onScroll: onScrollProp,
-     onStartReached,
-@@ -6556,7 +6708,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
+@@ -7055,7 +7210,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
    const combinedRef = useCombinedRef(refScroller, refScrollView);
    const keyExtractor = keyExtractorProp != null ? keyExtractorProp : ((_item, index) => index.toString());
    const stickyHeaderIndices = stickyHeaderIndicesProp;
@@ -878,15 +887,15 @@ index 2e96ca7..fc88d4b 100644
    const previousContentInsetEndAdjustmentRef = useRef(contentInsetEndAdjustmentResolved);
    const alwaysRenderIndices = useMemo(() => {
      const indices = getAlwaysRenderIndices(alwaysRender, dataProp, keyExtractor, anchoredEndSpace == null ? void 0 : anchoredEndSpace.anchorIndex);
-@@ -6689,6 +6841,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
+@@ -7194,6 +7349,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
      contentContainerAlignItems: contentContainerStyle.alignItems,
      contentInset,
      contentInsetEndAdjustment: contentInsetEndAdjustmentResolved,
 +    contentInsetStartAdjustment,
      data: dataProp,
+     dataKey,
      dataVersion,
-     drawDistance,
-@@ -6768,6 +6921,13 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
+@@ -7282,6 +7438,13 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
        return void 0;
      }
      const resolvedOffset = (_a4 = initialScroll.contentOffset) != null ? _a4 : resolveInitialScrollOffset(ctx, initialScroll);
@@ -900,20 +909,15 @@ index 2e96ca7..fc88d4b 100644
      return usesBootstrapInitialScroll && ((_b2 = state.initialScrollSession) == null ? void 0 : _b2.kind) === "bootstrap" && Platform.OS === "web" ? void 0 : resolvedOffset;
    }, [usesBootstrapInitialScroll]);
    useLayoutEffect(() => {
-@@ -6974,6 +7134,12 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
-           onMomentumScrollEnd(event);
-         }
-       },
-+      onScrollBeginDrag: (event) => {
+@@ -7505,6 +7668,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
+       onScroll: (event) => onScroll(ctx, event),
+       onScrollBeginDrag: (event) => {
+         var _a4, _b2;
 +        ctx.state.didUserDrag = true;
-+        if (onScrollBeginDrag) {
-+          onScrollBeginDrag(event);
-+        }
-+      },
-       onScroll: (event) => onScroll(ctx, event)
-     }),
-     []
-@@ -6998,6 +7164,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
+         prepareReachedEdgeForNextUserScroll(ctx);
+         (_b2 = (_a4 = state.props).onScrollBeginDrag) == null ? void 0 : _b2.call(_a4, event);
+       },
+@@ -7534,6 +7698,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
        onLayout,
        onLayoutFooter,
        onMomentumScrollEnd: fns.onMomentumScrollEnd,
@@ -922,10 +926,10 @@ index 2e96ca7..fc88d4b 100644
        recycleItems,
        refreshControl: refreshControlElement ? stylePaddingTopState > 0 ? React2.cloneElement(refreshControlElement, {
 diff --git a/reanimated.d.ts b/reanimated.d.ts
-index 7e2d11f..d5b0d66 100644
+index 940da28..28dccbe 100644
 --- a/reanimated.d.ts
 +++ b/reanimated.d.ts
-@@ -285,6 +285,12 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
+@@ -294,6 +294,12 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
       * The adjustment is also rendered as real content padding so the browser scroll range includes it.
       */
      contentInsetEndAdjustment?: number;
@@ -938,3 +942,73 @@ index 7e2d11f..d5b0d66 100644
      /**
       * Number of columns to render items in.
       * @default 1
+diff --git a/reanimated.js b/reanimated.js
+index f1265fa..16dcef0 100644
+--- a/reanimated.js
++++ b/reanimated.js
+@@ -116,7 +116,7 @@ var ReanimatedPositionView = typedMemo(function ReanimatedPositionViewComponent(
+   const [positionValue = POSITION_OUT_OF_VIEW] = useArr$([`containerPosition${id}`]);
+   const prevItemKeyRef = React__namespace.useRef(void 0);
+   let shouldSkipTransitionForRecycleReuse = false;
+-  if (recycleItems && layoutTransition) {
++  if (layoutTransition) {
+     const itemKeySignal = `containerItemKey${id}`;
+     const itemKey = peek$(ctx, itemKeySignal);
+     shouldSkipTransitionForRecycleReuse = itemKey !== void 0 && prevItemKeyRef.current !== void 0 && prevItemKeyRef.current !== itemKey;
+@@ -130,10 +130,20 @@ var ReanimatedPositionView = typedMemo(function ReanimatedPositionViewComponent(
+     () => [style, horizontal ? { left: positionValue } : { top: positionValue }],
+     [horizontal, positionValue, style]
+   );
++  // Two kinds of repositions must not animate: (1) MVCP size adjustments,
++  // which are compensated by an equal contentOffset shift so the row should
++  // not visibly move — animating turns the invisible correction into a
++  // lurch-and-settle; (2) any reposition while the user is actively
++  // scrolling, where rows shifting under the finger reads as jank. The
++  // transition exists to smooth at-rest shifts (streaming text, work-log
++  // folds), so gate it to at-rest moments.
++  const now = Date.now();
++  const isMVCPReposition = now - (ctx.state.lastMVCPAdjustTime || 0) < 300 ||
++    now - (ctx.state.lastNativeScrollTime || 0) < 300;
+   return /* @__PURE__ */ React__namespace.createElement(
+     Reanimated__default.default.View,
+     {
+-      layout: shouldSkipTransitionForRecycleReuse ? void 0 : layoutTransition,
++      layout: shouldSkipTransitionForRecycleReuse || isMVCPReposition ? void 0 : layoutTransition,
+       ref: refView,
+       style: viewStyle,
+       ...rest
+diff --git a/reanimated.mjs b/reanimated.mjs
+index 29a00d5..9c25ec5 100644
+--- a/reanimated.mjs
++++ b/reanimated.mjs
+@@ -92,7 +92,7 @@ var ReanimatedPositionView = typedMemo(function ReanimatedPositionViewComponent(
+   const [positionValue = POSITION_OUT_OF_VIEW] = useArr$([`containerPosition${id}`]);
+   const prevItemKeyRef = React.useRef(void 0);
+   let shouldSkipTransitionForRecycleReuse = false;
+-  if (recycleItems && layoutTransition) {
++  if (layoutTransition) {
+     const itemKeySignal = `containerItemKey${id}`;
+     const itemKey = peek$(ctx, itemKeySignal);
+     shouldSkipTransitionForRecycleReuse = itemKey !== void 0 && prevItemKeyRef.current !== void 0 && prevItemKeyRef.current !== itemKey;
+@@ -106,10 +106,20 @@ var ReanimatedPositionView = typedMemo(function ReanimatedPositionViewComponent(
+     () => [style, horizontal ? { left: positionValue } : { top: positionValue }],
+     [horizontal, positionValue, style]
+   );
++  // Two kinds of repositions must not animate: (1) MVCP size adjustments,
++  // which are compensated by an equal contentOffset shift so the row should
++  // not visibly move — animating turns the invisible correction into a
++  // lurch-and-settle; (2) any reposition while the user is actively
++  // scrolling, where rows shifting under the finger reads as jank. The
++  // transition exists to smooth at-rest shifts (streaming text, work-log
++  // folds), so gate it to at-rest moments.
++  const now = Date.now();
++  const isMVCPReposition = now - (ctx.state.lastMVCPAdjustTime || 0) < 300 ||
++    now - (ctx.state.lastNativeScrollTime || 0) < 300;
+   return /* @__PURE__ */ React.createElement(
+     Reanimated.View,
+     {
+-      layout: shouldSkipTransitionForRecycleReuse ? void 0 : layoutTransition,
++      layout: shouldSkipTransitionForRecycleReuse || isMVCPReposition ? void 0 : layoutTransition,
+       ref: refView,
+       style: viewStyle,
+       ...rest
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index c46d2c6a4dc..816846ab529 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -74,7 +74,7 @@ patchedDependencies:
   '@effect/vitest@4.0.0-beta.102': a607339aab944136a084a05f159aa0f5a69776934d4b835dab8f9992f1c13425
   '@expo/metro-config@56.0.14': 8cb08b5bb7051ed9d2dbe46a2c293c5a1e17f1bd6ddf30de27909e18c921ff46
   '@ff-labs/fff-node@0.9.4': 2b16019ce7ab61aec6478dd02f79ef468cc1d5c51e9d00764f7d2ab8167210c8
-  '@legendapp/list@3.2.0': 9203ec3db86574a31e157a265cefd8997b259cc420a0c4c61c580c80ed8cf78d
+  '@legendapp/list@3.3.3': d162d67b73933ab077d00627cdf52b18ea88b28c4fae4e8340a854df25026f09
   '@pierre/diffs@1.3.0-beta.10': 7ef7cb0cbabb17c15cdb137554068b36f15f6f5265e73fb51452aa3380db91aa
   '@react-native-menu/menu@2.0.0': 5ea3ae4bf1d9baf5443b65c269bb09621c27a68d556f713778f37b1e8d46aaae
   '@react-navigation/native-stack@7.17.6': c7fc101b78d434904425e5a24c22fb0042298dec6f807250486e784f3c717273
@@ -212,8 +212,8 @@ importers:
         specifier: ~56.0.18
         version: 56.0.18(3cdc0dde9f93166d952f1e1bd0cb25c0)
       '@legendapp/list':
-        specifier: 3.2.0
-        version: 3.2.0(patch_hash=9203ec3db86574a31e157a265cefd8997b259cc420a0c4c61c580c80ed8cf78d)(react-dom@19.2.3(react@19.2.3))(react-native@0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.3(@babel/core@7.29.7)(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@types/react@19.2.16)(bufferutil@4.1.0)(react@19.2.3)(utf-8-validate@6.0.6))(react@19.2.3)
+        specifier: 3.3.3
+        version: 3.3.3(patch_hash=d162d67b73933ab077d00627cdf52b18ea88b28c4fae4e8340a854df25026f09)(react-dom@19.2.3(react@19.2.3))(react-native@0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.3(@babel/core@7.29.7)(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@types/react@19.2.16)(bufferutil@4.1.0)(react@19.2.3)(utf-8-validate@6.0.6))(react@19.2.3)
       '@noble/curves':
         specifier: 'catalog:'
         version: 1.9.1
@@ -545,7 +545,7 @@ importers:
         version: 0.9.0
       '@legendapp/list':
         specifier: 3.2.0
-        version: 3.2.0(patch_hash=9203ec3db86574a31e157a265cefd8997b259cc420a0c4c61c580c80ed8cf78d)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+        version: 3.2.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       '@lexical/react':
         specifier: ^0.41.0
         version: 0.41.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(yjs@13.6.31)
@@ -2975,6 +2975,18 @@ packages:
       react-native:
         optional: true
 
+  '@legendapp/list@3.3.3':
+    resolution: {integrity: sha512-p3g4xG6f//s4XQKhuus2189GCQgOHEIbJXHePqeDxj+6UQQQyij4YBjyArNSCgqoP0c03sxDPSOuCFB128Ql6g==}
+    peerDependencies:
+      react: '*'
+      react-dom: '*'
+      react-native: '*'
+    peerDependenciesMeta:
+      react-dom:
+        optional: true
+      react-native:
+        optional: true
+
   '@lexical/clipboard@0.41.0':
     resolution: {integrity: sha512-Ex5lPkb4NBBX1DCPzOAIeHBJFH1bJcmATjREaqpnTfxCbuOeQkt44wchezUA0oDl+iAxNZ3+pLLWiUju9icoSA==}
 
@@ -12982,7 +12994,14 @@ snapshots:
     dependencies:
       jsbi: 4.3.2
 
-  '@legendapp/list@3.2.0(patch_hash=9203ec3db86574a31e157a265cefd8997b259cc420a0c4c61c580c80ed8cf78d)(react-dom@19.2.3(react@19.2.3))(react-native@0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.3(@babel/core@7.29.7)(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@types/react@19.2.16)(bufferutil@4.1.0)(react@19.2.3)(utf-8-validate@6.0.6))(react@19.2.3)':
+  '@legendapp/list@3.2.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+      use-sync-external-store: 1.6.0(react@19.2.6)
+    optionalDependencies:
+      react-dom: 19.2.6(react@19.2.6)
+
+  '@legendapp/list@3.3.3(patch_hash=d162d67b73933ab077d00627cdf52b18ea88b28c4fae4e8340a854df25026f09)(react-dom@19.2.3(react@19.2.3))(react-native@0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.3(@babel/core@7.29.7)(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@types/react@19.2.16)(bufferutil@4.1.0)(react@19.2.3)(utf-8-validate@6.0.6))(react@19.2.3)':
     dependencies:
       react: 19.2.3
       use-sync-external-store: 1.6.0(react@19.2.3)
@@ -12990,13 +13009,6 @@ snapshots:
       react-dom: 19.2.3(react@19.2.3)
       react-native: 0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.3(@babel/core@7.29.7)(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@types/react@19.2.16)(bufferutil@4.1.0)(react@19.2.3)(utf-8-validate@6.0.6)
 
-  '@legendapp/list@3.2.0(patch_hash=9203ec3db86574a31e157a265cefd8997b259cc420a0c4c61c580c80ed8cf78d)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
-    dependencies:
-      react: 19.2.6
-      use-sync-external-store: 1.6.0(react@19.2.6)
-    optionalDependencies:
-      react-dom: 19.2.6(react@19.2.6)
-
   '@lexical/clipboard@0.41.0':
     dependencies:
       '@lexical/html': 0.41.0
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 70f61242053..d41e50e8784 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -127,7 +127,7 @@ patchedDependencies:
   "@effect/vitest@4.0.0-beta.102": patches/@effect__vitest@4.0.0-beta.102.patch
   "@expo/metro-config@56.0.14": patches/@expo%2Fmetro-config@56.0.14.patch
   "@ff-labs/fff-node@0.9.4": patches/@ff-labs__fff-node@0.9.4.patch
-  "@legendapp/list@3.2.0": patches/@legendapp__list@3.2.0.patch
+  "@legendapp/list@3.3.3": patches/@legendapp__list@3.3.3.patch
   "@pierre/diffs@1.3.0-beta.10": patches/@pierre%2Fdiffs@1.3.0-beta.10.patch
   "@react-native-menu/menu@2.0.0": patches/@react-native-menu__menu@2.0.0.patch
   "@react-navigation/native-stack@7.17.6": patches/@react-navigation%2Fnative-stack@7.17.6.patch

From f0c6ba994670bbd9eeab97eab6701d5c3589178d Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Thu, 30 Jul 2026 03:48:33 -0700
Subject: [PATCH 15/34] fix(web): keep worktree default when switching a
 draft's machine (#4964)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---
 apps/web/src/composerDraftStore.test.ts  | 12 ++++++----
 apps/web/src/composerDraftStore.ts       | 29 +++++++++---------------
 apps/web/src/hooks/useHandleNewThread.ts |  3 +--
 3 files changed, 20 insertions(+), 24 deletions(-)

diff --git a/apps/web/src/composerDraftStore.test.ts b/apps/web/src/composerDraftStore.test.ts
index bc1b7107306..19822b8b7ee 100644
--- a/apps/web/src/composerDraftStore.test.ts
+++ b/apps/web/src/composerDraftStore.test.ts
@@ -1103,13 +1103,14 @@ describe("composerDraftStore project draft thread mapping", () => {
     });
   });
 
-  it("clears branch and worktree context when remapping a draft to another environment", () => {
+  it("clears branch and worktree but keeps env mode when remapping a draft to another environment", () => {
     const store = useComposerDraftStore.getState();
     store.setProjectDraftThreadId(projectRef, draftId, {
       threadId,
       branch: "feature/local-only",
       worktreePath: "/tmp/local-worktree",
       envMode: "worktree",
+      startFromOrigin: true,
     });
 
     store.setLogicalProjectDraftThreadId(scopedProjectKey(projectRef), remoteProjectRef, draftId, {
@@ -1121,17 +1122,19 @@ describe("composerDraftStore project draft thread mapping", () => {
       projectId,
       branch: null,
       worktreePath: null,
-      envMode: "local",
+      envMode: "worktree",
+      startFromOrigin: true,
     });
   });
 
-  it("clears branch and worktree context when changing a draft thread project ref", () => {
+  it("clears branch and worktree but keeps env mode when changing a draft thread project ref", () => {
     const store = useComposerDraftStore.getState();
     store.setProjectDraftThreadId(projectRef, draftId, {
       threadId,
       branch: "feature/local-only",
       worktreePath: "/tmp/local-worktree",
       envMode: "worktree",
+      startFromOrigin: true,
     });
 
     store.setDraftThreadContext(draftId, {
@@ -1143,7 +1146,8 @@ describe("composerDraftStore project draft thread mapping", () => {
       projectId,
       branch: null,
       worktreePath: null,
-      envMode: "local",
+      envMode: "worktree",
+      startFromOrigin: true,
     });
   });
 });
diff --git a/apps/web/src/composerDraftStore.ts b/apps/web/src/composerDraftStore.ts
index 16c99abad8a..95dde6187c8 100644
--- a/apps/web/src/composerDraftStore.ts
+++ b/apps/web/src/composerDraftStore.ts
@@ -1340,6 +1340,10 @@ function createDraftThreadState(
     interactionMode?: ProviderInteractionMode;
   },
 ): DraftThreadState {
+  // A project change (including switching environments within a logical
+  // project) invalidates machine-specific context: the branch may not exist
+  // there and the worktree path certainly doesn't. The user's *intent* —
+  // env mode and start-from-origin — is machine-independent and carries.
   const projectChanged =
     existingThread !== undefined &&
     (existingThread.environmentId !== projectRef.environmentId ||
@@ -1358,9 +1362,7 @@ function createDraftThreadState(
       : (options.branch ?? null);
   const nextStartFromOrigin =
     options?.startFromOrigin === undefined
-      ? projectChanged
-        ? false
-        : (existingThread?.startFromOrigin ?? false)
+      ? (existingThread?.startFromOrigin ?? false)
       : options.startFromOrigin;
   return {
     threadId,
@@ -1374,12 +1376,7 @@ function createDraftThreadState(
     branch: nextBranch,
     worktreePath: nextWorktreePath,
     envMode:
-      options?.envMode ??
-      (nextWorktreePath
-        ? "worktree"
-        : projectChanged
-          ? "local"
-          : (existingThread?.envMode ?? "local")),
+      options?.envMode ?? (nextWorktreePath ? "worktree" : (existingThread?.envMode ?? "local")),
     startFromOrigin: nextStartFromOrigin,
     promotedTo: null,
   };
@@ -2343,6 +2340,9 @@ const composerDraftStore = create<ComposerDraftStoreState>()(
             ) {
               return state;
             }
+            // Mirrors createDraftThreadState: a project/environment change
+            // drops machine-specific context (branch, worktree path) but
+            // keeps the user's env mode and start-from-origin intent.
             const projectChanged =
               nextProjectRef.environmentId !== existing.environmentId ||
               nextProjectRef.projectId !== existing.projectId;
@@ -2360,9 +2360,7 @@ const composerDraftStore = create<ComposerDraftStoreState>()(
                 : (options.branch ?? null);
             const nextStartFromOrigin =
               options.startFromOrigin === undefined
-                ? projectChanged
-                  ? false
-                  : existing.startFromOrigin
+                ? existing.startFromOrigin
                 : options.startFromOrigin;
             const nextDraftThread: DraftThreadState = {
               threadId: existing.threadId,
@@ -2378,12 +2376,7 @@ const composerDraftStore = create<ComposerDraftStoreState>()(
               branch: nextBranch,
               worktreePath: nextWorktreePath,
               envMode:
-                options.envMode ??
-                (nextWorktreePath
-                  ? "worktree"
-                  : projectChanged
-                    ? "local"
-                    : (existing.envMode ?? "local")),
+                options.envMode ?? (nextWorktreePath ? "worktree" : (existing.envMode ?? "local")),
               startFromOrigin: nextStartFromOrigin,
               promotedTo: existing.promotedTo ?? null,
             };
diff --git a/apps/web/src/hooks/useHandleNewThread.ts b/apps/web/src/hooks/useHandleNewThread.ts
index 2479d6ba02f..74ad952e5a2 100644
--- a/apps/web/src/hooks/useHandleNewThread.ts
+++ b/apps/web/src/hooks/useHandleNewThread.ts
@@ -183,8 +183,7 @@ export function useNewThreadHandler() {
           // The workspace context must also ride along here: when projectRef
           // targets a different physical member of the logical project,
           // createDraftThreadState treats the remap as a project change and
-          // would otherwise wipe branch/worktree and force "local" mode,
-          // undoing the write above.
+          // would otherwise wipe branch/worktree, undoing the write above.
           setLogicalProjectDraftThreadId(
             logicalProjectKey,
             projectRef,

From 69a18ce912ac3ae93cf498cfe0cee40beb49fb9f Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Thu, 30 Jul 2026 04:10:26 -0700
Subject: [PATCH 16/34] perf(mobile): reconnect environments immediately on
 resume (#4878)

---
 .../src/connection/app-state-wakeups.test.ts  |  21 ++
 .../src/connection/app-state-wakeups.ts       |  18 ++
 apps/mobile/src/connection/platform.ts        |  49 +++-
 docs/architecture/connection-runtime.md       |   3 +
 .../src/authorization/layer.test.ts           |  92 ++++++--
 .../src/authorization/service.ts              |  74 +++---
 .../src/connection/supervisor.test.ts         | 221 +++++++++++++++++-
 .../src/connection/supervisor.ts              | 112 +++++++--
 .../client-runtime/src/connection/wakeups.ts  |  18 +-
 .../src/state/shell-sync.test.ts              |  15 ++
 packages/client-runtime/src/state/shell.ts    |   2 +-
 .../src/state/threads-sync.test.ts            |  13 ++
 packages/client-runtime/src/state/threads.ts  |   2 +-
 13 files changed, 547 insertions(+), 93 deletions(-)
 create mode 100644 apps/mobile/src/connection/app-state-wakeups.test.ts
 create mode 100644 apps/mobile/src/connection/app-state-wakeups.ts

diff --git a/apps/mobile/src/connection/app-state-wakeups.test.ts b/apps/mobile/src/connection/app-state-wakeups.test.ts
new file mode 100644
index 00000000000..4e8bdf1edf4
--- /dev/null
+++ b/apps/mobile/src/connection/app-state-wakeups.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it } from "@effect/vitest";
+
+import {
+  MOBILE_BACKGROUND_RECONNECT_AFTER_MS,
+  mobileApplicationActiveWakeup,
+} from "./app-state-wakeups";
+
+describe("mobileApplicationActiveWakeup", () => {
+  it("uses a fast probe after a short interruption", () => {
+    expect(mobileApplicationActiveWakeup(null, 20_000)).toBe("application-active-probe");
+    expect(
+      mobileApplicationActiveWakeup(20_000, 20_000 + MOBILE_BACKGROUND_RECONNECT_AFTER_MS - 1),
+    ).toBe("application-active-probe");
+  });
+
+  it("replaces the session after a meaningful background suspension", () => {
+    expect(
+      mobileApplicationActiveWakeup(20_000, 20_000 + MOBILE_BACKGROUND_RECONNECT_AFTER_MS),
+    ).toBe("application-active-reconnect");
+  });
+});
diff --git a/apps/mobile/src/connection/app-state-wakeups.ts b/apps/mobile/src/connection/app-state-wakeups.ts
new file mode 100644
index 00000000000..185ff744958
--- /dev/null
+++ b/apps/mobile/src/connection/app-state-wakeups.ts
@@ -0,0 +1,18 @@
+import type { Wakeups } from "@t3tools/client-runtime/connection";
+
+export const MOBILE_BACKGROUND_RECONNECT_AFTER_MS = 10_000;
+
+export type MobileApplicationActiveWakeup = Extract<
+  Wakeups.ConnectionWakeup,
+  "application-active-probe" | "application-active-reconnect"
+>;
+
+export function mobileApplicationActiveWakeup(
+  backgroundedAtMs: number | null,
+  activeAtMs: number,
+): MobileApplicationActiveWakeup {
+  return backgroundedAtMs !== null &&
+    activeAtMs - backgroundedAtMs >= MOBILE_BACKGROUND_RECONNECT_AFTER_MS
+    ? "application-active-reconnect"
+    : "application-active-probe";
+}
diff --git a/apps/mobile/src/connection/platform.ts b/apps/mobile/src/connection/platform.ts
index b8a13137c88..852535d9d10 100644
--- a/apps/mobile/src/connection/platform.ts
+++ b/apps/mobile/src/connection/platform.ts
@@ -30,6 +30,7 @@ import * as MobileStorage from "../persistence/mobile-storage";
 import { appAtomRegistry } from "../state/atom-registry";
 import { clearThreadOutboxEnvironment } from "../state/thread-outbox";
 import { clearComposerDraftsEnvironment } from "../state/use-composer-drafts";
+import { mobileApplicationActiveWakeup } from "./app-state-wakeups";
 import { connectionStorageLayer } from "./storage";
 
 function networkStatus(state: Network.NetworkState): "unknown" | "offline" | "online" {
@@ -54,27 +55,53 @@ const connectivityLayer = Connectivity.layer({
   ),
   changes: Stream.callback((queue) =>
     Effect.acquireRelease(
-      Effect.sync(() =>
-        Network.addNetworkStateListener((state) => {
+      Effect.sync(() => {
+        let active = true;
+        const networkSubscription = Network.addNetworkStateListener((state) => {
           Queue.offerUnsafe(queue, networkStatus(state));
-        }),
-      ),
-      (subscription) => Effect.sync(() => subscription.remove()),
+        });
+        const appStateSubscription = AppState.addEventListener("change", (state) => {
+          if (state !== "active") {
+            return;
+          }
+          void Network.getNetworkStateAsync()
+            .then((current) => {
+              if (active) {
+                Queue.offerUnsafe(queue, networkStatus(current));
+              }
+            })
+            .catch(() => undefined);
+        });
+        return {
+          close: () => {
+            active = false;
+            networkSubscription.remove();
+            appStateSubscription.remove();
+          },
+        };
+      }),
+      ({ close }) => Effect.sync(close),
     ).pipe(Effect.asVoid),
   ),
 });
 
 const wakeupsLayer = Wakeups.layer({
   changes: Stream.merge(
-    Stream.callback<"application-active">((queue) =>
+    Stream.callback<"application-active-probe" | "application-active-reconnect">((queue) =>
       Effect.acquireRelease(
-        Effect.sync(() =>
-          AppState.addEventListener("change", (state) => {
+        Effect.sync(() => {
+          let backgroundedAtMs = AppState.currentState === "background" ? Date.now() : null;
+          return AppState.addEventListener("change", (state) => {
+            if (state === "background") {
+              backgroundedAtMs = Date.now();
+              return;
+            }
             if (state === "active") {
-              Queue.offerUnsafe(queue, "application-active");
+              Queue.offerUnsafe(queue, mobileApplicationActiveWakeup(backgroundedAtMs, Date.now()));
+              backgroundedAtMs = null;
             }
-          }),
-        ),
+          });
+        }),
         (subscription) => Effect.sync(() => subscription.remove()),
       ).pipe(Effect.asVoid),
     ),
diff --git a/docs/architecture/connection-runtime.md b/docs/architecture/connection-runtime.md
index 06f7e6338ca..acfd2ab5983 100644
--- a/docs/architecture/connection-runtime.md
+++ b/docs/architecture/connection-runtime.md
@@ -40,6 +40,9 @@ The supervisor is the only retry owner.
    seconds.
 5. Connectivity changes, application activation, credential changes, and
    explicit user retry interrupt the current wait and trigger a fresh attempt.
+   Application activation also resets the backoff ladder. Mobile briefly probes
+   a session after short interruptions and replaces it immediately after a
+   meaningful background suspension.
 6. Authentication or configuration failures remain blocked until an external
    wakeup changes the relevant input.
 7. An involuntary session close keeps the registration and cache, then retries.
diff --git a/packages/client-runtime/src/authorization/layer.test.ts b/packages/client-runtime/src/authorization/layer.test.ts
index 1d2c6c6cca7..466a5c2dd4e 100644
--- a/packages/client-runtime/src/authorization/layer.test.ts
+++ b/packages/client-runtime/src/authorization/layer.test.ts
@@ -4,6 +4,7 @@ import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import * as Ref from "effect/Ref";
+import * as TestClock from "effect/testing/TestClock";
 
 import * as ManagedRelay from "../relay/managedRelay.ts";
 import { remoteHttpClientLayer } from "../rpc/http.ts";
@@ -155,6 +156,81 @@ const makeHarness = Effect.fn("TestRemoteAuthorization.makeHarness")(function* (
 });
 
 describe("RemoteEnvironmentAuthorization", () => {
+  it.effect("reuses a validated bearer descriptor while issuing fresh websocket tickets", () =>
+    Effect.gen(function* () {
+      const harness = yield* makeHarness({
+        responses: [
+          Response.json(DESCRIPTOR),
+          websocketTicket("first-ticket"),
+          websocketTicket("second-ticket"),
+        ],
+      });
+
+      const [first, second] = yield* Effect.gen(function* () {
+        const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
+        const authorize = () =>
+          remote.authorizeBearer({
+            expectedEnvironmentId: ENVIRONMENT_ID,
+            httpBaseUrl: ENDPOINT.httpBaseUrl,
+            wsBaseUrl: ENDPOINT.wsBaseUrl,
+            bearerToken: "bearer-token",
+          });
+        return [yield* authorize(), yield* authorize()] as const;
+      }).pipe(Effect.provide(harness.layer));
+
+      expect(first.socketUrl).toContain("wsTicket=first-ticket");
+      expect(second.socketUrl).toContain("wsTicket=second-ticket");
+      expect(
+        harness.fetch.calls.filter(([url]) => String(url).endsWith("/.well-known/t3/environment")),
+      ).toHaveLength(1);
+      expect(
+        harness.fetch.calls.filter(([url]) => String(url).endsWith("/api/auth/websocket-ticket")),
+      ).toHaveLength(2);
+    }),
+  );
+
+  it.effect("revalidates a bearer descriptor after the cache expires", () =>
+    Effect.gen(function* () {
+      const reassignedEnvironmentId = EnvironmentId.make("environment-2");
+      const harness = yield* makeHarness({
+        responses: [
+          Response.json(DESCRIPTOR),
+          websocketTicket("first-ticket"),
+          Response.json({
+            ...DESCRIPTOR,
+            environmentId: reassignedEnvironmentId,
+          }),
+        ],
+      });
+
+      const failure = yield* Effect.gen(function* () {
+        const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
+        const authorize = () =>
+          remote.authorizeBearer({
+            expectedEnvironmentId: ENVIRONMENT_ID,
+            httpBaseUrl: ENDPOINT.httpBaseUrl,
+            wsBaseUrl: ENDPOINT.wsBaseUrl,
+            bearerToken: "bearer-token",
+          });
+
+        yield* authorize();
+        yield* TestClock.adjust("10 seconds");
+        return yield* authorize().pipe(Effect.flip);
+      }).pipe(Effect.provide(Layer.merge(harness.layer, TestClock.layer())));
+
+      expect(failure).toEqual(
+        expect.objectContaining({
+          _tag: "ConnectionBlockedError",
+          reason: "configuration",
+          detail: `Connected environment ${reassignedEnvironmentId} does not match ${ENVIRONMENT_ID}.`,
+        }),
+      );
+      expect(
+        harness.fetch.calls.filter(([url]) => String(url).endsWith("/.well-known/t3/environment")),
+      ).toHaveLength(2);
+    }),
+  );
+
   it.effect("reuses a valid persisted environment token without contacting the relay", () =>
     Effect.gen(function* () {
       const cached = new TokenStore.RemoteDpopAccessToken({
@@ -265,7 +341,7 @@ describe("RemoteEnvironmentAuthorization", () => {
     }),
   );
 
-  it.effect("refreshes a cached endpoint after consecutive transient failures", () =>
+  it.effect("refreshes a cached endpoint after its first transient failure", () =>
     Effect.gen(function* () {
       const cached = new TokenStore.RemoteDpopAccessToken({
         environmentId: ENVIRONMENT_ID,
@@ -279,7 +355,6 @@ describe("RemoteEnvironmentAuthorization", () => {
         initialToken: cached,
         responses: [
           new Response("endpoint unavailable", { status: 503 }),
-          new Response("endpoint still unavailable", { status: 503 }),
           Response.json(DESCRIPTOR),
           accessToken("replacement-access-token"),
           websocketTicket("replacement-ticket"),
@@ -288,17 +363,6 @@ describe("RemoteEnvironmentAuthorization", () => {
 
       const authorized = yield* Effect.gen(function* () {
         const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
-        const firstFailure = yield* remote
-          .authorizeDpop({
-            expectedEnvironmentId: ENVIRONMENT_ID,
-            obtainBootstrap: harness.obtainBootstrap,
-          })
-          .pipe(Effect.flip);
-
-        expect(firstFailure._tag).toBe("ConnectionTransientError");
-        expect(yield* Ref.get(harness.bootstrapCalls)).toBe(0);
-        expect((yield* Ref.get(harness.tokens)).get(ENVIRONMENT_ID)).toBe(cached);
-
         return yield* remote.authorizeDpop({
           expectedEnvironmentId: ENVIRONMENT_ID,
           obtainBootstrap: harness.obtainBootstrap,
@@ -312,7 +376,7 @@ describe("RemoteEnvironmentAuthorization", () => {
           accessToken: "replacement-access-token",
         }),
       );
-      expect(harness.fetch.calls).toHaveLength(5);
+      expect(harness.fetch.calls).toHaveLength(4);
     }),
   );
 
diff --git a/packages/client-runtime/src/authorization/service.ts b/packages/client-runtime/src/authorization/service.ts
index 624ecf7f672..410c7a39dc0 100644
--- a/packages/client-runtime/src/authorization/service.ts
+++ b/packages/client-runtime/src/authorization/service.ts
@@ -1,4 +1,4 @@
-import { EnvironmentId } from "@t3tools/contracts";
+import { EnvironmentId, type ExecutionEnvironmentDescriptor } from "@t3tools/contracts";
 import type { RelayManagedEndpoint } from "@t3tools/contracts/relay";
 import {
   exchangeRemoteDpopAccessToken,
@@ -58,7 +58,8 @@ export class RemoteEnvironmentAuthorization extends Context.Service<
 >()("@t3tools/client-runtime/authorization/service/RemoteEnvironmentAuthorization") {}
 
 const TOKEN_EXPIRY_SAFETY_MARGIN_MS = 60_000;
-const CACHED_ENDPOINT_FAILURE_THRESHOLD = 2;
+const CACHED_ENDPOINT_SOCKET_TIMEOUT_MS = 3_000;
+const BEARER_DESCRIPTOR_CACHE_TTL_MS = 10_000;
 
 function mapDpopSocketError(error: RemoteEnvironmentAuthError | ConnectionAttemptError) {
   return error._tag === "ConnectionTransientError" || error._tag === "ConnectionBlockedError"
@@ -79,25 +80,16 @@ export const make = Effect.gen(function* () {
   const presentation = yield* ClientCapabilities.ClientPresentation;
   const tokenStore = yield* TokenStore.RemoteDpopAccessTokenStore;
   const httpClient = yield* HttpClient.HttpClient;
-  const cachedEndpointFailures = yield* Ref.make<ReadonlyMap<string, number>>(new Map());
-
-  const resetCachedEndpointFailures = (environmentId: string) =>
-    Ref.update(cachedEndpointFailures, (current) => {
-      if (!current.has(environmentId)) {
-        return current;
+  const bearerDescriptors = yield* Ref.make<
+    ReadonlyMap<
+      EnvironmentId,
+      {
+        readonly httpBaseUrl: string;
+        readonly descriptor: ExecutionEnvironmentDescriptor;
+        readonly validatedAtEpochMs: number;
       }
-      const next = new Map(current);
-      next.delete(environmentId);
-      return next;
-    });
-
-  const recordCachedEndpointFailure = (environmentId: string) =>
-    Ref.modify(cachedEndpointFailures, (current) => {
-      const failureCount = (current.get(environmentId) ?? 0) + 1;
-      const next = new Map(current);
-      next.set(environmentId, failureCount);
-      return [failureCount, next] as const;
-    });
+    >
+  >(new Map());
 
   const authorizeBearer = Effect.fn("clientRuntime.connection.remote.authorizeBearer")(
     function* (input: {
@@ -108,15 +100,33 @@ export const make = Effect.gen(function* () {
       readonly wsBaseUrl: string;
       readonly bearerToken: string;
     }) {
-      const descriptor = yield* fetchDescriptor(input.httpBaseUrl).pipe(
-        Effect.provideService(HttpClient.HttpClient, httpClient),
-      );
+      const now = yield* Clock.currentTimeMillis;
+      const cachedDescriptor = (yield* Ref.get(bearerDescriptors)).get(input.expectedEnvironmentId);
+      const canReuseDescriptor =
+        cachedDescriptor?.httpBaseUrl === input.httpBaseUrl &&
+        cachedDescriptor.validatedAtEpochMs + BEARER_DESCRIPTOR_CACHE_TTL_MS > now;
+      const descriptor = canReuseDescriptor
+        ? cachedDescriptor.descriptor
+        : yield* fetchDescriptor(input.httpBaseUrl).pipe(
+            Effect.provideService(HttpClient.HttpClient, httpClient),
+          );
       if (descriptor.environmentId !== input.expectedEnvironmentId) {
         return yield* environmentMismatchError({
           expected: input.expectedEnvironmentId,
           actual: descriptor.environmentId,
         });
       }
+      if (!canReuseDescriptor) {
+        yield* Ref.update(bearerDescriptors, (current) => {
+          const next = new Map(current);
+          next.set(input.expectedEnvironmentId, {
+            httpBaseUrl: input.httpBaseUrl,
+            descriptor,
+            validatedAtEpochMs: now,
+          });
+          return next;
+        });
+      }
       const socketUrl = yield* resolveRemoteWebSocketConnectionUrl({
         wsBaseUrl: input.wsBaseUrl,
         httpBaseUrl: input.httpBaseUrl,
@@ -139,7 +149,7 @@ export const make = Effect.gen(function* () {
   );
 
   const createDpopSocketUrl = Effect.fn("clientRuntime.connection.remote.createDpopSocketUrl")(
-    function* (token: TokenStore.RemoteDpopAccessToken) {
+    function* (token: TokenStore.RemoteDpopAccessToken, timeoutMs?: number) {
       const ticketProof = yield* signer
         .createProof({
           method: "POST",
@@ -160,6 +170,7 @@ export const make = Effect.gen(function* () {
         httpBaseUrl: token.endpoint.httpBaseUrl,
         accessToken: token.accessToken,
         dpopProof: ticketProof,
+        ...(timeoutMs === undefined ? {} : { timeoutMs }),
       }).pipe(Effect.provideService(HttpClient.HttpClient, httpClient));
     },
   );
@@ -196,9 +207,11 @@ export const make = Effect.gen(function* () {
         yield* Effect.annotateCurrentSpan({
           "connection.remote_token_cache": "hit",
         });
-        const cachedSocket = yield* createDpopSocketUrl(cached.value).pipe(Effect.result);
+        const cachedSocket = yield* createDpopSocketUrl(
+          cached.value,
+          CACHED_ENDPOINT_SOCKET_TIMEOUT_MS,
+        ).pipe(Effect.result);
         if (Result.isSuccess(cachedSocket)) {
-          yield* resetCachedEndpointFailures(input.expectedEnvironmentId);
           return {
             environmentId: cached.value.environmentId,
             label: cached.value.label,
@@ -213,20 +226,11 @@ export const make = Effect.gen(function* () {
         if (cachedSocket.failure._tag === "ConnectionBlockedError") {
           return yield* mapDpopSocketError(cachedSocket.failure);
         }
-        const mappedFailure = mapDpopSocketError(cachedSocket.failure);
-        if (mappedFailure._tag === "ConnectionTransientError") {
-          const failureCount = yield* recordCachedEndpointFailure(input.expectedEnvironmentId);
-          if (failureCount < CACHED_ENDPOINT_FAILURE_THRESHOLD) {
-            return yield* mappedFailure;
-          }
-        }
         yield* tokenStore
           .remove(input.expectedEnvironmentId)
           .pipe(Effect.withSpan("environment.authorization.accessToken.remove"));
-        yield* resetCachedEndpointFailures(input.expectedEnvironmentId);
       }
 
-      yield* resetCachedEndpointFailures(input.expectedEnvironmentId);
       yield* Effect.annotateCurrentSpan({
         "connection.remote_token_cache": "miss",
       });
diff --git a/packages/client-runtime/src/connection/supervisor.test.ts b/packages/client-runtime/src/connection/supervisor.test.ts
index f3901e42251..b31ea9b4fc9 100644
--- a/packages/client-runtime/src/connection/supervisor.test.ts
+++ b/packages/client-runtime/src/connection/supervisor.test.ts
@@ -124,7 +124,7 @@ const makeHarness = Effect.fn("TestConnectionHarness.make")(function* (options?:
   const releaseCount = yield* Ref.make(0);
   const wakeups = yield* SubscriptionRef.make<{
     readonly sequence: number;
-    readonly reason: "application-active" | "credentials-changed";
+    readonly reason: ConnectionWakeups.ConnectionWakeup;
   }>({
     sequence: 0,
     reason: "application-active",
@@ -198,7 +198,7 @@ const makeHarness = Effect.fn("TestConnectionHarness.make")(function* (options?:
     sessionCount,
     releaseCount,
     setNetworkStatus: (status: NetworkStatus) => SubscriptionRef.set(networkStatus, status),
-    wake: (reason: "application-active" | "credentials-changed") =>
+    wake: (reason: ConnectionWakeups.ConnectionWakeup) =>
       SubscriptionRef.update(wakeups, (event) => ({
         sequence: event.sequence + 1,
         reason,
@@ -311,6 +311,38 @@ describe("EnvironmentSupervisor", () => {
     }),
   );
 
+  it.effect("resets retries when activation arrives before the network returns", () =>
+    Effect.gen(function* () {
+      const harness = yield* makeHarness();
+      const supervisor = yield* EnvironmentSupervisor.make(TARGET_ENTRY, {
+        initiallyDesired: true,
+      }).pipe(Effect.provide(harness.dependencies));
+
+      yield* awaitState(supervisor.state, (state) => state.phase === "connected");
+      yield* harness.closeLatestSession();
+      yield* awaitState(
+        supervisor.state,
+        (state) => state.phase === "backoff" && state.attempt === 1,
+      );
+      yield* harness.setNetworkStatus("offline");
+      yield* awaitState(
+        supervisor.state,
+        (state) => state.phase === "offline" && state.attempt === 2,
+      );
+
+      yield* harness.wake("application-active-reconnect");
+      yield* awaitState(
+        supervisor.state,
+        (state) => state.phase === "offline" && state.attempt === 1,
+      );
+      yield* harness.setNetworkStatus("online");
+      yield* awaitState(
+        supervisor.state,
+        (state) => state.phase === "connected" && state.generation === 2 && state.attempt === 1,
+      );
+    }),
+  );
+
   it.effect("retries forever with exponential backoff capped at sixteen seconds", () =>
     Effect.gen(function* () {
       const harness = yield* makeHarness({
@@ -501,6 +533,38 @@ describe("EnvironmentSupervisor", () => {
     }).pipe(Effect.provide(TestClock.layer())),
   );
 
+  it.effect("resets retries when activation wakes a blocked connection", () =>
+    Effect.gen(function* () {
+      const harness = yield* makeHarness({
+        prepare: (attempt) =>
+          attempt === 1
+            ? Effect.fail(transient())
+            : attempt === 2
+              ? Effect.fail(blocked())
+              : Effect.succeed(PREPARED_CONNECTION),
+      });
+      const supervisor = yield* EnvironmentSupervisor.make(TARGET_ENTRY, {
+        initiallyDesired: true,
+      }).pipe(Effect.provide(harness.dependencies));
+
+      yield* awaitState(
+        supervisor.state,
+        (state) => state.phase === "backoff" && state.attempt === 1,
+      );
+      yield* TestClock.adjust("1 second");
+      yield* awaitState(
+        supervisor.state,
+        (state) => state.phase === "blocked" && state.attempt === 2,
+      );
+
+      yield* harness.wake("application-active-reconnect");
+      yield* awaitState(
+        supervisor.state,
+        (state) => state.phase === "connected" && state.attempt === 1,
+      );
+    }).pipe(Effect.provide(TestClock.layer())),
+  );
+
   it.effect("releases a live session while offline and starts a new generation when online", () =>
     Effect.gen(function* () {
       const harness = yield* makeHarness();
@@ -652,6 +716,101 @@ describe("EnvironmentSupervisor", () => {
     }).pipe(Effect.provide(TestClock.layer())),
   );
 
+  it.effect("restarts the retry ladder when mobile returns to the foreground", () =>
+    Effect.gen(function* () {
+      const harness = yield* makeHarness();
+      const supervisor = yield* EnvironmentSupervisor.make(TARGET_ENTRY, {
+        initiallyDesired: true,
+      }).pipe(Effect.provide(harness.dependencies));
+
+      yield* awaitState(supervisor.state, (state) => state.phase === "connected");
+      yield* harness.closeLatestSession();
+      yield* awaitState(
+        supervisor.state,
+        (state) => state.phase === "backoff" && state.attempt === 1,
+      );
+      yield* TestClock.adjust("1 second");
+      yield* awaitState(
+        supervisor.state,
+        (state) => state.phase === "connected" && state.generation === 2,
+      );
+      yield* harness.closeLatestSession();
+      yield* awaitState(
+        supervisor.state,
+        (state) => state.phase === "backoff" && state.attempt === 2,
+      );
+
+      yield* harness.wake("application-active-reconnect");
+      yield* awaitState(
+        supervisor.state,
+        (state) => state.phase === "connected" && state.generation === 3 && state.attempt === 1,
+      );
+      yield* harness.closeLatestSession();
+      yield* awaitState(
+        supervisor.state,
+        (state) => state.phase === "backoff" && state.attempt === 1,
+      );
+
+      expect(yield* Ref.get(harness.sessionCount)).toBe(3);
+    }).pipe(Effect.provide(TestClock.layer())),
+  );
+
+  it.effect("restarts the retry ladder when a long resume replaces a connected session", () =>
+    Effect.gen(function* () {
+      const harness = yield* makeHarness();
+      const supervisor = yield* EnvironmentSupervisor.make(TARGET_ENTRY, {
+        initiallyDesired: true,
+      }).pipe(Effect.provide(harness.dependencies));
+
+      yield* awaitState(supervisor.state, (state) => state.phase === "connected");
+      yield* harness.closeLatestSession();
+      yield* awaitState(
+        supervisor.state,
+        (state) => state.phase === "backoff" && state.attempt === 1,
+      );
+      yield* TestClock.adjust("1 second");
+      yield* awaitState(
+        supervisor.state,
+        (state) => state.phase === "connected" && state.generation === 2 && state.attempt === 2,
+      );
+
+      yield* harness.wake("application-active-reconnect");
+      yield* awaitState(
+        supervisor.state,
+        (state) => state.phase === "connected" && state.generation === 3 && state.attempt === 1,
+      );
+    }).pipe(Effect.provide(TestClock.layer())),
+  );
+
+  it.effect("restarts the retry ladder when a long resume interrupts connection setup", () =>
+    Effect.gen(function* () {
+      const harness = yield* makeHarness({
+        prepare: (attempt) => (attempt === 2 ? Effect.never : Effect.succeed(PREPARED_CONNECTION)),
+      });
+      const supervisor = yield* EnvironmentSupervisor.make(TARGET_ENTRY, {
+        initiallyDesired: true,
+      }).pipe(Effect.provide(harness.dependencies));
+
+      yield* awaitState(supervisor.state, (state) => state.phase === "connected");
+      yield* harness.closeLatestSession();
+      yield* awaitState(
+        supervisor.state,
+        (state) => state.phase === "backoff" && state.attempt === 1,
+      );
+      yield* TestClock.adjust("1 second");
+      yield* awaitState(
+        supervisor.state,
+        (state) => state.phase === "connecting" && state.attempt === 2,
+      );
+
+      yield* harness.wake("application-active-reconnect");
+      yield* awaitState(
+        supervisor.state,
+        (state) => state.phase === "connected" && state.generation === 2 && state.attempt === 1,
+      );
+    }).pipe(Effect.provide(TestClock.layer())),
+  );
+
   it.effect("probes the active session without reconnecting on application activation", () =>
     Effect.gen(function* () {
       const probeCount = yield* Ref.make(0);
@@ -677,6 +836,58 @@ describe("EnvironmentSupervisor", () => {
     }),
   );
 
+  it.effect("immediately replaces a mobile session after a long background resume", () =>
+    Effect.gen(function* () {
+      const probeCount = yield* Ref.make(0);
+      const harness = yield* makeHarness({
+        probe: () => Ref.update(probeCount, (count) => count + 1),
+      });
+      const supervisor = yield* EnvironmentSupervisor.make(TARGET_ENTRY, {
+        initiallyDesired: true,
+      }).pipe(Effect.provide(harness.dependencies));
+
+      yield* awaitState(
+        supervisor.state,
+        (state) => state.phase === "connected" && state.generation === 1,
+      );
+      yield* harness.wake("application-active-reconnect");
+      yield* awaitState(
+        supervisor.state,
+        (state) => state.phase === "connected" && state.generation === 2,
+      );
+
+      expect(yield* Ref.get(probeCount)).toBe(0);
+      expect(yield* Ref.get(harness.sessionCount)).toBe(2);
+      expect(yield* Ref.get(harness.releaseCount)).toBe(1);
+    }),
+  );
+
+  it.effect("replaces a mobile session when a long resume interrupts an active probe", () =>
+    Effect.gen(function* () {
+      const harness = yield* makeHarness({
+        probe: (attempt) => (attempt === 1 ? Effect.never : Effect.void),
+      });
+      const supervisor = yield* EnvironmentSupervisor.make(TARGET_ENTRY, {
+        initiallyDesired: true,
+      }).pipe(Effect.provide(harness.dependencies));
+
+      yield* awaitState(
+        supervisor.state,
+        (state) => state.phase === "connected" && state.generation === 1,
+      );
+      yield* harness.wake("application-active-probe");
+      yield* Effect.yieldNow;
+      yield* harness.wake("application-active-reconnect");
+      yield* awaitState(
+        supervisor.state,
+        (state) => state.phase === "connected" && state.generation === 2,
+      );
+
+      expect(yield* Ref.get(harness.sessionCount)).toBe(2);
+      expect(yield* Ref.get(harness.releaseCount)).toBe(1);
+    }),
+  );
+
   it.effect("reconnects when the foreground liveness probe fails", () =>
     Effect.gen(function* () {
       const harness = yield* makeHarness({
@@ -701,7 +912,7 @@ describe("EnvironmentSupervisor", () => {
     }).pipe(Effect.provide(TestClock.layer())),
   );
 
-  it.effect("times out a stalled foreground liveness probe and reconnects", () =>
+  it.effect("quickly times out a stalled mobile foreground liveness probe", () =>
     Effect.gen(function* () {
       const harness = yield* makeHarness({
         probe: (attempt) => (attempt === 1 ? Effect.never : Effect.void),
@@ -711,8 +922,8 @@ describe("EnvironmentSupervisor", () => {
       }).pipe(Effect.provide(harness.dependencies));
 
       yield* awaitState(supervisor.state, (state) => state.phase === "connected");
-      yield* harness.wake("application-active");
-      yield* TestClock.adjust("15 seconds");
+      yield* harness.wake("application-active-probe");
+      yield* TestClock.adjust("3 seconds");
       yield* awaitState(
         supervisor.state,
         (state) => state.phase === "backoff" && state.lastFailure?.reason === "timeout",
diff --git a/packages/client-runtime/src/connection/supervisor.ts b/packages/client-runtime/src/connection/supervisor.ts
index d9efcd4263a..e4ac359e5b1 100644
--- a/packages/client-runtime/src/connection/supervisor.ts
+++ b/packages/client-runtime/src/connection/supervisor.ts
@@ -32,6 +32,7 @@ import * as ConnectionWakeups from "./wakeups.ts";
 const RETRY_DELAYS_MS = [1_000, 2_000, 4_000, 8_000, 16_000] as const;
 const CONNECTION_ESTABLISHMENT_TIMEOUT = "15 seconds";
 const CONNECTION_PROBE_TIMEOUT = "15 seconds";
+const MOBILE_CONNECTION_PROBE_TIMEOUT = "3 seconds";
 const BACKOFF_RESET_AFTER_MS = 30_000;
 
 interface SupervisorIntent {
@@ -63,6 +64,7 @@ type AttemptOutcome =
       readonly _tag: "Interrupted";
       readonly established: boolean;
       readonly stable: boolean;
+      readonly resetRetry: boolean;
     }
   | {
       readonly _tag: "Failure";
@@ -82,7 +84,7 @@ type EstablishmentEvent =
         TracedAttemptFailure
       >;
     }
-  | { readonly _tag: "Interrupted" }
+  | { readonly _tag: "Interrupted"; readonly resetRetry: boolean }
   | { readonly _tag: "TimedOut" };
 
 function exitUnlessInterrupted<A, E, R>(
@@ -168,7 +170,7 @@ function failureFromExit<A>(
   stable: boolean,
 ): AttemptOutcome {
   if (Exit.isSuccess(exit) || Cause.hasInterruptsOnly(exit.cause)) {
-    return { _tag: "Interrupted", established, stable };
+    return { _tag: "Interrupted", established, stable, resetRetry: false };
   }
   const typedFailure = exit.cause.reasons.find(Cause.isFailReason);
   if (typedFailure) {
@@ -365,18 +367,21 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
       switch (next._tag) {
         case "DisconnectRequested":
         case "RetryRequested":
-          return;
+          return false;
         case "NetworkChanged":
           if (next.network === "offline") {
-            return;
+            return false;
           }
           break;
         case "ConnectRequested":
           break;
         case "Wakeup":
+          if (next.reason === "application-active-reconnect") {
+            return true;
+          }
           if (next.reason === "credentials-changed" && target._tag === "RelayConnectionTarget") {
             yield* logManagedRelayAccountChange;
-            return;
+            return false;
           }
           break;
       }
@@ -391,21 +396,30 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
       switch (next._tag) {
         case "DisconnectRequested":
         case "RetryRequested":
-          return;
+          return false;
         case "NetworkChanged":
           if (next.network === "offline") {
-            return;
+            return false;
           }
           break;
         case "Wakeup":
           if (next.reason === "credentials-changed" && target._tag === "RelayConnectionTarget") {
             yield* logManagedRelayAccountChange;
-            return;
+            return false;
+          }
+          if (next.reason === "application-active-reconnect") {
+            // Mobile operating systems commonly suspend sockets without
+            // delivering a close event. A long background resume deliberately
+            // replaces that lease and starts a fresh attempt without backoff.
+            return true;
           }
-          if (next.reason === "application-active") {
+          if (next.reason === "application-active" || next.reason === "application-active-probe") {
             const probe = yield* lease.session.probe.pipe(
               Effect.timeoutOrElse({
-                duration: CONNECTION_PROBE_TIMEOUT,
+                duration:
+                  next.reason === "application-active-probe"
+                    ? MOBILE_CONNECTION_PROBE_TIMEOUT
+                    : CONNECTION_PROBE_TIMEOUT,
                 orElse: () =>
                   Effect.fail(
                     new ConnectionTransientError({
@@ -433,15 +447,27 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
                 case "DisconnectRequested":
                 case "RetryRequested":
                   yield* Fiber.interrupt(probe);
-                  return;
+                  return false;
                 case "NetworkChanged":
                   if (probeEvent.signal.network === "offline") {
                     yield* Fiber.interrupt(probe);
-                    return;
+                    return false;
                   }
                   break;
-                case "ConnectRequested":
                 case "Wakeup":
+                  if (probeEvent.signal.reason === "application-active-reconnect") {
+                    yield* Fiber.interrupt(probe);
+                    return true;
+                  }
+                  if (
+                    probeEvent.signal.reason === "credentials-changed" &&
+                    target._tag === "RelayConnectionTarget"
+                  ) {
+                    yield* Fiber.interrupt(probe);
+                    return false;
+                  }
+                  break;
+                case "ConnectRequested":
                   break;
               }
             }
@@ -471,7 +497,14 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
           }),
         ),
       ),
-      waitForEstablishmentInterrupt().pipe(Effect.as<EstablishmentEvent>({ _tag: "Interrupted" })),
+      waitForEstablishmentInterrupt().pipe(
+        Effect.map(
+          (resetRetry): EstablishmentEvent => ({
+            _tag: "Interrupted",
+            resetRetry,
+          }),
+        ),
+      ),
       Effect.sleep(CONNECTION_ESTABLISHMENT_TIMEOUT).pipe(
         Effect.as<EstablishmentEvent>({ _tag: "TimedOut" }),
       ),
@@ -482,6 +515,7 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
         _tag: "Interrupted",
         established: false,
         stable: false,
+        resetRetry: establishment.resetRetry,
       } satisfies AttemptOutcome;
     }
     if (establishment._tag === "TimedOut") {
@@ -524,6 +558,7 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
         _tag: "Interrupted",
         established: false,
         stable: false,
+        resetRetry: false,
       } satisfies AttemptOutcome;
     }
 
@@ -560,42 +595,58 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
       ),
     ).pipe(exitUnlessInterrupted);
     const connectedForMs = (yield* Clock.currentTimeMillis) - connectedAt;
+    if (Exit.isSuccess(connectedExit)) {
+      return {
+        _tag: "Interrupted",
+        established: true,
+        stable: connectedForMs >= BACKOFF_RESET_AFTER_MS,
+        resetRetry: connectedExit.value,
+      } satisfies AttemptOutcome;
+    }
     return failureFromExit(target, connectedExit, true, connectedForMs >= BACKOFF_RESET_AFTER_MS);
   }, Effect.ensuring(clearLease));
 
   const waitForRetrySignal = Effect.fnUntraced(function* (delayMs: number) {
     return yield* Effect.raceFirst(
-      Effect.sleep(delayMs),
+      Effect.sleep(delayMs).pipe(Effect.as(false)),
       Effect.gen(function* () {
         for (;;) {
           const next = yield* Queue.take(signals);
           switch (next._tag) {
+            case "Wakeup":
+              return ConnectionWakeups.isApplicationActiveWakeup(next.reason);
             case "ConnectRequested":
             case "DisconnectRequested":
             case "RetryRequested":
             case "NetworkChanged":
-            case "Wakeup":
-              return;
+              return false;
           }
         }
       }),
     );
   });
 
-  const waitForSignal = Queue.take(signals);
+  const waitForSignal = Queue.take(signals).pipe(
+    Effect.map(
+      (next) => next._tag === "Wakeup" && ConnectionWakeups.isApplicationActiveWakeup(next.reason),
+    ),
+  );
 
   const run = Effect.fnUntraced(function* () {
     let failureCount = 0;
     let generation = 0;
     let latestFailure: ConnectionAttemptError | null = null;
     let pendingRetry = Option.none<PendingRetryTrace>();
+    const resetRetryLadder = () => {
+      failureCount = 0;
+      pendingRetry = Option.none();
+    };
 
     for (;;) {
       const currentIntent = yield* Ref.get(intent);
       if (!currentIntent.desired) {
-        failureCount = 0;
+        resetRetryLadder();
         latestFailure = null;
-        pendingRetry = Option.none();
         yield* clearLease;
         yield* setState(availableState(currentIntent, generation));
         yield* waitForSignal;
@@ -604,7 +655,10 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
       if (currentIntent.network === "offline") {
         yield* clearLease;
         yield* setState(offlineState(currentIntent, generation, failureCount + 1, latestFailure));
-        yield* waitForSignal;
+        const applicationActivated = yield* waitForSignal;
+        if (applicationActivated) {
+          resetRetryLadder();
+        }
         continue;
       }
 
@@ -616,12 +670,14 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
       if (outcome.established) {
         generation = nextGeneration;
         if (outcome.stable) {
-          failureCount = 0;
+          resetRetryLadder();
           latestFailure = null;
-          pendingRetry = Option.none();
         }
       }
       if (outcome._tag === "Interrupted") {
+        if (outcome.resetRetry) {
+          resetRetryLadder();
+        }
         continue;
       }
 
@@ -640,7 +696,10 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
           lastFailure: error,
           retryAt: null,
         });
-        yield* waitForSignal;
+        const applicationActivated = yield* waitForSignal;
+        if (applicationActivated) {
+          resetRetryLadder();
+        }
         continue;
       }
 
@@ -663,7 +722,10 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
         lastFailure: error,
         retryAt: (yield* Clock.currentTimeMillis) + delayMs,
       });
-      yield* waitForRetrySignal(delayMs);
+      const applicationActivated = yield* waitForRetrySignal(delayMs);
+      if (applicationActivated) {
+        resetRetryLadder();
+      }
     }
   });
 
diff --git a/packages/client-runtime/src/connection/wakeups.ts b/packages/client-runtime/src/connection/wakeups.ts
index 107c5983e02..8573a49c147 100644
--- a/packages/client-runtime/src/connection/wakeups.ts
+++ b/packages/client-runtime/src/connection/wakeups.ts
@@ -2,7 +2,23 @@ import * as Context from "effect/Context";
 import * as Layer from "effect/Layer";
 import type * as Stream from "effect/Stream";
 
-export type ConnectionWakeup = "application-active" | "credentials-changed";
+export type ConnectionWakeup =
+  | "application-active"
+  | "application-active-probe"
+  | "application-active-reconnect"
+  | "credentials-changed";
+
+export function isApplicationActiveWakeup(reason: ConnectionWakeup): boolean {
+  return (
+    reason === "application-active" ||
+    reason === "application-active-probe" ||
+    reason === "application-active-reconnect"
+  );
+}
+
+export function shouldResubscribeAfterWakeup(reason: ConnectionWakeup): boolean {
+  return reason === "application-active" || reason === "application-active-probe";
+}
 
 export class ConnectionWakeups extends Context.Service<
   ConnectionWakeups,
diff --git a/packages/client-runtime/src/state/shell-sync.test.ts b/packages/client-runtime/src/state/shell-sync.test.ts
index 62d2a2c28b9..e006fc3cd76 100644
--- a/packages/client-runtime/src/state/shell-sync.test.ts
+++ b/packages/client-runtime/src/state/shell-sync.test.ts
@@ -329,6 +329,21 @@ describe("environment shell synchronization", () => {
 
       expect(yield* Ref.get(loaderCalls)).toBe(2);
       expect(yield* Ref.get(subscriptionCount)).toBe(2);
+
+      yield* Queue.offer(wakeups, "application-active-probe");
+      for (let attempt = 0; attempt < 100; attempt += 1) {
+        if ((yield* Ref.get(subscriptionCount)) >= 3) break;
+        yield* Effect.yieldNow;
+      }
+      expect(yield* Ref.get(loaderCalls)).toBe(3);
+      expect(yield* Ref.get(subscriptionCount)).toBe(3);
+
+      yield* Queue.offer(wakeups, "application-active-reconnect");
+      for (let attempt = 0; attempt < 10; attempt += 1) {
+        yield* Effect.yieldNow;
+      }
+      expect(yield* Ref.get(loaderCalls)).toBe(3);
+      expect(yield* Ref.get(subscriptionCount)).toBe(3);
     }),
   );
 });
diff --git a/packages/client-runtime/src/state/shell.ts b/packages/client-runtime/src/state/shell.ts
index 6ccb11797f5..a266af5f5f4 100644
--- a/packages/client-runtime/src/state/shell.ts
+++ b/packages/client-runtime/src/state/shell.ts
@@ -172,7 +172,7 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
   const foregroundResubscriptions = Option.match(wakeups, {
     onNone: () => Stream.never,
     onSome: (service) =>
-      service.changes.pipe(Stream.filter((reason) => reason === "application-active")),
+      service.changes.pipe(Stream.filter(ConnectionWakeups.shouldResubscribeAfterWakeup)),
   });
 
   yield* setSynchronizing;
diff --git a/packages/client-runtime/src/state/threads-sync.test.ts b/packages/client-runtime/src/state/threads-sync.test.ts
index 43cdc1590bf..c2df434e8e7 100644
--- a/packages/client-runtime/src/state/threads-sync.test.ts
+++ b/packages/client-runtime/src/state/threads-sync.test.ts
@@ -696,6 +696,19 @@ describe("EnvironmentThreads", () => {
         (value) => value.status === "live" && Option.isSome(value.data),
       );
       expect(Option.getOrThrow(live.data).title).toBe("Latest title");
+
+      yield* Queue.offer(harness.wakeups, "application-active-probe");
+      for (let attempt = 0; attempt < 100; attempt += 1) {
+        if ((yield* Ref.get(harness.subscriptionCount)) >= 3) break;
+        yield* Effect.yieldNow;
+      }
+      expect(yield* Ref.get(harness.subscriptionCount)).toBe(3);
+
+      yield* Queue.offer(harness.wakeups, "application-active-reconnect");
+      for (let attempt = 0; attempt < 10; attempt += 1) {
+        yield* Effect.yieldNow;
+      }
+      expect(yield* Ref.get(harness.subscriptionCount)).toBe(3);
     }),
   );
 });
diff --git a/packages/client-runtime/src/state/threads.ts b/packages/client-runtime/src/state/threads.ts
index 196229cc8b1..06b5428ca58 100644
--- a/packages/client-runtime/src/state/threads.ts
+++ b/packages/client-runtime/src/state/threads.ts
@@ -236,7 +236,7 @@ export const makeEnvironmentThreadState = Effect.fn("EnvironmentThreadState.make
   const foregroundResubscriptions = Option.match(wakeups, {
     onNone: () => Stream.never,
     onSome: (service) =>
-      service.changes.pipe(Stream.filter((reason) => reason === "application-active")),
+      service.changes.pipe(Stream.filter(ConnectionWakeups.shouldResubscribeAfterWakeup)),
   });
 
   yield* setSynchronizing;

From cbe8052020aa0c02c63fbe090e7f1f25603622d1 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Thu, 30 Jul 2026 04:35:06 -0700
Subject: [PATCH 17/34] feat(web): pasting a huge screenshot now compresses it
 instead of erroring (#4967)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---
 apps/web/src/components/chat/ChatComposer.tsx | 118 ++++++++---
 ...ssion.test.ts => imageCompression.test.ts} |  57 +++++-
 ...mageCompression.ts => imageCompression.ts} | 189 +++++++++++++-----
 3 files changed, 282 insertions(+), 82 deletions(-)
 rename apps/web/src/lib/{stashImageCompression.test.ts => imageCompression.test.ts} (76%)
 rename apps/web/src/lib/{stashImageCompression.ts => imageCompression.ts} (63%)

diff --git a/apps/web/src/components/chat/ChatComposer.tsx b/apps/web/src/components/chat/ChatComposer.tsx
index b89521a932d..e92ecd497e3 100644
--- a/apps/web/src/components/chat/ChatComposer.tsx
+++ b/apps/web/src/components/chat/ChatComposer.tsx
@@ -64,7 +64,7 @@ import {
 } from "../../promptStashStore";
 import { ComposerStashBadge } from "./ComposerStashBadge";
 import { ComposerStashMenu } from "./ComposerStashMenu";
-import { compressImageForStash } from "../../lib/stashImageCompression";
+import { compressImageForStash, compressImageToByteLimit } from "../../lib/imageCompression";
 import { isCommandPaletteOpen } from "../../commandPaletteBus";
 import { getTerminalFocusOwner } from "../../lib/terminalFocus";
 import { resolveShortcutCommand } from "../../keybindings";
@@ -206,8 +206,6 @@ import { searchProviderSkills } from "../../providerSkillSearch";
 import { useMediaQuery } from "../../hooks/useMediaQuery";
 import type { ReviewCommentContext } from "../../reviewCommentContext";
 
-const IMAGE_SIZE_LIMIT_LABEL = `${Math.round(PROVIDER_SEND_TURN_MAX_IMAGE_BYTES / (1024 * 1024))}MB`;
-
 const runtimeModeConfig: Record<
   RuntimeMode,
   { label: string; description: string; icon: LucideIcon }
@@ -1006,6 +1004,13 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
    * thread) can still be stashed while an earlier encode is running.
    */
   const stashInFlightRef = useRef<Set<string>>(new Set());
+  /**
+   * Count of pasted images still being compressed, per thread. Reserved
+   * against the attachment limit so concurrent pastes can't overshoot it,
+   * and checked by `submitComposer` so a send can't race an image into the
+   * next draft.
+   */
+  const pendingImageCompressionsRef = useRef<Map<ThreadId, number>>(new Map());
 
   // ------------------------------------------------------------------
   // Derived: composer send state
@@ -1821,12 +1826,26 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
         event?.preventDefault();
         return;
       }
+      // A send while a pasted image is still compressing would strand that
+      // image: the turn snapshot wouldn't include it, and it would surface
+      // in the *next* draft instead. Only oversized images hit this — small
+      // files clear the pending counter within a microtask.
+      if (activeThreadId && (pendingImageCompressionsRef.current.get(activeThreadId) ?? 0) > 0) {
+        event?.preventDefault();
+        toastManager.add({
+          type: "info",
+          title: "Still compressing a pasted image.",
+          description: "Send again once its thumbnail appears.",
+        });
+        return;
+      }
       onSend(event);
       if (shouldBlurMobileComposerOnSubmit()) {
         blurMobileComposerAfterSend();
       }
     },
     [
+      activeThreadId,
       blurMobileComposerAfterSend,
       isSendDisabled,
       noProviderAvailable,
@@ -2273,7 +2292,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
   // ------------------------------------------------------------------
   // Callbacks: images
   // ------------------------------------------------------------------
-  const addComposerImages = (files: File[]) => {
+  const addComposerImages = async (files: File[]) => {
     if (!activeThreadId || files.length === 0) return;
     if (pendingUserInputs.length > 0) {
       toastManager.add({
@@ -2282,40 +2301,81 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
       });
       return;
     }
-    const nextImages: ComposerImageAttachment[] = [];
-    let nextImageCount = composerImagesRef.current.length;
+    // Captured before the awaits below: the user may switch threads while a
+    // large image is being compressed, and the attachments and errors belong
+    // to the thread the paste happened in.
+    const threadId = activeThreadId;
+
+    // Validation happens synchronously so concurrent pastes see each other:
+    // accepted files reserve their attachment slots (via the pending counter)
+    // before the first await, keeping the total under the limit.
+    const pendingCount = pendingImageCompressionsRef.current.get(threadId) ?? 0;
+    let reservedCount = composerImagesRef.current.length + pendingCount;
+    const acceptedFiles: File[] = [];
     let error: string | null = null;
     for (const file of files) {
       if (!file.type.startsWith("image/")) {
         error = `Unsupported file type for '${file.name}'. Please attach image files only.`;
         continue;
       }
-      if (file.size > PROVIDER_SEND_TURN_MAX_IMAGE_BYTES) {
-        error = `'${file.name}' exceeds the ${IMAGE_SIZE_LIMIT_LABEL} attachment limit.`;
-        continue;
-      }
-      if (nextImageCount >= PROVIDER_SEND_TURN_MAX_ATTACHMENTS) {
+      if (reservedCount >= PROVIDER_SEND_TURN_MAX_ATTACHMENTS) {
         error = `You can attach up to ${PROVIDER_SEND_TURN_MAX_ATTACHMENTS} images per message.`;
         break;
       }
-      const previewUrl = URL.createObjectURL(file);
-      nextImages.push({
-        type: "image",
-        id: randomUUID(),
-        name: file.name || "image",
-        mimeType: file.type,
-        sizeBytes: file.size,
-        previewUrl,
-        file,
-      });
-      nextImageCount += 1;
+      acceptedFiles.push(file);
+      reservedCount += 1;
     }
-    if (nextImages.length === 1 && nextImages[0]) {
-      addComposerImage(nextImages[0]);
-    } else if (nextImages.length > 1) {
-      addComposerImagesToDraft(nextImages);
+    setThreadError(threadId, error);
+    if (acceptedFiles.length === 0) return;
+
+    pendingImageCompressionsRef.current.set(threadId, pendingCount + acceptedFiles.length);
+    try {
+      const nextImages: ComposerImageAttachment[] = [];
+      let compressionError: string | null = null;
+      for (const file of acceptedFiles) {
+        // Images over the wire cap are downscaled to fit rather than
+        // refused; files already within it pass through byte-for-byte.
+        const compressed = await compressImageToByteLimit(file, PROVIDER_SEND_TURN_MAX_IMAGE_BYTES);
+        if (!compressed.ok) {
+          compressionError =
+            compressed.reason === "unreadable"
+              ? `'${file.name}' could not be read as an image.`
+              : `'${file.name}' is too large to attach, even after compression.`;
+          continue;
+        }
+        const attachmentFile = compressed.file;
+        const previewUrl = URL.createObjectURL(attachmentFile);
+        nextImages.push({
+          type: "image",
+          id: randomUUID(),
+          name: attachmentFile.name || "image",
+          mimeType: attachmentFile.type,
+          sizeBytes: attachmentFile.size,
+          previewUrl,
+          file: attachmentFile,
+        });
+      }
+      if (nextImages.length === 1 && nextImages[0]) {
+        addComposerImage(nextImages[0]);
+      } else if (nextImages.length > 1) {
+        addComposerImagesToDraft(nextImages);
+      }
+      // Only failures are reported here. Success must not pass `null`: by
+      // now other work (a failed send, an overlapping paste) may have set a
+      // thread error this call knows nothing about, and clearing it would
+      // swallow that message.
+      if (compressionError !== null) {
+        setThreadError(threadId, compressionError);
+      }
+    } finally {
+      const remaining =
+        (pendingImageCompressionsRef.current.get(threadId) ?? 0) - acceptedFiles.length;
+      if (remaining > 0) {
+        pendingImageCompressionsRef.current.set(threadId, remaining);
+      } else {
+        pendingImageCompressionsRef.current.delete(threadId);
+      }
     }
-    setThreadError(activeThreadId, error);
   };
 
   const removeComposerImage = (imageId: string) => {
@@ -2331,7 +2391,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
     const imageFiles = files.filter((file) => file.type.startsWith("image/"));
     if (imageFiles.length === 0) return;
     event.preventDefault();
-    addComposerImages(imageFiles);
+    void addComposerImages(imageFiles);
   };
 
   const onComposerDragEnter = (event: React.DragEvent<HTMLDivElement>) => {
@@ -2365,7 +2425,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
     dragDepthRef.current = 0;
     setIsDragOverComposer(false);
     const files = Array.from(event.dataTransfer.files);
-    addComposerImages(files);
+    void addComposerImages(files);
     focusComposer();
   };
 
diff --git a/apps/web/src/lib/stashImageCompression.test.ts b/apps/web/src/lib/imageCompression.test.ts
similarity index 76%
rename from apps/web/src/lib/stashImageCompression.test.ts
rename to apps/web/src/lib/imageCompression.test.ts
index aaffa284cbb..63712ca7e29 100644
--- a/apps/web/src/lib/stashImageCompression.test.ts
+++ b/apps/web/src/lib/imageCompression.test.ts
@@ -1,6 +1,11 @@
 import { afterEach, describe, expect, it, vi } from "vite-plus/test";
 
-import { compressImageForStash, MAX_STASH_IMAGE_DATA_URL_CHARS } from "./stashImageCompression";
+import {
+  compressImageForStash,
+  compressImageToByteLimit,
+  MAX_COMPRESSIBLE_SOURCE_BYTES,
+  MAX_STASH_IMAGE_DATA_URL_CHARS,
+} from "./imageCompression";
 
 /**
  * jsdom has no real canvas/codec, so the re-encode path is exercised with
@@ -159,6 +164,56 @@ describe("compressImageForStash", () => {
     });
   });
 
+  it("compressImageToByteLimit passes small files through byte-for-byte", async () => {
+    const bitmapSpy = vi.fn();
+    vi.stubGlobal("createImageBitmap", bitmapSpy);
+
+    const original = makeFile(1024);
+    const result = await compressImageToByteLimit(original, 10 * 1024 * 1024);
+
+    expect(result.ok).toBe(true);
+    expect(result.ok && result.recompressed).toBe(false);
+    // Pass-through must be the same File object, not a copy.
+    expect(result.ok && result.file).toBe(original);
+    expect(bitmapSpy).not.toHaveBeenCalled();
+  });
+
+  it("compressImageToByteLimit re-encodes an oversized file under the byte cap", async () => {
+    stubCanvasPipeline(() => 200_000);
+
+    const result = await compressImageToByteLimit(makeFile(2_000_000), 1_000_000);
+
+    expect(result.ok).toBe(true);
+    expect(result.ok && result.recompressed).toBe(true);
+    expect(result.ok && result.file.type).toBe("image/webp");
+    // The re-encoded name must match the new container format.
+    expect(result.ok && result.file.name).toBe("shot.webp");
+    expect(result.ok && result.file.size).toBeLessThanOrEqual(1_000_000);
+  });
+
+  it("compressImageToByteLimit refuses sources above the decode-safety ceiling", async () => {
+    const bitmapSpy = vi.fn();
+    vi.stubGlobal("createImageBitmap", bitmapSpy);
+
+    const result = await compressImageToByteLimit(
+      makeFile(MAX_COMPRESSIBLE_SOURCE_BYTES + 1),
+      10 * 1024 * 1024,
+    );
+
+    expect(result).toEqual({ ok: false, reason: "too-large" });
+    // The whole point of the ceiling is to never decode such a file.
+    expect(bitmapSpy).not.toHaveBeenCalled();
+  });
+
+  it("compressImageToByteLimit reports too-large when no encoding fits", async () => {
+    const { close } = stubCanvasPipeline(() => 3_000_000);
+
+    const result = await compressImageToByteLimit(makeFile(2_000_000), 1_000_000);
+
+    expect(result).toEqual({ ok: false, reason: "too-large" });
+    expect(close).toHaveBeenCalled();
+  });
+
   it("shrinks below the source size when the image is already under MAX_DIMENSION", async () => {
     // A small-but-heavy source (e.g. a dense PNG): only a real downscale can
     // get it under budget, since quality alone is stubbed to never suffice.
diff --git a/apps/web/src/lib/stashImageCompression.ts b/apps/web/src/lib/imageCompression.ts
similarity index 63%
rename from apps/web/src/lib/stashImageCompression.ts
rename to apps/web/src/lib/imageCompression.ts
index 7f133fb2926..1c57fdad1a5 100644
--- a/apps/web/src/lib/stashImageCompression.ts
+++ b/apps/web/src/lib/imageCompression.ts
@@ -1,13 +1,14 @@
 /**
- * Re-encoding for stashed image attachments.
+ * Downscale + re-encode for image attachments that are too big for where
+ * they're headed. Two consumers share the same pipeline:
  *
- * The composer accepts images up to `PROVIDER_SEND_TURN_MAX_IMAGE_BYTES`
- * (10MB), but the stash persists them as base64 in localStorage, where the
- * whole origin shares a ~5MB quota. Rather than refuse large screenshots,
- * downscale + re-encode them to JPEG so a stashed prompt keeps its images.
+ * - The prompt stash persists images as base64 in localStorage (~5MB origin
+ *   quota), so `compressImageForStash` targets a per-image character budget.
+ * - The composer accepts pasted/dropped images larger than the provider's
+ *   `PROVIDER_SEND_TURN_MAX_IMAGE_BYTES` wire cap and shrinks them to fit
+ *   via `compressImageToByteLimit` instead of rejecting the paste.
  *
- * Only the *stashed copy* is compressed; the live composer attachment is
- * untouched, so sending without stashing still uploads the original file.
+ * Images already within budget pass through untouched.
  */
 
 /**
@@ -17,6 +18,12 @@
 const MAX_DIMENSION = 2048;
 /** Base64 budget for a single stashed image (~975KB of binary). */
 export const MAX_STASH_IMAGE_DATA_URL_CHARS = 1_300_000;
+/**
+ * Ceiling on the *source* file handed to the re-encoder. File size is a
+ * proxy for pixel count, and decoding hundreds of megapixels into an
+ * ImageBitmap can OOM the tab — beyond this we refuse rather than risk it.
+ */
+export const MAX_COMPRESSIBLE_SOURCE_BYTES = 50 * 1024 * 1024;
 /**
  * Quality ladder tried in order until the encoded image fits the budget.
  * The floor stays high enough to avoid visible blocking on UI screenshots;
@@ -35,14 +42,18 @@ export interface CompressedStashImage {
 }
 
 /**
- * Why an image could not be stashed. Callers report these differently:
+ * Why an image could not be compressed. Callers report these differently:
  * "too large" is a budget outcome, "unreadable" is a decode failure.
  */
-export type StashImageFailureReason = "too-large" | "unreadable";
+export type ImageCompressionFailureReason = "too-large" | "unreadable";
 
 export type CompressStashImageResult =
   | { ok: true; image: CompressedStashImage }
-  | { ok: false; reason: StashImageFailureReason };
+  | { ok: false; reason: ImageCompressionFailureReason };
+
+export type CompressImageFileResult =
+  | { ok: true; file: File; recompressed: boolean }
+  | { ok: false; reason: ImageCompressionFailureReason };
 
 /** Chunked so a large image can't blow the argument limit of `fromCharCode`. */
 const BASE64_CHUNK_SIZE = 0x8000;
@@ -73,6 +84,28 @@ function dataUrlByteLength(dataUrl: string): number {
   return Math.max(0, Math.floor((payload.length * 3) / 4) - padding);
 }
 
+/** Base64 payload of a data URL decoded back into a `File`. */
+function dataUrlToFile(dataUrl: string, name: string, mimeType: string): File {
+  const payload = dataUrl.slice(dataUrl.indexOf(",") + 1);
+  const binary = atob(payload);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return new File([bytes], name, { type: mimeType });
+}
+
+/**
+ * Re-encoding changes the container, so a name like `shot.png` would lie
+ * about its contents. Swap the extension to match the encoded mime type.
+ */
+function fileNameForMimeType(name: string, mimeType: string): string {
+  const extension = mimeType === "image/webp" ? ".webp" : ".jpg";
+  const dotIndex = name.lastIndexOf(".");
+  const base = dotIndex > 0 ? name.slice(0, dotIndex) : name;
+  return `${base}${extension}`;
+}
+
 function canRecompress(): boolean {
   return (
     typeof createImageBitmap === "function" &&
@@ -124,10 +157,10 @@ async function encodeToDataUrl(
 }
 
 /**
- * Draws `bitmap` scaled to fit `maxDimension` and encodes it as JPEG,
- * stepping quality down until the data URL fits `budgetChars`. Returns the
- * smallest encoding produced, even if it still exceeds the budget, so the
- * caller can decide whether to keep or drop it.
+ * Draws `bitmap` scaled to fit `maxDimension` and encodes it, stepping
+ * quality down until the data URL fits `budgetChars`. Returns the smallest
+ * encoding produced, even if it still exceeds the budget, so the caller can
+ * decide whether to keep or drop it.
  */
 async function encodeWithinBudget(
   bitmap: ImageBitmap,
@@ -165,35 +198,15 @@ async function encodeWithinBudget(
   return smallest;
 }
 
+type ReencodeResult =
+  | { ok: true; dataUrl: string; mimeType: string }
+  | { ok: false; reason: ImageCompressionFailureReason };
+
 /**
- * Produces the payload to persist for a stashed image.
- *
- * Small images are stored verbatim (preserving PNG transparency and exact
- * pixels). Anything over budget is downscaled and JPEG-encoded; if it still
- * doesn't fit after the fallback passes, returns `null` so the caller can
- * record it as dropped.
+ * Shared re-encode loop: decodes `file`, then walks the quality ladder and
+ * fallback downscale passes until an encoding fits `budgetChars`.
  */
-export async function compressImageForStash(
-  file: File,
-  budgetChars: number = MAX_STASH_IMAGE_DATA_URL_CHARS,
-): Promise<CompressStashImageResult> {
-  let originalDataUrl: string;
-  try {
-    originalDataUrl = await blobToDataUrl(file);
-  } catch {
-    return { ok: false, reason: "unreadable" };
-  }
-  if (originalDataUrl.length <= budgetChars) {
-    return {
-      ok: true,
-      image: {
-        dataUrl: originalDataUrl,
-        mimeType: file.type,
-        sizeBytes: file.size,
-        recompressed: false,
-      },
-    };
-  }
+async function reencodeWithinBudget(file: File, budgetChars: number): Promise<ReencodeResult> {
   if (!canRecompress()) {
     return { ok: false, reason: "too-large" };
   }
@@ -225,22 +238,14 @@ export async function compressImageForStash(
         // precisely *because* the target is too big (OOM on a large bitmap).
         // Keep trying the smaller fallback scales rather than giving up: a
         // reduced pass may well succeed. The exception must never escape,
-        // though, since the caller finalizes the entry after this returns and
-        // a throw would strand it as permanently "still saving".
+        // though, since callers finalize state after this returns and a
+        // throw would strand it (e.g. a stash entry stuck "still saving").
         encodeFailed = true;
         continue;
       }
       encodeFailed = false;
       if (encoded && encoded.dataUrl.length <= budgetChars) {
-        return {
-          ok: true,
-          image: {
-            dataUrl: encoded.dataUrl,
-            mimeType: encoded.mimeType,
-            sizeBytes: dataUrlByteLength(encoded.dataUrl),
-            recompressed: true,
-          },
-        };
+        return { ok: true, dataUrl: encoded.dataUrl, mimeType: encoded.mimeType };
       }
     }
     return { ok: false, reason: encodeFailed ? "unreadable" : "too-large" };
@@ -248,3 +253,83 @@ export async function compressImageForStash(
     bitmap.close();
   }
 }
+
+/**
+ * Produces the payload to persist for a stashed image.
+ *
+ * Small images are stored verbatim (preserving PNG transparency and exact
+ * pixels). Anything over budget is downscaled and re-encoded; if it still
+ * doesn't fit after the fallback passes, reports a failure so the caller
+ * can record it as dropped.
+ */
+export async function compressImageForStash(
+  file: File,
+  budgetChars: number = MAX_STASH_IMAGE_DATA_URL_CHARS,
+): Promise<CompressStashImageResult> {
+  let originalDataUrl: string;
+  try {
+    originalDataUrl = await blobToDataUrl(file);
+  } catch {
+    return { ok: false, reason: "unreadable" };
+  }
+  if (originalDataUrl.length <= budgetChars) {
+    return {
+      ok: true,
+      image: {
+        dataUrl: originalDataUrl,
+        mimeType: file.type,
+        sizeBytes: file.size,
+        recompressed: false,
+      },
+    };
+  }
+  const reencoded = await reencodeWithinBudget(file, budgetChars);
+  if (!reencoded.ok) {
+    return reencoded;
+  }
+  return {
+    ok: true,
+    image: {
+      dataUrl: reencoded.dataUrl,
+      mimeType: reencoded.mimeType,
+      sizeBytes: dataUrlByteLength(reencoded.dataUrl),
+      recompressed: true,
+    },
+  };
+}
+
+/**
+ * Shrinks `file` until its binary size fits `maxBytes`, returning a new
+ * `File` (WebP or JPEG). Files already within the limit pass through
+ * untouched, preserving their exact bytes and format. Sources above
+ * `MAX_COMPRESSIBLE_SOURCE_BYTES` are refused outright — decoding them is
+ * the risk, so no amount of output budget makes them safe.
+ */
+export async function compressImageToByteLimit(
+  file: File,
+  maxBytes: number,
+): Promise<CompressImageFileResult> {
+  if (file.size <= maxBytes) {
+    return { ok: true, file, recompressed: false };
+  }
+  if (file.size > MAX_COMPRESSIBLE_SOURCE_BYTES) {
+    return { ok: false, reason: "too-large" };
+  }
+  // The re-encode loop budgets in data-URL characters. Base64 turns 3 bytes
+  // into 4 chars; flooring keeps the budget a hair conservative instead of
+  // admitting an encoding right at the byte cap.
+  const budgetChars = Math.floor(maxBytes / 3) * 4;
+  const reencoded = await reencodeWithinBudget(file, budgetChars);
+  if (!reencoded.ok) {
+    return reencoded;
+  }
+  return {
+    ok: true,
+    file: dataUrlToFile(
+      reencoded.dataUrl,
+      fileNameForMimeType(file.name || "image", reencoded.mimeType),
+      reencoded.mimeType,
+    ),
+    recompressed: true,
+  };
+}

From 5c9358acaa34f8619513bba1e6821f0fdec27f74 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Thu, 30 Jul 2026 04:39:38 -0700
Subject: [PATCH 18/34] feat(web): regenerate thread titles from sidebar
 (#4810)

---
 .../src/environment/ServerEnvironment.test.ts |   1 +
 .../src/environment/ServerEnvironment.ts      |   1 +
 .../Layers/OrchestrationEngine.test.ts        |  28 +
 .../Layers/ProjectionPipeline.ts              |  10 +
 .../Layers/ProjectionSnapshotQuery.test.ts    |   2 +
 .../Layers/ProjectionSnapshotQuery.ts         |  23 +
 .../Layers/ProviderCommandReactor.test.ts     | 608 +++++++++++++++++-
 .../Layers/ProviderCommandReactor.ts          | 245 ++++++-
 .../decider.titleRegeneration.test.ts         |  72 +++
 apps/server/src/orchestration/decider.ts      |  38 ++
 apps/server/src/orchestration/projector.ts    |   4 +
 .../persistence/Layers/ProjectionThreads.ts   |  10 +
 apps/server/src/persistence/Migrations.ts     |   2 +
 ..._ProjectionThreadTitleRegeneration.test.ts |  27 +
 .../035_ProjectionThreadTitleRegeneration.ts  |  23 +
 .../persistence/Services/ProjectionThreads.ts |   3 +
 .../textGeneration/ClaudeTextGeneration.ts    |   1 +
 .../src/textGeneration/CodexTextGeneration.ts |   1 +
 .../textGeneration/CursorTextGeneration.ts    |   1 +
 .../src/textGeneration/GrokTextGeneration.ts  |   1 +
 .../textGeneration/OpenCodeTextGeneration.ts  |   1 +
 .../src/textGeneration/TextGeneration.ts      |   6 +-
 .../TextGenerationPrompts.test.ts             |  42 ++
 .../textGeneration/TextGenerationPrompts.ts   |  48 +-
 apps/web/src/components/Sidebar.logic.test.ts |  37 ++
 apps/web/src/components/Sidebar.logic.ts      |  19 +
 apps/web/src/components/SidebarV2.tsx         |  99 ++-
 .../src/state/threadReducer.test.ts           |  13 +-
 .../client-runtime/src/state/threadReducer.ts |   4 +
 packages/contracts/src/environment.ts         |   3 +
 packages/contracts/src/orchestration.test.ts  |  55 ++
 packages/contracts/src/orchestration.ts       |  34 +-
 32 files changed, 1438 insertions(+), 24 deletions(-)
 create mode 100644 apps/server/src/orchestration/decider.titleRegeneration.test.ts
 create mode 100644 apps/server/src/persistence/Migrations/035_ProjectionThreadTitleRegeneration.test.ts
 create mode 100644 apps/server/src/persistence/Migrations/035_ProjectionThreadTitleRegeneration.ts

diff --git a/apps/server/src/environment/ServerEnvironment.test.ts b/apps/server/src/environment/ServerEnvironment.test.ts
index e9dbc4a5956..a7aea90f826 100644
--- a/apps/server/src/environment/ServerEnvironment.test.ts
+++ b/apps/server/src/environment/ServerEnvironment.test.ts
@@ -69,6 +69,7 @@ it.layer(NodeServices.layer)("ServerEnvironmentLive", (it) => {
       expect(first.environmentId).toBe(second.environmentId);
       expect(second.capabilities.repositoryIdentity).toBe(true);
       expect(second.capabilities.connectionProbe).toBe(true);
+      expect(second.capabilities.threadTitleRegeneration).toBe(true);
     }),
   );
 
diff --git a/apps/server/src/environment/ServerEnvironment.ts b/apps/server/src/environment/ServerEnvironment.ts
index 0eaf5a7c16a..250d4d7745a 100644
--- a/apps/server/src/environment/ServerEnvironment.ts
+++ b/apps/server/src/environment/ServerEnvironment.ts
@@ -142,6 +142,7 @@ export const make = Effect.gen(function* () {
       connectionProbe: true,
       threadSettlement: true,
       threadSnooze: true,
+      threadTitleRegeneration: true,
       ...(serverSelfUpdate === null ? {} : { serverSelfUpdate }),
     },
   };
diff --git a/apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts b/apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts
index 731002ea783..3c039d2260f 100644
--- a/apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts
+++ b/apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts
@@ -335,6 +335,14 @@ describe("OrchestrationEngine", () => {
       }),
     );
 
+    await system.run(
+      engine.dispatch({
+        type: "thread.meta.update",
+        commandId: CommandId.make("cmd-thread-archive-title-regeneration"),
+        threadId: ThreadId.make("thread-archive"),
+        regenerateTitle: true,
+      }),
+    );
     await system.run(
       engine.dispatch({
         type: "thread.archive",
@@ -346,6 +354,10 @@ describe("OrchestrationEngine", () => {
       (await system.readModel()).threads.find((thread) => thread.id === "thread-archive")
         ?.archivedAt,
     ).not.toBeNull();
+    expect(
+      (await system.readModel()).threads.find((thread) => thread.id === "thread-archive")
+        ?.titleRegeneration,
+    ).toBeNull();
 
     await system.run(
       engine.dispatch({
@@ -358,6 +370,22 @@ describe("OrchestrationEngine", () => {
       (await system.readModel()).threads.find((thread) => thread.id === "thread-archive")
         ?.archivedAt,
     ).toBeNull();
+    expect(
+      (await system.readModel()).threads.find((thread) => thread.id === "thread-archive")
+        ?.titleRegeneration,
+    ).toBeNull();
+    await system.run(
+      engine.dispatch({
+        type: "thread.title.regeneration.complete",
+        commandId: CommandId.make("cmd-thread-archive-stale-title-completion"),
+        threadId: ThreadId.make("thread-archive"),
+        requestId: CommandId.make("cmd-thread-archive-title-regeneration"),
+        title: "Stale generated title",
+      }),
+    );
+    expect(
+      (await system.readModel()).threads.find((thread) => thread.id === "thread-archive")?.title,
+    ).toBe("Archive me");
 
     await system.dispose();
   });
diff --git a/apps/server/src/orchestration/Layers/ProjectionPipeline.ts b/apps/server/src/orchestration/Layers/ProjectionPipeline.ts
index 1f24a4a0200..1a08f7aeeae 100644
--- a/apps/server/src/orchestration/Layers/ProjectionPipeline.ts
+++ b/apps/server/src/orchestration/Layers/ProjectionPipeline.ts
@@ -611,6 +611,8 @@ const makeOrchestrationProjectionPipeline = Effect.fn("makeOrchestrationProjecti
             settledAt: null,
             snoozedUntil: null,
             snoozedAt: null,
+            titleRegenerationRequestId: null,
+            titleRegenerationStartedAt: null,
             latestUserMessageAt: null,
             pendingApprovalCount: 0,
             pendingUserInputCount: 0,
@@ -629,6 +631,8 @@ const makeOrchestrationProjectionPipeline = Effect.fn("makeOrchestrationProjecti
           yield* projectionThreadRepository.upsert({
             ...existingRow.value,
             archivedAt: event.payload.archivedAt,
+            titleRegenerationRequestId: null,
+            titleRegenerationStartedAt: null,
             updatedAt: event.payload.updatedAt,
           });
           return;
@@ -723,6 +727,12 @@ const makeOrchestrationProjectionPipeline = Effect.fn("makeOrchestrationProjecti
           yield* projectionThreadRepository.upsert({
             ...existingRow.value,
             ...(event.payload.title !== undefined ? { title: event.payload.title } : {}),
+            ...(event.payload.titleRegeneration !== undefined
+              ? {
+                  titleRegenerationRequestId: event.payload.titleRegeneration?.requestId ?? null,
+                  titleRegenerationStartedAt: event.payload.titleRegeneration?.startedAt ?? null,
+                }
+              : {}),
             ...(event.payload.modelSelection !== undefined
               ? { modelSelection: event.payload.modelSelection }
               : {}),
diff --git a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts
index d4a24a209ad..12afffea7e7 100644
--- a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts
+++ b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts
@@ -312,6 +312,7 @@ projectionSnapshotLayer("ProjectionSnapshotQuery", (it) => {
           settledAt: null,
           snoozedUntil: null,
           snoozedAt: null,
+          titleRegeneration: null,
           deletedAt: null,
           messages: [
             {
@@ -426,6 +427,7 @@ projectionSnapshotLayer("ProjectionSnapshotQuery", (it) => {
           settledAt: null,
           snoozedUntil: null,
           snoozedAt: null,
+          titleRegeneration: null,
           session: {
             threadId: ThreadId.make("thread-1"),
             status: "running",
diff --git a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts
index 3d05bef4bdf..1cd4289fe0c 100644
--- a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts
+++ b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts
@@ -209,6 +209,15 @@ function mapLatestTurn(
   };
 }
 
+function mapTitleRegeneration(row: Schema.Schema.Type<typeof ProjectionThreadDbRowSchema>) {
+  return row.titleRegenerationRequestId != null && row.titleRegenerationStartedAt != null
+    ? {
+        requestId: row.titleRegenerationRequestId,
+        startedAt: row.titleRegenerationStartedAt,
+      }
+    : null;
+}
+
 function mapSessionRow(
   row: Schema.Schema.Type<typeof ProjectionThreadSessionDbRowSchema>,
 ): OrchestrationSession {
@@ -338,6 +347,8 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
           settled_at AS "settledAt",
           snoozed_until AS "snoozedUntil",
           snoozed_at AS "snoozedAt",
+          title_regeneration_request_id AS "titleRegenerationRequestId",
+          title_regeneration_started_at AS "titleRegenerationStartedAt",
           latest_user_message_at AS "latestUserMessageAt",
           pending_approval_count AS "pendingApprovalCount",
           pending_user_input_count AS "pendingUserInputCount",
@@ -370,6 +381,8 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
           settled_at AS "settledAt",
           snoozed_until AS "snoozedUntil",
           snoozed_at AS "snoozedAt",
+          title_regeneration_request_id AS "titleRegenerationRequestId",
+          title_regeneration_started_at AS "titleRegenerationStartedAt",
           latest_user_message_at AS "latestUserMessageAt",
           pending_approval_count AS "pendingApprovalCount",
           pending_user_input_count AS "pendingUserInputCount",
@@ -404,6 +417,8 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
           settled_at AS "settledAt",
           snoozed_until AS "snoozedUntil",
           snoozed_at AS "snoozedAt",
+          title_regeneration_request_id AS "titleRegenerationRequestId",
+          title_regeneration_started_at AS "titleRegenerationStartedAt",
           latest_user_message_at AS "latestUserMessageAt",
           pending_approval_count AS "pendingApprovalCount",
           pending_user_input_count AS "pendingUserInputCount",
@@ -770,6 +785,8 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
           settled_at AS "settledAt",
           snoozed_until AS "snoozedUntil",
           snoozed_at AS "snoozedAt",
+          title_regeneration_request_id AS "titleRegenerationRequestId",
+          title_regeneration_started_at AS "titleRegenerationStartedAt",
           latest_user_message_at AS "latestUserMessageAt",
           pending_approval_count AS "pendingApprovalCount",
           pending_user_input_count AS "pendingUserInputCount",
@@ -1206,6 +1223,7 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
                 settledAt: row.settledAt,
                 snoozedUntil: row.snoozedUntil,
                 snoozedAt: row.snoozedAt,
+                titleRegeneration: mapTitleRegeneration(row),
                 deletedAt: row.deletedAt,
                 messages: messagesByThread.get(row.threadId) ?? [],
                 proposedPlans: proposedPlansByThread.get(row.threadId) ?? [],
@@ -1408,6 +1426,7 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
                   settledAt: row.settledAt,
                   snoozedUntil: row.snoozedUntil,
                   snoozedAt: row.snoozedAt,
+                  titleRegeneration: mapTitleRegeneration(row),
                   deletedAt: row.deletedAt,
                   messages: [],
                   proposedPlans: proposedPlansByThread.get(row.threadId) ?? [],
@@ -1541,6 +1560,7 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
                       settledAt: row.settledAt,
                       snoozedUntil: row.snoozedUntil,
                       snoozedAt: row.snoozedAt,
+                      titleRegeneration: mapTitleRegeneration(row),
                       session: sessionByThread.get(row.threadId) ?? null,
                       latestUserMessageAt: row.latestUserMessageAt,
                       hasPendingApprovals: row.pendingApprovalCount > 0,
@@ -1679,6 +1699,7 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
                   settledAt: row.settledAt,
                   snoozedUntil: row.snoozedUntil,
                   snoozedAt: row.snoozedAt,
+                  titleRegeneration: mapTitleRegeneration(row),
                   session: sessionByThread.get(row.threadId) ?? null,
                   latestUserMessageAt: row.latestUserMessageAt,
                   hasPendingApprovals: row.pendingApprovalCount > 0,
@@ -1923,6 +1944,7 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
         settledAt: threadRow.value.settledAt,
         snoozedUntil: threadRow.value.snoozedUntil,
         snoozedAt: threadRow.value.snoozedAt,
+        titleRegeneration: mapTitleRegeneration(threadRow.value),
         session: Option.isSome(sessionRow) ? mapSessionRow(sessionRow.value) : null,
         latestUserMessageAt: threadRow.value.latestUserMessageAt,
         hasPendingApprovals: threadRow.value.pendingApprovalCount > 0,
@@ -2021,6 +2043,7 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
         settledAt: threadRow.value.settledAt,
         snoozedUntil: threadRow.value.snoozedUntil,
         snoozedAt: threadRow.value.snoozedAt,
+        titleRegeneration: mapTitleRegeneration(threadRow.value),
         deletedAt: null,
         messages: messageRows.map((row) => {
           const message = {
diff --git a/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts b/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts
index c49646b7a4b..e4661061b23 100644
--- a/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts
+++ b/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts
@@ -146,6 +146,8 @@ describe("ProviderCommandReactor", () => {
     readonly threadModelSelection?: ModelSelection;
     readonly sessionModelSwitch?: "unsupported" | "in-session";
     readonly requiresNewThreadForModelChange?: boolean;
+    readonly titleRegenerationCompletionDispatchFailures?: number;
+    readonly titleRegenerationBeforeStart?: "one" | "two";
     readonly startSessionEffect?: (
       session: ProviderSession,
     ) => Effect.Effect<ProviderSession, ProviderAdapterRequestError>;
@@ -353,8 +355,34 @@ describe("ProviderCommandReactor", () => {
       Layer.provide(RepositoryIdentityResolver.layer),
       Layer.provide(SqlitePersistenceMemory),
     );
+    let titleRegenerationCompletionDispatchAttempts = 0;
+    const reactorOrchestrationLayer = Layer.effect(
+      OrchestrationEngineService,
+      Effect.gen(function* () {
+        const engine = yield* OrchestrationEngineService;
+        return {
+          readEvents: engine.readEvents,
+          dispatch: (command) => {
+            if (command.type === "thread.title.regeneration.complete") {
+              titleRegenerationCompletionDispatchAttempts += 1;
+              if (
+                titleRegenerationCompletionDispatchAttempts <=
+                (input?.titleRegenerationCompletionDispatchFailures ?? 0)
+              ) {
+                return Effect.die(new Error("Injected title regeneration completion failure"));
+              }
+            }
+            return engine.dispatch(command);
+          },
+          get streamDomainEvents() {
+            return engine.streamDomainEvents;
+          },
+          latestSequence: engine.latestSequence,
+        } satisfies OrchestrationEngineService["Service"];
+      }),
+    ).pipe(Layer.provide(orchestrationLayer));
     const layer = ProviderCommandReactorLive.pipe(
-      Layer.provideMerge(orchestrationLayer),
+      Layer.provideMerge(reactorOrchestrationLayer),
       Layer.provideMerge(projectionSnapshotLayer),
       Layer.provideMerge(Layer.succeed(ProviderService, service)),
       Layer.provideMerge(makeProviderRegistryLayer(providerSnapshots as never)),
@@ -387,9 +415,7 @@ describe("ProviderCommandReactor", () => {
     const engine = await runtime.runPromise(Effect.service(OrchestrationEngineService));
     const snapshotQuery = await runtime.runPromise(Effect.service(ProjectionSnapshotQuery));
     const reactor = await runtime.runPromise(Effect.service(ProviderCommandReactor));
-    scope = await Effect.runPromise(Scope.make("sequential"));
-    await Effect.runPromise(reactor.start().pipe(Scope.provide(scope)));
-    const drain = () => Effect.runPromise(reactor.drain);
+    const runEffect = <A, E>(effect: Effect.Effect<A, E>) => runtime!.runPromise(effect);
 
     await Effect.runPromise(
       engine.dispatch({
@@ -417,6 +443,45 @@ describe("ProviderCommandReactor", () => {
         createdAt: now,
       }),
     );
+    if (input?.titleRegenerationBeforeStart === "two") {
+      await Effect.runPromise(
+        engine.dispatch({
+          type: "thread.create",
+          commandId: CommandId.make("cmd-thread-create-2"),
+          threadId: ThreadId.make("thread-2"),
+          projectId: asProjectId("project-1"),
+          title: "Thread 2",
+          modelSelection: modelSelection,
+          interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+          runtimeMode: "approval-required",
+          branch: null,
+          worktreePath: null,
+          createdAt: now,
+        }),
+      );
+    }
+    const titleRegenerationThreadIds =
+      input?.titleRegenerationBeforeStart === "two"
+        ? [ThreadId.make("thread-1"), ThreadId.make("thread-2")]
+        : input?.titleRegenerationBeforeStart === "one"
+          ? [ThreadId.make("thread-1")]
+          : [];
+    for (const [index, threadId] of titleRegenerationThreadIds.entries()) {
+      await Effect.runPromise(
+        engine.dispatch({
+          type: "thread.meta.update",
+          commandId: CommandId.make(
+            `cmd-thread-title-regeneration-before-reactor-start-${index + 1}`,
+          ),
+          threadId,
+          regenerateTitle: true,
+        }),
+      );
+    }
+
+    scope = await Effect.runPromise(Scope.make("sequential"));
+    await Effect.runPromise(reactor.start().pipe(Scope.provide(scope)));
+    const drain = () => Effect.runPromise(reactor.drain);
 
     return {
       engine,
@@ -434,6 +499,10 @@ describe("ProviderCommandReactor", () => {
       runtimeSessions,
       stateDir,
       drain,
+      runEffect,
+      get titleRegenerationCompletionDispatchAttempts() {
+        return titleRegenerationCompletionDispatchAttempts;
+      },
     };
   }
 
@@ -637,6 +706,533 @@ describe("ProviderCommandReactor", () => {
     expect(thread?.title).toBe("Generated title");
   });
 
+  it("regenerates a thread title from the current conversation", async () => {
+    const harness = await createHarness();
+    const now = "2026-01-01T00:00:00.000Z";
+    harness.generateThreadTitle.mockReturnValue(
+      Effect.succeed({ title: "Resolve stale reconnect state" }),
+    );
+
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.meta.update",
+        commandId: CommandId.make("cmd-thread-title-existing"),
+        threadId: ThreadId.make("thread-1"),
+        title: "Investigate reconnect regressions",
+      }),
+    );
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.turn.start",
+        commandId: CommandId.make("cmd-turn-start-before-title-regeneration"),
+        threadId: ThreadId.make("thread-1"),
+        message: {
+          messageId: asMessageId("user-message-before-title-regeneration"),
+          role: "user",
+          text: "Please investigate reconnect regressions after restarting the session.",
+          attachments: [],
+        },
+        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+        runtimeMode: "approval-required",
+        createdAt: now,
+      }),
+    );
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.message.assistant.delta",
+        commandId: CommandId.make("cmd-assistant-before-title-regeneration"),
+        threadId: ThreadId.make("thread-1"),
+        messageId: asMessageId("assistant-message-before-title-regeneration"),
+        delta: "The remaining issue is stale reconnect state.",
+        createdAt: "2026-01-01T00:00:01.000Z",
+      }),
+    );
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.message.assistant.complete",
+        commandId: CommandId.make("cmd-assistant-complete-before-title-regeneration"),
+        threadId: ThreadId.make("thread-1"),
+        messageId: asMessageId("assistant-message-before-title-regeneration"),
+        createdAt: "2026-01-01T00:00:02.000Z",
+      }),
+    );
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.meta.update",
+        commandId: CommandId.make("cmd-thread-title-regenerate"),
+        threadId: ThreadId.make("thread-1"),
+        regenerateTitle: true,
+      }),
+    );
+
+    await harness.drain();
+
+    expect(harness.generateThreadTitle).toHaveBeenCalledTimes(1);
+    expect(harness.generateThreadTitle.mock.calls[0]?.[0]).toMatchObject({
+      cwd: "/tmp/provider-project",
+      previousTitle: "Investigate reconnect regressions",
+      message: [
+        "USER:",
+        "Please investigate reconnect regressions after restarting the session.",
+        "",
+        "ASSISTANT:",
+        "The remaining issue is stale reconnect state.",
+      ].join("\n"),
+    });
+    const readModel = await harness.readModel();
+    const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
+    expect(thread?.title).toBe("Resolve stale reconnect state");
+    expect(thread?.titleRegeneration).toBeNull();
+  });
+
+  it("clears title regeneration state left pending across reactor startup", async () => {
+    const harness = await createHarness({
+      titleRegenerationBeforeStart: "one",
+    });
+
+    expect(harness.generateThreadTitle).not.toHaveBeenCalled();
+    expect(harness.titleRegenerationCompletionDispatchAttempts).toBe(1);
+    const readModel = await harness.readModel();
+    const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
+    expect(thread?.title).toBe("Thread");
+    expect(thread?.titleRegeneration).toBeNull();
+  });
+
+  it("continues clearing startup title regeneration state after one completion fails", async () => {
+    const harness = await createHarness({
+      titleRegenerationBeforeStart: "two",
+      titleRegenerationCompletionDispatchFailures: 1,
+    });
+
+    expect(harness.generateThreadTitle).not.toHaveBeenCalled();
+    expect(harness.titleRegenerationCompletionDispatchAttempts).toBe(2);
+    const readModel = await harness.readModel();
+    expect(
+      readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"))?.titleRegeneration,
+    ).not.toBeNull();
+    expect(
+      readModel.threads.find((entry) => entry.id === ThreadId.make("thread-2"))?.titleRegeneration,
+    ).toBeNull();
+  });
+
+  it("keeps the current title when regeneration returns the fallback", async () => {
+    const harness = await createHarness();
+    const now = "2026-01-01T00:00:00.000Z";
+    harness.generateThreadTitle.mockReturnValue(Effect.succeed({ title: "New thread" }));
+
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.meta.update",
+        commandId: CommandId.make("cmd-thread-title-before-fallback-regeneration"),
+        threadId: ThreadId.make("thread-1"),
+        title: "Keep meaningful title",
+      }),
+    );
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.turn.start",
+        commandId: CommandId.make("cmd-turn-start-before-fallback-regeneration"),
+        threadId: ThreadId.make("thread-1"),
+        message: {
+          messageId: asMessageId("user-message-before-fallback-regeneration"),
+          role: "user",
+          text: "Investigate the reconnect state.",
+          attachments: [],
+        },
+        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+        runtimeMode: "approval-required",
+        createdAt: now,
+      }),
+    );
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.meta.update",
+        commandId: CommandId.make("cmd-thread-title-fallback-regeneration"),
+        threadId: ThreadId.make("thread-1"),
+        regenerateTitle: true,
+      }),
+    );
+
+    await harness.drain();
+
+    const readModel = await harness.readModel();
+    const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
+    expect(thread?.title).toBe("Keep meaningful title");
+    expect(thread?.titleRegeneration).toBeNull();
+  });
+
+  it("clears title regeneration state when generation fails", async () => {
+    const harness = await createHarness();
+    const now = "2026-01-01T00:00:00.000Z";
+
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.meta.update",
+        commandId: CommandId.make("cmd-thread-title-before-failed-regeneration"),
+        threadId: ThreadId.make("thread-1"),
+        title: "Keep title after failure",
+      }),
+    );
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.turn.start",
+        commandId: CommandId.make("cmd-turn-start-before-failed-regeneration"),
+        threadId: ThreadId.make("thread-1"),
+        message: {
+          messageId: asMessageId("user-message-before-failed-regeneration"),
+          role: "user",
+          text: "Investigate the reconnect state.",
+          attachments: [],
+        },
+        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+        runtimeMode: "approval-required",
+        createdAt: now,
+      }),
+    );
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.meta.update",
+        commandId: CommandId.make("cmd-thread-title-failed-regeneration"),
+        threadId: ThreadId.make("thread-1"),
+        regenerateTitle: true,
+      }),
+    );
+
+    await harness.drain();
+
+    const readModel = await harness.readModel();
+    const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
+    expect(thread?.title).toBe("Keep title after failure");
+    expect(thread?.titleRegeneration).toBeNull();
+  });
+
+  it("retries a failed completion and continues regenerating", async () => {
+    const harness = await createHarness({
+      titleRegenerationCompletionDispatchFailures: 1,
+    });
+    const now = "2026-01-01T00:00:00.000Z";
+    harness.generateThreadTitle
+      .mockReturnValueOnce(Effect.succeed({ title: "Title lost to completion failure" }))
+      .mockReturnValueOnce(Effect.succeed({ title: "Recovered regeneration worker" }));
+
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.meta.update",
+        commandId: CommandId.make("cmd-thread-title-before-completion-failure"),
+        threadId: ThreadId.make("thread-1"),
+        title: "Existing title",
+      }),
+    );
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.turn.start",
+        commandId: CommandId.make("cmd-turn-start-before-completion-failure"),
+        threadId: ThreadId.make("thread-1"),
+        message: {
+          messageId: asMessageId("user-message-before-completion-failure"),
+          role: "user",
+          text: "Investigate the reconnect state.",
+          attachments: [],
+        },
+        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+        runtimeMode: "approval-required",
+        createdAt: now,
+      }),
+    );
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.meta.update",
+        commandId: CommandId.make("cmd-thread-title-regeneration-completion-failure"),
+        threadId: ThreadId.make("thread-1"),
+        regenerateTitle: true,
+      }),
+    );
+    await harness.drain();
+
+    let readModel = await harness.readModel();
+    let thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
+    expect(thread?.title).toBe("Title lost to completion failure");
+    expect(thread?.titleRegeneration).toBeNull();
+
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.meta.update",
+        commandId: CommandId.make("cmd-thread-title-regeneration-after-completion-failure"),
+        threadId: ThreadId.make("thread-1"),
+        regenerateTitle: true,
+      }),
+    );
+    await harness.drain();
+
+    expect(harness.generateThreadTitle).toHaveBeenCalledTimes(2);
+    expect(harness.titleRegenerationCompletionDispatchAttempts).toBe(3);
+    readModel = await harness.readModel();
+    thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
+    expect(thread?.title).toBe("Recovered regeneration worker");
+    expect(thread?.titleRegeneration).toBeNull();
+  });
+
+  it("keeps the full retained context and excludes attachments outside it", async () => {
+    const harness = await createHarness();
+    const now = "2026-01-01T00:00:00.000Z";
+    const retainedContext = "x".repeat(8_000);
+
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.meta.update",
+        commandId: CommandId.make("cmd-thread-title-before-truncated-regeneration"),
+        threadId: ThreadId.make("thread-1"),
+        title: "Existing title",
+      }),
+    );
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.turn.start",
+        commandId: CommandId.make("cmd-turn-start-before-truncated-regeneration"),
+        threadId: ThreadId.make("thread-1"),
+        message: {
+          messageId: asMessageId("user-message-before-truncated-regeneration"),
+          role: "user",
+          text: "Old visual issue",
+          attachments: [
+            {
+              type: "image",
+              id: "old-title-context-image",
+              name: "old-issue.png",
+              mimeType: "image/png",
+              sizeBytes: 5,
+            },
+          ],
+        },
+        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+        runtimeMode: "approval-required",
+        createdAt: now,
+      }),
+    );
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.message.assistant.delta",
+        commandId: CommandId.make("cmd-assistant-truncated-regeneration-context"),
+        threadId: ThreadId.make("thread-1"),
+        messageId: asMessageId("assistant-truncated-regeneration-context"),
+        delta: `content before retained tail${"x".repeat(8_100)}`,
+        createdAt: "2026-01-01T00:00:01.000Z",
+      }),
+    );
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.message.assistant.complete",
+        commandId: CommandId.make("cmd-assistant-truncated-regeneration-context-complete"),
+        threadId: ThreadId.make("thread-1"),
+        messageId: asMessageId("assistant-truncated-regeneration-context"),
+        createdAt: "2026-01-01T00:00:02.000Z",
+      }),
+    );
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.meta.update",
+        commandId: CommandId.make("cmd-thread-title-regenerate-truncated-context"),
+        threadId: ThreadId.make("thread-1"),
+        regenerateTitle: true,
+      }),
+    );
+
+    await harness.drain();
+
+    expect(harness.generateThreadTitle.mock.calls[0]?.[0].message).toBe(
+      `[Earlier content truncated]\n\n${retainedContext}`,
+    );
+    expect(harness.generateThreadTitle.mock.calls[0]?.[0].attachments).toBeUndefined();
+  });
+
+  it("does not overwrite a manual rename while title regeneration is running", async () => {
+    const harness = await createHarness();
+    const now = "2026-01-01T00:00:00.000Z";
+    const generatedTitle = await harness.runEffect(
+      Deferred.make<{ readonly title: string }, never>(),
+    );
+    harness.generateThreadTitle.mockReturnValue(Deferred.await(generatedTitle));
+
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.meta.update",
+        commandId: CommandId.make("cmd-thread-title-before-regeneration-race"),
+        threadId: ThreadId.make("thread-1"),
+        title: "Existing thread title",
+      }),
+    );
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.turn.start",
+        commandId: CommandId.make("cmd-turn-start-before-regeneration-race"),
+        threadId: ThreadId.make("thread-1"),
+        message: {
+          messageId: asMessageId("user-message-before-regeneration-race"),
+          role: "user",
+          text: "Investigate the reconnect state.",
+          attachments: [],
+        },
+        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+        runtimeMode: "approval-required",
+        createdAt: now,
+      }),
+    );
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.meta.update",
+        commandId: CommandId.make("cmd-thread-title-regeneration-race"),
+        threadId: ThreadId.make("thread-1"),
+        regenerateTitle: true,
+      }),
+    );
+    await waitFor(() => harness.generateThreadTitle.mock.calls.length === 1);
+    const pendingReadModel = await harness.readModel();
+    expect(
+      pendingReadModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"))
+        ?.titleRegeneration?.requestId,
+    ).toBe(CommandId.make("cmd-thread-title-regeneration-race"));
+
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.meta.update",
+        commandId: CommandId.make("cmd-thread-manual-rename-during-regeneration"),
+        threadId: ThreadId.make("thread-1"),
+        title: "Keep manual rename",
+      }),
+    );
+    await harness.runEffect(
+      Deferred.succeed(generatedTitle, { title: "Generated title should not win" }),
+    );
+    await harness.drain();
+
+    const readModel = await harness.readModel();
+    const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
+    expect(thread?.title).toBe("Keep manual rename");
+    expect(thread?.titleRegeneration).toBeNull();
+  });
+
+  it("does not overwrite a manual rename while title regeneration is queued", async () => {
+    let releaseStart = () => {};
+    const startGate = new Promise<void>((resolve) => {
+      releaseStart = resolve;
+    });
+    const harness = await createHarness({
+      startSessionEffect: (session) => Effect.promise(() => startGate).pipe(Effect.as(session)),
+    });
+    const now = "2026-01-01T00:00:00.000Z";
+    harness.generateThreadTitle.mockReturnValue(
+      Effect.succeed({ title: "Generated title should not win" }),
+    );
+
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.meta.update",
+        commandId: CommandId.make("cmd-thread-title-before-queued-regeneration"),
+        threadId: ThreadId.make("thread-1"),
+        title: "Existing thread title",
+      }),
+    );
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.turn.start",
+        commandId: CommandId.make("cmd-turn-start-before-queued-regeneration"),
+        threadId: ThreadId.make("thread-1"),
+        message: {
+          messageId: asMessageId("user-message-before-queued-regeneration"),
+          role: "user",
+          text: "Investigate the reconnect state.",
+          attachments: [],
+        },
+        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+        runtimeMode: "approval-required",
+        createdAt: now,
+      }),
+    );
+    await waitFor(() => harness.startSession.mock.calls.length === 1);
+
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.meta.update",
+        commandId: CommandId.make("cmd-thread-title-queued-regeneration"),
+        threadId: ThreadId.make("thread-1"),
+        regenerateTitle: true,
+      }),
+    );
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.meta.update",
+        commandId: CommandId.make("cmd-thread-manual-rename-before-regeneration-starts"),
+        threadId: ThreadId.make("thread-1"),
+        title: "Keep queued manual rename",
+      }),
+    );
+    releaseStart();
+    await harness.drain();
+
+    expect(harness.generateThreadTitle).not.toHaveBeenCalled();
+    const readModel = await harness.readModel();
+    const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
+    expect(thread?.title).toBe("Keep queued manual rename");
+  });
+
+  it("skips superseded title regeneration before generation starts", async () => {
+    let releaseStart = () => {};
+    const startGate = new Promise<void>((resolve) => {
+      releaseStart = resolve;
+    });
+    const harness = await createHarness({
+      startSessionEffect: (session) => Effect.promise(() => startGate).pipe(Effect.as(session)),
+    });
+    const now = "2026-01-01T00:00:00.000Z";
+    harness.generateThreadTitle.mockReturnValue(
+      Effect.succeed({ title: "Latest regenerated title" }),
+    );
+
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.turn.start",
+        commandId: CommandId.make("cmd-turn-start-before-superseded-regeneration"),
+        threadId: ThreadId.make("thread-1"),
+        message: {
+          messageId: asMessageId("user-message-before-superseded-regeneration"),
+          role: "user",
+          text: "Investigate the reconnect state.",
+          attachments: [],
+        },
+        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+        runtimeMode: "approval-required",
+        createdAt: now,
+      }),
+    );
+    await waitFor(() => harness.startSession.mock.calls.length === 1);
+
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.meta.update",
+        commandId: CommandId.make("cmd-thread-title-superseded-regeneration"),
+        threadId: ThreadId.make("thread-1"),
+        regenerateTitle: true,
+      }),
+    );
+    await harness.runEffect(
+      harness.engine.dispatch({
+        type: "thread.meta.update",
+        commandId: CommandId.make("cmd-thread-title-latest-regeneration"),
+        threadId: ThreadId.make("thread-1"),
+        regenerateTitle: true,
+      }),
+    );
+    releaseStart();
+    await harness.drain();
+
+    expect(harness.generateThreadTitle).toHaveBeenCalledTimes(1);
+    expect(harness.titleRegenerationCompletionDispatchAttempts).toBe(1);
+    const readModel = await harness.readModel();
+    const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
+    expect(thread?.title).toBe("Latest regenerated title");
+    expect(thread?.titleRegeneration).toBeNull();
+  });
+
   it("does not overwrite an existing custom thread title on the first turn", async () => {
     const harness = await createHarness();
     const now = "2026-01-01T00:00:00.000Z";
@@ -2178,7 +2774,7 @@ describe("ProviderCommandReactor", () => {
     const harness = await createHarness();
     const now = "2026-01-01T00:00:00.000Z";
 
-    await Effect.runPromise(
+    await harness.runEffect(
       harness.engine.dispatch({
         type: "thread.session.set",
         commandId: CommandId.make("cmd-session-set-for-stop"),
@@ -2197,7 +2793,7 @@ describe("ProviderCommandReactor", () => {
       }),
     );
 
-    await Effect.runPromise(
+    await harness.runEffect(
       harness.engine.dispatch({
         type: "thread.session.stop",
         commandId: CommandId.make("cmd-session-stop"),
diff --git a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts b/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
index 3044cc6029d..6ddc9f18cb3 100644
--- a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
+++ b/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
@@ -51,6 +51,7 @@ type ProviderIntentEvent = Extract<
   OrchestrationEvent,
   {
     type:
+      | "thread.meta-updated"
       | "thread.runtime-mode-set"
       | "thread.turn-start-requested"
       | "thread.turn-interrupt-requested"
@@ -90,6 +91,60 @@ const HANDLED_TURN_START_KEY_MAX = 10_000;
 const HANDLED_TURN_START_KEY_TTL = Duration.minutes(30);
 const DEFAULT_RUNTIME_MODE: RuntimeMode = "full-access";
 const DEFAULT_THREAD_TITLE = "New thread";
+const MAX_REGENERATION_ATTACHMENTS = 4;
+const MAX_THREAD_TITLE_CONTEXT_CHARS = 8_000;
+const THREAD_TITLE_CONTEXT_TRUNCATION_MARKER = "[Earlier content truncated]\n\n";
+
+function formatThreadTitleContext(
+  messages: ReadonlyArray<{
+    readonly role: "user" | "assistant" | "system";
+    readonly text: string;
+    readonly attachments?: ReadonlyArray<ChatAttachment> | undefined;
+  }>,
+): {
+  readonly message: string;
+  readonly attachments: ReadonlyArray<ChatAttachment>;
+} {
+  let context = "";
+  let truncated = false;
+  const retainedAttachments: Array<ChatAttachment> = [];
+
+  for (const message of messages.toReversed()) {
+    if (message.role === "system") {
+      continue;
+    }
+    const text = message.text.trim();
+    const attachmentSummary = (message.attachments ?? [])
+      .map((attachment) => attachment.name)
+      .join(", ");
+    const contents = [
+      ...(text.length > 0 ? [text] : []),
+      ...(attachmentSummary.length > 0 ? [`[Attachments: ${attachmentSummary}]`] : []),
+    ].join("\n");
+    if (contents.length === 0) {
+      continue;
+    }
+
+    const section = `${message.role.toUpperCase()}:\n${contents}`;
+    const separator = context.length > 0 ? "\n\n" : "";
+    const available = MAX_THREAD_TITLE_CONTEXT_CHARS - context.length - separator.length;
+    if (section.length > available) {
+      if (available > 0) {
+        context = `${section.slice(-available)}${separator}${context}`;
+        retainedAttachments.unshift(...(message.attachments ?? []));
+      }
+      truncated = true;
+      break;
+    }
+    context = `${section}${separator}${context}`;
+    retainedAttachments.unshift(...(message.attachments ?? []));
+  }
+
+  return {
+    message: truncated ? `${THREAD_TITLE_CONTEXT_TRUNCATION_MARKER}${context}` : context,
+    attachments: retainedAttachments.slice(-MAX_REGENERATION_ATTACHMENTS),
+  };
+}
 
 export function providerErrorLabel(value: string | undefined): string {
   const normalized = value?.trim();
@@ -777,6 +832,170 @@ const make = Effect.gen(function* () {
     },
   );
 
+  const regenerateThreadTitle = Effect.fn("regenerateThreadTitle")(function* (
+    event: Extract<ProviderIntentEvent, { type: "thread.meta-updated" }>,
+    requestId: CommandId,
+  ) {
+    if (event.payload.regenerateTitle !== true) {
+      return { _tag: "Superseded" } as const;
+    }
+
+    const thread = yield* resolveThread(event.payload.threadId);
+    if (!thread || thread.titleRegeneration?.requestId !== requestId) {
+      return { _tag: "Superseded" } as const;
+    }
+
+    const { message, attachments } = formatThreadTitleContext(thread.messages);
+    if (message.length === 0) {
+      return { _tag: "Completed", title: undefined } as const;
+    }
+
+    const previousTitle = event.payload.previousTitle ?? thread.title;
+    if (thread.title !== previousTitle) {
+      return { _tag: "Superseded" } as const;
+    }
+    const project = yield* resolveProject(thread.projectId);
+    const cwd =
+      resolveThreadWorkspaceCwd({
+        thread,
+        projects: project ? [project] : [],
+      }) ?? process.cwd();
+    const { textGenerationModelSelection: modelSelection } =
+      yield* serverSettingsService.getSettings;
+    const generated = yield* textGeneration.generateThreadTitle({
+      cwd,
+      message,
+      previousTitle,
+      ...(attachments.length > 0 ? { attachments } : {}),
+      modelSelection,
+    });
+    if (generated.title === DEFAULT_THREAD_TITLE || generated.title === previousTitle) {
+      return { _tag: "Completed", title: undefined } as const;
+    }
+
+    const latestThread = yield* resolveThread(event.payload.threadId);
+    if (
+      !latestThread ||
+      latestThread.titleRegeneration?.requestId !== requestId ||
+      latestThread.title !== previousTitle
+    ) {
+      return { _tag: "Superseded" } as const;
+    }
+
+    return { _tag: "Completed", title: generated.title } as const;
+  });
+  const dispatchThreadTitleRegenerationCompletion = Effect.fn(
+    "dispatchThreadTitleRegenerationCompletion",
+  )(function* (input: {
+    readonly threadId: ThreadId;
+    readonly requestId: CommandId;
+    readonly title?: string;
+  }) {
+    yield* orchestrationEngine.dispatch({
+      type: "thread.title.regeneration.complete",
+      commandId: yield* serverCommandId("thread-title-regeneration-complete"),
+      threadId: input.threadId,
+      requestId: input.requestId,
+      ...(input.title !== undefined ? { title: input.title } : {}),
+    });
+  });
+  const clearInterruptedThreadTitleRegenerations = Effect.fn(
+    "clearInterruptedThreadTitleRegenerations",
+  )(function* () {
+    const readModel = yield* projectionSnapshotQuery.getCommandReadModel();
+    yield* Effect.forEach(
+      readModel.threads,
+      (thread) => {
+        const requestId = thread.titleRegeneration?.requestId;
+        if (requestId === undefined) {
+          return Effect.void;
+        }
+        return dispatchThreadTitleRegenerationCompletion({
+          threadId: thread.id,
+          requestId,
+        }).pipe(
+          Effect.catchCause((cause) => {
+            if (Cause.hasInterruptsOnly(cause)) {
+              return Effect.interrupt;
+            }
+            return Effect.logWarning(
+              "provider command reactor failed to clear interrupted title regeneration",
+              {
+                threadId: thread.id,
+                cause: Cause.pretty(cause),
+              },
+            );
+          }),
+        );
+      },
+      { discard: true },
+    );
+  });
+  const processThreadTitleRegenerationSafely = Effect.fn("processThreadTitleRegenerationSafely")(
+    function* (event: Extract<ProviderIntentEvent, { type: "thread.meta-updated" }>) {
+      if (event.payload.regenerateTitle !== true) {
+        return;
+      }
+
+      const requestId = event.payload.titleRegeneration?.requestId ?? event.commandId;
+      if (requestId === null) {
+        return;
+      }
+      const result = yield* regenerateThreadTitle(event, requestId).pipe(
+        Effect.catchCause((cause) => {
+          if (Cause.hasInterruptsOnly(cause)) {
+            return Effect.failCause(cause);
+          }
+          return Effect.logWarning("provider command reactor failed to regenerate thread title", {
+            threadId: event.payload.threadId,
+            cause: Cause.pretty(cause),
+          }).pipe(Effect.as({ _tag: "Completed", title: undefined } as const));
+        }),
+      );
+      if (result._tag === "Superseded") {
+        return;
+      }
+
+      const completion = {
+        threadId: event.payload.threadId,
+        requestId,
+        ...(result.title !== undefined ? { title: result.title } : {}),
+      };
+      yield* dispatchThreadTitleRegenerationCompletion(completion).pipe(
+        Effect.catchCause((cause) => {
+          if (Cause.hasInterruptsOnly(cause)) {
+            return Effect.failCause(cause);
+          }
+          return Effect.logWarning(
+            "provider command reactor retrying title regeneration completion",
+            {
+              threadId: event.payload.threadId,
+              cause: Cause.pretty(cause),
+            },
+          ).pipe(Effect.andThen(dispatchThreadTitleRegenerationCompletion(completion)));
+        }),
+      );
+    },
+    (effect, event) =>
+      effect.pipe(
+        Effect.catchCause((cause) => {
+          if (Cause.hasInterruptsOnly(cause)) {
+            return Effect.failCause(cause);
+          }
+          return Effect.logWarning(
+            "provider command reactor failed to complete title regeneration",
+            {
+              threadId: event.payload.threadId,
+              cause: Cause.pretty(cause),
+            },
+          );
+        }),
+      ),
+  );
+  const threadTitleRegenerationWorker = yield* makeDrainableWorker(
+    processThreadTitleRegenerationSafely,
+  );
+
   const processTurnStartRequested = Effect.fn("processTurnStartRequested")(function* (
     event: Extract<ProviderIntentEvent, { type: "thread.turn-start-requested" }>,
   ) {
@@ -1047,6 +1266,9 @@ const make = Effect.gen(function* () {
       eventType: event.type,
     });
     switch (event.type) {
+      case "thread.meta-updated":
+        yield* threadTitleRegenerationWorker.enqueue(event);
+        return;
       case "thread.runtime-mode-set": {
         const thread = yield* resolveThread(event.payload.threadId);
         if (!thread?.session || thread.session.status === "stopped") {
@@ -1096,6 +1318,7 @@ const make = Effect.gen(function* () {
   const start: ProviderCommandReactorShape["start"] = Effect.fn("start")(function* () {
     const processEvent = Effect.fn("processEvent")(function* (event: OrchestrationEvent) {
       if (
+        (event.type === "thread.meta-updated" && event.payload.regenerateTitle === true) ||
         event.type === "thread.runtime-mode-set" ||
         event.type === "thread.turn-start-requested" ||
         event.type === "thread.turn-interrupt-requested" ||
@@ -1110,11 +1333,31 @@ const make = Effect.gen(function* () {
     yield* Effect.forkScoped(
       Stream.runForEach(orchestrationEngine.streamDomainEvents, processEvent),
     );
+
+    // The domain event stream is hot, so work pending before this reactor
+    // starts cannot be resumed. Correlated completions only clear the request
+    // captured here, leaving any newer request untouched.
+    yield* clearInterruptedThreadTitleRegenerations().pipe(
+      Effect.catchCause((cause) => {
+        if (Cause.hasInterruptsOnly(cause)) {
+          return Effect.interrupt;
+        }
+        return Effect.logWarning(
+          "provider command reactor failed to clear interrupted title regenerations",
+          {
+            cause: Cause.pretty(cause),
+          },
+        );
+      }),
+    );
   });
 
   return {
     start,
-    drain: worker.drain,
+    drain: Effect.gen(function* () {
+      yield* worker.drain;
+      yield* threadTitleRegenerationWorker.drain;
+    }),
   } satisfies ProviderCommandReactorShape;
 });
 
diff --git a/apps/server/src/orchestration/decider.titleRegeneration.test.ts b/apps/server/src/orchestration/decider.titleRegeneration.test.ts
new file mode 100644
index 00000000000..b29c8ffda67
--- /dev/null
+++ b/apps/server/src/orchestration/decider.titleRegeneration.test.ts
@@ -0,0 +1,72 @@
+import {
+  CommandId,
+  ProjectId,
+  ProviderInstanceId,
+  ThreadId,
+  type OrchestrationReadModel,
+} from "@t3tools/contracts";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+
+import { decideOrchestrationCommand } from "./decider.ts";
+
+const UPDATED_AT = "2026-01-01T00:00:00.000Z";
+
+const readModel: OrchestrationReadModel = {
+  snapshotSequence: 0,
+  projects: [],
+  threads: [
+    {
+      id: ThreadId.make("thread-1"),
+      projectId: ProjectId.make("project-1"),
+      title: "Manual title",
+      modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5.4" },
+      runtimeMode: "full-access",
+      interactionMode: "default",
+      branch: null,
+      worktreePath: null,
+      latestTurn: null,
+      createdAt: UPDATED_AT,
+      updatedAt: UPDATED_AT,
+      archivedAt: null,
+      settledOverride: null,
+      settledAt: null,
+      snoozedUntil: null,
+      snoozedAt: null,
+      deletedAt: null,
+      messages: [],
+      proposedPlans: [],
+      activities: [],
+      checkpoints: [],
+      session: null,
+    },
+  ],
+  updatedAt: UPDATED_AT,
+};
+
+it.layer(NodeServices.layer)("title regeneration decider", (it) => {
+  it.effect("preserves updatedAt for a stale completion", () =>
+    Effect.gen(function* () {
+      const result = yield* decideOrchestrationCommand({
+        command: {
+          type: "thread.title.regeneration.complete",
+          commandId: CommandId.make("cmd-regeneration-complete"),
+          threadId: ThreadId.make("thread-1"),
+          requestId: CommandId.make("cmd-old-regeneration-request"),
+          title: "Generated title",
+        },
+        readModel,
+      });
+      const event = Array.isArray(result) ? result[0] : result;
+
+      expect(event.type).toBe("thread.meta-updated");
+      if (event.type === "thread.meta-updated") {
+        expect(event.payload).toEqual({
+          threadId: ThreadId.make("thread-1"),
+          updatedAt: UPDATED_AT,
+        });
+      }
+    }),
+  );
+});
diff --git a/apps/server/src/orchestration/decider.ts b/apps/server/src/orchestration/decider.ts
index 100369ae6e3..ae9a068864c 100644
--- a/apps/server/src/orchestration/decider.ts
+++ b/apps/server/src/orchestration/decider.ts
@@ -654,6 +654,19 @@ export const decideOrchestrationCommand = Effect.fn("decideOrchestrationCommand"
         payload: {
           threadId: command.threadId,
           ...(command.title !== undefined ? { title: command.title } : {}),
+          ...(command.regenerateTitle === true
+            ? {
+                regenerateTitle: true as const,
+                previousTitle: thread.title,
+                titleRegeneration: {
+                  requestId: command.commandId,
+                  startedAt: occurredAt,
+                },
+              }
+            : {}),
+          ...(command.title !== undefined && thread.titleRegeneration != null
+            ? { titleRegeneration: null }
+            : {}),
           ...(command.modelSelection !== undefined
             ? { modelSelection: command.modelSelection }
             : {}),
@@ -664,6 +677,31 @@ export const decideOrchestrationCommand = Effect.fn("decideOrchestrationCommand"
       };
     }
 
+    case "thread.title.regeneration.complete": {
+      const thread = yield* requireThread({
+        readModel,
+        command,
+        threadId: command.threadId,
+      });
+      const requestIsCurrent = thread.titleRegeneration?.requestId === command.requestId;
+      const occurredAt = yield* nowIso;
+      return {
+        ...(yield* withEventBase({
+          aggregateKind: "thread",
+          aggregateId: command.threadId,
+          occurredAt,
+          commandId: command.commandId,
+        })),
+        type: "thread.meta-updated",
+        payload: {
+          threadId: command.threadId,
+          ...(requestIsCurrent && command.title !== undefined ? { title: command.title } : {}),
+          ...(requestIsCurrent ? { titleRegeneration: null } : {}),
+          updatedAt: requestIsCurrent ? occurredAt : thread.updatedAt,
+        },
+      };
+    }
+
     case "thread.runtime-mode.set": {
       yield* requireThread({
         readModel,
diff --git a/apps/server/src/orchestration/projector.ts b/apps/server/src/orchestration/projector.ts
index 0504cb36f9a..4be5843c1ae 100644
--- a/apps/server/src/orchestration/projector.ts
+++ b/apps/server/src/orchestration/projector.ts
@@ -329,6 +329,7 @@ export function projectEvent(
           ...nextBase,
           threads: updateThread(nextBase.threads, payload.threadId, {
             archivedAt: payload.archivedAt,
+            titleRegeneration: null,
             updatedAt: payload.updatedAt,
           }),
         })),
@@ -399,6 +400,9 @@ export function projectEvent(
           ...nextBase,
           threads: updateThread(nextBase.threads, payload.threadId, {
             ...(payload.title !== undefined ? { title: payload.title } : {}),
+            ...(payload.titleRegeneration !== undefined
+              ? { titleRegeneration: payload.titleRegeneration }
+              : {}),
             ...(payload.modelSelection !== undefined
               ? { modelSelection: payload.modelSelection }
               : {}),
diff --git a/apps/server/src/persistence/Layers/ProjectionThreads.ts b/apps/server/src/persistence/Layers/ProjectionThreads.ts
index 7e86d49eac3..eb423aef99e 100644
--- a/apps/server/src/persistence/Layers/ProjectionThreads.ts
+++ b/apps/server/src/persistence/Layers/ProjectionThreads.ts
@@ -47,6 +47,8 @@ const makeProjectionThreadRepository = Effect.gen(function* () {
           settled_at,
           snoozed_until,
           snoozed_at,
+          title_regeneration_request_id,
+          title_regeneration_started_at,
           latest_user_message_at,
           pending_approval_count,
           pending_user_input_count,
@@ -70,6 +72,8 @@ const makeProjectionThreadRepository = Effect.gen(function* () {
           ${row.settledAt},
           ${row.snoozedUntil},
           ${row.snoozedAt},
+          ${row.titleRegenerationRequestId ?? null},
+          ${row.titleRegenerationStartedAt ?? null},
           ${row.latestUserMessageAt},
           ${row.pendingApprovalCount},
           ${row.pendingUserInputCount},
@@ -93,6 +97,8 @@ const makeProjectionThreadRepository = Effect.gen(function* () {
           settled_at = excluded.settled_at,
           snoozed_until = excluded.snoozed_until,
           snoozed_at = excluded.snoozed_at,
+          title_regeneration_request_id = excluded.title_regeneration_request_id,
+          title_regeneration_started_at = excluded.title_regeneration_started_at,
           latest_user_message_at = excluded.latest_user_message_at,
           pending_approval_count = excluded.pending_approval_count,
           pending_user_input_count = excluded.pending_user_input_count,
@@ -123,6 +129,8 @@ const makeProjectionThreadRepository = Effect.gen(function* () {
           settled_at AS "settledAt",
           snoozed_until AS "snoozedUntil",
           snoozed_at AS "snoozedAt",
+          title_regeneration_request_id AS "titleRegenerationRequestId",
+          title_regeneration_started_at AS "titleRegenerationStartedAt",
           latest_user_message_at AS "latestUserMessageAt",
           pending_approval_count AS "pendingApprovalCount",
           pending_user_input_count AS "pendingUserInputCount",
@@ -155,6 +163,8 @@ const makeProjectionThreadRepository = Effect.gen(function* () {
           settled_at AS "settledAt",
           snoozed_until AS "snoozedUntil",
           snoozed_at AS "snoozedAt",
+          title_regeneration_request_id AS "titleRegenerationRequestId",
+          title_regeneration_started_at AS "titleRegenerationStartedAt",
           latest_user_message_at AS "latestUserMessageAt",
           pending_approval_count AS "pendingApprovalCount",
           pending_user_input_count AS "pendingUserInputCount",
diff --git a/apps/server/src/persistence/Migrations.ts b/apps/server/src/persistence/Migrations.ts
index d25895671a9..95cb6b17f84 100644
--- a/apps/server/src/persistence/Migrations.ts
+++ b/apps/server/src/persistence/Migrations.ts
@@ -47,6 +47,7 @@ import Migration0031 from "./Migrations/031_AuthAuthorizationScopes.ts";
 import Migration0032 from "./Migrations/032_AuthPairingProofKeyThumbprint.ts";
 import Migration0033 from "./Migrations/033_ProjectionThreadsSettled.ts";
 import Migration0034 from "./Migrations/034_ProjectionThreadsSnoozed.ts";
+import Migration0035 from "./Migrations/035_ProjectionThreadTitleRegeneration.ts";
 
 /**
  * Migration loader with all migrations defined inline.
@@ -93,6 +94,7 @@ export const migrationEntries = [
   [32, "AuthPairingProofKeyThumbprint", Migration0032],
   [33, "ProjectionThreadsSettled", Migration0033],
   [34, "ProjectionThreadsSnoozed", Migration0034],
+  [35, "ProjectionThreadTitleRegeneration", Migration0035],
 ] as const;
 
 export const makeMigrationLoader = (throughId?: number) =>
diff --git a/apps/server/src/persistence/Migrations/035_ProjectionThreadTitleRegeneration.test.ts b/apps/server/src/persistence/Migrations/035_ProjectionThreadTitleRegeneration.test.ts
new file mode 100644
index 00000000000..755591201de
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/035_ProjectionThreadTitleRegeneration.test.ts
@@ -0,0 +1,27 @@
+import { assert, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+
+import { runMigrations } from "../Migrations.ts";
+import * as NodeSqliteClient from "../NodeSqliteClient.ts";
+
+const layer = it.layer(Layer.mergeAll(NodeSqliteClient.layerMemory()));
+
+layer("035_ProjectionThreadTitleRegeneration", (it) => {
+  it.effect("adds pending title regeneration columns", () =>
+    Effect.gen(function* () {
+      const sql = yield* SqlClient.SqlClient;
+
+      yield* runMigrations({ toMigrationInclusive: 34 });
+      yield* runMigrations({ toMigrationInclusive: 35 });
+
+      const columns = yield* sql<{ readonly name: string }>`
+        PRAGMA table_info(projection_threads)
+      `;
+      const names = new Set(columns.map((column) => column.name));
+      assert.ok(names.has("title_regeneration_request_id"));
+      assert.ok(names.has("title_regeneration_started_at"));
+    }),
+  );
+});
diff --git a/apps/server/src/persistence/Migrations/035_ProjectionThreadTitleRegeneration.ts b/apps/server/src/persistence/Migrations/035_ProjectionThreadTitleRegeneration.ts
new file mode 100644
index 00000000000..ee3dd4a0774
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/035_ProjectionThreadTitleRegeneration.ts
@@ -0,0 +1,23 @@
+import * as Effect from "effect/Effect";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+
+export default Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+  const columns = yield* sql<{ readonly name: string }>`
+    PRAGMA table_info(projection_threads)
+  `;
+
+  if (!columns.some((column) => column.name === "title_regeneration_request_id")) {
+    yield* sql`
+      ALTER TABLE projection_threads
+      ADD COLUMN title_regeneration_request_id TEXT
+    `;
+  }
+
+  if (!columns.some((column) => column.name === "title_regeneration_started_at")) {
+    yield* sql`
+      ALTER TABLE projection_threads
+      ADD COLUMN title_regeneration_started_at TEXT
+    `;
+  }
+});
diff --git a/apps/server/src/persistence/Services/ProjectionThreads.ts b/apps/server/src/persistence/Services/ProjectionThreads.ts
index 056425ae886..ea1b011be84 100644
--- a/apps/server/src/persistence/Services/ProjectionThreads.ts
+++ b/apps/server/src/persistence/Services/ProjectionThreads.ts
@@ -7,6 +7,7 @@
  * @module ProjectionThreadRepository
  */
 import {
+  CommandId,
   IsoDateTime,
   ModelSelection,
   NonNegativeInt,
@@ -40,6 +41,8 @@ export const ProjectionThread = Schema.Struct({
   settledAt: Schema.NullOr(IsoDateTime),
   snoozedUntil: Schema.NullOr(IsoDateTime),
   snoozedAt: Schema.NullOr(IsoDateTime),
+  titleRegenerationRequestId: Schema.optional(Schema.NullOr(CommandId)),
+  titleRegenerationStartedAt: Schema.optional(Schema.NullOr(IsoDateTime)),
   latestUserMessageAt: Schema.NullOr(IsoDateTime),
   pendingApprovalCount: NonNegativeInt,
   pendingUserInputCount: NonNegativeInt,
diff --git a/apps/server/src/textGeneration/ClaudeTextGeneration.ts b/apps/server/src/textGeneration/ClaudeTextGeneration.ts
index a27b2c8bd3e..37304795a22 100644
--- a/apps/server/src/textGeneration/ClaudeTextGeneration.ts
+++ b/apps/server/src/textGeneration/ClaudeTextGeneration.ts
@@ -342,6 +342,7 @@ export const makeClaudeTextGeneration = Effect.fn("makeClaudeTextGeneration")(fu
     Effect.fn("ClaudeTextGeneration.generateThreadTitle")(function* (input) {
       const { prompt, outputSchema } = buildThreadTitlePrompt({
         message: input.message,
+        previousTitle: input.previousTitle,
         attachments: input.attachments,
       });
 
diff --git a/apps/server/src/textGeneration/CodexTextGeneration.ts b/apps/server/src/textGeneration/CodexTextGeneration.ts
index 6ea710cd5a3..62d917012ae 100644
--- a/apps/server/src/textGeneration/CodexTextGeneration.ts
+++ b/apps/server/src/textGeneration/CodexTextGeneration.ts
@@ -384,6 +384,7 @@ export const makeCodexTextGeneration = Effect.fn("makeCodexTextGeneration")(func
       );
       const { prompt, outputSchema } = buildThreadTitlePrompt({
         message: input.message,
+        previousTitle: input.previousTitle,
         attachments: input.attachments,
       });
 
diff --git a/apps/server/src/textGeneration/CursorTextGeneration.ts b/apps/server/src/textGeneration/CursorTextGeneration.ts
index be0fc858ac5..5ae057b54f6 100644
--- a/apps/server/src/textGeneration/CursorTextGeneration.ts
+++ b/apps/server/src/textGeneration/CursorTextGeneration.ts
@@ -242,6 +242,7 @@ export const makeCursorTextGeneration = Effect.fn("makeCursorTextGeneration")(fu
     Effect.fn("CursorTextGeneration.generateThreadTitle")(function* (input) {
       const { prompt, outputSchema } = buildThreadTitlePrompt({
         message: input.message,
+        previousTitle: input.previousTitle,
         attachments: input.attachments,
       });
 
diff --git a/apps/server/src/textGeneration/GrokTextGeneration.ts b/apps/server/src/textGeneration/GrokTextGeneration.ts
index d26a2ebe01b..1cf3d13e225 100644
--- a/apps/server/src/textGeneration/GrokTextGeneration.ts
+++ b/apps/server/src/textGeneration/GrokTextGeneration.ts
@@ -234,6 +234,7 @@ export const makeGrokTextGeneration = Effect.fn("makeGrokTextGeneration")(functi
     Effect.fn("GrokTextGeneration.generateThreadTitle")(function* (input) {
       const { prompt, outputSchema } = buildThreadTitlePrompt({
         message: input.message,
+        previousTitle: input.previousTitle,
         attachments: input.attachments,
       });
 
diff --git a/apps/server/src/textGeneration/OpenCodeTextGeneration.ts b/apps/server/src/textGeneration/OpenCodeTextGeneration.ts
index 2adbb829b8d..e09c3db2cff 100644
--- a/apps/server/src/textGeneration/OpenCodeTextGeneration.ts
+++ b/apps/server/src/textGeneration/OpenCodeTextGeneration.ts
@@ -598,6 +598,7 @@ export const makeOpenCodeTextGeneration = Effect.fn("makeOpenCodeTextGeneration"
     Effect.fn("OpenCodeTextGeneration.generateThreadTitle")(function* (input) {
       const { prompt, outputSchema } = buildThreadTitlePrompt({
         message: input.message,
+        previousTitle: input.previousTitle,
         attachments: input.attachments,
       });
       const generated = yield* runOpenCodeJson({
diff --git a/apps/server/src/textGeneration/TextGeneration.ts b/apps/server/src/textGeneration/TextGeneration.ts
index ead09638776..66b7ccd465f 100644
--- a/apps/server/src/textGeneration/TextGeneration.ts
+++ b/apps/server/src/textGeneration/TextGeneration.ts
@@ -62,6 +62,8 @@ export interface BranchNameGenerationResult {
 export interface ThreadTitleGenerationInput {
   cwd: string;
   message: string;
+  /** Present when replacing an existing title from the current thread history. */
+  previousTitle?: string | undefined;
   attachments?: ReadonlyArray<ChatAttachment> | undefined;
   /** What model and provider to use for generation. */
   modelSelection: ModelSelection;
@@ -107,9 +109,7 @@ export class TextGeneration extends Context.Service<
       input: BranchNameGenerationInput,
     ) => Effect.Effect<BranchNameGenerationResult, TextGenerationError>;
 
-    /**
-     * Generate a concise thread title from a user's first message.
-     */
+    /** Generate a concise thread title from a first message or thread history. */
     readonly generateThreadTitle: (
       input: ThreadTitleGenerationInput,
     ) => Effect.Effect<ThreadTitleGenerationResult, TextGenerationError>;
diff --git a/apps/server/src/textGeneration/TextGenerationPrompts.test.ts b/apps/server/src/textGeneration/TextGenerationPrompts.test.ts
index 65b61b99bfc..ede18664051 100644
--- a/apps/server/src/textGeneration/TextGenerationPrompts.test.ts
+++ b/apps/server/src/textGeneration/TextGenerationPrompts.test.ts
@@ -175,6 +175,48 @@ describe("buildThreadTitlePrompt", () => {
     expect(result.prompt).toContain("image/png");
     expect(result.prompt).toContain("67890 bytes");
   });
+
+  it("regenerates from recent thread contents and identifies the previous title", () => {
+    const result = buildThreadTitlePrompt({
+      message: `USER:\nInvestigate reconnect regressions\n\nASSISTANT:\nThe remaining issue is stale session state`,
+      previousTitle: "Investigate reconnect regressions",
+    });
+
+    expect(result.prompt).toContain(
+      "The user requested a new title based on the contents of this thread.",
+    );
+    expect(result.prompt).toContain('The previous title was "Investigate reconnect regressions".');
+    expect(result.prompt).toContain("better represents the current state of the thread");
+    expect(result.prompt).toContain(
+      "Capture the thread's intent, not a PR number or other superficial detail.",
+    );
+    expect(result.prompt).toContain("Thread contents:");
+    expect(result.prompt).toContain("The remaining issue is stale session state");
+  });
+
+  it("keeps the latest thread contents when regeneration context is truncated", () => {
+    const result = buildThreadTitlePrompt({
+      message: `${"old context ".repeat(1_000)}\n\nASSISTANT:\nCurrent thread state`,
+      previousTitle: "Old title",
+    });
+
+    expect(result.prompt).toContain("[Earlier content truncated]");
+    expect(result.prompt).toContain("Current thread state");
+    expect(result.prompt).not.toContain("[truncated]");
+  });
+
+  it("does not truncate an already-marked regeneration context twice", () => {
+    const retainedContext = "x".repeat(7_998);
+    const result = buildThreadTitlePrompt({
+      message: `[Earlier content truncated]\n\n${retainedContext}`,
+      previousTitle: "Old title",
+    });
+
+    expect(result.prompt).toContain(
+      `Thread contents:\n[Earlier content truncated]\n\n${retainedContext}`,
+    );
+    expect(result.prompt.match(/\[Earlier content truncated\]/g)).toHaveLength(1);
+  });
 });
 
 describe("sanitizeThreadTitle", () => {
diff --git a/apps/server/src/textGeneration/TextGenerationPrompts.ts b/apps/server/src/textGeneration/TextGenerationPrompts.ts
index efa251963a5..8aed88b1f16 100644
--- a/apps/server/src/textGeneration/TextGenerationPrompts.ts
+++ b/apps/server/src/textGeneration/TextGenerationPrompts.ts
@@ -12,6 +12,8 @@ import type { ChatAttachment } from "@t3tools/contracts";
 import { limitSection } from "./TextGenerationUtils.ts";
 import type { TextGenerationPolicy } from "./TextGenerationPolicy.ts";
 
+const EARLIER_CONTENT_TRUNCATION_MARKER = "[Earlier content truncated]\n\n";
+
 function policyInstruction(instruction: string | undefined): ReadonlyArray<string> {
   const trimmed = instruction?.trim();
   return trimmed ? ["", "Additional instructions:", limitSection(trimmed, 4_000)] : [];
@@ -150,10 +152,23 @@ interface PromptFromMessageInput {
   responseShape: string;
   rules: ReadonlyArray<string>;
   message: string;
+  messageLabel?: string | undefined;
+  preserveMessageEnd?: boolean | undefined;
   attachments?: ReadonlyArray<ChatAttachment> | undefined;
   additionalInstructions?: string | undefined;
 }
 
+function preserveMessageEnd(message: string): string {
+  const alreadyTruncated = message.startsWith(EARLIER_CONTENT_TRUNCATION_MARKER);
+  const contents = alreadyTruncated
+    ? message.slice(EARLIER_CONTENT_TRUNCATION_MARKER.length)
+    : message;
+  if (!alreadyTruncated && contents.length <= 8_000) {
+    return contents;
+  }
+  return `${EARLIER_CONTENT_TRUNCATION_MARKER}${contents.slice(-8_000)}`;
+}
+
 function buildPromptFromMessage(input: PromptFromMessageInput): string {
   const attachmentLines = (input.attachments ?? []).map(
     (attachment) => `- ${attachment.name} (${attachment.mimeType}, ${attachment.sizeBytes} bytes)`,
@@ -165,8 +180,10 @@ function buildPromptFromMessage(input: PromptFromMessageInput): string {
     "Rules:",
     ...input.rules.map((rule) => `- ${rule}`),
     "",
-    "User message:",
-    limitSection(input.message, 8_000),
+    `${input.messageLabel ?? "User message"}:`,
+    input.preserveMessageEnd
+      ? preserveMessageEnd(input.message)
+      : limitSection(input.message, 8_000),
     ...policyInstruction(input.additionalInstructions),
   ];
   if (attachmentLines.length > 0) {
@@ -207,21 +224,44 @@ export function buildBranchNamePrompt(input: BranchNamePromptInput) {
 
 export interface ThreadTitlePromptInput {
   message: string;
+  previousTitle?: string | undefined;
   attachments?: ReadonlyArray<ChatAttachment> | undefined;
   policy?: TextGenerationPolicy | undefined;
 }
 
 export function buildThreadTitlePrompt(input: ThreadTitlePromptInput) {
+  const isRegeneration = input.previousTitle !== undefined;
   const prompt = buildPromptFromMessage({
-    instruction: "You write concise thread titles for coding conversations.",
+    instruction: isRegeneration
+      ? [
+          "You write concise thread titles for coding conversations.",
+          "The user requested a new title based on the contents of this thread.",
+          `The previous title was ${JSON.stringify(input.previousTitle)}.`,
+          "Come up with a new title that better represents the current state of the thread.",
+        ].join("\n")
+      : "You write concise thread titles for coding conversations.",
     responseShape: "Return a JSON object with key: title.",
     rules: [
-      "Title should summarize the user's request, not restate it verbatim.",
+      isRegeneration
+        ? "Title should summarize the thread's current state, not just its initial request."
+        : "Title should summarize the user's request, not restate it verbatim.",
+      ...(isRegeneration
+        ? [
+            "Capture the thread's intent, not a PR number or other superficial detail.",
+            "Return a different title from the previous title.",
+          ]
+        : []),
       "Keep it short and specific (3-8 words).",
       "Avoid quotes, filler, prefixes, and trailing punctuation.",
       "If images are attached, use them as primary context for visual/UI issues.",
     ],
     message: input.message,
+    ...(isRegeneration
+      ? {
+          messageLabel: "Thread contents",
+          preserveMessageEnd: true,
+        }
+      : {}),
     attachments: input.attachments,
     additionalInstructions: input.policy?.threadTitleInstructions,
   });
diff --git a/apps/web/src/components/Sidebar.logic.test.ts b/apps/web/src/components/Sidebar.logic.test.ts
index 59784bf8fac..9c1e7c8c563 100644
--- a/apps/web/src/components/Sidebar.logic.test.ts
+++ b/apps/web/src/components/Sidebar.logic.test.ts
@@ -1,6 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
 import {
   archiveSelectedThreadEntries,
+  buildBulkTitleRegenerationContextMenuItem,
   buildMultiSelectThreadContextMenuItems,
   createThreadJumpHintVisibilityController,
   getSidebarThreadIdsToPrewarm,
@@ -149,6 +150,42 @@ describe("archiveSelectedThreadEntries", () => {
   });
 });
 
+describe("buildBulkTitleRegenerationContextMenuItem", () => {
+  it("counts only threads that can start a new regeneration", () => {
+    expect(
+      buildBulkTitleRegenerationContextMenuItem({
+        supportedCount: 4,
+        actionableCount: 3,
+      }),
+    ).toEqual({
+      id: "regenerate-title",
+      label: "Regenerate titles (3)",
+    });
+  });
+
+  it("shows a disabled progress item when every supported thread is pending", () => {
+    expect(
+      buildBulkTitleRegenerationContextMenuItem({
+        supportedCount: 2,
+        actionableCount: 0,
+      }),
+    ).toEqual({
+      id: "regenerate-title",
+      label: "Regenerating… (2)",
+      disabled: true,
+    });
+  });
+
+  it("omits the action when no selected environment supports it", () => {
+    expect(
+      buildBulkTitleRegenerationContextMenuItem({
+        supportedCount: 0,
+        actionableCount: 0,
+      }),
+    ).toBeNull();
+  });
+});
+
 describe("buildMultiSelectThreadContextMenuItems", () => {
   it("offers bulk archive with the selected count", () => {
     expect(
diff --git a/apps/web/src/components/Sidebar.logic.ts b/apps/web/src/components/Sidebar.logic.ts
index 7aee3100d0e..d11e06c8406 100644
--- a/apps/web/src/components/Sidebar.logic.ts
+++ b/apps/web/src/components/Sidebar.logic.ts
@@ -18,6 +18,7 @@ export const THREAD_JUMP_HINT_SHOW_DELAY_MS = 100;
 // Visible sidebar rows are prewarmed into the thread-detail cache so opening a
 // nearby thread usually reuses an already-hot subscription.
 export const SIDEBAR_THREAD_PREWARM_LIMIT = 10;
+
 type SidebarProject = {
   id: string;
   title: string;
@@ -94,6 +95,24 @@ export function buildMultiSelectThreadContextMenuItems(input: {
   ];
 }
 
+export function buildBulkTitleRegenerationContextMenuItem(input: {
+  supportedCount: number;
+  actionableCount: number;
+}): ContextMenuItem<"regenerate-title"> | null {
+  if (input.supportedCount === 0) return null;
+  if (input.actionableCount === 0) {
+    return {
+      id: "regenerate-title",
+      label: `Regenerating… (${input.supportedCount})`,
+      disabled: true,
+    };
+  }
+  return {
+    id: "regenerate-title",
+    label: `Regenerate titles (${input.actionableCount})`,
+  };
+}
+
 export interface ThreadStatusPill {
   label:
     | "Working"
diff --git a/apps/web/src/components/SidebarV2.tsx b/apps/web/src/components/SidebarV2.tsx
index 33c2512abf7..d58d2b37cd1 100644
--- a/apps/web/src/components/SidebarV2.tsx
+++ b/apps/web/src/components/SidebarV2.tsx
@@ -106,6 +106,7 @@ import { formatRelativeTimeLabel, parseTimestampDate } from "../timestampFormat"
 import type { SidebarThreadSummary } from "../types";
 import { cn } from "~/lib/utils";
 import {
+  buildBulkTitleRegenerationContextMenuItem,
   formatWorkingDurationLabel,
   firstValidTimestampMs,
   hasUnseenCompletion,
@@ -444,6 +445,7 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
     [thread.environmentId, thread.id],
   );
   const threadKey = scopedThreadKey(threadRef);
+  const isRegeneratingTitle = thread.titleRegeneration != null;
   const lastVisitedAt = useUiStateStore((state) => state.threadLastVisitedAtById[threadKey]);
   const isSelected = useThreadSelectionStore((state) => state.selectedThreadKeys.has(threadKey));
   const openPrLink = useOpenPrLink();
@@ -721,7 +723,7 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
   ) : (
     <span
       className={cn(
-        "min-w-0 flex-1 text-sm",
+        "min-w-0 flex-1 text-sm transition-opacity motion-reduce:transition-none",
         shouldRecede ? "font-normal" : "font-medium",
         variant === "card"
           ? cn(
@@ -742,6 +744,7 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
                   ? "text-muted-foreground"
                   : "text-muted-foreground/70",
             ),
+        isRegeneratingTitle && "opacity-[0.55]",
       )}
     >
       {thread.title}
@@ -790,6 +793,7 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
                 role="button"
                 tabIndex={0}
                 data-testid="sidebar-v2-row-slim"
+                aria-busy={isRegeneratingTitle || undefined}
                 className={cn(rowSurfaceClassName, "flex h-9 items-center gap-2.5 px-2.5")}
                 onClick={handleClick}
                 onDoubleClick={handleDoubleClick}
@@ -816,6 +820,11 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
             </span>
             {title}
             {terminalStatusIcon}
+            {isRegeneratingTitle ? (
+              <span role="status" className="sr-only">
+                Regenerating title
+              </span>
+            ) : null}
             {/* The PR badge stays outside the hover-fading slot: it must
               remain visible AND clickable while the row is hovered. Only
               the time/jump label yields to the settle affordance. */}
@@ -900,6 +909,7 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
               role="button"
               tabIndex={0}
               data-testid="sidebar-v2-row-card"
+              aria-busy={isRegeneratingTitle || undefined}
               className={rowSurfaceClassName}
               onClick={handleClick}
               onDoubleClick={handleDoubleClick}
@@ -998,7 +1008,14 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
                 ) : null}
               </span>
             </div>
-            <div className="mt-1 flex min-w-0">{title}</div>
+            <div className="mt-1 flex min-w-0">
+              {title}
+              {isRegeneratingTitle ? (
+                <span role="status" className="sr-only">
+                  Regenerating title
+                </span>
+              ) : null}
+            </div>
             <div className="mt-0.5 flex min-w-0 items-center gap-1.5 text-xs text-muted-foreground/75">
               {thread.branch ? (
                 <span className="min-w-0 flex-1 truncate whitespace-nowrap">{thread.branch}</span>
@@ -1912,16 +1929,28 @@ export default function SidebarV2() {
       const count = threadKeys.length;
       // Snooze (N) is offered when every selected thread can actually take
       // it — a mixed selection with blocked-on-you work would half-apply.
-      const selectionNow = new Date().toISOString();
-      const snoozableThreads = threadKeys.flatMap((threadKey) => {
+      const selectionNow = new Date();
+      const selectedThreads = threadKeys.flatMap((threadKey) => {
         const thread = threadByKeyRef.current.get(threadKey);
         return thread ? [thread] : [];
       });
-      const canSnoozeSelection = snoozableThreads.every(
+      const canSnoozeSelection = selectedThreads.every(
         (thread) =>
           serverConfigs.get(thread.environmentId)?.environment.capabilities.threadSnooze === true &&
-          canSnooze(thread, { now: selectionNow }),
+          canSnooze(thread, { now: selectionNow.toISOString() }),
       );
+      const titleRegenerationThreads = selectedThreads.filter(
+        (thread) =>
+          serverConfigs.get(thread.environmentId)?.environment.capabilities
+            .threadTitleRegeneration === true,
+      );
+      const regeneratableTitleThreads = titleRegenerationThreads.filter(
+        (thread) => thread.titleRegeneration == null,
+      );
+      const titleRegenerationMenuItem = buildBulkTitleRegenerationContextMenuItem({
+        supportedCount: titleRegenerationThreads.length,
+        actionableCount: regeneratableTitleThreads.length,
+      });
       const snoozePresets = resolveSnoozePresets(new Date());
       const clicked = await settlePromise(() =>
         api.contextMenu.show(
@@ -1939,6 +1968,7 @@ export default function SidebarV2() {
                   },
                 ]
               : []),
+            ...(titleRegenerationMenuItem ? [titleRegenerationMenuItem] : []),
             { id: "mark-unread", label: `Mark unread (${count})` },
             { id: "delete", label: `Delete (${count})`, destructive: true },
           ],
@@ -1954,7 +1984,7 @@ export default function SidebarV2() {
           // Post-snooze navigation must skip threads snoozing in this same
           // batch — they are all leaving the card block together.
           const coSnoozingKeys = new Set(threadKeys);
-          for (const thread of snoozableThreads) {
+          for (const thread of selectedThreads) {
             attemptSnooze(scopeThreadRef(thread.environmentId, thread.id), preset, {
               coSnoozingKeys,
             });
@@ -1963,6 +1993,28 @@ export default function SidebarV2() {
         }
         return;
       }
+      if (clicked.value === "regenerate-title") {
+        for (const thread of regeneratableTitleThreads) {
+          const result = await updateThreadMetadata({
+            environmentId: thread.environmentId,
+            input: { threadId: thread.id, regenerateTitle: true },
+          });
+          if (result._tag === "Success") continue;
+          if (!isAtomCommandInterrupted(result)) {
+            const error = squashAtomCommandFailure(result);
+            toastManager.add(
+              stackedThreadToast({
+                type: "error",
+                title: "Failed to regenerate thread titles",
+                description: error instanceof Error ? error.message : "An error occurred.",
+              }),
+            );
+          }
+          return;
+        }
+        clearSelection();
+        return;
+      }
       if (clicked.value === "settle") {
         // Post-settle navigation must skip threads settling in this same
         // batch — they are all leaving the card block together. Rows that
@@ -2034,6 +2086,7 @@ export default function SidebarV2() {
       markThreadUnread,
       removeFromSelection,
       serverConfigs,
+      updateThreadMetadata,
     ],
   );
 
@@ -2063,6 +2116,10 @@ export default function SidebarV2() {
           true;
         const supportsSnooze =
           serverConfigs.get(thread.environmentId)?.environment.capabilities.threadSnooze === true;
+        const supportsTitleRegeneration =
+          serverConfigs.get(thread.environmentId)?.environment.capabilities
+            .threadTitleRegeneration === true;
+        const isRegeneratingTitle = thread.titleRegeneration != null;
         const isSettled = settledThreadKeysRef.current.has(threadKey);
         const isSnoozed = snoozedThreadKeysRef.current.has(threadKey);
         // Presets resolve at menu-open time (same as the popover).
@@ -2101,6 +2158,15 @@ export default function SidebarV2() {
                   ]
                 : []),
               { id: "rename", label: "Rename thread" },
+              ...(supportsTitleRegeneration
+                ? [
+                    {
+                      id: "regenerate-title",
+                      label: isRegeneratingTitle ? "Regenerating…" : "Regenerate title",
+                      disabled: isRegeneratingTitle,
+                    },
+                  ]
+                : []),
               { id: "mark-unread", label: "Mark unread" },
               { id: "copy-path", label: "Copy path", icon: "copy" },
               ...(thread.branch ? [{ id: "copy-branch", label: "Copy branch", icon: "copy" }] : []),
@@ -2153,6 +2219,24 @@ export default function SidebarV2() {
           case "rename":
             startThreadRename(threadRef, thread.title);
             return;
+          case "regenerate-title": {
+            if (isRegeneratingTitle) return;
+            const result = await updateThreadMetadata({
+              environmentId: threadRef.environmentId,
+              input: { threadId: threadRef.threadId, regenerateTitle: true },
+            });
+            if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
+              const error = squashAtomCommandFailure(result);
+              toastManager.add(
+                stackedThreadToast({
+                  type: "error",
+                  title: "Failed to regenerate thread title",
+                  description: error instanceof Error ? error.message : "An error occurred.",
+                }),
+              );
+            }
+            return;
+          }
           case "mark-unread":
             markThreadUnread(threadKey, thread.latestTurn?.completedAt);
             return;
@@ -2219,6 +2303,7 @@ export default function SidebarV2() {
       projectCwdByKey,
       serverConfigs,
       startThreadRename,
+      updateThreadMetadata,
     ],
   );
 
diff --git a/packages/client-runtime/src/state/threadReducer.test.ts b/packages/client-runtime/src/state/threadReducer.test.ts
index 211f8748f4e..967c30960f9 100644
--- a/packages/client-runtime/src/state/threadReducer.test.ts
+++ b/packages/client-runtime/src/state/threadReducer.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from "vite-plus/test";
 
 import {
   CheckpointRef,
+  CommandId,
   EventId,
   MessageId,
   ProjectId,
@@ -123,8 +124,15 @@ describe("applyThreadDetailEvent", () => {
   });
 
   describe("thread.archived / thread.unarchived", () => {
-    it("sets archivedAt", () => {
-      const result = applyThreadDetailEvent(baseThread, {
+    it("sets archivedAt and clears title regeneration", () => {
+      const regeneratingThread: OrchestrationThread = {
+        ...baseThread,
+        titleRegeneration: {
+          requestId: CommandId.make("regenerate-title"),
+          startedAt: "2026-04-01T02:00:00.000Z",
+        },
+      };
+      const result = applyThreadDetailEvent(regeneratingThread, {
         ...baseEventFields,
         sequence: 3,
         occurredAt: "2026-04-01T03:00:00.000Z",
@@ -141,6 +149,7 @@ describe("applyThreadDetailEvent", () => {
       expect(result.kind).toBe("updated");
       if (result.kind === "updated") {
         expect(result.thread.archivedAt).toBe("2026-04-01T03:00:00.000Z");
+        expect(result.thread.titleRegeneration).toBeNull();
       }
     });
 
diff --git a/packages/client-runtime/src/state/threadReducer.ts b/packages/client-runtime/src/state/threadReducer.ts
index ce0dca52f5a..6b04f094d82 100644
--- a/packages/client-runtime/src/state/threadReducer.ts
+++ b/packages/client-runtime/src/state/threadReducer.ts
@@ -94,6 +94,7 @@ export function applyThreadDetailEvent(
         thread: {
           ...thread,
           archivedAt: event.payload.archivedAt,
+          titleRegeneration: null,
           updatedAt: event.payload.updatedAt,
         },
       };
@@ -155,6 +156,9 @@ export function applyThreadDetailEvent(
         thread: {
           ...thread,
           ...(event.payload.title !== undefined ? { title: event.payload.title } : {}),
+          ...(event.payload.titleRegeneration !== undefined
+            ? { titleRegeneration: event.payload.titleRegeneration }
+            : {}),
           ...(event.payload.modelSelection !== undefined
             ? { modelSelection: event.payload.modelSelection }
             : {}),
diff --git a/packages/contracts/src/environment.ts b/packages/contracts/src/environment.ts
index 7f4b6c16541..3d753350d99 100644
--- a/packages/contracts/src/environment.ts
+++ b/packages/contracts/src/environment.ts
@@ -47,6 +47,9 @@ export const ExecutionEnvironmentCapabilities = Schema.Struct({
   /** Server understands thread.snooze / thread.unsnooze commands. Same
       version-skew contract as threadSettlement. */
   threadSnooze: Schema.optionalKey(Schema.Boolean),
+  /** Server understands regenerateTitle on thread.meta.update. Absent on
+      older servers, so clients hide the action instead of sending it. */
+  threadTitleRegeneration: Schema.optionalKey(Schema.Boolean),
   /** The update path clients should offer for this server. Absent on
       servers that must be relaunched manually (dev checkouts, Windows
       foreground runs, pre-update servers). */
diff --git a/packages/contracts/src/orchestration.test.ts b/packages/contracts/src/orchestration.test.ts
index 1ebc23a483b..ecf7afa0610 100644
--- a/packages/contracts/src/orchestration.test.ts
+++ b/packages/contracts/src/orchestration.test.ts
@@ -320,12 +320,20 @@ it.effect("decodes thread.meta-updated payloads with explicit provider", () =>
   Effect.gen(function* () {
     const parsed = yield* decodeThreadMetaUpdatedPayload({
       threadId: "thread-1",
+      regenerateTitle: true,
+      previousTitle: "Previous title",
+      titleRegeneration: {
+        requestId: "cmd-title-regenerate",
+        startedAt: "2026-01-01T00:00:00.000Z",
+      },
       modelSelection: {
         provider: "claudeAgent",
         model: "claude-opus-4-6",
       },
       updatedAt: "2026-01-01T00:00:00.000Z",
     });
+    assert.strictEqual(parsed.previousTitle, "Previous title");
+    assert.strictEqual(parsed.titleRegeneration?.requestId, "cmd-title-regenerate");
     assert.strictEqual(parsed.modelSelection?.instanceId, "claudeAgent");
   }),
 );
@@ -628,6 +636,53 @@ it.effect("accepts a title seed in thread.turn.start", () =>
   }),
 );
 
+it.effect("accepts a title regeneration intent in thread.meta.update", () =>
+  Effect.gen(function* () {
+    const parsed = yield* decodeOrchestrationCommand({
+      type: "thread.meta.update",
+      commandId: "cmd-title-regenerate",
+      threadId: "thread-1",
+      regenerateTitle: true,
+    });
+    assert.strictEqual(parsed.type, "thread.meta.update");
+    if (parsed.type === "thread.meta.update") {
+      assert.strictEqual(parsed.regenerateTitle, true);
+    }
+  }),
+);
+
+it.effect("accepts an internal title regeneration completion", () =>
+  Effect.gen(function* () {
+    const parsed = yield* decodeOrchestrationCommand({
+      type: "thread.title.regeneration.complete",
+      commandId: "cmd-title-regeneration-complete",
+      threadId: "thread-1",
+      requestId: "cmd-title-regenerate",
+      title: "Updated title",
+    });
+    assert.strictEqual(parsed.type, "thread.title.regeneration.complete");
+    if (parsed.type === "thread.title.regeneration.complete") {
+      assert.strictEqual(parsed.requestId, "cmd-title-regenerate");
+      assert.strictEqual(parsed.title, "Updated title");
+    }
+  }),
+);
+
+it.effect("rejects an explicit title combined with title regeneration", () =>
+  Effect.gen(function* () {
+    const result = yield* Effect.exit(
+      decodeOrchestrationCommand({
+        type: "thread.meta.update",
+        commandId: "cmd-title-regenerate-with-title",
+        threadId: "thread-1",
+        title: "Explicit title",
+        regenerateTitle: true,
+      }),
+    );
+    assert.strictEqual(result._tag, "Failure");
+  }),
+);
+
 it.effect("accepts a source proposed plan reference in thread.turn.start", () =>
   Effect.gen(function* () {
     const parsed = yield* decodeThreadTurnStartCommand({
diff --git a/packages/contracts/src/orchestration.ts b/packages/contracts/src/orchestration.ts
index b947bd63e4c..81d647ece7d 100644
--- a/packages/contracts/src/orchestration.ts
+++ b/packages/contracts/src/orchestration.ts
@@ -341,6 +341,12 @@ export const OrchestrationLatestTurn = Schema.Struct({
 });
 export type OrchestrationLatestTurn = typeof OrchestrationLatestTurn.Type;
 
+export const ThreadTitleRegeneration = Schema.Struct({
+  requestId: CommandId,
+  startedAt: IsoDateTime,
+});
+export type ThreadTitleRegeneration = typeof ThreadTitleRegeneration.Type;
+
 export const OrchestrationThread = Schema.Struct({
   id: ThreadId,
   projectId: ProjectId,
@@ -366,6 +372,8 @@ export const OrchestrationThread = Schema.Struct({
   // Optional so payloads from pre-snooze servers still decode.
   snoozedUntil: Schema.optional(Schema.NullOr(IsoDateTime)),
   snoozedAt: Schema.optional(Schema.NullOr(IsoDateTime)),
+  // Pending-only state. Optional so older servers remain compatible.
+  titleRegeneration: Schema.optional(Schema.NullOr(ThreadTitleRegeneration)),
   deletedAt: Schema.NullOr(IsoDateTime),
   messages: Schema.Array(OrchestrationMessage),
   proposedPlans: Schema.Array(OrchestrationProposedPlan).pipe(
@@ -418,6 +426,7 @@ export const OrchestrationThreadShell = Schema.Struct({
   settledAt: Schema.NullOr(IsoDateTime).pipe(Schema.withDecodingDefault(Effect.succeed(null))),
   snoozedUntil: Schema.optional(Schema.NullOr(IsoDateTime)),
   snoozedAt: Schema.optional(Schema.NullOr(IsoDateTime)),
+  titleRegeneration: Schema.optional(Schema.NullOr(ThreadTitleRegeneration)),
   session: Schema.NullOr(OrchestrationSession),
   latestUserMessageAt: Schema.NullOr(IsoDateTime),
   hasPendingApprovals: Schema.Boolean,
@@ -616,11 +625,18 @@ const ThreadMetaUpdateCommand = Schema.Struct({
   commandId: CommandId,
   threadId: ThreadId,
   title: Schema.optional(TrimmedNonEmptyString),
+  regenerateTitle: Schema.optional(Schema.Literal(true)),
   modelSelection: Schema.optional(ModelSelection),
   branch: Schema.optional(Schema.NullOr(TrimmedNonEmptyString)),
   expectedBranch: Schema.optional(Schema.NullOr(TrimmedNonEmptyString)),
   worktreePath: Schema.optional(Schema.NullOr(TrimmedNonEmptyString)),
-});
+}).check(
+  Schema.makeFilter(
+    (input) =>
+      !(input.title !== undefined && input.regenerateTitle === true) ||
+      "title and regenerateTitle cannot be specified together",
+  ),
+);
 
 const ThreadRuntimeModeSetCommand = Schema.Struct({
   type: Schema.Literal("thread.runtime-mode.set"),
@@ -859,6 +875,14 @@ const ThreadRevertCompleteCommand = Schema.Struct({
   createdAt: IsoDateTime,
 });
 
+const ThreadTitleRegenerationCompleteCommand = Schema.Struct({
+  type: Schema.Literal("thread.title.regeneration.complete"),
+  commandId: CommandId,
+  threadId: ThreadId,
+  requestId: CommandId,
+  title: Schema.optional(TrimmedNonEmptyString),
+});
+
 const InternalOrchestrationCommand = Schema.Union([
   ThreadSessionSetCommand,
   ThreadMessageAssistantDeltaCommand,
@@ -867,6 +891,7 @@ const InternalOrchestrationCommand = Schema.Union([
   ThreadTurnDiffCompleteCommand,
   ThreadActivityAppendCommand,
   ThreadRevertCompleteCommand,
+  ThreadTitleRegenerationCompleteCommand,
 ]);
 export type InternalOrchestrationCommand = typeof InternalOrchestrationCommand.Type;
 
@@ -999,6 +1024,13 @@ export const ThreadUnsnoozedPayload = Schema.Struct({
 export const ThreadMetaUpdatedPayload = Schema.Struct({
   threadId: ThreadId,
   title: Schema.optional(TrimmedNonEmptyString),
+  /** Intent marker consumed by the title-generation reactor. Keeping this on
+      the existing event lets older clients safely ignore the new field. */
+  regenerateTitle: Schema.optional(Schema.Literal(true)),
+  /** Title at request time, used to avoid overwriting a later manual rename. */
+  previousTitle: Schema.optional(TrimmedNonEmptyString),
+  /** Pending state shared with clients. Null clears a matching request. */
+  titleRegeneration: Schema.optional(Schema.NullOr(ThreadTitleRegeneration)),
   modelSelection: Schema.optional(ModelSelection),
   branch: Schema.optional(Schema.NullOr(TrimmedNonEmptyString)),
   worktreePath: Schema.optional(Schema.NullOr(TrimmedNonEmptyString)),

From 197d3487116372ca2f16661f57d4e869fc3cb6c0 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Thu, 30 Jul 2026 04:45:04 -0700
Subject: [PATCH 19/34] fix(web): show server update progress through reconnect
 (#4903)

---
 apps/server/src/auth/RpcAuthorization.ts      |   1 +
 apps/server/src/cloud/selfUpdate.test.ts      |  45 ++-
 apps/server/src/cloud/selfUpdate.ts           |  71 ++--
 .../src/environment/ServerEnvironment.ts      |   3 +
 apps/server/src/ws.ts                         |  29 ++
 apps/web/src/components/ChatView.tsx          |  73 ++--
 .../components/ServerUpdateAction.test.tsx    | 215 +++++------
 .../web/src/components/ServerUpdateAction.tsx | 249 +++++++------
 .../settings/ConnectionsSettings.tsx          |  63 +++-
 docs/architecture/server-updates.md           |  54 +--
 docs/user/server-updates.md                   |  13 +-
 .../src/connection/supervisor.test.ts         |  37 ++
 .../src/connection/supervisor.ts              |   9 +-
 packages/client-runtime/src/rpc/client.ts     |   3 +-
 .../client-runtime/src/state/runtime.test.ts  |  49 +++
 packages/client-runtime/src/state/runtime.ts  |  22 ++
 .../client-runtime/src/state/server.test.ts   | 134 ++++++-
 packages/client-runtime/src/state/server.ts   | 335 +++++++++++++++++-
 packages/contracts/src/environment.ts         |   3 +
 packages/contracts/src/rpc.ts                 |  13 +
 packages/contracts/src/server.ts              |  15 +
 21 files changed, 1072 insertions(+), 364 deletions(-)

diff --git a/apps/server/src/auth/RpcAuthorization.ts b/apps/server/src/auth/RpcAuthorization.ts
index 5655f260bc9..b4bea21d2e3 100644
--- a/apps/server/src/auth/RpcAuthorization.ts
+++ b/apps/server/src/auth/RpcAuthorization.ts
@@ -32,6 +32,7 @@ export const RPC_REQUIRED_SCOPES = {
   [WS_METHODS.serverRefreshProviders]: AuthOrchestrationOperateScope,
   [WS_METHODS.serverUpdateProvider]: AuthOrchestrationOperateScope,
   [WS_METHODS.serverUpdateServer]: AuthOrchestrationOperateScope,
+  [WS_METHODS.serverUpdateServerWithProgress]: AuthOrchestrationOperateScope,
   [WS_METHODS.serverUpsertKeybinding]: AuthOrchestrationOperateScope,
   [WS_METHODS.serverRemoveKeybinding]: AuthOrchestrationOperateScope,
   [WS_METHODS.serverGetSettings]: AuthOrchestrationReadScope,
diff --git a/apps/server/src/cloud/selfUpdate.test.ts b/apps/server/src/cloud/selfUpdate.test.ts
index 9d6e3801704..655228c047f 100644
--- a/apps/server/src/cloud/selfUpdate.test.ts
+++ b/apps/server/src/cloud/selfUpdate.test.ts
@@ -26,6 +26,33 @@ import * as SelfUpdate from "./selfUpdate.ts";
 
 const NODE_PATH = "/usr/local/bin/node";
 
+const eventuallyFileString = Effect.fn("test.eventuallyFileString")(function* (
+  filePath: string,
+  expected: string,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  for (let iteration = 0; iteration < 1_000; iteration += 1) {
+    const contents = yield* fs.readFileString(filePath);
+    if (contents === expected) {
+      return;
+    }
+    // The rollback performs real filesystem I/O on a detached fiber, which
+    // advancing TestClock does not await.
+    yield* Effect.yieldNow;
+  }
+  return yield* Effect.die(new Error(`Expected file contents were not observed at ${filePath}.`));
+});
+
+const eventuallyTrue = Effect.fn("test.eventuallyTrue")(function* (predicate: () => boolean) {
+  for (let iteration = 0; iteration < 1_000; iteration += 1) {
+    if (predicate()) {
+      return;
+    }
+    yield* Effect.yieldNow;
+  }
+  return yield* Effect.die(new Error("Expected condition was not observed."));
+});
+
 interface RecordedCommand {
   readonly command: string;
   readonly args: ReadonlyArray<string>;
@@ -457,8 +484,12 @@ it.layer(NodeServices.layer)("ServerSelfUpdate.update", (it) => {
   it.effect("installs, preflights, and respawns a foreground server", () =>
     Effect.gen(function* () {
       const context = yield* makeContext();
-      const result = yield* context.service.update({ targetVersion: "0.0.29" });
+      const progress: Array<string> = [];
+      const result = yield* context.service.update({ targetVersion: "0.0.29" }, (stage) =>
+        Effect.sync(() => progress.push(stage)),
+      );
       assert.deepEqual(result, { targetVersion: "0.0.29", method: "respawn" });
+      assert.deepEqual(progress, ["downloading", "installing"]);
       assert.lengthOf(context.spawns, 1);
 
       const concurrentError = yield* context.service
@@ -506,10 +537,12 @@ it.layer(NodeServices.layer)("ServerSelfUpdate.update", (it) => {
       assert.include(unit, `ExecStart=${NODE_PATH} ${pinnedEntry} serve`);
       assert.deepEqual(
         context.commands.map((entry) => entry.command),
-        ["npm", NODE_PATH, "systemctl", "systemctl"],
+        ["npm", NODE_PATH, "systemctl"],
       );
       assert.deepEqual(context.commands[2]?.args, ["--user", "daemon-reload"]);
 
+      // Restart waits until after the update acknowledgement can flush.
+      yield* TestClock.adjust(Duration.seconds(10));
       assert.deepEqual(context.commands[3], {
         command: "systemctl",
         args: ["--user", "restart", "t3code.service"],
@@ -542,9 +575,11 @@ it.layer(NodeServices.layer)("ServerSelfUpdate.update", (it) => {
       );
       const previousUnit = yield* context.fs.readFileString(unitPath);
 
-      const first = yield* context.service.update({ targetVersion: "0.0.29" }).pipe(Effect.flip);
-      assert.include(first.reason, "Restarting the systemd boot service failed");
-      assert.equal(yield* context.fs.readFileString(unitPath), previousUnit);
+      const first = yield* context.service.update({ targetVersion: "0.0.29" });
+      assert.deepEqual(first, { targetVersion: "0.0.29", method: "boot-service" });
+      yield* TestClock.adjust(Duration.seconds(10));
+      yield* eventuallyFileString(unitPath, previousUnit);
+      yield* eventuallyTrue(() => context.commands.at(-1)?.args[1] === "daemon-reload");
       assert.deepEqual(
         context.commands.slice(-2).map((entry) => entry.args),
         [
diff --git a/apps/server/src/cloud/selfUpdate.ts b/apps/server/src/cloud/selfUpdate.ts
index 62bd07fbbc8..f786cbea8cf 100644
--- a/apps/server/src/cloud/selfUpdate.ts
+++ b/apps/server/src/cloud/selfUpdate.ts
@@ -6,6 +6,7 @@ import {
   ServerSelfUpdateError,
   type ServerSelfUpdateCapability,
   type ServerSelfUpdateInput,
+  type ServerSelfUpdateProgressStage,
   type ServerSelfUpdateResult,
 } from "@t3tools/contracts";
 import {
@@ -147,6 +148,7 @@ export class ServerSelfUpdate extends Context.Service<
   {
     readonly update: (
       input: ServerSelfUpdateInput,
+      reportProgress?: (stage: ServerSelfUpdateProgressStage) => Effect.Effect<void, never, never>,
     ) => Effect.Effect<ServerSelfUpdateResult, ServerSelfUpdateError>;
   }
 >()("t3/cloud/selfUpdate/ServerSelfUpdate") {}
@@ -227,7 +229,7 @@ export const make = Effect.fn("cloud.server_self_update.make")(function* (option
 
   const update: ServerSelfUpdate["Service"]["update"] = Effect.fn(
     "cloud.server_self_update.update",
-  )(function* (input) {
+  )(function* (input, reportProgress = () => Effect.void) {
     if (capability === "desktop-managed") {
       return yield* failWith(
         "This server is managed by the T3 Code desktop app on its machine; update the desktop app to update it.",
@@ -250,6 +252,7 @@ export const make = Effect.fn("cloud.server_self_update.make")(function* (option
     }
 
     return yield* Effect.gen(function* () {
+      yield* reportProgress("downloading");
       const runtimePaths = yield* ensurePinnedRuntimeInstalled({
         baseDir: serverConfig.baseDir,
         version: targetVersion,
@@ -260,6 +263,7 @@ export const make = Effect.fn("cloud.server_self_update.make")(function* (option
         Effect.mapError((error) => failWith("Could not install the requested t3 version.", error)),
       );
 
+      yield* reportProgress("installing");
       // A broken artifact (failed native build, incompatible node) must be
       // caught while the current server is still alive to report it.
       const preflight = yield* runner
@@ -349,38 +353,45 @@ export const make = Effect.fn("cloud.server_self_update.make")(function* (option
         yield* Effect.logInfo("Server self-update installed; restarting boot service.", {
           targetVersion,
         });
-        // A successful systemd restart stops this process, so the RPC is
-        // interrupted and the reconnecting client observes the new version.
-        // A rejected restart returns while the old process is still alive;
-        // restore the previous unit and report that failure through the RPC.
-        yield* Effect.gen(function* () {
-          const restart = yield* runner
-            .run({
-              command: "systemctl",
-              args: ["--user", "restart", BOOT_SERVICE_UNIT_FILE],
-            })
-            .pipe(
-              Effect.mapError((cause) =>
-                failWith("Could not restart the systemd boot service.", cause),
+        // Restart after the acknowledgement has had time to cross any relay
+        // hop. If systemd rejects the handoff, restore the previous unit while
+        // this process is still alive and log the failure for diagnostics.
+        yield* scheduleRestart(
+          Effect.gen(function* () {
+            const restart = yield* runner
+              .run({
+                command: "systemctl",
+                args: ["--user", "restart", BOOT_SERVICE_UNIT_FILE],
+              })
+              .pipe(
+                Effect.mapError((cause) =>
+                  failWith("Could not restart the systemd boot service.", cause),
+                ),
+              );
+            if (restart.code !== 0) {
+              return yield* failWith(
+                `Restarting the systemd boot service failed (exit code ${String(restart.code)}).`,
+              );
+            }
+          }).pipe(
+            Effect.catch((restartError) =>
+              writeUnitAtomically(unitPath, previousUnit).pipe(
+                Effect.andThen(reloadSystemd()),
+                Effect.mapError((rollbackError) =>
+                  failWith("Could not restore the previous systemd unit.", {
+                    restartError,
+                    rollbackError,
+                  }),
+                ),
+                Effect.andThen(Effect.fail(restartError)),
               ),
-            );
-          if (restart.code !== 0) {
-            return yield* failWith(
-              `Restarting the systemd boot service failed (exit code ${String(restart.code)}).`,
-            );
-          }
-        }).pipe(
-          Effect.catch((restartError) =>
-            writeUnitAtomically(unitPath, previousUnit).pipe(
-              Effect.andThen(reloadSystemd()),
-              Effect.mapError((rollbackError) =>
-                failWith("Could not restore the previous systemd unit.", {
-                  restartError,
-                  rollbackError,
-                }),
+            ),
+            Effect.catch((error) =>
+              Effect.logError("Server self-update could not restart the boot service.").pipe(
+                Effect.annotateLogs({ targetVersion, error: error.reason }),
               ),
-              Effect.andThen(Effect.fail(restartError)),
             ),
+            Effect.ensuring(Ref.set(inFlight, false)),
           ),
         );
       } else {
diff --git a/apps/server/src/environment/ServerEnvironment.ts b/apps/server/src/environment/ServerEnvironment.ts
index 250d4d7745a..2290450e7d3 100644
--- a/apps/server/src/environment/ServerEnvironment.ts
+++ b/apps/server/src/environment/ServerEnvironment.ts
@@ -144,6 +144,9 @@ export const make = Effect.gen(function* () {
       threadSnooze: true,
       threadTitleRegeneration: true,
       ...(serverSelfUpdate === null ? {} : { serverSelfUpdate }),
+      ...(serverSelfUpdate === "boot-service" || serverSelfUpdate === "respawn"
+        ? { serverSelfUpdateProgress: true }
+        : {}),
     },
   };
 
diff --git a/apps/server/src/ws.ts b/apps/server/src/ws.ts
index 6c021c9af80..e33c6992bbb 100644
--- a/apps/server/src/ws.ts
+++ b/apps/server/src/ws.ts
@@ -40,6 +40,8 @@ import {
   ProjectWriteFileError,
   RelayClientInstallFailedError,
   type RelayClientInstallProgressEvent,
+  type ServerSelfUpdateError,
+  type ServerSelfUpdateProgressEvent,
   type FilesystemBrowseFailure,
   FilesystemBrowseError,
   AssetWorkspaceContextNotFoundError,
@@ -1364,6 +1366,33 @@ const makeWsRpcLayer = (
           observeRpcEffect(WS_METHODS.serverUpdateServer, serverSelfUpdate.update(input), {
             "rpc.aggregate": "server",
           }),
+        [WS_METHODS.serverUpdateServerWithProgress]: (input) =>
+          observeRpcStream(
+            WS_METHODS.serverUpdateServerWithProgress,
+            Stream.callback<ServerSelfUpdateProgressEvent, ServerSelfUpdateError>((queue) =>
+              serverSelfUpdate
+                .update(input, (stage) =>
+                  Queue.offer(queue, {
+                    type: "progress",
+                    stage,
+                  }).pipe(Effect.asVoid),
+                )
+                .pipe(
+                  Effect.flatMap((result) =>
+                    Queue.offer(queue, {
+                      type: "complete",
+                      result,
+                    }),
+                  ),
+                  Effect.catchTags({
+                    ServerSelfUpdateError: (error) => Queue.fail(queue, error),
+                  }),
+                  Effect.andThen(Queue.end(queue)),
+                  Effect.forkScoped,
+                ),
+            ),
+            { "rpc.aggregate": "server" },
+          ),
         [WS_METHODS.serverUpsertKeybinding]: (rule) =>
           observeRpcEffect(
             WS_METHODS.serverUpsertKeybinding,
diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index d532c8b1233..ec85e4c4c18 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -296,7 +296,7 @@ import {
   AlertDialogTitle,
 } from "./ui/alert-dialog";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "./ui/tooltip";
-import { ServerUpdateAction } from "./ServerUpdateAction";
+import { ServerUpdateAction, ServerUpdateProgress } from "./ServerUpdateAction";
 import {
   buildVersionMismatchDismissalKey,
   dismissVersionMismatch,
@@ -1876,12 +1876,16 @@ function ChatViewContent(props: ChatViewProps) {
     hasMultipleRegisteredEnvironments && activeThread
       ? `${environmentById.get(activeThread.environmentId)?.label ?? serverConfig?.environment.label ?? activeThread.environmentId} server`
       : "server";
-  const versionMismatchEnvironmentId =
-    versionMismatch && activeThread ? activeThread.environmentId : null;
+  const serverUpdateEnvironmentId = activeThread?.environmentId ?? null;
   const versionMismatchSelfUpdate = resolveServerSelfUpdateCapability(serverConfig);
+  const serverUpdateState = useAtomValue(
+    serverEnvironment.updateStateAtom(serverUpdateEnvironmentId),
+  );
   const systemComposerBannerItems = useMemo<ComposerBannerStackItem[]>(() => {
     const items: ComposerBannerStackItem[] = [];
-    if (activeEnvironmentUnavailableState) {
+    const resumingServerUpdate =
+      serverUpdateState.status === "running" && serverUpdateState.stage === "resuming";
+    if (activeEnvironmentUnavailableState && !resumingServerUpdate) {
       const connection = activeEnvironmentUnavailableState.connection;
       const isReconnecting =
         connection.phase === "connecting" || connection.phase === "reconnecting";
@@ -1918,39 +1922,57 @@ function ChatViewContent(props: ChatViewProps) {
       });
     }
     if (
-      showVersionMismatchBanner &&
-      versionMismatch &&
-      versionMismatchDismissKey &&
-      versionMismatchEnvironmentId
+      serverUpdateEnvironmentId &&
+      (serverUpdateState.status !== "idle" ||
+        (showVersionMismatchBanner && versionMismatch && versionMismatchDismissKey))
     ) {
+      const updateInProgress = serverUpdateState.status === "running";
+      const updateFailed = serverUpdateState.status === "failed";
       items.push({
-        id: `version-mismatch:${versionMismatchDismissKey}`,
-        variant: "warning",
+        id: `server-version:${serverUpdateEnvironmentId}`,
+        variant: updateFailed ? "error" : "warning",
         icon: <TriangleAlertIcon />,
-        title: "Client and server versions differ",
-        description: (
-          <>
-            Client {versionMismatch.clientVersion} is connected to {versionMismatchServerLabel}{" "}
-            {versionMismatch.serverVersion}.{" "}
-            {serverUpdateGuidance(versionMismatchSelfUpdate, versionMismatchServerLabel)}
-          </>
-        ),
+        title:
+          updateInProgress || updateFailed
+            ? `${updateFailed ? "Could not update" : "Updating"} ${versionMismatchServerLabel}`
+            : "Client and server versions differ",
+        description:
+          updateInProgress || updateFailed ? (
+            <ServerUpdateProgress
+              fromVersion={serverUpdateState.fromVersion}
+              serverLabel={versionMismatchServerLabel}
+              state={serverUpdateState}
+            />
+          ) : versionMismatch ? (
+            <>
+              Client {versionMismatch.clientVersion} is connected to {versionMismatchServerLabel}{" "}
+              {versionMismatch.serverVersion}.{" "}
+              {serverUpdateGuidance(versionMismatchSelfUpdate, versionMismatchServerLabel)}
+            </>
+          ) : null,
         // The desktop-managed guidance is already the description; the action
         // slot would only repeat it.
         actions:
+          updateInProgress ||
+          !versionMismatch ||
           versionMismatchSelfUpdate === "desktop-managed" ? undefined : (
             <ServerUpdateAction
-              environmentId={versionMismatchEnvironmentId}
+              environmentId={serverUpdateEnvironmentId}
               serverLabel={versionMismatchServerLabel}
               selfUpdate={versionMismatchSelfUpdate}
               targetVersion={versionMismatch.clientVersion}
+              {...(updateFailed ? { label: "Retry update" } : {})}
             />
           ),
-        dismissLabel: "Dismiss version mismatch warning",
-        onDismiss: () => {
-          dismissVersionMismatch(versionMismatchDismissKey);
-          setDismissedVersionMismatchKey(versionMismatchDismissKey);
-        },
+        ...(updateInProgress || updateFailed || !versionMismatchDismissKey
+          ? {}
+          : {
+              dismissLabel: "Dismiss version mismatch warning",
+              onDismiss: () => {
+                dismissVersionMismatch(versionMismatchDismissKey);
+                setDismissedVersionMismatchKey(versionMismatchDismissKey);
+              },
+            }),
       });
     }
     return items;
@@ -1960,9 +1982,10 @@ function ChatViewContent(props: ChatViewProps) {
     navigate,
     setDismissedVersionMismatchKey,
     showVersionMismatchBanner,
+    serverUpdateState,
     versionMismatch,
     versionMismatchDismissKey,
-    versionMismatchEnvironmentId,
+    serverUpdateEnvironmentId,
     versionMismatchSelfUpdate,
     versionMismatchServerLabel,
   ]);
diff --git a/apps/web/src/components/ServerUpdateAction.test.tsx b/apps/web/src/components/ServerUpdateAction.test.tsx
index c0ba1c693d4..17e44b8bae6 100644
--- a/apps/web/src/components/ServerUpdateAction.test.tsx
+++ b/apps/web/src/components/ServerUpdateAction.test.tsx
@@ -1,71 +1,15 @@
-import type { Dispatch, ReactElement, SetStateAction } from "react";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+import type { ReactElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import type { EnvironmentId } from "@t3tools/contracts";
 import * as Cause from "effect/Cause";
 import { AsyncResult } from "effect/unstable/reactivity";
-import type { EnvironmentId } from "@t3tools/contracts";
+import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
 
 const testState = vi.hoisted(() => ({
   updateServer: vi.fn(),
   toast: vi.fn(),
 }));
 
-const hooks = vi.hoisted(() => {
-  let cursor = 0;
-  let slots: unknown[] = [];
-  const nextIndex = () => cursor++;
-
-  return {
-    beginRender() {
-      cursor = 0;
-    },
-    reset() {
-      cursor = 0;
-      slots = [];
-    },
-    useEffect() {
-      nextIndex();
-    },
-    useMemoCache(size: number): unknown[] {
-      const index = nextIndex();
-      if (!slots[index]) {
-        slots[index] = Array.from({ length: size }, () => Symbol.for("react.memo_cache_sentinel"));
-      }
-      return slots[index] as unknown[];
-    },
-    useRef<T>(initialValue: T): { current: T } {
-      const index = nextIndex();
-      if (!slots[index]) {
-        slots[index] = { current: initialValue };
-      }
-      return slots[index] as { current: T };
-    },
-    useState<T>(initialValue: T | (() => T)): [T, Dispatch<SetStateAction<T>>] {
-      const index = nextIndex();
-      if (index >= slots.length) {
-        slots[index] =
-          typeof initialValue === "function" ? (initialValue as () => T)() : initialValue;
-      }
-      const setValue: Dispatch<SetStateAction<T>> = (nextValue) => {
-        const previous = slots[index] as T;
-        slots[index] =
-          typeof nextValue === "function" ? (nextValue as (value: T) => T)(previous) : nextValue;
-      };
-      return [slots[index] as T, setValue];
-    },
-  };
-});
-
-vi.mock("react", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("react")>();
-  return {
-    ...actual,
-    useEffect: hooks.useEffect,
-    useRef: hooks.useRef,
-    useState: hooks.useState,
-  };
-});
-
-vi.mock("react/compiler-runtime", () => ({ c: hooks.useMemoCache }));
 vi.mock("~/hooks/useCopyToClipboard", () => ({
   useCopyToClipboard: () => ({ copyToClipboard: vi.fn() }),
 }));
@@ -79,120 +23,123 @@ vi.mock("./ui/toast", () => ({
   toastManager: { add: testState.toast },
 }));
 
-import { ServerUpdateAction } from "./ServerUpdateAction";
+import { ServerUpdateAction, ServerUpdateProgress } from "./ServerUpdateAction";
 
 type ActionElement = ReactElement<{
-  readonly disabled?: boolean;
   readonly onClick?: () => void;
 }>;
 
 function renderAction(): ActionElement {
-  hooks.beginRender();
   return ServerUpdateAction({
     environmentId: "env-test" as EnvironmentId,
     serverLabel: "Test server",
     selfUpdate: "boot-service",
-    targetVersion: "0.0.29",
+    targetVersion: "0.0.31",
   }) as ActionElement;
 }
 
-function deferred<T>() {
-  let resolve!: (value: T) => void;
-  const promise = new Promise<T>((complete) => {
-    resolve = complete;
-  });
-  return { promise, resolve };
-}
-
 async function flushPromises(): Promise<void> {
   await Promise.resolve();
   await Promise.resolve();
-  await Promise.resolve();
-  await Promise.resolve();
-  await Promise.resolve();
 }
 
 describe("ServerUpdateAction", () => {
   beforeEach(() => {
-    vi.useFakeTimers();
-    hooks.reset();
     testState.updateServer.mockReset();
     testState.toast.mockReset();
   });
 
-  afterEach(() => {
-    vi.useRealTimers();
-  });
-
-  it("starts a fresh reconnect timeout after a long install succeeds", async () => {
-    const update =
-      deferred<
-        ReturnType<typeof AsyncResult.success<{ targetVersion: string; method: "boot-service" }>>
-      >();
-    testState.updateServer.mockReturnValue(update.promise);
+  it("reports success only after the shared update flow reconnects", async () => {
+    testState.updateServer.mockResolvedValue(
+      AsyncResult.success({ targetVersion: "0.0.31", method: "boot-service" as const }),
+    );
 
     renderAction().props.onClick?.();
-    expect(renderAction().props.disabled).toBe(true);
-
-    await vi.advanceTimersByTimeAsync(11 * 60_000);
-    update.resolve(
-      AsyncResult.success({
-        targetVersion: "0.0.29",
-        method: "boot-service",
-      }),
-    );
     await flushPromises();
 
-    // The click-based deadline would have fired by now. Success gets a fresh
-    // twelve-minute reconnect window, so the action remains disabled.
-    await vi.advanceTimersByTimeAsync(2 * 60_000);
-    expect(renderAction().props.disabled).toBe(true);
-    expect(testState.toast).not.toHaveBeenCalledWith(
-      expect.objectContaining({ title: "Server update timed out" }),
-    );
-
-    await vi.advanceTimersByTimeAsync(10 * 60_000);
-    expect(renderAction().props.disabled).not.toBe(true);
-    expect(testState.toast).toHaveBeenCalledWith(
-      expect.objectContaining({ title: "Server update timed out" }),
-    );
+    expect(testState.updateServer).toHaveBeenCalledWith({
+      environmentId: "env-test",
+      input: { targetVersion: "0.0.31" },
+    });
+    expect(testState.toast).toHaveBeenCalledWith({
+      type: "success",
+      title: "Test server updated",
+      description: "Reconnected on t3@0.0.31.",
+    });
   });
 
-  it("does not let an expired request clear a newer retry", async () => {
-    const first = deferred<ReturnType<typeof AsyncResult.failure>>();
-    const retry =
-      deferred<
-        ReturnType<typeof AsyncResult.success<{ targetVersion: string; method: "boot-service" }>>
-      >();
-    testState.updateServer.mockReturnValueOnce(first.promise).mockReturnValueOnce(retry.promise);
-
-    renderAction().props.onClick?.();
-    await vi.advanceTimersByTimeAsync(12 * 60_000);
-    expect(renderAction().props.disabled).not.toBe(true);
-
-    renderAction().props.onClick?.();
-    expect(renderAction().props.disabled).toBe(true);
-
-    first.resolve(AsyncResult.failure(Cause.fail(new Error("first request failed late"))));
-    await flushPromises();
+  it("reports one result when the update action is double-clicked", async () => {
+    let finishUpdate: (() => void) | undefined;
+    testState.updateServer.mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          finishUpdate = () =>
+            resolve(
+              AsyncResult.success({ targetVersion: "0.0.31", method: "boot-service" as const }),
+            );
+        }),
+    );
 
-    expect(renderAction().props.disabled).toBe(true);
-    expect(testState.updateServer).toHaveBeenCalledTimes(2);
+    const action = renderAction();
+    action.props.onClick?.();
+    action.props.onClick?.();
 
-    retry.resolve(AsyncResult.success({ targetVersion: "0.0.29", method: "boot-service" }));
+    expect(testState.updateServer).toHaveBeenCalledTimes(1);
+    finishUpdate?.();
     await flushPromises();
-    expect(renderAction().props.disabled).toBe(true);
+    expect(testState.toast).toHaveBeenCalledTimes(1);
   });
 
-  it("quietly releases the action when a restart RPC is interrupted", async () => {
+  it("quietly releases the action when the operation is interrupted", async () => {
     testState.updateServer.mockResolvedValue(AsyncResult.failure(Cause.interrupt()));
 
     renderAction().props.onClick?.();
     await flushPromises();
 
-    expect(renderAction().props.disabled).not.toBe(true);
-    expect(testState.toast).not.toHaveBeenCalledWith(
-      expect.objectContaining({ title: "Server update failed" }),
+    expect(testState.toast).not.toHaveBeenCalled();
+  });
+});
+
+describe("ServerUpdateProgress", () => {
+  it("renders the chosen horizontal step rail without an animated spinner", () => {
+    const markup = renderToStaticMarkup(
+      <ServerUpdateProgress
+        fromVersion="0.0.30"
+        serverLabel="bb-1"
+        state={{
+          status: "running",
+          stage: "resuming",
+          fromVersion: "0.0.30",
+          targetVersion: "0.0.31",
+        }}
+      />,
+    );
+
+    expect(markup).toContain("0.0.30");
+    expect(markup).toContain("0.0.31");
+    expect(markup).toContain("Download");
+    expect(markup).toContain("Install");
+    expect(markup).toContain("Resume");
+    expect(markup).toContain("Waiting for bb-1 to accept commands.");
+    expect(markup).not.toContain("animate-spin");
+  });
+
+  it("keeps the failed stage visible with its retryable error", () => {
+    const markup = renderToStaticMarkup(
+      <ServerUpdateProgress
+        fromVersion="0.0.30"
+        serverLabel="bb-1"
+        state={{
+          status: "failed",
+          stage: "installing",
+          fromVersion: "0.0.30",
+          targetVersion: "0.0.31",
+          message: "The package could not be verified.",
+        }}
+      />,
     );
+
+    expect(markup).toContain('role="alert"');
+    expect(markup).toContain("The package could not be verified.");
   });
 });
diff --git a/apps/web/src/components/ServerUpdateAction.tsx b/apps/web/src/components/ServerUpdateAction.tsx
index 5e82c4e4d93..929ea2e56c7 100644
--- a/apps/web/src/components/ServerUpdateAction.tsx
+++ b/apps/web/src/components/ServerUpdateAction.tsx
@@ -1,55 +1,147 @@
-import { useEffect, useRef, useState } from "react";
 import type { EnvironmentId, ServerSelfUpdateCapability } from "@t3tools/contracts";
+import type { ServerUpdateState } from "@t3tools/client-runtime/state/server";
 import {
   isAtomCommandInterrupted,
   squashAtomCommandFailure,
 } from "@t3tools/client-runtime/state/runtime";
+import { CheckIcon } from "lucide-react";
 
 import { useCopyToClipboard } from "~/hooks/useCopyToClipboard";
+import { cn } from "~/lib/utils";
 import { serverEnvironment } from "~/state/server";
 import { useAtomCommand } from "~/state/use-atom-command";
 import { manualServerUpdateCommand } from "~/versionSkew";
 import { Button } from "./ui/button";
-import { Spinner } from "./ui/spinner";
 import { toastManager } from "./ui/toast";
 
-/**
- * The npm install on the server side is capped at 10 minutes; expire the
- * spinner a bit beyond that so a dead transport never strands a disabled
- * button, while a legitimately slow install is never cut off.
- */
-const UPDATE_PENDING_EXPIRY_MS = 12 * 60_000;
+const UPDATE_STEPS = [
+  { stage: "downloading", label: "Download" },
+  { stage: "installing", label: "Install" },
+  { stage: "resuming", label: "Resume" },
+] as const;
+const pendingUpdateEnvironmentIds = new Set<EnvironmentId>();
 
 function updateFailureMessage(error: unknown): string {
   return error instanceof Error ? error.message : "Server update failed.";
 }
 
+function updateStatusCopy(
+  state: Exclude<ServerUpdateState, { status: "idle" }>,
+  serverLabel: string,
+): string {
+  if (state.status === "failed") {
+    return state.message;
+  }
+  switch (state.stage) {
+    case "downloading":
+      return "Downloading the matching server version.";
+    case "installing":
+      return `Installing and verifying t3@${state.targetVersion}.`;
+    case "resuming":
+      return `Waiting for ${serverLabel} to accept commands.`;
+  }
+}
+
+export function ServerUpdateProgress({
+  fromVersion,
+  serverLabel,
+  state,
+}: {
+  readonly fromVersion: string;
+  readonly serverLabel: string;
+  readonly state: Exclude<ServerUpdateState, { status: "idle" }>;
+}) {
+  const currentIndex = UPDATE_STEPS.findIndex(({ stage }) => stage === state.stage);
+
+  return (
+    <div className="mt-1 min-w-0 space-y-2.5">
+      <p className="text-xs text-muted-foreground">
+        {fromVersion} <span aria-hidden="true">→</span> {state.targetVersion}
+      </p>
+      <ol className="flex min-w-0 items-center" aria-label="Server update progress">
+        {UPDATE_STEPS.map((step, index) => {
+          const complete = index < currentIndex;
+          const current = index === currentIndex;
+          const failed = current && state.status === "failed";
+          return (
+            <li
+              key={step.stage}
+              className={cn(
+                "flex min-w-0 items-center text-xs font-medium",
+                index < UPDATE_STEPS.length - 1 ? "flex-1" : null,
+                complete
+                  ? "text-success"
+                  : failed
+                    ? "text-destructive"
+                    : current
+                      ? "text-primary"
+                      : "text-muted-foreground/60",
+              )}
+              aria-current={current && state.status === "running" ? "step" : undefined}
+            >
+              <span
+                className={cn(
+                  "grid size-4 shrink-0 place-items-center rounded-full border",
+                  complete
+                    ? "border-success bg-success text-success-foreground"
+                    : failed
+                      ? "border-destructive bg-destructive text-destructive-foreground"
+                      : current
+                        ? "border-primary bg-primary text-primary-foreground"
+                        : "border-muted-foreground/35",
+                )}
+                aria-hidden="true"
+              >
+                {complete ? <CheckIcon className="size-3" strokeWidth={3} /> : null}
+              </span>
+              <span className="ml-1.5 truncate">{step.label}</span>
+              {index < UPDATE_STEPS.length - 1 ? (
+                <span
+                  className={cn(
+                    "mx-2 h-px min-w-3 flex-1",
+                    complete ? "bg-success/60" : "bg-border",
+                  )}
+                  aria-hidden="true"
+                />
+              ) : null}
+            </li>
+          );
+        })}
+      </ol>
+      <p
+        className={cn(
+          "text-xs",
+          state.status === "failed" ? "text-destructive" : "text-muted-foreground",
+        )}
+        role={state.status === "failed" ? "alert" : "status"}
+      >
+        {updateStatusCopy(state, serverLabel)}
+      </p>
+    </div>
+  );
+}
+
 /**
- * The call-to-action for a version-skewed server, matched to the update path
- * it advertises: a one-click install-and-restart for servers that can update
- * themselves, an update-the-desktop-app hint for desktop-managed backends
- * (running `npx t3` there would start a second server, not update this one),
- * and copying the manual relaunch command for everything else — so the skew
- * warning always offers a way out.
+ * Offers the update path advertised by a version-skewed server. Self-updates
+ * delegate their full lifecycle to client-runtime so this component can
+ * unmount during reconnect without losing operation state.
  */
 export function ServerUpdateAction({
   environmentId,
   serverLabel,
   selfUpdate,
   targetVersion,
+  label = "Update server",
 }: {
   readonly environmentId: EnvironmentId;
   readonly serverLabel: string;
   readonly selfUpdate: ServerSelfUpdateCapability | null;
   readonly targetVersion: string;
+  readonly label?: string;
 }) {
   const updateServer = useAtomCommand(serverEnvironment.updateServer, {
     reportFailure: false,
   });
-  const [pending, setPending] = useState(false);
-  const inFlightRef = useRef(false);
-  const attemptRef = useRef(0);
-  const expiryRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const { copyToClipboard } = useCopyToClipboard<{ command: string }>({
     target: "update command",
     onCopy: ({ command }) => {
@@ -68,107 +160,35 @@ export function ServerUpdateAction({
     },
   });
 
-  useEffect(
-    () => () => {
-      if (expiryRef.current !== null) {
-        clearTimeout(expiryRef.current);
-        expiryRef.current = null;
-      }
-      attemptRef.current += 1;
-      inFlightRef.current = false;
-    },
-    [],
-  );
-
-  const handleUpdate = () => {
-    // Synchronous re-entry guard: setPending is async, so a rapid
-    // double-click would otherwise dispatch two updates.
-    if (inFlightRef.current) {
+  const handleUpdate = async () => {
+    if (pendingUpdateEnvironmentIds.has(environmentId)) {
       return;
     }
-    inFlightRef.current = true;
-    const attempt = attemptRef.current + 1;
-    attemptRef.current = attempt;
-    const ownsAttempt = () => attemptRef.current === attempt;
-    setPending(true);
-    const armExpiry = () => {
-      const expiry = setTimeout(() => {
-        if (!ownsAttempt()) return;
-        expiryRef.current = null;
-        attemptRef.current += 1;
-        inFlightRef.current = false;
-        setPending(false);
-        toastManager.add({
-          type: "error",
-          title: "Server update timed out",
-          description: "The update may still be running on the server — check again in a minute.",
-        });
-      }, UPDATE_PENDING_EXPIRY_MS);
-      expiryRef.current = expiry;
-      return expiry;
-    };
-    let expiry = armExpiry();
-    let restartAccepted = false;
-    const keepPendingForRestart = () => {
-      restartAccepted = true;
-      if (expiryRef.current === expiry) {
-        clearTimeout(expiry);
-        expiry = armExpiry();
-      }
-    };
-    void Promise.resolve()
-      .then(() =>
-        updateServer({
-          environmentId,
-          input: { targetVersion },
-        }),
-      )
-      .then((result) => {
-        if (!ownsAttempt()) return;
-        if (result._tag === "Failure") {
-          // An interrupt may be the expected boot-service disconnect, but it
-          // can also be client-side cancellation before restart was accepted.
-          // Release the action quietly; version sync will remove it when a
-          // successful replacement reconnects.
-          if (isAtomCommandInterrupted(result)) {
-            return;
-          }
-          toastManager.add({
-            type: "error",
-            title: "Server update failed",
-            description: updateFailureMessage(squashAtomCommandFailure(result)),
-          });
+    pendingUpdateEnvironmentIds.add(environmentId);
+    try {
+      const result = await updateServer({
+        environmentId,
+        input: { targetVersion },
+      });
+      if (result._tag === "Failure") {
+        if (isAtomCommandInterrupted(result)) {
           return;
         }
-        keepPendingForRestart();
-        // Installation can legitimately consume most of the request window.
-        // Give restart/reconnect a fresh full window after the server accepts
-        // the handoff instead of expiring based on the original click time.
-        toastManager.add({
-          type: "success",
-          title: `Updating ${serverLabel}`,
-          description: `t3@${result.value.targetVersion} is installed — the server is restarting and will reconnect shortly.`,
-        });
-      })
-      .catch((error: unknown) => {
-        if (!ownsAttempt()) return;
         toastManager.add({
           type: "error",
           title: "Server update failed",
-          description: updateFailureMessage(error),
+          description: updateFailureMessage(squashAtomCommandFailure(result)),
         });
-      })
-      .finally(() => {
-        // A successful RPC only acknowledges that restart is scheduled. Keep
-        // the action disabled until version sync unmounts it, or until the
-        // safety expiry reports that reconnection never arrived.
-        if (restartAccepted || !ownsAttempt() || expiryRef.current !== expiry) return;
-        expiryRef.current = null;
-        clearTimeout(expiry);
-        attemptRef.current += 1;
-        inFlightRef.current = false;
-        setPending(false);
+        return;
+      }
+      toastManager.add({
+        type: "success",
+        title: `${serverLabel} updated`,
+        description: `Reconnected on t3@${result.value.targetVersion}.`,
       });
+    } finally {
+      pendingUpdateEnvironmentIds.delete(environmentId);
+    }
   };
 
   if (selfUpdate === "desktop-managed") {
@@ -188,14 +208,9 @@ export function ServerUpdateAction({
     );
   }
 
-  return pending ? (
-    <Button size="xs" disabled>
-      <Spinner className="size-3.5" />
-      Updating...
-    </Button>
-  ) : (
+  return (
     <Button size="xs" onClick={() => void handleUpdate()}>
-      Update server
+      {label}
     </Button>
   );
 }
diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index 632221098d2..98ab7a128de 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -7,6 +7,7 @@ import {
   TerminalIcon,
   TriangleAlertIcon,
 } from "lucide-react";
+import { useAtomValue } from "@effect/atom-react";
 import { type ReactNode, memo, useCallback, useMemo, useState } from "react";
 import {
   AuthAccessReadScope,
@@ -131,8 +132,9 @@ import {
   usePrimaryEnvironment,
 } from "~/state/environments";
 import { useAtomCommand } from "../../state/use-atom-command";
+import { serverEnvironment } from "~/state/server";
 import { ConnectionStatusDot } from "../ConnectionStatusDot";
-import { ServerUpdateAction } from "../ServerUpdateAction";
+import { ServerUpdateAction, ServerUpdateProgress } from "../ServerUpdateAction";
 import { CloudEnvironmentConnectRows } from "../cloud/CloudEnvironmentConnectList";
 import { ITEM_ROW_CLASSNAME, ITEM_ROW_INNER_CLASSNAME } from "./itemRows";
 
@@ -1389,6 +1391,9 @@ function SavedBackendListRow({
     [copyTraceIdToClipboard],
   );
   const versionMismatch = resolveServerConfigVersionMismatch(environment.serverConfig);
+  const serverUpdateState = useAtomValue(serverEnvironment.updateStateAtom(environmentId));
+  const resumingServerUpdate =
+    serverUpdateState.status === "running" && serverUpdateState.stage === "resuming";
   const sshTarget =
     environment.entry.target._tag === "SshConnectionTarget" &&
     Option.isSome(environment.entry.profile) &&
@@ -1425,14 +1430,22 @@ function SavedBackendListRow({
           {metadataBits.length > 0 ? (
             <p className="text-xs text-muted-foreground">{metadataBits.join(" · ")}</p>
           ) : null}
-          {versionMismatch ? (
+          {serverUpdateState.status !== "idle" ? (
+            <div className="max-w-md">
+              <ServerUpdateProgress
+                fromVersion={serverUpdateState.fromVersion}
+                serverLabel={`${environment.label} server`}
+                state={serverUpdateState}
+              />
+            </div>
+          ) : versionMismatch ? (
             <p className="flex items-center gap-1 text-warning text-xs">
               <TriangleAlertIcon className="size-3.5 shrink-0" />
               Version drift: client {versionMismatch.clientVersion}, server{" "}
               {versionMismatch.serverVersion}.
             </p>
           ) : null}
-          {environment.connection.error ? (
+          {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>
               {errorTraceId ? (
@@ -1448,12 +1461,14 @@ function SavedBackendListRow({
           ) : null}
         </div>
         <div className="flex w-full shrink-0 items-center gap-2 sm:w-auto sm:justify-end">
-          {versionMismatch ? (
+          {versionMismatch &&
+          (serverUpdateState.status === "idle" || serverUpdateState.status === "failed") ? (
             <ServerUpdateAction
               environmentId={environmentId}
               serverLabel={`${environment.label} server`}
               selfUpdate={resolveServerSelfUpdateCapability(environment.serverConfig)}
               targetVersion={versionMismatch.clientVersion}
+              label={serverUpdateState.status === "failed" ? "Retry update" : "Update server"}
             />
           ) : null}
           {isWslEnvironment ? (
@@ -1834,6 +1849,9 @@ export function ConnectionsSettings() {
   >(null);
   const primaryServerConfig = primaryEnvironment?.serverConfig ?? null;
   const primaryVersionMismatch = resolveServerConfigVersionMismatch(primaryServerConfig);
+  const primaryServerUpdateState = useAtomValue(
+    serverEnvironment.updateStateAtom(primaryEnvironmentId),
+  );
   const [isAdvertisedEndpointListExpanded, setIsAdvertisedEndpointListExpanded] = useState(false);
   const defaultAdvertisedEndpointKey = useUiStateStore(
     (state) => state.defaultAdvertisedEndpointKey,
@@ -2980,24 +2998,43 @@ export function ConnectionsSettings() {
       {canManageLocalBackend ? (
         <>
           <SettingsSection title="This environment">
-            {primaryVersionMismatch ? (
+            {primaryVersionMismatch || primaryServerUpdateState.status !== "idle" ? (
               <SettingsRow
-                title="Version drift"
+                title={
+                  primaryServerUpdateState.status === "failed"
+                    ? "Update failed"
+                    : primaryServerUpdateState.status === "running"
+                      ? "Updating server"
+                      : "Version drift"
+                }
                 description={
-                  <span className="flex items-center gap-1 text-warning">
-                    <TriangleAlertIcon className="size-3.5 shrink-0" />
-                    Client {primaryVersionMismatch.clientVersion}, server{" "}
-                    {primaryVersionMismatch.serverVersion}. Sync them if RPC calls or reconnects
-                    fail.
-                  </span>
+                  primaryServerUpdateState.status !== "idle" ? (
+                    <ServerUpdateProgress
+                      fromVersion={primaryServerUpdateState.fromVersion}
+                      serverLabel={primaryEnvironment?.label ?? "this server"}
+                      state={primaryServerUpdateState}
+                    />
+                  ) : primaryVersionMismatch ? (
+                    <span className="flex items-center gap-1 text-warning">
+                      <TriangleAlertIcon className="size-3.5 shrink-0" />
+                      Client {primaryVersionMismatch.clientVersion}, server{" "}
+                      {primaryVersionMismatch.serverVersion}. Sync them if RPC calls or reconnects
+                      fail.
+                    </span>
+                  ) : null
                 }
                 control={
-                  primaryEnvironmentId !== null ? (
+                  primaryVersionMismatch &&
+                  primaryEnvironmentId !== null &&
+                  primaryServerUpdateState.status !== "running" ? (
                     <ServerUpdateAction
                       environmentId={primaryEnvironmentId}
                       serverLabel={primaryEnvironment?.label ?? "this server"}
                       selfUpdate={resolveServerSelfUpdateCapability(primaryServerConfig)}
                       targetVersion={primaryVersionMismatch.clientVersion}
+                      {...(primaryServerUpdateState.status === "failed"
+                        ? { label: "Retry update" }
+                        : {})}
                     />
                   ) : undefined
                 }
diff --git a/docs/architecture/server-updates.md b/docs/architecture/server-updates.md
index 2e8c9d6ef61..981f4e1eb42 100644
--- a/docs/architecture/server-updates.md
+++ b/docs/architecture/server-updates.md
@@ -13,8 +13,9 @@ The feature has three boundaries:
 ## Detection and Presentation
 
 `ExecutionEnvironmentDescriptor` includes the server version and an optional
-`capabilities.serverSelfUpdate` value. The client compares that version with `APP_VERSION` after
-loading server config.
+`capabilities.serverSelfUpdate` value. Progress-capable servers also advertise
+`capabilities.serverSelfUpdateProgress`. The client compares the server version with `APP_VERSION`
+after loading server config.
 
 The optional capability is intentionally backward compatible. An older server does not know about
 the field, so a missing value means the client must offer a manual relaunch instead of sending an
@@ -28,6 +29,10 @@ The shared `ServerUpdateAction` is rendered in both user-facing version-drift su
 Both surfaces target the client's exact version. When the reconnected server reports that version,
 the mismatch and action disappear.
 
+The operation state lives in `packages/client-runtime`, keyed by environment. Both web surfaces read
+the same `downloading`, `installing`, or `resuming` state, so route changes do not own or cancel the
+operation.
+
 ## Capability Selection
 
 The server resolves its capability once at startup and publishes it in the environment descriptor.
@@ -51,20 +56,25 @@ flowchart TD
     A[Client detects different versions] --> B{Advertised update path}
     B -->|desktop-managed| C[Update desktop app on server machine]
     B -->|missing| D[Copy exact manual relaunch command]
-    B -->|boot-service or respawn| E[server.updateServer]
-    E --> F[Install exact t3 version in pinned runtime]
-    F --> G[Run version preflight]
-    G -->|fails| H[Remove failed runtime and keep current server]
-    G -->|passes| I{Handoff method}
-    I -->|boot-service| J[Rewrite and restart T3 systemd unit]
-    I -->|respawn| K[Start delayed replacement and exit current process]
-    J --> L[Client reconnects]
-    K --> L
+    B -->|boot-service or respawn| E{Progress capability}
+    E -->|present| F[server.updateServerWithProgress]
+    E -->|missing| G[server.updateServer fallback]
+    F --> H[Download exact t3 version]
+    G --> H
+    H --> I[Install and run version preflight]
+    I -->|fails| J[Remove failed runtime and keep current server]
+    I -->|passes| K{Handoff method}
+    K -->|boot-service| L[Rewrite and restart T3 systemd unit]
+    K -->|respawn| M[Start delayed replacement and exit current process]
+    L --> N[Reconnect with fresh backoff]
+    M --> N
+    N --> O[Replacement publishes ready at target version]
 ```
 
-`server.updateServer` requires the environment's `orchestration:operate` authorization scope. Its
+Both update RPCs require the environment's `orchestration:operate` authorization scope. Their
 payload accepts only an exact npm version, including an exact prerelease version; dist-tags such as
-`latest` and `nightly` are rejected.
+`latest` and `nightly` are rejected. The unary `server.updateServer` method remains available so a
+new client can still repair skew with an older server.
 
 The update service permits one update at a time. It installs `t3@<version>` under
 `<baseDir>/runtime/versions/<version>` and writes an install-complete sentinel only after npm exits
@@ -89,20 +99,20 @@ authorization; it does not uninstall the host service.
 ## Process Handoff
 
 For `boot-service`, the server atomically rewrites the T3-managed user unit to point at the verified
-runtime, reloads systemd, and restarts the unit. Reload and restart failures restore the previous
-unit before returning an error.
+runtime and reloads systemd. It acknowledges the handoff, then restarts the unit after the same
+short grace period used by foreground respawn. A rejected deferred restart restores the previous
+unit and is logged by the still-running process.
 
 For `respawn`, the server starts a detached, delayed replacement that replays the original CLI
 arguments. It then acknowledges the request and schedules the current process to exit. The delays
 give the acknowledgement time to cross direct or relayed connections before the socket closes.
 
-There is no separate progress stream. The update request remains pending while npm installs and the
-client shows a disabled update action. A restart can interrupt the request normally; the connection
-runtime keeps the environment registered and reconnects through its usual retry path. After an
-acknowledged foreground handoff, the UI keeps the action pending until version sync removes it or a
-safety timeout releases it. If a boot-service restart closes the connection before acknowledgement,
-the UI releases the interrupted action without reporting a false update failure and lets reconnect
-and the next version check determine the result.
+Progress-capable servers emit `downloading` before installing the pinned runtime and `installing`
+before preflight and handoff. A terminal stream event acknowledges that restart is scheduled. The
+client then enters `resuming`, waits for the replacement lifecycle stream to publish `ready` with
+the target version, and only then completes the operation. It watches for the intentional
+disconnect's first backoff state and requests one fresh retry, which clears historical backoff debt
+without adding a separate reconnect loop.
 
 ## Release Invariant
 
diff --git a/docs/user/server-updates.md b/docs/user/server-updates.md
index 6a8e33977b7..27577c6f948 100644
--- a/docs/user/server-updates.md
+++ b/docs/user/server-updates.md
@@ -31,6 +31,11 @@ The update does not remove saved threads, settings, or project files.
 The available action depends on how that server was started. T3 Code does not update connected
 servers silently in the background.
 
+After selecting **Update server**, the warning becomes a three-step progress rail:
+**Download**, **Install**, and **Resume**. The same progress appears in the conversation and in
+Connections, so navigating between them does not lose the update. A failed step remains visible
+with its error and an option to retry.
+
 If the server uses the T3 Code background service, you can also update it directly on the host:
 
 ```sh
@@ -42,11 +47,11 @@ commands.
 
 ## After the Update
 
-Keep the web or desktop app open while the server restarts. When it reconnects with the matching
-version, the warning and update action disappear.
+Keep the web or desktop app open while the server restarts. The update completes only after the
+replacement server reports the requested version and is ready to accept commands. The warning and
+progress rail then disappear.
 
-If the client reports a timeout, the server may still be finishing the update. Wait a minute, then
-reconnect or open **Settings** → **Connections** again. If the warning remains:
+If a step 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.
diff --git a/packages/client-runtime/src/connection/supervisor.test.ts b/packages/client-runtime/src/connection/supervisor.test.ts
index b31ea9b4fc9..a925859049f 100644
--- a/packages/client-runtime/src/connection/supervisor.test.ts
+++ b/packages/client-runtime/src/connection/supervisor.test.ts
@@ -513,6 +513,43 @@ describe("EnvironmentSupervisor", () => {
     }),
   );
 
+  it.effect("explicit retry starts a fresh backoff sequence", () =>
+    Effect.gen(function* () {
+      const harness = yield* makeHarness({
+        prepare: () => Effect.fail(transient()),
+      });
+      const supervisor = yield* EnvironmentSupervisor.make(TARGET_ENTRY, {
+        initiallyDesired: true,
+      }).pipe(Effect.provide(harness.dependencies));
+
+      yield* awaitState(
+        supervisor.state,
+        (state) => state.phase === "backoff" && state.attempt === 1,
+      );
+      yield* TestClock.adjust("1 second");
+      yield* eventuallyState(
+        supervisor.state,
+        (state) => state.phase === "backoff" && state.attempt === 2,
+      );
+
+      yield* supervisor.retryNow;
+      yield* eventuallyState(
+        supervisor.state,
+        (state) => state.phase === "backoff" && state.attempt === 1,
+      );
+      expect(yield* Ref.get(harness.prepareCount)).toBe(3);
+
+      yield* TestClock.adjust("999 millis");
+      expect(yield* Ref.get(harness.prepareCount)).toBe(3);
+      yield* TestClock.adjust("1 milli");
+      yield* eventuallyState(
+        supervisor.state,
+        (state) => state.phase === "backoff" && state.attempt === 2,
+      );
+      expect(yield* Ref.get(harness.prepareCount)).toBe(4);
+    }).pipe(Effect.provide(TestClock.layer())),
+  );
+
   it.effect("keeps blocked failures idle until an external signal requests another attempt", () =>
     Effect.gen(function* () {
       const harness = yield* makeHarness({
diff --git a/packages/client-runtime/src/connection/supervisor.ts b/packages/client-runtime/src/connection/supervisor.ts
index e4ac359e5b1..2a9c7519072 100644
--- a/packages/client-runtime/src/connection/supervisor.ts
+++ b/packages/client-runtime/src/connection/supervisor.ts
@@ -231,6 +231,7 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
   };
   const intent = yield* Ref.make(initialIntent);
   const signals = yield* Queue.unbounded<SupervisorSignal>();
+  const resetRetryState = yield* Ref.make(false);
   const state = yield* SubscriptionRef.make<SupervisorConnectionState>(
     !initialIntent.desired
       ? availableState(initialIntent, 0)
@@ -643,6 +644,11 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
     };
 
     for (;;) {
+      if (yield* Ref.getAndSet(resetRetryState, false)) {
+        failureCount = 0;
+        latestFailure = null;
+        pendingRetry = Option.none();
+      }
       const currentIntent = yield* Ref.get(intent);
       if (!currentIntent.desired) {
         resetRetryLadder();
@@ -763,7 +769,8 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
     Effect.withSpan("EnvironmentSupervisor.disconnect"),
   );
 
-  const retryNow = signal({ _tag: "RetryRequested" }).pipe(
+  const retryNow = Ref.set(resetRetryState, true).pipe(
+    Effect.andThen(signal({ _tag: "RetryRequested" })),
     Effect.withSpan("EnvironmentSupervisor.retryNow"),
   );
 
diff --git a/packages/client-runtime/src/rpc/client.ts b/packages/client-runtime/src/rpc/client.ts
index 8013a135896..bfe57a6c0dd 100644
--- a/packages/client-runtime/src/rpc/client.ts
+++ b/packages/client-runtime/src/rpc/client.ts
@@ -56,6 +56,7 @@ export type EnvironmentSubscriptionRpcTag =
 
 export type EnvironmentStreamCommandRpcTag =
   | typeof WS_METHODS.cloudInstallRelayClient
+  | typeof WS_METHODS.serverUpdateServerWithProgress
   | typeof WS_METHODS.gitRunStackedAction;
 
 export type EnvironmentStreamRpcTag =
@@ -80,7 +81,7 @@ export class EnvironmentRpcSubscriptionObserver extends Context.Reference<{
   }),
 }) {}
 
-const isRpcClientError = Schema.is(RpcClientError.RpcClientError);
+export const isRpcClientError = Schema.is(RpcClientError.RpcClientError);
 
 export type EnvironmentRpcInput<TTag extends EnvironmentRpcTag> = Parameters<RpcMethod<TTag>>[0];
 
diff --git a/packages/client-runtime/src/state/runtime.test.ts b/packages/client-runtime/src/state/runtime.test.ts
index 7584e55d52e..f36087ebf66 100644
--- a/packages/client-runtime/src/state/runtime.test.ts
+++ b/packages/client-runtime/src/state/runtime.test.ts
@@ -13,6 +13,7 @@ import {
   environmentRpcKey,
   createAtomCommandScheduler,
   createRuntimeCommand,
+  scheduleAtomCommandEffect,
   executeAtomCommand,
   executeAtomQuery,
   isAtomCommandInterrupted,
@@ -399,6 +400,54 @@ describe("runtime command runner", () => {
     registry.dispose();
   });
 
+  it.effect("releases a shared scheduler lane before the outer command finishes", () =>
+    Effect.gen(function* () {
+      const handoffStarted = Latch.makeUnsafe();
+      const handoffComplete = Latch.makeUnsafe();
+      const resumeComplete = Latch.makeUnsafe();
+      const runtime = Atom.runtime(Layer.empty);
+      const scheduler = createAtomCommandScheduler();
+      const concurrency = { mode: "serial" as const, key: () => "shared" };
+      const updateCommand = createRuntimeCommand(runtime, {
+        label: "test.update",
+        execute: (_input: void, registry) =>
+          scheduleAtomCommandEffect(
+            registry,
+            scheduler,
+            concurrency,
+            undefined,
+            Effect.sync(() => handoffStarted.openUnsafe()).pipe(
+              Effect.andThen(handoffComplete.await),
+            ),
+          ).pipe(Effect.andThen(resumeComplete.await)),
+      });
+      const configCommand = createRuntimeCommand(runtime, {
+        label: "test.config",
+        scheduler,
+        concurrency,
+        execute: () => Effect.succeed("configured"),
+      });
+      const registry = AtomRegistry.make();
+
+      const update = updateCommand.run(registry, undefined);
+      yield* handoffStarted.await;
+      const config = configCommand.run(registry, undefined);
+      handoffComplete.openUnsafe();
+
+      expect(yield* Effect.promise(() => config)).toMatchObject({
+        _tag: "Success",
+        value: "configured",
+        waiting: false,
+      });
+      resumeComplete.openUnsafe();
+      expect(yield* Effect.promise(() => update)).toMatchObject({
+        _tag: "Success",
+        waiting: false,
+      });
+      registry.dispose();
+    }),
+  );
+
   it("deduplicates single-flight commands by key", async () => {
     const latch = Latch.makeUnsafe();
     let executions = 0;
diff --git a/packages/client-runtime/src/state/runtime.ts b/packages/client-runtime/src/state/runtime.ts
index fb5e9a0ab55..0a00e919c4b 100644
--- a/packages/client-runtime/src/state/runtime.ts
+++ b/packages/client-runtime/src/state/runtime.ts
@@ -253,6 +253,28 @@ export function createAtomCommandScheduler(): AtomCommandScheduler {
   };
 }
 
+/** Runs one effect inside an existing command scheduler lane. */
+export function scheduleAtomCommandEffect<W, A, E, R>(
+  registry: AtomRegistry.AtomRegistry,
+  scheduler: AtomCommandScheduler,
+  concurrency: AtomCommandConcurrency<W>,
+  input: W,
+  effect: Effect.Effect<A, E, R>,
+): Effect.Effect<A, E, R> {
+  return Effect.gen(function* () {
+    const context = yield* Effect.context<R>();
+    const result = yield* Effect.promise((signal) =>
+      scheduler.schedule<W, A, E>(registry, concurrency, input, async () => {
+        const exit = await Effect.runPromiseExitWith(context)(effect, { signal });
+        return Exit.isSuccess(exit)
+          ? AsyncResult.success(exit.value)
+          : AsyncResult.failure(exit.cause);
+      }),
+    );
+    return result._tag === "Success" ? result.value : yield* Effect.failCause(result.cause);
+  });
+}
+
 export async function runAtomCommand<W, A, E>(
   registry: AtomRegistry.AtomRegistry,
   command: AtomCommand<W, A, E>,
diff --git a/packages/client-runtime/src/state/server.test.ts b/packages/client-runtime/src/state/server.test.ts
index ddc8813316f..12925a99867 100644
--- a/packages/client-runtime/src/state/server.test.ts
+++ b/packages/client-runtime/src/state/server.test.ts
@@ -6,11 +6,15 @@ import {
   WS_METHODS,
 } from "@t3tools/contracts";
 import { describe, expect, it } from "@effect/vitest";
+import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
 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 { RpcClientError } from "effect/unstable/rpc";
+import * as Socket from "effect/unstable/socket/Socket";
 
 import {
   AVAILABLE_CONNECTION_STATE,
@@ -24,8 +28,12 @@ import type { RpcSession } from "../rpc/session.ts";
 import {
   applyServerConfigProjection,
   makeEnvironmentServerConfigState,
+  isLegacyUpdateHandoffLoss,
   projectServerWelcome,
   resolveServerConfigValue,
+  resolveServerUpdateProgressResult,
+  serverUpdateStateForProgressEvent,
+  serverUpdateStateForServerVersion,
 } from "./server.ts";
 
 const CONFIG = {
@@ -62,6 +70,109 @@ function session(client: WsRpcProtocolClient): RpcSession {
 }
 
 describe("server state projection", () => {
+  it("only treats a legacy transport interruption as an unacknowledged handoff", () => {
+    expect(isLegacyUpdateHandoffLoss(Cause.interrupt(1))).toBe(true);
+    expect(
+      isLegacyUpdateHandoffLoss(
+        Cause.fail(
+          new RpcClientError.RpcClientError({
+            reason: new Socket.SocketCloseError({ code: 1006 }),
+          }),
+        ),
+      ),
+    ).toBe(true);
+    expect(
+      isLegacyUpdateHandoffLoss(
+        Cause.fail(
+          new RpcClientError.RpcClientError({
+            reason: new Socket.SocketOpenError({
+              kind: "Unknown",
+              cause: new Error("connection refused"),
+            }),
+          }),
+        ),
+      ),
+    ).toBe(false);
+    expect(
+      isLegacyUpdateHandoffLoss(
+        Cause.fail(
+          new RpcClientError.RpcClientError({
+            reason: new RpcClientError.RpcClientDefect({
+              message: "incompatible protocol",
+              cause: new Error("invalid response"),
+            }),
+          }),
+        ),
+      ),
+    ).toBe(false);
+    expect(isLegacyUpdateHandoffLoss(Cause.fail(new Error("Install failed.")))).toBe(false);
+  });
+
+  it.effect("resumes after the progress stream disconnects following completion", () => {
+    const result = {
+      targetVersion: "0.0.31",
+      method: "respawn" as const,
+    };
+    const disconnect = new RpcClientError.RpcClientError({
+      reason: new Socket.SocketCloseError({ code: 1006 }),
+    });
+
+    return Effect.gen(function* () {
+      const resumed = yield* resolveServerUpdateProgressResult(
+        result.targetVersion,
+        Option.some(result),
+        Exit.fail(disconnect),
+      );
+      expect(resumed).toEqual(result);
+    });
+  });
+
+  it("projects streamed update milestones into the shared operation state", () => {
+    expect(
+      serverUpdateStateForProgressEvent("0.0.30", "0.0.31", {
+        type: "progress",
+        stage: "installing",
+      }),
+    ).toEqual({
+      status: "running",
+      stage: "installing",
+      fromVersion: "0.0.30",
+      targetVersion: "0.0.31",
+    });
+    expect(
+      serverUpdateStateForProgressEvent("0.0.30", "0.0.31", {
+        type: "complete",
+        result: { targetVersion: "0.0.31", method: "respawn" },
+      }),
+    ).toEqual({
+      status: "running",
+      stage: "resuming",
+      fromVersion: "0.0.30",
+      targetVersion: "0.0.31",
+    });
+  });
+
+  it("keeps active update state and hides stale failures after a version change", () => {
+    const running = {
+      status: "running" as const,
+      stage: "resuming" as const,
+      fromVersion: "0.0.30",
+      targetVersion: "0.0.31",
+    };
+    const failed = {
+      status: "failed" as const,
+      stage: "installing" as const,
+      fromVersion: "0.0.30",
+      targetVersion: "0.0.31",
+      message: "Install failed.",
+    };
+
+    expect(serverUpdateStateForServerVersion(running, "0.0.31")).toBe(running);
+    expect(serverUpdateStateForServerVersion(failed, "0.0.30")).toBe(failed);
+    expect(serverUpdateStateForServerVersion(failed, null)).toBe(failed);
+    expect(serverUpdateStateForServerVersion(failed, "0.0.31")).toEqual({ status: "idle" });
+  });
+
   it("applies every config category to the projected snapshot", () => {
     const snapshot = applyServerConfigProjection(Option.none(), {
       version: 1,
@@ -100,9 +211,16 @@ describe("server state projection", () => {
   });
 
   it("prefers an active session config over cache until a live event arrives", () => {
-    const cached = { ...CONFIG, settings: { source: "cache" } } as unknown as ServerConfig;
-    const initial = { ...CONFIG, settings: { source: "session" } } as unknown as ServerConfig;
-    const live = { ...CONFIG, settings: { source: "live" } } as unknown as ServerConfig;
+    const config = (source: string, serverVersion: string) =>
+      ({
+        ...CONFIG,
+        environment: { serverVersion },
+        settings: { source },
+      }) as unknown as ServerConfig;
+    const cached = config("cache", "0.0.29");
+    const staleLive = config("stale-live", "0.0.29");
+    const initial = config("session", "0.0.30");
+    const live = config("live", "0.0.30");
 
     expect(
       resolveServerConfigValue(
@@ -114,6 +232,16 @@ describe("server state projection", () => {
         initial,
       ),
     ).toBe(initial);
+    expect(
+      resolveServerConfigValue(
+        {
+          config: staleLive,
+          latestEvent: snapshotEvent(staleLive),
+          source: "live",
+        },
+        initial,
+      ),
+    ).toBe(initial);
     expect(
       resolveServerConfigValue(
         {
diff --git a/packages/client-runtime/src/state/server.ts b/packages/client-runtime/src/state/server.ts
index 5f93a3edb6e..edd1893f739 100644
--- a/packages/client-runtime/src/state/server.ts
+++ b/packages/client-runtime/src/state/server.ts
@@ -3,13 +3,19 @@ import {
   type ServerConfig,
   type ServerConfigStreamEvent,
   type ServerLifecycleWelcomePayload,
+  type ServerSelfUpdateProgressEvent,
+  type ServerSelfUpdateResult,
   WS_METHODS,
 } from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
 import * as Option from "effect/Option";
 import * as Queue from "effect/Queue";
 import * as Ref from "effect/Ref";
 import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
 import * as Stream from "effect/Stream";
 import * as SubscriptionRef from "effect/SubscriptionRef";
 import { AsyncResult, Atom } from "effect/unstable/reactivity";
@@ -19,14 +25,148 @@ import {
   createEnvironmentRpcCommand,
   createEnvironmentRpcQueryAtomFamily,
   createEnvironmentRpcSubscriptionAtomFamily,
+  createRuntimeCommand,
+  scheduleAtomCommandEffect,
 } from "./runtime.ts";
-import type { EnvironmentRegistry } from "../connection/registry.ts";
+import { EnvironmentRegistry } from "../connection/registry.ts";
 import { EnvironmentSupervisor } from "../connection/supervisor.ts";
 import { safeErrorLogAttributes } from "../errors/safeLog.ts";
 import { EnvironmentCacheStore } from "../platform/persistence.ts";
-import { subscribe, type EnvironmentRpcInput } from "../rpc/client.ts";
+import {
+  isRpcClientError,
+  request,
+  runStream,
+  subscribe,
+  type EnvironmentRpcInput,
+} from "../rpc/client.ts";
 import { followStreamInEnvironment } from "./runtime.ts";
 
+export type ServerUpdateStage = "downloading" | "installing" | "resuming";
+
+export type ServerUpdateState =
+  | { readonly status: "idle" }
+  | {
+      readonly status: "running";
+      readonly stage: ServerUpdateStage;
+      readonly fromVersion: string;
+      readonly targetVersion: string;
+    }
+  | {
+      readonly status: "failed";
+      readonly stage: ServerUpdateStage;
+      readonly fromVersion: string;
+      readonly targetVersion: string;
+      readonly message: string;
+    };
+
+export interface ServerUpdateTarget {
+  readonly environmentId: EnvironmentId;
+  readonly input: EnvironmentRpcInput<typeof WS_METHODS.serverUpdateServer>;
+}
+
+const IDLE_SERVER_UPDATE_STATE: ServerUpdateState = { status: "idle" };
+const EMPTY_SERVER_UPDATE_STATE_ATOM = Atom.make<ServerUpdateState>(IDLE_SERVER_UPDATE_STATE).pipe(
+  Atom.withLabel("environment-data:server:update-state:empty"),
+);
+const serverUpdateStateAtom = Atom.family((environmentId: EnvironmentId) =>
+  Atom.make<ServerUpdateState>(IDLE_SERVER_UPDATE_STATE).pipe(
+    Atom.withLabel(`environment-data:server:update-state:${environmentId}`),
+  ),
+);
+
+export class ServerUpdateResumeTimeoutError extends Schema.TaggedErrorClass<ServerUpdateResumeTimeoutError>()(
+  "ServerUpdateResumeTimeoutError",
+  {
+    environmentId: Schema.String,
+    targetVersion: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `The server did not resume on t3@${this.targetVersion}.`;
+  }
+}
+
+export class ServerUpdateProgressIncompleteError extends Schema.TaggedErrorClass<ServerUpdateProgressIncompleteError>()(
+  "ServerUpdateProgressIncompleteError",
+  {
+    targetVersion: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `The t3@${this.targetVersion} update ended before the server accepted the restart.`;
+  }
+}
+
+export function serverUpdateStateForProgressEvent(
+  fromVersion: string,
+  targetVersion: string,
+  event: ServerSelfUpdateProgressEvent,
+): Extract<ServerUpdateState, { status: "running" }> {
+  return {
+    status: "running",
+    stage: event.type === "complete" ? "resuming" : event.stage,
+    fromVersion,
+    targetVersion,
+  };
+}
+
+export function serverUpdateStateForServerVersion(
+  state: ServerUpdateState,
+  serverVersion: string | null,
+): ServerUpdateState {
+  return state.status === "idle" ||
+    state.status === "running" ||
+    serverVersion === null ||
+    state.fromVersion === serverVersion
+    ? state
+    : IDLE_SERVER_UPDATE_STATE;
+}
+
+function serverUpdateFailureMessage(error: unknown): string {
+  return error instanceof Error ? error.message : "Server update failed.";
+}
+
+function isRpcSocketError(error: unknown): boolean {
+  if (!isRpcClientError(error)) {
+    return false;
+  }
+  switch (error.reason._tag) {
+    case "SocketReadError":
+    case "SocketWriteError":
+    case "SocketCloseError":
+      return true;
+    default:
+      return false;
+  }
+}
+
+export function isLegacyUpdateHandoffLoss(cause: Cause.Cause<unknown>): boolean {
+  if (Cause.hasInterruptsOnly(cause)) {
+    return true;
+  }
+  return (
+    cause.reasons.length > 0 &&
+    cause.reasons.every((reason) => Cause.isFailReason(reason) && isRpcSocketError(reason.error))
+  );
+}
+
+export function resolveServerUpdateProgressResult<E>(
+  targetVersion: string,
+  terminal: Option.Option<ServerSelfUpdateResult>,
+  streamExit: Exit.Exit<void, E>,
+): Effect.Effect<ServerSelfUpdateResult, E | ServerUpdateProgressIncompleteError> {
+  if (
+    Option.isSome(terminal) &&
+    (Exit.isSuccess(streamExit) || isLegacyUpdateHandoffLoss(streamExit.cause))
+  ) {
+    return Effect.succeed(terminal.value);
+  }
+  if (Exit.isFailure(streamExit)) {
+    return Effect.failCause(streamExit.cause);
+  }
+  return Effect.fail(new ServerUpdateProgressIncompleteError({ targetVersion }));
+}
+
 export interface ServerConfigProjection {
   readonly config: ServerConfig;
   readonly latestEvent: ServerConfigStreamEvent;
@@ -225,7 +365,13 @@ export function resolveServerConfigValue(
   projection: ServerConfigProjection | null,
   initialConfig: ServerConfig | null,
 ): ServerConfig | null {
-  if (projection?.source === "live") return projection.config;
+  if (
+    projection?.source === "live" &&
+    (initialConfig === null ||
+      projection.config.environment.serverVersion === initialConfig.environment.serverVersion)
+  ) {
+    return projection.config;
+  }
   return initialConfig ?? projection?.config ?? null;
 }
 
@@ -238,6 +384,8 @@ export function createServerEnvironmentAtoms<R, E>(
   },
 ) {
   const configScheduler = createAtomCommandScheduler();
+  // Updates stay serial end-to-end, but only their handoff phase occupies the config lane.
+  const updateScheduler = createAtomCommandScheduler();
   const configConcurrency = {
     mode: "serial" as const,
     key: ({ environmentId }: { readonly environmentId: string }) => environmentId,
@@ -271,6 +419,179 @@ export function createServerEnvironmentAtoms<R, E>(
       );
     }).pipe(Atom.withLabel(`environment-data:server:config:${environmentId}`));
   });
+  const updateStateValueAtom = Atom.family((environmentId: EnvironmentId) =>
+    Atom.make((get) =>
+      serverUpdateStateForServerVersion(
+        get(serverUpdateStateAtom(environmentId)),
+        get(configValueAtom(environmentId))?.environment.serverVersion ?? null,
+      ),
+    ).pipe(Atom.withLabel(`environment-data:server:update-state-value:${environmentId}`)),
+  );
+  const updateStateAtom = (environmentId: EnvironmentId | null) =>
+    environmentId === null ? EMPTY_SERVER_UPDATE_STATE_ATOM : updateStateValueAtom(environmentId);
+  const updateServer = createRuntimeCommand<
+    EnvironmentRegistry | EnvironmentCacheStore | R,
+    E,
+    ServerUpdateTarget,
+    ServerSelfUpdateResult,
+    unknown
+  >(runtime, {
+    label: "environment-data:server:update-server",
+    scheduler: updateScheduler,
+    concurrency: configConcurrency,
+    execute: (target, atomRegistry) => {
+      const stateAtom = serverUpdateStateAtom(target.environmentId);
+      const targetVersion = target.input.targetVersion;
+      let fromVersion =
+        atomRegistry.get(configValueAtom(target.environmentId))?.environment.serverVersion ??
+        targetVersion;
+      let currentStage: ServerUpdateStage = "downloading";
+      atomRegistry.set(stateAtom, {
+        status: "running",
+        stage: currentStage,
+        fromVersion,
+        targetVersion,
+      });
+
+      return Effect.gen(function* () {
+        const environmentRegistry = yield* EnvironmentRegistry;
+        const result = yield* scheduleAtomCommandEffect(
+          atomRegistry,
+          configScheduler,
+          configConcurrency,
+          target,
+          Effect.gen(function* () {
+            const currentConfig = atomRegistry.get(configValueAtom(target.environmentId));
+            fromVersion = currentConfig?.environment.serverVersion ?? targetVersion;
+            atomRegistry.set(stateAtom, {
+              status: "running",
+              stage: currentStage,
+              fromVersion,
+              targetVersion,
+            });
+
+            const supportsProgress =
+              currentConfig?.environment.capabilities.serverSelfUpdateProgress === true;
+            const updateResult: ServerSelfUpdateResult = supportsProgress
+              ? yield* Effect.gen(function* () {
+                  const terminal = yield* Ref.make<Option.Option<ServerSelfUpdateResult>>(
+                    Option.none(),
+                  );
+                  const streamExit = yield* environmentRegistry
+                    .runStream(
+                      target.environmentId,
+                      runStream(WS_METHODS.serverUpdateServerWithProgress, target.input),
+                    )
+                    .pipe(
+                      Stream.runForEach((event) =>
+                        Effect.sync(() => {
+                          currentStage = event.type === "complete" ? "resuming" : event.stage;
+                          atomRegistry.set(
+                            stateAtom,
+                            serverUpdateStateForProgressEvent(fromVersion, targetVersion, event),
+                          );
+                        }).pipe(
+                          Effect.andThen(
+                            event.type === "complete"
+                              ? Ref.set(terminal, Option.some(event.result))
+                              : Effect.void,
+                          ),
+                        ),
+                      ),
+                      Effect.exit,
+                    );
+                  return yield* resolveServerUpdateProgressResult(
+                    targetVersion,
+                    yield* Ref.get(terminal),
+                    streamExit,
+                  );
+                })
+              : yield* Effect.gen(function* () {
+                  const selfUpdateMethod = currentConfig?.environment.capabilities.serverSelfUpdate;
+                  const exit = yield* environmentRegistry
+                    .run(target.environmentId, request(WS_METHODS.serverUpdateServer, target.input))
+                    .pipe(Effect.exit);
+                  if (Exit.isSuccess(exit)) {
+                    return exit.value;
+                  }
+                  if (
+                    (selfUpdateMethod === "boot-service" || selfUpdateMethod === "respawn") &&
+                    isLegacyUpdateHandoffLoss(exit.cause)
+                  ) {
+                    // Older servers can tear down the transport before their
+                    // unary acknowledgement arrives. Treat only that transport
+                    // loss as a handoff, then prove it by waiting for target ready.
+                    return { targetVersion, method: selfUpdateMethod };
+                  }
+                  return yield* Effect.failCause(exit.cause);
+                });
+
+            currentStage = "resuming";
+            atomRegistry.set(stateAtom, {
+              status: "running",
+              stage: currentStage,
+              fromVersion,
+              targetVersion,
+            });
+            return updateResult;
+          }),
+        );
+
+        // The update restart is intentional. As soon as the supervisor sees
+        // that first failed connection, discard any prior backoff debt and
+        // retry immediately instead of carrying an old 16-second delay.
+        yield* environmentRegistry.stateChanges(target.environmentId).pipe(
+          Stream.filter((state) => state.phase === "backoff"),
+          Stream.take(1),
+          Stream.runDrain,
+          Effect.andThen(environmentRegistry.retryNow(target.environmentId)),
+          Effect.timeoutOption(Duration.seconds(30)),
+          Effect.ignore,
+          Effect.forkChild,
+        );
+
+        const resumed = yield* environmentRegistry
+          .followStream(target.environmentId, subscribe(WS_METHODS.subscribeServerLifecycle, {}))
+          .pipe(
+            Stream.filter(
+              (event) =>
+                event.type === "ready" && event.payload.environment.serverVersion === targetVersion,
+            ),
+            Stream.runHead,
+            Effect.timeoutOption(Duration.seconds(120)),
+            Effect.map(Option.flatten),
+          );
+        if (Option.isNone(resumed)) {
+          return yield* new ServerUpdateResumeTimeoutError({
+            environmentId: target.environmentId,
+            targetVersion,
+          });
+        }
+
+        atomRegistry.set(stateAtom, IDLE_SERVER_UPDATE_STATE);
+        return result;
+      }).pipe(
+        Effect.onExit((exit) =>
+          Effect.sync(() => {
+            if (Exit.isSuccess(exit)) {
+              return;
+            }
+            if (Cause.hasInterruptsOnly(exit.cause)) {
+              atomRegistry.set(stateAtom, IDLE_SERVER_UPDATE_STATE);
+              return;
+            }
+            atomRegistry.set(stateAtom, {
+              status: "failed",
+              stage: currentStage,
+              fromVersion,
+              targetVersion,
+              message: serverUpdateFailureMessage(Cause.squash(exit.cause)),
+            });
+          }),
+        ),
+      );
+    },
+  });
   const settingsValueAtom = Atom.family((environmentId: EnvironmentId) =>
     Atom.make((get) => get(configValueAtom(environmentId))?.settings ?? null).pipe(
       Atom.withLabel(`environment-data:server:settings:${environmentId}`),
@@ -284,6 +605,7 @@ export function createServerEnvironmentAtoms<R, E>(
 
   return {
     configValueAtom,
+    updateStateAtom,
     settingsValueAtom,
     providersValueAtom,
     traceDiagnostics: createEnvironmentRpcQueryAtomFamily(runtime, {
@@ -331,12 +653,7 @@ export function createServerEnvironmentAtoms<R, E>(
       scheduler: configScheduler,
       concurrency: configConcurrency,
     }),
-    updateServer: createEnvironmentRpcCommand(runtime, {
-      label: "environment-data:server:update-server",
-      tag: WS_METHODS.serverUpdateServer,
-      scheduler: configScheduler,
-      concurrency: configConcurrency,
-    }),
+    updateServer,
     upsertKeybinding: createEnvironmentRpcCommand(runtime, {
       label: "environment-data:server:upsert-keybinding",
       tag: WS_METHODS.serverUpsertKeybinding,
diff --git a/packages/contracts/src/environment.ts b/packages/contracts/src/environment.ts
index 3d753350d99..5d4238994fb 100644
--- a/packages/contracts/src/environment.ts
+++ b/packages/contracts/src/environment.ts
@@ -54,6 +54,9 @@ export const ExecutionEnvironmentCapabilities = Schema.Struct({
       servers that must be relaunched manually (dev checkouts, Windows
       foreground runs, pre-update servers). */
   serverSelfUpdate: Schema.optionalKey(ServerSelfUpdateCapability),
+  /** Server can stream self-update progress before acknowledging the
+      restart. Clients fall back to server.updateServer when absent. */
+  serverSelfUpdateProgress: Schema.optionalKey(Schema.Boolean),
 });
 export type ExecutionEnvironmentCapabilities = typeof ExecutionEnvironmentCapabilities.Type;
 
diff --git a/packages/contracts/src/rpc.ts b/packages/contracts/src/rpc.ts
index 0701e15a668..d1a5f2504c7 100644
--- a/packages/contracts/src/rpc.ts
+++ b/packages/contracts/src/rpc.ts
@@ -127,6 +127,7 @@ import {
   ServerProviderUpdatedPayload,
   ServerSelfUpdateError,
   ServerSelfUpdateInput,
+  ServerSelfUpdateProgressEvent,
   ServerSelfUpdateResult,
   ServerTraceDiagnosticsResult,
   ServerProcessDiagnosticsResult,
@@ -218,6 +219,7 @@ export const WS_METHODS = {
   serverRefreshProviders: "server.refreshProviders",
   serverUpdateProvider: "server.updateProvider",
   serverUpdateServer: "server.updateServer",
+  serverUpdateServerWithProgress: "server.updateServerWithProgress",
   serverUpsertKeybinding: "server.upsertKeybinding",
   serverRemoveKeybinding: "server.removeKeybinding",
   serverGetSettings: "server.getSettings",
@@ -305,6 +307,16 @@ export const WsServerUpdateServerRpc = Rpc.make(WS_METHODS.serverUpdateServer, {
   error: Schema.Union([ServerSelfUpdateError, EnvironmentAuthorizationError]),
 });
 
+export const WsServerUpdateServerWithProgressRpc = Rpc.make(
+  WS_METHODS.serverUpdateServerWithProgress,
+  {
+    payload: ServerSelfUpdateInput,
+    success: ServerSelfUpdateProgressEvent,
+    error: Schema.Union([ServerSelfUpdateError, EnvironmentAuthorizationError]),
+    stream: true,
+  },
+);
+
 export const WsServerGetSettingsRpc = Rpc.make(WS_METHODS.serverGetSettings, {
   payload: Schema.Struct({}),
   success: ServerSettings,
@@ -759,6 +771,7 @@ export const WsRpcGroup = RpcGroup.make(
   WsServerRefreshProvidersRpc,
   WsServerUpdateProviderRpc,
   WsServerUpdateServerRpc,
+  WsServerUpdateServerWithProgressRpc,
   WsServerUpsertKeybindingRpc,
   WsServerRemoveKeybindingRpc,
   WsServerGetSettingsRpc,
diff --git a/packages/contracts/src/server.ts b/packages/contracts/src/server.ts
index 8e42c938ca4..e083523bbdf 100644
--- a/packages/contracts/src/server.ts
+++ b/packages/contracts/src/server.ts
@@ -592,6 +592,21 @@ export const ServerSelfUpdateResult = Schema.Struct({
 });
 export type ServerSelfUpdateResult = typeof ServerSelfUpdateResult.Type;
 
+export const ServerSelfUpdateProgressStage = Schema.Literals(["downloading", "installing"]);
+export type ServerSelfUpdateProgressStage = typeof ServerSelfUpdateProgressStage.Type;
+
+export const ServerSelfUpdateProgressEvent = Schema.Union([
+  Schema.Struct({
+    type: Schema.Literal("progress"),
+    stage: ServerSelfUpdateProgressStage,
+  }),
+  Schema.Struct({
+    type: Schema.Literal("complete"),
+    result: ServerSelfUpdateResult,
+  }),
+]);
+export type ServerSelfUpdateProgressEvent = typeof ServerSelfUpdateProgressEvent.Type;
+
 export class ServerSelfUpdateError extends Schema.TaggedErrorClass<ServerSelfUpdateError>()(
   "ServerSelfUpdateError",
   {

From 4b71a2ae2ffbbb7b6936051552094b71364cefd4 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Thu, 30 Jul 2026 05:30:11 -0700
Subject: [PATCH 20/34] feat(search): find threads by conversation content
 (#4959)

---
 .../src/features/home/HomeRouteScreen.tsx     |  30 +-
 apps/mobile/src/features/home/HomeScreen.tsx  | 124 ++++++--
 .../src/features/home/homeThreadList.test.ts  |  28 ++
 .../src/features/home/homeThreadList.ts       |  13 +-
 .../threads/ThreadNavigationSidebar.tsx       |  82 +++++-
 .../features/threads/thread-list-items.tsx    |  18 ++
 .../features/threads/thread-list-v2-items.tsx |  40 ++-
 .../features/threads/thread-search-match.tsx  |  92 ++++++
 .../src/features/threads/threadListV2.test.ts |  22 ++
 .../src/features/threads/threadListV2.ts      |  15 +-
 apps/mobile/src/state/queries.ts              |  47 ++++
 apps/server/src/auth/RpcAuthorization.ts      |   1 +
 .../checkpointing/CheckpointDiffQuery.test.ts |   5 +
 .../Layers/OrchestrationEngine.test.ts        |   1 +
 .../Layers/ProjectionSnapshotQuery.test.ts    | 265 ++++++++++++++++++
 .../Layers/ProjectionSnapshotQuery.ts         | 132 +++++++++
 .../Services/ProjectionSnapshotQuery.ts       |  10 +
 .../project/ProjectSetupScriptRunner.test.ts  |   1 +
 .../Layers/ProviderSessionReaper.test.ts      |   1 +
 apps/server/src/server.test.ts                |  30 ++
 apps/server/src/serverRuntimeStartup.test.ts  |   4 +
 apps/server/src/ws.ts                         |  15 +
 .../components/CommandPalette.logic.test.ts   |  23 ++
 .../src/components/CommandPalette.logic.ts    |  17 +-
 apps/web/src/components/CommandPalette.tsx    |  51 +++-
 .../src/components/CommandPaletteResults.tsx  |  89 +++++-
 apps/web/src/state/queries.ts                 |  45 +++
 docs/user/keybindings.md                      |   5 +
 packages/client-runtime/package.json          |   4 +
 .../client-runtime/src/state/orchestration.ts |   6 +
 .../src/state/threadSearch.test.ts            |  72 +++++
 .../client-runtime/src/state/threadSearch.ts  |  81 ++++++
 packages/contracts/src/orchestration.ts       |  39 +++
 packages/contracts/src/rpc.ts                 |   9 +
 34 files changed, 1345 insertions(+), 72 deletions(-)
 create mode 100644 apps/mobile/src/features/threads/thread-search-match.tsx
 create mode 100644 packages/client-runtime/src/state/threadSearch.test.ts
 create mode 100644 packages/client-runtime/src/state/threadSearch.ts

diff --git a/apps/mobile/src/features/home/HomeRouteScreen.tsx b/apps/mobile/src/features/home/HomeRouteScreen.tsx
index 9fa179f4c76..c172694b6c5 100644
--- a/apps/mobile/src/features/home/HomeRouteScreen.tsx
+++ b/apps/mobile/src/features/home/HomeRouteScreen.tsx
@@ -25,7 +25,7 @@ export function HomeRouteScreen() {
   const { layout } = useAdaptiveWorkspaceLayout();
   const projects = useProjects();
   const threads = useThreadShells();
-  const { state: catalogState } = useWorkspaceState();
+  const { environments: workspaceEnvironments, state: catalogState } = useWorkspaceState();
   const { savedConnectionsById } = useSavedRemoteConnections();
   const navigation = useNavigation();
   const [searchQuery, setSearchQuery] = useState("");
@@ -33,20 +33,22 @@ export function HomeRouteScreen() {
     useThreadListActions();
   const pendingTasks = usePendingNewTasks();
   const { openPendingTask, confirmDeletePendingTask } = usePendingTaskListActions();
-  const environments = useMemo(
-    () =>
-      Arr.sort(
-        Object.values(savedConnectionsById).map((connection) => ({
-          environmentId: connection.environmentId,
-          label: connection.environmentLabel,
-        })),
-        Order.mapInput(
-          Order.String,
-          (environment: { readonly label: string }) => environment.label,
-        ),
+  const environments = useMemo(() => {
+    const connectionStateByEnvironmentId = new Map(
+      workspaceEnvironments.map(
+        (environment) => [environment.environmentId, environment.connectionState] as const,
       ),
-    [savedConnectionsById],
-  );
+    );
+    return Arr.sort(
+      Object.values(savedConnectionsById).map((connection) => ({
+        environmentId: connection.environmentId,
+        label: connection.environmentLabel,
+        connectionState:
+          connectionStateByEnvironmentId.get(connection.environmentId) ?? "available",
+      })),
+      Order.mapInput(Order.String, (environment: { readonly label: string }) => environment.label),
+    );
+  }, [savedConnectionsById, workspaceEnvironments]);
   const availableEnvironmentIds = useMemo(
     () => new Set(environments.map((environment) => environment.environmentId)),
     [environments],
diff --git a/apps/mobile/src/features/home/HomeScreen.tsx b/apps/mobile/src/features/home/HomeScreen.tsx
index b96cc862b27..3c2ee4f7b92 100644
--- a/apps/mobile/src/features/home/HomeScreen.tsx
+++ b/apps/mobile/src/features/home/HomeScreen.tsx
@@ -7,6 +7,10 @@ import {
   type EnvironmentProject,
   type EnvironmentThreadShell,
 } from "@t3tools/client-runtime/state/shell";
+import {
+  threadSearchMatchKey,
+  type EnvironmentThreadSearchMatch,
+} from "@t3tools/client-runtime/state/thread-search";
 import type {
   EnvironmentId,
   SidebarProjectGroupingMode,
@@ -22,11 +26,12 @@ import { useThemeColor } from "../../lib/useThemeColor";
 
 import { AppText as Text } from "../../components/AppText";
 import { EmptyState } from "../../components/EmptyState";
-import type { WorkspaceState } from "../../state/workspaceModel";
+import type { WorkspaceEnvironment, WorkspaceState } from "../../state/workspaceModel";
 import type { SavedRemoteConnection } from "../../lib/connection";
 import { scopedProjectKey } from "../../lib/scopedEntities";
 import { NATIVE_LIQUID_GLASS_SUPPORTED } from "../../native/native-glass";
 import { mobilePreferencesAtom, updateMobilePreferencesAtom } from "../../state/preferences";
+import { useThreadSearch } from "../../state/queries";
 import { useThreadListV2Enabled } from "../threads/use-thread-list-v2-enabled";
 import { environmentServerConfigsAtom } from "../../state/server";
 import type { PendingNewTask } from "../../state/use-pending-new-tasks";
@@ -72,7 +77,9 @@ interface HomeScreenProps {
   readonly pendingTasks: ReadonlyArray<PendingNewTask>;
   readonly catalogState: WorkspaceState;
   readonly savedConnectionsById: Readonly<Record<string, SavedRemoteConnection>>;
-  readonly environments: ReadonlyArray<HomeListFilterMenuEnvironment>;
+  readonly environments: ReadonlyArray<
+    HomeListFilterMenuEnvironment & Pick<WorkspaceEnvironment, "connectionState">
+  >;
   readonly searchQuery: string;
   readonly selectedEnvironmentId: EnvironmentId | null;
   readonly selectedProjectKey: string | null;
@@ -189,6 +196,35 @@ export function HomeScreen(props: HomeScreenProps) {
   const listRef = useRef<LegendListRef | null>(null);
   const insets = useSafeAreaInsets();
   const accentColor = useThemeColor("--color-icon-muted");
+  const searchEnvironmentIds = useMemo(
+    () =>
+      props.selectedEnvironmentId === null
+        ? props.environments
+            .filter((environment) => environment.connectionState === "connected")
+            .map((environment) => environment.environmentId)
+        : props.environments.some(
+              (environment) =>
+                environment.environmentId === props.selectedEnvironmentId &&
+                environment.connectionState === "connected",
+            )
+          ? [props.selectedEnvironmentId]
+          : [],
+    [props.environments, props.selectedEnvironmentId],
+  );
+  const threadSearch = useThreadSearch(searchEnvironmentIds, props.searchQuery);
+  const threadSearchMatchByKey = useMemo(() => {
+    const matches = new Map<string, EnvironmentThreadSearchMatch>();
+    for (const match of threadSearch.matches) {
+      if (match.source === "user" || match.source === "assistant") {
+        matches.set(threadSearchMatchKey(match), match);
+      }
+    }
+    return matches;
+  }, [threadSearch.matches]);
+  const matchedThreadKeys = useMemo(
+    () => new Set(threadSearch.matches.map(threadSearchMatchKey)),
+    [threadSearch.matches],
+  );
   const effectiveGroupDisplayStates = useMemo(() => {
     const next = new Map(groupDisplayStates);
     if (!AsyncResult.isSuccess(preferencesResult)) {
@@ -318,6 +354,7 @@ export function HomeScreen(props: HomeScreenProps) {
         pendingTasks: scopedPendingTasks,
         environmentId: props.selectedEnvironmentId,
         searchQuery: props.searchQuery,
+        matchedThreadKeys,
         projectSortOrder: props.projectSortOrder,
         threadSortOrder: props.threadSortOrder,
         projectGroupingMode: props.projectGroupingMode,
@@ -328,6 +365,7 @@ export function HomeScreen(props: HomeScreenProps) {
       props.searchQuery,
       props.selectedEnvironmentId,
       props.threadSortOrder,
+      matchedThreadKeys,
       scopedPendingTasks,
       scopedProjects,
       scopedThreads,
@@ -516,6 +554,7 @@ export function HomeScreen(props: HomeScreenProps) {
       environmentId: props.selectedEnvironmentId,
       projectRefs: v2ScopedProjectGroup === null ? null : v2ScopedProjectGroup.projectRefs,
       searchQuery: props.searchQuery,
+      matchedThreadKeys,
       changeRequestStateByKey,
       settlementEnvironmentIds,
       snoozeEnvironmentIds,
@@ -533,6 +572,7 @@ export function HomeScreen(props: HomeScreenProps) {
     props.searchQuery,
     props.selectedEnvironmentId,
     props.threads,
+    matchedThreadKeys,
     threadListV2Enabled,
     v2ScopedProjectGroup,
   ]);
@@ -629,6 +669,13 @@ export function HomeScreen(props: HomeScreenProps) {
               ? (props.savedConnectionsById[thread.environmentId]?.environmentLabel ?? null)
               : null
           }
+          searchMatch={threadSearchMatchByKey.get(
+            threadSearchMatchKey({
+              environmentId: thread.environmentId,
+              threadId: thread.id,
+            }),
+          )}
+          searchQuery={props.searchQuery}
           onSelectThread={props.onSelectThread}
           onDeleteThread={handleDeleteThread}
           onArchiveThread={props.onArchiveThread}
@@ -660,7 +707,9 @@ export function HomeScreen(props: HomeScreenProps) {
       props.savedConnectionsById,
       serverConfigs,
       settlementEnvironmentIds,
+      threadSearchMatchByKey,
       v2ProjectTitleByProjectKey,
+      props.searchQuery,
     ],
   );
   const v2KeyExtractor = useCallback((item: ThreadListV2ListItem) => item.key, []);
@@ -675,19 +724,28 @@ export function HomeScreen(props: HomeScreenProps) {
       projectTitleByProjectKey: v2ProjectTitleByProjectKey,
       serverConfigs,
       savedConnectionsById: props.savedConnectionsById,
+      searchQuery: props.searchQuery,
+      threadSearchMatchByKey,
     }),
     [
       projectByKey,
       projectCwdByKey,
+      props.searchQuery,
       props.savedConnectionsById,
       serverConfigs,
+      threadSearchMatchByKey,
       v2ProjectTitleByProjectKey,
     ],
   );
 
   const extraData = useMemo(
-    () => ({ savedConnectionsById: props.savedConnectionsById, projectCwdByKey }),
-    [props.savedConnectionsById, projectCwdByKey],
+    () => ({
+      projectCwdByKey,
+      savedConnectionsById: props.savedConnectionsById,
+      searchQuery: props.searchQuery,
+      threadSearchMatchByKey,
+    }),
+    [projectCwdByKey, props.savedConnectionsById, props.searchQuery, threadSearchMatchByKey],
   );
 
   const renderItem = useCallback(
@@ -740,6 +798,13 @@ export function HomeScreen(props: HomeScreenProps) {
                 null
               }
               isLast={item.isLast}
+              searchMatch={threadSearchMatchByKey.get(
+                threadSearchMatchKey({
+                  environmentId: thread.environmentId,
+                  threadId: thread.id,
+                }),
+              )}
+              searchQuery={props.searchQuery}
               onArchiveThread={props.onArchiveThread}
               onDeleteThread={props.onDeleteThread}
               onSelectThread={props.onSelectThread}
@@ -770,7 +835,9 @@ export function HomeScreen(props: HomeScreenProps) {
       props.onNewThreadInProject,
       props.onSelectPendingTask,
       props.onSelectThread,
+      props.searchQuery,
       props.savedConnectionsById,
+      threadSearchMatchByKey,
       updateGroupDisplay,
     ],
   );
@@ -863,7 +930,7 @@ export function HomeScreen(props: HomeScreenProps) {
   const v2ListHeader = listHeader;
 
   const listEmpty = !hasResults ? (
-    hasSearchQuery ? (
+    hasSearchQuery && threadSearch.isPending ? null : hasSearchQuery ? (
       <EmptyState title="No results" detail={`No threads matching "${props.searchQuery}".`} />
     ) : selectedProjectScope !== null ? (
       <EmptyState
@@ -886,31 +953,34 @@ export function HomeScreen(props: HomeScreenProps) {
   // threads yet" over an inbox that is merely all-snoozed reads as data
   // loss.
   const v2SnoozedCount = threadListV2Layout.snoozedCount;
-  const v2ListEmpty = hasSearchQuery ? (
-    v2SnoozedCount > 0 ? (
-      // The snoozed threads already passed this search filter: "No
-      // results" would claim nothing matched when matches are merely
-      // parked.
+  const v2ListEmpty =
+    hasSearchQuery && threadSearch.isPending && v2SnoozedCount === 0 ? null : hasSearchQuery ? (
+      v2SnoozedCount > 0 ? (
+        // The snoozed threads already passed this search filter: "No
+        // results" would claim nothing matched when matches are merely
+        // parked.
+        <EmptyState
+          title={
+            v2SnoozedCount === 1 ? "1 matching thread snoozed" : `All matching threads snoozed`
+          }
+          detail={`Threads matching "${props.searchQuery}" are snoozed and return when their wake time passes.`}
+        />
+      ) : (
+        <EmptyState title="No results" detail={`No threads matching "${props.searchQuery}".`} />
+      )
+    ) : v2SnoozedCount > 0 ? (
+      <EmptyState
+        title={v2SnoozedCount === 1 ? "1 thread snoozed" : `${v2SnoozedCount} threads snoozed`}
+        detail="Snoozed threads return when their wake time passes."
+      />
+    ) : v2ScopedProjectGroup !== null ? (
       <EmptyState
-        title={v2SnoozedCount === 1 ? "1 matching thread snoozed" : `All matching threads snoozed`}
-        detail={`Threads matching "${props.searchQuery}" are snoozed and return when their wake time passes.`}
+        title={`No threads in ${v2ScopedProjectGroup.title}`}
+        detail="Choose another project or create a new task."
       />
     ) : (
-      <EmptyState title="No results" detail={`No threads matching "${props.searchQuery}".`} />
-    )
-  ) : v2SnoozedCount > 0 ? (
-    <EmptyState
-      title={v2SnoozedCount === 1 ? "1 thread snoozed" : `${v2SnoozedCount} threads snoozed`}
-      detail="Snoozed threads return when their wake time passes."
-    />
-  ) : v2ScopedProjectGroup !== null ? (
-    <EmptyState
-      title={`No threads in ${v2ScopedProjectGroup.title}`}
-      detail="Choose another project or create a new task."
-    />
-  ) : (
-    listEmpty
-  );
+      listEmpty
+    );
 
   if (threadListV2Enabled) {
     return (
diff --git a/apps/mobile/src/features/home/homeThreadList.test.ts b/apps/mobile/src/features/home/homeThreadList.test.ts
index e791cd3b36a..75964aa23d2 100644
--- a/apps/mobile/src/features/home/homeThreadList.test.ts
+++ b/apps/mobile/src/features/home/homeThreadList.test.ts
@@ -2,6 +2,7 @@ import type {
   EnvironmentProject,
   EnvironmentThreadShell,
 } from "@t3tools/client-runtime/state/shell";
+import { threadSearchMatchKey } from "@t3tools/client-runtime/state/thread-search";
 import { EnvironmentId, ProjectId, ProviderInstanceId, ThreadId } from "@t3tools/contracts";
 import { describe, expect, it } from "vite-plus/test";
 
@@ -661,6 +662,33 @@ describe("buildHomeThreadGroups", () => {
     );
   });
 
+  it("includes a thread matched by message content", () => {
+    const environmentId = EnvironmentId.make("environment-1");
+    const project = makeProject({
+      environmentId,
+      id: ProjectId.make("project-1"),
+      title: "T3 Code",
+    });
+    const thread = makeThread({
+      environmentId,
+      id: ThreadId.make("thread-content"),
+      projectId: project.id,
+      title: "Unrelated title",
+    });
+
+    const groups = buildGroups([project], [thread], {
+      searchQuery: "relay reconnect",
+      matchedThreadKeys: new Set([
+        threadSearchMatchKey({
+          environmentId,
+          threadId: thread.id,
+        }),
+      ]),
+    });
+
+    expect(groups[0]?.threads.map((candidate) => candidate.id)).toEqual(["thread-content"]);
+  });
+
   it("targets quick new threads at the group member with the newest thread", () => {
     const laptopEnv = EnvironmentId.make("environment-laptop");
     const desktopEnv = EnvironmentId.make("environment-desktop");
diff --git a/apps/mobile/src/features/home/homeThreadList.ts b/apps/mobile/src/features/home/homeThreadList.ts
index 21084f0f5fe..5bd14086e29 100644
--- a/apps/mobile/src/features/home/homeThreadList.ts
+++ b/apps/mobile/src/features/home/homeThreadList.ts
@@ -12,6 +12,7 @@ import {
   sortThreads,
   toSortableTimestamp,
 } from "@t3tools/client-runtime/state/thread-sort";
+import { threadSearchMatchKey } from "@t3tools/client-runtime/state/thread-search";
 import type {
   EnvironmentId,
   ScopedProjectRef,
@@ -254,6 +255,7 @@ export function buildHomeThreadGroups(input: {
   readonly pendingTasks?: ReadonlyArray<PendingNewTask>;
   readonly environmentId: EnvironmentId | null;
   readonly searchQuery: string;
+  readonly matchedThreadKeys?: ReadonlySet<string>;
   readonly projectSortOrder: HomeProjectSortOrder;
   readonly threadSortOrder: SidebarThreadSortOrder;
   readonly projectGroupingMode: SidebarProjectGroupingMode;
@@ -350,7 +352,16 @@ export function buildHomeThreadGroups(input: {
       group.projects.some((project) => project.title.toLocaleLowerCase().includes(query));
     const matchingThreads = groupMatches
       ? group.threads
-      : group.threads.filter((thread) => thread.title.toLocaleLowerCase().includes(query));
+      : group.threads.filter(
+          (thread) =>
+            thread.title.toLocaleLowerCase().includes(query) ||
+            input.matchedThreadKeys?.has(
+              threadSearchMatchKey({
+                environmentId: thread.environmentId,
+                threadId: thread.id,
+              }),
+            ) === true,
+        );
     const matchingPendingTasks = groupMatches
       ? group.pendingTasks
       : group.pendingTasks.filter((pendingTask) =>
diff --git a/apps/mobile/src/features/threads/ThreadNavigationSidebar.tsx b/apps/mobile/src/features/threads/ThreadNavigationSidebar.tsx
index 3d413f9c487..36a86ceb1e3 100644
--- a/apps/mobile/src/features/threads/ThreadNavigationSidebar.tsx
+++ b/apps/mobile/src/features/threads/ThreadNavigationSidebar.tsx
@@ -3,6 +3,10 @@ import type {
   EnvironmentProject,
   EnvironmentThreadShell,
 } from "@t3tools/client-runtime/state/shell";
+import {
+  threadSearchMatchKey,
+  type EnvironmentThreadSearchMatch,
+} from "@t3tools/client-runtime/state/thread-search";
 import { LegendList } from "@legendapp/list/react-native";
 import type { MenuAction } from "@react-native-menu/menu";
 import { useAtomValue } from "@effect/atom-react";
@@ -24,6 +28,7 @@ import { NativeStackScreenOptions } from "../../native/StackHeader";
 import { scopedProjectKey, scopedThreadKey } from "../../lib/scopedEntities";
 import { useThemeColor } from "../../lib/useThemeColor";
 import { useProjects, useThreadShells } from "../../state/entities";
+import { useThreadSearch } from "../../state/queries";
 import { useThreadListV2Enabled } from "./use-thread-list-v2-enabled";
 import { environmentServerConfigsAtom } from "../../state/server";
 import { usePendingNewTasks } from "../../state/use-pending-new-tasks";
@@ -180,7 +185,7 @@ function ThreadNavigationSidebarPane(
   const colorScheme = useColorScheme() === "dark" ? "dark" : "light";
   const projects = useProjects();
   const threads = useThreadShells();
-  const { state: catalogState } = useWorkspaceState();
+  const { environments: workspaceEnvironments, state: catalogState } = useWorkspaceState();
   const { savedConnectionsById } = useSavedRemoteConnections();
   const [headerIsOverContent, setHeaderIsOverContent] = useState(false);
   const searchInputRef = useRef<TextInput>(null);
@@ -209,6 +214,35 @@ function ThreadNavigationSidebarPane(
   );
   const { options, setSelectedEnvironmentId, setProjectSortOrder, setThreadSortOrder } =
     useHomeListOptions(availableEnvironmentIds);
+  const searchEnvironmentIds = useMemo(
+    () =>
+      options.selectedEnvironmentId === null
+        ? workspaceEnvironments
+            .filter((environment) => environment.connectionState === "connected")
+            .map((environment) => environment.environmentId)
+        : workspaceEnvironments.some(
+              (environment) =>
+                environment.environmentId === options.selectedEnvironmentId &&
+                environment.connectionState === "connected",
+            )
+          ? [options.selectedEnvironmentId]
+          : [],
+    [options.selectedEnvironmentId, workspaceEnvironments],
+  );
+  const threadSearch = useThreadSearch(searchEnvironmentIds, props.searchQuery);
+  const threadSearchMatchByKey = useMemo(() => {
+    const matches = new Map<string, EnvironmentThreadSearchMatch>();
+    for (const match of threadSearch.matches) {
+      if (match.source === "user" || match.source === "assistant") {
+        matches.set(threadSearchMatchKey(match), match);
+      }
+    }
+    return matches;
+  }, [threadSearch.matches]);
+  const matchedThreadKeys = useMemo(
+    () => new Set(threadSearch.matches.map(threadSearchMatchKey)),
+    [threadSearch.matches],
+  );
   const [selectedProjectKey, setSelectedProjectKey] = useState<string | null>(null);
   const projectScopes = useMemo(
     () =>
@@ -305,11 +339,19 @@ function ThreadNavigationSidebarPane(
         pendingTasks: scopedPendingTasks,
         environmentId: options.selectedEnvironmentId,
         searchQuery: props.searchQuery,
+        matchedThreadKeys,
         projectSortOrder: options.projectSortOrder,
         threadSortOrder: options.threadSortOrder,
         projectGroupingMode: options.projectGroupingMode,
       }),
-    [options, props.searchQuery, scopedPendingTasks, scopedProjects, scopedThreads],
+    [
+      matchedThreadKeys,
+      options,
+      props.searchQuery,
+      scopedPendingTasks,
+      scopedProjects,
+      scopedThreads,
+    ],
   );
   const [groupDisplayStates, setGroupDisplayStates] = useState<
     ReadonlyMap<string, HomeGroupDisplayState>
@@ -432,6 +474,7 @@ function ThreadNavigationSidebarPane(
       environmentId: options.selectedEnvironmentId,
       projectRefs: selectedProjectScope === null ? null : selectedProjectScope.projectRefs,
       searchQuery: props.searchQuery,
+      matchedThreadKeys,
       changeRequestStateByKey,
       settlementEnvironmentIds,
       snoozeEnvironmentIds,
@@ -445,6 +488,7 @@ function ThreadNavigationSidebarPane(
     snoozeWakeTick,
     options.selectedEnvironmentId,
     props.searchQuery,
+    matchedThreadKeys,
     settledVisibleCount,
     settlementEnvironmentIds,
     snoozeEnvironmentIds,
@@ -687,6 +731,7 @@ function ThreadNavigationSidebarPane(
       projectTitleByProjectKey,
       savedConnectionsById,
       serverConfigs,
+      threadSearchMatchByKey,
     }),
     [
       props.selectedThreadKey,
@@ -695,6 +740,7 @@ function ThreadNavigationSidebarPane(
       projectTitleByProjectKey,
       savedConnectionsById,
       serverConfigs,
+      threadSearchMatchByKey,
     ],
   );
   const sidebarItemsAreEqual = useCallback(
@@ -797,6 +843,13 @@ function ThreadNavigationSidebarPane(
                   ? (savedConnectionsById[thread.environmentId]?.environmentLabel ?? null)
                   : null
               }
+              searchMatch={threadSearchMatchByKey.get(
+                threadSearchMatchKey({
+                  environmentId: thread.environmentId,
+                  threadId: thread.id,
+                }),
+              )}
+              searchQuery={props.searchQuery}
               pane="sidebar"
               selected={
                 scopedThreadKey(thread.environmentId, thread.id) === props.selectedThreadKey
@@ -876,6 +929,13 @@ function ThreadNavigationSidebarPane(
                 null
               }
               isLast={item.isLast}
+              searchMatch={threadSearchMatchByKey.get(
+                threadSearchMatchKey({
+                  environmentId: thread.environmentId,
+                  threadId: thread.id,
+                }),
+              )}
+              searchQuery={props.searchQuery}
               selected={
                 scopedThreadKey(thread.environmentId, thread.id) === props.selectedThreadKey
               }
@@ -914,10 +974,12 @@ function ThreadNavigationSidebarPane(
       projectCwdByKey,
       projectTitleByProjectKey,
       props.onNewThreadInProject,
+      props.searchQuery,
       props.selectedThreadKey,
       props.width,
       savedConnectionsById,
       serverConfigs,
+      threadSearchMatchByKey,
       settleThread,
       settlementEnvironmentIds,
       showMoreSettled,
@@ -977,13 +1039,15 @@ function ThreadNavigationSidebarPane(
       {catalogState.isLoadingConnections
         ? "Loading threads…"
         : props.searchQuery.trim().length > 0
-          ? snoozedCount > 0
-            ? // Snoozed matches passed this same search filter — "No
-              // matching threads" would misreport them as nonexistent.
-              snoozedCount === 1
-              ? "1 matching thread snoozed"
-              : "All matching threads snoozed"
-            : "No matching threads"
+          ? threadSearch.isPending && snoozedCount === 0
+            ? "Searching thread messages…"
+            : snoozedCount > 0
+              ? // Snoozed matches passed this same search filter — "No
+                // matching threads" would misreport them as nonexistent.
+                snoozedCount === 1
+                ? "1 matching thread snoozed"
+                : "All matching threads snoozed"
+              : "No matching threads"
           : snoozedCount > 0
             ? snoozedCount === 1
               ? "1 thread snoozed"
diff --git a/apps/mobile/src/features/threads/thread-list-items.tsx b/apps/mobile/src/features/threads/thread-list-items.tsx
index c2eccc725ae..9ac4002a9b0 100644
--- a/apps/mobile/src/features/threads/thread-list-items.tsx
+++ b/apps/mobile/src/features/threads/thread-list-items.tsx
@@ -3,6 +3,7 @@ import type {
   EnvironmentProject,
   EnvironmentThreadShell,
 } from "@t3tools/client-runtime/state/shell";
+import type { EnvironmentThreadSearchMatch } from "@t3tools/client-runtime/state/thread-search";
 import type { MenuAction } from "@react-native-menu/menu";
 import { SymbolView } from "../../components/AppSymbol";
 import { memo, useCallback, useMemo, type ComponentProps } from "react";
@@ -21,6 +22,7 @@ import { useThreadPr, type ThreadPr } from "../../state/use-thread-pr";
 import type { HomeGroupDisplayAction } from "../home/homeListItems";
 import { ThreadSwipeable } from "../home/thread-swipe-actions";
 import { resolveThreadStatus } from "./threadPresentation";
+import { ThreadSearchMatchExcerpt } from "./thread-search-match";
 
 /**
  * Shared presentation for the thread lists: the compact (phone) Home list and
@@ -416,6 +418,8 @@ export const ThreadListRow = memo(function ThreadListRow(props: {
   readonly thread: EnvironmentThreadShell;
   readonly environmentLabel: string | null;
   readonly projectCwd: string | null;
+  readonly searchMatch?: EnvironmentThreadSearchMatch;
+  readonly searchQuery?: string;
   readonly isLast: boolean;
   /** Sidebar only: the thread currently open in the detail pane. */
   readonly selected?: boolean;
@@ -569,6 +573,13 @@ export const ThreadListRow = memo(function ThreadListRow(props: {
                 />
               </View>
             </View>
+            {props.searchMatch ? (
+              <ThreadSearchMatchExcerpt
+                compact
+                match={props.searchMatch}
+                query={props.searchQuery ?? ""}
+              />
+            ) : null}
             {subtitleRow}
           </View>
         </View>
@@ -623,6 +634,13 @@ export const ThreadListRow = memo(function ThreadListRow(props: {
               </Text>
             </View>
           </View>
+          {props.searchMatch ? (
+            <ThreadSearchMatchExcerpt
+              match={props.searchMatch}
+              query={props.searchQuery ?? ""}
+              selected={selected}
+            />
+          ) : null}
           {subtitleRow}
         </View>
       </Pressable>
diff --git a/apps/mobile/src/features/threads/thread-list-v2-items.tsx b/apps/mobile/src/features/threads/thread-list-v2-items.tsx
index 2ab7e6cf9f4..6af5795a94a 100644
--- a/apps/mobile/src/features/threads/thread-list-v2-items.tsx
+++ b/apps/mobile/src/features/threads/thread-list-v2-items.tsx
@@ -2,6 +2,7 @@ import type {
   EnvironmentProject,
   EnvironmentThreadShell,
 } from "@t3tools/client-runtime/state/shell";
+import type { EnvironmentThreadSearchMatch } from "@t3tools/client-runtime/state/thread-search";
 import type { MenuAction } from "@react-native-menu/menu";
 import { memo, useCallback, useEffect, useMemo, type ComponentProps } from "react";
 import { Platform, Pressable, useWindowDimensions, View } from "react-native";
@@ -18,6 +19,7 @@ import type { PendingNewTask } from "../../state/use-pending-new-tasks";
 import { useThreadPr } from "../../state/use-thread-pr";
 import { ThreadSwipeable } from "../home/thread-swipe-actions";
 import { resolveThreadListV2Status, type ThreadListV2Status } from "./threadListV2";
+import { ThreadSearchMatchExcerpt } from "./thread-search-match";
 
 /**
  * Thread List v2 renders one flat native list: rich edge-to-edge rows for
@@ -243,6 +245,8 @@ export const ThreadListV2Row = memo(function ThreadListV2Row(props: {
     state: "open" | "closed" | "merged" | null,
   ) => void;
   readonly projectCwd?: string | null;
+  readonly searchMatch?: EnvironmentThreadSearchMatch;
+  readonly searchQuery?: string;
   readonly simultaneousSwipeGesture?: ComponentProps<
     typeof ThreadSwipeable
   >["simultaneousWithExternalGesture"];
@@ -369,6 +373,15 @@ export const ThreadListV2Row = memo(function ThreadListV2Row(props: {
       >
         {thread.title}
       </Text>
+      {props.searchMatch ? (
+        <View className="mt-1">
+          <ThreadSearchMatchExcerpt
+            match={props.searchMatch}
+            query={props.searchQuery ?? ""}
+            selected={selected}
+          />
+        </View>
+      ) : null}
       <View className="mt-1 flex-row items-center gap-2">
         {status === "failed" && thread.session?.lastError ? (
           <Text
@@ -517,15 +530,24 @@ export const ThreadListV2Row = memo(function ThreadListV2Row(props: {
               />
             </View>
           ) : null}
-          <Text
-            className={cn(
-              "flex-1 text-base",
-              selected ? "text-user-bubble-foreground" : "text-foreground-muted",
-            )}
-            numberOfLines={1}
-          >
-            {thread.title}
-          </Text>
+          <View className="min-w-0 flex-1">
+            <Text
+              className={cn(
+                "text-base",
+                selected ? "text-user-bubble-foreground" : "text-foreground-muted",
+              )}
+              numberOfLines={1}
+            >
+              {thread.title}
+            </Text>
+            {props.searchMatch ? (
+              <ThreadSearchMatchExcerpt
+                match={props.searchMatch}
+                query={props.searchQuery ?? ""}
+                selected={selected}
+              />
+            ) : null}
+          </View>
           <Text
             className={cn(
               "text-sm tabular-nums",
diff --git a/apps/mobile/src/features/threads/thread-search-match.tsx b/apps/mobile/src/features/threads/thread-search-match.tsx
new file mode 100644
index 00000000000..da80ca0766a
--- /dev/null
+++ b/apps/mobile/src/features/threads/thread-search-match.tsx
@@ -0,0 +1,92 @@
+import type { EnvironmentThreadSearchMatch } from "@t3tools/client-runtime/state/thread-search";
+
+import { AppText as Text } from "../../components/AppText";
+import { cn } from "../../lib/cn";
+
+function foldAsciiCase(value: string): string {
+  return value.replace(/[A-Z]/g, (character) => character.toLowerCase());
+}
+
+function splitHighlightParts(text: string, query: string) {
+  const normalizedText = foldAsciiCase(text);
+  const normalizedQuery = foldAsciiCase(query.trim());
+  if (normalizedQuery.length === 0) {
+    return [{ text, highlighted: false, start: 0 }];
+  }
+
+  const parts: Array<{
+    readonly text: string;
+    readonly highlighted: boolean;
+    readonly start: number;
+  }> = [];
+  let cursor = 0;
+  while (cursor < text.length) {
+    const matchIndex = normalizedText.indexOf(normalizedQuery, cursor);
+    if (matchIndex === -1) {
+      parts.push({ text: text.slice(cursor), highlighted: false, start: cursor });
+      break;
+    }
+    if (matchIndex > cursor) {
+      parts.push({
+        text: text.slice(cursor, matchIndex),
+        highlighted: false,
+        start: cursor,
+      });
+    }
+    parts.push({
+      text: text.slice(matchIndex, matchIndex + normalizedQuery.length),
+      highlighted: true,
+      start: matchIndex,
+    });
+    cursor = matchIndex + normalizedQuery.length;
+  }
+  return parts;
+}
+
+export function ThreadSearchMatchExcerpt(props: {
+  readonly match: EnvironmentThreadSearchMatch;
+  readonly query: string;
+  readonly selected?: boolean;
+  readonly compact?: boolean;
+}) {
+  const isUser = props.match.source === "user";
+  const parts = splitHighlightParts(props.match.snippet, props.query);
+  return (
+    <Text
+      className={cn(
+        props.compact ? "text-sm" : "text-xs",
+        props.selected ? "text-user-bubble-foreground-muted" : "text-foreground-muted",
+      )}
+      numberOfLines={1}
+    >
+      <Text
+        className={cn(
+          props.compact ? "text-sm font-t3-medium" : "text-xs font-t3-medium",
+          props.selected
+            ? "text-user-bubble-foreground"
+            : isUser
+              ? "text-blue-500 dark:text-blue-400"
+              : "text-emerald-600 dark:text-emerald-400",
+        )}
+      >
+        {isUser ? "You:" : "Agent:"}{" "}
+      </Text>
+      {parts.map((part) => (
+        <Text
+          className={cn(
+            props.compact ? "text-sm" : "text-xs",
+            part.highlighted && "font-t3-bold",
+            props.selected
+              ? "text-user-bubble-foreground"
+              : part.highlighted
+                ? "text-foreground"
+                : "text-foreground-muted",
+          )}
+          key={part.start}
+        >
+          {part.text}
+        </Text>
+      ))}
+    </Text>
+  );
+}
diff --git a/apps/mobile/src/features/threads/threadListV2.test.ts b/apps/mobile/src/features/threads/threadListV2.test.ts
index 1b15905ef7b..90b5897f18e 100644
--- a/apps/mobile/src/features/threads/threadListV2.test.ts
+++ b/apps/mobile/src/features/threads/threadListV2.test.ts
@@ -1,4 +1,5 @@
 import type { EnvironmentThreadShell } from "@t3tools/client-runtime/state/shell";
+import { threadSearchMatchKey } from "@t3tools/client-runtime/state/thread-search";
 import {
   CommandId,
   EnvironmentId,
@@ -263,6 +264,27 @@ describe("buildThreadListV2Items", () => {
     ]);
   });
 
+  it("includes a thread matched by message content", () => {
+    const thread = makeThread({
+      id: ThreadId.make("content-match"),
+      title: "Unrelated title",
+    });
+    const { items } = buildThreadListV2Items({
+      threads: [thread],
+      environmentId: null,
+      searchQuery: "relay reconnect",
+      matchedThreadKeys: new Set([
+        threadSearchMatchKey({
+          environmentId,
+          threadId: thread.id,
+        }),
+      ]),
+      now: NOW,
+    });
+
+    expect(items.map((item) => item.thread.id)).toEqual(["content-match"]);
+  });
+
   it("scopes the flat list to one project", () => {
     const otherProjectId = ProjectId.make("project-2");
     const { items } = buildThreadListV2Items({
diff --git a/apps/mobile/src/features/threads/threadListV2.ts b/apps/mobile/src/features/threads/threadListV2.ts
index ab955d16d4d..920b7f0b53a 100644
--- a/apps/mobile/src/features/threads/threadListV2.ts
+++ b/apps/mobile/src/features/threads/threadListV2.ts
@@ -1,5 +1,6 @@
 import { effectiveSettled, effectiveSnoozed } from "@t3tools/client-runtime/state/thread-settled";
 import type { EnvironmentThreadShell } from "@t3tools/client-runtime/state/shell";
+import { threadSearchMatchKey } from "@t3tools/client-runtime/state/thread-search";
 import type { EnvironmentId, ProjectId } from "@t3tools/contracts";
 
 import type { PendingNewTask } from "../../state/use-pending-new-tasks";
@@ -183,6 +184,7 @@ export function buildThreadListV2Items(input: {
     readonly projectId: ProjectId;
   }> | null;
   readonly searchQuery: string;
+  readonly matchedThreadKeys?: ReadonlySet<string>;
   /** Per-row PR state reported up by visible rows ("env:threadId" keys). */
   readonly changeRequestStateByKey?: ReadonlyMap<string, "open" | "closed" | "merged">;
   /** Environments whose server supports thread.settle/unsettle. Threads on
@@ -222,7 +224,18 @@ export function buildThreadListV2Items(input: {
     if (projectKeys !== null && !projectKeys.has(`${thread.environmentId}:${thread.projectId}`)) {
       continue;
     }
-    if (query.length > 0 && !thread.title.toLocaleLowerCase().includes(query)) continue;
+    if (
+      query.length > 0 &&
+      !thread.title.toLocaleLowerCase().includes(query) &&
+      input.matchedThreadKeys?.has(
+        threadSearchMatchKey({
+          environmentId: thread.environmentId,
+          threadId: thread.id,
+        }),
+      ) !== true
+    ) {
+      continue;
+    }
     const supportsSettlement = input.settlementEnvironmentIds?.has(thread.environmentId) ?? true;
     const supportsSnooze = input.snoozeEnvironmentIds?.has(thread.environmentId) ?? true;
     const changeRequestState =
diff --git a/apps/mobile/src/state/queries.ts b/apps/mobile/src/state/queries.ts
index ea625995928..b02b190db25 100644
--- a/apps/mobile/src/state/queries.ts
+++ b/apps/mobile/src/state/queries.ts
@@ -1,5 +1,12 @@
 import type { EnvironmentId, OrchestrationThread, ThreadId } from "@t3tools/contracts";
+import {
+  createThreadSearchResultsAtomFamily,
+  makeThreadSearchKey,
+  type EnvironmentThreadSearchMatch,
+} from "@t3tools/client-runtime/state/thread-search";
+import { useAtomValue } from "@effect/atom-react";
 import * as Option from "effect/Option";
+import { Atom } from "effect/unstable/reactivity";
 import { useEffect, useMemo, useState } from "react";
 
 import { orchestrationEnvironment } from "./orchestration";
@@ -15,7 +22,22 @@ import {
 
 const COMPOSER_PATH_SEARCH_DEBOUNCE_MS = 200;
 const COMPOSER_PATH_SEARCH_LIMIT = 20;
+const THREAD_SEARCH_DEBOUNCE_MS = 200;
 const VCS_REF_LIST_LIMIT = 100;
+const EMPTY_THREAD_SEARCH_MATCHES: ReadonlyArray<EnvironmentThreadSearchMatch> = Object.freeze([]);
+const EMPTY_THREAD_SEARCH_ATOM = Atom.make({
+  matches: EMPTY_THREAD_SEARCH_MATCHES,
+  isLoading: false,
+}).pipe(Atom.withLabel("mobile:thread-search:empty"));
+
+const threadSearchResultsAtom = createThreadSearchResultsAtomFamily({
+  getSearchAtom: (environmentId, query) =>
+    orchestrationEnvironment.threadSearch({
+      environmentId,
+      input: { query },
+    }),
+  labelPrefix: "mobile:thread-search",
+});
 
 export interface ThreadDetailView {
   readonly data: OrchestrationThread | null;
@@ -45,6 +67,31 @@ function useDebouncedValue<A>(value: A, delayMs: number): A {
   return debounced;
 }
 
+export function useThreadSearch(
+  environmentIds: ReadonlyArray<EnvironmentId>,
+  query: string,
+): {
+  readonly matches: ReadonlyArray<EnvironmentThreadSearchMatch>;
+  readonly isPending: boolean;
+} {
+  const normalizedQuery = query.trim();
+  const debouncedQuery = useDebouncedValue(normalizedQuery, THREAD_SEARCH_DEBOUNCE_MS);
+  const canSearch = environmentIds.length > 0 && normalizedQuery.length >= 2;
+  const settledQuery = canSearch && normalizedQuery === debouncedQuery ? debouncedQuery : null;
+  const searchKey = useMemo(
+    () => (settledQuery === null ? null : makeThreadSearchKey(environmentIds, settledQuery)),
+    [environmentIds, settledQuery],
+  );
+  const result = useAtomValue(
+    searchKey === null ? EMPTY_THREAD_SEARCH_ATOM : threadSearchResultsAtom(searchKey),
+  );
+  const isDebouncing = canSearch && normalizedQuery !== debouncedQuery;
+  return {
+    matches: isDebouncing ? EMPTY_THREAD_SEARCH_MATCHES : result.matches,
+    isPending: canSearch && (isDebouncing || result.isLoading),
+  };
+}
+
 export function useThreadDetail(
   environmentId: EnvironmentId | null,
   threadId: ThreadId | null,
diff --git a/apps/server/src/auth/RpcAuthorization.ts b/apps/server/src/auth/RpcAuthorization.ts
index b4bea21d2e3..80b1cb4aa1f 100644
--- a/apps/server/src/auth/RpcAuthorization.ts
+++ b/apps/server/src/auth/RpcAuthorization.ts
@@ -24,6 +24,7 @@ export const RPC_REQUIRED_SCOPES = {
   [ORCHESTRATION_WS_METHODS.dispatchCommand]: AuthOrchestrationOperateScope,
   [ORCHESTRATION_WS_METHODS.getTurnDiff]: AuthOrchestrationReadScope,
   [ORCHESTRATION_WS_METHODS.getFullThreadDiff]: AuthOrchestrationReadScope,
+  [ORCHESTRATION_WS_METHODS.searchThreads]: AuthOrchestrationReadScope,
   [ORCHESTRATION_WS_METHODS.subscribeShell]: AuthOrchestrationReadScope,
   [ORCHESTRATION_WS_METHODS.getArchivedShellSnapshot]: AuthOrchestrationReadScope,
   [ORCHESTRATION_WS_METHODS.subscribeThread]: AuthOrchestrationReadScope,
diff --git a/apps/server/src/checkpointing/CheckpointDiffQuery.test.ts b/apps/server/src/checkpointing/CheckpointDiffQuery.test.ts
index 8e0e5fb74d5..fe093c451e2 100644
--- a/apps/server/src/checkpointing/CheckpointDiffQuery.test.ts
+++ b/apps/server/src/checkpointing/CheckpointDiffQuery.test.ts
@@ -108,6 +108,7 @@ describe("CheckpointDiffQuery.layer", () => {
             getThreadShellById: () => Effect.succeed(Option.none()),
             getThreadDetailById: () => Effect.succeed(Option.none()),
             getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
+            searchThreads: () => Effect.succeed({ matches: [] }),
           }),
         ),
       );
@@ -201,6 +202,7 @@ describe("CheckpointDiffQuery.layer", () => {
             getThreadShellById: () => Effect.succeed(Option.none()),
             getThreadDetailById: () => Effect.succeed(Option.none()),
             getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
+            searchThreads: () => Effect.succeed({ matches: [] }),
           }),
         ),
       );
@@ -284,6 +286,7 @@ describe("CheckpointDiffQuery.layer", () => {
             getThreadShellById: () => Effect.succeed(Option.none()),
             getThreadDetailById: () => Effect.succeed(Option.none()),
             getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
+            searchThreads: () => Effect.succeed({ matches: [] }),
           }),
         ),
       );
@@ -352,6 +355,7 @@ describe("CheckpointDiffQuery.layer", () => {
             getThreadShellById: () => Effect.succeed(Option.none()),
             getThreadDetailById: () => Effect.succeed(Option.none()),
             getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
+            searchThreads: () => Effect.succeed({ matches: [] }),
           }),
         ),
       );
@@ -405,6 +409,7 @@ describe("CheckpointDiffQuery.layer", () => {
             getThreadShellById: () => Effect.succeed(Option.none()),
             getThreadDetailById: () => Effect.succeed(Option.none()),
             getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
+            searchThreads: () => Effect.succeed({ matches: [] }),
           }),
         ),
       );
diff --git a/apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts b/apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts
index 3c039d2260f..9ffe50d1341 100644
--- a/apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts
+++ b/apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts
@@ -203,6 +203,7 @@ describe("OrchestrationEngine", () => {
           getThreadShellById: () => Effect.succeed(Option.none()),
           getThreadDetailById: () => Effect.succeed(Option.none()),
           getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
+          searchThreads: () => Effect.succeed({ matches: [] }),
         }),
       ),
       Layer.provide(
diff --git a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts
index 12afffea7e7..6fe7f831a03 100644
--- a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts
+++ b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts
@@ -1551,6 +1551,271 @@ projectionSnapshotLayer("ProjectionSnapshotQuery", (it) => {
       assert.equal(shellSnapshot.threads.length, 0);
     }),
   );
+
+  it.effect("searches active user messages and canonical assistant outputs", () =>
+    Effect.gen(function* () {
+      const snapshotQuery = yield* ProjectionSnapshotQuery;
+      const sql = yield* SqlClient.SqlClient;
+
+      yield* sql`DELETE FROM projection_thread_messages`;
+      yield* sql`DELETE FROM projection_turns`;
+      yield* sql`DELETE FROM projection_threads`;
+      yield* sql`DELETE FROM projection_projects`;
+
+      yield* sql`
+        INSERT INTO projection_projects (
+          project_id,
+          title,
+          workspace_root,
+          default_model_selection_json,
+          scripts_json,
+          created_at,
+          updated_at,
+          deleted_at
+        )
+        VALUES (
+          'project-search',
+          'Project Needle',
+          '/tmp/project-search',
+          '{"provider":"codex","model":"gpt-5-codex"}',
+          '[]',
+          '2026-05-01T00:00:00.000Z',
+          '2026-05-01T00:00:01.000Z',
+          NULL
+        )
+      `;
+
+      yield* sql`
+        INSERT INTO projection_threads (
+          thread_id,
+          project_id,
+          title,
+          model_selection_json,
+          runtime_mode,
+          interaction_mode,
+          branch,
+          worktree_path,
+          latest_turn_id,
+          latest_user_message_at,
+          pending_approval_count,
+          pending_user_input_count,
+          has_actionable_proposed_plan,
+          created_at,
+          updated_at,
+          archived_at,
+          deleted_at
+        )
+        VALUES
+          (
+            'thread-active',
+            'project-search',
+            'Literal 100% fix',
+            '{"provider":"codex","model":"gpt-5-codex"}',
+            'full-access',
+            'default',
+            'search-branch',
+            NULL,
+            'turn-active',
+            '2026-05-01T00:00:02.000Z',
+            0,
+            0,
+            0,
+            '2026-05-01T00:00:02.000Z',
+            '2026-05-01T00:00:03.000Z',
+            NULL,
+            NULL
+          ),
+          (
+            'thread-percent-decoy',
+            'project-search',
+            'Literal 100x fix',
+            '{"provider":"codex","model":"gpt-5-codex"}',
+            'full-access',
+            'default',
+            NULL,
+            NULL,
+            NULL,
+            NULL,
+            0,
+            0,
+            0,
+            '2026-05-01T00:00:04.000Z',
+            '2026-05-01T00:00:05.000Z',
+            NULL,
+            NULL
+          ),
+          (
+            'thread-hidden',
+            'project-search',
+            'Archived search',
+            '{"provider":"codex","model":"gpt-5-codex"}',
+            'full-access',
+            'default',
+            NULL,
+            NULL,
+            NULL,
+            NULL,
+            0,
+            0,
+            0,
+            '2026-05-01T00:00:06.000Z',
+            '2026-05-01T00:00:07.000Z',
+            '2026-05-01T00:00:08.000Z',
+            NULL
+          )
+      `;
+
+      yield* sql`
+        INSERT INTO projection_thread_messages (
+          message_id,
+          thread_id,
+          turn_id,
+          role,
+          text,
+          is_streaming,
+          created_at,
+          updated_at
+        )
+        VALUES
+          (
+            'message-user',
+            'thread-active',
+            'turn-active',
+            'user',
+            'Please find this USER needle in an old prompt.',
+            0,
+            '2026-05-01T00:00:12.000Z',
+            '2026-05-01T00:00:12.000Z'
+          ),
+          (
+            'message-percent',
+            'thread-active',
+            NULL,
+            'user',
+            'Literal 100% fix in a prompt.',
+            0,
+            '2026-05-01T00:00:11.000Z',
+            '2026-05-01T00:00:11.000Z'
+          ),
+          (
+            'message-percent-decoy',
+            'thread-percent-decoy',
+            NULL,
+            'user',
+            'Literal 100x fix in a prompt.',
+            0,
+            '2026-05-01T00:00:11.000Z',
+            '2026-05-01T00:00:11.000Z'
+          ),
+          (
+            'message-final',
+            'thread-active',
+            'turn-active',
+            'assistant',
+            'The canonical final needle appears in this completed answer.',
+            0,
+            '2026-05-01T00:00:13.000Z',
+            '2026-05-01T00:00:13.000Z'
+          ),
+          (
+            'message-interim',
+            'thread-active',
+            'turn-active',
+            'assistant',
+            'Interim needle must not be searchable.',
+            0,
+            '2026-05-01T00:00:14.000Z',
+            '2026-05-01T00:00:14.000Z'
+          ),
+          (
+            'message-system',
+            'thread-active',
+            NULL,
+            'system',
+            'System needle must not be searchable.',
+            0,
+            '2026-05-01T00:00:15.000Z',
+            '2026-05-01T00:00:15.000Z'
+          ),
+          (
+            'message-hidden',
+            'thread-hidden',
+            NULL,
+            'user',
+            'Hidden needle in archive.',
+            0,
+            '2026-05-01T00:00:16.000Z',
+            '2026-05-01T00:00:16.000Z'
+          )
+      `;
+
+      yield* sql`
+        INSERT INTO projection_turns (
+          thread_id,
+          turn_id,
+          pending_message_id,
+          assistant_message_id,
+          state,
+          requested_at,
+          started_at,
+          completed_at,
+          checkpoint_files_json
+        )
+        VALUES (
+          'thread-active',
+          'turn-active',
+          'message-user',
+          'message-final',
+          'completed',
+          '2026-05-01T00:00:12.000Z',
+          '2026-05-01T00:00:12.000Z',
+          '2026-05-01T00:00:13.000Z',
+          '[]'
+        )
+      `;
+
+      const literalPercent = yield* snapshotQuery.searchThreads({ query: "100%" });
+      assert.deepStrictEqual(
+        literalPercent.matches.map((match) => [match.threadId, match.source]),
+        [[ThreadId.make("thread-active"), "user"]],
+      );
+
+      const user = yield* snapshotQuery.searchThreads({ query: "user needle" });
+      assert.equal(user.matches[0]?.source, "user");
+      assert.match(user.matches[0]?.snippet ?? "", /USER needle/);
+
+      const assistant = yield* snapshotQuery.searchThreads({ query: "FINAL NEEDLE" });
+      assert.equal(assistant.matches[0]?.source, "assistant");
+
+      const deduped = yield* snapshotQuery.searchThreads({ query: "needle" });
+      assert.deepStrictEqual(
+        deduped.matches.map((match) => [match.threadId, match.source]),
+        [[ThreadId.make("thread-active"), "user"]],
+      );
+
+      assert.deepStrictEqual(
+        (yield* snapshotQuery.searchThreads({ query: "interim needle" })).matches,
+        [],
+      );
+      assert.deepStrictEqual(
+        (yield* snapshotQuery.searchThreads({ query: "system needle" })).matches,
+        [],
+      );
+      assert.deepStrictEqual(
+        (yield* snapshotQuery.searchThreads({ query: "hidden needle" })).matches,
+        [],
+      );
+      yield* sql`
+        UPDATE projection_threads
+        SET deleted_at = '2026-05-01T00:00:20.000Z'
+        WHERE thread_id = 'thread-active'
+      `;
+      assert.deepStrictEqual(
+        (yield* snapshotQuery.searchThreads({ query: "user needle" })).matches,
+        [],
+      );
+    }),
+  );
 });
 
 it.effect(
diff --git a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts
index 1cd4289fe0c..4dcc43913c4 100644
--- a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts
+++ b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts
@@ -7,6 +7,7 @@ import {
   OrchestrationCheckpointFile,
   OrchestrationProposedPlanId,
   OrchestrationReadModel,
+  OrchestrationThreadSearchSource,
   OrchestrationShellSnapshot,
   OrchestrationThread,
   OrchestrationThreadDetailSnapshot,
@@ -108,6 +109,17 @@ const ProjectionCountsRowSchema = Schema.Struct({
   projectCount: Schema.Number,
   threadCount: Schema.Number,
 });
+const ProjectionThreadSearchRequest = Schema.Struct({
+  pattern: Schema.String,
+  limit: Schema.Int,
+});
+const ProjectionThreadSearchRow = Schema.Struct({
+  threadId: ThreadId,
+  projectId: ProjectId,
+  source: OrchestrationThreadSearchSource,
+  matchText: Schema.String,
+  messageCreatedAt: Schema.NullOr(IsoDateTime),
+});
 const WorkspaceRootLookupInput = Schema.Struct({
   workspaceRoot: Schema.String,
 });
@@ -157,6 +169,31 @@ function maxIso(left: string | null, right: string): string {
   return left > right ? left : right;
 }
 
+function escapeLikePattern(value: string): string {
+  return value.replaceAll("!", "!!").replaceAll("%", "!%").replaceAll("_", "!_");
+}
+
+function foldAsciiCase(value: string): string {
+  return value.replace(/[A-Z]/g, (character) => character.toLowerCase());
+}
+
+function buildSearchSnippet(text: string, query: string): string {
+  const normalizedText = text.replace(/\s+/g, " ").trim();
+  if (normalizedText.length <= 240) {
+    return normalizedText;
+  }
+
+  const normalizedQuery = foldAsciiCase(query.replace(/\s+/g, " ").trim());
+  const matchIndex = foldAsciiCase(normalizedText).indexOf(normalizedQuery);
+  const bodyLength = 236;
+  const idealStart = Math.max(0, matchIndex - 72);
+  const start = Math.min(idealStart, normalizedText.length - bodyLength);
+  const end = Math.min(normalizedText.length, start + bodyLength);
+  return `${start > 0 ? "…" : ""}${normalizedText.slice(start, end)}${
+    end < normalizedText.length ? "…" : ""
+  }`;
+}
+
 function computeSnapshotSequence(
   stateRows: ReadonlyArray<Schema.Schema.Type<typeof ProjectionStateDbRowSchema>>,
 ): number {
@@ -685,6 +722,74 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
       `,
   });
 
+  const searchActiveThreadRows = SqlSchema.findAll({
+    Request: ProjectionThreadSearchRequest,
+    Result: ProjectionThreadSearchRow,
+    execute: ({ pattern, limit }) =>
+      sql`
+        WITH ranked AS (
+          SELECT
+            threads.thread_id AS thread_id,
+            threads.project_id AS project_id,
+            CASE messages.role
+              WHEN 'user' THEN 'user'
+              ELSE 'assistant'
+            END AS source,
+            messages.text AS match_text,
+            messages.created_at AS message_created_at,
+            CASE messages.role
+              WHEN 'user' THEN 0
+              ELSE 1
+            END AS match_rank,
+            threads.updated_at AS thread_updated_at,
+            ROW_NUMBER() OVER (
+              PARTITION BY threads.thread_id
+              ORDER BY
+                CASE messages.role
+                  WHEN 'user' THEN 0
+                  ELSE 1
+                END ASC,
+                messages.created_at DESC,
+                messages.message_id ASC
+            ) AS thread_match_rank
+          FROM projection_thread_messages AS messages
+          INNER JOIN projection_threads AS threads
+            ON threads.thread_id = messages.thread_id
+          INNER JOIN projection_projects AS projects
+            ON projects.project_id = threads.project_id
+          WHERE threads.deleted_at IS NULL
+            AND threads.archived_at IS NULL
+            AND projects.deleted_at IS NULL
+            AND messages.is_streaming = 0
+            AND (
+              messages.role = 'user'
+              OR (
+                messages.role = 'assistant'
+                AND messages.message_id IN (
+                  SELECT turns.assistant_message_id
+                  FROM projection_turns AS turns
+                  WHERE turns.assistant_message_id IS NOT NULL
+                )
+              )
+            )
+            AND messages.text LIKE ${pattern} ESCAPE '!'
+        )
+        SELECT
+          thread_id AS "threadId",
+          project_id AS "projectId",
+          source,
+          match_text AS "matchText",
+          message_created_at AS "messageCreatedAt"
+        FROM ranked
+        WHERE thread_match_rank = 1
+        ORDER BY
+          match_rank ASC,
+          thread_updated_at DESC,
+          thread_id ASC
+        LIMIT ${limit}
+      `,
+  });
+
   const getActiveProjectRowByWorkspaceRoot = SqlSchema.findOneOption({
     Request: WorkspaceRootLookupInput,
     Result: ProjectionProjectLookupRowSchema,
@@ -1758,6 +1863,32 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
       ),
     );
 
+  const searchThreads: ProjectionSnapshotQueryShape["searchThreads"] = Effect.fn(
+    "ProjectionSnapshotQuery.searchThreads",
+  )(function* (input) {
+    const escapedQuery = escapeLikePattern(input.query);
+    const rows = yield* searchActiveThreadRows({
+      pattern: `%${escapedQuery}%`,
+      limit: input.limit ?? 50,
+    }).pipe(
+      Effect.mapError(
+        toPersistenceSqlOrDecodeError(
+          "ProjectionSnapshotQuery.searchThreads:query",
+          "ProjectionSnapshotQuery.searchThreads:decodeRows",
+        ),
+      ),
+    );
+    return {
+      matches: rows.map((row) => ({
+        threadId: row.threadId,
+        projectId: row.projectId,
+        source: row.source,
+        snippet: buildSearchSnippet(row.matchText, input.query),
+        messageCreatedAt: row.messageCreatedAt,
+      })),
+    };
+  });
+
   const getActiveProjectByWorkspaceRoot: ProjectionSnapshotQueryShape["getActiveProjectByWorkspaceRoot"] =
     (workspaceRoot) =>
       getActiveProjectRowByWorkspaceRoot({ workspaceRoot }).pipe(
@@ -2131,6 +2262,7 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
     getSnapshot,
     getShellSnapshot,
     getArchivedShellSnapshot,
+    searchThreads,
     getSnapshotSequence,
     getCounts,
     getActiveProjectByWorkspaceRoot,
diff --git a/apps/server/src/orchestration/Services/ProjectionSnapshotQuery.ts b/apps/server/src/orchestration/Services/ProjectionSnapshotQuery.ts
index 23b291d8778..64138fb7559 100644
--- a/apps/server/src/orchestration/Services/ProjectionSnapshotQuery.ts
+++ b/apps/server/src/orchestration/Services/ProjectionSnapshotQuery.ts
@@ -12,6 +12,8 @@ import type {
   OrchestrationProject,
   OrchestrationProjectShell,
   OrchestrationReadModel,
+  OrchestrationSearchThreadsInput,
+  OrchestrationSearchThreadsResult,
   OrchestrationShellSnapshot,
   OrchestrationThread,
   OrchestrationThreadDetailSnapshot,
@@ -94,6 +96,14 @@ export interface ProjectionSnapshotQueryShape {
     ProjectionRepositoryError
   >;
 
+  /**
+   * Search active thread navigation metadata, user messages, and canonical
+   * assistant outputs without hydrating thread detail snapshots.
+   */
+  readonly searchThreads: (
+    input: OrchestrationSearchThreadsInput,
+  ) => Effect.Effect<OrchestrationSearchThreadsResult, ProjectionRepositoryError>;
+
   /**
    * Read the latest projection snapshot sequence without hydrating read-model
    * entities.
diff --git a/apps/server/src/project/ProjectSetupScriptRunner.test.ts b/apps/server/src/project/ProjectSetupScriptRunner.test.ts
index 15612908079..5c5da4666b0 100644
--- a/apps/server/src/project/ProjectSetupScriptRunner.test.ts
+++ b/apps/server/src/project/ProjectSetupScriptRunner.test.ts
@@ -44,6 +44,7 @@ const makeProjectionSnapshotQueryLayer = (project: OrchestrationProject) =>
     getThreadShellById: () => Effect.die("unused"),
     getThreadDetailById: () => Effect.die("unused"),
     getThreadDetailSnapshot: () => Effect.die("unused"),
+    searchThreads: () => Effect.succeed({ matches: [] }),
   });
 
 const makeTerminalManagerLayer = (
diff --git a/apps/server/src/provider/Layers/ProviderSessionReaper.test.ts b/apps/server/src/provider/Layers/ProviderSessionReaper.test.ts
index 3843c8acbcd..f3f4ca39d47 100644
--- a/apps/server/src/provider/Layers/ProviderSessionReaper.test.ts
+++ b/apps/server/src/provider/Layers/ProviderSessionReaper.test.ts
@@ -212,6 +212,7 @@ describe("ProviderSessionReaper", () => {
             ),
           getThreadDetailById: () => Effect.die("unused"),
           getThreadDetailSnapshot: () => Effect.die("unused"),
+          searchThreads: () => Effect.succeed({ matches: [] }),
         }),
       ),
       Layer.provideMerge(NodeServices.layer),
diff --git a/apps/server/src/server.test.ts b/apps/server/src/server.test.ts
index 0b233d7d9f7..fff71dbb4e7 100644
--- a/apps/server/src/server.test.ts
+++ b/apps/server/src/server.test.ts
@@ -729,6 +729,7 @@ const buildAppUnderTest = (options?: {
               threads: [],
               updatedAt: "1970-01-01T00:00:00.000Z",
             }),
+          searchThreads: () => Effect.succeed({ matches: [] }),
           getSnapshotSequence: () => Effect.succeed({ snapshotSequence: 0 }),
           getProjectShellById: () => Effect.succeed(Option.none()),
           getThreadShellById: () => Effect.succeed(Option.none()),
@@ -5723,6 +5724,18 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
         layers: {
           projectionSnapshotQuery: {
             getSnapshot: () => Effect.succeed(snapshot),
+            searchThreads: () =>
+              Effect.succeed({
+                matches: [
+                  {
+                    threadId: ThreadId.make("thread-1"),
+                    projectId: ProjectId.make("project-a"),
+                    source: "assistant",
+                    snippet: "Search reached the final response.",
+                    messageCreatedAt: now,
+                  },
+                ],
+              }),
           },
           orchestrationEngine: {
             dispatch: () => Effect.succeed({ sequence: 7 }),
@@ -5780,6 +5793,23 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
         ),
       );
       assert.equal(fullDiffResult.diff, "full-diff");
+
+      const searchResult = yield* Effect.scoped(
+        withWsRpcClient(wsUrl, (client) =>
+          client[ORCHESTRATION_WS_METHODS.searchThreads]({
+            query: "final response",
+          }),
+        ),
+      );
+      assert.deepEqual(searchResult.matches, [
+        {
+          threadId: ThreadId.make("thread-1"),
+          projectId: ProjectId.make("project-a"),
+          source: "assistant",
+          snippet: "Search reached the final response.",
+          messageCreatedAt: now,
+        },
+      ]);
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
diff --git a/apps/server/src/serverRuntimeStartup.test.ts b/apps/server/src/serverRuntimeStartup.test.ts
index b8102bda9ad..e3f7e482b2e 100644
--- a/apps/server/src/serverRuntimeStartup.test.ts
+++ b/apps/server/src/serverRuntimeStartup.test.ts
@@ -97,6 +97,7 @@ it.effect("launchStartupHeartbeat does not block the caller while counts are loa
           getThreadShellById: () => Effect.succeed(Option.none()),
           getThreadDetailById: () => Effect.succeed(Option.none()),
           getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
+          searchThreads: () => Effect.succeed({ matches: [] }),
         }),
         Effect.provideService(AnalyticsService.AnalyticsService, {
           record: () => Effect.void,
@@ -160,6 +161,7 @@ it.effect("resolveAutoBootstrapWelcomeTargets returns existing project and threa
         getThreadShellById: () => Effect.die("unused"),
         getThreadDetailById: () => Effect.die("unused"),
         getThreadDetailSnapshot: () => Effect.die("unused"),
+        searchThreads: () => Effect.succeed({ matches: [] }),
       }),
       Effect.provideService(OrchestrationEngine.OrchestrationEngineService, {
         readEvents: () => Stream.empty,
@@ -204,6 +206,7 @@ it.effect("resolveAutoBootstrapWelcomeTargets creates a project and thread when
         getThreadShellById: () => Effect.die("unused"),
         getThreadDetailById: () => Effect.die("unused"),
         getThreadDetailSnapshot: () => Effect.die("unused"),
+        searchThreads: () => Effect.succeed({ matches: [] }),
       }),
       Effect.provideService(OrchestrationEngine.OrchestrationEngineService, {
         readEvents: () => Stream.empty,
@@ -254,6 +257,7 @@ it.effect("resolveAutoBootstrapWelcomeTargets preserves typed UUID generation fa
         getThreadShellById: () => Effect.die("unused"),
         getThreadDetailById: () => Effect.die("unused"),
         getThreadDetailSnapshot: () => Effect.die("unused"),
+        searchThreads: () => Effect.succeed({ matches: [] }),
       }),
       Effect.provideService(OrchestrationEngine.OrchestrationEngineService, {
         readEvents: () => Stream.empty,
diff --git a/apps/server/src/ws.ts b/apps/server/src/ws.ts
index e33c6992bbb..935d7edec92 100644
--- a/apps/server/src/ws.ts
+++ b/apps/server/src/ws.ts
@@ -28,6 +28,7 @@ import {
   type OrchestrationThreadStreamItem,
   OrchestrationGetFullThreadDiffError,
   OrchestrationGetSnapshotError,
+  OrchestrationSearchThreadsError,
   OrchestrationGetTurnDiffError,
   ORCHESTRATION_WS_METHODS,
   type ProjectId,
@@ -1103,6 +1104,20 @@ const makeWsRpcLayer = (
             ),
             { "rpc.aggregate": "orchestration" },
           ),
+        [ORCHESTRATION_WS_METHODS.searchThreads]: (input) =>
+          observeRpcEffect(
+            ORCHESTRATION_WS_METHODS.searchThreads,
+            projectionSnapshotQuery.searchThreads(input).pipe(
+              Effect.mapError(
+                (cause) =>
+                  new OrchestrationSearchThreadsError({
+                    message: "Failed to search threads",
+                    cause,
+                  }),
+              ),
+            ),
+            { "rpc.aggregate": "orchestration" },
+          ),
         [ORCHESTRATION_WS_METHODS.subscribeShell]: (input) =>
           observeRpcStreamEffect(
             ORCHESTRATION_WS_METHODS.subscribeShell,
diff --git a/apps/web/src/components/CommandPalette.logic.test.ts b/apps/web/src/components/CommandPalette.logic.test.ts
index 04de1784715..5b4accc9fc7 100644
--- a/apps/web/src/components/CommandPalette.logic.test.ts
+++ b/apps/web/src/components/CommandPalette.logic.test.ts
@@ -169,6 +169,29 @@ describe("buildThreadActionItems", () => {
     expect(groups[0]?.items.map((item) => item.value)).toEqual(["thread:project-context-only"]);
   });
 
+  it("keeps message excerpts searchable without replacing thread metadata", () => {
+    const [item] = buildThreadActionItems({
+      threads: [makeThread({ branch: "feat/search" })],
+      projectTitleById: new Map([[PROJECT_ID, "T3 Code"]]),
+      sortOrder: "updated_at",
+      icon: null,
+      getContentMatch: () => ({
+        source: "assistant",
+        snippet: "The relay reconnect is now bounded.",
+        query: "reconnect",
+      }),
+      runThread: async (_thread) => undefined,
+    });
+
+    expect(item?.searchTerms).toContain("The relay reconnect is now bounded.");
+    expect(item?.threadContentMatch).toEqual({
+      source: "assistant",
+      snippet: "The relay reconnect is now bounded.",
+      query: "reconnect",
+    });
+    expect(item?.description).toBe("T3 Code · #feat/search");
+  });
+
   it("filters archived threads out of thread search items", () => {
     const items = buildThreadActionItems({
       threads: [
diff --git a/apps/web/src/components/CommandPalette.logic.ts b/apps/web/src/components/CommandPalette.logic.ts
index 058322744bb..7a07cc48481 100644
--- a/apps/web/src/components/CommandPalette.logic.ts
+++ b/apps/web/src/components/CommandPalette.logic.ts
@@ -15,12 +15,19 @@ export const RECENT_THREAD_LIMIT = 12;
 export const ITEM_ICON_CLASS = "size-4 text-muted-foreground/80";
 export const ADDON_ICON_CLASS = "size-4";
 
+export interface CommandPaletteThreadContentMatch {
+  readonly source: "user" | "assistant";
+  readonly snippet: string;
+  readonly query: string;
+}
+
 export interface CommandPaletteItem {
   readonly kind: "action" | "submenu";
   readonly value: string;
   readonly searchTerms: ReadonlyArray<string>;
   readonly title: ReactNode;
   readonly description?: string;
+  readonly threadContentMatch?: CommandPaletteThreadContentMatch;
   readonly timestamp?: string;
   readonly icon: ReactNode;
   readonly disabled?: boolean;
@@ -114,6 +121,7 @@ export function buildThreadActionItems<TThread extends BuildThreadActionItemsThr
   renderLeadingContent?: (thread: TThread) => ReactNode;
   /** Optional content rendered inline after the title text per-thread. */
   renderTrailingContent?: (thread: TThread) => ReactNode;
+  getContentMatch?: (thread: TThread) => CommandPaletteThreadContentMatch | undefined;
   runThread: (thread: Pick<SidebarThreadSummary, "environmentId" | "id">) => Promise<void>;
   limit?: number;
 }): CommandPaletteActionItem[] {
@@ -140,12 +148,18 @@ export function buildThreadActionItems<TThread extends BuildThreadActionItemsThr
 
     const leadingContent = input.renderLeadingContent?.(thread);
     const trailingContent = input.renderTrailingContent?.(thread);
+    const contentMatch = input.getContentMatch?.(thread);
 
     return Object.assign(
       {
         kind: "action" as const,
         value: `thread:${thread.id}`,
-        searchTerms: [thread.title, projectTitle ?? ``, thread.branch ?? ``],
+        searchTerms: [
+          thread.title,
+          projectTitle ?? ``,
+          thread.branch ?? ``,
+          contentMatch?.snippet ?? ``,
+        ],
         title: thread.title,
         description: descriptionParts.join(` · `),
         timestamp: formatRelativeTimeLabel(
@@ -155,6 +169,7 @@ export function buildThreadActionItems<TThread extends BuildThreadActionItemsThr
       },
       leadingContent ? { titleLeadingContent: leadingContent } : {},
       trailingContent ? { titleTrailingContent: trailingContent } : {},
+      contentMatch ? { threadContentMatch: contentMatch } : {},
       {
         run: async () => {
           await input.runThread(thread);
diff --git a/apps/web/src/components/CommandPalette.tsx b/apps/web/src/components/CommandPalette.tsx
index 45b5e117600..94870fef3eb 100644
--- a/apps/web/src/components/CommandPalette.tsx
+++ b/apps/web/src/components/CommandPalette.tsx
@@ -3,6 +3,7 @@
 import { scopeProjectRef, scopeThreadRef } from "@t3tools/client-runtime/environment";
 import { canCreateProjectInEnvironment } from "@t3tools/client-runtime/operations/projects";
 import { connectionStatusText } from "@t3tools/client-runtime/connection";
+import { threadSearchMatchKey } from "@t3tools/client-runtime/state/thread-search";
 import {
   canPreloadBrowsePath,
   createBrowseNavigationCoordinator,
@@ -66,6 +67,7 @@ import { useAtomCommand } from "../state/use-atom-command";
 import { useAtomQueryRunner } from "../state/use-atom-query-runner";
 import { useEnvironments, usePrimaryEnvironmentId } from "../state/environments";
 import { useProjects, useThreadShells } from "../state/entities";
+import { useThreadSearch } from "../state/queries";
 import { resolveThreadActionProjectRef, startNewThreadFromContext } from "../lib/chatThreadActions";
 import {
   appendBrowsePathSegment,
@@ -510,6 +512,26 @@ function OpenCommandPaletteDialog(props: {
   const providers = useAtomValue(primaryServerProvidersAtom);
   const [viewStack, setViewStack] = useState<CommandPaletteView[]>([]);
   const currentView = viewStack.at(-1) ?? null;
+  const environmentIds = useMemo(
+    () =>
+      environments
+        .filter((environment) => environment.connection.phase === "connected")
+        .map((environment) => environment.environmentId),
+    [environments],
+  );
+  const threadSearchQuery = currentView === null && !isActionsOnly ? deferredQuery : "";
+  const threadSearch = useThreadSearch(environmentIds, threadSearchQuery);
+  const threadContentMatchByKey = useMemo(
+    () =>
+      new Map(
+        threadSearch.matches.flatMap((match) =>
+          match.source === "user" || match.source === "assistant"
+            ? [[threadSearchMatchKey(match), match] as const]
+            : [],
+        ),
+      ),
+    [threadSearch.matches],
+  );
   const [browseGeneration, setBrowseGeneration] = useState(0);
   const browseNavigationRef = useRef<ReturnType<typeof createBrowseNavigationCoordinator> | null>(
     null,
@@ -916,6 +938,21 @@ function OpenCommandPaletteDialog(props: {
         icon: <MessageSquareIcon className={ITEM_ICON_CLASS} />,
         renderLeadingContent: (thread) => <ThreadRowLeadingStatus thread={thread} />,
         renderTrailingContent: (thread) => <ThreadRowTrailingStatus thread={thread} />,
+        getContentMatch: (thread) => {
+          const match = threadContentMatchByKey.get(
+            threadSearchMatchKey({
+              environmentId: thread.environmentId,
+              threadId: thread.id,
+            }),
+          );
+          return match && (match.source === "user" || match.source === "assistant")
+            ? {
+                source: match.source,
+                snippet: match.snippet,
+                query: threadSearchQuery,
+              }
+            : undefined;
+        },
         runThread: async (thread) => {
           await navigate({
             to: "/$environmentId/$threadId",
@@ -923,7 +960,15 @@ function OpenCommandPaletteDialog(props: {
           });
         },
       }),
-    [activeThreadId, clientSettings.sidebarThreadSortOrder, navigate, projectTitleById, threads],
+    [
+      activeThreadId,
+      clientSettings.sidebarThreadSortOrder,
+      navigate,
+      projectTitleById,
+      threadContentMatchByKey,
+      threadSearchQuery,
+      threads,
+    ],
   );
   const recentThreadItems = allThreadItems.slice(0, RECENT_THREAD_LIMIT);
 
@@ -2194,7 +2239,9 @@ function OpenCommandPaletteDialog(props: {
                         emptyStateMessage:
                           "Press Enter to create this folder and add it as a project.",
                       }
-                    : {})}
+                    : threadSearch.isPending
+                      ? { emptyStateMessage: "Searching thread messages…" }
+                      : {})}
           />
         </CommandPanel>
         <CommandFooter className="gap-3 max-sm:flex-col max-sm:items-start">
diff --git a/apps/web/src/components/CommandPaletteResults.tsx b/apps/web/src/components/CommandPaletteResults.tsx
index 532d546df9a..2ab4ef8f3f8 100644
--- a/apps/web/src/components/CommandPaletteResults.tsx
+++ b/apps/web/src/components/CommandPaletteResults.tsx
@@ -16,6 +16,69 @@ import {
 } from "./ui/command";
 import { cn } from "~/lib/utils";
 
+function foldAsciiCase(value: string): string {
+  return value.replace(/[A-Z]/g, (character) => character.toLowerCase());
+}
+
+function HighlightedSearchText(props: { text: string; query: string }) {
+  const query = props.query.trim();
+  if (query.length === 0) return props.text;
+
+  const normalizedText = foldAsciiCase(props.text);
+  const normalizedQuery = foldAsciiCase(query);
+  const parts: Array<{
+    readonly text: string;
+    readonly highlighted: boolean;
+    readonly start: number;
+  }> = [];
+  let cursor = 0;
+
+  while (cursor < props.text.length) {
+    const matchIndex = normalizedText.indexOf(normalizedQuery, cursor);
+    if (matchIndex === -1) {
+      parts.push({ text: props.text.slice(cursor), highlighted: false, start: cursor });
+      break;
+    }
+    if (matchIndex > cursor) {
+      parts.push({
+        text: props.text.slice(cursor, matchIndex),
+        highlighted: false,
+        start: cursor,
+      });
+    }
+    parts.push({
+      text: props.text.slice(matchIndex, matchIndex + query.length),
+      highlighted: true,
+      start: matchIndex,
+    });
+    cursor = matchIndex + query.length;
+  }
+
+  return parts.map((part) =>
+    part.highlighted ? (
+      <mark className="bg-transparent font-semibold text-foreground" key={part.start}>
+        {part.text}
+      </mark>
+    ) : (
+      part.text
+    ),
+  );
+}
+
+function ThreadContentMatch(props: {
+  match: NonNullable<CommandPaletteActionItem["threadContentMatch"]>;
+}) {
+  const isUser = props.match.source === "user";
+  return (
+    <span className="truncate text-xs text-muted-foreground/85">
+      <span className={isUser ? "text-blue-400" : "text-emerald-400"}>
+        {isUser ? "You:" : "Agent:"}
+      </span>{" "}
+      <HighlightedSearchText text={props.match.snippet} query={props.match.query} />
+    </span>
+  );
+}
+
 interface CommandPaletteResultsProps {
   emptyStateMessage?: string;
   groups: ReadonlyArray<CommandPaletteGroup>;
@@ -69,15 +132,20 @@ function DisabledCommandPaletteResultRow(props: {
   return (
     <div className="flex min-h-8 select-none items-center gap-2 rounded-sm px-2 py-1.5 text-base opacity-64 sm:min-h-7 sm:text-sm">
       {props.item.icon}
-      {props.item.description ? (
+      {props.item.description || props.item.threadContentMatch ? (
         <span className="flex min-w-0 flex-1 flex-col">
           <span className="flex min-w-0 items-center gap-1.5 text-sm text-foreground">
             {props.item.titleLeadingContent}
             <span className="truncate">{props.item.title}</span>
           </span>
-          <span className="truncate text-muted-foreground/85 text-xs">
-            {props.item.description}
-          </span>
+          {props.item.threadContentMatch ? (
+            <ThreadContentMatch match={props.item.threadContentMatch} />
+          ) : null}
+          {props.item.description ? (
+            <span className="truncate text-muted-foreground/70 text-xs">
+              {props.item.description}
+            </span>
+          ) : null}
         </span>
       ) : (
         <span className="flex min-w-0 flex-1 items-center gap-1.5 text-sm text-foreground">
@@ -115,15 +183,20 @@ function CommandPaletteResultRow(props: {
       }}
     >
       {props.item.icon}
-      {props.item.description ? (
+      {props.item.description || props.item.threadContentMatch ? (
         <span className="flex min-w-0 flex-1 flex-col">
           <span className="flex min-w-0 items-center gap-1.5 text-sm text-foreground">
             {props.item.titleLeadingContent}
             <span className="truncate">{props.item.title}</span>
           </span>
-          <span className="truncate text-muted-foreground/85 text-xs">
-            {props.item.description}
-          </span>
+          {props.item.threadContentMatch ? (
+            <ThreadContentMatch match={props.item.threadContentMatch} />
+          ) : null}
+          {props.item.description ? (
+            <span className="truncate text-muted-foreground/70 text-xs">
+              {props.item.description}
+            </span>
+          ) : null}
         </span>
       ) : (
         <span className="flex min-w-0 flex-1 items-center gap-1.5 text-sm text-foreground">
diff --git a/apps/web/src/state/queries.ts b/apps/web/src/state/queries.ts
index 745c9e700b3..a9564c2fd64 100644
--- a/apps/web/src/state/queries.ts
+++ b/apps/web/src/state/queries.ts
@@ -3,6 +3,11 @@ import {
   type CheckpointDiffTarget,
   type ComposerPathSearchTarget,
 } from "@t3tools/client-runtime/state/threads";
+import {
+  createThreadSearchResultsAtomFamily,
+  makeThreadSearchKey,
+  type EnvironmentThreadSearchMatch,
+} from "@t3tools/client-runtime/state/thread-search";
 import { type VcsRefTarget } from "@t3tools/client-runtime/state/vcs";
 import type {
   EnvironmentId,
@@ -26,9 +31,24 @@ import { vcsEnvironment } from "./vcs";
 
 const COMPOSER_PATH_SEARCH_DEBOUNCE_MS = 120;
 const COMPOSER_PATH_SEARCH_LIMIT = 80;
+const THREAD_SEARCH_DEBOUNCE_MS = 200;
 const VCS_REF_LIST_LIMIT = 100;
 const EMPTY_REFS: ReadonlyArray<VcsRef> = [];
 const INITIAL_BRANCH_CURSORS = [undefined] as const;
+const EMPTY_THREAD_SEARCH_MATCHES: ReadonlyArray<EnvironmentThreadSearchMatch> = Object.freeze([]);
+const EMPTY_THREAD_SEARCH_ATOM = Atom.make({
+  matches: EMPTY_THREAD_SEARCH_MATCHES,
+  isLoading: false,
+}).pipe(Atom.withLabel("web:thread-search:empty"));
+
+const threadSearchResultsAtom = createThreadSearchResultsAtomFamily({
+  getSearchAtom: (environmentId, query) =>
+    orchestrationEnvironment.threadSearch({
+      environmentId,
+      input: { query },
+    }),
+  labelPrefix: "web:thread-search",
+});
 
 export interface ThreadDetailView {
   readonly data: OrchestrationThread | null;
@@ -52,6 +72,31 @@ function useDebouncedValue<A>(value: A, delayMs: number): A {
   return debounced;
 }
 
+export function useThreadSearch(
+  environmentIds: ReadonlyArray<EnvironmentId>,
+  query: string,
+): {
+  readonly matches: ReadonlyArray<EnvironmentThreadSearchMatch>;
+  readonly isPending: boolean;
+} {
+  const normalizedQuery = query.trim();
+  const debouncedQuery = useDebouncedValue(normalizedQuery, THREAD_SEARCH_DEBOUNCE_MS);
+  const canSearch = environmentIds.length > 0 && normalizedQuery.length >= 2;
+  const settledQuery = canSearch && normalizedQuery === debouncedQuery ? debouncedQuery : null;
+  const searchKey = useMemo(
+    () => (settledQuery === null ? null : makeThreadSearchKey(environmentIds, settledQuery)),
+    [environmentIds, settledQuery],
+  );
+  const result = useAtomValue(
+    searchKey === null ? EMPTY_THREAD_SEARCH_ATOM : threadSearchResultsAtom(searchKey),
+  );
+  const isDebouncing = canSearch && normalizedQuery !== debouncedQuery;
+  return {
+    matches: isDebouncing ? EMPTY_THREAD_SEARCH_MATCHES : result.matches,
+    isPending: canSearch && (isDebouncing || result.isLoading),
+  };
+}
+
 export function useThreadDetail(
   environmentId: EnvironmentId | null,
   threadId: ThreadId | null,
diff --git a/docs/user/keybindings.md b/docs/user/keybindings.md
index 254aa92c6a0..0746272633f 100644
--- a/docs/user/keybindings.md
+++ b/docs/user/keybindings.md
@@ -69,6 +69,11 @@ Invalid rules are ignored. Invalid config files are ignored. Warnings are logged
 - `editor.openFavorite`: open current project/worktree in the last-used editor
 - `script.{id}.run`: run a project script by id (for example `script.test.run`)
 
+The command palette searches active thread titles, projects, branches, user messages, and final
+agent responses across connected environments. Message matches show one labeled excerpt while
+keeping the thread's project, branch, and machine context visible. Message search begins after two
+characters and uses SQLite's ASCII case-insensitive matching.
+
 ### Key Syntax
 
 Supported modifiers:
diff --git a/packages/client-runtime/package.json b/packages/client-runtime/package.json
index 4fa05f850e5..0b7b078a522 100644
--- a/packages/client-runtime/package.json
+++ b/packages/client-runtime/package.json
@@ -131,6 +131,10 @@
       "types": "./src/state/threadSettled.ts",
       "default": "./src/state/threadSettled.ts"
     },
+    "./state/thread-search": {
+      "types": "./src/state/threadSearch.ts",
+      "default": "./src/state/threadSearch.ts"
+    },
     "./state/vcs": {
       "types": "./src/state/vcs.ts",
       "default": "./src/state/vcs.ts"
diff --git a/packages/client-runtime/src/state/orchestration.ts b/packages/client-runtime/src/state/orchestration.ts
index f8faa49ea38..666b3b94c45 100644
--- a/packages/client-runtime/src/state/orchestration.ts
+++ b/packages/client-runtime/src/state/orchestration.ts
@@ -16,6 +16,12 @@ export function createOrchestrationEnvironmentAtoms<R, E>(
       label: "environment-data:orchestration:full-thread-diff",
       tag: ORCHESTRATION_WS_METHODS.getFullThreadDiff,
     }),
+    threadSearch: createEnvironmentRpcQueryAtomFamily(runtime, {
+      label: "environment-data:orchestration:thread-search",
+      tag: ORCHESTRATION_WS_METHODS.searchThreads,
+      staleTimeMs: 30_000,
+      idleTtlMs: 60_000,
+    }),
     archivedShellSnapshot: createEnvironmentRpcQueryAtomFamily(runtime, {
       label: "environment-data:orchestration:archived-shell-snapshot",
       tag: ORCHESTRATION_WS_METHODS.getArchivedShellSnapshot,
diff --git a/packages/client-runtime/src/state/threadSearch.test.ts b/packages/client-runtime/src/state/threadSearch.test.ts
new file mode 100644
index 00000000000..2f1430a51b6
--- /dev/null
+++ b/packages/client-runtime/src/state/threadSearch.test.ts
@@ -0,0 +1,72 @@
+import {
+  EnvironmentId,
+  ProjectId,
+  ThreadId,
+  type OrchestrationSearchThreadsResult,
+} from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import { AsyncResult, Atom, AtomRegistry } from "effect/unstable/reactivity";
+import { expect, it } from "vite-plus/test";
+
+import {
+  createThreadSearchResultsAtomFamily,
+  makeThreadSearchKey,
+  threadSearchMatchKey,
+} from "./threadSearch.ts";
+
+const envA = EnvironmentId.make("env-a");
+const envB = EnvironmentId.make("env-b");
+
+it("creates stable keys regardless of environment order", () => {
+  expect(makeThreadSearchKey([envB, envA], "needle")).toBe(
+    makeThreadSearchKey([envA, envB], "needle"),
+  );
+});
+
+it("encodes scoped thread keys without delimiter collisions", () => {
+  const first = threadSearchMatchKey({
+    environmentId: EnvironmentId.make("env\u0000thread"),
+    threadId: ThreadId.make("id"),
+  });
+  const second = threadSearchMatchKey({
+    environmentId: EnvironmentId.make("env"),
+    threadId: ThreadId.make("thread\u0000id"),
+  });
+
+  expect(first).not.toBe(second);
+});
+
+it("merges successful environments and silently ignores failures", () => {
+  const result: OrchestrationSearchThreadsResult = {
+    matches: [
+      {
+        threadId: ThreadId.make("thread-a"),
+        projectId: ProjectId.make("project-a"),
+        source: "user",
+        snippet: "needle",
+        messageCreatedAt: "2026-07-30T00:00:00.000Z",
+      },
+    ],
+  };
+  const searchAtom = createThreadSearchResultsAtomFamily<Error>({
+    getSearchAtom: (environmentId) =>
+      environmentId === envA
+        ? Atom.make(AsyncResult.success(result))
+        : Atom.make(
+            AsyncResult.failure<OrchestrationSearchThreadsResult, Error>(
+              Cause.fail(new Error("unsupported rpc")),
+            ),
+          ),
+    labelPrefix: "test:thread-search",
+  });
+  const registry = AtomRegistry.make();
+
+  const state = registry.get(searchAtom(makeThreadSearchKey([envB, envA], "needle")));
+  expect(state).toEqual({
+    matches: [{ ...result.matches[0], environmentId: envA }],
+    isLoading: false,
+  });
+  expect(threadSearchMatchKey(state.matches[0]!)).toBe('["env-a","thread-a"]');
+
+  registry.dispose();
+});
diff --git a/packages/client-runtime/src/state/threadSearch.ts b/packages/client-runtime/src/state/threadSearch.ts
new file mode 100644
index 00000000000..4011a91cd58
--- /dev/null
+++ b/packages/client-runtime/src/state/threadSearch.ts
@@ -0,0 +1,81 @@
+import {
+  EnvironmentId,
+  OrchestrationSearchThreadsInput,
+  type OrchestrationSearchThreadsResult,
+  type OrchestrationThreadSearchMatch,
+} from "@t3tools/contracts";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { AsyncResult, Atom } from "effect/unstable/reactivity";
+
+export interface EnvironmentThreadSearchMatch extends OrchestrationThreadSearchMatch {
+  readonly environmentId: EnvironmentId;
+}
+
+export interface ThreadSearchResultsState {
+  readonly matches: ReadonlyArray<EnvironmentThreadSearchMatch>;
+  readonly isLoading: boolean;
+}
+
+const ThreadSearchKey = Schema.Tuple([
+  Schema.Array(EnvironmentId),
+  OrchestrationSearchThreadsInput.fields.query,
+]);
+const decodeThreadSearchKey = Schema.decodeUnknownSync(ThreadSearchKey);
+
+export function makeThreadSearchKey(
+  environmentIds: ReadonlyArray<EnvironmentId>,
+  query: string,
+): string {
+  return JSON.stringify([
+    [...environmentIds].toSorted((left, right) => left.localeCompare(right)),
+    query,
+  ]);
+}
+
+function parseThreadSearchKey(key: string) {
+  return decodeThreadSearchKey(JSON.parse(key));
+}
+
+export function threadSearchMatchKey(
+  match: Pick<EnvironmentThreadSearchMatch, "environmentId" | "threadId">,
+): string {
+  return JSON.stringify([match.environmentId, match.threadId]);
+}
+
+/**
+ * Combines one search query atom per environment. Failed and disconnected
+ * environments contribute no content matches, preserving local title search
+ * as the compatibility fallback.
+ */
+export function createThreadSearchResultsAtomFamily<E>(options: {
+  readonly getSearchAtom: (
+    environmentId: EnvironmentId,
+    query: string,
+  ) => Atom.Atom<AsyncResult.AsyncResult<OrchestrationSearchThreadsResult, E>>;
+  readonly labelPrefix: string;
+}) {
+  return Atom.family((key: string) =>
+    Atom.make((get): ThreadSearchResultsState => {
+      const [environmentIds, query] = parseThreadSearchKey(key);
+      const matches: EnvironmentThreadSearchMatch[] = [];
+      let isLoading = false;
+
+      for (const environmentId of environmentIds) {
+        const result = get(options.getSearchAtom(environmentId, query));
+        isLoading ||= result.waiting;
+        const value = Option.getOrNull(AsyncResult.value(result));
+        if (value !== null) {
+          matches.push(
+            ...value.matches.map((match) => ({
+              ...match,
+              environmentId,
+            })),
+          );
+        }
+      }
+
+      return { matches, isLoading };
+    }).pipe(Atom.withLabel(`${options.labelPrefix}:${key}`)),
+  );
+}
diff --git a/packages/contracts/src/orchestration.ts b/packages/contracts/src/orchestration.ts
index 81d647ece7d..64520c89f90 100644
--- a/packages/contracts/src/orchestration.ts
+++ b/packages/contracts/src/orchestration.ts
@@ -18,6 +18,7 @@ import {
   ProviderItemId,
   ThreadId,
   TrimmedNonEmptyString,
+  TrimmedString,
   TurnId,
 } from "./baseSchemas.ts";
 import { ProviderInstanceId } from "./providerInstance.ts";
@@ -26,6 +27,7 @@ export const ORCHESTRATION_WS_METHODS = {
   dispatchCommand: "orchestration.dispatchCommand",
   getTurnDiff: "orchestration.getTurnDiff",
   getFullThreadDiff: "orchestration.getFullThreadDiff",
+  searchThreads: "orchestration.searchThreads",
   getArchivedShellSnapshot: "orchestration.getArchivedShellSnapshot",
   subscribeShell: "orchestration.subscribeShell",
   subscribeThread: "orchestration.subscribeThread",
@@ -1394,6 +1396,31 @@ export type OrchestrationGetFullThreadDiffInput = typeof OrchestrationGetFullThr
 export const OrchestrationGetFullThreadDiffResult = ThreadTurnDiff;
 export type OrchestrationGetFullThreadDiffResult = typeof OrchestrationGetFullThreadDiffResult.Type;
 
+export const OrchestrationThreadSearchSource = Schema.Literals(["user", "assistant"]);
+export type OrchestrationThreadSearchSource = typeof OrchestrationThreadSearchSource.Type;
+
+// The server's SQLite client is synchronous and single-connection. Bound both
+// scan input and response size so a search cannot monopolize that connection.
+export const OrchestrationSearchThreadsInput = Schema.Struct({
+  query: TrimmedString.check(Schema.isMinLength(2), Schema.isMaxLength(200)),
+  limit: Schema.optionalKey(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 50 }))),
+});
+export type OrchestrationSearchThreadsInput = typeof OrchestrationSearchThreadsInput.Type;
+
+export const OrchestrationThreadSearchMatch = Schema.Struct({
+  threadId: ThreadId,
+  projectId: ProjectId,
+  source: OrchestrationThreadSearchSource,
+  snippet: Schema.String.check(Schema.isMaxLength(240)),
+  messageCreatedAt: Schema.NullOr(IsoDateTime),
+});
+export type OrchestrationThreadSearchMatch = typeof OrchestrationThreadSearchMatch.Type;
+
+export const OrchestrationSearchThreadsResult = Schema.Struct({
+  matches: Schema.Array(OrchestrationThreadSearchMatch),
+});
+export type OrchestrationSearchThreadsResult = typeof OrchestrationSearchThreadsResult.Type;
+
 export const OrchestrationRpcSchemas = {
   dispatchCommand: {
     input: ClientOrchestrationCommand,
@@ -1407,6 +1434,10 @@ export const OrchestrationRpcSchemas = {
     input: OrchestrationGetFullThreadDiffInput,
     output: OrchestrationGetFullThreadDiffResult,
   },
+  searchThreads: {
+    input: OrchestrationSearchThreadsInput,
+    output: OrchestrationSearchThreadsResult,
+  },
   getArchivedShellSnapshot: {
     input: Schema.Struct({}),
     output: OrchestrationShellSnapshot,
@@ -1452,3 +1483,11 @@ export class OrchestrationGetFullThreadDiffError extends Schema.TaggedErrorClass
     cause: Schema.optional(Schema.Defect()),
   },
 ) {}
+
+export class OrchestrationSearchThreadsError extends Schema.TaggedErrorClass<OrchestrationSearchThreadsError>()(
+  "OrchestrationSearchThreadsError",
+  {
+    message: TrimmedNonEmptyString,
+    cause: Schema.optional(Schema.Defect()),
+  },
+) {}
diff --git a/packages/contracts/src/rpc.ts b/packages/contracts/src/rpc.ts
index d1a5f2504c7..17fbd57ddad 100644
--- a/packages/contracts/src/rpc.ts
+++ b/packages/contracts/src/rpc.ts
@@ -57,6 +57,8 @@ import {
   OrchestrationGetFullThreadDiffError,
   OrchestrationGetFullThreadDiffInput,
   OrchestrationGetSnapshotError,
+  OrchestrationSearchThreadsError,
+  OrchestrationSearchThreadsInput,
   OrchestrationGetTurnDiffError,
   OrchestrationGetTurnDiffInput,
   OrchestrationRpcSchemas,
@@ -690,6 +692,12 @@ export const WsOrchestrationGetFullThreadDiffRpc = Rpc.make(
   },
 );
 
+export const WsOrchestrationSearchThreadsRpc = Rpc.make(ORCHESTRATION_WS_METHODS.searchThreads, {
+  payload: OrchestrationSearchThreadsInput,
+  success: OrchestrationRpcSchemas.searchThreads.output,
+  error: Schema.Union([OrchestrationSearchThreadsError, EnvironmentAuthorizationError]),
+});
+
 export const WsOrchestrationGetArchivedShellSnapshotRpc = Rpc.make(
   ORCHESTRATION_WS_METHODS.getArchivedShellSnapshot,
   {
@@ -840,6 +848,7 @@ export const WsRpcGroup = RpcGroup.make(
   WsOrchestrationDispatchCommandRpc,
   WsOrchestrationGetTurnDiffRpc,
   WsOrchestrationGetFullThreadDiffRpc,
+  WsOrchestrationSearchThreadsRpc,
   WsOrchestrationGetArchivedShellSnapshotRpc,
   WsOrchestrationSubscribeShellRpc,
   WsOrchestrationSubscribeThreadRpc,

From 50871eb5de641ffd41b1f9d0151668982d276393 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Thu, 30 Jul 2026 05:31:42 -0700
Subject: [PATCH 21/34] fix: marketing site Vercel builds no longer die after
 ~100 deploys (#4975)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---
 package.json                   |  2 +-
 scripts/clean-tsgo-backups.mjs | 24 ++++++++++++++++++++++++
 2 files changed, 25 insertions(+), 1 deletion(-)
 create mode 100644 scripts/clean-tsgo-backups.mjs

diff --git a/package.json b/package.json
index 3f6c269aee7..839b8e79584 100644
--- a/package.json
+++ b/package.json
@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "prepare": "effect-tsgo patch && vp config --no-agent",
+    "prepare": "node scripts/clean-tsgo-backups.mjs && effect-tsgo patch && vp config --no-agent",
     "dev": "node scripts/dev-runner.ts dev",
     "dev:share": "node scripts/dev-runner.ts dev --share",
     "dev:server": "node scripts/dev-runner.ts dev:server",
diff --git a/scripts/clean-tsgo-backups.mjs b/scripts/clean-tsgo-backups.mjs
new file mode 100644
index 00000000000..43012a69bd3
--- /dev/null
+++ b/scripts/clean-tsgo-backups.mjs
@@ -0,0 +1,24 @@
+// Deletes stale tsgo backup files left behind by `effect-tsgo patch`.
+//
+// The patch command backs up the real tsgo binary to `tsgo.original`, and if
+// that name is taken it writes `tsgo.original.1`, `.2`, ... without ever
+// cleaning up. On runners that restore node_modules from a build cache
+// (Vercel), backups accumulate across deploys until patch hard-fails at 101
+// with "Too many backup files exist". Removing them is safe: from the second
+// patch onward the backup is just the previously-patched binary, and pnpm
+// restores the pristine one whenever the package is re-materialized.
+//
+// Runs as part of `prepare`, so it must only use node builtins.
+import * as NodeFS from "node:fs";
+
+const backups = NodeFS.globSync(
+  "node_modules/.pnpm/@typescript+native-preview-*/node_modules/@typescript/native-preview-*/lib/tsgo{,.exe}.original*",
+);
+
+for (const backup of backups) {
+  NodeFS.rmSync(backup, { force: true });
+}
+
+if (backups.length > 0) {
+  console.log(`Removed ${backups.length} stale tsgo backup(s)`);
+}

From 9dd425b2234c062b4767583e42d4b2c1aabab15d Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Thu, 30 Jul 2026 06:10:47 -0700
Subject: [PATCH 22/34] docs: split user and maintainer docs, fix 100+ stale
 claims (#4807)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---
 AGENTS.md                                     |  10 +-
 README.md                                     |  25 +-
 docs/README.md                                |  60 ++-
 docs/architecture/connection-runtime.md       | 140 ------
 docs/architecture/overview.md                 | 141 -------
 docs/architecture/providers.md                |  30 --
 docs/architecture/remote.md                   | 397 ------------------
 docs/architecture/runtime-modes.md            |   6 -
 docs/getting-started/codex-prerequisites.md   |   5 -
 docs/getting-started/quick-start.md           |  22 -
 docs/internals/ci.md                          |  24 ++
 docs/internals/connection-runtime.md          | 183 ++++++++
 docs/{cloud => internals}/environment-auth.md |  46 +-
 .../encyclopedia.md => internals/glossary.md} |  81 ++--
 docs/internals/overview.md                    | 152 +++++++
 docs/internals/providers.md                   |  92 ++++
 docs/internals/remote.md                      | 235 +++++++++++
 .../resource-telemetry.md                     |   2 +
 docs/internals/scripts.md                     | 119 ++++++
 .../server-updates.md                         |  19 +-
 .../t3-code-connect-auth-flow.html            |   0
 .../t3-connect.md}                            |  90 ++--
 docs/internals/workspace-layout.md            |  63 +++
 docs/operations/ci.md                         |   6 -
 docs/operations/effect-fn-checklist.md        | 198 ---------
 .../mobile-app-store-screenshots.md           |  74 ++--
 docs/operations/observability.md              |  61 ++-
 docs/operations/relay-observability.md        |  33 +-
 docs/operations/release.md                    |  59 ++-
 docs/project/todo.md                          |  13 -
 docs/reference/scripts.md                     |  56 ---
 docs/reference/workspace-layout.md            |   7 -
 docs/user/install.md                          |  84 ++++
 docs/user/keybindings.md                      | 121 ++----
 docs/user/permission-modes.md                 |  48 +++
 .../claude.md => user/providers-claude.md}    |  74 ++--
 .../codex.md => user/providers-codex.md}      |   3 +-
 docs/user/remote-access.md                    |  37 +-
 .../source-control.md}                        |  40 +-
 docs/user/{server-updates.md => updating.md}  |  12 +-
 infra/relay/README.md                         |  14 +-
 41 files changed, 1482 insertions(+), 1400 deletions(-)
 delete mode 100644 docs/architecture/connection-runtime.md
 delete mode 100644 docs/architecture/overview.md
 delete mode 100644 docs/architecture/providers.md
 delete mode 100644 docs/architecture/remote.md
 delete mode 100644 docs/architecture/runtime-modes.md
 delete mode 100644 docs/getting-started/codex-prerequisites.md
 delete mode 100644 docs/getting-started/quick-start.md
 create mode 100644 docs/internals/ci.md
 create mode 100644 docs/internals/connection-runtime.md
 rename docs/{cloud => internals}/environment-auth.md (70%)
 rename docs/{reference/encyclopedia.md => internals/glossary.md} (60%)
 create mode 100644 docs/internals/overview.md
 create mode 100644 docs/internals/providers.md
 create mode 100644 docs/internals/remote.md
 rename docs/{architecture => internals}/resource-telemetry.md (99%)
 create mode 100644 docs/internals/scripts.md
 rename docs/{architecture => internals}/server-updates.md (89%)
 rename docs/{cloud => internals}/t3-code-connect-auth-flow.html (100%)
 rename docs/{cloud/t3-connect-clerk.md => internals/t3-connect.md} (75%)
 create mode 100644 docs/internals/workspace-layout.md
 delete mode 100644 docs/operations/ci.md
 delete mode 100644 docs/operations/effect-fn-checklist.md
 delete mode 100644 docs/project/todo.md
 delete mode 100644 docs/reference/scripts.md
 delete mode 100644 docs/reference/workspace-layout.md
 create mode 100644 docs/user/install.md
 create mode 100644 docs/user/permission-modes.md
 rename docs/{providers/claude.md => user/providers-claude.md} (72%)
 rename docs/{providers/codex.md => user/providers-codex.md} (96%)
 rename docs/{integrations/source-control-providers.md => user/source-control.md} (74%)
 rename docs/user/{server-updates.md => updating.md} (84%)

diff --git a/AGENTS.md b/AGENTS.md
index 066dafe91c4..c3a7fe92bf4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -28,7 +28,7 @@ T3 Code has 3 key app surfaces: **web**, **desktop**, and **mobile**.
 
 **Desktop** is the main surface most users install first. It's a full Electron app that bundles the server runner as well. The desktop app can also be used as the host server, allowing remote connections from app.t3.codes or the mobile app.
 
-**Mobile** is a React native app for both iOS and Android. The mobile app allows for connecting to any T3 Code server to control work remotely. It is still in early access (Testflight), but it is pretty close to shipping globally.
+**Mobile** is a React Native app for both iOS and Android, available on the App Store and Google Play. The mobile app allows for connecting to any T3 Code server to control work remotely.
 
 ## A note from Theo
 
@@ -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/` mirrors this structure. Behavior changes that a user would notice belong in `docs/user/`; architecture changes in `docs/architecture/`; new vocabulary in `docs/reference/encyclopedia.md`.
+- **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`.
 
 ## Dev servers
 
@@ -123,13 +123,13 @@ An empty database is a bad test. Seed your worktree's `.t3` with a copy of real
 
 Clients send typed WebSocket requests. The server turns them into _commands_, a pure _decider_ turns commands into persisted _events_, and a _projector_ derives the read model the UI renders. Provider CLIs run as subprocesses; per-provider _adapters_ translate their native protocols into orchestration events. Side effects run in queue-backed _reactors_ that emit _receipts_ when milestones land. Each turn ends with a _checkpoint_, a hidden git ref, so the app can diff and restore.
 
-Full glossary with file links: `docs/reference/encyclopedia.md`
+Full glossary with file links: `docs/internals/glossary.md`
 
 ## Where code lives
 
-- `apps/server` - WebSocket, orchestration, providers, checkpointing. Effect-heavy: read `.repos/effect-smol/LLMS.md` and `docs/operations/effect-fn-checklist.md` before writing Effect code.
+- `apps/server` - WebSocket, orchestration, providers, checkpointing. Effect-heavy: read `.repos/effect-smol/LLMS.md` before writing Effect code.
 - `apps/web` - React/Vite UI. `apps/desktop` wraps it, `apps/mobile` is React Native, `apps/marketing` is the site.
-- `packages/contracts` - Effect/Schema contracts. Schema only, no runtime logic.
+- `packages/contracts` - Effect/Schema contracts plus small derived helpers. No heavy runtime logic.
 - `packages/shared` - shared runtime utils, subpath exports, no barrel.
 - `packages/client-runtime` - client code shared by web and mobile.
 - `.repos/` - vendored read-only references. Prefer their patterns over invented ones. Never edit or import from them. Sync with `vpr sync:repos` when bumping the matching dependency.
diff --git a/README.md b/README.md
index bc34b3f76b4..1e9b0517945 100644
--- a/README.md
+++ b/README.md
@@ -17,13 +17,13 @@ We wanted something performant, remote-ready, and truly open. If we ever go the
 >
 > - Codex: install [Codex CLI](https://developers.openai.com/codex/cli) and run `codex login`
 > - Claude: install [Claude Code](https://claude.com/product/claude-code) and run `claude auth login`
-> - Cursor: install [Cursor CLI](https://cursor.com/cli) and run `cursor-agent login`
+> - Cursor: install [Cursor CLI](https://cursor.com/cli) and run `agent login`
 > - Grok Build: install [Grok Build CLI](https://x.ai/cli) and run `grok login`
 > - OpenCode: install [OpenCode](https://opencode.ai) and run `opencode auth login`
 
 ### Try it out (install-free)
 
-The easiest way to test T3 Code is to run the server in your terminal:
+The easiest way to test T3 Code is to run the server in your terminal (requires Node.js 22.16+, 23.11+, or 24.10+):
 
 ```bash
 npx t3@latest
@@ -61,17 +61,20 @@ We are very very early in this project. Expect bugs.
 
 We are (mostly) not accepting contributions yet. Small fixes may be considered. Big features will not be.
 
-There's no public docs site yet, checkout the miscellaneous markdown files in [docs](./docs).
-
 ## Documentation
 
-- [Getting started](./docs/getting-started/quick-start.md)
-- [Remote access](./docs/user/remote-access.md)
-- [Keeping T3 Code in sync](./docs/user/server-updates.md)
-- [Architecture overview](./docs/architecture/overview.md)
-- [Provider guides](./docs/providers/codex.md)
-- [Operations](./docs/operations/ci.md)
-- [Reference](./docs/reference/encyclopedia.md)
+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)
+- [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)
+
+Building from source? Start at [docs/internals/overview.md](./docs/internals/overview.md).
 
 ## If you REALLY want to contribute still.... read this first
 
diff --git a/docs/README.md b/docs/README.md
index fe473094bbc..bc359826a04 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,19 +1,41 @@
-# Documentation
-
-- [Getting started](./getting-started/quick-start.md)
-- Architecture
-  - [Overview](./architecture/overview.md)
-  - [Connection runtime](./architecture/connection-runtime.md)
-  - [Remote environments](./architecture/remote.md)
-  - [Server updates](./architecture/server-updates.md)
-- User guides
-  - [Background service](./user/background-service.md)
-  - [Remote access](./user/remote-access.md)
-  - [Keeping T3 Code in sync](./user/server-updates.md)
-  - [Keybindings](./user/keybindings.md)
-- [T3 Connect](./cloud/t3-connect-clerk.md)
-- [Integrations](./integrations/source-control-providers.md)
-- [Mobile](./mobile/app.md)
-- [Operations](./operations/ci.md)
-- [Providers](./providers/codex.md)
-- [Reference](./reference/encyclopedia.md)
+# T3 Code docs
+
+## Using T3 Code
+
+- [Install and first run](./user/install.md)
+- [Permission modes](./user/permission-modes.md)
+- [Keyboard shortcuts](./user/keybindings.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)
+
+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).
+
+- [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)
+- [Providers](./internals/providers.md)
+- [Remote environments](./internals/remote.md)
+- [Server updates](./internals/server-updates.md)
+- [Resource telemetry](./internals/resource-telemetry.md)
+- [Environment auth](./internals/environment-auth.md)
+- [T3 Connect](./internals/t3-connect.md)
+- [CI gates](./internals/ci.md)
+
+### Runbooks
+
+- [Release](./operations/release.md)
+- [Observability](./operations/observability.md)
+- [Relay observability](./operations/relay-observability.md)
+- [Mobile app store screenshots](./operations/mobile-app-store-screenshots.md)
diff --git a/docs/architecture/connection-runtime.md b/docs/architecture/connection-runtime.md
deleted file mode 100644
index acfd2ab5983..00000000000
--- a/docs/architecture/connection-runtime.md
+++ /dev/null
@@ -1,140 +0,0 @@
-# Connection Runtime
-
-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. There is no
-legacy connection owner or supported mixed mode.
-
-## Ownership
-
-Each registered environment has one scoped Effect `Context` containing focused
-services:
-
-- `EnvironmentSupervisor` owns desired state, retry scheduling, and the active
-  session scope.
-- `ConnectionBroker` prepares credentials and endpoints for primary, bearer,
-  relay, and SSH targets.
-- `RpcSessionFactory` performs one transport attempt. It does not retry.
-- `EnvironmentRpc` exposes the active session without leaking the transport.
-- `EnvironmentProjectCommands` and `EnvironmentThreadCommands` construct
-  orchestration commands, IDs, and timestamps.
-- `EnvironmentShell` and `EnvironmentThreads` own live subscriptions and cached
-  snapshots.
-
-`EnvironmentServicesFactory` assembles that context, and `EnvironmentRegistry`
-owns its scope. There is no aggregate environment runtime facade. 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 without consuming retry attempts.
-3. When online, the supervisor asks the broker for one prepared connection and
-   asks the session factory for one RPC session.
-4. Transient failures retry forever with exponential backoff capped at 16
-   seconds.
-5. Connectivity changes, application activation, credential changes, and
-   explicit user retry interrupt the current wait and trigger a fresh attempt.
-   Application activation also resets the backoff ladder. Mobile briefly probes
-   a session after short interruptions and replaces it immediately after a
-   meaningful background suspension.
-6. Authentication or configuration failures remain blocked until an external
-   wakeup changes the relevant input.
-7. An involuntary session close keeps the registration and cache, then retries.
-8. Explicit removal closes the session and deletes the registration,
-   credentials, shell cache, and thread cache.
-
-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.
-- Expected subscription failures update domain sync state and wait for a
-  replacement session; they do not take down a healthy transport.
-- Mutations resolve the current environment runtime at execution time.
-- Shell and thread snapshots are available while offline.
-- A connected transport may have `empty`, `cached`, `synchronizing`, `live`, or
-  failed shell and thread data independently.
-- 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.
-- 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.
-
-## Source Boundaries
-
-The public package subpaths mirror the runtime layers:
-
-- `connection/core` contains state, catalog, retry policy, and connectivity.
-- `connection/transport` contains brokerage, authorization, attempts, and RPC
-  sessions.
-- `connection/platform` declares capabilities and persistence contracts.
-- `connection/services` contains environment-scoped data services.
-- `connection/application` assembles registries, discovery, and startup.
-- `connection/atoms` adapts shared services to application-owned Atom runtimes.
-- `connection/presentation` contains pure UI projections.
-
-Other reusable state lives in domain subpaths such as `shell`, `threads`,
-`terminal`, and `vcs`. Applications must import explicit package subpaths; the
-package intentionally has no root export.
-
-## Application Boundary
-
-The application root mounts the shared connection application 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 `WsTransport`, RPC clients, retry loops, or
-raw orchestration commands. Persistence paths belong to the platform
-registration and cache stores, with explicit migration or invalidation policy.
-
-## Verification
-
-Core state-machine tests use `@effect/vitest` and deterministic service layers.
-Required coverage includes:
-
-- offline startup and online wakeup;
-- forever retry with the 16-second cap;
-- explicit retry interrupting backoff;
-- authentication wakeups;
-- involuntary close and reconnect;
-- explicit removal clearing all owned state;
-- relay token reuse and refresh;
-- progressive relay discovery;
-- shell and thread cache hydration;
-- durable subscriptions switching sessions;
-- command metadata and idempotent queued-command metadata.
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
deleted file mode 100644
index eca184aa067..00000000000
--- a/docs/architecture/overview.md
+++ /dev/null
@@ -1,141 +0,0 @@
-# Architecture
-
-T3 Code runs as a **Node.js WebSocket server** that wraps `codex app-server` (JSON-RPC over stdio) and serves a React web app.
-
-```
-┌─────────────────────────────────┐
-│  Browser (React + Vite)         │
-│  wsTransport (state machine)    │
-│  Typed push decode at boundary  │
-└──────────┬──────────────────────┘
-           │ ws://localhost:3773
-┌──────────▼──────────────────────┐
-│  apps/server (Node.js)          │
-│  WebSocket + HTTP static server │
-│  ServerPushBus (ordered pushes) │
-│  ServerReadiness (startup gate) │
-│  OrchestrationEngine            │
-│  ProviderService                │
-│  CheckpointReactor              │
-│  RuntimeReceiptBus              │
-└──────────┬──────────────────────┘
-           │ JSON-RPC over stdio
-┌──────────▼──────────────────────┐
-│  codex app-server               │
-└─────────────────────────────────┘
-```
-
-## Components
-
-- **Browser app**: The React app renders session state, owns the client-side WebSocket transport, and treats typed push events as the boundary between server runtime details and UI state.
-
-- **Server**: `apps/server` is the main coordinator. It serves the web app, accepts WebSocket requests, waits for startup readiness before welcoming clients, and sends all outbound pushes through a single ordered push path.
-
-- **Provider runtime**: `codex app-server` does the actual provider/session work. The server talks to it over JSON-RPC on stdio and translates those runtime events into the app's orchestration model.
-
-- **Background workers**: Long-running async flows such as runtime ingestion, command reaction, and checkpoint processing run as queue-backed workers. This keeps work ordered, reduces timing races, and gives tests a deterministic way to wait for the system to go idle.
-
-- **Runtime signals**: The server emits lightweight typed receipts when important async milestones finish, such as checkpoint capture, diff finalization, or a turn becoming fully quiescent. Tests and orchestration code wait on these signals instead of polling internal state.
-
-- **Server updates**: A connected environment advertises whether its server can replace itself. When client and server versions differ, the browser selects an automatic, desktop-managed, or manual update path without changing connection ownership. See [Server Update Architecture](./server-updates.md).
-
-Related design:
-
-- [Resource telemetry architecture](./resource-telemetry.md)
-
-## Event Lifecycle
-
-### Startup and client connect
-
-```mermaid
-sequenceDiagram
-    participant Browser
-    participant Transport as WsTransport
-    participant Server as wsServer
-    participant Layers as serverLayers
-    participant Ready as ServerReadiness
-    participant Push as ServerPushBus
-
-    Browser->>Transport: Load app and open WebSocket
-    Transport->>Server: Connect
-    Server->>Layers: Start runtime services
-    Server->>Ready: Wait for startup barriers
-    Ready-->>Server: Ready
-    Server->>Push: Publish server.welcome
-    Push-->>Transport: Ordered welcome push
-    Transport-->>Browser: Hydrate initial state
-```
-
-1. The browser boots `WsTransport` and registers typed listeners in `wsNativeApi`.
-2. The server accepts the connection in `wsServer` and brings up the runtime graph defined in `serverLayers`.
-3. `ServerReadiness` waits until the key startup barriers are complete.
-4. Once the server is ready, `wsServer` sends `server.welcome` from the contracts in `ws.ts` through `ServerPushBus`.
-5. The browser receives that ordered push through `WsTransport`, and `wsNativeApi` uses it to seed local client state.
-
-### User turn flow
-
-```mermaid
-sequenceDiagram
-    participant Browser
-    participant Transport as WsTransport
-    participant Server as wsServer
-    participant Provider as ProviderService
-    participant Codex as codex app-server
-    participant Ingest as ProviderRuntimeIngestion
-    participant Engine as OrchestrationEngine
-    participant Push as ServerPushBus
-
-    Browser->>Transport: Send user action
-    Transport->>Server: Typed WebSocket request
-    Server->>Provider: Route request
-    Provider->>Codex: JSON-RPC over stdio
-    Codex-->>Ingest: Provider runtime events
-    Ingest->>Engine: Normalize into orchestration events
-    Engine-->>Server: Domain events
-    Server->>Push: Publish orchestration.domainEvent
-    Push-->>Browser: Typed push
-```
-
-1. A user action in the browser becomes a typed request through `WsTransport` and the browser API layer in `nativeApi`.
-2. `wsServer` decodes that request using the shared WebSocket contracts in `ws.ts` and routes it to the right service.
-3. [`ProviderService`][8] starts or resumes a session and talks to `codex app-server` over JSON-RPC on stdio.
-4. Provider-native events are pulled back into the server by [`ProviderRuntimeIngestion`][9], which converts them into orchestration events.
-5. [`OrchestrationEngine`][10] persists those events, updates the read model, and exposes them as domain events.
-6. `wsServer` pushes those updates to the browser through `ServerPushBus` on channels defined in [`orchestration.ts`][11].
-
-### Async completion flow
-
-```mermaid
-sequenceDiagram
-    participant Server as wsServer
-    participant Worker as Queue-backed workers
-    participant Cmd as ProviderCommandReactor
-    participant Checkpoint as CheckpointReactor
-    participant Receipt as RuntimeReceiptBus
-    participant Push as ServerPushBus
-    participant Browser
-
-    Server->>Worker: Enqueue follow-up work
-    Worker->>Cmd: Process provider commands
-    Worker->>Checkpoint: Process checkpoint tasks
-    Checkpoint->>Receipt: Publish completion receipt
-    Cmd-->>Server: Produce orchestration changes
-    Checkpoint-->>Server: Produce orchestration changes
-    Server->>Push: Publish resulting state updates
-    Push-->>Browser: User-visible push
-```
-
-1. Some work continues after the initial request returns, especially in [`ProviderRuntimeIngestion`][9], [`ProviderCommandReactor`][13], and [`CheckpointReactor`][14].
-2. These flows run as queue-backed workers using [`DrainableWorker`][16], which helps keep side effects ordered and test synchronization deterministic.
-3. When a milestone completes, the server emits a typed receipt on [`RuntimeReceiptBus`][15], such as checkpoint completion or turn quiescence.
-4. Tests and orchestration code wait on those receipts instead of polling git state, projections, or timers.
-5. Any user-visible state changes produced by that async work still go back through `wsServer` and `ServerPushBus`.
-
-[8]: ../../apps/server/src/provider/Layers/ProviderService.ts
-[9]: ../../apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
-[10]: ../../apps/server/src/orchestration/Layers/OrchestrationEngine.ts
-[11]: ../../packages/contracts/src/orchestration.ts
-[13]: ../../apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
-[14]: ../../apps/server/src/orchestration/Layers/CheckpointReactor.ts
-[15]: ../../apps/server/src/orchestration/Layers/RuntimeReceiptBus.ts
-[16]: ../../packages/shared/src/DrainableWorker.ts
diff --git a/docs/architecture/providers.md b/docs/architecture/providers.md
deleted file mode 100644
index 794b6aa5d5e..00000000000
--- a/docs/architecture/providers.md
+++ /dev/null
@@ -1,30 +0,0 @@
-# Provider architecture
-
-The web app communicates with the server via WebSocket using a simple JSON-RPC-style protocol:
-
-- **Request/Response**: `{ id, method, params }` → `{ id, result }` or `{ id, error }`
-- **Push events**: typed envelopes with `channel`, `sequence` (monotonic per connection), and channel-specific `data`
-
-Push channels: `server.welcome`, `server.configUpdated`, `terminal.event`, `orchestration.domainEvent`. Payloads are schema-validated at the transport boundary (`wsTransport.ts`). Decode failures produce structured `WsDecodeDiagnostic` with `code`, `reason`, and path info.
-
-Methods mirror the `NativeApi` interface defined in `@t3tools/contracts`:
-
-- `providers.startSession`, `providers.sendTurn`, `providers.interruptTurn`
-- `providers.respondToRequest`, `providers.stopSession`
-- `shell.openInEditor`, `server.getConfig`
-
-Codex is the only implemented provider. `claudeCode` is reserved in contracts/UI.
-
-## Client transport
-
-`wsTransport.ts` manages connection state: `connecting` → `open` → `reconnecting` → `closed` → `disposed`. Outbound requests are queued while disconnected and flushed on reconnect. Inbound pushes are decoded and validated at the boundary, then cached per channel. Subscribers can opt into `replayLatest` to receive the last push on subscribe.
-
-## Server-side orchestration layers
-
-Provider runtime events flow through queue-based workers:
-
-1. **ProviderRuntimeIngestion** — consumes provider runtime streams, emits orchestration commands
-2. **ProviderCommandReactor** — reacts to orchestration intent events, dispatches provider calls
-3. **CheckpointReactor** — captures git checkpoints on turn start/complete, publishes runtime receipts
-
-All three use `DrainableWorker` internally and expose `drain()` for deterministic test synchronization.
diff --git a/docs/architecture/remote.md b/docs/architecture/remote.md
deleted file mode 100644
index fc4fc0b4065..00000000000
--- a/docs/architecture/remote.md
+++ /dev/null
@@ -1,397 +0,0 @@
-# Remote Architecture
-
-This document describes the target architecture for first-class remote environments in T3 Code.
-
-It is intentionally architecture-first. It does not define a complete implementation plan or user-facing rollout checklist. The goal is to establish the core model so remote support can be added without another broad rewrite.
-
-## Goals
-
-- Treat remote environments as first-class product primitives, not special cases.
-- Support multiple ways to reach the same environment.
-- Keep the T3 server as the execution boundary.
-- Let desktop, mobile, and web all share the same conceptual model.
-- Avoid introducing a local control plane unless product pressure proves it is necessary.
-
-## Non-goals
-
-- Replacing the existing WebSocket server boundary with a custom transport protocol.
-- Making SSH the only remote story.
-- Syncing provider auth across machines.
-- Shipping every access method in the first iteration.
-
-## High-level architecture
-
-T3 already has a clean runtime boundary: the client talks to a T3 server over HTTP/WebSocket, and the server owns orchestration, providers, terminals, git, and filesystem operations.
-
-Remote support should preserve that boundary.
-
-```text
-┌──────────────────────────────────────────────┐
-│ Client (desktop / mobile / web)             │
-│                                              │
-│ - known environments                         │
-│ - connection manager                         │
-│ - environment-aware routing                  │
-└───────────────┬──────────────────────────────┘
-                │
-                │ resolves one access endpoint
-                │
-┌───────────────▼──────────────────────────────┐
-│ Access method                               │
-│                                              │
-│ - direct ws / wss                           │
-│ - tunneled ws / wss                         │
-│ - desktop-managed ssh bootstrap + forward   │
-└───────────────┬──────────────────────────────┘
-                │
-                │ connects to one T3 server
-                │
-┌───────────────▼──────────────────────────────┐
-│ Execution environment = one T3 server       │
-│                                              │
-│ - environment identity                       │
-│ - provider state                             │
-│ - projects / threads / terminals             │
-│ - git / filesystem / process runtime         │
-└──────────────────────────────────────────────┘
-```
-
-The important decision is that remoteness is expressed at the environment connection layer, not by splitting the T3 runtime itself.
-
-## Domain model
-
-### ExecutionEnvironment
-
-An `ExecutionEnvironment` is one running T3 server instance.
-
-It is the unit that owns:
-
-- provider availability and auth state
-- model availability
-- projects and threads
-- terminal processes
-- filesystem access
-- git operations
-- server settings
-
-It is identified by a stable `environmentId`.
-
-This is the shared cross-client primitive. Desktop, mobile, and web should all reason about the same concept here.
-
-### KnownEnvironment
-
-A `KnownEnvironment` is a client-side saved entry for an environment the client knows how to reach.
-
-It is not server-authored. It is local to a device or client profile.
-
-Examples:
-
-- a saved LAN URL
-- a saved public `wss://` endpoint
-- a desktop-managed SSH host entry
-- a saved tunneled environment
-
-A known environment may or may not know the target `environmentId` before first successful connect.
-
-In the hosted web app, known environments are browser-local. A hosted pairing URL can create the saved entry, but it does not give the hosted app a server-side control plane or a copy of the session state.
-
-### AccessEndpoint
-
-An `AccessEndpoint` is one concrete way to reach a known environment.
-
-This is the key abstraction that keeps SSH from taking over the model.
-
-A single environment may have many endpoints:
-
-- `wss://t3.example.com`
-- `ws://10.0.0.25:3773`
-- a tunneled relay URL
-- a desktop-managed SSH tunnel that resolves to a local forwarded WebSocket URL
-
-The environment stays the same. Only the access path changes.
-
-### AdvertisedEndpoint
-
-An `AdvertisedEndpoint` is a server or desktop-authored candidate endpoint for an environment. It is how the backend tells the client which URLs may be useful for pairing and reconnecting.
-
-`AdvertisedEndpoint` is deliberately narrower than the full access model:
-
-- it describes a concrete HTTP and WebSocket base URL pair
-- it can mark the endpoint as default, available, or unavailable
-- it includes reachability hints such as loopback, LAN, private, public, or tunnel
-- it includes compatibility hints such as whether the endpoint can be used from the hosted HTTPS app
-
-Clients should treat advertised endpoints as hints, not as proof that a route works from the current device. The final connection attempt still decides whether the endpoint is reachable.
-
-The UI presents one default advertised endpoint in the network-access summary and keeps the rest behind an expandable advanced list. The default controls pairing QR codes and primary copy actions. Users can override it, but that override is a UI preference, not backend configuration.
-
-Persist the override by stable endpoint kind rather than raw URL whenever possible. For example, a LAN endpoint should be stored as the desktop LAN endpoint preference, not as `192.168.x.y`, because the address can change when the user switches networks. Provider endpoints should use provider-specific stable keys such as Tailscale IP or Tailscale MagicDNS HTTPS. Custom endpoints may fall back to their concrete identity.
-
-When no user default is saved, endpoint selection should prefer:
-
-1. endpoints compatible with the hosted HTTPS app
-2. explicitly default endpoints
-3. non-loopback endpoints
-4. loopback endpoints only for same-machine clients
-
-This keeps endpoint discovery centralized without making any one provider, such as Tailscale or a future tunnel service, part of the core environment model.
-
-### Endpoint providers
-
-Endpoint providers are add-ons that contribute advertised endpoints for the current environment.
-
-The provider boundary is intentionally outside the core environment model:
-
-- core owns `ExecutionEnvironment`, saved environments, pairing, and connection lifecycle
-- providers discover or synthesize endpoints
-- providers return normalized `AdvertisedEndpoint` records
-- the UI and pairing logic select from those records without knowing provider-specific commands
-
-The first provider is Tailscale. It can discover Tailnet IP and MagicDNS addresses from the local machine and publish them as additional endpoint candidates. Future providers, such as a hosted tunnel service, should plug into the same shape rather than adding a separate remote environment path.
-
-Provider-specific confidence should remain a hint. A Tailscale endpoint still needs a successful browser or desktop connection before the client treats it as connected.
-
-### Hosted pairing request
-
-A hosted pairing request is a bootstrap URL for the static web app, not a transport.
-
-Example:
-
-```text
-https://app.t3.codes/pair?host=https://backend.example.com:3773#token=PAIRCODE
-```
-
-The hosted app reads the `host` parameter and pairing token, exchanges the token directly with that backend, then saves the resulting environment record in browser local storage.
-
-Important constraints:
-
-- the hosted app does not proxy HTTP or WebSocket traffic
-- the backend must still be reachable directly from the browser
-- HTTPS pages can only connect to HTTPS/WSS backends
-- HTTP LAN endpoints should keep using direct desktop or CLI pairing URLs
-- the token belongs in the URL hash so it is not sent to the hosted app origin
-
-### RepositoryIdentity
-
-`RepositoryIdentity` remains a best-effort logical repo grouping mechanism across environments.
-
-It is not used for routing. It is only used for UI grouping and correlation between local and remote clones of the same repository.
-
-### Workspace / Project
-
-The current `Project` model remains environment-local.
-
-That means:
-
-- a local clone and a remote clone are different projects
-- they may share a `RepositoryIdentity`
-- threads still bind to one project in one environment
-
-## Access methods
-
-Access methods answer one question:
-
-How does the client speak WebSocket to a T3 server?
-
-They do not answer:
-
-- how the server got started
-- who manages the server process
-- whether the environment is local or remote
-
-### 1. Direct WebSocket access
-
-Examples:
-
-- `ws://10.0.0.15:3773`
-- `wss://t3.example.com`
-
-This is the base model and should be the first-class default.
-
-Benefits:
-
-- works for desktop, mobile, and web
-- no client-specific process management required
-- best fit for hosted or self-managed remote T3 deployments
-
-Browser security rules are part of this access method. A hosted HTTPS web client can connect to `wss://` backends, but it cannot connect to plain `ws://` or `http://` LAN backends because that would be mixed content.
-
-### 2. Tunneled WebSocket access
-
-Examples:
-
-- public relay URLs
-- private network relay URLs
-- local tunnel products such as pipenet
-
-This is still direct WebSocket access from the client's perspective. The difference is that the route is mediated by a tunnel or relay.
-
-For T3, tunnels are best modeled as another `AccessEndpoint`, not as a different kind of environment.
-
-This is especially useful when:
-
-- the host is behind NAT
-- inbound ports are unavailable
-- mobile must reach a desktop-hosted environment
-- a machine should be reachable without exposing raw LAN or public ports
-
-Tailscale-backed access sits here architecturally even though the current implementation is endpoint discovery rather than a T3-managed tunnel. It contributes private-network endpoints and lets the existing HTTP/WebSocket client path do the actual connection.
-
-### 3. Desktop-managed SSH access
-
-SSH is an access and launch helper, not a separate environment type.
-
-The desktop main process can use SSH to:
-
-- reach a machine
-- probe it
-- launch or reuse a remote T3 server
-- establish a local port forward
-
-After that, the renderer should still connect using an ordinary WebSocket URL against the forwarded local port.
-
-This keeps the renderer transport model consistent with every other access method.
-
-The desktop main process owns the SSH bridge because it can spawn local SSH processes, manage askpass prompts, write temporary launch scripts, and clean up forwards. The renderer receives a saved environment record and connects through the forwarded URL; it should not need SSH-specific RPC paths for normal environment traffic.
-
-## Launch methods
-
-Launch methods answer a different question:
-
-How does a T3 server come to exist on the target machine?
-
-Launch and access should stay separate in the design.
-
-### 1. Pre-existing server
-
-The simplest launch method is no launch at all.
-
-The user or operator already runs T3 on the target machine, and the client connects through a direct or tunneled WebSocket endpoint.
-
-This should be the first remote mode shipped because it validates the environment model with minimal extra machinery.
-
-### 2. Desktop-managed remote launch over SSH
-
-This is the main place where Zed is a useful reference.
-
-Useful ideas to borrow from Zed:
-
-- remote probing
-- platform detection
-- session directories with pid/log metadata
-- reconnect-friendly launcher behavior
-- desktop-owned connection UX
-
-What should be different in T3:
-
-- no custom stdio/socket proxy protocol between renderer and remote runtime
-- no attempt to make the remote runtime look like an editor transport
-- keep the final client-to-server connection as WebSocket
-
-The recommended T3 flow is:
-
-1. Desktop connects over SSH.
-2. Desktop probes the remote machine and verifies T3 availability.
-3. Desktop launches or reuses a remote T3 server.
-4. Desktop establishes local port forwarding.
-5. Renderer connects to the forwarded WebSocket endpoint as a normal environment.
-
-The saved environment should remember that it was created by desktop SSH launch only for reconnect and lifecycle UX. That metadata should not change the server protocol or the environment identity model.
-
-Failure handling should be explicit:
-
-- SSH authentication failure should surface before any environment is saved
-- remote launch failure should include remote logs or the launcher command output when available
-- forwarded-port failure should leave the saved environment disconnected rather than falling back to an unrelated endpoint
-- reconnect should attempt to restore the SSH bridge before reconnecting the normal WebSocket client
-
-### 3. Client-managed local publish
-
-This is the inverse of remote launch: a local T3 server is already running, and the client publishes it through a tunnel.
-
-This is useful for:
-
-- exposing a desktop-hosted environment to mobile
-- temporary remote access without changing router or firewall settings
-
-This is still a launch concern, not a new environment kind.
-
-## Why access and launch must stay separate
-
-These concerns are easy to conflate, but separating them prevents architectural drift.
-
-Examples:
-
-- A manually hosted T3 server might be reached through direct `wss`.
-- The same server might also be reachable through a tunnel.
-- An SSH-managed server might be launched over SSH but then reached through forwarded WebSocket.
-- A local desktop server might be published through a tunnel for mobile.
-
-In all of those cases, the `ExecutionEnvironment` is the same kind of thing.
-
-Only the launch and access paths differ.
-
-## Version Coordination
-
-Remote environments may stay online while web, desktop, or mobile clients move to a newer release.
-The environment descriptor therefore carries the running server version and may advertise a safe
-replacement path. The web and desktop UI use that information to show the appropriate action
-without making the connection transport responsible for process management.
-
-Published CLI servers on supported hosts can install and hand off to the client's exact version. A
-desktop-managed backend instead points the user to the desktop app on that machine, while older or
-unsupported servers fall back to a manual relaunch. The existing connection supervisor owns the
-disconnect and reconnect just as it would for any other involuntary socket close.
-
-See [Server Update Architecture](./server-updates.md) for capability detection, installation safety,
-and restart sequencing.
-
-## Security model
-
-Remote support must assume that some environments will be reachable over untrusted networks.
-
-That means:
-
-- remote-capable environments should require explicit authentication
-- tunnel exposure should not rely on obscurity
-- client-saved endpoints should carry enough auth metadata to reconnect safely
-
-T3 already supports a WebSocket auth token on the server. That should become a first-class part of environment access rather than remaining an incidental query parameter convention.
-
-For publicly reachable environments, authenticated access should be treated as required.
-
-Hosted pairing should be treated as a client-side convenience only. The hosted app must not receive pairing tokens through query parameters, must not store pairing state server-side, and must not imply that an HTTP backend is safe or reachable from an HTTPS browser context.
-
-## Relationship to Zed
-
-Zed is a useful reference implementation for managed remote launch and reconnect behavior.
-
-The relevant lessons are:
-
-- remote bootstrap should be explicit
-- reconnect should be first-class
-- connection UX belongs in the client shell
-- runtime ownership should stay clearly on the remote host
-
-The important mismatch is transport shape.
-
-Zed needs a custom proxy/server protocol because its remote boundary sits below the editor and project runtime.
-
-T3 should not copy that part.
-
-T3 already has the right runtime boundary:
-
-- one T3 server per environment
-- ordinary HTTP/WebSocket between client and environment
-
-So T3 should borrow Zed's launch discipline, not its transport protocol.
-
-## Recommended rollout
-
-1. First-class known environments and access endpoints.
-2. Direct `ws` / `wss` remote environments.
-3. Authenticated tunnel-backed environments.
-4. Desktop-managed SSH launch and forwarding.
-5. Multi-environment UI improvements after the base runtime path is proven.
-
-This ordering keeps the architecture network-first and transport-agnostic while still leaving room for richer managed remote flows.
diff --git a/docs/architecture/runtime-modes.md b/docs/architecture/runtime-modes.md
deleted file mode 100644
index 956b242e1c1..00000000000
--- a/docs/architecture/runtime-modes.md
+++ /dev/null
@@ -1,6 +0,0 @@
-# Runtime modes
-
-T3 Code has a global runtime mode switch in the chat toolbar:
-
-- **Full access** (default): starts sessions with `approvalPolicy: never` and `sandboxMode: danger-full-access`.
-- **Supervised**: starts sessions with `approvalPolicy: on-request` and `sandboxMode: workspace-write`, then prompts in-app for command/file approvals.
diff --git a/docs/getting-started/codex-prerequisites.md b/docs/getting-started/codex-prerequisites.md
deleted file mode 100644
index 608374d5db9..00000000000
--- a/docs/getting-started/codex-prerequisites.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# Codex prerequisites
-
-- Install Codex CLI so `codex` is on your PATH.
-- Authenticate Codex before running T3 Code (for example via API key or ChatGPT auth supported by Codex).
-- T3 Code starts the server via `codex app-server` per session.
diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md
deleted file mode 100644
index 2206d53ee58..00000000000
--- a/docs/getting-started/quick-start.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# Quick start
-
-```bash
-# Development (with hot reload)
-bun run dev
-
-# Desktop development
-bun run dev:desktop
-
-# Desktop development on an isolated port set
-T3CODE_DEV_INSTANCE=feature-xyz bun run dev:desktop
-
-# Production
-bun run build
-bun run start
-
-# Build a shareable macOS .dmg (arm64 by default)
-bun run dist:desktop:dmg
-
-# Or from any project directory after publishing:
-npx t3
-```
diff --git a/docs/internals/ci.md b/docs/internals/ci.md
new file mode 100644
index 00000000000..e88b9a9e4b5
--- /dev/null
+++ b/docs/internals/ci.md
@@ -0,0 +1,24 @@
+# CI quality gates
+
+> For maintainers. Using T3 Code? See [docs/user](../user/).
+
+[`.github/workflows/ci.yml`](../../.github/workflows/ci.yml) runs four jobs 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
+  still exports its expected symbols.
+- **Test**: `vp run test` across the workspace.
+- **Mobile Native Static Analysis**: `vp run lint:mobile` on macOS, wrapping
+  `scripts/mobile-native-static-check.ts`.
+- **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/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.
+
+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
new file mode 100644
index 00000000000..46fe0c82716
--- /dev/null
+++ b/docs/internals/connection-runtime.md
@@ -0,0 +1,183 @@
+# 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.
+
+## Source Boundaries
+
+Applications must import explicit package subpaths; the package intentionally
+has no root export. The subpaths are documented in
+[packages/client-runtime/README.md](../../packages/client-runtime/README.md),
+with the `exports` map in that package's `package.json` as the authoritative
+list. Files that are not exported are implementation details.
+
+## Application Boundary
+
+The application root mounts the shared connection layer, creates its own Atom
+runtime, and selects the domain atom factories required by that platform. Web
+and mobile may expose different hooks and features without changing connection
+ownership.
+
+Application code must not construct RPC clients, retry loops, or raw
+orchestration commands. Persistence paths belong to the platform registration
+and cache stores, with explicit migration or invalidation policy.
+
+## Verification
+
+Core state-machine tests use `@effect/vitest` and deterministic service layers.
+Required coverage includes:
+
+- offline startup and online wakeup;
+- forever retry with the 16-second cap;
+- explicit retry interrupting backoff;
+- authentication wakeups;
+- involuntary close and reconnect;
+- explicit removal clearing all owned state;
+- relay token reuse and refresh;
+- progressive relay discovery;
+- shell and thread cache hydration;
+- durable subscriptions switching sessions;
+- command metadata and idempotent queued-command metadata.
+
+[layer]: ../../packages/client-runtime/src/connection/layer.ts
+[resolver]: ../../packages/client-runtime/src/connection/resolver.ts
+[driver]: ../../packages/client-runtime/src/connection/driver.ts
+[registry]: ../../packages/client-runtime/src/connection/registry.ts
+[supervisor]: ../../packages/client-runtime/src/connection/supervisor.ts
+[session]: ../../packages/client-runtime/src/rpc/session.ts
+[client]: ../../packages/client-runtime/src/rpc/client.ts
diff --git a/docs/cloud/environment-auth.md b/docs/internals/environment-auth.md
similarity index 70%
rename from docs/cloud/environment-auth.md
rename to docs/internals/environment-auth.md
index af92bcb474d..5f4f5b6e960 100644
--- a/docs/cloud/environment-auth.md
+++ b/docs/internals/environment-auth.md
@@ -1,5 +1,7 @@
 # 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.
@@ -61,26 +63,52 @@ The response has the token-exchange shape:
   "access_token": "<opaque session token>",
   "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
   "token_type": "Bearer",
-  "expires_in": 3600,
+  "expires_in": 2592000,
   "scope": "orchestration:read orchestration:operate terminal:operate review:write relay:read"
 }
 ```
 
+Sessions issued from a plain bearer exchange use the store's
+`DEFAULT_SESSION_TTL` of 30 days. The shorter one-hour `expires_in: 3600` applies
+only to DPoP-bound exchanges, where the token is additionally constrained by a
+proof key. See `SessionStore.ts` and `EnvironmentAuth.ts`.
+
 Requested scopes must be a subset of the one-time bootstrap credential grant.
 An ordinary paired client therefore cannot exchange its grant for
 `access:read`, `access:write`, or `relay:write`.
 
+### DPoP-Bound Access Token
+
+The same `/oauth/token` exchange supports proof-of-possession tokens. A client
+that sends a `DPoP` header has its proof verified by `verifyRequestDpopProof`;
+the resulting JWK thumbprint is stored on the session, which is then issued with
+method `dpop-access-token` and a one-hour TTL instead of the bearer default. An
+invalid proof gets a DPoP challenge header and a credential error rather than a
+bearer token.
+
+`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. This keeps bearer tokens and
-browser cookies out of WebSocket URLs while allowing the socket handshake to
-authenticate. The ticket carries its session's scopes; each RPC method then
-enforces `orchestration:read`, `orchestration:operate`, `terminal:operate`,
-`review:write`, or `access:read` as appropriate. 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.
+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
 
diff --git a/docs/reference/encyclopedia.md b/docs/internals/glossary.md
similarity index 60%
rename from docs/reference/encyclopedia.md
rename to docs/internals/glossary.md
index 82a58fd959c..da16f74d339 100644
--- a/docs/reference/encyclopedia.md
+++ b/docs/internals/glossary.md
@@ -1,4 +1,6 @@
-# Encyclopedia
+# 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.
 
@@ -16,7 +18,7 @@ This is a living glossary for T3 Code. It explains what common terms mean in thi
 
 #### Project
 
-The top-level workspace record in the app. In [the orchestration contracts][1], a project has a `workspaceRoot`, a title, and one or more threads. See [workspace-layout.md][2].
+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
 
@@ -24,7 +26,7 @@ The root filesystem path for a project. In [the orchestration model][1], it is t
 
 #### 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 in [GitCore.ts][3].
+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
 
@@ -34,7 +36,7 @@ The main durable unit of conversation and workspace history. In [the orchestrati
 
 #### Turn
 
-A single user-to-assistant work cycle inside a thread. It starts with user input and ends when follow-up work like checkpointing settles. See [the contracts][1], [ProviderRuntimeIngestion.ts][5], and [CheckpointReactor.ts][6].
+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
 
@@ -80,20 +82,19 @@ A side-effecting service that handles follow-up work after events or runtime sig
 
 #### Receipt
 
-A lightweight typed runtime signal emitted when an async milestone completes. See [RuntimeReceiptBus.ts][13].
-Examples include `checkpoint.baseline.captured`, `checkpoint.diff.finalized`, and `turn.processing.quiesced`, which are emitted by flows such as [CheckpointReactor.ts][6].
+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. In [the receipt schema][13], it means the follow-up work has settled, including work in [CheckpointReactor.ts][6].
+"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 [provider-architecture.md][16].
+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. See [ProviderService.ts][14], [ProviderAdapter.ts][15], and [CodexAdapter.ts][17].
+The backend agent runtime that actually performs work. Five drivers ship built in: Codex, Claude, Cursor, Grok, and OpenCode. See [ProviderService.ts][14], [ProviderAdapter.ts][15], and [CodexAdapter.ts][17] as a representative adapter.
 
 #### Session
 
@@ -101,15 +102,15 @@ The live provider-backed runtime attached to a thread. Session shape is in [the
 
 #### Runtime mode
 
-The safety/access mode for a thread or session. In [the contracts][1], the main values are `approval-required` and `full-access`. See [runtime-modes.md][18].
+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 main values are `default` and `plan`. See [runtime-modes.md][18].
+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` delivers a completed result. See [ProviderService.ts][14].
+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
 
@@ -143,38 +144,38 @@ The file patch and changed-file summary for one turn. It is usually computed in
 
 - If you see `requested`, think "intent recorded".
 - If you see `completed`, think "result applied".
-- If you see `receipt`, think "async milestone signal".
+- 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.md][24]
-- [provider-architecture.md][16]
-- [runtime-modes.md][18]
-- [workspace-layout.md][2]
+- [Architecture overview][24]
+- [Provider architecture][16]
+- [Permission modes][18]
+- [Workspace layout][2]
 
-[1]: ../packages/contracts/src/orchestration.ts
+[1]: ../../packages/contracts/src/orchestration.ts
 [2]: ./workspace-layout.md
-[3]: ../apps/server/src/git/Layers/GitCore.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]: ./provider-architecture.md
-[17]: ../apps/server/src/provider/Layers/CodexAdapter.ts
-[18]: ./runtime-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]: ./architecture.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
diff --git a/docs/internals/overview.md b/docs/internals/overview.md
new file mode 100644
index 00000000000..b9454f7b58d
--- /dev/null
+++ b/docs/internals/overview.md
@@ -0,0 +1,152 @@
+# 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 (5 built-in drivers) │
+│  checkpointing, VCS, terminals, filesystem     │
+└──────────────────┬─────────────────────────────┘
+                   │ per-driver transport
+┌──────────────────▼─────────────────────────────┐
+│ Agent CLIs: Codex, Claude, Cursor, Grok,       │
+│ OpenCode                                       │
+└────────────────────────────────────────────────┘
+```
+
+## 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 and publishes committed events to subscribers.
+
+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.
+
+## 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, and
+[`CheckpointReactor`][checkpoint] captures and reverts workspace checkpoints.
+
+`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 the three 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
+
+Five drivers ship built in, registered in [`builtInDrivers.ts`][drivers] as `BUILT_IN_DRIVERS`:
+Codex, Claude, Cursor, Grok, and OpenCode. 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)
+- [Remote environments](./remote.md), [Server updates](./server-updates.md)
+- [Resource telemetry](./resource-telemetry.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
+[receipts]: ../../apps/server/src/orchestration/Layers/RuntimeReceiptBus.ts
+[drivers]: ../../apps/server/src/provider/builtInDrivers.ts
diff --git a/docs/internals/providers.md b/docs/internals/providers.md
new file mode 100644
index 00000000000..a309d70f03d
--- /dev/null
+++ b/docs/internals/providers.md
@@ -0,0 +1,92 @@
+# 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 five 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] |
+
+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.
+
+## 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.
+
+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.
+
+## 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
+[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
diff --git a/docs/internals/remote.md b/docs/internals/remote.md
new file mode 100644
index 00000000000..afce95f725b
--- /dev/null
+++ b/docs/internals/remote.md
@@ -0,0 +1,235 @@
+# 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.
+
+### 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).
+
+## 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
diff --git a/docs/architecture/resource-telemetry.md b/docs/internals/resource-telemetry.md
similarity index 99%
rename from docs/architecture/resource-telemetry.md
rename to docs/internals/resource-telemetry.md
index 504aa3f8b64..0d07f31f8ac 100644
--- a/docs/architecture/resource-telemetry.md
+++ b/docs/internals/resource-telemetry.md
@@ -1,5 +1,7 @@
 # Resource telemetry architecture
 
+> For maintainers. Using T3 Code? See [docs/user](../user/).
+
 Status: implemented
 
 ## Purpose
diff --git a/docs/internals/scripts.md b/docs/internals/scripts.md
new file mode 100644
index 00000000000..2a020701064
--- /dev/null
+++ b/docs/internals/scripts.md
@@ -0,0 +1,119 @@
+# 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.
+- `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.
+
+### 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.
+- 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/architecture/server-updates.md b/docs/internals/server-updates.md
similarity index 89%
rename from docs/architecture/server-updates.md
rename to docs/internals/server-updates.md
index 981f4e1eb42..1e017737148 100644
--- a/docs/architecture/server-updates.md
+++ b/docs/internals/server-updates.md
@@ -1,5 +1,7 @@
 # Server Update Architecture
 
+> For maintainers. Using T3 Code? See [docs/user](../user/).
+
 T3 Code can update a connected server to the exact version of the client that detected version
 drift. This path exists primarily for remote environments, where the user may not have a terminal
 open on the server machine.
@@ -59,10 +61,11 @@ flowchart TD
     B -->|boot-service or respawn| E{Progress capability}
     E -->|present| F[server.updateServerWithProgress]
     E -->|missing| G[server.updateServer fallback]
-    F --> H[Download exact t3 version]
+    F --> H[Install exact t3 version in pinned runtime]
     G --> H
-    H --> I[Install and run version preflight]
-    I -->|fails| J[Remove failed runtime and keep current server]
+    H --> I[Run version preflight]
+    I -->|bad code or version| J[Remove candidate runtime and keep current server]
+    I -->|cannot run preflight| J2[Keep candidate and current server]
     I -->|passes| K{Handoff method}
     K -->|boot-service| L[Rewrite and restart T3 systemd unit]
     K -->|respawn| M[Start delayed replacement and exit current process]
@@ -82,8 +85,14 @@ successfully. Boot-service setup and self-update share the same process-wide ins
 they cannot mutate a pinned runtime concurrently.
 
 Before any restart, the current Node executable runs the replacement with `--version`. A failed
-install, failed preflight, or wrong reported version leaves the current server running. A failed
-preflight also removes the candidate runtime so retrying the same version performs a clean install.
+install, failed preflight, or wrong reported version leaves the current server running.
+
+Candidate cleanup is narrower than "any failed preflight". The candidate runtime is removed only when
+the preflight process actually completes and reports a bad exit code or the wrong version: that is
+the case where a completed npm install produced an unusable tree, so retrying the same version must
+perform a clean install rather than reuse it. If the preflight cannot run at all, for example a spawn
+error or the `PREFLIGHT_TIMEOUT` elapsing, the update fails before reaching cleanup and the candidate
+directory is left in place.
 
 ## Host Service Lifecycle
 
diff --git a/docs/cloud/t3-code-connect-auth-flow.html b/docs/internals/t3-code-connect-auth-flow.html
similarity index 100%
rename from docs/cloud/t3-code-connect-auth-flow.html
rename to docs/internals/t3-code-connect-auth-flow.html
diff --git a/docs/cloud/t3-connect-clerk.md b/docs/internals/t3-connect.md
similarity index 75%
rename from docs/cloud/t3-connect-clerk.md
rename to docs/internals/t3-connect.md
index 2fe48243a59..c8a0217919f 100644
--- a/docs/cloud/t3-connect-clerk.md
+++ b/docs/internals/t3-connect.md
@@ -1,8 +1,16 @@
-# T3 Connect Clerk Setup
+# T3 Connect
 
-T3 Connect uses one Clerk application for web, desktop, and mobile authentication. The relay accepts
-Clerk JWTs only when they are generated from the `t3-relay` template with the shared
-`t3-code-relay` audience.
+> 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
 
@@ -35,10 +43,11 @@ should set `T3CODE_CLERK_PUBLISHABLE_KEY`, `T3CODE_CLERK_JWT_TEMPLATE`,
 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. When the CLI public values are
-absent, the `t3 connect` CLI command group is omitted. The bundled server still accepts runtime
-overrides for self-hosted or operator-managed
-deployments.
+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`,
@@ -63,7 +72,12 @@ 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 `http://127.0.0.1:34338/callback` as an allowed redirect URI.
+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.
@@ -72,17 +86,20 @@ The CLI derives Clerk's frontend API URL from the publishable key and calls Cler
 `/oauth/authorize` and `/oauth/token` endpoints 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 CLI supports these headless operations:
+The connect command group is:
 
 ```sh
+t3 connect            # default: onboarding
 t3 connect login
-t3 connect link
-t3 connect status
+t3 connect link       # --publish-only
+t3 connect status     # --json
+t3 connect publish    # --disable
 t3 connect unlink
 t3 connect logout
-t3 serve
 ```
 
+`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
@@ -95,16 +112,21 @@ 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`.
 
-The current OAuth callback listener binds to loopback port `34338`. When running the CLI over SSH,
-forward that port before running `t3 connect login` or `t3 connect link`:
+### 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>
 ```
 
-A relay-hosted callback broker can remove this port-forward requirement later without changing the
-stored PKCE token model.
-
 ## JWT Template
 
 In **Clerk Dashboard > JWT templates**, create a template with:
@@ -207,34 +229,26 @@ 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.
 
-## Enable Waitlist Access
-
-For a private beta where people should request access, use **Clerk Dashboard > Waitlist**:
-
-1. Toggle on **Enable waitlist** and save.
-2. Review requests on the same page and select **Invite** or **Deny**.
-
-Approved signed-in users manage T3 Connect under **Connections**. The web and desktop sidebars do
-not expose a dedicated account or waitlist control. Signed-out users reach Clerk's waitlist and
-sign-in flow contextually from the T3 Connect controls on the Connections page.
-
-On mobile, signed-out users open **Settings > T3 Account** to reach `/settings/waitlist` within the
-Settings form sheet. It submits enrollment through Clerk's `useWaitlist()` flow because the prebuilt
-`<Waitlist />` component is web-only in the Expo SDK. Approved users can use **Sign in** from that
-screen.
+## Sign-in Surfaces
 
-## Alternative: Known-User Allowlist
+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.
 
-For a closed beta where all permitted users are known in advance, use an allowlist instead of a
-request-and-approval waitlist:
+## Restricting Sign-ups: Known-User Allowlist
 
-To restrict the beta to permitted email addresses or domains:
+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 without a waitlist request flow.
+   manually created.
 
 Do not enable an empty allowlist: it blocks all new sign-ups.
 
diff --git a/docs/internals/workspace-layout.md b/docs/internals/workspace-layout.md
new file mode 100644
index 00000000000..e933e452891
--- /dev/null
+++ b/docs/internals/workspace-layout.md
@@ -0,0 +1,63 @@
+# 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/ci.md b/docs/operations/ci.md
deleted file mode 100644
index 7a0447ec070..00000000000
--- a/docs/operations/ci.md
+++ /dev/null
@@ -1,6 +0,0 @@
-# CI quality gates
-
-- `.github/workflows/ci.yml` runs `vp check` (lint + typecheck), `vpr typecheck`, and `vp run test` on pull requests and pushes to `main`.
-- `.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.
-- The release workflow 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.
-- See [Release Checklist](./release.md) for the full release/signing setup checklist.
diff --git a/docs/operations/effect-fn-checklist.md b/docs/operations/effect-fn-checklist.md
deleted file mode 100644
index 938dea8d681..00000000000
--- a/docs/operations/effect-fn-checklist.md
+++ /dev/null
@@ -1,198 +0,0 @@
-# Effect.fn Refactor Checklist
-
-Generated from a repo scan for non-test wrapper-style candidates matching either `=> Effect.gen(function* ...)` or `return Effect.gen(function* ...)`.
-
-Refactor Method:
-
-```ts
-// Old
-function old () {
-    return Effect.gen(function* () {
-        ...
-    });
-}
-
-const old2 = () => Effect.gen(function* () {
-    ...
-});
-```
-
-```ts
-// New
-const new = Effect.fn('functionName')(function* () {
-    ...
-})
-```
-
-- Use `Effect.fn('name')(function* (input: Input): Effect.fn.Return<A, E, R> {})` to annotate the return type of the function if needed.
-
-- The 2nd argument works as a pipe, and it gets the effect and input as arguments:
-
-```ts
-Effect.fn("name")(
-  function* (input: Input): Effect.fn.Return<A, E, R> {},
-  (effect, input) => Effect.catch(effect, (reason) => Effect.logWarning("Err", { input, reason })),
-);
-```
-
-## Summary
-
-- Total non-test candidates: `322`
-
-## Suggested Order
-
-- [ ] `apps/server/src/provider/Layers/ProviderService.ts`
-- [x] `apps/server/src/provider/Layers/ClaudeAdapter.ts`
-- [x] `apps/server/src/provider/Layers/CodexAdapter.ts`
-- [x] `apps/server/src/git/Layers/GitCore.ts`
-- [x] `apps/server/src/git/Layers/GitManager.ts`
-- [x] `apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts`
-- [x] `apps/server/src/orchestration/Layers/ProjectionPipeline.ts`
-- [ ] `apps/server/src/orchestration/Layers/OrchestrationEngine.ts`
-- [ ] `apps/server/src/provider/Layers/EventNdjsonLogger.ts`
-- [ ] `Everything else`
-
-## Checklist
-
-### `apps/server/src/provider/Layers/ClaudeAdapter.ts` (`62`)
-
-- [x] [buildUserMessageEffect](../../apps/server/src/provider/Layers/ClaudeAdapter.ts#L554)
-- [x] [makeClaudeAdapter](../../apps/server/src/provider/Layers/ClaudeAdapter.ts#L913)
-- [x] [startSession](../../apps/server/src/provider/Layers/ClaudeAdapter.ts#L2414)
-- [x] [sendTurn](../../apps/server/src/provider/Layers/ClaudeAdapter.ts#L2887)
-- [x] [interruptTurn](../../apps/server/src/provider/Layers/ClaudeAdapter.ts#L2975)
-- [x] [readThread](../../apps/server/src/provider/Layers/ClaudeAdapter.ts#L2984)
-- [x] [rollbackThread](../../apps/server/src/provider/Layers/ClaudeAdapter.ts#L2990)
-- [x] [stopSession](../../apps/server/src/provider/Layers/ClaudeAdapter.ts#L3039)
-- [x] Internal helpers and callback wrappers in this file
-
-### `apps/server/src/git/Layers/GitCore.ts` (`58`)
-
-- [x] [makeGitCore](../../apps/server/src/git/Layers/GitCore.ts#L513)
-- [x] [handleTraceLine](../../apps/server/src/git/Layers/GitCore.ts#L324)
-- [x] [emitCompleteLines](../../apps/server/src/git/Layers/GitCore.ts#L455)
-- [x] [commit](../../apps/server/src/git/Layers/GitCore.ts#L1190)
-- [x] [pushCurrentBranch](../../apps/server/src/git/Layers/GitCore.ts#L1223)
-- [x] [pullCurrentBranch](../../apps/server/src/git/Layers/GitCore.ts#L1323)
-- [x] [checkoutBranch](../../apps/server/src/git/Layers/GitCore.ts#L1727)
-- [x] Service methods and callback wrappers in this file
-
-### `apps/server/src/git/Layers/GitManager.ts` (`28`)
-
-- [x] [configurePullRequestHeadUpstream](../../apps/server/src/git/Layers/GitManager.ts#L387)
-- [x] [materializePullRequestHeadBranch](../../apps/server/src/git/Layers/GitManager.ts#L428)
-- [x] [findOpenPr](../../apps/server/src/git/Layers/GitManager.ts#L576)
-- [x] [findLatestPr](../../apps/server/src/git/Layers/GitManager.ts#L602)
-- [x] [runCommitStep](../../apps/server/src/git/Layers/GitManager.ts#L728)
-- [x] [runPrStep](../../apps/server/src/git/Layers/GitManager.ts#L842)
-- [x] [runFeatureBranchStep](../../apps/server/src/git/Layers/GitManager.ts#L1106)
-- [x] Remaining helpers and nested callback wrappers in this file
-
-### `apps/server/src/orchestration/Layers/ProjectionPipeline.ts` (`25`)
-
-- [x] [runProjectorForEvent](../../apps/server/src/orchestration/Layers/ProjectionPipeline.ts#L1161)
-- [x] [applyProjectsProjection](../../apps/server/src/orchestration/Layers/ProjectionPipeline.ts#L357)
-- [x] [applyThreadsProjection](../../apps/server/src/orchestration/Layers/ProjectionPipeline.ts#L415)
-- [x] `Effect.forEach(..., threadId => Effect.gen(...))` callbacks around `L250`
-- [x] `Effect.forEach(..., entry => Effect.gen(...))` callbacks around `L264`
-- [x] `Effect.forEach(..., entry => Effect.gen(...))` callbacks around `L305`
-- [x] Remaining apply helpers in this file
-
-### `apps/server/src/provider/Layers/ProviderService.ts` (`24`)
-
-- [ ] [makeProviderService](../../apps/server/src/provider/Layers/ProviderService.ts#L134)
-- [ ] [recoverSessionForThread](../../apps/server/src/provider/Layers/ProviderService.ts#L196)
-- [ ] [resolveRoutableSession](../../apps/server/src/provider/Layers/ProviderService.ts#L255)
-- [ ] [startSession](../../apps/server/src/provider/Layers/ProviderService.ts#L284)
-- [ ] [sendTurn](../../apps/server/src/provider/Layers/ProviderService.ts#L347)
-- [ ] [interruptTurn](../../apps/server/src/provider/Layers/ProviderService.ts#L393)
-- [ ] [respondToRequest](../../apps/server/src/provider/Layers/ProviderService.ts#L411)
-- [ ] [respondToUserInput](../../apps/server/src/provider/Layers/ProviderService.ts#L430)
-- [ ] [stopSession](../../apps/server/src/provider/Layers/ProviderService.ts#L445)
-- [ ] [listSessions](../../apps/server/src/provider/Layers/ProviderService.ts#L466)
-- [ ] [rollbackConversation](../../apps/server/src/provider/Layers/ProviderService.ts#L516)
-- [ ] [runStopAll](../../apps/server/src/provider/Layers/ProviderService.ts#L538)
-
-### `apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts` (`14`)
-
-- [x] [finalizeAssistantMessage](../../apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts#L680)
-- [x] [upsertProposedPlan](../../apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts#L722)
-- [x] [finalizeBufferedProposedPlan](../../apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts#L761)
-- [x] [clearTurnStateForSession](../../apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts#L800)
-- [x] [processRuntimeEvent](../../apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts#L908)
-- [x] Nested callback wrappers in this file
-
-### `apps/server/src/provider/Layers/CodexAdapter.ts` (`12`)
-
-- [x] [makeCodexAdapter](../../apps/server/src/provider/Layers/CodexAdapter.ts#L1317)
-- [x] [sendTurn](../../apps/server/src/provider/Layers/CodexAdapter.ts#L1399)
-- [x] [writeNativeEvent](../../apps/server/src/provider/Layers/CodexAdapter.ts#L1546)
-- [x] [listener](../../apps/server/src/provider/Layers/CodexAdapter.ts#L1555)
-- [x] Remaining nested callback wrappers in this file
-
-### `apps/server/src/checkpointing/CheckpointStore.ts` (`10`)
-
-- [ ] [captureCheckpoint](../../apps/server/src/checkpointing/CheckpointStore.ts#L123)
-- [ ] [restoreCheckpoint](../../apps/server/src/checkpointing/CheckpointStore.ts#L137)
-- [ ] [diffCheckpoints](../../apps/server/src/checkpointing/CheckpointStore.ts#L144)
-- [ ] [deleteCheckpointRefs](../../apps/server/src/checkpointing/CheckpointStore.ts#L151)
-- [ ] Nested callback wrappers in this file
-
-### `apps/server/src/provider/Layers/EventNdjsonLogger.ts` (`9`)
-
-- [ ] [toLogMessage](../../apps/server/src/provider/Layers/EventNdjsonLogger.ts#L77)
-- [ ] [makeThreadWriter](../../apps/server/src/provider/Layers/EventNdjsonLogger.ts#L102)
-- [ ] [makeEventNdjsonLogger](../../apps/server/src/provider/Layers/EventNdjsonLogger.ts#L174)
-- [ ] [write](../../apps/server/src/provider/Layers/EventNdjsonLogger.ts#L231)
-- [ ] [close](../../apps/server/src/provider/Layers/EventNdjsonLogger.ts#L247)
-- [ ] Flush and writer-resolution callback wrappers in this file
-
-### `apps/server/scripts/cli.ts` (`8`)
-
-- [ ] Command handlers around [cli.ts](../../apps/server/scripts/cli.ts#L125)
-- [ ] Command handlers around [cli.ts](../../apps/server/scripts/cli.ts#L170)
-- [ ] Resource callbacks around [cli.ts](../../apps/server/scripts/cli.ts#L221)
-- [ ] Resource callbacks around [cli.ts](../../apps/server/scripts/cli.ts#L239)
-
-### `apps/server/src/orchestration/Layers/OrchestrationEngine.ts` (`7`)
-
-- [ ] [processEnvelope](../../apps/server/src/orchestration/Layers/OrchestrationEngine.ts#L64)
-- [ ] [dispatch](../../apps/server/src/orchestration/Layers/OrchestrationEngine.ts#L218)
-- [ ] Catch/stream callback wrappers around [OrchestrationEngine.ts](../../apps/server/src/orchestration/Layers/OrchestrationEngine.ts#L162)
-- [ ] Catch/stream callback wrappers around [OrchestrationEngine.ts](../../apps/server/src/orchestration/Layers/OrchestrationEngine.ts#L200)
-
-### `apps/server/src/orchestration/projector.ts` (`5`)
-
-- [ ] `switch` branch wrapper at [projector.ts](../../apps/server/src/orchestration/projector.ts#L242)
-- [ ] `switch` branch wrapper at [projector.ts](../../apps/server/src/orchestration/projector.ts#L336)
-- [ ] `switch` branch wrapper at [projector.ts](../../apps/server/src/orchestration/projector.ts#L397)
-- [ ] `switch` branch wrapper at [projector.ts](../../apps/server/src/orchestration/projector.ts#L446)
-- [ ] `switch` branch wrapper at [projector.ts](../../apps/server/src/orchestration/projector.ts#L478)
-
-### Smaller clusters
-
-- [ ] [packages/shared/src/DrainableWorker.ts](../../packages/shared/src/DrainableWorker.ts) (`4`)
-- [ ] [apps/server/src/wsServer/pushBus.ts](../../apps/server/src/wsServer/pushBus.ts) (`4`)
-- [ ] [apps/server/src/wsServer.ts](../../apps/server/src/wsServer.ts) (`4`)
-- [ ] [apps/server/src/provider/Layers/ProviderRegistry.ts](../../apps/server/src/provider/Layers/ProviderRegistry.ts) (`4`)
-- [ ] [apps/server/src/persistence/Layers/Sqlite.ts](../../apps/server/src/persistence/Layers/Sqlite.ts) (`4`)
-- [ ] [apps/server/src/orchestration/Layers/ProviderCommandReactor.ts](../../apps/server/src/orchestration/Layers/ProviderCommandReactor.ts) (`4`)
-- [ ] [apps/server/src/main.ts](../../apps/server/src/main.ts) (`4`)
-- [ ] [apps/server/src/keybindings.ts](../../apps/server/src/keybindings.ts) (`4`)
-- [ ] [apps/server/src/git/Layers/CodexTextGeneration.ts](../../apps/server/src/git/Layers/CodexTextGeneration.ts) (`4`)
-- [ ] [apps/server/src/serverLayers.ts](../../apps/server/src/serverLayers.ts) (`3`)
-- [ ] [apps/server/src/telemetry/Layers/AnalyticsService.ts](../../apps/server/src/telemetry/Layers/AnalyticsService.ts) (`2`)
-- [ ] [apps/server/src/telemetry/Identify.ts](../../apps/server/src/telemetry/Identify.ts) (`2`)
-- [ ] [apps/server/src/provider/Layers/ProviderAdapterRegistry.ts](../../apps/server/src/provider/Layers/ProviderAdapterRegistry.ts) (`2`)
-- [ ] [apps/server/src/provider/Layers/CodexProvider.ts](../../apps/server/src/provider/Layers/CodexProvider.ts) (`2`)
-- [ ] [apps/server/src/provider/Layers/ClaudeProvider.ts](../../apps/server/src/provider/Layers/ClaudeProvider.ts) (`2`)
-- [ ] [apps/server/src/persistence/NodeSqliteClient.ts](../../apps/server/src/persistence/NodeSqliteClient.ts) (`2`)
-- [ ] [apps/server/src/persistence/Migrations.ts](../../apps/server/src/persistence/Migrations.ts) (`2`)
-- [ ] [apps/server/src/open.ts](../../apps/server/src/open.ts) (`2`)
-- [ ] [apps/server/src/git/Layers/ClaudeTextGeneration.ts](../../apps/server/src/git/Layers/ClaudeTextGeneration.ts) (`2`)
-- [ ] [apps/server/src/checkpointing/CheckpointDiffQuery.ts](../../apps/server/src/checkpointing/CheckpointDiffQuery.ts) (`2`)
-- [ ] [apps/server/src/provider/makeManagedServerProvider.ts](../../apps/server/src/provider/makeManagedServerProvider.ts) (`1`)
-
-```
-
-```
diff --git a/docs/operations/mobile-app-store-screenshots.md b/docs/operations/mobile-app-store-screenshots.md
index 2c36ab9d008..27891cb5d63 100644
--- a/docs/operations/mobile-app-store-screenshots.md
+++ b/docs/operations/mobile-app-store-screenshots.md
@@ -1,5 +1,7 @@
 # Mobile app-store screenshot harness
 
+> For maintainers. Using T3 Code? See [docs/user](../user/).
+
 The screenshot harness runs the real mobile application against three disposable local T3
 environments. It creates an isolated base directory and server for each environment, real Git
 projects with deterministic content, seeded orchestration projections, and persisted terminal
@@ -44,35 +46,44 @@ delay allows native terminal and Git review data to finish rendering.
 A full capture regenerates the selected native project with Expo's clean development prebuild before
 building it. Use --skip-build for repeated captures after the first build.
 
-The harness uses its own Metro port (8199 by default), so an ordinary mobile server or another
-worktree cannot accidentally provide the bundle being photographed.
+The harness uses fixed Metro port `8199`, which separates it from Expo's normal default port but is
+shared across every checkout. The readiness check only verifies that the port is open; it does not
+verify process ownership. Concurrent screenshot harnesses in different worktrees can therefore
+collide or attach to the wrong Metro process.
+
+Every configured device defaults to dark appearance, so plain `pnpm screenshots:mobile` produces
+30 dark PNGs. Pass `--appearance light`, `--appearance dark`, or `--appearance both` to override the
+configured appearance; `both` produces 60 PNGs.
 
 The default matrix is:
 
-| Output folder                         | Capture target            | Upload dimensions | Store slot                                |
-| ------------------------------------- | ------------------------- | ----------------- | ----------------------------------------- |
-| `apple/iphone-6.9/{light,dark}/`      | iPhone 17 Pro Max         | 1320×2868         | App Store Connect iPhone 6.9-inch         |
-| `apple/iphone-6.5/{light,dark}/`      | disposable iPhone 14 Plus | 1284×2778         | App Store Connect iPhone 6.5-inch         |
-| `apple/ipad-13/{light,dark}/`         | iPad Pro 13-inch (M5)     | 2064×2752         | App Store Connect iPad 13-inch            |
-| `google-play/phone/{light,dark}/`     | Pixel AVD at 420 dpi      | 1080×1920         | Google Play phone, portrait 9:16          |
-| `google-play/tablet-7/{light,dark}/`  | Pixel AVD at 600dp width  | 1080×1920         | Google Play 7-inch tablet, portrait 9:16  |
-| `google-play/tablet-10/{light,dark}/` | Pixel AVD at 800dp width  | 1440×2560         | Google Play 10-inch tablet, portrait 9:16 |
-
-Each target captures thread, terminal, review, thread list, and environments, producing 30 PNG
-files for one appearance or 60 for both. Each appearance folder's five screenshots satisfy the configured Apple limit of 1–10, Google
+| Output folder                 | Capture target            | Upload dimensions | Store slot                                |
+| ----------------------------- | ------------------------- | ----------------- | ----------------------------------------- |
+| `apple/iphone-6.9/dark/`      | iPhone 17 Pro Max         | 1320×2868         | App Store Connect iPhone 6.9-inch         |
+| `apple/iphone-6.5/dark/`      | disposable iPhone 14 Plus | 1284×2778         | App Store Connect iPhone 6.5-inch         |
+| `apple/ipad-13/dark/`         | iPad Pro 13-inch (M5)     | 2064×2752         | App Store Connect iPad 13-inch            |
+| `google-play/phone/dark/`     | Pixel AVD at 420 dpi      | 1080×1920         | Google Play phone, portrait 9:16          |
+| `google-play/tablet-7/dark/`  | Pixel AVD at 600dp width  | 1080×1920         | Google Play 7-inch tablet, portrait 9:16  |
+| `google-play/tablet-10/dark/` | Pixel AVD at 800dp width  | 1440×2560         | Google Play 10-inch tablet, portrait 9:16 |
+
+Each target captures thread, terminal, review, thread list, and environments. Each appearance
+folder's five screenshots satisfy the configured Apple limit of 1–10, Google
 phone requirement of 2–8, and Google tablet recommendation/slot minimum of 4 with a maximum of 8.
 
 The generated tree is deliberately aligned with the store upload fields:
 
     artifacts/app-store/screenshots/
     ├── apple/
-    │   ├── iphone-6.9/{light,dark}/{thread,terminal,review,threads,environments}.png
-    │   ├── iphone-6.5/{light,dark}/{thread,terminal,review,threads,environments}.png
-    │   └── ipad-13/{light,dark}/{thread,terminal,review,threads,environments}.png
+    │   ├── iphone-6.9/dark/{thread,terminal,review,threads,environments}.png
+    │   ├── iphone-6.5/dark/{thread,terminal,review,threads,environments}.png
+    │   └── ipad-13/dark/{thread,terminal,review,threads,environments}.png
     └── google-play/
-        ├── phone/{light,dark}/{thread,terminal,review,threads,environments}.png
-        ├── tablet-7/{light,dark}/{thread,terminal,review,threads,environments}.png
-        └── tablet-10/{light,dark}/{thread,terminal,review,threads,environments}.png
+        ├── phone/dark/{thread,terminal,review,threads,environments}.png
+        ├── tablet-7/dark/{thread,terminal,review,threads,environments}.png
+        └── tablet-10/dark/{thread,terminal,review,threads,environments}.png
+
+A light-only run writes the same tree under `light/`; `--appearance both` writes both appearance
+folders.
 
 Edit [mobile-showcase.config.ts](../../scripts/mobile-showcase.config.ts) to change simulator or AVD
 names, light/dark appearance, scenes, output directory, capture delay, Android ABI, or viewport.
@@ -85,10 +96,11 @@ runs iOS and Android concurrently: iPhone and iPad capture on a
 12-vCPU Blacksmith macOS runner, while Android phone, 7-inch tablet, and 10-inch tablet capture on a
 16-vCPU Blacksmith Linux runner with a KVM-accelerated x86_64 emulator.
 
-Every job uploads its PNGs even when a later capture fails, which makes partial runs useful for
-diagnosis. Download `app-store-connect-screenshots` and `google-play-screenshots` from the workflow
-run's Artifacts section. Each job runs validation again immediately before upload. Artifacts are
-retained for 14 days.
+Every job uploads its PNGs even when capture fails, which makes partial runs useful for diagnosis.
+The separate validation step is success-gated: it runs before upload only when capture succeeds. If
+capture fails, the `always()` upload still publishes partial PNGs without re-validating them.
+Download `app-store-connect-screenshots` and `google-play-screenshots` from the workflow run's
+Artifacts section. Artifacts are retained for 14 days.
 
 The workflow uses the same checked-in device and scene matrix as local capture. Android remains
 ARM64 by default for local Apple Silicon development; CI sets `T3_SHOWCASE_ANDROID_ABI=x86_64` so the
@@ -111,11 +123,19 @@ Reuse the native build and retain the disposable environment:
 
     pnpm screenshots:mobile --device ipad-13 --skip-build --keep-running
 
-Run Metro separately:
+By default, let the screenshot runner start Metro on port `8199`. To keep Metro in a separate
+terminal, start it with the same showcase environment and explicit harness port:
+
+    cd apps/mobile
+    APP_VARIANT=development EXPO_PUBLIC_SHOWCASE=1 pnpm exec expo start --dev-client --port 8199
+
+Then run the capture from the repository root:
 
-    pnpm --filter @t3tools/mobile showcase
     pnpm screenshots:mobile --skip-build --skip-metro --device iphone-6.9
 
+`pnpm --filter @t3tools/mobile showcase` starts Expo on its normal port, so it is not compatible with
+the harness's `--skip-metro` mode.
+
 List the matrix and flags:
 
     pnpm screenshots:mobile --list
@@ -151,7 +171,9 @@ remote-first while the harness retains reliable loopback connections to its ephe
 ## Local prerequisites
 
 - iOS: Xcode command-line tools, the configured simulator runtimes, and installed CocoaPods.
-- Android: ANDROID_HOME (or the default macOS SDK path), adb, emulator, and the configured AVD.
+- Android: SDK resolution checks `ANDROID_HOME`, then `ANDROID_SDK_ROOT`, then defaults to
+  `$HOME/Library/Android/sdk` on macOS or `$HOME/Android/Sdk` on other platforms. The resolved SDK
+  must provide `adb` and `emulator`, and the configured AVD must exist.
 
 The harness is the source of truth for upload dimensions; do not resize its output. If store rules
 change, update the target's `storeAsset` specification. Capture fails when a PNG is the wrong size,
diff --git a/docs/operations/observability.md b/docs/operations/observability.md
index 1d55894b182..7341bfb5eda 100644
--- a/docs/operations/observability.md
+++ b/docs/operations/observability.md
@@ -1,39 +1,53 @@
 # Observability
 
+> For maintainers. Using T3 Code? See [docs/user](../user/).
+
 T3 Code has one server-side observability model:
 
 - pretty logs go to stdout for humans
 - completed spans go to a local NDJSON trace file
 - traces and metrics can also be exported over OTLP to a real backend like Grafana LGTM
 
-The local trace file is the persisted source of truth. There is no separate persisted server log file anymore.
+The local trace file is the persisted source of truth for normal local launches. Those launches do not
+write a separate server log file, but SSH-managed launches also persist the remote process's
+stdout/stderr at `~/.t3/ssh-launch/<state>/server.log`.
 
 ## Where To Find Things
 
 ### Logs
 
-Logs are human-facing only:
+Logs are human-facing:
 
 - destination: stdout
 - format: `Logger.consolePretty()`
-- persistence: none
+- normal local persistence: none
+- SSH-managed launch persistence: `~/.t3/ssh-launch/<state>/server.log`
 
 If you want a log message to show up in the trace file, emit it inside an active span with `Effect.log...`. `Logger.tracerLogger` will attach it as a span event.
 
 ### Traces
 
-Completed spans are written as NDJSON records to `serverTracePath` (by default, `~/.t3/userdata/logs/server.trace.ndjson`).
+Completed spans are written as NDJSON records to `serverTracePath`. The default depends on how the
+server starts: production and explicitly configured homes use
+`<home>/userdata/logs/server.trace.ndjson` (so `~/.t3/userdata/...` by default, or
+`/custom/path/userdata/...` with `--home-dir /custom/path`), a linked worktree dev run uses
+`<worktree>/.t3/userdata/logs/server.trace.ndjson`, and an implicit dev run outside a linked
+worktree uses `~/.t3/dev/logs/server.trace.ndjson`.
 
-Important fields in each record:
+Important fields common to both record types:
 
+- `type`: `effect-span` or `otlp-span`
 - `name`: span name
 - `traceId`, `spanId`, `parentSpanId`: correlation
 - `durationMs`: elapsed time
 - `attributes`: structured context
 - `events`: embedded logs and custom events
-- `exit`: `Success`, `Failure`, or `Interrupted`
 
-The schema lives in `apps/server/src/observability/TraceRecord.ts`.
+`effect-span` records also contain `exit` with `Success`, `Failure`, or `Interrupted`. `otlp-span`
+records instead carry OTLP resource, scope, and optional status fields.
+
+The `TraceRecord`, `EffectTraceRecord`, and `OtlpTraceRecord` schemas live in
+`packages/shared/src/observability.ts`.
 
 ### Metrics
 
@@ -165,30 +179,35 @@ The backend reads observability config at process start. If you change OTLP env
 
 The trace file is the fastest way to inspect raw span data.
 
-Resolve the production or explicitly configured trace file once. Runtime state lives under the
-base directory's `userdata` folder:
+Resolve the path for the launch mode once. Production and explicitly configured homes store runtime
+state under the base directory's `userdata` folder:
 
 ```bash
 TRACE_FILE="${T3CODE_HOME:-$HOME/.t3}/userdata/logs/server.trace.ndjson"
 ```
 
-Tail it:
+A dev server started from a linked worktree defaults to that worktree's local home:
 
 ```bash
-tail -f "$TRACE_FILE"
+TRACE_FILE="$WORKTREE/.t3/userdata/logs/server.trace.ndjson"
 ```
 
-For an implicit monorepo dev server, use:
+Only an implicit dev run outside a linked worktree uses the shared dev directory:
 
 ```bash
 TRACE_FILE="$HOME/.t3/dev/logs/server.trace.ndjson"
+```
+
+Tail the selected file:
+
+```bash
 tail -f "$TRACE_FILE"
 ```
 
 Show failed spans:
 
 ```bash
-jq -c 'select(.exit._tag != "Success") | {
+jq -c 'select(.type == "effect-span" and .exit._tag != "Success") | {
   name,
   durationMs,
   exit,
@@ -281,10 +300,12 @@ Recommended flow in Grafana:
 Good first searches:
 
 - service name such as `t3-local`, `t3-dev`, or `t3-desktop`
-- span names like `sql.execute`, `git.runCommand`, `provider.sendTurn`
+- span names like `sendTurn` or a Git operation such as `GitVcsDriver.statusDetails.status`
+- Git spans whose `git.operation` attribute identifies the operation
 - orchestration spans with attributes like `orchestration.command_type`
 
-Once you know traces are arriving, narrower TraceQL queries like `name = "sql.execute"` become useful.
+Once you know traces are arriving, narrower TraceQL queries for names such as `sendTurn` or Git
+operation names become useful.
 
 ### Use Metrics To See Systemic Problems
 
@@ -297,7 +318,6 @@ Good metric families to watch:
 - `t3_orchestration_command_ack_duration`
 - `t3_provider_turn_duration`
 - `t3_git_command_duration`
-- `t3_db_query_duration`
 
 Counters tell you volume and failure rate:
 
@@ -305,7 +325,6 @@ Counters tell you volume and failure rate:
 - `t3_orchestration_commands_total`
 - `t3_provider_turns_total`
 - `t3_git_commands_total`
-- `t3_db_queries_total`
 
 Use metrics when the question is:
 
@@ -339,7 +358,7 @@ If you need those later, add client-side instrumentation or a dedicated server f
 ### "Why did this request fail?"
 
 1. Start with the local NDJSON file.
-2. Find spans where `exit._tag != "Success"`.
+2. Find `effect-span` records where `exit._tag != "Success"`.
 3. Group by `traceId`.
 4. Inspect sibling spans and span events.
 5. If needed, move to Tempo for the full trace tree.
@@ -522,6 +541,8 @@ Current high-value span and metric boundaries include:
 
 ### Current Constraints
 
-- logs outside spans are not persisted
+- logs outside spans are not persisted in the trace file; SSH-managed launch stdout/stderr is still
+  captured in its launcher log
 - metrics are not snapshotted locally
-- the old `serverLogPath` still exists in config for compatibility, but the trace file is the persisted artifact that matters
+- the old `serverLogPath` still exists in config for compatibility, but the trace file is the primary
+  structured persisted artifact
diff --git a/docs/operations/relay-observability.md b/docs/operations/relay-observability.md
index dafad2155af..2bc697b2ef1 100644
--- a/docs/operations/relay-observability.md
+++ b/docs/operations/relay-observability.md
@@ -1,9 +1,14 @@
 # Relay observability
 
-The relay Alchemy stack owns a focused Axiom trace setup:
+> For maintainers. Using T3 Code? See [docs/user](../user/).
 
-- `t3-code-relay-traces-prod`, an OpenTelemetry trace dataset for Worker requests
-- `t3-code-relay-otel-ingest-prod`, a dataset-scoped ingest token bound to the Worker
+The relay Alchemy stack owns a shared Axiom trace setup:
+
+- `t3-code-relay-traces-prod`, the OpenTelemetry trace dataset shared by the Worker, mobile app, and
+  first-party relay clients
+- `t3-code-relay-otel-ingest-prod`, the dataset-scoped Worker ingest token
+- `t3-code-mobile-otel-ingest-prod`, the dataset-scoped mobile ingest token
+- `t3-code-relay-client-otel-ingest-prod`, the dataset-scoped first-party relay-client ingest token
 - `t3-code-relay-recent-spans-prod`, a view of recent request and endpoint spans
 
 Alchemy stages append their sanitized stage name to isolate resources, for example
@@ -15,8 +20,9 @@ Deploy from `infra/relay` with the normal Alchemy workflow:
 vp run deploy
 ```
 
-Alchemy resolves Axiom deployment credentials through its provider. At runtime, the Worker
-receives only the scoped ingest token; it does not receive the diagnostics query token.
+Alchemy resolves account-level Axiom deployment credentials through its provider. At runtime, the
+Worker receives only its scoped ingest token. Mobile and relay clients use their own separately
+provisioned scoped ingest tokens.
 
 The Worker emits Effect's built-in HTTP server spans plus endpoint and database child spans.
 Effect's OpenTelemetry exporter stores semantic HTTP attributes below the `attributes.` prefix.
@@ -25,18 +31,23 @@ For example:
 ```apl
 ['t3-code-relay-traces-prod']
 | where name startswith 'http.server'
+| extend endpoint = column_ifexists('attributes.http.route', ''),
+    customAttributes = column_ifexists('attributes.custom', dynamic({}))
 | project _time, name, trace_id, duration,
     ['attributes.http.request.method'],
     ['attributes.url.path'],
-    ['attributes.http.response.status_code']
+    ['attributes.http.response.status_code'],
+    endpoint,
+    relayOperation = customAttributes['relay']['operation']
 | order by _time desc
 | limit 200
 ```
 
-Endpoint failure annotations and other relay-specific attributes are also emitted in the
-`attributes.custom` map when present on a span, for example
-`['attributes.custom']['relay.endpoint']`.
+The provisioned view also reads the endpoint from `attributes.http.route`. Relay-specific span
+annotations are stored under `attributes.custom`; `relay.operation` is one of the emitted custom
+attributes.
 
 Agents should prefer the provisioned view or APL queries for completed incidents instead of
-tailing the Cloudflare Worker. Use the read-only query token when scripted access is needed;
-keep the ingest token reserved for the Worker.
+tailing the Cloudflare Worker. The stack does not provision a separate query token. Responders who
+need scripted query access use the authorized account-level `AXIOM_TOKEN` together with
+`AXIOM_ORG_ID`; scoped ingest tokens remain write-only credentials for their producers.
diff --git a/docs/operations/release.md b/docs/operations/release.md
index 9e908550054..9b33e94cc60 100644
--- a/docs/operations/release.md
+++ b/docs/operations/release.md
@@ -1,5 +1,7 @@
 # Release Checklist
 
+> For maintainers. Using T3 Code? See [docs/user](../user/).
+
 This document covers the unified release workflow for stable and nightly desktop releases.
 
 ## What the workflow does
@@ -30,6 +32,17 @@ This document covers the unified release workflow for stable and nightly desktop
   - nightly releases are aliased to the `nightly` hosted app channel
 - Signing is optional and auto-detected per platform from secrets.
 
+## Required release credentials
+
+The release workflow requires these GitHub Actions secrets in addition to the platform and deployment
+credentials documented below:
+
+- `RELEASE_APP_ID`
+- `RELEASE_APP_PRIVATE_KEY`
+
+The GitHub Release job uses them to mint the token that publishes release assets. Stable releases use
+them again in the finalize job, which can commit and push aligned package versions to `main`.
+
 ## T3 Connect relay deployment
 
 The relay is a shared control plane versioned separately from client releases. Stable and nightly
@@ -148,7 +161,8 @@ One-time Vercel dashboard setup:
   - manual `workflow_dispatch` with `channel=nightly`
 - Runs the same desktop quality gates and artifact matrix as the tagged release flow.
 - Publishes a GitHub prerelease only:
-  - tag format: `nightly-vX.Y.Z-nightly.YYYYMMDD.<run_number>`
+  - current tag format: `vX.Y.Z-nightly.YYYYMMDD.<run_number>`
+  - `nightly-v...` is accepted only as a legacy previous-nightly tag
   - release name includes the short commit SHA
   - `make_latest` is always `false`
 - Uses the next stable patch version as the nightly base. For example, `0.0.17` produces nightlies on `0.0.18-nightly.*`.
@@ -178,7 +192,9 @@ guidance when those environments are available.
 
 ## Desktop auto-update notes
 
-- Runtime updater: `electron-updater` in `apps/desktop/src/main.ts`.
+- Updater runtime: `apps/desktop/src/updates/DesktopUpdates.ts`.
+- `electron-updater` adapter: `apps/desktop/src/electron/ElectronUpdater.ts`.
+- `apps/desktop/src/main.ts` only wires the updater layers into the desktop runtime.
 - Update UX:
   - Background checks run on startup delay + interval.
   - No automatic download or install.
@@ -187,9 +203,6 @@ guidance when those environments are available.
 - Repository slug source:
   - `T3CODE_DESKTOP_UPDATE_REPOSITORY` (format `owner/repo`), if set.
   - otherwise `GITHUB_REPOSITORY` from GitHub Actions.
-- Temporary private-repo auth workaround:
-  - set `T3CODE_DESKTOP_UPDATE_GITHUB_TOKEN` (or `GH_TOKEN`) in the desktop app runtime environment.
-  - the app forwards it as an `Authorization: Bearer <token>` request header for updater HTTP calls.
 - Required release assets for updater:
   - platform installers (`.exe`, `.dmg`, `.AppImage`, plus macOS `.zip` for Squirrel.Mac update payloads)
   - channel metadata: `latest*.yml` for stable releases, `nightly*.yml` for nightly releases
@@ -200,8 +213,9 @@ guidance when those environments are available.
 
 ## 0) npm OIDC trusted publishing setup (CLI)
 
-The workflow publishes the CLI with `npm publish` from `apps/server` after bumping
-the package version to the release tag version.
+The workflow invokes `node apps/server/scripts/cli.ts publish` after aligning package versions. That
+script temporarily prepares the `t3` package, then runs `vp pm publish --filter t3 ...` from the
+repository root so workspace publish configuration is applied correctly.
 
 Checklist:
 
@@ -213,22 +227,27 @@ Checklist:
    - Environment (if used): match your npm trusted publishing config
 3. Ensure npm account and org policies allow trusted publishing for the package.
 4. Create release tag `vX.Y.Z` and push; workflow will:
-   - set `apps/server/package.json` version to `X.Y.Z`
+   - align the release package versions to `X.Y.Z`
    - build web + server
-   - run `npm publish --access public --tag latest`
-5. Nightly runs from the same workflow file publish with `npm publish --access public --tag nightly`.
+   - invoke the CLI publish script with npm dist-tag `latest`
+5. Nightly runs invoke the same publish script with npm dist-tag `nightly`.
+
+## 1) Release validation and unsigned builds
 
-## 1) Dry-run release without signing
+There is no dry-run tag path. Pushing any accepted non-nightly tag, including
+`v0.0.0-test.1`, classifies the run as the stable channel. It publishes `t3` with npm dist-tag
+`latest`, creates a real GitHub Release, aliases the hosted app to `latest.app.t3.codes` and
+`app.t3.codes`, and can commit a version bump to `main` in the finalize job. Do not push a test tag
+to validate the workflow.
 
-Use this first to validate the release pipeline.
+The workflow has no non-publishing `workflow_dispatch` mode. Use normal CI or local quality gates to
+validate checks and builds without shipping. To exercise the complete release graph at lower stable
+risk, manually dispatch `channel=nightly`; this still publishes a real nightly npm package, GitHub
+prerelease, desktop updater release, and hosted nightly alias, but it does not update stable aliases or
+commit a version bump to `main`. Only run it when a real nightly release is acceptable.
 
-1. Confirm no signing secrets are required for this test.
-2. Create a test tag:
-   - `git tag v0.0.0-test.1`
-   - `git push origin v0.0.0-test.1`
-3. Wait for `.github/workflows/release.yml` to finish.
-4. Verify the GitHub Release contains all platform artifacts.
-5. Download each artifact and sanity-check installation on each OS.
+Manual `channel=stable` with a version input is also a real stable-channel release. Omitting signing
+secrets only makes platform artifacts unsigned; it does not prevent publication.
 
 ## 2) Apple signing + notarization setup (macOS)
 
@@ -267,7 +286,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](../cloud/t3-connect-clerk.md#desktop-passkeys).
+10. Complete the Clerk Native API and AASA setup in [T3 Connect Clerk Setup](../internals/t3-connect.md#desktop-passkeys).
 11. Re-run a tag release and confirm macOS artifacts are signed/notarized and contain the expected
     `com.apple.developer.associated-domains` entitlement.
 
diff --git a/docs/project/todo.md b/docs/project/todo.md
deleted file mode 100644
index 3d856996d8d..00000000000
--- a/docs/project/todo.md
+++ /dev/null
@@ -1,13 +0,0 @@
-# TODO
-
-## Small things
-
-- [ ] Submitting new messages should scroll to bottom
-- [ ] Only show last 10 threads for a given project
-- [ ] Thread archiving
-- [ ] New projects should go on top
-- [ ] Projects should be sorted by latest thread update
-
-## Bigger things
-
-- [ ] Queueing messages
diff --git a/docs/reference/scripts.md b/docs/reference/scripts.md
deleted file mode 100644
index 3927adcfe29..00000000000
--- a/docs/reference/scripts.md
+++ /dev/null
@@ -1,56 +0,0 @@
-# Scripts
-
-- `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.
-- `vp run dev:server` — Starts just the WebSocket server. The server process runs on Bun (`@effect/platform-bun` + `BunPtyAdapter`), but task running uses `vp run`.
-- `vp run dev:web` — Starts just the Vite dev server for the web app.
-- 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.
-- Web dev commands do not auto-open a browser. Open the one-time pairing URL printed by the server so the first browser navigation is authenticated. Set `T3CODE_NO_BROWSER=0` only when interactive auto-open is intentional.
-- Pass dev-runner flags directly after the root task name, for example:
-  `vp run dev --home-dir /tmp/t3code-dev`
-- `vp run start` — Runs the production server (serves built web app as static files).
-- `vp run build` — Builds contracts, web app, and server.
-- `vp run typecheck` — Strict TypeScript checks for all packages.
-- `vp run test` — Runs workspace tests.
-- `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.
-- `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`.
-- `vp run dist:desktop:dmg:x64` — Builds an Intel macOS `.dmg`.
-- `vp run dist:desktop:linux` — Builds a Linux AppImage into `./release`.
-- `vp run dist:desktop:win` — Builds a Windows NSIS installer into `./release`.
-
-## 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.
-- Desktop production windows load the bundled UI from `t3code://app/index.html` (not a `127.0.0.1` document URL).
-
-- 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.
-
-Worktrees derive a preferred port offset from their path. The runner shifts both ports together when either is occupied or the web port is blocked by browsers, so treat the `[dev-runner]` output as authoritative.
-
-## Running multiple dev instances
-
-Set `T3CODE_DEV_INSTANCE` to any value to deterministically shift all dev ports together.
-
-- Default ports: server `13773`, web `5733`
-- Shifted ports: `base + offset` (offset is hashed from `T3CODE_DEV_INSTANCE`)
-- Example: `T3CODE_DEV_INSTANCE=branch-a vp run dev:desktop`
-
-If you want full control instead of hashing, set `T3CODE_PORT_OFFSET` to a numeric offset.
diff --git a/docs/reference/workspace-layout.md b/docs/reference/workspace-layout.md
deleted file mode 100644
index be88f2b603b..00000000000
--- a/docs/reference/workspace-layout.md
+++ /dev/null
@@ -1,7 +0,0 @@
-# Workspace layout
-
-- `/apps/server`: Node.js WebSocket server. Wraps Codex app-server, serves the built web app, and opens the browser on start.
-- `/apps/web`: React + Vite UI. Session control, conversation, and provider event rendering. Connects to the server via WebSocket.
-- `/apps/desktop`: Electron shell. Spawns a desktop-scoped `t3` backend process and loads the shared web app.
-- `/packages/contracts`: Shared effect/Schema schemas and TypeScript contracts for provider events, WebSocket protocol, and model/session types.
-- `/packages/shared`: Shared runtime utilities consumed by both server and web. Uses explicit subpath exports (e.g. `@t3tools/shared/git`, `@t3tools/shared/DrainableWorker`) — no barrel index.
diff --git a/docs/user/install.md b/docs/user/install.md
new file mode 100644
index 00000000000..fe0b418ca1e
--- /dev/null
+++ b/docs/user/install.md
@@ -0,0 +1,84 @@
+# Install T3 Code
+
+T3 Code is a web and desktop GUI for running coding agents on your machine.
+
+## Requirements
+
+Node.js `^22.16 || ^23.11 || >=24.10` on the machine that runs the T3 Code server.
+
+At least one provider CLI, installed and authenticated. See [Providers](#providers) below.
+
+## 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.
+
+## Desktop App
+
+Download the latest release from
+[GitHub Releases](https://github.com/pingdotgg/t3code/releases), or install from a package
+registry.
+
+Windows:
+
+```bash
+winget install T3Tools.T3Code
+```
+
+macOS:
+
+```bash
+brew install --cask t3-code
+```
+
+Arch Linux:
+
+```bash
+yay -S t3code-bin
+```
+
+## Providers
+
+T3 Code drives provider CLIs; it does not ship them. Install the CLI for each provider you want
+to use, then authenticate it.
+
+| 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` |
+
+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`.
+
+Run the login command on the machine running the T3 Code server, not on the device you browse
+from.
+
+### 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.
+
+### 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 in **Settings** and fails at session start with the login command
+to run.
+
+For multi-account setups, see [Codex](./providers-codex.md) and [Claude](./providers-claude.md).
+
+## 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
diff --git a/docs/user/keybindings.md b/docs/user/keybindings.md
index 0746272633f..95f487f45f3 100644
--- a/docs/user/keybindings.md
+++ b/docs/user/keybindings.md
@@ -1,10 +1,14 @@
 # Keybindings
 
-T3 Code reads keybindings from:
+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.
 
-- `~/.t3/keybindings.json`
+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.
 
-The file must be a JSON array of rules:
+The file is a JSON array of rules.
 
 ```json
 [
@@ -13,110 +17,59 @@ The file must be a JSON array of rules:
 ]
 ```
 
-See the full schema for more details: [`packages/contracts/src/keybindings.ts`](../../packages/contracts/src/keybindings.ts)
+Invalid rules are ignored. An invalid file is ignored entirely, and the server logs a warning.
 
-## Defaults
+## Rule Shape
 
-```json
-[
-  { "key": "mod+j", "command": "terminal.toggle" },
-  { "key": "mod+d", "command": "terminal.split", "when": "terminalFocus" },
-  { "key": "mod+n", "command": "terminal.new", "when": "terminalFocus" },
-  { "key": "mod+w", "command": "terminal.close", "when": "terminalFocus" },
-  { "key": "mod+shift+j", "command": "preview.toggle" },
-  { "key": "mod+r", "command": "preview.refresh", "when": "previewFocus" },
-  { "key": "mod+l", "command": "preview.focusUrl", "when": "previewFocus" },
-  { "key": "mod+=", "command": "preview.zoomIn", "when": "previewFocus" },
-  { "key": "mod+-", "command": "preview.zoomOut", "when": "previewFocus" },
-  { "key": "mod+0", "command": "preview.resetZoom", "when": "previewFocus" },
-  { "key": "mod+k", "command": "commandPalette.toggle", "when": "!terminalFocus" },
-  { "key": "mod+n", "command": "chat.new", "when": "!terminalFocus" },
-  { "key": "mod+shift+o", "command": "chat.new", "when": "!terminalFocus" },
-  { "key": "mod+shift+n", "command": "chat.newLocal", "when": "!terminalFocus" },
-  { "key": "mod+o", "command": "editor.openFavorite" }
-]
-```
-
-For most up to date defaults, see [`DEFAULT_KEYBINDINGS` in `apps/server/src/keybindings.ts`](../../apps/server/src/keybindings.ts)
+- `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
 
-## Configuration
+## Key Syntax
 
-### Rule Shape
+Modifiers: `mod` (`cmd` on macOS, `ctrl` elsewhere), `cmd` / `meta`, `ctrl` / `control`, `shift`,
+`alt` / `option`.
 
-Each entry supports:
+Examples: `mod+j`, `mod+shift+d`, `ctrl+l`, `cmd+k`.
 
-- `key` (required): shortcut string, like `mod+j`, `ctrl+k`, `cmd+shift+d`
-- `command` (required): action ID
-- `when` (optional): boolean expression controlling when the shortcut is active
+## Commands
 
-Invalid rules are ignored. Invalid config files are ignored. Warnings are logged by the server.
-
-### Available Commands
-
-- `terminal.toggle`: open/close terminal drawer
-- `terminal.split`: split terminal (in focused terminal context by default)
-- `terminal.new`: create new terminal (in focused terminal context by default)
-- `terminal.close`: close/kill the focused terminal (in focused terminal context by default)
-- `preview.toggle`: open/close the in-app browser preview panel (desktop app only)
-- `preview.refresh`: reload the active preview tab (in focused preview context by default)
-- `preview.focusUrl`: focus the URL input of the preview panel (in focused preview context by default)
-- `preview.zoomIn`: zoom the preview viewport in one step (in focused preview context by default)
-- `preview.zoomOut`: zoom the preview viewport out one step (in focused preview context by default)
-- `preview.resetZoom`: reset the preview zoom to 100% (in focused preview context by default)
-- `commandPalette.toggle`: open or close the global command palette
-- `chat.new`: create a new chat thread preserving the active thread's branch/worktree state
-- `chat.newLocal`: create a new chat thread for the active project in a new environment (local/worktree determined by app settings (default `local`))
-- `editor.openFavorite`: open current project/worktree in the last-used editor
-- `script.{id}.run`: run a project script by id (for example `script.test.run`)
+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`.
 
 The command palette searches active thread titles, projects, branches, user messages, and final
 agent responses across connected environments. Message matches show one labeled excerpt while
 keeping the thread's project, branch, and machine context visible. Message search begins after two
 characters and uses SQLite's ASCII case-insensitive matching.
 
-### Key Syntax
-
-Supported modifiers:
-
-- `mod` (`cmd` on macOS, `ctrl` on non-macOS)
-- `cmd` / `meta`
-- `ctrl` / `control`
-- `shift`
-- `alt` / `option`
-
-Examples:
-
-- `mod+j`
-- `mod+shift+d`
-- `ctrl+l`
-- `cmd+k`
+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.
 
-### `when` Conditions
+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.
 
-Currently available context keys:
+## `when` Conditions
 
-- `terminalFocus`
-- `terminalOpen`
-- `previewFocus`
-- `previewOpen`
+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`.
 
-Supported operators:
-
-- `!` (not)
-- `&&` (and)
-- `||` (or)
-- parentheses: `(` `)`
+Operators: `!` (not), `&&` (and), `||` (or), and parentheses.
 
 Examples:
 
 - `"when": "terminalFocus"`
 - `"when": "terminalOpen && !terminalFocus"`
-- `"when": "terminalFocus || terminalOpen"`
-
-Unknown condition keys evaluate to `false`.
+- `"when": "!terminalFocus"`
 
-### Precedence
+## Precedence
 
 - Rules are evaluated in array order.
 - For a key event, the last rule where both `key` matches and `when` evaluates to `true` wins.
-- That means precedence is across commands, not only within the same command.
+- 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.
diff --git a/docs/user/permission-modes.md b/docs/user/permission-modes.md
new file mode 100644
index 00000000000..cb69e45b5d7
--- /dev/null
+++ b/docs/user/permission-modes.md
@@ -0,0 +1,48 @@
+# Permission Modes
+
+A permission mode controls how much the agent does on its own and when it stops to ask you.
+
+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.
+
+## The Modes
+
+**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.
+
+**Auto-accept edits**: auto-approve edits, ask before other actions. File changes go through
+without prompting; commands and anything else still stop for approval.
+
+**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, and providers without an equivalent (such as OpenCode) 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.
+
+## 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. The
+labels above describe what you get; the exact per-provider translation is internal and may
+change.
+
+Mobile offers the same four modes. It labels the first one **Approve actions** rather than
+**Supervised**.
diff --git a/docs/providers/claude.md b/docs/user/providers-claude.md
similarity index 72%
rename from docs/providers/claude.md
rename to docs/user/providers-claude.md
index bbf72722cf1..79f1211cf40 100644
--- a/docs/providers/claude.md
+++ b/docs/user/providers-claude.md
@@ -1,6 +1,7 @@
 # Claude
 
-This guide is for people who want to use more than one Claude setup in T3 Code.
+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).
 
 Common reasons:
 
@@ -24,20 +25,24 @@ In T3 Code Settings, your Claude provider can stay like this:
 ```text
 Display name: Claude
 Binary path: claude
-Claude HOME path: empty
+CLAUDE_CONFIG_DIR path: empty
 ```
 
-An empty `Claude HOME path` means T3 Code uses your normal home directory.
+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.
 
 ## I Want Work And Personal Claude Accounts
 
-Use a different Claude home for each account.
+Use a different Claude config directory for each account.
 
 Example:
 
 ```text
-default home                 work account
-~/.claude_personal_home       personal account
+default config dir           work account
+~/.claude_personal_home      personal account
 ```
 
 ### Set Up The First Account
@@ -53,24 +58,27 @@ In T3 Code Settings:
 ```text
 Display name: Claude Work
 Binary path: claude
-Claude HOME path: empty
+CLAUDE_CONFIG_DIR path: empty
 ```
 
 ### Set Up The Second Account
 
-Log in with a separate home:
+Log in with a separate config directory:
 
 ```bash
 mkdir -p ~/.claude_personal_home
-HOME=~/.claude_personal_home claude auth login
+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 HOME path: ~/.claude_personal_home
+CLAUDE_CONFIG_DIR path: ~/.claude_personal_home
 ```
 
 Use the email shown in Settings to confirm each provider is using the intended account. Emails are
@@ -80,12 +88,12 @@ blurred by default; click the blurred email to reveal it.
 
 Usually, no.
 
-T3 Code only offers Claude providers that use the same Claude home for an existing thread. A
-different Claude home is treated as a different Claude environment.
+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 home directory, so T3 Code keeps separate Claude homes isolated instead of
-trying to share part of the state.
+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
 
@@ -102,7 +110,7 @@ Add or edit a Claude provider in T3 Code Settings:
 ```text
 Display name: Claude OpenRouter
 Binary path: claude
-Claude HOME path: ~/.claude_openrouter_home
+CLAUDE_CONFIG_DIR path: ~/.claude_openrouter_home
 ```
 
 In that provider's Environment variables section, add:
@@ -173,40 +181,18 @@ Claude Code Router is useful when you want a local routing layer with more contr
 OpenRouter setup.
 
 T3 Code does not need a special Claude Code Router provider. Treat the router as a Claude
-environment.
-
-Use this when you want Claude Code Router to decide which upstream model or provider handles Claude
-requests.
-
-High-level flow:
-
-1. Start Claude Code Router.
-2. Add or configure a Claude provider in T3 Code.
-3. Put the router's required variables on that provider instance.
-
-Configure a Claude provider:
+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 HOME path: ~/.claude_router_home
-```
-
-Then copy the variables that `ccr activate` would export into the provider's Environment variables
-section. Mark tokens and API keys as sensitive.
-
-If you want the router-backed setup to stay separate from your normal Claude account, create and log
-in with a dedicated home first:
-
-```bash
-mkdir -p ~/.claude_router_home
-ccr start
-ccr activate
-HOME=~/.claude_router_home claude auth login
+CLAUDE_CONFIG_DIR path: ~/.claude_router_home
 ```
 
-Claude Code Router's setup can change over time. Use its upstream README for the current install and
-configuration steps: <https://github.com/musistudio/claude-code-router>.
+Follow the upstream project's README for the router's own install, startup, and configuration
+steps: <https://github.com/musistudio/claude-code-router>.
 
 ## I Want Different Claude Settings, Not A Different Account
 
@@ -218,7 +204,7 @@ Examples:
 - "Claude Router"
 - "Claude Experimental"
 
-If the preset needs different Claude files, give it a different `Claude HOME path`. If it needs
+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.
 
 Do not put environment variable assignments in `Launch arguments`.
diff --git a/docs/providers/codex.md b/docs/user/providers-codex.md
similarity index 96%
rename from docs/providers/codex.md
rename to docs/user/providers-codex.md
index cc9e84e484a..7c5ea91f043 100644
--- a/docs/providers/codex.md
+++ b/docs/user/providers-codex.md
@@ -1,6 +1,7 @@
 # Codex
 
-This guide is for people who want to use more than one Codex account in T3 Code.
+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).
 
 Common reasons:
 
diff --git a/docs/user/remote-access.md b/docs/user/remote-access.md
index d6ff00bee1f..3881c5be3a4 100644
--- a/docs/user/remote-access.md
+++ b/docs/user/remote-access.md
@@ -14,14 +14,15 @@ That gives you:
 
 ## Enabling Network Access
 
-There are two ways to expose your server for remote connections: from the desktop app or from the CLI.
+There are three ways to reach your server from another device: expose the desktop app's backend,
+run a headless server from the CLI, or have the desktop app launch T3 Code over SSH.
 
 ### Option 1: Desktop App
 
 If you are already running the desktop app and want to make it reachable from other devices:
 
 1. Open **Settings** → **Connections**.
-2. Under **Manage Local Backend**, toggle **Network access** on. This will restart the app and run the backend on all network interfaces.
+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.
 
@@ -48,10 +49,10 @@ Depending on your Tailscale setup, this may include:
 - an HTTPS MagicDNS endpoint when Tailscale Serve is configured for this backend
 
 The Tailscale HTTPS endpoint uses the clean MagicDNS URL, such as
-`https://machine.tailnet.ts.net/`, and is disabled until the app verifies that the URL reaches this
-backend. Use **Setup** on the Tailscale HTTPS row to opt in. The desktop app restarts the backend
-with the same server-side behavior as `t3 serve --tailscale-serve`, then the server asks Tailscale
-Serve to proxy HTTPS traffic to the local backend.
+`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.
 
@@ -96,10 +97,8 @@ By default this configures Tailscale Serve on HTTPS port 443 and advertises
 npx t3 serve --tailscale-serve --tailscale-serve-port 8443
 ```
 
-> Note
-> The GUIs do not currently support adding projects on remote environments.
-> For now, use `t3 project ...` on the server machine instead.
-> Full GUI support for remote project management is coming soon.
+Once paired, add projects normally: open the Command Palette and choose **Add Project**, then pick
+the environment the project lives on. Every saved environment is offered, not only the local one.
 
 ### Option 3: Desktop-Managed SSH Launch
 
@@ -125,16 +124,10 @@ The remote host must have a compatible Node.js runtime. T3 Code uses the server
 ^22.16 || ^23.11 || >=24.10
 ```
 
-During SSH launch, T3 Code first checks whether `node` is already available on `PATH`. If it is missing, the launcher tries common non-interactive shell locations and version-manager shims/activation hooks:
-
-- `~/.local/bin`, `~/bin`, `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, `/bin`
-- Volta via `~/.volta/bin`
-- asdf via `~/.asdf/shims`, `~/.asdf/bin`, or `~/.asdf/asdf.sh`
-- mise via `~/.local/share/mise/shims`, `~/.mise/shims`, or `mise activate sh`
-- fnm via `fnm env --use-on-cd --shell sh` or `fnm env --shell sh`
-- nodenv via `~/.nodenv/bin`, `~/.nodenv/shims`, or `nodenv init -`
-- nvm via `$NVM_DIR/nvm.sh`, then `nvm use default`, `nvm use node`, or `nvm use --lts`
-- installed nvm versions under `$NVM_DIR/versions/node/*/bin`
+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:
 
@@ -148,7 +141,7 @@ If that does not print a compatible Node version, configure your version manager
 nvm alias default 24
 ```
 
-With mise/asdf/fnm/nodenv, make sure the tool's shim directory is installed and points at a Node version satisfying the range above.
+With mise, asdf, fnm, or nodenv, make sure the tool's shim directory is installed and resolves to a Node version satisfying the range above without an interactive shell.
 
 If reconnecting after an app update fails, retry the SSH launch once. The launcher now compares its generated runner script, stops stale launcher-managed remote servers, clears the SSH launch PID/port state, and starts a fresh remote server. You should not normally need to delete `~/.t3/ssh-launch` or kill `t3` processes manually.
 
@@ -160,7 +153,7 @@ be able to update and reconnect the server for you, or it may ask you to update
 run a copied command on the server machine.
 
 Finish active work before updating because the server restarts briefly. For step-by-step guidance,
-see [Keeping T3 Code in Sync](./server-updates.md).
+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).
diff --git a/docs/integrations/source-control-providers.md b/docs/user/source-control.md
similarity index 74%
rename from docs/integrations/source-control-providers.md
rename to docs/user/source-control.md
index c496d5516a6..6d81d2b33ab 100644
--- a/docs/integrations/source-control-providers.md
+++ b/docs/user/source-control.md
@@ -1,6 +1,6 @@
 # Source Control Integrations
 
-T3 Code connects directly to your Git hosting provider so you can create pull requests, review code, and manage repositories without leaving your editor. Work stays in flow—no more jumping between browser tabs and terminal windows.
+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
 
@@ -24,16 +24,16 @@ T3 Code works with the platforms your team already uses:
 **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—all in one flow
-- Perfect for turning a weekend prototype into a real project
+- 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 panel
+- 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
-- Supports GitHub Pull Requests, GitLab Merge Requests, and Bitbucket Pull Requests
+- Supports GitHub Pull Requests, GitLab Merge Requests, Bitbucket Pull Requests, and Azure DevOps Pull Requests
 
 **Stay on top of open reviews**
 
@@ -65,7 +65,7 @@ Run a quick **Rescan** after setting up a new machine or changing credentials.
    ```
 3. Open **Settings → Source Control** in T3 Code and verify GitHub shows as authenticated
 
-That's it—you can now clone, publish, and create pull requests.
+You can now clone, publish, and create pull requests.
 
 ### For GitLab
 
@@ -81,15 +81,25 @@ That's it—you can now clone, publish, and create pull requests.
 
 ### For Bitbucket
 
-Bitbucket uses API tokens instead of a CLI tool:
+Bitbucket uses tokens instead of a CLI tool. Two options, both set as environment variables on the
+machine running T3 Code.
 
-1. Create an API token in your Atlassian account with read/write access to pull requests and repositories
-2. Add these environment variables to the environment running T3 Code:
-   ```bash
-   export T3CODE_BITBUCKET_EMAIL="you@example.com"
-   export T3CODE_BITBUCKET_API_TOKEN="your-token"
-   ```
-3. Restart T3 Code and verify the connection in **Source Control settings**
+Recommended, a Bitbucket access token:
+
+```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:
+
+```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**.
 
 ### For Azure DevOps
 
@@ -124,4 +134,4 @@ Bitbucket uses API tokens instead of a CLI tool:
 
 - [GitHub CLI](https://cli.github.com/)
 - [GitLab CLI](https://gitlab.com/gitlab-org/cli)
-- [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/)
+- [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/)
diff --git a/docs/user/server-updates.md b/docs/user/updating.md
similarity index 84%
rename from docs/user/server-updates.md
rename to docs/user/updating.md
index 27577c6f948..8e1fac81854 100644
--- a/docs/user/server-updates.md
+++ b/docs/user/updating.md
@@ -36,12 +36,20 @@ After selecting **Update server**, the warning becomes a three-step progress rai
 Connections, so navigating between them does not lose the update. A failed step remains visible
 with its error and an option to retry.
 
-If the server uses the T3 Code background service, you can also update it directly on the host:
+**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:
 
 ```sh
-npx t3@latest service update
+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.
 
diff --git a/infra/relay/README.md b/infra/relay/README.md
index 114d5e9b07f..0085c9c5b6b 100644
--- a/infra/relay/README.md
+++ b/infra/relay/README.md
@@ -1,7 +1,7 @@
 # T3 Connect Relay
 
-> [!WARNING]
-> T3 Connect is currently in private beta. Join the waitlist in the app under Settings > T3 Connect.
+> [!NOTE]
+> Sign in to T3 Connect from the app under Settings > Connections.
 
 The relay is the hosted control plane for T3 Connect. It helps clients discover and connect to
 remote environments, manages the cloud-side records needed for those connections, and delivers
@@ -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/cloud/t3-code-connect-auth-flow.html) for the larger system
+See the [T3 Connect architecture overview](../../docs/internals/t3-code-connect-auth-flow.html) for the larger system
 design.
 
 ## Responsibilities
@@ -25,7 +25,7 @@ The relay currently owns:
 - Persisting relay state and exposing relay-specific traces for diagnostics.
 
 The environment server and relay have separate credentials and trust boundaries. Read
-[Environment Authentication Profile](../../docs/environment-auth.md) before changing token,
+[Environment Authentication Profile](../../docs/internals/environment-auth.md) before changing token,
 credential, or authorization behavior.
 
 ## Code Map
@@ -159,8 +159,8 @@ and hosted web builds.
 
 See:
 
-- [T3 Connect Clerk Setup](../../docs/cloud/t3-connect-clerk.md) for Clerk keys, JWT templates, and waitlist
+- [T3 Connect Clerk Setup](../../docs/internals/t3-connect.md) for Clerk keys, JWT templates, and sign-up restrictions
   setup.
-- [Relay Observability](../../docs/relay-observability.md) for deployment tracing and diagnostics.
-- [T3 Connect Architecture Overview](../../docs/cloud/t3-code-connect-auth-flow.html) for the full link,
+- [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.

From e0513d29839f934df1d5a13551e6ccd76d11006b Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Thu, 30 Jul 2026 07:30:24 -0700
Subject: [PATCH 23/34] fix(web): server updates no longer look like warnings
 (#4992)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---
 apps/web/src/components/ChatView.tsx          | 115 ++++++++++++------
 .../components/ServerUpdateAction.test.tsx    |  13 +-
 .../web/src/components/ServerUpdateAction.tsx |  96 +++++++--------
 .../components/chat/ComposerBannerStack.tsx   |   2 +-
 .../settings/ConnectionsSettings.tsx          |   2 -
 5 files changed, 126 insertions(+), 102 deletions(-)

diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index ec85e4c4c18..7aaae278908 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -1883,46 +1883,75 @@ function ChatViewContent(props: ChatViewProps) {
   );
   const systemComposerBannerItems = useMemo<ComposerBannerStackItem[]>(() => {
     const items: ComposerBannerStackItem[] = [];
-    const resumingServerUpdate =
-      serverUpdateState.status === "running" && serverUpdateState.stage === "resuming";
-    if (activeEnvironmentUnavailableState && !resumingServerUpdate) {
-      const connection = activeEnvironmentUnavailableState.connection;
-      const isReconnecting =
-        connection.phase === "connecting" || connection.phase === "reconnecting";
-      items.push({
-        id: `environment-unavailable:${activeEnvironmentUnavailableState.environmentId}`,
-        variant: connection.phase === "error" ? "error" : "warning",
-        icon: <WifiOffIcon />,
-        title: `${activeEnvironmentUnavailableState.label}: ${connectionStatusTitle(connection)}`,
-        description:
-          connection.error ??
-          "Reconnect this environment before sending messages or running actions.",
-        actions: (
-          <>
-            <Button
-              size="xs"
-              disabled={isReconnecting}
-              onClick={() =>
-                void handleReconnectActiveEnvironment(
-                  activeEnvironmentUnavailableState.environmentId,
-                )
-              }
-            >
-              {isReconnecting ? "Reconnecting..." : "Reconnect"}
-            </Button>
-            <Button
-              size="xs"
-              variant="outline"
-              onClick={() => void navigate({ to: "/settings/connections" })}
-            >
-              Connections
-            </Button>
-          </>
-        ),
-      });
+    const updateRunning = serverUpdateState.status === "running";
+    const unavailableConnection = activeEnvironmentUnavailableState?.connection ?? null;
+    const environmentReconnecting =
+      unavailableConnection !== null &&
+      (unavailableConnection.phase === "connecting" ||
+        unavailableConnection.phase === "reconnecting");
+    // Reconnecting to a version-skewed server with no update in flight
+    // usually means the server is restarting mid-update and a refresh wiped
+    // the in-memory update state. Fold the reconnect and version banners
+    // into one calm line instead of stacking "Failed to connect" on
+    // "versions differ". A failed update never folds: its error and retry
+    // action must stay visible.
+    const reconnectingThroughVersionSkew =
+      serverUpdateState.status === "idle" && environmentReconnecting && versionMismatch !== null;
+    // While an update runs, transient connect blips are expected (the server
+    // restarts) and the update banner already shows progress. Hard failure
+    // phases still surface so the Reconnect action stays reachable.
+    const suppressUnavailableBanner = updateRunning && environmentReconnecting;
+    if (activeEnvironmentUnavailableState && unavailableConnection && !suppressUnavailableBanner) {
+      if (reconnectingThroughVersionSkew) {
+        items.push({
+          id: `environment-unavailable:${activeEnvironmentUnavailableState.environmentId}`,
+          variant: "default",
+          icon: (
+            <span
+              className="size-1.5 animate-status-pulse rounded-full bg-foreground"
+              aria-hidden="true"
+            />
+          ),
+          title: `${unavailableConnection.phase === "connecting" ? "Connecting" : "Reconnecting"} to ${activeEnvironmentUnavailableState.label}`,
+          description: "It may be finishing an update. One moment.",
+        });
+      } else {
+        items.push({
+          id: `environment-unavailable:${activeEnvironmentUnavailableState.environmentId}`,
+          variant: unavailableConnection.phase === "error" ? "error" : "warning",
+          icon: <WifiOffIcon />,
+          title: `${activeEnvironmentUnavailableState.label}: ${connectionStatusTitle(unavailableConnection)}`,
+          description:
+            unavailableConnection.error ??
+            "Reconnect this environment before sending messages or running actions.",
+          actions: (
+            <>
+              <Button
+                size="xs"
+                disabled={environmentReconnecting}
+                onClick={() =>
+                  void handleReconnectActiveEnvironment(
+                    activeEnvironmentUnavailableState.environmentId,
+                  )
+                }
+              >
+                {environmentReconnecting ? "Reconnecting..." : "Reconnect"}
+              </Button>
+              <Button
+                size="xs"
+                variant="outline"
+                onClick={() => void navigate({ to: "/settings/connections" })}
+              >
+                Connections
+              </Button>
+            </>
+          ),
+        });
+      }
     }
     if (
       serverUpdateEnvironmentId &&
+      !reconnectingThroughVersionSkew &&
       (serverUpdateState.status !== "idle" ||
         (showVersionMismatchBanner && versionMismatch && versionMismatchDismissKey))
     ) {
@@ -1930,8 +1959,15 @@ function ChatViewContent(props: ChatViewProps) {
       const updateFailed = serverUpdateState.status === "failed";
       items.push({
         id: `server-version:${serverUpdateEnvironmentId}`,
-        variant: updateFailed ? "error" : "warning",
-        icon: <TriangleAlertIcon />,
+        variant: updateFailed ? "error" : updateInProgress ? "default" : "warning",
+        icon: updateInProgress ? (
+          <span
+            className="size-1.5 animate-status-pulse rounded-full bg-foreground"
+            aria-hidden="true"
+          />
+        ) : (
+          <TriangleAlertIcon />
+        ),
         title:
           updateInProgress || updateFailed
             ? `${updateFailed ? "Could not update" : "Updating"} ${versionMismatchServerLabel}`
@@ -1940,7 +1976,6 @@ function ChatViewContent(props: ChatViewProps) {
           updateInProgress || updateFailed ? (
             <ServerUpdateProgress
               fromVersion={serverUpdateState.fromVersion}
-              serverLabel={versionMismatchServerLabel}
               state={serverUpdateState}
             />
           ) : versionMismatch ? (
diff --git a/apps/web/src/components/ServerUpdateAction.test.tsx b/apps/web/src/components/ServerUpdateAction.test.tsx
index 17e44b8bae6..4d5669a0a8f 100644
--- a/apps/web/src/components/ServerUpdateAction.test.tsx
+++ b/apps/web/src/components/ServerUpdateAction.test.tsx
@@ -101,11 +101,10 @@ describe("ServerUpdateAction", () => {
 });
 
 describe("ServerUpdateProgress", () => {
-  it("renders the chosen horizontal step rail without an animated spinner", () => {
+  it("renders the monochrome step rail with only the active step highlighted", () => {
     const markup = renderToStaticMarkup(
       <ServerUpdateProgress
         fromVersion="0.0.30"
-        serverLabel="bb-1"
         state={{
           status: "running",
           stage: "resuming",
@@ -119,8 +118,12 @@ describe("ServerUpdateProgress", () => {
     expect(markup).toContain("0.0.31");
     expect(markup).toContain("Download");
     expect(markup).toContain("Install");
-    expect(markup).toContain("Resume");
-    expect(markup).toContain("Waiting for bb-1 to accept commands.");
+    expect(markup).toContain("Resuming");
+    // The wait state is monochrome and calm: no success/warning colors, no
+    // status sentence, one duty-cycled pulse on the active step.
+    expect(markup).not.toContain("text-success");
+    expect(markup).not.toContain("text-primary");
+    expect(markup).toContain("animate-status-pulse");
     expect(markup).not.toContain("animate-spin");
   });
 
@@ -128,7 +131,6 @@ describe("ServerUpdateProgress", () => {
     const markup = renderToStaticMarkup(
       <ServerUpdateProgress
         fromVersion="0.0.30"
-        serverLabel="bb-1"
         state={{
           status: "failed",
           stage: "installing",
@@ -141,5 +143,6 @@ describe("ServerUpdateProgress", () => {
 
     expect(markup).toContain('role="alert"');
     expect(markup).toContain("The package could not be verified.");
+    expect(markup).not.toContain("animate-status-pulse");
   });
 });
diff --git a/apps/web/src/components/ServerUpdateAction.tsx b/apps/web/src/components/ServerUpdateAction.tsx
index 929ea2e56c7..f3b6c694fae 100644
--- a/apps/web/src/components/ServerUpdateAction.tsx
+++ b/apps/web/src/components/ServerUpdateAction.tsx
@@ -15,9 +15,9 @@ import { Button } from "./ui/button";
 import { toastManager } from "./ui/toast";
 
 const UPDATE_STEPS = [
-  { stage: "downloading", label: "Download" },
-  { stage: "installing", label: "Install" },
-  { stage: "resuming", label: "Resume" },
+  { stage: "downloading", label: "Download", activeLabel: "Downloading" },
+  { stage: "installing", label: "Install", activeLabel: "Installing" },
+  { stage: "resuming", label: "Resume", activeLabel: "Resuming" },
 ] as const;
 const pendingUpdateEnvironmentIds = new Set<EnvironmentId>();
 
@@ -25,37 +25,24 @@ function updateFailureMessage(error: unknown): string {
   return error instanceof Error ? error.message : "Server update failed.";
 }
 
-function updateStatusCopy(
-  state: Exclude<ServerUpdateState, { status: "idle" }>,
-  serverLabel: string,
-): string {
-  if (state.status === "failed") {
-    return state.message;
-  }
-  switch (state.stage) {
-    case "downloading":
-      return "Downloading the matching server version.";
-    case "installing":
-      return `Installing and verifying t3@${state.targetVersion}.`;
-    case "resuming":
-      return `Waiting for ${serverLabel} to accept commands.`;
-  }
-}
-
+/**
+ * Monochrome step rail for an in-flight server update. The update is a
+ * wait, not a warning: done steps recede to gray, the active step is the
+ * only bright element and pulses. Failure keeps the rail but surfaces the
+ * error below it.
+ */
 export function ServerUpdateProgress({
   fromVersion,
-  serverLabel,
   state,
 }: {
   readonly fromVersion: string;
-  readonly serverLabel: string;
   readonly state: Exclude<ServerUpdateState, { status: "idle" }>;
 }) {
   const currentIndex = UPDATE_STEPS.findIndex(({ stage }) => stage === state.stage);
 
   return (
     <div className="mt-1 min-w-0 space-y-2.5">
-      <p className="text-xs text-muted-foreground">
+      <p className="text-xs text-muted-foreground/70">
         {fromVersion} <span aria-hidden="true">→</span> {state.targetVersion}
       </p>
       <ol className="flex min-w-0 items-center" aria-label="Server update progress">
@@ -63,6 +50,7 @@ export function ServerUpdateProgress({
           const complete = index < currentIndex;
           const current = index === currentIndex;
           const failed = current && state.status === "failed";
+          const running = current && state.status === "running";
           return (
             <li
               key={step.stage}
@@ -70,36 +58,40 @@ export function ServerUpdateProgress({
                 "flex min-w-0 items-center text-xs font-medium",
                 index < UPDATE_STEPS.length - 1 ? "flex-1" : null,
                 complete
-                  ? "text-success"
+                  ? "text-muted-foreground"
                   : failed
                     ? "text-destructive"
-                    : current
-                      ? "text-primary"
-                      : "text-muted-foreground/60",
+                    : running
+                      ? "animate-status-pulse text-foreground"
+                      : "text-muted-foreground/50",
               )}
-              aria-current={current && state.status === "running" ? "step" : undefined}
+              aria-current={running ? "step" : undefined}
             >
-              <span
-                className={cn(
-                  "grid size-4 shrink-0 place-items-center rounded-full border",
-                  complete
-                    ? "border-success bg-success text-success-foreground"
-                    : failed
-                      ? "border-destructive bg-destructive text-destructive-foreground"
-                      : current
-                        ? "border-primary bg-primary text-primary-foreground"
-                        : "border-muted-foreground/35",
-                )}
-                aria-hidden="true"
-              >
-                {complete ? <CheckIcon className="size-3" strokeWidth={3} /> : null}
-              </span>
-              <span className="ml-1.5 truncate">{step.label}</span>
+              {complete ? (
+                <CheckIcon
+                  className="size-3.5 shrink-0 opacity-70"
+                  strokeWidth={2.5}
+                  aria-hidden="true"
+                />
+              ) : (
+                <span
+                  className={cn(
+                    "size-1.5 shrink-0 rounded-full",
+                    failed
+                      ? "bg-destructive"
+                      : running
+                        ? "bg-foreground"
+                        : "border border-muted-foreground/40",
+                  )}
+                  aria-hidden="true"
+                />
+              )}
+              <span className="ml-1.5 truncate">{running ? step.activeLabel : step.label}</span>
               {index < UPDATE_STEPS.length - 1 ? (
                 <span
                   className={cn(
                     "mx-2 h-px min-w-3 flex-1",
-                    complete ? "bg-success/60" : "bg-border",
+                    complete ? "bg-muted-foreground/40" : "bg-border",
                   )}
                   aria-hidden="true"
                 />
@@ -108,15 +100,11 @@ export function ServerUpdateProgress({
           );
         })}
       </ol>
-      <p
-        className={cn(
-          "text-xs",
-          state.status === "failed" ? "text-destructive" : "text-muted-foreground",
-        )}
-        role={state.status === "failed" ? "alert" : "status"}
-      >
-        {updateStatusCopy(state, serverLabel)}
-      </p>
+      {state.status === "failed" ? (
+        <p className="text-xs text-destructive" role="alert">
+          {state.message}
+        </p>
+      ) : null}
     </div>
   );
 }
diff --git a/apps/web/src/components/chat/ComposerBannerStack.tsx b/apps/web/src/components/chat/ComposerBannerStack.tsx
index 699c9cfd9c4..548bd0f4262 100644
--- a/apps/web/src/components/chat/ComposerBannerStack.tsx
+++ b/apps/web/src/components/chat/ComposerBannerStack.tsx
@@ -24,7 +24,7 @@ const exitTransitionStyle = {
 
 export interface ComposerBannerStackItem {
   readonly id: string;
-  readonly variant: "error" | "info" | "success" | "warning";
+  readonly variant: "default" | "error" | "info" | "success" | "warning";
   readonly icon: ReactNode;
   readonly title: ReactNode;
   readonly description?: ReactNode;
diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index 98ab7a128de..ae9f061b01a 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -1434,7 +1434,6 @@ function SavedBackendListRow({
             <div className="max-w-md">
               <ServerUpdateProgress
                 fromVersion={serverUpdateState.fromVersion}
-                serverLabel={`${environment.label} server`}
                 state={serverUpdateState}
               />
             </div>
@@ -3011,7 +3010,6 @@ export function ConnectionsSettings() {
                   primaryServerUpdateState.status !== "idle" ? (
                     <ServerUpdateProgress
                       fromVersion={primaryServerUpdateState.fromVersion}
-                      serverLabel={primaryEnvironment?.label ?? "this server"}
                       state={primaryServerUpdateState}
                     />
                   ) : primaryVersionMismatch ? (

From 1877237c7ae99ecf2163b4c5bb7d3e14bebcca4d Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Thu, 30 Jul 2026 07:31:53 -0700
Subject: [PATCH 24/34] fix(connect): reboots no longer strand the relay link,
 403s now say why (#4988)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---
 .../src/features/cloud/linkEnvironment.ts     |  9 +++++++-
 apps/server/src/server.ts                     | 22 ++++++++++++++++++-
 apps/web/src/cloud/linkEnvironment.ts         |  9 +++++++-
 .../src/environments/EnvironmentConnector.ts  | 18 +++------------
 infra/relay/src/http/Api.ts                   |  6 +++--
 packages/contracts/src/relay.ts               | 20 ++++++++++++++++-
 6 files changed, 63 insertions(+), 21 deletions(-)

diff --git a/apps/mobile/src/features/cloud/linkEnvironment.ts b/apps/mobile/src/features/cloud/linkEnvironment.ts
index 5d619c688f1..958827ee492 100644
--- a/apps/mobile/src/features/cloud/linkEnvironment.ts
+++ b/apps/mobile/src/features/cloud/linkEnvironment.ts
@@ -134,7 +134,14 @@ function relayProtectedErrorMessage(error: RelayProtectedErrorType): string {
     case "RelayEnvironmentLinkProofInvalidError":
       return `Relay rejected the environment link proof (${error.reason}).`;
     case "RelayEnvironmentConnectNotAuthorizedError":
-      return "Relay rejected the environment connection request.";
+      // "Not authorized" covers non-auth causes too; surface the reason so a
+      // missing link doesn't read as a credential problem.
+      if (error.reason === "environment_link_not_found") {
+        return "Relay has no active link for this environment. The environment server may not have re-established its link yet.";
+      }
+      return error.reason
+        ? `Relay rejected the environment connection request (${error.reason}).`
+        : "Relay rejected the environment connection request.";
     case "RelayEnvironmentEndpointUnavailableError":
       return `Relay could not reach the environment endpoint (${error.reason}).`;
     case "RelayEnvironmentEndpointTimedOutError":
diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index e0d36e99bc9..853bb0b1101 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -1,6 +1,8 @@
 import { EnvironmentHttpApi } from "@t3tools/contracts";
+import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
+import * as Schedule from "effect/Schedule";
 import { FetchHttpClient, HttpRouter, HttpServer } from "effect/unstable/http";
 import * as HttpApiBuilder from "effect/unstable/httpapi/HttpApiBuilder";
 
@@ -535,7 +537,25 @@ export const makeServerLayer = Layer.unwrap(
         yield* Effect.forkScoped(
           Effect.sleep("250 millis").pipe(
             Effect.andThen(reconcileDesiredCloudLink(`http://127.0.0.1:${address.port}`)),
-            Effect.retry({ times: 4 }),
+            // On reboot this races NIC/DNS bring-up, so back off exponentially
+            // (capped at 30s) instead of burning all retries in a second.
+            // Bounded overall so a permanently broken setup still surfaces the
+            // warning below. Bad-request/unauthorized/conflict are
+            // deterministic failures (malformed origin, not linked yet, linked
+            // to a different cloud account) that no amount of retrying
+            // converges.
+            Effect.retry({
+              while: (error) =>
+                error._tag !== "EnvironmentHttpBadRequestError" &&
+                error._tag !== "EnvironmentHttpUnauthorizedError" &&
+                error._tag !== "EnvironmentHttpConflictError",
+              schedule: Schedule.exponential("1 second").pipe(
+                Schedule.modifyDelay(({ duration }) =>
+                  Effect.succeed(Duration.min(duration, Duration.seconds(30))),
+                ),
+                Schedule.upTo({ duration: "10 minutes" }),
+              ),
+            }),
             Effect.tap(() => Effect.logInfo("T3 Connect desired link reconciled on startup")),
             Effect.catch((cause) =>
               Effect.logWarning("Failed to reconcile T3 Connect desired link on startup", {
diff --git a/apps/web/src/cloud/linkEnvironment.ts b/apps/web/src/cloud/linkEnvironment.ts
index 22ff986afbd..a245cbc54db 100644
--- a/apps/web/src/cloud/linkEnvironment.ts
+++ b/apps/web/src/cloud/linkEnvironment.ts
@@ -145,7 +145,14 @@ function relayProtectedErrorMessage(error: RelayProtectedErrorType): string {
     case "RelayEnvironmentLinkProofInvalidError":
       return `Relay rejected the environment link proof (${error.reason}).`;
     case "RelayEnvironmentConnectNotAuthorizedError":
-      return "Relay rejected the environment connection request.";
+      // "Not authorized" covers non-auth causes too; surface the reason so a
+      // missing link doesn't read as a credential problem.
+      if (error.reason === "environment_link_not_found") {
+        return "Relay has no active link for this environment. The environment server may not have re-established its link yet.";
+      }
+      return error.reason
+        ? `Relay rejected the environment connection request (${error.reason}).`
+        : "Relay rejected the environment connection request.";
     case "RelayEnvironmentEndpointUnavailableError":
       return `Relay could not reach the environment endpoint (${error.reason}).`;
     case "RelayEnvironmentEndpointTimedOutError":
diff --git a/infra/relay/src/environments/EnvironmentConnector.ts b/infra/relay/src/environments/EnvironmentConnector.ts
index db662aee94d..d840f809e5a 100644
--- a/infra/relay/src/environments/EnvironmentConnector.ts
+++ b/infra/relay/src/environments/EnvironmentConnector.ts
@@ -13,6 +13,7 @@ import {
   RelayEnvironmentMintResponse,
   RelayEnvironmentMintResponseProofPayload,
   RelayCloudMintCredentialProofPayload,
+  RelayEnvironmentConnectNotAuthorizedReason,
   type RelayEnvironmentConnectResponse,
   type RelayEnvironmentStatusResponse,
 } from "@t3tools/contracts/relay";
@@ -44,21 +45,8 @@ import * as ManagedEndpointAllocations from "./ManagedEndpointAllocations.ts";
 import * as RelayConfiguration from "../Config.ts";
 import { isManagedEndpointHostname } from "../deploymentConfig.ts";
 
-export const EnvironmentConnectNotAuthorizedReason = Schema.Literals([
-  "client_proof_key_thumbprint_missing",
-  "environment_link_not_found",
-  "endpoint_provider_not_managed",
-  "managed_endpoint_allocation_not_found",
-  "managed_endpoint_base_domain_not_configured",
-  "managed_endpoint_allocation_not_ready",
-  "managed_endpoint_hostname_invalid",
-  "managed_endpoint_mismatch",
-]);
-export type EnvironmentConnectNotAuthorizedReason =
-  typeof EnvironmentConnectNotAuthorizedReason.Type;
-
 function environmentConnectNotAuthorizedReasonMessage(
-  reason: EnvironmentConnectNotAuthorizedReason,
+  reason: RelayEnvironmentConnectNotAuthorizedReason,
 ): string {
   switch (reason) {
     case "client_proof_key_thumbprint_missing":
@@ -85,7 +73,7 @@ export class EnvironmentConnectNotAuthorized extends Schema.TaggedErrorClass<Env
   {
     environmentId: Schema.String,
     operation: Schema.Literals(["connect", "status"]),
-    reason: EnvironmentConnectNotAuthorizedReason,
+    reason: RelayEnvironmentConnectNotAuthorizedReason,
   },
 ) {
   override get message(): string {
diff --git a/infra/relay/src/http/Api.ts b/infra/relay/src/http/Api.ts
index 7510b4a8d41..50bcff665a9 100644
--- a/infra/relay/src/http/Api.ts
+++ b/infra/relay/src/http/Api.ts
@@ -778,9 +778,10 @@ export const dpopClientApi = HttpApiBuilder.group(
           },
           mapRelayCommonApiErrors("invalid_dpop"),
           mapErrorTags({
-            EnvironmentConnectNotAuthorized: (_error, traceId) =>
+            EnvironmentConnectNotAuthorized: (error, traceId) =>
               new RelayEnvironmentConnectNotAuthorizedError({
                 code: "environment_connect_not_authorized",
+                reason: error.reason,
                 traceId,
               }),
             EnvironmentMintRequestFailed: (_error, traceId) =>
@@ -820,9 +821,10 @@ export const dpopClientApi = HttpApiBuilder.group(
           },
           mapRelayCommonApiErrors("invalid_dpop"),
           mapErrorTags({
-            EnvironmentConnectNotAuthorized: (_error, traceId) =>
+            EnvironmentConnectNotAuthorized: (error, traceId) =>
               new RelayEnvironmentConnectNotAuthorizedError({
                 code: "environment_connect_not_authorized",
+                reason: error.reason,
                 traceId,
               }),
             EnvironmentMintRequestFailed: (_error, traceId) =>
diff --git a/packages/contracts/src/relay.ts b/packages/contracts/src/relay.ts
index ff9a9e3ac61..52f7d7d4355 100644
--- a/packages/contracts/src/relay.ts
+++ b/packages/contracts/src/relay.ts
@@ -371,16 +371,34 @@ export class RelayEnvironmentLinkProofInvalidError extends Schema.TaggedErrorCla
   }
 }
 
+export const RelayEnvironmentConnectNotAuthorizedReason = Schema.Literals([
+  "client_proof_key_thumbprint_missing",
+  "environment_link_not_found",
+  "endpoint_provider_not_managed",
+  "managed_endpoint_allocation_not_found",
+  "managed_endpoint_base_domain_not_configured",
+  "managed_endpoint_allocation_not_ready",
+  "managed_endpoint_hostname_invalid",
+  "managed_endpoint_mismatch",
+]);
+export type RelayEnvironmentConnectNotAuthorizedReason =
+  typeof RelayEnvironmentConnectNotAuthorizedReason.Type;
+
 export class RelayEnvironmentConnectNotAuthorizedError extends Schema.TaggedErrorClass<RelayEnvironmentConnectNotAuthorizedError>()(
   "RelayEnvironmentConnectNotAuthorizedError",
   {
     code: Schema.Literal("environment_connect_not_authorized"),
+    // Optional so responses from relays deployed before the reason was
+    // threaded through still decode.
+    reason: Schema.optional(RelayEnvironmentConnectNotAuthorizedReason),
     traceId: TrimmedNonEmptyString,
   },
   { httpApiStatus: 403 },
 ) {
   override get message(): string {
-    return "Relay environment connection is not authorized";
+    return this.reason
+      ? `Relay environment connection is not authorized: ${this.reason}`
+      : "Relay environment connection is not authorized";
   }
 }
 

From abc409c2d4a072c2de46c9015f5cffff00dcc46b Mon Sep 17 00:00:00 2001
From: Jake Leventhal <jakeleventhal@me.com>
Date: Thu, 30 Jul 2026 10:39:15 -0400
Subject: [PATCH 25/34] =?UTF-8?q?Add=20project=20file=20picker=20(?=
 =?UTF-8?q?=E2=8C=98P)=20and=20project=20content=20search=20(=E2=87=A7?=
 =?UTF-8?q?=E2=8C=98F)=20(#4855)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Julius Marminge <julius0216@outlook.com>
---
 apps/server/src/auth/RpcAuthorization.ts      |   1 +
 apps/server/src/keybindings.test.ts           |   2 +
 apps/server/src/keybindings.ts                |  21 +-
 .../src/workspace/WorkspaceEntries.test.ts    | 344 ++++++++++-
 apps/server/src/workspace/WorkspaceEntries.ts | 105 +++-
 .../workspace/WorkspaceSearchIndex.test.ts    | 143 ++++-
 .../src/workspace/WorkspaceSearchIndex.ts     | 315 ++++++++--
 apps/server/src/ws.ts                         |  18 +
 apps/web/src/components/ChatMarkdown.tsx      |  52 +-
 .../components/CommandPalette.logic.test.ts   |  72 +++
 .../src/components/CommandPalette.logic.ts    |  51 +-
 apps/web/src/components/CommandPalette.tsx    | 584 +++++++++---------
 .../src/components/CommandPaletteContent.tsx  |  77 +++
 .../src/components/RenderErrorBoundary.tsx    |  16 +
 .../src/components/files/FileBrowserPanel.tsx |  72 +++
 .../src/components/files/FilePreviewPanel.tsx | 188 ++++--
 .../files/ProjectFilePicker.logic.test.ts     |  83 +++
 .../files/ProjectFilePicker.logic.ts          |  73 +++
 .../components/files/ProjectFilePicker.tsx    | 163 +++++
 .../components/files/fileLineReveal.test.ts   |  32 +
 .../src/components/files/fileLineReveal.ts    |  24 +
 .../files/projectFilesQueryState.ts           |  27 +
 .../search/HighlightedSearchLine.tsx          | 183 ++++++
 .../search/ProjectContentSearchDialog.tsx     | 315 ++++++++++
 apps/web/src/hooks/useActiveProjectTarget.ts  |  41 ++
 apps/web/src/hooks/useHandleNewThread.ts      |   2 +-
 apps/web/src/keybindings.test.ts              |  52 ++
 apps/web/src/lib/syntaxHighlighting.test.ts   |  28 +
 apps/web/src/lib/syntaxHighlighting.ts        |  30 +
 apps/web/src/state/projects.ts                |  13 +
 apps/web/src/state/queries.test.ts            |  25 +
 apps/web/src/state/queries.ts                 |  97 ++-
 docs/user/keybindings.md                      |   4 +
 packages/contracts/src/keybindings.test.ts    |  12 +
 packages/contracts/src/keybindings.ts         |   2 +
 packages/contracts/src/project.test.ts        |  42 ++
 packages/contracts/src/project.ts             |  82 ++-
 packages/contracts/src/rpc.ts                 |  11 +
 packages/shared/src/keybindings.ts            |   2 +
 39 files changed, 2928 insertions(+), 476 deletions(-)
 create mode 100644 apps/web/src/components/CommandPaletteContent.tsx
 create mode 100644 apps/web/src/components/RenderErrorBoundary.tsx
 create mode 100644 apps/web/src/components/files/ProjectFilePicker.logic.test.ts
 create mode 100644 apps/web/src/components/files/ProjectFilePicker.logic.ts
 create mode 100644 apps/web/src/components/files/ProjectFilePicker.tsx
 create mode 100644 apps/web/src/components/files/fileLineReveal.test.ts
 create mode 100644 apps/web/src/components/files/fileLineReveal.ts
 create mode 100644 apps/web/src/components/search/HighlightedSearchLine.tsx
 create mode 100644 apps/web/src/components/search/ProjectContentSearchDialog.tsx
 create mode 100644 apps/web/src/hooks/useActiveProjectTarget.ts
 create mode 100644 apps/web/src/lib/syntaxHighlighting.test.ts
 create mode 100644 apps/web/src/lib/syntaxHighlighting.ts
 create mode 100644 apps/web/src/state/queries.test.ts

diff --git a/apps/server/src/auth/RpcAuthorization.ts b/apps/server/src/auth/RpcAuthorization.ts
index 80b1cb4aa1f..fb753b9aa4b 100644
--- a/apps/server/src/auth/RpcAuthorization.ts
+++ b/apps/server/src/auth/RpcAuthorization.ts
@@ -55,6 +55,7 @@ export const RPC_REQUIRED_SCOPES = {
   [WS_METHODS.sourceControlPublishRepository]: AuthOrchestrationOperateScope,
   [WS_METHODS.projectsListEntries]: AuthOrchestrationReadScope,
   [WS_METHODS.projectsReadFile]: AuthOrchestrationReadScope,
+  [WS_METHODS.projectsSearchContents]: AuthOrchestrationReadScope,
   [WS_METHODS.projectsSearchEntries]: AuthOrchestrationReadScope,
   [WS_METHODS.projectsWriteFile]: AuthOrchestrationOperateScope,
   [WS_METHODS.shellOpenInEditor]: AuthOrchestrationOperateScope,
diff --git a/apps/server/src/keybindings.test.ts b/apps/server/src/keybindings.test.ts
index 2eef6ac8416..252819adacf 100644
--- a/apps/server/src/keybindings.test.ts
+++ b/apps/server/src/keybindings.test.ts
@@ -198,6 +198,8 @@ it.layer(NodeServices.layer)("keybindings", (it) => {
       assert.equal(defaultsByCommand.get("thread.jump.1"), "mod+1");
       assert.equal(defaultsByCommand.get("thread.jump.9"), "mod+9");
       assert.equal(defaultsByCommand.get("modelPicker.toggle"), "mod+shift+m");
+      assert.equal(defaultsByCommand.get("filePicker.toggle"), "mod+p");
+      assert.equal(defaultsByCommand.get("projectSearch.toggle"), "mod+shift+f");
       assert.equal(defaultsByCommand.get("sidebar.toggle"), "mod+b");
       assert.equal(defaultsByCommand.get("rightPanel.toggle"), "mod+alt+b");
       assert.equal(defaultsByCommand.get("terminal.splitVertical"), "mod+shift+d");
diff --git a/apps/server/src/keybindings.ts b/apps/server/src/keybindings.ts
index 18a78fe3623..53f329e8512 100644
--- a/apps/server/src/keybindings.ts
+++ b/apps/server/src/keybindings.ts
@@ -547,19 +547,24 @@ const make = Effect.gen(function* () {
         });
       }
 
-      const nextConfig = [...customConfig, ...missingDefaults];
-      const cappedConfig =
-        nextConfig.length > MAX_KEYBINDINGS_COUNT
-          ? nextConfig.slice(-MAX_KEYBINDINGS_COUNT)
-          : nextConfig;
-      if (nextConfig.length > MAX_KEYBINDINGS_COUNT) {
-        yield* Effect.logWarning("truncating keybindings config to max entries", {
+      // Startup backfill must never evict persisted user rules: append only
+      // the defaults that fit and skip the rest.
+      const availableSlots = Math.max(0, MAX_KEYBINDINGS_COUNT - customConfig.length);
+      const defaultsToAppend = missingDefaults.slice(0, availableSlots);
+      const skippedDefaults = missingDefaults.slice(availableSlots);
+      if (skippedDefaults.length > 0) {
+        yield* Effect.logWarning("skipping default keybinding backfill at max entries", {
           path: keybindingsConfigPath,
           maxEntries: MAX_KEYBINDINGS_COUNT,
+          commands: skippedDefaults.map((rule) => rule.command),
         });
       }
+      if (defaultsToAppend.length === 0) {
+        yield* Cache.invalidate(resolvedConfigCache, resolvedConfigCacheKey);
+        return;
+      }
 
-      yield* writeConfigAtomically(cappedConfig);
+      yield* writeConfigAtomically([...customConfig, ...defaultsToAppend]);
       yield* Cache.invalidate(resolvedConfigCache, resolvedConfigCacheKey);
     }),
   );
diff --git a/apps/server/src/workspace/WorkspaceEntries.test.ts b/apps/server/src/workspace/WorkspaceEntries.test.ts
index a08350ed959..d47aaaec826 100644
--- a/apps/server/src/workspace/WorkspaceEntries.test.ts
+++ b/apps/server/src/workspace/WorkspaceEntries.test.ts
@@ -72,7 +72,12 @@ const git = (cwd: string, args: ReadonlyArray<string>, env?: NodeJS.ProcessEnv)
     return result.stdout.trim();
   });
 
-const searchWorkspaceEntries = (input: { cwd: string; query: string; limit: number }) =>
+const searchWorkspaceEntries = (input: {
+  cwd: string;
+  query: string;
+  limit: number;
+  kind?: "file" | "directory";
+}) =>
   Effect.gen(function* () {
     const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
     return yield* workspaceEntries.search(input);
@@ -200,6 +205,62 @@ it.layer(TestLayer, { excludeTestServices: true })("WorkspaceEntries", (it) => {
       }),
     );
 
+    it.effect("applies the file filter before limiting search results", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-file-limit-" });
+        yield* writeTextFile(cwd, "src/index.ts");
+        yield* writeTextFile(cwd, "src/internal.ts");
+
+        const result = yield* searchWorkspaceEntries({
+          cwd,
+          query: "src",
+          limit: 1,
+          kind: "file",
+        });
+
+        expect(result.entries).toEqual([{ path: "src/index.ts", kind: "file" }]);
+        expect(result.truncated).toBe(true);
+      }),
+    );
+
+    it.effect("answers an empty file-filtered query with a bounded file listing", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-empty-query-" });
+        yield* writeTextFile(cwd, "src/index.ts");
+        yield* writeTextFile(cwd, "README.md");
+
+        const result = yield* searchWorkspaceEntries({
+          cwd,
+          query: "",
+          limit: 10,
+          kind: "file",
+        });
+
+        const paths = result.entries.map((entry) => entry.path);
+        expect(paths).toHaveLength(2);
+        expect(paths).toContain("src/index.ts");
+        expect(paths).toContain("README.md");
+        expect(result.entries.every((entry) => entry.kind === "file")).toBe(true);
+      }),
+    );
+
+    it.effect("returns only directories for the directory filter", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-directory-filter-" });
+        yield* writeTextFile(cwd, "src/index.ts");
+
+        const result = yield* searchWorkspaceEntries({
+          cwd,
+          query: "src",
+          limit: 10,
+          kind: "directory",
+        });
+
+        expect(result.entries).toEqual([{ path: "src", kind: "directory" }]);
+        expect(result.truncated).toBe(false);
+      }),
+    );
+
     it.effect("excludes gitignored paths for git repositories", () =>
       Effect.gen(function* () {
         const cwd = yield* makeTempDir({ prefix: "t3code-workspace-gitignore-", git: true });
@@ -292,6 +353,287 @@ it.layer(TestLayer, { excludeTestServices: true })("WorkspaceEntries", (it) => {
     );
   });
 
+  describe("searchContents", () => {
+    it.effect("returns content matches with file paths, line numbers, and ranges", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-content-search-" });
+        yield* writeTextFile(
+          cwd,
+          "src/shapes.ts",
+          "export const square = 4;\nexport const Square = 16;\nexport const squareSize = 8;\n",
+        );
+        yield* writeTextFile(cwd, "src/other.ts", "const circle = true;\n");
+
+        const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
+        const result = yield* workspaceEntries.searchContents({
+          cwd,
+          query: "Square",
+          limit: 100,
+          caseSensitive: false,
+          wholeWord: true,
+          useRegex: false,
+        });
+
+        expect(result.matches.map((match) => [match.path, match.lineNumber])).toEqual([
+          ["src/shapes.ts", 1],
+          ["src/shapes.ts", 2],
+        ]);
+        expect(result.matches[0]?.matchRanges).toEqual([{ start: 13, end: 19 }]);
+        expect(result.truncated).toBe(false);
+      }),
+    );
+
+    it.effect("honors case sensitivity and gitignore rules", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-content-ignore-", git: true });
+        yield* writeTextFile(cwd, ".gitignore", "ignored.txt\n");
+        yield* writeTextFile(cwd, "src/keep.ts", "square\nSquare\n");
+        yield* writeTextFile(cwd, "ignored.txt", "Square\n");
+
+        const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
+        const result = yield* workspaceEntries.searchContents({
+          cwd,
+          query: "Square",
+          limit: 100,
+          caseSensitive: true,
+          wholeWord: false,
+          useRegex: false,
+        });
+
+        expect(result.matches).toHaveLength(1);
+        expect(result.matches[0]).toMatchObject({ path: "src/keep.ts", lineNumber: 2 });
+      }),
+    );
+
+    it.effect("filters whole-word matches by word boundaries without widening ranges", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-content-whole-word-" });
+        yield* writeTextFile(cwd, "src/words.ts", "note notes denote\nfootnote note\n");
+
+        const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
+        const result = yield* workspaceEntries.searchContents({
+          cwd,
+          query: "note",
+          limit: 100,
+          caseSensitive: true,
+          wholeWord: true,
+          useRegex: false,
+        });
+
+        // "notes", "denote", and "footnote" are word-adjacent and excluded;
+        // ranges cover exactly the query, never boundary characters.
+        expect(result.matches).toEqual([
+          expect.objectContaining({
+            path: "src/words.ts",
+            lineNumber: 1,
+            matchRanges: [{ start: 0, end: 4 }],
+          }),
+          expect.objectContaining({
+            path: "src/words.ts",
+            lineNumber: 2,
+            matchRanges: [{ start: 9, end: 13 }],
+          }),
+        ]);
+      }),
+    );
+
+    it.effect("finds later whole-word matches in a file after rejected raw matches", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-content-late-whole-word-" });
+        yield* writeTextFile(cwd, "src/words.ts", `${"afoo\n".repeat(10)}foo\n`);
+
+        const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
+        const result = yield* workspaceEntries.searchContents({
+          cwd,
+          query: "foo",
+          limit: 1,
+          caseSensitive: true,
+          wholeWord: true,
+          useRegex: false,
+        });
+
+        expect(result.matches).toEqual([
+          expect.objectContaining({
+            path: "src/words.ts",
+            lineNumber: 11,
+            matchRanges: [{ start: 0, end: 3 }],
+          }),
+        ]);
+      }),
+    );
+
+    it.effect("treats astral-plane letters as whole word characters", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-content-astral-word-" });
+        yield* writeTextFile(cwd, "src/words.ts", "𐐀foo foo foo𐐀\n");
+
+        const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
+        const result = yield* workspaceEntries.searchContents({
+          cwd,
+          query: "foo",
+          limit: 100,
+          caseSensitive: true,
+          wholeWord: true,
+          useRegex: false,
+        });
+
+        expect(result.matches).toEqual([
+          expect.objectContaining({
+            path: "src/words.ts",
+            lineNumber: 1,
+            matchRanges: [{ start: 6, end: 9 }],
+          }),
+        ]);
+      }),
+    );
+
+    it.effect("matches punctuation-edged whole-word queries including adjacent occurrences", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-content-punctuation-" });
+        yield* writeTextFile(cwd, "src/words.ts", "-foo- -foo- -foo-\n");
+
+        const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
+        const result = yield* workspaceEntries.searchContents({
+          cwd,
+          query: "-foo-",
+          limit: 100,
+          caseSensitive: true,
+          wholeWord: true,
+          useRegex: false,
+        });
+
+        // Consuming-boundary regex would swallow the separating spaces and
+        // drop the middle occurrence; boundary post-filtering keeps all three.
+        expect(result.matches).toHaveLength(1);
+        expect(result.matches[0]).toMatchObject({
+          path: "src/words.ts",
+          lineNumber: 1,
+          matchRanges: [
+            { start: 0, end: 5 },
+            { start: 6, end: 11 },
+            { start: 12, end: 17 },
+          ],
+        });
+      }),
+    );
+
+    it.effect("matches punctuation-edged regex queries as whole words", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-content-regex-punctuation-" });
+        yield* writeTextFile(cwd, "src/words.ts", "foo- foo-\nafoo-b\n");
+
+        const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
+        const result = yield* workspaceEntries.searchContents({
+          cwd,
+          query: "foo-",
+          limit: 100,
+          caseSensitive: true,
+          wholeWord: true,
+          useRegex: true,
+        });
+
+        // wholeWord + useRegex must not silently drop non-word-edged patterns
+        // like "foo-", and "afoo-" is excluded because 'a'/'f' are both word
+        // characters at the match's left edge.
+        expect(result.matches).toHaveLength(1);
+        expect(result.matches[0]).toMatchObject({
+          path: "src/words.ts",
+          lineNumber: 1,
+          matchRanges: [
+            { start: 0, end: 4 },
+            { start: 5, end: 9 },
+          ],
+        });
+      }),
+    );
+
+    it.effect("caps matches per file so one dense file cannot fill the page", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-content-per-file-cap-" });
+        yield* writeTextFile(cwd, "src/dense.ts", "needle\n".repeat(300));
+        yield* writeTextFile(cwd, "src/other.ts", "needle\n");
+
+        const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
+        const result = yield* workspaceEntries.searchContents({
+          cwd,
+          query: "needle",
+          limit: 500,
+          caseSensitive: true,
+          wholeWord: false,
+          useRegex: false,
+        });
+
+        const byPath = new Map<string, number>();
+        for (const match of result.matches) {
+          byPath.set(match.path, (byPath.get(match.path) ?? 0) + 1);
+        }
+        expect(byPath.get("src/dense.ts")).toBe(100);
+        expect(byPath.get("src/other.ts")).toBe(1);
+      }),
+    );
+
+    it.effect("preserves regex escapes during case-insensitive searches", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-content-regex-" });
+        yield* writeTextFile(cwd, "src/shapes.ts", "Square\nsquare\n");
+
+        const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
+        const result = yield* workspaceEntries.searchContents({
+          cwd,
+          query: "\\SQUARE",
+          limit: 100,
+          caseSensitive: false,
+          wholeWord: false,
+          useRegex: true,
+        });
+
+        expect(result.matches.map((match) => match.lineNumber)).toEqual([1, 2]);
+      }),
+    );
+
+    it.effect("preserves invalid regex errors during case-insensitive searches", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-content-invalid-regex-" });
+        yield* writeTextFile(cwd, "src/shapes.ts", "foobar\n");
+
+        const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
+        const result = yield* workspaceEntries.searchContents({
+          cwd,
+          query: "foo)bar(",
+          limit: 100,
+          caseSensitive: false,
+          wholeWord: false,
+          useRegex: true,
+        });
+
+        expect(result.regexFallbackError).toBeDefined();
+        expect(result.matches).toEqual([]);
+      }),
+    );
+
+    it.effect("maps multi-byte lines to string-indexed ranges", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-content-multibyte-" });
+        yield* writeTextFile(cwd, "src/notes.ts", 'const label = "héllo wörld";\n');
+
+        const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
+        const result = yield* workspaceEntries.searchContents({
+          cwd,
+          query: "wörld",
+          limit: 100,
+          caseSensitive: true,
+          wholeWord: false,
+          useRegex: false,
+        });
+
+        expect(result.matches).toHaveLength(1);
+        const match = result.matches[0]!;
+        const range = match.matchRanges[0]!;
+        expect(match.lineContent.slice(range.start, range.end)).toBe("wörld");
+      }),
+    );
+  });
+
   describe("browse", () => {
     it.effect("returns matching directories and excludes files", () =>
       Effect.gen(function* () {
diff --git a/apps/server/src/workspace/WorkspaceEntries.ts b/apps/server/src/workspace/WorkspaceEntries.ts
index 7501cbe0eab..bb2113dac37 100644
--- a/apps/server/src/workspace/WorkspaceEntries.ts
+++ b/apps/server/src/workspace/WorkspaceEntries.ts
@@ -14,11 +14,14 @@ import type {
   FilesystemBrowseResult,
   ProjectListEntriesInput,
   ProjectListEntriesResult,
+  ProjectSearchContentsInput,
+  ProjectSearchContentsResult,
   ProjectSearchEntriesInput,
   ProjectSearchEntriesResult,
 } from "@t3tools/contracts";
 import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 import { isExplicitRelativePath, isWindowsAbsolutePath } from "@t3tools/shared/path";
+import { normalizeSearchQuery } from "@t3tools/shared/searchRanking";
 
 import * as WorkspacePaths from "./WorkspacePaths.ts";
 import * as WorkspaceSearchIndex from "./WorkspaceSearchIndex.ts";
@@ -93,6 +96,9 @@ export class WorkspaceEntries extends Context.Service<
     readonly search: (
       input: ProjectSearchEntriesInput,
     ) => Effect.Effect<ProjectSearchEntriesResult, WorkspaceEntriesError>;
+    readonly searchContents: (
+      input: ProjectSearchContentsInput,
+    ) => Effect.Effect<ProjectSearchContentsResult, WorkspaceEntriesError>;
     readonly refresh: (cwd: string) => Effect.Effect<void>;
   }
 >()("t3/workspace/WorkspaceEntries") {}
@@ -148,33 +154,37 @@ export const make = Effect.gen(function* () {
       const normalizedCwd = yield* normalizeWorkspaceRoot(cwd).pipe(
         Effect.orElseSucceed(() => cwd),
       );
-      if (!(yield* RcMap.has(workspaceSearchIndexes.rcMap, normalizedCwd))) {
-        return;
-      }
-      const recoverRefreshFailure = (
-        cause:
-          | WorkspaceSearchIndex.WorkspaceSearchIndexCreateFailed
-          | WorkspaceSearchIndex.WorkspaceSearchIndexScanTimedOut
-          | WorkspaceSearchIndex.WorkspaceSearchIndexRefreshFailed,
-      ) =>
-        Effect.gen(function* () {
-          yield* Effect.logWarning("Failed to refresh workspace search index", {
-            cwd,
-            cause,
+      for (const variant of WorkspaceSearchIndex.WORKSPACE_SEARCH_INDEX_VARIANTS) {
+        const indexKey = WorkspaceSearchIndex.workspaceSearchIndexKey(normalizedCwd, variant);
+        if (!(yield* RcMap.has(workspaceSearchIndexes.rcMap, indexKey))) {
+          continue;
+        }
+        const recoverRefreshFailure = (
+          cause:
+            | WorkspaceSearchIndex.WorkspaceSearchIndexCreateFailed
+            | WorkspaceSearchIndex.WorkspaceSearchIndexScanTimedOut
+            | WorkspaceSearchIndex.WorkspaceSearchIndexRefreshFailed,
+        ) =>
+          Effect.gen(function* () {
+            yield* Effect.logWarning("Failed to refresh workspace search index", {
+              cwd,
+              variant,
+              cause,
+            });
+            yield* workspaceSearchIndexes.invalidate(indexKey);
           });
-          yield* workspaceSearchIndexes.invalidate(normalizedCwd);
-        });
-      yield* Effect.gen(function* () {
-        const searchIndex = yield* WorkspaceSearchIndex.WorkspaceSearchIndex;
-        yield* searchIndex.refresh();
-      }).pipe(
-        Effect.provide(workspaceSearchIndexes.get(normalizedCwd)),
-        Effect.catchTags({
-          WorkspaceSearchIndexCreateFailed: recoverRefreshFailure,
-          WorkspaceSearchIndexScanTimedOut: recoverRefreshFailure,
-          WorkspaceSearchIndexRefreshFailed: recoverRefreshFailure,
-        }),
-      );
+        yield* Effect.gen(function* () {
+          const searchIndex = yield* WorkspaceSearchIndex.WorkspaceSearchIndex;
+          yield* searchIndex.refresh();
+        }).pipe(
+          Effect.provide(workspaceSearchIndexes.get(indexKey)),
+          Effect.catchTags({
+            WorkspaceSearchIndexCreateFailed: recoverRefreshFailure,
+            WorkspaceSearchIndexScanTimedOut: recoverRefreshFailure,
+            WorkspaceSearchIndexRefreshFailed: recoverRefreshFailure,
+          }),
+        );
+      }
     },
   );
 
@@ -230,28 +240,55 @@ export const make = Effect.gen(function* () {
   const search: WorkspaceEntries["Service"]["search"] = Effect.fn("WorkspaceEntries.search")(
     function* (input) {
       const normalizedCwd = yield* normalizeWorkspaceRoot(input.cwd);
-      const normalizedQuery = input.query
-        .trim()
-        .toLowerCase()
-        .replace(/^[@./]+/, "");
+      const normalizedQuery = normalizeSearchQuery(input.query, {
+        trimLeadingPattern: /^[@./]+/,
+      });
       return yield* Effect.gen(function* () {
         const searchIndex = yield* WorkspaceSearchIndex.WorkspaceSearchIndex;
-        return yield* searchIndex.search(normalizedQuery, input.limit);
-      }).pipe(Effect.provide(workspaceSearchIndexes.get(normalizedCwd)));
+        return yield* searchIndex.search(normalizedQuery, input.limit, input.kind);
+      }).pipe(
+        Effect.provide(
+          workspaceSearchIndexes.get(
+            WorkspaceSearchIndex.workspaceSearchIndexKey(normalizedCwd, "paths"),
+          ),
+        ),
+      );
     },
   );
 
+  const searchContents: WorkspaceEntries["Service"]["searchContents"] = Effect.fn(
+    "WorkspaceEntries.searchContents",
+  )(function* (input) {
+    const normalizedCwd = yield* normalizeWorkspaceRoot(input.cwd);
+    return yield* Effect.gen(function* () {
+      const searchIndex = yield* WorkspaceSearchIndex.WorkspaceSearchIndex;
+      return yield* searchIndex.searchContents(input);
+    }).pipe(
+      Effect.provide(
+        workspaceSearchIndexes.get(
+          WorkspaceSearchIndex.workspaceSearchIndexKey(normalizedCwd, "content"),
+        ),
+      ),
+    );
+  });
+
   const list: WorkspaceEntries["Service"]["list"] = Effect.fn("WorkspaceEntries.list")(
     function* (input) {
       const normalizedCwd = yield* normalizeWorkspaceRoot(input.cwd);
       return yield* Effect.gen(function* () {
         const searchIndex = yield* WorkspaceSearchIndex.WorkspaceSearchIndex;
         return yield* searchIndex.list();
-      }).pipe(Effect.provide(workspaceSearchIndexes.get(normalizedCwd)));
+      }).pipe(
+        Effect.provide(
+          workspaceSearchIndexes.get(
+            WorkspaceSearchIndex.workspaceSearchIndexKey(normalizedCwd, "paths"),
+          ),
+        ),
+      );
     },
   );
 
-  return WorkspaceEntries.of({ browse, list, refresh, search });
+  return WorkspaceEntries.of({ browse, list, refresh, search, searchContents });
 });
 
 export const layer = Layer.effect(WorkspaceEntries, make).pipe(
diff --git a/apps/server/src/workspace/WorkspaceSearchIndex.test.ts b/apps/server/src/workspace/WorkspaceSearchIndex.test.ts
index 9b7ed4e2453..15572837030 100644
--- a/apps/server/src/workspace/WorkspaceSearchIndex.test.ts
+++ b/apps/server/src/workspace/WorkspaceSearchIndex.test.ts
@@ -1,4 +1,4 @@
-import { FileFinder } from "@ff-labs/fff-node";
+import { FileFinder, type GrepCursor, type GrepOptions, type GrepResult } from "@ff-labs/fff-node";
 import { afterEach, expect, it } from "@effect/vitest";
 import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
@@ -51,6 +51,41 @@ it.effect("keeps returned FileFinder creation diagnostics out of the cause chain
   }),
 );
 
+it.effect("waits for the full content index warmup before returning", () =>
+  Effect.gen(function* () {
+    const waitForIndexReady = vi.fn(async () => ({ ok: true as const, value: true }));
+    const finder = {
+      destroy: vi.fn(),
+      waitForIndexReady,
+    } as unknown as FileFinder;
+    vi.spyOn(FileFinder, "create").mockReturnValueOnce({ ok: true, value: finder });
+
+    yield* Effect.scoped(WorkspaceSearchIndex.make("/workspace/project", "content"));
+
+    expect(waitForIndexReady).toHaveBeenCalledWith(15_000);
+  }),
+);
+
+it.effect("preserves a full-index warmup timeout as a structured error", () =>
+  Effect.gen(function* () {
+    const finder = {
+      destroy: vi.fn(),
+      waitForIndexReady: vi.fn(async () => ({ ok: true as const, value: false })),
+    } as unknown as FileFinder;
+    vi.spyOn(FileFinder, "create").mockReturnValueOnce({ ok: true, value: finder });
+
+    const error = yield* Effect.flip(
+      Effect.scoped(WorkspaceSearchIndex.make("/workspace/project", "content")),
+    );
+
+    expect(error).toMatchObject({
+      _tag: "WorkspaceSearchIndexScanTimedOut",
+      cwd: "/workspace/project",
+      timeout: "15 seconds",
+    });
+  }),
+);
+
 it.effect("preserves FileFinder destroy failures as structured defects", () =>
   Effect.gen(function* () {
     const cause = new Error("native destroy failed");
@@ -58,7 +93,7 @@ it.effect("preserves FileFinder destroy failures as structured defects", () =>
       destroy: vi.fn(() => {
         throw cause;
       }),
-      isScanning: vi.fn(() => false),
+      waitForIndexReady: vi.fn(async () => ({ ok: true as const, value: true })),
     } as unknown as FileFinder;
     vi.spyOn(FileFinder, "create").mockReturnValueOnce({ ok: true, value: finder });
 
@@ -85,12 +120,16 @@ it.effect("preserves search and refresh failures with operation context", () =>
     Effect.gen(function* () {
       const searchCause = new Error("native search failed");
       const refreshCause = new Error("native scan failed");
+      const contentSearchCause = new Error("native grep failed");
       const finder = {
         destroy: vi.fn(),
-        isScanning: vi.fn(() => false),
+        waitForIndexReady: vi.fn(async () => ({ ok: true as const, value: true })),
         mixedSearch: vi.fn(() => {
           throw searchCause;
         }),
+        grep: vi.fn(() => {
+          throw contentSearchCause;
+        }),
         scanFiles: vi.fn(() => {
           throw refreshCause;
         }),
@@ -100,6 +139,15 @@ it.effect("preserves search and refresh failures with operation context", () =>
       const searchIndex = yield* WorkspaceSearchIndex.make("/workspace/project");
       const query = "authorization: Bearer secret-token";
       const searchError = yield* Effect.flip(searchIndex.search(query, 3));
+      const contentSearchError = yield* Effect.flip(
+        searchIndex.searchContents({
+          query,
+          limit: 3,
+          caseSensitive: false,
+          wholeWord: false,
+          useRegex: false,
+        }),
+      );
       const refreshError = yield* Effect.flip(searchIndex.refresh());
 
       expect(searchError).toMatchObject({
@@ -112,6 +160,16 @@ it.effect("preserves search and refresh failures with operation context", () =>
       });
       expect(searchError).not.toHaveProperty("query");
       expect(searchError.message).not.toMatch(/Bearer|secret-token/);
+      expect(contentSearchError).toMatchObject({
+        _tag: "WorkspaceSearchIndexSearchFailed",
+        cwd: "/workspace/project",
+        queryLength: query.length,
+        pageSize: 3,
+        reason: "FileFinder.grep threw unexpectedly.",
+        cause: contentSearchCause,
+      });
+      expect(contentSearchError).not.toHaveProperty("query");
+      expect(contentSearchError.message).not.toMatch(/Bearer|secret-token/);
       expect(refreshError).toMatchObject({
         _tag: "WorkspaceSearchIndexRefreshFailed",
         cwd: "/workspace/project",
@@ -127,7 +185,7 @@ it.effect("keeps returned search diagnostics out of the cause chain", () =>
     Effect.gen(function* () {
       const finder = {
         destroy: vi.fn(),
-        isScanning: vi.fn(() => false),
+        waitForIndexReady: vi.fn(async () => ({ ok: true as const, value: true })),
         mixedSearch: vi.fn(() => ({ ok: false, error: "native query rejected" })),
         scanFiles: vi.fn(() => ({ ok: false, error: "native refresh rejected" })),
       } as unknown as FileFinder;
@@ -157,3 +215,80 @@ it.effect("keeps returned search diagnostics out of the cause chain", () =>
     }),
   ),
 );
+
+it.effect("continues whole-word searches after a filtered grep page", () =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const nextCursor = {
+        __brand: "GrepCursor",
+        _offset: 1,
+      } as GrepCursor;
+      const grepResult = (
+        lineContent: string,
+        matchRanges: Array<[number, number]>,
+        cursor: GrepCursor | null,
+      ): GrepResult => ({
+        items: [
+          {
+            relativePath: "src/words.ts",
+            fileName: "words.ts",
+            gitStatus: "unmodified",
+            size: lineContent.length,
+            modified: 0,
+            isBinary: false,
+            totalFrecencyScore: 0,
+            accessFrecencyScore: 0,
+            modificationFrecencyScore: 0,
+            lineNumber: 1,
+            col: 0,
+            byteOffset: 0,
+            lineContent,
+            matchRanges,
+          },
+        ],
+        totalMatched: 1,
+        totalFilesSearched: 1,
+        totalFiles: 1,
+        filteredFileCount: 1,
+        nextCursor: cursor,
+      });
+      const grep = vi.fn((_query: string, options?: GrepOptions) =>
+        options?.cursor
+          ? { ok: true as const, value: grepResult("needle", [[0, 6]], null) }
+          : {
+              ok: true as const,
+              value: grepResult("needleSuffix", [[0, 6]], nextCursor),
+            },
+      );
+      const finder = {
+        destroy: vi.fn(),
+        waitForIndexReady: vi.fn(async () => ({ ok: true as const, value: true })),
+        grep,
+      } as unknown as FileFinder;
+      vi.spyOn(FileFinder, "create").mockReturnValueOnce({ ok: true, value: finder });
+
+      const searchIndex = yield* WorkspaceSearchIndex.make("/workspace/project", "content");
+      const result = yield* searchIndex.searchContents({
+        query: "needle",
+        limit: 1,
+        caseSensitive: true,
+        wholeWord: true,
+        useRegex: false,
+      });
+
+      expect(result).toEqual({
+        matches: [
+          {
+            path: "src/words.ts",
+            lineNumber: 1,
+            lineContent: "needle",
+            matchRanges: [{ start: 0, end: 6 }],
+          },
+        ],
+        truncated: false,
+      });
+      expect(grep).toHaveBeenCalledTimes(2);
+      expect(grep.mock.calls[1]?.[1]?.cursor).toBe(nextCursor);
+    }),
+  ),
+);
diff --git a/apps/server/src/workspace/WorkspaceSearchIndex.ts b/apps/server/src/workspace/WorkspaceSearchIndex.ts
index db4d46851e7..8bf36b7a80a 100644
--- a/apps/server/src/workspace/WorkspaceSearchIndex.ts
+++ b/apps/server/src/workspace/WorkspaceSearchIndex.ts
@@ -1,22 +1,36 @@
-import { FileFinder, type MixedItem, type MixedSearchResult } from "@ff-labs/fff-node";
+import {
+  type DirItem,
+  type DirSearchResult,
+  type FileItem,
+  FileFinder,
+  type GrepCursor,
+  type MixedItem,
+  type MixedSearchResult,
+  type Result,
+  type SearchResult,
+} from "@ff-labs/fff-node";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as LayerMap from "effect/LayerMap";
-import * as Schedule from "effect/Schedule";
 import * as Schema from "effect/Schema";
 
 import type {
   ProjectEntry,
+  ProjectEntryKind,
   ProjectListEntriesResult,
+  ProjectSearchContentsInput,
+  ProjectSearchContentsResult,
   ProjectSearchEntriesResult,
 } from "@t3tools/contracts";
 
 const WORKSPACE_INDEX_MAX_ENTRIES = 25_000;
 const WORKSPACE_INDEX_PAGE_SIZE = WORKSPACE_INDEX_MAX_ENTRIES + 2;
 const WORKSPACE_INDEX_SCAN_TIMEOUT = "15 seconds";
+const WORKSPACE_INDEX_SCAN_TIMEOUT_MS = 15_000;
 const WORKSPACE_INDEX_IDLE_TTL = "15 minutes";
-const WORKSPACE_INDEX_SCAN_POLL_INTERVAL = "50 millis";
+const CONTENT_SEARCH_TIME_BUDGET_MS = 250;
+const CONTENT_SEARCH_MAX_MATCHES_PER_FILE = 100;
 
 export class WorkspaceSearchIndexCreateFailed extends Schema.TaggedErrorClass<WorkspaceSearchIndexCreateFailed>()(
   "WorkspaceSearchIndexCreateFailed",
@@ -96,7 +110,11 @@ export class WorkspaceSearchIndex extends Context.Service<
     readonly search: (
       query: string,
       limit: number,
+      kind?: ProjectEntryKind,
     ) => Effect.Effect<ProjectSearchEntriesResult, WorkspaceSearchIndexSearchFailed>;
+    readonly searchContents: (
+      input: Omit<ProjectSearchContentsInput, "cwd">,
+    ) => Effect.Effect<ProjectSearchContentsResult, WorkspaceSearchIndexSearchFailed>;
     readonly refresh: () => Effect.Effect<
       void,
       WorkspaceSearchIndexRefreshFailed | WorkspaceSearchIndexScanTimedOut
@@ -129,6 +147,43 @@ function toProjectEntry(item: MixedItem): ProjectEntry | null {
   };
 }
 
+function toFileEntry(item: FileItem): ProjectEntry | null {
+  const normalizedPath = trimDirectorySeparator(toPosixPath(item.relativePath));
+  return normalizedPath ? { path: normalizedPath, kind: "file" } : null;
+}
+
+function toDirectoryEntry(item: DirItem): ProjectEntry | null {
+  const normalizedPath = trimDirectorySeparator(toPosixPath(item.relativePath));
+  return normalizedPath ? { path: normalizedPath, kind: "directory" } : null;
+}
+
+function mapFileSearchResult(result: SearchResult, limit: number): ProjectSearchEntriesResult {
+  return {
+    entries: result.items
+      .flatMap((item) => {
+        const entry = toFileEntry(item);
+        return entry ? [entry] : [];
+      })
+      .slice(0, limit),
+    truncated: result.totalMatched > limit,
+  };
+}
+
+function mapDirectorySearchResult(
+  result: DirSearchResult,
+  limit: number,
+): ProjectSearchEntriesResult {
+  const entries = result.items.flatMap((item) => {
+    const entry = toDirectoryEntry(item);
+    return entry ? [entry] : [];
+  });
+  const rootDirectoryCount = result.items.some((item) => item.relativePath.length === 0) ? 1 : 0;
+  return {
+    entries: entries.slice(0, limit),
+    truncated: result.totalMatched - rootDirectoryCount > limit,
+  };
+}
+
 function mapMixedSearchResult(
   result: MixedSearchResult,
   limit: number,
@@ -155,6 +210,74 @@ function mapMixedSearchResult(
   };
 }
 
+const WORD_CHARACTER = /[\p{Letter}\p{Mark}\p{Number}_]/u;
+
+function codePointAt(line: string, index: number): string | undefined {
+  const codePoint = line.codePointAt(index);
+  return codePoint === undefined ? undefined : String.fromCodePoint(codePoint);
+}
+
+function codePointBefore(line: string, index: number): string | undefined {
+  if (index <= 0) return undefined;
+  const previousCodeUnit = line.charCodeAt(index - 1);
+  const previousIndex =
+    previousCodeUnit >= 0xdc00 && previousCodeUnit <= 0xdfff ? index - 2 : index - 1;
+  return codePointAt(line, previousIndex);
+}
+
+function buildContentSearchQuery(input: Omit<ProjectSearchContentsInput, "cwd">): {
+  readonly searchQuery: string;
+  readonly regexMode: boolean;
+} {
+  if (input.caseSensitive) {
+    return { searchQuery: input.query, regexMode: input.useRegex };
+  }
+  // Plain mode relies on smart case: an all-lowercase needle matches
+  // case-insensitively. Regex mode needs an explicit inline flag instead.
+  return input.useRegex
+    ? { searchQuery: `(?i)${input.query}`, regexMode: true }
+    : { searchQuery: input.query.toLowerCase(), regexMode: false };
+}
+
+function mapContentMatchRanges(
+  line: string,
+  byteRanges: ReadonlyArray<readonly [number, number]>,
+): Array<{ readonly start: number; readonly end: number }> {
+  const lineBytes = Buffer.from(line);
+  const toStringIndex = (byteOffset: number) => lineBytes.subarray(0, byteOffset).toString().length;
+  return byteRanges.map(([startByte, endByte]) => ({
+    start: toStringIndex(startByte),
+    end: toStringIndex(endByte),
+  }));
+}
+
+/**
+ * Whole-word filtering happens after the grep rather than by wrapping the
+ * pattern in boundary regex: consuming boundaries such as `(?:^|\W)` swallow
+ * the separator between adjacent matches and widen the reported ranges, and
+ * `\b` cannot match punctuation-edged queries at all. Matching VS Code, a
+ * match edge is a word boundary when it touches the line edge, the
+ * neighbouring character is not a word character, or the match's own edge
+ * character is not a word character.
+ */
+function isWholeWordRange(
+  line: string,
+  range: { readonly start: number; readonly end: number },
+): boolean {
+  if (range.end <= range.start) return false;
+  const isWord = (character: string | undefined) =>
+    character !== undefined && WORD_CHARACTER.test(character);
+  const leftIsBoundary =
+    range.start === 0 ||
+    !isWord(codePointBefore(line, range.start)) ||
+    !isWord(codePointAt(line, range.start));
+  const rightIsBoundary =
+    range.end >= line.length ||
+    !isWord(codePointAt(line, range.end)) ||
+    !isWord(codePointBefore(line, range.end));
+  return leftIsBoundary && rightIsBoundary;
+}
+
 function withDirectoryAncestors(entries: ReadonlyArray<ProjectEntry>): ProjectEntry[] {
   const entryByPath = new Map(entries.map((entry) => [entry.path, entry]));
   for (const entry of entries) {
@@ -169,13 +292,19 @@ function withDirectoryAncestors(entries: ReadonlyArray<ProjectEntry>): ProjectEn
   return [...entryByPath.values()];
 }
 
-const createFinder = Effect.fn("WorkspaceSearchIndex.createFinder")(function* (cwd: string) {
+const createFinder = Effect.fn("WorkspaceSearchIndex.createFinder")(function* (
+  cwd: string,
+  variant: WorkspaceSearchIndexVariant,
+) {
   const result = yield* Effect.try({
     try: () =>
       FileFinder.create({
         basePath: cwd,
         disableMmapCache: true,
-        disableContentIndexing: true,
+        // Content indexing costs scan CPU and memory, so only the on-demand
+        // content-search index pays for it; path-only consumers (file tree,
+        // composer path search, file picker) keep the lightweight index.
+        disableContentIndexing: variant !== "content",
         aiMode: false,
         enableFsRootScanning: true,
         enableHomeDirScanning: true,
@@ -194,53 +323,65 @@ const createFinder = Effect.fn("WorkspaceSearchIndex.createFinder")(function* (c
   });
 });
 
-const waitForScan = <E>(cwd: string, finder: FileFinder, onFailure: (cause: unknown) => E) =>
-  Effect.try({
-    try: () => finder.isScanning(),
-    catch: onFailure,
-  }).pipe(
-    Effect.repeat({
-      while: (scanning) => scanning,
-      schedule: Schedule.spaced(WORKSPACE_INDEX_SCAN_POLL_INTERVAL),
-    }),
-    Effect.timeoutOrElse({
-      duration: WORKSPACE_INDEX_SCAN_TIMEOUT,
-      orElse: () =>
-        new WorkspaceSearchIndexScanTimedOut({ cwd, timeout: WORKSPACE_INDEX_SCAN_TIMEOUT }),
-    }),
-    Effect.withSpan("WorkspaceSearchIndex.waitForScan"),
-  );
+const waitForIndexReady = Effect.fn("WorkspaceSearchIndex.waitForIndexReady")(function* <E>(
+  cwd: string,
+  finder: FileFinder,
+  onFailure: (input: { readonly reason: string; readonly cause?: unknown }) => E,
+): Effect.fn.Return<void, E | WorkspaceSearchIndexScanTimedOut> {
+  const result = yield* Effect.tryPromise({
+    try: () => finder.waitForIndexReady(WORKSPACE_INDEX_SCAN_TIMEOUT_MS),
+    catch: (cause) =>
+      onFailure({
+        reason: "FileFinder.waitForIndexReady rejected unexpectedly.",
+        cause,
+      }),
+  });
+  if (!result.ok) {
+    return yield* Effect.fail(onFailure({ reason: result.error }));
+  }
+  if (!result.value) {
+    return yield* new WorkspaceSearchIndexScanTimedOut({
+      cwd,
+      timeout: WORKSPACE_INDEX_SCAN_TIMEOUT,
+    });
+  }
+});
 
-export const make = Effect.fn("WorkspaceSearchIndex.make")(function* (cwd: string) {
-  const finder = yield* Effect.acquireRelease(createFinder(cwd), (finder) =>
+export const make = Effect.fn("WorkspaceSearchIndex.make")(function* (
+  cwd: string,
+  variant: WorkspaceSearchIndexVariant = "paths",
+) {
+  const finder = yield* Effect.acquireRelease(createFinder(cwd, variant), (finder) =>
     Effect.try({
       try: () => finder.destroy(),
       catch: (cause) => new WorkspaceSearchIndexDestroyFailed({ cwd, cause }),
     }).pipe(Effect.orDie),
   );
-  yield* waitForScan(
+  yield* waitForIndexReady(
     cwd,
     finder,
-    (cause) =>
+    ({ reason, cause }) =>
       new WorkspaceSearchIndexCreateFailed({
         cwd,
-        reason: "FileFinder.isScanning threw while creating the index.",
+        reason,
         cause,
       }),
   );
 
-  const runMixedSearch = Effect.fn("WorkspaceSearchIndex.runMixedSearch")(function* (
+  const runSearch = Effect.fn("WorkspaceSearchIndex.runSearch")(function* <A>(
     query: string,
     pageSize: number,
-  ) {
+    operation: "directorySearch" | "fileSearch" | "grep" | "mixedSearch",
+    execute: () => Result<A>,
+  ): Effect.fn.Return<A, WorkspaceSearchIndexSearchFailed> {
     const result = yield* Effect.try({
-      try: () => finder.mixedSearch(query, { pageSize }),
+      try: execute,
       catch: (cause) =>
         new WorkspaceSearchIndexSearchFailed({
           cwd,
           queryLength: query.length,
           pageSize,
-          reason: "FileFinder.mixedSearch threw unexpectedly.",
+          reason: `FileFinder.${operation} threw unexpectedly.`,
           cause,
         }),
     });
@@ -273,13 +414,13 @@ export const make = Effect.fn("WorkspaceSearchIndex.make")(function* (cwd: strin
         reason: result.error,
       });
     }
-    yield* waitForScan(
+    yield* waitForIndexReady(
       cwd,
       finder,
-      (cause) =>
+      ({ reason, cause }) =>
         new WorkspaceSearchIndexRefreshFailed({
           cwd,
-          reason: "FileFinder.isScanning threw while refreshing the index.",
+          reason,
           cause,
         }),
     );
@@ -287,7 +428,9 @@ export const make = Effect.fn("WorkspaceSearchIndex.make")(function* (cwd: strin
 
   const list: WorkspaceSearchIndex["Service"]["list"] = Effect.fn("WorkspaceSearchIndex.list")(
     function* () {
-      const result = yield* runMixedSearch("", WORKSPACE_INDEX_PAGE_SIZE);
+      const result = yield* runSearch("", WORKSPACE_INDEX_PAGE_SIZE, "mixedSearch", () =>
+        finder.mixedSearch("", { pageSize: WORKSPACE_INDEX_PAGE_SIZE }),
+      );
       const mapped = mapMixedSearchResult(result, WORKSPACE_INDEX_MAX_ENTRIES);
       const sortedEntries = withDirectoryAncestors(mapped.entries).toSorted((left, right) =>
         left.path.localeCompare(right.path),
@@ -302,20 +445,112 @@ export const make = Effect.fn("WorkspaceSearchIndex.make")(function* (cwd: strin
 
   const search: WorkspaceSearchIndex["Service"]["search"] = Effect.fn(
     "WorkspaceSearchIndex.search",
-  )(function* (query, limit) {
-    const result = yield* runMixedSearch(query, Math.max(1, limit + 1));
+  )(function* (query, limit, kind) {
+    const pageSize = Math.max(1, limit + 1);
+    if (kind === "file") {
+      const result = yield* runSearch(query, pageSize, "fileSearch", () =>
+        finder.fileSearch(query, { pageSize }),
+      );
+      return mapFileSearchResult(result, limit);
+    }
+    if (kind === "directory") {
+      const result = yield* runSearch(query, pageSize, "directorySearch", () =>
+        finder.directorySearch(query, { pageSize }),
+      );
+      return mapDirectorySearchResult(result, limit);
+    }
+    const result = yield* runSearch(query, pageSize, "mixedSearch", () =>
+      finder.mixedSearch(query, { pageSize }),
+    );
     return mapMixedSearchResult(result, limit);
   });
 
-  return WorkspaceSearchIndex.of({ list, refresh, search });
+  const searchContents: WorkspaceSearchIndex["Service"]["searchContents"] = Effect.fn(
+    "WorkspaceSearchIndex.searchContents",
+  )(function* (input) {
+    const { searchQuery, regexMode } = buildContentSearchQuery(input);
+    const deadline = performance.now() + CONTENT_SEARCH_TIME_BUDGET_MS;
+    // Grep cursors advance by file, so whole-word post-filtering needs enough
+    // raw candidates from the current file before moving to the next one.
+    const rawPageSize = input.wholeWord
+      ? Math.max(input.limit, CONTENT_SEARCH_MAX_MATCHES_PER_FILE)
+      : input.limit;
+    const matches: Array<ProjectSearchContentsResult["matches"][number]> = [];
+    let nextCursor: GrepCursor | null = null;
+    let regexFallbackError: string | undefined;
+
+    do {
+      const remainingTimeBudgetMs = Math.max(1, Math.ceil(deadline - performance.now()));
+      const result = yield* runSearch(input.query, input.limit, "grep", () =>
+        finder.grep(searchQuery, {
+          mode: regexMode ? "regex" : "plain",
+          smartCase: !input.caseSensitive && !regexMode,
+          // A single dense file must not consume the whole result page.
+          maxMatchesPerFile: Math.min(CONTENT_SEARCH_MAX_MATCHES_PER_FILE, rawPageSize),
+          pageSize: rawPageSize,
+          cursor: nextCursor,
+          timeBudgetMs: remainingTimeBudgetMs,
+        }),
+      );
+
+      for (const match of result.items) {
+        const matchRanges = mapContentMatchRanges(match.lineContent, match.matchRanges).filter(
+          (range) => !input.wholeWord || isWholeWordRange(match.lineContent, range),
+        );
+        if (matchRanges.length === 0) continue;
+        matches.push({
+          path: toPosixPath(match.relativePath),
+          lineNumber: match.lineNumber,
+          lineContent: match.lineContent,
+          matchRanges,
+        });
+      }
+      nextCursor = result.nextCursor;
+      regexFallbackError ??= result.regexFallbackError;
+    } while (matches.length < input.limit && nextCursor !== null && performance.now() < deadline);
+
+    return {
+      matches: matches.slice(0, input.limit),
+      truncated: matches.length > input.limit || nextCursor !== null,
+      ...(regexFallbackError !== undefined ? { regexFallbackError } : {}),
+    };
+  });
+
+  return WorkspaceSearchIndex.of({ list, refresh, search, searchContents });
 });
 
+export const WORKSPACE_SEARCH_INDEX_VARIANTS = ["paths", "content"] as const;
+export type WorkspaceSearchIndexVariant = (typeof WORKSPACE_SEARCH_INDEX_VARIANTS)[number];
+
+/**
+ * Composite LayerMap key so the lightweight path index and the on-demand
+ * content-search index of the same workspace are separate resources with
+ * independent lifecycles. "\n" cannot appear in a filesystem path.
+ */
+export const workspaceSearchIndexKey = (cwd: string, variant: WorkspaceSearchIndexVariant) =>
+  `${variant}\n${cwd}`;
+
+function parseWorkspaceSearchIndexKey(key: string): {
+  readonly cwd: string;
+  readonly variant: WorkspaceSearchIndexVariant;
+} {
+  const separatorIndex = key.indexOf("\n");
+  return {
+    variant: key.slice(0, separatorIndex) as WorkspaceSearchIndexVariant,
+    cwd: key.slice(separatorIndex + 1),
+  };
+}
+
 /**
  * A layer factory is required because every index is scoped to a concrete
- * workspace root. WorkspaceSearchIndexMap owns memoization and idle cleanup;
- * using a default cwd here would mix resources from different workspaces.
+ * workspace root and variant. WorkspaceSearchIndexMap owns memoization and
+ * idle cleanup; using a default cwd here would mix resources from different
+ * workspaces.
  */
-export const layer = (cwd: string) => Layer.effect(WorkspaceSearchIndex, make(cwd));
+export const layer = (key: string) => {
+  const { cwd, variant } = parseWorkspaceSearchIndexKey(key);
+  return Layer.effect(WorkspaceSearchIndex, make(cwd, variant));
+};
 
 export class WorkspaceSearchIndexMap extends LayerMap.Service<WorkspaceSearchIndexMap>()(
   "t3/workspace/WorkspaceSearchIndexMap",
diff --git a/apps/server/src/ws.ts b/apps/server/src/ws.ts
index 935d7edec92..06888ef3f70 100644
--- a/apps/server/src/ws.ts
+++ b/apps/server/src/ws.ts
@@ -37,6 +37,7 @@ import {
   type ProjectFileOperation,
   ProjectListEntriesError,
   ProjectReadFileError,
+  ProjectSearchContentsError,
   ProjectSearchEntriesError,
   ProjectWriteFileError,
   RelayClientInstallFailedError,
@@ -1597,6 +1598,23 @@ const makeWsRpcLayer = (
             ),
             { "rpc.aggregate": "workspace" },
           ),
+        [WS_METHODS.projectsSearchContents]: (input) =>
+          observeRpcEffect(
+            WS_METHODS.projectsSearchContents,
+            workspaceEntries.searchContents(input).pipe(
+              Effect.mapError(
+                (cause) =>
+                  new ProjectSearchContentsError({
+                    cwd: input.cwd,
+                    queryLength: input.query.length,
+                    limit: input.limit,
+                    ...projectEntriesFailureContext(cause),
+                    cause,
+                  }),
+              ),
+            ),
+            { "rpc.aggregate": "workspace" },
+          ),
         [WS_METHODS.projectsListEntries]: (input) =>
           observeRpcEffect(
             WS_METHODS.projectsListEntries,
diff --git a/apps/web/src/components/ChatMarkdown.tsx b/apps/web/src/components/ChatMarkdown.tsx
index d86fe39a77f..985e943cb39 100644
--- a/apps/web/src/components/ChatMarkdown.tsx
+++ b/apps/web/src/components/ChatMarkdown.tsx
@@ -1,5 +1,4 @@
 import { useAtomValue } from "@effect/atom-react";
-import { DiffsHighlighter, getSharedHighlighter, SupportedLanguages } from "@pierre/diffs";
 import {
   CheckIcon,
   ChevronRightIcon,
@@ -57,6 +56,8 @@ import { useOpenInPreferredEditor } from "../editorPreferences";
 import { resolveDiffThemeName, type DiffThemeName } from "../lib/diffRendering";
 import { fnv1a32 } from "../lib/diffRendering";
 import { LRUCache } from "../lib/lruCache";
+import { getSyntaxHighlighterPromise } from "../lib/syntaxHighlighting";
+import { RenderErrorBoundary } from "./RenderErrorBoundary";
 import { useTheme } from "../hooks/useTheme";
 import { getClientSettings } from "../hooks/useSettings";
 import {
@@ -91,27 +92,6 @@ import {
   BrowserPreviewUnavailableError,
 } from "../browser/openFileInPreview";
 
-class CodeHighlightErrorBoundary extends React.Component<
-  { fallback: ReactNode; children: ReactNode },
-  { hasError: boolean }
-> {
-  constructor(props: { fallback: ReactNode; children: ReactNode }) {
-    super(props);
-    this.state = { hasError: false };
-  }
-
-  static getDerivedStateFromError() {
-    return { hasError: true };
-  }
-
-  override render() {
-    if (this.state.hasError) {
-      return this.props.fallback;
-    }
-    return this.props.children;
-  }
-}
-
 interface ChatMarkdownProps {
   text: string;
   cwd: string | undefined;
@@ -147,7 +127,6 @@ const highlightedCodeCache = new LRUCache<string>(
   MAX_HIGHLIGHT_CACHE_ENTRIES,
   MAX_HIGHLIGHT_CACHE_MEMORY_BYTES,
 );
-const highlighterPromiseCache = new Map<string, Promise<DiffsHighlighter>>();
 
 function findTaskListMarkerOffset(markdown: string, listItemStart: number): number | null {
   const firstLineEnd = markdown.indexOf("\n", listItemStart);
@@ -333,27 +312,6 @@ function estimateHighlightedSize(html: string, code: string): number {
   return Math.max(html.length * 2, code.length * 3);
 }
 
-function getHighlighterPromise(language: string): Promise<DiffsHighlighter> {
-  const cached = highlighterPromiseCache.get(language);
-  if (cached) return cached;
-
-  const promise = getSharedHighlighter({
-    themes: [resolveDiffThemeName("dark"), resolveDiffThemeName("light")],
-    langs: [language as SupportedLanguages],
-    preferredHighlighter: "shiki-js",
-  }).catch((err) => {
-    highlighterPromiseCache.delete(language);
-    if (language === "text") {
-      // "text" itself failed — Shiki cannot initialize at all, surface the error
-      throw err;
-    }
-    // Language not supported by Shiki — fall back to "text"
-    return getHighlighterPromise("text");
-  });
-  highlighterPromiseCache.set(language, promise);
-  return promise;
-}
-
 function readInitialWordWrapSetting(): boolean {
   return getClientSettings().wordWrap;
 }
@@ -743,7 +701,7 @@ function UncachedShikiCodeBlock({
   cacheKey,
   isStreaming,
 }: UncachedShikiCodeBlockProps) {
-  const highlighter = use(getHighlighterPromise(language));
+  const highlighter = use(getSyntaxHighlighterPromise(language));
   const highlightedHtml = useMemo(() => {
     try {
       return highlighter.codeToHtml(code, { lang: language, theme: themeName });
@@ -1605,7 +1563,7 @@ function ChatMarkdown({
             fenceTitle={fenceTitle}
             theme={resolvedTheme}
           >
-            <CodeHighlightErrorBoundary fallback={<pre {...props}>{children}</pre>}>
+            <RenderErrorBoundary fallback={<pre {...props}>{children}</pre>}>
               <Suspense fallback={<pre {...props}>{children}</pre>}>
                 <SuspenseShikiCodeBlock
                   className={codeBlock.className}
@@ -1614,7 +1572,7 @@ function ChatMarkdown({
                   isStreaming={isStreaming}
                 />
               </Suspense>
-            </CodeHighlightErrorBoundary>
+            </RenderErrorBoundary>
           </MarkdownCodeBlock>
         );
       },
diff --git a/apps/web/src/components/CommandPalette.logic.test.ts b/apps/web/src/components/CommandPalette.logic.test.ts
index 5b4accc9fc7..4d591500f5c 100644
--- a/apps/web/src/components/CommandPalette.logic.test.ts
+++ b/apps/web/src/components/CommandPalette.logic.test.ts
@@ -6,9 +6,81 @@ import {
   buildThreadActionItems,
   enumerateCommandPaletteItems,
   filterCommandPaletteGroups,
+  reduceCommandPaletteUiState,
   type CommandPaletteGroup,
 } from "./CommandPalette.logic";
 
+describe("reduceCommandPaletteUiState", () => {
+  const closedState = { open: false, mode: "command", openIntent: null } as const;
+
+  it("toggles each overlay mode open and closed", () => {
+    const filesOpen = reduceCommandPaletteUiState(closedState, {
+      _tag: "ToggleMode",
+      mode: "files",
+    });
+    expect(filesOpen).toEqual({ open: true, mode: "files", openIntent: null });
+
+    const contentOpen = reduceCommandPaletteUiState(filesOpen, {
+      _tag: "ToggleMode",
+      mode: "content",
+    });
+    expect(contentOpen).toEqual({ open: true, mode: "content", openIntent: null });
+
+    expect(
+      reduceCommandPaletteUiState(contentOpen, { _tag: "ToggleMode", mode: "content" }),
+    ).toEqual({ open: false, mode: "command", openIntent: null });
+  });
+
+  it("switches between open modes without closing", () => {
+    const filesOpen = reduceCommandPaletteUiState(closedState, {
+      _tag: "ToggleMode",
+      mode: "files",
+    });
+    expect(reduceCommandPaletteUiState(filesOpen, { _tag: "ToggleMode", mode: "command" })).toEqual(
+      {
+        open: true,
+        mode: "command",
+        openIntent: null,
+      },
+    );
+  });
+
+  it("routes open intents to command mode", () => {
+    const filesOpen = reduceCommandPaletteUiState(closedState, {
+      _tag: "ToggleMode",
+      mode: "files",
+    });
+    expect(reduceCommandPaletteUiState(filesOpen, { _tag: "OpenAddProject" })).toEqual({
+      open: true,
+      mode: "command",
+      openIntent: { kind: "add-project" },
+    });
+    expect(reduceCommandPaletteUiState(filesOpen, { _tag: "OpenNewThreadIn" })).toEqual({
+      open: true,
+      mode: "command",
+      openIntent: { kind: "new-thread-in" },
+    });
+  });
+
+  it("resets to command mode for dialog-driven opens and closes", () => {
+    const filesOpen = reduceCommandPaletteUiState(closedState, {
+      _tag: "ToggleMode",
+      mode: "files",
+    });
+
+    expect(reduceCommandPaletteUiState(filesOpen, { _tag: "SetOpen", open: false })).toEqual({
+      open: false,
+      mode: "command",
+      openIntent: null,
+    });
+    expect(reduceCommandPaletteUiState(filesOpen, { _tag: "SetOpen", open: true })).toEqual({
+      open: true,
+      mode: "command",
+      openIntent: null,
+    });
+  });
+});
+
 describe("enumerateCommandPaletteItems", () => {
   it("assigns positional jump shortcuts to the first nine displayed items", () => {
     const items = Array.from({ length: 10 }, (_, index) => ({
diff --git a/apps/web/src/components/CommandPalette.logic.ts b/apps/web/src/components/CommandPalette.logic.ts
index 7a07cc48481..eee6ba5886e 100644
--- a/apps/web/src/components/CommandPalette.logic.ts
+++ b/apps/web/src/components/CommandPalette.logic.ts
@@ -15,6 +15,55 @@ export const RECENT_THREAD_LIMIT = 12;
 export const ITEM_ICON_CLASS = "size-4 text-muted-foreground/80";
 export const ADDON_ICON_CLASS = "size-4";
 
+/**
+ * The global search overlay hosts three mutually exclusive surfaces: the
+ * command palette (⌘K), the project file picker (⌘P), and project content
+ * search (⇧⌘F). One reducer owns open/mode state so the surfaces can never
+ * stack and re-triggering a mode's shortcut toggles it closed.
+ */
+export type SearchOverlayMode = "command" | "files" | "content";
+
+export interface CommandPaletteOpenIntent {
+  readonly kind: "add-project" | "new-thread-in";
+}
+
+export interface CommandPaletteUiState {
+  readonly open: boolean;
+  readonly mode: SearchOverlayMode;
+  readonly openIntent: CommandPaletteOpenIntent | null;
+}
+
+export type CommandPaletteUiAction =
+  | { readonly _tag: "SetOpen"; readonly open: boolean }
+  | { readonly _tag: "ToggleMode"; readonly mode: SearchOverlayMode }
+  | { readonly _tag: "OpenAddProject" }
+  | { readonly _tag: "OpenNewThreadIn" }
+  | { readonly _tag: "ClearOpenIntent" };
+
+export function reduceCommandPaletteUiState(
+  state: CommandPaletteUiState,
+  action: CommandPaletteUiAction,
+): CommandPaletteUiState {
+  switch (action._tag) {
+    case "SetOpen":
+      return {
+        open: action.open,
+        mode: "command",
+        openIntent: action.open ? state.openIntent : null,
+      };
+    case "ToggleMode":
+      return state.open && state.mode === action.mode
+        ? { open: false, mode: "command", openIntent: null }
+        : { open: true, mode: action.mode, openIntent: null };
+    case "OpenAddProject":
+      return { open: true, mode: "command", openIntent: { kind: "add-project" } };
+    case "OpenNewThreadIn":
+      return { open: true, mode: "command", openIntent: { kind: "new-thread-in" } };
+    case "ClearOpenIntent":
+      return state.openIntent ? { ...state, openIntent: null } : state;
+  }
+}
+
 export interface CommandPaletteThreadContentMatch {
   readonly source: "user" | "assistant";
   readonly snippet: string;
@@ -26,7 +75,7 @@ export interface CommandPaletteItem {
   readonly value: string;
   readonly searchTerms: ReadonlyArray<string>;
   readonly title: ReactNode;
-  readonly description?: string;
+  readonly description?: ReactNode;
   readonly threadContentMatch?: CommandPaletteThreadContentMatch;
   readonly timestamp?: string;
   readonly icon: ReactNode;
diff --git a/apps/web/src/components/CommandPalette.tsx b/apps/web/src/components/CommandPalette.tsx
index 94870fef3eb..853d317655a 100644
--- a/apps/web/src/components/CommandPalette.tsx
+++ b/apps/web/src/components/CommandPalette.tsx
@@ -28,16 +28,16 @@ import {
 import { useNavigate, useParams } from "@tanstack/react-router";
 import * as Option from "effect/Option";
 import {
-  ArrowDownIcon,
   ArrowLeftIcon,
-  ArrowUpIcon,
   CornerLeftUpIcon,
+  FileSearchIcon,
   FolderIcon,
   FolderPlusIcon,
   LinkIcon,
   MessageSquareIcon,
   SettingsIcon,
   SquarePenIcon,
+  TextSearchIcon,
 } from "lucide-react";
 import {
   useCallback,
@@ -81,7 +81,9 @@ import {
   resolveProjectPathForDispatch,
 } from "../lib/projectPaths";
 import { onOpenCommandPalette } from "../commandPaletteBus";
+import { isPreviewFocused } from "../lib/previewFocus";
 import { isTerminalFocused } from "../lib/terminalFocus";
+import { selectActiveRightPanel, useRightPanelStore } from "../rightPanelStore";
 import { getLatestThreadForProject, sortThreads } from "../lib/threadSort";
 import { cn, isMacPlatform, isWindowsPlatform, newProjectId } from "../lib/utils";
 import { selectThreadTerminalUiState, useTerminalUiStateStore } from "../terminalUiStateStore";
@@ -100,6 +102,7 @@ import {
   buildThreadActionItems,
   enumerateCommandPaletteItems,
   type CommandPaletteActionItem,
+  type CommandPaletteOpenIntent,
   type CommandPaletteSubmenuItem,
   type CommandPaletteView,
   filterCommandPaletteGroups,
@@ -107,24 +110,22 @@ import {
   getCommandPaletteMode,
   ITEM_ICON_CLASS,
   RECENT_THREAD_LIMIT,
+  reduceCommandPaletteUiState,
+  type SearchOverlayMode,
 } from "./CommandPalette.logic";
 import { orderItemsByPreferredIds, sortLogicalProjectsForSidebar } from "./Sidebar.logic";
 import { resolveEnvironmentOptionLabel } from "./BranchToolbar.logic";
+import { CommandPaletteContent } from "./CommandPaletteContent";
 import { CommandPaletteResults } from "./CommandPaletteResults";
 import { AzureDevOpsIcon, BitbucketIcon, GitHubIcon, GitLabIcon } from "./Icons";
 import { ProjectFavicon } from "./ProjectFavicon";
+import { ProjectFilePicker } from "./files/ProjectFilePicker";
+import { ProjectContentSearchDialog } from "./search/ProjectContentSearchDialog";
 import { ThreadRowLeadingStatus, ThreadRowTrailingStatus } from "./ThreadStatusIndicators";
 import { primaryServerKeybindingsAtom, primaryServerProvidersAtom } from "../state/server";
 import { resolveDefaultProviderModelSelection } from "../providerInstances";
 import { resolveShortcutCommand, threadJumpIndexFromCommand } from "../keybindings";
-import {
-  Command,
-  CommandDialog,
-  CommandDialogPopup,
-  CommandFooter,
-  CommandInput,
-  CommandPanel,
-} from "./ui/command";
+import { CommandDialog, CommandDialogPopup } from "./ui/command";
 import { Button } from "./ui/button";
 import { Kbd, KbdGroup } from "./ui/kbd";
 import { stackedThreadToast, toastManager } from "./ui/toast";
@@ -346,50 +347,30 @@ function errorMessage(error: unknown): string {
   return "An error occurred.";
 }
 
-interface CommandPaletteOpenIntent {
-  readonly kind: "add-project" | "new-thread-in";
-}
-
-interface CommandPaletteUiState {
-  readonly open: boolean;
-  readonly openIntent: CommandPaletteOpenIntent | null;
-}
+const OVERLAY_MODE_BY_COMMAND = {
+  "commandPalette.toggle": "command",
+  "filePicker.toggle": "files",
+  "projectSearch.toggle": "content",
+} as const satisfies Partial<Record<string, SearchOverlayMode>>;
 
-type CommandPaletteUiAction =
-  | { readonly _tag: "SetOpen"; readonly open: boolean }
-  | { readonly _tag: "Toggle" }
-  | { readonly _tag: "OpenAddProject" }
-  | { readonly _tag: "OpenNewThreadIn" }
-  | { readonly _tag: "ClearOpenIntent" };
-
-function reduceCommandPaletteUiState(
-  state: CommandPaletteUiState,
-  action: CommandPaletteUiAction,
-): CommandPaletteUiState {
-  switch (action._tag) {
-    case "SetOpen":
-      return {
-        open: action.open,
-        openIntent: action.open ? state.openIntent : null,
-      };
-    case "Toggle":
-      return { open: !state.open, openIntent: null };
-    case "OpenAddProject":
-      return { open: true, openIntent: { kind: "add-project" } };
-    case "OpenNewThreadIn":
-      return { open: true, openIntent: { kind: "new-thread-in" } };
-    case "ClearOpenIntent":
-      return state.openIntent ? { ...state, openIntent: null } : state;
-  }
+function overlayModeForCommand(command: string | null): SearchOverlayMode | null {
+  if (command === null) return null;
+  return command in OVERLAY_MODE_BY_COMMAND
+    ? OVERLAY_MODE_BY_COMMAND[command as keyof typeof OVERLAY_MODE_BY_COMMAND]
+    : null;
 }
 
 export function CommandPalette({ children }: { children: ReactNode }) {
   const [state, dispatch] = useReducer(reduceCommandPaletteUiState, {
     open: false,
+    mode: "command",
     openIntent: null,
   });
   const setOpen = useCallback((open: boolean) => dispatch({ _tag: "SetOpen", open }), []);
-  const toggleOpen = useCallback(() => dispatch({ _tag: "Toggle" }), []);
+  const toggleMode = useCallback(
+    (mode: SearchOverlayMode) => dispatch({ _tag: "ToggleMode", mode }),
+    [],
+  );
   const openAddProject = useCallback(() => dispatch({ _tag: "OpenAddProject" }), []);
   const openNewThreadIn = useCallback(() => dispatch({ _tag: "OpenNewThreadIn" }), []);
   const clearOpenIntent = useCallback(() => dispatch({ _tag: "ClearOpenIntent" }), []);
@@ -405,26 +386,48 @@ export function CommandPalette({ children }: { children: ReactNode }) {
       ? selectThreadTerminalUiState(state.terminalUiStateByThreadKey, routeThreadRef).terminalOpen
       : false,
   );
+  const previewOpen = useRightPanelStore((state) =>
+    routeThreadRef
+      ? selectActiveRightPanel(state.byThreadKey, routeThreadRef) === "preview"
+      : false,
+  );
+
+  useEffect(() => {
+    if (!state.open || state.mode === "command") return;
+    const onEscapeKeyDown = (event: globalThis.KeyboardEvent) => {
+      if (event.isComposing || event.key !== "Escape") return;
+      event.preventDefault();
+      event.stopPropagation();
+      toggleMode("command");
+    };
+    window.addEventListener("keydown", onEscapeKeyDown, true);
+    return () => window.removeEventListener("keydown", onEscapeKeyDown, true);
+  }, [state.mode, state.open, toggleMode]);
 
   useEffect(() => {
     const onKeyDown = (event: globalThis.KeyboardEvent) => {
       if (event.defaultPrevented) return;
+      // Resolve with the complete shortcut context so customized bindings
+      // using any documented `when` condition (e.g. previewFocus) work.
       const command = resolveShortcutCommand(event, keybindings, {
         context: {
           terminalFocus: isTerminalFocused(),
           terminalOpen,
+          previewFocus: isPreviewFocused(),
+          previewOpen,
         },
       });
-      if (command !== "commandPalette.toggle") {
+      const mode = overlayModeForCommand(command);
+      if (mode === null) {
         return;
       }
       event.preventDefault();
       event.stopPropagation();
-      toggleOpen();
+      toggleMode(mode);
     };
     window.addEventListener("keydown", onKeyDown);
     return () => window.removeEventListener("keydown", onKeyDown);
-  }, [keybindings, terminalOpen, toggleOpen]);
+  }, [keybindings, previewOpen, terminalOpen, toggleMode]);
 
   useEffect(
     () =>
@@ -442,12 +445,24 @@ export function CommandPalette({ children }: { children: ReactNode }) {
 
   return (
     <ComposerHandleContext value={composerHandleRef}>
-      <CommandDialog open={state.open} onOpenChange={setOpen}>
+      <CommandDialog
+        open={state.open}
+        onOpenChange={(open, eventDetails) => {
+          if (!open && eventDetails.reason === "escape-key" && state.mode !== "command") {
+            eventDetails.cancel();
+            toggleMode("command");
+            return;
+          }
+          setOpen(open);
+        }}
+      >
         {children}
         <CommandPaletteDialog
           open={state.open}
+          mode={state.mode}
           openIntent={state.openIntent}
           setOpen={setOpen}
+          openOverlayMode={toggleMode}
           clearOpenIntent={clearOpenIntent}
         />
       </CommandDialog>
@@ -457,31 +472,63 @@ export function CommandPalette({ children }: { children: ReactNode }) {
 
 function CommandPaletteDialog(props: {
   readonly open: boolean;
+  readonly mode: SearchOverlayMode;
   readonly openIntent: CommandPaletteOpenIntent | null;
   readonly setOpen: (open: boolean) => void;
+  readonly openOverlayMode: (mode: SearchOverlayMode) => void;
   readonly clearOpenIntent: () => void;
 }) {
+  const composerHandleRef = useComposerHandleContext();
+
   if (!props.open) {
     return null;
   }
 
   return (
-    <OpenCommandPaletteDialog
-      openIntent={props.openIntent}
-      setOpen={props.setOpen}
-      clearOpenIntent={props.clearOpenIntent}
-    />
+    <CommandDialogPopup
+      aria-label={
+        props.mode === "files"
+          ? "File picker"
+          : props.mode === "content"
+            ? "Search project contents"
+            : "Command palette"
+      }
+      className={cn("overflow-hidden p-0", props.mode === "content" && "h-105")}
+      data-command-palette="true"
+      data-palette-mode={props.mode}
+      data-testid="command-palette"
+      finalFocus={() => {
+        composerHandleRef?.current?.focusAtEnd();
+        return false;
+      }}
+      onBackdropPointerDown={() => {
+        props.setOpen(false);
+      }}
+    >
+      {props.mode === "files" ? (
+        <ProjectFilePicker setOpen={props.setOpen} />
+      ) : props.mode === "content" ? (
+        <ProjectContentSearchDialog onOpenChange={props.setOpen} />
+      ) : (
+        <OpenCommandPaletteDialog
+          openIntent={props.openIntent}
+          setOpen={props.setOpen}
+          openOverlayMode={props.openOverlayMode}
+          clearOpenIntent={props.clearOpenIntent}
+        />
+      )}
+    </CommandDialogPopup>
   );
 }
 
 function OpenCommandPaletteDialog(props: {
   readonly openIntent: CommandPaletteOpenIntent | null;
   readonly setOpen: (open: boolean) => void;
+  readonly openOverlayMode: (mode: SearchOverlayMode) => void;
   readonly clearOpenIntent: () => void;
 }) {
   const navigate = useNavigate();
-  const { clearOpenIntent, openIntent, setOpen } = props;
-  const composerHandleRef = useComposerHandleContext();
+  const { clearOpenIntent, openIntent, openOverlayMode, setOpen } = props;
   const [query, setQuery] = useState("");
   const deferredQuery = useDeferredValue(query);
   const isActionsOnly = deferredQuery.startsWith(">");
@@ -1346,6 +1393,32 @@ function OpenCommandPaletteDialog(props: {
     });
   }
 
+  actionItems.push({
+    kind: "action",
+    value: "action:open-file-picker",
+    searchTerms: ["go to file", "open file", "file picker", "find file", "quick open"],
+    title: "Go to file",
+    icon: <FileSearchIcon className={ITEM_ICON_CLASS} />,
+    keepOpen: true,
+    shortcutCommand: "filePicker.toggle",
+    run: async () => {
+      openOverlayMode("files");
+    },
+  });
+
+  actionItems.push({
+    kind: "action",
+    value: "action:search-project-contents",
+    searchTerms: ["search project", "find in files", "grep", "content search", "text search"],
+    title: "Search project contents",
+    icon: <TextSearchIcon className={ITEM_ICON_CLASS} />,
+    keepOpen: true,
+    shortcutCommand: "projectSearch.toggle",
+    run: async () => {
+      openOverlayMode("content");
+    },
+  });
+
   actionItems.push({
     kind: "action",
     value: "action:add-project",
@@ -2062,236 +2135,189 @@ function OpenCommandPaletteDialog(props: {
     primaryEnvironmentId,
   ]);
 
+  const inputAccessory =
+    addProjectCloneFlow?.step === "repository" ? (
+      <Tooltip>
+        <TooltipTrigger
+          render={
+            <Button
+              variant="outline"
+              size="xs"
+              tabIndex={-1}
+              className="absolute inset-e-2.5 top-1/2 gap-1.5 pe-1 ps-2 -translate-y-1/2"
+              aria-label={`${remoteProjectButtonLabel ?? "Continue"} (Enter)`}
+              disabled={!canSubmitRemoteProjectFlow}
+              onMouseDown={(event) => {
+                event.preventDefault();
+              }}
+              onClick={() => {
+                void submitAddProjectCloneFlow();
+              }}
+            />
+          }
+        >
+          <span>{isRemoteProjectPending ? "Working" : remoteProjectButtonLabel}</span>
+          <KbdGroup className="pointer-events-none -me-0.5 items-center gap-1">
+            <Kbd>Enter</Kbd>
+          </KbdGroup>
+        </TooltipTrigger>
+        <TooltipPopup side="top">{remoteProjectButtonLabel ?? "Continue"} (Enter)</TooltipPopup>
+      </Tooltip>
+    ) : isBrowsing ? (
+      <Tooltip>
+        <TooltipTrigger
+          render={
+            <Button
+              variant="outline"
+              size="xs"
+              tabIndex={-1}
+              className={cn(
+                "absolute inset-e-2.5 top-1/2 pe-1 ps-2 -translate-y-1/2",
+                hasHighlightedBrowseItem ? "gap-1" : "gap-1.5",
+              )}
+              aria-label={`${submitActionLabel} (${addShortcutLabel})`}
+              disabled={
+                !canCreateProjectInEnvironment(browseEnvironment?.connection.phase) ||
+                relativePathNeedsActiveProject ||
+                (isCloneDestinationStep && isRemoteProjectPending)
+              }
+              onMouseDown={(event) => {
+                event.preventDefault();
+              }}
+              onClick={() => {
+                if (relativePathNeedsActiveProject) {
+                  return;
+                }
+                if (isCloneDestinationStep) {
+                  void submitAddProjectCloneFlow(resolvedAddProjectPath);
+                } else {
+                  void handleAddProject(resolvedAddProjectPath);
+                }
+              }}
+            />
+          }
+        >
+          <span>
+            {isCloneDestinationStep && isRemoteProjectPending ? "Cloning" : submitActionLabel}
+          </span>
+          <KbdGroup className="pointer-events-none -me-0.5 items-center gap-1">
+            <Kbd>{hasHighlightedBrowseItem ? `${submitModifierLabel} Enter` : "Enter"}</Kbd>
+          </KbdGroup>
+        </TooltipTrigger>
+        <TooltipPopup side="top">
+          {submitActionLabel} ({addShortcutLabel})
+        </TooltipPopup>
+      </Tooltip>
+    ) : null;
+
+  const footerActionLabel =
+    addProjectCloneFlow?.step === "repository"
+      ? (remoteProjectButtonLabel ?? "Continue")
+      : !canSubmitBrowsePath || hasHighlightedBrowseItem
+        ? "Select"
+        : undefined;
+
+  const footerTrailing = canOpenProjectFromFileManager ? (
+    <Button
+      variant="ghost"
+      size="xs"
+      className="h-auto px-2 text-muted-foreground text-xs hover:bg-transparent hover:text-foreground"
+      disabled={isPickingProjectFolder}
+      onClick={() => {
+        void handleOpenProjectFromFileManager();
+      }}
+    >
+      {`Open in ${fileManagerName}`}
+    </Button>
+  ) : null;
+
   return (
-    <CommandDialogPopup
+    <CommandPaletteContent
+      key={`${viewStack.length}-${browseGeneration}-${isBrowsing}-${addProjectCloneFlow?.step ?? "none"}`}
       aria-label="Command palette"
-      className="overflow-hidden p-0"
-      data-command-palette="true"
-      data-testid="command-palette"
-      finalFocus={() => {
-        composerHandleRef?.current?.focusAtEnd();
-        return false;
+      autoHighlight={isBrowsing || isRemoteProjectCloneFlow ? false : "always"}
+      footerActionLabel={footerActionLabel}
+      footerTrailing={footerTrailing}
+      inputAccessory={inputAccessory}
+      inputProps={{
+        className:
+          addProjectCloneFlow?.step === "repository"
+            ? "pe-32"
+            : isBrowsing
+              ? willCreateProjectPath
+                ? "pe-36"
+                : "pe-16"
+              : undefined,
+        placeholder: inputPlaceholder,
+        wrapperClassName: isSubmenu
+          ? "[&_[data-slot=autocomplete-start-addon]]:pointer-events-auto"
+          : undefined,
+        ...(isSubmenu
+          ? {
+              startAddon: (
+                <button
+                  type="button"
+                  className="flex cursor-pointer items-center"
+                  aria-label="Back"
+                  onClick={popView}
+                >
+                  <ArrowLeftIcon />
+                </button>
+              ),
+            }
+          : isBrowsing
+            ? { startAddon: <FolderPlusIcon /> }
+            : {}),
+        onKeyDown: handleKeyDown,
       }}
-      onBackdropPointerDown={() => {
-        setOpen(false);
+      mode="none"
+      onItemHighlighted={(value) => {
+        setHighlightedItemValue(typeof value === "string" ? value : null);
       }}
+      onValueChange={handleQueryChange}
+      panelClassName="max-h-[min(28rem,70vh)]"
+      showBackHint={isSubmenu}
+      value={query}
     >
-      <Command
-        key={`${viewStack.length}-${browseGeneration}-${isBrowsing}-${addProjectCloneFlow?.step ?? "none"}`}
-        aria-label="Command palette"
-        autoHighlight={isBrowsing || isRemoteProjectCloneFlow ? false : "always"}
-        mode="none"
-        onItemHighlighted={(value) => {
-          setHighlightedItemValue(typeof value === "string" ? value : null);
-        }}
-        onValueChange={handleQueryChange}
-        value={query}
-      >
-        <div className="relative">
-          <CommandInput
-            className={
-              addProjectCloneFlow?.step === "repository"
-                ? "pe-32"
-                : isBrowsing
-                  ? willCreateProjectPath
-                    ? "pe-36"
-                    : "pe-16"
-                  : undefined
-            }
-            placeholder={inputPlaceholder}
-            wrapperClassName={
-              isSubmenu ? "[&_[data-slot=autocomplete-start-addon]]:pointer-events-auto" : undefined
+      {remoteProjectContext ? (
+        <div className="p-2 pb-0">
+          <div className="px-2 py-1.5 font-medium text-muted-foreground text-xs">Repository</div>
+          <div className="flex min-h-8 items-center gap-2 rounded-sm px-2 py-1.5">
+            {remoteProjectContext.icon}
+            <span className="flex min-w-0 flex-1 flex-col">
+              <span className="truncate text-foreground text-sm">{remoteProjectContext.title}</span>
+              <span className="truncate text-muted-foreground/85 text-xs">
+                {remoteProjectContext.description}
+              </span>
+            </span>
+          </div>
+        </div>
+      ) : null}
+      <CommandPaletteResults
+        groups={displayedGroups}
+        highlightedItemValue={highlightedItemValue}
+        isActionsOnly={isActionsOnly}
+        keybindings={keybindings}
+        onExecuteItem={executeItem}
+        {...(addProjectCloneFlow?.step === "repository"
+          ? {
+              emptyStateMessage:
+                addProjectCloneFlow.source === "url"
+                  ? "Enter a Git clone URL and press Enter to continue."
+                  : "Enter a repository path and press Enter to look it up.",
             }
-            {...(isSubmenu
-              ? {
-                  startAddon: (
-                    <button
-                      type="button"
-                      className="flex cursor-pointer items-center"
-                      aria-label="Back"
-                      onClick={popView}
-                    >
-                      <ArrowLeftIcon />
-                    </button>
-                  ),
-                }
-              : isBrowsing && !isSubmenu
+          : addProjectCloneFlow?.step === "confirm"
+            ? { emptyStateMessage: "Choose a destination path and press Enter to clone." }
+            : relativePathNeedsActiveProject
+              ? { emptyStateMessage: "Relative paths require an active project." }
+              : willCreateProjectPath
                 ? {
-                    startAddon: <FolderPlusIcon />,
+                    emptyStateMessage: "Press Enter to create this folder and add it as a project.",
                   }
-                : {})}
-            onKeyDown={handleKeyDown}
-          />
-          {addProjectCloneFlow?.step === "repository" ? (
-            <Tooltip>
-              <TooltipTrigger
-                render={
-                  <Button
-                    variant="outline"
-                    size="xs"
-                    tabIndex={-1}
-                    className="absolute inset-e-2.5 top-1/2 gap-1.5 pe-1 ps-2 -translate-y-1/2"
-                    aria-label={`${remoteProjectButtonLabel ?? "Continue"} (Enter)`}
-                    disabled={!canSubmitRemoteProjectFlow}
-                    onMouseDown={(event) => {
-                      event.preventDefault();
-                    }}
-                    onClick={() => {
-                      void submitAddProjectCloneFlow();
-                    }}
-                  />
-                }
-              >
-                <span>{isRemoteProjectPending ? "Working" : remoteProjectButtonLabel}</span>
-                <KbdGroup className="pointer-events-none -me-0.5 items-center gap-1">
-                  <Kbd>Enter</Kbd>
-                </KbdGroup>
-              </TooltipTrigger>
-              <TooltipPopup side="top">
-                {remoteProjectButtonLabel ?? "Continue"} (Enter)
-              </TooltipPopup>
-            </Tooltip>
-          ) : isBrowsing ? (
-            <Tooltip>
-              <TooltipTrigger
-                render={
-                  <Button
-                    variant="outline"
-                    size="xs"
-                    tabIndex={-1}
-                    className={cn(
-                      "absolute inset-e-2.5 top-1/2 pe-1 ps-2 -translate-y-1/2",
-                      hasHighlightedBrowseItem ? "gap-1" : "gap-1.5",
-                    )}
-                    aria-label={`${submitActionLabel} (${addShortcutLabel})`}
-                    disabled={
-                      !canCreateProjectInEnvironment(browseEnvironment?.connection.phase) ||
-                      relativePathNeedsActiveProject ||
-                      (isCloneDestinationStep && isRemoteProjectPending)
-                    }
-                    onMouseDown={(event) => {
-                      event.preventDefault();
-                    }}
-                    onClick={() => {
-                      if (relativePathNeedsActiveProject) {
-                        return;
-                      }
-                      if (isCloneDestinationStep) {
-                        void submitAddProjectCloneFlow(resolvedAddProjectPath);
-                      } else {
-                        void handleAddProject(resolvedAddProjectPath);
-                      }
-                    }}
-                  />
-                }
-              >
-                <span>
-                  {isCloneDestinationStep && isRemoteProjectPending ? "Cloning" : submitActionLabel}
-                </span>
-                <KbdGroup className="pointer-events-none -me-0.5 items-center gap-1">
-                  <Kbd>{hasHighlightedBrowseItem ? `${submitModifierLabel} Enter` : "Enter"}</Kbd>
-                </KbdGroup>
-              </TooltipTrigger>
-              <TooltipPopup side="top">
-                {submitActionLabel} ({addShortcutLabel})
-              </TooltipPopup>
-            </Tooltip>
-          ) : null}
-        </div>
-        <CommandPanel className="max-h-[min(28rem,70vh)]">
-          {remoteProjectContext ? (
-            <div className="p-2 pb-0">
-              <div className="px-2 py-1.5 font-medium text-muted-foreground text-xs">
-                Repository
-              </div>
-              <div className="flex min-h-8 items-center gap-2 rounded-sm px-2 py-1.5">
-                {remoteProjectContext.icon}
-                <span className="flex min-w-0 flex-1 flex-col">
-                  <span className="truncate text-foreground text-sm">
-                    {remoteProjectContext.title}
-                  </span>
-                  <span className="truncate text-muted-foreground/85 text-xs">
-                    {remoteProjectContext.description}
-                  </span>
-                </span>
-              </div>
-            </div>
-          ) : null}
-          <CommandPaletteResults
-            groups={displayedGroups}
-            highlightedItemValue={highlightedItemValue}
-            isActionsOnly={isActionsOnly}
-            keybindings={keybindings}
-            onExecuteItem={executeItem}
-            {...(addProjectCloneFlow?.step === "repository"
-              ? {
-                  emptyStateMessage:
-                    addProjectCloneFlow.source === "url"
-                      ? "Enter a Git clone URL and press Enter to continue."
-                      : "Enter a repository path and press Enter to look it up.",
-                }
-              : addProjectCloneFlow?.step === "confirm"
-                ? { emptyStateMessage: "Choose a destination path and press Enter to clone." }
-                : relativePathNeedsActiveProject
-                  ? { emptyStateMessage: "Relative paths require an active project." }
-                  : willCreateProjectPath
-                    ? {
-                        emptyStateMessage:
-                          "Press Enter to create this folder and add it as a project.",
-                      }
-                    : threadSearch.isPending
-                      ? { emptyStateMessage: "Searching thread messages…" }
-                      : {})}
-          />
-        </CommandPanel>
-        <CommandFooter className="gap-3 max-sm:flex-col max-sm:items-start">
-          <div className="flex items-center gap-3">
-            <KbdGroup className="items-center gap-1.5">
-              <Kbd>
-                <ArrowUpIcon />
-              </Kbd>
-              <Kbd>
-                <ArrowDownIcon />
-              </Kbd>
-              <span>Navigate</span>
-            </KbdGroup>
-            {addProjectCloneFlow?.step === "repository" ? (
-              <KbdGroup className="items-center gap-1.5">
-                <Kbd>Enter</Kbd>
-                <span>{remoteProjectButtonLabel ?? "Continue"}</span>
-              </KbdGroup>
-            ) : !canSubmitBrowsePath || hasHighlightedBrowseItem ? (
-              <KbdGroup className="items-center gap-1.5">
-                <Kbd>Enter</Kbd>
-                <span>Select</span>
-              </KbdGroup>
-            ) : null}
-            {isSubmenu ? (
-              <KbdGroup className="items-center gap-1.5">
-                <Kbd>Backspace</Kbd>
-                <span>Back</span>
-              </KbdGroup>
-            ) : null}
-            <KbdGroup className="items-center gap-1.5">
-              <Kbd>Esc</Kbd>
-              <span>Close</span>
-            </KbdGroup>
-          </div>
-          {canOpenProjectFromFileManager ? (
-            <Button
-              variant="ghost"
-              size="xs"
-              className="h-auto px-2 text-muted-foreground text-xs hover:bg-transparent hover:text-foreground"
-              disabled={isPickingProjectFolder}
-              onClick={() => {
-                void handleOpenProjectFromFileManager();
-              }}
-            >
-              {`Open in ${fileManagerName}`}
-            </Button>
-          ) : null}
-        </CommandFooter>
-      </Command>
-    </CommandDialogPopup>
+                : threadSearch.isPending
+                  ? { emptyStateMessage: "Searching thread messages…" }
+                  : {})}
+      />
+    </CommandPaletteContent>
   );
 }
diff --git a/apps/web/src/components/CommandPaletteContent.tsx b/apps/web/src/components/CommandPaletteContent.tsx
new file mode 100644
index 00000000000..af3c1b67170
--- /dev/null
+++ b/apps/web/src/components/CommandPaletteContent.tsx
@@ -0,0 +1,77 @@
+import { ArrowDownIcon, ArrowUpIcon } from "lucide-react";
+import type { ComponentProps, ReactNode } from "react";
+
+import { Command, CommandFooter, CommandInput, CommandPanel } from "./ui/command";
+import { Kbd, KbdGroup } from "./ui/kbd";
+
+type CommandPaletteContentProps = Omit<ComponentProps<typeof Command>, "children"> & {
+  readonly children: ReactNode;
+  readonly escapeLabel?: ReactNode;
+  readonly footerActionLabel?: ReactNode;
+  readonly footerTrailing?: ReactNode;
+  readonly inputAccessory?: ReactNode;
+  readonly inputProps: ComponentProps<typeof CommandInput>;
+  readonly panelClassName?: string;
+  readonly showBackHint?: boolean;
+  readonly testId?: string;
+};
+
+/**
+ * Shared command palette chrome. Palette modes provide their query behavior,
+ * results, and optional input accessory while retaining one input, panel, and
+ * keyboard-hint gutter.
+ */
+export function CommandPaletteContent({
+  children,
+  escapeLabel = "Close",
+  footerActionLabel,
+  footerTrailing,
+  inputAccessory,
+  inputProps,
+  panelClassName,
+  showBackHint,
+  testId,
+  ...commandProps
+}: CommandPaletteContentProps) {
+  return (
+    <div className="contents" data-testid={testId}>
+      <Command {...commandProps}>
+        <div className="relative">
+          <CommandInput {...inputProps} />
+          {inputAccessory}
+        </div>
+        <CommandPanel className={panelClassName}>{children}</CommandPanel>
+        <CommandFooter className="gap-3 max-sm:flex-col max-sm:items-start">
+          <div className="flex items-center gap-3">
+            <KbdGroup className="items-center gap-1.5">
+              <Kbd>
+                <ArrowUpIcon />
+              </Kbd>
+              <Kbd>
+                <ArrowDownIcon />
+              </Kbd>
+              <span>Navigate</span>
+            </KbdGroup>
+            {footerActionLabel !== undefined ? (
+              <KbdGroup className="items-center gap-1.5">
+                <Kbd>Enter</Kbd>
+                <span>{footerActionLabel}</span>
+              </KbdGroup>
+            ) : null}
+            {showBackHint ? (
+              <KbdGroup className="items-center gap-1.5">
+                <Kbd>Backspace</Kbd>
+                <span>Back</span>
+              </KbdGroup>
+            ) : null}
+            <KbdGroup className="items-center gap-1.5">
+              <Kbd>Esc</Kbd>
+              <span>{escapeLabel}</span>
+            </KbdGroup>
+          </div>
+          {footerTrailing}
+        </CommandFooter>
+      </Command>
+    </div>
+  );
+}
diff --git a/apps/web/src/components/RenderErrorBoundary.tsx b/apps/web/src/components/RenderErrorBoundary.tsx
new file mode 100644
index 00000000000..29f7d612d94
--- /dev/null
+++ b/apps/web/src/components/RenderErrorBoundary.tsx
@@ -0,0 +1,16 @@
+import { Component, type ReactNode } from "react";
+
+export class RenderErrorBoundary extends Component<
+  { readonly children: ReactNode; readonly fallback: ReactNode },
+  { readonly failed: boolean }
+> {
+  override state = { failed: false };
+
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+
+  override render() {
+    return this.state.failed ? this.props.fallback : this.props.children;
+  }
+}
diff --git a/apps/web/src/components/files/FileBrowserPanel.tsx b/apps/web/src/components/files/FileBrowserPanel.tsx
index 307d4413751..ff658693a70 100644
--- a/apps/web/src/components/files/FileBrowserPanel.tsx
+++ b/apps/web/src/components/files/FileBrowserPanel.tsx
@@ -26,6 +26,10 @@ interface FileBrowserPanelProps {
   environmentId: EnvironmentId;
   cwd: string;
   projectName: string;
+  /** File currently open in the preview pane; revealed and selected in the tree. */
+  selectedPath: string | null;
+  /** Bumped when the same path should be revealed again (e.g. re-opened from search). */
+  selectedPathRevealId: number;
   onOpenFile: (relativePath: string) => void;
 }
 
@@ -98,6 +102,8 @@ export default function FileBrowserPanel({
   environmentId,
   cwd,
   projectName,
+  selectedPath,
+  selectedPathRevealId,
   onOpenFile,
 }: FileBrowserPanelProps) {
   const { resolvedTheme } = useTheme();
@@ -111,6 +117,9 @@ export default function FileBrowserPanel({
   const entryKindsRef = useRef<ReadonlyMap<string, ProjectEntry["kind"]>>(entryKinds);
   const treePaths = useMemo(() => entries.map(treePath), [entries]);
   const previousTreePathsRef = useRef<readonly string[]>([]);
+  const syncingSelectionRef = useRef(false);
+  const treeSelectionPathRef = useRef<string | null>(null);
+  const handledRevealRef = useRef<{ path: string; revealId: number } | null>(null);
 
   // The tree renders rows in shadow DOM and its anchor rect is unreliable, so
   // capture the right-click position ourselves; contextmenu is a composed
@@ -216,7 +225,12 @@ export default function FileBrowserPanel({
     initialExpansion: 1,
     icons: T3_PIERRE_ICONS,
     onSelectionChange: (selectedPaths) => {
+      // The drag controller's selection cache must track every change,
+      // including reveal-driven ones, or drags act on a stale selection.
       dragMention.handleSelectionChange(selectedPaths);
+      // Selection changes driven by the reveal sync below are echoes of an
+      // already-open file, not a request to open it again.
+      if (syncingSelectionRef.current) return;
       // Starting a drag selects the dragged row; that selection is a side
       // effect of the gesture, not a request to open the file.
       if (dragMention.isDragInProgress()) {
@@ -224,6 +238,7 @@ export default function FileBrowserPanel({
       }
       const selectedPath = selectedPaths.at(-1)?.replace(/\/$/, "");
       if (selectedPath && entryKindsRef.current.get(selectedPath) === "file") {
+        treeSelectionPathRef.current = selectedPath;
         onOpenFile(selectedPath);
       }
     },
@@ -247,6 +262,63 @@ export default function FileBrowserPanel({
     model.resetPaths(treePaths);
   }, [entryKinds, model, treePaths]);
 
+  useEffect(() => {
+    if (!selectedPath) {
+      handledRevealRef.current = null;
+      return;
+    }
+    const revealRequest = { path: selectedPath, revealId: selectedPathRevealId };
+    const handledReveal = handledRevealRef.current;
+    // Entry refreshes rebuild treePaths while the same preview stays open.
+    // Replaying a handled reveal would close an active tree search and steal focus.
+    if (
+      handledReveal?.path === revealRequest.path &&
+      handledReveal.revealId === revealRequest.revealId
+    ) {
+      return;
+    }
+    if (entryKinds.get(selectedPath) !== "file") return;
+    const selectedItem = model.getItem(selectedPath);
+    if (!selectedItem) return;
+
+    // A selection that originated inside the tree (clicking a row, possibly
+    // in an active tree search) is already visible; re-revealing it would
+    // close the search and clobber the user's context. Only sync external
+    // opens (file picker, content search, chat links).
+    const selectedInTree = model
+      .getSelectedPaths()
+      .some((path) => path.replace(/\/$/, "") === selectedPath);
+    if (selectedInTree && treeSelectionPathRef.current === selectedPath) {
+      treeSelectionPathRef.current = null;
+      handledRevealRef.current = revealRequest;
+      return;
+    }
+    treeSelectionPathRef.current = null;
+    handledRevealRef.current = revealRequest;
+
+    syncingSelectionRef.current = true;
+    model.closeSearch();
+    for (const path of model.getSelectedPaths()) {
+      model.getItem(path)?.deselect();
+    }
+
+    // Directory rows are registered with a trailing slash (see treePath), so
+    // ancestor lookups must use the same form to expand them.
+    const segments = selectedPath.split("/");
+    let ancestorPath = "";
+    for (const segment of segments.slice(0, -1)) {
+      ancestorPath = ancestorPath ? `${ancestorPath}/${segment}` : segment;
+      const item = model.getItem(`${ancestorPath}/`) ?? model.getItem(ancestorPath);
+      if (item && "expand" in item) item.expand();
+    }
+
+    selectedItem.select();
+    model.scrollToPath(selectedPath, { focus: true, offset: "center" });
+    queueMicrotask(() => {
+      syncingSelectionRef.current = false;
+    });
+  }, [entryKinds, model, selectedPath, selectedPathRevealId, treePaths]);
+
   // Tag tree drags with the composer mention payload. The row is read from
   // the composed event path (the tree's shadow root is open), so this does
   // not depend on running after the tree's own dragstart handler; the drag
diff --git a/apps/web/src/components/files/FilePreviewPanel.tsx b/apps/web/src/components/files/FilePreviewPanel.tsx
index 24e63a6d8ea..a736cf96cd3 100644
--- a/apps/web/src/components/files/FilePreviewPanel.tsx
+++ b/apps/web/src/components/files/FilePreviewPanel.tsx
@@ -51,6 +51,7 @@ import {
   remapFileCommentAnnotations,
 } from "./fileCommentAnnotations";
 import { installFileEditorDismissal } from "./fileEditorDismissal";
+import { resolveCenteredFileLineScrollTop } from "./fileLineReveal";
 import { LocalCommentAnnotation } from "./LocalCommentAnnotation";
 import { projectFileCacheKey, projectFileEditorCacheKey } from "./fileContentRevision";
 import { fileBreadcrumbs } from "./filePath";
@@ -182,25 +183,53 @@ function updateFileLinkReveal(fileContainer: HTMLElement, line: number | null):
     ?.setAttribute(FILE_LINK_REVEAL_ATTRIBUTE, "");
 }
 
+/**
+ * Frames to keep retrying while the file contents or line metrics are not
+ * available yet (fresh mounts hydrate asynchronously).
+ */
+const REVEAL_MAX_ATTEMPTS = 30;
+/**
+ * After scrolling to the target, hold it for a short window so late
+ * programmatic scroll resets (editable-editor focus and state restoration)
+ * cannot silently snap the file back to the top. Real user input cancels the
+ * guard immediately.
+ */
+const REVEAL_GUARD_FRAMES = 20;
+const REVEAL_GUARD_TOLERANCE_PX = 2;
+
+interface FileRevealState {
+  frameId: number | null;
+  cancelGuard: (() => void) | null;
+  handledRequestId: number | null;
+  latestRequestId: number | null;
+}
+
 function useFileLineReveal(
   relativePath: string | null,
   revealLine: number | null,
   revealRequestId: number,
 ): FilePostRender {
-  const [handledRequestIdsByPath] = useState(() => new Map<string, number>());
-  const [latestRequestIdsByPath] = useState(() => new Map<string, number>());
-  const [pendingFramesByPath] = useState(() => new Map<string, number>());
+  const [revealStatesByPath] = useState(() => new Map<string, FileRevealState>());
 
   return useCallback<FilePostRender>(
     (fileContainer, instance, phase) => {
       if (relativePath === null) return;
 
+      const existingState = revealStatesByPath.get(relativePath);
+      const state: FileRevealState = existingState ?? {
+        frameId: null,
+        cancelGuard: null,
+        handledRequestId: null,
+        latestRequestId: null,
+      };
+      if (!existingState) revealStatesByPath.set(relativePath, state);
+
       const cancelPendingReveal = () => {
-        const frameId = pendingFramesByPath.get(relativePath);
-        if (frameId !== undefined) {
-          cancelAnimationFrame(frameId);
-          pendingFramesByPath.delete(relativePath);
+        if (state.frameId !== null) {
+          cancelAnimationFrame(state.frameId);
+          state.frameId = null;
         }
+        state.cancelGuard?.();
       };
 
       if (phase === "unmount") {
@@ -208,18 +237,20 @@ function useFileLineReveal(
         return;
       }
 
+      const contents = instance.file?.contents;
       const targetLine =
-        revealLine === null ? null : clampFileLine(instance.file?.contents ?? "", revealLine);
+        revealLine === null || contents === undefined ? null : clampFileLine(contents, revealLine);
       updateFileLinkReveal(fileContainer, targetLine);
 
       if (!(instance instanceof VirtualizedFile)) return;
 
-      if (latestRequestIdsByPath.get(relativePath) !== revealRequestId) {
+      if (state.latestRequestId !== revealRequestId) {
         cancelPendingReveal();
-        latestRequestIdsByPath.set(relativePath, revealRequestId);
+        state.latestRequestId = revealRequestId;
+        state.handledRequestId = null;
       }
 
-      if (targetLine === null) {
+      if (revealLine === null) {
         fileContainer.style.minHeight = "";
         return;
       }
@@ -230,54 +261,113 @@ function useFileLineReveal(
         Math.max(instance.height, scrollContainer.clientHeight),
       )}px`;
 
-      if (
-        handledRequestIdsByPath.get(relativePath) === revealRequestId ||
-        pendingFramesByPath.has(relativePath)
-      ) {
+      if (state.handledRequestId === revealRequestId || state.frameId !== null) {
         return;
       }
 
-      const reveal = () => {
-        pendingFramesByPath.delete(relativePath);
-        if (
-          latestRequestIdsByPath.get(relativePath) !== revealRequestId ||
-          !fileContainer.isConnected
-        ) {
-          return;
-        }
-
-        const linePosition = instance.getLinePosition(targetLine);
-        if (!linePosition) return;
+      const resolveScrollTarget = (line: number): number | null => {
+        const linePosition = instance.getLinePosition(line);
+        if (!linePosition) return null;
 
+        const scrollContainerRect = scrollContainer.getBoundingClientRect();
         const fileTop =
           scrollContainer.scrollTop +
           fileContainer.getBoundingClientRect().top -
-          scrollContainer.getBoundingClientRect().top;
-        const centeredTop = Math.max(
-          0,
-          fileTop +
-            linePosition.top -
-            Math.max(0, (scrollContainer.clientHeight - linePosition.height) / 2),
-        );
-        const maxScrollTop = Math.max(
-          0,
-          scrollContainer.scrollHeight - scrollContainer.clientHeight,
-        );
+          scrollContainerRect.top;
+        const root = fileContainer.shadowRoot ?? fileContainer;
+        const renderedLineElement = root.querySelector<HTMLElement>(`[data-line="${line}"]`);
+        const renderedLineRect = renderedLineElement?.getBoundingClientRect();
 
-        scrollContainer.scrollTop = Math.min(centeredTop, maxScrollTop);
-        handledRequestIdsByPath.set(relativePath, revealRequestId);
+        return resolveCenteredFileLineScrollTop({
+          scrollTop: scrollContainer.scrollTop,
+          scrollHeight: scrollContainer.scrollHeight,
+          viewportTop: scrollContainerRect.top,
+          viewportHeight: scrollContainer.clientHeight,
+          fileTop,
+          estimatedLine: linePosition,
+          ...(renderedLineRect && renderedLineRect.height > 0
+            ? {
+                renderedLine: {
+                  top: renderedLineRect.top,
+                  height: renderedLineRect.height,
+                },
+              }
+            : {}),
+        });
       };
 
-      pendingFramesByPath.set(relativePath, requestAnimationFrame(reveal));
+      const guardScrollTarget = (line: number) => {
+        let framesLeft = REVEAL_GUARD_FRAMES;
+        let guardFrameId: number | null = null;
+        const cancelGuard = () => {
+          if (guardFrameId !== null) {
+            cancelAnimationFrame(guardFrameId);
+            guardFrameId = null;
+          }
+          scrollContainer.removeEventListener("wheel", cancelGuard);
+          scrollContainer.removeEventListener("touchstart", cancelGuard);
+          scrollContainer.removeEventListener("pointerdown", cancelGuard, true);
+          window.removeEventListener("keydown", cancelGuard, true);
+          if (state.cancelGuard === cancelGuard) state.cancelGuard = null;
+        };
+        scrollContainer.addEventListener("wheel", cancelGuard, { passive: true });
+        scrollContainer.addEventListener("touchstart", cancelGuard, { passive: true });
+        // Pierre stops gutter pointer events from bubbling. Listen in capture
+        // so starting a comment cancels the reveal guard before the row expands.
+        scrollContainer.addEventListener("pointerdown", cancelGuard, {
+          passive: true,
+          capture: true,
+        });
+        window.addEventListener("keydown", cancelGuard, true);
+        const holdTarget = () => {
+          guardFrameId = null;
+          framesLeft -= 1;
+          if (framesLeft <= 0 || !scrollContainer.isConnected) {
+            cancelGuard();
+            return;
+          }
+          const targetTop = resolveScrollTarget(line);
+          if (
+            targetTop !== null &&
+            Math.abs(scrollContainer.scrollTop - targetTop) > REVEAL_GUARD_TOLERANCE_PX
+          ) {
+            scrollContainer.scrollTop = targetTop;
+          }
+          guardFrameId = requestAnimationFrame(holdTarget);
+        };
+        guardFrameId = requestAnimationFrame(holdTarget);
+        state.cancelGuard = cancelGuard;
+      };
+
+      const scheduleReveal = (attempt: number) => {
+        state.frameId = requestAnimationFrame(() => {
+          state.frameId = null;
+          if (state.latestRequestId !== revealRequestId || !fileContainer.isConnected) {
+            return;
+          }
+
+          // Contents and line metrics can lag the first post-render on fresh
+          // mounts; clamping against missing contents would scroll to line 1
+          // and wrongly mark the request handled.
+          const currentContents = instance.file?.contents;
+          const line =
+            currentContents === undefined ? null : clampFileLine(currentContents, revealLine);
+          const targetTop = line === null ? null : resolveScrollTarget(line);
+          if (line === null || targetTop === null) {
+            if (attempt < REVEAL_MAX_ATTEMPTS) scheduleReveal(attempt + 1);
+            return;
+          }
+          updateFileLinkReveal(fileContainer, line);
+
+          scrollContainer.scrollTop = targetTop;
+          state.handledRequestId = revealRequestId;
+          guardScrollTarget(line);
+        });
+      };
+
+      scheduleReveal(0);
     },
-    [
-      handledRequestIdsByPath,
-      latestRequestIdsByPath,
-      pendingFramesByPath,
-      relativePath,
-      revealLine,
-      revealRequestId,
-    ],
+    [revealStatesByPath, relativePath, revealLine, revealRequestId],
   );
 }
 
@@ -963,6 +1053,8 @@ export default function FilePreviewPanel({
               environmentId={environmentId}
               cwd={cwd}
               projectName={projectName}
+              selectedPath={relativePath}
+              selectedPathRevealId={revealRequestId}
               onOpenFile={onOpenFile}
             />
           </aside>
diff --git a/apps/web/src/components/files/ProjectFilePicker.logic.test.ts b/apps/web/src/components/files/ProjectFilePicker.logic.test.ts
new file mode 100644
index 00000000000..2693ac9a072
--- /dev/null
+++ b/apps/web/src/components/files/ProjectFilePicker.logic.test.ts
@@ -0,0 +1,83 @@
+import { assert, describe, it } from "vite-plus/test";
+
+import { getProjectFilePickerMatches } from "./ProjectFilePicker.logic";
+
+function pathsForQuery(entries: Parameters<typeof getProjectFilePickerMatches>[0], query: string) {
+  return getProjectFilePickerMatches(entries, query).map(({ name, path }) => ({ name, path }));
+}
+
+const entries = [
+  { kind: "directory", path: "apps/web/src" },
+  { kind: "file", path: "apps/web/src/index.ts" },
+  { kind: "file", path: "packages/shared/src/index.ts" },
+  { kind: "file", path: "README.md" },
+  { kind: "file", path: ".gitignore" },
+] as const;
+
+describe("getProjectFilePickerMatches", () => {
+  it("returns files only and preserves index order for an empty query", () => {
+    assert.deepEqual(pathsForQuery(entries, ""), [
+      { name: "index.ts", path: "apps/web/src/index.ts" },
+      { name: "index.ts", path: "packages/shared/src/index.ts" },
+      { name: "README.md", path: "README.md" },
+      { name: ".gitignore", path: ".gitignore" },
+    ]);
+  });
+
+  it("preserves the server result order", () => {
+    assert.deepEqual(pathsForQuery(entries, "index"), [
+      { name: "index.ts", path: "apps/web/src/index.ts" },
+      { name: "index.ts", path: "packages/shared/src/index.ts" },
+      { name: "README.md", path: "README.md" },
+      { name: ".gitignore", path: ".gitignore" },
+    ]);
+  });
+
+  it("supports space-separated path tokens and a result limit", () => {
+    assert.deepEqual(
+      getProjectFilePickerMatches(entries, "src index", 1).map(({ name, path }) => ({
+        name,
+        path,
+      })),
+      [{ name: "index.ts", path: "apps/web/src/index.ts" }],
+    );
+  });
+
+  it("matches ordered characters while allowing skipped characters", () => {
+    const fuzzyEntries = [
+      { kind: "file", path: "src/TestFlags.tsx" },
+      { kind: "file", path: "src/SubtestFlow.tsx" },
+      { kind: "file", path: "src/useSubtestFlags.ts" },
+      {
+        kind: "file",
+        path: "src/useSubtestFlags/useTabActivity.ts",
+      },
+    ] as const;
+
+    assert.deepEqual(
+      pathsForQuery(fuzzyEntries, "testf").map(({ name }) => name),
+      ["TestFlags.tsx", "SubtestFlow.tsx", "useSubtestFlags.ts", "useTabActivity.ts"],
+    );
+    assert.deepEqual(getProjectFilePickerMatches(fuzzyEntries, "tsfl")[0], {
+      name: "TestFlags.tsx",
+      nameMatchIndices: [0, 2, 4, 5],
+      path: "src/TestFlags.tsx",
+      pathMatchIndices: [4, 6, 8, 9],
+    });
+  });
+
+  it("uses the first ordered subsequence for highlighting", () => {
+    assert.deepEqual(
+      getProjectFilePickerMatches([{ kind: "file", path: "aabba" }], "aba")[0]?.nameMatchIndices,
+      [0, 2, 4],
+    );
+  });
+
+  it("normalizes path prefixes consistently with server search", () => {
+    assert.deepEqual(
+      getProjectFilePickerMatches([{ kind: "file", path: "src/index.ts" }], "@/src")[0]
+        ?.pathMatchIndices,
+      [0, 1, 2],
+    );
+  });
+});
diff --git a/apps/web/src/components/files/ProjectFilePicker.logic.ts b/apps/web/src/components/files/ProjectFilePicker.logic.ts
new file mode 100644
index 00000000000..048c5373425
--- /dev/null
+++ b/apps/web/src/components/files/ProjectFilePicker.logic.ts
@@ -0,0 +1,73 @@
+import type { ProjectEntry } from "@t3tools/contracts";
+import { normalizeSearchQuery } from "@t3tools/shared/searchRanking";
+
+export const PROJECT_FILE_PICKER_RESULT_LIMIT = 200;
+
+export interface ProjectFilePickerMatch {
+  readonly name: string;
+  readonly nameMatchIndices: ReadonlyArray<number>;
+  readonly path: string;
+  readonly pathMatchIndices: ReadonlyArray<number>;
+}
+
+function fileName(path: string): string {
+  return path.slice(path.lastIndexOf("/") + 1);
+}
+
+/**
+ * First ordered subsequence of `query` inside `value`, as highlight indices.
+ * Returns null when `value` does not contain the subsequence at all — the
+ * entry still renders (the server matched it), just without highlights.
+ */
+function findMatchIndices(value: string, query: string): number[] | null {
+  if (!query) return [];
+
+  const normalizedValue = value.toLowerCase();
+  const indices: number[] = [];
+  let queryIndex = 0;
+
+  for (let valueIndex = 0; valueIndex < normalizedValue.length; valueIndex += 1) {
+    if (normalizedValue[valueIndex] !== query[queryIndex]) continue;
+    indices.push(valueIndex);
+    queryIndex += 1;
+    if (queryIndex === query.length) return indices;
+  }
+
+  return null;
+}
+
+/**
+ * Maps server search results to picker rows. Server ordering is preserved —
+ * ranking already happened there; this pass only filters to files and
+ * computes highlight positions with the same query normalization the server
+ * applied.
+ */
+export function getProjectFilePickerMatches(
+  entries: ReadonlyArray<ProjectEntry>,
+  rawQuery: string,
+  limit = PROJECT_FILE_PICKER_RESULT_LIMIT,
+): ProjectFilePickerMatch[] {
+  if (limit <= 0) return [];
+
+  const query = normalizeSearchQuery(rawQuery, {
+    trimLeadingPattern: /^[@./]+/,
+  }).replaceAll(/\s/g, "");
+  const matches: ProjectFilePickerMatch[] = [];
+
+  for (const entry of entries) {
+    if (entry.kind !== "file") continue;
+
+    const name = fileName(entry.path);
+    const nameMatchIndices = findMatchIndices(name, query);
+    const pathMatchIndices = findMatchIndices(entry.path, query);
+    matches.push({
+      name,
+      nameMatchIndices: nameMatchIndices ?? [],
+      path: entry.path,
+      pathMatchIndices: pathMatchIndices ?? [],
+    });
+    if (matches.length >= limit) break;
+  }
+
+  return matches;
+}
diff --git a/apps/web/src/components/files/ProjectFilePicker.tsx b/apps/web/src/components/files/ProjectFilePicker.tsx
new file mode 100644
index 00000000000..a59e8dd77e4
--- /dev/null
+++ b/apps/web/src/components/files/ProjectFilePicker.tsx
@@ -0,0 +1,163 @@
+import { useAtomValue } from "@effect/atom-react";
+import { useMemo, useState, type ReactNode } from "react";
+
+import { useActiveProjectTarget, type ActiveProjectTarget } from "~/hooks/useActiveProjectTarget";
+import { useTheme } from "~/hooks/useTheme";
+import { useRightPanelStore } from "~/rightPanelStore";
+import { primaryServerKeybindingsAtom } from "~/state/server";
+
+import { PierreEntryIcon } from "../chat/PierreEntryIcon";
+import { CommandPaletteContent } from "../CommandPaletteContent";
+import { type CommandPaletteActionItem } from "../CommandPalette.logic";
+import { CommandPaletteResults } from "../CommandPaletteResults";
+import {
+  getProjectFilePickerMatches,
+  PROJECT_FILE_PICKER_RESULT_LIMIT,
+} from "./ProjectFilePicker.logic";
+import { useProjectFilePickerQuery } from "./projectFilesQueryState";
+
+interface ProjectFilePickerProps {
+  readonly setOpen: (open: boolean) => void;
+}
+
+function HighlightedFuzzyText(props: {
+  readonly active: boolean;
+  readonly indices: ReadonlyArray<number>;
+  readonly value: string;
+}) {
+  if (!props.active) return props.value;
+
+  const parts: ReactNode[] = [];
+  let start = 0;
+  for (const index of props.indices) {
+    if (start < index) parts.push(props.value.slice(start, index));
+    parts.push(
+      <strong className="font-semibold text-foreground" key={index}>
+        {props.value[index]}
+      </strong>,
+    );
+    start = index + 1;
+  }
+  if (start < props.value.length) parts.push(props.value.slice(start));
+
+  return <span className="text-muted-foreground">{parts}</span>;
+}
+
+function getEmptyStateMessage(query: string, error: string | null, isPending: boolean): string {
+  if (error) return error;
+  const isSearching = query.trim().length > 0;
+  if (isPending) return isSearching ? "Searching workspace files…" : "Indexing workspace files…";
+  return isSearching ? "No matching files." : "No files found.";
+}
+
+function EmptyProjectFilePicker() {
+  return (
+    <CommandPaletteContent
+      aria-label="File picker"
+      escapeLabel="Back"
+      footerActionLabel="Open file"
+      inputProps={{ disabled: true, placeholder: "Search files…" }}
+      mode="none"
+      testId="project-file-picker"
+      value=""
+    >
+      <div className="py-10 text-center text-sm text-muted-foreground">
+        Open a project to search its files.
+      </div>
+    </CommandPaletteContent>
+  );
+}
+
+function OpenProjectFilePicker(props: ProjectFilePickerProps & { target: ActiveProjectTarget }) {
+  const { target } = props;
+  const [query, setQuery] = useState("");
+  const [highlightedItemValue, setHighlightedItemValue] = useState<string | null>(null);
+  const result = useProjectFilePickerQuery(
+    target.environmentId,
+    target.cwd,
+    query,
+    PROJECT_FILE_PICKER_RESULT_LIMIT,
+  );
+  const { resolvedTheme } = useTheme();
+  const keybindings = useAtomValue(primaryServerKeybindingsAtom);
+  const matches = useMemo(
+    () => getProjectFilePickerMatches(result.entries, result.matchedQuery),
+    [result.entries, result.matchedQuery],
+  );
+  const hasMatchedQuery = /\S/.test(result.matchedQuery);
+  const items = useMemo<CommandPaletteActionItem[]>(
+    () =>
+      matches.map((match) => ({
+        kind: "action",
+        value: `file:${match.path}`,
+        searchTerms: [match.name, match.path],
+        title: (
+          <HighlightedFuzzyText
+            active={hasMatchedQuery}
+            value={match.name}
+            indices={match.nameMatchIndices}
+          />
+        ),
+        description: (
+          <HighlightedFuzzyText
+            active={hasMatchedQuery}
+            value={match.path}
+            indices={match.pathMatchIndices}
+          />
+        ),
+        icon: <PierreEntryIcon pathValue={match.path} kind="file" theme={resolvedTheme} />,
+        run: async () => {
+          useRightPanelStore.getState().openFile(target.threadRef, match.path);
+        },
+      })),
+    [hasMatchedQuery, matches, resolvedTheme, target.threadRef],
+  );
+
+  const emptyStateMessage = getEmptyStateMessage(query, result.error, result.isPending);
+
+  return (
+    <CommandPaletteContent
+      aria-label="File picker"
+      autoHighlight="always"
+      escapeLabel="Back"
+      footerActionLabel="Open file"
+      inputProps={{ placeholder: "Search files…" }}
+      mode="none"
+      onItemHighlighted={(value) => {
+        setHighlightedItemValue(typeof value === "string" ? value : null);
+      }}
+      onValueChange={(value) => {
+        setHighlightedItemValue(null);
+        setQuery(value);
+      }}
+      panelClassName="max-h-[min(34rem,76vh)]"
+      testId="project-file-picker"
+      value={query}
+    >
+      <CommandPaletteResults
+        groups={
+          items.length > 0 ? [{ value: "project-files", label: target.projectName, items }] : []
+        }
+        highlightedItemValue={highlightedItemValue}
+        isActionsOnly={false}
+        keybindings={keybindings}
+        onExecuteItem={(item) => {
+          if (item.kind !== "action") return;
+          props.setOpen(false);
+          void item.run();
+        }}
+        emptyStateMessage={emptyStateMessage}
+      />
+    </CommandPaletteContent>
+  );
+}
+
+export function ProjectFilePicker(props: ProjectFilePickerProps) {
+  const target = useActiveProjectTarget();
+
+  if (!target) {
+    return <EmptyProjectFilePicker />;
+  }
+
+  return <OpenProjectFilePicker setOpen={props.setOpen} target={target} />;
+}
diff --git a/apps/web/src/components/files/fileLineReveal.test.ts b/apps/web/src/components/files/fileLineReveal.test.ts
new file mode 100644
index 00000000000..3a63168d5d3
--- /dev/null
+++ b/apps/web/src/components/files/fileLineReveal.test.ts
@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { resolveCenteredFileLineScrollTop } from "./fileLineReveal";
+
+describe("resolveCenteredFileLineScrollTop", () => {
+  it("centers an estimated virtualized line position", () => {
+    expect(
+      resolveCenteredFileLineScrollTop({
+        scrollTop: 0,
+        scrollHeight: 2_000,
+        viewportTop: 100,
+        viewportHeight: 400,
+        fileTop: 20,
+        estimatedLine: { top: 1_000, height: 20 },
+      }),
+    ).toBe(830);
+  });
+
+  it("corrects a stale estimate from the rendered line geometry", () => {
+    expect(
+      resolveCenteredFileLineScrollTop({
+        scrollTop: 830,
+        scrollHeight: 2_000,
+        viewportTop: 100,
+        viewportHeight: 400,
+        fileTop: 20,
+        estimatedLine: { top: 1_000, height: 20 },
+        renderedLine: { top: 620, height: 20 },
+      }),
+    ).toBe(1_160);
+  });
+});
diff --git a/apps/web/src/components/files/fileLineReveal.ts b/apps/web/src/components/files/fileLineReveal.ts
new file mode 100644
index 00000000000..fd066ae205b
--- /dev/null
+++ b/apps/web/src/components/files/fileLineReveal.ts
@@ -0,0 +1,24 @@
+interface LineGeometry {
+  readonly top: number;
+  readonly height: number;
+}
+
+interface CenteredFileLineScrollInput {
+  readonly scrollTop: number;
+  readonly scrollHeight: number;
+  readonly viewportTop: number;
+  readonly viewportHeight: number;
+  readonly fileTop: number;
+  readonly estimatedLine: LineGeometry;
+  readonly renderedLine?: LineGeometry;
+}
+
+export function resolveCenteredFileLineScrollTop(input: CenteredFileLineScrollInput): number {
+  const lineTop =
+    input.renderedLine === undefined
+      ? input.fileTop + input.estimatedLine.top
+      : input.scrollTop + input.renderedLine.top - input.viewportTop;
+  const lineHeight = input.renderedLine?.height ?? input.estimatedLine.height;
+  const centeredTop = Math.max(0, lineTop - Math.max(0, (input.viewportHeight - lineHeight) / 2));
+  return Math.min(centeredTop, Math.max(0, input.scrollHeight - input.viewportHeight));
+}
diff --git a/apps/web/src/components/files/projectFilesQueryState.ts b/apps/web/src/components/files/projectFilesQueryState.ts
index 0d3fb8dd941..d165c1d1a7a 100644
--- a/apps/web/src/components/files/projectFilesQueryState.ts
+++ b/apps/web/src/components/files/projectFilesQueryState.ts
@@ -11,6 +11,7 @@ import { useCallback } from "react";
 
 import { appAtomRegistry } from "~/rpc/atomRegistry";
 import { projectEnvironment } from "~/state/projects";
+import { useProjectPathSearch } from "~/state/queries";
 import { executeAtomQuery } from "@t3tools/client-runtime/state/runtime";
 
 const EMPTY_PROJECT_FILE_PATH = "";
@@ -136,6 +137,32 @@ export function useProjectEntriesQuery(
   };
 }
 
+/**
+ * Backing query for the project file picker: a debounced, bounded, file-only
+ * server search. An empty query is a valid request — the index answers it
+ * with frecency-ordered files, so the picker's initial view is recent files
+ * without transferring the full workspace listing. `matchedQuery` is the
+ * query the returned entries were computed for, so the caller can highlight
+ * against results instead of half-typed input.
+ */
+export function useProjectFilePickerQuery(
+  environmentId: EnvironmentId,
+  cwd: string,
+  query: string,
+  limit: number,
+) {
+  const search = useProjectPathSearch({ environmentId, cwd, query, kind: "file" }, limit, {
+    allowEmptyQuery: true,
+  });
+
+  return {
+    entries: search.isPending ? [] : search.entries,
+    error: search.error,
+    isPending: search.isPending,
+    matchedQuery: search.searchedQuery,
+  };
+}
+
 export function useProjectFileQuery(
   environmentId: EnvironmentId,
   cwd: string,
diff --git a/apps/web/src/components/search/HighlightedSearchLine.tsx b/apps/web/src/components/search/HighlightedSearchLine.tsx
new file mode 100644
index 00000000000..9d529622776
--- /dev/null
+++ b/apps/web/src/components/search/HighlightedSearchLine.tsx
@@ -0,0 +1,183 @@
+import { getFiletypeFromFileName } from "@pierre/diffs";
+import type { ProjectContentMatch } from "@t3tools/contracts";
+import { memo, Suspense, use, useMemo, type CSSProperties } from "react";
+
+import { resolveDiffThemeName } from "~/lib/diffRendering";
+import { getSyntaxHighlighterPromise } from "~/lib/syntaxHighlighting";
+
+import { RenderErrorBoundary } from "../RenderErrorBoundary";
+
+interface Range {
+  readonly start: number;
+  readonly end: number;
+}
+
+interface CodeToken {
+  readonly content: string;
+  readonly offset: number;
+  readonly color?: string;
+  readonly fontStyle?: number;
+}
+
+interface Segment {
+  readonly content: string;
+  readonly isMatch: boolean;
+  readonly start: number;
+  readonly end: number;
+  readonly token: CodeToken;
+}
+
+function normalizeRanges(match: ProjectContentMatch): Range[] {
+  const ranges = match.matchRanges
+    .map((range) => ({
+      start: Math.max(0, Math.min(match.lineContent.length, range.start)),
+      end: Math.max(0, Math.min(match.lineContent.length, range.end)),
+    }))
+    .filter((range) => range.end > range.start)
+    .toSorted((left, right) => left.start - right.start);
+
+  const merged: Array<{ start: number; end: number }> = [];
+  for (const range of ranges) {
+    const previous = merged.at(-1);
+    if (previous && range.start <= previous.end) {
+      previous.end = Math.max(previous.end, range.end);
+    } else {
+      merged.push({ ...range });
+    }
+  }
+  return merged;
+}
+
+function splitToken(line: string, token: CodeToken, ranges: ReadonlyArray<Range>): Segment[] {
+  const segments: Segment[] = [];
+  const tokenEnd = token.offset + token.content.length;
+  let cursor = token.offset;
+
+  for (const range of ranges) {
+    if (range.end <= cursor) continue;
+    if (range.start >= tokenEnd) break;
+
+    const matchStart = Math.max(cursor, range.start);
+    if (matchStart > cursor) {
+      segments.push({
+        content: line.slice(cursor, matchStart),
+        isMatch: false,
+        start: cursor,
+        end: matchStart,
+        token,
+      });
+    }
+
+    const matchEnd = Math.min(tokenEnd, range.end);
+    segments.push({
+      content: line.slice(matchStart, matchEnd),
+      isMatch: true,
+      start: matchStart,
+      end: matchEnd,
+      token,
+    });
+    cursor = matchEnd;
+  }
+
+  if (cursor < tokenEnd) {
+    segments.push({
+      content: line.slice(cursor, tokenEnd),
+      isMatch: false,
+      start: cursor,
+      end: tokenEnd,
+      token,
+    });
+  }
+  return segments;
+}
+
+function tokenStyle(token: CodeToken): CSSProperties {
+  const fontStyle = token.fontStyle ?? 0;
+  return {
+    ...(token.color ? { color: token.color } : {}),
+    ...(fontStyle & 1 ? { fontStyle: "italic" } : {}),
+    ...(fontStyle & 2 ? { fontWeight: 700 } : {}),
+    ...(fontStyle & 4 ? { textDecoration: "underline" } : {}),
+  };
+}
+
+function HighlightedTokens(props: {
+  readonly line: string;
+  readonly ranges: ReadonlyArray<Range>;
+  readonly tokens: ReadonlyArray<CodeToken>;
+}) {
+  return props.tokens
+    .flatMap((token) => splitToken(props.line, token, props.ranges))
+    .map((segment) =>
+      segment.isMatch ? (
+        <mark
+          className="rounded-[2px] bg-primary/25 text-inherit"
+          key={`${segment.start}:${segment.end}:match`}
+          style={tokenStyle(segment.token)}
+        >
+          {segment.content}
+        </mark>
+      ) : (
+        <span key={`${segment.start}:${segment.end}:code`} style={tokenStyle(segment.token)}>
+          {segment.content}
+        </span>
+      ),
+    );
+}
+
+function SyntaxHighlightedTokens(props: {
+  readonly line: string;
+  readonly language: string;
+  readonly ranges: ReadonlyArray<Range>;
+  readonly theme: "light" | "dark";
+}) {
+  const highlighter = use(getSyntaxHighlighterPromise(props.language));
+  const tokens = useMemo(() => {
+    try {
+      return highlighter.codeToTokens(props.line, {
+        lang: props.language,
+        theme: resolveDiffThemeName(props.theme),
+      }).tokens[0];
+    } catch {
+      return undefined;
+    }
+  }, [highlighter, props.language, props.line, props.theme]);
+
+  return tokens ? (
+    <HighlightedTokens line={props.line} ranges={props.ranges} tokens={tokens} />
+  ) : (
+    <HighlightedTokens
+      line={props.line}
+      ranges={props.ranges}
+      tokens={[{ content: props.line, offset: 0 }]}
+    />
+  );
+}
+
+export const HighlightedSearchLine = memo(function HighlightedSearchLine(props: {
+  readonly match: ProjectContentMatch;
+  readonly path: string;
+  readonly theme: "light" | "dark";
+}) {
+  const ranges = useMemo(() => normalizeRanges(props.match), [props.match]);
+  const fallback = (
+    <HighlightedTokens
+      line={props.match.lineContent}
+      ranges={ranges}
+      tokens={[{ content: props.match.lineContent, offset: 0 }]}
+    />
+  );
+
+  return (
+    <RenderErrorBoundary fallback={fallback}>
+      <Suspense fallback={fallback}>
+        <SyntaxHighlightedTokens
+          line={props.match.lineContent}
+          language={getFiletypeFromFileName(props.path)}
+          ranges={ranges}
+          theme={props.theme}
+        />
+      </Suspense>
+    </RenderErrorBoundary>
+  );
+});
diff --git a/apps/web/src/components/search/ProjectContentSearchDialog.tsx b/apps/web/src/components/search/ProjectContentSearchDialog.tsx
new file mode 100644
index 00000000000..1890aab7fa7
--- /dev/null
+++ b/apps/web/src/components/search/ProjectContentSearchDialog.tsx
@@ -0,0 +1,315 @@
+import type { ProjectContentMatch } from "@t3tools/contracts";
+import { LoaderCircle } from "lucide-react";
+import { useCallback, useEffect, useMemo, useState, type ReactNode } from "react";
+
+import { useActiveProjectTarget, type ActiveProjectTarget } from "~/hooks/useActiveProjectTarget";
+import { useTheme } from "~/hooks/useTheme";
+import { cn } from "~/lib/utils";
+import { useRightPanelStore } from "~/rightPanelStore";
+import { useProjectContentSearch } from "~/state/queries";
+
+import { PierreEntryIcon } from "../chat/PierreEntryIcon";
+import { CommandPaletteContent } from "../CommandPaletteContent";
+import { ScrollArea } from "../ui/scroll-area";
+import { HighlightedSearchLine } from "./HighlightedSearchLine";
+
+interface ProjectContentSearchDialogProps {
+  readonly onOpenChange: (open: boolean) => void;
+}
+
+/**
+ * Result rows are syntax highlighted, so mounting all 500 possible rows at
+ * once stalls the UI. Rows render in windows that grow as the sentinel at the
+ * bottom of the list scrolls into view (or keyboard navigation moves past
+ * the rendered window).
+ */
+const VISIBLE_MATCH_WINDOW = 100;
+
+interface MatchGroup {
+  readonly path: string;
+  readonly matches: ReadonlyArray<ProjectContentMatch & { readonly resultIndex: number }>;
+}
+
+function splitPath(path: string): { readonly name: string; readonly directory: string } {
+  const separator = path.lastIndexOf("/");
+  return separator === -1
+    ? { name: path, directory: "" }
+    : { name: path.slice(separator + 1), directory: path.slice(0, separator) };
+}
+
+function groupMatches(matches: ReadonlyArray<ProjectContentMatch>): MatchGroup[] {
+  const groups = new Map<string, Array<ProjectContentMatch & { readonly resultIndex: number }>>();
+  matches.forEach((match, resultIndex) => {
+    const group = groups.get(match.path);
+    const indexedMatch = { ...match, resultIndex };
+    if (group) {
+      group.push(indexedMatch);
+    } else {
+      groups.set(match.path, [indexedMatch]);
+    }
+  });
+  return [...groups].map(([path, groupedMatches]) => ({ path, matches: groupedMatches }));
+}
+
+function SearchOptionButton(props: {
+  readonly active: boolean;
+  readonly label: string;
+  readonly onClick: () => void;
+  readonly children: ReactNode;
+}) {
+  return (
+    <button
+      type="button"
+      aria-label={props.label}
+      aria-pressed={props.active}
+      title={props.label}
+      className={cn(
+        "flex size-8 shrink-0 items-center justify-center rounded-[5px] font-mono text-xs font-medium text-muted-foreground transition-colors hover:bg-accent hover:text-foreground",
+        props.active && "bg-accent text-foreground shadow-sm",
+      )}
+      onClick={props.onClick}
+    >
+      {props.children}
+    </button>
+  );
+}
+
+function EmptyContentSearchDialog() {
+  return (
+    <CommandPaletteContent
+      aria-label="Search project contents"
+      escapeLabel="Back"
+      footerActionLabel="Open file"
+      inputProps={{ disabled: true, placeholder: "Search project contents…" }}
+      mode="none"
+      panelClassName="flex min-h-0 flex-1 items-center justify-center px-6 text-center text-sm text-muted-foreground"
+      testId="project-content-search"
+      value=""
+    >
+      Open a project to search its files.
+    </CommandPaletteContent>
+  );
+}
+
+function OpenContentSearchDialog(props: {
+  readonly onOpenChange: (open: boolean) => void;
+  readonly target: ActiveProjectTarget;
+}) {
+  const { target } = props;
+  const { resolvedTheme } = useTheme();
+  const [query, setQuery] = useState("");
+  const [caseSensitive, setCaseSensitive] = useState(false);
+  const [wholeWord, setWholeWord] = useState(false);
+  const [useRegex, setUseRegex] = useState(false);
+  const [selectedIndex, setSelectedIndex] = useState(0);
+
+  const [visibleCount, setVisibleCount] = useState(VISIBLE_MATCH_WINDOW);
+
+  const search = useProjectContentSearch({
+    environmentId: target.environmentId,
+    cwd: target.cwd,
+    query,
+    caseSensitive,
+    wholeWord,
+    useRegex,
+  });
+  const canOpenMatches = !search.isPending;
+  const matches = search.matches;
+  const visibleMatches = useMemo(() => matches.slice(0, visibleCount), [matches, visibleCount]);
+  const groups = useMemo(() => groupMatches(visibleMatches), [visibleMatches]);
+
+  useEffect(() => {
+    setSelectedIndex(0);
+    setVisibleCount(VISIBLE_MATCH_WINDOW);
+  }, [matches]);
+
+  useEffect(() => {
+    if (selectedIndex >= visibleCount) {
+      setVisibleCount(selectedIndex + VISIBLE_MATCH_WINDOW);
+      return;
+    }
+    document
+      .querySelector<HTMLElement>(`[data-content-search-result="${selectedIndex}"]`)
+      ?.scrollIntoView({ block: "nearest" });
+  }, [selectedIndex, visibleCount]);
+
+  const observeLoadMoreSentinel = useCallback((sentinel: HTMLElement | null) => {
+    if (!sentinel) return;
+    const observer = new IntersectionObserver((entries) => {
+      if (entries.some((entry) => entry.isIntersecting)) {
+        setVisibleCount((current) => current + VISIBLE_MATCH_WINDOW);
+      }
+    });
+    observer.observe(sentinel);
+    return () => observer.disconnect();
+  }, []);
+
+  const openMatch = (match: ProjectContentMatch) => {
+    if (!canOpenMatches) return;
+    props.onOpenChange(false);
+    useRightPanelStore.getState().openFile(target.threadRef, match.path, match.lineNumber);
+  };
+  const fileCount = useMemo(() => new Set(matches.map((match) => match.path)).size, [matches]);
+  const showSearchStatus =
+    search.hasQuery || search.isPending || search.error !== null || search.invalidRegex;
+
+  return (
+    <CommandPaletteContent
+      aria-label={`Search file contents in ${target.projectName}`}
+      escapeLabel="Back"
+      footerActionLabel="Open file"
+      inputAccessory={
+        <div className="absolute inset-e-2.5 top-1/2 flex shrink-0 -translate-y-1/2 items-center gap-0.5 rounded-md border bg-muted/30 p-0.5">
+          <SearchOptionButton
+            active={caseSensitive}
+            label="Match case"
+            onClick={() => setCaseSensitive((current) => !current)}
+          >
+            Aa
+          </SearchOptionButton>
+          <SearchOptionButton
+            active={wholeWord}
+            label="Match whole word"
+            onClick={() => setWholeWord((current) => !current)}
+          >
+            <span className="underline decoration-2 underline-offset-2">ab</span>
+          </SearchOptionButton>
+          <SearchOptionButton
+            active={useRegex}
+            label="Use regular expression"
+            onClick={() => setUseRegex((current) => !current)}
+          >
+            .*
+          </SearchOptionButton>
+        </div>
+      }
+      inputProps={{
+        className: "pe-30",
+        placeholder: `Search in ${target.projectName}`,
+        onKeyDown: (event) => {
+          if (event.key === "ArrowDown" && matches.length > 0) {
+            event.preventDefault();
+            setSelectedIndex((current) => (current + 1) % matches.length);
+          } else if (event.key === "ArrowUp" && matches.length > 0) {
+            event.preventDefault();
+            setSelectedIndex((current) => (current - 1 + matches.length) % matches.length);
+          } else if (event.key === "Enter") {
+            // While a newer query is debouncing or in flight, the visible
+            // matches belong to the previous query; opening one would jump
+            // to a result the user did not ask for.
+            if (!canOpenMatches) {
+              event.preventDefault();
+              return;
+            }
+            const match = matches[selectedIndex];
+            if (match) {
+              event.preventDefault();
+              openMatch(match);
+            }
+          }
+        },
+      }}
+      mode="none"
+      onValueChange={setQuery}
+      panelClassName="flex min-h-0 flex-1 flex-col"
+      testId="project-content-search"
+      value={query}
+    >
+      {showSearchStatus ? (
+        <div className="flex h-9 shrink-0 items-center border-b px-3 text-xs text-muted-foreground">
+          {search.isPending ? (
+            <span className="flex items-center gap-2">
+              <LoaderCircle className="size-3.5 animate-spin" /> Searching…
+            </span>
+          ) : search.error ? (
+            <span className="text-destructive">{search.error}</span>
+          ) : search.invalidRegex ? (
+            <span className="text-destructive">Invalid regular expression</span>
+          ) : (
+            `${matches.length.toLocaleString()}${search.truncated ? "+" : ""} results in ${fileCount.toLocaleString()} files`
+          )}
+        </div>
+      ) : null}
+
+      {matches.length === 0 ? (
+        <div className="flex flex-1 items-center justify-center px-6 text-center text-sm text-muted-foreground">
+          {search.hasQuery && !search.isPending && !search.error
+            ? "No results found."
+            : "Type to search across your project."}
+        </div>
+      ) : (
+        <ScrollArea className="min-h-0 flex-1" scrollFade>
+          <div className="py-2">
+            {groups.map((group) => {
+              const path = splitPath(group.path);
+              return (
+                <section className="pb-2" key={group.path}>
+                  <div className="sticky top-0 z-10 flex h-8 items-center gap-2 bg-popover/95 px-3 text-xs backdrop-blur-sm">
+                    <PierreEntryIcon
+                      pathValue={group.path}
+                      kind="file"
+                      theme={resolvedTheme}
+                      className="size-3.5"
+                    />
+                    <span className="font-medium text-foreground">{path.name}</span>
+                    {path.directory ? (
+                      <span className="min-w-0 truncate text-muted-foreground">
+                        {path.directory}
+                      </span>
+                    ) : null}
+                    <span className="ml-auto rounded-full bg-muted px-1.5 py-0.5 tabular-nums text-[10px] text-muted-foreground">
+                      {group.matches.length}
+                    </span>
+                  </div>
+                  {group.matches.map((match) => (
+                    <button
+                      type="button"
+                      key={`${match.path}:${match.lineNumber}:${match.resultIndex}`}
+                      data-content-search-result={match.resultIndex}
+                      className={cn(
+                        "flex h-7 w-full min-w-0 items-center gap-3 px-3 text-left font-mono text-xs hover:bg-accent/60 disabled:pointer-events-none",
+                        match.resultIndex === selectedIndex && "bg-accent text-accent-foreground",
+                      )}
+                      disabled={!canOpenMatches}
+                      onMouseEnter={() => setSelectedIndex(match.resultIndex)}
+                      onClick={() => openMatch(match)}
+                    >
+                      <span className="w-10 shrink-0 text-right tabular-nums text-muted-foreground/70">
+                        {match.lineNumber}
+                      </span>
+                      <span className="min-w-0 flex-1 truncate whitespace-pre">
+                        <HighlightedSearchLine
+                          match={match}
+                          path={group.path}
+                          theme={resolvedTheme}
+                        />
+                      </span>
+                    </button>
+                  ))}
+                </section>
+              );
+            })}
+            {matches.length > visibleCount ? (
+              <div ref={observeLoadMoreSentinel} className="h-8" aria-hidden="true" />
+            ) : null}
+          </div>
+        </ScrollArea>
+      )}
+    </CommandPaletteContent>
+  );
+}
+
+export function ProjectContentSearchDialog(props: ProjectContentSearchDialogProps) {
+  const target = useActiveProjectTarget();
+
+  return target ? (
+    <OpenContentSearchDialog
+      // Reset the query and options whenever the workspace changes.
+      key={`${target.environmentId}:${target.cwd}`}
+      onOpenChange={props.onOpenChange}
+      target={target}
+    />
+  ) : (
+    <EmptyContentSearchDialog />
+  );
+}
diff --git a/apps/web/src/hooks/useActiveProjectTarget.ts b/apps/web/src/hooks/useActiveProjectTarget.ts
new file mode 100644
index 00000000000..560bba54f73
--- /dev/null
+++ b/apps/web/src/hooks/useActiveProjectTarget.ts
@@ -0,0 +1,41 @@
+import { scopeThreadRef } from "@t3tools/client-runtime/environment";
+import type { EnvironmentId, ScopedThreadRef } from "@t3tools/contracts";
+
+import { useProjects } from "~/state/entities";
+
+import { useHandleNewThread } from "./useHandleNewThread";
+
+export interface ActiveProjectTarget {
+  readonly environmentId: EnvironmentId;
+  readonly cwd: string;
+  readonly projectName: string;
+  readonly threadRef: ScopedThreadRef;
+}
+
+/**
+ * Resolves the project workspace behind the active thread (or draft) so
+ * project-scoped surfaces like the file picker and content search know which
+ * workspace to query and which thread's right panel opens their results.
+ */
+export function useActiveProjectTarget(): ActiveProjectTarget | null {
+  const { activeDraftThread, activeThread } = useHandleNewThread();
+  const projects = useProjects();
+  const thread = activeThread ?? activeDraftThread;
+  const threadId = activeThread?.id ?? activeDraftThread?.threadId;
+  const project = thread
+    ? projects.find(
+        (candidate) =>
+          candidate.environmentId === thread.environmentId && candidate.id === thread.projectId,
+      )
+    : null;
+  const cwd = thread?.worktreePath ?? project?.workspaceRoot;
+
+  if (!thread || !threadId || !project || !cwd) return null;
+
+  return {
+    environmentId: project.environmentId,
+    cwd,
+    projectName: project.title,
+    threadRef: scopeThreadRef(thread.environmentId, threadId),
+  };
+}
diff --git a/apps/web/src/hooks/useHandleNewThread.ts b/apps/web/src/hooks/useHandleNewThread.ts
index 74ad952e5a2..547d8287012 100644
--- a/apps/web/src/hooks/useHandleNewThread.ts
+++ b/apps/web/src/hooks/useHandleNewThread.ts
@@ -190,7 +190,7 @@ export function useNewThreadHandler() {
             reusableStoredDraftThread.draftId,
             {
               threadId: reusableStoredDraftThread.threadId,
-              ...(workspaceContext ?? {}),
+              ...workspaceContext,
               ...(carryRuntimeMode ? { runtimeMode: carryRuntimeMode } : {}),
               ...(carryInteractionMode ? { interactionMode: carryInteractionMode } : {}),
             },
diff --git a/apps/web/src/keybindings.test.ts b/apps/web/src/keybindings.test.ts
index c0d326edd55..703077e3ef3 100644
--- a/apps/web/src/keybindings.test.ts
+++ b/apps/web/src/keybindings.test.ts
@@ -118,6 +118,16 @@ const DEFAULT_BINDINGS = compile([
     command: "commandPalette.toggle",
     whenAst: whenNot(whenIdentifier("terminalFocus")),
   },
+  {
+    shortcut: modShortcut("p"),
+    command: "filePicker.toggle",
+    whenAst: whenNot(whenIdentifier("terminalFocus")),
+  },
+  {
+    shortcut: modShortcut("f", { shiftKey: true }),
+    command: "projectSearch.toggle",
+    whenAst: whenNot(whenIdentifier("terminalFocus")),
+  },
   {
     shortcut: modShortcut("m", { shiftKey: true }),
     command: "modelPicker.toggle",
@@ -327,6 +337,14 @@ describe("shortcutLabelForCommand", () => {
       shortcutLabelForCommand(DEFAULT_BINDINGS, "commandPalette.toggle", "MacIntel"),
       "⌘K",
     );
+    assert.strictEqual(
+      shortcutLabelForCommand(DEFAULT_BINDINGS, "filePicker.toggle", "MacIntel"),
+      "⌘P",
+    );
+    assert.strictEqual(
+      shortcutLabelForCommand(DEFAULT_BINDINGS, "projectSearch.toggle", "MacIntel"),
+      "⇧⌘F",
+    );
     assert.strictEqual(
       shortcutLabelForCommand(DEFAULT_BINDINGS, "modelPicker.toggle", "Linux"),
       "Ctrl+Shift+M",
@@ -514,6 +532,40 @@ describe("chat/editor shortcuts", () => {
     );
   });
 
+  it("matches filePicker.toggle shortcut outside terminal focus", () => {
+    assert.strictEqual(
+      resolveShortcutCommand(event({ key: "p", metaKey: true }), DEFAULT_BINDINGS, {
+        platform: "MacIntel",
+        context: { terminalFocus: false },
+      }),
+      "filePicker.toggle",
+    );
+    assert.notStrictEqual(
+      resolveShortcutCommand(event({ key: "p", metaKey: true }), DEFAULT_BINDINGS, {
+        platform: "MacIntel",
+        context: { terminalFocus: true },
+      }),
+      "filePicker.toggle",
+    );
+  });
+
+  it("matches projectSearch.toggle shortcut outside terminal focus", () => {
+    assert.strictEqual(
+      resolveShortcutCommand(event({ key: "f", metaKey: true, shiftKey: true }), DEFAULT_BINDINGS, {
+        platform: "MacIntel",
+        context: { terminalFocus: false },
+      }),
+      "projectSearch.toggle",
+    );
+    assert.notStrictEqual(
+      resolveShortcutCommand(event({ key: "f", metaKey: true, shiftKey: true }), DEFAULT_BINDINGS, {
+        platform: "MacIntel",
+        context: { terminalFocus: true },
+      }),
+      "projectSearch.toggle",
+    );
+  });
+
   it("matches diff.toggle shortcut outside terminal focus", () => {
     assert.isTrue(
       isDiffToggleShortcut(event({ key: "d", metaKey: true }), DEFAULT_BINDINGS, {
diff --git a/apps/web/src/lib/syntaxHighlighting.test.ts b/apps/web/src/lib/syntaxHighlighting.test.ts
new file mode 100644
index 00000000000..1f7ce756b60
--- /dev/null
+++ b/apps/web/src/lib/syntaxHighlighting.test.ts
@@ -0,0 +1,28 @@
+import type { DiffsHighlighter } from "@pierre/diffs";
+import { expect, it, vi } from "vite-plus/test";
+
+const { getSharedHighlighter } = vi.hoisted(() => ({
+  getSharedHighlighter: vi.fn(),
+}));
+
+vi.mock("@pierre/diffs", () => ({
+  getSharedHighlighter,
+}));
+
+import { getSyntaxHighlighterPromise } from "./syntaxHighlighting";
+
+it("caches the recovered text highlighter for unsupported languages", async () => {
+  const textHighlighter = {} as DiffsHighlighter;
+  getSharedHighlighter.mockImplementation(({ langs }: { langs: string[] }) =>
+    langs[0] === "text"
+      ? Promise.resolve(textHighlighter)
+      : Promise.reject(new Error("unsupported language")),
+  );
+
+  const first = getSyntaxHighlighterPromise("unsupported-test-language");
+  await expect(first).resolves.toBe(textHighlighter);
+  const second = getSyntaxHighlighterPromise("unsupported-test-language");
+
+  expect(second).toBe(first);
+  expect(getSharedHighlighter).toHaveBeenCalledTimes(2);
+});
diff --git a/apps/web/src/lib/syntaxHighlighting.ts b/apps/web/src/lib/syntaxHighlighting.ts
new file mode 100644
index 00000000000..171725617e8
--- /dev/null
+++ b/apps/web/src/lib/syntaxHighlighting.ts
@@ -0,0 +1,30 @@
+import {
+  getSharedHighlighter,
+  type DiffsHighlighter,
+  type SupportedLanguages,
+} from "@pierre/diffs";
+
+import { resolveDiffThemeName } from "./diffRendering";
+
+const highlighterPromiseCache = new Map<string, Promise<DiffsHighlighter>>();
+
+export function getSyntaxHighlighterPromise(language: string): Promise<DiffsHighlighter> {
+  const cached = highlighterPromiseCache.get(language);
+  if (cached) return cached;
+
+  const promise = getSharedHighlighter({
+    themes: [resolveDiffThemeName("dark"), resolveDiffThemeName("light")],
+    langs: [language as SupportedLanguages],
+    preferredHighlighter: "shiki-js",
+  }).catch((error) => {
+    if (language === "text") {
+      highlighterPromiseCache.delete(language);
+      // "text" itself failed — Shiki cannot initialize at all, surface the error
+      throw error;
+    }
+    // Language not supported by Shiki — fall back to "text"
+    return getSyntaxHighlighterPromise("text");
+  });
+  highlighterPromiseCache.set(language, promise);
+  return promise;
+}
diff --git a/apps/web/src/state/projects.ts b/apps/web/src/state/projects.ts
index 7a879988328..d4e1098a364 100644
--- a/apps/web/src/state/projects.ts
+++ b/apps/web/src/state/projects.ts
@@ -1,11 +1,24 @@
 import { createEnvironmentProjectAtoms } from "@t3tools/client-runtime/state/projects";
 import { createProjectEnvironmentAtoms } from "@t3tools/client-runtime/state/projects";
+import { createEnvironmentRpcQueryAtomFamily } from "@t3tools/client-runtime/state/runtime";
+import { WS_METHODS } from "@t3tools/contracts";
 
 import { environmentCatalog } from "../connection/catalog";
 import { connectionAtomRuntime } from "../connection/runtime";
 import { environmentSnapshotAtom } from "./shell";
 
 export const projectEnvironment = createProjectEnvironmentAtoms(connectionAtomRuntime);
+/**
+ * Web-only: project content search backs the ⇧⌘F dialog, which has no mobile
+ * surface, so the atom family lives here instead of the shared client-runtime
+ * project atoms consumed by the mobile app.
+ */
+export const projectContentSearch = createEnvironmentRpcQueryAtomFamily(connectionAtomRuntime, {
+  label: "environment-data:projects:search-contents",
+  tag: WS_METHODS.projectsSearchContents,
+  staleTimeMs: 5_000,
+  idleTtlMs: 60_000,
+});
 export const environmentProjects = createEnvironmentProjectAtoms({
   catalogValueAtom: environmentCatalog.catalogValueAtom,
   snapshotAtom: environmentSnapshotAtom,
diff --git a/apps/web/src/state/queries.test.ts b/apps/web/src/state/queries.test.ts
new file mode 100644
index 00000000000..f8887dfb8ef
--- /dev/null
+++ b/apps/web/src/state/queries.test.ts
@@ -0,0 +1,25 @@
+import { EnvironmentId } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { areProjectPathSearchTargetsEqual } from "./queries";
+
+describe("areProjectPathSearchTargetsEqual", () => {
+  const target = {
+    environmentId: EnvironmentId.make("environment-a"),
+    cwd: "/project-a",
+    query: "index",
+  };
+
+  it("requires the environment, workspace, query, and entry kind to match", () => {
+    expect(areProjectPathSearchTargetsEqual(target, target)).toBe(true);
+    expect(
+      areProjectPathSearchTargetsEqual(target, {
+        ...target,
+        environmentId: EnvironmentId.make("environment-b"),
+      }),
+    ).toBe(false);
+    expect(areProjectPathSearchTargetsEqual(target, { ...target, cwd: "/project-b" })).toBe(false);
+    expect(areProjectPathSearchTargetsEqual(target, { ...target, query: "readme" })).toBe(false);
+    expect(areProjectPathSearchTargetsEqual(target, { ...target, kind: "file" })).toBe(false);
+  });
+});
diff --git a/apps/web/src/state/queries.ts b/apps/web/src/state/queries.ts
index a9564c2fd64..2a095b8f584 100644
--- a/apps/web/src/state/queries.ts
+++ b/apps/web/src/state/queries.ts
@@ -12,6 +12,8 @@ import { type VcsRefTarget } from "@t3tools/client-runtime/state/vcs";
 import type {
   EnvironmentId,
   OrchestrationThread,
+  ProjectContentMatch,
+  ProjectEntryKind,
   ThreadId,
   VcsListRefsResult,
   VcsRef,
@@ -24,16 +26,19 @@ import { useCallback, useEffect, useMemo, useState } from "react";
 import { appAtomRegistry } from "../rpc/atomRegistry";
 import { orchestrationEnvironment } from "./orchestration";
 import { isPaginatedBranchesNextPagePending } from "./paginatedBranches";
-import { projectEnvironment } from "./projects";
+import { projectContentSearch, projectEnvironment } from "./projects";
 import { useEnvironmentQuery } from "./query";
 import { useEnvironmentThread } from "./threads";
 import { vcsEnvironment } from "./vcs";
 
-const COMPOSER_PATH_SEARCH_DEBOUNCE_MS = 120;
+const PROJECT_PATH_SEARCH_DEBOUNCE_MS = 120;
 const COMPOSER_PATH_SEARCH_LIMIT = 80;
+const PROJECT_CONTENT_SEARCH_DEBOUNCE_MS = 120;
+const PROJECT_CONTENT_SEARCH_LIMIT = 500;
 const THREAD_SEARCH_DEBOUNCE_MS = 200;
 const VCS_REF_LIST_LIMIT = 100;
 const EMPTY_REFS: ReadonlyArray<VcsRef> = [];
+const EMPTY_CONTENT_MATCHES: ReadonlyArray<ProjectContentMatch> = [];
 const INITIAL_BRANCH_CURSORS = [undefined] as const;
 const EMPTY_THREAD_SEARCH_MATCHES: ReadonlyArray<EnvironmentThreadSearchMatch> = Object.freeze([]);
 const EMPTY_THREAD_SEARCH_ATOM = Atom.make({
@@ -229,26 +234,50 @@ export function usePaginatedBranches(target: VcsRefTarget) {
   };
 }
 
-export function useComposerPathSearch(target: ComposerPathSearchTarget) {
+type ProjectPathSearchTarget = ComposerPathSearchTarget & {
+  readonly kind?: ProjectEntryKind | undefined;
+};
+
+export function areProjectPathSearchTargetsEqual(
+  left: ProjectPathSearchTarget,
+  right: ProjectPathSearchTarget,
+): boolean {
+  return (
+    left.environmentId === right.environmentId &&
+    left.cwd === right.cwd &&
+    left.query === right.query &&
+    left.kind === right.kind
+  );
+}
+
+export function useProjectPathSearch(
+  target: ProjectPathSearchTarget,
+  limit: number,
+  options?: { readonly allowEmptyQuery?: boolean },
+) {
+  const allowEmptyQuery = options?.allowEmptyQuery === true;
   const normalizedTarget = useMemo(
     () => ({
       environmentId: target.environmentId,
       cwd: target.cwd,
-      query: target.query?.trim() ?? "",
+      query: target.query == null ? null : target.query.trim(),
+      kind: target.kind,
     }),
-    [target.cwd, target.environmentId, target.query],
+    [target.cwd, target.environmentId, target.kind, target.query],
   );
-  const debouncedTarget = useDebouncedValue(normalizedTarget, COMPOSER_PATH_SEARCH_DEBOUNCE_MS);
+  const debouncedTarget = useDebouncedValue(normalizedTarget, PROJECT_PATH_SEARCH_DEBOUNCE_MS);
   const result = useEnvironmentQuery(
     debouncedTarget.environmentId !== null &&
       debouncedTarget.cwd !== null &&
-      debouncedTarget.query.length > 0
+      debouncedTarget.query !== null &&
+      (allowEmptyQuery || debouncedTarget.query.length > 0)
       ? projectEnvironment.searchEntries({
           environmentId: debouncedTarget.environmentId,
           input: {
             cwd: debouncedTarget.cwd,
             query: debouncedTarget.query,
-            limit: COMPOSER_PATH_SEARCH_LIMIT,
+            limit,
+            ...(debouncedTarget.kind ? { kind: debouncedTarget.kind } : {}),
           },
         })
       : null,
@@ -257,11 +286,61 @@ export function useComposerPathSearch(target: ComposerPathSearchTarget) {
   return {
     entries: result.data?.entries ?? [],
     error: result.error,
-    isPending: normalizedTarget.query !== debouncedTarget.query || result.isPending,
+    isPending:
+      !areProjectPathSearchTargetsEqual(normalizedTarget, debouncedTarget) || result.isPending,
+    searchedQuery: debouncedTarget.query ?? "",
     refresh: result.refresh,
   };
 }
 
+export function useComposerPathSearch(target: ComposerPathSearchTarget) {
+  return useProjectPathSearch(target, COMPOSER_PATH_SEARCH_LIMIT);
+}
+
+interface ProjectContentSearchTarget {
+  readonly environmentId: EnvironmentId | null;
+  readonly cwd: string | null;
+  readonly query: string;
+  readonly caseSensitive: boolean;
+  readonly wholeWord: boolean;
+  readonly useRegex: boolean;
+}
+
+export function useProjectContentSearch(target: ProjectContentSearchTarget) {
+  // Whitespace is significant in content queries; trimming is only used to
+  // decide whether the input is blank.
+  const query = target.query;
+  const hasQuery = query.trim().length > 0;
+  const debouncedQuery = useDebouncedValue(query, PROJECT_CONTENT_SEARCH_DEBOUNCE_MS);
+  const result = useEnvironmentQuery(
+    target.environmentId !== null &&
+      target.cwd !== null &&
+      hasQuery &&
+      debouncedQuery.trim().length > 0
+      ? projectContentSearch({
+          environmentId: target.environmentId,
+          input: {
+            cwd: target.cwd,
+            query: debouncedQuery,
+            limit: PROJECT_CONTENT_SEARCH_LIMIT,
+            caseSensitive: target.caseSensitive,
+            wholeWord: target.wholeWord,
+            useRegex: target.useRegex,
+          },
+        })
+      : null,
+  );
+
+  return {
+    matches: result.data?.matches ?? EMPTY_CONTENT_MATCHES,
+    error: result.error,
+    isPending: hasQuery && (query !== debouncedQuery || result.isPending),
+    hasQuery,
+    truncated: result.data?.truncated ?? false,
+    invalidRegex: target.useRegex && result.data?.regexFallbackError !== undefined,
+  };
+}
+
 export function useCheckpointDiff(
   target: CheckpointDiffTarget,
   options?: { readonly enabled?: boolean },
diff --git a/docs/user/keybindings.md b/docs/user/keybindings.md
index 95f487f45f3..d94d3dc2dba 100644
--- a/docs/user/keybindings.md
+++ b/docs/user/keybindings.md
@@ -37,6 +37,10 @@ Examples: `mod+j`, `mod+shift+d`, `ctrl+l`, `cmd+k`.
 Commands are IDs like `terminal.toggle`, `commandPalette.toggle`, `preview.refresh`, and
 `chat.new`. Project scripts are addressable as `script.{id}.run`, for example `script.test.run`.
 
+`filePicker.toggle` opens file search for the active project and defaults to `mod+p`.
+`projectSearch.toggle` searches inside the active project's files and defaults to `mod+shift+f`.
+Repeating either shortcut closes that search, and switching shortcuts replaces the open search.
+
 The command palette searches active thread titles, projects, branches, user messages, and final
 agent responses across connected environments. Message matches show one labeled excerpt while
 keeping the thread's project, branch, and machine context visible. Message search begins after two
diff --git a/packages/contracts/src/keybindings.test.ts b/packages/contracts/src/keybindings.test.ts
index 33ecd38039f..4e8ea953770 100644
--- a/packages/contracts/src/keybindings.test.ts
+++ b/packages/contracts/src/keybindings.test.ts
@@ -59,6 +59,18 @@ it.effect("parses keybinding rules", () =>
     });
     assert.strictEqual(parsedCommandPalette.command, "commandPalette.toggle");
 
+    const parsedFilePicker = yield* decode(KeybindingRule, {
+      key: "mod+p",
+      command: "filePicker.toggle",
+    });
+    assert.strictEqual(parsedFilePicker.command, "filePicker.toggle");
+
+    const parsedProjectSearch = yield* decode(KeybindingRule, {
+      key: "mod+shift+f",
+      command: "projectSearch.toggle",
+    });
+    assert.strictEqual(parsedProjectSearch.command, "projectSearch.toggle");
+
     const parsedLocal = yield* decode(KeybindingRule, {
       key: "mod+shift+n",
       command: "chat.newLocal",
diff --git a/packages/contracts/src/keybindings.ts b/packages/contracts/src/keybindings.ts
index d966c1e7e61..14a2a9a4b30 100644
--- a/packages/contracts/src/keybindings.ts
+++ b/packages/contracts/src/keybindings.ts
@@ -63,6 +63,8 @@ const STATIC_KEYBINDING_COMMANDS = [
   "preview.zoomOut",
   "preview.resetZoom",
   "commandPalette.toggle",
+  "filePicker.toggle",
+  "projectSearch.toggle",
   "composer.stash",
   "chat.new",
   "chat.newLocal",
diff --git a/packages/contracts/src/project.test.ts b/packages/contracts/src/project.test.ts
index ea9d5a90e7c..8e6771cba88 100644
--- a/packages/contracts/src/project.test.ts
+++ b/packages/contracts/src/project.test.ts
@@ -3,10 +3,40 @@ import { describe, expect, it } from "vite-plus/test";
 
 import {
   ProjectReadFileError,
+  ProjectSearchContentsError,
+  ProjectSearchContentsInput,
   ProjectSearchEntriesError,
+  ProjectSearchEntriesInput,
   ProjectWriteFileError,
 } from "./project.ts";
 
+const decodeSearchEntriesInput = Schema.decodeUnknownSync(ProjectSearchEntriesInput);
+const decodeSearchContentsInput = Schema.decodeUnknownSync(ProjectSearchContentsInput);
+
+describe("project search inputs", () => {
+  it("allows an empty entries query for bounded frecency browsing", () => {
+    const decoded = decodeSearchEntriesInput({
+      cwd: "/workspace",
+      query: "   ",
+      limit: 10,
+      kind: "file",
+    });
+    expect(decoded.query).toBe("");
+  });
+
+  it("preserves whitespace in content search queries", () => {
+    const decoded = decodeSearchContentsInput({
+      cwd: "/workspace",
+      query: " foo ",
+      limit: 10,
+      caseSensitive: false,
+      wholeWord: false,
+      useRegex: false,
+    });
+    expect(decoded.query).toBe(" foo ");
+  });
+});
+
 describe("project RPC errors", () => {
   it("derives stable messages from structured request context while retaining causes", () => {
     const cause = new Error("sensitive platform detail");
@@ -39,6 +69,18 @@ describe("project RPC errors", () => {
     expect(readError.message).toBe("Failed to read workspace file 'src/index.ts' in '/workspace'.");
     expect(readError.message).not.toContain(cause.message);
     expect(readError.cause).toBe(cause);
+
+    const contentSearchError = new ProjectSearchContentsError({
+      cwd: "/workspace",
+      queryLength: "authorization: Bearer secret-token".length,
+      limit: 100,
+      failure: "search_index_search_failed",
+      cause,
+    });
+    expect(contentSearchError.message).toBe("Failed to search workspace contents in '/workspace'.");
+    expect(contentSearchError.message).not.toContain(cause.message);
+    expect(contentSearchError).not.toHaveProperty("query");
+    expect(contentSearchError.cause).toBe(cause);
   });
 
   it("decodes legacy message-only errors during rolling upgrades", () => {
diff --git a/packages/contracts/src/project.ts b/packages/contracts/src/project.ts
index d59b9770ad3..a1b11df73b2 100644
--- a/packages/contracts/src/project.ts
+++ b/packages/contracts/src/project.ts
@@ -1,19 +1,29 @@
 import * as Schema from "effect/Schema";
-import { NonNegativeInt, PositiveInt, TrimmedNonEmptyString } from "./baseSchemas.ts";
+import {
+  NonNegativeInt,
+  PositiveInt,
+  TrimmedNonEmptyString,
+  TrimmedString,
+} from "./baseSchemas.ts";
 
 const PROJECT_SEARCH_ENTRIES_MAX_LIMIT = 200;
+const PROJECT_SEARCH_CONTENTS_MAX_LIMIT = 500;
 const PROJECT_WRITE_FILE_PATH_MAX_LENGTH = 512;
 const PROJECT_READ_FILE_PATH_MAX_LENGTH = 512;
 
+export const ProjectEntryKind = Schema.Literals(["file", "directory"]);
+export type ProjectEntryKind = typeof ProjectEntryKind.Type;
+
 export const ProjectSearchEntriesInput = Schema.Struct({
   cwd: TrimmedNonEmptyString,
-  query: TrimmedNonEmptyString.check(Schema.isMaxLength(256)),
+  // An empty query is a bounded browse: the index returns frecency-ordered
+  // entries, which the file picker uses for its initial results.
+  query: TrimmedString.check(Schema.isMaxLength(256)),
   limit: PositiveInt.check(Schema.isLessThanOrEqualTo(PROJECT_SEARCH_ENTRIES_MAX_LIMIT)),
+  kind: Schema.optional(ProjectEntryKind),
 });
 export type ProjectSearchEntriesInput = typeof ProjectSearchEntriesInput.Type;
 
-const ProjectEntryKind = Schema.Literals(["file", "directory"]);
-
 export const ProjectEntry = Schema.Struct({
   path: TrimmedNonEmptyString,
   kind: ProjectEntryKind,
@@ -26,6 +36,39 @@ export const ProjectSearchEntriesResult = Schema.Struct({
 });
 export type ProjectSearchEntriesResult = typeof ProjectSearchEntriesResult.Type;
 
+export const ProjectSearchContentsInput = Schema.Struct({
+  cwd: TrimmedNonEmptyString,
+  // Whitespace is significant in content queries (" foo", regex trailing
+  // spaces), so the query is deliberately not trimmed on the wire.
+  query: Schema.String.check(Schema.isNonEmpty(), Schema.isMaxLength(256)),
+  limit: PositiveInt.check(Schema.isLessThanOrEqualTo(PROJECT_SEARCH_CONTENTS_MAX_LIMIT)),
+  caseSensitive: Schema.Boolean,
+  wholeWord: Schema.Boolean,
+  useRegex: Schema.Boolean,
+});
+export type ProjectSearchContentsInput = typeof ProjectSearchContentsInput.Type;
+
+export const ProjectContentMatchRange = Schema.Struct({
+  start: NonNegativeInt,
+  end: NonNegativeInt,
+});
+export type ProjectContentMatchRange = typeof ProjectContentMatchRange.Type;
+
+export const ProjectContentMatch = Schema.Struct({
+  path: TrimmedNonEmptyString,
+  lineNumber: PositiveInt,
+  lineContent: Schema.String,
+  matchRanges: Schema.Array(ProjectContentMatchRange),
+});
+export type ProjectContentMatch = typeof ProjectContentMatch.Type;
+
+export const ProjectSearchContentsResult = Schema.Struct({
+  matches: Schema.Array(ProjectContentMatch),
+  truncated: Schema.Boolean,
+  regexFallbackError: Schema.optional(Schema.String),
+});
+export type ProjectSearchContentsResult = typeof ProjectSearchContentsResult.Type;
+
 export const ProjectListEntriesInput = Schema.Struct({
   cwd: TrimmedNonEmptyString,
 });
@@ -94,6 +137,37 @@ export class ProjectSearchEntriesError extends Schema.TaggedErrorClass<ProjectSe
   }
 }
 
+export class ProjectSearchContentsError extends Schema.TaggedErrorClass<ProjectSearchContentsError>()(
+  "ProjectSearchContentsError",
+  {
+    cwd: Schema.optional(TrimmedNonEmptyString),
+    queryLength: Schema.optional(NonNegativeInt),
+    limit: Schema.optional(PositiveInt),
+    failure: Schema.optional(ProjectEntriesFailure),
+    normalizedCwd: Schema.optional(TrimmedNonEmptyString),
+    timeout: Schema.optional(TrimmedNonEmptyString),
+    detail: Schema.optional(TrimmedNonEmptyString),
+    message: TrimmedNonEmptyString,
+    cause: Schema.optional(Schema.Defect()),
+  },
+) {
+  // @effect-diagnostics-next-line overriddenSchemaConstructor:off
+  constructor(
+    props: ProjectEntriesFailureContext & {
+      readonly cwd: string;
+      readonly queryLength: number;
+      readonly limit: number;
+    },
+  ) {
+    super({
+      ...props,
+      message:
+        decodedProjectErrorMessage(props) ??
+        `Failed to search workspace contents in '${props.cwd}'.`,
+    } as any);
+  }
+}
+
 export class ProjectListEntriesError extends Schema.TaggedErrorClass<ProjectListEntriesError>()(
   "ProjectListEntriesError",
   {
diff --git a/packages/contracts/src/rpc.ts b/packages/contracts/src/rpc.ts
index 17fbd57ddad..400011f8843 100644
--- a/packages/contracts/src/rpc.ts
+++ b/packages/contracts/src/rpc.ts
@@ -76,6 +76,9 @@ import {
   ProjectReadFileError,
   ProjectReadFileInput,
   ProjectReadFileResult,
+  ProjectSearchContentsError,
+  ProjectSearchContentsInput,
+  ProjectSearchContentsResult,
   ProjectSearchEntriesError,
   ProjectSearchEntriesInput,
   ProjectSearchEntriesResult,
@@ -166,6 +169,7 @@ export const WS_METHODS = {
   projectsRemove: "projects.remove",
   projectsListEntries: "projects.listEntries",
   projectsReadFile: "projects.readFile",
+  projectsSearchContents: "projects.searchContents",
   projectsSearchEntries: "projects.searchEntries",
   projectsWriteFile: "projects.writeFile",
 
@@ -438,6 +442,12 @@ export const WsProjectsSearchEntriesRpc = Rpc.make(WS_METHODS.projectsSearchEntr
   error: Schema.Union([ProjectSearchEntriesError, EnvironmentAuthorizationError]),
 });
 
+export const WsProjectsSearchContentsRpc = Rpc.make(WS_METHODS.projectsSearchContents, {
+  payload: ProjectSearchContentsInput,
+  success: ProjectSearchContentsResult,
+  error: Schema.Union([ProjectSearchContentsError, EnvironmentAuthorizationError]),
+});
+
 export const WsProjectsListEntriesRpc = Rpc.make(WS_METHODS.projectsListEntries, {
   payload: ProjectListEntriesInput,
   success: ProjectListEntriesResult,
@@ -801,6 +811,7 @@ export const WsRpcGroup = RpcGroup.make(
   WsSourceControlPublishRepositoryRpc,
   WsProjectsListEntriesRpc,
   WsProjectsReadFileRpc,
+  WsProjectsSearchContentsRpc,
   WsProjectsSearchEntriesRpc,
   WsProjectsWriteFileRpc,
   WsShellOpenInEditorRpc,
diff --git a/packages/shared/src/keybindings.ts b/packages/shared/src/keybindings.ts
index 0688cf07254..6add9f47844 100644
--- a/packages/shared/src/keybindings.ts
+++ b/packages/shared/src/keybindings.ts
@@ -35,6 +35,8 @@ export const DEFAULT_KEYBINDINGS: ReadonlyArray<KeybindingRule> = [
   { key: "mod+-", command: "preview.zoomOut", when: "previewFocus" },
   { key: "mod+0", command: "preview.resetZoom", when: "previewFocus" },
   { key: "mod+k", command: "commandPalette.toggle", when: "!terminalFocus" },
+  { key: "mod+p", command: "filePicker.toggle", when: "!terminalFocus" },
+  { key: "mod+shift+f", command: "projectSearch.toggle", when: "!terminalFocus" },
   { key: "mod+s", command: "composer.stash", when: "!terminalFocus" },
   { key: "mod+n", command: "chat.new", when: "!terminalFocus" },
   { key: "mod+shift+o", command: "chat.new", when: "!terminalFocus" },

From 6154b46cb86b038f1b54c32690a794ac639520ca Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Thu, 30 Jul 2026 16:57:00 +0200
Subject: [PATCH 26/34] Check for mobile app updates on launch (#4958)

Co-authored-by: codex <codex@users.noreply.github.com>
---
 .../src/features/home/HomeRouteScreen.tsx     |   6 +
 .../features/settings/SettingsRouteScreen.tsx | 117 ++------
 .../src/features/updates/app-updates.test.ts  | 252 ++++++++++++++++++
 .../src/features/updates/app-updates.ts       | 228 ++++++++++++++++
 4 files changed, 512 insertions(+), 91 deletions(-)
 create mode 100644 apps/mobile/src/features/updates/app-updates.test.ts
 create mode 100644 apps/mobile/src/features/updates/app-updates.ts

diff --git a/apps/mobile/src/features/home/HomeRouteScreen.tsx b/apps/mobile/src/features/home/HomeRouteScreen.tsx
index c172694b6c5..62f6e324602 100644
--- a/apps/mobile/src/features/home/HomeRouteScreen.tsx
+++ b/apps/mobile/src/features/home/HomeRouteScreen.tsx
@@ -11,6 +11,7 @@ import { useSavedRemoteConnections } from "../../state/use-remote-environment-re
 import { useAdaptiveWorkspaceLayout } from "../layout/AdaptiveWorkspaceLayout";
 import { WorkspaceEmptyDetail } from "../layout/WorkspaceEmptyDetail";
 import { WorkspaceSidebarToolbar } from "../layout/workspace-sidebar-toolbar";
+import { checkForAppUpdateOnLaunch } from "../updates/app-updates";
 import { AndroidHomeFabLayout } from "./AndroidHomeFab";
 import { HomeScreen } from "./HomeScreen";
 import { HomeHeader } from "./HomeHeader";
@@ -29,6 +30,11 @@ export function HomeRouteScreen() {
   const { savedConnectionsById } = useSavedRemoteConnections();
   const navigation = useNavigation();
   const [searchQuery, setSearchQuery] = useState("");
+
+  useEffect(() => {
+    void checkForAppUpdateOnLaunch();
+  }, []);
+
   const { archiveThread, confirmDeleteThread, settleThread, unsettleThread } =
     useThreadListActions();
   const pendingTasks = usePendingNewTasks();
diff --git a/apps/mobile/src/features/settings/SettingsRouteScreen.tsx b/apps/mobile/src/features/settings/SettingsRouteScreen.tsx
index f354bcd29ac..49adfe75cb2 100644
--- a/apps/mobile/src/features/settings/SettingsRouteScreen.tsx
+++ b/apps/mobile/src/features/settings/SettingsRouteScreen.tsx
@@ -9,19 +9,10 @@ import { SymbolView } from "../../components/AppSymbol";
 import * as Effect from "effect/Effect";
 import { AsyncResult } from "effect/unstable/reactivity";
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
-import {
-  ActivityIndicator,
-  Alert,
-  Linking,
-  Platform,
-  Pressable,
-  ScrollView,
-  View,
-} from "react-native";
+import { Alert, Linking, Platform, Pressable, ScrollView, View } from "react-native";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 
 import {
-  type AtomCommandResult,
   isAtomCommandInterrupted,
   reportAtomCommandResult,
   settleAsyncResult,
@@ -47,6 +38,11 @@ import { runtime } from "../../lib/runtime";
 import { useThemeColor } from "../../lib/useThemeColor";
 import { mobilePreferencesAtom, updateMobilePreferencesAtom } from "../../state/preferences";
 import { useThreadListV2Enabled } from "../threads/use-thread-list-v2-enabled";
+import {
+  type AppUpdateCheckState,
+  registerHiddenUpdateTap,
+  runAppUpdateCheck,
+} from "../updates/app-updates";
 import { useSavedRemoteConnections } from "../../state/use-remote-environment-registry";
 import { SettingsRow } from "./components/SettingsRow";
 import { SettingsSection } from "./components/SettingsSection";
@@ -578,12 +574,11 @@ function BetaSettingsSection() {
   );
 }
 
-type UpdateCheckState = "idle" | "checking" | "downloading" | "restarting" | "current";
-
 function AppSettingsSection() {
   const icon = useThemeColor("--color-icon");
-  const [updateState, setUpdateState] = useState<UpdateCheckState>("idle");
+  const [updateState, setUpdateState] = useState<AppUpdateCheckState>("idle");
   const updateInFlight = useRef(false);
+  const hiddenUpdateTapCount = useRef(0);
 
   const version = Constants.expoConfig?.version ?? "0.0.0";
   // Fall back to "production" to match resolveAppVariant in app.config.ts, so a
@@ -591,22 +586,11 @@ function AppSettingsSection() {
   const variant = (Constants.expoConfig?.extra?.appVariant as string | undefined) ?? "production";
   const variantLabel = variant === "production" ? "" : capitalize(variant);
   const versionLabel = variantLabel ? `${version} · ${variantLabel}` : version;
-  // Which JS is actually running: the bundle shipped in the binary, or an OTA
-  // update downloaded on top of it. Surfacing this makes "am I even on the
-  // right build?" answerable at a glance.
-  const bundleLabel = Updates.isEnabled
-    ? Updates.isEmbeddedLaunch
-      ? "Embedded"
-      : Updates.updateId
-        ? `OTA ${Updates.updateId.slice(0, 7)}`
-        : null
-    : null;
-
   const busy =
     updateState === "checking" || updateState === "downloading" || updateState === "restarting";
 
   // "Up to date" is a transient acknowledgement, not a state worth persisting —
-  // drop back to the bundle label so the row keeps answering "what am I running?".
+  // return the version row to its normal, deliberately quiet state.
   useEffect(() => {
     if (updateState !== "current") return;
     const timer = setTimeout(() => setUpdateState("idle"), 3000);
@@ -619,12 +603,24 @@ function AppSettingsSection() {
     if (updateInFlight.current) return;
     updateInFlight.current = true;
     try {
-      await runUpdateCheck(setUpdateState);
+      await runAppUpdateCheck({
+        onFailure: (message) => Alert.alert("Update failed", message),
+        onStateChange: setUpdateState,
+      });
     } finally {
       updateInFlight.current = false;
     }
   }, []);
 
+  const handleVersionPress = useCallback(() => {
+    if (!Updates.isEnabled || updateInFlight.current) return;
+    const tap = registerHiddenUpdateTap(hiddenUpdateTapCount.current);
+    hiddenUpdateTapCount.current = tap.nextCount;
+    if (tap.shouldCheck) {
+      void checkForUpdate();
+    }
+  }, [checkForUpdate]);
+
   const statusLabel =
     updateState === "checking"
       ? "Checking…"
@@ -634,7 +630,7 @@ function AppSettingsSection() {
           ? "Restarting…"
           : updateState === "current"
             ? "Up to date"
-            : bundleLabel;
+            : null;
 
   const versionRow = (
     <View className="flex-row items-center gap-4 p-4">
@@ -652,21 +648,6 @@ function AppSettingsSection() {
           <Text className="text-xs text-foreground-muted/70">{statusLabel}</Text>
         ) : null}
       </View>
-      {Updates.isEnabled ? (
-        <View className="w-[22px] items-center">
-          {busy ? (
-            <ActivityIndicator color={icon} size="small" />
-          ) : (
-            <SymbolView
-              name="arrow.clockwise"
-              size={18}
-              tintColor={icon}
-              type="monochrome"
-              weight="semibold"
-            />
-          )}
-        </View>
-      ) : null}
     </View>
   );
 
@@ -676,10 +657,10 @@ function AppSettingsSection() {
       <SettingsRow icon="doc.text" label="Legal" fullScreenTarget="SettingsLegal" />
       {Updates.isEnabled ? (
         <Pressable
-          accessibilityLabel="Check for updates"
-          accessibilityRole="button"
+          accessibilityLabel={`Version ${versionLabel}`}
+          accessibilityRole="text"
           disabled={busy}
-          onPress={() => void checkForUpdate()}
+          onPress={handleVersionPress}
         >
           {versionRow}
         </Pressable>
@@ -690,52 +671,6 @@ function AppSettingsSection() {
   );
 }
 
-async function runUpdateCheck(setUpdateState: (state: UpdateCheckState) => void): Promise<void> {
-  setUpdateState("checking");
-  const check = await settlePromise(() => Updates.checkForUpdateAsync());
-  if (check._tag === "Failure") {
-    reportUpdateFailure(check, "Could not check for updates.");
-    setUpdateState("idle");
-    return;
-  }
-  // A rollback directive (`eas update:rollback`) arrives as isAvailable: false
-  // with isRollBackToEmbedded: true — there is nothing newer to install, but the
-  // running OTA still has to be dropped for the embedded bundle.
-  if (!check.value.isAvailable && !check.value.isRollBackToEmbedded) {
-    setUpdateState("current");
-    return;
-  }
-
-  setUpdateState("downloading");
-  const fetched = await settlePromise(() => Updates.fetchUpdateAsync());
-  if (fetched._tag === "Failure") {
-    reportUpdateFailure(fetched, "Could not download the update.");
-    setUpdateState("idle");
-    return;
-  }
-  // isNew is always false for a rollback, so it can't be the sole gate here either.
-  if (!fetched.value.isNew && !fetched.value.isRollBackToEmbedded) {
-    setUpdateState("current");
-    return;
-  }
-
-  setUpdateState("restarting");
-  // reloadAsync never resolves on success — the JS context is torn down — so
-  // reaching the failure branch below is the only way this returns.
-  const reloaded = await settlePromise(() => Updates.reloadAsync());
-  if (reloaded._tag === "Failure") {
-    reportUpdateFailure(reloaded, "Downloaded, but could not restart the app.");
-    setUpdateState("idle");
-  }
-}
-
-function reportUpdateFailure(result: AtomCommandResult<unknown, unknown>, fallback: string): void {
-  reportAtomCommandResult(result, { label: "app update check" });
-  if (result._tag !== "Failure" || isAtomCommandInterrupted(result)) return;
-  const error = squashAtomCommandFailure(result);
-  Alert.alert("Update failed", error instanceof Error ? error.message : fallback);
-}
-
 function capitalize(value: string): string {
   return value.length > 0 ? value.charAt(0).toUpperCase() + value.slice(1) : value;
 }
diff --git a/apps/mobile/src/features/updates/app-updates.test.ts b/apps/mobile/src/features/updates/app-updates.test.ts
new file mode 100644
index 00000000000..474c99668cd
--- /dev/null
+++ b/apps/mobile/src/features/updates/app-updates.test.ts
@@ -0,0 +1,252 @@
+import { describe, expect, it, vi } from "vite-plus/test";
+
+import {
+  createAppUpdateLaunchCheck,
+  registerHiddenUpdateTap,
+  runAppUpdateCheck,
+  type AppUpdateCheckState,
+  type AppUpdateClient,
+} from "./app-updates";
+
+vi.mock("expo-updates", () => ({
+  isEnabled: true,
+  checkForUpdateAsync: vi.fn(),
+  fetchUpdateAsync: vi.fn(),
+  reloadAsync: vi.fn(),
+}));
+
+function makeUpdateClient(overrides: Partial<AppUpdateClient> = {}): AppUpdateClient {
+  return {
+    isEnabled: true,
+    checkForUpdateAsync: vi.fn(async () => ({
+      isAvailable: false,
+      isRollBackToEmbedded: false,
+    })),
+    fetchUpdateAsync: vi.fn(async () => ({
+      isNew: true,
+      isRollBackToEmbedded: false,
+    })),
+    reloadAsync: vi.fn(async () => {}),
+    ...overrides,
+  };
+}
+
+describe("runAppUpdateCheck", () => {
+  it("downloads and restarts when a new update is available", async () => {
+    const client = makeUpdateClient({
+      checkForUpdateAsync: vi.fn(async () => ({
+        isAvailable: true,
+        isRollBackToEmbedded: false,
+      })),
+    });
+    const states: AppUpdateCheckState[] = [];
+
+    await runAppUpdateCheck({ client, onStateChange: (state) => states.push(state) });
+
+    expect(client.checkForUpdateAsync).toHaveBeenCalledOnce();
+    expect(client.fetchUpdateAsync).toHaveBeenCalledOnce();
+    expect(client.reloadAsync).toHaveBeenCalledOnce();
+    expect(states).toEqual(["checking", "downloading", "restarting"]);
+  });
+
+  it("restarts into the embedded bundle for a rollback directive", async () => {
+    const client = makeUpdateClient({
+      checkForUpdateAsync: vi.fn(async () => ({
+        isAvailable: false,
+        isRollBackToEmbedded: true,
+      })),
+      fetchUpdateAsync: vi.fn(async () => ({
+        isNew: false,
+        isRollBackToEmbedded: true,
+      })),
+    });
+
+    await runAppUpdateCheck({ client });
+
+    expect(client.fetchUpdateAsync).toHaveBeenCalledOnce();
+    expect(client.reloadAsync).toHaveBeenCalledOnce();
+  });
+
+  it("stops quietly when the running bundle is current", async () => {
+    const client = makeUpdateClient();
+    const states: AppUpdateCheckState[] = [];
+
+    await runAppUpdateCheck({ client, onStateChange: (state) => states.push(state) });
+
+    expect(client.fetchUpdateAsync).not.toHaveBeenCalled();
+    expect(client.reloadAsync).not.toHaveBeenCalled();
+    expect(states).toEqual(["checking", "current"]);
+  });
+
+  it("reports manual failures without continuing the update", async () => {
+    const reportError = vi.spyOn(console, "error").mockImplementation(() => {});
+    const client = makeUpdateClient({
+      checkForUpdateAsync: vi.fn(async () => {
+        throw new Error("offline");
+      }),
+    });
+    const failures: string[] = [];
+    const states: AppUpdateCheckState[] = [];
+
+    await runAppUpdateCheck({
+      client,
+      onFailure: (message) => failures.push(message),
+      onStateChange: (state) => states.push(state),
+    });
+
+    expect(client.fetchUpdateAsync).not.toHaveBeenCalled();
+    expect(failures).toEqual(["offline"]);
+    expect(states).toEqual(["checking", "idle"]);
+    reportError.mockRestore();
+  });
+
+  it("coalesces overlapping launch and manual checks", async () => {
+    let resolveCheck!: (result: {
+      readonly isAvailable: boolean;
+      readonly isRollBackToEmbedded: boolean;
+    }) => void;
+    const checkResult = new Promise<{
+      readonly isAvailable: boolean;
+      readonly isRollBackToEmbedded: boolean;
+    }>((resolve) => {
+      resolveCheck = resolve;
+    });
+    const client = makeUpdateClient({
+      checkForUpdateAsync: vi.fn(() => checkResult),
+    });
+    const checkOnLaunch = createAppUpdateLaunchCheck(client);
+    const manualStates: AppUpdateCheckState[] = [];
+
+    const launchCheck = checkOnLaunch();
+    const manualCheck = runAppUpdateCheck({
+      client,
+      onStateChange: (state) => manualStates.push(state),
+    });
+
+    expect(client.checkForUpdateAsync).toHaveBeenCalledOnce();
+    expect(manualStates).toEqual(["checking"]);
+
+    resolveCheck({
+      isAvailable: false,
+      isRollBackToEmbedded: false,
+    });
+    await Promise.all([launchCheck, manualCheck]);
+
+    expect(manualStates).toEqual(["checking", "current"]);
+
+    await runAppUpdateCheck({ client });
+    expect(client.checkForUpdateAsync).toHaveBeenCalledTimes(2);
+  });
+
+  it("forwards failures to a manual check coalesced with the launch check", async () => {
+    const reportError = vi.spyOn(console, "error").mockImplementation(() => {});
+    let rejectCheck!: (error: Error) => void;
+    const checkResult = new Promise<{
+      readonly isAvailable: boolean;
+      readonly isRollBackToEmbedded: boolean;
+    }>((_resolve, reject) => {
+      rejectCheck = reject;
+    });
+    const client = makeUpdateClient({
+      checkForUpdateAsync: vi.fn(() => checkResult),
+    });
+    const checkOnLaunch = createAppUpdateLaunchCheck(client);
+    const failures: string[] = [];
+    const manualStates: AppUpdateCheckState[] = [];
+
+    const launchCheck = checkOnLaunch();
+    const manualCheck = runAppUpdateCheck({
+      client,
+      onFailure: (message) => failures.push(message),
+      onStateChange: (state) => manualStates.push(state),
+    });
+
+    rejectCheck(new Error("offline"));
+    await Promise.all([launchCheck, manualCheck]);
+
+    expect(client.checkForUpdateAsync).toHaveBeenCalledOnce();
+    expect(failures).toEqual(["offline"]);
+    expect(manualStates).toEqual(["checking", "idle"]);
+    reportError.mockRestore();
+  });
+
+  it("publishes the in-flight check before a state callback can re-enter", async () => {
+    let resolveCheck!: (result: {
+      readonly isAvailable: boolean;
+      readonly isRollBackToEmbedded: boolean;
+    }) => void;
+    const checkResult = new Promise<{
+      readonly isAvailable: boolean;
+      readonly isRollBackToEmbedded: boolean;
+    }>((resolve) => {
+      resolveCheck = resolve;
+    });
+    const client = makeUpdateClient({
+      checkForUpdateAsync: vi.fn(() => checkResult),
+    });
+    const reentrantStates: AppUpdateCheckState[] = [];
+    let reentrantCheck: Promise<void> | undefined;
+    let didReenter = false;
+
+    const initialCheck = runAppUpdateCheck({
+      client,
+      onStateChange: (state) => {
+        if (state !== "checking" || didReenter) return;
+        didReenter = true;
+        reentrantCheck = runAppUpdateCheck({
+          client,
+          onStateChange: (reentrantState) => reentrantStates.push(reentrantState),
+        });
+      },
+    });
+
+    expect(client.checkForUpdateAsync).toHaveBeenCalledOnce();
+    expect(reentrantCheck).toBeDefined();
+    expect(reentrantStates).toEqual(["checking"]);
+
+    resolveCheck({
+      isAvailable: false,
+      isRollBackToEmbedded: false,
+    });
+    await Promise.all([initialCheck, reentrantCheck]);
+
+    expect(client.checkForUpdateAsync).toHaveBeenCalledOnce();
+    expect(reentrantStates).toEqual(["checking", "current"]);
+  });
+});
+
+describe("createAppUpdateLaunchCheck", () => {
+  it("checks at most once for each JavaScript launch", async () => {
+    const client = makeUpdateClient();
+    const checkOnLaunch = createAppUpdateLaunchCheck(client);
+
+    const first = checkOnLaunch();
+    const second = checkOnLaunch();
+    await first;
+
+    expect(second).toBeUndefined();
+    expect(client.checkForUpdateAsync).toHaveBeenCalledOnce();
+  });
+
+  it("does nothing when Expo updates are disabled", () => {
+    const client = makeUpdateClient({ isEnabled: false });
+    const checkOnLaunch = createAppUpdateLaunchCheck(client);
+
+    expect(checkOnLaunch()).toBeUndefined();
+    expect(client.checkForUpdateAsync).not.toHaveBeenCalled();
+  });
+});
+
+describe("registerHiddenUpdateTap", () => {
+  it("unlocks the manual check on the fifth tap", () => {
+    let count = 0;
+
+    for (let tap = 1; tap <= 5; tap += 1) {
+      const result = registerHiddenUpdateTap(count);
+      expect(result.shouldCheck).toBe(tap === 5);
+      count = result.nextCount;
+    }
+
+    expect(count).toBe(0);
+  });
+});
diff --git a/apps/mobile/src/features/updates/app-updates.ts b/apps/mobile/src/features/updates/app-updates.ts
new file mode 100644
index 00000000000..ab896b53c07
--- /dev/null
+++ b/apps/mobile/src/features/updates/app-updates.ts
@@ -0,0 +1,228 @@
+import * as Updates from "expo-updates";
+
+import {
+  type AtomCommandResult,
+  isAtomCommandInterrupted,
+  reportAtomCommandResult,
+  settlePromise,
+  squashAtomCommandFailure,
+} from "@t3tools/client-runtime/state/runtime";
+
+export type AppUpdateCheckState = "idle" | "checking" | "downloading" | "restarting" | "current";
+
+export interface AppUpdateClient {
+  readonly isEnabled: boolean;
+  readonly checkForUpdateAsync: () => Promise<{
+    readonly isAvailable: boolean;
+    readonly isRollBackToEmbedded: boolean;
+  }>;
+  readonly fetchUpdateAsync: () => Promise<{
+    readonly isNew: boolean;
+    readonly isRollBackToEmbedded: boolean;
+  }>;
+  readonly reloadAsync: () => Promise<void>;
+}
+
+interface AppUpdateCheckOptions {
+  readonly client?: AppUpdateClient;
+  readonly onFailure?: (message: string) => void;
+  readonly onStateChange?: (state: AppUpdateCheckState) => void;
+}
+
+interface AppUpdateCheckProgress {
+  failure: string | undefined;
+  state: AppUpdateCheckState | undefined;
+}
+
+interface AppUpdateCheckInFlight {
+  readonly failureListeners: Set<NonNullable<AppUpdateCheckOptions["onFailure"]>>;
+  readonly progress: AppUpdateCheckProgress;
+  readonly promise: Promise<void>;
+  readonly stateListeners: Set<NonNullable<AppUpdateCheckOptions["onStateChange"]>>;
+}
+
+interface Deferred {
+  readonly promise: Promise<void>;
+  readonly reject: (cause: unknown) => void;
+  readonly resolve: () => void;
+}
+
+const HIDDEN_UPDATE_TAP_COUNT = 5;
+let appUpdateCheckInFlight: AppUpdateCheckInFlight | undefined;
+
+/**
+ * Keeps the manual update affordance discoverable only to someone deliberately
+ * tapping the version row five times.
+ */
+export function registerHiddenUpdateTap(count: number): {
+  readonly nextCount: number;
+  readonly shouldCheck: boolean;
+} {
+  const nextCount = count + 1;
+  if (nextCount >= HIDDEN_UPDATE_TAP_COUNT) {
+    return {
+      nextCount: 0,
+      shouldCheck: true,
+    };
+  }
+  return {
+    nextCount,
+    shouldCheck: false,
+  };
+}
+
+export async function runAppUpdateCheck(options: AppUpdateCheckOptions = {}): Promise<void> {
+  const client = options.client ?? Updates;
+  if (!client.isEnabled) return;
+
+  if (appUpdateCheckInFlight) {
+    await observeAppUpdateCheck(appUpdateCheckInFlight, options);
+    return;
+  }
+
+  const progress: AppUpdateCheckProgress = {
+    failure: undefined,
+    state: undefined,
+  };
+  const failureListeners = new Set<NonNullable<AppUpdateCheckOptions["onFailure"]>>();
+  const stateListeners = new Set<NonNullable<AppUpdateCheckOptions["onStateChange"]>>();
+  if (options.onFailure) failureListeners.add(options.onFailure);
+  if (options.onStateChange) stateListeners.add(options.onStateChange);
+
+  const deferred = createDeferred();
+  const inFlight: AppUpdateCheckInFlight = {
+    failureListeners,
+    progress,
+    promise: deferred.promise,
+    stateListeners,
+  };
+  // Publish the operation before any state listener can synchronously re-enter.
+  appUpdateCheckInFlight = inFlight;
+
+  const execution = performAppUpdateCheck(client, {
+    onFailure: (message) => {
+      progress.failure = message;
+      notifyListeners(failureListeners, message);
+    },
+    onStateChange: (state) => {
+      progress.state = state;
+      notifyListeners(stateListeners, state);
+    },
+  });
+  void execution.then(deferred.resolve, deferred.reject);
+
+  try {
+    await deferred.promise;
+  } finally {
+    if (appUpdateCheckInFlight === inFlight) {
+      appUpdateCheckInFlight = undefined;
+    }
+  }
+}
+
+function createDeferred(): Deferred {
+  let reject!: Deferred["reject"];
+  let resolve!: Deferred["resolve"];
+  const promise = new Promise<void>((resolvePromise, rejectPromise) => {
+    resolve = () => resolvePromise();
+    reject = rejectPromise;
+  });
+  return { promise, reject, resolve };
+}
+
+function notifyListeners<A>(listeners: ReadonlySet<(value: A) => void>, value: A): void {
+  // A listener can synchronously subscribe another caller. Snapshot so that
+  // caller receives only observeAppUpdateCheck's explicit current-value replay.
+  const snapshot = Array.from(listeners);
+  for (const listener of snapshot) listener(value);
+}
+
+async function observeAppUpdateCheck(
+  inFlight: AppUpdateCheckInFlight,
+  options: AppUpdateCheckOptions,
+): Promise<void> {
+  const onFailure = options.onFailure;
+  const onStateChange = options.onStateChange;
+
+  if (onFailure) {
+    inFlight.failureListeners.add(onFailure);
+    if (inFlight.progress.failure) onFailure(inFlight.progress.failure);
+  }
+  if (onStateChange) {
+    inFlight.stateListeners.add(onStateChange);
+    if (inFlight.progress.state) onStateChange(inFlight.progress.state);
+  }
+
+  try {
+    await inFlight.promise;
+  } finally {
+    if (onFailure) inFlight.failureListeners.delete(onFailure);
+    if (onStateChange) inFlight.stateListeners.delete(onStateChange);
+  }
+}
+
+async function performAppUpdateCheck(
+  client: AppUpdateClient,
+  options: AppUpdateCheckOptions,
+): Promise<void> {
+  const setState = options.onStateChange ?? (() => {});
+
+  setState("checking");
+  const check = await settlePromise(() => client.checkForUpdateAsync());
+  if (check._tag === "Failure") {
+    reportUpdateFailure(check, "Could not check for updates.", options.onFailure);
+    setState("idle");
+    return;
+  }
+  // A rollback directive (`eas update:rollback`) arrives as isAvailable: false
+  // with isRollBackToEmbedded: true. The running OTA still has to be dropped.
+  if (!check.value.isAvailable && !check.value.isRollBackToEmbedded) {
+    setState("current");
+    return;
+  }
+
+  setState("downloading");
+  const fetched = await settlePromise(() => client.fetchUpdateAsync());
+  if (fetched._tag === "Failure") {
+    reportUpdateFailure(fetched, "Could not download the update.", options.onFailure);
+    setState("idle");
+    return;
+  }
+  // isNew is always false for a rollback, so it cannot be the sole gate.
+  if (!fetched.value.isNew && !fetched.value.isRollBackToEmbedded) {
+    setState("current");
+    return;
+  }
+
+  setState("restarting");
+  const reloaded = await settlePromise(() => client.reloadAsync());
+  if (reloaded._tag === "Failure") {
+    reportUpdateFailure(reloaded, "Downloaded, but could not restart the app.", options.onFailure);
+    setState("idle");
+  }
+}
+
+function reportUpdateFailure(
+  result: AtomCommandResult<unknown, unknown>,
+  fallback: string,
+  onFailure: AppUpdateCheckOptions["onFailure"],
+): void {
+  reportAtomCommandResult(result, { label: "app update check" });
+  if (result._tag !== "Failure" || isAtomCommandInterrupted(result)) return;
+  const error = squashAtomCommandFailure(result);
+  onFailure?.(error instanceof Error ? error.message : fallback);
+}
+
+export function createAppUpdateLaunchCheck(
+  client: AppUpdateClient = Updates,
+): () => Promise<void> | undefined {
+  let started = false;
+
+  return () => {
+    if (started || !client.isEnabled) return undefined;
+    started = true;
+    return runAppUpdateCheck({ client });
+  };
+}
+
+export const checkForAppUpdateOnLaunch = createAppUpdateLaunchCheck();

From 323dc321a2f8bec2160e6e35f94d07c5bb949084 Mon Sep 17 00:00:00 2001
From: Gabriel De Andrade <30420087+gabrielelpidio@users.noreply.github.com>
Date: Thu, 30 Jul 2026 12:01:14 -0400
Subject: [PATCH 27/34] fix(mobile): support pre-Liquid-Glass iOS bottom
 toolbar (#4984)

---
 .../archive/ArchivedThreadsScreen.tsx         | 14 ++-
 .../features/files/ThreadFilesRouteScreen.tsx |  8 +-
 apps/mobile/src/features/home/HomeHeader.tsx  | 97 +++++++++----------
 apps/mobile/src/features/home/HomeScreen.tsx  | 18 +++-
 .../layout/native-mail-search-toolbar.ts      | 11 +++
 apps/mobile/src/native/StackHeader.tsx        |  9 +-
 6 files changed, 96 insertions(+), 61 deletions(-)

diff --git a/apps/mobile/src/features/archive/ArchivedThreadsScreen.tsx b/apps/mobile/src/features/archive/ArchivedThreadsScreen.tsx
index 916802e9faf..01440007bc6 100644
--- a/apps/mobile/src/features/archive/ArchivedThreadsScreen.tsx
+++ b/apps/mobile/src/features/archive/ArchivedThreadsScreen.tsx
@@ -29,7 +29,10 @@ import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { relativeTime } from "../../lib/time";
 import { useThemeColor } from "../../lib/useThemeColor";
 import { ThreadSwipeable } from "../home/thread-swipe-actions";
-import { createNativeMailSearchToolbarItem } from "../layout/native-mail-search-toolbar";
+import {
+  createNativeMailSearchToolbarItem,
+  NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED,
+} from "../layout/native-mail-search-toolbar";
 import type { ArchivedThreadGroup, ArchivedThreadSortOrder } from "./archivedThreadList";
 
 export interface ArchivedThreadsHeaderEnvironment {
@@ -70,7 +73,8 @@ function ArchivedThreadsHeader(props: {
   const searchIconColor = useThemeColor("--color-icon");
   const searchTextColor = useThemeColor("--color-foreground");
   const usesNativeChrome = Platform.OS === "ios";
-  const usesCompactMailToolbar = Platform.OS === "ios" && width < 700;
+  const usesCompactMailToolbar =
+    Platform.OS === "ios" && width < 700 && NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED;
   const androidFilterActions = useMemo<MenuAction[]>(
     () => [
       {
@@ -272,7 +276,11 @@ function ArchivedThreadsHeader(props: {
                 ...(usesNativeChrome
                   ? {
                       allowToolbarIntegration: true,
-                      placement: "integratedButton" as const,
+                      // "integratedButton" is an iOS 26 search-bar placement;
+                      // pre-glass iOS keeps the default pull-down placement.
+                      ...(NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED
+                        ? { placement: "integratedButton" as const }
+                        : null),
                     }
                   : {
                       placement: "stacked" as const,
diff --git a/apps/mobile/src/features/files/ThreadFilesRouteScreen.tsx b/apps/mobile/src/features/files/ThreadFilesRouteScreen.tsx
index 012f99536d2..7f5105aac17 100644
--- a/apps/mobile/src/features/files/ThreadFilesRouteScreen.tsx
+++ b/apps/mobile/src/features/files/ThreadFilesRouteScreen.tsx
@@ -29,7 +29,10 @@ import {
   useAdaptiveWorkspacePaneRole,
   useRegisterWorkspaceInspector,
 } from "../layout/AdaptiveWorkspaceLayout";
-import { createNativeMailSearchToolbarItem } from "../layout/native-mail-search-toolbar";
+import {
+  createNativeMailSearchToolbarItem,
+  NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED,
+} from "../layout/native-mail-search-toolbar";
 import { WorkspaceSidebarToolbar } from "../layout/workspace-sidebar-toolbar";
 import { ReviewHighlighterProvider } from "../review/ReviewHighlighterProvider";
 import { ThreadRouteScreen } from "../threads/ThreadRouteScreen";
@@ -354,7 +357,8 @@ export function ThreadFilesTreeScreen(props: ThreadFilesRouteScreenProps) {
     );
   }
 
-  const usesCompactMailToolbar = Platform.OS === "ios" && !layout.usesSplitView;
+  const usesCompactMailToolbar =
+    Platform.OS === "ios" && !layout.usesSplitView && NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED;
 
   return (
     <>
diff --git a/apps/mobile/src/features/home/HomeHeader.tsx b/apps/mobile/src/features/home/HomeHeader.tsx
index 4265107912b..12d5eaca473 100644
--- a/apps/mobile/src/features/home/HomeHeader.tsx
+++ b/apps/mobile/src/features/home/HomeHeader.tsx
@@ -13,7 +13,10 @@ import { useThemeColor } from "../../lib/useThemeColor";
 import { useThreadListV2Enabled } from "../threads/use-thread-list-v2-enabled";
 import { useHardwareKeyboardCommand } from "../keyboard/hardwareKeyboardCommands";
 import { withNativeGlassHeaderItem } from "../layout/native-glass-header-items";
-import { createNativeMailSearchToolbarItem } from "../layout/native-mail-search-toolbar";
+import {
+  createNativeMailSearchToolbarItem,
+  NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED,
+} from "../layout/native-mail-search-toolbar";
 import type { HomeProjectSortOrder } from "./homeThreadList";
 import {
   buildHomeListFilterMenu,
@@ -320,9 +323,11 @@ function IosHomeHeader(props: HomeHeaderProps) {
                   }),
                 ]
               : undefined,
-          unstable_headerToolbarItems:
-            Platform.OS === "ios"
-              ? () => [
+          // The keys below are set per-branch (not `undefined`) so a later
+          // reapply cannot clobber options owned by NativeHeaderToolbar.
+          ...(NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED
+            ? {
+                unstable_headerToolbarItems: () => [
                   createNativeMailSearchToolbarItem({
                     composeButtonId: "home-new-task",
                     composeSystemImageName: "square.and.pencil",
@@ -336,14 +341,14 @@ function IosHomeHeader(props: HomeHeaderProps) {
                     placeholder: "Search",
                     searchTextChangeId: "home-search-text",
                   }),
-                ]
-              : undefined,
-          headerSearchBarOptions:
-            Platform.OS === "ios"
-              ? undefined
-              : {
+                ],
+              }
+            : {
+                // Pre-Liquid-Glass iOS: standard pull-down search in the nav
+                // bar; create + sort live in the plain bottom toolbar below.
+                headerSearchBarOptions: {
                   ref: searchBarRef,
-                  allowToolbarIntegration: true,
+                  autoCapitalize: "none" as const,
                   hideNavigationBar: false,
                   placeholder: "Search",
                   onCancelButtonPress: () => {
@@ -353,21 +358,11 @@ function IosHomeHeader(props: HomeHeaderProps) {
                     props.onSearchQueryChange(event.nativeEvent.text);
                   },
                 },
+              }),
         }}
       />
 
-      {Platform.OS === "ios" ? null : (
-        <NativeHeaderToolbar placement="right">
-          <NativeHeaderToolbar.Button
-            accessibilityLabel="Open settings"
-            icon="gearshape"
-            onPress={props.onOpenSettings}
-            separateBackground
-          />
-        </NativeHeaderToolbar>
-      )}
-
-      {Platform.OS === "ios" ? null : (
+      {NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED ? null : (
         <NativeHeaderToolbar placement="bottom">
           <NativeHeaderToolbar.Menu
             accessibilityLabel="Filter and sort threads"
@@ -421,35 +416,37 @@ function IosHomeHeader(props: HomeHeaderProps) {
               </NativeHeaderToolbar.Menu>
             ) : null}
 
-            <NativeHeaderToolbar.Menu title="Sort projects">
-              <NativeHeaderToolbar.Label>Sort projects</NativeHeaderToolbar.Label>
-              {PROJECT_SORT_OPTIONS.map((option) => (
-                <NativeHeaderToolbar.MenuAction
-                  key={option.value}
-                  isOn={props.projectSortOrder === option.value}
-                  onPress={() => props.onProjectSortOrderChange(option.value)}
-                >
-                  <NativeHeaderToolbar.Label>{option.label}</NativeHeaderToolbar.Label>
-                </NativeHeaderToolbar.MenuAction>
-              ))}
-            </NativeHeaderToolbar.Menu>
+            {threadListV2Enabled ? null : (
+              <NativeHeaderToolbar.Menu title="Sort projects">
+                <NativeHeaderToolbar.Label>Sort projects</NativeHeaderToolbar.Label>
+                {PROJECT_SORT_OPTIONS.map((option) => (
+                  <NativeHeaderToolbar.MenuAction
+                    key={option.value}
+                    isOn={props.projectSortOrder === option.value}
+                    onPress={() => props.onProjectSortOrderChange(option.value)}
+                  >
+                    <NativeHeaderToolbar.Label>{option.label}</NativeHeaderToolbar.Label>
+                  </NativeHeaderToolbar.MenuAction>
+                ))}
+              </NativeHeaderToolbar.Menu>
+            )}
 
-            <NativeHeaderToolbar.Menu title="Sort threads">
-              <NativeHeaderToolbar.Label>Sort threads</NativeHeaderToolbar.Label>
-              {THREAD_SORT_OPTIONS.map((option) => (
-                <NativeHeaderToolbar.MenuAction
-                  key={option.value}
-                  isOn={props.threadSortOrder === option.value}
-                  onPress={() => props.onThreadSortOrderChange(option.value)}
-                >
-                  <NativeHeaderToolbar.Label>{option.label}</NativeHeaderToolbar.Label>
-                </NativeHeaderToolbar.MenuAction>
-              ))}
-            </NativeHeaderToolbar.Menu>
+            {threadListV2Enabled ? null : (
+              <NativeHeaderToolbar.Menu title="Sort threads">
+                <NativeHeaderToolbar.Label>Sort threads</NativeHeaderToolbar.Label>
+                {THREAD_SORT_OPTIONS.map((option) => (
+                  <NativeHeaderToolbar.MenuAction
+                    key={option.value}
+                    isOn={props.threadSortOrder === option.value}
+                    onPress={() => props.onThreadSortOrderChange(option.value)}
+                  >
+                    <NativeHeaderToolbar.Label>{option.label}</NativeHeaderToolbar.Label>
+                  </NativeHeaderToolbar.MenuAction>
+                ))}
+              </NativeHeaderToolbar.Menu>
+            )}
           </NativeHeaderToolbar.Menu>
-          <NativeHeaderToolbar.Spacer width={8} sharesBackground={false} />
-          <NativeHeaderToolbar.SearchBarSlot />
-          <NativeHeaderToolbar.Spacer width={8} sharesBackground={false} />
+          <NativeHeaderToolbar.Spacer flexible />
           <NativeHeaderToolbar.Button
             accessibilityLabel="New task"
             icon="square.and.pencil"
diff --git a/apps/mobile/src/features/home/HomeScreen.tsx b/apps/mobile/src/features/home/HomeScreen.tsx
index 3c2ee4f7b92..507a39d94a1 100644
--- a/apps/mobile/src/features/home/HomeScreen.tsx
+++ b/apps/mobile/src/features/home/HomeScreen.tsx
@@ -109,6 +109,7 @@ interface HomeScreenProps {
 /* ─── Layout constants ───────────────────────────────────────────────── */
 
 const ESTIMATED_THREAD_ROW_HEIGHT = 72;
+const PRE_LIQUID_GLASS_BOTTOM_TOOLBAR_HEIGHT = 44;
 /**
  * Top spacing between the list and the Android custom header. The Android
  * header (AndroidHomeHeader) is rendered in-flow above this screen and
@@ -196,6 +197,10 @@ export function HomeScreen(props: HomeScreenProps) {
   const listRef = useRef<LegendListRef | null>(null);
   const insets = useSafeAreaInsets();
   const accentColor = useThemeColor("--color-icon-muted");
+  const iosBottomToolbarClearance =
+    Platform.OS === "ios" && !NATIVE_LIQUID_GLASS_SUPPORTED
+      ? PRE_LIQUID_GLASS_BOTTOM_TOOLBAR_HEIGHT
+      : 0;
   const searchEnvironmentIds = useMemo(
     () =>
       props.selectedEnvironmentId === null
@@ -877,7 +882,7 @@ export function HomeScreen(props: HomeScreenProps) {
       <View
         className="flex-1 items-center justify-center bg-screen px-8"
         style={{
-          paddingBottom: Math.max(insets.bottom, 24),
+          paddingBottom: Math.max(insets.bottom, 24) + iosBottomToolbarClearance,
           paddingTop: NATIVE_LIQUID_GLASS_SUPPORTED ? insets.top + 72 : 0,
         }}
       >
@@ -1019,7 +1024,7 @@ export function HomeScreen(props: HomeScreenProps) {
             contentContainerStyle={{
               paddingBottom:
                 Platform.OS === "ios"
-                  ? Math.max(insets.bottom, 24) + 96
+                  ? Math.max(insets.bottom, 24) + 96 + iosBottomToolbarClearance
                   : Math.max(insets.bottom, 16) + 88,
             }}
           />
@@ -1060,16 +1065,19 @@ export function HomeScreen(props: HomeScreenProps) {
           scrollEventThrottle={16}
           contentContainerStyle={{
             // Android reserves room for the floating new-task FAB
-            // (56 button + 16 gap + bottom inset).
+            // (56 button + 16 gap + bottom inset). Pre-glass iOS shows a
+            // standard 44pt bottom toolbar that overlays the list and is not
+            // reflected in insets while contentInsetAdjustmentBehavior is
+            // "never".
             paddingBottom:
               Platform.OS === "ios"
-                ? Math.max(insets.bottom, 24) + 24
+                ? Math.max(insets.bottom, 24) + 24 + iosBottomToolbarClearance
                 : Math.max(insets.bottom, 16) + 88,
           }}
           scrollIndicatorInsets={
             Platform.OS === "ios"
               ? {
-                  bottom: Math.max(insets.bottom, 16) + 24,
+                  bottom: Math.max(insets.bottom, 16) + 24 + iosBottomToolbarClearance,
                   top: 0,
                 }
               : undefined
diff --git a/apps/mobile/src/features/layout/native-mail-search-toolbar.ts b/apps/mobile/src/features/layout/native-mail-search-toolbar.ts
index 820e1222243..8770d96b124 100644
--- a/apps/mobile/src/features/layout/native-mail-search-toolbar.ts
+++ b/apps/mobile/src/features/layout/native-mail-search-toolbar.ts
@@ -1,5 +1,16 @@
 import type { HeaderBarButtonMailSearchToolbarItem } from "react-native-screens";
 
+import { NATIVE_LIQUID_GLASS_SUPPORTED } from "../../native/native-glass";
+
+/**
+ * The patched mail-style toolbar is built natively from iOS 26 Liquid Glass
+ * UIKit (`UIGlassEffect`) with no earlier fallback: pre-26 the native side
+ * silently drops the item and hides the navigation toolbar entirely. Screens
+ * that send it must fall back to standard search/toolbar primitives when this
+ * is false.
+ */
+export const NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED = NATIVE_LIQUID_GLASS_SUPPORTED;
+
 type NativeMailSearchToolbarInput = Omit<
   HeaderBarButtonMailSearchToolbarItem,
   "type" | "useFallbackSearchField"
diff --git a/apps/mobile/src/native/StackHeader.tsx b/apps/mobile/src/native/StackHeader.tsx
index 78c87119512..ddfbc64d6c1 100644
--- a/apps/mobile/src/native/StackHeader.tsx
+++ b/apps/mobile/src/native/StackHeader.tsx
@@ -340,7 +340,8 @@ function convertToolbarChild(child: ReactNode): NativeStackHeaderItem | null {
     return {
       type: "spacing",
       spacing: typeof child.props.width === "number" ? child.props.width : 8,
-    };
+      flexible: Boolean(child.props.flexible),
+    } as NativeStackHeaderItem;
   }
 
   return null;
@@ -351,6 +352,11 @@ function collectToolbarItems(children: ReactNode): NativeStackHeaderItem[] {
   Children.forEach(children, (child) => {
     const item = convertToolbarChild(child);
     if (item) {
+      if (item.type === "spacing") {
+        // Native inserts spacing items at `index`, treating a missing index
+        // as 0 — which would move the spacer in front of earlier siblings.
+        (item as { index?: number }).index = items.length;
+      }
       items.push(item);
     }
   });
@@ -440,6 +446,7 @@ function NativeHeaderToolbarLabel(_props: { readonly children?: ReactNode }) {
 NativeHeaderToolbarLabel.displayName = "NativeHeaderToolbarLabel";
 
 function NativeHeaderToolbarSpacer(_props: {
+  readonly flexible?: boolean;
   readonly sharesBackground?: boolean;
   readonly width?: number;
 }) {

From edc503a7a8ea5284a2711981c1a10a6b9999f5e4 Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Thu, 30 Jul 2026 18:17:44 +0200
Subject: [PATCH 28/34] fix(server): restore PR detection without HOME (#4985)

---
 apps/server/src/os-jank.test.ts | 40 +++++++++++++++++++++++++++++++++
 apps/server/src/os-jank.ts      | 19 ++++++++++++++++
 2 files changed, 59 insertions(+)
 create mode 100644 apps/server/src/os-jank.test.ts

diff --git a/apps/server/src/os-jank.test.ts b/apps/server/src/os-jank.test.ts
new file mode 100644
index 00000000000..a157efb665f
--- /dev/null
+++ b/apps/server/src/os-jank.test.ts
@@ -0,0 +1,40 @@
+import * as NodeOS from "node:os";
+import { assert, it } from "vite-plus/test";
+
+import { hydratePosixHome } from "./os-jank.ts";
+
+it("hydrates HOME for minimal service environments from the user account", () => {
+  const env: NodeJS.ProcessEnv = {};
+
+  hydratePosixHome(env);
+
+  assert.equal(env.HOME, NodeOS.userInfo().homedir);
+});
+
+it("hydrates HOME independently of a blank process HOME", () => {
+  const originalHome = process.env.HOME;
+  const env: NodeJS.ProcessEnv = { HOME: " " };
+
+  try {
+    process.env.HOME = " ";
+    hydratePosixHome(env);
+  } finally {
+    if (originalHome === undefined) {
+      delete process.env.HOME;
+    } else {
+      process.env.HOME = originalHome;
+    }
+  }
+
+  assert.equal(env.HOME, NodeOS.userInfo().homedir);
+});
+
+it("preserves an explicitly configured HOME", () => {
+  const env: NodeJS.ProcessEnv = { HOME: "/custom/home" };
+
+  hydratePosixHome(env, () => {
+    throw new Error("HOME lookup should not run");
+  });
+
+  assert.equal(env.HOME, "/custom/home");
+});
diff --git a/apps/server/src/os-jank.ts b/apps/server/src/os-jank.ts
index bc72758bc71..18ddbc66c0c 100644
--- a/apps/server/src/os-jank.ts
+++ b/apps/server/src/os-jank.ts
@@ -36,6 +36,18 @@ function hydratePosixPath(env: NodeJS.ProcessEnv, platform: NodeJS.Platform): vo
   }
 }
 
+export function hydratePosixHome(
+  env: NodeJS.ProcessEnv,
+  resolveHomeDir = () => NodeOS.userInfo().homedir,
+): void {
+  if ((env.HOME?.trim() ?? "").length > 0) return;
+
+  const homeDir = resolveHomeDir();
+  if (homeDir.length > 0) {
+    env.HOME = homeDir;
+  }
+}
+
 export const fixPath = Effect.fn("fixPath")(function* (): Effect.fn.Return<
   void,
   never,
@@ -63,6 +75,13 @@ export const fixPath = Effect.fn("fixPath")(function* (): Effect.fn.Return<
 
   if (platform !== "darwin" && platform !== "linux") return;
 
+  yield* Effect.sync(() => hydratePosixHome(env)).pipe(
+    Effect.catchDefect((defect) =>
+      Effect.sync(() => {
+        logPathHydrationWarning("Failed to hydrate HOME from the user account.", defect);
+      }),
+    ),
+  );
   yield* Effect.sync(() => hydratePosixPath(env, platform)).pipe(
     Effect.catchDefect((defect) =>
       Effect.sync(() => {

From 4ba4871af76081f0e830a91b8f747ff2de53ba7d Mon Sep 17 00:00:00 2001
From: maria <maria@kuuro.net>
Date: Thu, 30 Jul 2026 12:42:21 -0400
Subject: [PATCH 29/34] fix(web): fill fast mode icon (#5004)

---
 apps/web/src/components/chat/TraitsPicker.tsx | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/apps/web/src/components/chat/TraitsPicker.tsx b/apps/web/src/components/chat/TraitsPicker.tsx
index a9f910ec064..6593acd8e1f 100644
--- a/apps/web/src/components/chat/TraitsPicker.tsx
+++ b/apps/web/src/components/chat/TraitsPicker.tsx
@@ -476,7 +476,13 @@ export const TraitsPicker = memo(function TraitsPicker({
   });
   const fastModeIcon = showFastModeIcon ? (
     <>
-      <ComposerControlIcon icon={ZapIcon} className="text-foreground/80 opacity-100" />
+      <ComposerControlIcon
+        icon={ZapIcon}
+        className={cn(
+          "fill-current opacity-80",
+          provider === "claudeAgent" ? "text-[#d97757]" : "text-foreground",
+        )}
+      />
       <span className="sr-only">Fast mode on</span>
     </>
   ) : null;

From 1d77cec991971d3113918e896b1c871e8b044da7 Mon Sep 17 00:00:00 2001
From: Gabriel De Andrade <30420087+gabrielelpidio@users.noreply.github.com>
Date: Thu, 30 Jul 2026 14:13:50 -0400
Subject: [PATCH 30/34] fix: cache project favicons across web and mobile
 (#4767)

---
 apps/mobile/src/components/ProjectFavicon.tsx |  57 ++++++--
 .../components/projectFaviconCache.test.ts    | 108 +++++++++++++++
 .../src/components/projectFaviconCache.ts     |  94 +++++++++++++
 apps/server/src/assets/AssetAccess.test.ts    |  46 ++++++-
 apps/server/src/assets/AssetAccess.ts         |  63 +++++++--
 .../src/components/ProjectFavicon.test.tsx    | 128 ++++++++++++++++++
 apps/web/src/components/ProjectFavicon.tsx    |  61 ++++++---
 packages/shared/src/projectFavicon.test.ts    |  26 +++-
 packages/shared/src/projectFavicon.ts         |  17 +++
 9 files changed, 552 insertions(+), 48 deletions(-)
 create mode 100644 apps/mobile/src/components/projectFaviconCache.test.ts
 create mode 100644 apps/mobile/src/components/projectFaviconCache.ts
 create mode 100644 apps/web/src/components/ProjectFavicon.test.tsx

diff --git a/apps/mobile/src/components/ProjectFavicon.tsx b/apps/mobile/src/components/ProjectFavicon.tsx
index 772d5e8cc14..d52aa05b446 100644
--- a/apps/mobile/src/components/ProjectFavicon.tsx
+++ b/apps/mobile/src/components/ProjectFavicon.tsx
@@ -1,14 +1,21 @@
 import { SymbolView } from "./AppSymbol";
 import { Image } from "expo-image";
-import { useState } from "react";
+import { useLayoutEffect, useMemo, useState } from "react";
 import { View } from "react-native";
 import type { EnvironmentId } from "@t3tools/contracts";
-import { isProjectFaviconFallbackUrl } from "@t3tools/shared/projectFavicon";
+import {
+  getProjectFaviconCacheKey,
+  isProjectFaviconFallbackUrl,
+} from "@t3tools/shared/projectFavicon";
 import { useThemeColor } from "../lib/useThemeColor";
 import { useAssetUrl } from "../state/assets";
-
-/* ─── Favicon cache (matches web pattern) ────────────────────────────── */
-const loadedFaviconUrls = new Set<string>();
+import {
+  beginProjectFaviconRequest,
+  createProjectFaviconRequest,
+  hasLoadedProjectFavicon,
+  markProjectFaviconFailed,
+  markProjectFaviconLoaded,
+} from "./projectFaviconCache";
 
 /* ─── Component ──────────────────────────────────────────────────────── */
 export function ProjectFavicon(props: {
@@ -26,10 +33,15 @@ export function ProjectFavicon(props: {
       : { _tag: "project-favicon", cwd: props.workspaceRoot },
   );
   const renderableFaviconUrl = isProjectFaviconFallbackUrl(faviconUrl) ? null : faviconUrl;
+  const cacheKey =
+    renderableFaviconUrl && props.workspaceRoot
+      ? getProjectFaviconCacheKey(props.environmentId, props.workspaceRoot, renderableFaviconUrl)
+      : null;
 
   return (
     <ProjectFaviconImage
-      key={faviconUrl}
+      key={cacheKey}
+      cacheKey={cacheKey}
       faviconUrl={renderableFaviconUrl}
       open={props.open}
       projectTitle={props.projectTitle}
@@ -39,18 +51,32 @@ export function ProjectFavicon(props: {
 }
 
 function ProjectFaviconImage(props: {
+  readonly cacheKey: string | null;
   readonly faviconUrl: string | null;
   readonly open?: boolean;
   readonly projectTitle: string;
   readonly size: number;
 }) {
   const iconMuted = useThemeColor("--color-icon-subtle");
+  const faviconRequest = useMemo(
+    () => createProjectFaviconRequest(props.cacheKey, props.faviconUrl),
+    [props.cacheKey, props.faviconUrl],
+  );
+  const [activeFaviconRequest, setActiveFaviconRequest] = useState<typeof faviconRequest>(null);
+  useLayoutEffect(() => {
+    if (faviconRequest === null) return;
+
+    const endRequest = beginProjectFaviconRequest(faviconRequest);
+    setActiveFaviconRequest(faviconRequest);
+    return endRequest;
+  }, [faviconRequest]);
 
   const [status, setStatus] = useState<"loading" | "loaded" | "error">(() =>
-    props.faviconUrl && loadedFaviconUrls.has(props.faviconUrl) ? "loaded" : "loading",
+    hasLoadedProjectFavicon(props.cacheKey) ? "loaded" : "loading",
   );
 
-  const showImage = props.faviconUrl !== null && status === "loaded";
+  const requestIsActive = faviconRequest !== null && activeFaviconRequest === faviconRequest;
+  const showImage = requestIsActive && status === "loaded";
 
   return (
     <View
@@ -72,11 +98,15 @@ function ProjectFaviconImage(props: {
       ) : null}
 
       {/* Favicon image (hidden until loaded) */}
-      {props.faviconUrl ? (
+      {requestIsActive ? (
         <Image
+          key={faviconRequest.faviconUrl}
           source={{
-            uri: props.faviconUrl,
+            uri: faviconRequest.faviconUrl,
+            cacheKey: faviconRequest.cacheKey,
           }}
+          cachePolicy="memory-disk"
+          recyclingKey={faviconRequest.cacheKey}
           accessibilityLabel={`${props.projectTitle} favicon`}
           style={{
             width: props.size,
@@ -86,10 +116,13 @@ function ProjectFaviconImage(props: {
           }}
           contentFit="contain"
           onLoad={() => {
-            if (props.faviconUrl) loadedFaviconUrls.add(props.faviconUrl);
+            if (!markProjectFaviconLoaded(faviconRequest)) return;
             setStatus("loaded");
           }}
-          onError={() => setStatus("error")}
+          onError={() => {
+            if (!markProjectFaviconFailed(faviconRequest)) return;
+            setStatus("error");
+          }}
         />
       ) : null}
     </View>
diff --git a/apps/mobile/src/components/projectFaviconCache.test.ts b/apps/mobile/src/components/projectFaviconCache.test.ts
new file mode 100644
index 00000000000..d0582a8b5f5
--- /dev/null
+++ b/apps/mobile/src/components/projectFaviconCache.test.ts
@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+  beginProjectFaviconRequest,
+  createProjectFaviconRequest,
+  hasLoadedProjectFavicon,
+  markProjectFaviconFailed,
+  markProjectFaviconLoaded,
+} from "./projectFaviconCache";
+
+describe("project favicon cache", () => {
+  it("ignores callbacks from a superseded URL", () => {
+    const cacheKey = "environment-1:/workspace:v1-favicon.svg";
+    const expiredUrl = "https://environment.example/api/assets/expired/v1-favicon.svg";
+    const refreshedUrl = "https://environment.example/api/assets/refreshed/v1-favicon.svg";
+
+    const expiredRequest = createProjectFaviconRequest(cacheKey, expiredUrl);
+    const endExpiredRequest = beginProjectFaviconRequest(expiredRequest);
+    markProjectFaviconLoaded(expiredRequest);
+    const refreshedRequest = createProjectFaviconRequest(cacheKey, refreshedUrl);
+    const endRefreshedRequest = beginProjectFaviconRequest(refreshedRequest);
+
+    expect(markProjectFaviconLoaded(expiredRequest)).toBe(false);
+    expect(markProjectFaviconFailed(expiredRequest)).toBe(false);
+    expect(hasLoadedProjectFavicon(cacheKey)).toBe(true);
+    expect(markProjectFaviconFailed(refreshedRequest)).toBe(true);
+    expect(hasLoadedProjectFavicon(cacheKey)).toBe(false);
+
+    endRefreshedRequest();
+    endExpiredRequest();
+  });
+
+  it("evicts the URL that actually failed", () => {
+    const cacheKey = "environment-1:/workspace:v2-favicon.svg";
+    const faviconUrl = "https://environment.example/api/assets/current/v2-favicon.svg";
+    const request = createProjectFaviconRequest(cacheKey, faviconUrl);
+    const endRequest = beginProjectFaviconRequest(request);
+
+    markProjectFaviconLoaded(request);
+
+    expect(markProjectFaviconFailed(request)).toBe(true);
+    expect(hasLoadedProjectFavicon(cacheKey)).toBe(false);
+
+    endRequest();
+  });
+
+  it("does not supersede a request until the next request begins", () => {
+    const cacheKey = "environment-1:/workspace:v3-favicon.svg";
+    const committedUrl = "https://environment.example/api/assets/current/v3-favicon.svg";
+    const abandonedUrl = "https://environment.example/api/assets/abandoned/v3-favicon.svg";
+    const committedRequest = createProjectFaviconRequest(cacheKey, committedUrl);
+    const endCommittedRequest = beginProjectFaviconRequest(committedRequest);
+
+    createProjectFaviconRequest(cacheKey, abandonedUrl);
+
+    expect(markProjectFaviconLoaded(committedRequest)).toBe(true);
+    expect(hasLoadedProjectFavicon(cacheKey)).toBe(true);
+
+    endCommittedRequest();
+  });
+
+  it("requires a cache key before creating a URL-bearing request", () => {
+    const firstUrl = "https://environment.example/api/assets/first/favicon.svg";
+    const secondUrl = "https://environment.example/api/assets/second/favicon.svg";
+
+    expect(createProjectFaviconRequest(null, firstUrl)).toBeNull();
+    expect(createProjectFaviconRequest(null, secondUrl)).toBeNull();
+  });
+
+  it("restores the remaining active URL when a newer request ends", () => {
+    const cacheKey = "environment-1:/workspace:v4-favicon.svg";
+    const firstRequest = createProjectFaviconRequest(
+      cacheKey,
+      "https://environment.example/api/assets/first/v4-favicon.svg",
+    );
+    const secondRequest = createProjectFaviconRequest(
+      cacheKey,
+      "https://environment.example/api/assets/second/v4-favicon.svg",
+    );
+    const endFirstRequest = beginProjectFaviconRequest(firstRequest);
+    const endSecondRequest = beginProjectFaviconRequest(secondRequest);
+
+    expect(markProjectFaviconLoaded(firstRequest)).toBe(false);
+    endSecondRequest();
+    expect(markProjectFaviconLoaded(firstRequest)).toBe(true);
+    endFirstRequest();
+    expect(markProjectFaviconLoaded(firstRequest)).toBe(false);
+  });
+
+  it("bounds remembered loaded revisions", () => {
+    const firstCacheKey = "environment-1:/workspace:revision-0";
+    let lastCacheKey = firstCacheKey;
+
+    for (let revision = 0; revision < 300; revision++) {
+      lastCacheKey = `environment-1:/workspace:revision-${revision}`;
+      const request = createProjectFaviconRequest(
+        lastCacheKey,
+        `https://environment.example/api/assets/revision-${revision}/favicon.svg`,
+      );
+      const endRequest = beginProjectFaviconRequest(request);
+      markProjectFaviconLoaded(request);
+      endRequest();
+    }
+
+    expect(hasLoadedProjectFavicon(firstCacheKey)).toBe(false);
+    expect(hasLoadedProjectFavicon(lastCacheKey)).toBe(true);
+  });
+});
diff --git a/apps/mobile/src/components/projectFaviconCache.ts b/apps/mobile/src/components/projectFaviconCache.ts
new file mode 100644
index 00000000000..da77d7613f2
--- /dev/null
+++ b/apps/mobile/src/components/projectFaviconCache.ts
@@ -0,0 +1,94 @@
+export interface ProjectFaviconRequest {
+  readonly cacheKey: string;
+  readonly faviconUrl: string;
+}
+
+interface ActiveFaviconRequests {
+  readonly urls: Map<string, number>;
+  currentUrl: string;
+}
+
+const MAX_LOADED_FAVICONS = 256;
+const activeFaviconRequests = new Map<string, ActiveFaviconRequests>();
+const loadedFaviconKeys = new Map<string, true>();
+
+export function createProjectFaviconRequest(
+  cacheKey: string,
+  faviconUrl: string,
+): ProjectFaviconRequest;
+export function createProjectFaviconRequest(
+  cacheKey: string | null,
+  faviconUrl: string | null,
+): ProjectFaviconRequest | null;
+export function createProjectFaviconRequest(cacheKey: string | null, faviconUrl: string | null) {
+  if (!cacheKey || !faviconUrl) return null;
+  return { cacheKey, faviconUrl };
+}
+
+export function beginProjectFaviconRequest(request: ProjectFaviconRequest) {
+  let activeRequests = activeFaviconRequests.get(request.cacheKey);
+  if (!activeRequests) {
+    activeRequests = { currentUrl: request.faviconUrl, urls: new Map() };
+    activeFaviconRequests.set(request.cacheKey, activeRequests);
+  }
+
+  const activeCount = activeRequests.urls.get(request.faviconUrl) ?? 0;
+  activeRequests.urls.delete(request.faviconUrl);
+  activeRequests.urls.set(request.faviconUrl, activeCount + 1);
+  activeRequests.currentUrl = request.faviconUrl;
+
+  let ended = false;
+  return () => {
+    if (ended) return;
+    ended = true;
+
+    const remainingCount = (activeRequests.urls.get(request.faviconUrl) ?? 1) - 1;
+    if (remainingCount > 0) {
+      activeRequests.urls.set(request.faviconUrl, remainingCount);
+      return;
+    }
+
+    activeRequests.urls.delete(request.faviconUrl);
+    if (activeRequests.urls.size === 0) {
+      if (activeFaviconRequests.get(request.cacheKey) === activeRequests) {
+        activeFaviconRequests.delete(request.cacheKey);
+      }
+      return;
+    }
+
+    if (activeRequests.currentUrl === request.faviconUrl) {
+      activeRequests.currentUrl = Array.from(activeRequests.urls.keys()).at(-1)!;
+    }
+  };
+}
+
+export function hasLoadedProjectFavicon(cacheKey: string | null) {
+  return cacheKey !== null && loadedFaviconKeys.has(cacheKey);
+}
+
+function isCurrentProjectFaviconRequest(request: ProjectFaviconRequest) {
+  return activeFaviconRequests.get(request.cacheKey)?.currentUrl === request.faviconUrl;
+}
+
+function rememberLoadedProjectFavicon(cacheKey: string) {
+  loadedFaviconKeys.delete(cacheKey);
+  loadedFaviconKeys.set(cacheKey, true);
+
+  if (loadedFaviconKeys.size > MAX_LOADED_FAVICONS) {
+    loadedFaviconKeys.delete(loadedFaviconKeys.keys().next().value!);
+  }
+}
+
+export function markProjectFaviconLoaded(request: ProjectFaviconRequest) {
+  if (!isCurrentProjectFaviconRequest(request)) return false;
+
+  rememberLoadedProjectFavicon(request.cacheKey);
+  return true;
+}
+
+export function markProjectFaviconFailed(request: ProjectFaviconRequest) {
+  if (!isCurrentProjectFaviconRequest(request)) return false;
+
+  loadedFaviconKeys.delete(request.cacheKey);
+  return true;
+}
diff --git a/apps/server/src/assets/AssetAccess.test.ts b/apps/server/src/assets/AssetAccess.test.ts
index 42fd3f900e5..568dc3739c0 100644
--- a/apps/server/src/assets/AssetAccess.test.ts
+++ b/apps/server/src/assets/AssetAccess.test.ts
@@ -2,11 +2,13 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 import { ThreadId } from "@t3tools/contracts";
 import { PROJECT_FAVICON_FALLBACK_MARKER } from "@t3tools/shared/projectFavicon";
 import { describe, expect, it } from "@effect/vitest";
+import * as Crypto from "effect/Crypto";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
 import * as Path from "effect/Path";
 import * as PlatformError from "effect/PlatformError";
+import * as TestClock from "effect/testing/TestClock";
 
 import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
 import * as ServerConfig from "../config.ts";
@@ -214,12 +216,21 @@ describe("AssetAccess", () => {
         prefix: "t3-asset-favicon-",
       });
       const faviconPath = path.join(root, "favicon.svg");
-      yield* fileSystem.writeFileString(faviconPath, "<svg />");
+      const initialFavicon = "<svg>a</svg>";
+      const updatedFavicon = "<svg>b</svg>";
+      expect(updatedFavicon).toHaveLength(initialFavicon.length);
+      yield* fileSystem.writeFileString(faviconPath, initialFavicon);
       const canonicalFaviconPath = yield* fileSystem.realPath(faviconPath);
 
       const faviconResult = yield* issueAssetUrl({
         resource: { _tag: "project-favicon", cwd: root },
       });
+      expect(faviconResult.relativeUrl).toMatch(/\/v[0-9a-f]{64}-favicon\.svg$/);
+      expect(
+        yield* issueAssetUrl({
+          resource: { _tag: "project-favicon", cwd: root },
+        }),
+      ).toEqual(faviconResult);
       const faviconSuffix = faviconResult.relativeUrl.slice(`${ASSET_ROUTE_PREFIX}/`.length);
       const faviconSeparatorIndex = faviconSuffix.indexOf("/");
       expect(
@@ -229,6 +240,14 @@ describe("AssetAccess", () => {
         ),
       ).toEqual({ kind: "file", path: canonicalFaviconPath });
 
+      yield* fileSystem.writeFileString(faviconPath, updatedFavicon);
+      const updatedFaviconResult = yield* issueAssetUrl({
+        resource: { _tag: "project-favicon", cwd: root },
+      });
+      expect(
+        updatedFaviconResult.relativeUrl.slice(updatedFaviconResult.relativeUrl.lastIndexOf("/")),
+      ).not.toBe(faviconResult.relativeUrl.slice(faviconResult.relativeUrl.lastIndexOf("/")));
+
       yield* fileSystem.remove(faviconPath);
       const fallbackResult = yield* issueAssetUrl({
         resource: { _tag: "project-favicon", cwd: root },
@@ -245,6 +264,31 @@ describe("AssetAccess", () => {
     }).pipe(Effect.provide(testLayer)),
   );
 
+  it.effect("buckets project favicon expiry after content hashing", () =>
+    Effect.gen(function* () {
+      const crypto = yield* Crypto.Crypto;
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const root = yield* fileSystem.makeTempDirectoryScoped({
+        prefix: "t3-asset-favicon-expiry-",
+      });
+      yield* fileSystem.writeFileString(path.join(root, "favicon.svg"), "<svg />");
+
+      const bucketMs = 30 * 60 * 1000;
+      yield* TestClock.setTime(bucketMs - 1);
+      const crossingCrypto = Crypto.make({
+        randomBytes: (size) => new Uint8Array(size),
+        digest: (algorithm, data) =>
+          TestClock.adjust("2 millis").pipe(Effect.andThen(crypto.digest(algorithm, data))),
+      });
+      const result = yield* issueAssetUrl({
+        resource: { _tag: "project-favicon", cwd: root },
+      }).pipe(Effect.provideService(Crypto.Crypto, crossingCrypto));
+
+      expect(result.expiresAt).toBe(3 * bucketMs);
+    }).pipe(Effect.provide(testLayer)),
+  );
+
   it.effect("preserves structured project favicon resolution causes", () =>
     Effect.gen(function* () {
       const fileSystem = yield* FileSystem.FileSystem;
diff --git a/apps/server/src/assets/AssetAccess.ts b/apps/server/src/assets/AssetAccess.ts
index b469e0e315b..c00f7f1a5e3 100644
--- a/apps/server/src/assets/AssetAccess.ts
+++ b/apps/server/src/assets/AssetAccess.ts
@@ -21,7 +21,9 @@ import {
 } from "@t3tools/shared/filePreview";
 import { PROJECT_FAVICON_FALLBACK_MARKER } from "@t3tools/shared/projectFavicon";
 import * as Clock from "effect/Clock";
+import * as Crypto from "effect/Crypto";
 import * as Effect from "effect/Effect";
+import * as Encoding from "effect/Encoding";
 import * as FileSystem from "effect/FileSystem";
 import * as Option from "effect/Option";
 import * as Path from "effect/Path";
@@ -44,6 +46,8 @@ export const ASSET_ROUTE_PREFIX = "/api/assets";
 
 const SIGNING_SECRET_NAME = "asset-access-signing-key";
 const ASSET_TOKEN_TTL_MS = 60 * 60 * 1000;
+const PROJECT_FAVICON_TOKEN_BUCKET_MS = 30 * 60 * 1000;
+const PROJECT_FAVICON_VERSION_PREFIX = "v";
 const PREVIEW_ASSET_EXTENSIONS = new Set([
   ...WORKSPACE_BROWSER_PREVIEW_EXTENSIONS,
   ...WORKSPACE_IMAGE_PREVIEW_EXTENSIONS,
@@ -169,7 +173,7 @@ export const issueAssetUrl = Effect.fn("AssetAccess.issueAssetUrl")(function* (i
   const fileSystem = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
   const workspacePaths = yield* WorkspacePaths.WorkspacePaths;
-  const expiresAt = (yield* Clock.currentTimeMillis) + ASSET_TOKEN_TTL_MS;
+  let expiresAt = (yield* Clock.currentTimeMillis) + ASSET_TOKEN_TTL_MS;
   let claims: AssetClaims;
   let fileName: string;
 
@@ -293,18 +297,18 @@ export const issueAssetUrl = Effect.fn("AssetAccess.issueAssetUrl")(function* (i
         ),
       );
       const relativePath = faviconPath ? path.relative(workspaceRoot, faviconPath) : null;
-      if (
-        relativePath &&
-        !(yield* resolveCanonicalWorkspaceFile({ workspaceRoot, relativePath }).pipe(
-          Effect.mapError(
-            (cause) =>
-              new AssetProjectFaviconInspectionError({
-                resource: input.resource,
-                cause,
-              }),
-          ),
-        ))
-      ) {
+      const canonicalFaviconPath = relativePath
+        ? yield* resolveCanonicalWorkspaceFile({ workspaceRoot, relativePath }).pipe(
+            Effect.mapError(
+              (cause) =>
+                new AssetProjectFaviconInspectionError({
+                  resource: input.resource,
+                  cause,
+                }),
+            ),
+          )
+        : null;
+      if (relativePath && !canonicalFaviconPath) {
         return yield* new AssetProjectFaviconNotFoundError({
           resource: input.resource,
         });
@@ -324,7 +328,31 @@ export const issueAssetUrl = Effect.fn("AssetAccess.issueAssetUrl")(function* (i
         relativePath,
         expiresAt,
       };
-      fileName = relativePath ? path.basename(relativePath) : PROJECT_FAVICON_FALLBACK_MARKER;
+      if (relativePath && canonicalFaviconPath) {
+        const crypto = yield* Crypto.Crypto;
+        const faviconBytes = yield* fileSystem.readFile(canonicalFaviconPath).pipe(
+          Effect.mapError(
+            (cause) =>
+              new AssetProjectFaviconInspectionError({
+                resource: input.resource,
+                cause,
+              }),
+          ),
+        );
+        const revision = yield* crypto.digest("SHA-256", faviconBytes).pipe(
+          Effect.map(Encoding.encodeHex),
+          Effect.mapError(
+            (cause) =>
+              new AssetProjectFaviconInspectionError({
+                resource: input.resource,
+                cause,
+              }),
+          ),
+        );
+        fileName = `${PROJECT_FAVICON_VERSION_PREFIX}${revision}-${path.basename(relativePath)}`;
+      } else {
+        fileName = PROJECT_FAVICON_FALLBACK_MARKER;
+      }
       break;
     }
   }
@@ -339,6 +367,13 @@ export const issueAssetUrl = Effect.fn("AssetAccess.issueAssetUrl")(function* (i
         }),
     ),
   );
+  if (claims.kind === "project-favicon") {
+    const issuedAt = yield* Clock.currentTimeMillis;
+    expiresAt =
+      (Math.floor(issuedAt / PROJECT_FAVICON_TOKEN_BUCKET_MS) + 2) *
+      PROJECT_FAVICON_TOKEN_BUCKET_MS;
+    claims = { ...claims, expiresAt };
+  }
   const encodedPayload = base64UrlEncode(encodeAssetClaims(claims));
   const token = `${encodedPayload}.${signPayload(encodedPayload, signingSecret)}`;
   return {
diff --git a/apps/web/src/components/ProjectFavicon.test.tsx b/apps/web/src/components/ProjectFavicon.test.tsx
new file mode 100644
index 00000000000..c2fac8beb7e
--- /dev/null
+++ b/apps/web/src/components/ProjectFavicon.test.tsx
@@ -0,0 +1,128 @@
+import type { ComponentType, Dispatch, ReactElement, SetStateAction } from "react";
+import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
+import type { EnvironmentId } from "@t3tools/contracts";
+
+const testState = vi.hoisted(() => ({
+  faviconUrl: "https://environment.test/api/assets/token-a/v1-20-favicon.svg",
+}));
+
+const hooks = vi.hoisted(() => {
+  let cursor = 0;
+  let slots: unknown[] = [];
+  const nextIndex = () => cursor++;
+
+  return {
+    beginRender() {
+      cursor = 0;
+    },
+    reset() {
+      cursor = 0;
+      slots = [];
+    },
+    useMemoCache(size: number): unknown[] {
+      const index = nextIndex();
+      if (!slots[index]) {
+        slots[index] = Array.from({ length: size }, () => Symbol.for("react.memo_cache_sentinel"));
+      }
+      return slots[index] as unknown[];
+    },
+    useState<T>(initialValue: T | (() => T)): [T, Dispatch<SetStateAction<T>>] {
+      const index = nextIndex();
+      if (index >= slots.length) {
+        slots[index] =
+          typeof initialValue === "function" ? (initialValue as () => T)() : initialValue;
+      }
+      const setValue: Dispatch<SetStateAction<T>> = (nextValue) => {
+        const previous = slots[index] as T;
+        slots[index] =
+          typeof nextValue === "function" ? (nextValue as (value: T) => T)(previous) : nextValue;
+      };
+      return [slots[index] as T, setValue];
+    },
+  };
+});
+
+vi.mock("react", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react")>();
+  return {
+    ...actual,
+    useState: hooks.useState,
+  };
+});
+
+vi.mock("react/compiler-runtime", () => ({ c: hooks.useMemoCache }));
+vi.mock("../assets/assetUrls", () => ({
+  useAssetUrl: () => testState.faviconUrl,
+}));
+
+import { ProjectFavicon } from "./ProjectFavicon";
+
+type ProjectFaviconImageProps = {
+  readonly cacheKey: string;
+  readonly src: string;
+  readonly className?: string | undefined;
+  readonly fallbackIcon: ComponentType<{ className?: string }>;
+};
+
+type ImageElement = ReactElement<{
+  readonly src: string;
+  readonly onLoad?: () => void;
+  readonly onError?: () => void;
+}>;
+
+type ProjectFaviconImageElement = ReactElement<{
+  readonly children: [ReactElement | null, ImageElement | null, ImageElement | null];
+}>;
+
+function resolveImageComponent(): {
+  readonly Component: (props: ProjectFaviconImageProps) => ProjectFaviconImageElement;
+  readonly props: ProjectFaviconImageProps;
+} {
+  hooks.beginRender();
+  const element = ProjectFavicon({
+    environmentId: "environment-test" as EnvironmentId,
+    cwd: "/workspace-test",
+  }) as ReactElement<ProjectFaviconImageProps>;
+  hooks.reset();
+
+  return {
+    Component: element.type as (props: ProjectFaviconImageProps) => ProjectFaviconImageElement,
+    props: element.props,
+  };
+}
+
+function renderImage(
+  Component: (props: ProjectFaviconImageProps) => ProjectFaviconImageElement,
+  props: ProjectFaviconImageProps,
+): ProjectFaviconImageElement {
+  hooks.beginRender();
+  return Component(props);
+}
+
+describe("ProjectFavicon", () => {
+  beforeEach(() => {
+    hooks.reset();
+  });
+
+  it("falls back when the displayed favicon fails without discarding a valid older image early", () => {
+    const { Component, props } = resolveImageComponent();
+    const initialLoadingImage = renderImage(Component, props).props.children[2];
+    initialLoadingImage?.props.onLoad?.();
+
+    const refreshedProps = {
+      ...props,
+      src: "https://environment.test/api/assets/token-b/v1-20-favicon.svg",
+    };
+    const refreshing = renderImage(Component, refreshedProps).props.children;
+    expect(refreshing[1]?.props.src).toBe(props.src);
+    refreshing[2]?.props.onError?.();
+
+    const afterRefreshError = renderImage(Component, refreshedProps).props.children;
+    expect(afterRefreshError[1]?.props.src).toBe(props.src);
+    afterRefreshError[1]?.props.onError?.();
+
+    const afterDisplayedError = renderImage(Component, refreshedProps).props.children;
+    expect(afterDisplayedError[0]).not.toBeNull();
+    expect(afterDisplayedError[1]).toBeNull();
+  });
+});
diff --git a/apps/web/src/components/ProjectFavicon.tsx b/apps/web/src/components/ProjectFavicon.tsx
index 201241731fa..1df19a64075 100644
--- a/apps/web/src/components/ProjectFavicon.tsx
+++ b/apps/web/src/components/ProjectFavicon.tsx
@@ -1,12 +1,15 @@
 import type { EnvironmentId } from "@t3tools/contracts";
-import { isProjectFaviconFallbackUrl } from "@t3tools/shared/projectFavicon";
+import {
+  getProjectFaviconCacheKey,
+  isProjectFaviconFallbackUrl,
+} from "@t3tools/shared/projectFavicon";
 import { FolderIcon } from "lucide-react";
 import type { ComponentType } from "react";
 import { useState } from "react";
 import { useAssetUrl } from "../assets/assetUrls";
 import { cn } from "~/lib/utils";
 
-const loadedProjectFaviconSrcs = new Set<string>();
+const loadedProjectFaviconSrcs = new Map<string, string>();
 
 export function ProjectFavicon(input: {
   environmentId: EnvironmentId;
@@ -24,9 +27,12 @@ export function ProjectFavicon(input: {
     return <ProjectFaviconFallback className={input.className} icon={FallbackIcon} />;
   }
 
+  const cacheKey = getProjectFaviconCacheKey(input.environmentId, input.cwd, src);
+
   return (
     <ProjectFaviconImage
-      key={src}
+      key={cacheKey}
+      cacheKey={cacheKey}
       src={src}
       className={input.className}
       fallbackIcon={FallbackIcon}
@@ -45,37 +51,52 @@ function ProjectFaviconFallback({
 }
 
 function ProjectFaviconImage({
+  cacheKey,
   src,
   className,
   fallbackIcon: FallbackIcon,
 }: {
+  readonly cacheKey: string;
   readonly src: string;
   readonly className?: string | undefined;
   readonly fallbackIcon: ComponentType<{ className?: string }>;
 }) {
-  const [status, setStatus] = useState<"loading" | "loaded" | "error">(() =>
-    loadedProjectFaviconSrcs.has(src) ? "loaded" : "loading",
+  const [displayedSrc, setDisplayedSrc] = useState<string | null>(
+    () => loadedProjectFaviconSrcs.get(cacheKey) ?? null,
   );
+  const isLoading = displayedSrc !== src;
+  const handleLoadError = (failedSrc: string) => {
+    if (loadedProjectFaviconSrcs.get(cacheKey) === failedSrc) {
+      loadedProjectFaviconSrcs.delete(cacheKey);
+    }
+    setDisplayedSrc((currentSrc) => (currentSrc === failedSrc ? null : currentSrc));
+  };
 
   return (
     <>
-      {status !== "loaded" ? (
+      {displayedSrc === null ? (
         <ProjectFaviconFallback className={className} icon={FallbackIcon} />
       ) : null}
-      <img
-        src={src}
-        alt=""
-        className={cn(
-          "size-3.5 shrink-0 rounded-sm object-contain",
-          status !== "loaded" && "hidden",
-          className,
-        )}
-        onLoad={() => {
-          loadedProjectFaviconSrcs.add(src);
-          setStatus("loaded");
-        }}
-        onError={() => setStatus("error")}
-      />
+      {displayedSrc ? (
+        <img
+          src={displayedSrc}
+          alt=""
+          className={cn("size-3.5 shrink-0 rounded-sm object-contain", className)}
+          onError={() => handleLoadError(displayedSrc)}
+        />
+      ) : null}
+      {isLoading ? (
+        <img
+          src={src}
+          alt=""
+          className="hidden"
+          onLoad={() => {
+            loadedProjectFaviconSrcs.set(cacheKey, src);
+            setDisplayedSrc(src);
+          }}
+          onError={() => handleLoadError(src)}
+        />
+      ) : null}
     </>
   );
 }
diff --git a/packages/shared/src/projectFavicon.test.ts b/packages/shared/src/projectFavicon.test.ts
index 0011b2fc7c9..1df17cc7fe5 100644
--- a/packages/shared/src/projectFavicon.test.ts
+++ b/packages/shared/src/projectFavicon.test.ts
@@ -1,8 +1,32 @@
 import { describe, expect, it } from "vite-plus/test";
 
-import { isProjectFaviconFallbackUrl, PROJECT_FAVICON_FALLBACK_MARKER } from "./projectFavicon.ts";
+import {
+  getProjectFaviconCacheKey,
+  isProjectFaviconFallbackUrl,
+  PROJECT_FAVICON_FALLBACK_MARKER,
+} from "./projectFavicon.ts";
 
 describe("project favicon", () => {
+  it("uses the project and versioned filename as the cache identity", () => {
+    const firstUrl = "https://environment.example/api/assets/first-signed-token/v1-20-favicon.svg";
+    const refreshedUrl =
+      "https://environment.example/api/assets/refreshed-signed-token/v1-20-favicon.svg";
+
+    expect(getProjectFaviconCacheKey("environment-1", "/workspace", firstUrl)).toBe(
+      getProjectFaviconCacheKey("environment-1", "/workspace", refreshedUrl),
+    );
+    expect(getProjectFaviconCacheKey("environment-1", "/workspace", firstUrl)).not.toBe(
+      getProjectFaviconCacheKey(
+        "environment-1",
+        "/workspace",
+        "https://environment.example/api/assets/refreshed-signed-token/v2-20-favicon.svg",
+      ),
+    );
+    expect(getProjectFaviconCacheKey("environment-1", "/workspace", firstUrl)).not.toBe(
+      getProjectFaviconCacheKey("environment-2", "/workspace", firstUrl),
+    );
+  });
+
   it("identifies fallback asset URLs by their dedicated filename", () => {
     expect(
       isProjectFaviconFallbackUrl(
diff --git a/packages/shared/src/projectFavicon.ts b/packages/shared/src/projectFavicon.ts
index 2e46429b6c1..eebc1a8a1b6 100644
--- a/packages/shared/src/projectFavicon.ts
+++ b/packages/shared/src/projectFavicon.ts
@@ -1,5 +1,22 @@
 export const PROJECT_FAVICON_FALLBACK_MARKER = "project-favicon-missing";
 
+export function getProjectFaviconCacheKey(
+  environmentId: string,
+  workspaceRoot: string,
+  url: string,
+) {
+  let revision = url;
+
+  try {
+    const pathname = new URL(url, "https://t3.invalid").pathname;
+    revision = pathname.slice(pathname.lastIndexOf("/") + 1);
+  } catch {
+    // Keep the full value as a safe fallback for malformed URLs.
+  }
+
+  return JSON.stringify([environmentId, workspaceRoot, revision]);
+}
+
 export function isProjectFaviconFallbackUrl(url: string | null | undefined): boolean {
   if (!url) return false;
 

From e4829603ff70bdeac96780e1512ac2c09638e5a3 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Thu, 30 Jul 2026 11:25:31 -0700
Subject: [PATCH 31/34] perf(ci): cut stale runs and redundant setup (#4802)

---
 .github/workflows/ci.yml                      | 34 ++++++++++--
 .github/workflows/deploy-relay.yml            |  9 +++-
 .github/workflows/mobile-eas-preview.yml      | 17 ++++--
 .github/workflows/mobile-eas-production.yml   |  8 ++-
 .../workflows/mobile-showcase-screenshots.yml | 20 ++++++-
 .github/workflows/release.yml                 | 52 +++++++++++++++++--
 6 files changed, 126 insertions(+), 14 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5a418a463c2..1e51867cbe7 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -6,6 +6,10 @@ on:
     branches:
       - main
 
+concurrency:
+  group: ci-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
   check:
     name: Check
@@ -14,6 +18,11 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
@@ -55,6 +64,11 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
@@ -77,18 +91,25 @@ jobs:
 
   mobile_native_static_analysis:
     name: Mobile Native Static Analysis
-    runs-on: blacksmith-12vcpu-macos-26
+    runs-on: blacksmith-6vcpu-macos-26
     timeout-minutes: 10
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
         with:
           node-version-file: package.json
           cache: true
-          run-install: true
+          run-install: |
+            args:
+              - --filter=@t3tools/scripts...
 
       - name: Install mobile native static analysis tools
         run: brew bundle install --file apps/mobile/Brewfile
@@ -103,13 +124,20 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
         with:
           node-version-file: package.json
           cache: true
-          run-install: true
+          run-install: |
+            args:
+              - --filter=@t3tools/scripts...
 
       - name: Exercise release-only workflow steps
         run: node scripts/release-smoke.ts
diff --git a/.github/workflows/deploy-relay.yml b/.github/workflows/deploy-relay.yml
index 94d4af17e41..f652844a54f 100644
--- a/.github/workflows/deploy-relay.yml
+++ b/.github/workflows/deploy-relay.yml
@@ -38,13 +38,20 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
         with:
           node-version-file: package.json
           cache: true
-          run-install: true
+          run-install: |
+            args:
+              - --filter=t3code-relay...
 
       - name: Deploy production relay stage
         id: deploy
diff --git a/.github/workflows/mobile-eas-preview.yml b/.github/workflows/mobile-eas-preview.yml
index 32e45fef54e..d8b07208c13 100644
--- a/.github/workflows/mobile-eas-preview.yml
+++ b/.github/workflows/mobile-eas-preview.yml
@@ -2,13 +2,18 @@ name: Mobile EAS Preview
 
 on:
   pull_request:
-    types: [opened, reopened, synchronize, labeled, unlabeled]
+    types: [opened, reopened, synchronize, labeled]
 
 jobs:
   preview:
     name: EAS Preview
-    if: contains(github.event.pull_request.labels.*.name, '🚀 Mobile Continuous Deployment')
+    if: |
+      contains(github.event.pull_request.labels.*.name, '🚀 Mobile Continuous Deployment') &&
+      (github.event.action != 'labeled' || github.event.label.name == '🚀 Mobile Continuous Deployment')
     runs-on: blacksmith-8vcpu-ubuntu-2404
+    concurrency:
+      group: mobile-eas-preview-${{ github.event.pull_request.number }}
+      cancel-in-progress: true
     permissions:
       contents: read
       pull-requests: write
@@ -34,6 +39,10 @@ jobs:
         uses: actions/checkout@v6
         with:
           fetch-depth: 0
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         if: steps.expo-token.outputs.present == 'true'
@@ -41,7 +50,9 @@ jobs:
         with:
           node-version-file: package.json
           cache: true
-          run-install: true
+          run-install: |
+            args:
+              - --filter=@t3tools/mobile...
 
       - name: Expose pnpm
         if: steps.expo-token.outputs.present == 'true'
diff --git a/.github/workflows/mobile-eas-production.yml b/.github/workflows/mobile-eas-production.yml
index 685df85e57c..95cd0ddacc8 100644
--- a/.github/workflows/mobile-eas-production.yml
+++ b/.github/workflows/mobile-eas-production.yml
@@ -57,6 +57,10 @@ jobs:
         uses: actions/checkout@v6
         with:
           fetch-depth: 0
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         if: steps.expo-token.outputs.present == 'true'
@@ -64,7 +68,9 @@ jobs:
         with:
           node-version-file: package.json
           cache: true
-          run-install: true
+          run-install: |
+            args:
+              - --filter=@t3tools/mobile...
 
       - name: Expose pnpm
         if: steps.expo-token.outputs.present == 'true'
diff --git a/.github/workflows/mobile-showcase-screenshots.yml b/.github/workflows/mobile-showcase-screenshots.yml
index 36dfb61f73f..0aa9f30a2ff 100644
--- a/.github/workflows/mobile-showcase-screenshots.yml
+++ b/.github/workflows/mobile-showcase-screenshots.yml
@@ -37,13 +37,21 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
         with:
           node-version-file: package.json
           cache: true
-          run-install: true
+          run-install: |
+            args:
+              - --filter=@t3tools/mobile...
+              - --filter=@t3tools/scripts...
 
       - name: Expose pnpm
         run: |
@@ -77,13 +85,21 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
         with:
           node-version-file: package.json
           cache: true
-          run-install: true
+          run-install: |
+            args:
+              - --filter=@t3tools/mobile...
+              - --filter=@t3tools/scripts...
 
       - name: Expose pnpm
         run: |
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index bc0b0622d7f..ce47d6e6ed7 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -38,6 +38,10 @@ jobs:
         uses: actions/checkout@v6
         with:
           fetch-depth: 0
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - id: check
         name: Compare HEAD to last nightly tag
@@ -84,6 +88,10 @@ jobs:
         uses: actions/checkout@v6
         with:
           fetch-depth: 0
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
@@ -192,6 +200,10 @@ jobs:
         uses: actions/checkout@v6
         with:
           ref: ${{ needs.preflight.outputs.ref }}
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
@@ -269,14 +281,19 @@ jobs:
         uses: actions/checkout@v6
         with:
           ref: ${{ needs.preflight.outputs.ref }}
-          fetch-depth: 0
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
         with:
           node-version-file: package.json
           cache: true
-          run-install: true
+          run-install: |
+            args:
+              - --filter=t3...
 
       - name: Build node-pty linux-x64 prebuild
         shell: bash
@@ -359,14 +376,21 @@ jobs:
         uses: actions/checkout@v6
         with:
           ref: ${{ needs.preflight.outputs.ref }}
-          fetch-depth: 0
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
         with:
           node-version-file: package.json
           cache: true
-          run-install: true
+          run-install: |
+            args:
+              - --filter=@t3tools/desktop...
+              - --filter=t3...
+              - --filter=@t3tools/scripts...
 
       - name: Setup Rust
         uses: dtolnay/rust-toolchain@stable
@@ -657,6 +681,10 @@ jobs:
         uses: actions/checkout@v6
         with:
           ref: ${{ needs.preflight.outputs.ref }}
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
@@ -732,6 +760,10 @@ jobs:
         uses: actions/checkout@v6
         with:
           ref: ${{ needs.preflight.outputs.ref }}
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
@@ -853,6 +885,10 @@ jobs:
         uses: actions/checkout@v6
         with:
           ref: ${{ needs.preflight.outputs.ref }}
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
@@ -967,6 +1003,10 @@ jobs:
           fetch-depth: 0
           token: ${{ steps.app_token.outputs.token }}
           persist-credentials: true
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - id: app_bot
         name: Resolve GitHub App bot identity
@@ -1037,6 +1077,10 @@ jobs:
         uses: actions/checkout@v6
         with:
           ref: ${{ needs.preflight.outputs.ref }}
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1

From bc142f84a2f1ab47b7bca2c363b72f9115d76bda Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Thu, 30 Jul 2026 13:07:10 -0700
Subject: [PATCH 32/34] chore(mobile): bump app version to 1.0.1

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/mobile/app.config.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/mobile/app.config.ts b/apps/mobile/app.config.ts
index 4a0c761f2c6..92b8268c0e9 100644
--- a/apps/mobile/app.config.ts
+++ b/apps/mobile/app.config.ts
@@ -161,7 +161,7 @@ const config: ExpoConfig = {
   slug: "t3-code",
   platforms: ["ios", "android"],
   scheme: variant.scheme,
-  version: "0.1.0",
+  version: "1.0.1",
   runtimeVersion: {
     // Fingerprint (not appVersion) so an OTA only reaches binaries whose native
     // project — native deps, config plugins, AND patches/ — matches the update.

From 5b2577f6a941527e4db4ae32d6d0992e435d58a4 Mon Sep 17 00:00:00 2001
From: maria <maria@kuuro.net>
Date: Thu, 30 Jul 2026 16:08:05 -0400
Subject: [PATCH 33/34] style(web): make scroll-to-end pill translucent (#5036)

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

diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index 7aaae278908..f0a918e136f 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -5829,7 +5829,7 @@ function ChatViewContent(props: ChatViewProps) {
                     aria-label="Scroll to end"
                     title="Scroll to end"
                     onClick={() => scrollToEnd(true)}
-                    className="pointer-events-auto flex items-center gap-1.5 rounded-full border border-border/60 bg-card px-3 py-1 text-muted-foreground text-xs shadow-sm transition-colors hover:border-border hover:text-foreground hover:cursor-pointer"
+                    className="chat-composer-glass pointer-events-auto flex items-center gap-1.5 rounded-full border border-border/60 px-3 py-1 text-muted-foreground text-xs shadow-sm transition-colors hover:border-border hover:text-foreground hover:cursor-pointer"
                   >
                     <ChevronDownIcon className="size-3.5" />
                     Scroll to end

From 4029b858eaaa3f029d30a02a930f887853239169 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Thu, 30 Jul 2026 13:15:03 -0700
Subject: [PATCH 34/34] fix(ci): drop sparse-checkout from EAS workflows

actions/checkout implements sparse-checkout with --filter=blob:none, so
the runner repo is a partial clone missing the .repos/ blobs. eas-cli
archives the project via `git clone --depth 1 file://<workspace>`,
which upload-pack cannot serve from a partial clone and exits 128
(#4802 broke both EAS build workflows this way).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .github/workflows/mobile-eas-preview.yml    | 8 ++++----
 .github/workflows/mobile-eas-production.yml | 8 ++++----
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/mobile-eas-preview.yml b/.github/workflows/mobile-eas-preview.yml
index d8b07208c13..d53602f8f5e 100644
--- a/.github/workflows/mobile-eas-preview.yml
+++ b/.github/workflows/mobile-eas-preview.yml
@@ -39,10 +39,10 @@ jobs:
         uses: actions/checkout@v6
         with:
           fetch-depth: 0
-          sparse-checkout: |
-            /*
-            !/.repos/
-          sparse-checkout-cone-mode: false
+          # No sparse-checkout here: it makes actions/checkout fetch with
+          # --filter=blob:none, and eas-cli archives the project via
+          # `git clone --depth 1 file://<workspace>`, which fails (exit 128)
+          # when the partial clone can't serve the unfetched blobs.
 
       - name: Setup Vite+
         if: steps.expo-token.outputs.present == 'true'
diff --git a/.github/workflows/mobile-eas-production.yml b/.github/workflows/mobile-eas-production.yml
index 95cd0ddacc8..2e61de6039e 100644
--- a/.github/workflows/mobile-eas-production.yml
+++ b/.github/workflows/mobile-eas-production.yml
@@ -57,10 +57,10 @@ jobs:
         uses: actions/checkout@v6
         with:
           fetch-depth: 0
-          sparse-checkout: |
-            /*
-            !/.repos/
-          sparse-checkout-cone-mode: false
+          # No sparse-checkout here: it makes actions/checkout fetch with
+          # --filter=blob:none, and eas-cli archives the project via
+          # `git clone --depth 1 file://<workspace>`, which fails (exit 128)
+          # when the partial clone can't serve the unfetched blobs.
 
       - name: Setup Vite+
         if: steps.expo-token.outputs.present == 'true'