test(app): verify Mermaid controls through user journeys

Keep source-toggle mechanics in diagram helpers and compare preview geometry with its screen and controls instead of requiring exact pixel heights.

Co-authored-by: luke <luopeihuan@gmail.com>

docs/agent-lifecycle.md

@@ -136,6 +136,12 @@ the marker. Closing a tab sets that client's label to `false`. Any `true` client
 open. Detach clears the parent and every open-tab label. The surviving child therefore becomes a
 normal root agent immediately, and closing its still-open tab archives it.
 
+Agent-scoped workspace creation records the caller's workspace as `parentWorkspaceId`.
+This is informational ancestry for future workspace grouping. It does not change placement,
+visibility, status, or archive behavior. Archiving a parent workspace preserves its children's
+records and parentage. Unscoped creation and existing workspaces have no parent; ancestry is
+never inferred from directories, projects, or Git branches.
+
 Runtime ownership is resolved from explicit workspace ID and caller context, never from `cwd`. Workspace creation is a separate operation with `local | worktree` isolation; agent creation reuses that workspace unless a new workspace is explicitly requested.
 
 Setup belongs to the workspace, including combined workspace-plus-agent creation and the supported agent `worktree` request. Run setup through the workspace workflow before launching configured terminals or scripts. Setup output is read in the Setup panel from per-command snapshots; never produce setup chat timeline rows or concatenate command logs. Legacy agent `git`/`worktreeName` inputs and hidden MCP worktree placement are rejected with workspace-creation guidance. Existing wire schemas retain an empty combined-log string for parsing compatibility.

docs/design.md

@@ -68,7 +68,7 @@ the sidebar. Apply it as `backgroundColor`; setting `opacity` on the control als
 
 `destructive` is filled with `destructive`. It only appears inside a confirm. The button on the page is `outline`; the destructive button is the confirm button inside the dialog.
 
-Controls come in two sizes, defined once in `control-geometry.ts`. The default is the right size almost everywhere — pages, dialogs, forms, settings rows, the setup flow — so don't pass a size. It is 32px tall where a pointer drives it and 44px where controls are touch-sized, so every touch control meets the iOS HIG's 44pt hit region. `sm` is 28px pointer and 32px touch, with `fontSize.sm` labels, and is for tight chrome only: toolbars, nested settings rows, dense inline row actions. A `size="sm"` on an ordinary page or dialog is wrong, and so is choosing a size from `useIsCompactFormFactor()`.
+Controls come in two sizes, defined once in `control-geometry.ts`. The default is the right size almost everywhere — pages, dialogs, forms, settings rows, the setup flow — so don't pass a size. It is 32px tall where a pointer drives it and 44px where controls are touch-sized, so every touch control meets the iOS HIG's 44pt hit region. The hit region is not the painted area: a filled toolbar control such as the composer's send or stop keeps the 44pt frame and paints a 36pt disc inside it (`TOOLBAR_DISC_SIZE`), so it does not outweigh its unpainted neighbours. `sm` is 28px pointer and 32px touch, with `fontSize.sm` labels, and is for tight chrome only: toolbars, nested settings rows, dense inline row actions. A `size="sm"` on an ordinary page or dialog is wrong, and so is choosing a size from `useIsCompactFormFactor()`.
 
 One gate, `resolveControlSizing`, picks touch or pointer sizing: touch when the layout is compact or the device has a touch screen. An iPad with the sidebar docked is wide and touch-sized; a desktop is pointer-sized; a phone is both compact and touch. The touch-screen fact is read once at startup (`hasTouchScreen` in `hooks/use-fine-pointer.ts`), so attaching a mouse or keyboard to a tablet never shrinks its controls. Stylesheets take sizes from `bySizing({ touch, pointer })`, which resolves to a breakpoint value, so a caller never sees which sizing it got. Rows, icon buttons and icon slots take theirs from `styles/density.ts`, which uses the same gate. An `{ xs, md }` literal for a hit target or glyph is wrong: on an iPad it yields the pointer size.
 

docs/menus.md

@@ -226,7 +226,8 @@ its own.
   inactive. An async action can navigate before its menu closes; a hidden panel must not leave a
   portal backdrop blocking the destination. On web the chat suspends one commit after it goes
   inactive, and that inactive commit is where the surface unmounts.
-- Anchoring, flipping, and edge clamping live in `components/ui/anchor.ts`, shared with the hover
-  card, and are unit-tested. Fix positioning bugs there, not at a call site.
+- Anchoring, flipping, edge clamping, and capping a surface's width to the display live in
+  `components/ui/anchor.ts`, shared with the hover card, and are unit-tested. Clamping moves a
+  surface but cannot shrink it, so the width cap is what keeps a wide menu on a narrow screen. Fix positioning bugs there, not at a call site.
 - Everything else about floating surfaces on Android — Portal/Modal escape, lifecycle gates,
   status-bar offset, the open flash — is in [floating-panels.md](floating-panels.md).

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

@@ -235,6 +235,7 @@ 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;
@@ -245,6 +246,9 @@ 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;
@@ -257,14 +261,24 @@ 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 }
+        | {
+            active: boolean;
+            largestDownwardShift: number;
+            sawMissing: boolean;
+            sawHidden: 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 };
+      return {
+        largestDownwardShift: state.largestDownwardShift,
+        sawMissing: state.sawMissing,
+        sawHidden: state.sawHidden,
+      };
     });
     expect(result.sawMissing).toBe(false);
+    expect(result.sawHidden).toBe(false);
     expect(result.largestDownwardShift).toBeLessThanOrEqual(2);
   };
 }
