fix(diff): keep non-Git workspace refresh successful

Diff invalidation has no target repository for an ordinary folder. Treat that expected absence as a no-op while preserving other root-resolution errors.

docs/agent-lifecycle.md

@@ -136,12 +136,6 @@ 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.

docs/android.md

@@ -179,17 +179,8 @@ This is the Android counterpart of the iOS local-simulator flow in [development.
 `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 content-position corrections and the React Native issues they work around.
-
-The timeline's `nativeID` (`agent-chat-scroll-native-virtualized`) also identifies it to the native
-scroll owner: a nested panel's edge overshoot and unconsumed fling must leave the timeline still.
-Ordinary scroll parents retain Android's handoff. Keep that identity in sync with
-`agent-stream/strategy-native.tsx`; the end pin is absent while reading history, so it cannot
-identify the timeline for this rule.
-
-`VisibleContentPositionClampTest` mounts through React Native's own mounting manager;
-`PanelEdgeTest` covers both panel edges, flings, interior/direct scrolling, and ordinary-parent
-handoff with the real compiled scroll views:
+lists the corrections and the React Native issues they work around. Its instrumentation test,
+`VisibleContentPositionClampTest`, mounts through React Native's own mounting manager:
 
 ```bash
 cd packages/app/android

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. 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()`.
+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()`.
 
 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.
 

docs/menus.md

@@ -226,8 +226,7 @@ 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, 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.
+- 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.
 - 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).

packages/app/e2e/browser/agent-message-submission.spec.ts

@@ -235,7 +235,6 @@ async function beginTimelineRowStabilityCheck(
       lastTop: initialRow.getBoundingClientRect().top,
       largestDownwardShift: 0,
       sawMissing: false,
-      sawHidden: false,
     };
     const windowState = window as unknown as Record<string, unknown>;
     windowState.__messageSubmissionTimelineRowStability = state;
@@ -246,9 +245,6 @@ async function beginTimelineRowStabilityCheck(
         requestAnimationFrame(checkFrame);
         return;
       }
-      if (!initialRow.checkVisibility({ opacityProperty: true, visibilityProperty: true })) {
-        state.sawHidden = true;
-      }
       const top = initialRow.getBoundingClientRect().top;
       state.largestDownwardShift = Math.max(state.largestDownwardShift, top - state.lastTop);
       state.lastTop = top;
@@ -261,24 +257,14 @@ async function beginTimelineRowStabilityCheck(
     const result = await page.evaluate(() => {
       const windowState = window as unknown as Record<string, unknown>;
       const state = windowState.__messageSubmissionTimelineRowStability as
-        | {
-            active: boolean;
-            largestDownwardShift: number;
-            sawMissing: boolean;
-            sawHidden: boolean;
-          }
+        | { active: boolean; largestDownwardShift: number; sawMissing: boolean }
         | undefined;
       if (!state) throw new Error("Timeline-row stability check was not started");
       state.active = false;
       delete windowState.__messageSubmissionTimelineRowStability;
-      return {
-        largestDownwardShift: state.largestDownwardShift,
-        sawMissing: state.sawMissing,
-        sawHidden: state.sawHidden,
-      };
+      return { largestDownwardShift: state.largestDownwardShift, sawMissing: state.sawMissing };
     });
     expect(result.sawMissing).toBe(false);
-    expect(result.sawHidden).toBe(false);
     expect(result.largestDownwardShift).toBeLessThanOrEqual(2);
   };
 }
@@ -1192,13 +1178,7 @@ test.describe("Agent message submission", () => {
     test.setTimeout(120_000);
     const toasts = await recordPanelToasts(page);
     const pending = await beginDraftCreateSubmission(page, draftCreateScenario);
-    // The created agent takes over the draft's timeline: the same row stays mounted and painted.
-    const finishTimelineRowStabilityCheck = await beginTimelineRowStabilityCheck(
-      page,
-      pending.userMessage,
-    );
     await completeDraftCreateSubmission(page, draftCreateScenario, pending);
-    await finishTimelineRowStabilityCheck();
     // A chat this client just created is current by construction; it is never out of date.
     await toasts.expectNeverShown("agent-updating-toast");
   });

packages/app/e2e/browser/changes-pane.spec.ts

@@ -8,7 +8,11 @@ import { daemonWsRoutePattern } from "../support/helpers/daemon-port";
 import { getServerId } from "../support/helpers/server-id";
 import { connectSeedClient } from "../support/helpers/seed-client";
 import { createTempGitRepo } from "../support/helpers/workspace";
-import { openChangesPanel, waitForWorkspaceTabsVisible } from "../support/helpers/workspace-tabs";
+import {
+  openChangesPanel,
+  openChangesTreePanel,
+  waitForWorkspaceTabsVisible,
+} from "../support/helpers/workspace-tabs";
 
 interface DirtyWorkspace {
   id: string;
@@ -262,6 +266,126 @@ test.afterEach(async () => {
   }
 });
 
