From 6221b0c8b76c1ae522431dacd6beba5b9c28536e Mon Sep 17 00:00:00 2001
From: Monarch Maisuriya <monarchmaisuriya7600@gmail.com>
Date: Wed, 4 Nov 2026 14:32:25 +0530
Subject: [PATCH 01/29] Fork from earlier replies when a plugin card was
 updated later (#8746)

The fork checkpoint check refused a fork when any projected row spanned the
selected reply. A plugin card re-appended with the same id keeps its first
position and stretches to its latest update, so it spanned every reply in
between, although the fork never copies plugin cards. The check now looks only
at the row kinds the fork copies, taken from the same constant as the copy.

Closes #8745

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/timeline-sync.md                         |  7 +++--
 .../src/server/agent/activity-curator.test.ts | 28 +++++++++++++++++++
 .../src/server/agent/activity-curator.ts      | 17 +++++++++--
 3 files changed, 47 insertions(+), 5 deletions(-)

diff --git a/docs/timeline-sync.md b/docs/timeline-sync.md
index 3d6af249bf..e12b4a495a 100644
--- a/docs/timeline-sync.md
+++ b/docs/timeline-sync.md
@@ -95,9 +95,10 @@ Provider message IDs are not guaranteed for every displayed item. Paseo-generate
 Actions that address a point in chat history, such as Fork, use the daemon timeline `epoch` plus the projected item's `seqEnd`. The app carries that position on the rendered assistant item for both live and fetched history. When adjacent projected chunks merge, the merged item retains the newer chunk's position.
 
 The daemon validates the epoch and locates the projected item at the selected position. A fork
-includes projected items through that checkpoint. If an item spans the checkpoint and changed
-afterward, the daemon refuses that fork with an actionable error: discarded historical payloads
-cannot be reconstructed from sequence metadata. Forking the current context remains available.
+includes projected items through that checkpoint. If an item the fork copies spans the checkpoint
+and changed afterward, the daemon refuses that fork with an actionable error: discarded historical
+payloads cannot be reconstructed from sequence metadata. Plugin cards are not copied, so a card
+updated after the checkpoint does not block it. Forking the current context remains available.
 
 ## Resume behavior
 
diff --git a/packages/server/src/server/agent/activity-curator.test.ts b/packages/server/src/server/agent/activity-curator.test.ts
index 4e9ce49528..6a1d85bcf0 100644
--- a/packages/server/src/server/agent/activity-curator.test.ts
+++ b/packages/server/src/server/agent/activity-curator.test.ts
@@ -454,6 +454,34 @@ second line'`,
     ).toThrow("Fork from a later completed response");
   });
 
+  it("forks from a checkpoint when a plugin card was updated after it", () => {
+    const card = (seq: number, turns: number) =>
+      row(seq, {
+        type: "plugin",
+        id: "memory-receipt",
+        pluginId: "memorise",
+        kind: "memory-receipt",
+        version: 1,
+        data: { turns },
+      });
+    const result = buildAgentForkContextAttachment({
+      boundaryMessageId: "assistant-1",
+      rows: [
+        row(1, { type: "user_message", text: "First question", messageId: "user-1" }),
+        card(2, 1),
+        row(3, { type: "assistant_message", text: "First answer.", messageId: "assistant-1" }),
+        row(4, { type: "user_message", text: "Second question", messageId: "user-2" }),
+        row(5, { type: "assistant_message", text: "Second answer.", messageId: "assistant-2" }),
+        card(6, 2),
+      ],
+    });
+
+    expect(result.attachment.text).toContain("[User] First question");
+    expect(result.attachment.text).toContain("[Assistant] First answer.");
+    expect(result.attachment.text).not.toContain("Second question");
+    expect(result.attachment.text).not.toContain("memory-receipt");
+  });
+
   it("selects a synthetic assistant error by its timeline cursor", () => {
     const result = buildAgentForkContextAttachment({
       cursorBoundary: {
diff --git a/packages/server/src/server/agent/activity-curator.ts b/packages/server/src/server/agent/activity-curator.ts
index 2a7cbff5e6..a0c537254a 100644
--- a/packages/server/src/server/agent/activity-curator.ts
+++ b/packages/server/src/server/agent/activity-curator.ts
@@ -13,6 +13,12 @@ const MAX_TOOL_SUMMARY_CHARS = 200;
 const MAX_FORK_CONTEXT_CHARS = 100_000;
 const MAX_FORK_METADATA_CHARS = 1_000;
 const FORK_HISTORY_OMITTED = "[Earlier chat history omitted]\n";
+// A fork copies only these kinds, so only they can make a checkpoint stale.
+const FORK_CONTEXT_KINDS: readonly AgentTimelineItem["type"][] = [
+  "user_message",
+  "assistant_message",
+  "tool_call",
+];
 
 interface ActivityCuratorOptions {
   maxItems?: number;
@@ -269,7 +275,14 @@ function selectForkContextRows(input: {
     );
   }
   const boundarySeq = projectedRows[boundaryIndex].seqEnd;
-  if (projectedRows.some((row) => row.seqStart <= boundarySeq && row.seqEnd > boundarySeq)) {
+  if (
+    projectedRows.some(
+      (row) =>
+        FORK_CONTEXT_KINDS.includes(row.item.type) &&
+        row.seqStart <= boundarySeq &&
+        row.seqEnd > boundarySeq,
+    )
+  ) {
     throw new Error(
       "This checkpoint changed after it was created. Fork from a later completed response instead.",
     );
@@ -349,7 +362,7 @@ export function buildAgentForkContextAttachment(input: {
   const entries = curateProjectedActivityEntries(selected.items, {
     maxItems: 0,
     labelAssistantMessages: true,
-    includeKinds: ["user_message", "assistant_message", "tool_call"],
+    includeKinds: FORK_CONTEXT_KINDS,
     includeExternalToolInput: false,
   });
   const metadata = { agentTitle: input.agentTitle, cwd: input.cwd };

From fcbfb4f0d373f050ee12a3b68f6e82889be84cc5 Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Wed, 4 Nov 2026 17:04:52 +0700
Subject: [PATCH 02/29] Size controls for touch on iPad and other touch screens
 (#8748)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(app): size controls for touch on any touch device, not just compact layouts

One gate picks touch or pointer sizing: touch when the layout is compact or
the device has a touch screen. The touch fact is read once, so attaching a
mouse or keyboard to a tablet never shrinks its controls. Stylesheets take
`bySizing({ touch, pointer })`, which resolves to a breakpoint value, so the
existing `{ xs, md }` consumers follow the gate without call-site changes.

Touch values follow the iOS HIG 44pt hit region: controls, icon buttons,
rows, bars and menu rows are 44 on touch; `sm` controls are 32. Glyphs move
to a touch ladder (14/18/20/24). Pointer sizes are unchanged.

Merges duplicated header control heights, density's private icon ladder and
the compact-only icon button sizes into control-geometry.

* feat(app): size the composer for touch through control geometry

The composer toolbar, attach / dictation / realtime / send buttons, context
meter and model triggers take TOOLBAR_CONTROL_SIZES (28 pointer, 44 touch)
instead of private 28 constants. The density budget, button glyphs and the
fullscreen glyph rail offset resolve the same gate, replacing the isWeb /
isNative glyph branches. Track rows join the menu row height.

Desktop geometry is unchanged. On touch the toolbar steps down density
earlier: iPad portrait goes from condensed to tight.

* feat(app): fold composer controls before the model label truncates

The composer toolbar walks one width budget: full, condensed, tight,
compact, then icon-only. Tight keeps the model at its family label;
below that, thinking, mode and features fold into the model control's
sheet (the phone toolbar), and only then does the model drop its label.
A touch iPad in portrait with an attachment now reads
"GPT-6-Astra Medium" instead of "GP…".

The context meter glyph and combobox rows and icons take the density
ladder. Desktop is pixel-identical in the content area.

* refactor(app): keep the sizing gate free of the theme

constants/layout sized its bars through control-geometry, which loads the
theme and runs Platform.select at import. The gate (resolveControlSizing,
bySizing, TOUCH_TARGET) moves to control-sizing.ts with no theme import;
control-geometry re-exports it, so its callers are unchanged.

* test(app): expect touch sizing in the compact Changes and plugin sidebar specs

The compact Changes options button is a 44pt icon button with a 20pt glyph,
and its framed actions trigger is 32 tall. In the compact sidebar the nav
block is capped at half the height, so 44pt rows put the plugin header row
below the cap; the spec scrolls it into view as a user would.

* fix(app): close composer menus when the controls fold or unfold

Folding swaps the toolbar controls for the model sheet. A menu opened on the
separate controls stayed marked open across the fold, so widening the
composer again reopened Thinking without a click.
---
 docs/design.md                                |   8 +-
 packages/app/e2e/browser/changes-pane.spec.ts |  10 +-
 .../browser/composer-control-density.spec.ts  |  32 +++
 .../e2e/browser/plugin-sidebar-items.spec.ts  |   5 +-
 .../components/combined-model-selector.tsx    |   3 +-
 .../src/components/context-window-meter.tsx   |   7 +-
 .../src/components/settings/row-density.tsx   |   4 +-
 .../src/components/sidebar-workspace-list.tsx |  13 +-
 .../sidebar/sidebar-workspace-menu.tsx        |  13 +-
 packages/app/src/components/ui/combobox.tsx   |  18 +-
 .../components/ui/control-geometry.test.ts    |  97 +++++--
 .../app/src/components/ui/control-geometry.ts | 108 +++++---
 .../app/src/components/ui/control-sizing.ts   |  68 +++++
 .../src/components/ui/icon-button-chrome.ts   |  44 +--
 .../src/components/ui/menu/menu-geometry.ts   |   5 +-
 .../src/composer/agent-controls/control.tsx   |   5 +-
 .../app/src/composer/agent-controls/glyph.tsx |   6 +-
 .../app/src/composer/agent-controls/index.tsx |  59 ++--
 .../agent-controls/layout-context.tsx         |  12 +-
 .../composer/agent-controls/layout.test.ts    | 126 ++++++++-
 .../app/src/composer/agent-controls/layout.ts | 253 +++++++++++++-----
 .../composer/agent-controls/mode-control.tsx  |  11 +-
 .../composer/agent-controls/model-sheet.tsx   |  36 ++-
 packages/app/src/composer/index.tsx           |  28 +-
 packages/app/src/composer/input/input.tsx     |  29 +-
 .../app/src/composer/input/presentation.tsx   |  34 ++-
 packages/app/src/composer/tracks.tsx          |  10 +-
 packages/app/src/constants/layout.ts          |  11 +-
 packages/app/src/git/actions-split-button.tsx |  27 +-
 .../git/pull-request-panel/section-kit.tsx    |   6 +-
 packages/app/src/hooks/use-fine-pointer.ts    |  10 +
 packages/app/src/plugins/buttons/view.tsx     |   4 +-
 packages/app/src/screens/settings-screen.tsx  |   6 +-
 .../scripts/workspace-scripts-button.tsx      |   7 +-
 .../workspace/workspace-desktop-tabs-row.tsx  |  17 +-
 packages/app/src/styles/density.ts            |  41 +--
 .../src/workspace/open-in-editor/button.tsx   |  17 +-
 37 files changed, 832 insertions(+), 358 deletions(-)
 create mode 100644 packages/app/src/components/ui/control-sizing.ts

diff --git a/docs/design.md b/docs/design.md
index 8a2cae25ba..0437320c09 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -68,9 +68,11 @@ the sidebar. Apply it as `backgroundColor`; setting `opacity` on the control als
 
 `destructive` is filled with `destructive`. It only appears inside a confirm. The button on the page is `outline`; the destructive button is the confirm button inside the dialog.
 
-Controls come in two sizes, defined once in `control-geometry.ts`. The default is the right size almost everywhere — pages, dialogs, forms, settings rows, the setup flow — so don't pass a size. It is 32px tall where a pointer drives it and 44px in the compact layout, so every phone control is a full touch target; the breakpoint, not the caller, makes that choice. `sm` is 28px with `fontSize.sm` labels and is for tight chrome only: toolbars, nested settings rows, dense inline row actions. A `size="sm"` on an ordinary page or dialog is wrong, and so is choosing a size from `useIsCompactFormFactor()`.
+Controls come in two sizes, defined once in `control-geometry.ts`. The default is the right size almost everywhere — pages, dialogs, forms, settings rows, the setup flow — so don't pass a size. It is 32px tall where a pointer drives it and 44px where controls are touch-sized, so every touch control meets the iOS HIG's 44pt hit region. `sm` is 28px pointer and 32px touch, with `fontSize.sm` labels, and is for tight chrome only: toolbars, nested settings rows, dense inline row actions. A `size="sm"` on an ordinary page or dialog is wrong, and so is choosing a size from `useIsCompactFormFactor()`.
 
-Buttons are pills (`borderRadius.full`) with medium-weight labels; an icon-only button is a circle. `<Switch>` follows the same two sizes: a 34×20 track by default and in `sm`, 44×26 in the compact layout, and it reserves its size's control height so a row holding one lines up with a row holding a button. Buttons, text fields, dropdown triggers, and `<SegmentedControl>` (`packages/app/src/components/ui/segmented-control.tsx`) share the size contract — the same size name means the same height and label size on every control kind, so controls in one row line up. Segments run tighter than a button, because the gap between segments already reads as padding. The selected segment is a `surface3` fill with `foreground` text, not an inverted one — inverting it inside thin chrome puts a white slab in the toolbar. A settings row sizes the controls in its trailing slot itself, default in a card and `sm` when nested (`packages/app/src/components/ui/control-size.tsx`), so don't pass a size to a button, dropdown or field placed in a row. Code that computes with a control's height outside a stylesheet uses `controlHeightForLayout`. Never shrink a control's font or padding locally to fit a context — if the context needs a smaller control, the size tier is missing or the wrong one is in use.
+One gate, `resolveControlSizing`, picks touch or pointer sizing: touch when the layout is compact or the device has a touch screen. An iPad with the sidebar docked is wide and touch-sized; a desktop is pointer-sized; a phone is both compact and touch. The touch-screen fact is read once at startup (`hasTouchScreen` in `hooks/use-fine-pointer.ts`), so attaching a mouse or keyboard to a tablet never shrinks its controls. Stylesheets take sizes from `bySizing({ touch, pointer })`, which resolves to a breakpoint value, so a caller never sees which sizing it got. Rows, icon buttons and icon slots take theirs from `styles/density.ts`, which uses the same gate. An `{ xs, md }` literal for a hit target or glyph is wrong: on an iPad it yields the pointer size.
+
+Buttons are pills (`borderRadius.full`) with medium-weight labels; an icon-only button is a circle. `<Switch>` follows the same two sizes: a 34×20 track by default and in `sm`, 44×26 where controls are touch-sized, and it reserves its size's control height so a row holding one lines up with a row holding a button. Buttons, text fields, dropdown triggers, and `<SegmentedControl>` (`packages/app/src/components/ui/segmented-control.tsx`) share the size contract — the same size name means the same height and label size on every control kind, so controls in one row line up. Segments run tighter than a button, because the gap between segments already reads as padding. The selected segment is a `surface3` fill with `foreground` text, not an inverted one — inverting it inside thin chrome puts a white slab in the toolbar. A settings row sizes the controls in its trailing slot itself, default in a card and `sm` when nested (`packages/app/src/components/ui/control-size.tsx`), so don't pass a size to a button, dropdown or field placed in a row. Code that computes with a control's height outside a stylesheet uses `controlHeightForLayout`. Never shrink a control's font or padding locally to fit a context — if the context needs a smaller control, the size tier is missing or the wrong one is in use.
 
 A `<Pressable>` wrapping a `<Text>` is a sixth variant. It is wrong. `<Button>` accepts `style`, `textStyle`, `leftIcon`, `disabled`, `size`, and `variant`.
 
@@ -150,7 +152,7 @@ One row off the rail makes the whole card look unconsidered.
 
 Compact-first. The small case is designed; the large case adds chrome around it.
 
-Use `md: 600` for both the compact/wide layout boundary and responsive density, in logical points on native and CSS pixels on web. Do not add a separate density breakpoint. Measured content constraints remain independent: composer controls use `COMPACT_CONTENT_WIDTH` (500), so a narrow pane can keep compact controls inside a wide window.
+Use `md: 600` for the compact/wide layout boundary, in logical points on native and CSS pixels on web. Do not add a separate density breakpoint; touch sizing comes from the control sizing gate in [Buttons](#4-buttons). Measured content constraints remain independent: composer controls use `COMPACT_CONTENT_WIDTH` (500), so a narrow pane can keep compact controls inside a wide window.
 
 The settings shell (`packages/app/src/screens/settings-screen.tsx`) and the projects screen (`packages/app/src/screens/projects-screen.tsx`) share the canonical list+detail navigation pattern:
 
diff --git a/packages/app/e2e/browser/changes-pane.spec.ts b/packages/app/e2e/browser/changes-pane.spec.ts
index 1ff6059460..aa884c66e9 100644
--- a/packages/app/e2e/browser/changes-pane.spec.ts
+++ b/packages/app/e2e/browser/changes-pane.spec.ts
@@ -928,11 +928,11 @@ test("compact Changes keeps its actions compact and menu-only", async ({ page })
     throw new Error("Compact Changes toolbar geometry could not be measured");
   }
   expect(actionsBox.width).toBe(48);
-  expect(actionsBox.height).toBe(28);
-  expect(optionsBox.width).toBe(32);
-  expect(optionsBox.height).toBe(32);
-  expect(glyphBox.width).toBe(18);
-  expect(glyphBox.height).toBe(18);
+  expect(actionsBox.height).toBe(32);
+  expect(optionsBox.width).toBe(44);
+  expect(optionsBox.height).toBe(44);
+  expect(glyphBox.width).toBe(20);
+  expect(glyphBox.height).toBe(20);
 
   await expect(actions).not.toContainText("Commit");
   await expect(actions.locator("svg")).toHaveCount(2);
diff --git a/packages/app/e2e/browser/composer-control-density.spec.ts b/packages/app/e2e/browser/composer-control-density.spec.ts
index 9c81037526..ebd9717feb 100644
--- a/packages/app/e2e/browser/composer-control-density.spec.ts
+++ b/packages/app/e2e/browser/composer-control-density.spec.ts
@@ -5,6 +5,7 @@ import {
   recordComposerToolbarFrames,
 } from "../support/helpers/composer-control-density";
 import { clickNewChat, gotoWorkspace } from "../support/helpers/launcher";
+import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
 import { seedWorkspace, type SeededWorkspace } from "../support/helpers/seed-client";
 
 const SETTLE_MS = 1_000;
@@ -92,3 +93,34 @@ test.describe("Composer control density across tab switches", () => {
     }
   });
 });
+
+test.describe("Composer controls folding on a touch device", () => {
+  test.use({ viewport: { width: 1194, height: 834 }, isMobile: true, hasTouch: true });
+  test.describe.configure({ timeout: 180_000 });
+
+  test("an open menu stays closed after the controls fold and unfold", async ({ page }) => {
+    const session = await seedMockAgentWorkspace({
+      repoPrefix: "composer-density-fold-",
+      title: "Folding chat",
+      model: "ten-second-stream",
+    });
+    try {
+      await openAgentRoute(page, session);
+      const thinking = page.getByTestId("agent-thinking-selector").filter({ visible: true });
+      const thinkingMenu = page.getByTestId("combobox-desktop-container");
+
+      await thinking.click();
+      await expect(thinkingMenu).toBeVisible();
+
+      // Still a wide layout, but too narrow for separate controls: they fold into the model control.
+      await page.setViewportSize({ width: 640, height: 834 });
+      await expect(thinking).toHaveCount(0);
+
+      await page.setViewportSize({ width: 1194, height: 834 });
+      await expect(thinking).toBeVisible();
+      await expect(thinkingMenu).toHaveCount(0);
+    } finally {
+      await session.cleanup();
+    }
+  });
+});
diff --git a/packages/app/e2e/browser/plugin-sidebar-items.spec.ts b/packages/app/e2e/browser/plugin-sidebar-items.spec.ts
index dfba0ec816..e91b6a55da 100644
--- a/packages/app/e2e/browser/plugin-sidebar-items.spec.ts
+++ b/packages/app/e2e/browser/plugin-sidebar-items.spec.ts
@@ -317,7 +317,10 @@ test.describe("Plugin sidebar items", () => {
       const compactSync = footerItem(page, SHOWCASE_PLUGIN_ID, "sync");
       await expect(compactSync).toBeInViewport();
       await expectFooterRow(page, compactSync);
-      await expect(headerRow(page, SHOWCASE_PLUGIN_ID, "deploys")).toBeInViewport();
+      // The compact nav block is capped at half the sidebar and scrolls past it.
+      const compactDeploys = headerRow(page, SHOWCASE_PLUGIN_ID, "deploys");
+      await compactDeploys.scrollIntoViewIfNeeded();
+      await expect(compactDeploys).toBeInViewport();
       await qaScreenshot(page, "phase2-compact-sidebar");
       await qaScreenshot(page, "phase5-compact-footer", sidebarFooter(page));
       await compactSync.click();
diff --git a/packages/app/src/components/combined-model-selector.tsx b/packages/app/src/components/combined-model-selector.tsx
index 8473760c92..2f6ab0137e 100644
--- a/packages/app/src/components/combined-model-selector.tsx
+++ b/packages/app/src/components/combined-model-selector.tsx
@@ -13,6 +13,7 @@ import { useIsCompactFormFactor } from "@/constants/layout";
 import { isNative, isWeb } from "@/constants/platform";
 import type { ProviderSelectorProvider } from "@/provider-selection/provider-selection";
 import { ICON_SIZE, type Theme } from "@/styles/theme";
+import { TOOLBAR_CONTROL_HEIGHT } from "@/components/ui/control-geometry";
 
 const EMPTY_COMBOBOX_OPTIONS: ComboboxOption[] = [];
 const ThemedLoadingSpinner = withUnistyles(LoadingSpinner);
@@ -292,7 +293,7 @@ const styles = StyleSheet.create((theme) => ({
     paddingHorizontal: 0,
   },
   trigger: {
-    height: 28,
+    height: TOOLBAR_CONTROL_HEIGHT,
     minWidth: 0,
     flexShrink: 1,
     flexDirection: "row",
diff --git a/packages/app/src/components/context-window-meter.tsx b/packages/app/src/components/context-window-meter.tsx
index 32c739c073..4d78ea7592 100644
--- a/packages/app/src/components/context-window-meter.tsx
+++ b/packages/app/src/components/context-window-meter.tsx
@@ -9,6 +9,7 @@ import { useIsCompactFormFactor } from "@/constants/layout";
 import { isNative } from "@/constants/platform";
 import { useHostReportsUsage } from "@/usage";
 import type { Theme } from "@/styles/theme";
+import { TOOLBAR_CONTROL_HEIGHT } from "@/components/ui/control-geometry";
 import { ContextWindowDetails } from "./context-window-details";
 import { ContextWindowSheet } from "./context-window-sheet";
 import { formatContextPercentage } from "./context-window-meter.utils";
@@ -306,14 +307,14 @@ export function ContextWindowMeter({
 
 const styles = StyleSheet.create((theme) => ({
   container: {
-    width: 28,
-    height: 28,
+    width: TOOLBAR_CONTROL_HEIGHT,
+    height: TOOLBAR_CONTROL_HEIGHT,
     borderRadius: theme.borderRadius.full,
     alignItems: "center",
     justifyContent: "center",
   },
   containerWithLabel: {
-    height: 28,
+    height: TOOLBAR_CONTROL_HEIGHT,
     flexDirection: "row",
     alignItems: "center",
     justifyContent: "center",
diff --git a/packages/app/src/components/settings/row-density.tsx b/packages/app/src/components/settings/row-density.tsx
index 8a52d6cdab..3682899624 100644
--- a/packages/app/src/components/settings/row-density.tsx
+++ b/packages/app/src/components/settings/row-density.tsx
@@ -1,7 +1,7 @@
 import { createContext, useContext, useMemo, type ReactNode } from "react";
 import type { StyleProp, TextStyle, ViewStyle } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
-import { CONTROL_HEIGHTS, type ControlSize } from "@/components/ui/control-geometry";
+import { CONTROL_HEIGHTS, mapLayout, type ControlSize } from "@/components/ui/control-geometry";
 
 import { settingsStyles } from "@/styles/settings";
 
@@ -49,7 +49,7 @@ const styles = StyleSheet.create((theme) => ({
   // trailing button line up.
   nestedRow: {
     paddingVertical: theme.spacing[2],
-    minHeight: CONTROL_HEIGHTS.sm + theme.spacing[2] * 2,
+    minHeight: mapLayout(CONTROL_HEIGHTS.sm, (height) => height + theme.spacing[2] * 2),
   },
   nestedText: {
     fontSize: theme.fontSize.sm,
diff --git a/packages/app/src/components/sidebar-workspace-list.tsx b/packages/app/src/components/sidebar-workspace-list.tsx
index 8697a4b27b..5000e1f067 100644
--- a/packages/app/src/components/sidebar-workspace-list.tsx
+++ b/packages/app/src/components/sidebar-workspace-list.tsx
@@ -154,6 +154,7 @@ import type { HostBadgeModel } from "@/hosts/appearance";
 import { useHostBadges } from "@/hosts/use-host-badges";
 import { useSidebarRowItems } from "@/components/sidebar/display-preferences/model";
 import { PullRequestStateIcon } from "@/git/pull-request-state-icon";
+import { bySizing } from "@/components/ui/control-geometry";
 
 const workspaceKeyExtractor = (workspace: SidebarWorkspacePlacement) => workspace.workspaceKey;
 
@@ -2737,12 +2738,12 @@ const styles = StyleSheet.create((theme) => ({
     marginRight: -6,
   },
   projectKebabButton: {
-    // Larger on compact so the kebab is an easy tap target. The negative margins keep its
-    // dots on the same rail as the 24px desktop box and the row at its 44px height.
-    width: { xs: 32, md: 24 },
-    height: { xs: 32, md: 24 },
-    marginRight: { xs: -4, md: 0 },
-    marginVertical: { xs: -4, md: 0 },
+    // Larger on touch so the kebab is an easy tap target. The negative margins keep its
+    // dots on the same rail as the 24px pointer box and the row at its 44px height.
+    width: bySizing({ touch: 32, pointer: 24 }),
+    height: bySizing({ touch: 32, pointer: 24 }),
+    marginRight: bySizing({ touch: -4, pointer: 0 }),
+    marginVertical: bySizing({ touch: -4, pointer: 0 }),
     borderRadius: theme.borderRadius.md,
     alignItems: "center",
     justifyContent: "center",
diff --git a/packages/app/src/components/sidebar/sidebar-workspace-menu.tsx b/packages/app/src/components/sidebar/sidebar-workspace-menu.tsx
index f74c43c980..64a3099047 100644
--- a/packages/app/src/components/sidebar/sidebar-workspace-menu.tsx
+++ b/packages/app/src/components/sidebar/sidebar-workspace-menu.tsx
@@ -36,6 +36,7 @@ import {
 import { Shortcut } from "@/components/ui/shortcut";
 import { OpenInFileManagerMenuItem } from "@/workspace/open-in-file-manager/menu-item";
 import { resolveSidebarWorkspaceAccessibilityLabel } from "@/components/sidebar/sidebar-workspace-title";
+import { bySizing } from "@/components/ui/control-geometry";
 import {
   workspaceServiceLabelKey,
   type WorkspaceServiceSummary,
@@ -438,18 +439,18 @@ function triggerStyle({ hovered = false }: PressableStateCallbackType & { hovere
 
 const styles = StyleSheet.create((theme) => ({
   trigger: {
-    // Larger on compact so the kebab is an easy tap target.
-    width: { xs: 32, md: 18 },
-    height: { xs: 32, md: 18 },
+    // Larger on touch so the kebab is an easy tap target.
+    width: bySizing({ touch: 32, pointer: 18 }),
+    height: bySizing({ touch: 32, pointer: 18 }),
     alignItems: "center",
     justifyContent: "center",
     borderRadius: 4,
     marginLeft: 2,
-    // Center the compact box on the 20px title line it is anchored to.
-    marginTop: { xs: -6, md: 0 },
+    // Center the touch box on the 20px title line it is anchored to.
+    marginTop: bySizing({ touch: -6, pointer: 0 }),
     // MoreVertical paints only around the center of its SVG. Keep the padded hit box, but
     // pull the painted dots through that unused view-box space onto the trailing-content rail.
-    marginRight: { xs: -14, md: -7 },
+    marginRight: bySizing({ touch: -14, pointer: -7 }),
   },
   triggerHovered: {
     backgroundColor: theme.colors.surface2,
diff --git a/packages/app/src/components/ui/combobox.tsx b/packages/app/src/components/ui/combobox.tsx
index 5a2da0a365..cee4fc2dea 100644
--- a/packages/app/src/components/ui/combobox.tsx
+++ b/packages/app/src/components/ui/combobox.tsx
@@ -64,6 +64,8 @@ import {
 import { FloatingSurface } from "@/components/ui/floating";
 import { useDismissKeyboardOnOpen } from "@/components/ui/keyboard-dismiss";
 import { getOverlayRoot, OverlayLayerProvider, useOverlayLayer } from "@/lib/overlay-root";
+import { density, densityIconBox } from "@/styles/density";
+import { DensityIcon } from "@/components/ui/density-icon";
 import { buildDesktopFrameStyle } from "./combobox-frame-style";
 
 export { buildDesktopFrameStyle } from "./combobox-frame-style";
@@ -203,7 +205,7 @@ export function SearchInput({
 
   return (
     <View style={styles.searchInputContainer}>
-      <Search size={16} color={theme.colors.foregroundMuted} />
+      <DensityIcon icon={Search} size="md" color="foregroundMuted" />
       <AdaptiveTextInput
         ref={inputRef}
         // @ts-expect-error - outlineStyle is web-only
@@ -250,21 +252,19 @@ export function ComboboxItem({
   onPress,
   testID,
 }: ComboboxItemProps): ReactElement {
-  const { theme } = useUnistyles();
-
   let leadingContent: ReactElement | null = null;
   if (leadingSlot) {
     leadingContent = <View style={styles.comboboxItemLeadingSlot}>{leadingSlot}</View>;
   } else if (kind === "directory") {
     leadingContent = (
       <View style={styles.comboboxItemLeadingSlot}>
-        <Folder size={16} color={theme.colors.foregroundMuted} />
+        <DensityIcon icon={Folder} size="md" color="foregroundMuted" />
       </View>
     );
   } else if (kind === "file") {
     leadingContent = (
       <View style={styles.comboboxItemLeadingSlot}>
-        <File size={16} color={theme.colors.foregroundMuted} />
+        <DensityIcon icon={File} size="md" color="foregroundMuted" />
       </View>
     );
   }
@@ -308,7 +308,7 @@ export function ComboboxItem({
       {selected || trailingSlot ? (
         <View style={styles.comboboxItemTrailingContainer}>
           <View style={styles.comboboxItemTrailingSlot}>
-            {selected ? <Check size={16} color={theme.colors.foregroundMuted} /> : null}
+            {selected ? <DensityIcon icon={Check} size="md" color="foregroundMuted" /> : null}
           </View>
           {trailingSlot}
         </View>
@@ -1682,7 +1682,7 @@ const styles = StyleSheet.create((theme) => ({
   comboboxItem: {
     flexDirection: "row",
     alignItems: "center",
-    minHeight: 36,
+    minHeight: density.rowHeight,
     gap: theme.spacing[2],
     paddingHorizontal: theme.spacing[3],
     paddingVertical: theme.spacing[2],
@@ -1713,7 +1713,7 @@ const styles = StyleSheet.create((theme) => ({
     opacity: 0.55,
   },
   comboboxItemTrailingSlot: {
-    width: 16,
+    width: densityIconBox("md"),
     alignItems: "center",
     justifyContent: "center",
   },
@@ -1733,7 +1733,7 @@ const styles = StyleSheet.create((theme) => ({
     gap: theme.spacing[2],
   },
   comboboxItemLeadingSlot: {
-    width: 16,
+    width: densityIconBox("md"),
     alignItems: "center",
     justifyContent: "center",
   },
diff --git a/packages/app/src/components/ui/control-geometry.test.ts b/packages/app/src/components/ui/control-geometry.test.ts
index dc39cdf596..90b18d6029 100644
--- a/packages/app/src/components/ui/control-geometry.test.ts
+++ b/packages/app/src/components/ui/control-geometry.test.ts
@@ -1,11 +1,20 @@
 import { describe, expect, it } from "vitest";
 import {
   ALERT_ICON_SIZE,
+  bySizing,
   CONTROL_HEIGHTS,
   controlHeightForLayout,
+  controlSizingForLayout,
   createControlGeometry,
+  HEADER_CONTROL_HEIGHT,
+  ICON_BUTTON_SIZES,
+  iconSizeFor,
+  resolveControlSizing,
   switchGeometryForLayout,
   getControlInteractionPhase,
+  TOOLBAR_CONTROL_HEIGHT,
+  TOOLBAR_CONTROL_SIZES,
+  TOUCH_TARGET,
 } from "@/components/ui/control-geometry";
 import type { Theme } from "@/styles/theme";
 
@@ -47,6 +56,52 @@ const theme = {
   },
 } as unknown as Theme;
 
+describe("control sizing gate", () => {
+  it("is touch-sized in the compact layout or on a touch screen, and pointer-sized otherwise", () => {
+    expect(resolveControlSizing({ compactLayout: true, touchScreen: true })).toBe("touch");
+    expect(resolveControlSizing({ compactLayout: true, touchScreen: false })).toBe("touch");
+    expect(resolveControlSizing({ compactLayout: false, touchScreen: true })).toBe("touch");
+    expect(resolveControlSizing({ compactLayout: false, touchScreen: false })).toBe("pointer");
+  });
+
+  it("gives a touch screen its touch sizes at every width", () => {
+    const sizes = { touch: 44, pointer: 32 };
+
+    // An iPad: touch-sized in the docked desktop layout too.
+    expect(bySizing(sizes, true)).toEqual({ xs: 44, md: 44 });
+    // A mouse-driven window: touch-sized only once it narrows into the compact layout.
+    expect(bySizing(sizes, false)).toEqual({ xs: 44, md: 32 });
+  });
+
+  it("keeps a device without a touch screen on pointer sizes from md up", () => {
+    // The unit runtime has no touch screen, which is the desktop that must not change.
+    expect(controlSizingForLayout(false)).toBe("pointer");
+    expect(controlSizingForLayout(true)).toBe("touch");
+    expect(CONTROL_HEIGHTS.md).toEqual({ xs: 44, md: 32 });
+    expect(CONTROL_HEIGHTS.sm).toEqual({ xs: 32, md: 28 });
+    expect(HEADER_CONTROL_HEIGHT).toEqual({ xs: 32, md: 26 });
+  });
+
+  it("follows the HIG on touch: a 44pt target, no control under 28pt, larger glyphs", () => {
+    expect(TOUCH_TARGET).toBe(44);
+    expect(controlHeightForLayout("md", true)).toBe(TOUCH_TARGET);
+    expect(ICON_BUTTON_SIZES.large.touch).toBe(TOUCH_TARGET);
+    expect(ICON_BUTTON_SIZES.small.touch).toBe(TOUCH_TARGET);
+    // Composer toolbar controls: a full target on touch, unchanged 28 on pointer.
+    expect(TOOLBAR_CONTROL_SIZES).toEqual({ touch: TOUCH_TARGET, pointer: 28 });
+    expect(TOOLBAR_CONTROL_HEIGHT).toEqual({ xs: TOUCH_TARGET, md: 28 });
+    for (const size of ["sm", "md"] as const) {
+      expect(controlHeightForLayout(size, true)).toBeGreaterThan(
+        controlHeightForLayout(size, false),
+      );
+      expect(controlHeightForLayout(size, false)).toBeGreaterThanOrEqual(28);
+    }
+    for (const size of ["xs", "sm", "md", "lg"] as const) {
+      expect(iconSizeFor(size).touch).toBeGreaterThan(iconSizeFor(size).pointer);
+    }
+  });
+});
+
 describe("control geometry", () => {
   it("keeps resting control borders transparent while preserving border geometry", () => {
     const geometry = createControlGeometry(theme);
@@ -98,18 +153,17 @@ describe("control geometry", () => {
     const geometry = createControlGeometry(theme);
     const borderWidth = theme.borderWidth[1];
 
-    expect(geometry.fieldControlSm.minHeight).toBe(28);
-    expect(
-      geometry.fieldTextSm.lineHeight +
-        geometry.fieldControlSm.paddingVertical * 2 +
-        borderWidth * 2,
-    ).toBe(geometry.fieldControlSm.minHeight);
-
+    expect(geometry.fieldControlSm.minHeight).toEqual({ xs: 32, md: 28 });
     // The default keeps a 44 touch target in the compact layout and is 32 from the md
     // breakpoint up.
     expect(geometry.fieldControlMd.minHeight).toEqual({ xs: 44, md: 32 });
     expect(geometry.fieldControlMd.paddingVertical).toEqual({ xs: 11, md: 5 });
     for (const layout of ["xs", "md"] as const) {
+      expect(
+        geometry.fieldTextSm.lineHeight +
+          geometry.fieldControlSm.paddingVertical[layout] * 2 +
+          borderWidth * 2,
+      ).toBe(geometry.fieldControlSm.minHeight[layout]);
       expect(
         geometry.fieldTextMd.lineHeight +
           geometry.fieldControlMd.paddingVertical[layout] * 2 +
@@ -125,24 +179,25 @@ describe("control geometry", () => {
     expect(geometry.segmentedContainerMd.padding).toBe(0);
     expect(geometry.segmentedSegmentSm.borderRadius).toBe(geometry.buttonSm.borderRadius);
     expect(geometry.segmentedSegmentMd.borderRadius).toBe(geometry.buttonMd.borderRadius);
-    expect(geometry.segmentedContainerSm.minHeight).toBe(geometry.buttonSm.minHeight);
+    expect(geometry.segmentedContainerSm.minHeight).toEqual(geometry.buttonSm.minHeight);
     expect(geometry.segmentedContainerMd.minHeight).toEqual(geometry.buttonMd.minHeight);
-    expect(geometry.segmentedSegmentSm.minHeight).toBe(24);
+    expect(geometry.segmentedSegmentSm.minHeight).toEqual({ xs: 28, md: 24 });
     expect(geometry.segmentedSegmentMd.minHeight).toEqual({ xs: 40, md: 28 });
   });
 
   it("keeps one size contract across buttons, fields, and segmented controls", () => {
     const geometry = createControlGeometry(theme);
 
-    expect(geometry.buttonSm.minHeight).toBe(28);
+    expect(geometry.buttonSm.minHeight).toEqual({ xs: 32, md: 28 });
     expect(geometry.buttonMd.minHeight).toEqual({ xs: 44, md: 32 });
-    expect(geometry.buttonSm.minHeight).toBe(CONTROL_HEIGHTS.sm);
+    expect(geometry.buttonSm.minHeight).toEqual(CONTROL_HEIGHTS.sm);
     expect(geometry.buttonMd.minHeight).toEqual(CONTROL_HEIGHTS.md);
-    expect(geometry.fieldControlSm.minHeight).toBe(CONTROL_HEIGHTS.sm);
+    expect(geometry.fieldControlSm.minHeight).toEqual(CONTROL_HEIGHTS.sm);
     expect(geometry.fieldControlMd.minHeight).toEqual(CONTROL_HEIGHTS.md);
     expect(controlHeightForLayout("md", true)).toBe(44);
     expect(controlHeightForLayout("md", false)).toBe(32);
-    expect(controlHeightForLayout("sm", true)).toBe(28);
+    expect(controlHeightForLayout("sm", true)).toBe(32);
+    expect(controlHeightForLayout("sm", false)).toBe(28);
 
     // Same size name means the same label size on every control kind.
     expect(geometry.segmentedLabelSm.fontSize).toBe(12);
@@ -177,13 +232,15 @@ describe("control geometry", () => {
       thumbTravel: 18,
       reservedHeight: 44,
     });
-    // Tight chrome keeps the pointer-sized switch on every layout.
-    for (const isCompact of [true, false]) {
-      expect(switchGeometryForLayout("sm", isCompact)).toMatchObject({
-        trackWidth: 34,
-        reservedHeight: 28,
-      });
-    }
+    // Tight chrome keeps the pointer-sized track on every layout and reserves its row's height.
+    expect(switchGeometryForLayout("sm", true)).toMatchObject({
+      trackWidth: 34,
+      reservedHeight: 32,
+    });
+    expect(switchGeometryForLayout("sm", false)).toMatchObject({
+      trackWidth: 34,
+      reservedHeight: 28,
+    });
   });
 
   it("gives alert title and description one font size and a tight gap per size", () => {
diff --git a/packages/app/src/components/ui/control-geometry.ts b/packages/app/src/components/ui/control-geometry.ts
index ef2f6a7a72..407c042cbe 100644
--- a/packages/app/src/components/ui/control-geometry.ts
+++ b/packages/app/src/components/ui/control-geometry.ts
@@ -1,5 +1,14 @@
 import type { StyleProp, ViewStyle } from "react-native";
 import { ICON_SIZE, type Theme } from "@/styles/theme";
+import {
+  bySizing,
+  controlSizingForLayout,
+  mapLayout,
+  TOUCH_TARGET,
+  type ControlSizing,
+  type LayoutValue,
+  type SizingValue,
+} from "./control-sizing";
 
 /**
  * Controls come in two sizes. `md` is the default and the right size almost everywhere;
@@ -26,46 +35,78 @@ export interface ControlInteractionStyleMap {
   controlDisabled?: StyleProp<ViewStyle>;
 }
 
-const SMALL_CONTROL_HEIGHT = 28;
-// The default control keeps a full touch target in the compact layout and tightens where a
-// pointer drives it.
-const DEFAULT_CONTROL_HEIGHT_COMPACT_LAYOUT = 44;
-const DEFAULT_CONTROL_HEIGHT_WIDE_LAYOUT = 32;
-export const HEADER_CONTROL_HEIGHT = 26;
+export {
+  bySizing,
+  controlSizingForLayout,
+  mapLayout,
+  resolveControlSizing,
+  TOUCH_TARGET,
+  type ControlSizing,
+  type ControlSizingFacts,
+  type LayoutValue,
+  type SizingValue,
+} from "./control-sizing";
+
+// Touch `md` is the iOS HIG's 44pt default control; touch `sm` stays above its 28pt minimum.
+const CONTROL_SIZES = {
+  sm: { touch: 32, pointer: 28 },
+  md: { touch: TOUCH_TARGET, pointer: 32 },
+} satisfies Record<ControlSize, SizingValue>;
+
+/** Pointer-sized header controls run tighter than `sm` so they fit the 36pt header. */
+const POINTER_HEADER_CONTROL_HEIGHT = 26;
 const SEGMENTED_INSET = 2;
 const CONTROL_FOCUS_RING_WIDTH = 2;
 const CONTROL_FOCUS_RING_OFFSET = 1;
 const FIELD_TEXT_LINE_HEIGHT_RATIO = 1.4;
 
-/** A Unistyles breakpoint value: one number in the compact layout, another from `md` up. */
-// A mapped type, not an interface: Unistyles checks breakpoint objects against an index
-// signature, which interfaces never satisfy.
-export type LayoutValue = Record<"xs" | "md", number>;
-
-function byLayout(compact: number, wide: number): LayoutValue {
-  return { xs: compact, md: wide };
-}
-
-function mapLayout(value: LayoutValue, map: (height: number) => number): LayoutValue {
-  return byLayout(map(value.xs), map(value.md));
-}
-
 /**
  * The height of every button, field, and segmented control of a size. Exported so a row that
  * hosts one of those controls can size itself from the same numbers instead of guessing a
- * height the control then outgrows. `md` depends on the layout, so it only works inside a
- * Unistyles stylesheet.
+ * height the control then outgrows. Breakpoint values, so they only work inside a Unistyles
+ * stylesheet.
  */
 export const CONTROL_HEIGHTS = {
-  sm: SMALL_CONTROL_HEIGHT,
-  md: byLayout(DEFAULT_CONTROL_HEIGHT_COMPACT_LAYOUT, DEFAULT_CONTROL_HEIGHT_WIDE_LAYOUT),
-} satisfies Record<ControlSize, number | LayoutValue>;
+  sm: bySizing(CONTROL_SIZES.sm),
+  md: bySizing(CONTROL_SIZES.md),
+} satisfies Record<ControlSize, LayoutValue>;
+
+/** A framed control in a header row, such as a split button. Touch-sized it is an `sm` control. */
+export const HEADER_CONTROL_HEIGHT = bySizing({
+  touch: CONTROL_SIZES.sm.touch,
+  pointer: POINTER_HEADER_CONTROL_HEIGHT,
+});
+
+/**
+ * Square icon-only buttons. Touch-sized, every icon button is one touch target; pointer-sized,
+ * header buttons are larger than toolbar buttons.
+ */
+export const ICON_BUTTON_SIZES = {
+  large: { touch: TOUCH_TARGET, pointer: POINTER_HEADER_CONTROL_HEIGHT },
+  small: { touch: TOUCH_TARGET, pointer: 20 },
+} satisfies Record<"large" | "small", SizingValue>;
+
+/**
+ * A control in a dense toolbar row, such as the composer's: an icon-only square or a labelled
+ * pill. Touch-sized it is one touch target.
+ */
+export const TOOLBAR_CONTROL_SIZES = { touch: TOUCH_TARGET, pointer: 28 } satisfies SizingValue;
+export const TOOLBAR_CONTROL_HEIGHT = bySizing(TOOLBAR_CONTROL_SIZES);
+
+/**
+ * Glyph sizes. Pointer glyphs sit beside 13-14pt text; touch glyphs sit beside iOS's 17pt body
+ * text, so each step is larger.
+ */
+export type IconSize = keyof typeof ICON_SIZE;
+export const TOUCH_ICON_SIZE: Record<IconSize, number> = { xs: 14, sm: 18, md: 20, lg: 24 };
+
+export function iconSizeFor(size: IconSize): SizingValue {
+  return { touch: TOUCH_ICON_SIZE[size], pointer: ICON_SIZE[size] };
+}
 
 /** The height of a control of `size`, for code that has to compute with it outside a stylesheet. */
 export function controlHeightForLayout(size: ControlSize, isCompact: boolean): number {
-  const height = CONTROL_HEIGHTS[size];
-  if (typeof height === "number") return height;
-  return isCompact ? height.xs : height.md;
+  return CONTROL_SIZES[size][controlSizingForLayout(isCompact)];
 }
 
 export const controlIconSize: Record<ControlSize, number> = {
@@ -96,7 +137,8 @@ const SWITCH_TOUCH = switchSize(44, 26, 22);
  * animation, so the size is resolved to plain numbers here instead of a stylesheet breakpoint.
  */
 export function switchGeometryForLayout(size: ControlSize, isCompact: boolean): SwitchGeometry {
-  const track = size === "md" && isCompact ? SWITCH_TOUCH : SWITCH_POINTER;
+  const touchSized = controlSizingForLayout(isCompact) === "touch";
+  const track = size === "md" && touchSized ? SWITCH_TOUCH : SWITCH_POINTER;
   return { ...track, reservedHeight: controlHeightForLayout(size, isCompact) };
 }
 
@@ -225,10 +267,8 @@ export function createControlGeometry(theme: Theme) {
   const fieldControlSm = {
     minHeight: CONTROL_HEIGHTS.sm,
     paddingHorizontal: theme.spacing[2],
-    paddingVertical: fieldVerticalPadding(
-      CONTROL_HEIGHTS.sm,
-      fieldTextSmLineHeight,
-      controlBorderWidth,
+    paddingVertical: mapLayout(CONTROL_HEIGHTS.sm, (height) =>
+      fieldVerticalPadding(height, fieldTextSmLineHeight, controlBorderWidth),
     ),
     borderRadius: theme.borderRadius.md,
   };
@@ -258,7 +298,7 @@ export function createControlGeometry(theme: Theme) {
     },
     buttonMd: {
       minHeight: CONTROL_HEIGHTS.md,
-      paddingHorizontal: byLayout(theme.spacing[6], theme.spacing[4]),
+      paddingHorizontal: bySizing({ touch: theme.spacing[6], pointer: theme.spacing[4] }),
       borderRadius: theme.borderRadius.full,
     },
     // A button with only an icon is a circle of its size's height.
@@ -314,7 +354,7 @@ export function createControlGeometry(theme: Theme) {
       padding: 0,
     },
     segmentedSegmentSm: {
-      minHeight: CONTROL_HEIGHTS.sm - SEGMENTED_INSET * 2,
+      minHeight: mapLayout(CONTROL_HEIGHTS.sm, (height) => height - SEGMENTED_INSET * 2),
       paddingHorizontal: theme.spacing[2],
       borderRadius: theme.borderRadius.full,
     },
diff --git a/packages/app/src/components/ui/control-sizing.ts b/packages/app/src/components/ui/control-sizing.ts
new file mode 100644
index 0000000000..d64fc3f000
--- /dev/null
+++ b/packages/app/src/components/ui/control-sizing.ts
@@ -0,0 +1,68 @@
+import { hasTouchScreen } from "@/hooks/use-fine-pointer";
+
+// The sizing gate, apart from the control sizes so that low-level modules such as
+// `constants/layout` can size by it without loading the theme. Import it through
+// `@/components/ui/control-geometry`, which re-exports it.
+
+/**
+ * Every size comes in a touch value and a pointer value. Touch values follow Apple's Human
+ * Interface Guidelines for iOS and iPadOS: a 44pt default control and hit region, nothing
+ * smaller than its 28pt minimum. Pointer values sit one step down the same button ladder.
+ */
+export type ControlSizing = "touch" | "pointer";
+
+export interface ControlSizingFacts {
+  /** The layout is below the `md` breakpoint. */
+  compactLayout: boolean;
+  /** The device has a touch screen; see `hasTouchScreen`. */
+  touchScreen: boolean;
+}
+
+/**
+ * The one sizing gate: touch-sized in the compact layout or on any device with a touch screen,
+ * pointer-sized otherwise. A touch screen keeps touch sizing when a mouse or keyboard is attached.
+ */
+export function resolveControlSizing({
+  compactLayout,
+  touchScreen,
+}: ControlSizingFacts): ControlSizing {
+  if (compactLayout || touchScreen) return "touch";
+  return "pointer";
+}
+
+// Read once, so attaching a mouse or keyboard later never flips the sizing.
+const DEVICE_HAS_TOUCH_SCREEN = hasTouchScreen();
+
+/** The sizing on this device for a layout, for code that sizes outside a stylesheet. */
+export function controlSizingForLayout(compactLayout: boolean): ControlSizing {
+  return resolveControlSizing({ compactLayout, touchScreen: DEVICE_HAS_TOUCH_SCREEN });
+}
+
+/** A Unistyles breakpoint value: one number in the compact layout, another from `md` up. */
+// A mapped type, not an interface: Unistyles checks breakpoint objects against an index
+// signature, which interfaces never satisfy.
+export type LayoutValue = Record<"xs" | "md", number>;
+
+export type SizingValue = Record<ControlSizing, number>;
+
+/**
+ * A size as a Unistyles breakpoint value. The compact layout always takes the touch value; from
+ * `md` up the device decides.
+ */
+export function bySizing(
+  sizes: SizingValue,
+  touchScreen: boolean = DEVICE_HAS_TOUCH_SCREEN,
+): LayoutValue {
+  return {
+    xs: sizes[resolveControlSizing({ compactLayout: true, touchScreen })],
+    md: sizes[resolveControlSizing({ compactLayout: false, touchScreen })],
+  };
+}
+
+/** Derives a breakpoint value from another, such as a row as tall as its control plus padding. */
+export function mapLayout(value: LayoutValue, map: (height: number) => number): LayoutValue {
+  return { xs: map(value.xs), md: map(value.md) };
+}
+
+/** The smallest touch target, and the size of every touch-sized icon button, row, and bar. */
+export const TOUCH_TARGET = 44;
diff --git a/packages/app/src/components/ui/icon-button-chrome.ts b/packages/app/src/components/ui/icon-button-chrome.ts
index 75735ac986..42ba47a80a 100644
--- a/packages/app/src/components/ui/icon-button-chrome.ts
+++ b/packages/app/src/components/ui/icon-button-chrome.ts
@@ -1,17 +1,24 @@
 import { createContext, useCallback, useContext } from "react";
 import type { StyleProp, ViewStyle } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
-import { HEADER_CONTROL_HEIGHT } from "@/components/ui/control-geometry";
+import {
+  bySizing,
+  controlSizingForLayout,
+  ICON_BUTTON_SIZES,
+  TOUCH_ICON_SIZE,
+  type SizingValue,
+} from "@/components/ui/control-geometry";
 import { ICON_SIZE } from "@/styles/theme";
 
 export { extraMutedIconColorMapping, mutedIconColorMapping } from "@/components/ui/icon-color";
 
 export type IconButtonChromeSize = "large" | "small";
 
-const SMALL_ICON_BUTTON_SIZE = 20;
-/** Width and height of a large icon button on compact layouts. */
-export const COMPACT_LARGE_ICON_BUTTON_SIZE = 32;
-const COMPACT_SMALL_ICON_BUTTON_SIZE = 32;
+// Touch-sized, every icon button is one target with one glyph size.
+const GLYPH_SIZES = {
+  large: { touch: TOUCH_ICON_SIZE.md, pointer: ICON_SIZE.md },
+  small: { touch: TOUCH_ICON_SIZE.md, pointer: ICON_SIZE.sm },
+} satisfies Record<IconButtonChromeSize, SizingValue>;
 
 export interface IconButtonChromeState {
   hovered?: boolean;
@@ -22,7 +29,7 @@ export interface IconButtonChromeState {
 
 function resolveIconButtonFrame(size: IconButtonChromeSize, compact: boolean) {
   if (size === "large") return styles.large;
-  return compact ? styles.smallCompact : styles.small;
+  return controlSizingForLayout(compact) === "touch" ? styles.smallTouch : styles.small;
 }
 
 interface IconButtonChromeOptions {
@@ -92,24 +99,17 @@ export function iconButtonChromeFrameStyle(
 }
 
 export function iconButtonChromeGlyphSize(size: IconButtonChromeSize, compact = false): number {
-  if (size === "large") return ICON_SIZE.md;
-  return compact ? 18 : 14;
+  return GLYPH_SIZES[size][controlSizingForLayout(compact)];
 }
 
 export function smallIconButtonChromeFrameSize(compact = false): number {
-  return compact ? COMPACT_SMALL_ICON_BUTTON_SIZE : SMALL_ICON_BUTTON_SIZE;
+  return ICON_BUTTON_SIZES.small[controlSizingForLayout(compact)];
 }
 
 const styles = StyleSheet.create((theme) => ({
   large: {
-    width: {
-      xs: COMPACT_LARGE_ICON_BUTTON_SIZE,
-      md: HEADER_CONTROL_HEIGHT,
-    },
-    height: {
-      xs: COMPACT_LARGE_ICON_BUTTON_SIZE,
-      md: HEADER_CONTROL_HEIGHT,
-    },
+    width: bySizing(ICON_BUTTON_SIZES.large),
+    height: bySizing(ICON_BUTTON_SIZES.large),
     padding: 0,
     borderRadius: theme.borderRadius.md,
     alignItems: "center",
@@ -119,8 +119,8 @@ const styles = StyleSheet.create((theme) => ({
     outlineColor: "transparent",
   },
   small: {
-    width: SMALL_ICON_BUTTON_SIZE,
-    height: SMALL_ICON_BUTTON_SIZE,
+    width: ICON_BUTTON_SIZES.small.pointer,
+    height: ICON_BUTTON_SIZES.small.pointer,
     padding: 0,
     borderRadius: theme.borderRadius.md,
     alignItems: "center",
@@ -129,9 +129,9 @@ const styles = StyleSheet.create((theme) => ({
     outlineWidth: 0,
     outlineColor: "transparent",
   },
-  smallCompact: {
-    width: COMPACT_SMALL_ICON_BUTTON_SIZE,
-    height: COMPACT_SMALL_ICON_BUTTON_SIZE,
+  smallTouch: {
+    width: ICON_BUTTON_SIZES.small.touch,
+    height: ICON_BUTTON_SIZES.small.touch,
     padding: 0,
     borderRadius: theme.borderRadius.md,
     alignItems: "center",
diff --git a/packages/app/src/components/ui/menu/menu-geometry.ts b/packages/app/src/components/ui/menu/menu-geometry.ts
index 089f4afa67..b0b53e697e 100644
--- a/packages/app/src/components/ui/menu/menu-geometry.ts
+++ b/packages/app/src/components/ui/menu/menu-geometry.ts
@@ -1,2 +1,5 @@
 /** Shared geometry for menu rows and controls that align with them. */
-export const MENU_ITEM_HEIGHT = { xs: 40, md: 28 } as const;
+import { density } from "@/styles/density";
+
+/** A menu row is a tight row: touch-sized wherever controls are (see `resolveControlSizing`). */
+export const MENU_ITEM_HEIGHT = density.tightRowHeight;
diff --git a/packages/app/src/composer/agent-controls/control.tsx b/packages/app/src/composer/agent-controls/control.tsx
index 64b8b39100..a858c64f71 100644
--- a/packages/app/src/composer/agent-controls/control.tsx
+++ b/packages/app/src/composer/agent-controls/control.tsx
@@ -2,6 +2,7 @@ import { forwardRef, useCallback, type ComponentProps } from "react";
 import { Text, View, type PressableStateCallbackType } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
 import { ComboboxTrigger } from "@/components/ui/combobox-trigger";
+import { TOOLBAR_CONTROL_HEIGHT } from "@/components/ui/control-geometry";
 import { useComposerControlLayout } from "@/composer/agent-controls/layout-context";
 import { ComposerToolbarGlyph } from "@/composer/agent-controls/glyph";
 import type { AgentControlIcon } from "@/agent-controls/icons";
@@ -96,7 +97,7 @@ export const AgentControlTrigger = forwardRef<View, AgentControlTriggerProps>(
 
 const styles = StyleSheet.create((theme) => ({
   toolbarControl: {
-    height: 28,
+    height: TOOLBAR_CONTROL_HEIGHT,
     minWidth: 0,
     flexShrink: 1,
     flexDirection: "row",
@@ -107,7 +108,7 @@ const styles = StyleSheet.create((theme) => ({
     backgroundColor: "transparent",
   },
   toolbarIconOnly: {
-    width: 28,
+    width: TOOLBAR_CONTROL_HEIGHT,
     flexShrink: 0,
     paddingHorizontal: 0,
     justifyContent: "center",
diff --git a/packages/app/src/composer/agent-controls/glyph.tsx b/packages/app/src/composer/agent-controls/glyph.tsx
index 73b2a220c1..f7d68d38c0 100644
--- a/packages/app/src/composer/agent-controls/glyph.tsx
+++ b/packages/app/src/composer/agent-controls/glyph.tsx
@@ -4,7 +4,7 @@ import { StyleSheet, View } from "react-native";
 export function ComposerToolbarGlyph({ children, size }: { children: ReactNode; size: number }) {
   return (
     <View
-      style={size >= 20 ? styles.native : styles.web}
+      style={size >= 20 ? styles.touch : styles.pointer}
       accessibilityElementsHidden
       importantForAccessibility="no-hide-descendants"
       pointerEvents="none"
@@ -15,14 +15,14 @@ export function ComposerToolbarGlyph({ children, size }: { children: ReactNode;
 }
 
 const styles = StyleSheet.create({
-  web: {
+  pointer: {
     width: 16,
     height: 16,
     flexShrink: 0,
     alignItems: "center",
     justifyContent: "center",
   },
-  native: {
+  touch: {
     width: 20,
     height: 20,
     flexShrink: 0,
diff --git a/packages/app/src/composer/agent-controls/index.tsx b/packages/app/src/composer/agent-controls/index.tsx
index 72795289cf..63111538e3 100644
--- a/packages/app/src/composer/agent-controls/index.tsx
+++ b/packages/app/src/composer/agent-controls/index.tsx
@@ -61,6 +61,8 @@ import {
   resolveAgentModelSelection,
 } from "@/composer/agent-controls/utils";
 import { useIsCompactFormFactor } from "@/constants/layout";
+import { controlSizingForLayout, TOOLBAR_CONTROL_HEIGHT } from "@/components/ui/control-geometry";
+import { DensityIcon } from "@/components/ui/density-icon";
 import { readMeasuredWidth } from "@/hooks/use-container-width";
 import { useToast } from "@/contexts/toast-context";
 import { toErrorMessage } from "@/utils/error-messages";
@@ -70,11 +72,10 @@ import {
   type AgentControlCommandCenterSource,
 } from "@/command-center/agent-control-registration";
 import { useComposerKeyboardScope } from "@/composer/keyboard-scope";
-import { isNative } from "@/constants/platform";
 import {
+  composerToolbarGeometry,
   resolveComposerControlDensity,
   resolveComposerControlPresentation,
-  resolveComposerToolbarGlyphSize,
   type ComposerControlDensity,
   type ComposerControlPresentation,
 } from "@/composer/agent-controls/layout";
@@ -460,6 +461,10 @@ function buildAgentProviderModels(
   return map;
 }
 
+function densityFolds(density: ComposerControlDensity): boolean {
+  return resolveComposerControlPresentation(density).foldControls;
+}
+
 function buildOpenChangeHandler(
   selector: AgentControlSelector,
   setOpenSelector: (next: AgentControlSelector | null) => void,
@@ -503,14 +508,20 @@ function ControlledAgentControls({
   modelSelectorServerId = null,
   isCompactLayout,
 }: ControlledAgentControlsProps) {
-  const { theme } = useUnistyles();
   const { t } = useTranslation();
   const isCompactFormFactor = useIsCompactFormFactor();
   const isCompact = isCompactLayout ?? isCompactFormFactor;
+  // Control sizes follow the window layout, as the toolbar's stylesheet does. A narrow pane in a
+  // wide window (`isCompactLayout`) changes which labels show, never how large a control is.
+  const toolbarSizing = controlSizingForLayout(isCompactFormFactor);
+  const toolbarGeometry = useMemo(() => composerToolbarGeometry(toolbarSizing), [toolbarSizing]);
   const { fontScale } = useWindowDimensions();
   const [activeSheet, setActiveSheet] = useState<ActiveSheet>(null);
   const [openSelector, setOpenSelector] = useState<AgentControlSelector | null>(null);
-  const initialDensity: ComposerControlDensity = isCompact ? "tight" : "full";
+  // A compact composer always folds its controls into the model sheet; the width budget only
+  // decides whether the model keeps its label.
+  const minimumDensity: ComposerControlDensity = isCompact ? "compact" : "full";
+  const initialDensity = minimumDensity;
   const [density, setDensity] = useState<ComposerControlDensity>(initialDensity);
   const densityRef = useRef<ComposerControlDensity>(initialDensity);
   const availableWidthRef = useRef(0);
@@ -574,10 +585,10 @@ function ControlledAgentControls({
   const presentation = useMemo(() => resolveComposerControlPresentation(density), [density]);
   const layoutContextValue = useMemo(
     () => ({
-      glyphSize: resolveComposerToolbarGlyphSize(isNative ? "native" : "web"),
+      glyphSize: toolbarGeometry.glyphSize,
       presentation,
     }),
-    [presentation],
+    [presentation, toolbarGeometry],
   );
 
   const updateDensityForWidth = useCallback(
@@ -586,12 +597,20 @@ function ControlledAgentControls({
         availableWidth,
         currentDensity: densityRef.current,
         controls: controlPresence,
+        geometry: toolbarGeometry,
+        minimumDensity,
       });
       if (nextDensity === densityRef.current) return;
+      // Folding swaps the toolbar controls for the model sheet and back, so whatever menu or
+      // sheet was open belonged to controls that are gone.
+      if (densityFolds(nextDensity) !== densityFolds(densityRef.current)) {
+        setOpenSelector(null);
+        setActiveSheet(null);
+      }
       densityRef.current = nextDensity;
       setDensity(nextDensity);
     },
-    [controlPresence],
+    [controlPresence, minimumDensity, toolbarGeometry],
   );
 
   const handleLayout = useCallback(
@@ -633,10 +652,9 @@ function ControlledAgentControls({
         selected={args.selected}
         active={args.active}
         onPress={args.onPress}
-        iconColor={theme.colors.foreground}
       />
     ),
-    [theme.colors.foreground],
+    [],
   );
 
   const handleOpenChange = useCallback(
@@ -702,8 +720,8 @@ function ControlledAgentControls({
 
   const handleCloseSheet = useCallback(() => {
     setActiveSheet(null);
-    if (!isCompact) onDropdownClose?.();
-  }, [isCompact, onDropdownClose]);
+    if (!presentation.foldControls) onDropdownClose?.();
+  }, [onDropdownClose, presentation.foldControls]);
 
   const handleSelectThinkingAndClose = useCallback(
     (thinkingOptionId: string) => {
@@ -734,7 +752,7 @@ function ControlledAgentControls({
   return (
     <ComposerControlLayoutProvider value={layoutContextValue}>
       <View style={styles.container} onLayout={handleLayout}>
-        {!isCompact ? (
+        {!presentation.foldControls ? (
           <DesktopAgentControlsContent
             provider={provider}
             providerOptions={providerOptions}
@@ -821,6 +839,7 @@ function ControlledAgentControls({
             renderThinkingOption={renderThinkingOption}
             modeControl={modeControl}
             glyphSize={layoutContextValue.glyphSize}
+            showLabels={presentation.showModelLabel}
             modelSelectorServerId={modelSelectorServerId}
             canSwitchProvider={Boolean(onSelectProviderAndModel)}
           />
@@ -1144,6 +1163,7 @@ interface SheetAgentControlsContentProps {
   }) => ReactElement;
   modeControl?: AgentModeControlValue | null;
   glyphSize: number;
+  showLabels: boolean;
   modelSelectorServerId: string | null;
   canSwitchProvider: boolean;
 }
@@ -1183,6 +1203,7 @@ function SheetAgentControlsContent(props: SheetAgentControlsContentProps) {
     renderThinkingOption,
     modeControl,
     glyphSize,
+    showLabels,
     modelSelectorServerId,
     canSwitchProvider,
   } = props;
@@ -1271,6 +1292,7 @@ function SheetAgentControlsContent(props: SheetAgentControlsContentProps) {
       isRetryingProvider={isRetryingModelProvider}
       serverId={modelSelectorServerId}
       glyphSize={glyphSize}
+      showLabels={showLabels}
       canSwitchProvider={canSwitchProvider}
     >
       {sheetControls}
@@ -1529,15 +1551,16 @@ function ThinkingComboboxOption({
   selected,
   active,
   onPress,
-  iconColor,
 }: {
   option: ComboboxOption;
   selected: boolean;
   active: boolean;
   onPress: () => void;
-  iconColor: string;
 }) {
-  const leadingSlot = useMemo(() => <ThinkingIcon size={16} color={iconColor} />, [iconColor]);
+  const leadingSlot = useMemo(
+    () => <DensityIcon icon={ThinkingIcon} size="md" color="foreground" />,
+    [],
+  );
   return (
     <ComboboxItem
       label={option.label}
@@ -1953,7 +1976,7 @@ const styles = StyleSheet.create((theme) => ({
     overflow: "hidden",
   },
   modeBadge: {
-    height: 28,
+    height: TOOLBAR_CONTROL_HEIGHT,
     flexDirection: "row",
     alignItems: "center",
     backgroundColor: "transparent",
@@ -1971,8 +1994,8 @@ const styles = StyleSheet.create((theme) => ({
     flexShrink: 0,
   },
   modeIconBadge: {
-    width: 28,
-    height: 28,
+    width: TOOLBAR_CONTROL_HEIGHT,
+    height: TOOLBAR_CONTROL_HEIGHT,
     alignItems: "center",
     justifyContent: "center",
     paddingHorizontal: 0,
diff --git a/packages/app/src/composer/agent-controls/layout-context.tsx b/packages/app/src/composer/agent-controls/layout-context.tsx
index edf8fec7aa..75b4abac80 100644
--- a/packages/app/src/composer/agent-controls/layout-context.tsx
+++ b/packages/app/src/composer/agent-controls/layout-context.tsx
@@ -1,5 +1,8 @@
 import { createContext, useContext, type ReactNode } from "react";
-import type { ComposerControlPresentation } from "@/composer/agent-controls/layout";
+import {
+  resolveComposerControlPresentation,
+  type ComposerControlPresentation,
+} from "@/composer/agent-controls/layout";
 
 interface ComposerControlLayoutValue {
   glyphSize: number;
@@ -8,12 +11,7 @@ interface ComposerControlLayoutValue {
 
 const DEFAULT_LAYOUT: ComposerControlLayoutValue = {
   glyphSize: 16,
-  presentation: {
-    showCarets: true,
-    showThinkingLabel: true,
-    showModeLabel: true,
-    aggregateFeatures: false,
-  },
+  presentation: resolveComposerControlPresentation("full"),
 };
 
 const ComposerControlLayoutContext = createContext(DEFAULT_LAYOUT);
diff --git a/packages/app/src/composer/agent-controls/layout.test.ts b/packages/app/src/composer/agent-controls/layout.test.ts
index 2e52972b1c..2135068bdc 100644
--- a/packages/app/src/composer/agent-controls/layout.test.ts
+++ b/packages/app/src/composer/agent-controls/layout.test.ts
@@ -1,30 +1,42 @@
 import { describe, expect, it } from "vitest";
 import {
-  COMPOSER_TOOLBAR_GEOMETRY,
+  composerToolbarGeometry,
   resolveComposerControlDensity,
   resolveComposerControlPresentation,
-  resolveComposerToolbarGlyphSize,
 } from "./layout";
 
+const POINTER = composerToolbarGeometry("pointer");
+const TOUCH = composerToolbarGeometry("touch");
+
 describe("composer control layout", () => {
-  it("removes labels in priority order as the toolbar narrows", () => {
+  it("removes labels, then folds controls, then drops the model label as the toolbar narrows", () => {
     expect(resolveComposerControlPresentation("full")).toEqual({
       showCarets: true,
       showThinkingLabel: true,
       showModeLabel: true,
       aggregateFeatures: false,
+      foldControls: false,
+      showModelLabel: true,
     });
-    expect(resolveComposerControlPresentation("condensed")).toEqual({
+    expect(resolveComposerControlPresentation("condensed")).toMatchObject({
       showCarets: false,
       showThinkingLabel: false,
       showModeLabel: true,
       aggregateFeatures: true,
+      foldControls: false,
     });
-    expect(resolveComposerControlPresentation("tight")).toEqual({
-      showCarets: false,
-      showThinkingLabel: false,
+    expect(resolveComposerControlPresentation("tight")).toMatchObject({
       showModeLabel: false,
-      aggregateFeatures: true,
+      foldControls: false,
+      showModelLabel: true,
+    });
+    expect(resolveComposerControlPresentation("compact")).toMatchObject({
+      foldControls: true,
+      showModelLabel: true,
+    });
+    expect(resolveComposerControlPresentation("iconOnly")).toMatchObject({
+      foldControls: true,
+      showModelLabel: false,
     });
   });
 
@@ -41,6 +53,7 @@ describe("composer control layout", () => {
       resolveComposerControlDensity({
         availableWidth: 420,
         currentDensity: "full",
+        geometry: POINTER,
         controls,
       }),
     ).toBe("full");
@@ -48,6 +61,7 @@ describe("composer control layout", () => {
       resolveComposerControlDensity({
         availableWidth: 380,
         currentDensity: "full",
+        geometry: POINTER,
         controls,
       }),
     ).toBe("condensed");
@@ -55,6 +69,7 @@ describe("composer control layout", () => {
       resolveComposerControlDensity({
         availableWidth: 290,
         currentDensity: "condensed",
+        geometry: POINTER,
         controls,
       }),
     ).toBe("condensed");
@@ -62,6 +77,7 @@ describe("composer control layout", () => {
       resolveComposerControlDensity({
         availableWidth: 280,
         currentDensity: "condensed",
+        geometry: POINTER,
         controls,
       }),
     ).toBe("tight");
@@ -69,6 +85,7 @@ describe("composer control layout", () => {
       resolveComposerControlDensity({
         availableWidth: 300,
         currentDensity: "tight",
+        geometry: POINTER,
         controls,
       }),
     ).toBe("tight");
@@ -76,6 +93,7 @@ describe("composer control layout", () => {
       resolveComposerControlDensity({
         availableWidth: 312,
         currentDensity: "tight",
+        geometry: POINTER,
         controls,
       }),
     ).toBe("condensed");
@@ -85,6 +103,7 @@ describe("composer control layout", () => {
     const base = {
       availableWidth: 430,
       currentDensity: "condensed" as const,
+      geometry: POINTER,
     };
 
     expect(
@@ -129,6 +148,7 @@ describe("composer control layout", () => {
     const base = {
       availableWidth: 430,
       currentDensity: "full" as const,
+      geometry: POINTER,
       controls: {
         hasModel: true,
         hasThinking: true,
@@ -154,15 +174,97 @@ describe("composer control layout", () => {
     ).toBe("condensed");
   });
 
-  it("gives every toolbar control one shell and one platform glyph envelope", () => {
-    expect(COMPOSER_TOOLBAR_GEOMETRY).toEqual({
+  it("gives every toolbar control one shell and one glyph per control sizing", () => {
+    expect(POINTER).toEqual({
       controlSize: 28,
+      glyphSize: 16,
       controlGap: 4,
       iconLabelGap: 4,
       labelPadding: 8,
       caretSize: 14,
     });
-    expect(resolveComposerToolbarGlyphSize("web")).toBe(16);
-    expect(resolveComposerToolbarGlyphSize("native")).toBe(20);
+    expect(TOUCH).toMatchObject({ controlSize: 44, glyphSize: 20 });
+  });
+
+  it("budgets touch-sized controls, so a touch toolbar condenses at a width a pointer one fits", () => {
+    const input = {
+      availableWidth: 420,
+      currentDensity: "full" as const,
+      controls: {
+        hasModel: true,
+        hasThinking: true,
+        hasMode: true,
+        features: [{ type: "toggle" as const }],
+        fontScale: 1,
+      },
+    };
+
+    expect(resolveComposerControlDensity({ ...input, geometry: POINTER })).toBe("full");
+    expect(resolveComposerControlDensity({ ...input, geometry: TOUCH })).toBe("condensed");
+  });
+
+  describe("touch toolbar on an iPad in portrait, sidebar docked", () => {
+    // Codex: model, thinking, mode and two toggle features. The measured toolbar is 272 wide
+    // with an empty draft and 224 once an attachment brings in the send button.
+    const controls = {
+      hasModel: true,
+      hasThinking: true,
+      hasMode: true,
+      features: [{ type: "toggle" as const }, { type: "toggle" as const }],
+      fontScale: 1,
+    };
+
+    it("keeps the model family label with icon-only controls on an empty draft", () => {
+      expect(
+        resolveComposerControlDensity({
+          availableWidth: 272,
+          currentDensity: "full",
+          geometry: TOUCH,
+          controls,
+        }),
+      ).toBe("tight");
+    });
+
+    it("folds thinking, mode and features into the model control once an attachment narrows it", () => {
+      expect(
+        resolveComposerControlDensity({
+          availableWidth: 224,
+          currentDensity: "tight",
+          geometry: TOUCH,
+          controls,
+        }),
+      ).toBe("compact");
+    });
+
+    it("drops the model label only after the controls are folded", () => {
+      expect(
+        resolveComposerControlDensity({
+          availableWidth: 120,
+          currentDensity: "compact",
+          geometry: TOUCH,
+          controls,
+        }),
+      ).toBe("iconOnly");
+    });
+  });
+
+  it("starts a compact composer at the folded toolbar however wide it is", () => {
+    const input = {
+      currentDensity: "compact" as const,
+      geometry: TOUCH,
+      minimumDensity: "compact" as const,
+      controls: {
+        hasModel: true,
+        hasThinking: true,
+        hasMode: true,
+        features: [],
+        fontScale: 1,
+      },
+    };
+
+    expect(resolveComposerControlDensity({ ...input, availableWidth: 600 })).toBe("compact");
+    // The iPhone toolbar with an attachment: "GPT-6…" beside "Medium" still fits.
+    expect(resolveComposerControlDensity({ ...input, availableWidth: 159 })).toBe("compact");
+    expect(resolveComposerControlDensity({ ...input, availableWidth: 120 })).toBe("iconOnly");
   });
 });
diff --git a/packages/app/src/composer/agent-controls/layout.ts b/packages/app/src/composer/agent-controls/layout.ts
index 6f7c78cc73..f14950231c 100644
--- a/packages/app/src/composer/agent-controls/layout.ts
+++ b/packages/app/src/composer/agent-controls/layout.ts
@@ -1,4 +1,23 @@
-export type ComposerControlDensity = "full" | "condensed" | "tight";
+import {
+  iconSizeFor,
+  TOOLBAR_CONTROL_SIZES,
+  type ControlSizing,
+} from "@/components/ui/control-geometry";
+
+/**
+ * How much of the toolbar shows, widest first. Each step drops something before the next:
+ * carets and labels, then the mode label, then the thinking, mode and feature controls fold into
+ * the model control's sheet (`compact`, the phone toolbar), then the model's own label.
+ */
+export type ComposerControlDensity = "full" | "condensed" | "tight" | "compact" | "iconOnly";
+
+const DENSITY_LADDER: readonly ComposerControlDensity[] = [
+  "full",
+  "condensed",
+  "tight",
+  "compact",
+  "iconOnly",
+];
 
 export interface ComposerControlPresence {
   hasModel: boolean;
@@ -15,27 +34,46 @@ export interface ComposerControlPresentation {
   showThinkingLabel: boolean;
   showModeLabel: boolean;
   aggregateFeatures: boolean;
+  /** Thinking, mode and features live in the model control's sheet. */
+  foldControls: boolean;
+  showModelLabel: boolean;
 }
 
-export const COMPOSER_TOOLBAR_GEOMETRY = {
-  controlSize: 28,
-  controlGap: 4,
-  iconLabelGap: 4,
-  labelPadding: 8,
-  caretSize: 14,
-} as const;
+export interface ComposerToolbarGeometry {
+  controlSize: number;
+  glyphSize: number;
+  controlGap: number;
+  iconLabelGap: number;
+  labelPadding: number;
+  caretSize: number;
+}
+
+/** The toolbar's measurements under a control sizing; see `resolveControlSizing`. */
+export function composerToolbarGeometry(sizing: ControlSizing): ComposerToolbarGeometry {
+  return {
+    controlSize: TOOLBAR_CONTROL_SIZES[sizing],
+    glyphSize: iconSizeFor("md")[sizing],
+    controlGap: 4,
+    iconLabelGap: 4,
+    labelPadding: 8,
+    caretSize: 14,
+  };
+}
 
 const DENSITY_HYSTERESIS = 12;
+/** The model label's narrowest useful width: enough for the model family, such as "GPT-6…". */
+const MODEL_FAMILY_LABEL_WIDTH = 56;
+/** A thinking label beside the folded model label, such as "Medium". */
+const THINKING_LABEL_WIDTH = 48;
 
 function normalizedFontScale(fontScale: number): number {
   return Number.isFinite(fontScale) ? Math.max(1, fontScale) : 1;
 }
 
-function sumControlWidths(widths: number[]): number {
+function sumControlWidths(widths: number[], geometry: ComposerToolbarGeometry): number {
   if (widths.length === 0) return 0;
   return (
-    widths.reduce((total, width) => total + width, 0) +
-    (widths.length - 1) * COMPOSER_TOOLBAR_GEOMETRY.controlGap
+    widths.reduce((total, width) => total + width, 0) + (widths.length - 1) * geometry.controlGap
   );
 }
 
@@ -43,92 +81,173 @@ function estimateLabelWidth(label: string, fontScale: number): number {
   return Array.from(label).length * 7 * fontScale;
 }
 
+/** A labelled control's fixed chrome: its padding, its glyph, and the gap to its label. */
+function labelledChrome(geometry: ComposerToolbarGeometry): number {
+  return geometry.labelPadding * 2 + geometry.glyphSize + geometry.iconLabelGap;
+}
+
 function resolveFeatureControlWidth(
   feature: ComposerFeatureControlPresence,
   fontScale: number,
+  geometry: ComposerToolbarGeometry,
 ): number {
-  if (feature.type === "toggle") return COMPOSER_TOOLBAR_GEOMETRY.controlSize;
+  if (feature.type === "toggle") return geometry.controlSize;
   return (
-    COMPOSER_TOOLBAR_GEOMETRY.controlSize +
-    COMPOSER_TOOLBAR_GEOMETRY.iconLabelGap +
-    COMPOSER_TOOLBAR_GEOMETRY.labelPadding * 2 +
+    geometry.controlSize +
+    geometry.iconLabelGap +
+    geometry.labelPadding * 2 +
     estimateLabelWidth(feature.label, fontScale)
   );
 }
 
-function resolveCondensedFloor(controls: ComposerControlPresence): number {
+function resolveCondensedFloor(
+  controls: ComposerControlPresence,
+  geometry: ComposerToolbarGeometry,
+): number {
   const fontScale = normalizedFontScale(controls.fontScale);
+  const chrome = labelledChrome(geometry);
   const widths: number[] = [];
-  if (controls.hasModel) widths.push(36 + 60 * fontScale);
-  if (controls.hasThinking) widths.push(COMPOSER_TOOLBAR_GEOMETRY.controlSize);
-  if (controls.hasMode) widths.push(36 + 96 * fontScale);
-  if (controls.features.length > 0) widths.push(COMPOSER_TOOLBAR_GEOMETRY.controlSize);
-  return sumControlWidths(widths);
+  if (controls.hasModel) widths.push(chrome + 60 * fontScale);
+  if (controls.hasThinking) widths.push(geometry.controlSize);
+  if (controls.hasMode) widths.push(chrome + 96 * fontScale);
+  if (controls.features.length > 0) widths.push(geometry.controlSize);
+  return sumControlWidths(widths, geometry);
 }
 
-function resolveFullFloor(controls: ComposerControlPresence): number {
+function resolveFullFloor(
+  controls: ComposerControlPresence,
+  geometry: ComposerToolbarGeometry,
+): number {
   const fontScale = normalizedFontScale(controls.fontScale);
+  const chrome = labelledChrome(geometry);
+  const caret = geometry.caretSize;
   const widths: number[] = [];
-  if (controls.hasModel) widths.push(50 + 70 * fontScale);
-  if (controls.hasThinking) widths.push(54 + 48 * fontScale);
-  if (controls.hasMode) widths.push(54 + 96 * fontScale);
+  if (controls.hasModel) widths.push(chrome + caret + 70 * fontScale);
+  if (controls.hasThinking) widths.push(chrome + geometry.iconLabelGap + caret + 48 * fontScale);
+  if (controls.hasMode) widths.push(chrome + geometry.iconLabelGap + caret + 96 * fontScale);
   for (const feature of controls.features) {
-    widths.push(resolveFeatureControlWidth(feature, fontScale));
+    widths.push(resolveFeatureControlWidth(feature, fontScale, geometry));
   }
-  return sumControlWidths(widths);
+  return sumControlWidths(widths, geometry);
 }
 
+/** Model at its family label, with thinking, mode and features as icon-only squares. */
+function resolveTightFloor(
+  controls: ComposerControlPresence,
+  geometry: ComposerToolbarGeometry,
+): number {
+  const fontScale = normalizedFontScale(controls.fontScale);
+  const widths: number[] = [];
+  if (controls.hasModel) {
+    widths.push(labelledChrome(geometry) + MODEL_FAMILY_LABEL_WIDTH * fontScale);
+  }
+  if (controls.hasThinking) widths.push(geometry.controlSize);
+  if (controls.hasMode) widths.push(geometry.controlSize);
+  if (controls.features.length > 0) widths.push(geometry.controlSize);
+  return sumControlWidths(widths, geometry);
+}
+
+/** One model control carrying the model family label and the thinking label. */
+function resolveCompactFloor(
+  controls: ComposerControlPresence,
+  geometry: ComposerToolbarGeometry,
+): number {
+  const fontScale = normalizedFontScale(controls.fontScale);
+  const thinkingLabel = controls.hasThinking
+    ? geometry.iconLabelGap + THINKING_LABEL_WIDTH * fontScale
+    : 0;
+  return labelledChrome(geometry) + MODEL_FAMILY_LABEL_WIDTH * fontScale + thinkingLabel;
+}
+
+function resolveDensityFloor(
+  density: ComposerControlDensity,
+  controls: ComposerControlPresence,
+  geometry: ComposerToolbarGeometry,
+): number {
+  switch (density) {
+    case "full":
+      return resolveFullFloor(controls, geometry);
+    case "condensed":
+      return resolveCondensedFloor(controls, geometry);
+    case "tight":
+      return resolveTightFloor(controls, geometry);
+    case "compact":
+      return resolveCompactFloor(controls, geometry);
+    case "iconOnly":
+      return 0;
+  }
+}
+
+/**
+ * The widest density whose floor fits `availableWidth`. Widening past the current density needs
+ * the floor plus the hysteresis and keeping it tolerates the floor minus it, so a width near a
+ * floor does not flip back and forth. `minimumDensity` is the widest density allowed.
+ */
 export function resolveComposerControlDensity(input: {
   availableWidth: number;
   currentDensity: ComposerControlDensity;
   controls: ComposerControlPresence;
+  geometry: ComposerToolbarGeometry;
+  minimumDensity?: ComposerControlDensity;
 }): ComposerControlDensity {
-  const fullFloor = resolveFullFloor(input.controls);
-  const condensedFloor = resolveCondensedFloor(input.controls);
-
-  if (input.currentDensity === "full") {
-    if (input.availableWidth >= fullFloor - DENSITY_HYSTERESIS) return "full";
-    return input.availableWidth >= condensedFloor ? "condensed" : "tight";
+  const current = DENSITY_LADDER.indexOf(input.currentDensity);
+  const first = DENSITY_LADDER.indexOf(input.minimumDensity ?? "full");
+  for (let step = first; step < DENSITY_LADDER.length; step += 1) {
+    const density = DENSITY_LADDER[step];
+    const floor = resolveDensityFloor(density, input.controls, input.geometry);
+    let required = floor;
+    if (step < current) required = floor + DENSITY_HYSTERESIS;
+    if (step === current) required = floor - DENSITY_HYSTERESIS;
+    if (input.availableWidth >= required) return density;
   }
-
-  if (input.currentDensity === "condensed") {
-    if (input.availableWidth >= fullFloor + DENSITY_HYSTERESIS) return "full";
-    if (input.availableWidth < condensedFloor - DENSITY_HYSTERESIS) return "tight";
-    return "condensed";
-  }
-
-  if (input.availableWidth >= fullFloor + DENSITY_HYSTERESIS) return "full";
-  if (input.availableWidth >= condensedFloor + DENSITY_HYSTERESIS) return "condensed";
-  return "tight";
+  return "iconOnly";
 }
 
-export function resolveComposerControlPresentation(
-  density: ComposerControlDensity,
-): ComposerControlPresentation {
-  if (density === "full") {
-    return {
-      showCarets: true,
-      showThinkingLabel: true,
-      showModeLabel: true,
-      aggregateFeatures: false,
-    };
-  }
-  if (density === "condensed") {
-    return {
-      showCarets: false,
-      showThinkingLabel: false,
-      showModeLabel: true,
-      aggregateFeatures: true,
-    };
-  }
-  return {
+const PRESENTATIONS: Record<ComposerControlDensity, ComposerControlPresentation> = {
+  full: {
+    showCarets: true,
+    showThinkingLabel: true,
+    showModeLabel: true,
+    aggregateFeatures: false,
+    foldControls: false,
+    showModelLabel: true,
+  },
+  condensed: {
+    showCarets: false,
+    showThinkingLabel: false,
+    showModeLabel: true,
+    aggregateFeatures: true,
+    foldControls: false,
+    showModelLabel: true,
+  },
+  tight: {
     showCarets: false,
     showThinkingLabel: false,
     showModeLabel: false,
     aggregateFeatures: true,
-  };
-}
+    foldControls: false,
+    showModelLabel: true,
+  },
+  compact: {
+    showCarets: false,
+    showThinkingLabel: true,
+    showModeLabel: false,
+    aggregateFeatures: true,
+    foldControls: true,
+    showModelLabel: true,
+  },
+  iconOnly: {
+    showCarets: false,
+    showThinkingLabel: false,
+    showModeLabel: false,
+    aggregateFeatures: true,
+    foldControls: true,
+    showModelLabel: false,
+  },
+};
 
-export function resolveComposerToolbarGlyphSize(platform: "web" | "native"): number {
-  return platform === "native" ? 20 : 16;
+export function resolveComposerControlPresentation(
+  density: ComposerControlDensity,
+): ComposerControlPresentation {
+  return PRESENTATIONS[density];
 }
diff --git a/packages/app/src/composer/agent-controls/mode-control.tsx b/packages/app/src/composer/agent-controls/mode-control.tsx
index 59fb515ce5..25352d8a9d 100644
--- a/packages/app/src/composer/agent-controls/mode-control.tsx
+++ b/packages/app/src/composer/agent-controls/mode-control.tsx
@@ -27,6 +27,7 @@ import { showProviderNoticeToast } from "@/utils/provider-notice-toast";
 import type { AgentMode } from "@getpaseo/protocol/agent-types";
 import type { AgentProviderDefinition } from "@getpaseo/protocol/provider-manifest";
 import { getAgentModeIcon, getAgentModeOptionIcon } from "@/agent-controls/icons";
+import { DensityIcon } from "@/components/ui/density-icon";
 interface ModeComboboxOptionProps {
   option: ComboboxOption;
   selected: boolean;
@@ -34,7 +35,6 @@ interface ModeComboboxOptionProps {
   onPress: () => void;
   provider: string;
   providerDefinitions: AgentProviderDefinition[];
-  iconColor: string;
 }
 
 function ModeComboboxOption({
@@ -44,12 +44,12 @@ function ModeComboboxOption({
   onPress,
   provider,
   providerDefinitions,
-  iconColor,
 }: ModeComboboxOptionProps) {
   const IconComponent = getAgentModeOptionIcon(provider, option.id, providerDefinitions);
   const leadingSlot = useMemo(
-    () => (IconComponent ? <IconComponent size={16} color={iconColor} /> : null),
-    [IconComponent, iconColor],
+    () =>
+      IconComponent ? <DensityIcon icon={IconComponent} size="md" color="foreground" /> : null,
+    [IconComponent],
   );
   return (
     <ComboboxItem
@@ -171,10 +171,9 @@ export function AgentModeControl({
         onPress={args.onPress}
         provider={provider}
         providerDefinitions={providerDefinitions}
-        iconColor={theme.colors.foreground}
       />
     ),
-    [provider, providerDefinitions, theme.colors.foreground],
+    [provider, providerDefinitions],
   );
 
   const sheetHeader = useMemo<SheetHeader>(
diff --git a/packages/app/src/composer/agent-controls/model-sheet.tsx b/packages/app/src/composer/agent-controls/model-sheet.tsx
index 6929b447ea..2eccda373d 100644
--- a/packages/app/src/composer/agent-controls/model-sheet.tsx
+++ b/packages/app/src/composer/agent-controls/model-sheet.tsx
@@ -15,6 +15,7 @@ import { resolveModelSheetOpening } from "@/composer/agent-controls/model-sheet-
 import type { ProviderSelectorProvider } from "@/provider-selection/provider-selection";
 import { useIsCompactFormFactor } from "@/constants/layout";
 import { isNative, isWeb } from "@/constants/platform";
+import { TOOLBAR_CONTROL_HEIGHT } from "@/components/ui/control-geometry";
 
 const SNAP_POINTS = ["80%", "90%"];
 const MODEL_LIST_TOP_INSET = 4;
@@ -42,6 +43,8 @@ interface CompactModelSheetProps {
   disabled?: boolean;
   serverId?: string | null;
   glyphSize: number;
+  /** False when the toolbar is too narrow for labels: the trigger shows the provider glyph only. */
+  showLabels: boolean;
   canSwitchProvider: boolean;
   children: ReactNode;
 }
@@ -94,6 +97,7 @@ export function CompactModelSheet({
   disabled = false,
   serverId = null,
   glyphSize,
+  showLabels,
   canSwitchProvider,
   children,
 }: CompactModelSheetProps) {
@@ -229,14 +233,16 @@ export function CompactModelSheet({
     open();
   }, [close, isOpen, open]);
 
+  const iconOnly = !showLabels && hasSelectedProvider;
   const triggerStyle = useCallback(
     ({ hovered, pressed }: PressableStateCallbackType) => [
       styles.trigger,
+      iconOnly && styles.triggerIconOnly,
       hovered && styles.triggerHovered,
       (pressed || isOpen) && styles.triggerPressed,
       disabled && styles.triggerDisabled,
     ],
-    [disabled, isOpen],
+    [disabled, iconOnly, isOpen],
   );
   const mobileRootContent = useMemo(
     () => (
@@ -280,16 +286,18 @@ export function CompactModelSheet({
             <ModelIcon size={glyphSize} color={styles.providerIcon.color} />
           </ComposerToolbarGlyph>
         ) : null}
-        <View style={styles.triggerLabels}>
-          <Text style={styles.triggerText} numberOfLines={1}>
-            {shortModelLabel(rootBrowser.triggerLabel)}
-          </Text>
-          {thinkingLabel ? (
-            <Text style={styles.triggerThinking} numberOfLines={1}>
-              {thinkingLabel}
+        {!iconOnly ? (
+          <View style={styles.triggerLabels}>
+            <Text style={styles.triggerText} numberOfLines={1}>
+              {shortModelLabel(rootBrowser.triggerLabel)}
             </Text>
-          ) : null}
-        </View>
+            {thinkingLabel ? (
+              <Text style={styles.triggerThinking} numberOfLines={1}>
+                {thinkingLabel}
+              </Text>
+            ) : null}
+          </View>
+        ) : null}
       </ComboboxTrigger>
 
       <AdaptiveModalSheet
@@ -374,7 +382,7 @@ export function CompactModelSheet({
 
 const styles = StyleSheet.create((theme) => ({
   trigger: {
-    height: 28,
+    height: TOOLBAR_CONTROL_HEIGHT,
     minWidth: 0,
     flexShrink: 1,
     flexDirection: "row",
@@ -384,6 +392,12 @@ const styles = StyleSheet.create((theme) => ({
     borderRadius: theme.borderRadius["2xl"],
     backgroundColor: "transparent",
   },
+  triggerIconOnly: {
+    width: TOOLBAR_CONTROL_HEIGHT,
+    flexShrink: 0,
+    paddingHorizontal: 0,
+    justifyContent: "center",
+  },
   triggerHovered: {
     backgroundColor: theme.colors.surface2,
   },
diff --git a/packages/app/src/composer/index.tsx b/packages/app/src/composer/index.tsx
index d6b4bae63f..af9a56b826 100644
--- a/packages/app/src/composer/index.tsx
+++ b/packages/app/src/composer/index.tsx
@@ -31,6 +31,11 @@ import {
 import { useTranslation } from "react-i18next";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import { useIsCompactFormFactor } from "@/constants/layout";
+import {
+  controlSizingForLayout,
+  iconSizeFor,
+  TOOLBAR_CONTROL_HEIGHT,
+} from "@/components/ui/control-geometry";
 import { usePanelStore } from "@/stores/panel-store";
 import { useHasFinePointer } from "@/hooks/use-fine-pointer";
 import { useShallow } from "zustand/shallow";
@@ -193,10 +198,6 @@ const EMPTY_ATTACHMENT_SCOPE_KEYS: readonly string[] = [];
 function noop() {}
 const noopCallback = () => {};
 
-function resolveComposerButtonIconSize(): number {
-  return isWeb ? ICON_SIZE.md : ICON_SIZE.lg;
-}
-
 function resolveIsComposerLocked(
   submitBehavior: "clear" | "preserve-and-lock",
   isSubmitLoading: boolean,
@@ -1281,7 +1282,6 @@ function ComposerContentImpl({
 }: ComposerContentProps) {
   const mode = resolveComposerInputMode(inputMode);
   const { t } = useTranslation();
-  const buttonIconSize = resolveComposerButtonIconSize();
   const client = useHostRuntimeClient(serverId);
   const isConnected = useHostRuntimeIsConnected(serverId);
   const agentDirectoryStatus = useHostRuntimeAgentDirectoryStatus(serverId);
@@ -1310,6 +1310,7 @@ function ComposerContentImpl({
 
   const isCompactFormFactor = useIsCompactFormFactor();
   const isCompactLayout = resolveCompactLayout(isCompactLayoutOverride, isCompactFormFactor);
+  const buttonIconSize = iconSizeFor("md")[controlSizingForLayout(isCompactFormFactor)];
   const isDesktopWebBreakpoint = resolveIsDesktopWebBreakpoint(isCompactFormFactor);
   const hasFinePointer = useHasFinePointer();
   const isDesktopLayout = resolveIsDesktopWebBreakpoint(isCompactLayout);
@@ -2081,7 +2082,6 @@ function ComposerContentImpl({
     ],
   );
 
-  const contextWindowMeterGlyphSize = isCompactLayout ? ICON_SIZE.md : buttonIconSize;
   const beforeVoiceContent = useMemo(
     () =>
       hasAgent ? (
@@ -2092,7 +2092,7 @@ function ComposerContentImpl({
             maxTokens={agentState.contextWindowMaxTokens}
             usedTokens={agentState.contextWindowUsedTokens}
             totalCostUsd={agentState.totalCostUsd}
-            glyphSize={contextWindowMeterGlyphSize}
+            glyphSize={buttonIconSize}
           />
         </View>
       ) : null,
@@ -2103,7 +2103,7 @@ function ComposerContentImpl({
       agentState.contextWindowMaxTokens,
       agentState.contextWindowUsedTokens,
       agentState.totalCostUsd,
-      contextWindowMeterGlyphSize,
+      buttonIconSize,
     ],
   );
 
@@ -2598,8 +2598,8 @@ const styles = StyleSheet.create((theme: Theme) => ({
     gap: theme.spacing[3],
   },
   cancelButton: {
-    width: 28,
-    height: 28,
+    width: TOOLBAR_CONTROL_HEIGHT,
+    height: TOOLBAR_CONTROL_HEIGHT,
     borderRadius: theme.borderRadius.full,
     backgroundColor: theme.colors.palette.red[600],
     alignItems: "center",
@@ -2612,15 +2612,15 @@ const styles = StyleSheet.create((theme: Theme) => ({
     gap: theme.spacing[1],
   },
   contextWindowMeterSlot: {
-    width: 28,
-    height: 28,
+    width: TOOLBAR_CONTROL_HEIGHT,
+    height: TOOLBAR_CONTROL_HEIGHT,
     flexShrink: 0,
     alignItems: "center",
     justifyContent: "center",
   },
   realtimeVoiceButton: {
-    width: 28,
-    height: 28,
+    width: TOOLBAR_CONTROL_HEIGHT,
+    height: TOOLBAR_CONTROL_HEIGHT,
     borderRadius: theme.borderRadius.full,
     alignItems: "center",
     justifyContent: "center",
diff --git a/packages/app/src/composer/input/input.tsx b/packages/app/src/composer/input/input.tsx
index 618b923024..311e4dedd4 100644
--- a/packages/app/src/composer/input/input.tsx
+++ b/packages/app/src/composer/input/input.tsx
@@ -27,7 +27,12 @@ import {
 } from "react";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import { useTranslation } from "react-i18next";
-import { ICON_SIZE, type Theme } from "@/styles/theme";
+import type { Theme } from "@/styles/theme";
+import {
+  controlSizingForLayout,
+  iconSizeFor,
+  TOOLBAR_CONTROL_HEIGHT,
+} from "@/components/ui/control-geometry";
 import { ArrowUp, Mic, MicOff, CornerDownLeft, Plus, Square } from "lucide-react-native";
 import * as Haptics from "expo-haptics";
 import { useDictation } from "@/hooks/use-dictation";
@@ -1282,7 +1287,8 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
     const isFullscreen = useComposerFullscreen(editingSession);
     const [renderedLines, setRenderedLines] = useState(1);
     const maxInputHeight = resolveMaxInputHeight(windowHeight, isCompact);
-    const buttonIconSize = isWeb ? ICON_SIZE.md : ICON_SIZE.lg;
+    const controlSizing = controlSizingForLayout(isCompact);
+    const buttonIconSize = iconSizeFor("md")[controlSizing];
     const toast = useToast();
     const voice = useVoiceOptional();
     const voiceMuteToggleKeys = useShortcutKeys("voice-mute-toggle");
@@ -2235,6 +2241,7 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
         />
         <ComposerInputPresentation
           fullscreen={isFullscreen}
+          controlSizing={controlSizing}
           sendIconSize={buttonIconSize}
           surface={textSurface}
           toolbar={toolbar}
@@ -2384,21 +2391,21 @@ const styles = StyleSheet.create((theme: Theme) => ({
     gap: theme.spacing[1],
   },
   attachButton: {
-    width: 28,
-    height: 28,
+    width: TOOLBAR_CONTROL_HEIGHT,
+    height: TOOLBAR_CONTROL_HEIGHT,
     borderRadius: theme.borderRadius.full,
     alignItems: "center",
     justifyContent: "center",
   },
   attachButtonAnchor: {
-    width: 28,
-    height: 28,
+    width: TOOLBAR_CONTROL_HEIGHT,
+    height: TOOLBAR_CONTROL_HEIGHT,
     alignItems: "center",
     justifyContent: "center",
   },
   voiceButton: {
-    width: 28,
-    height: 28,
+    width: TOOLBAR_CONTROL_HEIGHT,
+    height: TOOLBAR_CONTROL_HEIGHT,
     borderRadius: theme.borderRadius.full,
     alignItems: "center",
     justifyContent: "center",
@@ -2407,8 +2414,8 @@ const styles = StyleSheet.create((theme: Theme) => ({
     backgroundColor: theme.colors.destructive,
   },
   sendButton: {
-    width: 28,
-    height: 28,
+    width: TOOLBAR_CONTROL_HEIGHT,
+    height: TOOLBAR_CONTROL_HEIGHT,
     borderRadius: theme.borderRadius.full,
     backgroundColor: theme.colors.accent,
     alignItems: "center",
@@ -2417,7 +2424,7 @@ const styles = StyleSheet.create((theme: Theme) => ({
   },
   sendButtonLabeled: {
     width: "auto",
-    minWidth: 28,
+    minWidth: TOOLBAR_CONTROL_HEIGHT,
     paddingHorizontal: theme.spacing[3],
     borderRadius: theme.borderRadius.full,
   },
diff --git a/packages/app/src/composer/input/presentation.tsx b/packages/app/src/composer/input/presentation.tsx
index 23f78c58ee..956dc22597 100644
--- a/packages/app/src/composer/input/presentation.tsx
+++ b/packages/app/src/composer/input/presentation.tsx
@@ -6,14 +6,16 @@ import { Button } from "@/components/ui/button";
 import { ComposerFullscreenBody, ComposerFullscreenFooter } from "@/composer/dock";
 import { useComposerKeyboardScope } from "@/composer/keyboard-scope";
 import { isWeb } from "@/constants/platform";
-import { ICON_SIZE } from "@/styles/theme";
+import {
+  iconSizeFor,
+  TOOLBAR_CONTROL_HEIGHT,
+  TOOLBAR_CONTROL_SIZES,
+  type ControlSizing,
+} from "@/components/ui/control-geometry";
 import { StyleSheet } from "react-native-unistyles";
 import { useComposerFullscreenExit } from "./fullscreen-exit";
 import { resolveGlyphRailOffset } from "./state";
 
-const CONTROL_SIZE = 28;
-const FULLSCREEN_GLYPH_SIZE = ICON_SIZE.md;
-
 function keepEditorFocused(event: import("react-native").PointerEvent) {
   if (isWeb) event.preventDefault();
 }
@@ -27,6 +29,7 @@ function keepEditorFocused(event: import("react-native").PointerEvent) {
  */
 export function ComposerInputPresentation({
   fullscreen,
+  controlSizing,
   sendIconSize,
   surface,
   toolbar,
@@ -42,6 +45,8 @@ export function ComposerInputPresentation({
   overlay,
 }: {
   fullscreen: boolean;
+  /** The sizing the toolbar's stylesheet resolves to; see `resolveControlSizing`. */
+  controlSizing: ControlSizing;
   sendIconSize: number;
   surface: ReactNode;
   toolbar: ReactNode;
@@ -61,18 +66,19 @@ export function ComposerInputPresentation({
   // action (Escape, hardware back) belongs only to the pane the user is in.
   const { isActiveComposer } = useComposerKeyboardScope();
   const exitScopeRef = useComposerFullscreenExit(fullscreen && isActiveComposer, onExit);
+  const glyphSize = iconSizeFor("md")[controlSizing];
   const railOffset = resolveGlyphRailOffset({
-    controlSize: CONTROL_SIZE,
+    controlSize: TOOLBAR_CONTROL_SIZES[controlSizing],
     sendIconSize,
-    glyphIconSize: FULLSCREEN_GLYPH_SIZE,
+    glyphIconSize: glyphSize,
   });
   const maximizeIcon = useCallback(
-    (color: string) => <Maximize2 color={color} size={FULLSCREEN_GLYPH_SIZE} />,
-    [],
+    (color: string) => <Maximize2 color={color} size={glyphSize} />,
+    [glyphSize],
   );
   const minimizeIcon = useCallback(
-    (color: string) => <Minimize2 color={color} size={FULLSCREEN_GLYPH_SIZE} />,
-    [],
+    (color: string) => <Minimize2 color={color} size={glyphSize} />,
+    [glyphSize],
   );
   // The toolbar row bleeds 6px past the input padding; the inline glyph sits on that edge.
   const enterStyle = useMemo(() => [styles.enterButton, { right: -6 + railOffset }], [railOffset]);
@@ -141,8 +147,8 @@ const styles = StyleSheet.create((theme) => ({
   inline: { flexShrink: 1, position: "relative" },
   inlineTextSurface: { flexShrink: 1, position: "relative" },
   iconButton: {
-    width: CONTROL_SIZE,
-    height: CONTROL_SIZE,
+    width: TOOLBAR_CONTROL_HEIGHT,
+    height: TOOLBAR_CONTROL_HEIGHT,
     padding: 0,
     borderWidth: 0,
     borderRadius: theme.borderRadius.full,
@@ -150,8 +156,8 @@ const styles = StyleSheet.create((theme) => ({
   enterButton: {
     position: "absolute",
     top: 0,
-    width: CONTROL_SIZE,
-    height: CONTROL_SIZE,
+    width: TOOLBAR_CONTROL_HEIGHT,
+    height: TOOLBAR_CONTROL_HEIGHT,
     padding: 0,
     borderWidth: 0,
     borderRadius: theme.borderRadius.full,
diff --git a/packages/app/src/composer/tracks.tsx b/packages/app/src/composer/tracks.tsx
index a6c0db1098..71ed312739 100644
--- a/packages/app/src/composer/tracks.tsx
+++ b/packages/app/src/composer/tracks.tsx
@@ -13,6 +13,7 @@ import {
   type MenuTriggerState,
 } from "@/components/ui/menu";
 import { StatusRing } from "@/components/status-ring";
+import { bySizing } from "@/components/ui/control-geometry";
 import { STATUS_RING_HALO_INSET } from "@/components/status-ring/geometry";
 import { isWeb } from "@/constants/platform";
 import { getStatusDotColor } from "@/utils/status-dot-color";
@@ -343,16 +344,17 @@ const styles = StyleSheet.create((theme) => {
   // The rail every panel row sits on: inset from the panel edge so the fill is a rounded block
   // inside it, and tall enough that revealing an action button cannot resize the row.
   //
-  // Compact and desktop differ here and only here. A finger needs the taller row a menu row gets
-  // on compact; a pointer does not, and the popover keeps its density.
+  // Touch and pointer sizing differ here and only here. A finger needs the row a menu row gets
+  // on touch (`MENU_ITEM_HEIGHT` is always its touch value at `xs`); a pointer does not, and the
+  // popover keeps its density.
   const trackRow = {
     flexDirection: "row",
     alignItems: "center",
     gap: theme.spacing[2],
-    minHeight: { xs: MENU_ITEM_HEIGHT.xs, md: 32 },
+    minHeight: bySizing({ touch: MENU_ITEM_HEIGHT.xs, pointer: 32 }),
     marginHorizontal: theme.spacing[1],
     paddingHorizontal: theme.spacing[2],
-    paddingVertical: { xs: theme.spacing[2], md: theme.spacing[1] },
+    paddingVertical: bySizing({ touch: theme.spacing[2], pointer: theme.spacing[1] }),
     borderRadius: theme.borderRadius.md,
   } as const;
 
diff --git a/packages/app/src/constants/layout.ts b/packages/app/src/constants/layout.ts
index 739be45ee9..ee30a611ff 100644
--- a/packages/app/src/constants/layout.ts
+++ b/packages/app/src/constants/layout.ts
@@ -1,14 +1,19 @@
 import { useUnistyles } from "react-native-unistyles";
+import { bySizing, TOUCH_TARGET } from "@/components/ui/control-sizing";
 import { isWeb } from "@/constants/platform";
 
 export const FOOTER_HEIGHT = 75;
 
-// Shared header inner height (excluding safe area insets and border)
+// A bar of icon buttons: touch-sized it is one touch target tall, like an iOS navigation bar.
+const BAR_HEIGHT = { touch: TOUCH_TARGET, pointer: 36 };
+
+// Shared header inner height from `md` up (excluding safe area insets and border).
 // Used by both agent header (ScreenHeader) and explorer sidebar header
 // This ensures both headers have the same visual height
-export const HEADER_INNER_HEIGHT = 36;
+export const HEADER_INNER_HEIGHT = bySizing(BAR_HEIGHT).md;
 export const HEADER_INNER_HEIGHT_MOBILE = 56;
-export const WORKSPACE_SECONDARY_HEADER_HEIGHT = 36;
+/** The tab rail and pane toolbars under the header. A breakpoint value for stylesheets. */
+export const WORKSPACE_SECONDARY_HEADER_HEIGHT = bySizing(BAR_HEIGHT);
 export const HEADER_TOP_PADDING_MOBILE = 8;
 
 // Measured composer width; independent of the window's compact/wide breakpoint.
diff --git a/packages/app/src/git/actions-split-button.tsx b/packages/app/src/git/actions-split-button.tsx
index 7bd9aaf055..eb52e5ca53 100644
--- a/packages/app/src/git/actions-split-button.tsx
+++ b/packages/app/src/git/actions-split-button.tsx
@@ -17,7 +17,7 @@ import { inlineUnistylesStyle } from "@/styles/unistyles-inline-style";
 import type { ShortcutKey } from "@/utils/format-shortcut";
 import { actionsWithoutPrimary, type GitAction, type GitActions } from "@/git/policy";
 import { useGitActionRunner } from "@/git/use-actions";
-import { CONTROL_HEIGHTS, HEADER_CONTROL_HEIGHT } from "@/components/ui/control-geometry";
+import { HEADER_CONTROL_HEIGHT } from "@/components/ui/control-geometry";
 
 interface GitActionsSplitButtonProps {
   gitActions: GitActions;
@@ -272,10 +272,7 @@ const styles = StyleSheet.create((theme) => ({
     flexShrink: 0,
   },
   splitButton: {
-    height: {
-      xs: CONTROL_HEIGHTS.sm,
-      md: HEADER_CONTROL_HEIGHT,
-    },
+    height: HEADER_CONTROL_HEIGHT,
     flexDirection: "row",
     alignItems: "stretch",
     borderRadius: theme.borderRadius.md,
@@ -296,10 +293,7 @@ const styles = StyleSheet.create((theme) => ({
       xs: 48,
       md: 42,
     },
-    height: {
-      xs: CONTROL_HEIGHTS.sm,
-      md: HEADER_CONTROL_HEIGHT,
-    },
+    height: HEADER_CONTROL_HEIGHT,
     flexDirection: "row",
     alignItems: "center",
     justifyContent: "center",
@@ -330,24 +324,15 @@ const styles = StyleSheet.create((theme) => ({
     transform: [{ scale: 0.8 }],
   },
   splitButtonCaret: {
-    width: {
-      xs: CONTROL_HEIGHTS.sm,
-      md: HEADER_CONTROL_HEIGHT,
-    },
+    width: HEADER_CONTROL_HEIGHT,
     alignItems: "center",
     justifyContent: "center",
     borderLeftWidth: theme.borderWidth[1],
     borderLeftColor: theme.colors.borderAccent,
   },
   iconButton: {
-    width: {
-      xs: CONTROL_HEIGHTS.sm,
-      md: HEADER_CONTROL_HEIGHT,
-    },
-    height: {
-      xs: CONTROL_HEIGHTS.sm,
-      md: HEADER_CONTROL_HEIGHT,
-    },
+    width: HEADER_CONTROL_HEIGHT,
+    height: HEADER_CONTROL_HEIGHT,
     alignItems: "center",
     justifyContent: "center",
     borderRadius: theme.borderRadius.md,
diff --git a/packages/app/src/git/pull-request-panel/section-kit.tsx b/packages/app/src/git/pull-request-panel/section-kit.tsx
index 3022d93161..b4a9d00a3a 100644
--- a/packages/app/src/git/pull-request-panel/section-kit.tsx
+++ b/packages/app/src/git/pull-request-panel/section-kit.tsx
@@ -2,7 +2,7 @@ import React, { type ReactNode } from "react";
 import { Pressable, Text, View } from "react-native";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import type { CountedCheckPresentation } from "@/git/check-presentation";
-import { CONTROL_HEIGHTS } from "@/components/ui/control-geometry";
+import { CONTROL_HEIGHTS, mapLayout } from "@/components/ui/control-geometry";
 import {
   CheckPresentationIcon,
   getCheckPresentationTone,
@@ -164,10 +164,10 @@ export const sectionKitStyles = StyleSheet.create((theme) => ({
     gap: theme.spacing[2],
     paddingHorizontal: theme.spacing[3],
     // Fixed, not minHeight plus padding. A row's trailing slot holds an sm Button
-    // (28pt), which stacked on the vertical padding and made rows with an
+    // , which stacked on the vertical padding and made rows with an
     // "Add to chat" button taller than rows without one. The row is single-line by
     // construction, so it declares a height the button fits inside instead.
-    height: CONTROL_HEIGHTS.sm + theme.spacing[1],
+    height: mapLayout(CONTROL_HEIGHTS.sm, (height) => height + theme.spacing[1]),
   },
   checkName: {
     fontSize: theme.fontSize.base,
diff --git a/packages/app/src/hooks/use-fine-pointer.ts b/packages/app/src/hooks/use-fine-pointer.ts
index a0bc2489bf..dcd8fe0853 100644
--- a/packages/app/src/hooks/use-fine-pointer.ts
+++ b/packages/app/src/hooks/use-fine-pointer.ts
@@ -18,6 +18,16 @@ export function hasFinePointer(): boolean {
   return getFinePointerQueryList()?.matches ?? false;
 }
 
+/**
+ * True when the device has a touch screen, even while a mouse or keyboard is attached to it:
+ * the primary pointer is coarse, or the screen reports touch points. Always true on native.
+ */
+export function hasTouchScreen(): boolean {
+  if (!isWeb) return true;
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return false;
+  return window.matchMedia("(pointer: coarse)").matches || window.navigator.maxTouchPoints > 0;
+}
+
 /**
  * Reactive `hasFinePointer()` — re-renders when the user switches between a
  * mouse and touch (detachable keyboards, tablet mode).
diff --git a/packages/app/src/plugins/buttons/view.tsx b/packages/app/src/plugins/buttons/view.tsx
index 889d71001f..1876fef431 100644
--- a/packages/app/src/plugins/buttons/view.tsx
+++ b/packages/app/src/plugins/buttons/view.tsx
@@ -656,8 +656,8 @@ const styles = StyleSheet.create((theme) => ({
     gap: { xs: theme.spacing[1], md: theme.spacing[2] },
   },
   headerButton: {
-    height: { xs: 32, md: HEADER_CONTROL_HEIGHT },
-    minWidth: { xs: 32, md: HEADER_CONTROL_HEIGHT },
+    height: HEADER_CONTROL_HEIGHT,
+    minWidth: HEADER_CONTROL_HEIGHT,
     paddingHorizontal: theme.spacing[2],
     flexDirection: "row",
     alignItems: "center",
diff --git a/packages/app/src/screens/settings-screen.tsx b/packages/app/src/screens/settings-screen.tsx
index 8bce0c4dd1..9c8b230e4c 100644
--- a/packages/app/src/screens/settings-screen.tsx
+++ b/packages/app/src/screens/settings-screen.tsx
@@ -125,7 +125,7 @@ import {
   SETTINGS_DESKTOP_SIDEBAR_WIDTH,
   useIsCompactFormFactor,
 } from "@/constants/layout";
-import { densityIconBox, densityIconSize } from "@/styles/density";
+import { density, densityIconBox, densityIconSize } from "@/styles/density";
 import { useLocalDaemonServerId } from "@/hooks/use-is-local-daemon";
 import {
   type EnableBuiltInDaemonOption,
@@ -1523,7 +1523,7 @@ const sidebarStyles = StyleSheet.create((theme) => ({
     flexDirection: "row",
     alignItems: "center",
     gap: { xs: theme.spacing[3], md: theme.spacing[2] },
-    minHeight: { xs: 52, md: 28 },
+    minHeight: { xs: 52, md: density.tightRowHeight.md },
     paddingVertical: theme.spacing[1],
     paddingHorizontal: { xs: theme.spacing[4], md: theme.spacing[2] },
     borderRadius: { xs: 0, md: theme.borderRadius.lg },
@@ -1549,7 +1549,7 @@ const sidebarStyles = StyleSheet.create((theme) => ({
     flexDirection: "row",
     alignItems: "center",
     gap: { xs: theme.spacing[3], md: theme.spacing[2] },
-    minHeight: { xs: 52, md: 28 },
+    minHeight: { xs: 52, md: density.tightRowHeight.md },
     paddingVertical: theme.spacing[1],
     paddingHorizontal: { xs: theme.spacing[4], md: theme.spacing[2] },
     borderRadius: { xs: 0, md: theme.borderRadius.lg },
diff --git a/packages/app/src/screens/workspace/scripts/workspace-scripts-button.tsx b/packages/app/src/screens/workspace/scripts/workspace-scripts-button.tsx
index 6acd0dfe53..2f58dedfca 100644
--- a/packages/app/src/screens/workspace/scripts/workspace-scripts-button.tsx
+++ b/packages/app/src/screens/workspace/scripts/workspace-scripts-button.tsx
@@ -28,7 +28,7 @@ import type {
   WorkspaceScriptLinkTarget,
 } from "@/utils/workspace-script-links";
 import type { Theme } from "@/styles/theme";
-import { CONTROL_HEIGHTS, HEADER_CONTROL_HEIGHT } from "@/components/ui/control-geometry";
+import { HEADER_CONTROL_HEIGHT } from "@/components/ui/control-geometry";
 import { extraMutedIconColorMapping } from "@/components/ui/icon-color";
 import { ExitCodeBadge, routeLabelKey, ScriptIcon } from "./script-marks";
 import { scriptToneColorMapping } from "./script-status";
@@ -531,10 +531,7 @@ const styles = StyleSheet.create((theme) => ({
     flexShrink: 0,
   },
   splitButton: {
-    height: {
-      xs: CONTROL_HEIGHTS.sm,
-      md: HEADER_CONTROL_HEIGHT,
-    },
+    height: HEADER_CONTROL_HEIGHT,
     flexDirection: "row",
     alignItems: "stretch",
     borderRadius: theme.borderRadius.md,
diff --git a/packages/app/src/screens/workspace/workspace-desktop-tabs-row.tsx b/packages/app/src/screens/workspace/workspace-desktop-tabs-row.tsx
index bf957a27d4..01a5ccadaf 100644
--- a/packages/app/src/screens/workspace/workspace-desktop-tabs-row.tsx
+++ b/packages/app/src/screens/workspace/workspace-desktop-tabs-row.tsx
@@ -82,6 +82,7 @@ import { buildWorkspaceKeyboardHandlerId } from "@/keyboard/handler-id";
 import type { KeyboardActionDefinition } from "@/keyboard/keyboard-action-dispatcher";
 import { WorkspaceNewTabMenuContent } from "@/screens/workspace/workspace-new-tab-menu";
 import {
+  paneContentToolbarIconSize,
   paneContentToolbarTrailingPadding,
   ToolbarButton,
   ToolbarControls,
@@ -115,6 +116,8 @@ const TAB_ICON_WIDTH = 14;
 const TAB_CONTENT_GAP = 4;
 const TAB_DROP_INDICATOR_WIDTH = 4;
 const TAB_MODIFIED_DOT_SIZE = 8;
+// The tab rail only renders in the wide layout, so the device alone picks its glyph size.
+const TAB_RAIL_GLYPH_SIZE = paneContentToolbarIconSize(false);
 const TAB_MIN_WIDTH = 64;
 const TAB_MAX_WIDTH = 160;
 const TAB_CLOSE_BUTTON_RESERVED_WIDTH = 0;
@@ -249,7 +252,7 @@ function WorkspaceNewTabButton({
         testID="workspace-new-tab-button"
         style={placement === "inline" ? styles.inlineNewTabButton : undefined}
       >
-        <ThemedPlus size={14} uniProps={extraMutedColorMapping} />
+        <ThemedPlus size={TAB_RAIL_GLYPH_SIZE} uniProps={extraMutedColorMapping} />
       </ToolbarButton>
       <WorkspaceNewTabMenuContent
         serverId={serverId}
@@ -298,11 +301,11 @@ function WorkspacePaneToolbarActions({
   const splitDownKeys = useShortcutKeys("workspace-pane-split-down");
   const splitActionsVisible = showSplitActions && Boolean(onSplitRight && onSplitDown);
   const splitRightLeading = useMemo(
-    () => <ThemedColumns2 size={14} uniProps={extraMutedColorMapping} />,
+    () => <ThemedColumns2 size={TAB_RAIL_GLYPH_SIZE} uniProps={extraMutedColorMapping} />,
     [],
   );
   const splitDownLeading = useMemo(
-    () => <ThemedRows2 size={14} uniProps={extraMutedColorMapping} />,
+    () => <ThemedRows2 size={TAB_RAIL_GLYPH_SIZE} uniProps={extraMutedColorMapping} />,
     [],
   );
   const splitRightTrailing = useMemo(
@@ -341,9 +344,9 @@ function WorkspacePaneToolbarActions({
           onPress={onTogglePaneMaximized}
         >
           {paneMaximized ? (
-            <ThemedMinimize size={14} uniProps={extraMutedColorMapping} />
+            <ThemedMinimize size={TAB_RAIL_GLYPH_SIZE} uniProps={extraMutedColorMapping} />
           ) : (
-            <ThemedMaximize size={14} uniProps={extraMutedColorMapping} />
+            <ThemedMaximize size={TAB_RAIL_GLYPH_SIZE} uniProps={extraMutedColorMapping} />
           )}
         </ToolbarButton>
       ) : null}
@@ -354,7 +357,7 @@ function WorkspacePaneToolbarActions({
             label={t("workspace.git.actions.moreActions")}
             testID="workspace-split-pane-menu"
           >
-            <ThemedEllipsis size={14} uniProps={extraMutedColorMapping} />
+            <ThemedEllipsis size={TAB_RAIL_GLYPH_SIZE} uniProps={extraMutedColorMapping} />
           </ToolbarButton>
           <DropdownMenuContent
             side="bottom"
@@ -409,7 +412,7 @@ function WorkspaceExitFocusModeButton({
         testID="workspace-exit-focus-mode"
         onPress={onPress}
       >
-        <ThemedX size={14} uniProps={mutedColorMapping} />
+        <ThemedX size={TAB_RAIL_GLYPH_SIZE} uniProps={mutedColorMapping} />
       </ToolbarButton>
     </View>
   );
diff --git a/packages/app/src/styles/density.ts b/packages/app/src/styles/density.ts
index d29547ee88..1e66a555c0 100644
--- a/packages/app/src/styles/density.ts
+++ b/packages/app/src/styles/density.ts
@@ -1,33 +1,36 @@
+import {
+  bySizing,
+  iconSizeFor,
+  TOOLBAR_CONTROL_HEIGHT,
+  TOUCH_TARGET,
+  type IconSize,
+} from "@/components/ui/control-geometry";
 import { isCompactBreakpoint } from "@/constants/layout";
-import { ICON_SIZE, type Theme } from "@/styles/theme";
+import type { Theme } from "@/styles/theme";
 
 /**
- * Density sizes for surfaces that opt into touch sizing: rows and icons grow on compact
- * layouts and keep their desktop sizes from the `md` breakpoint up. Plain theme tokens stay
- * desktop-sized everywhere, so a surface migrates by swapping its sizes for these.
+ * Density sizes for surfaces that opt into touch sizing: rows and icons take their touch sizes
+ * where controls do (see `resolveControlSizing`) and their pointer sizes elsewhere. Plain theme
+ * tokens stay pointer-sized everywhere, so a surface migrates by swapping its sizes for these.
  *
  * Style values are Unistyles breakpoint values, resolved inside `StyleSheet.create`. Icon sizes
  * are props, so icons take them through `DensityIcon` or a `densityIconProps` mapping.
  */
 
-export type DensityIconSize = keyof typeof ICON_SIZE;
-
-const COMPACT_ICON_SIZE: Record<DensityIconSize, number> = { xs: 14, sm: 18, md: 20, lg: 24 };
-
-// Compact layouts end where `md` begins; see `isCompactBreakpoint`.
-function byLayout<T>(compact: T, desktop: T) {
-  return { xs: compact, md: desktop };
-}
+export type DensityIconSize = IconSize;
 
 export const density = {
   /** A list row such as a sidebar entry. */
-  rowHeight: byLayout(44, 36),
-  /** A row in a tight group, such as the sidebar's navigation rows. */
-  tightRowHeight: byLayout(36, 28),
+  rowHeight: bySizing({ touch: TOUCH_TARGET, pointer: 36 }),
+  /** A row in a tight group, such as the sidebar's navigation rows. Touch-sized it is a full row. */
+  tightRowHeight: bySizing({ touch: TOUCH_TARGET, pointer: 28 }),
   /** A square icon-only button that sits in a row or toolbar. */
-  iconButton: byLayout(44, 28),
-  /** The space between two blocks of rich text, such as Markdown paragraphs, code and images. */
-  blockGap: byLayout(12, 16),
+  iconButton: TOOLBAR_CONTROL_HEIGHT,
+  /**
+   * The space between two blocks of rich text, such as Markdown paragraphs, code and images.
+   * Reading rhythm, not a touch target, so it follows the layout alone.
+   */
+  blockGap: { xs: 12, md: 16 },
 };
 
 /** Resolves a density value for a prop, which Unistyles cannot resolve on its own. */
@@ -37,7 +40,7 @@ export function resolveDensity<T>(rt: { breakpoint?: string }, value: { xs: T; m
 
 /** The width or height of a slot that holds an icon of `size`. */
 export function densityIconBox(size: DensityIconSize) {
-  return byLayout(COMPACT_ICON_SIZE[size], ICON_SIZE[size]);
+  return bySizing(iconSizeFor(size));
 }
 
 export function densityIconSize(rt: { breakpoint?: string }, size: DensityIconSize): number {
diff --git a/packages/app/src/workspace/open-in-editor/button.tsx b/packages/app/src/workspace/open-in-editor/button.tsx
index e2b0530a82..5df614ec50 100644
--- a/packages/app/src/workspace/open-in-editor/button.tsx
+++ b/packages/app/src/workspace/open-in-editor/button.tsx
@@ -27,7 +27,7 @@ import { planWorkspaceOpenTargets } from "@/workspace/open-in-editor/planner";
 import type { Theme } from "@/styles/theme";
 import { ForgeBrandIcon } from "@/git/forge-icon";
 import { getForgePresentation } from "@/git/forge";
-import { CONTROL_HEIGHTS, HEADER_CONTROL_HEIGHT } from "@/components/ui/control-geometry";
+import { HEADER_CONTROL_HEIGHT } from "@/components/ui/control-geometry";
 import { extraMutedIconColorMapping } from "@/components/ui/icon-button-chrome";
 
 interface WorkspaceOpenInEditorButtonProps {
@@ -297,10 +297,7 @@ const styles = StyleSheet.create((theme) => ({
     flexShrink: 0,
   },
   splitButton: {
-    height: {
-      xs: CONTROL_HEIGHTS.sm,
-      md: HEADER_CONTROL_HEIGHT,
-    },
+    height: HEADER_CONTROL_HEIGHT,
     flexDirection: "row",
     alignItems: "stretch",
     borderRadius: theme.borderRadius.md,
@@ -317,10 +314,7 @@ const styles = StyleSheet.create((theme) => ({
     position: "relative",
   },
   splitButtonPrimaryIconOnly: {
-    width: {
-      xs: CONTROL_HEIGHTS.sm,
-      md: HEADER_CONTROL_HEIGHT,
-    },
+    width: HEADER_CONTROL_HEIGHT,
     paddingHorizontal: 0,
     justifyContent: "center",
     position: "relative",
@@ -348,10 +342,7 @@ const styles = StyleSheet.create((theme) => ({
     transform: [{ scale: 0.8 }],
   },
   splitButtonCaret: {
-    width: {
-      xs: CONTROL_HEIGHTS.sm,
-      md: HEADER_CONTROL_HEIGHT,
-    },
+    width: HEADER_CONTROL_HEIGHT,
     alignItems: "center",
     justifyContent: "center",
     borderLeftWidth: theme.borderWidth[1],

From 4991efddf8c3349848c406d941f87599484fb8f3 Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Wed, 4 Nov 2026 17:05:45 +0700
Subject: [PATCH 03/29] feat(app): follow iPhone Duo vertical bars and fold
 divisions (#8741)

* feat(app): follow system vertical bars and fold divisions

Keep custom navigation controls outside system content areas and use active division regions for temporary panel allocation. Normal sidebar preferences resume when the division disappears.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): show window actions in the active portal scope

The bottom-sheet provider creates its own portal context. Register the window action host within that context so symbols reach the root host.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): hide workspace bar actions behind compact panels

Compact panels keep the workspace route focused while covering its content. Hide its portal actions until the workspace panel is active again.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): continue the sidebar surface across divisions

Keep the fold free of controls while painting it as part of the sidebar, with the shared divider at the workspace edge.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): omit tab count beside the full tab rail

The full tab rail already exposes navigation. Use the same compact/full header selection for the vertical action list.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): preserve folded navigation and bar action lifetime

Use resolved sidebar visibility for desktop activity, and keep bar controls mounted while compact panels cover them so pending menu work survives. Carry circular button chrome inside the portal and exercise the rendered boundary in Chromium.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): own script actions across header placement changes

Keep one script action instance on the workspace screen so pending restarts survive removal of either menu. Pass activity through the bar portal so covered menus close their overlays without taking workflow state with them.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* test(app): exercise script ownership through the workspace

Replace synthetic ownership fixtures with a real workspace, script menu and isolated terminal worker. Hold terminal exit until the compact header is removed so moving pending state back into the menu fails the regression. Exercise portal activity with production menu and header controls.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

---------

Co-authored-by: Elsa Granger <zeyugao@outlook.com>
---
 .../browser/compact-workspace-header.spec.ts  |  47 ++++
 .../native-sidebar-drag-release.ios.ad        |   5 +
 .../e2e/support/helpers/workspace-setup.ts    |  20 ++
 .../expo-module.config.json                   |   4 +
 .../ios/PaseoWindowLayout.podspec             |  15 ++
 .../ios/PaseoWindowLayoutModule.swift         | 110 +++++++++
 packages/app/src/app/_layout.tsx              |  68 ++++--
 .../components/desktop-sidebar-layout.test.ts |  84 +++++++
 .../src/components/desktop-sidebar-layout.ts  |  13 +-
 packages/app/src/components/left-sidebar.tsx  |  61 +++--
 .../compact-workspace-header/index.tsx        |  53 +++--
 .../src/screens/workspace/scripts/index.ts    |   2 +
 .../scripts/use-workspace-script-actions.ts   |  11 +-
 .../scripts/workspace-scripts-button.test.tsx |  62 +++--
 .../scripts/workspace-scripts-button.tsx      |  19 +-
 .../scripts/workspace-scripts-menu-pages.tsx  |  22 +-
 .../screens/workspace/workspace-screen.tsx    | 222 ++++++++++--------
 .../window-layout/actions.browser.test.tsx    |  95 ++++++++
 packages/app/src/window-layout/actions.tsx    |  50 ++++
 packages/app/src/window-layout/context.ts     |  15 ++
 packages/app/src/window-layout/index.ios.tsx  |  43 ++++
 packages/app/src/window-layout/index.tsx      |  15 ++
 packages/app/src/window-layout/model.ts       |  65 +++++
 packages/app/src/window-layout/surface.tsx    |  64 +++++
 .../app/test-stubs/react-native-unistyles.ts  |   2 +
 25 files changed, 948 insertions(+), 219 deletions(-)
 create mode 100644 packages/app/modules/paseo-window-layout/expo-module.config.json
 create mode 100644 packages/app/modules/paseo-window-layout/ios/PaseoWindowLayout.podspec
 create mode 100644 packages/app/modules/paseo-window-layout/ios/PaseoWindowLayoutModule.swift
 create mode 100644 packages/app/src/window-layout/actions.browser.test.tsx
 create mode 100644 packages/app/src/window-layout/actions.tsx
 create mode 100644 packages/app/src/window-layout/context.ts
 create mode 100644 packages/app/src/window-layout/index.ios.tsx
 create mode 100644 packages/app/src/window-layout/index.tsx
 create mode 100644 packages/app/src/window-layout/model.ts
 create mode 100644 packages/app/src/window-layout/surface.tsx

diff --git a/packages/app/e2e/browser/compact-workspace-header.spec.ts b/packages/app/e2e/browser/compact-workspace-header.spec.ts
index be26dbb8d1..ca352e277e 100644
--- a/packages/app/e2e/browser/compact-workspace-header.spec.ts
+++ b/packages/app/e2e/browser/compact-workspace-header.spec.ts
@@ -1,5 +1,6 @@
 import type { Page, TestInfo } from "@playwright/test";
 import { test, expect } from "../support/fixtures";
+import { pauseWorkspaceTerminalWorker } from "../support/helpers/workspace-setup";
 import { seedWorkspace } from "../support/helpers/seed-client";
 import { openAgentRoute } from "../support/helpers/mock-agent";
 import { getServerId } from "../support/helpers/server-id";
@@ -190,3 +191,49 @@ test("compact header menu runs, shows, and stops workspace scripts", async ({ pa
     await workspace.cleanup();
   }
 });
+
+async function restartScriptAcrossHeaderRemoval(page: Page, terminalId: string) {
+  await openRunningScriptPage(page, "lint");
+  const resumeWorker = await pauseWorkspaceTerminalWorker(terminalId);
+  try {
+    await menuRow(page, "Restart").click();
+    await page.setViewportSize({ width: 1280, height: 844 });
+    await expect(page.getByRole("button", { name: /Switch tabs/ })).toHaveCount(0);
+    await expect(page.getByTestId("workspace-scripts-button")).toBeVisible();
+  } finally {
+    resumeWorker();
+  }
+}
+
+async function expectScriptTerminalReplaced(
+  workspace: Awaited<ReturnType<typeof openWorkspaceWithScripts>>,
+  previousId: string,
+) {
+  await expect
+    .poll(
+      async () => {
+        const after = await workspace.client.listTerminals(undefined, undefined, {
+          workspaceId: workspace.workspaceId,
+        });
+        return after.terminals.filter((terminal) => terminal.id !== previousId).length;
+      },
+      { timeout: 15_000 },
+    )
+    .toBe(1);
+}
+
+test("pending script restart survives removal of the compact header", async ({ page }) => {
+  await page.setViewportSize({ width: 390, height: 844 });
+  const workspace = await openWorkspaceWithScripts(page);
+  try {
+    await runScriptFromScriptsPage(page, "lint");
+    const before = await workspace.client.listTerminals(undefined, undefined, {
+      workspaceId: workspace.workspaceId,
+    });
+    expect(before.terminals).toHaveLength(1);
+    await restartScriptAcrossHeaderRemoval(page, before.terminals[0]!.id);
+    await expectScriptTerminalReplaced(workspace, before.terminals[0]!.id);
+  } finally {
+    await workspace.cleanup();
+  }
+});
diff --git a/packages/app/e2e/mobile/agent-device/native-sidebar-drag-release.ios.ad b/packages/app/e2e/mobile/agent-device/native-sidebar-drag-release.ios.ad
index 359e89c5c9..d92c92771c 100644
--- a/packages/app/e2e/mobile/agent-device/native-sidebar-drag-release.ios.ad
+++ b/packages/app/e2e/mobile/agent-device/native-sidebar-drag-release.ios.ad
@@ -6,6 +6,11 @@ env APP_ID=sh.paseo.debug
 # Hold past drag arming (180ms), then release.
 open "${APP_ID}"
 press "label=\"Open menu\""
+wait "id=\"sidebar-close\"" 10000
+press "id=\"sidebar-close\""
+# The close target must clear system controls, including a trailing status column.
+wait "label=\"Open menu\"" 5000
+press "label=\"Open menu\""
 wait "id=\"${WORKSPACE_ROW}\"" 10000
 longpress "id=\"${WORKSPACE_ROW}\"" 250
 press "id=\"${WORKSPACE_ROW}\""
diff --git a/packages/app/e2e/support/helpers/workspace-setup.ts b/packages/app/e2e/support/helpers/workspace-setup.ts
index eda1d8d023..a89f52c70a 100644
--- a/packages/app/e2e/support/helpers/workspace-setup.ts
+++ b/packages/app/e2e/support/helpers/workspace-setup.ts
@@ -1,3 +1,5 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
 import { realpathSync } from "node:fs";
 import { expect, type Page } from "@playwright/test";
 import type { DaemonClient as InternalDaemonClient } from "@getpaseo/client/internal/daemon-client";
@@ -380,3 +382,21 @@ export function observeSetupPanelTraffic(page: Page) {
 export function setupCommandOutput(detail: { commands: Array<{ log: string }> }): string {
   return detail.commands.map((command) => command.log).join("\n");
 }
+
+/** Hold this isolated daemon's terminal worker so script exit cannot race a layout change. */
+export async function pauseWorkspaceTerminalWorker(terminalId: string): Promise<() => void> {
+  const home = process.env.E2E_PASEO_HOME;
+  if (!home) throw new Error("Missing isolated E2E home");
+  const directory = path.join(home, "terminal-worker");
+  for (const name of await readdir(directory)) {
+    if (!name.endsWith(".json")) continue;
+    const record = JSON.parse(await readFile(path.join(directory, name), "utf8")) as {
+      pid: number;
+      terminals: Array<{ id: string }>;
+    };
+    if (!record.terminals.some((terminal) => terminal.id === terminalId)) continue;
+    process.kill(record.pid, "SIGSTOP");
+    return () => process.kill(record.pid, "SIGCONT");
+  }
+  throw new Error(`No isolated terminal worker owns ${terminalId}`);
+}
diff --git a/packages/app/modules/paseo-window-layout/expo-module.config.json b/packages/app/modules/paseo-window-layout/expo-module.config.json
new file mode 100644
index 0000000000..369360a041
--- /dev/null
+++ b/packages/app/modules/paseo-window-layout/expo-module.config.json
@@ -0,0 +1,4 @@
+{
+  "platforms": ["ios"],
+  "ios": { "modules": ["PaseoWindowLayoutModule"] }
+}
diff --git a/packages/app/modules/paseo-window-layout/ios/PaseoWindowLayout.podspec b/packages/app/modules/paseo-window-layout/ios/PaseoWindowLayout.podspec
new file mode 100644
index 0000000000..6f2e20f24a
--- /dev/null
+++ b/packages/app/modules/paseo-window-layout/ios/PaseoWindowLayout.podspec
@@ -0,0 +1,15 @@
+Pod::Spec.new do |s|
+  s.name = 'PaseoWindowLayout'
+  s.version = '0.1.0'
+  s.summary = 'System window layout geometry for Paseo'
+  s.description = 'Publishes system bar and division geometry'
+  s.license = 'Apache-2.0'
+  s.author = 'Paseo'
+  s.homepage = 'https://paseo.sh'
+  s.platforms = { :ios => '16.4' }
+  s.swift_version = '5.4'
+  s.source = { :path => '.' }
+  s.static_framework = true
+  s.dependency 'ExpoModulesCore'
+  s.source_files = '**/*.swift'
+end
diff --git a/packages/app/modules/paseo-window-layout/ios/PaseoWindowLayoutModule.swift b/packages/app/modules/paseo-window-layout/ios/PaseoWindowLayoutModule.swift
new file mode 100644
index 0000000000..f5b673e6cc
--- /dev/null
+++ b/packages/app/modules/paseo-window-layout/ios/PaseoWindowLayoutModule.swift
@@ -0,0 +1,110 @@
+import ExpoModulesCore
+import UIKit
+
+public final class PaseoWindowLayoutModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("PaseoWindowLayout")
+    View(WindowLayoutView.self) {
+      Events("onGeometryChange")
+    }
+  }
+}
+
+final class WindowLayoutView: ExpoView {
+  let onGeometryChange = EventDispatcher()
+  private var updateScheduled = false
+  private var previousPayload: [String: Any]?
+  private var divisions: [CGRect] = []
+  private var barGuide: UILayoutGuide?
+  private var barEdge = "none"
+  private var measuredBounds = CGRect.zero
+
+  required init(appContext: AppContext? = nil) {
+    super.init(appContext: appContext)
+    isUserInteractionEnabled = false
+    #if compiler(>=6.4)
+    if #available(iOS 27.1, *) {
+      registerForTraitChanges(UITraitCollection.systemTraitsAffectingVerticalBarEdge) {
+        (view: WindowLayoutView, _) in
+        view.setNeedsUpdateConstraints()
+        view.scheduleUpdate()
+      }
+    }
+    #endif
+  }
+
+  override func didMoveToWindow() {
+    super.didMoveToWindow()
+    previousPayload = nil
+    setNeedsUpdateConstraints()
+    scheduleUpdate()
+  }
+
+  override func safeAreaInsetsDidChange() {
+    super.safeAreaInsetsDidChange()
+    setNeedsUpdateConstraints()
+    scheduleUpdate()
+  }
+
+  override func layoutSubviews() {
+    super.layoutSubviews()
+    if bounds != measuredBounds {
+      measuredBounds = bounds
+      setNeedsUpdateConstraints()
+    }
+    scheduleUpdate()
+  }
+
+  override func updateConstraints() {
+    #if compiler(>=6.4)
+    if #available(iOS 27.1, *) {
+      // UIKit tracks these reads and invalidates constraints when regions change.
+      divisions = reservedRegions(kind: .division).compactMap { $0.isActive ? $0.frame : nil }
+      let edge: String
+      switch traitCollection.verticalBarEdge {
+      case .leading: edge = "leading"
+      case .trailing: edge = "trailing"
+      default: edge = "none"
+      }
+      if edge != barEdge {
+        barEdge = edge
+        barGuide = edge == "none" ? nil : layoutGuide(
+          for: .bar(onEdge: edge == "trailing" ? .right : .left, extent: 44)
+        )
+      }
+    }
+    #endif
+    super.updateConstraints()
+    scheduleUpdate()
+  }
+
+  private func scheduleUpdate() {
+    guard !updateScheduled else { return }
+    updateScheduled = true
+    DispatchQueue.main.async { [weak self] in
+      guard let self else { return }
+      self.updateScheduled = false
+      self.publish()
+    }
+  }
+
+  private func publish() {
+    guard window != nil, bounds.width > 0, bounds.height > 0 else { return }
+    let bar = barGuide?.layoutFrame
+    var barPayload: Any = NSNull()
+    if let bar, bar.width > 0, bar.height > 0 { barPayload = rect(bar) }
+    let payload: [String: Any] = [
+      "bounds": rect(bounds),
+      "verticalBarEdge": barEdge,
+      "verticalBar": barPayload,
+      "divisions": divisions.map(rect)
+    ]
+    guard !NSDictionary(dictionary: payload).isEqual(to: previousPayload ?? [:]) else { return }
+    previousPayload = payload
+    onGeometryChange(payload)
+  }
+
+  private func rect(_ frame: CGRect) -> [String: CGFloat] {
+    ["x": frame.minX, "y": frame.minY, "width": frame.width, "height": frame.height]
+  }
+}
diff --git a/packages/app/src/app/_layout.tsx b/packages/app/src/app/_layout.tsx
index 483de1c27d..29d63a6a05 100644
--- a/packages/app/src/app/_layout.tsx
+++ b/packages/app/src/app/_layout.tsx
@@ -1,4 +1,12 @@
 import { useHardwareKeyboardPresent } from "@/keyboard";
+import {
+  WindowLayoutProvider,
+  WindowLayoutActionsHost,
+  WindowLayoutSurface,
+  WindowLayoutDivisionGap,
+  useWindowLayout,
+  resolveDesktopDivisionLayout,
+} from "@/window-layout";
 import { AddHostProvider, AddHostFlowHost } from "@/hosts/add-host";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { useActiveWorkspaceSelection } from "@/stores/navigation-active-workspace-store";
@@ -59,6 +67,7 @@ import {
   resolveDesktopAppChromeLayout,
   resolveDesktopAppContentMinimum,
   resolveDesktopSidebarVisibility,
+  resolveSidebarActivity,
 } from "@/components/desktop-sidebar-layout";
 import { isNative, isWeb } from "@/constants/platform";
 import { HorizontalScrollProvider } from "@/contexts/horizontal-scroll-context";
@@ -355,9 +364,16 @@ function AppContainer({ children, chromeEnabled: chromeEnabledOverride }: AppCon
   const isFocusModeEnabled = usePanelStore((state) => state.desktop.focusModeEnabled);
   const isDesktopAgentListOpen = usePanelStore((state) => state.desktop.agentListOpen);
   const sidebarWidth = usePanelStore((state) => state.sidebarWidth);
-  const { width: windowWidth } = useWindowDimensions();
+  const { width: windowWidth, height: windowHeight } = useWindowDimensions();
   const insets = useSafeAreaInsets();
   const viewportWidth = windowWidth - insets.left - insets.right;
+  const divisionLayout = resolveDesktopDivisionLayout({
+    geometry: useWindowLayout(),
+    windowWidth,
+    windowHeight,
+    leftInset: insets.left,
+    rightInset: insets.right,
+  });
 
   const cycleTheme = useCallback(() => {
     void updateSettings({ theme: getNextThemePreference(settings.theme) });
@@ -418,6 +434,7 @@ function AppContainer({ children, chromeEnabled: chromeEnabledOverride }: AppCon
     isCompactLayout,
     isMounted: desktopSidebarMounted,
     isOpen: isDesktopAgentListOpen,
+    divisionLayout,
     canShare: canDesktopAppSidebarShare({
       contentMinimumWidth: appContentMinimumWidth,
       requestedSidebarWidth: sidebarWidth,
@@ -441,18 +458,19 @@ function AppContainer({ children, chromeEnabled: chromeEnabledOverride }: AppCon
   if (isWeb) {
     themedSidebarChrome = <AppearanceStyleBoundary>{sidebarChrome}</AppearanceStyleBoundary>;
   }
-  const workspaceChromeStyle = useMemo(
-    () => [rowStyle, !isCompactLayout && { paddingLeft: insets.left, paddingRight: insets.right }],
-    [insets.left, insets.right, isCompactLayout],
-  );
   const workspaceChrome = (
-    <View style={workspaceChromeStyle}>
+    <WindowLayoutSurface compact={isCompactLayout} style={rowStyle}>
       <WorkspaceLayoutModePublisher />
       {!isCompactLayout ? (
         <WindowChromeRegion corners={appChromeLayout.sidebarCorners}>
           {themedSidebarChrome}
         </WindowChromeRegion>
       ) : null}
+      <WindowLayoutDivisionGap
+        layout={divisionLayout}
+        sidebarVisible={desktopSidebarVisible}
+        compact={isCompactLayout}
+      />
       <WorkspaceExplorerOpenGesture enabled={chromeEnabled && isCompactLayout}>
         <WindowChromeRegion
           corners={isCompactLayout && chromeEnabled ? "both" : appChromeLayout.contentCorners}
@@ -460,7 +478,7 @@ function AppContainer({ children, chromeEnabled: chromeEnabledOverride }: AppCon
           <View style={flexStyle}>{children}</View>
         </WindowChromeRegion>
       </WorkspaceExplorerOpenGesture>
-    </View>
+    </WindowLayoutSurface>
   );
 
   // Native panel gesture hosts outlive appearance keys, like native navigators.
@@ -548,8 +566,7 @@ function SidebarChrome({
 }) {
   const isCompactLayout = useIsCompactFormFactor();
   const isMobileActive = useIsMobilePanelActive("agent-list");
-  const isDesktopOpen = usePanelStore((state) => state.desktop.agentListOpen);
-  const active = visible && (isCompactLayout ? isMobileActive : isDesktopOpen);
+  const active = resolveSidebarActivity(visible, isCompactLayout, isMobileActive);
   const hardwareKeyboardPresent = useHardwareKeyboardPresent();
   return (
     <SidebarModelProvider
@@ -875,20 +892,31 @@ function RuntimeProviders({ children }: { children: ReactNode }) {
 // auth, settings, ...) must wrap PortalProvider, not be wrapped by it.
 // BottomSheetModalProvider is the exception: Gorhom modals consume portal
 // context and need one shared provider for sibling sheets to stack.
+function RootOverlayProviders({ children }: { children: ReactNode }) {
+  return (
+    <ToastProvider>
+      <PortalProvider>
+        <BottomSheetModalProvider>
+          {children}
+          <WindowLayoutActionsHost />
+        </BottomSheetModalProvider>
+      </PortalProvider>
+    </ToastProvider>
+  );
+}
+
 function RootProviders({ children }: { children: ReactNode }) {
   return (
     <KeyboardActionDispatcherProvider>
-      <WindowChromeProvider>
-        <KeyboardProvider>
-          <KeyboardShiftProvider>
-            <ToastProvider>
-              <PortalProvider>
-                <BottomSheetModalProvider>{children}</BottomSheetModalProvider>
-              </PortalProvider>
-            </ToastProvider>
-          </KeyboardShiftProvider>
-        </KeyboardProvider>
-      </WindowChromeProvider>
+      <WindowLayoutProvider>
+        <WindowChromeProvider>
+          <KeyboardProvider>
+            <KeyboardShiftProvider>
+              <RootOverlayProviders>{children}</RootOverlayProviders>
+            </KeyboardShiftProvider>
+          </KeyboardProvider>
+        </WindowChromeProvider>
+      </WindowLayoutProvider>
     </KeyboardActionDispatcherProvider>
   );
 }
diff --git a/packages/app/src/components/desktop-sidebar-layout.test.ts b/packages/app/src/components/desktop-sidebar-layout.test.ts
index 969bbb581f..f4ccec7e98 100644
--- a/packages/app/src/components/desktop-sidebar-layout.test.ts
+++ b/packages/app/src/components/desktop-sidebar-layout.test.ts
@@ -1,13 +1,97 @@
 import { describe, expect, it } from "vitest";
+import {
+  resolveDesktopDivisionLayout,
+  resolveWorkspaceActionPlacement,
+  resolveWorkspaceBarActions,
+  type WindowLayout,
+} from "@/window-layout";
 import {
   canDesktopAppSidebarShare,
   resolveDesktopAppChromeLayout,
   resolveDesktopAppContentMinimum,
   resolveDesktopSidebarVisibility,
+  resolveSidebarActivity,
   resolveDesktopSidebarWidth,
 } from "@/components/desktop-sidebar-layout";
 
 describe("desktop sidebar layout", () => {
+  const geometry: WindowLayout = {
+    bounds: { x: 0, y: 0, width: 951, height: 669 },
+    verticalBarEdge: "trailing",
+    verticalBar: { x: 875, y: 160, width: 44, height: 450 },
+    divisions: [{ x: 465, y: 0, width: 21, height: 669 }],
+  };
+
+  it("places workspace action symbols in the reported trailing bar", () => {
+    expect(resolveWorkspaceActionPlacement(geometry)).toBe("vertical-bar");
+    expect(resolveWorkspaceActionPlacement(null)).toBe("header");
+    expect(resolveWorkspaceActionPlacement({ ...geometry, verticalBarEdge: "none" })).toBe(
+      "header",
+    );
+    expect(resolveWorkspaceActionPlacement({ ...geometry, verticalBar: null })).toBe("header");
+    expect(resolveWorkspaceActionPlacement({ ...geometry, verticalBarEdge: "leading" })).toBe(
+      "header",
+    );
+  });
+
+  it("shows the tab count only for the compact header selection", () => {
+    expect(resolveWorkspaceBarActions("compact")).toEqual(["tab-count", "overflow", "explorer"]);
+    expect(resolveWorkspaceBarActions("full")).toEqual(["overflow", "explorer"]);
+  });
+
+  it("allocates both panels around a live division without clamping to saved sidebar widths", () => {
+    const input = {
+      geometry,
+      windowWidth: 951,
+      windowHeight: 669,
+      leftInset: 0,
+      rightInset: 84,
+    };
+    expect(resolveDesktopDivisionLayout(input)).toEqual({
+      sidebarWidth: 465,
+      gap: 21,
+      contentWidth: 381,
+    });
+    expect(
+      resolveDesktopDivisionLayout({ ...input, geometry: { ...geometry, divisions: [] } }),
+    ).toBeNull();
+    expect(
+      resolveDesktopDivisionLayout({ ...input, windowWidth: 669, windowHeight: 951 }),
+    ).toBeNull();
+    expect(resolveDesktopDivisionLayout({ ...input, geometry: null })).toBeNull();
+    expect(
+      resolveDesktopDivisionLayout({
+        ...input,
+        geometry: { ...geometry, divisions: [{ x: 0, y: 325, width: 951, height: 19 }] },
+      }),
+    ).toBeNull();
+  });
+
+  it("activates a revealed folded sidebar while preserving closed desktop intent", () => {
+    expect(resolveSidebarActivity(true, false, false)).toBe(true);
+    expect(resolveSidebarActivity(false, false, false)).toBe(false);
+    expect(resolveSidebarActivity(true, true, false)).toBe(false);
+    expect(resolveSidebarActivity(true, true, true)).toBe(true);
+  });
+
+  it("temporarily reveals navigation for a division without changing the saved closed intent", () => {
+    const visibility = {
+      chromeEnabled: true,
+      isCompactLayout: false,
+      isMounted: true,
+      isOpen: false,
+      canShare: false,
+    };
+    expect(
+      resolveDesktopSidebarVisibility({
+        ...visibility,
+        divisionLayout: { sidebarWidth: 465, gap: 21, contentWidth: 381 },
+      }),
+    ).toBe(true);
+    expect(resolveDesktopSidebarVisibility({ ...visibility, divisionLayout: null })).toBe(false);
+    expect(visibility.isOpen).toBe(false);
+  });
+
   it("keeps a retained sidebar hidden while app chrome is suppressed", () => {
     expect(
       resolveDesktopSidebarVisibility({
diff --git a/packages/app/src/components/desktop-sidebar-layout.ts b/packages/app/src/components/desktop-sidebar-layout.ts
index d8518bcb82..09e03bc02e 100644
--- a/packages/app/src/components/desktop-sidebar-layout.ts
+++ b/packages/app/src/components/desktop-sidebar-layout.ts
@@ -1,6 +1,7 @@
 import { EXPLORER_WORKSPACE_MIN_WIDTH } from "@/components/explorer-sidebar-layout";
 import { SETTINGS_DESKTOP_SPLIT_MIN_WIDTH } from "@/constants/layout";
 import { MAX_SIDEBAR_WIDTH, MIN_SIDEBAR_WIDTH } from "@/stores/panel-store";
+import type { DesktopDivisionLayout } from "@/window-layout";
 
 const MIN_DESKTOP_CENTER_WIDTH = 400;
 
@@ -10,13 +11,13 @@ export function resolveDesktopSidebarVisibility(input: {
   isMounted: boolean;
   isOpen: boolean;
   canShare: boolean;
+  divisionLayout?: DesktopDivisionLayout | null;
 }): boolean {
   return (
     input.chromeEnabled &&
     !input.isCompactLayout &&
     input.isMounted &&
-    input.isOpen &&
-    input.canShare
+    (input.divisionLayout != null || (input.isOpen && input.canShare))
   );
 }
 
@@ -85,3 +86,11 @@ export function canDesktopAppSidebarShare(input: {
     input.contentMinimumWidth
   );
 }
+
+export function resolveSidebarActivity(
+  visible: boolean,
+  compact: boolean,
+  mobileActive: boolean,
+): boolean {
+  return visible && (!compact || mobileActive);
+}
diff --git a/packages/app/src/components/left-sidebar.tsx b/packages/app/src/components/left-sidebar.tsx
index 7f59312f7a..73c1fadb7b 100644
--- a/packages/app/src/components/left-sidebar.tsx
+++ b/packages/app/src/components/left-sidebar.tsx
@@ -26,6 +26,7 @@ import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { TitlebarDragRegion } from "@/components/desktop/titlebar-drag-region";
 import { SidebarCloseButton } from "@/components/headers/sidebar-close-button";
 import { resolveDesktopSidebarWidth } from "@/components/desktop-sidebar-layout";
+import { useWindowLayout, resolveDesktopDivisionLayout } from "@/window-layout";
 import {
   SIDEBAR_RESIZE_ACTIVATION_OFFSET,
   SIDEBAR_RESIZE_FAIL_OFFSET,
@@ -528,6 +529,7 @@ function MobileSidebar({
   insetsBottom,
   closeSidebar,
 }: MobileSidebarProps) {
+  const insets = useSafeAreaInsets();
   const hasActiveHostFilter = useSidebarViewStore((state) => state.hostFilters.length > 0);
   const { gesture: closeGesture, gestureRef: closeGestureRef } = useCloseAgentListGesture();
 
@@ -542,10 +544,10 @@ function MobileSidebar({
         onPress={closeSidebar}
         testID="sidebar-close"
         nativeID="sidebar-close"
-        style={styles.mobileCloseButton}
+        style={styles.mobileCloseButton(insets.right)}
       />
     ),
-    [labels.closeSidebar, closeSidebar],
+    [labels.closeSidebar, closeSidebar, insets.right],
   );
 
   const mobileSidebarInsetStyle = useMemo(
@@ -666,13 +668,22 @@ function DesktopSidebar({
   const hasActiveHostFilter = useSidebarViewStore((state) => state.hostFilters.length > 0);
   const sidebarWidth = usePanelStore((state) => state.sidebarWidth);
   const setSidebarWidth = usePanelStore((state) => state.setSidebarWidth);
-  const { width: windowWidth } = useWindowDimensions();
+  const { width: windowWidth, height: windowHeight } = useWindowDimensions();
   const insets = useSafeAreaInsets();
   const viewportWidth = windowWidth - insets.left - insets.right;
-  const visibleSidebarWidth = resolveDesktopSidebarWidth({
-    requestedWidth: sidebarWidth,
-    viewportWidth,
+  const divisionLayout = resolveDesktopDivisionLayout({
+    geometry: useWindowLayout(),
+    windowWidth,
+    windowHeight,
+    leftInset: insets.left,
+    rightInset: insets.right,
   });
+  const visibleSidebarWidth =
+    divisionLayout?.sidebarWidth ??
+    resolveDesktopSidebarWidth({
+      requestedWidth: sidebarWidth,
+      viewportWidth,
+    });
 
   const startWidthRef = useRef(visibleSidebarWidth);
   const resizeWidth = useSharedValue(visibleSidebarWidth);
@@ -687,6 +698,7 @@ function DesktopSidebar({
   const resizeGesture = useMemo(
     () =>
       Gesture.Pan()
+        .enabled(divisionLayout === null)
         .hitSlop({ left: 8, right: 8, top: 0, bottom: 0 })
         .onBegin(() => {
           scheduleOnRN(showResizeGrip);
@@ -708,13 +720,14 @@ function DesktopSidebar({
             viewportWidth,
           });
         })
-        .onEnd(() => {
-          runOnJS(setSidebarWidth)(resizeWidth.value);
+        .onEnd((_event, success) => {
+          if (success) runOnJS(setSidebarWidth)(resizeWidth.value);
         })
         .onFinalize(() => {
           scheduleOnRN(hideResizeGrip);
         }),
     [
+      divisionLayout,
       hideResizeGrip,
       resizeWidth,
       setSidebarWidth,
@@ -725,7 +738,7 @@ function DesktopSidebar({
   );
 
   const resizeAnimatedStyle = useAnimatedStyle(() => ({
-    width: resizeWidth.value,
+    width: divisionLayout?.sidebarWidth ?? resizeWidth.value,
   }));
 
   const desktopSidebarStyle = useMemo(
@@ -738,10 +751,10 @@ function DesktopSidebar({
   );
   const desktopSidebarBorderStyle = useMemo(
     () => [
-      styles.desktopSidebarBorder,
+      styles.desktopSidebarBorder(divisionLayout !== null),
       { flex: 1, paddingTop: insetsTop, paddingBottom: insets.bottom },
     ],
-    [insetsTop, insets.bottom],
+    [insetsTop, insets.bottom, divisionLayout],
   );
   const sidebarHeaderGroupStyle = useMemo(
     () => [styles.sidebarHeaderGroup, ownsTopLeft && styles.sidebarHeaderGroupBelowChrome],
@@ -812,12 +825,14 @@ function DesktopSidebar({
           handleOpenHostSettings={handleOpenHostSettings}
         />
 
-        <SidebarResizeHandle
-          edge="right"
-          gesture={resizeGesture}
-          pressed={resizePressed}
-          testID="left-sidebar-resize-handle"
-        />
+        {divisionLayout === null ? (
+          <SidebarResizeHandle
+            edge="right"
+            gesture={resizeGesture}
+            pressed={resizePressed}
+            testID="left-sidebar-resize-handle"
+          />
+        ) : null}
       </View>
     </Animated.View>
   );
@@ -883,14 +898,14 @@ const styles = StyleSheet.create((theme) => ({
     flex: 1,
     minHeight: 0,
   },
-  mobileCloseButton: {
-    marginRight: theme.spacing[2],
-  },
-  desktopSidebarBorder: {
-    borderRightWidth: 1,
+  mobileCloseButton: (rightInset: number) => ({
+    marginRight: theme.spacing[2] + rightInset,
+  }),
+  desktopSidebarBorder: (hasDivision: boolean) => ({
+    borderRightWidth: hasDivision ? 0 : 1,
     borderRightColor: theme.colors.border,
     backgroundColor: theme.colors.surfaceSidebar,
-  },
+  }),
   sidebarDragArea: {
     position: "relative",
   },
diff --git a/packages/app/src/screens/workspace/compact-workspace-header/index.tsx b/packages/app/src/screens/workspace/compact-workspace-header/index.tsx
index 2a7c4a6a57..1865bc5c93 100644
--- a/packages/app/src/screens/workspace/compact-workspace-header/index.tsx
+++ b/packages/app/src/screens/workspace/compact-workspace-header/index.tsx
@@ -1,4 +1,4 @@
-import { useMemo, type ReactNode } from "react";
+import { Fragment, useMemo, type ReactNode } from "react";
 import { useTranslation } from "react-i18next";
 import { CompactHeader } from "@/components/headers/compact-header";
 import {
@@ -6,6 +6,13 @@ import {
   WorkspaceExplorerToggle,
 } from "@/screens/workspace/workspace-explorer-toggle";
 import { WorkspaceHeaderProjectRow } from "@/screens/workspace/workspace-header-project-row";
+import {
+  useWindowLayout,
+  resolveWorkspaceActionPlacement,
+  resolveWorkspaceBarActions,
+  WindowLayoutActions,
+} from "@/window-layout";
+import { IconButtonChromeProvider } from "@/components/ui/icon-button-chrome";
 
 export { MobileWorkspaceTabSwitcher } from "./tab-switcher";
 
@@ -18,8 +25,11 @@ interface CompactWorkspaceHeaderProps {
   onToggleExplorer: () => void;
   explorerToggleLabel: string;
   explorerToggleAccessibilityState: { expanded: boolean };
-  /** Tab switcher and workspace menu, before the explorer toggle. */
+  tabSwitcher: ReactNode;
+  /** Workspace overflow menu. */
   children: ReactNode;
+  headerVariant: "compact" | "full";
+  actionsActive: boolean;
 }
 
 /** The compact header with the workspace's project row and controls. */
@@ -32,9 +42,13 @@ export function CompactWorkspaceHeader({
   explorerToggleLabel,
   explorerToggleAccessibilityState,
   children,
+  tabSwitcher,
   serverId,
+  headerVariant,
+  actionsActive,
 }: CompactWorkspaceHeaderProps) {
   const { t } = useTranslation();
+  const actionsInBar = resolveWorkspaceActionPlacement(useWindowLayout()) === "vertical-bar";
   const projectRow = useMemo(
     () => (
       <WorkspaceHeaderProjectRow
@@ -45,9 +59,10 @@ export function CompactWorkspaceHeader({
     ),
     [subtitle, isSubtitleDistinct, serverId],
   );
-  const actions = (
-    <>
-      {children}
+  const symbols = {
+    "tab-count": tabSwitcher,
+    overflow: children,
+    explorer: (
       <WorkspaceExplorerToggle
         onPress={onToggleExplorer}
         label={explorerToggleLabel}
@@ -56,17 +71,25 @@ export function CompactWorkspaceHeader({
         accessibilityState={explorerToggleAccessibilityState}
         mobile
       />
-    </>
-  );
+    ),
+  };
+  const actions = resolveWorkspaceBarActions(headerVariant).map((symbol) => (
+    <Fragment key={symbol}>{symbols[symbol]}</Fragment>
+  ));
 
   return (
-    <CompactHeader
-      navigation="menu"
-      title={title}
-      titleTestID="workspace-header-title"
-      subtitle={projectRow}
-      loading={isLoading}
-      actions={actions}
-    />
+    <IconButtonChromeProvider value="header-island">
+      {headerVariant === "compact" ? (
+        <CompactHeader
+          navigation="menu"
+          title={title}
+          titleTestID="workspace-header-title"
+          subtitle={projectRow}
+          loading={isLoading}
+          actions={actionsInBar ? undefined : actions}
+        />
+      ) : null}
+      <WindowLayoutActions active={actionsActive}>{actions}</WindowLayoutActions>
+    </IconButtonChromeProvider>
   );
 }
diff --git a/packages/app/src/screens/workspace/scripts/index.ts b/packages/app/src/screens/workspace/scripts/index.ts
index efff482e80..bbe223f520 100644
--- a/packages/app/src/screens/workspace/scripts/index.ts
+++ b/packages/app/src/screens/workspace/scripts/index.ts
@@ -8,3 +8,5 @@ export {
   type UseWorkspaceScriptsMenuPagesInput,
   type WorkspaceScriptsMenuPages,
 } from "./workspace-scripts-menu-pages";
+
+export { useWorkspaceScriptActions } from "./use-workspace-script-actions";
diff --git a/packages/app/src/screens/workspace/scripts/use-workspace-script-actions.ts b/packages/app/src/screens/workspace/scripts/use-workspace-script-actions.ts
index fb7809990f..6752f02719 100644
--- a/packages/app/src/screens/workspace/scripts/use-workspace-script-actions.ts
+++ b/packages/app/src/screens/workspace/scripts/use-workspace-script-actions.ts
@@ -3,9 +3,9 @@ import * as Clipboard from "expo-clipboard";
 import { useMutation } from "@tanstack/react-query";
 import { useTranslation } from "react-i18next";
 import type { WorkspaceDescriptor } from "@/stores/session-store";
-import { useSessionStore } from "@/stores/session-store";
+import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
 import { useHostRuntimeSnapshot } from "@/runtime/host-runtime";
-import { useToast } from "@/contexts/toast-context";
+import { useToast } from "@/contexts/toast-api-context";
 import {
   resolveWorkspaceScriptLink,
   type WorkspaceScriptLinkKind,
@@ -34,6 +34,7 @@ export interface WorkspaceScriptActions {
 }
 
 export interface UseWorkspaceScriptActionsInput {
+  client: Pick<DaemonClient, "startWorkspaceScript" | "killTerminal"> | null;
   serverId: string;
   workspaceId: string;
   scripts: WorkspaceDescriptor["scripts"];
@@ -45,10 +46,11 @@ export interface UseWorkspaceScriptActionsInput {
  * lists them.
  *
  * A restart outlives the press that asked for it — the second half waits for the daemon to
- * report the script stopped — so mount this with whatever owns the menu, not inside a menu page
- * that unmounts when the menu closes.
+ * report the script stopped — so mount this once with the workspace screen and pass its actions to
+ * each menu surface. Header placement and menu lifetime must not own pending restarts.
  */
 export function useWorkspaceScriptActions({
+  client,
   serverId,
   workspaceId,
   scripts,
@@ -56,7 +58,6 @@ export function useWorkspaceScriptActions({
 }: UseWorkspaceScriptActionsInput): WorkspaceScriptActions {
   const { t } = useTranslation();
   const toast = useToast();
-  const client = useSessionStore((state) => state.sessions[serverId]?.client ?? null);
   const activeConnection = useHostRuntimeSnapshot(serverId)?.activeConnection ?? null;
   const preferredRouteKind = useWorkspaceServiceRoutePreferencesStore(
     (state) => state.byServerId[serverId] ?? null,
diff --git a/packages/app/src/screens/workspace/scripts/workspace-scripts-button.test.tsx b/packages/app/src/screens/workspace/scripts/workspace-scripts-button.test.tsx
index 290f424e97..dbe4b1ab92 100644
--- a/packages/app/src/screens/workspace/scripts/workspace-scripts-button.test.tsx
+++ b/packages/app/src/screens/workspace/scripts/workspace-scripts-button.test.tsx
@@ -8,6 +8,8 @@ import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import type { WorkspaceScriptPayload } from "@getpaseo/protocol/messages";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { createRoot } from "react-dom/client";
+import { ToastApiProvider } from "@/contexts/toast-api-context";
+import { useWorkspaceScriptActions } from "./use-workspace-script-actions";
 import { WorkspaceScriptsButton } from "./workspace-scripts-button";
 
 void testI18n;
@@ -50,7 +52,13 @@ const {
 
   return {
     theme: hoistedTheme,
-    startWorkspaceScriptMock: vi.fn(async () => ({ terminalId: "terminal-script-1" })),
+    startWorkspaceScriptMock: vi.fn(async () => ({
+      terminalId: "terminal-script-1",
+      requestId: "start-1",
+      workspaceId: "workspace-1",
+      scriptName: "dev",
+      error: null,
+    })),
     killTerminalMock: vi.fn(async () => ({
       terminalId: "terminal-script-1",
       success: true,
@@ -113,20 +121,6 @@ vi.mock("@/workspace-service-routes/store", async () => {
   };
 });
 
-vi.mock("@/stores/session-store", () => ({
-  useSessionStore: (selector: (state: unknown) => unknown) =>
-    selector({
-      sessions: {
-        "test-server": {
-          client: {
-            startWorkspaceScript: startWorkspaceScriptMock,
-            killTerminal: killTerminalMock,
-          },
-        },
-      },
-    }),
-}));
-
 vi.mock("@/contexts/toast-context", () => ({
   useToast: () => ({ show: vi.fn(), error: vi.fn(), copied: copiedToastMock }),
 }));
@@ -237,6 +231,34 @@ interface RenderScriptsOptions {
   hideLabels?: boolean;
 }
 
+const testToast = { show: () => () => {}, error: () => {}, copied: copiedToastMock };
+const scriptClient = {
+  startWorkspaceScript: startWorkspaceScriptMock,
+  killTerminal: killTerminalMock,
+};
+function ScriptsOwner({
+  scripts,
+  hideLabels,
+}: {
+  scripts: WorkspaceScriptPayload[];
+  hideLabels?: boolean;
+}) {
+  const actions = useWorkspaceScriptActions({
+    client: scriptClient,
+    serverId: "test-server",
+    workspaceId: "workspace-1",
+    scripts,
+  });
+  return (
+    <WorkspaceScriptsButton
+      actions={actions}
+      scripts={scripts}
+      liveTerminalIds={LIVE_TERMINAL_IDS}
+      hideLabels={hideLabels}
+    />
+  );
+}
+
 function renderScripts(
   scripts: WorkspaceScriptPayload[],
   options: RenderScriptsOptions = {},
@@ -257,13 +279,9 @@ function renderScripts(
   function element(nextScripts: WorkspaceScriptPayload[]): ReactElement {
     return (
       <QueryClientProvider client={queryClient}>
-        <WorkspaceScriptsButton
-          serverId="test-server"
-          workspaceId="workspace-1"
-          scripts={nextScripts}
-          liveTerminalIds={LIVE_TERMINAL_IDS}
-          hideLabels={options.hideLabels}
-        />
+        <ToastApiProvider api={testToast}>
+          <ScriptsOwner scripts={nextScripts} hideLabels={options.hideLabels} />
+        </ToastApiProvider>
       </QueryClientProvider>
     );
   }
diff --git a/packages/app/src/screens/workspace/scripts/workspace-scripts-button.tsx b/packages/app/src/screens/workspace/scripts/workspace-scripts-button.tsx
index 2f58dedfca..8e922ee2ab 100644
--- a/packages/app/src/screens/workspace/scripts/workspace-scripts-button.tsx
+++ b/packages/app/src/screens/workspace/scripts/workspace-scripts-button.tsx
@@ -32,19 +32,14 @@ import { HEADER_CONTROL_HEIGHT } from "@/components/ui/control-geometry";
 import { extraMutedIconColorMapping } from "@/components/ui/icon-color";
 import { ExitCodeBadge, routeLabelKey, ScriptIcon } from "./script-marks";
 import { scriptToneColorMapping } from "./script-status";
-import {
-  useWorkspaceScriptActions,
-  type WorkspaceScriptActions,
-} from "./use-workspace-script-actions";
+import type { WorkspaceScriptActions } from "./use-workspace-script-actions";
 
 type RowActionIcon = "copy" | "open" | "restart" | "start" | "stop" | "terminal";
 
 interface WorkspaceScriptsButtonProps {
-  serverId: string;
-  workspaceId: string;
+  actions: WorkspaceScriptActions;
   scripts: WorkspaceDescriptor["scripts"];
   liveTerminalIds?: readonly string[];
-  onScriptTerminalStarted?: (terminalId: string) => void;
   onViewTerminal?: (terminalId: string) => void;
   onOpenUrlInBrowserTab?: (url: string) => void;
   hideLabels?: boolean;
@@ -448,22 +443,14 @@ function ScriptRow({
 }
 
 export function WorkspaceScriptsButton({
-  serverId,
-  workspaceId,
+  actions,
   scripts,
   liveTerminalIds = [],
-  onScriptTerminalStarted,
   onViewTerminal,
   onOpenUrlInBrowserTab,
   hideLabels,
 }: WorkspaceScriptsButtonProps): ReactElement | null {
   const { t } = useTranslation();
-  const actions = useWorkspaceScriptActions({
-    serverId,
-    workspaceId,
-    scripts,
-    onScriptTerminalStarted,
-  });
   const liveTerminalIdSet = useMemo(() => new Set(liveTerminalIds), [liveTerminalIds]);
 
   const triggerStyle = useCallback(
diff --git a/packages/app/src/screens/workspace/scripts/workspace-scripts-menu-pages.tsx b/packages/app/src/screens/workspace/scripts/workspace-scripts-menu-pages.tsx
index 3d14d9faff..0dd6fe5400 100644
--- a/packages/app/src/screens/workspace/scripts/workspace-scripts-menu-pages.tsx
+++ b/packages/app/src/screens/workspace/scripts/workspace-scripts-menu-pages.tsx
@@ -18,10 +18,7 @@ import type {
 } from "@/utils/workspace-script-links";
 import { ExitCodeBadge, routeLabelKey, ScriptIcon } from "./script-marks";
 import { scriptToneColorMapping, summarizeScripts, type ScriptsSummary } from "./script-status";
-import {
-  useWorkspaceScriptActions,
-  type WorkspaceScriptActions,
-} from "./use-workspace-script-actions";
+import type { WorkspaceScriptActions } from "./use-workspace-script-actions";
 
 type WorkspaceScript = WorkspaceDescriptor["scripts"][number];
 
@@ -56,11 +53,9 @@ function scriptPageId(scriptName: string): string {
 }
 
 export interface UseWorkspaceScriptsMenuPagesInput {
-  serverId: string;
-  workspaceId: string;
+  actions: WorkspaceScriptActions;
   scripts: WorkspaceDescriptor["scripts"];
   liveTerminalIds: readonly string[];
-  onScriptTerminalStarted: (terminalId: string) => void;
   onViewTerminal: (terminalId: string) => void;
   onOpenUrlInBrowserTab: (url: string) => void;
 }
@@ -80,25 +75,16 @@ export interface WorkspaceScriptsMenuPages {
  * Every script gets a page whether or not it runs, so stopping one from its own page flips that
  * page to its stopped state instead of pulling it out from under the user.
  *
- * The actions live here rather than in a page, so call this from whatever owns the menu: a restart
- * finishes after the sheet has closed.
+ * The workspace screen owns the actions so a restart finishes across menu and header changes.
  */
 export function useWorkspaceScriptsMenuPages({
-  serverId,
-  workspaceId,
+  actions,
   scripts,
   liveTerminalIds,
-  onScriptTerminalStarted,
   onViewTerminal,
   onOpenUrlInBrowserTab,
 }: UseWorkspaceScriptsMenuPagesInput): WorkspaceScriptsMenuPages {
   const { t } = useTranslation();
-  const actions = useWorkspaceScriptActions({
-    serverId,
-    workspaceId,
-    scripts,
-    onScriptTerminalStarted,
-  });
   const summary = useMemo(() => summarizeScripts(scripts), [scripts]);
 
   const trigger = useMemo(
diff --git a/packages/app/src/screens/workspace/workspace-screen.tsx b/packages/app/src/screens/workspace/workspace-screen.tsx
index 2aa5a54bae..68810013d7 100644
--- a/packages/app/src/screens/workspace/workspace-screen.tsx
+++ b/packages/app/src/screens/workspace/workspace-screen.tsx
@@ -7,6 +7,7 @@ import {
   type InlinePathTarget,
 } from "@/assistant-file-links";
 import { useFileExplorerActions } from "@/hooks/use-file-explorer-actions";
+import { useWindowLayout, resolveWorkspaceActionPlacement } from "@/window-layout";
 import { revealWorkspaceTab } from "@/workspace-tabs/navigation";
 import type { LayoutChangeEvent } from "react-native";
 import { ExplorerSidebarDock } from "@/screens/workspace/explorer-sidebar";
@@ -62,7 +63,7 @@ import { SplitContainer } from "@/components/split-container";
 import { RetainedPanel } from "@/components/retained-panel";
 import { WorkspaceActions } from "@/git/workspace-actions";
 import { WorkspaceOpenInEditorButton } from "@/workspace/open-in-editor/button";
-import { WorkspaceScriptsButton } from "@/screens/workspace/scripts";
+import { WorkspaceScriptsButton, useWorkspaceScriptActions } from "@/screens/workspace/scripts";
 import { ImportSessionSheet } from "@/components/import-session-sheet";
 import { useNavigateToImportedAgent } from "@/hooks/use-import-session";
 import { useToast } from "@/contexts/toast-context";
@@ -502,6 +503,7 @@ function WorkspaceHeaderTitleBar({
   onCopyBranchName,
   onOpenSetupTab,
 }: WorkspaceHeaderTitleBarProps) {
+  const actionsInBar = resolveWorkspaceActionPlacement(useWindowLayout()) === "vertical-bar";
   return (
     <View style={styles.headerTitleContainer}>
       {isLoading ? (
@@ -518,18 +520,20 @@ function WorkspaceHeaderTitleBar({
           />
         </View>
       )}
-      <View style={styles.compactHeaderMenuCluster}>
-        <WorkspaceHeaderMenuDesktop
-          currentBranchName={currentBranchName}
-          showWorkspaceSetup={showWorkspaceSetup}
-          importAgentDisabled={importAgentDisabled}
-          copyPathDisabled={copyPathDisabled}
-          onOpenImportSheet={onOpenImportSheet}
-          onCopyWorkspacePath={onCopyWorkspacePath}
-          onCopyBranchName={onCopyBranchName}
-          onOpenSetupTab={onOpenSetupTab}
-        />
-      </View>
+      {actionsInBar ? null : (
+        <View style={styles.compactHeaderMenuCluster}>
+          <WorkspaceHeaderMenuDesktop
+            currentBranchName={currentBranchName}
+            showWorkspaceSetup={showWorkspaceSetup}
+            importAgentDisabled={importAgentDisabled}
+            copyPathDisabled={copyPathDisabled}
+            onOpenImportSheet={onOpenImportSheet}
+            onCopyWorkspacePath={onCopyWorkspacePath}
+            onCopyBranchName={onCopyBranchName}
+            onOpenSetupTab={onOpenSetupTab}
+          />
+        </View>
+      )}
     </View>
   );
 }
@@ -1022,8 +1026,11 @@ function WorkspaceScreenContent({
 }: WorkspaceScreenContentProps) {
   const { t } = useTranslation();
   const _insets = useSafeAreaInsets();
+  const workspaceActionsInBar =
+    resolveWorkspaceActionPlacement(useWindowLayout()) === "vertical-bar";
   const toast = useToast();
   const isMobile = useIsCompactFormFactor();
+  const workspacePanelActive = usePanelStore((state) => state.mobilePanel.target === "agent");
   const canRenderDesktopPaneSplits = supportsDesktopPaneSplits();
   const layoutMode = useWorkspaceLayoutStore((state) => state.layoutMode);
   const hasMacTrafficLights = useHasWindowChromeObstruction("top-left");
@@ -1213,6 +1220,13 @@ function WorkspaceScreenContent({
     onTerminalCreateQueued: handleTerminalCreateQueued,
     onTerminalCreateFailed: handleTerminalCreateFailed,
   });
+  const scriptActions = useWorkspaceScriptActions({
+    client,
+    serverId: normalizedServerId,
+    workspaceId: normalizedWorkspaceId,
+    scripts: workspaceScripts,
+    onScriptTerminalStarted: handleScriptTerminalStarted,
+  });
   const { archiveAgent } = useArchiveAgent();
 
   const { checkoutQuery, isCheckoutStatusLoading } = useWorkspaceCheckoutStatus({
@@ -3189,11 +3203,9 @@ function WorkspaceScreenContent({
         <PluginHeaderButtons serverId={normalizedServerId} workspaceId={normalizedWorkspaceId} />
         {workspaceDescriptor && workspaceDescriptor.scripts.length > 0 ? (
           <WorkspaceScriptsButton
-            serverId={normalizedServerId}
-            workspaceId={normalizedWorkspaceId}
+            actions={scriptActions}
             scripts={workspaceDescriptor.scripts}
             liveTerminalIds={liveTerminalIds}
-            onScriptTerminalStarted={handleScriptTerminalStarted}
             onViewTerminal={handleViewScriptTerminal}
             onOpenUrlInBrowserTab={handleOpenUrlInBrowserTab}
             hideLabels
@@ -3211,15 +3223,17 @@ function WorkspaceScreenContent({
         {workspaceDirectory ? (
           <>
             <WorkspaceActions serverId={normalizedServerId} cwd={workspaceDirectory} />
-            <WorkspaceHeaderExplorerToggle
-              owner={explorerToggleOwner}
-              onPress={handleToggleExplorerSidebar}
-              label={explorerSidebarToggleLabel}
-              tooltipLabel={t("workspace.tabs.explorerSidebar.toggle")}
-              tooltipKeys={EXPLORER_TOGGLE_KEYS}
-              style={styles.compactHeaderActionButton}
-              accessibilityState={explorerSidebarToggleAccessibilityState}
-            />
+            {workspaceActionsInBar ? null : (
+              <WorkspaceHeaderExplorerToggle
+                owner={explorerToggleOwner}
+                onPress={handleToggleExplorerSidebar}
+                label={explorerSidebarToggleLabel}
+                tooltipLabel={t("workspace.tabs.explorerSidebar.toggle")}
+                tooltipKeys={EXPLORER_TOGGLE_KEYS}
+                style={styles.compactHeaderActionButton}
+                accessibilityState={explorerSidebarToggleAccessibilityState}
+              />
+            )}
           </>
         ) : null}
       </View>
@@ -3231,13 +3245,14 @@ function WorkspaceScreenContent({
       workspaceDirectory,
       activeFileLocation,
       liveTerminalIds,
-      handleScriptTerminalStarted,
+      scriptActions,
       handleViewScriptTerminal,
       handleOpenUrlInBrowserTab,
       handleToggleExplorerSidebar,
       explorerSidebarToggleLabel,
       explorerSidebarToggleAccessibilityState,
       explorerToggleOwner,
+      workspaceActionsInBar,
       t,
     ],
   );
@@ -3343,104 +3358,113 @@ function WorkspaceScreenContent({
   );
   const compactHeaderScripts = useMemo(
     () => ({
-      serverId: normalizedServerId,
-      workspaceId: normalizedWorkspaceId,
+      actions: scriptActions,
       scripts: workspaceScripts,
       liveTerminalIds,
-      onScriptTerminalStarted: handleScriptTerminalStarted,
       onViewTerminal: handleViewScriptTerminal,
       onOpenUrlInBrowserTab: handleOpenUrlInBrowserTab,
     }),
     [
-      normalizedServerId,
-      normalizedWorkspaceId,
       workspaceScripts,
       liveTerminalIds,
-      handleScriptTerminalStarted,
+      scriptActions,
       handleViewScriptTerminal,
       handleOpenUrlInBrowserTab,
     ],
   );
-  const compactWorkspaceHeader = useMemo(
-    () =>
-      isMobile ? (
-        <CompactWorkspaceHeader
-          isLoading={isWorkspaceHeaderLoading}
-          title={workspaceHeaderTitle}
-          subtitle={workspaceHeaderSubtitle}
-          isSubtitleDistinct={isWorkspaceHeaderSubtitleDistinct}
-          serverId={normalizedServerId}
-          onToggleExplorer={handleToggleExplorerSidebar}
-          explorerToggleLabel={explorerSidebarToggleLabel}
-          explorerToggleAccessibilityState={explorerSidebarToggleAccessibilityState}
-        >
-          <MobileWorkspaceTabSwitcher
-            tabs={tabs}
-            activeTabKey={activeTabKey}
-            normalizedServerId={normalizedServerId}
-            normalizedWorkspaceId={normalizedWorkspaceId}
-            onSelectSwitcherTab={handleSelectSwitcherTab}
-            createTerminalDisabled={createTerminalDisabled}
-            onCreateDraftTab={handleCreateDraftTab}
-            onCreateTerminal={handleCreateTerminal}
-            onCopyResumeCommand={handleCopyResumeCommand}
-            onCopyAgentId={handleCopyAgentId}
-            onCopyTerminalId={handleCopyTerminalId}
-            onCopyFilePath={handleCopyFilePath}
-            onReloadAgent={handleReloadAgent}
-            onRenameTab={handleRenameTab}
-            onCloseTab={handleCloseTabById}
-            onCloseTabsAbove={handleCloseTabsToLeft}
-            onCloseTabsBelow={handleCloseTabsToRight}
-            onCloseOtherTabs={handleCloseOtherTabs}
-          />
-          <WorkspaceHeaderMenuMobile
-            normalizedServerId={normalizedServerId}
-            normalizedWorkspaceId={normalizedWorkspaceId}
-            scripts={compactHeaderScripts}
-            currentBranchName={currentBranchName}
-            showWorkspaceSetup={showWorkspaceSetup}
-            showCreateBrowserTab={showCreateBrowserTab}
-            createTerminalDisabled={createTerminalDisabled}
-            importAgentDisabled={!canOpenImportSheet}
-            copyPathDisabled={!workspaceDirectory}
-            onCreateTerminalWithProfile={handleCreateTerminalWithProfile}
-            onCreateBrowser={handleCreateBrowserTab}
-            onOpenImportSheet={openImportSheet}
-            onCopyWorkspacePath={handleCopyWorkspacePath}
-            onCopyBranchName={handleCopyBranchName}
-            onOpenSetupTab={handleOpenSetupTab}
-          />
-        </CompactWorkspaceHeader>
-      ) : null,
+  const workspaceTabSwitcher = useMemo(
+    () => (
+      <MobileWorkspaceTabSwitcher
+        tabs={tabs}
+        activeTabKey={activeTabKey}
+        normalizedServerId={normalizedServerId}
+        normalizedWorkspaceId={normalizedWorkspaceId}
+        onSelectSwitcherTab={handleSelectSwitcherTab}
+        createTerminalDisabled={createTerminalDisabled}
+        onCreateDraftTab={handleCreateDraftTab}
+        onCreateTerminal={handleCreateTerminal}
+        onCopyResumeCommand={handleCopyResumeCommand}
+        onCopyAgentId={handleCopyAgentId}
+        onCopyTerminalId={handleCopyTerminalId}
+        onCopyFilePath={handleCopyFilePath}
+        onReloadAgent={handleReloadAgent}
+        onRenameTab={handleRenameTab}
+        onCloseTab={handleCloseTabById}
+        onCloseTabsAbove={handleCloseTabsToLeft}
+        onCloseTabsBelow={handleCloseTabsToRight}
+        onCloseOtherTabs={handleCloseOtherTabs}
+      />
+    ),
     [
       activeTabKey,
+      createTerminalDisabled,
+      handleCloseOtherTabs,
+      handleCloseTabById,
+      handleCloseTabsToLeft,
+      handleCloseTabsToRight,
+      handleCopyAgentId,
+      handleCopyFilePath,
+      handleCopyResumeCommand,
+      handleCopyTerminalId,
+      handleCreateDraftTab,
+      handleCreateTerminal,
+      handleReloadAgent,
+      handleRenameTab,
+      handleSelectSwitcherTab,
+      normalizedServerId,
+      normalizedWorkspaceId,
+      tabs,
+    ],
+  );
+  const compactWorkspaceHeader = useMemo(
+    () => (
+      <CompactWorkspaceHeader
+        headerVariant={isMobile ? "compact" : "full"}
+        actionsActive={isRouteFocused && (!isMobile || workspacePanelActive)}
+        isLoading={isWorkspaceHeaderLoading}
+        title={workspaceHeaderTitle}
+        subtitle={workspaceHeaderSubtitle}
+        isSubtitleDistinct={isWorkspaceHeaderSubtitleDistinct}
+        serverId={normalizedServerId}
+        onToggleExplorer={handleToggleExplorerSidebar}
+        explorerToggleLabel={explorerSidebarToggleLabel}
+        explorerToggleAccessibilityState={explorerSidebarToggleAccessibilityState}
+        tabSwitcher={workspaceTabSwitcher}
+      >
+        <WorkspaceHeaderMenuMobile
+          normalizedServerId={normalizedServerId}
+          normalizedWorkspaceId={normalizedWorkspaceId}
+          scripts={compactHeaderScripts}
+          currentBranchName={currentBranchName}
+          showWorkspaceSetup={showWorkspaceSetup}
+          showCreateBrowserTab={showCreateBrowserTab}
+          createTerminalDisabled={createTerminalDisabled}
+          importAgentDisabled={!canOpenImportSheet}
+          copyPathDisabled={!workspaceDirectory}
+          onCreateTerminalWithProfile={handleCreateTerminalWithProfile}
+          onCreateBrowser={handleCreateBrowserTab}
+          onOpenImportSheet={openImportSheet}
+          onCopyWorkspacePath={handleCopyWorkspacePath}
+          onCopyBranchName={handleCopyBranchName}
+          onOpenSetupTab={handleOpenSetupTab}
+        />
+      </CompactWorkspaceHeader>
+    ),
+    [
       canOpenImportSheet,
       compactHeaderScripts,
       createTerminalDisabled,
       currentBranchName,
       explorerSidebarToggleAccessibilityState,
       explorerSidebarToggleLabel,
-      handleCloseOtherTabs,
-      handleCloseTabById,
-      handleCloseTabsToLeft,
-      handleCloseTabsToRight,
-      handleCopyAgentId,
       handleCopyBranchName,
-      handleCopyFilePath,
-      handleCopyResumeCommand,
-      handleCopyTerminalId,
       handleCopyWorkspacePath,
       handleCreateBrowserTab,
-      handleCreateDraftTab,
-      handleCreateTerminal,
       handleCreateTerminalWithProfile,
       handleOpenSetupTab,
-      handleReloadAgent,
-      handleRenameTab,
-      handleSelectSwitcherTab,
       handleToggleExplorerSidebar,
       isMobile,
+      isRouteFocused,
       isWorkspaceHeaderLoading,
       isWorkspaceHeaderSubtitleDistinct,
       normalizedServerId,
@@ -3448,10 +3472,11 @@ function WorkspaceScreenContent({
       openImportSheet,
       showCreateBrowserTab,
       showWorkspaceSetup,
-      tabs,
       workspaceDirectory,
       workspaceHeaderSubtitle,
       workspaceHeaderTitle,
+      workspacePanelActive,
+      workspaceTabSwitcher,
     ],
   );
   const desktopSplitContent = useMemo(() => {
@@ -3559,6 +3584,7 @@ function WorkspaceScreenContent({
     </View>
   ) : (
     <View style={styles.centerColumn}>
+      {compactWorkspaceHeader}
       {rendersDesktopSplitContent ? null : renderWorkspaceScreenHeader()}
 
       {shouldRenderDesktopPaneFallback ? (
diff --git a/packages/app/src/window-layout/actions.browser.test.tsx b/packages/app/src/window-layout/actions.browser.test.tsx
new file mode 100644
index 0000000000..a7f3a4a75e
--- /dev/null
+++ b/packages/app/src/window-layout/actions.browser.test.tsx
@@ -0,0 +1,95 @@
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { PortalProvider } from "@gorhom/portal";
+import { afterEach, expect, it, vi } from "vitest";
+import { Text } from "react-native";
+import { page } from "vitest/browser";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { HeaderToggleButton } from "@/components/headers/header-toggle-button";
+import type { WindowLayout } from "./model";
+import { WindowLayoutContext } from "./context";
+import { WindowLayoutActions, WindowLayoutActionsHost } from "./actions";
+import { WindowLayoutDivisionGap } from "./surface";
+import { lightTheme } from "@/styles/theme";
+
+vi.stubGlobal("React", React);
+const layout = { sidebarWidth: 465, gap: 21, contentWidth: 381 };
+const geometry: WindowLayout = {
+  bounds: { x: 0, y: 0, width: window.innerWidth, height: window.innerHeight },
+  verticalBarEdge: "trailing",
+  verticalBar: { x: 20, y: 20, width: 44, height: 400 },
+  divisions: [],
+};
+const container = document.createElement("div");
+document.body.appendChild(container);
+const root = createRoot(container);
+afterEach(() => {
+  act(() => root.render(null));
+});
+
+it("paints the reserved division with the sidebar surface", () => {
+  act(() =>
+    root.render(<WindowLayoutDivisionGap layout={layout} sidebarVisible compact={false} />),
+  );
+  const gap = container.firstElementChild as HTMLElement;
+  const expected = document.createElement("div");
+  expected.style.backgroundColor = lightTheme.colors.surfaceSidebar;
+  expect(getComputedStyle(gap).backgroundColor).toBe(expected.style.backgroundColor);
+  expect(getComputedStyle(gap).borderRightWidth).toBe("1px");
+  expect(gap.getBoundingClientRect().width).toBe(21);
+});
+
+const explorerState = { expanded: false };
+const noKeys: [] = [];
+const noop = () => {};
+
+it("preserves circular explorer chrome and closes a portaled menu when actions become inactive", async () => {
+  async function renderActions(active: boolean) {
+    await act(async () =>
+      root.render(
+        <PortalProvider>
+          <WindowLayoutContext.Provider value={geometry}>
+            <WindowLayoutActionsHost />
+            <WindowLayoutActions active={active}>
+              <HeaderToggleButton
+                onPress={noop}
+                accessibilityRole="button"
+                accessibilityLabel="Explorer"
+                tooltipLabel="Explorer"
+                tooltipSide="left"
+                tooltipKeys={noKeys}
+                accessibilityState={explorerState}
+              >
+                <Text>Explorer</Text>
+              </HeaderToggleButton>
+              <DropdownMenu>
+                <DropdownMenuTrigger accessibilityRole="button" accessibilityLabel="Bar menu">
+                  <Text>Menu</Text>
+                </DropdownMenuTrigger>
+                <DropdownMenuContent>
+                  <DropdownMenuItem onSelect={noop}>Bar menu item</DropdownMenuItem>
+                </DropdownMenuContent>
+              </DropdownMenu>
+            </WindowLayoutActions>
+          </WindowLayoutContext.Provider>
+        </PortalProvider>,
+      ),
+    );
+  }
+  await renderActions(true);
+  const explorer = container.querySelector('[aria-label="Explorer"]') as HTMLElement;
+  expect(getComputedStyle(explorer).borderRadius).toBe(`${lightTheme.borderRadius.full}px`);
+  await page.getByRole("button", { name: "Bar menu", exact: true }).click();
+  await expect.element(page.getByRole("menuitem", { name: "Bar menu item" })).toBeVisible();
+  await renderActions(false);
+  await expect.poll(() => document.querySelectorAll('[role="menuitem"]').length).toBe(0);
+  expect(
+    container.querySelector('[data-testid="workspace-vertical-actions"]')?.getBoundingClientRect()
+      .height,
+  ).toBe(0);
+});
diff --git a/packages/app/src/window-layout/actions.tsx b/packages/app/src/window-layout/actions.tsx
new file mode 100644
index 0000000000..06fcf57633
--- /dev/null
+++ b/packages/app/src/window-layout/actions.tsx
@@ -0,0 +1,50 @@
+import type { ReactNode } from "react";
+import { Portal, PortalHost } from "@gorhom/portal";
+import { StyleSheet, View } from "react-native";
+import { RetainedPanelActivity } from "@/components/retained-panel";
+import { IconButtonChromeProvider } from "@/components/ui/icon-button-chrome";
+import { useWindowLayout } from "./context";
+import { resolveWorkspaceActionPlacement } from "./model";
+
+const HOST = "window-layout-actions";
+
+export function WindowLayoutActionsHost() {
+  return <PortalHost name={HOST} />;
+}
+
+/** The native bar guide is in window coordinates, so the host lives at the window root. */
+export function WindowLayoutActions({
+  children,
+  active,
+}: {
+  children: ReactNode;
+  active: boolean;
+}) {
+  const layout = useWindowLayout();
+  if (resolveWorkspaceActionPlacement(layout) !== "vertical-bar" || !layout?.verticalBar) {
+    return null;
+  }
+  const bar = layout.verticalBar;
+  return (
+    <Portal hostName={HOST}>
+      <View
+        testID="workspace-vertical-actions"
+        style={[
+          styles.bar,
+          { left: bar.x, top: bar.y, width: bar.width, height: bar.height },
+          !active && styles.hidden,
+        ]}
+        pointerEvents="box-none"
+      >
+        <RetainedPanelActivity active={active}>
+          <IconButtonChromeProvider value="header-island">{children}</IconButtonChromeProvider>
+        </RetainedPanelActivity>
+      </View>
+    </Portal>
+  );
+}
+
+const styles = StyleSheet.create({
+  hidden: { display: "none" },
+  bar: { position: "absolute", alignItems: "center", gap: 8 },
+});
diff --git a/packages/app/src/window-layout/context.ts b/packages/app/src/window-layout/context.ts
new file mode 100644
index 0000000000..e2d0246a92
--- /dev/null
+++ b/packages/app/src/window-layout/context.ts
@@ -0,0 +1,15 @@
+import { createContext, useContext } from "react";
+import { useWindowDimensions } from "react-native";
+import type { WindowLayout } from "./model";
+
+export const WindowLayoutContext = createContext<WindowLayout | null>(null);
+
+export function useWindowLayout(): WindowLayout | null {
+  const layout = useContext(WindowLayoutContext);
+  const { width, height } = useWindowDimensions();
+  return layout &&
+    Math.abs(layout.bounds.width - width) <= 0.5 &&
+    Math.abs(layout.bounds.height - height) <= 0.5
+    ? layout
+    : null;
+}
diff --git a/packages/app/src/window-layout/index.ios.tsx b/packages/app/src/window-layout/index.ios.tsx
new file mode 100644
index 0000000000..237c9c8114
--- /dev/null
+++ b/packages/app/src/window-layout/index.ios.tsx
@@ -0,0 +1,43 @@
+import { useCallback, useState, type ReactNode } from "react";
+import { StyleSheet, View, type NativeSyntheticEvent, type ViewProps } from "react-native";
+import { requireNativeViewManager } from "expo-modules-core";
+import { WindowLayoutContext } from "./context";
+import type { WindowLayout } from "./model";
+
+export { useWindowLayout } from "./context";
+export { WindowLayoutActions, WindowLayoutActionsHost } from "./actions";
+export { WindowLayoutSurface, WindowLayoutDivisionGap } from "./surface";
+export {
+  resolveDesktopDivisionLayout,
+  resolveWorkspaceActionPlacement,
+  resolveWorkspaceBarActions,
+} from "./model";
+export type { DesktopDivisionLayout, WindowLayout, WindowLayoutRect } from "./model";
+
+const GeometryProbe = requireNativeViewManager<
+  ViewProps & {
+    onGeometryChange: (event: NativeSyntheticEvent<WindowLayout>) => void;
+  }
+>("PaseoWindowLayout");
+
+export function WindowLayoutProvider({ children }: { children: ReactNode }) {
+  const [geometry, setGeometry] = useState<WindowLayout | null>(null);
+  const onGeometryChange = useCallback(
+    (event: NativeSyntheticEvent<WindowLayout>) => setGeometry(event.nativeEvent),
+    [],
+  );
+  return (
+    <WindowLayoutContext.Provider value={geometry}>
+      <View style={styles.root}>
+        <GeometryProbe
+          pointerEvents="none"
+          style={StyleSheet.absoluteFill}
+          onGeometryChange={onGeometryChange}
+        />
+        {children}
+      </View>
+    </WindowLayoutContext.Provider>
+  );
+}
+
+const styles = StyleSheet.create({ root: { flex: 1 } });
diff --git a/packages/app/src/window-layout/index.tsx b/packages/app/src/window-layout/index.tsx
new file mode 100644
index 0000000000..c884d3e987
--- /dev/null
+++ b/packages/app/src/window-layout/index.tsx
@@ -0,0 +1,15 @@
+import type { ReactNode } from "react";
+
+export { useWindowLayout } from "./context";
+export { WindowLayoutActions, WindowLayoutActionsHost } from "./actions";
+export { WindowLayoutSurface, WindowLayoutDivisionGap } from "./surface";
+export {
+  resolveDesktopDivisionLayout,
+  resolveWorkspaceActionPlacement,
+  resolveWorkspaceBarActions,
+} from "./model";
+export type { DesktopDivisionLayout, WindowLayout, WindowLayoutRect } from "./model";
+
+export function WindowLayoutProvider({ children }: { children: ReactNode }) {
+  return children;
+}
diff --git a/packages/app/src/window-layout/model.ts b/packages/app/src/window-layout/model.ts
new file mode 100644
index 0000000000..3e8d5b82ec
--- /dev/null
+++ b/packages/app/src/window-layout/model.ts
@@ -0,0 +1,65 @@
+export interface WindowLayoutRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface WindowLayout {
+  bounds: WindowLayoutRect;
+  verticalBarEdge: "none" | "leading" | "trailing";
+  verticalBar: WindowLayoutRect | null;
+  divisions: WindowLayoutRect[];
+}
+
+export interface DesktopDivisionLayout {
+  sidebarWidth: number;
+  gap: number;
+  contentWidth: number;
+}
+
+export function resolveWorkspaceActionPlacement(
+  layout: WindowLayout | null,
+): "header" | "vertical-bar" {
+  return layout?.verticalBarEdge === "trailing" && layout.verticalBar !== null
+    ? "vertical-bar"
+    : "header";
+}
+
+export function resolveWorkspaceBarActions(
+  headerVariant: "compact" | "full",
+): readonly ("tab-count" | "overflow" | "explorer")[] {
+  return headerVariant === "compact"
+    ? ["tab-count", "overflow", "explorer"]
+    : ["overflow", "explorer"];
+}
+
+/** One book-like partition owns allocation; horizontal folds retain the normal flow. */
+export function resolveDesktopDivisionLayout(input: {
+  geometry: WindowLayout | null;
+  windowWidth: number;
+  windowHeight: number;
+  leftInset: number;
+  rightInset: number;
+}): DesktopDivisionLayout | null {
+  const { geometry, windowWidth, windowHeight, leftInset, rightInset } = input;
+  if (
+    !geometry ||
+    Math.abs(geometry.bounds.width - windowWidth) > 0.5 ||
+    Math.abs(geometry.bounds.height - windowHeight) > 0.5
+  )
+    return null;
+  const divisions = geometry.divisions.filter(
+    (frame) =>
+      frame.width > 0 &&
+      frame.height > frame.width &&
+      frame.y < windowHeight &&
+      frame.y + frame.height > 0,
+  );
+  if (divisions.length !== 1) return null;
+  const division = divisions[0];
+  const sidebarWidth = division.x - leftInset;
+  const contentWidth = windowWidth - rightInset - division.x - division.width;
+  if (sidebarWidth <= 0 || contentWidth <= 0) return null;
+  return { sidebarWidth, gap: division.width, contentWidth };
+}
diff --git a/packages/app/src/window-layout/surface.tsx b/packages/app/src/window-layout/surface.tsx
new file mode 100644
index 0000000000..e9645c799e
--- /dev/null
+++ b/packages/app/src/window-layout/surface.tsx
@@ -0,0 +1,64 @@
+import { useMemo, type ReactNode } from "react";
+import { View, type StyleProp, type ViewStyle } from "react-native";
+import { StyleSheet } from "react-native-unistyles";
+import { SafeAreaInsetsContext, useSafeAreaInsets } from "react-native-safe-area-context";
+import { useWindowLayout } from "./context";
+import { resolveWorkspaceActionPlacement, type DesktopDivisionLayout } from "./model";
+
+/** Consume horizontal safe areas once, including compact content beside a vertical bar. */
+export function WindowLayoutSurface({
+  children,
+  compact,
+  style,
+}: {
+  children: ReactNode;
+  compact: boolean;
+  style: StyleProp<ViewStyle>;
+}) {
+  const insets = useSafeAreaInsets();
+  const usesBar = resolveWorkspaceActionPlacement(useWindowLayout()) === "vertical-bar";
+  const surfaceStyle = useMemo(
+    () => [
+      style,
+      (!compact || usesBar) && { paddingLeft: insets.left, paddingRight: insets.right },
+    ],
+    [style, compact, usesBar, insets.left, insets.right],
+  );
+  const contentInsets = useMemo(
+    () => (compact && usesBar ? { ...insets, left: 0, right: 0 } : insets),
+    [compact, usesBar, insets],
+  );
+  return (
+    <View style={surfaceStyle}>
+      <SafeAreaInsetsContext.Provider value={contentInsets}>
+        {children}
+      </SafeAreaInsetsContext.Provider>
+    </View>
+  );
+}
+
+export function WindowLayoutDivisionGap({
+  layout,
+  sidebarVisible,
+  compact,
+}: {
+  layout: DesktopDivisionLayout | null;
+  sidebarVisible: boolean;
+  compact: boolean;
+}) {
+  const style = useMemo(
+    () => ({
+      width: layout ? layout.gap + (sidebarVisible ? 0 : layout.sidebarWidth) : 0,
+    }),
+    [layout, sidebarVisible],
+  );
+  return !compact && layout ? <View style={[styles.divisionGap, style]} /> : null;
+}
+
+const styles = StyleSheet.create((theme) => ({
+  divisionGap: {
+    backgroundColor: theme.colors.surfaceSidebar,
+    borderRightWidth: 1,
+    borderRightColor: theme.colors.border,
+  },
+}));
diff --git a/packages/app/test-stubs/react-native-unistyles.ts b/packages/app/test-stubs/react-native-unistyles.ts
index 5f37c3eaf8..38a86c7567 100644
--- a/packages/app/test-stubs/react-native-unistyles.ts
+++ b/packages/app/test-stubs/react-native-unistyles.ts
@@ -1,4 +1,5 @@
 import { lightHighlightColors } from "@getpaseo/highlight";
+import { lightTheme } from "../src/styles/theme";
 
 const testTheme = {
   colorScheme: "light",
@@ -26,6 +27,7 @@ const testTheme = {
     surface1: "#fafafa",
     surface2: "#f4f4f5",
     surface3: "#e4e4e7",
+    surfaceSidebar: lightTheme.colors.surfaceSidebar,
     border: "#e4e4e7",
     borderAccent: "#a1a1aa",
     palette: {

From 4f7813d3aafdb5f6cdcf5453d0128c1156f80e60 Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Wed, 4 Nov 2026 17:21:31 +0700
Subject: [PATCH 04/29] Keep the tapped line in place when chat disclosures
 expand or collapse, with the native timeline on LegendList (#8717)

* Keep a disclosure's trigger in place on web

Expanding or collapsing a turn summary, tool-call group, tool call details
or todo badge now holds the row that owns the trigger. Rows inside the
timeline get a disclosure context; each toggle runs its state change through
`useDisclosureHold()`, and the viewport's new `holdRow(rowId, apply)` replaces
`holdReadingPosition()`.

On web the hold pins the reading anchor to that row, stops following output,
and resumes following when the change leaves the list at its end. Native keeps
its previous behaviour (detach, then apply) until the anchored toggle lands.

* Render the native chat timeline with LegendList in forward order

The native timeline was an inverted FlatList. Disclosure toggles moved their
trigger, and a cold open settled visibly. It is now a forward-order LegendList
that stays virtualized, and one owner moves the scroll offset at a time:

- Before placement: LegendList's initial scroll, behind its hidden reveal.
- While following: the end pin (native-end-pin.tsx). This is a zero-height first
  child at the bottom of the content, which native maintainVisibleContentPosition
  keeps in place. A content shrink or growth never scrolls from JS; only a
  viewport resize or an explicit jump does.
- During a disclosure hold and while detached: LegendList MVCP with
  shouldRestorePosition (native-disclosure-hold.ts), so a toggle keeps its
  trigger at the same y and paints one layout change.
- Every newly mounted row starts at a per-kind estimate (new-row-estimates.ts).

PaseoScrollView defers React Native's content clamp while MVCP is set. A shrink
below an unmoved anchor no longer draws a frame past the end (RN #58578,
PR #58695). VisibleContentPositionClampTest covers this.

LegendList 3.7.1 patch, one "Paseo patch" comment per hunk:
- The content height comes from React state on the new architecture.
- Rows get a per-row size estimate.
- The MVCP anchor lock runs on native too. Upstream gated it to web in d24a9d93
  without a native reason. Without the lock, the size pass for prepended history
  re-anchors on a prepended row and moves the rows on screen. Native ends the
  lock when its row leaves the view, not on the 300 ms clock.
- Header and footer reveal together with the rows.
- Only lists that keep their end preserve the initial end.
- A remeasure within one pixel plus the 1/8 dp floor of the known size is
  noise. Upstream compares the raw size with the floored one, so the live
  turn's assistant row (1380 -> 1381 px) read as a resize and moved every row
  a frame after the reveal.
- The Android silent initial scroll retry sends its 1 dp nudge and the return
  to the target in one task. Upstream returns on the next frame, but its 16 ms
  check can finish the scroll first and cancel that frame, so the list revealed
  3 px short of its end and moved into place a frame later.
- The top-padding shrink hold applies on iOS only.

Android, emulator. Evidence is in .artifacts/legend-impl.
- J1, J2 at the end, J3, J4, J5, J6, J7: pass.
- J2 while streaming: not reachable on the Ten second stream fixture; its turns
  never fold.
- J8: no blank frames over 10 fresh flings, at host load 32-37.

J4: still. Before these two hunks, 6 of 7 cold opens moved every row one frame
after the reveal. After them, 9 valid cold opens show no shift. 5 of those
were traced through the nudge path. Runs that hit the dev client's startup
SIGSEGV in MountingCoordinator::pullTransaction were left out. That crash is
in the emulator's dropbox from before this work.

* Revise a history row when its turn summary line changes

LegendList renders a row again only when its item changes. The forward-order
timeline in d1f2ae352 folds a finished turn into its host user message, but the
host's item does not change when the fold appears, so a turn that folded live
lost its summary line until something else revised the row.

collapseTurns now reports the hosts whose summary line appeared, changed or went
away since the previous fold (updatedHostIds), and the history row revision
treats them as changed content.

* Stop following the end while a user scroll owns the viewport

The bottom anchor controller kept sticky-bottom for the whole of a drag and its momentum and only
decided at the end. While it is sticky the native list mounts the end pin, so a drag started during
a stream had every new line move the rows under the finger: on the iOS simulator the offset jumped
by each line's height (+22, +35, +22 pt) mid-drag, and Android does the same with the same code.

beginUserScroll now detaches. endUserScroll resumes following when the gesture ends at the end
(scrolling there without animation) and otherwise stays detached and drops any pending anchor, as
before. The re-stick is not animated: on Android a line that mounts during a smooth scroll cancels
it, and the list then followed 40 pt short of the end until the controller detached it.

Measured after the change, frame by frame:
- iOS and Android, drag up mid-stream: the content tracks the finger and momentum with no line
  steps; the stream grows below; tapping the pill re-sticks and follows again.
- A short drag at the end, mid-stream: following resumes; the release lands on the end in one
  frame (the drag distance, here 8 pt on iOS and 21 dp on Android).

A line already mounting when the drag begins can still move the rows once in its first frame,
because the detach reaches native one commit after the touch.

* Correct the iOS scroll view under maintainVisibleContentPosition

Phase 2 of the LegendList timeline. The native timeline relies on maintainVisibleContentPosition
for the end pin and the disclosure hold, and React Native 0.86 on iOS gets two cases wrong.
modules/paseo-scroll now registers PaseoScrollViewComponentView, a subclass of
RCTScrollViewComponentView, for the iOS scroll view, like PaseoScrollView on Android.

- A mount that removes its own anchor: detaching removes the end pin in the same mount that opens
  the tapped disclosure, and the offset jumped by the removed view's frame. The subclass keeps the
  offset when the anchor's tag is no longer registered, the check React Native 0.88 adds in
  https://github.com/react/react-native/pull/57294. That PR's extra superview check is not copied
  because it skips anchors detached by removeClippedSubviews
  (https://github.com/react/react-native/issues/58910).
- A shrink at the end: UIKit clamps the offset to the new end during the mount, then React Native
  adds the anchor's movement, so a turn folding while following landed above the end
  (https://github.com/react/react-native/issues/58578). The subclass restores the pre-mount offset
  for the adjustment and clamps after it, as
  https://github.com/react/react-native/pull/58695 does.

The dev client was rebuilt with the module. Verified on the iPhone 16 Pro simulator, frame by frame:
the summary far up and the latest turn's summary while following each keep the trigger at 0 px
with one layout change per toggle, the todo card the same, the cold open lands still, older
history pages keep the visible rows in place, and the keyboard, send-time shrink and streaming
stay pinned to the end.

Freshly mounted markdown on iOS paints one frame after its layout, because enriched-markdown
renders asynchronously (https://github.com/software-mansion/enriched-markdown/issues/1131). A
synchronous first render removed that frame but raised fling frame time at p90 and p99, so it is
not part of this change.

docs/agent-stream-disclosure.md now describes the clamp correction on both platforms.

* Keep the rows under the finger at a drag's start and its release

Two one-frame row movements remained around a user scroll while the timeline streams.

A drag's first frames. The end pin stays mounted until JS stops following, one round trip after
the drag begins, so a line mounting in those frames scrolled the rows under the finger by its
height. Both scroll view subclasses now skip the content-position correction while the user drags
and the anchor is the end pin, which they recognise by its native ID ("paseo-end-pin"). Android
overrides scrollToPreservingMomentum, the position keeper's only scroll call, from the begin-drag
event until the finger lifts; iOS skips the adjustment while the scroll view is dragging. The skip
is limited to the pin: LegendList's own anchoring for the detached list also uses the native
correction, and a history page landing mid-drag needs it. It starts at the drag rather than at
touch-down: a tap or long press while following would otherwise leave the list stranded short of
its end, still following, once the finger lifts.

The release. A gesture ending within 32 pt of the end re-stuck with an instant scroll, a snap of up
to 56 px. Following now resumes only when the finger lifts at or past the end, or momentum stops
there, within 1 px, the distance web resumes at (strategy-web.tsx). Anything else stays detached with the
pill. The check runs when the gesture is decided, so output that arrived below meanwhile counts. A
release past the end counts as at the end: on iOS it bounces back, and a line landing during the
bounce scrolls in as following would. endUserScroll takes isAtEnd, like releaseDisclosure.

Tests: VisibleContentPositionClampTest gains growth at the end during a drag (red before the
change: the offset moved by the 120 px growth, 352 -> 472) and growth without a touch (the pin
still follows); the module suite passes on emulator-5558, 11 tests.
bottom-anchor-controller.test.ts: a release near but short of the end stays detached.

Device, frame scans while streaming (dev clients rebuilt):
- Android, 8 slow drags with a pill tap between: no frame moves against the finger once a drag
  starts; the stream follows between drags. Three short releases 50 px short of the end stay put
  until the pill; three drags back past the end resume following.
- iOS simulator, 6 drags: no line step during any drag or its momentum. Two short releases stay
  detached with no snap; three drags past the end resume following within 0.5 s of the bounce.

* Document the LegendList timeline and remove what the inverted list left

The native section of docs/agent-stream-disclosure.md described the FlatList hold (anchor
neighbour, native child index, frame spacing, render window). It now covers why the timeline is
forward order, who owns the offset in each state, the hold and its sync layout trigger, user
scroll and release, draw distance numbers, the LegendList patch and the scroll view corrections.

Draw distance stays at 2000. The spike measured it on a chat with a 15,000 px turn expanded: 500
blanked the viewport 1.0 to 1.5 s per fling and 2000 not at all. A re-measure on the collapsed chat
(500, 1000, 1500, 2000, interleaved) blanked at no value and its jank followed host load, which
stayed between 19 and 40, so it could not separate 1000 or 1500 from 2000.

The patch file now opens with a header listing its eight hunks by purpose and linking
LegendApp/legend-list#593, which reports each one upstream. The markdown doc records the iOS
first-paint delay (software-mansion/enriched-markdown#1131).

Removed with the inverted list: PaseoScrollView's child-reveal override (a no-op without the
inverting transform) and ScrollSelectionTest, the invertedWrapper style, and the inverted-list
passages in android.md, native-text-selection.md, mobile-testing.md, floating-panels.md and
agent-stream-performance.md. model.test, layout.test and footer-spacing.test still asserted the
inverted native order and failed; they now assert forward order, and footer-spacing uses the
real strategies instead of an inverted stub.

* fix(app): show a reply's footer when the next prompt arrives on native

LegendList re-renders a mounted row only when its item or extraData changes.
When a new prompt arrives, the previous reply's footer moves from the live
auxiliary slot into that reply's layout item (completedFooter). The reply's
StreamItem keeps its identity, and renderItem is a stable event, so the row never
rendered its new layout and the footer (copy, timing, fork) disappeared until the
row remounted. FlatList had the same gap.

The history renderer is now LegendList's extraData. Its identity changes with the
history layout map, and StreamRow's memo limits the pass to rows whose layout
item changed.

* test(app): run the web disclosure hold cases in a real browser

The three hold cases simulated layout in jsdom: hand-written row heights,
scroll clamping and resize callbacks. They could pass while Chromium paints
the trigger somewhere else. They now run in Vitest browser mode with real
layout, ResizeObserver and scroll clamping. The two hold cases fail when the
hold is bypassed.

The browser project pre-bundles @tanstack/react-virtual, so its first import no
longer reloads the test mid-run. The lucide stub gains ArrowDown, which
pane-find imports.

* fix(app): let a drag end a disclosure hold on native

A drag detached the bottom controller but kept the disclosure hold. Every item
size change restarts the hold's quiet frames, including a streaming row's, so
the hold can outlive the toggle. While it lasts, shouldRestorePosition accepts
only the held row. Once the drag scrolls that row away, a history page arriving
mid-gesture gets no anchor, and the rows the reader was on move by the page's
height.

The drag now cancels the hold without releasing it. The controller keeps no hold
state of its own beyond detached, and the gesture's end decides whether following
resumes.

* perf(app): keep the scroll-to-bottom button's state out of the timeline

Opening a tool call or turn at the end of the chat now holds its trigger in
place, so the timeline detaches and the scroll-to-bottom button appears. That
visibility was useState in AgentStreamView, so showing the button re-rendered
the whole timeline view for a change only the button reads. The viewport now
writes near-bottom into a per-agent store that only the button subscribes to.

* fix(app): show the scroll-to-bottom button on native whenever following has stopped

A gesture now resumes following only when it ends within 1 px of the end, but
the button still hid within 32 px. A release 2-32 px short of the end left the
list detached with no button to return. While detached the button now hides
only at the end; while following it keeps the 32 px tolerance so content
growth that the offset trails for a frame does not flash it. The button also
updates when following starts or stops without a scroll.

* fix(app): stop the timeline jumping when the keyboard opens or closes on native

The keyboard's settled height was committed to the list after the motion, as
paddingTop on Android and contentInset.top on iOS, to keep the top of the
history reachable under the translated dock. While following, the end pin
absorbed it in the same mount. While detached or holding a disclosure, nothing
did: Android's native anchor is LegendList's ScrollAdjust view, which padding
does not move, and LegendList compensates a padding change only on iOS. Every
row jumped by the keyboard height 0.2-1 s after the keyboard settled, and back
after it closed. On send, the same commit raced the jump to the end.

The keyboard now only translates the list with the composer. The cost: while
the keyboard is open, the composer viewport clips the top keyboard-height of
the list, so the start of a short conversation is hidden until it closes.

* chore(app): describe the native timeline as LegendList in stream comments

* fix(app): keep a disclosure's trigger in place when its row is cut off at the top on native

LegendList's idsInView starts at the first fully visible row. When a turn host's prompt bubble
sat above the viewport, a disclosure hold found no anchor in the data pass (shouldRestorePosition
rejects every other row), and the size pass anchored on the row below the host instead, so the
trigger moved by the host's size change. The patch appends the partly visible rows to idsInView
after the fully visible ones, so the held row anchors while every pass that does not restrict the
anchor keeps the first fully visible row.

The browser test renders the patched native build, which vitest now aliases instead of the
package's unpatched web build.

* fix(app): let a turn's summary line collapse again after it opens

The React Compiler cached StreamRow's `renderStreamItem(layoutItem)` on the layout item and the
renderer. The revised item that useRevisedHistoryRows hands a row whose display state changed only
fed the row id, so the row reused its cached content. Opening a turn usually inserts its rows
directly below the host, which also gives the host a new layout item. When another row sits
between them, such as a compaction marker, the host kept its layout item, its summary line stayed
collapsed, and every later tap asked to open the turn again.

The renderer now takes the item it renders, so the compiler's cache keys on the revision. StreamRow
moves to its own module, which the tests compile the way Expo does.

* test(app): alias the patched LegendList build in browser tests only

Unit tests load @legendapp/list outside Vite, so the native build's react-native import skipped
the react-native-web alias and reached React Native's Flow source, failing every unit suite that
imports the native strategy.

* fix(app): keep a size-only disclosure's trigger in place when its row is cut off at the top on native

LegendList's prepareMVCP picks the anchor for a size change with no data change as the first row
in view, without asking shouldRestorePosition. A disclosure that only grows its own row (a todo
card) while that row's top was above the viewport therefore held the row below it, and the trigger
moved by the row's size change. The patch now applies shouldRestorePosition to size changes as it
already does to data changes.

* test(app): render the timeline row revision test in a real browser

The repo's unit tests do not mount components in JSDOM. The test still compiles stream-row.tsx with
the React Compiler, so it fails when a revised row ignores the item it was handed.
---
 CLAUDE.md                                     |   1 +
 docs/agent-stream-disclosure.md               | 163 ++++++
 docs/agent-stream-performance.md              |   8 +-
 docs/android.md                               |  20 +-
 docs/floating-panels.md                       |  10 +-
 docs/markdown-renderer.md                     |   2 +
 docs/mobile-testing.md                        |  11 +-
 docs/native-text-selection.md                 |   9 -
 package-lock.json                             |  21 +
 .../src/androidTest/AndroidManifest.xml       |   7 +
 .../sh/paseo/scroll/MountingReactContext.java |  77 +++
 .../sh/paseo/scroll/ScrollSelectionTest.kt    | 159 -----
 .../sh/paseo/scroll/ScrollTestContext.java    |  19 -
 .../scroll/VisibleContentPositionClampTest.kt | 271 +++++++++
 .../sh/paseo/scroll/PaseoScrollPackage.kt     |  52 --
 .../java/sh/paseo/scroll/PaseoScrollView.java | 142 +++++
 .../paseo-scroll/expo-module.config.json      |   2 +-
 .../paseo-scroll/ios/PaseoScroll.podspec      |  16 +
 .../ios/PaseoScrollViewComponentView.mm       | 148 +++++
 packages/app/package.json                     |   1 +
 .../bottom-anchor-controller.test.ts          | 292 ++++------
 .../agent-stream/bottom-anchor-controller.ts  | 107 ++--
 .../chat-find/viewport.browser.test.ts        |   4 +-
 .../chat-outline/use-chat-outline.test.tsx    |   6 +-
 packages/app/src/agent-stream/disclosure.tsx  |  40 ++
 .../src/agent-stream/footer-spacing.test.ts   |  29 +-
 packages/app/src/agent-stream/layout.test.ts  |   2 +-
 .../legend-list-held-row.browser.test.tsx     | 171 ++++++
 packages/app/src/agent-stream/model.test.ts   |   8 +-
 .../native-disclosure-hold.test.ts            | 105 ++++
 .../agent-stream/native-disclosure-hold.ts    |  64 ++
 .../app/src/agent-stream/native-end-pin.tsx   |  61 ++
 .../native-scroll-animation.test.ts           |  37 +-
 .../agent-stream/native-scroll-animation.ts   |  12 +-
 packages/app/src/agent-stream/near-bottom.ts  |  44 ++
 .../agent-stream/new-row-estimates.test.ts    |  92 +++
 .../app/src/agent-stream/new-row-estimates.ts |  47 ++
 packages/app/src/agent-stream/presentation.ts |   2 +
 .../src/agent-stream/reading-anchor.test.ts   |  10 +
 .../app/src/agent-stream/reading-anchor.ts    |   5 +
 .../src/agent-stream/render-strategy.test.ts  | 309 ++--------
 .../scroll-keyboard-dismiss/model.test.ts     |  56 +-
 .../scroll-keyboard-dismiss/model.ts          |   8 +-
 .../use-scroll-keyboard-dismiss.ts            |   2 +-
 .../app/src/agent-stream/strategy-native.tsx  | 478 +++++++++------
 .../strategy-web.browser.test.tsx             | 158 +++++
 .../app/src/agent-stream/strategy-web.tsx     |  45 +-
 packages/app/src/agent-stream/strategy.ts     |  40 +-
 .../agent-stream/stream-row.browser.test.tsx  |  69 +++
 packages/app/src/agent-stream/stream-row.tsx  |  58 ++
 packages/app/src/agent-stream/top-overlay.ts  |   2 +-
 .../agent-stream/turn-collapse/model.test.ts  |  32 +
 .../src/agent-stream/turn-collapse/model.ts   |  40 ++
 .../turn-collapse/summary-line.tsx            |   6 +-
 packages/app/src/agent-stream/view.tsx        | 148 +++--
 packages/app/src/components/message.tsx       |  11 +-
 packages/app/src/keyboard/shift/index.ts      |   3 +-
 .../src/keyboard/shift/internal/context.ts    |  10 -
 .../keyboard/shift/internal/policy.test.ts    |  24 -
 .../app/src/keyboard/shift/internal/policy.ts |  20 -
 .../src/keyboard/shift/internal/provider.ts   |  27 +-
 .../app/src/keyboard/shift/internal/stream.ts |  17 -
 .../tool-calls/detail-level/overview/view.tsx |   9 +-
 .../app/test-stubs/lucide-react-native.ts     |   1 +
 packages/app/vitest.config.ts                 |  19 +-
 patches/@legendapp+list+3.7.1.patch           | 548 ++++++++++++++++++
 scripts/postinstall-patches.mjs               |   5 +
 67 files changed, 3143 insertions(+), 1279 deletions(-)
 create mode 100644 docs/agent-stream-disclosure.md
 create mode 100644 packages/app/modules/paseo-scroll/android/src/androidTest/AndroidManifest.xml
 create mode 100644 packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/MountingReactContext.java
 delete mode 100644 packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/ScrollSelectionTest.kt
 delete mode 100644 packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/ScrollTestContext.java
 create mode 100644 packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/VisibleContentPositionClampTest.kt
 create mode 100644 packages/app/modules/paseo-scroll/android/src/main/java/sh/paseo/scroll/PaseoScrollView.java
 create mode 100644 packages/app/modules/paseo-scroll/ios/PaseoScroll.podspec
 create mode 100644 packages/app/modules/paseo-scroll/ios/PaseoScrollViewComponentView.mm
 create mode 100644 packages/app/src/agent-stream/disclosure.tsx
 create mode 100644 packages/app/src/agent-stream/legend-list-held-row.browser.test.tsx
 create mode 100644 packages/app/src/agent-stream/native-disclosure-hold.test.ts
 create mode 100644 packages/app/src/agent-stream/native-disclosure-hold.ts
 create mode 100644 packages/app/src/agent-stream/native-end-pin.tsx
 create mode 100644 packages/app/src/agent-stream/near-bottom.ts
 create mode 100644 packages/app/src/agent-stream/new-row-estimates.test.ts
 create mode 100644 packages/app/src/agent-stream/new-row-estimates.ts
 create mode 100644 packages/app/src/agent-stream/strategy-web.browser.test.tsx
 create mode 100644 packages/app/src/agent-stream/stream-row.browser.test.tsx
 create mode 100644 packages/app/src/agent-stream/stream-row.tsx
 delete mode 100644 packages/app/src/keyboard/shift/internal/stream.ts
 create mode 100644 patches/@legendapp+list+3.7.1.patch

diff --git a/CLAUDE.md b/CLAUDE.md
index c9b6e0db7c..1496bd407b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -55,6 +55,7 @@ At the start of non-trivial work, list `docs/` and skim anything relevant to the
 | [docs/terminal-performance.md](docs/terminal-performance.md)         | Terminal latency pipeline, coalescing/backpressure invariants, benchmark + perf spec usage                                     |
 | [docs/terminal-rendering.md](docs/terminal-rendering.md)             | Native terminal view: xterm owns the grid, cluster placement, emoji widths, mixed-direction limits, render regression          |
 | [docs/agent-stream-performance.md](docs/agent-stream-performance.md) | Assistant text pipeline — coalescing window, paced reveal, why arrival lumps are smoothed at render                            |
+| [docs/agent-stream-disclosure.md](docs/agent-stream-disclosure.md)   | Expand/collapse in the chat timeline — hold contract, native anchor sequence, frame spacing, render-window cost                |
 | [docs/markdown-renderer.md](docs/markdown-renderer.md)               | Shared Markdown engine, native selection, links, images and library constraints                                                |
 | [docs/native-text-selection.md](docs/native-text-selection.md)       | Native diagram grouping, selection boundaries and leading inline image limitations                                             |
 | [docs/file-observation.md](docs/file-observation.md)                 | Recursive watcher ownership, Linux constraints, teardown invariants, and Parcel comparison                                     |
diff --git a/docs/agent-stream-disclosure.md b/docs/agent-stream-disclosure.md
new file mode 100644
index 0000000000..9cde8a44ff
--- /dev/null
+++ b/docs/agent-stream-disclosure.md
@@ -0,0 +1,163 @@
+# Agent stream disclosures
+
+Expanding or collapsing something in the chat timeline (a turn's summary line, a tool-call group,
+a tool call's inline details, a todo card) keeps the tapped trigger at the same screen y in the
+first painted frame. No animation.
+
+## The contract
+
+A disclosure component knows nothing about the list. It wraps its state change:
+
+```tsx
+const hold = useDisclosureHold();
+const handleToggle = () => hold(() => setExpanded((value) => !value));
+```
+
+`view.tsx` wraps every timeline row in `DisclosureRow`, which routes `hold` to the strategy's
+`holdRow(rowId, apply)` (`packages/app/src/agent-stream/disclosure.tsx`). Outside a timeline row,
+`apply` runs as is. The strategy owns when `apply` runs and how the row keeps its place.
+
+Following output:
+
+- A hold always detaches the bottom anchor controller (`holdForDisclosure`).
+- When the hold ends, the controller re-sticks only if the list sits at its end and no user scroll
+  owns the viewport (`releaseDisclosure({ isAtEnd })`). Expanding at the bottom therefore leaves
+  the list detached with the scroll-to-bottom pill showing; collapsing back to the end resumes
+  following.
+- Scroll events during the hold never re-stick: the correction is a programmatic scroll that
+  would otherwise read as "back at the bottom".
+
+The trigger can only stay put when the list has scroll room for the change. When the loaded
+content fits the viewport, or a collapse at the end would need an offset past the end, the list
+ends at its end and the trigger moves by the difference.
+
+## Web
+
+`holdRow` pins the row in the reading anchor and runs `apply`; the next reading reconcile restores
+the row's top after layout, before paint (`strategy-web.tsx`).
+
+## Native
+
+On compact layouts, tool calls and tool-call groups open a sheet instead of expanding, so they do
+not hold. Summary lines and todo cards expand inline.
+
+The timeline is a LegendList in forward order: one `data` array of history rows followed by the
+live head, oldest first (`strategy-native.tsx`). LegendList keeps a row in place across a size
+change in the commit that makes it, so a hold needs no anchor neighbour, native child index or
+render window stretch. The inverted FlatList it replaced needed all three, and three commits per
+toggle; its applied commit took up to 3.5 s of JS on a long turn.
+
+### Who owns the offset
+
+One owner keeps the scroll offset at any moment:
+
+| State                  | Owner                                                                                     |
+| ---------------------- | ----------------------------------------------------------------------------------------- |
+| Before rows are placed | LegendList's initial scroll to the end. It keeps the rows hidden until they are measured. |
+| Following the end      | The end pin (`native-end-pin.tsx`).                                                       |
+| Disclosure hold        | LegendList's `maintainVisibleContentPosition`, restoring only the held row.               |
+| User scroll            | The finger. The controller detaches at drag start.                                        |
+| Detached               | LegendList's `maintainVisibleContentPosition` on the first visible row.                   |
+| Keyboard motion        | Nobody. The keyboard translates the list with the composer and leaves the offset alone.   |
+
+The end pin is a zero-height view at the bottom of the content and the content's first native
+child, with React Native's `maintainVisibleContentPosition` set to `{ minIndexForVisible: 0 }`. The
+native correction runs on the UI thread around each mount, so a row that grows or lands at the end
+scrolls in the frame it lays out. The controller scrolls only for a viewport resize (the composer
+growing or shrinking) and an explicit jump, both through the native `scrollToEnd`.
+
+Do not use LegendList's `maintainScrollAtEnd` instead. It scrolls from JS after the mount to the end
+its JS sizes predict: growth paints below the viewport for a frame, and the scroll lands short of
+the native end, which the controller reads as the user scrolling away.
+
+The keyboard never changes the list's size, padding or offset. `KeyboardTranslateView` moves the list
+and the composer together on the UI thread, and the composer viewport clips the top of the list
+while the keyboard is open. Do not add a keyboard-sized inset to keep that content reachable: it can
+only commit after the motion, and while detached or holding nothing corrects for it, so every row
+jumps by the keyboard height after the keyboard settles.
+
+### The hold
+
+`holdRow(rowId, apply)` runs in the toggle's event:
+
+1. Mark the row held and detach the controller (`holdForDisclosure`). The pin goes away and
+   LegendList's `maintainVisibleContentPosition` takes over, restoring only the held row
+   (`shouldRestorePosition`). Upstream LegendList anchors only rows from the first fully visible
+   one down, and a size change with no data change keeps the first row in view whatever
+   `shouldRestorePosition` says. A row cut off at the top would then let the row below it hold
+   instead, moving the trigger by the row's size change. The LegendList patch counts rows cut off
+   at the top as in view and applies `shouldRestorePosition` to size changes too.
+2. Run `apply`.
+3. Call the row's `useSyncLayout` trigger. The toggle changes the row from its own state, so
+   LegendList's container does not re-render and would learn the new height from `onLayout` a task
+   later, after the change painted. The trigger puts the measurement and the corrected positions
+   in the toggle's own commit.
+
+The hold ends two frames after the last item size change, since the list measures the toggled row
+and any rows it inserted over several frames (`native-disclosure-hold.ts`). The controller then
+re-sticks only if the list is within 1 px of its end, the same distance web resumes from.
+
+### User scroll
+
+The controller detaches at `onScrollBeginDrag`, so lines that stream in during a drag grow below
+the rows under the finger. The detach reaches native a JS round trip after the drag begins, so for
+those frames the pin is still mounted. The scroll view subclasses skip the pin's correction while
+the user drags (see [scroll view corrections](#scroll-view-corrections)). They skip only the pin's:
+in the detached state LegendList uses the same native correction, and a history page that lands
+mid-drag needs it. They key on the drag, not the touch, so a tap or long press while following
+keeps following.
+
+Following resumes only for a gesture that ends within 1 px of the end, either when the finger lifts
+or when momentum stops. A release past the end counts: iOS bounces back to the end, and lines that
+land during the bounce must keep scrolling in. A release anywhere short of the end stays detached
+with the scroll-to-bottom pill, so the rows the user let go of never move.
+
+### Draw distance
+
+`drawDistance` is 2000 px on each side of the viewport. A fling over rows that were never measured
+blanks the viewport until LegendList renders and measures them. Twelve flings over a chat with a
+15,000 px turn expanded, Android emulator, dev build:
+
+| List                          | Blank viewport             | Janky frames | p50 / p90 / p99  |
+| ----------------------------- | -------------------------- | ------------ | ---------------- |
+| Inverted FlatList             | 1.3 to 1.7 s over 5 flings | 10.8%        | 27 / 48 / 109 ms |
+| LegendList, drawDistance 500  | 1.0 to 1.5 s per fling     |              |                  |
+| LegendList, drawDistance 2000 | none                       | 1.7%         | 24 / 32 / 48 ms  |
+
+With every turn collapsed, flinging from a cold open into history did not blank at any value from
+500 to 2000, and jank followed host load (19 to 40 on 16 cores) rather than draw distance. Measure
+1000 and 1500 on the expanded chat, on a host under load 10, before lowering it.
+
+### LegendList patch
+
+`patches/@legendapp+list+3.7.1.patch` carries ten changes for the timeline. Its header lists
+them by purpose, and
+[legend-list #593](https://github.com/LegendApp/legend-list/issues/593) reports each upstream.
+Drop a hunk when the installed LegendList ships its fix.
+
+### Scroll view corrections
+
+`modules/paseo-scroll` replaces React Native's scroll view on both platforms with a subclass:
+Android's `PaseoScrollView` and iOS's `PaseoScrollViewComponentView`.
+`VisibleContentPositionClampTest` covers Android; iOS has no native test harness.
+
+**Content clamp.** A mount that shrinks the content while `maintainVisibleContentPosition` is set
+applies the shrink twice on both platforms: the scroll view clamps its offset to the new end during
+the mount, and React Native then adds the anchor's movement to the clamped offset
+([RN #58578](https://github.com/react/react-native/issues/58578), fix in
+[PR #58695](https://github.com/react/react-native/pull/58695)). A turn that folds while the list
+follows its end lands above the end. Android defers the clamp to the pre-draw pass, and iOS restores
+the pre-mount offset for the adjustment and clamps after it.
+
+**Removed anchor (iOS).** A hold removes the end pin in the same mount that opens the tapped
+disclosure, and React Native 0.86 on iOS moves the offset by the removed view's frame. The iOS
+subclass keeps the offset. Android keeps a removed view's last frame, so it keeps the offset already.
+React Native 0.88 skips the adjustment for a removed anchor
+([PR #57294](https://github.com/react/react-native/pull/57294)).
+
+**End pin during a drag.** Both subclasses recognize the pin by its native ID, `paseo-end-pin`,
+and skip its correction while the user drags ([user scroll](#user-scroll)). This one has no React
+Native counterpart; it stays while the timeline uses the pin.
+
+Remove the content clamp and removed-anchor overrides once the installed React Native includes
+their fixes.
diff --git a/docs/agent-stream-performance.md b/docs/agent-stream-performance.md
index ec506ee99b..fb022895bc 100644
--- a/docs/agent-stream-performance.md
+++ b/docs/agent-stream-performance.md
@@ -34,10 +34,10 @@ So arrival sets a _target_ and the reveal rate is derived from the backlog inste
 - **First sight of a text is revealed whole.** Only growth is paced. This is what makes history hydration, timeline replay, a virtualized row remounting on scroll, and an already-finished message all render complete on first paint without a special case for each.
 - **Leaving `phase: "streaming"` snaps the reveal.** A completed turn must never be left holding characters. `layoutStream` sets the phase, so anything outside the live head with an active turn is already complete.
 - **The reducer queue commits on a frame, with a timer as the ceiling.** A frame callback never fires in a hidden tab, so a timer races it and wins when nothing is painting — the store has to keep advancing either way.
-- **A history row re-renders only when its item or layout item identity changes.** The inverted
-  FlatList hands every mounted cell a new `index` and `ref` whenever a row is prepended, so without a
-  memo boundary each coalesced tick re-rendered every mounted row (about 50 on a phone, 100–250 ms of
-  JS per tick). `layoutStream` keeps a layout item's identity when nothing about it changed,
+- **A history row re-renders only when its item or layout item identity changes.** Every
+  coalesced tick hands the list a new layout. Without a memo boundary each tick re-rendered every
+  mounted row (measured on the inverted FlatList native used before LegendList: about 50 rows on a
+  phone, 100–250 ms of JS per tick). `layoutStream` keeps a layout item's identity when nothing about it changed,
   `useRevisedHistoryRows` hands a fresh item identity to rows whose tool-call group, expanded state,
   or breakpoint changed, and `StreamRow` memoizes on both. Every viewport runs its history
   through that hook; the web viewport once skipped it and history hosts of a live tool group went
diff --git a/docs/android.md b/docs/android.md
index 6b10a56892..8b6201ae91 100644
--- a/docs/android.md
+++ b/docs/android.md
@@ -174,18 +174,18 @@ REACT_NATIVE_PACKAGER_HOSTNAME=localhost \
 
 This is the Android counterpart of the iOS local-simulator flow in [development.md](development.md): on iOS the simulator shares the Mac's loopback so `localhost:<port>` works directly; on Android you need `10.0.2.2` or `adb reverse`.
 
-## Inverted timeline input
+## Scroll view corrections
 
-Android focus and selection visibility requests must not reposition inverted timelines. The
-`modules/paseo-scroll` package keeps React Native's scroll manager interface and returns zero for
-child-reveal scroll calculations when the view's transform matrix inverts the vertical axis. React
-Native's Android list uses `scale: -1`, which decomposes into a 180-degree rotation with positive
-`scaleY`; checking the scale property alone misses it. Dragging and explicit scroll
-commands still work; non-inverted scroll views keep Android's default behavior.
+`modules/paseo-scroll` replaces React Native's vertical scroll view with `PaseoScrollView`, which
+keeps React Native's scroll manager interface and corrects `maintainVisibleContentPosition` for the
+chat timeline. [agent-stream-disclosure.md](agent-stream-disclosure.md#scroll-view-corrections)
+lists the corrections and the React Native issues they work around. Its instrumentation test,
+`VisibleContentPositionClampTest`, mounts through React Native's own mounting manager:
 
-Mouse wheel axes also bypass the inversion transform. The same module reverses the vertical
-wheel axis for inverted scroll views before delegating to Android, preserving native scroll
-bounds and React Native's scroll events and disabled-scroll behavior.
+```bash
+cd packages/app/android
+./gradlew :paseo-scroll:connectedDebugAndroidTest --no-daemon --max-workers=2 -Dorg.gradle.parallel=false
+```
 
 Register this package before React Native's core package through its Expo config plugin. Normal
 Android builds use the prebuilt `react-android` library, so patching Java under `node_modules` does
diff --git a/docs/floating-panels.md b/docs/floating-panels.md
index 4616a03815..9032a3d079 100644
--- a/docs/floating-panels.md
+++ b/docs/floating-panels.md
@@ -157,8 +157,7 @@ and the stream keeps its existing flick-to-dismiss gesture.
 The dock's private viewport and capacity model are extracted from chat. The
 app-wide `@/keyboard/shift` module owns shared motion for the dock, portals, streams,
 terminal, explorer, and dialogs. Import only its public entry point: the provider,
-shift hooks, shift style, translate view, keyboard anchor, settled stream inset, and explorer padding
-policy. Its contexts and reconciliation stay private. Keep `KeyboardShiftProvider`
+shift hooks, shift style, translate view, and keyboard anchor. Its contexts and reconciliation stay private. Keep `KeyboardShiftProvider`
 at its root mount point outside the portal host when changing dock hosts.
 
 `KeyboardTranslateView` owns visual keyboard motion inside `@/keyboard/shift`. Android uses the
@@ -171,15 +170,14 @@ animation. Keep this platform choice inside the keyboard module's private platfo
 `KeyboardTranslateView`. The panel root clips it at the header edge, so rows
 slide under the header on open and out from under it on close. Do not swap the
 dock to keyboard padding at rest. Changing its height creates either a blank
-band or a paused transition when the inverted list updates its viewport.
+band or a paused transition when the stream list updates its viewport.
 
 Do not animate a layout prop through the keyboard transition. On Android
 Fabric, each animated layout update clones the shadow tree and runs Yoga over
 the dock subtree. This measured about 10 ms per frame on the emulator and the
 mounted layouts arrived in bursts every 2–4 frames. A transform does not dirty
-layout. Preserve the translated dock's history scroll range with a far-end
-content inset on the inverted stream list. Update that inset only when keyboard
-motion settles; never drive it per frame.
+layout. The stream list gets no keyboard inset either; see
+[who owns the offset](agent-stream-disclosure.md#who-owns-the-offset).
 
 The translated dock's height is not the composer's available height. Bound the
 composer against the stationary space below the header inside
diff --git a/docs/markdown-renderer.md b/docs/markdown-renderer.md
index 9a69631071..11b9f09405 100644
--- a/docs/markdown-renderer.md
+++ b/docs/markdown-renderer.md
@@ -26,6 +26,8 @@ Native code blocks use the library's copy control and compiled grammars. Web cod
 
 The package patch also keeps overflowing native horizontal blocks in control of their drags: Android claims parent interception at touch-down and releases it for vertical drags so the chat list can scroll; iOS keeps its scroll recognizer active for outward drags at the leading edge. This prevents compact sidebar pans from taking block scrolling without changing sidebar swipes on prose or non-overflowing blocks. Native changes require a client rebuild.
 
+On iOS a newly mounted Markdown view paints empty for a frame or more after it is laid out at its measured height: the library parses even a view's first content on a background queue and applies it in a later main-queue turn. Expanding a turn in chat therefore shows its rows in place with the text arriving a frame later (165 ms when the mount keeps the main thread busy). Android paints the text in the first frame. Rendering a view's first content synchronously fixes the frame but costs frame time when a fling mounts history rows, so the app keeps the library's behavior until [enriched-markdown #1131](https://github.com/software-mansion/enriched-markdown/issues/1131) is resolved.
+
 Android measurements use a size-only, 512-entry LRU across view unmounts, matching the library’s existing iOS cache. Scrolling back through history can reuse layout sizes without parsing those rows again. Content, layout props and width identify each entry; font-scale changes and native layout invalidation discard affected sizes. The cache retains no views or spans.
 
 The library determines how incomplete Markdown appears during streaming. Completed text uses the same component and engine as history. Find and scroll-to-message address source message ids; selection-copy understands semantic HTML and the web code component's copy metadata.
diff --git a/docs/mobile-testing.md b/docs/mobile-testing.md
index 903244e3d9..3dbea66676 100644
--- a/docs/mobile-testing.md
+++ b/docs/mobile-testing.md
@@ -452,18 +452,9 @@ Regular `View` components can safely use Unistyles dynamic styles — the confli
 
 ## Native Chat Stream Layout
 
-The native agent stream uses an inverted `FlatList`, so chat layout has three coordinate systems:
-
-- chronological stream order
-- strategy-ordered array order
-- native inverted cell visual order
-
 Do not compute stream neighbors, history/live-head seams, turn footer ownership, assistant block spacing, or tool sequence endings inside React render loops. Those policies live in `packages/app/src/agent-stream/layout.ts` and are unit-tested without React Native rendering.
 
-Platform-specific stream edges belong on `StreamStrategy`:
-
-- forward web uses the last history item as the history/live-head boundary and renders content before a footer
-- native inverted uses the first history item as the history/live-head boundary and compensates for inverted cell child order
+Platform-specific stream edges belong on `StreamStrategy`. Web and native both render in chronological order, so both use the last history item as the history/live-head boundary and render content before a footer.
 
 If a chat footer looks duplicated or appears above the assistant message on mobile, start with `packages/app/src/agent-stream/layout.test.ts`. Do not add a React Native renderer test for this class of bug; make the pure layout invariant fail first.
 
diff --git a/docs/native-text-selection.md b/docs/native-text-selection.md
index dd7edcd79c..fb04571451 100644
--- a/docs/native-text-selection.md
+++ b/docs/native-text-selection.md
@@ -2,15 +2,6 @@
 
 Keep completed assistant prose in one native text view so selection crosses paragraphs, headings and lists. The shared [Markdown renderer](markdown-renderer.md) owns that view.
 
-## Android inverted chat
-
-Keep selection visibility handling in `modules/paseo-scroll`. Android's visibility
-rectangles ignore list inversion. React Native decomposes Android's `scale: -1`
-into rotation with positive `scaleY`, so test the composed matrix when deciding
-whether those requests should move the viewport. Native tests must apply the
-list's transform through React Native's view manager; assigning `scaleY` directly
-misses that decomposition.
-
 ## Diagrams in lists and quotes
 
 Selection stops at a Mermaid diagram. Native extracts Mermaid fences into separate views because the library exposes no native block renderer override. A diagram inside a list or quote therefore appears outside that container, and its following prose starts a separate Markdown fragment.
diff --git a/package-lock.json b/package-lock.json
index 5518ce485e..7e561ceb9d 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -8142,6 +8142,26 @@
         "@jridgewell/sourcemap-codec": "^1.4.14"
       }
     },
+    "node_modules/@legendapp/list": {
+      "version": "3.7.1",
+      "resolved": "https://registry.npmjs.org/@legendapp/list/-/list-3.7.1.tgz",
+      "integrity": "sha512-zgIy84yG2JP93+kib61rZBTcYGZ6fULrkCQz/MF7WrjVJeJQa/rR4z+rXfM5oveirO5mYkro4IDGytARIjJe9w==",
+      "license": "MIT",
+      "dependencies": {
+        "use-sync-external-store": "^1.5.0"
+      },
+      "peerDependencies": {
+        "react": "*"
+      },
+      "peerDependenciesMeta": {
+        "react-dom": {
+          "optional": true
+        },
+        "react-native": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/@lezer/common": {
       "version": "1.5.1",
       "resolved": "https://registry.npmjs.org/@lezer/common/-/common-1.5.1.tgz",
@@ -37466,6 +37486,7 @@
         "@getpaseo/protocol": "*",
         "@gorhom/bottom-sheet": "^5.2.14",
         "@gorhom/portal": "^1.0.14",
+        "@legendapp/list": "^3.7.1",
         "@marijn/find-cluster-break": "^1.0.2",
         "@mattermost/react-native-paste-input": "2.0.1",
         "@react-native-async-storage/async-storage": "2.2.0",
diff --git a/packages/app/modules/paseo-scroll/android/src/androidTest/AndroidManifest.xml b/packages/app/modules/paseo-scroll/android/src/androidTest/AndroidManifest.xml
new file mode 100644
index 0000000000..2b3dae4d2a
--- /dev/null
+++ b/packages/app/modules/paseo-scroll/android/src/androidTest/AndroidManifest.xml
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <application>
+    <!-- Hosts a scroll view in a real window, so layout clamps and draws run as they do on device. -->
+    <activity android:name="android.app.Activity" android:exported="false" />
+  </application>
+</manifest>
diff --git a/packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/MountingReactContext.java b/packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/MountingReactContext.java
new file mode 100644
index 0000000000..fb9f65ced1
--- /dev/null
+++ b/packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/MountingReactContext.java
@@ -0,0 +1,77 @@
+package sh.paseo.scroll;
+
+import android.content.Context;
+import com.facebook.react.bridge.BridgeReactContext;
+import com.facebook.react.bridge.UIManager;
+import com.facebook.react.bridge.UIManagerListener;
+import com.facebook.react.uimanager.events.EventDispatcher;
+import com.facebook.react.uimanager.events.EventDispatcherProvider;
+import java.lang.reflect.Proxy;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * A React context with a running Fabric UIManager, so scroll views find the mount listener
+ * registry and event dispatcher the way they do in the app. The UIManager only records mount
+ * listeners and the dispatcher drops events; every other call returns a default. Java, because
+ * {@link EventDispatcherProvider} is internal to React Native's Kotlin module.
+ */
+final class MountingReactContext extends BridgeReactContext implements EventDispatcherProvider {
+  final List<UIManagerListener> mountListeners = new ArrayList<>();
+  final UIManager uiManager;
+  private final EventDispatcher eventDispatcher = inert(EventDispatcher.class, null);
+
+  MountingReactContext(Context base) {
+    super(base);
+    uiManager = inert(UIManager.class, this);
+  }
+
+  /** Runs one Fabric mount: listeners see willMountItems, then the change, then didMountItems. */
+  void mount(Runnable change) {
+    for (UIManagerListener listener : new ArrayList<>(mountListeners)) listener.willMountItems(uiManager);
+    change.run();
+    for (UIManagerListener listener : new ArrayList<>(mountListeners)) listener.didMountItems(uiManager);
+  }
+
+  @Override
+  public boolean hasActiveReactInstance() {
+    return true;
+  }
+
+  @Override
+  public UIManager getFabricUIManager() {
+    return uiManager;
+  }
+
+  @Override
+  public EventDispatcher getEventDispatcher() {
+    return eventDispatcher;
+  }
+
+  private static <T> T inert(Class<T> type, MountingReactContext owner) {
+    return type.cast(
+        Proxy.newProxyInstance(
+            type.getClassLoader(),
+            new Class<?>[] {type},
+            (proxy, method, args) -> {
+              switch (method.getName()) {
+                case "addUIManagerEventListener":
+                  owner.mountListeners.add((UIManagerListener) args[0]);
+                  return null;
+                case "removeUIManagerEventListener":
+                  owner.mountListeners.remove((UIManagerListener) args[0]);
+                  return null;
+                case "getEventDispatcher":
+                  return owner.eventDispatcher;
+                default:
+                  Class<?> result = method.getReturnType();
+                  if (result == boolean.class) return false;
+                  if (result == int.class) return 0;
+                  if (result == long.class) return 0L;
+                  if (result == float.class) return 0f;
+                  if (result == double.class) return 0.0;
+                  return null;
+              }
+            }));
+  }
+}
diff --git a/packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/ScrollSelectionTest.kt b/packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/ScrollSelectionTest.kt
deleted file mode 100644
index 0ed8e69626..0000000000
--- a/packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/ScrollSelectionTest.kt
+++ /dev/null
@@ -1,159 +0,0 @@
-package sh.paseo.scroll
-
-import android.graphics.Rect
-import android.text.Selection
-import android.text.Spannable
-import android.view.View
-import android.view.InputDevice
-import android.view.MotionEvent
-import android.os.SystemClock
-import android.widget.FrameLayout
-import android.widget.TextView
-import androidx.test.ext.junit.runners.AndroidJUnit4
-import androidx.test.platform.app.InstrumentationRegistry
-import com.facebook.react.bridge.JavaOnlyArray
-import com.facebook.react.bridge.JavaOnlyMap
-import com.facebook.react.soloader.OpenSourceMergedSoMapping
-import com.facebook.react.uimanager.DisplayMetricsHolder
-import com.facebook.react.uimanager.ReactStylesDiffMap
-import com.facebook.react.uimanager.ThemedReactContext
-import com.facebook.react.views.scroll.ReactScrollView
-import com.facebook.react.views.scroll.ReactScrollViewManager
-import com.facebook.soloader.SoLoader
-import org.junit.Assert.*
-import org.junit.Test
-import org.junit.runner.RunWith
-
-@RunWith(AndroidJUnit4::class)
-class ScrollSelectionTest {
-  @Test fun mouseWheelMovesInvertedViewportInVisualDirection() = withScroll(inverted = true) { scroll, _ ->
-    val before = scroll.scrollY
-    withWheel(1f) { event ->
-      assertTrue(scroll.dispatchGenericMotionEvent(event))
-      assertTrue("Wheel up must move toward older messages: $before -> ${scroll.scrollY}", scroll.scrollY > before)
-      assertEquals("The caller's event must not change", 1f, event.getAxisValue(MotionEvent.AXIS_VSCROLL))
-    }
-    val afterUp = scroll.scrollY
-    withWheel(-1f) { event ->
-      assertTrue(scroll.dispatchGenericMotionEvent(event))
-      assertTrue("Wheel down must move toward newer messages: $afterUp -> ${scroll.scrollY}", scroll.scrollY < afterUp)
-    }
-  }
-
-  @Test fun mouseWheelKeepsOrdinaryScrollDirection() = withScroll(inverted = false) { scroll, _ ->
-    val before = scroll.scrollY
-    withWheel(1f) { event ->
-      assertTrue(scroll.dispatchGenericMotionEvent(event))
-      assertTrue(scroll.scrollY < before)
-    }
-    val afterUp = scroll.scrollY
-    withWheel(-1f) { event ->
-      assertTrue(scroll.dispatchGenericMotionEvent(event))
-      assertTrue(scroll.scrollY > afterUp)
-    }
-  }
-
-  @Test fun mouseWheelRespectsDisabledScrolling() = withScroll(inverted = true) { scroll, _ ->
-    scroll.setScrollEnabled(false)
-    val before = scroll.scrollY
-    withWheel(1f) { scroll.dispatchGenericMotionEvent(it) }
-    assertEquals(before, scroll.scrollY)
-  }
-
-  @Test fun focusingSelectableTextKeepsInvertedViewportStill() = withScroll(inverted = true) { scroll, text ->
-    val before = scroll.scrollY
-    assertTrue(text.requestFocus())
-    assertSame(text, scroll.findFocus())
-    assertEquals("Text focus must not move the inverted viewport", before, scroll.scrollY)
-    assertTrue(text.isTextSelectable)
-  }
-
-  @Test fun selectingTextKeepsInvertedViewportStill() = withScroll(inverted = true) { scroll, text ->
-    val before = scroll.scrollY
-    Selection.setSelection(text.text as Spannable, 0, 8)
-    text.requestRectangleOnScreen(Rect(0, 0, 80, 40), true)
-    assertEquals("Selection visibility requests must not move the inverted viewport", before, scroll.scrollY)
-    assertEquals("Selectab", text.text.subSequence(text.selectionStart, text.selectionEnd).toString())
-  }
-
-  @Test fun explicitScrollCommandsStillMoveInvertedViewport() = withScroll(inverted = true) { scroll, _ ->
-    scroll.scrollTo(0, 600)
-    assertEquals(600, scroll.scrollY)
-  }
-
-  @Test fun ordinaryScrollViewsStillRevealSelectedText() = withScroll(inverted = false) { scroll, text ->
-    val before = scroll.scrollY
-    text.requestRectangleOnScreen(Rect(0, 0, 80, 40), true)
-    assertNotEquals(before, scroll.scrollY)
-  }
-
-  @Test fun verticalScaleStillKeepsFocusAndSelectionInPlace() = withScroll(inverted = true, transform = "scaleY") { scroll, text ->
-    val before = scroll.scrollY
-    assertTrue(text.requestFocus())
-    text.requestRectangleOnScreen(Rect(0, 0, 80, 40), true)
-    assertEquals(before, scroll.scrollY)
-  }
-
-  @Test fun horizontalScaleStillRevealsSelectedText() = withScroll(inverted = true, transform = "scaleX") { scroll, text ->
-    val before = scroll.scrollY
-    text.requestRectangleOnScreen(Rect(0, 0, 80, 40), true)
-    assertNotEquals(before, scroll.scrollY)
-  }
-
-  private fun withScroll(inverted: Boolean, transform: String = "scale", check: (ReactScrollView, TextView) -> Unit) {
-    val instrumentation = InstrumentationRegistry.getInstrumentation()
-    instrumentation.runOnMainSync {
-      val appContext = instrumentation.targetContext
-      DisplayMetricsHolder.initDisplayMetricsIfNotInitialized(appContext)
-      SoLoader.init(appContext, OpenSourceMergedSoMapping)
-      val reactContext = ScrollTestContext(appContext)
-      val context = ThemedReactContext(reactContext, appContext)
-      val manager = PaseoScrollPackage().createViewManager(reactContext, ReactScrollViewManager.REACT_CLASS) as ReactScrollViewManager
-      val scroll = manager.createViewInstance(context)
-      val content = FrameLayout(context)
-      val text = TextView(context).apply {
-        setText("Selectable timeline text", TextView.BufferType.SPANNABLE)
-        setTextIsSelectable(true)
-      }
-      content.addView(text, FrameLayout.LayoutParams(300, 100).apply { topMargin = 1400 })
-      scroll.addView(content)
-      content.measure(exact(300), exact(2000))
-      content.layout(0, 0, 300, 2000)
-      scroll.measure(exact(300), exact(300))
-      scroll.layout(0, 0, 300, 300)
-      // Apply RN's actual Android inversion through the manager's transform decomposition.
-      val transforms = JavaOnlyArray.of(JavaOnlyMap.of(transform, if (inverted) -1.0 else 1.0))
-      manager.updateProperties(scroll, ReactStylesDiffMap(JavaOnlyMap.of("transform", transforms)))
-      if (inverted && transform == "scale") {
-        assertEquals(1f, scroll.scaleY, 0f)
-        assertEquals(180f, kotlin.math.abs(scroll.rotation), 0f)
-      }
-      scroll.scrollTo(0, 400)
-      check(scroll, text)
-    }
-  }
-
-  private fun exact(size: Int) = View.MeasureSpec.makeMeasureSpec(size, View.MeasureSpec.EXACTLY)
-
-  private fun withWheel(axis: Float, check: (MotionEvent) -> Unit) {
-    val time = SystemClock.uptimeMillis()
-    val properties = MotionEvent.PointerProperties().apply {
-      id = 0
-      toolType = MotionEvent.TOOL_TYPE_MOUSE
-    }
-    val coordinates = MotionEvent.PointerCoords().apply {
-      x = 150f
-      y = 150f
-      setAxisValue(MotionEvent.AXIS_VSCROLL, axis)
-    }
-    val event = MotionEvent.obtain(
-      time, time, MotionEvent.ACTION_SCROLL, 1, arrayOf(properties), arrayOf(coordinates),
-      0, 0, 1f, 1f, 0, 0, InputDevice.SOURCE_MOUSE, 0,
-    )
-    try {
-      check(event)
-    } finally {
-      event.recycle()
-    }
-  }
-}
diff --git a/packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/ScrollTestContext.java b/packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/ScrollTestContext.java
deleted file mode 100644
index d2e64c6339..0000000000
--- a/packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/ScrollTestContext.java
+++ /dev/null
@@ -1,19 +0,0 @@
-package sh.paseo.scroll;
-
-import android.content.Context;
-import com.facebook.react.bridge.BridgeReactContext;
-import com.facebook.react.uimanager.events.BlackHoleEventDispatcher;
-import com.facebook.react.uimanager.events.EventDispatcher;
-import com.facebook.react.uimanager.events.EventDispatcherProvider;
-
-/** Native-only tests use RN's dispatcher for a context without a JS instance. */
-final class ScrollTestContext extends BridgeReactContext implements EventDispatcherProvider {
-  ScrollTestContext(Context context) {
-    super(context);
-  }
-
-  @Override
-  public EventDispatcher getEventDispatcher() {
-    return BlackHoleEventDispatcher.INSTANCE;
-  }
-}
diff --git a/packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/VisibleContentPositionClampTest.kt b/packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/VisibleContentPositionClampTest.kt
new file mode 100644
index 0000000000..c99241db47
--- /dev/null
+++ b/packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/VisibleContentPositionClampTest.kt
@@ -0,0 +1,271 @@
+package sh.paseo.scroll
+
+import android.app.Activity
+import android.content.Context
+import android.content.Intent
+import android.graphics.Canvas
+import android.os.SystemClock
+import android.view.MotionEvent
+import android.view.View
+import android.widget.FrameLayout
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import androidx.test.platform.app.InstrumentationRegistry
+import com.facebook.react.bridge.JavaOnlyMap
+import com.facebook.react.soloader.OpenSourceMergedSoMapping
+import com.facebook.react.uimanager.DisplayMetricsHolder
+import com.facebook.react.uimanager.ReactStylesDiffMap
+import com.facebook.react.uimanager.RootView
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.views.scroll.ReactScrollView
+import com.facebook.react.views.scroll.ReactScrollViewManager
+import com.facebook.react.views.view.ReactViewGroup
+import com.facebook.soloader.SoLoader
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+
+/**
+ * A Fabric mount that shrinks the content of a scroll view with `maintainVisibleContentPosition`
+ * set. The mount runs through React Native's real position keeper, driven by the same
+ * willMountItems/didMountItems calls Fabric makes, inside a real window so layout clamps and draws
+ * happen as they do on a device.
+ */
+@RunWith(AndroidJUnit4::class)
+class VisibleContentPositionClampTest {
+  private val instrumentation = InstrumentationRegistry.getInstrumentation()
+  private var activity: Activity? = null
+
+  @After fun finish() {
+    activity?.finish()
+  }
+
+  @Test fun shrinkAtTheEndLandsAtTheNewEnd() {
+    val timeline = openTimeline(anchor = Anchor.END)
+
+    timeline.shrinkInOneMount()
+
+    assertEquals("Offset after the mount", NEW_END, timeline.scrollY())
+    assertEquals("Offset in the first frame drawn after the mount", NEW_END, timeline.firstDrawnScrollY())
+  }
+
+  @Test fun shrinkBelowAnUnmovedAnchorIsClampedBeforeTheFrameDraws() {
+    val timeline = openTimeline(anchor = Anchor.TOP_ROW)
+
+    timeline.shrinkInOneMount()
+
+    assertEquals("Offset in the first frame drawn after the mount", NEW_END, timeline.firstDrawnScrollY())
+    assertEquals("Offset after the mount", NEW_END, timeline.scrollY())
+  }
+
+  @Test fun shrinkDuringATouchDragLeavesNoOffsetPastTheEnd() {
+    val timeline = openTimeline(anchor = Anchor.TOP_ROW)
+
+    timeline.beginDrag()
+    assertTrue("The drag owns the viewport", timeline.scrollY() < CONTENT_HEIGHT - VIEWPORT)
+    timeline.shrinkInOneMount()
+    val drawn = timeline.firstDrawnScrollY()
+    timeline.endDrag()
+    val settled = timeline.settledScrollY()
+
+    assertTrue("Offset $drawn drawn past the end $NEW_END", drawn <= NEW_END)
+    assertTrue("Offset $settled settled past the end $NEW_END", settled <= NEW_END)
+    timeline.awaitFrames(10)
+    assertEquals("Offset kept moving after the drag ended", settled, timeline.scrollY())
+  }
+
+  @Test fun growthAtTheEndFollowsWithoutATouch() {
+    val timeline = openTimeline(anchor = Anchor.END)
+
+    timeline.growInOneMount()
+
+    assertEquals("Offset after the mount", CONTENT_HEIGHT + GROWTH - VIEWPORT, timeline.scrollY())
+  }
+
+  // The drag begins before JS stops following and removes the pin, so a line mounting in the drag's
+  // first frames must not scroll the rows the finger is on.
+  @Test fun growthAtTheEndDuringATouchDragKeepsTheRowsUnderTheFinger() {
+    val timeline = openTimeline(anchor = Anchor.END)
+
+    timeline.beginDrag()
+    val dragged = timeline.scrollY()
+    assertTrue("The drag owns the viewport", dragged < CONTENT_HEIGHT - VIEWPORT)
+    timeline.growInOneMount()
+
+    assertEquals("Offset after the mount", dragged, timeline.scrollY())
+    assertEquals("Offset in the first frame drawn after the mount", dragged, timeline.firstDrawnScrollY())
+    timeline.endDrag()
+  }
+
+  private enum class Anchor {
+    /** A zero-height view at the bottom of the content, first child: the end pin. */
+    END,
+    /** A row at the top of the content that reaches into the viewport and does not move. */
+    TOP_ROW,
+  }
+
+  private inner class Timeline(
+    val scroll: ReactScrollView,
+    private val content: ReactViewGroup,
+    private val endPin: View,
+    private val probe: DrawProbe,
+    private val reactContext: MountingReactContext,
+  ) {
+    private var dragY = 0f
+    private var downTime = 0L
+
+    fun scrollY(): Int {
+      var y = 0
+      instrumentation.runOnMainSync { y = scroll.scrollY }
+      return y
+    }
+
+    fun shrinkInOneMount() = resizeInOneMount(CONTENT_HEIGHT - SHRINK)
+
+    fun growInOneMount() = resizeInOneMount(CONTENT_HEIGHT + GROWTH)
+
+    private fun resizeInOneMount(height: Int) {
+      instrumentation.runOnMainSync {
+        probe.drawnScrollY.clear()
+        reactContext.mount { layoutContent(height) }
+        probe.invalidate()
+      }
+    }
+
+    fun firstDrawnScrollY(): Int {
+      val deadline = SystemClock.uptimeMillis() + 2000
+      while (SystemClock.uptimeMillis() < deadline) {
+        instrumentation.waitForIdleSync()
+        var drawn: Int? = null
+        instrumentation.runOnMainSync { drawn = probe.drawnScrollY.firstOrNull() }
+        drawn?.let { return it }
+        SystemClock.sleep(16)
+      }
+      throw AssertionError("No frame was drawn after the mount")
+    }
+
+    fun beginDrag() {
+      downTime = SystemClock.uptimeMillis()
+      dragY = 300f
+      touch(MotionEvent.ACTION_DOWN)
+      // Finger moves down, so the content scrolls up from the end and the drag owns the viewport.
+      repeat(6) {
+        dragY += 12f
+        touch(MotionEvent.ACTION_MOVE)
+      }
+    }
+
+    fun endDrag() {
+      dragY += 4f
+      touch(MotionEvent.ACTION_MOVE)
+      touch(MotionEvent.ACTION_UP)
+    }
+
+    fun settledScrollY(): Int {
+      var previous = scrollY()
+      repeat(60) {
+        awaitFrames(2)
+        val current = scrollY()
+        if (current == previous) return current
+        previous = current
+      }
+      throw AssertionError("Offset never settled")
+    }
+
+    fun awaitFrames(count: Int) {
+      repeat(count) {
+        instrumentation.waitForIdleSync()
+        SystemClock.sleep(16)
+      }
+    }
+
+    fun layoutContent(height: Int) {
+      content.layout(0, 0, WIDTH, height)
+      endPin.layout(0, height, 0, height)
+    }
+
+    private fun touch(action: Int) {
+      instrumentation.runOnMainSync {
+        val event = MotionEvent.obtain(downTime, SystemClock.uptimeMillis(), action, WIDTH / 2f, dragY, 0)
+        scroll.dispatchTouchEvent(event)
+        event.recycle()
+      }
+    }
+  }
+
+  /** The React surface root a scroll view reports its native gestures to. */
+  private class SurfaceRoot(context: Context) : FrameLayout(context), RootView {
+    override fun onChildStartedNativeGesture(childView: View?, ev: MotionEvent) {}
+
+    override fun onChildEndedNativeGesture(childView: View, ev: MotionEvent) {}
+
+    override fun handleException(t: Throwable) {
+      throw t
+    }
+  }
+
+  private class DrawProbe(context: Context) : View(context) {
+    val drawnScrollY = mutableListOf<Int>()
+
+    override fun onDraw(canvas: Canvas) {
+      drawnScrollY += (parent.parent as View).scrollY
+    }
+  }
+
+  private fun openTimeline(anchor: Anchor): Timeline {
+    val started =
+      instrumentation.startActivitySync(
+        Intent(instrumentation.targetContext, Activity::class.java).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+      )
+    activity = started
+    lateinit var timeline: Timeline
+    instrumentation.runOnMainSync {
+      DisplayMetricsHolder.initDisplayMetricsIfNotInitialized(started)
+      SoLoader.init(started, OpenSourceMergedSoMapping)
+      val reactContext = MountingReactContext(started.applicationContext)
+      val context = ThemedReactContext(reactContext, started)
+      val manager =
+        PaseoScrollPackage().createViewManager(reactContext, ReactScrollViewManager.REACT_CLASS)
+          as ReactScrollViewManager
+      val scroll = manager.createViewInstance(context)
+      val content = ReactViewGroup(context)
+      val endPin = View(context).apply { setTag(com.facebook.react.R.id.view_tag_native_id, END_PIN_NATIVE_ID) }
+      val probe = DrawProbe(context)
+      if (anchor == Anchor.END) {
+        content.addView(endPin)
+        content.addView(probe)
+      } else {
+        content.addView(probe)
+        content.addView(endPin)
+      }
+      scroll.addView(content)
+      manager.updateProperties(
+        scroll,
+        ReactStylesDiffMap(
+          JavaOnlyMap.of("maintainVisibleContentPosition", JavaOnlyMap.of("minIndexForVisible", 0))
+        ),
+      )
+      started.setContentView(SurfaceRoot(started).apply { addView(scroll, FrameLayout.LayoutParams(WIDTH, VIEWPORT)) })
+      timeline = Timeline(scroll, content, endPin, probe, reactContext)
+      timeline.layoutContent(CONTENT_HEIGHT)
+      probe.layout(0, 0, WIDTH, PROBE_HEIGHT)
+    }
+    timeline.awaitFrames(2)
+    instrumentation.runOnMainSync { timeline.scroll.scrollTo(0, CONTENT_HEIGHT - VIEWPORT) }
+    timeline.awaitFrames(2)
+    assertEquals("Starts at the end", CONTENT_HEIGHT - VIEWPORT, timeline.scrollY())
+    return timeline
+  }
+
+  private companion object {
+    const val WIDTH = 300
+    const val VIEWPORT = 600
+    const val CONTENT_HEIGHT = 1000
+    const val SHRINK = 240
+    const val GROWTH = 120
+    const val END_PIN_NATIVE_ID = "paseo-end-pin"
+    const val NEW_END = CONTENT_HEIGHT - SHRINK - VIEWPORT
+    const val PROBE_HEIGHT = 700
+  }
+}
diff --git a/packages/app/modules/paseo-scroll/android/src/main/java/sh/paseo/scroll/PaseoScrollPackage.kt b/packages/app/modules/paseo-scroll/android/src/main/java/sh/paseo/scroll/PaseoScrollPackage.kt
index e887d67a31..617a017336 100644
--- a/packages/app/modules/paseo-scroll/android/src/main/java/sh/paseo/scroll/PaseoScrollPackage.kt
+++ b/packages/app/modules/paseo-scroll/android/src/main/java/sh/paseo/scroll/PaseoScrollPackage.kt
@@ -1,9 +1,5 @@
 package sh.paseo.scroll
 
-import android.graphics.Matrix
-import android.graphics.Rect
-import android.view.InputDevice
-import android.view.MotionEvent
 import com.facebook.react.ReactPackage
 import com.facebook.react.ViewManagerOnDemandReactPackage
 import com.facebook.react.bridge.NativeModule
@@ -28,51 +24,3 @@ private class PaseoScrollViewManager : ReactScrollViewManager() {
   override fun createViewInstance(context: ThemedReactContext): ReactScrollView =
     PaseoScrollView(context)
 }
-
-private class PaseoScrollView(context: ThemedReactContext) : ReactScrollView(context) {
-  private val transformValues = FloatArray(9)
-
-  private fun isVerticallyInverted(): Boolean {
-    // Android FlatList uses scale: -1, which RN decomposes into a 180-degree
-    // rotation with positive scaleY. Read the resulting transform, not scaleY.
-    matrix.getValues(transformValues)
-    return transformValues[Matrix.MSCALE_Y] < 0
-  }
-
-  override fun onGenericMotionEvent(event: MotionEvent): Boolean {
-    if (!isVerticallyInverted() || event.actionMasked != MotionEvent.ACTION_SCROLL ||
-        !event.isFromSource(InputDevice.SOURCE_CLASS_POINTER)) {
-      return super.onGenericMotionEvent(event)
-    }
-    if (!scrollEnabled) return false
-
-    // Android applies wheel axes directly to scrollY; the inversion transform only
-    // transforms pointer coordinates. Reverse the vertical axis before delegating so
-    // platform scroll bounds and scroll events still apply.
-    val properties = Array(event.pointerCount) { index ->
-      MotionEvent.PointerProperties().also { event.getPointerProperties(index, it) }
-    }
-    val coordinates = Array(event.pointerCount) { index ->
-      MotionEvent.PointerCoords().also {
-        event.getPointerCoords(index, it)
-        it.setAxisValue(MotionEvent.AXIS_VSCROLL, -it.getAxisValue(MotionEvent.AXIS_VSCROLL))
-      }
-    }
-    val correctedEvent = MotionEvent.obtain(
-      event.downTime, event.eventTime, event.action, event.pointerCount, properties, coordinates,
-      event.metaState, event.buttonState, event.xPrecision, event.yPrecision,
-      event.deviceId, event.edgeFlags, event.source, event.flags,
-    )
-    return try {
-      super.onGenericMotionEvent(correctedEvent)
-    } finally {
-      correctedEvent.recycle()
-    }
-  }
-
-  // Both RN focus handling and Android selection visibility requests use this calculation.
-  // Its coordinates ignore inversion. Keep focus/selection bookkeeping, but leave timeline
-  // movement to user gestures and explicit scroll commands.
-  override fun computeScrollDeltaToGetChildRectOnScreen(rect: Rect): Int =
-    if (isVerticallyInverted()) 0 else super.computeScrollDeltaToGetChildRectOnScreen(rect)
-}
diff --git a/packages/app/modules/paseo-scroll/android/src/main/java/sh/paseo/scroll/PaseoScrollView.java b/packages/app/modules/paseo-scroll/android/src/main/java/sh/paseo/scroll/PaseoScrollView.java
new file mode 100644
index 0000000000..5e2345830c
--- /dev/null
+++ b/packages/app/modules/paseo-scroll/android/src/main/java/sh/paseo/scroll/PaseoScrollView.java
@@ -0,0 +1,142 @@
+package sh.paseo.scroll;
+
+import android.content.Context;
+import android.view.MotionEvent;
+import android.view.View;
+import android.view.ViewGroup;
+import android.view.ViewTreeObserver;
+import androidx.annotation.Nullable;
+import com.facebook.react.R;
+import com.facebook.react.views.scroll.MaintainVisibleScrollPositionHelper;
+import com.facebook.react.views.scroll.ReactScrollView;
+import com.facebook.react.views.scroll.ReactScrollViewHelper;
+
+/**
+ * React Native's vertical scroll view with two corrections. Java, because the content-position
+ * config type is internal to React Native's Kotlin module.
+ */
+final class PaseoScrollView extends ReactScrollView {
+  // The chat timeline's end pin, packages/app/src/agent-stream/native-end-pin.tsx.
+  private static final String END_PIN_NATIVE_ID = "paseo-end-pin";
+
+  private final ViewTreeObserver.OnPreDrawListener clampBeforeDraw =
+      () -> {
+        clampToContentEnd();
+        return true;
+      };
+  private @Nullable MaintainVisibleScrollPositionHelper.Config visibleContentPosition = null;
+  private boolean isClampPending = false;
+  private boolean isUserDragging = false;
+
+  PaseoScrollView(Context context) {
+    super(context);
+  }
+
+  @Override
+  public void setMaintainVisibleContentPosition(
+      @Nullable MaintainVisibleScrollPositionHelper.Config config) {
+    super.setMaintainVisibleContentPosition(config);
+    visibleContentPosition = config;
+  }
+
+  // While the timeline follows its end, its end pin anchors the content position, so every line that
+  // mounts scrolls the content by its height. A drag owns the offset from the frame it begins, and
+  // JS removes the pin only a round trip later. While the user drags, the correction for the pin is
+  // skipped, so the line grows below the rows under the finger. iOS's PaseoScrollViewComponentView
+  // does the same.
+  // MaintainVisibleScrollPositionHelper is the only caller: it moves the offset by its anchor's move.
+  @Override
+  public void scrollToPreservingMomentum(int x, int y) {
+    if (isUserDragging && isEndPinTheAnchor()) return;
+    super.scrollToPreservingMomentum(x, y);
+  }
+
+  // The drag begins where React Native emits onScrollBeginDrag.
+  @Override
+  protected void handleInterceptedTouchEvent(MotionEvent ev) {
+    super.handleInterceptedTouchEvent(ev);
+    isUserDragging = true;
+  }
+
+  @Override
+  public boolean onTouchEvent(MotionEvent ev) {
+    boolean handled = super.onTouchEvent(ev);
+    int action = ev.getActionMasked();
+    if (action == MotionEvent.ACTION_UP || action == MotionEvent.ACTION_CANCEL) {
+      isUserDragging = false;
+    }
+    return handled;
+  }
+
+  // The helper anchors on the first content child from minIndexForVisible that reaches into the
+  // viewport. The pin is the first child and sits at the bottom of the content, so it always does.
+  private boolean isEndPinTheAnchor() {
+    if (visibleContentPosition == null || visibleContentPosition.getMinIndexForVisible() != 0) {
+      return false;
+    }
+    View content = getChildAt(0);
+    if (!(content instanceof ViewGroup) || ((ViewGroup) content).getChildCount() == 0) return false;
+    Object nativeId = ((ViewGroup) content).getChildAt(0).getTag(R.id.view_tag_native_id);
+    return END_PIN_NATIVE_ID.equals(nativeId);
+  }
+
+  // With maintainVisibleContentPosition set, a mount that shrinks the content past the offset would
+  // apply the shrink twice:
+  // 1. MaintainVisibleScrollPositionHelper.willMountItems records the anchor's frame.
+  // 2. The mount lays out the shorter content, and ReactScrollView.onLayoutChange clamps the offset
+  //    to the new end.
+  // 3. MaintainVisibleScrollPositionHelper.didMountItems adds the anchor's move to the clamped
+  //    offset, so the shrink moves the offset a second time (to the top, for a shrink at the end).
+  // The clamp waits for the pre-draw pass instead, which runs after didMountItems and before the
+  // frame draws: the anchor's move applies to the offset the content had before the mount, and the
+  // clamp only catches what the anchor did not account for.
+  // https://github.com/react/react-native/issues/58578 tracks it; remove this override once
+  // https://github.com/react/react-native/pull/58695 ships in the React Native version we use.
+  @Override
+  public void onLayoutChange(
+      View v,
+      int left,
+      int top,
+      int right,
+      int bottom,
+      int oldLeft,
+      int oldTop,
+      int oldRight,
+      int oldBottom) {
+    if (visibleContentPosition == null) {
+      super.onLayoutChange(v, left, top, right, bottom, oldLeft, oldTop, oldRight, oldBottom);
+      return;
+    }
+    if (!isClampPending) {
+      isClampPending = true;
+      getViewTreeObserver().addOnPreDrawListener(clampBeforeDraw);
+    }
+    ReactScrollViewHelper.emitLayoutChangeEvent(this);
+  }
+
+  @Override
+  protected void onDetachedFromWindow() {
+    cancelPendingClamp();
+    isUserDragging = false;
+    super.onDetachedFromWindow();
+  }
+
+  private void clampToContentEnd() {
+    cancelPendingClamp();
+    View content = getChildAt(0);
+    if (content == null || content.getWidth() == 0 || content.getHeight() == 0 || !isShown()) {
+      return;
+    }
+    int viewportHeight = getHeight() - getPaddingTop() - getPaddingBottom();
+    int maxScrollY = Math.max(0, content.getHeight() - viewportHeight);
+    if (getScrollY() > maxScrollY) {
+      scrollTo(getScrollX(), maxScrollY);
+    }
+  }
+
+  private void cancelPendingClamp() {
+    if (!isClampPending) return;
+    isClampPending = false;
+    getViewTreeObserver().removeOnPreDrawListener(clampBeforeDraw);
+  }
+}
diff --git a/packages/app/modules/paseo-scroll/expo-module.config.json b/packages/app/modules/paseo-scroll/expo-module.config.json
index ba00434407..47b7ac97b7 100644
--- a/packages/app/modules/paseo-scroll/expo-module.config.json
+++ b/packages/app/modules/paseo-scroll/expo-module.config.json
@@ -1 +1 @@
-{ "platforms": ["android"], "android": { "modules": [] } }
+{ "platforms": ["android", "ios"], "android": { "modules": [] }, "ios": { "modules": [] } }
diff --git a/packages/app/modules/paseo-scroll/ios/PaseoScroll.podspec b/packages/app/modules/paseo-scroll/ios/PaseoScroll.podspec
new file mode 100644
index 0000000000..8ddbfd47b2
--- /dev/null
+++ b/packages/app/modules/paseo-scroll/ios/PaseoScroll.podspec
@@ -0,0 +1,16 @@
+Pod::Spec.new do |s|
+  s.name           = 'PaseoScroll'
+  s.version        = '0.1.0'
+  s.summary        = 'Scroll view corrections for Paseo'
+  s.description    = 'Scroll view corrections for Paseo'
+  s.license        = 'Apache-2.0'
+  s.author         = 'Paseo'
+  s.homepage       = 'https://paseo.sh'
+  s.platforms      = { :ios => '15.1' }
+  s.source         = { :path => '.' }
+  s.static_framework = true
+
+  s.source_files = "**/*.{h,mm}"
+
+  install_modules_dependencies(s)
+end
diff --git a/packages/app/modules/paseo-scroll/ios/PaseoScrollViewComponentView.mm b/packages/app/modules/paseo-scroll/ios/PaseoScrollViewComponentView.mm
new file mode 100644
index 0000000000..6b9ca95435
--- /dev/null
+++ b/packages/app/modules/paseo-scroll/ios/PaseoScrollViewComponentView.mm
@@ -0,0 +1,148 @@
+#import <React/RCTComponentViewFactory.h>
+#import <React/RCTCustomPullToRefreshViewProtocol.h>
+#import <React/RCTScrollViewComponentView.h>
+#import <React/RCTViewComponentView.h>
+#import <react/renderer/components/scrollview/ScrollViewProps.h>
+#import <react/renderer/components/scrollview/ScrollViewShadowNode.h>
+
+using namespace facebook::react;
+
+/**
+ * React Native's scroll view with three maintainVisibleContentPosition corrections.
+ *
+ * An anchor removed by the mount it anchors. React Native picks the anchor before the mount and
+ * moves the offset by the anchor's movement after it. When the mount removes that view, its frame
+ * after the mount no longer describes the content, and the offset jumps by an unrelated amount.
+ * Android keeps a removed view's last frame, so it keeps the offset. This class keeps the offset on
+ * iOS too.
+ * The chat timeline hits this when it stops following its end: the same mount removes the end pin
+ * and opens the disclosure the reader tapped.
+ * React Native 0.88 skips the adjustment for a removed anchor
+ * (https://github.com/react/react-native/pull/57294). Its view-registry tag check matches the check
+ * here; its superview check also skips anchors that removeClippedSubviews detached
+ * (https://github.com/react/react-native/issues/58910). Remove this part once the installed React
+ * Native includes the tag check.
+ *
+ * The chat timeline's end pin during a drag. While the timeline follows its end, a zero-height view
+ * at the bottom of the content (native ID "paseo-end-pin", packages/app/src/agent-stream/
+ * native-end-pin.tsx) is the anchor, so every line that mounts scrolls the content by its height.
+ * A drag owns the offset from the frame it begins, and JS removes the pin only a round trip later.
+ * While the user drags, a mount anchored on the pin keeps the offset, so the line grows below the
+ * rows under the finger. Android's PaseoScrollView does the same.
+ *
+ * A shrink at the end. A mount that shrinks the content sets the smaller contentSize, and UIKit
+ * clamps contentOffset to the new end. React Native then adds the anchor's movement to the clamped
+ * offset, so the shrink is applied twice and the viewport lands above the content it kept.
+ * The chat timeline hits this when a finished turn folds while the end pin follows the latest row.
+ * https://github.com/react/react-native/issues/58578
+ * Remove once https://github.com/react/react-native/pull/58695 ships; it keeps the pre-mount
+ * offset and clamps after the adjustment, as this class does.
+ */
+@interface PaseoScrollViewComponentView : RCTScrollViewComponentView
+@end
+
+@implementation PaseoScrollViewComponentView {
+  CGPoint _offsetBeforeMount;
+  __weak UIView *_anchorBeforeMount;
+  NSInteger _anchorTagBeforeMount;
+}
+
+// Replaces React Native's class for the ScrollView component. The factory looks a component up the
+// first time it mounts, so the registration has to come before the first surface.
++ (void)load
+{
+  [[RCTComponentViewFactory currentComponentViewFactory] registerComponentViewClass:self];
+}
+
+- (void)mountingTransactionWillMount:(const MountingTransaction &)transaction
+                withSurfaceTelemetry:(const SurfaceTelemetry &)surfaceTelemetry
+{
+  _offsetBeforeMount = self.scrollView.contentOffset;
+  _anchorBeforeMount = [self visibleContentAnchor];
+  _anchorTagBeforeMount = _anchorBeforeMount.tag;
+  [super mountingTransactionWillMount:transaction withSurfaceTelemetry:surfaceTelemetry];
+}
+
+- (void)mountingTransactionDidMount:(const MountingTransaction &)transaction
+               withSurfaceTelemetry:(const SurfaceTelemetry &)surfaceTelemetry
+{
+  // The view registry sets a removed view's tag to 0; a released view reads nil here.
+  BOOL isAnchorRemoved = _anchorTagBeforeMount != 0 && _anchorBeforeMount.tag != _anchorTagBeforeMount;
+  if (isAnchorRemoved || (self.scrollView.isDragging && [self isEndPin:_anchorBeforeMount])) {
+    // Without the content-position props, React Native's mount completes without moving the offset.
+    SharedViewProps props = _props;
+    _props = ScrollViewShadowNode::defaultSharedProps();
+    [super mountingTransactionDidMount:transaction withSurfaceTelemetry:surfaceTelemetry];
+    _props = props;
+    return;
+  }
+  if (![self didClampOffsetDuringMount]) {
+    [super mountingTransactionDidMount:transaction withSurfaceTelemetry:surfaceTelemetry];
+    return;
+  }
+  UIScrollView *scrollView = self.scrollView;
+  scrollView.contentOffset = _offsetBeforeMount;
+  [super mountingTransactionDidMount:transaction withSurfaceTelemetry:surfaceTelemetry];
+  CGFloat y = MAX(MIN(scrollView.contentOffset.y, [self maxOffsetY]), -scrollView.adjustedContentInset.top);
+  if (y != scrollView.contentOffset.y) {
+    scrollView.contentOffset = CGPointMake(scrollView.contentOffset.x, y);
+  }
+}
+
+// UIKit moved the offset to the new end while the mount set a smaller contentSize. A user scroll
+// never gets here: React Native keeps the offset through contentSize changes while the user scrolls.
+- (BOOL)didClampOffsetDuringMount
+{
+  const auto &props = static_cast<const ScrollViewProps &>(*_props);
+  if (!props.maintainVisibleContentPosition) {
+    return NO;
+  }
+  CGFloat y = self.scrollView.contentOffset.y;
+  return y < _offsetBeforeMount.y - 0.5 && ABS(y - [self maxOffsetY]) <= 0.5;
+}
+
+// The view React Native anchors on for vertical content: the first content child from
+// minIndexForVisible that reaches into the viewport, or the last one.
+- (UIView *)visibleContentAnchor
+{
+  const auto &props = static_cast<const ScrollViewProps &>(*_props);
+  UIScrollView *scrollView = self.scrollView;
+  if (!props.maintainVisibleContentPosition || scrollView.contentSize.width > self.frame.size.width) {
+    return nil;
+  }
+  NSArray<UIView *> *children = [self contentView].subviews;
+  NSUInteger first = props.maintainVisibleContentPosition.value().minIndexForVisible;
+  for (NSUInteger index = first; index < children.count; ++index) {
+    UIView *child = children[index];
+    if (CGRectGetMaxY(child.frame) > scrollView.contentOffset.y || index == children.count - 1) {
+      return child;
+    }
+  }
+  return nil;
+}
+
+- (BOOL)isEndPin:(UIView *)view
+{
+  return [view isKindOfClass:[RCTViewComponentView class]] &&
+      [((RCTViewComponentView *)view).nativeId isEqualToString:@"paseo-end-pin"];
+}
+
+- (UIView *)contentView
+{
+  for (UIView *child in self.containerView.subviews) {
+    if (![child conformsToProtocol:@protocol(RCTCustomPullToRefreshViewProtocol)]) {
+      return child;
+    }
+  }
+  return nil;
+}
+
+- (CGFloat)maxOffsetY
+{
+  UIScrollView *scrollView = self.scrollView;
+  return MAX(
+      scrollView.contentSize.height - scrollView.bounds.size.height + scrollView.adjustedContentInset.bottom,
+      -scrollView.adjustedContentInset.top);
+}
+
+@end
diff --git a/packages/app/package.json b/packages/app/package.json
index 42d791fbf4..1447bef2f7 100644
--- a/packages/app/package.json
+++ b/packages/app/package.json
@@ -59,6 +59,7 @@
     "@getpaseo/protocol": "*",
     "@gorhom/bottom-sheet": "^5.2.14",
     "@gorhom/portal": "^1.0.14",
+    "@legendapp/list": "^3.7.1",
     "@marijn/find-cluster-break": "^1.0.2",
     "@mattermost/react-native-paste-input": "2.0.1",
     "@react-native-async-storage/async-storage": "2.2.0",
diff --git a/packages/app/src/agent-stream/bottom-anchor-controller.test.ts b/packages/app/src/agent-stream/bottom-anchor-controller.test.ts
index 17b6d44459..12ff114521 100644
--- a/packages/app/src/agent-stream/bottom-anchor-controller.test.ts
+++ b/packages/app/src/agent-stream/bottom-anchor-controller.test.ts
@@ -263,7 +263,7 @@ describe("bottom anchor controller driver", () => {
 
     expect(harness.scrollAttempts).toHaveLength(0);
 
-    harness.driver.endUserScroll({ isNearBottom: true });
+    harness.driver.endUserScroll({ isAtEnd: true });
     harness.scheduler.flushAll();
 
     expect(harness.scrollAttempts).toHaveLength(1);
@@ -293,7 +293,7 @@ describe("bottom anchor controller driver", () => {
     });
     harness.context.authoritativeReady = true;
     harness.driver.notifyAuthoritativeHistoryMaybeChanged();
-    harness.driver.endUserScroll({ isNearBottom: true });
+    harness.driver.endUserScroll({ isAtEnd: true });
     harness.scheduler.flushAll();
 
     expect(harness.scrollAttempts).toHaveLength(1);
@@ -321,7 +321,7 @@ describe("bottom anchor controller driver", () => {
       nextIsNearBottom: false,
       scrollDelta: 48,
     });
-    harness.driver.endUserScroll({ isNearBottom: false });
+    harness.driver.endUserScroll({ isAtEnd: false });
     harness.context.authoritativeReady = true;
     harness.driver.notifyAuthoritativeHistoryMaybeChanged();
     harness.driver.reevaluate();
@@ -340,10 +340,7 @@ describe("bottom anchor controller driver", () => {
     const harness = createDriverHarness();
 
     harness.driver.detachByUser();
-    harness.driver.handleContentSizeChange({
-      previousContentHeight: 1200,
-      contentHeight: 1500,
-    });
+    harness.driver.handleContentSizeChange();
     harness.driver.handleViewportMetricsChange({
       previousViewportWidth: 800,
       viewportWidth: 640,
@@ -356,7 +353,9 @@ describe("bottom anchor controller driver", () => {
     expect(harness.scrollAttempts).toHaveLength(0);
   });
 
-  it("pauses sticky maintenance while a user scroll owns the viewport", () => {
+  // While following, the list keeps its end through every content change, so a drag that kept
+  // following would see each streamed line move the rows under the finger.
+  it("stops following while a user scroll owns the viewport", () => {
     const harness = createDriverHarness({
       transportBehavior: {
         verificationDelayFrames: 2,
@@ -364,12 +363,8 @@ describe("bottom anchor controller driver", () => {
       },
     });
 
-    harness.driver.prepareForStickyContentChange();
     harness.driver.beginUserScroll();
-    harness.driver.handleContentSizeChange({
-      previousContentHeight: 1200,
-      contentHeight: 1400,
-    });
+    harness.driver.handleContentSizeChange();
     harness.context.nearBottom = false;
     harness.driver.handleScrollNearBottomChange({
       nextIsNearBottom: false,
@@ -377,19 +372,29 @@ describe("bottom anchor controller driver", () => {
     });
     harness.scheduler.flushAll();
 
-    expect(harness.scrollAttempts).toHaveLength(1);
-    expect(harness.driver.getSnapshot()).toMatchObject({
-      mode: "sticky-bottom",
-      pendingRequest: null,
-      pendingVerification: null,
-    });
+    expect(harness.scrollAttempts).toHaveLength(0);
+    expect(harness.driver.getSnapshot().mode).toBe("detached");
 
-    harness.driver.endUserScroll({ isNearBottom: false });
+    harness.driver.endUserScroll({ isAtEnd: false });
 
     expect(harness.driver.getSnapshot().mode).toBe("detached");
   });
 
-  it("restores sticky maintenance when a user scroll returns to the bottom", () => {
+  // Resuming would scroll by the distance left to the end in one frame, right after the release.
+  it("stays detached when a user scroll ends near the end but short of it", () => {
+    const harness = createDriverHarness();
+
+    harness.driver.beginUserScroll();
+    harness.context.nearBottom = true;
+    harness.driver.handleContentSizeChange();
+    harness.driver.endUserScroll({ isAtEnd: false });
+    harness.scheduler.flushAll();
+
+    expect(harness.driver.getSnapshot().mode).toBe("detached");
+    expect(harness.scrollAttempts).toHaveLength(0);
+  });
+
+  it("resumes following when a user scroll ends at the end", () => {
     const harness = createDriverHarness({
       transportBehavior: {
         verificationDelayFrames: 2,
@@ -403,16 +408,13 @@ describe("bottom anchor controller driver", () => {
       nextIsNearBottom: false,
       scrollDelta: 48,
     });
-    harness.driver.handleContentSizeChange({
-      previousContentHeight: 1200,
-      contentHeight: 1400,
-    });
+    harness.driver.handleContentSizeChange();
     harness.context.nearBottom = true;
     harness.driver.handleScrollNearBottomChange({
       nextIsNearBottom: true,
       scrollDelta: -48,
     });
-    harness.driver.endUserScroll({ isNearBottom: true });
+    harness.driver.endUserScroll({ isAtEnd: true });
     harness.scheduler.flushAll();
 
     expect(harness.driver.getSnapshot()).toMatchObject({
@@ -420,7 +422,55 @@ describe("bottom anchor controller driver", () => {
       pendingRequest: null,
       pendingVerification: null,
     });
-    expect(harness.scrollAttempts).toHaveLength(1);
+    // Following stopped for the gesture, so content that arrived meanwhile left the end below it.
+    expect(harness.scrollAttempts).toEqual([false]);
+  });
+
+  it("holds a disclosure detached and resumes following when it is released at the end", () => {
+    const harness = createDriverHarness({
+      transportBehavior: {
+        verificationDelayFrames: 2,
+        verificationRetryMode: "recheck",
+      },
+    });
+
+    harness.driver.holdForDisclosure();
+    harness.driver.handleContentSizeChange();
+    harness.driver.handleScrollNearBottomChange({
+      nextIsNearBottom: true,
+      scrollDelta: -12,
+    });
+    harness.scheduler.flushAll();
+
+    expect(harness.driver.getSnapshot().mode).toBe("detached");
+    expect(harness.scrollAttempts).toHaveLength(0);
+
+    harness.driver.releaseDisclosure({ isAtEnd: true });
+    harness.scheduler.flushAll();
+
+    expect(harness.driver.getSnapshot().mode).toBe("sticky-bottom");
+  });
+
+  it("stays detached when a disclosure is released away from the end", () => {
+    const harness = createDriverHarness();
+
+    harness.driver.holdForDisclosure();
+    harness.driver.releaseDisclosure({ isAtEnd: false });
+    harness.scheduler.flushAll();
+
+    expect(harness.driver.getSnapshot().mode).toBe("detached");
+    expect(harness.scrollAttempts).toHaveLength(0);
+  });
+
+  it("leaves a disclosure release to a user scroll that owns the viewport", () => {
+    const harness = createDriverHarness();
+
+    harness.driver.holdForDisclosure();
+    harness.driver.beginUserScroll();
+    harness.driver.releaseDisclosure({ isAtEnd: true });
+    harness.scheduler.flushAll();
+
+    expect(harness.driver.getSnapshot().mode).toBe("detached");
   });
 
   it("switches back to sticky-bottom for explicit jump-to-bottom", () => {
@@ -441,7 +491,7 @@ describe("bottom anchor controller driver", () => {
     expect(harness.driver.getSnapshot().mode).toBe("sticky-bottom");
   });
 
-  it("schedules sticky maintenance on viewport and content growth", () => {
+  it("scrolls for a viewport resize while following", () => {
     const harness = createDriverHarness();
 
     harness.driver.handleViewportMetricsChange({
@@ -452,13 +502,44 @@ describe("bottom anchor controller driver", () => {
     });
     harness.scheduler.flushAll();
 
-    harness.driver.handleContentSizeChange({
-      previousContentHeight: 1200,
-      contentHeight: 1600,
+    expect(harness.scrollAttempts).toHaveLength(1);
+  });
+
+  it("never scrolls for a content change while following", () => {
+    const harness = createDriverHarness({
+      transportBehavior: {
+        verificationDelayFrames: 2,
+        verificationRetryMode: "recheck",
+      },
     });
+
+    harness.context.measurementState.contentHeight = 1600;
+    harness.driver.handleContentSizeChange();
+    harness.context.measurementState.contentHeight = 1250;
+    harness.driver.handleContentSizeChange();
     harness.scheduler.flushAll();
 
-    expect(harness.scrollAttempts).toHaveLength(2);
+    expect(harness.scrollAttempts).toHaveLength(0);
+    expect(harness.driver.getSnapshot()).toMatchObject({
+      mode: "sticky-bottom",
+      pendingRequest: null,
+      pendingVerification: null,
+    });
+  });
+
+  it("detaches when the user scrolls away after a content change", () => {
+    const harness = createDriverHarness();
+
+    harness.context.measurementState.contentHeight = 1600;
+    harness.driver.handleContentSizeChange();
+    harness.context.nearBottom = false;
+    harness.driver.handleScrollNearBottomChange({
+      nextIsNearBottom: false,
+      scrollDelta: 4,
+    });
+
+    expect(harness.driver.getSnapshot().mode).toBe("detached");
+    expect(harness.scrollAttempts).toHaveLength(0);
   });
 
   it("keeps a pending request blocked when stale container measurements arrive", () => {
@@ -556,10 +637,7 @@ describe("bottom anchor controller driver", () => {
 
     harness.context.measurementState.contentHeight = 14804;
     harness.context.nearBottom = false;
-    harness.driver.handleContentSizeChange({
-      previousContentHeight: 14322,
-      contentHeight: 14804,
-    });
+    harness.driver.handleContentSizeChange();
 
     harness.scheduler.flushFrame();
 
@@ -628,10 +706,7 @@ describe("bottom anchor controller driver", () => {
 
     harness.context.measurementState.contentHeight = 16230;
     harness.context.nearBottom = false;
-    harness.driver.handleContentSizeChange({
-      previousContentHeight: 14322,
-      contentHeight: 16230,
-    });
+    harness.driver.handleContentSizeChange();
 
     harness.scheduler.flushFrame();
     harness.scheduler.flushFrame();
@@ -685,136 +760,6 @@ describe("bottom anchor controller driver", () => {
 
     expect(harness.driver.getSnapshot().mode).toBe("detached");
   });
-
-  it("keeps sticky-bottom during streaming growth until bottom is re-verified", () => {
-    const harness = createDriverHarness();
-    harness.context.nearBottom = false;
-    harness.setScrollToBottomBehavior(() => {
-      harness.context.measurementState.offsetY = 900;
-    });
-
-    harness.driver.handleContentSizeChange({
-      previousContentHeight: 1200,
-      contentHeight: 1400,
-    });
-    harness.scheduler.flushAll();
-
-    expect(harness.scrollAttempts).toHaveLength(4);
-    expect(harness.driver.getSnapshot()).toMatchObject({
-      mode: "sticky-bottom",
-      pendingRequest: null,
-      pendingVerification: null,
-    });
-
-    harness.driver.handleScrollNearBottomChange({
-      nextIsNearBottom: false,
-      scrollDelta: 0,
-    });
-
-    expect(harness.driver.getSnapshot().mode).toBe("sticky-bottom");
-
-    harness.context.nearBottom = true;
-    harness.driver.handleScrollNearBottomChange({
-      nextIsNearBottom: true,
-      scrollDelta: 0,
-    });
-    harness.scheduler.flushAll();
-    harness.driver.handleScrollNearBottomChange({
-      nextIsNearBottom: false,
-      scrollDelta: 64,
-    });
-
-    expect(harness.driver.getSnapshot().mode).toBe("detached");
-  });
-
-  it("keeps initial native content growth anchored before layout scroll events arrive", () => {
-    const harness = createDriverHarness({
-      transportBehavior: {
-        verificationDelayFrames: 2,
-        verificationRetryMode: "recheck",
-      },
-      measurementState: createMeasurementState({
-        containerKey: "native-virtualized",
-        viewportWidth: 0,
-        viewportHeight: 0,
-        contentHeight: 0,
-        offsetY: 0,
-        viewportMeasuredForKey: null,
-        contentMeasuredForKey: null,
-      }),
-    });
-    harness.setScrollToBottomBehavior(() => {
-      harness.context.measurementState.offsetY = 0;
-    });
-
-    harness.context.measurementState.contentHeight = 1348;
-    harness.context.measurementState.contentMeasuredForKey = "native-virtualized";
-    harness.driver.handleContentSizeChange({
-      previousContentHeight: 0,
-      contentHeight: 1348,
-    });
-
-    expect(harness.scrollAttempts).toHaveLength(1);
-    expect(harness.driver.getSnapshot()).toMatchObject({
-      mode: "sticky-bottom",
-      pendingVerification: {
-        requestId: null,
-      },
-    });
-
-    harness.context.measurementState.viewportWidth = 390;
-    harness.context.measurementState.viewportHeight = 546;
-    harness.context.measurementState.viewportMeasuredForKey = "native-virtualized";
-    harness.context.measurementState.offsetY = 50;
-    harness.context.nearBottom = false;
-    harness.driver.handleScrollNearBottomChange({
-      nextIsNearBottom: false,
-      scrollDelta: 50,
-    });
-
-    expect(harness.driver.getSnapshot().mode).toBe("sticky-bottom");
-  });
-
-  it("keeps native sticky content changes anchored when measured height is unchanged", () => {
-    const harness = createDriverHarness({
-      transportBehavior: {
-        verificationDelayFrames: 2,
-        verificationRetryMode: "recheck",
-      },
-      measurementState: createMeasurementState({
-        containerKey: "native-virtualized",
-        viewportWidth: 390,
-        viewportHeight: 546,
-        contentHeight: 546,
-        offsetY: 0,
-        viewportMeasuredForKey: "native-virtualized",
-        contentMeasuredForKey: "native-virtualized",
-      }),
-    });
-    harness.setScrollToBottomBehavior(() => {
-      harness.context.measurementState.offsetY = 0;
-      harness.context.nearBottom = true;
-    });
-
-    harness.driver.prepareForStickyContentChange();
-
-    expect(harness.scrollAttempts).toHaveLength(1);
-    expect(harness.driver.getSnapshot()).toMatchObject({
-      mode: "sticky-bottom",
-      pendingVerification: {
-        requestId: null,
-      },
-    });
-
-    harness.context.measurementState.offsetY = 50;
-    harness.context.nearBottom = false;
-    harness.driver.handleScrollNearBottomChange({
-      nextIsNearBottom: false,
-      scrollDelta: 50,
-    });
-
-    expect(harness.driver.getSnapshot().mode).toBe("sticky-bottom");
-  });
 });
 
 describe("controller helper predicates", () => {
@@ -864,13 +809,6 @@ describe("controller helper predicates", () => {
   it("suppresses auto-anchor helpers while detached", () => {
     const mode: BottomAnchorMode = "detached";
 
-    expect(
-      __private__.shouldRestickOnContentChange({
-        mode,
-        previousContentHeight: 1000,
-        contentHeight: 1100,
-      }),
-    ).toBe(false);
     expect(
       __private__.shouldRestickOnViewportChange({
         mode,
diff --git a/packages/app/src/agent-stream/bottom-anchor-controller.ts b/packages/app/src/agent-stream/bottom-anchor-controller.ts
index 93b3c075e7..84535caaf5 100644
--- a/packages/app/src/agent-stream/bottom-anchor-controller.ts
+++ b/packages/app/src/agent-stream/bottom-anchor-controller.ts
@@ -69,20 +69,18 @@ interface BottomAnchorControllerDriver {
   applyRouteRequest: (request: BottomAnchorRouteRequest | null) => void;
   requestLocalAnchor: (request: BottomAnchorLocalRequest) => void;
   beginUserScroll: () => void;
-  endUserScroll: (params: { isNearBottom: boolean }) => void;
+  endUserScroll: (params: { isAtEnd: boolean }) => void;
   detachByUser: () => void;
+  holdForDisclosure: () => void;
+  releaseDisclosure: (params: { isAtEnd: boolean }) => void;
   handleViewportMetricsChange: (params: {
     previousViewportWidth: number;
     viewportWidth: number;
     previousViewportHeight: number;
     viewportHeight: number;
   }) => void;
-  handleContentSizeChange: (params: {
-    previousContentHeight: number;
-    contentHeight: number;
-  }) => void;
+  handleContentSizeChange: () => void;
   prepareForStickyViewportChange: () => void;
-  prepareForStickyContentChange: () => void;
   handleScrollNearBottomChange: (params: {
     nextIsNearBottom: boolean;
     scrollDelta: number;
@@ -415,6 +413,7 @@ function createBottomAnchorControllerDriver(
       | "content_size_change"
       | "scroll_near_bottom_change"
       | "user_scroll_end"
+      | "disclosure_released"
       | "history_readiness_change"
       | "manual_reevaluate"
       | "retry_scroll",
@@ -505,13 +504,19 @@ function createBottomAnchorControllerDriver(
     requestLocalAnchor(request) {
       createRequest(request);
     },
+    // The gesture owns the viewport, so following stops until it ends: content growing at the end
+    // must not move the rows under the finger. The gesture's end decides whether following resumes.
     beginUserScroll() {
       isUserScrollActive = true;
       cancelPendingAttempt();
+      setModeInternal("detached");
     },
+    // Following resumes only for a gesture that ends at the end. Resuming from short of it would
+    // scroll the rows the finger just let go of, so a release above the end, or with output that
+    // arrived below it during the gesture, stays detached with the pill.
     endUserScroll(params) {
       isUserScrollActive = false;
-      if (params.isNearBottom) {
+      if (params.isAtEnd) {
         if (mode === "detached") {
           setModeInternal("sticky-bottom");
           pendingVerification = { requestId: null, retries: 0 };
@@ -533,9 +538,8 @@ function createBottomAnchorControllerDriver(
         markStickyMeasurementVerified();
         return;
       }
-      if (mode === "sticky-bottom") {
-        this.detachByUser();
-      }
+      cancelPendingRequest("user_scrolled_away");
+      setModeInternal("detached");
     },
     detachByUser() {
       if (mode === "detached") {
@@ -544,6 +548,21 @@ function createBottomAnchorControllerDriver(
       cancelPendingRequest("user_scrolled_away");
       setModeInternal("detached");
     },
+    // A disclosure keeps its trigger in place, so following output stops while it applies.
+    holdForDisclosure() {
+      cancelPendingRequest("disclosure");
+      setModeInternal("detached");
+    },
+    // Following resumes only if the applied change left the list at its end. Scroll events
+    // during the hold never re-stick: before the change lands the list is still at the end.
+    releaseDisclosure(params) {
+      if (isUserScrollActive || mode !== "detached" || !params.isAtEnd) {
+        return;
+      }
+      setModeInternal("sticky-bottom");
+      pendingVerification = { requestId: null, retries: 0 };
+      evaluate(false, "disclosure_released");
+    },
     handleViewportMetricsChange(params) {
       if (
         params.previousViewportWidth !== params.viewportWidth ||
@@ -568,30 +587,13 @@ function createBottomAnchorControllerDriver(
         evaluate(false, "viewport_change");
       }
     },
-    handleContentSizeChange(params) {
-      if (params.previousContentHeight !== params.contentHeight) {
-        markStickyMeasurementChanged();
-      }
-      if (isUserScrollActive) {
+    // The list keeps its own end through content changes while following, so a change in content
+    // height never scrolls from here. It only gives a pending jump another look at the new geometry.
+    handleContentSizeChange() {
+      if (isUserScrollActive || !pendingRequest) {
         return;
       }
-      const shouldRestick = __private__.shouldRestickOnContentChange({
-        mode,
-        previousContentHeight: params.previousContentHeight,
-        contentHeight: params.contentHeight,
-      });
-      if (shouldRestick && !pendingRequest) {
-        pendingVerification = { requestId: null, retries: 0 };
-        if (attemptHandle) {
-          input.cancelFrame(attemptHandle);
-          attemptHandle = null;
-        }
-        runAttempt(false);
-        return;
-      }
-      if (shouldRestick || pendingRequest) {
-        evaluate(false, "content_size_change");
-      }
+      evaluate(false, "content_size_change");
     },
     prepareForStickyViewportChange() {
       if (mode !== "sticky-bottom") {
@@ -599,25 +601,6 @@ function createBottomAnchorControllerDriver(
       }
       markStickyMeasurementChanged();
     },
-    prepareForStickyContentChange() {
-      if (mode !== "sticky-bottom") {
-        return;
-      }
-      markStickyMeasurementChanged();
-      if (isUserScrollActive) {
-        return;
-      }
-      if (!pendingRequest) {
-        pendingVerification = { requestId: null, retries: 0 };
-        if (attemptHandle) {
-          input.cancelFrame(attemptHandle);
-          attemptHandle = null;
-        }
-        runAttempt(false);
-        return;
-      }
-      evaluate(false, "content_size_change");
-    },
     handleScrollNearBottomChange(params) {
       const { nextIsNearBottom, scrollDelta } = params;
       if (isUserScrollActive) {
@@ -695,13 +678,6 @@ export const __private__ = {
           input.previousViewportWidth !== input.viewportWidth))
     );
   },
-  shouldRestickOnContentChange(input: {
-    mode: BottomAnchorMode;
-    previousContentHeight: number;
-    contentHeight: number;
-  }): boolean {
-    return input.mode === "sticky-bottom" && input.contentHeight > input.previousContentHeight;
-  },
   shouldDetachFromScrollAway(input: {
     mode: BottomAnchorMode;
     nextIsNearBottom: boolean;
@@ -792,12 +768,18 @@ export function useBottomAnchorController(input: {
     beginUserScroll() {
       driverRef.current?.beginUserScroll();
     },
-    endUserScroll(params: { isNearBottom: boolean }) {
+    endUserScroll(params: { isAtEnd: boolean }) {
       driverRef.current?.endUserScroll(params);
     },
     detachByUser() {
       driverRef.current?.detachByUser();
     },
+    holdForDisclosure() {
+      driverRef.current?.holdForDisclosure();
+    },
+    releaseDisclosure(params: { isAtEnd: boolean }) {
+      driverRef.current?.releaseDisclosure(params);
+    },
     handleViewportLayout() {},
     handleViewportMetricsChange(params: {
       previousViewportWidth: number;
@@ -807,15 +789,12 @@ export function useBottomAnchorController(input: {
     }) {
       driverRef.current?.handleViewportMetricsChange(params);
     },
-    handleContentSizeChange(params: { previousContentHeight: number; contentHeight: number }) {
-      driverRef.current?.handleContentSizeChange(params);
+    handleContentSizeChange() {
+      driverRef.current?.handleContentSizeChange();
     },
     prepareForStickyViewportChange() {
       driverRef.current?.prepareForStickyViewportChange();
     },
-    prepareForStickyContentChange() {
-      driverRef.current?.prepareForStickyContentChange();
-    },
     handleScrollNearBottomChange(params: { nextIsNearBottom: boolean; scrollDelta: number }) {
       driverRef.current?.handleScrollNearBottomChange(params);
     },
diff --git a/packages/app/src/agent-stream/chat-find/viewport.browser.test.ts b/packages/app/src/agent-stream/chat-find/viewport.browser.test.ts
index 1b4b8d18e8..876c615577 100644
--- a/packages/app/src/agent-stream/chat-find/viewport.browser.test.ts
+++ b/packages/app/src/agent-stream/chat-find/viewport.browser.test.ts
@@ -24,7 +24,9 @@ function viewport(root: HTMLElement, capture: Capture) {
   const handle: StreamViewportHandle = {
     scrollToBottom() {},
     prepareForViewportChange() {},
-    holdReadingPosition() {},
+    holdRow(_rowId, apply) {
+      apply();
+    },
     scrollToMessage(_messageId, occurrence) {
       if (occurrence) capture.occurrence = occurrence;
     },
diff --git a/packages/app/src/agent-stream/chat-outline/use-chat-outline.test.tsx b/packages/app/src/agent-stream/chat-outline/use-chat-outline.test.tsx
index 890f6eaae7..1ca917f0b3 100644
--- a/packages/app/src/agent-stream/chat-outline/use-chat-outline.test.tsx
+++ b/packages/app/src/agent-stream/chat-outline/use-chat-outline.test.tsx
@@ -265,7 +265,7 @@ describe("useChatOutline", () => {
     const viewport: StreamViewportHandle = {
       scrollToBottom: vi.fn(),
       prepareForViewportChange: vi.fn(),
-      holdReadingPosition: vi.fn(),
+      holdRow: vi.fn(),
       scrollToMessage,
     };
     const viewportRef = { current: viewport };
@@ -317,7 +317,7 @@ describe("useChatOutline", () => {
       current: {
         scrollToBottom: vi.fn(),
         prepareForViewportChange: vi.fn(),
-        holdReadingPosition: vi.fn(),
+        holdRow: vi.fn(),
         scrollToMessage,
       },
     };
@@ -373,7 +373,7 @@ describe("useChatOutline", () => {
     const viewport: StreamViewportHandle = {
       scrollToBottom: vi.fn(),
       prepareForViewportChange: vi.fn(),
-      holdReadingPosition: vi.fn(),
+      holdRow: vi.fn(),
       scrollToMessage,
     };
     const livePrompt = {
diff --git a/packages/app/src/agent-stream/disclosure.tsx b/packages/app/src/agent-stream/disclosure.tsx
new file mode 100644
index 0000000000..b35e67e567
--- /dev/null
+++ b/packages/app/src/agent-stream/disclosure.tsx
@@ -0,0 +1,40 @@
+import { createContext, useContext, useMemo, type ReactNode, type RefObject } from "react";
+import type { StreamViewportHandle } from "./strategy";
+
+/**
+ * Runs a disclosure's state change. Inside a timeline row, the row that owns the
+ * trigger keeps its screen position through the change; elsewhere `apply` runs as is.
+ */
+export type DisclosureHold = (apply: () => void) => void;
+
+const applyInPlace: DisclosureHold = (apply) => apply();
+
+const DisclosureHoldContext = createContext<DisclosureHold>(applyInPlace);
+
+export function DisclosureRow({
+  rowId,
+  viewportRef,
+  children,
+}: {
+  rowId: string;
+  viewportRef: RefObject<StreamViewportHandle | null>;
+  children: ReactNode;
+}) {
+  const hold = useMemo<DisclosureHold>(
+    () => (apply) => {
+      const viewport = viewportRef.current;
+      if (viewport) {
+        viewport.holdRow(rowId, apply);
+      } else {
+        apply();
+      }
+    },
+    [rowId, viewportRef],
+  );
+  return <DisclosureHoldContext.Provider value={hold}>{children}</DisclosureHoldContext.Provider>;
+}
+
+/** Call with the toggle's state change: `hold(() => setExpanded(!expanded))`. */
+export function useDisclosureHold(): DisclosureHold {
+  return useContext(DisclosureHoldContext);
+}
diff --git a/packages/app/src/agent-stream/footer-spacing.test.ts b/packages/app/src/agent-stream/footer-spacing.test.ts
index 341ce75583..e3e28ab0bc 100644
--- a/packages/app/src/agent-stream/footer-spacing.test.ts
+++ b/packages/app/src/agent-stream/footer-spacing.test.ts
@@ -3,32 +3,13 @@ import type { TurnTiming } from "@/timeline/turn-time";
 import type { StreamItem } from "@/types/stream";
 import { layoutStream } from "./layout";
 import type { StreamStrategy } from "./strategy";
+import { resolveStreamRenderStrategy } from "./strategy-resolver";
 
 function strategyFor(platform: "web" | "native"): StreamStrategy {
-  const inverted = platform === "native";
-  const neighborStep = inverted ? 1 : -1;
-  const getHistoryBoundaryIndex = (items: StreamItem[]) => {
-    if (items.length === 0) return null;
-    return inverted ? 0 : items.length - 1;
-  };
-  const getLiveHeadBoundaryIndex = (items: StreamItem[]) => {
-    if (items.length === 0) return null;
-    return inverted ? items.length - 1 : 0;
-  };
-  return {
-    orderTail: (items) => (inverted ? [...items].toReversed() : items),
-    orderHead: (items) => (inverted ? [...items].toReversed() : items),
-    getNeighborIndex: (index, relation) =>
-      relation === "above" ? index + neighborStep : index - neighborStep,
-    getNeighborItem: (items, index, relation) => {
-      const neighborIndex = relation === "above" ? index + neighborStep : index - neighborStep;
-      return items[neighborIndex];
-    },
-    getHistoryLiveBoundaryIndex: getHistoryBoundaryIndex,
-    getLiveHeadHistoryBoundaryIndex: getLiveHeadBoundaryIndex,
-    getLatestItemIndex: getHistoryBoundaryIndex,
-    getFrameChildOrder: () => (inverted ? "footer-then-content" : "content-then-footer"),
-  } as StreamStrategy;
+  return resolveStreamRenderStrategy({
+    platform: platform === "native" ? "android" : "web",
+    isMobileBreakpoint: false,
+  });
 }
 
 function userMessage(id: string): Extract<StreamItem, { kind: "user_message" }> {
diff --git a/packages/app/src/agent-stream/layout.test.ts b/packages/app/src/agent-stream/layout.test.ts
index a86817b6a7..fde9a3a342 100644
--- a/packages/app/src/agent-stream/layout.test.ts
+++ b/packages/app/src/agent-stream/layout.test.ts
@@ -289,7 +289,7 @@ describe("layoutStream", () => {
     expect(layout.auxiliaryTurnFooter).toBeNull();
     expect(assistantRow.completedFooter?.itemId).toBe(assistant.id);
     expect(assistantRow.belowItem?.id).toBe("u2");
-    expect(assistantRow.frameOrder).toBe("footer-then-content");
+    expect(assistantRow.frameOrder).toBe("content-then-footer");
   });
 
   it("keeps an accepted steer inline while its canonical turn is active", () => {
diff --git a/packages/app/src/agent-stream/legend-list-held-row.browser.test.tsx b/packages/app/src/agent-stream/legend-list-held-row.browser.test.tsx
new file mode 100644
index 0000000000..cc52429b23
--- /dev/null
+++ b/packages/app/src/agent-stream/legend-list-held-row.browser.test.tsx
@@ -0,0 +1,171 @@
+import { LegendList, type LegendListRef } from "@legendapp/list/react-native";
+import React, { act, useSyncExternalStore } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { View } from "react-native";
+import { afterEach, beforeEach, expect, it } from "vitest";
+
+// The native chat timeline runs on the patched LegendList (patches/@legendapp+list+3.7.1.patch).
+// A disclosure hold keeps only the held row in place: `shouldRestorePosition` accepts no other row.
+// The native build applies its scroll adjustments through native scroll props that
+// react-native-web ignores, so these tests read the offset LegendList holds, not the DOM's.
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const VIEWPORT_HEIGHT = 100;
+
+interface Row {
+  id: string;
+  height: number;
+}
+
+let root: Root;
+let host: HTMLDivElement;
+
+beforeEach(() => {
+  host = document.createElement("div");
+  host.style.cssText = `display:flex;flex-direction:column;width:300px;height:${VIEWPORT_HEIGHT}px`;
+  document.body.appendChild(host);
+  root = createRoot(host);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  grownHeights.clear();
+  host.remove();
+});
+
+function wait(ms: number): Promise<void> {
+  return act(() => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+}
+
+const LIST_STYLE = { flex: 1 };
+const rowStyles = new Map<number, { height: number }>();
+
+function rowStyle(height: number) {
+  let style = rowStyles.get(height);
+  if (!style) {
+    style = { height };
+    rowStyles.set(height, style);
+  }
+  return style;
+}
+
+// A row that changes its own height without a data change, like a todo card toggling its details.
+const grownHeights = new Map<string, number>();
+const heightListeners = new Set<() => void>();
+
+function subscribeToHeights(listener: () => void) {
+  heightListeners.add(listener);
+  return () => heightListeners.delete(listener);
+}
+
+function growRow(id: string, height: number) {
+  grownHeights.set(id, height);
+  for (const listener of heightListeners) listener();
+}
+
+function RowView({ row }: { row: Row }) {
+  const height = useSyncExternalStore(
+    subscribeToHeights,
+    () => grownHeights.get(row.id) ?? row.height,
+  );
+  return <View style={rowStyle(height)} />;
+}
+
+function renderRow({ item }: { item: Row }) {
+  return <RowView row={item} />;
+}
+
+function holdOnly(heldRowId: string) {
+  return {
+    data: true,
+    size: true,
+    shouldRestorePosition: (item: Row) => item.id === heldRowId,
+  };
+}
+
+function keyExtractor(item: Row) {
+  return item.id;
+}
+
+function mountList(heldRowId: string) {
+  const listRef = React.createRef<LegendListRef>();
+  const maintainVisibleContentPosition = holdOnly(heldRowId);
+  const render = (data: Row[]) =>
+    act(() =>
+      root.render(
+        <LegendList
+          ref={listRef}
+          data={data}
+          renderItem={renderRow}
+          keyExtractor={keyExtractor}
+          estimatedItemSize={40}
+          recycleItems={false}
+          scrollEventThrottle={16}
+          maintainVisibleContentPosition={maintainVisibleContentPosition}
+          style={LIST_STYLE}
+        />,
+      ),
+    );
+  const scrollElement = () => {
+    const scroller = [...host.querySelectorAll<HTMLElement>("div")].find(
+      (element) => element.scrollHeight > element.clientHeight + 1,
+    );
+    if (!scroller) throw new Error("The list has no scroll element");
+    return scroller;
+  };
+  // Small steps: a large jump suspends LegendList's anchoring until the rows re-measure.
+  const scrollTo = async (offset: number) => {
+    for (let step = 20; step <= offset; step += 20) {
+      scrollElement().scrollTop = step;
+      await wait(150);
+    }
+  };
+  const heldRowTop = () => {
+    const state = listRef.current?.getState();
+    const position = state?.positionByKey(heldRowId);
+    if (state === undefined || position === undefined) {
+      throw new Error("The held row is not laid out");
+    }
+    return position - state.scroll;
+  };
+  return { render, scrollTo, heldRowTop };
+}
+
+it("anchors a data change on a held row whose top is above the viewport", async () => {
+  // The held row is a turn host whose prompt bubble is cut off at the top of the viewport, with a
+  // fully visible row below it. LegendList's ids in view start at that fully visible row.
+  const rows: Row[] = Array.from({ length: 10 }, (_, index) => ({
+    id: `row-${index}`,
+    height: index === 3 ? 60 : 40,
+  }));
+  const list = mountList("row-3");
+  list.render(rows);
+  await wait(150);
+  await list.scrollTo(140);
+  expect(list.heldRowTop()).toBe(-20);
+
+  const inserted: Row = { id: "inserted", height: 30 };
+  list.render([...rows.slice(0, 2), inserted, ...rows.slice(2)]);
+  await wait(150);
+
+  expect(list.heldRowTop()).toBe(-20);
+});
+
+it("anchors a size change on a held row whose top is above the viewport", async () => {
+  // The same cut-off row grows from its own state, so LegendList sees a size change only.
+  const rows: Row[] = Array.from({ length: 10 }, (_, index) => ({
+    id: `row-${index}`,
+    height: index === 3 ? 60 : 40,
+  }));
+  const list = mountList("row-3");
+  list.render(rows);
+  await wait(150);
+  await list.scrollTo(140);
+  expect(list.heldRowTop()).toBe(-20);
+
+  act(() => growRow("row-3", 260));
+  await wait(150);
+
+  expect(list.heldRowTop()).toBe(-20);
+});
diff --git a/packages/app/src/agent-stream/model.test.ts b/packages/app/src/agent-stream/model.test.ts
index 9c6ef3384d..bf6ce27f75 100644
--- a/packages/app/src/agent-stream/model.test.ts
+++ b/packages/app/src/agent-stream/model.test.ts
@@ -47,7 +47,7 @@ describe("buildAgentStreamRenderModel", () => {
       historyStart: 2,
     });
 
-    expect(model.history.map((item) => item.id)).toEqual(["a3", "u3", "a2", "u2"]);
+    expect(model.history.map((item) => item.id)).toEqual(["u2", "a2", "u3", "a3"]);
     expect(model.segments.historyVirtualized).toHaveLength(0);
   });
 
@@ -98,7 +98,7 @@ describe("buildAgentStreamRenderModel", () => {
       historyStart,
     });
 
-    expect(model.history.map((item) => item.id)).toEqual(["visible-a", "visible-u"]);
+    expect(model.history.map((item) => item.id)).toEqual(["visible-u", "visible-a"]);
   });
 
   it("keeps head separate from committed history on desktop web", () => {
@@ -207,7 +207,7 @@ describe("buildAgentStreamRenderModel", () => {
     });
   });
 
-  it("derives the same timing for native inverted rendering", () => {
+  it("derives the same timing on native", () => {
     const tail = [userMessage("u1", 1), assistantMessage("a1", 4)];
 
     const model = buildAgentStreamRenderModel({
@@ -219,7 +219,7 @@ describe("buildAgentStreamRenderModel", () => {
       isMobileBreakpoint: false,
     });
 
-    expect(model.segments.historyMounted.map((item) => item.id)).toEqual(["a1", "u1"]);
+    expect(model.segments.historyMounted.map((item) => item.id)).toEqual(["u1", "a1"]);
     expect(model.turnTiming.byItemId.get("a1")).toEqual({
       completedAt: tail[1]?.timestamp,
       durationMs: 3000,
diff --git a/packages/app/src/agent-stream/native-disclosure-hold.test.ts b/packages/app/src/agent-stream/native-disclosure-hold.test.ts
new file mode 100644
index 0000000000..b732edbb01
--- /dev/null
+++ b/packages/app/src/agent-stream/native-disclosure-hold.test.ts
@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+import { createNativeDisclosureHold } from "./native-disclosure-hold";
+
+function createFrames() {
+  let nextId = 1;
+  const pending = new Map<number, () => void>();
+  return {
+    requestFrame: (callback: () => void) => {
+      const id = nextId++;
+      pending.set(id, callback);
+      return id;
+    },
+    cancelFrame: (id: number) => {
+      pending.delete(id);
+    },
+    runFrame: () => {
+      const callbacks = [...pending.values()];
+      pending.clear();
+      for (const callback of callbacks) {
+        callback();
+      }
+    },
+  };
+}
+
+function createHarness() {
+  const frames = createFrames();
+  const releases: string[] = [];
+  const hold = createNativeDisclosureHold({
+    quietFrames: 2,
+    requestFrame: frames.requestFrame,
+    cancelFrame: frames.cancelFrame,
+    onRelease: () => releases.push("released"),
+  });
+  return { frames, hold, releases };
+}
+
+describe("native disclosure hold", () => {
+  it("holds the row until two frames pass without an item size change", () => {
+    const { frames, hold, releases } = createHarness();
+
+    hold.hold("turn-1");
+    frames.runFrame();
+
+    expect(hold.heldRowId()).toBe("turn-1");
+    expect(releases).toEqual([]);
+
+    frames.runFrame();
+
+    expect(hold.heldRowId()).toBeNull();
+    expect(releases).toEqual(["released"]);
+  });
+
+  it("restarts the quiet frames on every item size change", () => {
+    const { frames, hold, releases } = createHarness();
+
+    hold.hold("turn-1");
+    frames.runFrame();
+    hold.noteItemSizeChanged();
+    frames.runFrame();
+
+    expect(releases).toEqual([]);
+
+    frames.runFrame();
+
+    expect(releases).toEqual(["released"]);
+  });
+
+  it("ignores item size changes outside a hold", () => {
+    const { frames, hold, releases } = createHarness();
+
+    hold.noteItemSizeChanged();
+    frames.runFrame();
+    frames.runFrame();
+
+    expect(releases).toEqual([]);
+  });
+
+  it("moves the hold to the latest toggled row and releases once", () => {
+    const { frames, hold, releases } = createHarness();
+
+    hold.hold("turn-1");
+    frames.runFrame();
+    hold.hold("turn-2");
+
+    expect(hold.heldRowId()).toBe("turn-2");
+
+    frames.runFrame();
+    frames.runFrame();
+
+    expect(releases).toEqual(["released"]);
+  });
+
+  it("drops the hold without releasing when cancelled", () => {
+    const { frames, hold, releases } = createHarness();
+
+    hold.hold("turn-1");
+    hold.cancel();
+    frames.runFrame();
+    frames.runFrame();
+
+    expect(hold.heldRowId()).toBeNull();
+    expect(releases).toEqual([]);
+  });
+});
diff --git a/packages/app/src/agent-stream/native-disclosure-hold.ts b/packages/app/src/agent-stream/native-disclosure-hold.ts
new file mode 100644
index 0000000000..96b5087b98
--- /dev/null
+++ b/packages/app/src/agent-stream/native-disclosure-hold.ts
@@ -0,0 +1,64 @@
+/**
+ * The native viewport's disclosure hold. While a row is held, it is the only row the list may
+ * anchor on. The hold ends once item sizes stop changing for `quietFrames` frames: the list
+ * measures the toggled row and any rows it inserted over one or more frames, and end following
+ * must not resume between the change and the list's last layout correction.
+ */
+export interface NativeDisclosureHold {
+  heldRowId(): string | null;
+  hold(rowId: string): void;
+  noteItemSizeChanged(): void;
+  cancel(): void;
+}
+
+export function createNativeDisclosureHold(input: {
+  quietFrames: number;
+  requestFrame: (callback: () => void) => number;
+  cancelFrame: (id: number) => void;
+  onRelease: () => void;
+}): NativeDisclosureHold {
+  let heldRowId: string | null = null;
+  let frameId: number | null = null;
+  let remainingFrames = 0;
+
+  const stopCountdown = () => {
+    if (frameId !== null) {
+      input.cancelFrame(frameId);
+      frameId = null;
+    }
+  };
+
+  const tick = () => {
+    remainingFrames -= 1;
+    if (remainingFrames > 0) {
+      frameId = input.requestFrame(tick);
+      return;
+    }
+    frameId = null;
+    heldRowId = null;
+    input.onRelease();
+  };
+
+  const restartCountdown = () => {
+    stopCountdown();
+    remainingFrames = input.quietFrames;
+    frameId = input.requestFrame(tick);
+  };
+
+  return {
+    heldRowId: () => heldRowId,
+    hold(rowId) {
+      heldRowId = rowId;
+      restartCountdown();
+    },
+    noteItemSizeChanged() {
+      if (heldRowId !== null) {
+        restartCountdown();
+      }
+    },
+    cancel() {
+      stopCountdown();
+      heldRowId = null;
+    },
+  };
+}
diff --git a/packages/app/src/agent-stream/native-end-pin.tsx b/packages/app/src/agent-stream/native-end-pin.tsx
new file mode 100644
index 0000000000..dced2bf4a0
--- /dev/null
+++ b/packages/app/src/agent-stream/native-end-pin.tsx
@@ -0,0 +1,61 @@
+import { forwardRef, type ReactNode } from "react";
+import {
+  Animated,
+  type ScrollView,
+  type ScrollViewProps,
+  View,
+  type ViewStyle,
+} from "react-native";
+
+// While the stream follows its end, React Native's native content-position keeping holds a
+// zero-height view at the bottom of the content still. It runs on the UI thread around each mount,
+// so a row that grows or lands at the end scrolls in the same frame it lays out. LegendList's
+// `maintainScrollAtEnd` scrolls from JS after the mount, which paints the growth below the viewport
+// for a frame or more first.
+//
+// The anchor has to be the content's first native child: content-position keeping anchors on the
+// first child at or after `minIndexForVisible` that reaches into the viewport, and every child
+// LegendList renders can be flattened away. Absolute positioning keeps it out of the flow.
+//
+// A drag owns the offset from the frame it begins, but the pin stays until JS stops following a
+// round trip later. The scroll view subclasses in `modules/paseo-scroll` recognise the pin by its
+// native ID and skip its correction while the user drags, so a line mounting in those frames grows
+// below the rows under the finger.
+const END_PIN_NATIVE_ID = "paseo-end-pin";
+const END_ANCHOR_STYLE: ViewStyle = {
+  position: "absolute",
+  bottom: 0,
+  left: 0,
+  height: 0,
+  width: 0,
+};
+const END_ANCHOR_POSITION = { minIndexForVisible: 0 };
+
+interface EndPinnedScrollViewProps extends ScrollViewProps {
+  pinEnd: boolean;
+  children?: ReactNode;
+}
+
+export const EndPinnedScrollView = forwardRef<ScrollView, EndPinnedScrollViewProps>(
+  function EndPinnedScrollView({ pinEnd, children, maintainVisibleContentPosition, ...rest }, ref) {
+    return (
+      <Animated.ScrollView
+        {...rest}
+        ref={ref}
+        maintainVisibleContentPosition={
+          pinEnd ? END_ANCHOR_POSITION : maintainVisibleContentPosition
+        }
+      >
+        {pinEnd ? (
+          <View
+            collapsable={false}
+            nativeID={END_PIN_NATIVE_ID}
+            pointerEvents="none"
+            style={END_ANCHOR_STYLE}
+          />
+        ) : null}
+        {children}
+      </Animated.ScrollView>
+    );
+  },
+);
diff --git a/packages/app/src/agent-stream/native-scroll-animation.test.ts b/packages/app/src/agent-stream/native-scroll-animation.test.ts
index 947b8c3d1d..10508154a8 100644
--- a/packages/app/src/agent-stream/native-scroll-animation.test.ts
+++ b/packages/app/src/agent-stream/native-scroll-animation.test.ts
@@ -4,31 +4,48 @@ import { shouldAnimateNativeScrollToBottom } from "./native-scroll-animation";
 describe("native scroll-to-bottom animation", () => {
   it("jumps across unmounted history instead of animating through blank rows", () => {
     expect(
-      shouldAnimateNativeScrollToBottom({ offsetY: 60_000, viewportHeight: 600, windowSize: 10 }),
+      shouldAnimateNativeScrollToBottom({
+        distanceFromEnd: 60_000,
+        viewportHeight: 600,
+        drawDistance: 2000,
+      }),
     ).toBe(false);
   });
 
-  it("keeps near-bottom movement eligible for animation", () => {
+  it("keeps near-end movement eligible for animation", () => {
     expect(
-      shouldAnimateNativeScrollToBottom({ offsetY: 300, viewportHeight: 600, windowSize: 10 }),
+      shouldAnimateNativeScrollToBottom({
+        distanceFromEnd: 300,
+        viewportHeight: 600,
+        drawDistance: 2000,
+      }),
     ).toBe(true);
   });
 
-  it("bounds travel by the bottom-side overscan, not the whole window", () => {
+  it("bounds travel by the rows mounted below the viewport", () => {
     expect(
-      shouldAnimateNativeScrollToBottom({ offsetY: 2700, viewportHeight: 600, windowSize: 10 }),
+      shouldAnimateNativeScrollToBottom({
+        distanceFromEnd: 1000,
+        viewportHeight: 600,
+        drawDistance: 2000,
+      }),
     ).toBe(true);
     expect(
-      shouldAnimateNativeScrollToBottom({ offsetY: 2701, viewportHeight: 600, windowSize: 10 }),
-    ).toBe(false);
-    expect(
-      shouldAnimateNativeScrollToBottom({ offsetY: 1500, viewportHeight: 600, windowSize: 5 }),
+      shouldAnimateNativeScrollToBottom({
+        distanceFromEnd: 1001,
+        viewportHeight: 600,
+        drawDistance: 2000,
+      }),
     ).toBe(false);
   });
 
   it("does not animate before the viewport has been measured", () => {
     expect(
-      shouldAnimateNativeScrollToBottom({ offsetY: 0, viewportHeight: 0, windowSize: 10 }),
+      shouldAnimateNativeScrollToBottom({
+        distanceFromEnd: 0,
+        viewportHeight: 0,
+        drawDistance: 2000,
+      }),
     ).toBe(false);
   });
 });
diff --git a/packages/app/src/agent-stream/native-scroll-animation.ts b/packages/app/src/agent-stream/native-scroll-animation.ts
index 72bc39108c..bd5a4966b6 100644
--- a/packages/app/src/agent-stream/native-scroll-animation.ts
+++ b/packages/app/src/agent-stream/native-scroll-animation.ts
@@ -1,10 +1,10 @@
 export function shouldAnimateNativeScrollToBottom(input: {
-  offsetY: number;
+  distanceFromEnd: number;
   viewportHeight: number;
-  windowSize: number;
+  drawDistance: number;
 }): boolean {
-  // VirtualizedList splits the extra window around the viewport. An animated
-  // jump farther than the bottom-side overscan crosses unmounted history.
-  const bottomOverscanHeight = ((input.windowSize - 1) / 2) * input.viewportHeight;
-  return input.viewportHeight > 0 && input.offsetY <= bottomOverscanHeight;
+  // Scrolled away from the end, LegendList keeps half its draw distance mounted below the
+  // viewport. An animated jump farther than that crosses rows it has not rendered.
+  const mountedBelowViewport = input.drawDistance / 2;
+  return input.viewportHeight > 0 && input.distanceFromEnd <= mountedBelowViewport;
 }
diff --git a/packages/app/src/agent-stream/near-bottom.ts b/packages/app/src/agent-stream/near-bottom.ts
new file mode 100644
index 0000000000..19de04b11a
--- /dev/null
+++ b/packages/app/src/agent-stream/near-bottom.ts
@@ -0,0 +1,44 @@
+import { useState, useSyncExternalStore } from "react";
+
+/**
+ * Whether the reader is at the end of the timeline. The viewport writes it and only the
+ * scroll-to-bottom button reads it, so detaching from the end (a scroll, or a disclosure
+ * that opens below its trigger) re-renders the button and not the timeline.
+ */
+export interface NearBottom {
+  set: (value: boolean) => void;
+  subscribe: (listener: () => void) => () => void;
+  get: () => boolean;
+}
+
+function createNearBottom(): NearBottom {
+  let value = true;
+  const listeners = new Set<() => void>();
+  return {
+    set: (next) => {
+      if (next === value) return;
+      value = next;
+      for (const listener of listeners) listener();
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    get: () => value,
+  };
+}
+
+/** One per viewed agent; a newly viewed agent starts at the end. */
+export function useNearBottom(agentId: string): NearBottom {
+  const [owner, setOwner] = useState(() => ({ agentId, nearBottom: createNearBottom() }));
+  if (owner.agentId === agentId) return owner.nearBottom;
+  const next = { agentId, nearBottom: createNearBottom() };
+  setOwner(next);
+  return next.nearBottom;
+}
+
+export function useIsNearBottom(nearBottom: NearBottom): boolean {
+  return useSyncExternalStore(nearBottom.subscribe, nearBottom.get, nearBottom.get);
+}
diff --git a/packages/app/src/agent-stream/new-row-estimates.test.ts b/packages/app/src/agent-stream/new-row-estimates.test.ts
new file mode 100644
index 0000000000..d38c3fe3e0
--- /dev/null
+++ b/packages/app/src/agent-stream/new-row-estimates.test.ts
@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+import { createNewRowEstimates } from "./new-row-estimates";
+
+interface Row {
+  id: string;
+  kind: string;
+}
+
+function row(id: string, kind = "assistant_message"): Row {
+  return { id, kind };
+}
+
+describe("new row estimates", () => {
+  it("leaves rows of the first list to the list's averages", () => {
+    const estimates = createNewRowEstimates<Row>();
+    const first = row("a");
+
+    estimates.noteRows([first]);
+
+    expect(estimates.estimate(first)).toBeUndefined();
+  });
+
+  it("estimates a new row at the first measured size of the last new row of its kind", () => {
+    const estimates = createNewRowEstimates<Row>();
+    estimates.noteRows([row("a")]);
+    const second = row("b");
+    estimates.noteRows([row("a"), second]);
+
+    expect(estimates.estimate(second)).toBeUndefined();
+
+    estimates.noteMeasured(second, 34);
+    estimates.noteMeasured(second, 56);
+    const third = row("c");
+    estimates.noteRows([row("a"), second, third]);
+
+    expect(estimates.estimate(third)).toBe(34);
+  });
+
+  it("keeps sizes per kind", () => {
+    const estimates = createNewRowEstimates<Row>();
+    estimates.noteRows([]);
+    const text = row("a");
+    const tool = row("b", "tool_call");
+    estimates.noteRows([text, tool]);
+    estimates.noteMeasured(text, 34);
+    estimates.noteMeasured(tool, 36);
+    const nextTool = row("c", "tool_call");
+    const nextText = row("d");
+    estimates.noteRows([text, tool, nextTool, nextText]);
+
+    expect(estimates.estimate(nextTool)).toBe(36);
+    expect(estimates.estimate(nextText)).toBe(34);
+  });
+
+  it("records the kind a row has when it is measured", () => {
+    const estimates = createNewRowEstimates<Row>();
+    estimates.noteRows([]);
+    estimates.noteRows([row("a", "thought")]);
+    estimates.noteMeasured(row("a", "tool_call"), 36);
+    const thought = row("b", "thought");
+    const tool = row("c", "tool_call");
+    estimates.noteRows([row("a", "tool_call"), thought, tool]);
+
+    expect(estimates.estimate(thought)).toBeUndefined();
+    expect(estimates.estimate(tool)).toBe(36);
+  });
+
+  it("estimates new rows anywhere in the list", () => {
+    const estimates = createNewRowEstimates<Row>();
+    estimates.noteRows([row("b"), row("d")]);
+    const appendedTool = row("e", "tool_call");
+    estimates.noteRows([row("b"), row("d"), appendedTool]);
+    estimates.noteMeasured(appendedTool, 36);
+    const older = row("a", "tool_call");
+    const revealed = row("c", "tool_call");
+    estimates.noteRows([older, row("b"), revealed, row("d"), appendedTool]);
+
+    expect(estimates.estimate(older)).toBe(36);
+    expect(estimates.estimate(revealed)).toBe(36);
+    expect(estimates.estimate(row("b", "tool_call"))).toBeUndefined();
+  });
+
+  it("stops estimating a measured row", () => {
+    const estimates = createNewRowEstimates<Row>();
+    estimates.noteRows([]);
+    const first = row("a");
+    estimates.noteRows([first]);
+    estimates.noteMeasured(first, 34);
+
+    expect(estimates.estimate(first)).toBeUndefined();
+  });
+});
diff --git a/packages/app/src/agent-stream/new-row-estimates.ts b/packages/app/src/agent-stream/new-row-estimates.ts
new file mode 100644
index 0000000000..f13a32697a
--- /dev/null
+++ b/packages/app/src/agent-stream/new-row-estimates.ts
@@ -0,0 +1,47 @@
+interface EstimatedRow {
+  id: string;
+  kind: string;
+}
+
+export interface NewRowEstimates<Row extends EstimatedRow> {
+  /** Called with every row list; a row whose id the previous list did not have is new. */
+  noteRows: (rows: readonly Row[]) => void;
+  /** Estimated size of an unmeasured new row, or undefined to use the list's average for its type. */
+  estimate: (row: Row) => number | undefined;
+  /** A row can change kind under the same id (a thought becomes a tool call); its current kind counts. */
+  noteMeasured: (row: Row, size: number) => void;
+}
+
+// A row that enters the list is a streamed row at the end, a tool call an expanded summary reveals,
+// or an older row loaded at the start. Its first measured size is close to constant per kind: one
+// line of text, a tool call header, a thought line. So a new row is estimated at the first measured
+// size of the last new row of its kind, and is laid out near its real size before it is measured.
+// The list's average for a type is the size of whole turns and is far off for any of these. Rows of
+// the first list are not new; they keep the average until measured.
+export function createNewRowEstimates<Row extends EstimatedRow>(): NewRowEstimates<Row> {
+  let previousRowIds: ReadonlySet<string> | null = null;
+  const unmeasuredRowIds = new Set<string>();
+  const firstSizeByKind = new Map<string, number>();
+
+  return {
+    noteRows(rows) {
+      const rowIds = new Set(rows.map((row) => row.id));
+      if (previousRowIds) {
+        for (const row of rows) {
+          if (!previousRowIds.has(row.id)) unmeasuredRowIds.add(row.id);
+        }
+      }
+      for (const rowId of unmeasuredRowIds) {
+        if (!rowIds.has(rowId)) unmeasuredRowIds.delete(rowId);
+      }
+      previousRowIds = rowIds;
+    },
+    estimate(row) {
+      return unmeasuredRowIds.has(row.id) ? firstSizeByKind.get(row.kind) : undefined;
+    },
+    noteMeasured(row, size) {
+      if (!unmeasuredRowIds.delete(row.id)) return;
+      firstSizeByKind.set(row.kind, size);
+    },
+  };
+}
diff --git a/packages/app/src/agent-stream/presentation.ts b/packages/app/src/agent-stream/presentation.ts
index 94140ca395..9a5ff6469e 100644
--- a/packages/app/src/agent-stream/presentation.ts
+++ b/packages/app/src/agent-stream/presentation.ts
@@ -50,6 +50,7 @@ const NO_COLLAPSED_TURNS: StreamPresentation["turns"] = collapseTurns({
   isLatestTurnOpen: false,
   expandedHostIds: new Set(),
   getGroupedCalls: () => undefined,
+  previousTurnsByHostId: new Map(),
 });
 
 /** Source messages reach plugins before display projection. */
@@ -134,6 +135,7 @@ export function createStreamPresentation() {
         isLatestTurnOpen,
         expandedHostIds: input.expandedTurnHostIds,
         getGroupedCalls: (itemId) => projection.groupsByHostId.get(itemId)?.run.calls,
+        previousTurnsByHostId: collapsed?.turnsByHostId ?? NO_COLLAPSED_TURNS.turnsByHostId,
       });
       collapsedSource = projection.tail;
       collapsedIsLatestTurnOpen = isLatestTurnOpen;
diff --git a/packages/app/src/agent-stream/reading-anchor.test.ts b/packages/app/src/agent-stream/reading-anchor.test.ts
index d7d1b2beb4..30d30ab1a0 100644
--- a/packages/app/src/agent-stream/reading-anchor.test.ts
+++ b/packages/app/src/agent-stream/reading-anchor.test.ts
@@ -56,6 +56,16 @@ describe("reading anchor", () => {
     ).toBe(1100);
   });
 
+  it("keeps a pinned row in place instead of the row under the reading line", () => {
+    const anchor = createReadingAnchor();
+    anchor.reconcile(600, rows);
+    anchor.pin(rows[2]!);
+    // The row being read grows; only the pinned row below it holds its position.
+    expect(
+      anchor.reconcile(600, [rows[0]!, { ...rows[1]!, height: 800 }, { ...rows[2]!, top: 1300 }]),
+    ).toBe(900);
+  });
+
   it("leaves expansion of the row being read in place", () => {
     const anchor = createReadingAnchor();
     anchor.reconcile(600, rows);
diff --git a/packages/app/src/agent-stream/reading-anchor.ts b/packages/app/src/agent-stream/reading-anchor.ts
index aa915c6ae7..ed2baa552a 100644
--- a/packages/app/src/agent-stream/reading-anchor.ts
+++ b/packages/app/src/agent-stream/reading-anchor.ts
@@ -33,6 +33,11 @@ export function createReadingAnchor() {
     reset() {
       anchor = null;
     },
+    // A disclosure names the row that owns its trigger. That row keeps its top
+    // through the toggle, even when another row sits under the reading line.
+    pin(row: Pick<RowGeometry, "id" | "top">) {
+      anchor = { id: row.id, top: row.top };
+    },
     scroll(scrollTop: number) {
       const next = readingRow(scrollTop);
       anchor = next ? { id: next.id, top: next.top } : null;
diff --git a/packages/app/src/agent-stream/render-strategy.test.ts b/packages/app/src/agent-stream/render-strategy.test.ts
index 59a2f7aed3..5e5ab7f7a2 100644
--- a/packages/app/src/agent-stream/render-strategy.test.ts
+++ b/packages/app/src/agent-stream/render-strategy.test.ts
@@ -12,7 +12,6 @@ import {
   isNearBottomForStreamRenderStrategy,
   orderHeadForStreamRenderStrategy,
   orderTailForStreamRenderStrategy,
-  resolveBottomAnchorTransportBehavior,
 } from "./strategy";
 import { resolveStreamRenderStrategy } from "./strategy-resolver";
 
@@ -64,8 +63,6 @@ describe("resolveStreamRenderStrategy", () => {
     });
 
     expect(strategy.shouldUseVirtualizedList()).toBe(false);
-    expect(strategy.getFlatListInverted()).toBe(false);
-    expect(strategy.getOverlayScrollbarInverted()).toBe(false);
     expect(strategy.shouldAnchorBottomOnContentSizeChange()).toBe(true);
     expect(strategy.getBottomAnchorTransportBehavior()).toEqual({
       verificationDelayFrames: 0,
@@ -73,57 +70,27 @@ describe("resolveStreamRenderStrategy", () => {
     });
   });
 
-  it("uses inverted_stream on native", () => {
+  it("uses a virtualized forward stream on native", () => {
     const strategy = resolveStreamRenderStrategy({
       platform: "ios",
       isMobileBreakpoint: false,
     });
 
     expect(strategy.shouldUseVirtualizedList()).toBe(true);
-    expect(strategy.getFlatListInverted()).toBe(true);
-    expect(strategy.getOverlayScrollbarInverted()).toBe(true);
     expect(strategy.shouldAnchorBottomOnContentSizeChange()).toBe(false);
     expect(strategy.getBottomAnchorTransportBehavior()).toEqual({
       verificationDelayFrames: 2,
       verificationRetryMode: "recheck",
     });
   });
-
-  it("delays native verification while viewport settling is in flight", () => {
-    const strategy = resolveStreamRenderStrategy({
-      platform: "ios",
-      isMobileBreakpoint: false,
-    });
-
-    expect(
-      resolveBottomAnchorTransportBehavior({
-        strategy,
-        isViewportSettling: true,
-      }),
-    ).toEqual({
-      verificationDelayFrames: 4,
-      verificationRetryMode: "recheck",
-    });
-  });
-
-  it("does not inflate forward-stream verification delays during web resize", () => {
-    const strategy = resolveStreamRenderStrategy({
-      platform: "web",
-      isMobileBreakpoint: false,
-    });
-
-    expect(
-      resolveBottomAnchorTransportBehavior({
-        strategy,
-        isViewportSettling: true,
-      }),
-    ).toEqual({
-      verificationDelayFrames: 0,
-      verificationRetryMode: "rescroll",
-    });
-  });
 });
 
+const PLATFORMS = ["web", "ios", "android"] as const;
+
+function strategyFor(platform: (typeof PLATFORMS)[number]) {
+  return resolveStreamRenderStrategy({ platform, isMobileBreakpoint: false });
+}
+
 describe("stream ordering", () => {
   const streamItems: StreamItem[] = [
     userMessage("u1", "user-1", 1),
@@ -131,11 +98,8 @@ describe("stream ordering", () => {
     assistantMessage("a2", "assistant-2", 3),
   ];
 
-  it("keeps forward_stream order unchanged for tail and head", () => {
-    const strategy = resolveStreamRenderStrategy({
-      platform: "web",
-      isMobileBreakpoint: false,
-    });
+  it.each(PLATFORMS)("keeps oldest-to-newest order for tail and head on %s", (platform) => {
+    const strategy = strategyFor(platform);
 
     const tail = orderTailForStreamRenderStrategy({ strategy, streamItems });
     const head = orderHeadForStreamRenderStrategy({ strategy, streamHead: streamItems });
@@ -143,73 +107,31 @@ describe("stream ordering", () => {
     expect(tail.map((item) => item.id)).toEqual(["u1", "a1", "a2"]);
     expect(head.map((item) => item.id)).toEqual(["u1", "a1", "a2"]);
   });
-
-  it("reverses inverted_stream order for tail and head", () => {
-    const strategy = resolveStreamRenderStrategy({
-      platform: "android",
-      isMobileBreakpoint: false,
-    });
-
-    const tail = orderTailForStreamRenderStrategy({ strategy, streamItems });
-    const head = orderHeadForStreamRenderStrategy({ strategy, streamHead: streamItems });
-
-    expect(tail.map((item) => item.id)).toEqual(["a2", "a1", "u1"]);
-    expect(head.map((item) => item.id)).toEqual(["a2", "a1", "u1"]);
-  });
 });
 
 describe("neighbor and traversal semantics", () => {
-  it("maps above/below indices for forward and inverted streams", () => {
-    const forward = resolveStreamRenderStrategy({
-      platform: "web",
-      isMobileBreakpoint: false,
-    });
-    const inverted = resolveStreamRenderStrategy({
-      platform: "ios",
-      isMobileBreakpoint: false,
-    });
+  it.each(PLATFORMS)("maps above/below indices on %s", (platform) => {
+    const strategy = strategyFor(platform);
 
-    expect(getStreamNeighborIndex({ strategy: forward, index: 3, relation: "above" })).toBe(2);
-    expect(getStreamNeighborIndex({ strategy: forward, index: 3, relation: "below" })).toBe(4);
-    expect(getStreamNeighborIndex({ strategy: inverted, index: 3, relation: "above" })).toBe(4);
-    expect(getStreamNeighborIndex({ strategy: inverted, index: 3, relation: "below" })).toBe(2);
+    expect(getStreamNeighborIndex({ strategy, index: 3, relation: "above" })).toBe(2);
+    expect(getStreamNeighborIndex({ strategy, index: 3, relation: "below" })).toBe(4);
   });
 
-  it("collects assistant response content with strategy traversal direction", () => {
+  it.each(PLATFORMS)("collects assistant response content on %s", (platform) => {
     const chronological: StreamItem[] = [
       userMessage("u1", "user-1", 1),
       assistantMessage("a1", "assistant-1", 2),
       assistantMessage("a2", "assistant-2", 3),
       userMessage("u2", "user-2", 4),
     ];
+    const strategy = strategyFor(platform);
+    const items = orderTailForStreamRenderStrategy({ strategy, streamItems: chronological });
 
-    const forward = resolveStreamRenderStrategy({
-      platform: "web",
-      isMobileBreakpoint: false,
-    });
-    const forwardStartIndex = chronological.findIndex((item) => item.id === "a2");
     expect(
       collectAssistantResponseContentForStreamRenderStrategy({
-        strategy: forward,
-        items: chronological,
-        startIndex: forwardStartIndex,
-      }),
-    ).toBe("assistant-1\n\nassistant-2");
-
-    const inverted = resolveStreamRenderStrategy({
-      platform: "android",
-      isMobileBreakpoint: false,
-    });
-    const invertedItems = orderTailForStreamRenderStrategy({
-      strategy: inverted,
-      streamItems: chronological,
-    });
-    const invertedStartIndex = invertedItems.findIndex((item) => item.id === "a2");
-    expect(
-      collectAssistantResponseContentForStreamRenderStrategy({
-        strategy: inverted,
-        items: invertedItems,
-        startIndex: invertedStartIndex,
+        strategy,
+        items,
+        startIndex: items.findIndex((item) => item.id === "a2"),
       }),
     ).toBe("assistant-1\n\nassistant-2");
   });
@@ -220,7 +142,7 @@ describe("neighbor and traversal semantics", () => {
       { ...toolCall("tool", 2), turnId: "turn-2" },
       { ...assistantMessage("a2", "second turn", 3), turnId: "turn-2" },
     ];
-    const strategy = resolveStreamRenderStrategy({ platform: "web", isMobileBreakpoint: false });
+    const strategy = strategyFor("web");
 
     expect(
       collectAssistantResponseContentForStreamRenderStrategy({
@@ -232,37 +154,17 @@ describe("neighbor and traversal semantics", () => {
   });
 
   it("returns undefined neighbor when index would be out of bounds", () => {
-    const forward = resolveStreamRenderStrategy({
-      platform: "web",
-      isMobileBreakpoint: false,
-    });
+    const strategy = strategyFor("web");
     const items: StreamItem[] = [userMessage("u1", "user-1", 1)];
 
-    expect(
-      getStreamNeighborItem({
-        strategy: forward,
-        items,
-        index: 0,
-        relation: "above",
-      }),
-    ).toBeUndefined();
-    expect(
-      getStreamNeighborItem({
-        strategy: forward,
-        items,
-        index: 0,
-        relation: "below",
-      }),
-    ).toBeUndefined();
+    expect(getStreamNeighborItem({ strategy, items, index: 0, relation: "above" })).toBeUndefined();
+    expect(getStreamNeighborItem({ strategy, items, index: 0, relation: "below" })).toBeUndefined();
   });
 });
 
 describe("scroll/bottom calculations", () => {
-  it("computes near-bottom using forward_stream distance-from-bottom math", () => {
-    const strategy = resolveStreamRenderStrategy({
-      platform: "web",
-      isMobileBreakpoint: false,
-    });
+  it.each(PLATFORMS)("computes near-bottom from the distance to the end on %s", (platform) => {
+    const strategy = strategyFor(platform);
 
     expect(
       isNearBottomForStreamRenderStrategy({
@@ -284,48 +186,10 @@ describe("scroll/bottom calculations", () => {
     ).toBe(false);
   });
 
-  it("computes near-bottom and scroll-to-bottom offset for inverted_stream", () => {
-    const strategy = resolveStreamRenderStrategy({
-      platform: "ios",
-      isMobileBreakpoint: false,
-    });
-
-    expect(
-      isNearBottomForStreamRenderStrategy({
-        strategy,
-        offsetY: 12,
-        viewportHeight: 300,
-        contentHeight: 1000,
-        threshold: 24,
-      }),
-    ).toBe(true);
-    expect(
-      isNearBottomForStreamRenderStrategy({
-        strategy,
-        offsetY: 40,
-        viewportHeight: 300,
-        contentHeight: 1000,
-        threshold: 24,
-      }),
-    ).toBe(false);
+  it.each(PLATFORMS)("maps scroll-to-bottom to the max offset on %s", (platform) => {
     expect(
       getBottomOffsetForStreamRenderStrategy({
-        strategy,
-        viewportHeight: 300,
-        contentHeight: 1000,
-      }),
-    ).toBe(0);
-  });
-
-  it("maps scroll-to-bottom to max offset for forward_stream", () => {
-    const strategy = resolveStreamRenderStrategy({
-      platform: "web",
-      isMobileBreakpoint: false,
-    });
-
-    expect(
-      getBottomOffsetForStreamRenderStrategy({
-        strategy,
+        strategy: strategyFor(platform),
         viewportHeight: 320,
         contentHeight: 1000,
       }),
@@ -334,36 +198,15 @@ describe("scroll/bottom calculations", () => {
 });
 
 describe("edge slot semantics", () => {
-  it("uses footer slot for forward_stream and header slot for inverted_stream", () => {
+  it.each(PLATFORMS)("uses the footer slot on %s", (platform) => {
     const EdgeSlot = () => null;
-    const forward = resolveStreamRenderStrategy({
-      platform: "web",
-      isMobileBreakpoint: false,
-    });
-    const inverted = resolveStreamRenderStrategy({
-      platform: "android",
-      isMobileBreakpoint: false,
-    });
 
-    const forwardProps = getStreamEdgeSlotProps({
-      strategy: forward,
-      component: EdgeSlot,
-      gapSize: 4,
-    });
-    const invertedProps = getStreamEdgeSlotProps({
-      strategy: inverted,
-      component: EdgeSlot,
-      gapSize: 4,
-    });
-
-    expect(forwardProps).toEqual({
+    expect(
+      getStreamEdgeSlotProps({ strategy: strategyFor(platform), component: EdgeSlot, gapSize: 4 }),
+    ).toEqual({
       ListFooterComponent: EdgeSlot,
       ListFooterComponentStyle: { marginTop: 4 },
     });
-    expect(invertedProps).toEqual({
-      ListHeaderComponent: EdgeSlot,
-      ListHeaderComponentStyle: { marginBottom: 4 },
-    });
   });
 });
 
@@ -373,81 +216,31 @@ describe("layout strategy edges", () => {
     assistantMessage("a1", "assistant-1", 2),
   ];
 
-  it("uses the newest history edge as the history/live boundary", () => {
-    const forward = resolveStreamRenderStrategy({
-      platform: "web",
-      isMobileBreakpoint: false,
-    });
-    const inverted = resolveStreamRenderStrategy({
-      platform: "android",
-      isMobileBreakpoint: false,
-    });
+  it.each(PLATFORMS)(
+    "uses the newest history edge as the history/live boundary on %s",
+    (platform) => {
+      const strategy = strategyFor(platform);
+      const history = orderTailForStreamRenderStrategy({ strategy, streamItems });
 
-    const forwardHistory = orderTailForStreamRenderStrategy({ strategy: forward, streamItems });
-    const invertedHistory = orderTailForStreamRenderStrategy({ strategy: inverted, streamItems });
+      expect(getHistoryLiveBoundaryIndexForStreamRenderStrategy({ strategy, history })).toBe(1);
+    },
+  );
 
-    expect(
-      getHistoryLiveBoundaryIndexForStreamRenderStrategy({
-        strategy: forward,
-        history: forwardHistory,
-      }),
-    ).toBe(1);
-    expect(
-      getHistoryLiveBoundaryIndexForStreamRenderStrategy({
-        strategy: inverted,
-        history: invertedHistory,
-      }),
-    ).toBe(0);
-  });
+  it.each(PLATFORMS)(
+    "uses the oldest live-head edge as the live-head/history boundary on %s",
+    (platform) => {
+      const strategy = strategyFor(platform);
+      const liveHead = orderHeadForStreamRenderStrategy({ strategy, streamHead: streamItems });
 
-  it("uses the oldest live-head edge as the live-head/history boundary", () => {
-    const forward = resolveStreamRenderStrategy({
-      platform: "web",
-      isMobileBreakpoint: false,
-    });
-    const inverted = resolveStreamRenderStrategy({
-      platform: "ios",
-      isMobileBreakpoint: false,
-    });
+      expect(getLiveHeadHistoryBoundaryIndexForStreamRenderStrategy({ strategy, liveHead })).toBe(
+        0,
+      );
+    },
+  );
 
-    const forwardHead = orderHeadForStreamRenderStrategy({
-      strategy: forward,
-      streamHead: streamItems,
-    });
-    const invertedHead = orderHeadForStreamRenderStrategy({
-      strategy: inverted,
-      streamHead: streamItems,
-    });
-
-    expect(
-      getLiveHeadHistoryBoundaryIndexForStreamRenderStrategy({
-        strategy: forward,
-        liveHead: forwardHead,
-      }),
-    ).toBe(0);
-    expect(
-      getLiveHeadHistoryBoundaryIndexForStreamRenderStrategy({
-        strategy: inverted,
-        liveHead: invertedHead,
-      }),
-    ).toBe(1);
-  });
-
-  it("names the frame child order needed by native inverted cells", () => {
-    const forward = resolveStreamRenderStrategy({
-      platform: "web",
-      isMobileBreakpoint: false,
-    });
-    const inverted = resolveStreamRenderStrategy({
-      platform: "android",
-      isMobileBreakpoint: false,
-    });
-
-    expect(getFrameChildOrderForStreamRenderStrategy({ strategy: forward })).toBe(
+  it.each(PLATFORMS)("renders a cell's content before its footer on %s", (platform) => {
+    expect(getFrameChildOrderForStreamRenderStrategy({ strategy: strategyFor(platform) })).toBe(
       "content-then-footer",
     );
-    expect(getFrameChildOrderForStreamRenderStrategy({ strategy: inverted })).toBe(
-      "footer-then-content",
-    );
   });
 });
diff --git a/packages/app/src/agent-stream/scroll-keyboard-dismiss/model.test.ts b/packages/app/src/agent-stream/scroll-keyboard-dismiss/model.test.ts
index 9d22d2b90c..d459ca8ba8 100644
--- a/packages/app/src/agent-stream/scroll-keyboard-dismiss/model.test.ts
+++ b/packages/app/src/agent-stream/scroll-keyboard-dismiss/model.test.ts
@@ -41,23 +41,23 @@ describe("scroll keyboard dismissal", () => {
       shouldDismiss(
         { ts: 1000, y: 0 },
         [
-          { ts: 1040, y: 8 },
-          { ts: 1080, y: 16 },
-          { ts: 1120, y: 24 },
+          { ts: 1040, y: -8 },
+          { ts: 1080, y: -16 },
+          { ts: 1120, y: -24 },
         ],
-        { ts: 1160, y: 32 },
+        { ts: 1160, y: -32 },
       ),
     ).toBe(false);
   });
 
-  it("dismisses for an upward flick", () => {
-    expect(shouldDismiss({ ts: 1000, y: 0 }, [{ ts: 1040, y: 120 }], { ts: 1080, y: 240 })).toBe(
+  it("dismisses for a flick toward older messages", () => {
+    expect(shouldDismiss({ ts: 1000, y: 0 }, [{ ts: 1040, y: -120 }], { ts: 1080, y: -240 })).toBe(
       true,
     );
   });
 
-  it("keeps the keyboard up when the inverted list moves toward newer messages", () => {
-    expect(shouldDismiss({ ts: 1000, y: 0 }, [{ ts: 1040, y: -120 }], { ts: 1080, y: -240 })).toBe(
+  it("keeps the keyboard up when the list moves toward newer messages", () => {
+    expect(shouldDismiss({ ts: 1000, y: 0 }, [{ ts: 1040, y: 120 }], { ts: 1080, y: 240 })).toBe(
       false,
     );
   });
@@ -67,17 +67,17 @@ describe("scroll keyboard dismissal", () => {
       shouldDismiss(
         { ts: 1000, y: 0 },
         [
-          { ts: 1100, y: 500 },
-          { ts: 1200, y: 590 },
-          { ts: 1270, y: 598 },
+          { ts: 1100, y: -500 },
+          { ts: 1200, y: -590 },
+          { ts: 1270, y: -598 },
         ],
-        { ts: 1300, y: 600 },
+        { ts: 1300, y: -600 },
       ),
     ).toBe(false);
   });
 
   it("uses the whole drag when the gesture is too short to sample", () => {
-    expect(shouldDismiss({ ts: 1000, y: 0 }, [], { ts: 1020, y: 60 })).toBe(true);
+    expect(shouldDismiss({ ts: 1000, y: 0 }, [], { ts: 1020, y: -60 })).toBe(true);
   });
 
   it("steps back a sample when release lands immediately after one", () => {
@@ -85,22 +85,22 @@ describe("scroll keyboard dismissal", () => {
       shouldDismiss(
         { ts: 1000, y: 0 },
         [
-          { ts: 1040, y: 120 },
-          { ts: 1075, y: 225 },
+          { ts: 1040, y: -120 },
+          { ts: 1075, y: -225 },
         ],
-        { ts: 1080, y: 240 },
+        { ts: 1080, y: -240 },
       ),
     ).toBe(true);
   });
 
   it("keeps the keyboard up when release has no measurable time span", () => {
-    expect(shouldDismiss({ ts: 1000, y: 0 }, [], { ts: 1000, y: 90 })).toBe(false);
+    expect(shouldDismiss({ ts: 1000, y: 0 }, [], { ts: 1000, y: -90 })).toBe(false);
   });
 
   it("ignores scroll events that arrive before the minimum sample span", () => {
-    expect(shouldDismiss({ ts: 1000, y: 0 }, [{ ts: 1029, y: 1000 }], { ts: 1060, y: 1000 })).toBe(
-      true,
-    );
+    expect(
+      shouldDismiss({ ts: 1000, y: 0 }, [{ ts: 1029, y: -1000 }], { ts: 1060, y: -1000 }),
+    ).toBe(true);
   });
 
   it("uses native gesture time when delayed callbacks arrive in a burst", () => {
@@ -108,32 +108,32 @@ describe("scroll keyboard dismissal", () => {
       shouldDismiss(
         { ts: 5000, nativeTs: 1000, y: 0 },
         [
-          { ts: 5001, nativeTs: 1200, y: 40 },
-          { ts: 5002, nativeTs: 1400, y: 80 },
+          { ts: 5001, nativeTs: 1200, y: -40 },
+          { ts: 5002, nativeTs: 1400, y: -80 },
         ],
-        { ts: 5003, nativeTs: 1600, y: 120 },
+        { ts: 5003, nativeTs: 1600, y: -120 },
       ),
     ).toBe(false);
   });
 
   it("falls back to synthetic event time when native time is absent", () => {
     expect(
-      shouldDismiss({ ts: 1000, nativeTs: null, y: 0 }, [{ ts: 1040, nativeTs: null, y: 120 }], {
+      shouldDismiss({ ts: 1000, nativeTs: null, y: 0 }, [{ ts: 1040, nativeTs: null, y: -120 }], {
         ts: 1080,
         nativeTs: null,
-        y: 240,
+        y: -240,
       }),
     ).toBe(true);
   });
 
   it("ignores scroll and release events without a matching drag", () => {
-    const idle = recordScroll(IDLE_SCROLL_KEYBOARD_DISMISS_GESTURE, event({ ts: 1000, y: 200 }));
+    const idle = recordScroll(IDLE_SCROLL_KEYBOARD_DISMISS_GESTURE, event({ ts: 1000, y: -200 }));
     expect(idle).toBe(IDLE_SCROLL_KEYBOARD_DISMISS_GESTURE);
-    expect(releaseDrag(idle, event({ ts: 1010, y: 300 })).shouldDismiss).toBe(false);
+    expect(releaseDrag(idle, event({ ts: 1010, y: -300 })).shouldDismiss).toBe(false);
   });
 
   it("returns to idle after release", () => {
-    const release = releaseDrag(beginDrag(event({ ts: 1000, y: 0 })), event({ ts: 1020, y: 60 }));
+    const release = releaseDrag(beginDrag(event({ ts: 1000, y: 0 })), event({ ts: 1020, y: -60 }));
     expect(release.gesture).toBe(IDLE_SCROLL_KEYBOARD_DISMISS_GESTURE);
   });
 });
diff --git a/packages/app/src/agent-stream/scroll-keyboard-dismiss/model.ts b/packages/app/src/agent-stream/scroll-keyboard-dismiss/model.ts
index 73e0d19a76..374bb84762 100644
--- a/packages/app/src/agent-stream/scroll-keyboard-dismiss/model.ts
+++ b/packages/app/src/agent-stream/scroll-keyboard-dismiss/model.ts
@@ -2,8 +2,7 @@
  * Pure state machine for the chat history's flick-to-dismiss gesture.
  *
  * Native keyboardDismissMode cannot express this interaction: "on-drag"
- * dismisses on the first pixel, while "interactive" behaves incorrectly on an
- * inverted list. We therefore classify the list's existing scroll gesture at
+ * dismisses on the first pixel, while "interactive" is iOS-only. We therefore classify the list's existing scroll gesture at
  * release instead of introducing a competing pan recognizer.
  */
 
@@ -114,11 +113,12 @@ export function releaseDrag(
     spanStartY = samples.previousSampleY;
   }
 
+  // The list runs oldest to newest, so moving toward older messages lowers the offset.
   const spanDurationMs = releaseTs - spanStartTs;
-  const releaseVelocity = spanDurationMs > 0 ? (releaseY - spanStartY) / spanDurationMs : 0;
+  const towardOlderVelocity = spanDurationMs > 0 ? (spanStartY - releaseY) / spanDurationMs : 0;
 
   return {
     gesture: IDLE_SCROLL_KEYBOARD_DISMISS_GESTURE,
-    shouldDismiss: releaseVelocity > DISMISS_VELOCITY_POINTS_PER_MS,
+    shouldDismiss: towardOlderVelocity > DISMISS_VELOCITY_POINTS_PER_MS,
   };
 }
diff --git a/packages/app/src/agent-stream/scroll-keyboard-dismiss/use-scroll-keyboard-dismiss.ts b/packages/app/src/agent-stream/scroll-keyboard-dismiss/use-scroll-keyboard-dismiss.ts
index fb78eea9b5..e0455687ea 100644
--- a/packages/app/src/agent-stream/scroll-keyboard-dismiss/use-scroll-keyboard-dismiss.ts
+++ b/packages/app/src/agent-stream/scroll-keyboard-dismiss/use-scroll-keyboard-dismiss.ts
@@ -18,7 +18,7 @@ type ScrollEvent = NativeSyntheticEvent<NativeScrollEvent>;
 
 /**
  * Owns the chat history's flick-to-dismiss behavior. The native stream only
- * forwards the FlatList scroll lifecycle; removing this hook and those three
+ * forwards the LegendList scroll lifecycle; removing this hook and those three
  * calls removes the feature completely.
  */
 export function useScrollKeyboardDismiss() {
diff --git a/packages/app/src/agent-stream/strategy-native.tsx b/packages/app/src/agent-stream/strategy-native.tsx
index 7dc6e8d521..f894880d23 100644
--- a/packages/app/src/agent-stream/strategy-native.tsx
+++ b/packages/app/src/agent-stream/strategy-native.tsx
@@ -1,38 +1,42 @@
 import {
-  Fragment,
   type ReactElement,
+  type ReactNode,
   useCallback,
   useEffect,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState,
 } from "react";
 import {
-  FlatList,
-  Platform,
   View,
   type LayoutChangeEvent,
-  type ListRenderItemInfo,
   type NativeScrollEvent,
   type NativeSyntheticEvent,
+  type ScrollView,
+  type ScrollViewProps,
   type ViewStyle,
 } from "react-native";
+import {
+  LegendList,
+  type LegendListRef,
+  type LegendListRenderItemProps,
+  useSyncLayout,
+} from "@legendapp/list/react-native";
 import { withUnistyles } from "react-native-unistyles";
 import { LoadingSpinner } from "@/components/ui/loading-spinner";
 import type { StreamItem } from "@/types/stream";
 import type { Theme } from "@/styles/theme";
 import { useStableEvent } from "@/hooks/use-stable-event";
-import { useKeyboardStreamInset } from "@/keyboard/shift";
 import { shouldAnimateNativeScrollToBottom } from "./native-scroll-animation";
 import { useRevisedHistoryRows } from "./history-row-revision";
 import { useBottomAnchorController } from "./bottom-anchor-controller";
 import { useScrollKeyboardDismiss } from "./scroll-keyboard-dismiss/use-scroll-keyboard-dismiss";
+import { createNativeDisclosureHold } from "./native-disclosure-hold";
+import { EndPinnedScrollView } from "./native-end-pin";
+import { createNewRowEstimates } from "./new-row-estimates";
 import type { StreamRenderInput, StreamStrategy, StreamViewportHandle } from "./strategy";
-import {
-  createStreamStrategy,
-  isNearBottomForStreamRenderStrategy,
-  resolveBottomAnchorTransportBehavior,
-} from "./strategy";
+import { createStreamStrategy, isNearBottomForStreamRenderStrategy } from "./strategy";
 import {
   abandonHistoryStartPaginationRequest,
   createHistoryStartPaginationState,
@@ -49,11 +53,6 @@ import {
   type HistoryStartSettleScheduler,
 } from "./history-start-settle-scheduler";
 
-const DEFAULT_MAINTAIN_VISIBLE_CONTENT_POSITION = Object.freeze({
-  minIndexForVisible: 0,
-  autoscrollToTopThreshold: 0,
-});
-
 const ThemedLoadingSpinner = withUnistyles(LoadingSpinner);
 const foregroundMutedColorMapping = (theme: Theme) => ({
   color: theme.colors.foregroundMuted,
@@ -65,7 +64,50 @@ const historyStartSlotStyle: ViewStyle = {
   flexShrink: 0,
 };
 const HISTORY_START_SETTLE_FRAMES = 2;
-const NATIVE_STREAM_WINDOW_SIZE = 10;
+// Rendered distance on each side of the viewport. Smaller values blank the viewport while a fling
+// crosses rows that were never measured (docs/agent-stream-disclosure.md).
+const NATIVE_STREAM_DRAW_DISTANCE = 2000;
+// Following resumes after a disclosure or a user scroll only from the end, so resuming never moves
+// the rows the user is looking at. Web resumes within the same distance (strategy-web.tsx).
+const AT_END_OFFSET_PX = 1;
+// A disclosure settles after this many frames without an item size change.
+const DISCLOSURE_QUIET_FRAMES = 2;
+const BOTTOM_ANCHOR_TRANSPORT_BEHAVIOR = Object.freeze({
+  verificationDelayFrames: 2,
+  verificationRetryMode: "recheck" as const,
+});
+
+type RowLayoutSyncRegistry = Map<string, () => void>;
+
+// A disclosure toggle changes a row from the row's own state, so LegendList's container does not
+// re-render and would learn the new height from onLayout a task later, a frame after the change
+// painted. The row's measurement trigger, called next to the toggle, batches the measurement and
+// the corrected positions into the toggle's own commit.
+function RowLayoutSync(props: {
+  rowId: string;
+  registry: RowLayoutSyncRegistry;
+  children: ReactNode;
+}) {
+  const { rowId, registry } = props;
+  const syncLayout = useSyncLayout();
+  useLayoutEffect(() => {
+    registry.set(rowId, syncLayout);
+    return () => {
+      if (registry.get(rowId) === syncLayout) {
+        registry.delete(rowId);
+      }
+    };
+  }, [registry, rowId, syncLayout]);
+  return props.children;
+}
+
+function distanceFromEnd(input: {
+  offsetY: number;
+  contentHeight: number;
+  viewportHeight: number;
+}): number {
+  return Math.max(0, input.contentHeight - input.viewportHeight - input.offsetY);
+}
 
 function keyExtractor(item: { id: string }): string {
   return item.id;
@@ -94,7 +136,12 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     strategy,
   } = props;
   const { renderHistoryMountedRow, renderLiveHeadRow, renderLiveAuxiliary } = renderers;
-  const flatListRef = useRef<FlatList<StreamItem>>(null);
+  const listRef = useRef<LegendListRef>(null);
+  // LegendList places the rows of each agent once, behind a hidden reveal (`dataKey`).
+  const [placedAgentId, setPlacedAgentId] = useState<string | null>(null);
+  const isListPlaced = placedAgentId === agentId;
+  const isListPlacedRef = useRef(isListPlaced);
+  isListPlacedRef.current = isListPlaced;
   const streamViewportMetricsRef = useRef({
     containerKey: "native-virtualized",
     contentHeight: 0,
@@ -107,11 +154,9 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
   const scrollOffsetYRef = useRef(0);
   const isUserScrollActiveRef = useRef(false);
   const scrollKeyboardDismiss = useScrollKeyboardDismiss();
-  const streamKeyboardInset = useKeyboardStreamInset();
   const userScrollEndFrameIdRef = useRef<number | null>(null);
+  const isReleasedAtEndRef = useRef(false);
   const programmaticScrollEventBudgetRef = useRef(0);
-  const isNativeViewportSettlingRef = useRef(false);
-  const nativeViewportSettlingFrameIdRef = useRef<number | null>(null);
   const historyStartReadyRef = useRef(false);
   const [historyStartPaginationState, setHistoryStartPaginationState] = useState(
     createHistoryStartPaginationState,
@@ -126,13 +171,28 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     return [...segments.historyVirtualized, ...segments.historyMounted];
   }, [segments.historyMounted, segments.historyVirtualized]);
   const historyRows = useRevisedHistoryRows(historyItems, historyRowRevision);
+  // Live rows are the tail of the list, so a row that finishes keeps its id, container and measured
+  // size when it moves into history. A fresh identity per live-head change re-renders every live
+  // row, which is how they pick up neighbour and expansion changes (`liveHeadRowRevision`).
+  const liveRows = useMemo(() => {
+    void liveHeadRowRevision;
+    return segments.liveHead.map((item) => ({ ...item }));
+  }, [segments.liveHead, liveHeadRowRevision]);
+  const liveRowIds = useMemo(() => new Set(liveRows.map((item) => item.id)), [liveRows]);
+  const [newRowEstimates] = useState(() => createNewRowEstimates<StreamItem>());
+  const rows = useMemo(() => {
+    const nextRows = [...historyRows, ...liveRows];
+    newRowEstimates.noteRows(nextRows);
+    return nextRows;
+  }, [newRowEstimates, historyRows, liveRows]);
+  const getEstimatedItemSize = useStableEvent((item: StreamItem) => newRowEstimates.estimate(item));
   const getHistoryStartPaginationInput = useStableEvent((): HistoryStartPaginationInput => {
     const metrics = streamViewportMetricsRef.current;
     const hasMeasuredViewport =
       metrics.viewportMeasuredForKey === metrics.containerKey &&
       metrics.contentMeasuredForKey === metrics.containerKey;
     return {
-      distanceFromHistoryStart: metrics.contentHeight - metrics.viewportHeight - metrics.offsetY,
+      distanceFromHistoryStart: metrics.offsetY,
       hasOlderHistory,
       isLoadingOlderHistory,
       isReady: historyStartReadyRef.current && hasMeasuredViewport,
@@ -196,13 +256,6 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     scheduler.schedule();
   });
 
-  const clearNativeViewportSettling = useCallback(() => {
-    if (nativeViewportSettlingFrameIdRef.current !== null) {
-      cancelAnimationFrame(nativeViewportSettlingFrameIdRef.current);
-      nativeViewportSettlingFrameIdRef.current = null;
-    }
-  }, []);
-
   const clearPendingUserScrollEnd = useCallback(() => {
     if (userScrollEndFrameIdRef.current !== null) {
       cancelAnimationFrame(userScrollEndFrameIdRef.current);
@@ -210,49 +263,30 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     }
   }, []);
 
-  const markNativeViewportSettling = useCallback(() => {
-    clearNativeViewportSettling();
-    isNativeViewportSettlingRef.current = true;
-    let remainingFrames = 4;
-    const tick = () => {
-      if (remainingFrames <= 0) {
-        nativeViewportSettlingFrameIdRef.current = null;
-        isNativeViewportSettlingRef.current = false;
-        return;
-      }
-      remainingFrames -= 1;
-      nativeViewportSettlingFrameIdRef.current = requestAnimationFrame(tick);
-    };
-    nativeViewportSettlingFrameIdRef.current = requestAnimationFrame(tick);
-  }, [clearNativeViewportSettling]);
-
-  const getBottomAnchorTransportBehavior = useCallback(
-    () =>
-      resolveBottomAnchorTransportBehavior({
-        strategy,
-        isViewportSettling: isNativeViewportSettlingRef.current,
-      }),
-    [strategy],
-  );
+  const getBottomAnchorTransportBehavior = useCallback(() => BOTTOM_ANCHOR_TRANSPORT_BEHAVIOR, []);
 
   const scrollToBottom = useCallback(
     (animated: boolean) => {
       programmaticScrollEventBudgetRef.current = 3;
-      flatListRef.current?.scrollToOffset({
-        offset: 0,
+      const metrics = streamViewportMetricsRef.current;
+      // The native scroll view finds its end from the content it has mounted, and the end pin holds
+      // it from there. LegendList's own scrollToEnd keeps re-aiming at the end its JS sizes predict
+      // until it lands, which runs ahead of the mount and scrolls the end out of view.
+      const list = listRef.current;
+      list?.cancelScroll();
+      // The scroll component is `EndPinnedScrollView`, a ScrollView.
+      (list?.getNativeScrollRef() as ScrollView | undefined)?.scrollToEnd({
         animated:
           animated &&
           shouldAnimateNativeScrollToBottom({
-            offsetY: scrollOffsetYRef.current,
-            viewportHeight: streamViewportMetricsRef.current.viewportHeight,
-            windowSize: NATIVE_STREAM_WINDOW_SIZE,
+            distanceFromEnd: distanceFromEnd(metrics),
+            viewportHeight: metrics.viewportHeight,
+            drawDistance: NATIVE_STREAM_DRAW_DISTANCE,
           }),
       });
-      scrollOffsetYRef.current = 0;
-      streamViewportMetricsRef.current = {
-        ...streamViewportMetricsRef.current,
-        offsetY: 0,
-      };
+      const endOffsetY = Math.max(0, metrics.contentHeight - metrics.viewportHeight);
+      scrollOffsetYRef.current = endOffsetY;
+      streamViewportMetricsRef.current = { ...metrics, offsetY: endOffsetY };
       onNearBottomChange(true);
     },
     [onNearBottomChange],
@@ -262,7 +296,7 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     agentId,
     routeRequest: routeBottomAnchorRequest,
     isAuthoritativeHistoryReady,
-    renderStrategy: "inverted-stream",
+    renderStrategy: "legend-stream",
     getTransportBehavior: getBottomAnchorTransportBehavior,
     getMeasurementState: () => streamViewportMetricsRef.current,
     isNearBottom: () => {
@@ -277,39 +311,76 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     },
     scrollToBottom,
   });
-  // Android's maintainVisibleContentPosition ignores the list inversion transform and
-  // fights the controller's offset-zero correction while the live header grows.
-  const maintainVisibleContentPosition =
-    Platform.OS === "android" && bottomAnchorController.mode === "sticky-bottom"
-      ? undefined
-      : DEFAULT_MAINTAIN_VISIBLE_CONTENT_POSITION;
-  const topOverlayInset = useStreamTopOverlayInset();
-  // The list is inverted, so its content's bottom padding is the visual top.
-  const listContentContainerStyle = useMemo(
-    () => [
-      baseListContentContainerStyle,
-      {
-        paddingBottom: streamKeyboardInset.contentContainerPaddingBottom + topOverlayInset,
-      },
-    ],
-    [
-      baseListContentContainerStyle,
-      streamKeyboardInset.contentContainerPaddingBottom,
-      topOverlayInset,
-    ],
+
+  const [rowLayoutSyncRegistry] = useState<RowLayoutSyncRegistry>(() => new Map());
+  const isAtEnd = useStableEvent(
+    () => distanceFromEnd(streamViewportMetricsRef.current) <= AT_END_OFFSET_PX,
   );
-  const listInsetProps = useMemo(
-    () =>
-      streamKeyboardInset.contentInset
-        ? {
-            automaticallyAdjustContentInsets: false,
-            automaticallyAdjustsScrollIndicatorInsets: false,
-            contentInsetAdjustmentBehavior: "never" as const,
-            contentInset: streamKeyboardInset.contentInset,
-            scrollIndicatorInsets: streamKeyboardInset.contentInset,
-          }
-        : {},
-    [streamKeyboardInset.contentInset],
+  const releaseDisclosure = useStableEvent(() => {
+    bottomAnchorController.releaseDisclosure({ isAtEnd: isAtEnd() });
+  });
+  const [disclosureHold] = useState(() =>
+    createNativeDisclosureHold({
+      quietFrames: DISCLOSURE_QUIET_FRAMES,
+      requestFrame: requestAnimationFrame,
+      cancelFrame: cancelAnimationFrame,
+      onRelease: releaseDisclosure,
+    }),
+  );
+  useEffect(() => () => disclosureHold.cancel(), [disclosureHold]);
+  // The hold detaches the controller in the same event as `apply`, so the toggle's commit already
+  // has end following off and LegendList anchoring on the held row. The row's measurement trigger
+  // makes that same commit carry the row's new height.
+  const holdRow = useStableEvent((rowId: string, apply: () => void) => {
+    disclosureHold.hold(rowId);
+    bottomAnchorController.holdForDisclosure();
+    apply();
+    rowLayoutSyncRegistry.get(rowId)?.();
+  });
+  const handleItemSizeChanged = useStableEvent(
+    (info: { size: number; previous: number; itemKey: string; itemData: StreamItem }) => {
+      newRowEstimates.noteMeasured(info.itemData, info.size);
+      disclosureHold.noteItemSizeChanged();
+    },
+  );
+  const shouldRestorePosition = useStableEvent((item: StreamItem) => {
+    const heldRowId = disclosureHold.heldRowId();
+    return heldRowId === null || item.id === heldRowId;
+  });
+  // One owner keeps the scroll offset at any moment:
+  // - Before the list has placed its rows for the agent: LegendList's initial scroll to the end. It
+  //   keeps the rows hidden until they are measured and in place, so neither the pin nor the
+  //   controller acts; the content does not count as measured yet (`handleContentSizeChange`).
+  // - Following the end: the end pin. Rows added, rows resized and footer changes never scroll from
+  //   JS; the pin holds the end in the frame the change mounts. The controller scrolls only for a
+  //   viewport resize (the composer growing or shrinking), which the pin cannot see, and for an
+  //   explicit jump, and both go to the native end (`scrollToBottom`). The keyboard does not resize
+  //   the viewport: it translates the list with the composer. LegendList's end keeping stays off: it
+  //   scrolls to the end its JS sizes predict, which runs ahead of the native mount, so it lands
+  //   short of the real end and the controller reads that as the user scrolling away.
+  // - A disclosure hold: the held row. The hold detaches the controller, which removes the pin, and
+  //   LegendList keeps only the held row in place.
+  // - A user scroll: the finger. The controller detaches for the gesture, so streamed lines grow below
+  //   the rows the user is dragging, and resumes following if the gesture ends at the end.
+  // - Detached: the visible rows. LegendList keeps the first visible row in place, so history loading
+  //   above or rows growing below leave what the user is reading where it is.
+  const isFollowingEnd = bottomAnchorController.mode === "sticky-bottom";
+  const pinsEnd = isFollowingEnd && isListPlaced;
+  const maintainVisibleContentPosition = useMemo(
+    () => (isFollowingEnd ? false : { data: true, size: true, shouldRestorePosition }),
+    [isFollowingEnd, shouldRestorePosition],
+  );
+  // A new identity re-renders LegendList's scroll component, which is how the pin follows the mode.
+  const renderScrollComponent = useCallback(
+    (scrollProps: ScrollViewProps) => <EndPinnedScrollView {...scrollProps} pinEnd={pinsEnd} />,
+    [pinsEnd],
+  );
+  const topOverlayInset = useStreamTopOverlayInset();
+  // No keyboard inset: one committed after the keyboard settles moves every row when the end pin is
+  // not holding the offset (docs/agent-stream-disclosure.md).
+  const listContentContainerStyle = useMemo(
+    () => [baseListContentContainerStyle, { paddingTop: topOverlayInset }],
+    [baseListContentContainerStyle, topOverlayInset],
   );
 
   useEffect(() => {
@@ -325,8 +396,7 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     scrollOffsetYRef.current = 0;
     isUserScrollActiveRef.current = false;
     clearPendingUserScrollEnd();
-    clearNativeViewportSettling();
-    isNativeViewportSettlingRef.current = false;
+    disclosureHold.cancel();
     historyStartReadyRef.current = false;
     const initialHistoryStartState = createHistoryStartPaginationState();
     historyStartPaginationStateRef.current = initialHistoryStartState;
@@ -341,13 +411,7 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
       historyStartSettleSchedulerRef.current?.cancel();
       historyStartSettleSchedulerRef.current = null;
     };
-  }, [agentId, clearNativeViewportSettling, clearPendingUserScrollEnd, evaluateHistoryStart]);
-
-  useEffect(() => () => clearNativeViewportSettling(), [clearNativeViewportSettling]);
-
-  useEffect(() => {
-    bottomAnchorController.prepareForStickyContentChange();
-  }, [bottomAnchorController, historyRows, segments.liveHead]);
+  }, [agentId, clearPendingUserScrollEnd, disclosureHold, evaluateHistoryStart]);
 
   useEffect(() => {
     const handle: StreamViewportHandle = {
@@ -359,9 +423,8 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
       },
       prepareForViewportChange: () => {
         bottomAnchorController.prepareForStickyViewportChange();
-        markNativeViewportSettling();
       },
-      holdReadingPosition: () => bottomAnchorController.detachByUser(),
+      holdRow,
     };
     viewportRef.current = handle;
     return () => {
@@ -369,7 +432,32 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
         viewportRef.current = null;
       }
     };
-  }, [agentId, bottomAnchorController, markNativeViewportSettling, viewportRef]);
+  }, [agentId, bottomAnchorController, holdRow, viewportRef]);
+
+  // The scroll-to-bottom button shows whenever following would not resume on its own. A detached
+  // list resumes only from the end, so the button shows anywhere short of it. While following, the
+  // offset can trail content growth for a frame, so the controller's wider threshold keeps the
+  // button from flashing.
+  const publishNearBottom = useStableEvent(() => {
+    const metrics = streamViewportMetricsRef.current;
+    onNearBottomChange(
+      bottomAnchorController.mode === "detached"
+        ? distanceFromEnd(metrics) <= AT_END_OFFSET_PX
+        : isNearBottomForStreamRenderStrategy({
+            strategy,
+            offsetY: metrics.offsetY,
+            threshold: 32,
+            contentHeight: metrics.contentHeight,
+            viewportHeight: metrics.viewportHeight,
+          }),
+    );
+  });
+
+  // Following starts and stops without a scroll, for example when a disclosure hold begins short of
+  // the end, and the button follows it.
+  useEffect(() => {
+    publishNearBottom();
+  }, [isFollowingEnd, publishNearBottom]);
 
   const isScrollEventNearBottom = useStableEvent(
     (event: NativeSyntheticEvent<NativeScrollEvent>) => {
@@ -384,6 +472,17 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     },
   );
 
+  const isScrollEventAtEnd = useStableEvent((event: NativeSyntheticEvent<NativeScrollEvent>) => {
+    const { contentOffset, contentSize, layoutMeasurement } = event.nativeEvent;
+    return (
+      distanceFromEnd({
+        offsetY: contentOffset.y,
+        contentHeight: contentSize.height,
+        viewportHeight: layoutMeasurement.height,
+      }) <= AT_END_OFFSET_PX
+    );
+  });
+
   const handleScroll = useStableEvent((event: NativeSyntheticEvent<NativeScrollEvent>) => {
     const { contentOffset, contentSize, layoutMeasurement } = event.nativeEvent;
     const previousOffsetY = scrollOffsetYRef.current;
@@ -401,14 +500,18 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     };
 
     const nearBottom = isScrollEventNearBottom(event);
-    onNearBottomChange(nearBottom);
+    publishNearBottom();
 
     evaluateHistoryStart();
 
     if (
       !isUserScrollActiveRef.current &&
       programmaticScrollEventBudgetRef.current > 0 &&
-      contentOffset.y <= 8
+      distanceFromEnd({
+        offsetY: contentOffset.y,
+        contentHeight: contentSize.height,
+        viewportHeight: layoutMeasurement.height,
+      }) <= 8
     ) {
       programmaticScrollEventBudgetRef.current -= 1;
     } else {
@@ -424,6 +527,10 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     clearPendingUserScrollEnd();
     isUserScrollActiveRef.current = true;
     scrollKeyboardDismiss.onScrollBeginDrag(event);
+    // The gesture takes the viewport from a disclosure hold. Size changes from a streaming row can
+    // keep the hold's quiet frames from ever passing, and a held row that scrolls away would leave
+    // no row LegendList may anchor a history page on. The gesture's end decides following.
+    disclosureHold.cancel();
     bottomAnchorController.beginUserScroll();
     const rearmed = rearmHistoryStartPagination(historyStartPaginationStateRef.current);
     if (rearmed !== historyStartPaginationStateRef.current) {
@@ -433,17 +540,22 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     }
   });
 
-  // Defer drag end so momentum can take ownership, but capture the terminal
-  // gesture position now because layout may move the viewport in the meantime.
+  // A gesture ends at the end when the finger lifts at or past it, or when its momentum stops there.
+  // A release past the end bounces back to it on iOS, and lines that land during the bounce scroll
+  // in as they do while following. Momentum stopping short of the end, or output that arrived below
+  // the viewport before the decision, leaves the list detached.
+  // Drag end is deferred a frame so momentum can take ownership.
   const handleScrollEndDrag = useStableEvent((event: NativeSyntheticEvent<NativeScrollEvent>) => {
-    const isNearBottom = isScrollEventNearBottom(event);
     scrollKeyboardDismiss.onScrollEndDrag(event);
+    isReleasedAtEndRef.current = isScrollEventAtEnd(event);
 
     clearPendingUserScrollEnd();
     userScrollEndFrameIdRef.current = requestAnimationFrame(() => {
       userScrollEndFrameIdRef.current = null;
       isUserScrollActiveRef.current = false;
-      bottomAnchorController.endUserScroll({ isNearBottom });
+      bottomAnchorController.endUserScroll({
+        isAtEnd: isReleasedAtEndRef.current || isAtEnd(),
+      });
     });
   });
 
@@ -458,10 +570,11 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
       if (!isUserScrollActiveRef.current) {
         return;
       }
-      const isNearBottom = isScrollEventNearBottom(event);
       clearPendingUserScrollEnd();
       isUserScrollActiveRef.current = false;
-      bottomAnchorController.endUserScroll({ isNearBottom });
+      bottomAnchorController.endUserScroll({
+        isAtEnd: isReleasedAtEndRef.current || isScrollEventAtEnd(event),
+      });
     },
   );
 
@@ -470,9 +583,6 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     const previousViewportHeight = streamViewportMetricsRef.current.viewportHeight;
     const viewportWidth = Math.max(0, event.nativeEvent.layout.width);
     const viewportHeight = Math.max(0, event.nativeEvent.layout.height);
-    const viewportChanged =
-      (previousViewportWidth > 0 && previousViewportWidth !== viewportWidth) ||
-      (previousViewportHeight > 0 && previousViewportHeight !== viewportHeight);
     streamViewportMetricsRef.current = {
       ...streamViewportMetricsRef.current,
       containerKey: "native-virtualized",
@@ -480,9 +590,6 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
       viewportHeight,
       viewportMeasuredForKey: "native-virtualized",
     };
-    if (viewportChanged) {
-      markNativeViewportSettling();
-    }
     bottomAnchorController.handleViewportMetricsChange({
       previousViewportWidth,
       viewportWidth,
@@ -493,24 +600,37 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
   });
 
   const handleContentSizeChange = useStableEvent((_width: number, height: number) => {
-    const previousContentHeight = streamViewportMetricsRef.current.contentHeight;
     const nextContentHeight = Math.max(0, height);
     streamViewportMetricsRef.current = {
       ...streamViewportMetricsRef.current,
       containerKey: "native-virtualized",
       contentHeight: nextContentHeight,
-      contentMeasuredForKey: "native-virtualized",
+      contentMeasuredForKey: isListPlacedRef.current ? "native-virtualized" : null,
     };
-    bottomAnchorController.handleContentSizeChange({
-      previousContentHeight,
-      contentHeight: nextContentHeight,
-    });
+    bottomAnchorController.handleContentSizeChange();
+    // Content growing below a detached viewport moves the end away without a scroll event.
+    if (
+      bottomAnchorController.mode === "detached" &&
+      streamViewportMetricsRef.current.viewportHeight > 0
+    ) {
+      publishNearBottom();
+    }
     evaluateHistoryStart();
     if (historyStartPaginationStateRef.current.status === "settling") {
       scheduleHistoryStartSettle();
     }
   });
 
+  const handleListPlaced = useStableEvent(() => {
+    isListPlacedRef.current = true;
+    setPlacedAgentId(agentId);
+    streamViewportMetricsRef.current = {
+      ...streamViewportMetricsRef.current,
+      contentMeasuredForKey: "native-virtualized",
+    };
+    bottomAnchorController.handleContentSizeChange();
+  });
+
   useEffect(() => {
     evaluateHistoryStart();
     if (historyStartPaginationStateRef.current.status === "settling") {
@@ -524,45 +644,35 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     scheduleHistoryStartSettle,
   ]);
 
+  // LegendList re-renders a mounted row only when its item or `extraData` changes, not when
+  // renderItem does. Item identity carries content and display changes (`useRevisedHistoryRows`);
+  // `extraData` carries the history renderer, whose identity changes with the history layout (a
+  // reply gaining its completed footer when the next prompt arrives) and keeps its row's item.
+  // StreamRow's memo limits that pass to the rows whose layout item changed.
   const renderItem = useStableEvent(
-    ({ item, index }: ListRenderItemInfo<StreamItem>): ReactElement | null => {
-      const rendered = renderHistoryMountedRow(item, index, historyItems);
-      return (rendered ?? null) as ReactElement | null;
-    },
+    ({ item, index }: LegendListRenderItemProps<StreamItem>): ReactElement => (
+      <RowLayoutSync rowId={item.id} registry={rowLayoutSyncRegistry}>
+        {liveRowIds.has(item.id)
+          ? renderLiveHeadRow(item, index - historyRows.length, segments.liveHead)
+          : renderHistoryMountedRow(item, index, historyItems)}
+      </RowLayoutSync>
+    ),
   );
 
-  const liveHeaderContent = useMemo(() => {
-    // Stable render events read the latest expansion state; this revision makes
-    // the memo invoke them again when that state changes.
-    void liveHeadRowRevision;
-    const liveHeadRows = segments.liveHead.map((item, index) => (
-      <Fragment key={item.id}>{renderLiveHeadRow(item, index, segments.liveHead)}</Fragment>
-    ));
+  const liveAuxiliaryContent = useMemo(() => {
     const liveAuxiliary = renderLiveAuxiliary();
     if (
-      liveHeadRows.length === 0 &&
+      liveRows.length === 0 &&
       !liveAuxiliary &&
       !boundary.hasMountedHistory &&
       !boundary.hasVirtualizedHistory
     ) {
       return (listEmptyComponent ?? null) as ReactElement | null;
     }
-    return (
-      <Fragment>
-        {liveHeadRows}
-        {liveAuxiliary}
-      </Fragment>
-    );
-  }, [
-    boundary,
-    listEmptyComponent,
-    liveHeadRowRevision,
-    renderLiveAuxiliary,
-    renderLiveHeadRow,
-    segments.liveHead,
-  ]);
+    return <View>{liveAuxiliary}</View>;
+  }, [boundary, listEmptyComponent, liveRows.length, renderLiveAuxiliary]);
 
-  const historyFooterContent = useMemo(() => {
+  const historyStartContent = useMemo(() => {
     const isLoadingOperation = isHistoryStartLoadingOperation(historyStartPaginationState);
     return (
       <View style={historyStartSlotStyle} testID="older-history-slot">
@@ -575,21 +685,21 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
     );
   }, [historyStartPaginationState]);
 
-  // RN's FlatList strictMode keeps its internal renderItem wrapper stable when
-  // data or the live header changes, preserving the row identities above.
   return (
-    <FlatList
-      {...listInsetProps}
-      ref={flatListRef}
-      data={historyRows}
+    <LegendList<StreamItem>
+      ref={listRef}
+      data={rows}
       renderItem={renderItem}
+      extraData={renderHistoryMountedRow}
       keyExtractor={keyExtractor}
-      strictMode
       testID="agent-chat-scroll"
       nativeID="agent-chat-scroll-native-virtualized"
-      ListHeaderComponent={liveHeaderContent ?? undefined}
-      ListFooterComponent={historyFooterContent ?? undefined}
+      ListHeaderComponent={historyStartContent}
+      ListFooterComponent={liveAuxiliaryContent ?? undefined}
       contentContainerStyle={listContentContainerStyle}
+      automaticallyAdjustContentInsets={false}
+      automaticallyAdjustsScrollIndicatorInsets={false}
+      contentInsetAdjustmentBehavior="never"
       style={listStyle}
       onLayout={handleListLayout}
       onScroll={handleScroll}
@@ -599,16 +709,18 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
       onMomentumScrollEnd={handleMomentumScrollEnd}
       scrollEventThrottle={16}
       onContentSizeChange={handleContentSizeChange}
+      onItemSizeChanged={handleItemSizeChanged}
+      onReady={handleListPlaced}
+      dataKey={agentId}
       maintainVisibleContentPosition={maintainVisibleContentPosition}
-      // Tall Markdown rows exhaust a shallow window during flings. Keep the initial
-      // render small, then refill a deeper window in batches large enough to keep up.
-      initialNumToRender={2}
-      maxToRenderPerBatch={10}
-      windowSize={NATIVE_STREAM_WINDOW_SIZE}
-      removeClippedSubviews={false}
+      renderScrollComponent={renderScrollComponent}
+      recycleItems={false}
+      alignItemsAtEnd
+      initialScrollAtEnd
+      drawDistance={NATIVE_STREAM_DRAW_DISTANCE}
+      getEstimatedItemSize={getEstimatedItemSize}
       scrollEnabled={scrollEnabled}
       showsVerticalScrollIndicator
-      inverted
     />
   );
 }
@@ -616,26 +728,20 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
 export function createNativeStreamStrategy(): StreamStrategy {
   const strategy = createStreamStrategy({
     render: (renderInput) => <NativeStreamViewport {...renderInput} strategy={strategy} />,
-    orderTailReverse: true,
-    orderHeadReverse: true,
-    assistantTurnTraversalStep: 1,
-    edgeSlot: "header",
-    historyLiveBoundaryEdge: "first",
-    liveHeadHistoryBoundaryEdge: "last",
-    frameChildOrder: "footer-then-content",
-    flatListInverted: true,
-    overlayScrollbarInverted: true,
-    maintainVisibleContentPosition: DEFAULT_MAINTAIN_VISIBLE_CONTENT_POSITION,
-    bottomAnchorTransportBehavior: {
-      verificationDelayFrames: 2,
-      verificationRetryMode: "recheck",
-    },
+    orderTailReverse: false,
+    orderHeadReverse: false,
+    assistantTurnTraversalStep: -1,
+    edgeSlot: "footer",
+    historyLiveBoundaryEdge: "last",
+    liveHeadHistoryBoundaryEdge: "first",
+    frameChildOrder: "content-then-footer",
+    bottomAnchorTransportBehavior: BOTTOM_ANCHOR_TRANSPORT_BEHAVIOR,
     disableParentScrollOnInlineDetailsExpansion: false,
     anchorBottomOnContentSizeChange: false,
     animateManualScrollToBottom: true,
     useVirtualizedList: true,
-    isNearBottom: (input) => input.offsetY <= input.threshold,
-    getBottomOffset: () => 0,
+    isNearBottom: (input) => distanceFromEnd(input) <= input.threshold,
+    getBottomOffset: (metrics) => Math.max(0, metrics.contentHeight - metrics.viewportHeight),
   });
   return strategy;
 }
diff --git a/packages/app/src/agent-stream/strategy-web.browser.test.tsx b/packages/app/src/agent-stream/strategy-web.browser.test.tsx
new file mode 100644
index 0000000000..28fbd1e2a2
--- /dev/null
+++ b/packages/app/src/agent-stream/strategy-web.browser.test.tsx
@@ -0,0 +1,158 @@
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { DEFAULT_CONTENT_MAX_WIDTH } from "@/styles/theme";
+import type { StreamItem } from "@/types/stream";
+import type { StreamRenderInput, StreamViewportHandle } from "./strategy";
+import { createWebStreamStrategy } from "./strategy-web";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const VIEWPORT_HEIGHT = 100;
+const ROW_HEIGHT = 40;
+
+// A row's height comes from its text, so a disclosure that opens or grows a row is a new item
+// for that row, as it is in the app.
+function row(index: number, height = ROW_HEIGHT): Extract<StreamItem, { kind: "user_message" }> {
+  return {
+    kind: "user_message",
+    id: `message-${index}`,
+    text: String(height),
+    timestamp: new Date(`2026-04-20T00:00:${String(index % 60).padStart(2, "0")}.000Z`),
+  };
+}
+
+const rowStyleByHeight = new Map<number, { height: number }>();
+
+function renderRow(item: StreamItem) {
+  const height = item.kind === "user_message" ? Number(item.text) : ROW_HEIGHT;
+  let style = rowStyleByHeight.get(height);
+  if (!style) {
+    style = { height };
+    rowStyleByHeight.set(height, style);
+  }
+  return <div style={style}>{item.id}</div>;
+}
+
+let root: Root;
+let host: HTMLDivElement;
+
+beforeEach(() => {
+  host = document.createElement("div");
+  host.style.cssText = `display:flex;flex-direction:column;width:500px;height:${VIEWPORT_HEIGHT}px`;
+  document.body.appendChild(host);
+  root = createRoot(host);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  host.remove();
+});
+
+function mountTimeline(historyMounted: StreamItem[]) {
+  const strategy = createWebStreamStrategy({ isMobileBreakpoint: true });
+  const viewportRef = React.createRef<StreamViewportHandle>();
+  const input: StreamRenderInput = {
+    agentId: "agent",
+    segments: { historyVirtualized: [], historyMounted, liveHead: [] },
+    boundary: { hasVirtualizedHistory: false, hasMountedHistory: true, hasLiveHead: false },
+    renderers: {
+      renderHistoryVirtualizedRow: renderRow,
+      renderHistoryMountedRow: renderRow,
+      renderLiveHeadRow: renderRow,
+      renderLiveAuxiliary: () => null,
+    },
+    listEmptyComponent: null,
+    viewportRef,
+    routeBottomAnchorRequest: null,
+    isAuthoritativeHistoryReady: true,
+    onNearBottomChange: () => {},
+    onNearHistoryStart: () => true,
+    isLoadingOlderHistory: false,
+    hasOlderHistory: false,
+    olderHistoryProgressKey: null,
+    scrollEnabled: true,
+    listStyle: null,
+    baseListContentContainerStyle: null,
+    forwardListContentContainerStyle: null,
+    contentMaxWidth: DEFAULT_CONTENT_MAX_WIDTH,
+  };
+  const render = (segments: Partial<StreamRenderInput["segments"]>) =>
+    root.render(strategy.render({ ...input, segments: { ...input.segments, ...segments } }));
+  act(() => render({}));
+
+  const scrollContainer = host.querySelector<HTMLElement>('[data-testid="agent-chat-scroll"]');
+  if (!scrollContainer) throw new Error("Expected agent chat scroll container");
+  const rowElement = (id: string) => {
+    const element = host.querySelector<HTMLElement>(`[data-history-row-id="${id}"]`);
+    if (!element) throw new Error(`Expected row ${id}`);
+    return element;
+  };
+
+  return {
+    render: (segments: Partial<StreamRenderInput["segments"]>) => act(() => render(segments)),
+    hold: (rowId: string, apply: () => void) =>
+      act(() => viewportRef.current!.holdRow(rowId, apply)),
+    rowTop: (id: string) =>
+      rowElement(id).getBoundingClientRect().top - scrollContainer.getBoundingClientRect().top,
+    distanceFromEnd: () =>
+      scrollContainer.scrollHeight - scrollContainer.clientHeight - scrollContainer.scrollTop,
+    // Resize observers and the hold's settle run on animation frames.
+    settle: () =>
+      act(async () => {
+        for (let frame = 0; frame < 4; frame += 1) {
+          await new Promise((resolve) => requestAnimationFrame(resolve));
+        }
+      }),
+  };
+}
+
+describe("web disclosure hold", () => {
+  it("keeps the trigger's top when an anchored toggle at the bottom opens rows below it, and stops following", async () => {
+    const history = [1, 2, 3, 4, 5, 6].map((index) => row(index));
+    const timeline = mountTimeline(history);
+    await timeline.settle();
+    expect(timeline.distanceFromEnd()).toBeLessThanOrEqual(1);
+    const triggerTop = timeline.rowTop("message-5");
+
+    timeline.hold("message-5", () =>
+      timeline.render({ historyMounted: [...history.slice(0, 5), row(7, 200), history[5]!] }),
+    );
+    await timeline.settle();
+    expect(timeline.rowTop("message-5")).toBe(triggerTop);
+
+    timeline.render({ liveHead: [row(8)] });
+    await timeline.settle();
+    expect(timeline.rowTop("message-5")).toBe(triggerTop);
+  });
+
+  it("keeps the trigger's top when its row grows while following output", async () => {
+    const history = [1, 2, 3, 4, 5, 6].map((index) => row(index));
+    const timeline = mountTimeline(history);
+    await timeline.settle();
+    const triggerTop = timeline.rowTop("message-5");
+
+    timeline.hold("message-5", () =>
+      timeline.render({ historyMounted: [...history.slice(0, 4), row(5, 240), history[5]!] }),
+    );
+    await timeline.settle();
+    expect(timeline.rowTop("message-5")).toBe(triggerTop);
+  });
+
+  it("resumes following when collapsing an anchored row lands back at the end", async () => {
+    const history = [1, 2, 3, 4, 5, 6].map((index) => row(index));
+    const timeline = mountTimeline(history);
+    await timeline.settle();
+    timeline.hold("message-5", () =>
+      timeline.render({ historyMounted: [...history.slice(0, 4), row(5, 240), history[5]!] }),
+    );
+    await timeline.settle();
+
+    timeline.hold("message-5", () => timeline.render({ historyMounted: history }));
+    await timeline.settle();
+
+    timeline.render({ liveHead: [row(8)] });
+    await timeline.settle();
+    expect(timeline.distanceFromEnd()).toBeLessThanOrEqual(1);
+  });
+});
diff --git a/packages/app/src/agent-stream/strategy-web.tsx b/packages/app/src/agent-stream/strategy-web.tsx
index 9dae42bcc0..904ab9c157 100644
--- a/packages/app/src/agent-stream/strategy-web.tsx
+++ b/packages/app/src/agent-stream/strategy-web.tsx
@@ -363,6 +363,8 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
   const wasFollowOutputLayoutActiveRef = useRef(false);
   const resumedUnchangedLayoutRef = useRef(false);
   const pendingResumeGeometryCheckRef = useRef(false);
+  // Set by holdRow; the next reading reconcile sees the disclosure's layout.
+  const disclosurePendingRef = useRef(false);
   const shouldUseVirtualizer = segments.historyVirtualized.length > 0;
   const {
     renderHistoryVirtualizedRow,
@@ -728,22 +730,27 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
     onNearBottomChange,
   });
 
-  const reconcileReadingPosition = useStableEvent(() => {
+  // Row tops in content coordinates, which survive scrolling.
+  const measureRows = useStableEvent(() => {
     const container = scrollContainerRef.current;
     const content = contentRef.current;
-    if (!isActiveRef.current || !container || !content) return;
+    if (!container || !content) return null;
     const viewportTop = container.getBoundingClientRect().top;
     const scrollTop = container.scrollTop;
     const width = content.getBoundingClientRect().width;
-    const rows = Array.from(
-      content.querySelectorAll<HTMLElement>("[data-history-row-id]"),
-      (element) => {
-        const bounds = element.getBoundingClientRect();
-        const id = element.dataset.historyRowId!;
-        measuredRowHeights.current.set(id, { width, height: bounds.height });
-        return { id, top: bounds.top - viewportTop + scrollTop, height: bounds.height };
-      },
-    );
+    return Array.from(content.querySelectorAll<HTMLElement>("[data-history-row-id]"), (element) => {
+      const bounds = element.getBoundingClientRect();
+      const id = element.dataset.historyRowId!;
+      measuredRowHeights.current.set(id, { width, height: bounds.height });
+      return { id, top: bounds.top - viewportTop + scrollTop, height: bounds.height };
+    });
+  });
+
+  const reconcileReadingPosition = useStableEvent(() => {
+    const container = scrollContainerRef.current;
+    if (!isActiveRef.current || !container) return;
+    const rows = measureRows();
+    if (!rows) return;
     const shouldAnchor = !followOutputRef.current && !isJumpSettling();
     if (!shouldAnchor) readingAnchor.reset();
     const correctedTop = readingAnchor.reconcile(
@@ -763,6 +770,11 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
       // this layout so the reader does not get a frame containing only the pin.
       virtualOffsetListener.current?.(container.scrollTop, false);
     }
+    // A disclosure that closes back to the end of the list rejoins the output.
+    if (disclosurePendingRef.current) {
+      disclosurePendingRef.current = false;
+      if (isScrollContainerAtBottom(container)) setFollowOutput(true);
+    }
   });
 
   // Apply row positions and their scroll correction in the same paint, including
@@ -1182,10 +1194,13 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
         }
         scheduleStickToBottom();
       },
-      holdReadingPosition: () => {
+      holdRow: (rowId, apply) => {
         cancelPendingStickToBottom();
         setFollowOutput(false);
-        readingAnchor.scroll(scrollContainerRef.current?.scrollTop ?? 0);
+        const row = measureRows()?.find((candidate) => candidate.id === rowId);
+        if (row) readingAnchor.pin(row);
+        disclosurePendingRef.current = true;
+        apply();
       },
       scrollToMessage,
     };
@@ -1199,6 +1214,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
   }, [
     cancelPendingStickToBottom,
     forceStickToBottom,
+    measureRows,
     readingAnchor,
     scheduleStickToBottom,
     scrollToMessage,
@@ -1392,9 +1408,6 @@ export function createWebStreamStrategy(input: CreateWebStreamStrategyInput): St
     historyLiveBoundaryEdge: "last",
     liveHeadHistoryBoundaryEdge: "first",
     frameChildOrder: "content-then-footer",
-    flatListInverted: false,
-    overlayScrollbarInverted: false,
-    maintainVisibleContentPosition: undefined,
     bottomAnchorTransportBehavior: {
       verificationDelayFrames: 0,
       verificationRetryMode: "rescroll",
diff --git a/packages/app/src/agent-stream/strategy.ts b/packages/app/src/agent-stream/strategy.ts
index 364eba1043..d1d40d351f 100644
--- a/packages/app/src/agent-stream/strategy.ts
+++ b/packages/app/src/agent-stream/strategy.ts
@@ -14,11 +14,6 @@ type NeighborRelation = "above" | "below";
 type AssistantTurnTraversalStep = -1 | 1;
 export type StreamFrameChildOrder = "content-then-footer" | "footer-then-content";
 
-export type MaintainVisibleContentPositionConfig = Readonly<{
-  minIndexForVisible: number;
-  autoscrollToTopThreshold: number;
-}>;
-
 export type BottomAnchorTransportBehavior = Readonly<{
   verificationDelayFrames: number;
   verificationRetryMode: "rescroll" | "recheck";
@@ -56,8 +51,11 @@ export interface StreamViewportHandle {
   focus?: () => void;
   scrollToBottom: (reason?: BottomAnchorLocalRequest["reason"]) => void;
   prepareForViewportChange: () => void;
-  /** Stop following output so the rows on screen stay put while rows below them open or close. */
-  holdReadingPosition: () => void;
+  /**
+   * Run a disclosure's state change so the row that owns its trigger keeps its visual top.
+   * Following output stops; it resumes if the change leaves the list at its end.
+   */
+  holdRow: (rowId: string, apply: () => void) => void;
   scrollToMessage?: (messageId: string, occurrence?: ScrollToMessageOccurrence) => void;
 }
 
@@ -125,14 +123,11 @@ export interface StreamStrategy {
     component: ReactElement | ComponentType<unknown> | null,
     gapSize: number,
   ) => StreamEdgeSlotProps;
-  getMaintainVisibleContentPosition: () => MaintainVisibleContentPositionConfig | undefined;
   getBottomAnchorTransportBehavior: () => BottomAnchorTransportBehavior;
   getHistoryLiveBoundaryIndex: (history: StreamItem[]) => number | null;
   getLiveHeadHistoryBoundaryIndex: (liveHead: StreamItem[]) => number | null;
   getLatestItemIndex: (items: StreamItem[]) => number | null;
   getFrameChildOrder: () => StreamFrameChildOrder;
-  getFlatListInverted: () => boolean;
-  getOverlayScrollbarInverted: () => boolean;
   shouldDisableParentScrollOnInlineDetailsExpansion: () => boolean;
   shouldAnchorBottomOnContentSizeChange: () => boolean;
   shouldAnimateManualScrollToBottom: () => boolean;
@@ -148,9 +143,6 @@ interface StreamStrategyConfig {
   historyLiveBoundaryEdge: "first" | "last";
   liveHeadHistoryBoundaryEdge: "first" | "last";
   frameChildOrder: StreamFrameChildOrder;
-  flatListInverted: boolean;
-  overlayScrollbarInverted: boolean;
-  maintainVisibleContentPosition?: MaintainVisibleContentPositionConfig;
   bottomAnchorTransportBehavior: BottomAnchorTransportBehavior;
   disableParentScrollOnInlineDetailsExpansion: boolean;
   anchorBottomOnContentSizeChange: boolean;
@@ -160,8 +152,6 @@ interface StreamStrategyConfig {
   getBottomOffset: (metrics: StreamViewportMetrics) => number;
 }
 
-const NATIVE_SETTLING_VERIFICATION_DELAY_FRAMES = 4;
-
 export function createStreamStrategy(config: StreamStrategyConfig): StreamStrategy {
   return {
     render: config.render,
@@ -216,7 +206,6 @@ export function createStreamStrategy(config: StreamStrategyConfig): StreamStrate
         ListFooterComponentStyle: { marginTop: gapSize },
       };
     },
-    getMaintainVisibleContentPosition: () => config.maintainVisibleContentPosition,
     getBottomAnchorTransportBehavior: () => config.bottomAnchorTransportBehavior,
     getHistoryLiveBoundaryIndex: (history) => {
       if (history.length === 0) {
@@ -237,8 +226,6 @@ export function createStreamStrategy(config: StreamStrategyConfig): StreamStrate
       return config.historyLiveBoundaryEdge === "first" ? 0 : items.length - 1;
     },
     getFrameChildOrder: () => config.frameChildOrder,
-    getFlatListInverted: () => config.flatListInverted,
-    getOverlayScrollbarInverted: () => config.overlayScrollbarInverted,
     shouldDisableParentScrollOnInlineDetailsExpansion: () =>
       config.disableParentScrollOnInlineDetailsExpansion,
     shouldAnchorBottomOnContentSizeChange: () => config.anchorBottomOnContentSizeChange,
@@ -247,23 +234,6 @@ export function createStreamStrategy(config: StreamStrategyConfig): StreamStrate
   };
 }
 
-export function resolveBottomAnchorTransportBehavior(input: {
-  strategy: StreamStrategy;
-  isViewportSettling: boolean;
-}): BottomAnchorTransportBehavior {
-  const baseBehavior = input.strategy.getBottomAnchorTransportBehavior();
-  if (!input.isViewportSettling || !input.strategy.getFlatListInverted()) {
-    return baseBehavior;
-  }
-  return {
-    verificationDelayFrames: Math.max(
-      baseBehavior.verificationDelayFrames,
-      NATIVE_SETTLING_VERIFICATION_DELAY_FRAMES,
-    ),
-    verificationRetryMode: "recheck",
-  };
-}
-
 export function orderTailForStreamRenderStrategy(params: {
   strategy: StreamStrategy;
   streamItems: StreamItem[];
diff --git a/packages/app/src/agent-stream/stream-row.browser.test.tsx b/packages/app/src/agent-stream/stream-row.browser.test.tsx
new file mode 100644
index 0000000000..7608704d2d
--- /dev/null
+++ b/packages/app/src/agent-stream/stream-row.browser.test.tsx
@@ -0,0 +1,69 @@
+import { act, createRef } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, expect, it } from "vitest";
+import type { StreamItem } from "@/types/stream";
+import type { StreamLayoutItem } from "./layout";
+import type { StreamViewportHandle } from "./strategy";
+import { renderStreamRow } from "./stream-row";
+
+// stream-row.tsx is compiled with the React Compiler here, as Expo compiles it.
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+let root: Root;
+let host: HTMLDivElement;
+
+beforeEach(() => {
+  host = document.createElement("div");
+  document.body.appendChild(host);
+  root = createRoot(host);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  host.remove();
+});
+
+const turnHost: StreamItem = {
+  kind: "user_message",
+  id: "host",
+  text: "Fix the build",
+  timestamp: new Date(0),
+};
+
+const turnHostLayout: StreamLayoutItem = {
+  item: turnHost,
+  aboveItem: null,
+  // The turn's rows land below another row, so opening it leaves the host's layout unchanged.
+  belowItem: null,
+  gapBelow: 0,
+  assistantSpacing: "default",
+  completedFooter: null,
+  toolSequence: "none",
+  isFirstInUserGroup: true,
+  isLastInUserGroup: true,
+  isLastInToolSequence: false,
+  frameOrder: "content-then-footer",
+  phase: "complete",
+};
+
+it("renders a revised row again when its layout is unchanged", () => {
+  // The turn's open state lives outside the row, as `getCollapsedTurn` reads it in view.tsx.
+  let turnOpen = false;
+  const renderStreamItem = () => <span>{turnOpen ? "open" : "closed"}</span>;
+  const viewportRef = createRef<StreamViewportHandle>();
+  const layoutItemById = new Map([[turnHost.id, turnHostLayout]]);
+  const renderRow = (item: StreamItem) =>
+    act(() =>
+      root.render(renderStreamRow({ item, layoutItemById, renderStreamItem, viewportRef })),
+    );
+
+  renderRow(turnHost);
+  expect(host.textContent).toBe("closed");
+
+  turnOpen = true;
+  // useRevisedHistoryRows hands the row a fresh item when its display state changes.
+  renderRow({ ...turnHost });
+
+  expect(host.textContent).toBe("open");
+});
diff --git a/packages/app/src/agent-stream/stream-row.tsx b/packages/app/src/agent-stream/stream-row.tsx
new file mode 100644
index 0000000000..874b032f1d
--- /dev/null
+++ b/packages/app/src/agent-stream/stream-row.tsx
@@ -0,0 +1,58 @@
+import { memo, type ReactNode, type RefObject } from "react";
+import type { StreamItem } from "@/types/stream";
+import { DisclosureRow } from "./disclosure";
+import type { StreamLayoutItem } from "./layout";
+import type { StreamViewportHandle } from "./strategy";
+
+/**
+ * Renders a timeline row from the item the row was handed. The item is a revision of
+ * `layoutItem.item` with the same content: render from it, so a revision that leaves the layout
+ * unchanged still renders the row again.
+ */
+export type RenderStreamItem = (item: StreamItem, layoutItem: StreamLayoutItem) => ReactNode;
+
+// Live and retained rows use the same boundary so completion preserves the message
+// subtree, including measured diagrams and selections. LegendList renders every mounted row
+// again when `extraData` (the history renderer) changes, and history rows shift index when older
+// history loads. This boundary limits that pass: a row renders again only when its stream item
+// identity, its layout item identity, or the renderer itself changes. Item identity is the
+// revision signal the strategy already uses (`useRevisedHistoryRows` clones items whose content or
+// display state changed). The row passes the item to the renderer, so the React Compiler's cache
+// of the rendered content keys on it too.
+const StreamRow = memo(function StreamRow({
+  item,
+  layoutItem,
+  renderStreamItem,
+  viewportRef,
+}: {
+  item: StreamItem;
+  layoutItem: StreamLayoutItem;
+  renderStreamItem: RenderStreamItem;
+  viewportRef: RefObject<StreamViewportHandle | null>;
+}) {
+  return (
+    <DisclosureRow rowId={item.id} viewportRef={viewportRef}>
+      {renderStreamItem(item, layoutItem)}
+    </DisclosureRow>
+  );
+});
+
+export function renderStreamRow(input: {
+  item: StreamItem;
+  layoutItemById: Map<string, StreamLayoutItem>;
+  renderStreamItem: RenderStreamItem;
+  viewportRef: RefObject<StreamViewportHandle | null>;
+}): ReactNode {
+  const layoutItem = input.layoutItemById.get(input.item.id);
+  if (!layoutItem) {
+    return null;
+  }
+  return (
+    <StreamRow
+      item={input.item}
+      layoutItem={layoutItem}
+      renderStreamItem={input.renderStreamItem}
+      viewportRef={input.viewportRef}
+    />
+  );
+}
diff --git a/packages/app/src/agent-stream/top-overlay.ts b/packages/app/src/agent-stream/top-overlay.ts
index 24cd7f9592..12652580e2 100644
--- a/packages/app/src/agent-stream/top-overlay.ts
+++ b/packages/app/src/agent-stream/top-overlay.ts
@@ -1,7 +1,7 @@
 import { createContext, useContext } from "react";
 import { isNative } from "@/constants/platform";
 
-/** The native inverted viewport reserves visual-top clearance; web stays in flow. */
+/** The native viewport reserves top clearance under the overlay; web stays in flow. */
 export const supportsStreamTopOverlay = isNative;
 
 const StreamTopOverlayContext = createContext(0);
diff --git a/packages/app/src/agent-stream/turn-collapse/model.test.ts b/packages/app/src/agent-stream/turn-collapse/model.test.ts
index eca6d8757c..d46085f95d 100644
--- a/packages/app/src/agent-stream/turn-collapse/model.test.ts
+++ b/packages/app/src/agent-stream/turn-collapse/model.test.ts
@@ -41,6 +41,7 @@ function collapse(tail: StreamItem[], options: Partial<CollapseTurnsInput> = {})
     isLatestTurnOpen: false,
     expandedHostIds: new Set(),
     getGroupedCalls: () => undefined,
+    previousTurnsByHostId: new Map(),
     ...options,
   });
 }
@@ -48,6 +49,37 @@ function collapse(tail: StreamItem[], options: Partial<CollapseTurnsInput> = {})
 const ids = (items: StreamItem[]) => items.map((item) => item.id);
 
 describe("collapseTurns", () => {
+  // A history row renders again only when its item changes, so a prompt that is already retained
+  // when its turn closes needs its row revised to show the summary line.
+  it("reports the hosts whose summary line appeared, changed or went away", () => {
+    const open = collapse([user("u1"), shell("c1"), reply("r1"), user("u2"), shell("c2")], {
+      isLatestTurnOpen: true,
+    });
+    expect([...open.updatedHostIds]).toEqual(["u1"]);
+    const closed = collapse(
+      [user("u1"), shell("c1"), reply("r1"), user("u2"), shell("c2"), reply("r2")],
+      {
+        previousTurnsByHostId: open.turnsByHostId,
+      },
+    );
+    expect([...closed.updatedHostIds]).toEqual(["u2"]);
+    const unchanged = collapse(
+      [user("u1"), shell("c1"), reply("r1"), user("u2"), shell("c2"), reply("r2")],
+      {
+        previousTurnsByHostId: closed.turnsByHostId,
+      },
+    );
+    expect(unchanged.updatedHostIds.size).toBe(0);
+    const moreWork = collapse(
+      [user("u1"), shell("c1"), reply("r1"), user("u2"), shell("c2"), shell("c3"), reply("r2")],
+      { previousTurnsByHostId: unchanged.turnsByHostId },
+    );
+    expect([...moreWork.updatedHostIds]).toEqual(["u2"]);
+    const rewound = collapse([user("u1"), shell("c1"), reply("r1")], {
+      previousTurnsByHostId: moreWork.turnsByHostId,
+    });
+    expect([...rewound.updatedHostIds]).toEqual(["u2"]);
+  });
   it("maps hidden rows only while their turn is closed", () => {
     const result = collapse([user("u1"), shell("c1"), reply("final")]);
     expect(result.hostIdByHiddenRowId.get("c1")).toBe("u1");
diff --git a/packages/app/src/agent-stream/turn-collapse/model.ts b/packages/app/src/agent-stream/turn-collapse/model.ts
index a5985e600f..167a7cc219 100644
--- a/packages/app/src/agent-stream/turn-collapse/model.ts
+++ b/packages/app/src/agent-stream/turn-collapse/model.ts
@@ -27,6 +27,11 @@ export interface TurnCollapse {
   hostIdByFoldedMessageId: ReadonlyMap<string, string>;
   /** Mounted rows replaced by a closed turn's host, for preserving the reading position. */
   hostIdByHiddenRowId: ReadonlyMap<string, string>;
+  /**
+   * Hosts whose summary line appeared, changed or went away since `previousTurnsByHostId`. A
+   * history row renders again only when its item changes, so these rows are revised.
+   */
+  updatedHostIds: ReadonlySet<string>;
 }
 
 export interface CollapseTurnsInput {
@@ -36,6 +41,8 @@ export interface CollapseTurnsInput {
   expandedHostIds: ReadonlySet<string>;
   /** The calls a tool-call group row stands for; undefined for a single call. */
   getGroupedCalls: (itemId: string) => readonly (ToolCallItem | ThoughtItem)[] | undefined;
+  /** The previous fold of the same history, the baseline for `updatedHostIds`. */
+  previousTurnsByHostId: ReadonlyMap<string, CollapsedTurn>;
 }
 
 const EMPTY_TURNS: ReadonlyMap<string, CollapsedTurn> = new Map();
@@ -59,6 +66,36 @@ function hasWork(summary: TurnSummary): boolean {
   return Object.keys(paseoActions).length > 0 || Object.values(counts).some((count) => count > 0);
 }
 
+function isSameTurn(a: CollapsedTurn, b: CollapsedTurn): boolean {
+  const { paseoActions: actionsA, ...countsA } = a.summary.tools;
+  const { paseoActions: actionsB, ...countsB } = b.summary.tools;
+  return (
+    a.expanded === b.expanded &&
+    hasSameCounts(countsA, countsB) &&
+    hasSameCounts(actionsA, actionsB)
+  );
+}
+
+function hasSameCounts(a: Record<string, number>, b: Record<string, number>): boolean {
+  const keys = Object.keys(a);
+  return keys.length === Object.keys(b).length && keys.every((key) => a[key] === b[key]);
+}
+
+function findUpdatedHosts(
+  previous: ReadonlyMap<string, CollapsedTurn>,
+  next: ReadonlyMap<string, CollapsedTurn>,
+): ReadonlySet<string> {
+  const updated = new Set<string>();
+  for (const [hostId, turn] of next) {
+    const before = previous.get(hostId);
+    if (!before || !isSameTurn(before, turn)) updated.add(hostId);
+  }
+  for (const hostId of previous.keys()) {
+    if (!next.has(hostId)) updated.add(hostId);
+  }
+  return updated.size === 0 ? EMPTY_IDS : updated;
+}
+
 function staysVisibleWhenCollapsed(item: StreamItem): boolean {
   return isTurnTrigger(item) || item.kind === "compaction";
 }
@@ -137,6 +174,7 @@ export function collapseTurns(input: CollapseTurnsInput): TurnCollapse {
   }
   flushRun(tail.length);
 
+  const updatedHostIds = findUpdatedHosts(input.previousTurnsByHostId, turnsByHostId);
   if (turnsByHostId.size === 0) {
     return {
       tail,
@@ -144,6 +182,7 @@ export function collapseTurns(input: CollapseTurnsInput): TurnCollapse {
       nestedItemIds: EMPTY_IDS,
       hostIdByFoldedMessageId: EMPTY_HOSTS,
       hostIdByHiddenRowId: EMPTY_HOSTS,
+      updatedHostIds,
     };
   }
   return {
@@ -155,5 +194,6 @@ export function collapseTurns(input: CollapseTurnsInput): TurnCollapse {
     nestedItemIds,
     hostIdByFoldedMessageId,
     hostIdByHiddenRowId,
+    updatedHostIds,
   };
 }
diff --git a/packages/app/src/agent-stream/turn-collapse/summary-line.tsx b/packages/app/src/agent-stream/turn-collapse/summary-line.tsx
index 191ac706d5..22660b4606 100644
--- a/packages/app/src/agent-stream/turn-collapse/summary-line.tsx
+++ b/packages/app/src/agent-stream/turn-collapse/summary-line.tsx
@@ -1,6 +1,7 @@
 import { memo, useCallback } from "react";
 import { useTranslation } from "react-i18next";
 import { Summary } from "lucide-react-native";
+import { useDisclosureHold } from "@/agent-stream/disclosure";
 import { ExpandableBadge } from "@/components/message";
 import { useOverviewSummaryLabel } from "@/tool-calls/detail-level/overview/label";
 import type { CollapsedTurn } from "./model";
@@ -18,9 +19,10 @@ export const TurnSummaryLine = memo(function TurnSummaryLine({
 }) {
   const { t } = useTranslation();
   const label = useOverviewSummaryLabel(turn.summary.tools) || t("turnSummary.details");
+  const hold = useDisclosureHold();
   const toggle = useCallback(
-    () => onExpandedChange(turn.hostId, !turn.expanded),
-    [onExpandedChange, turn.expanded, turn.hostId],
+    () => hold(() => onExpandedChange(turn.hostId, !turn.expanded)),
+    [hold, onExpandedChange, turn.expanded, turn.hostId],
   );
 
   return (
diff --git a/packages/app/src/agent-stream/view.tsx b/packages/app/src/agent-stream/view.tsx
index 72923b4212..15d9435fd7 100644
--- a/packages/app/src/agent-stream/view.tsx
+++ b/packages/app/src/agent-stream/view.tsx
@@ -74,6 +74,8 @@ import { TurnSummaryLine } from "./turn-collapse/summary-line";
 import { type AgentStreamRenderModel, buildAgentStreamRenderModel } from "./model";
 import { resolveStreamRenderStrategy } from "./strategy-resolver";
 import { type StreamSegmentRenderers, type StreamViewportHandle } from "./strategy";
+import { renderStreamRow, type RenderStreamItem } from "./stream-row";
+import { type NearBottom, useIsNearBottom, useNearBottom } from "./near-bottom";
 import { ChatOutlineRail } from "@/agent-stream/chat-outline/rail";
 import { useChatOutline } from "@/agent-stream/chat-outline/use-chat-outline";
 import { getHostRuntimeStore } from "@/runtime/host-runtime";
@@ -230,41 +232,6 @@ function renderListEmptyComponent(input: {
   );
 }
 
-// Live and retained rows use the same boundary so completion preserves the message
-// subtree, including measured diagrams and selections. FlatList recreates history
-// cells with fresh refs and shifted indexes on data changes. This boundary is
-// what stops that churn: a row renders again only when its stream item identity, its layout item
-// identity, or the renderer itself changes. Item identity is the revision signal the strategy
-// already uses (`useRevisedHistoryRows` clones items whose content or display state changed).
-const StreamRow = memo(function StreamRow({
-  layoutItem,
-  renderStreamItem,
-}: {
-  item: StreamItem;
-  layoutItem: StreamLayoutItem;
-  renderStreamItem: (layoutItem: StreamLayoutItem) => ReactNode;
-}) {
-  return <>{renderStreamItem(layoutItem)}</>;
-});
-
-function renderStreamRow(input: {
-  item: StreamItem;
-  layoutItemById: Map<string, StreamLayoutItem>;
-  renderStreamItem: (layoutItem: StreamLayoutItem) => ReactNode;
-}): ReactNode {
-  const layoutItem = input.layoutItemById.get(input.item.id);
-  if (!layoutItem) {
-    return null;
-  }
-  return (
-    <StreamRow
-      item={input.item}
-      layoutItem={layoutItem}
-      renderStreamItem={input.renderStreamItem}
-    />
-  );
-}
-
 export interface AgentStreamViewHandle {
   scrollToBottom(reason?: BottomAnchorLocalRequest["reason"]): void;
   prepareForViewportChange(): void;
@@ -324,6 +291,47 @@ function resolveBottomOverlayControlOffset(clearance: number | undefined): numbe
   return Math.max(16, clearance ?? 0);
 }
 
+// Keep entry/exit animations off on Android due to RN dispatchDraw crashes
+// tracked in react-native-reanimated#8422.
+const shouldDisableEntryExitAnimations = Platform.OS === "android";
+const scrollIndicatorFadeIn = shouldDisableEntryExitAnimations ? undefined : FadeIn.duration(200);
+const scrollIndicatorFadeOut = shouldDisableEntryExitAnimations ? undefined : FadeOut.duration(200);
+
+function ScrollToBottomButton({
+  nearBottom,
+  isTimelineDetached,
+  bottomOffset,
+  onPress,
+}: {
+  nearBottom: NearBottom;
+  isTimelineDetached: boolean;
+  bottomOffset: number;
+  onPress: () => void;
+}) {
+  const { t } = useTranslation();
+  const isNearBottom = useIsNearBottom(nearBottom);
+  const containerStyle = useMemo(
+    () => [stylesheet.scrollToBottomContainer, { bottom: bottomOffset }],
+    [bottomOffset],
+  );
+  if (isNearBottom && !isTimelineDetached) return null;
+  return (
+    <View style={containerStyle} pointerEvents="box-none">
+      <Animated.View entering={scrollIndicatorFadeIn} exiting={scrollIndicatorFadeOut}>
+        <Pressable
+          style={stylesheet.scrollToBottomButton}
+          onPress={onPress}
+          accessibilityRole="button"
+          accessibilityLabel={t("agentStream.scrollToBottom")}
+          testID="scroll-to-bottom-button"
+        >
+          <ChevronDown size={24} color={stylesheet.scrollToBottomIcon.color} />
+        </Pressable>
+      </Animated.View>
+    </View>
+  );
+}
+
 const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamViewProps>(
   function AgentStreamView(
     {
@@ -365,7 +373,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
         }),
       [isMobile],
     );
-    const [isNearBottom, setIsNearBottom] = useState(true);
+    const nearBottom = useNearBottom(agentId);
     const [expandedInlineToolCallIds, setExpandedInlineToolCallIds] = useState<Set<string>>(
       new Set(),
     );
@@ -422,18 +430,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
           loadOlder: historyPagination.onLoadOlder,
         }
       : agentHistoryPagination;
-    // Keep entry/exit animations off on Android due to RN dispatchDraw crashes
-    // tracked in react-native-reanimated#8422.
-    const shouldDisableEntryExitAnimations = Platform.OS === "android";
-    const scrollIndicatorFadeIn = shouldDisableEntryExitAnimations
-      ? undefined
-      : FadeIn.duration(200);
-    const scrollIndicatorFadeOut = shouldDisableEntryExitAnimations
-      ? undefined
-      : FadeOut.duration(200);
-
     useEffect(() => {
-      setIsNearBottom(true);
       setExpandedInlineToolCallIds(new Set());
       setExpandedTurnHostIds(new Set());
     }, [agentId]);
@@ -675,9 +672,8 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
       [streamRenderStrategy],
     );
 
+    // The summary line holds its row around this; chat find opens a turn without a hold.
     const setTurnExpanded = useCallback((hostId: string, expanded: boolean) => {
-      // A turn opens below its summary line; keep that line under the reader's pointer.
-      viewportRef.current?.holdReadingPosition();
       setExpandedTurnHostIds((previous) => {
         if (previous.has(hostId) === expanded) return previous;
         const next = new Set(previous);
@@ -928,8 +924,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
     );
 
     const renderStreamItemContent = useCallback(
-      (layoutItem: StreamLayoutItem) => {
-        const item = layoutItem.item;
+      (item: StreamItem, layoutItem: StreamLayoutItem) => {
         switch (item.kind) {
           case "user_message":
             return renderUserMessageItem(layoutItem, item);
@@ -990,9 +985,9 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
 
     const bottomTurnFooterHost = streamLayout.auxiliaryTurnFooter;
 
-    const renderStreamItem = useCallback(
-      (layoutItem: StreamLayoutItem) => {
-        const content = renderStreamItemContent(layoutItem);
+    const renderStreamItem = useCallback<RenderStreamItem>(
+      (item, layoutItem) => {
+        const content = renderStreamItemContent(item, layoutItem);
         return renderStreamItemWithTurnFooter({
           content,
           layoutItem,
@@ -1061,13 +1056,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
     }, [baseRenderModel, pendingPermissionsNode, turnFooterNode]);
 
     const emptyStateStyle = useMemo(() => [stylesheet.emptyState, stylesheet.contentWrapper], []);
-    const scrollToBottomContainerStyle = useMemo(
-      () => [
-        stylesheet.scrollToBottomContainer,
-        { bottom: resolveBottomOverlayControlOffset(bottomOverlayControlClearance) },
-      ],
-      [bottomOverlayControlClearance],
-    );
+    const scrollToBottomOffset = resolveBottomOverlayControlOffset(bottomOverlayControlClearance);
     const listEmptyComponent = useMemo(
       () =>
         renderListEmptyComponent({
@@ -1110,6 +1099,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
           item,
           layoutItemById: layoutHistoryItemById,
           renderStreamItem,
+          viewportRef,
         }),
       [layoutHistoryItemById, renderStreamItem],
     );
@@ -1131,6 +1121,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
           item,
           layoutItemById: layoutLiveHeadItemById,
           renderStreamItem,
+          viewportRef,
         }),
     );
     const renderLiveAuxiliary = useCallback<StreamSegmentRenderers["renderLiveAuxiliary"]>(() => {
@@ -1165,10 +1156,13 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
     const streamScrollEnabled =
       !streamRenderStrategy.shouldDisableParentScrollOnInlineDetailsExpansion() ||
       expandedInlineToolCallIds.size === 0;
-    const { nestedItemIds } = presentation.turns;
+    const { nestedItemIds, updatedHostIds: updatedTurnHostIds } = presentation.turns;
     const historyRowRevision = useMemo(
       () => ({
-        contentById: presentation.historyGroupUpdatesByHostId,
+        contentById: {
+          has: (id: string) =>
+            presentation.historyGroupUpdatesByHostId.has(id) || updatedTurnHostIds.has(id),
+        },
         displayStateById: {
           // An opened lone call also marks its future group open; that row stays unrevised
           // until a group actually forms there.
@@ -1186,6 +1180,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
         isMobile,
         nestedItemIds,
         presentation.historyGroupUpdatesByHostId,
+        updatedTurnHostIds,
       ],
     );
 
@@ -1219,7 +1214,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
                   viewportRef,
                   routeBottomAnchorRequest,
                   isAuthoritativeHistoryReady,
-                  onNearBottomChange: setIsNearBottom,
+                  onNearBottomChange: nearBottom.set,
                   onReadingPositionChange: handleReadingPositionChange,
                   onNearHistoryStart: loadOlder,
                   isLoadingOlderHistory: isLoadingOlder,
@@ -1238,21 +1233,12 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
               activePrompt={chatOutline.activePrompt}
               onJumpToPrompt={chatOutline.jumpToPrompt}
             />
-            {(!isNearBottom || isTimelineDetached) && (
-              <View style={scrollToBottomContainerStyle} pointerEvents="box-none">
-                <Animated.View entering={scrollIndicatorFadeIn} exiting={scrollIndicatorFadeOut}>
-                  <Pressable
-                    style={stylesheet.scrollToBottomButton}
-                    onPress={scrollToBottom}
-                    accessibilityRole="button"
-                    accessibilityLabel={t("agentStream.scrollToBottom")}
-                    testID="scroll-to-bottom-button"
-                  >
-                    <ChevronDown size={24} color={stylesheet.scrollToBottomIcon.color} />
-                  </Pressable>
-                </Animated.View>
-              </View>
-            )}
+            <ScrollToBottomButton
+              nearBottom={nearBottom}
+              isTimelineDetached={isTimelineDetached}
+              bottomOffset={scrollToBottomOffset}
+              onPress={scrollToBottom}
+            />
           </AssistantSelectionCopySurface>
         </ToolCallSheetProvider>
       </ChatFind>
@@ -1789,10 +1775,6 @@ const stylesheet = StyleSheet.create((theme) => ({
     color: theme.colors.foregroundMuted,
     fontSize: theme.fontSize.base,
   },
-  invertedWrapper: {
-    transform: [{ scaleY: -1 }],
-    width: "100%",
-  },
   emptyStateText: {
     color: theme.colors.foregroundMuted,
     fontSize: theme.fontSize.base,
diff --git a/packages/app/src/components/message.tsx b/packages/app/src/components/message.tsx
index 0ec5cbfb44..e73dd4171f 100644
--- a/packages/app/src/components/message.tsx
+++ b/packages/app/src/components/message.tsx
@@ -1,3 +1,4 @@
+import { useDisclosureHold } from "@/agent-stream/disclosure";
 import { MessagePreview, MessageSender } from "@/components/user-message";
 import { useStableEvent } from "@/hooks/use-stable-event";
 import { getAgentAttachmentPillContent } from "@/attachments/attachment-pill-content";
@@ -1483,9 +1484,9 @@ export const TodoListCard = memo(function TodoListCard({
     };
   }, [activity, t]);
 
-  const handleToggle = useCallback(() => {
-    setIsExpanded((prev) => !prev);
-  }, []);
+  const hold = useDisclosureHold();
+  const toggleExpanded = useCallback(() => setIsExpanded((prev) => !prev), []);
+  const handleToggle = useCallback(() => hold(toggleExpanded), [hold, toggleExpanded]);
 
   const renderDetails = useCallback(() => {
     return (
@@ -2279,6 +2280,7 @@ export const ToolCall = memo(function ToolCall({
 
   const isMobile = useIsCompactFormFactor();
   const shouldRenderInline = !isMobile || forceInline;
+  const hold = useDisclosureHold();
 
   const effectiveDetail = useMemo<ToolCallDetail | undefined>(() => {
     if (detail) {
@@ -2330,9 +2332,10 @@ export const ToolCall = memo(function ToolCall({
         showLoadingSkeleton: presentation.isLoadingDetails,
       });
     } else {
-      toggleExpanded();
+      hold(toggleExpanded);
     }
   }, [
+    hold,
     shouldRenderInline,
     toggleExpanded,
     openToolCall,
diff --git a/packages/app/src/keyboard/shift/index.ts b/packages/app/src/keyboard/shift/index.ts
index e54fc7ace9..e570bd3fee 100644
--- a/packages/app/src/keyboard/shift/index.ts
+++ b/packages/app/src/keyboard/shift/index.ts
@@ -1,5 +1,4 @@
 export { KeyboardShiftProvider, useKeyboardShiftStyle } from "./internal/provider";
-export { useKeyboardShift, useSettledKeyboardShift } from "./internal/context";
+export { useKeyboardShift } from "./internal/context";
 export { KeyboardTranslateView } from "./internal/translate";
 export { useKeyboardAnchor } from "./internal/anchor";
-export { useKeyboardStreamInset } from "./internal/stream";
diff --git a/packages/app/src/keyboard/shift/internal/context.ts b/packages/app/src/keyboard/shift/internal/context.ts
index f010c01255..bc1df21fb4 100644
--- a/packages/app/src/keyboard/shift/internal/context.ts
+++ b/packages/app/src/keyboard/shift/internal/context.ts
@@ -41,7 +41,6 @@ export const KeyboardTranslationContext = createContext<KeyboardTranslationScope
   translation: { enabled: false, bottomClearance: 0 },
   measureAtRest: measureInWindow,
 });
-export const SettledKeyboardShiftContext = createContext<number | null>(null);
 
 /** Read the app-wide keyboard inset without loading its native provider implementation. */
 export function useKeyboardShift(): KeyboardShiftContextValue {
@@ -51,12 +50,3 @@ export function useKeyboardShift(): KeyboardShiftContextValue {
   }
   return context;
 }
-
-/** Read the keyboard inset published after native keyboard motion has settled. */
-export function useSettledKeyboardShift(): number {
-  const context = useContext(SettledKeyboardShiftContext);
-  if (context === null) {
-    throw new Error("useSettledKeyboardShift must be used inside KeyboardShiftProvider");
-  }
-  return context;
-}
diff --git a/packages/app/src/keyboard/shift/internal/policy.test.ts b/packages/app/src/keyboard/shift/internal/policy.test.ts
index 6867f3ffa1..51387eba43 100644
--- a/packages/app/src/keyboard/shift/internal/policy.test.ts
+++ b/packages/app/src/keyboard/shift/internal/policy.test.ts
@@ -1,6 +1,5 @@
 import { describe, expect, it } from "vitest";
 import {
-  resolveStreamKeyboardInset,
   shouldReconcileHiddenKeyboardEnd,
   resolveKeyboardLift,
   resolveKeyboardShift,
@@ -29,29 +28,6 @@ describe("keyboard layout reservation", () => {
   });
 });
 
-describe("resolveStreamKeyboardInset", () => {
-  it("uses the native scroll inset on iOS without changing content size", () => {
-    expect(resolveStreamKeyboardInset({ platform: "ios", settledShift: 311 })).toEqual({
-      contentContainerPaddingBottom: 0,
-      contentInset: { bottom: 311 },
-    });
-  });
-
-  it("keeps Android's exact content-container padding behavior", () => {
-    expect(resolveStreamKeyboardInset({ platform: "android", settledShift: 311 })).toEqual({
-      contentContainerPaddingBottom: 311,
-      contentInset: undefined,
-    });
-  });
-
-  it("does not expose a negative inset", () => {
-    expect(resolveStreamKeyboardInset({ platform: "ios", settledShift: -1 })).toEqual({
-      contentContainerPaddingBottom: 0,
-      contentInset: { bottom: 0 },
-    });
-  });
-});
-
 describe("resolveKeyboardShift", () => {
   it("keeps the existing open-keyboard offset behavior", () => {
     expect(
diff --git a/packages/app/src/keyboard/shift/internal/policy.ts b/packages/app/src/keyboard/shift/internal/policy.ts
index 4e618c8a49..c7d79bd9fa 100644
--- a/packages/app/src/keyboard/shift/internal/policy.ts
+++ b/packages/app/src/keyboard/shift/internal/policy.ts
@@ -10,26 +10,6 @@ export function reserveKeyboardLayoutShift(input: {
   return input.phase === "start" ? Math.max(input.current, input.target) : input.target;
 }
 
-export function resolveStreamKeyboardInset(input: {
-  platform: "android" | "ios";
-  settledShift: number;
-}): {
-  contentContainerPaddingBottom: number;
-  contentInset: { bottom: number } | undefined;
-} {
-  const settledShift = Math.max(0, input.settledShift);
-  if (input.platform === "ios") {
-    return {
-      contentContainerPaddingBottom: 0,
-      contentInset: { bottom: settledShift },
-    };
-  }
-  return {
-    contentContainerPaddingBottom: settledShift,
-    contentInset: undefined,
-  };
-}
-
 export function resolveKeyboardShift(input: {
   rawKeyboardHeight: number;
   keyboardProgress: number;
diff --git a/packages/app/src/keyboard/shift/internal/provider.ts b/packages/app/src/keyboard/shift/internal/provider.ts
index 7b2ff46eae..a99a148aef 100644
--- a/packages/app/src/keyboard/shift/internal/provider.ts
+++ b/packages/app/src/keyboard/shift/internal/provider.ts
@@ -1,4 +1,4 @@
-import { createElement, useCallback, useEffect, useMemo, useState, type ReactNode } from "react";
+import { createElement, useEffect, useMemo, type ReactNode } from "react";
 import { Platform } from "react-native";
 import type { ViewStyle } from "react-native";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
@@ -8,19 +8,17 @@ import {
 } from "react-native-keyboard-controller";
 import {
   useAnimatedStyle,
-  useAnimatedReaction,
   useDerivedValue,
   useSharedValue,
   type SharedValue,
 } from "react-native-reanimated";
-import { scheduleOnRN } from "react-native-worklets";
 import {
   DEFAULT_IOS_KEYBOARD_INSET_MIN_HEIGHT,
   resolveKeyboardShift,
   reserveKeyboardLayoutShift,
   shouldReconcileHiddenKeyboardEnd,
 } from "./policy";
-import { KeyboardShiftContext, SettledKeyboardShiftContext, useKeyboardShift } from "./context";
+import { KeyboardShiftContext, useKeyboardShift } from "./context";
 
 type KeyboardShiftMode = "translate" | "padding";
 
@@ -31,11 +29,6 @@ export function KeyboardShiftProvider({ children }: { children: ReactNode }) {
   const isIos = Platform.OS === "ios";
   const isMoving = useSharedValue(false);
   const layoutShift = useSharedValue(0);
-  const [settledShift, setSettledShift] = useState(0);
-  const publishSettledShift = useCallback((nextShift: number) => {
-    setSettledShift((currentShift) => (currentShift === nextShift ? currentShift : nextShift));
-  }, []);
-
   useEffect(() => {
     bottomInset.value = insets.bottom;
   }, [bottomInset, insets.bottom]);
@@ -93,16 +86,6 @@ export function KeyboardShiftProvider({ children }: { children: ReactNode }) {
     [bottomInset, isIos, isMoving, keyboardHeight, keyboardProgress, layoutShift],
   );
 
-  useAnimatedReaction(
-    () => ({ moving: isMoving.value, shift: shift.value }),
-    (current, previous) => {
-      if (!current.moving && (previous === null || previous.moving)) {
-        scheduleOnRN(publishSettledShift, current.shift);
-      }
-    },
-    [isMoving, publishSettledShift, shift],
-  );
-
   const value = useMemo(
     () => ({
       shift,
@@ -113,11 +96,7 @@ export function KeyboardShiftProvider({ children }: { children: ReactNode }) {
     [bottomInset, isMoving, layoutShift, shift],
   );
 
-  return createElement(
-    KeyboardShiftContext.Provider,
-    { value },
-    createElement(SettledKeyboardShiftContext.Provider, { value: settledShift }, children),
-  );
+  return createElement(KeyboardShiftContext.Provider, { value }, children);
 }
 
 export function useKeyboardShiftStyle(input: { mode: KeyboardShiftMode; enabled?: boolean }): {
diff --git a/packages/app/src/keyboard/shift/internal/stream.ts b/packages/app/src/keyboard/shift/internal/stream.ts
deleted file mode 100644
index 45fe167fe4..0000000000
--- a/packages/app/src/keyboard/shift/internal/stream.ts
+++ /dev/null
@@ -1,17 +0,0 @@
-import { useMemo } from "react";
-import { Platform } from "react-native";
-import { useSettledKeyboardShift } from "./context";
-import { resolveStreamKeyboardInset } from "./policy";
-
-/** Preserve the translated inverted list's far-end scroll range only after motion settles. */
-export function useKeyboardStreamInset() {
-  const settledShift = useSettledKeyboardShift();
-  return useMemo(
-    () =>
-      resolveStreamKeyboardInset({
-        platform: Platform.OS === "ios" ? "ios" : "android",
-        settledShift,
-      }),
-    [settledShift],
-  );
-}
diff --git a/packages/app/src/tool-calls/detail-level/overview/view.tsx b/packages/app/src/tool-calls/detail-level/overview/view.tsx
index b11e82e4f7..b05fbe1edd 100644
--- a/packages/app/src/tool-calls/detail-level/overview/view.tsx
+++ b/packages/app/src/tool-calls/detail-level/overview/view.tsx
@@ -2,6 +2,7 @@ import React, { memo, useCallback, useRef, type ReactNode } from "react";
 import { ScrollView } from "react-native";
 import { Wrench } from "lucide-react-native";
 import { StyleSheet } from "react-native-unistyles";
+import { useDisclosureHold } from "@/agent-stream/disclosure";
 import { IndentRail } from "@/components/indent-rail";
 import { ExpandableBadge } from "@/components/message";
 import { useIsCompactFormFactor } from "@/constants/layout";
@@ -32,9 +33,13 @@ export const OverviewToolCallGroupView = memo(function OverviewToolCallGroupView
   const scrollToLatest = useCallback(() => {
     scrollRef.current?.scrollToEnd({ animated: false });
   }, []);
+  const hold = useDisclosureHold();
   const toggle = useCallback(() => {
-    onExpandedChange(group.run.id, !expanded);
-  }, [expanded, group.run.id, onExpandedChange]);
+    const apply = () => onExpandedChange(group.run.id, !expanded);
+    // Compact opens a sheet; nothing in the timeline moves.
+    if (isCompact) apply();
+    else hold(apply);
+  }, [expanded, group.run.id, hold, isCompact, onExpandedChange]);
   const close = useCallback(() => {
     onExpandedChange(group.run.id, false);
   }, [group.run.id, onExpandedChange]);
diff --git a/packages/app/test-stubs/lucide-react-native.ts b/packages/app/test-stubs/lucide-react-native.ts
index a85976e1bf..e07f0b05e7 100644
--- a/packages/app/test-stubs/lucide-react-native.ts
+++ b/packages/app/test-stubs/lucide-react-native.ts
@@ -11,6 +11,7 @@ const StubIcon: LucideIcon = () => null;
 export const Activity = StubIcon;
 export const AlertTriangle = StubIcon;
 export const Archive = StubIcon;
+export const ArrowDown = StubIcon;
 export const ArrowDownUp = StubIcon;
 export const ArrowLeft = StubIcon;
 export const ArrowLeftToLine = StubIcon;
diff --git a/packages/app/vitest.config.ts b/packages/app/vitest.config.ts
index f63a3b73c5..69360fa7ee 100644
--- a/packages/app/vitest.config.ts
+++ b/packages/app/vitest.config.ts
@@ -39,10 +39,12 @@ export default defineConfig({
       name: "compile-react-components",
       enforce: "pre",
       transform(source, id) {
-        // Exercise compiler-sensitive labels and overlay lifetime in the same form as Expo.
+        // Exercise compiler-sensitive labels, overlay lifetime and timeline row revisions in the same
+        // form as Expo.
         const usageComponent = id.includes("/src/usage/") && id.endsWith(".tsx");
         const overlayLayer = id.endsWith("/src/lib/overlay-root.ts");
-        if ((!usageComponent && !overlayLayer) || id.includes(".test.")) return;
+        const streamRow = id.endsWith("/src/agent-stream/stream-row.tsx");
+        if ((!usageComponent && !overlayLayer && !streamRow) || id.includes(".test.")) return;
         const result = transformSync(source, {
           filename: id,
           babelrc: false,
@@ -95,6 +97,17 @@ export default defineConfig({
       },
       {
         extends: true,
+        resolve: {
+          alias: [
+            // The app renders LegendList on native only, from the patched native build. Browser
+            // tests render that build too, instead of the package's separate web build. Unit tests
+            // load it outside Vite, where its react-native import would miss the web alias.
+            {
+              find: /^@legendapp\/list\/react-native$/,
+              replacement: path.resolve(rootNodeModules, "@legendapp/list/react-native.mjs"),
+            },
+          ],
+        },
         test: {
           name: "browser",
           fileParallelism: false,
@@ -165,6 +178,8 @@ export default defineConfig({
       "expo-router/react-navigation",
       "@testing-library/react",
       "@tanstack/react-query",
+      "@tanstack/react-virtual",
+      "@legendapp/list/react-native",
       "react-i18next",
       "i18next",
       "@marijn/find-cluster-break",
diff --git a/patches/@legendapp+list+3.7.1.patch b/patches/@legendapp+list+3.7.1.patch
new file mode 100644
index 0000000000..3a59c09550
--- /dev/null
+++ b/patches/@legendapp+list+3.7.1.patch
@@ -0,0 +1,548 @@
+# LegendList 3.7.1 for the native chat timeline (docs/agent-stream-disclosure.md).
+# Upstream: https://github.com/LegendApp/legend-list/issues/593 covers every change below.
+# react-native.js and react-native.mjs carry the same hunks; each has a "Paseo patch" comment.
+#
+# 1. getEstimatedItemSize (react-native.d.ts, getItemSize, LegendListInner props): a per-item
+#    estimate for an unmeasured row wins over the running average for its type.
+# 2. MVCP anchor lock on native (canRestoreAnchorLock, resolveAnchorLock, updateAnchorLock,
+#    prepareMVCP): upstream enables it on web only. On native the lock ends when its row leaves
+#    the view or shouldRestorePosition rejects it, instead of after 300 ms.
+# 3. Preserved initial end only with maintainScrollAtEnd (finishScrollTo,
+#    finishBootstrapInitialScrollWithoutScroll): otherwise every data change re-arms the initial
+#    scroll to the end.
+# 4. Silent initial scroll retry in one task (checkFinishedScrollFallback): the nudge and the return
+#    to the target go out together, so Android does not reveal 1 dp short of the end.
+# 5. Layout noise against the floored known size (isNativeLayoutNoise, updateOneItemSize): a
+#    one-pixel snap change is not a resize.
+# 6. Content height from React state on the New Architecture (useContentSize, ContainersLayer):
+#    the Animated height mounts the estimated layout for a frame.
+# 7. Header and footer revealed with the rows (RevealedLayoutView, ListComponent).
+# 8. Top-padding shrink hold on iOS only (setPaddingTop): Android paints the held height as blank
+#    space at the end.
+# 9. Rows cut off at the top count as in view (getIdsInVisibleRange): they follow the fully
+#    visible rows in idsInView, so a disclosure hold on a row whose top is above the viewport
+#    still anchors on that row instead of the row below it.
+# 10. A size change keeps only a row shouldRestorePosition accepts in place (prepareMVCP), as a
+#    data change already does, so a disclosure that only grows (a todo card) holds the cut-off
+#    row instead of the first row in view.
+#
+# Upgrading: drop each hunk whose fix the new version ships, regenerate with
+# `npx patch-package @legendapp/list`, and copy this header back on top.
+diff --git a/node_modules/@legendapp/list/react-native.d.ts b/node_modules/@legendapp/list/react-native.d.ts
+index 983e937..970ba51 100644
+--- a/node_modules/@legendapp/list/react-native.d.ts
++++ b/node_modules/@legendapp/list/react-native.d.ts
+@@ -204,6 +204,11 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
+      * Change extraData when the fixed sizes returned by this callback change.
+      */
+     getFixedItemSize?: (item: ItemT, index: number, type: TItemType) => number | undefined;
++    /**
++     * Paseo patch: estimated size of an item that has not been measured yet. Return undefined to
++     * fall back to the average size for its type.
++     */
++    getEstimatedItemSize?: (item: ItemT, index: number, type: TItemType) => number | undefined;
+     /**
+      * Returns a stable item type used for pooling and size estimation.
+      */
+diff --git a/node_modules/@legendapp/list/react-native.js b/node_modules/@legendapp/list/react-native.js
+index eeb3fb0..b1689ad 100644
+--- a/node_modules/@legendapp/list/react-native.js
++++ b/node_modules/@legendapp/list/react-native.js
+@@ -1497,7 +1497,15 @@ function getItemSize(ctx, key, index, data, useAverageSize, preferCachedSize, no
+     return renderedSize;
+   }
+   const itemType = (_b = resolved == null ? void 0 : resolved.itemType) != null ? _b : getItemType ? (_a3 = getItemType(data, index)) != null ? _a3 : "" : "";
+-  if (useAverageSize && !scrollingTo) {
++  // Paseo patch: a caller estimate for an unmeasured item wins over the running average for its
++  // type, so a row new to the list can be laid out near its real size before it is measured.
++  if (state.props.getEstimatedItemSize) {
++    const estimate = state.props.getEstimatedItemSize(data, index, itemType);
++    if (estimate !== void 0) {
++      size = estimate + ctx.scrollAxisGap;
++    }
++  }
++  if (size === void 0 && useAverageSize && !scrollingTo) {
+     const averageSizeForType = (_c = averageSizes[itemType]) == null ? void 0 : _c.avg;
+     if (averageSizeForType !== void 0) {
+       size = roundSize(averageSizeForType);
+@@ -1570,6 +1578,12 @@ var MVCP_POSITION_EPSILON = 0.1;
+ var MVCP_ANCHOR_LOCK_TTL_MS = 300;
+ var MVCP_ANCHOR_LOCK_QUIET_PASSES_TO_RELEASE = 2;
+ var NATIVE_END_CLAMP_EPSILON = 1;
++function canRestoreAnchorLock(state, id) {
++  const shouldRestorePosition = state.props.maintainVisibleContentPosition.shouldRestorePosition;
++  const index = state.indexByKey.get(id);
++  const data = state.props.data;
++  return !shouldRestorePosition || index !== void 0 && data[index] !== void 0 && shouldRestorePosition(data[index], index, data);
++}
+ function resolveAnchorLock(state, enableMVCPAnchorLock, mvcpData, now) {
+   if (!enableMVCPAnchorLock) {
+     state.mvcpAnchorLock = void 0;
+@@ -1579,7 +1593,13 @@ function resolveAnchorLock(state, enableMVCPAnchorLock, mvcpData, now) {
+   if (!lock) {
+     return void 0;
+   }
+-  const isExpired = now > lock.expiresAt;
++  // Paseo patch: native keeps the anchor of a data change through the size passes that follow, as
++  // web does. Upstream limits the lock to web (d24a9d93 "feat: (web) add MVCP anchor lock") without a
++  // native reason. Without it, the pass that applies the measured sizes of prepended rows re-anchors
++  // on the first row in view, which can be one of those rows, and its growth moves the rows below.
++  // A wall-clock expiry is wrong on native, where the measurements arrive after the native mount
++  // and a slow render; the lock ends when its row leaves the view or may not be restored instead.
++  const isExpired = Platform.OS === "web" ? now > lock.expiresAt : !state.idsInView.includes(lock.id) || !canRestoreAnchorLock(state, lock.id);
+   const isMissing = state.indexByKey.get(lock.id) === void 0;
+   if (isExpired || isMissing || !mvcpData) {
+     state.mvcpAnchorLock = void 0;
+@@ -1588,7 +1608,7 @@ function resolveAnchorLock(state, enableMVCPAnchorLock, mvcpData, now) {
+   return lock;
+ }
+ function updateAnchorLock(state, params) {
+-  if (Platform.OS === "web") {
++  {
+     const { anchorId, anchorPosition, dataChanged, now, positionDiff } = params;
+     const enableMVCPAnchorLock = !!dataChanged || !!state.mvcpAnchorLock;
+     const mvcpData = state.props.maintainVisibleContentPosition.data;
+@@ -1713,7 +1733,7 @@ function prepareMVCP(ctx, dataChanged, adjustmentSource) {
+   } = props;
+   const isWeb = Platform.OS === "web";
+   const now = Date.now();
+-  const enableMVCPAnchorLock = isWeb && (!!dataChanged || !!state.mvcpAnchorLock);
++  const enableMVCPAnchorLock = !!dataChanged || !!state.mvcpAnchorLock;
+   const scrollingTo = state.scrollingTo;
+   if ((scrollingTo == null ? void 0 : scrollingTo.key) !== void 0) {
+     const nextIndex = state.indexByKey.get(scrollingTo.key);
+@@ -1723,7 +1743,7 @@ function prepareMVCP(ctx, dataChanged, adjustmentSource) {
+     state.mvcpAnchorLock = void 0;
+     return void 0;
+   }
+-  const anchorLock = isWeb ? resolveAnchorLock(state, enableMVCPAnchorLock, mvcpData, now) : void 0;
++  const anchorLock = resolveAnchorLock(state, enableMVCPAnchorLock, mvcpData, now);
+   let prevPosition;
+   let targetId;
+   const idsInViewWithPositions = [];
+@@ -1755,7 +1775,10 @@ function prepareMVCP(ctx, dataChanged, adjustmentSource) {
+       }
+       targetId = (_b = scrollingTo == null ? void 0 : scrollingTo.key) != null ? _b : getId(state, scrollTarget);
+     } else if (idsInView.length > 0 && state.didContainersLayout && !dataChanged) {
+-      targetId = idsInView.find((id) => indexByKey.get(id) !== void 0);
++      // Paseo patch: a size change keeps only a row shouldRestorePosition accepts in place, as a data
++      // change does. Upstream keeps the first row in view, so a disclosure hold on a row cut off at
++      // the top kept the row below it instead and moved the trigger by the row's size change.
++      targetId = idsInView.find((id) => indexByKey.get(id) !== void 0 && canRestoreAnchorLock(state, id));
+     }
+     if (dataChanged && idsInView.length > 0 && state.didContainersLayout) {
+       for (let i = 0; i < idsInView.length; i++) {
+@@ -2371,7 +2394,10 @@ function finishScrollTo(ctx) {
+     };
+     if (scrollingTo.isInitialScroll || state.initialScroll) {
+       const isOffsetSession = ((_b = state.initialScrollSession) == null ? void 0 : _b.kind) === "offset";
+-      const shouldPreserveResizeTarget = !!scrollingTo.isInitialScroll && !state.clearPreservedInitialScrollOnNextFinish && state.props.data.length > 0 && ((_c = state.initialScroll) == null ? void 0 : _c.viewPosition) === 1;
++      // Paseo patch: only a list that keeps its end keeps landing on the initial end after the
++      // initial scroll. Without maintainScrollAtEnd, the preserved target re-arms the initial scroll
++      // on every data change, footer layout and viewport resize, and a stream never lets it clear.
++      const shouldPreserveResizeTarget = !!state.props.maintainScrollAtEnd && !!scrollingTo.isInitialScroll && !state.clearPreservedInitialScrollOnNextFinish && state.props.data.length > 0 && ((_c = state.initialScroll) == null ? void 0 : _c.viewPosition) === 1;
+       finishInitialScroll(ctx, {
+         onFinished: complete,
+         preserveTarget: isOffsetSession && state.props.data.length === 0 || shouldPreserveResizeTarget,
+@@ -2515,11 +2541,12 @@ function checkFinishedScrollFallback(ctx) {
+         const targetOffset = (_d = (_c = (_b = initialScrollWatchdog.get(state)) == null ? void 0 : _b.targetOffset) != null ? _c : isStillScrollingTo.targetOffset) != null ? _d : 0;
+         const jiggleOffset = targetOffset >= SILENT_INITIAL_SCROLL_TARGET_EPSILON ? targetOffset - SILENT_INITIAL_SCROLL_TARGET_EPSILON : targetOffset + SILENT_INITIAL_SCROLL_TARGET_EPSILON;
+         initialScrollCompletion.markSilentInitialScrollRetry(state);
++        // Paseo patch: send the nudge and the return to the target in one task, so native applies both before
++        // it draws and the pair still emits the scroll event this retry exists for. Upstream returns on the next
++        // frame, but the 16 ms check below can run first, finish the scroll and cancel that frame; the list then
++        // revealed 1 dp short of its end and moved into place a frame later.
+         scrollToFallbackOffset(ctx, jiggleOffset);
+-        state.scheduledWork.frame(
+-          () => scrollToFallbackOffset(ctx, targetOffset),
+-          "checkFinishedScrollRetryFrame"
+-        );
++        scrollToFallbackOffset(ctx, targetOffset);
+         scheduleFallbackCheck(SILENT_INITIAL_SCROLL_RETRY_DELAY_MS);
+       } else if (shouldRetryUnalignedEndScroll) {
+         scrollToFallbackOffset(ctx, completionState.clampedTargetOffset, !!isStillScrollingTo.animated);
+@@ -3378,7 +3405,8 @@ function finishBootstrapInitialScrollWithoutScroll(ctx, resolvedOffset) {
+   var _a3;
+   const state = ctx.state;
+   clearBootstrapInitialScrollSession(state);
+-  const shouldPreserveResizeTarget = !state.clearPreservedInitialScrollOnNextFinish && state.props.data.length > 0 && ((_a3 = state.initialScroll) == null ? void 0 : _a3.viewPosition) === 1;
++  // Paseo patch: see finishScrollTo; only a list that keeps its end preserves the initial end.
++  const shouldPreserveResizeTarget = !!state.props.maintainScrollAtEnd && !state.clearPreservedInitialScrollOnNextFinish && state.props.data.length > 0 && ((_a3 = state.initialScroll) == null ? void 0 : _a3.viewPosition) === 1;
+   finishInitialScroll(ctx, {
+     preserveTarget: shouldPreserveResizeTarget,
+     recalculateItems: true,
+@@ -4569,6 +4597,17 @@ function getIdsInVisibleRange(state, range) {
+       const id = (_b = state.idCache[i]) != null ? _b : getId(state, i);
+       idsInView.push(id);
+     }
++    // Paseo patch: a row whose top is above the viewport is still in view. Upstream starts the ids at
++    // the first fully visible row, so a disclosure hold on a row cut off at the top finds no anchor
++    // (shouldRestorePosition rejects every other row) and the next size pass keeps the row below it
++    // in place instead. The partly visible rows go last, so the first fully visible row stays the
++    // anchor of every pass that does not restrict it.
++    if (range.startNoBuffer !== null && range.startNoBuffer < firstVisibleAnchorIndex) {
++      for (let i = range.startNoBuffer; i < firstVisibleAnchorIndex; i++) {
++        const id = (_b = state.idCache[i]) != null ? _b : getId(state, i);
++        idsInView.push(id);
++      }
++    }
+   }
+   return idsInView;
+ }
+@@ -5176,8 +5215,13 @@ var NATIVE_LAYOUT_MEASUREMENT_EPSILON = 1 / PixelRatio.get() + FLOATING_POINT_SL
+ function isWithinEpsilon(delta) {
+   return Math.abs(delta) <= NATIVE_LAYOUT_MEASUREMENT_EPSILON;
+ }
+-function isNativeLayoutNoise(delta) {
+-  return isWithinEpsilon(delta);
++// Paseo patch: sizesKnown holds roundSize values, floored to 1/8 dp, so the raw size behind a known
++// size lies in [known, known + 1/8). Upstream compares the raw size with the floored one, so a row
++// whose pixel-snapped height changes by one pixel, plus the floor, reads as a resize. On a cold open
++// that late resize moved every row a frame after the reveal.
++function isNativeLayoutNoise(rawSize, knownSize) {
++  const delta = rawSize - knownSize;
++  return delta >= -NATIVE_LAYOUT_MEASUREMENT_EPSILON && delta < NATIVE_LAYOUT_MEASUREMENT_EPSILON + 1 / 8;
+ }
+ 
+ // src/core/updateItemSizes.ts
+@@ -5414,7 +5458,7 @@ function updateOneItemSize(ctx, itemKey, sizeObj, resolvedMeasurementItem, notif
+     state.fixedItemSizeKeys.add(itemKey);
+   }
+   const prevSizeKnown = sizesKnown.get(itemKey);
+-  if (Platform.OS !== "web" && prevSizeKnown !== void 0 && isNativeLayoutNoise(rawSize - prevSizeKnown)) {
++  if (Platform.OS !== "web" && prevSizeKnown !== void 0 && isNativeLayoutNoise(rawSize, prevSizeKnown)) {
+     return 0;
+   }
+   const size = Platform.OS === "web" ? Math.round(rawSize) : roundSize(rawSize);
+@@ -6283,6 +6327,10 @@ function useFreshDataTransitionVisibility(readyToRender, transitionEpoch) {
+ 
+ // src/components/Containers.native.tsx
+ var useCommittedMinSize = IsNewArchitecture ? () => useArr$(["totalSize"])[0] : () => void 0;
++// Paseo patch: on the new architecture the content height comes from React state only. The
++// JS-driven Animated height writes through setNativeProps, which Fabric commits synchronously
++// mid-task, mounting React's estimated layout for a frame before the measured one.
++var useContentSize = IsNewArchitecture ? useCommittedMinSize : () => useValue$("totalSize");
+ var ContainersLayer = typedMemo(function ContainersLayer2({
+   children,
+   freshDataTransitionEpoch,
+@@ -6290,7 +6338,7 @@ var ContainersLayer = typedMemo(function ContainersLayer2({
+ }) {
+   const ctx = useStateContext();
+   const columnWrapperStyle = ctx.columnWrapperStyle;
+-  const size = useValue$("totalSize");
++  const size = useContentSize();
+   const minSize = useCommittedMinSize();
+   const [readyToRender, numColumns, otherAxisSize = 0] = useArr$(["readyToRender", "numColumns", "otherAxisSize"]);
+   const isVisible = useFreshDataTransitionVisibility(!!readyToRender, freshDataTransitionEpoch);
+@@ -6513,6 +6561,14 @@ var AlignItemsAtEndSpacer = typedMemo(function AlignItemsAtEndSpacer2({ horizont
+     null
+   );
+ });
++// Paseo patch: the header and footer reveal with the rows. Upstream hides only the containers until
++// readyToRender, so a cold open paints the header and footer at their estimated place a frame or more
++// before the rows appear around them.
++var RevealedLayoutView = function RevealedLayoutView2({ freshDataTransitionEpoch, style, ...rest }) {
++  const [readyToRender] = useArr$(["readyToRender"]);
++  const isVisible = useFreshDataTransitionVisibility(!!readyToRender, freshDataTransitionEpoch);
++  return /* @__PURE__ */ React2__namespace.createElement(LayoutView, { ...rest, pointerEvents: isVisible ? "auto" : "none", style: isVisible ? style : [style, { opacity: 0 }] });
++};
+ var ListComponent = typedMemo(function ListComponent2({
+   canRender,
+   freshDataTransitionEpoch,
+@@ -6651,7 +6707,7 @@ var ListComponent = typedMemo(function ListComponent2({
+       style: autoOtherAxisStyle ? [autoOtherAxisStyle, style] : style
+     },
+     /* @__PURE__ */ React2__namespace.createElement(ScrollAdjust, null),
+-    ListHeaderComponent && /* @__PURE__ */ React2__namespace.createElement(LayoutView, { onLayoutChange: onLayoutHeader, style: ListHeaderComponentStyle }, getComponent(ListHeaderComponent)),
++    ListHeaderComponent && /* @__PURE__ */ React2__namespace.createElement(RevealedLayoutView, { freshDataTransitionEpoch, onLayoutChange: onLayoutHeader, style: ListHeaderComponentStyle }, getComponent(ListHeaderComponent)),
+     ListEmptyComponent && getComponent(ListEmptyComponent),
+     shouldRenderAlignItemsAtEndSpacer && /* @__PURE__ */ React2__namespace.createElement(AlignItemsAtEndSpacer, { horizontal }),
+     canRender && !ListEmptyComponent && /* @__PURE__ */ React2__namespace.createElement(
+@@ -6665,7 +6721,7 @@ var ListComponent = typedMemo(function ListComponent2({
+         stickyHeaderConfig
+       }
+     ),
+-    ListFooterComponent && /* @__PURE__ */ React2__namespace.createElement(LayoutView, { onLayoutChange: onLayoutFooterInternal, style: ListFooterComponentStyle }, getComponent(ListFooterComponent)),
++    ListFooterComponent && /* @__PURE__ */ React2__namespace.createElement(RevealedLayoutView, { freshDataTransitionEpoch, onLayoutChange: onLayoutFooterInternal, style: ListFooterComponentStyle }, getComponent(ListFooterComponent)),
+     IS_DEV && ENABLE_DEVMODE
+   );
+ });
+@@ -7886,7 +7942,10 @@ function setPaddingTop(ctx, { stylePaddingTop }) {
+   const state = ctx.state;
+   if (stylePaddingTop !== void 0) {
+     const prevStylePaddingTop = peek$(ctx, "stylePaddingTop") || 0;
+-    if (stylePaddingTop < prevStylePaddingTop) {
++    // Paseo patch: only iOS compensates a shrinking top padding with a scroll adjust, which this
++    // keeps the native clamp from doubling. Elsewhere the held height paints as blank space at the
++    // end until the timer fires, and a scroll view that keeps its end scrolls into it.
++    if (stylePaddingTop < prevStylePaddingTop && Platform.OS === "ios") {
+       let prevTotalSize = peek$(ctx, "totalSize") || 0;
+       set$(ctx, "totalSize", prevTotalSize + prevStylePaddingTop);
+       state.timeoutSetPaddingTop = setTimeout(() => {
+@@ -7989,6 +8048,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
+     estimatedListSize,
+     extraData,
+     getFixedItemSize,
++    getEstimatedItemSize,
+     getItemType,
+     horizontal,
+     rtl,
+@@ -8282,6 +8342,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
+     dataVersion,
+     drawDistance,
+     estimatedItemSize,
++    getEstimatedItemSize: useWrapIfItem(getEstimatedItemSize),
+     getFixedItemSize: useWrapIfItem(getFixedItemSize),
+     getItemType: useWrapIfItem(getItemType),
+     hasExternalScroll,
+diff --git a/node_modules/@legendapp/list/react-native.mjs b/node_modules/@legendapp/list/react-native.mjs
+index fe5f415..e61945e 100644
+--- a/node_modules/@legendapp/list/react-native.mjs
++++ b/node_modules/@legendapp/list/react-native.mjs
+@@ -1476,7 +1476,15 @@ function getItemSize(ctx, key, index, data, useAverageSize, preferCachedSize, no
+     return renderedSize;
+   }
+   const itemType = (_b = resolved == null ? void 0 : resolved.itemType) != null ? _b : getItemType ? (_a3 = getItemType(data, index)) != null ? _a3 : "" : "";
+-  if (useAverageSize && !scrollingTo) {
++  // Paseo patch: a caller estimate for an unmeasured item wins over the running average for its
++  // type, so a row new to the list can be laid out near its real size before it is measured.
++  if (state.props.getEstimatedItemSize) {
++    const estimate = state.props.getEstimatedItemSize(data, index, itemType);
++    if (estimate !== void 0) {
++      size = estimate + ctx.scrollAxisGap;
++    }
++  }
++  if (size === void 0 && useAverageSize && !scrollingTo) {
+     const averageSizeForType = (_c = averageSizes[itemType]) == null ? void 0 : _c.avg;
+     if (averageSizeForType !== void 0) {
+       size = roundSize(averageSizeForType);
+@@ -1549,6 +1557,12 @@ var MVCP_POSITION_EPSILON = 0.1;
+ var MVCP_ANCHOR_LOCK_TTL_MS = 300;
+ var MVCP_ANCHOR_LOCK_QUIET_PASSES_TO_RELEASE = 2;
+ var NATIVE_END_CLAMP_EPSILON = 1;
++function canRestoreAnchorLock(state, id) {
++  const shouldRestorePosition = state.props.maintainVisibleContentPosition.shouldRestorePosition;
++  const index = state.indexByKey.get(id);
++  const data = state.props.data;
++  return !shouldRestorePosition || index !== void 0 && data[index] !== void 0 && shouldRestorePosition(data[index], index, data);
++}
+ function resolveAnchorLock(state, enableMVCPAnchorLock, mvcpData, now) {
+   if (!enableMVCPAnchorLock) {
+     state.mvcpAnchorLock = void 0;
+@@ -1558,7 +1572,13 @@ function resolveAnchorLock(state, enableMVCPAnchorLock, mvcpData, now) {
+   if (!lock) {
+     return void 0;
+   }
+-  const isExpired = now > lock.expiresAt;
++  // Paseo patch: native keeps the anchor of a data change through the size passes that follow, as
++  // web does. Upstream limits the lock to web (d24a9d93 "feat: (web) add MVCP anchor lock") without a
++  // native reason. Without it, the pass that applies the measured sizes of prepended rows re-anchors
++  // on the first row in view, which can be one of those rows, and its growth moves the rows below.
++  // A wall-clock expiry is wrong on native, where the measurements arrive after the native mount
++  // and a slow render; the lock ends when its row leaves the view or may not be restored instead.
++  const isExpired = Platform.OS === "web" ? now > lock.expiresAt : !state.idsInView.includes(lock.id) || !canRestoreAnchorLock(state, lock.id);
+   const isMissing = state.indexByKey.get(lock.id) === void 0;
+   if (isExpired || isMissing || !mvcpData) {
+     state.mvcpAnchorLock = void 0;
+@@ -1567,7 +1587,7 @@ function resolveAnchorLock(state, enableMVCPAnchorLock, mvcpData, now) {
+   return lock;
+ }
+ function updateAnchorLock(state, params) {
+-  if (Platform.OS === "web") {
++  {
+     const { anchorId, anchorPosition, dataChanged, now, positionDiff } = params;
+     const enableMVCPAnchorLock = !!dataChanged || !!state.mvcpAnchorLock;
+     const mvcpData = state.props.maintainVisibleContentPosition.data;
+@@ -1692,7 +1712,7 @@ function prepareMVCP(ctx, dataChanged, adjustmentSource) {
+   } = props;
+   const isWeb = Platform.OS === "web";
+   const now = Date.now();
+-  const enableMVCPAnchorLock = isWeb && (!!dataChanged || !!state.mvcpAnchorLock);
++  const enableMVCPAnchorLock = !!dataChanged || !!state.mvcpAnchorLock;
+   const scrollingTo = state.scrollingTo;
+   if ((scrollingTo == null ? void 0 : scrollingTo.key) !== void 0) {
+     const nextIndex = state.indexByKey.get(scrollingTo.key);
+@@ -1702,7 +1722,7 @@ function prepareMVCP(ctx, dataChanged, adjustmentSource) {
+     state.mvcpAnchorLock = void 0;
+     return void 0;
+   }
+-  const anchorLock = isWeb ? resolveAnchorLock(state, enableMVCPAnchorLock, mvcpData, now) : void 0;
++  const anchorLock = resolveAnchorLock(state, enableMVCPAnchorLock, mvcpData, now);
+   let prevPosition;
+   let targetId;
+   const idsInViewWithPositions = [];
+@@ -1734,7 +1754,10 @@ function prepareMVCP(ctx, dataChanged, adjustmentSource) {
+       }
+       targetId = (_b = scrollingTo == null ? void 0 : scrollingTo.key) != null ? _b : getId(state, scrollTarget);
+     } else if (idsInView.length > 0 && state.didContainersLayout && !dataChanged) {
+-      targetId = idsInView.find((id) => indexByKey.get(id) !== void 0);
++      // Paseo patch: a size change keeps only a row shouldRestorePosition accepts in place, as a data
++      // change does. Upstream keeps the first row in view, so a disclosure hold on a row cut off at
++      // the top kept the row below it instead and moved the trigger by the row's size change.
++      targetId = idsInView.find((id) => indexByKey.get(id) !== void 0 && canRestoreAnchorLock(state, id));
+     }
+     if (dataChanged && idsInView.length > 0 && state.didContainersLayout) {
+       for (let i = 0; i < idsInView.length; i++) {
+@@ -2350,7 +2373,10 @@ function finishScrollTo(ctx) {
+     };
+     if (scrollingTo.isInitialScroll || state.initialScroll) {
+       const isOffsetSession = ((_b = state.initialScrollSession) == null ? void 0 : _b.kind) === "offset";
+-      const shouldPreserveResizeTarget = !!scrollingTo.isInitialScroll && !state.clearPreservedInitialScrollOnNextFinish && state.props.data.length > 0 && ((_c = state.initialScroll) == null ? void 0 : _c.viewPosition) === 1;
++      // Paseo patch: only a list that keeps its end keeps landing on the initial end after the
++      // initial scroll. Without maintainScrollAtEnd, the preserved target re-arms the initial scroll
++      // on every data change, footer layout and viewport resize, and a stream never lets it clear.
++      const shouldPreserveResizeTarget = !!state.props.maintainScrollAtEnd && !!scrollingTo.isInitialScroll && !state.clearPreservedInitialScrollOnNextFinish && state.props.data.length > 0 && ((_c = state.initialScroll) == null ? void 0 : _c.viewPosition) === 1;
+       finishInitialScroll(ctx, {
+         onFinished: complete,
+         preserveTarget: isOffsetSession && state.props.data.length === 0 || shouldPreserveResizeTarget,
+@@ -2494,11 +2520,12 @@ function checkFinishedScrollFallback(ctx) {
+         const targetOffset = (_d = (_c = (_b = initialScrollWatchdog.get(state)) == null ? void 0 : _b.targetOffset) != null ? _c : isStillScrollingTo.targetOffset) != null ? _d : 0;
+         const jiggleOffset = targetOffset >= SILENT_INITIAL_SCROLL_TARGET_EPSILON ? targetOffset - SILENT_INITIAL_SCROLL_TARGET_EPSILON : targetOffset + SILENT_INITIAL_SCROLL_TARGET_EPSILON;
+         initialScrollCompletion.markSilentInitialScrollRetry(state);
++        // Paseo patch: send the nudge and the return to the target in one task, so native applies both before
++        // it draws and the pair still emits the scroll event this retry exists for. Upstream returns on the next
++        // frame, but the 16 ms check below can run first, finish the scroll and cancel that frame; the list then
++        // revealed 1 dp short of its end and moved into place a frame later.
+         scrollToFallbackOffset(ctx, jiggleOffset);
+-        state.scheduledWork.frame(
+-          () => scrollToFallbackOffset(ctx, targetOffset),
+-          "checkFinishedScrollRetryFrame"
+-        );
++        scrollToFallbackOffset(ctx, targetOffset);
+         scheduleFallbackCheck(SILENT_INITIAL_SCROLL_RETRY_DELAY_MS);
+       } else if (shouldRetryUnalignedEndScroll) {
+         scrollToFallbackOffset(ctx, completionState.clampedTargetOffset, !!isStillScrollingTo.animated);
+@@ -3357,7 +3384,8 @@ function finishBootstrapInitialScrollWithoutScroll(ctx, resolvedOffset) {
+   var _a3;
+   const state = ctx.state;
+   clearBootstrapInitialScrollSession(state);
+-  const shouldPreserveResizeTarget = !state.clearPreservedInitialScrollOnNextFinish && state.props.data.length > 0 && ((_a3 = state.initialScroll) == null ? void 0 : _a3.viewPosition) === 1;
++  // Paseo patch: see finishScrollTo; only a list that keeps its end preserves the initial end.
++  const shouldPreserveResizeTarget = !!state.props.maintainScrollAtEnd && !state.clearPreservedInitialScrollOnNextFinish && state.props.data.length > 0 && ((_a3 = state.initialScroll) == null ? void 0 : _a3.viewPosition) === 1;
+   finishInitialScroll(ctx, {
+     preserveTarget: shouldPreserveResizeTarget,
+     recalculateItems: true,
+@@ -4548,6 +4576,17 @@ function getIdsInVisibleRange(state, range) {
+       const id = (_b = state.idCache[i]) != null ? _b : getId(state, i);
+       idsInView.push(id);
+     }
++    // Paseo patch: a row whose top is above the viewport is still in view. Upstream starts the ids at
++    // the first fully visible row, so a disclosure hold on a row cut off at the top finds no anchor
++    // (shouldRestorePosition rejects every other row) and the next size pass keeps the row below it
++    // in place instead. The partly visible rows go last, so the first fully visible row stays the
++    // anchor of every pass that does not restrict it.
++    if (range.startNoBuffer !== null && range.startNoBuffer < firstVisibleAnchorIndex) {
++      for (let i = range.startNoBuffer; i < firstVisibleAnchorIndex; i++) {
++        const id = (_b = state.idCache[i]) != null ? _b : getId(state, i);
++        idsInView.push(id);
++      }
++    }
+   }
+   return idsInView;
+ }
+@@ -5155,8 +5194,13 @@ var NATIVE_LAYOUT_MEASUREMENT_EPSILON = 1 / PixelRatio.get() + FLOATING_POINT_SL
+ function isWithinEpsilon(delta) {
+   return Math.abs(delta) <= NATIVE_LAYOUT_MEASUREMENT_EPSILON;
+ }
+-function isNativeLayoutNoise(delta) {
+-  return isWithinEpsilon(delta);
++// Paseo patch: sizesKnown holds roundSize values, floored to 1/8 dp, so the raw size behind a known
++// size lies in [known, known + 1/8). Upstream compares the raw size with the floored one, so a row
++// whose pixel-snapped height changes by one pixel, plus the floor, reads as a resize. On a cold open
++// that late resize moved every row a frame after the reveal.
++function isNativeLayoutNoise(rawSize, knownSize) {
++  const delta = rawSize - knownSize;
++  return delta >= -NATIVE_LAYOUT_MEASUREMENT_EPSILON && delta < NATIVE_LAYOUT_MEASUREMENT_EPSILON + 1 / 8;
+ }
+ 
+ // src/core/updateItemSizes.ts
+@@ -5393,7 +5437,7 @@ function updateOneItemSize(ctx, itemKey, sizeObj, resolvedMeasurementItem, notif
+     state.fixedItemSizeKeys.add(itemKey);
+   }
+   const prevSizeKnown = sizesKnown.get(itemKey);
+-  if (Platform.OS !== "web" && prevSizeKnown !== void 0 && isNativeLayoutNoise(rawSize - prevSizeKnown)) {
++  if (Platform.OS !== "web" && prevSizeKnown !== void 0 && isNativeLayoutNoise(rawSize, prevSizeKnown)) {
+     return 0;
+   }
+   const size = Platform.OS === "web" ? Math.round(rawSize) : roundSize(rawSize);
+@@ -6262,6 +6306,10 @@ function useFreshDataTransitionVisibility(readyToRender, transitionEpoch) {
+ 
+ // src/components/Containers.native.tsx
+ var useCommittedMinSize = IsNewArchitecture ? () => useArr$(["totalSize"])[0] : () => void 0;
++// Paseo patch: on the new architecture the content height comes from React state only. The
++// JS-driven Animated height writes through setNativeProps, which Fabric commits synchronously
++// mid-task, mounting React's estimated layout for a frame before the measured one.
++var useContentSize = IsNewArchitecture ? useCommittedMinSize : () => useValue$("totalSize");
+ var ContainersLayer = typedMemo(function ContainersLayer2({
+   children,
+   freshDataTransitionEpoch,
+@@ -6269,7 +6317,7 @@ var ContainersLayer = typedMemo(function ContainersLayer2({
+ }) {
+   const ctx = useStateContext();
+   const columnWrapperStyle = ctx.columnWrapperStyle;
+-  const size = useValue$("totalSize");
++  const size = useContentSize();
+   const minSize = useCommittedMinSize();
+   const [readyToRender, numColumns, otherAxisSize = 0] = useArr$(["readyToRender", "numColumns", "otherAxisSize"]);
+   const isVisible = useFreshDataTransitionVisibility(!!readyToRender, freshDataTransitionEpoch);
+@@ -6492,6 +6540,14 @@ var AlignItemsAtEndSpacer = typedMemo(function AlignItemsAtEndSpacer2({ horizont
+     null
+   );
+ });
++// Paseo patch: the header and footer reveal with the rows. Upstream hides only the containers until
++// readyToRender, so a cold open paints the header and footer at their estimated place a frame or more
++// before the rows appear around them.
++var RevealedLayoutView = function RevealedLayoutView2({ freshDataTransitionEpoch, style, ...rest }) {
++  const [readyToRender] = useArr$(["readyToRender"]);
++  const isVisible = useFreshDataTransitionVisibility(!!readyToRender, freshDataTransitionEpoch);
++  return /* @__PURE__ */ React2.createElement(LayoutView, { ...rest, pointerEvents: isVisible ? "auto" : "none", style: isVisible ? style : [style, { opacity: 0 }] });
++};
+ var ListComponent = typedMemo(function ListComponent2({
+   canRender,
+   freshDataTransitionEpoch,
+@@ -6630,7 +6686,7 @@ var ListComponent = typedMemo(function ListComponent2({
+       style: autoOtherAxisStyle ? [autoOtherAxisStyle, style] : style
+     },
+     /* @__PURE__ */ React2.createElement(ScrollAdjust, null),
+-    ListHeaderComponent && /* @__PURE__ */ React2.createElement(LayoutView, { onLayoutChange: onLayoutHeader, style: ListHeaderComponentStyle }, getComponent(ListHeaderComponent)),
++    ListHeaderComponent && /* @__PURE__ */ React2.createElement(RevealedLayoutView, { freshDataTransitionEpoch, onLayoutChange: onLayoutHeader, style: ListHeaderComponentStyle }, getComponent(ListHeaderComponent)),
+     ListEmptyComponent && getComponent(ListEmptyComponent),
+     shouldRenderAlignItemsAtEndSpacer && /* @__PURE__ */ React2.createElement(AlignItemsAtEndSpacer, { horizontal }),
+     canRender && !ListEmptyComponent && /* @__PURE__ */ React2.createElement(
+@@ -6644,7 +6700,7 @@ var ListComponent = typedMemo(function ListComponent2({
+         stickyHeaderConfig
+       }
+     ),
+-    ListFooterComponent && /* @__PURE__ */ React2.createElement(LayoutView, { onLayoutChange: onLayoutFooterInternal, style: ListFooterComponentStyle }, getComponent(ListFooterComponent)),
++    ListFooterComponent && /* @__PURE__ */ React2.createElement(RevealedLayoutView, { freshDataTransitionEpoch, onLayoutChange: onLayoutFooterInternal, style: ListFooterComponentStyle }, getComponent(ListFooterComponent)),
+     IS_DEV && ENABLE_DEVMODE
+   );
+ });
+@@ -7865,7 +7921,10 @@ function setPaddingTop(ctx, { stylePaddingTop }) {
+   const state = ctx.state;
+   if (stylePaddingTop !== void 0) {
+     const prevStylePaddingTop = peek$(ctx, "stylePaddingTop") || 0;
+-    if (stylePaddingTop < prevStylePaddingTop) {
++    // Paseo patch: only iOS compensates a shrinking top padding with a scroll adjust, which this
++    // keeps the native clamp from doubling. Elsewhere the held height paints as blank space at the
++    // end until the timer fires, and a scroll view that keeps its end scrolls into it.
++    if (stylePaddingTop < prevStylePaddingTop && Platform.OS === "ios") {
+       let prevTotalSize = peek$(ctx, "totalSize") || 0;
+       set$(ctx, "totalSize", prevTotalSize + prevStylePaddingTop);
+       state.timeoutSetPaddingTop = setTimeout(() => {
+@@ -7968,6 +8027,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
+     estimatedListSize,
+     extraData,
+     getFixedItemSize,
++    getEstimatedItemSize,
+     getItemType,
+     horizontal,
+     rtl,
+@@ -8261,6 +8321,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
+     dataVersion,
+     drawDistance,
+     estimatedItemSize,
++    getEstimatedItemSize: useWrapIfItem(getEstimatedItemSize),
+     getFixedItemSize: useWrapIfItem(getFixedItemSize),
+     getItemType: useWrapIfItem(getItemType),
+     hasExternalScroll,
diff --git a/scripts/postinstall-patches.mjs b/scripts/postinstall-patches.mjs
index 3dbbeddcaf..0f4b96b19f 100644
--- a/scripts/postinstall-patches.mjs
+++ b/scripts/postinstall-patches.mjs
@@ -43,6 +43,11 @@ const patchedPackages = [
     nodeModulesPath: "node_modules/react-native-reanimated",
     patchPrefix: "react-native-reanimated+",
   },
+  // The native chat timeline. The patch's header lists its hunks and the upstream issue.
+  {
+    nodeModulesPath: "node_modules/@legendapp/list",
+    patchPrefix: "@legendapp+list+",
+  },
   {
     nodeModulesPath: "node_modules/react-native-draggable-flatlist",
     patchPrefix: "react-native-draggable-flatlist+",

From 4407283a134502bf4a7704bfa823fcfed7f702b0 Mon Sep 17 00:00:00 2001
From: "paseo-ai[bot]" <266920839+paseo-ai[bot]@users.noreply.github.com>
Date: Wed, 4 Nov 2026 10:31:18 +0000
Subject: [PATCH 05/29] fix: update lockfile signatures and Nix hash [skip ci]

---
 nix/npm-deps.hash | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/nix/npm-deps.hash b/nix/npm-deps.hash
index 319e7426ce..edbcfe2f64 100644
--- a/nix/npm-deps.hash
+++ b/nix/npm-deps.hash
@@ -1 +1 @@
-sha256-p97CaALgkY+x9XVvS4/ILqmbwYSX0fSbVUgQl35BjiU=
+sha256-sLaLHD1u1eJRdGdflcwWBGxnnhRQpB1T74BlaWcmxbU=

From cab5eedfe3be11d358fb0ea97834e76f0b27f5e2 Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Wed, 4 Nov 2026 18:23:41 +0700
Subject: [PATCH 06/29] Keep workspace layouts usable in narrow columns across
 platforms (#8740)

* fix(app): retain Explorer resize width until acknowledged

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): choose workspace header by measured column width

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): separate iOS composer clipping from its shadow

Keep explicit coverage of the existing keyboard rotation guard.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): choose workspace chrome within each desktop pane

The outer width wrapper added a compact header while the desktop split container kept its full header and pane rails. Each pane now owns the complete choice, replacing its header and rail together.

Each split pane uses its own measured width: below 500 points it shows its own tab dropdown, even if the neighboring pane is wide. Pane width determines usable header space. Keep new-tab keyboard ownership outside the switched chrome and retain positive measurements while hidden.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): reserve readable width for the compact tab popover

Native scroll content does not contribute intrinsic width to the anchored frame. The count badge alone allowed the popover to compress its tab list and footer labels.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): preserve compact pane actions and window clearance

Carry the owning pane into compact launch actions, keep split and restore controls in its menu, and distribute window corners through visible split children. Keep tab rails below header-owned window controls.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): retain window dragging in compact panes

Keep the shared titlebar drag region when pane width replaces full desktop chrome. Cover two compact panes with both sidebars closed through the desktop host adapter.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* test(app): align pane journeys with measured workspace chrome

Give rail-specific split journeys enough column width, assert launched Diff content independently of header shape, and retain pane identity across compact transitions. Expect the compact selector in the half-screen Explorer workflow.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* refactor(app): share pane tab-switcher rendering after header rebase

Keep compact and vertical-bar header actions on the same pane-aware switcher contract while preserving the merged control geometry and script ownership.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): retain Explorer acknowledgements across consecutive drags

Keep earlier released widths as expected allocations while a newer gesture owns the frame, and restore the latest release if that gesture is canceled.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): keep focus mode exit in the compact workspace menu

Carry the workspace focus state into its compact action menu so a narrow header retains an exit without keyboard shortcuts.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): distinguish resize rollback from pending acknowledgements

Restore the last released width when repeated widths precede a canceled gesture, and retain ownership when an unchanged old allocation matches a newer release before its predecessors arrive.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* test(app): allow software WebGL time to finish atlas growth coverage

The 256-batch pixel regression crosses more than 500 render boundaries and exceeds its 30-second total budget under CPU contention. Keep the corpus, every pixel assertion, and the two-second per-frame deadline; allow 60 seconds for the complete workload. Reproduced the timeout with Chromium confined to one CPU and verified two successful constrained runs after the adjustment.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

---------

Co-authored-by: Elsa Granger <zeyugao@outlook.com>
---
 .../e2e/browser/composer-diff-stat.spec.ts    |   3 +-
 ...t-terminal-shortcut-pane-placement.spec.ts |  88 ++++++
 .../e2e/browser/empty-pane-keyboard.spec.ts   |   6 +-
 .../browser/explorer-pane-placement.spec.ts   |   3 +
 packages/app/e2e/browser/file-editing.spec.ts |   3 +-
 .../app/e2e/browser/sidebar-workspace.spec.ts |   3 +
 .../e2e/browser/subagent-origin-pane.spec.ts  |   6 +-
 .../app/e2e/browser/terminal-find.spec.ts     |   2 +
 .../browser/viewed-agent-timelines.spec.ts    |   2 +
 .../e2e/browser/workspace-focus-mode.spec.ts  |  17 ++
 .../browser/workspace-pane-remount.spec.ts    |   2 +
 .../explorer-sidebar-layout.test.ts           | 197 +++++++++++++
 .../src/components/explorer-sidebar-layout.ts |  79 +++++
 .../app/src/components/split-container.tsx    | 165 ++++++++---
 packages/app/src/composer/input/input.tsx     |  10 +-
 .../keyboard/shift/internal/policy.test.ts    |  15 +
 .../workspace/adaptive-workspace-chrome.tsx   |  38 +++
 .../compact-workspace-header/tab-switcher.tsx |  16 +-
 .../workspace/explorer-sidebar/geometry.tsx   |  87 ++++--
 .../workspace/workspace-desktop-tabs-row.tsx  |  89 ++++--
 .../workspace/workspace-header-menu.tsx       |  46 ++-
 .../screens/workspace/workspace-screen.tsx    | 270 +++++++++++-------
 .../workspace/workspace-tab-layout.test.ts    |  37 +++
 .../screens/workspace/workspace-tab-layout.ts |  19 ++
 .../terminal-glyph-rendering.browser.test.ts  |   4 +-
 packages/app/src/utils/desktop-window.test.ts |  52 ++++
 packages/app/src/utils/desktop-window.tsx     |  13 +
 27 files changed, 1063 insertions(+), 209 deletions(-)
 create mode 100644 packages/app/src/screens/workspace/adaptive-workspace-chrome.tsx

diff --git a/packages/app/e2e/browser/composer-diff-stat.spec.ts b/packages/app/e2e/browser/composer-diff-stat.spec.ts
index 959567f58b..4eeada2f1f 100644
--- a/packages/app/e2e/browser/composer-diff-stat.spec.ts
+++ b/packages/app/e2e/browser/composer-diff-stat.spec.ts
@@ -78,7 +78,8 @@ test("composer diff stat reveals Changes, then opens the diff in the configured
   const workspace = await seedChangedAgent("composer-diff-stat-side-");
 
   try {
-    await page.setViewportSize({ width: 1400, height: 900 });
+    // Keep both workspace rails visible alongside app navigation and Explorer.
+    await page.setViewportSize({ width: 1900, height: 900 });
     await openAgentRoute(page, {
       workspaceId: workspace.workspaceId,
       agentId: workspace.agentId,
diff --git a/packages/app/e2e/browser/direct-terminal-shortcut-pane-placement.spec.ts b/packages/app/e2e/browser/direct-terminal-shortcut-pane-placement.spec.ts
index 0c3787f46d..373459ef4c 100644
--- a/packages/app/e2e/browser/direct-terminal-shortcut-pane-placement.spec.ts
+++ b/packages/app/e2e/browser/direct-terminal-shortcut-pane-placement.spec.ts
@@ -1,3 +1,5 @@
+import { installLocalDesktopHost } from "../support/helpers/local-desktop-host";
+import type { Locator, Page } from "@playwright/test";
 import { expect, test } from "../support/fixtures";
 import { runWorkspaceActionFromCommandCenter } from "../support/helpers/command-center-workspace-actions";
 import {
@@ -9,6 +11,7 @@ import { seedWorkspace } from "../support/helpers/seed-client";
 import { waitForWorkspaceTabsVisible } from "../support/helpers/workspace-tabs";
 
 test.describe("Direct terminal shortcut pane placement", () => {
+  test.use({ viewport: { width: 1600, height: 900 } });
   test("opens a terminal in the focused pane", async ({ page }) => {
     const workspace = await seedWorkspace({ repoPrefix: "direct-terminal-shortcut-pane-" });
 
@@ -47,3 +50,88 @@ test.describe("Direct terminal shortcut pane placement", () => {
     }
   });
 });
+
+async function prepareUnfocusedCompactPane(page: Page, workspaceId: string) {
+  await page.setViewportSize({ width: 1600, height: 900 });
+  await gotoWorkspace(page, workspaceId);
+  await waitForWorkspaceTabsVisible(page);
+  await clickNewChat(page);
+  await runWorkspaceActionFromCommandCenter(page, "Split pane right");
+  const draftPane = page
+    .locator('[data-testid^="workspace-pane-"]')
+    .filter({ has: page.getByTestId("message-input-root") });
+  const emptyPane = page
+    .locator('[data-testid^="workspace-pane-"]')
+    .filter({ has: page.getByTestId("workspace-new-tab-panel") });
+  const draftPaneId = await draftPane.getAttribute("data-testid");
+  const emptyPaneId = await emptyPane.getAttribute("data-testid");
+  expect(draftPaneId).not.toBeNull();
+  expect(emptyPaneId).not.toBeNull();
+  await page.setViewportSize({ width: 760, height: 900 });
+  return {
+    originalPane: page.getByTestId(draftPaneId!),
+    otherPane: page.getByTestId(emptyPaneId!),
+  };
+}
+
+async function launchTerminalFromCompactPane(page: Page, pane: Locator) {
+  await pane.getByTestId("workspace-tab-switcher-trigger").click();
+  await page.getByTestId("workspace-tab-switcher-new-terminal").click();
+  await expect(pane.getByTestId("terminal-surface")).toBeVisible({ timeout: 30_000 });
+}
+
+async function maximizeAndRestoreCompactPane(page: Page, pane: Locator) {
+  await pane.getByTestId("workspace-header-menu-trigger").click();
+  await expect(page.getByRole("menuitem", { name: "Split pane right", exact: true })).toBeVisible();
+  await page.getByRole("menuitem", { name: "Maximize pane", exact: true }).click();
+  await pane.getByTestId("workspace-header-menu-trigger").click();
+  await page.getByRole("menuitem", { name: "Restore pane", exact: true }).click();
+}
+
+test("compact pane launch stays in its owning pane and pane controls remain reachable", async ({
+  page,
+}) => {
+  const workspace = await seedWorkspace({ repoPrefix: "compact-pane-launch-" });
+  try {
+    const { originalPane, otherPane } = await prepareUnfocusedCompactPane(
+      page,
+      workspace.workspaceId,
+    );
+    await launchTerminalFromCompactPane(page, originalPane);
+    await expect(otherPane.getByTestId("workspace-new-tab-panel")).toBeVisible();
+    await maximizeAndRestoreCompactPane(page, originalPane);
+    await expect(otherPane).toBeVisible();
+  } finally {
+    await workspace.cleanup();
+  }
+});
+
+async function expectPaneHasWindowDragSurface(pane: Locator) {
+  await expect
+    .poll(() =>
+      pane.evaluate((element) =>
+        Array.from(element.querySelectorAll<HTMLElement>("div")).some(
+          (node) => node.style.getPropertyValue("-webkit-app-region") === "drag",
+        ),
+      ),
+    )
+    .toBe(true);
+}
+
+test("compact desktop panes retain window dragging with both sidebars closed", async ({ page }) => {
+  const workspace = await seedWorkspace({ repoPrefix: "compact-pane-window-drag-" });
+  try {
+    await installLocalDesktopHost(page, workspace.repoPath);
+    const { originalPane, otherPane } = await prepareUnfocusedCompactPane(
+      page,
+      workspace.workspaceId,
+    );
+    await runWorkspaceActionFromCommandCenter(page, "Toggle left sidebar");
+    await expect(originalPane.getByTestId("workspace-tab-switcher-trigger")).toBeVisible();
+    await expect(otherPane.getByTestId("workspace-tab-switcher-trigger")).toBeVisible();
+    await expectPaneHasWindowDragSurface(originalPane);
+    await expectPaneHasWindowDragSurface(otherPane);
+  } finally {
+    await workspace.cleanup();
+  }
+});
diff --git a/packages/app/e2e/browser/empty-pane-keyboard.spec.ts b/packages/app/e2e/browser/empty-pane-keyboard.spec.ts
index 46dc4cf47f..8430fe5974 100644
--- a/packages/app/e2e/browser/empty-pane-keyboard.spec.ts
+++ b/packages/app/e2e/browser/empty-pane-keyboard.spec.ts
@@ -56,9 +56,9 @@ test.describe("New tab keyboard launcher", () => {
       await expectLauncherSelection(launcher, "Diff");
       await page.keyboard.press("Enter");
 
-      await expect(
-        page.getByTestId("workspace-tab-working_diff").filter({ visible: true }),
-      ).toBeVisible({ timeout: 30_000 });
+      await expect(page.getByTestId("working-diff-panel").filter({ visible: true })).toBeVisible({
+        timeout: 30_000,
+      });
     } finally {
       await workspace.cleanup();
     }
diff --git a/packages/app/e2e/browser/explorer-pane-placement.spec.ts b/packages/app/e2e/browser/explorer-pane-placement.spec.ts
index 55f96cc0cf..9a4a7127fe 100644
--- a/packages/app/e2e/browser/explorer-pane-placement.spec.ts
+++ b/packages/app/e2e/browser/explorer-pane-placement.spec.ts
@@ -105,6 +105,9 @@ function collectConsoleErrors(page: Page): string[] {
   return errors;
 }
 
+// These drag and tab-menu journeys need full rails beside the docked Explorer.
+test.use({ viewport: { width: 1900, height: 900 } });
+
 test.describe("explorer pane tab placement", () => {
   test("agents open in the main pane and New-tab splits keep the app usable", async ({
     page,
diff --git a/packages/app/e2e/browser/file-editing.spec.ts b/packages/app/e2e/browser/file-editing.spec.ts
index e9fc0b15ba..a395a517c2 100644
--- a/packages/app/e2e/browser/file-editing.spec.ts
+++ b/packages/app/e2e/browser/file-editing.spec.ts
@@ -435,7 +435,8 @@ test.describe("CodeMirror workspace file editing", () => {
     });
 
     try {
-      await page.setViewportSize({ width: 1280, height: 900 });
+      // Keep both tab rails available alongside the docked Explorer.
+      await page.setViewportSize({ width: 1900, height: 900 });
       await openAgentRoute(page, session);
 
       await openWorkspaceFile(page, "target.ts");
diff --git a/packages/app/e2e/browser/sidebar-workspace.spec.ts b/packages/app/e2e/browser/sidebar-workspace.spec.ts
index 0270235168..a7a7b4320a 100644
--- a/packages/app/e2e/browser/sidebar-workspace.spec.ts
+++ b/packages/app/e2e/browser/sidebar-workspace.spec.ts
@@ -652,6 +652,9 @@ test.describe("Half-screen desktop layout", () => {
           .locator('[data-testid^="workspace-pane-"]')
           .getByTestId("workspace-tabs-row")
           .filter({ visible: true }),
+      ).toHaveCount(0);
+      await expect(
+        page.getByTestId("workspace-tab-switcher-trigger").filter({ visible: true }),
       ).toHaveCount(1);
 
       await explorerToggle.click();
diff --git a/packages/app/e2e/browser/subagent-origin-pane.spec.ts b/packages/app/e2e/browser/subagent-origin-pane.spec.ts
index 545076ab06..8af88bd547 100644
--- a/packages/app/e2e/browser/subagent-origin-pane.spec.ts
+++ b/packages/app/e2e/browser/subagent-origin-pane.spec.ts
@@ -38,8 +38,12 @@ async function openParentInRightPane(page: Page, parentId: string, workspaceId:
   await expect(left).toBeVisible();
   await expect(right).toBeVisible();
   await expect(right).not.toHaveAttribute("data-testid", "workspace-pane-main");
+  // A later split can replace the parent pane's rail with compact chrome.
+  // Keep the pane identity instead of finding it again through that rail.
+  const rightPaneId = await right.getAttribute("data-testid");
+  expect(rightPaneId).not.toBeNull();
   await left.locator('[data-testid^="workspace-tab-draft_"]').click();
-  return { left, right };
+  return { left, right: page.getByTestId(rightPaneId!) };
 }
 
 test.beforeEach(async ({ page }) => {
diff --git a/packages/app/e2e/browser/terminal-find.spec.ts b/packages/app/e2e/browser/terminal-find.spec.ts
index 91e8e5826a..e4dde5cfaa 100644
--- a/packages/app/e2e/browser/terminal-find.spec.ts
+++ b/packages/app/e2e/browser/terminal-find.spec.ts
@@ -413,6 +413,8 @@ test("searches retained output without sending Find input to the shell", async (
 test("keeps terminal Find owned by retained tabs and the focused split pane", async ({
   page,
 }, testInfo) => {
+  // This journey selects tabs from the full rails in both split panes.
+  await page.setViewportSize({ width: 1600, height: 900 });
   const first = await harness.createTerminal({
     name: "First search",
     command: "bash",
diff --git a/packages/app/e2e/browser/viewed-agent-timelines.spec.ts b/packages/app/e2e/browser/viewed-agent-timelines.spec.ts
index 5ef70cca61..934a48d264 100644
--- a/packages/app/e2e/browser/viewed-agent-timelines.spec.ts
+++ b/packages/app/e2e/browser/viewed-agent-timelines.spec.ts
@@ -357,6 +357,8 @@ test.describe("Viewed agent timelines", () => {
   });
 
   test("two visible split chats both stay current", async ({ page }) => {
+    // Keep both split panes wide enough for the tab-rail interactions below.
+    await page.setViewportSize({ width: 1600, height: 900 });
     const scenario = await seedViewedTimelineScenario();
     try {
       await enableMoveTabShortcut(page);
diff --git a/packages/app/e2e/browser/workspace-focus-mode.spec.ts b/packages/app/e2e/browser/workspace-focus-mode.spec.ts
index e152b4defe..2929c2d093 100644
--- a/packages/app/e2e/browser/workspace-focus-mode.spec.ts
+++ b/packages/app/e2e/browser/workspace-focus-mode.spec.ts
@@ -101,3 +101,20 @@ test("focus mode only applies to the active workspace screen", async ({ page, wi
   await expect(exitFocusMode).toHaveCount(0);
   await expect(settingsButton).toBeVisible();
 });
+
+async function exitFocusModeFromCompactHeader(page: Page) {
+  await page.setViewportSize({ width: 400, height: 844 });
+  await page.getByTestId("workspace-header-menu-trigger").click();
+  await page.getByRole("menuitem", { name: "Exit focus mode", exact: true }).click();
+  await page.setViewportSize({ width: 1280, height: 900 });
+}
+
+test("compact workspace menu keeps focus mode exit reachable", async ({ page, withWorkspace }) => {
+  const workspace = await withWorkspace({ prefix: "compact-focus-exit-" });
+  await page.setViewportSize({ width: 1280, height: 900 });
+  await workspace.navigateTo();
+  await enterFocusMode(page);
+  await exitFocusModeFromCompactHeader(page);
+  await expect(exitFocusModeButton(page)).toHaveCount(0);
+  await expect(page.getByTestId("sidebar-global-new-workspace")).toBeVisible();
+});
diff --git a/packages/app/e2e/browser/workspace-pane-remount.spec.ts b/packages/app/e2e/browser/workspace-pane-remount.spec.ts
index 201b6e3ccf..c259dc8af2 100644
--- a/packages/app/e2e/browser/workspace-pane-remount.spec.ts
+++ b/packages/app/e2e/browser/workspace-pane-remount.spec.ts
@@ -52,6 +52,8 @@ async function waitForWorkspaceRoute(page: Page, route: string) {
 test.describe("Workspace pane mounting", () => {
   test("workspace navigation keeps the existing agent composer mounted", async ({ page }) => {
     test.setTimeout(90_000);
+    // Keep both split panes wide enough for the tab-rail interactions below.
+    await page.setViewportSize({ width: 1600, height: 900 });
     const serverId = getServerId();
 
     const workspace = await seedWorkspace({ repoPrefix: "pane-remount-" });
diff --git a/packages/app/src/components/explorer-sidebar-layout.test.ts b/packages/app/src/components/explorer-sidebar-layout.test.ts
index 3681ad4e16..adad890abe 100644
--- a/packages/app/src/components/explorer-sidebar-layout.test.ts
+++ b/packages/app/src/components/explorer-sidebar-layout.test.ts
@@ -1,7 +1,12 @@
 import { describe, expect, it } from "vitest";
 import {
+  beginExplorerSidebarResize,
+  finishExplorerSidebarResize,
+  reconcileExplorerSidebarResize,
   resolveExplorerSidebarDockSizes,
+  resolveExplorerSidebarFrameWidth,
   resolveExplorerSidebarWidth,
+  type ExplorerSidebarResize,
 } from "@/components/explorer-sidebar-layout";
 
 describe("Explorer sidebar layout", () => {
@@ -19,4 +24,196 @@ describe("Explorer sidebar layout", () => {
     expect(resolveExplorerSidebarWidth({ requestedWidth: 900, containerWidth: 1200 })).toBe(840);
     expect(resolveExplorerSidebarWidth({ requestedWidth: 600, containerWidth: 750 })).toBe(390);
   });
+
+  describe("native resize ownership", () => {
+    const allocation = {
+      width: 320,
+      containerWidth: 1200,
+      overlay: false,
+      resizeEnabled: true,
+    };
+    const dragging: ExplorerSidebarResize = {
+      sourceWidths: [allocation.width],
+      restoreWidth: allocation.width,
+      containerWidth: allocation.containerWidth,
+      pendingWidth: null,
+    };
+
+    it.each([false, true])(
+      "keeps a second drag through the previous release acknowledgement (released=%s)",
+      (releaseSecond) => {
+        const first = finishExplorerSidebarResize(dragging, 480, true);
+        const second = beginExplorerSidebarResize(first, allocation);
+        const current = releaseSecond ? finishExplorerSidebarResize(second, 600, true) : second;
+        const acknowledged = reconcileExplorerSidebarResize(current, { ...allocation, width: 480 });
+        expect(
+          resolveExplorerSidebarFrameWidth({
+            ...allocation,
+            width: 480,
+            resize: acknowledged,
+            resizeWidth: 600,
+          }),
+        ).toBe(600);
+        const released = finishExplorerSidebarResize(acknowledged, 600, true);
+        expect(released?.pendingWidth).toBe(600);
+        expect(reconcileExplorerSidebarResize(released, { ...allocation, width: 600 })).toBeNull();
+      },
+    );
+
+    it("keeps a return to the minimum while an earlier wider release is acknowledged", () => {
+      const initial = { ...allocation, width: 240 };
+      const wider = finishExplorerSidebarResize(
+        beginExplorerSidebarResize(null, initial),
+        540,
+        true,
+      );
+      const returned = finishExplorerSidebarResize(
+        beginExplorerSidebarResize(wider, initial),
+        240,
+        true,
+      );
+      const awaiting = reconcileExplorerSidebarResize(returned, initial);
+      const intermediate = reconcileExplorerSidebarResize(awaiting, { ...initial, width: 540 });
+      expect(
+        resolveExplorerSidebarFrameWidth({
+          ...initial,
+          width: 540,
+          resize: intermediate,
+          resizeWidth: 240,
+        }),
+      ).toBe(240);
+      expect(reconcileExplorerSidebarResize(intermediate, initial)).toBeNull();
+    });
+
+    it("cancels back to the latest release when earlier widths repeat", () => {
+      const first = finishExplorerSidebarResize(dragging, 480, true);
+      const second = finishExplorerSidebarResize(
+        beginExplorerSidebarResize(first, allocation),
+        600,
+        true,
+      );
+      const third = finishExplorerSidebarResize(
+        beginExplorerSidebarResize(second, allocation),
+        480,
+        true,
+      );
+      const fourth = beginExplorerSidebarResize(third, allocation);
+      const canceled = finishExplorerSidebarResize(fourth, 700, false);
+      expect(
+        resolveExplorerSidebarFrameWidth({ ...allocation, resize: canceled, resizeWidth: 700 }),
+      ).toBe(480);
+    });
+
+    it("cancels a newer gesture back to its last released width", () => {
+      const first = finishExplorerSidebarResize(dragging, 480, true);
+      const second = beginExplorerSidebarResize(first, allocation);
+      const canceled = finishExplorerSidebarResize(second, 600, false);
+      expect(
+        resolveExplorerSidebarFrameWidth({ ...allocation, resize: canceled, resizeWidth: 600 }),
+      ).toBe(480);
+      expect(reconcileExplorerSidebarResize(canceled, { ...allocation, width: 480 })).toBeNull();
+    });
+
+    it("keeps the drag width after release while the JS commit still has the old prop", () => {
+      expect(
+        resolveExplorerSidebarFrameWidth({ ...allocation, resize: dragging, resizeWidth: 480 }),
+      ).toBe(480);
+
+      const released = finishExplorerSidebarResize(dragging, 480, true);
+      expect(reconcileExplorerSidebarResize(released, allocation)).toBe(released);
+      expect(
+        resolveExplorerSidebarFrameWidth({ ...allocation, resize: released, resizeWidth: 480 }),
+      ).toBe(480);
+      expect(
+        resolveExplorerSidebarFrameWidth({ ...allocation, resize: released, resizeWidth: 320 }),
+      ).toBe(480);
+    });
+
+    it("acknowledges the committed width and immediately follows subsequent props", () => {
+      const released = finishExplorerSidebarResize(dragging, 480, true);
+      const acknowledgedAllocation = { ...allocation, width: 480 };
+      expect(
+        resolveExplorerSidebarFrameWidth({
+          ...acknowledgedAllocation,
+          resize: released,
+          resizeWidth: 480,
+        }),
+      ).toBe(480);
+      const acknowledged = reconcileExplorerSidebarResize(released, acknowledgedAllocation);
+      expect(acknowledged).toBeNull();
+      expect(
+        resolveExplorerSidebarFrameWidth({
+          ...allocation,
+          width: 360,
+          resize: acknowledged,
+          resizeWidth: 480,
+        }),
+      ).toBe(360);
+    });
+
+    it.each([
+      { name: "a new width prop", next: { ...allocation, width: 360 }, expected: 360 },
+      {
+        name: "a window allocation with an unchanged width prop",
+        next: { ...allocation, containerWidth: 900 },
+        expected: 320,
+      },
+      {
+        name: "a window allocation that clamps the width prop",
+        next: { ...allocation, width: 540, containerWidth: 900 },
+        expected: 540,
+      },
+      { name: "overlay presentation", next: { ...allocation, overlay: true }, expected: 1200 },
+      { name: "an inactive dock", next: { ...allocation, resizeEnabled: false }, expected: 320 },
+    ])(
+      "yields synchronously to $name and does not resurrect the old handoff",
+      ({ next, expected }) => {
+        const released = finishExplorerSidebarResize(dragging, 600, true);
+        expect(
+          resolveExplorerSidebarFrameWidth({ ...next, resize: released, resizeWidth: 600 }),
+        ).toBe(expected);
+        const interrupted = reconcileExplorerSidebarResize(released, next);
+        expect(interrupted).toBeNull();
+        expect(
+          resolveExplorerSidebarFrameWidth({
+            ...allocation,
+            resize: interrupted,
+            resizeWidth: 600,
+          }),
+        ).toBe(320);
+      },
+    );
+
+    it("restores canonical intent when a drag is canceled", () => {
+      const canceled = finishExplorerSidebarResize(dragging, 480, false);
+      expect(canceled).toBeNull();
+      expect(
+        resolveExplorerSidebarFrameWidth({ ...allocation, resize: canceled, resizeWidth: 480 }),
+      ).toBe(320);
+    });
+
+    it("cannot finish an interrupted drag over a newer allocation", () => {
+      const next = { ...allocation, width: 360, containerWidth: 1000 };
+      const interrupted = reconcileExplorerSidebarResize(dragging, next);
+      const released = finishExplorerSidebarResize(interrupted, 480, true);
+      expect(released).toBeNull();
+      expect(
+        resolveExplorerSidebarFrameWidth({ ...next, resize: released, resizeWidth: 480 }),
+      ).toBe(360);
+    });
+
+    it("settles a release at the already-committed width without retaining ownership", () => {
+      const released = finishExplorerSidebarResize(dragging, allocation.width, true);
+      expect(reconcileExplorerSidebarResize(released, allocation)).toBeNull();
+    });
+
+    it("keeps an earlier released handoff when a later touch fails before activation", () => {
+      const released = finishExplorerSidebarResize(dragging, 480, true);
+      const finalized = finishExplorerSidebarResize(released, 480, false);
+      expect(finalized).toBe(released);
+      expect(
+        resolveExplorerSidebarFrameWidth({ ...allocation, resize: finalized, resizeWidth: 480 }),
+      ).toBe(480);
+    });
+  });
 });
diff --git a/packages/app/src/components/explorer-sidebar-layout.ts b/packages/app/src/components/explorer-sidebar-layout.ts
index 8a39e2e9f4..9bb09600eb 100644
--- a/packages/app/src/components/explorer-sidebar-layout.ts
+++ b/packages/app/src/components/explorer-sidebar-layout.ts
@@ -16,6 +16,85 @@ export function resolveExplorerSidebarWidth(input: {
   return Math.max(MIN_EXPLORER_SIDEBAR_WIDTH, Math.min(maximumVisibleWidth, requestedWidth));
 }
 
+// A release keeps its UI width until React acknowledges it or replaces its allocation.
+// Null pendingWidth means the gesture still owns the live resizeWidth instead.
+export interface ExplorerSidebarResize {
+  sourceWidths: number[];
+  restoreWidth: number;
+  containerWidth: number;
+  pendingWidth: number | null;
+}
+
+interface ExplorerSidebarAllocation {
+  width: number;
+  containerWidth: number;
+  overlay: boolean;
+  resizeEnabled: boolean;
+}
+
+export function reconcileExplorerSidebarResize(
+  resize: ExplorerSidebarResize | null,
+  allocation: ExplorerSidebarAllocation,
+): ExplorerSidebarResize | null {
+  "worklet";
+  if (
+    !resize ||
+    allocation.overlay ||
+    !allocation.resizeEnabled ||
+    allocation.containerWidth !== resize.containerWidth ||
+    !resize.sourceWidths.includes(allocation.width) ||
+    (allocation.width === resize.pendingWidth &&
+      resize.sourceWidths.indexOf(allocation.width) === resize.sourceWidths.length - 1)
+  ) {
+    return null;
+  }
+  const acknowledgedIndex = resize.sourceWidths.indexOf(allocation.width);
+  return acknowledgedIndex > 0
+    ? { ...resize, sourceWidths: resize.sourceWidths.slice(acknowledgedIndex) }
+    : resize;
+}
+
+export function beginExplorerSidebarResize(
+  previous: ExplorerSidebarResize | null,
+  allocation: ExplorerSidebarAllocation,
+): ExplorerSidebarResize {
+  "worklet";
+  const current = reconcileExplorerSidebarResize(previous, allocation);
+  // Released widths remain expected allocations while a newer gesture owns the frame.
+  const sourceWidths = current ? [...current.sourceWidths] : [allocation.width];
+  if (current && current.pendingWidth !== null && !sourceWidths.includes(current.pendingWidth))
+    sourceWidths.push(current.pendingWidth);
+  return {
+    sourceWidths,
+    restoreWidth: current ? (current.pendingWidth ?? current.restoreWidth) : allocation.width,
+    containerWidth: allocation.containerWidth,
+    pendingWidth: null,
+  };
+}
+
+export function finishExplorerSidebarResize(
+  resize: ExplorerSidebarResize | null,
+  width: number,
+  success: boolean,
+): ExplorerSidebarResize | null {
+  "worklet";
+  if (!resize || resize.pendingWidth !== null) return resize;
+  if (success) return { ...resize, pendingWidth: width };
+  return resize.sourceWidths.length > 1 ? { ...resize, pendingWidth: resize.restoreWidth } : null;
+}
+
+export function resolveExplorerSidebarFrameWidth(
+  allocation: ExplorerSidebarAllocation & {
+    resize: ExplorerSidebarResize | null;
+    resizeWidth: number;
+  },
+): number {
+  "worklet";
+  if (allocation.overlay) return allocation.containerWidth;
+  const resize = reconcileExplorerSidebarResize(allocation.resize, allocation);
+  return resize ? (resize.pendingWidth ?? allocation.resizeWidth) : allocation.width;
+}
+
 export function resolveExplorerSidebarDockSizes(input: {
   requestedWidth?: number;
   containerWidth: number;
diff --git a/packages/app/src/components/split-container.tsx b/packages/app/src/components/split-container.tsx
index 278317243a..63a3144dda 100644
--- a/packages/app/src/components/split-container.tsx
+++ b/packages/app/src/components/split-container.tsx
@@ -1,3 +1,7 @@
+import {
+  AdaptiveWorkspaceChrome,
+  type WorkspaceCompactHeaderActions,
+} from "@/screens/workspace/adaptive-workspace-chrome";
 import { useWorkspaceTabDrag } from "./workspace-tab-drag-context";
 import {
   Fragment,
@@ -32,6 +36,7 @@ import {
   WindowChromeSafeArea,
   useWindowChromeCorners,
   removeWindowChromeCorner,
+  resolveChildWindowChromeCorners,
   type WindowChromeCorners,
 } from "@/utils/desktop-window";
 import { TitlebarDragRegion } from "@/components/desktop/titlebar-drag-region";
@@ -42,6 +47,7 @@ import type { WorkspacePaneContentModel } from "@/screens/workspace/workspace-pa
 import { WorkspacePanelHost } from "@/screens/workspace/workspace-panel-host";
 import {
   WorkspaceDesktopTabsRow,
+  useWorkspaceNewTabKeyboardAction,
   type WorkspaceDesktopTabRowItem,
 } from "@/screens/workspace/workspace-desktop-tabs-row";
 import type { WorkspaceTabDescriptor } from "@/screens/workspace/workspace-tabs-types";
@@ -61,6 +67,11 @@ import { isNative } from "@/constants/platform";
 interface SplitContainerProps {
   layout: WorkspaceLayout;
   renderMainHeader?: () => ReactNode;
+  renderCompactHeader: (
+    tabs: WorkspaceTabDescriptor[],
+    activeTabKey: string,
+    actions: WorkspaceCompactHeaderActions,
+  ) => ReactNode;
   workspaceKey: string;
   normalizedServerId: string;
   normalizedWorkspaceId: string;
@@ -145,7 +156,6 @@ const EMPTY_SPLIT_SIZES: number[] = [];
 
 export function SplitContainer({
   layout,
-  renderMainHeader,
   workspaceKey,
   normalizedServerId,
   normalizedWorkspaceId,
@@ -174,9 +184,11 @@ export function SplitContainer({
   onReorderTabsInPane,
   focusModeEnabled,
   onExitFocusMode,
+  renderMainHeader,
+  renderCompactHeader,
 }: SplitContainerProps) {
   const inheritedWindowChromeCorners = useWindowChromeCorners();
-  const windowChromeCorners = focusModeEnabled ? inheritedWindowChromeCorners : "none";
+  const windowChromeCorners = inheritedWindowChromeCorners;
   const { activeDragTabId, dropPreview, tabDropPreview } = useWorkspaceTabDrag();
   const [maximizedPane, setMaximizedPane] = useState<{
     workspaceKey: string;
@@ -237,7 +249,6 @@ export function SplitContainer({
       <View style={styles.workspaceShell}>
         <WindowChromeRegion corners={mainColumnWindowChromeCorners}>
           <View style={mainColumnStyle}>
-            {renderMainHeader?.()}
             {splitRoot.usesFallbackStrip && <WindowChromeSafeArea placement="below" />}
             {renderRoot ? (
               <SplitNodeView
@@ -279,6 +290,8 @@ export function SplitContainer({
                 onTogglePaneMaximized={handleTogglePaneMaximized}
                 focusModeEnabled={focusModeEnabled}
                 onExitFocusMode={onExitFocusMode}
+                renderMainHeader={renderMainHeader}
+                renderCompactHeader={renderCompactHeader}
               />
             ) : null}
           </View>
@@ -410,6 +423,8 @@ function SplitNodeView({
   onTogglePaneMaximized,
   focusModeEnabled,
   onExitFocusMode,
+  renderMainHeader,
+  renderCompactHeader,
 }: SplitNodeViewProps) {
   const [groupContainerSize, setGroupContainerSize] = useState(0);
   const groupId = node.kind === "group" ? node.group.id : null;
@@ -496,6 +511,8 @@ function SplitNodeView({
             onTogglePaneMaximized={onTogglePaneMaximized}
             focusModeEnabled={focusModeEnabled}
             onExitFocusMode={onExitFocusMode}
+            renderMainHeader={renderMainHeader}
+            renderCompactHeader={renderCompactHeader}
           />
         </WindowChromeRegion>
       </RetainedPanel>
@@ -544,12 +561,25 @@ function SplitNodeView({
               showDropZones={showDropZones}
               dropPreview={dropPreview}
               tabDropPreview={tabDropPreview}
-              windowChromeCorners={windowChromeCorners}
+              windowChromeCorners={resolveChildWindowChromeCorners({
+                corners: windowChromeCorners,
+                direction: node.group.direction,
+                isFirst:
+                  node.group.children.findIndex(
+                    (candidate) => !isSplitNodeHiddenForPresentation(candidate, maximizedPaneId),
+                  ) === index,
+                isLast:
+                  node.group.children.findLastIndex(
+                    (candidate) => !isSplitNodeHiddenForPresentation(candidate, maximizedPaneId),
+                  ) === index,
+              })}
               maximizedPaneId={maximizedPaneId}
               workspaceHasMultiplePanes={workspaceHasMultiplePanes}
               onTogglePaneMaximized={onTogglePaneMaximized}
               focusModeEnabled={focusModeEnabled}
               onExitFocusMode={onExitFocusMode}
+              renderMainHeader={renderMainHeader}
+              renderCompactHeader={renderCompactHeader}
             />
           </SplitGroupChild>
           {index < node.group.children.length - 1 &&
@@ -608,6 +638,8 @@ const SplitPaneView = memo(function SplitPaneView({
   onTogglePaneMaximized,
   focusModeEnabled,
   onExitFocusMode,
+  renderMainHeader,
+  renderCompactHeader,
 }: SplitPaneViewProps) {
   recordRenderProfileReasons(`SplitPaneView:${pane.id}`, ["render"]);
   const paneRef = useRef<View | null>(null);
@@ -701,6 +733,51 @@ const SplitPaneView = memo(function SplitPaneView({
     () => onTogglePaneMaximized(paneId),
     [onTogglePaneMaximized, paneId],
   );
+  const compactHeaderActions = useMemo(
+    () => ({
+      pane: {
+        id: paneId,
+        splitRight: focusModeEnabled ? undefined : handleSplitRight,
+        splitDown: focusModeEnabled ? undefined : handleSplitDown,
+        toggleMaximized:
+          workspaceHasMultiplePanes && !focusModeEnabled ? handleTogglePaneMaximized : undefined,
+        maximized: paneId === maximizedPaneId,
+      },
+      closeAbove: handleCloseTabsToLeft,
+      closeBelow: handleCloseTabsToRight,
+      closeOthers: handleCloseOtherTabs,
+    }),
+    [
+      paneId,
+      focusModeEnabled,
+      handleSplitRight,
+      handleSplitDown,
+      workspaceHasMultiplePanes,
+      handleTogglePaneMaximized,
+      maximizedPaneId,
+      handleCloseTabsToLeft,
+      handleCloseTabsToRight,
+      handleCloseOtherTabs,
+    ],
+  );
+  const createNewTab = useCallback(() => onCreateNewTab({ paneId }), [onCreateNewTab, paneId]);
+  useWorkspaceNewTabKeyboardAction({
+    handlerName: "workspace-chrome-new-tab",
+    ownsKeyboardShortcuts: isFocused && isWorkspaceFocused,
+    normalizedServerId,
+    normalizedWorkspaceId,
+    paneId,
+    createNewTab,
+  });
+  const compactHeader = useMemo(
+    () => (
+      <WindowChromeSafeArea placement="inline">
+        <TitlebarDragRegion />
+        {renderCompactHeader(paneTabs, activeTabDescriptor?.key ?? "", compactHeaderActions)}
+      </WindowChromeSafeArea>
+    ),
+    [renderCompactHeader, paneTabs, activeTabDescriptor?.key, compactHeaderActions],
+  );
   return (
     <RenderProfile id={`SplitPaneView:${pane.id}`}>
       <View
@@ -709,43 +786,49 @@ const SplitPaneView = memo(function SplitPaneView({
         style={styles.pane}
         testID={`workspace-pane-${pane.id}`}
       >
-        <WindowChromeSafeArea placement="inline" style={styles.paneTabs}>
-          <TitlebarDragRegion />
-          <WorkspaceDesktopTabsRow
-            paneId={pane.id}
-            isFocused={isFocused && isWorkspaceFocused}
-            tabs={desktopTabRowItems}
-            normalizedServerId={normalizedServerId}
-            normalizedWorkspaceId={normalizedWorkspaceId}
-            setHoveredCloseTabKey={setHoveredCloseTabKey}
-            onNavigateTab={onNavigateTab}
-            onCloseTab={onCloseTab}
-            onCopyResumeCommand={onCopyResumeCommand}
-            onCopyAgentId={onCopyAgentId}
-            onCopyTerminalId={onCopyTerminalId}
-            onCopyFilePath={onCopyFilePath}
-            onReloadAgent={onReloadAgent}
-            onRenameTab={onRenameTab}
-            onCloseTabsToLeft={handleCloseTabsToLeft}
-            onCloseTabsToRight={handleCloseTabsToRight}
-            onCloseOtherTabs={handleCloseOtherTabs}
-            onCreateNewTab={onCreateNewTab}
-            onReorderTabs={handleReorderTabs}
-            externalDndContext
-            activeDragTabId={activeDragTabId}
-            tabDropPreviewIndex={
-              tabDropPreview?.paneId === pane.id ? tabDropPreview.indicatorIndex : null
-            }
-            showPaneSplitActions={!focusModeEnabled}
-            showPaneMaximizeAction={workspaceHasMultiplePanes && !focusModeEnabled}
-            paneMaximized={paneId === maximizedPaneId}
-            onTogglePaneMaximized={handleTogglePaneMaximized}
-            onSplitRight={handleSplitRight}
-            onSplitDown={handleSplitDown}
-            focusModeEnabled={Boolean(focusModeEnabled)}
-            onExitFocusMode={onExitFocusMode}
-          />
-        </WindowChromeSafeArea>
+        <AdaptiveWorkspaceChrome compactHeader={compactHeader}>
+          {renderMainHeader?.()}
+          <WindowChromeRegion corners={focusModeEnabled ? "both" : "none"}>
+            <WindowChromeSafeArea placement="inline" style={styles.paneTabs}>
+              <TitlebarDragRegion />
+              <WorkspaceDesktopTabsRow
+                paneId={pane.id}
+                isFocused={isFocused && isWorkspaceFocused}
+                tabs={desktopTabRowItems}
+                normalizedServerId={normalizedServerId}
+                normalizedWorkspaceId={normalizedWorkspaceId}
+                setHoveredCloseTabKey={setHoveredCloseTabKey}
+                onNavigateTab={onNavigateTab}
+                onCloseTab={onCloseTab}
+                onCopyResumeCommand={onCopyResumeCommand}
+                onCopyAgentId={onCopyAgentId}
+                onCopyTerminalId={onCopyTerminalId}
+                onCopyFilePath={onCopyFilePath}
+                onReloadAgent={onReloadAgent}
+                onRenameTab={onRenameTab}
+                onCloseTabsToLeft={handleCloseTabsToLeft}
+                onCloseTabsToRight={handleCloseTabsToRight}
+                onCloseOtherTabs={handleCloseOtherTabs}
+                onCreateNewTab={onCreateNewTab}
+                onReorderTabs={handleReorderTabs}
+                ownsKeyboardShortcuts={false}
+                externalDndContext
+                activeDragTabId={activeDragTabId}
+                tabDropPreviewIndex={
+                  tabDropPreview?.paneId === pane.id ? tabDropPreview.indicatorIndex : null
+                }
+                showPaneSplitActions={!focusModeEnabled}
+                showPaneMaximizeAction={workspaceHasMultiplePanes && !focusModeEnabled}
+                paneMaximized={paneId === maximizedPaneId}
+                onTogglePaneMaximized={handleTogglePaneMaximized}
+                onSplitRight={handleSplitRight}
+                onSplitDown={handleSplitDown}
+                focusModeEnabled={Boolean(focusModeEnabled)}
+                onExitFocusMode={onExitFocusMode}
+              />
+            </WindowChromeSafeArea>
+          </WindowChromeRegion>
+        </AdaptiveWorkspaceChrome>
 
         <View style={styles.paneContent}>
           <WorkspacePanelHost
diff --git a/packages/app/src/composer/input/input.tsx b/packages/app/src/composer/input/input.tsx
index 311e4dedd4..c79c3e0082 100644
--- a/packages/app/src/composer/input/input.tsx
+++ b/packages/app/src/composer/input/input.tsx
@@ -8,6 +8,7 @@ import {
 import { LoadingSpinner } from "@/components/ui/loading-spinner";
 import {
   View,
+  Platform,
   Text,
   useWindowDimensions,
   NativeSyntheticEvent,
@@ -1936,7 +1937,7 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
     const inputWrapperCombinedStyle = useMemo(
       () => [
         styles.inputWrapper,
-        isCompact && !isFullscreen && styles.inputWrapperCompact,
+        Platform.OS !== "ios" && isCompact && !isFullscreen && styles.inputWrapperCompact,
         readOnly && styles.inputWrapperReadOnly,
         inputWrapperStyle,
         { opacity: surfacePresentation.input.opacity },
@@ -2230,7 +2231,11 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
     return (
       <View
         ref={rootRef}
-        style={isFullscreen ? styles.fullscreenContainer : styles.container}
+        style={
+          isFullscreen
+            ? styles.fullscreenContainer
+            : [styles.container, Platform.OS === "ios" && isCompact && styles.inputWrapperCompact]
+        }
         testID="message-input-root"
         onLayout={handleComposerLayout}
       >
@@ -2276,6 +2281,7 @@ const styles = StyleSheet.create((theme: Theme) => ({
     position: "relative",
   },
   inputWrapper: {
+    ...(Platform.OS === "ios" ? { overflow: "hidden" as const } : {}),
     flexShrink: 1,
     flexDirection: "column",
     gap: theme.spacing[3],
diff --git a/packages/app/src/keyboard/shift/internal/policy.test.ts b/packages/app/src/keyboard/shift/internal/policy.test.ts
index 51387eba43..10192b1b88 100644
--- a/packages/app/src/keyboard/shift/internal/policy.test.ts
+++ b/packages/app/src/keyboard/shift/internal/policy.test.ts
@@ -29,6 +29,21 @@ describe("keyboard layout reservation", () => {
 });
 
 describe("resolveKeyboardShift", () => {
+  it.each([0, -1])(
+    "ignores a rotation report with height %s and progress one",
+    (rawKeyboardHeight) => {
+      expect(
+        resolveKeyboardShift({
+          rawKeyboardHeight,
+          keyboardProgress: 1,
+          bottomInset: 24,
+          isIos: true,
+          iosMinHeight: 120,
+        }),
+      ).toBe(0);
+    },
+  );
+
   it("keeps the existing open-keyboard offset behavior", () => {
     expect(
       resolveKeyboardShift({
diff --git a/packages/app/src/screens/workspace/adaptive-workspace-chrome.tsx b/packages/app/src/screens/workspace/adaptive-workspace-chrome.tsx
new file mode 100644
index 0000000000..668f6345a8
--- /dev/null
+++ b/packages/app/src/screens/workspace/adaptive-workspace-chrome.tsx
@@ -0,0 +1,38 @@
+import { useCallback, useState, type ReactNode } from "react";
+import { View, type LayoutChangeEvent } from "react-native";
+import { selectWorkspaceChrome } from "./workspace-tab-layout";
+import { WorkspaceTabMeasurementScope } from "./workspace-desktop-tabs-row";
+
+export function AdaptiveWorkspaceChrome({
+  compactHeader,
+  children,
+}: {
+  compactHeader: ReactNode;
+  children: ReactNode;
+}) {
+  const [width, setWidth] = useState<number | null>(null);
+  const measure = useCallback((event: LayoutChangeEvent) => {
+    const measured = event.nativeEvent.layout.width;
+    if (measured > 0) setWidth(measured);
+  }, []);
+  return (
+    <WorkspaceTabMeasurementScope>
+      <View onLayout={measure}>
+        {selectWorkspaceChrome({ width, compact: compactHeader, full: children })}
+      </View>
+    </WorkspaceTabMeasurementScope>
+  );
+}
+
+export interface WorkspaceCompactHeaderActions {
+  pane?: {
+    id: string;
+    splitRight?: () => void;
+    splitDown?: () => void;
+    toggleMaximized?: () => void;
+    maximized: boolean;
+  };
+  closeAbove: (key: string) => Promise<void> | void;
+  closeBelow: (key: string) => Promise<void> | void;
+  closeOthers: (key: string) => Promise<void> | void;
+}
diff --git a/packages/app/src/screens/workspace/compact-workspace-header/tab-switcher.tsx b/packages/app/src/screens/workspace/compact-workspace-header/tab-switcher.tsx
index 737e92b4c2..334a166aef 100644
--- a/packages/app/src/screens/workspace/compact-workspace-header/tab-switcher.tsx
+++ b/packages/app/src/screens/workspace/compact-workspace-header/tab-switcher.tsx
@@ -1,3 +1,4 @@
+import { workspaceTabSwitcherPopoverLayout } from "../workspace-tab-layout";
 import { memo, useCallback, useMemo, useRef, useState } from "react";
 import { Keyboard, Pressable, Text, View } from "react-native";
 import { useTranslation } from "react-i18next";
@@ -123,14 +124,15 @@ function getFallbackTabOptionDescription(
 }
 
 interface MobileWorkspaceTabSwitcherProps {
+  paneId?: string;
   tabs: WorkspaceTabDescriptor[];
   activeTabKey: string;
   normalizedServerId: string;
   normalizedWorkspaceId: string;
   onSelectSwitcherTab: (key: string) => void;
   createTerminalDisabled: boolean;
-  onCreateDraftTab: () => void;
-  onCreateTerminal: () => void;
+  onCreateDraftTab: (input?: { paneId?: string }) => void;
+  onCreateTerminal: (input?: { paneId?: string }) => void;
   onCopyResumeCommand: (agentId: string) => Promise<void> | void;
   onCopyAgentId: (agentId: string) => Promise<void> | void;
   onCopyTerminalId: (terminalId: string) => Promise<void> | void;
@@ -285,6 +287,7 @@ export const MobileWorkspaceTabSwitcher = memo(function MobileWorkspaceTabSwitch
   createTerminalDisabled,
   onCreateDraftTab,
   onCreateTerminal,
+  paneId,
   onCopyResumeCommand,
   onCopyAgentId,
   onCopyTerminalId,
@@ -342,13 +345,13 @@ export const MobileWorkspaceTabSwitcher = memo(function MobileWorkspaceTabSwitch
 
   const handleNewAgent = useCallback(() => {
     setIsOpen(false);
-    onCreateDraftTab();
-  }, [onCreateDraftTab]);
+    onCreateDraftTab({ paneId });
+  }, [onCreateDraftTab, paneId]);
 
   const handleNewTerminal = useCallback(() => {
     setIsOpen(false);
-    onCreateTerminal();
-  }, [onCreateTerminal]);
+    onCreateTerminal({ paneId });
+  }, [onCreateTerminal, paneId]);
 
   const footer = useMemo(
     () => (
@@ -456,6 +459,7 @@ export const MobileWorkspaceTabSwitcher = memo(function MobileWorkspaceTabSwitch
       </Pressable>
 
       <Combobox
+        {...workspaceTabSwitcherPopoverLayout}
         options={tabSwitcherOptions}
         value={activeTabKey}
         onSelect={onSelectSwitcherTab}
diff --git a/packages/app/src/screens/workspace/explorer-sidebar/geometry.tsx b/packages/app/src/screens/workspace/explorer-sidebar/geometry.tsx
index 4714467985..d2ece171f7 100644
--- a/packages/app/src/screens/workspace/explorer-sidebar/geometry.tsx
+++ b/packages/app/src/screens/workspace/explorer-sidebar/geometry.tsx
@@ -1,6 +1,11 @@
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useMemo, useState } from "react";
 import { Gesture } from "react-native-gesture-handler";
-import { runOnJS, useAnimatedStyle, useSharedValue } from "react-native-reanimated";
+import {
+  runOnJS,
+  useAnimatedReaction,
+  useAnimatedStyle,
+  useSharedValue,
+} from "react-native-reanimated";
 import { scheduleOnRN } from "react-native-worklets";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { HEADER_TOP_PADDING_MOBILE } from "@/constants/layout";
@@ -9,7 +14,14 @@ import {
   SIDEBAR_RESIZE_ACTIVATION_OFFSET,
   SIDEBAR_RESIZE_FAIL_OFFSET,
 } from "@/components/sidebar-resize-handle-layout";
-import { resolveExplorerSidebarWidth } from "@/components/explorer-sidebar-layout";
+import {
+  beginExplorerSidebarResize,
+  finishExplorerSidebarResize,
+  reconcileExplorerSidebarResize,
+  resolveExplorerSidebarFrameWidth,
+  resolveExplorerSidebarWidth,
+  type ExplorerSidebarResize,
+} from "@/components/explorer-sidebar-layout";
 import type { ExplorerGeometryInput, ExplorerGeometry } from "./geometry-types";
 export function useExplorerGeometry({
   width,
@@ -21,10 +33,16 @@ export function useExplorerGeometry({
   const insets = useSafeAreaInsets();
   const resizeWidth = useSharedValue(width);
   const startWidth = useSharedValue(width);
+  const resize = useSharedValue<ExplorerSidebarResize | null>(null);
   const [resizePressed, setResizePressed] = useState(false);
-  useEffect(() => {
-    resizeWidth.value = width;
-  }, [resizeWidth, width]);
+  useAnimatedReaction(
+    () => ({ resize: resize.value, width, containerWidth, overlay, resizeEnabled }),
+    ({ resize: currentResize, ...allocation }) => {
+      const nextResize = reconcileExplorerSidebarResize(currentResize, allocation);
+      if (nextResize !== currentResize) resize.value = nextResize;
+    },
+    [containerWidth, overlay, resize, resizeEnabled, width],
+  );
 
   const showResizeGrip = useCallback(() => setResizePressed(true), []);
   const hideResizeGrip = useCallback(() => setResizePressed(false), []);
@@ -37,22 +55,50 @@ export function useExplorerGeometry({
         .activeOffsetX([-SIDEBAR_RESIZE_ACTIVATION_OFFSET, SIDEBAR_RESIZE_ACTIVATION_OFFSET])
         .failOffsetY([-SIDEBAR_RESIZE_FAIL_OFFSET, SIDEBAR_RESIZE_FAIL_OFFSET])
         .onStart((event) => {
-          startWidth.value = width + event.translationX;
-          resizeWidth.value = width;
+          const currentWidth = resolveExplorerSidebarFrameWidth({
+            width,
+            containerWidth,
+            overlay,
+            resizeEnabled,
+            resize: resize.value,
+            resizeWidth: resizeWidth.value,
+          });
+          resize.value = beginExplorerSidebarResize(resize.value, {
+            width,
+            containerWidth,
+            overlay,
+            resizeEnabled,
+          });
+          startWidth.value = currentWidth + event.translationX;
+          resizeWidth.value = currentWidth;
         })
         .onUpdate((event) => {
+          if (!resize.value) return;
           resizeWidth.value = resolveExplorerSidebarWidth({
             requestedWidth: startWidth.value - event.translationX,
             containerWidth,
           });
         })
-        .onEnd(() => runOnJS(onResize)(resizeWidth.value))
-        .onFinalize(() => scheduleOnRN(hideResizeGrip)),
+        .onEnd((_event, success) => {
+          {
+            resize.value = finishExplorerSidebarResize(resize.value, resizeWidth.value, success);
+            if (!success || !resize.value) return;
+          }
+          runOnJS(onResize)(resizeWidth.value);
+        })
+        .onFinalize((_event, success) => {
+          if (!success) {
+            resize.value = finishExplorerSidebarResize(resize.value, resizeWidth.value, false);
+          }
+          scheduleOnRN(hideResizeGrip);
+        }),
     [
       resizeEnabled,
       onResize,
       containerWidth,
       hideResizeGrip,
+      overlay,
+      resize,
       resizeWidth,
       showResizeGrip,
       startWidth,
@@ -61,12 +107,21 @@ export function useExplorerGeometry({
   );
   // Reanimated retains the last animated value when its style is removed. Keep this
   // style attached across folding and explicitly size overlays to the workspace viewport.
-  const animatedWidthStyle = useAnimatedStyle(
-    () => ({
-      width: overlay ? containerWidth : resizeWidth.value,
-    }),
-    [containerWidth, overlay],
-  );
+  const animatedWidthStyle = useAnimatedStyle(() => {
+    if (overlay) return { width: containerWidth };
+    {
+      return {
+        width: resolveExplorerSidebarFrameWidth({
+          width,
+          containerWidth,
+          overlay,
+          resizeEnabled,
+          resize: resize.value,
+          resizeWidth: resizeWidth.value,
+        }),
+      };
+    }
+  }, [containerWidth, overlay, resizeEnabled, width]);
   return {
     frameStyle: animatedWidthStyle,
     panelStyle: {
diff --git a/packages/app/src/screens/workspace/workspace-desktop-tabs-row.tsx b/packages/app/src/screens/workspace/workspace-desktop-tabs-row.tsx
index 01a5ccadaf..3c138087c0 100644
--- a/packages/app/src/screens/workspace/workspace-desktop-tabs-row.tsx
+++ b/packages/app/src/screens/workspace/workspace-desktop-tabs-row.tsx
@@ -1,6 +1,8 @@
 import { LoadingSpinner } from "@/components/ui/loading-spinner";
 import React, {
   Fragment,
+  createContext,
+  useContext,
   useCallback,
   useEffect,
   useLayoutEffect,
@@ -488,6 +490,13 @@ interface WorkspaceTabLabelMeasurement {
   width: number;
 }
 
+const TabMeasurementCache = createContext<Map<string, WorkspaceTabLabelMeasurement> | null>(null);
+
+export function WorkspaceTabMeasurementScope({ children }: { children: React.ReactNode }) {
+  const cache = useMemo(() => new Map<string, WorkspaceTabLabelMeasurement>(), []);
+  return <TabMeasurementCache.Provider value={cache}>{children}</TabMeasurementCache.Provider>;
+}
+
 interface WorkspaceTabTrackSnapshot {
   signature: string;
   tabs: ResolvedWorkspaceDesktopTabRowItem[];
@@ -961,6 +970,47 @@ function TabChip({
   );
 }
 
+export function useWorkspaceNewTabKeyboardAction({
+  handlerName = "workspace-new-tab",
+  ownsKeyboardShortcuts,
+  normalizedServerId,
+  normalizedWorkspaceId,
+  paneId,
+  createNewTab,
+}: {
+  handlerName?: string;
+  ownsKeyboardShortcuts: boolean;
+  normalizedServerId: string;
+  normalizedWorkspaceId: string;
+  paneId?: string;
+  createNewTab: () => void;
+}) {
+  const handleNewTabKeyboardAction = useCallback(
+    (action: KeyboardActionDefinition): boolean => {
+      if (!ownsKeyboardShortcuts) return false;
+      if (action.id === "workspace.tab.menu.open") {
+        createNewTab();
+        return true;
+      }
+      return false;
+    },
+    [createNewTab, ownsKeyboardShortcuts],
+  );
+
+  useKeyboardActionHandler({
+    handlerId: buildWorkspaceKeyboardHandlerId({
+      name: handlerName,
+      serverId: normalizedServerId,
+      workspaceId: normalizedWorkspaceId,
+      paneId,
+    }),
+    actions: ["workspace.tab.menu.open"],
+    enabled: ownsKeyboardShortcuts,
+    priority: 200,
+    handle: handleNewTabKeyboardAction,
+  });
+}
+
 export function WorkspaceDesktopTabsRow(props: WorkspaceDesktopTabsRowProps) {
   const [presentations, setPresentations] = useState(
     () => new Map<string, WorkspaceTabPresentation>(),
@@ -1062,9 +1112,13 @@ function ResolvedWorkspaceDesktopTabsRow({
   const tabsScrollRef = useRef<ScrollView>(null);
   const [exitFocusModeWidth, setExitFocusModeWidth] = useState<number>(0);
   const tabScrollBoundary = useHorizontalScrollBoundary();
-  const [labelMeasurements, setLabelMeasurements] = useState(
-    () => new Map<string, WorkspaceTabLabelMeasurement>(),
-  );
+  const measurementCache = useContext(TabMeasurementCache);
+  const [labelMeasurements, setLabelMeasurements] = useState(() => new Map(measurementCache ?? []));
+  useLayoutEffect(() => {
+    if (!measurementCache) return;
+    measurementCache.clear();
+    for (const [key, value] of labelMeasurements) measurementCache.set(key, value);
+  }, [measurementCache, labelMeasurements]);
   const [trackSnapshot, setTrackSnapshot] = useState<WorkspaceTabTrackSnapshot | null>(null);
 
   const handleTabsContainerLayout = useCallback((event: LayoutChangeEvent) => {
@@ -1249,29 +1303,12 @@ function ResolvedWorkspaceDesktopTabsRow({
 
   const createNewTab = useCallback(() => onCreateNewTab({ paneId }), [onCreateNewTab, paneId]);
 
-  const handleNewTabKeyboardAction = useCallback(
-    (action: KeyboardActionDefinition): boolean => {
-      if (!ownsKeyboardShortcuts) return false;
-      if (action.id === "workspace.tab.menu.open") {
-        createNewTab();
-        return true;
-      }
-      return false;
-    },
-    [createNewTab, ownsKeyboardShortcuts],
-  );
-
-  useKeyboardActionHandler({
-    handlerId: buildWorkspaceKeyboardHandlerId({
-      name: "workspace-new-tab",
-      serverId: normalizedServerId,
-      workspaceId: normalizedWorkspaceId,
-      paneId,
-    }),
-    actions: ["workspace.tab.menu.open"],
-    enabled: ownsKeyboardShortcuts,
-    priority: 200,
-    handle: handleNewTabKeyboardAction,
+  useWorkspaceNewTabKeyboardAction({
+    ownsKeyboardShortcuts,
+    normalizedServerId,
+    normalizedWorkspaceId,
+    paneId,
+    createNewTab,
   });
 
   const rail: WorkspaceTabRailSurface = host === "explorer" ? "sidebar" : "surface";
diff --git a/packages/app/src/screens/workspace/workspace-header-menu.tsx b/packages/app/src/screens/workspace/workspace-header-menu.tsx
index b8f4739cfb..cca5dd2e10 100644
--- a/packages/app/src/screens/workspace/workspace-header-menu.tsx
+++ b/packages/app/src/screens/workspace/workspace-header-menu.tsx
@@ -1,3 +1,4 @@
+import type { WorkspaceCompactHeaderActions } from "./adaptive-workspace-chrome";
 import React, { useCallback, useMemo } from "react";
 import { View } from "react-native";
 import { useRouter, type Href } from "expo-router";
@@ -206,13 +207,15 @@ function HeaderMenuProfileItem({
 }
 
 export interface WorkspaceHeaderMenuMobileProps extends WorkspaceHeaderWorkspaceActions {
+  pane?: WorkspaceCompactHeaderActions["pane"];
+  onExitFocusMode?: () => void;
   normalizedServerId: string;
   normalizedWorkspaceId: string;
   scripts: UseWorkspaceScriptsMenuPagesInput;
   showCreateBrowserTab: boolean;
   createTerminalDisabled: boolean;
-  onCreateTerminalWithProfile: (profile: TerminalProfile) => void;
-  onCreateBrowser: () => void;
+  onCreateTerminalWithProfile: (profile: TerminalProfile, paneId?: string) => void;
+  onCreateBrowser: (input?: { paneId?: string }) => void;
 }
 
 /**
@@ -231,8 +234,19 @@ export function WorkspaceHeaderMenuMobile({
   createTerminalDisabled,
   onCreateTerminalWithProfile,
   onCreateBrowser,
+  pane,
+  onExitFocusMode,
   ...workspaceActions
 }: WorkspaceHeaderMenuMobileProps) {
+  const paneId = pane?.id;
+  const handleCreateBrowser = useCallback(
+    () => onCreateBrowser({ paneId }),
+    [onCreateBrowser, paneId],
+  );
+  const handleCreateTerminalWithProfile = useCallback(
+    (profile: TerminalProfile) => onCreateTerminalWithProfile(profile, paneId),
+    [onCreateTerminalWithProfile, paneId],
+  );
   const { t } = useTranslation();
   const router = useRouter();
   const triggerStyle = useIconButtonChromeStyle({ size: "large" });
@@ -278,6 +292,30 @@ export function WorkspaceHeaderMenuMobile({
         pages={pages}
         sheetTitle={t("workspace.header.actions.workspaceActions")}
       >
+        {onExitFocusMode ? (
+          <DropdownMenuItem onSelect={onExitFocusMode}>
+            {t("workspace.tabs.actions.exitFocusMode")}
+          </DropdownMenuItem>
+        ) : null}
+        {pane?.splitRight ? (
+          <DropdownMenuItem onSelect={pane.splitRight}>
+            {t("workspace.tabs.actions.splitRight")}
+          </DropdownMenuItem>
+        ) : null}
+        {pane?.splitDown ? (
+          <DropdownMenuItem onSelect={pane.splitDown}>
+            {t("workspace.tabs.actions.splitDown")}
+          </DropdownMenuItem>
+        ) : null}
+        {pane?.toggleMaximized ? (
+          <DropdownMenuItem onSelect={pane.toggleMaximized}>
+            {t(
+              pane.maximized
+                ? "workspace.tabs.actions.restorePane"
+                : "workspace.tabs.actions.maximizePane",
+            )}
+          </DropdownMenuItem>
+        ) : null}
         {scriptsMenu.trigger}
         {pluginMenu.rows}
         {pluginMenu.rows.length > 0 ? <DropdownMenuSeparator /> : null}
@@ -285,7 +323,7 @@ export function WorkspaceHeaderMenuMobile({
           <DropdownMenuItem
             testID="workspace-header-new-browser"
             leading={MENU_NEW_BROWSER_ICON}
-            onSelect={onCreateBrowser}
+            onSelect={handleCreateBrowser}
           >
             {t("workspace.header.actions.newBrowser")}
           </DropdownMenuItem>
@@ -298,7 +336,7 @@ export function WorkspaceHeaderMenuMobile({
             key={profile.id}
             profile={profile}
             disabled={createTerminalDisabled}
-            onCreateTerminalWithProfile={onCreateTerminalWithProfile}
+            onCreateTerminalWithProfile={handleCreateTerminalWithProfile}
           />
         ))}
         <DropdownMenuSeparator />
diff --git a/packages/app/src/screens/workspace/workspace-screen.tsx b/packages/app/src/screens/workspace/workspace-screen.tsx
index 68810013d7..2d6f2bfeac 100644
--- a/packages/app/src/screens/workspace/workspace-screen.tsx
+++ b/packages/app/src/screens/workspace/workspace-screen.tsx
@@ -1,3 +1,7 @@
+import {
+  AdaptiveWorkspaceChrome,
+  type WorkspaceCompactHeaderActions,
+} from "./adaptive-workspace-chrome";
 import { planTimelineTailFetch } from "@/timeline/timeline-sync-plan";
 import { useHostFeature } from "@/runtime/host-features";
 import {
@@ -148,6 +152,7 @@ import {
 } from "@/screens/workspace/use-workspace-tab-rename";
 import {
   WorkspaceDesktopTabsRow,
+  useWorkspaceNewTabKeyboardAction,
   type WorkspaceDesktopTabRowItem,
 } from "@/screens/workspace/workspace-desktop-tabs-row";
 import { useDesktopBrowserNewTabRequests } from "@/desktop/browser/new-tab-requests";
@@ -1808,8 +1813,8 @@ function WorkspaceScreenContent({
   });
 
   const handleCreateTerminalWithProfile = useCallback(
-    (profile: TerminalProfile) => {
-      createTerminal({ profile, destination: { kind: "open" } });
+    (profile: TerminalProfile, paneId?: string) => {
+      createTerminal({ profile, destination: { kind: "open", paneId } });
     },
     [createTerminal],
   );
@@ -3372,85 +3377,100 @@ function WorkspaceScreenContent({
       handleOpenUrlInBrowserTab,
     ],
   );
-  const workspaceTabSwitcher = useMemo(
-    () => (
-      <MobileWorkspaceTabSwitcher
-        tabs={tabs}
-        activeTabKey={activeTabKey}
-        normalizedServerId={normalizedServerId}
-        normalizedWorkspaceId={normalizedWorkspaceId}
-        onSelectSwitcherTab={handleSelectSwitcherTab}
-        createTerminalDisabled={createTerminalDisabled}
-        onCreateDraftTab={handleCreateDraftTab}
-        onCreateTerminal={handleCreateTerminal}
-        onCopyResumeCommand={handleCopyResumeCommand}
-        onCopyAgentId={handleCopyAgentId}
-        onCopyTerminalId={handleCopyTerminalId}
-        onCopyFilePath={handleCopyFilePath}
-        onReloadAgent={handleReloadAgent}
-        onRenameTab={handleRenameTab}
-        onCloseTab={handleCloseTabById}
-        onCloseTabsAbove={handleCloseTabsToLeft}
-        onCloseTabsBelow={handleCloseTabsToRight}
-        onCloseOtherTabs={handleCloseOtherTabs}
-      />
-    ),
-    [
-      activeTabKey,
-      createTerminalDisabled,
-      handleCloseOtherTabs,
-      handleCloseTabById,
-      handleCloseTabsToLeft,
-      handleCloseTabsToRight,
-      handleCopyAgentId,
-      handleCopyFilePath,
-      handleCopyResumeCommand,
-      handleCopyTerminalId,
-      handleCreateDraftTab,
-      handleCreateTerminal,
-      handleReloadAgent,
-      handleRenameTab,
-      handleSelectSwitcherTab,
-      normalizedServerId,
-      normalizedWorkspaceId,
-      tabs,
-    ],
-  );
-  const compactWorkspaceHeader = useMemo(
-    () => (
-      <CompactWorkspaceHeader
-        headerVariant={isMobile ? "compact" : "full"}
-        actionsActive={isRouteFocused && (!isMobile || workspacePanelActive)}
-        isLoading={isWorkspaceHeaderLoading}
-        title={workspaceHeaderTitle}
-        subtitle={workspaceHeaderSubtitle}
-        isSubtitleDistinct={isWorkspaceHeaderSubtitleDistinct}
-        serverId={normalizedServerId}
-        onToggleExplorer={handleToggleExplorerSidebar}
-        explorerToggleLabel={explorerSidebarToggleLabel}
-        explorerToggleAccessibilityState={explorerSidebarToggleAccessibilityState}
-        tabSwitcher={workspaceTabSwitcher}
-      >
-        <WorkspaceHeaderMenuMobile
+  const renderWorkspaceTabSwitcher = useCallback(
+    (
+      headerTabs: WorkspaceTabDescriptor[],
+      headerActiveTabKey: string,
+      actions: WorkspaceCompactHeaderActions,
+    ) => {
+      return (
+        <MobileWorkspaceTabSwitcher
+          paneId={actions.pane?.id}
+          tabs={headerTabs}
+          activeTabKey={headerActiveTabKey}
           normalizedServerId={normalizedServerId}
           normalizedWorkspaceId={normalizedWorkspaceId}
-          scripts={compactHeaderScripts}
-          currentBranchName={currentBranchName}
-          showWorkspaceSetup={showWorkspaceSetup}
-          showCreateBrowserTab={showCreateBrowserTab}
+          onSelectSwitcherTab={handleSelectSwitcherTab}
           createTerminalDisabled={createTerminalDisabled}
-          importAgentDisabled={!canOpenImportSheet}
-          copyPathDisabled={!workspaceDirectory}
-          onCreateTerminalWithProfile={handleCreateTerminalWithProfile}
-          onCreateBrowser={handleCreateBrowserTab}
-          onOpenImportSheet={openImportSheet}
-          onCopyWorkspacePath={handleCopyWorkspacePath}
-          onCopyBranchName={handleCopyBranchName}
-          onOpenSetupTab={handleOpenSetupTab}
+          onCreateDraftTab={handleCreateDraftTab}
+          onCreateTerminal={handleCreateTerminal}
+          onCopyResumeCommand={handleCopyResumeCommand}
+          onCopyAgentId={handleCopyAgentId}
+          onCopyTerminalId={handleCopyTerminalId}
+          onCopyFilePath={handleCopyFilePath}
+          onReloadAgent={handleReloadAgent}
+          onRenameTab={handleRenameTab}
+          onCloseTab={handleCloseTabById}
+          onCloseTabsAbove={actions.closeAbove}
+          onCloseTabsBelow={actions.closeBelow}
+          onCloseOtherTabs={actions.closeOthers}
         />
-      </CompactWorkspaceHeader>
-    ),
+      );
+    },
     [
+      normalizedServerId,
+      normalizedWorkspaceId,
+      handleSelectSwitcherTab,
+      createTerminalDisabled,
+      handleCreateDraftTab,
+      handleCreateTerminal,
+      handleCopyResumeCommand,
+      handleCopyAgentId,
+      handleCopyTerminalId,
+      handleCopyFilePath,
+      handleReloadAgent,
+      handleRenameTab,
+      handleCloseTabById,
+    ],
+  );
+  const renderCompactWorkspaceHeader = useCallback(
+    (
+      headerTabs: WorkspaceTabDescriptor[],
+      headerActiveTabKey: string,
+      actions: WorkspaceCompactHeaderActions,
+      actionsOnly = false,
+    ) => {
+      const tabSwitcher = renderWorkspaceTabSwitcher(headerTabs, headerActiveTabKey, actions);
+      return (
+        <CompactWorkspaceHeader
+          headerVariant={actionsOnly ? "full" : "compact"}
+          actionsActive={isRouteFocused && (!isMobile || workspacePanelActive)}
+          tabSwitcher={tabSwitcher}
+          isLoading={isWorkspaceHeaderLoading}
+          title={workspaceHeaderTitle}
+          subtitle={workspaceHeaderSubtitle}
+          isSubtitleDistinct={isWorkspaceHeaderSubtitleDistinct}
+          serverId={normalizedServerId}
+          onToggleExplorer={handleToggleExplorerSidebar}
+          explorerToggleLabel={explorerSidebarToggleLabel}
+          explorerToggleAccessibilityState={explorerSidebarToggleAccessibilityState}
+        >
+          <WorkspaceHeaderMenuMobile
+            pane={actions.pane}
+            onExitFocusMode={isFocusModeEnabled ? toggleFocusMode : undefined}
+            normalizedServerId={normalizedServerId}
+            normalizedWorkspaceId={normalizedWorkspaceId}
+            scripts={compactHeaderScripts}
+            currentBranchName={currentBranchName}
+            showWorkspaceSetup={showWorkspaceSetup}
+            showCreateBrowserTab={showCreateBrowserTab}
+            createTerminalDisabled={createTerminalDisabled}
+            importAgentDisabled={!canOpenImportSheet}
+            copyPathDisabled={!workspaceDirectory}
+            onCreateTerminalWithProfile={handleCreateTerminalWithProfile}
+            onCreateBrowser={handleCreateBrowserTab}
+            onOpenImportSheet={openImportSheet}
+            onCopyWorkspacePath={handleCopyWorkspacePath}
+            onCopyBranchName={handleCopyBranchName}
+            onOpenSetupTab={handleOpenSetupTab}
+          />
+        </CompactWorkspaceHeader>
+      );
+    },
+    [
+      renderWorkspaceTabSwitcher,
+      isFocusModeEnabled,
+      toggleFocusMode,
       canOpenImportSheet,
       compactHeaderScripts,
       createTerminalDisabled,
@@ -3476,9 +3496,23 @@ function WorkspaceScreenContent({
       workspaceHeaderSubtitle,
       workspaceHeaderTitle,
       workspacePanelActive,
-      workspaceTabSwitcher,
     ],
   );
+  const compactWorkspaceHeader = renderCompactWorkspaceHeader(tabs, activeTabKey, {
+    closeAbove: handleCloseTabsToLeft,
+    closeBelow: handleCloseTabsToRight,
+    closeOthers: handleCloseOtherTabs,
+  });
+  const fullWorkspaceActions = renderCompactWorkspaceHeader(
+    tabs,
+    activeTabKey,
+    {
+      closeAbove: handleCloseTabsToLeft,
+      closeBelow: handleCloseTabsToRight,
+      closeOthers: handleCloseOtherTabs,
+    },
+    true,
+  );
   const desktopSplitContent = useMemo(() => {
     if (!canRenderDesktopPaneSplits || !workspaceLayout || !persistenceKey) {
       return null;
@@ -3487,6 +3521,7 @@ function WorkspaceScreenContent({
       <SplitContainer
         layout={workspaceLayout}
         renderMainHeader={renderWorkspaceScreenHeader}
+        renderCompactHeader={renderCompactWorkspaceHeader}
         focusModeEnabled={desktopFocusModeEnabled}
         onExitFocusMode={toggleFocusMode}
         workspaceKey={persistenceKey}
@@ -3523,6 +3558,7 @@ function WorkspaceScreenContent({
     canRenderDesktopPaneSplits,
     workspaceLayout,
     renderWorkspaceScreenHeader,
+    renderCompactWorkspaceHeader,
     persistenceKey,
     desktopFocusModeEnabled,
     toggleFocusMode,
@@ -3561,6 +3597,22 @@ function WorkspaceScreenContent({
     [uiTabs, sheets],
   );
   const workspacePanelKey = `${normalizedServerId}:${normalizedWorkspaceId}`;
+  const createFallbackTab = useCallback(
+    () => handleCreateNewTab({ paneId: focusedPaneIdOrUndefined }),
+    [handleCreateNewTab, focusedPaneIdOrUndefined],
+  );
+  const ownsFallbackKeyboardShortcuts = useMemo(
+    () => shouldRenderDesktopPaneFallback && isRouteFocused,
+    [shouldRenderDesktopPaneFallback, isRouteFocused],
+  );
+  useWorkspaceNewTabKeyboardAction({
+    handlerName: "workspace-chrome-new-tab",
+    ownsKeyboardShortcuts: ownsFallbackKeyboardShortcuts,
+    normalizedServerId,
+    normalizedWorkspaceId,
+    paneId: focusedPaneIdOrUndefined,
+    createNewTab: createFallbackTab,
+  });
   const compactHeaderLayout = resolveCompactHeaderLayout({
     header: compactWorkspaceHeader,
     activeTab: activeTabDescriptor,
@@ -3584,37 +3636,41 @@ function WorkspaceScreenContent({
     </View>
   ) : (
     <View style={styles.centerColumn}>
-      {compactWorkspaceHeader}
-      {rendersDesktopSplitContent ? null : renderWorkspaceScreenHeader()}
-
-      {shouldRenderDesktopPaneFallback ? (
-        <NewTabLauncherProvider value={newTabLauncher}>
-          <WorkspaceDesktopTabsRow
-            paneId={focusedPaneIdOrUndefined}
-            isFocused={isRouteFocused}
-            tabs={desktopTabRowItems}
-            normalizedServerId={normalizedServerId}
-            normalizedWorkspaceId={normalizedWorkspaceId}
-            setHoveredCloseTabKey={setHoveredCloseTabKey}
-            onNavigateTab={navigateToTabId}
-            onCloseTab={handleCloseTabById}
-            onCopyResumeCommand={handleCopyResumeCommand}
-            onCopyAgentId={handleCopyAgentId}
-            onCopyTerminalId={handleCopyTerminalId}
-            onCopyFilePath={handleCopyFilePath}
-            onReloadAgent={handleReloadAgent}
-            onRenameTab={handleRenameTab}
-            onCloseTabsToLeft={handleCloseTabsToLeft}
-            onCloseTabsToRight={handleCloseTabsToRight}
-            onCloseOtherTabs={handleCloseOtherTabs}
-            onCreateNewTab={handleCreateNewTab}
-            onReorderTabs={handleReorderTabsInFocusedPane}
-            focusModeEnabled={desktopFocusModeEnabled}
-            onExitFocusMode={toggleFocusMode}
-          />
-        </NewTabLauncherProvider>
-      ) : null}
+      {rendersDesktopSplitContent ? null : (
+        <AdaptiveWorkspaceChrome compactHeader={compactWorkspaceHeader}>
+          {fullWorkspaceActions}
+          {renderWorkspaceScreenHeader()}
 
+          {shouldRenderDesktopPaneFallback ? (
+            <NewTabLauncherProvider value={newTabLauncher}>
+              <WorkspaceDesktopTabsRow
+                paneId={focusedPaneIdOrUndefined}
+                ownsKeyboardShortcuts={false}
+                isFocused={isRouteFocused}
+                tabs={desktopTabRowItems}
+                normalizedServerId={normalizedServerId}
+                normalizedWorkspaceId={normalizedWorkspaceId}
+                setHoveredCloseTabKey={setHoveredCloseTabKey}
+                onNavigateTab={navigateToTabId}
+                onCloseTab={handleCloseTabById}
+                onCopyResumeCommand={handleCopyResumeCommand}
+                onCopyAgentId={handleCopyAgentId}
+                onCopyTerminalId={handleCopyTerminalId}
+                onCopyFilePath={handleCopyFilePath}
+                onReloadAgent={handleReloadAgent}
+                onRenameTab={handleRenameTab}
+                onCloseTabsToLeft={handleCloseTabsToLeft}
+                onCloseTabsToRight={handleCloseTabsToRight}
+                onCloseOtherTabs={handleCloseOtherTabs}
+                onCreateNewTab={handleCreateNewTab}
+                onReorderTabs={handleReorderTabsInFocusedPane}
+                focusModeEnabled={desktopFocusModeEnabled}
+                onExitFocusMode={toggleFocusMode}
+              />
+            </NewTabLauncherProvider>
+          ) : null}
+        </AdaptiveWorkspaceChrome>
+      )}
       <View style={styles.centerContent}>
         <View style={styles.content}>{desktopContent}</View>
       </View>
diff --git a/packages/app/src/screens/workspace/workspace-tab-layout.test.ts b/packages/app/src/screens/workspace/workspace-tab-layout.test.ts
index 7c7b98cee0..9b428bc0bc 100644
--- a/packages/app/src/screens/workspace/workspace-tab-layout.test.ts
+++ b/packages/app/src/screens/workspace/workspace-tab-layout.test.ts
@@ -1,3 +1,4 @@
+import { buildDesktopFrameStyle } from "@/components/ui/combobox-frame-style";
 import {
   WorkspaceHeaderExplorerToggle,
   WorkspaceExplorerSidebarToggle,
@@ -7,6 +8,8 @@ import { SidebarCloseButton } from "@/components/headers/sidebar-close-button";
 import { resolveWorkspaceTabChipBackdrop } from "@/screens/workspace/workspace-tab-chip-backdrop";
 import { darkPureBlackTheme, darkTheme, lightTheme } from "@/styles/theme";
 import {
+  workspaceTabSwitcherPopoverLayout,
+  selectWorkspaceChrome,
   computeWorkspaceTabLayout,
   retainWorkspaceTabMeasuredWidth,
 } from "@/screens/workspace/workspace-tab-layout";
@@ -256,3 +259,37 @@ describe("resolveWorkspaceTabChipBackdrop", () => {
     ).toBe("surface0");
   });
 });
+
+import { shouldUseCompactWorkspaceHeader } from "./workspace-tab-layout";
+it.each([
+  [349, true],
+  [499, true],
+  [500, false],
+  [800, false],
+])("workspace width %s selects compact=%s", (width, compact) => {
+  expect(shouldUseCompactWorkspaceHeader(width)).toBe(compact);
+});
+
+describe("desktop pane chrome", () => {
+  it("replaces the pane header and rail together at the pane width boundary", () => {
+    const full = ["workspace header", "pane tab rail"];
+    expect(selectWorkspaceChrome({ width: 440, compact: "pane dropdown", full })).toBe(
+      "pane dropdown",
+    );
+    expect(selectWorkspaceChrome({ width: 500, compact: "pane dropdown", full })).toBe(full);
+    expect(selectWorkspaceChrome({ width: null, compact: "pane dropdown", full })).toBe(full);
+  });
+});
+
+it("gives the tab switcher a readable popover width independent of its 16pt count badge", () => {
+  const frame = buildDesktopFrameStyle({
+    desktopMinWidth: workspaceTabSwitcherPopoverLayout.desktopMinWidth,
+    desktopLockWidth: false,
+    referenceWidth: 16,
+    desktopFixedHeight: undefined,
+    desktopPositionStyle: {},
+    shouldHideDesktopContent: false,
+    availableHeight: 600,
+  }) as Array<{ minWidth?: number }>;
+  expect(frame[0].minWidth).toBeGreaterThanOrEqual(320);
+});
diff --git a/packages/app/src/screens/workspace/workspace-tab-layout.ts b/packages/app/src/screens/workspace/workspace-tab-layout.ts
index cb89d9c54c..2a9ec47837 100644
--- a/packages/app/src/screens/workspace/workspace-tab-layout.ts
+++ b/packages/app/src/screens/workspace/workspace-tab-layout.ts
@@ -1,3 +1,9 @@
+import { COMPACT_CONTENT_WIDTH } from "@/constants/layout";
+
+export function shouldUseCompactWorkspaceHeader(width: number): boolean {
+  return width < COMPACT_CONTENT_WIDTH;
+}
+
 export type WorkspaceTabCloseButtonPolicy = "all" | "none";
 
 export interface WorkspaceTabLayoutMetrics {
@@ -120,3 +126,16 @@ export function computeWorkspaceTabLayout(
     requiresHorizontalScrollFallback,
   };
 }
+
+export function selectWorkspaceChrome<Compact, Full>(input: {
+  width: number | null;
+  compact: Compact;
+  full: Full;
+}): Compact | Full {
+  const compact = input.width !== null && shouldUseCompactWorkspaceHeader(input.width);
+  return compact ? input.compact : input.full;
+}
+
+// A count badge is only 16pt wide. Native popovers need a content width floor
+// because their scrolling tab list does not contribute an intrinsic width.
+export const workspaceTabSwitcherPopoverLayout = { desktopMinWidth: 320 } as const;
diff --git a/packages/app/src/terminal/runtime/terminal-glyph-rendering.browser.test.ts b/packages/app/src/terminal/runtime/terminal-glyph-rendering.browser.test.ts
index 62a65c6878..5b1e875b44 100644
--- a/packages/app/src/terminal/runtime/terminal-glyph-rendering.browser.test.ts
+++ b/packages/app/src/terminal/runtime/terminal-glyph-rendering.browser.test.ts
@@ -160,6 +160,8 @@ it("preserves another terminal's glyph pixels when a shared atlas is cleared", a
   expectSamePixels({ expected: before, actual: after, label: "sibling after atlas clear" });
 });
 
+// Software WebGL can take over 30 seconds for this corpus on a contended runner.
+// Each capture still has its own two-second render deadline.
 it("preserves both headers while ordinary output grows the shared glyph atlas", async () => {
   const { active, sibling } = await mountPair();
   const cells = active.terminal.cols * (active.terminal.rows - 2);
@@ -199,4 +201,4 @@ it("preserves both headers while ordinary output grows the shared glyph atlas",
       label: `sibling frame ${batch}`,
     });
   }
-}, 30000);
+}, 60_000);
diff --git a/packages/app/src/utils/desktop-window.test.ts b/packages/app/src/utils/desktop-window.test.ts
index aa95a90dbf..21f35537dc 100644
--- a/packages/app/src/utils/desktop-window.test.ts
+++ b/packages/app/src/utils/desktop-window.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 import {
   intersectWindowChromeCorners,
+  resolveChildWindowChromeCorners,
   resolveHasOwnedWindowChromeObstruction,
   resolveWindowChromeObstruction,
   resolveWindowChromeSafeArea,
@@ -87,3 +88,54 @@ describe("window chrome", () => {
     ).toBe(false);
   });
 });
+
+it("assigns window buttons only to exposed split edges", () => {
+  expect(
+    resolveChildWindowChromeCorners({
+      corners: "both",
+      direction: "horizontal",
+      isFirst: true,
+      isLast: false,
+    }),
+  ).toBe("top-left");
+  expect(
+    resolveChildWindowChromeCorners({
+      corners: "both",
+      direction: "horizontal",
+      isFirst: false,
+      isLast: true,
+    }),
+  ).toBe("top-right");
+  expect(
+    resolveChildWindowChromeCorners({
+      corners: "both",
+      direction: "horizontal",
+      isFirst: false,
+      isLast: false,
+    }),
+  ).toBe("none");
+  expect(
+    resolveChildWindowChromeCorners({
+      corners: "both",
+      direction: "vertical",
+      isFirst: true,
+      isLast: false,
+    }),
+  ).toBe("both");
+  expect(
+    resolveChildWindowChromeCorners({
+      corners: "both",
+      direction: "vertical",
+      isFirst: false,
+      isLast: true,
+    }),
+  ).toBe("none");
+  expect(
+    resolveChildWindowChromeCorners({
+      corners: "top-right",
+      direction: "horizontal",
+      isFirst: true,
+      isLast: true,
+    }),
+  ).toBe("top-right");
+});
diff --git a/packages/app/src/utils/desktop-window.tsx b/packages/app/src/utils/desktop-window.tsx
index adc3f7c9a1..fa1f397e1c 100644
--- a/packages/app/src/utils/desktop-window.tsx
+++ b/packages/app/src/utils/desktop-window.tsx
@@ -83,6 +83,19 @@ export function intersectWindowChromeCorners(
   );
 }
 
+export function resolveChildWindowChromeCorners(input: {
+  corners: WindowChromeCorners;
+  direction: "horizontal" | "vertical";
+  isFirst: boolean;
+  isLast: boolean;
+}): WindowChromeCorners {
+  if (input.direction === "vertical") return input.isFirst ? input.corners : "none";
+  return intersectWindowChromeCorners(
+    input.corners,
+    windowChromeCornersFromFlags(input.isFirst, input.isLast),
+  );
+}
+
 export function removeWindowChromeCorner(
   corners: WindowChromeCorners,
   corner: WindowChromeCorner,

From 0e7f452c2f6c6286a72a558caed8f23bdee5427c Mon Sep 17 00:00:00 2001
From: "paseo-bot[bot]" <266920839+paseo-bot[bot]@users.noreply.github.com>
Date: Wed, 4 Nov 2026 12:25:42 +0000
Subject: [PATCH 07/29] Keep duplicate-path setup out of the Git filter CI
 budget (#8753)

* test(server): prepare duplicate paths before measuring Git filtering

* test(server): clarify the observer path preparation boundary

---------

Co-authored-by: paseo-bot[bot] <266920839+paseo-bot[bot]@users.noreply.github.com>
---
 ...ace-git-service.observation.integration.test.ts | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/packages/server/src/server/workspace-git-service.observation.integration.test.ts b/packages/server/src/server/workspace-git-service.observation.integration.test.ts
index 26d47918b7..17e3a4a2af 100644
--- a/packages/server/src/server/workspace-git-service.observation.integration.test.ts
+++ b/packages/server/src/server/workspace-git-service.observation.integration.test.ts
@@ -624,7 +624,10 @@ test("Git refresh, command tracing and 10,000 ignored alias events do no synchro
       await writeFile(join(worktree, 'ignored', 'noise'), 'noise');
       await symlink(worktree, alias, process.platform === 'win32' ? 'junction' : 'dir');
       const subscription = await service.requestWorkingTreeWatch(alias, () => { notifications++; });
-      const events = Array.from({ length: process.env.GIT_IO_TRACE ? 2 : 10000 }, (_, i) => ({ type: 'update', path: join(i % 2 ? alias : worktree, 'ignored', 'noise') }));
+      // The observer hashes and coalesces paths in a Map before delivery. Reuse
+      // two prepared strings instead of constructing 10,000 equal-valued strings.
+      const noisePaths = [join(worktree, 'ignored', 'noise'), join(alias, 'ignored', 'noise')];
+      const events = Array.from({ length: process.env.GIT_IO_TRACE ? 2 : 10000 }, (_, i) => ({ type: 'update', path: noisePaths[i % 2] }));
       let fsCalls = 0;
       const hook = createHook({ init(_id, type) { if (type.startsWith('FSREQ')) fsCalls++; } });
       // Collect repository setup and event-fixture garbage before measuring
@@ -648,15 +651,18 @@ test("Git refresh, command tracing and 10,000 ignored alias events do no synchro
       assert.equal(unrelatedWorkStarted, false, 'control work must not contaminate the cold filter');
       hook.enable();
       let blockingMs;
+      let elapsedMs;
+      let cpu;
       try {
         // This callback is synchronous: measure its own span, without waiting
         // for marker IO, loader messages or other event-loop callbacks.
         const startedAt = performance.now();
         const startedCpu = threadCpuUsage();
         callback(null, events);
-        const cpu = threadCpuUsage(startedCpu);
+        cpu = threadCpuUsage(startedCpu);
         // Cap coarse Windows CPU accounting by elapsed time; exclude descheduling.
-        blockingMs = Math.min(performance.now() - startedAt, (cpu.user + cpu.system) / 1000);
+        elapsedMs = performance.now() - startedAt;
+        blockingMs = Math.min(elapsedMs, (cpu.user + cpu.system) / 1000);
       } finally {
         hook.disable();
         await marker('FILTER_END');
@@ -665,7 +671,7 @@ test("Git refresh, command tracing and 10,000 ignored alias events do no synchro
       assert.equal(unrelatedWorkStarted, true, 'control work must run outside the filter span');
       assert.equal(fsCalls, 0, "filesystem calls");
       assert.equal(notifications, 0, "ignored event notification");
-      assert.ok(blockingMs < 20, 'blocking filter work: ' + blockingMs);
+      assert.ok(blockingMs < 20, 'blocking filter work: ' + JSON.stringify({ blockingMs, elapsedMs, cpu }));
       console.log(JSON.stringify({ blockingMs, fsCalls }));
       // Alias identity remains useful after deletion: no per-event realpath can recover this file.
       callback(null, [{ type: 'delete', path: join(worktree, 'tracked.txt') }]);

From ac775a29042751318c10e6415ff051e1fe3768c8 Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Wed, 4 Nov 2026 19:30:39 +0700
Subject: [PATCH 08/29] Reveal collapsed navigation as a touch overlay on wide
 layouts (#8739)

* feat(app): swipe open collapsed tablet navigation

Reuse the retained sidebar and mobile panel motion for a partial-width
navigation overlay when the wide dock is hidden. Preserve the dock
preference, project gestures through the sidebar width, and dismiss the
overlay when revealing workspace content.

Reset the animated frame width explicitly across dock transitions and
keep the resize origin on the UI thread.

Validated on Duo portrait and landscape, iPad portrait and landscape,
iPhone full-width navigation, and browser sidebar interactions.
Typecheck, lint, targeted formatting, and 31 relevant tests passed.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): refine touch navigation overlays

Enable navigation swipes only on touch-capable runtimes and reject mouse
and pen input per gesture event. Allow swiping from anywhere in the
workspace instead of requiring an edge start.

Cover the full application window with the backdrop, including safe-area
padding, and remove the wide overlay's inline close button. Preserve
swipe, backdrop, and destination-selection dismissal.

Validated interior swipes on Duo and iPad, mouse exclusion in a browser,
and full-window dimming and dismissal in Duo portrait and landscape.
Typecheck, lint, and targeted formatting passed.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* refactor(app): let the panel store drop the overlay target on dock

Docking the sidebar, or any layout that no longer presents it as an
overlay, now drops the transient agent-list target inside the panel
store. App chrome publishes one left sidebar presentation (overlay,
dock, hidden) instead of an effect in SidebarChrome watching flags.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* refactor(app): answer fine pointer and touch screen from one module

Merge use-fine-pointer and use-has-touch-screen into
hooks/pointer-capabilities, which reads both answers from the media
queries it subscribes to. The touch answer now comes from
(any-pointer: coarse) instead of navigator.maxTouchPoints, which that
query's change events never reported.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): keep the phone web drawer on its edge swipe

Restore the 32px left-edge start for the compact web navigation drawer,
so interior rightward swipes over terminals, code blocks, and diffs stay
with their horizontal scrollers. The wide navigation overlay still opens
from anywhere. The edge rule moves into resolveMobilePanelGestureIntent
so both drawers share it and it has a test.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* refactor(app): one sidebar handler per destination

Settings, host settings, add host, add project, and every navigation
row now use one handler that closes the navigation overlay before it
navigates. Closing is idempotent, so the docked sidebar shares it and
the overlay ? mobile : desktop handler pairs go away.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* refactor(app): resolve the left panel width in one place

MobilePanelsProvider now resolves the left sidebar width (full window
on compact, the saved width clamped to the safe viewport on wide) and
exposes it through the panel runtime. The open and close gestures, the
overlay frame, and the docked sidebar all read that value, so gesture
travel and panel width cannot disagree. MobileGestureWrapper no longer
recomputes it, and the panelWidth/width parameters go away.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* docs: fold the wide navigation overlay into the mobile panel rules

Move the facts the overlay PR appended into the sections that own them:
the destinations intro, store ownership of the agent-list target, the
projection widths, gesture pointer and edge rules, and the sidebar
presentation bullets.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): keep the sidebar pans live across dock and overlay switches

On an Android tablet, opening the dock with the header toggle and collapsing
it again left the touch swipe unable to open the overlay until the app
reloaded. Swipe-to-close from the sidebar also stopped working after the
same toggle cycle.

Both pans took the dock/overlay state through RNGH's `.enabled()`. On
Android, RNGH 2.32 cancels the native handler when `isEnabled` changes and
resets its config on every update. After a false -> true flip the handler
stayed inert. `.enabled()` now carries only the device capability (touch
screen present), which does not change at runtime. The dock/overlay state
moves to a UI-thread derived value that fails the gesture in
onTouchesDown, next to the existing non-touch pointer check.

The wide sidebar's workspace list now always receives the close gesture
ref, as the compact sidebar already does. Toggling it between undefined
and the ref rewired the list's simultaneous handlers on every dock switch,
and that also left the close pan dead after a toggle cycle.

This is a native RNGH handler behavior, so there is no unit repro. It was
verified on the Android fold emulator: toggle open, toggle closed, swipe
opens the overlay, swipe on an empty sidebar strip closes it, no reload.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): keep the workspace full width after collapsing the dock

On an Android tablet, opening the dock with the header toggle and
collapsing it again could leave the workspace at the docked width, with a
blank strip on the right, until the overlay was next opened. Elsa's
original head showed the same.

The sidebar's panel host flips between an in-flow dock and an absolute
overlay. Its width came from a Reanimated style that read the React
`overlay` flag, so the width reached the native view on the UI thread
after React had already committed the new presentation. Layout logs on
the fold emulator show the lag on every toggle-open: the workspace laid
out at width 0 while the docked host still had the overlay's full window
width, then a second pass laid out the 320dp dock. When the late update
was lost on collapse, the workspace kept its dock width.

The host no longer has a width of its own:
- The dock sizes to the inner sidebar view, which already carries the
  animated resize width.
- The overlay host is absoluteFill, which covers the whole row including
  the safe-area padding.

With no animated layout prop on the host, a presentation switch is one
React commit, and the host and the workspace lay out in the same pass.

Device evidence on the fold emulator:
- Toggle open and collapse cycles: the host and the workspace lay out
  together (320/521dp, then 841/841dp).
- A swipe opens the 320dp overlay with a full-window backdrop, and a
  swipe on the sidebar closes it.
- Dragging the dock edge still resizes the dock and the workspace
  together.

There is no unit repro: the defect is the ordering of Reanimated's
UI-thread layout updates against React commits.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): cancel pending sidebar swipes when docking

An opening swipe still has the agent target until release. Leaving overlay presentation must advance its revision even then, so motion ownership and queued commits reject the obsolete swipe.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): keep mouse selection free of the touch-only pan's capture

On a touch-capable browser the navigation pan registers pointer listeners
over the whole workspace. Gesture Handler's web pointer manager captured
the pressed element before the handler saw the pointer, and captured it
again on every move, so a mouse drag that the pan rejects stayed captured
and the browser's selection stopped at the starting paragraph.

The patched manager now captures after pointer-down, and only a pointer the
handler still tracks. The resize handle and touch swipes keep capturing.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): drop the compact Explorer target when the layout widens

Opening the Explorer on a compact layout selects the `file-explorer` mobile panel target. Widening
the window (unfolding a foldable, rotating a tablet) kept that target, because the store only
heard the left sidebar presentation, which is `overlay` on both compact layouts and wide layouts
with a collapsed dock. The navigation swipe begins only from `agent`, so on the wide layout every
swipe was rejected until something else reset the target.

App chrome now publishes the whole panel layout (compact or wide, plus the left sidebar
presentation) and the store drops any target that layout does not present.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): keep wide overlay sidebar content inside the left safe area

The overlay starts at the window's left edge, over the workspace's
safe-area padding, so its content now takes the left inset itself. The
dock already sits inside app chrome's padding and stays unchanged.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): return an interrupted swipe to its anchor when docking cancels it

Docking mid-swipe bumps the panel revision while keeping the agent
target. The command treated the unchanged target as motion already in
progress and skipped the animation, leaving the dragged position
stranded between anchors. A command that interrupts a drag now always
animates to its target.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): synchronize startup panel selection and gate pending swipes

A child layout effect can publish panel layout before the motion provider subscribes. Establish the current selection when subscribing, then observe later commands. Recheck presentation eligibility before gesture activation so docking also cancels touches that have not started dragging.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* test(app): cover panel subscription through its public contract

Verify initial snapshot delivery, later commands, and unsubscription directly in the existing panel-store suite instead of mounting test-only React components.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* test(app): reopen compact navigation after leaving settings

Destination navigation clears the transient overlay selection. Reopen the compact drawer before asserting its configured footer rather than relying on a stale open target surviving a wide layout.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* test(app): open navigation by keyboard in composer focus checks

Navigation pans intentionally reject mouse drags. Use the keyboard sidebar command to exercise focus and fullscreen Escape behavior without relying on the former mouse swipe helper.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): complete sidebar integration after main rebase

Retain the resize width resolver and format the shared division-width and hybrid touch-sizing integration.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* test(desktop): give split browser panes room for tab rails

After #8740, narrow panes replace tab rails with compact dropdowns. The desktop browser journey counts and selects rail tabs, so widen the real Electron content window before splitting instead of treating missing narrow-pane rails as missing panes.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

---------

Co-authored-by: Elsa <zeyugao@outlook.com>
---
 docs/mobile-panels.md                         |  49 ++-
 .../browser/assistant-selection-copy.spec.ts  |  43 +++
 .../app/e2e/browser/composer-focus.spec.ts    |   4 +-
 .../e2e/browser/composer-whitespace.spec.ts   |   6 +-
 .../e2e/browser/sidebar-nav-settings.spec.ts  |   1 +
 packages/app/e2e/support/helpers/sidebar.ts   |  13 +-
 packages/app/src/app/_layout.tsx              |  38 ++-
 .../components/desktop-sidebar-layout.test.ts |  41 +++
 .../src/components/desktop-sidebar-layout.ts  |  33 +-
 packages/app/src/components/left-sidebar.tsx  | 286 +++++++++---------
 packages/app/src/components/resize-handle.tsx |   4 +-
 .../src/components/sidebar-resize-handle.tsx  |   4 +-
 .../app/src/components/ui/control-sizing.ts   |   2 +-
 packages/app/src/composer/index.tsx           |   4 +-
 packages/app/src/composer/input/input.tsx     |   2 +-
 .../src/hooks/pointer-capabilities.test.ts    |  77 +++++
 .../app/src/hooks/pointer-capabilities.ts     |  88 ++++++
 packages/app/src/hooks/use-fine-pointer.ts    |  50 ---
 .../src/mobile-panels/gesture-intent.test.ts  |  68 +++++
 .../app/src/mobile-panels/gesture-intent.ts   |  27 +-
 packages/app/src/mobile-panels/gestures.ts    |  72 +++--
 packages/app/src/mobile-panels/model.test.ts  |  27 ++
 packages/app/src/mobile-panels/model.ts       |   4 +-
 .../app/src/mobile-panels/presentation.tsx    |  15 +-
 packages/app/src/mobile-panels/provider.tsx   |  48 ++-
 packages/app/src/mobile-panels/selection.ts   |  14 +
 .../index.ts                                  |   4 +-
 packages/app/src/stores/panel-store/index.ts  |  44 ++-
 .../app/src/stores/panel-store/state.test.ts  | 102 ++++++-
 packages/app/src/stores/panel-store/state.ts  |  37 +++
 .../app/src/workspace-tabs/navigation.test.ts |  22 ++
 packages/app/src/workspace-tabs/navigation.ts |   9 +-
 packages/desktop/e2e/browser-tabs.e2e.mjs     |   4 +
 .../react-native-gesture-handler+2.32.0.patch | 120 +++++++-
 scripts/postinstall-patches.mjs               |   3 +
 35 files changed, 1065 insertions(+), 300 deletions(-)
 create mode 100644 packages/app/src/hooks/pointer-capabilities.test.ts
 create mode 100644 packages/app/src/hooks/pointer-capabilities.ts
 delete mode 100644 packages/app/src/hooks/use-fine-pointer.ts
 create mode 100644 packages/app/src/mobile-panels/selection.ts

diff --git a/docs/mobile-panels.md b/docs/mobile-panels.md
index 3301b4b60a..21849788d2 100644
--- a/docs/mobile-panels.md
+++ b/docs/mobile-panels.md
@@ -9,6 +9,10 @@ Compact layouts have three mutually exclusive destinations:
 They are one interaction, not two independent drawers. The implementation lives in
 `packages/app/src/mobile-panels/`.
 
+Wide layouts reuse `agent-list` for the navigation overlay. When the left dock is collapsed or
+yields its width, a touch swipe reveals the same sidebar over the workspace at the resolved sidebar
+width. The workspace does not move, and the saved dock preference does not change.
+
 ## Ownership
 
 React/Zustand owns the durable intent:
@@ -23,6 +27,12 @@ interface MobilePanelSelection {
 Every semantic target change increments `revision`. Repeating the current target is idempotent.
 Compact panel selection is not persisted; a cold start begins at `agent`.
 
+Only an overlay sidebar holds `agent-list`, and only a compact layout holds `file-explorer`. App
+chrome publishes the layout (compact or wide, and the left sidebar presentation `overlay`, `dock`, or
+`hidden`) to `panel-store`, which drops any target the layout does not present. A stale
+`agent-list` would reopen the overlay on the next collapse; a stale `file-explorer` after widening
+would block the navigation swipe, which begins only from `agent`.
+
 The UI worklet owns transient motion:
 
 - one normalized position (`-1` left, `0` center, `1` right)
@@ -32,8 +42,10 @@ The UI worklet owns transient motion:
 
 React publishes the active panel only when the canonical target and the UI-thread position agree at
 the final anchor. Retained content never observes gesture previews, progress, or an unsettled target.
-The gesture hosts stay mounted. The Gesture Handler web patch keeps initially disabled hosts
-from capturing paragraph pointers; that capture confines browser selection to its starting paragraph.
+The gesture hosts stay mounted. A pointer capture on a paragraph confines browser selection to that
+paragraph, so the Gesture Handler web patch keeps it off: initially disabled hosts register no
+pointer listeners, and an enabled host captures only a pointer its handler still tracks after
+pointer-down. The touch-only navigation pans fail a mouse at pointer-down and never capture it.
 Native worklets own overlay opacity and pointer events while
 React owns settled panel activity and accessibility. Keep hidden native overlays laid out: collapsing
 their scroll ranges makes Android spring retained offsets back to zero during touch cancellation or
@@ -43,8 +55,11 @@ appearance keys; see [Unistyles appearance boundaries](unistyles.md#runtime-them
 
 ## Why one position
 
-Both transforms and both backdrop opacities are derived from the same normalized position. Window
-width is only a projection input. Rotation changes the projection, not the panel state.
+Both transforms and both backdrop opacities are derived from the same normalized position. Panel
+width is only a projection input: the window width on the right, and on the left the width
+`MobilePanelsProvider` resolves (the full window on compact layouts, the saved sidebar width
+clamped to the viewport on wide ones). The dock, the overlay, and their gestures read that one
+value. Rotation changes the projection, not the panel state.
 
 This makes these invalid states unrepresentable:
 
@@ -62,7 +77,9 @@ A gesture captures the current revision when it becomes active. Per-frame update
 while that revision still owns the gesture.
 
 When a React command arrives during a drag, its newer revision clears gesture ownership and starts
-motion toward the new target. The older gesture's remaining updates and finish callback are ignored.
+motion toward its target, even an unchanged one: docking mid-swipe keeps `agent` and still returns
+the dragged position to its anchor. The older gesture's remaining updates and finish callback are
+ignored.
 Canceled gestures return to the latest canonical target. A successful gesture starts its finishing
 motion immediately; the matching React command adopts that motion instead of restarting it. Position
 settlement and command acceptance may arrive in either order. Activity changes after both agree on
@@ -80,6 +97,12 @@ definition, no longer eligible to begin.
 
 - Callers request semantic targets through `panel-store`; they never write shared values.
 - Gesture behavior comes from the four explicit hooks in `mobile-panels/gestures.ts`.
+- Navigation gestures accept touch pointers only. Mouse and pen fail at touch-down, so dragging a
+  mouse to select text on a hybrid laptop never moves a panel. Browsers without a touch screen
+  (`hooks/pointer-capabilities`) never enable them.
+- Phone web opens a drawer only from the 32px edge it slides in from, so interior swipes stay with
+  terminals, code blocks, and diff scrollers. Native drawers and the wide overlay open from anywhere.
+  Horizontal-scroll ownership and the open-gesture blocker still take precedence.
 - A focused interactive surface may block panel-opening gestures through
   `useBlockMobilePanelOpenGestures`. Register only while the conflicting interaction is active and
   unregister when the surface is hidden or unfocused. The blocker never disables gestures that close
@@ -87,11 +110,17 @@ definition, no longer eligible to begin.
 - Keep `SidebarModelProvider` outside `MobileGestureWrapper`. The provider shares sidebar derivation
   across consumers, while Gesture Handler requires the wrapper's direct child to be a native `View`
   so its injected `collapsable={false}` reaches Android/Fabric.
-- Mobile sidebars render through `MobilePanelOverlay`; do not duplicate overlay lifecycle or motion
-  styles in sidebar components.
-- The desktop left sidebar is retained too. App chrome owns separate mounted and visible decisions:
-  closing it or yielding its width marks it inactive and applies `display: none` without conditionally
-  removing the sidebar tree.
+- Sidebars render through `MobilePanelOverlay`; do not duplicate overlay lifecycle or motion styles
+  in sidebar components. The wide left sidebar keeps the same content and gesture hosts when switching
+  between dock and overlay. App chrome owns mounting and presentation; settled panel activity owns
+  overlay work. A hidden dock is inactive with `display: none`; the sidebar tree stays mounted. Keep
+  the native overlay laid out while hidden, as on compact layouts. Give the switching host no
+  Reanimated layout props: a width keyed on the presentation reaches Android after React commits the
+  switch, and a lost update left the workspace at the dock width. The dock sizes to its content and
+  the overlay host fills the window.
+- The overlay's backdrop covers the whole window; safe-area padding applies to the sidebar and
+  workspace content only. It closes by swiping back, tapping the backdrop, or picking a destination:
+  every sidebar destination closes the overlay before it navigates.
 - Animated panel nodes use React Native static styles plus inline theme values. Do not attach
   Unistyles-generated styles to those nodes; Unistyles and Reanimated patching the same Fabric node
   has caused native crashes.
diff --git a/packages/app/e2e/browser/assistant-selection-copy.spec.ts b/packages/app/e2e/browser/assistant-selection-copy.spec.ts
index 7daa11c7d6..81f89290c7 100644
--- a/packages/app/e2e/browser/assistant-selection-copy.spec.ts
+++ b/packages/app/e2e/browser/assistant-selection-copy.spec.ts
@@ -723,3 +723,46 @@ test("copying a selection across an assistant image keeps its Markdown source an
     await agent.cleanup();
   }
 });
+
+test.describe("on a touch-capable desktop browser", () => {
+  // A touch screen registers the navigation pan's pointer listeners over the whole workspace.
+  // The pan accepts touch only, and a mouse drag must still extend the browser's selection.
+  test.use({ hasTouch: true });
+
+  test("a mouse drag selects across assistant paragraphs", async ({ page }) => {
+    const agent = await seedMockAgentWorkspace({
+      repoPrefix: "assistant-selection-drag-",
+      title: "Assistant selection drag",
+      initialPrompt: "Render three paragraphs.",
+      featureValues: {
+        mockAssistantResponse: "First paragraph.\n\nSecond paragraph.\n\nThird paragraph.",
+      },
+    });
+
+    try {
+      await agent.client.waitForAgentUpsert(
+        agent.agentId,
+        (snapshot) => snapshot.status === "idle",
+        30_000,
+      );
+      await openAgentRoute(page, agent);
+      const blocks = assistantMessageBlocks(page);
+      const first = await blocks.getByText("First paragraph.").boundingBox();
+      const third = await blocks.getByText("Third paragraph.").boundingBox();
+      if (!first || !third) {
+        throw new Error("Expected rendered paragraphs");
+      }
+
+      await page.mouse.move(first.x + 1, first.y + first.height / 2);
+      await page.mouse.down();
+      await page.mouse.move(third.x + third.width - 1, third.y + third.height / 2, { steps: 20 });
+      await page.mouse.up();
+
+      const selected = await page.evaluate(() => window.getSelection()?.toString() ?? "");
+      expect(selected).toContain("First paragraph.");
+      expect(selected).toContain("Third paragraph.");
+    } finally {
+      await agent.cleanup();
+    }
+  });
+});
diff --git a/packages/app/e2e/browser/composer-focus.spec.ts b/packages/app/e2e/browser/composer-focus.spec.ts
index 5557e9e9ac..11fe0bf50f 100644
--- a/packages/app/e2e/browser/composer-focus.spec.ts
+++ b/packages/app/e2e/browser/composer-focus.spec.ts
@@ -25,7 +25,7 @@ import {
   expectMobileAgentSidebarVisible,
   expectMobileExplorerHidden,
   expectMobileExplorerVisible,
-  swipeOpenMobileAgentSidebar,
+  openMobileAgentSidebarWithKeyboard,
   swipeOpenMobileExplorer,
 } from "../support/helpers/sidebar";
 import { readScrollMetrics } from "../support/helpers/agent-bottom-anchor";
@@ -249,7 +249,7 @@ test.describe("touch screen wide enough for the desktop layout", () => {
 const COMPACT_PANELS = [
   {
     name: "agent list",
-    open: swipeOpenMobileAgentSidebar,
+    open: openMobileAgentSidebarWithKeyboard,
     expectOpen: expectMobileAgentSidebarVisible,
     close: closeMobileAgentSidebar,
     expectClosed: expectMobileAgentSidebarHidden,
diff --git a/packages/app/e2e/browser/composer-whitespace.spec.ts b/packages/app/e2e/browser/composer-whitespace.spec.ts
index 8e1a527f0f..9ad03112db 100644
--- a/packages/app/e2e/browser/composer-whitespace.spec.ts
+++ b/packages/app/e2e/browser/composer-whitespace.spec.ts
@@ -37,7 +37,7 @@ import {
   closeMobileAgentSidebar,
   expectMobileAgentSidebarHidden,
   expectMobileAgentSidebarVisible,
-  swipeOpenMobileAgentSidebar,
+  openMobileAgentSidebarWithKeyboard,
 } from "../support/helpers/sidebar";
 
 async function composerHeight(page: Page): Promise<number> {
@@ -541,8 +541,8 @@ test("the compact sidebar over a fullscreen editor leaves the exit action alone"
     await writeCompactDraft(page, draft);
     await enterComposerFullscreen(page);
     await expectWorkspaceHeaderHidden(page);
-    // Fullscreen hides the header's menu button; the edge swipe still opens the list over it.
-    await swipeOpenMobileAgentSidebar(page);
+    // Fullscreen hides the header's menu button; the keyboard shortcut opens the list over it.
+    await openMobileAgentSidebarWithKeyboard(page);
     await expectMobileAgentSidebarVisible(page);
     // The list covers the pane, so the editor's exit action is not armed.
     await page.keyboard.press("Escape");
diff --git a/packages/app/e2e/browser/sidebar-nav-settings.spec.ts b/packages/app/e2e/browser/sidebar-nav-settings.spec.ts
index b557b73ccb..618d44729c 100644
--- a/packages/app/e2e/browser/sidebar-nav-settings.spec.ts
+++ b/packages/app/e2e/browser/sidebar-nav-settings.spec.ts
@@ -97,6 +97,7 @@ test("fixed footer line keeps its five icons, Help and Settings at the end", asy
   await setFooterItemVisible(page, "usage", true);
   await leaveSettings(page);
   await page.setViewportSize({ width: 390, height: 844 });
+  await openCompactSidebar(page);
   await expectCompactSidebarOpen(page);
   await expectFooterSeparator(page, true);
   await expectFooterIconRow(page);
diff --git a/packages/app/e2e/support/helpers/sidebar.ts b/packages/app/e2e/support/helpers/sidebar.ts
index 0943eba0b4..9fd61a8451 100644
--- a/packages/app/e2e/support/helpers/sidebar.ts
+++ b/packages/app/e2e/support/helpers/sidebar.ts
@@ -261,16 +261,9 @@ export async function expectMobileAgentSidebarHidden(page: Page): Promise<void>
   await expect(page.getByTestId("sidebar-sessions")).not.toBeInViewport({ timeout: 5_000 });
 }
 
-/** Drag from the left edge: the only way to open the list while fullscreen hides the header. */
-export async function swipeOpenMobileAgentSidebar(page: Page): Promise<void> {
-  const viewport = page.viewportSize();
-  if (!viewport) throw new Error("viewport size is required");
-  const y = Math.round(viewport.height / 2);
-  await page.mouse.move(8, y);
-  await page.mouse.down();
-  await page.mouse.move(40, y, { steps: 4 });
-  await page.mouse.move(Math.round(viewport.width * 0.7), y, { steps: 12 });
-  await page.mouse.up();
+/** Opens navigation without moving focus to the header, including over a fullscreen editor. */
+export async function openMobileAgentSidebarWithKeyboard(page: Page): Promise<void> {
+  await page.keyboard.press("ControlOrMeta+b");
 }
 
 /** Drag from the right edge to open the compact Explorer over the agent. */
diff --git a/packages/app/src/app/_layout.tsx b/packages/app/src/app/_layout.tsx
index 29d63a6a05..d5b6794c03 100644
--- a/packages/app/src/app/_layout.tsx
+++ b/packages/app/src/app/_layout.tsx
@@ -25,6 +25,7 @@ import {
   useCallback,
   useContext,
   useEffect,
+  useLayoutEffect,
   useMemo,
   useState,
   useSyncExternalStore,
@@ -68,6 +69,7 @@ import {
   resolveDesktopAppContentMinimum,
   resolveDesktopSidebarVisibility,
   resolveSidebarActivity,
+  resolveLeftSidebarPresentation,
 } from "@/components/desktop-sidebar-layout";
 import { isNative, isWeb } from "@/constants/platform";
 import { HorizontalScrollProvider } from "@/contexts/horizontal-scroll-context";
@@ -121,7 +123,7 @@ import {
   useHosts,
 } from "@/runtime/host-runtime";
 import { getDaemonStartService } from "@/runtime/daemon-start-service";
-import { usePanelStore } from "@/stores/panel-store";
+import { usePanelStore, type LeftSidebarPresentation } from "@/stores/panel-store";
 import { flushDraftPersistStorage } from "@/stores/draft-store";
 import { getNextThemePreference, ICON_STROKE_WIDTH } from "@/styles/theme";
 import { useSessionStore } from "@/stores/session-store";
@@ -441,6 +443,17 @@ function AppContainer({ children, chromeEnabled: chromeEnabledOverride }: AppCon
       viewportWidth,
     }),
   });
+  const sidebarPresentation = resolveLeftSidebarPresentation({
+    chromeEnabled,
+    isCompactLayout,
+    isFocusModeEnabled: isWorkspaceFocusModeEnabled,
+    desktopSidebarVisible,
+  });
+  const applyPanelLayout = usePanelStore((state) => state.applyPanelLayout);
+  // Publishes the layout to the store, which owns the panel targets each layout allows.
+  useLayoutEffect(() => {
+    applyPanelLayout({ isCompact: isCompactLayout, leftSidebar: sidebarPresentation });
+  }, [applyPanelLayout, isCompactLayout, sidebarPresentation]);
   const hasTopLeftWindowControls = useHasWindowChromeObstruction("top-left");
   const appChromeLayout = resolveDesktopAppChromeLayout({
     desktopSidebarRendered: desktopSidebarVisible,
@@ -450,7 +463,7 @@ function AppContainer({ children, chromeEnabled: chromeEnabledOverride }: AppCon
   const sidebarChrome = (
     <SidebarChrome
       mounted={isCompactLayout ? chromeEnabled : desktopSidebarMounted}
-      visible={isCompactLayout ? chromeEnabled : desktopSidebarVisible}
+      presentation={sidebarPresentation}
       keyboardShortcutsEnabled={keyboardShortcutsEnabled}
     />
   );
@@ -531,7 +544,7 @@ function AppContainer({ children, chromeEnabled: chromeEnabledOverride }: AppCon
   );
 
   return (
-    <AppContainerLifetime compactGesturesEnabled={chromeEnabled && isCompactLayout}>
+    <AppContainerLifetime sidebarGesturesEnabled={sidebarPresentation === "overlay"}>
       <SheetHostScope enabled={isCompactLayout}>{surface}</SheetHostScope>
     </AppContainerLifetime>
   );
@@ -539,15 +552,15 @@ function AppContainer({ children, chromeEnabled: chromeEnabledOverride }: AppCon
 
 function AppContainerLifetime({
   children,
-  compactGesturesEnabled,
+  sidebarGesturesEnabled,
 }: {
   children: ReactNode;
-  compactGesturesEnabled: boolean;
+  sidebarGesturesEnabled: boolean;
 }) {
   return (
     <ComposerEditingSessionsProvider>
       <CommandCenterProvider>
-        <MobileGestureWrapper chromeEnabled={compactGesturesEnabled}>
+        <MobileGestureWrapper chromeEnabled={sidebarGesturesEnabled}>
           {children}
         </MobileGestureWrapper>
       </CommandCenterProvider>
@@ -557,23 +570,26 @@ function AppContainerLifetime({
 
 function SidebarChrome({
   mounted,
-  visible,
+  presentation,
   keyboardShortcutsEnabled,
 }: {
   mounted: boolean;
-  visible: boolean;
+  presentation: LeftSidebarPresentation;
   keyboardShortcutsEnabled: boolean;
 }) {
   const isCompactLayout = useIsCompactFormFactor();
   const isMobileActive = useIsMobilePanelActive("agent-list");
-  const active = resolveSidebarActivity(visible, isCompactLayout, isMobileActive);
+  const overlay = presentation === "overlay";
+  const active = resolveSidebarActivity(presentation !== "hidden", overlay, isMobileActive);
   const hardwareKeyboardPresent = useHardwareKeyboardPresent();
   return (
     <SidebarModelProvider
       active={active}
       keyboardNavigationActive={keyboardShortcutsEnabled && hardwareKeyboardPresent}
     >
-      {mounted ? <LeftSidebar active={active} /> : null}
+      {mounted ? (
+        <LeftSidebar active={active} desktopOverlay={overlay && !isCompactLayout} />
+      ) : null}
       <WorkspaceShortcutTargetsSubscriber enabled={keyboardShortcutsEnabled} />
     </SidebarModelProvider>
   );
@@ -586,8 +602,8 @@ function MobileGestureWrapper({
   children: ReactNode;
   chromeEnabled: boolean;
 }) {
-  const openGesture = useOpenAgentListGesture(chromeEnabled);
   const isCompactLayout = useIsCompactFormFactor();
+  const openGesture = useOpenAgentListGesture(chromeEnabled);
 
   return (
     <GestureDetector gesture={openGesture} touchAction={MOBILE_WEB_GESTURE_TOUCH_ACTION}>
diff --git a/packages/app/src/components/desktop-sidebar-layout.test.ts b/packages/app/src/components/desktop-sidebar-layout.test.ts
index f4ccec7e98..41a663a9e3 100644
--- a/packages/app/src/components/desktop-sidebar-layout.test.ts
+++ b/packages/app/src/components/desktop-sidebar-layout.test.ts
@@ -9,9 +9,11 @@ import {
   canDesktopAppSidebarShare,
   resolveDesktopAppChromeLayout,
   resolveDesktopAppContentMinimum,
+  resolveDesktopSidebarInsetLeft,
   resolveDesktopSidebarVisibility,
   resolveSidebarActivity,
   resolveDesktopSidebarWidth,
+  resolveLeftSidebarPresentation,
 } from "@/components/desktop-sidebar-layout";
 
 describe("desktop sidebar layout", () => {
@@ -104,6 +106,40 @@ describe("desktop sidebar layout", () => {
     ).toBe(false);
   });
 
+  it("offers an overlay only after wide navigation yields its dock", () => {
+    const input = {
+      chromeEnabled: true,
+      isCompactLayout: false,
+      isFocusModeEnabled: false,
+    };
+    expect(resolveLeftSidebarPresentation({ ...input, desktopSidebarVisible: true })).toBe("dock");
+    expect(resolveLeftSidebarPresentation({ ...input, desktopSidebarVisible: false })).toBe(
+      "overlay",
+    );
+  });
+
+  it("does not reveal navigation over a focused workspace or suppressed chrome", () => {
+    const input = {
+      chromeEnabled: true,
+      isCompactLayout: false,
+      isFocusModeEnabled: false,
+      desktopSidebarVisible: false,
+    };
+    expect(resolveLeftSidebarPresentation({ ...input, isFocusModeEnabled: true })).toBe("hidden");
+    expect(resolveLeftSidebarPresentation({ ...input, chromeEnabled: false })).toBe("hidden");
+  });
+
+  it("keeps phone navigation available independently of saved wide focus mode", () => {
+    expect(
+      resolveLeftSidebarPresentation({
+        chromeEnabled: true,
+        isCompactLayout: true,
+        isFocusModeEnabled: true,
+        desktopSidebarVisible: false,
+      }),
+    ).toBe("overlay");
+  });
+
   it("keeps the sidebar toggle window-owned beside left window controls", () => {
     expect(
       resolveDesktopAppChromeLayout({
@@ -207,3 +243,8 @@ it("reserves room for Explorer and the workspace before showing app navigation",
     }),
   ).toBe(true);
 });
+
+it("insets an overlay sidebar's content by the left safe area and leaves the dock to app chrome", () => {
+  expect(resolveDesktopSidebarInsetLeft({ overlay: true, safeAreaLeft: 20 })).toBe(20);
+  expect(resolveDesktopSidebarInsetLeft({ overlay: false, safeAreaLeft: 20 })).toBe(0);
+});
diff --git a/packages/app/src/components/desktop-sidebar-layout.ts b/packages/app/src/components/desktop-sidebar-layout.ts
index 09e03bc02e..692934d73e 100644
--- a/packages/app/src/components/desktop-sidebar-layout.ts
+++ b/packages/app/src/components/desktop-sidebar-layout.ts
@@ -1,6 +1,10 @@
 import { EXPLORER_WORKSPACE_MIN_WIDTH } from "@/components/explorer-sidebar-layout";
 import { SETTINGS_DESKTOP_SPLIT_MIN_WIDTH } from "@/constants/layout";
-import { MAX_SIDEBAR_WIDTH, MIN_SIDEBAR_WIDTH } from "@/stores/panel-store";
+import {
+  MAX_SIDEBAR_WIDTH,
+  MIN_SIDEBAR_WIDTH,
+  type LeftSidebarPresentation,
+} from "@/stores/panel-store";
 import type { DesktopDivisionLayout } from "@/window-layout";
 
 const MIN_DESKTOP_CENTER_WIDTH = 400;
@@ -21,6 +25,33 @@ export function resolveDesktopSidebarVisibility(input: {
   );
 }
 
+/**
+ * Compact layouts always present navigation as a drawer overlay. Wide layouts dock it when it is
+ * visible and fall back to an overlay when the dock is collapsed or yields its width.
+ */
+export function resolveLeftSidebarPresentation(input: {
+  chromeEnabled: boolean;
+  isCompactLayout: boolean;
+  isFocusModeEnabled: boolean;
+  desktopSidebarVisible: boolean;
+}): LeftSidebarPresentation {
+  if (!input.chromeEnabled) return "hidden";
+  if (input.isCompactLayout) return "overlay";
+  if (input.isFocusModeEnabled) return "hidden";
+  return input.desktopSidebarVisible ? "dock" : "overlay";
+}
+
+/**
+ * The overlay sidebar starts at the window's left edge, over the workspace's safe-area padding, so
+ * its content takes the left inset itself. The dock sits inside app chrome, which already pads it.
+ */
+export function resolveDesktopSidebarInsetLeft(input: {
+  overlay: boolean;
+  safeAreaLeft: number;
+}): number {
+  return input.overlay ? input.safeAreaLeft : 0;
+}
+
 export function resolveDesktopAppChromeLayout(input: {
   desktopSidebarRendered: boolean;
   hasTopLeftWindowControls: boolean;
diff --git a/packages/app/src/components/left-sidebar.tsx b/packages/app/src/components/left-sidebar.tsx
index 73c1fadb7b..b4b54db3db 100644
--- a/packages/app/src/components/left-sidebar.tsx
+++ b/packages/app/src/components/left-sidebar.tsx
@@ -25,7 +25,10 @@ import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { TitlebarDragRegion } from "@/components/desktop/titlebar-drag-region";
 import { SidebarCloseButton } from "@/components/headers/sidebar-close-button";
-import { resolveDesktopSidebarWidth } from "@/components/desktop-sidebar-layout";
+import {
+  resolveDesktopSidebarInsetLeft,
+  resolveDesktopSidebarWidth,
+} from "@/components/desktop-sidebar-layout";
 import { useWindowLayout, resolveDesktopDivisionLayout } from "@/window-layout";
 import {
   SIDEBAR_RESIZE_ACTIVATION_OFFSET,
@@ -65,6 +68,7 @@ import { useSidebarNavItems } from "@/sidebar-nav/use-sidebar-nav-items";
 import { usePanelStore } from "@/stores/panel-store";
 import { useOwnsWindowChromeCorner, WindowChromeSafeArea } from "@/utils/desktop-window";
 import { useCloseAgentListGesture } from "@/mobile-panels/gestures";
+import { useLeftPanelWidth } from "@/mobile-panels/provider";
 import { MobilePanelOverlay } from "@/mobile-panels/presentation";
 import { buildSettingsRoute } from "@/utils/host-routes";
 import { openHostOverview } from "@/navigation/settings-navigation";
@@ -121,9 +125,16 @@ interface MobileSidebarProps extends SidebarSharedProps {
 interface DesktopSidebarProps extends SidebarSharedProps {
   insetsTop: number;
   active: boolean;
+  overlay: boolean;
 }
 
-export const LeftSidebar = memo(function LeftSidebar({ active }: { active: boolean }) {
+export const LeftSidebar = memo(function LeftSidebar({
+  active,
+  desktopOverlay,
+}: {
+  active: boolean;
+  desktopOverlay: boolean;
+}) {
   const { theme } = useUnistyles();
   const { t } = useTranslation();
   const insets = useSafeAreaInsets();
@@ -164,27 +175,20 @@ export const LeftSidebar = memo(function LeftSidebar({ active }: { active: boole
   const openProjectPicker = useOpenAddProject();
   const { open: openImportSession, sheet: importSessionSheet } = useImportSession();
 
-  const handleOpenProjectMobile = useCallback(() => {
+  // Each destination closes the navigation overlay first. Closing is idempotent, so a docked
+  // sidebar runs the same handler.
+  const handleOpenProject = useCallback(() => {
     void openProjectPicker();
   }, [openProjectPicker]);
 
-  const handleOpenProjectDesktop = useCallback(() => {
-    void openProjectPicker();
-  }, [openProjectPicker]);
-
-  const handleSettingsMobile = useCallback(() => {
+  const handleSettings = useCallback(() => {
     showMobileAgent();
     router.push(buildSettingsRoute());
   }, [showMobileAgent]);
 
-  const handleSettingsDesktop = useCallback(() => {
-    router.push(buildSettingsRoute());
-  }, []);
+  const handleAddHost = useAddHost();
 
-  const handleAddHostMobile = useAddHost();
-  const handleAddHostDesktop = handleAddHostMobile;
-
-  const handleOpenHostSettingsMobile = useCallback(
+  const handleOpenHostSettings = useCallback(
     (serverId: string) => {
       showMobileAgent();
       openHostOverview(serverId);
@@ -192,14 +196,6 @@ export const LeftSidebar = memo(function LeftSidebar({ active }: { active: boole
     [showMobileAgent],
   );
 
-  const handleOpenHostSettingsDesktop = useCallback((serverId: string) => {
-    openHostOverview(serverId);
-  }, []);
-
-  const handleImportSessionMobile = useCallback(() => {
-    openImportSession();
-  }, [openImportSession]);
-
   const labels = useMemo(
     (): SidebarLabels => ({
       addProject: t("sidebar.actions.addProject"),
@@ -232,41 +228,35 @@ export const LeftSidebar = memo(function LeftSidebar({ active }: { active: boole
     labels,
   };
 
-  if (isCompactLayout) {
-    return (
-      <>
-        <RetainedPanelActivity active={active}>
-          <MobileSidebar
-            {...sharedProps}
-            active={active}
-            insetsTop={insets.top}
-            insetsBottom={insets.bottom}
-            closeSidebar={showMobileAgent}
-            handleOpenProject={handleOpenProjectMobile}
-            handleImportSession={handleImportSessionMobile}
-            handleSettings={handleSettingsMobile}
-            handleAddHost={handleAddHostMobile}
-            handleOpenHostSettings={handleOpenHostSettingsMobile}
-          />
-        </RetainedPanelActivity>
-        {importSessionSheet}
-      </>
-    );
-  }
+  const handlers = {
+    handleOpenProject,
+    handleImportSession: openImportSession,
+    handleSettings,
+    handleAddHost,
+    handleOpenHostSettings,
+  };
 
   return (
     <>
       <RetainedPanelActivity active={active}>
-        <DesktopSidebar
-          {...sharedProps}
-          insetsTop={insets.top}
-          active={active}
-          handleOpenProject={handleOpenProjectDesktop}
-          handleImportSession={openImportSession}
-          handleSettings={handleSettingsDesktop}
-          handleAddHost={handleAddHostDesktop}
-          handleOpenHostSettings={handleOpenHostSettingsDesktop}
-        />
+        {isCompactLayout ? (
+          <MobileSidebar
+            {...sharedProps}
+            {...handlers}
+            active={active}
+            insetsTop={insets.top}
+            insetsBottom={insets.bottom}
+            closeSidebar={showMobileAgent}
+          />
+        ) : (
+          <DesktopSidebar
+            {...sharedProps}
+            {...handlers}
+            insetsTop={insets.top}
+            active={active}
+            overlay={desktopOverlay}
+          />
+        )}
       </RetainedPanelActivity>
       {importSessionSheet}
     </>
@@ -663,10 +653,10 @@ function DesktopSidebar({
   handleOpenHostSettings,
   insetsTop,
   active,
+  overlay,
 }: DesktopSidebarProps) {
   const ownsTopLeft = useOwnsWindowChromeCorner("top-left");
   const hasActiveHostFilter = useSidebarViewStore((state) => state.hostFilters.length > 0);
-  const sidebarWidth = usePanelStore((state) => state.sidebarWidth);
   const setSidebarWidth = usePanelStore((state) => state.setSidebarWidth);
   const { width: windowWidth, height: windowHeight } = useWindowDimensions();
   const insets = useSafeAreaInsets();
@@ -678,14 +668,12 @@ function DesktopSidebar({
     leftInset: insets.left,
     rightInset: insets.right,
   });
-  const visibleSidebarWidth =
-    divisionLayout?.sidebarWidth ??
-    resolveDesktopSidebarWidth({
-      requestedWidth: sidebarWidth,
-      viewportWidth,
-    });
+  const visibleSidebarWidth = useLeftPanelWidth();
 
-  const startWidthRef = useRef(visibleSidebarWidth);
+  const closeSidebar = usePanelStore((state) => state.showMobileAgent);
+  const { gesture: closeGesture, gestureRef: closeGestureRef } = useCloseAgentListGesture(overlay);
+
+  const startWidth = useSharedValue(visibleSidebarWidth);
   const resizeWidth = useSharedValue(visibleSidebarWidth);
   const [resizePressed, setResizePressed] = useState(false);
   const showResizeGrip = useCallback(() => setResizePressed(true), []);
@@ -709,12 +697,12 @@ function DesktopSidebar({
         .activeOffsetX([-SIDEBAR_RESIZE_ACTIVATION_OFFSET, SIDEBAR_RESIZE_ACTIVATION_OFFSET])
         .failOffsetY([-SIDEBAR_RESIZE_FAIL_OFFSET, SIDEBAR_RESIZE_FAIL_OFFSET])
         .onStart((event) => {
-          startWidthRef.current = visibleSidebarWidth - event.translationX;
+          startWidth.value = visibleSidebarWidth - event.translationX;
           resizeWidth.value = visibleSidebarWidth;
         })
         .onUpdate((event) => {
           // Dragging right (positive translationX) increases width
-          const newWidth = startWidthRef.current + event.translationX;
+          const newWidth = startWidth.value + event.translationX;
           resizeWidth.value = resolveDesktopSidebarWidth({
             requestedWidth: newWidth,
             viewportWidth,
@@ -732,6 +720,7 @@ function DesktopSidebar({
       resizeWidth,
       setSidebarWidth,
       showResizeGrip,
+      startWidth,
       viewportWidth,
       visibleSidebarWidth,
     ],
@@ -740,101 +729,110 @@ function DesktopSidebar({
   const resizeAnimatedStyle = useAnimatedStyle(() => ({
     width: divisionLayout?.sidebarWidth ?? resizeWidth.value,
   }));
-
+  // The panel host gets no width of its own: the dock sizes to this view and the overlay fills the
+  // window. A Reanimated width on the host reached Android after React had switched presentation,
+  // and a lost update left the workspace at the dock width after the dock collapsed.
   const desktopSidebarStyle = useMemo(
-    () => [
-      staticStyles.desktopSidebar,
-      !active && staticStyles.desktopSidebarHidden,
-      resizeAnimatedStyle,
-    ],
-    [active, resizeAnimatedStyle],
+    () => [staticStyles.desktopSidebar, resizeAnimatedStyle],
+    [resizeAnimatedStyle],
   );
   const desktopSidebarBorderStyle = useMemo(
     () => [
       styles.desktopSidebarBorder(divisionLayout !== null),
-      { flex: 1, paddingTop: insetsTop, paddingBottom: insets.bottom },
+      {
+        flex: 1,
+        paddingTop: insetsTop,
+        paddingBottom: insets.bottom,
+        paddingLeft: resolveDesktopSidebarInsetLeft({ overlay, safeAreaLeft: insets.left }),
+      },
     ],
-    [insetsTop, insets.bottom, divisionLayout],
+    [insetsTop, insets.bottom, insets.left, overlay, divisionLayout],
   );
   const sidebarHeaderGroupStyle = useMemo(
     () => [styles.sidebarHeaderGroup, ownsTopLeft && styles.sidebarHeaderGroupBelowChrome],
     [ownsTopLeft],
   );
   return (
-    <Animated.View
-      accessibilityElementsHidden={!active}
-      importantForAccessibility={active ? "auto" : "no-hide-descendants"}
-      pointerEvents={active ? "auto" : "none"}
-      style={desktopSidebarStyle}
+    <MobilePanelOverlay
+      panel="agent-list"
+      presentation={overlay ? "overlay" : "dock"}
+      dockVisible={active}
+      closeGesture={closeGesture}
     >
-      <View style={desktopSidebarBorderStyle}>
-        <View style={styles.sidebarDragArea}>
-          {ownsTopLeft || DEV_BUILD_LABEL ? (
-            <View style={styles.desktopChromeRow}>
+      <Animated.View style={desktopSidebarStyle}>
+        <View style={desktopSidebarBorderStyle}>
+          <View style={styles.sidebarDragArea}>
+            {ownsTopLeft || DEV_BUILD_LABEL ? (
+              <View style={styles.desktopChromeRow}>
+                <TitlebarDragRegion />
+                {DEV_BUILD_LABEL ? (
+                  <View
+                    pointerEvents="none"
+                    style={styles.devBuildBadge}
+                    testID="dev-build-label"
+                    accessibilityLabel={`Development build: ${DEV_BUILD_LABEL}`}
+                  >
+                    <GitBranch size={12} color={theme.colors.accentForeground} />
+                    <Text numberOfLines={1} ellipsizeMode="tail" style={styles.devBuildBadgeText}>
+                      {DEV_BUILD_LABEL}
+                    </Text>
+                  </View>
+                ) : null}
+              </View>
+            ) : (
               <TitlebarDragRegion />
-              {DEV_BUILD_LABEL ? (
-                <View
-                  pointerEvents="none"
-                  style={styles.devBuildBadge}
-                  testID="dev-build-label"
-                  accessibilityLabel={`Development build: ${DEV_BUILD_LABEL}`}
-                >
-                  <GitBranch size={12} color={theme.colors.accentForeground} />
-                  <Text numberOfLines={1} ellipsizeMode="tail" style={styles.devBuildBadgeText}>
-                    {DEV_BUILD_LABEL}
-                  </Text>
-                </View>
-              ) : null}
-            </View>
+            )}
+            <SidebarNavRows style={sidebarHeaderGroupStyle} onBeforeNavigate={closeSidebar} />
+          </View>
+
+          {isInitialLoad && !hasActiveHostFilter ? (
+            <SidebarAgentListSkeleton />
           ) : (
-            <TitlebarDragRegion />
+            <SidebarWorkspaceList
+              collapsedProjectKeys={collapsedProjectKeys}
+              onToggleProjectCollapsed={toggleProjectCollapsed}
+              shortcutIndexByWorkspaceKey={shortcutIndexByWorkspaceKey}
+              groupMode={groupMode}
+              workspaceGroups={workspaceGroups}
+              projectIconTargets={projectIconTargets}
+              pinnedGroups={pinnedGroups}
+              projects={projects}
+              hasProjectsBeforeFilter={hasProjectsBeforeFilter}
+              hasActiveProjectFilter={hasActiveProjectFilter}
+              workspaceEntriesByKey={workspaceEntriesByKey}
+              isRefreshing={isManualRefresh && isRevalidating}
+              onRefresh={handleRefresh}
+              onAddProject={handleOpenProject}
+              onImportSession={handleImportSession}
+              onWorkspacePress={closeSidebar}
+              parentGestureRef={closeGestureRef}
+              dragGestureHostActive={active}
+              listHeaderComponent={workspacesSectionHeaderElement}
+            />
           )}
-          <SidebarNavRows style={sidebarHeaderGroupStyle} />
+
+          <SidebarCalloutSlot />
+
+          <SidebarFooter
+            handleOpenProject={handleOpenProject}
+            handleSettings={handleSettings}
+            labels={labels}
+            handleAddHost={handleAddHost}
+            handleOpenHostSettings={handleOpenHostSettings}
+            onBeforeNavigate={closeSidebar}
+          />
+
+          {!overlay && divisionLayout === null ? (
+            <SidebarResizeHandle
+              edge="right"
+              gesture={resizeGesture}
+              pressed={resizePressed}
+              testID="left-sidebar-resize-handle"
+            />
+          ) : null}
         </View>
-
-        {isInitialLoad && !hasActiveHostFilter ? (
-          <SidebarAgentListSkeleton />
-        ) : (
-          <SidebarWorkspaceList
-            collapsedProjectKeys={collapsedProjectKeys}
-            onToggleProjectCollapsed={toggleProjectCollapsed}
-            shortcutIndexByWorkspaceKey={shortcutIndexByWorkspaceKey}
-            groupMode={groupMode}
-            workspaceGroups={workspaceGroups}
-            projectIconTargets={projectIconTargets}
-            pinnedGroups={pinnedGroups}
-            projects={projects}
-            hasProjectsBeforeFilter={hasProjectsBeforeFilter}
-            hasActiveProjectFilter={hasActiveProjectFilter}
-            workspaceEntriesByKey={workspaceEntriesByKey}
-            isRefreshing={isManualRefresh && isRevalidating}
-            onRefresh={handleRefresh}
-            onAddProject={handleOpenProject}
-            onImportSession={handleImportSession}
-            listHeaderComponent={workspacesSectionHeaderElement}
-          />
-        )}
-
-        <SidebarCalloutSlot />
-
-        <SidebarFooter
-          handleOpenProject={handleOpenProject}
-          handleSettings={handleSettings}
-          labels={labels}
-          handleAddHost={handleAddHost}
-          handleOpenHostSettings={handleOpenHostSettings}
-        />
-
-        {divisionLayout === null ? (
-          <SidebarResizeHandle
-            edge="right"
-            gesture={resizeGesture}
-            pressed={resizePressed}
-            testID="left-sidebar-resize-handle"
-          />
-        ) : null}
-      </View>
-    </Animated.View>
+      </Animated.View>
+    </MobilePanelOverlay>
   );
 }
 
@@ -865,9 +863,7 @@ const workspacesSectionHeaderElement = <WorkspacesSectionHeader />;
 const staticStyles = RNStyleSheet.create({
   desktopSidebar: {
     position: "relative" as const,
-  },
-  desktopSidebarHidden: {
-    display: "none",
+    flex: 1,
   },
 });
 
diff --git a/packages/app/src/components/resize-handle.tsx b/packages/app/src/components/resize-handle.tsx
index c3930688c2..8bb2434ae8 100644
--- a/packages/app/src/components/resize-handle.tsx
+++ b/packages/app/src/components/resize-handle.tsx
@@ -3,7 +3,7 @@ import { View, type PointerEvent as RNPointerEvent } from "react-native";
 import { Gesture, GestureDetector } from "react-native-gesture-handler";
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { startResizeHandleDrag, type ResizeHandleDrag } from "@/components/resize-handle-drag";
-import { useHasFinePointer } from "@/hooks/use-fine-pointer";
+import { usePointerCapabilities } from "@/hooks/pointer-capabilities";
 import {
   SIDEBAR_RESIZE_ACTIVATION_OFFSET,
   SIDEBAR_RESIZE_FAIL_OFFSET,
@@ -47,7 +47,7 @@ export function ResizeHandle({
   onResizeSplit,
 }: ResizeHandleProps) {
   const { theme } = useUnistyles();
-  const finePointer = useHasFinePointer();
+  const { finePointer } = usePointerCapabilities();
   const pointerStatesRef = useRef(new Map<number, PointerState>());
   const touchStateRef = useRef<PointerState | null>(null);
   const cursorBeforeDragRef = useRef<string | null>(null);
diff --git a/packages/app/src/components/sidebar-resize-handle.tsx b/packages/app/src/components/sidebar-resize-handle.tsx
index d842f0f008..37eef984b9 100644
--- a/packages/app/src/components/sidebar-resize-handle.tsx
+++ b/packages/app/src/components/sidebar-resize-handle.tsx
@@ -7,7 +7,7 @@ import {
   type SidebarResizeEdge,
 } from "@/components/sidebar-resize-handle-layout";
 import { isWeb } from "@/constants/platform";
-import { useHasFinePointer } from "@/hooks/use-fine-pointer";
+import { usePointerCapabilities } from "@/hooks/pointer-capabilities";
 
 interface SidebarResizeHandleProps {
   edge: SidebarResizeEdge;
@@ -29,7 +29,7 @@ function edgeOffsetStyle(edge: SidebarResizeEdge, edgeOffset: number) {
 }
 
 export function SidebarResizeHandle({ edge, gesture, pressed, testID }: SidebarResizeHandleProps) {
-  const finePointer = useHasFinePointer();
+  const { finePointer } = usePointerCapabilities();
 
   if (finePointer) {
     return <PointerResizeHandle edge={edge} gesture={gesture} pressed={pressed} testID={testID} />;
diff --git a/packages/app/src/components/ui/control-sizing.ts b/packages/app/src/components/ui/control-sizing.ts
index d64fc3f000..6dc371af76 100644
--- a/packages/app/src/components/ui/control-sizing.ts
+++ b/packages/app/src/components/ui/control-sizing.ts
@@ -1,4 +1,4 @@
-import { hasTouchScreen } from "@/hooks/use-fine-pointer";
+import { hasTouchScreen } from "@/hooks/pointer-capabilities";
 
 // The sizing gate, apart from the control sizes so that low-level modules such as
 // `constants/layout` can size by it without loading the theme. Import it through
diff --git a/packages/app/src/composer/index.tsx b/packages/app/src/composer/index.tsx
index af9a56b826..2ad3620313 100644
--- a/packages/app/src/composer/index.tsx
+++ b/packages/app/src/composer/index.tsx
@@ -37,7 +37,7 @@ import {
   TOOLBAR_CONTROL_HEIGHT,
 } from "@/components/ui/control-geometry";
 import { usePanelStore } from "@/stores/panel-store";
-import { useHasFinePointer } from "@/hooks/use-fine-pointer";
+import { usePointerCapabilities } from "@/hooks/pointer-capabilities";
 import { useShallow } from "zustand/shallow";
 import {
   ArrowUp,
@@ -1312,7 +1312,7 @@ function ComposerContentImpl({
   const isCompactLayout = resolveCompactLayout(isCompactLayoutOverride, isCompactFormFactor);
   const buttonIconSize = iconSizeFor("md")[controlSizingForLayout(isCompactFormFactor)];
   const isDesktopWebBreakpoint = resolveIsDesktopWebBreakpoint(isCompactFormFactor);
-  const hasFinePointer = useHasFinePointer();
+  const { finePointer: hasFinePointer } = usePointerCapabilities();
   const isDesktopLayout = resolveIsDesktopWebBreakpoint(isCompactLayout);
   const messagePlaceholder = resolveMessagePlaceholder(inputMode, isDesktopLayout, t, placeholder);
   const hasText = useSyncExternalStore(
diff --git a/packages/app/src/composer/input/input.tsx b/packages/app/src/composer/input/input.tsx
index c79c3e0082..a71469c626 100644
--- a/packages/app/src/composer/input/input.tsx
+++ b/packages/app/src/composer/input/input.tsx
@@ -37,7 +37,7 @@ import {
 import { ArrowUp, Mic, MicOff, CornerDownLeft, Plus, Square } from "lucide-react-native";
 import * as Haptics from "expo-haptics";
 import { useDictation } from "@/hooks/use-dictation";
-import { hasFinePointer } from "@/hooks/use-fine-pointer";
+import { hasFinePointer } from "@/hooks/pointer-capabilities";
 import { DictationOverlay } from "@/components/dictation-controls";
 import { RealtimeVoiceOverlay } from "@/components/realtime-voice-overlay";
 import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
diff --git a/packages/app/src/hooks/pointer-capabilities.test.ts b/packages/app/src/hooks/pointer-capabilities.test.ts
new file mode 100644
index 0000000000..167db7c553
--- /dev/null
+++ b/packages/app/src/hooks/pointer-capabilities.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import { createPointerCapabilitiesSource } from "./pointer-capabilities";
+
+class FakeMediaQueryList {
+  private readonly listeners = new Set<() => void>();
+
+  constructor(
+    readonly media: string,
+    public matches: boolean,
+  ) {}
+
+  addEventListener(_type: "change", listener: () => void) {
+    this.listeners.add(listener);
+  }
+
+  removeEventListener(_type: "change", listener: () => void) {
+    this.listeners.delete(listener);
+  }
+
+  setMatches(matches: boolean) {
+    this.matches = matches;
+    for (const listener of this.listeners) listener();
+  }
+}
+
+function createFakeDisplay(initial: { finePointer: boolean; touchScreen: boolean }) {
+  const queries = {
+    finePointer: new FakeMediaQueryList("(hover: hover) and (pointer: fine)", initial.finePointer),
+    touchScreen: new FakeMediaQueryList("(any-pointer: coarse)", initial.touchScreen),
+  };
+  const matchMedia = (query: string) => {
+    const match = Object.values(queries).find((list) => list.media === query);
+    if (!match) throw new Error(`Unexpected media query ${query}`);
+    return match as unknown as MediaQueryList;
+  };
+  return { queries, matchMedia };
+}
+
+describe("pointer capabilities", () => {
+  it("reports a hybrid touch laptop as both a fine pointer and a touch screen", () => {
+    const display = createFakeDisplay({ finePointer: true, touchScreen: true });
+    const source = createPointerCapabilitiesSource(display.matchMedia);
+
+    expect(source.getSnapshot()).toEqual({ finePointer: true, touchScreen: true });
+  });
+
+  it("notifies and updates the touch answer when a touch screen appears or goes away", () => {
+    const display = createFakeDisplay({ finePointer: true, touchScreen: false });
+    const source = createPointerCapabilitiesSource(display.matchMedia);
+    const seen: boolean[] = [];
+    const unsubscribe = source.subscribe(() => seen.push(source.getSnapshot().touchScreen));
+
+    display.queries.touchScreen.setMatches(true);
+    display.queries.touchScreen.setMatches(false);
+    unsubscribe();
+    display.queries.touchScreen.setMatches(true);
+
+    expect(seen).toEqual([true, false]);
+  });
+
+  it("keeps one snapshot until an answer changes", () => {
+    const display = createFakeDisplay({ finePointer: false, touchScreen: true });
+    const source = createPointerCapabilitiesSource(display.matchMedia);
+    const first = source.getSnapshot();
+
+    expect(source.getSnapshot()).toBe(first);
+    display.queries.finePointer.setMatches(true);
+    expect(source.getSnapshot()).toEqual({ finePointer: true, touchScreen: true });
+  });
+
+  it("reports neither capability without media queries", () => {
+    expect(createPointerCapabilitiesSource(null).getSnapshot()).toEqual({
+      finePointer: false,
+      touchScreen: false,
+    });
+  });
+});
diff --git a/packages/app/src/hooks/pointer-capabilities.ts b/packages/app/src/hooks/pointer-capabilities.ts
new file mode 100644
index 0000000000..360ff88c24
--- /dev/null
+++ b/packages/app/src/hooks/pointer-capabilities.ts
@@ -0,0 +1,88 @@
+import { useSyncExternalStore } from "react";
+import { isWeb } from "@/constants/platform";
+
+// A touch tablet running the desktop layout is still `isWeb === false || true`
+// depending on the build, so neither platform gate answers "can this user
+// hover and point precisely" or "can this user touch the screen". Only the
+// media queries do, and the same queries notify when the answer changes
+// (detachable keyboards, tablet mode, devtools touch emulation).
+const FINE_POINTER_QUERY = "(hover: hover) and (pointer: fine)";
+const TOUCH_SCREEN_QUERY = "(any-pointer: coarse)";
+
+export interface PointerCapabilities {
+  /** A mouse-like pointer drives the UI. */
+  finePointer: boolean;
+  /** A touch screen is available, possibly next to a mouse on hybrid devices. */
+  touchScreen: boolean;
+}
+
+type MatchMedia = (query: string) => MediaQueryList;
+
+export interface PointerCapabilitiesSource {
+  getSnapshot: () => PointerCapabilities;
+  subscribe: (onChange: () => void) => () => void;
+}
+
+export function createPointerCapabilitiesSource(
+  matchMedia: MatchMedia | null,
+): PointerCapabilitiesSource {
+  const finePointerQuery = matchMedia?.(FINE_POINTER_QUERY) ?? null;
+  const touchScreenQuery = matchMedia?.(TOUCH_SCREEN_QUERY) ?? null;
+  let snapshot: PointerCapabilities = { finePointer: false, touchScreen: false };
+
+  return {
+    getSnapshot() {
+      const finePointer = finePointerQuery?.matches ?? false;
+      const touchScreen = touchScreenQuery?.matches ?? false;
+      if (snapshot.finePointer !== finePointer || snapshot.touchScreen !== touchScreen) {
+        snapshot = { finePointer, touchScreen };
+      }
+      return snapshot;
+    },
+    subscribe(onChange) {
+      finePointerQuery?.addEventListener("change", onChange);
+      touchScreenQuery?.addEventListener("change", onChange);
+      return () => {
+        finePointerQuery?.removeEventListener("change", onChange);
+        touchScreenQuery?.removeEventListener("change", onChange);
+      };
+    },
+  };
+}
+
+function browserMatchMedia(): MatchMedia | null {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return null;
+  return (query) => window.matchMedia(query);
+}
+
+// Native builds run on iOS and Android touch screens. A paired mouse or pen is
+// filtered per gesture event by its pointer type, not by this capability.
+const NATIVE_POINTER_CAPABILITIES: PointerCapabilities = { finePointer: false, touchScreen: true };
+const nativeSource: PointerCapabilitiesSource = {
+  getSnapshot: () => NATIVE_POINTER_CAPABILITIES,
+  subscribe: () => () => {},
+};
+
+const source = isWeb ? createPointerCapabilitiesSource(browserMatchMedia()) : nativeSource;
+const SERVER_SNAPSHOT: PointerCapabilities = { finePointer: false, touchScreen: false };
+
+function getServerSnapshot(): PointerCapabilities {
+  return SERVER_SNAPSHOT;
+}
+
+export function usePointerCapabilities(): PointerCapabilities {
+  return useSyncExternalStore(source.subscribe, source.getSnapshot, getServerSnapshot);
+}
+
+/** True when a mouse-like pointer drives the UI, read at call time. */
+export function hasFinePointer(): boolean {
+  return source.getSnapshot().finePointer;
+}
+
+/** Touch sizing remains enabled on hybrid browsers that report touch points. */
+export function hasTouchScreen(): boolean {
+  return (
+    source.getSnapshot().touchScreen ||
+    (isWeb && typeof window !== "undefined" && window.navigator.maxTouchPoints > 0)
+  );
+}
diff --git a/packages/app/src/hooks/use-fine-pointer.ts b/packages/app/src/hooks/use-fine-pointer.ts
deleted file mode 100644
index dcd8fe0853..0000000000
--- a/packages/app/src/hooks/use-fine-pointer.ts
+++ /dev/null
@@ -1,50 +0,0 @@
-import { useEffect, useState } from "react";
-import { isWeb } from "@/constants/platform";
-
-// A touch tablet running the desktop layout is still `isWeb === false || true`
-// depending on the build, so neither platform gate answers "can this user
-// hover and point precisely". Only the media query does.
-const FINE_POINTER_QUERY = "(hover: hover) and (pointer: fine)";
-
-function getFinePointerQueryList(): MediaQueryList | null {
-  if (!isWeb || typeof window === "undefined" || typeof window.matchMedia !== "function") {
-    return null;
-  }
-  return window.matchMedia(FINE_POINTER_QUERY);
-}
-
-/** True when a mouse-like pointer drives the UI. Always false on native. */
-export function hasFinePointer(): boolean {
-  return getFinePointerQueryList()?.matches ?? false;
-}
-
-/**
- * True when the device has a touch screen, even while a mouse or keyboard is attached to it:
- * the primary pointer is coarse, or the screen reports touch points. Always true on native.
- */
-export function hasTouchScreen(): boolean {
-  if (!isWeb) return true;
-  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return false;
-  return window.matchMedia("(pointer: coarse)").matches || window.navigator.maxTouchPoints > 0;
-}
-
-/**
- * Reactive `hasFinePointer()` — re-renders when the user switches between a
- * mouse and touch (detachable keyboards, tablet mode).
- */
-export function useHasFinePointer(): boolean {
-  const [finePointer, setFinePointer] = useState(hasFinePointer);
-
-  useEffect(() => {
-    const mediaQuery = getFinePointerQueryList();
-    if (!mediaQuery) return;
-    const handleChange = () => setFinePointer(mediaQuery.matches);
-    handleChange();
-    mediaQuery.addEventListener?.("change", handleChange);
-    return () => {
-      mediaQuery.removeEventListener?.("change", handleChange);
-    };
-  }, []);
-
-  return finePointer;
-}
diff --git a/packages/app/src/mobile-panels/gesture-intent.test.ts b/packages/app/src/mobile-panels/gesture-intent.test.ts
index 74035096fb..a85c25e81b 100644
--- a/packages/app/src/mobile-panels/gesture-intent.test.ts
+++ b/packages/app/src/mobile-panels/gesture-intent.test.ts
@@ -3,19 +3,36 @@ import { describe, expect, it } from "vitest";
 import { resolveMobilePanelGestureIntent } from "./gesture-intent";
 
 describe("mobile panel gesture intent", () => {
+  it("rejects a pending swipe when presentation changes before activation", () => {
+    expect(
+      resolveMobilePanelGestureIntent({
+        enabled: false,
+        deltaX: 40,
+        deltaY: 2,
+        direction: 1,
+        openGesturesBlocked: false,
+        openEdge: null,
+      }),
+    ).toBe("fail");
+  });
+
   it("blocks both panel-opening directions while the active surface owns horizontal dragging", () => {
     expect([
       resolveMobilePanelGestureIntent({
+        enabled: true,
         deltaX: 40,
         deltaY: 2,
         direction: 1,
         openGesturesBlocked: true,
+        openEdge: null,
       }),
       resolveMobilePanelGestureIntent({
+        enabled: true,
         deltaX: -40,
         deltaY: 2,
         direction: -1,
         openGesturesBlocked: true,
+        openEdge: null,
       }),
     ]).toEqual(["fail", "fail"]);
   });
@@ -23,17 +40,68 @@ describe("mobile panel gesture intent", () => {
   it("keeps ordinary horizontal panel gestures available when unblocked", () => {
     expect([
       resolveMobilePanelGestureIntent({
+        enabled: true,
         deltaX: 40,
         deltaY: 2,
         direction: 1,
         openGesturesBlocked: false,
+        openEdge: null,
       }),
       resolveMobilePanelGestureIntent({
+        enabled: true,
         deltaX: -40,
         deltaY: 2,
         direction: -1,
         openGesturesBlocked: false,
+        openEdge: null,
       }),
     ]).toEqual(["activate", "activate"]);
   });
+
+  it("opens phone web drawers only from the edge they slide in from", () => {
+    const swipe = { deltaY: 2, openGesturesBlocked: false };
+    expect([
+      resolveMobilePanelGestureIntent({
+        enabled: true,
+        ...swipe,
+        deltaX: 40,
+        direction: 1,
+        openEdge: { startX: 200, windowWidth: 400 },
+      }),
+      resolveMobilePanelGestureIntent({
+        enabled: true,
+        ...swipe,
+        deltaX: 40,
+        direction: 1,
+        openEdge: { startX: 12, windowWidth: 400 },
+      }),
+      resolveMobilePanelGestureIntent({
+        enabled: true,
+        ...swipe,
+        deltaX: -40,
+        direction: -1,
+        openEdge: { startX: 200, windowWidth: 400 },
+      }),
+      resolveMobilePanelGestureIntent({
+        enabled: true,
+        ...swipe,
+        deltaX: -40,
+        direction: -1,
+        openEdge: { startX: 388, windowWidth: 400 },
+      }),
+    ]).toEqual(["fail", "activate", "fail", "activate"]);
+  });
+
+  it("opens from anywhere when the layout does not require an edge start", () => {
+    expect(
+      resolveMobilePanelGestureIntent({
+        enabled: true,
+        deltaX: 40,
+        deltaY: 2,
+        direction: 1,
+        openGesturesBlocked: false,
+        openEdge: null,
+      }),
+    ).toBe("activate");
+  });
 });
diff --git a/packages/app/src/mobile-panels/gesture-intent.ts b/packages/app/src/mobile-panels/gesture-intent.ts
index 3399670924..6722ec0c0f 100644
--- a/packages/app/src/mobile-panels/gesture-intent.ts
+++ b/packages/app/src/mobile-panels/gesture-intent.ts
@@ -1,14 +1,39 @@
 export type MobilePanelGestureDirection = -1 | 1;
 export type MobilePanelGestureIntent = "activate" | "fail" | "wait";
 
+/** How far from the window edge an edge-only open gesture may start. */
+export const MOBILE_PANEL_OPEN_EDGE_WIDTH = 32;
+
+/**
+ * Where an edge-only open gesture started. Phone web opens drawers only from the edge they slide in
+ * from: interior horizontal scrollers (terminals, code blocks, diffs) keep their swipes there.
+ */
+export interface MobilePanelOpenEdge {
+  startX: number;
+  windowWidth: number;
+}
+
+function startsAtOpenEdge(edge: MobilePanelOpenEdge, direction: MobilePanelGestureDirection) {
+  "worklet";
+  return direction === 1
+    ? edge.startX <= MOBILE_PANEL_OPEN_EDGE_WIDTH
+    : edge.startX >= edge.windowWidth - MOBILE_PANEL_OPEN_EDGE_WIDTH;
+}
+
 export function resolveMobilePanelGestureIntent(input: {
+  enabled: boolean;
   deltaX: number;
   deltaY: number;
   direction: MobilePanelGestureDirection;
   openGesturesBlocked: boolean;
+  /** Required start edge for opening gestures, or `null` when they may start anywhere. */
+  openEdge: MobilePanelOpenEdge | null;
 }): MobilePanelGestureIntent {
   "worklet";
-  if (input.openGesturesBlocked) {
+  if (!input.enabled || input.openGesturesBlocked) {
+    return "fail";
+  }
+  if (input.openEdge && !startsAtOpenEdge(input.openEdge, input.direction)) {
     return "fail";
   }
   const directedDelta = input.deltaX * input.direction;
diff --git a/packages/app/src/mobile-panels/gestures.ts b/packages/app/src/mobile-panels/gestures.ts
index 2b3f3e11fe..c95c69aba4 100644
--- a/packages/app/src/mobile-panels/gestures.ts
+++ b/packages/app/src/mobile-panels/gestures.ts
@@ -1,16 +1,16 @@
 import { createContext, useContext, useRef, type RefObject, useCallback, useMemo } from "react";
-import { Gesture, type GestureType } from "react-native-gesture-handler";
-import { useSharedValue } from "react-native-reanimated";
+import { Gesture, PointerType, type GestureType } from "react-native-gesture-handler";
+import { useDerivedValue, useSharedValue } from "react-native-reanimated";
 import { scheduleOnRN } from "react-native-worklets";
+import { useIsCompactFormFactor } from "@/constants/layout";
 import { isWeb } from "@/constants/platform";
 import { useHorizontalScrollOptional } from "@/contexts/horizontal-scroll-context";
+import { usePointerCapabilities } from "@/hooks/pointer-capabilities";
 import { usePanelStore } from "@/stores/panel-store";
 import { canBeginMobilePanelGesture, isMobilePanelGestureCurrent } from "./model";
 import { useMobilePanelsRuntime } from "./provider";
 import { resolveMobilePanelGestureIntent } from "./gesture-intent";
 
-const MOBILE_WEB_EDGE_SWIPE_WIDTH = 32;
-
 function isCurrentSelection(startedRevision: number): boolean {
   return usePanelStore.getState().mobilePanel.revision === startedRevision;
 }
@@ -23,6 +23,15 @@ function useGestureState() {
   };
 }
 
+/**
+ * Gates a sidebar pan on the UI thread. The sidebar flips between the dock and the overlay at
+ * runtime, and on Android flipping the handler's `.enabled()` config from false back to true left
+ * it inert until the app reloaded (RNGH 2.32), so `.enabled()` only carries the device capability.
+ */
+function useGestureGate(enabled: boolean) {
+  return useDerivedValue(() => enabled, [enabled]);
+}
+
 function useRevisionCommit(action: () => void) {
   return useCallback(
     (revision: number) => {
@@ -39,24 +48,35 @@ export function useOpenAgentListGesture(enabled: boolean) {
     beginGesture,
     finishGesture,
     leftOpenGestureRef,
+    leftPanelWidth: width,
     motionState,
     openGesturesBlocked,
     position,
     updateGesture,
     windowWidth,
   } = useMobilePanelsRuntime();
+  const { touchScreen: hasTouchScreen } = usePointerCapabilities();
+  // Phone web keeps interior swipes for the page's horizontal scrollers; the wide overlay opens
+  // from anywhere in the workspace.
+  const isCompact = useIsCompactFormFactor();
+  const openFromEdgeOnly = isWeb && isCompact;
   const horizontalScroll = useHorizontalScrollOptional();
   const { startedRevision, touchStartX, touchStartY } = useGestureState();
   const showMobileAgentList = usePanelStore((state) => state.showMobileAgentList);
   const commit = useRevisionCommit(showMobileAgentList);
+  const gate = useGestureGate(enabled);
 
   return useMemo(
     () =>
       Gesture.Pan()
         .withRef(leftOpenGestureRef)
-        .enabled(enabled)
+        .enabled(hasTouchScreen)
         .manualActivation(true)
-        .onTouchesDown((event) => {
+        .onTouchesDown((event, stateManager) => {
+          if (!gate.value || event.pointerType !== PointerType.TOUCH) {
+            stateManager.fail();
+            return;
+          }
           const touch = event.changedTouches[0];
           if (touch) {
             touchStartX.value = touch.absoluteX;
@@ -76,15 +96,16 @@ export function useOpenAgentListGesture(enabled: boolean) {
           }
 
           const panIntent = resolveMobilePanelGestureIntent({
+            enabled: gate.value,
             deltaX,
             deltaY,
             direction: 1,
             openGesturesBlocked: openGesturesBlocked.value,
+            openEdge: openFromEdgeOnly ? { startX: touchStartX.value, windowWidth } : null,
           });
           if (
             !canBeginMobilePanelGesture(motionState.value, "agent", position.value) ||
             horizontalScroll?.isAnyScrolledRight.value ||
-            (isWeb && touchStartX.value > MOBILE_WEB_EDGE_SWIPE_WIDTH) ||
             panIntent === "fail"
           ) {
             stateManager.fail();
@@ -98,10 +119,10 @@ export function useOpenAgentListGesture(enabled: boolean) {
           startedRevision.value = beginGesture({ origin: "agent" });
         })
         .onUpdate((event) => {
-          updateGesture(startedRevision.value, -event.translationX / windowWidth);
+          updateGesture(startedRevision.value, -event.translationX / width);
         })
         .onEnd((event, success) => {
-          const shouldOpen = event.translationX > windowWidth / 3 || event.velocityX > 500;
+          const shouldOpen = event.translationX > width / 3 || event.velocityX > 500;
           const result = finishGesture({
             startedRevision: startedRevision.value,
             target: shouldOpen ? "agent-list" : "agent",
@@ -113,43 +134,53 @@ export function useOpenAgentListGesture(enabled: boolean) {
         }),
     [
       commit,
-      enabled,
       beginGesture,
+      gate,
       finishGesture,
+      hasTouchScreen,
       horizontalScroll?.isAnyScrolledRight,
       leftOpenGestureRef,
       motionState,
+      openFromEdgeOnly,
       openGesturesBlocked,
       position,
       startedRevision,
       touchStartX,
       touchStartY,
       updateGesture,
+      width,
       windowWidth,
     ],
   );
 }
 
-export function useCloseAgentListGesture() {
+export function useCloseAgentListGesture(enabled = true) {
   const {
     beginGesture,
     finishGesture,
     leftCloseGestureRef,
+    leftPanelWidth: width,
     motionState,
     position,
     updateGesture,
-    windowWidth,
   } = useMobilePanelsRuntime();
+  const { touchScreen: hasTouchScreen } = usePointerCapabilities();
   const { startedRevision, touchStartX, touchStartY } = useGestureState();
   const showMobileAgent = usePanelStore((state) => state.showMobileAgent);
   const commit = useRevisionCommit(showMobileAgent);
+  const gate = useGestureGate(enabled);
 
   const gesture = useMemo(
     () =>
       Gesture.Pan()
         .withRef(leftCloseGestureRef)
+        .enabled(hasTouchScreen)
         .manualActivation(true)
-        .onTouchesDown((event) => {
+        .onTouchesDown((event, stateManager) => {
+          if (!gate.value || event.pointerType !== PointerType.TOUCH) {
+            stateManager.fail();
+            return;
+          }
           const touch = event.changedTouches[0];
           if (touch) {
             touchStartX.value = touch.absoluteX;
@@ -169,10 +200,12 @@ export function useCloseAgentListGesture() {
           }
 
           const panIntent = resolveMobilePanelGestureIntent({
+            enabled: gate.value,
             deltaX,
             deltaY,
             direction: -1,
             openGesturesBlocked: false,
+            openEdge: null,
           });
           if (
             !canBeginMobilePanelGesture(motionState.value, "agent-list", position.value) ||
@@ -191,10 +224,10 @@ export function useCloseAgentListGesture() {
           });
         })
         .onUpdate((event) => {
-          updateGesture(startedRevision.value, -1 - event.translationX / windowWidth);
+          updateGesture(startedRevision.value, -1 - event.translationX / width);
         })
         .onEnd((event, success) => {
-          const shouldClose = event.translationX < -windowWidth / 3 || event.velocityX < -500;
+          const shouldClose = event.translationX < -width / 3 || event.velocityX < -500;
           const result = finishGesture({
             startedRevision: startedRevision.value,
             target: shouldClose ? "agent" : "agent-list",
@@ -207,6 +240,8 @@ export function useCloseAgentListGesture() {
     [
       beginGesture,
       commit,
+      gate,
+      hasTouchScreen,
       finishGesture,
       leftCloseGestureRef,
       motionState,
@@ -215,7 +250,7 @@ export function useCloseAgentListGesture() {
       touchStartX,
       touchStartY,
       updateGesture,
-      windowWidth,
+      width,
     ],
   );
 
@@ -269,14 +304,15 @@ export function useOpenFileExplorerGesture({ enabled, onOpen }: OpenFileExplorer
           }
 
           const panIntent = resolveMobilePanelGestureIntent({
+            enabled: enabled,
             deltaX,
             deltaY,
             direction: -1,
             openGesturesBlocked: openGesturesBlocked.value,
+            openEdge: isWeb ? { startX: touchStartX.value, windowWidth } : null,
           });
           if (
             !canBeginMobilePanelGesture(motionState.value, "agent", position.value) ||
-            (isWeb && touchStartX.value < windowWidth - MOBILE_WEB_EDGE_SWIPE_WIDTH) ||
             panIntent === "fail"
           ) {
             stateManager.fail();
@@ -363,10 +399,12 @@ export function useCloseFileExplorerGesture(enabled = true) {
           }
 
           const panIntent = resolveMobilePanelGestureIntent({
+            enabled: enabled,
             deltaX,
             deltaY,
             direction: 1,
             openGesturesBlocked: false,
+            openEdge: null,
           });
           if (
             !canBeginMobilePanelGesture(motionState.value, "file-explorer", position.value) ||
diff --git a/packages/app/src/mobile-panels/model.test.ts b/packages/app/src/mobile-panels/model.test.ts
index 5e2d8e229c..ca4ef04a8a 100644
--- a/packages/app/src/mobile-panels/model.test.ts
+++ b/packages/app/src/mobile-panels/model.test.ts
@@ -17,6 +17,7 @@ class MobilePanelsScenario {
   private startedRevision = -1;
   private state: MobilePanelMotionState;
   readonly commits: MobilePanelCommit[] = [];
+  readonly animations: MobilePanelView[] = [];
 
   constructor(target: MobilePanelView = "agent") {
     this.state = createMobilePanelMotionState({ target, revision: this.nextRevision });
@@ -74,6 +75,9 @@ class MobilePanelsScenario {
     if (transition.commit) {
       this.commits.push(transition.commit);
     }
+    if (transition.animationTarget) {
+      this.animations.push(transition.animationTarget);
+    }
   }
 }
 
@@ -237,6 +241,29 @@ describe("mobile panel ownership", () => {
     expect(panels.commits).toEqual([]);
   });
 
+  it("returns an interrupted drag to the anchor when the command keeps its target", () => {
+    const panels = new MobilePanelsScenario();
+
+    panels.beginGesture("agent").command("agent").finishGesture("agent-list");
+
+    expect(panels.animations).toEqual(["agent"]);
+    expect(panels.snapshot()).toEqual({
+      target: "agent",
+      motionTarget: "agent",
+      settledTarget: "agent",
+      revision: 1,
+    });
+    expect(panels.commits).toEqual([]);
+  });
+
+  it("lets the command for a completed drag adopt the drag's finishing motion", () => {
+    const panels = new MobilePanelsScenario();
+
+    panels.beginGesture("agent").finishGesture("agent-list").command("agent-list");
+
+    expect(panels.animations).toEqual(["agent-list"]);
+  });
+
   it("keeps the latest rapid command when position reaches a stale anchor", () => {
     const panels = new MobilePanelsScenario();
 
diff --git a/packages/app/src/mobile-panels/model.ts b/packages/app/src/mobile-panels/model.ts
index a7b821e82e..363bcfc450 100644
--- a/packages/app/src/mobile-panels/model.ts
+++ b/packages/app/src/mobile-panels/model.ts
@@ -78,7 +78,9 @@ export function transitionMobilePanel(
     if (event.selection.revision <= state.revision) {
       return { state };
     }
-    const continuesCurrentMotion = state.motionTarget === event.selection.target;
+    // An interrupted drag left the position between anchors, so it moves back even when the
+    // target is unchanged. Without a drag, the command adopts motion already heading there.
+    const continuesCurrentMotion = !state.gesture && state.motionTarget === event.selection.target;
     return {
       animationTarget: continuesCurrentMotion ? undefined : event.selection.target,
       state: {
diff --git a/packages/app/src/mobile-panels/presentation.tsx b/packages/app/src/mobile-panels/presentation.tsx
index cb919e4595..7336e7c029 100644
--- a/packages/app/src/mobile-panels/presentation.tsx
+++ b/packages/app/src/mobile-panels/presentation.tsx
@@ -29,26 +29,27 @@ export function MobilePanelOverlay({
   dockVisible = false,
   frameStyle,
 }: MobilePanelOverlayProps) {
-  const { position, windowWidth } = useMobilePanelsRuntime();
+  const { leftPanelWidth, position, windowWidth } = useMobilePanelsRuntime();
   const showMobileAgent = usePanelStore((state) => state.showMobileAgent);
   const overlayOpen = useIsMobilePanelActive(panel);
   const docked = presentation === "dock";
   const isOpen = docked ? dockVisible : overlayOpen;
   const hostId = useId();
   const isLeft = panel === "agent-list";
+  const width = isLeft ? leftPanelWidth : windowWidth;
 
   const sidebarAnimatedStyle = useAnimatedStyle(() => {
     if (docked) return { transform: [{ translateX: 0 }] };
-    const frame = getMobilePanelFrame(position.value, windowWidth);
+    const frame = getMobilePanelFrame(position.value, width);
     return {
       transform: [{ translateX: isLeft ? frame.leftTranslateX : frame.rightTranslateX }],
     };
-  }, [docked, isLeft, windowWidth]);
+  }, [docked, isLeft, width]);
 
   const backdropAnimatedStyle = useAnimatedStyle(() => {
-    const frame = getMobilePanelFrame(position.value, windowWidth);
+    const frame = getMobilePanelFrame(position.value, width);
     return { opacity: isLeft ? frame.leftBackdropOpacity : frame.rightBackdropOpacity };
-  }, [isLeft, windowWidth]);
+  }, [isLeft, width]);
 
   const overlayAnimatedStyle = useAnimatedStyle(() => {
     if (docked) return { opacity: 1, display: "flex" as const, pointerEvents: "box-none" as const };
@@ -73,11 +74,11 @@ export function MobilePanelOverlay({
     () => [
       docked ? styles.dockedPanel : styles.panel,
       !docked && positionedPanelStyle,
-      !docked && { width: windowWidth },
+      !docked && { width },
       panelStyle,
       sidebarAnimatedStyle,
     ],
-    [docked, panelStyle, positionedPanelStyle, sidebarAnimatedStyle, windowWidth],
+    [docked, panelStyle, positionedPanelStyle, sidebarAnimatedStyle, width],
   );
   let overlayPointerEvents: "auto" | "box-none" | "none";
   if (!isWeb) {
diff --git a/packages/app/src/mobile-panels/provider.tsx b/packages/app/src/mobile-panels/provider.tsx
index b2f97a2547..77c00558ce 100644
--- a/packages/app/src/mobile-panels/provider.tsx
+++ b/packages/app/src/mobile-panels/provider.tsx
@@ -1,3 +1,6 @@
+import { useWindowLayout, resolveDesktopDivisionLayout } from "@/window-layout";
+import { subscribeMobilePanelSelection } from "./selection";
+
 import {
   createContext,
   useCallback,
@@ -20,7 +23,10 @@ import {
   withTiming,
   type SharedValue,
 } from "react-native-reanimated";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { scheduleOnRN, scheduleOnUI } from "react-native-worklets";
+import { resolveDesktopSidebarWidth } from "@/components/desktop-sidebar-layout";
+import { useIsCompactFormFactor } from "@/constants/layout";
 import { isNative } from "@/constants/platform";
 import {
   usePanelStore,
@@ -45,6 +51,7 @@ interface MobilePanelsRuntime {
   beginGesture: (input: BeginGestureInput) => number;
   finishGesture: (input: FinishGestureInput) => MobilePanelCommit | null;
   leftCloseGestureRef: RefObject<GestureType | undefined>;
+  leftPanelWidth: number;
   leftOpenGestureRef: RefObject<GestureType | undefined>;
   motionState: SharedValue<MobilePanelMotionState>;
   openGesturesBlocked: SharedValue<boolean>;
@@ -68,8 +75,36 @@ interface FinishGestureInput {
 const MobilePanelsContext = createContext<MobilePanelsRuntime | null>(null);
 const MobilePanelActiveContext = createContext<MobilePanelView>("agent");
 
+/**
+ * The left sidebar's width: the full window for the compact drawer, the saved sidebar width
+ * clamped to the safe viewport on wide layouts. The wide dock, its overlay, and the gestures that
+ * drag it all read this one value.
+ */
+function useResolvedLeftPanelWidth(windowWidth: number): number {
+  const isCompact = useIsCompactFormFactor();
+  const insets = useSafeAreaInsets();
+  const sidebarWidth = usePanelStore((state) => state.sidebarWidth);
+  const { height: windowHeight } = useWindowDimensions();
+  const divisionLayout = resolveDesktopDivisionLayout({
+    geometry: useWindowLayout(),
+    windowWidth,
+    windowHeight,
+    leftInset: insets.left,
+    rightInset: insets.right,
+  });
+  if (isCompact) return windowWidth;
+  return (
+    divisionLayout?.sidebarWidth ??
+    resolveDesktopSidebarWidth({
+      requestedWidth: sidebarWidth,
+      viewportWidth: windowWidth - insets.left - insets.right,
+    })
+  );
+}
+
 export function MobilePanelsProvider({ children }: { children: ReactNode }) {
   const { width: windowWidth } = useWindowDimensions();
+  const leftPanelWidth = useResolvedLeftPanelWidth(windowWidth);
   const initialSelection = useRef(usePanelStore.getState().mobilePanel).current;
   const position = useSharedValue(getMobilePanelAnchor(initialSelection.target));
   const motionState = useSharedValue(createMobilePanelMotionState(initialSelection));
@@ -152,11 +187,7 @@ export function MobilePanelsProvider({ children }: { children: ReactNode }) {
   );
 
   useEffect(() => {
-    return usePanelStore.subscribe((state, previousState) => {
-      const selection = state.mobilePanel;
-      if (selection === previousState.mobilePanel) {
-        return;
-      }
+    return subscribeMobilePanelSelection((selection) => {
       scheduleOnUI(applySelection, selection);
     });
   }, [applySelection]);
@@ -217,6 +248,7 @@ export function MobilePanelsProvider({ children }: { children: ReactNode }) {
       finishGesture,
       leftCloseGestureRef,
       leftOpenGestureRef,
+      leftPanelWidth,
       motionState,
       openGesturesBlocked,
       position,
@@ -228,6 +260,7 @@ export function MobilePanelsProvider({ children }: { children: ReactNode }) {
     [
       beginGesture,
       finishGesture,
+      leftPanelWidth,
       motionState,
       openGesturesBlocked,
       position,
@@ -255,6 +288,11 @@ export function useMobilePanelsRuntime(): MobilePanelsRuntime {
   return context;
 }
 
+/** The resolved left sidebar width shared by the dock, the overlay, and their gestures. */
+export function useLeftPanelWidth(): number {
+  return useMobilePanelsRuntime().leftPanelWidth;
+}
+
 export function useIsMobilePanelActive(panel: MobilePanelView): boolean {
   return useContext(MobilePanelActiveContext) === panel;
 }
diff --git a/packages/app/src/mobile-panels/selection.ts b/packages/app/src/mobile-panels/selection.ts
new file mode 100644
index 0000000000..f47d9e737c
--- /dev/null
+++ b/packages/app/src/mobile-panels/selection.ts
@@ -0,0 +1,14 @@
+import { usePanelStore, type MobilePanelSelection } from "@/stores/panel-store";
+
+/** Observe panel commands, including layout commands published before subscription. */
+export function subscribeMobilePanelSelection(
+  onSelection: (selection: MobilePanelSelection) => void,
+) {
+  const unsubscribe = usePanelStore.subscribe((state, previousState) => {
+    if (state.mobilePanel !== previousState.mobilePanel) {
+      onSelection(state.mobilePanel);
+    }
+  });
+  onSelection(usePanelStore.getState().mobilePanel);
+  return unsubscribe;
+}
diff --git a/packages/app/src/stores/navigation-active-workspace-store/index.ts b/packages/app/src/stores/navigation-active-workspace-store/index.ts
index 16f3a23f0b..def8c73cc4 100644
--- a/packages/app/src/stores/navigation-active-workspace-store/index.ts
+++ b/packages/app/src/stores/navigation-active-workspace-store/index.ts
@@ -38,9 +38,7 @@ function navigateDeps(): NavigateToWorkspaceDeps {
   return {
     revealTab: revealWorkspaceTab,
     revealWorkspace: () => {
-      if (useWorkspaceLayoutStore.getState().layoutMode === "compact") {
-        usePanelStore.getState().showMobileAgent();
-      }
+      usePanelStore.getState().showMobileAgent();
     },
     getSessionWorkspaces: (serverId) => useSessionStore.getState().sessions[serverId]?.workspaces,
     getSessionAgents: (serverId) =>
diff --git a/packages/app/src/stores/panel-store/index.ts b/packages/app/src/stores/panel-store/index.ts
index 8af964f181..660f2d1b62 100644
--- a/packages/app/src/stores/panel-store/index.ts
+++ b/packages/app/src/stores/panel-store/index.ts
@@ -5,6 +5,7 @@ import {
   clampTreeRailWidth,
   clampSidebarWidth,
   DEFAULT_TREE_RAIL_WIDTH,
+  dropOverlayAgentList,
   DEFAULT_SIDEBAR_WIDTH,
   MAX_TREE_RAIL_WIDTH,
   MAX_SIDEBAR_WIDTH,
@@ -15,9 +16,11 @@ import {
   selectIsAgentListOpen,
   selectIsCompactFileExplorerOpen,
   setMobilePanelTarget,
+  reconcileMobilePanel,
   type DesktopSidebarState,
   type MobilePanelView,
   type MobilePanelSelection,
+  type PanelLayout,
   type PanelLayoutInput,
   type SortOption,
 } from "./state";
@@ -25,8 +28,10 @@ import { isWeb } from "@/constants/platform";
 import { createValidatedPersistStorage } from "@/storage/validated-persist-storage";
 export type {
   DesktopSidebarState,
+  LeftSidebarPresentation,
   MobilePanelView,
   MobilePanelSelection,
+  PanelLayout,
   PanelLayoutInput,
   SortOption,
 } from "./state";
@@ -80,6 +85,7 @@ export interface PanelState {
   openAgentListForLayout: (input: PanelLayoutInput) => void;
   closeAgentListForLayout: (input: PanelLayoutInput) => void;
   toggleAgentListForLayout: (input: PanelLayoutInput) => void;
+  applyPanelLayout: (layout: PanelLayout) => void;
 
   // File explorer settings actions
   setExpandedPathsForWorkspace: (workspaceKey: string, paths: ExpandedPathsUpdate) => void;
@@ -102,6 +108,13 @@ function setMobilePanelTargetPatch(
   return mobilePanel === state.mobilePanel ? state : { mobilePanel };
 }
 
+function dockAgentListPatch(state: PanelState): Pick<PanelState, "desktop" | "mobilePanel"> {
+  return {
+    desktop: { ...state.desktop, agentListOpen: true },
+    mobilePanel: dropOverlayAgentList(state.mobilePanel),
+  };
+}
+
 export const usePanelStore = create<PanelState>()(
   persist(
     (set) => ({
@@ -151,12 +164,7 @@ export const usePanelStore = create<PanelState>()(
         ),
 
       openDesktopAgentList: () =>
-        set((state) => {
-          if (state.desktop.agentListOpen) {
-            return state;
-          }
-          return { desktop: { ...state.desktop, agentListOpen: true } };
-        }),
+        set((state) => (state.desktop.agentListOpen ? state : dockAgentListPatch(state))),
 
       closeDesktopAgentList: () =>
         set((state) => {
@@ -167,18 +175,18 @@ export const usePanelStore = create<PanelState>()(
         }),
 
       toggleDesktopAgentList: () =>
-        set((state) => ({
-          desktop: { ...state.desktop, agentListOpen: !state.desktop.agentListOpen },
-        })),
+        set((state) =>
+          state.desktop.agentListOpen
+            ? { desktop: { ...state.desktop, agentListOpen: false } }
+            : dockAgentListPatch(state),
+        ),
 
       openAgentListForLayout: ({ isCompact }) =>
         set((state) => {
           if (isCompact) {
             return setMobilePanelTargetPatch(state, "agent-list");
           }
-          return state.desktop.agentListOpen
-            ? state
-            : { desktop: { ...state.desktop, agentListOpen: true } };
+          return state.desktop.agentListOpen ? state : dockAgentListPatch(state);
         }),
 
       closeAgentListForLayout: ({ isCompact }) =>
@@ -199,9 +207,15 @@ export const usePanelStore = create<PanelState>()(
               state.mobilePanel.target === "agent-list" ? "agent" : "agent-list",
             );
           }
-          return {
-            desktop: { ...state.desktop, agentListOpen: !state.desktop.agentListOpen },
-          };
+          return state.desktop.agentListOpen
+            ? { desktop: { ...state.desktop, agentListOpen: false } }
+            : dockAgentListPatch(state);
+        }),
+
+      applyPanelLayout: (layout) =>
+        set((state) => {
+          const mobilePanel = reconcileMobilePanel(state.mobilePanel, layout);
+          return mobilePanel === state.mobilePanel ? state : { mobilePanel };
         }),
 
       setExpandedPathsForWorkspace: (workspaceKey, paths) =>
diff --git a/packages/app/src/stores/panel-store/state.test.ts b/packages/app/src/stores/panel-store/state.test.ts
index ad52b8a8c4..317d4fd9a8 100644
--- a/packages/app/src/stores/panel-store/state.test.ts
+++ b/packages/app/src/stores/panel-store/state.test.ts
@@ -1,4 +1,6 @@
-import { describe, expect, it } from "vitest";
+import { subscribeMobilePanelSelection } from "@/mobile-panels/selection";
+import { beforeEach, describe, expect, it } from "vitest";
+import { usePanelStore } from ".";
 import {
   DEFAULT_TREE_RAIL_WIDTH,
   migratePanelState,
@@ -122,3 +124,101 @@ it("discards obsolete checkout selection while preserving other panel preference
   expect(state).not.toHaveProperty("explorerTabByCheckout");
   expect(state.sidebarWidth).toBe(400);
 });
+
+describe("panel-store wide navigation overlay", () => {
+  it("subscribes with the current selection and observes future commands until unsubscribe", () => {
+    usePanelStore.getState().showMobileAgent();
+    usePanelStore.getState().applyPanelLayout({ isCompact: false, leftSidebar: "hidden" });
+    const published = usePanelStore.getState().mobilePanel;
+    const received: (typeof published)[] = [];
+    const unsubscribe = subscribeMobilePanelSelection((selection) => received.push(selection));
+    try {
+      expect(received).toEqual([published]);
+      usePanelStore.getState().showMobileAgentList();
+      expect(received).toEqual([published, usePanelStore.getState().mobilePanel]);
+      unsubscribe();
+      const before = [...received];
+      usePanelStore.getState().showMobileAgent();
+      expect(received).toEqual(before);
+    } finally {
+      unsubscribe();
+    }
+  });
+
+  beforeEach(() => {
+    const panels = usePanelStore.getState();
+    panels.showMobileAgent();
+    panels.closeDesktopAgentList();
+  });
+
+  it.each([
+    ["openDesktopAgentList", () => usePanelStore.getState().openDesktopAgentList()],
+    ["toggleDesktopAgentList", () => usePanelStore.getState().toggleDesktopAgentList()],
+    [
+      "openAgentListForLayout",
+      () => usePanelStore.getState().openAgentListForLayout({ isCompact: false }),
+    ],
+    [
+      "toggleAgentListForLayout",
+      () => usePanelStore.getState().toggleAgentListForLayout({ isCompact: false }),
+    ],
+  ])("drops the overlay target when %s docks the sidebar", (_name, dock) => {
+    usePanelStore.getState().showMobileAgentList();
+
+    dock();
+
+    expect(usePanelStore.getState().desktop.agentListOpen).toBe(true);
+    expect(usePanelStore.getState().mobilePanel.target).toBe("agent");
+  });
+
+  it("drops the overlay target once the sidebar is no longer presented as an overlay", () => {
+    usePanelStore.getState().showMobileAgentList();
+    usePanelStore.getState().applyPanelLayout({ isCompact: false, leftSidebar: "overlay" });
+    expect(usePanelStore.getState().mobilePanel.target).toBe("agent-list");
+
+    usePanelStore.getState().applyPanelLayout({ isCompact: false, leftSidebar: "dock" });
+    expect(usePanelStore.getState().mobilePanel.target).toBe("agent");
+
+    usePanelStore.getState().showMobileAgentList();
+    usePanelStore.getState().applyPanelLayout({ isCompact: false, leftSidebar: "hidden" });
+    expect(usePanelStore.getState().mobilePanel.target).toBe("agent");
+  });
+
+  it.each(["dock", "hidden"] as const)(
+    "invalidates an opening swipe when presentation becomes %s before its target commits",
+    (presentation) => {
+      usePanelStore.getState().applyPanelLayout({ isCompact: false, leftSidebar: "overlay" });
+      const startedRevision = usePanelStore.getState().mobilePanel.revision;
+      expect(usePanelStore.getState().mobilePanel.target).toBe("agent");
+
+      usePanelStore.getState().applyPanelLayout({ isCompact: false, leftSidebar: presentation });
+
+      expect(usePanelStore.getState().mobilePanel.target).toBe("agent");
+      expect(usePanelStore.getState().mobilePanel.revision).toBeGreaterThan(startedRevision);
+    },
+  );
+
+  it.each(["overlay", "hidden"] as const)(
+    "keeps the compact explorer target when the compact sidebar becomes %s",
+    (leftSidebar) => {
+      usePanelStore.getState().showMobileFileExplorer();
+
+      usePanelStore.getState().applyPanelLayout({ isCompact: true, leftSidebar });
+
+      expect(usePanelStore.getState().mobilePanel.target).toBe("file-explorer");
+    },
+  );
+
+  it.each(["overlay", "dock", "hidden"] as const)(
+    "drops the compact explorer target when the layout widens with a %s sidebar",
+    (leftSidebar) => {
+      usePanelStore.getState().showMobileFileExplorer();
+      const openedRevision = usePanelStore.getState().mobilePanel.revision;
+
+      usePanelStore.getState().applyPanelLayout({ isCompact: false, leftSidebar });
+
+      expect(usePanelStore.getState().mobilePanel.target).toBe("agent");
+      expect(usePanelStore.getState().mobilePanel.revision).toBeGreaterThan(openedRevision);
+    },
+  );
+});
diff --git a/packages/app/src/stores/panel-store/state.ts b/packages/app/src/stores/panel-store/state.ts
index cbbead4161..a9971fa458 100644
--- a/packages/app/src/stores/panel-store/state.ts
+++ b/packages/app/src/stores/panel-store/state.ts
@@ -26,6 +26,14 @@ export interface PanelLayoutInput {
   isCompact: boolean;
 }
 
+/** How app chrome presents the left sidebar: over the workspace, beside it, or not at all. */
+export type LeftSidebarPresentation = "overlay" | "dock" | "hidden";
+
+/** The panels app chrome presents, which decide the mobile panel targets that can stay selected. */
+export interface PanelLayout extends PanelLayoutInput {
+  leftSidebar: LeftSidebarPresentation;
+}
+
 export interface PanelCoreState {
   mobilePanel: MobilePanelSelection;
   desktop: DesktopSidebarState;
@@ -68,6 +76,35 @@ export function setMobilePanelTarget(
   return { target, revision: selection.revision + 1 };
 }
 
+/**
+ * Only an overlay sidebar shows the `agent-list` target. A docked or hidden sidebar drops it, so
+ * a stale target cannot resurface the overlay on the next collapse. Always invalidate in-flight
+ * gestures, even when an opening swipe has not committed `agent-list` yet.
+ */
+export function dropOverlayAgentList(selection: MobilePanelSelection): MobilePanelSelection {
+  return {
+    target: selection.target === "agent-list" ? "agent" : selection.target,
+    revision: selection.revision + 1,
+  };
+}
+
+/**
+ * Keeps only the targets the layout presents. The `file-explorer` target exists on compact layouts
+ * only; a wide layout docks the Explorer instead, and a stale target there would block the
+ * navigation swipe, which begins only from `agent`.
+ */
+export function reconcileMobilePanel(
+  selection: MobilePanelSelection,
+  layout: PanelLayout,
+): MobilePanelSelection {
+  const sidebarReconciled =
+    layout.leftSidebar === "overlay" ? selection : dropOverlayAgentList(selection);
+  if (!layout.isCompact && sidebarReconciled.target === "file-explorer") {
+    return setMobilePanelTarget(sidebarReconciled, "agent");
+  }
+  return sidebarReconciled;
+}
+
 const ExplorerTabSchema = z.enum(["changes", "files", "pr"]);
 const DesktopSidebarStorageSchema = z.strictObject({
   agentListOpen: z.boolean().optional(),
diff --git a/packages/app/src/workspace-tabs/navigation.test.ts b/packages/app/src/workspace-tabs/navigation.test.ts
index c32fc91cf9..de918e53d4 100644
--- a/packages/app/src/workspace-tabs/navigation.test.ts
+++ b/packages/app/src/workspace-tabs/navigation.test.ts
@@ -33,6 +33,28 @@ it("reveals an existing main file selected from compact Explorer", () => {
   expect(existing).toBe(tabId);
   expect(usePanelStore.getState().mobilePanel.target).toBe("agent");
 });
+it.each(["single-pane", "split-panes"] as const)(
+  "dismisses floating navigation when revealing a %s tab without pinning its dock",
+  (layoutMode) => {
+    const store = useWorkspaceLayoutStore.getState();
+    store.setLayoutMode(layoutMode);
+    usePanelStore.getState().closeDesktopAgentList();
+    usePanelStore.getState().showMobileAgentList();
+    const tabId = store.openTab({
+      workspaceKey,
+      target: { kind: "agent", agentId: "root" },
+      intent: "reveal",
+    });
+    revealWorkspaceTab(workspaceKey, tabId);
+    expect(usePanelStore.getState().mobilePanel.target).toBe("agent");
+    expect(usePanelStore.getState().desktop.agentListOpen).toBe(false);
+    expect(
+      useWorkspaceLayoutStore.getState().getTabDestination(workspaceKey, tabId!),
+    ).toMatchObject({
+      host: "main",
+    });
+  },
+);
 it("keeps Explorer beneath a new compact file sheet", () => {
   const store = useWorkspaceLayoutStore.getState();
   store.setLayoutMode("compact");
diff --git a/packages/app/src/workspace-tabs/navigation.ts b/packages/app/src/workspace-tabs/navigation.ts
index 5e36f65102..89e46994b8 100644
--- a/packages/app/src/workspace-tabs/navigation.ts
+++ b/packages/app/src/workspace-tabs/navigation.ts
@@ -10,10 +10,11 @@ export function revealWorkspaceTab(workspaceKey: string, tabId: string | null):
   if (!destination) return null;
   if (destination.kind === "sheet") return tabId;
   store.focusTab(workspaceKey, tabId);
-  if (store.layoutMode === "compact") {
-    const panels = usePanelStore.getState();
-    if (destination.host === "explorer") panels.showMobileFileExplorer();
-    else panels.showMobileAgent();
+  const panels = usePanelStore.getState();
+  if (store.layoutMode === "compact" && destination.host === "explorer") {
+    panels.showMobileFileExplorer();
+  } else {
+    panels.showMobileAgent();
   }
   return tabId;
 }
diff --git a/packages/desktop/e2e/browser-tabs.e2e.mjs b/packages/desktop/e2e/browser-tabs.e2e.mjs
index 9c275d6cc9..f06860d862 100644
--- a/packages/desktop/e2e/browser-tabs.e2e.mjs
+++ b/packages/desktop/e2e/browser-tabs.e2e.mjs
@@ -1056,6 +1056,10 @@ async function runRegression({
   await page.screenshot({ path: path.join(artifactDir, "local-page-screenshot-selector.png") });
   await originalDeck.getByRole("button", { name: "Cancel element selector" }).click();
 
+  // This journey selects tabs from both pane rails. Keep both columns above the compact-header
+  // breakpoint; narrow panes deliberately replace their rail with a tab dropdown.
+  await resizeDesktopWindow(inspectorPort, { width: 1920, height: 1080 });
+  await page.waitForFunction(() => innerWidth >= 1920, null, { timeout: timeoutMs });
   await originalDeck.getByTestId(`workspace-tab-agent_${callerAgentId}`).click();
   await page.getByTestId("sidebar-search").click();
   await page.getByTestId("command-center-input").fill("Split pane right");
diff --git a/patches/react-native-gesture-handler+2.32.0.patch b/patches/react-native-gesture-handler+2.32.0.patch
index 7cdbc35d4a..b6e3a810f1 100644
--- a/patches/react-native-gesture-handler+2.32.0.patch
+++ b/patches/react-native-gesture-handler+2.32.0.patch
@@ -194,10 +194,37 @@ index 96c5227..cbf1a88 100644
  
    //
 diff --git a/node_modules/react-native-gesture-handler/lib/commonjs/web/tools/PointerEventManager.js b/node_modules/react-native-gesture-handler/lib/commonjs/web/tools/PointerEventManager.js
-index 76eb808..7c40526 100644
+index 76eb808..75a9d75 100644
 --- a/node_modules/react-native-gesture-handler/lib/commonjs/web/tools/PointerEventManager.js
 +++ b/node_modules/react-native-gesture-handler/lib/commonjs/web/tools/PointerEventManager.js
-@@ -58,7 +58,14 @@ class PointerEventManager extends _EventManager.default {
+@@ -35,9 +35,6 @@ class PointerEventManager extends _EventManager.default {
+     }
+     const adaptedEvent = this.mapEvent(event, _interfaces.EventTypes.DOWN);
+     const target = event.target;
+-    if (!POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)) {
+-      target.setPointerCapture(adaptedEvent.pointerId);
+-    }
+     this.markAsInBounds(adaptedEvent.pointerId);
+     this.trackedPointers.add(adaptedEvent.pointerId);
+     if (++this.activePointersCounter > 1) {
+@@ -46,6 +43,16 @@ class PointerEventManager extends _EventManager.default {
+     } else {
+       this.onPointerDown(adaptedEvent);
+     }
++
++    // Capture only a pointer the handler still tracks after seeing it. A handler that fails
++    // the pointer on down (a touch-only pan rejecting the mouse) resets, and a capture it kept
++    // would confine the browser's text selection to the pressed element.
++    if (
++      this.trackedPointers.has(adaptedEvent.pointerId) &&
++      !POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)
++    ) {
++      target.setPointerCapture(adaptedEvent.pointerId);
++    }
+   };
+   pointerUpCallback = event => {
+     // When we call reset on gesture handlers, it also resets their event managers
+@@ -58,7 +65,14 @@ class PointerEventManager extends _EventManager.default {
      const adaptedEvent = this.mapEvent(event, _interfaces.EventTypes.UP);
      const target = event.target;
      if (!POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)) {
@@ -213,6 +240,15 @@ index 76eb808..7c40526 100644
      }
      this.markAsOutOfBounds(adaptedEvent.pointerId);
      this.trackedPointers.delete(adaptedEvent.pointerId);
+@@ -85,7 +99,7 @@ class PointerEventManager extends _EventManager.default {
+     // incorporating it here seems stupid), so we just call it again here, every time
+     // pointer moves until it succeeds.
+     // God, I do love web development.
+-    if (!target?.hasPointerCapture(event.pointerId) && !POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)) {
++    if (this.trackedPointers.has(event.pointerId) && !target?.hasPointerCapture(event.pointerId) && !POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)) {
+       target.setPointerCapture(event.pointerId);
+     }
+     const inBounds = (0, _utils.isPointerInBounds)(this.view, {
 diff --git a/node_modules/react-native-gesture-handler/lib/module/web/handlers/GestureHandler.js b/node_modules/react-native-gesture-handler/lib/module/web/handlers/GestureHandler.js
 index 0791c66..2f41c77 100644
 --- a/node_modules/react-native-gesture-handler/lib/module/web/handlers/GestureHandler.js
@@ -229,10 +265,37 @@ index 0791c66..2f41c77 100644
  
    //
 diff --git a/node_modules/react-native-gesture-handler/lib/module/web/tools/PointerEventManager.js b/node_modules/react-native-gesture-handler/lib/module/web/tools/PointerEventManager.js
-index 6ce3b8f..8fe28bc 100644
+index 6ce3b8f..65cc6c8 100644
 --- a/node_modules/react-native-gesture-handler/lib/module/web/tools/PointerEventManager.js
 +++ b/node_modules/react-native-gesture-handler/lib/module/web/tools/PointerEventManager.js
-@@ -53,7 +53,14 @@ export default class PointerEventManager extends EventManager {
+@@ -30,9 +30,6 @@ export default class PointerEventManager extends EventManager {
+     }
+     const adaptedEvent = this.mapEvent(event, EventTypes.DOWN);
+     const target = event.target;
+-    if (!POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)) {
+-      target.setPointerCapture(adaptedEvent.pointerId);
+-    }
+     this.markAsInBounds(adaptedEvent.pointerId);
+     this.trackedPointers.add(adaptedEvent.pointerId);
+     if (++this.activePointersCounter > 1) {
+@@ -41,6 +38,16 @@ export default class PointerEventManager extends EventManager {
+     } else {
+       this.onPointerDown(adaptedEvent);
+     }
++
++    // Capture only a pointer the handler still tracks after seeing it. A handler that fails
++    // the pointer on down (a touch-only pan rejecting the mouse) resets, and a capture it kept
++    // would confine the browser's text selection to the pressed element.
++    if (
++      this.trackedPointers.has(adaptedEvent.pointerId) &&
++      !POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)
++    ) {
++      target.setPointerCapture(adaptedEvent.pointerId);
++    }
+   };
+   pointerUpCallback = event => {
+     // When we call reset on gesture handlers, it also resets their event managers
+@@ -53,7 +60,14 @@ export default class PointerEventManager extends EventManager {
      const adaptedEvent = this.mapEvent(event, EventTypes.UP);
      const target = event.target;
      if (!POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)) {
@@ -248,6 +311,15 @@ index 6ce3b8f..8fe28bc 100644
      }
      this.markAsOutOfBounds(adaptedEvent.pointerId);
      this.trackedPointers.delete(adaptedEvent.pointerId);
+@@ -80,7 +94,7 @@ export default class PointerEventManager extends EventManager {
+     // incorporating it here seems stupid), so we just call it again here, every time
+     // pointer moves until it succeeds.
+     // God, I do love web development.
+-    if (!target?.hasPointerCapture(event.pointerId) && !POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)) {
++    if (this.trackedPointers.has(event.pointerId) && !target?.hasPointerCapture(event.pointerId) && !POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)) {
+       target.setPointerCapture(event.pointerId);
+     }
+     const inBounds = isPointerInBounds(this.view, {
 diff --git a/node_modules/react-native-gesture-handler/src/web/handlers/GestureHandler.ts b/node_modules/react-native-gesture-handler/src/web/handlers/GestureHandler.ts
 index ddb79a3..4e1274c 100644
 --- a/node_modules/react-native-gesture-handler/src/web/handlers/GestureHandler.ts
@@ -264,10 +336,38 @@ index ddb79a3..4e1274c 100644
  
    //
 diff --git a/node_modules/react-native-gesture-handler/src/web/tools/PointerEventManager.ts b/node_modules/react-native-gesture-handler/src/web/tools/PointerEventManager.ts
-index 18d3627..769b0fe 100644
+index 18d3627..106b97c 100644
 --- a/node_modules/react-native-gesture-handler/src/web/tools/PointerEventManager.ts
 +++ b/node_modules/react-native-gesture-handler/src/web/tools/PointerEventManager.ts
-@@ -67,7 +67,14 @@ export default class PointerEventManager extends EventManager<HTMLElement> {
+@@ -39,10 +39,6 @@ export default class PointerEventManager extends EventManager<HTMLElement> {
+     const adaptedEvent: AdaptedEvent = this.mapEvent(event, EventTypes.DOWN);
+     const target = event.target as HTMLElement;
+ 
+-    if (!POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)) {
+-      target.setPointerCapture(adaptedEvent.pointerId);
+-    }
+-
+     this.markAsInBounds(adaptedEvent.pointerId);
+     this.trackedPointers.add(adaptedEvent.pointerId);
+ 
+@@ -52,6 +48,16 @@ export default class PointerEventManager extends EventManager<HTMLElement> {
+     } else {
+       this.onPointerDown(adaptedEvent);
+     }
++
++    // Capture only a pointer the handler still tracks after seeing it. A handler that fails
++    // the pointer on down (a touch-only pan rejecting the mouse) resets, and a capture it kept
++    // would confine the browser's text selection to the pressed element.
++    if (
++      this.trackedPointers.has(adaptedEvent.pointerId) &&
++      !POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)
++    ) {
++      target.setPointerCapture(adaptedEvent.pointerId);
++    }
+   };
+ 
+   private pointerUpCallback = (event: PointerEvent) => {
+@@ -67,7 +73,14 @@ export default class PointerEventManager extends EventManager<HTMLElement> {
      const target = event.target as HTMLElement;
  
      if (!POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)) {
@@ -283,3 +383,11 @@ index 18d3627..769b0fe 100644
      }
  
      this.markAsOutOfBounds(adaptedEvent.pointerId);
+@@ -98,6 +111,7 @@ export default class PointerEventManager extends EventManager<HTMLElement> {
+     // pointer moves until it succeeds.
+     // God, I do love web development.
+     if (
++      this.trackedPointers.has(event.pointerId) &&
+       !target?.hasPointerCapture(event.pointerId) &&
+       !POINTER_CAPTURE_EXCLUDE_LIST.has(target.tagName)
+     ) {
diff --git a/scripts/postinstall-patches.mjs b/scripts/postinstall-patches.mjs
index 0f4b96b19f..e6b9195a94 100644
--- a/scripts/postinstall-patches.mjs
+++ b/scripts/postinstall-patches.mjs
@@ -52,6 +52,9 @@ const patchedPackages = [
     nodeModulesPath: "node_modules/react-native-draggable-flatlist",
     patchPrefix: "react-native-draggable-flatlist+",
   },
+  // Web pointer capture: capture only pointers the handler still tracks after pointer-down, so a
+  // touch-only pan that fails the mouse leaves browser text selection alone. Keep until upstream
+  // stops capturing pointers a handler has rejected.
   {
     nodeModulesPath: "node_modules/react-native-gesture-handler",
     patchPrefix: "react-native-gesture-handler+",

From 2d5b8eb1fd10115bf93962e1b265ff00517177e2 Mon Sep 17 00:00:00 2001
From: "paseo-bot[bot]" <266920839+paseo-bot[bot]@users.noreply.github.com>
Date: Wed, 4 Nov 2026 13:17:32 +0000
Subject: [PATCH 09/29] Handle web terminal finger scrolling once (#8776)

* fix(app): scroll web terminal history with a finger swipe

A phone browser claims the vertical drag and drops it, because the canvas covers the scrollable viewport and the page itself does not scroll. Keep the gesture in the touch handler and move one line per cell.

* fix(app): handle terminal finger scrolling once

Keep the vertical gesture in the existing terminal handler so xterm does not also scroll it at document level. Retain only the confirmed propagation correction from the contributor patch and cover the actual phone-sized app with trusted touch input.

Co-authored-by: sino <sino2322@gmail.com>

* fix(app): let xterm own terminal touch input

Remove the duplicate gesture implementation so history scrolls once and terminal applications retain arrow-key and mouse-report input. Cover live application modes with trusted touch gestures and a real raw-stdin process.

---------

Co-authored-by: sino <sino2322@gmail.com>
Co-authored-by: paseo-bot[bot] <266920839+paseo-bot[bot]@users.noreply.github.com>
---
 .../app/e2e/browser/terminal-find.spec.ts     | 140 ++++++++++++++++++
 .../runtime/terminal-emulator-runtime.ts      | 125 ----------------
 2 files changed, 140 insertions(+), 125 deletions(-)

diff --git a/packages/app/e2e/browser/terminal-find.spec.ts b/packages/app/e2e/browser/terminal-find.spec.ts
index e4dde5cfaa..26a5b52063 100644
--- a/packages/app/e2e/browser/terminal-find.spec.ts
+++ b/packages/app/e2e/browser/terminal-find.spec.ts
@@ -1,3 +1,4 @@
+import { getServerId } from "../support/helpers/server-id";
 import { runWorkspaceActionFromCommandCenter } from "../support/helpers/command-center-workspace-actions";
 import { spawnSync } from "node:child_process";
 import { readFile, writeFile } from "node:fs/promises";
@@ -489,3 +490,142 @@ test("keeps the shared Find controls usable in a compact dark browser", async ({
   await page.getByRole("button", { name: "Close Find" }).click();
   await expect(input(page)).toBeFocused();
 });
+
+// A phone browser installs xterm's document-level touch gesture listener too.
+// Keep this journey touch-enabled so it catches duplicate scroll handling.
+test.describe("terminal history with a finger", () => {
+  test.use({ isMobile: true, hasTouch: true, viewport: { width: 390, height: 844 } });
+
+  test("scrolls history once per finger drag", async ({ page }) => {
+    await openPhoneTerminalHistory(page);
+    await expectSingleFingerScroll(page, 24);
+    await expectSingleFingerScroll(page, 1);
+    await expectMouseWheelScrollsHistory(page);
+  });
+
+  for (const mode of ["alternate", "mouse"] as const) {
+    test(`preserves finger navigation in ${mode} input mode`, async ({ page }) => {
+      await openPhoneInputCapture(page, mode);
+      await expectFingerNavigationInput(page, mode);
+    });
+  }
+});
+
+async function expectFingerNavigationInput(page: Page, mode: "alternate" | "mouse") {
+  await dragTerminalWithFinger(page, 24, async () => {
+    const prefix = mode === "alternate" ? "TOUCH_BYTES:1b4f41" : "TOUCH_BYTES:1b5b3c3634";
+    await expect.poll(() => getTerminalBufferText(page)).toContain(prefix);
+  });
+}
+
+async function openPhoneTerminalHistory(page: Page) {
+  await harness.createTerminal({
+    name: "Finger scroll history",
+    command: "bash",
+    args: [
+      "--noprofile",
+      "--norc",
+      "-c",
+      "for i in $(seq 1 150); do echo HISTORY_$i; done; exec sleep 300",
+    ],
+  });
+  await openPhoneTerminal(page);
+  await expect.poll(() => getTerminalBufferText(page)).toContain("HISTORY_150");
+}
+
+async function openPhoneInputCapture(page: Page, mode: "alternate" | "mouse") {
+  const escapes = mode === "alternate" ? "\x1b[?1049h\x1b[?1h" : "\x1b[?1000h\x1b[?1006h";
+  await harness.createTerminal({
+    name: "Touch application input",
+    command: process.execPath,
+    args: [
+      "-e",
+      `
+      process.stdin.setRawMode(true);
+      process.stdin.once("data", () => {
+        process.stdin.on("data", chunk => {
+          process.stdout.write("\\r\\nTOUCH_BYTES:" + chunk.toString("hex") + ":END\\r\\n");
+        });
+        process.stdout.write(${JSON.stringify(escapes)} + "TOUCH_INPUT_READY\\r\\n");
+      });
+      process.stdout.write("TOUCH_START_READY\\r\\n");
+    `,
+    ],
+  });
+  await openPhoneTerminal(page);
+  await expect.poll(() => getTerminalBufferText(page)).toContain("TOUCH_START_READY");
+  await input(page).press("x");
+  await expect.poll(() => getTerminalBufferText(page)).toContain("TOUCH_INPUT_READY");
+  await expect
+    .poll(() => page.evaluate(() => window.__paseoTerminal!.buffer.active.type))
+    .toBe(mode === "alternate" ? "alternate" : "normal");
+  await expect
+    .poll(() => page.evaluate(() => window.__paseoTerminal!.modes.mouseTrackingMode))
+    .toBe(mode === "mouse" ? "vt200" : "none");
+}
+
+async function openPhoneTerminal(page: Page) {
+  await page.goto("/");
+  await page.getByRole("button", { name: "Open menu", exact: true }).click();
+  await page.getByTestId(`sidebar-workspace-row-${getServerId()}:${harness.workspaceId}`).click();
+  await expect(page.getByRole("textbox", { name: "Terminal input" })).toBeVisible();
+  await expect(page.getByTestId("terminal-surface").filter({ visible: true })).toBeVisible();
+}
+
+async function expectMouseWheelScrollsHistory(page: Page) {
+  const beforeWheel = (await viewport(page))!;
+  await page.mouse.move(200, 300);
+  await page.mouse.wheel(0, -120);
+  await expect.poll(() => viewport(page)).toBeLessThan(beforeWheel);
+}
+
+async function expectSingleFingerScroll(page: Page, moves: number) {
+  await dragTerminalWithFinger(page, moves, async ({ lineHeight, before }) => {
+    await expect.poll(async () => before - (await viewport(page))!).toBeGreaterThan(0);
+    const moved = before - (await viewport(page))!;
+    await test.info().attach("finger-scroll", {
+      body: JSON.stringify({ moves, distancePx: 120, lineHeight, rowsMoved: moved }),
+      contentType: "application/json",
+    });
+    expect(moved, "one gesture must not scroll twice its physical distance").toBeLessThanOrEqual(
+      Math.ceil(120 / lineHeight),
+    );
+  });
+}
+
+async function dragTerminalWithFinger(
+  page: Page,
+  moves: number,
+  inspect: (state: { lineHeight: number; before: number }) => Promise<void>,
+) {
+  await test.step(`Drag history with ${moves} touch moves`, async () => {
+    const screen = page
+      .getByTestId("terminal-surface")
+      .filter({ visible: true })
+      .locator(".xterm-screen");
+    const box = await screen.boundingBox();
+    if (!box) throw new Error("Terminal screen is not visible");
+    const rows = await page.evaluate(() => window.__paseoTerminal!.rows);
+    const lineHeight = box.height / rows;
+    const before = (await viewport(page))!;
+    const session = await page.context().newCDPSession(page);
+    try {
+      const start = { x: box.x + box.width / 2, y: box.y + box.height / 3 };
+      await session.send("Input.dispatchTouchEvent", {
+        type: "touchStart",
+        touchPoints: [{ ...start, id: 1 }],
+      });
+      for (let step = 1; step <= moves; step++) {
+        await session.send("Input.dispatchTouchEvent", {
+          type: "touchMove",
+          touchPoints: [{ x: start.x, y: start.y + (120 * step) / moves, id: 1 }],
+        });
+      }
+      // Check before lifting the finger to exclude inertial scrolling.
+      await inspect({ lineHeight, before });
+    } finally {
+      await session.send("Input.dispatchTouchEvent", { type: "touchEnd", touchPoints: [] });
+      await session.detach();
+    }
+  });
+}
diff --git a/packages/app/src/terminal/runtime/terminal-emulator-runtime.ts b/packages/app/src/terminal/runtime/terminal-emulator-runtime.ts
index b1cab84d0e..ae74a4945f 100644
--- a/packages/app/src/terminal/runtime/terminal-emulator-runtime.ts
+++ b/packages/app/src/terminal/runtime/terminal-emulator-runtime.ts
@@ -123,7 +123,6 @@ interface TerminalEmulatorRuntimeDisposables {
   removeVisualViewportResize: () => void;
   clearFitTimeouts: () => void;
   removeFontListeners: () => void;
-  removeTouchListeners: () => void;
   removeFilePasteListener: () => void;
   restoreDocumentStyles: () => void;
   restoreViewportStyles: () => void;
@@ -155,7 +154,6 @@ const isAppleHandheld =
     maxTouchPoints: navigator.maxTouchPoints,
   });
 
-const DEFAULT_TOUCH_SCROLL_LINE_HEIGHT_PX = 18;
 const FIT_TIMEOUT_DELAYS_MS = [0, 16, 48, 120, 250, 500, 1_000, 2_000];
 const OUTPUT_OPERATION_TIMEOUT_MS = 5_000;
 const EMPTY_TERMINAL_OUTPUT = new Uint8Array(0);
@@ -764,11 +762,6 @@ export class TerminalEmulatorRuntime {
     };
     input.host.addEventListener("paste", filePasteHandler, true);
 
-    const removeTouchListeners = this.setupTouchScrollHandlers({
-      root: input.root,
-      host: input.host,
-      terminal,
-    });
     const resizeObserver = new ResizeObserver(() => {
       fitAndEmitResize({ shouldClaim: false });
     });
@@ -848,7 +841,6 @@ export class TerminalEmulatorRuntime {
       removeFontListeners: () => {
         fontSet?.removeEventListener?.("loadingdone", fontReadyHandler);
       },
-      removeTouchListeners,
       removeFilePasteListener: () => {
         input.host.removeEventListener("paste", filePasteHandler, true);
       },
@@ -880,7 +872,6 @@ export class TerminalEmulatorRuntime {
       disposables.removeVisualViewportResize();
       disposables.clearFitTimeouts();
       disposables.removeFontListeners();
-      disposables.removeTouchListeners();
       disposables.removeFilePasteListener();
       disposables.disposeFitAddon();
       disposables.disposeWebglAddon();
@@ -1420,120 +1411,4 @@ export class TerminalEmulatorRuntime {
       }
     };
   }
-
-  private setupTouchScrollHandlers(input: {
-    root: HTMLDivElement;
-    host: HTMLDivElement;
-    terminal: Terminal;
-  }): () => void {
-    let touchScrollRemainderPx = 0;
-    const measuredLineHeight =
-      input.host.querySelector<HTMLElement>(".xterm-rows > div")?.getBoundingClientRect().height ??
-      0;
-    const touchScrollLineHeightPx =
-      measuredLineHeight > 0 ? measuredLineHeight : DEFAULT_TOUCH_SCROLL_LINE_HEIGHT_PX;
-
-    const activeTouch = {
-      identifier: -1,
-      startX: 0,
-      startY: 0,
-      lastX: 0,
-      lastY: 0,
-      mode: null as "vertical" | "horizontal" | null,
-    };
-
-    const touchStartHandler = (event: TouchEvent) => {
-      if (event.touches.length !== 1) {
-        touchScrollRemainderPx = 0;
-        activeTouch.identifier = -1;
-        activeTouch.mode = null;
-        return;
-      }
-
-      const touch = event.touches[0];
-      if (!touch) {
-        touchScrollRemainderPx = 0;
-        activeTouch.identifier = -1;
-        activeTouch.mode = null;
-        return;
-      }
-
-      activeTouch.identifier = touch.identifier;
-      activeTouch.startX = touch.clientX;
-      activeTouch.startY = touch.clientY;
-      activeTouch.lastX = touch.clientX;
-      activeTouch.lastY = touch.clientY;
-      activeTouch.mode = null;
-      touchScrollRemainderPx = 0;
-    };
-
-    const touchMoveHandler = (event: TouchEvent) => {
-      if (event.touches.length !== 1) {
-        return;
-      }
-
-      const touch = Array.from(event.touches).find(
-        (candidate) => candidate.identifier === activeTouch.identifier,
-      );
-      if (!touch) {
-        return;
-      }
-
-      const totalDeltaX = touch.clientX - activeTouch.startX;
-      const totalDeltaY = touch.clientY - activeTouch.startY;
-      if (activeTouch.mode === null) {
-        const absX = Math.abs(totalDeltaX);
-        const absY = Math.abs(totalDeltaY);
-        if (absX > 8 || absY > 8) {
-          activeTouch.mode = absY >= absX ? "vertical" : "horizontal";
-        }
-      }
-
-      const deltaY = touch.clientY - activeTouch.lastY;
-      activeTouch.lastX = touch.clientX;
-      activeTouch.lastY = touch.clientY;
-
-      if (activeTouch.mode !== "vertical") {
-        return;
-      }
-
-      touchScrollRemainderPx += deltaY;
-      const lineDelta = Math.trunc(touchScrollRemainderPx / touchScrollLineHeightPx);
-      if (lineDelta !== 0) {
-        input.terminal.scrollLines(-lineDelta);
-        touchScrollRemainderPx -= lineDelta * touchScrollLineHeightPx;
-      }
-
-      event.preventDefault();
-    };
-
-    const touchEndHandler = (event: TouchEvent) => {
-      const activeTouchEnded = Array.from(event.changedTouches).some(
-        (touch) => touch.identifier === activeTouch.identifier,
-      );
-      if (activeTouchEnded || event.touches.length === 0) {
-        touchScrollRemainderPx = 0;
-        activeTouch.identifier = -1;
-        activeTouch.mode = null;
-      }
-    };
-
-    const touchCancelHandler = () => {
-      touchScrollRemainderPx = 0;
-      activeTouch.identifier = -1;
-      activeTouch.mode = null;
-    };
-
-    input.root.addEventListener("touchstart", touchStartHandler, { passive: true });
-    input.root.addEventListener("touchmove", touchMoveHandler, { passive: false });
-    input.root.addEventListener("touchend", touchEndHandler, { passive: true });
-    input.root.addEventListener("touchcancel", touchCancelHandler, { passive: true });
-
-    return () => {
-      input.root.removeEventListener("touchstart", touchStartHandler);
-      input.root.removeEventListener("touchmove", touchMoveHandler);
-      input.root.removeEventListener("touchend", touchEndHandler);
-      input.root.removeEventListener("touchcancel", touchCancelHandler);
-    };
-  }
 }

From 15997a06d07e387eb50fc620b1f2cbc47d739043 Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Wed, 4 Nov 2026 21:54:29 +0700
Subject: [PATCH 10/29] fix(ci): pin semver away from incomplete attestations
 (#8787)

The pkijs lockfile regeneration bumped tiny-async-pool's semver to 5.7.3
and app-builder-lib's @electron/get semver to 6.3.2, both published
2026-11-02 in one batch. Some Cloudflare edges cached the attestation
document for 5.7.3 before the publish attestation attached, so
`npm audit signatures` fails with EMISSINGSIGNATUREKEY depending on the
runner's region. Pin both back to the 2023 releases with per-parent,
range-keyed overrides so global-agent's semver ^7 under @electron/get
is left alone.
---
 docs/development.md | 11 ++++++++++-
 package-lock.json   | 12 ++++++------
 package.json        |  8 +++++++-
 3 files changed, 23 insertions(+), 8 deletions(-)

diff --git a/docs/development.md b/docs/development.md
index 5c891b2121..ddebf3ffff 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -594,7 +594,16 @@ rerun passes only by landing elsewhere.
 To confirm, fetch the URL from several runners and compare `content-length`, the `cf-ray` colo
 suffix, and the number of `attestations` entries (#7730 has the probe). To fix, remove or
 replace that version in the lockfile. If the dependent’s range cannot be changed, pin a clean
-version in root `overrides` and regenerate the lockfile. Report the URL to npm so they purge it.
+version in root `overrides`. Report the URL to npm so they purge it.
+
+A lockfile regeneration is itself how new bad versions enter: the pkijs fix re-resolved the
+electron-builder tree and pulled in `semver` 5.7.3 and 6.3.2, published two days earlier, and
+5.7.3 then failed the same way. After editing `overrides`, run `npm install --package-lock-only`
+and check that the changed `resolved` lines in `package-lock.json` are only the ones you meant.
+
+A per-parent override such as `"tiny-async-pool": { "semver": "5.7.2" }` applies to that
+parent's whole subtree, so it can also downgrade a grandchild that needs a different major. Key
+the child by range (`{ "semver@^5": "5.7.2" }`) so only matching edges are replaced.
 
 ## ACP provider catalog versions
 
diff --git a/package-lock.json b/package-lock.json
index 7e561ceb9d..f1cbf595c3 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -15088,9 +15088,9 @@
       }
     },
     "node_modules/app-builder-lib/node_modules/@electron/get/node_modules/semver": {
-      "version": "6.3.2",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.2.tgz",
-      "integrity": "sha512-GYrCADwpu6yV5OAvchkQ27Z5wwMxWAEMg5NNWjyHh/5DboFFqbdbvYNIvZouQpxXyeMPoTOh0vdPYKlf0ZswdQ==",
+      "version": "6.3.1",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz",
+      "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==",
       "dev": true,
       "license": "ISC",
       "bin": {
@@ -35100,9 +35100,9 @@
       }
     },
     "node_modules/tiny-async-pool/node_modules/semver": {
-      "version": "5.7.3",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.3.tgz",
-      "integrity": "sha512-kM18BPOqTi0+TB68703/GJRpAML5Me+IDQsR1J26YB3EFKKNEyHIVZuWDX7+WKQB3tHwDwgk24BfhdpWUbytvQ==",
+      "version": "5.7.2",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.2.tgz",
+      "integrity": "sha512-cBznnQ9KjJqU67B52RMC65CMarK2600WFnbkcaiwWq3xy/5haFJlshgnpjovMVJ+Hff49d8GEn0b87C5pDQ10g==",
       "dev": true,
       "license": "ISC",
       "bin": {
diff --git a/package.json b/package.json
index b017f0b106..83f56c1d31 100644
--- a/package.json
+++ b/package.json
@@ -149,6 +149,9 @@
   "overrides": {
     "@codemirror/language": "6.12.4",
     "@codemirror/view": "6.43.6",
+    "@electron/get@^3.0.0": {
+      "semver@^6": "6.3.1"
+    },
     "expo": "~57.0.30",
     "expo-router": "~57.0.28",
     "lightningcss": "1.30.1",
@@ -158,6 +161,9 @@
     "react-native": "0.86.3",
     "react-native-gesture-handler": "~2.32.0",
     "react-native-reanimated": "4.5.5",
-    "react-native-worklets": "0.10.4"
+    "react-native-worklets": "0.10.4",
+    "tiny-async-pool": {
+      "semver@^5": "5.7.2"
+    }
   }
 }

From a91bb4d406d8a18690e38ce721715264b0acb542 Mon Sep 17 00:00:00 2001
From: "paseo-ai[bot]" <266920839+paseo-ai[bot]@users.noreply.github.com>
Date: Wed, 4 Nov 2026 15:01:56 +0000
Subject: [PATCH 11/29] fix: update lockfile signatures and Nix hash [skip ci]

---
 nix/npm-deps.hash | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/nix/npm-deps.hash b/nix/npm-deps.hash
index edbcfe2f64..c1fd37546e 100644
--- a/nix/npm-deps.hash
+++ b/nix/npm-deps.hash
@@ -1 +1 @@
-sha256-sLaLHD1u1eJRdGdflcwWBGxnnhRQpB1T74BlaWcmxbU=
+sha256-plC3c5pOkD/q2Q8Oi/5ARTyVVmN4eze+scbHoEUC7NA=

From 5d1a2c10f8a493e2329f3f9bee51dfb94ccd28af Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Wed, 4 Nov 2026 22:35:23 +0700
Subject: [PATCH 12/29] test(app): wheel the thinking group into view before
 opening it (#8791)

The "reasoning follows Expand thinking (false)" spec clicked a tool-call
group above the viewport. Playwright's scroll-into-view is programmatic,
and the web timeline only leaves sticky-bottom on user input (wheel, key,
touch, scrollbar), so it snapped back to the bottom while the click was
in flight and the group never opened. Wheel the group into view first,
reusing the helper the timeline pagination specs already use for
prompts.
---
 .../app/e2e/browser/turn-collapse.spec.ts     |  2 ++
 .../support/helpers/timeline-pagination.ts    | 19 +++++++++++++++----
 2 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/packages/app/e2e/browser/turn-collapse.spec.ts b/packages/app/e2e/browser/turn-collapse.spec.ts
index d990e33009..cd899d1ee8 100644
--- a/packages/app/e2e/browser/turn-collapse.spec.ts
+++ b/packages/app/e2e/browser/turn-collapse.spec.ts
@@ -2,6 +2,7 @@ import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
 import path from "node:path";
 import {
   holdOlderHistoryPages,
+  scrollTimelineRowIntoView,
   userScrollsTimelineToHistoryStart,
 } from "../support/helpers/timeline-pagination";
 import { getActiveTabTestId } from "../support/helpers/launcher";
@@ -529,6 +530,7 @@ async function expectThinkingPresentation(page: Page, autoExpandReasoning: boole
       .last();
     await expect(group).toContainText(/read 1 file/i);
     await expect(group.getByRole("button").first()).not.toContainText(/thought/i);
+    await scrollTimelineRowIntoView(page, group);
     await group.getByRole("button").first().click();
     // Expand thinking is off: the group opens its rows, but the thought row stays closed
     // until the reader opens it.
diff --git a/packages/app/e2e/support/helpers/timeline-pagination.ts b/packages/app/e2e/support/helpers/timeline-pagination.ts
index e575f4f0d9..f54fd86812 100644
--- a/packages/app/e2e/support/helpers/timeline-pagination.ts
+++ b/packages/app/e2e/support/helpers/timeline-pagination.ts
@@ -477,18 +477,29 @@ export async function expectStableHistoryStartGutter(page: Page): Promise<void>
     .toBe(32);
 }
 
-export async function scrollTimelinePromptIntoView(page: Page, prompt: string): Promise<void> {
+/**
+ * Wheels the timeline until `row` is centered, as a reader does. Playwright's own
+ * scroll-into-view is programmatic, which the timeline does not treat as the reader leaving
+ * the bottom: it snaps back to the bottom and can move the row away mid-click.
+ */
+export async function scrollTimelineRowIntoView(page: Page, row: Locator): Promise<void> {
   const timeline = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
-  const row = timeline.getByTestId("user-message").filter({ hasText: prompt });
   const [viewport, target] = await Promise.all([timeline.boundingBox(), row.boundingBox()]);
   if (!viewport || !target) {
-    throw new Error(`Expected a rendered timeline prompt for ${prompt}`);
+    throw new Error("Expected a rendered timeline row");
   }
-  // Programmatic scrolling does not express the user's intent to stop following output.
   await timeline.hover();
   await page.mouse.wheel(0, target.y - viewport.y - (viewport.height - target.height) / 2);
   await expect(row).toBeInViewport({ ratio: 1 });
   await waitForTimelineGeometryToSettle(page);
+}
+
+export async function scrollTimelinePromptIntoView(page: Page, prompt: string): Promise<void> {
+  const timeline = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  await scrollTimelineRowIntoView(
+    page,
+    timeline.getByTestId("user-message").filter({ hasText: prompt }),
+  );
   await expect
     .poll(async () => (await readTimelineViewport(page)).scrollTop)
     .toBeGreaterThan(HISTORY_START_THRESHOLD_PX);

From 8dfdb479ab9664d1789000e603ebb610214c52d2 Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Thu, 5 Nov 2026 08:59:04 +0700
Subject: [PATCH 13/29] fix(terminal): start the daemon when the terminal
 worker cannot start (#8810)

On 0.15.0 the daemon launches the detached terminal worker while it is
being created, and the worker refuses to start unless it can read its own
birth time and command line (Windows PowerShell 5.1 `Get-CimInstance`,
`ps` elsewhere). Any failure of that query used to escape
startWorkerTerminalManager and take the whole daemon down with
"Daemon failed to start (exit 1)", as two Windows machines hit after the
update: one whose PowerShell 5.1 cannot load CimCmdlets, one where
powershell.exe cannot be spawned at all. 0.14.0 never ran that query at
startup.

The launch error is now logged and the daemon starts without a current
worker. The pool already launches one lazily on the first terminal
creation, so that request reports the same error while the machine still
cannot run the query, and terminals come back once it can. The identity
requirement itself is unchanged: a worker without a verified identity is
never written or adopted.
---
 .../terminal/worker-terminal-manager.test.ts  | 33 ++++++++++++++++++-
 .../src/terminal/worker-terminal-manager.ts   | 13 ++++++--
 2 files changed, 43 insertions(+), 3 deletions(-)

diff --git a/packages/server/src/terminal/worker-terminal-manager.test.ts b/packages/server/src/terminal/worker-terminal-manager.test.ts
index 2a584087a3..0bcc2acf92 100644
--- a/packages/server/src/terminal/worker-terminal-manager.test.ts
+++ b/packages/server/src/terminal/worker-terminal-manager.test.ts
@@ -70,7 +70,7 @@ import {
   TerminalWorkerIncompatibleError,
 } from "./terminal-worker-pool.js";
 import { connectTerminalWorker } from "./terminal-worker-client.js";
-import { launchTerminalWorker } from "./terminal-worker-launch.js";
+import { launchTerminalWorker, TerminalWorkerLaunchError } from "./terminal-worker-launch.js";
 
 type TerminalRow = TerminalState["grid"][number];
 
@@ -2671,3 +2671,34 @@ it.each([false, true])(
   },
   45000,
 );
+
+// Both Windows reports in #8766: the worker's process identity query (PowerShell there, `ps` here)
+// fails, the worker exits before writing its record, and the daemon used to exit with it.
+it.skipIf(isPlatform("win32"))(
+  "starts without a worker when the worker cannot read its own identity, and launches one once it can",
+  async () => {
+    const paseoHome = createTemporaryHome();
+    const binDir = mkdtempSync(join(tmpdir(), "worker-terminal-manager-no-ps-"));
+    temporaryDirs.push(binDir);
+    writeFileSync(join(binDir, "ps"), "#!/bin/sh\nexit 1\n", { mode: 0o755 });
+    const originalPath = process.env.PATH;
+    process.env.PATH = `${binDir}${delimiter}${originalPath ?? ""}`;
+    try {
+      manager = await startRealWorkerManager({ paseoHome });
+      expect(await workerRecords(paseoHome)).toEqual([]);
+      await expect(
+        manager.createTerminal({ workspaceId: "ws-no-identity", cwd: paseoHome }),
+      ).rejects.toThrow(TerminalWorkerLaunchError);
+      expect(await workerRecords(paseoHome)).toEqual([]);
+    } finally {
+      process.env.PATH = originalPath;
+    }
+
+    const terminal = trackTerminal(
+      await manager.createTerminal({ workspaceId: "ws-no-identity", cwd: paseoHome }),
+    );
+    expect(terminal.id).toBeTruthy();
+    expect((await workerRecords(paseoHome)).map((record) => record.pid)).toHaveLength(1);
+  },
+  30000,
+);
diff --git a/packages/server/src/terminal/worker-terminal-manager.ts b/packages/server/src/terminal/worker-terminal-manager.ts
index 9a82826cec..ea91d54a66 100644
--- a/packages/server/src/terminal/worker-terminal-manager.ts
+++ b/packages/server/src/terminal/worker-terminal-manager.ts
@@ -1269,8 +1269,17 @@ export async function startWorkerTerminalManager(
     try {
       current = await startCurrent();
     } catch (error) {
-      if (!(error instanceof NoTerminalWorkerAvailableError)) throw error;
-      logger.warn(error.message);
+      if (error instanceof NoTerminalWorkerAvailableError) {
+        logger.warn(error.message);
+      } else {
+        // The daemon starts without terminals rather than not at all. A worker that cannot start
+        // here (its process identity query failed, say) is launched again by the first terminal
+        // creation, which reports the same error if it still cannot.
+        logger.error(
+          { err: error },
+          "Terminal worker did not start; terminals are unavailable until one starts",
+        );
+      }
     }
   }
 

From 72955cef6065b3a44927b36e14f283f5506db462 Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Thu, 5 Nov 2026 10:26:47 +0700
Subject: [PATCH 14/29] chore(release): reconcile 0.15.1 into main (#8814)

Brings the shipped 0.15.1 changelog entries, version, and F-Droid changelog files from release/v0.15.1 into main.
---
 CHANGELOG.md                                  |  6 ++
 CHANGELOG.zh-CN.md                            |  6 ++
 .../android/en-US/changelogs/150011.txt       |  4 ++
 .../android/en-US/changelogs/150012.txt       |  4 ++
 .../android/en-US/changelogs/150013.txt       |  4 ++
 .../android/en-US/changelogs/150014.txt       |  4 ++
 package-lock.json                             | 56 +++++++++----------
 package.json                                  |  2 +-
 packages/app/package.json                     |  2 +-
 packages/cli/package.json                     |  8 +--
 packages/client/package.json                  |  6 +-
 packages/desktop/package.json                 |  2 +-
 packages/expo-two-way-audio/package.json      |  2 +-
 packages/highlight/package.json               |  2 +-
 packages/plugin/package.json                  | 10 ++--
 packages/protocol/package.json                |  2 +-
 packages/relay/package.json                   |  2 +-
 packages/server/package.json                  | 12 ++--
 packages/website/package.json                 |  2 +-
 plugins/package.json                          |  2 +-
 20 files changed, 83 insertions(+), 55 deletions(-)
 create mode 100644 fastlane/metadata/android/en-US/changelogs/150011.txt
 create mode 100644 fastlane/metadata/android/en-US/changelogs/150012.txt
 create mode 100644 fastlane/metadata/android/en-US/changelogs/150013.txt
 create mode 100644 fastlane/metadata/android/en-US/changelogs/150014.txt

diff --git a/CHANGELOG.md b/CHANGELOG.md
index fc0dc45092..e3b08b0f50 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.15.1 - 2026-11-05
+
+### Fixed
+
+- Fixed the daemon failing to start when the terminal worker cannot read its own process identity, which left Paseo Desktop without a daemon on Windows machines where Windows PowerShell 5.1 cannot run `Get-CimInstance` ([#8810](https://github.com/getpaseo/paseo/pull/8810))
+
 ## 0.15.0 - 2026-11-03
 
 Daemon restarts now keep terminal programs running. Interrupted agents can resume in their existing conversations when you turn on agent recovery.
diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
index e70a2f92da..09e516a704 100644
--- a/CHANGELOG.zh-CN.md
+++ b/CHANGELOG.zh-CN.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.15.1 - 2026-11-05
+
+### 修复
+
+- 修复终端工作进程无法读取自身进程标识时 daemon 无法启动的问题；此前在 Windows PowerShell 5.1 无法运行 `Get-CimInstance` 的 Windows 机器上，Paseo 桌面版因此没有可用的 daemon ([#8810](https://github.com/getpaseo/paseo/pull/8810))
+
 ## 0.15.0 - 2026-11-03
 
 daemon 重启后，终端中的程序继续运行。开启 Agent 恢复后，被中断的 Agent 会在原有会话中恢复工作。
diff --git a/fastlane/metadata/android/en-US/changelogs/150011.txt b/fastlane/metadata/android/en-US/changelogs/150011.txt
new file mode 100644
index 0000000000..81cf386750
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150011.txt
@@ -0,0 +1,4 @@
+Fixed
+- Fixed the daemon failing to start when the terminal worker cannot read its own process identity, which left Paseo Desktop without a daemon on Windows machines where Windows PowerShell 5.1 cannot run Get-CimInstance
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150012.txt b/fastlane/metadata/android/en-US/changelogs/150012.txt
new file mode 100644
index 0000000000..81cf386750
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150012.txt
@@ -0,0 +1,4 @@
+Fixed
+- Fixed the daemon failing to start when the terminal worker cannot read its own process identity, which left Paseo Desktop without a daemon on Windows machines where Windows PowerShell 5.1 cannot run Get-CimInstance
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150013.txt b/fastlane/metadata/android/en-US/changelogs/150013.txt
new file mode 100644
index 0000000000..81cf386750
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150013.txt
@@ -0,0 +1,4 @@
+Fixed
+- Fixed the daemon failing to start when the terminal worker cannot read its own process identity, which left Paseo Desktop without a daemon on Windows machines where Windows PowerShell 5.1 cannot run Get-CimInstance
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150014.txt b/fastlane/metadata/android/en-US/changelogs/150014.txt
new file mode 100644
index 0000000000..81cf386750
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150014.txt
@@ -0,0 +1,4 @@
+Fixed
+- Fixed the daemon failing to start when the terminal worker cannot read its own process identity, which left Paseo Desktop without a daemon on Windows machines where Windows PowerShell 5.1 cannot run Get-CimInstance
+
+Full notes: https://paseo.sh/changelog
diff --git a/package-lock.json b/package-lock.json
index f1cbf595c3..db6aab7828 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "paseo",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "paseo",
-      "version": "0.15.0",
+      "version": "0.15.1",
       "hasInstallScript": true,
       "license": "Apache-2.0",
       "workspaces": [
@@ -37468,7 +37468,7 @@
     },
     "packages/app": {
       "name": "@getpaseo/app",
-      "version": "0.15.0",
+      "version": "0.15.1",
       "dependencies": {
         "@codemirror/commands": "6.10.4",
         "@codemirror/language": "6.12.4",
@@ -39637,13 +39637,13 @@
     },
     "packages/cli": {
       "name": "@getpaseo/cli",
-      "version": "0.15.0",
+      "version": "0.15.1",
       "license": "Apache-2.0",
       "dependencies": {
         "@clack/prompts": "^1.0.0",
-        "@getpaseo/client": "0.15.0",
-        "@getpaseo/protocol": "0.15.0",
-        "@getpaseo/server": "0.15.0",
+        "@getpaseo/client": "0.15.1",
+        "@getpaseo/protocol": "0.15.1",
+        "@getpaseo/server": "0.15.1",
         "chalk": "^5.3.0",
         "commander": "^12.0.0",
         "mime-types": "^2.1.35",
@@ -39890,11 +39890,11 @@
     },
     "packages/client": {
       "name": "@getpaseo/client",
-      "version": "0.15.0",
+      "version": "0.15.1",
       "license": "Apache-2.0",
       "dependencies": {
-        "@getpaseo/protocol": "0.15.0",
-        "@getpaseo/relay": "0.15.0",
+        "@getpaseo/protocol": "0.15.1",
+        "@getpaseo/relay": "0.15.1",
         "ws": "^8.20.0",
         "zod": "^4.4.3"
       },
@@ -39906,7 +39906,7 @@
     },
     "packages/desktop": {
       "name": "@getpaseo/desktop",
-      "version": "0.15.0",
+      "version": "0.15.1",
       "license": "Apache-2.0",
       "dependencies": {
         "@getpaseo/cli": "*",
@@ -40149,7 +40149,7 @@
     },
     "packages/expo-two-way-audio": {
       "name": "@getpaseo/expo-two-way-audio",
-      "version": "0.15.0",
+      "version": "0.15.1",
       "license": "MIT",
       "devDependencies": {
         "@types/jest": "^29.5.14",
@@ -40195,7 +40195,7 @@
     },
     "packages/highlight": {
       "name": "@getpaseo/highlight",
-      "version": "0.15.0",
+      "version": "0.15.1",
       "license": "Apache-2.0",
       "dependencies": {
         "@codemirror/language": "6.12.4",
@@ -40225,7 +40225,7 @@
     },
     "packages/plugin": {
       "name": "@getpaseo/plugin",
-      "version": "0.15.0",
+      "version": "0.15.1",
       "license": "Apache-2.0",
       "dependencies": {
         "@agentclientprotocol/sdk": "^1.4.0",
@@ -40233,8 +40233,8 @@
         "use-sync-external-store": "^1.6.0"
       },
       "devDependencies": {
-        "@getpaseo/client": "0.15.0",
-        "@getpaseo/protocol": "0.15.0",
+        "@getpaseo/client": "0.15.1",
+        "@getpaseo/protocol": "0.15.1",
         "@types/node": "^20.9.0",
         "@types/react": "~19.2.0",
         "react": "19.2.3",
@@ -40244,8 +40244,8 @@
         "zod": "^4.4.3"
       },
       "peerDependencies": {
-        "@getpaseo/client": "0.15.0",
-        "@getpaseo/protocol": "0.15.0",
+        "@getpaseo/client": "0.15.1",
+        "@getpaseo/protocol": "0.15.1",
         "react": ">=19.1.0 <20",
         "react-native": ">=0.81.5",
         "zod": "^4.4.3"
@@ -40267,7 +40267,7 @@
     },
     "packages/protocol": {
       "name": "@getpaseo/protocol",
-      "version": "0.15.0",
+      "version": "0.15.1",
       "license": "Apache-2.0",
       "dependencies": {
         "semver": "^7.8.5",
@@ -40295,7 +40295,7 @@
     },
     "packages/relay": {
       "name": "@getpaseo/relay",
-      "version": "0.15.0",
+      "version": "0.15.1",
       "license": "Apache-2.0",
       "dependencies": {
         "@noble/ciphers": "^2.4.0",
@@ -40517,17 +40517,17 @@
     },
     "packages/server": {
       "name": "@getpaseo/server",
-      "version": "0.15.0",
+      "version": "0.15.1",
       "license": "Apache-2.0",
       "dependencies": {
         "@agentclientprotocol/sdk": "^0.17.1",
         "@anthropic-ai/claude-agent-sdk": "0.3.246",
         "@anthropic-ai/sdk": "^0.104.2",
-        "@getpaseo/client": "0.15.0",
-        "@getpaseo/highlight": "0.15.0",
-        "@getpaseo/plugin": "0.15.0",
-        "@getpaseo/protocol": "0.15.0",
-        "@getpaseo/relay": "0.15.0",
+        "@getpaseo/client": "0.15.1",
+        "@getpaseo/highlight": "0.15.1",
+        "@getpaseo/plugin": "0.15.1",
+        "@getpaseo/protocol": "0.15.1",
+        "@getpaseo/relay": "0.15.1",
         "@isaacs/ttlcache": "^2.1.4",
         "@modelcontextprotocol/sdk": "1.29.0",
         "@opencode-ai/sdk": "1.14.46",
@@ -41474,7 +41474,7 @@
     },
     "packages/website": {
       "name": "@getpaseo/website",
-      "version": "0.15.0",
+      "version": "0.15.1",
       "dependencies": {
         "@cloudflare/vite-plugin": "^1.29.1",
         "@cloudflare/workers-types": "^4.20260317.1",
@@ -43084,7 +43084,7 @@
     },
     "plugins": {
       "name": "@getpaseo/builtin-plugins",
-      "version": "0.15.0",
+      "version": "0.15.1",
       "dependencies": {
         "@getpaseo/plugin": "*",
         "zod": "^4.4.3"
diff --git a/package.json b/package.json
index 83f56c1d31..86b21bee50 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "paseo",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "private": true,
   "description": "Paseo: voice-controlled development environment for local AI coding agents",
   "keywords": [
diff --git a/packages/app/package.json b/packages/app/package.json
index 1447bef2f7..3fa80be49a 100644
--- a/packages/app/package.json
+++ b/packages/app/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/app",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "private": true,
   "main": "index.ts",
   "scripts": {
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 6f3737d3cc..bd3b13a4f1 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/cli",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "Paseo CLI - control your AI coding agents from the command line",
   "license": "Apache-2.0",
   "bin": {
@@ -29,9 +29,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.0.0",
-    "@getpaseo/client": "0.15.0",
-    "@getpaseo/protocol": "0.15.0",
-    "@getpaseo/server": "0.15.0",
+    "@getpaseo/client": "0.15.1",
+    "@getpaseo/protocol": "0.15.1",
+    "@getpaseo/server": "0.15.1",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "mime-types": "^2.1.35",
diff --git a/packages/client/package.json b/packages/client/package.json
index ceeebba644..3f6edeaf18 100644
--- a/packages/client/package.json
+++ b/packages/client/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/client",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "Paseo client SDK package",
   "license": "Apache-2.0",
   "files": [
@@ -48,8 +48,8 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@getpaseo/protocol": "0.15.0",
-    "@getpaseo/relay": "0.15.0",
+    "@getpaseo/protocol": "0.15.1",
+    "@getpaseo/relay": "0.15.1",
     "ws": "^8.20.0",
     "zod": "^4.4.3"
   },
diff --git a/packages/desktop/package.json b/packages/desktop/package.json
index 0d92757b2b..788716cef7 100644
--- a/packages/desktop/package.json
+++ b/packages/desktop/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/desktop",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "private": true,
   "description": "Paseo desktop app (Electron wrapper)",
   "homepage": "https://paseo.sh",
diff --git a/packages/expo-two-way-audio/package.json b/packages/expo-two-way-audio/package.json
index cf8fdbdce6..df44ab2a92 100644
--- a/packages/expo-two-way-audio/package.json
+++ b/packages/expo-two-way-audio/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/expo-two-way-audio",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "Native module for two way audio streaming",
   "keywords": [
     "ExpoTwoWayAudio",
diff --git a/packages/highlight/package.json b/packages/highlight/package.json
index 9356707c85..5f40283e3c 100644
--- a/packages/highlight/package.json
+++ b/packages/highlight/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/highlight",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "license": "Apache-2.0",
   "files": [
     "dist",
diff --git a/packages/plugin/package.json b/packages/plugin/package.json
index 7c355d2062..262d57381e 100644
--- a/packages/plugin/package.json
+++ b/packages/plugin/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/plugin",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "Paseo plugin SDK package",
   "license": "Apache-2.0",
   "files": [
@@ -78,8 +78,8 @@
     "use-sync-external-store": "^1.6.0"
   },
   "devDependencies": {
-    "@getpaseo/client": "0.15.0",
-    "@getpaseo/protocol": "0.15.0",
+    "@getpaseo/client": "0.15.1",
+    "@getpaseo/protocol": "0.15.1",
     "@types/node": "^20.9.0",
     "@types/react": "~19.2.0",
     "react": "19.2.3",
@@ -89,8 +89,8 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@getpaseo/client": "0.15.0",
-    "@getpaseo/protocol": "0.15.0",
+    "@getpaseo/client": "0.15.1",
+    "@getpaseo/protocol": "0.15.1",
     "react": ">=19.1.0 <20",
     "react-native": ">=0.81.5",
     "zod": "^4.4.3"
diff --git a/packages/protocol/package.json b/packages/protocol/package.json
index 975ad5833d..d802f6afe3 100644
--- a/packages/protocol/package.json
+++ b/packages/protocol/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/protocol",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "Paseo shared protocol schemas and wire types",
   "license": "Apache-2.0",
   "files": [
diff --git a/packages/relay/package.json b/packages/relay/package.json
index 52d892733f..d4f7af0c0c 100644
--- a/packages/relay/package.json
+++ b/packages/relay/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/relay",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "Paseo relay for bridging daemon and client connections",
   "license": "Apache-2.0",
   "files": [
diff --git a/packages/server/package.json b/packages/server/package.json
index bba90e58cd..2c9615da7a 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/server",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "Paseo backend server",
   "license": "Apache-2.0",
   "files": [
@@ -108,11 +108,11 @@
     "@agentclientprotocol/sdk": "^0.17.1",
     "@anthropic-ai/claude-agent-sdk": "0.3.246",
     "@anthropic-ai/sdk": "^0.104.2",
-    "@getpaseo/client": "0.15.0",
-    "@getpaseo/highlight": "0.15.0",
-    "@getpaseo/plugin": "0.15.0",
-    "@getpaseo/protocol": "0.15.0",
-    "@getpaseo/relay": "0.15.0",
+    "@getpaseo/client": "0.15.1",
+    "@getpaseo/highlight": "0.15.1",
+    "@getpaseo/plugin": "0.15.1",
+    "@getpaseo/protocol": "0.15.1",
+    "@getpaseo/relay": "0.15.1",
     "@isaacs/ttlcache": "^2.1.4",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@opencode-ai/sdk": "1.14.46",
diff --git a/packages/website/package.json b/packages/website/package.json
index 9554c5a8f9..3d9aa70ff8 100644
--- a/packages/website/package.json
+++ b/packages/website/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/website",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "private": true,
   "type": "module",
   "scripts": {
diff --git a/plugins/package.json b/plugins/package.json
index 3e97f0215b..829209bd2a 100644
--- a/plugins/package.json
+++ b/plugins/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/builtin-plugins",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "private": true,
   "type": "module",
   "scripts": {

From 9667ec5576352599c729975c690285e91c4495f5 Mon Sep 17 00:00:00 2001
From: "paseo-ai[bot]" <266920839+paseo-ai[bot]@users.noreply.github.com>
Date: Thu, 5 Nov 2026 03:35:49 +0000
Subject: [PATCH 15/29] fix: update lockfile signatures and Nix hash [skip ci]

---
 nix/npm-deps.hash | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/nix/npm-deps.hash b/nix/npm-deps.hash
index c1fd37546e..acc5703b71 100644
--- a/nix/npm-deps.hash
+++ b/nix/npm-deps.hash
@@ -1 +1 @@
-sha256-plC3c5pOkD/q2Q8Oi/5ARTyVVmN4eze+scbHoEUC7NA=
+sha256-6FUGQhWie9533i6FoOSCdtEWUXHmwei61W0cT6GK66k=

From b920243c74e25ec06e523019fb154f78ea9870be Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Thu, 5 Nov 2026 11:00:04 +0700
Subject: [PATCH 16/29] docs(release): dispatch the instant-admit flip only
 after the release is published (#8816)

A draft release has no tag, so dispatching desktop-rollout.yml before finalize-rollout publishes it fails with "release not found". Seen on v0.15.1.
---
 docs/release.md | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/docs/release.md b/docs/release.md
index 328c189f7b..4ddeb04c28 100644
--- a/docs/release.md
+++ b/docs/release.md
@@ -281,23 +281,26 @@ Drafts do not appear in GitHub's releases feed. Updater clients continue to see
 
 The `rollout_hours` input on `desktop-release.yml` is **only read on `workflow_dispatch`** — tag-push runs always default to 36. To get any other rollout duration on a fresh release, use the post-publish flip below.
 
-### Instant-admit release (rollout_hours=0 from publish)
+### Instant-admit release (rollout_hours=0)
 
-For a fresh release that should admit everyone immediately (low-risk change, doc-only, hotfix, or just a release you want out fast), cut the release normally and queue the rollout flip immediately after:
+`npm run release:patch` and `npm run release:minor` tag-push, and tag-push runs always stamp 36 hours. To admit everyone immediately (hotfix, doc-only change, a release you want out fast), cut the release normally, wait for it to publish, then flip the manifests:
 
 ```bash
-# 1. Cut and publish (default 36h ramp from tag push).
+# 1. Cut and publish (36h ramp from tag push).
 npm run release:patch
 
-# 2. Immediately queue the flip — runs as soon as finalize-rollout completes.
+# 2. Wait for Desktop Release to publish the GitHub Release.
+gh run watch <desktop-release-run-id> --exit-status
+
+# 3. Flip the published manifests to instant admit.
 gh workflow run desktop-rollout.yml \
   -f tag=v0.1.64 \
   -f rollout_hours=0
 ```
 
-**Why this is gap-free:** `desktop-release.yml`'s `finalize-rollout` job and `desktop-rollout.yml` share the concurrency group `desktop-rollout-<tag>`. Dispatching `desktop-rollout.yml` while the tag-push pipeline is still running queues it safely behind `finalize-rollout`. The first public manifests already carry `rolloutHours=36`, then `desktop-rollout.yml` flips them to `rolloutHours=0` shortly afterward. The renderer polls every 30 minutes, so active stable users pick up the new manifest on their next check.
+Dispatch only after `finalize-rollout` has published the release. Until then the release is a draft, and a draft has no tag: `desktop-rollout.yml` looks the release up by tag and fails with `release not found`. The concurrency group `desktop-rollout-<tag>` that the two workflows share orders them only once both are queued; it does not hold an early dispatch until the draft is published.
 
-Run the dispatch right after `release:patch` or `release:minor` returns. Don't wait for the tag-push CI to finish.
+The first public manifests carry `rolloutHours=36` for the minutes between publish and the flip. The renderer polls every 30 minutes, so active stable users pick up the new manifest on their next check.
 
 ### Adjusting an already-published release
 

From 92c8c55f3148ffc8980e95f37513a0f5f9beacfd Mon Sep 17 00:00:00 2001
From: "paseo-bot[bot]" <266920839+paseo-bot[bot]@users.noreply.github.com>
Date: Thu, 5 Nov 2026 08:59:05 +0000
Subject: [PATCH 17/29] Fix registry plugin installs through npm mirrors
 (#8756)

* fix(plugins): install registry npm pins through the configured registry

Registry npm pins carry an npmjs.org tarball URL. Passing that URL to npm made it rewrite the host onto the configured registry and drop any path, so mirrors such as https://mirrors.tencent.com/npm/ returned 404. Install the pinned version instead and identify the reviewed artifact by version and integrity, since a mirror records its own tarball URL.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(plugins): address review on npm artifact comparison

Take an object parameter in isSameNpmArtifact, and clean up the mirror fixture when test setup fails.

Co-authored-by: Cursor <cursoragent@cursor.com>

* test(plugins): verify mirror artifacts with a warm npm cache

A shared npm cache lets the mirror regression reuse tarballs from earlier
fixture installations, so successful installs made no tarball requests.
Check the installed artifact's mirror URL, version and integrity instead
of requiring network transfers.

Co-authored-by: finofliu <finofliu@tencent.com>

---------

Co-authored-by: finofliu <finofliu@tencent.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: paseo-bot[bot] <266920839+paseo-bot[bot]@users.noreply.github.com>
---
 .../plugins/managed-source.posix.test.ts      | 50 +++++++++++++++++++
 .../src/server/plugins/managed-source.ts      | 14 +++---
 .../src/server/plugins/managed-source/npm.ts  | 19 ++++---
 3 files changed, 70 insertions(+), 13 deletions(-)

diff --git a/packages/server/src/server/plugins/managed-source.posix.test.ts b/packages/server/src/server/plugins/managed-source.posix.test.ts
index 7b694f1ef3..440ef52074 100644
--- a/packages/server/src/server/plugins/managed-source.posix.test.ts
+++ b/packages/server/src/server/plugins/managed-source.posix.test.ts
@@ -575,3 +575,53 @@ it("installs and updates only the npm artifacts pinned by the plugin registry",
     else process.env.npm_config_userconfig = previous;
   }
 }, 30_000);
+
+it("installs a registry npm pin through the configured npm mirror", async () => {
+  const { startNpmRegistry, npmPluginPackages } =
+    await import("../../../../../scripts/test-support/npm-registry.mjs");
+  const { readNpmArtifact, resolveNpm } = await import("./managed-source/npm.js");
+  const mirror = await startNpmRegistry(npmPluginPackages());
+  const previous = process.env.npm_config_userconfig;
+  process.env.npm_config_userconfig = mirror.userconfig;
+  // The public registry pins npmjs.org tarball URLs, which a mirror does not serve at the same path.
+  const pin = {
+    version: "1.0.0",
+    resolved: "https://registry.npmjs.org/paseo-fixture-plugin/-/paseo-fixture-plugin-1.0.0.tgz",
+    integrity: "",
+  };
+  const server = createServer((_request, response) => {
+    response.end(
+      JSON.stringify({
+        id: "acme/example",
+        artifact: { kind: "npm", package: "paseo-fixture-plugin", ...pin },
+      }),
+    );
+  });
+  try {
+    const home = await mkdtemp(path.join(tmpdir(), "paseo-registry-npm-mirror-"));
+    roots.push(home);
+    pin.integrity = (await resolveNpm("paseo-fixture-plugin", "1.0.0", home)).integrity;
+    await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const address = server.address();
+    if (!address || typeof address === "string") throw new Error("Missing registry address");
+    const sources = new ManagedPluginSources(home, {
+      defaultUrl: `http://127.0.0.1:${address.port}`,
+    });
+    const candidate = await sources.place(
+      "example",
+      await sources.prepareInstall({ source: "acme/example" }),
+    );
+    await sources.verifyCandidate("example", candidate);
+    sources.commit("example", candidate.record);
+    expect((await sources.describe("example", candidate.directory)).currentRevision).toBe("1.0.0");
+    expect(
+      await readNpmArtifact(path.resolve(candidate.directory, "../.."), "paseo-fixture-plugin"),
+    ).toEqual({ ...pin, resolved: `${mirror.url}/artifacts/1.tgz` });
+  } finally {
+    server.closeAllConnections();
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    await mirror.close();
+    if (previous === undefined) delete process.env.npm_config_userconfig;
+    else process.env.npm_config_userconfig = previous;
+  }
+}, 30_000);
diff --git a/packages/server/src/server/plugins/managed-source.ts b/packages/server/src/server/plugins/managed-source.ts
index 5373b7453a..a20be890b3 100644
--- a/packages/server/src/server/plugins/managed-source.ts
+++ b/packages/server/src/server/plugins/managed-source.ts
@@ -22,7 +22,13 @@ import {
 import { runGitCommand } from "../../utils/run-git-command.js";
 import { ensurePrivateDirectory, writePrivateFileAtomicSync } from "../private-files.js";
 import { readPluginManifest, type PluginManifest } from "./manifest.js";
-import { acquireNpm, isNpmSource, readNpmArtifact, resolveNpm } from "./managed-source/npm.js";
+import {
+  acquireNpm,
+  isNpmSource,
+  isSameNpmArtifact,
+  readNpmArtifact,
+  resolveNpm,
+} from "./managed-source/npm.js";
 
 const GIT_TIMEOUT_MS = 120_000;
 const GIT_ENV = { GIT_TERMINAL_PROMPT: "0" } as const;
@@ -346,11 +352,7 @@ export class ManagedPluginSources {
       throw new Error("Preparation changed the reviewed Git commit");
     if (target?.kind === "npm" && location.identity.kind === "npm") {
       const artifact = await readNpmArtifact(location.versionRoot, location.identity.packageName);
-      if (
-        artifact.version !== target.version ||
-        artifact.integrity !== target.integrity ||
-        artifact.resolved !== target.resolved
-      )
+      if (!isSameNpmArtifact({ installed: artifact, target }))
         throw new Error("Preparation changed the reviewed npm artifact");
     }
   }
diff --git a/packages/server/src/server/plugins/managed-source/npm.ts b/packages/server/src/server/plugins/managed-source/npm.ts
index 315bbc981e..419a807201 100644
--- a/packages/server/src/server/plugins/managed-source/npm.ts
+++ b/packages/server/src/server/plugins/managed-source/npm.ts
@@ -48,7 +48,7 @@ export async function acquireNpm(source: string, installRoot: string, target?: N
       name: "paseo-plugin-installation",
       version: "1.0.0",
       private: true,
-      dependencies: { [packageName]: target?.resolved ?? requestedSpec },
+      dependencies: { [packageName]: requestedSpec },
     }),
   );
   const npm = await requireNpm();
@@ -70,23 +70,28 @@ export async function acquireNpm(source: string, installRoot: string, target?: N
     { cwd: installRoot, timeout: 120_000, maxBuffer: 1024 * 1024 },
   );
   const installed = await readNpmArtifact(installRoot, packageName);
-  if (
-    target &&
-    (installed.version !== target.version ||
-      installed.integrity !== target.integrity ||
-      installed.resolved !== target.resolved)
-  ) {
+  if (target && !isSameNpmArtifact({ installed, target })) {
     throw new Error(`npm artifact changed since review for ${packageName}`);
   }
   return { packageName, ...installed };
 }
 
+// Mirrors serve the reviewed tarball from their own URL, so the content hash identifies it.
+export function isSameNpmArtifact({ installed, target }: NpmArtifactComparison): boolean {
+  return installed.version === target.version && installed.integrity === target.integrity;
+}
+
 export interface NpmArtifact {
   version: string;
   resolved: string;
   integrity: string;
 }
 
+export interface NpmArtifactComparison {
+  installed: NpmArtifact;
+  target: NpmArtifact;
+}
+
 export async function readNpmArtifact(
   installRoot: string,
   packageName: string,

From 902d43da7c76989cebe90c3de5cde9dde76757a1 Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Thu, 5 Nov 2026 16:40:53 +0700
Subject: [PATCH 18/29] chore(release): reconcile v0.15.2 into main (#8845)

* fix(app): hold the loading screen until first-run setup is decided

A new user saw the empty home, the sidebar and a logo jump before setup
popped in. Startup now keeps the splash while setup may still open over
the empty home, for at most 3 s and only while the setup host is
reachable. Remembered-workspace restore does not wait. Web dialogs now
fade in as they already fade out.

(cherry picked from commit a0a7620b6289808847ca55f4c2f053acee287467)
(cherry picked from commit 72d7c0bf262dde715045dbfe2382271313842060)

* fix(app): fade the dialog card in and land the dim at once

(cherry picked from commit 6ef05705a07bd2ae770d53ae9ba5f325473de9f0)
(cherry picked from commit 71c28b431c9e537639b984326bb44466611a6951)

* fix(app): keep the loading screen up while startup redirects

(cherry picked from commit 0b28d4cbff4853ff831f482e415035bfa510fca0)
(cherry picked from commit 13cc485e6fa412ef0439d791f581f119d5800b35)

* test(app): cover a setup host that drops while startup waits

(cherry picked from commit 2a906ef83e6ed6ffe833398d32271d21c26d847c)
(cherry picked from commit 7b6e21207ae2b625e4a97e0deb2898766df2a070)

* fix(app): type the web-only dialog enter animation style

The CSS animation props are not part of ViewStyle. CI typechecks without the
generated expo-env.d.ts, which declares them, so the cast is required there.

(cherry picked from commit b887d979d27dabc7c39d10f39b08ddb89d0c2a35)

* fix(app): keep the setup window mounted when the theme changes

The shell's appearance boundary remounts its dialog hosts whenever a theme
color changes, so picking a theme in setup, or a system light/dark switch,
replaced the open setup window and replayed its fade. Setup draws colors
through CSS variables and themed props, which update in place, and changes
no font size, so it now sits outside that remount.

The dialog enter fade is skipped with reduced motion, and its style is typed
for CI, which typechecks without the generated expo-env.d.ts.

(cherry picked from commit b24c6eacf8693985d914f2b5d61b3df05feb20b6)
(cherry picked from commit cb0e9907f54f7e75b3328d42216a082cc16f0f6f)

* docs(changelog): prepare 0.15.2

(cherry picked from commit 5af1a8ff66642b08d1c84b3aaecdaacba1cc2f30)

* chore(release): cut 0.15.2

(cherry picked from commit e896c05b09707e711a2324fcab7da84a0ae57291)
---
 CHANGELOG.md                                  |  17 +++
 CHANGELOG.zh-CN.md                            |  17 +++
 .../android/en-US/changelogs/150021.txt       |   8 +
 .../android/en-US/changelogs/150022.txt       |   8 +
 .../android/en-US/changelogs/150023.txt       |   8 +
 .../android/en-US/changelogs/150024.txt       |   8 +
 package-lock.json                             |  56 +++----
 package.json                                  |   2 +-
 packages/app/e2e/browser/onboarding.spec.ts   | 137 ++++++++++++++++++
 .../app/e2e/support/helpers/onboarding.ts     |  48 ++++++
 packages/app/package.json                     |   2 +-
 packages/app/src/app/_layout.tsx              |  40 ++++-
 packages/app/src/app/index.tsx                |  12 +-
 .../src/components/adaptive-modal-sheet.tsx   |  23 +++
 .../navigation/host-runtime-bootstrap.test.ts |  23 +++
 .../src/navigation/host-runtime-bootstrap.ts  |   8 +
 packages/app/src/onboarding/index.ts          |   6 +-
 .../onboarding/use-setup-decision-pending.ts  |  24 +++
 packages/cli/package.json                     |   8 +-
 packages/client/package.json                  |   6 +-
 packages/desktop/package.json                 |   2 +-
 packages/expo-two-way-audio/package.json      |   2 +-
 packages/highlight/package.json               |   2 +-
 packages/plugin/package.json                  |  10 +-
 packages/protocol/package.json                |   2 +-
 packages/relay/package.json                   |   2 +-
 packages/server/package.json                  |  12 +-
 packages/website/package.json                 |   2 +-
 plugins/package.json                          |   2 +-
 29 files changed, 434 insertions(+), 63 deletions(-)
 create mode 100644 fastlane/metadata/android/en-US/changelogs/150021.txt
 create mode 100644 fastlane/metadata/android/en-US/changelogs/150022.txt
 create mode 100644 fastlane/metadata/android/en-US/changelogs/150023.txt
 create mode 100644 fastlane/metadata/android/en-US/changelogs/150024.txt
 create mode 100644 packages/app/src/onboarding/use-setup-decision-pending.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e3b08b0f50..10cfa1ef09 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.15.2 - 2026-11-05
+
+### Added
+
+- Added a first-run setup on Paseo Desktop and web that walks new users through theme, providers, projects, agent orchestration and the mobile app, with Settings → General → Show setup again to reopen it ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+- Added project suggestions from the folders where you ran Claude Code, Codex, OpenCode or Pi, shown in the setup Projects step ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+
+### Improved
+
+- Changed the theme picker to a grid of tiles with a preview of each theme ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+- Replaced the "Loading…" text in Providers settings with skeleton rows ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+- Changed controls to two sizes: default controls are 32px tall on desktop and 44px on phones, and compact controls are 28px ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+- Changed first launch to go from the loading screen straight into setup instead of showing the empty home first ([#8824](https://github.com/getpaseo/paseo/pull/8824))
+- Changed dialogs on desktop and web to fade in over about 160ms ([#8824](https://github.com/getpaseo/paseo/pull/8824))
+- Changed modal and sheet backgrounds to match the screen background ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+- Changed documentation links in Settings sections to a `Label ↗` link beside the section title ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+
 ## 0.15.1 - 2026-11-05
 
 ### Fixed
diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
index 09e516a704..5f0156eb0e 100644
--- a/CHANGELOG.zh-CN.md
+++ b/CHANGELOG.zh-CN.md
@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.15.2 - 2026-11-05
+
+### 新增
+
+- 在 Paseo 桌面版和网页版新增首次运行引导，依次带新用户设置主题、提供商、项目、Agent 编排和移动端应用，并可通过“设置 → 通用 → Show setup again”重新打开 ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+- 在引导的“项目”步骤中，根据你运行过 Claude Code、Codex、OpenCode 或 Pi 的文件夹推荐项目 ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+
+### 改进
+
+- 将主题选择器改为带各主题预览的图块网格 ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+- 将“提供商”设置中的“Loading…”文字替换为骨架占位行 ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+- 将控件统一为两种尺寸：默认控件在桌面端高 32px、在手机上高 44px，紧凑控件高 28px ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+- 将首次启动改为从加载界面直接进入引导，不再先显示空白的主页 ([#8824](https://github.com/getpaseo/paseo/pull/8824))
+- 将桌面端和网页版的对话框改为约 160 毫秒的淡入 ([#8824](https://github.com/getpaseo/paseo/pull/8824))
+- 将弹窗和面板的背景改为与屏幕背景一致 ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+- 将“设置”各分区的文档链接改为分区标题旁的 `Label ↗` 链接 ([#8363](https://github.com/getpaseo/paseo/pull/8363))
+
 ## 0.15.1 - 2026-11-05
 
 ### 修复
diff --git a/fastlane/metadata/android/en-US/changelogs/150021.txt b/fastlane/metadata/android/en-US/changelogs/150021.txt
new file mode 100644
index 0000000000..1c9864a4ad
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150021.txt
@@ -0,0 +1,8 @@
+Added
+- Added a first-run setup on Paseo Desktop and web that walks new users through theme, providers, projects, agent orchestration and the mobile app, with Settings → General → Show setup again to reopen it
+- Added project suggestions from the folders where you ran Claude Code, Codex, OpenCode or Pi, shown in the setup Projects step
+
+Improved
+- Changed the theme picker to a grid of tiles with a preview of each theme
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150022.txt b/fastlane/metadata/android/en-US/changelogs/150022.txt
new file mode 100644
index 0000000000..1c9864a4ad
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150022.txt
@@ -0,0 +1,8 @@
+Added
+- Added a first-run setup on Paseo Desktop and web that walks new users through theme, providers, projects, agent orchestration and the mobile app, with Settings → General → Show setup again to reopen it
+- Added project suggestions from the folders where you ran Claude Code, Codex, OpenCode or Pi, shown in the setup Projects step
+
+Improved
+- Changed the theme picker to a grid of tiles with a preview of each theme
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150023.txt b/fastlane/metadata/android/en-US/changelogs/150023.txt
new file mode 100644
index 0000000000..1c9864a4ad
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150023.txt
@@ -0,0 +1,8 @@
+Added
+- Added a first-run setup on Paseo Desktop and web that walks new users through theme, providers, projects, agent orchestration and the mobile app, with Settings → General → Show setup again to reopen it
+- Added project suggestions from the folders where you ran Claude Code, Codex, OpenCode or Pi, shown in the setup Projects step
+
+Improved
+- Changed the theme picker to a grid of tiles with a preview of each theme
+
+Full notes: https://paseo.sh/changelog
diff --git a/fastlane/metadata/android/en-US/changelogs/150024.txt b/fastlane/metadata/android/en-US/changelogs/150024.txt
new file mode 100644
index 0000000000..1c9864a4ad
--- /dev/null
+++ b/fastlane/metadata/android/en-US/changelogs/150024.txt
@@ -0,0 +1,8 @@
+Added
+- Added a first-run setup on Paseo Desktop and web that walks new users through theme, providers, projects, agent orchestration and the mobile app, with Settings → General → Show setup again to reopen it
+- Added project suggestions from the folders where you ran Claude Code, Codex, OpenCode or Pi, shown in the setup Projects step
+
+Improved
+- Changed the theme picker to a grid of tiles with a preview of each theme
+
+Full notes: https://paseo.sh/changelog
diff --git a/package-lock.json b/package-lock.json
index db6aab7828..e4e82efad8 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "paseo",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "paseo",
-      "version": "0.15.1",
+      "version": "0.15.2",
       "hasInstallScript": true,
       "license": "Apache-2.0",
       "workspaces": [
@@ -37468,7 +37468,7 @@
     },
     "packages/app": {
       "name": "@getpaseo/app",
-      "version": "0.15.1",
+      "version": "0.15.2",
       "dependencies": {
         "@codemirror/commands": "6.10.4",
         "@codemirror/language": "6.12.4",
@@ -39637,13 +39637,13 @@
     },
     "packages/cli": {
       "name": "@getpaseo/cli",
-      "version": "0.15.1",
+      "version": "0.15.2",
       "license": "Apache-2.0",
       "dependencies": {
         "@clack/prompts": "^1.0.0",
-        "@getpaseo/client": "0.15.1",
-        "@getpaseo/protocol": "0.15.1",
-        "@getpaseo/server": "0.15.1",
+        "@getpaseo/client": "0.15.2",
+        "@getpaseo/protocol": "0.15.2",
+        "@getpaseo/server": "0.15.2",
         "chalk": "^5.3.0",
         "commander": "^12.0.0",
         "mime-types": "^2.1.35",
@@ -39890,11 +39890,11 @@
     },
     "packages/client": {
       "name": "@getpaseo/client",
-      "version": "0.15.1",
+      "version": "0.15.2",
       "license": "Apache-2.0",
       "dependencies": {
-        "@getpaseo/protocol": "0.15.1",
-        "@getpaseo/relay": "0.15.1",
+        "@getpaseo/protocol": "0.15.2",
+        "@getpaseo/relay": "0.15.2",
         "ws": "^8.20.0",
         "zod": "^4.4.3"
       },
@@ -39906,7 +39906,7 @@
     },
     "packages/desktop": {
       "name": "@getpaseo/desktop",
-      "version": "0.15.1",
+      "version": "0.15.2",
       "license": "Apache-2.0",
       "dependencies": {
         "@getpaseo/cli": "*",
@@ -40149,7 +40149,7 @@
     },
     "packages/expo-two-way-audio": {
       "name": "@getpaseo/expo-two-way-audio",
-      "version": "0.15.1",
+      "version": "0.15.2",
       "license": "MIT",
       "devDependencies": {
         "@types/jest": "^29.5.14",
@@ -40195,7 +40195,7 @@
     },
     "packages/highlight": {
       "name": "@getpaseo/highlight",
-      "version": "0.15.1",
+      "version": "0.15.2",
       "license": "Apache-2.0",
       "dependencies": {
         "@codemirror/language": "6.12.4",
@@ -40225,7 +40225,7 @@
     },
     "packages/plugin": {
       "name": "@getpaseo/plugin",
-      "version": "0.15.1",
+      "version": "0.15.2",
       "license": "Apache-2.0",
       "dependencies": {
         "@agentclientprotocol/sdk": "^1.4.0",
@@ -40233,8 +40233,8 @@
         "use-sync-external-store": "^1.6.0"
       },
       "devDependencies": {
-        "@getpaseo/client": "0.15.1",
-        "@getpaseo/protocol": "0.15.1",
+        "@getpaseo/client": "0.15.2",
+        "@getpaseo/protocol": "0.15.2",
         "@types/node": "^20.9.0",
         "@types/react": "~19.2.0",
         "react": "19.2.3",
@@ -40244,8 +40244,8 @@
         "zod": "^4.4.3"
       },
       "peerDependencies": {
-        "@getpaseo/client": "0.15.1",
-        "@getpaseo/protocol": "0.15.1",
+        "@getpaseo/client": "0.15.2",
+        "@getpaseo/protocol": "0.15.2",
         "react": ">=19.1.0 <20",
         "react-native": ">=0.81.5",
         "zod": "^4.4.3"
@@ -40267,7 +40267,7 @@
     },
     "packages/protocol": {
       "name": "@getpaseo/protocol",
-      "version": "0.15.1",
+      "version": "0.15.2",
       "license": "Apache-2.0",
       "dependencies": {
         "semver": "^7.8.5",
@@ -40295,7 +40295,7 @@
     },
     "packages/relay": {
       "name": "@getpaseo/relay",
-      "version": "0.15.1",
+      "version": "0.15.2",
       "license": "Apache-2.0",
       "dependencies": {
         "@noble/ciphers": "^2.4.0",
@@ -40517,17 +40517,17 @@
     },
     "packages/server": {
       "name": "@getpaseo/server",
-      "version": "0.15.1",
+      "version": "0.15.2",
       "license": "Apache-2.0",
       "dependencies": {
         "@agentclientprotocol/sdk": "^0.17.1",
         "@anthropic-ai/claude-agent-sdk": "0.3.246",
         "@anthropic-ai/sdk": "^0.104.2",
-        "@getpaseo/client": "0.15.1",
-        "@getpaseo/highlight": "0.15.1",
-        "@getpaseo/plugin": "0.15.1",
-        "@getpaseo/protocol": "0.15.1",
-        "@getpaseo/relay": "0.15.1",
+        "@getpaseo/client": "0.15.2",
+        "@getpaseo/highlight": "0.15.2",
+        "@getpaseo/plugin": "0.15.2",
+        "@getpaseo/protocol": "0.15.2",
+        "@getpaseo/relay": "0.15.2",
         "@isaacs/ttlcache": "^2.1.4",
         "@modelcontextprotocol/sdk": "1.29.0",
         "@opencode-ai/sdk": "1.14.46",
@@ -41474,7 +41474,7 @@
     },
     "packages/website": {
       "name": "@getpaseo/website",
-      "version": "0.15.1",
+      "version": "0.15.2",
       "dependencies": {
         "@cloudflare/vite-plugin": "^1.29.1",
         "@cloudflare/workers-types": "^4.20260317.1",
@@ -43084,7 +43084,7 @@
     },
     "plugins": {
       "name": "@getpaseo/builtin-plugins",
-      "version": "0.15.1",
+      "version": "0.15.2",
       "dependencies": {
         "@getpaseo/plugin": "*",
         "zod": "^4.4.3"
diff --git a/package.json b/package.json
index 86b21bee50..b5fd31ae8e 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "paseo",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "private": true,
   "description": "Paseo: voice-controlled development environment for local AI coding agents",
   "keywords": [
diff --git a/packages/app/e2e/browser/onboarding.spec.ts b/packages/app/e2e/browser/onboarding.spec.ts
index 68d54687a9..cf9ab06442 100644
--- a/packages/app/e2e/browser/onboarding.spec.ts
+++ b/packages/app/e2e/browser/onboarding.spec.ts
@@ -12,11 +12,15 @@ import {
   openAppAsNewUser,
   openRelayPairingFromSetup,
   closeRelayPairing,
+  emptyHome,
+  loadingScreen,
   openTailscaleDocsFromSetup,
   paseoToolsSwitch,
   pickTheme,
   projectSuggestion,
   projectSuggestionRow,
+  readFirstLaunch,
+  recordFirstLaunch,
   setupModal,
   setupPrimaryButton,
   showSetupAgainFromSettings,
@@ -99,6 +103,139 @@ test("a new user is walked through setup once", async ({ page }, testInfo) => {
   }
 });
 
+test("a new user goes from the loading screen straight into setup", async ({ page }) => {
+  const host = await startSetupHost("first-launch");
+
+  try {
+    await recordFirstLaunch(page);
+    await openAppAsNewUser(page, host);
+    await expectSetupStep(page, "Welcome to Paseo");
+
+    const launch = await readFirstLaunch(page);
+    expect(launch.appBeforeSetup).toBe(false);
+    expect(launch.setupOpacityOnArrival).toBeLessThan(1);
+    await expect(setupModal(page)).toHaveCSS("opacity", "1");
+  } finally {
+    await host.close();
+  }
+});
+
+test("with reduced motion, setup appears without fading in", async ({ page }) => {
+  const host = await startSetupHost("reduced-motion");
+
+  try {
+    await page.emulateMedia({ reducedMotion: "reduce" });
+    await recordFirstLaunch(page);
+    await openAppAsNewUser(page, host);
+    await expectSetupStep(page, "Welcome to Paseo");
+
+    expect((await readFirstLaunch(page)).setupOpacityOnArrival).toBe(1);
+  } finally {
+    await host.close();
+  }
+});
+
+test("changing the theme keeps the setup window in place on every step", async ({ page }) => {
+  const host = await startSetupHost("theme-change");
+
+  try {
+    await openAppAsNewUser(page, host);
+    await expectSetupStep(page, "Welcome to Paseo");
+    const setupWindow = await setupModal(page).elementHandle();
+
+    for (const title of [
+      "Welcome to Paseo",
+      "Your agents",
+      "Add your projects",
+      "Let agents use Paseo",
+      "Take your agents with you",
+    ]) {
+      if (title !== "Welcome to Paseo") await continueSetup(page);
+      await expectSetupStep(page, title);
+      const heading = setupModal(page).getByRole("heading", { name: title });
+      const headingNode = await heading.elementHandle();
+      const lightColor = await heading.evaluate((node) => getComputedStyle(node).color);
+      await page.emulateMedia({ colorScheme: "dark" });
+      await expect(heading).not.toHaveCSS("color", lightColor);
+      await page.emulateMedia({ colorScheme: "light" });
+      await expect(heading).toHaveCSS("color", lightColor);
+      expect(await setupWindow?.evaluate((node) => node.isConnected), title).toBe(true);
+      expect(await headingNode?.evaluate((node) => node.isConnected), title).toBe(true);
+    }
+
+    await goToSetupStep(page, "Appearance");
+    await pickTheme(page, "Midnight");
+    await pickTheme(page, "Light");
+    expect(await setupWindow?.evaluate((node) => node.isConnected)).toBe(true);
+  } finally {
+    await host.close();
+  }
+});
+
+test("the loading screen stays up while the setup host loads its workspaces", async ({ page }) => {
+  const host = await startSetupHost("slow-workspaces");
+  const gate = await installDaemonWebSocketGate(page, { port: host.port });
+
+  try {
+    await recordFirstLaunch(page);
+    gate.holdNextClientRequest("fetch_workspaces_request");
+    await openAppAsNewUser(page, host);
+    await gate.waitForHeldClientRequest();
+    await expect(loadingScreen(page)).toBeVisible();
+    await expect(emptyHome(page)).toHaveCount(0);
+
+    gate.releaseHeldClientRequest();
+    await expectSetupStep(page, "Welcome to Paseo");
+    expect((await readFirstLaunch(page)).appBeforeSetup).toBe(false);
+  } finally {
+    await host.close();
+  }
+});
+
+test("a setup host that never loads its workspaces still lands on the home", async ({ page }) => {
+  const host = await startSetupHost("stuck-workspaces");
+  const gate = await installDaemonWebSocketGate(page, { port: host.port });
+
+  try {
+    gate.holdNextClientRequest("fetch_workspaces_request");
+    await openAppAsNewUser(page, host);
+    await gate.waitForHeldClientRequest();
+    await expect(emptyHome(page)).toBeVisible({ timeout: 15_000 });
+    await expect(setupModal(page)).toHaveCount(0);
+
+    // Setup still opens once the host answers.
+    gate.releaseHeldClientRequest();
+    await expectSetupStep(page, "Welcome to Paseo");
+  } finally {
+    await host.close();
+  }
+});
+
+test("a setup host that drops while loading still lands on the home", async ({ page }) => {
+  const host = await startSetupHost("dropped-workspaces");
+  const gate = await installDaemonWebSocketGate(page, { port: host.port });
+
+  try {
+    gate.holdNextClientRequest("fetch_workspaces_request");
+    await openAppAsNewUser(page, host);
+    await gate.waitForHeldClientRequest();
+    await gate.drop();
+    await expect(emptyHome(page)).toBeVisible({ timeout: 15_000 });
+    await expect(setupModal(page)).toHaveCount(0);
+  } finally {
+    await host.close();
+  }
+});
+
+test("an unreachable setup host lands on the home without setup", async ({ page }) => {
+  const host = await startSetupHost("unreachable");
+  await host.close();
+
+  await openAppAsNewUser(page, host);
+  await expect(emptyHome(page)).toBeVisible({ timeout: 15_000 });
+  await expect(setupModal(page)).toHaveCount(0);
+});
+
 test("setup suggests the repos the user already ran agents in", async ({ page }, testInfo) => {
   const repo = await createTempGitRepo("onboarding-history-");
   const repoName = path.basename(repo.path);
diff --git a/packages/app/e2e/support/helpers/onboarding.ts b/packages/app/e2e/support/helpers/onboarding.ts
index 6f1d4c53b0..4226c1c27e 100644
--- a/packages/app/e2e/support/helpers/onboarding.ts
+++ b/packages/app/e2e/support/helpers/onboarding.ts
@@ -34,6 +34,54 @@ export async function openAppAsNewUser(
   await page.goto("/");
 }
 
+interface FirstLaunchRecord {
+  appBeforeSetup: boolean;
+  setupOpacityOnArrival: number | null;
+}
+
+/**
+ * Watches the page from its first paint: whether the app's sidebar or home showed before setup,
+ * and how opaque setup was when it arrived. Call before `openAppAsNewUser`.
+ */
+export async function recordFirstLaunch(page: Page): Promise<void> {
+  await page.addInitScript(() => {
+    const record: FirstLaunchRecord = { appBeforeSetup: false, setupOpacityOnArrival: null };
+    Object.assign(window, { __firstLaunch: record });
+    const observer = new MutationObserver(() => {
+      const setup = document.querySelector('[data-testid="onboarding-modal"] [role="dialog"]');
+      if (setup) {
+        record.setupOpacityOnArrival = Number(getComputedStyle(setup).opacity);
+        observer.disconnect();
+        return;
+      }
+      if (
+        document.querySelector(
+          '[data-testid="open-project-submit"], [data-testid="sidebar-settings"]',
+        )
+      ) {
+        record.appBeforeSetup = true;
+      }
+    });
+    observer.observe(document, { childList: true, subtree: true });
+  });
+}
+
+export async function readFirstLaunch(page: Page): Promise<FirstLaunchRecord> {
+  return page.evaluate(
+    () => (window as unknown as { __firstLaunch: FirstLaunchRecord }).__firstLaunch,
+  );
+}
+
+/** The loading screen the app shows while it starts. */
+export function loadingScreen(page: Page): Locator {
+  return page.getByTestId("startup-splash");
+}
+
+/** The empty home a host with no projects lands on. */
+export function emptyHome(page: Page): Locator {
+  return page.getByTestId("open-project-submit");
+}
+
 export function setupModal(page: Page): Locator {
   return page.getByTestId("onboarding-modal").getByRole("dialog");
 }
diff --git a/packages/app/package.json b/packages/app/package.json
index 3fa80be49a..2c897be9d4 100644
--- a/packages/app/package.json
+++ b/packages/app/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/app",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "private": true,
   "main": "index.ts",
   "scripts": {
diff --git a/packages/app/src/app/_layout.tsx b/packages/app/src/app/_layout.tsx
index d5b6794c03..8548b4bb76 100644
--- a/packages/app/src/app/_layout.tsx
+++ b/packages/app/src/app/_layout.tsx
@@ -46,7 +46,7 @@ import { DownloadToast } from "@/components/download-toast";
 import { QuittingOverlay } from "@/components/quitting-overlay";
 import { KeyboardShortcutsDialog } from "@/components/keyboard-shortcuts-dialog";
 import { ChangelogHost } from "@/changelog";
-import { OnboardingHost } from "@/onboarding";
+import { OnboardingHost, useIsSetupDecisionPending } from "@/onboarding";
 import { AppDiagnosticHost } from "@/components/app-diagnostic-host";
 import { AppearanceStyleBoundary } from "@/components/appearance-style-boundary";
 import { LeftSidebar } from "@/components/left-sidebar";
@@ -151,6 +151,7 @@ export interface HostRuntimeBootstrapState {
   splashError: string | null;
   retry: () => void;
   hasGivenUpWaitingForHost: boolean;
+  isWaitingForSetup: boolean;
   storeReady: boolean;
   startupBlocker: StartupBlocker;
 }
@@ -159,6 +160,7 @@ const HostRuntimeBootstrapContext = createContext<HostRuntimeBootstrapState>({
   splashError: null,
   retry: () => {},
   hasGivenUpWaitingForHost: false,
+  isWaitingForSetup: false,
   storeReady: false,
   startupBlocker: { kind: "none" },
 });
@@ -255,6 +257,9 @@ function useDaemonStartIsRunning(): boolean {
 }
 
 const STARTUP_GIVE_UP_TIMEOUT_MS = 5_000;
+// How long the splash waits on top of host startup to learn whether setup opens. A slow host
+// lands on the home instead, and setup opens over it once it is decided.
+const STARTUP_SETUP_WAIT_TIMEOUT_MS = 3_000;
 
 async function shouldStartBuiltInDaemon(): Promise<boolean> {
   if (!shouldUseDesktopDaemon()) {
@@ -316,6 +321,23 @@ function HostRuntimeBootstrapProvider({ children }: { children: ReactNode }) {
     };
   }, [shouldRunGiveUpTimer]);
 
+  const isSetupDecisionPending = useIsSetupDecisionPending();
+  const [hasGivenUpWaitingForSetup, setHasGivenUpWaitingForSetup] = useState(false);
+  const isWaitingForSetup = isSetupDecisionPending && !hasGivenUpWaitingForSetup;
+  const shouldRunSetupWaitTimer = isWaitingForSetup && startupBlocker.kind === "none";
+
+  useEffect(() => {
+    if (!shouldRunSetupWaitTimer) {
+      return;
+    }
+    const handle = setTimeout(() => {
+      setHasGivenUpWaitingForSetup(true);
+    }, STARTUP_SETUP_WAIT_TIMEOUT_MS);
+    return () => {
+      clearTimeout(handle);
+    };
+  }, [shouldRunSetupWaitTimer]);
+
   const retry = useCallback(() => {
     const daemonStartService = getDaemonStartService({ store: getHostRuntimeStore() });
     void daemonStartService.startIfEnabled({ shouldStart: shouldStartBuiltInDaemon });
@@ -326,8 +348,15 @@ function HostRuntimeBootstrapProvider({ children }: { children: ReactNode }) {
   const storeReady = resolveStartupNavigationReady({ startupBlocker });
 
   const state = useMemo<HostRuntimeBootstrapState>(
-    () => ({ splashError, retry, hasGivenUpWaitingForHost, storeReady, startupBlocker }),
-    [splashError, retry, hasGivenUpWaitingForHost, storeReady, startupBlocker],
+    () => ({
+      splashError,
+      retry,
+      hasGivenUpWaitingForHost,
+      isWaitingForSetup,
+      storeReady,
+      startupBlocker,
+    }),
+    [splashError, retry, hasGivenUpWaitingForHost, isWaitingForSetup, storeReady, startupBlocker],
   );
 
   return (
@@ -529,7 +558,6 @@ function AppContainer({ children, chromeEnabled: chromeEnabledOverride }: AppCon
         <WorkspacePinShortcutHandler />
         <WorkspaceRenameHost />
         <CommandCenter />
-        <OnboardingHost />
         <AddProjectFlowHost />
         <HostChooserModal />
         <HostConfirmationSheet />
@@ -540,6 +568,10 @@ function AppContainer({ children, chromeEnabled: chromeEnabledOverride }: AppCon
         <ChangelogHost />
         <QuittingOverlay />
       </AppearanceStyleBoundary>
+      {/* Setup changes the theme while it is open, so it stays out of the remount above. Its
+          colors are CSS variables and themed props, which update in place, and setup changes no
+          font size. */}
+      <OnboardingHost />
     </View>
   );
 
diff --git a/packages/app/src/app/index.tsx b/packages/app/src/app/index.tsx
index e0649f65a1..f6850a2a57 100644
--- a/packages/app/src/app/index.tsx
+++ b/packages/app/src/app/index.tsx
@@ -45,11 +45,19 @@ export default function Index() {
     }),
     isWorkspaceSelectionLoaded,
     hasGivenUpWaitingForHost: bootstrapState.hasGivenUpWaitingForHost,
+    isWaitingForSetup: bootstrapState.isWaitingForSetup,
   });
 
+  const splash = <StartupSplashScreen bootstrapState={isDesktop ? bootstrapState : undefined} />;
   if (startupRoute.kind === "redirect") {
-    return <Redirect href={startupRoute.href} />;
+    // The loading screen stays up until the target route paints; a redirect alone renders nothing.
+    return (
+      <>
+        {splash}
+        <Redirect href={startupRoute.href} />
+      </>
+    );
   }
 
-  return <StartupSplashScreen bootstrapState={isDesktop ? bootstrapState : undefined} />;
+  return splash;
 }
diff --git a/packages/app/src/components/adaptive-modal-sheet.tsx b/packages/app/src/components/adaptive-modal-sheet.tsx
index bff7fe34f6..7e28f3d81a 100644
--- a/packages/app/src/components/adaptive-modal-sheet.tsx
+++ b/packages/app/src/components/adaptive-modal-sheet.tsx
@@ -232,6 +232,28 @@ const styles = StyleSheet.create((theme) => ({
 }));
 
 const WEB_EXIT_DURATION_MS = 160;
+const WEB_ENTER_DURATION_MS = 160;
+const WEB_ENTER_ANIMATION_NAME = "paseo-modal-enter";
+
+// The desktop card fades in; the dim lands at once, so the screen behind is never seen undimmed
+// while the dialog arrives. A CSS animation runs from the card's first paint, so a dialog that opens
+// on its own, like first-run setup, never pops in. Closing fades the whole overlay. With reduced
+// motion the keyframes are never defined, so the card appears at once.
+function ensureWebEnterKeyframes() {
+  if (!isWeb || typeof document === "undefined") return;
+  if (document.getElementById(WEB_ENTER_ANIMATION_NAME)) return;
+  const style = document.createElement("style");
+  style.id = WEB_ENTER_ANIMATION_NAME;
+  style.textContent = `@media (prefers-reduced-motion: no-preference) { @keyframes ${WEB_ENTER_ANIMATION_NAME} { from { opacity: 0; } to { opacity: 1; } } }`;
+  document.head.appendChild(style);
+}
+ensureWebEnterKeyframes();
+// The CSS animation props are not part of ViewStyle without the generated expo-env.d.ts.
+const WEB_ENTER_STYLE = {
+  animationName: WEB_ENTER_ANIMATION_NAME,
+  animationDuration: `${WEB_ENTER_DURATION_MS}ms`,
+  animationTimingFunction: "ease-out",
+} as unknown as ViewStyle;
 
 /** The compact sheet's surface: Gorhom's `backgroundComponent` for every bottom sheet. */
 export function SheetBackground({ style }: BottomSheetBackgroundProps) {
@@ -662,6 +684,7 @@ export function AdaptiveModalSheet({
       styles.desktopCard,
       desktopHeight != null && { height: desktopHeight },
       desktopMaxWidth != null && { maxWidth: desktopMaxWidth },
+      isWeb && WEB_ENTER_STYLE,
     ],
     [desktopMaxWidth, desktopHeight],
   );
diff --git a/packages/app/src/navigation/host-runtime-bootstrap.test.ts b/packages/app/src/navigation/host-runtime-bootstrap.test.ts
index 6e1e130090..fe7687886c 100644
--- a/packages/app/src/navigation/host-runtime-bootstrap.test.ts
+++ b/packages/app/src/navigation/host-runtime-bootstrap.test.ts
@@ -177,6 +177,7 @@ describe("resolveStartupRoute", () => {
     workspaceSelectionStatus: "unknown" as const,
     isWorkspaceSelectionLoaded: true,
     hasGivenUpWaitingForHost: false,
+    isWaitingForSetup: false,
   };
   const baseHostInput = {
     route: { kind: "host" as const, serverId: "server-saved" },
@@ -278,6 +279,28 @@ describe("resolveStartupRoute", () => {
     ).toEqual({ kind: "redirect", href: "/h/srv-desktop" });
   });
 
+  it("holds the splash over the empty home while setup may still open", () => {
+    expect(
+      resolveStartupRoute({
+        ...baseIndexInput,
+        hosts: [{ serverId: "srv-desktop" }],
+        anyOnlineHostServerId: "srv-desktop",
+        isWaitingForSetup: true,
+      }),
+    ).toEqual({ kind: "splash" });
+  });
+
+  it("restores a saved workspace without waiting for setup", () => {
+    expect(
+      resolveStartupRoute({
+        ...baseIndexInput,
+        hosts: [{ serverId: "server-1" }],
+        workspaceSelection: { serverId: "server-1", workspaceId: "workspace-a" },
+        isWaitingForSetup: true,
+      }),
+    ).toEqual({ kind: "redirect", href: "/h/server-1" });
+  });
+
   it("keeps a known connecting host in app-owned routing instead of showing welcome", () => {
     expect(
       resolveStartupRoute({
diff --git a/packages/app/src/navigation/host-runtime-bootstrap.ts b/packages/app/src/navigation/host-runtime-bootstrap.ts
index 8ee1f7bfb2..c78b40c1cc 100644
--- a/packages/app/src/navigation/host-runtime-bootstrap.ts
+++ b/packages/app/src/navigation/host-runtime-bootstrap.ts
@@ -117,6 +117,8 @@ export interface ResolveIndexStartupRouteInput extends ResolveStartupRouteBaseIn
   workspaceSelectionStatus: WorkspaceSelectionStatus;
   isWorkspaceSelectionLoaded: boolean;
   hasGivenUpWaitingForHost: boolean;
+  /** Setup may still open over the empty home; see `useIsSetupDecisionPending`. */
+  isWaitingForSetup: boolean;
 }
 
 export interface ResolveHostStartupRouteInput extends ResolveStartupRouteBaseInput {
@@ -198,6 +200,12 @@ function resolveReadyIndexStartupRoute(input: ResolveIndexStartupRouteInput): St
     };
   }
 
+  // Without a workspace to restore, startup lands on the empty home. A new user's setup opens
+  // over it, so hold the splash until that is known instead of flashing the home first.
+  if (input.isWaitingForSetup) {
+    return { kind: "splash" };
+  }
+
   if (input.anyOnlineHostServerId) {
     return { kind: "redirect", href: buildHostRootRoute(input.anyOnlineHostServerId) };
   }
diff --git a/packages/app/src/onboarding/index.ts b/packages/app/src/onboarding/index.ts
index 68c80d8f0d..78d3da6016 100644
--- a/packages/app/src/onboarding/index.ts
+++ b/packages/app/src/onboarding/index.ts
@@ -2,8 +2,10 @@
  * First-run setup: a one-time modal that walks a new user through the surfaces Settings
  * already has — appearance, providers, projects, Paseo tools and phone pairing.
  *
- * The app shell mounts the host; Settings reopens it. Whether it opens, which steps it has,
- * and how completion is remembered stay inside; import from `@/onboarding` only.
+ * The app shell mounts the host, startup waits for its decision, and Settings reopens it. Whether
+ * it opens, which steps it has, and how completion is remembered stay inside; import from
+ * `@/onboarding` only.
  */
 export { OnboardingHost } from "./onboarding-host";
 export { useOpenOnboarding } from "./use-open-onboarding";
+export { useIsSetupDecisionPending } from "./use-setup-decision-pending";
diff --git a/packages/app/src/onboarding/use-setup-decision-pending.ts b/packages/app/src/onboarding/use-setup-decision-pending.ts
new file mode 100644
index 0000000000..5918833ce6
--- /dev/null
+++ b/packages/app/src/onboarding/use-setup-decision-pending.ts
@@ -0,0 +1,24 @@
+import { useSyncExternalStore } from "react";
+import { isNative } from "@/constants/platform";
+import { useHostRuntimeConnectionStatus } from "@/runtime/host-runtime";
+import { getOnboardingModel } from "./internal/onboarding-instance";
+import { useSetupHostServerId } from "./internal/use-setup-host";
+
+/**
+ * True while this launch may still open setup: it has not been decided, and the setup host is
+ * connecting, or connected and loading its workspaces. Startup keeps its loading screen up
+ * meanwhile, so a new user lands on setup rather than on the empty home first. False on phones,
+ * where setup never opens, when there is no setup host, and while the host is unreachable.
+ */
+export const useIsSetupDecisionPending: () => boolean = isNative
+  ? () => false
+  : useIsSetupDecisionPendingOnDesktop;
+
+function useIsSetupDecisionPendingOnDesktop(): boolean {
+  const model = getOnboardingModel();
+  const state = useSyncExternalStore(model.subscribe, model.getState, model.getState);
+  const serverId = useSetupHostServerId();
+  const connectionStatus = useHostRuntimeConnectionStatus(serverId ?? "");
+  if (state.status !== "deciding" || !serverId) return false;
+  return connectionStatus !== "offline" && connectionStatus !== "error";
+}
diff --git a/packages/cli/package.json b/packages/cli/package.json
index bd3b13a4f1..9248988869 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/cli",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "description": "Paseo CLI - control your AI coding agents from the command line",
   "license": "Apache-2.0",
   "bin": {
@@ -29,9 +29,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.0.0",
-    "@getpaseo/client": "0.15.1",
-    "@getpaseo/protocol": "0.15.1",
-    "@getpaseo/server": "0.15.1",
+    "@getpaseo/client": "0.15.2",
+    "@getpaseo/protocol": "0.15.2",
+    "@getpaseo/server": "0.15.2",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "mime-types": "^2.1.35",
diff --git a/packages/client/package.json b/packages/client/package.json
index 3f6edeaf18..62e5b8c664 100644
--- a/packages/client/package.json
+++ b/packages/client/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/client",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "description": "Paseo client SDK package",
   "license": "Apache-2.0",
   "files": [
@@ -48,8 +48,8 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@getpaseo/protocol": "0.15.1",
-    "@getpaseo/relay": "0.15.1",
+    "@getpaseo/protocol": "0.15.2",
+    "@getpaseo/relay": "0.15.2",
     "ws": "^8.20.0",
     "zod": "^4.4.3"
   },
diff --git a/packages/desktop/package.json b/packages/desktop/package.json
index 788716cef7..7e3b01dfaa 100644
--- a/packages/desktop/package.json
+++ b/packages/desktop/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/desktop",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "private": true,
   "description": "Paseo desktop app (Electron wrapper)",
   "homepage": "https://paseo.sh",
diff --git a/packages/expo-two-way-audio/package.json b/packages/expo-two-way-audio/package.json
index df44ab2a92..b9c1190375 100644
--- a/packages/expo-two-way-audio/package.json
+++ b/packages/expo-two-way-audio/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/expo-two-way-audio",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "description": "Native module for two way audio streaming",
   "keywords": [
     "ExpoTwoWayAudio",
diff --git a/packages/highlight/package.json b/packages/highlight/package.json
index 5f40283e3c..85d9c90471 100644
--- a/packages/highlight/package.json
+++ b/packages/highlight/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/highlight",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "license": "Apache-2.0",
   "files": [
     "dist",
diff --git a/packages/plugin/package.json b/packages/plugin/package.json
index 262d57381e..ef537c35e3 100644
--- a/packages/plugin/package.json
+++ b/packages/plugin/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/plugin",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "description": "Paseo plugin SDK package",
   "license": "Apache-2.0",
   "files": [
@@ -78,8 +78,8 @@
     "use-sync-external-store": "^1.6.0"
   },
   "devDependencies": {
-    "@getpaseo/client": "0.15.1",
-    "@getpaseo/protocol": "0.15.1",
+    "@getpaseo/client": "0.15.2",
+    "@getpaseo/protocol": "0.15.2",
     "@types/node": "^20.9.0",
     "@types/react": "~19.2.0",
     "react": "19.2.3",
@@ -89,8 +89,8 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@getpaseo/client": "0.15.1",
-    "@getpaseo/protocol": "0.15.1",
+    "@getpaseo/client": "0.15.2",
+    "@getpaseo/protocol": "0.15.2",
     "react": ">=19.1.0 <20",
     "react-native": ">=0.81.5",
     "zod": "^4.4.3"
diff --git a/packages/protocol/package.json b/packages/protocol/package.json
index d802f6afe3..4667c9abe1 100644
--- a/packages/protocol/package.json
+++ b/packages/protocol/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/protocol",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "description": "Paseo shared protocol schemas and wire types",
   "license": "Apache-2.0",
   "files": [
diff --git a/packages/relay/package.json b/packages/relay/package.json
index d4f7af0c0c..6f17d20847 100644
--- a/packages/relay/package.json
+++ b/packages/relay/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/relay",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "description": "Paseo relay for bridging daemon and client connections",
   "license": "Apache-2.0",
   "files": [
diff --git a/packages/server/package.json b/packages/server/package.json
index 2c9615da7a..471e558b77 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/server",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "description": "Paseo backend server",
   "license": "Apache-2.0",
   "files": [
@@ -108,11 +108,11 @@
     "@agentclientprotocol/sdk": "^0.17.1",
     "@anthropic-ai/claude-agent-sdk": "0.3.246",
     "@anthropic-ai/sdk": "^0.104.2",
-    "@getpaseo/client": "0.15.1",
-    "@getpaseo/highlight": "0.15.1",
-    "@getpaseo/plugin": "0.15.1",
-    "@getpaseo/protocol": "0.15.1",
-    "@getpaseo/relay": "0.15.1",
+    "@getpaseo/client": "0.15.2",
+    "@getpaseo/highlight": "0.15.2",
+    "@getpaseo/plugin": "0.15.2",
+    "@getpaseo/protocol": "0.15.2",
+    "@getpaseo/relay": "0.15.2",
     "@isaacs/ttlcache": "^2.1.4",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@opencode-ai/sdk": "1.14.46",
diff --git a/packages/website/package.json b/packages/website/package.json
index 3d9aa70ff8..696ebb8a51 100644
--- a/packages/website/package.json
+++ b/packages/website/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/website",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "private": true,
   "type": "module",
   "scripts": {
diff --git a/plugins/package.json b/plugins/package.json
index 829209bd2a..1e56036650 100644
--- a/plugins/package.json
+++ b/plugins/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/builtin-plugins",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "private": true,
   "type": "module",
   "scripts": {

From cdd7800fed3d87757952a368467e703ac4d15873 Mon Sep 17 00:00:00 2001
From: "paseo-bot[bot]" <266920839+paseo-bot[bot]@users.noreply.github.com>
Date: Thu, 5 Nov 2026 09:46:14 +0000
Subject: [PATCH 19/29] test(app): wait for workspace hover cards to settle
 (#8846)

Keyboard focus can briefly mount the next card while the previous card closes. Poll uniqueness and visibility together so the assertion tolerates that transition but still rejects persistent duplicates.

Co-authored-by: paseo-bot[bot] <266920839+paseo-bot[bot]@users.noreply.github.com>
---
 packages/app/e2e/support/helpers/sidebar.ts | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/packages/app/e2e/support/helpers/sidebar.ts b/packages/app/e2e/support/helpers/sidebar.ts
index 9fd61a8451..6e0a4abedc 100644
--- a/packages/app/e2e/support/helpers/sidebar.ts
+++ b/packages/app/e2e/support/helpers/sidebar.ts
@@ -81,7 +81,13 @@ export async function scrollWorkspaceList(page: Page): Promise<void> {
 }
 
 export async function expectWorkspaceHoverCardOpen(page: Page): Promise<void> {
-  await expect(page.getByTestId("workspace-hover-card")).toBeVisible();
+  const cards = page.getByTestId("workspace-hover-card");
+  // Keyboard navigation can leave the previous card closing while the next opens.
+  // Retry both checks together: another card may mount between count and visibility.
+  await expect(async () => {
+    expect(await cards.count()).toBe(1);
+    expect(await cards.isVisible()).toBe(true);
+  }).toPass({ timeout: 10_000 });
 }
 
 export async function expectWorkspaceHoverCardStaysOpen(page: Page): Promise<void> {

From 59be8975a463e92ead1fc5ea4c120b10de089eec Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Thu, 5 Nov 2026 18:49:12 +0700
Subject: [PATCH 20/29] Dismiss a failed agent's red dot by reading it (#8831)

* fix(sidebar): clear the failed status once the error is read

Reading an errored agent already cleared its error attention, but the
state bucket also mapped lifecycle status "error" to failed. Lifecycle
only leaves "error" when the next turn starts, so the red dot and the
Failed group stuck until the agent was prompted again. The failed bucket
now follows unread error attention, the same way the green dot follows
unread finished attention; lifecycle status stays "error".

Because failed now depends on attention, a failure must replace unread
finished attention, otherwise a reload that fails on an unread agent
would show green.

* fix(sidebar): keep failed subagents red and let read failures be marked unread

The failed bucket now follows unread error attention, which broke three
places that relied on lifecycle "error" alone:

- Subagent track rows and provider-subagent tabs have no read state of
  their own, so failed children lost their red mark. They now map the
  child's lifecycle directly.
- A read errored workspace became "done" and offered Mark as unread, but
  the daemon only accepted idle or closed agents. Marking it unread now
  restores error attention.
- A reload that failed again while the lifecycle was already "error"
  raised no new attention. A failed reload now raises error attention
  directly instead of relying on a lifecycle transition.
---
 docs/agent-lifecycle.md                       | 13 ++-
 .../src/panels/provider-subagent-panel.tsx    |  7 +-
 packages/app/src/subagents/index.ts           |  1 +
 .../app/src/subagents/track-presentation.ts   | 18 +++-
 .../utils/workspace-agent-activity.test.ts    |  2 +
 .../protocol/src/agent-state-bucket.test.ts   | 35 ++++++-
 packages/protocol/src/agent-state-bucket.ts   | 10 +-
 .../src/server/agent/agent-manager.test.ts    | 93 +++++++++++++++++++
 .../server/src/server/agent/agent-manager.ts  | 55 +++++++----
 packages/server/src/server/session.ts         |  7 +-
 .../src/server/session.workspaces.test.ts     | 50 +++++++++-
 .../src/server/workspace-directory.test.ts    | 15 +++
 12 files changed, 267 insertions(+), 39 deletions(-)

diff --git a/docs/agent-lifecycle.md b/docs/agent-lifecycle.md
index d8ee067c6c..1d0b29b018 100644
--- a/docs/agent-lifecycle.md
+++ b/docs/agent-lifecycle.md
@@ -305,9 +305,9 @@ Workspace status is an aggregate activity signal computed **per `workspaceId`**.
 
 Running provider-native subagents contribute `running` to the workspace owned by their parent agent. Their completed, failed, and canceled states stay in the parent's subagents track.
 
-A finished workspace can be marked unread after it has been reviewed. The daemon restores
-`finished` attention on its newest eligible workspace-root agent without sending a new completion
-notification. Opening the workspace clears that attention through the normal focus flow.
+A finished or failed workspace can be marked unread after it has been reviewed. The daemon restores
+attention on its newest eligible workspace-root agent, `error` for an agent whose lifecycle is
+`error` and `finished` otherwise, without sending a new notification. Opening the workspace clears that attention through the normal focus flow.
 
 Attention is set by the agent finishing or failing and cleared by the client's
 `workspace.clear_attention`, which fires when the user reads the chat. Loading an agent's runtime is
@@ -316,6 +316,13 @@ untouched. Forging either makes a background resume look like the user read a wo
 agent worked in it just now, which rewrites the sidebar timestamp permanently — persisted
 `updatedAt` is what workspace `statusEnteredAt` is re-derived from on the next daemon start.
 
+The `failed` bucket follows unread `error` attention, not lifecycle status. An agent stays `error`
+until its next turn starts, so reading the chat dismisses the red dot the same way it dismisses the
+green one. For the same reason every new failure raises `error` attention, including a failed reload
+that leaves the lifecycle at `error`, and replaces unread `finished` attention; otherwise the failed
+agent would show the green dot or none. Subagents track marks are the exception: they follow the
+child's lifecycle, because the track is where a failed child stays visible.
+
 ## The subagents track
 
 The track is a pill at the foot of an agent's pane (`packages/app/src/subagents/track.tsx`): a count you can read at a glance, and a panel behind it — a popover on wide screens, a sheet on compact ones — holding the rows. It floats over the transcript rather than sitting in a band above the composer, so the timeline scrolls underneath it; `packages/app/src/panels/agent-tracks.tsx` owns that placement, and the pill frame is shared with the task list in `packages/app/src/composer/tracks.tsx`.
diff --git a/packages/app/src/panels/provider-subagent-panel.tsx b/packages/app/src/panels/provider-subagent-panel.tsx
index 99a38c2f8b..377d5331c8 100644
--- a/packages/app/src/panels/provider-subagent-panel.tsx
+++ b/packages/app/src/panels/provider-subagent-panel.tsx
@@ -31,7 +31,7 @@ import {
 import { useTranslation } from "react-i18next";
 import type { PendingPermission } from "@/types/shared";
 import type { StreamItem } from "@/types/stream";
-import { deriveSidebarStateBucket } from "@/utils/sidebar-agent-state";
+import { deriveSubagentStatusBucket } from "@/subagents";
 import { TIMELINE_FETCH_PAGE_SIZE } from "@/timeline/timeline-fetch-policy";
 import type { TurnPresentation } from "@/timeline/turn-liveness";
 import { buildWorkspaceTabPersistenceKey } from "@/workspace-tabs/model";
@@ -107,10 +107,7 @@ function useProviderSubagentDescriptor(
     titleState: descriptor ? "ready" : "loading",
     icon: useProviderIcon(provider, context.serverId),
     statusBucket: descriptor
-      ? deriveSidebarStateBucket({
-          status: providerSubagentLifecycleStatus(descriptor.status),
-          requiresAttention: descriptor.status === "failed",
-        })
+      ? deriveSubagentStatusBucket(providerSubagentLifecycleStatus(descriptor.status))
       : null,
   };
 }
diff --git a/packages/app/src/subagents/index.ts b/packages/app/src/subagents/index.ts
index 0b72ccfcf5..cd8ee753fb 100644
--- a/packages/app/src/subagents/index.ts
+++ b/packages/app/src/subagents/index.ts
@@ -10,3 +10,4 @@ export {
   type UseArchiveFinishedSubagentsInput,
 } from "./use-archive-finished";
 export { useSubagentSheetTab } from "./sheet-tab";
+export { deriveSubagentStatusBucket } from "./track-presentation";
diff --git a/packages/app/src/subagents/track-presentation.ts b/packages/app/src/subagents/track-presentation.ts
index d95082ca39..5a1d671339 100644
--- a/packages/app/src/subagents/track-presentation.ts
+++ b/packages/app/src/subagents/track-presentation.ts
@@ -1,7 +1,8 @@
 import type { TFunction } from "i18next";
 import type { ComposerTrackPillSegment } from "@/composer/tracks";
 import type { SidebarStateBucket } from "@/utils/sidebar-agent-state";
-import { deriveSidebarStateBucket, STATUS_BUCKET_ORDER } from "@/utils/sidebar-agent-state";
+import type { AgentLifecycleStatus } from "@getpaseo/protocol/agent-lifecycle";
+import { STATUS_BUCKET_ORDER } from "@/utils/sidebar-agent-state";
 import type { SubagentRow } from "./select";
 import { isFinishedSubagent } from "./archive-finished";
 import { providerSubagentLifecycleStatus } from "./provider-store";
@@ -14,6 +15,16 @@ function presentationStatus(row: SubagentRow) {
   return providerSubagentLifecycleStatus(row.status);
 }
 
+/**
+ * A child's mark reports what it is doing, not whether anyone read it: the track is where a
+ * failed child stays visible after the parent's own attention is cleared.
+ */
+export function deriveSubagentStatusBucket(status: AgentLifecycleStatus): SidebarStateBucket {
+  if (status === "error") return "failed";
+  if (status === "running") return "running";
+  return "done";
+}
+
 export interface SubagentRowPresentationData {
   key: string;
   kind: "agent";
@@ -38,10 +49,7 @@ export function buildSubagentRowPresentationData(row: SubagentRow): SubagentRowP
     label: label ?? "",
     subtitle: subtitle ?? "",
     titleState: label ? "ready" : "loading",
-    statusBucket: deriveSidebarStateBucket({
-      status,
-      requiresAttention: false,
-    }),
+    statusBucket: deriveSubagentStatusBucket(status),
   };
 }
 
diff --git a/packages/app/src/utils/workspace-agent-activity.test.ts b/packages/app/src/utils/workspace-agent-activity.test.ts
index 66cfcd758c..a539a3881a 100644
--- a/packages/app/src/utils/workspace-agent-activity.test.ts
+++ b/packages/app/src/utils/workspace-agent-activity.test.ts
@@ -93,6 +93,8 @@ describe("workspace agent activity index", () => {
             workspaceId: "workspace-error",
             status: "error",
             turn: { phase: "idle", cancellationRequestId: null },
+            requiresAttention: true,
+            attentionReason: "error",
             updatedAt: "2026-01-01T00:00:00.000Z",
           }),
         ],
diff --git a/packages/protocol/src/agent-state-bucket.test.ts b/packages/protocol/src/agent-state-bucket.test.ts
index 3c5d281b39..89d1ef93ab 100644
--- a/packages/protocol/src/agent-state-bucket.test.ts
+++ b/packages/protocol/src/agent-state-bucket.test.ts
@@ -39,6 +39,28 @@ describe("deriveAgentStateBucket", () => {
     ).toBe("failed");
   });
 
+  it("treats an errored agent whose error was read as done", () => {
+    expect(
+      deriveAgentStateBucket({
+        status: "error",
+        pendingPermissionCount: 0,
+        requiresAttention: false,
+        attentionReason: null,
+      }),
+    ).toBe("done");
+  });
+
+  it("treats an errored agent with unread error attention as failed", () => {
+    expect(
+      deriveAgentStateBucket({
+        status: "error",
+        pendingPermissionCount: 0,
+        requiresAttention: true,
+        attentionReason: "error",
+      }),
+    ).toBe("failed");
+  });
+
   it("treats unread finished agents as attention", () => {
     expect(
       deriveAgentStateBucket({
@@ -83,10 +105,21 @@ describe("getAgentStatusPriority", () => {
   it("prioritizes pending permissions before errors and running agents", () => {
     const permission = getAgentStatusPriority({ status: "running", pendingPermissionCount: 1 });
     expect(permission).toBeLessThan(
-      getAgentStatusPriority({ status: "error", pendingPermissionCount: 0 }),
+      getAgentStatusPriority({
+        status: "error",
+        pendingPermissionCount: 0,
+        requiresAttention: true,
+        attentionReason: "error",
+      }),
     );
     expect(permission).toBeLessThan(
       getAgentStatusPriority({ status: "running", pendingPermissionCount: 0 }),
     );
   });
+
+  it("ranks an errored agent with a read error alongside completed agents", () => {
+    expect(getAgentStatusPriority({ status: "error", requiresAttention: false })).toBe(
+      getAgentStatusPriority({ status: "idle" }),
+    );
+  });
 });
diff --git a/packages/protocol/src/agent-state-bucket.ts b/packages/protocol/src/agent-state-bucket.ts
index 2973152f1d..746d70a4e2 100644
--- a/packages/protocol/src/agent-state-bucket.ts
+++ b/packages/protocol/src/agent-state-bucket.ts
@@ -19,11 +19,17 @@ const WORKSPACE_STATE_BUCKET_PRIORITY = {
   done: 4,
 } as const satisfies Record<WorkspaceStateBucket, number>;
 
+// An error is a notification like a finish: once the user has seen it, the agent stops showing as
+// failed even though its lifecycle stays "error" until the next turn starts.
+function hasUnreadError(input: AgentStateBucketInput): boolean {
+  return input.requiresAttention === true && input.attentionReason === "error";
+}
+
 export function deriveAgentStateBucket(input: AgentStateBucketInput): WorkspaceStateBucket {
   if ((input.pendingPermissionCount ?? 0) > 0 || input.attentionReason === "permission") {
     return "needs_input";
   }
-  if (input.status === "error" || input.attentionReason === "error") {
+  if (hasUnreadError(input)) {
     return "failed";
   }
   if (input.status === "running") {
@@ -43,7 +49,7 @@ export function getAgentStatusPriority(input: AgentStateBucketInput): number {
   if ((input.pendingPermissionCount ?? 0) > 0 || input.attentionReason === "permission") {
     return 0;
   }
-  if (input.status === "error" || input.attentionReason === "error") {
+  if (hasUnreadError(input)) {
     return 1;
   }
   if (input.status === "running") {
diff --git a/packages/server/src/server/agent/agent-manager.test.ts b/packages/server/src/server/agent/agent-manager.test.ts
index 57e5b0df20..6c7396d657 100644
--- a/packages/server/src/server/agent/agent-manager.test.ts
+++ b/packages/server/src/server/agent/agent-manager.test.ts
@@ -2801,6 +2801,53 @@ test("closing during reload leaves the replacement closed", async () => {
   }
 });
 
+test("every failed reload raises error attention, replacing unread finished attention", async () => {
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-reload-error-attention-"));
+  const storage = new AgentStorage(join(workdir, "agents"), logger);
+  const client = new HeldReloadCloseClient();
+  const attentionReasons: Array<"finished" | "error" | "permission"> = [];
+  const manager = new AgentManager({
+    clients: { codex: client },
+    registry: storage,
+    logger,
+    rescueTimeouts: { reloadSessionCloseMs: 10 },
+    onAgentAttention: ({ reason }) => attentionReasons.push(reason),
+  });
+  try {
+    const created = await manager.createAgent({ provider: "codex", cwd: workdir }, undefined, {
+      workspaceId: undefined,
+    });
+    await manager.markAgentUnread(created.id);
+    expect(manager.getAgent(created.id)?.attention).toMatchObject({
+      attentionReason: "finished",
+    });
+
+    await expect(manager.reloadAgentSession(created.id)).rejects.toThrow("Timed out closing");
+
+    expect(manager.getAgent(created.id)?.lifecycle).toBe("error");
+    expect(manager.getAgent(created.id)?.attention).toMatchObject({
+      requiresAttention: true,
+      attentionReason: "error",
+    });
+    expect(attentionReasons).toEqual(["error"]);
+
+    await manager.clearAgentAttention(created.id);
+    await expect(manager.reloadAgentSession(created.id)).rejects.toThrow("Timed out closing");
+    expect(manager.getAgent(created.id)?.attention).toMatchObject({
+      requiresAttention: true,
+      attentionReason: "error",
+    });
+    expect(attentionReasons).toEqual(["error", "error"]);
+
+    client.finishClosing();
+    await manager.closeAgent(created.id);
+  } finally {
+    client.finishClosing();
+    await storage.flush();
+    rmSync(workdir, { recursive: true, force: true });
+  }
+});
+
 test("retrying a timed-out reload waits for the original close to finish", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-reload-late-close-"));
   const storage = new AgentStorage(join(workdir, "agents"), logger);
@@ -5807,6 +5854,52 @@ test("archiveSnapshot dispatches archived state for stored-only agents", async (
   expect(last.lifecycle).toBe("closed");
 });
 
+test("markAgentUnread restores error attention on a read errored agent", async () => {
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-mark-unread-error-"));
+  const storage = new AgentStorage(join(workdir, "agents"), logger);
+  class ErrorClient extends TestAgentClient {
+    readonly session = new TestAgentSession({ provider: "codex", cwd: workdir });
+
+    override async createSession(): Promise<AgentSession> {
+      return this.session;
+    }
+  }
+  const client = new ErrorClient();
+  const manager = new AgentManager({ clients: { codex: client }, registry: storage, logger });
+  onTestFinished(async () => {
+    await manager.closeAgent(agent.id);
+    await manager.flush();
+    rmSync(workdir, { recursive: true, force: true });
+  });
+  const agent = await manager.createAgent({ provider: "codex", cwd: workdir }, undefined, {
+    workspaceId: undefined,
+  });
+  const running = waitForAgentLifecycle(manager, agent.id, "running");
+  client.session.pushEvent({ type: "turn_started", provider: "codex", turnId: "failed-turn" });
+  await running;
+  const failed = waitForAgentLifecycle(manager, agent.id, "error");
+  client.session.pushEvent({
+    type: "turn_failed",
+    provider: "codex",
+    turnId: "failed-turn",
+    error: "Selected model is at capacity.",
+  });
+  await failed;
+  await manager.clearAgentAttention(agent.id);
+
+  await manager.markAgentUnread(agent.id);
+
+  expect(manager.getAgent(agent.id)?.attention).toMatchObject({
+    requiresAttention: true,
+    attentionReason: "error",
+  });
+  expect(await storage.get(agent.id)).toMatchObject({
+    lastStatus: "error",
+    requiresAttention: true,
+    attentionReason: "error",
+  });
+});
+
 test("markAgentUnread dispatches stored attention to every subscriber", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-mark-unread-dispatch-"));
   const storage = new AgentStorage(join(workdir, "agents"), logger);
diff --git a/packages/server/src/server/agent/agent-manager.ts b/packages/server/src/server/agent/agent-manager.ts
index 387d76082d..fea3eed438 100644
--- a/packages/server/src/server/agent/agent-manager.ts
+++ b/packages/server/src/server/agent/agent-manager.ts
@@ -411,6 +411,13 @@ function raisesAttention(agent: Pick<ManagedAgent, "internal" | "background">):
   return !agent.internal && !agent.background;
 }
 
+/** The attention a read agent gets back when marked unread; null while it is still working. */
+function unreadAttentionReason(status: AgentLifecycleStatus): "finished" | "error" | null {
+  if (status === "idle" || status === "closed") return "finished";
+  if (status === "error") return "error";
+  return null;
+}
+
 function resolveInitialAttention(input: AttentionState | undefined): AttentionState {
   if (input == null || !input.requiresAttention) {
     return { requiresAttention: false };
@@ -1776,6 +1783,7 @@ export class AgentManager {
       } else if (this.agents.get(agentId) === existing) {
         existing.lifecycle = "error";
         existing.lastError = error instanceof Error ? error.message : String(error);
+        this.raiseErrorAttention(existing);
         this.emitState(existing);
       }
       throw error;
@@ -2433,16 +2441,16 @@ export class AgentManager {
   async markAgentUnread(agentId: string): Promise<void> {
     const liveAgent = this.agents.get(agentId);
     if (liveAgent) {
-      const isFinished = liveAgent.lifecycle === "idle";
+      const attentionReason = unreadAttentionReason(liveAgent.lifecycle);
       const hasPendingPermissions = liveAgent.pendingPermissions.size > 0;
       const canMarkUnread =
-        isFinished && !liveAgent.attention.requiresAttention && !hasPendingPermissions;
+        attentionReason && !liveAgent.attention.requiresAttention && !hasPendingPermissions;
       if (!canMarkUnread) {
-        throw new Error(`Agent is no longer finished and read: ${agentId}`);
+        throw new Error(`Agent is no longer settled and read: ${agentId}`);
       }
       liveAgent.attention = {
         requiresAttention: true,
-        attentionReason: "finished",
+        attentionReason,
         attentionTimestamp: new Date(),
       };
       await this.persistSnapshot(liveAgent);
@@ -2452,18 +2460,18 @@ export class AgentManager {
 
     const registry = this.requireRegistry();
     const record = await registry.get(agentId);
-    const hasFinishedStatus = record?.lastStatus === "idle" || record?.lastStatus === "closed";
+    const attentionReason = record?.lastStatus ? unreadAttentionReason(record.lastStatus) : null;
     const canMarkUnread =
       record && !record.internal && !record.archivedAt && !record.requiresAttention;
-    if (!canMarkUnread || !hasFinishedStatus) {
-      throw new Error(`Agent is no longer finished and read: ${agentId}`);
+    if (!canMarkUnread || !attentionReason) {
+      throw new Error(`Agent is no longer settled and read: ${agentId}`);
     }
     const updatedAt = this.nextStoredUpdatedAt(record);
     const nextRecord: StoredAgentRecord = {
       ...record,
       updatedAt,
       requiresAttention: true,
-      attentionReason: "finished",
+      attentionReason,
       attentionTimestamp: updatedAt,
     };
     await registry.upsert(nextRecord);
@@ -5300,12 +5308,15 @@ export class AgentManager {
       return;
     }
 
-    // Skip if already requires attention
+    if (previousStatus !== "error" && currentStatus === "error") {
+      this.raiseErrorAttention(agent);
+      return;
+    }
+
     if (agent.attention.requiresAttention) {
       return;
     }
 
-    // Check if agent transitioned from running to idle (finished)
     if (previousStatus === "running" && currentStatus === "idle") {
       agent.attention = {
         requiresAttention: true,
@@ -5313,19 +5324,25 @@ export class AgentManager {
         attentionTimestamp: new Date(),
       };
       this.broadcastAgentAttention(agent, "finished");
-      return;
     }
+  }
 
-    // Check if agent entered error state
-    if (previousStatus !== "error" && currentStatus === "error") {
-      agent.attention = {
-        requiresAttention: true,
-        attentionReason: "error",
-        attentionTimestamp: new Date(),
-      };
-      this.broadcastAgentAttention(agent, "error");
+  // The failed state is only shown while error attention is unread, so every new failure raises
+  // it, including one that keeps the lifecycle at "error". An error outranks an unread finish,
+  // which would otherwise make the failure look green.
+  private raiseErrorAttention(agent: ManagedAgent): void {
+    if (!raisesAttention(agent)) {
       return;
     }
+    if (agent.attention.requiresAttention && agent.attention.attentionReason !== "finished") {
+      return;
+    }
+    agent.attention = {
+      requiresAttention: true,
+      attentionReason: "error",
+      attentionTimestamp: new Date(),
+    };
+    this.broadcastAgentAttention(agent, "error");
   }
 
   private enqueueBackgroundPersist(agent: ManagedAgent): void {
diff --git a/packages/server/src/server/session.ts b/packages/server/src/server/session.ts
index 4b260f8550..9ce3fbbcb4 100644
--- a/packages/server/src/server/session.ts
+++ b/packages/server/src/server/session.ts
@@ -7955,7 +7955,10 @@ export class Session {
         .filter((agent) => !agent.archivedAt && !agent.background)
         .filter((agent) => agent.workspaceId === workspace.workspaceId)
         .filter((agent) => resolveWorkspaceRootAgent(agent, agentsById)?.id === agent.id)
-        .filter((agent) => agent.status === "idle" || agent.status === "closed")
+        .filter(
+          (agent) =>
+            agent.status === "idle" || agent.status === "closed" || agent.status === "error",
+        )
         .filter((agent) => agent.requiresAttention !== true)
         .filter((agent) => (agent.pendingPermissions?.length ?? 0) === 0)
         .sort(
@@ -7964,7 +7967,7 @@ export class Session {
         );
       const candidate = candidates[0];
       if (!candidate) {
-        throw new Error(`Workspace has no finished agent to mark unread: ${workspaceId}`);
+        throw new Error(`Workspace has no read agent to mark unread: ${workspaceId}`);
       }
 
       await this.agentManager.markAgentUnread(candidate.id);
diff --git a/packages/server/src/server/session.workspaces.test.ts b/packages/server/src/server/session.workspaces.test.ts
index 6b1db34449..928131ab3a 100644
--- a/packages/server/src/server/session.workspaces.test.ts
+++ b/packages/server/src/server/session.workspaces.test.ts
@@ -2123,7 +2123,53 @@ test("workspace mark unread selects a finished cross-workspace child with scoped
   }
 });
 
-test("workspace mark unread rejects workspaces without a finished root agent", async () => {
+test("workspace mark unread marks a read errored root agent", async () => {
+  const emitted: SessionOutboundMessage[] = [];
+  const workspace = createPersistedWorkspaceRecord({
+    workspaceId: REPO_CWD,
+    projectId: REPO_CWD,
+    cwd: REPO_CWD,
+    kind: "directory",
+    displayName: "repo",
+    createdAt: "2026-03-30T15:00:00.000Z",
+    updatedAt: "2026-03-30T15:00:00.000Z",
+  });
+  const markedAgentIds: string[] = [];
+  const session = createSessionForWorkspaceTests({
+    onMessage: (message) => emitted.push(message),
+    agentManager: {
+      markAgentUnread: async (agentId: string) => {
+        markedAgentIds.push(agentId);
+      },
+    },
+  });
+  session.workspaceRegistry.get = async (id: string) =>
+    id === workspace.workspaceId ? workspace : null;
+  session.listAgentPayloads = async () => [
+    makeAgent({
+      id: "errored-agent",
+      cwd: REPO_CWD,
+      workspaceId: workspace.workspaceId,
+      status: "error",
+      updatedAt: "2026-03-30T16:00:00.000Z",
+      requiresAttention: false,
+    }),
+  ];
+
+  await session.handleMessage({
+    type: "workspace.mark_unread.request",
+    workspaceId: workspace.workspaceId,
+    requestId: "req-mark-unread",
+  });
+
+  expect(markedAgentIds).toEqual(["errored-agent"]);
+  expect(findByType(emitted, "workspace.mark_unread.response").payload).toMatchObject({
+    markedAgentId: "errored-agent",
+    success: true,
+  });
+});
+
+test("workspace mark unread rejects workspaces without a read root agent", async () => {
   const emitted: SessionOutboundMessage[] = [];
   const workspace = createPersistedWorkspaceRecord({
     workspaceId: REPO_CWD,
@@ -2150,7 +2196,7 @@ test("workspace mark unread rejects workspaces without a finished root agent", a
     workspaceId: workspace.workspaceId,
     markedAgentId: null,
     success: false,
-    error: `Workspace has no finished agent to mark unread: ${workspace.workspaceId}`,
+    error: `Workspace has no read agent to mark unread: ${workspace.workspaceId}`,
   });
 });
 
diff --git a/packages/server/src/server/workspace-directory.test.ts b/packages/server/src/server/workspace-directory.test.ts
index ab2ead15aa..85e8aeb600 100644
--- a/packages/server/src/server/workspace-directory.test.ts
+++ b/packages/server/src/server/workspace-directory.test.ts
@@ -343,6 +343,21 @@ describe("WorkspaceDirectory", () => {
     await expect(workspace.workspaceStatus()).resolves.toBe("running");
   });
 
+  test("an errored root agent shows failed only until its error is read", async () => {
+    const unread = new WorkspaceStatus();
+    unread.hasRootAgent({
+      id: "root-agent",
+      status: "error",
+      requiresAttention: true,
+      attentionReason: "error",
+    });
+    await expect(unread.workspaceStatus()).resolves.toBe("failed");
+
+    const read = new WorkspaceStatus();
+    read.hasRootAgent({ id: "root-agent", status: "error", requiresAttention: false });
+    await expect(read.workspaceStatus()).resolves.toBe("done");
+  });
+
   test("a running background agent does not make its workspace running", async () => {
     const workspace = new WorkspaceStatus();
 

From e6064bb374ccddb63bea7d6aac15c9cad3d985ee Mon Sep 17 00:00:00 2001
From: "paseo-ai[bot]" <266920839+paseo-ai[bot]@users.noreply.github.com>
Date: Thu, 5 Nov 2026 11:58:31 +0000
Subject: [PATCH 21/29] fix: update lockfile signatures and Nix hash [skip ci]

---
 nix/npm-deps.hash | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/nix/npm-deps.hash b/nix/npm-deps.hash
index acc5703b71..a6968c10fe 100644
--- a/nix/npm-deps.hash
+++ b/nix/npm-deps.hash
@@ -1 +1 @@
-sha256-6FUGQhWie9533i6FoOSCdtEWUXHmwei61W0cT6GK66k=
+sha256-wO0vJVhh1urkt4q9NiQ0RSXUj++WWuHTneWSPelU+JQ=

From 412550c36fd5e3625c8050aeb4856837d06c4e09 Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Thu, 5 Nov 2026 20:57:13 +0700
Subject: [PATCH 22/29] Keep active transfers connected when the app returns to
 foreground (#8651)

* fix(client): keep active transfers alive during foreground checks

Foreground used an independent three-second probe that closed live connections while a pong waited behind bulk data. Share the heartbeat clock and refresh its outstanding deadline on validated inbound frames, including incomplete chunk assemblies.

* test(client): deliver bulk response before the queued pong

* fix(client): preserve latency deadlines when sharing heartbeat pings

* fix(client): keep heartbeat cadence during active downloads
---
 packages/client/src/daemon-client.test.ts  | 158 ++++++++++++++++++++-
 packages/client/src/daemon-client.ts       |  82 +++++------
 packages/protocol/src/chunked-transport.ts |   2 +
 3 files changed, 199 insertions(+), 43 deletions(-)

diff --git a/packages/client/src/daemon-client.test.ts b/packages/client/src/daemon-client.test.ts
index eb0dcdb6ca..87719a0a56 100644
--- a/packages/client/src/daemon-client.test.ts
+++ b/packages/client/src/daemon-client.test.ts
@@ -657,6 +657,38 @@ class FakeDaemon {
     },
   };
 
+  finishTransfer(): void {
+    // Four MiB of JSON whitespace precedes this valid application message.
+    const bytes = new TextEncoder().encode(
+      JSON.stringify({
+        type: "session",
+        message: {
+          type: "status",
+          payload: {
+            status: "server_info",
+            serverId: "srv_heartbeat_test",
+            hostname: null,
+            version: null,
+            features: { binaryChunkingV1: true },
+          },
+        },
+      }),
+    );
+    const frame = new Uint8Array(bytes.length + 4);
+    frame.set([0x31, 1, 0, 2]);
+    frame.set(bytes, 4);
+    this.onMessage(frame);
+    this.onMessage(JSON.stringify({ type: "pong" }));
+    this.daemonAnswersPingsAfter("fast");
+  }
+
+  receiveChunk(start: boolean): void {
+    const frame = new Uint8Array(1024 * 1024 + 4);
+    frame.set([0x31, 1, 0, start ? 1 : 0]);
+    frame.fill(32, 4);
+    this.onMessage(frame);
+  }
+
   openConnection(): void {
     this.onOpen();
     this.onMessage(
@@ -667,6 +699,7 @@ class FakeDaemon {
           payload: {
             status: "server_info",
             serverId: "srv_heartbeat_test",
+            features: { binaryChunkingV1: true },
             hostname: null,
             version: null,
           },
@@ -2572,7 +2605,7 @@ test("keeps default connect timeout shorter than session RPC waiters", async ()
   }
 });
 
-test("foreground verification replaces a silently broken socket without waiting for heartbeats", async () => {
+test("foreground checks a silently broken socket through two normal heartbeat misses", async () => {
   useHeartbeatClock();
   const first = new FakeDaemon();
   const second = new FakeDaemon();
@@ -2590,7 +2623,11 @@ test("foreground verification replaces a silently broken socket without waiting
   await connection;
 
   client.ensureConnected({ verify: true });
-  await vi.advanceTimersByTimeAsync(3_000);
+  await vi.advanceTimersByTimeAsync(15_000);
+  expect(first.closesFromClient()).toEqual([]);
+  await vi.advanceTimersByTimeAsync(25_000);
+  expect(first.closesFromClient()).toEqual([{ code: 1001, reason: "Liveness check timed out" }]);
+  client.ensureConnected();
   expect(attempts).toBe(2);
   second.openConnection();
   expect(client.getConnectionState()).toEqual({ status: "connected" });
@@ -2618,7 +2655,110 @@ test("foreground verification preserves a healthy socket and deduplicates simult
   expect(daemon.closesFromClient()).toEqual([]);
 });
 
-test("an obsolete foreground probe cannot close a replacement connection", async () => {
+test("chunks prevent heartbeat misses until silence causes two misses", async () => {
+  useHeartbeatClock();
+  const daemon = new FakeDaemon();
+  daemon.daemonGoesSilent();
+  const client = new DaemonClient({
+    url: "ws://test",
+    clientId: "bulk-resume",
+    logger: noopLogger,
+    reconnect: { enabled: false },
+    transportFactory: () => daemon.transport,
+  });
+  clients.push(client);
+  const connection = client.connect();
+  daemon.openConnection();
+  await connection;
+  client.ensureConnected({ verify: true });
+  let measurementError: unknown;
+  void client.measureLatency({ timeoutMs: 5_000 }).catch((error: unknown) => {
+    measurementError = error;
+  });
+  await vi.advanceTimersByTimeAsync(5_000);
+  expect(measurementError).toEqual(
+    expect.objectContaining({
+      message: "Latency measurement timed out (5000ms)",
+    }),
+  );
+  for (let index = 0; index < 4; index++) {
+    await vi.advanceTimersByTimeAsync(index === 0 ? 5_000 : 10_000);
+    daemon.receiveChunk(index === 0);
+    expect(daemon.closesFromClient()).toEqual([]);
+  }
+  // No complete message or pong has arrived, but progress prevents misses.
+  expect(daemon.pingTimestamps()).toEqual(["0s", "25s"]);
+  await vi.advanceTimersByTimeAsync(25_000);
+  expect(daemon.closesFromClient()).toEqual([]);
+  await vi.advanceTimersByTimeAsync(25_000);
+  expect(daemon.closesFromClient()).toEqual([{ code: 1001, reason: "Liveness check timed out" }]);
+});
+
+test("foreground preserves a multi-MB transfer with its pong queued behind chunks", async () => {
+  useHeartbeatClock();
+  const daemon = new FakeDaemon();
+  daemon.daemonGoesSilent();
+  const client = new DaemonClient({
+    url: "ws://test",
+    clientId: "bulk-resume",
+    logger: noopLogger,
+    reconnect: { enabled: false },
+    transportFactory: () => daemon.transport,
+  });
+  clients.push(client);
+  const connection = client.connect();
+  daemon.openConnection();
+  await connection;
+  client.ensureConnected({ verify: true });
+  await vi.advanceTimersByTimeAsync(3_001);
+  expect(daemon.closesFromClient()).toEqual([]);
+  for (let index = 0; index < 4; index++) {
+    await vi.advanceTimersByTimeAsync(10_000);
+    daemon.receiveChunk(index === 0);
+    expect(daemon.closesFromClient()).toEqual([]);
+  }
+  // No complete message or pong has arrived, but progress prevents misses.
+  expect(daemon.pingTimestamps()).toEqual(["0s", "25s"]);
+  daemon.finishTransfer();
+  await vi.advanceTimersByTimeAsync(30_000);
+  expect(client.getConnectionState()).toEqual({ status: "connected" });
+  expect(daemon.closesFromClient()).toEqual([]);
+});
+
+test("chunk progress beyond the daemon lease keeps sending heartbeat pings", async () => {
+  useHeartbeatClock();
+  const daemon = new FakeDaemon();
+  daemon.daemonGoesSilent();
+  const client = new DaemonClient({
+    url: "ws://test",
+    clientId: "long-download",
+    logger: noopLogger,
+    reconnect: { enabled: false },
+    transportFactory: () => daemon.transport,
+  });
+  clients.push(client);
+  const connection = client.connect();
+  daemon.openConnection();
+  await connection;
+  client.ensureConnected({ verify: true });
+  for (let index = 0; index < 12; index++) {
+    await vi.advanceTimersByTimeAsync(5_000);
+    daemon.receiveChunk(index === 0);
+    // Each completed window starts the next ping ten seconds later,
+    // even though the response and all queued pongs are still in flight.
+    const expected = ["0s"];
+    if (index >= 4) expected.push("25s");
+    if (index >= 9) expected.push("50s");
+    expect(daemon.pingTimestamps()).toEqual(expected);
+    expect(daemon.closesFromClient()).toEqual([]);
+  }
+  daemon.finishTransfer();
+  await vi.advanceTimersByTimeAsync(30_000);
+  expect(client.getConnectionState()).toEqual({ status: "connected" });
+  expect(daemon.closesFromClient()).toEqual([]);
+});
+
+test("an obsolete heartbeat cannot close a replacement connection", async () => {
   useHeartbeatClock();
   const first = new FakeDaemon();
   const second = new FakeDaemon();
@@ -2735,6 +2875,18 @@ test("sends only one ping while a slow pong is still outstanding", async () => {
   expect(session.pingTimestamps()).toEqual(["10s"]);
 });
 
+test("a heartbeat sharing a latency measurement still saves the RTT", async () => {
+  useHeartbeatClock();
+  const session = new DaemonClientSession();
+  session.daemonAnswersPingsAfter("2s");
+  await session.connect();
+  await session.advance(9_000);
+  const measurement = session.measureLatency({ timeoutMs: 5_000 });
+  await session.advance(2_000);
+  await expect(measurement).resolves.toBe(2000);
+  expect(session.lastLivenessRttMs()).toBe(2000);
+});
+
 test("reports the round-trip time of the last successful heartbeat", async () => {
   useHeartbeatClock();
   const session = new DaemonClientSession();
diff --git a/packages/client/src/daemon-client.ts b/packages/client/src/daemon-client.ts
index 7454c8448f..68677c3f24 100644
--- a/packages/client/src/daemon-client.ts
+++ b/packages/client/src/daemon-client.ts
@@ -1296,6 +1296,7 @@ interface PingProbe {
   reject: (error: Error) => void;
   timeoutHandle: ReturnType<typeof setTimeout>;
   startedAt: number;
+  receivedActivity: boolean;
   // Whether a timeout on this ping should be recorded as a liveness failure. Only the
   // heartbeat sets this; a latency measurement never drives teardown, even when a
   // heartbeat tick shares (dedupes onto) an in-flight measurement ping.
@@ -1439,7 +1440,6 @@ export class DaemonClient {
   private runtimeMetricsInterval: ReturnType<typeof setInterval> | null = null;
   private runtimeMetrics: DaemonClientRuntimeMetrics | null = null;
   private pingProbe: PingProbe | null = null;
-  private connectionVerification: DaemonTransport | null = null;
   private livenessHeartbeatTimer: ReturnType<typeof setTimeout> | null = null;
   private lastLivenessRttMs: number | null = null;
   private consecutiveLivenessFailures = 0;
@@ -1589,6 +1589,7 @@ export class DaemonClient {
         send: (frame) => transport.send(frame),
         onFailure: () => transport.close(4003, "Transport send failed"),
         deliver: (frame) => this.handleTransportMessage(frame),
+        onActivity: () => this.recordTransportActivity(),
       });
       this.lastServerInfoMessage = null;
       this.authFailureReasonValue = null;
@@ -1785,7 +1786,7 @@ export class DaemonClient {
       this.shouldReconnect = true;
     }
     if (this.connectionState.status === "connected") {
-      if (options?.verify) this.verifyConnection();
+      if (options?.verify) this.tickLivenessHeartbeat();
       return;
     }
     if (this.connectionState.status === "connecting") return;
@@ -1798,26 +1799,9 @@ export class DaemonClient {
     );
   }
 
-  private verifyConnection(): void {
-    const transport = this.transport;
-    if (!transport || this.connectionVerification === transport) return;
-    this.connectionVerification = transport;
-    // A session probe has its own deadline, independent of a heartbeat that the OS
-    // may have suspended. A successful response also proves the session can serve RPCs.
-    void this.ping({ timeoutMs: 3_000 })
-      .catch((error: unknown) => {
-        if (this.transport !== transport || this.connectionState.status !== "connected") return;
-        this.disposeTransport(1001, "Connection verification failed");
-        this.scheduleReconnect({
-          reason: error instanceof Error ? error.message : String(error),
-          event: "CONNECTION_VERIFICATION_FAILED",
-          reasonCode: "liveness_timeout",
-        });
-        this.ensureConnected();
-      })
-      .finally(() => {
-        if (this.connectionVerification === transport) this.connectionVerification = null;
-      });
+  private recordTransportActivity(): void {
+    this.consecutiveLivenessFailures = 0;
+    if (this.pingProbe) this.pingProbe.receivedActivity = true;
   }
 
   requireConnectedHosts(): void {
@@ -2553,9 +2537,18 @@ export class DaemonClient {
 
   measureLatency(params?: { timeoutMs?: number }): Promise<number> {
     const timeoutMs = Math.max(1, params?.timeoutMs ?? DEFAULT_LIVENESS_TIMEOUT_MS);
-    return this.sendPingAwaitRtt({ timeoutMs, drivesLivenessFailure: false }).catch((error) => {
-      throw toTimeoutError(error, "Latency measurement", timeoutMs);
+    let deadline: ReturnType<typeof setTimeout>;
+    const timeout = new Promise<never>((_resolve, reject) => {
+      deadline = setTimeout(() => reject(new PingTimeoutError(timeoutMs)), timeoutMs);
     });
+    return Promise.race([
+      this.sendPingAwaitRtt({ timeoutMs, drivesLivenessFailure: false }),
+      timeout,
+    ])
+      .catch((error) => {
+        throw toTimeoutError(error, "Latency measurement", timeoutMs);
+      })
+      .finally(() => clearTimeout(deadline));
   }
 
   private async livenessPing(params?: { timeoutMs?: number }): Promise<number> {
@@ -2591,21 +2584,23 @@ export class DaemonClient {
       resolveProbe = resolve;
       rejectProbe = reject;
     });
+    const expire = () => {
+      if (this.pingProbe !== probe) return;
+      this.pingProbe = null;
+      const error = new PingTimeoutError(timeoutMs);
+      probe.reject(error);
+      // Keep the deadline fixed so subsequent pings renew the daemon socket lease
+      // during a long download. Progress proves life even when its pong is queued.
+      if (probe.drivesLivenessFailure && !probe.receivedActivity) {
+        this.recordLivenessFailure(toTimeoutError(error, "Liveness check", timeoutMs));
+      }
+    };
     const probe: PingProbe = {
       promise,
       resolve: (value) => resolveProbe?.(value),
       reject: (error) => rejectProbe?.(error),
-      timeoutHandle: setTimeout(() => {
-        if (this.pingProbe !== probe) {
-          return;
-        }
-        this.pingProbe = null;
-        const error = new PingTimeoutError(timeoutMs);
-        probe.reject(error);
-        if (probe.drivesLivenessFailure) {
-          this.recordLivenessFailure(toTimeoutError(error, "Liveness check", timeoutMs));
-        }
-      }, timeoutMs),
+      timeoutHandle: setTimeout(expire, timeoutMs),
+      receivedActivity: false,
       startedAt,
       drivesLivenessFailure: params.drivesLivenessFailure,
     };
@@ -2646,14 +2641,21 @@ export class DaemonClient {
     }
     this.livenessHeartbeatTimer = setTimeout(() => {
       this.livenessHeartbeatTimer = null;
-      this.livenessPing({ timeoutMs: LIVENESS_HEARTBEAT_TIMEOUT_MS })
-        .catch(() => {})
-        .finally(() => {
-          this.scheduleNextLivenessHeartbeat();
-        });
+      this.tickLivenessHeartbeat();
     }, LIVENESS_HEARTBEAT_INTERVAL_MS);
   }
 
+  private tickLivenessHeartbeat(): void {
+    this.stopLivenessHeartbeat();
+    const transport = this.transport;
+    const tick = this.livenessPing({ timeoutMs: LIVENESS_HEARTBEAT_TIMEOUT_MS });
+    void tick
+      .catch(() => {})
+      .finally(() => {
+        if (this.transport === transport) this.scheduleNextLivenessHeartbeat();
+      });
+  }
+
   // ============================================================================
   // Agent RPCs (requestId-correlated)
   // ============================================================================
diff --git a/packages/protocol/src/chunked-transport.ts b/packages/protocol/src/chunked-transport.ts
index a32d68424f..8faa22cd96 100644
--- a/packages/protocol/src/chunked-transport.ts
+++ b/packages/protocol/src/chunked-transport.ts
@@ -25,6 +25,7 @@ export class ChunkedTransport {
       supportsDrain?: boolean;
       send: (frame: Frame, waitForDrain: boolean) => void | Promise<void>;
       deliver: (frame: Frame) => void;
+      onActivity?: () => void;
       onFailure?: (error: unknown) => void;
     },
   ) {
@@ -134,6 +135,7 @@ export class ChunkedTransport {
         { cause: error },
       );
     }
+    this.io.onActivity?.();
     if (message !== undefined) this.io.deliver(message);
   }
 

From b0a8a5db6d5cc64a802c0f56fa91da8ada2647a3 Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Thu, 5 Nov 2026 21:30:09 +0700
Subject: [PATCH 23/29] Stop the double reconnect when returning to the app
 (#8855)

* fix(app): keep the selected connection when it reconnects during a probe cycle

When the app returns from the background with more than one saved
connection and the selected socket was closed meanwhile, the probe cycle
marks the selected connection unavailable at probe start, while its client
is still reconnecting. The alternative probe lands later, after the
selected client has already reconnected, and finalizing the cycle switched
to the alternative using that stale verdict. That disposed the live client
(rejecting the in-flight timeline catch-up) and reconnected a second time.

The cycle now reconciles the selected connection's verdict with its
client's current state before deciding to fail over. A client that is
still down at that point still fails over as before.

* test(app): cover reconnect with and without a heartbeat RTT
---
 packages/app/src/runtime/host-runtime.test.ts | 145 ++++++++++++++++++
 packages/app/src/runtime/host-runtime.ts      |  24 +++
 2 files changed, 169 insertions(+)

diff --git a/packages/app/src/runtime/host-runtime.test.ts b/packages/app/src/runtime/host-runtime.test.ts
index 33e4f1a316..ca8e417fc3 100644
--- a/packages/app/src/runtime/host-runtime.test.ts
+++ b/packages/app/src/runtime/host-runtime.test.ts
@@ -1189,6 +1189,151 @@ describe("HostRuntimeController", () => {
     expect(controller.getSnapshot().client).toBe(activeClient as unknown as DaemonClient);
   });
 
+  it.each([40, null])(
+    "keeps the selected connection when it reconnects before an alternative probe resolves with heartbeat RTT %s",
+    async (reconnectedRtt) => {
+      useHostRuntimeClock();
+      const primary: HostConnection = {
+        id: "relay:relay.paseo.sh:443",
+        type: "relay",
+        relayEndpoint: "relay.paseo.sh:443",
+        daemonPublicKeyB64: "pk_test",
+      };
+      const alternative: HostConnection = {
+        id: "relay:relay-next.paseo.sh:443",
+        type: "relay",
+        relayEndpoint: "relay-next.paseo.sh:443",
+        daemonPublicKeyB64: "pk_test",
+      };
+      const host = makeHost({
+        connections: [primary, alternative],
+        preferredConnectionId: primary.id,
+      });
+      const activeClient = new FakeDaemonClient();
+      activeClient.setConnectionState({ status: "connected" });
+      activeClient.heartbeatReportsRtt(40);
+      // The first alternative probe (startup) answers immediately; the one that
+      // runs after the foreground is slow, like a relay handshake on mobile.
+      const slowAlternativeProbe = createDeferred<void>();
+      let alternativeProbes = 0;
+      const createdClients: FakeDaemonClient[] = [];
+      const controller = new HostRuntimeController({
+        host,
+        deps: {
+          createClient: () => {
+            const client = new FakeDaemonClient();
+            createdClients.push(client);
+            return client as unknown as DaemonClient;
+          },
+          connectToDaemon: async ({ connection }) => {
+            if (connection.id !== alternative.id) {
+              throw new Error(`unexpected probe for ${connection.id}`);
+            }
+            alternativeProbes += 1;
+            if (alternativeProbes > 1) await slowAlternativeProbe.promise;
+            return {
+              client: makeConnectedProbeClient(60) as unknown as DaemonClient,
+              serverId: host.serverId,
+              hostname: host.label ?? null,
+            };
+          },
+          getClientId: async () => "cid_test_runtime",
+        },
+      });
+      await controller.start({
+        autoProbe: false,
+        initialConnection: {
+          connectionId: primary.id,
+          existingClient: activeClient as unknown as DaemonClient,
+        },
+      });
+      expect(controller.getSnapshot().activeConnectionId).toBe(primary.id);
+
+      // The relay closed the socket while the app was in the background.
+      activeClient.setConnectionState({ status: "disconnected", reason: "1012" });
+      await vi.advanceTimersByTimeAsync(130_000);
+
+      // Foreground: the probe cycle starts while the selected client is still down ...
+      const cycle = controller.runProbeCycleNow();
+      await vi.advanceTimersByTimeAsync(1_000);
+      expect(alternativeProbes).toBe(2);
+      // ... the selected client reconnects ...
+      activeClient.heartbeatReportsRtt(reconnectedRtt);
+      activeClient.setConnectionState({ status: "connected" });
+      expect(controller.getSnapshot().connectionStatus).toBe("online");
+      const statuses: string[] = [];
+      controller.subscribe(() => statuses.push(controller.getSnapshot().connectionStatus));
+      // ... and only then does the alternative probe come back.
+      slowAlternativeProbe.resolve();
+      await cycle;
+
+      // Once the selected connection is back online, nothing should take it down again.
+      expect(statuses.filter((status) => status !== "online")).toEqual([]);
+      expect(controller.getSnapshot().activeConnectionId).toBe(primary.id);
+      expect(controller.getSnapshot().client).toBe(activeClient as unknown as DaemonClient);
+      expect(activeClient.isDisposed()).toBe(false);
+      expect(createdClients).toEqual([]);
+    },
+  );
+
+  it("fails over when the selected connection stays down until an alternative probe resolves", async () => {
+    useHostRuntimeClock();
+    const primary: HostConnection = {
+      id: "relay:relay.paseo.sh:443",
+      type: "relay",
+      relayEndpoint: "relay.paseo.sh:443",
+      daemonPublicKeyB64: "pk_test",
+    };
+    const alternative: HostConnection = {
+      id: "relay:relay-next.paseo.sh:443",
+      type: "relay",
+      relayEndpoint: "relay-next.paseo.sh:443",
+      daemonPublicKeyB64: "pk_test",
+    };
+    const host = makeHost({
+      connections: [primary, alternative],
+      preferredConnectionId: primary.id,
+    });
+    const activeClient = new FakeDaemonClient();
+    activeClient.setConnectionState({ status: "connected" });
+    const slowAlternativeProbe = createDeferred<void>();
+    let alternativeProbes = 0;
+    const controller = new HostRuntimeController({
+      host,
+      deps: {
+        createClient: () => new FakeDaemonClient() as unknown as DaemonClient,
+        connectToDaemon: async () => {
+          alternativeProbes += 1;
+          if (alternativeProbes > 1) await slowAlternativeProbe.promise;
+          return {
+            client: makeConnectedProbeClient(60) as unknown as DaemonClient,
+            serverId: host.serverId,
+            hostname: host.label ?? null,
+          };
+        },
+        getClientId: async () => "cid_test_runtime",
+      },
+    });
+    await controller.start({
+      autoProbe: false,
+      initialConnection: {
+        connectionId: primary.id,
+        existingClient: activeClient as unknown as DaemonClient,
+      },
+    });
+
+    activeClient.setConnectionState({ status: "disconnected", reason: "1012" });
+    await vi.advanceTimersByTimeAsync(130_000);
+    const cycle = controller.runProbeCycleNow();
+    await vi.advanceTimersByTimeAsync(1_000);
+    slowAlternativeProbe.resolve();
+    await cycle;
+
+    expect(controller.getSnapshot().activeConnectionId).toBe(alternative.id);
+    expect(activeClient.isDisposed()).toBe(true);
+    await controller.stop();
+  });
+
   it("rejects probes that resolve to a different server id", async () => {
     const host = makeHost({
       serverId: "srv_old",
diff --git a/packages/app/src/runtime/host-runtime.ts b/packages/app/src/runtime/host-runtime.ts
index 0c7c9f4660..4d31258aaa 100644
--- a/packages/app/src/runtime/host-runtime.ts
+++ b/packages/app/src/runtime/host-runtime.ts
@@ -1021,6 +1021,9 @@ export class HostRuntimeController {
       }
 
       const currentActiveConnectionId = this.snapshot.activeConnectionId;
+      if (currentActiveConnectionId) {
+        this.reconcileActiveProbeWithClient(currentActiveConnectionId, probeByConnectionId);
+      }
       const activeProbe = currentActiveConnectionId
         ? probeByConnectionId.get(currentActiveConnectionId)
         : null;
@@ -1211,6 +1214,27 @@ export class HostRuntimeController {
     });
   }
 
+  // The active connection is probed through its own client, which may still be
+  // reconnecting when the probe starts. A verdict taken then is stale if the client
+  // has since connected, so the decision uses the client's current state.
+  private reconcileActiveProbeWithClient(
+    connectionId: string,
+    probeByConnectionId: Map<string, ConnectionProbeState>,
+  ): void {
+    if (probeByConnectionId.get(connectionId)?.status !== "unavailable") return;
+    if (this.authRejectedConnectionIds.has(connectionId)) return;
+    const client = this.snapshot.client;
+    if (!client || client.getConnectionState().status !== "connected") return;
+    const rttMs = client.getLastLivenessRttMs();
+    probeByConnectionId.set(
+      connectionId,
+      rttMs === null
+        ? { status: "pending", latencyMs: null }
+        : { status: "available", latencyMs: rttMs },
+    );
+    this.updateSnapshot({ probeByConnectionId: new Map(probeByConnectionId) });
+  }
+
   private isConnectionUnavailable(
     connectionId: string,
     probe: ConnectionProbeState | null | undefined,

From e9f897a66a9f74cc22c993c284d5fdb46b3af4d9 Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Thu, 5 Nov 2026 21:33:17 +0700
Subject: [PATCH 24/29] fix(app): rest the iPhone composer at the screen's
 bottom clearance (#8823)

* fix(app): rest the iPhone composer at the screen's bottom clearance

The composer sat 50pt above the bottom edge on every iPhone: the dock
padded the rectangular home-indicator safe area (34pt) and the composer
stacked another 16pt under it. On iPhone Duo that safe area is also
taller than needed; iOS 27.1's bottom-bar layout guide, which follows
the screen's corners, rests 26pt from the edge.

The native window-layout probe now publishes that clearance, and
WindowLayoutProvider overrides the safe-area context's bottom with it,
so every useSafeAreaInsets() consumer reads one bottom value and null
falls back to the system inset. The docked composer applies
max(bottom, 16) once and keeps 16pt above the keyboard through the
translate view's transform; the gap is not animated as padding because
layout updates through the keyboard transition are expensive on Android
Fabric.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

* fix(app): keep the Import session gap under the wide new workspace composer

The composer's own bottom spacing used to separate it from the Import
session pill on the wide form. With that spacing moved to the dock, the
centered slot padded below the pill instead, so the pill touched the
composer. The pill now owns its gap above.

Co-authored-by: Elsa Granger <zeyugao@outlook.com>

---------

Co-authored-by: Elsa Granger <zeyugao@outlook.com>
---
 docs/design.md                                |  2 +
 docs/floating-panels.md                       |  5 ++
 .../browser/composer-bottom-spacing.spec.ts   | 53 +++++++++++++++
 .../ios/PaseoWindowLayoutModule.swift         | 14 ++++
 .../src/components/workspace-setup-dialog.tsx |  5 +-
 .../app/src/composer/dock/index.native.tsx    | 24 +++++--
 packages/app/src/composer/dock/index.tsx      |  2 +-
 .../composer/dock/internal/capacity.test.ts   | 66 ++++++++++++++++++-
 .../src/composer/dock/internal/capacity.ts    | 30 ++++++++-
 packages/app/src/composer/index.tsx           |  2 -
 .../src/keyboard/shift/internal/context.ts    |  3 +-
 .../keyboard/shift/internal/policy.test.ts    | 38 +++++++++--
 .../app/src/keyboard/shift/internal/policy.ts |  7 +-
 .../shift/internal/translate.android.tsx      | 11 +++-
 .../keyboard/shift/internal/translate.ios.tsx | 41 ++++++++----
 .../src/keyboard/shift/internal/translate.tsx |  2 +
 .../new-workspace/import-session-button.tsx   |  5 +-
 packages/app/src/window-layout/index.ios.tsx  | 17 +++--
 packages/app/src/window-layout/model.test.ts  | 35 ++++++++++
 packages/app/src/window-layout/model.ts       | 16 +++++
 20 files changed, 341 insertions(+), 37 deletions(-)
 create mode 100644 packages/app/e2e/browser/composer-bottom-spacing.spec.ts
 create mode 100644 packages/app/src/window-layout/model.test.ts

diff --git a/docs/design.md b/docs/design.md
index 0437320c09..b48ed81891 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -169,6 +169,8 @@ Electron window controls are top-corner obstructions, not a compact-layout condi
 
 Windows and Linux controls are fixed window chrome, outside scrolling header content. A tab rail that reaches them ends at their obstruction and shows the shared overflow fade. On macOS, the Explorer toggle occupies a fixed top-right window slot so opening and closing Explorer does not move the pointer target.
 
+Each window edge has one safe-area owner. `WindowLayoutProvider` publishes the bottom inset that every surface reads through `useSafeAreaInsets()`: on iOS 27.1 and later it is UIKit's bottom-bar clearance, which refines the rectangular home-indicator inset to the screen's corners, and elsewhere the system inset. Surfaces apply that value once and never stack their own spacing under it; `WindowLayoutSurface` owns the horizontal insets the same way.
+
 A new list+detail feature copies the settings shell. A new workspace-shaped feature copies the workspace shell. Inventing a third shape happens in design review, not in a PR.
 
 ---
diff --git a/docs/floating-panels.md b/docs/floating-panels.md
index 9032a3d079..4a770f897b 100644
--- a/docs/floating-panels.md
+++ b/docs/floating-panels.md
@@ -172,6 +172,11 @@ slide under the header on open and out from under it on close. Do not swap the
 dock to keyboard padding at rest. Changing its height creates either a blank
 band or a paused transition when the stream list updates its viewport.
 
+The docked composer rests at the larger of the safe-area bottom and 16pt. With
+the keyboard open it keeps 16pt above the keyboard through the translate view's
+`keyboardGap`, which rises further than the keyboard's safe-area overlap. Do not
+grow the composer's bottom padding with the keyboard instead.
+
 Do not animate a layout prop through the keyboard transition. On Android
 Fabric, each animated layout update clones the shadow tree and runs Yoga over
 the dock subtree. This measured about 10 ms per frame on the emulator and the
diff --git a/packages/app/e2e/browser/composer-bottom-spacing.spec.ts b/packages/app/e2e/browser/composer-bottom-spacing.spec.ts
new file mode 100644
index 0000000000..d4a00ee0a0
--- /dev/null
+++ b/packages/app/e2e/browser/composer-bottom-spacing.spec.ts
@@ -0,0 +1,53 @@
+import type { Locator } from "@playwright/test";
+import { expect, test } from "../support/fixtures";
+import { gotoAppShell } from "../support/helpers/app";
+import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
+import { openNewWorkspaceComposer } from "../support/helpers/new-workspace";
+import { seedWorkspace } from "../support/helpers/seed-client";
+import { waitForSidebarHydration } from "../support/helpers/workspace-ui";
+
+async function box(locator: Locator) {
+  await expect(locator).toBeVisible({ timeout: 30_000 });
+  const rect = await locator.boundingBox();
+  expect(rect).not.toBeNull();
+  return { top: rect!.y, bottom: rect!.y + rect!.height };
+}
+
+test.describe("Composer bottom spacing", () => {
+  test("the chat composer rests one content spacing above the window edge", async ({ page }) => {
+    const agent = await seedMockAgentWorkspace({
+      repoPrefix: "composer-bottom-spacing-",
+      title: "Bottom spacing",
+    });
+    try {
+      await openAgentRoute(page, { workspaceId: agent.workspaceId, agentId: agent.agentId });
+      const surface = await box(
+        page.getByTestId("message-input-root").filter({ visible: true }).first(),
+      );
+      const viewportHeight = await page.evaluate(() => window.innerHeight);
+      expect(viewportHeight - surface.bottom).toBe(16);
+    } finally {
+      await agent.cleanup();
+    }
+  });
+
+  test("the wide new workspace form keeps one content spacing above Import session", async ({
+    page,
+  }) => {
+    const workspace = await seedWorkspace({ repoPrefix: "composer-bottom-spacing-form-" });
+    try {
+      await page.setViewportSize({ width: 1440, height: 900 });
+      await gotoAppShell(page);
+      await waitForSidebarHydration(page);
+      await openNewWorkspaceComposer(page, {
+        projectKey: workspace.projectKey,
+        projectDisplayName: workspace.projectDisplayName,
+      });
+      const composer = await box(page.locator('[data-testid="message-input-root"]:visible'));
+      const importButton = await box(page.getByTestId("new-workspace-import-session"));
+      expect(importButton.top - composer.bottom).toBe(16);
+    } finally {
+      await workspace.cleanup();
+    }
+  });
+});
diff --git a/packages/app/modules/paseo-window-layout/ios/PaseoWindowLayoutModule.swift b/packages/app/modules/paseo-window-layout/ios/PaseoWindowLayoutModule.swift
index f5b673e6cc..3ac90cf2b5 100644
--- a/packages/app/modules/paseo-window-layout/ios/PaseoWindowLayoutModule.swift
+++ b/packages/app/modules/paseo-window-layout/ios/PaseoWindowLayoutModule.swift
@@ -17,6 +17,7 @@ final class WindowLayoutView: ExpoView {
   private var divisions: [CGRect] = []
   private var barGuide: UILayoutGuide?
   private var barEdge = "none"
+  private var bottomBarGuide: UILayoutGuide?
   private var measuredBounds = CGRect.zero
 
   required init(appContext: AppContext? = nil) {
@@ -36,6 +37,7 @@ final class WindowLayoutView: ExpoView {
   override func didMoveToWindow() {
     super.didMoveToWindow()
     previousPayload = nil
+    bottomBarGuide = nil
     setNeedsUpdateConstraints()
     scheduleUpdate()
   }
@@ -66,6 +68,11 @@ final class WindowLayoutView: ExpoView {
       case .trailing: edge = "trailing"
       default: edge = "none"
       }
+      if bottomBarGuide == nil {
+        // Where a bottom bar rests: above the home indicator, refined to the
+        // screen's corners rather than the rectangular safe area.
+        bottomBarGuide = layoutGuide(for: .bar(onEdge: UIRectEdge.bottom, extent: 44))
+      }
       if edge != barEdge {
         barEdge = edge
         barGuide = edge == "none" ? nil : layoutGuide(
@@ -93,10 +100,17 @@ final class WindowLayoutView: ExpoView {
     let bar = barGuide?.layoutFrame
     var barPayload: Any = NSNull()
     if let bar, bar.width > 0, bar.height > 0 { barPayload = rect(bar) }
+    // Before UIKit resolves the guide its frame has no height: publish null (the
+    // system inset applies) rather than a false zero clearance.
+    var bottomClearance: Any = NSNull()
+    if let bottomBar = bottomBarGuide?.layoutFrame, bottomBar.height > 0 {
+      bottomClearance = max(0, bounds.maxY - bottomBar.maxY)
+    }
     let payload: [String: Any] = [
       "bounds": rect(bounds),
       "verticalBarEdge": barEdge,
       "verticalBar": barPayload,
+      "bottomClearance": bottomClearance,
       "divisions": divisions.map(rect)
     ]
     guard !NSDictionary(dictionary: payload).isEqual(to: previousPayload ?? [:]) else { return }
diff --git a/packages/app/src/components/workspace-setup-dialog.tsx b/packages/app/src/components/workspace-setup-dialog.tsx
index 3a326aed3d..299bd9f27b 100644
--- a/packages/app/src/components/workspace-setup-dialog.tsx
+++ b/packages/app/src/components/workspace-setup-dialog.tsx
@@ -436,7 +436,7 @@ export function WorkspaceSetupDialog() {
       desktopMaxWidth={640}
     >
       <FileDropZone style={styles.section}>
-        <KeyboardTranslateView>
+        <KeyboardTranslateView style={styles.composerSlot}>
           <Composer
             agentId={`workspace-setup:${serverId}:${sourceDirectory}`}
             serverId={serverId}
@@ -487,6 +487,9 @@ const styles = StyleSheet.create((theme) => ({
     color: theme.colors.destructive,
     lineHeight: 20,
   },
+  composerSlot: {
+    paddingBottom: theme.spacing[4],
+  },
   composerInputWrapper: {
     backgroundColor: theme.colors.surface2,
   },
diff --git a/packages/app/src/composer/dock/index.native.tsx b/packages/app/src/composer/dock/index.native.tsx
index e3720ccbee..ab26fe5612 100644
--- a/packages/app/src/composer/dock/index.native.tsx
+++ b/packages/app/src/composer/dock/index.native.tsx
@@ -19,15 +19,18 @@ import Animated, {
 import { useKeyboardShift } from "@/keyboard/shift";
 import {
   resolveCenteredClearance,
+  resolveComposerBottomPlacement,
   resolveComposerSlotCapacity,
   updateComposerCapacity,
   type ComposerCapacity,
 } from "./internal/capacity";
+import { SPACING } from "@/styles/theme";
 
 const ViewportSizing = createContext<SharedValue<ComposerCapacity | undefined> | null>(null);
 
 interface ComposerViewportProps extends ViewProps {
   bottomInset?: number;
+  keyboardGap?: number;
   centered?: boolean;
 }
 
@@ -36,6 +39,7 @@ function ComposerViewport({
   children,
   onLayout,
   bottomInset = 0,
+  keyboardGap = 0,
   centered = false,
   ...props
 }: ComposerViewportProps) {
@@ -48,6 +52,7 @@ function ComposerViewport({
       bottomInset,
       safeAreaBottom: safeAreaBottom.value,
       keyboardShift: layoutShift.value,
+      keyboardGap,
       centered,
     }),
     (geometry) => {
@@ -129,6 +134,10 @@ export function ComposerDock({
   const insets = useSafeAreaInsets();
   const contentMaxWidth = resolveContentMaxWidth(useAppSettings().settings);
   const centeredClearance = useCenteredClearance(insets.bottom);
+  const placement = resolveComposerBottomPlacement({
+    safeAreaBottom: insets.bottom,
+    contentSpacing: SPACING[4],
+  });
   // Preserve the existing centered form's visual balance on tablets.
   const bottomInset = centered && !fullscreen ? HEADER_INNER_HEIGHT + 24 : 0;
   const fullscreenSurface = [
@@ -176,7 +185,9 @@ export function ComposerDock({
               style={fullscreen ? dockStyles.surface : dockStyles.centeredComposer}
               fullscreen={fullscreen}
             >
-              <View style={fullscreen ? fullscreenSurface : dockStyles.composer}>{composer}</View>
+              <View style={fullscreen ? fullscreenSurface : dockStyles.centeredComposerSurface}>
+                {composer}
+              </View>
             </ComposerViewportContent>
           </ComposerViewportContent>
         </KeyboardTranslateView>
@@ -185,8 +196,12 @@ export function ComposerDock({
     );
   }
   return (
-    <ComposerViewport style={dockStyles.viewport}>
-      <KeyboardTranslateView style={dockStyles.surface} enabled={!fullscreen}>
+    <ComposerViewport style={dockStyles.viewport} keyboardGap={placement.keyboardGap}>
+      <KeyboardTranslateView
+        style={dockStyles.surface}
+        enabled={!fullscreen}
+        keyboardGap={placement.keyboardGap}
+      >
         <View
           testID="composer-dock-content"
           collapsable={false}
@@ -208,7 +223,7 @@ export function ComposerDock({
             style={
               fullscreen
                 ? fullscreenSurface
-                : [dockStyles.composer, { paddingBottom: insets.bottom }]
+                : [dockStyles.composer, { paddingBottom: placement.restingPadding }]
             }
           >
             {composer}
@@ -232,6 +247,7 @@ const dockStyles = StyleSheet.create({
   centered: { flexShrink: 1, width: "100%" },
   // Reserve the composer's own capped height before the setup scroll view shrinks.
   centeredComposer: { width: "100%", flexShrink: 0 },
+  centeredComposerSurface: { width: "100%", flexShrink: 1 },
   setup: { flexGrow: 0, flexShrink: 1, minHeight: 0 },
   hiddenSetup: { display: "none" },
 });
diff --git a/packages/app/src/composer/dock/index.tsx b/packages/app/src/composer/dock/index.tsx
index 421002352e..0456cd6280 100644
--- a/packages/app/src/composer/dock/index.tsx
+++ b/packages/app/src/composer/dock/index.tsx
@@ -72,7 +72,7 @@ export function ComposerDock({
 const styles = StyleSheet.create((theme) => ({
   surface: { flex: 1, overflow: "hidden" },
   content: { flex: 1, justifyContent: "flex-end" },
-  composer: { width: "100%", flexShrink: 1 },
+  composer: { width: "100%", flexShrink: 1, paddingBottom: theme.spacing[4] },
   // Fixed, not absolute: a touch pan that starts inside an overflow-hidden ancestor
   // never reaches the zoomed visual viewport, while a fixed box chains to the viewport
   // directly. React Native Web renders `fixed`; React Native's style type omits it.
diff --git a/packages/app/src/composer/dock/internal/capacity.test.ts b/packages/app/src/composer/dock/internal/capacity.test.ts
index 44e79e6ef9..973c7f2406 100644
--- a/packages/app/src/composer/dock/internal/capacity.test.ts
+++ b/packages/app/src/composer/dock/internal/capacity.test.ts
@@ -1,18 +1,66 @@
 import { describe, expect, it } from "vitest";
 import {
   resolveCenteredClearance,
+  resolveComposerBottomPlacement,
   resolveComposerSlotCapacity,
   resolveInlineComposerCapacity,
   resolveComposerCapacity,
   updateComposerCapacity,
 } from "./capacity";
 
+describe("composer bottom placement", () => {
+  const keyboardHeight = 264;
+  /** Keyboard top minus composer bottom, both measured up from the window bottom. */
+  function keyboardGapAbove(safeAreaBottom: number): number {
+    const placement = resolveComposerBottomPlacement({ safeAreaBottom, contentSpacing: 16 });
+    const shift = keyboardHeight - safeAreaBottom;
+    const lift = shift + Math.min(placement.keyboardGap, shift);
+    return placement.restingPadding + lift - keyboardHeight;
+  }
+
+  it("rests at the bottom clearance without stacking a second gutter", () => {
+    expect(resolveComposerBottomPlacement({ safeAreaBottom: 34, contentSpacing: 16 })).toEqual({
+      restingPadding: 34,
+      keyboardGap: 16,
+    });
+    expect(
+      resolveComposerBottomPlacement({ safeAreaBottom: 24, contentSpacing: 16 }).restingPadding,
+    ).toBe(24);
+  });
+
+  it.each([0, 20, 34])("never rests closer to the edge than the content spacing (%s)", (inset) => {
+    expect(
+      resolveComposerBottomPlacement({ safeAreaBottom: inset, contentSpacing: 16 }).restingPadding,
+    ).toBe(Math.max(inset, 16));
+  });
+
+  it("keeps a measured zero clearance at the content spacing", () => {
+    expect(resolveComposerBottomPlacement({ safeAreaBottom: 0, contentSpacing: 16 })).toEqual({
+      restingPadding: 16,
+      keyboardGap: 0,
+    });
+  });
+
+  it.each([0, 20, 24, 34])("keeps the content spacing above the keyboard (%s)", (inset) => {
+    expect(keyboardGapAbove(inset)).toBe(16);
+  });
+
+  it("reserves the gap's extra rise out of the docked composer's capacity", () => {
+    const viewport = { height: 582, bottomInset: 0, safeAreaBottom: 34, centered: false };
+    const closed = resolveComposerCapacity({ ...viewport, keyboardShift: 0, keyboardGap: 16 });
+    const open = resolveComposerCapacity({ ...viewport, keyboardShift: 230, keyboardGap: 16 });
+    expect(closed).toBe(577);
+    expect(open).toBe(331);
+  });
+});
+
 describe("composer viewport", () => {
   it("caps the complete compact composer at sixty percent of keyboard-reserved space", () => {
     const open = updateComposerCapacity(undefined, {
       height: 582,
       bottomInset: 24,
       safeAreaBottom: 0,
+      keyboardGap: 0,
       centered: false,
       keyboardShift: 308,
     });
@@ -25,6 +73,7 @@ describe("composer viewport", () => {
       height: 582,
       bottomInset: 24,
       safeAreaBottom: 0,
+      keyboardGap: 0,
       centered: false,
       keyboardShift: 308,
     });
@@ -35,7 +84,13 @@ describe("composer viewport", () => {
     );
   });
   it("preserves the editing capacity when the keyboard closes", () => {
-    const viewport = { height: 582, bottomInset: 24, safeAreaBottom: 0, centered: false };
+    const viewport = {
+      height: 582,
+      bottomInset: 24,
+      safeAreaBottom: 0,
+      keyboardGap: 0,
+      centered: false,
+    };
     const open = updateComposerCapacity(undefined, { ...viewport, keyboardShift: 308 });
     const closed = updateComposerCapacity(open, { ...viewport, keyboardShift: 0 });
     expect(open.capacity).toBe(245);
@@ -48,6 +103,7 @@ describe("composer viewport", () => {
       height: 582,
       bottomInset: 24,
       safeAreaBottom: 0,
+      keyboardGap: 0,
       centered: false,
       keyboardShift: 308,
     });
@@ -56,6 +112,7 @@ describe("composer viewport", () => {
         height: 650,
         bottomInset: 24,
         safeAreaBottom: 0,
+        keyboardGap: 0,
         centered: false,
         keyboardShift: 0,
       }).capacity,
@@ -65,6 +122,7 @@ describe("composer viewport", () => {
         height: 0,
         bottomInset: 24,
         safeAreaBottom: 0,
+        keyboardGap: 0,
         centered: false,
         keyboardShift: 0,
       }),
@@ -76,6 +134,7 @@ describe("composer viewport", () => {
       bottomInset: 24,
       safeAreaBottom: 0,
       keyboardShift: 308,
+      keyboardGap: 0,
       centered: false,
     });
     expect(height).toBe(245);
@@ -91,6 +150,7 @@ describe("composer viewport", () => {
       bottomInset,
       safeAreaBottom: 0,
       keyboardShift,
+      keyboardGap: 0,
       centered: true,
     });
     expect(height).toBe(695);
@@ -110,6 +170,7 @@ describe("composer viewport", () => {
         bottomInset: 72,
         safeAreaBottom: 0,
         keyboardShift: 313,
+        keyboardGap: 0,
         centered: true,
       }),
     ).toBe(407);
@@ -122,6 +183,7 @@ describe("composer viewport", () => {
       bottomInset: 60,
       safeAreaBottom: 32,
       keyboardShift: 288,
+      keyboardGap: 0,
       centered: true,
     };
     const height = resolveComposerCapacity(geometry);
@@ -145,6 +207,7 @@ describe("composer viewport", () => {
         bottomInset: 24,
         safeAreaBottom: 0,
         keyboardShift: 0,
+        keyboardGap: 0,
         centered: false,
       }),
     ).toBe(553);
@@ -154,6 +217,7 @@ describe("composer viewport", () => {
         bottomInset: 0,
         safeAreaBottom: 0,
         keyboardShift: 200,
+        keyboardGap: 0,
         centered: false,
       }),
     ).toBe(95);
diff --git a/packages/app/src/composer/dock/internal/capacity.ts b/packages/app/src/composer/dock/internal/capacity.ts
index 9c460e1729..d9be8b9255 100644
--- a/packages/app/src/composer/dock/internal/capacity.ts
+++ b/packages/app/src/composer/dock/internal/capacity.ts
@@ -4,6 +4,8 @@ interface ComposerGeometry {
   /** The keyboard also covers this space below its shift. */
   safeAreaBottom: number;
   keyboardShift: number;
+  /** A docked composer rises this much beyond the keyboard shift; see the placement. */
+  keyboardGap: number;
   centered: boolean;
 }
 
@@ -24,10 +26,36 @@ export function resolveComposerCapacity(input: ComposerGeometry): number {
         input.height - input.bottomInset,
         input.height - input.safeAreaBottom - input.keyboardShift,
       )
-    : input.height - input.bottomInset - input.keyboardShift;
+    : input.height -
+      input.bottomInset -
+      input.keyboardShift -
+      Math.min(input.keyboardGap, input.keyboardShift);
   return Math.max(0, available - 5);
 }
 
+export interface ComposerBottomPlacement {
+  /** The composer's distance from the window bottom with the keyboard closed. */
+  restingPadding: number;
+  /** How much further than the keyboard's safe-area overlap the composer rises. */
+  keyboardGap: number;
+}
+
+/**
+ * One bottom distance for the docked composer: the safe-area bottom, never closer to
+ * the edge than the content spacing. With the keyboard open it keeps the content
+ * spacing above the keyboard.
+ */
+export function resolveComposerBottomPlacement(input: {
+  safeAreaBottom: number;
+  contentSpacing: number;
+}): ComposerBottomPlacement {
+  const restingPadding = Math.max(input.safeAreaBottom, input.contentSpacing);
+  return {
+    restingPadding,
+    keyboardGap: input.safeAreaBottom + input.contentSpacing - restingPadding,
+  };
+}
+
 /** Space below a centered form that the keyboard fills before the form moves. */
 export function resolveCenteredClearance(input: {
   viewportHeight: number;
diff --git a/packages/app/src/composer/index.tsx b/packages/app/src/composer/index.tsx
index 2ad3620313..ad6961fe16 100644
--- a/packages/app/src/composer/index.tsx
+++ b/packages/app/src/composer/index.tsx
@@ -2568,7 +2568,6 @@ const styles = StyleSheet.create((theme: Theme) => ({
     width: "100%",
     overflow: "visible",
     paddingHorizontal: theme.spacing[4],
-    paddingBottom: theme.spacing[4],
   },
   inputAreaLocked: {
     opacity: 0.6,
@@ -2578,7 +2577,6 @@ const styles = StyleSheet.create((theme: Theme) => ({
     minHeight: 0,
     alignItems: "stretch",
     paddingHorizontal: 0,
-    paddingBottom: 0,
   },
   fullscreenFill: {
     flex: 1,
diff --git a/packages/app/src/keyboard/shift/internal/context.ts b/packages/app/src/keyboard/shift/internal/context.ts
index bc1df21fb4..b86005e214 100644
--- a/packages/app/src/keyboard/shift/internal/context.ts
+++ b/packages/app/src/keyboard/shift/internal/context.ts
@@ -17,6 +17,7 @@ export const KeyboardShiftContext = createContext<KeyboardShiftContextValue | nu
 export interface KeyboardTranslation {
   enabled: boolean;
   bottomClearance: number;
+  keyboardGap: number;
 }
 
 export interface WindowRect {
@@ -38,7 +39,7 @@ export interface KeyboardTranslationScope {
 
 /** Views outside a KeyboardTranslateView stay put. */
 export const KeyboardTranslationContext = createContext<KeyboardTranslationScope>({
-  translation: { enabled: false, bottomClearance: 0 },
+  translation: { enabled: false, bottomClearance: 0, keyboardGap: 0 },
   measureAtRest: measureInWindow,
 });
 
diff --git a/packages/app/src/keyboard/shift/internal/policy.test.ts b/packages/app/src/keyboard/shift/internal/policy.test.ts
index 10192b1b88..6b278ed224 100644
--- a/packages/app/src/keyboard/shift/internal/policy.test.ts
+++ b/packages/app/src/keyboard/shift/internal/policy.test.ts
@@ -83,16 +83,46 @@ describe("resolveKeyboardShift", () => {
 
 describe("resolveKeyboardLift", () => {
   it("lifts a docked view by the whole shift", () => {
-    expect(resolveKeyboardLift({ shift: 302, enabled: true, bottomClearance: 0 })).toBe(302);
+    expect(
+      resolveKeyboardLift({ shift: 302, enabled: true, bottomClearance: 0, keyboardGap: 0 }),
+    ).toBe(302);
   });
 
   it("lets the keyboard fill a centered form's clearance before lifting it", () => {
-    expect(resolveKeyboardLift({ shift: 403, enabled: true, bottomClearance: 267 })).toBe(136);
-    expect(resolveKeyboardLift({ shift: 403, enabled: true, bottomClearance: 455 })).toBe(0);
+    expect(
+      resolveKeyboardLift({ shift: 403, enabled: true, bottomClearance: 267, keyboardGap: 0 }),
+    ).toBe(136);
+    expect(
+      resolveKeyboardLift({ shift: 403, enabled: true, bottomClearance: 455, keyboardGap: 0 }),
+    ).toBe(0);
+  });
+
+  it("rises a docked composer's gap beyond the keyboard overlap, never at rest", () => {
+    const docked = { enabled: true, bottomClearance: 0, keyboardGap: 16 };
+    expect(resolveKeyboardLift({ ...docked, shift: 0 })).toBe(0);
+    expect(resolveKeyboardLift({ ...docked, shift: 8 })).toBe(16);
+    expect(resolveKeyboardLift({ ...docked, shift: 276 })).toBe(292);
+  });
+
+  it("measures the shift from the window's bottom clearance, not the rectangular inset", () => {
+    // iPhone Duo outer screen: the bar guide rests 24pt up where safeAreaInsets reports 34.
+    const shift = resolveKeyboardShift({
+      rawKeyboardHeight: 300,
+      keyboardProgress: 1,
+      bottomInset: 24,
+      isIos: true,
+      iosMinHeight: 120,
+    });
+    expect(shift).toBe(276);
+    const lift = resolveKeyboardLift({ shift, enabled: true, bottomClearance: 0, keyboardGap: 16 });
+    const restingComposerBottom = 24;
+    expect(restingComposerBottom + lift - 300).toBe(16);
   });
 
   it("keeps a disabled view in place", () => {
-    expect(resolveKeyboardLift({ shift: 302, enabled: false, bottomClearance: 0 })).toBe(0);
+    expect(
+      resolveKeyboardLift({ shift: 302, enabled: false, bottomClearance: 0, keyboardGap: 0 }),
+    ).toBe(0);
   });
 });
 
diff --git a/packages/app/src/keyboard/shift/internal/policy.ts b/packages/app/src/keyboard/shift/internal/policy.ts
index c7d79bd9fa..3cd290fd94 100644
--- a/packages/app/src/keyboard/shift/internal/policy.ts
+++ b/packages/app/src/keyboard/shift/internal/policy.ts
@@ -37,9 +37,14 @@ export function resolveKeyboardLift(input: {
   shift: number;
   enabled: boolean;
   bottomClearance: number;
+  keyboardGap: number;
 }): number {
   "worklet";
-  return input.enabled ? Math.max(0, input.shift - input.bottomClearance) : 0;
+  if (!input.enabled) return 0;
+  // The gap opens over the shift's first points, so the view never rises at rest.
+  return (
+    Math.max(0, input.shift - input.bottomClearance) + Math.min(input.keyboardGap, input.shift)
+  );
 }
 
 export function shouldReconcileHiddenKeyboardEnd(input: {
diff --git a/packages/app/src/keyboard/shift/internal/translate.android.tsx b/packages/app/src/keyboard/shift/internal/translate.android.tsx
index cec2f0fcfd..5766c001ac 100644
--- a/packages/app/src/keyboard/shift/internal/translate.android.tsx
+++ b/packages/app/src/keyboard/shift/internal/translate.android.tsx
@@ -10,18 +10,27 @@ interface KeyboardTranslateViewProps extends ViewProps {
   enabled?: boolean;
   /** Space below the view's resting position that the keyboard may fill before the view moves. */
   bottomClearance?: number;
+  /**
+   * Distance the view rises beyond the keyboard's overlap of the safe area, so content
+   * resting on the safe-area boundary keeps this gap above the open keyboard.
+   */
+  keyboardGap?: number;
 }
 
 export function KeyboardTranslateView({
   children,
   enabled = true,
   bottomClearance = 0,
+  keyboardGap = 0,
   style,
   ...props
 }: KeyboardTranslateViewProps) {
   const { shift } = useKeyboardShift();
   const frameRef = useRef<View>(null);
-  const translation = useMemo(() => ({ enabled, bottomClearance }), [bottomClearance, enabled]);
+  const translation = useMemo(
+    () => ({ enabled, bottomClearance, keyboardGap }),
+    [bottomClearance, enabled, keyboardGap],
+  );
   const scope = useKeyboardTranslationScope(frameRef, translation);
   const keyboardStyle = useAnimatedStyle(() => ({
     transform: [{ translateY: -resolveKeyboardLift({ shift: shift.value, ...translation }) }],
diff --git a/packages/app/src/keyboard/shift/internal/translate.ios.tsx b/packages/app/src/keyboard/shift/internal/translate.ios.tsx
index 8628ba8b8c..5b5f378e0d 100644
--- a/packages/app/src/keyboard/shift/internal/translate.ios.tsx
+++ b/packages/app/src/keyboard/shift/internal/translate.ios.tsx
@@ -10,30 +10,40 @@ interface KeyboardTranslateViewProps extends ViewProps {
   enabled?: boolean;
   /** Space below the view's resting position that the keyboard may fill before the view moves. */
   bottomClearance?: number;
+  /**
+   * Distance the view rises beyond the keyboard's overlap of the safe area, so content
+   * resting on the safe-area boundary keeps this gap above the open keyboard.
+   */
+  keyboardGap?: number;
 }
 
 export function KeyboardTranslateView({
   children,
   enabled = true,
   bottomClearance = 0,
+  keyboardGap = 0,
   style,
   ...props
 }: KeyboardTranslateViewProps) {
   const insets = useSafeAreaInsets();
   const { height, progress } = useKeyboardAnimation();
-  const translateY = useMemo(
-    () =>
-      Animated.add(
-        Animated.add(height, Animated.multiply(progress, insets.bottom)),
-        bottomClearance,
-      ).interpolate({
-        inputRange: [-1, 0],
-        outputRange: [-1, 0],
-        extrapolateLeft: "extend",
-        extrapolateRight: "clamp",
-      }),
-    [bottomClearance, height, insets.bottom, progress],
-  );
+  // Mirrors resolveKeyboardLift on the native driver: `overlap` is the negated shift.
+  const translateY = useMemo(() => {
+    const overlap = Animated.add(height, Animated.multiply(progress, insets.bottom));
+    const lift = Animated.add(overlap, bottomClearance).interpolate({
+      inputRange: [-1, 0],
+      outputRange: [-1, 0],
+      extrapolateLeft: "extend",
+      extrapolateRight: "clamp",
+    });
+    if (!(keyboardGap > 0)) return lift;
+    const gap = overlap.interpolate({
+      inputRange: [-keyboardGap, 0],
+      outputRange: [-keyboardGap, 0],
+      extrapolate: "clamp",
+    });
+    return Animated.add(lift, gap);
+  }, [bottomClearance, height, insets.bottom, keyboardGap, progress]);
   // Fullscreen resizes this view while disabling translation. iOS Fabric can
   // reapply its previous transform during that layout commit. Keep the graph
   // attached and apply the mode on the native animation frame; a static zero or
@@ -57,7 +67,10 @@ export function KeyboardTranslateView({
   );
 
   const frameRef = useRef<View>(null);
-  const translation = useMemo(() => ({ enabled, bottomClearance }), [bottomClearance, enabled]);
+  const translation = useMemo(
+    () => ({ enabled, bottomClearance, keyboardGap }),
+    [bottomClearance, enabled, keyboardGap],
+  );
   const scope = useKeyboardTranslationScope(frameRef, translation);
 
   return (
diff --git a/packages/app/src/keyboard/shift/internal/translate.tsx b/packages/app/src/keyboard/shift/internal/translate.tsx
index 6a0506c301..b04613d495 100644
--- a/packages/app/src/keyboard/shift/internal/translate.tsx
+++ b/packages/app/src/keyboard/shift/internal/translate.tsx
@@ -5,12 +5,14 @@ interface KeyboardTranslateViewProps extends ViewProps {
   children: ReactNode;
   enabled?: boolean;
   bottomClearance?: number;
+  keyboardGap?: number;
 }
 
 export function KeyboardTranslateView({
   children,
   enabled: _enabled,
   bottomClearance: _bottomClearance,
+  keyboardGap: _keyboardGap,
   ...props
 }: KeyboardTranslateViewProps) {
   return <View {...props}>{children}</View>;
diff --git a/packages/app/src/screens/new-workspace/import-session-button.tsx b/packages/app/src/screens/new-workspace/import-session-button.tsx
index 3114d7bd79..331e274882 100644
--- a/packages/app/src/screens/new-workspace/import-session-button.tsx
+++ b/packages/app/src/screens/new-workspace/import-session-button.tsx
@@ -33,11 +33,12 @@ export function ImportSessionButton({
 }
 
 const styles = StyleSheet.create((theme) => ({
-  // The composer sits spacing[4] in from the dock and leaves spacing[4] below itself; the pill's
-  // border lines up with the composer's border.
+  // The composer sits spacing[4] in from the dock; the pill's border lines up with the
+  // composer's border, spacing[4] below it.
   wide: {
     alignItems: "flex-start",
     paddingHorizontal: theme.spacing[4],
+    paddingTop: theme.spacing[4],
   },
   pill: {
     borderRadius: theme.borderRadius.full,
diff --git a/packages/app/src/window-layout/index.ios.tsx b/packages/app/src/window-layout/index.ios.tsx
index 237c9c8114..507133528e 100644
--- a/packages/app/src/window-layout/index.ios.tsx
+++ b/packages/app/src/window-layout/index.ios.tsx
@@ -1,8 +1,9 @@
-import { useCallback, useState, type ReactNode } from "react";
+import { useCallback, useMemo, useState, type ReactNode } from "react";
 import { StyleSheet, View, type NativeSyntheticEvent, type ViewProps } from "react-native";
 import { requireNativeViewManager } from "expo-modules-core";
-import { WindowLayoutContext } from "./context";
-import type { WindowLayout } from "./model";
+import { SafeAreaInsetsContext, useSafeAreaInsets } from "react-native-safe-area-context";
+import { WindowLayoutContext, useWindowLayout } from "./context";
+import { resolveSafeAreaInsets, type WindowLayout } from "./model";
 
 export { useWindowLayout } from "./context";
 export { WindowLayoutActions, WindowLayoutActionsHost } from "./actions";
@@ -34,10 +35,18 @@ export function WindowLayoutProvider({ children }: { children: ReactNode }) {
           style={StyleSheet.absoluteFill}
           onGeometryChange={onGeometryChange}
         />
-        {children}
+        <WindowSafeAreaInsets>{children}</WindowSafeAreaInsets>
       </View>
     </WindowLayoutContext.Provider>
   );
 }
 
+/** The one bottom inset every descendant reads through `useSafeAreaInsets()`. */
+function WindowSafeAreaInsets({ children }: { children: ReactNode }) {
+  const systemInsets = useSafeAreaInsets();
+  const layout = useWindowLayout();
+  const insets = useMemo(() => resolveSafeAreaInsets(systemInsets, layout), [systemInsets, layout]);
+  return <SafeAreaInsetsContext.Provider value={insets}>{children}</SafeAreaInsetsContext.Provider>;
+}
+
 const styles = StyleSheet.create({ root: { flex: 1 } });
diff --git a/packages/app/src/window-layout/model.test.ts b/packages/app/src/window-layout/model.test.ts
new file mode 100644
index 0000000000..e363d4313a
--- /dev/null
+++ b/packages/app/src/window-layout/model.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { resolveSafeAreaInsets, type WindowLayout } from "./model";
+
+const systemInsets = { top: 59, right: 0, bottom: 34, left: 0 };
+
+function layout(bottomClearance: number | null | undefined): WindowLayout {
+  return {
+    bounds: { x: 0, y: 0, width: 402, height: 874 },
+    verticalBarEdge: "none",
+    verticalBar: null,
+    bottomClearance,
+    divisions: [],
+  };
+}
+
+describe("resolveSafeAreaInsets", () => {
+  it("replaces only the bottom with the measured bar clearance", () => {
+    expect(resolveSafeAreaInsets(systemInsets, layout(24))).toEqual({
+      ...systemInsets,
+      bottom: 24,
+    });
+  });
+
+  it("keeps a measured zero instead of falling back to the system inset", () => {
+    expect(resolveSafeAreaInsets(systemInsets, layout(0)).bottom).toBe(0);
+  });
+
+  it.each([null, undefined])("leaves system insets alone without a clearance (%s)", (value) => {
+    expect(resolveSafeAreaInsets(systemInsets, layout(value))).toBe(systemInsets);
+  });
+
+  it("leaves system insets alone before the native layout arrives", () => {
+    expect(resolveSafeAreaInsets(systemInsets, null)).toBe(systemInsets);
+  });
+});
diff --git a/packages/app/src/window-layout/model.ts b/packages/app/src/window-layout/model.ts
index 3e8d5b82ec..d2ba0de709 100644
--- a/packages/app/src/window-layout/model.ts
+++ b/packages/app/src/window-layout/model.ts
@@ -9,9 +9,25 @@ export interface WindowLayout {
   bounds: WindowLayoutRect;
   verticalBarEdge: "none" | "leading" | "trailing";
   verticalBar: WindowLayoutRect | null;
+  /**
+   * Points from the window's bottom edge to where a bottom bar rests, or null where
+   * the system has no bottom bar guide. Zero is a measured value.
+   */
+  bottomClearance?: number | null;
   divisions: WindowLayoutRect[];
 }
 
+/** The window's measured bottom clearance replaces the rectangular safe-area bottom. */
+export function resolveSafeAreaInsets<Insets extends { bottom: number }>(
+  systemInsets: Insets,
+  layout: WindowLayout | null,
+): Insets {
+  const clearance = layout?.bottomClearance;
+  return typeof clearance === "number" && clearance !== systemInsets.bottom
+    ? { ...systemInsets, bottom: clearance }
+    : systemInsets;
+}
+
 export interface DesktopDivisionLayout {
   sidebarWidth: number;
   gap: number;

From 3ed57e9dd72df4927b08f16859eaf8d4d2d70ac2 Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Thu, 5 Nov 2026 22:30:14 +0700
Subject: [PATCH 25/29] Change a worktree workspace base from Changes (#8642)

Change a worktree workspace's base from the Changes pane. The choice persists and diffs, counts, commits and Git actions follow it.

Supersedes #6872.

Co-authored-by: Tianyu Yang <yangtianyu.cl@bytedance.com>
---
 docs/data-model.md                            |   6 +-
 packages/app/e2e/browser/changes-pane.spec.ts | 126 ++++++++++++
 packages/app/src/git/checkout-status-cache.ts |  11 +-
 packages/app/src/git/diff-pane.tsx            |  29 +++
 packages/app/src/git/policy.test.ts           |  84 +++++++-
 packages/app/src/git/policy.ts                |  28 ++-
 packages/app/src/git/use-actions.tsx          |  15 +-
 .../src/git/workspace-base-branch-picker.tsx  | 179 ++++++++++++++++++
 packages/app/src/i18n/resources/ar.ts         |   3 +
 packages/app/src/i18n/resources/en.ts         |   3 +
 packages/app/src/i18n/resources/es.ts         |   3 +
 packages/app/src/i18n/resources/fr.ts         |   3 +
 packages/app/src/i18n/resources/ja.ts         |   3 +
 packages/app/src/i18n/resources/ko.ts         |   3 +
 packages/app/src/i18n/resources/pt-BR.ts      |   3 +
 packages/app/src/i18n/resources/ru.ts         |   3 +
 packages/app/src/i18n/resources/zh-CN.ts      |   3 +
 packages/client/src/daemon-client.ts          |  19 +-
 packages/client/src/index.test.ts             |  23 +++
 packages/client/src/index.ts                  |   6 +
 packages/protocol/src/messages.ts             |  25 +++
 .../protocol/src/messages.wire-compat.test.ts |  57 ++++++
 .../authorization/operation-permissions.ts    |   2 +
 .../src/server/checkout-diff-manager.ts       |   1 +
 .../src/server/checkout/status-projection.ts  |   2 +
 .../server/git-metadata-event-rules.test.ts   |   1 +
 .../src/server/git-metadata-event-rules.ts    |   2 +-
 packages/server/src/server/session.ts         |  55 ++++++
 .../session/checkout/checkout-session.ts      |   3 +-
 .../session/workspace-base-branch/service.ts  | 104 ++++++++++
 .../workspace-provisioning-service.test.ts    |  61 ++++++
 .../workspace-provisioning-service.ts         |  42 ++--
 .../server/src/server/websocket-server.ts     |  15 +-
 ...orkspace-archive-record-scoped.e2e.test.ts | 113 +++++++++++
 .../src/server/workspace-git-service.test.ts  |  29 +++
 .../src/server/workspace-git-service.ts       |  16 +-
 .../src/server/workspace-registry-model.ts    |   2 +-
 .../server/src/server/workspace-registry.ts   |   4 +-
 .../server/src/utils/checkout-git.test.ts     |  58 ++++++
 packages/server/src/utils/checkout-git.ts     |  76 ++++++--
 .../server/src/utils/worktree-metadata.ts     |  17 +-
 41 files changed, 1192 insertions(+), 46 deletions(-)
 create mode 100644 packages/app/src/git/workspace-base-branch-picker.tsx
 create mode 100644 packages/server/src/server/session/workspace-base-branch/service.ts

diff --git a/docs/data-model.md b/docs/data-model.md
index dc65096b66..38c13b63df 100644
--- a/docs/data-model.md
+++ b/docs/data-model.md
@@ -26,6 +26,10 @@ checkout root. They intentionally differ for an exact subproject inside a worktr
 restore, branch auto-name, and descriptor flows consume those persisted facts rather than
 rediscovering ownership from a directory that may already be gone. Reconciliation may refresh
 mutable placement facts, but never changes `projectId`, `cwd`, `displayName`, or `baseBranch`.
+An explicit base selection is stored in the checkout's Git-directory Paseo metadata and
+mirrored to `baseBranch` in every workspace record sharing that checkout. The record keeps
+recovery possible after the checkout metadata is deleted. A newly opened workspace inherits
+the checkout's selected base; separate worktrees keep separate bases.
 Workspace archive runs lifecycle teardown from the exact `cwd` but removes only the backing
 `worktreeRoot` after its last active reference disappears. Worktree recovery recreates that backing
 checkout from `mainRepoRoot`, then restores the relative path from `worktreeRoot` to `cwd`.
@@ -470,7 +474,7 @@ Array of workspace records. A workspace is a specific working directory within a
 | `title`                        | `string \| null`                                             | User-set name override layered over `displayName`. Null means "use `displayName`".                                                                                                            |
 | `branch`                       | `string \| null`                                             | The current Git branch for git-backed workspaces. Separate from `displayName`/`title`; a background branch refresh never rewrites the name.                                                   |
 | `worktreeRoot`                 | `string \| null`                                             | Backing checkout/worktree root. May differ from `cwd` for exact subprojects and remains persisted after the worktree is deleted so restore can reproduce the placement.                       |
-| `baseBranch`                   | `string \| null`                                             | Comparison base retained across archive and restore. Branch-off creation stores the resolved ref; legacy and PR-checkout records hold a bare name. Null means no recorded base.               |
+| `baseBranch`                   | `string \| null`                                             | Current base retained across archive and restore. Explicit selections and branch-off creation store exact refs; older records may store branch names. Null means no recorded base.            |
 | `isPaseoOwnedWorktree`         | `boolean`                                                    | Whether Paseo owns and may remove/recreate the backing `worktreeRoot`                                                                                                                         |
 | `mainRepoRoot`                 | `string \| null`                                             | Main repository root for worktree checkouts, independent of both exact `cwd` and backing `worktreeRoot`                                                                                       |
 | `createdAt`                    | `string` (ISO 8601)                                          |                                                                                                                                                                                               |
diff --git a/packages/app/e2e/browser/changes-pane.spec.ts b/packages/app/e2e/browser/changes-pane.spec.ts
index aa884c66e9..a233567b5f 100644
--- a/packages/app/e2e/browser/changes-pane.spec.ts
+++ b/packages/app/e2e/browser/changes-pane.spec.ts
@@ -323,6 +323,110 @@ test("All changes combines committed and pending edits and preserves an unfinish
   });
 });
 
+test("Changes selects exact local and remote bases and retains the selection after reload", async ({
+  page,
+}, testInfo) => {
+  const workspace = await createWorktreeWithCommittedDiff();
+  execFileSync("git", ["branch", "release"], { cwd: workspace.repoPath });
+  execFileSync("git", ["update-ref", "refs/remotes/upstream/release", "main"], {
+    cwd: workspace.repoPath,
+  });
+  const head = execFileSync("git", ["rev-parse", "HEAD"], { cwd: workspace.repoPath }).toString();
+  await openWorkspaceChangesSurface(page, workspace);
+  const tree = page.getByTestId("changes-tree-panel").filter({ visible: true });
+  const picker = tree.getByTestId("workspace-base-branch-trigger");
+  await expect(picker).toBeVisible();
+  await picker.click();
+  await expect(page.getByRole("button", { name: "release", exact: true })).toBeVisible();
+  await page.screenshot({ path: testInfo.outputPath("base-picker.png") });
+  await page.getByRole("button", { name: "release", exact: true }).click();
+  await expect(picker).toContainText("release");
+  await expect(tree.getByText("No changes to display", { exact: true })).toBeVisible();
+  await picker.click();
+  await page.getByRole("button", { name: "upstream/release", exact: true }).click();
+  await expect(picker).toContainText("upstream/release");
+  await expect(tree.getByText("committed-only.ts", { exact: true })).toBeVisible();
+  await page.screenshot({ path: testInfo.outputPath("base-selected.png") });
+  await page.reload();
+  await waitForWorkspaceTabsVisible(page);
+  await expect(picker).toContainText("upstream/release");
+  expect(execFileSync("git", ["rev-parse", "HEAD"], { cwd: workspace.repoPath }).toString()).toBe(
+    head,
+  );
+});
+
+test("Changes lets a compact workspace change its base in a sheet", async ({ page }, testInfo) => {
+  const workspace = await createWorktreeWithCommittedDiff();
+  execFileSync("git", ["branch", "release"], { cwd: workspace.repoPath });
+  await openCompactChanges(page, workspace);
+  const picker = page.getByRole("button", { name: "Change base" }).filter({ visible: true });
+  await picker.click();
+  await expect(page.getByText("Change base", { exact: true })).toBeVisible();
+  const release = page.getByRole("button", { name: "release", exact: true });
+  await expect(release).toBeVisible();
+  await page.screenshot({ path: testInfo.outputPath("compact-base-picker.png") });
+  await release.click();
+  await expect(picker).toContainText("release");
+  await page.screenshot({ path: testInfo.outputPath("compact-base-selected.png") });
+});
+
+test("Changes shows a failed base selection and lets the user retry", async ({ page }) => {
+  const workspace = await createWorktreeWithCommittedDiff();
+  execFileSync("git", ["branch", "release"], { cwd: workspace.repoPath });
+  await openWorkspaceChangesSurface(page, workspace);
+  const picker = page
+    .getByTestId("workspace-base-branch-trigger")
+    .filter({ visible: true })
+    .first();
+  await picker.click();
+  const option = page.getByRole("button", { name: "release", exact: true });
+  await expect(option).toBeVisible();
+  execFileSync("git", ["branch", "-D", "release"], { cwd: workspace.repoPath });
+  await option.click();
+  await expect(page.getByTestId("workspace-base-branch-error")).toContainText(
+    "Base branch not found",
+  );
+  await expect(picker).toContainText("main");
+  execFileSync("git", ["branch", "release"], { cwd: workspace.repoPath });
+  await option.click();
+  await expect(page.getByTestId("workspace-base-branch-error")).toHaveCount(0);
+  await expect(picker).toContainText("release");
+});
+
+test("Changes shows the base as text on a host without the base-branch capability", async ({
+  page,
+}) => {
+  let baseRequests = 0;
+  await page.routeWebSocket(daemonWsRoutePattern(), (browser) => {
+    const server = browser.connectToServer();
+    browser.onMessage((frame) => {
+      if (typeof frame === "string") {
+        const envelope = JSON.parse(frame) as { message?: { type?: string } };
+        if (envelope.message?.type === "workspace.base_branch.set.request") baseRequests += 1;
+      }
+      server.send(frame);
+    });
+    server.onMessage((frame) => {
+      if (typeof frame === "string") {
+        const envelope = JSON.parse(frame) as {
+          message?: { payload?: { status?: string; features?: Record<string, unknown> } };
+        };
+        const payload = envelope.message?.payload;
+        if (payload?.status === "server_info" && payload.features) {
+          delete payload.features.workspaceBaseBranch;
+          browser.send(JSON.stringify(envelope));
+          return;
+        }
+      }
+      browser.send(frame);
+    });
+  });
+  const workspace = await createWorktreeWithCommittedDiff();
+  await openWorkspaceChangesSurface(page, workspace);
+  await expect(page.getByTestId("workspace-base-branch-trigger")).toHaveCount(0);
+  expect(baseRequests).toBe(0);
+});
+
 test("Changes keeps a manual comparison when checkout dirtiness changes", async ({ page }) => {
   const workspace = await createWorkspaceWithMountedTabDiff();
   await openWorkspaceChanges(page, workspace);
@@ -1657,6 +1761,28 @@ async function expectRenderedAddedLine(page: Page, contents: string): Promise<vo
   }).toPass({ timeout: 15_000 });
 }
 
+async function createWorktreeWithCommittedDiff(): Promise<DirtyWorkspace> {
+  const repo = await createTempGitRepo("changes-base-worktree-", {
+    files: [{ path: "tracked.ts", content: "export const tracked = 1;\n" }],
+  });
+  const client = await connectSeedClient();
+  cleanupTasks.push({
+    run: async () => {
+      await client.close();
+      await repo.cleanup();
+    },
+  });
+  const created = await client.createWorkspace({
+    source: { kind: "worktree", cwd: repo.path, worktreeSlug: "base-picker", baseBranch: "main" },
+  });
+  if (!created.workspace) throw new Error(created.error ?? "Failed to create worktree");
+  const cwd = created.workspace.workspaceDirectory;
+  await writeFile(path.join(cwd, "committed-only.ts"), "export const committed = true;\n");
+  execFileSync("git", ["add", "committed-only.ts"], { cwd });
+  execFileSync("git", ["commit", "-m", "Add committed-only file"], { cwd });
+  return { id: created.workspace.id, repoPath: cwd };
+}
+
 async function createWorkspaceWithCommittedDiff(): Promise<DirtyWorkspace> {
   const repo = await createTempGitRepo("changes-committed-", {
     files: [{ path: "tracked.ts", content: "export const tracked = 1;\n" }],
diff --git a/packages/app/src/git/checkout-status-cache.ts b/packages/app/src/git/checkout-status-cache.ts
index 4aaa650c70..7a20e98fa2 100644
--- a/packages/app/src/git/checkout-status-cache.ts
+++ b/packages/app/src/git/checkout-status-cache.ts
@@ -25,7 +25,7 @@ export async function fetchCheckoutStatus({
   serverId: string;
   cwd: string;
 }): Promise<CheckoutStatusPayload> {
-  const payload = await client.getCheckoutStatus(cwd);
+  const payload = normalizeCheckoutBaseRef(await client.getCheckoutStatus(cwd));
   return payload;
 }
 
@@ -56,7 +56,7 @@ export function applyCheckoutStatusUpdateFromEvent({
   serverId: string;
   message: CheckoutStatusUpdate;
 }): void {
-  const { payload } = message;
+  const payload = normalizeCheckoutBaseRef(message.payload);
   const prStatus = payload.prStatus
     ? normalizeCheckoutPrStatusPayload(payload.prStatus)
     : undefined;
@@ -88,6 +88,13 @@ export function applyCheckoutStatusUpdateFromEvent({
   }
 }
 
+function normalizeCheckoutBaseRef<T extends CheckoutStatusPayload>(payload: T): T {
+  // COMPAT(workspaceBaseBranch): hosts <= v0.11.2 only send the display ref; remove after 2027-10-14.
+  return !payload.isGit || payload.baseRefExact === undefined
+    ? payload
+    : { ...payload, baseRef: payload.baseRefExact };
+}
+
 // requestId changes on every emission and carries no PR state.
 function prStatusWithoutVolatileFields(
   prStatus: CheckoutPrStatusPayload,
diff --git a/packages/app/src/git/diff-pane.tsx b/packages/app/src/git/diff-pane.tsx
index 08e584b3cc..d4a7d43ea8 100644
--- a/packages/app/src/git/diff-pane.tsx
+++ b/packages/app/src/git/diff-pane.tsx
@@ -19,6 +19,7 @@ import type { Theme } from "@/styles/theme";
 import { useIsCompactFormFactor } from "@/constants/layout";
 import {
   AlignJustify,
+  ArrowRight,
   ChevronDown,
   Columns2,
   ExternalLink,
@@ -61,6 +62,7 @@ import { GitActionsSplitButton } from "@/git/actions-split-button";
 import type { GitActions } from "@/git/policy";
 import { BranchSwitcher } from "@/components/branch-switcher";
 import { useGitActions } from "@/git/use-actions";
+import { WorkspaceBaseBranchPicker } from "@/git/workspace-base-branch-picker";
 import { GIT_ACTION_ICONS } from "@/git/action-icons";
 import { buildForgeSignInCommand, getForgePresentation, type Forge } from "@/git/forge";
 import { parseGitRemoteLocation } from "@getpaseo/protocol/git-remote";
@@ -201,6 +203,7 @@ const foregroundMutedIconColorMapping = (theme: Theme) => ({ color: theme.colors
 
 const ThemedLoadingSpinner = withUnistyles(LoadingSpinner);
 const ThemedAlignJustify = withUnistyles(AlignJustify);
+const ThemedArrowRight = withUnistyles(ArrowRight);
 const ThemedColumns2 = withUnistyles(Columns2);
 const ThemedPilcrow = withUnistyles(Pilcrow);
 const ThemedWrapText = withUnistyles(WrapText);
@@ -470,6 +473,8 @@ interface ChangesPullRequestLinkModel extends Pick<PrHint, "forge" | "number" |
 }
 
 interface ChangesRepositoryToolbarModel {
+  baseRef: string | null;
+  isWorktree: boolean;
   branchName: string | null;
   cwd: string;
   gitActions: GitActions | null;
@@ -496,6 +501,8 @@ interface ChangesHeaderProps {
 }
 
 interface BuildChangesHeaderModelInput {
+  baseRef: string | null;
+  isWorktree: boolean;
   branchName: string | null;
   committedDescription?: string;
   compact: boolean;
@@ -519,6 +526,8 @@ function buildChangesHeaderModel(input: BuildChangesHeaderModelInput): {
 } {
   return {
     repository: {
+      baseRef: input.baseRef,
+      isWorktree: input.isWorktree,
       branchName: input.branchName,
       cwd: input.cwd,
       gitActions: input.compact ? input.gitActions : null,
@@ -629,6 +638,10 @@ function ChangesToolbarTrailing({ children }: { children: ReactNode }) {
   return <ToolbarControls style={styles.changesToolbarControls}>{children}</ToolbarControls>;
 }
 
+function isManagedWorktree(status: { isPaseoOwnedWorktree?: boolean } | null | undefined): boolean {
+  return status?.isPaseoOwnedWorktree === true;
+}
+
 function ChangesRepositoryToolbar({
   compact,
   model,
@@ -654,6 +667,18 @@ function ChangesRepositoryToolbar({
           isGitCheckout
           testID="changes-branch-switcher"
         />
+        {model.baseRef ? (
+          <>
+            <ThemedArrowRight size={14} uniProps={foregroundMutedIconColorMapping} />
+            <WorkspaceBaseBranchPicker
+              serverId={model.serverId}
+              workspaceId={model.workspaceId}
+              cwd={model.cwd}
+              baseRef={model.baseRef}
+              isWorktree={model.isWorktree}
+            />
+          </>
+        ) : null}
       </ChangesToolbarLeading>
       <ChangesToolbarTrailing>
         {model.pullRequest ? (
@@ -1904,6 +1929,8 @@ export function ChangesSurface({
   const changesHeaderModel = useMemo(
     () =>
       buildChangesHeaderModel({
+        baseRef: baseRef ?? null,
+        isWorktree: isManagedWorktree(status),
         branchName: currentBranchName,
         committedDescription: committedDiffDescription,
         compact: isMobile,
@@ -1921,6 +1948,8 @@ export function ChangesSurface({
         workspaceId,
       }),
     [
+      baseRef,
+      status,
       committedDiffDescription,
       currentBranchName,
       cwd,
diff --git a/packages/app/src/git/policy.test.ts b/packages/app/src/git/policy.test.ts
index efbd61efa6..34f6e93d1d 100644
--- a/packages/app/src/git/policy.test.ts
+++ b/packages/app/src/git/policy.test.ts
@@ -2,7 +2,13 @@ import { afterEach, describe, expect, it } from "vitest";
 import { CheckoutPrStatusSchema } from "@getpaseo/protocol/messages";
 import { i18n } from "@/i18n/i18next";
 
-import { actionsWithoutPrimary, buildGitActions, type BuildGitActionsInput } from "./policy";
+import {
+  actionsWithoutPrimary,
+  buildGitActions,
+  isCurrentBranchBase,
+  canMergeIntoLocalBase,
+  type BuildGitActionsInput,
+} from "./policy";
 import { deriveMergeCapability, type ForgeSpecificStatusFacts } from "./merge-capability";
 
 type GithubMergeFactsFixture = ForgeSpecificStatusFacts & {
@@ -72,6 +78,7 @@ function createInput(
     hasRemote: false,
     isPaseoOwnedWorktree: false,
     isOnBaseBranch: true,
+    canMergeLocally: true,
     hasUncommittedChanges: false,
     baseRefAvailable: true,
     baseRefLabel: "main",
@@ -208,6 +215,81 @@ describe("git-actions-policy", () => {
     ]);
   });
 
+  it("distinguishes exact local and remote base refs and retains legacy names", () => {
+    expect(isCurrentBranchBase("release", "refs/heads/release")).toBe(true);
+    expect(isCurrentBranchBase("release", "refs/remotes/origin/release")).toBe(false);
+    expect(isCurrentBranchBase("release", "release")).toBe(true);
+    expect(isCurrentBranchBase("release", "origin/release")).toBe(true);
+    expect(isCurrentBranchBase(null, "refs/heads/release")).toBe(false);
+    expect(canMergeIntoLocalBase("release", "refs/heads/release")).toBe(false);
+    expect(canMergeIntoLocalBase("feature", "refs/remotes/origin/release")).toBe(true);
+    expect(canMergeIntoLocalBase("release", "refs/remotes/upstream/release")).toBe(false);
+  });
+
+  it("offers local merge when the selected local base starts with origin slash", () => {
+    const actions = buildGitActions(
+      createInput({
+        isPaseoOwnedWorktree: true,
+        isOnBaseBranch: isCurrentBranchBase("release", "refs/heads/origin/release"),
+        canMergeLocally: canMergeIntoLocalBase("release", "refs/heads/origin/release"),
+        baseRefLabel: "origin/release",
+        aheadCount: 1,
+        shipDefault: "merge",
+      }),
+    );
+    expect(actions.primary?.id).toBe("merge-branch");
+  });
+
+  it("offers update but not local merge for a non-origin remote base", () => {
+    const actions = buildGitActions(
+      createInput({
+        isPaseoOwnedWorktree: true,
+        isOnBaseBranch: false,
+        canMergeLocally: canMergeIntoLocalBase("feature", "refs/remotes/upstream/release"),
+        baseRefLabel: "upstream/release",
+        aheadCount: 1,
+        behindBaseCount: 1,
+        aheadOfOrigin: null,
+        behindOfOrigin: null,
+        shipDefault: "merge",
+      }),
+    );
+    expect(actions.primary?.id).toBe("merge-from-base");
+    expect(actionsWithoutPrimary(actions).map((action) => action.id)).not.toContain("merge-branch");
+  });
+
+  it("does not offer merging into the current local branch when the remote base shares its name", () => {
+    const actions = buildGitActions(
+      createInput({
+        isPaseoOwnedWorktree: true,
+        isOnBaseBranch: false,
+        canMergeLocally: canMergeIntoLocalBase("release", "refs/remotes/origin/release"),
+        baseRefLabel: "release",
+        aheadCount: 1,
+        behindBaseCount: 1,
+        aheadOfOrigin: null,
+        behindOfOrigin: null,
+        shipDefault: "merge",
+      }),
+    );
+    expect(actions.primary?.id).toBe("merge-from-base");
+    expect(actionsWithoutPrimary(actions).map((action) => action.id)).not.toContain("merge-branch");
+  });
+
+  it("offers update from the same-named remote base when it is ahead", () => {
+    const actions = buildGitActions(
+      createInput({
+        isPaseoOwnedWorktree: true,
+        isOnBaseBranch: isCurrentBranchBase("release", "refs/remotes/origin/release"),
+        baseRefLabel: "release",
+        behindBaseCount: 1,
+        aheadOfOrigin: null,
+        behindOfOrigin: null,
+      }),
+    );
+    expect(actions.primary?.id).toBe("merge-from-base");
+  });
+
   it("drops a promoted merge action from the remaining menu actions", () => {
     const actions = buildGitActions(
       createInput({
diff --git a/packages/app/src/git/policy.ts b/packages/app/src/git/policy.ts
index 71d63eae37..9f18e65755 100644
--- a/packages/app/src/git/policy.ts
+++ b/packages/app/src/git/policy.ts
@@ -50,6 +50,29 @@ interface GitActionRuntimeState {
   handler: () => void;
 }
 
+export function isCurrentBranchBase(
+  currentBranch: string | null | undefined,
+  baseRef: string | null | undefined,
+): boolean {
+  if (!currentBranch || !baseRef) return false;
+  if (baseRef.startsWith("refs/heads/")) return baseRef === `refs/heads/${currentBranch}`;
+  if (baseRef.startsWith("refs/")) return false;
+  // Older hosts send a display name, which cannot distinguish a local ref from its remote.
+  return currentBranch === baseRef.replace(/^origin\//, "");
+}
+
+export function canMergeIntoLocalBase(
+  currentBranch: string | null | undefined,
+  baseRef: string | null | undefined,
+): boolean {
+  if (!currentBranch || !baseRef) return false;
+  if (baseRef.startsWith("refs/remotes/") && !baseRef.startsWith("refs/remotes/origin/")) {
+    return false;
+  }
+  const localTarget = baseRef.replace(/^(?:refs\/heads\/|refs\/remotes\/origin\/|origin\/)/, "");
+  return currentBranch !== localTarget;
+}
+
 export interface BuildGitActionsInput {
   isGit: boolean;
   githubFeaturesEnabled: boolean;
@@ -68,6 +91,7 @@ export interface BuildGitActionsInput {
   hasRemote: boolean;
   isPaseoOwnedWorktree: boolean;
   isOnBaseBranch: boolean;
+  canMergeLocally: boolean;
   hasUncommittedChanges: boolean;
   baseRefAvailable: boolean;
   baseRefLabel: string;
@@ -349,7 +373,7 @@ function getPrimaryActionId(input: BuildGitActionsInput): GitActionId | null {
   if (input.shipDefault === "pr" && canUsePullRequestActionAsShipDefault(input)) {
     return "pr";
   }
-  if (!input.isOnBaseBranch && input.aheadCount > 0) {
+  if (!input.isOnBaseBranch && input.canMergeLocally && input.aheadCount > 0) {
     return "merge-branch";
   }
   if (!input.isOnBaseBranch && canMergeFromBase(input)) {
@@ -380,7 +404,7 @@ function getPullRequestActionIds(filter: {
 function getFeatureActionIds(input: BuildGitActionsInput): GitActionId[] {
   return [
     "merge-from-base",
-    "merge-branch",
+    ...(input.canMergeLocally ? (["merge-branch"] as const) : []),
     ...getPullRequestActionIds({ roles: ["status", "direct", "auto"], input }),
   ];
 }
diff --git a/packages/app/src/git/use-actions.tsx b/packages/app/src/git/use-actions.tsx
index 05e65a21a5..13f7587623 100644
--- a/packages/app/src/git/use-actions.tsx
+++ b/packages/app/src/git/use-actions.tsx
@@ -12,6 +12,8 @@ import { type CheckoutStatusPayload, useCheckoutStatusQuery } from "@/git/use-st
 import { type CheckoutPrStatusPayload, useCheckoutPrStatusQuery } from "@/git/use-pr-status-query";
 import {
   buildGitActions,
+  isCurrentBranchBase,
+  canMergeIntoLocalBase,
   narrowPullRequestState,
   type BuildGitActionsInput,
   type GitAction,
@@ -116,7 +118,7 @@ interface DeriveGitActionsStateArgs {
   hasUncommittedChanges: boolean;
   postShipArchiveSuggested: boolean;
   isStatusLoading: boolean;
-  baseRefLabel: string;
+  baseRef: string | undefined;
 }
 
 interface DerivedGitActionsState {
@@ -129,6 +131,7 @@ interface DerivedGitActionsState {
   hasRemote: boolean;
   isPaseoOwnedWorktree: boolean;
   isOnBaseBranch: boolean;
+  canMergeLocally: boolean;
   shouldPromoteArchive: boolean;
 }
 
@@ -167,7 +170,7 @@ function deriveGitActionsState(args: DeriveGitActionsStateArgs): DerivedGitActio
     hasUncommittedChanges,
     postShipArchiveSuggested,
     isStatusLoading,
-    baseRefLabel,
+    baseRef,
   } = args;
   const actionsDisabled = !isGit || Boolean(status?.error) || isStatusLoading;
   const isPaseoOwnedWorktree = gitStatus?.isPaseoOwnedWorktree ?? false;
@@ -178,7 +181,8 @@ function deriveGitActionsState(args: DeriveGitActionsStateArgs): DerivedGitActio
     hasPullRequest: Boolean(prStatus?.url),
     hasRemote: gitStatus?.hasRemote ?? false,
     isPaseoOwnedWorktree,
-    isOnBaseBranch: gitStatus?.currentBranch === baseRefLabel,
+    isOnBaseBranch: isCurrentBranchBase(gitStatus?.currentBranch, baseRef),
+    canMergeLocally: canMergeIntoLocalBase(gitStatus?.currentBranch, baseRef),
     shouldPromoteArchive: computeShouldPromoteArchive({
       hasUncommittedChanges,
       postShipArchiveSuggested,
@@ -653,7 +657,7 @@ export function useGitActions({ serverId, cwd, icons }: UseGitActionsInput): Use
     hasUncommittedChanges,
     postShipArchiveSuggested,
     isStatusLoading,
-    baseRefLabel,
+    baseRef,
   });
   const {
     actionsDisabled,
@@ -665,6 +669,7 @@ export function useGitActions({ serverId, cwd, icons }: UseGitActionsInput): Use
     hasRemote,
     isPaseoOwnedWorktree,
     isOnBaseBranch,
+    canMergeLocally,
     shouldPromoteArchive,
   } = derived;
 
@@ -695,6 +700,7 @@ export function useGitActions({ serverId, cwd, icons }: UseGitActionsInput): Use
       hasRemote,
       isPaseoOwnedWorktree,
       isOnBaseBranch,
+      canMergeLocally,
       hasUncommittedChanges,
       baseRefAvailable: Boolean(baseRef),
       baseRefLabel,
@@ -812,6 +818,7 @@ export function useGitActions({ serverId, cwd, icons }: UseGitActionsInput): Use
     behindBaseCount,
     isPaseoOwnedWorktree,
     isOnBaseBranch,
+    canMergeLocally,
     githubFeaturesEnabled,
     forge,
     githubAutoMergeActionsEnabled,
diff --git a/packages/app/src/git/workspace-base-branch-picker.tsx b/packages/app/src/git/workspace-base-branch-picker.tsx
new file mode 100644
index 0000000000..cf260e90d6
--- /dev/null
+++ b/packages/app/src/git/workspace-base-branch-picker.tsx
@@ -0,0 +1,179 @@
+import { useCallback, useMemo, useRef, useState } from "react";
+import { Text, View } from "react-native";
+import { GitBranch } from "lucide-react-native";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useFetchQuery } from "@/data/query";
+import { useTranslation } from "react-i18next";
+import { StyleSheet, withUnistyles } from "react-native-unistyles";
+import type { Theme } from "@/styles/theme";
+import { Combobox, ComboboxItem, type ComboboxProps } from "@/components/ui/combobox";
+import { ToolbarLabelSelectTrigger } from "@/components/ui/toolbar-label-trigger";
+import { LoadingSpinner } from "@/components/ui/loading-spinner";
+import { Button } from "@/components/ui/button";
+import { useHostRuntimeClient, useHostRuntimeIsConnected } from "@/runtime/host-runtime";
+import { useSessionStore } from "@/stores/session-store";
+import { useDebouncedValue } from "@/hooks/use-debounced-value";
+import { invalidateCheckoutGitQueriesForClient } from "./query-keys";
+
+interface Props {
+  serverId: string;
+  workspaceId?: string | null;
+  cwd: string;
+  baseRef: string;
+  isWorktree: boolean;
+}
+
+const ThemedLoadingSpinner = withUnistyles(LoadingSpinner);
+const ThemedGitBranch = withUnistyles(GitBranch);
+const mutedColor = (theme: Theme) => ({ color: theme.colors.foregroundMuted });
+
+function refLabel(ref: string): string {
+  return ref.replace(/^refs\/(heads|remotes)\//, "");
+}
+
+export function WorkspaceBaseBranchPicker({
+  serverId,
+  workspaceId,
+  cwd,
+  baseRef,
+  isWorktree,
+}: Props) {
+  const { t } = useTranslation();
+  const client = useHostRuntimeClient(serverId);
+  const connected = useHostRuntimeIsConnected(serverId);
+  // COMPAT(workspaceBaseBranch): added after v0.11.2, remove gate after 2027-10-14.
+  const supported = useSessionStore(
+    (state) => state.sessions[serverId]?.serverInfo?.features?.workspaceBaseBranch === true,
+  );
+  const queryClient = useQueryClient();
+  const anchorRef = useRef<View>(null);
+  const [open, setOpen] = useState(false);
+  const [search, setSearch] = useState("");
+  const query = useDebouncedValue(search, 200);
+  const branches = useFetchQuery({
+    queryKey: ["workspaceBaseBranches", serverId, cwd, query],
+    queryFn: async () => {
+      if (!client) throw new Error(t("common.errors.daemonClientUnavailable"));
+      const result = await client.getBranchSuggestions({
+        cwd,
+        refMode: "exact",
+        query,
+        limit: 200,
+      });
+      if (result.error) throw new Error(result.error);
+      return result.branches;
+    },
+    enabled: open && supported && connected && Boolean(client),
+    retry: false,
+    dataShape: "value",
+    staleTimeMs: 0,
+  });
+  const mutation = useMutation({
+    mutationFn: async (ref: string) => {
+      if (!client || !workspaceId) throw new Error(t("common.errors.daemonClientUnavailable"));
+      return client.setWorkspaceBaseBranch({ workspaceId, baseRef: ref });
+    },
+    onSuccess: async () => {
+      setOpen(false);
+      await invalidateCheckoutGitQueriesForClient(queryClient, { serverId, cwd });
+    },
+  });
+  const options = useMemo(
+    () => (branches.data ?? []).map((ref) => ({ id: ref, label: refLabel(ref) })),
+    [branches.data],
+  );
+  const error = mutation.error ?? branches.error;
+  const title = t("workspace.git.diff.baseBranch.title");
+  const label = refLabel(baseRef).replace(/^origin\//, "");
+
+  const { reset, mutate, isPending } = mutation;
+  const { refetch, isError } = branches;
+  const handleOpen = useCallback(() => {
+    reset();
+    setSearch("");
+    setOpen(true);
+  }, [reset]);
+  const handleSelect = useCallback(
+    (ref: string) => {
+      if (!isPending) mutate(ref);
+    },
+    [isPending, mutate],
+  );
+  const handleRetry = useCallback(() => {
+    void refetch();
+  }, [refetch]);
+  const branchIcon = useMemo(() => <ThemedGitBranch size={14} uniProps={mutedColor} />, []);
+  const renderOption = useCallback<NonNullable<ComboboxProps["renderOption"]>>(
+    ({ option, selected, active, onPress }) => (
+      <ComboboxItem
+        label={option.label}
+        leadingSlot={branchIcon}
+        selected={selected}
+        active={active}
+        onPress={onPress}
+        disabled={isPending}
+      />
+    ),
+    [isPending, branchIcon],
+  );
+  const footer = useMemo(
+    () => (
+      <View style={styles.footer}>
+        {isPending ? <ThemedLoadingSpinner size="small" uniProps={mutedColor} /> : null}
+        {error ? (
+          <Text accessibilityRole="alert" testID="workspace-base-branch-error" style={styles.error}>
+            {error.message}
+          </Text>
+        ) : null}
+        {isError ? (
+          <Button variant="outline" onPress={handleRetry}>
+            {t("common.actions.retry")}
+          </Button>
+        ) : null}
+      </View>
+    ),
+    [t, isPending, error, isError, handleRetry],
+  );
+
+  if (!supported || !isWorktree || !workspaceId) return <Text style={styles.text}>{label}</Text>;
+
+  return (
+    <View ref={anchorRef} collapsable={false} style={styles.anchor}>
+      <ToolbarLabelSelectTrigger
+        testID="workspace-base-branch-trigger"
+        label={label}
+        open={open}
+        disabled={!connected || mutation.isPending}
+        accessibilityRole="button"
+        accessibilityLabel={title}
+        onPress={handleOpen}
+      />
+      <Combobox
+        options={options}
+        value={baseRef}
+        onSelect={handleSelect}
+        keepOpenOnSelect
+        searchable
+        onSearchQueryChange={setSearch}
+        searchPlaceholder={t("branchSwitcher.searchPlaceholder")}
+        emptyText={branches.isFetching ? t("common.states.loading") : t("branchSwitcher.empty")}
+        title={title}
+        open={open}
+        onOpenChange={setOpen}
+        anchorRef={anchorRef}
+        desktopPlacement="bottom-start"
+        desktopPreventInitialFlash
+        desktopMinWidth={300}
+        renderOption={renderOption}
+        footer={error || isPending ? footer : undefined}
+      />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create((theme) => ({
+  anchor: { flexShrink: 1, minWidth: 0 },
+  footer: { padding: theme.spacing[3], gap: theme.spacing[2] },
+  text: { color: theme.colors.foregroundMuted, fontSize: theme.fontSize.sm },
+  error: { color: theme.colors.destructive, fontSize: theme.fontSize.sm },
+}));
diff --git a/packages/app/src/i18n/resources/ar.ts b/packages/app/src/i18n/resources/ar.ts
index 098a49ae52..9d1ca6610d 100644
--- a/packages/app/src/i18n/resources/ar.ts
+++ b/packages/app/src/i18n/resources/ar.ts
@@ -930,6 +930,9 @@ export const ar: TranslationResources = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "الفرع الأساسي",
+        },
         openChangesTab: "فتح علامة تبويب التغييرات",
         openDiffTab: "فتح علامة تبويب الفرق",
         closeChangesTab: "إغلاق علامة تبويب التغييرات",
diff --git a/packages/app/src/i18n/resources/en.ts b/packages/app/src/i18n/resources/en.ts
index 16ba66d960..3f3091ae4a 100644
--- a/packages/app/src/i18n/resources/en.ts
+++ b/packages/app/src/i18n/resources/en.ts
@@ -938,6 +938,9 @@ export const en = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "Change base",
+        },
         openChangesTab: "Open Changes tab",
         openDiffTab: "Open Diff tab",
         closeChangesTab: "Close Changes tab",
diff --git a/packages/app/src/i18n/resources/es.ts b/packages/app/src/i18n/resources/es.ts
index 3d28cda81f..73cc70a8ca 100644
--- a/packages/app/src/i18n/resources/es.ts
+++ b/packages/app/src/i18n/resources/es.ts
@@ -963,6 +963,9 @@ export const es: TranslationResources = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "Rama base",
+        },
         openChangesTab: "Abrir la pestaña Cambios",
         openDiffTab: "Abrir la pestaña Diferencia",
         closeChangesTab: "Cerrar la pestaña Cambios",
diff --git a/packages/app/src/i18n/resources/fr.ts b/packages/app/src/i18n/resources/fr.ts
index da19c643ad..4257b799aa 100644
--- a/packages/app/src/i18n/resources/fr.ts
+++ b/packages/app/src/i18n/resources/fr.ts
@@ -956,6 +956,9 @@ export const fr: TranslationResources = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "Branche de base",
+        },
         openChangesTab: "Ouvrir l’onglet Modifications",
         openDiffTab: "Ouvrir l’onglet Diff",
         closeChangesTab: "Fermer l’onglet Modifications",
diff --git a/packages/app/src/i18n/resources/ja.ts b/packages/app/src/i18n/resources/ja.ts
index 73e14a0b68..073f164e6b 100644
--- a/packages/app/src/i18n/resources/ja.ts
+++ b/packages/app/src/i18n/resources/ja.ts
@@ -943,6 +943,9 @@ export const ja: TranslationResources = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "ベースブランチ",
+        },
         openChangesTab: "変更タブを開く",
         openDiffTab: "差分タブを開く",
         closeChangesTab: "変更タブを閉じる",
diff --git a/packages/app/src/i18n/resources/ko.ts b/packages/app/src/i18n/resources/ko.ts
index 117d5d68bc..cee2bb19bd 100644
--- a/packages/app/src/i18n/resources/ko.ts
+++ b/packages/app/src/i18n/resources/ko.ts
@@ -937,6 +937,9 @@ export const ko: TranslationResources = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "기준 브랜치",
+        },
         openChangesTab: "변경사항 탭 열기",
         openDiffTab: "Diff 탭 열기",
         closeChangesTab: "변경사항 탭 닫기",
diff --git a/packages/app/src/i18n/resources/pt-BR.ts b/packages/app/src/i18n/resources/pt-BR.ts
index 4460039b7f..a88a749709 100644
--- a/packages/app/src/i18n/resources/pt-BR.ts
+++ b/packages/app/src/i18n/resources/pt-BR.ts
@@ -953,6 +953,9 @@ export const ptBR: TranslationResources = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "Branch base",
+        },
         openChangesTab: "Abrir a aba Alterações",
         openDiffTab: "Abrir a aba Diff",
         closeChangesTab: "Fechar a aba Alterações",
diff --git a/packages/app/src/i18n/resources/ru.ts b/packages/app/src/i18n/resources/ru.ts
index 012e6eb47b..3d8bd13196 100644
--- a/packages/app/src/i18n/resources/ru.ts
+++ b/packages/app/src/i18n/resources/ru.ts
@@ -947,6 +947,9 @@ export const ru: TranslationResources = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "Базовая ветка",
+        },
         openChangesTab: "Открыть вкладку «Изменения»",
         openDiffTab: "Открыть вкладку «Дифф»",
         closeChangesTab: "Закрыть вкладку «Изменения»",
diff --git a/packages/app/src/i18n/resources/zh-CN.ts b/packages/app/src/i18n/resources/zh-CN.ts
index 1c6106553e..f0a0c9bc5c 100644
--- a/packages/app/src/i18n/resources/zh-CN.ts
+++ b/packages/app/src/i18n/resources/zh-CN.ts
@@ -922,6 +922,9 @@ export const zhCN: TranslationResources = {
         },
       },
       diff: {
+        baseBranch: {
+          title: "基准分支",
+        },
         openChangesTab: "打开“更改”标签页",
         openDiffTab: "打开 Diff 标签页",
         closeChangesTab: "关闭“更改”标签页",
diff --git a/packages/client/src/daemon-client.ts b/packages/client/src/daemon-client.ts
index 68677c3f24..b29a34111c 100644
--- a/packages/client/src/daemon-client.ts
+++ b/packages/client/src/daemon-client.ts
@@ -3582,6 +3582,22 @@ export class DaemonClient {
     return { pinnedAt: payload.pinnedAt };
   }
 
+  async setWorkspaceBaseBranch(options: {
+    workspaceId: string;
+    baseRef: string;
+    requestId?: string;
+  }): Promise<{ baseRef: string | null }> {
+    const { requestId, workspaceId, baseRef } = options;
+    const payload =
+      await this.sendNamespacedCorrelatedSessionRequest<"workspace.base_branch.set.response">({
+        requestId,
+        message: { type: "workspace.base_branch.set.request", workspaceId, baseRef },
+      });
+    if (!payload.accepted)
+      throw new Error(payload.error ?? "Changing the workspace base branch failed");
+    return { baseRef: payload.baseRef };
+  }
+
   async inspectWorkspaceRecovery(
     workspaceId: string,
     requestId?: string,
@@ -5134,7 +5150,7 @@ export class DaemonClient {
   }
 
   async getBranchSuggestions(
-    options: { cwd: string; query?: string; limit?: number },
+    options: { cwd: string; query?: string; limit?: number; refMode?: "exact" },
     requestId?: string,
   ): Promise<BranchSuggestionsPayload> {
     return this.sendCorrelatedSessionRequest({
@@ -5144,6 +5160,7 @@ export class DaemonClient {
         cwd: options.cwd,
         query: options.query,
         limit: options.limit,
+        refMode: options.refMode,
       },
       responseType: "branch_suggestions_response",
     });
diff --git a/packages/client/src/index.test.ts b/packages/client/src/index.test.ts
index 62ee8dda6a..5fd4d92958 100644
--- a/packages/client/src/index.test.ts
+++ b/packages/client/src/index.test.ts
@@ -607,6 +607,29 @@ test("workspace handles keep identity and refresh snapshots through existing dri
     }),
   );
   await expect(titlePromise).resolves.toEqual({ title: "SDK review" });
+  const basePromise = workspace.setBaseBranch({
+    baseRef: "refs/heads/release",
+    requestId: "workspace-base-request",
+  });
+  expect(parseSentSessionMessage(ws.sent.at(-1))).toMatchObject({
+    type: "workspace.base_branch.set.request",
+    workspaceId: "workspace_sdk",
+    baseRef: "refs/heads/release",
+    requestId: "workspace-base-request",
+  });
+  ws.message(
+    sessionMessage({
+      type: "workspace.base_branch.set.response",
+      payload: {
+        requestId: "workspace-base-request",
+        workspaceId: "workspace_sdk",
+        accepted: true,
+        baseRef: "refs/heads/release",
+        error: null,
+      },
+    }),
+  );
+  await expect(basePromise).resolves.toEqual({ baseRef: "refs/heads/release" });
 
   unsubscribe();
   ws.message(
diff --git a/packages/client/src/index.ts b/packages/client/src/index.ts
index 568c23896b..ead91e719c 100644
--- a/packages/client/src/index.ts
+++ b/packages/client/src/index.ts
@@ -189,6 +189,10 @@ export interface PaseoWorkspaceHandle {
   current(): PaseoWorkspace | null;
   refresh(options?: { requestId?: string }): Promise<PaseoWorkspace | null>;
   setTitle(title: string | null, requestId?: string): Promise<{ title: string | null }>;
+  setBaseBranch(options: {
+    baseRef: string;
+    requestId?: string;
+  }): Promise<{ baseRef: string | null }>;
   archive(requestId?: string): Promise<PaseoWorkspaceArchiveResult>;
   /**
    * Subscribes to already-emitted daemon workspace_update events for this id.
@@ -862,6 +866,8 @@ function createWorkspaceHandleFactory(
       current: () => current,
       refresh,
       setTitle: (title, requestId) => daemonClient.setWorkspaceTitle(id, title, requestId),
+      setBaseBranch: (options) =>
+        daemonClient.setWorkspaceBaseBranch({ ...options, workspaceId: id }),
       archive: async (requestId) => {
         const result = await daemonClient.archiveWorkspace(id, requestId);
         if (current) {
diff --git a/packages/protocol/src/messages.ts b/packages/protocol/src/messages.ts
index b5fa571914..64f37064e2 100644
--- a/packages/protocol/src/messages.ts
+++ b/packages/protocol/src/messages.ts
@@ -1040,6 +1040,13 @@ export const WorkspacePinSetRequestSchema = z.object({
   requestId: z.string(),
 });
 
+export const WorkspaceBaseBranchSetRequestSchema = z.object({
+  type: z.literal("workspace.base_branch.set.request"),
+  workspaceId: z.string(),
+  baseRef: z.string(),
+  requestId: z.string(),
+});
+
 export const WorkspaceLabelColorSchema = z.enum(WORKSPACE_LABEL_COLORS);
 export const WorkspaceLabelDefinitionSchema = z.object({
   name: z.string(),
@@ -2197,6 +2204,17 @@ export const WorkspacePinSetResponseSchema = z.object({
   payload: WorkspacePinSetResponsePayloadSchema,
 });
 
+export const WorkspaceBaseBranchSetResponseSchema = z.object({
+  type: z.literal("workspace.base_branch.set.response"),
+  payload: z.object({
+    requestId: z.string(),
+    workspaceId: z.string(),
+    accepted: z.boolean(),
+    baseRef: z.string().nullable(),
+    error: z.string().nullable(),
+  }),
+});
+
 export const WorkspaceRecoveryStateSchema = z.discriminatedUnion("kind", [
   z.object({
     kind: z.literal("recoverable"),
@@ -2514,6 +2532,7 @@ export const BranchSuggestionsRequestSchema = z.object({
   cwd: z.string(),
   query: z.string().optional(),
   limit: z.number().int().min(1).max(200).optional(),
+  refMode: z.literal("exact").optional(),
   requestId: z.string(),
 });
 
@@ -3328,6 +3347,7 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
   ProjectRemoveRequestSchema,
   WorkspaceTitleSetRequestSchema,
   WorkspacePinSetRequestSchema,
+  WorkspaceBaseBranchSetRequestSchema,
   WorkspaceLabelListRequestSchema,
   WorkspaceLabelAssignmentSetRequestSchema,
   WorkspaceLabelUpdateRequestSchema,
@@ -3712,6 +3732,8 @@ export const ServerInfoStatusPayloadSchema = z
         directorySync: z.boolean().optional(),
         // COMPAT(workspaceLabels): added in v0.5.0, remove after 2027-08-14.
         workspaceLabels: z.boolean().optional(),
+        // COMPAT(workspaceBaseBranch): added after v0.11.2, remove gate after 2027-10-14.
+        workspaceBaseBranch: z.boolean().optional(),
         // COMPAT(workspaceSetupRun): added in v0.8.0, remove gate after 2027-09-02.
         workspaceSetupRun: z.boolean().optional(),
         // COMPAT(workspaceTerminals): added in v0.8.0, remove gate after 2027-09-05.
@@ -5405,6 +5427,7 @@ const CheckoutStatusCommonSchema = z.object({
   cwd: z.string(),
   error: CheckoutErrorSchema.nullable(),
   requestId: z.string(),
+  baseRefExact: z.string().nullable().optional(),
   // The full ref currentBranch tracks, as git resolves `<branch>@{upstream}`:
   // "refs/remotes/origin/main", "refs/remotes/upstream/main" on a fork, or a
   // "refs/heads/..." ref for a branch tracking a local branch. Null when there is no
@@ -7203,6 +7226,7 @@ export const SessionOutboundMessageSchema = z.discriminatedUnion("type", [
   ProjectRemoveResponseSchema,
   WorkspaceTitleSetResponseSchema,
   WorkspacePinSetResponseSchema,
+  WorkspaceBaseBranchSetResponseSchema,
   WorkspaceRecoveryInspectResponseSchema,
   WorkspaceRecoveryRestoreResponseSchema,
   WaitForFinishResponseMessageSchema,
@@ -7564,6 +7588,7 @@ export type ProjectIconSetRequest = z.infer<typeof ProjectIconSetRequestSchema>;
 export type ProjectRemoveRequest = z.infer<typeof ProjectRemoveRequestSchema>;
 export type WorkspaceTitleSetRequest = z.infer<typeof WorkspaceTitleSetRequestSchema>;
 export type WorkspacePinSetRequest = z.infer<typeof WorkspacePinSetRequestSchema>;
+export type WorkspaceBaseBranchSetRequest = z.infer<typeof WorkspaceBaseBranchSetRequestSchema>;
 export type WorkspaceRecoveryInspectRequest = z.infer<typeof WorkspaceRecoveryInspectRequestSchema>;
 export type WorkspaceRecoveryRestoreRequest = z.infer<typeof WorkspaceRecoveryRestoreRequestSchema>;
 export type SetAgentModeRequestMessage = z.infer<typeof SetAgentModeRequestMessageSchema>;
diff --git a/packages/protocol/src/messages.wire-compat.test.ts b/packages/protocol/src/messages.wire-compat.test.ts
index abc89b06aa..a15c1ae1be 100644
--- a/packages/protocol/src/messages.wire-compat.test.ts
+++ b/packages/protocol/src/messages.wire-compat.test.ts
@@ -12,8 +12,65 @@ import {
   WorkspaceSetupSnapshotSchema,
   WorkspaceSetupProgressMessageSchema,
   AgentTimelineEntryPayloadSchema,
+  CheckoutStatusResponseSchema,
+  BranchSuggestionsRequestSchema,
+  WorkspaceBaseBranchSetRequestSchema,
+  WorkspaceBaseBranchSetResponseSchema,
 } from "./messages.js";
 
+test("base selection RPCs are correlated while older checkout and branch messages remain valid", () => {
+  const payload = {
+    cwd: "/repo",
+    requestId: "status",
+    error: null,
+    isGit: true,
+    isPaseoOwnedWorktree: false,
+    repoRoot: "/repo",
+    currentBranch: "feature",
+    isDirty: false,
+    baseRef: "release",
+    aheadBehind: null,
+    aheadOfOrigin: null,
+    behindOfOrigin: null,
+    hasRemote: false,
+    remoteUrl: null,
+  };
+  expect(
+    CheckoutStatusResponseSchema.safeParse({ type: "checkout_status_response", payload }).success,
+  ).toBe(true);
+  expect(
+    CheckoutStatusResponseSchema.parse({
+      type: "checkout_status_response",
+      payload: { ...payload, baseRefExact: "refs/remotes/upstream/release" },
+    }).payload.baseRefExact,
+  ).toBe("refs/remotes/upstream/release");
+  expect(
+    BranchSuggestionsRequestSchema.safeParse({
+      type: "branch_suggestions_request",
+      cwd: "/repo",
+      requestId: "branches",
+    }).success,
+  ).toBe(true);
+  const request = {
+    type: "workspace.base_branch.set.request",
+    workspaceId: "workspace",
+    baseRef: "refs/heads/release",
+    requestId: "base",
+  };
+  expect(WorkspaceBaseBranchSetRequestSchema.parse(request)).toEqual(request);
+  const response = {
+    type: "workspace.base_branch.set.response",
+    payload: {
+      workspaceId: "workspace",
+      baseRef: "refs/heads/release",
+      requestId: "base",
+      accepted: true,
+      error: null,
+    },
+  };
+  expect(WorkspaceBaseBranchSetResponseSchema.parse(response)).toEqual(response);
+});
+
 test("terminal listings accept older rows and retain new per-terminal directories", () => {
   const response = {
     type: "list_terminals_response",
diff --git a/packages/server/src/server/authorization/operation-permissions.ts b/packages/server/src/server/authorization/operation-permissions.ts
index 0719e3d984..8cc9d6d1a0 100644
--- a/packages/server/src/server/authorization/operation-permissions.ts
+++ b/packages/server/src/server/authorization/operation-permissions.ts
@@ -216,6 +216,7 @@ const INBOUND_PERMISSION = {
   "workspace.label.list.request": "workspace.read",
   "workspace.label.update.request": "workspace.manage",
   "workspace.pin.set.request": "workspace.manage",
+  "workspace.base_branch.set.request": "workspace.write",
   "workspace.recovery.inspect.request": ["workspace.read", "hub.execute"],
   "workspace.recovery.restore.request": ["workspace.manage", "hub.execute"],
   "workspace.script.list.request": "workspace.read",
@@ -458,6 +459,7 @@ const OUTBOUND_PERMISSION = {
   "workspace.label.update": "workspace.read",
   "workspace.label.update.response": "workspace.manage",
   "workspace.pin.set.response": "workspace.manage",
+  "workspace.base_branch.set.response": "workspace.write",
   "workspace.recovery.inspect.response": ["workspace.read", "hub.execute"],
   "workspace.recovery.restore.response": ["workspace.manage", "hub.execute"],
   "workspace.script.list.response": "workspace.read",
diff --git a/packages/server/src/server/checkout-diff-manager.ts b/packages/server/src/server/checkout-diff-manager.ts
index 917813d587..8293ce965f 100644
--- a/packages/server/src/server/checkout-diff-manager.ts
+++ b/packages/server/src/server/checkout-diff-manager.ts
@@ -195,6 +195,7 @@ export class CheckoutDiffManager {
       remoteUrl: snapshot.git.remoteUrl,
       isPaseoOwnedWorktree: snapshot.git.isPaseoOwnedWorktree,
       baseRef: snapshot.git.baseRef,
+      baseRefExact: snapshot.git.baseRefExact,
       aheadBehind: snapshot.git.aheadBehind,
       aheadOfOrigin: snapshot.git.aheadOfOrigin,
       behindOfOrigin: snapshot.git.behindOfOrigin,
diff --git a/packages/server/src/server/checkout/status-projection.ts b/packages/server/src/server/checkout/status-projection.ts
index 7f7365efca..90c900435c 100644
--- a/packages/server/src/server/checkout/status-projection.ts
+++ b/packages/server/src/server/checkout/status-projection.ts
@@ -61,6 +61,7 @@ export function buildCheckoutStatusPayloadFromSnapshot({
       currentBranch: snapshot.git.currentBranch ?? null,
       isDirty: snapshot.git.isDirty,
       baseRef: snapshot.git.baseRef,
+      baseRefExact: snapshot.git.baseRefExact,
       aheadBehind: snapshot.git.aheadBehind ?? null,
       upstreamRef: snapshot.git.upstreamRef ?? null,
       aheadOfOrigin: snapshot.git.aheadOfOrigin ?? null,
@@ -81,6 +82,7 @@ export function buildCheckoutStatusPayloadFromSnapshot({
     currentBranch: snapshot.git.currentBranch ?? null,
     isDirty: snapshot.git.isDirty,
     baseRef: snapshot.git.baseRef ?? null,
+    baseRefExact: snapshot.git.baseRefExact,
     aheadBehind: snapshot.git.aheadBehind ?? null,
     upstreamRef: snapshot.git.upstreamRef ?? null,
     aheadOfOrigin: snapshot.git.aheadOfOrigin ?? null,
diff --git a/packages/server/src/server/git-metadata-event-rules.test.ts b/packages/server/src/server/git-metadata-event-rules.test.ts
index 8c7e491970..4456573624 100644
--- a/packages/server/src/server/git-metadata-event-rules.test.ts
+++ b/packages/server/src/server/git-metadata-event-rules.test.ts
@@ -21,6 +21,7 @@ describe("Git metadata event rules", () => {
     ["worktree", "HEAD", { kind: "owner", refreshBase: true }],
     ["worktree", "config.worktree", { kind: "owner", refreshBase: true }],
     ["worktree", "paseo/worktree.json", { kind: "owner", refreshBase: true }],
+    ["common", "paseo/worktree.json", { kind: "owner", refreshBase: true }],
     ["worktree", "COMMIT_EDITMSG", { kind: "ignore" }],
     ["worktree", "ORIG_HEAD", { kind: "ignore" }],
     ["common", "index", { kind: "owner", refreshBase: false }],
diff --git a/packages/server/src/server/git-metadata-event-rules.ts b/packages/server/src/server/git-metadata-event-rules.ts
index dab6bc4887..ff82747ba0 100644
--- a/packages/server/src/server/git-metadata-event-rules.ts
+++ b/packages/server/src/server/git-metadata-event-rules.ts
@@ -44,7 +44,7 @@ export const GIT_METADATA_EVENT_RULES = [
   },
   {
     id: "paseo-worktree-metadata",
-    scope: "worktree",
+    scope: "both",
     match: "exact",
     path: "paseo/worktree.json",
     route: "owner",
diff --git a/packages/server/src/server/session.ts b/packages/server/src/server/session.ts
index 9ce3fbbcb4..3dec72f45f 100644
--- a/packages/server/src/server/session.ts
+++ b/packages/server/src/server/session.ts
@@ -3,6 +3,12 @@ import type { AgentMessageDelivery } from "./agent/agent-messages/index.js";
 import { AgentDirectory, type BackgroundVisibility } from "./agent/directory.js";
 import { ConnectedHostSession } from "./connected-hosts/index.js";
 import type { ConnectedHosts } from "./connected-hosts/index.js";
+import {
+  createWorkspaceBaseBranchService,
+  type WorkspaceBaseBranchService,
+} from "./session/workspace-base-branch/service.js";
+import type { WorkspaceBaseBranchSetRequest } from "@getpaseo/protocol/messages";
+
 import { searchTimeline } from "./agent/chat-search/index.js";
 import type { BrowserToolsBroker } from "./browser-tools/broker.js";
 import { BrowserAutomationHostCapabilitySchema } from "@getpaseo/protocol/browser-automation/capabilities";
@@ -483,6 +489,7 @@ export interface SessionOptions {
   creationService: Pick<CreationService, "create" | "subscribe">;
   projectRegistry: ProjectRegistry;
   workspaceRegistry: WorkspaceRegistry;
+  workspaceBaseBranch?: WorkspaceBaseBranchService;
   directorySync?: DirectorySyncService;
   workspaceLabelService?: WorkspaceLabelService;
   filesystem?: SessionFileSystem;
@@ -779,6 +786,7 @@ export class Session {
   private readonly gitMutation: GitMutationService;
   private readonly workspaceProvisioning: WorkspaceProvisioningService;
   private readonly workspaceRecovery: WorkspaceRecoveryService;
+  private workspaceBaseBranch: WorkspaceBaseBranchService | undefined;
   private readonly daemonConfigStore: DaemonConfigStore;
   private readonly pushNotifications: PushNotifications;
   private readonly pluginRuntime: SessionOptions["pluginRuntime"];
@@ -962,12 +970,22 @@ export class Session {
     this.renameCurrentBranch = renameCurrentBranch ?? renameCurrentBranchDefault;
     this.workspaceGitService = workspaceGitService;
     this.workspaceRuntimeStore = workspaceRuntimeStore;
+    this.workspaceBaseBranch =
+      options.workspaceBaseBranch ??
+      createWorkspaceBaseBranchService({
+        paseoHome: this.paseoHome,
+        worktreesRoot: this.worktreesRoot,
+        workspaceRegistry: this.workspaceRegistry,
+        workspaceGitService: this.workspaceGitService,
+      });
+
     this.gitMutation = createGitMutationService({
       workspaceGitService: this.workspaceGitService,
       logger: this.sessionLogger,
     });
     this.workspaceAutoName = workspaceAutoName;
     this.workspaceProvisioning = createWorkspaceProvisioningService({
+      withCheckoutLock: this.workspaceBaseBranch.withCheckoutLock,
       lifecycle: this.pluginRuntime,
       serverId,
       workspaceRegistry: this.workspaceRegistry,
@@ -3213,6 +3231,8 @@ export class Session {
         return this.handleWorkspaceTitleSetRequest(msg.workspaceId, msg.title, msg.requestId);
       case "workspace.pin.set.request":
         return this.handleWorkspacePinSetRequest(msg.workspaceId, msg.pinned, msg.requestId);
+      case "workspace.base_branch.set.request":
+        return this.handleWorkspaceBaseBranchSetRequest(msg);
       default:
         return undefined;
     }
@@ -4076,6 +4096,41 @@ export class Session {
     }
   }
 
+  private async handleWorkspaceBaseBranchSetRequest(
+    msg: WorkspaceBaseBranchSetRequest,
+  ): Promise<void> {
+    try {
+      this.workspaceBaseBranch ??= createWorkspaceBaseBranchService({
+        paseoHome: this.paseoHome,
+        worktreesRoot: this.worktreesRoot,
+        workspaceRegistry: this.workspaceRegistry,
+        workspaceGitService: this.workspaceGitService,
+      });
+      const baseRef = await this.workspaceBaseBranch.setBaseBranch(msg);
+      this.emit({
+        type: "workspace.base_branch.set.response",
+        payload: {
+          requestId: msg.requestId,
+          workspaceId: msg.workspaceId,
+          accepted: true,
+          baseRef,
+          error: null,
+        },
+      });
+    } catch (error) {
+      this.emit({
+        type: "workspace.base_branch.set.response",
+        payload: {
+          requestId: msg.requestId,
+          workspaceId: msg.workspaceId,
+          accepted: false,
+          baseRef: null,
+          error: getErrorMessage(error),
+        },
+      });
+    }
+  }
+
   private async handleWorkspacePinSetRequest(
     workspaceId: string,
     pinned: boolean,
diff --git a/packages/server/src/server/session/checkout/checkout-session.ts b/packages/server/src/server/session/checkout/checkout-session.ts
index ceb69e9623..4deb28a56b 100644
--- a/packages/server/src/server/session/checkout/checkout-session.ts
+++ b/packages/server/src/server/session/checkout/checkout-session.ts
@@ -379,13 +379,14 @@ export class CheckoutSession {
   }
 
   async handleBranchSuggestionsRequest(msg: BranchSuggestionsRequest): Promise<void> {
-    const { cwd, query, limit, requestId } = msg;
+    const { cwd, query, limit, refMode, requestId } = msg;
 
     try {
       const resolvedCwd = expandTilde(cwd);
       const branchDetails = await this.workspaceGitService.suggestBranchesForCwd(resolvedCwd, {
         query,
         limit,
+        refMode,
       });
       this.host.emit({
         type: "branch_suggestions_response",
diff --git a/packages/server/src/server/session/workspace-base-branch/service.ts b/packages/server/src/server/session/workspace-base-branch/service.ts
new file mode 100644
index 0000000000..ffc8feffb0
--- /dev/null
+++ b/packages/server/src/server/session/workspace-base-branch/service.ts
@@ -0,0 +1,104 @@
+import { resolve } from "node:path";
+import { getCheckoutSnapshotFacts, setCheckoutBaseBranch } from "../../../utils/checkout-git.js";
+import {
+  readPaseoWorktreeMetadata,
+  setPaseoWorktreeBaseRef,
+} from "../../../utils/worktree-metadata.js";
+import type { WorkspaceRegistry } from "../../workspace-registry.js";
+import type { WorkspaceGitService } from "../../workspace-git-service.js";
+
+interface Dependencies {
+  paseoHome: string;
+  worktreesRoot?: string;
+  workspaceRegistry: WorkspaceRegistry;
+  workspaceGitService: WorkspaceGitService;
+}
+
+export function createWorkspaceBaseBranchService(deps: Dependencies) {
+  const queues = new Map<string, Promise<void>>();
+
+  async function withCheckoutLock<T>(root: string, operation: () => Promise<T>): Promise<T> {
+    root = resolve(root);
+    const previous = queues.get(root);
+    let release!: () => void;
+    const queued = new Promise<void>((done) => {
+      release = done;
+    });
+    queues.set(root, queued);
+    await previous;
+
+    try {
+      return await operation();
+    } finally {
+      release();
+      if (queues.get(root) === queued) queues.delete(root);
+    }
+  }
+
+  async function setBaseBranch(input: { workspaceId: string; baseRef: string }): Promise<string> {
+    const workspace = await deps.workspaceRegistry.get(input.workspaceId);
+    if (!workspace || workspace.archivedAt) throw new Error("Workspace is unavailable");
+    const facts = await getCheckoutSnapshotFacts(workspace.cwd, {
+      paseoHome: deps.paseoHome,
+      worktreesRoot: deps.worktreesRoot,
+    });
+    if (!facts.isGit) throw new Error("Workspace is not a Git checkout");
+    if (!facts.paseoWorktree.isPaseoOwnedWorktree)
+      throw new Error("Workspace is not a Paseo worktree");
+    const root = resolve(facts.worktreeRoot);
+    return withCheckoutLock(root, async () => {
+      const current = await deps.workspaceRegistry.get(input.workspaceId);
+      if (!current || current.archivedAt) throw new Error("Workspace is unavailable");
+      const records = await deps.workspaceRegistry.listActive();
+      const matching = records.filter(
+        (record) =>
+          record.workspaceId === input.workspaceId ||
+          resolve(record.worktreeRoot ?? record.cwd) === root,
+      );
+      await deps.workspaceGitService.getSnapshot(root);
+      const metadata = await readPaseoWorktreeMetadata(root);
+      const baseRef = await setCheckoutBaseBranch({
+        cwd: root,
+        baseRef: input.baseRef,
+        context: { paseoHome: deps.paseoHome, worktreesRoot: deps.worktreesRoot },
+      });
+      const updatedAt = new Date().toISOString();
+      try {
+        for (const record of matching) {
+          await deps.workspaceRegistry.update(record.workspaceId, (latest) => ({
+            ...latest,
+            baseBranch: baseRef,
+            updatedAt,
+          }));
+        }
+      } catch (error) {
+        if (metadata)
+          await setPaseoWorktreeBaseRef({
+            worktreeRoot: root,
+            baseRef: metadata.baseRef ?? metadata.baseRefName,
+          });
+        for (const record of matching) {
+          await deps.workspaceRegistry.update(record.workspaceId, (latest) => ({
+            ...latest,
+            baseBranch: record.baseBranch,
+            updatedAt: record.updatedAt,
+          }));
+        }
+        throw error;
+      }
+      for (const cwd of new Set(matching.map((record) => record.cwd))) {
+        await deps.workspaceGitService.getSnapshot(cwd, {
+          force: true,
+          afterInFlight: true,
+          includeForge: false,
+          reason: "base-branch-change",
+        });
+      }
+      return baseRef;
+    });
+  }
+
+  return { setBaseBranch, withCheckoutLock };
+}
+
+export type WorkspaceBaseBranchService = ReturnType<typeof createWorkspaceBaseBranchService>;
diff --git a/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.test.ts b/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.test.ts
index d9f7ccea96..012ad0d490 100644
--- a/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.test.ts
+++ b/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.test.ts
@@ -5,6 +5,11 @@ import { mkdirSync, mkdtempSync, rmSync, statSync, symlinkSync } from "node:fs";
 import { afterEach, beforeEach, expect, test } from "vitest";
 
 import { getCheckoutStatus } from "../../../utils/checkout-git.js";
+import {
+  setPaseoWorktreeBaseRef,
+  writePaseoWorktreeMetadata,
+} from "../../../utils/worktree-metadata.js";
+import { createWorkspaceBaseBranchService } from "../workspace-base-branch/service.js";
 import { createTestLogger } from "../../../test-utils/test-logger.js";
 import {
   createNoGitWorkspaceRuntimeSnapshot,
@@ -125,6 +130,62 @@ afterEach(() => {
   rmSync(tmpDir, { recursive: true, force: true });
 });
 
+test("a workspace created during a base change records the new base", async () => {
+  const cwd = path.join(tmpDir, "worktree");
+  mkdirSync(path.join(cwd, ".git"), { recursive: true });
+  await writePaseoWorktreeMetadata(cwd, { baseRefName: "main", baseRef: "refs/heads/main" });
+  const git = createNoopWorkspaceGitService({
+    getCheckout: async () => ({
+      cwd,
+      isGit: true,
+      currentBranch: "feature",
+      remoteUrl: null,
+      worktreeRoot: cwd,
+      isPaseoOwnedWorktree: true,
+      mainRepoRoot: cwd,
+    }),
+  });
+  const bases = createWorkspaceBaseBranchService({
+    paseoHome: tmpDir,
+    workspaceRegistry,
+    workspaceGitService: git,
+  });
+  let release!: () => void;
+  let entered!: () => void;
+  let attempted!: () => void;
+  const gate = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const locked = new Promise<void>((resolve) => {
+    entered = resolve;
+  });
+  const waiting = new Promise<void>((resolve) => {
+    attempted = resolve;
+  });
+  const change = bases.withCheckoutLock(cwd, async () => {
+    entered();
+    await gate;
+    await setPaseoWorktreeBaseRef({ worktreeRoot: cwd, baseRef: "refs/heads/release" });
+  });
+  await locked;
+  const creator = createWorkspaceProvisioningService({
+    workspaceRegistry,
+    projectRegistry,
+    workspaceGitService: git,
+    isDirectory,
+    logger,
+    withCheckoutLock: (root, operation) => {
+      attempted();
+      return bases.withCheckoutLock(root, operation);
+    },
+  });
+  const created = creator.createWorkspaceForDirectory(cwd);
+  await waiting;
+  release();
+  await change;
+  expect((await created).baseBranch).toBe("refs/heads/release");
+});
+
 test("fresh git repo creates a workspace at the canonical worktree root", async () => {
   const repo = path.join(tmpDir, "repo");
   gitRoots.add(repo);
diff --git a/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.ts b/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.ts
index c4554688e0..3f2a7b423c 100644
--- a/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.ts
+++ b/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.ts
@@ -20,6 +20,7 @@ import type { CreatePaseoWorktreeWorkflowResult } from "../../worktree-session.j
 import { deriveProjectKey } from "../../project-key.js";
 import { areEquivalentPaths, createRealpathAwarePathMatcher } from "../../../utils/path.js";
 import type { UntrustedWorkspaceSource } from "../../workspace-automation-gate.js";
+import { readPaseoWorktreeMetadata } from "../../../utils/worktree-metadata.js";
 
 export interface ResolveOrCreateWorkspaceIdInput {
   createdWorktree: CreatePaseoWorktreeWorkflowResult | null;
@@ -107,6 +108,7 @@ export function createWorkspaceProvisioningService(deps: {
   isDirectory: (path: string) => Promise<boolean>;
   logger: Logger;
   lifecycle?: PluginLifecycle;
+  withCheckoutLock?: <T>(root: string, operation: () => Promise<T>) => Promise<T>;
 }): WorkspaceProvisioningService {
   const { serverId, workspaceRegistry, projectRegistry, workspaceGitService, logger } = deps;
 
@@ -253,21 +255,31 @@ export function createWorkspaceProvisioningService(deps: {
       ? await refreshProjectKind(await requireActiveProject(projectId), normalizedCwd, checkout)
       : // COMPAT(workspaceCreateMissingProjectId): added in v0.1.107, remove after 2027-01-15.
         await findOrCreateProjectForDirectory(normalizedCwd);
-    const timestamp = new Date().toISOString();
-    const workspace = createPersistedWorkspaceRecord({
-      workspaceId: context?.workspaceId ?? generateWorkspaceId(),
-      projectId: project.projectId,
-      ...initialWorkspacePlacement({ source: "checkout", cwd: normalizedCwd, checkout }),
-      title: title?.trim() || null,
-      createdAt: timestamp,
-      updatedAt: timestamp,
-      background: await resolveBackground(context),
-    });
-    await workspaceRegistry.upsert(workspace, {
-      expectsInitialAgent: context?.expectsInitialAgent,
-    });
-    emitWorkspaceCreated(workspace);
-    return workspace;
+    const create = async () => {
+      const baseMetadata =
+        checkout.isGit && checkout.isPaseoOwnedWorktree
+          ? await readPaseoWorktreeMetadata(checkout.worktreeRoot ?? normalizedCwd)
+          : null;
+      const timestamp = new Date().toISOString();
+      const workspace = createPersistedWorkspaceRecord({
+        workspaceId: context?.workspaceId ?? generateWorkspaceId(),
+        projectId: project.projectId,
+        ...initialWorkspacePlacement({ source: "checkout", cwd: normalizedCwd, checkout }),
+        baseBranch: baseMetadata?.baseRef ?? baseMetadata?.baseRefName ?? null,
+        title: title?.trim() || null,
+        createdAt: timestamp,
+        updatedAt: timestamp,
+        background: await resolveBackground(context),
+      });
+      await workspaceRegistry.upsert(workspace, {
+        expectsInitialAgent: context?.expectsInitialAgent,
+      });
+      emitWorkspaceCreated(workspace);
+      return workspace;
+    };
+    return deps.withCheckoutLock && checkout.isGit && checkout.isPaseoOwnedWorktree
+      ? deps.withCheckoutLock(checkout.worktreeRoot ?? normalizedCwd, create)
+      : create();
   }
 
   async function createWorkspaceForWorktree(
diff --git a/packages/server/src/server/websocket-server.ts b/packages/server/src/server/websocket-server.ts
index 61014327fd..7c301556c3 100644
--- a/packages/server/src/server/websocket-server.ts
+++ b/packages/server/src/server/websocket-server.ts
@@ -16,6 +16,10 @@ import { HOST_ROUTE_OPCODE } from "@getpaseo/protocol/binary-frames/index";
 import { DaemonLinkEndpoint, VirtualHostSocket } from "./connected-hosts/index.js";
 import { ConnectedHosts } from "./connected-hosts/index.js";
 import { stat } from "node:fs/promises";
+import {
+  createWorkspaceBaseBranchService,
+  type WorkspaceBaseBranchService,
+} from "./session/workspace-base-branch/service.js";
 import type { CreationSnapshot } from "@getpaseo/protocol/messages";
 import { CreationService } from "./creation/index.js";
 import { MessageReceipts } from "./message-receipts/index.js";
@@ -569,6 +573,7 @@ export class VoiceAssistantWebSocketServer {
   private readonly creationService: CreationService;
   private readonly projectRegistry: ProjectRegistry;
   private readonly workspaceRegistry: WorkspaceRegistry;
+  private readonly workspaceBaseBranch: WorkspaceBaseBranchService;
   private readonly workspaceLabelService: WorkspaceLabelService | null;
   private readonly scheduleService: ScheduleService;
   private readonly checkoutDiffManager: CheckoutDiffManager;
@@ -756,12 +761,18 @@ export class VoiceAssistantWebSocketServer {
     this.checkoutDiffManager = requiredServices.checkoutDiffManager;
     this.github = github ?? createGitHubService();
     this.workspaceGitService = workspaceGitService ?? createFallbackWorkspaceGitService();
+    this.worktreesRoot = daemonRuntimeConfig?.worktreesRoot;
+    this.workspaceBaseBranch = createWorkspaceBaseBranchService({
+      paseoHome,
+      worktreesRoot: this.worktreesRoot,
+      workspaceRegistry: this.workspaceRegistry,
+      workspaceGitService: this.workspaceGitService,
+    });
     this.workspaceAutoName = workspaceAutoName;
     this.downloadTokenStore = downloadTokenStore;
     this.paseoHome = paseoHome;
     this.connectedHosts = new ConnectedHosts(paseoHome, { serverId, label: getHostName() });
     this.passwordHash = auth?.password;
-    this.worktreesRoot = daemonRuntimeConfig?.worktreesRoot;
     this.daemonConfigStore = daemonConfigStore;
     this.mcpBaseUrl = mcpBaseUrl;
     this.assignOptionalServices({
@@ -1661,6 +1672,7 @@ export class VoiceAssistantWebSocketServer {
       creationService: this.creationService,
       projectRegistry: this.projectRegistry,
       workspaceRegistry: this.workspaceRegistry,
+      workspaceBaseBranch: this.workspaceBaseBranch,
       workspaceLabelService: this.workspaceLabelService ?? undefined,
       directorySync: this.directorySync,
       scheduleService: this.scheduleService,
@@ -2016,6 +2028,7 @@ export class VoiceAssistantWebSocketServer {
         backgroundWorkspaces: true,
         // COMPAT(backgroundAgents): added in v0.15.0; remove gate after 2027-05-03.
         backgroundAgents: true,
+        workspaceBaseBranch: true,
         // COMPAT(directorySync): added in v0.3.x, remove gate after 2027-02-12.
         directorySync: true,
         // COMPAT(workspaceLabels): added in v0.5.0, remove after 2027-08-14.
diff --git a/packages/server/src/server/workspace-archive-record-scoped.e2e.test.ts b/packages/server/src/server/workspace-archive-record-scoped.e2e.test.ts
index df229f9221..d10a098d79 100644
--- a/packages/server/src/server/workspace-archive-record-scoped.e2e.test.ts
+++ b/packages/server/src/server/workspace-archive-record-scoped.e2e.test.ts
@@ -8,6 +8,7 @@ import { afterEach, beforeEach, expect, test } from "vitest";
 
 import { getFullAccessConfig } from "./daemon-e2e/agent-configs.js";
 import { createWorktree } from "../utils/worktree.js";
+import { readPaseoWorktreeMetadata } from "../utils/worktree-metadata.js";
 import {
   createDaemonTestContext,
   DaemonClient,
@@ -277,6 +278,118 @@ test("renaming a workspace updates every subscribed client", async () => {
   }
 });
 
+test("a local checkout rejects a base change without creating worktree metadata", async () => {
+  const repo = createGitRepo();
+  const id = await createLocalWorkspace(repo, "Local");
+  await expect(
+    ctx.client.setWorkspaceBaseBranch({ workspaceId: id, baseRef: "refs/heads/main" }),
+  ).rejects.toThrow("not a Paseo worktree");
+  expect(await readPaseoWorktreeMetadata(repo)).toBeNull();
+});
+
+test("changing a worktree base refreshes its diff and persists across restart", async () => {
+  const repo = createGitRepo();
+  execFileSync("git", ["checkout", "-b", "release"], { cwd: repo });
+  writeFileSync(path.join(repo, "release.txt"), "release\n");
+  execFileSync("git", ["add", "release.txt"], { cwd: repo });
+  execFileSync("git", ["-c", "commit.gpgsign=false", "commit", "-m", "release"], { cwd: repo });
+  const created = await ctx.client.createWorkspace({
+    source: { kind: "worktree", cwd: repo, worktreeSlug: "base-refresh", baseBranch: "main" },
+  });
+  const workspace = created.workspace;
+  if (!workspace) throw new Error(created.error ?? "Failed to create workspace");
+  const cwd = workspace.workspaceDirectory;
+  execFileSync("git", ["merge", "--ff-only", "release"], { cwd });
+  expect(
+    (await ctx.client.getCheckoutDiff(cwd, { mode: "base" })).files.map((file) => file.path),
+  ).toContain("release.txt");
+  await ctx.client.setWorkspaceBaseBranch({
+    workspaceId: workspace.id,
+    baseRef: "refs/heads/release",
+  });
+  expect(
+    (await ctx.client.getCheckoutDiff(cwd, { mode: "base" })).files.map((file) => file.path),
+  ).not.toContain("release.txt");
+  await expect(
+    ctx.client.setWorkspaceBaseBranch({ workspaceId: workspace.id, baseRef: "refs/heads/missing" }),
+  ).rejects.toThrow("Base branch not found");
+  execFileSync("git", ["update-ref", "refs/remotes/origin/vanished", "release"], { cwd });
+  await ctx.client.setWorkspaceBaseBranch({
+    workspaceId: workspace.id,
+    baseRef: "refs/remotes/origin/vanished",
+  });
+  execFileSync("git", ["update-ref", "-d", "refs/remotes/origin/vanished"], { cwd });
+  await ctx.client.setWorkspaceBaseBranch({
+    workspaceId: workspace.id,
+    baseRef: "refs/heads/main",
+  });
+  expect(
+    (await ctx.client.getCheckoutDiff(cwd, { mode: "base" })).files.map((file) => file.path),
+  ).toContain("release.txt");
+  await ctx.client.setWorkspaceBaseBranch({
+    workspaceId: workspace.id,
+    baseRef: "refs/heads/release",
+  });
+  const previous = ctx;
+  const paseoHomeRoot = path.dirname(previous.daemon.paseoHome);
+  await previous.client.close();
+  await previous.daemon.daemon.stop();
+  tempRoots.push(previous.daemon.staticDir);
+  ctx = await createDaemonTestContext({ paseoHomeRoot });
+  expect((await ctx.client.getCheckoutStatus(cwd)).baseRefExact).toBe("refs/heads/release");
+}, 30_000);
+
+test("a managed workspace restores its changed base after archival removes the checkout", async () => {
+  const repo = createGitRepo();
+  execFileSync("git", ["branch", "release"], { cwd: repo });
+  const created = await ctx.client.createWorkspace({
+    source: { kind: "worktree", cwd: repo, worktreeSlug: "changed-base", baseBranch: "main" },
+  });
+  const workspace = created.workspace;
+  if (!workspace) throw new Error(created.error ?? "Failed to create workspace");
+  await ctx.client.setWorkspaceBaseBranch({
+    workspaceId: workspace.id,
+    baseRef: "refs/heads/release",
+  });
+  const joinedId = await createLocalWorkspace(
+    workspace.workspaceDirectory,
+    "Joined after changing base",
+  );
+  expect((await ctx.client.archiveWorkspace(workspace.id)).error).toBe(null);
+  expect(existsSync(workspace.workspaceDirectory)).toBe(true);
+  expect((await ctx.client.archiveWorkspace(joinedId)).error).toBe(null);
+  expect(existsSync(workspace.workspaceDirectory)).toBe(false);
+  await ctx.client.restoreWorkspace(joinedId);
+  expect((await readPaseoWorktreeMetadata(workspace.workspaceDirectory))?.baseRef).toBe(
+    "refs/heads/release",
+  );
+  expect((await ctx.client.getCheckoutStatus(workspace.workspaceDirectory)).baseRefExact).toBe(
+    "refs/heads/release",
+  );
+});
+
+test("an archived workspace keeps its base when a later workspace reuses its path", async () => {
+  const repo = createGitRepo();
+  execFileSync("git", ["branch", "release"], { cwd: repo });
+  const source = { kind: "worktree", cwd: repo, worktreeSlug: "reused-path", baseBranch: "main" };
+  const first = (await ctx.client.createWorkspace({ source })).workspace;
+  if (!first) throw new Error("Failed to create first workspace");
+  expect((await ctx.client.archiveWorkspace(first.id)).error).toBe(null);
+  expect(existsSync(first.workspaceDirectory)).toBe(false);
+  const second = (await ctx.client.createWorkspace({ source })).workspace;
+  if (!second) throw new Error("Failed to create second workspace");
+  expect(second.workspaceDirectory).toBe(first.workspaceDirectory);
+  await ctx.client.setWorkspaceBaseBranch({
+    workspaceId: second.id,
+    baseRef: "refs/heads/release",
+  });
+  expect((await ctx.client.archiveWorkspace(second.id)).error).toBe(null);
+  await ctx.client.restoreWorkspace(first.id);
+  expect((await readPaseoWorktreeMetadata(first.workspaceDirectory))?.baseRef).toBe(
+    "refs/heads/main",
+  );
+});
+
 test.each(["worktree", "workspace"] as const)(
   "%s archive immediately removes the deleted worktree from a warm CLI listing",
   async (command) => {
diff --git a/packages/server/src/server/workspace-git-service.test.ts b/packages/server/src/server/workspace-git-service.test.ts
index 490807f8d6..d87e896ead 100644
--- a/packages/server/src/server/workspace-git-service.test.ts
+++ b/packages/server/src/server/workspace-git-service.test.ts
@@ -766,6 +766,35 @@ describe("WorkspaceGitServiceImpl", () => {
     service.dispose();
   });
 
+  test("a refresh requested after a mutation waits for a new snapshot", async () => {
+    const gate = createDeferred<CheckoutStatusGit>();
+    let reads = 0;
+    const service = createService({
+      getCheckoutStatus: (cwd: string) => {
+        reads += 1;
+        return reads === 1
+          ? gate.promise
+          : Promise.resolve(createCheckoutStatus(cwd, { currentBranch: "new-base" }));
+      },
+    });
+    const first = service.getSnapshot(REPO_CWD, {
+      force: true,
+      includeForge: false,
+      reason: "before-mutation",
+    });
+    await vi.waitFor(() => expect(reads).toBe(1));
+    const after = service.getSnapshot(REPO_CWD, {
+      force: true,
+      includeForge: false,
+      reason: "after-mutation",
+      afterInFlight: true,
+    });
+    gate.resolve(createCheckoutStatus(REPO_CWD, { currentBranch: "old-base" }));
+    await first;
+    expect((await after).git.currentBranch).toBe("new-base");
+    service.dispose();
+  });
+
   test("bounds refresh generations and re-enqueues hot workspace successors fairly", async () => {
     const hotCwds = Array.from({ length: WORKSPACE_GIT_REFRESH_CONCURRENCY }, (_, index) =>
       path.resolve(`/tmp/hot-repo-${index}`),
diff --git a/packages/server/src/server/workspace-git-service.ts b/packages/server/src/server/workspace-git-service.ts
index 668373e998..ea91186e9b 100644
--- a/packages/server/src/server/workspace-git-service.ts
+++ b/packages/server/src/server/workspace-git-service.ts
@@ -160,6 +160,7 @@ export interface WorkspaceGitRuntimeSnapshot {
     isPaseoOwnedWorktree: boolean;
     isDirty: boolean | null;
     baseRef: string | null;
+    baseRefExact?: string | null;
     aheadBehind: { ahead: number; behind: number } | null;
     upstreamRef: string | null;
     aheadOfOrigin: number | null;
@@ -296,6 +297,7 @@ export type WorkspaceGitReadOptions =
 export interface WorkspaceGitBranchSuggestionsOptions {
   query?: string;
   limit?: number;
+  refMode?: "exact";
 }
 
 export interface WorkspaceGitStashListOptions {
@@ -905,7 +907,13 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
     const normalizedCwd = resolve(cwd);
     const query = options?.query ?? "";
     const limit = options?.limit;
-    const key = JSON.stringify(["branch-suggestions", normalizedCwd, query, limit ?? null]);
+    const key = JSON.stringify([
+      "branch-suggestions",
+      normalizedCwd,
+      query,
+      limit ?? null,
+      options?.refMode,
+    ]);
     return this.readAuxiliaryCache(this.branchSuggestionsCache, key, readOptions, () =>
       this.deps.listBranchSuggestions(normalizedCwd, options),
     );
@@ -3573,6 +3581,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
 
     const cwd = target.cwd;
     const previousForgePrStatusPollKey = this.getForgePrStatusPollKey(target);
+    const previousBaseRef = target.latestFacts?.isGit ? target.latestFacts.resolvedBaseRef : null;
     const baseContext: CheckoutContext = {
       paseoHome: this.paseoHome,
       worktreesRoot: this.worktreesRoot,
@@ -3580,6 +3589,10 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
       runGitCommand: runRefreshGitCommand,
     };
     const facts = await this.loadCheckoutFacts(target, baseContext);
+    if (facts.isGit && facts.resolvedBaseRef !== previousBaseRef) {
+      this.invalidateCheckoutDiffCache(cwd, "base");
+      this.invalidateCheckoutDiffCache(facts.worktreeRoot, "base");
+    }
     const context: CheckoutContext = { ...baseContext, facts };
     const checkoutStatus = await this.deps.getCheckoutStatus(cwd, context);
     if (!checkoutStatus.isGit) {
@@ -3612,6 +3625,7 @@ export class WorkspaceGitServiceImpl implements WorkspaceGitService {
         ? checkoutStatus.isDirty
         : (target.latestGit?.isDirty ?? checkoutStatus.isDirty),
       baseRef: checkoutStatus.baseRef,
+      baseRefExact: checkoutStatus.baseRefExact,
       aheadBehind: checkoutStatus.aheadBehind,
       upstreamRef: checkoutStatus.upstreamRef,
       aheadOfOrigin: checkoutStatus.aheadOfOrigin,
diff --git a/packages/server/src/server/workspace-registry-model.ts b/packages/server/src/server/workspace-registry-model.ts
index 181ec96eae..3170281d60 100644
--- a/packages/server/src/server/workspace-registry-model.ts
+++ b/packages/server/src/server/workspace-registry-model.ts
@@ -108,7 +108,7 @@ export function initialWorkspacePlacement(
 
 /**
  * Applies live placement facts without rewriting the workspace's durable name
- * or its creation-time base branch.
+ * or its selected base branch.
  *
  * A null checkout is an absence, not an observation: nothing was read at the
  * workspace directory, so the recorded placement stands. Only a directory that
diff --git a/packages/server/src/server/workspace-registry.ts b/packages/server/src/server/workspace-registry.ts
index 474fc24829..351ba043e4 100644
--- a/packages/server/src/server/workspace-registry.ts
+++ b/packages/server/src/server/workspace-registry.ts
@@ -75,9 +75,9 @@ const PersistedWorkspaceRecordSchema = z.object({
   // archive and recovery do not need the directory to still exist in order to
   // recover placement.
   worktreeRoot: z.string().nullable().default(null),
-  // Comparison base preserved across worktree deletion and restore. New branch-off
+  // Current base preserved across worktree deletion and restore. New branch-off
   // workspaces store the resolved ref (e.g. refs/remotes/upstream/main); legacy and
-  // PR checkout records may contain a bare branch name. Ordinary checkouts use null.
+  // PR checkout records may contain a bare branch name. Null means no recorded base.
   baseBranch: z
     .string()
     .nullable()
diff --git a/packages/server/src/utils/checkout-git.test.ts b/packages/server/src/utils/checkout-git.test.ts
index bd52b0e49f..075f7ebda1 100644
--- a/packages/server/src/utils/checkout-git.test.ts
+++ b/packages/server/src/utils/checkout-git.test.ts
@@ -32,6 +32,7 @@ import {
   getCheckoutStatus,
   checkoutResolvedBranch,
   listBranchSuggestions,
+  setCheckoutBaseBranch,
   mergeToBase,
   mergeFromBase,
   MergeConflictError,
@@ -263,6 +264,56 @@ describe("checkout git utilities", () => {
     rmSync(tempDir, { recursive: true, force: true });
   });
 
+  it("rejects changing the base of a local checkout without creating metadata", async () => {
+    await expect(setCheckoutBaseBranch({ cwd: repoDir, baseRef: "main" })).rejects.toThrow();
+    expect(existsSync(await getPaseoWorktreeMetadataPath(repoDir))).toBe(false);
+  });
+
+  it("changing a managed worktree base preserves its runtime and PR identity", async () => {
+    const worktree = await createLegacyWorktreeForTest({
+      cwd: repoDir,
+      branchName: "feature/base",
+      baseBranch: "main",
+      worktreeSlug: "base",
+      paseoHome,
+      runSetup: false,
+    });
+    const original = await readPaseoWorktreeMetadata(worktree.worktreePath);
+    execFileSync("git", ["branch", "release"], { cwd: repoDir });
+    await setCheckoutBaseBranch({
+      cwd: worktree.worktreePath,
+      baseRef: "release",
+      context: { paseoHome },
+    });
+    expect(await readPaseoWorktreeMetadata(worktree.worktreePath)).toEqual({
+      ...original,
+      baseRefName: "release",
+      baseRef: "refs/heads/release",
+    });
+    expect(await getCheckoutSnapshotFacts(worktree.worktreePath, { paseoHome })).toMatchObject({
+      storedBaseRef: "refs/heads/release",
+    });
+  });
+
+  it("lists exact local and all remote refs separately for the base picker", async () => {
+    execFileSync("git", ["branch", "release"], { cwd: repoDir });
+    execFileSync("git", ["update-ref", "refs/remotes/origin/release", "HEAD"], { cwd: repoDir });
+    execFileSync("git", ["update-ref", "refs/remotes/upstream/release", "HEAD"], { cwd: repoDir });
+    const suggestions = await listBranchSuggestions(repoDir, {
+      refMode: "exact",
+      query: "release",
+    });
+    expect(suggestions.map((entry) => entry.name).sort()).toEqual([
+      "refs/heads/release",
+      "refs/remotes/origin/release",
+      "refs/remotes/upstream/release",
+    ]);
+    expect(suggestions.find((entry) => entry.name === "refs/heads/release")).toMatchObject({
+      hasLocal: true,
+      hasRemote: false,
+    });
+  });
+
   it("throws NotGitRepoError for non-git directories", async () => {
     const nonGitDir = join(tempDir, "not-git");
     mkdirSync(nonGitDir, { recursive: true });
@@ -1920,6 +1971,13 @@ const x = 1;
     expect(status.currentBranch).toBe("feature/plain");
   });
 
+  it("rejects merging a branch into its own same-named remote base", async () => {
+    execFileSync("git", ["update-ref", "refs/remotes/origin/main", "HEAD"], { cwd: repoDir });
+    await expect(mergeToBase(repoDir, { baseRef: "refs/remotes/origin/main" })).rejects.toThrow(
+      "Cannot merge a branch into itself",
+    );
+  });
+
   it("merges the current branch into base from a worktree checkout", async () => {
     const worktree = await createLegacyWorktreeForTest({
       branchName: "main",
diff --git a/packages/server/src/utils/checkout-git.ts b/packages/server/src/utils/checkout-git.ts
index a0cbaa7afc..d793e2c683 100644
--- a/packages/server/src/utils/checkout-git.ts
+++ b/packages/server/src/utils/checkout-git.ts
@@ -51,6 +51,7 @@ import {
   type PaseoWorktreeMetadata,
   readPaseoWorktreeMetadata,
   rebindPaseoWorktreeChangeRequestHint,
+  setPaseoWorktreeBaseRef,
 } from "./worktree-metadata.js";
 const READ_ONLY_GIT_ENV = {
   GIT_OPTIONAL_LOCKS: "0",
@@ -323,15 +324,30 @@ function sortBranchSuggestions(
 
 export async function listBranchSuggestions(
   cwd: string,
-  options?: { query?: string; limit?: number },
+  options: { query?: string; limit?: number; refMode?: "exact" } = {},
 ): Promise<BranchSuggestion[]> {
   await requireGitRepo(cwd);
 
-  const requestedLimit = options?.limit ?? 50;
+  const requestedLimit = options.limit ?? 50;
   const limit = Math.max(1, Math.min(200, requestedLimit));
-  const rawQuery = options?.query?.trim().toLowerCase() ?? "";
+  const rawQuery = options.query?.trim().toLowerCase() ?? "";
   const query = normalizeBranchSuggestionName(rawQuery) ?? rawQuery;
 
+  if (options.refMode === "exact") {
+    const refs = await listGitRefs(cwd, "refs");
+    const branches = refs.filter((ref) => {
+      const isBranch = ref.name.startsWith("refs/heads/") || ref.name.startsWith("refs/remotes/");
+      return isBranch && !ref.name.endsWith("/HEAD") && ref.name.toLowerCase().includes(rawQuery);
+    });
+    branches.sort((a, b) => b.committerDate - a.committerDate || a.name.localeCompare(b.name));
+    return branches.slice(0, limit).map((ref) => ({
+      name: ref.name,
+      committerDate: ref.committerDate,
+      hasLocal: ref.name.startsWith("refs/heads/"),
+      hasRemote: ref.name.startsWith("refs/remotes/"),
+    }));
+  }
+
   const [localRefs, remoteRefs] = await Promise.all([
     listGitRefs(cwd, "refs/heads"),
     listGitRefs(cwd, "refs/remotes/origin"),
@@ -889,6 +905,7 @@ export interface CheckoutStatusGitNonPaseo {
   currentBranch: string | null;
   isDirty: boolean;
   baseRef: string | null;
+  baseRefExact?: string | null;
   aheadBehind: AheadBehind | null;
   // Remote-tracking ref for currentBranch, e.g. "refs/remotes/origin/main". Null when the
   // branch has no upstream or git could not resolve it. aheadOfOrigin/behindOfOrigin are
@@ -908,6 +925,7 @@ export interface CheckoutStatusGitPaseo {
   currentBranch: string | null;
   isDirty: boolean;
   baseRef: string;
+  baseRefExact?: string | null;
   aheadBehind: AheadBehind | null;
   upstreamRef: string | null;
   aheadOfOrigin: number | null;
@@ -1308,12 +1326,36 @@ async function getStoredBaseRefForCwd(
   if (context?.facts?.isGit) {
     return context.facts.storedBaseRef;
   }
-  const paseoWorktree = await getPaseoWorktreeForCwd(cwd, { context });
-  if (!paseoWorktree.isPaseoOwnedWorktree) {
-    return null;
-  }
+  const ownership = await getPaseoWorktreeForCwd(cwd, { context });
+  return ownership.isPaseoOwnedWorktree ? readPaseoWorktreeBaseRef(ownership.worktreeRoot) : null;
+}
 
-  return readPaseoWorktreeBaseRef(paseoWorktree.worktreeRoot);
+export async function setCheckoutBaseBranch(input: {
+  cwd: string;
+  baseRef: string;
+  context?: CheckoutContext;
+}): Promise<string> {
+  await requireGitRepo(input.cwd);
+  const ownership = await getPaseoWorktreeForCwd(input.cwd, { context: input.context });
+  if (!ownership.isPaseoOwnedWorktree) throw new Error("Workspace is not a Paseo worktree");
+  const requested = input.baseRef.trim();
+  const qualified = requested.startsWith("refs/");
+  const candidates = qualified
+    ? [requested]
+    : [`refs/heads/${requested}`, `refs/remotes/${requested}`, `refs/remotes/origin/${requested}`];
+  for (const candidate of candidates) {
+    if (!isQualifiedBranchRef(candidate) || candidate.endsWith("/HEAD")) continue;
+    const valid = await runGitCommand(["check-ref-format", candidate], {
+      cwd: input.cwd,
+      acceptExitCodes: [0, 1],
+    });
+    if (valid.exitCode !== 0 || !(await doesGitRefExist(input.cwd, candidate))) continue;
+    const worktreeRoot = await getWorktreeRoot(input.cwd);
+    if (!worktreeRoot) throw new NotGitRepoError(input.cwd);
+    await setPaseoWorktreeBaseRef({ worktreeRoot, baseRef: candidate });
+    return candidate;
+  }
+  throw new Error(`Base branch not found: ${requested}`);
 }
 
 async function getResolvedBaseRefForCwd(
@@ -1786,7 +1828,11 @@ async function getAheadBehind(
   context?: CheckoutContext,
 ): Promise<AheadBehind | null> {
   const normalizedBaseRef = branchNameFromRef(baseRef);
-  if (!normalizedBaseRef || !currentBranch || normalizedBaseRef === currentBranch) {
+  if (
+    !normalizedBaseRef ||
+    !currentBranch ||
+    (!isQualifiedBranchRef(baseRef) && normalizedBaseRef === currentBranch)
+  ) {
     return null;
   }
   const comparisonBaseRef =
@@ -2128,7 +2174,8 @@ export async function getCheckoutSnapshotFacts(
   if (
     resolvedBaseRef &&
     inspected.currentBranch &&
-    branchNameFromRef(resolvedBaseRef) !== inspected.currentBranch
+    (isQualifiedBranchRef(resolvedBaseRef) ||
+      branchNameFromRef(resolvedBaseRef) !== inspected.currentBranch)
   ) {
     comparisonBaseRef = await resolveBestComparisonBaseRef(cwd, resolvedBaseRef, context).catch(
       () => null,
@@ -2373,6 +2420,7 @@ export async function getCheckoutStatus(
       currentBranch,
       isDirty,
       baseRef: displayBaseRef ?? baseRef,
+      baseRefExact: baseRef,
       aheadBehind,
       upstreamRef,
       aheadOfOrigin,
@@ -2391,6 +2439,7 @@ export async function getCheckoutStatus(
     currentBranch,
     isDirty,
     baseRef: displayBaseRef,
+    baseRefExact: baseRef,
     aheadBehind,
     upstreamRef,
     aheadOfOrigin,
@@ -2605,7 +2654,10 @@ async function tryResolveCheckoutCommitsBaseRef(
     return null;
   }
   const normalizedBaseRef = branchNameFromRef(baseRef);
-  if (!normalizedBaseRef || normalizedBaseRef === currentBranch) {
+  if (
+    !normalizedBaseRef ||
+    (!isQualifiedBranchRef(baseRef) && normalizedBaseRef === currentBranch)
+  ) {
     return null;
   }
   try {
@@ -3890,7 +3942,7 @@ export async function mergeToBase(
   const normalizedBaseRef = resolveMergeTargetBranch(baseRef);
   const currentWorktreeRoot = (await getWorktreeRoot(cwd, context)) ?? cwd;
   if (normalizedBaseRef === currentBranch) {
-    return currentWorktreeRoot;
+    throw new Error("Cannot merge a branch into itself");
   }
 
   const baseWorktree = await getWorktreePathForBranch(cwd, normalizedBaseRef);
diff --git a/packages/server/src/utils/worktree-metadata.ts b/packages/server/src/utils/worktree-metadata.ts
index fcb0454672..fc4488d742 100644
--- a/packages/server/src/utils/worktree-metadata.ts
+++ b/packages/server/src/utils/worktree-metadata.ts
@@ -14,7 +14,7 @@ const ChangeRequestLookupTargetSchema = z.object({
   localBranchName: z.string().min(1).optional(),
 });
 
-// baseRefName is the display name; baseRef is the exact ref the worktree was cut from
+// baseRefName is the display name; baseRef is the checkout's current exact base
 // ("refs/remotes/upstream/main"). baseRef is optional because worktrees written before it
 // existed only have the name — there are no migrations, so readers fall back.
 const PaseoWorktreeMetadataV1Schema = z.object({
@@ -249,6 +249,21 @@ export async function writePaseoWorktreeMetadata(
   });
 }
 
+export async function setPaseoWorktreeBaseRef(input: {
+  worktreeRoot: string;
+  baseRef: string;
+}): Promise<void> {
+  return mutateMetadata(input.worktreeRoot, async (root) => {
+    const current = await readMetadataFile(root);
+    if (!current) throw new Error("Cannot change base: missing worktree metadata");
+    await writePaseoWorktreeMetadataFile(root, {
+      ...current,
+      baseRefName: branchNameFromRef(input.baseRef),
+      baseRef: input.baseRef,
+    });
+  });
+}
+
 export async function writePaseoWorktreeRuntimeMetadata(
   worktreeRoot: string,
   options: { worktreePort: number },

From a68dc55490812605a174d7f01b45a62e0a0a74f5 Mon Sep 17 00:00:00 2001
From: Okan YILDIRIM <63511519+ragokan@users.noreply.github.com>
Date: Fri, 6 Nov 2026 03:03:57 +0000
Subject: [PATCH 26/29] fix(app): refresh visible usage summaries periodically
 (#7806)

---
 .../e2e/browser/usage-sidebar-item.spec.ts    | 108 +++++++++++++++++-
 packages/app/src/usage/queries.ts             |  21 ++--
 packages/app/src/usage/sidebar-item.tsx       |   9 +-
 3 files changed, 129 insertions(+), 9 deletions(-)

diff --git a/packages/app/e2e/browser/usage-sidebar-item.spec.ts b/packages/app/e2e/browser/usage-sidebar-item.spec.ts
index 9151403904..8d206f35e8 100644
--- a/packages/app/e2e/browser/usage-sidebar-item.spec.ts
+++ b/packages/app/e2e/browser/usage-sidebar-item.spec.ts
@@ -8,7 +8,7 @@ import {
   openProjectViaDaemon,
 } from "../support/helpers/new-workspace";
 import { getServerId } from "../support/helpers/server-id";
-import { openSettingsHostSection } from "../support/helpers/settings";
+import { openCompactSettings, openSettingsHostSection } from "../support/helpers/settings";
 import {
   expectFooterItemSetting,
   expectFooterSeparator,
@@ -42,6 +42,7 @@ import {
 import { seedSidebarFooterPreferences } from "../support/helpers/sidebar-nav-settings";
 import { waitForSettledPosition } from "../support/helpers/sheet-layout";
 import { createTempGitRepo } from "../support/helpers/workspace";
+import { buildOpenProjectRoute } from "@/utils/host-routes";
 
 const WIDE = { width: 1440, height: 900 };
 const COMPACT = { width: 390, height: 844 };
@@ -70,7 +71,112 @@ async function footerClip(page: Page) {
   return (await page.locator('[data-testid="sidebar-footer"]:visible').boundingBox())!;
 }
 
+async function setPageVisibility(page: Page, visibility: DocumentVisibilityState): Promise<void> {
+  await page.evaluate((state) => {
+    Object.defineProperty(document, "visibilityState", { configurable: true, get: () => state });
+    Object.defineProperty(document, "hidden", {
+      configurable: true,
+      get: () => state === "hidden",
+    });
+    document.dispatchEvent(new Event("visibilitychange"));
+  }, visibility);
+}
+
 test.describe("Usage item", () => {
+  test("visible summary refreshes every five minutes without opening Usage", async ({ page }) => {
+    let usedPct = 31;
+    const usage = await installUsageReportsFixture(page, {
+      lists: [
+        () => [
+          {
+            ...claudeAndCodexReports()[0]!,
+            report: {
+              status: "available",
+              windows: [
+                { id: "five_hour", label: "Session", shortLabel: "5h", summary: true, usedPct },
+              ],
+            },
+          },
+        ],
+      ],
+    });
+    await page.clock.install();
+    await page.setViewportSize(WIDE);
+    await seedSidebarFooterPreferences(page, [{ key: "usage", visible: true }]);
+    await gotoAppShell(page);
+    await expectPinnedUsage(page, ["31% 5h"]);
+    const startingUrl = page.url();
+    await qaScreenshot(page, "usage-auto-refresh-initial", { kind: "footer" });
+    const requestsBeforeRefresh = usage.listRequests();
+
+    usedPct = 42;
+    await page.clock.fastForward(5 * 60_000);
+    await qaScreenshot(page, "usage-auto-refresh-after-interval", { kind: "footer" });
+    await expectPinnedUsage(page, ["42% 5h"]);
+    await expect(usageModal(page)).toHaveCount(0);
+    await expect(page).toHaveURL(startingUrl);
+    expect(usage.listRequests()).toEqual([
+      ...requestsBeforeRefresh,
+      { forceRefresh: false, reportIds: undefined, agentId: undefined },
+    ]);
+
+    await setPageVisibility(page, "hidden");
+    const requestsBeforeBackgrounding = usage.listRequests();
+    usedPct = 47;
+    await page.clock.fastForward(5 * 60_000);
+    expect(usage.listRequests()).toEqual(requestsBeforeBackgrounding);
+    await expectPinnedUsage(page, ["42% 5h"]);
+    await setPageVisibility(page, "visible");
+    await page.clock.fastForward(5 * 60_000);
+    await expectPinnedUsage(page, ["47% 5h"]);
+    expect(usage.listRequests()).toEqual([
+      ...requestsBeforeBackgrounding,
+      { forceRefresh: false, reportIds: undefined, agentId: undefined },
+    ]);
+
+    await page.setViewportSize(COMPACT);
+    await expect(usageItem(page)).toHaveCount(0);
+    const requestsBeforeHiding = usage.listRequests();
+    await page.clock.fastForward(5 * 60_000);
+    expect(usage.listRequests()).toEqual(requestsBeforeHiding);
+
+    await openCompactSidebar(page);
+    await expectPinnedUsage(page, ["47% 5h"]);
+    await expect(page.getByTestId("agent-list-backdrop")).toBeVisible();
+    usedPct = 53;
+    await page.clock.fastForward(5 * 60_000);
+    await expectPinnedUsage(page, ["53% 5h"]);
+    await expect(usageModal(page)).toHaveCount(0);
+
+    await page.setViewportSize(WIDE);
+    await openSidebarNavSettings(page);
+    await setFooterItemVisible(page, "usage", false);
+    await leaveSettings(page);
+    await expectNoUsageItem(page);
+    const requestsBeforeDisabling = usage.listRequests();
+    await page.clock.fastForward(5 * 60_000);
+    expect(usage.listRequests()).toEqual(requestsBeforeDisabling);
+  });
+
+  test("Usage settings do not poll reports while the sidebar is inactive", async ({ page }) => {
+    const usage = await installUsageReportsFixture(page, {
+      lists: [() => claudeAndCodexReports()],
+    });
+    await page.clock.install();
+    await page.setViewportSize(COMPACT);
+    await seedSidebarFooterPreferences(page, [{ key: "usage", visible: true }]);
+    await gotoAppShell(page);
+    await openCompactSettings(page, buildOpenProjectRoute());
+    await openSettingsHostSection(page, getServerId(), "usage");
+    await expect(page.getByTestId("usage-card").getByText("31% used")).toBeVisible();
+    await expect(usageItem(page)).toHaveCount(0);
+    const requestsBeforeWaiting = usage.listRequests();
+
+    await page.clock.fastForward(5 * 60_000);
+    expect(usage.listRequests()).toEqual(requestsBeforeWaiting);
+    await expect(page.getByTestId("usage-card").getByText("31% used")).toBeVisible();
+  });
+
   test("both compact footer entry points open Usage as a sheet", async ({ page }) => {
     await page.setViewportSize(COMPACT);
     await installUsageReportsFixture(page, { lists: [() => claudeAndCodexReports()] });
diff --git a/packages/app/src/usage/queries.ts b/packages/app/src/usage/queries.ts
index 524972a010..bac8bd7ffa 100644
--- a/packages/app/src/usage/queries.ts
+++ b/packages/app/src/usage/queries.ts
@@ -33,9 +33,10 @@ import {
 } from "./model";
 import type { UsageReportEntry, UsageView } from "./types";
 
-// The daemon caches each report for five minutes, so re-reading it is cheap. Only
-// an explicit refresh passes `forceRefresh` and reaches the source's API.
+// The daemon caches each report for five minutes, so re-reading it is cheap.
+// An explicit refresh passes `forceRefresh` to bypass that cache.
 const REPORTS_STALE_TIME_MS = 60_000;
+const REPORTS_REFETCH_INTERVAL_MS = 5 * 60_000;
 
 /** Every report list of a host: its own and each agent's. */
 function hostUsageQueryKey(serverId: string) {
@@ -164,11 +165,16 @@ export function useHostUsage(serverId: string): { view: UsageView; refresh: () =
 
 const NO_REPORTS: UsageReportEntry[] = [];
 
-/**
- * The reports of the sidebar's usage host, which is connected and reports usage; none until they
- * load, or without a host.
- */
-export function useUsageHostReports(serverId: string | null): UsageReportEntry[] {
+interface UsageHostReportsInput {
+  serverId: string | null;
+  shouldPoll?: boolean;
+}
+
+/** A host's reports, with periodic refresh enabled only by the visible sidebar summary. */
+export function useUsageHostReports({
+  serverId,
+  shouldPoll = false,
+}: UsageHostReportsInput): UsageReportEntry[] {
   const setting = useUsageSetting(serverId);
   const queryClient = useQueryClient();
   const query = useFetchQuery({
@@ -177,6 +183,7 @@ export function useUsageHostReports(serverId: string | null): UsageReportEntry[]
     queryFn: serverId ? () => listReports(queryClient, serverId) : skipToken,
     dataShape: "list",
     staleTimeMs: REPORTS_STALE_TIME_MS,
+    refetchInterval: shouldPoll ? REPORTS_REFETCH_INTERVAL_MS : false,
   });
   return setting.enabled ? (query.data ?? NO_REPORTS) : NO_REPORTS;
 }
diff --git a/packages/app/src/usage/sidebar-item.tsx b/packages/app/src/usage/sidebar-item.tsx
index 437c0a929c..bd4dfeb65e 100644
--- a/packages/app/src/usage/sidebar-item.tsx
+++ b/packages/app/src/usage/sidebar-item.tsx
@@ -16,6 +16,8 @@ import {
   type PressableStateCallbackType,
 } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
+import { useRetainedPanelActive } from "@/components/retained-panel";
+import { useAppVisible } from "@/hooks/use-app-visible";
 import { builtinSidebarNavLabelKey } from "@/sidebar-nav/model";
 import { useUsageDisplay } from "./display";
 import { useUsageInSidebar } from "./in-sidebar";
@@ -36,9 +38,14 @@ import { UsageModal } from "./usage-modal";
 /** Each summary window with data on the usage host, under its source; empty while none has. */
 export function useUsageSummary(): readonly PinnedUsageSource[] {
   const { t } = useTranslation();
+  const active = useRetainedPanelActive();
+  const isAppVisible = useAppVisible();
   const { inSidebar } = useUsageInSidebar();
   const serverId = useUsageHostId();
-  const reports = useUsageHostReports(inSidebar ? serverId : null);
+  const reports = useUsageHostReports({
+    serverId: inSidebar ? serverId : null,
+    shouldPoll: active && inSidebar && isAppVisible,
+  });
   const { preferences } = useUsageDisplay(reports);
   return useMemo(() => resolvePinnedUsage(reports, preferences, t), [preferences, reports, t]);
 }

From 8b9c42c26683e69db724318e8272f2d9e90f6fc1 Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Fri, 6 Nov 2026 10:28:38 +0700
Subject: [PATCH 27/29] Keep every sidebar footer action reachable in a narrow
 sidebar (#8885)

* fix(app): move sidebar footer actions that don't fit behind a caret

Touch sizing makes each footer icon a 44pt target, so five of them plus
the row's padding need 236pt. A docked sidebar can be 200pt and a fold
column about as narrow, so Settings was cut off at the sidebar's edge.

The row now measures itself and keeps as many full-size buttons as fit;
the rest move behind a caret that opens a menu-engine popover. Help and
Usage leave first, Settings and Add project last, and Hosts and Help
open as pages of the overflow menu rather than second popovers.

* fix(app): keep the sidebar footer empty until it has measured

Laying the footer out before its first onLayout put all five buttons in
the row, so a narrow sidebar painted Settings clipped for a few frames
before the caret replaced it. The unmeasured row now places nothing and
holds its height, so the first painted row is already the measured one.

* fix(app): keep the footer overflow menu on a narrow, short screen

The overflow menu asked for 240pt, and edge clamping can move a surface
but not shrink it, so on a 220pt screen its right edge and submenu
arrows hung off the display. Anchored surfaces now cap their width to
the display inside the same edge padding that clamping uses.

The Hosts page lists every host, so the overflow menu is scrollable:
on a short screen the last hosts and Add host were below the fold with
no way to reach them.
---
 docs/menus.md                                 |   5 +-
 .../browser/sidebar-footer-overflow.spec.ts   | 127 +++++++++
 packages/app/e2e/support/helpers/hosts.ts     |  36 ++-
 .../helpers/sidebar-footer-overflow.ts        | 127 +++++++++
 packages/app/src/components/left-sidebar.tsx  | 103 ++++++--
 .../components/sidebar-footer-layout.test.ts  |  89 +++++++
 .../src/components/sidebar-footer-layout.ts   |  62 +++++
 .../sidebar/sidebar-footer-menu-trigger.tsx   |  69 +++++
 .../sidebar/sidebar-footer-overflow-menu.tsx  | 245 ++++++++++++++++++
 .../components/sidebar/sidebar-help-menu.tsx  | 172 ++++++------
 packages/app/src/components/ui/anchor.test.ts |  25 +-
 packages/app/src/components/ui/anchor.ts      |  21 ++
 .../src/components/ui/menu/menu-overlay.tsx   |   7 +-
 packages/app/src/i18n/resources/ar.ts         |   1 +
 packages/app/src/i18n/resources/en.ts         |   1 +
 packages/app/src/i18n/resources/es.ts         |   1 +
 packages/app/src/i18n/resources/fr.ts         |   1 +
 packages/app/src/i18n/resources/ja.ts         |   1 +
 packages/app/src/i18n/resources/ko.ts         |   1 +
 packages/app/src/i18n/resources/pt-BR.ts      |   1 +
 packages/app/src/i18n/resources/ru.ts         |   1 +
 packages/app/src/i18n/resources/zh-CN.ts      |   1 +
 22 files changed, 956 insertions(+), 141 deletions(-)
 create mode 100644 packages/app/e2e/browser/sidebar-footer-overflow.spec.ts
 create mode 100644 packages/app/e2e/support/helpers/sidebar-footer-overflow.ts
 create mode 100644 packages/app/src/components/sidebar-footer-layout.test.ts
 create mode 100644 packages/app/src/components/sidebar-footer-layout.ts
 create mode 100644 packages/app/src/components/sidebar/sidebar-footer-menu-trigger.tsx
 create mode 100644 packages/app/src/components/sidebar/sidebar-footer-overflow-menu.tsx

diff --git a/docs/menus.md b/docs/menus.md
index 590def2b33..3e29e13ac3 100644
--- a/docs/menus.md
+++ b/docs/menus.md
@@ -226,7 +226,8 @@ its own.
   inactive. An async action can navigate before its menu closes; a hidden panel must not leave a
   portal backdrop blocking the destination. On web the chat suspends one commit after it goes
   inactive, and that inactive commit is where the surface unmounts.
-- Anchoring, flipping, and edge clamping live in `components/ui/anchor.ts`, shared with the hover
-  card, and are unit-tested. Fix positioning bugs there, not at a call site.
+- Anchoring, flipping, edge clamping, and capping a surface's width to the display live in
+  `components/ui/anchor.ts`, shared with the hover card, and are unit-tested. Clamping moves a
+  surface but cannot shrink it, so the width cap is what keeps a wide menu on a narrow screen. Fix positioning bugs there, not at a call site.
 - Everything else about floating surfaces on Android — Portal/Modal escape, lifecycle gates,
   status-bar offset, the open flash — is in [floating-panels.md](floating-panels.md).
diff --git a/packages/app/e2e/browser/sidebar-footer-overflow.spec.ts b/packages/app/e2e/browser/sidebar-footer-overflow.spec.ts
new file mode 100644
index 0000000000..da16dbb648
--- /dev/null
+++ b/packages/app/e2e/browser/sidebar-footer-overflow.spec.ts
@@ -0,0 +1,127 @@
+import { expect, test } from "../support/fixtures";
+import { addProjectFlow } from "../support/helpers/add-project-flow";
+import { gotoAppShell } from "../support/helpers/app";
+import {
+  chooseFooterOverflowAction,
+  expectFooterLine,
+  expectFooterMenusInsideViewport,
+  expectFooterNeverClipped,
+  expectFooterOverflowActions,
+  footerOverflowMenu,
+  openFooterOverflow,
+  seedDockedSidebarWidth,
+  watchFooterClipping,
+} from "../support/helpers/sidebar-footer-overflow";
+import { addOfflineHostsAndReload } from "../support/helpers/hosts";
+import { openCompactSidebar } from "../support/helpers/usage-sidebar-item";
+
+const TOUCH_CONTROL = 44;
+const MIN_SIDEBAR_WIDTH = 200;
+const ALL_INLINE = [
+  "sidebar-add-project",
+  "sidebar-usage-icon",
+  "sidebar-hosts-trigger",
+  "sidebar-help",
+  "sidebar-settings",
+];
+// Five 44pt buttons and the row's padding need 236pt; 200pt holds three and the caret.
+const NARROW_TOUCH_LINE = [
+  "sidebar-add-project",
+  "sidebar-hosts-trigger",
+  "sidebar-footer-overflow",
+  "sidebar-settings",
+];
+
+test.describe("Sidebar footer on a touch screen", () => {
+  test.use({ viewport: { width: 1280, height: 800 }, hasTouch: true });
+
+  test("a narrow docked sidebar moves the actions it can't fit behind a caret", async ({
+    page,
+  }) => {
+    await seedDockedSidebarWidth(page, MIN_SIDEBAR_WIDTH);
+    await watchFooterClipping(page);
+    await gotoAppShell(page);
+    await expectFooterLine(page, { testIDs: NARROW_TOUCH_LINE, controlSize: TOUCH_CONTROL });
+    await expectFooterNeverClipped(page);
+
+    await test.step("Help opens as a page of the overflow menu", async () => {
+      await openFooterOverflow(page);
+      await expectFooterOverflowActions(page, ["Usage", "Help and support"]);
+      await chooseFooterOverflowAction(page, "Help and support");
+      await expect(page.getByRole("menuitem", { name: "What's new" })).toBeVisible();
+      await expect(page.getByTestId("sidebar-help-menu")).toHaveCount(0);
+      await page.keyboard.press("Escape");
+      await expect(footerOverflowMenu(page)).toBeHidden();
+    });
+
+    await test.step("Usage opens from the overflow menu", async () => {
+      await openFooterOverflow(page);
+      await chooseFooterOverflowAction(page, "Usage");
+      await expect(footerOverflowMenu(page)).toBeHidden();
+      await expect(page.getByTestId("usage-modal")).toBeVisible();
+      await page.keyboard.press("Escape");
+      await expect(page.getByTestId("usage-modal")).toBeHidden();
+    });
+
+    await test.step("Add project and Settings shortcuts still work", async () => {
+      await page.keyboard.press("Control+o");
+      await expect(addProjectFlow(page)).toBeVisible();
+      await page.keyboard.press("Escape");
+      await expect(addProjectFlow(page)).toBeHidden();
+      await page.keyboard.press("Control+,");
+      await expect(page).toHaveURL(/\/settings\/general$/);
+    });
+  });
+
+  test("the default sidebar width keeps all five actions inline", async ({ page }) => {
+    await gotoAppShell(page);
+    await expectFooterLine(page, { testIDs: ALL_INLINE, controlSize: TOUCH_CONTROL });
+  });
+});
+
+test.describe("Sidebar footer in a compact overlay narrower than the footer", () => {
+  test.use({ viewport: { width: 220, height: 800 }, hasTouch: true });
+
+  test("the overflow menu reaches the hidden actions", async ({ page }) => {
+    await watchFooterClipping(page);
+    await gotoAppShell(page);
+    await openCompactSidebar(page);
+    await expectFooterLine(page, { testIDs: NARROW_TOUCH_LINE, controlSize: TOUCH_CONTROL });
+    await expectFooterNeverClipped(page);
+    await openFooterOverflow(page);
+    await expectFooterOverflowActions(page, ["Usage", "Help and support"]);
+    await expectFooterMenusInsideViewport(page);
+  });
+});
+
+test.describe("Sidebar footer on a short, narrow phone", () => {
+  // 164pt for buttons holds Settings, Add project and the caret, so Hosts moves behind it.
+  test.use({ viewport: { width: 180, height: 360 }, hasTouch: true });
+
+  test("the overflow Hosts page scrolls to its last host and Add host", async ({ page }) => {
+    await gotoAppShell(page);
+    await addOfflineHostsAndReload(
+      page,
+      Array.from({ length: 10 }, (_, index) => ({
+        serverId: `overflow-host-${index}`,
+        label: `Overflow host ${index}`,
+      })),
+    );
+    await openCompactSidebar(page);
+    await expectFooterLine(page, {
+      testIDs: ["sidebar-add-project", "sidebar-footer-overflow", "sidebar-settings"],
+      controlSize: TOUCH_CONTROL,
+    });
+    await openFooterOverflow(page);
+    await expectFooterOverflowActions(page, ["Usage", "Hosts", "Help and support"]);
+    await expectFooterMenusInsideViewport(page);
+    await chooseFooterOverflowAction(page, "Hosts");
+    await expectFooterMenusInsideViewport(page);
+    const addHost = page.getByRole("menuitem", { name: "Add host" });
+    await addHost.scrollIntoViewIfNeeded();
+    await expect(page.getByRole("menuitem", { name: "Overflow host 9" })).toBeVisible();
+    await expect(addHost).toBeInViewport();
+    await addHost.click();
+    await expect(page.getByText("Add connection", { exact: true })).toBeVisible();
+  });
+});
diff --git a/packages/app/e2e/support/helpers/hosts.ts b/packages/app/e2e/support/helpers/hosts.ts
index 69e0c4b9f5..0e0a9f56fe 100644
--- a/packages/app/e2e/support/helpers/hosts.ts
+++ b/packages/app/e2e/support/helpers/hosts.ts
@@ -22,15 +22,27 @@ export async function addOfflineHostAndReload(
   page: Page,
   input: { serverId: string; label: string; primaryLabel?: string },
 ): Promise<void> {
-  const offlineHost = buildSeededHost({
-    serverId: input.serverId,
-    label: input.label,
-    endpoint: "127.0.0.1:59999",
-    nowIso: new Date().toISOString(),
-  });
+  await addOfflineHostsAndReload(page, [input], { primaryLabel: input.primaryLabel });
+}
+
+/** Adds several unreachable hosts with one reload. See `addOfflineHostAndReload`. */
+export async function addOfflineHostsAndReload(
+  page: Page,
+  hosts: Array<{ serverId: string; label: string }>,
+  options: { primaryLabel?: string } = {},
+): Promise<void> {
+  const nowIso = new Date().toISOString();
+  const offlineHosts = hosts.map((host) =>
+    buildSeededHost({
+      serverId: host.serverId,
+      label: host.label,
+      endpoint: "127.0.0.1:59999",
+      nowIso,
+    }),
+  );
 
   await page.evaluate(
-    ({ host, keys, primaryLabel }) => {
+    ({ hosts: added, keys, primaryLabel }) => {
       const nonce = localStorage.getItem(keys.nonce);
       if (!nonce) {
         throw new Error("Expected the e2e seed nonce before overriding the host registry.");
@@ -40,20 +52,22 @@ export async function addOfflineHostAndReload(
       if (primaryLabel && registry[0]) {
         registry[0].label = primaryLabel;
       }
-      if (!registry.some((entry) => entry.serverId === host.serverId)) {
-        registry.push(host);
+      for (const host of added) {
+        if (!registry.some((entry) => entry.serverId === host.serverId)) {
+          registry.push(host);
+        }
       }
       localStorage.setItem(keys.registry, JSON.stringify(registry));
       localStorage.setItem(keys.disableSeedOnce, nonce);
     },
     {
-      host: offlineHost,
+      hosts: offlineHosts,
       keys: {
         registry: REGISTRY_KEY,
         nonce: SEED_NONCE_KEY,
         disableSeedOnce: DISABLE_DEFAULT_SEED_ONCE_KEY,
       },
-      primaryLabel: input.primaryLabel,
+      primaryLabel: options.primaryLabel,
     },
   );
 
diff --git a/packages/app/e2e/support/helpers/sidebar-footer-overflow.ts b/packages/app/e2e/support/helpers/sidebar-footer-overflow.ts
new file mode 100644
index 0000000000..85983578df
--- /dev/null
+++ b/packages/app/e2e/support/helpers/sidebar-footer-overflow.ts
@@ -0,0 +1,127 @@
+import { expect, type Locator, type Page } from "@playwright/test";
+
+/** Every footer control that can sit in the icon line, caret included. */
+const FOOTER_LINE_TEST_IDS = [
+  "sidebar-add-project",
+  "sidebar-usage-icon",
+  "sidebar-hosts-trigger",
+  "sidebar-help",
+  "sidebar-footer-overflow",
+  "sidebar-settings",
+];
+
+// Browser layout boxes include floating-point rounding, even for whole-pixel styles.
+const GEOMETRY_TOLERANCE = 0.01;
+
+/** Open the app with the docked sidebar at `width`, as if the user had dragged it there. */
+export async function seedDockedSidebarWidth(page: Page, width: number): Promise<void> {
+  await page.addInitScript((sidebarWidth) => {
+    localStorage.setItem("panel-state", JSON.stringify({ version: 17, state: { sidebarWidth } }));
+  }, width);
+}
+
+/**
+ * From the first frame, record any frame in which a footer button reaches past its row, so a row
+ * laid out before it measured shows up even if it lasted one frame.
+ */
+export async function watchFooterClipping(page: Page): Promise<void> {
+  await page.addInitScript((testIDs) => {
+    const clippedFrames: string[] = [];
+    Object.assign(window, { __footerClippedFrames: clippedFrames });
+    const sample = () => {
+      for (const row of document.querySelectorAll('[data-testid="sidebar-footer-bottom-line"]')) {
+        const rowRect = row.getBoundingClientRect();
+        if (rowRect.width === 0) continue;
+        for (const testID of testIDs) {
+          const button = row.querySelector(`[data-testid="${testID}"]`);
+          if (button && button.getBoundingClientRect().right > rowRect.right + 0.5) {
+            clippedFrames.push(testID);
+          }
+        }
+      }
+      requestAnimationFrame(sample);
+    };
+    requestAnimationFrame(sample);
+  }, FOOTER_LINE_TEST_IDS);
+}
+
+export async function expectFooterNeverClipped(page: Page): Promise<void> {
+  const clipped = await page.evaluate(
+    () => (window as unknown as { __footerClippedFrames: string[] }).__footerClippedFrames,
+  );
+  expect(clipped).toEqual([]);
+}
+
+function footerLine(page: Page): Locator {
+  return page.locator('[data-testid="sidebar-footer-bottom-line"]:visible');
+}
+
+export function footerOverflowMenu(page: Page): Locator {
+  return page.getByTestId("sidebar-footer-overflow-menu");
+}
+
+/**
+ * The icon line shows exactly `testIDs`, in order, each `controlSize` square and wholly inside the
+ * line's box, so no button is cut off by the sidebar's edge.
+ */
+export async function expectFooterLine(
+  page: Page,
+  input: { testIDs: string[]; controlSize: number },
+): Promise<void> {
+  const line = footerLine(page);
+  await expect(line).toHaveCount(1);
+  await expect
+    .poll(async () =>
+      line
+        .locator(FOOTER_LINE_TEST_IDS.map((testID) => `[data-testid="${testID}"]`).join(","))
+        .evaluateAll((elements) => elements.map((element) => element.getAttribute("data-testid"))),
+    )
+    .toEqual(input.testIDs);
+  const { row, buttons } = await line.evaluate((element, testIDs) => {
+    const rect = (node: Element) => {
+      const { x, width, height } = node.getBoundingClientRect();
+      return { x, width, height };
+    };
+    return {
+      row: rect(element),
+      buttons: testIDs.map((testID) => rect(element.querySelector(`[data-testid="${testID}"]`)!)),
+    };
+  }, input.testIDs);
+  for (const button of buttons) {
+    expect(Math.abs(button.width - input.controlSize)).toBeLessThan(GEOMETRY_TOLERANCE);
+    expect(Math.abs(button.height - input.controlSize)).toBeLessThan(GEOMETRY_TOLERANCE);
+    expect(button.x).toBeGreaterThanOrEqual(row.x - GEOMETRY_TOLERANCE);
+    expect(button.x + button.width).toBeLessThanOrEqual(row.x + row.width + GEOMETRY_TOLERANCE);
+  }
+}
+
+export async function openFooterOverflow(page: Page): Promise<void> {
+  await footerLine(page).getByTestId("sidebar-footer-overflow").click();
+  await expect(footerOverflowMenu(page)).toBeVisible();
+}
+
+/** The overflow menu lists exactly these actions, in row order. */
+export async function expectFooterOverflowActions(page: Page, names: string[]): Promise<void> {
+  await expect(footerOverflowMenu(page).getByRole("menuitem")).toHaveText(names);
+}
+
+export async function chooseFooterOverflowAction(page: Page, name: string): Promise<void> {
+  await footerOverflowMenu(page).getByRole("menuitem", { name }).click();
+}
+
+/** Every row of the open overflow menu, and of the page it opened, is inside the viewport's width. */
+export async function expectFooterMenusInsideViewport(page: Page): Promise<void> {
+  const viewport = page.viewportSize()!;
+  const rows = page.getByRole("menuitem");
+  await expect(rows.first()).toBeVisible();
+  const boxes = await rows.evaluateAll((elements) =>
+    elements.map((element) => {
+      const { x, width } = element.getBoundingClientRect();
+      return { x, width };
+    }),
+  );
+  for (const box of boxes) {
+    expect(box.x).toBeGreaterThanOrEqual(0);
+    expect(box.x + box.width).toBeLessThanOrEqual(viewport.width);
+  }
+}
diff --git a/packages/app/src/components/left-sidebar.tsx b/packages/app/src/components/left-sidebar.tsx
index b4b54db3db..1b2df08302 100644
--- a/packages/app/src/components/left-sidebar.tsx
+++ b/packages/app/src/components/left-sidebar.tsx
@@ -17,6 +17,7 @@ import {
   Text,
   useWindowDimensions,
   View,
+  type LayoutChangeEvent,
 } from "react-native";
 import { Gesture, ScrollView as GHScrollView } from "react-native-gesture-handler";
 import Animated, { runOnJS, useAnimatedStyle, useSharedValue } from "react-native-reanimated";
@@ -40,6 +41,17 @@ import { SidebarSeparator } from "@/components/sidebar/sidebar-separator";
 import { SidebarNavRows } from "@/components/sidebar/sidebar-nav-rows";
 import { SidebarFooterIconHighlight } from "@/components/sidebar/sidebar-footer-icon-highlight";
 import { SidebarHelpMenu } from "@/components/sidebar/sidebar-help-menu";
+import { SidebarFooterOverflowMenu } from "@/components/sidebar/sidebar-footer-overflow-menu";
+import {
+  resolveSidebarFooterLayout,
+  SIDEBAR_FOOTER_ACTIONS,
+  type SidebarFooterAction,
+} from "@/components/sidebar-footer-layout";
+import {
+  controlSizingForLayout,
+  mapLayout,
+  TOOLBAR_CONTROL_SIZES,
+} from "@/components/ui/control-geometry";
 import { SidebarResizeHandle } from "@/components/sidebar-resize-handle";
 import { DensityIcon } from "@/components/ui/density-icon";
 import { SidebarSectionHeader } from "@/components/sidebar/sidebar-section-header";
@@ -55,6 +67,7 @@ import {
   type SidebarWorkspaceEntry,
 } from "@/hooks/use-sidebar-workspaces-list";
 import { density } from "@/styles/density";
+import { SPACING } from "@/styles/theme";
 import { useSidebarModel } from "@/components/sidebar/sidebar-model";
 import type { PinnedSidebarGroups } from "@/hooks/use-sidebar-pins";
 import { RetainedPanelActivity } from "@/components/retained-panel";
@@ -79,6 +92,9 @@ import { SidebarWorkspaceList } from "./sidebar-workspace-list";
 
 type SidebarTheme = ReturnType<typeof useUnistyles>["theme"];
 
+/** The footer icon line's inset; the overflow layout counts it as space the buttons can't use. */
+const FOOTER_ROW_PADDING = SPACING[2];
+
 const DEV_BUILD_LABEL = process.env.EXPO_PUBLIC_PASEO_DEV_BUILD_LABEL?.trim() || null;
 
 interface SidebarSharedProps {
@@ -410,35 +426,72 @@ function SidebarFooter({
 }) {
   const newAgentKeys = useShortcutKeys("new-agent");
   const settingsKeys = useShortcutKeys("toggle-settings");
+  const isCompactLayout = useIsCompactFormFactor();
+  const [rowWidth, setRowWidth] = useState(0);
+  const handleRowLayout = useCallback((event: LayoutChangeEvent) => {
+    setRowWidth(event.nativeEvent.layout.width);
+  }, []);
+  const { inline, overflow } = useMemo(
+    () =>
+      resolveSidebarFooterLayout({
+        rowWidth,
+        controlSize: TOOLBAR_CONTROL_SIZES[controlSizingForLayout(isCompactLayout)],
+        rowPadding: FOOTER_ROW_PADDING,
+        actions: SIDEBAR_FOOTER_ACTIONS,
+      }),
+    [rowWidth, isCompactLayout],
+  );
+  const isInline = (action: SidebarFooterAction) => inline.includes(action);
 
-  // One line of icons: Add project, Usage, Hosts, then Help and Settings at the end.
+  // One line of icons: Add project, Usage, Hosts, then Help and Settings at the end. Actions that
+  // don't fit move behind a caret before Settings.
   return (
     <UsageSidebarRoot>
       <View style={styles.footerContainer} testID="sidebar-footer">
         <SidebarFooterRows onBeforeNavigate={onBeforeNavigate} />
-        <View style={styles.sidebarFooter} testID="sidebar-footer-bottom-line">
-          <FooterIconButton
-            onPress={handleOpenProject}
-            testID="sidebar-add-project"
-            label={labels.addProject}
-            icon={FolderPlus}
-            shortcutKeys={newAgentKeys}
-          />
-          <SidebarUsageIcon label={labels.usage} />
-          <SidebarHostPicker
-            label={labels.hosts}
-            onAddHost={handleAddHost}
-            onOpenHostSettings={handleOpenHostSettings}
-          />
+        <View
+          style={styles.sidebarFooter}
+          onLayout={handleRowLayout}
+          testID="sidebar-footer-bottom-line"
+        >
+          {isInline("add-project") ? (
+            <FooterIconButton
+              onPress={handleOpenProject}
+              testID="sidebar-add-project"
+              label={labels.addProject}
+              icon={FolderPlus}
+              shortcutKeys={newAgentKeys}
+            />
+          ) : null}
+          {isInline("usage") ? <SidebarUsageIcon label={labels.usage} /> : null}
+          {isInline("hosts") ? (
+            <SidebarHostPicker
+              label={labels.hosts}
+              onAddHost={handleAddHost}
+              onOpenHostSettings={handleOpenHostSettings}
+            />
+          ) : null}
           <View style={styles.footerSpacer} />
-          <SidebarHelpMenu />
-          <FooterIconButton
-            onPress={handleSettings}
-            testID="sidebar-settings"
-            label={labels.settings}
-            icon={Settings}
-            shortcutKeys={settingsKeys}
-          />
+          {isInline("help") ? <SidebarHelpMenu /> : null}
+          {overflow.length > 0 ? (
+            <SidebarFooterOverflowMenu
+              actions={overflow}
+              labels={labels}
+              onAddProject={handleOpenProject}
+              onSettings={handleSettings}
+              onAddHost={handleAddHost}
+              onOpenHostSettings={handleOpenHostSettings}
+            />
+          ) : null}
+          {isInline("settings") ? (
+            <FooterIconButton
+              onPress={handleSettings}
+              testID="sidebar-settings"
+              label={labels.settings}
+              icon={Settings}
+              shortcutKeys={settingsKeys}
+            />
+          ) : null}
         </View>
       </View>
     </UsageSidebarRoot>
@@ -937,10 +990,12 @@ const styles = StyleSheet.create((theme) => ({
     borderTopColor: theme.colors.border,
   },
   // Buttons sit edge to edge; their own inset spaces the glyphs.
+  // As tall as its buttons from the first frame, which places none until the row has measured.
   sidebarFooter: {
     flexDirection: "row",
     alignItems: "center",
-    paddingHorizontal: theme.spacing[2],
+    minHeight: mapLayout(density.iconButton, (height) => height + theme.spacing[1.5] * 2),
+    paddingHorizontal: FOOTER_ROW_PADDING,
     paddingVertical: theme.spacing[1.5],
   },
   // Pushes Help and Settings to the end of the icon line.
diff --git a/packages/app/src/components/sidebar-footer-layout.test.ts b/packages/app/src/components/sidebar-footer-layout.test.ts
new file mode 100644
index 0000000000..b4ec0584f7
--- /dev/null
+++ b/packages/app/src/components/sidebar-footer-layout.test.ts
@@ -0,0 +1,89 @@
+import { describe, expect, it } from "vitest";
+import {
+  resolveSidebarFooterLayout,
+  SIDEBAR_FOOTER_ACTIONS,
+} from "@/components/sidebar-footer-layout";
+import { DEFAULT_SIDEBAR_WIDTH, MIN_SIDEBAR_WIDTH } from "@/stores/panel-store";
+
+const TOUCH = 44;
+const POINTER = 28;
+const ROW_PADDING = 8;
+
+function layout(rowWidth: number, controlSize: number) {
+  return resolveSidebarFooterLayout({
+    rowWidth,
+    controlSize,
+    rowPadding: ROW_PADDING,
+    actions: SIDEBAR_FOOTER_ACTIONS,
+  });
+}
+
+describe("sidebar footer layout", () => {
+  it("keeps every action inline at the default width with either sizing", () => {
+    for (const controlSize of [TOUCH, POINTER]) {
+      expect(layout(DEFAULT_SIDEBAR_WIDTH, controlSize)).toEqual({
+        inline: ["add-project", "usage", "hosts", "help", "settings"],
+        overflow: [],
+      });
+    }
+  });
+
+  it("keeps every action inline at the minimum width with pointer sizing", () => {
+    expect(layout(MIN_SIDEBAR_WIDTH, POINTER).overflow).toEqual([]);
+  });
+
+  // The iPhone Duo report: the folded sidebar column is about the minimum width, and touch
+  // sizing makes five 44pt buttons plus padding 236pt wide.
+  it("moves Help and Usage behind the caret at the minimum width with touch sizing", () => {
+    expect(layout(MIN_SIDEBAR_WIDTH, TOUCH)).toEqual({
+      inline: ["add-project", "hosts", "settings"],
+      overflow: ["usage", "help"],
+    });
+  });
+
+  it("keeps Settings and Add project inline longest", () => {
+    // Three slots: two actions and the caret.
+    expect(layout(3 * TOUCH + 2 * ROW_PADDING, TOUCH)).toEqual({
+      inline: ["add-project", "settings"],
+      overflow: ["usage", "hosts", "help"],
+    });
+    // Two slots: Settings and the caret.
+    expect(layout(2 * TOUCH + 2 * ROW_PADDING, TOUCH)).toEqual({
+      inline: ["settings"],
+      overflow: ["add-project", "usage", "hosts", "help"],
+    });
+  });
+
+  it("puts everything behind the caret when only the caret fits", () => {
+    expect(layout(TOUCH + 2 * ROW_PADDING - 10, TOUCH)).toEqual({
+      inline: [],
+      overflow: ["add-project", "usage", "hosts", "help", "settings"],
+    });
+  });
+
+  it("fits all five actions exactly at their combined width", () => {
+    const exact = 5 * TOUCH + 2 * ROW_PADDING;
+    expect(layout(exact, TOUCH).overflow).toEqual([]);
+    // Browser layout rounds a little below the exact width.
+    expect(layout(exact - 0.4, TOUCH).overflow).toEqual([]);
+    expect(layout(exact - 1, TOUCH).overflow).toEqual(["usage", "help"]);
+  });
+
+  it("only places the actions it is given", () => {
+    expect(
+      resolveSidebarFooterLayout({
+        rowWidth: 3 * TOUCH + 2 * ROW_PADDING,
+        controlSize: TOUCH,
+        rowPadding: ROW_PADDING,
+        actions: ["add-project", "hosts", "settings"],
+      }),
+    ).toEqual({ inline: ["add-project", "hosts", "settings"], overflow: [] });
+  });
+
+  // Laying out against a guessed width would paint a clipped row for a frame on narrow sidebars.
+  it("places nothing before the row has been measured", () => {
+    for (const controlSize of [TOUCH, POINTER]) {
+      expect(layout(0, controlSize)).toEqual({ inline: [], overflow: [] });
+    }
+  });
+});
diff --git a/packages/app/src/components/sidebar-footer-layout.ts b/packages/app/src/components/sidebar-footer-layout.ts
new file mode 100644
index 0000000000..5513d59d09
--- /dev/null
+++ b/packages/app/src/components/sidebar-footer-layout.ts
@@ -0,0 +1,62 @@
+/** The sidebar footer's icon line, in row order. */
+export const SIDEBAR_FOOTER_ACTIONS = [
+  "add-project",
+  "usage",
+  "hosts",
+  "help",
+  "settings",
+] as const;
+
+export type SidebarFooterAction = (typeof SIDEBAR_FOOTER_ACTIONS)[number];
+
+/** The order actions keep their place in a row too narrow for all of them. */
+const KEEP_ORDER: readonly SidebarFooterAction[] = [
+  "settings",
+  "add-project",
+  "hosts",
+  "usage",
+  "help",
+];
+
+/** Measured widths land a hair under the exact sum of their parts. */
+const MEASUREMENT_TOLERANCE = 0.5;
+
+export interface SidebarFooterLayout {
+  /** Actions drawn in the row, in row order. */
+  inline: SidebarFooterAction[];
+  /** Actions behind the overflow caret, in row order. Empty when everything fits. */
+  overflow: SidebarFooterAction[];
+}
+
+/**
+ * Splits the footer's actions between the row and the overflow menu. Buttons keep their full size;
+ * when they don't all fit, the caret takes one slot and the actions that lose their place move
+ * behind it, Help first and Settings last. Nothing is placed until the row has a measured width.
+ */
+export function resolveSidebarFooterLayout(input: {
+  rowWidth: number;
+  controlSize: number;
+  rowPadding: number;
+  actions: readonly SidebarFooterAction[];
+}): SidebarFooterLayout {
+  const { rowWidth, controlSize, rowPadding, actions } = input;
+  // An unmeasured row stays empty: any guess would paint a clipped row for a frame on a narrow
+  // sidebar before the real width arrives.
+  if (rowWidth <= 0) {
+    return { inline: [], overflow: [] };
+  }
+  const slots = Math.floor(
+    (rowWidth - rowPadding * 2 + MEASUREMENT_TOLERANCE) / Math.max(controlSize, 1),
+  );
+  if (slots >= actions.length) {
+    return { inline: [...actions], overflow: [] };
+  }
+  const inlineCount = Math.max(slots - 1, 0);
+  const kept = new Set(
+    KEEP_ORDER.filter((action) => actions.includes(action)).slice(0, inlineCount),
+  );
+  return {
+    inline: actions.filter((action) => kept.has(action)),
+    overflow: actions.filter((action) => !kept.has(action)),
+  };
+}
diff --git a/packages/app/src/components/sidebar/sidebar-footer-menu-trigger.tsx b/packages/app/src/components/sidebar/sidebar-footer-menu-trigger.tsx
new file mode 100644
index 0000000000..fd165efa79
--- /dev/null
+++ b/packages/app/src/components/sidebar/sidebar-footer-menu-trigger.tsx
@@ -0,0 +1,69 @@
+import type { ReactElement } from "react";
+import { Text, View } from "react-native";
+import type { LucideIcon } from "lucide-react-native";
+import { StyleSheet } from "react-native-unistyles";
+import { DropdownMenuTrigger } from "@/components/ui/dropdown-menu";
+import { DensityIcon } from "@/components/ui/density-icon";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
+import { density } from "@/styles/density";
+import { SidebarFooterIconHighlight } from "./sidebar-footer-icon-highlight";
+
+/**
+ * A footer icon that opens a menu. Sized and drawn like the footer's other icon buttons; the
+ * tooltip stays out of the way while the menu is open.
+ */
+export function SidebarFooterMenuTrigger({
+  icon,
+  label,
+  menuOpen,
+  testID,
+}: {
+  icon: LucideIcon;
+  label: string;
+  menuOpen: boolean;
+  testID: string;
+}): ReactElement {
+  return (
+    <Tooltip delayDuration={300} enabledOnDesktop={!menuOpen}>
+      <TooltipTrigger asChild>
+        <View>
+          <DropdownMenuTrigger
+            style={styles.trigger}
+            testID={testID}
+            accessibilityRole="button"
+            accessibilityLabel={label}
+          >
+            {({ hovered, pressed, open }) => (
+              <>
+                <SidebarFooterIconHighlight visible={pressed || open} />
+                <DensityIcon
+                  icon={icon}
+                  size="md"
+                  color={hovered ? "foreground" : "foregroundMuted"}
+                />
+              </>
+            )}
+          </DropdownMenuTrigger>
+        </View>
+      </TooltipTrigger>
+      <TooltipContent side="top" align="center" offset={8}>
+        <Text style={styles.tooltipText}>{label}</Text>
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
+const styles = StyleSheet.create((theme) => ({
+  trigger: {
+    width: density.iconButton,
+    height: density.iconButton,
+    alignItems: "center",
+    justifyContent: "center",
+    paddingVertical: theme.spacing[1],
+    paddingHorizontal: theme.spacing[1],
+  },
+  tooltipText: {
+    fontSize: theme.fontSize.base,
+    color: theme.colors.popoverForeground,
+  },
+}));
diff --git a/packages/app/src/components/sidebar/sidebar-footer-overflow-menu.tsx b/packages/app/src/components/sidebar/sidebar-footer-overflow-menu.tsx
new file mode 100644
index 0000000000..aef13f7e28
--- /dev/null
+++ b/packages/app/src/components/sidebar/sidebar-footer-overflow-menu.tsx
@@ -0,0 +1,245 @@
+import { useCallback, useMemo, useState, type ReactElement } from "react";
+import { useTranslation } from "react-i18next";
+import {
+  ChevronUp,
+  CircleGauge,
+  CircleHelp,
+  FolderPlus,
+  Plus,
+  Server,
+  Settings,
+} from "lucide-react-native";
+import { withUnistyles } from "react-native-unistyles";
+import { HostStatusDotSlot } from "@/components/hosts/host-picker";
+import type { SidebarFooterAction } from "@/components/sidebar-footer-layout";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuSubTrigger,
+  type MenuPageDefinition,
+} from "@/components/ui/dropdown-menu";
+import { Shortcut } from "@/components/ui/shortcut";
+import { useLocalDaemonServerId } from "@/hooks/use-is-local-daemon";
+import { useShortcutKeys } from "@/hooks/use-shortcut-keys";
+import { useHosts } from "@/runtime/host-runtime";
+import { ICON_SIZE, type Theme } from "@/styles/theme";
+import { orderHostsLocalFirst } from "@/types/host-connection";
+import { useOpenSidebarUsage } from "@/usage";
+import { SidebarFooterMenuTrigger } from "./sidebar-footer-menu-trigger";
+import { SidebarHelpMenuItems } from "./sidebar-help-menu";
+
+const mutedIconMapping = (theme: Theme) => ({ color: theme.colors.foregroundMuted });
+const ThemedFolderPlus = withUnistyles(FolderPlus);
+const ThemedCircleGauge = withUnistyles(CircleGauge);
+const ThemedServer = withUnistyles(Server);
+const ThemedCircleHelp = withUnistyles(CircleHelp);
+const ThemedSettings = withUnistyles(Settings);
+const ThemedPlus = withUnistyles(Plus);
+const addProjectLeading = <ThemedFolderPlus size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
+const usageLeading = <ThemedCircleGauge size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
+const hostsLeading = <ThemedServer size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
+const helpLeading = <ThemedCircleHelp size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
+const settingsLeading = <ThemedSettings size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
+const addHostLeading = <ThemedPlus size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
+
+const HOSTS_PAGE_ID = "hosts";
+const HELP_PAGE_ID = "help";
+
+export interface SidebarFooterOverflowMenuProps {
+  /** The footer actions that did not fit in the row, in row order. */
+  actions: readonly SidebarFooterAction[];
+  labels: { addProject: string; hosts: string; settings: string; usage: string };
+  onAddProject: () => void;
+  onSettings: () => void;
+  onAddHost: () => void;
+  onOpenHostSettings: (serverId: string) => void;
+}
+
+/**
+ * The caret at the end of a footer row too narrow for every action. It lists the actions that
+ * lost their place, with the same test IDs they carry in the row; Hosts and Help, menus of their
+ * own in the row, open as pages of this menu.
+ */
+export function SidebarFooterOverflowMenu({
+  actions,
+  labels,
+  onAddProject,
+  onSettings,
+  onAddHost,
+  onOpenHostSettings,
+}: SidebarFooterOverflowMenuProps): ReactElement {
+  const { t } = useTranslation();
+  const [open, setOpen] = useState(false);
+  const openUsage = useOpenSidebarUsage();
+  const newAgentKeys = useShortcutKeys("new-agent");
+  const settingsKeys = useShortcutKeys("toggle-settings");
+  const helpLabel = t("sidebar.help.trigger");
+  const addProjectTrailing = useMemo(
+    () => (newAgentKeys ? <Shortcut chord={newAgentKeys} /> : null),
+    [newAgentKeys],
+  );
+  const settingsTrailing = useMemo(
+    () => (settingsKeys ? <Shortcut chord={settingsKeys} /> : null),
+    [settingsKeys],
+  );
+
+  const pages = useMemo((): MenuPageDefinition[] => {
+    const result: MenuPageDefinition[] = [];
+    if (actions.includes("hosts")) {
+      result.push({
+        id: HOSTS_PAGE_ID,
+        title: labels.hosts,
+        content: <HostsPage onAddHost={onAddHost} onOpenHostSettings={onOpenHostSettings} />,
+      });
+    }
+    if (actions.includes("help")) {
+      result.push({ id: HELP_PAGE_ID, title: helpLabel, content: <SidebarHelpMenuItems /> });
+    }
+    return result;
+  }, [actions, helpLabel, labels.hosts, onAddHost, onOpenHostSettings]);
+
+  function renderAction(action: SidebarFooterAction): ReactElement {
+    switch (action) {
+      case "add-project":
+        return (
+          <DropdownMenuItem
+            key={action}
+            testID="sidebar-add-project"
+            leading={addProjectLeading}
+            trailing={addProjectTrailing}
+            onSelect={onAddProject}
+          >
+            {labels.addProject}
+          </DropdownMenuItem>
+        );
+      case "usage":
+        return (
+          <DropdownMenuItem
+            key={action}
+            testID="sidebar-usage-icon"
+            leading={usageLeading}
+            onSelect={openUsage}
+          >
+            {labels.usage}
+          </DropdownMenuItem>
+        );
+      case "hosts":
+        return (
+          <DropdownMenuSubTrigger
+            key={action}
+            id={HOSTS_PAGE_ID}
+            testID="sidebar-hosts-trigger"
+            leading={hostsLeading}
+          >
+            {labels.hosts}
+          </DropdownMenuSubTrigger>
+        );
+      case "help":
+        return (
+          <DropdownMenuSubTrigger
+            key={action}
+            id={HELP_PAGE_ID}
+            testID="sidebar-help"
+            leading={helpLeading}
+          >
+            {helpLabel}
+          </DropdownMenuSubTrigger>
+        );
+      case "settings":
+        return (
+          <DropdownMenuItem
+            key={action}
+            testID="sidebar-settings"
+            leading={settingsLeading}
+            trailing={settingsTrailing}
+            onSelect={onSettings}
+          >
+            {labels.settings}
+          </DropdownMenuItem>
+        );
+    }
+  }
+
+  return (
+    <DropdownMenu open={open} onOpenChange={setOpen}>
+      <SidebarFooterMenuTrigger
+        icon={ChevronUp}
+        label={t("sidebar.actions.moreActions")}
+        menuOpen={open}
+        testID="sidebar-footer-overflow"
+      />
+      <DropdownMenuContent
+        side="top"
+        align="end"
+        offset={8}
+        width={240}
+        pages={pages}
+        scrollable
+        testID="sidebar-footer-overflow-menu"
+      >
+        {actions.map(renderAction)}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
+
+/** The host picker's choices as a menu page: each host opens its settings, then Add host. */
+function HostsPage({
+  onAddHost,
+  onOpenHostSettings,
+}: {
+  onAddHost: () => void;
+  onOpenHostSettings: (serverId: string) => void;
+}): ReactElement {
+  const { t } = useTranslation();
+  const hosts = useHosts();
+  const localServerId = useLocalDaemonServerId();
+  const orderedHosts = useMemo(
+    () => orderHostsLocalFirst(hosts, localServerId),
+    [hosts, localServerId],
+  );
+
+  return (
+    <>
+      {orderedHosts.map((host) => (
+        <HostRow
+          key={host.serverId}
+          serverId={host.serverId}
+          label={host.label}
+          onOpenHostSettings={onOpenHostSettings}
+        />
+      ))}
+      {orderedHosts.length > 0 ? <DropdownMenuSeparator /> : null}
+      <DropdownMenuItem testID="sidebar-host-add" leading={addHostLeading} onSelect={onAddHost}>
+        {t("settings.addHost")}
+      </DropdownMenuItem>
+    </>
+  );
+}
+
+function HostRow({
+  serverId,
+  label,
+  onOpenHostSettings,
+}: {
+  serverId: string;
+  label: string;
+  onOpenHostSettings: (serverId: string) => void;
+}): ReactElement {
+  const handleSelect = useCallback(
+    () => onOpenHostSettings(serverId),
+    [onOpenHostSettings, serverId],
+  );
+  const leading = useMemo(() => <HostStatusDotSlot serverId={serverId} />, [serverId]);
+  return (
+    <DropdownMenuItem
+      testID={`sidebar-host-row-${serverId}`}
+      leading={leading}
+      onSelect={handleSelect}
+    >
+      {label}
+    </DropdownMenuItem>
+  );
+}
diff --git a/packages/app/src/components/sidebar/sidebar-help-menu.tsx b/packages/app/src/components/sidebar/sidebar-help-menu.tsx
index 3ba3011517..d6ba4e98e1 100644
--- a/packages/app/src/components/sidebar/sidebar-help-menu.tsx
+++ b/packages/app/src/components/sidebar/sidebar-help-menu.tsx
@@ -1,5 +1,5 @@
 import { useCallback, useState } from "react";
-import { Text, View } from "react-native";
+import { View } from "react-native";
 import { Activity, CircleHelp, Gift, Keyboard } from "lucide-react-native";
 import { useTranslation } from "react-i18next";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
@@ -12,17 +12,13 @@ import {
   DropdownMenuItem,
   DropdownMenuLabel,
   DropdownMenuSeparator,
-  DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
-import { DensityIcon } from "@/components/ui/density-icon";
-import { SidebarFooterIconHighlight } from "./sidebar-footer-icon-highlight";
-import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
+import { SidebarFooterMenuTrigger } from "./sidebar-footer-menu-trigger";
 import { useAppDiagnosticStore } from "@/diagnostics/store";
 import { useHardwareKeyboardPresent } from "@/keyboard";
 import { useHostRuntimeIsConnected, useHosts } from "@/runtime/host-runtime";
 import { useKeyboardShortcutsStore } from "@/stores/keyboard-shortcuts-store";
 import { useSessionStore } from "@/stores/session-store";
-import { density } from "@/styles/density";
 import { ICON_SIZE, type Theme } from "@/styles/theme";
 import type { HostProfile } from "@/types/host-connection";
 import { formatVersionWithPrefix } from "@/desktop/updates/desktop-updates";
@@ -77,12 +73,32 @@ function HostVersionHint({ host }: { host: HostProfile }) {
   );
 }
 
+/** The Help menu's trigger, and the menu it opens. */
 export function SidebarHelpMenu() {
+  const { t } = useTranslation();
+  const [open, setOpen] = useState(false);
+
+  return (
+    <DropdownMenu open={open} onOpenChange={setOpen}>
+      <SidebarFooterMenuTrigger
+        icon={CircleHelp}
+        label={t("sidebar.help.trigger")}
+        menuOpen={open}
+        testID="sidebar-help"
+      />
+      <DropdownMenuContent side="top" align="end" offset={8} width={280} testID="sidebar-help-menu">
+        <SidebarHelpMenuItems />
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
+
+/** The Help menu's rows, shared by the Help menu and the footer's overflow page for it. */
+export function SidebarHelpMenuItems() {
   const { t } = useTranslation();
   const shortcutsAvailable = useHardwareKeyboardPresent();
   const openAppDiagnostic = useAppDiagnosticStore((state) => state.open);
   const setShortcutsDialogOpen = useKeyboardShortcutsStore((state) => state.setShortcutsDialogOpen);
-  const [open, setOpen] = useState(false);
   const version = formatVersionWithPrefix(resolveAppVersion());
   const hosts = useHosts();
 
@@ -99,105 +115,65 @@ export function SidebarHelpMenu() {
   }, []);
 
   return (
-    <DropdownMenu open={open} onOpenChange={setOpen}>
-      <Tooltip delayDuration={300} enabledOnDesktop={!open}>
-        <TooltipTrigger asChild>
-          <View>
-            <DropdownMenuTrigger
-              style={styles.trigger}
-              testID="sidebar-help"
-              accessibilityRole="button"
-              accessibilityLabel={t("sidebar.help.trigger")}
-            >
-              {({ hovered, pressed, open: menuOpen }) => (
-                <>
-                  <SidebarFooterIconHighlight visible={pressed || menuOpen} />
-                  <DensityIcon
-                    icon={CircleHelp}
-                    size="md"
-                    color={hovered ? "foreground" : "foregroundMuted"}
-                  />
-                </>
-              )}
-            </DropdownMenuTrigger>
-          </View>
-        </TooltipTrigger>
-        <TooltipContent side="top" align="center" offset={8}>
-          <Text style={styles.tooltipText}>{t("sidebar.help.trigger")}</Text>
-        </TooltipContent>
-      </Tooltip>
-      <DropdownMenuContent side="top" align="end" offset={8} width={280} testID="sidebar-help-menu">
-        <DropdownMenuLabel>{t("sidebar.help.sectionHelp")}</DropdownMenuLabel>
-        {shortcutsAvailable ? (
-          <DropdownMenuItem
-            testID="sidebar-help-shortcuts"
-            leading={shortcutsLeadingIcon}
-            onSelect={openKeyboardShortcuts}
-          >
-            {t("sidebar.help.shortcuts")}
-          </DropdownMenuItem>
-        ) : null}
+    <>
+      <DropdownMenuLabel>{t("sidebar.help.sectionHelp")}</DropdownMenuLabel>
+      {shortcutsAvailable ? (
         <DropdownMenuItem
-          testID="sidebar-help-changelog"
-          leading={changelogLeadingIcon}
-          onSelect={openChangelog}
+          testID="sidebar-help-shortcuts"
+          leading={shortcutsLeadingIcon}
+          onSelect={openKeyboardShortcuts}
         >
-          {t("sidebar.help.whatsNew")}
+          {t("sidebar.help.shortcuts")}
         </DropdownMenuItem>
-        <DropdownMenuItem
-          testID="sidebar-help-diagnostics"
-          leading={diagnosticLeadingIcon}
-          onSelect={openAppDiagnostic}
+      ) : null}
+      <DropdownMenuItem
+        testID="sidebar-help-changelog"
+        leading={changelogLeadingIcon}
+        onSelect={openChangelog}
+      >
+        {t("sidebar.help.whatsNew")}
+      </DropdownMenuItem>
+      <DropdownMenuItem
+        testID="sidebar-help-diagnostics"
+        leading={diagnosticLeadingIcon}
+        onSelect={openAppDiagnostic}
+      >
+        {t("sidebar.help.diagnostics")}
+      </DropdownMenuItem>
+      <DropdownMenuSeparator />
+      <DropdownMenuLabel>{t("sidebar.help.reportIssue")}</DropdownMenuLabel>
+      <DropdownMenuItem
+        testID="sidebar-help-discord"
+        leading={discordLeadingIcon}
+        onSelect={openDiscord}
+      >
+        {t("sidebar.help.discord")}
+      </DropdownMenuItem>
+      <DropdownMenuItem
+        testID="sidebar-help-github"
+        leading={githubLeadingIcon}
+        onSelect={openGitHubIssue}
+      >
+        {t("sidebar.help.github")}
+      </DropdownMenuItem>
+      <DropdownMenuSeparator />
+      <View style={styles.versionList}>
+        <DropdownMenuHint
+          style={styles.versionHint}
+          trailing={version}
+          testID="sidebar-help-version"
         >
-          {t("sidebar.help.diagnostics")}
-        </DropdownMenuItem>
-        <DropdownMenuSeparator />
-        <DropdownMenuLabel>{t("sidebar.help.reportIssue")}</DropdownMenuLabel>
-        <DropdownMenuItem
-          testID="sidebar-help-discord"
-          leading={discordLeadingIcon}
-          onSelect={openDiscord}
-        >
-          {t("sidebar.help.discord")}
-        </DropdownMenuItem>
-        <DropdownMenuItem
-          testID="sidebar-help-github"
-          leading={githubLeadingIcon}
-          onSelect={openGitHubIssue}
-        >
-          {t("sidebar.help.github")}
-        </DropdownMenuItem>
-        <DropdownMenuSeparator />
-        <View style={styles.versionList}>
-          <DropdownMenuHint
-            style={styles.versionHint}
-            trailing={version}
-            testID="sidebar-help-version"
-          >
-            {t("sidebar.help.appName")}
-          </DropdownMenuHint>
-          {hosts.map((host) => (
-            <HostVersionHint key={host.serverId} host={host} />
-          ))}
-        </View>
-      </DropdownMenuContent>
-    </DropdownMenu>
+          {t("sidebar.help.appName")}
+        </DropdownMenuHint>
+        {hosts.map((host) => (
+          <HostVersionHint key={host.serverId} host={host} />
+        ))}
+      </View>
+    </>
   );
 }
 
 const styles = StyleSheet.create((theme) => ({
-  trigger: {
-    width: density.iconButton,
-    height: density.iconButton,
-    alignItems: "center",
-    justifyContent: "center",
-    paddingVertical: theme.spacing[1],
-    paddingHorizontal: theme.spacing[1],
-  },
-  tooltipText: {
-    fontSize: theme.fontSize.base,
-    color: theme.colors.popoverForeground,
-  },
   versionList: {
     gap: theme.spacing[1],
     paddingVertical: theme.spacing[2],
diff --git a/packages/app/src/components/ui/anchor.test.ts b/packages/app/src/components/ui/anchor.test.ts
index cb18a86271..2e1cd6f68f 100644
--- a/packages/app/src/components/ui/anchor.test.ts
+++ b/packages/app/src/components/ui/anchor.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { computePosition, getTransformOrigin, type Rect } from "./anchor";
+import { computePosition, fitSurfaceWidth, getTransformOrigin, type Rect } from "./anchor";
 
 const DISPLAY: Rect = { x: 0, y: 0, width: 1000, height: 800 };
 const TRIGGER: Rect = { x: 100, y: 100, width: 40, height: 20 };
@@ -97,3 +97,26 @@ describe("getTransformOrigin", () => {
     expect(getTransformOrigin(placement, alignment)).toEqual(expected);
   });
 });
+
+describe("fitSurfaceWidth", () => {
+  it("leaves a surface that fits the display alone, capped at the display", () => {
+    expect(fitSurfaceWidth({ width: 240, minWidth: 180 }, 1000)).toEqual({
+      width: 240,
+      minWidth: 180,
+      maxWidth: 984,
+    });
+  });
+
+  it("shrinks a surface wider than a narrow display to the space inside its edge padding", () => {
+    expect(fitSurfaceWidth({ width: 240, minWidth: 180, maxWidth: 320 }, 220)).toEqual({
+      width: 204,
+      minWidth: 180,
+      maxWidth: 204,
+    });
+    expect(fitSurfaceWidth({ minWidth: 180 }, 150)).toEqual({
+      width: undefined,
+      minWidth: 134,
+      maxWidth: 134,
+    });
+  });
+});
diff --git a/packages/app/src/components/ui/anchor.ts b/packages/app/src/components/ui/anchor.ts
index 51454a9ee5..96a7518cba 100644
--- a/packages/app/src/components/ui/anchor.ts
+++ b/packages/app/src/components/ui/anchor.ts
@@ -120,6 +120,27 @@ function clampToDisplayArea(input: {
   };
 }
 
+export interface SurfaceWidth {
+  width?: number;
+  minWidth?: number;
+  maxWidth?: number;
+}
+
+/**
+ * Caps a surface's requested width to the display. Position clamping can move a surface but not
+ * shrink it, so a menu wider than a narrow screen would otherwise hang off the far edge.
+ */
+export function fitSurfaceWidth(requested: SurfaceWidth, displayWidth: number): SurfaceWidth {
+  const available = Math.max(displayWidth - EDGE_PADDING * 2, 0);
+  const cap = (value: number | undefined) =>
+    typeof value === "number" ? Math.min(value, available) : undefined;
+  return {
+    width: cap(requested.width),
+    minWidth: cap(requested.minWidth),
+    maxWidth: cap(requested.maxWidth) ?? available,
+  };
+}
+
 export function computePosition({
   triggerRect,
   contentSize,
diff --git a/packages/app/src/components/ui/menu/menu-overlay.tsx b/packages/app/src/components/ui/menu/menu-overlay.tsx
index 5bfcd9b5bf..c48fda7156 100644
--- a/packages/app/src/components/ui/menu/menu-overlay.tsx
+++ b/packages/app/src/components/ui/menu/menu-overlay.tsx
@@ -29,6 +29,7 @@ import type { KeyboardFocusScope } from "@/keyboard/actions";
 import { getOverlayRoot, OverlayLayerProvider, useOverlayLayer } from "@/lib/overlay-root";
 import {
   computePosition,
+  fitSurfaceWidth,
   getTransformOrigin,
   measureElement,
   type Alignment,
@@ -283,11 +284,7 @@ export function AnchoredSurface({
     const { width: screenWidth } = Dimensions.get("window");
     const resolvedWidthStyle: ViewStyle = fullWidth
       ? { width: screenWidth - horizontalPadding * 2 }
-      : {
-          ...(typeof width === "number" ? { width } : null),
-          ...(typeof minWidth === "number" ? { minWidth } : null),
-          ...(typeof maxWidth === "number" ? { maxWidth } : null),
-        };
+      : fitSurfaceWidth({ width, minWidth, maxWidth }, screenWidth);
     return [
       resolvedWidthStyle,
       {
diff --git a/packages/app/src/i18n/resources/ar.ts b/packages/app/src/i18n/resources/ar.ts
index 9d1ca6610d..f86d81b6e9 100644
--- a/packages/app/src/i18n/resources/ar.ts
+++ b/packages/app/src/i18n/resources/ar.ts
@@ -1236,6 +1236,7 @@ export const ar: TranslationResources = {
       hosts: "المضيفون",
       settings: "إعدادات",
       closeSidebar: "إغلاق الشريط الجانبي",
+      moreActions: "المزيد من الإجراءات",
     },
     footer: {
       usage: "الاستخدام",
diff --git a/packages/app/src/i18n/resources/en.ts b/packages/app/src/i18n/resources/en.ts
index 3f3091ae4a..103a981abc 100644
--- a/packages/app/src/i18n/resources/en.ts
+++ b/packages/app/src/i18n/resources/en.ts
@@ -1244,6 +1244,7 @@ export const en = {
       hosts: "Hosts",
       settings: "Settings",
       closeSidebar: "Close sidebar",
+      moreActions: "More actions",
     },
     footer: {
       usage: "Usage",
diff --git a/packages/app/src/i18n/resources/es.ts b/packages/app/src/i18n/resources/es.ts
index 73cc70a8ca..48737ee20e 100644
--- a/packages/app/src/i18n/resources/es.ts
+++ b/packages/app/src/i18n/resources/es.ts
@@ -1272,6 +1272,7 @@ export const es: TranslationResources = {
       hosts: "Hosts",
       settings: "Ajustes",
       closeSidebar: "Cerrar barra lateral",
+      moreActions: "Más acciones",
     },
     footer: {
       usage: "Uso",
diff --git a/packages/app/src/i18n/resources/fr.ts b/packages/app/src/i18n/resources/fr.ts
index 4257b799aa..0d2e4aabce 100644
--- a/packages/app/src/i18n/resources/fr.ts
+++ b/packages/app/src/i18n/resources/fr.ts
@@ -1266,6 +1266,7 @@ export const fr: TranslationResources = {
       hosts: "Hôtes",
       settings: "Paramètres",
       closeSidebar: "Fermer la barre latérale",
+      moreActions: "Plus d’actions",
     },
     footer: {
       usage: "Utilisation",
diff --git a/packages/app/src/i18n/resources/ja.ts b/packages/app/src/i18n/resources/ja.ts
index 073f164e6b..ca93aa3106 100644
--- a/packages/app/src/i18n/resources/ja.ts
+++ b/packages/app/src/i18n/resources/ja.ts
@@ -1250,6 +1250,7 @@ export const ja: TranslationResources = {
       hosts: "ホスト",
       settings: "設定",
       closeSidebar: "サイドバーを閉じる",
+      moreActions: "その他のアクション",
     },
     footer: {
       usage: "使用状況",
diff --git a/packages/app/src/i18n/resources/ko.ts b/packages/app/src/i18n/resources/ko.ts
index cee2bb19bd..51ea225983 100644
--- a/packages/app/src/i18n/resources/ko.ts
+++ b/packages/app/src/i18n/resources/ko.ts
@@ -1243,6 +1243,7 @@ export const ko: TranslationResources = {
       hosts: "호스트",
       settings: "설정",
       closeSidebar: "사이드바 닫기",
+      moreActions: "추가 작업",
     },
     footer: {
       usage: "사용량",
diff --git a/packages/app/src/i18n/resources/pt-BR.ts b/packages/app/src/i18n/resources/pt-BR.ts
index a88a749709..5c2695f3bf 100644
--- a/packages/app/src/i18n/resources/pt-BR.ts
+++ b/packages/app/src/i18n/resources/pt-BR.ts
@@ -1262,6 +1262,7 @@ export const ptBR: TranslationResources = {
       hosts: "Hosts",
       settings: "Configurações",
       closeSidebar: "Fechar barra lateral",
+      moreActions: "Mais ações",
     },
     footer: {
       usage: "Uso",
diff --git a/packages/app/src/i18n/resources/ru.ts b/packages/app/src/i18n/resources/ru.ts
index 3d8bd13196..ea8fb1eb25 100644
--- a/packages/app/src/i18n/resources/ru.ts
+++ b/packages/app/src/i18n/resources/ru.ts
@@ -1254,6 +1254,7 @@ export const ru: TranslationResources = {
       hosts: "Хосты",
       settings: "Настройки",
       closeSidebar: "Закрыть боковую панель",
+      moreActions: "Дополнительные действия",
     },
     footer: {
       usage: "Использование",
diff --git a/packages/app/src/i18n/resources/zh-CN.ts b/packages/app/src/i18n/resources/zh-CN.ts
index f0a0c9bc5c..54454d9bff 100644
--- a/packages/app/src/i18n/resources/zh-CN.ts
+++ b/packages/app/src/i18n/resources/zh-CN.ts
@@ -1228,6 +1228,7 @@ export const zhCN: TranslationResources = {
       hosts: "Hosts",
       settings: "设置",
       closeSidebar: "关闭侧边栏",
+      moreActions: "更多操作",
     },
     footer: {
       usage: "使用情况",

From 6355b339c8f7ea0f2b4d0f55d315d6a03d7ef434 Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Fri, 6 Nov 2026 10:28:42 +0700
Subject: [PATCH 28/29] fix(app): paint a smaller send and stop disc inside the
 touch hit frame (#8891)

Under touch sizing the composer's send and stop buttons filled their whole
44pt hit frame with color, so they outweighed every unpainted control in the
toolbar. The trigger keeps the 44pt frame and now paints a 36pt disc
(TOOLBAR_DISC_SIZE) centered inside it. Pointer sizing paints 28 inside 28, so
desktop is unchanged. The voice button's recording fill follows the same rule.
---
 docs/design.md                                |  2 +-
 .../components/ui/control-geometry.test.ts    |  7 ++
 .../app/src/components/ui/control-geometry.ts |  8 +++
 packages/app/src/composer/index.tsx           | 12 +++-
 packages/app/src/composer/input/input.tsx     | 65 ++++++++++++-------
 5 files changed, 67 insertions(+), 27 deletions(-)

diff --git a/docs/design.md b/docs/design.md
index b48ed81891..e840e81bfa 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -68,7 +68,7 @@ the sidebar. Apply it as `backgroundColor`; setting `opacity` on the control als
 
 `destructive` is filled with `destructive`. It only appears inside a confirm. The button on the page is `outline`; the destructive button is the confirm button inside the dialog.
 
-Controls come in two sizes, defined once in `control-geometry.ts`. The default is the right size almost everywhere — pages, dialogs, forms, settings rows, the setup flow — so don't pass a size. It is 32px tall where a pointer drives it and 44px where controls are touch-sized, so every touch control meets the iOS HIG's 44pt hit region. `sm` is 28px pointer and 32px touch, with `fontSize.sm` labels, and is for tight chrome only: toolbars, nested settings rows, dense inline row actions. A `size="sm"` on an ordinary page or dialog is wrong, and so is choosing a size from `useIsCompactFormFactor()`.
+Controls come in two sizes, defined once in `control-geometry.ts`. The default is the right size almost everywhere — pages, dialogs, forms, settings rows, the setup flow — so don't pass a size. It is 32px tall where a pointer drives it and 44px where controls are touch-sized, so every touch control meets the iOS HIG's 44pt hit region. The hit region is not the painted area: a filled toolbar control such as the composer's send or stop keeps the 44pt frame and paints a 36pt disc inside it (`TOOLBAR_DISC_SIZE`), so it does not outweigh its unpainted neighbours. `sm` is 28px pointer and 32px touch, with `fontSize.sm` labels, and is for tight chrome only: toolbars, nested settings rows, dense inline row actions. A `size="sm"` on an ordinary page or dialog is wrong, and so is choosing a size from `useIsCompactFormFactor()`.
 
 One gate, `resolveControlSizing`, picks touch or pointer sizing: touch when the layout is compact or the device has a touch screen. An iPad with the sidebar docked is wide and touch-sized; a desktop is pointer-sized; a phone is both compact and touch. The touch-screen fact is read once at startup (`hasTouchScreen` in `hooks/use-fine-pointer.ts`), so attaching a mouse or keyboard to a tablet never shrinks its controls. Stylesheets take sizes from `bySizing({ touch, pointer })`, which resolves to a breakpoint value, so a caller never sees which sizing it got. Rows, icon buttons and icon slots take theirs from `styles/density.ts`, which uses the same gate. An `{ xs, md }` literal for a hit target or glyph is wrong: on an iPad it yields the pointer size.
 
diff --git a/packages/app/src/components/ui/control-geometry.test.ts b/packages/app/src/components/ui/control-geometry.test.ts
index 90b18d6029..9b0ef21308 100644
--- a/packages/app/src/components/ui/control-geometry.test.ts
+++ b/packages/app/src/components/ui/control-geometry.test.ts
@@ -14,6 +14,8 @@ import {
   getControlInteractionPhase,
   TOOLBAR_CONTROL_HEIGHT,
   TOOLBAR_CONTROL_SIZES,
+  TOOLBAR_DISC_SIZE,
+  TOOLBAR_DISC_SIZES,
   TOUCH_TARGET,
 } from "@/components/ui/control-geometry";
 import type { Theme } from "@/styles/theme";
@@ -90,6 +92,11 @@ describe("control sizing gate", () => {
     // Composer toolbar controls: a full target on touch, unchanged 28 on pointer.
     expect(TOOLBAR_CONTROL_SIZES).toEqual({ touch: TOUCH_TARGET, pointer: 28 });
     expect(TOOLBAR_CONTROL_HEIGHT).toEqual({ xs: TOUCH_TARGET, md: 28 });
+    // A filled toolbar control paints a 36pt disc inside its 44pt touch frame, and fills its
+    // 28pt pointer frame exactly, so desktop is unchanged. Its glyph is the `md` glyph.
+    expect(TOOLBAR_DISC_SIZES).toEqual({ touch: 36, pointer: TOOLBAR_CONTROL_SIZES.pointer });
+    expect(TOOLBAR_DISC_SIZE).toEqual({ xs: 36, md: 28 });
+    expect(iconSizeFor("md")).toEqual({ touch: 20, pointer: 16 });
     for (const size of ["sm", "md"] as const) {
       expect(controlHeightForLayout(size, true)).toBeGreaterThan(
         controlHeightForLayout(size, false),
diff --git a/packages/app/src/components/ui/control-geometry.ts b/packages/app/src/components/ui/control-geometry.ts
index 407c042cbe..ae552a4c78 100644
--- a/packages/app/src/components/ui/control-geometry.ts
+++ b/packages/app/src/components/ui/control-geometry.ts
@@ -93,6 +93,14 @@ export const ICON_BUTTON_SIZES = {
 export const TOOLBAR_CONTROL_SIZES = { touch: TOUCH_TARGET, pointer: 28 } satisfies SizingValue;
 export const TOOLBAR_CONTROL_HEIGHT = bySizing(TOOLBAR_CONTROL_SIZES);
 
+/**
+ * The painted disc of a filled toolbar control, such as the composer's send and stop. The
+ * control keeps the full toolbar hit frame and paints this smaller disc centered inside it, so
+ * touch-sized it does not outweigh its unpainted neighbours. Pointer-sized it fills the frame.
+ */
+export const TOOLBAR_DISC_SIZES = { touch: 36, pointer: 28 } satisfies SizingValue;
+export const TOOLBAR_DISC_SIZE = bySizing(TOOLBAR_DISC_SIZES);
+
 /**
  * Glyph sizes. Pointer glyphs sit beside 13-14pt text; touch glyphs sit beside iOS's 17pt body
  * text, so each step is larger.
diff --git a/packages/app/src/composer/index.tsx b/packages/app/src/composer/index.tsx
index ad6961fe16..5401f77d73 100644
--- a/packages/app/src/composer/index.tsx
+++ b/packages/app/src/composer/index.tsx
@@ -35,6 +35,7 @@ import {
   controlSizingForLayout,
   iconSizeFor,
   TOOLBAR_CONTROL_HEIGHT,
+  TOOLBAR_DISC_SIZE,
 } from "@/components/ui/control-geometry";
 import { usePanelStore } from "@/stores/panel-store";
 import { usePointerCapabilities } from "@/hooks/pointer-capabilities";
@@ -1117,7 +1118,7 @@ function ComposerCancelButton({
         accessibilityRole="button"
         style={cancelButtonStyle}
       >
-        {icon}
+        <View style={styles.cancelButtonDisc}>{icon}</View>
       </TooltipTrigger>
       <TooltipContent side="top" align="center" offset={8}>
         <View style={styles.tooltipRow}>
@@ -2595,14 +2596,21 @@ const styles = StyleSheet.create((theme: Theme) => ({
     width: "100%",
     gap: theme.spacing[3],
   },
+  // The trigger is the hit frame and stays unpainted; the disc inside it carries the fill.
   cancelButton: {
     width: TOOLBAR_CONTROL_HEIGHT,
     height: TOOLBAR_CONTROL_HEIGHT,
+    alignItems: "center",
+    justifyContent: "center",
+    marginLeft: theme.spacing[1],
+  },
+  cancelButtonDisc: {
+    width: TOOLBAR_DISC_SIZE,
+    height: TOOLBAR_DISC_SIZE,
     borderRadius: theme.borderRadius.full,
     backgroundColor: theme.colors.palette.red[600],
     alignItems: "center",
     justifyContent: "center",
-    marginLeft: theme.spacing[1],
   },
   rightControls: {
     flexDirection: "row",
diff --git a/packages/app/src/composer/input/input.tsx b/packages/app/src/composer/input/input.tsx
index a71469c626..be1f2c3ed0 100644
--- a/packages/app/src/composer/input/input.tsx
+++ b/packages/app/src/composer/input/input.tsx
@@ -33,6 +33,7 @@ import {
   controlSizingForLayout,
   iconSizeFor,
   TOOLBAR_CONTROL_HEIGHT,
+  TOOLBAR_DISC_SIZE,
 } from "@/components/ui/control-geometry";
 import { ArrowUp, Mic, MicOff, CornerDownLeft, Plus, Square } from "lucide-react-native";
 import * as Haptics from "expo-haptics";
@@ -349,7 +350,11 @@ function VoiceButtonIcon({
   buttonIconSize: number;
 }) {
   if (isDictating) {
-    return <Square size={buttonIconSize} color="white" fill="white" />;
+    return (
+      <View style={styles.voiceButtonRecordingDisc}>
+        <Square size={buttonIconSize} color="white" fill="white" />
+      </View>
+    );
   }
   const colorMapping = hovered ? iconForegroundMapping : iconForegroundMutedMapping;
   if (isMutedRealtime) {
@@ -837,12 +842,14 @@ function SendButtonTooltip({
         testID={submitButtonTestID}
         style={sendButtonCombinedStyle}
       >
-        <SendButtonContent
-          isSubmitLoading={isSubmitLoading}
-          submitIcon={submitIcon}
-          submitLabel={submitLabel}
-          buttonIconSize={buttonIconSize}
-        />
+        <View style={submitLabel ? styles.sendButtonDiscLabeled : styles.sendButtonDisc}>
+          <SendButtonContent
+            isSubmitLoading={isSubmitLoading}
+            submitIcon={submitIcon}
+            submitLabel={submitLabel}
+            buttonIconSize={buttonIconSize}
+          />
+        </View>
       </TooltipTrigger>
       <TooltipContent side="top" align="center" offset={8}>
         <SendTooltipBody label={sendTooltipLabel} sendKeys={sendKeys} />
@@ -1925,7 +1932,6 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
         styles.voiceButton,
         Boolean(hovered) && !isDictating && styles.iconButtonHovered,
         !isDictationStartEnabled && styles.buttonDisabled,
-        isDictating && styles.voiceButtonRecording,
       ],
       [isDictating, isDictationStartEnabled],
     );
@@ -1974,12 +1980,8 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
       allowEmpty: allowEmptySubmit,
     });
     const sendButtonCombinedStyle = useMemo(
-      () => [
-        styles.sendButton,
-        submitLabel ? styles.sendButtonLabeled : undefined,
-        isPresentedSendDisabled && styles.buttonDisabled,
-      ],
-      [isPresentedSendDisabled, submitLabel],
+      () => [styles.sendButton, isPresentedSendDisabled && styles.buttonDisabled],
+      [isPresentedSendDisabled],
     );
     const overlayContainerStyle = useMemo(
       () => [styles.overlayContainer, { opacity: surfacePresentation.overlay.opacity }],
@@ -2416,23 +2418,38 @@ const styles = StyleSheet.create((theme: Theme) => ({
     alignItems: "center",
     justifyContent: "center",
   },
-  voiceButtonRecording: {
-    backgroundColor: theme.colors.destructive,
-  },
-  sendButton: {
-    width: TOOLBAR_CONTROL_HEIGHT,
-    height: TOOLBAR_CONTROL_HEIGHT,
+  voiceButtonRecordingDisc: {
+    width: TOOLBAR_DISC_SIZE,
+    height: TOOLBAR_DISC_SIZE,
     borderRadius: theme.borderRadius.full,
-    backgroundColor: theme.colors.accent,
+    backgroundColor: theme.colors.destructive,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  // The trigger is the hit frame and stays unpainted; the disc inside it carries the fill.
+  sendButton: {
+    minWidth: TOOLBAR_CONTROL_HEIGHT,
+    height: TOOLBAR_CONTROL_HEIGHT,
     alignItems: "center",
     justifyContent: "center",
     marginLeft: theme.spacing[1],
   },
-  sendButtonLabeled: {
-    width: "auto",
-    minWidth: TOOLBAR_CONTROL_HEIGHT,
+  sendButtonDisc: {
+    width: TOOLBAR_DISC_SIZE,
+    height: TOOLBAR_DISC_SIZE,
+    borderRadius: theme.borderRadius.full,
+    backgroundColor: theme.colors.accent,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  sendButtonDiscLabeled: {
+    minWidth: TOOLBAR_DISC_SIZE,
+    height: TOOLBAR_DISC_SIZE,
     paddingHorizontal: theme.spacing[3],
     borderRadius: theme.borderRadius.full,
+    backgroundColor: theme.colors.accent,
+    alignItems: "center",
+    justifyContent: "center",
   },
   sendButtonLabel: {
     fontSize: theme.fontSize.base,

From 5abfdf7107b5dabb885964de97dde8b55050613d Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Fri, 6 Nov 2026 10:55:56 +0700
Subject: [PATCH 29/29] Record workspace creation parentage (#8890)

* feat(workspaces): record workspace creation parentage

Retain the caller workspace as informational ancestry for future sidebar nesting, independently of workspace placement and lifecycle.

* fix(app): preserve workspace parentage in replica cache
---
 docs/agent-lifecycle.md                       |  6 ++
 .../src/runtime/replica-cache/index.test.ts   | 20 +++++
 .../app/src/runtime/replica-cache/index.ts    |  2 +
 packages/app/src/stores/session-store.test.ts | 27 +++++++
 packages/app/src/stores/session-store.ts      |  2 +
 packages/protocol/src/messages.ts             |  2 +
 .../protocol/src/messages.workspaces.test.ts  | 20 +++++
 .../src/server/agent/mcp-parity.e2e.test.ts   | 35 ++++++++-
 .../src/server/agent/tools/paseo-tools.ts     |  2 +
 packages/server/src/server/session.ts         |  2 +
 .../workspace-provisioning-service.test.ts    | 76 +++++++++++++++++++
 .../workspace-provisioning-service.ts         | 20 +++--
 .../server/src/server/workspace-registry.ts   |  2 +
 13 files changed, 207 insertions(+), 9 deletions(-)

diff --git a/docs/agent-lifecycle.md b/docs/agent-lifecycle.md
index 1d0b29b018..45c54ca18b 100644
--- a/docs/agent-lifecycle.md
+++ b/docs/agent-lifecycle.md
@@ -136,6 +136,12 @@ the marker. Closing a tab sets that client's label to `false`. Any `true` client
 open. Detach clears the parent and every open-tab label. The surviving child therefore becomes a
 normal root agent immediately, and closing its still-open tab archives it.
 
+Agent-scoped workspace creation records the caller's workspace as `parentWorkspaceId`.
+This is informational ancestry for future workspace grouping. It does not change placement,
+visibility, status, or archive behavior. Archiving a parent workspace preserves its children's
+records and parentage. Unscoped creation and existing workspaces have no parent; ancestry is
+never inferred from directories, projects, or Git branches.
+
 Runtime ownership is resolved from explicit workspace ID and caller context, never from `cwd`. Workspace creation is a separate operation with `local | worktree` isolation; agent creation reuses that workspace unless a new workspace is explicitly requested.
 
 Setup belongs to the workspace, including combined workspace-plus-agent creation and the supported agent `worktree` request. Run setup through the workspace workflow before launching configured terminals or scripts. Setup output is read in the Setup panel from per-command snapshots; never produce setup chat timeline rows or concatenate command logs. Legacy agent `git`/`worktreeName` inputs and hidden MCP worktree placement are rejected with workspace-creation guidance. Existing wire schemas retain an empty combined-log string for parsing compatibility.
diff --git a/packages/app/src/runtime/replica-cache/index.test.ts b/packages/app/src/runtime/replica-cache/index.test.ts
index 0ea262f7cb..5c90ffa5e1 100644
--- a/packages/app/src/runtime/replica-cache/index.test.ts
+++ b/packages/app/src/runtime/replica-cache/index.test.ts
@@ -321,6 +321,26 @@ describe("ReplicaCache", () => {
     expect(restored?.range).toBeNull();
   });
 
+  it("preserves workspace parentage and its checkpoint across cache reopen", async () => {
+    const storage = new MemoryStorage();
+    const writer = createCache(storage);
+    const baseline = directory({ workspaces: { generation: "g", afterSeq: 8 } });
+    const workspace = normalizeWorkspaceDescriptor({
+      ...workspacePayload(),
+      parentWorkspaceId: "parent",
+    });
+    baseline.workspaces.set(workspace.id, workspace);
+    commitDirectory(writer, SERVER_ID, baseline);
+    await writer.flush();
+    const reader = createCache(storage);
+    const restored = await reader.readDirectory(SERVER_ID);
+    expect(restored.checkpoint).toEqual(baseline.checkpoint);
+    expect(restored.workspaces.get(workspace.id)?.parentWorkspaceId).toBe("parent");
+    expect((await reader.readWorkspace(SERVER_ID, workspace.id))?.workspace.parentWorkspaceId).toBe(
+      "parent",
+    );
+  });
+
   it("preserves workspace sorting timestamps across cache reopen", async () => {
     const storage = new MemoryStorage();
     const writer = createCache(storage);
diff --git a/packages/app/src/runtime/replica-cache/index.ts b/packages/app/src/runtime/replica-cache/index.ts
index 1032a663bf..91a41e4186 100644
--- a/packages/app/src/runtime/replica-cache/index.ts
+++ b/packages/app/src/runtime/replica-cache/index.ts
@@ -299,6 +299,7 @@ const WorkspaceGitRuntimeSchema = z
   .optional();
 
 const StoredWorkspaceSchema = z.strictObject({
+  parentWorkspaceId: z.string().optional(),
   // Require both keys: a cursor without these values would preserve the wrong sort on reconnect.
   createdAt: IsoDateSchema.nullable(),
   lastUserMessageAt: IsoDateSchema.nullable(),
@@ -707,6 +708,7 @@ function restoreWorkspace(stored: StoredWorkspace): WorkspaceDescriptor {
 
 function serializeWorkspace(workspace: WorkspaceDescriptor): StoredWorkspace {
   return {
+    parentWorkspaceId: workspace.parentWorkspaceId,
     createdAt: workspace.createdAt?.toISOString() ?? null,
     lastUserMessageAt: workspace.lastUserMessageAt?.toISOString() ?? null,
     id: workspace.id,
diff --git a/packages/app/src/stores/session-store.test.ts b/packages/app/src/stores/session-store.test.ts
index fb38605220..1b9052c4c1 100644
--- a/packages/app/src/stores/session-store.test.ts
+++ b/packages/app/src/stores/session-store.test.ts
@@ -557,6 +557,33 @@ describe("normalizeWorkspaceDescriptor", () => {
     expect(blank.workspaceDirectory).toBe("");
   });
 
+  it("preserves informational workspace parentage", () => {
+    const payload = {
+      id: "child",
+      parentWorkspaceId: "parent",
+      projectId: "1",
+      projectDisplayName: "Project 1",
+      projectRootPath: "/repo",
+      workspaceDirectory: "/repo",
+      projectKind: "git",
+      workspaceKind: "checkout",
+      name: "main",
+      archivingAt: null,
+      status: "done",
+      statusEnteredAt: null,
+      activityAt: null,
+      diffStat: null,
+      scripts: [],
+    } as WorkspaceDescriptorPayload;
+
+    const workspace = normalizeWorkspaceDescriptor(payload);
+
+    expect(workspace.parentWorkspaceId).toBe("parent");
+    expect(
+      normalizeWorkspaceDescriptor({ ...payload, parentWorkspaceId: undefined }).parentWorkspaceId,
+    ).toBeUndefined();
+  });
+
   it("defaults missing scripts to an empty array", () => {
     const payload = {
       id: "1",
diff --git a/packages/app/src/stores/session-store.ts b/packages/app/src/stores/session-store.ts
index b1312860a9..0f8a9f2476 100644
--- a/packages/app/src/stores/session-store.ts
+++ b/packages/app/src/stores/session-store.ts
@@ -105,6 +105,7 @@ export interface Agent {
 }
 
 export interface WorkspaceDescriptor {
+  parentWorkspaceId?: string;
   createdAt: Date | null;
   lastUserMessageAt: Date | null;
   id: string;
@@ -162,6 +163,7 @@ export function normalizeWorkspaceDescriptor(
     projectKind: payload.projectKind,
     workspaceKind: payload.workspaceKind,
     background: payload.background ?? false,
+    parentWorkspaceId: payload.parentWorkspaceId,
     name: payload.name,
     title: payload.title ?? null,
     pinnedAt: payload.pinnedAt ?? null,
diff --git a/packages/protocol/src/messages.ts b/packages/protocol/src/messages.ts
index 64f37064e2..5436e1737d 100644
--- a/packages/protocol/src/messages.ts
+++ b/packages/protocol/src/messages.ts
@@ -4189,6 +4189,8 @@ export const WorkspaceGitHubRuntimePayloadSchema = z
 
 export const WorkspaceDescriptorPayloadSchema = z
   .object({
+    // Informational creation ancestry; independent of placement and lifecycle.
+    parentWorkspaceId: z.string().optional(),
     id: z.string(),
     projectId: z.string(),
     projectDisplayName: z.string(),
diff --git a/packages/protocol/src/messages.workspaces.test.ts b/packages/protocol/src/messages.workspaces.test.ts
index 3cb9b0d5bd..8a5bd13224 100644
--- a/packages/protocol/src/messages.workspaces.test.ts
+++ b/packages/protocol/src/messages.workspaces.test.ts
@@ -634,6 +634,26 @@ describe("workspace message schemas", () => {
     ]);
   });
 
+  test("preserves informational workspace parentage in directory updates", () => {
+    const workspace = {
+      id: "child",
+      parentWorkspaceId: "parent",
+      projectId: "project",
+      projectDisplayName: "repo",
+      projectRootPath: "/repo",
+      projectKind: "git",
+      workspaceKind: "worktree",
+      name: "child",
+      status: "done",
+      activityAt: null,
+    };
+    expect(WorkspaceDescriptorPayloadSchema.parse(workspace).parentWorkspaceId).toBe("parent");
+    expect(
+      WorkspaceDescriptorPayloadSchema.parse({ ...workspace, parentWorkspaceId: undefined })
+        .parentWorkspaceId,
+    ).toBeUndefined();
+  });
+
   test("parses legacy workspace descriptors without workspaceDirectory", () => {
     const parsed = SessionOutboundMessageSchema.parse({
       type: "workspace_update",
diff --git a/packages/server/src/server/agent/mcp-parity.e2e.test.ts b/packages/server/src/server/agent/mcp-parity.e2e.test.ts
index 80d6da20a7..d4b1b76af1 100644
--- a/packages/server/src/server/agent/mcp-parity.e2e.test.ts
+++ b/packages/server/src/server/agent/mcp-parity.e2e.test.ts
@@ -1171,7 +1171,7 @@ describe("Suite E: Workspace Tools", () => {
         .callTool({ name: "archive_workspace", args: { workspaceId } })
         .catch(() => undefined);
     }
-  });
+  }, 30_000);
 
   test("agent-scoped workspace creation inherits visibility and permits an explicit false override", async () => {
     const parentWorkspace = await callToolStructured(topLevelClient, "create_workspace", {
@@ -1197,12 +1197,43 @@ describe("Suite E: Workspace Tools", () => {
       });
       ownedWorkspaces.push(str(inherited.workspaceId));
       expect(inherited.background).toBe(true);
+      expect(inherited.parentWorkspaceId).toBe(parentWorkspaceId);
       const visible = await callToolStructured(scoped, "create_workspace", {
         isolation: "local",
         background: false,
       });
       ownedWorkspaces.push(str(visible.workspaceId));
       expect(visible.background).toBe(false);
+      expect(visible.parentWorkspaceId).toBe(parentWorkspaceId);
+      const worktree = await callToolStructured(scoped, "create_workspace", {
+        isolation: "worktree",
+        branchName: "parentage-child",
+        baseBranch: "main",
+        background: false,
+      });
+      ownedWorkspaces.push(str(worktree.workspaceId));
+      expect(worktree.parentWorkspaceId).toBe(parentWorkspaceId);
+      const client = new DaemonClient({ url: `ws://127.0.0.1:${daemonHandle.port}/ws` });
+      try {
+        await client.connect();
+        const created = await client.createWorkspace({
+          source: { kind: "directory", path: worktreeRepoCwd },
+          callerAgentId: str(parent.agentId),
+          background: false,
+        });
+        const workspaceId = str(created.workspace?.id);
+        ownedWorkspaces.push(workspaceId);
+        expect(created.workspace?.parentWorkspaceId).toBe(parentWorkspaceId);
+        const listed = await client.fetchWorkspaces();
+        expect(listed.entries).toContainEqual(
+          expect.objectContaining({
+            id: workspaceId,
+            parentWorkspaceId: parentWorkspaceId,
+          }),
+        );
+      } finally {
+        await client.close();
+      }
     } finally {
       await scoped?.close();
       for (const workspaceId of ownedWorkspaces.toReversed())
@@ -1210,7 +1241,7 @@ describe("Suite E: Workspace Tools", () => {
           .callTool({ name: "archive_workspace", args: { workspaceId } })
           .catch(() => undefined);
     }
-  });
+  }, 30_000);
 
   test("a background agent's children and workspaces are background unless it overrides", async () => {
     const visibleAgentId = await createTopLevelAgent();
diff --git a/packages/server/src/server/agent/tools/paseo-tools.ts b/packages/server/src/server/agent/tools/paseo-tools.ts
index 7b33d2e250..42b6ddec4c 100644
--- a/packages/server/src/server/agent/tools/paseo-tools.ts
+++ b/packages/server/src/server/agent/tools/paseo-tools.ts
@@ -188,6 +188,7 @@ interface ProviderSummary {
 }
 
 const WorkspaceAutomationSummarySchema = z.object({
+  parentWorkspaceId: z.string().optional(),
   workspaceId: z.string(),
   projectId: z.string(),
   cwd: z.string(),
@@ -206,6 +207,7 @@ function toWorkspaceAutomationSummary(workspace: PersistedWorkspaceRecord) {
     kind: workspace.kind,
     title: workspace.title,
     background: workspace.background,
+    parentWorkspaceId: workspace.parentWorkspaceId,
   };
 }
 
diff --git a/packages/server/src/server/session.ts b/packages/server/src/server/session.ts
index 3dec72f45f..339a7c17fb 100644
--- a/packages/server/src/server/session.ts
+++ b/packages/server/src/server/session.ts
@@ -5900,6 +5900,7 @@ export class Session {
       pinnedAt: workspace.pinnedAt,
       ...(workspace.labels && workspace.labels.length > 0 ? { labels: workspace.labels } : {}),
       background: workspace.background,
+      parentWorkspaceId: workspace.parentWorkspaceId,
       archivingAt: null,
       status: "done",
       statusEnteredAt: null,
@@ -5988,6 +5989,7 @@ export class Session {
       projectKind: projectRecord?.kind ?? "git",
       workspaceKind: result.workspace.kind,
       background: result.workspace.background,
+      parentWorkspaceId: result.workspace.parentWorkspaceId,
       name: resolveWorkspaceName({
         title: result.workspace.title,
         derivedDisplayName: result.worktree.branchName || result.workspace.displayName,
diff --git a/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.test.ts b/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.test.ts
index 012ad0d490..706f199114 100644
--- a/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.test.ts
+++ b/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.test.ts
@@ -205,6 +205,82 @@ test("fresh non-git directory creates a directory workspace at the exact path",
   expect(workspace.cwd).toBe(dir);
 });
 
+test("workspace parentage survives reload and parent archive without changing placement", async () => {
+  const cwd = path.join(tmpDir, "plain");
+  const parent = await provisioning.createWorkspaceForDirectory(cwd);
+  const child = await provisioning.createWorkspaceForDirectory(cwd, null, undefined, {
+    callerWorkspaceId: parent.workspaceId,
+    background: false,
+  });
+  const grandchild = await provisioning.createWorkspaceForDirectory(
+    path.join(tmpDir, "other"),
+    null,
+    undefined,
+    {
+      callerWorkspaceId: child.workspaceId,
+    },
+  );
+  expect(parent.parentWorkspaceId).toBeUndefined();
+  expect(child).toMatchObject({ parentWorkspaceId: parent.workspaceId, cwd });
+  expect(grandchild).toMatchObject({ parentWorkspaceId: child.workspaceId });
+  await workspaceRegistry.archive(parent.workspaceId, ARCHIVED_AT);
+  const reloaded = new FileBackedWorkspaceRegistry(
+    path.join(tmpDir, "projects", "workspaces.json"),
+    logger,
+  );
+  await reloaded.initialize();
+  expect(await reloaded.get(child.workspaceId)).toMatchObject({
+    parentWorkspaceId: parent.workspaceId,
+    archivedAt: null,
+  });
+  expect(await reloaded.get(grandchild.workspaceId)).toMatchObject({
+    parentWorkspaceId: child.workspaceId,
+    archivedAt: null,
+  });
+});
+
+test("worktree workspace creation records its caller independently of its source project", async () => {
+  const sourceCwd = path.join(tmpDir, "repo");
+  gitRoots.add(sourceCwd);
+  const parent = await provisioning.createWorkspaceForDirectory(path.join(tmpDir, "other"));
+  const child = await provisioning.createWorkspaceForWorktree({
+    sourceCwd,
+    repoRoot: sourceCwd,
+    cwd: path.join(tmpDir, "worktree"),
+    worktreeRoot: path.join(tmpDir, "worktree"),
+    branch: "child",
+    baseBranch: "main",
+    title: null,
+    callerWorkspaceId: parent.workspaceId,
+  });
+  expect(child.parentWorkspaceId).toBe(parent.workspaceId);
+  expect(child.projectId).not.toBe(parent.projectId);
+  expect(await workspaceRegistry.get(child.workspaceId)).toMatchObject({
+    parentWorkspaceId: parent.workspaceId,
+  });
+});
+
+test("workspace creation rejects an unknown caller even with explicit visibility", async () => {
+  await expect(
+    provisioning.createWorkspaceForDirectory(path.join(tmpDir, "plain"), null, undefined, {
+      callerWorkspaceId: "missing",
+      background: false,
+    }),
+  ).rejects.toThrow("Caller workspace missing not found");
+});
+
+test("workspace creation cannot overwrite its caller with a self relationship", async () => {
+  const cwd = path.join(tmpDir, "plain");
+  const parent = await provisioning.createWorkspaceForDirectory(cwd);
+  await expect(
+    provisioning.createWorkspaceForDirectory(cwd, null, undefined, {
+      callerWorkspaceId: parent.workspaceId,
+      workspaceId: parent.workspaceId,
+    }),
+  ).rejects.toThrow("A workspace cannot be its own parent");
+  expect(await workspaceRegistry.get(parent.workspaceId)).toEqual(parent);
+});
+
 test("background workspace creation preserves hooks, inheritance and durable visibility", async () => {
   const dir = path.join(tmpDir, "plain");
   const events: string[] = [];
diff --git a/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.ts b/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.ts
index 3f2a7b423c..5744c2ddeb 100644
--- a/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.ts
+++ b/packages/server/src/server/session/workspace-provisioning/workspace-provisioning-service.ts
@@ -227,15 +227,21 @@ export function createWorkspaceProvisioningService(deps: {
     return project;
   }
 
-  async function resolveBackground(input?: {
+  async function resolveCreationMetadata(input?: {
+    workspaceId?: string;
     background?: boolean;
     callerWorkspaceId?: string;
-  }): Promise<boolean> {
-    if (input?.background !== undefined) return input.background;
-    if (!input?.callerWorkspaceId) return false;
+  }): Promise<{ background: boolean; parentWorkspaceId?: string }> {
+    if (!input?.callerWorkspaceId) return { background: input?.background ?? false };
+    if (input.workspaceId === input.callerWorkspaceId) {
+      throw new Error("A workspace cannot be its own parent");
+    }
     const callerWorkspace = await workspaceRegistry.get(input.callerWorkspaceId);
     if (!callerWorkspace) throw new Error(`Caller workspace ${input.callerWorkspaceId} not found`);
-    return callerWorkspace.background;
+    return {
+      background: input.background ?? callerWorkspace.background,
+      parentWorkspaceId: callerWorkspace.workspaceId,
+    };
   }
 
   async function createWorkspaceForDirectory(
@@ -269,7 +275,7 @@ export function createWorkspaceProvisioningService(deps: {
         title: title?.trim() || null,
         createdAt: timestamp,
         updatedAt: timestamp,
-        background: await resolveBackground(context),
+        ...(await resolveCreationMetadata(context)),
       });
       await workspaceRegistry.upsert(workspace, {
         expectsInitialAgent: context?.expectsInitialAgent,
@@ -310,7 +316,7 @@ export function createWorkspaceProvisioningService(deps: {
       createdAt: timestamp,
       updatedAt: timestamp,
       ...(input.untrustedSource ? { untrustedSource: input.untrustedSource } : {}),
-      background: await resolveBackground(input),
+      ...(await resolveCreationMetadata(input)),
     });
     await workspaceRegistry.upsert(workspace, {
       expectsInitialAgent: input.expectsInitialAgent,
diff --git a/packages/server/src/server/workspace-registry.ts b/packages/server/src/server/workspace-registry.ts
index 351ba043e4..b337543c7e 100644
--- a/packages/server/src/server/workspace-registry.ts
+++ b/packages/server/src/server/workspace-registry.ts
@@ -49,6 +49,7 @@ const PersistedProjectRecordSchema = z.object({
 });
 
 const PersistedWorkspaceRecordSchema = z.object({
+  parentWorkspaceId: z.string().optional(),
   workspaceId: z.string(),
   projectId: z.string(),
   cwd: z.string(),
@@ -679,6 +680,7 @@ export function resolveProjectDisplayName(record: PersistedProjectRecord): strin
 }
 
 export function createPersistedWorkspaceRecord(input: {
+  parentWorkspaceId?: string;
   workspaceId: string;
   projectId: string;
   cwd: string;