@@ -1178,7 +1192,13 @@ 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,11 +8,7 @@ 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,
-  openChangesTreePanel,
-  waitForWorkspaceTabsVisible,
-} from "../support/helpers/workspace-tabs";
+import { openChangesPanel, waitForWorkspaceTabsVisible } from "../support/helpers/workspace-tabs";
 
 interface DirtyWorkspace {
   id: string;
@@ -266,126 +262,6 @@ 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();
 
@@ -614,35 +490,6 @@ 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,
 }) => {
@@ -1455,13 +1302,11 @@ 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(300_000);
+  test.setTimeout(180_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);
@@ -2040,16 +1885,12 @@ async function createWorkspaceWithTwoSelectionDiffs(): Promise<DirtyWorkspace> {
   return { id: created.workspace.id, repoPath: repo.path };
 }
 
-async function createWorkspaceWithManyTinyDiffs(
-  fileCount: number,
-  branch = "main",
-): Promise<DirtyWorkspace> {
+async function createWorkspaceWithManyTinyDiffs(fileCount: number): 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,12 +79,6 @@ 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");
@@ -106,7 +100,6 @@ 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/mermaid-fullscreen.spec.ts

@@ -1,6 +1,8 @@
 import { test } from "../support/fixtures";
 import {
   closeDiagramFullscreen,
+  expectInlineDiagramFitsViewport,
+  toggleDiagramSourceAndVerifyControls,
   closeDiagramFullscreenFromOutside,
   expectCompletedDiagram,
   expectFullscreenDiagram,
@@ -21,6 +23,36 @@ const MERMAID_DIAGRAM = [
   "```",
 ].join("\n");
 
+test("bounds a tall inline diagram", async ({ page }) => {
+  test.setTimeout(120_000);
+  const diagram = [
+    "```mermaid",
+    "flowchart TD",
+    ...Array.from({ length: 30 }, (_, i) => `N${i} --> N${i + 1}`),
+    "```",
+  ].join("\n");
+  const agent = await seedMockAgentWorkspace({
+    repoPrefix: "mermaid-tall-",
+    title: "Tall Mermaid",
+    featureValues: {
+      mockStreamingAssistantResponse: diagram,
+      mockStreamingAssistantIntervalMs: 10,
+    },
+  });
+  try {
+    await openAgentRoute(page, agent);
+    await requestDiagram(agent);
+    await waitForDiagramTurnToComplete(agent);
+    await expectCompletedDiagram(page, ["N0", "N30"]);
+    await expectInlineDiagramFitsViewport(page);
+    await openDiagramFullscreen(page);
+    await expectFullscreenDiagram(page, ["N0", "N30"]);
+    await closeDiagramFullscreen(page);
+  } finally {
+    await agent.cleanup();
+  }
+});
+
 test("opens a Mermaid diagram fullscreen and closes it again", async ({ page }) => {
   test.setTimeout(120_000);
 
@@ -40,6 +72,10 @@ test("opens a Mermaid diagram fullscreen and closes it again", async ({ page })
       await expectCompletedDiagram(page, ["Start", "Ship"]);
     });
 
+    await test.step("Source toggles preserve the diagram and exclude hidden controls", async () => {
+      await toggleDiagramSourceAndVerifyControls(page);
+    });
+
     await test.step("The toolbar opens the diagram fullscreen", async () => {
       await openDiagramFullscreen(page);
       await expectFullscreenDiagram(page, ["Start", "Review", "Ship"]);

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

@@ -0,0 +1,127 @@
+import { expect, test } from "../support/fixtures";
+import { addProjectFlow } from "../support/helpers/add-project-flow";
+import { gotoAppShell } from "../support/helpers/app";
+import {
+  chooseFooterOverflowAction,
+  expectFooterLine,
+  expectFooterMenusInsideViewport,
+  expectFooterNeverClipped,
+  expectFooterOverflowActions,
+  footerOverflowMenu,
+  openFooterOverflow,
+  seedDockedSidebarWidth,
+  watchFooterClipping,
+} from "../support/helpers/sidebar-footer-overflow";
+import { addOfflineHostsAndReload } from "../support/helpers/hosts";
+import { openCompactSidebar } from "../support/helpers/usage-sidebar-item";
+
+const TOUCH_CONTROL = 44;
+const MIN_SIDEBAR_WIDTH = 200;
+const ALL_INLINE = [
+  "sidebar-add-project",
+  "sidebar-usage-icon",
+  "sidebar-hosts-trigger",
+  "sidebar-help",
+  "sidebar-settings",
+];
+// Five 44pt buttons and the row's padding need 236pt; 200pt holds three and the caret.
+const NARROW_TOUCH_LINE = [
+  "sidebar-add-project",
+  "sidebar-hosts-trigger",
+  "sidebar-footer-overflow",
+  "sidebar-settings",
+];
+
+test.describe("Sidebar footer on a touch screen", () => {
+  test.use({ viewport: { width: 1280, height: 800 }, hasTouch: true });
+
+  test("a narrow docked sidebar moves the actions it can't fit behind a caret", async ({
+    page,
+  }) => {
+    await seedDockedSidebarWidth(page, MIN_SIDEBAR_WIDTH);
+    await watchFooterClipping(page);
+    await gotoAppShell(page);
+    await expectFooterLine(page, { testIDs: NARROW_TOUCH_LINE, controlSize: TOUCH_CONTROL });
+    await expectFooterNeverClipped(page);
+
+    await test.step("Help opens as a page of the overflow menu", async () => {
+      await openFooterOverflow(page);
+      await expectFooterOverflowActions(page, ["Usage", "Help and support"]);
+      await chooseFooterOverflowAction(page, "Help and support");
+      await expect(page.getByRole("menuitem", { name: "What's new" })).toBeVisible();
+      await expect(page.getByTestId("sidebar-help-menu")).toHaveCount(0);
+      await page.keyboard.press("Escape");
+      await expect(footerOverflowMenu(page)).toBeHidden();
+    });
+
+    await test.step("Usage opens from the overflow menu", async () => {
+      await openFooterOverflow(page);
+      await chooseFooterOverflowAction(page, "Usage");
+      await expect(footerOverflowMenu(page)).toBeHidden();
+      await expect(page.getByTestId("usage-modal")).toBeVisible();
+      await page.keyboard.press("Escape");
+      await expect(page.getByTestId("usage-modal")).toBeHidden();
+    });
+
+    await test.step("Add project and Settings shortcuts still work", async () => {
+      await page.keyboard.press("Control+o");
+      await expect(addProjectFlow(page)).toBeVisible();
+      await page.keyboard.press("Escape");
+      await expect(addProjectFlow(page)).toBeHidden();
+      await page.keyboard.press("Control+,");
+      await expect(page).toHaveURL(/\/settings\/general$/);
+    });
+  });
+
+  test("the default sidebar width keeps all five actions inline", async ({ page }) => {
+    await gotoAppShell(page);
+    await expectFooterLine(page, { testIDs: ALL_INLINE, controlSize: TOUCH_CONTROL });
+  });
+});
+
+test.describe("Sidebar footer in a compact overlay narrower than the footer", () => {
+  test.use({ viewport: { width: 220, height: 800 }, hasTouch: true });
+
+  test("the overflow menu reaches the hidden actions", async ({ page }) => {
+    await watchFooterClipping(page);
+    await gotoAppShell(page);
+    await openCompactSidebar(page);
+    await expectFooterLine(page, { testIDs: NARROW_TOUCH_LINE, controlSize: TOUCH_CONTROL });
+    await expectFooterNeverClipped(page);
+    await openFooterOverflow(page);
+    await expectFooterOverflowActions(page, ["Usage", "Help and support"]);
+    await expectFooterMenusInsideViewport(page);
+  });
+});
+
+test.describe("Sidebar footer on a short, narrow phone", () => {
+  // 164pt for buttons holds Settings, Add project and the caret, so Hosts moves behind it.
+  test.use({ viewport: { width: 180, height: 360 }, hasTouch: true });
+
+  test("the overflow Hosts page scrolls to its last host and Add host", async ({ page }) => {
+    await gotoAppShell(page);
+    await addOfflineHostsAndReload(
+      page,
+      Array.from({ length: 10 }, (_, index) => ({
+        serverId: `overflow-host-${index}`,
+        label: `Overflow host ${index}`,
+      })),
+    );
+    await openCompactSidebar(page);
+    await expectFooterLine(page, {
+      testIDs: ["sidebar-add-project", "sidebar-footer-overflow", "sidebar-settings"],
+      controlSize: TOUCH_CONTROL,
+    });
+    await openFooterOverflow(page);
+    await expectFooterOverflowActions(page, ["Usage", "Hosts", "Help and support"]);
+    await expectFooterMenusInsideViewport(page);
+    await chooseFooterOverflowAction(page, "Hosts");
+    await expectFooterMenusInsideViewport(page);
+    const addHost = page.getByRole("menuitem", { name: "Add host" });
+    await addHost.scrollIntoViewIfNeeded();
+    await expect(page.getByRole("menuitem", { name: "Overflow host 9" })).toBeVisible();
+    await expect(addHost).toBeInViewport();
+    await addHost.click();
+    await expect(page.getByText("Add connection", { exact: true })).toBeVisible();
+  });
+});

packages/app/e2e/browser/usage-sidebar-item.spec.ts

@@ -8,7 +8,7 @@ import {
   openProjectViaDaemon,
 } from "../support/helpers/new-workspace";
 import { getServerId } from "../support/helpers/server-id";
-import { openSettingsHostSection } from "../support/helpers/settings";
+import { openCompactSettings, openSettingsHostSection } from "../support/helpers/settings";
 import {
   expectFooterItemSetting,
   expectFooterSeparator,
@@ -42,6 +42,7 @@ import {
 import { seedSidebarFooterPreferences } from "../support/helpers/sidebar-nav-settings";
 import { waitForSettledPosition } from "../support/helpers/sheet-layout";
 import { createTempGitRepo } from "../support/helpers/workspace";
+import { buildOpenProjectRoute } from "@/utils/host-routes";
 
 const WIDE = { width: 1440, height: 900 };
 const COMPACT = { width: 390, height: 844 };
@@ -70,7 +71,112 @@ async function footerClip(page: Page) {
   return (await page.locator('[data-testid="sidebar-footer"]:visible').boundingBox())!;
 }
 
+async function setPageVisibility(page: Page, visibility: DocumentVisibilityState): Promise<void> {
+  await page.evaluate((state) => {
+    Object.defineProperty(document, "visibilityState", { configurable: true, get: () => state });
+    Object.defineProperty(document, "hidden", {
+      configurable: true,
+      get: () => state === "hidden",
+    });
+    document.dispatchEvent(new Event("visibilitychange"));
+  }, visibility);
+}
+
 test.describe("Usage item", () => {
+  test("visible summary refreshes every five minutes without opening Usage", async ({ page }) => {
+    let usedPct = 31;
+    const usage = await installUsageReportsFixture(page, {
+      lists: [
+        () => [
+          {
+            ...claudeAndCodexReports()[0]!,
+            report: {
+              status: "available",
+              windows: [
+                { id: "five_hour", label: "Session", shortLabel: "5h", summary: true, usedPct },
+              ],
+            },
+          },
+        ],
+      ],
+    });
+    await page.clock.install();
+    await page.setViewportSize(WIDE);
+    await seedSidebarFooterPreferences(page, [{ key: "usage", visible: true }]);
+    await gotoAppShell(page);
+    await expectPinnedUsage(page, ["31% 5h"]);
+    const startingUrl = page.url();
+    await qaScreenshot(page, "usage-auto-refresh-initial", { kind: "footer" });
+    const requestsBeforeRefresh = usage.listRequests();
+
+    usedPct = 42;
+    await page.clock.fastForward(5 * 60_000);
+    await qaScreenshot(page, "usage-auto-refresh-after-interval", { kind: "footer" });
+    await expectPinnedUsage(page, ["42% 5h"]);
+    await expect(usageModal(page)).toHaveCount(0);
+    await expect(page).toHaveURL(startingUrl);
+    expect(usage.listRequests()).toEqual([
+      ...requestsBeforeRefresh,
+      { forceRefresh: false, reportIds: undefined, agentId: undefined },
+    ]);
+
+    await setPageVisibility(page, "hidden");
+    const requestsBeforeBackgrounding = usage.listRequests();
+    usedPct = 47;
+    await page.clock.fastForward(5 * 60_000);
+    expect(usage.listRequests()).toEqual(requestsBeforeBackgrounding);
+    await expectPinnedUsage(page, ["42% 5h"]);
+    await setPageVisibility(page, "visible");
+    await page.clock.fastForward(5 * 60_000);
+    await expectPinnedUsage(page, ["47% 5h"]);
+    expect(usage.listRequests()).toEqual([
+      ...requestsBeforeBackgrounding,
+      { forceRefresh: false, reportIds: undefined, agentId: undefined },
+    ]);
+
+    await page.setViewportSize(COMPACT);
+    await expect(usageItem(page)).toHaveCount(0);
+    const requestsBeforeHiding = usage.listRequests();
+    await page.clock.fastForward(5 * 60_000);
+    expect(usage.listRequests()).toEqual(requestsBeforeHiding);
+
+    await openCompactSidebar(page);
+    await expectPinnedUsage(page, ["47% 5h"]);
+    await expect(page.getByTestId("agent-list-backdrop")).toBeVisible();
+    usedPct = 53;
+    await page.clock.fastForward(5 * 60_000);
+    await expectPinnedUsage(page, ["53% 5h"]);
+    await expect(usageModal(page)).toHaveCount(0);
+
+    await page.setViewportSize(WIDE);
+    await openSidebarNavSettings(page);
+    await setFooterItemVisible(page, "usage", false);
+    await leaveSettings(page);
+    await expectNoUsageItem(page);
+    const requestsBeforeDisabling = usage.listRequests();
+    await page.clock.fastForward(5 * 60_000);
+    expect(usage.listRequests()).toEqual(requestsBeforeDisabling);
+  });
+
+  test("Usage settings do not poll reports while the sidebar is inactive", async ({ page }) => {
+    const usage = await installUsageReportsFixture(page, {
+      lists: [() => claudeAndCodexReports()],
+    });
+    await page.clock.install();
+    await page.setViewportSize(COMPACT);
+    await seedSidebarFooterPreferences(page, [{ key: "usage", visible: true }]);
+    await gotoAppShell(page);
+    await openCompactSettings(page, buildOpenProjectRoute());
+    await openSettingsHostSection(page, getServerId(), "usage");
+    await expect(page.getByTestId("usage-card").getByText("31% used")).toBeVisible();
+    await expect(usageItem(page)).toHaveCount(0);
+    const requestsBeforeWaiting = usage.listRequests();
+
+    await page.clock.fastForward(5 * 60_000);
+    expect(usage.listRequests()).toEqual(requestsBeforeWaiting);
+    await expect(page.getByTestId("usage-card").getByText("31% used")).toBeVisible();
+  });
+
   test("both compact footer entry points open Usage as a sheet", async ({ page }) => {
     await page.setViewportSize(COMPACT);
     await installUsageReportsFixture(page, { lists: [() => claudeAndCodexReports()] });

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

@@ -148,3 +148,59 @@ export async function expectFullscreenDiagram(
 export async function expectFullscreenDiagramClosed(page: Page): Promise<void> {
   await expect(page.getByTestId(FULLSCREEN_VIEWPORT)).toHaveCount(0);
 }
+
+/** Tall diagrams stay within the screen so their controls remain reachable. */
+export async function expectInlineDiagramFitsViewport(page: Page): Promise<void> {
+  const viewport = page.getByTestId("mermaid-viewport").last();
+  const box = await viewport.boundingBox();
+  expect(box, "the inline diagram has measurable layout").not.toBeNull();
+  const screenHeight = page.viewportSize()!.height;
+  expect(box!.height, "the inline diagram fits within the screen").toBeLessThan(screenHeight);
+  const contentHeight = await diagramSvg(page, "mermaid-viewport").evaluate(
+    (svg) => (svg as SVGSVGElement).viewBox.baseVal.height,
+  );
+  expect(box!.height, "a tall diagram is bounded rather than expanding the chat").toBeLessThan(
+    contentHeight,
+  );
+}
+
+/** Exercise pointer toggles and the controls encountered along that same journey. */
+export async function toggleDiagramSourceAndVerifyControls(page: Page): Promise<void> {
+  const viewport = page.getByTestId("mermaid-viewport").last();
+  const iframe = await viewport.locator("iframe").elementHandle();
+  for (let iteration = 0; iteration < 3; iteration++) {
+    await viewport.hover();
+    await page.getByRole("button", { name: "View source" }).last().click();
+    const viewDiagram = page.getByRole("button", { name: "View diagram" }).last();
+    await viewDiagram.click({ timeout: 10_000 });
+    await expect(viewDiagram).toHaveCount(0);
+    await expectFullscreenDiagramClosed(page);
+    expect(
+      await viewport.locator("iframe").evaluate((node, original) => node === original, iframe),
+      "switching views preserves the rendered diagram",
+    ).toBe(true);
+  }
+  await viewport.hover();
+  await page.getByRole("button", { name: "View source" }).last().click();
+  const hiddenFullscreen = viewport.getByRole("button", {
+    name: "Fullscreen",
+    includeHidden: true,
+  });
+  await hiddenFullscreen.focus();
+  await expect(hiddenFullscreen).not.toBeFocused();
+  await page.getByRole("button", { name: "View diagram" }).last().click();
+  await viewport.hover();
+  const fullscreen = viewport.getByRole("button", { name: "Fullscreen", exact: true });
+  const box = await viewport.boundingBox();
+  const control = await fullscreen.boundingBox();
+  expect(box).not.toBeNull();
+  expect(control).not.toBeNull();
+  expect(control!.y, "the toolbar starts inside the preview").toBeGreaterThanOrEqual(box!.y);
+  expect(control!.y + control!.height, "the toolbar fits inside the preview").toBeLessThanOrEqual(
+    box!.y + box!.height,
+  );
+  await viewport.getByRole("button", { name: "Zoom in" }).click();
+  await expect(viewport.getByRole("button", { name: "Reset view" })).toBeEnabled();
+  await viewport.getByRole("button", { name: "Reset view" }).click();
+  await expect(viewport.getByRole("button", { name: "Reset view" })).toBeDisabled();
+}

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

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

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

@@ -0,0 +1,127 @@
+import { expect, type Locator, type Page } from "@playwright/test";
+
+/** Every footer control that can sit in the icon line, caret included. */
+const FOOTER_LINE_TEST_IDS = [
+  "sidebar-add-project",
+  "sidebar-usage-icon",
+  "sidebar-hosts-trigger",
+  "sidebar-help",
+  "sidebar-footer-overflow",
+  "sidebar-settings",
+];
+
+// Browser layout boxes include floating-point rounding, even for whole-pixel styles.
+const GEOMETRY_TOLERANCE = 0.01;
+
+/** Open the app with the docked sidebar at `width`, as if the user had dragged it there. */
+export async function seedDockedSidebarWidth(page: Page, width: number): Promise<void> {
+  await page.addInitScript((sidebarWidth) => {
+    localStorage.setItem("panel-state", JSON.stringify({ version: 17, state: { sidebarWidth } }));
+  }, width);
+}
+
+/**
+ * From the first frame, record any frame in which a footer button reaches past its row, so a row
+ * laid out before it measured shows up even if it lasted one frame.
+ */
+export async function watchFooterClipping(page: Page): Promise<void> {
+  await page.addInitScript((testIDs) => {
+    const clippedFrames: string[] = [];
+    Object.assign(window, { __footerClippedFrames: clippedFrames });
+    const sample = () => {
+      for (const row of document.querySelectorAll('[data-testid="sidebar-footer-bottom-line"]')) {
+        const rowRect = row.getBoundingClientRect();
+        if (rowRect.width === 0) continue;
+        for (const testID of testIDs) {
+          const button = row.querySelector(`[data-testid="${testID}"]`);
+          if (button && button.getBoundingClientRect().right > rowRect.right + 0.5) {
+            clippedFrames.push(testID);
+          }
+        }
+      }
+      requestAnimationFrame(sample);
+    };
+    requestAnimationFrame(sample);
+  }, FOOTER_LINE_TEST_IDS);
+}
+
+export async function expectFooterNeverClipped(page: Page): Promise<void> {
+  const clipped = await page.evaluate(
+    () => (window as unknown as { __footerClippedFrames: string[] }).__footerClippedFrames,
+  );
+  expect(clipped).toEqual([]);
+}
+
+function footerLine(page: Page): Locator {
+  return page.locator('[data-testid="sidebar-footer-bottom-line"]:visible');
+}
+
+export function footerOverflowMenu(page: Page): Locator {
+  return page.getByTestId("sidebar-footer-overflow-menu");
+}
+
+/**
+ * The icon line shows exactly `testIDs`, in order, each `controlSize` square and wholly inside the
+ * line's box, so no button is cut off by the sidebar's edge.
+ */
+export async function expectFooterLine(
+  page: Page,
+  input: { testIDs: string[]; controlSize: number },
+): Promise<void> {
+  const line = footerLine(page);
+  await expect(line).toHaveCount(1);
+  await expect
+    .poll(async () =>
+      line
+        .locator(FOOTER_LINE_TEST_IDS.map((testID) => `[data-testid="${testID}"]`).join(","))
+        .evaluateAll((elements) => elements.map((element) => element.getAttribute("data-testid"))),
+    )
+    .toEqual(input.testIDs);
+  const { row, buttons } = await line.evaluate((element, testIDs) => {
+    const rect = (node: Element) => {
+      const { x, width, height } = node.getBoundingClientRect();
+      return { x, width, height };
+    };
+    return {
+      row: rect(element),
+      buttons: testIDs.map((testID) => rect(element.querySelector(`[data-testid="${testID}"]`)!)),
+    };
+  }, input.testIDs);
+  for (const button of buttons) {
+    expect(Math.abs(button.width - input.controlSize)).toBeLessThan(GEOMETRY_TOLERANCE);
+    expect(Math.abs(button.height - input.controlSize)).toBeLessThan(GEOMETRY_TOLERANCE);
+    expect(button.x).toBeGreaterThanOrEqual(row.x - GEOMETRY_TOLERANCE);
+    expect(button.x + button.width).toBeLessThanOrEqual(row.x + row.width + GEOMETRY_TOLERANCE);
+  }
+}
+
+export async function openFooterOverflow(page: Page): Promise<void> {
+  await footerLine(page).getByTestId("sidebar-footer-overflow").click();
+  await expect(footerOverflowMenu(page)).toBeVisible();
+}
+
+/** The overflow menu lists exactly these actions, in row order. */
+export async function expectFooterOverflowActions(page: Page, names: string[]): Promise<void> {
+  await expect(footerOverflowMenu(page).getByRole("menuitem")).toHaveText(names);
+}
+
+export async function chooseFooterOverflowAction(page: Page, name: string): Promise<void> {
+  await footerOverflowMenu(page).getByRole("menuitem", { name }).click();
+}
+
+/** Every row of the open overflow menu, and of the page it opened, is inside the viewport's width. */
+export async function expectFooterMenusInsideViewport(page: Page): Promise<void> {
+  const viewport = page.viewportSize()!;
+  const rows = page.getByRole("menuitem");
+  await expect(rows.first()).toBeVisible();
+  const boxes = await rows.evaluateAll((elements) =>
+    elements.map((element) => {
+      const { x, width } = element.getBoundingClientRect();
+      return { x, width };
+    }),
+  );
+  for (const box of boxes) {
+    expect(box.x).toBeGreaterThanOrEqual(0);
+    expect(box.x + box.width).toBeLessThanOrEqual(viewport.width);
+  }
+}

packages/app/modules/paseo-scroll/ios/PaseoScrollViewComponentView.mm

@@ -54,6 +54,28 @@ using namespace facebook::react;
   [[RCTComponentViewFactory currentComponentViewFactory] registerComponentViewClass:self];
 }
 
+// iOS 26 blurs a scroll view's edges and places the blur in the scroll view's own coordinates,
+// ignoring transforms. The keyboard lifts the chat with a translateY, so on iPhones the blur lands
+// over the readable chat and stays until the next scroll (#7883). React Native hides it for
+// inverted lists for the same reason (https://github.com/react/react-native/pull/58684). The app
+// draws its own header fade, so every edge is hidden; hiding only top and bottom leaves the side
+// effects, which also cover a transformed list on device.
+- (instancetype)initWithFrame:(CGRect)frame
+{
+  if (self = [super initWithFrame:frame]) {
+#if defined(__IPHONE_26_0) && __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_26_0
+    if (@available(iOS 26.0, *)) {
+      UIScrollView *scrollView = self.scrollView;
+      scrollView.topEdgeEffect.hidden = YES;
+      scrollView.bottomEdgeEffect.hidden = YES;
+      scrollView.leftEdgeEffect.hidden = YES;
+      scrollView.rightEdgeEffect.hidden = YES;
+    }
+#endif
+  }
+  return self;
+}
+
 - (void)mountingTransactionWillMount:(const MountingTransaction &)transaction
                 withSurfaceTelemetry:(const SurfaceTelemetry &)surfaceTelemetry
 {

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

@@ -65,7 +65,6 @@ interface BottomAnchorControllerDriver {
     pendingVerification: AttemptContext | null;
     blockedReason: BottomAnchorBlockedReason | null;
   };
-  resetForAgent: () => void;
   applyRouteRequest: (request: BottomAnchorRouteRequest | null) => void;
   requestLocalAnchor: (request: BottomAnchorLocalRequest) => void;
   beginUserScroll: () => void;
@@ -480,17 +479,6 @@ 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;
@@ -741,10 +729,6 @@ 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,7 +129,8 @@ function mountList(heldRowId: string) {
     }
     return position - state.scroll;
   };
-  return { render, scrollTo, heldRowTop };
+  const rowSize = (rowId: string) => listRef.current?.getState().sizes.get(rowId);
+  return { render, scrollTo, heldRowTop, rowSize };
 }
 
 it("anchors a data change on a held row whose top is above the viewport", async () => {
@@ -169,3 +170,21 @@ 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,9 +137,8 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
   } = props;
   const { renderHistoryMountedRow, renderLiveHeadRow, renderLiveAuxiliary } = renderers;
   const listRef = useRef<LegendListRef>(null);
-  // LegendList places the rows of each agent once, behind a hidden reveal (`dataKey`).
-  const [placedAgentId, setPlacedAgentId] = useState<string | null>(null);
-  const isListPlaced = placedAgentId === agentId;
+  // LegendList places the rows once, behind a hidden reveal, when the list mounts.
+  const [isListPlaced, setIsListPlaced] = useState(false);
   const isListPlacedRef = useRef(isListPlaced);
   isListPlacedRef.current = isListPlaced;
   const streamViewportMetricsRef = useRef({
@@ -384,23 +383,6 @@ 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();
@@ -411,7 +393,7 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
       historyStartSettleSchedulerRef.current?.cancel();
       historyStartSettleSchedulerRef.current = null;
     };
-  }, [agentId, clearPendingUserScrollEnd, disclosureHold, evaluateHistoryStart]);
+  }, [clearPendingUserScrollEnd, evaluateHistoryStart]);
 
   useEffect(() => {
     const handle: StreamViewportHandle = {
@@ -623,7 +605,7 @@ function NativeStreamViewport(props: StreamRenderInput & { strategy: StreamStrat
 
   const handleListPlaced = useStableEvent(() => {
     isListPlacedRef.current = true;
-    setPlacedAgentId(agentId);
+    setIsListPlaced(true);
     streamViewportMetricsRef.current = {
       ...streamViewportMetricsRef.current,
       contentMeasuredForKey: "native-virtualized",
@@ -711,7 +693,6 @@ 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,10 +839,6 @@ 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();
@@ -853,7 +849,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
       historyStartSettleSchedulerRef.current?.cancel();
       historyStartSettleSchedulerRef.current = null;
     };
-  }, [evaluateHistoryStart, props.agentId, readingAnchor]);
+  }, [evaluateHistoryStart]);
 
   useLayoutEffect(() => {
     if (!isActiveRef.current || !isActivationReady) {
@@ -1395,11 +1391,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
 export function createWebStreamStrategy(input: CreateWebStreamStrategyInput): StreamStrategy {
   return createStreamStrategy({
     render: (renderInput) => (
-      <WebStreamViewport
-        key={renderInput.agentId}
-        {...renderInput}
-        isMobileBreakpoint={input.isMobileBreakpoint}
-      />
+      <WebStreamViewport {...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({ agentId: "agent-1", items, loadRemoteOlder: vi.fn() }),
+      useStreamHistoryWindow({ items, loadRemoteOlder: vi.fn() }),
     );
 
     expect(result.current.start).toBe(2);
@@ -35,7 +35,6 @@ describe("useStreamHistoryWindow", () => {
     const loadRemoteOlder = vi.fn(async () => true);
     const { result } = renderHook(() =>
       useStreamHistoryWindow({
-        agentId: "agent-1",
         items: [
           message("u1", "user_message"),
           message("a1", "assistant_message"),
@@ -67,8 +66,7 @@ describe("useStreamHistoryWindow", () => {
       message("a2", "assistant_message"),
     ];
     const { result, rerender } = renderHook(
-      ({ history }) =>
-        useStreamHistoryWindow({ agentId: "agent-1", items: history, loadRemoteOlder: vi.fn() }),
+      ({ history }) => useStreamHistoryWindow({ items: history, loadRemoteOlder: vi.fn() }),
       { initialProps: { history: items } },
     );
 
@@ -91,8 +89,7 @@ describe("useStreamHistoryWindow", () => {
       message("a2", "assistant_message"),
     ];
     const { result, rerender } = renderHook(
-      ({ history }) =>
-        useStreamHistoryWindow({ agentId: "agent-1", items: history, loadRemoteOlder: vi.fn() }),
+      ({ history }) => useStreamHistoryWindow({ items: history, loadRemoteOlder: vi.fn() }),
       { initialProps: { history: items } },
     );
 
@@ -108,8 +105,7 @@ describe("useStreamHistoryWindow", () => {
       configurable: true,
     });
     const { result, rerender } = renderHook(
-      ({ history }) =>
-        useStreamHistoryWindow({ agentId: "agent-1", items: history, loadRemoteOlder: vi.fn() }),
+      ({ history }) => useStreamHistoryWindow({ items: history, loadRemoteOlder: vi.fn() }),
       {
         initialProps: {
           history: [
@@ -142,7 +138,6 @@ 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,22 +28,17 @@ 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, agentId, boundaryIndex, initialBoundaryItemId, hasItems } = input;
-  if (current.agentId !== agentId) {
-    return { agentId, boundaryItemId: initialBoundaryItemId, initialized: hasItems };
-  }
+  const { current, boundaryIndex, initialBoundaryItemId, hasItems } = input;
   if (!current.initialized && hasItems) {
     return { ...current, boundaryItemId: initialBoundaryItemId, initialized: true };
   }
@@ -54,28 +49,26 @@ function reconcileHistoryWindow(input: {
 }
 
 export function useStreamHistoryWindow(input: {
-  agentId: string;
   items: StreamItem[];
   loadRemoteOlder: () => boolean | Promise<boolean>;
 }) {
-  const { agentId, items, loadRemoteOlder } = input;
+  const { 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.agentId === agentId ? window.boundaryItemId : null;
+  const boundaryItemId = window.boundaryItemId;
   const boundaryIndex = useMemo(
     () => (boundaryItemId === null ? -1 : items.findIndex((item) => item.id === boundaryItemId)),
     [boundaryItemId, items],
   );
   let start = initialStart;
-  if (window.agentId === agentId && window.initialized) {
+  if (window.initialized) {
     if (window.boundaryItemId === null) {
       start = 0;
     } else if (boundaryIndex >= 0) {
@@ -87,13 +80,12 @@ export function useStreamHistoryWindow(input: {
     setWindow((current) =>
       reconcileHistoryWindow({
         current,
-        agentId,
         boundaryIndex,
         initialBoundaryItemId,
         hasItems: items.length > 0,
       }),
     );
-  }, [agentId, boundaryIndex, initialBoundaryItemId, items.length]);
+  }, [boundaryIndex, initialBoundaryItemId, items.length]);
 
   const revealLoadedHistory = useCallback(
     (itemId?: string): boolean => {
@@ -106,13 +98,12 @@ export function useStreamHistoryWindow(input: {
         return false;
       }
       setWindow({
-        agentId,
         boundaryItemId: items[nextStart]?.id ?? null,
         initialized: true,
       });
       return true;
     },
-    [agentId, items, start],
+    [items, start],
   );
   const loadOlder = useCallback(async (): Promise<boolean> => {
     return revealLoadedHistory() || (await loadRemoteOlder());

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

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

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

@@ -17,6 +17,7 @@ import {
   Text,
   useWindowDimensions,
   View,
+  type LayoutChangeEvent,
 } from "react-native";
 import { Gesture, ScrollView as GHScrollView } from "react-native-gesture-handler";
 import Animated, { runOnJS, useAnimatedStyle, useSharedValue } from "react-native-reanimated";
@@ -40,6 +41,17 @@ import { SidebarSeparator } from "@/components/sidebar/sidebar-separator";
 import { SidebarNavRows } from "@/components/sidebar/sidebar-nav-rows";
 import { SidebarFooterIconHighlight } from "@/components/sidebar/sidebar-footer-icon-highlight";
 import { SidebarHelpMenu } from "@/components/sidebar/sidebar-help-menu";
+import { SidebarFooterOverflowMenu } from "@/components/sidebar/sidebar-footer-overflow-menu";
+import {
+  resolveSidebarFooterLayout,
+  SIDEBAR_FOOTER_ACTIONS,
+  type SidebarFooterAction,
+} from "@/components/sidebar-footer-layout";
+import {
+  controlSizingForLayout,
+  mapLayout,
+  TOOLBAR_CONTROL_SIZES,
+} from "@/components/ui/control-geometry";
 import { SidebarResizeHandle } from "@/components/sidebar-resize-handle";
 import { DensityIcon } from "@/components/ui/density-icon";
 import { SidebarSectionHeader } from "@/components/sidebar/sidebar-section-header";
@@ -55,6 +67,7 @@ import {
   type SidebarWorkspaceEntry,
 } from "@/hooks/use-sidebar-workspaces-list";
 import { density } from "@/styles/density";
+import { SPACING } from "@/styles/theme";
 import { useSidebarModel } from "@/components/sidebar/sidebar-model";
 import type { PinnedSidebarGroups } from "@/hooks/use-sidebar-pins";
 import { RetainedPanelActivity } from "@/components/retained-panel";
@@ -79,6 +92,9 @@ import { SidebarWorkspaceList } from "./sidebar-workspace-list";
 
 type SidebarTheme = ReturnType<typeof useUnistyles>["theme"];
 
+/** The footer icon line's inset; the overflow layout counts it as space the buttons can't use. */
+const FOOTER_ROW_PADDING = SPACING[2];
+
 const DEV_BUILD_LABEL = process.env.EXPO_PUBLIC_PASEO_DEV_BUILD_LABEL?.trim() || null;
 
 interface SidebarSharedProps {
@@ -410,35 +426,72 @@ function SidebarFooter({
 }) {
   const newAgentKeys = useShortcutKeys("new-agent");
   const settingsKeys = useShortcutKeys("toggle-settings");
+  const isCompactLayout = useIsCompactFormFactor();
+  const [rowWidth, setRowWidth] = useState(0);
+  const handleRowLayout = useCallback((event: LayoutChangeEvent) => {
+    setRowWidth(event.nativeEvent.layout.width);
+  }, []);
+  const { inline, overflow } = useMemo(
+    () =>
+      resolveSidebarFooterLayout({
+        rowWidth,
+        controlSize: TOOLBAR_CONTROL_SIZES[controlSizingForLayout(isCompactLayout)],
+        rowPadding: FOOTER_ROW_PADDING,
+        actions: SIDEBAR_FOOTER_ACTIONS,
+      }),
+    [rowWidth, isCompactLayout],
+  );
+  const isInline = (action: SidebarFooterAction) => inline.includes(action);
 
-  // One line of icons: Add project, Usage, Hosts, then Help and Settings at the end.
+  // One line of icons: Add project, Usage, Hosts, then Help and Settings at the end. Actions that
+  // don't fit move behind a caret before Settings.
   return (
     <UsageSidebarRoot>
       <View style={styles.footerContainer} testID="sidebar-footer">
         <SidebarFooterRows onBeforeNavigate={onBeforeNavigate} />
-        <View style={styles.sidebarFooter} testID="sidebar-footer-bottom-line">
-          <FooterIconButton
-            onPress={handleOpenProject}
-            testID="sidebar-add-project"
-            label={labels.addProject}
-            icon={FolderPlus}
-            shortcutKeys={newAgentKeys}
-          />
-          <SidebarUsageIcon label={labels.usage} />
-          <SidebarHostPicker
-            label={labels.hosts}
-            onAddHost={handleAddHost}
-            onOpenHostSettings={handleOpenHostSettings}
-          />
+        <View
+          style={styles.sidebarFooter}
+          onLayout={handleRowLayout}
+          testID="sidebar-footer-bottom-line"
+        >
+          {isInline("add-project") ? (
+            <FooterIconButton
+              onPress={handleOpenProject}
+              testID="sidebar-add-project"
+              label={labels.addProject}
+              icon={FolderPlus}
+              shortcutKeys={newAgentKeys}
+            />
+          ) : null}
+          {isInline("usage") ? <SidebarUsageIcon label={labels.usage} /> : null}
+          {isInline("hosts") ? (
+            <SidebarHostPicker
+              label={labels.hosts}
+              onAddHost={handleAddHost}
+              onOpenHostSettings={handleOpenHostSettings}
+            />
+          ) : null}
           <View style={styles.footerSpacer} />
-          <SidebarHelpMenu />
-          <FooterIconButton
-            onPress={handleSettings}
-            testID="sidebar-settings"
-            label={labels.settings}
-            icon={Settings}
-            shortcutKeys={settingsKeys}
-          />
+          {isInline("help") ? <SidebarHelpMenu /> : null}
+          {overflow.length > 0 ? (
+            <SidebarFooterOverflowMenu
+              actions={overflow}
+              labels={labels}
+              onAddProject={handleOpenProject}
+              onSettings={handleSettings}
+              onAddHost={handleAddHost}
+              onOpenHostSettings={handleOpenHostSettings}
+            />
+          ) : null}
+          {isInline("settings") ? (
+            <FooterIconButton
+              onPress={handleSettings}
+              testID="sidebar-settings"
+              label={labels.settings}
+              icon={Settings}
+              shortcutKeys={settingsKeys}
+            />
+          ) : null}
         </View>
       </View>
     </UsageSidebarRoot>
@@ -937,10 +990,12 @@ const styles = StyleSheet.create((theme) => ({
     borderTopColor: theme.colors.border,
   },
   // Buttons sit edge to edge; their own inset spaces the glyphs.
+  // As tall as its buttons from the first frame, which places none until the row has measured.
   sidebarFooter: {
     flexDirection: "row",
     alignItems: "center",
-    paddingHorizontal: theme.spacing[2],
+    minHeight: mapLayout(density.iconButton, (height) => height + theme.spacing[1.5] * 2),
+    paddingHorizontal: FOOTER_ROW_PADDING,
     paddingVertical: theme.spacing[1.5],
   },
   // Pushes Help and Settings to the end of the icon line.

packages/app/src/components/markdown/fence/mermaid/host.web.tsx

@@ -72,7 +72,7 @@ function MermaidFenceHostImpl({
     () => [
       getDiagramBoxStyle(textStyle),
       containerStyle,
-      { height: runtimeHeight, minHeight: MIN_DIAGRAM_BOX_HEIGHT },
+      { height: Math.min(runtimeHeight, MAX_PREVIEW_HEIGHT), minHeight: MIN_DIAGRAM_BOX_HEIGHT },
     ],
     [runtimeHeight, textStyle],
   );
@@ -111,20 +111,22 @@ function MermaidFenceHostImpl({
           ) : null}
         </View>
       ) : null}
-      <ZoomableViewport
-        accessibilityLabel={t("message.diagram.diagram")}
-        actions={actions}
-        contentSize={diagramSize}
-        style={viewportStyle}
-        testID="mermaid-viewport"
-        wheelActivation="modifier"
-      >
-        <MermaidIframeRuntime
-          request={request}
-          onRendered={handleRendered}
-          onRenderFailed={renderFailed}
-        />
-      </ZoomableViewport>
+      <div inert={!diagramVisible} style={boundaryStyle}>
+        <ZoomableViewport
+          accessibilityLabel={t("message.diagram.diagram")}
+          actions={actions}
+          contentSize={diagramSize}
+          style={viewportStyle}
+          testID="mermaid-viewport"
+          wheelActivation="modifier"
+        >
+          <MermaidIframeRuntime
+            request={request}
+            onRendered={handleRendered}
+            onRenderFailed={renderFailed}
+          />
+        </ZoomableViewport>
+      </div>
       {isFullscreen && visible ? (
         <MermaidFullscreenViewer
           source={visible.source}
@@ -142,6 +144,8 @@ const MEASURING_SIZE = { width: 240, height: 240 };
  * with `overflow: hidden`, so a shorter box leaves the buttons half-clipped and unclickable.
  */
 const MIN_DIAGRAM_BOX_HEIGHT = 56;
+const MAX_PREVIEW_HEIGHT = 480;
+const boundaryStyle: React.CSSProperties = { display: "contents" };
 const sourceContainerStyle: ViewStyle = { position: "relative" };
 /**
  * The viewport's own root is `flex: 1`, so as a flex item it has `flex-basis: 0%` and that basis

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

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "vitest";
+import {
+  resolveSidebarFooterLayout,
+  SIDEBAR_FOOTER_ACTIONS,
+} from "@/components/sidebar-footer-layout";
+import { DEFAULT_SIDEBAR_WIDTH, MIN_SIDEBAR_WIDTH } from "@/stores/panel-store";
+
+const TOUCH = 44;
+const POINTER = 28;
+const ROW_PADDING = 8;
+
+function layout(rowWidth: number, controlSize: number) {
+  return resolveSidebarFooterLayout({
+    rowWidth,
+    controlSize,
+    rowPadding: ROW_PADDING,
+    actions: SIDEBAR_FOOTER_ACTIONS,
+  });
+}
+
+describe("sidebar footer layout", () => {
+  it("keeps every action inline at the default width with either sizing", () => {
+    for (const controlSize of [TOUCH, POINTER]) {
+      expect(layout(DEFAULT_SIDEBAR_WIDTH, controlSize)).toEqual({
+        inline: ["add-project", "usage", "hosts", "help", "settings"],
+        overflow: [],
+      });
+    }
+  });
+
+  it("keeps every action inline at the minimum width with pointer sizing", () => {
+    expect(layout(MIN_SIDEBAR_WIDTH, POINTER).overflow).toEqual([]);
+  });
+
+  // The iPhone Duo report: the folded sidebar column is about the minimum width, and touch
+  // sizing makes five 44pt buttons plus padding 236pt wide.
+  it("moves Help and Usage behind the caret at the minimum width with touch sizing", () => {
+    expect(layout(MIN_SIDEBAR_WIDTH, TOUCH)).toEqual({
+      inline: ["add-project", "hosts", "settings"],
+      overflow: ["usage", "help"],
+    });
+  });
+
+  it("keeps Settings and Add project inline longest", () => {
+    // Three slots: two actions and the caret.
+    expect(layout(3 * TOUCH + 2 * ROW_PADDING, TOUCH)).toEqual({
+      inline: ["add-project", "settings"],
+      overflow: ["usage", "hosts", "help"],
+    });
+    // Two slots: Settings and the caret.
+    expect(layout(2 * TOUCH + 2 * ROW_PADDING, TOUCH)).toEqual({
+      inline: ["settings"],
+      overflow: ["add-project", "usage", "hosts", "help"],
+    });
+  });
+
+  it("puts everything behind the caret when only the caret fits", () => {
+    expect(layout(TOUCH + 2 * ROW_PADDING - 10, TOUCH)).toEqual({
+      inline: [],
+      overflow: ["add-project", "usage", "hosts", "help", "settings"],
+    });
+  });
+
+  it("fits all five actions exactly at their combined width", () => {
+    const exact = 5 * TOUCH + 2 * ROW_PADDING;
+    expect(layout(exact, TOUCH).overflow).toEqual([]);
+    // Browser layout rounds a little below the exact width.
+    expect(layout(exact - 0.4, TOUCH).overflow).toEqual([]);
+    expect(layout(exact - 1, TOUCH).overflow).toEqual(["usage", "help"]);
+  });
+
+  it("only places the actions it is given", () => {
+    expect(
+      resolveSidebarFooterLayout({
+        rowWidth: 3 * TOUCH + 2 * ROW_PADDING,
+        controlSize: TOUCH,
+        rowPadding: ROW_PADDING,
+        actions: ["add-project", "hosts", "settings"],
+      }),
+    ).toEqual({ inline: ["add-project", "hosts", "settings"], overflow: [] });
+  });
+
+  // Laying out against a guessed width would paint a clipped row for a frame on narrow sidebars.
+  it("places nothing before the row has been measured", () => {
+    for (const controlSize of [TOUCH, POINTER]) {
+      expect(layout(0, controlSize)).toEqual({ inline: [], overflow: [] });
+    }
+  });
+});

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

@@ -0,0 +1,62 @@
+/** The sidebar footer's icon line, in row order. */
+export const SIDEBAR_FOOTER_ACTIONS = [
+  "add-project",
+  "usage",
+  "hosts",
+  "help",
+  "settings",
+] as const;
+
+export type SidebarFooterAction = (typeof SIDEBAR_FOOTER_ACTIONS)[number];
+
+/** The order actions keep their place in a row too narrow for all of them. */
+const KEEP_ORDER: readonly SidebarFooterAction[] = [
+  "settings",
+  "add-project",
+  "hosts",
+  "usage",
+  "help",
+];
+
+/** Measured widths land a hair under the exact sum of their parts. */
+const MEASUREMENT_TOLERANCE = 0.5;
+
+export interface SidebarFooterLayout {
+  /** Actions drawn in the row, in row order. */
+  inline: SidebarFooterAction[];
+  /** Actions behind the overflow caret, in row order. Empty when everything fits. */
+  overflow: SidebarFooterAction[];
+}
+
+/**
+ * Splits the footer's actions between the row and the overflow menu. Buttons keep their full size;
+ * when they don't all fit, the caret takes one slot and the actions that lose their place move
+ * behind it, Help first and Settings last. Nothing is placed until the row has a measured width.
+ */
+export function resolveSidebarFooterLayout(input: {
+  rowWidth: number;
+  controlSize: number;
+  rowPadding: number;
+  actions: readonly SidebarFooterAction[];
+}): SidebarFooterLayout {
+  const { rowWidth, controlSize, rowPadding, actions } = input;
+  // An unmeasured row stays empty: any guess would paint a clipped row for a frame on a narrow
+  // sidebar before the real width arrives.
+  if (rowWidth <= 0) {
+    return { inline: [], overflow: [] };
+  }
+  const slots = Math.floor(
+    (rowWidth - rowPadding * 2 + MEASUREMENT_TOLERANCE) / Math.max(controlSize, 1),
+  );
+  if (slots >= actions.length) {
+    return { inline: [...actions], overflow: [] };
+  }
+  const inlineCount = Math.max(slots - 1, 0);
+  const kept = new Set(
+    KEEP_ORDER.filter((action) => actions.includes(action)).slice(0, inlineCount),
+  );
+  return {
+    inline: actions.filter((action) => kept.has(action)),
+    overflow: actions.filter((action) => !kept.has(action)),
+  };
+}

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

@@ -0,0 +1,69 @@
+import type { ReactElement } from "react";
+import { Text, View } from "react-native";
+import type { LucideIcon } from "lucide-react-native";
+import { StyleSheet } from "react-native-unistyles";
+import { DropdownMenuTrigger } from "@/components/ui/dropdown-menu";
+import { DensityIcon } from "@/components/ui/density-icon";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
+import { density } from "@/styles/density";
+import { SidebarFooterIconHighlight } from "./sidebar-footer-icon-highlight";
+
+/**
+ * A footer icon that opens a menu. Sized and drawn like the footer's other icon buttons; the
+ * tooltip stays out of the way while the menu is open.
+ */
+export function SidebarFooterMenuTrigger({
+  icon,
+  label,
+  menuOpen,
+  testID,
+}: {
+  icon: LucideIcon;
+  label: string;
+  menuOpen: boolean;
+  testID: string;
+}): ReactElement {
+  return (
+    <Tooltip delayDuration={300} enabledOnDesktop={!menuOpen}>
+      <TooltipTrigger asChild>
+        <View>
+          <DropdownMenuTrigger
+            style={styles.trigger}
+            testID={testID}
+            accessibilityRole="button"
+            accessibilityLabel={label}
+          >
+            {({ hovered, pressed, open }) => (
+              <>
+                <SidebarFooterIconHighlight visible={pressed || open} />
+                <DensityIcon
+                  icon={icon}
+                  size="md"
+                  color={hovered ? "foreground" : "foregroundMuted"}
+                />
+              </>
+            )}
+          </DropdownMenuTrigger>
+        </View>
+      </TooltipTrigger>
+      <TooltipContent side="top" align="center" offset={8}>
+        <Text style={styles.tooltipText}>{label}</Text>
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
+const styles = StyleSheet.create((theme) => ({
+  trigger: {
+    width: density.iconButton,
+    height: density.iconButton,
+    alignItems: "center",
+    justifyContent: "center",
+    paddingVertical: theme.spacing[1],
+    paddingHorizontal: theme.spacing[1],
+  },
+  tooltipText: {
+    fontSize: theme.fontSize.base,
+    color: theme.colors.popoverForeground,
+  },
+}));

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

@@ -0,0 +1,245 @@
+import { useCallback, useMemo, useState, type ReactElement } from "react";
+import { useTranslation } from "react-i18next";
+import {
+  ChevronUp,
+  CircleGauge,
+  CircleHelp,
+  FolderPlus,
+  Plus,
+  Server,
+  Settings,
+} from "lucide-react-native";
+import { withUnistyles } from "react-native-unistyles";
+import { HostStatusDotSlot } from "@/components/hosts/host-picker";
+import type { SidebarFooterAction } from "@/components/sidebar-footer-layout";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuSubTrigger,
+  type MenuPageDefinition,
+} from "@/components/ui/dropdown-menu";
+import { Shortcut } from "@/components/ui/shortcut";
+import { useLocalDaemonServerId } from "@/hooks/use-is-local-daemon";
+import { useShortcutKeys } from "@/hooks/use-shortcut-keys";
+import { useHosts } from "@/runtime/host-runtime";
+import { ICON_SIZE, type Theme } from "@/styles/theme";
+import { orderHostsLocalFirst } from "@/types/host-connection";
+import { useOpenSidebarUsage } from "@/usage";
+import { SidebarFooterMenuTrigger } from "./sidebar-footer-menu-trigger";
+import { SidebarHelpMenuItems } from "./sidebar-help-menu";
+
+const mutedIconMapping = (theme: Theme) => ({ color: theme.colors.foregroundMuted });
+const ThemedFolderPlus = withUnistyles(FolderPlus);
+const ThemedCircleGauge = withUnistyles(CircleGauge);
+const ThemedServer = withUnistyles(Server);
+const ThemedCircleHelp = withUnistyles(CircleHelp);
+const ThemedSettings = withUnistyles(Settings);
+const ThemedPlus = withUnistyles(Plus);
+const addProjectLeading = <ThemedFolderPlus size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
+const usageLeading = <ThemedCircleGauge size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
+const hostsLeading = <ThemedServer size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
+const helpLeading = <ThemedCircleHelp size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
+const settingsLeading = <ThemedSettings size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
+const addHostLeading = <ThemedPlus size={ICON_SIZE.sm} uniProps={mutedIconMapping} />;
+
+const HOSTS_PAGE_ID = "hosts";
+const HELP_PAGE_ID = "help";
+
+export interface SidebarFooterOverflowMenuProps {
+  /** The footer actions that did not fit in the row, in row order. */
+  actions: readonly SidebarFooterAction[];
+  labels: { addProject: string; hosts: string; settings: string; usage: string };
+  onAddProject: () => void;
+  onSettings: () => void;
+  onAddHost: () => void;
+  onOpenHostSettings: (serverId: string) => void;
+}
+
+/**
+ * The caret at the end of a footer row too narrow for every action. It lists the actions that
+ * lost their place, with the same test IDs they carry in the row; Hosts and Help, menus of their
+ * own in the row, open as pages of this menu.
+ */
+export function SidebarFooterOverflowMenu({
+  actions,
+  labels,
+  onAddProject,
+  onSettings,
+  onAddHost,
+  onOpenHostSettings,
+}: SidebarFooterOverflowMenuProps): ReactElement {
+  const { t } = useTranslation();
+  const [open, setOpen] = useState(false);
+  const openUsage = useOpenSidebarUsage();
+  const newAgentKeys = useShortcutKeys("new-agent");
+  const settingsKeys = useShortcutKeys("toggle-settings");
+  const helpLabel = t("sidebar.help.trigger");
+  const addProjectTrailing = useMemo(
+    () => (newAgentKeys ? <Shortcut chord={newAgentKeys} /> : null),
+    [newAgentKeys],
+  );
+  const settingsTrailing = useMemo(
+    () => (settingsKeys ? <Shortcut chord={settingsKeys} /> : null),
+    [settingsKeys],
+  );
+
+  const pages = useMemo((): MenuPageDefinition[] => {
+    const result: MenuPageDefinition[] = [];
+    if (actions.includes("hosts")) {
+      result.push({
+        id: HOSTS_PAGE_ID,
+        title: labels.hosts,
+        content: <HostsPage onAddHost={onAddHost} onOpenHostSettings={onOpenHostSettings} />,
+      });
+    }
+    if (actions.includes("help")) {
+      result.push({ id: HELP_PAGE_ID, title: helpLabel, content: <SidebarHelpMenuItems /> });
+    }
+    return result;
+  }, [actions, helpLabel, labels.hosts, onAddHost, onOpenHostSettings]);
+
+  function renderAction(action: SidebarFooterAction): ReactElement {
+    switch (action) {
+      case "add-project":
+        return (
+          <DropdownMenuItem
+            key={action}
+            testID="sidebar-add-project"
+            leading={addProjectLeading}
+            trailing={addProjectTrailing}
+            onSelect={onAddProject}
+          >
+            {labels.addProject}
+          </DropdownMenuItem>
+        );
+      case "usage":
+        return (
+          <DropdownMenuItem
+            key={action}
+            testID="sidebar-usage-icon"
+            leading={usageLeading}
+            onSelect={openUsage}
+          >
+            {labels.usage}
+          </DropdownMenuItem>
+        );
+      case "hosts":
+        return (
+          <DropdownMenuSubTrigger
+            key={action}
+            id={HOSTS_PAGE_ID}
+            testID="sidebar-hosts-trigger"
+            leading={hostsLeading}
+          >
+            {labels.hosts}
+          </DropdownMenuSubTrigger>
+        );
+      case "help":
+        return (
+          <DropdownMenuSubTrigger
+            key={action}
+            id={HELP_PAGE_ID}
+            testID="sidebar-help"
+            leading={helpLeading}
+          >
+            {helpLabel}
+          </DropdownMenuSubTrigger>
+        );
+      case "settings":
+        return (
+          <DropdownMenuItem
+            key={action}
+            testID="sidebar-settings"
+            leading={settingsLeading}
+            trailing={settingsTrailing}
+            onSelect={onSettings}
+          >
+            {labels.settings}
+          </DropdownMenuItem>
+        );
+    }
+  }
+
+  return (
+    <DropdownMenu open={open} onOpenChange={setOpen}>
+      <SidebarFooterMenuTrigger
+        icon={ChevronUp}
+        label={t("sidebar.actions.moreActions")}
+        menuOpen={open}
+        testID="sidebar-footer-overflow"
+      />
+      <DropdownMenuContent
+        side="top"
+        align="end"
+        offset={8}
+        width={240}
+        pages={pages}
+        scrollable
+        testID="sidebar-footer-overflow-menu"
+      >
+        {actions.map(renderAction)}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
+
+/** The host picker's choices as a menu page: each host opens its settings, then Add host. */
+function HostsPage({
+  onAddHost,
+  onOpenHostSettings,
+}: {
+  onAddHost: () => void;
+  onOpenHostSettings: (serverId: string) => void;
+}): ReactElement {
+  const { t } = useTranslation();
+  const hosts = useHosts();
+  const localServerId = useLocalDaemonServerId();
+  const orderedHosts = useMemo(
+    () => orderHostsLocalFirst(hosts, localServerId),
+    [hosts, localServerId],
+  );
+
+  return (
+    <>
+      {orderedHosts.map((host) => (
+        <HostRow
+          key={host.serverId}
+          serverId={host.serverId}
+          label={host.label}
+          onOpenHostSettings={onOpenHostSettings}
+        />
+      ))}
+      {orderedHosts.length > 0 ? <DropdownMenuSeparator /> : null}
+      <DropdownMenuItem testID="sidebar-host-add" leading={addHostLeading} onSelect={onAddHost}>
+        {t("settings.addHost")}
+      </DropdownMenuItem>
+    </>
+  );
+}
+
+function HostRow({
+  serverId,
+  label,
+  onOpenHostSettings,
+}: {
+  serverId: string;
+  label: string;
+  onOpenHostSettings: (serverId: string) => void;
+}): ReactElement {
+  const handleSelect = useCallback(
+    () => onOpenHostSettings(serverId),
+    [onOpenHostSettings, serverId],
+  );
+  const leading = useMemo(() => <HostStatusDotSlot serverId={serverId} />, [serverId]);
+  return (
+    <DropdownMenuItem
+      testID={`sidebar-host-row-${serverId}`}
+      leading={leading}
+      onSelect={handleSelect}
+    >
+      {label}
+    </DropdownMenuItem>
+  );
+}

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

@@ -1,5 +1,5 @@
 import { useCallback, useState } from "react";
-import { Text, View } from "react-native";
+import { View } from "react-native";
 import { Activity, CircleHelp, Gift, Keyboard } from "lucide-react-native";
 import { useTranslation } from "react-i18next";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
@@ -12,17 +12,13 @@ import {
   DropdownMenuItem,
   DropdownMenuLabel,
   DropdownMenuSeparator,
-  DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
-import { DensityIcon } from "@/components/ui/density-icon";
-import { SidebarFooterIconHighlight } from "./sidebar-footer-icon-highlight";
-import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
+import { SidebarFooterMenuTrigger } from "./sidebar-footer-menu-trigger";
 import { useAppDiagnosticStore } from "@/diagnostics/store";
 import { useHardwareKeyboardPresent } from "@/keyboard";
 import { useHostRuntimeIsConnected, useHosts } from "@/runtime/host-runtime";
 import { useKeyboardShortcutsStore } from "@/stores/keyboard-shortcuts-store";
 import { useSessionStore } from "@/stores/session-store";
-import { density } from "@/styles/density";
 import { ICON_SIZE, type Theme } from "@/styles/theme";
 import type { HostProfile } from "@/types/host-connection";
 import { formatVersionWithPrefix } from "@/desktop/updates/desktop-updates";
@@ -77,12 +73,32 @@ function HostVersionHint({ host }: { host: HostProfile }) {
   );
 }
 
+/** The Help menu's trigger, and the menu it opens. */
 export function SidebarHelpMenu() {
+  const { t } = useTranslation();
+  const [open, setOpen] = useState(false);
+
+  return (
+    <DropdownMenu open={open} onOpenChange={setOpen}>
+      <SidebarFooterMenuTrigger
+        icon={CircleHelp}
+        label={t("sidebar.help.trigger")}
+        menuOpen={open}
+        testID="sidebar-help"
+      />
+      <DropdownMenuContent side="top" align="end" offset={8} width={280} testID="sidebar-help-menu">
+        <SidebarHelpMenuItems />
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
+
+/** The Help menu's rows, shared by the Help menu and the footer's overflow page for it. */
+export function SidebarHelpMenuItems() {
   const { t } = useTranslation();
   const shortcutsAvailable = useHardwareKeyboardPresent();
   const openAppDiagnostic = useAppDiagnosticStore((state) => state.open);
   const setShortcutsDialogOpen = useKeyboardShortcutsStore((state) => state.setShortcutsDialogOpen);
-  const [open, setOpen] = useState(false);
   const version = formatVersionWithPrefix(resolveAppVersion());
   const hosts = useHosts();
 
@@ -99,105 +115,65 @@ export function SidebarHelpMenu() {
   }, []);
 
   return (
-    <DropdownMenu open={open} onOpenChange={setOpen}>
-      <Tooltip delayDuration={300} enabledOnDesktop={!open}>
-        <TooltipTrigger asChild>
-          <View>
-            <DropdownMenuTrigger
-              style={styles.trigger}
-              testID="sidebar-help"
-              accessibilityRole="button"
-              accessibilityLabel={t("sidebar.help.trigger")}
-            >
-              {({ hovered, pressed, open: menuOpen }) => (
-                <>
-                  <SidebarFooterIconHighlight visible={pressed || menuOpen} />
-                  <DensityIcon
-                    icon={CircleHelp}
-                    size="md"
-                    color={hovered ? "foreground" : "foregroundMuted"}
-                  />
-                </>
-              )}
-            </DropdownMenuTrigger>
-          </View>
-        </TooltipTrigger>
-        <TooltipContent side="top" align="center" offset={8}>
-          <Text style={styles.tooltipText}>{t("sidebar.help.trigger")}</Text>
-        </TooltipContent>
-      </Tooltip>
-      <DropdownMenuContent side="top" align="end" offset={8} width={280} testID="sidebar-help-menu">
-        <DropdownMenuLabel>{t("sidebar.help.sectionHelp")}</DropdownMenuLabel>
-        {shortcutsAvailable ? (
-          <DropdownMenuItem
-            testID="sidebar-help-shortcuts"
-            leading={shortcutsLeadingIcon}
-            onSelect={openKeyboardShortcuts}
-          >
-            {t("sidebar.help.shortcuts")}
-          </DropdownMenuItem>
-        ) : null}
+    <>
+      <DropdownMenuLabel>{t("sidebar.help.sectionHelp")}</DropdownMenuLabel>
+      {shortcutsAvailable ? (
         <DropdownMenuItem
-          testID="sidebar-help-changelog"
-          leading={changelogLeadingIcon}
-          onSelect={openChangelog}
+          testID="sidebar-help-shortcuts"
+          leading={shortcutsLeadingIcon}
+          onSelect={openKeyboardShortcuts}
         >
-          {t("sidebar.help.whatsNew")}
+          {t("sidebar.help.shortcuts")}
         </DropdownMenuItem>
-        <DropdownMenuItem
-          testID="sidebar-help-diagnostics"
-          leading={diagnosticLeadingIcon}
-          onSelect={openAppDiagnostic}
+      ) : null}
+      <DropdownMenuItem
+        testID="sidebar-help-changelog"
+        leading={changelogLeadingIcon}
+        onSelect={openChangelog}
+      >
+        {t("sidebar.help.whatsNew")}
+      </DropdownMenuItem>
+      <DropdownMenuItem
+        testID="sidebar-help-diagnostics"
+        leading={diagnosticLeadingIcon}
+        onSelect={openAppDiagnostic}
+      >
+        {t("sidebar.help.diagnostics")}
+      </DropdownMenuItem>
+      <DropdownMenuSeparator />
+      <DropdownMenuLabel>{t("sidebar.help.reportIssue")}</DropdownMenuLabel>
+      <DropdownMenuItem
+        testID="sidebar-help-discord"
+        leading={discordLeadingIcon}
+        onSelect={openDiscord}
+      >
+        {t("sidebar.help.discord")}
+      </DropdownMenuItem>
+      <DropdownMenuItem
+        testID="sidebar-help-github"
+        leading={githubLeadingIcon}
+        onSelect={openGitHubIssue}
+      >
+        {t("sidebar.help.github")}
+      </DropdownMenuItem>
+      <DropdownMenuSeparator />
+      <View style={styles.versionList}>
+        <DropdownMenuHint
+          style={styles.versionHint}
+          trailing={version}
+          testID="sidebar-help-version"
         >
-          {t("sidebar.help.diagnostics")}
-        </DropdownMenuItem>
-        <DropdownMenuSeparator />
-        <DropdownMenuLabel>{t("sidebar.help.reportIssue")}</DropdownMenuLabel>
-        <DropdownMenuItem
-          testID="sidebar-help-discord"
-          leading={discordLeadingIcon}
-          onSelect={openDiscord}
-        >
-          {t("sidebar.help.discord")}
-        </DropdownMenuItem>
-        <DropdownMenuItem
-          testID="sidebar-help-github"
-          leading={githubLeadingIcon}
-          onSelect={openGitHubIssue}
-        >
-          {t("sidebar.help.github")}
-        </DropdownMenuItem>
-        <DropdownMenuSeparator />
-        <View style={styles.versionList}>
-          <DropdownMenuHint
-            style={styles.versionHint}
-            trailing={version}
-            testID="sidebar-help-version"
-          >
-            {t("sidebar.help.appName")}
-          </DropdownMenuHint>
-          {hosts.map((host) => (
-            <HostVersionHint key={host.serverId} host={host} />
-          ))}
-        </View>
-      </DropdownMenuContent>
-    </DropdownMenu>
+          {t("sidebar.help.appName")}
+        </DropdownMenuHint>
+        {hosts.map((host) => (
+          <HostVersionHint key={host.serverId} host={host} />
+        ))}
+      </View>
+    </>
   );
 }
 
 const styles = StyleSheet.create((theme) => ({
-  trigger: {
-    width: density.iconButton,
-    height: density.iconButton,
-    alignItems: "center",
-    justifyContent: "center",
-    paddingVertical: theme.spacing[1],
-    paddingHorizontal: theme.spacing[1],
-  },
-  tooltipText: {
-    fontSize: theme.fontSize.base,
-    color: theme.colors.popoverForeground,
-  },
   versionList: {
     gap: theme.spacing[1],
     paddingVertical: theme.spacing[2],

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { computePosition, getTransformOrigin, type Rect } from "./anchor";
+import { computePosition, fitSurfaceWidth, getTransformOrigin, type Rect } from "./anchor";
 
 const DISPLAY: Rect = { x: 0, y: 0, width: 1000, height: 800 };
 const TRIGGER: Rect = { x: 100, y: 100, width: 40, height: 20 };
@@ -97,3 +97,26 @@ describe("getTransformOrigin", () => {
     expect(getTransformOrigin(placement, alignment)).toEqual(expected);
   });
 });
+
+describe("fitSurfaceWidth", () => {
+  it("leaves a surface that fits the display alone, capped at the display", () => {
+    expect(fitSurfaceWidth({ width: 240, minWidth: 180 }, 1000)).toEqual({
+      width: 240,
+      minWidth: 180,
+      maxWidth: 984,
+    });
+  });
+
+  it("shrinks a surface wider than a narrow display to the space inside its edge padding", () => {
+    expect(fitSurfaceWidth({ width: 240, minWidth: 180, maxWidth: 320 }, 220)).toEqual({
+      width: 204,
+      minWidth: 180,
+      maxWidth: 204,
+    });
+    expect(fitSurfaceWidth({ minWidth: 180 }, 150)).toEqual({
+      width: undefined,
+      minWidth: 134,
+      maxWidth: 134,
+    });
+  });
+});

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

@@ -120,6 +120,27 @@ function clampToDisplayArea(input: {
   };
 }
 
+export interface SurfaceWidth {
+  width?: number;
+  minWidth?: number;
+  maxWidth?: number;
+}
+
+/**
+ * Caps a surface's requested width to the display. Position clamping can move a surface but not
+ * shrink it, so a menu wider than a narrow screen would otherwise hang off the far edge.
+ */
+export function fitSurfaceWidth(requested: SurfaceWidth, displayWidth: number): SurfaceWidth {
+  const available = Math.max(displayWidth - EDGE_PADDING * 2, 0);
+  const cap = (value: number | undefined) =>
+    typeof value === "number" ? Math.min(value, available) : undefined;
+  return {
+    width: cap(requested.width),
+    minWidth: cap(requested.minWidth),
+    maxWidth: cap(requested.maxWidth) ?? available,
+  };
+}
+
 export function computePosition({
   triggerRect,
   contentSize,

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

@@ -14,6 +14,8 @@ import {
   getControlInteractionPhase,
   TOOLBAR_CONTROL_HEIGHT,
   TOOLBAR_CONTROL_SIZES,
+  TOOLBAR_DISC_SIZE,
+  TOOLBAR_DISC_SIZES,
   TOUCH_TARGET,
 } from "@/components/ui/control-geometry";
 import type { Theme } from "@/styles/theme";
@@ -90,6 +92,11 @@ describe("control sizing gate", () => {
     // Composer toolbar controls: a full target on touch, unchanged 28 on pointer.
     expect(TOOLBAR_CONTROL_SIZES).toEqual({ touch: TOUCH_TARGET, pointer: 28 });
     expect(TOOLBAR_CONTROL_HEIGHT).toEqual({ xs: TOUCH_TARGET, md: 28 });
+    // A filled toolbar control paints a 36pt disc inside its 44pt touch frame, and fills its
+    // 28pt pointer frame exactly, so desktop is unchanged. Its glyph is the `md` glyph.
+    expect(TOOLBAR_DISC_SIZES).toEqual({ touch: 36, pointer: TOOLBAR_CONTROL_SIZES.pointer });
+    expect(TOOLBAR_DISC_SIZE).toEqual({ xs: 36, md: 28 });
+    expect(iconSizeFor("md")).toEqual({ touch: 20, pointer: 16 });
     for (const size of ["sm", "md"] as const) {
       expect(controlHeightForLayout(size, true)).toBeGreaterThan(
         controlHeightForLayout(size, false),

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

@@ -93,6 +93,14 @@ export const ICON_BUTTON_SIZES = {
 export const TOOLBAR_CONTROL_SIZES = { touch: TOUCH_TARGET, pointer: 28 } satisfies SizingValue;
 export const TOOLBAR_CONTROL_HEIGHT = bySizing(TOOLBAR_CONTROL_SIZES);
 
+/**
+ * The painted disc of a filled toolbar control, such as the composer's send and stop. The
+ * control keeps the full toolbar hit frame and paints this smaller disc centered inside it, so
+ * touch-sized it does not outweigh its unpainted neighbours. Pointer-sized it fills the frame.
+ */
+export const TOOLBAR_DISC_SIZES = { touch: 36, pointer: 28 } satisfies SizingValue;
+export const TOOLBAR_DISC_SIZE = bySizing(TOOLBAR_DISC_SIZES);
+
 /**
  * Glyph sizes. Pointer glyphs sit beside 13-14pt text; touch glyphs sit beside iOS's 17pt body
  * text, so each step is larger.

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

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

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

@@ -60,17 +60,6 @@ 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,15 +8,8 @@ import {
 import { isActiveCreateFlowForDraft, useCreateFlowStore } from "@/stores/create-flow-store";
 import { handoffCreatedAgentMessageSubmission } from "@/composer/submission/writer";
 import { useSessionStore } from "@/stores/session-store";
-import {
-  createUserMessage,
-  type StreamItem,
-  type UserMessageImageAttachment,
-} from "@/types/stream";
+import { createUserMessage, 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;
@@ -153,38 +146,6 @@ 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) => {
@@ -365,8 +326,6 @@ export function useDraftAgentCreateFlow<TDraftAgent, TCreateResult>({
     machine,
     formErrorMessage,
     isSubmitting,
-    submittedStreamItems,
-    pendingMessageSubmissions,
     draftAgent,
     handleCreateFromInput,
     continueCreateFromAttempt,

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

@@ -0,0 +1,103 @@
+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

@@ -0,0 +1,102 @@
+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,4 +1,5 @@
 import { resolveSubmissionReadiness } from "@/provider-selection/provider-selection";
+import type { WorkspaceDraftTabSetup } from "@/workspace-tabs/model";
 
 export interface WorkspaceDraftAutoSubmitConfig {
   provider: string;
@@ -50,3 +51,13 @@ 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,21 +1,17 @@
 import { useCallback, useEffect, useMemo, useRef } from "react";
-import { Keyboard, ScrollView, StyleSheet as RNStyleSheet, Text, View } from "react-native";
+import { Keyboard, 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 { useComposerEditingSession, useComposerFullscreen } from "@/composer/editing-session";
-import { FileDropZone } from "@/components/file-drop/file-drop-zone";
+import { type ComposerEditingSession, useComposerFullscreen } from "@/composer/editing-session";
 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";
@@ -25,13 +21,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 type { AgentCapabilityFlags } from "@getpaseo/protocol/agent-types";
+import { DRAFT_CAPABILITIES } from "@/composer/draft/timeline";
 import type { AgentSnapshotPayload } from "@getpaseo/protocol/messages";
 import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
 import type { WorkspaceComposerAttachment } from "@/attachments/types";
@@ -50,16 +46,6 @@ 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;
@@ -260,25 +246,15 @@ function buildDraftInitialValues(input: {
   };
 }
 
-function resolveDraftWorkingDirectory(input: {
-  workspaceDirectory: string | null;
-  initialSetup: WorkspaceDraftTabSetup | null;
-}): string | null {
-  if (input.initialSetup) {
-    return input.initialSetup.cwd;
-  }
-  return input.workspaceDirectory;
-}
-
-interface WorkspaceDraftAgentTabProps {
+interface WorkspaceDraftComposerProps {
   serverId: string;
   workspaceId: string;
   tabId: string;
   draftId: string;
   initialSetup?: WorkspaceDraftTabSetup;
   isPaneFocused: boolean;
+  editingSession: ComposerEditingSession;
   onCreated: (snapshot: AgentSnapshotPayload) => void;
-  onOpenWorkspaceFile: (request: WorkspaceFileOpenRequest) => void;
   onOpenImportSheet?: () => void;
 }
 
@@ -292,17 +268,21 @@ function resolveImportPillPress(
   return onOpenImportSheet ?? null;
 }
 
-export function WorkspaceDraftAgentTab({
+/**
+ * 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({
   serverId,
   workspaceId,
   tabId,
   draftId,
   initialSetup = undefined,
   isPaneFocused,
+  editingSession,
   onCreated,
-  onOpenWorkspaceFile,
   onOpenImportSheet,
-}: WorkspaceDraftAgentTabProps) {
+}: WorkspaceDraftComposerProps) {
   const { t } = useTranslation();
   const client = useHostRuntimeClient(serverId);
   const isConnected = useHostRuntimeIsConnected(serverId);
@@ -387,7 +367,6 @@ export function WorkspaceDraftAgentTab({
   }, [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,
@@ -421,82 +400,71 @@ export function WorkspaceDraftAgentTab({
     [isCompactFormFactor, openInSidePane, serverId, workspaceId],
   );
 
-  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],
-  );
+  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);
+      },
+    });
   useAgentControlCommandCenterActions({
     sourceId: `draft:${serverId}:${tabId}`,
     enabled: isPaneFocused && !isSubmitting,
@@ -600,75 +568,48 @@ export function WorkspaceDraftAgentTab({
     }),
     [composerState.agentControls, handleDropdownCloseFocus, isSubmitting],
   );
-  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>
-      ) : (
-        <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>
-        </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 style={animatedStaticStyles.inputAreaWrapper} onLayout={onInputAreaLayout}>
+      {formErrorMessage ? (
+        <View style={styles.formErrorRow}>
+          <View style={styles.formError}>
+            <Text style={styles.errorText}>{formErrorMessage}</Text>
+          </View>
         </View>
-      </ComposerDock>
-    </FileDropZone>
+      ) : null}
+      {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>
   );
 }
 
@@ -682,27 +623,10 @@ const animatedStaticStyles = RNStyleSheet.create({
 });
 
 const styles = StyleSheet.create((theme) => ({
-  container: {
-    flex: 1,
+  formErrorRow: {
     width: "100%",
-    backgroundColor: theme.colors.surface0,
-  },
-  contentContainer: {
-    flex: 1,
-  },
-  streamContainer: {
-    flex: 1,
-  },
-  scrollView: {
-    flex: 1,
-  },
-  configScrollContent: {
     paddingHorizontal: theme.spacing[4],
-    paddingTop: theme.spacing[4],
-    paddingBottom: theme.spacing[6],
-  },
-  configSection: {
-    gap: theme.spacing[3],
+    alignItems: "center",
   },
   importPillRow: {
     width: "100%",
@@ -722,8 +646,10 @@ const styles = StyleSheet.create((theme) => ({
     maxWidth: theme.contentMaxWidth,
     flexDirection: "row",
   },
-  errorContainer: {
-    marginTop: theme.spacing[2],
+  formError: {
+    width: "100%",
+    maxWidth: theme.contentMaxWidth,
+    marginBottom: theme.spacing[2],
     paddingHorizontal: theme.spacing[3],
     paddingVertical: theme.spacing[2],
     borderRadius: theme.borderRadius.md,

packages/app/src/composer/index.tsx

@@ -35,6 +35,7 @@ import {
   controlSizingForLayout,
   iconSizeFor,
   TOOLBAR_CONTROL_HEIGHT,
+  TOOLBAR_DISC_SIZE,
 } from "@/components/ui/control-geometry";
 import { usePanelStore } from "@/stores/panel-store";
 import { usePointerCapabilities } from "@/hooks/pointer-capabilities";
@@ -1117,7 +1118,7 @@ function ComposerCancelButton({
         accessibilityRole="button"
         style={cancelButtonStyle}
       >
-        {icon}
+        <View style={styles.cancelButtonDisc}>{icon}</View>
       </TooltipTrigger>
       <TooltipContent side="top" align="center" offset={8}>
         <View style={styles.tooltipRow}>
@@ -2595,14 +2596,21 @@ const styles = StyleSheet.create((theme: Theme) => ({
     width: "100%",
     gap: theme.spacing[3],
   },
+  // The trigger is the hit frame and stays unpainted; the disc inside it carries the fill.
   cancelButton: {
     width: TOOLBAR_CONTROL_HEIGHT,
     height: TOOLBAR_CONTROL_HEIGHT,
+    alignItems: "center",
+    justifyContent: "center",
+    marginLeft: theme.spacing[1],
+  },
+  cancelButtonDisc: {
+    width: TOOLBAR_DISC_SIZE,
+    height: TOOLBAR_DISC_SIZE,
     borderRadius: theme.borderRadius.full,
     backgroundColor: theme.colors.palette.red[600],
     alignItems: "center",
     justifyContent: "center",
-    marginLeft: theme.spacing[1],
   },
   rightControls: {
     flexDirection: "row",

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

@@ -33,6 +33,7 @@ import {
   controlSizingForLayout,
   iconSizeFor,
   TOOLBAR_CONTROL_HEIGHT,
+  TOOLBAR_DISC_SIZE,
 } from "@/components/ui/control-geometry";
 import { ArrowUp, Mic, MicOff, CornerDownLeft, Plus, Square } from "lucide-react-native";
 import * as Haptics from "expo-haptics";
@@ -349,7 +350,11 @@ function VoiceButtonIcon({
   buttonIconSize: number;
 }) {
   if (isDictating) {
-    return <Square size={buttonIconSize} color="white" fill="white" />;
+    return (
+      <View style={styles.voiceButtonRecordingDisc}>
+        <Square size={buttonIconSize} color="white" fill="white" />
+      </View>
+    );
   }
   const colorMapping = hovered ? iconForegroundMapping : iconForegroundMutedMapping;
   if (isMutedRealtime) {
@@ -837,12 +842,14 @@ function SendButtonTooltip({
         testID={submitButtonTestID}
         style={sendButtonCombinedStyle}
       >
-        <SendButtonContent
-          isSubmitLoading={isSubmitLoading}
-          submitIcon={submitIcon}
-          submitLabel={submitLabel}
-          buttonIconSize={buttonIconSize}
-        />
+        <View style={submitLabel ? styles.sendButtonDiscLabeled : styles.sendButtonDisc}>
+          <SendButtonContent
+            isSubmitLoading={isSubmitLoading}
+            submitIcon={submitIcon}
+            submitLabel={submitLabel}
+            buttonIconSize={buttonIconSize}
+          />
+        </View>
       </TooltipTrigger>
       <TooltipContent side="top" align="center" offset={8}>
         <SendTooltipBody label={sendTooltipLabel} sendKeys={sendKeys} />
@@ -1925,7 +1932,6 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
         styles.voiceButton,
         Boolean(hovered) && !isDictating && styles.iconButtonHovered,
         !isDictationStartEnabled && styles.buttonDisabled,
-        isDictating && styles.voiceButtonRecording,
       ],
       [isDictating, isDictationStartEnabled],
     );
@@ -1974,12 +1980,8 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(
       allowEmpty: allowEmptySubmit,
     });
     const sendButtonCombinedStyle = useMemo(
-      () => [
-        styles.sendButton,
-        submitLabel ? styles.sendButtonLabeled : undefined,
-        isPresentedSendDisabled && styles.buttonDisabled,
-      ],
-      [isPresentedSendDisabled, submitLabel],
+      () => [styles.sendButton, isPresentedSendDisabled && styles.buttonDisabled],
+      [isPresentedSendDisabled],
     );
     const overlayContainerStyle = useMemo(
       () => [styles.overlayContainer, { opacity: surfacePresentation.overlay.opacity }],
@@ -2416,23 +2418,38 @@ const styles = StyleSheet.create((theme: Theme) => ({
     alignItems: "center",
     justifyContent: "center",
   },
-  voiceButtonRecording: {
-    backgroundColor: theme.colors.destructive,
-  },
-  sendButton: {
-    width: TOOLBAR_CONTROL_HEIGHT,
-    height: TOOLBAR_CONTROL_HEIGHT,
+  voiceButtonRecordingDisc: {
+    width: TOOLBAR_DISC_SIZE,
+    height: TOOLBAR_DISC_SIZE,
     borderRadius: theme.borderRadius.full,
-    backgroundColor: theme.colors.accent,
+    backgroundColor: theme.colors.destructive,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  // The trigger is the hit frame and stays unpainted; the disc inside it carries the fill.
+  sendButton: {
+    minWidth: TOOLBAR_CONTROL_HEIGHT,
+    height: TOOLBAR_CONTROL_HEIGHT,
     alignItems: "center",
     justifyContent: "center",
     marginLeft: theme.spacing[1],
   },
-  sendButtonLabeled: {
-    width: "auto",
-    minWidth: TOOLBAR_CONTROL_HEIGHT,
+  sendButtonDisc: {
+    width: TOOLBAR_DISC_SIZE,
+    height: TOOLBAR_DISC_SIZE,
+    borderRadius: theme.borderRadius.full,
+    backgroundColor: theme.colors.accent,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  sendButtonDiscLabeled: {
+    minWidth: TOOLBAR_DISC_SIZE,
+    height: TOOLBAR_DISC_SIZE,
     paddingHorizontal: theme.spacing[3],
     borderRadius: theme.borderRadius.full,
+    backgroundColor: theme.colors.accent,
+    alignItems: "center",
+    justifyContent: "center",
   },
   sendButtonLabel: {
     fontSize: theme.fontSize.base,

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

@@ -1,4 +1,4 @@
-import type { DiffState, OwnedSubscription, SubscriptionObserver } from "@getpaseo/client";
+import type { 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,21 +144,10 @@ function createFakeClient(config: { rejectCheckoutDiffSubscribe?: boolean } = {}
           ["status", "providers_snapshot_update"],
           () => {},
         ),
-      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,
-        };
+      observeCheckoutDiff(cwd, compare) {
         const subscriptionId = `server-diff-${subscribeCheckoutDiffCalls.length + 1}`;
         subscribeCheckoutDiffCalls.push({ cwd, compare, subscriptionId });
-        const handle = observe<SubscribeCheckoutDiffResponseMessage["payload"]>(
+        const handle = observe(
           { subscriptionId, cwd, files: [], error: null, requestId: "subscribe-checkout-diff" },
           ["checkout_diff_update", "subscribe_checkout_diff_response"],
           () => unsubscribeCheckoutDiffCalls.push(subscriptionId),
@@ -166,43 +155,9 @@ function createFakeClient(config: { rejectCheckoutDiffSubscribe?: boolean } = {}
             "subscriptionId" in message.payload &&
             message.payload.subscriptionId === subscriptionId,
         );
-        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;
+        if (!config.rejectCheckoutDiffSubscribe) return handle;
         return {
-          ...modern,
+          ...handle,
           subscribe: (observer) => {
             queueMicrotask(() => observer.error?.(new Error("subscribe failed")));
             return () => {};
@@ -373,7 +328,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("diff:1:ready");
+      expect(same.requestId).toBe("reopen");
       const changed = structuredClone(files);
       changed[0]!.hunks[0]!.lines[0]!.tokens![0]!.style = "variable";
       const next = publish(changed, "edit");
@@ -475,7 +430,7 @@ describe("server data push router", () => {
       files: [],
       error: null,
       diffTooLarge: true,
-      requestId: "diff:1:ready",
+      requestId: "diff-1",
     });
 
     fake.emit({
@@ -494,7 +449,7 @@ describe("server data push router", () => {
       files: [],
       error: null,
       diffTooLarge: true,
-      requestId: "diff:2:ready",
+      requestId: `subscription:${serverSubscriptionId}`,
     });
 
     unsubscribeObserver();

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

@@ -1,5 +1,3 @@
-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";
@@ -25,9 +23,14 @@ 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 CheckoutDiffCachePayload = CheckoutDiffSnapshot;
+type CheckoutDiffResponsePayload = SubscribeCheckoutDiffResponseMessage["payload"];
+type CheckoutDiffCachePayload = Omit<CheckoutDiffResponsePayload, "subscriptionId">;
 type ListTerminalsPayload = ListTerminalsResponse["payload"];
 
 interface CheckoutDiffCompare {
@@ -46,7 +49,7 @@ interface CheckoutDiffRoute {
 }
 
 interface CheckoutDiffRegistration extends CheckoutDiffRoute {
-  subscription: OwnedSubscription<DiffState>;
+  subscription: OwnedSubscription<CheckoutDiffResponsePayload>;
 }
 
 interface WorkspaceTerminalsRoute {
@@ -72,7 +75,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"];
-  observeDiff: import("@getpaseo/client/internal/daemon-client").DaemonClient["observeDiff"];
+  observeCheckoutDiff: import("@getpaseo/client/internal/daemon-client").DaemonClient["observeCheckoutDiff"];
   observeTerminals: import("@getpaseo/client/internal/daemon-client").DaemonClient["observeTerminals"];
 }
 
@@ -336,34 +339,34 @@ function reconcileCheckoutDiffSubscriptions(input: {
   }
   for (const [key, desired] of input.desired) {
     if (input.active.has(key)) continue;
-    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 subscription = input.client.observeCheckoutDiff(desired.cwd, desired.compare);
     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: (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) },
-        });
+      snapshot: apply,
+      update: (message) => {
+        if (message.type === "checkout_diff_update") apply(message.payload);
       },
-      update: () => {},
       error: (error) => {
         if (input.active.get(key) === registration) input.active.delete(key);
-        console.error("[server-data] observeDiff failed", {
+        console.error("[server-data] observeCheckoutDiff 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 { DiffFileHeader } from "@/git/diff-snapshot";
+import type { ParsedDiffFile } from "@/git/use-diff-query";
 
 export interface ChangedFilesTreeProps {
-  files: DiffFileHeader[];
+  files: ParsedDiffFile[];
   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" ? [files[row.fileIndex]] : [],
+    row.kind === "file" ? [row.file] : [],
   );
 }

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

@@ -1,4 +1,3 @@
-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";
@@ -1096,7 +1095,6 @@ interface DiffBodyContentProps {
   emptyMessage: string;
   emptyAction: ChangesEmptyAction | null;
   children: ReactElement;
-  loadingLabel: string;
   checkingRepositoryLabel: string;
   notRepositoryLabel: string;
 }
@@ -1113,16 +1111,11 @@ function DiffBodyContent({
   emptyAction,
   children,
   checkingRepositoryLabel,
-  loadingLabel,
   notRepositoryLabel,
 }: DiffBodyContentProps) {
   if (isStatusLoading) {
     return (
-      <View
-        style={styles.loadingContainer}
-        accessibilityRole="progressbar"
-        accessibilityLabel={loadingLabel}
-      >
+      <View style={styles.loadingContainer}>
         <ThemedLoadingSpinner size="large" uniProps={foregroundMutedIconColorMapping} />
         <Text style={styles.loadingText}>{checkingRepositoryLabel}</Text>
       </View>
@@ -1144,16 +1137,12 @@ function DiffBodyContent({
   }
   if (isDiffLoading) {
     return (
-      <View
-        style={styles.loadingContainer}
-        accessibilityRole="progressbar"
-        accessibilityLabel={loadingLabel}
-      >
+      <View style={styles.loadingContainer}>
         <ThemedLoadingSpinner size="large" uniProps={foregroundMutedIconColorMapping} />
       </View>
     );
   }
-  if (diffTooLarge && !hasChanges) {
+  if (diffTooLarge) {
     return <DiffTooLargeState />;
   }
   if (diffErrorMessage) {
@@ -1332,7 +1321,7 @@ function ChangesTreeRail({
 }: {
   shown: boolean;
   children: ReactElement;
-  files: DiffFileHeader[];
+  files: ParsedDiffFile[];
   mode: WorkingDiffMode;
   onSelectFile: (path: string) => void;
   treeWidth?: number;
@@ -1372,7 +1361,7 @@ function ChangesBody({
   children: ReactElement;
   desktopTreeVisible: boolean;
   isMobile: boolean;
-  files: DiffFileHeader[];
+  files: ParsedDiffFile[];
   mode: WorkingDiffMode;
   onSelectFile: (path: string) => void;
   treeWidth?: number;
@@ -1597,7 +1586,6 @@ export function ChangesSurface({
     selectBase: handleSelectBase,
     selectAll: handleSelectAll,
     files,
-    treeFiles,
     diffPayloadError,
     diffTooLarge,
     isDiffLoading,
@@ -1847,7 +1835,6 @@ 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")}
       >
@@ -1878,7 +1865,7 @@ export function ChangesSurface({
       presentation={presentation}
       desktopTreeVisible={desktopTreeVisible}
       isMobile={isMobile}
-      files={treeFiles}
+      files={files}
       mode={workingMode}
       onSelectFile={handleSelectTreeFile}
       treeWidth={instanceState.treeWidth}

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

@@ -1,8 +1,7 @@
 import { replaceEqualDeep } from "@tanstack/react-query";
-import type { CheckoutDiffSnapshot } from "./diff-snapshot";
-import type { ParsedDiffFile } from "@getpaseo/protocol/messages";
+import type { ParsedDiffFile, SubscribeCheckoutDiffResponse } from "@getpaseo/protocol/messages";
 
-type DiffPayload = CheckoutDiffSnapshot;
+type DiffPayload = Omit<SubscribeCheckoutDiffResponse["payload"], "subscriptionId">;
 
 /** File identity owns text-model reuse. Never reconstruct the hunk/token graph. */
 export function retainDiffFiles(
@@ -31,7 +30,6 @@ 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

@@ -1,74 +0,0 @@
-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 { DiffFileHeader } from "@/git/diff-snapshot";
+import type { ParsedDiffFile } from "@/git/use-diff-query";
 
-// Builds a directory hierarchy from the `DiffFileHeader[]` the Changes view
+// Builds a directory hierarchy from the `ParsedDiffFile[]` the Changes view
 // renders. The tree renders on every form factor, consistent with the Files
 // explorer.
 //
@@ -17,7 +17,7 @@ import type { DiffFileHeader } from "@/git/diff-snapshot";
 
 export interface DiffTreeFileNode {
   kind: "file";
-  file: DiffFileHeader;
+  file: ParsedDiffFile;
   fileIndex: number;
   /** basename, e.g. "diff-pane.tsx" */
   name: string;
@@ -47,7 +47,7 @@ export interface DiffTreeFolderRow {
 
 export interface DiffTreeFileRow {
   kind: "file";
-  file: DiffFileHeader;
+  file: ParsedDiffFile;
   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: DiffFileHeader[]): DiffTreeDirNode {
+export function buildDiffTree(files: ParsedDiffFile[]): 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 { DiffFileHeader } from "@/git/diff-snapshot";
+import type { ParsedDiffFile } from "@/git/use-diff-query";
 import { inlineUnistylesStyle } from "@/styles/unistyles-inline-style";
 
 export interface FileHeaderProps {
-  file: DiffFileHeader;
+  file: ParsedDiffFile;
   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: DiffFileHeader) {
+function fileHeaderAccessibilityLabel(canvasRendered: boolean, file: ParsedDiffFile) {
   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: DiffFileHeader): "added" | "deleted" | "modified" {
+function fileChange(file: ParsedDiffFile): "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 "./diff-snapshot";
+import { deriveCheckoutDiffResult } from "./use-diff-query";
 
 function createParsedDiffFile(path: string): ParsedDiffFile {
   return {
@@ -59,7 +59,6 @@ describe("deriveCheckoutDiffResult", () => {
 
     expect(result).toEqual({
       files: [],
-      entries: null,
       payloadError: error,
       diffTooLarge: true,
       isLoading: false,
@@ -69,27 +68,3 @@ 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,13 +5,7 @@ import { useRetainedPanelActive } from "@/components/retained-panel";
 import { useReplicaQuery } from "@/data/query";
 import { checkoutDiffPushRoute } from "@/data/push-router";
 import { useHostRuntimeIsConnected } from "@/runtime/host-runtime";
-import {
-  checkoutDiffComparisonError,
-  deriveCheckoutDiffResult,
-  type CheckoutDiffSnapshot,
-} from "./diff-snapshot";
-export { deriveCheckoutDiffResult } from "./diff-snapshot";
-import type { ParsedDiffFile } from "@getpaseo/protocol/messages";
+import type { ParsedDiffFile, SubscribeCheckoutDiffResponse } from "@getpaseo/protocol/messages";
 import { checkoutDiffQueryKey } from "@/git/query-keys";
 
 interface UseCheckoutDiffQueryOptions {
@@ -24,7 +18,7 @@ interface UseCheckoutDiffQueryOptions {
   queryScope?: string;
 }
 
-type CheckoutDiffQueryPayload = CheckoutDiffSnapshot;
+type CheckoutDiffQueryPayload = Omit<SubscribeCheckoutDiffResponse["payload"], "subscriptionId">;
 
 // Re-export the canonical protocol type so all consumers share one definition.
 export type { ParsedDiffFile };
@@ -83,11 +77,7 @@ export function useCheckoutDiffQuery({
     return normalizedScope ? [...comparisonKey, "scope", normalizedScope] : comparisonKey;
   }, [serverId, cwd, compareMode, compareBaseRef, compareIgnoreWhitespace, queryScope]);
   const subscriptionId = useMemo(() => `checkoutDiff:${JSON.stringify(queryKey)}`, [queryKey]);
-  const comparisonError =
-    queryEnabled && isConnected ? checkoutDiffComparisonError(normalizedCompare) : null;
-  const routeEnabled = Boolean(
-    queryEnabled && isConnected && cwd && !requiresUpdate && !comparisonError,
-  );
+  const routeEnabled = Boolean(queryEnabled && isConnected && cwd && !requiresUpdate);
 
   const query = useReplicaQuery<CheckoutDiffQueryPayload>({
     queryKey,
@@ -107,13 +97,46 @@ export function useCheckoutDiffQuery({
     }),
   });
 
-  const boundaryError =
-    requiresUpdate && isConnected
-      ? { code: "UNKNOWN" as const, message: "Update the host to view All changes" }
-      : comparisonError;
   return deriveCheckoutDiffResult(
-    boundaryError
-      ? { requestId: "unavailable", cwd, files: [], error: boundaryError }
+    requiresUpdate && isConnected
+      ? {
+          requestId: "unsupported",
+          cwd,
+          files: [],
+          error: { code: "UNKNOWN", message: "Update the host to view All changes" },
+        }
       : (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,8 +9,6 @@ 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";
@@ -46,11 +44,7 @@ export function useWorkingDiff({
   const statusErrorMessage =
     status?.error?.message ??
     (isStatusError && statusError instanceof Error ? statusError.message : null);
-  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 baseRef = gitStatus?.baseRef ?? undefined;
   const currentBranchName =
     gitStatus?.currentBranch && gitStatus.currentBranch !== "HEAD" ? gitStatus.currentBranch : null;
 
@@ -65,7 +59,6 @@ export function useWorkingDiff({
 
   const {
     files,
-    entries,
     payloadError: diffPayloadError,
     diffTooLarge,
     isLoading: isDiffLoading,
@@ -78,7 +71,6 @@ export function useWorkingDiff({
     enabled: enabled && isGit,
     queryScope,
   });
-  const treeFiles = useMemo(() => (entries ? diffEntryHeaders(entries) : files), [entries, files]);
   const reviewDraftKey = useMemo(
     () =>
       buildReviewDraftKey({
@@ -120,7 +112,6 @@ export function useWorkingDiff({
     selectBase,
     selectAll,
     files,
-    treeFiles,
     diffPayloadError,
     diffTooLarge,
     isDiffLoading,

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -78,7 +78,8 @@ import {
   deriveRouteBottomAnchorIntent,
   deriveRouteBottomAnchorRequest,
 } from "@/screens/agent/agent-ready-screen-bottom-anchor";
-import { WorkspaceDraftAgentTab } from "@/composer/draft/workspace-tab";
+import { WorkspaceDraftComposer } from "@/composer/draft/workspace-tab";
+import { type DraftConversation, useDraftTimeline } from "@/composer/draft/timeline";
 import { AgentTracks } from "@/panels/agent-tracks";
 import { ParentAgentCallout, useParentAgentId } from "@/subagents/parent";
 import { useCreateFlowStore } from "@/stores/create-flow-store";
@@ -90,14 +91,13 @@ import {
   useSessionStore,
 } from "@/stores/session-store";
 import { useWorkspaceLayoutStore } from "@/stores/workspace-layout-store";
-import { buildWorkspaceTabPersistenceKey } from "@/workspace-tabs/model";
+import { buildWorkspaceTabPersistenceKey, type WorkspaceTabTarget } 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, TodoEntry } from "@/types/stream";
+import type { StreamItem } 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,6 +225,29 @@ 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;
@@ -303,17 +326,31 @@ function storeFetchedAgentDetail(input: {
   return hydrated;
 }
 
-function AgentPanel() {
+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() {
   const { serverId, workspaceId, target, openFileInWorkspace } = usePaneContext();
   const { isInteractive } = usePaneFocus();
-  invariant(target.kind === "agent", "AgentPanel requires agent target");
+  invariant(
+    target.kind === "agent" || target.kind === "draft",
+    "AgentConversationPanel requires an agent or draft target",
+  );
 
   return (
     <RetainedChatContent>
       <AgentPanelContent
         serverId={serverId}
         workspaceId={workspaceId}
-        agentId={target.agentId}
+        target={target}
         isPaneFocused={isInteractive}
         onOpenWorkspaceFile={openFileInWorkspace}
       />
@@ -321,55 +358,6 @@ function AgentPanel() {
   );
 }
 
-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,
@@ -444,18 +432,18 @@ type AgentLookupState =
 function AgentPanelContent({
   serverId,
   workspaceId,
-  agentId,
+  target,
   isPaneFocused,
   onOpenWorkspaceFile,
 }: {
   serverId: string;
   workspaceId: string;
-  agentId: string;
+  target: ConversationTarget;
   isPaneFocused: boolean;
   onOpenWorkspaceFile?: (request: WorkspaceFileOpenRequest) => void;
 }) {
   const { t } = useTranslation();
-  const resolvedAgentId = agentId.trim() || undefined;
+  const resolvedAgentId = resolveConversationAgentId(target);
   const resolvedServerId = serverId.trim() || undefined;
   const daemons = useHosts();
   const runtimeServerId = resolvedServerId ?? "";
@@ -484,7 +472,7 @@ function AgentPanelContent({
       : runtimeConnectionStatus;
   const lastConnectionError = runtimeLastError;
 
-  if (!resolvedServerId || (!runtimeClient && !hasCachedAgent)) {
+  if (target.kind === "agent" && (!resolvedServerId || (!runtimeClient && !hasCachedAgent))) {
     return (
       <AgentSessionUnavailableState
         serverLabel={serverLabel}
@@ -498,9 +486,9 @@ function AgentPanelContent({
 
   return (
     <AgentPanelBody
-      serverId={resolvedServerId}
+      serverId={resolvedServerId ?? serverId}
       workspaceId={workspaceId}
-      agentId={resolvedAgentId}
+      target={target}
       isPaneFocused={isPaneFocused}
       client={runtimeClient}
       isConnected={runtimeIsConnected}
@@ -512,7 +500,7 @@ function AgentPanelContent({
 function AgentPanelBody({
   serverId,
   workspaceId,
-  agentId,
+  target,
   isPaneFocused,
   client,
   isConnected,
@@ -520,13 +508,14 @@ function AgentPanelBody({
 }: {
   serverId: string;
   workspaceId: string;
-  agentId?: string;
+  target: ConversationTarget;
   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(
@@ -641,7 +630,7 @@ function AgentPanelBody({
         }
       : null;
 
-  if (!agent) {
+  if (target.kind === "agent" && !agent) {
     return (
       <View style={styles.container} testID="agent-loading">
         <View style={styles.errorContainer}>
@@ -655,7 +644,7 @@ function AgentPanelBody({
     <ChatAgentContent
       serverId={serverId}
       workspaceId={workspaceId}
-      agentId={agentId}
+      target={target}
       isPaneFocused={isPaneFocused}
       client={client}
       isConnected={isConnected}
@@ -667,7 +656,7 @@ function AgentPanelBody({
 function ChatAgentContent({
   serverId,
   workspaceId,
-  agentId,
+  target,
   isPaneFocused,
   client,
   isConnected,
@@ -675,13 +664,15 @@ function ChatAgentContent({
 }: {
   serverId: string;
   workspaceId: string;
-  agentId?: string;
+  target: ConversationTarget;
   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();
@@ -988,17 +979,23 @@ function ChatAgentContent({
     visibilityCatchUpStatus,
   ]);
 
-  const nonReadyView = renderChatAgentNonReadyView({
+  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,
     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" &&
@@ -1013,7 +1010,8 @@ function ChatAgentContent({
     <ChatAgentReadyContent
       serverId={serverId}
       workspaceId={workspaceId}
-      agentId={agentId}
+      agentId={agentId ?? tabId}
+      draft={draft}
       isPaneFocused={isPaneFocused}
       isArchivingCurrentAgent={isArchivingCurrentAgent}
       agentState={agentState}
@@ -1031,7 +1029,7 @@ function ChatAgentContent({
       showHistorySyncOverlay={showHistorySyncOverlay}
       showHistorySyncError={showHistorySyncError}
       isRetryingHistorySync={isRetryingHistorySync}
-      cwd={agentCwd}
+      cwd={agentState.cwd ?? ""}
       retryTimelineSync={retryTimelineSync}
       onAttentionInputFocus={attentionController.clearOnInputFocus}
       onAttentionPromptSend={attentionController.clearOnPromptSend}
@@ -1044,6 +1042,7 @@ const ChatAgentReadyContent = memo(function ChatAgentReadyContent({
   serverId,
   workspaceId,
   agentId,
+  draft,
   isPaneFocused,
   isArchivingCurrentAgent,
   agentState,
@@ -1069,11 +1068,13 @@ 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;
+  effectiveAgent: AgentScreenAgent | null;
   routeBottomAnchorRequest: RouteBottomAnchorRequest;
   hasAppliedAuthoritativeHistory: boolean;
   toastApi: ToastApi;
@@ -1095,19 +1096,11 @@ 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 showsComposer = usePaneContext().host !== "sheet";
+  const paneHost = usePaneContext().host;
+  const showsComposer = draft !== null || paneHost !== "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.
@@ -1161,7 +1154,7 @@ const ChatAgentReadyContent = memo(function ChatAgentReadyContent({
   const parentCallout = parentAgentId ? (
     <ParentAgentCallout serverId={serverId} parentAgentId={parentAgentId} />
   ) : null;
-  const composerSection = showsComposer ? (
+  const agentComposerSection = showsComposer ? (
     <RenderProfile id={`AgentComposerSection:${agentId}`}>
       <AgentComposerSection
         agentId={agentId}
@@ -1182,6 +1175,16 @@ 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} />}
@@ -1191,6 +1194,7 @@ const ChatAgentReadyContent = memo(function ChatAgentReadyContent({
           serverId={serverId}
           agentId={agentId}
           agent={effectiveAgent}
+          draft={draft}
           routeBottomAnchorRequest={routeBottomAnchorRequest}
           hasAppliedAuthoritativeHistory={hasAppliedAuthoritativeHistory}
           hasActiveComposer={hasActiveComposer}
@@ -1198,16 +1202,12 @@ const ChatAgentReadyContent = memo(function ChatAgentReadyContent({
           onOpenWorkspaceFile={onOpenWorkspaceFile}
         />
       </RenderProfile>
-      {hasActiveComposer ? (
+      {hasActiveComposer && !draft ? (
         <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,
+    enabled: showsComposer && hasActiveComposer && !draft,
     serverId,
     agentId,
     editingSession: composerEditingSession,
@@ -1355,6 +1355,7 @@ const AgentStreamSection = memo(function AgentStreamSection({
   serverId,
   agentId,
   agent,
+  draft,
   routeBottomAnchorRequest,
   hasAppliedAuthoritativeHistory,
   hasActiveComposer,
@@ -1364,7 +1365,8 @@ const AgentStreamSection = memo(function AgentStreamSection({
   streamViewRef: React.RefObject<AgentStreamViewHandle | null>;
   serverId: string;
   agentId?: string;
-  agent: AgentScreenAgent;
+  agent: AgentScreenAgent | null;
+  draft: DraftConversation | null;
   routeBottomAnchorRequest: RouteBottomAnchorRequest;
   hasAppliedAuthoritativeHistory: boolean;
   hasActiveComposer: boolean;
@@ -1422,7 +1424,31 @@ 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}
@@ -1443,6 +1469,44 @@ 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 {
-  type ArchiveFinishedStatus,
+  useArchiveFinishedSubagents,
   useArchiveSubagent,
   useDetachSubagent,
   useSubagentSheetTab,
-  type SubagentRow,
+  useSubagentsForParent,
 } from "@/subagents";
 import { ParentAgentPill } from "@/subagents/parent";
 import { SubagentsTrack } from "@/subagents/track";
@@ -35,20 +35,21 @@ 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);
@@ -119,8 +120,8 @@ export const AgentTracks = memo(function AgentTracks({
         onOpenProviderSubagent={handleOpenProviderSubagent}
         sheetTabFor={sheetTabFor}
         onArchiveSubagent={archiveSubagent}
-        onArchiveFinished={onArchiveFinished}
-        archiveFinishedStatus={archiveFinishedStatus}
+        onArchiveFinished={archiveFinishedSubagents.archiveFinished}
+        archiveFinishedStatus={archiveFinishedSubagents.status}
         onDetachSubagent={canDetachSubagents ? detachSubagent : undefined}
       />
       <PluginComposerPills

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

@@ -390,4 +390,39 @@ 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,6 +21,26 @@ 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 =
@@ -59,7 +79,8 @@ export class AgentStoreProjection {
     let accepted = agent;
     useSessionStore.getState().setAgents(this.serverId, (current) => {
       const previous = current.get(agent.id);
-      accepted = acceptAgentDirectoryUpdate(previous, mergeSnapshotTurn(previous, agent));
+      const winner = acceptAgentDirectoryUpdate(previous, mergeSnapshotTurn(previous, agent));
+      accepted = previous ? keepUnchangedFields(previous, winner) : winner;
       if (accepted === previous) return current;
       const next = new Map(current);
       next.set(agent.id, accepted);
@@ -117,7 +138,7 @@ export class AgentStoreProjection {
     for (const [agentId, fetchedAgent] of fetched) {
       const existing = current.get(agentId);
       const merged = mergeSnapshotTurn(existing, fetchedAgent);
-      agents.set(agentId, existing && equal(existing, merged) ? existing : merged);
+      agents.set(agentId, existing ? keepUnchangedFields(existing, merged) : merged);
       if (fetchedAgent.archivedAt) {
         clearArchiveAgentPending({ queryClient, serverId: this.serverId, agentId });
       }

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

@@ -321,6 +321,26 @@ describe("ReplicaCache", () => {
     expect(restored?.range).toBeNull();
   });
 
+  it("preserves workspace parentage and its checkpoint across cache reopen", async () => {
+    const storage = new MemoryStorage();
+    const writer = createCache(storage);
+    const baseline = directory({ workspaces: { generation: "g", afterSeq: 8 } });
+    const workspace = normalizeWorkspaceDescriptor({
+      ...workspacePayload(),
+      parentWorkspaceId: "parent",
+    });
+    baseline.workspaces.set(workspace.id, workspace);
+    commitDirectory(writer, SERVER_ID, baseline);
+    await writer.flush();
+    const reader = createCache(storage);
+    const restored = await reader.readDirectory(SERVER_ID);
+    expect(restored.checkpoint).toEqual(baseline.checkpoint);
+    expect(restored.workspaces.get(workspace.id)?.parentWorkspaceId).toBe("parent");
+    expect((await reader.readWorkspace(SERVER_ID, workspace.id))?.workspace.parentWorkspaceId).toBe(
+      "parent",
+    );
+  });
+
   it("preserves workspace sorting timestamps across cache reopen", async () => {
     const storage = new MemoryStorage();
     const writer = createCache(storage);

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

@@ -299,6 +299,7 @@ const WorkspaceGitRuntimeSchema = z
   .optional();
 
 const StoredWorkspaceSchema = z.strictObject({
+  parentWorkspaceId: z.string().optional(),
   // Require both keys: a cursor without these values would preserve the wrong sort on reconnect.
   createdAt: IsoDateSchema.nullable(),
   lastUserMessageAt: IsoDateSchema.nullable(),
@@ -707,6 +708,7 @@ function restoreWorkspace(stored: StoredWorkspace): WorkspaceDescriptor {
 
 function serializeWorkspace(workspace: WorkspaceDescriptor): StoredWorkspace {
   return {
+    parentWorkspaceId: workspace.parentWorkspaceId,
     createdAt: workspace.createdAt?.toISOString() ?? null,
     lastUserMessageAt: workspace.lastUserMessageAt?.toISOString() ?? null,
     id: workspace.id,

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

@@ -870,8 +870,12 @@ 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";
+  return supportsStreamTopOverlay && (activeTab?.kind === "agent" || activeTab?.kind === "draft");
 }
 
 /** A fullscreen composer covers the compact header; the column lays out without it. */

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

@@ -557,6 +557,33 @@ describe("normalizeWorkspaceDescriptor", () => {
     expect(blank.workspaceDirectory).toBe("");
   });
 
+  it("preserves informational workspace parentage", () => {
+    const payload = {
+      id: "child",
+      parentWorkspaceId: "parent",
+      projectId: "1",
+      projectDisplayName: "Project 1",
+      projectRootPath: "/repo",
+      workspaceDirectory: "/repo",
+      projectKind: "git",
+      workspaceKind: "checkout",
+      name: "main",
+      archivingAt: null,
+      status: "done",
+      statusEnteredAt: null,
+      activityAt: null,
+      diffStat: null,
+      scripts: [],
+    } as WorkspaceDescriptorPayload;
+
+    const workspace = normalizeWorkspaceDescriptor(payload);
+
+    expect(workspace.parentWorkspaceId).toBe("parent");
+    expect(
+      normalizeWorkspaceDescriptor({ ...payload, parentWorkspaceId: undefined }).parentWorkspaceId,
+    ).toBeUndefined();
+  });
+
   it("defaults missing scripts to an empty array", () => {
     const payload = {
       id: "1",

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

@@ -105,6 +105,7 @@ export interface Agent {
 }
 
 export interface WorkspaceDescriptor {
+  parentWorkspaceId?: string;
   createdAt: Date | null;
   lastUserMessageAt: Date | null;
   id: string;
@@ -162,6 +163,7 @@ export function normalizeWorkspaceDescriptor(
     projectKind: payload.projectKind,
     workspaceKind: payload.workspaceKind,
     background: payload.background ?? false,
+    parentWorkspaceId: payload.parentWorkspaceId,
     name: payload.name,
     title: payload.title ?? null,
     pinnedAt: payload.pinnedAt ?? null,

packages/app/src/usage/queries.ts

@@ -33,9 +33,10 @@ import {
 } from "./model";
 import type { UsageReportEntry, UsageView } from "./types";
 
-// The daemon caches each report for five minutes, so re-reading it is cheap. Only
-// an explicit refresh passes `forceRefresh` and reaches the source's API.
+// The daemon caches each report for five minutes, so re-reading it is cheap.
+// An explicit refresh passes `forceRefresh` to bypass that cache.
 const REPORTS_STALE_TIME_MS = 60_000;
+const REPORTS_REFETCH_INTERVAL_MS = 5 * 60_000;
 
 /** Every report list of a host: its own and each agent's. */
 function hostUsageQueryKey(serverId: string) {
@@ -164,11 +165,16 @@ export function useHostUsage(serverId: string): { view: UsageView; refresh: () =
 
 const NO_REPORTS: UsageReportEntry[] = [];
 
-/**
- * The reports of the sidebar's usage host, which is connected and reports usage; none until they
- * load, or without a host.
- */
-export function useUsageHostReports(serverId: string | null): UsageReportEntry[] {
+interface UsageHostReportsInput {
+  serverId: string | null;
+  shouldPoll?: boolean;
+}
+
+/** A host's reports, with periodic refresh enabled only by the visible sidebar summary. */
+export function useUsageHostReports({
+  serverId,
+  shouldPoll = false,
+}: UsageHostReportsInput): UsageReportEntry[] {
   const setting = useUsageSetting(serverId);
   const queryClient = useQueryClient();
   const query = useFetchQuery({
@@ -177,6 +183,7 @@ export function useUsageHostReports(serverId: string | null): UsageReportEntry[]
     queryFn: serverId ? () => listReports(queryClient, serverId) : skipToken,
     dataShape: "list",
     staleTimeMs: REPORTS_STALE_TIME_MS,
+    refetchInterval: shouldPoll ? REPORTS_REFETCH_INTERVAL_MS : false,
   });
   return setting.enabled ? (query.data ?? NO_REPORTS) : NO_REPORTS;
 }

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

@@ -16,6 +16,8 @@ import {
   type PressableStateCallbackType,
 } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
+import { useRetainedPanelActive } from "@/components/retained-panel";
+import { useAppVisible } from "@/hooks/use-app-visible";
 import { builtinSidebarNavLabelKey } from "@/sidebar-nav/model";
 import { useUsageDisplay } from "./display";
 import { useUsageInSidebar } from "./in-sidebar";
@@ -36,9 +38,14 @@ import { UsageModal } from "./usage-modal";
 /** Each summary window with data on the usage host, under its source; empty while none has. */
 export function useUsageSummary(): readonly PinnedUsageSource[] {
   const { t } = useTranslation();
+  const active = useRetainedPanelActive();
+  const isAppVisible = useAppVisible();
   const { inSidebar } = useUsageInSidebar();
   const serverId = useUsageHostId();
-  const reports = useUsageHostReports(inSidebar ? serverId : null);
+  const reports = useUsageHostReports({
+    serverId: inSidebar ? serverId : null,
+    shouldPoll: active && inSidebar && isAppVisible,
+  });
   const { preferences } = useUsageDisplay(reports);
   return useMemo(() => resolvePinnedUsage(reports, preferences, t), [preferences, reports, t]);
 }

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

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

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

@@ -1,38 +0,0 @@
-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,9 +1,3 @@
-import {
-  DiffStreamRouter,
-  DiffSubscriptionError,
-  type DiffCompare,
-  type DiffState,
-} from "./diff/index.js";
 import {
   ChunkedTransport,
   ChunkedTransportProtocolError,
@@ -1417,20 +1411,6 @@ 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>();
@@ -1780,7 +1760,6 @@ 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"));
@@ -2684,12 +2663,7 @@ export class DaemonClient {
   private observe<T extends CorrelatedResponseType>(
     responseType: T,
     message: { type: SessionInboundMessage["type"] } & Record<string, unknown>,
-    options?: {
-      requestId?: string;
-      timeout?: number;
-      signal?: AbortSignal;
-      validateSnapshot?: (payload: CorrelatedResponsePayload<T>) => void;
-    },
+    options?: { requestId?: string; timeout?: number; signal?: AbortSignal },
   ): OwnedSubscription<CorrelatedResponsePayload<T>> {
     let resetSource = false;
     return this.owned.observeRequest<CorrelatedResponsePayload<T>>(
@@ -2715,16 +2689,12 @@ export class DaemonClient {
                   requestType: message.type,
                   error: payload.error,
                 });
-              options?.validateSnapshot?.(payload);
               accept(payload);
               return payload;
             },
           });
         } catch (error) {
-          resetSource =
-            !(error instanceof DaemonRpcError) &&
-            !(error instanceof DiffSubscriptionError) &&
-            this.isConnected;
+          resetSource = !(error instanceof DaemonRpcError) && this.isConnected;
           throw error;
         }
       },
@@ -4690,26 +4660,6 @@ 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 },
@@ -6986,7 +6936,6 @@ export class DaemonClient {
     this.chunkedTransport?.close();
     this.chunkedTransport = null;
     this.owned.disconnected();
-    this.diffStreams.disconnected();
     this.providerSnapshotUpdates.clear();
     this.stopLivenessHeartbeat();
     this.cleanupTransport();
@@ -7177,10 +7126,6 @@ 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;
@@ -7381,7 +7326,6 @@ export class DaemonClient {
     }
 
     this.owned.disconnected();
-    this.diffStreams.disconnected();
     this.providerSnapshotUpdates.clear();
 
     // Clear all pending waiters and queued sends since the connection was lost
@@ -7541,7 +7485,6 @@ 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,
@@ -7818,5 +7761,3 @@ 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

@@ -1,210 +0,0 @@
-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

@@ -1,246 +0,0 @@
-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

@@ -1,86 +0,0 @@
-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

@@ -1,94 +0,0 @@
-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,5 +1212,3 @@ 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,4 +1,3 @@
-import { decodeDiffFrame, DiffOpcode, type DiffFrame } from "./diff.js";
 import { HOST_ROUTE_OPCODE, decodeHostRouteFrame, type HostRouteFrame } from "./host-route.js";
 import {
   decodeFileTransferFrame,
@@ -13,20 +12,12 @@ 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

@@ -1,270 +0,0 @@
-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

@@ -1,360 +0,0 @@
-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,4 +3,3 @@ 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

@@ -1,24 +0,0 @@
-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,51 +2288,6 @@ 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(),
@@ -3473,8 +3428,6 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
   AgentDetachRequestMessageSchema,
   AgentRewindRequestMessageSchema,
   AgentPermissionResponseMessageSchema,
-  DiffSubscribeRequestSchema,
-  DiffUnsubscribeRequestSchema,
   CheckoutStatusRequestSchema,
   CheckoutDiffGetRequestSchema,
   SubscribeCheckoutDiffRequestSchema,
@@ -3934,7 +3887,6 @@ 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(),
@@ -4237,6 +4189,8 @@ export const WorkspaceGitHubRuntimePayloadSchema = z
 
 export const WorkspaceDescriptorPayloadSchema = z
   .object({
+    // Informational creation ancestry; independent of placement and lifecycle.
+    parentWorkspaceId: z.string().optional(),
     id: z.string(),
     projectId: z.string(),
     projectDisplayName: z.string(),
@@ -5476,7 +5430,6 @@ 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
@@ -7284,7 +7237,6 @@ export const SessionOutboundMessageSchema = z.discriminatedUnion("type", [
   AgentDeletedMessageSchema,
   AgentArchivedMessageSchema,
   CloseItemsResponseSchema,
-  DiffSubscribeResponseSchema,
   CheckoutStatusResponseSchema,
   CheckoutStatusUpdateSchema,
   CheckoutDiffGetResponseSchema,

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

@@ -634,6 +634,26 @@ describe("workspace message schemas", () => {
     ]);
   });
 
+  test("preserves informational workspace parentage in directory updates", () => {
+    const workspace = {
+      id: "child",
+      parentWorkspaceId: "parent",
+      projectId: "project",
+      projectDisplayName: "repo",
+      projectRootPath: "/repo",
+      projectKind: "git",
+      workspaceKind: "worktree",
+      name: "child",
+      status: "done",
+      activityAt: null,
+    };
+    expect(WorkspaceDescriptorPayloadSchema.parse(workspace).parentWorkspaceId).toBe("parent");
+    expect(
+      WorkspaceDescriptorPayloadSchema.parse({ ...workspace, parentWorkspaceId: undefined })
+        .parentWorkspaceId,
+    ).toBeUndefined();
+  });
+
   test("parses legacy workspace descriptors without workspaceDirectory", () => {
     const parsed = SessionOutboundMessageSchema.parse({
       type: "workspace_update",

packages/server/package.json

@@ -102,8 +102,7 @@
     "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",
-    "measure:diff-subscriptions": "tsx scripts/measure-diff-subscriptions.ts"
+    "test:e2e:ui": "vitest --ui e2e.test.ts"
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "^0.17.1",

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

@@ -1,111 +0,0 @@
-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,12 +1197,43 @@ describe("Suite E: Workspace Tools", () => {
       });
       ownedWorkspaces.push(str(inherited.workspaceId));
       expect(inherited.background).toBe(true);
+      expect(inherited.parentWorkspaceId).toBe(parentWorkspaceId);
       const visible = await callToolStructured(scoped, "create_workspace", {
         isolation: "local",
         background: false,
       });
       ownedWorkspaces.push(str(visible.workspaceId));
       expect(visible.background).toBe(false);
+      expect(visible.parentWorkspaceId).toBe(parentWorkspaceId);
+      const worktree = await callToolStructured(scoped, "create_workspace", {
+        isolation: "worktree",
+        branchName: "parentage-child",
+        baseBranch: "main",
+        background: false,
+      });
+      ownedWorkspaces.push(str(worktree.workspaceId));
+      expect(worktree.parentWorkspaceId).toBe(parentWorkspaceId);
+      const client = new DaemonClient({ url: `ws://127.0.0.1:${daemonHandle.port}/ws` });
+      try {
+        await client.connect();
+        const created = await client.createWorkspace({
+          source: { kind: "directory", path: worktreeRepoCwd },
+          callerAgentId: str(parent.agentId),
+          background: false,
+        });
+        const workspaceId = str(created.workspace?.id);
+        ownedWorkspaces.push(workspaceId);
+        expect(created.workspace?.parentWorkspaceId).toBe(parentWorkspaceId);
+        const listed = await client.fetchWorkspaces();
+        expect(listed.entries).toContainEqual(
+          expect.objectContaining({
+            id: workspaceId,
+            parentWorkspaceId: parentWorkspaceId,
+          }),
+        );
+      } finally {
+        await client.close();
+      }
     } finally {
       await scoped?.close();
       for (const workspaceId of ownedWorkspaces.toReversed())
@@ -1210,7 +1241,7 @@ describe("Suite E: Workspace Tools", () => {
           .callTool({ name: "archive_workspace", args: { workspaceId } })
           .catch(() => undefined);
     }
-  });
+  }, 30_000);
 
   test("a background agent's children and workspaces are background unless it overrides", async () => {
     const visibleAgentId = await createTopLevelAgent();

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

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

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

@@ -194,8 +194,6 @@ 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",
@@ -439,7 +437,6 @@ 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,253 +1,488 @@
-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 { createFileObserver } from "./file-observer/index.js";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 
-async function withCheckout(
-  run: (input: {
-    cwd: string;
-    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(),
-    workspaceGitService: {
-      async requestWorkingTreeWatch(root, onChange) {
-        const subscription = await observer.subscribe(root, () => onChange(), {
-          ignore: [join(root, ".git")],
-        });
-        return {
-          repoRoot: root,
-          unsubscribe: async () => {
-            await subscription.unsubscribe();
-          },
-        };
-      },
+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,
     },
-  });
-  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 });
-  }
+    forge: {
+      featuresEnabled: false,
+      authState: "no_remote",
+      pullRequest: null,
+      error: null,
+    },
+  };
 }
 
-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),
-      ),
-      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);
+function createPendingManager() {
+  const watches: Array<{
+    cwd: string;
+    onChange: () => void;
+    unsubscribeCalls: number;
+    resolve(): void;
+  }> = [];
+  const workspaceGitService = {
+    getCheckoutDiff: async () => ({ diff: "", structured: [] }),
+    getSnapshot: async () => createWorkspaceSnapshot(),
 
-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(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("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();
-    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();
-      },
-    );
-    const legacy = manager.subscribe(
-      { cwd, compare: { mode: "uncommitted" }, signal: abort.signal },
-      () => {
-        throw new Error("Cancelled subscriber received an update");
-      },
-    );
-    try {
-      await modern.start();
-      const result = await legacy;
-      expect(result.initial).toMatchObject({
-        files: [],
-        error: { message: "Diff subscription cancelled" },
-      });
-      await result.unsubscribe();
-    } finally {
-      await modern.release();
-    }
-  });
-}, 30_000);
-
-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",
-    });
-    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("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;" })]),
+    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: () => {} };
+  const manager = new CheckoutDiffManager({
+    workspaceRuntimeStore: createWorkspaceRuntimeStore(),
+    logger: logger as unknown as pino.Logger,
+    paseoHome: "/tmp/paseo-test",
+    workspaceGitService,
+  });
+  return { manager, watches };
+}
+
+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 };
+        },
+      ),
+      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,
+    });
+
+    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" },
+      },
+      () => {},
+    );
+
+    expect(mockRequestWorkingTreeWatch).toHaveBeenCalledWith(
+      "/tmp/repo/packages/server",
+      expect.any(Function),
+    );
+  });
+
+  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();
-  });
-});
 
-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();
+    expect(unsubscribe).toHaveBeenCalledTimes(1);
+  });
+
+  test("cancels a subscription while its working tree watch is still opening", async () => {
+    const { manager, watches } = createPendingManager();
+    const abort = new AbortController();
+
+    const pendingSubscription = manager.subscribe(
+      {
+        cwd: "/tmp/repo/packages/server",
+        compare: { mode: "uncommitted" },
+        signal: abort.signal,
+      },
+      () => {},
+    );
+    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" },
+      },
+      () => {},
+    );
+
+    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" }],
+      });
+
+    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 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,
+      });
+    });
+  });
+
+  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,
+    });
+
+    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();
+  });
+
+  test("base diff subscriptions ignore worktree-only workspace snapshot updates", async () => {
+    const getCheckoutDiff = vi.fn(async () => ({ diff: "", structured: [] }));
+    const { manager, getOnWorkspaceSnapshot } = createManager({
+      getCheckoutDiffImplementation: getCheckoutDiff,
+    });
+
+    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,
+    );
   });
 });
-
-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,201 +1,400 @@
+import { type WorkspaceRuntimeStore } from "./workspace-runtime-store/index.js";
 import type pino from "pino";
 import type { SubscribeCheckoutDiffRequest, SessionOutboundMessage } from "./messages.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 type { WorkspaceGitRuntimeSnapshot, WorkspaceGitService } from "./workspace-git-service.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 {
-  readonly streams: DiffSubscriptions;
-  private readonly paseoHome: string;
+  private readonly workspaceGitService: CheckoutDiffWorkspace;
+  private readonly workspaceRuntimeStore: WorkspaceRuntimeStore;
+  private readonly targets = new Map<string, CheckoutDiffWatchTarget>();
+
   constructor(options: {
     logger: pino.Logger;
     paseoHome: string;
-    workspaceGitService: Pick<WorkspaceGitService, "requestWorkingTreeWatch">;
+    workspaceGitService: CheckoutDiffWorkspace;
     workspaceRuntimeStore: WorkspaceRuntimeStore;
   }) {
-    this.streams = new DiffSubscriptions(options.workspaceGitService);
-    this.paseoHome = options.paseoHome;
-  }
-  readCommitFile(input: CommitFileRead) {
-    return this.streams.readCommitFile(input);
+    this.workspaceGitService = options.workspaceGitService;
+    this.workspaceRuntimeStore = options.workspaceRuntimeStore;
   }
+
   async read(
     params: Omit<CheckoutDiffSubscriptionRequest, "signal">,
   ): Promise<CheckoutDiffSnapshotPayload> {
-    const subscription = await this.subscribe(params, () => {});
-    await subscription.unsubscribe();
-    return subscription.initial;
+    return this.computeCheckoutDiffSnapshot(params.cwd, this.normalizeCompare(params.compare));
   }
+
   async subscribe(
     params: CheckoutDiffSubscriptionRequest,
     listener: (snapshot: CheckoutDiffSnapshotPayload) => void,
   ): Promise<CheckoutDiffSubscription> {
-    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();
+    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) {
         return;
       }
-      if (!pending || frame.revision !== pending.revision) return;
-      if (frame.opcode === DiffOpcode.Bodies) {
-        for (const body of frame.files) bodies.set(body.path, body);
-        return;
-      }
-      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);
-      }
+      isSubscribed = false;
+      params.signal?.removeEventListener("abort", unsubscribe);
+      this.removeListener(target, listener);
     };
+    params.signal?.addEventListener("abort", unsubscribe, { once: true });
+    if (params.signal?.aborted) {
+      unsubscribe();
+    }
+
     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 };
+      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) {
-      return { initial: { cwd, files: [], error: toCheckoutError(error) }, unsubscribe() {} };
+      unsubscribe();
+      throw error;
     }
   }
-  scheduleRefreshForCwd(cwd: string): Promise<void> {
-    return this.streams.invalidateForCwd(expandTilde(cwd));
+
+  scheduleRefreshForCwd(cwd: string): void {
+    const resolvedCwd = expandTilde(cwd);
+    for (const target of this.targets.values()) {
+      if (target.cwd !== resolvedCwd && target.diffCwd !== resolvedCwd) {
+        continue;
+      }
+      this.scheduleTargetRefresh(target);
+    }
   }
+
   getMetrics(): CheckoutDiffMetrics {
-    const metrics = this.streams.getMetrics();
+    let checkoutDiffSubscriptionCount = 0;
+
+    for (const target of this.targets.values()) {
+      checkoutDiffSubscriptionCount += target.listeners.size;
+    }
+
     return {
-      checkoutDiffTargetCount: metrics.targets,
-      checkoutDiffSubscriptionCount: metrics.subscriptions,
-      checkoutDiffWatcherCount: metrics.metadataObservers,
+      checkoutDiffTargetCount: this.targets.size,
+      checkoutDiffSubscriptionCount,
+      checkoutDiffWatcherCount: 0,
       checkoutDiffFallbackRefreshTargetCount: 0,
     };
   }
-  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);
+  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);
     }
   }
-  return { cwd, files, error: null };
-}
 
-function legacyTooLarge(cwd: string): CheckoutDiffSnapshotPayload {
-  return {
-    cwd,
-    files: [],
-    diffTooLarge: true,
-    error: toCheckoutError(new Error("Diff too large to display")),
-  };
+  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;
+  }
 }

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

@@ -62,7 +62,6 @@ 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,
@@ -84,7 +83,6 @@ 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,263 +293,3 @@ 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,8 +142,7 @@ 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.
-    // Stay below the full-source highlighting budget as well.
-    const denseExpression = `const value = ${"a+".repeat(100)}a;\n`.repeat(3_500);
+    const denseExpression = `const value = ${"a+".repeat(100)}a;\n`.repeat(4_000);
     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,7 +690,6 @@ 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

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