+test("Changes without a comparison base explains how to view pending changes", async ({ page }) => {
+  const workspace = await createWorkspaceWithManyTinyDiffs(2, "dev");
+  await openWorkspaceChangesTree(page, workspace);
+  await expect(
+    page.getByText("Comparison base is unavailable. Select Uncommitted to view pending changes."),
+  ).toBeVisible();
+  await selectChangesComparison(page, "Uncommitted");
+  await expect(changesTree(page).getByText("file-0000.ts", { exact: true })).toBeVisible();
+});
+async function openWorkspaceChangesTree(page: Page, workspace: DirtyWorkspace): Promise<void> {
+  await page.setViewportSize({ width: 1400, height: 900 });
+  await page.goto(buildHostWorkspaceRoute(getServerId(), workspace.id));
+  await waitForWorkspaceTabsVisible(page);
+  await openChangesTreePanel(page);
+}
+
+test("streamed Changes shows the tree before completion and applies a one-file refresh", async ({
+  page,
+}, testInfo) => {
+  test.setTimeout(120_000);
+  const workspace = await createLargeStreamedWorkspace();
+  await addOversizedSibling(workspace);
+  const stream = await holdDiffCompletion(page);
+  await openWorkspaceChangesSurface(page, workspace, 90_000);
+  await expectAnnouncedTreeAndLoader(page);
+  await page.screenshot({ path: testInfo.outputPath("tree-loading.png") });
+  stream.finish();
+  await expect.poll(() => stream.completed, { timeout: 60_000 }).toBeGreaterThan(0);
+  await expect(page.getByRole("progressbar", { name: "Loading..." })).toHaveCount(0);
+  const connections = stream.connections;
+  const panel = page.getByTestId("working-diff-panel").filter({ visible: true });
+  await expect(panel.getByTestId("diff-file-0")).toHaveAccessibleName("src/file-0000.ts, +90, -1");
+  await addOneLineToFirstFile(workspace);
+  await expect.poll(() => stream.changedBodies.at(-1), { timeout: 30_000 }).toBe(1);
+  await expect(panel.getByTestId("diff-file-0")).toHaveAccessibleName("src/file-0000.ts, +91, -1");
+  await expect(page.getByRole("progressbar", { name: "Loading..." })).toHaveCount(0);
+  expect(stream.connections).toBe(connections);
+  await page.screenshot({ path: testInfo.outputPath("refreshed.png") });
+});
+
+async function createLargeStreamedWorkspace(): Promise<DirtyWorkspace> {
+  const workspace = await createWorkspaceWithManyTinyDiffs(252);
+  await Promise.all(
+    Array.from({ length: 252 }, (_, file) =>
+      writeFile(
+        path.join(workspace.repoPath, `src/file-${String(file).padStart(4, "0")}.ts`),
+        Array.from(
+          { length: 90 },
+          (_unused, line) =>
+            `export const fn${line} = (param: string) => ({ key: param, value: ${file} });`,
+        ).join("\n") + "\n",
+      ),
+    ),
+  );
+  return workspace;
+}
+async function addOversizedSibling(workspace: DirtyWorkspace): Promise<void> {
+  await writeFile(path.join(workspace.repoPath, "zz-too-large.txt"), "x".repeat(1024 * 1024 + 1));
+}
+async function addOneLineToFirstFile(workspace: DirtyWorkspace): Promise<void> {
+  const file = path.join(workspace.repoPath, "src/file-0000.ts");
+  await writeFile(file, (await readFile(file, "utf8")) + "export const refreshed = true;\n");
+}
+async function holdDiffCompletion(page: Page) {
+  const { decodeDiffFrame, DiffOpcode } = await import("@getpaseo/protocol/binary-frames/index");
+  let holding = true;
+  let connections = 0;
+  let completed = 0;
+  const completions: Array<() => void> = [];
+  const changedBodies: number[] = [];
+  const bodyCounts = new Map<number, number>();
+  await page.routeWebSocket(daemonWsRoutePattern(), (browserSocket) => {
+    connections++;
+    const serverSocket = browserSocket.connectToServer();
+    browserSocket.onMessage((message) => serverSocket.send(message));
+    serverSocket.onMessage((message) => {
+      if (
+        typeof message !== "string" &&
+        message[0] >= DiffOpcode.Begin &&
+        message[0] <= DiffOpcode.End
+      ) {
+        const frame = decodeDiffFrame(message);
+        if (frame.opcode === DiffOpcode.Begin) bodyCounts.set(frame.slot, 0);
+        else if (frame.opcode === DiffOpcode.Bodies)
+          bodyCounts.set(frame.slot, (bodyCounts.get(frame.slot) ?? 0) + frame.files.length);
+        else {
+          completed++;
+          changedBodies.push(bodyCounts.get(frame.slot) ?? 0);
+        }
+      }
+      if (holding && typeof message !== "string" && message[0] === DiffOpcode.End) {
+        completions.push(() => browserSocket.send(message));
+        return;
+      }
+      browserSocket.send(message);
+    });
+  });
+  return {
+    changedBodies,
+    get connections() {
+      return connections;
+    },
+    get completed() {
+      return completed;
+    },
+    finish: () => {
+      holding = false;
+      completions.splice(0).forEach((send) => send());
+    },
+  };
+}
+async function expectWorkingDiffLoaded(page: Page, timeout: number): Promise<void> {
+  const panel = page.getByTestId("working-diff-panel").filter({ visible: true });
+  await expect(panel.getByTestId("diff-file-0")).toBeAttached({ timeout });
+}
+async function expectAnnouncedTreeAndLoader(page: Page): Promise<void> {
+  await expect(changesTree(page).first()).toBeVisible();
+  await expect(page.getByRole("progressbar", { name: "Loading..." }).first()).toBeVisible();
+}
+
 test("Changes opens All changes for a clean checkout", async ({ page }) => {
   const workspace = await createWorkspaceWithCommittedDiff();
 
@@ -490,6 +614,35 @@ test("an empty Changes comparison links to the populated comparison", async ({ p
   await expect(panel.getByTestId("diff-file-0")).toHaveAccessibleName("committed-only.ts, +1, -0");
 });
 
+test("legacy diff hosts keep All, Committed and Uncommitted comparisons", async ({ page }) => {
+  await useLegacyDiffHost(page);
+  const workspace = await createWorkspaceWithScrollableComparisons();
+  await openWorkspaceChangesSurface(page, workspace);
+  await expect(changesTree(page).getByText("committed", { exact: true })).toBeVisible();
+  await expect(changesTree(page).getByText("uncommitted", { exact: true })).toBeVisible();
+  await selectChangesComparison(page, "Committed");
+  await expectWorkingComparisonFiles(page, "committed");
+  await selectChangesComparison(page, "Uncommitted");
+  await expectWorkingComparisonFiles(page, "uncommitted");
+});
+async function useLegacyDiffHost(page: Page): Promise<void> {
+  await page.routeWebSocket(daemonWsRoutePattern(), (browserSocket) => {
+    const serverSocket = browserSocket.connectToServer();
+    browserSocket.onMessage((message) => serverSocket.send(message));
+    serverSocket.onMessage((message) => {
+      if (typeof message === "string") {
+        const envelope = JSON.parse(message);
+        if (envelope.message?.payload?.status === "server_info") {
+          delete envelope.message.payload.features.diffSubscription;
+          browserSocket.send(JSON.stringify(envelope));
+          return;
+        }
+      }
+      browserSocket.send(message);
+    });
+  });
+}
+
 test("Changes comparison controls the working diff and tree selection focuses its file", async ({
   page,
 }) => {
@@ -1302,11 +1455,13 @@ test("canvas diff uses the overlay scrollbar and its thumb controls vertical scr
 test("canvas headers keep a many-file diff bounded while scrolling end to end", async ({
   page,
 }) => {
-  test.setTimeout(180_000);
+  test.setTimeout(300_000);
   const workspace = await createWorkspaceWithManyTinyDiffs(2_000);
   await useUnwrappedDiffLines(page);
   await openWorkspaceChangesSurface(page, workspace, 90_000);
 
+  // Measure document bounds after delivery, independently of the cold Git read.
+  await expectWorkingDiffLoaded(page, 240_000);
   const root = page.getByTestId("git-diff-canvas-root");
   const scroller = page.getByTestId("git-diff-scroll");
   await expect(root.locator('[data-testid^="git-diff-sticky-header-"]')).toHaveCount(2);
@@ -1885,12 +2040,16 @@ async function createWorkspaceWithTwoSelectionDiffs(): Promise<DirtyWorkspace> {
   return { id: created.workspace.id, repoPath: repo.path };
 }
 
-async function createWorkspaceWithManyTinyDiffs(fileCount: number): Promise<DirtyWorkspace> {
+async function createWorkspaceWithManyTinyDiffs(
+  fileCount: number,
+  branch = "main",
+): Promise<DirtyWorkspace> {
   const files = Array.from({ length: fileCount }, (_, index) => ({
     path: `src/file-${String(index).padStart(4, "0")}.ts`,
     content: "export const value = 0;\n",
   }));
   const repo = await createTempGitRepo("changes-canvas-many-files-", { files });
+  if (branch !== "main") execFileSync("git", ["branch", "-m", branch], { cwd: repo.path });
   await Promise.all(
     files.map((file, index) =>
       writeFile(path.join(repo.path, file.path), `export const value = ${index + 1};\n`),

packages/app/e2e/browser/explorer-resize-performance.spec.ts

@@ -79,6 +79,12 @@ async function previewExplorerResize(page: Page, distance: number) {
   return { ...measurement, width: after };
 }
 
+async function expectCleanChangesLoaded(page: Page): Promise<void> {
+  await expect(
+    page.getByTestId("changes-tree-panel").getByText("No changes to display", { exact: true }),
+  ).toBeVisible();
+}
+
 async function expectExplorerWidthSurvivesReload(page: Page, width: number): Promise<void> {
   await page.reload();
   const explorer = page.getByTestId("workspace-explorer-sidebar");
@@ -100,6 +106,7 @@ test("Explorer drag previews without rerendering panes or rewriting the shared s
   await runWorkspaceActionFromCommandCenter(page, "Split pane right");
   await page.getByTestId("workspace-explorer-toggle").first().click();
   await expect(page.getByTestId("workspace-explorer-sidebar")).toBeVisible();
+  await expectCleanChangesLoaded(page);
   // Verify that direct pane renders are being counted before resetting them.
   expect(
     await page.evaluate(() =>

packages/app/e2e/browser/sidebar-footer-overflow.spec.ts

@@ -1,127 +0,0 @@
-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();
-  });
-});

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 { openCompactSettings, openSettingsHostSection } from "../support/helpers/settings";
+import { openSettingsHostSection } from "../support/helpers/settings";
 import {
   expectFooterItemSetting,
   expectFooterSeparator,
@@ -42,7 +42,6 @@ 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 };
@@ -71,112 +70,7 @@ 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()] });

packages/app/e2e/support/helpers/hosts.ts

@@ -22,27 +22,15 @@ export async function addOfflineHostAndReload(
   page: Page,
   input: { serverId: string; label: string; primaryLabel?: string },
 ): Promise<void> {
-  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,
-    }),
-  );
+  const offlineHost = buildSeededHost({
+    serverId: input.serverId,
+    label: input.label,
+    endpoint: "127.0.0.1:59999",
+    nowIso: new Date().toISOString(),
+  });
 
   await page.evaluate(
-    ({ hosts: added, keys, primaryLabel }) => {
+    ({ host, keys, primaryLabel }) => {
       const nonce = localStorage.getItem(keys.nonce);
       if (!nonce) {
         throw new Error("Expected the e2e seed nonce before overriding the host registry.");
@@ -52,22 +40,20 @@ export async function addOfflineHostsAndReload(
       if (primaryLabel && registry[0]) {
         registry[0].label = primaryLabel;
       }
-      for (const host of added) {
-        if (!registry.some((entry) => entry.serverId === host.serverId)) {
-          registry.push(host);
-        }
+      if (!registry.some((entry) => entry.serverId === host.serverId)) {
+        registry.push(host);
       }
       localStorage.setItem(keys.registry, JSON.stringify(registry));
       localStorage.setItem(keys.disableSeedOnce, nonce);
     },
     {
-      hosts: offlineHosts,
+      host: offlineHost,
       keys: {
         registry: REGISTRY_KEY,
         nonce: SEED_NONCE_KEY,
         disableSeedOnce: DISABLE_DEFAULT_SEED_ONCE_KEY,
       },
-      primaryLabel: options.primaryLabel,
+      primaryLabel: input.primaryLabel,
     },
   );
 

packages/app/e2e/support/helpers/sidebar-footer-overflow.ts

@@ -1,127 +0,0 @@
-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);
-  }
-}

packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/PanelEdgeTest.kt

@@ -1,158 +0,0 @@
-package sh.paseo.scroll
-
-import android.app.Activity
-import android.content.Intent
-import android.os.SystemClock
-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.soloader.OpenSourceMergedSoMapping
-import com.facebook.react.uimanager.DisplayMetricsHolder
-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
-
-/** Forward-order parent, as used by the current Android timeline, and a nested panel at its edge. */
-@RunWith(AndroidJUnit4::class)
-class PanelEdgeTest {
-  private val instrumentation = InstrumentationRegistry.getInstrumentation()
-  private var activity: Activity? = null
-  private lateinit var manager: ReactScrollViewManager
-
-  @After fun finish() {
-    instrumentation.runOnMainSync { activity?.finish() }
-  }
-
-  @Test fun panelBottomEdgeLeavesTimelineStill() {
-    val (parent, child) = openPanel()
-    instrumentation.runOnMainSync {
-      child.scrollTo(0, 600)
-      assertTrue(child.startNestedScroll(View.SCROLL_AXIS_VERTICAL))
-      child.dispatchNestedScroll(0, 0, 0, 100, null)
-      child.stopNestedScroll()
-      assertEquals("Panel stays at its bottom", 600, child.scrollY)
-      assertEquals("Panel overshoot must leave timeline still", 400, parent.scrollY)
-    }
-  }
-
-  @Test fun panelTopEdgeLeavesTimelineStill() {
-    val (parent, child) = openPanel()
-    instrumentation.runOnMainSync {
-      child.scrollTo(0, 0)
-      assertTrue(child.startNestedScroll(View.SCROLL_AXIS_VERTICAL))
-      child.dispatchNestedScroll(0, 0, 0, -100, null)
-      child.stopNestedScroll()
-      assertEquals("Panel stays at its top", 0, child.scrollY)
-      assertEquals("Panel overshoot must leave timeline still", 400, parent.scrollY)
-    }
-  }
-
-  @Test fun panelFlingLeavesTimelineStill() {
-    val (parent, child) = openPanel()
-    instrumentation.runOnMainSync {
-      child.scrollTo(0, 600)
-      assertTrue(child.startNestedScroll(View.SCROLL_AXIS_VERTICAL))
-      child.dispatchNestedFling(0f, 1500f, false)
-      child.stopNestedScroll()
-    }
-    SystemClock.sleep(500)
-    instrumentation.runOnMainSync {
-      assertEquals("Panel fling must leave timeline still", 400, parent.scrollY)
-    }
-  }
-
-  @Test fun disablingChildNestedScrollPreventsHandoff() {
-    val (parent, child) = openPanel()
-    instrumentation.runOnMainSync {
-      child.isNestedScrollingEnabled = false
-      assertEquals(false, child.startNestedScroll(View.SCROLL_AXIS_VERTICAL))
-      child.dispatchNestedScroll(0, 0, 0, 100, null)
-      assertEquals(400, parent.scrollY)
-    }
-  }
-
-  @Test fun ordinaryParentStillConsumesNestedOvershoot() {
-    val (parent, child) = openPanel()
-    instrumentation.runOnMainSync {
-      manager.setNativeId(parent, "ordinary-scroll-parent")
-      assertTrue(child.startNestedScroll(View.SCROLL_AXIS_VERTICAL))
-      child.dispatchNestedScroll(0, 0, 0, 100, null)
-      child.stopNestedScroll()
-      assertEquals("Ordinary parent retains framework handoff", 500, parent.scrollY)
-    }
-  }
-
-  @Test fun ordinaryParentStillConsumesUnconsumedFling() {
-    val (parent, child) = openPanel()
-    instrumentation.runOnMainSync {
-      manager.setNativeId(parent, "ordinary-scroll-parent")
-      child.scrollTo(0, 600)
-      assertTrue(child.startNestedScroll(View.SCROLL_AXIS_VERTICAL))
-      child.dispatchNestedFling(0f, 1500f, false)
-      child.stopNestedScroll()
-    }
-    SystemClock.sleep(500)
-    instrumentation.runOnMainSync { assertTrue(parent.scrollY > 400) }
-  }
-
-  @Test fun consumedPanelFlingDoesNotStartParentFling() {
-    val (parent, child) = openPanel()
-    instrumentation.runOnMainSync {
-      assertTrue(child.startNestedScroll(View.SCROLL_AXIS_VERTICAL))
-      assertEquals(false, child.dispatchNestedFling(0f, 1500f, true))
-      child.stopNestedScroll()
-      assertEquals(400, parent.scrollY)
-    }
-  }
-
-  @Test fun panelInteriorScrollingLeavesTimelineStill() {
-    val (parent, child) = openPanel()
-    instrumentation.runOnMainSync {
-      child.scrollTo(0, 100)
-      assertEquals(100, child.scrollY)
-      assertEquals(400, parent.scrollY)
-      parent.scrollTo(0, 500)
-      assertEquals("Direct timeline scrolling remains available", 500, parent.scrollY)
-    }
-  }
-
-  private fun openPanel(): Pair<ReactScrollView, ReactScrollView> {
-    val started = instrumentation.startActivitySync(
-      Intent(instrumentation.targetContext, Activity::class.java).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
-    )
-    activity = started
-    lateinit var parent: ReactScrollView
-    lateinit var child: ReactScrollView
-    instrumentation.runOnMainSync {
-      DisplayMetricsHolder.initDisplayMetricsIfNotInitialized(started)
-      SoLoader.init(started, OpenSourceMergedSoMapping)
-      val react = ScrollTestContext(started.applicationContext)
-      val context = ThemedReactContext(react, started)
-      manager = PaseoScrollPackage().createViewManager(react, ReactScrollViewManager.REACT_CLASS) as ReactScrollViewManager
-      parent = manager.createViewInstance(context)
-      manager.setNativeId(parent, "agent-chat-scroll-native-virtualized")
-      child = manager.createViewInstance(context)
-      child.isNestedScrollingEnabled = true
-      val content = ReactViewGroup(context)
-      content.addView(child, FrameLayout.LayoutParams(300, 200).apply { topMargin = 400 })
-      parent.addView(content)
-      val childContent = ReactViewGroup(context)
-      child.addView(childContent)
-      started.setContentView(FrameLayout(started).apply { addView(parent, FrameLayout.LayoutParams(300, 400)) })
-      parent.layout(0, 0, 300, 400)
-      content.layout(0, 0, 300, 2000)
-      child.layout(0, 400, 300, 600)
-      childContent.layout(0, 0, 300, 800)
-      parent.scrollTo(0, 400)
-    }
-    return Pair(parent, child)
-  }
-}

packages/app/modules/paseo-scroll/android/src/androidTest/java/sh/paseo/scroll/ScrollTestContext.java

@@ -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 own event sink for a context without JavaScript. */
-final class ScrollTestContext extends BridgeReactContext implements EventDispatcherProvider {
-  ScrollTestContext(Context context) {
-    super(context);
-  }
-
-  @Override
-  public EventDispatcher getEventDispatcher() {
-    return BlackHoleEventDispatcher.INSTANCE;
-  }
-}

packages/app/modules/paseo-scroll/android/src/main/java/sh/paseo/scroll/PaseoScrollView.java

@@ -12,13 +12,10 @@ import com.facebook.react.views.scroll.ReactScrollView;
 import com.facebook.react.views.scroll.ReactScrollViewHelper;
 
 /**
- * React Native's vertical scroll view with timeline corrections. Java, because the content-position
+ * 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, packages/app/src/agent-stream/strategy-native.tsx.
-  private static final String TIMELINE_NATIVE_ID = "agent-chat-scroll-native-virtualized";
-
   // 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";
 
@@ -35,26 +32,6 @@ final class PaseoScrollView extends ReactScrollView {
     super(context);
   }
 
-  // A panel owns its gesture through its edges; remaining child motion must not move the chat
-  // behind it. The timeline's native identity stays present when its end pin is removed for
-  // reading history. Ordinary parents retain Android's nested-scroll handoff.
-  @Override
-  public void onNestedScroll(
-      View target, int dxConsumed, int dyConsumed, int dxUnconsumed, int dyUnconsumed) {
-    if (isTimeline()) return;
-    super.onNestedScroll(target, dxConsumed, dyConsumed, dxUnconsumed, dyUnconsumed);
-  }
-
-  @Override
-  public boolean onNestedFling(View target, float velocityX, float velocityY, boolean consumed) {
-    if (isTimeline() && !consumed) return true;
-    return super.onNestedFling(target, velocityX, velocityY, consumed);
-  }
-
-  private boolean isTimeline() {
-    return TIMELINE_NATIVE_ID.equals(getTag(R.id.view_tag_native_id));
-  }
-
   @Override
   public void setMaintainVisibleContentPosition(
       @Nullable MaintainVisibleScrollPositionHelper.Config config) {

packages/app/src/agent-stream/bottom-anchor-controller.ts

@@ -65,6 +65,7 @@ interface BottomAnchorControllerDriver {
     pendingVerification: AttemptContext | null;
     blockedReason: BottomAnchorBlockedReason | null;
   };
+  resetForAgent: () => void;
   applyRouteRequest: (request: BottomAnchorRouteRequest | null) => void;
   requestLocalAnchor: (request: BottomAnchorLocalRequest) => void;
   beginUserScroll: () => void;
@@ -479,6 +480,17 @@ function createBottomAnchorControllerDriver(
         blockedReason,
       };
     },
+    resetForAgent() {
+      lastRouteRequestKey = null;
+      pendingRequest = null;
+      blockedReason = null;
+      cancelPendingAttempt();
+      stickyMeasurementRevision = 0;
+      lastVerifiedStickyMeasurementRevision = 0;
+      isUserScrollActive = false;
+      mode = "sticky-bottom";
+      input.onModeChange("sticky-bottom");
+    },
     applyRouteRequest(request) {
       if (!request) {
         return;
@@ -729,6 +741,10 @@ export function useBottomAnchorController(input: {
     });
   }
 
+  useEffect(() => {
+    driverRef.current?.resetForAgent();
+  }, [input.agentId]);
+
   useEffect(() => {
     driverRef.current?.applyRouteRequest(input.routeRequest);
   }, [input.routeRequest]);

packages/app/src/agent-stream/legend-list-held-row.browser.test.tsx

@@ -129,8 +129,7 @@ function mountList(heldRowId: string) {
     }
     return position - state.scroll;
   };
-  const rowSize = (rowId: string) => listRef.current?.getState().sizes.get(rowId);
-  return { render, scrollTo, heldRowTop, rowSize };
+  return { render, scrollTo, heldRowTop };
 }
 
 it("anchors a data change on a held row whose top is above the viewport", async () => {
@@ -170,21 +169,3 @@ it("anchors a size change on a held row whose top is above the viewport", async
 
   expect(list.heldRowTop()).toBe(-20);
 });
-
-it("keeps measured row sizes while the list is not laid out", async () => {
-  // A hidden retained tab is display: none. Its rows still render, and a row measured there
-  // reports 0 x 0. When the tab shows again, a row whose frame did not change gets no new layout
-  // event, so a 0 recorded while hidden would stay and the next row would overlap it.
-  const rows: Row[] = Array.from({ length: 3 }, (_, index) => ({ id: `row-${index}`, height: 40 }));
-  const list = mountList("row-0");
-  list.render(rows);
-  await wait(150);
-  expect(rows.map((row) => list.rowSize(row.id))).toEqual([40, 40, 40]);
-
-  host.style.display = "none";
-  await wait(150);
-  list.render(rows.map((row) => ({ ...row })));
-  await wait(150);
-
-  expect(rows.map((row) => list.rowSize(row.id))).toEqual([40, 40, 40]);
-});

packages/app/src/agent-stream/strategy-native.tsx

@@ -137,8 +137,9 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
   } = props;
   const { renderHistoryMountedRow, renderLiveHeadRow, renderLiveAuxiliary } = renderers;
   const listRef = useRef<LegendListRef>(null);
-  // LegendList places the rows once, behind a hidden reveal, when the list mounts.
-  const [isListPlaced, setIsListPlaced] = useState(false);
+  // 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({
@@ -383,6 +384,23 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
   );
 
   useEffect(() => {
+    streamViewportMetricsRef.current = {
+      containerKey: "native-virtualized",
+      contentHeight: 0,
+      viewportWidth: 0,
+      viewportHeight: 0,
+      offsetY: 0,
+      viewportMeasuredForKey: null,
+      contentMeasuredForKey: null,
+    };
+    scrollOffsetYRef.current = 0;
+    isUserScrollActiveRef.current = false;
+    clearPendingUserScrollEnd();
+    disclosureHold.cancel();
+    historyStartReadyRef.current = false;
+    const initialHistoryStartState = createHistoryStartPaginationState();
+    historyStartPaginationStateRef.current = initialHistoryStartState;
+    setHistoryStartPaginationState(initialHistoryStartState);
     const frame = requestAnimationFrame(() => {
       historyStartReadyRef.current = true;
       evaluateHistoryStart();
@@ -393,7 +411,7 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
       historyStartSettleSchedulerRef.current?.cancel();
       historyStartSettleSchedulerRef.current = null;
     };
-  }, [clearPendingUserScrollEnd, evaluateHistoryStart]);
+  }, [agentId, clearPendingUserScrollEnd, disclosureHold, evaluateHistoryStart]);
 
   useEffect(() => {
     const handle: StreamViewportHandle = {
@@ -605,7 +623,7 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
 
   const handleListPlaced = useStableEvent(() => {
     isListPlacedRef.current = true;
-    setIsListPlaced(true);
+    setPlacedAgentId(agentId);
     streamViewportMetricsRef.current = {
       ...streamViewportMetricsRef.current,
       contentMeasuredForKey: "native-virtualized",
@@ -675,7 +693,6 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
       extraData={renderHistoryMountedRow}
       keyExtractor={keyExtractor}
       testID="agent-chat-scroll"
-      // The Android scroll owner identifies the timeline to contain nested panel gestures.
       nativeID="agent-chat-scroll-native-virtualized"
       ListHeaderComponent={historyStartContent}
       ListFooterComponent={liveAuxiliaryContent ?? undefined}
@@ -694,6 +711,7 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
       onContentSizeChange={handleContentSizeChange}
       onItemSizeChanged={handleItemSizeChanged}
       onReady={handleListPlaced}
+      dataKey={agentId}
       maintainVisibleContentPosition={maintainVisibleContentPosition}
       renderScrollComponent={renderScrollComponent}
       recycleItems={false}

packages/app/src/agent-stream/strategy-web.tsx

@@ -839,6 +839,10 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
   ]);
 
   useEffect(() => {
+    const initialHistoryStartState = createHistoryStartPaginationState();
+    historyStartPaginationStateRef.current = initialHistoryStartState;
+    setHistoryStartPaginationState(initialHistoryStartState);
+    readingAnchor.reset();
     const frame = window.requestAnimationFrame(() => {
       historyStartReadyRef.current = true;
       evaluateHistoryStart();
@@ -849,7 +853,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
       historyStartSettleSchedulerRef.current?.cancel();
       historyStartSettleSchedulerRef.current = null;
     };
-  }, [evaluateHistoryStart]);
+  }, [evaluateHistoryStart, props.agentId, readingAnchor]);
 
   useLayoutEffect(() => {
     if (!isActiveRef.current || !isActivationReady) {
@@ -1391,7 +1395,11 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
 export function createWebStreamStrategy(input: CreateWebStreamStrategyInput): StreamStrategy {
   return createStreamStrategy({
     render: (renderInput) => (
-      <WebStreamViewport {...renderInput} isMobileBreakpoint={input.isMobileBreakpoint} />
+      <WebStreamViewport
+        key={renderInput.agentId}
+        {...renderInput}
+        isMobileBreakpoint={input.isMobileBreakpoint}
+      />
     ),
     orderTailReverse: false,
     orderHeadReverse: false,

packages/app/src/agent-stream/use-stream-history-window.test.tsx

@@ -21,7 +21,7 @@ describe("useStreamHistoryWindow", () => {
     ]).flat();
 
     const { result } = renderHook(() =>
-      useStreamHistoryWindow({ items, loadRemoteOlder: vi.fn() }),
+      useStreamHistoryWindow({ agentId: "agent-1", items, loadRemoteOlder: vi.fn() }),
     );
 
     expect(result.current.start).toBe(2);
@@ -35,6 +35,7 @@ describe("useStreamHistoryWindow", () => {
     const loadRemoteOlder = vi.fn(async () => true);
     const { result } = renderHook(() =>
       useStreamHistoryWindow({
+        agentId: "agent-1",
         items: [
           message("u1", "user_message"),
           message("a1", "assistant_message"),
@@ -66,7 +67,8 @@ describe("useStreamHistoryWindow", () => {
       message("a2", "assistant_message"),
     ];
     const { result, rerender } = renderHook(
-      ({ history }) => useStreamHistoryWindow({ items: history, loadRemoteOlder: vi.fn() }),
+      ({ history }) =>
+        useStreamHistoryWindow({ agentId: "agent-1", items: history, loadRemoteOlder: vi.fn() }),
       { initialProps: { history: items } },
     );
 
@@ -89,7 +91,8 @@ describe("useStreamHistoryWindow", () => {
       message("a2", "assistant_message"),
     ];
     const { result, rerender } = renderHook(
-      ({ history }) => useStreamHistoryWindow({ items: history, loadRemoteOlder: vi.fn() }),
+      ({ history }) =>
+        useStreamHistoryWindow({ agentId: "agent-1", items: history, loadRemoteOlder: vi.fn() }),
       { initialProps: { history: items } },
     );
 
@@ -105,7 +108,8 @@ describe("useStreamHistoryWindow", () => {
       configurable: true,
     });
     const { result, rerender } = renderHook(
-      ({ history }) => useStreamHistoryWindow({ items: history, loadRemoteOlder: vi.fn() }),
+      ({ history }) =>
+        useStreamHistoryWindow({ agentId: "agent-1", items: history, loadRemoteOlder: vi.fn() }),
       {
         initialProps: {
           history: [
@@ -138,6 +142,7 @@ describe("useStreamHistoryWindow", () => {
     });
     const { result } = renderHook(() =>
       useStreamHistoryWindow({
+        agentId: "agent-1",
         items: [
           message("u1", "user_message"),
           message("a1", "assistant_message"),

packages/app/src/agent-stream/use-stream-history-window.ts

@@ -28,17 +28,22 @@ function findEarlierHistoryWindowStart(input: {
 }
 
 interface HistoryWindowBoundary {
+  agentId: string;
   boundaryItemId: string | null;
   initialized: boolean;
 }
 
 function reconcileHistoryWindow(input: {
   current: HistoryWindowBoundary;
+  agentId: string;
   boundaryIndex: number;
   initialBoundaryItemId: string | null;
   hasItems: boolean;
 }): HistoryWindowBoundary {
-  const { current, boundaryIndex, initialBoundaryItemId, hasItems } = input;
+  const { current, agentId, boundaryIndex, initialBoundaryItemId, hasItems } = input;
+  if (current.agentId !== agentId) {
+    return { agentId, boundaryItemId: initialBoundaryItemId, initialized: hasItems };
+  }
   if (!current.initialized && hasItems) {
     return { ...current, boundaryItemId: initialBoundaryItemId, initialized: true };
   }
@@ -49,26 +54,28 @@ function reconcileHistoryWindow(input: {
 }
 
 export function useStreamHistoryWindow(input: {
+  agentId: string;
   items: StreamItem[];
   loadRemoteOlder: () => boolean | Promise<boolean>;
 }) {
-  const { items, loadRemoteOlder } = input;
+  const { agentId, items, loadRemoteOlder } = input;
   const initialStart = useMemo(
     () => findMountedWindowStart({ items, minMountedCount: getMountedRecentStreamItems() }),
     [items],
   );
   const initialBoundaryItemId = initialStart === 0 ? null : (items[initialStart]?.id ?? null);
   const [window, setWindow] = useState(() => ({
+    agentId,
     boundaryItemId: initialBoundaryItemId,
     initialized: items.length > 0,
   }));
-  const boundaryItemId = window.boundaryItemId;
+  const boundaryItemId = window.agentId === agentId ? window.boundaryItemId : null;
   const boundaryIndex = useMemo(
     () => (boundaryItemId === null ? -1 : items.findIndex((item) => item.id === boundaryItemId)),
     [boundaryItemId, items],
   );
   let start = initialStart;
-  if (window.initialized) {
+  if (window.agentId === agentId && window.initialized) {
     if (window.boundaryItemId === null) {
       start = 0;
     } else if (boundaryIndex >= 0) {
@@ -80,12 +87,13 @@ export function useStreamHistoryWindow(input: {
     setWindow((current) =>
       reconcileHistoryWindow({
         current,
+        agentId,
         boundaryIndex,
         initialBoundaryItemId,
         hasItems: items.length > 0,
       }),
     );
-  }, [boundaryIndex, initialBoundaryItemId, items.length]);
+  }, [agentId, boundaryIndex, initialBoundaryItemId, items.length]);
 
   const revealLoadedHistory = useCallback(
     (itemId?: string): boolean => {
@@ -98,12 +106,13 @@ export function useStreamHistoryWindow(input: {
         return false;
       }
       setWindow({
+        agentId,
         boundaryItemId: items[nextStart]?.id ?? null,
         initialized: true,
       });
       return true;
     },
-    [items, start],
+    [agentId, items, start],
   );
   const loadOlder = useCallback(async (): Promise<boolean> => {
     return revealLoadedHistory() || (await loadRemoteOlder());

packages/app/src/agent-stream/view.tsx

@@ -430,6 +430,10 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
           loadOlder: historyPagination.onLoadOlder,
         }
       : agentHistoryPagination;
+    useEffect(() => {
+      setExpandedInlineToolCallIds(new Set());
+      setExpandedTurnHostIds(new Set());
+    }, [agentId]);
 
     const isActive = useRetainedPanelActive();
     const openInlineFile = useStableEvent(
@@ -472,7 +476,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
     useEffect(() => {
       if (!isActive) inlinePathOpener.cancel();
       return () => inlinePathOpener.cancel();
-    }, [inlinePathOpener, isActive]);
+    }, [inlinePathOpener, isActive, agentId]);
     const handleInlinePathPress = useStableEvent(
       (target: InlinePathTarget, disposition: OpenFileDisposition) => {
         if (isActive) void inlinePathOpener.open(target, disposition);
@@ -547,6 +551,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
       revealLoadedHistory,
       loadOlder,
     } = useStreamHistoryWindow({
+      agentId,
       items: presentation.tail,
       loadRemoteOlder,
     });

packages/app/src/components/left-sidebar.tsx

@@ -17,7 +17,6 @@ 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";
@@ -41,17 +40,6 @@ 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";
@@ -67,7 +55,6 @@ 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";
@@ -92,9 +79,6 @@ 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 {
@@ -426,72 +410,35 @@ 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. Actions that
-  // don't fit move behind a caret before Settings.
+  // One line of icons: Add project, Usage, Hosts, then Help and Settings at the end.
   return (
     <UsageSidebarRoot>
       <View style={styles.footerContainer} testID="sidebar-footer">
         <SidebarFooterRows onBeforeNavigate={onBeforeNavigate} />
-        <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.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.footerSpacer} />
-          {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}
+          <SidebarHelpMenu />
+          <FooterIconButton
+            onPress={handleSettings}
+            testID="sidebar-settings"
+            label={labels.settings}
+            icon={Settings}
+            shortcutKeys={settingsKeys}
+          />
         </View>
       </View>
     </UsageSidebarRoot>
@@ -990,12 +937,10 @@ 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",
-    minHeight: mapLayout(density.iconButton, (height) => height + theme.spacing[1.5] * 2),
-    paddingHorizontal: FOOTER_ROW_PADDING,
+    paddingHorizontal: theme.spacing[2],
     paddingVertical: theme.spacing[1.5],
   },
   // Pushes Help and Settings to the end of the icon line.

packages/app/src/components/sidebar-footer-layout.test.ts

@@ -1,89 +0,0 @@
-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: [] });
-    }
-  });
-});

packages/app/src/components/sidebar-footer-layout.ts

@@ -1,62 +0,0 @@
-/** 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)),
-  };
-}

packages/app/src/components/sidebar/sidebar-footer-menu-trigger.tsx

@@ -1,69 +0,0 @@
-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,
-  },
-}));

packages/app/src/components/sidebar/sidebar-footer-overflow-menu.tsx

@@ -1,245 +0,0 @@
-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>
-  );
-}

packages/app/src/components/sidebar/sidebar-help-menu.tsx

@@ -1,5 +1,5 @@
 import { useCallback, useState } from "react";
-import { View } from "react-native";
+import { Text, 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,13 +12,17 @@ import {
   DropdownMenuItem,
   DropdownMenuLabel,
   DropdownMenuSeparator,
+  DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
-import { SidebarFooterMenuTrigger } from "./sidebar-footer-menu-trigger";
+import { DensityIcon } from "@/components/ui/density-icon";
+import { SidebarFooterIconHighlight } from "./sidebar-footer-icon-highlight";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
 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";
@@ -73,32 +77,12 @@ 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();
 
@@ -115,65 +99,105 @@ export function SidebarHelpMenuItems() {
   }, []);
 
   return (
-    <>
-      <DropdownMenuLabel>{t("sidebar.help.sectionHelp")}</DropdownMenuLabel>
-      {shortcutsAvailable ? (
+    <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}
         <DropdownMenuItem
-          testID="sidebar-help-shortcuts"
-          leading={shortcutsLeadingIcon}
-          onSelect={openKeyboardShortcuts}
+          testID="sidebar-help-changelog"
+          leading={changelogLeadingIcon}
+          onSelect={openChangelog}
         >
-          {t("sidebar.help.shortcuts")}
+          {t("sidebar.help.whatsNew")}
         </DropdownMenuItem>
-      ) : 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"
+        <DropdownMenuItem
+          testID="sidebar-help-diagnostics"
+          leading={diagnosticLeadingIcon}
+          onSelect={openAppDiagnostic}
         >
-          {t("sidebar.help.appName")}
-        </DropdownMenuHint>
-        {hosts.map((host) => (
-          <HostVersionHint key={host.serverId} host={host} />
-        ))}
-      </View>
-    </>
+          {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>
   );
 }
 
 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],

packages/app/src/components/ui/anchor.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { computePosition, fitSurfaceWidth, getTransformOrigin, type Rect } from "./anchor";
+import { computePosition, 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,26 +97,3 @@ 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,
-    });
-  });
-});

packages/app/src/components/ui/anchor.ts

@@ -120,27 +120,6 @@ 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,

packages/app/src/components/ui/control-geometry.test.ts

@@ -14,8 +14,6 @@ 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";
@@ -92,11 +90,6 @@ 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),

packages/app/src/components/ui/control-geometry.ts

@@ -93,14 +93,6 @@ 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.

packages/app/src/components/ui/menu/menu-overlay.tsx

@@ -29,7 +29,6 @@ import type { KeyboardFocusScope } from "@/keyboard/actions";
 import { getOverlayRoot, OverlayLayerProvider, useOverlayLayer } from "@/lib/overlay-root";
 import {
   computePosition,
-  fitSurfaceWidth,
   getTransformOrigin,
   measureElement,
   type Alignment,
@@ -284,7 +283,11 @@ export function AnchoredSurface({
     const { width: screenWidth } = Dimensions.get("window");
     const resolvedWidthStyle: ViewStyle = fullWidth
       ? { width: screenWidth - horizontalPadding * 2 }
-      : fitSurfaceWidth({ width, minWidth, maxWidth }, screenWidth);
+      : {
+          ...(typeof width === "number" ? { width } : null),
+          ...(typeof minWidth === "number" ? { minWidth } : null),
+          ...(typeof maxWidth === "number" ? { maxWidth } : null),
+        };
     return [
       resolvedWidthStyle,
       {

packages/app/src/composer/draft/create-flow.test.ts

@@ -60,6 +60,17 @@ describe("useDraftAgentCreateFlow", () => {
 
     expect(result.current.isSubmitting).toBe(true);
     expect(result.current.draftAgent).toEqual({ currentAttempt: attempt });
+    expect(result.current.submittedStreamItems).toEqual([
+      {
+        kind: "user_message",
+        id: "msg-prepared",
+        clientMessageId: "msg-prepared",
+        text: "build this",
+        timestamp: attempt.timestamp,
+        images: [image],
+        attachments: [attachment],
+      },
+    ]);
     expect(createRequest).not.toHaveBeenCalled();
 
     await act(async () => {

packages/app/src/composer/draft/create-flow.ts

@@ -8,8 +8,15 @@ import {
 import { isActiveCreateFlowForDraft, useCreateFlowStore } from "@/stores/create-flow-store";
 import { handoffCreatedAgentMessageSubmission } from "@/composer/submission/writer";
 import { useSessionStore } from "@/stores/session-store";
-import { createUserMessage, type UserMessageImageAttachment } from "@/types/stream";
+import {
+  createUserMessage,
+  type StreamItem,
+  type UserMessageImageAttachment,
+} from "@/types/stream";
 import type { AgentAttachment } from "@getpaseo/protocol/messages";
+import type { PendingMessageSubmission } from "@/composer/submission/model";
+
+const EMPTY_STREAM_ITEMS: StreamItem[] = [];
 
 interface CreateAttempt {
   clientMessageId: string;
@@ -146,6 +153,38 @@ export function useDraftAgentCreateFlow<TDraftAgent, TCreateResult>({
   const formErrorMessage = machine.tag === "draft" ? machine.errorMessage : "";
   const isSubmitting = machine.tag === "creating";
 
+  const submittedStreamItems = useMemo<StreamItem[]>(() => {
+    if (machine.tag !== "creating") {
+      return EMPTY_STREAM_ITEMS;
+    }
+
+    if (
+      !machine.attempt.text &&
+      (!machine.attempt.images || machine.attempt.images.length === 0) &&
+      (!machine.attempt.attachments || machine.attempt.attachments.length === 0)
+    ) {
+      return EMPTY_STREAM_ITEMS;
+    }
+
+    return [
+      createUserMessage({
+        clientMessageId: machine.attempt.clientMessageId,
+        text: machine.attempt.text,
+        timestamp: machine.attempt.timestamp,
+        images: machine.attempt.images,
+        attachments: machine.attempt.attachments,
+      }),
+    ];
+  }, [machine]);
+  const pendingMessageSubmissions = useMemo<readonly PendingMessageSubmission[]>(() => {
+    if (machine.tag !== "creating") return [];
+    return [
+      {
+        clientMessageId: machine.attempt.clientMessageId,
+      },
+    ];
+  }, [machine]);
+
   const draftAgent = machine.tag === "creating" ? machine.draftAgent : null;
   const startCreateAttempt = useCallback(
     (attempt: CreateAttempt) => {
@@ -326,6 +365,8 @@ export function useDraftAgentCreateFlow<TDraftAgent, TCreateResult>({
     machine,
     formErrorMessage,
     isSubmitting,
+    submittedStreamItems,
+    pendingMessageSubmissions,
     draftAgent,
     handleCreateFromInput,
     continueCreateFromAttempt,

packages/app/src/composer/draft/timeline.test.ts

@@ -1,103 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { AgentAttachment } from "@getpaseo/protocol/messages";
-import type { PendingCreateAttempt } from "@/stores/create-flow-store";
-import type { UserMessageImageAttachment } from "@/types/stream";
-import { DRAFT_CAPABILITIES, resolveDraftTimeline } from "./timeline";
-
-const image: UserMessageImageAttachment = {
-  id: "image-1",
-  mimeType: "image/png",
-  storageType: "web-indexeddb",
-  storageKey: "image-key",
-  createdAt: 123,
-};
-const attachment = {
-  type: "review",
-  cwd: "/repo",
-  summary: "Review",
-} as unknown as AgentAttachment;
-
-function pendingAttempt(overrides: Partial<PendingCreateAttempt> = {}): PendingCreateAttempt {
-  return {
-    draftId: "draft-1",
-    serverId: "server-1",
-    agentId: null,
-    clientMessageId: "draft-1:initial-message",
-    text: "build this",
-    timestamp: Date.parse("2026-05-25T00:00:00.000Z"),
-    lifecycle: "active",
-    images: [image],
-    attachments: [attachment],
-    ...overrides,
-  };
-}
-
-describe("resolveDraftTimeline", () => {
-  it("shows the sent prompt pending with the turn working", () => {
-    const timeline = resolveDraftTimeline({
-      pending: pendingAttempt(),
-      serverId: "server-1",
-      tabId: "tab-1",
-      cwd: "/repo",
-    });
-
-    expect(timeline?.agent).toEqual({
-      serverId: "server-1",
-      id: "tab-1",
-      status: "running",
-      cwd: "/repo",
-      capabilities: DRAFT_CAPABILITIES,
-    });
-    expect(timeline?.streamItems).toEqual([
-      {
-        kind: "user_message",
-        id: "draft-1:initial-message",
-        clientMessageId: "draft-1:initial-message",
-        text: "build this",
-        timestamp: new Date("2026-05-25T00:00:00.000Z"),
-        images: [image],
-        attachments: [attachment],
-      },
-    ]);
-    expect(timeline?.pendingMessageSubmissions).toEqual([
-      { clientMessageId: "draft-1:initial-message" },
-    ]);
-    expect(timeline?.turnPresentation.isActive).toBe(true);
-  });
-
-  it("keeps the prompt once the agent is created, until the tab retargets", () => {
-    const timeline = resolveDraftTimeline({
-      pending: pendingAttempt({ lifecycle: "sent", agentId: "agent-1" }),
-      serverId: "server-1",
-      tabId: "tab-1",
-      cwd: "/repo",
-    });
-
-    expect(timeline?.streamItems).toHaveLength(1);
-  });
-
-  it("shows only the working turn for a prompt without content", () => {
-    const timeline = resolveDraftTimeline({
-      pending: pendingAttempt({ text: "", images: undefined, attachments: undefined }),
-      serverId: "server-1",
-      tabId: "tab-1",
-      cwd: "/repo",
-    });
-
-    expect(timeline?.streamItems).toEqual([]);
-    expect(timeline?.turnPresentation.isActive).toBe(true);
-  });
-
-  it("shows no timeline before a prompt is sent, after it fails, or on another host", () => {
-    const base = { serverId: "server-1", tabId: "tab-1", cwd: "/repo" };
-
-    expect(resolveDraftTimeline({ ...base, pending: undefined })).toBeNull();
-    expect(
-      resolveDraftTimeline({ ...base, pending: pendingAttempt({ lifecycle: "abandoned" }) }),
-    ).toBeNull();
-    expect(
-      resolveDraftTimeline({ ...base, pending: pendingAttempt({ serverId: "server-2" }) }),
-    ).toBeNull();
-    expect(resolveDraftTimeline({ ...base, cwd: null, pending: pendingAttempt() })).toBeNull();
-  });
-});

packages/app/src/composer/draft/timeline.ts

@@ -1,102 +0,0 @@
-import { useMemo } from "react";
-import type { AgentCapabilityFlags } from "@getpaseo/protocol/agent-types";
-import type { PendingMessageSubmission } from "@/composer/submission/model";
-import type { AgentScreenAgent } from "@/hooks/use-agent-screen-state-machine";
-import { type PendingCreateAttempt, useCreateFlowStore } from "@/stores/create-flow-store";
-import { useWorkspaceFields } from "@/stores/session-store-hooks";
-import {
-  resolveTurnPresentation,
-  TURN_LIVENESS_IDLE,
-  type TurnPresentation,
-} from "@/timeline/turn-liveness";
-import { createUserMessage, type StreamItem } from "@/types/stream";
-import type { WorkspaceDraftTabSetup } from "@/workspace-tabs/model";
-import { resolveDraftWorkingDirectory } from "@/composer/draft/workspace-tab-core";
-
-export const DRAFT_CAPABILITIES: AgentCapabilityFlags = {
-  supportsStreaming: true,
-  supportsSessionPersistence: false,
-  supportsDynamicModes: false,
-  supportsMcpServers: false,
-  supportsReasoningStream: false,
-  supportsToolInvocations: false,
-};
-
-export interface DraftConversation {
-  tabId: string;
-  workspaceId: string;
-  draftId: string;
-  setup?: WorkspaceDraftTabSetup;
-}
-
-/** The timeline a draft shows while its first prompt creates the agent. */
-export interface DraftTimeline {
-  agent: AgentScreenAgent;
-  streamItems: StreamItem[];
-  pendingMessageSubmissions: readonly PendingMessageSubmission[];
-  turnPresentation: TurnPresentation;
-}
-
-const EMPTY_STREAM_ITEMS: StreamItem[] = [];
-
-/**
- * The sent prompt, pending, with the turn working. The created agent's timeline carries the same
- * row (same client message id), so the handoff only changes who owns it.
- */
-export function resolveDraftTimeline(input: {
-  pending: PendingCreateAttempt | undefined;
-  serverId: string;
-  tabId: string;
-  cwd: string | null;
-}): DraftTimeline | null {
-  const { pending, serverId, tabId, cwd } = input;
-  if (!pending || pending.serverId !== serverId || pending.lifecycle === "abandoned" || !cwd) {
-    return null;
-  }
-  const hasContent =
-    pending.text.length > 0 ||
-    (pending.images?.length ?? 0) > 0 ||
-    (pending.attachments?.length ?? 0) > 0;
-  return {
-    agent: { serverId, id: tabId, status: "running", cwd, capabilities: DRAFT_CAPABILITIES },
-    streamItems: hasContent
-      ? [
-          createUserMessage({
-            clientMessageId: pending.clientMessageId,
-            text: pending.text,
-            timestamp: new Date(pending.timestamp),
-            images: pending.images,
-            attachments: pending.attachments,
-          }),
-        ]
-      : EMPTY_STREAM_ITEMS,
-    pendingMessageSubmissions: [{ clientMessageId: pending.clientMessageId }],
-    turnPresentation: resolveTurnPresentation(TURN_LIVENESS_IDLE, true),
-  };
-}
-
-export function useDraftTimeline(input: {
-  serverId: string;
-  draft: DraftConversation | null;
-}): DraftTimeline | null {
-  const { serverId, draft } = input;
-  const pending = useCreateFlowStore((state) =>
-    draft ? state.pendingByDraftId[draft.draftId] : undefined,
-  );
-  const workspaceDirectory = useWorkspaceFields(
-    serverId,
-    draft?.workspaceId ?? null,
-    (workspace) => workspace.workspaceDirectory,
-  );
-  const cwd = draft
-    ? resolveDraftWorkingDirectory({
-        workspaceDirectory: workspaceDirectory || null,
-        initialSetup: draft.setup ?? null,
-      })
-    : null;
-  const tabId = draft?.tabId ?? "";
-  return useMemo(
-    () => resolveDraftTimeline({ pending, serverId, tabId, cwd }),
-    [cwd, pending, serverId, tabId],
-  );
-}

packages/app/src/composer/draft/workspace-tab-core.ts

@@ -1,5 +1,4 @@
 import { resolveSubmissionReadiness } from "@/provider-selection/provider-selection";
-import type { WorkspaceDraftTabSetup } from "@/workspace-tabs/model";
 
 export interface WorkspaceDraftAutoSubmitConfig {
   provider: string;
@@ -51,13 +50,3 @@ export function validateDraftSubmission(input: {
   });
   return readiness.ok ? null : (readiness.reason ?? null);
 }
-
-export function resolveDraftWorkingDirectory(input: {
-  workspaceDirectory: string | null;
-  initialSetup: WorkspaceDraftTabSetup | null;
-}): string | null {
-  if (input.initialSetup) {
-    return input.initialSetup.cwd;
-  }
-  return input.workspaceDirectory;
-}

packages/app/src/composer/draft/workspace-tab.tsx

@@ -1,17 +1,21 @@
 import { useCallback, useEffect, useMemo, useRef } from "react";
-import { Keyboard, StyleSheet as RNStyleSheet, Text, View } from "react-native";
+import { Keyboard, ScrollView, StyleSheet as RNStyleSheet, Text, View } from "react-native";
 import { useTranslation } from "react-i18next";
 import { StyleSheet } from "react-native-unistyles";
+import { ComposerDock } from "@/composer/dock";
 import { useContainerWidthBelow } from "@/hooks/use-container-width";
 import invariant from "tiny-invariant";
 import { Composer } from "@/composer";
-import { type ComposerEditingSession, useComposerFullscreen } from "@/composer/editing-session";
+import { useComposerEditingSession, useComposerFullscreen } from "@/composer/editing-session";
+import { FileDropZone } from "@/components/file-drop/file-drop-zone";
 import { ComposerImportPill } from "@/composer/draft/import-pill";
 import { COMPOSER_PILL_CLEARANCE } from "@/composer/pill-styles";
+import { AgentStreamView } from "@/agent-stream/view";
 import { composerWorkspaceAttachment } from "@/composer/attachments/workspace";
 import { useAgentInputDraft } from "@/composer/draft/input-draft";
 import type { CreateAgentInitialValues } from "@/hooks/use-agent-form-state";
 import { useDraftAgentCreateFlow, type DraftCreateAttempt } from "@/composer/draft/create-flow";
+import { resolveTurnPresentation, TURN_LIVENESS_IDLE } from "@/timeline/turn-liveness";
 import { useHostRuntimeClient, useHostRuntimeIsConnected } from "@/runtime/host-runtime";
 import { buildWorkspaceDraftAgentConfig } from "@/screens/workspace/workspace-draft-agent-config";
 import { buildDraftStoreKey } from "@/stores/draft-keys";
@@ -21,13 +25,13 @@ import { useWorkspaceFields } from "@/stores/session-store-hooks";
 import { useWorkspaceDraftSubmissionStore } from "@/stores/workspace-draft-submission-store";
 import { useAgentControlCommandCenterActions } from "@/command-center/agent-control-registration";
 import { encodeImages } from "@/utils/encode-images";
+import type { WorkspaceFileOpenRequest } from "@/workspace/file-open";
 import { shouldAutoFocusWorkspaceDraftComposer } from "@/screens/workspace/workspace-draft-pane-focus";
 import {
-  resolveDraftWorkingDirectory,
   shouldAllowEmptyDraftText,
   validateDraftSubmission,
 } from "@/composer/draft/workspace-tab-core";
-import { DRAFT_CAPABILITIES } from "@/composer/draft/timeline";
+import type { AgentCapabilityFlags } from "@getpaseo/protocol/agent-types";
 import type { AgentSnapshotPayload } from "@getpaseo/protocol/messages";
 import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
 import type { WorkspaceComposerAttachment } from "@/attachments/types";
@@ -46,6 +50,16 @@ import {
 import { openWorkspaceChanges } from "@/workspace-tabs/open-supporting-view";
 import { useSettings } from "@/hooks/use-settings";
 
+const EMPTY_PENDING_PERMISSIONS = new Map();
+const DRAFT_CAPABILITIES: AgentCapabilityFlags = {
+  supportsStreaming: true,
+  supportsSessionPersistence: false,
+  supportsDynamicModes: false,
+  supportsMcpServers: false,
+  supportsReasoningStream: false,
+  supportsToolInvocations: false,
+};
+
 interface AutoSubmitConfig {
   provider: string;
   modeId: string | null;
@@ -246,15 +260,25 @@ function buildDraftInitialValues(input: {
   };
 }
 
-interface WorkspaceDraftComposerProps {
+function resolveDraftWorkingDirectory(input: {
+  workspaceDirectory: string | null;
+  initialSetup: WorkspaceDraftTabSetup | null;
+}): string | null {
+  if (input.initialSetup) {
+    return input.initialSetup.cwd;
+  }
+  return input.workspaceDirectory;
+}
+
+interface WorkspaceDraftAgentTabProps {
   serverId: string;
   workspaceId: string;
   tabId: string;
   draftId: string;
   initialSetup?: WorkspaceDraftTabSetup;
   isPaneFocused: boolean;
-  editingSession: ComposerEditingSession;
   onCreated: (snapshot: AgentSnapshotPayload) => void;
+  onOpenWorkspaceFile: (request: WorkspaceFileOpenRequest) => void;
   onOpenImportSheet?: () => void;
 }
 
@@ -268,21 +292,17 @@ function resolveImportPillPress(
   return onOpenImportSheet ?? null;
 }
 
-/**
- * Creates the agent from the draft's first prompt. The conversation panel shows that prompt in
- * the timeline from the create-flow store while the agent is created.
- */
-export function WorkspaceDraftComposer({
+export function WorkspaceDraftAgentTab({
   serverId,
   workspaceId,
   tabId,
   draftId,
   initialSetup = undefined,
   isPaneFocused,
-  editingSession,
   onCreated,
+  onOpenWorkspaceFile,
   onOpenImportSheet,
-}: WorkspaceDraftComposerProps) {
+}: WorkspaceDraftAgentTabProps) {
   const { t } = useTranslation();
   const client = useHostRuntimeClient(serverId);
   const isConnected = useHostRuntimeIsConnected(serverId);
@@ -367,6 +387,7 @@ export function WorkspaceDraftComposer({
   }, [pendingCreateAttempt]);
   const allowsEmptyAutoSubmit = pendingAutoSubmit?.allowEmptyText === true;
   const isCompactFormFactor = useIsCompactFormFactor();
+  const editingSession = useComposerEditingSession("chat");
   const isComposerFullscreen = useComposerFullscreen(editingSession);
   const { onLayout: onInputAreaLayout, isBelow: isCompactComposerLayout } = useContainerWidthBelow(
     COMPACT_CONTENT_WIDTH,
@@ -400,71 +421,82 @@ export function WorkspaceDraftComposer({
     [isCompactFormFactor, openInSidePane, serverId, workspaceId],
   );
 
-  const { formErrorMessage, isSubmitting, handleCreateFromInput, continueCreateFromAttempt } =
-    useDraftAgentCreateFlow<Agent, AgentSnapshotPayload>({
-      draftId,
-      getPendingServerId: () => serverId,
-      initialAttempt: initialCreateAttempt,
-      allowEmptyText: allowsEmptyAutoSubmit,
-      validateBeforeSubmit: ({ text, attachments }) => {
-        const allowsEmptyDraftText = shouldAllowEmptyDraftText({
-          allowsEmptyAutoSubmit,
-          attachments,
-        });
-        return validateDraftSubmission({
-          text,
-          allowsEmptyAutoSubmit: allowsEmptyDraftText,
-          composerState,
-          autoSubmitConfig,
-          workspaceDirectory: draftWorkingDirectory,
-          isConnected,
-        });
-      },
-      onBeforeSubmit: async () => {
-        await composerState.persistFormPreferences();
-        if (isWeb) {
-          (document.activeElement as HTMLElement | null)?.blur?.();
-        }
-        Keyboard.dismiss();
-      },
-      buildDraftAgent: (attempt) =>
-        buildDraftAgentSnapshot({
-          attempt,
-          serverId,
-          tabId,
-          workspaceDirectory: draftWorkingDirectory,
-          autoSubmitConfig,
-          composerState,
-          selectModelMessage: t("workspaceSetup.errors.selectModel"),
-        }),
-      createRequest: async ({ attempt, text, images, attachments, cwd }) => {
-        if (pendingAutoSubmit?.agentCreation) {
-          const result = await pendingAutoSubmit.agentCreation.result;
-          return { agentId: result.id, result };
-        }
-        return submitDraftCreateRequest({
-          draftId,
-          attempt,
-          text,
-          images,
-          attachments,
-          cwd,
-          client,
-          workspaceDirectory: draftWorkingDirectory,
-          workspaceId: workspaceFields?.id ?? null,
-          autoSubmitConfig,
-          composerState,
-          hostDisconnectedMessage: t("workspace.terminal.hostDisconnected"),
-          selectModelMessage: t("workspaceSetup.errors.selectModel"),
-        });
-      },
-      onCreateSuccess: ({ result }) => {
-        clearDraftInput("sent");
-        clearWorkspaceAttachments({ scopeKey: draftAttachmentScopeKey });
-        useWorkspaceDraftSubmissionStore.getState().clearDraftSetup({ draftId });
-        onCreated(result);
-      },
-    });
+  const {
+    formErrorMessage,
+    isSubmitting,
+    submittedStreamItems,
+    pendingMessageSubmissions,
+    draftAgent,
+    handleCreateFromInput,
+    continueCreateFromAttempt,
+  } = useDraftAgentCreateFlow<Agent, AgentSnapshotPayload>({
+    draftId,
+    getPendingServerId: () => serverId,
+    initialAttempt: initialCreateAttempt,
+    allowEmptyText: allowsEmptyAutoSubmit,
+    validateBeforeSubmit: ({ text, attachments }) => {
+      const allowsEmptyDraftText = shouldAllowEmptyDraftText({
+        allowsEmptyAutoSubmit,
+        attachments,
+      });
+      return validateDraftSubmission({
+        text,
+        allowsEmptyAutoSubmit: allowsEmptyDraftText,
+        composerState,
+        autoSubmitConfig,
+        workspaceDirectory: draftWorkingDirectory,
+        isConnected,
+      });
+    },
+    onBeforeSubmit: async () => {
+      await composerState.persistFormPreferences();
+      if (isWeb) {
+        (document.activeElement as HTMLElement | null)?.blur?.();
+      }
+      Keyboard.dismiss();
+    },
+    buildDraftAgent: (attempt) =>
+      buildDraftAgentSnapshot({
+        attempt,
+        serverId,
+        tabId,
+        workspaceDirectory: draftWorkingDirectory,
+        autoSubmitConfig,
+        composerState,
+        selectModelMessage: t("workspaceSetup.errors.selectModel"),
+      }),
+    createRequest: async ({ attempt, text, images, attachments, cwd }) => {
+      if (pendingAutoSubmit?.agentCreation) {
+        const result = await pendingAutoSubmit.agentCreation.result;
+        return { agentId: result.id, result };
+      }
+      return submitDraftCreateRequest({
+        draftId,
+        attempt,
+        text,
+        images,
+        attachments,
+        cwd,
+        client,
+        workspaceDirectory: draftWorkingDirectory,
+        workspaceId: workspaceFields?.id ?? null,
+        autoSubmitConfig,
+        composerState,
+        hostDisconnectedMessage: t("workspace.terminal.hostDisconnected"),
+        selectModelMessage: t("workspaceSetup.errors.selectModel"),
+      });
+    },
+    onCreateSuccess: ({ result }) => {
+      clearDraftInput("sent");
+      clearWorkspaceAttachments({ scopeKey: draftAttachmentScopeKey });
+      useWorkspaceDraftSubmissionStore.getState().clearDraftSetup({ draftId });
+      onCreated(result);
+    },
+  });
+  const turnPresentation = useMemo(
+    () => resolveTurnPresentation(TURN_LIVENESS_IDLE, pendingMessageSubmissions.length > 0),
+    [pendingMessageSubmissions],
+  );
   useAgentControlCommandCenterActions({
     sourceId: `draft:${serverId}:${tabId}`,
     enabled: isPaneFocused && !isSubmitting,
@@ -568,49 +600,76 @@ export function WorkspaceDraftComposer({
     }),
     [composerState.agentControls, handleDropdownCloseFocus, isSubmitting],
   );
-  return (
-    <View style={animatedStaticStyles.inputAreaWrapper} onLayout={onInputAreaLayout}>
-      {formErrorMessage ? (
-        <View style={styles.formErrorRow}>
-          <View style={styles.formError}>
-            <Text style={styles.errorText}>{formErrorMessage}</Text>
-          </View>
+  const dockContent = (
+    <View style={styles.contentContainer}>
+      {isSubmitting && draftAgent ? (
+        <View style={styles.streamContainer}>
+          <AgentStreamView
+            agentId={tabId}
+            serverId={serverId}
+            context={draftAgent}
+            streamItems={submittedStreamItems}
+            pendingMessageSubmissions={pendingMessageSubmissions}
+            turnPresentation={turnPresentation}
+            pendingPermissions={EMPTY_PENDING_PERMISSIONS}
+            onOpenWorkspaceFile={onOpenWorkspaceFile}
+          />
         </View>
-      ) : null}
-      {importPillPress && !isComposerFullscreen ? (
-        <View style={styles.importPillRow}>
-          <View style={styles.importPillContent}>
-            <ComposerImportPill onPress={importPillPress} />
+      ) : (
+        <ScrollView style={styles.scrollView} contentContainerStyle={styles.configScrollContent}>
+          <View style={styles.configSection}>
+            {formErrorMessage ? (
+              <View style={styles.errorContainer}>
+                <Text style={styles.errorText}>{formErrorMessage}</Text>
+              </View>
+            ) : null}
           </View>
-        </View>
-      ) : null}
-      <Composer
-        agentId={tabId}
-        serverId={serverId}
-        workspaceId={workspaceId}
-        isPaneFocused={isPaneFocused}
-        onSubmitMessage={handleCreateFromInput}
-        isSubmitLoading={isSubmitting}
-        blurOnSubmit={true}
-        textSource={draftInput.textSource}
-        onChangeText={draftInput.editText}
-        textReplacement={draftInput.textReplacement}
-        attachments={draftInput.attachments}
-        attachmentScopeKeys={attachmentScopeKeys}
-        onOpenWorkspaceAttachment={handleOpenWorkspaceAttachment}
-        onChangeAttachments={draftInput.setAttachments}
-        cwd={composerState.workingDir}
-        clearDraft={draftInput.clear}
-        editingSession={editingSession}
-        autoFocus={shouldAutoFocusWorkspaceDraftComposer({ isPaneFocused, isSubmitting })}
-        autoFocusKey={String(draftInput.attachmentFocusRequestId)}
-        onFocusInput={handleFocusInputCallback}
-        commandDraft={composerState.commandDraft}
-        agentControls={composerAgentControls}
-        isCompactLayout={isCompactComposerLayout}
-      />
+        </ScrollView>
+      )}
     </View>
   );
+
+  return (
+    <FileDropZone style={styles.container}>
+      <ComposerDock fullscreen={isComposerFullscreen}>
+        {dockContent}
+        <View style={animatedStaticStyles.inputAreaWrapper} onLayout={onInputAreaLayout}>
+          {importPillPress && !isComposerFullscreen ? (
+            <View style={styles.importPillRow}>
+              <View style={styles.importPillContent}>
+                <ComposerImportPill onPress={importPillPress} />
+              </View>
+            </View>
+          ) : null}
+          <Composer
+            agentId={tabId}
+            serverId={serverId}
+            workspaceId={workspaceId}
+            isPaneFocused={isPaneFocused}
+            onSubmitMessage={handleCreateFromInput}
+            isSubmitLoading={isSubmitting}
+            blurOnSubmit={true}
+            textSource={draftInput.textSource}
+            onChangeText={draftInput.editText}
+            textReplacement={draftInput.textReplacement}
+            attachments={draftInput.attachments}
+            attachmentScopeKeys={attachmentScopeKeys}
+            onOpenWorkspaceAttachment={handleOpenWorkspaceAttachment}
+            onChangeAttachments={draftInput.setAttachments}
+            cwd={composerState.workingDir}
+            clearDraft={draftInput.clear}
+            editingSession={editingSession}
+            autoFocus={shouldAutoFocusWorkspaceDraftComposer({ isPaneFocused, isSubmitting })}
+            autoFocusKey={String(draftInput.attachmentFocusRequestId)}
+            onFocusInput={handleFocusInputCallback}
+            commandDraft={composerState.commandDraft}
+            agentControls={composerAgentControls}
+            isCompactLayout={isCompactComposerLayout}
+          />
+        </View>
+      </ComposerDock>
+    </FileDropZone>
+  );
 }
 
 const animatedStaticStyles = RNStyleSheet.create({
@@ -623,10 +682,27 @@ const animatedStaticStyles = RNStyleSheet.create({
 });
 
 const styles = StyleSheet.create((theme) => ({
-  formErrorRow: {
+  container: {
+    flex: 1,
     width: "100%",
+    backgroundColor: theme.colors.surface0,
+  },
+  contentContainer: {
+    flex: 1,
+  },
+  streamContainer: {
+    flex: 1,
+  },
+  scrollView: {
+    flex: 1,
+  },
+  configScrollContent: {
     paddingHorizontal: theme.spacing[4],
-    alignItems: "center",
+    paddingTop: theme.spacing[4],
+    paddingBottom: theme.spacing[6],
+  },
+  configSection: {
+    gap: theme.spacing[3],
   },
   importPillRow: {
     width: "100%",
@@ -646,10 +722,8 @@ const styles = StyleSheet.create((theme) => ({
     maxWidth: theme.contentMaxWidth,
     flexDirection: "row",
   },
-  formError: {
-    width: "100%",
-    maxWidth: theme.contentMaxWidth,
-    marginBottom: theme.spacing[2],
+  errorContainer: {
+    marginTop: theme.spacing[2],
     paddingHorizontal: theme.spacing[3],
     paddingVertical: theme.spacing[2],
     borderRadius: theme.borderRadius.md,

packages/app/src/composer/index.tsx

@@ -35,7 +35,6 @@ 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";
@@ -1118,7 +1117,7 @@ function ComposerCancelButton({
         accessibilityRole="button"
         style={cancelButtonStyle}
       >
-        <View style={styles.cancelButtonDisc}>{icon}</View>
+        {icon}
       </TooltipTrigger>
       <TooltipContent side="top" align="center" offset={8}>
         <View style={styles.tooltipRow}>
@@ -2596,21 +2595,14 @@ 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",

packages/app/src/composer/input/input.tsx

@@ -33,7 +33,6 @@ 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";
@@ -350,11 +349,7 @@ function VoiceButtonIcon({
   buttonIconSize: number;
 }) {
   if (isDictating) {
-    return (
-      <View style={styles.voiceButtonRecordingDisc}>
-        <Square size={buttonIconSize} color="white" fill="white" />
-      </View>
-    );
+    return <Square size={buttonIconSize} color="white" fill="white" />;
   }
   const colorMapping = hovered ? iconForegroundMapping : iconForegroundMutedMapping;
   if (isMutedRealtime) {
@@ -842,14 +837,12 @@ function SendButtonTooltip({
         testID={submitButtonTestID}
         style={sendButtonCombinedStyle}
       >
-        <View style={submitLabel ? styles.sendButtonDiscLabeled : styles.sendButtonDisc}>
-          <SendButtonContent
-            isSubmitLoading={isSubmitLoading}
-            submitIcon={submitIcon}
-            submitLabel={submitLabel}
-            buttonIconSize={buttonIconSize}
-          />
-        </View>
+        <SendButtonContent
+          isSubmitLoading={isSubmitLoading}
+          submitIcon={submitIcon}
+          submitLabel={submitLabel}
+          buttonIconSize={buttonIconSize}
+        />
       </TooltipTrigger>
       <TooltipContent side="top" align="center" offset={8}>
         <SendTooltipBody label={sendTooltipLabel} sendKeys={sendKeys} />
@@ -1932,6 +1925,7 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
         styles.voiceButton,
         Boolean(hovered) && !isDictating && styles.iconButtonHovered,
         !isDictationStartEnabled && styles.buttonDisabled,
+        isDictating && styles.voiceButtonRecording,
       ],
       [isDictating, isDictationStartEnabled],
     );
@@ -1980,8 +1974,12 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
       allowEmpty: allowEmptySubmit,
     });
     const sendButtonCombinedStyle = useMemo(
-      () => [styles.sendButton, isPresentedSendDisabled && styles.buttonDisabled],
-      [isPresentedSendDisabled],
+      () => [
+        styles.sendButton,
+        submitLabel ? styles.sendButtonLabeled : undefined,
+        isPresentedSendDisabled && styles.buttonDisabled,
+      ],
+      [isPresentedSendDisabled, submitLabel],
     );
     const overlayContainerStyle = useMemo(
       () => [styles.overlayContainer, { opacity: surfacePresentation.overlay.opacity }],
@@ -2418,38 +2416,23 @@ const styles = StyleSheet.create((theme: Theme) => ({
     alignItems: "center",
     justifyContent: "center",
   },
-  voiceButtonRecordingDisc: {
-    width: TOOLBAR_DISC_SIZE,
-    height: TOOLBAR_DISC_SIZE,
-    borderRadius: theme.borderRadius.full,
+  voiceButtonRecording: {
     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,
+    width: TOOLBAR_CONTROL_HEIGHT,
     height: TOOLBAR_CONTROL_HEIGHT,
+    borderRadius: theme.borderRadius.full,
+    backgroundColor: theme.colors.accent,
     alignItems: "center",
     justifyContent: "center",
     marginLeft: theme.spacing[1],
   },
-  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,
+  sendButtonLabeled: {
+    width: "auto",
+    minWidth: TOOLBAR_CONTROL_HEIGHT,
     paddingHorizontal: theme.spacing[3],
     borderRadius: theme.borderRadius.full,
-    backgroundColor: theme.colors.accent,
-    alignItems: "center",
-    justifyContent: "center",
   },
   sendButtonLabel: {
     fontSize: theme.fontSize.base,

packages/app/src/data/push-router.test.ts

@@ -1,4 +1,4 @@
-import type { OwnedSubscription, SubscriptionObserver } from "@getpaseo/client";
+import type { DiffState, OwnedSubscription, SubscriptionObserver } from "@getpaseo/client";
 import { QueryClient, QueryObserver, skipToken } from "@tanstack/react-query";
 import { describe, expect, it } from "vitest";
 import type { MutableDaemonConfig, SessionOutboundMessage } from "@getpaseo/protocol/messages";
@@ -144,10 +144,21 @@ function createFakeClient(config: { rejectCheckoutDiffSubscribe?: boolean } = {}
           ["status", "providers_snapshot_update"],
           () => {},
         ),
-      observeCheckoutDiff(cwd, compare) {
+      observeDiff(input) {
+        const cwd = input.cwd;
+        let mode: "uncommitted" | "base" | "all" = "uncommitted";
+        if (input.head.kind === "rev") mode = "base";
+        else if (input.mergeBase) mode = "all";
+        const compare = {
+          mode,
+          ...(input.base.kind === "rev" && input.base.rev !== "HEAD"
+            ? { baseRef: input.base.rev }
+            : {}),
+          ignoreWhitespace: input.ignoreWhitespace,
+        };
         const subscriptionId = `server-diff-${subscribeCheckoutDiffCalls.length + 1}`;
         subscribeCheckoutDiffCalls.push({ cwd, compare, subscriptionId });
-        const handle = observe(
+        const handle = observe<SubscribeCheckoutDiffResponseMessage["payload"]>(
           { subscriptionId, cwd, files: [], error: null, requestId: "subscribe-checkout-diff" },
           ["checkout_diff_update", "subscribe_checkout_diff_response"],
           () => unsubscribeCheckoutDiffCalls.push(subscriptionId),
@@ -155,9 +166,43 @@ function createFakeClient(config: { rejectCheckoutDiffSubscribe?: boolean } = {}
             "subscriptionId" in message.payload &&
             message.payload.subscriptionId === subscriptionId,
         );
-        if (!config.rejectCheckoutDiffSubscribe) return handle;
-        return {
+        const modern: OwnedSubscription<DiffState> = {
           ...handle,
+          ready: Promise.resolve({
+            phase: "ready",
+            revision: 1,
+            resolved: { baseSha: "", headSha: "", mergeBaseSha: "" },
+            files: [],
+            diffTooLarge: false,
+            subscriptionId,
+          }),
+          subscribe: (observer) =>
+            handle.subscribe({
+              snapshot: (payload) =>
+                observer.snapshot({
+                  phase: "ready",
+                  revision: 1,
+                  resolved: { baseSha: "", headSha: "", mergeBaseSha: "" },
+                  files: payload.files,
+                  diffTooLarge: payload.diffTooLarge === true,
+                  subscriptionId,
+                }),
+              update: (message) => {
+                if (message.type === "checkout_diff_update")
+                  observer.snapshot({
+                    phase: "ready",
+                    revision: 2,
+                    resolved: { baseSha: "", headSha: "", mergeBaseSha: "" },
+                    files: message.payload.files,
+                    diffTooLarge: message.payload.diffTooLarge === true,
+                    subscriptionId,
+                  });
+              },
+            }),
+        };
+        if (!config.rejectCheckoutDiffSubscribe) return modern;
+        return {
+          ...modern,
           subscribe: (observer) => {
             queueMicrotask(() => observer.error?.(new Error("subscribe failed")));
             return () => {};
@@ -328,7 +373,7 @@ describe("server data push router", () => {
       const first = publish(files, "first");
       const same = publish(structuredClone(files), "reopen");
       expect(same.files).toBe(first.files);
-      expect(same.requestId).toBe("reopen");
+      expect(same.requestId).toBe("diff:1:ready");
       const changed = structuredClone(files);
       changed[0]!.hunks[0]!.lines[0]!.tokens![0]!.style = "variable";
       const next = publish(changed, "edit");
@@ -430,7 +475,7 @@ describe("server data push router", () => {
       files: [],
       error: null,
       diffTooLarge: true,
-      requestId: "diff-1",
+      requestId: "diff:1:ready",
     });
 
     fake.emit({
@@ -449,7 +494,7 @@ describe("server data push router", () => {
       files: [],
       error: null,
       diffTooLarge: true,
-      requestId: `subscription:${serverSubscriptionId}`,
+      requestId: "diff:2:ready",
     });
 
     unsubscribeObserver();

packages/app/src/data/push-router.ts

@@ -1,3 +1,5 @@
+import { checkoutDiffSnapshot, type CheckoutDiffSnapshot } from "@/git/diff-snapshot";
+import type { DiffState } from "@getpaseo/client";
 import type { OwnedSubscription } from "@getpaseo/client";
 import type { ProviderSnapshotEntry } from "@getpaseo/protocol/agent-types";
 import type { Query, QueryCacheNotifyEvent, QueryClient, QueryKey } from "@tanstack/react-query";
@@ -23,14 +25,9 @@ type ProvidersSnapshotUpdateMessage = Extract<
   SessionOutboundMessage,
   { type: "providers_snapshot_update" }
 >;
-type SubscribeCheckoutDiffResponseMessage = Extract<
-  SessionOutboundMessage,
-  { type: "subscribe_checkout_diff_response" }
->;
 type StatusMessage = Extract<SessionOutboundMessage, { type: "status" }>;
 type TerminalsChangedMessage = Extract<SessionOutboundMessage, { type: "terminals_changed" }>;
-type CheckoutDiffResponsePayload = SubscribeCheckoutDiffResponseMessage["payload"];
-type CheckoutDiffCachePayload = Omit<CheckoutDiffResponsePayload, "subscriptionId">;
+type CheckoutDiffCachePayload = CheckoutDiffSnapshot;
 type ListTerminalsPayload = ListTerminalsResponse["payload"];
 
 interface CheckoutDiffCompare {
@@ -49,7 +46,7 @@ interface CheckoutDiffRoute {
 }
 
 interface CheckoutDiffRegistration extends CheckoutDiffRoute {
-  subscription: OwnedSubscription<CheckoutDiffResponsePayload>;
+  subscription: OwnedSubscription<DiffState>;
 }
 
 interface WorkspaceTerminalsRoute {
@@ -75,7 +72,7 @@ export type ProvidersSnapshotUpdate = ProvidersSnapshotUpdateMessage;
 interface ServerDataPushClient {
   getProvidersSnapshot: import("@getpaseo/client/internal/daemon-client").DaemonClient["getProvidersSnapshot"];
   observeEvents: import("@getpaseo/client/internal/daemon-client").DaemonClient["observeEvents"];
-  observeCheckoutDiff: import("@getpaseo/client/internal/daemon-client").DaemonClient["observeCheckoutDiff"];
+  observeDiff: import("@getpaseo/client/internal/daemon-client").DaemonClient["observeDiff"];
   observeTerminals: import("@getpaseo/client/internal/daemon-client").DaemonClient["observeTerminals"];
 }
 
@@ -339,34 +336,34 @@ function reconcileCheckoutDiffSubscriptions(input: {
   }
   for (const [key, desired] of input.desired) {
     if (input.active.has(key)) continue;
-    const subscription = input.client.observeCheckoutDiff(desired.cwd, desired.compare);
+    const { mode, baseRef, ignoreWhitespace } = desired.compare;
+    const revision = mode === "uncommitted" ? "HEAD" : baseRef;
+    if (!revision) continue;
+    const subscription = input.client.observeDiff({
+      cwd: desired.cwd,
+      base: { kind: "rev", rev: revision },
+      head: mode === "base" ? { kind: "rev", rev: "HEAD" } : { kind: "worktree" },
+      mergeBase: mode !== "uncommitted",
+      ignoreWhitespace,
+    });
     const registration = { ...desired, subscription };
     input.active.set(key, registration);
-    const apply = (
-      payload: Omit<CheckoutDiffResponsePayload, "requestId"> & { requestId?: string },
-    ) => {
-      if (input.active.get(key) !== registration) return;
-      const { subscriptionId, ...snapshot } = payload;
-      setCheckoutDiffPayload({
-        activeCheckoutDiffSubscriptions: input.active,
-        queryClient: input.queryClient,
-        serverId: input.serverId,
-        subscriptionId: key,
-        payload: {
-          ...snapshot,
-          files: orderCheckoutDiffFiles(payload.files),
-          requestId: payload.requestId ?? `subscription:${subscriptionId}`,
-        },
-      });
-    };
     subscription.subscribe({
-      snapshot: apply,
-      update: (message) => {
-        if (message.type === "checkout_diff_update") apply(message.payload);
+      snapshot: (state) => {
+        if (input.active.get(key) !== registration) return;
+        const snapshot = checkoutDiffSnapshot(desired.cwd, state);
+        setCheckoutDiffPayload({
+          activeCheckoutDiffSubscriptions: input.active,
+          queryClient: input.queryClient,
+          serverId: input.serverId,
+          subscriptionId: key,
+          payload: { ...snapshot, files: orderCheckoutDiffFiles(snapshot.files) },
+        });
       },
+      update: () => {},
       error: (error) => {
         if (input.active.get(key) === registration) input.active.delete(key);
-        console.error("[server-data] observeCheckoutDiff failed", {
+        console.error("[server-data] observeDiff failed", {
           serverId: input.serverId,
           cwd: desired.cwd,
           error,

packages/app/src/git/changed-files-tree.tsx

@@ -13,10 +13,10 @@ import {
   type DiffTreeRow,
 } from "@/git/diff-tree";
 import { FileHeader } from "@/git/file-header";
-import type { ParsedDiffFile } from "@/git/use-diff-query";
+import type { DiffFileHeader } from "@/git/diff-snapshot";
 
 export interface ChangedFilesTreeProps {
-  files: ParsedDiffFile[];
+  files: DiffFileHeader[];
   mode: WorkingDiffMode;
   onSelectFile: (path: string) => void;
   collapsedFolderPaths: string[];

packages/app/src/git/diff-order.ts

@@ -13,6 +13,6 @@ export function orderCheckoutDiffFiles(files: ParsedDiffFile[]): ParsedDiffFile[
   // chains, so it is skipped; the collapsed set is empty because the flat list
   // always carries every file, whatever the rail has collapsed.
   return flattenDiffTree(buildDiffTree(files), new Set()).flatMap((row) =>
-    row.kind === "file" ? [row.file] : [],
+    row.kind === "file" ? [files[row.fileIndex]] : [],
   );
 }

packages/app/src/git/diff-pane.tsx

@@ -1,3 +1,4 @@
+import type { DiffFileHeader } from "@/git/diff-snapshot";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { floatingActionsClearance } from "@/components/ui/floating-action-button";
 import { useState, useCallback, useMemo, type ReactElement, type ReactNode } from "react";
@@ -1095,6 +1096,7 @@ interface DiffBodyContentProps {
   emptyMessage: string;
   emptyAction: ChangesEmptyAction | null;
   children: ReactElement;
+  loadingLabel: string;
   checkingRepositoryLabel: string;
   notRepositoryLabel: string;
 }
@@ -1111,11 +1113,16 @@ function DiffBodyContent({
   emptyAction,
   children,
   checkingRepositoryLabel,
+  loadingLabel,
   notRepositoryLabel,
 }: DiffBodyContentProps) {
   if (isStatusLoading) {
     return (
-      <View style={styles.loadingContainer}>
+      <View
+        style={styles.loadingContainer}
+        accessibilityRole="progressbar"
+        accessibilityLabel={loadingLabel}
+      >
         <ThemedLoadingSpinner size="large" uniProps={foregroundMutedIconColorMapping} />
         <Text style={styles.loadingText}>{checkingRepositoryLabel}</Text>
       </View>
@@ -1137,12 +1144,16 @@ function DiffBodyContent({
   }
   if (isDiffLoading) {
     return (
-      <View style={styles.loadingContainer}>
+      <View
+        style={styles.loadingContainer}
+        accessibilityRole="progressbar"
+        accessibilityLabel={loadingLabel}
+      >
         <ThemedLoadingSpinner size="large" uniProps={foregroundMutedIconColorMapping} />
       </View>
     );
   }
-  if (diffTooLarge) {
+  if (diffTooLarge && !hasChanges) {
     return <DiffTooLargeState />;
   }
   if (diffErrorMessage) {
@@ -1321,7 +1332,7 @@ function ChangesTreeRail({
 }: {
   shown: boolean;
   children: ReactElement;
-  files: ParsedDiffFile[];
+  files: DiffFileHeader[];
   mode: WorkingDiffMode;
   onSelectFile: (path: string) => void;
   treeWidth?: number;
@@ -1361,7 +1372,7 @@ function ChangesBody({
   children: ReactElement;
   desktopTreeVisible: boolean;
   isMobile: boolean;
-  files: ParsedDiffFile[];
+  files: DiffFileHeader[];
   mode: WorkingDiffMode;
   onSelectFile: (path: string) => void;
   treeWidth?: number;
@@ -1586,6 +1597,7 @@ export function ChangesSurface({
     selectBase: handleSelectBase,
     selectAll: handleSelectAll,
     files,
+    treeFiles,
     diffPayloadError,
     diffTooLarge,
     isDiffLoading,
@@ -1835,6 +1847,7 @@ export function ChangesSurface({
         hasChanges={hasChanges}
         emptyMessage={emptyMessage}
         emptyAction={emptyAction}
+        loadingLabel={t("common.loading")}
         checkingRepositoryLabel={t("workspace.git.diff.checkingRepository")}
         notRepositoryLabel={t("workspace.git.diff.notRepository")}
       >
@@ -1865,7 +1878,7 @@ export function ChangesSurface({
       presentation={presentation}
       desktopTreeVisible={desktopTreeVisible}
       isMobile={isMobile}
-      files={files}
+      files={treeFiles}
       mode={workingMode}
       onSelectFile={handleSelectTreeFile}
       treeWidth={instanceState.treeWidth}

packages/app/src/git/diff-sharing.ts

@@ -1,7 +1,8 @@
 import { replaceEqualDeep } from "@tanstack/react-query";
-import type { ParsedDiffFile, SubscribeCheckoutDiffResponse } from "@getpaseo/protocol/messages";
+import type { CheckoutDiffSnapshot } from "./diff-snapshot";
+import type { ParsedDiffFile } from "@getpaseo/protocol/messages";
 
-type DiffPayload = Omit<SubscribeCheckoutDiffResponse["payload"], "subscriptionId">;
+type DiffPayload = CheckoutDiffSnapshot;
 
 /** File identity owns text-model reuse. Never reconstruct the hunk/token graph. */
 export function retainDiffFiles(
@@ -30,6 +31,7 @@ export function shareCheckoutDiff(previous: unknown, incoming: unknown): DiffPay
     error === old.error &&
     old.cwd === next.cwd &&
     old.requestId === next.requestId &&
+    old.entries === next.entries &&
     old.diffTooLarge === next.diffTooLarge
     ? old
     : { ...next, files, error };

packages/app/src/git/diff-snapshot.ts

@@ -0,0 +1,74 @@
+import type { DiffState, DiffEntry } from "@getpaseo/client";
+import type {
+  DiffError,
+  ParsedDiffFile,
+  SubscribeCheckoutDiffRequest,
+} from "@getpaseo/protocol/messages";
+export type DiffFileHeader = Omit<ParsedDiffFile, "hunks">;
+export interface CheckoutDiffSnapshot {
+  requestId: string;
+  cwd: string;
+  files: ParsedDiffFile[];
+  entries?: DiffEntry[];
+  error: DiffError | null;
+  diffTooLarge?: boolean;
+}
+export function checkoutDiffSnapshot(cwd: string, state: DiffState): CheckoutDiffSnapshot {
+  const common = { cwd, requestId: `diff:${state.revision}:${state.phase}` };
+  if (state.phase === "loading")
+    return { ...common, files: [], entries: state.entries, error: null };
+  if (state.phase === "error") return { ...common, files: [], error: state.error };
+  return { ...common, files: state.files, error: null, diffTooLarge: state.diffTooLarge };
+}
+export function diffEntryHeaders(entries: DiffEntry[]): DiffFileHeader[] {
+  return entries.map((entry) => ({
+    path: entry.path,
+    ...(entry.oldPath === null ? {} : { oldPath: entry.oldPath }),
+    isNew: entry.change === "added",
+    isDeleted: entry.change === "deleted",
+    additions: entry.additions,
+    deletions: entry.deletions,
+    status: entry.content === "binary" ? "binary" : "ok",
+  }));
+}
+export interface CheckoutDiffResult {
+  files: ParsedDiffFile[];
+  entries: DiffEntry[] | null;
+  payloadError: CheckoutDiffSnapshot["error"];
+  diffTooLarge: boolean;
+  isLoading: boolean;
+  isFetching: boolean;
+  isError: boolean;
+  error: null;
+}
+
+/**
+ * The result derives from the payload alone. Until a payload arrives there is no
+ * diff to describe, so the boundary reports loading rather than an empty diff —
+ * whether the query is idle (an inactive retained panel), in flight, or the host
+ * is disconnected. Reporting `files: []` as settled made callers render "+0 -0"
+ * and "No changes" for a diff nobody has fetched yet.
+ */
+export function deriveCheckoutDiffResult(payload: CheckoutDiffSnapshot | null): CheckoutDiffResult {
+  const payloadError = payload?.error ?? null;
+  return {
+    files: payload?.files ?? [],
+    entries: payload?.entries ?? null,
+    payloadError,
+    diffTooLarge: payload?.diffTooLarge === true,
+    isLoading: payload === null || payload.entries !== undefined,
+    isFetching: false,
+    isError: Boolean(payloadError),
+    error: null,
+  };
+}
+
+export function checkoutDiffComparisonError(
+  compare: Pick<SubscribeCheckoutDiffRequest["compare"], "mode" | "baseRef">,
+): DiffError | null {
+  if (compare.mode === "uncommitted" || compare.baseRef?.trim()) return null;
+  return {
+    code: "INVALID_COMPARE",
+    message: "Comparison base is unavailable. Select Uncommitted to view pending changes.",
+  };
+}

packages/app/src/git/diff-tree.ts

@@ -1,6 +1,6 @@
-import type { ParsedDiffFile } from "@/git/use-diff-query";
+import type { DiffFileHeader } from "@/git/diff-snapshot";
 
-// Builds a directory hierarchy from the `ParsedDiffFile[]` the Changes view
+// Builds a directory hierarchy from the `DiffFileHeader[]` the Changes view
 // renders. The tree renders on every form factor, consistent with the Files
 // explorer.
 //
@@ -17,7 +17,7 @@ import type { ParsedDiffFile } from "@/git/use-diff-query";
 
 export interface DiffTreeFileNode {
   kind: "file";
-  file: ParsedDiffFile;
+  file: DiffFileHeader;
   fileIndex: number;
   /** basename, e.g. "diff-pane.tsx" */
   name: string;
@@ -47,7 +47,7 @@ export interface DiffTreeFolderRow {
 
 export interface DiffTreeFileRow {
   kind: "file";
-  file: ParsedDiffFile;
+  file: DiffFileHeader;
   fileIndex: number;
   depth: number;
 }
@@ -73,7 +73,7 @@ function sortTree(node: DiffTreeDirNode): void {
 }
 
 /** Build the (uncompressed) directory tree. Returns the virtual root (dirPath ""). */
-export function buildDiffTree(files: ParsedDiffFile[]): DiffTreeDirNode {
+export function buildDiffTree(files: DiffFileHeader[]): DiffTreeDirNode {
   const root: DiffTreeDirNode = { kind: "dir", dirPath: "", name: "", children: [] };
   const dirByPath = new Map<string, DiffTreeDirNode>([["", root]]);
 

packages/app/src/git/file-header.tsx

@@ -28,11 +28,11 @@ import {
   fileNameForPath,
   formatDiffCount,
 } from "@/git/file-header-presentation";
-import type { ParsedDiffFile } from "@/git/use-diff-query";
+import type { DiffFileHeader } from "@/git/diff-snapshot";
 import { inlineUnistylesStyle } from "@/styles/unistyles-inline-style";
 
 export interface FileHeaderProps {
-  file: ParsedDiffFile;
+  file: DiffFileHeader;
   workspaceFileDragScope?: { serverId: string; workspaceId: string };
   bodyVisible: boolean;
   showsBodyState?: boolean;
@@ -73,7 +73,7 @@ function expandedAriaValue(showsBodyState: boolean, bodyVisible: boolean): boole
   return showsBodyState ? bodyVisible : undefined;
 }
 
-function fileHeaderAccessibilityLabel(canvasRendered: boolean, file: ParsedDiffFile) {
+function fileHeaderAccessibilityLabel(canvasRendered: boolean, file: DiffFileHeader) {
   if (!canvasRendered) return undefined;
   return `${file.path}, +${formatDiffCount(file.additions)}, -${formatDiffCount(file.deletions)}`;
 }
@@ -130,7 +130,7 @@ function fileHeaderNameStyle(showsBodyState: boolean, isHovered: boolean) {
   ];
 }
 
-function fileChange(file: ParsedDiffFile): "added" | "deleted" | "modified" {
+function fileChange(file: DiffFileHeader): "added" | "deleted" | "modified" {
   return diffFileChangeKind(file);
 }
 

packages/app/src/git/use-diff-query.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import type { ParsedDiffFile } from "@getpaseo/protocol/messages";
-import { deriveCheckoutDiffResult } from "./use-diff-query";
+import { deriveCheckoutDiffResult } from "./diff-snapshot";
 
 function createParsedDiffFile(path: string): ParsedDiffFile {
   return {
@@ -59,6 +59,7 @@ describe("deriveCheckoutDiffResult", () => {
 
     expect(result).toEqual({
       files: [],
+      entries: null,
       payloadError: error,
       diffTooLarge: true,
       isLoading: false,
@@ -68,3 +69,27 @@ describe("deriveCheckoutDiffResult", () => {
     });
   });
 });
+
+it("shows the announced tree while file bodies are still loading", () => {
+  const entries = [
+    {
+      path: "src/app.ts",
+      oldPath: null,
+      change: "modified",
+      content: "text",
+      additions: 3,
+      deletions: 1,
+    },
+  ] as const;
+  const result = deriveCheckoutDiffResult({ ...createPayload([]), entries: [...entries] });
+  expect(result.isLoading).toBe(true);
+  expect(result.entries).toEqual(entries);
+  expect(result.files).toEqual([]);
+});
+
+it("settles a comparison without a base and leaves Uncommitted available", async () => {
+  const { checkoutDiffComparisonError } = await import("./diff-snapshot");
+  expect(checkoutDiffComparisonError({ mode: "all" })).toMatchObject({ code: "INVALID_COMPARE" });
+  expect(checkoutDiffComparisonError({ mode: "base" })).toMatchObject({ code: "INVALID_COMPARE" });
+  expect(checkoutDiffComparisonError({ mode: "uncommitted" })).toBeNull();
+});

packages/app/src/git/use-diff-query.ts

@@ -5,7 +5,13 @@ import { useRetainedPanelActive } from "@/components/retained-panel";
 import { useReplicaQuery } from "@/data/query";
 import { checkoutDiffPushRoute } from "@/data/push-router";
 import { useHostRuntimeIsConnected } from "@/runtime/host-runtime";
-import type { ParsedDiffFile, SubscribeCheckoutDiffResponse } from "@getpaseo/protocol/messages";
+import {
+  checkoutDiffComparisonError,
+  deriveCheckoutDiffResult,
+  type CheckoutDiffSnapshot,
+} from "./diff-snapshot";
+export { deriveCheckoutDiffResult } from "./diff-snapshot";
+import type { ParsedDiffFile } from "@getpaseo/protocol/messages";
 import { checkoutDiffQueryKey } from "@/git/query-keys";
 
 interface UseCheckoutDiffQueryOptions {
@@ -18,7 +24,7 @@ interface UseCheckoutDiffQueryOptions {
   queryScope?: string;
 }
 
-type CheckoutDiffQueryPayload = Omit<SubscribeCheckoutDiffResponse["payload"], "subscriptionId">;
+type CheckoutDiffQueryPayload = CheckoutDiffSnapshot;
 
 // Re-export the canonical protocol type so all consumers share one definition.
 export type { ParsedDiffFile };
@@ -77,7 +83,11 @@ export function useCheckoutDiffQuery({
     return normalizedScope ? [...comparisonKey, "scope", normalizedScope] : comparisonKey;
   }, [serverId, cwd, compareMode, compareBaseRef, compareIgnoreWhitespace, queryScope]);
   const subscriptionId = useMemo(() => `checkoutDiff:${JSON.stringify(queryKey)}`, [queryKey]);
-  const routeEnabled = Boolean(queryEnabled && isConnected && cwd && !requiresUpdate);
+  const comparisonError =
+    queryEnabled && isConnected ? checkoutDiffComparisonError(normalizedCompare) : null;
+  const routeEnabled = Boolean(
+    queryEnabled && isConnected && cwd && !requiresUpdate && !comparisonError,
+  );
 
   const query = useReplicaQuery<CheckoutDiffQueryPayload>({
     queryKey,
@@ -97,46 +107,13 @@ export function useCheckoutDiffQuery({
     }),
   });
 
-  return deriveCheckoutDiffResult(
+  const boundaryError =
     requiresUpdate && isConnected
-      ? {
-          requestId: "unsupported",
-          cwd,
-          files: [],
-          error: { code: "UNKNOWN", message: "Update the host to view All changes" },
-        }
+      ? { code: "UNKNOWN" as const, message: "Update the host to view All changes" }
+      : comparisonError;
+  return deriveCheckoutDiffResult(
+    boundaryError
+      ? { requestId: "unavailable", cwd, files: [], error: boundaryError }
       : (query.data ?? null),
   );
 }
-
-export interface CheckoutDiffResult {
-  files: ParsedDiffFile[];
-  payloadError: CheckoutDiffQueryPayload["error"];
-  diffTooLarge: boolean;
-  isLoading: boolean;
-  isFetching: boolean;
-  isError: boolean;
-  error: null;
-}
-
-/**
- * The result derives from the payload alone. Until a payload arrives there is no
- * diff to describe, so the boundary reports loading rather than an empty diff —
- * whether the query is idle (an inactive retained panel), in flight, or the host
- * is disconnected. Reporting `files: []` as settled made callers render "+0 -0"
- * and "No changes" for a diff nobody has fetched yet.
- */
-export function deriveCheckoutDiffResult(
-  payload: CheckoutDiffQueryPayload | null,
-): CheckoutDiffResult {
-  const payloadError = payload?.error ?? null;
-  return {
-    files: payload?.files ?? [],
-    payloadError,
-    diffTooLarge: payload?.diffTooLarge === true,
-    isLoading: payload === null,
-    isFetching: false,
-    isError: Boolean(payloadError),
-    error: null,
-  };
-}

packages/app/src/git/use-working-diff.ts

@@ -9,6 +9,8 @@ import {
   useReviewAttachmentSnapshot,
   useReviewFeedback,
 } from "@/review";
+import { useSessionStore } from "@/stores/session-store";
+import { diffEntryHeaders } from "./diff-snapshot";
 import { useCheckoutDiffQuery } from "@/git/use-diff-query";
 import { useCheckoutStatusQuery } from "@/git/use-status-query";
 import { useWorkingDiffComparison } from "@/git/working-diff-comparison";
@@ -44,7 +46,11 @@ export function useWorkingDiff({
   const statusErrorMessage =
     status?.error?.message ??
     (isStatusError && statusError instanceof Error ? statusError.message : null);
-  const baseRef = gitStatus?.baseRef ?? undefined;
+  const modernDiff = useSessionStore(
+    (state) => state.sessions[serverId]?.serverInfo?.features?.diffSubscription === true,
+  );
+  // COMPAT(diffSubscription): added in v0.15.0, remove after 2027-05-06.
+  const baseRef = (modernDiff ? gitStatus?.comparisonBaseRef : gitStatus?.baseRef) ?? undefined;
   const currentBranchName =
     gitStatus?.currentBranch && gitStatus.currentBranch !== "HEAD" ? gitStatus.currentBranch : null;
 
@@ -59,6 +65,7 @@ export function useWorkingDiff({
 
   const {
     files,
+    entries,
     payloadError: diffPayloadError,
     diffTooLarge,
     isLoading: isDiffLoading,
@@ -71,6 +78,7 @@ export function useWorkingDiff({
     enabled: enabled && isGit,
     queryScope,
   });
+  const treeFiles = useMemo(() => (entries ? diffEntryHeaders(entries) : files), [entries, files]);
   const reviewDraftKey = useMemo(
     () =>
       buildReviewDraftKey({
@@ -112,6 +120,7 @@ export function useWorkingDiff({
     selectBase,
     selectAll,
     files,
+    treeFiles,
     diffPayloadError,
     diffTooLarge,
     isDiffLoading,

packages/app/src/i18n/resources/ar.ts

@@ -1236,7 +1236,6 @@ export const ar: TranslationResources = {
       hosts: "المضيفون",
       settings: "إعدادات",
       closeSidebar: "إغلاق الشريط الجانبي",
-      moreActions: "المزيد من الإجراءات",
     },
     footer: {
       usage: "الاستخدام",

packages/app/src/i18n/resources/en.ts

@@ -1244,7 +1244,6 @@ export const en = {
       hosts: "Hosts",
       settings: "Settings",
       closeSidebar: "Close sidebar",
-      moreActions: "More actions",
     },
     footer: {
       usage: "Usage",

packages/app/src/i18n/resources/es.ts

@@ -1272,7 +1272,6 @@ export const es: TranslationResources = {
       hosts: "Hosts",
       settings: "Ajustes",
       closeSidebar: "Cerrar barra lateral",
-      moreActions: "Más acciones",
     },
     footer: {
       usage: "Uso",

packages/app/src/i18n/resources/fr.ts

@@ -1266,7 +1266,6 @@ export const fr: TranslationResources = {
       hosts: "Hôtes",
       settings: "Paramètres",
       closeSidebar: "Fermer la barre latérale",
-      moreActions: "Plus d’actions",
     },
     footer: {
       usage: "Utilisation",

packages/app/src/i18n/resources/ja.ts

@@ -1250,7 +1250,6 @@ export const ja: TranslationResources = {
       hosts: "ホスト",
       settings: "設定",
       closeSidebar: "サイドバーを閉じる",
-      moreActions: "その他のアクション",
     },
     footer: {
       usage: "使用状況",

packages/app/src/i18n/resources/ko.ts

@@ -1243,7 +1243,6 @@ export const ko: TranslationResources = {
       hosts: "호스트",
       settings: "설정",
       closeSidebar: "사이드바 닫기",
-      moreActions: "추가 작업",
     },
     footer: {
       usage: "사용량",

packages/app/src/i18n/resources/pt-BR.ts

@@ -1262,7 +1262,6 @@ export const ptBR: TranslationResources = {
       hosts: "Hosts",
       settings: "Configurações",
       closeSidebar: "Fechar barra lateral",
-      moreActions: "Mais ações",
     },
     footer: {
       usage: "Uso",

packages/app/src/i18n/resources/ru.ts

@@ -1254,7 +1254,6 @@ export const ru: TranslationResources = {
       hosts: "Хосты",
       settings: "Настройки",
       closeSidebar: "Закрыть боковую панель",
-      moreActions: "Дополнительные действия",
     },
     footer: {
       usage: "Использование",

packages/app/src/i18n/resources/zh-CN.ts

@@ -1228,7 +1228,6 @@ export const zhCN: TranslationResources = {
       hosts: "Hosts",
       settings: "设置",
       closeSidebar: "关闭侧边栏",
-      moreActions: "更多操作",
     },
     footer: {
       usage: "使用情况",

packages/app/src/panels/agent-panel.tsx

@@ -78,8 +78,7 @@ import {
   deriveRouteBottomAnchorIntent,
   deriveRouteBottomAnchorRequest,
 } from "@/screens/agent/agent-ready-screen-bottom-anchor";
-import { WorkspaceDraftComposer } from "@/composer/draft/workspace-tab";
-import { type DraftConversation, useDraftTimeline } from "@/composer/draft/timeline";
+import { WorkspaceDraftAgentTab } from "@/composer/draft/workspace-tab";
 import { AgentTracks } from "@/panels/agent-tracks";
 import { ParentAgentCallout, useParentAgentId } from "@/subagents/parent";
 import { useCreateFlowStore } from "@/stores/create-flow-store";
@@ -91,13 +90,14 @@ import {
   useSessionStore,
 } from "@/stores/session-store";
 import { useWorkspaceLayoutStore } from "@/stores/workspace-layout-store";
-import { buildWorkspaceTabPersistenceKey, type WorkspaceTabTarget } from "@/workspace-tabs/model";
+import { buildWorkspaceTabPersistenceKey } from "@/workspace-tabs/model";
 import { openWorkspaceChanges } from "@/workspace-tabs/open-supporting-view";
 import { useSettings } from "@/hooks/use-settings";
 import type { Theme } from "@/styles/theme";
 import type { PendingPermission } from "@/types/shared";
-import type { StreamItem } from "@/types/stream";
+import type { StreamItem, TodoEntry } from "@/types/stream";
 import type { ViewedTimelineStatus, ViewedTimelineUiBridge } from "@/timeline/viewed-timeline-sync";
+import { useArchiveFinishedSubagents, useSubagentsForParent } from "@/subagents";
 import { getInitDeferred, getInitKey } from "@/utils/agent-initialization";
 import { derivePendingPermissionKey, normalizeAgentSnapshot } from "@/utils/agent-snapshots";
 import { applyLegacyDaemonWorkspaceOwnership } from "@/workspace/legacy-daemon-workspaces";
@@ -225,29 +225,6 @@ function AgentLoadErrorView({ message, onRetry }: { message: string; onRetry: ()
   );
 }
 
-/** A draft has no agent to wait for; an agent shows its loading and error states until ready. */
-function renderConversationNonReadyView(args: {
-  draft: DraftConversation | null;
-  agentId: string | undefined;
-  cwd: string | null;
-  viewState: AgentScreenViewState;
-  effectiveAgent: AgentScreenAgent | null;
-  t: TFunction;
-  onRetryLoad: () => void;
-}): React.ReactElement | null {
-  if (args.draft) {
-    return null;
-  }
-  const nonReadyView = renderChatAgentNonReadyView(args);
-  if (nonReadyView) {
-    return nonReadyView;
-  }
-  invariant(args.agentId, "agent id is defined when agent content is ready");
-  invariant(args.effectiveAgent, "effectiveAgent is defined when the non-ready view is absent");
-  invariant(args.cwd, "agent cwd is defined when agent content is ready");
-  return null;
-}
-
 function renderChatAgentNonReadyView(args: {
   viewState: AgentScreenViewState;
   effectiveAgent: AgentScreenAgent | null;
@@ -326,31 +303,17 @@ function storeFetchedAgentDetail(input: {
   return hydrated;
 }
 
-type ConversationTarget = Extract<WorkspaceTabTarget, { kind: "agent" } | { kind: "draft" }>;
-
-/** The agent a conversation shows; a draft has none until its first prompt creates one. */
-function resolveConversationAgentId(target: ConversationTarget): string | undefined {
-  return target.kind === "agent" ? target.agentId.trim() || undefined : undefined;
-}
-
-/**
- * Drafts and agents render through one chain so the timeline stays mounted when the draft's
- * first prompt creates the agent and the tab retargets. The agent gates are idle for a draft.
- */
-export function AgentConversationPanel() {
+function AgentPanel() {
   const { serverId, workspaceId, target, openFileInWorkspace } = usePaneContext();
   const { isInteractive } = usePaneFocus();
-  invariant(
-    target.kind === "agent" || target.kind === "draft",
-    "AgentConversationPanel requires an agent or draft target",
-  );
+  invariant(target.kind === "agent", "AgentPanel requires agent target");
 
   return (
     <RetainedChatContent>
       <AgentPanelContent
         serverId={serverId}
         workspaceId={workspaceId}
-        target={target}
+        agentId={target.agentId}
         isPaneFocused={isInteractive}
         onOpenWorkspaceFile={openFileInWorkspace}
       />
@@ -358,6 +321,55 @@ export function AgentConversationPanel() {
   );
 }
 
+function DraftPanel() {
+  const {
+    serverId,
+    workspaceId,
+    tabId,
+    target,
+    openFileInWorkspace,
+    openImportSheet,
+    retargetCurrentTab,
+  } = usePaneContext();
+  const { isInteractive } = usePaneFocus();
+  invariant(target.kind === "draft", "DraftPanel requires draft target");
+
+  const handleCreated = useCallback(
+    (agentSnapshot: Parameters<typeof normalizeAgentSnapshot>[0]) => {
+      const normalized = normalizeAgentSnapshot(agentSnapshot, serverId);
+      const agent = applyLegacyDaemonWorkspaceOwnership({ serverId, agent: normalized });
+      getHostRuntimeStore().acceptAgentSnapshot(serverId, agent);
+      retargetCurrentTab({ kind: "agent", agentId: agentSnapshot.id });
+    },
+    [retargetCurrentTab, serverId],
+  );
+
+  return (
+    <WorkspaceDraftAgentTab
+      serverId={serverId}
+      workspaceId={workspaceId}
+      tabId={tabId}
+      draftId={target.draftId}
+      initialSetup={target.setup}
+      isPaneFocused={isInteractive}
+      onOpenWorkspaceFile={openFileInWorkspace}
+      onCreated={handleCreated}
+      onOpenImportSheet={openImportSheet}
+    />
+  );
+}
+
+export function AgentConversationPanel() {
+  const { target } = usePaneContext();
+  if (target.kind === "draft") {
+    return <DraftPanel />;
+  }
+  if (target.kind === "agent") {
+    return <AgentPanel />;
+  }
+  invariant(false, "AgentConversationPanel requires an agent or draft target");
+}
+
 export const agentPanelRegistration = definePanel("agent", {
   component: AgentConversationPanel,
   useDescriptor: useAgentDescriptor,
@@ -432,18 +444,18 @@ type AgentLookupState =
 function AgentPanelContent({
   serverId,
   workspaceId,
-  target,
+  agentId,
   isPaneFocused,
   onOpenWorkspaceFile,
 }: {
   serverId: string;
   workspaceId: string;
-  target: ConversationTarget;
+  agentId: string;
   isPaneFocused: boolean;
   onOpenWorkspaceFile?: (request: WorkspaceFileOpenRequest) => void;
 }) {
   const { t } = useTranslation();
-  const resolvedAgentId = resolveConversationAgentId(target);
+  const resolvedAgentId = agentId.trim() || undefined;
   const resolvedServerId = serverId.trim() || undefined;
   const daemons = useHosts();
   const runtimeServerId = resolvedServerId ?? "";
@@ -472,7 +484,7 @@ function AgentPanelContent({
       : runtimeConnectionStatus;
   const lastConnectionError = runtimeLastError;
 
-  if (target.kind === "agent" && (!resolvedServerId || (!runtimeClient && !hasCachedAgent))) {
+  if (!resolvedServerId || (!runtimeClient && !hasCachedAgent)) {
     return (
       <AgentSessionUnavailableState
         serverLabel={serverLabel}
@@ -486,9 +498,9 @@ function AgentPanelContent({
 
   return (
     <AgentPanelBody
-      serverId={resolvedServerId ?? serverId}
+      serverId={resolvedServerId}
       workspaceId={workspaceId}
-      target={target}
+      agentId={resolvedAgentId}
       isPaneFocused={isPaneFocused}
       client={runtimeClient}
       isConnected={runtimeIsConnected}
@@ -500,7 +512,7 @@ function AgentPanelContent({
 function AgentPanelBody({
   serverId,
   workspaceId,
-  target,
+  agentId,
   isPaneFocused,
   client,
   isConnected,
@@ -508,14 +520,13 @@ function AgentPanelBody({
 }: {
   serverId: string;
   workspaceId: string;
-  target: ConversationTarget;
+  agentId?: string;
   isPaneFocused: boolean;
   client: ReturnType<typeof useHostRuntimeClient>;
   isConnected: boolean;
   onOpenWorkspaceFile?: (request: WorkspaceFileOpenRequest) => void;
 }) {
   const { t } = useTranslation();
-  const agentId = resolveConversationAgentId(target);
   const { isArchivingAgent: _isArchivingAgent } = useArchiveAgent();
   const hasSession = useSessionStore((state) => Boolean(state.sessions[serverId]));
   const projectPlacement = useStoreWithEqualityFn(
@@ -630,7 +641,7 @@ function AgentPanelBody({
         }
       : null;
 
-  if (target.kind === "agent" && !agent) {
+  if (!agent) {
     return (
       <View style={styles.container} testID="agent-loading">
         <View style={styles.errorContainer}>
@@ -644,7 +655,7 @@ function AgentPanelBody({
     <ChatAgentContent
       serverId={serverId}
       workspaceId={workspaceId}
-      target={target}
+      agentId={agentId}
       isPaneFocused={isPaneFocused}
       client={client}
       isConnected={isConnected}
@@ -656,7 +667,7 @@ function AgentPanelBody({
 function ChatAgentContent({
   serverId,
   workspaceId,
-  target,
+  agentId,
   isPaneFocused,
   client,
   isConnected,
@@ -664,15 +675,13 @@ function ChatAgentContent({
 }: {
   serverId: string;
   workspaceId: string;
-  target: ConversationTarget;
+  agentId?: string;
   isPaneFocused: boolean;
   client: ReturnType<typeof useHostRuntimeClient>;
   isConnected: boolean;
   onOpenWorkspaceFile?: (request: WorkspaceFileOpenRequest) => void;
 }) {
   const { t } = useTranslation();
-  const { tabId } = usePaneContext();
-  const agentId = resolveConversationAgentId(target);
   const isPaneVisible = useRetainedPanelActive();
   const { api: toastApi, toast: toastState, dismiss: dismissToast } = useToastHost();
   const { isArchivingAgent } = useArchiveAgent();
@@ -979,23 +988,17 @@ function ChatAgentContent({
     visibilityCatchUpStatus,
   ]);
 
-  const draft = useMemo<DraftConversation | null>(
-    () =>
-      target.kind === "draft"
-        ? { tabId, workspaceId, draftId: target.draftId, setup: target.setup }
-        : null,
-    [tabId, target, workspaceId],
-  );
-  const nonReadyView = renderConversationNonReadyView({
-    draft,
-    agentId,
-    cwd: agentState.cwd,
+  const nonReadyView = renderChatAgentNonReadyView({
     viewState,
     effectiveAgent,
     t,
     onRetryLoad: retryAgentLoad,
   });
   if (nonReadyView) return nonReadyView;
+  invariant(agentId, "agent id is defined when agent content is ready");
+  invariant(effectiveAgent, "effectiveAgent is defined when the non-ready view is absent");
+  const agentCwd = agentState.cwd;
+  invariant(agentCwd, "agent cwd is defined when agent content is ready");
   const showHistorySyncOverlay =
     viewState.tag === "ready" &&
     viewState.sync.status === "catching_up" &&
@@ -1010,8 +1013,7 @@ function ChatAgentContent({
     <ChatAgentReadyContent
       serverId={serverId}
       workspaceId={workspaceId}
-      agentId={agentId ?? tabId}
-      draft={draft}
+      agentId={agentId}
       isPaneFocused={isPaneFocused}
       isArchivingCurrentAgent={isArchivingCurrentAgent}
       agentState={agentState}
@@ -1029,7 +1031,7 @@ function ChatAgentContent({
       showHistorySyncOverlay={showHistorySyncOverlay}
       showHistorySyncError={showHistorySyncError}
       isRetryingHistorySync={isRetryingHistorySync}
-      cwd={agentState.cwd ?? ""}
+      cwd={agentCwd}
       retryTimelineSync={retryTimelineSync}
       onAttentionInputFocus={attentionController.clearOnInputFocus}
       onAttentionPromptSend={attentionController.clearOnPromptSend}
@@ -1042,7 +1044,6 @@ const ChatAgentReadyContent = memo(function ChatAgentReadyContent({
   serverId,
   workspaceId,
   agentId,
-  draft,
   isPaneFocused,
   isArchivingCurrentAgent,
   agentState,
@@ -1068,13 +1069,11 @@ const ChatAgentReadyContent = memo(function ChatAgentReadyContent({
 }: {
   serverId: string;
   workspaceId: string;
-  /** The agent's id, or the tab id while a draft has no agent yet. */
   agentId: string;
-  draft: DraftConversation | null;
   isPaneFocused: boolean;
   isArchivingCurrentAgent: boolean;
   agentState: ChatAgentSelectedState;
-  effectiveAgent: AgentScreenAgent | null;
+  effectiveAgent: AgentScreenAgent;
   routeBottomAnchorRequest: RouteBottomAnchorRequest;
   hasAppliedAuthoritativeHistory: boolean;
   toastApi: ToastApi;
@@ -1096,11 +1095,19 @@ const ChatAgentReadyContent = memo(function ChatAgentReadyContent({
 }) {
   const { t } = useTranslation();
   // The workspace sheet is for looking; Open as tab brings the agent back with its composer.
-  const paneHost = usePaneContext().host;
-  const showsComposer = draft !== null || paneHost !== "sheet";
+  const showsComposer = usePaneContext().host !== "sheet";
   // The dock lays out fullscreen for the same session the composer edits in.
   const composerEditingSession = useComposerEditingSession("chat");
   const isComposerFullscreen = useComposerFullscreen(composerEditingSession);
+  const subagentRows = useSubagentsForParent({ serverId, parentAgentId: agentId });
+  const tasks = useSessionStore((state): TodoEntry[] | undefined =>
+    state.sessions[serverId]?.agentTasks.get(agentId),
+  );
+  const archiveFinishedSubagents = useArchiveFinishedSubagents({
+    serverId,
+    parentAgentId: agentId,
+    rows: subagentRows,
+  });
   const hasActiveComposer = !agentState.archivedAt && !isArchivingCurrentAgent;
   const parentAgentId = useParentAgentId(serverId, agentId);
   // With a composer the parent is a pill above it; without one, the box takes the composer's place.
@@ -1154,7 +1161,7 @@ const ChatAgentReadyContent = memo(function ChatAgentReadyContent({
   const parentCallout = parentAgentId ? (
     <ParentAgentCallout serverId={serverId} parentAgentId={parentAgentId} />
   ) : null;
-  const agentComposerSection = showsComposer ? (
+  const composerSection = showsComposer ? (
     <RenderProfile id={`AgentComposerSection:${agentId}`}>
       <AgentComposerSection
         agentId={agentId}
@@ -1175,16 +1182,6 @@ const ChatAgentReadyContent = memo(function ChatAgentReadyContent({
   ) : (
     parentCallout
   );
-  const composerSection = draft ? (
-    <DraftComposerSection
-      serverId={serverId}
-      draft={draft}
-      isPaneFocused={isPaneFocused}
-      editingSession={composerEditingSession}
-    />
-  ) : (
-    agentComposerSection
-  );
   const streamContent = (
     <View style={animatedStaticStyles.content}>
       {showsComposer ? null : <SheetAgentFacts serverId={serverId} agentId={agentId} />}
@@ -1194,7 +1191,6 @@ const ChatAgentReadyContent = memo(function ChatAgentReadyContent({
           serverId={serverId}
           agentId={agentId}
           agent={effectiveAgent}
-          draft={draft}
           routeBottomAnchorRequest={routeBottomAnchorRequest}
           hasAppliedAuthoritativeHistory={hasAppliedAuthoritativeHistory}
           hasActiveComposer={hasActiveComposer}
@@ -1202,12 +1198,16 @@ const ChatAgentReadyContent = memo(function ChatAgentReadyContent({
           onOpenWorkspaceFile={onOpenWorkspaceFile}
         />
       </RenderProfile>
-      {hasActiveComposer && !draft ? (
+      {hasActiveComposer ? (
         <AgentTracks
           serverId={serverId}
           workspaceId={workspaceId}
           agentId={agentId}
           parentAgentId={parentPillAgentId}
+          subagentRows={subagentRows}
+          tasks={tasks}
+          archiveFinishedStatus={archiveFinishedSubagents.status}
+          onArchiveFinished={archiveFinishedSubagents.archiveFinished}
         />
       ) : null}
     </View>
@@ -1263,7 +1263,7 @@ const ChatAgentReadyContent = memo(function ChatAgentReadyContent({
     </RewindComposerRestoreProvider>
   );
   return wrapAgentCommandProvider({
-    enabled: showsComposer && hasActiveComposer && !draft,
+    enabled: showsComposer && hasActiveComposer,
     serverId,
     agentId,
     editingSession: composerEditingSession,
@@ -1355,7 +1355,6 @@ const AgentStreamSection = memo(function AgentStreamSection({
   serverId,
   agentId,
   agent,
-  draft,
   routeBottomAnchorRequest,
   hasAppliedAuthoritativeHistory,
   hasActiveComposer,
@@ -1365,8 +1364,7 @@ const AgentStreamSection = memo(function AgentStreamSection({
   streamViewRef: React.RefObject<AgentStreamViewHandle | null>;
   serverId: string;
   agentId?: string;
-  agent: AgentScreenAgent | null;
-  draft: DraftConversation | null;
+  agent: AgentScreenAgent;
   routeBottomAnchorRequest: RouteBottomAnchorRequest;
   hasAppliedAuthoritativeHistory: boolean;
   hasActiveComposer: boolean;
@@ -1424,31 +1422,7 @@ const AgentStreamSection = memo(function AgentStreamSection({
     }
     return new Map(pendingPermissionList.map((permission) => [permission.key, permission]));
   }, [pendingPermissionList]);
-  // A draft's timeline exists only while its first prompt creates the agent. The created agent's
-  // timeline then replaces this input in the same mounted view.
-  const draftTimeline = useDraftTimeline({ serverId, draft });
 
-  if (draftTimeline) {
-    return (
-      <AgentStreamView
-        ref={streamViewRef}
-        agentId={draftTimeline.agent.id}
-        serverId={serverId}
-        context={draftTimeline.agent}
-        streamItems={draftTimeline.streamItems}
-        pendingPermissions={EMPTY_PENDING_PERMISSIONS}
-        bottomOverlayTailClearance={bottomOverlayTailClearance}
-        bottomOverlayControlClearance={bottomOverlayControlClearance}
-        toast={toast}
-        pendingMessageSubmissions={draftTimeline.pendingMessageSubmissions}
-        turnPresentation={draftTimeline.turnPresentation}
-        onOpenWorkspaceFile={onOpenWorkspaceFile}
-      />
-    );
-  }
-  if (!agent) {
-    return null;
-  }
   return (
     <AgentStreamView
       ref={streamViewRef}
@@ -1469,44 +1443,6 @@ const AgentStreamSection = memo(function AgentStreamSection({
   );
 });
 
-/** The draft's composer, which creates the agent and retargets this tab to it. */
-function DraftComposerSection({
-  serverId,
-  draft,
-  isPaneFocused,
-  editingSession,
-}: {
-  serverId: string;
-  draft: DraftConversation;
-  isPaneFocused: boolean;
-  editingSession: ComposerEditingSession;
-}) {
-  const { openImportSheet, retargetCurrentTab } = usePaneContext();
-  const handleCreated = useCallback(
-    (agentSnapshot: Parameters<typeof normalizeAgentSnapshot>[0]) => {
-      const normalized = normalizeAgentSnapshot(agentSnapshot, serverId);
-      const agent = applyLegacyDaemonWorkspaceOwnership({ serverId, agent: normalized });
-      getHostRuntimeStore().acceptAgentSnapshot(serverId, agent);
-      retargetCurrentTab({ kind: "agent", agentId: agentSnapshot.id });
-    },
-    [retargetCurrentTab, serverId],
-  );
-
-  return (
-    <WorkspaceDraftComposer
-      serverId={serverId}
-      workspaceId={draft.workspaceId}
-      tabId={draft.tabId}
-      draftId={draft.draftId}
-      initialSetup={draft.setup}
-      isPaneFocused={isPaneFocused}
-      editingSession={editingSession}
-      onCreated={handleCreated}
-      onOpenImportSheet={openImportSheet}
-    />
-  );
-}
-
 const AgentComposerSection = memo(function AgentComposerSection({
   agentId,
   serverId,

packages/app/src/panels/agent-tracks.tsx

@@ -9,11 +9,11 @@ import { useSettings } from "@/hooks/use-settings";
 import { PluginComposerPills } from "@/plugins";
 import { useSessionStore } from "@/stores/session-store";
 import {
-  useArchiveFinishedSubagents,
+  type ArchiveFinishedStatus,
   useArchiveSubagent,
   useDetachSubagent,
   useSubagentSheetTab,
-  useSubagentsForParent,
+  type SubagentRow,
 } from "@/subagents";
 import { ParentAgentPill } from "@/subagents/parent";
 import { SubagentsTrack } from "@/subagents/track";
@@ -35,21 +35,20 @@ export const AgentTracks = memo(function AgentTracks({
   workspaceId,
   agentId,
   parentAgentId,
+  subagentRows,
+  tasks,
+  archiveFinishedStatus,
+  onArchiveFinished,
 }: {
   serverId: string;
   workspaceId: string;
   agentId: string;
   parentAgentId: string | null;
+  subagentRows: SubagentRow[];
+  tasks: TodoEntry[] | undefined;
+  archiveFinishedStatus: ArchiveFinishedStatus;
+  onArchiveFinished: () => void;
 }): ReactElement {
-  const subagentRows = useSubagentsForParent({ serverId, parentAgentId: agentId });
-  const tasks = useSessionStore((state): TodoEntry[] | undefined =>
-    state.sessions[serverId]?.agentTasks.get(agentId),
-  );
-  const archiveFinishedSubagents = useArchiveFinishedSubagents({
-    serverId,
-    parentAgentId: agentId,
-    rows: subagentRows,
-  });
   const { tabId } = usePaneContext();
   const isCompact = useIsCompactFormFactor();
   const openInSidePane = useSettings((settings) => settings.openInSidePane);
@@ -120,8 +119,8 @@ export const AgentTracks = memo(function AgentTracks({
         onOpenProviderSubagent={handleOpenProviderSubagent}
         sheetTabFor={sheetTabFor}
         onArchiveSubagent={archiveSubagent}
-        onArchiveFinished={archiveFinishedSubagents.archiveFinished}
-        archiveFinishedStatus={archiveFinishedSubagents.status}
+        onArchiveFinished={onArchiveFinished}
+        archiveFinishedStatus={archiveFinishedStatus}
         onDetachSubagent={canDetachSubagents ? detachSubagent : undefined}
       />
       <PluginComposerPills

packages/app/src/runtime/directory-sync/agent-replica.test.ts

@@ -390,39 +390,4 @@ describe("AgentDirectoryReplica", () => {
     expect(useSessionStore.getState().sessions[serverId]?.agents.has("agent")).toBe(true);
     store.clearSession(serverId);
   });
-  it("keeps unchanged agent fields when an update changes only the status", () => {
-    const serverId = "agent-replica-unchanged-fields";
-    const store = useSessionStore.getState();
-    store.initializeSession(serverId, null as unknown as DaemonClient);
-    const replica = new AgentDirectoryReplica(
-      serverId,
-      () => undefined,
-      () => undefined,
-    );
-    const agentInStore = () => useSessionStore.getState().sessions[serverId]?.agents.get("agent");
-    replica.commitSnapshot([entry(payload("agent"))], []);
-    const before = agentInStore();
-
-    replica.applyDelta({
-      kind: "upsert",
-      agent: { ...payload("agent"), status: "running", updatedAt: "2026-07-17T00:02:00.000Z" },
-      project: entry(payload("agent")).project,
-    });
-    const afterDelta = agentInStore();
-    replica.commitSnapshot(
-      [entry({ ...payload("agent"), status: "idle", updatedAt: "2026-07-17T00:03:00.000Z" })],
-      [],
-    );
-    const afterSnapshot = agentInStore();
-
-    expect(afterDelta?.status).toBe("running");
-    expect(afterSnapshot?.status).toBe("idle");
-    for (const agent of [afterDelta, afterSnapshot]) {
-      expect(agent?.capabilities).toBe(before?.capabilities);
-      expect(agent?.availableModes).toBe(before?.availableModes);
-      expect(agent?.labels).toBe(before?.labels);
-      expect(agent?.projectPlacement).toBe(before?.projectPlacement);
-    }
-    store.clearSession(serverId);
-  });
 });

packages/app/src/runtime/directory-sync/internal/agent-store.ts

@@ -21,26 +21,6 @@ function withoutAgent(agentId: string) {
   };
 }
 
-/**
- * Every update arrives as a whole new agent, so each nested value (capabilities, modes, labels) is
- * a new object even when it did not change. Keep the stored value for every field that is equal,
- * and the stored agent when nothing changed, so a reader of one field sees a new value only when
- * that field changes.
- */
-function keepUnchangedFields(stored: Agent, incoming: Agent): Agent {
-  const next = { ...incoming };
-  let changed = Object.keys(stored).length !== Object.keys(next).length;
-  for (const key of Object.keys(next) as (keyof Agent)[]) {
-    if (next[key] === stored[key]) continue;
-    if (key in stored && equal(next[key], stored[key])) {
-      Object.assign(next, { [key]: stored[key] });
-    } else {
-      changed = true;
-    }
-  }
-  return changed ? next : stored;
-}
-
 function mergeSnapshotTurn(previous: Agent | undefined, incoming: Agent): Agent {
   if (!previous) return incoming;
   const activeTurn =
@@ -79,8 +59,7 @@ export class AgentStoreProjection {
     let accepted = agent;
     useSessionStore.getState().setAgents(this.serverId, (current) => {
       const previous = current.get(agent.id);
-      const winner = acceptAgentDirectoryUpdate(previous, mergeSnapshotTurn(previous, agent));
-      accepted = previous ? keepUnchangedFields(previous, winner) : winner;
+      accepted = acceptAgentDirectoryUpdate(previous, mergeSnapshotTurn(previous, agent));
       if (accepted === previous) return current;
       const next = new Map(current);
       next.set(agent.id, accepted);
@@ -138,7 +117,7 @@ export class AgentStoreProjection {
     for (const [agentId, fetchedAgent] of fetched) {
       const existing = current.get(agentId);
       const merged = mergeSnapshotTurn(existing, fetchedAgent);
-      agents.set(agentId, existing ? keepUnchangedFields(existing, merged) : merged);
+      agents.set(agentId, existing && equal(existing, merged) ? existing : merged);
       if (fetchedAgent.archivedAt) {
         clearArchiveAgentPending({ queryClient, serverId: this.serverId, agentId });
       }

packages/app/src/runtime/replica-cache/index.test.ts

@@ -321,26 +321,6 @@ 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);

packages/app/src/runtime/replica-cache/index.ts

@@ -299,7 +299,6 @@ 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(),
@@ -708,7 +707,6 @@ 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,

packages/app/src/screens/workspace/workspace-screen.tsx

@@ -870,12 +870,8 @@ function WorkspaceDocumentTitleEffectSlot({
   );
 }
 
-/**
- * The header floats over a conversation's timeline. A draft and the agent it creates share one
- * timeline, so their surfaces match and the timeline does not move when the tab retargets.
- */
 function floatsHeaderOverContent(activeTab: WorkspaceTabDescriptor | null): boolean {
-  return supportsStreamTopOverlay && (activeTab?.kind === "agent" || activeTab?.kind === "draft");
+  return supportsStreamTopOverlay && activeTab?.kind === "agent";
 }
 
 /** A fullscreen composer covers the compact header; the column lays out without it. */

packages/app/src/stores/session-store.test.ts

@@ -557,33 +557,6 @@ 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",

packages/app/src/stores/session-store.ts

@@ -105,7 +105,6 @@ export interface Agent {
 }
 
 export interface WorkspaceDescriptor {
-  parentWorkspaceId?: string;
   createdAt: Date | null;
   lastUserMessageAt: Date | null;
   id: string;
@@ -163,7 +162,6 @@ 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,

packages/app/src/usage/queries.ts

@@ -33,10 +33,9 @@ import {
 } from "./model";
 import type { UsageReportEntry, UsageView } from "./types";
 
-// The daemon caches each report for five minutes, so re-reading it is cheap.
-// An explicit refresh passes `forceRefresh` to bypass that cache.
+// 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.
 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) {
@@ -165,16 +164,11 @@ export function useHostUsage(serverId: string): { view: UsageView; refresh: () =
 
 const NO_REPORTS: 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[] {
+/**
+ * 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[] {
   const setting = useUsageSetting(serverId);
   const queryClient = useQueryClient();
   const query = useFetchQuery({
@@ -183,7 +177,6 @@ export function useUsageHostReports({
     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;
 }

packages/app/src/usage/sidebar-item.tsx

@@ -16,8 +16,6 @@ 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";
@@ -38,14 +36,9 @@ 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({
-    serverId: inSidebar ? serverId : null,
-    shouldPoll: active && inSidebar && isAppVisible,
-  });
+  const reports = useUsageHostReports(inSidebar ? serverId : null);
   const { preferences } = useUsageDisplay(reports);
   return useMemo(() => resolvePinnedUsage(reports, preferences, t), [preferences, reports, t]);
 }

packages/app/src/utils/agent-directory-reconciliation.test.ts

@@ -126,23 +126,6 @@ describe("agent directory reconciliation", () => {
     }).toEqual({ title: "newer page", status: "running", projectName: "repo" });
   });
 
-  it("takes the project of a newer buffered upsert", () => {
-    const snapshotEntry = entry("agent", "idle");
-    const newerProject = { ...snapshotEntry.project, projectName: "renamed project" };
-    const result = reconcileAgentDirectory({
-      snapshot: [snapshotEntry],
-      deltas: [
-        {
-          kind: "upsert",
-          agent: { ...snapshot("agent", "idle"), updatedAt: "2026-07-12T11:00:00.000Z" },
-          project: newerProject,
-        },
-      ],
-    });
-
-    expect(result[0]?.project.projectName).toBe("renamed project");
-  });
-
   it("clears a snapshot stop when a newer buffered upsert is running", () => {
     const result = reconcileAgentDirectory({
       snapshot: [entry("agent", "idle")],

packages/client/package.json

@@ -45,7 +45,8 @@
     "prepack": "npm run build:clean",
     "typecheck": "tsgo --noEmit",
     "typecheck:examples": "tsgo -p tsconfig.examples.json --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "measure:diff-materialization": "tsx scripts/measure-diff-materialization.ts"
   },
   "dependencies": {
     "@getpaseo/protocol": "0.15.2",

packages/client/scripts/measure-diff-materialization.ts

@@ -0,0 +1,38 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { performance } from "node:perf_hooks";
+import { decodeDiffFrame } from "@getpaseo/protocol/binary-frames/index";
+import { validateWSOutboundMessage } from "@getpaseo/protocol/validation/ws-outbound";
+import { DiffStream } from "../src/diff/stream.js";
+const artifacts = resolve(import.meta.dirname, "../../../.artifacts/diff-subscription");
+const results = [];
+for (const count of [1, 30]) {
+  const corpus = JSON.parse(await readFile(resolve(artifacts, `corpus-${count}.json`), "utf8")) as {
+    frames: string[];
+    legacy: string;
+  };
+  const frames = corpus.frames.map((value) => Buffer.from(value, "base64"));
+  const binary: number[] = [];
+  const json: number[] = [];
+  for (let iteration = 0; iteration < 15; iteration++) {
+    let files = 0;
+    const stream = new DiffStream((state) => {
+      if (state.phase === "ready") files = state.files.length;
+    });
+    let start = performance.now();
+    for (const frame of frames) stream.receive(decodeDiffFrame(frame));
+    binary.push(performance.now() - start);
+    start = performance.now();
+    validateWSOutboundMessage(JSON.parse(corpus.legacy));
+    json.push(performance.now() - start);
+    if (!files) throw new Error("No materialized files");
+  }
+  const median = (values: number[]) =>
+    values.slice(3).sort((a, b) => a - b)[Math.floor((values.length - 3) / 2)];
+  const result = { count, materializationMs: median(binary), jsonParseValidationMs: median(json) };
+  results.push(result);
+  console.log(JSON.stringify(result));
+}
+await writeFile(resolve(artifacts, "client-metrics.json"), JSON.stringify(results, null, 2));
+if (results.some((result) => result.materializationMs > result.jsonParseValidationMs))
+  process.exitCode = 1;

packages/client/src/daemon-client.ts

@@ -1,3 +1,9 @@
+import {
+  DiffStreamRouter,
+  DiffSubscriptionError,
+  type DiffCompare,
+  type DiffState,
+} from "./diff/index.js";
 import {
   ChunkedTransport,
   ChunkedTransportProtocolError,
@@ -1411,6 +1417,20 @@ export class DaemonClient {
   private connectionFailure: Error | undefined;
   private authFailureReasonValue: DaemonAuthFailureReason | null = null;
   private connectionState: ConnectionState = { status: "idle" };
+  private readonly diffStreams = new DiffStreamRouter({
+    modern: (compare) =>
+      this.observe(
+        "diff.subscribe.response",
+        { type: "diff.subscribe.request", ...compare },
+        {
+          validateSnapshot: (payload) => {
+            if (payload.error) throw new DiffSubscriptionError(payload.error);
+          },
+        },
+      ),
+    legacy: (cwd, compare) => this.observeCheckoutDiff(cwd, compare),
+    failed: (error) => this.logger.error({ err: error }, "Diff observer failed"),
+  });
   private readonly terminalStreams = new TerminalStreamRouter();
   private pendingBinaryFileReads = new Map<string, PendingBinaryFileRead>();
   private activeBinaryFileTransfers = new Map<string, BinaryFileTransferState>();
@@ -1760,6 +1780,7 @@ export class DaemonClient {
     this.disposeTransport(1000, "Client closed");
     this.providerSnapshotUpdates.clear();
     this.clearWaiters(new Error("Daemon client closed"));
+    await this.diffStreams.close();
     await this.owned.close();
     this.creations.close();
     this.rejectPendingSendQueue(new Error("Daemon client closed"));
@@ -2663,7 +2684,12 @@ export class DaemonClient {
   private observe<T extends CorrelatedResponseType>(
     responseType: T,
     message: { type: SessionInboundMessage["type"] } & Record<string, unknown>,
-    options?: { requestId?: string; timeout?: number; signal?: AbortSignal },
+    options?: {
+      requestId?: string;
+      timeout?: number;
+      signal?: AbortSignal;
+      validateSnapshot?: (payload: CorrelatedResponsePayload<T>) => void;
+    },
   ): OwnedSubscription<CorrelatedResponsePayload<T>> {
     let resetSource = false;
     return this.owned.observeRequest<CorrelatedResponsePayload<T>>(
@@ -2689,12 +2715,16 @@ export class DaemonClient {
                   requestType: message.type,
                   error: payload.error,
                 });
+              options?.validateSnapshot?.(payload);
               accept(payload);
               return payload;
             },
           });
         } catch (error) {
-          resetSource = !(error instanceof DaemonRpcError) && this.isConnected;
+          resetSource =
+            !(error instanceof DaemonRpcError) &&
+            !(error instanceof DiffSubscriptionError) &&
+            this.isConnected;
           throw error;
         }
       },
@@ -4660,6 +4690,26 @@ export class DaemonClient {
     });
   }
 
+  observeDiff(compare: DiffCompare): OwnedSubscription<DiffState> {
+    return this.diffStreams.observe(compare);
+  }
+
+  async readDiff(compare: DiffCompare): Promise<DiffState> {
+    const observation = this.observeDiff(compare);
+    try {
+      return await new Promise<DiffState>((resolve) => {
+        observation.subscribe({
+          snapshot: (state) => {
+            if (state.phase !== "loading") resolve(state);
+          },
+          update: () => {},
+        });
+      });
+    } finally {
+      await observation.release();
+    }
+  }
+
   observeCheckoutDiff(
     cwd: string,
     compare: { mode: "uncommitted" | "base" | "all"; baseRef?: string; ignoreWhitespace?: boolean },
@@ -6936,6 +6986,7 @@ export class DaemonClient {
     this.chunkedTransport?.close();
     this.chunkedTransport = null;
     this.owned.disconnected();
+    this.diffStreams.disconnected();
     this.providerSnapshotUpdates.clear();
     this.stopLivenessHeartbeat();
     this.cleanupTransport();
@@ -7126,6 +7177,10 @@ export class DaemonClient {
       for (const handler of this.hostFrameListeners) handler(hostFrame);
       return true;
     }
+    if (rawBytes[0] >= 0x40 && rawBytes[0] <= 0x4f) {
+      this.diffStreams.receive(rawBytes);
+      return true;
+    }
     if (isPluginFrameOpcode(rawBytes[0])) {
       this.handlePluginFrame(rawBytes);
       return true;
@@ -7326,6 +7381,7 @@ export class DaemonClient {
     }
 
     this.owned.disconnected();
+    this.diffStreams.disconnected();
     this.providerSnapshotUpdates.clear();
 
     // Clear all pending waiters and queued sends since the connection was lost
@@ -7485,6 +7541,7 @@ export class DaemonClient {
           this.reconnectAttempt = 0;
           this.updateConnectionState({ status: "connected" }, { event: "HELLO_SERVER_INFO" });
           this.startLivenessHeartbeat();
+          this.diffStreams.connected(serverInfo.features?.diffSubscription === true);
           this.owned.restore(serverInfo, {
             ...DEFAULT_CLIENT_CAPABILITIES,
             ...this.config.capabilities,
@@ -7761,3 +7818,5 @@ function resolveAgentConfig(options: CreateAgentRequestOptions): AgentSessionCon
     cwd: merged.cwd,
   };
 }
+
+export type { DiffCompare, DiffState, DiffEntry, ResolvedShas } from "./diff/index.js";

packages/client/src/diff/client.test.ts

@@ -0,0 +1,210 @@
+import { expect, test } from "vitest";
+import { DaemonClient, type DaemonTransport } from "../daemon-client.js";
+import {
+  encodeDiffFrame,
+  DiffOpcode,
+  type DiffFrame,
+} from "@getpaseo/protocol/binary-frames/index";
+import type { DiffState } from "./index.js";
+function socket() {
+  let message: (data: unknown, binary?: boolean) => void = () => {};
+  let open: () => void = () => {};
+  let close: (event?: unknown) => void = () => {};
+  const sent: Record<string, unknown>[] = [];
+  const transport: DaemonTransport = {
+    send: (data) => {
+      if (typeof data === "string") {
+        const value = JSON.parse(data);
+        if (value.type === "session") {
+          sent.push(value.message);
+          if (value.message.type === "subscription.release.request")
+            queueMicrotask(() =>
+              receive({
+                type: "subscription.release.response",
+                payload: {
+                  requestId: value.message.requestId,
+                  subscriptionId: value.message.subscriptionId,
+                  released: true,
+                },
+              }),
+            );
+        }
+      }
+    },
+    close: () => {},
+    onMessage: (handler) => {
+      message = handler;
+      return () => {};
+    },
+    onOpen: (handler) => {
+      open = handler;
+      return () => {};
+    },
+    onClose: (handler) => {
+      close = handler;
+      return () => {};
+    },
+    onError: () => () => {},
+  };
+  const receive = (value: unknown) =>
+    message(JSON.stringify({ type: "session", message: value }), false);
+  return {
+    transport,
+    sent,
+    receive,
+    raw: (bytes: Uint8Array) => message(bytes, true),
+    frame: (frame: DiffFrame) => message(encodeDiffFrame(frame), true),
+    disconnect: () => close({ code: 1001 }),
+    open: (modern = true) => {
+      open();
+      receive({
+        type: "status",
+        payload: {
+          status: "server_info",
+          serverId: "srv_test",
+          hostname: null,
+          version: null,
+          features: { ownedSubscriptions: true, diffSubscription: modern, checkoutDiffAll: true },
+        },
+      });
+    },
+  };
+}
+const compare = {
+  cwd: "/repo",
+  base: { kind: "rev", rev: "HEAD" },
+  head: { kind: "worktree" },
+} as const;
+const begin: DiffFrame = {
+  opcode: DiffOpcode.Begin,
+  slot: 3,
+  revision: 1,
+  baseRevision: 0,
+  baseSha: "a",
+  headSha: "b",
+  mergeBaseSha: "",
+  entries: [],
+};
+const end: DiffFrame = {
+  opcode: DiffOpcode.End,
+  slot: 3,
+  revision: 1,
+  diffTooLarge: false,
+  omitted: [],
+  error: null,
+};
+async function setup(modern = true) {
+  const wire = socket();
+  const client = new DaemonClient({
+    url: "ws://test",
+    clientId: "diff-test",
+    transportFactory: () => wire.transport,
+    reconnect: { enabled: false },
+  });
+  const connecting = client.connect();
+  wire.open(modern);
+  await connecting;
+  return { wire, client };
+}
+function acknowledge(wire: ReturnType<typeof socket>, ordinal = 1) {
+  const request = wire.sent.findLast((value) => value.type === "diff.subscribe.request");
+  wire.receive({
+    type: "diff.subscribe.response",
+    payload: {
+      requestId: request?.requestId,
+      subscriptionId: `diff-${ordinal}`,
+      slot: 3,
+      error: null,
+    },
+  });
+}
+test("attaches binary routing during handshake and resubscribes with a full state on reconnect", async () => {
+  const { wire, client } = await setup();
+  try {
+    const states: DiffState[] = [];
+    const observation = client.observeDiff(compare);
+    observation.subscribe({ snapshot: (state) => states.push(state), update: () => {} });
+    acknowledge(wire);
+    wire.frame(begin);
+    wire.frame(end);
+    expect(states.map((state) => state.phase)).toEqual(["loading", "ready"]);
+    wire.disconnect();
+    const connected = client.connect();
+    wire.open();
+    await connected;
+    acknowledge(wire, 2);
+    wire.frame(begin);
+    wire.frame(end);
+    expect(states.map((state) => state.phase)).toEqual(["loading", "ready", "loading", "ready"]);
+    await observation.release();
+  } finally {
+    await client.close();
+  }
+});
+test("an unknown version fails only its subscription and readDiff resolves typed subscribe errors", async () => {
+  const { wire, client } = await setup();
+  try {
+    const observation = client.observeDiff(compare);
+    const states: DiffState[] = [];
+    observation.subscribe({ snapshot: (state) => states.push(state), update: () => {} });
+    acknowledge(wire);
+    const malformed = { ...begin, slot: 3 };
+    const bytes = encodeDiffFrame(malformed);
+    bytes[2] = 255;
+    wire.raw(bytes);
+    expect(states.at(-1)).toMatchObject({ phase: "error", error: { code: "UNKNOWN" } });
+    const next = client.readDiff(compare);
+    const request = wire.sent.findLast((value) => value.type === "diff.subscribe.request");
+    wire.receive({
+      type: "diff.subscribe.response",
+      payload: {
+        requestId: request?.requestId,
+        subscriptionId: "",
+        slot: 0,
+        error: { code: "INVALID_COMPARE", message: "invalid" },
+      },
+    });
+    expect(await next).toMatchObject({ phase: "error", error: { code: "INVALID_COMPARE" } });
+    expect(client.isConnected).toBe(true);
+    await observation.release();
+  } finally {
+    await client.close();
+  }
+});
+test.each(["uncommitted", "base", "all"] as const)(
+  "old hosts serve the %s comparison through the tagged compatibility route",
+  async (mode) => {
+    const { wire, client } = await setup(false);
+    try {
+      const comparison =
+        mode === "uncommitted"
+          ? compare
+          : {
+              ...compare,
+              base: { kind: "rev", rev: "refs/tags/v1" } as const,
+              head: mode === "base" ? ({ kind: "rev", rev: "HEAD" } as const) : compare.head,
+              mergeBase: true,
+            };
+      const result = client.readDiff(comparison);
+      const request = wire.sent.find((value) => value.type === "subscribe_checkout_diff_request");
+      expect(request?.compare).toMatchObject({ mode });
+      wire.receive({
+        type: "subscribe_checkout_diff_response",
+        payload: {
+          requestId: request?.requestId,
+          subscriptionId: "legacy",
+          cwd: "/repo",
+          files: [],
+          error: null,
+        },
+      });
+      wire.receive({
+        type: "checkout_diff_update",
+        payload: { subscriptionId: "legacy", cwd: "/repo", files: [], error: null },
+      });
+      expect(await result).toMatchObject({ phase: "ready", files: [] });
+    } finally {
+      await client.close();
+    }
+  },
+);

packages/client/src/diff/index.ts

@@ -0,0 +1,246 @@
+import {
+  decodeDiffFrame,
+  type DiffEntry as WireEntry,
+  type DiffBegin,
+} from "@getpaseo/protocol/binary-frames/index";
+import type {
+  DiffSubscribeRequest,
+  SubscribeCheckoutDiffRequest,
+  DiffError,
+  DiffSubscribeResponse,
+  SubscribeCheckoutDiffResponse,
+  ParsedDiffFile,
+} from "@getpaseo/protocol/messages";
+import type { OwnedSubscription, SubscriptionObserver } from "../connection/index.js";
+import { DiffStream } from "./stream.js";
+export type { DiffEndpoint } from "@getpaseo/protocol/messages";
+export type DiffCompare = Omit<DiffSubscribeRequest, "type" | "requestId">;
+
+export type DiffEntry = Omit<WireEntry, "body">;
+export type ResolvedShas = Pick<DiffBegin, "baseSha" | "headSha" | "mergeBaseSha">;
+
+export type DiffState =
+  | { phase: "loading"; revision: number; entries: DiffEntry[] }
+  | {
+      phase: "ready";
+      revision: number;
+      resolved: ResolvedShas;
+      diffTooLarge: boolean;
+      files: ParsedDiffFile[];
+    }
+  | { phase: "error"; revision: number; error: DiffError };
+type LegacyCompare = SubscribeCheckoutDiffRequest["compare"];
+
+interface Port {
+  modern(compare: DiffCompare): OwnedSubscription<DiffSubscribeResponse["payload"]>;
+  legacy(
+    cwd: string,
+    compare: LegacyCompare,
+  ): OwnedSubscription<SubscribeCheckoutDiffResponse["payload"]>;
+  failed(error: unknown): void;
+}
+export class DiffSubscriptionError extends Error {
+  constructor(readonly detail: DiffError) {
+    super(detail.message);
+  }
+}
+interface Registration {
+  start(modern: boolean): void;
+  disconnected(): void;
+  release(): Promise<void>;
+}
+/** Capability selection, slot ownership and reconnect belong to this domain. */
+export class DiffStreamRouter {
+  private registrations = new Set<Registration>();
+  private slots = new Map<number, { receive(bytes: Uint8Array): void }>();
+  private mode: boolean | null = null;
+  constructor(private port: Port) {}
+  connected(modern: boolean): void {
+    this.mode = modern;
+    for (const registration of this.registrations) registration.start(modern);
+  }
+  disconnected(): void {
+    this.mode = null;
+    this.slots.clear();
+    for (const registration of this.registrations) registration.disconnected();
+  }
+  async close(): Promise<void> {
+    await Promise.all([...this.registrations].map((registration) => registration.release()));
+  }
+  receive(bytes: Uint8Array): void {
+    const owner = this.slots.get(bytes[1]);
+    owner?.receive(bytes);
+  }
+  private releaseBackend(backend: OwnedSubscription<unknown> | null): void {
+    void backend?.release().catch(this.port.failed);
+  }
+  observe(compare: DiffCompare): OwnedSubscription<DiffState> {
+    let backend: OwnedSubscription<unknown> | null = null;
+    let state: (DiffState & { subscriptionId: string }) | null = null;
+    let slot: number | null = null;
+    let released = false;
+    let generation = 0;
+    let stream: DiffStream;
+    const observers = new Set<SubscriptionObserver<DiffState & { subscriptionId: string }>>();
+    let resolve!: (state: DiffState & { subscriptionId: string }) => void;
+    const ready = new Promise<DiffState & { subscriptionId: string }>((accept) => {
+      resolve = accept;
+    });
+    const publish = (value: DiffState) => {
+      if (released) return;
+      state = { ...value, subscriptionId: backend?.subscriptionId ?? "" };
+      resolve(state);
+      for (const observer of observers) {
+        try {
+          observer.snapshot(state);
+        } catch (error) {
+          this.port.failed(error);
+        }
+      }
+    };
+    const detach = () => {
+      if (slot !== null) this.slots.delete(slot);
+      slot = null;
+    };
+    const fail = (error: unknown) => {
+      detach();
+      publish({
+        phase: "error",
+        revision: 0,
+        error:
+          error instanceof DiffSubscriptionError
+            ? error.detail
+            : { code: "UNKNOWN", message: error instanceof Error ? error.message : String(error) },
+      });
+      this.releaseBackend(backend);
+    };
+    const registration: Registration = {
+      start: (modern) => {
+        if (released || backend) return;
+        const current = ++generation;
+        const failed = (error: unknown) => {
+          if (current === generation) fail(error);
+        };
+        stream = new DiffStream(publish);
+        if (modern) {
+          const observation = this.port.modern(compare);
+          backend = observation;
+          observation.subscribe({
+            snapshot: (payload) => {
+              if (current !== generation) return;
+              detach();
+              if (payload.error) {
+                fail(new DiffSubscriptionError(payload.error));
+                return;
+              }
+              slot = payload.slot;
+              const owner = {
+                receive: (bytes: Uint8Array) => {
+                  try {
+                    stream.receive(decodeDiffFrame(bytes));
+                  } catch (error) {
+                    fail(error);
+                  }
+                },
+              };
+              this.slots.set(slot, owner);
+            },
+            update: () => {},
+            error: failed,
+          });
+          void observation.ready.catch(failed);
+        } else {
+          // COMPAT(diffSubscription): added in v0.15.0, remove after 2027-05-06.
+          const legacy = legacyCompare(compare);
+          if (!legacy) {
+            fail(
+              new DiffSubscriptionError({
+                code: "INVALID_COMPARE",
+                message: "Update the host to use this comparison",
+              }),
+            );
+            return;
+          }
+          const observation = this.port.legacy(compare.cwd, legacy);
+          backend = observation;
+          const apply = (
+            payload: Pick<
+              SubscribeCheckoutDiffResponse["payload"],
+              "files" | "error" | "diffTooLarge"
+            >,
+          ) => {
+            if (current !== generation) return;
+            if (payload.error)
+              publish({
+                phase: "error",
+                revision: 0,
+                error: {
+                  code: payload.error.code === "NOT_GIT_REPO" ? "NOT_GIT_REPO" : "UNKNOWN",
+                  message: payload.error.message,
+                },
+              });
+            else
+              publish({
+                phase: "ready",
+                revision: (state?.revision ?? 0) + 1,
+                resolved: { baseSha: "", headSha: "", mergeBaseSha: "" },
+                diffTooLarge: payload.diffTooLarge === true,
+                files: payload.files,
+              });
+          };
+          observation.subscribe({
+            snapshot: apply,
+            update: (message) => {
+              if (message.type === "checkout_diff_update") apply(message.payload);
+            },
+            error: failed,
+          });
+          void observation.ready.catch(failed);
+        }
+      },
+      disconnected: () => {
+        generation++;
+        detach();
+        state = null;
+        const old = backend;
+        backend = null;
+        void old?.release().catch(this.port.failed);
+      },
+      release: async () => {
+        if (released) return;
+        released = true;
+        generation++;
+        detach();
+        this.registrations.delete(registration);
+        await backend?.release();
+        observers.clear();
+      },
+    };
+    this.registrations.add(registration);
+    if (this.mode !== null) registration.start(this.mode);
+    return {
+      get subscriptionId() {
+        return backend?.subscriptionId ?? null;
+      },
+      ready,
+      subscribe: (observer) => {
+        observers.add(observer);
+        if (state) observer.snapshot(state);
+        return () => observers.delete(observer);
+      },
+      release: () => registration.release(),
+    };
+  }
+}
+function legacyCompare(compare: DiffCompare): LegacyCompare | null {
+  if (compare.highlight === false) return null;
+  const { base, head } = compare;
+  if (base.kind !== "rev") return null;
+  if (base.rev === "HEAD" && head.kind === "worktree")
+    return { mode: "uncommitted", ignoreWhitespace: compare.ignoreWhitespace };
+  if (compare.mergeBase && head.kind === "rev" && head.rev === "HEAD")
+    return { mode: "base", baseRef: base.rev, ignoreWhitespace: compare.ignoreWhitespace };
+  if (compare.mergeBase && head.kind === "worktree")
+    return { mode: "all", baseRef: base.rev, ignoreWhitespace: compare.ignoreWhitespace };
+  return null;
+}

packages/client/src/diff/stream.test.ts

@@ -0,0 +1,86 @@
+import { expect, test } from "vitest";
+import { DiffStream } from "./stream.js";
+import { DiffOpcode, type DiffBegin } from "@getpaseo/protocol/binary-frames/index";
+import type { DiffState } from "./index.js";
+const entry = {
+  path: "a.ts",
+  oldPath: null,
+  change: "modified" as const,
+  content: "text" as const,
+  additions: 1,
+  deletions: 0,
+  body: true,
+};
+const begin = (revision: number, baseRevision = 0): DiffBegin => ({
+  opcode: DiffOpcode.Begin,
+  slot: 0,
+  revision,
+  baseRevision,
+  baseSha: "a",
+  headSha: "b",
+  mergeBaseSha: "",
+  entries: [entry],
+});
+const end = (revision: number) =>
+  ({
+    opcode: DiffOpcode.End,
+    slot: 0,
+    revision,
+    diffTooLarge: false,
+    omitted: [],
+    error: null,
+  }) as const;
+test("publishes the initial tree, commits on End and buffers refreshes with stable equal files", () => {
+  const states: DiffState[] = [];
+  const stream = new DiffStream((state) => states.push(state));
+  stream.receive(begin(1));
+  expect(states[0]).toMatchObject({ phase: "loading", entries: [{ path: "a.ts" }] });
+  stream.receive({
+    opcode: DiffOpcode.Bodies,
+    slot: 0,
+    revision: 1,
+    files: [{ path: "a.ts", hunks: [] }],
+  });
+  expect(states).toHaveLength(1);
+  stream.receive(end(1));
+  const ready = states[1];
+  if (ready.phase !== "ready") throw new Error("Expected ready");
+  stream.receive(begin(2, 1));
+  stream.receive({
+    opcode: DiffOpcode.Bodies,
+    slot: 0,
+    revision: 2,
+    files: [{ path: "a.ts", hunks: [] }],
+  });
+  expect(states).toHaveLength(2);
+  stream.receive(end(2));
+  const refreshed = states[2];
+  if (refreshed.phase !== "ready") throw new Error("Expected ready");
+  expect(refreshed.files[0]).toBe(ready.files[0]);
+});
+test("superseded and stale frames cannot leave the client loading; End is authoritative", () => {
+  const states: DiffState[] = [];
+  const stream = new DiffStream((s) => states.push(s));
+  stream.receive(begin(1));
+  stream.receive(begin(2));
+  stream.receive(end(1));
+  expect(() => stream.receive(end(2))).toThrow(/Missing/);
+  stream.receive(begin(3));
+  stream.receive({ ...end(3), error: { code: "REF_NOT_FOUND", message: "gone" } });
+  expect(states.at(-1)).toMatchObject({ phase: "error", error: { code: "REF_NOT_FOUND" } });
+  stream.receive({ ...begin(4), entries: [] });
+  stream.receive(end(4));
+  expect(states.at(-1)).toMatchObject({ phase: "ready", files: [] });
+});
+test("unchanged entries retain hunks, omissions override cache, removed paths disappear", () => {
+  const states: DiffState[] = [];
+  const stream = new DiffStream((s) => states.push(s));
+  stream.receive(begin(1));
+  stream.receive({ ...end(1), omitted: ["a.ts"], diffTooLarge: true });
+  stream.receive({ ...begin(2, 1), entries: [{ ...entry, body: false }] });
+  stream.receive(end(2));
+  expect(states.at(-1)).toMatchObject({ phase: "ready", files: [{ status: "too_large" }] });
+  stream.receive({ ...begin(3, 2), entries: [] });
+  stream.receive(end(3));
+  expect(states.at(-1)).toMatchObject({ phase: "ready", files: [] });
+});

packages/client/src/diff/stream.ts

@@ -0,0 +1,94 @@
+import {
+  DiffOpcode,
+  materializeDiffFile,
+  type DiffBegin,
+  type DiffBody,
+  type DiffFrame,
+} from "@getpaseo/protocol/binary-frames/index";
+import type { ParsedDiffFile } from "@getpaseo/protocol/messages";
+import type { DiffState } from "./index.js";
+
+/** Owns revision assembly. End, rather than a local body count, commits the snapshot. */
+export class DiffStream {
+  private pending: { begin: DiffBegin; bodies: Map<string, DiffBody> } | null = null;
+  private committed: Extract<DiffState, { phase: "ready" }> | null = null;
+  constructor(private publish: (state: DiffState) => void) {}
+  receive(frame: DiffFrame): void {
+    if (frame.opcode === DiffOpcode.Begin) {
+      if (frame.baseRevision !== 0 && frame.baseRevision !== this.committed?.revision)
+        throw new Error("Unknown diff base revision");
+      if (new Set(frame.entries.map((entry) => entry.path)).size !== frame.entries.length)
+        throw new Error("Duplicate diff entry");
+      this.pending = { begin: frame, bodies: new Map() };
+      if (!this.committed)
+        this.publish({
+          phase: "loading",
+          revision: frame.revision,
+          entries: frame.entries.map(({ body: _body, ...entry }) => entry),
+        });
+      return;
+    }
+    const pending = this.pending;
+    if (!pending || frame.revision !== pending.begin.revision) return;
+    if (frame.opcode === DiffOpcode.Bodies) {
+      for (const body of frame.files) {
+        if (pending.bodies.has(body.path)) throw new Error("Duplicate diff body");
+        const entry = pending.begin.entries.find((candidate) => candidate.path === body.path);
+        if (!entry?.body) throw new Error("Unexpected diff body");
+        pending.bodies.set(body.path, body);
+      }
+      return;
+    }
+    this.pending = null;
+    if (frame.error) {
+      this.committed = null;
+      this.publish({ phase: "error", revision: frame.revision, error: frame.error });
+      return;
+    }
+    const previous = new Map(this.committed?.files.map((file) => [file.path, file]));
+    const omitted = new Set(frame.omitted);
+    for (const path of omitted)
+      if (!pending.begin.entries.some((entry) => entry.path === path))
+        throw new Error("Unknown omitted diff path");
+    const files = pending.begin.entries.map((entry) => {
+      const old = previous.get(entry.path);
+      const body = pending.bodies.get(entry.path);
+      if (entry.content === "text" && !omitted.has(entry.path) && entry.body && !body)
+        throw new Error(`Missing diff body: ${entry.path}`);
+      if (
+        entry.content === "text" &&
+        !entry.body &&
+        !omitted.has(entry.path) &&
+        (!old || pending.begin.baseRevision === 0)
+      )
+        throw new Error(`Missing inherited diff: ${entry.path}`);
+      let file = materializeDiffFile(entry, body ?? null, omitted.has(entry.path));
+      if (entry.content === "text" && !entry.body && !omitted.has(entry.path) && old)
+        file = { ...file, hunks: old.hunks, status: old.status };
+      return old && sameFile(old, file) ? old : file;
+    });
+    const { revision, baseSha, headSha, mergeBaseSha } = pending.begin;
+    this.committed = {
+      phase: "ready",
+      revision,
+      resolved: { baseSha, headSha, mergeBaseSha },
+      files,
+      diffTooLarge: frame.diffTooLarge,
+    };
+    this.publish(this.committed);
+  }
+}
+function sameFile(a: ParsedDiffFile, b: ParsedDiffFile): boolean {
+  if (
+    a.path !== b.path ||
+    a.oldPath !== b.oldPath ||
+    a.isNew !== b.isNew ||
+    a.isDeleted !== b.isDeleted ||
+    a.additions !== b.additions ||
+    a.deletions !== b.deletions ||
+    a.status !== b.status
+  )
+    return false;
+  if (a.hunks === b.hunks) return true;
+  return JSON.stringify(a.hunks) === JSON.stringify(b.hunks);
+}

packages/client/src/index.ts

@@ -1212,3 +1212,5 @@ function createGeneratedClientId(): string {
       : Math.random().toString(36).slice(2);
   return `paseo-sdk-${randomId}`;
 }
+
+export type { DiffCompare, DiffState, DiffEntry, ResolvedShas } from "./diff/index.js";

packages/protocol/src/binary-frames/demux.ts

@@ -1,3 +1,4 @@
+import { decodeDiffFrame, DiffOpcode, type DiffFrame } from "./diff.js";
 import { HOST_ROUTE_OPCODE, decodeHostRouteFrame, type HostRouteFrame } from "./host-route.js";
 import {
   decodeFileTransferFrame,
@@ -12,12 +13,20 @@ import {
 } from "./terminal.js";
 
 export type BinaryFrame =
+  | { kind: "diff"; frame: DiffFrame }
   | { kind: "host_route"; frame: HostRouteFrame }
   | { kind: "terminal"; frame: TerminalStreamFrame }
   | { kind: "file_transfer"; frame: FileTransferFrame }
   | { kind: "plugin"; frame: PluginFrame };
 
 export function decodeBinaryFrame(bytes: Uint8Array): BinaryFrame | null {
+  if (Object.values(DiffOpcode).some((opcode) => opcode === bytes[0])) {
+    return { kind: "diff", frame: decodeDiffFrame(bytes) };
+  }
+  return decodeExistingBinaryFrame(bytes);
+}
+
+function decodeExistingBinaryFrame(bytes: Uint8Array): BinaryFrame | null {
   switch (bytes[0]) {
     case HOST_ROUTE_OPCODE: {
       const frame = decodeHostRouteFrame(bytes);

packages/protocol/src/binary-frames/diff.test.ts

@@ -0,0 +1,270 @@
+import { expect, test } from "vitest";
+import { decodeDiffFrame, encodeDiffFrame } from "./diff.js";
+import { decodeBinaryFrame } from "./demux.js";
+import { decodePluginFrame } from "./plugin.js";
+
+test("routes diff revisions independently of plugin frames", () => {
+  const frame = {
+    opcode: 0x40 as const,
+    slot: 0,
+    revision: 1,
+    baseRevision: 0,
+    baseSha: "",
+    headSha: "",
+    mergeBaseSha: "",
+    entries: [],
+  };
+  const bytes = encodeDiffFrame(frame);
+  expect([...bytes]).toEqual([64, 0, 1, 1, 0, 0, 0, 0, 0]);
+  expect(decodeDiffFrame(bytes)).toEqual(frame);
+  expect(decodeBinaryFrame(bytes)).toEqual({ kind: "diff", frame });
+  expect(decodePluginFrame(bytes)).toBeNull();
+});
+
+test("roundtrips Unicode runs and materializes the existing file shape", async () => {
+  const { materializeDiffFile } = await import("./diff.js");
+  const frame = {
+    opcode: 0x41 as const,
+    slot: 255,
+    revision: 128,
+    files: [
+      {
+        path: "é.ts",
+        hunks: [
+          {
+            oldStart: 1,
+            oldCount: 1,
+            newStart: 1,
+            newCount: 1,
+            lines: [
+              {
+                type: "add" as const,
+                content: "😀é",
+                runs: [
+                  { style: "string", length: 2 },
+                  { style: null, length: 2 },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+  expect(decodeDiffFrame(encodeDiffFrame(frame))).toEqual(frame);
+  const file = materializeDiffFile(
+    {
+      path: "é.ts",
+      oldPath: null,
+      change: "modified",
+      content: "text",
+      additions: 1,
+      deletions: 1,
+      body: true,
+    },
+    frame.files[0],
+    false,
+  );
+  expect(file.hunks[0].lines[0].tokens).toEqual([
+    { text: "😀", style: "string" },
+    { text: "é", style: null },
+  ]);
+});
+
+test("preserves binary additions, modifications, deletions and mode-only text", async () => {
+  const { materializeDiffFile } = await import("./diff.js");
+  for (const change of ["added", "modified", "deleted"] as const) {
+    const entry = {
+      path: "image.png",
+      oldPath: null,
+      change,
+      content: "binary" as const,
+      additions: 0,
+      deletions: 0,
+      body: false,
+    };
+    const begin = {
+      opcode: 0x40 as const,
+      slot: 1,
+      revision: 1,
+      baseRevision: 0,
+      baseSha: "",
+      headSha: "",
+      mergeBaseSha: "",
+      entries: [entry],
+    };
+    expect(decodeDiffFrame(encodeDiffFrame(begin))).toEqual(begin);
+    expect(materializeDiffFile(entry, null, false)).toEqual({
+      path: "image.png",
+      isNew: change === "added",
+      isDeleted: change === "deleted",
+      additions: 0,
+      deletions: 0,
+      status: "binary",
+      hunks: [],
+    });
+  }
+  expect(
+    materializeDiffFile(
+      {
+        path: "script",
+        oldPath: null,
+        change: "modified",
+        content: "text",
+        additions: 0,
+        deletions: 0,
+        body: true,
+      },
+      { path: "script", hunks: [] },
+      false,
+    ),
+  ).toEqual({
+    path: "script",
+    isNew: false,
+    isDeleted: false,
+    additions: 0,
+    deletions: 0,
+    status: "ok",
+    hunks: [],
+  });
+});
+
+test("rejects every truncated prefix, unknown version, trailing data, and invalid coverage", () => {
+  const end = {
+    opcode: 0x42 as const,
+    slot: 1,
+    revision: 9007199254740991,
+    diffTooLarge: true,
+    omitted: ["a.ts"],
+    error: { code: "REF_NOT_FOUND" as const, message: "missing" },
+  };
+  const bytes = encodeDiffFrame(end);
+  expect(decodeDiffFrame(bytes)).toEqual(end);
+  for (let length = 0; length < bytes.length; length++)
+    expect(() => decodeDiffFrame(bytes.slice(0, length))).toThrow();
+  const version = bytes.slice();
+  version[2] = 2;
+  expect(() => decodeDiffFrame(version)).toThrow("version");
+  expect(() => decodeDiffFrame(Uint8Array.from([...bytes, 0]))).toThrow("Trailing");
+  expect(() =>
+    encodeDiffFrame({
+      opcode: 0x41,
+      slot: 1,
+      revision: 1,
+      files: [
+        {
+          path: "x",
+          hunks: [
+            {
+              oldStart: 0,
+              oldCount: 0,
+              newStart: 1,
+              newCount: 1,
+              lines: [{ type: "add", content: "😀", runs: [{ style: null, length: 1 }] }],
+            },
+          ],
+        },
+      ],
+    }),
+  ).toThrow("cover");
+});
+
+test("uses fixed UTF-8 byte vectors while runs count UTF-16 units", () => {
+  const bytes = Uint8Array.from([
+    65, 0, 1, 1, 1, 1, 120, 1, 0, 0, 1, 1, 1, 129, 7, 240, 159, 152, 128, 101, 204, 129, 1, 3, 4,
+  ]);
+  const frame = {
+    opcode: 0x41 as const,
+    slot: 0,
+    revision: 1,
+    files: [
+      {
+        path: "x",
+        hunks: [
+          {
+            oldStart: 0,
+            oldCount: 0,
+            newStart: 1,
+            newCount: 1,
+            lines: [
+              { type: "add" as const, content: "😀é", runs: [{ style: "string", length: 4 }] },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+  expect(encodeDiffFrame(frame)).toEqual(bytes);
+  expect(decodeDiffFrame(bytes)).toEqual(frame);
+  const unknownStyle = bytes.slice();
+  unknownStyle[23] = 255;
+  expect(decodeDiffFrame(unknownStyle)).toEqual({
+    ...frame,
+    files: [
+      {
+        ...frame.files[0],
+        hunks: [
+          {
+            ...frame.files[0].hunks[0],
+            lines: [{ type: "add", content: "😀é", runs: [{ style: null, length: 4 }] }],
+          },
+        ],
+      },
+    ],
+  });
+});
+
+test("roundtrips generated entry lists across varint boundaries", () => {
+  for (const revision of [0, 1, 127, 128, 16383, 16384, 4294967296, Number.MAX_SAFE_INTEGER]) {
+    const entries = Array.from({ length: 130 }, (_, index) => ({
+      path: `src/${index}-😀.ts`,
+      oldPath: `old/${index}.ts`,
+      change: "renamed" as const,
+      content: "text" as const,
+      additions: index * 128,
+      deletions: index,
+      body: true,
+    }));
+    const begin = {
+      opcode: 0x40 as const,
+      slot: 255,
+      revision,
+      baseRevision: 0,
+      baseSha: "base",
+      headSha: "head",
+      mergeBaseSha: "merge",
+      entries,
+    };
+    expect(decodeDiffFrame(encodeDiffFrame(begin))).toEqual(begin);
+  }
+});
+
+test.each([true, false])(
+  "preserves BOM-prefixed paths and source lines with runs=%s",
+  (highlight) => {
+    const frame = {
+      opcode: 0x41 as const,
+      slot: 0,
+      revision: 1,
+      files: [
+        {
+          path: "\uFEFFbom.ts",
+          hunks: [
+            {
+              oldStart: 1,
+              oldCount: 1,
+              newStart: 1,
+              newCount: 1,
+              lines: (["add", "remove", "context"] as const).map((type) => ({
+                type,
+                content: "\uFEFFvalue",
+                runs: highlight ? [{ style: null, length: 6 }] : undefined,
+              })),
+            },
+          ],
+        },
+      ],
+    };
+    expect(decodeDiffFrame(encodeDiffFrame(frame))).toEqual(frame);
+  },
+);

packages/protocol/src/binary-frames/diff.ts

@@ -0,0 +1,360 @@
+import type { ParsedDiffFile } from "../messages.js";
+
+// Opcodes 0x40–0x4f are reserved for diff revisions. Plugins own 0x20–0x2f.
+export const DiffOpcode = { Begin: 0x40, Bodies: 0x41, End: 0x42 } as const;
+export const DIFF_HIGHLIGHT_STYLES = [
+  null,
+  "keyword",
+  "comment",
+  "string",
+  "number",
+  "literal",
+  "function",
+  "definition",
+  "class",
+  "type",
+  "tag",
+  "attribute",
+  "property",
+  "variable",
+  "operator",
+  "punctuation",
+  "regexp",
+  "escape",
+  "meta",
+  "heading",
+  "link",
+] as const;
+const CHANGES = ["added", "modified", "deleted", "renamed"] as const;
+const CONTENTS = ["text", "binary"] as const;
+const KINDS = ["context", "add", "remove", "header"] as const;
+const ERRORS = [
+  null,
+  "NOT_GIT_REPO",
+  "REF_NOT_FOUND",
+  "INVALID_COMPARE",
+  "TOO_MANY_SUBSCRIPTIONS",
+  "UNKNOWN",
+] as const;
+export interface DiffEntry {
+  path: string;
+  oldPath: string | null;
+  change: (typeof CHANGES)[number];
+  content: (typeof CONTENTS)[number];
+  additions: number;
+  deletions: number;
+  body: boolean;
+}
+export interface DiffRun {
+  style: string | null;
+  length: number;
+}
+export interface DiffStreamLine {
+  type: (typeof KINDS)[number];
+  content: string;
+  runs?: DiffRun[];
+}
+export interface DiffStreamHunk {
+  oldStart: number;
+  oldCount: number;
+  newStart: number;
+  newCount: number;
+  lines: DiffStreamLine[];
+}
+export interface DiffBody {
+  path: string;
+  hunks: DiffStreamHunk[];
+}
+export interface DiffBegin {
+  opcode: typeof DiffOpcode.Begin;
+  slot: number;
+  revision: number;
+  baseRevision: number;
+  baseSha: string;
+  headSha: string;
+  mergeBaseSha: string;
+  entries: DiffEntry[];
+}
+export interface DiffBodies {
+  opcode: typeof DiffOpcode.Bodies;
+  slot: number;
+  revision: number;
+  files: DiffBody[];
+}
+export interface DiffEnd {
+  opcode: typeof DiffOpcode.End;
+  slot: number;
+  revision: number;
+  diffTooLarge: boolean;
+  omitted: string[];
+  error: { code: NonNullable<(typeof ERRORS)[number]>; message: string } | null;
+}
+export type DiffFrame = DiffBegin | DiffBodies | DiffEnd;
+export class InvalidDiffFrameError extends Error {}
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+
+class Writer {
+  private bytes: number[] = [];
+  byte(value: number): void {
+    if (!Number.isInteger(value) || value < 0 || value > 255)
+      throw new InvalidDiffFrameError("Invalid byte");
+    this.bytes.push(value);
+  }
+  uint(value: number): void {
+    if (!Number.isSafeInteger(value) || value < 0)
+      throw new InvalidDiffFrameError("Invalid unsigned integer");
+    do {
+      const next = value % 128;
+      value = Math.floor(value / 128);
+      this.byte(next + (value ? 128 : 0));
+    } while (value);
+  }
+  str(value: string): void {
+    const bytes = textEncoder.encode(value);
+    this.uint(bytes.length);
+    for (const byte of bytes) this.byte(byte);
+  }
+  finish(): Uint8Array {
+    return Uint8Array.from(this.bytes);
+  }
+}
+class Reader {
+  private offset = 0;
+  constructor(private bytes: Uint8Array) {}
+  byte(): number {
+    if (this.offset >= this.bytes.length) throw new InvalidDiffFrameError("Truncated diff frame");
+    return this.bytes[this.offset++];
+  }
+  uint(): number {
+    let value = 0;
+    let factor = 1;
+    for (let index = 0; index < 8; index++) {
+      const byte = this.byte();
+      value += (byte & 127) * factor;
+      if (!Number.isSafeInteger(value)) throw new InvalidDiffFrameError("Integer overflow");
+      if (byte < 128) return value;
+      factor *= 128;
+    }
+    throw new InvalidDiffFrameError("Invalid varint");
+  }
+  count(): number {
+    const value = this.uint();
+    if (value > this.bytes.length - this.offset)
+      throw new InvalidDiffFrameError("Count exceeds frame");
+    return value;
+  }
+  str(): string {
+    const size = this.count();
+    const start = this.offset;
+    this.offset += size;
+    try {
+      return textDecoder.decode(this.bytes.subarray(start, this.offset));
+    } catch {
+      throw new InvalidDiffFrameError("Invalid UTF-8");
+    }
+  }
+  done(): void {
+    if (this.offset !== this.bytes.length) throw new InvalidDiffFrameError("Trailing bytes");
+  }
+}
+function enumAt<T>(values: readonly T[], index: number): T {
+  if (index >= values.length) throw new InvalidDiffFrameError("Unknown enum value");
+  return values[index];
+}
+function validateRuns(line: DiffStreamLine): void {
+  if (!line.runs) return;
+  let length = 0;
+  for (const run of line.runs) {
+    if (!Number.isSafeInteger(run.length) || run.length <= 0)
+      throw new InvalidDiffFrameError("Invalid run length");
+    length += run.length;
+  }
+  if (length !== line.content.length) throw new InvalidDiffFrameError("Runs do not cover line");
+}
+function writeLine(writer: Writer, line: DiffStreamLine): void {
+  validateRuns(line);
+  writer.byte(KINDS.indexOf(line.type) | (line.runs ? 128 : 0));
+  writer.str(line.content);
+  writer.uint(line.runs ? line.runs.length : 0);
+  for (const run of line.runs ?? []) {
+    const style = DIFF_HIGHLIGHT_STYLES.findIndex((value) => value === run.style);
+    writer.byte(Math.max(0, style));
+    writer.uint(run.length);
+  }
+}
+function readLine(reader: Reader): DiffStreamLine {
+  const flags = reader.byte();
+  const type = enumAt(KINDS, flags & 127);
+  const content = reader.str();
+  const count = reader.count();
+  const runs: DiffRun[] = [];
+  for (let index = 0; index < count; index++) {
+    const styleIndex = reader.byte();
+    const style = DIFF_HIGHLIGHT_STYLES[styleIndex] ?? null;
+    runs.push({ style, length: reader.uint() });
+  }
+  if (!(flags & 128)) {
+    if (count) throw new InvalidDiffFrameError("Runs without flag");
+    return { type, content };
+  }
+  const line = { type, content, runs };
+  validateRuns(line);
+  return line;
+}
+export function encodeDiffFrame(frame: DiffFrame): Uint8Array {
+  const writer = new Writer();
+  writer.byte(frame.opcode);
+  writer.byte(frame.slot);
+  writer.byte(1);
+  writer.uint(frame.revision);
+  if (frame.opcode === DiffOpcode.Begin) {
+    writer.uint(frame.baseRevision);
+    writer.str(frame.baseSha);
+    writer.str(frame.headSha);
+    writer.str(frame.mergeBaseSha);
+    writer.uint(frame.entries.length);
+    for (const entry of frame.entries) {
+      if (entry.content === "binary" && entry.body)
+        throw new InvalidDiffFrameError("Binary entry has a body");
+      writer.str(entry.path);
+      writer.str(entry.oldPath ?? "");
+      writer.byte(CHANGES.indexOf(entry.change));
+      writer.byte(CONTENTS.indexOf(entry.content));
+      writer.uint(entry.additions);
+      writer.uint(entry.deletions);
+      writer.byte(Number(entry.body));
+    }
+  } else if (frame.opcode === DiffOpcode.Bodies) {
+    writer.uint(frame.files.length);
+    for (const file of frame.files) {
+      writer.str(file.path);
+      writer.uint(file.hunks.length);
+      for (const hunk of file.hunks) {
+        writer.uint(hunk.oldStart);
+        writer.uint(hunk.oldCount);
+        writer.uint(hunk.newStart);
+        writer.uint(hunk.newCount);
+        writer.uint(hunk.lines.length);
+        for (const line of hunk.lines) writeLine(writer, line);
+      }
+    }
+  } else {
+    writer.byte(Number(frame.diffTooLarge));
+    writer.uint(frame.omitted.length);
+    for (const path of frame.omitted) writer.str(path);
+    writer.byte(frame.error ? ERRORS.indexOf(frame.error.code) : 0);
+    writer.str(frame.error ? frame.error.message : "");
+  }
+  return writer.finish();
+}
+export function decodeDiffFrame(bytes: Uint8Array): DiffFrame {
+  const reader = new Reader(bytes);
+  const opcode = reader.byte();
+  const slot = reader.byte();
+  if (reader.byte() !== 1) throw new InvalidDiffFrameError("Unknown diff version");
+  const revision = reader.uint();
+  let frame: DiffFrame;
+  if (opcode === DiffOpcode.Begin) {
+    const baseRevision = reader.uint();
+    const baseSha = reader.str();
+    const headSha = reader.str();
+    const mergeBaseSha = reader.str();
+    const count = reader.count();
+    const entries: DiffEntry[] = [];
+    for (let index = 0; index < count; index++) {
+      const path = reader.str();
+      const oldPath = reader.str() || null;
+      const change = enumAt(CHANGES, reader.byte());
+      const content = enumAt(CONTENTS, reader.byte());
+      const additions = reader.uint();
+      const deletions = reader.uint();
+      const bodyByte = reader.byte();
+      if (bodyByte > 1 || (content === "binary" && bodyByte))
+        throw new InvalidDiffFrameError("Invalid entry body");
+      entries.push({ path, oldPath, change, content, additions, deletions, body: bodyByte === 1 });
+    }
+    frame = { opcode, slot, revision, baseRevision, baseSha, headSha, mergeBaseSha, entries };
+  } else if (opcode === DiffOpcode.Bodies) {
+    const count = reader.count();
+    const files: DiffBody[] = [];
+    for (let index = 0; index < count; index++) {
+      const path = reader.str();
+      const hunkCount = reader.count();
+      const hunks: DiffStreamHunk[] = [];
+      for (let h = 0; h < hunkCount; h++) {
+        const oldStart = reader.uint();
+        const oldCount = reader.uint();
+        const newStart = reader.uint();
+        const newCount = reader.uint();
+        const lineCount = reader.count();
+        const lines: DiffStreamLine[] = [];
+        for (let l = 0; l < lineCount; l++) lines.push(readLine(reader));
+        hunks.push({ oldStart, oldCount, newStart, newCount, lines });
+      }
+      files.push({ path, hunks });
+    }
+    frame = { opcode, slot, revision, files };
+  } else if (opcode === DiffOpcode.End) {
+    const flags = reader.byte();
+    if (flags > 1) throw new InvalidDiffFrameError("Unknown flags");
+    const count = reader.count();
+    const omitted: string[] = [];
+    for (let index = 0; index < count; index++) omitted.push(reader.str());
+    const code = enumAt(ERRORS, reader.byte());
+    const message = reader.str();
+    frame = {
+      opcode,
+      slot,
+      revision,
+      diffTooLarge: flags === 1,
+      omitted,
+      error: code ? { code, message } : null,
+    };
+  } else {
+    throw new InvalidDiffFrameError("Unknown diff opcode");
+  }
+  reader.done();
+  return frame;
+}
+export function runsToTokens(
+  line: DiffStreamLine,
+): NonNullable<ParsedDiffFile["hunks"][number]["lines"][number]["tokens"]> {
+  let offset = 0;
+  return (line.runs ?? []).map((run) => {
+    const text = line.content.slice(offset, offset + run.length);
+    offset += run.length;
+    return { text, style: run.style };
+  });
+}
+export function materializeDiffFile(
+  entry: DiffEntry,
+  body: DiffBody | null,
+  omitted: boolean,
+): ParsedDiffFile {
+  let status: "ok" | "binary" | "too_large" = "ok";
+  if (entry.content === "binary") status = "binary";
+  else if (omitted) status = "too_large";
+  const hunks = body
+    ? body.hunks.map((hunk) => ({
+        ...hunk,
+        lines: hunk.lines.map((line) => {
+          if (line.runs)
+            return { type: line.type, content: line.content, tokens: runsToTokens(line) };
+          return { type: line.type, content: line.content };
+        }),
+      }))
+    : [];
+  const file: ParsedDiffFile = {
+    path: entry.path,
+    isNew: entry.change === "added",
+    isDeleted: entry.change === "deleted",
+    additions: entry.additions,
+    deletions: entry.deletions,
+    hunks,
+    status,
+  };
+  if (entry.oldPath !== null) file.oldPath = entry.oldPath;
+  return file;
+}

packages/protocol/src/binary-frames/index.ts

@@ -3,3 +3,4 @@ export * from "./file-transfer.js";
 export * from "./terminal.js";
 export * from "./host-route.js";
 export * from "./plugin.js";
+export * from "./diff.js";

packages/protocol/src/messages.diff.test.ts

@@ -0,0 +1,24 @@
+import { expect, test } from "vitest";
+import { DiffSubscribeRequestSchema, DiffSubscribeResponseSchema } from "./messages.js";
+
+test("accepts explicit endpoints without changing legacy schemas", () => {
+  const request = {
+    type: "diff.subscribe.request",
+    requestId: "r",
+    cwd: "/repo",
+    base: { kind: "rev", rev: "v1" },
+    head: { kind: "worktree" },
+    mergeBase: true,
+    highlight: false,
+  };
+  expect(DiffSubscribeRequestSchema.parse(request)).toEqual(request);
+  expect(
+    DiffSubscribeRequestSchema.safeParse({ ...request, base: { kind: "unknown" } }).success,
+  ).toBe(false);
+  expect(
+    DiffSubscribeResponseSchema.safeParse({
+      type: "diff.subscribe.response",
+      payload: { requestId: "r", subscriptionId: "s", slot: 256, error: null },
+    }).success,
+  ).toBe(false);
+});

packages/protocol/src/messages.ts

@@ -2288,6 +2288,51 @@ const CheckoutDiffCompareSchema = z.object({
   ignoreWhitespace: z.boolean().optional(),
 });
 
+export const DiffEndpointSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("rev"), rev: z.string() }),
+  z.object({ kind: z.literal("index") }),
+  z.object({ kind: z.literal("worktree") }),
+  z.object({ kind: z.literal("empty") }),
+]);
+export const DiffErrorSchema = z.object({
+  code: z.enum([
+    "NOT_GIT_REPO",
+    "REF_NOT_FOUND",
+    "INVALID_COMPARE",
+    "TOO_MANY_SUBSCRIPTIONS",
+    "UNKNOWN",
+  ]),
+  message: z.string(),
+});
+export const DiffSubscribeRequestSchema = z.object({
+  type: z.literal("diff.subscribe.request"),
+  requestId: z.string(),
+  cwd: z.string(),
+  base: DiffEndpointSchema,
+  head: DiffEndpointSchema,
+  mergeBase: z.boolean().optional(),
+  ignoreWhitespace: z.boolean().optional(),
+  highlight: z.boolean().optional(),
+});
+// Unsubscribe is fire-and-forget; release has no correlated response.
+export const DiffUnsubscribeRequestSchema = z.object({
+  type: z.literal("diff.unsubscribe.request"),
+  subscriptionId: z.string(),
+});
+export const DiffSubscribeResponseSchema = z.object({
+  type: z.literal("diff.subscribe.response"),
+  payload: z.object({
+    requestId: z.string(),
+    subscriptionId: z.string(),
+    slot: z.number().int().min(0).max(255),
+    error: DiffErrorSchema.nullable(),
+  }),
+});
+export type DiffEndpoint = z.infer<typeof DiffEndpointSchema>;
+export type DiffError = z.infer<typeof DiffErrorSchema>;
+export type DiffSubscribeRequest = z.infer<typeof DiffSubscribeRequestSchema>;
+export type DiffSubscribeResponse = z.infer<typeof DiffSubscribeResponseSchema>;
+
 export const CheckoutStatusRequestSchema = z.object({
   type: z.literal("checkout_status_request"),
   cwd: z.string(),
@@ -3428,6 +3473,8 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
   AgentDetachRequestMessageSchema,
   AgentRewindRequestMessageSchema,
   AgentPermissionResponseMessageSchema,
+  DiffSubscribeRequestSchema,
+  DiffUnsubscribeRequestSchema,
   CheckoutStatusRequestSchema,
   CheckoutDiffGetRequestSchema,
   SubscribeCheckoutDiffRequestSchema,
@@ -3887,6 +3934,7 @@ export const ServerInfoStatusPayloadSchema = z
         selectiveAgentTimeline: z.boolean().optional(),
         explicitEventSubscriptions: z.boolean().optional(),
         ownedSubscriptions: z.boolean().optional(),
+        diffSubscription: z.boolean().optional(),
         binaryChunkingV1: z.boolean().optional(),
         workspaceSetupObservation: z.boolean().optional(),
         workspaceSortTimes: z.boolean().optional(),
@@ -4189,8 +4237,6 @@ 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(),
@@ -5430,6 +5476,7 @@ const CheckoutStatusCommonSchema = z.object({
   error: CheckoutErrorSchema.nullable(),
   requestId: z.string(),
   baseRefExact: z.string().nullable().optional(),
+  comparisonBaseRef: 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
@@ -7237,6 +7284,7 @@ export const SessionOutboundMessageSchema = z.discriminatedUnion("type", [
   AgentDeletedMessageSchema,
   AgentArchivedMessageSchema,
   CloseItemsResponseSchema,
+  DiffSubscribeResponseSchema,
   CheckoutStatusResponseSchema,
   CheckoutStatusUpdateSchema,
   CheckoutDiffGetResponseSchema,

packages/protocol/src/messages.workspaces.test.ts

@@ -634,26 +634,6 @@ 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",

packages/server/package.json

@@ -102,7 +102,8 @@
     "test:e2e:real": "npm run test:integration:real",
     "test:e2e:local": "npm run test:integration:local",
     "test:e2e:relay:live": "cross-env RUN_LIVE_RELAY_E2E=1 vitest run src/server/daemon-e2e/live-relay.real.e2e.test.ts --maxWorkers=1",
-    "test:e2e:ui": "vitest --ui e2e.test.ts"
+    "test:e2e:ui": "vitest --ui e2e.test.ts",
+    "measure:diff-subscriptions": "tsx scripts/measure-diff-subscriptions.ts"
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "^0.17.1",

packages/server/scripts/measure-diff-subscriptions.ts

@@ -0,0 +1,111 @@
+import { performance } from "node:perf_hooks";
+import { mkdir, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import {
+  encodeDiffFrame,
+  DiffOpcode,
+  type DiffFrame,
+} from "@getpaseo/protocol/binary-frames/index";
+import { DiffSubscriptions } from "../src/server/diff/index.js";
+import { createFileObserver } from "../src/server/file-observer/index.js";
+import { runGitCommand } from "../src/utils/run-git-command.js";
+import { parseAndHighlightDiff } from "../src/server/utils/diff-highlighter.js";
+import { validateWSOutboundMessage } from "@getpaseo/protocol/validation/ws-outbound";
+
+const cwd = resolve(import.meta.dirname, "../../..");
+const artifacts = resolve(cwd, ".artifacts/diff-subscription");
+await mkdir(artifacts, { recursive: true });
+const pinnedHead = "3ed57e9dd";
+const observer = createFileObserver();
+const engine = new DiffSubscriptions({
+  async requestWorkingTreeWatch(root, changed) {
+    const watch = await observer.subscribe(root, () => changed(), {
+      ignore: [resolve(root, ".git")],
+    });
+    return {
+      repoRoot: root,
+      unsubscribe: async () => {
+        await watch.unsubscribe();
+      },
+    };
+  },
+});
+try {
+  for (const count of [1, 30]) {
+    const [base, head] = await Promise.all([
+      runGitCommand(["rev-parse", `${pinnedHead}~${count}`], { cwd }),
+      runGitCommand(["rev-parse", pinnedHead], { cwd }),
+    ]);
+    const started = performance.now();
+    const frames: DiffFrame[] = [];
+    const encoded: Uint8Array[] = [];
+    const subscription = await engine.subscribe(
+      {
+        cwd,
+        base: { kind: "rev", rev: base.stdout.trim() },
+        head: { kind: "rev", rev: head.stdout.trim() },
+      },
+      async (frame) => {
+        frames.push(frame);
+        encoded.push(encodeDiffFrame(frame));
+      },
+    );
+    await subscription.start();
+    const coldMs = performance.now() - started;
+    await subscription.release();
+    const raw = await runGitCommand(["diff", base.stdout.trim(), head.stdout.trim()], {
+      cwd,
+      maxOutputBytes: 50 * 1024 * 1024,
+    });
+    const contentAt = async (sha: string, path: string) => {
+      const result = await runGitCommand(["show", `${sha}:${path}`], {
+        cwd,
+        acceptExitCodes: [0, 128],
+      });
+      return result.exitCode === 0 ? result.stdout : null;
+    };
+    const legacyFiles = await parseAndHighlightDiff(raw.stdout, cwd, {
+      getOldFileContent: (file) => contentAt(base.stdout.trim(), file.path),
+      getNewFileContent: (file) => contentAt(head.stdout.trim(), file.path),
+    });
+    const legacy = JSON.stringify({
+      type: "session",
+      message: {
+        type: "checkout_diff_update",
+        payload: { cwd, subscriptionId: "benchmark", files: legacyFiles, error: null },
+      },
+    });
+    const parseStart = performance.now();
+    const validation = validateWSOutboundMessage(JSON.parse(legacy));
+    if (!validation.success) throw validation.error;
+    const jsonParseValidationMs = performance.now() - parseStart;
+    const begin = frames.find((frame) => frame.opcode === DiffOpcode.Begin);
+    const end = frames.findLast((frame) => frame.opcode === DiffOpcode.End);
+    if (!begin || begin.opcode !== DiffOpcode.Begin || !end || end.opcode !== DiffOpcode.End)
+      throw new Error("Revision was not delimited");
+    if (end.error) throw new Error(end.error.message);
+    const metrics = {
+      pinnedHead: head.stdout.trim(),
+      count,
+      files: begin.entries.length,
+      rawPatchBytes: Buffer.byteLength(raw.stdout),
+      encodedBytes: encoded.reduce((sum, bytes) => sum + bytes.length, 0),
+      legacyJsonBytes: Buffer.byteLength(legacy),
+      coldMs,
+      jsonParseValidationMs,
+      omitted: end.omitted,
+    };
+    console.log(JSON.stringify(metrics));
+    await writeFile(
+      resolve(artifacts, `corpus-${count}.json`),
+      JSON.stringify({
+        metrics,
+        legacy,
+        frames: encoded.map((bytes) => Buffer.from(bytes).toString("base64")),
+      }),
+    );
+  }
+} finally {
+  await engine.close();
+  await observer.close();
+}

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,43 +1197,12 @@ 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())
@@ -1241,7 +1210,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();

packages/server/src/server/agent/tools/paseo-tools.ts

@@ -188,7 +188,6 @@ interface ProviderSummary {
 }
 
 const WorkspaceAutomationSummarySchema = z.object({
-  parentWorkspaceId: z.string().optional(),
   workspaceId: z.string(),
   projectId: z.string(),
   cwd: z.string(),
@@ -207,7 +206,6 @@ function toWorkspaceAutomationSummary(workspace: PersistedWorkspaceRecord) {
     kind: workspace.kind,
     title: workspace.title,
     background: workspace.background,
-    parentWorkspaceId: workspace.parentWorkspaceId,
   };
 }
 

packages/server/src/server/authorization/operation-permissions.ts

@@ -194,6 +194,8 @@ const INBOUND_PERMISSION = {
   stash_pop_request: "workspace.write",
   stash_save_request: "workspace.write",
   "checkout.diff.get.request": "workspace.read",
+  "diff.subscribe.request": "workspace.read",
+  "diff.unsubscribe.request": "workspace.read",
   subscribe_checkout_diff_request: "workspace.read",
   subscribe_terminal_request: "workspace.read",
   subscribe_terminals_request: "workspace.read",
@@ -437,6 +439,7 @@ const OUTBOUND_PERMISSION = {
   stash_save_response: "workspace.read",
   status: "daemon.read",
   "checkout.diff.get.response": "workspace.read",
+  "diff.subscribe.response": "workspace.read",
   subscribe_checkout_diff_response: "workspace.read",
   subscribe_terminal_response: "workspace.read",
   "terminal.rename.response": "workspace.write",

packages/server/src/server/checkout-diff-manager.test.ts

@@ -1,488 +1,253 @@
+import { execFileSync } from "node:child_process";
+import { mkdtemp, writeFile, rm, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import pino from "pino";
+import { expect, test } from "vitest";
+import { CheckoutDiffManager, type CheckoutDiffSnapshotPayload } from "./checkout-diff-manager.js";
 import { createWorkspaceRuntimeStore } from "./workspace-runtime-store/index.js";
-import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { createFileObserver } from "./file-observer/index.js";
 
-const { toCheckoutErrorMock } = vi.hoisted(() => ({
-  toCheckoutErrorMock: vi.fn((error: unknown) => ({
-    message: error instanceof Error ? error.message : String(error),
-  })),
-}));
-
-vi.mock("./checkout-git-utils.js", () => ({
-  toCheckoutError: toCheckoutErrorMock,
-}));
-
-import type pino from "pino";
-import { CheckoutDiffManager } from "./checkout-diff-manager.js";
-import type { WorkspaceGitRuntimeSnapshot, WorkspaceGitService } from "./workspace-git-service.js";
-
-interface Deferred<T> {
-  promise: Promise<T>;
-  resolve(value: T): void;
-}
-
-function createDeferred<T>(): Deferred<T> {
-  let resolve!: (value: T) => void;
-  const promise = new Promise<T>((resolvePromise) => {
-    resolve = resolvePromise;
-  });
-  return { promise, resolve };
-}
-
-function createWorkspaceSnapshot(
-  overrides?: Partial<WorkspaceGitRuntimeSnapshot["git"]>,
-): WorkspaceGitRuntimeSnapshot {
-  return {
-    cwd: "/tmp/repo",
-    git: {
-      isGit: true,
-      repoRoot: "/tmp/repo",
-      mainRepoRoot: null,
-      currentBranch: "feature",
-      remoteUrl: "https://github.com/acme/repo.git",
-      isPaseoOwnedWorktree: false,
-      isDirty: false,
-      baseRef: "main",
-      aheadBehind: { ahead: 1, behind: 0 },
-      aheadOfOrigin: 1,
-      behindOfOrigin: 0,
-      hasRemote: true,
-      diffStat: { additions: 1, deletions: 0 },
-      ...overrides,
-    },
-    forge: {
-      featuresEnabled: false,
-      authState: "no_remote",
-      pullRequest: null,
-      error: null,
-    },
-  };
-}
-
-function createPendingManager() {
-  const watches: Array<{
+async function withCheckout(
+  run: (input: {
     cwd: string;
-    onChange: () => void;
-    unsubscribeCalls: number;
-    resolve(): void;
-  }> = [];
-  const workspaceGitService = {
-    getCheckoutDiff: async () => ({ diff: "", structured: [] }),
-    getSnapshot: async () => createWorkspaceSnapshot(),
-
-    registerWorkspace: () => ({ unsubscribe: () => {} }),
-    requestWorkingTreeWatch: (cwd: string, onChange: () => void) => {
-      const pending = createDeferred<{ repoRoot: string | null; unsubscribe: () => void }>();
-      const watch = {
-        cwd,
-        onChange,
-        unsubscribeCalls: 0,
-        resolve: () => {
-          pending.resolve({
-            repoRoot: "/tmp/repo",
-            unsubscribe: () => {
-              watch.unsubscribeCalls += 1;
-            },
-          });
-        },
-      };
-      watches.push(watch);
-      return pending.promise;
-    },
-  };
-  const logger = { child: () => logger, warn: () => {} };
+    manager: CheckoutDiffManager;
+    git(...args: string[]): string;
+  }) => Promise<void>,
+): Promise<void> {
+  const cwd = await mkdtemp(join(tmpdir(), "legacy-diff-adapter-"));
+  const observer = createFileObserver();
+  const git = (...args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
   const manager = new CheckoutDiffManager({
+    logger: pino({ level: "silent" }),
+    paseoHome: cwd,
     workspaceRuntimeStore: createWorkspaceRuntimeStore(),
-    logger: logger as unknown as pino.Logger,
-    paseoHome: "/tmp/paseo-test",
-    workspaceGitService,
+    workspaceGitService: {
+      async requestWorkingTreeWatch(root, onChange) {
+        const subscription = await observer.subscribe(root, () => onChange(), {
+          ignore: [join(root, ".git")],
+        });
+        return {
+          repoRoot: root,
+          unsubscribe: async () => {
+            await subscription.unsubscribe();
+          },
+        };
+      },
+    },
   });
-  return { manager, watches };
+  try {
+    git("init", "-b", "main");
+    git("config", "user.email", "test@example.com");
+    git("config", "user.name", "Test");
+    await writeFile(join(cwd, "README"), "base\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "base");
+    await run({ cwd, manager, git });
+  } finally {
+    await manager.dispose();
+    await observer.close();
+    await rm(cwd, { recursive: true, force: true });
+  }
 }
 
-describe("CheckoutDiffManager", () => {
-  beforeEach(() => {
-    vi.useFakeTimers();
-    toCheckoutErrorMock.mockClear();
-  });
-
-  afterEach(() => {
-    vi.useRealTimers();
-  });
-
-  function createManager(options?: {
-    repoRoot?: string | null;
-    getCheckoutDiffImplementation?: ReturnType<typeof vi.fn>;
-  }) {
-    const unsubscribe = vi.fn();
-    const workspaceUnsubscribe = vi.fn();
-    let onChange: (() => void) | null = null;
-    let onWorkspaceSnapshot: ((snapshot: WorkspaceGitRuntimeSnapshot) => void) | null = null;
-    const mockRequestWorkingTreeWatch = vi.fn(async (_cwd: string, listener: () => void) => {
-      onChange = listener;
-      return {
-        repoRoot: options?.repoRoot === undefined ? "/tmp/repo" : options.repoRoot,
-        unsubscribe,
-      };
-    });
-
-    const workspaceGitService = {
-      subscribe: vi.fn(),
-
-      registerWorkspace: vi.fn(
-        (_params: { cwd: string }, listener: (snapshot: WorkspaceGitRuntimeSnapshot) => void) => {
-          onWorkspaceSnapshot = listener;
-          return { unsubscribe: workspaceUnsubscribe };
-        },
+test("legacy callers share one live comparison, receive edits, and release it", async () => {
+  await withCheckout(async ({ cwd, manager }) => {
+    await mkdir(join(cwd, "sub"));
+    await writeFile(join(cwd, "x.ts"), "const value = 1;\n");
+    const first: CheckoutDiffSnapshotPayload[] = [];
+    const second: CheckoutDiffSnapshotPayload[] = [];
+    const [a, b] = await Promise.all([
+      manager.subscribe({ cwd: join(cwd, "sub"), compare: { mode: "uncommitted" } }, (snapshot) =>
+        first.push(snapshot),
       ),
-      getSnapshot: vi.fn(async () => createWorkspaceSnapshot()),
-      getCheckoutDiff:
-        options?.getCheckoutDiffImplementation ?? vi.fn(async () => ({ diff: "", structured: [] })),
-      refresh: vi.fn(),
-      scheduleRefreshForCwd: vi.fn(),
-      requestWorkingTreeWatch: mockRequestWorkingTreeWatch,
-      dispose: vi.fn(),
-    };
-
-    const logger = {
-      child: () => logger,
-      warn: vi.fn(),
-    };
-
-    const manager = new CheckoutDiffManager({
-      workspaceRuntimeStore: createWorkspaceRuntimeStore(),
-      logger: logger as unknown as pino.Logger,
-      paseoHome: "/tmp/paseo-test",
-      workspaceGitService: workspaceGitService as unknown as WorkspaceGitService,
+      manager.subscribe({ cwd, compare: { mode: "uncommitted" } }, (snapshot) =>
+        second.push(snapshot),
+      ),
+    ]);
+    expect(a.initial.cwd).toBe(join(cwd, "sub"));
+    expect(a.initial.files).toEqual(b.initial.files);
+    expect(a.initial.files.map((file) => file.path)).toEqual(["x.ts"]);
+    expect(manager.getMetrics()).toMatchObject({
+      checkoutDiffTargetCount: 1,
+      checkoutDiffSubscriptionCount: 2,
     });
+    await writeFile(join(cwd, "x.ts"), "const value = 2;\n");
+    await expect.poll(() => first.length, { timeout: 10000 }).toBeGreaterThan(0);
+    expect(first.at(-1)?.files).toEqual(second.at(-1)?.files);
+    await a.unsubscribe();
+    await b.unsubscribe();
+    expect(manager.getMetrics().checkoutDiffTargetCount).toBe(0);
+  });
+}, 30_000);
 
-    return {
-      manager,
-      workspaceGitService,
-      mockRequestWorkingTreeWatch,
-      unsubscribe,
-      getOnChange: () => onChange,
-      getOnWorkspaceSnapshot: () => onWorkspaceSnapshot,
-      workspaceUnsubscribe,
-    };
-  }
-
-  test("subscribe requests a working tree watch with the correct cwd", async () => {
-    const { manager, mockRequestWorkingTreeWatch } = createManager();
-
-    await manager.subscribe(
-      {
-        cwd: "/tmp/repo/packages/server",
-        compare: { mode: "uncommitted" },
-      },
-      () => {},
+test("Committed ignores working-tree edits while All and Uncommitted include them", async () => {
+  await withCheckout(async ({ cwd, manager, git }) => {
+    git("checkout", "-b", "feature");
+    await writeFile(join(cwd, "x.ts"), "const value = 1;\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "feature");
+    await writeFile(join(cwd, "x.ts"), "const value = 2;\n");
+    const committed = await manager.read({ cwd, compare: { mode: "base", baseRef: "main" } });
+    const all = await manager.read({ cwd, compare: { mode: "all", baseRef: "main" } });
+    const uncommitted = await manager.read({ cwd, compare: { mode: "uncommitted" } });
+    expect(committed.files[0].hunks[0].lines).toContainEqual(
+      expect.objectContaining({ type: "add", content: "const value = 1;" }),
     );
-
-    expect(mockRequestWorkingTreeWatch).toHaveBeenCalledWith(
-      "/tmp/repo/packages/server",
-      expect.any(Function),
+    expect(all.files[0].hunks[0].lines).toContainEqual(
+      expect.objectContaining({ type: "add", content: "const value = 2;" }),
+    );
+    expect(uncommitted.files[0].hunks[0].lines).toContainEqual(
+      expect.objectContaining({ type: "remove", content: "const value = 1;" }),
     );
   });
+}, 30_000);
 
-  test("unsubscribe calls the working tree watch unsubscribe", async () => {
-    const { manager, unsubscribe } = createManager();
-
-    const subscription = await manager.subscribe(
-      {
-        cwd: "/tmp/repo/packages/server",
-        compare: { mode: "uncommitted" },
-      },
-      () => {},
-    );
-
-    subscription.unsubscribe();
-
-    expect(unsubscribe).toHaveBeenCalledTimes(1);
-  });
-
-  test("cancels a subscription while its working tree watch is still opening", async () => {
-    const { manager, watches } = createPendingManager();
+test("cancelling a legacy subscriber during a shared revision does not revive it", async () => {
+  await withCheckout(async ({ cwd, manager }) => {
+    await writeFile(join(cwd, "x.ts"), "export const value = 1;\n");
     const abort = new AbortController();
-
-    const pendingSubscription = manager.subscribe(
-      {
-        cwd: "/tmp/repo/packages/server",
-        compare: { mode: "uncommitted" },
-        signal: abort.signal,
+    let cancelled = false;
+    const modern = await manager.streams.subscribe(
+      { cwd, base: { kind: "rev", rev: "HEAD" }, head: { kind: "worktree" } },
+      async (frame) => {
+        if (frame.opcode !== 0x40 || cancelled) return;
+        await waitForSubscriberCount(manager, 2);
+        cancelled = true;
+        abort.abort();
       },
-      () => {},
     );
-    abort.abort();
-    watches[0].resolve();
-    await pendingSubscription;
-
-    expect(watches[0].unsubscribeCalls).toBe(1);
-    expect(manager.getMetrics()).toEqual({
-      checkoutDiffTargetCount: 0,
-      checkoutDiffSubscriptionCount: 0,
-      checkoutDiffWatcherCount: 0,
-      checkoutDiffFallbackRefreshTargetCount: 0,
-    });
-  });
-
-  test("shares one opening target between concurrent subscriptions", async () => {
-    const { manager, watches } = createPendingManager();
-
-    const firstSubscription = manager.subscribe(
-      { cwd: "/tmp/repo/packages/server", compare: { mode: "uncommitted" } },
-      () => {},
-    );
-    const secondSubscription = manager.subscribe(
-      { cwd: "/tmp/repo/packages/server", compare: { mode: "uncommitted" } },
-      () => {},
-    );
-
-    expect(watches).toHaveLength(1);
-    watches[0].resolve();
-    const [first, second] = await Promise.all([firstSubscription, secondSubscription]);
-    expect(manager.getMetrics().checkoutDiffSubscriptionCount).toBe(2);
-
-    first.unsubscribe();
-    expect(watches[0].unsubscribeCalls).toBe(0);
-    second.unsubscribe();
-    expect(watches[0].unsubscribeCalls).toBe(1);
-  });
-
-  test("diffCwd uses repoRoot from the working tree watch result", async () => {
-    const { manager, workspaceGitService } = createManager({ repoRoot: "/tmp/repo" });
-
-    await manager.subscribe(
-      {
-        cwd: "/tmp/repo/packages/server",
-        compare: { mode: "uncommitted" },
+    const legacy = manager.subscribe(
+      { cwd, compare: { mode: "uncommitted" }, signal: abort.signal },
+      () => {
+        throw new Error("Cancelled subscriber received an update");
       },
-      () => {},
     );
-
-    expect(workspaceGitService.getCheckoutDiff).toHaveBeenCalledWith(
-      "/tmp/repo",
-      expect.objectContaining({ mode: "uncommitted", includeStructured: true }),
-      undefined,
-    );
-  });
-
-  test("diff refresh is triggered when the working tree watch callback fires", async () => {
-    const getCheckoutDiff = vi
-      .fn()
-      .mockResolvedValueOnce({
-        diff: "",
-        structured: [{ path: "a.ts", additions: 1, deletions: 0, status: "modified" }],
-      })
-      .mockResolvedValueOnce({
-        diff: "",
-        structured: [{ path: "b.ts", additions: 2, deletions: 0, status: "modified" }],
+    try {
+      await modern.start();
+      const result = await legacy;
+      expect(result.initial).toMatchObject({
+        files: [],
+        error: { message: "Diff subscription cancelled" },
       });
-
-    const { manager, getOnChange } = createManager({
-      getCheckoutDiffImplementation: getCheckoutDiff,
-    });
-    const listener = vi.fn();
-
-    await manager.subscribe(
-      {
-        cwd: "/tmp/repo/packages/server",
-        compare: { mode: "uncommitted" },
-      },
-      listener,
-    );
-
-    const onChange = getOnChange();
-    expect(onChange).toBeTypeOf("function");
-
-    onChange?.();
-    await vi.advanceTimersByTimeAsync(150);
-
-    expect(listener).toHaveBeenCalledTimes(1);
-    expect(listener).toHaveBeenCalledWith({
-      cwd: "/tmp/repo/packages/server",
-      files: [{ path: "b.ts", additions: 2, deletions: 0, status: "modified" }],
-      error: null,
-    });
-  });
-
-  test("watch-triggered refresh forces a cache bypass on getCheckoutDiff", async () => {
-    const getCheckoutDiff = vi
-      .fn()
-      .mockResolvedValueOnce({
-        diff: "",
-        structured: [{ path: "a.ts", additions: 1, deletions: 0, status: "modified" }],
-      })
-      .mockResolvedValueOnce({
-        diff: "",
-        structured: [{ path: "b.ts", additions: 2, deletions: 0, status: "modified" }],
-      });
-
-    const { manager, getOnChange } = createManager({
-      getCheckoutDiffImplementation: getCheckoutDiff,
-    });
-
-    await manager.subscribe(
-      {
-        cwd: "/tmp/repo/packages/server",
-        compare: { mode: "uncommitted" },
-      },
-      vi.fn(),
-    );
-
-    expect(getCheckoutDiff).toHaveBeenNthCalledWith(
-      1,
-      "/tmp/repo",
-      expect.objectContaining({ mode: "uncommitted" }),
-      undefined,
-    );
-
-    const onChange = getOnChange();
-    onChange?.();
-    await vi.advanceTimersByTimeAsync(150);
-
-    expect(getCheckoutDiff).toHaveBeenCalledTimes(2);
-    const watchFiredCall = getCheckoutDiff.mock.calls[1];
-    expect(watchFiredCall[2]).toEqual({
-      force: true,
-      reason: expect.stringContaining("working-tree"),
-    });
-  });
-
-  test("an edit during an in-flight diff refresh produces one final follow-up", async () => {
-    const inFlightDiff = createDeferred<{
-      diff: string;
-      structured: Array<{
-        path: string;
-        additions: number;
-        deletions: number;
-        status: "modified";
-      }>;
-    }>();
-    const getCheckoutDiff = vi
-      .fn()
-      .mockResolvedValueOnce({
-        diff: "",
-        structured: [{ path: "tracked.ts", additions: 1, deletions: 0, status: "modified" }],
-      })
-      .mockImplementationOnce(() => inFlightDiff.promise)
-      .mockResolvedValue({
-        diff: "",
-        structured: [{ path: "tracked.ts", additions: 100, deletions: 25, status: "modified" }],
-      });
-    const { manager, getOnChange } = createManager({
-      getCheckoutDiffImplementation: getCheckoutDiff,
-    });
-    const listener = vi.fn();
-
-    await manager.subscribe({ cwd: "/tmp/repo", compare: { mode: "uncommitted" } }, listener);
-    getOnChange()?.();
-    await vi.advanceTimersByTimeAsync(150);
-    expect(getCheckoutDiff).toHaveBeenCalledTimes(2);
-
-    for (let event = 0; event < 100; event += 1) {
-      getOnChange()?.();
+      await result.unsubscribe();
+    } finally {
+      await modern.release();
     }
-    await vi.advanceTimersByTimeAsync(150);
-    expect(getCheckoutDiff).toHaveBeenCalledTimes(2);
-
-    inFlightDiff.resolve({
-      diff: "",
-      structured: [{ path: "tracked.ts", additions: 2, deletions: 1, status: "modified" }],
-    });
-    await vi.waitFor(() => {
-      expect(getCheckoutDiff).toHaveBeenCalledTimes(3);
-      expect(listener).toHaveBeenLastCalledWith({
-        cwd: "/tmp/repo",
-        files: [{ path: "tracked.ts", additions: 100, deletions: 25, status: "modified" }],
-        error: null,
-      });
-    });
   });
+}, 30_000);
 
-  test("base diff subscriptions ignore ordinary working tree edits", async () => {
-    const getCheckoutDiff = vi.fn(async () => ({
-      diff: "",
-      structured: [{ path: "committed.ts", additions: 1, deletions: 0, status: "modified" }],
-    }));
-    const { manager, getOnChange, mockRequestWorkingTreeWatch } = createManager({
-      getCheckoutDiffImplementation: getCheckoutDiff,
+async function waitForSubscriberCount(manager: CheckoutDiffManager, count: number): Promise<void> {
+  await expect
+    .poll(() => manager.getMetrics().checkoutDiffSubscriptionCount, { timeout: 10_000 })
+    .toBe(count);
+}
+
+test("moving a tag refreshes binary file metadata even though binary files have no bodies", async () => {
+  await withCheckout(async ({ cwd, manager, git }) => {
+    git("tag", "v1");
+    await writeFile(join(cwd, "image.bin"), Buffer.from([0, 1]));
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "binary");
+    await writeFile(join(cwd, "image.bin"), Buffer.from([0, 2]));
+    const updates: CheckoutDiffSnapshotPayload[] = [];
+    const subscription = await manager.subscribe(
+      { cwd, compare: { mode: "all", baseRef: "v1" } },
+      (snapshot) => updates.push(snapshot),
+    );
+    expect(subscription.initial.files[0]).toMatchObject({
+      path: "image.bin",
+      isNew: true,
+      status: "binary",
     });
-
-    await manager.subscribe(
-      { cwd: "/tmp/repo", compare: { mode: "base", baseRef: "main" } },
-      vi.fn(),
-    );
-    getOnChange()?.();
-    await vi.advanceTimersByTimeAsync(150);
-
-    expect(getCheckoutDiff).toHaveBeenCalledTimes(1);
-    expect(mockRequestWorkingTreeWatch).not.toHaveBeenCalled();
+    git("update-ref", "refs/tags/v1", "HEAD");
+    await expect.poll(() => updates.at(-1)?.files[0]?.isNew, { timeout: 10000 }).toBe(false);
+    await subscription.unsubscribe();
   });
+}, 30000);
 
-  test("base diff subscriptions ignore worktree-only workspace snapshot updates", async () => {
-    const getCheckoutDiff = vi.fn(async () => ({ diff: "", structured: [] }));
-    const { manager, getOnWorkspaceSnapshot } = createManager({
-      getCheckoutDiffImplementation: getCheckoutDiff,
+test("legacy diffs retain successful bodies when an oversized sibling is removed", async () => {
+  await withCheckout(async ({ cwd, manager }) => {
+    await writeFile(join(cwd, "a.ts"), "const value = 1;\n");
+    await writeFile(join(cwd, "b.txt"), "x".repeat(1024 * 1024 + 1));
+    const updates: CheckoutDiffSnapshotPayload[] = [];
+    const subscription = await manager.subscribe(
+      { cwd, compare: { mode: "uncommitted" } },
+      (snapshot) => updates.push(snapshot),
+    );
+    expect(subscription.initial.files).toMatchObject([
+      { path: "a.ts", status: "ok" },
+      { path: "b.txt", status: "too_large" },
+    ]);
+    await rm(join(cwd, "b.txt"));
+    await manager.scheduleRefreshForCwd(cwd);
+    await expect.poll(() => updates.at(-1)?.error).toBeNull();
+    expect(updates.at(-1)?.files[0]).toMatchObject({
+      path: "a.ts",
+      hunks: [
+        {
+          lines: expect.arrayContaining([expect.objectContaining({ content: "const value = 1;" })]),
+        },
+      ],
     });
-
-    await manager.subscribe(
-      { cwd: "/tmp/repo", compare: { mode: "base", baseRef: "main" } },
-      vi.fn(),
-    );
-
-    getOnWorkspaceSnapshot()?.(
-      createWorkspaceSnapshot({
-        isDirty: true,
-        diffStat: { additions: 5, deletions: 2 },
-      }),
-    );
-    await vi.advanceTimersByTimeAsync(150);
-
-    expect(getCheckoutDiff).toHaveBeenCalledTimes(1);
-  });
-
-  test("base diff subscriptions refresh for structural workspace changes", async () => {
-    const getCheckoutDiff = vi.fn(async () => ({ diff: "", structured: [] }));
-    const { manager, getOnWorkspaceSnapshot, workspaceGitService } = createManager({
-      getCheckoutDiffImplementation: getCheckoutDiff,
-    });
-
-    await manager.subscribe(
-      { cwd: "/tmp/repo", compare: { mode: "base", baseRef: "main" } },
-      vi.fn(),
-    );
-
-    expect(workspaceGitService.registerWorkspace).toHaveBeenCalledTimes(1);
-    getOnWorkspaceSnapshot()?.(
-      createWorkspaceSnapshot({
-        currentBranch: "feature-2",
-        isDirty: true,
-        diffStat: { additions: 5, deletions: 2 },
-      }),
-    );
-    await vi.advanceTimersByTimeAsync(150);
-    expect(getCheckoutDiff).toHaveBeenCalledTimes(2);
-    expect(getCheckoutDiff.mock.calls[1]?.[2]).toBeUndefined();
-
-    getOnWorkspaceSnapshot()?.(createWorkspaceSnapshot({ aheadBehind: { ahead: 2, behind: 0 } }));
-    await vi.advanceTimersByTimeAsync(150);
-    expect(getCheckoutDiff).toHaveBeenCalledTimes(3);
-  });
-
-  test("falls back to cwd when the working tree watch returns no repo root", async () => {
-    const { manager, workspaceGitService } = createManager({ repoRoot: null });
-
-    await manager.subscribe(
-      {
-        cwd: "/tmp/plain",
-        compare: { mode: "uncommitted" },
-      },
-      () => {},
-    );
-
-    expect(workspaceGitService.getCheckoutDiff).toHaveBeenCalledWith(
-      "/tmp/plain",
-      expect.objectContaining({ mode: "uncommitted", includeStructured: true }),
-      undefined,
-    );
+    subscription.unsubscribe();
   });
 });
+
+test("legacy subscriptions reselect the preferred base when a remote ref appears", async () => {
+  await withCheckout(async ({ cwd, manager, git }) => {
+    git("checkout", "-b", "feature");
+    await writeFile(join(cwd, "b.ts"), "export const b = 1;\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "feature");
+    const updates: CheckoutDiffSnapshotPayload[] = [];
+    const params = { cwd, compare: { mode: "base" as const, baseRef: "main" } };
+    const subscription = await manager.subscribe(params, (snapshot) => updates.push(snapshot));
+    try {
+      expect(subscription.initial.files.map((file) => file.path)).toEqual(["b.ts"]);
+      git("update-ref", "refs/remotes/origin/main", "HEAD");
+      await manager.scheduleRefreshForCwd(cwd);
+      await expect.poll(() => updates.at(-1)?.files.length, { timeout: 5000 }).toBe(0);
+      expect(updates.at(-1)).toEqual(await manager.read(params));
+    } finally {
+      await subscription.unsubscribe();
+    }
+  });
+});
+
+test("cold many-file reads batch Git patches while matching the legacy reader", async () => {
+  const { getCheckoutDiff } = await import("../utils/checkout-git.js");
+  const { startGitCommandMetrics, stopGitCommandMetrics } =
+    await import("../utils/run-git-command.js");
+  await withCheckout(async ({ cwd, manager, git }) => {
+    const count = 1000;
+    for (let index = 0; index < count; index++)
+      await writeFile(join(cwd, `file-${index}.ts`), "export const value = 0;\n");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-m", "many files");
+    for (let index = 0; index < count; index++)
+      await writeFile(join(cwd, `file-${index}.ts`), "export const value = 1;\n");
+    const legacyStart = performance.now();
+    const legacy = await getCheckoutDiff(cwd, { mode: "uncommitted", includeStructured: true });
+    const legacyMs = performance.now() - legacyStart;
+    startGitCommandMetrics();
+    const streamedStart = performance.now();
+    const streamed = await manager.read({ cwd, compare: { mode: "uncommitted" } });
+    const streamedMs = performance.now() - streamedStart;
+    const metrics = stopGitCommandMetrics();
+    const patches = metrics.commands.filter((command) => command.args.includes("--patch"));
+    const artifactDirectory = join(import.meta.dirname, "../../../../.artifacts/diff-subscription");
+    await mkdir(artifactDirectory, { recursive: true });
+    await writeFile(
+      join(artifactDirectory, "cold-many-file-metrics.json"),
+      JSON.stringify({ count, legacyMs, streamedMs, patchCommands: patches.length }, null, 2),
+    );
+    expect(streamed.error).toBeNull();
+    expect(streamed.files).toHaveLength(count);
+    expect(legacy.structured).toHaveLength(count);
+    expect(streamed.files.map((file) => [file.path, file.hunks])).toEqual(
+      legacy.structured?.map((file) => [file.path, file.hunks]),
+    );
+    expect(patches.length).toBeLessThanOrEqual(Math.ceil(count / 64));
+  });
+}, 60000);

packages/server/src/server/checkout-diff-manager.ts

@@ -1,400 +1,201 @@
-import { type WorkspaceRuntimeStore } from "./workspace-runtime-store/index.js";
 import type pino from "pino";
 import type { SubscribeCheckoutDiffRequest, SessionOutboundMessage } from "./messages.js";
-import type { WorkspaceGitRuntimeSnapshot, WorkspaceGitService } from "./workspace-git-service.js";
+import type { WorkspaceGitService } from "./workspace-git-service.js";
+import type { WorkspaceRuntimeStore } from "./workspace-runtime-store/index.js";
+import { DiffSubscriptions, type CommitFileRead } from "./diff/index.js";
+import {
+  DiffOpcode,
+  materializeDiffFile,
+  type DiffFrame,
+  type DiffBegin,
+  type DiffBody,
+} from "@getpaseo/protocol/binary-frames/index";
+import type { ParsedDiffFile } from "@getpaseo/protocol/messages";
+import {
+  CHECKOUT_DIFF_MAX_STRUCTURED_BYTES,
+  resolveCheckoutDiffBase,
+} from "../utils/checkout-git.js";
 import { expandTilde } from "../utils/path.js";
 import { toCheckoutError } from "./checkout-git-utils.js";
 
-const CHECKOUT_DIFF_WATCH_DEBOUNCE_MS = 150;
-
-type CheckoutDiffWorkspace = Pick<
-  WorkspaceGitService,
-  "getCheckoutDiff" | "getSnapshot" | "registerWorkspace" | "requestWorkingTreeWatch"
->;
-
 export type CheckoutDiffCompareInput = SubscribeCheckoutDiffRequest["compare"];
-
 export type CheckoutDiffSnapshotPayload = Omit<
   Extract<SessionOutboundMessage, { type: "checkout_diff_update" }>["payload"],
   "subscriptionId"
 >;
-
 export interface CheckoutDiffMetrics {
   checkoutDiffTargetCount: number;
   checkoutDiffSubscriptionCount: number;
   checkoutDiffWatcherCount: number;
   checkoutDiffFallbackRefreshTargetCount: number;
 }
-
-interface CheckoutDiffWatchTarget {
-  key: string;
-  cwd: string;
-  diffCwd: string;
-  compare: CheckoutDiffCompareInput;
-  listeners: Set<(snapshot: CheckoutDiffSnapshotPayload) => void>;
-  workingTreeWatchUnsubscribe: (() => void) | null;
-  workspaceGitUnsubscribe: (() => void) | null;
-  latestWorkspaceStructureFingerprint: string | null;
-  latestWorkspaceWorktreeFingerprint: string | null;
-  latestWorkspaceForgeFingerprint: string | null;
-  debounceTimer: NodeJS.Timeout | null;
-  pendingDebounceForce: boolean;
-  refreshPromise: Promise<void> | null;
-  refreshQueued: boolean;
-  refreshQueuedForce: boolean;
-  latestPayload: CheckoutDiffSnapshotPayload | null;
-  latestFingerprint: string | null;
-  openPromise: Promise<void> | null;
-}
-
 export interface CheckoutDiffSubscriptionRequest {
   cwd: string;
   compare: CheckoutDiffCompareInput;
   signal?: AbortSignal;
 }
-
 export interface CheckoutDiffSubscription {
   initial: CheckoutDiffSnapshotPayload;
-  unsubscribe: () => void;
+  unsubscribe(): void;
 }
 
+// COMPAT(diffSubscription): added in v0.15.0, remove after 2027-05-06.
+// Old clients receive the same JSON snapshot while the shared engine owns reads and observation.
 export class CheckoutDiffManager {
-  private readonly workspaceGitService: CheckoutDiffWorkspace;
-  private readonly workspaceRuntimeStore: WorkspaceRuntimeStore;
-  private readonly targets = new Map<string, CheckoutDiffWatchTarget>();
-
+  readonly streams: DiffSubscriptions;
+  private readonly paseoHome: string;
   constructor(options: {
     logger: pino.Logger;
     paseoHome: string;
-    workspaceGitService: CheckoutDiffWorkspace;
+    workspaceGitService: Pick<WorkspaceGitService, "requestWorkingTreeWatch">;
     workspaceRuntimeStore: WorkspaceRuntimeStore;
   }) {
-    this.workspaceGitService = options.workspaceGitService;
-    this.workspaceRuntimeStore = options.workspaceRuntimeStore;
+    this.streams = new DiffSubscriptions(options.workspaceGitService);
+    this.paseoHome = options.paseoHome;
+  }
+  readCommitFile(input: CommitFileRead) {
+    return this.streams.readCommitFile(input);
   }
-
   async read(
     params: Omit<CheckoutDiffSubscriptionRequest, "signal">,
   ): Promise<CheckoutDiffSnapshotPayload> {
-    return this.computeCheckoutDiffSnapshot(params.cwd, this.normalizeCompare(params.compare));
+    const subscription = await this.subscribe(params, () => {});
+    await subscription.unsubscribe();
+    return subscription.initial;
   }
-
   async subscribe(
     params: CheckoutDiffSubscriptionRequest,
     listener: (snapshot: CheckoutDiffSnapshotPayload) => void,
   ): Promise<CheckoutDiffSubscription> {
-    const cwd = params.cwd;
-    const compare = this.normalizeCompare(params.compare);
-    const target = this.ensureTarget(cwd, compare);
-    target.listeners.add(listener);
-    target.openPromise ??= this.openTarget(target);
-
-    let isSubscribed = true;
-    const unsubscribe = () => {
-      if (!isSubscribed) {
+    const cwd = expandTilde(params.cwd);
+    let resolveInitial!: (snapshot: CheckoutDiffSnapshotPayload) => void;
+    const initial = new Promise<CheckoutDiffSnapshotPayload>((resolve) => {
+      resolveInitial = resolve;
+    });
+    let delivered = false;
+    let pending: DiffBegin | null = null;
+    let files = new Map<string, ParsedDiffFile>();
+    let bodies = new Map<string, DiffBody>();
+    const receive = async (frame: DiffFrame) => {
+      if (params.signal?.aborted) return;
+      if (frame.opcode === DiffOpcode.Begin) {
+        pending = frame;
+        bodies = new Map();
         return;
       }
-      isSubscribed = false;
-      params.signal?.removeEventListener("abort", unsubscribe);
-      this.removeListener(target, listener);
-    };
-    params.signal?.addEventListener("abort", unsubscribe, { once: true });
-    if (params.signal?.aborted) {
-      unsubscribe();
-    }
-
-    try {
-      await target.openPromise;
-      const initial =
-        target.latestPayload ??
-        (await this.computeCheckoutDiffSnapshot(target.cwd, target.compare, {
-          diffCwd: target.diffCwd,
-        }));
-      target.latestPayload = initial;
-      target.latestFingerprint = JSON.stringify(initial);
-      return { initial, unsubscribe };
-    } catch (error) {
-      unsubscribe();
-      throw error;
-    }
-  }
-
-  scheduleRefreshForCwd(cwd: string): void {
-    const resolvedCwd = expandTilde(cwd);
-    for (const target of this.targets.values()) {
-      if (target.cwd !== resolvedCwd && target.diffCwd !== resolvedCwd) {
-        continue;
+      if (!pending || frame.revision !== pending.revision) return;
+      if (frame.opcode === DiffOpcode.Bodies) {
+        for (const body of frame.files) bodies.set(body.path, body);
+        return;
       }
-      this.scheduleTargetRefresh(target);
+      let payload: CheckoutDiffSnapshotPayload;
+      if (frame.error) {
+        const message = frame.error.message;
+        payload = {
+          cwd,
+          files: [],
+          error: toCheckoutError(new Error(message)),
+          diffTooLarge: frame.diffTooLarge,
+        };
+        files.clear();
+      } else {
+        const next = new Map<string, ParsedDiffFile>();
+        const omitted = new Set(frame.omitted);
+        for (const entry of pending.entries) {
+          const previous = pending.baseRevision ? files.get(entry.path) : undefined;
+          const body = bodies.get(entry.path) ?? null;
+          const file = materializeDiffFile(entry, body, omitted.has(entry.path));
+          if (!entry.body && previous && entry.content === "text" && !omitted.has(entry.path))
+            file.hunks = previous.hunks;
+          next.set(entry.path, file);
+        }
+        files = next;
+        // Stream omissions remain file placeholders; the JSON budget rejects a legacy snapshot.
+        payload = legacySnapshot(cwd, [...next.values()]);
+      }
+      pending = null;
+      if (delivered) listener(payload);
+      else {
+        delivered = true;
+        resolveInitial(payload);
+      }
+    };
+    try {
+      const baseRef = await resolveCheckoutDiffBase(cwd, params.compare, {
+        paseoHome: this.paseoHome,
+      });
+      if (!baseRef) return { initial: { cwd, files: [], error: null }, unsubscribe() {} };
+      const subscription = await this.streams.subscribe(
+        {
+          cwd,
+          base: { kind: "rev", rev: baseRef },
+          checkoutBase:
+            params.compare.mode === "uncommitted"
+              ? undefined
+              : { compare: params.compare, paseoHome: this.paseoHome },
+          head:
+            params.compare.mode === "base" ? { kind: "rev", rev: "HEAD" } : { kind: "worktree" },
+          mergeBase: params.compare.mode !== "uncommitted",
+          ignoreWhitespace: params.compare.ignoreWhitespace,
+        },
+        receive,
+      );
+      const unsubscribe = async () => {
+        if (!delivered) {
+          delivered = true;
+          resolveInitial({
+            cwd,
+            files: [],
+            error: toCheckoutError(new Error("Diff subscription cancelled")),
+          });
+        }
+        params.signal?.removeEventListener("abort", unsubscribe);
+        await subscription.release();
+      };
+      params.signal?.addEventListener("abort", unsubscribe, { once: true });
+      if (params.signal?.aborted) {
+        await subscription.release();
+        throw new Error("Diff subscription cancelled");
+      }
+      await subscription.start();
+      return { initial: await initial, unsubscribe };
+    } catch (error) {
+      return { initial: { cwd, files: [], error: toCheckoutError(error) }, unsubscribe() {} };
     }
   }
-
+  scheduleRefreshForCwd(cwd: string): Promise<void> {
+    return this.streams.invalidateForCwd(expandTilde(cwd));
+  }
   getMetrics(): CheckoutDiffMetrics {
-    let checkoutDiffSubscriptionCount = 0;
-
-    for (const target of this.targets.values()) {
-      checkoutDiffSubscriptionCount += target.listeners.size;
-    }
-
+    const metrics = this.streams.getMetrics();
     return {
-      checkoutDiffTargetCount: this.targets.size,
-      checkoutDiffSubscriptionCount,
-      checkoutDiffWatcherCount: 0,
+      checkoutDiffTargetCount: metrics.targets,
+      checkoutDiffSubscriptionCount: metrics.subscriptions,
+      checkoutDiffWatcherCount: metrics.metadataObservers,
       checkoutDiffFallbackRefreshTargetCount: 0,
     };
   }
-
-  dispose(): void {
-    for (const target of this.targets.values()) {
-      this.closeTarget(target);
-    }
-    this.targets.clear();
-  }
-
-  private normalizeCompare(compare: CheckoutDiffCompareInput): CheckoutDiffCompareInput {
-    const ignoreWhitespace = compare.ignoreWhitespace === true;
-    if (compare.mode === "uncommitted") {
-      return { mode: "uncommitted", ignoreWhitespace };
-    }
-    const trimmedBaseRef = compare.baseRef?.trim();
-    return trimmedBaseRef
-      ? { mode: compare.mode, baseRef: trimmedBaseRef, ignoreWhitespace }
-      : { mode: compare.mode, ignoreWhitespace };
-  }
-
-  private buildTargetKey(cwd: string, compare: CheckoutDiffCompareInput): string {
-    return JSON.stringify([
-      cwd,
-      compare.mode,
-      compare.mode !== "uncommitted" ? (compare.baseRef ?? "") : "",
-      compare.ignoreWhitespace === true,
-    ]);
-  }
-
-  private closeTarget(target: CheckoutDiffWatchTarget): void {
-    if (target.debounceTimer) {
-      clearTimeout(target.debounceTimer);
-      target.debounceTimer = null;
-    }
-    target.workingTreeWatchUnsubscribe?.();
-    target.workingTreeWatchUnsubscribe = null;
-    target.workspaceGitUnsubscribe?.();
-    target.workspaceGitUnsubscribe = null;
-    target.listeners.clear();
-  }
-
-  private rememberWorkspaceSnapshot(
-    target: CheckoutDiffWatchTarget,
-    snapshot: WorkspaceGitRuntimeSnapshot,
-  ): void {
-    const structureFingerprint = JSON.stringify({
-      isGit: snapshot.git.isGit,
-      repoRoot: snapshot.git.repoRoot,
-      mainRepoRoot: snapshot.git.mainRepoRoot,
-      currentBranch: snapshot.git.currentBranch,
-      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,
-      hasRemote: snapshot.git.hasRemote,
-    });
-    const worktreeFingerprint = JSON.stringify({
-      isDirty: snapshot.git.isDirty,
-      diffStat: snapshot.git.diffStat,
-    });
-    const forgeFingerprint = JSON.stringify(snapshot.forge);
-    const previousStructureFingerprint = target.latestWorkspaceStructureFingerprint;
-    const previousWorktreeFingerprint = target.latestWorkspaceWorktreeFingerprint;
-    const previousForgeFingerprint = target.latestWorkspaceForgeFingerprint;
-    target.latestWorkspaceStructureFingerprint = structureFingerprint;
-    target.latestWorkspaceWorktreeFingerprint = worktreeFingerprint;
-    target.latestWorkspaceForgeFingerprint = forgeFingerprint;
-
-    if (previousStructureFingerprint === null) {
-      return;
-    }
-    const structureChanged = structureFingerprint !== previousStructureFingerprint;
-    const worktreeChanged = worktreeFingerprint !== previousWorktreeFingerprint;
-    const forgeChanged = forgeFingerprint !== previousForgeFingerprint;
-    if (structureChanged || (!worktreeChanged && !forgeChanged)) {
-      this.scheduleTargetRefresh(target, false);
-    }
-  }
-
-  private removeListener(
-    target: CheckoutDiffWatchTarget,
-    listener: (snapshot: CheckoutDiffSnapshotPayload) => void,
-  ): void {
-    target.listeners.delete(listener);
-    if (target.listeners.size > 0) {
-      return;
-    }
-    this.closeTarget(target);
-    if (this.targets.get(target.key) === target) {
-      this.targets.delete(target.key);
-    }
-  }
-
-  private scheduleTargetRefresh(target: CheckoutDiffWatchTarget, force = true): void {
-    target.pendingDebounceForce ||= force;
-    if (target.debounceTimer) {
-      clearTimeout(target.debounceTimer);
-    }
-    target.debounceTimer = setTimeout(() => {
-      target.debounceTimer = null;
-      const pendingForce = target.pendingDebounceForce;
-      target.pendingDebounceForce = false;
-      void this.refreshTarget(target, pendingForce);
-    }, CHECKOUT_DIFF_WATCH_DEBOUNCE_MS);
-  }
-
-  private async computeCheckoutDiffSnapshot(
-    cwd: string,
-    compare: CheckoutDiffCompareInput,
-    options?: { diffCwd?: string; force?: boolean; reason?: string },
-  ): Promise<CheckoutDiffSnapshotPayload> {
-    const diffCwd = options?.diffCwd ?? cwd;
-    try {
-      const diffResult = await this.workspaceGitService.getCheckoutDiff(
-        diffCwd,
-        {
-          mode: compare.mode,
-          baseRef: compare.baseRef,
-          ignoreWhitespace: compare.ignoreWhitespace,
-          includeStructured: true,
-        },
-        options?.force
-          ? { force: true, reason: options.reason ?? "checkout-diff-refresh" }
-          : undefined,
-      );
-      if (diffResult.diffTooLarge) {
-        return {
-          cwd,
-          files: [],
-          diffTooLarge: true,
-          error: toCheckoutError(new Error("Diff too large to display")),
-        };
-      }
-      const files = [...(diffResult.structured ?? [])];
-      files.sort((a, b) => {
-        if (a.path === b.path) return 0;
-        return a.path < b.path ? -1 : 1;
-      });
-      return {
-        cwd,
-        files,
-        error: null,
-      };
-    } catch (error) {
-      return {
-        cwd,
-        files: [],
-        error: toCheckoutError(error),
-      };
-    }
-  }
-
-  private async refreshTarget(target: CheckoutDiffWatchTarget, force: boolean): Promise<void> {
-    if (target.refreshPromise) {
-      target.refreshQueued = true;
-      target.refreshQueuedForce ||= force;
-      return;
-    }
-
-    target.refreshPromise = (async () => {
-      let currentForce = force;
-      do {
-        target.refreshQueued = false;
-        target.refreshQueuedForce = false;
-        const snapshot = await this.computeCheckoutDiffSnapshot(target.cwd, target.compare, {
-          diffCwd: target.diffCwd,
-          force: currentForce,
-          ...(currentForce ? { reason: "working-tree-watch" } : {}),
-        });
-        target.latestPayload = snapshot;
-        const fingerprint = JSON.stringify(snapshot);
-        if (fingerprint !== target.latestFingerprint) {
-          target.latestFingerprint = fingerprint;
-          for (const listener of target.listeners) {
-            listener(snapshot);
-          }
-        }
-        currentForce = target.refreshQueuedForce;
-      } while (target.refreshQueued);
-    })();
-
-    try {
-      await target.refreshPromise;
-    } finally {
-      target.refreshPromise = null;
-    }
-  }
-
-  private ensureTarget(cwd: string, compare: CheckoutDiffCompareInput): CheckoutDiffWatchTarget {
-    const targetKey = this.buildTargetKey(cwd, compare);
-    const existing = this.targets.get(targetKey);
-    if (existing) {
-      return existing;
-    }
-
-    const target: CheckoutDiffWatchTarget = {
-      key: targetKey,
-      cwd,
-      diffCwd: cwd,
-      compare,
-      listeners: new Set(),
-      workingTreeWatchUnsubscribe: null,
-      workspaceGitUnsubscribe: null,
-      latestWorkspaceStructureFingerprint: null,
-      latestWorkspaceWorktreeFingerprint: null,
-      latestWorkspaceForgeFingerprint: null,
-      debounceTimer: null,
-      pendingDebounceForce: false,
-      refreshPromise: null,
-      refreshQueued: false,
-      refreshQueuedForce: false,
-      latestPayload: null,
-      latestFingerprint: null,
-      openPromise: null,
-    };
-    this.targets.set(targetKey, target);
-    return target;
-  }
-
-  private async openTarget(target: CheckoutDiffWatchTarget): Promise<void> {
-    if (target.compare.mode !== "uncommitted") {
-      const snapshot =
-        this.workspaceRuntimeStore.get(target.cwd) ??
-        (await this.workspaceGitService.getSnapshot(target.cwd, { includeForge: false }));
-      target.diffCwd = snapshot.git.repoRoot ?? target.cwd;
-      if (this.targets.get(target.key) !== target || target.listeners.size === 0) {
-        return;
-      }
-      this.rememberWorkspaceSnapshot(target, snapshot);
-      const workspaceSubscription = this.workspaceGitService.registerWorkspace(
-        { cwd: target.cwd },
-        (nextSnapshot) => this.rememberWorkspaceSnapshot(target, nextSnapshot),
-      );
-      if (this.targets.get(target.key) !== target || target.listeners.size === 0) {
-        workspaceSubscription.unsubscribe();
-        return;
-      }
-      target.workspaceGitUnsubscribe = workspaceSubscription.unsubscribe;
-      if (target.compare.mode === "base") return;
-    }
-
-    const { repoRoot, unsubscribe } = await this.workspaceGitService.requestWorkingTreeWatch(
-      target.cwd,
-      () => this.scheduleTargetRefresh(target),
-    );
-    target.diffCwd = repoRoot ?? target.cwd;
-    if (this.targets.get(target.key) !== target || target.listeners.size === 0) {
-      unsubscribe();
-      return;
-    }
-    target.workingTreeWatchUnsubscribe = unsubscribe;
+  async dispose(): Promise<void> {
+    await this.streams.close();
   }
 }
+
+function legacySnapshot(cwd: string, files: ParsedDiffFile[]): CheckoutDiffSnapshotPayload {
+  let bytes = 2;
+  for (let index = 0; index < files.length; index++) {
+    bytes += Buffer.byteLength(JSON.stringify(files[index])) + Number(index > 0);
+    if (bytes > CHECKOUT_DIFF_MAX_STRUCTURED_BYTES) {
+      return legacyTooLarge(cwd);
+    }
+  }
+  return { cwd, files, error: null };
+}
+
+function legacyTooLarge(cwd: string): CheckoutDiffSnapshotPayload {
+  return {
+    cwd,
+    files: [],
+    diffTooLarge: true,
+    error: toCheckoutError(new Error("Diff too large to display")),
+  };
+}

packages/server/src/server/checkout/status-projection.ts

@@ -62,6 +62,7 @@ export function buildCheckoutStatusPayloadFromSnapshot({
       isDirty: snapshot.git.isDirty,
       baseRef: snapshot.git.baseRef,
       baseRefExact: snapshot.git.baseRefExact,
+      comparisonBaseRef: snapshot.git.comparisonBaseRef,
       aheadBehind: snapshot.git.aheadBehind ?? null,
       upstreamRef: snapshot.git.upstreamRef ?? null,
       aheadOfOrigin: snapshot.git.aheadOfOrigin ?? null,
@@ -83,6 +84,7 @@ export function buildCheckoutStatusPayloadFromSnapshot({
     isDirty: snapshot.git.isDirty,
     baseRef: snapshot.git.baseRef ?? null,
     baseRefExact: snapshot.git.baseRefExact,
+    comparisonBaseRef: snapshot.git.comparisonBaseRef,
     aheadBehind: snapshot.git.aheadBehind ?? null,
     upstreamRef: snapshot.git.upstreamRef ?? null,
     aheadOfOrigin: snapshot.git.aheadOfOrigin ?? null,

packages/server/src/server/daemon-e2e/checkout-diff-content.e2e.test.ts

@@ -293,3 +293,263 @@ test("large source diffs stay renderable for reads, subscriptions, and commit fi
     await rm(cwd, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
   }
 }, 60_000);
+
+test("streams whole-file batches and answers a same-socket ping before the revision ends", async () => {
+  const ctx = await createDaemonTestContext();
+  const cwd = mkdtempSync(join(tmpdir(), "diff-stream-wire-"));
+  let probe: Awaited<ReturnType<typeof openDiffWireProbe>> | null = null;
+  try {
+    git(cwd, "init", "-b", "main");
+    git(cwd, "config", "user.name", "Test");
+    git(cwd, "config", "user.email", "test@example.com");
+    writeFileSync(join(cwd, "README"), "base\n");
+    git(cwd, "add", ".");
+    git(cwd, "-c", "commit.gpgsign=false", "commit", "-m", "base");
+    for (let file = 0; file < 252; file++) {
+      const content =
+        Array.from(
+          { length: 80 },
+          (_, line) =>
+            `export const fn${line} = (param: string) => ({ key: param, value: ${file} });`,
+        ).join("\n") + "\n";
+      writeFileSync(join(cwd, `${file}.ts`), content);
+    }
+    expect(ctx.client.getLastServerInfoMessage()).toMatchObject({
+      features: { diffSubscription: true },
+    });
+    const legacy = await ctx.client.getCheckoutDiff(cwd, { mode: "uncommitted" });
+    const legacyJsonBytes = Buffer.byteLength(JSON.stringify(legacy.files));
+    expect(legacyJsonBytes).toBeGreaterThanOrEqual(10 * 1024 * 1024);
+    probe = await openDiffWireProbe(ctx.daemon.port, cwd);
+    const { encodedBytes, bodyFrames, pongDuringRevision, entryCount } = await probe.done;
+    expect(entryCount).toBe(252);
+    expect(bodyFrames).toBeGreaterThan(1);
+    expect(pongDuringRevision).toBe(true);
+    const artifactDirectory = join(
+      import.meta.dirname,
+      "../../../../../.artifacts/diff-subscription",
+    );
+    mkdirSync(artifactDirectory, { recursive: true });
+    writeFileSync(
+      join(artifactDirectory, "wire-metrics.json"),
+      JSON.stringify({ legacyJsonBytes, encodedBytes, bodyFrames, pongDuringRevision }, null, 2),
+    );
+  } finally {
+    probe?.socket.terminate();
+    await ctx.cleanup();
+    rmSync(cwd, { recursive: true, force: true });
+  }
+}, 60_000);
+
+interface DiffWireResult {
+  encodedBytes: number;
+  bodyFrames: number;
+  pongDuringRevision: boolean;
+  entryCount: number;
+}
+async function openDiffWireProbe(port: number, cwd: string) {
+  const { WebSocket } = await import("ws");
+  const { decodeDiffFrame, DiffOpcode } = await import("@getpaseo/protocol/binary-frames/index");
+  const activeSocket = new WebSocket(`ws://127.0.0.1:${port}/ws`);
+  await new Promise<void>((resolve, reject) => {
+    activeSocket.once("open", resolve);
+    activeSocket.once("error", reject);
+  });
+  let encodedBytes = 0;
+  let endReceived = false;
+  let pingSent = false;
+  let pongDuringRevision = false;
+  let bodyFrames = 0;
+  let entryCount = 0;
+  const done = new Promise<DiffWireResult>((resolve, reject) => {
+    activeSocket.on("message", (data, binary) => {
+      try {
+        if (binary) {
+          if (!Buffer.isBuffer(data)) throw new Error("Expected buffer");
+          encodedBytes += data.byteLength;
+          const frame = decodeDiffFrame(new Uint8Array(data));
+          if (frame.opcode === DiffOpcode.Begin) entryCount = frame.entries.length;
+          if (frame.opcode === DiffOpcode.Bodies) {
+            bodyFrames++;
+            if (!pingSent) {
+              pingSent = true;
+              activeSocket.send(
+                JSON.stringify({
+                  type: "session",
+                  message: { type: "ping", requestId: "mid-revision", clientSentAt: 1 },
+                }),
+              );
+            }
+          }
+          if (frame.opcode === DiffOpcode.End) {
+            expect(frame.error).toBeNull();
+            endReceived = true;
+            resolve({ encodedBytes, bodyFrames, pongDuringRevision, entryCount });
+          }
+        } else {
+          const envelope = JSON.parse(data.toString());
+          if (
+            envelope.message?.type === "pong" &&
+            envelope.message.payload.requestId === "mid-revision"
+          )
+            pongDuringRevision = !endReceived;
+          if (envelope.message?.payload?.status === "server_info")
+            activeSocket.send(
+              JSON.stringify({
+                type: "session",
+                message: {
+                  type: "diff.subscribe.request",
+                  requestId: "stream-diff",
+                  cwd,
+                  base: { kind: "rev", rev: "HEAD" },
+                  head: { kind: "worktree" },
+                },
+              }),
+            );
+          if (envelope.message?.type === "diff.subscribe.response")
+            expect(envelope.message.payload.error).toBeNull();
+        }
+      } catch (error) {
+        reject(error);
+      }
+    });
+    activeSocket.once("error", reject);
+  });
+  activeSocket.send(
+    JSON.stringify({
+      type: "hello",
+      clientId: "diff-wire-test",
+      clientType: "browser",
+      protocolVersion: 1,
+      capabilities: { owned_subscriptions: true },
+    }),
+  );
+  return { socket: activeSocket, done };
+}
+
+test("SDK diff journey publishes a tag tree, commits a one-file refresh and shares two sockets", async () => {
+  const ctx = await createDaemonTestContext();
+  const cwd = mkdtempSync(join(tmpdir(), "sdk-stream-diff-"));
+  const { DaemonClient } = await import("../test-utils/daemon-client.js");
+  const { startGitCommandMetrics, stopGitCommandMetrics } =
+    await import("../../utils/run-git-command.js");
+  const second = new DaemonClient({ url: `ws://127.0.0.1:${ctx.daemon.port}/ws` });
+  try {
+    git(cwd, "init", "-b", "main");
+    git(cwd, "config", "user.name", "Test");
+    git(cwd, "config", "user.email", "test@example.com");
+    writeFileSync(join(cwd, "a.ts"), "export const a = 1;\n");
+    writeFileSync(join(cwd, "b.ts"), "export const b = 1;\n");
+    git(cwd, "add", ".");
+    git(cwd, "-c", "commit.gpgsign=false", "commit", "-m", "base");
+    git(cwd, "tag", "v1");
+    writeFileSync(join(cwd, "a.ts"), "export const a = 2;\n");
+    writeFileSync(join(cwd, "b.ts"), "export const b = 2;\n");
+    const compare = {
+      cwd,
+      base: { kind: "rev", rev: "refs/tags/v1" },
+      head: { kind: "worktree" },
+      mergeBase: true,
+    } as const;
+    const states: import("@getpaseo/client").DiffState[] = [];
+    const observation = ctx.client.observeDiff(compare);
+    observation.subscribe({ snapshot: (state) => states.push(state), update: () => {} });
+    await expect.poll(() => states.at(-1)?.phase, { timeout: 15000 }).toBe("ready");
+    expect(states[0]).toMatchObject({
+      phase: "loading",
+      entries: [{ path: "a.ts" }, { path: "b.ts" }],
+    });
+    const initial = states.at(-1);
+    if (initial?.phase !== "ready") throw new Error("Expected ready");
+    const initialStateCount = states.length;
+    await second.connect();
+    startGitCommandMetrics();
+    const duplicateStates: import("@getpaseo/client").DiffState[] = [];
+    const duplicate = second.observeDiff(compare);
+    duplicate.subscribe({ snapshot: (state) => duplicateStates.push(state), update: () => {} });
+    await expect.poll(() => duplicateStates.at(-1)?.phase).toBe("ready");
+    const metrics = stopGitCommandMetrics();
+    expect(duplicateStates.at(-1)).toMatchObject({
+      phase: "ready",
+      files: [{ path: "a.ts" }, { path: "b.ts" }],
+    });
+    expect(metrics.commands.filter((command) => command.args.includes("--raw"))).toHaveLength(0);
+    startGitCommandMetrics();
+    writeFileSync(join(cwd, "a.ts"), "export const a = 3;\n");
+    await expect
+      .poll(() => states.at(-1)?.revision, { timeout: 15000 })
+      .toBeGreaterThan(initial.revision);
+    await expect.poll(() => duplicateStates.at(-1)?.revision).toBeGreaterThan(initial.revision);
+    const refreshMetrics = stopGitCommandMetrics();
+    expect(
+      refreshMetrics.commands.filter((command) => command.args.includes("--raw")),
+    ).toHaveLength(1);
+    const refreshed = states.at(-1);
+    if (refreshed?.phase !== "ready") throw new Error("Expected ready");
+    expect(refreshed.files[0]).not.toBe(initial.files[0]);
+    expect(refreshed.files[1]).toBe(initial.files[1]);
+    expect(states.slice(initialStateCount).map((state) => state.phase)).not.toContain("loading");
+    expect(states.map((state) => state.phase)).not.toContain("error");
+    await duplicate.release();
+    await observation.release();
+  } finally {
+    await second.close();
+    await ctx.cleanup();
+    rmSync(cwd, { recursive: true, force: true });
+  }
+}, 45000);
+
+test("commit-file RPC keeps the existing read ceiling for patches larger than one MiB", async () => {
+  const ctx = await createDaemonTestContext();
+  const cwd = mkdtempSync(join(tmpdir(), "commit-file-budget-"));
+  try {
+    git(cwd, "init", "-b", "main");
+    git(cwd, "config", "user.name", "Test");
+    git(cwd, "config", "user.email", "test@example.com");
+    writeFileSync(join(cwd, "large.txt"), "base\n");
+    git(cwd, "add", ".");
+    git(cwd, "-c", "commit.gpgsign=false", "commit", "-m", "base");
+    writeFileSync(join(cwd, "large.txt"), ("x".repeat(100) + "\n").repeat(11000));
+    git(cwd, "add", ".");
+    git(cwd, "-c", "commit.gpgsign=false", "commit", "-m", "large change");
+    const sha = git(cwd, "rev-parse", "HEAD").trim();
+    const { getCommitFileDiff } = await import("../../utils/checkout-git.js");
+    const expected = await getCommitFileDiff({ cwd, sha, path: "large.txt" });
+    const actual = await ctx.client.getCommitFileDiff(cwd, sha, "large.txt");
+    expect(expected?.hunks.length).toBeGreaterThan(0);
+    expect(actual.file?.hunks).toEqual(expected?.hunks);
+  } finally {
+    await ctx.cleanup();
+    rmSync(cwd, { recursive: true, force: true });
+  }
+}, 30000);
+
+test("commit-file RPC selects renamed content when the source path becomes a directory", async () => {
+  const ctx = await createDaemonTestContext();
+  const cwd = mkdtempSync(join(tmpdir(), "commit-rename-directory-"));
+  try {
+    git(cwd, "init", "-b", "main");
+    git(cwd, "config", "user.name", "Test");
+    git(cwd, "config", "user.email", "test@example.com");
+    writeFileSync(join(cwd, "a.txt"), "original line\n".repeat(16));
+    git(cwd, "add", ".");
+    git(cwd, "-c", "commit.gpgsign=false", "commit", "-m", "base");
+    git(cwd, "mv", "a.txt", "z.txt");
+    writeFileSync(join(cwd, "z.txt"), "original line\n".repeat(16) + "renamed line\n");
+    mkdirSync(join(cwd, "a.txt"));
+    writeFileSync(join(cwd, "a.txt", "child.txt"), "replacement line\n");
+    git(cwd, "add", ".");
+    git(cwd, "-c", "commit.gpgsign=false", "commit", "-m", "rename");
+    const sha = git(cwd, "rev-parse", "HEAD").trim();
+    const { getCommitFileDiff } = await import("../../utils/checkout-git.js");
+    const expected = await getCommitFileDiff({ cwd, sha, path: "z.txt" });
+    const actual = await ctx.client.getCommitFileDiff(cwd, sha, "z.txt");
+    expect(expected?.hunks.flatMap((hunk) => hunk.lines.map((line) => line.content))).toContain(
+      "renamed line",
+    );
+    expect(actual.file?.hunks).toEqual(expected?.hunks);
+  } finally {
+    await ctx.cleanup();
+    rmSync(cwd, { recursive: true, force: true });
+  }
+}, 30000);

packages/server/src/server/daemon-e2e/checkout-diff-subscription.e2e.test.ts

@@ -142,7 +142,8 @@ test("keeps the socket usable after rejecting an oversized structured diff", asy
     commitFile(cwd, "large-b.js", "const value = 0;\n");
     // Short lines stay eligible for highlighting; a giant single line is skipped
     // before token expansion and cannot exercise the structured-payload limit.
-    const denseExpression = `const value = ${"a+".repeat(100)}a;\n`.repeat(4_000);
+    // Stay below the full-source highlighting budget as well.
+    const denseExpression = `const value = ${"a+".repeat(100)}a;\n`.repeat(3_500);
     writeFileSync(path.join(cwd, "large-a.js"), denseExpression);
     writeFileSync(path.join(cwd, "large-b.js"), denseExpression);
 

packages/server/src/server/daemon-e2e/filesystem.e2e.test.ts

@@ -690,6 +690,7 @@ describe("commit file diffs", () => {
     expect(result).toEqual({
       file: {
         path: filePath,
+        status: "ok",
         isNew: false,
         isDeleted: false,
         additions: 1,

packages/server/src/server/diff/batches.ts

@@ -0,0 +1,30 @@
+import { encodeDiffFrame, DiffOpcode, type DiffBody } from "@getpaseo/protocol/binary-frames/index";
+
+export async function* packBodies(
+  files: AsyncIterable<DiffBody> | Iterable<DiffBody>,
+  revision: number,
+): AsyncGenerator<DiffBody[]> {
+  let batch: DiffBody[] = [];
+  let size = 0;
+  for await (const file of files) {
+    const bytes = encodeDiffFrame({
+      opcode: DiffOpcode.Bodies,
+      slot: 0,
+      revision,
+      files: [file],
+    }).length;
+    if (batch.length && size + bytes > 256 * 1024) {
+      yield batch;
+      batch = [];
+      size = 0;
+    }
+    batch.push(file);
+    size += bytes;
+    if (size >= 256 * 1024) {
+      yield batch;
+      batch = [];
+      size = 0;
+    }
+  }
+  if (batch.length) yield batch;
+}