Skip unrelated required checks without losing their names (#2542)

* fix(ci): skip unrelated required checks cleanly

Matrix jobs had to start no-op runners to preserve interpolated required-check names. Static named jobs let GitHub report genuine skipped conclusions while keeping those names stable.

* fix(ci): gate changes to install patching script

* fix(ci): route cross-package test contracts narrowly

* fix(ci): keep routed contracts merge-blocking

* fix(server): exclude nested test utilities from builds

* fix(ci): cover app-owned native and browser domains

* refactor(ci): align tests with runtime domains

Own browser specs, desktop specs, and Electron-only app code by stable directories so PR routing does not depend on filename conventions. Keep desktop integration coverage inside the required desktop check.

* fix(ci): keep routing and desktop suites isolated

The routing regression must run before dependency installation, and desktop Vitest must not collect Playwright-owned specs.

* fix(ci): isolate desktop e2e runtime

* perf(test): isolate Playwright workers

* perf(test): parallelize Playwright within specs

* fix(test): keep Playwright file scheduling

* fix(test): share dynamic Metro fixture

* fix(test): preserve own-host restart fixtures

* fix(ci): preserve routed contracts after rebase

* Stabilize Playwright wheel-scroll assertions

packages/app/e2e/support/fixtures.ts

@@ -0,0 +1,227 @@
+import { test as base, expect, type Page } from "@playwright/test";
+import { startOutdatedDaemon, type OutdatedDaemon } from "./helpers/daemon-update";
+import { startE2EWorker } from "./helpers/e2e-worker";
+import { getE2EDaemonPort } from "./helpers/daemon-port";
+import { buildCreateAgentPreferences, buildSeededHost } from "./helpers/daemon-registry";
+import {
+  createProjectPickerFixture,
+  removeProjectPickerFixture,
+  type ProjectPickerFixture,
+} from "./helpers/project-picker-fixture";
+import { connectSeedClient, type SeedDaemonClient } from "./helpers/seed-client";
+import { createWithWorkspace, type WithWorkspace } from "./helpers/with-workspace";
+
+const EXTRA_HOSTS_KEY = "@paseo:e2e-extra-hosts";
+
+interface TrackedProjectPickerFixture extends ProjectPickerFixture {
+  rememberProjectId: (projectId: string) => void;
+}
+
+// Test setup is wired through an `auto: true` fixture rather than `test.beforeEach`.
+// `test.beforeEach` declared at the top level of a non-test fixture file is unreliable
+// across spec-file boundaries — Playwright sometimes skips it for the first test of a
+// subsequent spec when multiple specs run in the same worker. Auto fixtures run
+// reliably for every test that uses this `test` object.
+const metroTest = base.extend({
+  baseURL: async ({}, provide) => {
+    const metroPort = process.env.E2E_METRO_PORT;
+    if (!metroPort) {
+      throw new Error("E2E_METRO_PORT not set - globalSetup must run first");
+    }
+    await provide(`http://localhost:${metroPort}`);
+  },
+});
+
+const test = metroTest.extend<
+  {
+    paseoE2ESetup: void;
+    projectOwnership: void;
+    outdatedDaemon: OutdatedDaemon;
+    desktopManagedOutdatedDaemon: OutdatedDaemon;
+    relayConfigOutdatedDaemon: OutdatedDaemon;
+    projectPickerFixture: TrackedProjectPickerFixture;
+    withWorkspace: WithWorkspace;
+  },
+  { e2eWorker: void; e2eWorkerClient: SeedDaemonClient }
+>({
+  e2eWorker: [
+    async ({}, provide, workerInfo) => {
+      const worker = await startE2EWorker(workerInfo.workerIndex);
+      try {
+        await provide();
+      } finally {
+        await worker.close();
+      }
+    },
+    { scope: "worker", auto: true },
+  ],
+  e2eWorkerClient: [
+    async ({ e2eWorker }, provide) => {
+      void e2eWorker;
+      const client = await connectSeedClient();
+      try {
+        await provide(client);
+      } finally {
+        await client.close().catch(() => undefined);
+      }
+    },
+    { scope: "worker" },
+  ],
+  projectOwnership: [
+    async ({ e2eWorkerClient }, provide, testInfo) => {
+      const before = new Set(
+        (await e2eWorkerClient.fetchWorkspaces()).entries.map((workspace) => workspace.projectId),
+      );
+
+      await provide();
+
+      const leaked = [
+        ...new Set(
+          (await e2eWorkerClient.fetchWorkspaces()).entries.map((workspace) => workspace.projectId),
+        ),
+      ].filter((projectId) => !before.has(projectId));
+      for (const projectId of leaked) {
+        await e2eWorkerClient.removeProject(projectId).catch(() => undefined);
+      }
+      if (leaked.length > 0) {
+        const message = `Test leaked daemon project records: ${leaked.join(", ")}`;
+        if (testInfo.status === testInfo.expectedStatus) throw new Error(message);
+        await testInfo.attach("project-leaks", { body: message, contentType: "text/plain" });
+      }
+    },
+    { auto: true },
+  ],
+  paseoE2ESetup: [
+    async ({ page }, provide, testInfo) => {
+      const daemonPort = getE2EDaemonPort();
+      const metroPort = process.env.E2E_METRO_PORT;
+      if (!metroPort) {
+        throw new Error(
+          "E2E_METRO_PORT is not set. Ensure Playwright `globalSetup` starts Metro and exports E2E_METRO_PORT.",
+        );
+      }
+
+      // Hard guardrail: never allow tests to hit the developer's default daemon.
+      // This blocks both HTTP and WS attempts to :6767 (before any navigation).
+      await page.route(/:(6767)\b/, (route) => route.abort());
+      await page.routeWebSocket(/:(6767)\b/, async (ws) => {
+        await ws.close({ code: 1008, reason: "Blocked connection to localhost:6767 during e2e." });
+      });
+
+      const entries: string[] = [];
+
+      page.on("console", (message) => {
+        entries.push(`[console:${message.type()}] ${message.text()}`);
+      });
+
+      page.on("pageerror", (error) => {
+        entries.push(`[pageerror] ${error.message}`);
+      });
+
+      const nowIso = new Date().toISOString();
+      const seedNonce = Math.random().toString(36).slice(2);
+      const serverId = process.env.E2E_SERVER_ID;
+      if (!serverId) {
+        throw new Error("E2E_SERVER_ID is not set - expected from the Playwright worker fixture.");
+      }
+      const testDaemon = buildSeededHost({
+        serverId,
+        endpoint: `127.0.0.1:${daemonPort}`,
+        nowIso,
+      });
+      const createAgentPreferences = buildCreateAgentPreferences(testDaemon.serverId);
+
+      await page.addInitScript(
+        ({ daemon, preferences, seedNonce: nonce, extraHostsKey }) => {
+          // `addInitScript` runs on every navigation (including reloads). Some tests intentionally
+          // override storage and reload; they can opt out of seeding for the *next* navigation by
+          // setting this flag before the reload.
+          const disableOnceKey = "@paseo:e2e-disable-default-seed-once";
+          const disableValue = localStorage.getItem(disableOnceKey);
+          if (disableValue) {
+            localStorage.removeItem(disableOnceKey);
+            if (disableValue === nonce) {
+              return;
+            }
+          }
+
+          localStorage.setItem("@paseo:e2e", "1");
+          localStorage.setItem("@paseo:e2e-seed-nonce", nonce);
+
+          const rawExtraHosts = localStorage.getItem(extraHostsKey);
+          const extraHosts = rawExtraHosts ? JSON.parse(rawExtraHosts) : [];
+
+          // Hard-reset anything that could point to a developer's real daemon.
+          localStorage.setItem("@paseo:daemon-registry", JSON.stringify([daemon, ...extraHosts]));
+          localStorage.removeItem("@paseo:settings");
+          localStorage.setItem("@paseo:create-agent-preferences", JSON.stringify(preferences));
+        },
+        {
+          daemon: testDaemon,
+          preferences: createAgentPreferences,
+          seedNonce,
+          extraHostsKey: EXTRA_HOSTS_KEY,
+        },
+      );
+
+      await provide();
+
+      if (entries.length > 0 && testInfo.status !== testInfo.expectedStatus) {
+        await testInfo.attach("browser-console", {
+          body: entries.join("\n"),
+          contentType: "text/plain",
+        });
+      }
+    },
+    { auto: true },
+  ],
+  outdatedDaemon: async ({}, provide) => {
+    const daemon = await startOutdatedDaemon();
+    await provide(daemon);
+    await daemon.close();
+  },
+  desktopManagedOutdatedDaemon: async ({}, provide) => {
+    const daemon = await startOutdatedDaemon({ desktopManaged: true });
+    await provide(daemon);
+    await daemon.close();
+  },
+  relayConfigOutdatedDaemon: async ({}, provide) => {
+    const daemon = await startOutdatedDaemon({
+      daemonStatusRpcCapability: false,
+      relayConfigCapability: false,
+    });
+    await provide(daemon);
+    await daemon.close();
+  },
+  projectPickerFixture: async ({}, provide) => {
+    const resource = await createProjectPickerFixture();
+    const { fixture } = resource;
+    let projectId: string | null = null;
+    try {
+      await provide({
+        ...fixture,
+        rememberProjectId: (openedProjectId) => {
+          projectId = openedProjectId;
+        },
+      });
+    } finally {
+      try {
+        const client = await connectSeedClient();
+        try {
+          await removeProjectPickerFixture(client, fixture, projectId);
+        } finally {
+          await client.close();
+        }
+      } finally {
+        await resource.removeDirectory();
+      }
+    }
+  },
+  withWorkspace: async ({ page }, provide) => {
+    const handle = createWithWorkspace(page);
+    await provide(handle.withWorkspace);
+    await handle.cleanup();
+  },
+});
+
+export { test, metroTest, expect, type Page };

packages/app/e2e/support/fixtures/recording.baseline.txt

@@ -0,0 +1,2 @@
+This is a voice note.
+

packages/app/e2e/support/global-setup.ts

@@ -0,0 +1,226 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { once } from "node:events";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import net from "node:net";
+import dotenv from "dotenv";
+
+export interface WaitForServerOptions {
+  host?: string;
+  timeoutMs?: number;
+  label: string;
+  childProcess?: ChildProcess | null;
+  getRecentOutput?: () => string;
+}
+
+type ServerProbe = (host: string, port: number) => Promise<void>;
+
+const RESERVED_LOCAL_PORTS = new Set([
+  6767, // Developer daemon.
+  61680, // OpenCode's default local server.
+]);
+
+function createLineBuffer(maxLines = 120): { add: (line: string) => void; dump: () => string } {
+  const lines: string[] = [];
+  return {
+    add(line) {
+      lines.push(line);
+      if (lines.length > maxLines) lines.shift();
+    },
+    dump: () => lines.join("\n"),
+  };
+}
+
+function formatRecentOutput(getRecentOutput?: () => string): string {
+  const output = getRecentOutput?.().trim();
+  return output ? `\nRecent output:\n${output}` : "";
+}
+
+async function getAvailablePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        server.close(() => reject(new Error("Failed to acquire port")));
+        return;
+      }
+      server.close(() => resolve(address.port));
+    });
+  });
+}
+
+async function getAvailableE2EPort(): Promise<number> {
+  for (;;) {
+    const port = await getAvailablePort();
+    if (!RESERVED_LOCAL_PORTS.has(port)) return port;
+  }
+}
+
+async function connectToServer(host: string, port: number): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const socket = net.connect(port, host, () => {
+      socket.end();
+      resolve();
+    });
+    socket.setTimeout(1_000, () => {
+      socket.destroy();
+      reject(new Error(`Connection timed out to ${host}:${port}`));
+    });
+    socket.on("error", reject);
+  });
+}
+
+async function waitForServer(
+  port: number,
+  options: WaitForServerOptions,
+  probe: ServerProbe = connectToServer,
+): Promise<void> {
+  const { host = "127.0.0.1", timeoutMs = 15_000, label, childProcess, getRecentOutput } = options;
+  const deadline = Date.now() + timeoutMs;
+  let lastConnectionError: unknown = null;
+
+  while (Date.now() < deadline) {
+    if (childProcess?.exitCode !== null && childProcess?.exitCode !== undefined) {
+      const signal = childProcess.signalCode ? `, signal ${childProcess.signalCode}` : "";
+      throw new Error(
+        `${label} exited before listening on ${host}:${port} (exit code ${childProcess.exitCode}${signal}).${formatRecentOutput(getRecentOutput)}`,
+      );
+    }
+    try {
+      await probe(host, port);
+      return;
+    } catch (error) {
+      lastConnectionError = error;
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }
+
+  const reason =
+    lastConnectionError instanceof Error
+      ? ` Last connection error: ${lastConnectionError.message}`
+      : "";
+  throw new Error(
+    `${label} did not start on ${host}:${port} within ${timeoutMs}ms.${reason}${formatRecentOutput(getRecentOutput)}`,
+  );
+}
+
+async function probeMetro(host: string, port: number): Promise<void> {
+  const response = await fetch(`http://${host}:${port}/status`, {
+    signal: AbortSignal.timeout(1_000),
+  });
+  const body = (await response.text()).trim();
+  if (response.status !== 200 || body !== "packager-status:running") {
+    throw new Error(
+      `Expected Metro status on ${host}:${port}, received HTTP ${response.status}: ${JSON.stringify(body.slice(0, 200))}`,
+    );
+  }
+}
+
+export async function waitForMetro(port: number, options: WaitForServerOptions): Promise<void> {
+  await waitForServer(port, options, probeMetro);
+}
+
+export async function warmMetro(port: number): Promise<void> {
+  const origin = `http://127.0.0.1:${port}`;
+  const documentResponse = await fetch(origin, { signal: AbortSignal.timeout(120_000) });
+  if (!documentResponse.ok) {
+    throw new Error(`Metro document warmup failed with HTTP ${documentResponse.status}`);
+  }
+  const document = await documentResponse.text();
+  const scriptSources = [...document.matchAll(/<script[^>]+src=["']([^"']+)["']/g)].map(
+    (match) => match[1],
+  );
+  if (scriptSources.length === 0) {
+    throw new Error("Metro document warmup found no scripts to compile");
+  }
+  for (const source of scriptSources) {
+    const scriptUrl = new URL(source, origin);
+    if (scriptUrl.origin !== origin) continue;
+    const response = await fetch(scriptUrl, { signal: AbortSignal.timeout(120_000) });
+    if (!response.ok) {
+      throw new Error(
+        `Metro bundle warmup failed for ${scriptUrl.pathname}: HTTP ${response.status}`,
+      );
+    }
+    await response.arrayBuffer();
+  }
+}
+
+async function stopProcess(child: ChildProcess | null): Promise<void> {
+  if (!child || child.exitCode !== null || child.signalCode !== null) return;
+  child.kill("SIGTERM");
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    await Promise.race([
+      once(child, "exit"),
+      new Promise<void>((resolve) => {
+        timeout = setTimeout(() => {
+          if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+          resolve();
+        }, 5_000);
+      }),
+    ]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+
+function startMetro(port: number, buffer: ReturnType<typeof createLineBuffer>): ChildProcess {
+  const appDir = path.resolve(__dirname, "../..");
+  const child = spawn("npx", ["expo", "start", "--web", "--port", String(port)], {
+    cwd: appDir,
+    env: {
+      ...process.env,
+      BROWSER: "none",
+      ...(process.env.E2E_DESKTOP_RUNTIME === "1" ? { PASEO_WEB_PLATFORM: "electron" } : {}),
+    },
+    stdio: ["ignore", "pipe", "pipe"],
+    detached: false,
+  });
+  const log = (chunk: Buffer, stream: "stdout" | "stderr") => {
+    for (const line of chunk.toString().split("\n").filter(Boolean)) {
+      buffer.add(`[${stream}] ${line}`);
+      console[stream === "stdout" ? "log" : "error"](`[metro] ${line}`);
+    }
+  };
+  child.stdout?.on("data", (chunk: Buffer) => log(chunk, "stdout"));
+  child.stderr?.on("data", (chunk: Buffer) => log(chunk, "stderr"));
+  return child;
+}
+
+async function loadHarnessEnvironment(repoRoot: string): Promise<void> {
+  const envTestPath = path.join(repoRoot, ".env.test");
+  if (existsSync(envTestPath)) dotenv.config({ path: envTestPath });
+}
+
+export default async function globalSetup() {
+  const repoRoot = path.resolve(__dirname, "../../../..");
+  await loadHarnessEnvironment(repoRoot);
+
+  const metroPort = await getAvailableE2EPort();
+  const metroOutput = createLineBuffer();
+  let metroProcess: ChildProcess | null = null;
+
+  try {
+    metroProcess = startMetro(metroPort, metroOutput);
+    await waitForMetro(metroPort, {
+      label: "Metro web server",
+      timeoutMs: 120_000,
+      childProcess: metroProcess,
+      getRecentOutput: metroOutput.dump,
+    });
+    await warmMetro(metroPort);
+    process.env.E2E_METRO_PORT = String(metroPort);
+    console.log(`[e2e] Metro warmed on port ${metroPort}`);
+
+    return async () => {
+      await stopProcess(metroProcess);
+      console.log("[e2e] Metro stopped");
+    };
+  } catch (error) {
+    await stopProcess(metroProcess);
+    throw error;
+  }
+}

packages/app/e2e/support/helpers/add-project-flow.ts

@@ -0,0 +1,84 @@
+import { expect, type Locator, type Page } from "@playwright/test";
+
+export type AddProjectFlowPage =
+  | "host"
+  | "method"
+  | "directory-search"
+  | "github-search"
+  | "github-location"
+  | "new-directory-parent"
+  | "new-directory-name";
+
+export type AddProjectMethod = "directory-search" | "browse" | "github" | "new-directory";
+
+const METHOD_DESTINATIONS: Record<Exclude<AddProjectMethod, "browse">, AddProjectFlowPage> = {
+  "directory-search": "directory-search",
+  github: "github-search",
+  "new-directory": "new-directory-parent",
+};
+
+export function addProjectFlow(page: Page): Locator {
+  return page.getByTestId("add-project-flow");
+}
+
+export function addProjectFlowInput(page: Page): Locator {
+  return page.getByTestId("add-project-flow-input");
+}
+
+export function addProjectFlowBack(page: Page): Locator {
+  return page.getByTestId("add-project-flow-back");
+}
+
+export function addProjectFlowHost(page: Page, serverId: string): Locator {
+  return page.getByTestId(`add-project-flow-host-${serverId}`);
+}
+
+export function addProjectFlowMethod(page: Page, method: AddProjectMethod): Locator {
+  return page.getByTestId(`add-project-flow-method-${method}`);
+}
+
+export async function expectAddProjectPage(page: Page, kind: AddProjectFlowPage): Promise<Locator> {
+  const currentPage = page.getByTestId(`add-project-flow-page-${kind}`);
+  await expect(currentPage).toBeVisible({ timeout: 30_000 });
+  return currentPage;
+}
+
+export async function openAddProjectFlow(
+  page: Page,
+  expectedPage: "host" | "method" = "method",
+): Promise<void> {
+  await page.getByTestId("sidebar-add-project").click();
+  await expect(addProjectFlow(page)).toBeVisible({ timeout: 30_000 });
+  await expectAddProjectPage(page, expectedPage);
+  await expect(addProjectFlowInput(page)).toBeFocused();
+}
+
+export async function chooseAddProjectMethod(page: Page, method: AddProjectMethod): Promise<void> {
+  const option = addProjectFlowMethod(page, method);
+  await expect(option).toBeVisible();
+  await option.click();
+  if (method !== "browse") {
+    await expectAddProjectPage(page, METHOD_DESTINATIONS[method]);
+  }
+}
+
+export async function expectNewWorkspaceForAddedProject(
+  page: Page,
+  input: {
+    serverId: string;
+    projectId: string;
+    projectName: string;
+    projectPath: string;
+  },
+): Promise<void> {
+  await expect(page).toHaveURL(/\/new\?.*projectId=/u, { timeout: 30_000 });
+  const url = new URL(page.url());
+  expect(url.pathname).toBe("/new");
+  expect(url.searchParams.get("serverId")).toBe(input.serverId);
+  expect(url.searchParams.get("projectId")).toBe(input.projectId);
+  expect(url.searchParams.get("dir")).toBe(input.projectPath);
+  await expect(page.getByRole("button", { name: "Workspace project" })).toContainText(
+    input.projectName,
+    { timeout: 30_000 },
+  );
+}

packages/app/e2e/support/helpers/agent-bottom-anchor.ts

@@ -0,0 +1,281 @@
+import { expect, type Page } from "@playwright/test";
+
+const NEAR_BOTTOM_THRESHOLD_PX = 72;
+const DEFAULT_SCROLL_TOLERANCE_PX = 24;
+
+export interface ScrollMetrics {
+  offsetY: number;
+  contentHeight: number;
+  viewportHeight: number;
+  distanceFromBottom: number;
+}
+
+function getVisibleChatScroll(page: Page) {
+  return page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+}
+
+export async function readScrollMetrics(page: Page): Promise<ScrollMetrics> {
+  return getVisibleChatScroll(page).evaluate((root: Element) => {
+    const candidates = [root, ...Array.from(root.querySelectorAll("*"))]
+      .filter((element): element is HTMLElement => element instanceof HTMLElement)
+      .filter((element) => {
+        const tagName = element.tagName.toLowerCase();
+        const isEditable =
+          tagName === "textarea" ||
+          tagName === "input" ||
+          element.getAttribute("contenteditable") === "true";
+        return !isEditable && element.scrollHeight - element.clientHeight > 1;
+      });
+    const scrollElement =
+      candidates.sort(
+        (left, right) =>
+          right.scrollHeight - right.clientHeight - (left.scrollHeight - left.clientHeight),
+      )[0] ?? (root as HTMLElement);
+
+    const offsetY = Math.max(0, scrollElement.scrollTop);
+    const contentHeight = Math.max(0, scrollElement.scrollHeight);
+    const viewportHeight = Math.max(0, scrollElement.clientHeight);
+    const distanceFromBottom = Math.max(0, contentHeight - (offsetY + viewportHeight));
+
+    return {
+      offsetY,
+      contentHeight,
+      viewportHeight,
+      distanceFromBottom,
+    };
+  });
+}
+
+export async function expectNearBottom(page: Page): Promise<void> {
+  await expect
+    .poll(async () => {
+      const metrics = await readScrollMetrics(page);
+      return metrics.distanceFromBottom;
+    })
+    .toBeLessThanOrEqual(NEAR_BOTTOM_THRESHOLD_PX);
+}
+
+export async function scrollAgentChatToBottom(page: Page): Promise<void> {
+  const chatScroll = getVisibleChatScroll(page);
+  await chatScroll.evaluate((root: Element) => {
+    const scrollElement = root as HTMLElement;
+    scrollElement.scrollTop = scrollElement.scrollHeight;
+  });
+  await expect
+    .poll(async () =>
+      chatScroll.evaluate((root: Element) => {
+        const scrollElement = root as HTMLElement;
+        return Math.max(
+          0,
+          scrollElement.scrollHeight - (scrollElement.scrollTop + scrollElement.clientHeight),
+        );
+      }),
+    )
+    .toBeLessThanOrEqual(NEAR_BOTTOM_THRESHOLD_PX);
+}
+
+export async function waitForContentGrowth(
+  page: Page,
+  previousContentHeight: number,
+): Promise<ScrollMetrics> {
+  await expect
+    .poll(async () => {
+      const metrics = await readScrollMetrics(page);
+      return metrics.contentHeight;
+    })
+    .toBeGreaterThan(previousContentHeight);
+  return readScrollMetrics(page);
+}
+
+export async function waitForScrollableChat(
+  page: Page,
+  input: { minScrollableDistance: number; timeout?: number },
+): Promise<void> {
+  await expect
+    .poll(
+      async () => {
+        const metrics = await readScrollMetrics(page);
+        return metrics.contentHeight - metrics.viewportHeight;
+      },
+      { timeout: input.timeout },
+    )
+    .toBeGreaterThan(input.minScrollableDistance);
+}
+
+export async function scrollChatAwayFromBottom(
+  page: Page,
+  input: { deltaY: number; minDistanceFromBottom: number },
+): Promise<ScrollMetrics> {
+  const scroll = getVisibleChatScroll(page);
+  const box = await scroll.boundingBox();
+  if (!box) {
+    throw new Error("Agent chat scroll container is not visible");
+  }
+  const wheelSettled = scroll.evaluate(
+    (root: Element) =>
+      new Promise<void>((resolve) => {
+        root.addEventListener(
+          "wheel",
+          () => {
+            const scrollElement = root as HTMLElement;
+            let previousOffset = scrollElement.scrollTop;
+            let stableFrames = 0;
+            const sample = () => {
+              const currentOffset = scrollElement.scrollTop;
+              stableFrames = Math.abs(currentOffset - previousOffset) <= 0.5 ? stableFrames + 1 : 0;
+              previousOffset = currentOffset;
+              if (stableFrames >= 3) {
+                resolve();
+                return;
+              }
+              requestAnimationFrame(sample);
+            };
+            requestAnimationFrame(sample);
+          },
+          { once: true },
+        );
+      }),
+  );
+  await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
+  await page.mouse.wheel(0, input.deltaY);
+  await wheelSettled;
+
+  await expect
+    .poll(async () => {
+      const metrics = await readScrollMetrics(page);
+      return metrics.distanceFromBottom;
+    })
+    .toBeGreaterThan(input.minDistanceFromBottom);
+
+  return readScrollMetrics(page);
+}
+
+export async function clickToolCallBesideScrollToBottomButton(page: Page): Promise<{
+  outsideButton: boolean;
+  toolCallReceivesPointer: boolean;
+  withinButtonBand: boolean;
+}> {
+  await scrollChatAwayFromBottom(page, {
+    deltaY: -900,
+    minDistanceFromBottom: 300,
+  });
+
+  const scrollToBottomButton = page.getByRole("button", { name: "Scroll to bottom" });
+  await expect(scrollToBottomButton).toBeVisible();
+
+  const buttonBounds = await scrollToBottomButton.boundingBox();
+  expect(buttonBounds, "Expected visible scroll-to-bottom button bounds").not.toBeNull();
+  const visibleButtonBounds = buttonBounds!;
+
+  const toolCalls = page.locator('[data-testid="tool-call-badge"] [role="button"]');
+  const toolCallBounds = await Promise.all(
+    Array.from({ length: await toolCalls.count() }, async (_, index) => ({
+      index,
+      bounds: await toolCalls.nth(index).boundingBox(),
+    })),
+  );
+  const buttonCenterY = visibleButtonBounds.y + visibleButtonBounds.height / 2;
+  const candidate = toolCallBounds
+    .filter(
+      (entry): entry is { index: number; bounds: NonNullable<typeof entry.bounds> } =>
+        entry.bounds !== null && entry.bounds.width > 0,
+    )
+    .sort(
+      (left, right) =>
+        Math.abs(left.bounds.y + left.bounds.height / 2 - buttonCenterY) -
+        Math.abs(right.bounds.y + right.bounds.height / 2 - buttonCenterY),
+    )[0];
+  expect(
+    candidate,
+    `Expected at least one rendered tool-call badge: ${JSON.stringify({
+      buttonBounds,
+      scrollMetrics: await readScrollMetrics(page),
+      toolCallBounds,
+    })}`,
+  ).toBeDefined();
+  const visibleToolCall = candidate!;
+  const initialToolCallCenterY = visibleToolCall.bounds.y + visibleToolCall.bounds.height / 2;
+  await getVisibleChatScroll(page).evaluate((scroll, deltaY) => {
+    (scroll as HTMLElement).scrollTop += deltaY;
+  }, initialToolCallCenterY - buttonCenterY);
+
+  const alignedToolCall = toolCalls.nth(visibleToolCall.index);
+  await expect
+    .poll(async () => {
+      const [currentButtonBounds, currentToolCallBounds] = await Promise.all([
+        scrollToBottomButton.boundingBox(),
+        alignedToolCall.boundingBox(),
+      ]);
+      if (!currentButtonBounds || !currentToolCallBounds) {
+        return false;
+      }
+      const toolCallCenterY = currentToolCallBounds.y + currentToolCallBounds.height / 2;
+      return (
+        toolCallCenterY >= currentButtonBounds.y &&
+        toolCallCenterY <= currentButtonBounds.y + currentButtonBounds.height
+      );
+    })
+    .toBe(true);
+
+  const [alignedButtonBounds, visibleToolCallBounds] = await Promise.all([
+    scrollToBottomButton.boundingBox(),
+    alignedToolCall.boundingBox(),
+  ]);
+  expect(alignedButtonBounds, "Expected scroll-to-bottom button to remain visible").not.toBeNull();
+  expect(
+    visibleToolCallBounds,
+    "Expected aligned tool-call badge to remain visible",
+  ).not.toBeNull();
+  const finalButtonBounds = alignedButtonBounds!;
+  const finalToolCallBounds = visibleToolCallBounds!;
+
+  const clickPoint = {
+    x: finalToolCallBounds.x + 24,
+    y: finalToolCallBounds.y + finalToolCallBounds.height / 2,
+  };
+  const toolCallReceivesPointer = await alignedToolCall.evaluate((toolCall, point) => {
+    const hit = document.elementFromPoint(point.x, point.y);
+    return hit !== null && toolCall.contains(hit);
+  }, clickPoint);
+  const hitArea = {
+    clickPoint,
+    outsideButton:
+      clickPoint.x < finalButtonBounds.x ||
+      clickPoint.x > finalButtonBounds.x + finalButtonBounds.width,
+    toolCallReceivesPointer,
+    withinButtonBand:
+      clickPoint.y >= finalButtonBounds.y &&
+      clickPoint.y <= finalButtonBounds.y + finalButtonBounds.height,
+  };
+  await page.mouse.click(hitArea.clickPoint.x, hitArea.clickPoint.y);
+  return {
+    outsideButton: hitArea.outsideButton,
+    toolCallReceivesPointer: hitArea.toolCallReceivesPointer,
+    withinButtonBand: hitArea.withinButtonBand,
+  };
+}
+
+export async function expectScrollStaysFixed(
+  page: Page,
+  baseline: ScrollMetrics,
+  input?: { durationMs?: number; sampleIntervalMs?: number; tolerancePx?: number },
+): Promise<void> {
+  const durationMs = input?.durationMs ?? 2_000;
+  const sampleIntervalMs = input?.sampleIntervalMs ?? 250;
+  const tolerancePx = input?.tolerancePx ?? DEFAULT_SCROLL_TOLERANCE_PX;
+  const samples: Array<{ elapsedMs: number; offsetY: number; contentHeight: number }> = [];
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < durationMs) {
+    await page.waitForTimeout(sampleIntervalMs);
+    const metrics = await readScrollMetrics(page);
+    samples.push({
+      elapsedMs: Date.now() - startedAt,
+      offsetY: metrics.offsetY,
+      contentHeight: metrics.contentHeight,
+    });
+    expect(
+      metrics.offsetY,
+      JSON.stringify({ baseline, samples: samples.slice(-12) }),
+    ).toBeLessThanOrEqual(baseline.offsetY + tolerancePx);
+  }
+}

packages/app/e2e/support/helpers/agent-message-gate.ts

@@ -0,0 +1,86 @@
+import type { Page, WebSocketRoute } from "@playwright/test";
+import { daemonWsRoutePattern } from "./daemon-port";
+
+type WebSocketMessage = string | Buffer;
+
+interface SendAgentMessageRequest {
+  type: "send_agent_message_request";
+  requestId: string;
+  agentId: string;
+}
+
+function readSendRequest(message: WebSocketMessage): SendAgentMessageRequest | null {
+  if (typeof message !== "string") return null;
+  try {
+    const envelope = JSON.parse(message) as {
+      type?: unknown;
+      message?: Record<string, unknown>;
+    };
+    const request = envelope.type === "session" ? envelope.message : null;
+    if (
+      request?.type !== "send_agent_message_request" ||
+      typeof request.requestId !== "string" ||
+      typeof request.agentId !== "string"
+    ) {
+      return null;
+    }
+    return {
+      type: "send_agent_message_request",
+      requestId: request.requestId,
+      agentId: request.agentId,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function gateNextAgentMessage(page: Page) {
+  let serverSocket: WebSocketRoute | null = null;
+  let browserSocket: WebSocketRoute | null = null;
+  const heldMessages: Array<WebSocketMessage | null> = [];
+  const requests: SendAgentMessageRequest[] = [];
+  const requestWaiters = new Set<() => void>();
+
+  await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
+    browserSocket = ws;
+    const server = ws.connectToServer();
+    serverSocket = server;
+
+    ws.onMessage((message) => {
+      const request = readSendRequest(message);
+      if (request) {
+        heldMessages.push(message);
+        requests.push(request);
+        for (const resolve of requestWaiters) resolve();
+        requestWaiters.clear();
+        return;
+      }
+      server.send(message);
+    });
+
+    server.onMessage((message) => ws.send(message));
+  });
+
+  const waitForRequest = async (count = 1): Promise<SendAgentMessageRequest> => {
+    while (requests.length < count) {
+      await new Promise<void>((resolve) => requestWaiters.add(resolve));
+    }
+    return requests[count - 1];
+  };
+
+  return {
+    waitForRequest,
+    accept(index = 0) {
+      const heldMessage = heldMessages[index];
+      if (!serverSocket || !heldMessage) {
+        throw new Error("No held send-agent-message request to accept");
+      }
+      serverSocket.send(heldMessage);
+      heldMessages[index] = null;
+    },
+    async disconnect(): Promise<void> {
+      if (!browserSocket) throw new Error("No browser daemon socket to disconnect");
+      await browserSocket.close({ code: 1008, reason: "Dropped by submission test." });
+    },
+  };
+}

packages/app/e2e/support/helpers/agent-stream.ts

@@ -0,0 +1,79 @@
+import { expect, type Page } from "@playwright/test";
+import { readScrollMetrics, waitForContentGrowth, expectNearBottom } from "./agent-bottom-anchor";
+
+export async function awaitAssistantMessage(page: Page, hasText?: string | RegExp): Promise<void> {
+  const messages = page.getByTestId("assistant-message");
+  const target = hasText === undefined ? messages.first() : messages.filter({ hasText }).first();
+  await expect(target).toBeVisible({ timeout: 30_000 });
+}
+
+export async function awaitToolCall(page: Page, toolName: string | RegExp): Promise<void> {
+  await expect(
+    page.getByTestId("tool-call-badge").filter({ hasText: toolName }).first(),
+  ).toBeVisible({ timeout: 30_000 });
+}
+
+export async function expectAgentIdle(page: Page, timeout = 30_000): Promise<void> {
+  await expect(page.getByRole("button", { name: /stop|cancel/i })).toHaveCount(0, { timeout });
+}
+
+// The working indicator is an animated spinner View — no semantic ARIA role, testId is correct.
+export async function expectInlineWorkingIndicator(page: Page): Promise<void> {
+  await expect(page.getByTestId("turn-working-indicator")).toBeVisible({ timeout: 30_000 });
+}
+
+export async function expectRunningAgentChrome(page: Page, title: string): Promise<void> {
+  const tab = page.getByRole("button", { name: title, exact: true });
+
+  await expect(tab).toBeVisible({ timeout: 30_000 });
+  await expect(tab.getByRole("progressbar", { name: "Agent running" })).toBeVisible({
+    timeout: 30_000,
+  });
+  await expect(page.getByRole("button", { name: /stop agent|canceling agent/i })).toBeVisible({
+    timeout: 30_000,
+  });
+  await expectInlineWorkingIndicator(page);
+}
+
+export async function expectAgentReadyToInterrupt(page: Page): Promise<void> {
+  await expect(page.getByRole("button", { name: "Stop agent", exact: true })).toBeVisible({
+    timeout: 30_000,
+  });
+  await expect(page.getByRole("button", { name: "Canceling agent", exact: true })).toHaveCount(0);
+}
+
+export async function expectVisibleAgentSurfacesIdle(page: Page): Promise<void> {
+  const visibleAgentTab = page
+    .getByTestId(/^workspace-tab-agent_/)
+    .filter({ visible: true })
+    .first();
+
+  await expect(visibleAgentTab).toBeVisible({ timeout: 30_000 });
+  await expect(visibleAgentTab.getByRole("progressbar", { name: "Agent running" })).toHaveCount(0);
+  await expect(page.getByRole("button", { name: /stop agent|canceling agent/i })).toHaveCount(0);
+  await expect(page.getByTestId("turn-working-indicator")).toHaveCount(0);
+  await expect(page.getByTestId("turn-working-elapsed")).toHaveCount(0);
+}
+
+export async function expectAgentSurfacesIdle(page: Page, title: string): Promise<void> {
+  const tab = page.getByRole("button", { name: title, exact: true });
+
+  await expect(tab).toBeVisible({ timeout: 30_000 });
+  await expect(tab.getByRole("progressbar", { name: "Agent running" })).toHaveCount(0);
+  await expect(page.getByRole("button", { name: /stop agent|canceling agent/i })).toHaveCount(0);
+  await expect(page.getByTestId("turn-working-indicator")).toHaveCount(0);
+  await expect(page.getByTestId("turn-working-elapsed")).toHaveCount(0);
+  await expectTurnCopyButton(page);
+}
+
+export async function expectTurnCopyButton(page: Page): Promise<void> {
+  await expect(page.getByRole("button", { name: "Copy turn" }).first()).toBeVisible({
+    timeout: 30_000,
+  });
+}
+
+export async function expectScrollFollowsNewContent(page: Page): Promise<void> {
+  const { contentHeight } = await readScrollMetrics(page);
+  await waitForContentGrowth(page, contentHeight);
+  await expectNearBottom(page);
+}

packages/app/e2e/support/helpers/agent-timeline-gate.ts

@@ -0,0 +1,376 @@
+import type { Page } from "@playwright/test";
+import { daemonWsRoutePattern } from "./daemon-port";
+
+type WebSocketMessage = string | Buffer;
+
+interface CreatedAgentTimelineGate {
+  release(): void;
+  waitForCreatedAgent(): Promise<string>;
+  waitForDelayedResponse(): Promise<void>;
+  waitForForwardedResponse(): Promise<void>;
+}
+
+export interface AgentTimelineResponseGate {
+  release(): void;
+  waitForDelayedResponse(): Promise<void>;
+}
+
+export interface OlderTimelinePagesGate {
+  getRequestCount(): number;
+  getRepeatedAssistantEntryCount(): number;
+  releasePage(pageNumber: number): void;
+  waitForRequestCount(count: number): Promise<void>;
+}
+
+export interface DaemonHydrationGate {
+  release(): void;
+}
+
+export interface BootstrapTimelineGate extends AgentTimelineResponseGate {
+  releaseCatchUp(): void;
+  waitForDelayedCatchUp(): Promise<void>;
+}
+
+function parseWebSocketJson(message: WebSocketMessage): unknown {
+  const rawMessage = typeof message === "string" ? message : message.toString("utf8");
+  try {
+    return JSON.parse(rawMessage);
+  } catch {
+    return null;
+  }
+}
+
+function getSessionMessage(message: WebSocketMessage): Record<string, unknown> | null {
+  const envelope = parseWebSocketJson(message);
+  if (!envelope || typeof envelope !== "object") {
+    return null;
+  }
+  const maybeEnvelope = envelope as { type?: unknown; message?: unknown };
+  if (maybeEnvelope.type !== "session" || !maybeEnvelope.message) {
+    return null;
+  }
+  if (typeof maybeEnvelope.message !== "object") {
+    return null;
+  }
+  return maybeEnvelope.message as Record<string, unknown>;
+}
+
+function getPayload(message: Record<string, unknown>): Record<string, unknown> | null {
+  return message.payload && typeof message.payload === "object"
+    ? (message.payload as Record<string, unknown>)
+    : null;
+}
+
+export async function holdDaemonHydration(page: Page): Promise<DaemonHydrationGate> {
+  let released = false;
+  const delayedForwards: Array<() => void> = [];
+
+  await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
+    const server = ws.connectToServer();
+    ws.onMessage((message) => server.send(message));
+    server.onMessage((message) => {
+      if (released) {
+        ws.send(message);
+        return;
+      }
+      delayedForwards.push(() => ws.send(message));
+    });
+  });
+
+  return {
+    release() {
+      released = true;
+      for (const forward of delayedForwards.splice(0)) {
+        forward();
+      }
+    },
+  };
+}
+
+export async function delayCreatedAgentInitialTailResponse(
+  page: Page,
+): Promise<CreatedAgentTimelineGate> {
+  let createdAgentId: string | null = null;
+  let releaseRequested = false;
+  let delayedResponseSeen = false;
+  const delayedForwards: Array<() => void> = [];
+  let resolveCreatedAgent: ((agentId: string) => void) | null = null;
+  let resolveDelayedResponse: (() => void) | null = null;
+  let resolveForwardedResponse: (() => void) | null = null;
+  const createdAgentSeen = new Promise<string>((resolve) => {
+    resolveCreatedAgent = resolve;
+  });
+  const delayedResponse = new Promise<void>((resolve) => {
+    resolveDelayedResponse = resolve;
+  });
+  const forwardedResponse = new Promise<void>((resolve) => {
+    resolveForwardedResponse = resolve;
+  });
+
+  await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
+    const server = ws.connectToServer();
+    const forwardToClient = (message: WebSocketMessage) => {
+      ws.send(message);
+      resolveForwardedResponse?.();
+    };
+
+    ws.onMessage((message) => {
+      server.send(message);
+    });
+
+    server.onMessage((message) => {
+      const sessionMessage = getSessionMessage(message);
+      const payload = sessionMessage ? getPayload(sessionMessage) : null;
+      if (sessionMessage?.type === "status" && payload?.status === "agent_created") {
+        const agentId = payload.agentId;
+        if (typeof agentId === "string") {
+          createdAgentId = agentId;
+          resolveCreatedAgent?.(agentId);
+        }
+      }
+
+      if (sessionMessage?.type === "fetch_agent_timeline_response") {
+        const agentId = payload?.agentId;
+        const direction = payload?.direction;
+        if (
+          !delayedResponseSeen &&
+          typeof agentId === "string" &&
+          agentId === createdAgentId &&
+          direction === "tail"
+        ) {
+          delayedResponseSeen = true;
+          resolveDelayedResponse?.();
+          if (releaseRequested) {
+            forwardToClient(message);
+            return;
+          }
+          delayedForwards.push(() => forwardToClient(message));
+          return;
+        }
+      }
+
+      ws.send(message);
+    });
+  });
+
+  return {
+    release() {
+      releaseRequested = true;
+      for (const forward of delayedForwards.splice(0)) {
+        forward();
+      }
+    },
+    waitForCreatedAgent: () => createdAgentSeen,
+    waitForDelayedResponse: () => delayedResponse,
+    waitForForwardedResponse: () => forwardedResponse,
+  };
+}
+
+export async function delayAgentOlderTimelineResponse(
+  page: Page,
+  agentId: string,
+): Promise<AgentTimelineResponseGate> {
+  return delayAgentTimelineResponse(page, agentId, "before");
+}
+
+export async function holdAgentOlderTimelinePages(
+  page: Page,
+  agentId: string,
+): Promise<OlderTimelinePagesGate> {
+  let requestCount = 0;
+  let responseCount = 0;
+  let repeatedAssistantEntryCount = 0;
+  const assistantEntryKeys = new Set<string>();
+  const releasedPages = new Set<number>();
+  const delayedForwards = new Map<number, Array<() => void>>();
+  const requestWaiters = new Map<number, Array<() => void>>();
+
+  const resolveRequestWaiters = () => {
+    for (const [count, resolvers] of requestWaiters) {
+      if (requestCount < count) continue;
+      requestWaiters.delete(count);
+      for (const resolve of resolvers) resolve();
+    }
+  };
+
+  await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
+    const server = ws.connectToServer();
+    ws.onMessage((message) => {
+      const sessionMessage = getSessionMessage(message);
+      if (
+        sessionMessage?.type === "fetch_agent_timeline_request" &&
+        sessionMessage.agentId === agentId &&
+        sessionMessage.direction === "before"
+      ) {
+        requestCount += 1;
+        resolveRequestWaiters();
+      }
+      server.send(message);
+    });
+    server.onMessage((message) => {
+      const sessionMessage = getSessionMessage(message);
+      const payload = sessionMessage ? getPayload(sessionMessage) : null;
+      if (
+        sessionMessage?.type === "fetch_agent_timeline_response" &&
+        payload?.agentId === agentId &&
+        payload.direction === "before"
+      ) {
+        responseCount += 1;
+        const entries = Array.isArray(payload.entries) ? payload.entries : [];
+        for (const entry of entries) {
+          if (!entry || typeof entry !== "object") continue;
+          const projectedEntry = entry as {
+            seqStart?: unknown;
+            seqEnd?: unknown;
+            item?: { type?: unknown };
+          };
+          if (
+            typeof projectedEntry.seqStart !== "number" ||
+            typeof projectedEntry.seqEnd !== "number" ||
+            typeof projectedEntry.item?.type !== "string"
+          ) {
+            continue;
+          }
+          if (projectedEntry.item.type !== "assistant_message") continue;
+          const key = `${projectedEntry.seqStart}:${projectedEntry.seqEnd}:${projectedEntry.item.type}`;
+          if (assistantEntryKeys.has(key)) repeatedAssistantEntryCount += 1;
+          else assistantEntryKeys.add(key);
+        }
+        const pageNumber = responseCount;
+        if (releasedPages.has(pageNumber)) {
+          ws.send(message);
+          return;
+        }
+        const forwards = delayedForwards.get(pageNumber) ?? [];
+        forwards.push(() => ws.send(message));
+        delayedForwards.set(pageNumber, forwards);
+        return;
+      }
+      ws.send(message);
+    });
+  });
+
+  return {
+    getRequestCount: () => requestCount,
+    getRepeatedAssistantEntryCount: () => repeatedAssistantEntryCount,
+    releasePage(pageNumber) {
+      releasedPages.add(pageNumber);
+      for (const forward of delayedForwards.get(pageNumber) ?? []) forward();
+      delayedForwards.delete(pageNumber);
+    },
+    waitForRequestCount(count) {
+      if (requestCount >= count) return Promise.resolve();
+      return new Promise<void>((resolve) => {
+        const resolvers = requestWaiters.get(count) ?? [];
+        resolvers.push(resolve);
+        requestWaiters.set(count, resolvers);
+      });
+    },
+  };
+}
+
+export async function delayAgentBootstrapTailResponse(
+  page: Page,
+  agentId: string,
+): Promise<BootstrapTimelineGate> {
+  let tailReleased = false;
+  let catchUpReleased = false;
+  const delayedTailForwards: Array<() => void> = [];
+  const delayedCatchUpForwards: Array<() => void> = [];
+  let resolveDelayedTail: (() => void) | null = null;
+  let resolveDelayedCatchUp: (() => void) | null = null;
+  const delayedTail = new Promise<void>((resolve) => {
+    resolveDelayedTail = resolve;
+  });
+  const delayedCatchUp = new Promise<void>((resolve) => {
+    resolveDelayedCatchUp = resolve;
+  });
+
+  await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
+    const server = ws.connectToServer();
+    ws.onMessage((message) => server.send(message));
+    server.onMessage((message) => {
+      const sessionMessage = getSessionMessage(message);
+      const payload = sessionMessage ? getPayload(sessionMessage) : null;
+      const isTimelineResponse =
+        sessionMessage?.type === "fetch_agent_timeline_response" && payload?.agentId === agentId;
+      if (isTimelineResponse && payload.direction === "tail") {
+        resolveDelayedTail?.();
+        if (tailReleased) ws.send(message);
+        else delayedTailForwards.push(() => ws.send(message));
+        return;
+      }
+      if (isTimelineResponse && payload.direction === "after") {
+        resolveDelayedCatchUp?.();
+        if (catchUpReleased) ws.send(message);
+        else delayedCatchUpForwards.push(() => ws.send(message));
+        return;
+      }
+      ws.send(message);
+    });
+  });
+
+  return {
+    release() {
+      tailReleased = true;
+      for (const forward of delayedTailForwards.splice(0)) forward();
+    },
+    releaseCatchUp() {
+      catchUpReleased = true;
+      for (const forward of delayedCatchUpForwards.splice(0)) forward();
+    },
+    waitForDelayedResponse: () => delayedTail,
+    waitForDelayedCatchUp: () => delayedCatchUp,
+  };
+}
+
+async function delayAgentTimelineResponse(
+  page: Page,
+  agentId: string,
+  direction: "before" | "tail",
+): Promise<AgentTimelineResponseGate> {
+  let releaseRequested = false;
+  let delayedResponseSeen = false;
+  const delayedForwards: Array<() => void> = [];
+  let resolveDelayedResponse: (() => void) | null = null;
+  const delayedResponse = new Promise<void>((resolve) => {
+    resolveDelayedResponse = resolve;
+  });
+
+  await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
+    const server = ws.connectToServer();
+    ws.onMessage((message) => {
+      server.send(message);
+    });
+    server.onMessage((message) => {
+      const sessionMessage = getSessionMessage(message);
+      const payload = sessionMessage ? getPayload(sessionMessage) : null;
+      if (
+        !delayedResponseSeen &&
+        sessionMessage?.type === "fetch_agent_timeline_response" &&
+        payload?.agentId === agentId &&
+        payload.direction === direction
+      ) {
+        delayedResponseSeen = true;
+        resolveDelayedResponse?.();
+        if (releaseRequested) {
+          ws.send(message);
+          return;
+        }
+        delayedForwards.push(() => ws.send(message));
+        return;
+      }
+      ws.send(message);
+    });
+  });
+
+  return {
+    release() {
+      releaseRequested = true;
+      for (const forward of delayedForwards.splice(0)) {
+        forward();
+      }
+    },
+    waitForDelayedResponse: () => delayedResponse,
+  };
+}

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

@@ -0,0 +1,443 @@
+import { expect, type Page } from "@playwright/test";
+import { escapeRegex } from "./regex";
+
+export const gotoAppShell = async (page: Page) => {
+  await page.goto("/");
+};
+
+export const gotoHome = async (page: Page) => {
+  await gotoAppShell(page);
+  const composer = page.getByRole("textbox", { name: "Message agent..." }).first();
+  const entryButton = page
+    .getByText("Add a project", { exact: true })
+    .or(page.getByText("Add project", { exact: true }))
+    .or(page.getByText("New agent", { exact: true }))
+    .first();
+
+  await expect
+    .poll(
+      async () =>
+        (await composer.isVisible().catch(() => false)) ||
+        (await entryButton.isVisible().catch(() => false)),
+      { timeout: 10_000 },
+    )
+    .toBe(true);
+
+  if (!(await composer.isVisible().catch(() => false))) {
+    await entryButton.click();
+  }
+
+  await expect(composer).toBeVisible({ timeout: 30_000 });
+};
+
+export const openSettings = async (page: Page) => {
+  // Navigate through the real app control so route changes stay aligned with UI behavior.
+  const settingsButton = page.locator('[data-testid="sidebar-settings"]:visible').first();
+  await expect(settingsButton).toBeVisible();
+  await settingsButton.click();
+  await expect(page).toHaveURL(/\/settings\/general$/);
+};
+
+export const setWorkingDirectory = async (page: Page, directory: string) => {
+  const workingDirectorySelect = page
+    .locator('[data-testid="working-directory-select"]:visible')
+    .first();
+  await expect(workingDirectorySelect).toBeVisible({ timeout: 30000 });
+
+  const legacyInput = page.getByRole("textbox", { name: "/path/to/project" }).first();
+  const directorySearchInput = page.getByRole("textbox", { name: /search directories/i }).first();
+  const worktreePicker = page.getByTestId("worktree-attach-picker");
+  const worktreeSheetTitle = page.getByText("Select worktree", { exact: true }).first();
+  const closeBottomSheet = async () => {
+    const bottomSheetBackdrop = page.getByRole("button", { name: "Bottom sheet backdrop" }).first();
+    const bottomSheetHandle = page.getByRole("slider", { name: "Bottom sheet handle" }).first();
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      if (!(await bottomSheetBackdrop.isVisible())) {
+        return;
+      }
+      await bottomSheetBackdrop.click({ force: true });
+      await page.keyboard.press("Escape").catch(() => undefined);
+      await page.waitForTimeout(200);
+    }
+    if (await bottomSheetBackdrop.isVisible()) {
+      const box = await bottomSheetHandle.boundingBox();
+      if (box) {
+        const startX = box.x + box.width / 2;
+        const startY = box.y + box.height / 2;
+        await page.mouse.move(startX, startY);
+        await page.mouse.down();
+        await page.mouse.move(startX, startY + 400);
+        await page.mouse.up();
+        await page.waitForTimeout(200);
+      }
+    }
+  };
+  const closeWorktreeSheetIfOpen = async () => {
+    if (!(await worktreeSheetTitle.isVisible()) && !(await worktreePicker.isVisible())) {
+      return;
+    }
+    const attachToggle = page.getByTestId("worktree-attach-toggle");
+    if (await attachToggle.isVisible()) {
+      await attachToggle.click({ force: true });
+      await page.waitForTimeout(200);
+    }
+    await closeBottomSheet();
+  };
+
+  await closeWorktreeSheetIfOpen();
+
+  const pickerInputVisible = async () =>
+    (await directorySearchInput.isVisible().catch(() => false)) ||
+    (await legacyInput.isVisible().catch(() => false));
+
+  if (!(await pickerInputVisible())) {
+    await closeBottomSheet();
+    await workingDirectorySelect.click({ force: true });
+    if (!(await pickerInputVisible())) {
+      await closeBottomSheet();
+      await workingDirectorySelect.click({ force: true });
+    }
+    await expect.poll(async () => pickerInputVisible(), { timeout: 10000 }).toBe(true);
+  }
+
+  const trimmedDirectory = directory.replace(/\/+$/, "");
+  const activeInput = (await directorySearchInput.isVisible().catch(() => false))
+    ? directorySearchInput
+    : legacyInput;
+
+  await activeInput.fill(trimmedDirectory);
+
+  if (activeInput === directorySearchInput) {
+    // Combobox custom rows can be either plain path labels or prefixed labels.
+    const plainOption = page
+      .getByText(new RegExp(`^${escapeRegex(trimmedDirectory)}$`, "i"))
+      .first();
+    const prefixedUseOption = page
+      .getByText(new RegExp(`^Use "${escapeRegex(trimmedDirectory)}"$`, "i"))
+      .first();
+
+    if (await plainOption.isVisible().catch(() => false)) {
+      await plainOption.click({ force: true });
+    } else if (await prefixedUseOption.isVisible().catch(() => false)) {
+      await prefixedUseOption.click({ force: true });
+    } else {
+      // Fallback: accept highlighted option (directory suggestion).
+      await activeInput.press("Enter");
+    }
+  } else {
+    // Legacy path picker fallback.
+    await activeInput.press("Enter");
+  }
+
+  // Wait for picker to close.
+  await expect(activeInput).not.toBeVisible({ timeout: 10000 });
+
+  const directoryCandidates = new Set<string>([trimmedDirectory]);
+  if (trimmedDirectory.startsWith("/var/")) {
+    directoryCandidates.add(`/private${trimmedDirectory}`);
+  }
+  if (trimmedDirectory.startsWith("/private/var/")) {
+    directoryCandidates.add(trimmedDirectory.replace(/^\/private/, ""));
+  }
+  const basename = trimmedDirectory.split("/").findLast(Boolean) ?? trimmedDirectory;
+
+  await expect
+    .poll(
+      async () => {
+        const text = await workingDirectorySelect.innerText().catch(() => "");
+        if (text.includes(basename)) return true;
+        for (const candidate of directoryCandidates) {
+          if (text.includes(candidate)) return true;
+        }
+        return false;
+      },
+      { timeout: 30000 },
+    )
+    .toBe(true);
+};
+
+export const ensureHostSelected = async (page: Page) => {
+  const input = page.getByRole("textbox", { name: "Message agent..." });
+  await expect(input).toBeVisible();
+
+  if (await input.isEditable()) {
+    return;
+  }
+
+  const selectHostLabel = page.getByText("Select host", { exact: true });
+  if (await selectHostLabel.isVisible()) {
+    await selectHostLabel.click();
+
+    // We enforce a single seeded daemon, so the option should be unambiguous.
+    const localhostOption = page.getByText("localhost", { exact: true }).first();
+    const daemonIdOption = page
+      .getByText(process.env.E2E_SERVER_ID ?? "srv_e2e_test_daemon", { exact: true })
+      .first();
+
+    if (await localhostOption.isVisible()) {
+      await localhostOption.click();
+    } else {
+      await expect(daemonIdOption).toBeVisible();
+      await daemonIdOption.click();
+    }
+  }
+
+  await expect(input).toBeEditable();
+};
+
+export const createAgent = async (page: Page, message: string) => {
+  const input = page.getByRole("textbox", { name: "Message agent..." });
+  await expect(input).toBeEditable();
+  await preferFastThinkingOption(page);
+  await input.fill(message);
+  await input.press("Enter");
+
+  // The composer may remain on the draft screen briefly while the initial run starts,
+  // so assert the user-visible result instead of forcing one route shape here.
+  await expect(page).toHaveURL(/\/(workspace|agent|new-agent)(\/|$|\?)/, { timeout: 30000 });
+  await expect(page.getByText(message, { exact: true }).first()).toBeVisible({
+    timeout: 30000,
+  });
+};
+
+async function preferFastThinkingOption(page: Page): Promise<void> {
+  const providerTrigger = page
+    .locator(
+      '[data-testid="agent-provider-selector"]:visible, [data-testid="draft-provider-select"]:visible',
+    )
+    .first();
+  if (await providerTrigger.isVisible().catch(() => false)) {
+    const providerText = ((await providerTrigger.innerText().catch(() => "")) ?? "").trim();
+    if (!/codex/i.test(providerText)) {
+      return;
+    }
+  }
+
+  const thinkingTrigger = page.getByTestId("agent-thinking-selector").first();
+  if (!(await thinkingTrigger.isVisible().catch(() => false))) {
+    return;
+  }
+
+  const currentThinkingLabel = ((await thinkingTrigger.innerText().catch(() => "")) ?? "")
+    .trim()
+    .toLowerCase();
+  if (/\b(low|minimal|off)\b/.test(currentThinkingLabel)) {
+    return;
+  }
+
+  await thinkingTrigger.click();
+  const menu = page.getByTestId("agent-thinking-menu").first();
+  if (!(await menu.isVisible().catch(() => false))) {
+    return;
+  }
+
+  const preferredLabels = ["low", "minimal", "off", "medium"];
+  let selected = false;
+  for (const label of preferredLabels) {
+    const option = menu
+      .getByRole("button", { name: new RegExp(`^${escapeRegex(label)}$`, "i") })
+      .first();
+    if (await option.isVisible().catch(() => false)) {
+      await option.click({ force: true });
+      selected = true;
+      break;
+    }
+  }
+
+  if (!selected) {
+    const options = menu.getByRole("button");
+    const count = await options.count();
+    for (let index = 0; index < count; index += 1) {
+      const option = options.nth(index);
+      const label = ((await option.innerText().catch(() => "")) ?? "").trim();
+      if (!label) {
+        continue;
+      }
+      if (label.toLowerCase() === currentThinkingLabel) {
+        continue;
+      }
+      await option.click({ force: true });
+      selected = true;
+      break;
+    }
+  }
+
+  if (!selected) {
+    await page.keyboard.press("Escape").catch(() => undefined);
+    return;
+  }
+
+  await expect(menu).not.toBeVisible({ timeout: 5000 });
+}
+
+export interface AgentConfig {
+  directory: string;
+  provider?: string;
+  model?: string;
+  mode?: string;
+  prompt: string;
+}
+
+export const selectProvider = async (page: Page, provider: string) => {
+  const normalizedProvider = provider.trim();
+  if (!normalizedProvider) {
+    throw new Error("Provider must be a non-empty string.");
+  }
+
+  const providerTrigger = page
+    .locator(
+      '[data-testid="agent-provider-selector"]:visible, [data-testid="draft-provider-select"]:visible',
+    )
+    .first();
+  if (
+    await providerTrigger
+      .getByText(new RegExp(`^${escapeRegex(normalizedProvider)}$`, "i"))
+      .first()
+      .isVisible()
+      .catch(() => false)
+  ) {
+    return;
+  }
+
+  if (await providerTrigger.isVisible().catch(() => false)) {
+    await providerTrigger.click();
+  } else {
+    const providerLabel = page.getByText("PROVIDER", { exact: true }).first();
+    await expect(providerLabel).toBeVisible();
+    await providerLabel.click();
+  }
+
+  const dialog = page.getByRole("dialog").last();
+  const searchInput = dialog.getByRole("textbox", { name: /search provider/i }).first();
+  if (await searchInput.isVisible().catch(() => false)) {
+    await searchInput.fill(normalizedProvider);
+  }
+
+  const option = dialog.getByText(new RegExp(`^${escapeRegex(normalizedProvider)}$`, "i")).first();
+  await expect(option).toBeVisible();
+  await option.click();
+};
+
+export const selectModel = async (page: Page, model: string) => {
+  const normalizedModel = model.trim();
+  if (!normalizedModel) {
+    throw new Error("Model must be a non-empty string.");
+  }
+
+  const modelTrigger = page
+    .locator(
+      '[data-testid="agent-model-selector"]:visible, [data-testid="draft-model-select"]:visible',
+    )
+    .first();
+  if (
+    await modelTrigger
+      .getByText(new RegExp(`^${escapeRegex(normalizedModel)}$`, "i"))
+      .first()
+      .isVisible()
+      .catch(() => false)
+  ) {
+    return;
+  }
+
+  if (await modelTrigger.isVisible().catch(() => false)) {
+    await modelTrigger.click();
+  } else {
+    const modelButton = page
+      .getByRole("button", { name: /Select model/i })
+      .filter({ visible: true })
+      .first();
+    if (await modelButton.isVisible().catch(() => false)) {
+      await modelButton.click();
+    } else {
+      const modelLabel = page.getByText("MODEL", { exact: true }).first();
+      await expect(modelLabel).toBeVisible();
+      await modelLabel.click();
+    }
+  }
+
+  // Wait for the model dropdown to open
+  const searchInput = page.getByRole("textbox", { name: /search model/i });
+  await expect(searchInput).toBeVisible({ timeout: 10000 });
+
+  // Type to search/filter models
+  await searchInput.fill(normalizedModel);
+
+  const dialog = page.getByRole("dialog");
+  const exactOption = dialog
+    .getByText(new RegExp(`^${escapeRegex(normalizedModel)}$`, "i"))
+    .first();
+  const exactVisible = await exactOption.isVisible().catch(() => false);
+  if (exactVisible) {
+    await exactOption.click({ force: true });
+  } else {
+    // Modern labels include version suffixes (for example "Haiku 4.5"), so
+    // select the first filtered result using keyboard confirm.
+    await searchInput.press("Enter");
+  }
+
+  // Wait for dropdown to close
+  if (await searchInput.isVisible().catch(() => false)) {
+    await page.keyboard.press("Escape").catch(() => undefined);
+  }
+  await expect(searchInput).not.toBeVisible({ timeout: 5000 });
+};
+
+export const selectMode = async (page: Page, mode: string) => {
+  const modeTrigger = page
+    .locator(
+      '[data-testid="agent-mode-selector"]:visible, [data-testid="draft-mode-select"]:visible',
+    )
+    .first();
+  if (await modeTrigger.isVisible().catch(() => false)) {
+    await modeTrigger.click();
+  } else {
+    const modeLabel = page.getByText("MODE", { exact: true }).first();
+    await expect(modeLabel).toBeVisible();
+    await modeLabel.click();
+  }
+
+  // Wait for the mode dropdown to open
+  const searchInput = page.getByRole("textbox", { name: /search mode/i });
+  await expect(searchInput).toBeVisible({ timeout: 10000 });
+
+  // Type to filter modes
+  await searchInput.fill(mode);
+
+  const dialog = page.getByRole("dialog");
+  const option = dialog.getByText(new RegExp(`^${escapeRegex(mode)}$`, "i")).first();
+  await expect(option).toBeVisible();
+  await option.click({ force: true });
+
+  // Wait for dropdown to close
+  await expect(searchInput).not.toBeVisible({ timeout: 5000 });
+};
+
+export const createAgentWithConfig = async (page: Page, config: AgentConfig) => {
+  await gotoHome(page);
+  await ensureHostSelected(page);
+  await setWorkingDirectory(page, config.directory);
+
+  if (config.provider) {
+    await selectProvider(page, config.provider);
+  }
+
+  if (config.model) {
+    await selectModel(page, config.model);
+  }
+
+  if (config.mode) {
+    await selectMode(page, config.mode);
+  }
+
+  await createAgent(page, config.prompt);
+};
+
+export const createAgentInRepo = async (
+  page: Page,
+  config: Pick<AgentConfig, "directory" | "prompt">,
+) => {
+  await gotoHome(page);
+  await ensureHostSelected(page);
+  await setWorkingDirectory(page, config.directory);
+  await createAgent(page, config.prompt);
+};

packages/app/e2e/support/helpers/archive-tab.ts

@@ -0,0 +1,289 @@
+import { randomUUID } from "node:crypto";
+import { expect, type Page } from "@playwright/test";
+import { buildCreateAgentPreferences, buildSeededHost } from "./daemon-registry";
+import { getE2EDaemonPort } from "./daemon-port";
+import { getServerId } from "./server-id";
+import { expectAppRoute } from "./route-assertions";
+import { waitForWorkspaceTabsVisible } from "./workspace-tabs";
+import {
+  buildHostAgentDetailRoute,
+  buildHostWorkspaceRoute,
+  buildSessionsRoute,
+} from "@/utils/host-routes";
+
+export interface ArchiveTabAgent {
+  id: string;
+  title: string;
+  cwd: string;
+  workspaceId: string;
+}
+
+function buildSeededStoragePayload() {
+  const nowIso = new Date().toISOString();
+  return {
+    daemon: buildSeededHost({
+      serverId: getServerId(),
+      endpoint: `127.0.0.1:${getE2EDaemonPort()}`,
+      nowIso,
+    }),
+    preferences: buildCreateAgentPreferences(getServerId()),
+  };
+}
+
+/**
+ * The slice of a daemon client `createIdleAgent` needs: spawn an agent and await
+ * its idle upsert. The shared seed client satisfies it, so a spec can seed an
+ * idle agent from the same client it uses for everything else.
+ */
+export interface IdleAgentSeedClient {
+  createAgent(options: {
+    provider: string;
+    model: string;
+    modeId: string;
+    featureValues?: Record<string, unknown>;
+    cwd: string;
+    workspaceId: string;
+    title: string;
+  }): Promise<{ id: string }>;
+  waitForAgentUpsert(
+    agentId: string,
+    predicate: (snapshot: { status: string }) => boolean,
+    timeout?: number,
+  ): Promise<{ status: string }>;
+}
+
+export async function createIdleAgent(
+  client: IdleAgentSeedClient,
+  input: { cwd: string; workspaceId: string; title: string },
+): Promise<ArchiveTabAgent> {
+  const created = await client.createAgent({
+    provider: "opencode",
+    model: "opencode/gpt-5-nano",
+    // OpenCode has no "bypassPermissions" mode (that's Claude's). Use build with
+    // auto_accept for unattended full access — mode validation now rejects modes
+    // the provider doesn't define.
+    modeId: "build",
+    featureValues: { auto_accept: true },
+    cwd: input.cwd,
+    workspaceId: input.workspaceId,
+    title: input.title,
+  });
+  const snapshot = await client.waitForAgentUpsert(
+    created.id,
+    (agent) => agent.status === "idle",
+    30_000,
+  );
+  if (snapshot.status !== "idle") {
+    throw new Error(`Expected agent ${created.id} to become idle, got ${snapshot.status}.`);
+  }
+  return {
+    id: created.id,
+    title: input.title,
+    cwd: input.cwd,
+    workspaceId: input.workspaceId,
+  };
+}
+
+export async function archiveAgentFromDaemon(
+  client: { archiveAgent(agentId: string): Promise<{ archivedAt: string }> },
+  agentId: string,
+): Promise<void> {
+  await client.archiveAgent(agentId);
+}
+
+export async function fetchAgentArchivedAt(
+  client: {
+    fetchAgent(options: {
+      agentId: string;
+    }): Promise<{ agent: { archivedAt?: string | null } } | null>;
+  },
+  agentId: string,
+): Promise<string | null> {
+  const result = await client.fetchAgent({ agentId });
+  return result?.agent.archivedAt ?? null;
+}
+
+export async function primeAdditionalPage(page: Page): Promise<void> {
+  const seedNonce = randomUUID();
+  const { daemon, preferences } = buildSeededStoragePayload();
+
+  await page.route(/:(6767)\b/, (route) => route.abort());
+  await page.routeWebSocket(/:(6767)\b/, async (ws) => {
+    await ws.close({ code: 1008, reason: "Blocked connection to localhost:6767 during e2e." });
+  });
+  await page.addInitScript(
+    ({ daemon: seededDaemon, preferences: seededPreferences, seedNonce: nonce }) => {
+      const disableOnceKey = "@paseo:e2e-disable-default-seed-once";
+      const disableValue = localStorage.getItem(disableOnceKey);
+      if (disableValue) {
+        localStorage.removeItem(disableOnceKey);
+        if (disableValue === nonce) {
+          return;
+        }
+      }
+
+      localStorage.setItem("@paseo:e2e", "1");
+      localStorage.setItem("@paseo:e2e-seed-nonce", nonce);
+      localStorage.setItem("@paseo:daemon-registry", JSON.stringify([seededDaemon]));
+      localStorage.removeItem("@paseo:settings");
+      localStorage.setItem("@paseo:create-agent-preferences", JSON.stringify(seededPreferences));
+    },
+    { daemon, preferences, seedNonce },
+  );
+  await page.goto("/");
+}
+
+export async function resetSeededPageState(page: Page): Promise<void> {
+  const { daemon, preferences } = buildSeededStoragePayload();
+  await page.goto("/");
+  await page.evaluate(
+    ({ daemon: seededDaemon, preferences: seededPreferences }) => {
+      localStorage.clear();
+      localStorage.setItem("@paseo:e2e", "1");
+      localStorage.setItem("@paseo:daemon-registry", JSON.stringify([seededDaemon]));
+      localStorage.setItem("@paseo:create-agent-preferences", JSON.stringify(seededPreferences));
+      localStorage.removeItem("@paseo:settings");
+    },
+    { daemon, preferences },
+  );
+  await page.goto("/");
+}
+
+export async function openWorkspaceWithAgents(
+  page: Page,
+  agents: [ArchiveTabAgent, ArchiveTabAgent],
+): Promise<void> {
+  const serverId = getServerId();
+  for (const agent of agents) {
+    await page.goto(buildHostAgentDetailRoute(serverId, agent.id, agent.workspaceId));
+
+    // The workspace layout consumes `?open=agent:xxx`, returns null during the effect,
+    // then replaces the URL with the clean workspace route after preparing the tab.
+    // On CI, Expo Router's rootNavigationState may take time to initialize,
+    // so we allow a generous timeout here (matching terminal-perf pattern).
+    await page.waitForURL(
+      (url) => url.pathname.includes("/workspace/") && !url.searchParams.has("open"),
+      { timeout: 60_000 },
+    );
+
+    await waitForWorkspaceTabsVisible(page);
+    await expectWorkspaceTabVisible(page, agent.id);
+  }
+}
+
+export async function expectWorkspaceTabVisible(page: Page, agentId: string): Promise<void> {
+  await expect(
+    page.getByTestId(`workspace-tab-agent_${agentId}`).filter({ visible: true }).first(),
+  ).toBeVisible({ timeout: 30_000 });
+}
+
+export async function expectWorkspaceTabHidden(page: Page, agentId: string): Promise<void> {
+  await expect(
+    page.getByTestId(`workspace-tab-agent_${agentId}`).filter({ visible: true }),
+  ).toHaveCount(0, {
+    timeout: 30_000,
+  });
+}
+
+export async function expectWorkspaceArchiveOutcome(
+  page: Page,
+  input: { archivedAgentId: string; survivingAgentId: string },
+): Promise<void> {
+  await expectWorkspaceTabHidden(page, input.archivedAgentId);
+  await expectWorkspaceTabVisible(page, input.survivingAgentId);
+}
+
+export async function closeWorkspaceAgentTab(page: Page, agentId: string): Promise<void> {
+  const closeButton = page.getByTestId(`workspace-agent-close-${agentId}`).filter({
+    visible: true,
+  });
+  await expect(closeButton.first()).toBeVisible({ timeout: 30_000 });
+  await closeButton.first().click();
+  await expectWorkspaceTabHidden(page, agentId);
+}
+
+export async function expectArchivedAgentFocused(page: Page, agentId: string): Promise<void> {
+  await expectWorkspaceTabVisible(page, agentId);
+  await expect(
+    page.getByText("This agent is archived").filter({ visible: true }).first(),
+  ).toBeVisible({
+    timeout: 30_000,
+  });
+}
+
+export async function reloadWorkspace(page: Page, workspaceId: string): Promise<void> {
+  const serverId = getServerId();
+  await page.goto(buildHostWorkspaceRoute(serverId, workspaceId));
+  await waitForWorkspaceTabsVisible(page);
+}
+
+export async function openSessions(page: Page): Promise<void> {
+  const sessionsButton = page.getByTestId("sidebar-sessions");
+  await expect(sessionsButton).toBeVisible({ timeout: 30_000 });
+  await sessionsButton.click();
+  await expectAppRoute(page, buildSessionsRoute(), { timeout: 30_000 });
+  await expect(page.getByText("History", { exact: true }).last()).toBeVisible({
+    timeout: 30_000,
+  });
+}
+
+const AGENT_ROW_SELECTOR = '[data-testid^="agent-row-"]';
+
+function getSessionRowByTitle(page: Page, title: string) {
+  return page.locator(AGENT_ROW_SELECTOR).filter({ hasText: title }).first();
+}
+
+export async function expectSessionRowVisible(page: Page, title: string): Promise<void> {
+  await expect(getSessionRowByTitle(page, title)).toBeVisible({ timeout: 30_000 });
+}
+
+export async function expectSessionRowArchived(page: Page, title: string): Promise<void> {
+  await expect(getSessionRowByTitle(page, title)).toContainText("Archived", { timeout: 30_000 });
+}
+
+export async function expectSessionRowNotArchived(page: Page, title: string): Promise<void> {
+  await expect(getSessionRowByTitle(page, title)).not.toContainText("Archived", {
+    timeout: 30_000,
+  });
+}
+
+export async function clickSessionRow(page: Page, title: string): Promise<void> {
+  const row = getSessionRowByTitle(page, title);
+  await expect(row).toBeVisible({ timeout: 30_000 });
+  await row.click();
+}
+
+export async function expectSessionsEmptyState(page: Page): Promise<void> {
+  // Guard: the sessions-empty spec owns a pristine daemon, so this helper only
+  // needs to distinguish an empty result from the expected seeded rows.
+  await expect(page.locator(AGENT_ROW_SELECTOR)).toHaveCount(0, { timeout: 5_000 });
+  await expect(page.getByText("No sessions yet")).toBeVisible({ timeout: 30_000 });
+}
+
+export async function archiveAgentFromSessions(
+  page: Page,
+  input: { agentId: string; title: string },
+): Promise<void> {
+  const row = getSessionRowByTitle(page, input.title);
+  await expect(row).toBeVisible({ timeout: 30_000 });
+  const box = await row.boundingBox();
+  if (!box) {
+    throw new Error(`Could not read bounding box for session row ${input.agentId}.`);
+  }
+
+  // Long-press the row. Idle agents are archived immediately (no modal).
+  // Running/initializing agents show a confirmation modal instead.
+  await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
+  await page.mouse.down();
+  await page.waitForTimeout(900);
+  await page.mouse.up();
+
+  // If a confirmation modal appears (running agent), click the archive button.
+  const archiveButton = page.getByTestId("agent-action-archive").first();
+  const modalVisible = await archiveButton.isVisible().catch(() => false);
+  if (modalVisible) {
+    await archiveButton.click();
+  }
+
+  await expectSessionRowArchived(page, input.title);
+}

packages/app/e2e/support/helpers/assistant-fork.ts

@@ -0,0 +1,114 @@
+import { expect, type Page } from "@playwright/test";
+import { scrollAgentChatToBottom } from "./agent-bottom-anchor";
+import { getE2EDaemonPort } from "./daemon-port";
+
+type WebSocketMessage = string | Buffer;
+
+interface SessionMessage {
+  type?: unknown;
+  payload?: unknown;
+}
+
+interface ForkContextResponsePayload {
+  attachment?: { text?: unknown } | null;
+}
+
+function readSessionMessage(message: WebSocketMessage): SessionMessage | null {
+  if (typeof message !== "string") return null;
+  try {
+    const envelope = JSON.parse(message) as { type?: unknown; message?: SessionMessage };
+    return envelope.type === "session" ? (envelope.message ?? null) : envelope;
+  } catch {
+    return null;
+  }
+}
+
+export function observeForkAttachment(page: Page): {
+  waitForText: () => Promise<string>;
+} {
+  const attachmentTexts: string[] = [];
+  const daemonPortMarker = `:${getE2EDaemonPort()}`;
+
+  page.on("websocket", (socket) => {
+    if (!socket.url().includes(daemonPortMarker)) return;
+    socket.on("framereceived", ({ payload }) => {
+      const message = readSessionMessage(payload);
+      if (message?.type === "agent.fork_context.response") {
+        const response = (message.payload ?? {}) as ForkContextResponsePayload;
+        attachmentTexts.push(String(response.attachment?.text ?? ""));
+      }
+    });
+  });
+
+  return {
+    async waitForText() {
+      await expect.poll(() => attachmentTexts.length, { timeout: 30_000 }).toBeGreaterThan(0);
+      const text = attachmentTexts.at(-1);
+      if (text === undefined) {
+        throw new Error("Expected a chat history attachment from the fork");
+      }
+      return text;
+    },
+  };
+}
+
+function inFlightTurn(page: Page) {
+  return page.getByTestId("turn-working-indicator");
+}
+
+async function openForkMenu(page: Page, trigger: ReturnType<Page["getByRole"]>): Promise<void> {
+  await trigger.click();
+  await expect(page.getByRole("button", { name: "Fork in a new tab" })).toBeVisible({
+    timeout: 10_000,
+  });
+}
+
+export async function openMostRecentAssistantForkMenu(page: Page): Promise<void> {
+  await expect
+    .poll(
+      async () => {
+        await scrollAgentChatToBottom(page);
+        return page.getByRole("button", { name: "Fork chat" }).count();
+      },
+      { timeout: 30_000 },
+    )
+    .toBeGreaterThan(0);
+  const trigger = page.getByRole("button", { name: "Fork chat" }).last();
+  await expect(trigger).toBeVisible({ timeout: 30_000 });
+  await openForkMenu(page, trigger);
+}
+
+export async function forkMostRecentAssistantTurnToNewTab(page: Page): Promise<void> {
+  await openMostRecentAssistantForkMenu(page);
+  await page.getByRole("button", { name: "Fork in a new tab" }).click();
+}
+
+export async function expectInFlightForkAvailable(page: Page): Promise<void> {
+  const trigger = inFlightTurn(page).getByRole("button", { name: "Fork chat" });
+  await expect(trigger).toHaveCount(1, { timeout: 30_000 });
+  await expect(trigger).toBeVisible();
+}
+
+export async function forkInFlightTurnToNewTab(page: Page): Promise<void> {
+  const trigger = inFlightTurn(page).getByRole("button", { name: "Fork chat" });
+  await openForkMenu(page, trigger);
+  await page.getByRole("button", { name: "Fork in a new tab" }).click();
+}
+
+export async function forkMostRecentAssistantTurnToNewWorkspace(page: Page): Promise<void> {
+  await openMostRecentAssistantForkMenu(page);
+  await page.getByRole("button", { name: "Fork in a new workspace" }).click();
+}
+
+export async function expectChatHistoryAttachment(page: Page): Promise<void> {
+  const attachment = page.getByRole("button", { name: "Open chat history attachment" }).first();
+  await expect(attachment).toBeVisible({ timeout: 30_000 });
+  await expect(attachment).toContainText("Chat history");
+}
+
+export async function expectLiveAssistantText(page: Page, text: string): Promise<void> {
+  await expect(inFlightTurn(page)).toBeVisible({ timeout: 30_000 });
+  await expect(page.getByTestId("assistant-message").last()).toContainText(text, {
+    timeout: 60_000,
+  });
+}

packages/app/e2e/support/helpers/assistant-images.ts

@@ -0,0 +1,343 @@
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { deflateSync } from "node:zlib";
+import { expect, type Page } from "@playwright/test";
+import type { ArchiveTabAgent } from "./archive-tab";
+import { openWorkspaceWithAgents } from "./archive-tab";
+import { submitMessage } from "./composer";
+import type { SeedDaemonClient, SeededWorkspace } from "./seed-client";
+import { openAgentRoute } from "./mock-agent";
+import { rememberTimelineViewport, userScrollsTimelineToHistoryStart } from "./timeline-pagination";
+
+const IMAGE_PREVIEW_ERROR = "Unable to load image preview.";
+const SMALL_PNG = Buffer.from(
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg==",
+  "base64",
+);
+const TEN_MEBIBYTES = 10 * 1024 * 1024;
+
+export interface AssistantImageFixture {
+  alt: string;
+  height: number;
+  relativePath: string;
+  size: number;
+  width: number;
+}
+
+export async function createSmallAssistantPng(
+  workspace: SeededWorkspace,
+  input: { alt: string; fileName: string },
+): Promise<AssistantImageFixture> {
+  await writeFile(path.join(workspace.repoPath, input.fileName), SMALL_PNG);
+  return {
+    alt: input.alt,
+    height: 1,
+    relativePath: input.fileName,
+    size: SMALL_PNG.byteLength,
+    width: 1,
+  };
+}
+
+export async function createNearTenMegabyteAssistantPng(
+  workspace: SeededWorkspace,
+  input: { alt: string; fileName: string },
+): Promise<AssistantImageFixture> {
+  const width = 2_048;
+  const height = 1_280;
+  const bytes = encodeDeterministicPng(width, height);
+  if (bytes.byteLength < TEN_MEBIBYTES * 0.95 || bytes.byteLength > TEN_MEBIBYTES * 1.05) {
+    throw new Error(`Expected a PNG near 10 MiB, encoded ${bytes.byteLength} bytes`);
+  }
+  await writeFile(path.join(workspace.repoPath, input.fileName), bytes);
+  return {
+    alt: input.alt,
+    height,
+    relativePath: input.fileName,
+    size: bytes.byteLength,
+    width,
+  };
+}
+
+export async function createSettledMockAgent(
+  workspace: SeededWorkspace,
+  title: string,
+): Promise<ArchiveTabAgent> {
+  const agent = await workspace.client.createAgent({
+    provider: "mock",
+    model: "ten-second-stream",
+    modeId: "load-test",
+    cwd: workspace.repoPath,
+    workspaceId: workspace.workspaceId,
+    title,
+  });
+  await workspace.client.waitForAgentUpsert(
+    agent.id,
+    (snapshot) => snapshot.status === "idle",
+    30_000,
+  );
+  return {
+    id: agent.id,
+    title,
+    cwd: workspace.repoPath,
+    workspaceId: workspace.workspaceId,
+  };
+}
+
+export async function emitSettledAssistantImage(
+  client: SeedDaemonClient,
+  agent: ArchiveTabAgent,
+  image: AssistantImageFixture,
+): Promise<void> {
+  await client.sendAgentMessage(
+    agent.id,
+    `Emit settled assistant image Markdown: ![${image.alt}](${image.relativePath})`,
+  );
+  const result = await client.waitForFinish(agent.id, 30_000);
+  if (result.status !== "idle" || result.final?.lastError) {
+    throw new Error(
+      `Assistant image agent did not settle: ${result.final?.lastError ?? result.status}`,
+    );
+  }
+}
+
+export async function appendSettledTimelineTurns(
+  client: SeedDaemonClient,
+  agent: ArchiveTabAgent,
+  count: number,
+): Promise<void> {
+  for (let index = 0; index < count; index += 1) {
+    await client.sendAgentMessage(
+      agent.id,
+      `image-history-turn-${index}: emit 1 coalesced agent stream updates`,
+    );
+    const result = await client.waitForFinish(agent.id, 30_000);
+    if (result.status !== "idle" || result.final?.lastError) {
+      throw new Error(
+        `Assistant image history turn did not settle: ${result.final?.lastError ?? result.status}`,
+      );
+    }
+  }
+}
+
+export async function expectAssistantImageRendered(
+  page: Page,
+  image: AssistantImageFixture,
+): Promise<void> {
+  const rendered = page.getByRole("img", { name: image.alt }).first();
+  await expect(rendered).toBeVisible({ timeout: 30_000 });
+  await expect
+    .poll(async () =>
+      rendered.evaluate((element) => {
+        const imageElement =
+          element instanceof HTMLImageElement ? element : element.querySelector("img");
+        return imageElement?.complete
+          ? { height: imageElement.naturalHeight, width: imageElement.naturalWidth }
+          : null;
+      }),
+    )
+    .toEqual({ height: image.height, width: image.width });
+}
+
+export async function switchAwayAndBackWithoutImageInstability(
+  page: Page,
+  input: {
+    image: AssistantImageFixture;
+    imageAgent: ArchiveTabAgent;
+    otherAgent: ArchiveTabAgent;
+  },
+): Promise<void> {
+  await beginVisibleImageStabilityObservation(page, input.image.alt, input.imageAgent.id);
+  await selectSettledAgentTab(page, input.otherAgent);
+  await selectSettledAgentTab(page, input.imageAgent);
+  await expectAssistantImageRendered(page, input.image);
+  await expectNoVisibleImageInstability(page);
+}
+
+export async function openExistingImageAgentTabs(
+  page: Page,
+  input: { imageAgent: ArchiveTabAgent; otherAgent: ArchiveTabAgent },
+): Promise<void> {
+  await openWorkspaceWithAgents(page, [input.otherAgent, input.imageAgent]);
+}
+
+export async function openAssistantImageTimeline(
+  page: Page,
+  agent: ArchiveTabAgent,
+): Promise<void> {
+  await openAgentRoute(page, { workspaceId: agent.workspaceId, agentId: agent.id });
+}
+
+export async function expectAssistantImageNotMounted(
+  page: Page,
+  image: AssistantImageFixture,
+): Promise<void> {
+  await expect(page.getByRole("img", { name: image.alt })).toHaveCount(0);
+}
+
+export async function userPagesUntilAssistantImageRenders(
+  page: Page,
+  image: AssistantImageFixture,
+): Promise<void> {
+  const rendered = page.getByRole("img", { name: image.alt });
+  for (let attempt = 0; attempt < 10; attempt += 1) {
+    if ((await rendered.count()) > 0) {
+      await expectAssistantImageRendered(page, image);
+      return;
+    }
+    const previous = await rememberTimelineViewport(page);
+    await userScrollsTimelineToHistoryStart(page);
+    await expect
+      .poll(async () => (await rememberTimelineViewport(page)).scrollHeight)
+      .toBeGreaterThan(previous.scrollHeight);
+  }
+  await expectAssistantImageRendered(page, image);
+}
+
+export async function remountAndRecoverAssistantImageFromHistory(
+  page: Page,
+  image: AssistantImageFixture,
+): Promise<void> {
+  await page.reload();
+  await userPagesUntilAssistantImageRenders(page, image);
+}
+
+export async function sendFollowUpAndExpectVisibleResponse(
+  page: Page,
+  input: { prompt: string; response: string },
+): Promise<void> {
+  await submitMessage(page, input.prompt);
+  await expect(page.getByText(input.prompt, { exact: true })).toBeVisible({ timeout: 30_000 });
+  await expect(page.getByText(input.response, { exact: true })).toBeVisible({ timeout: 30_000 });
+}
+
+async function selectSettledAgentTab(page: Page, agent: ArchiveTabAgent): Promise<void> {
+  const tab = page.getByRole("button", { name: agent.title, exact: true });
+  await tab.click();
+  await expect(page).toHaveTitle(agent.title);
+  await expect(tab).toHaveAttribute("aria-selected", "true");
+  await expect(page.locator('[data-testid="agent-chat-scroll"]:visible').first()).toBeVisible({
+    timeout: 30_000,
+  });
+}
+
+async function beginVisibleImageStabilityObservation(
+  page: Page,
+  alt: string,
+  imageAgentId: string,
+): Promise<void> {
+  await page.evaluate(
+    ({ accessibleName, errorText, tabTestId }) => {
+      const record = {
+        errorSeen: false,
+        missingSeen: false,
+        inspect: () => undefined,
+        observer: null as MutationObserver | null,
+      };
+      const isVisible = (element: Element) => {
+        const rect = element.getBoundingClientRect();
+        return rect.width > 0 && rect.height > 0;
+      };
+      record.inspect = () => {
+        record.errorSeen ||= Array.from(document.querySelectorAll("*")).some(
+          (element) =>
+            element.children.length === 0 &&
+            element.textContent?.trim() === errorText &&
+            isVisible(element),
+        );
+        const imageTab = document.querySelector(`[data-testid="${tabTestId}"]`);
+        if (imageTab?.getAttribute("aria-selected") !== "true") return;
+        const imageVisible = Array.from(document.querySelectorAll('[role="img"]')).some(
+          (element) => element.getAttribute("aria-label") === accessibleName && isVisible(element),
+        );
+        record.missingSeen ||= !imageVisible;
+      };
+      record.observer = new MutationObserver(record.inspect);
+      record.observer.observe(document.body, {
+        attributes: true,
+        childList: true,
+        subtree: true,
+        characterData: true,
+      });
+      record.inspect();
+      (
+        window as unknown as {
+          __paseoAssistantImageObservation?: typeof record;
+        }
+      ).__paseoAssistantImageObservation = record;
+    },
+    {
+      accessibleName: alt,
+      errorText: IMAGE_PREVIEW_ERROR,
+      tabTestId: `workspace-tab-agent_${imageAgentId}`,
+    },
+  );
+}
+
+async function expectNoVisibleImageInstability(page: Page): Promise<void> {
+  const observation = await page.evaluate(() => {
+    const owner = window as unknown as {
+      __paseoAssistantImageObservation?: {
+        errorSeen: boolean;
+        missingSeen: boolean;
+        inspect(): void;
+        observer: MutationObserver | null;
+      };
+    };
+    const record = owner.__paseoAssistantImageObservation;
+    if (!record) throw new Error("Assistant image stability observation was not started");
+    record.inspect();
+    record.observer?.disconnect();
+    delete owner.__paseoAssistantImageObservation;
+    return { errorSeen: record.errorSeen, missingSeen: record.missingSeen };
+  });
+  expect(observation).toEqual({ errorSeen: false, missingSeen: false });
+}
+
+function encodeDeterministicPng(width: number, height: number): Buffer {
+  const stride = width * 4 + 1;
+  const scanlines = Buffer.allocUnsafe(stride * height);
+  let state = 0x9e3779b9;
+  for (let row = 0; row < height; row += 1) {
+    const rowOffset = row * stride;
+    scanlines[rowOffset] = 0;
+    for (let offset = 1; offset < stride; offset += 1) {
+      state ^= state << 13;
+      state ^= state >>> 17;
+      state ^= state << 5;
+      scanlines[rowOffset + offset] = state & 0xff;
+    }
+  }
+
+  const header = Buffer.alloc(13);
+  header.writeUInt32BE(width, 0);
+  header.writeUInt32BE(height, 4);
+  header[8] = 8;
+  header[9] = 6;
+  return Buffer.concat([
+    Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]),
+    pngChunk("IHDR", header),
+    pngChunk("IDAT", deflateSync(scanlines, { level: 0 })),
+    pngChunk("IEND", Buffer.alloc(0)),
+  ]);
+}
+
+function pngChunk(type: string, data: Buffer): Buffer {
+  const typeBytes = Buffer.from(type, "ascii");
+  const chunk = Buffer.allocUnsafe(12 + data.byteLength);
+  chunk.writeUInt32BE(data.byteLength, 0);
+  typeBytes.copy(chunk, 4);
+  data.copy(chunk, 8);
+  chunk.writeUInt32BE(crc32(Buffer.concat([typeBytes, data])), 8 + data.byteLength);
+  return chunk;
+}
+
+function crc32(bytes: Buffer): number {
+  let crc = 0xffffffff;
+  for (const byte of bytes) {
+    crc ^= byte;
+    for (let bit = 0; bit < 8; bit += 1) {
+      crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0);
+    }
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}

packages/app/e2e/support/helpers/branch-switcher.ts

@@ -0,0 +1,67 @@
+import { expect, type Page } from "@playwright/test";
+import { escapeRegex } from "./regex";
+
+// The branch switcher lives in the git diff panel's Changes header (right-side
+// ExplorerSidebar), not in the workspace header. It renders as a button whose
+// accessible name carries the current branch ("Current branch: <name>. Press to
+// switch branch."). Matching on the accessible name keeps these helpers tied to
+// what a screen reader user hears, and it proves the panel resolved a real
+// checkout directory from the opaque workspace id. Scoping to the changes header
+// keeps the matcher unambiguous even when the header is shared with diff actions.
+function branchSwitcherTrigger(page: Page, branchName: string) {
+  return page
+    .getByTestId("changes-header")
+    .getByRole("button", { name: new RegExp(`Current branch: ${escapeRegex(branchName)}\\b`) })
+    .filter({ visible: true })
+    .first();
+}
+
+// Opens the right-side explorer and lands on the Changes tab, where the branch
+// switcher and diff live. Git checkouts default to the Changes tab when the
+// explorer opens, so this is enough to reveal the switcher on desktop and mobile.
+export async function openChangesPanel(page: Page): Promise<void> {
+  await expect(page.getByTestId("workspace-explorer-toggle").first()).toBeVisible({
+    timeout: 30_000,
+  });
+  await page.getByTestId("workspace-explorer-toggle").first().click();
+  const changesTab = page.getByTestId("explorer-tab-changes").filter({ visible: true }).first();
+  await expect(changesTab).toBeVisible({ timeout: 30_000 });
+  await changesTab.click();
+  await expect(page.getByTestId("changes-header").filter({ visible: true }).first()).toBeVisible({
+    timeout: 30_000,
+  });
+}
+
+export async function expectWorkspaceBranch(page: Page, branchName: string): Promise<void> {
+  await expect(branchSwitcherTrigger(page, branchName)).toBeVisible({ timeout: 30_000 });
+}
+
+export async function switchBranchFromChangesPanel(
+  page: Page,
+  input: { from: string; to: string },
+): Promise<void> {
+  await branchSwitcherTrigger(page, input.from).click();
+
+  const picker = page.getByTestId("combobox-desktop-container");
+  await expect(picker).toBeVisible({ timeout: 30_000 });
+
+  // The branch switcher combobox renders its options as plain text rows with no ARIA
+  // role, so filter by the visible branch name and click the matching row. Filtering
+  // first guarantees a single, unambiguous match.
+  const search = page.getByPlaceholder("Filter branches...");
+  await expect(search).toBeVisible({ timeout: 30_000 });
+  await search.fill(input.to);
+
+  const option = picker.getByText(input.to, { exact: true });
+  await expect(option).toBeVisible({ timeout: 30_000 });
+  await option.click();
+
+  await expect(picker).not.toBeVisible({ timeout: 30_000 });
+}
+
+// The workspace header title is a plain static title in Model B; the branch
+// switcher must never appear there. Asserting on the header testID keeps this
+// honest even as the switcher continues to exist inside the Changes panel.
+export async function expectNoBranchSwitcherInWorkspaceHeader(page: Page): Promise<void> {
+  await expect(page.getByTestId("workspace-header-branch-switcher")).toHaveCount(0);
+}

packages/app/e2e/support/helpers/command-center-agent-controls.ts

@@ -0,0 +1,95 @@
+import { expect, type Page } from "@playwright/test";
+import type { SeededWorkspace } from "./seed-client";
+import { openCommandCenter } from "./command-center";
+
+export interface CommandCenterAgentControlChoice {
+  query: string;
+  choice: string;
+}
+
+export async function chooseCommandCenterAgentControl(input: {
+  page: Page;
+  query: string;
+  choice: string;
+}): Promise<void> {
+  const panel = input.page.getByTestId("command-center-panel");
+  await panel.getByRole("textbox").fill(input.query);
+  const choice = panel.getByRole("button", { name: input.choice });
+  await expect(choice).toBeVisible({ timeout: 30_000 });
+  await choice.click();
+}
+
+export async function expectCommandCenterAgentControlSelected(input: {
+  page: Page;
+  query: string;
+  choice: string;
+}): Promise<void> {
+  const panel = input.page.getByTestId("command-center-panel");
+  await panel.getByRole("textbox").fill(input.query);
+  const choice = panel.getByRole("button", { name: input.choice });
+  await expect(choice).toHaveRole("button");
+  await expect(choice).toHaveAttribute("aria-pressed", "true");
+}
+
+export async function applyCommandCenterAgentControls(
+  page: Page,
+  choices: readonly CommandCenterAgentControlChoice[],
+): Promise<void> {
+  for (const choice of choices) {
+    await openCommandCenter(page);
+    await chooseCommandCenterAgentControl({ page, ...choice });
+  }
+}
+
+export async function expectFocusedAgentControls(
+  page: Page,
+  choices: readonly CommandCenterAgentControlChoice[],
+): Promise<void> {
+  await openCommandCenter(page);
+  for (const choice of choices) {
+    await expectCommandCenterAgentControlSelected({ page, ...choice });
+  }
+}
+
+export async function submitDraftAgent(page: Page, prompt: string): Promise<void> {
+  const composer = page.getByRole("textbox", { name: "Message agent..." }).first();
+  await expect(composer).toBeEditable({ timeout: 30_000 });
+  await composer.fill(prompt);
+  await composer.press("Enter");
+  await expect(page.getByText(prompt, { exact: true }).first()).toBeVisible({ timeout: 30_000 });
+}
+
+export async function waitForDraftComposer(page: Page): Promise<void> {
+  await expect(page.getByRole("textbox", { name: "Message agent..." }).first()).toBeEditable({
+    timeout: 30_000,
+  });
+}
+
+export async function expectWorkspaceAgentConfiguration(
+  workspace: Pick<SeededWorkspace, "client" | "workspaceId">,
+  expected: { id?: string; provider: string; model: string | null; modeId: string | null },
+): Promise<void> {
+  await expect
+    .poll(
+      async () => {
+        const entries = (await workspace.client.fetchAgents({ scope: "active" })).entries;
+        const agent = entries
+          .map((entry) => entry.agent)
+          .find(
+            (candidate) =>
+              candidate.workspaceId === workspace.workspaceId &&
+              (expected.id === undefined || candidate.id === expected.id),
+          );
+        return agent
+          ? {
+              id: agent.id,
+              provider: agent.provider,
+              model: agent.model,
+              modeId: agent.currentModeId,
+            }
+          : null;
+      },
+      { timeout: 30_000 },
+    )
+    .toMatchObject(expected);
+}

packages/app/e2e/support/helpers/command-center-scroll.ts

@@ -0,0 +1,167 @@
+import { expect, type Locator, type Page } from "@playwright/test";
+
+interface CommandCenterScrollSample {
+  scrollTop: number;
+  firstResultTop: number;
+  viewportTop: number;
+}
+
+interface CommandCenterScrollObservation {
+  done: boolean;
+  samples: CommandCenterScrollSample[];
+}
+
+type ScrollOracleWindow = Window & {
+  __commandCenterScrollObservation?: CommandCenterScrollObservation;
+};
+
+export async function observeCommandCenterScroll(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    const oracleWindow = window as ScrollOracleWindow;
+    oracleWindow.__commandCenterScrollObservation = { done: false, samples: [] };
+
+    const discoverPanel = new MutationObserver(() => {
+      const panel = document.querySelector<HTMLElement>('[data-testid="command-center-panel"]');
+      const firstResult = panel?.querySelector<HTMLElement>('[role="button"]');
+      if (!panel || !firstResult) return;
+
+      let viewport = firstResult.parentElement;
+      while (viewport && viewport !== panel && viewport.scrollHeight <= viewport.clientHeight) {
+        viewport = viewport.parentElement;
+      }
+      if (!viewport || viewport === panel) return;
+
+      discoverPanel.disconnect();
+      let frame = 0;
+      const sample = () => {
+        const observation = oracleWindow.__commandCenterScrollObservation;
+        if (!observation) return;
+        const firstResultBounds = firstResult.getBoundingClientRect();
+        const viewportBounds = viewport.getBoundingClientRect();
+        observation.samples.push({
+          scrollTop: viewport.scrollTop,
+          firstResultTop: firstResultBounds.top,
+          viewportTop: viewportBounds.top,
+        });
+        frame += 1;
+        if (frame < 60) {
+          requestAnimationFrame(sample);
+          return;
+        }
+        observation.done = true;
+      };
+      requestAnimationFrame(sample);
+    });
+
+    discoverPanel.observe(document.body, { childList: true, subtree: true });
+  });
+}
+
+export async function openCommandCenterWithKeyboard(page: Page): Promise<Locator> {
+  await expect(page.getByTestId("sidebar-command-center-search")).toBeVisible({ timeout: 30_000 });
+  await page.keyboard.press("Meta+K");
+  const panel = page.getByTestId("command-center-panel");
+  await expect(panel).toBeVisible({ timeout: 30_000 });
+  return panel;
+}
+
+export async function expectCommandCenterToRemainAtTheTop(page: Page): Promise<void> {
+  await page.waitForFunction(
+    () => (window as ScrollOracleWindow).__commandCenterScrollObservation?.done === true,
+  );
+  const samples = await page.evaluate(
+    () => (window as ScrollOracleWindow).__commandCenterScrollObservation?.samples ?? [],
+  );
+
+  expect(samples.length).toBeGreaterThan(0);
+  expect(
+    Math.min(...samples.map((sample) => sample.firstResultTop - sample.viewportTop)),
+  ).toBeGreaterThanOrEqual(0);
+  expect(Math.max(...samples.map((sample) => sample.scrollTop))).toBe(0);
+}
+
+export async function expectPrimaryCommandCenterActions(panel: Locator): Promise<void> {
+  const expectedActions = [
+    { title: "New workspace", shortcut: "⌘N" },
+    { title: "History" },
+    { title: "Schedules" },
+    { title: "Settings", shortcut: "⌘," },
+    { title: "Keyboard shortcuts", shortcut: "?" },
+  ] as const;
+
+  for (const action of expectedActions) {
+    const row = panel.getByRole("button").filter({ hasText: action.title });
+    await expect(row).toBeVisible();
+    if ("shortcut" in action) await expect(row).toContainText(action.shortcut);
+  }
+
+  await expect(panel.getByRole("button").filter({ hasText: "Add project" })).toHaveCount(0);
+  await expect(panel.getByRole("button").filter({ hasText: "Home" })).toHaveCount(0);
+
+  const input = panel.getByTestId("command-center-input");
+  await input.fill("add project");
+  await expect(panel.getByRole("button").filter({ hasText: "Add project" })).toBeVisible();
+  await expect(panel.getByRole("button").filter({ hasText: "Home" })).toHaveCount(0);
+  await input.fill("home");
+  await expect(panel.getByRole("button").filter({ hasText: "Home" })).toBeVisible();
+  await expect(panel.getByRole("button").filter({ hasText: "Add project" })).toHaveCount(0);
+  await input.fill("");
+}
+
+export async function expectVisibleKeyboardNavigationNotToScroll(
+  page: Page,
+  panel: Locator,
+): Promise<void> {
+  for (let index = 0; index < 4; index += 1) await page.keyboard.press("ArrowDown");
+
+  const scrollSamples = await panel
+    .getByRole("button")
+    .first()
+    .evaluate(async (firstResult) => {
+      let viewport = firstResult.parentElement;
+      while (viewport && viewport.scrollHeight <= viewport.clientHeight) {
+        viewport = viewport.parentElement;
+      }
+      if (!viewport) throw new Error("Could not find the command center scroll viewport");
+
+      const samples: number[] = [];
+      for (let frame = 0; frame < 20; frame += 1) {
+        await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+        samples.push(viewport.scrollTop);
+      }
+      return samples;
+    });
+
+  expect(Math.max(...scrollSamples)).toBe(0);
+}
+
+export async function expectWorkspaceResultsToBeLimitedUntilSearch(panel: Locator): Promise<void> {
+  const workspaces = panel.locator(
+    '[data-testid^="command-center-workspace-"]:not([data-testid="command-center-workspace-subtitle"])',
+  );
+  const distinctWorkspaceCount = async () =>
+    new Set(
+      await workspaces.evaluateAll((elements) =>
+        elements.map((element) => element.getAttribute("data-testid")),
+      ),
+    ).size;
+
+  await expect.poll(distinctWorkspaceCount).toBe(5);
+
+  await panel.getByTestId("command-center-input").fill("Command Center Scroll");
+  await expect.poll(distinctWorkspaceCount).toBe(9);
+}
+
+export async function expectTightTwoLineResultSpacing(
+  panel: Locator,
+  title: string,
+): Promise<void> {
+  const row = panel.getByText(title, { exact: true }).locator("..");
+  const titleTop = await row
+    .getByText(title, { exact: true })
+    .evaluate((element) => element.getBoundingClientRect().top);
+  const subtitleTop = await row
+    .getByTestId("command-center-workspace-subtitle")
+    .evaluate((element) => element.getBoundingClientRect().top);
+  expect(subtitleTop - titleTop).toBeLessThanOrEqual(18);
+}

packages/app/e2e/support/helpers/command-center-workspace-actions.ts

@@ -0,0 +1,66 @@
+import { writeFileSync } from "node:fs";
+import path from "node:path";
+import { expect, type Locator, type Page } from "@playwright/test";
+import { buildHostWorkspaceRoute } from "@/utils/host-routes";
+import { openCommandCenter } from "./command-center";
+import { expectAppRoute } from "./route-assertions";
+import type { SeededWorkspace } from "./seed-client";
+import { getServerId } from "./server-id";
+import { expectTerminalTabOpen } from "./workspace-tabs";
+
+function action(panel: Locator, title: string): Locator {
+  const escapedTitle = title.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return panel.getByRole("button", { name: new RegExp(`^${escapedTitle}(?:\\s|$)`) });
+}
+
+export async function makeWorkspacePrimaryGitActionCommit(seeded: SeededWorkspace): Promise<void> {
+  writeFileSync(path.join(seeded.repoPath, "command-center-dirty.txt"), "dirty\n");
+  const refreshed = await seeded.client.checkoutRefresh(seeded.repoPath);
+  if (!refreshed.success) {
+    throw new Error(`Failed to refresh checkout: ${JSON.stringify(refreshed.error)}`);
+  }
+}
+
+export async function openWorkspaceFromCommandCenter(
+  page: Page,
+  seeded: SeededWorkspace,
+  title: string,
+): Promise<void> {
+  const panel = await openCommandCenter(page);
+  await panel.getByTestId("command-center-input").fill(title);
+  await page.keyboard.press("Enter");
+  await expectAppRoute(page, buildHostWorkspaceRoute(getServerId(), seeded.workspaceId), {
+    timeout: 30_000,
+  });
+}
+
+export async function expectDefaultWorkspaceActions(panel: Locator): Promise<void> {
+  await expect(panel.getByText("Workspace actions", { exact: true })).toBeVisible({
+    timeout: 30_000,
+  });
+  await expect(action(panel, "New agent")).toBeVisible();
+  await expect(action(panel, "Commit")).toBeVisible();
+  await expect(action(panel, "Push")).toHaveCount(0);
+  await expect(action(panel, "New terminal")).toHaveCount(0);
+  await expect(action(panel, "Split pane right")).toHaveCount(0);
+  await expect(action(panel, "Home")).toHaveCount(0);
+  await expect(action(panel, "Add project")).toHaveCount(0);
+}
+
+export async function expectWorkspaceActionsAvailableThroughSearch(panel: Locator): Promise<void> {
+  const input = panel.getByTestId("command-center-input");
+  await input.fill("push");
+  await expect(action(panel, "Push")).toBeVisible();
+
+  await input.fill("home");
+  await expect(action(panel, "Home")).toBeVisible();
+
+  await input.fill("git");
+  await expect.poll(() => panel.getByRole("button").count()).toBeGreaterThan(1);
+}
+
+export async function createTerminalFromCommandCenter(page: Page, panel: Locator): Promise<void> {
+  await panel.getByTestId("command-center-input").fill("terminal");
+  await page.keyboard.press("Enter");
+  await expectTerminalTabOpen(page);
+}

packages/app/e2e/support/helpers/command-center.ts

@@ -0,0 +1,14 @@
+import { expect, type Locator, type Page } from "@playwright/test";
+
+// Opens the command center / global search palette from the sidebar and returns its panel.
+export async function openCommandCenter(page: Page): Promise<Locator> {
+  await page.getByTestId("sidebar-command-center-search").click();
+  const panel = page.getByTestId("command-center-panel");
+  await expect(panel).toBeVisible({ timeout: 30_000 });
+  return panel;
+}
+
+export async function closeCommandCenter(page: Page): Promise<void> {
+  await page.keyboard.press("Escape");
+  await expect(page.getByTestId("command-center-panel")).not.toBeVisible();
+}

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

@@ -0,0 +1,248 @@
+import { expect, type Page } from "@playwright/test";
+import { buildHostWorkspaceRoute } from "@/utils/host-routes";
+import { createTempGitRepo } from "./workspace";
+import { connectSeedClient, type SeedDaemonClient } from "./seed-client";
+import { gotoAppShell } from "./app";
+import { connectWorkspaceSetupClient } from "./workspace-setup";
+import { selectWorkspaceInSidebar } from "./sidebar";
+import { getServerId } from "./server-id";
+import { waitForTabBar } from "./launcher";
+
+function composerInput(page: Page) {
+  return page.getByRole("textbox", { name: "Message agent..." }).first();
+}
+
+export function composerLocator(page: Page) {
+  return composerInput(page);
+}
+
+export async function expectComposerVisible(
+  page: Page,
+  options?: { timeout?: number },
+): Promise<void> {
+  await expect(composerInput(page)).toBeVisible({ timeout: options?.timeout ?? 15_000 });
+}
+
+export async function expectComposerDisabled(page: Page): Promise<void> {
+  // React Native TextInput with editable={false} renders as <textarea readonly> on web,
+  // not <textarea disabled>. Use not.toBeEditable() to match either form.
+  await expect(composerInput(page)).not.toBeEditable({ timeout: 10_000 });
+}
+
+export async function expectComposerDraft(page: Page, text: string): Promise<void> {
+  await expect(composerInput(page)).toHaveValue(text, { timeout: 5_000 });
+}
+
+export async function expectComposerEditable(page: Page): Promise<void> {
+  await expect(composerInput(page)).toBeEditable({ timeout: 15_000 });
+}
+
+export async function submitMessage(page: Page, text: string): Promise<void> {
+  const input = composerInput(page);
+  await expect(input).toBeEditable({ timeout: 30_000 });
+  await input.fill(text);
+  await input.press("Enter");
+}
+
+export async function fillComposerDraft(page: Page, text: string): Promise<void> {
+  await composerInput(page).fill(text);
+}
+
+export async function sendDraftToQueue(page: Page): Promise<void> {
+  await composerInput(page).press("Control+Enter");
+}
+
+export async function expectQueuedMessageButton(page: Page): Promise<void> {
+  await expect(page.getByRole("button", { name: "Send queued message now" })).toBeVisible({
+    timeout: 10_000,
+  });
+}
+
+export async function cancelAgent(page: Page): Promise<void> {
+  const stopButton = page.getByRole("button", { name: /stop|cancel/i }).first();
+  await expect(stopButton).toBeVisible({ timeout: 10_000 });
+  await stopButton.click();
+}
+
+/** Escape is bound to the "agent.interrupt" keyboard shortcut. */
+export async function pressInterruptShortcut(page: Page): Promise<void> {
+  await page.keyboard.press("Escape");
+}
+
+export async function openAttachmentMenu(page: Page): Promise<void> {
+  await page.getByTestId("message-input-attach-button").filter({ visible: true }).first().click();
+  await expect(page.getByTestId("message-input-attachment-menu")).toBeVisible({ timeout: 5_000 });
+}
+
+export async function expectAttachButtonDisabled(page: Page): Promise<void> {
+  await expect(
+    page.getByTestId("message-input-attach-button").filter({ visible: true }).first(),
+  ).toBeDisabled({ timeout: 10_000 });
+}
+
+export async function attachImageFromMenu(
+  page: Page,
+  file: { name: string; mimeType: string; buffer: Buffer },
+): Promise<void> {
+  const chooserPromise = page.waitForEvent("filechooser", { timeout: 10_000 });
+  await openAttachmentMenu(page);
+  await page.getByTestId("message-input-attachment-menu-item-image").click();
+  const chooser = await chooserPromise;
+  await chooser.setFiles([file]);
+}
+
+export async function expectAttachmentPill(page: Page, testID: string): Promise<void> {
+  await expect(page.getByTestId(testID).first()).toBeVisible({ timeout: 10_000 });
+}
+
+export async function dropFileOnComposer(
+  page: Page,
+  file: { name: string; mimeType: string; buffer: Buffer },
+): Promise<void> {
+  const dataTransfer = await page.evaluateHandle(
+    ({ name, mimeType, base64 }) => {
+      const bytes = Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));
+      const droppedFile = new File([bytes], name, { type: mimeType });
+      const transfer = new DataTransfer();
+      transfer.items.add(droppedFile);
+      return transfer;
+    },
+    {
+      name: file.name,
+      mimeType: file.mimeType,
+      base64: file.buffer.toString("base64"),
+    },
+  );
+
+  const composerRoot = page.getByTestId("message-input-root").filter({ visible: true }).first();
+  await expect(composerRoot).toBeVisible({ timeout: 10_000 });
+  await composerRoot.dispatchEvent("dragenter", { dataTransfer });
+  await composerRoot.dispatchEvent("dragover", { dataTransfer });
+  await composerRoot.dispatchEvent("drop", { dataTransfer });
+  await dataTransfer.dispose();
+}
+
+/** Hover to reveal the X button (hidden until hover on desktop web), then click by accessible label. */
+export async function removeAttachmentPill(
+  page: Page,
+  pillTestId: string,
+  removeAccessibilityLabel: string,
+): Promise<void> {
+  await page.getByTestId(pillTestId).first().hover();
+  await page.getByRole("button", { name: removeAccessibilityLabel }).first().click();
+}
+
+export async function expectGithubAttachmentPill(
+  page: Page,
+  input: { number: number; title: string },
+): Promise<void> {
+  const pill = page.getByTestId("composer-github-attachment-pill").first();
+  await expect(pill).toBeVisible({ timeout: 10_000 });
+  await expect(pill).toContainText(`#${input.number}`);
+  await expect(pill).toContainText(input.title);
+}
+
+export async function openImageLightbox(page: Page): Promise<void> {
+  await page.getByRole("button", { name: "Open image attachment" }).first().click();
+  await expect(page.getByTestId("attachment-lightbox-close")).toBeVisible({ timeout: 5_000 });
+}
+
+export async function closeImageLightbox(page: Page): Promise<void> {
+  await page.keyboard.press("Escape");
+  await expect(page.getByTestId("attachment-lightbox-close")).not.toBeVisible({ timeout: 5_000 });
+}
+
+export async function openGithubPickerFromMenu(page: Page): Promise<void> {
+  await openAttachmentMenu(page);
+  await page.getByTestId("message-input-attachment-menu-item-github").click();
+  await expect(page.getByTestId("combobox-desktop-container")).toBeVisible({ timeout: 5_000 });
+}
+
+/** Open picker, type a query, wait for the matching option by id (e.g. "issue:3", "pr:1"), and click it. */
+export async function selectGithubOption(
+  page: Page,
+  searchTerm: string,
+  optionId: string,
+): Promise<void> {
+  await openGithubPickerFromMenu(page);
+  const searchInput = page.getByPlaceholder("Search issues and PRs...");
+  await expect(searchInput).toBeVisible({ timeout: 5_000 });
+  await searchInput.fill(searchTerm);
+  const option = page.getByTestId(`composer-github-option-${optionId}`);
+  await expect(option).toBeVisible({ timeout: 15_000 });
+  await option.click();
+}
+
+export interface MockAgentSetup {
+  client: SeedDaemonClient;
+  repo: Awaited<ReturnType<typeof createTempGitRepo>>;
+  cleanup: () => Promise<void>;
+}
+
+/** Create a temp repo, start a mock agent, navigate to it, and wait for it to be running. */
+export async function startRunningMockAgent(
+  page: Page,
+  opts: { prefix: string; model: string; prompt: string },
+): Promise<MockAgentSetup> {
+  const serverId = getServerId();
+
+  const repo = await createTempGitRepo(opts.prefix);
+  const client = await connectSeedClient();
+  const createdWorkspace = await client.createWorkspace({
+    source: { kind: "directory", path: repo.path },
+  });
+  if (!createdWorkspace.workspace) {
+    throw new Error(createdWorkspace.error ?? "Failed to create workspace");
+  }
+  const workspace = createdWorkspace.workspace;
+  const agent = await client.createAgent({
+    provider: "mock",
+    cwd: repo.path,
+    workspaceId: workspace.id,
+    model: opts.model,
+  });
+  const agentUrl = `${buildHostWorkspaceRoute(serverId, workspace.id)}?open=${encodeURIComponent(`agent:${agent.id}`)}`;
+  await page.goto(agentUrl);
+  await expectComposerVisible(page);
+  await client.sendAgentMessage(agent.id, opts.prompt);
+  await expect(page.getByRole("button", { name: /stop|cancel/i }).first()).toBeVisible({
+    timeout: 30_000,
+  });
+  return {
+    client,
+    repo,
+    cleanup: async () => {
+      await client.removeProject(workspace.projectId).catch(() => undefined);
+      await client.close().catch(() => undefined);
+      await repo.cleanup().catch(() => undefined);
+    },
+  };
+}
+
+export interface GithubWorkspaceHandle {
+  cleanup: () => Promise<void>;
+}
+
+/** Open a workspace backed by an existing repo path (e.g. a cloned GitHub repo). */
+export async function openGithubWorkspace(
+  page: Page,
+  repoPath: string,
+): Promise<GithubWorkspaceHandle> {
+  const client = await connectWorkspaceSetupClient();
+  const createdWorkspace = await client.createWorkspace({
+    source: { kind: "directory", path: repoPath },
+  });
+  if (!createdWorkspace.workspace) {
+    throw new Error(createdWorkspace.error ?? `Failed to create workspace ${repoPath}`);
+  }
+  const workspace = createdWorkspace.workspace;
+  await gotoAppShell(page);
+  await selectWorkspaceInSidebar(page, workspace.id);
+  await waitForTabBar(page);
+  return {
+    cleanup: async () => {
+      await client.removeProject(workspace.projectId).catch(() => undefined);
+      await client.close().catch(() => undefined);
+    },
+  };
+}

packages/app/e2e/support/helpers/daemon-client-loader.ts

@@ -0,0 +1,66 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { getE2EDaemonPort } from "./daemon-port";
+import { createNodeWebSocketFactory, type NodeWebSocketFactory } from "./node-ws-factory";
+
+export async function loadDaemonClientConstructor<ClientConfig, ClientInstance>(): Promise<
+  new (config: ClientConfig) => ClientInstance
+> {
+  const repoRoot = path.resolve(__dirname, "../../../../../");
+  const moduleUrl = pathToFileURL(
+    path.join(repoRoot, "packages/client/dist/daemon-client.js"),
+  ).href;
+  const mod = (await import(moduleUrl)) as {
+    DaemonClient: new (config: ClientConfig) => ClientInstance;
+  };
+  return mod.DaemonClient;
+}
+
+interface E2EDaemonClientConfig {
+  url: string;
+  clientId: string;
+  clientType: "cli";
+  appVersion?: string;
+  webSocketFactory?: NodeWebSocketFactory;
+}
+
+function resolveDaemonWsUrl(port?: number): string {
+  return `ws://127.0.0.1:${port ?? getE2EDaemonPort()}/ws`;
+}
+
+export interface ConnectDaemonClientOptions {
+  clientIdPrefix: string;
+  appVersion?: string;
+  port?: number;
+}
+
+/**
+ * Connects an in-test daemon client over the isolated E2E daemon's WebSocket.
+ * The port-6767 guard keeps tests off the developer daemon. Each helper passes
+ * its own typed client interface as the generic.
+ */
+export async function connectDaemonClient<ClientInstance extends { connect(): Promise<void> }>(
+  options: ConnectDaemonClientOptions,
+): Promise<ClientInstance> {
+  const DaemonClient = await loadDaemonClientConstructor<E2EDaemonClientConfig, ClientInstance>();
+  const client = new DaemonClient({
+    url: resolveDaemonWsUrl(options.port),
+    clientId: `${options.clientIdPrefix}-${randomUUID()}`,
+    clientType: "cli",
+    appVersion: options.appVersion ?? loadAppVersion(),
+    webSocketFactory: createNodeWebSocketFactory(),
+  });
+  await client.connect();
+  return client;
+}
+
+function loadAppVersion(): string {
+  const packageJsonPath = path.resolve(__dirname, "../../../package.json");
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8")) as { version?: unknown };
+  if (typeof packageJson.version !== "string" || packageJson.version.length === 0) {
+    throw new Error(`Missing app version in ${packageJsonPath}`);
+  }
+  return packageJson.version;
+}

packages/app/e2e/support/helpers/daemon-port.ts

@@ -0,0 +1,38 @@
+import { escapeRegex } from "./regex";
+
+/**
+ * Resolves the isolated E2E daemon's port, which Playwright's globalSetup
+ * publishes into the environment before any spec runs. Helpers and specs that
+ * build daemon WebSocket URLs, route patterns, or host endpoints share this
+ * accessor instead of re-reading the env var.
+ *
+ * The port-6767 guard is a hard guardrail: 6767 is the developer's default
+ * daemon, which manages real agents. The e2e port is never legitimately 6767,
+ * so refusing it here keeps every test off the developer daemon.
+ */
+export function getE2EDaemonPort(): string {
+  const port = process.env.E2E_DAEMON_PORT;
+  if (!port) {
+    throw new Error("E2E_DAEMON_PORT is not set (expected from the Playwright worker fixture).");
+  }
+  if (port === "6767") {
+    throw new Error("E2E_DAEMON_PORT must not point at the developer daemon (6767).");
+  }
+  return port;
+}
+
+/**
+ * Playwright `routeWebSocket` matcher for a WebSocket on `port`. Matches the
+ * `:<port>` segment at a word boundary, so it catches the URL regardless of
+ * host or path. Use this when intercepting connections to an arbitrary port
+ * (e.g. blocking an unreachable test host); for the E2E daemon itself, prefer
+ * `daemonWsRoutePattern()`.
+ */
+export function wsRoutePatternForPort(port: string): RegExp {
+  return new RegExp(`:${escapeRegex(port)}\\b`);
+}
+
+/** `routeWebSocket` matcher for the isolated E2E daemon's WebSocket. */
+export function daemonWsRoutePattern(): RegExp {
+  return wsRoutePatternForPort(getE2EDaemonPort());
+}

packages/app/e2e/support/helpers/daemon-registry.ts

@@ -0,0 +1,44 @@
+export const TEST_HOST_LABEL = "localhost";
+
+export const TEST_PROVIDER_PREFERENCES = {
+  claude: { model: "haiku" },
+  codex: { model: "gpt-5.4-mini", thinkingOptionId: "low" },
+} as const;
+
+export function buildDirectTcpConnection(endpoint: string) {
+  return {
+    id: `direct:${endpoint}`,
+    type: "directTcp" as const,
+    endpoint,
+  };
+}
+
+export function buildSeededHost(input: {
+  serverId: string;
+  endpoint: string;
+  label?: string;
+  nowIso: string;
+}) {
+  const connection = buildDirectTcpConnection(input.endpoint);
+  return {
+    serverId: input.serverId,
+    label: input.label ?? TEST_HOST_LABEL,
+    connections: [connection],
+    preferredConnectionId: connection.id,
+    createdAt: input.nowIso,
+    updatedAt: input.nowIso,
+  };
+}
+
+export const TEST_MOCK_PROVIDER_PREFERENCES = {
+  ...TEST_PROVIDER_PREFERENCES,
+  mock: { model: "ten-second-stream" },
+} as const;
+
+export function buildCreateAgentPreferences(serverId: string) {
+  return {
+    serverId,
+    provider: "mock" as const,
+    providerPreferences: TEST_MOCK_PROVIDER_PREFERENCES,
+  };
+}

packages/app/e2e/support/helpers/daemon-update.ts

@@ -0,0 +1,97 @@
+import { fork, type ChildProcess } from "node:child_process";
+import { once } from "node:events";
+import path from "node:path";
+
+export interface OutdatedDaemon {
+  endpoint: string;
+  label: string;
+  serverId: string;
+  close(): Promise<void>;
+}
+
+interface OutdatedDaemonReadyMessage {
+  type: "ready";
+  endpoint: string;
+  serverId: string;
+}
+
+interface OutdatedDaemonErrorMessage {
+  type: "error";
+  error: string;
+}
+
+type OutdatedDaemonMessage = OutdatedDaemonReadyMessage | OutdatedDaemonErrorMessage;
+
+export async function startOutdatedDaemon(options?: {
+  desktopManaged?: boolean;
+  daemonStatusRpcCapability?: boolean;
+  relayConfigCapability?: boolean;
+}): Promise<OutdatedDaemon> {
+  const metroPort = process.env.E2E_METRO_PORT;
+  if (!metroPort) {
+    throw new Error("E2E_METRO_PORT is not set - globalSetup must run first");
+  }
+
+  const child = fork(
+    path.resolve(__dirname, "../../../../server/src/server/test-utils/outdated-daemon-process.ts"),
+    {
+      env: {
+        ...process.env,
+        E2E_METRO_PORT: metroPort,
+        E2E_DESKTOP_MANAGED: options?.desktopManaged === true ? "1" : "0",
+        E2E_DAEMON_STATUS_RPC_CAPABILITY: options?.daemonStatusRpcCapability === false ? "0" : "1",
+        E2E_RELAY_CONFIG_CAPABILITY: options?.relayConfigCapability === false ? "0" : "1",
+      },
+      execArgv: ["--import", "tsx"],
+      stdio: ["ignore", "pipe", "pipe", "ipc"],
+    },
+  );
+  const stderr: string[] = [];
+  child.stderr?.on("data", (data: Buffer) => stderr.push(data.toString("utf8")));
+
+  try {
+    const ready = await waitForDaemon(child, stderr);
+    return {
+      endpoint: ready.endpoint,
+      label: options?.desktopManaged === true ? "outdated Desktop host" : "outdated host",
+      serverId: ready.serverId,
+      async close() {
+        if (child.exitCode !== null || child.signalCode !== null) return;
+        child.kill("SIGTERM");
+        await once(child, "exit");
+      },
+    };
+  } catch (error) {
+    child.kill("SIGTERM");
+    throw error;
+  }
+}
+
+async function waitForDaemon(
+  child: ChildProcess,
+  stderr: string[],
+): Promise<OutdatedDaemonReadyMessage> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      reject(new Error(`Timed out starting outdated daemon. ${stderr.join("")}`));
+    }, 20_000);
+
+    child.once("exit", (code, signal) => {
+      clearTimeout(timeout);
+      reject(
+        new Error(
+          `Outdated daemon exited before startup (code ${String(code)}, signal ${String(signal)}). ${stderr.join("")}`,
+        ),
+      );
+    });
+    child.once("message", (message: OutdatedDaemonMessage) => {
+      if (message.type === "error") {
+        clearTimeout(timeout);
+        reject(new Error(message.error));
+        return;
+      }
+      clearTimeout(timeout);
+      resolve(message);
+    });
+  });
+}

packages/app/e2e/support/helpers/daemon-websocket-gate.ts

@@ -0,0 +1,701 @@
+import type { Page, WebSocketRoute } from "@playwright/test";
+import { daemonWsRoutePattern } from "./daemon-port";
+
+export interface DirectoryBootstrapCounts {
+  agents: number;
+  workspaces: number;
+}
+
+export interface DirectoryRequestStartCounts {
+  subscribed: DirectoryBootstrapCounts;
+  unsubscribed: DirectoryBootstrapCounts;
+  total: DirectoryBootstrapCounts;
+}
+
+interface ClientRequest {
+  type?: unknown;
+  direction?: unknown;
+  subscribe?: unknown;
+  page?: { cursor?: unknown };
+  payload?: unknown;
+  mode?: unknown;
+  path?: unknown;
+}
+
+interface ServerMessage {
+  type?: unknown;
+  payload?: {
+    initial?: {
+      path?: unknown;
+    };
+    version?: {
+      status?: unknown;
+      path?: unknown;
+    };
+  };
+}
+
+interface HeldAgentUpdate {
+  agentId: string;
+  status: string;
+}
+
+interface HeldServerMessage {
+  browser: WebSocketRoute;
+  message: string | Buffer;
+  key: string;
+  agentStreamFollowers: Array<string | Buffer>;
+  blockedAgentId?: string;
+}
+
+function readSessionMessage(message: string | Buffer): ClientRequest | null {
+  try {
+    const envelope = JSON.parse(typeof message === "string" ? message : message.toString()) as {
+      type?: unknown;
+      message?: ClientRequest;
+    };
+    return envelope.message ?? envelope;
+  } catch {
+    return null;
+  }
+}
+
+function readClientRequest(message: string | Buffer): ClientRequest | null {
+  if (typeof message !== "string") return null;
+  try {
+    const envelope = JSON.parse(message) as {
+      type?: unknown;
+      message?: ClientRequest;
+    };
+    return envelope.type === "session" ? (envelope.message ?? null) : envelope;
+  } catch {
+    return null;
+  }
+}
+
+function directoryForRequest(request: ClientRequest): keyof DirectoryBootstrapCounts | null {
+  if (request.page?.cursor) return null;
+  if (request.type === "fetch_agents_request") return "agents";
+  if (request.type === "fetch_workspaces_request") return "workspaces";
+  return null;
+}
+
+function stripAssistantMessageId(
+  message: string | Buffer,
+  enabled: boolean,
+  messageType: unknown,
+): string | Buffer {
+  if (!enabled || messageType !== "agent_stream" || typeof message !== "string") return message;
+  const envelope = JSON.parse(message) as {
+    message?: { payload?: { event?: { type?: unknown; item?: Record<string, unknown> } } };
+    payload?: { event?: { type?: unknown; item?: Record<string, unknown> } };
+  };
+  const event = (envelope.message?.payload ?? envelope.payload)?.event;
+  if (event?.type !== "timeline" || event.item?.type !== "assistant_message") return message;
+  delete event.item.messageId;
+  return JSON.stringify(envelope);
+}
+
+function stripCanonicalSubmittedPrompts(
+  message: string | Buffer,
+  enabled: boolean,
+  messageType: unknown,
+): string | Buffer {
+  if (!enabled || messageType !== "status" || typeof message !== "string") return message;
+  const envelope = JSON.parse(message) as {
+    message?: { payload?: { status?: unknown; features?: Record<string, unknown> } };
+    payload?: { status?: unknown; features?: Record<string, unknown> };
+  };
+  const payload = envelope.message?.payload ?? envelope.payload;
+  if (payload?.status !== "server_info" || !payload.features) return message;
+  delete payload.features.canonicalSubmittedPrompts;
+  return JSON.stringify(envelope);
+}
+
+function forceTimelineReset(message: string | Buffer, enabled: boolean): string | Buffer {
+  if (!enabled || typeof message !== "string") return message;
+  const envelope = JSON.parse(message) as {
+    message?: { payload?: Record<string, unknown> };
+    payload?: Record<string, unknown>;
+  };
+  const payload = envelope.message?.payload ?? envelope.payload;
+  if (!payload) return message;
+  payload.epoch = `playwright-reset-${Date.now()}`;
+  payload.reset = true;
+  return JSON.stringify(envelope);
+}
+
+function readAgentStreamEventType(message: ClientRequest | null): string | null {
+  if (message?.type !== "agent_stream" || !message.payload || typeof message.payload !== "object") {
+    return null;
+  }
+  const event = (message.payload as { event?: { type?: unknown } }).event;
+  return typeof event?.type === "string" ? event.type : null;
+}
+
+function readAgentStreamAgentId(message: ClientRequest | null): string | null {
+  if (message?.type !== "agent_stream" || !message.payload || typeof message.payload !== "object") {
+    return null;
+  }
+  const agentId = (message.payload as { agentId?: unknown }).agentId;
+  return typeof agentId === "string" ? agentId : null;
+}
+
+function readAgentStreamItemType(message: ClientRequest | null): string | null {
+  if (message?.type !== "agent_stream" || !message.payload || typeof message.payload !== "object") {
+    return null;
+  }
+  const event = (message.payload as { event?: { type?: unknown; item?: { type?: unknown } } })
+    .event;
+  return event?.type === "timeline" && typeof event.item?.type === "string"
+    ? event.item.type
+    : null;
+}
+
+function shouldSuppressServerMessage(input: {
+  message: ClientRequest | null;
+  messageTypes: ReadonlySet<string>;
+  agentStreamEventTypes: ReadonlySet<string>;
+  agentStreamItemTypes: ReadonlySet<string>;
+  suppressAgentStream: boolean;
+}): boolean {
+  const messageType = typeof input.message?.type === "string" ? input.message.type : null;
+  if (messageType && input.messageTypes.has(messageType)) return true;
+  if (input.suppressAgentStream && messageType === "agent_stream") return true;
+  const itemType = readAgentStreamItemType(input.message);
+  if (itemType && input.agentStreamItemTypes.has(itemType)) return true;
+  const eventType = readAgentStreamEventType(input.message);
+  return Boolean(eventType && input.agentStreamEventTypes.has(eventType));
+}
+
+function serverMessageKey(type: string): string {
+  return `message:${type}`;
+}
+
+function agentStreamEventKey(type: string): string {
+  return `agent-stream-event:${type}`;
+}
+
+function agentUpdateKey(agentId: string, status: string): string {
+  return `agent-update:${agentId}:${status}`;
+}
+
+function matchesAgentUpdate(message: ClientRequest | null, agentUpdate: HeldAgentUpdate): boolean {
+  if (message?.type !== "agent_update") return false;
+  const payload = message.payload;
+  if (
+    !payload ||
+    typeof payload !== "object" ||
+    (payload as { kind?: unknown }).kind !== "upsert"
+  ) {
+    return false;
+  }
+  const agent = (payload as { agent?: { id?: unknown; status?: unknown } }).agent;
+  return agent?.id === agentUpdate.agentId && agent.status === agentUpdate.status;
+}
+
+function recordClientRequest(
+  request: ClientRequest | null,
+  clientRequestCounts: Map<string, number>,
+  timelineRequestCounts: Map<string, number>,
+  directoryStarts: DirectoryRequestStartCounts,
+): void {
+  if (typeof request?.type !== "string") return;
+  clientRequestCounts.set(request.type, (clientRequestCounts.get(request.type) ?? 0) + 1);
+  if (request.type === "fetch_agent_timeline_request" && typeof request.direction === "string") {
+    timelineRequestCounts.set(
+      request.direction,
+      (timelineRequestCounts.get(request.direction) ?? 0) + 1,
+    );
+  }
+  const directory = directoryForRequest(request);
+  if (!directory) return;
+  const subscription = request.subscribe === undefined ? "unsubscribed" : "subscribed";
+  directoryStarts[subscription][directory] += 1;
+  directoryStarts.total[directory] += 1;
+}
+
+export async function installDaemonWebSocketGate(page: Page) {
+  let acceptingConnections = true;
+  let reconnectWithFreshClient = false;
+  let suppressAgentStream = false;
+  let forceTimelineEpochReset = false;
+  let stripAssistantMessageIds = false;
+  let stripCanonicalSubmittedPromptsFeature = false;
+  let heldClientRequestType: string | null = null;
+  let heldClientRequest: { server: WebSocketRoute; message: string | Buffer } | null = null;
+  let resolveHeldClientRequest: (() => void) | null = null;
+  const pendingServerMessageHolds = new Map<string, (message: ClientRequest | null) => boolean>();
+  const heldServerMessages: HeldServerMessage[] = [];
+  const heldServerMessageWaiters = new Set<() => void>();
+  const suppressedServerMessageTypes = new Set<string>();
+  const suppressedAgentStreamEventTypes = new Set<string>();
+  const suppressedAgentStreamItemTypes = new Set<string>();
+  const activeSockets = new Set<WebSocketRoute>();
+  let latestServer: WebSocketRoute | null = null;
+  const directoryStarts: DirectoryRequestStartCounts = {
+    subscribed: { agents: 0, workspaces: 0 },
+    unsubscribed: { agents: 0, workspaces: 0 },
+    total: { agents: 0, workspaces: 0 },
+  };
+  const clientRequestCounts = new Map<string, number>();
+  const timelineRequestCounts = new Map<string, number>();
+  const serverMessageCounts = new Map<string, number>();
+  const agentStreamEventCounts = new Map<string, number>();
+  const agentStreamItemCounts = new Map<string, number>();
+  const serverMessageWaiters = new Set<() => void>();
+  const subscribedFilePaths = new Set<string>();
+  const fileSubscriptionWaiters = new Map<string, () => void>();
+  const observedFileUpdates = new Set<string>();
+  const fileUpdateWaiters = new Map<string, () => void>();
+  let fileReadPathToHold: string | null = null;
+  let heldFileReads: Array<() => void> = [];
+  let resolveHeldFileRead: (() => void) | null = null;
+  let heldFileReadPromise = Promise.resolve();
+  let readyFileUpdatePathToHold: string | null = null;
+  let heldReadyFileUpdate: (() => void) | null = null;
+  let resolveHeldReadyFileUpdate: (() => void) | null = null;
+  let heldReadyFileUpdatePromise = Promise.resolve();
+  const recordFileUpdate = (message: ServerMessage): void => {
+    if (
+      message.type !== "fs.file.update" ||
+      typeof message.payload?.version?.status !== "string" ||
+      typeof message.payload.version.path !== "string"
+    ) {
+      return;
+    }
+    const key = `${message.payload.version.path}:${message.payload.version.status}`;
+    observedFileUpdates.add(key);
+    fileUpdateWaiters.get(key)?.();
+    fileUpdateWaiters.delete(key);
+  };
+
+  const recordServerMessage = (message: ClientRequest | null): void => {
+    const messageType = typeof message?.type === "string" ? message.type : null;
+    const itemType = readAgentStreamItemType(message);
+    const eventType = readAgentStreamEventType(message);
+    if (messageType)
+      serverMessageCounts.set(messageType, (serverMessageCounts.get(messageType) ?? 0) + 1);
+    if (itemType)
+      agentStreamItemCounts.set(itemType, (agentStreamItemCounts.get(itemType) ?? 0) + 1);
+    if (eventType)
+      agentStreamEventCounts.set(eventType, (agentStreamEventCounts.get(eventType) ?? 0) + 1);
+    if (!messageType && !itemType && !eventType) return;
+    for (const resolve of serverMessageWaiters) resolve();
+    serverMessageWaiters.clear();
+  };
+
+  const observeFileMessage = (message: ServerMessage | null): void => {
+    if (
+      message?.type === "fs.file.subscribe.response" &&
+      typeof message.payload?.initial?.path === "string"
+    ) {
+      const path = message.payload.initial.path;
+      subscribedFilePaths.add(path);
+      fileSubscriptionWaiters.get(path)?.();
+      fileSubscriptionWaiters.delete(path);
+    }
+    if (message) recordFileUpdate(message);
+  };
+
+  const holdServerMessage = (input: {
+    browser: WebSocketRoute;
+    message: string | Buffer;
+    parsed: ClientRequest | null;
+  }): boolean => {
+    const agentId = readAgentStreamAgentId(input.parsed);
+    const blocked = agentId
+      ? heldServerMessages.find((held) => held.blockedAgentId === agentId)
+      : undefined;
+    const suppressed = shouldSuppressServerMessage({
+      message: input.parsed,
+      messageTypes: suppressedServerMessageTypes,
+      agentStreamEventTypes: suppressedAgentStreamEventTypes,
+      agentStreamItemTypes: suppressedAgentStreamItemTypes,
+      suppressAgentStream,
+    });
+    if (blocked) {
+      if (!suppressed) blocked.agentStreamFollowers.push(input.message);
+      return true;
+    }
+    const matchedHold = Array.from(pendingServerMessageHolds).find(([, matches]) =>
+      matches(input.parsed),
+    );
+    if (!matchedHold) return suppressed;
+    const [key] = matchedHold;
+    pendingServerMessageHolds.delete(key);
+    heldServerMessages.push({
+      browser: input.browser,
+      message: input.message,
+      key,
+      agentStreamFollowers: [],
+      blockedAgentId:
+        readAgentStreamEventType(input.parsed) === "turn_started"
+          ? (agentId ?? undefined)
+          : undefined,
+    });
+    for (const resolve of heldServerMessageWaiters) resolve();
+    heldServerMessageWaiters.clear();
+    return true;
+  };
+
+  const holdReadyFileUpdate = (
+    browser: WebSocketRoute,
+    message: string | Buffer,
+    fileMessage: ServerMessage | null,
+  ): boolean => {
+    if (
+      fileMessage?.type !== "fs.file.update" ||
+      fileMessage.payload?.version?.status !== "ready" ||
+      fileMessage.payload.version.path !== readyFileUpdatePathToHold ||
+      heldReadyFileUpdate
+    ) {
+      return false;
+    }
+    heldReadyFileUpdate = () => browser.send(message);
+    resolveHeldReadyFileUpdate?.();
+    return true;
+  };
+
+  await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
+    if (!acceptingConnections) {
+      void ws.close({ code: 1008, reason: "Blocked by reconnect test." });
+      return;
+    }
+
+    activeSockets.add(ws);
+    const server = ws.connectToServer();
+    latestServer = server;
+
+    ws.onMessage((message) => {
+      if (!acceptingConnections) return;
+      if (reconnectWithFreshClient && typeof message === "string") {
+        const hello = readClientRequest(message);
+        if (hello?.type === "hello") {
+          const parsed = JSON.parse(message) as { clientId?: string };
+          parsed.clientId = `${parsed.clientId ?? "playwright"}-fresh-${Date.now()}`;
+          reconnectWithFreshClient = false;
+          server.send(JSON.stringify(parsed));
+          return;
+        }
+      }
+      const request = readClientRequest(message);
+      recordClientRequest(request, clientRequestCounts, timelineRequestCounts, directoryStarts);
+      if (request?.type === heldClientRequestType) {
+        heldClientRequest = { server, message };
+        resolveHeldClientRequest?.();
+        resolveHeldClientRequest = null;
+        return;
+      }
+      if (
+        request?.type === "file_explorer_request" &&
+        request.mode === "file" &&
+        request.path === fileReadPathToHold
+      ) {
+        heldFileReads.push(() => server.send(message));
+        resolveHeldFileRead?.();
+        return;
+      }
+      try {
+        server.send(message);
+      } catch {
+        activeSockets.delete(ws);
+      }
+    });
+
+    server.onMessage((message) => {
+      if (!acceptingConnections) return;
+      const serverMessage = readSessionMessage(message);
+      const fileMessage = serverMessage as ServerMessage | null;
+      observeFileMessage(fileMessage);
+      let outboundMessage = stripAssistantMessageId(
+        message,
+        stripAssistantMessageIds,
+        serverMessage?.type,
+      );
+      outboundMessage = stripCanonicalSubmittedPrompts(
+        outboundMessage,
+        stripCanonicalSubmittedPromptsFeature,
+        serverMessage?.type,
+      );
+      const shouldForceTimelineReset =
+        forceTimelineEpochReset && serverMessage?.type === "fetch_agent_timeline_response";
+      outboundMessage = forceTimelineReset(outboundMessage, shouldForceTimelineReset);
+      if (shouldForceTimelineReset) forceTimelineEpochReset = false;
+      recordServerMessage(serverMessage);
+      if (holdServerMessage({ browser: ws, message: outboundMessage, parsed: serverMessage }))
+        return;
+      if (holdReadyFileUpdate(ws, outboundMessage, fileMessage)) return;
+      try {
+        ws.send(outboundMessage);
+      } catch {
+        activeSockets.delete(ws);
+      }
+    });
+  });
+
+  return {
+    waitForFileSubscription(path: string): Promise<void> {
+      if (subscribedFilePaths.has(path)) return Promise.resolve();
+      return new Promise((resolve) => fileSubscriptionWaiters.set(path, resolve));
+    },
+    waitForFileUpdate(path: string, status: "ready" | "missing" | "error"): Promise<void> {
+      const key = `${path}:${status}`;
+      if (observedFileUpdates.has(key)) return Promise.resolve();
+      return new Promise((resolve) => fileUpdateWaiters.set(key, resolve));
+    },
+    holdFileReads(path: string): void {
+      fileReadPathToHold = path;
+      heldFileReads = [];
+      heldFileReadPromise = new Promise((resolve) => {
+        resolveHeldFileRead = resolve;
+      });
+    },
+    waitForHeldFileRead(): Promise<void> {
+      return heldFileReadPromise;
+    },
+    releaseHeldFileRead(): void {
+      const forwards = heldFileReads;
+      heldFileReads = [];
+      fileReadPathToHold = null;
+      resolveHeldFileRead = null;
+      for (const forward of forwards) forward();
+    },
+    holdNextReadyFileUpdate(path: string): void {
+      readyFileUpdatePathToHold = path;
+      heldReadyFileUpdate = null;
+      heldReadyFileUpdatePromise = new Promise((resolve) => {
+        resolveHeldReadyFileUpdate = resolve;
+      });
+    },
+    waitForHeldReadyFileUpdate(): Promise<void> {
+      return heldReadyFileUpdatePromise;
+    },
+    releaseHeldReadyFileUpdate(): void {
+      const forward = heldReadyFileUpdate;
+      heldReadyFileUpdate = null;
+      readyFileUpdatePathToHold = null;
+      resolveHeldReadyFileUpdate = null;
+      forward?.();
+    },
+    async drop(): Promise<void> {
+      acceptingConnections = false;
+      const sockets = Array.from(activeSockets);
+      activeSockets.clear();
+      await Promise.all(
+        sockets.map((ws) =>
+          ws.close({ code: 1008, reason: "Dropped by reconnect test." }).catch(() => undefined),
+        ),
+      );
+    },
+    restore(): void {
+      acceptingConnections = true;
+    },
+    restoreFresh(): void {
+      reconnectWithFreshClient = true;
+      acceptingConnections = true;
+    },
+    holdNextClientRequest(type: string): void {
+      heldClientRequestType = type;
+      heldClientRequest = null;
+    },
+    waitForHeldClientRequest(): Promise<void> {
+      if (heldClientRequest) return Promise.resolve();
+      return new Promise<void>((resolve) => {
+        resolveHeldClientRequest = resolve;
+      });
+    },
+    releaseHeldClientRequest(): void {
+      if (!heldClientRequest) throw new Error("No held client request to release");
+      heldClientRequest.server.send(heldClientRequest.message);
+      heldClientRequest = null;
+      heldClientRequestType = null;
+    },
+    holdNextServerMessage(type: string): void {
+      pendingServerMessageHolds.set(serverMessageKey(type), (message) => message?.type === type);
+    },
+    holdNextAgentUpdate(agentId: string, status: string): void {
+      const heldAgentUpdate = { agentId, status };
+      pendingServerMessageHolds.set(agentUpdateKey(agentId, status), (message) =>
+        matchesAgentUpdate(message, heldAgentUpdate),
+      );
+    },
+    holdNextAgentStreamEvent(type: string): void {
+      pendingServerMessageHolds.set(
+        agentStreamEventKey(type),
+        (message) => readAgentStreamEventType(message) === type,
+      );
+    },
+    async waitForHeldServerMessage(type?: string): Promise<void> {
+      const key = type ? serverMessageKey(type) : null;
+      while (!heldServerMessages.some((message) => key === null || message.key === key)) {
+        await new Promise<void>((resolve) => heldServerMessageWaiters.add(resolve));
+      }
+    },
+    releaseHeldServerMessage(type?: string): void {
+      const key = type ? serverMessageKey(type) : null;
+      const index = heldServerMessages.findIndex((message) => key === null || message.key === key);
+      const [heldServerMessage] = index >= 0 ? heldServerMessages.splice(index, 1) : [];
+      if (!heldServerMessage) throw new Error("No held server message to release");
+      heldServerMessage.browser.send(heldServerMessage.message);
+      for (const follower of heldServerMessage.agentStreamFollowers) {
+        heldServerMessage.browser.send(follower);
+      }
+    },
+    async waitForHeldAgentUpdate(agentId: string, status: string): Promise<void> {
+      const key = agentUpdateKey(agentId, status);
+      while (!heldServerMessages.some((message) => message.key === key)) {
+        await new Promise<void>((resolve) => heldServerMessageWaiters.add(resolve));
+      }
+    },
+    releaseHeldAgentUpdate(agentId: string, status: string): void {
+      const key = agentUpdateKey(agentId, status);
+      const index = heldServerMessages.findIndex((message) => message.key === key);
+      const [heldServerMessage] = index >= 0 ? heldServerMessages.splice(index, 1) : [];
+      if (!heldServerMessage) throw new Error("No held agent update to release");
+      heldServerMessage.browser.send(heldServerMessage.message);
+      for (const follower of heldServerMessage.agentStreamFollowers) {
+        heldServerMessage.browser.send(follower);
+      }
+    },
+    async waitForHeldAgentStreamEvent(type: string): Promise<void> {
+      const key = agentStreamEventKey(type);
+      while (!heldServerMessages.some((message) => message.key === key)) {
+        await new Promise<void>((resolve) => heldServerMessageWaiters.add(resolve));
+      }
+    },
+    releaseHeldAgentStreamEvent(type: string): void {
+      const key = agentStreamEventKey(type);
+      const index = heldServerMessages.findIndex((message) => message.key === key);
+      const [heldServerMessage] = index >= 0 ? heldServerMessages.splice(index, 1) : [];
+      if (!heldServerMessage) throw new Error("No held agent stream event to release");
+      heldServerMessage.browser.send(heldServerMessage.message);
+      for (const follower of heldServerMessage.agentStreamFollowers) {
+        heldServerMessage.browser.send(follower);
+      }
+    },
+    requestTimelineTail(agentId: string): void {
+      if (!latestServer) throw new Error("No daemon WebSocket is connected");
+      latestServer.send(
+        JSON.stringify({
+          type: "session",
+          message: {
+            type: "fetch_agent_timeline_request",
+            agentId,
+            requestId: `playwright-timeline-${Date.now()}`,
+            direction: "tail",
+            limit: 0,
+            projection: "projected",
+          },
+        }),
+      );
+    },
+    getHeldTimelineLastItemType(): string | null {
+      const heldServerMessage = heldServerMessages[0];
+      if (!heldServerMessage) throw new Error("No held server message to inspect");
+      const response = readSessionMessage(heldServerMessage.message);
+      const payload = response?.payload;
+      if (!payload || typeof payload !== "object") return null;
+      const entries = (payload as { entries?: unknown }).entries;
+      if (!Array.isArray(entries)) return null;
+      const last = entries.at(-1) as { item?: { type?: unknown } } | undefined;
+      return typeof last?.item?.type === "string" ? last.item.type : null;
+    },
+    truncateHeldTimelineAfterLast(itemType: string): void {
+      const heldServerMessage = heldServerMessages[0];
+      if (!heldServerMessage || typeof heldServerMessage.message !== "string") {
+        throw new Error("No held text server message to truncate");
+      }
+      const envelope = JSON.parse(heldServerMessage.message) as {
+        message?: { payload?: Record<string, unknown> };
+        payload?: Record<string, unknown>;
+      };
+      const payload = envelope.message?.payload ?? envelope.payload;
+      if (!payload) throw new Error("Held message has no payload");
+      const entries = payload.entries;
+      if (!Array.isArray(entries)) throw new Error("Held message is not a timeline response");
+      const index = entries.findLastIndex(
+        (entry) =>
+          typeof entry === "object" &&
+          entry !== null &&
+          (entry as { item?: { type?: unknown } }).item?.type === itemType,
+      );
+      if (index < 0) throw new Error(`Timeline response has no ${itemType} item`);
+      const retained = entries.slice(0, index + 1) as Array<{ seqEnd?: unknown }>;
+      const lastSeq = retained.at(-1)?.seqEnd;
+      if (typeof lastSeq !== "number") throw new Error("Timeline entry has no sequence end");
+      payload.entries = retained;
+      payload.endCursor = { epoch: payload.epoch, seq: lastSeq };
+      payload.hasNewer = false;
+      if (payload.window && typeof payload.window === "object") {
+        (payload.window as Record<string, unknown>).maxSeq = lastSeq;
+        (payload.window as Record<string, unknown>).nextSeq = lastSeq + 1;
+      }
+      heldServerMessage.message = JSON.stringify(envelope);
+    },
+    setServerMessageSuppressed(type: string, suppressed: boolean): void {
+      if (suppressed) {
+        suppressedServerMessageTypes.add(type);
+      } else {
+        suppressedServerMessageTypes.delete(type);
+      }
+    },
+    setAgentStreamEventSuppressed(type: string, suppressed: boolean): void {
+      if (suppressed) {
+        suppressedAgentStreamEventTypes.add(type);
+      } else {
+        suppressedAgentStreamEventTypes.delete(type);
+      }
+    },
+    setAgentStreamItemSuppressed(type: string, suppressed: boolean): void {
+      if (suppressed) {
+        suppressedAgentStreamItemTypes.add(type);
+      } else {
+        suppressedAgentStreamItemTypes.delete(type);
+      }
+    },
+    setAssistantMessageIdsStripped(stripped: boolean): void {
+      stripAssistantMessageIds = stripped;
+    },
+    setCanonicalSubmittedPromptsStripped(stripped: boolean): void {
+      stripCanonicalSubmittedPromptsFeature = stripped;
+    },
+    setAgentStreamSuppressed(suppressed: boolean): void {
+      suppressAgentStream = suppressed;
+    },
+    forceNextTimelineEpochReset(): void {
+      forceTimelineEpochReset = true;
+    },
+    getDirectoryRequestStartCounts(): DirectoryRequestStartCounts {
+      return {
+        subscribed: { ...directoryStarts.subscribed },
+        unsubscribed: { ...directoryStarts.unsubscribed },
+        total: { ...directoryStarts.total },
+      };
+    },
+    getClientRequestCount(type: string): number {
+      return clientRequestCounts.get(type) ?? 0;
+    },
+    getTimelineRequestCount(direction: "tail" | "before" | "after"): number {
+      return timelineRequestCounts.get(direction) ?? 0;
+    },
+    getAgentStreamItemCount(type: string): number {
+      return agentStreamItemCounts.get(type) ?? 0;
+    },
+    async waitForServerMessage(type: string, count = 1): Promise<void> {
+      while ((serverMessageCounts.get(type) ?? 0) < count) {
+        await new Promise<void>((resolve) => serverMessageWaiters.add(resolve));
+      }
+    },
+    async waitForAgentStreamItem(type: string, count = 1): Promise<void> {
+      while ((agentStreamItemCounts.get(type) ?? 0) < count) {
+        await new Promise<void>((resolve) => serverMessageWaiters.add(resolve));
+      }
+    },
+    async waitForAgentStreamEvent(type: string, count = 1): Promise<void> {
+      while ((agentStreamEventCounts.get(type) ?? 0) < count) {
+        await new Promise<void>((resolve) => serverMessageWaiters.add(resolve));
+      }
+    },
+  };
+}

packages/app/e2e/support/helpers/directory-bootstrap-scenario.ts

@@ -0,0 +1,155 @@
+import { expect, type Page } from "@playwright/test";
+import { buildHostAgentDetailRoute } from "@/utils/host-routes";
+import { installDaemonWebSocketGate } from "./daemon-websocket-gate";
+import { seedWorkspace, type SeededWorkspace } from "./seed-client";
+import { getServerId } from "./server-id";
+import { waitForWorkspaceTabsVisible } from "./workspace-tabs";
+import { expectReconnectingToastGone, expectReconnectingToastVisible } from "./workspace-ui";
+
+interface SeededDirectoryAgent {
+  id: string;
+  title: string;
+}
+
+async function createRunningMockAgent(
+  workspace: SeededWorkspace,
+  title: string,
+): Promise<SeededDirectoryAgent> {
+  const agent = await workspace.client.createAgent({
+    provider: "mock",
+    cwd: workspace.repoPath,
+    workspaceId: workspace.workspaceId,
+    title,
+    modeId: "load-test",
+    model: "five-minute-stream",
+    initialPrompt: `Keep ${title} running for directory synchronization.`,
+  });
+  const running = await workspace.client.waitForAgentUpsert(
+    agent.id,
+    (snapshot) => snapshot.status === "running",
+    30_000,
+  );
+  expect(running.status).toBe("running");
+  return { id: agent.id, title };
+}
+
+async function openCommandCenter(page: Page): Promise<void> {
+  await page.getByRole("button", { name: "Open command center" }).click();
+}
+
+export class DirectoryBootstrapScenario {
+  private readonly workspaces: SeededWorkspace[] = [];
+  private disconnectedWorkspace: SeededWorkspace | null = null;
+  private disconnectedAgent: SeededDirectoryAgent | null = null;
+
+  private constructor(
+    private readonly page: Page,
+    private readonly gate: Awaited<ReturnType<typeof installDaemonWebSocketGate>>,
+  ) {}
+
+  static async open(page: Page): Promise<DirectoryBootstrapScenario> {
+    const gate = await installDaemonWebSocketGate(page);
+    const scenario = new DirectoryBootstrapScenario(page, gate);
+    const workspace = await scenario.seedWorkspace("directory-bootstrap-initial-");
+    const agent = await createRunningMockAgent(workspace, "Initial directory agent");
+    await page.goto(buildHostAgentDetailRoute(getServerId(), agent.id, workspace.workspaceId));
+    await page.waitForURL(
+      (url) => url.pathname.includes("/workspace/") && !url.searchParams.has("open"),
+    );
+    await waitForWorkspaceTabsVisible(page);
+    await expect(page.getByRole("button", { name: agent.title, exact: true })).toBeVisible();
+    return scenario;
+  }
+
+  async expectDirectoryStarts(expectedPerDirectory: number): Promise<void> {
+    await expect
+      .poll(() => this.gate.getDirectoryRequestStartCounts())
+      .toEqual({
+        subscribed: { agents: expectedPerDirectory, workspaces: expectedPerDirectory },
+        unsubscribed: { agents: 0, workspaces: 0 },
+        total: { agents: expectedPerDirectory, workspaces: expectedPerDirectory },
+      });
+  }
+
+  async stayConnectedWithoutRefetchAndApplyDeltas(): Promise<void> {
+    const workspace = await this.seedWorkspace("directory-bootstrap-background-");
+    const agent = await createRunningMockAgent(workspace, "Background directory agent");
+
+    const workspaceLink = this.page.getByText(workspace.projectDisplayName, { exact: true });
+    await expect(workspaceLink).toHaveCount(1);
+    await expect(workspaceLink).toBeVisible();
+    await openCommandCenter(this.page);
+    const agentLink = this.page.getByText(agent.title, { exact: true });
+    await expect(agentLink).toHaveCount(1);
+    await expect(agentLink).toBeVisible();
+    await this.page.keyboard.press("Escape");
+    await this.expectDirectoryStarts(1);
+  }
+
+  async disconnectMutateAndReconnect(): Promise<void> {
+    await this.gate.drop();
+    await expectReconnectingToastVisible(this.page);
+
+    this.disconnectedWorkspace = await this.seedWorkspace("directory-bootstrap-reconnect-");
+    this.disconnectedAgent = await createRunningMockAgent(
+      this.disconnectedWorkspace,
+      "Reconnected directory agent",
+    );
+    await expect(
+      this.page.getByText(this.disconnectedWorkspace.projectDisplayName, { exact: true }),
+    ).toHaveCount(0);
+    await expect(this.page.getByText(this.disconnectedAgent.title, { exact: true })).toHaveCount(0);
+
+    this.gate.restore();
+    await expectReconnectingToastGone(this.page);
+    await this.expectDirectoryStarts(2);
+  }
+
+  async expectVisibleReconciliationAndNavigateAgent(): Promise<void> {
+    const workspace = this.requireDisconnectedWorkspace();
+    const agent = this.requireDisconnectedAgent();
+    const workspaceLink = this.page.getByText(workspace.projectDisplayName, { exact: true });
+    await expect(workspaceLink).toHaveCount(1);
+    await expect(workspaceLink).toBeVisible();
+    await openCommandCenter(this.page);
+    const agentLink = this.page.getByText(agent.title, { exact: true });
+    await expect(agentLink).toHaveCount(1);
+    await expect(agentLink).toBeVisible();
+    await agentLink.click();
+    await expect(this.page).toHaveURL(
+      new RegExp(
+        `/workspace/${workspace.workspaceId}/agent/${agent.id}|/workspace/${workspace.workspaceId}`,
+      ),
+    );
+    await expect(this.page.getByRole("button", { name: agent.title, exact: true })).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+    const pings = this.gate.getClientRequestCount("ping");
+    await expect
+      .poll(() => this.gate.getClientRequestCount("ping"), { timeout: 30_000 })
+      .toBeGreaterThan(pings);
+    await this.expectDirectoryStarts(2);
+  }
+
+  async cleanup(): Promise<void> {
+    this.gate.restore();
+    await Promise.all(this.workspaces.map((workspace) => workspace.cleanup()));
+  }
+
+  private async seedWorkspace(prefix: string): Promise<SeededWorkspace> {
+    const workspace = await seedWorkspace({ repoPrefix: prefix });
+    this.workspaces.push(workspace);
+    return workspace;
+  }
+
+  private requireDisconnectedWorkspace(): SeededWorkspace {
+    if (!this.disconnectedWorkspace) throw new Error("Reconnect workspace was not seeded.");
+    return this.disconnectedWorkspace;
+  }
+
+  private requireDisconnectedAgent(): SeededDirectoryAgent {
+    if (!this.disconnectedAgent) throw new Error("Reconnect agent was not seeded.");
+    return this.disconnectedAgent;
+  }
+}

packages/app/e2e/support/helpers/e2e-worker.ts

@@ -0,0 +1,166 @@
+import { execSync } from "node:child_process";
+import { chmod, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { forkPaseoHomeMetadata, resolvePaseoHomePath } from "./paseo-home-fork";
+import { startIsolatedHostDaemon } from "./isolated-host-daemon";
+
+export interface E2EWorker {
+  close(): Promise<void>;
+}
+
+function resolveOptionalHome(value: string | undefined): string | null {
+  const trimmed = value?.trim();
+  if (!trimmed) return null;
+  return resolvePaseoHomePath(trimmed === "current" ? "~/.paseo" : trimmed);
+}
+
+async function createFakeEditorBin(): Promise<string> {
+  const binDir = await mkdtemp(path.join(tmpdir(), "paseo-e2e-editor-bin-"));
+  let realGhPath = "";
+  try {
+    realGhPath = execSync("which gh").toString().trim();
+  } catch {
+    // The local GitHub fixture remains usable without a system gh binary.
+  }
+
+  const fakeEditorSource = `#!/usr/bin/env node
+const fs = require("fs");
+const path = require("path");
+const recordPath = process.env.PASEO_E2E_EDITOR_RECORD_PATH;
+if (recordPath) {
+  fs.appendFileSync(recordPath, JSON.stringify({
+    command: path.basename(process.argv[1]),
+    args: process.argv.slice(2),
+    cwd: process.cwd(),
+    at: Date.now()
+  }) + "\\n");
+}
+`;
+  for (const editorCommand of ["cursor", "code"]) {
+    const editorPath = path.join(binDir, editorCommand);
+    await writeFile(editorPath, fakeEditorSource);
+    await chmod(editorPath, 0o755);
+  }
+
+  const fakeGhPath = path.join(binDir, "gh");
+  const fakeGhSource = `#!/usr/bin/env node
+const { spawnSync } = require("child_process");
+const args = process.argv.slice(2);
+const fixtureRemote = "https://github.com/paseo-e2e/local-fixture.git";
+const origin = spawnSync("git", ["config", "--get", "remote.origin.url"], {
+  encoding: "utf8",
+  stdio: ["ignore", "pipe", "ignore"]
+}).stdout?.trim();
+
+if (origin === fixtureRemote) {
+  const command = args.slice(0, 2).join(" ");
+  if (command === "auth status") process.exit(0);
+  if (command === "repo view") {
+    process.stdout.write(JSON.stringify({ owner: { login: "paseo-e2e" }, name: "local-fixture", parent: null }));
+    process.exit(0);
+  }
+  if (command === "issue list") {
+    process.stdout.write("[]");
+    process.exit(0);
+  }
+  if (command === "pr list" || command === "pr view") {
+    const pr = {
+      number: 1,
+      title: "Use pasted PR as start ref",
+      url: "https://github.com/paseo-e2e/local-fixture/pull/1",
+      state: "OPEN",
+      body: null,
+      labels: [],
+      baseRefName: "main",
+      headRefName: "pr-branch-1",
+      updatedAt: "2026-01-01T00:00:00Z"
+    };
+    process.stdout.write(JSON.stringify(command === "pr list" ? [pr] : pr));
+    process.exit(0);
+  }
+  if (command === "api graphql" && args.some((arg) => arg.includes("PullRequestCheckoutTarget"))) {
+    process.stdout.write(JSON.stringify({
+      data: { repository: { pullRequest: {
+        number: 1,
+        baseRefName: "main",
+        headRefName: "pr-branch-1",
+        isCrossRepository: false,
+        headRepositoryOwner: { login: "paseo-e2e" },
+        headRepository: {
+          sshUrl: "git@github.com:paseo-e2e/local-fixture.git",
+          url: fixtureRemote
+        }
+      } } }
+    }));
+    process.exit(0);
+  }
+  process.stderr.write("Unsupported local GitHub fixture command: " + args.join(" ") + "\\n");
+  process.exit(1);
+}
+
+const realGhPath = ${JSON.stringify(realGhPath)};
+if (!realGhPath) process.exit(127);
+const result = spawnSync(realGhPath, args, { stdio: "inherit" });
+process.exit(result.status ?? 1);
+`;
+  await writeFile(fakeGhPath, fakeGhSource);
+  await chmod(fakeGhPath, 0o755);
+  return binDir;
+}
+
+async function applyMetadataFork(targetHome: string): Promise<void> {
+  const sourceHome = resolveOptionalHome(process.env.E2E_FORK_PASEO_HOME_FROM);
+  if (!sourceHome) return;
+  const result = await forkPaseoHomeMetadata({ sourceHome, targetHome });
+  process.env.E2E_FORK_SOURCE_PASEO_HOME = result.sourceHome;
+  process.env.E2E_FORK_TARGET_PASEO_HOME = result.targetHome;
+  process.env.E2E_FORK_COPIED_FILES = String(result.copiedFiles);
+  process.env.E2E_FORK_COPIED_BYTES = String(result.copiedBytes);
+}
+
+export async function startE2EWorker(workerIndex: number): Promise<E2EWorker> {
+  const requestedRoot = resolveOptionalHome(process.env.E2E_PASEO_HOME);
+  const paseoHome = requestedRoot
+    ? path.join(requestedRoot, `worker-${workerIndex}`)
+    : await mkdtemp(path.join(tmpdir(), `paseo-e2e-worker-${workerIndex}-`));
+  const preserveHome = Boolean(requestedRoot) || process.env.E2E_KEEP_PASEO_HOME === "1";
+  const fakeEditorBin = await createFakeEditorBin();
+  const editorRecordPath = path.join(paseoHome, "editor-open-records.jsonl");
+  const serverId = `srv_e2e_worker_${workerIndex}`;
+
+  try {
+    await applyMetadataFork(paseoHome);
+    const daemon = await startIsolatedHostDaemon(serverId, {
+      paseoHome,
+      preserveHome,
+      environment: {
+        NODE_ENV: "development",
+        PATH: `${fakeEditorBin}${path.delimiter}${process.env.PATH ?? ""}`,
+        PASEO_E2E_EDITOR_RECORD_PATH: editorRecordPath,
+      },
+    });
+
+    process.env.E2E_DAEMON_PORT = String(daemon.port);
+    process.env.E2E_SERVER_ID = daemon.serverId;
+    process.env.E2E_PASEO_HOME = daemon.paseoHome;
+    process.env.E2E_EDITOR_RECORD_PATH = editorRecordPath;
+    delete process.env.E2E_RELAY_PORT;
+    delete process.env.E2E_RELAY_DAEMON_PUBLIC_KEY;
+
+    console.log(
+      `[e2e] Worker ${workerIndex} daemon started on port ${daemon.port}, home: ${daemon.paseoHome}`,
+    );
+    return {
+      close: async () => {
+        await daemon.close();
+        await rm(fakeEditorBin, { recursive: true, force: true });
+        console.log(`[e2e] Worker ${workerIndex} daemon stopped`);
+      },
+    };
+  } catch (error) {
+    await rm(fakeEditorBin, { recursive: true, force: true });
+    if (!preserveHome) await rm(paseoHome, { recursive: true, force: true });
+    throw error;
+  }
+}

packages/app/e2e/support/helpers/file-callouts.ts

@@ -0,0 +1,48 @@
+import type { Page } from "@playwright/test";
+import { expect } from "../fixtures";
+
+export async function recordFileCallouts(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    const callouts: string[] = [];
+    const recordAlert = (alert: Element) => {
+      const text = alert.textContent?.trim();
+      if (text && !callouts.includes(text)) callouts.push(text);
+    };
+    const record = (records: MutationRecord[]) => {
+      for (const mutation of records) {
+        if (
+          !(mutation.target instanceof Element) ||
+          !mutation.target.closest('[data-testid="workspace-file-pane"]')
+        ) {
+          continue;
+        }
+        for (const node of mutation.addedNodes) {
+          if (!(node instanceof Element)) continue;
+          if (node.matches('[role="alert"]')) recordAlert(node);
+          for (const alert of node.querySelectorAll('[role="alert"]')) recordAlert(alert);
+        }
+      }
+    };
+    const observer = new MutationObserver(record);
+    observer.observe(document.body, { childList: true, subtree: true, characterData: true });
+    Object.assign(globalThis, { __PASEO_RECORDED_FILE_CALLOUTS__: callouts });
+  });
+}
+
+export async function expectFileCalloutWasRendered(page: Page, title: string): Promise<void> {
+  await expect
+    .poll(() => recordedFileCallouts(page))
+    .toEqual(expect.arrayContaining([expect.stringContaining(title)]));
+}
+
+export async function expectNoFileCalloutWasRendered(page: Page): Promise<void> {
+  await expect.poll(() => recordedFileCallouts(page)).toEqual([]);
+}
+
+function recordedFileCallouts(page: Page): Promise<string[]> {
+  return page.evaluate(
+    () =>
+      (globalThis as typeof globalThis & { __PASEO_RECORDED_FILE_CALLOUTS__?: string[] })
+        .__PASEO_RECORDED_FILE_CALLOUTS__ ?? [],
+  );
+}

packages/app/e2e/support/helpers/file-explorer.ts

@@ -0,0 +1,41 @@
+import { expect, type Page } from "@playwright/test";
+
+function fileExplorerTree(page: Page) {
+  return page.getByTestId("file-explorer-tree-scroll");
+}
+
+function fileExplorerEntry(page: Page, name: string) {
+  return fileExplorerTree(page).getByText(name, { exact: true }).first();
+}
+
+export async function openFileExplorer(page: Page): Promise<void> {
+  await page.getByRole("button", { name: "Open explorer" }).first().click();
+  await page.getByTestId("explorer-tab-files").click();
+  await expect(fileExplorerTree(page)).toBeVisible({ timeout: 30_000 });
+}
+
+export async function expandFolder(page: Page, folderName: string): Promise<void> {
+  await fileExplorerEntry(page, folderName).click();
+}
+
+export async function collapseFolder(page: Page, folderName: string): Promise<void> {
+  await fileExplorerEntry(page, folderName).click();
+}
+
+export async function openFileFromExplorer(page: Page, fileName: string): Promise<void> {
+  await fileExplorerEntry(page, fileName).click();
+}
+
+export async function expectExplorerEntryVisible(page: Page, name: string): Promise<void> {
+  await expect(fileExplorerEntry(page, name)).toBeVisible({ timeout: 30_000 });
+}
+
+export async function expectExplorerEntryHidden(page: Page, name: string): Promise<void> {
+  await expect(fileExplorerEntry(page, name)).toBeHidden({ timeout: 30_000 });
+}
+
+export async function expectFileTabOpen(page: Page, filePath: string): Promise<void> {
+  await expect(page.getByTestId(`workspace-tab-file_${filePath}`).first()).toBeVisible({
+    timeout: 30_000,
+  });
+}

packages/app/e2e/support/helpers/github-fixtures.ts

@@ -0,0 +1,343 @@
+import { execFileSync, execSync } from "node:child_process";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+export function hasGithubAuth(): boolean {
+  try {
+    execSync("gh auth status", { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export interface CheckSpec {
+  context: string;
+  state: "success" | "failure" | "pending";
+}
+
+export interface PrSpec {
+  title: string;
+  state: "open" | "merged" | "closed" | "draft";
+  checks?: CheckSpec[];
+  commentCount?: number;
+}
+
+export interface IssueSpec {
+  title: string;
+  body?: string;
+  labels?: string[];
+  state?: "open" | "closed";
+}
+
+export interface GhPrFixture {
+  number: number;
+  title: string;
+  url: string;
+  branch: string;
+  localPath: string;
+}
+
+export interface GhIssueFixture {
+  number: number;
+  title: string;
+  url: string;
+}
+
+export interface GhRepoFixture {
+  owner: string;
+  name: string;
+  fullName: string;
+  defaultBranch: string;
+  prs: GhPrFixture[];
+  issues: GhIssueFixture[];
+  cleanup(): Promise<void>;
+}
+
+export interface GhDefaultBranchClone {
+  path: string;
+  cleanup(): Promise<void>;
+}
+
+export interface LocalGhPrFixture {
+  pr: GhPrFixture;
+  mainCheckout: GhDefaultBranchClone;
+  cleanup(): Promise<void>;
+}
+
+function gh(args: string[], opts?: { cwd?: string }): string {
+  return execFileSync("gh", args, {
+    cwd: opts?.cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  }).trim();
+}
+
+function git(args: string[], cwd: string): string {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  }).trim();
+}
+
+async function seedPr(args: {
+  spec: PrSpec;
+  branch: string;
+  index: number;
+  basePath: string;
+  authedUrl: string;
+  fullName: string;
+  repoName: string;
+  defaultBranch: string;
+}): Promise<{ fixture: GhPrFixture; localPath: string }> {
+  const { spec, branch, index, basePath, authedUrl, fullName, repoName, defaultBranch } = args;
+
+  const createArgs = [
+    "pr",
+    "create",
+    "--title",
+    spec.title,
+    "--base",
+    defaultBranch,
+    "--head",
+    branch,
+    "--body",
+    "",
+  ];
+  if (spec.state === "draft") createArgs.push("--draft");
+
+  const prUrl = gh(createArgs, { cwd: basePath });
+  const prNumber = parseInt(prUrl.split("/").pop() ?? "0", 10);
+
+  if (spec.checks && spec.checks.length > 0) {
+    const sha = git(["rev-parse", branch], basePath);
+    for (const check of spec.checks) {
+      gh([
+        "api",
+        `repos/${fullName}/statuses/${sha}`,
+        "--method",
+        "POST",
+        "-f",
+        `state=${check.state}`,
+        "-f",
+        `context=${check.context}`,
+        "-f",
+        `target_url=https://example.com/${encodeURIComponent(check.context)}`,
+      ]);
+    }
+  }
+
+  for (let j = 0; j < (spec.commentCount ?? 0); j++) {
+    gh(["pr", "comment", String(prNumber), "--body", `Test comment ${j + 1}`], { cwd: basePath });
+  }
+
+  if (spec.state === "merged") {
+    gh(["pr", "merge", String(prNumber), "--merge"], { cwd: basePath });
+  } else if (spec.state === "closed") {
+    gh(["pr", "close", String(prNumber)], { cwd: basePath });
+  }
+
+  const localPath = await mkdtemp(path.join("/tmp", `${repoName}-ws-${index}-`));
+  git(["clone", authedUrl, localPath, "--quiet", "-b", branch], basePath);
+  // Clean remote URL (no embedded token) so gh can parse owner/repo
+  git(["remote", "set-url", "origin", `https://github.com/${fullName}.git`], localPath);
+  git(["config", "user.email", "e2e@paseo.test"], localPath);
+  git(["config", "user.name", "Paseo E2E"], localPath);
+  git(["config", "commit.gpgsign", "false"], localPath);
+
+  return {
+    fixture: { number: prNumber, title: spec.title, url: prUrl, branch, localPath },
+    localPath,
+  };
+}
+
+function seedIssue(args: { spec: IssueSpec; basePath: string }): GhIssueFixture {
+  const { spec, basePath } = args;
+  const createArgs = ["issue", "create", "--title", spec.title, "--body", spec.body ?? ""];
+  for (const label of spec.labels ?? []) {
+    createArgs.push("--label", label);
+  }
+  const issueUrl = gh(createArgs, { cwd: basePath });
+  const issueNumber = parseInt(issueUrl.split("/").pop() ?? "0", 10);
+  if (spec.state === "closed") {
+    gh(["issue", "close", String(issueNumber)], { cwd: basePath });
+  }
+  return { number: issueNumber, title: spec.title, url: issueUrl };
+}
+
+// Single namespace for temporary GitHub repos created by Paseo tests.
+// Bulk cleanup relies on this prefix being unmistakable — never reuse `paseo-`
+// (collides with real repos like `paseo`, `paseo-website`).
+const TEMP_GITHUB_REPO_PREFIX = "paseotmp-";
+
+export async function createTempGithubRepo(options: {
+  category: string;
+  prs?: PrSpec[];
+  issues?: IssueSpec[];
+}): Promise<GhRepoFixture> {
+  const { category, prs = [], issues = [] } = options;
+  const uniqueSuffix = `${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+  const repoName = `${TEMP_GITHUB_REPO_PREFIX}${category}-${uniqueSuffix}`;
+  const defaultBranch = "main";
+
+  // Bootstrap local git repo
+  const basePath = await mkdtemp(path.join("/tmp", `${repoName}-base-`));
+  git(["init", "-b", defaultBranch], basePath);
+  git(["config", "user.email", "e2e@paseo.test"], basePath);
+  git(["config", "user.name", "Paseo E2E"], basePath);
+  git(["config", "commit.gpgsign", "false"], basePath);
+  await writeFile(path.join(basePath, "README.md"), "# E2E Test Repo\n");
+  git(["add", "README.md"], basePath);
+  git(["commit", "-m", "Initial commit"], basePath);
+
+  // Create GitHub repo and push initial commit
+  gh(["repo", "create", repoName, "--private", `--source=${basePath}`, "--push"]);
+
+  const owner = gh(["api", "user", "--jq", ".login"]);
+  const fullName = `${owner}/${repoName}`;
+  const token = gh(["auth", "token"]);
+  const authedUrl = `https://x-access-token:${token}@github.com/${fullName}.git`;
+
+  // Switch remote to authed URL for subsequent pushes
+  git(["remote", "set-url", "origin", authedUrl], basePath);
+
+  // Create a branch + commit for each PR spec
+  const branches: string[] = [];
+  for (let i = 0; i < prs.length; i++) {
+    const branch = `pr-branch-${i + 1}`;
+    branches.push(branch);
+    git(["checkout", "-b", branch], basePath);
+    await writeFile(path.join(basePath, `pr-${i + 1}.txt`), `PR ${i + 1}\n`);
+    git(["add", `pr-${i + 1}.txt`], basePath);
+    git(["commit", "-m", `Add PR ${i + 1}`], basePath);
+    git(["checkout", defaultBranch], basePath);
+  }
+
+  if (branches.length > 0) {
+    git(["push", "origin", ...branches], basePath);
+  }
+
+  // Create PRs, seed checks/comments, apply state changes, clone workspaces
+  const prFixtures: GhPrFixture[] = [];
+  const localPaths: string[] = [];
+
+  for (let i = 0; i < prs.length; i++) {
+    const { fixture, localPath } = await seedPr({
+      spec: prs[i],
+      branch: branches[i],
+      index: i,
+      basePath,
+      authedUrl,
+      fullName,
+      repoName,
+      defaultBranch,
+    });
+    localPaths.push(localPath);
+    prFixtures.push(fixture);
+  }
+
+  // Create issues
+  const issueFixtures: GhIssueFixture[] = [];
+  for (const spec of issues) {
+    issueFixtures.push(seedIssue({ spec, basePath }));
+  }
+
+  return {
+    owner,
+    name: repoName,
+    fullName,
+    defaultBranch,
+    prs: prFixtures,
+    issues: issueFixtures,
+    cleanup: async () => {
+      try {
+        gh(["repo", "delete", fullName, "--yes"]);
+      } catch {
+        // Best-effort cleanup
+      }
+      await Promise.all([
+        rm(basePath, { recursive: true, force: true }),
+        ...localPaths.map((p) => rm(p, { recursive: true, force: true })),
+      ]);
+    },
+  };
+}
+
+export async function cloneGithubRepoDefaultBranchOnly(
+  repo: Pick<GhRepoFixture, "fullName" | "name" | "defaultBranch">,
+): Promise<GhDefaultBranchClone> {
+  const token = gh(["auth", "token"]);
+  const authedUrl = `https://x-access-token:${token}@github.com/${repo.fullName}.git`;
+  const clonePath = await mkdtemp(path.join("/tmp", `${repo.name}-${repo.defaultBranch}-only-`));
+
+  execFileSync(
+    "git",
+    ["clone", "--quiet", "--single-branch", "--branch", repo.defaultBranch, authedUrl, clonePath],
+    { stdio: ["ignore", "pipe", "pipe"] },
+  );
+  git(["config", "user.email", "e2e@paseo.test"], clonePath);
+  git(["config", "user.name", "Paseo E2E"], clonePath);
+  git(["config", "commit.gpgsign", "false"], clonePath);
+
+  return {
+    path: clonePath,
+    cleanup: async () => {
+      await rm(clonePath, { recursive: true, force: true });
+    },
+  };
+}
+
+export async function createLocalGithubPrFixture(): Promise<LocalGhPrFixture> {
+  const fixtureRoot = await mkdtemp(path.join("/tmp", "paseo-e2e-local-github-pr-"));
+  const basePath = path.join(fixtureRoot, "base");
+  const remotePath = path.join(fixtureRoot, "remote.git");
+  const checkoutPath = path.join(fixtureRoot, "main-only");
+  const githubUrl = "https://github.com/paseo-e2e/local-fixture.git";
+  await mkdir(basePath);
+
+  git(["init", "-b", "main"], basePath);
+  git(["config", "user.email", "e2e@paseo.test"], basePath);
+  git(["config", "user.name", "Paseo E2E"], basePath);
+  git(["config", "commit.gpgsign", "false"], basePath);
+  await writeFile(path.join(basePath, "README.md"), "# Local GitHub fixture\n");
+  git(["add", "README.md"], basePath);
+  git(["commit", "-m", "Initial commit"], basePath);
+  git(["checkout", "-b", "pr-branch-1"], basePath);
+  await writeFile(path.join(basePath, "pr-1.txt"), "PR 1\n");
+  git(["add", "pr-1.txt"], basePath);
+  git(["commit", "-m", "Add PR 1"], basePath);
+  git(["checkout", "main"], basePath);
+
+  execFileSync("git", ["clone", "--quiet", "--bare", basePath, remotePath], {
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  git(["update-ref", "refs/pull/1/head", "refs/heads/pr-branch-1"], remotePath);
+  execFileSync(
+    "git",
+    ["clone", "--quiet", "--single-branch", "--branch", "main", remotePath, checkoutPath],
+    { stdio: ["ignore", "pipe", "pipe"] },
+  );
+  git(["remote", "set-url", "origin", githubUrl], checkoutPath);
+  git(["config", `url.${remotePath}.insteadOf`, githubUrl], checkoutPath);
+  git(["config", "user.email", "e2e@paseo.test"], checkoutPath);
+  git(["config", "user.name", "Paseo E2E"], checkoutPath);
+  git(["config", "commit.gpgsign", "false"], checkoutPath);
+
+  return {
+    pr: {
+      number: 1,
+      title: "Use pasted PR as start ref",
+      url: "https://github.com/paseo-e2e/local-fixture/pull/1",
+      branch: "pr-branch-1",
+      localPath: basePath,
+    },
+    mainCheckout: {
+      path: checkoutPath,
+      cleanup: async () => {},
+    },
+    cleanup: async () => {
+      await rm(fixtureRoot, { recursive: true, force: true });
+    },
+  };
+}

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

@@ -0,0 +1,142 @@
+import { expect, type Page } from "@playwright/test";
+import { buildSeededHost } from "./daemon-registry";
+
+const REGISTRY_KEY = "@paseo:daemon-registry";
+const SEED_NONCE_KEY = "@paseo:e2e-seed-nonce";
+const DISABLE_DEFAULT_SEED_ONCE_KEY = "@paseo:e2e-disable-default-seed-once";
+
+// The multi-host UI (the command-center host label, the sidebar host filter) only renders once
+// more than one host exists. The e2e harness runs a single real daemon, so we add an extra registry
+// entry pointing at an unreachable endpoint: it stays offline, which is enough to make the UI treat
+// the view as multi-host without standing up a second daemon.
+//
+// Must run AFTER the first navigation: the auto-seed fixture writes the registry + nonce on load,
+// and reseeds on every navigation. We write the full registry here and set the fixture's
+// disable-once flag, then reload — so the fixture skips its reset and the registry survives. This
+// avoids depending on the (unspecified) ordering of multiple Playwright init scripts. Optionally
+// relabels the seeded primary host so assertions can target a distinctive name.
+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 page.evaluate(
+    ({ host, keys, primaryLabel }) => {
+      const nonce = localStorage.getItem(keys.nonce);
+      if (!nonce) {
+        throw new Error("Expected the e2e seed nonce before overriding the host registry.");
+      }
+      const raw = localStorage.getItem(keys.registry);
+      const registry: Array<{ serverId: string; label?: string }> = raw ? JSON.parse(raw) : [];
+      if (primaryLabel && registry[0]) {
+        registry[0].label = primaryLabel;
+      }
+      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,
+      keys: {
+        registry: REGISTRY_KEY,
+        nonce: SEED_NONCE_KEY,
+        disableSeedOnce: DISABLE_DEFAULT_SEED_ONCE_KEY,
+      },
+      primaryLabel: input.primaryLabel,
+    },
+  );
+
+  await page.reload();
+}
+
+export async function addConnectedHostAndReload(
+  page: Page,
+  input: { serverId: string; label: string; port: number; primaryLabel?: string },
+): Promise<void> {
+  await addConnectedHostsAndReload(page, [input], { primaryLabel: input.primaryLabel });
+}
+
+export async function addConnectedHostsAndReload(
+  page: Page,
+  inputs: Array<{ serverId: string; label: string; port: number }>,
+  options?: { primaryLabel?: string },
+): Promise<void> {
+  const connectedHosts = inputs.map((input) =>
+    buildSeededHost({
+      serverId: input.serverId,
+      label: input.label,
+      endpoint: `127.0.0.1:${input.port}`,
+      nowIso: new Date().toISOString(),
+    }),
+  );
+
+  await page.evaluate(
+    ({ hosts, keys, primaryLabel }) => {
+      const nonce = localStorage.getItem(keys.nonce);
+      if (!nonce) {
+        throw new Error("Expected the e2e seed nonce before overriding the host registry.");
+      }
+      const raw = localStorage.getItem(keys.registry);
+      const registry: Array<{ serverId: string; label?: string }> = raw ? JSON.parse(raw) : [];
+      if (primaryLabel && registry[0]) registry[0].label = primaryLabel;
+      for (const host of hosts) {
+        if (!registry.some((entry) => entry.serverId === host.serverId)) {
+          registry.push(host);
+        }
+      }
+      localStorage.setItem(keys.registry, JSON.stringify(registry));
+      localStorage.setItem(keys.disableSeedOnce, nonce);
+    },
+    {
+      hosts: connectedHosts,
+      keys: {
+        registry: REGISTRY_KEY,
+        nonce: SEED_NONCE_KEY,
+        disableSeedOnce: DISABLE_DEFAULT_SEED_ONCE_KEY,
+      },
+      primaryLabel: options?.primaryLabel,
+    },
+  );
+
+  await page.reload();
+}
+
+export async function waitForConnectedHost(
+  page: Page,
+  input: { serverId: string; endpoint: string },
+): Promise<void> {
+  await page.getByTestId("sidebar-hosts-trigger").click();
+  const host = page.getByTestId(`sidebar-host-row-${input.serverId}`);
+  await expect(host).toContainText(input.endpoint, { timeout: 30_000 });
+  await page.keyboard.press("Escape");
+  await expect(host).not.toBeVisible();
+}
+
+export async function openSidebarDisplayPreferences(page: Page): Promise<void> {
+  await page.getByTestId("sidebar-display-preferences-menu").click();
+  await expect(page.getByTestId("sidebar-display-preferences-content")).toBeVisible({
+    timeout: 10_000,
+  });
+}
+
+// A host's filter row carries a status dot on the left next to its label.
+export async function expectHostFilterRow(page: Page, serverId: string): Promise<void> {
+  await expect(page.getByTestId(`sidebar-host-filter-${serverId}`)).toBeVisible();
+  await expect(page.getByTestId(`sidebar-host-filter-status-${serverId}`)).toBeVisible();
+}
+
+export async function toggleHostFilter(page: Page, serverId: string): Promise<void> {
+  await page.getByTestId(`sidebar-host-filter-${serverId}`).click();
+}
+
+export async function selectAllHostsFilter(page: Page): Promise<void> {
+  await page.getByTestId("sidebar-host-filter-all").click();
+}

packages/app/e2e/support/helpers/isolated-host-daemon.ts

@@ -0,0 +1,191 @@
+import { once } from "node:events";
+import { spawn, execSync, type ChildProcess } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import net from "node:net";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { withDisabledE2ESpeechEnv } from "./speech-env";
+
+export interface IsolatedHostDaemon {
+  serverId: string;
+  port: number;
+  paseoHome: string;
+  getPid(): number | undefined;
+  restart(): Promise<void>;
+  close(): Promise<void>;
+}
+
+export interface IsolatedHostDaemonOptions {
+  environment?: NodeJS.ProcessEnv;
+  mutableRelay?: {
+    enabled: boolean;
+    endpoint?: string;
+  };
+  paseoHome?: string;
+  preserveHome?: boolean;
+}
+
+async function getAvailablePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        server.close(() => reject(new Error("Failed to acquire an isolated daemon port")));
+        return;
+      }
+      server.close(() => resolve(address.port));
+    });
+  });
+}
+
+async function waitForServer(port: number, child: ChildProcess): Promise<void> {
+  const deadline = Date.now() + 20_000;
+  let lastError: unknown = null;
+
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null) {
+      throw new Error(`Isolated host daemon exited before listening (exit ${child.exitCode})`);
+    }
+    try {
+      await new Promise<void>((resolve, reject) => {
+        const socket = net.connect(port, "127.0.0.1", () => {
+          socket.end();
+          resolve();
+        });
+        socket.setTimeout(1_000, () => {
+          socket.destroy();
+          reject(new Error(`Connection timed out to isolated daemon port ${port}`));
+        });
+        socket.on("error", reject);
+      });
+      return;
+    } catch (error) {
+      lastError = error;
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }
+
+  throw new Error(
+    `Isolated host daemon did not listen on ${port}: ${
+      lastError instanceof Error ? lastError.message : String(lastError)
+    }`,
+  );
+}
+
+async function stopProcess(child: ChildProcess): Promise<void> {
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  child.kill("SIGTERM");
+  const timeout = setTimeout(() => {
+    if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+  }, 5_000);
+  try {
+    await once(child, "exit");
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export async function startIsolatedHostDaemon(
+  serverId: string,
+  options: IsolatedHostDaemonOptions = {},
+): Promise<IsolatedHostDaemon> {
+  const primaryPort = Number(process.env.E2E_DAEMON_PORT ?? 0);
+  let port = await getAvailablePort();
+  while (port === 6767 || port === primaryPort) port = await getAvailablePort();
+
+  const metroPort = process.env.E2E_METRO_PORT;
+  if (!metroPort) throw new Error("E2E_METRO_PORT is required to start an isolated host daemon");
+
+  const paseoHome =
+    options.paseoHome ?? (await mkdtemp(path.join(tmpdir(), "paseo-e2e-secondary-host-")));
+  if (options.mutableRelay) {
+    const endpoint =
+      options.mutableRelay.endpoint ??
+      (process.env.E2E_RELAY_PORT ? `127.0.0.1:${process.env.E2E_RELAY_PORT}` : "127.0.0.1:9");
+    await writeFile(
+      path.join(paseoHome, "config.json"),
+      `${JSON.stringify({
+        version: 1,
+        daemon: {
+          relay: {
+            enabled: options.mutableRelay.enabled,
+            endpoint,
+            publicEndpoint: endpoint,
+            useTls: false,
+            publicUseTls: false,
+          },
+        },
+      })}\n`,
+    );
+  }
+  const serverDir = path.resolve(__dirname, "../../../../server");
+  const tsxBin = execSync("which tsx").toString().trim();
+  const spawnDaemon = async (): Promise<ChildProcess> => {
+    const child = spawn(tsxBin, ["scripts/supervisor-entrypoint.ts", "--dev"], {
+      cwd: serverDir,
+      env: withDisabledE2ESpeechEnv({
+        ...process.env,
+        ...options.environment,
+        PASEO_HOME: paseoHome,
+        PASEO_SERVER_ID: serverId,
+        PASEO_LISTEN: `127.0.0.1:${port}`,
+        PASEO_CORS_ORIGINS: `http://localhost:${metroPort}`,
+        PASEO_RELAY_ENABLED: options.mutableRelay ? undefined : "0",
+        PASEO_NODE_ENV: "development",
+        NODE_ENV: "development",
+      }),
+      stdio: ["ignore", "ignore", "pipe"],
+      detached: false,
+    });
+
+    let stderr = "";
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString("utf8");
+      stderr = stderr.split("\n").slice(-40).join("\n");
+    });
+
+    try {
+      await waitForServer(port, child);
+      return child;
+    } catch (error) {
+      await stopProcess(child);
+      throw new Error(
+        `${error instanceof Error ? error.message : String(error)}\nDaemon stderr:\n${stderr}`,
+        { cause: error },
+      );
+    }
+  };
+
+  let child: ChildProcess;
+  try {
+    child = await spawnDaemon();
+  } catch (error) {
+    if (!options.preserveHome) {
+      await rm(paseoHome, { recursive: true, force: true });
+    }
+    throw error;
+  }
+  let closed = false;
+
+  return {
+    serverId,
+    port,
+    paseoHome,
+    getPid: () => child.pid,
+    restart: async () => {
+      if (closed) throw new Error(`Cannot restart closed isolated daemon ${serverId}`);
+      await stopProcess(child);
+      child = await spawnDaemon();
+    },
+    close: async () => {
+      if (closed) return;
+      closed = true;
+      await stopProcess(child);
+      if (!options.preserveHome) {
+        await rm(paseoHome, { recursive: true, force: true });
+      }
+    },
+  };
+}

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

@@ -0,0 +1,202 @@
+import { expect, type Page } from "@playwright/test";
+import { buildHostWorkspaceRoute } from "../../../src/utils/host-routes";
+import { createTempGitRepo } from "./workspace";
+import { getServerId } from "./server-id";
+
+// ─── Navigation ────────────────────────────────────────────────────────────
+
+/** Navigate to a workspace and wait for the tab bar to appear. */
+export async function gotoWorkspace(page: Page, workspaceId: string): Promise<void> {
+  const route = buildHostWorkspaceRoute(getServerId(), workspaceId);
+  await page.goto(route);
+  await waitForTabBar(page);
+}
+
+// ─── Tab bar queries ───────────────────────────────────────────────────────
+
+/** Wait for the workspace tab bar to be visible. */
+export async function waitForTabBar(page: Page): Promise<void> {
+  await expect(
+    page.getByTestId("workspace-tabs-row").filter({ visible: true }).first(),
+  ).toBeVisible({
+    timeout: 30_000,
+  });
+}
+
+/** Return all tab test IDs currently in the tab bar. */
+export async function getTabTestIds(page: Page): Promise<string[]> {
+  const tabs = page
+    .locator('[data-testid^="workspace-tab-"]:not([data-testid^="workspace-tab-context-"])')
+    .filter({ visible: true });
+  const count = await tabs.count();
+  const ids: string[] = [];
+  for (let i = 0; i < count; i++) {
+    const testId = await tabs.nth(i).getAttribute("data-testid");
+    if (testId) ids.push(testId);
+  }
+  return ids;
+}
+
+/** Return the number of tabs matching a kind prefix (e.g. "launcher", "draft", "terminal", "agent"). */
+export async function countTabsOfKind(page: Page, kind: string): Promise<number> {
+  const ids = await getTabTestIds(page);
+  return ids.filter((id) => id.includes(kind)).length;
+}
+
+/** Return the currently active tab's test ID (the one with aria-selected or focus styling). */
+export async function getActiveTabTestId(page: Page): Promise<string | null> {
+  // Active tab has the focused highlight — check for the aria-selected or data-active attribute
+  const activeTab = page
+    .locator(
+      '[data-testid^="workspace-tab-"]:not([data-testid^="workspace-tab-context-"])[aria-selected="true"]',
+    )
+    .filter({ visible: true })
+    .first();
+  if (await activeTab.isVisible().catch(() => false)) {
+    return activeTab.getAttribute("data-testid");
+  }
+  // Fallback: the tab with focused styling
+  return null;
+}
+
+// ─── Tab actions ───────────────────────────────────────────────────────────
+
+/** Press Cmd+T (macOS) or Ctrl+T (Linux/Windows) to open a new tab. */
+export async function pressNewTabShortcut(page: Page): Promise<void> {
+  const modifier = process.platform === "darwin" ? "Meta" : "Control";
+  await page.keyboard.press(`${modifier}+t`);
+}
+
+// ─── Tab bar assertions ───────────────────────────────────────────────────
+
+/** Assert the inline new-agent plus button is visible in the tab bar. */
+export async function assertNewChatTileVisible(page: Page): Promise<void> {
+  await expect(
+    page.getByTestId("workspace-new-agent-tab-inline").filter({ visible: true }).first(),
+  ).toBeVisible();
+}
+
+/** Assert the new-tab dropdown trigger is visible in the tab bar. */
+export async function assertNewTabMenuTriggerVisible(page: Page): Promise<void> {
+  await expect(
+    page.getByTestId("workspace-new-tab-menu-trigger").filter({ visible: true }).first(),
+  ).toBeVisible();
+}
+
+// ─── Tab creation actions ─────────────────────────────────────────────────
+
+/** Click the inline plus button to create a draft/chat tab. */
+export async function clickNewChat(page: Page): Promise<void> {
+  const button = page
+    .getByTestId("workspace-new-agent-tab-inline")
+    .filter({ visible: true })
+    .first();
+  await expect(button).toBeVisible({ timeout: 10_000 });
+  await button.click();
+}
+
+/** Open the new-tab menu and click "New terminal". */
+export async function clickNewTerminal(page: Page): Promise<void> {
+  const trigger = page
+    .getByTestId("workspace-new-tab-menu-trigger")
+    .filter({ visible: true })
+    .first();
+  await expect(trigger).toBeVisible({ timeout: 10_000 });
+  await trigger.click();
+  const item = page
+    .getByTestId("workspace-new-tab-menu-terminal")
+    .filter({ visible: true })
+    .first();
+  await expect(item).toBeVisible({ timeout: 10_000 });
+  await item.click();
+}
+
+// ─── Tab title assertions ──────────────────────────────────────────────────
+
+/** Wait for any tab in the bar to display the given title text. */
+export async function waitForTabWithTitle(
+  page: Page,
+  title: string | RegExp,
+  timeout = 30_000,
+): Promise<void> {
+  const matcher = typeof title === "string" ? new RegExp(title, "i") : title;
+  await expect(
+    page
+      .locator('[data-testid^="workspace-tab-"]:not([data-testid^="workspace-tab-context-"])')
+      .filter({ hasText: matcher })
+      .filter({ visible: true })
+      .first(),
+  ).toBeVisible({ timeout });
+}
+
+/** Assert the inline new-agent plus button is visible in the tab bar. */
+export async function assertSingleNewTabButton(page: Page): Promise<void> {
+  const buttons = page.getByTestId("workspace-new-agent-tab-inline").filter({ visible: true });
+  const count = await buttons.count();
+  expect(count).toBeGreaterThanOrEqual(1);
+}
+
+// ─── No-flash measurement ──────────────────────────────────────────────────
+
+/**
+ * Measure the time between clicking a launcher tile and the replacement panel becoming visible.
+ * Returns elapsed milliseconds.
+ */
+export async function measureTileTransition(
+  page: Page,
+  clickAction: () => Promise<void>,
+  successLocator: ReturnType<Page["locator"]>,
+  timeout = 5_000,
+): Promise<number> {
+  const start = Date.now();
+  await clickAction();
+  await expect(successLocator).toBeVisible({ timeout });
+  return Date.now() - start;
+}
+
+/**
+ * Sample tab IDs at high frequency across a transition to detect blank/intermediate states.
+ * Returns all unique snapshots observed.
+ */
+export async function sampleTabsDuringTransition(
+  page: Page,
+  action: () => Promise<void>,
+  durationMs = 2_000,
+  intervalMs = 30,
+): Promise<string[][]> {
+  const snapshots: string[][] = [];
+  const startSampling = async () => {
+    const start = Date.now();
+    while (Date.now() - start < durationMs) {
+      snapshots.push(await getTabTestIds(page));
+      await page.waitForTimeout(intervalMs);
+    }
+  };
+
+  const samplingPromise = startSampling();
+  await action();
+  await samplingPromise;
+  return snapshots;
+}
+
+export function terminalSurfaceLocator(page: Page) {
+  return page.locator('[data-testid="terminal-surface"]').first();
+}
+
+export async function expectAgentTabActive(page: Page, agentId: string): Promise<void> {
+  const tabTestId = `workspace-tab-agent_${agentId}`;
+  await expect(page.getByTestId(tabTestId).filter({ visible: true })).toHaveAttribute(
+    "aria-selected",
+    "true",
+  );
+  await expect(getActiveTabTestId(page)).resolves.toBe(tabTestId);
+}
+
+// ─── Workspace setup ───────────────────────────────────────────────────────
+
+/** Create a temp git repo and return its path with a cleanup function. */
+export async function createWorkspace(
+  prefix = "launcher-e2e-",
+): ReturnType<typeof createTempGitRepo> {
+  return createTempGitRepo(prefix);
+}

packages/app/e2e/support/helpers/mock-agent.ts

@@ -0,0 +1,87 @@
+import type { Page } from "@playwright/test";
+import { seedWorkspace, type SeedDaemonClient } from "./seed-client";
+import { getServerId } from "./server-id";
+import { buildHostAgentDetailRoute } from "../../../src/utils/host-routes";
+
+export interface MockAgentWorkspace {
+  agentId: string;
+  workspaceId: string;
+  cwd: string;
+  client: SeedDaemonClient;
+  cleanup(): Promise<void>;
+}
+
+export interface MockAgentOptions {
+  repoPrefix: string;
+  title: string;
+  initialPrompt?: string;
+  model?: string;
+  modeId?: string;
+  featureValues?: Record<string, unknown>;
+}
+
+/**
+ * Seeds a temp git repo, opens it as a project, and creates a ready mock-provider
+ * agent in it via the daemon. Returns the agent id plus a cleanup that closes the
+ * client and removes the repo. Pair with {@link openAgentRoute} to drive the UI.
+ */
+export async function seedMockAgentWorkspace(
+  options: MockAgentOptions,
+): Promise<MockAgentWorkspace> {
+  const workspace = await seedWorkspace({ repoPrefix: options.repoPrefix });
+  try {
+    const agent = await workspace.client.createAgent({
+      provider: "mock",
+      cwd: workspace.repoPath,
+      workspaceId: workspace.workspaceId,
+      title: options.title,
+      modeId: options.modeId ?? "load-test",
+      model: options.model ?? "ten-second-stream",
+      initialPrompt: options.initialPrompt,
+      featureValues: options.featureValues,
+    });
+    return {
+      agentId: agent.id,
+      workspaceId: workspace.workspaceId,
+      cwd: workspace.repoPath,
+      client: workspace.client,
+      cleanup: workspace.cleanup,
+    };
+  } catch (error) {
+    await workspace.cleanup();
+    throw error;
+  }
+}
+
+export async function seedRunningMockAgentWorkspace(
+  options: MockAgentOptions,
+): Promise<MockAgentWorkspace> {
+  const agent = await seedMockAgentWorkspace(options);
+  try {
+    await agent.client.waitForAgentUpsert(
+      agent.agentId,
+      (snapshot) => snapshot.status === "running",
+      15_000,
+    );
+    return agent;
+  } catch (error) {
+    await agent.cleanup();
+    throw error;
+  }
+}
+
+export function buildAgentRoute(workspaceId: string, agentId: string): string {
+  return buildHostAgentDetailRoute(getServerId(), agentId, workspaceId);
+}
+
+/** Boots the app directly at the agent's workspace route and waits for the open intent to settle. */
+export async function openAgentRoute(
+  page: Page,
+  input: { workspaceId: string; agentId: string },
+): Promise<void> {
+  await page.goto(buildAgentRoute(input.workspaceId, input.agentId));
+  await page.waitForURL(
+    (url) => url.pathname.includes("/workspace/") && !url.searchParams.has("open"),
+    { timeout: 60_000 },
+  );
+}

packages/app/e2e/support/helpers/new-workspace.ts

@@ -0,0 +1,574 @@
+import { expect, type BrowserContext, type Page } from "@playwright/test";
+import type { DaemonClient as InternalDaemonClient } from "@getpaseo/client/internal/daemon-client";
+import { decodeWorkspaceIdFromPathSegment } from "@/utils/host-routes";
+import { connectDaemonClient } from "./daemon-client-loader";
+import { daemonWsRoutePattern } from "./daemon-port";
+import { projectEquivalenceViewKey } from "./project-view-key";
+import { expectWorkspaceHeader } from "./workspace-ui";
+import { withProjectOwnership } from "./project-ownership";
+
+type NewWorkspaceDaemonClient = Pick<
+  InternalDaemonClient,
+  | "archivePaseoWorktree"
+  | "archiveWorkspace"
+  | "checkoutRefresh"
+  | "close"
+  | "connect"
+  | "createPaseoWorktree"
+  | "createWorkspace"
+  | "fetchWorkspaces"
+  | "getPaseoWorktreeList"
+  | "getDaemonConfig"
+  | "inspectWorkspaceRecovery"
+  | "listProjects"
+  | "on"
+  | "patchDaemonConfig"
+  | "removeProject"
+>;
+
+type CreateWorkspacePayload = Awaited<ReturnType<NewWorkspaceDaemonClient["createWorkspace"]>>;
+type WorkspacePayload = Pick<CreateWorkspacePayload, "error" | "workspace">;
+type WorkspaceDescriptor = NonNullable<CreateWorkspacePayload["workspace"]>;
+
+export interface OpenedProject {
+  workspaceId: string;
+  projectId: string;
+  projectKey: string;
+  projectDisplayName: string;
+  workspaceName: string;
+  workspaceDirectory: string;
+}
+
+function requireWorkspace(payload: WorkspacePayload) {
+  if (payload.error) {
+    throw new Error(payload.error);
+  }
+  if (!payload.workspace) {
+    throw new Error("workspace.create returned no workspace.");
+  }
+  return payload.workspace;
+}
+
+async function openedProjectFromWorkspace(
+  client: NewWorkspaceDaemonClient,
+  workspace: WorkspaceDescriptor,
+): Promise<OpenedProject> {
+  const payload = await client.listProjects();
+  const project = payload.projects.find((candidate) => candidate.projectId === workspace.projectId);
+  if (!project?.projectKey) {
+    throw new Error(`Project ${workspace.projectId} has no project key`);
+  }
+  return {
+    workspaceId: workspace.id,
+    projectId: workspace.projectId,
+    projectKey: project.projectKey,
+    projectDisplayName: workspace.projectDisplayName,
+    workspaceName: workspace.name,
+    workspaceDirectory: workspace.workspaceDirectory,
+  };
+}
+
+async function fetchWorkspaceById(
+  client: NewWorkspaceDaemonClient,
+  workspaceId: string,
+): Promise<WorkspaceDescriptor | null> {
+  const payload = await client.fetchWorkspaces();
+  return payload.entries.find((entry) => entry.id === workspaceId) ?? null;
+}
+
+async function waitForWorkspaceDescriptor(
+  client: NewWorkspaceDaemonClient,
+  workspaceId: string,
+): Promise<WorkspaceDescriptor> {
+  const deadline = Date.now() + 30_000;
+  while (Date.now() < deadline) {
+    const workspace = await fetchWorkspaceById(client, workspaceId);
+    if (workspace) {
+      return workspace;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  throw new Error(`Workspace descriptor not found: ${workspaceId}`);
+}
+
+function parseWorkspaceIdFromPageUrl(page: Page, serverId: string): string | null {
+  const pathname = new URL(page.url()).pathname;
+  const match = pathname.match(
+    new RegExp(`^/h/${serverId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/workspace/([^/?#]+)`),
+  );
+  if (!match?.[1]) {
+    return null;
+  }
+  return decodeWorkspaceIdFromPathSegment(match[1]);
+}
+
+export async function connectNewWorkspaceDaemonClient(options?: {
+  port?: number;
+  ownProjects?: boolean;
+}): Promise<NewWorkspaceDaemonClient> {
+  const client = await connectDaemonClient<NewWorkspaceDaemonClient>({
+    clientIdPrefix: "app-e2e-new-workspace",
+    port: options?.port,
+  });
+  if (options?.ownProjects === false) return client;
+
+  return withProjectOwnership(client);
+}
+
+export async function openProjectViaDaemon(
+  client: NewWorkspaceDaemonClient,
+  repoPath: string,
+): Promise<OpenedProject> {
+  const workspace = requireWorkspace(
+    await client.createWorkspace({
+      source: { kind: "directory", path: repoPath },
+    }),
+  );
+  return openedProjectFromWorkspace(client, workspace);
+}
+
+export async function archiveWorkspaceFromDaemon(
+  client: NewWorkspaceDaemonClient,
+  workspaceDirectory: string,
+  options?: { scope?: "workspace" | "worktree" },
+): Promise<void> {
+  const payload = await client.archivePaseoWorktree({
+    worktreePath: workspaceDirectory,
+    ...(options?.scope !== undefined ? { scope: options.scope } : {}),
+  });
+  if (payload.error) {
+    throw new Error(payload.error.message);
+  }
+  if (!payload.success) {
+    throw new Error(`Failed to archive workspace: ${workspaceDirectory}`);
+  }
+}
+
+export async function archiveLocalWorkspaceFromDaemon(
+  client: NewWorkspaceDaemonClient,
+  workspaceId: string,
+): Promise<void> {
+  const payload = await client.archiveWorkspace(workspaceId);
+  if (payload.error) {
+    throw new Error(payload.error);
+  }
+  if (!payload.archivedAt) {
+    throw new Error(`Failed to archive workspace: ${workspaceId}`);
+  }
+}
+
+export async function createWorktreeViaDaemon(
+  client: NewWorkspaceDaemonClient,
+  input: { cwd: string; slug: string },
+): Promise<OpenedProject> {
+  const payload = await client.createPaseoWorktree({
+    cwd: input.cwd,
+    worktreeSlug: input.slug,
+  });
+  const workspace = requireWorkspace(payload);
+  return openedProjectFromWorkspace(client, workspace);
+}
+
+export async function openNewWorkspaceComposer(
+  page: Page,
+  input: { projectKey: string; projectDisplayName: string },
+): Promise<void> {
+  const projectViewKey = projectEquivalenceViewKey(input.projectKey);
+  const projectRow = page.getByTestId(`sidebar-project-row-${projectViewKey}`).first();
+  await expect(projectRow).toBeVisible({ timeout: 30_000 });
+  await projectRow.hover();
+
+  const button = page.getByTestId(`sidebar-project-new-worktree-${projectViewKey}`).first();
+  await expect(button).toBeVisible({ timeout: 30_000 });
+  await button.click();
+
+  await expect(page).toHaveURL(/\/new(?:\?.*)?$/, {
+    timeout: 30_000,
+  });
+}
+
+export async function openGlobalNewWorkspaceComposer(page: Page): Promise<void> {
+  await page.getByTestId("sidebar-global-new-workspace").click();
+
+  await expect(page).toHaveURL(/\/new(?:\?.*)?$/, {
+    timeout: 30_000,
+  });
+}
+
+export async function openMissingProjectNewWorkspaceComposer(
+  page: Page,
+  input: { serverId: string; projectId: string; sourceDirectory: string },
+): Promise<void> {
+  const query = new URLSearchParams({
+    serverId: input.serverId,
+    projectId: input.projectId,
+    dir: input.sourceDirectory,
+    name: "Missing project",
+  });
+  await page.goto(`/new?${query.toString()}`);
+  await expect(page).toHaveURL(/\/new\?.*projectId=/u, { timeout: 30_000 });
+}
+
+export async function expectNewWorkspaceControlsEnabled(page: Page): Promise<void> {
+  await expect(page.getByRole("button", { name: "Workspace project" })).toBeEnabled({
+    timeout: 30_000,
+  });
+  await expect(page.getByRole("textbox", { name: "Message agent..." })).toBeEditable({
+    timeout: 30_000,
+  });
+}
+
+export async function openNewWorkspaceProjectPickerWithShortcut(page: Page): Promise<void> {
+  await page.keyboard.press("Control+P");
+
+  const searchInput = page.getByPlaceholder("Search projects");
+  await expect(searchInput).toBeVisible({ timeout: 30_000 });
+  await expect(searchInput).toBeFocused();
+}
+
+export async function expectNewWorkspaceProjectSelected(
+  page: Page,
+  projectDisplayName: string,
+): Promise<void> {
+  const projectPicker = page.getByRole("button", { name: "Workspace project" });
+  await expect(projectPicker).toBeVisible({ timeout: 30_000 });
+  await expect(projectPicker).toContainText(projectDisplayName);
+}
+
+export async function fillNewWorkspaceDraft(page: Page, draft: string): Promise<void> {
+  const composer = page.getByRole("textbox", { name: "Message agent..." });
+  await expect(composer).toBeVisible({ timeout: 30_000 });
+  await composer.fill(draft);
+}
+
+export async function expectNewWorkspaceDraft(page: Page, draft: string): Promise<void> {
+  await expect(page.getByRole("textbox", { name: "Message agent..." })).toHaveValue(draft);
+}
+
+export async function selectNewWorkspaceHost(page: Page, hostLabel: string): Promise<void> {
+  const trigger = page.getByTestId("host-picker-trigger");
+  await trigger.click();
+  await page.getByRole("button", { name: hostLabel, exact: true }).click();
+  await expect(trigger).toContainText(hostLabel);
+}
+
+export async function submitNewWorkspacePrompt(
+  page: Page,
+  prompt = "Hello from e2e",
+): Promise<void> {
+  const composer = page.getByRole("textbox", { name: "Message agent..." });
+  await expect(composer).toBeVisible({ timeout: 30_000 });
+  await composer.fill(prompt);
+  const createButton = page
+    .getByTestId("message-input-root")
+    .getByRole("button", { name: "Create" });
+  await expect(createButton).toBeVisible({ timeout: 30_000 });
+  await createButton.click();
+}
+
+export async function clickNewWorkspaceButton(
+  page: Page,
+  input: { projectKey: string; projectDisplayName: string; prompt?: string },
+): Promise<void> {
+  await openNewWorkspaceComposer(page, input);
+  await submitNewWorkspacePrompt(page, input.prompt);
+}
+
+export async function selectNewWorkspaceProject(
+  page: Page,
+  input: { projectKey: string; projectDisplayName: string; projectViewKey?: string },
+): Promise<void> {
+  const trigger = page.getByTestId("new-workspace-project-picker-trigger");
+  await expect(trigger).toBeVisible({ timeout: 30_000 });
+  await trigger.click();
+
+  const projectViewKey = input.projectViewKey ?? projectEquivalenceViewKey(input.projectKey);
+  const option = page.getByTestId(`new-workspace-project-picker-option-${projectViewKey}`);
+  await expect(option).toBeVisible({ timeout: 30_000 });
+  await option.click();
+
+  await expectNewWorkspaceProjectSelected(page, input.projectDisplayName);
+}
+
+// The isolation trigger renders the active isolation's label ("Local" / "New
+// worktree"), so asserting its text proves what the screen currently remembers.
+const ISOLATION_TRIGGER_LABEL: Record<"local" | "worktree", string> = {
+  local: "Local",
+  worktree: "New worktree",
+};
+
+export async function expectWorkspaceIsolationSelected(
+  page: Page,
+  isolation: "local" | "worktree",
+): Promise<void> {
+  const trigger = page.getByRole("button", { name: "Workspace isolation" });
+  await expect(trigger).toBeVisible({ timeout: 30_000 });
+  await expect(trigger).toContainText(ISOLATION_TRIGGER_LABEL[isolation]);
+}
+
+export async function selectWorkspaceIsolation(
+  page: Page,
+  isolation: "local" | "worktree",
+): Promise<void> {
+  const trigger = page.getByTestId("workspace-create-isolation-trigger");
+  await expect(trigger).toBeVisible({ timeout: 30_000 });
+  await trigger.click();
+
+  // Isolation options are derived from project capability. Wait for the option
+  // so this helper also covers route-to-project reconciliation.
+  const option = page.getByTestId(`workspace-create-isolation-${isolation}`);
+  await expect(option).toBeVisible({ timeout: 30_000 });
+  await option.click();
+}
+
+export async function submitNewWorkspaceEmpty(page: Page): Promise<void> {
+  const createButton = page
+    .getByTestId("message-input-root")
+    .getByRole("button", { name: "Create" });
+  await expect(createButton).toBeVisible({ timeout: 30_000 });
+  await createButton.click();
+}
+
+export async function openStartingRefPicker(page: Page): Promise<void> {
+  const trigger = page.getByTestId("new-workspace-ref-picker-trigger");
+  await expect(trigger).toBeVisible({ timeout: 30_000 });
+  await trigger.click();
+}
+
+export async function selectBranchInPicker(page: Page, name: string): Promise<void> {
+  const branchRow = page.getByTestId(`new-workspace-ref-picker-branch-${name}`);
+  await expect(branchRow).toBeVisible({ timeout: 30_000 });
+  await branchRow.click();
+}
+
+export async function searchAndSelectBranchInPicker(page: Page, name: string): Promise<void> {
+  const searchInput = page.getByPlaceholder("Search branches and PRs");
+  await expect(searchInput).toBeVisible({ timeout: 30_000 });
+  await searchInput.fill(name);
+  await selectBranchInPicker(page, name);
+}
+
+export async function selectGitHubPrInPicker(page: Page, number: number): Promise<void> {
+  const prRow = page.getByTestId(`new-workspace-ref-picker-pr-${number}`);
+  await expect(prRow).toBeVisible({ timeout: 30_000 });
+  await prRow.click();
+}
+
+export async function expectStartingRefPickerTriggerPr(
+  page: Page,
+  input: { number: number; title: string; headRef: string },
+): Promise<void> {
+  const trigger = page.getByRole("button", { name: "Starting ref" });
+  await expect(trigger).toContainText(`#${input.number}`);
+  await expect(trigger).toContainText(input.title);
+  await expect(trigger).not.toContainText(input.headRef);
+}
+
+export async function openBranchPicker(page: Page): Promise<void> {
+  const trigger = page.getByRole("button", { name: "Starting ref" });
+  await expect(trigger).toBeVisible({ timeout: 30_000 });
+  await trigger.click();
+}
+
+export async function selectPickerOptionByKeyboard(page: Page, label: string): Promise<void> {
+  const searchInput = page.getByPlaceholder("Search branches and PRs");
+  await expect(searchInput).toBeVisible({ timeout: 30_000 });
+  await page.keyboard.type(label);
+  await expect(page.getByTestId(`new-workspace-ref-picker-branch-${label}`)).toBeVisible({
+    timeout: 10_000,
+  });
+  await page.keyboard.press("Enter");
+}
+
+export async function closeBranchPicker(page: Page): Promise<void> {
+  await page.keyboard.press("Escape");
+}
+
+export async function expectPickerOpen(page: Page): Promise<void> {
+  await expect(page.getByTestId("combobox-desktop-container")).toBeVisible({ timeout: 30_000 });
+}
+
+export async function expectPickerClosed(page: Page): Promise<void> {
+  await expect(page.getByTestId("combobox-desktop-container")).not.toBeVisible({
+    timeout: 30_000,
+  });
+}
+
+export async function expectPickerSelected(page: Page, label: string): Promise<void> {
+  const trigger = page.getByRole("button", { name: "Starting ref" });
+  await expect(trigger).toContainText(label);
+}
+
+export async function expectComposerGithubAttachmentPill(
+  page: Page,
+  input: { number: number; title: string },
+): Promise<void> {
+  const pills = page.getByTestId("composer-github-attachment-pill");
+  await expect(pills).toHaveCount(1);
+  await expect(pills.first()).toContainText(`#${input.number}`);
+  await expect(pills.first()).toContainText(input.title);
+}
+
+export async function pasteGithubPrUrl(
+  page: Page,
+  context: BrowserContext,
+  url: string,
+): Promise<void> {
+  const composer = page.getByRole("textbox", { name: "Message agent..." });
+  await context.grantPermissions(["clipboard-read", "clipboard-write"]);
+  await page.evaluate((value) => navigator.clipboard.writeText(value), url);
+  await composer.focus();
+  await page.keyboard.press("Control+V");
+}
+
+export async function assertNewWorkspaceSidebarAndHeader(
+  page: Page,
+  input: {
+    serverId: string;
+    client: NewWorkspaceDaemonClient;
+    previousWorkspaceId: string;
+    projectDisplayName: string;
+    assertSidebarRow?: boolean;
+    assertHeader?: boolean;
+  },
+): Promise<{ workspaceId: string; workspaceName: string; workspaceDirectory: string }> {
+  // URL is the source of truth so concurrent sidebar rows cannot satisfy this.
+  await expect
+    .poll(
+      () => {
+        const workspaceId = parseWorkspaceIdFromPageUrl(page, input.serverId);
+        return workspaceId && workspaceId !== input.previousWorkspaceId ? workspaceId : null;
+      },
+      { timeout: 60_000 },
+    )
+    .not.toBeNull();
+
+  const workspaceId = parseWorkspaceIdFromPageUrl(page, input.serverId);
+  if (!workspaceId || workspaceId === input.previousWorkspaceId) {
+    throw new Error(`Expected URL to redirect to a new workspace.\nCurrent URL: ${page.url()}`);
+  }
+
+  const workspace = await waitForWorkspaceDescriptor(input.client, workspaceId);
+
+  if (input.assertSidebarRow !== false) {
+    const createdWorkspaceRow = page.getByTestId(
+      `sidebar-workspace-row-${input.serverId}:${workspace.id}`,
+    );
+    await expect(createdWorkspaceRow.first()).toBeVisible({ timeout: 30_000 });
+  }
+
+  if (input.assertHeader !== false) {
+    await expectWorkspaceHeader(page, {
+      title: workspace.name,
+      subtitle: input.projectDisplayName,
+    });
+  }
+
+  return {
+    workspaceId: workspace.id,
+    workspaceName: workspace.name,
+    workspaceDirectory: workspace.workspaceDirectory,
+  };
+}
+
+type WebSocketMessage = string | Buffer;
+
+function parseWebSocketJson(message: WebSocketMessage): unknown {
+  const rawMessage = typeof message === "string" ? message : message.toString("utf8");
+  try {
+    return JSON.parse(rawMessage);
+  } catch {
+    return null;
+  }
+}
+
+function getSessionMessage(message: WebSocketMessage): Record<string, unknown> | null {
+  const envelope = parseWebSocketJson(message);
+  if (!envelope || typeof envelope !== "object") {
+    return null;
+  }
+  const maybeEnvelope = envelope as { type?: unknown; message?: unknown };
+  if (maybeEnvelope.type !== "session" || !maybeEnvelope.message) {
+    return null;
+  }
+  if (typeof maybeEnvelope.message !== "object") {
+    return null;
+  }
+  return maybeEnvelope.message as Record<string, unknown>;
+}
+
+function getStringField(input: Record<string, unknown>, key: string): string | null {
+  const value = input[key];
+  return typeof value === "string" ? value : null;
+}
+
+export interface AgentCreatedDelayControl {
+  release(): void;
+  waitForCreateRequest(): Promise<void>;
+  waitForDelayedCreatedStatus(): Promise<void>;
+}
+
+export async function delayBrowserAgentCreatedStatus(
+  page: Page,
+): Promise<AgentCreatedDelayControl> {
+  const daemonPortPattern = daemonWsRoutePattern();
+  const createRequestIds = new Set<string>();
+  const delayedForwards: Array<() => void> = [];
+  let releaseRequested = false;
+  let resolveCreateRequest: (() => void) | null = null;
+  let resolveDelayedCreatedStatus: (() => void) | null = null;
+  const createRequestSeen = new Promise<void>((resolve) => {
+    resolveCreateRequest = resolve;
+  });
+  const delayedCreatedStatusSeen = new Promise<void>((resolve) => {
+    resolveDelayedCreatedStatus = resolve;
+  });
+
+  await page.routeWebSocket(daemonPortPattern, (ws) => {
+    const server = ws.connectToServer();
+
+    ws.onMessage((message) => {
+      const sessionMessage = getSessionMessage(message);
+      if (sessionMessage?.type === "create_agent_request") {
+        const requestId = getStringField(sessionMessage, "requestId");
+        if (requestId) {
+          createRequestIds.add(requestId);
+          resolveCreateRequest?.();
+        }
+      }
+      server.send(message);
+    });
+
+    server.onMessage((message) => {
+      const sessionMessage = getSessionMessage(message);
+      const payload =
+        sessionMessage?.type === "status" && typeof sessionMessage.payload === "object"
+          ? (sessionMessage.payload as Record<string, unknown>)
+          : null;
+      const requestId = payload ? getStringField(payload, "requestId") : null;
+
+      if (payload?.status === "agent_created" && requestId && createRequestIds.has(requestId)) {
+        resolveDelayedCreatedStatus?.();
+        if (releaseRequested) {
+          ws.send(message);
+          return;
+        }
+        delayedForwards.push(() => ws.send(message));
+        return;
+      }
+
+      ws.send(message);
+    });
+  });
+
+  return {
+    release() {
+      releaseRequested = true;
+      for (const forward of delayedForwards.splice(0)) {
+        forward();
+      }
+    },
+    waitForCreateRequest: () => createRequestSeen,
+    waitForDelayedCreatedStatus: () => delayedCreatedStatusSeen,
+  };
+}

packages/app/e2e/support/helpers/no-truncation.ts

@@ -0,0 +1,61 @@
+import { expect, type Locator } from "@playwright/test";
+
+interface TruncatedLabel {
+  text: string;
+  scrollWidth: number;
+  clientWidth: number;
+}
+
+export async function expectNoTruncation(locator: Locator): Promise<void> {
+  await expect(locator.first()).toBeVisible({ timeout: 30_000 });
+
+  const truncated = await locator.evaluateAll((elements): TruncatedLabel[] => {
+    function isVisible(element: HTMLElement): boolean {
+      const style = window.getComputedStyle(element);
+      const rect = element.getBoundingClientRect();
+      return (
+        style.display !== "none" &&
+        style.visibility !== "hidden" &&
+        rect.width > 0 &&
+        rect.height > 0
+      );
+    }
+
+    function directText(element: HTMLElement): string {
+      return Array.from(element.childNodes)
+        .filter((node) => node.nodeType === Node.TEXT_NODE)
+        .map((node) => node.textContent ?? "")
+        .join("")
+        .trim();
+    }
+
+    const checked = new Set<HTMLElement>();
+    const failures: TruncatedLabel[] = [];
+
+    for (const root of elements) {
+      if (!(root instanceof HTMLElement) || !isVisible(root)) continue;
+      const candidates = [root, ...Array.from(root.querySelectorAll<HTMLElement>("*"))];
+
+      for (const candidate of candidates) {
+        if (checked.has(candidate) || !isVisible(candidate) || candidate.clientWidth <= 0) {
+          continue;
+        }
+        checked.add(candidate);
+
+        const text = directText(candidate);
+        if (!text) continue;
+        if (candidate.scrollWidth <= candidate.clientWidth) continue;
+
+        failures.push({
+          text,
+          scrollWidth: candidate.scrollWidth,
+          clientWidth: candidate.clientWidth,
+        });
+      }
+    }
+
+    return failures;
+  });
+
+  expect(truncated, "option labels should not be horizontally truncated").toEqual([]);
+}

packages/app/e2e/support/helpers/node-ws-factory.ts

@@ -0,0 +1,27 @@
+import { WebSocket } from "ws";
+
+interface WebSocketLike {
+  readyState: number;
+  send: (data: string | Uint8Array | ArrayBuffer) => void;
+  close: (code?: number, reason?: string) => void;
+  binaryType?: string;
+  on?: (event: string, listener: (...args: unknown[]) => void) => void;
+  off?: (event: string, listener: (...args: unknown[]) => void) => void;
+  removeListener?: (event: string, listener: (...args: unknown[]) => void) => void;
+  addEventListener?: (event: string, listener: (event: unknown) => void) => void;
+  removeEventListener?: (event: string, listener: (event: unknown) => void) => void;
+  onopen?: ((event: unknown) => void) | null;
+  onclose?: ((event: unknown) => void) | null;
+  onerror?: ((event: unknown) => void) | null;
+  onmessage?: ((event: unknown) => void) | null;
+}
+
+export type NodeWebSocketFactory = (
+  url: string,
+  options?: { headers?: Record<string, string> },
+) => WebSocketLike;
+
+export function createNodeWebSocketFactory(): NodeWebSocketFactory {
+  return (url: string, options?: { headers?: Record<string, string> }) =>
+    new WebSocket(url, { headers: options?.headers }) as unknown as WebSocketLike;
+}

packages/app/e2e/support/helpers/pair-device.ts

@@ -0,0 +1,218 @@
+import { expect, type Page } from "@playwright/test";
+import type { IsolatedHostDaemon } from "./isolated-host-daemon";
+import type { OutdatedDaemon } from "./daemon-update";
+import { openSettings, gotoAppShell } from "./app";
+import {
+  openSettingsHost,
+  openSettingsHostSection,
+  seedSavedSettingsHosts,
+  selectSettingsHost,
+} from "./settings";
+import { expectAppRoute } from "./route-assertions";
+import { buildSettingsHostSectionRoute } from "@/utils/host-routes";
+
+interface PairingHostInput {
+  serverId: string;
+  label: string;
+  endpoint: string;
+}
+
+export async function prepareLocalPairingHost(
+  page: Page,
+  daemon: IsolatedHostDaemon | OutdatedDaemon,
+  additionalHosts: PairingHostInput[] = [],
+): Promise<void> {
+  await page.addInitScript((localServerId) => {
+    (window as unknown as { paseoDesktop: unknown }).paseoDesktop = {
+      platform: "darwin",
+      invoke: async (command: string) => {
+        if (command === "desktop_daemon_status") {
+          return {
+            serverId: localServerId,
+            status: "running",
+            listen: null,
+            hostname: null,
+            pid: null,
+            home: "",
+            version: null,
+            desktopManaged: true,
+            error: null,
+          };
+        }
+        if (command === "get_desktop_settings") {
+          return {
+            releaseChannel: "stable",
+            daemon: { manageBuiltInDaemon: false, keepRunningAfterQuit: true },
+          };
+        }
+        return null;
+      },
+      getPendingOpenProject: async () => null,
+      events: { on: async () => () => undefined },
+      opener: {
+        openUrl: async (url: string) => {
+          localStorage.setItem("@paseo:e2e-opened-url", url);
+        },
+      },
+    };
+  }, daemon.serverId);
+
+  await preparePairingHost(page, daemon, additionalHosts);
+}
+
+export async function preparePairingHost(
+  page: Page,
+  daemon: IsolatedHostDaemon | OutdatedDaemon,
+  additionalHosts: PairingHostInput[] = [],
+): Promise<void> {
+  await seedSavedSettingsHosts(page, [
+    {
+      serverId: daemon.serverId,
+      label: "Local pairing host",
+      endpoint: "port" in daemon ? `127.0.0.1:${daemon.port}` : daemon.endpoint,
+    },
+    ...additionalHosts,
+  ]);
+  await gotoAppShell(page);
+  await openSettings(page);
+  await openSettingsHost(page, daemon.serverId);
+  await expect(page.getByTestId("host-page-pair-device-row")).toHaveCount(0);
+  await openSettingsHostSection(page, daemon.serverId, "pair-device");
+  await expect(page.getByTestId("host-page-pair-device-row")).toBeVisible();
+}
+
+export async function openPairDeviceModal(page: Page): Promise<void> {
+  await page.getByRole("button", { name: /Pair a device/ }).click();
+  await expect(page.getByTestId("host-page-pair-device-card")).toBeVisible();
+}
+
+export async function expectRelayConsent(page: Page): Promise<void> {
+  const modal = page.getByTestId("host-page-pair-device-card");
+  await expect(modal.getByText("Enable relay?", { exact: true })).toBeVisible();
+  await expect(modal.getByText(/end-to-end encrypted/)).toBeVisible();
+  await expect(modal.getByRole("link", { name: "Read how Paseo relay works" })).toBeVisible();
+  await expect(modal.getByText(/TCP, Tailscale, or another VPN/)).toBeVisible();
+  await expect(modal.getByRole("img", { name: "Pairing QR code" })).toHaveCount(0);
+  await expect(modal.getByRole("textbox", { name: "Pairing link" })).toHaveCount(0);
+  await expect(modal.getByRole("button", { name: "Copy", exact: true })).toHaveCount(0);
+}
+
+export async function declineRelay(page: Page): Promise<void> {
+  await page.getByRole("button", { name: "Not now", exact: true }).click();
+  await expect(page.getByTestId("host-page-pair-device-card")).toHaveCount(0);
+}
+
+export async function enableRelayAndExpectOffer(page: Page): Promise<void> {
+  const enableButton = page.getByRole("button", { name: "Enable relay", exact: true });
+  await enableButton.click();
+  await expect(page.getByRole("button", { name: "Enabling...", exact: true })).toBeDisabled();
+  await expect(page.getByRole("img", { name: "Pairing QR code" })).toBeVisible();
+  await expect(page.getByRole("textbox", { name: "Pairing link" })).toHaveValue(/#offer=/);
+  await expect(page.getByText("Enable relay?", { exact: true })).toHaveCount(0);
+}
+
+export async function expectPairingOffer(page: Page): Promise<void> {
+  await expect(page.getByRole("img", { name: "Pairing QR code" })).toBeVisible();
+  await expect(page.getByRole("textbox", { name: "Pairing link" })).toHaveValue(/#offer=/);
+  await expect(page.getByRole("button", { name: "Copy", exact: true })).toBeVisible();
+  await expect(page.getByRole("button", { name: "Enable relay", exact: true })).toHaveCount(0);
+}
+
+export async function closePairDeviceModal(page: Page): Promise<void> {
+  await page
+    .getByTestId("host-page-pair-device-card")
+    .getByRole("button", { name: "Close", exact: true })
+    .click();
+  await expect(page.getByTestId("host-page-pair-device-card")).toHaveCount(0);
+}
+
+export async function reloadAndOpenPairDevice(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    const nonce = localStorage.getItem("@paseo:e2e-seed-nonce");
+    if (!nonce) throw new Error("Expected e2e seed nonce");
+    localStorage.setItem("@paseo:e2e-disable-default-seed-once", nonce);
+  });
+  await page.reload();
+  await openPairDeviceModal(page);
+}
+
+export async function enableRelayAndExpectFailure(
+  page: Page,
+  expectedError = "Relay is controlled by a daemon launch override",
+): Promise<void> {
+  await page.getByRole("button", { name: "Enable relay", exact: true }).click();
+  const modal = page.getByTestId("host-page-pair-device-card");
+  await expect(modal.getByRole("alert")).toContainText(expectedError);
+  await expect(modal.getByRole("button", { name: "Retry", exact: true })).toBeEnabled();
+  await expect(modal.getByRole("textbox", { name: "Pairing link" })).toHaveCount(0);
+}
+
+export async function retryRelayAndExpectFailure(
+  page: Page,
+  expectedError = "Relay is controlled by a daemon launch override",
+): Promise<void> {
+  const modal = page.getByTestId("host-page-pair-device-card");
+  await modal.getByRole("button", { name: "Retry", exact: true }).click();
+  await expect(modal.getByRole("alert")).toContainText(expectedError);
+  await expect(modal.getByRole("button", { name: "Retry", exact: true })).toBeEnabled();
+}
+
+export async function openPairDeviceFromHome(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    const nonce = localStorage.getItem("@paseo:e2e-seed-nonce");
+    if (!nonce) throw new Error("Expected e2e seed nonce");
+    localStorage.setItem("@paseo:e2e-disable-default-seed-once", nonce);
+  });
+  await page.goto("/open-project");
+  await page.getByTestId("open-project-pair-device").click();
+  await expect(page.getByTestId("open-project-pair-device-modal")).toBeVisible();
+}
+
+export async function expectRelayUpdateRequired(page: Page): Promise<void> {
+  const modal = page.getByTestId("host-page-pair-device-card");
+  await expect(
+    modal.getByText("Update the host to enable relay from Paseo Desktop."),
+  ).toBeVisible();
+  await expect(modal.getByRole("button", { name: "Enable relay", exact: true })).toHaveCount(0);
+  await expect(modal.getByRole("textbox", { name: "Pairing link" })).toHaveCount(0);
+}
+
+export function observePairingOfferRequests(page: Page, daemon: OutdatedDaemon): () => void {
+  let requestCount = 0;
+  const port = daemon.endpoint.slice(daemon.endpoint.lastIndexOf(":") + 1);
+  page.on("websocket", (socket) => {
+    if (!socket.url().includes(`:${port}`)) return;
+    socket.on("framesent", ({ payload }) => {
+      const message = typeof payload === "string" ? payload : payload.toString();
+      if (message.includes('"type":"daemon.get_pairing_offer.request"')) requestCount += 1;
+    });
+  });
+  return () => expect(requestCount).toBe(0);
+}
+
+export async function expectPairingDisconnected(page: Page): Promise<void> {
+  const modal = page.getByTestId("host-page-pair-device-card");
+  await expect(modal.getByRole("alert")).toContainText("Host is not connected");
+  await expect(modal.getByRole("button", { name: "Retry", exact: true })).toBeVisible();
+}
+
+export async function switchPairDeviceToHost(page: Page, serverId: string): Promise<void> {
+  await selectSettingsHost(page, serverId);
+  await expectAppRoute(page, buildSettingsHostSectionRoute(serverId, "pair-device"));
+  await expect(page.getByTestId("host-page-pair-device-row")).toBeVisible();
+}
+
+export async function openRelaySecurityDocs(page: Page): Promise<void> {
+  await page.getByRole("link", { name: "Read how Paseo relay works" }).click();
+  await expect
+    .poll(() => page.evaluate(() => localStorage.getItem("@paseo:e2e-opened-url")))
+    .toBe("https://paseo.sh/docs/security");
+}
+
+export function expectDaemonPidUnchanged(
+  before: number | undefined,
+  after: number | undefined,
+): void {
+  expect(before).toBeDefined();
+  expect(after).toBe(before);
+}

packages/app/e2e/support/helpers/paseo-home-fork.ts

@@ -0,0 +1,131 @@
+import { existsSync } from "node:fs";
+import { copyFile, mkdir, readdir, rm, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+
+export interface PaseoHomeMetadataForkResult {
+  sourceHome: string;
+  targetHome: string;
+  agentFiles: number;
+  agentBytes: number;
+  projectFiles: number;
+  projectBytes: number;
+  copiedFiles: number;
+  copiedBytes: number;
+  skippedMissing: string[];
+}
+
+interface CopyStats {
+  files: number;
+  bytes: number;
+  skippedMissing: string[];
+}
+
+export function resolvePaseoHomePath(value: string): string {
+  if (value === "~") {
+    return homedir();
+  }
+  if (value.startsWith("~/")) {
+    return path.join(homedir(), value.slice(2));
+  }
+  return path.resolve(value);
+}
+
+async function copyJsonTree(sourceDir: string, targetDir: string): Promise<CopyStats> {
+  if (!existsSync(sourceDir)) {
+    return { files: 0, bytes: 0, skippedMissing: [sourceDir] };
+  }
+
+  const stats: CopyStats = { files: 0, bytes: 0, skippedMissing: [] };
+  const entries = await readdir(sourceDir, { withFileTypes: true });
+  await mkdir(targetDir, { recursive: true });
+
+  for (const entry of entries) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+
+    if (entry.isDirectory()) {
+      const nested = await copyJsonTree(sourcePath, targetPath);
+      stats.files += nested.files;
+      stats.bytes += nested.bytes;
+      stats.skippedMissing.push(...nested.skippedMissing);
+      continue;
+    }
+
+    if (!entry.isFile() || !entry.name.endsWith(".json")) {
+      continue;
+    }
+
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await copyFile(sourcePath, targetPath);
+    const fileStat = await stat(sourcePath);
+    stats.files += 1;
+    stats.bytes += fileStat.size;
+  }
+
+  return stats;
+}
+
+async function copyProjectRegistryFiles(
+  sourceHome: string,
+  targetHome: string,
+): Promise<CopyStats> {
+  const stats: CopyStats = { files: 0, bytes: 0, skippedMissing: [] };
+  const sourceProjectsDir = path.join(sourceHome, "projects");
+  const targetProjectsDir = path.join(targetHome, "projects");
+  await mkdir(targetProjectsDir, { recursive: true });
+
+  for (const fileName of ["projects.json", "workspaces.json"]) {
+    const sourcePath = path.join(sourceProjectsDir, fileName);
+    const targetPath = path.join(targetProjectsDir, fileName);
+    if (!existsSync(sourcePath)) {
+      stats.skippedMissing.push(sourcePath);
+      continue;
+    }
+    await copyFile(sourcePath, targetPath);
+    const fileStat = await stat(sourcePath);
+    stats.files += 1;
+    stats.bytes += fileStat.size;
+  }
+
+  return stats;
+}
+
+export async function forkPaseoHomeMetadata(input: {
+  sourceHome: string;
+  targetHome: string;
+}): Promise<PaseoHomeMetadataForkResult> {
+  const sourceHome = resolvePaseoHomePath(input.sourceHome);
+  const targetHome = resolvePaseoHomePath(input.targetHome);
+
+  if (sourceHome === targetHome) {
+    throw new Error("Refusing to fork Paseo metadata onto the same PASEO_HOME.");
+  }
+
+  await mkdir(targetHome, { recursive: true });
+
+  // Reset only the copied metadata surface. In particular, do not copy or remove
+  // worktrees here: forked workspace records should continue to point at the
+  // original checkout/worktree paths from the source home.
+  await rm(path.join(targetHome, "agents"), { recursive: true, force: true });
+  await rm(path.join(targetHome, "projects", "projects.json"), { force: true });
+  await rm(path.join(targetHome, "projects", "workspaces.json"), { force: true });
+
+  const agents = await copyJsonTree(
+    path.join(sourceHome, "agents"),
+    path.join(targetHome, "agents"),
+  );
+  const projects = await copyProjectRegistryFiles(sourceHome, targetHome);
+
+  return {
+    sourceHome,
+    targetHome,
+    agentFiles: agents.files,
+    agentBytes: agents.bytes,
+    projectFiles: projects.files,
+    projectBytes: projects.bytes,
+    copiedFiles: agents.files + projects.files,
+    copiedBytes: agents.bytes + projects.bytes,
+    skippedMissing: [...agents.skippedMissing, ...projects.skippedMissing],
+  };
+}

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

@@ -0,0 +1,17 @@
+import { expect, type Page } from "@playwright/test";
+
+export async function waitForPermissionPrompt(page: Page, timeout = 30_000): Promise<void> {
+  await expect(page.getByTestId("permission-request-question").first()).toBeVisible({ timeout });
+}
+
+export async function allowPermission(page: Page): Promise<void> {
+  const acceptButton = page.getByTestId("permission-request-accept").first();
+  await expect(acceptButton).toBeVisible({ timeout: 5_000 });
+  await acceptButton.click();
+}
+
+export async function denyPermission(page: Page): Promise<void> {
+  const denyButton = page.getByTestId("permission-request-deny").first();
+  await expect(denyButton).toBeVisible({ timeout: 5_000 });
+  await denyButton.click();
+}

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

@@ -0,0 +1,45 @@
+import { expect, type Page } from "@playwright/test";
+import type { PinnedTabTarget } from "../../../src/workspace-pins/target";
+import { pinnedTargetKey } from "../../../src/workspace-pins/target";
+
+// The new-tab dropdown menu items carry no stable web ARIA role for the inline
+// pin toggle (it lives inside a reveal-on-hover slot), so the pins flow is
+// addressed through the test ids the feature assigns per target key — the same
+// escape-hatch convention the sidebar kebab and tab context menus use.
+
+function pinToggle(page: Page, target: PinnedTabTarget) {
+  return page.getByTestId(`workspace-pin-toggle-${pinnedTargetKey(target)}`);
+}
+
+function menuItemFor(page: Page, target: PinnedTabTarget) {
+  if (target.kind === "draft") {
+    return page.getByTestId("workspace-new-tab-menu-agent");
+  }
+  return page.getByTestId(`workspace-new-tab-menu-${target.kind}`);
+}
+
+export function tabRowPin(page: Page, target: PinnedTabTarget) {
+  return page.getByTestId(`workspace-pinned-target-${pinnedTargetKey(target)}`);
+}
+
+export async function openNewTabMenu(page: Page): Promise<void> {
+  const trigger = page
+    .getByTestId("workspace-new-tab-menu-trigger")
+    .filter({ visible: true })
+    .first();
+  await expect(trigger).toBeVisible({ timeout: 10_000 });
+  await trigger.click();
+}
+
+// The pin toggle is hidden behind reveal-on-hover (opacity + pointerEvents) on
+// desktop web, so the menu item must be hovered before the toggle is clickable.
+export async function togglePinFromMenu(page: Page, target: PinnedTabTarget): Promise<void> {
+  await openNewTabMenu(page);
+  const item = menuItemFor(page, target);
+  await expect(item).toBeVisible({ timeout: 10_000 });
+  await item.hover();
+  const toggle = pinToggle(page, target);
+  await expect(toggle).toBeVisible({ timeout: 10_000 });
+  await toggle.click();
+  await page.keyboard.press("Escape");
+}

packages/app/e2e/support/helpers/pr-pane.ts

@@ -0,0 +1,42 @@
+import { expect, type Page } from "@playwright/test";
+import { getStateLabel } from "@/git/pull-request-panel/data";
+
+export async function openPrPane(page: Page): Promise<void> {
+  await page.getByRole("button", { name: "Open explorer" }).click();
+  await page.getByTestId("explorer-tab-pr").click();
+  await expect(page.getByTestId("pr-pane")).toBeVisible({ timeout: 15_000 });
+}
+
+export async function expectPrPaneTitle(page: Page, title: string): Promise<void> {
+  await expect(page.getByTestId("pr-pane-title")).toContainText(title, { timeout: 15_000 });
+}
+
+export async function expectPrPaneState(
+  page: Page,
+  state: "open" | "merged" | "closed" | "draft",
+): Promise<void> {
+  await expect(page.getByTestId("pr-pane-state")).toHaveText(getStateLabel(state), {
+    timeout: 15_000,
+  });
+}
+
+async function assertCheckPill(page: Page, testId: string, count: number): Promise<void> {
+  const locator = page.getByTestId(testId);
+  await expect(locator).toHaveCount(count > 0 ? 1 : 0, { timeout: 15_000 });
+  if (count > 0) {
+    await expect(locator).toContainText(String(count));
+  }
+}
+
+export async function expectPrPaneCheckSummary(
+  page: Page,
+  counts: { passed: number; failed: number; pending: number },
+): Promise<void> {
+  await assertCheckPill(page, "pr-pane-check-passed", counts.passed);
+  await assertCheckPill(page, "pr-pane-check-failed", counts.failed);
+  await assertCheckPill(page, "pr-pane-check-pending", counts.pending);
+}
+
+export async function expectPrPaneActivityCount(page: Page, count: number): Promise<void> {
+  await expect(page.getByTestId("pr-pane-activity-row")).toHaveCount(count, { timeout: 15_000 });
+}

packages/app/e2e/support/helpers/project-grouping.ts

@@ -0,0 +1,136 @@
+import { expect, type Locator, type Page } from "@playwright/test";
+import { gotoAppShell } from "./app";
+import { addConnectedHostsAndReload, waitForConnectedHost } from "./hosts";
+import { openProjectSettings } from "./project-settings";
+import { selectSettingsHost } from "./settings";
+import { waitForSidebarHydration } from "./workspace-ui";
+import { buildProjectsSettingsRoute } from "@/utils/host-routes";
+
+const PROJECT_VISIBILITY_TIMEOUT = 30_000;
+
+function projectGroup(page: Page, projectName: string): Locator {
+  return page.getByRole("group", { name: projectName, exact: true });
+}
+
+function projectGroupWithWorkspace(
+  page: Page,
+  projectName: string,
+  workspaceName: string,
+): Locator {
+  return projectGroup(page, projectName).filter({ hasText: workspaceName });
+}
+
+export async function openProjectDirectory(page: Page): Promise<void> {
+  await gotoAppShell(page);
+  await waitForSidebarHydration(page);
+}
+
+export async function openProjectDirectoryWithHosts(
+  page: Page,
+  input: {
+    hosts: Array<{ serverId: string; label: string; port: number }>;
+    primaryLabel?: string;
+  },
+): Promise<void> {
+  await gotoAppShell(page);
+  await addConnectedHostsAndReload(page, input.hosts, { primaryLabel: input.primaryLabel });
+  for (const host of input.hosts) {
+    await waitForConnectedHost(page, {
+      serverId: host.serverId,
+      endpoint: `localhost:${host.port}`,
+    });
+  }
+  await waitForSidebarHydration(page);
+}
+
+export async function expectProjectContainsWorkspaces(
+  page: Page,
+  input: { projectName: string; workspaceNames: string[] },
+): Promise<void> {
+  const group = projectGroup(page, input.projectName);
+  await expect(group).toHaveCount(1, { timeout: PROJECT_VISIBILITY_TIMEOUT });
+  for (const workspaceName of input.workspaceNames) {
+    await expect(group.getByRole("button").filter({ hasText: workspaceName })).toBeVisible({
+      timeout: PROJECT_VISIBILITY_TIMEOUT,
+    });
+  }
+}
+
+export async function expectSeparateProjects(
+  page: Page,
+  projects: Array<{ projectName: string; workspaceName: string }>,
+): Promise<void> {
+  for (const project of projects) {
+    await expect(
+      projectGroupWithWorkspace(page, project.projectName, project.workspaceName),
+    ).toHaveCount(1, { timeout: PROJECT_VISIBILITY_TIMEOUT });
+  }
+}
+
+export async function beginWorkspaceFromProject(page: Page, projectName: string): Promise<void> {
+  const group = projectGroup(page, projectName);
+  await expect(group).toBeVisible({ timeout: PROJECT_VISIBILITY_TIMEOUT });
+  await group.hover();
+  await group.getByLabel(`Create a new workspace for ${projectName}`).click();
+  await expect(page.getByRole("button", { name: "Workspace project", exact: true })).toContainText(
+    projectName,
+    { timeout: PROJECT_VISIBILITY_TIMEOUT },
+  );
+}
+
+export async function selectWorkspaceHost(page: Page, hostName: string): Promise<void> {
+  await page.getByRole("button", { name: "Host", exact: true }).click();
+  await page.getByRole("button", { name: hostName, exact: true }).click();
+  await expect(page.getByRole("button", { name: "Host", exact: true })).toContainText(hostName);
+}
+
+export async function createWorkspaceWithoutAgent(page: Page): Promise<void> {
+  await page.getByRole("button", { name: "Create", exact: true }).click();
+}
+
+export async function expectProjectWorkspaceCountForHost(
+  page: Page,
+  input: { projectName: string; hostName: string; count: number },
+): Promise<void> {
+  const group = projectGroup(page, input.projectName);
+  await expect(group.getByRole("button").filter({ hasText: input.hostName })).toHaveCount(
+    input.count,
+    { timeout: PROJECT_VISIBILITY_TIMEOUT },
+  );
+}
+
+export async function renameProject(page: Page, name: string): Promise<void> {
+  await page.getByRole("button", { name: "Edit project", exact: true }).click();
+  await page.getByRole("textbox", { name: "Project name", exact: true }).fill(name);
+  await page.getByRole("button", { name: "Save changes", exact: true }).click();
+  await expect(page.getByText("Project updated", { exact: true })).toBeVisible({
+    timeout: PROJECT_VISIBILITY_TIMEOUT,
+  });
+}
+
+export async function openGroupedProjectSettings(
+  page: Page,
+  input: { serverId: string; projectName: string },
+): Promise<void> {
+  await page.getByRole("button", { name: "Settings", exact: true }).click();
+  await expect(page).toHaveURL(/\/settings\/general$/);
+  await selectSettingsHost(page, input.serverId);
+  await page.locator('[data-testid="settings-host-section-projects"]:visible').click();
+  await expect(page).toHaveURL(/\/settings\/hosts\/[^/]+\/projects$/);
+  await openProjectSettings(page, input.projectName);
+}
+
+export async function openProjectsForSettingsHost(
+  page: Page,
+  input: { serverId: string; projectName: string },
+): Promise<void> {
+  await selectSettingsHost(page, input.serverId);
+  await expect(page).toHaveURL(buildProjectsSettingsRoute(input.serverId));
+  await openProjectSettings(page, input.projectName);
+}
+
+export async function expectProjectSettingsName(page: Page, projectName: string): Promise<void> {
+  await expect(page.getByRole("main").getByText(projectName, { exact: true })).toBeVisible({
+    timeout: PROJECT_VISIBILITY_TIMEOUT,
+  });
+}

packages/app/e2e/support/helpers/project-ownership.ts

@@ -0,0 +1,64 @@
+interface OwnedResourceResult {
+  project?: { projectId: string } | null;
+  workspace?: { projectId: string } | null;
+}
+
+interface ProjectClient {
+  addProject?: (...args: unknown[]) => Promise<OwnedResourceResult>;
+  close(): Promise<void>;
+  createPaseoWorktree?: (...args: unknown[]) => Promise<OwnedResourceResult>;
+  createWorkspace?: (...args: unknown[]) => Promise<OwnedResourceResult>;
+  removeProject(projectId: string): Promise<unknown>;
+}
+
+/**
+ * Makes a test client own every project it creates. Closing the client removes
+ * those projects first, which also terminates their workspaces and terminals.
+ */
+export function withProjectOwnership<Client extends object>(client: Client): Client {
+  const target = client as Client & ProjectClient;
+  const projectIds = new Set<string>();
+  let closed = false;
+
+  async function trackProject(result: OwnedResourceResult) {
+    const projectId = result.project?.projectId ?? result.workspace?.projectId;
+    if (projectId) projectIds.add(projectId);
+    return result;
+  }
+
+  return new Proxy(client, {
+    get(_target, property) {
+      if (property === "addProject" && target.addProject) {
+        const addProject = target.addProject.bind(target);
+        return async (...args: unknown[]) => trackProject(await addProject(...args));
+      }
+      if (property === "createWorkspace" && target.createWorkspace) {
+        const createWorkspace = target.createWorkspace.bind(target);
+        return async (...args: unknown[]) => trackProject(await createWorkspace(...args));
+      }
+      if (property === "createPaseoWorktree" && target.createPaseoWorktree) {
+        const createPaseoWorktree = target.createPaseoWorktree.bind(target);
+        return async (...args: unknown[]) => trackProject(await createPaseoWorktree(...args));
+      }
+      if (property === "removeProject") {
+        return async (projectId: string) => {
+          const result = await target.removeProject(projectId);
+          projectIds.delete(projectId);
+          return result;
+        };
+      }
+      if (property === "close") {
+        return async () => {
+          if (closed) return;
+          closed = true;
+          for (const projectId of projectIds) {
+            await target.removeProject(projectId).catch(() => undefined);
+          }
+          await target.close();
+        };
+      }
+      const value = Reflect.get(target, property, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+}

packages/app/e2e/support/helpers/project-picker-fixture.ts

@@ -0,0 +1,48 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import type { SeedDaemonClient } from "./seed-client";
+
+export interface ProjectPickerFixture {
+  projectPath: string;
+  projectName: string;
+  fuzzyQuery: string;
+}
+
+interface ProjectPickerFixtureResource {
+  fixture: ProjectPickerFixture;
+  removeDirectory: () => Promise<void>;
+}
+
+export async function createProjectPickerFixture(): Promise<ProjectPickerFixtureResource> {
+  const root = await mkdtemp(path.join(homedir(), "paseo-e2e-project-picker-"));
+  const nonce = randomUUID().replaceAll("-", "").slice(0, 8);
+  const projectPath = path.join(root, "client", "team", `paseo-desktop-fuzzy-target-${nonce}`);
+  await mkdir(projectPath, { recursive: true });
+
+  return {
+    fixture: {
+      projectPath,
+      projectName: path.basename(projectPath),
+      fuzzyQuery: `psodfzt${nonce}`,
+    },
+    removeDirectory: () => rm(root, { recursive: true, force: true }),
+  };
+}
+
+export async function removeProjectPickerFixture(
+  client: SeedDaemonClient,
+  fixture: ProjectPickerFixture,
+  knownProjectId: string | null = null,
+): Promise<void> {
+  let projectId = knownProjectId;
+  if (!projectId) {
+    const lookup = await client.addProject(fixture.projectPath);
+    projectId = lookup.project?.projectId ?? null;
+    if (!projectId) {
+      throw new Error(lookup.error ?? "Could not resolve project picker fixture for cleanup");
+    }
+  }
+  await client.removeProject(projectId);
+}

packages/app/e2e/support/helpers/project-picker-ui.ts

@@ -0,0 +1,14 @@
+import { expect, type Page } from "@playwright/test";
+
+export async function expectOpenedProject(page: Page, projectName: string): Promise<string> {
+  const projectRow = page
+    .locator('[data-testid^="sidebar-project-row-"]')
+    .filter({ hasText: projectName })
+    .first();
+  await expect(projectRow).toBeVisible({ timeout: 30_000 });
+
+  await expect(page).toHaveURL(/\/new\?.*projectId=/u, { timeout: 30_000 });
+  const projectId = new URL(page.url()).searchParams.get("projectId");
+  expect(projectId).not.toBeNull();
+  return projectId!;
+}

packages/app/e2e/support/helpers/project-settings.ts

@@ -0,0 +1,366 @@
+import { chmod, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { expect, type Page } from "@playwright/test";
+import type { WebSocketRoute } from "@playwright/test";
+import { gotoAppShell, openSettings } from "./app";
+import { daemonWsRoutePattern } from "./daemon-port";
+import { getServerId } from "./server-id";
+import { buildProjectsSettingsRoute } from "@/utils/host-routes";
+
+type WebSocketMessage = string | Buffer;
+
+function parseWebSocketJson(message: WebSocketMessage): unknown {
+  const raw = typeof message === "string" ? message : message.toString("utf8");
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function getSessionMessage(message: WebSocketMessage): Record<string, unknown> | null {
+  const envelope = parseWebSocketJson(message);
+  if (!envelope || typeof envelope !== "object") {
+    return null;
+  }
+  const maybeEnvelope = envelope as { type?: unknown; message?: unknown };
+  if (maybeEnvelope.type !== "session" || typeof maybeEnvelope.message !== "object") {
+    return null;
+  }
+  return maybeEnvelope.message as Record<string, unknown>;
+}
+
+// --- Navigation ---
+
+export async function openProjects(page: Page): Promise<void> {
+  await gotoAppShell(page);
+  await openSettings(page);
+  await page.getByRole("button", { name: "Projects", exact: true }).click();
+  await expect(page).toHaveURL(buildProjectsSettingsRoute(getServerId()));
+}
+
+export async function openProjectSettings(page: Page, projectName: string): Promise<void> {
+  await page.getByRole("button", { name: `Edit ${projectName}`, exact: true }).click();
+  await expect(page.getByRole("textbox", { name: "Worktree setup commands" })).toBeVisible({
+    timeout: 30_000,
+  });
+}
+
+export async function navigateToProjectSettings(page: Page, projectName: string): Promise<void> {
+  await page.getByRole("button", { name: `Edit ${projectName}`, exact: true }).click();
+}
+
+export async function returnToProjectsList(page: Page): Promise<void> {
+  await page.getByRole("button", { name: "Back to projects", exact: true }).click();
+  await expect(page).toHaveURL(buildProjectsSettingsRoute(getServerId()));
+}
+
+export async function expectProjectSettingsHistoryRoundTrip(
+  page: Page,
+  projectName: string,
+): Promise<void> {
+  await page.goBack();
+  await expect(page).toHaveURL(buildProjectsSettingsRoute(getServerId()));
+  await page.goForward();
+  await expectProjectTitle(page, projectName);
+}
+
+// --- Form interactions ---
+
+export async function editWorktreeSetup(page: Page, setupCommands: string[]): Promise<void> {
+  await page
+    .getByRole("textbox", { name: "Worktree setup commands" })
+    .fill(setupCommands.join("\n"));
+}
+
+export async function clickSaveProjectSettings(page: Page): Promise<void> {
+  await page.getByTestId("save-button").click();
+}
+
+export async function clickRetryProjectSettingsSave(page: Page): Promise<void> {
+  // action-0 is always "Try again"; action-1 is always "Reload".
+  // The write-failed callout renders these two buttons in a fixed order.
+  await page.getByTestId("write-failed-callout-action-0").click();
+}
+
+export async function clickReloadProjectSettings(page: Page): Promise<void> {
+  // Scope to the active error callout so the locator is unambiguous.
+  // At most one error callout renders at a time.
+  await page.locator('[data-testid$="-callout"]').getByRole("button", { name: "Reload" }).click();
+}
+
+// --- Project edit sheet (name + icon) ---
+
+export async function openProjectEditSheet(page: Page): Promise<void> {
+  await page.getByRole("button", { name: "Edit project", exact: true }).click();
+  await expect(page.getByRole("textbox", { name: "Project name" })).toBeVisible();
+}
+
+export async function fillProjectName(page: Page, name: string): Promise<void> {
+  await page.getByRole("textbox", { name: "Project name" }).fill(name);
+}
+
+export async function chooseProjectIconImage(
+  page: Page,
+  file: { name: string; mimeType: string; buffer: Buffer },
+): Promise<void> {
+  const chooserPromise = page.waitForEvent("filechooser", { timeout: 10_000 });
+  await page.getByRole("button", { name: "Choose image" }).click();
+  await (await chooserPromise).setFiles([file]);
+  await expect(page.getByText(file.name, { exact: true })).toBeVisible();
+}
+
+export async function fillProjectIconUrl(page: Page, url: string): Promise<void> {
+  await page.getByRole("textbox", { name: "Image or website URL" }).fill(url);
+}
+
+export async function useAutomaticProjectIcon(page: Page): Promise<void> {
+  await page.getByRole("button", { name: "Use automatic" }).click();
+}
+
+export async function saveProjectEdits(page: Page): Promise<void> {
+  await page.getByRole("button", { name: "Save changes" }).click();
+}
+
+export async function expectProjectEditName(page: Page, name: string): Promise<void> {
+  await expect(page.getByRole("textbox", { name: "Project name" })).toHaveValue(name);
+}
+
+export async function expectProjectEditsSaveDisabled(page: Page): Promise<void> {
+  await expect(page.getByRole("button", { name: "Save changes" })).toBeDisabled();
+}
+
+export async function expectProjectEditSaved(page: Page): Promise<void> {
+  await expect(page.getByTestId("app-toast-message")).toHaveText("Project updated");
+}
+
+// The sheet keeps the user's input on a failed save so the value stays editable.
+export async function expectProjectEditFailed(page: Page, detail: string): Promise<void> {
+  await expect(page.getByText(detail, { exact: true })).toBeVisible();
+  await expect(page.getByRole("textbox", { name: "Project name" })).toBeVisible();
+}
+
+export async function expectProjectTitle(page: Page, projectName: string): Promise<void> {
+  await expect(page.getByRole("main").getByText(projectName, { exact: true })).toBeVisible();
+}
+
+// --- Error-state assertions ---
+
+type ErrorKind = "stale" | "invalid" | "write_failed" | "transport" | "read_failed";
+
+const errorCalloutTestId: Record<ErrorKind, string> = {
+  stale: "stale-callout",
+  invalid: "invalid-callout",
+  write_failed: "write-failed-callout",
+  transport: "read-transport-callout",
+  read_failed: "read-failed-callout",
+};
+
+export async function expectProjectSettingsError(page: Page, kind: ErrorKind): Promise<void> {
+  await expect(page.getByTestId(errorCalloutTestId[kind])).toBeVisible({ timeout: 15_000 });
+}
+
+export async function expectNoProjectSettingsError(
+  page: Page,
+  kind: ErrorKind,
+  timeout = 15_000,
+): Promise<void> {
+  await expect(page.getByTestId(errorCalloutTestId[kind])).not.toBeVisible({ timeout });
+}
+
+export async function expectWriteFailedCalloutActions(page: Page): Promise<void> {
+  await expect(page.getByTestId("write-failed-callout-action-0")).toHaveText("Try again");
+  await expect(page.getByTestId("write-failed-callout-action-1")).toHaveText("Reload");
+}
+
+export async function expectSaveButtonDisabled(page: Page): Promise<void> {
+  await expect(page.getByTestId("save-button")).toBeDisabled();
+}
+
+// --- Form-state assertions ---
+
+export async function expectProjectSettingsFormVisible(page: Page): Promise<void> {
+  await expect(page.getByRole("textbox", { name: "Worktree setup commands" })).toBeVisible({
+    timeout: 15_000,
+  });
+}
+
+export async function expectProjectSettingsFormHidden(page: Page): Promise<void> {
+  await expect(page.getByRole("textbox", { name: "Worktree setup commands" })).not.toBeVisible();
+}
+
+export async function expectNoEditableTarget(page: Page): Promise<void> {
+  await expect(page.getByTestId("project-settings-back-button")).toBeVisible({ timeout: 30_000 });
+}
+
+export async function expectProjectHostContextHidden(page: Page): Promise<void> {
+  await expect(page.getByTestId("host-indicator")).not.toBeVisible();
+  await expect(page.getByTestId("host-picker")).not.toBeVisible();
+}
+
+// --- Script-list assertions and interactions ---
+
+// Counts only row Views, not kebab-trigger elements (which share the "script-row-"
+// prefix but contain "-menu-").
+export async function expectScriptRowCount(page: Page, count: number): Promise<void> {
+  await expect(
+    page
+      .getByTestId("scripts-list")
+      .locator('[data-testid^="script-row-"]:not([data-testid*="-menu-"])'),
+  ).toHaveCount(count);
+}
+
+export async function expectEmptyScriptList(page: Page): Promise<void> {
+  await expect(page.getByText("No scripts yet.")).toBeVisible();
+}
+
+export async function removeProjectScript(page: Page, scriptName: string): Promise<void> {
+  const row = page
+    .getByTestId("scripts-list")
+    .locator('[data-testid^="script-row-"]:not([data-testid*="-menu-"])')
+    .filter({ hasText: scriptName })
+    .first();
+  // DropdownMenuTrigger renders as a Pressable (no role="button"); derive its testID
+  // from the row's testID to avoid scoped locator unreliability.
+  const id = (await row.getAttribute("data-testid"))!.replace("script-row-", "");
+  await page.getByTestId(`script-row-menu-${id}`).click();
+  page.once("dialog", (dialog) => void dialog.accept());
+  await page.getByRole("button", { name: "Remove" }).click();
+}
+
+// --- File manipulation ---
+
+export async function corruptPaseoConfig(repoPath: string): Promise<void> {
+  await writeFile(path.join(repoPath, "paseo.json"), "{not valid json}");
+}
+
+export async function bumpPaseoConfigOnDisk(repoPath: string): Promise<void> {
+  const configPath = path.join(repoPath, "paseo.json");
+  const raw = await readFile(configPath, "utf8");
+  const config = JSON.parse(raw) as Record<string, unknown>;
+  config._bump = Date.now();
+  await writeFile(configPath, JSON.stringify(config, null, 2) + "\n");
+}
+
+export async function restorePaseoConfig(
+  repoPath: string,
+  config: Record<string, unknown>,
+): Promise<void> {
+  await writeFile(path.join(repoPath, "paseo.json"), JSON.stringify(config, null, 2) + "\n");
+}
+
+// The daemon writes atomically via a temp file + rename, so blocking writes requires
+// removing write permission from the *directory*, not just the file.
+export async function blockPaseoConfigWrites(repoPath: string): Promise<void> {
+  await chmod(repoPath, 0o555);
+}
+
+export async function unblockPaseoConfigWrites(repoPath: string): Promise<void> {
+  await chmod(repoPath, 0o755);
+}
+
+// --- WebSocket helpers ---
+
+// Proxies all daemon WS traffic transparently, but rejects paseo.json reads
+// until the test explicitly allows recovery. Closing the transport leaves the
+// client-side RPC pending across reconnects, so this injects the same correlated
+// rpc_error shape the daemon emits for failed async session requests.
+export async function installReadTransportFailure(
+  page: Page,
+): Promise<{ allowRecovery: () => void }> {
+  let shouldFailReads = true;
+
+  await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
+    const server = ws.connectToServer();
+
+    ws.onMessage((message) => {
+      const sessionMessage = getSessionMessage(message);
+      if (shouldFailReads && sessionMessage?.type === "read_project_config_request") {
+        const requestId = sessionMessage.requestId;
+        if (typeof requestId === "string") {
+          ws.send(
+            JSON.stringify({
+              type: "session",
+              message: {
+                type: "rpc_error",
+                payload: {
+                  requestId,
+                  requestType: "read_project_config_request",
+                  error: "Test read transport failure.",
+                  code: "transport",
+                },
+              },
+            }),
+          );
+        }
+        return;
+      }
+      try {
+        server.send(message);
+      } catch {
+        // server socket already closed
+      }
+    });
+
+    server.onMessage((message) => {
+      try {
+        ws.send(message);
+      } catch {
+        // client socket already closed
+      }
+    });
+  });
+
+  return {
+    allowRecovery() {
+      shouldFailReads = false;
+    },
+  };
+}
+
+// Installs a transparent WS proxy that can later drop all active daemon connections
+// and block new ones. Code 1001 (Going Away) without reason triggers "error" state
+// in DaemonClient due to describeTransportClose returning a non-empty string.
+export async function installDaemonConnectionGate(
+  page: Page,
+): Promise<{ drop: () => Promise<void> }> {
+  let acceptingConnections = true;
+  const activeSockets = new Set<WebSocketRoute>();
+
+  await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
+    if (!acceptingConnections) {
+      void ws.close({ code: 1001 });
+      return;
+    }
+
+    activeSockets.add(ws);
+    const server = ws.connectToServer();
+
+    ws.onMessage((message) => {
+      if (!acceptingConnections) return;
+      try {
+        server.send(message);
+      } catch {
+        activeSockets.delete(ws);
+      }
+    });
+
+    server.onMessage((message) => {
+      if (!acceptingConnections) return;
+      try {
+        ws.send(message);
+      } catch {
+        activeSockets.delete(ws);
+      }
+    });
+  });
+
+  return {
+    async drop(): Promise<void> {
+      acceptingConnections = false;
+      const sockets = Array.from(activeSockets);
+      activeSockets.clear();
+      await Promise.all(sockets.map((ws) => ws.close({ code: 1001 }).catch(() => undefined)));
+    },
+  };
+}

packages/app/e2e/support/helpers/project-view-key.ts

@@ -0,0 +1,7 @@
+export function projectEquivalenceViewKey(projectKey: string): string {
+  return projectKey;
+}
+
+export function projectPlacementViewKey(serverId: string, projectId: string): string {
+  return JSON.stringify([serverId, projectId]);
+}

packages/app/e2e/support/helpers/provider-usage.ts

@@ -0,0 +1,154 @@
+import type { Page } from "@playwright/test";
+import type { ProviderUsage } from "@getpaseo/protocol/messages";
+import { daemonWsRoutePattern } from "./daemon-port";
+
+interface ProviderUsageFixturePayload {
+  fetchedAt: string;
+  providers: ProviderUsage[];
+}
+
+export interface ProviderUsageFixture {
+  requestCount(): number;
+  waitForRequestCount(count: number): Promise<void>;
+}
+
+type WebSocketMessage = string | Buffer;
+
+function parseJson(message: WebSocketMessage): unknown {
+  const raw = typeof message === "string" ? message : message.toString("utf8");
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function getSessionMessage(message: WebSocketMessage): Record<string, unknown> | null {
+  const envelope = parseJson(message);
+  if (!envelope || typeof envelope !== "object") {
+    return null;
+  }
+  const maybeEnvelope = envelope as { type?: unknown; message?: unknown };
+  if (maybeEnvelope.type !== "session" || !maybeEnvelope.message) {
+    return null;
+  }
+  if (typeof maybeEnvelope.message !== "object") {
+    return null;
+  }
+  return maybeEnvelope.message as Record<string, unknown>;
+}
+
+function withProviderUsageFeature(message: WebSocketMessage): string | null {
+  const envelope = parseJson(message);
+  if (!envelope || typeof envelope !== "object") {
+    return null;
+  }
+  const maybeEnvelope = envelope as {
+    type?: unknown;
+    message?: {
+      type?: unknown;
+      payload?: Record<string, unknown>;
+    };
+  };
+  const payload = maybeEnvelope.message?.payload;
+  if (
+    maybeEnvelope.type !== "session" ||
+    maybeEnvelope.message?.type !== "status" ||
+    payload?.status !== "server_info"
+  ) {
+    return null;
+  }
+  return JSON.stringify({
+    ...maybeEnvelope,
+    message: {
+      ...maybeEnvelope.message,
+      payload: {
+        ...payload,
+        features: {
+          ...(typeof payload.features === "object" && payload.features !== null
+            ? payload.features
+            : {}),
+          providerUsageList: true,
+        },
+      },
+    },
+  });
+}
+
+export async function installProviderUsageFixture(
+  page: Page,
+  payloads: ProviderUsageFixturePayload[],
+): Promise<ProviderUsageFixture> {
+  let requests = 0;
+  const waiters: Array<{ count: number; resolve: () => void }> = [];
+
+  function notifyWaiters() {
+    for (const waiter of waiters.splice(0)) {
+      if (requests >= waiter.count) {
+        waiter.resolve();
+      } else {
+        waiters.push(waiter);
+      }
+    }
+  }
+
+  function payloadForRequest(): ProviderUsageFixturePayload {
+    const index = Math.min(requests - 1, payloads.length - 1);
+    const payload = payloads[index];
+    if (!payload) {
+      throw new Error("Provider usage fixture requires at least one payload.");
+    }
+    return payload;
+  }
+
+  await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
+    const server = ws.connectToServer();
+
+    ws.onMessage((message) => {
+      const sessionMessage = getSessionMessage(message);
+      if (sessionMessage?.type === "provider.usage.list.request") {
+        requests += 1;
+        const requestId = sessionMessage.requestId;
+        if (typeof requestId !== "string") {
+          throw new Error("provider.usage.list.request missing requestId");
+        }
+        const payload = payloadForRequest();
+        notifyWaiters();
+        ws.send(
+          JSON.stringify({
+            type: "session",
+            message: {
+              type: "provider.usage.list.response",
+              payload: {
+                requestId,
+                fetchedAt: payload.fetchedAt,
+                providers: payload.providers,
+              },
+            },
+          }),
+        );
+        return;
+      }
+      server.send(message);
+    });
+
+    server.onMessage((message) => {
+      const serverInfo = typeof message === "string" ? withProviderUsageFeature(message) : null;
+      ws.send(serverInfo ?? message);
+    });
+  });
+
+  return {
+    requestCount() {
+      return requests;
+    },
+    waitForRequestCount(count: number) {
+      if (requests >= count) {
+        return Promise.resolve();
+      }
+      return new Promise<void>((resolve) => {
+        waiters.push({ count, resolve });
+      });
+    },
+  };
+}

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

@@ -0,0 +1,103 @@
+import { expect, type Page } from "@playwright/test";
+
+export async function waitForQuestionPrompt(page: Page, timeout = 30_000): Promise<void> {
+  await expect(page.getByTestId("question-form-card").first()).toBeVisible({ timeout });
+}
+
+export async function expectCurrentQuestion(
+  page: Page,
+  input: { index: number; total: number; question: string },
+): Promise<void> {
+  const card = page.getByTestId("question-form-card").first();
+  await expect(card.getByTestId("question-form-current-question")).toHaveText(input.question);
+  // Nav tabs only render for multi-question cards (hidden for a lone question).
+  if (input.total > 1) {
+    await expect(questionNavTab(page, input)).toHaveAttribute("aria-selected", "true");
+  }
+}
+
+export async function expectQuestionHidden(page: Page, question: string): Promise<void> {
+  await expect(page.getByText(question, { exact: true })).toHaveCount(0);
+}
+
+// Options render as radios (single-select) or checkboxes (multi-select), so match
+// either role by accessible name.
+function questionOption(page: Page, option: string) {
+  const card = page.getByTestId("question-form-card").first();
+  return card.getByRole("radio", { name: option }).or(card.getByRole("checkbox", { name: option }));
+}
+
+// The multi-question nav renders as a tablist; each question is a tab.
+function questionNavTab(page: Page, input: { index: number; total: number }) {
+  return page
+    .getByTestId("question-form-card")
+    .first()
+    .getByRole("tab", { name: `Question ${input.index} of ${input.total}` });
+}
+
+export async function chooseQuestionOption(page: Page, option: string): Promise<void> {
+  await questionOption(page, option).click();
+}
+
+export async function expectQuestionOptionSelected(page: Page, option: string): Promise<void> {
+  await expect(questionOption(page, option)).toHaveAttribute("aria-checked", "true");
+}
+
+export async function openQuestion(
+  page: Page,
+  input: { index: number; total: number },
+): Promise<void> {
+  await questionNavTab(page, input).click();
+}
+
+export async function expectQuestionNavigationEnabled(
+  page: Page,
+  input: { index: number; total: number },
+): Promise<void> {
+  await expect(questionNavTab(page, input)).toBeEnabled();
+}
+
+export async function fillQuestionAnswer(
+  page: Page,
+  input: { question: string; answer: string },
+): Promise<void> {
+  await page
+    .getByTestId("question-form-card")
+    .first()
+    .getByRole("textbox", { name: input.question })
+    .fill(input.answer);
+}
+
+export async function submitQuestionAnswers(page: Page): Promise<void> {
+  await page.getByTestId("question-form-primary-action").click();
+  await expect(page.getByTestId("question-form-card")).toHaveCount(0, { timeout: 30_000 });
+}
+
+export async function expectQuestionPrimaryActionEnabled(page: Page, label: string): Promise<void> {
+  await expect(
+    page.getByTestId("question-form-card").first().getByRole("button", { name: label }),
+  ).toBeEnabled();
+}
+
+export async function expectQuestionPrimaryActionDisabled(
+  page: Page,
+  label: string,
+): Promise<void> {
+  await expect(
+    page.getByTestId("question-form-card").first().getByRole("button", { name: label }),
+  ).toBeDisabled();
+}
+
+export async function expectQuestionDismissEnabled(page: Page): Promise<void> {
+  await expect(
+    page.getByTestId("question-form-card").first().getByRole("button", { name: "Dismiss" }),
+  ).toBeEnabled();
+}
+
+export async function continueToNextQuestion(page: Page): Promise<void> {
+  await page
+    .getByTestId("question-form-card")
+    .first()
+    .getByRole("button", { name: "Next" })
+    .click();
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Escape a literal string so it can be embedded safely inside a `RegExp`.
+ * Used across the suite to build dynamic patterns from daemon ports, URLs,
+ * workspace routes, and user-visible text without regex injection.
+ */
+export function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

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

@@ -0,0 +1,13 @@
+import { type Page } from "@playwright/test";
+
+export function renameModalInput(page: Page, testIdPrefix: string) {
+  return page.getByTestId(`${testIdPrefix}-input`);
+}
+
+export function renameModalSubmit(page: Page, testIdPrefix: string) {
+  return page.getByTestId(`${testIdPrefix}-submit`);
+}
+
+export function renameModalError(page: Page, testIdPrefix: string) {
+  return page.getByTestId(`${testIdPrefix}-error`);
+}

packages/app/e2e/support/helpers/rewind-flow.ts

@@ -0,0 +1,357 @@
+import { randomUUID } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { expect, type Page } from "@playwright/test";
+import { buildHostWorkspaceRoute } from "@/utils/host-routes";
+import { expectComposerEditable, submitMessage } from "./composer";
+import { connectSeedClient, type SeedDaemonClient } from "./seed-client";
+import { getServerId } from "./server-id";
+
+export type RewindFlowProvider = "claude" | "codex" | "opencode" | "pi";
+export type RewindFlowMode = "conversation" | "files" | "both";
+
+export interface AgentHandle {
+  page: Page;
+  client: SeedDaemonClient;
+  agentId: string;
+  projectId: string;
+  workspaceId: string;
+  cwd: string;
+  provider: RewindFlowProvider;
+}
+
+export interface TranscriptMessage {
+  role: "user" | "assistant";
+  text: string | RegExp;
+}
+
+interface ProviderLaunchConfig {
+  provider: RewindFlowProvider;
+  model?: string;
+  thinkingOptionId?: string;
+  modeId?: string;
+  featureValues?: Record<string, unknown>;
+}
+
+const SEND_TIMEOUT_MS = 240_000;
+const REWIND_TIMEOUT_MS = 120_000;
+
+function fullAccessConfig(provider: RewindFlowProvider): ProviderLaunchConfig {
+  switch (provider) {
+    case "claude":
+      return { provider, model: "haiku", modeId: "bypassPermissions" };
+    case "codex":
+      return {
+        provider,
+        model: "gpt-5.4-mini",
+        thinkingOptionId: "low",
+        modeId: "full-access",
+      };
+    case "opencode":
+      return {
+        provider,
+        model: "opencode/big-pickle",
+        modeId: "build",
+        featureValues: { auto_accept: true },
+      };
+    case "pi":
+      return {
+        provider,
+        model: "openrouter/google/gemini-2.5-flash-lite",
+        thinkingOptionId: "medium",
+      };
+  }
+}
+
+function agentRoute(workspaceId: string, agentId: string): string {
+  return `${buildHostWorkspaceRoute(getServerId(), workspaceId)}?open=${encodeURIComponent(
+    `agent:${agentId}`,
+  )}`;
+}
+
+async function openAgent(
+  page: Page,
+  input: { workspaceId: string; agentId: string },
+): Promise<void> {
+  await page.goto(agentRoute(input.workspaceId, input.agentId));
+  await page.waitForURL(
+    (url) => url.pathname.includes("/workspace/") && !url.searchParams.has("open"),
+    { timeout: 60_000 },
+  );
+  await assertComposerIdle({ page });
+}
+
+function visibleChatMessages(page: Page) {
+  return page
+    .locator('[data-testid="agent-chat-scroll"]:visible')
+    .first()
+    .locator('[data-testid="user-message"], [data-testid="assistant-message"]');
+}
+
+async function transcript(
+  page: Page,
+): Promise<Array<{ role: "user" | "assistant"; text: string }>> {
+  const rawMessages = await visibleChatMessages(page).evaluateAll((elements) =>
+    elements.map((element) => ({
+      role: (element.getAttribute("data-testid") === "user-message" ? "user" : "assistant") as
+        | "user"
+        | "assistant",
+      text: (element.textContent ?? "")
+        .replace(/\s+/g, " ")
+        .replace(/\d{1,2}:\d{2}\s?(?:AM|PM)$/u, "")
+        .trim(),
+    })),
+  );
+
+  return coalesceAssistantTurnSegments(rawMessages);
+}
+
+function coalesceAssistantTurnSegments(
+  messages: Array<{ role: "user" | "assistant"; text: string }>,
+): Array<{ role: "user" | "assistant"; text: string }> {
+  const transcriptMessages: Array<{ role: "user" | "assistant"; text: string }> = [];
+
+  for (const message of messages) {
+    const previous = transcriptMessages.at(-1);
+    if (message.role === "assistant" && previous?.role === "assistant") {
+      const joinedText =
+        previous.text && message.text
+          ? `${previous.text}\n${message.text}`
+          : previous.text || message.text;
+      transcriptMessages[transcriptMessages.length - 1] = {
+        role: "assistant",
+        text: joinedText,
+      };
+      continue;
+    }
+
+    transcriptMessages.push(message);
+  }
+
+  return transcriptMessages.filter(
+    (message) => message.role !== "assistant" || message.text.length > 0,
+  );
+}
+
+function expectedTextMatches(actual: string, expected: string | RegExp): boolean {
+  if (typeof expected === "string") {
+    return actual === expected;
+  }
+  return expected.test(actual);
+}
+
+function formatExpectedMessage(message: TranscriptMessage): string {
+  const text = typeof message.text === "string" ? JSON.stringify(message.text) : message.text;
+  return `${message.role}:${text}`;
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+
+export async function launchAgent(input: {
+  page: Page;
+  provider: RewindFlowProvider;
+  cwd: string;
+  mode: "full-access";
+  providerConfig?: {
+    model?: string;
+    extra?: { codex?: { features?: { multi_agent_v2?: boolean } } };
+  };
+}): Promise<AgentHandle> {
+  execFileSync("git", ["init", "-b", "main"], { cwd: input.cwd, stdio: "ignore" });
+  execFileSync("git", ["config", "user.email", "paseo-test@example.com"], {
+    cwd: input.cwd,
+    stdio: "ignore",
+  });
+  execFileSync("git", ["config", "user.name", "Paseo Test"], {
+    cwd: input.cwd,
+    stdio: "ignore",
+  });
+  execFileSync("git", ["config", "commit.gpgsign", "false"], {
+    cwd: input.cwd,
+    stdio: "ignore",
+  });
+  writeFileSync(`${input.cwd}/README.md`, "# Paseo rewind flow\n", "utf8");
+  execFileSync("git", ["add", "README.md"], { cwd: input.cwd, stdio: "ignore" });
+  execFileSync("git", ["commit", "-m", "Initial commit"], { cwd: input.cwd, stdio: "ignore" });
+  const client = await connectSeedClient();
+  const createdWorkspace = await client.createWorkspace({
+    source: { kind: "directory", path: input.cwd },
+  });
+  if (!createdWorkspace.workspace) {
+    throw new Error(createdWorkspace.error ?? `Failed to create workspace ${input.cwd}`);
+  }
+  const agent = await client.createAgent({
+    ...fullAccessConfig(input.provider),
+    ...input.providerConfig,
+    cwd: input.cwd,
+    workspaceId: createdWorkspace.workspace.id,
+    title: `rewind-flow-${input.provider}-${randomUUID()}`,
+  });
+  const handle = {
+    page: input.page,
+    client,
+    agentId: agent.id,
+    projectId: createdWorkspace.workspace.projectId,
+    workspaceId: createdWorkspace.workspace.id,
+    cwd: input.cwd,
+    provider: input.provider,
+  };
+  await openAgent(input.page, { workspaceId: createdWorkspace.workspace.id, agentId: agent.id });
+  return handle;
+}
+
+export async function closeAgent(handle: AgentHandle): Promise<void> {
+  await handle.client.removeProject(handle.projectId).catch(() => undefined);
+  await handle.client.close().catch(() => undefined);
+}
+
+export async function sendMessage(handle: AgentHandle, text: string): Promise<void> {
+  const before = await transcript(handle.page);
+  await submitMessage(handle.page, text);
+  const finish = await handle.client.waitForFinish(handle.agentId, SEND_TIMEOUT_MS);
+  if (finish.status !== "idle") {
+    const suffix = finish.final?.lastError ? `: ${finish.final.lastError}` : "";
+    throw new Error(
+      `Expected agent ${handle.agentId} to become idle, got ${finish.status}${suffix}`,
+    );
+  }
+  if (finish.final?.lastError) {
+    throw new Error(finish.final.lastError);
+  }
+  await expect
+    .poll(async () => transcript(handle.page), { timeout: 30_000 })
+    .toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ role: "user", text }),
+        expect.objectContaining({ role: "assistant" }),
+      ]),
+    );
+  await expect
+    .poll(async () => transcript(handle.page).then((messages) => messages.length), {
+      timeout: 30_000,
+    })
+    .toBeGreaterThanOrEqual(before.length + 2);
+  await assertComposerIdle(handle);
+}
+
+export async function assertChatTranscript(
+  handle: Pick<AgentHandle, "page">,
+  expected: TranscriptMessage[],
+): Promise<void> {
+  await expect
+    .poll(
+      async () => {
+        const actual = await transcript(handle.page);
+        if (actual.length !== expected.length) {
+          return JSON.stringify(actual);
+        }
+        const matches = actual.every(
+          (message, index) =>
+            message.role === expected[index]?.role &&
+            expectedTextMatches(message.text, expected[index]!.text),
+        );
+        return matches ? "match" : JSON.stringify(actual);
+      },
+      { timeout: 30_000 },
+    )
+    .toBe("match");
+
+  const actual = await transcript(handle.page);
+  if (actual.length !== expected.length) {
+    throw new Error(
+      `Expected ${expected.length} chat messages (${expected
+        .map(formatExpectedMessage)
+        .join(", ")}), found ${actual.length}: ${JSON.stringify(actual)}`,
+    );
+  }
+}
+
+export async function rewindMessage(
+  handle: AgentHandle,
+  userMessageIndex: number,
+  mode: RewindFlowMode,
+): Promise<void> {
+  const beforeEpoch = await fetchTimelineEpoch(handle);
+  const userMessage = handle.page.getByTestId("user-message").nth(userMessageIndex);
+  await expect(userMessage).toBeVisible({ timeout: 30_000 });
+  const userMessages = (await transcript(handle.page)).filter((message) => message.role === "user");
+  const userText = userMessages[userMessageIndex]?.text;
+  if (!userText) {
+    throw new Error(`No user message found at index ${userMessageIndex}`);
+  }
+  await userMessage
+    .getByText(new RegExp(escapeRegExp(userText)))
+    .first()
+    .hover();
+  const trigger = userMessage.getByTestId("rewind-menu-trigger");
+  await expect(trigger).toBeVisible({ timeout: 10_000 });
+  await trigger.click();
+  await expect(handle.page.getByTestId("rewind-menu-content")).toBeVisible({ timeout: 10_000 });
+  const modeItem = handle.page.getByTestId(`rewind-menu-${mode}`);
+  await expect(modeItem).toBeVisible({ timeout: 10_000 });
+  await modeItem.click();
+  await expect(handle.page.getByTestId("rewind-menu-content")).toHaveCount(0, { timeout: 10_000 });
+  if (mode !== "files") {
+    await waitForNextTimelineEpoch(handle, beforeEpoch);
+  }
+  await assertComposerIdle(handle);
+}
+
+export async function assertFileExists(filePath: string): Promise<void> {
+  await expect.poll(() => existsSync(filePath), { timeout: 10_000 }).toBe(true);
+}
+
+export async function assertFileMissing(filePath: string): Promise<void> {
+  await expect.poll(() => existsSync(filePath), { timeout: 10_000 }).toBe(false);
+}
+
+export async function assertFileContains(filePath: string, text: string): Promise<void> {
+  await assertFileExists(filePath);
+  await expect.poll(() => readFileSync(filePath, "utf8"), { timeout: 10_000 }).toContain(text);
+}
+
+export async function assertComposerIdle(handle: Pick<AgentHandle, "page">): Promise<void> {
+  await expectComposerEditable(handle.page);
+  await expect(handle.page.getByRole("button", { name: /stop|cancel/i })).toHaveCount(0, {
+    timeout: 30_000,
+  });
+  await expect(handle.page.getByTestId("turn-working-indicator")).toHaveCount(0, {
+    timeout: 30_000,
+  });
+}
+
+export async function cleanupRewindFlow(input: {
+  handle?: AgentHandle;
+  cwd: string;
+}): Promise<void> {
+  if (input.handle) {
+    await closeAgent(input.handle);
+  }
+  rmSync(input.cwd, { recursive: true, force: true });
+}
+
+async function fetchTimelineEpoch(handle: AgentHandle): Promise<string | undefined> {
+  const client = handle.client as SeedDaemonClient & {
+    fetchAgentTimeline: (
+      agentId: string,
+      options?: { direction?: "head" | "tail"; projection?: "projected"; limit?: number },
+    ) => Promise<{ epoch?: string }>;
+  };
+  const timeline = await client.fetchAgentTimeline(handle.agentId, {
+    direction: "tail",
+    projection: "projected",
+    limit: 0,
+  });
+  return timeline.epoch;
+}
+
+async function waitForNextTimelineEpoch(
+  handle: AgentHandle,
+  beforeEpoch: string | undefined,
+): Promise<void> {
+  await expect
+    .poll(async () => fetchTimelineEpoch(handle), { timeout: REWIND_TIMEOUT_MS })
+    .not.toBe(beforeEpoch);
+}

packages/app/e2e/support/helpers/route-assertions.ts

@@ -0,0 +1,17 @@
+import { expect, type Page } from "@playwright/test";
+
+export async function expectAppRoute(
+  page: Page,
+  expectedRoute: string,
+  options?: { timeout?: number },
+): Promise<void> {
+  await expect
+    .poll(
+      () => {
+        const current = new URL(page.url());
+        return `${current.pathname}${current.search}`;
+      },
+      { timeout: options?.timeout },
+    )
+    .toBe(expectedRoute);
+}

packages/app/e2e/support/helpers/schedule-fake-host.ts

@@ -0,0 +1,304 @@
+import { type Page } from "@playwright/test";
+import { buildSeededHost } from "./daemon-registry";
+import { wsRoutePatternForPort } from "./daemon-port";
+import { type SeededWorkspace } from "./seed-client";
+
+const REGISTRY_KEY = "@paseo:daemon-registry";
+const SEED_NONCE_KEY = "@paseo:e2e-seed-nonce";
+const EXTRA_HOSTS_KEY = "@paseo:e2e-extra-hosts";
+export const FAKE_HOST_MODEL_ID = "fake-host-model";
+export const FAKE_HOST_MODEL_LABEL = "Fake host model";
+export const FAKE_HOST_PROJECT_DISPLAY_NAME = "Fake host project";
+
+type WebSocketMessage = string | Buffer;
+type SessionRequest = Record<string, unknown> & { type?: string; requestId?: string };
+
+export interface FakeScheduleHostWorkspace {
+  serverId: string;
+  projectId: string;
+  projectKey: string;
+  projectDisplayName: string;
+  workspace: Record<string, unknown>;
+}
+
+interface FakeScheduleSummary {
+  id: string;
+  name: string | null;
+  prompt: string;
+  cadence: { type: "cron"; expression: string };
+  target: {
+    type: "new-agent";
+    config: {
+      provider: "mock";
+      cwd: string;
+      model: string;
+      modeId: string;
+      title?: string;
+    };
+  };
+  status: "active";
+  createdAt: string;
+  updatedAt: string;
+  nextRunAt: string | null;
+  lastRunAt: string | null;
+  pausedAt: string | null;
+  expiresAt: string | null;
+  maxRuns: number | null;
+}
+
+function parseJson(message: WebSocketMessage): unknown {
+  const raw = typeof message === "string" ? message : message.toString("utf8");
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function buildSessionMessage(type: string, payload: Record<string, unknown>) {
+  return JSON.stringify({
+    type: "session",
+    message: {
+      type,
+      payload,
+    },
+  });
+}
+
+function buildFakeProviderEntries(nowIso: string) {
+  return [
+    {
+      provider: "mock",
+      label: "Mock",
+      status: "ready",
+      enabled: true,
+      fetchedAt: nowIso,
+      models: [
+        {
+          provider: "mock",
+          id: FAKE_HOST_MODEL_ID,
+          label: FAKE_HOST_MODEL_LABEL,
+          isDefault: true,
+        },
+      ],
+      modes: [{ id: "load-test", label: "Load test" }],
+      defaultModeId: "load-test",
+    },
+  ];
+}
+
+function readSessionRequest(message: WebSocketMessage): SessionRequest | null {
+  const parsed = parseJson(message);
+  if (!parsed || typeof parsed !== "object") {
+    return null;
+  }
+
+  const envelope = parsed as { type?: string; message?: SessionRequest };
+  if (envelope.type !== "session" || !envelope.message) {
+    return null;
+  }
+
+  return envelope.message;
+}
+
+function getRequestId(request: SessionRequest): string {
+  return typeof request.requestId === "string" ? request.requestId : "fake-request";
+}
+
+export async function buildFakeScheduleHostWorkspace(
+  workspace: SeededWorkspace,
+): Promise<FakeScheduleHostWorkspace> {
+  const workspaceList = await workspace.client.fetchWorkspaces({
+    filter: { projectId: workspace.projectId },
+  });
+  const baseWorkspace = workspaceList.entries.find((entry) => entry.id === workspace.workspaceId);
+  if (!baseWorkspace) {
+    throw new Error(`Failed to load seeded workspace descriptor ${workspace.workspaceId}`);
+  }
+
+  const projectId = `${workspace.projectId}-fake-host`;
+  const cwd = `${workspace.repoPath}-fake-host`;
+  return {
+    serverId: "schedule-fake-host",
+    projectId,
+    projectKey: workspace.projectKey,
+    projectDisplayName: FAKE_HOST_PROJECT_DISPLAY_NAME,
+    workspace: {
+      ...baseWorkspace,
+      id: `${baseWorkspace.id}-fake-host`,
+      projectId,
+      projectDisplayName: FAKE_HOST_PROJECT_DISPLAY_NAME,
+      projectRootPath: cwd,
+      workspaceDirectory: cwd,
+      name: FAKE_HOST_PROJECT_DISPLAY_NAME,
+      project: undefined,
+    },
+  };
+}
+
+export async function installFakeScheduleHost(input: {
+  page: Page;
+  port: string;
+  serverId: string;
+  workspace: Record<string, unknown>;
+  project: Pick<FakeScheduleHostWorkspace, "projectId" | "projectKey" | "projectDisplayName">;
+  schedules?: FakeScheduleSummary[];
+}): Promise<void> {
+  await input.page.routeWebSocket(wsRoutePatternForPort(input.port), (ws) => {
+    ws.onMessage((message) => {
+      const parsed = parseJson(message);
+      if (parsed && typeof parsed === "object" && (parsed as { type?: string }).type === "hello") {
+        ws.send(
+          buildSessionMessage("status", {
+            status: "server_info",
+            serverId: input.serverId,
+            hostname: "fake-schedule-host",
+            version: "0.0.0-e2e",
+            features: {
+              providersSnapshot: true,
+              workspaceMultiplicity: true,
+              projectList: true,
+              projectAdd: true,
+              projectRemove: true,
+              workspaceRecovery: true,
+            },
+          }),
+        );
+        return;
+      }
+
+      if (parsed && typeof parsed === "object" && (parsed as { type?: string }).type === "ping") {
+        ws.send(JSON.stringify({ type: "pong" }));
+        return;
+      }
+
+      const request = readSessionRequest(message);
+      if (!request) {
+        return;
+      }
+
+      const requestId = getRequestId(request);
+      const now = Date.now();
+      const nowIso = new Date(now).toISOString();
+      switch (request.type) {
+        case "ping":
+          ws.send(
+            buildSessionMessage("pong", {
+              requestId,
+              clientSentAt: typeof request.clientSentAt === "number" ? request.clientSentAt : now,
+              serverReceivedAt: now,
+              serverSentAt: now,
+            }),
+          );
+          return;
+        case "fetch_workspaces_request":
+          ws.send(
+            buildSessionMessage("fetch_workspaces_response", {
+              requestId,
+              entries: [input.workspace],
+              emptyProjects: [],
+              pageInfo: { nextCursor: null, prevCursor: null, hasMore: false },
+            }),
+          );
+          return;
+        case "project.list.request":
+          ws.send(
+            buildSessionMessage("project.list.response", {
+              requestId,
+              projects: [
+                {
+                  projectId: input.project.projectId,
+                  projectKey: input.project.projectKey,
+                  projectDisplayName: input.project.projectDisplayName,
+                  projectRootPath: String(input.workspace.projectRootPath),
+                  projectKind: "git",
+                },
+              ],
+            }),
+          );
+          return;
+        case "fetch_agents_request":
+          ws.send(
+            buildSessionMessage("fetch_agents_response", {
+              requestId,
+              entries: [],
+              pageInfo: { nextCursor: null, prevCursor: null, hasMore: false },
+            }),
+          );
+          return;
+        case "get_providers_snapshot_request":
+          ws.send(
+            buildSessionMessage("get_providers_snapshot_response", {
+              requestId,
+              entries: buildFakeProviderEntries(nowIso),
+              generatedAt: nowIso,
+            }),
+          );
+          return;
+        case "refresh_providers_snapshot_request":
+          ws.send(
+            buildSessionMessage("refresh_providers_snapshot_response", {
+              requestId,
+              acknowledged: true,
+            }),
+          );
+          return;
+        case "schedule/list":
+          ws.send(
+            buildSessionMessage("schedule/list/response", {
+              requestId,
+              schedules: input.schedules ?? [],
+              error: null,
+            }),
+          );
+          return;
+      }
+    });
+  });
+}
+
+export async function addFakeScheduleHostAndReload(input: {
+  page: Page;
+  serverId: string;
+  label: string;
+  port: string;
+}): Promise<void> {
+  const host = buildSeededHost({
+    serverId: input.serverId,
+    label: input.label,
+    endpoint: `127.0.0.1:${input.port}`,
+    nowIso: new Date().toISOString(),
+  });
+
+  await input.page.evaluate(
+    ({ seededHost, keys }) => {
+      const nonce = localStorage.getItem(keys.nonce);
+      if (!nonce) {
+        throw new Error("Expected the e2e seed nonce before overriding the host registry.");
+      }
+      const raw = localStorage.getItem(keys.registry);
+      const registry: Array<{ serverId: string }> = raw ? JSON.parse(raw) : [];
+      const nextRegistry = registry.filter((entry) => entry.serverId !== seededHost.serverId);
+      nextRegistry.push(seededHost);
+      localStorage.setItem(keys.registry, JSON.stringify(nextRegistry));
+
+      const rawExtraHosts = localStorage.getItem(keys.extraHosts);
+      const extraHosts: Array<{ serverId: string }> = rawExtraHosts
+        ? JSON.parse(rawExtraHosts)
+        : [];
+      const nextExtraHosts = extraHosts.filter((entry) => entry.serverId !== seededHost.serverId);
+      nextExtraHosts.push(seededHost);
+      localStorage.setItem(keys.extraHosts, JSON.stringify(nextExtraHosts));
+    },
+    {
+      seededHost: host,
+      keys: {
+        registry: REGISTRY_KEY,
+        nonce: SEED_NONCE_KEY,
+        extraHosts: EXTRA_HOSTS_KEY,
+      },
+    },
+  );
+
+  await input.page.reload();
+}

packages/app/e2e/support/helpers/seed-client.ts

@@ -0,0 +1,263 @@
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import type { TerminalActivity } from "@getpaseo/protocol/terminal-activity";
+import { connectDaemonClient } from "./daemon-client-loader";
+import { withProjectOwnership } from "./project-ownership";
+import { createTempDirectory, createTempGitRepo } from "./workspace";
+
+export interface SeedWorkspaceDescriptor {
+  id: string;
+  name: string;
+  projectId: string;
+  projectDisplayName: string;
+  projectRootPath: string;
+  workspaceDirectory: string;
+}
+
+interface SeedProjectDescriptor {
+  projectId: string;
+  projectKey?: string;
+}
+
+/**
+ * The general-purpose E2E daemon client used to seed and drive state out of
+ * band (workspaces, agents, terminals) while the UI is exercised through the
+ * browser. Domain-specific helpers wrap it for their own flows; specs should
+ * prefer those wrappers over reaching for this client directly.
+ */
+export interface SeedDaemonClient {
+  connect(): Promise<void>;
+  close(): Promise<void>;
+  addProject(cwd: string): Promise<{
+    project: {
+      projectId: string;
+      projectKey?: string;
+      projectDisplayName: string;
+      projectRootPath: string;
+    } | null;
+    error: string | null;
+  }>;
+  removeProject(projectId: string): Promise<{ removedWorkspaceIds: string[] }>;
+  renameProject(projectId: string, customName: string | null): Promise<void>;
+  fetchWorkspaces(options?: { filter?: { projectId?: string } }): Promise<{
+    entries: SeedWorkspaceDescriptor[];
+  }>;
+  listProjects(): Promise<{ projects: SeedProjectDescriptor[] }>;
+  createWorkspace(input: {
+    source:
+      | { kind: "directory"; path: string; projectId?: string }
+      | {
+          kind: "worktree";
+          cwd?: string;
+          projectId?: string;
+          action?: "branch-off" | "checkout";
+          refName?: string;
+          baseBranch?: string;
+          githubPrNumber?: number;
+          worktreeSlug?: string;
+        };
+    title?: string;
+  }): Promise<{
+    workspace: SeedWorkspaceDescriptor | null;
+    error: string | null;
+  }>;
+  /**
+   * Force the daemon to recompute its git snapshot and diff for a checkout,
+   * mirroring the UI's manual refresh. Tests use this to make an out-of-band
+   * working-tree write authoritative before asserting on it in the UI, instead
+   * of racing the filesystem watcher's debounce.
+   */
+  checkoutRefresh(cwd: string): Promise<{ success: boolean; error: unknown }>;
+  createTerminal(
+    cwd: string,
+    name?: string,
+    requestId?: string,
+    options?: { agentId?: string; command?: string; args?: string[]; workspaceId?: string },
+  ): Promise<{
+    terminal: { id: string; name: string; cwd: string; activity?: TerminalActivity | null } | null;
+    error: string | null;
+  }>;
+  listTerminals(
+    cwd?: string,
+    requestId?: string,
+    options?: { workspaceId?: string },
+  ): Promise<{
+    terminals: Array<{
+      id: string;
+      name: string;
+      cwd: string;
+      title?: string;
+      activity?: TerminalActivity | null;
+    }>;
+    error?: string | null;
+  }>;
+  createAgent(options: {
+    provider: string;
+    cwd: string;
+    workspaceId?: string;
+    title?: string;
+    modeId?: string;
+    model?: string;
+    thinkingOptionId?: string;
+    featureValues?: Record<string, unknown>;
+    initialPrompt?: string;
+    labels?: Record<string, string>;
+  }): Promise<{ id: string; status: string }>;
+  fetchAgents(options?: { scope?: "active" }): Promise<{
+    entries: Array<{
+      agent: {
+        id: string;
+        provider: string;
+        cwd: string;
+        workspaceId?: string;
+        model: string | null;
+        currentModeId: string | null;
+        status: string;
+        title?: string | null;
+      };
+    }>;
+  }>;
+  fetchRecentProviderSessions(options: {
+    cwd: string;
+    providers: string[];
+    limit: number;
+  }): Promise<{
+    entries: Array<{
+      providerId: string;
+      providerHandleId: string;
+      cwd: string;
+      firstPromptPreview?: string | null;
+    }>;
+  }>;
+  updateAgent(agentId: string, updates: { name?: string }): Promise<void>;
+  setAgentMode(agentId: string, modeId: string): Promise<unknown>;
+  waitForAgentUpsert(
+    agentId: string,
+    predicate: (snapshot: { status: string }) => boolean,
+    timeout?: number,
+  ): Promise<{ status: string }>;
+  sendAgentMessage(agentId: string, text: string): Promise<void>;
+  waitForFinish(
+    agentId: string,
+    timeout?: number,
+  ): Promise<{ status: string; final?: { lastError?: string | null } | null }>;
+  archiveAgent(agentId: string): Promise<{ archivedAt: string }>;
+  refreshAgent(agentId: string): Promise<unknown>;
+  fetchAgent(options: {
+    agentId: string;
+  }): Promise<{ agent: { id: string; archivedAt?: string | null } } | null>;
+  getLastServerInfoMessage(): {
+    features?: {
+      projectAdd?: boolean;
+      workspaceRecovery?: boolean;
+    } | null;
+  } | null;
+  fetchAgentHistory(options?: {
+    page?: { limit: number };
+  }): Promise<{ entries: Array<{ agent: { id: string } }> }>;
+  subscribeTerminal(
+    terminalId: string,
+  ): Promise<{ terminalId: string; slot: number; error: null } | { error: string }>;
+  sendTerminalInput(
+    terminalId: string,
+    message: { type: "input"; data: string } | { type: "resize"; rows: number; cols: number },
+  ): void;
+  onTerminalStreamEvent(
+    handler: (event: { terminalId: string; type: string; data?: Uint8Array }) => void,
+  ): () => void;
+  killTerminal(terminalId: string): Promise<{ error: string | null }>;
+}
+
+export async function connectSeedClient(options?: {
+  port?: number;
+  /** Use only with a private host whose teardown removes its entire PASEO_HOME. */
+  projectOwnership?: "client" | "host";
+}): Promise<SeedDaemonClient> {
+  const client = await connectDaemonClient<SeedDaemonClient>({
+    clientIdPrefix: "seed",
+    appVersion: loadAppVersion(),
+    port: options?.port,
+  });
+  return options?.projectOwnership === "host" ? client : withProjectOwnership(client);
+}
+
+/**
+ * A temp project opened as a workspace, with a seed client connected to drive
+ * it out of band. `cleanup` closes the client and removes the project. This is
+ * the canonical bootstrap for specs that need a real workspace plus daemon
+ * access; domain helpers (e.g. mock-agent) build on it rather than re-rolling
+ * the trio. `repoPath` is the project root on disk (git repo or plain dir).
+ */
+export interface SeededWorkspace {
+  client: SeedDaemonClient;
+  repoPath: string;
+  workspaceId: string;
+  workspaceName: string;
+  workspaceDirectory: string;
+  /** Host-local identity used by daemon project operations. */
+  projectId: string;
+  /** Opaque cross-host key used by grouped project UI. */
+  projectKey: string;
+  /** Project label the UI shows (owner/repo for known remotes, else basename). */
+  projectDisplayName: string;
+  cleanup(): Promise<void>;
+}
+
+export async function seedWorkspace(options: {
+  repoPrefix: string;
+  title?: string;
+  port?: number;
+  /** Repo fixture options; only applies to git projects (the default). */
+  repo?: Parameters<typeof createTempGitRepo>[1];
+  /** Set to false to seed a plain non-git directory instead of a git repo. */
+  git?: boolean;
+}): Promise<SeededWorkspace> {
+  const project =
+    options.git === false
+      ? await createTempDirectory(options.repoPrefix)
+      : await createTempGitRepo(options.repoPrefix, options.repo);
+  const client = await connectSeedClient({ port: options.port });
+  try {
+    const created = await client.createWorkspace({
+      source: { kind: "directory", path: project.path },
+      title: options.title,
+    });
+    if (!created.workspace) {
+      throw new Error(created.error ?? `Failed to create workspace ${project.path}`);
+    }
+    const workspace = created.workspace;
+    const listed = await client.listProjects();
+    const descriptor = listed.projects.find((item) => item.projectId === workspace.projectId);
+    if (!descriptor?.projectKey) {
+      throw new Error(`Created project ${workspace.projectId} has no project key`);
+    }
+    return {
+      client,
+      repoPath: project.path,
+      workspaceId: workspace.id,
+      workspaceName: workspace.name,
+      workspaceDirectory: workspace.workspaceDirectory,
+      projectId: workspace.projectId,
+      projectKey: descriptor.projectKey,
+      projectDisplayName: workspace.projectDisplayName,
+      cleanup: async () => {
+        await client.removeProject(workspace.projectId).catch(() => undefined);
+        await client.close().catch(() => undefined);
+        await project.cleanup().catch(() => undefined);
+      },
+    };
+  } catch (error) {
+    await client.close().catch(() => undefined);
+    await project.cleanup().catch(() => undefined);
+    throw error;
+  }
+}
+
+function loadAppVersion(): string {
+  const packageJsonPath = path.resolve(__dirname, "../../../package.json");
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8")) as { version?: unknown };
+  if (typeof packageJson.version !== "string" || packageJson.version.length === 0) {
+    throw new Error(`Missing app version in ${packageJsonPath}`);
+  }
+  return packageJson.version;
+}

packages/app/e2e/support/helpers/server-id.ts

@@ -0,0 +1,13 @@
+/**
+ * Resolves the isolated E2E daemon's server id, which Playwright's globalSetup
+ * publishes into the environment before any spec runs. Helpers and specs that
+ * build host routes or `sidebar-workspace-row-${serverId}:${id}` selectors share
+ * this accessor instead of re-reading the env var.
+ */
+export function getServerId(): string {
+  const serverId = process.env.E2E_SERVER_ID;
+  if (!serverId) {
+    throw new Error("E2E_SERVER_ID is not set (expected from the Playwright worker fixture).");
+  }
+  return serverId;
+}

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

@@ -0,0 +1,405 @@
+import { expect, type Page } from "@playwright/test";
+import { buildCreateAgentPreferences, buildSeededHost, TEST_HOST_LABEL } from "./daemon-registry";
+import { getServerId } from "./server-id";
+import { expectAppRoute } from "./route-assertions";
+import {
+  buildSettingsHostSectionRoute,
+  buildSettingsRoute,
+  buildSettingsSectionRoute,
+} from "@/utils/host-routes";
+
+const DISABLE_DEFAULT_SEED_ONCE_KEY = "@paseo:e2e-disable-default-seed-once";
+const SEED_NONCE_KEY = "@paseo:e2e-seed-nonce";
+const REGISTRY_KEY = "@paseo:daemon-registry";
+
+interface SavedSettingsHostInput {
+  serverId: string;
+  label: string;
+  endpoint: string;
+}
+
+const SECTION_LABELS = {
+  general: "General",
+  appearance: "Appearance",
+  editor: "Editor",
+  shortcuts: "Shortcuts",
+  integrations: "Integrations",
+  permissions: "Permissions",
+  diagnostics: "Diagnostics",
+  about: "About",
+} as const;
+
+export type SettingsSection = keyof typeof SECTION_LABELS;
+
+type HostSection =
+  | "projects"
+  | "connections"
+  | "pair-device"
+  | "agents"
+  | "workspaces"
+  | "providers"
+  | "usage"
+  | "host";
+
+export async function openSettingsSection(page: Page, section: SettingsSection): Promise<void> {
+  const sidebar = page.getByTestId("settings-sidebar");
+  await expect(sidebar).toBeVisible();
+
+  await sidebar.getByRole("button", { name: SECTION_LABELS[section], exact: true }).click();
+  await expectAppRoute(page, buildSettingsSectionRoute(section));
+}
+
+export async function openSettingsHost(page: Page, serverId: string): Promise<void> {
+  // Host sections are now flat top-level rows under the Host group. Navigate by
+  // clicking the Connections section row; the picker only matters when >1 host.
+  await page.getByTestId("settings-host-section-connections").click();
+  await expectHostSettingsUrl(page, serverId);
+  await expect(page.getByTestId("host-page-connections-card")).toBeVisible();
+}
+
+export async function openSettingsHostSection(
+  page: Page,
+  serverId: string,
+  section: HostSection,
+): Promise<void> {
+  await page.getByTestId(`settings-host-section-${section}`).click();
+  await expectAppRoute(page, buildSettingsHostSectionRoute(serverId, section));
+}
+
+export async function expectSettingsHeader(page: Page, title: string): Promise<void> {
+  await expect(page.getByTestId("settings-detail-header-title")).toHaveText(title);
+}
+
+export async function openAddHostFlow(page: Page): Promise<void> {
+  // "Add host" is now an item inside the host picker (a Combobox); open the
+  // picker first, then pick it. The picker renders whenever a host exists.
+  await page.getByTestId("settings-host-picker").click();
+  await page.getByTestId("settings-add-host").click();
+  await expect(page.getByText("Add connection", { exact: true })).toBeVisible();
+}
+
+export async function selectHostConnectionType(
+  page: Page,
+  type: "direct" | "relay",
+): Promise<void> {
+  const label = type === "direct" ? "Direct connection" : "Paste pairing link";
+  await page.getByRole("button", { name: label }).click();
+}
+
+export async function toggleHostAdvanced(page: Page): Promise<void> {
+  await page.getByTestId("direct-host-advanced-toggle").click();
+}
+
+export async function openCompactSettings(page: Page, expectedStartRoute: string): Promise<void> {
+  await expectAppRoute(page, expectedStartRoute, { timeout: 15_000 });
+  await page.getByRole("button", { name: "Open menu", exact: true }).first().click();
+  const settingsButton = page.locator('[data-testid="sidebar-settings"]:visible').first();
+  await expect(settingsButton).toBeVisible();
+  await settingsButton.click();
+  await expectAppRoute(page, buildSettingsRoute());
+  await expect(page.getByTestId("settings-sidebar")).toBeVisible();
+}
+
+export async function seedSavedSettingsHosts(
+  page: Page,
+  hosts: SavedSettingsHostInput[],
+): Promise<void> {
+  await page.goto("/");
+  const nowIso = new Date().toISOString();
+  const registry = hosts.map((host) =>
+    buildSeededHost({
+      serverId: host.serverId,
+      label: host.label,
+      endpoint: host.endpoint,
+      nowIso,
+    }),
+  );
+  const firstHost = registry[0];
+  if (!firstHost) {
+    throw new Error("Expected at least one settings host fixture.");
+  }
+  const preferences = buildCreateAgentPreferences(firstHost.serverId);
+
+  await page.evaluate(
+    ({ keys, storedRegistry, storedPreferences }) => {
+      const nonce = localStorage.getItem(keys.seedNonce);
+      if (!nonce) {
+        throw new Error("Expected e2e seed nonce before overriding settings host registry.");
+      }
+
+      localStorage.setItem(keys.registry, JSON.stringify(storedRegistry));
+      localStorage.setItem("@paseo:create-agent-preferences", JSON.stringify(storedPreferences));
+      localStorage.setItem(keys.disableDefaultSeedOnce, nonce);
+    },
+    {
+      keys: {
+        disableDefaultSeedOnce: DISABLE_DEFAULT_SEED_ONCE_KEY,
+        registry: REGISTRY_KEY,
+        seedNonce: SEED_NONCE_KEY,
+      },
+      storedRegistry: registry,
+      storedPreferences: preferences,
+    },
+  );
+}
+
+export async function selectSettingsHost(page: Page, serverId: string): Promise<void> {
+  await page.locator('[data-testid="settings-host-picker"]:visible').click();
+  await page.locator(`[data-testid="settings-host-picker-item-${serverId}"]:visible`).click();
+}
+
+export async function expectSettingsHostPickerLabel(page: Page, label: string): Promise<void> {
+  await expect(
+    page.getByTestId("settings-host-picker").getByText(label, { exact: true }),
+  ).toBeVisible();
+}
+
+export async function expectCompactSettingsList(page: Page): Promise<void> {
+  await expectAppRoute(page, buildSettingsRoute());
+  await expect(page.getByTestId("settings-sidebar")).toBeVisible();
+  await expect(page.getByText("Theme", { exact: true })).toHaveCount(0);
+  await expect(page.getByRole("button", { name: "Play test" })).toHaveCount(0);
+  await expect(page.getByTestId("host-page-connections-card")).toHaveCount(0);
+}
+
+export async function expectSettingsSidebarVisible(page: Page): Promise<void> {
+  await expect(page.getByTestId("settings-sidebar")).toBeVisible();
+}
+
+export async function expectSettingsSidebarHidden(page: Page): Promise<void> {
+  await expect(page.locator('[data-testid="settings-sidebar"]:visible')).toHaveCount(0);
+}
+
+export async function expectSettingsSidebarSections(
+  page: Page,
+  sections: SettingsSection[],
+): Promise<void> {
+  const sidebar = page.getByTestId("settings-sidebar");
+  for (const section of sections) {
+    await expect(
+      sidebar.getByRole("button", { name: SECTION_LABELS[section], exact: true }),
+    ).toBeVisible();
+  }
+}
+
+export async function goBackInSettings(page: Page): Promise<void> {
+  await page.getByRole("button", { name: "Back", exact: true }).click();
+}
+
+export async function closeCompactSettings(page: Page): Promise<void> {
+  await goBackInSettings(page);
+  await expect(page).not.toHaveURL(/\/settings(\/|$)/);
+}
+
+export async function removeCurrentHostFromSettings(page: Page): Promise<void> {
+  await page.getByTestId("host-page-remove-host-button").click();
+  await expect(page.getByTestId("remove-host-confirm-modal")).toBeVisible();
+  await page.getByTestId("remove-host-confirm").click();
+  await expectAppRoute(page, buildSettingsRoute());
+}
+
+export async function expectSettingsBackButton(page: Page): Promise<void> {
+  await expect(page.getByRole("button", { name: "Back", exact: true })).toBeVisible();
+}
+
+export async function clickSettingsBackToWorkspace(page: Page): Promise<void> {
+  await page.getByTestId("settings-back-to-workspace").click();
+}
+
+export async function expectHostSettingsUrl(page: Page, serverId: string): Promise<void> {
+  await expectAppRoute(page, buildSettingsHostSectionRoute(serverId, "connections"));
+}
+
+export async function verifyLegacyHostSettingsRedirect(page: Page): Promise<void> {
+  const serverId = getServerId();
+  await page.goto(`/h/${encodeURIComponent(serverId)}/settings`);
+  await expectHostSettingsUrl(page, serverId);
+}
+
+export async function openCompactSettingsHost(page: Page): Promise<void> {
+  const serverId = getServerId();
+  await openSettingsHost(page, serverId);
+  await expectHostSettingsUrl(page, serverId);
+}
+
+export async function expectAddHostMethodOptions(page: Page): Promise<void> {
+  await expect(page.getByRole("button", { name: "Direct connection" })).toBeVisible();
+  await expect(page.getByRole("button", { name: "Paste pairing link" })).toBeVisible();
+}
+
+export async function fillDirectHostUri(page: Page, uri: string): Promise<void> {
+  await page.getByTestId("direct-host-uri-input").fill(uri);
+}
+
+export async function expectDirectHostFormValues(
+  page: Page,
+  fields: { host: string; port: string; password: string },
+): Promise<void> {
+  await expect(page.getByTestId("direct-host-input")).toHaveValue(fields.host);
+  await expect(page.getByTestId("direct-port-input")).toHaveValue(fields.port);
+  await expect(page.getByTestId("direct-password-input")).toHaveValue(fields.password);
+}
+
+export async function expectDirectHostSslEnabled(page: Page): Promise<void> {
+  await expect(page.getByTestId("direct-ssl-toggle-checked")).toBeVisible();
+}
+
+export async function expectDirectHostUriValue(page: Page, uri: string): Promise<void> {
+  await expect(page.getByTestId("direct-host-uri-input")).toHaveValue(uri);
+}
+
+export async function expectDirectHostUriHidden(page: Page): Promise<void> {
+  await expect(page.getByTestId("direct-host-uri-input")).toHaveCount(0);
+}
+
+export async function expectDiagnosticsContent(page: Page): Promise<void> {
+  await expect(page.getByRole("button", { name: "Run" })).toBeVisible();
+  await expect(page.getByRole("button", { name: "Play test" })).toBeVisible();
+}
+
+export async function expectAboutContent(page: Page): Promise<void> {
+  await expect(page.getByText("App version", { exact: true }).first()).toBeVisible();
+}
+
+export async function expectGeneralContent(page: Page): Promise<void> {
+  await expect(page.getByText("Default send", { exact: true }).first()).toBeVisible();
+}
+
+export async function expectAppearanceContent(page: Page): Promise<void> {
+  await expect(page.getByText("Highlight theme", { exact: true }).first()).toBeVisible();
+}
+
+export async function expectHostLabelDisplayed(page: Page): Promise<void> {
+  await expect(page.getByTestId("host-page-label-edit-button")).toBeVisible();
+  await expect(page.getByTestId("host-page-rename-modal-input")).toHaveCount(0);
+}
+
+export async function clickEditHostLabel(page: Page): Promise<void> {
+  await page.getByTestId("host-page-label-edit-button").click();
+}
+
+export async function expectHostLabelEditMode(page: Page, expectedLabel: string): Promise<void> {
+  await expect(page.getByTestId("host-page-rename-modal-input")).toBeVisible();
+  await expect(page.getByTestId("host-page-rename-modal-input")).toHaveValue(expectedLabel);
+  await expect(page.getByTestId("host-page-rename-modal-submit")).toBeVisible();
+}
+
+export async function expectHostConnectionsCard(page: Page, port: string): Promise<void> {
+  const card = page.getByTestId("host-page-connections-card");
+  await expect(card).toBeVisible();
+  // "Connections" appears three times on this page: the sidebar section row, the
+  // detail header title, and the SettingsSection heading above the card. Match
+  // the first to keep the heading assertion without tripping Playwright strict
+  // mode.
+  await expect(page.getByText("Connections", { exact: true }).first()).toBeVisible();
+  await expect(
+    card.getByText(new RegExp(`TCP \\((localhost|127\\.0\\.0\\.1):${port}\\)`)),
+  ).toBeVisible();
+}
+
+export async function expectHostInjectMcpCard(page: Page): Promise<void> {
+  const card = page.getByTestId("host-page-inject-mcp-card");
+  await expect(card).toBeVisible();
+  await expect(card.getByRole("switch", { name: "Inject Paseo tools" })).toBeVisible();
+}
+
+export async function openHostSection(
+  page: Page,
+  serverId: string,
+  section: HostSection,
+): Promise<void> {
+  await openSettingsHostSection(page, serverId, section);
+}
+
+export async function expectHostActionCards(page: Page, serverId: string): Promise<void> {
+  // Restart + remove cards live on the Host section; providers moved to its
+  // own Providers section (asserted via expectHostProvidersCard).
+  await openSettingsHostSection(page, serverId, "host");
+  await expect(page.getByTestId("host-page-restart-card")).toBeVisible();
+  await expect(page.getByTestId("host-page-restart-button")).toBeVisible();
+  await expect(page.getByTestId("host-page-remove-host-card")).toBeVisible();
+  await expect(page.getByTestId("host-page-remove-host-button")).toBeVisible();
+}
+
+export async function expectHostProvidersCard(page: Page, serverId: string): Promise<void> {
+  await openSettingsHostSection(page, serverId, "providers");
+  await expect(page.getByTestId("host-page-providers-card")).toBeVisible();
+}
+
+export async function serveJson(page: Page, url: string, body: unknown): Promise<void> {
+  await page.route(url, async (route) => {
+    await route.fulfill({
+      status: 200,
+      contentType: "application/json",
+      body: JSON.stringify(body),
+    });
+  });
+}
+
+export async function openAddProviderArea(page: Page): Promise<void> {
+  await page.getByTestId("host-page-add-provider-card").scrollIntoViewIfNeeded();
+  await expect(page.getByRole("textbox", { name: "Search providers" })).toBeVisible();
+}
+
+export async function findAcpCatalogProvider(page: Page, providerName: string): Promise<void> {
+  await page.getByRole("textbox", { name: "Search providers" }).fill(providerName);
+  await expect(page.getByText(providerName, { exact: true })).toBeVisible();
+}
+
+export async function installAcpCatalogProvider(page: Page, providerName: string): Promise<void> {
+  await findAcpCatalogProvider(page, providerName);
+  await page.getByRole("button", { name: "Add", exact: true }).click();
+}
+
+export async function expectProviderInstalledInSettings(
+  page: Page,
+  providerName: string,
+): Promise<void> {
+  await expect(
+    page.getByRole("button", { name: `${providerName} provider details`, exact: true }),
+  ).toBeVisible();
+}
+
+export async function expectHostNoDaemonLifecycleRow(page: Page): Promise<void> {
+  await expect(page.getByTestId("host-page-daemon-lifecycle-card")).toHaveCount(0);
+}
+
+export async function expectRetiredSidebarSectionsAbsent(page: Page): Promise<void> {
+  const sidebar = page.getByTestId("settings-sidebar");
+  await expect(sidebar).toBeVisible();
+
+  // App group rows remain top-level.
+  await expect(sidebar.getByRole("button", { name: "General", exact: true })).toBeVisible();
+  await expect(sidebar.getByRole("button", { name: "Diagnostics", exact: true })).toBeVisible();
+  await expect(sidebar.getByRole("button", { name: "About", exact: true })).toBeVisible();
+  await expect(sidebar.getByRole("button", { name: "Daemon", exact: true })).toHaveCount(0);
+
+  // Host group rows are now flat top-level sections (no drill-in).
+  await expect(sidebar.getByTestId("settings-host-section-connections")).toBeVisible();
+  await expect(sidebar.getByTestId("settings-host-section-projects")).toBeVisible();
+  await expect(sidebar.getByTestId("settings-host-section-agents")).toBeVisible();
+  await expect(sidebar.getByTestId("settings-host-section-workspaces")).toBeVisible();
+  await expect(sidebar.getByTestId("settings-host-section-providers")).toBeVisible();
+  await expect(sidebar.getByTestId("settings-host-section-usage")).toBeVisible();
+  await expect(sidebar.getByTestId("settings-host-section-host")).toBeVisible();
+
+  // The old per-host entry rows are replaced by the host picker.
+  await expect(sidebar.locator('[data-testid^="settings-host-entry-"]')).toHaveCount(0);
+}
+
+export async function expectHostPageVisible(page: Page, _serverId: string): Promise<void> {
+  await expect(page.getByTestId("host-page-connections-card")).toBeVisible();
+}
+
+export async function expectLocalHostEntryFirst(page: Page, _serverId: string): Promise<void> {
+  const sidebar = page.getByTestId("settings-sidebar");
+  await expect(sidebar).toBeVisible({ timeout: 15_000 });
+
+  // Single-host fixture: the picker is a non-interactive chip (no dropdown to
+  // open) that surfaces the local host by its label. The per-row connection
+  // endpoint only appears on dropdown rows in the multi-host case, which this
+  // fixture does not exercise.
+  const picker = sidebar.getByTestId("settings-host-picker");
+  await expect(picker).toBeVisible();
+  await expect(picker.getByText(TEST_HOST_LABEL, { exact: true })).toBeVisible();
+}

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

@@ -0,0 +1,86 @@
+import { expect, type Locator } from "@playwright/test";
+
+interface SettledOptions {
+  timeout?: number;
+  durationMs?: number;
+  intervalMs?: number;
+  heightTolerance?: number;
+}
+
+interface Sample {
+  text: string;
+  height: number;
+}
+
+const DEFAULT_DURATION_MS = 1_500;
+const DEFAULT_INTERVAL_MS = 100;
+const DEFAULT_HEIGHT_TOLERANCE = 1;
+
+async function sample(locator: Locator): Promise<Sample> {
+  const [text, box] = await Promise.all([locator.textContent(), locator.boundingBox()]);
+  if (!box) {
+    throw new Error("Expected locator to keep a bounding box while sampling settledness.");
+  }
+  return { text: text ?? "", height: box.height };
+}
+
+async function collectSamples(locator: Locator, options?: SettledOptions): Promise<Sample[]> {
+  await expect(locator).toBeVisible({ timeout: options?.timeout ?? 30_000 });
+
+  const durationMs = options?.durationMs ?? DEFAULT_DURATION_MS;
+  const intervalMs = options?.intervalMs ?? DEFAULT_INTERVAL_MS;
+  const samples: Sample[] = [];
+  const deadline = Date.now() + durationMs;
+
+  while (Date.now() <= deadline || samples.length < 2) {
+    samples.push(await sample(locator));
+    await locator.page().waitForTimeout(intervalMs);
+  }
+
+  return samples;
+}
+
+function assertStableHeight(samples: Sample[], tolerance: number): void {
+  const heights = samples.map((entry) => entry.height);
+  const minHeight = Math.min(...heights);
+  const maxHeight = Math.max(...heights);
+  expect(maxHeight - minHeight, `height changed by more than ${tolerance}px`).toBeLessThanOrEqual(
+    tolerance,
+  );
+}
+
+function assertSettledText(samples: Sample[]): void {
+  let stableText: string | null = null;
+  let previousText: string | null = null;
+
+  for (const entry of samples) {
+    if (stableText !== null && entry.text !== stableText) {
+      throw new Error(
+        `Text changed after settling. Expected ${JSON.stringify(stableText)}, received ${JSON.stringify(entry.text)}.`,
+      );
+    }
+
+    if (previousText === entry.text) {
+      stableText = entry.text;
+    }
+    previousText = entry.text;
+  }
+
+  if (stableText === null) {
+    throw new Error("Text did not reach a stable value during the settledness window.");
+  }
+}
+
+export async function expectSettled(locator: Locator, options?: SettledOptions): Promise<void> {
+  const samples = await collectSamples(locator, options);
+  assertSettledText(samples);
+  assertStableHeight(samples, options?.heightTolerance ?? DEFAULT_HEIGHT_TOLERANCE);
+}
+
+export async function expectStableHeight(
+  locator: Locator,
+  options?: SettledOptions,
+): Promise<void> {
+  const samples = await collectSamples(locator, options);
+  assertStableHeight(samples, options?.heightTolerance ?? DEFAULT_HEIGHT_TOLERANCE);
+}

packages/app/e2e/support/helpers/sheet-layout.ts

@@ -0,0 +1,68 @@
+import { expect, type Locator, type Page } from "@playwright/test";
+
+export interface Rails {
+  left: number;
+  right: number;
+}
+
+interface Box {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+async function readBox(locator: Locator): Promise<Box> {
+  const box = await locator.boundingBox();
+  expect(box, "Expected the element to be laid out").not.toBeNull();
+  return box as Box;
+}
+
+/** Leading and trailing edges of an element, in whole pixels. */
+export async function readRails(locator: Locator): Promise<Rails> {
+  const box = await readBox(locator);
+  return { left: Math.round(box.x), right: Math.round(box.x + box.width) };
+}
+
+/**
+ * The two rails an AdaptiveModalSheet header indents to: the title's leading
+ * glyph and the close button's trailing edge. Sheet content sits on the same
+ * two rails, in every presentation.
+ */
+export async function readSheetHeaderRails(
+  page: Page,
+  sheetTestID: string,
+  title: string,
+): Promise<Rails> {
+  const header = page.getByTestId(sheetTestID);
+  const [titleRails, closeRails] = await Promise.all([
+    readRails(header.getByText(title, { exact: true })),
+    readRails(header.getByRole("button", { name: "Close" })),
+  ]);
+  return { left: titleRails.left, right: closeRails.right };
+}
+
+/** Vertical space between the bottom of one element and the top of the next. */
+export async function readVerticalGap(upper: Locator, lower: Locator): Promise<number> {
+  const [above, below] = await Promise.all([readBox(upper), readBox(lower)]);
+  return Math.round(below.y - (above.y + above.height));
+}
+
+/**
+ * A compact sheet slides up into place, so anything measured across two reads
+ * has to wait for the surface to stop moving first.
+ */
+export async function waitForSettledPosition(locator: Locator): Promise<void> {
+  let previousTop: number | null = null;
+  await expect
+    .poll(
+      async () => {
+        const { y } = await readBox(locator);
+        const settled = previousTop === y;
+        previousTop = y;
+        return settled;
+      },
+      { message: "Expected the sheet to stop moving" },
+    )
+    .toBe(true);
+}

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

@@ -0,0 +1,83 @@
+import { expect, type Page } from "@playwright/test";
+import { getServerId } from "./server-id";
+
+export async function selectWorkspaceInSidebar(page: Page, workspaceId: string): Promise<void> {
+  const row = page.getByTestId(`sidebar-workspace-row-${getServerId()}:${workspaceId}`);
+  await expect(row).toBeVisible({ timeout: 30_000 });
+  await row.click();
+}
+
+async function openWorkspaceSidebarKebab(page: Page, workspaceId: string) {
+  const serverId = getServerId();
+  const row = page.getByTestId(`sidebar-workspace-row-${serverId}:${workspaceId}`);
+  await expect(row).toBeVisible({ timeout: 30_000 });
+  await row.hover();
+
+  const kebab = page.getByTestId(`sidebar-workspace-kebab-${serverId}:${workspaceId}`);
+  await expect(kebab).toBeVisible({ timeout: 10_000 });
+  await kebab.click();
+
+  return serverId;
+}
+
+export async function expectWorkspaceListed(page: Page, name: string): Promise<void> {
+  await expect(
+    page.locator('[data-testid^="sidebar-workspace-row-"]').filter({ hasText: name }).first(),
+  ).toBeVisible({ timeout: 30_000 });
+}
+
+// The workspace row kebab and its menu items carry no web ARIA role, so the sidebar
+// suite addresses them by the stable test ids the app assigns per workspace — the same
+// convention the rename flow uses. The kebab only reveals on hover.
+export async function clickArchiveWorkspaceMenuItem(
+  page: Page,
+  workspaceId: string,
+): Promise<void> {
+  const serverId = await openWorkspaceSidebarKebab(page, workspaceId);
+  const archiveItem = page.getByTestId(`sidebar-workspace-menu-archive-${serverId}:${workspaceId}`);
+  await expect(archiveItem).toBeVisible({ timeout: 10_000 });
+  await archiveItem.click();
+}
+
+export async function pinWorkspaceFromSidebar(page: Page, workspaceId: string): Promise<void> {
+  const serverId = await openWorkspaceSidebarKebab(page, workspaceId);
+  const pinItem = page.getByTestId(`sidebar-workspace-menu-pin-${serverId}:${workspaceId}`);
+  await expect(pinItem).toBeVisible({ timeout: 10_000 });
+  await pinItem.click();
+}
+
+export async function archiveWorkspaceFromSidebar(page: Page, workspaceId: string): Promise<void> {
+  // A clean workspace archives with no prompt. Managed worktree backing may raise
+  // a browser confirm for unsynced work, so accept it when present.
+  page.once("dialog", (dialog) => void dialog.accept());
+  await clickArchiveWorkspaceMenuItem(page, workspaceId);
+}
+
+export async function expectWorkspaceAbsentFromSidebar(
+  page: Page,
+  workspaceId: string,
+): Promise<void> {
+  await expect(
+    page.getByTestId(`sidebar-workspace-row-${getServerId()}:${workspaceId}`),
+  ).toHaveCount(0, { timeout: 30_000 });
+}
+
+export async function openMobileAgentSidebar(page: Page): Promise<void> {
+  await page.getByRole("button", { name: "Open menu" }).click();
+}
+
+export async function closeMobileAgentSidebar(page: Page): Promise<void> {
+  const closeButton = page.getByTestId("sidebar-close");
+  await expect(closeButton).toBeInViewport({ ratio: 1, timeout: 5_000 });
+  await closeButton.click();
+}
+
+// The mobile sidebar panel animates via translateX. Waiting for its header to be fully visible
+// prevents a close click from targeting a button while the panel is still moving.
+export async function expectMobileAgentSidebarVisible(page: Page): Promise<void> {
+  await expect(page.getByTestId("sidebar-sessions")).toBeInViewport({ ratio: 1, timeout: 5_000 });
+}
+
+export async function expectMobileAgentSidebarHidden(page: Page): Promise<void> {
+  await expect(page.getByTestId("sidebar-sessions")).not.toBeInViewport({ timeout: 5_000 });
+}

packages/app/e2e/support/helpers/speech-env.ts

@@ -0,0 +1,32 @@
+const LOCAL_SPEECH_ENV_KEYS = [
+  "PASEO_LOCAL_MODELS_DIR",
+  "PASEO_DICTATION_LOCAL_STT_MODEL",
+  "PASEO_VOICE_LOCAL_STT_MODEL",
+  "PASEO_VOICE_LOCAL_TTS_MODEL",
+  "PASEO_VOICE_LOCAL_TTS_SPEAKER_ID",
+  "PASEO_VOICE_LOCAL_TTS_SPEED",
+] as const;
+
+const DISABLED_E2E_SPEECH_ENV = {
+  PASEO_DICTATION_ENABLED: "0",
+  PASEO_VOICE_MODE_ENABLED: "0",
+  PASEO_DICTATION_STT_PROVIDER: "openai",
+  PASEO_VOICE_TURN_DETECTION_PROVIDER: "openai",
+  PASEO_VOICE_STT_PROVIDER: "openai",
+  PASEO_VOICE_TTS_PROVIDER: "openai",
+} as const;
+
+export function withDisabledE2ESpeechEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  // Default app E2E does not cover speech flows; keep restarts from starting
+  // background local-model downloads for unrelated tests.
+  const next: NodeJS.ProcessEnv = {
+    ...env,
+    ...DISABLED_E2E_SPEECH_ENV,
+  };
+
+  for (const key of LOCAL_SPEECH_ENV_KEYS) {
+    delete next[key];
+  }
+
+  return next;
+}

packages/app/e2e/support/helpers/startup-dsl.ts

@@ -0,0 +1,250 @@
+import type { Route } from "@playwright/test";
+import { expect, type Page } from "../fixtures";
+import { buildCreateAgentPreferences, buildSeededHost } from "./daemon-registry";
+import { wsRoutePatternForPort } from "./daemon-port";
+
+const DISABLE_DEFAULT_SEED_ONCE_KEY = "@paseo:e2e-disable-default-seed-once";
+const SEED_NONCE_KEY = "@paseo:e2e-seed-nonce";
+const REGISTRY_KEY = "@paseo:daemon-registry";
+const E2E_KEY = "@paseo:e2e";
+const STORAGE_SEED_HTML = "<!doctype html><html><body>storage seed</body></html>";
+
+interface SavedHostInput {
+  serverId: string;
+  label: string;
+  endpoint: string;
+}
+
+export function startupScenario(page: Page) {
+  return new StartupScenario(page);
+}
+
+class StartupScenario {
+  private readonly page: Page;
+  private savedHosts: SavedHostInput[] = [];
+  private desktopBridge = false;
+  private blockedEndpointPorts = new Set<string>();
+  private viewport: { width: number; height: number } | null = null;
+
+  constructor(page: Page) {
+    this.page = page;
+  }
+
+  withMobileViewport(): this {
+    this.viewport = { width: 390, height: 844 };
+    return this;
+  }
+
+  withSavedHost(input: SavedHostInput): this {
+    this.savedHosts.push(input);
+    const port = input.endpoint.match(/:(\d+)$/)?.[1];
+    if (port) {
+      this.blockedEndpointPorts.add(port);
+    }
+    return this;
+  }
+
+  withPendingDesktopDaemon(): this {
+    this.desktopBridge = true;
+    return this;
+  }
+
+  withBlockedPort(port: string): this {
+    this.blockedEndpointPorts.add(port);
+    return this;
+  }
+
+  async openRoot(): Promise<StartupAssertions> {
+    await this.prepare();
+    await this.page.goto("/");
+    return new StartupAssertions(this.page);
+  }
+
+  async openHostWorkspace(input: {
+    serverId: string;
+    workspaceId: string;
+  }): Promise<StartupAssertions> {
+    await this.prepare();
+    await this.page.goto(
+      `/h/${encodeURIComponent(input.serverId)}/workspace/${encodeURIComponent(input.workspaceId)}`,
+    );
+    return new StartupAssertions(this.page);
+  }
+
+  private async prepare(): Promise<void> {
+    if (this.viewport) {
+      await this.page.setViewportSize(this.viewport);
+    }
+
+    if (this.desktopBridge) {
+      await installPendingDesktopBridge(this.page);
+    }
+
+    for (const port of this.blockedEndpointPorts) {
+      await this.page.routeWebSocket(wsRoutePatternForPort(port), async (ws) => {
+        await ws.close({ code: 1008, reason: "Blocked unreachable startup test host." });
+      });
+    }
+
+    if (this.savedHosts.length === 0) {
+      return;
+    }
+
+    // Create same-origin storage without booting the app. If the default host runtime
+    // starts first, it can race this scenario's registry override during CI.
+    await openStorageSeedDocument(this.page);
+    const nowIso = new Date().toISOString();
+    const registry = this.savedHosts.map((host) =>
+      buildStoredHost({
+        serverId: host.serverId,
+        endpoint: host.endpoint,
+        label: host.label,
+        nowIso,
+      }),
+    );
+    const firstHost = registry[0];
+    if (!firstHost) {
+      throw new Error("Expected at least one startup test host.");
+    }
+    const createAgentPreferences = buildStoredCreateAgentPreferences(firstHost.serverId);
+
+    await this.page.evaluate(
+      ({ keys, registry: storedRegistry, createAgentPreferences: storedPreferences }) => {
+        const nonce = localStorage.getItem(keys.seedNonce);
+        if (!nonce) {
+          throw new Error("Expected e2e seed nonce before overriding startup registry.");
+        }
+
+        localStorage.setItem(keys.e2e, "1");
+        localStorage.setItem(keys.registry, JSON.stringify(storedRegistry));
+        localStorage.setItem("@paseo:create-agent-preferences", JSON.stringify(storedPreferences));
+        localStorage.setItem(keys.disableDefaultSeedOnce, nonce);
+      },
+      {
+        keys: {
+          disableDefaultSeedOnce: DISABLE_DEFAULT_SEED_ONCE_KEY,
+          e2e: E2E_KEY,
+          registry: REGISTRY_KEY,
+          seedNonce: SEED_NONCE_KEY,
+        },
+        registry,
+        createAgentPreferences,
+      },
+    );
+  }
+}
+
+async function openStorageSeedDocument(page: Page): Promise<void> {
+  await page.route(
+    "**/*",
+    async (route: Route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: "text/html",
+        body: STORAGE_SEED_HTML,
+      });
+    },
+    { times: 1 },
+  );
+  await page.goto("/");
+}
+
+class StartupAssertions {
+  private readonly page: Page;
+
+  constructor(page: Page) {
+    this.page = page;
+  }
+
+  async expectsSavedHostShell(input: { serverId: string; label: string }): Promise<this> {
+    await this.page.getByRole("button", { name: "Open menu", exact: true }).click();
+    await this.page.getByTestId("sidebar-hosts-trigger").click();
+    const hostRow = this.page.getByTestId(`sidebar-host-row-${input.serverId}`);
+    await expect(hostRow).toBeVisible({ timeout: 15_000 });
+    await expect(hostRow).toContainText(input.label);
+    await expect(this.page.getByTestId("sidebar-add-project")).toBeVisible();
+    await expect(this.page.getByTestId("sidebar-home")).toBeVisible();
+    await expect(this.page.getByTestId("sidebar-settings")).toBeVisible();
+    await expect(this.page.getByTestId("welcome-screen")).toHaveCount(0);
+    return this;
+  }
+
+  async expectsNoSavedHostErrorStatus(): Promise<this> {
+    await expect(this.page.getByText("Connection error", { exact: true })).toHaveCount(0);
+    await expect(this.page.getByText("Offline", { exact: true })).toHaveCount(0);
+    return this;
+  }
+
+  async expectsNoLocalServerStartupCopy(): Promise<this> {
+    await expect(this.page.getByText("Starting local server...", { exact: true })).toHaveCount(0);
+    await expect(this.page.getByText("Connecting to local server...", { exact: true })).toHaveCount(
+      0,
+    );
+    return this;
+  }
+
+  async expectsDesktopDaemonStartup(): Promise<this> {
+    await expect(this.page.getByTestId("startup-splash")).toBeVisible({
+      timeout: 15_000,
+    });
+    return this;
+  }
+
+  async expectsSidebarHidden(): Promise<this> {
+    await expect(this.page.locator('[data-testid="sidebar-settings"]:visible')).toHaveCount(0);
+    await expect(this.page.locator('[data-testid="sidebar-project-list"]:visible')).toHaveCount(0);
+    return this;
+  }
+
+  async expectsNoUndefinedRoute(): Promise<this> {
+    await expect(this.page).not.toHaveURL(/\/h\/undefined\/workspace\/undefined/);
+    return this;
+  }
+}
+
+async function installPendingDesktopBridge(page: Page): Promise<void> {
+  await page.addInitScript(() => {
+    (window as unknown as { paseoDesktop: unknown }).paseoDesktop = {
+      platform: "darwin",
+      invoke: async (command: string) => {
+        if (command === "start_desktop_daemon") {
+          await new Promise(() => {
+            // Keep the daemon in the startup phase until the test ends.
+          });
+        }
+        if (command === "desktop_daemon_status") {
+          return {
+            serverId: "srv_desktop_pending",
+            status: "starting",
+            listen: null,
+            hostname: null,
+            pid: null,
+            home: "",
+            version: null,
+            desktopManaged: true,
+            error: null,
+          };
+        }
+        if (command === "desktop_daemon_logs") {
+          return { logPath: "", contents: "" };
+        }
+        return null;
+      },
+      getPendingOpenProject: async () => null,
+      events: { on: async () => () => undefined },
+    };
+  });
+}
+
+function buildStoredHost(input: {
+  serverId: string;
+  endpoint: string;
+  label: string;
+  nowIso: string;
+}) {
+  return buildSeededHost(input);
+}
+
+function buildStoredCreateAgentPreferences(serverId: string) {
+  return buildCreateAgentPreferences(serverId);
+}

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

@@ -0,0 +1,148 @@
+import { PARENT_AGENT_ID_LABEL } from "@getpaseo/protocol/agent-labels";
+import { expect, type Page } from "@playwright/test";
+import type { SeededWorkspace } from "./seed-client";
+
+export interface SeededSubagentPair {
+  parent: {
+    id: string;
+    title: string;
+  };
+  child: {
+    id: string;
+    title: string;
+  };
+  workspaceId: string;
+}
+
+export interface SeededCrossWorkspaceSubagentPair {
+  parent: {
+    id: string;
+    workspaceId: string;
+  };
+  child: {
+    id: string;
+    workspaceId: string;
+  };
+}
+
+export async function seedParentWithSubagent(
+  workspace: Pick<SeededWorkspace, "client" | "repoPath" | "workspaceId">,
+  input: { parentTitle: string; childTitle: string },
+): Promise<SeededSubagentPair> {
+  const parent = await workspace.client.createAgent({
+    provider: "mock",
+    cwd: workspace.repoPath,
+    workspaceId: workspace.workspaceId,
+    title: input.parentTitle,
+    modeId: "load-test",
+    model: "ten-second-stream",
+  });
+  const child = await workspace.client.createAgent({
+    provider: "mock",
+    cwd: workspace.repoPath,
+    workspaceId: workspace.workspaceId,
+    title: input.childTitle,
+    modeId: "load-test",
+    model: "ten-second-stream",
+    labels: {
+      [PARENT_AGENT_ID_LABEL]: parent.id,
+    },
+  });
+
+  return {
+    parent: {
+      id: parent.id,
+      title: input.parentTitle,
+    },
+    child: {
+      id: child.id,
+      title: input.childTitle,
+    },
+    workspaceId: workspace.workspaceId,
+  };
+}
+
+export async function seedParentWithCrossWorkspaceSubagent(
+  workspace: Pick<SeededWorkspace, "client" | "repoPath" | "workspaceId" | "projectId">,
+  input: { parentTitle: string; childTitle: string },
+): Promise<SeededCrossWorkspaceSubagentPair> {
+  const parent = await workspace.client.createAgent({
+    provider: "mock",
+    cwd: workspace.repoPath,
+    workspaceId: workspace.workspaceId,
+    title: input.parentTitle,
+    modeId: "load-test",
+    model: "ten-second-stream",
+  });
+  const createdWorkspace = await workspace.client.createWorkspace({
+    source: {
+      kind: "directory",
+      path: workspace.repoPath,
+      projectId: workspace.projectId,
+    },
+    title: "Subagent workspace",
+  });
+  if (!createdWorkspace.workspace) {
+    throw new Error(createdWorkspace.error ?? "Failed to create subagent workspace");
+  }
+
+  const child = await workspace.client.createAgent({
+    provider: "mock",
+    cwd: workspace.repoPath,
+    workspaceId: createdWorkspace.workspace.id,
+    title: input.childTitle,
+    modeId: "load-test",
+    model: "five-minute-stream",
+    initialPrompt: "stay running",
+    labels: {
+      [PARENT_AGENT_ID_LABEL]: parent.id,
+    },
+  });
+  await workspace.client.waitForAgentUpsert(
+    child.id,
+    (snapshot) => snapshot.status === "running",
+    15_000,
+  );
+
+  return {
+    parent: {
+      id: parent.id,
+      workspaceId: workspace.workspaceId,
+    },
+    child: {
+      id: child.id,
+      workspaceId: createdWorkspace.workspace.id,
+    },
+  };
+}
+
+export async function openSubagentsTrack(page: Page): Promise<void> {
+  await page.getByTestId("subagents-track-header").click();
+}
+
+export async function expectSubagentRowVisible(page: Page, childId: string): Promise<void> {
+  await expect(page.getByTestId(`subagents-track-row-${childId}`)).toBeVisible({
+    timeout: 30_000,
+  });
+}
+
+export async function expectSubagentRowGone(page: Page, childId: string): Promise<void> {
+  await expect(page.getByTestId(`subagents-track-row-${childId}`)).toHaveCount(0, {
+    timeout: 30_000,
+  });
+}
+
+export async function detachSubagentFromTrack(page: Page, childId: string): Promise<void> {
+  const row = page.getByTestId(`subagents-track-row-${childId}`);
+  await expect(row).toBeVisible({ timeout: 30_000 });
+  await row.hover();
+
+  page.once("dialog", (dialog) => {
+    expect(dialog.message()).toContain("Detach subagent?");
+    void dialog.accept();
+  });
+
+  const detachButton = page.getByTestId(`subagents-track-detach-${childId}`);
+  await expect(detachButton).toBeVisible({ timeout: 30_000 });
+  await detachButton.click();
+}

packages/app/e2e/support/helpers/terminal-dsl.ts

@@ -0,0 +1,156 @@
+import type { Page } from "@playwright/test";
+import type { TerminalActivity, TerminalActivityState } from "@getpaseo/protocol/terminal-activity";
+import { createTempGitRepo } from "./workspace";
+import { navigateToTerminal, setupDeterministicPrompt } from "./terminal-perf";
+import { connectSeedClient, type SeedDaemonClient } from "./seed-client";
+
+interface TempRepo {
+  path: string;
+  cleanup: () => Promise<void>;
+}
+
+export interface TerminalInstance {
+  id: string;
+  name: string;
+  cwd: string;
+}
+
+interface CreateTerminalInput {
+  name: string;
+  command?: string;
+  args?: string[];
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export class TerminalE2EHarness {
+  readonly client: SeedDaemonClient;
+  readonly tempRepo: TempRepo;
+  readonly projectId: string;
+  readonly workspaceId: string;
+
+  private constructor(input: {
+    client: SeedDaemonClient;
+    tempRepo: TempRepo;
+    projectId: string;
+    workspaceId: string;
+  }) {
+    this.client = input.client;
+    this.tempRepo = input.tempRepo;
+    this.projectId = input.projectId;
+    this.workspaceId = input.workspaceId;
+  }
+
+  static async create(input: { tempPrefix: string }): Promise<TerminalE2EHarness> {
+    const tempRepo = await createTempGitRepo(input.tempPrefix);
+    const client = await connectSeedClient();
+    const seedResult = await client.createWorkspace({
+      source: { kind: "directory", path: tempRepo.path },
+    });
+    if (!seedResult.workspace) {
+      await client.close().catch(() => {});
+      await tempRepo.cleanup().catch(() => {});
+      throw new Error(seedResult.error ?? "Failed to seed workspace");
+    }
+    return new TerminalE2EHarness({
+      client,
+      tempRepo,
+      projectId: seedResult.workspace.projectId,
+      workspaceId: seedResult.workspace.id,
+    });
+  }
+
+  async cleanup(): Promise<void> {
+    await this.client.removeProject(this.projectId).catch(() => {});
+    await this.client.close().catch(() => {});
+    await this.tempRepo.cleanup().catch(() => {});
+  }
+
+  async createTerminal(input: CreateTerminalInput): Promise<TerminalInstance> {
+    const options =
+      input.command || input.args
+        ? {
+            command: input.command,
+            args: input.args,
+            workspaceId: this.workspaceId,
+          }
+        : { workspaceId: this.workspaceId };
+    const result = await this.client.createTerminal(
+      this.tempRepo.path,
+      input.name,
+      undefined,
+      options,
+    );
+    if (!result.terminal) {
+      throw new Error(`Failed to create terminal: ${result.error}`);
+    }
+    return result.terminal;
+  }
+
+  async waitForTerminalActivity(input: {
+    terminalId: string;
+    state: TerminalActivityState | null;
+    attentionReason?: TerminalActivity["attentionReason"] | null;
+    timeoutMs?: number;
+  }): Promise<void> {
+    const timeoutMs = input.timeoutMs ?? 10_000;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const result = await this.client.listTerminals(this.tempRepo.path, undefined, {
+        workspaceId: this.workspaceId,
+      });
+      const terminal = result.terminals.find((entry) => entry.id === input.terminalId);
+      const activity = terminal?.activity ?? null;
+      const attentionMatches =
+        input.attentionReason === undefined ||
+        (activity?.attentionReason ?? null) === input.attentionReason;
+      if ((activity?.state ?? null) === input.state && attentionMatches) {
+        return;
+      }
+      await sleep(50);
+    }
+    const attentionSuffix =
+      input.attentionReason === undefined
+        ? ""
+        : ` with attention ${input.attentionReason ?? "none"}`;
+    throw new Error(
+      `Timed out waiting for terminal ${input.terminalId} activity state ${input.state ?? "unknown"}${attentionSuffix}`,
+    );
+  }
+
+  async killTerminal(terminalId: string): Promise<void> {
+    await this.client.killTerminal(terminalId).catch(() => {});
+  }
+
+  async openTerminal(page: Page, input: { terminalId: string }): Promise<void> {
+    await navigateToTerminal(page, {
+      workspaceId: this.workspaceId,
+      terminalId: input.terminalId,
+    });
+  }
+
+  terminalSurface(page: Page) {
+    return page.locator('[data-testid="terminal-surface"]');
+  }
+
+  async setupPrompt(page: Page, sentinel?: string): Promise<void> {
+    await setupDeterministicPrompt(page, sentinel);
+  }
+}
+
+export async function withTerminalInApp<T>(
+  page: Page,
+  harness: TerminalE2EHarness,
+  input: { name: string },
+  fn: (terminal: TerminalInstance) => Promise<T>,
+): Promise<T> {
+  const terminal = await harness.createTerminal({ name: input.name });
+  try {
+    await harness.openTerminal(page, { terminalId: terminal.id });
+    return await fn(terminal);
+  } finally {
+    await harness.killTerminal(terminal.id);
+  }
+}

packages/app/e2e/support/helpers/terminal-perf.ts

@@ -0,0 +1,207 @@
+import { expect, type Page } from "@playwright/test";
+import { buildHostWorkspaceRoute } from "../../../src/utils/host-routes";
+import { getServerId } from "./server-id";
+
+export function buildTerminalWorkspaceUrl(workspaceId: string, terminalId: string): string {
+  const serverId = getServerId();
+  const route = buildHostWorkspaceRoute(serverId, workspaceId);
+  return `${route}?open=${encodeURIComponent(`terminal:${terminalId}`)}`;
+}
+
+function buildWorkspaceUrl(workspaceId: string): string {
+  return buildHostWorkspaceRoute(getServerId(), workspaceId);
+}
+
+export async function getTerminalBufferText(page: Page): Promise<string> {
+  return page.evaluate(() => {
+    const term = (
+      window as Window & {
+        __paseoTerminal?: {
+          buffer: {
+            active: {
+              length: number;
+              getLine: (i: number) => { translateToString: (trim: boolean) => string } | null;
+            };
+          };
+          onWriteParsed: (cb: () => void) => { dispose: () => void };
+        };
+      }
+    ).__paseoTerminal;
+    if (!term) {
+      return "";
+    }
+    const buf = term.buffer.active;
+    const lines: string[] = [];
+    for (let i = 0; i < buf.length; i++) {
+      const line = buf.getLine(i);
+      if (line) {
+        lines.push(line.translateToString(true));
+      }
+    }
+    return lines.join("\n");
+  });
+}
+
+export async function waitForTerminalContent(
+  page: Page,
+  predicate: (text: string) => boolean,
+  timeout: number,
+): Promise<void> {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    const text = await getTerminalBufferText(page);
+    if (predicate(text)) {
+      return;
+    }
+    await page.waitForTimeout(50);
+  }
+  throw new Error(`Terminal content did not match predicate within ${timeout}ms`);
+}
+
+export async function navigateToTerminal(
+  page: Page,
+  input: { workspaceId: string; terminalId: string },
+): Promise<void> {
+  // Boot the app at the workspace route directly.
+  // The fixtures.ts beforeEach addInitScript seeds localStorage on every navigation,
+  // so the daemon registry is already configured when the app starts.
+  const workspaceRoute = buildTerminalWorkspaceUrl(input.workspaceId, input.terminalId);
+  await page.goto(workspaceRoute);
+
+  // The workspace layout consumes `?open=...`, returns null during the effect,
+  // then replaces the URL with the clean workspace route after preparing the tab.
+  // On CI, Expo Router's rootNavigationState may take time to initialize,
+  // so we allow a generous timeout here.
+  const cleanWorkspaceRoute = buildWorkspaceUrl(input.workspaceId);
+  await page.waitForURL(
+    (url) => url.pathname === cleanWorkspaceRoute && !url.searchParams.has("open"),
+    { timeout: 30_000 },
+  );
+
+  // The open intent should have prepared and focused the exact pre-created terminal tab.
+  // Its presence is the user-visible proof that workspace and terminal state have hydrated.
+  // The tab reconciliation effect also auto-creates terminal tabs once hydration completes,
+  // so we give it enough time for the full workspace hydration + tab creation cycle.
+  const terminalTab = page.locator(`[data-testid="workspace-tab-terminal_${input.terminalId}"]`);
+  await terminalTab.waitFor({ state: "visible", timeout: 30_000 });
+  await terminalTab.click();
+
+  const terminalSurface = page.locator('[data-testid="terminal-surface"]');
+  await terminalSurface.waitFor({ state: "visible", timeout: 15_000 });
+
+  // Wait for loading overlay to disappear (terminal attached)
+  await page
+    .locator('[data-testid="terminal-attach-loading"]')
+    .waitFor({ state: "hidden", timeout: 10_000 })
+    .catch(() => {
+      // overlay may never appear if attachment is instant
+    });
+
+  await terminalSurface.scrollIntoViewIfNeeded();
+  await terminalSurface.click();
+}
+
+export async function setupDeterministicPrompt(page: Page, sentinel?: string): Promise<void> {
+  const tag = sentinel ?? `READY_${Date.now()}`;
+  const terminal = page.locator('[data-testid="terminal-surface"]');
+
+  await terminal.pressSequentially(`echo ${tag}\n`, { delay: 0 });
+  await waitForTerminalContent(page, (text) => text.includes(tag), 10_000);
+
+  await terminal.pressSequentially("export PS1='$ '\n", { delay: 0 });
+  await page.waitForTimeout(300);
+}
+
+export interface LatencySample {
+  char: string;
+  latencyMs: number;
+}
+
+/**
+ * Measures keystroke echo round-trip latency.
+ *
+ * Starts a high-resolution timer on the browser keydown event (capture phase)
+ * and stops it when xterm.js finishes parsing the echoed write. This measures
+ * the full path: keydown → WebSocket → daemon PTY echo → WebSocket → xterm render.
+ */
+export async function measureKeystrokeLatency(page: Page, char: string): Promise<number> {
+  await page.evaluate(() => {
+    const win = window as Window & {
+      __paseoTerminal?: { onWriteParsed: (cb: () => void) => { dispose: () => void } };
+      __perfKeystroke?: { promise: Promise<number> | null };
+    };
+    if (!win.__paseoTerminal) {
+      throw new Error("__paseoTerminal not available");
+    }
+    const term = win.__paseoTerminal;
+
+    const state = (win.__perfKeystroke = {
+      promise: null as Promise<number> | null,
+    });
+
+    state.promise = new Promise<number>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        document.removeEventListener("keydown", onKeyDown, true);
+        reject(new Error("keystroke echo timeout (5s)"));
+      }, 5000);
+
+      function onKeyDown() {
+        document.removeEventListener("keydown", onKeyDown, true);
+        const start = performance.now();
+        const disposable = term.onWriteParsed(() => {
+          clearTimeout(timeout);
+          disposable.dispose();
+          resolve(performance.now() - start);
+        });
+      }
+
+      document.addEventListener("keydown", onKeyDown, true);
+    });
+  });
+
+  await page.keyboard.press(char);
+
+  return page.evaluate(
+    () =>
+      (window as unknown as { __perfKeystroke: { promise: Promise<number> } }).__perfKeystroke
+        .promise,
+  );
+}
+
+export async function expectTerminalSurfaceVisible(
+  page: Page,
+  options?: { timeout?: number },
+): Promise<void> {
+  await expect(page.locator('[data-testid="terminal-surface"]').first()).toBeVisible({
+    timeout: options?.timeout ?? 20_000,
+  });
+}
+
+export async function focusTerminalSurface(page: Page): Promise<void> {
+  await expectTerminalSurfaceVisible(page);
+  await page.locator('[data-testid="terminal-surface"]').first().click();
+}
+
+export async function typeInTerminal(page: Page, text: string): Promise<void> {
+  await page
+    .locator('[data-testid="terminal-surface"]')
+    .first()
+    .pressSequentially(text, { delay: 0 });
+}
+
+export async function waitForTerminalAttached(page: Page): Promise<void> {
+  await page
+    .locator('[data-testid="terminal-attach-loading"]')
+    .waitFor({ state: "hidden", timeout: 10_000 })
+    .catch(() => undefined);
+}
+
+export function computePercentile(samples: number[], p: number): number {
+  const sorted = [...samples].sort((a, b) => a - b);
+  const index = Math.ceil((p / 100) * sorted.length) - 1;
+  return sorted[Math.max(0, index)];
+}
+
+export function round2(value: number): number {
+  return Math.round(value * 100) / 100;
+}

packages/app/e2e/support/helpers/terminal-probes.ts

@@ -0,0 +1,711 @@
+import type { Page } from "@playwright/test";
+
+export interface TerminalRenderProbeSnapshot {
+  setCount: number;
+  unsetCount: number;
+  writeCount: number;
+  resetWrites: number;
+  clearScreenWrites: number;
+  altEnterWrites: number;
+  altExitWrites: number;
+  events: TerminalRenderProbeEvent[];
+  frames: TerminalFrame[];
+}
+
+export interface TerminalRenderProbeEvent {
+  at: number;
+  type: "set" | "unset" | "reset-write" | "clear-write" | "alt-enter-write" | "alt-exit-write";
+  preview?: string;
+}
+
+export interface TerminalFrame {
+  at: number;
+  rowCount: number;
+  nonEmptyRows: number;
+  firstNonEmptyRow: number | null;
+  text: string;
+  topText: string;
+}
+
+export type TerminalRenderProbeSummary = Omit<TerminalRenderProbeSnapshot, "frames"> & {
+  frameCount: number;
+};
+
+export interface TerminalKeystrokeStressReport {
+  inputTextLength: number;
+  keydownCount: number;
+  inputFrameCount: number;
+  outputFrameCount: number;
+  textMessageFrameCount: number;
+  textMessagePayloadBytes: number;
+  largeTextMessageCount: number;
+  largestTextMessageBytes: number;
+  agentStreamTextMessageCount: number;
+  agentStreamTextMessagePayloadBytes: number;
+  largeAgentStreamTextMessageCount: number;
+  largestAgentStreamTextMessageBytes: number;
+  appEventCount: number;
+  appEventCounts: Record<string, number>;
+  runtimeMaxQueueDepth: number;
+  xtermWriteCount: number;
+  inputFramePayloadBytes: number;
+  outputFramePayloadBytes: number;
+  keydownToInputFrameMs: LatencyStats | null;
+  inputFrameToOutputFrameMs: LatencyStats | null;
+  appBinaryReceivedToFrameDecodedMs: LatencyStats | null;
+  appFrameDecodedToTerminalEmitMs: LatencyStats | null;
+  appTerminalEmitListenerDurationMs: LatencyStats | null;
+  appTerminalEmitToStreamControllerOutputMs: LatencyStats | null;
+  appStreamControllerDecodeToOnOutputMs: LatencyStats | null;
+  appStreamControllerToEmulatorWriteMs: LatencyStats | null;
+  appEmulatorWriteToRuntimeEnqueuedMs: LatencyStats | null;
+  appRuntimeEnqueuedToOperationStartMs: LatencyStats | null;
+  appRuntimeOperationStartToXtermWriteMs: LatencyStats | null;
+  appRuntimeXtermWriteToCommitMs: LatencyStats | null;
+  appBinaryReceivedToRuntimeEnqueuedMs: LatencyStats | null;
+  appBinaryReceivedToRuntimeOperationStartMs: LatencyStats | null;
+  appBinaryReceivedToXtermCommitMs: LatencyStats | null;
+  outputFrameToXtermWriteMs: LatencyStats | null;
+  xtermWriteDurationMs: LatencyStats | null;
+  keydownToXtermCommitMs: LatencyStats | null;
+  firstKeydownAt: number | null;
+  lastXtermCommitAt: number | null;
+}
+
+export interface LatencyStats {
+  count: number;
+  minMs: number;
+  p50Ms: number;
+  p95Ms: number;
+  maxMs: number;
+  avgMs: number;
+}
+
+export async function installTerminalRenderProbe(page: Page): Promise<void> {
+  await page.addInitScript(() => {
+    interface ProbeTerm {
+      write?: (data: string | Uint8Array, callback?: () => void) => void;
+      __paseoRenderProbeWriteWrapped?: boolean;
+    }
+    interface ProbeState {
+      term: ProbeTerm | undefined;
+      setCount: number;
+      unsetCount: number;
+      writeCount: number;
+      resetWrites: number;
+      clearScreenWrites: number;
+      altEnterWrites: number;
+      altExitWrites: number;
+      events: TerminalRenderProbeEvent[];
+      frames: TerminalFrame[];
+      rafId: number | null;
+      sampleUntil: number;
+      reset: () => void;
+      snapshot: () => TerminalRenderProbeSnapshot;
+      startSampling: (durationMs: number) => void;
+    }
+
+    const win = window as unknown as Record<string, unknown> & {
+      __terminalRenderProbe?: ProbeState;
+      __paseoTerminal?: ProbeTerm;
+    };
+    const existingDescriptor = Object.getOwnPropertyDescriptor(win, "__paseoTerminal");
+    const getExisting = () =>
+      existingDescriptor?.get ? existingDescriptor.get.call(win) : existingDescriptor?.value;
+
+    const probe: ProbeState = {
+      term: getExisting(),
+      setCount: 0,
+      unsetCount: 0,
+      writeCount: 0,
+      resetWrites: 0,
+      clearScreenWrites: 0,
+      altEnterWrites: 0,
+      altExitWrites: 0,
+      events: [],
+      frames: [],
+      rafId: null,
+      sampleUntil: 0,
+      reset() {
+        this.setCount = 0;
+        this.unsetCount = 0;
+        this.writeCount = 0;
+        this.resetWrites = 0;
+        this.clearScreenWrites = 0;
+        this.altEnterWrites = 0;
+        this.altExitWrites = 0;
+        this.events = [];
+        this.frames = [];
+      },
+      snapshot() {
+        return {
+          setCount: this.setCount,
+          unsetCount: this.unsetCount,
+          writeCount: this.writeCount,
+          resetWrites: this.resetWrites,
+          clearScreenWrites: this.clearScreenWrites,
+          altEnterWrites: this.altEnterWrites,
+          altExitWrites: this.altExitWrites,
+          events: this.events,
+          frames: this.frames,
+        };
+      },
+      startSampling(durationMs: number) {
+        this.sampleUntil = performance.now() + durationMs;
+        if (this.rafId !== null) {
+          cancelAnimationFrame(this.rafId);
+        }
+        const sample = () => {
+          const rows = Array.from(document.querySelectorAll(".xterm-rows > div")).map(
+            (row) => row.textContent ?? "",
+          );
+          const nonEmptyRows = rows.filter((row) => row.trim().length > 0);
+          const firstNonEmptyRow = rows.findIndex((row) => row.trim().length > 0);
+          this.frames.push({
+            at: performance.now(),
+            rowCount: rows.length,
+            nonEmptyRows: nonEmptyRows.length,
+            firstNonEmptyRow: firstNonEmptyRow === -1 ? null : firstNonEmptyRow,
+            text: rows.join("\n"),
+            topText: rows.slice(0, 3).join("\n"),
+          });
+          if (performance.now() < this.sampleUntil) {
+            this.rafId = requestAnimationFrame(sample);
+          } else {
+            this.rafId = null;
+          }
+        };
+        this.rafId = requestAnimationFrame(sample);
+      },
+    };
+
+    Object.defineProperty(win, "__terminalRenderProbe", {
+      configurable: true,
+      value: probe,
+    });
+
+    Object.defineProperty(win, "__paseoTerminal", {
+      configurable: true,
+      get() {
+        return probe.term;
+      },
+      set(next: ProbeTerm | undefined) {
+        if (next === undefined) {
+          probe.unsetCount += 1;
+          probe.events.push({ at: performance.now(), type: "unset" });
+          probe.term = next;
+          return;
+        }
+
+        probe.setCount += 1;
+        probe.events.push({ at: performance.now(), type: "set" });
+        probe.term = next;
+
+        if (next?.write && !next.__paseoRenderProbeWriteWrapped) {
+          const originalWrite = next.write.bind(next);
+          next.write = (data: string | Uint8Array, callback?: () => void) => {
+            const text = typeof data === "string" ? data : new TextDecoder().decode(data);
+            probe.writeCount += 1;
+            const preview = text
+              .replaceAll("\u001b", "\\x1b")
+              .replace(/\r/g, "\\r")
+              .replace(/\n/g, "\\n")
+              .slice(0, 160);
+            if (text.includes("\u001bc")) {
+              probe.resetWrites += 1;
+              probe.events.push({ at: performance.now(), type: "reset-write", preview });
+            }
+            if (text.includes("\u001b[2J")) {
+              probe.clearScreenWrites += 1;
+              probe.events.push({ at: performance.now(), type: "clear-write", preview });
+            }
+            if (text.includes("\u001b[?1049h")) {
+              probe.altEnterWrites += 1;
+              probe.events.push({ at: performance.now(), type: "alt-enter-write", preview });
+            }
+            if (text.includes("\u001b[?1049l")) {
+              probe.altExitWrites += 1;
+              probe.events.push({ at: performance.now(), type: "alt-exit-write", preview });
+            }
+            return originalWrite(data, callback);
+          };
+          next.__paseoRenderProbeWriteWrapped = true;
+        }
+      },
+    });
+  });
+}
+
+interface TerminalRenderProbeWindow {
+  __terminalRenderProbe: {
+    reset: () => void;
+    startSampling: (durationMs: number) => void;
+    snapshot: () => TerminalRenderProbeSnapshot;
+  };
+}
+
+export async function resetTerminalRenderProbe(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    (window as unknown as TerminalRenderProbeWindow).__terminalRenderProbe.reset();
+  });
+}
+
+export async function startTerminalFrameSampling(page: Page, durationMs = 2500): Promise<void> {
+  await page.evaluate((ms) => {
+    (window as unknown as TerminalRenderProbeWindow).__terminalRenderProbe.startSampling(ms);
+  }, durationMs);
+}
+
+export async function readTerminalRenderProbe(page: Page): Promise<TerminalRenderProbeSnapshot> {
+  return page.evaluate(() =>
+    (window as unknown as TerminalRenderProbeWindow).__terminalRenderProbe.snapshot(),
+  );
+}
+
+export async function terminalVisibleText(page: Page): Promise<string> {
+  return page.evaluate(() =>
+    Array.from(document.querySelectorAll(".xterm-rows > div"))
+      .map((row) => row.textContent ?? "")
+      .join("\n"),
+  );
+}
+
+export function summarizeTerminalRenderProbe(
+  probe: TerminalRenderProbeSnapshot,
+): TerminalRenderProbeSummary {
+  return {
+    setCount: probe.setCount,
+    unsetCount: probe.unsetCount,
+    writeCount: probe.writeCount,
+    resetWrites: probe.resetWrites,
+    clearScreenWrites: probe.clearScreenWrites,
+    altEnterWrites: probe.altEnterWrites,
+    altExitWrites: probe.altExitWrites,
+    events: probe.events,
+    frameCount: probe.frames.length,
+  };
+}
+
+export async function installTerminalKeystrokeStressProbe(page: Page): Promise<void> {
+  await page.addInitScript(() => {
+    interface TimedTextEvent {
+      at: number;
+      text: string;
+      bytes: number;
+    }
+    interface TimedTextMessageEvent {
+      at: number;
+      bytes: number;
+      kind: string | null;
+    }
+    interface XtermWriteEvent {
+      at: number;
+      committedAt: number | null;
+      text: string;
+      bytes: number;
+    }
+    interface AppProbeEvent {
+      type: string;
+      at: number;
+      bytes?: number;
+      queueDepth?: number;
+    }
+    interface StressProbeState {
+      keydowns: Array<{ at: number; key: string }>;
+      inputFrames: TimedTextEvent[];
+      outputFrames: TimedTextEvent[];
+      textMessageFrames: TimedTextMessageEvent[];
+      xtermWrites: XtermWriteEvent[];
+      appEvents: AppProbeEvent[];
+      reset: () => void;
+      report: (inputText: string) => TerminalKeystrokeStressReport;
+    }
+
+    const INPUT_OPCODE = 0x02;
+    const OUTPUT_OPCODE = 0x01;
+    const decoder = new TextDecoder();
+
+    function bytesFrom(data: unknown): Uint8Array | null {
+      if (data instanceof Uint8Array) return data;
+      if (data instanceof ArrayBuffer) return new Uint8Array(data);
+      if (ArrayBuffer.isView(data)) {
+        return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+      }
+      return null;
+    }
+
+    function eventDataBytes(data: unknown): Promise<Uint8Array | null> {
+      const bytes = bytesFrom(data);
+      if (bytes) return Promise.resolve(bytes);
+      if (typeof Blob !== "undefined" && data instanceof Blob) {
+        return data.arrayBuffer().then((buffer) => new Uint8Array(buffer));
+      }
+      return Promise.resolve(null);
+    }
+
+    function frameText(bytes: Uint8Array): string {
+      return decoder.decode(bytes.slice(2));
+    }
+
+    function eventDataText(data: unknown): Promise<string | null> {
+      if (typeof data === "string") {
+        return Promise.resolve(data);
+      }
+      if (typeof Blob !== "undefined" && data instanceof Blob) {
+        return data.text();
+      }
+      return Promise.resolve(null);
+    }
+
+    function textMessageKind(text: string): string | null {
+      try {
+        const parsed = JSON.parse(text) as {
+          type?: unknown;
+          message?: {
+            type?: unknown;
+          };
+        };
+        if (typeof parsed.type !== "string") {
+          return null;
+        }
+        if (typeof parsed.message?.type === "string") {
+          return `${parsed.type}:${parsed.message.type}`;
+        }
+        return parsed.type;
+      } catch {
+        return null;
+      }
+    }
+
+    function summarize(values: number[]): LatencyStats | null {
+      if (values.length === 0) return null;
+      const sorted = [...values].sort((a, b) => a - b);
+      const percentile = (p: number) => {
+        const index = Math.ceil((p / 100) * sorted.length) - 1;
+        return sorted[Math.max(0, Math.min(sorted.length - 1, index))];
+      };
+      const total = values.reduce((sum, value) => sum + value, 0);
+      const round2 = (value: number) => Math.round(value * 100) / 100;
+      return {
+        count: values.length,
+        minMs: round2(sorted[0] ?? 0),
+        p50Ms: round2(percentile(50)),
+        p95Ms: round2(percentile(95)),
+        maxMs: round2(sorted[sorted.length - 1] ?? 0),
+        avgMs: round2(total / values.length),
+      };
+    }
+
+    function firstAtOrAfter<T extends { at: number }>(events: T[], at: number): T | null {
+      return events.find((event) => event.at >= at) ?? null;
+    }
+
+    function firstCommitAtOrAfter(events: XtermWriteEvent[], at: number): XtermWriteEvent | null {
+      return (
+        events.find((event) => typeof event.committedAt === "number" && event.committedAt >= at) ??
+        null
+      );
+    }
+
+    function countByType(events: AppProbeEvent[]): Record<string, number> {
+      const counts: Record<string, number> = {};
+      for (const event of events) {
+        counts[event.type] = (counts[event.type] ?? 0) + 1;
+      }
+      return counts;
+    }
+
+    function appEventsOf(type: string, events: AppProbeEvent[]): AppProbeEvent[] {
+      return events.filter((event) => event.type === type);
+    }
+
+    function latencyByIndex(from: AppProbeEvent[], to: AppProbeEvent[]): number[] {
+      const count = Math.min(from.length, to.length);
+      const values: number[] = [];
+      for (let index = 0; index < count; index += 1) {
+        values.push(to[index].at - from[index].at);
+      }
+      return values;
+    }
+
+    const probe: StressProbeState = {
+      keydowns: [],
+      inputFrames: [],
+      outputFrames: [],
+      textMessageFrames: [],
+      xtermWrites: [],
+      appEvents: [],
+      reset() {
+        this.keydowns = [];
+        this.inputFrames = [];
+        this.outputFrames = [];
+        this.textMessageFrames = [];
+        this.xtermWrites = [];
+        this.appEvents = [];
+      },
+      report(inputText: string) {
+        const binaryReceived = appEventsOf("daemon-client-binary-received", this.appEvents);
+        const frameDecoded = appEventsOf("daemon-client-frame-decoded", this.appEvents);
+        const terminalEmit = appEventsOf("daemon-client-terminal-emit", this.appEvents);
+        const terminalEmitted = appEventsOf("daemon-client-terminal-emitted", this.appEvents);
+        const streamControllerOutput = appEventsOf("stream-controller-output", this.appEvents);
+        const streamControllerOnOutput = appEventsOf("stream-controller-on-output", this.appEvents);
+        const emulatorWriteOutput = appEventsOf("terminal-emulator-write-output", this.appEvents);
+        const runtimeWriteEnqueued = appEventsOf("runtime-write-enqueued", this.appEvents);
+        const runtimeOperationStart = appEventsOf("runtime-operation-start", this.appEvents);
+        const runtimeXtermWrite = appEventsOf("runtime-xterm-write", this.appEvents);
+        const runtimeXtermCommitted = appEventsOf("runtime-xterm-committed", this.appEvents);
+        const keydownToInputFrame = this.keydowns
+          .map((keydown) => firstAtOrAfter(this.inputFrames, keydown.at)?.at ?? null)
+          .filter((at): at is number => at !== null)
+          .map((at, index) => at - this.keydowns[index].at);
+        const inputFrameToOutputFrame = this.inputFrames
+          .map((input) => {
+            const output = firstAtOrAfter(this.outputFrames, input.at);
+            return output ? output.at - input.at : null;
+          })
+          .filter((value): value is number => value !== null);
+        const outputFrameToXtermWrite = this.outputFrames
+          .map((output) => {
+            const write = firstAtOrAfter(this.xtermWrites, output.at);
+            return write ? write.at - output.at : null;
+          })
+          .filter((value): value is number => value !== null);
+        const xtermWriteDurations = this.xtermWrites
+          .map((write) => (write.committedAt === null ? null : write.committedAt - write.at))
+          .filter((value): value is number => value !== null);
+        const keydownToXtermCommit = this.keydowns
+          .map((keydown) => {
+            const write = firstCommitAtOrAfter(this.xtermWrites, keydown.at);
+            return write?.committedAt ? write.committedAt - keydown.at : null;
+          })
+          .filter((value): value is number => value !== null);
+
+        return {
+          inputTextLength: inputText.length,
+          keydownCount: this.keydowns.length,
+          inputFrameCount: this.inputFrames.length,
+          outputFrameCount: this.outputFrames.length,
+          textMessageFrameCount: this.textMessageFrames.length,
+          textMessagePayloadBytes: this.textMessageFrames.reduce(
+            (sum, frame) => sum + frame.bytes,
+            0,
+          ),
+          largeTextMessageCount: this.textMessageFrames.filter((frame) => frame.bytes >= 50_000)
+            .length,
+          largestTextMessageBytes: Math.max(
+            0,
+            ...this.textMessageFrames.map((frame) => frame.bytes),
+          ),
+          agentStreamTextMessageCount: this.textMessageFrames.filter(
+            (frame) => frame.kind === "session:agent_stream",
+          ).length,
+          agentStreamTextMessagePayloadBytes: this.textMessageFrames
+            .filter((frame) => frame.kind === "session:agent_stream")
+            .reduce((sum, frame) => sum + frame.bytes, 0),
+          largeAgentStreamTextMessageCount: this.textMessageFrames.filter(
+            (frame) => frame.kind === "session:agent_stream" && frame.bytes >= 50_000,
+          ).length,
+          largestAgentStreamTextMessageBytes: Math.max(
+            0,
+            ...this.textMessageFrames
+              .filter((frame) => frame.kind === "session:agent_stream")
+              .map((frame) => frame.bytes),
+          ),
+          appEventCount: this.appEvents.length,
+          appEventCounts: countByType(this.appEvents),
+          runtimeMaxQueueDepth: Math.max(
+            0,
+            ...this.appEvents
+              .map((event) => event.queueDepth)
+              .filter((value): value is number => typeof value === "number"),
+          ),
+          xtermWriteCount: this.xtermWrites.length,
+          inputFramePayloadBytes: this.inputFrames.reduce((sum, frame) => sum + frame.bytes, 0),
+          outputFramePayloadBytes: this.outputFrames.reduce((sum, frame) => sum + frame.bytes, 0),
+          keydownToInputFrameMs: summarize(keydownToInputFrame),
+          inputFrameToOutputFrameMs: summarize(inputFrameToOutputFrame),
+          appBinaryReceivedToFrameDecodedMs: summarize(
+            latencyByIndex(binaryReceived, frameDecoded),
+          ),
+          appFrameDecodedToTerminalEmitMs: summarize(latencyByIndex(frameDecoded, terminalEmit)),
+          appTerminalEmitListenerDurationMs: summarize(
+            latencyByIndex(terminalEmit, terminalEmitted),
+          ),
+          appTerminalEmitToStreamControllerOutputMs: summarize(
+            latencyByIndex(terminalEmit, streamControllerOutput),
+          ),
+          appStreamControllerDecodeToOnOutputMs: summarize(
+            latencyByIndex(streamControllerOutput, streamControllerOnOutput),
+          ),
+          appStreamControllerToEmulatorWriteMs: summarize(
+            latencyByIndex(streamControllerOnOutput, emulatorWriteOutput),
+          ),
+          appEmulatorWriteToRuntimeEnqueuedMs: summarize(
+            latencyByIndex(emulatorWriteOutput, runtimeWriteEnqueued),
+          ),
+          appRuntimeEnqueuedToOperationStartMs: summarize(
+            latencyByIndex(runtimeWriteEnqueued, runtimeOperationStart),
+          ),
+          appRuntimeOperationStartToXtermWriteMs: summarize(
+            latencyByIndex(runtimeOperationStart, runtimeXtermWrite),
+          ),
+          appRuntimeXtermWriteToCommitMs: summarize(
+            latencyByIndex(runtimeXtermWrite, runtimeXtermCommitted),
+          ),
+          appBinaryReceivedToRuntimeEnqueuedMs: summarize(
+            latencyByIndex(binaryReceived, runtimeWriteEnqueued),
+          ),
+          appBinaryReceivedToRuntimeOperationStartMs: summarize(
+            latencyByIndex(binaryReceived, runtimeOperationStart),
+          ),
+          appBinaryReceivedToXtermCommitMs: summarize(
+            latencyByIndex(binaryReceived, runtimeXtermCommitted),
+          ),
+          outputFrameToXtermWriteMs: summarize(outputFrameToXtermWrite),
+          xtermWriteDurationMs: summarize(xtermWriteDurations),
+          keydownToXtermCommitMs: summarize(keydownToXtermCommit),
+          firstKeydownAt: this.keydowns[0]?.at ?? null,
+          lastXtermCommitAt:
+            this.xtermWrites
+              .map((write) => write.committedAt)
+              .findLast((at): at is number => typeof at === "number") ?? null,
+        };
+      },
+    };
+
+    Object.defineProperty(window, "__terminalKeystrokeStressProbe", {
+      configurable: true,
+      value: probe,
+    });
+
+    document.addEventListener(
+      "keydown",
+      (event) => {
+        if (event.key.length === 1) {
+          probe.keydowns.push({ at: performance.now(), key: event.key });
+        }
+      },
+      true,
+    );
+
+    const NativeWebSocket = window.WebSocket;
+    class InstrumentedWebSocket extends NativeWebSocket {
+      constructor(url: string | URL, protocols?: string | string[]) {
+        if (protocols === undefined) {
+          super(url);
+        } else {
+          super(url, protocols);
+        }
+        super.addEventListener("message", (event) => {
+          void eventDataBytes(event.data).then((bytes) => {
+            if (!bytes || bytes.byteLength < 2 || bytes[0] !== OUTPUT_OPCODE) {
+              return;
+            }
+            probe.outputFrames.push({
+              at: performance.now(),
+              text: frameText(bytes),
+              bytes: bytes.byteLength - 2,
+            });
+            return;
+          });
+          void eventDataText(event.data).then((text) => {
+            if (text === null) {
+              return;
+            }
+            probe.textMessageFrames.push({
+              at: performance.now(),
+              bytes: new TextEncoder().encode(text).byteLength,
+              kind: textMessageKind(text),
+            });
+            return;
+          });
+        });
+      }
+
+      send(data: Parameters<WebSocket["send"]>[0]): void {
+        const bytes = bytesFrom(data);
+        if (bytes && bytes.byteLength >= 2 && bytes[0] === INPUT_OPCODE) {
+          probe.inputFrames.push({
+            at: performance.now(),
+            text: frameText(bytes),
+            bytes: bytes.byteLength - 2,
+          });
+        }
+        super.send(data);
+      }
+    }
+
+    Object.defineProperty(InstrumentedWebSocket, "CONNECTING", {
+      value: NativeWebSocket.CONNECTING,
+    });
+    Object.defineProperty(InstrumentedWebSocket, "OPEN", { value: NativeWebSocket.OPEN });
+    Object.defineProperty(InstrumentedWebSocket, "CLOSING", { value: NativeWebSocket.CLOSING });
+    Object.defineProperty(InstrumentedWebSocket, "CLOSED", { value: NativeWebSocket.CLOSED });
+    window.WebSocket = InstrumentedWebSocket as typeof WebSocket;
+
+    const existingDescriptor = Object.getOwnPropertyDescriptor(window, "__paseoTerminal");
+    const getExisting = () =>
+      existingDescriptor?.get ? existingDescriptor.get.call(window) : existingDescriptor?.value;
+
+    let terminal = getExisting();
+    Object.defineProperty(window, "__paseoTerminal", {
+      configurable: true,
+      get() {
+        return terminal;
+      },
+      set(next: {
+        write?: (data: string | Uint8Array, callback?: () => void) => void;
+        __paseoKeystrokeProbeWriteWrapped?: boolean;
+      }) {
+        terminal = next;
+        if (next?.write && !next.__paseoKeystrokeProbeWriteWrapped) {
+          const originalWrite = next.write.bind(next);
+          next.write = (data: string | Uint8Array, callback?: () => void) => {
+            const text = typeof data === "string" ? data : new TextDecoder().decode(data);
+            const event: XtermWriteEvent = {
+              at: performance.now(),
+              committedAt: null,
+              text,
+              bytes: text.length,
+            };
+            probe.xtermWrites.push(event);
+            return originalWrite(data, () => {
+              event.committedAt = performance.now();
+              callback?.();
+            });
+          };
+          next.__paseoKeystrokeProbeWriteWrapped = true;
+        }
+      },
+    });
+  });
+}
+
+interface TerminalKeystrokeStressProbeWindow {
+  __terminalKeystrokeStressProbe: {
+    reset: () => void;
+    report: (text: string) => TerminalKeystrokeStressReport;
+  };
+}
+
+export async function resetTerminalKeystrokeStressProbe(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    (
+      window as unknown as TerminalKeystrokeStressProbeWindow
+    ).__terminalKeystrokeStressProbe.reset();
+  });
+}
+
+export async function readTerminalKeystrokeStressReport(
+  page: Page,
+  inputText: string,
+): Promise<TerminalKeystrokeStressReport> {
+  return page.evaluate(
+    (text) =>
+      (
+        window as unknown as TerminalKeystrokeStressProbeWindow
+      ).__terminalKeystrokeStressProbe.report(text),
+    inputText,
+  );
+}

packages/app/e2e/support/helpers/timeline-delivery.ts

@@ -0,0 +1,55 @@
+import { expect, type Page } from "@playwright/test";
+
+type WebSocketMessage = string | Buffer;
+
+interface SessionMessage {
+  type?: unknown;
+  payload?: unknown;
+}
+
+interface TimelineSubscriptionWaitOptions {
+  timeout?: number;
+}
+
+function readSessionMessage(message: WebSocketMessage): SessionMessage | null {
+  if (typeof message !== "string") return null;
+  try {
+    const envelope = JSON.parse(message) as {
+      type?: unknown;
+      message?: SessionMessage;
+    };
+    return envelope.type === "session" ? (envelope.message ?? null) : envelope;
+  } catch {
+    return null;
+  }
+}
+
+export function observeTimelineSubscriptions(page: Page) {
+  let acknowledgedAgentIds: string[] | null = null;
+
+  page.on("websocket", (socket) => {
+    socket.on("framereceived", ({ payload }) => {
+      const message = readSessionMessage(payload);
+      if (message?.type !== "agent.timeline.set_subscription.response") return;
+      const response = message.payload as { agentIds?: unknown } | undefined;
+      if (!Array.isArray(response?.agentIds)) return;
+      acknowledgedAgentIds = response.agentIds.filter(
+        (agentId): agentId is string => typeof agentId === "string",
+      );
+    });
+  });
+
+  return {
+    async waitForSubscribedAgents(
+      agentIds: string[],
+      options: TimelineSubscriptionWaitOptions = {},
+    ): Promise<void> {
+      const expected = [...new Set(agentIds)].sort();
+      await expect
+        .poll(() => acknowledgedAgentIds?.slice().sort() ?? null, {
+          timeout: options.timeout ?? 15_000,
+        })
+        .toEqual(expected);
+    },
+  };
+}

packages/app/e2e/support/helpers/timeline-pagination.ts

@@ -0,0 +1,529 @@
+import { expect, type Page } from "@playwright/test";
+import { buildAgentRoute, seedMockAgentWorkspace, type MockAgentWorkspace } from "./mock-agent";
+import {
+  delayAgentBootstrapTailResponse,
+  delayAgentOlderTimelineResponse,
+  holdDaemonHydration,
+  holdAgentOlderTimelinePages,
+  type AgentTimelineResponseGate,
+  type BootstrapTimelineGate,
+  type OlderTimelinePagesGate,
+} from "./agent-timeline-gate";
+
+export { holdDaemonHydration };
+
+interface LongTimelineAgentOptions {
+  turns: number;
+}
+
+export interface LongTimelineAgent extends MockAgentWorkspace {
+  firstOlderPagePrompt: string;
+  initialTailAnchorPrompt: string;
+  initialTailOldestPrompt: string;
+  oldestPrompt: string;
+  newestPrompt: string;
+}
+
+interface RealisticOlderTimelineAgent extends MockAgentWorkspace {
+  newestPrompt: string;
+}
+
+const PROMPT_PREFIX = "timeline-pagination-turn";
+const LIVE_BEFORE_HYDRATION_PROMPT = "timeline live before authoritative hydration";
+const HISTORY_START_THRESHOLD_PX = 96;
+
+interface TimelineViewportSnapshot {
+  scrollHeight: number;
+  scrollTop: number;
+}
+
+export interface TimelinePresentationSnapshot {
+  marker: string;
+  position: TimelinePromptPositionSnapshot;
+  viewport: TimelineViewportSnapshot;
+}
+
+interface TimelinePromptPositionSnapshot {
+  prompt: string;
+  top: number;
+}
+
+interface OlderHistoryLoadingOperation {
+  animationStartTime: number | null;
+  marker: string;
+}
+
+interface OlderHistoryPages {
+  expectRequestedPages(count: number): Promise<void>;
+  expectSettledWithRequestedPages(count: number): Promise<void>;
+  expectNoRepeatedAssistantEntries(): void;
+  releasePage(pageNumber: number): void;
+}
+
+function promptForTurn(index: number): string {
+  return `${PROMPT_PREFIX}-${index}: emit 1 coalesced agent stream updates`;
+}
+
+export async function seedLongMockAgentTimeline(
+  options: LongTimelineAgentOptions,
+): Promise<LongTimelineAgent> {
+  const agent = await seedMockAgentWorkspace({
+    repoPrefix: "timeline-pagination-",
+    title: "Timeline pagination regression",
+    model: "ten-second-stream",
+  });
+
+  for (let index = 0; index < options.turns; index += 1) {
+    await agent.client.sendAgentMessage(agent.agentId, promptForTurn(index));
+    await agent.client.waitForFinish(agent.agentId, 15_000);
+  }
+
+  return {
+    ...agent,
+    firstOlderPagePrompt: promptForTurn(Math.max(0, options.turns - 40)),
+    initialTailAnchorPrompt: promptForTurn(Math.max(0, options.turns - 5)),
+    initialTailOldestPrompt: promptForTurn(Math.max(0, options.turns - 20)),
+    oldestPrompt: promptForTurn(0),
+    newestPrompt: promptForTurn(options.turns - 1),
+  };
+}
+
+export async function seedRealisticOlderTimeline(): Promise<RealisticOlderTimelineAgent> {
+  const agent = await seedMockAgentWorkspace({
+    repoPrefix: "timeline-realistic-older-history-",
+    title: "Realistic older timeline pagination regression",
+    model: "ten-second-stream",
+  });
+
+  const olderTurnCount = 40;
+  for (let index = 0; index < olderTurnCount; index += 1) {
+    await agent.client.sendAgentMessage(
+      agent.agentId,
+      `timeline-pagination-older-turn-${index}: emit 1 coalesced agent stream updates`,
+    );
+    await agent.client.waitForFinish(agent.agentId, 15_000);
+  }
+
+  await agent.client.sendAgentMessage(agent.agentId, "build a realistic long mock timeline");
+  await agent.client.waitForFinish(agent.agentId, 20_000);
+
+  const newerTurnCount = 20;
+  for (let index = 0; index < newerTurnCount; index += 1) {
+    await agent.client.sendAgentMessage(agent.agentId, promptForTurn(index));
+    await agent.client.waitForFinish(agent.agentId, 15_000);
+  }
+
+  return {
+    ...agent,
+    newestPrompt: promptForTurn(newerTurnCount - 1),
+  };
+}
+
+export async function scrollThroughOlderHistoryPages(
+  page: Page,
+  pageCount: number,
+  history: OlderHistoryPages,
+): Promise<void> {
+  for (let pageNumber = 0; pageNumber < pageCount; pageNumber += 1) {
+    await userScrollsTimelineToHistoryStart(page);
+    await history.expectRequestedPages(pageNumber + 1);
+    history.releasePage(pageNumber + 1);
+    await history.expectSettledWithRequestedPages(pageNumber + 1);
+  }
+}
+
+export async function rememberTimelinePromptPosition(
+  page: Page,
+  prompt: string,
+): Promise<TimelinePromptPositionSnapshot> {
+  const timeline = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  const item = timeline.getByText(prompt, { exact: true });
+  await expect(item).toBeVisible();
+  const box = await item.boundingBox();
+  if (!box) {
+    throw new Error(`Expected a rendered timeline item for ${prompt}`);
+  }
+  return { prompt, top: box.y };
+}
+
+export async function expectTimelinePromptPositionPreserved(
+  page: Page,
+  before: TimelinePromptPositionSnapshot,
+): Promise<void> {
+  const timeline = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  const item = timeline.getByText(before.prompt, { exact: true });
+  await expect(item).toBeVisible();
+  await expect
+    .poll(async () => {
+      const box = await item.boundingBox();
+      return box ? Math.abs(box.y - before.top) : Number.POSITIVE_INFINITY;
+    })
+    .toBeLessThanOrEqual(2);
+}
+
+export async function openAgentTimeline(page: Page, agent: MockAgentWorkspace): Promise<void> {
+  await page.goto(buildAgentRoute(agent.workspaceId, agent.agentId));
+  await page.waitForURL(
+    (url) => url.pathname.includes("/workspace/") && !url.searchParams.has("open"),
+    { timeout: 60_000 },
+  );
+}
+
+export async function expectTimelinePromptVisible(page: Page, prompt: string): Promise<void> {
+  const timeline = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  await expect(timeline.getByText(prompt, { exact: true })).toBeVisible({ timeout: 30_000 });
+}
+
+export async function expectTimelinePromptCentered(page: Page, prompt: string): Promise<void> {
+  const timeline = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  const message = timeline.getByTestId("user-message").filter({ hasText: prompt });
+  await expect(message).toBeVisible();
+  await expect
+    .poll(async () => {
+      const [timelineBox, messageBox] = await Promise.all([
+        timeline.boundingBox(),
+        message.boundingBox(),
+      ]);
+      if (!timelineBox || !messageBox) {
+        return Number.POSITIVE_INFINITY;
+      }
+      const timelineCenter = timelineBox.x + timelineBox.width / 2;
+      const messageCenter = messageBox.x + messageBox.width / 2;
+      return Math.abs(timelineCenter - messageCenter);
+    })
+    .toBeLessThanOrEqual(2);
+}
+
+export async function expectTimelinePromptNotMounted(page: Page, prompt: string): Promise<void> {
+  const timeline = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  await expect(timeline.getByText(prompt, { exact: true })).toHaveCount(0);
+}
+
+export async function makeLoadedTimelineFitViewport(page: Page): Promise<void> {
+  await page.setViewportSize({ width: 1280, height: 20_000 });
+}
+
+export async function expectLoadedTimelineDoesNotScroll(page: Page): Promise<void> {
+  const scroll = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  await expect
+    .poll(async () =>
+      scroll.evaluate((element) => {
+        if (!(element instanceof HTMLElement)) {
+          throw new Error("Agent chat scroll element is not an HTMLElement");
+        }
+        return element.scrollHeight <= element.clientHeight;
+      }),
+    )
+    .toBe(true);
+}
+
+export async function reloadAgentTimelineFromPersistedReplica(
+  page: Page,
+  agent: LongTimelineAgent,
+): Promise<void> {
+  await expect
+    .poll(() =>
+      page.evaluate((agentId) => {
+        const raw = localStorage.getItem("@paseo:replica-cache");
+        if (!raw) return false;
+        const cache = JSON.parse(raw) as {
+          hosts?: Array<{
+            timeline?: {
+              agentId?: string;
+              items?: unknown[];
+            } | null;
+          }>;
+        };
+        const timeline = cache.hosts?.find((host) => host.timeline?.agentId === agentId)?.timeline;
+        return timeline?.items?.length === 50;
+      }, agent.agentId),
+    )
+    .toBe(true);
+
+  await page.reload();
+  await expectTimelinePromptVisible(page, agent.newestPrompt);
+}
+
+export async function holdNextOlderTimelinePage(
+  page: Page,
+  agent: LongTimelineAgent,
+): Promise<AgentTimelineResponseGate & { expectLoading(): Promise<void> }> {
+  const gate = await delayAgentOlderTimelineResponse(page, agent.agentId);
+  return {
+    ...gate,
+    async expectLoading() {
+      await gate.waitForDelayedResponse();
+      await expect(page.getByTestId("load-older-history-spinner")).toBeVisible();
+      await expectTimelinePromptNotMounted(page, agent.oldestPrompt);
+    },
+  };
+}
+
+export async function holdOlderHistoryPages(
+  page: Page,
+  agent: MockAgentWorkspace,
+): Promise<OlderHistoryPages> {
+  const gate: OlderTimelinePagesGate = await holdAgentOlderTimelinePages(page, agent.agentId);
+  return {
+    async expectRequestedPages(count) {
+      await gate.waitForRequestCount(count);
+      expect(gate.getRequestCount()).toBe(count);
+    },
+    async expectSettledWithRequestedPages(count) {
+      await waitForTimelineGeometryToSettle(page);
+      expect(gate.getRequestCount()).toBe(count);
+    },
+    expectNoRepeatedAssistantEntries() {
+      expect(gate.getRepeatedAssistantEntryCount()).toBe(0);
+    },
+    releasePage(pageNumber) {
+      gate.releasePage(pageNumber);
+    },
+  };
+}
+
+export async function rememberTimelineViewport(page: Page): Promise<TimelineViewportSnapshot> {
+  return readTimelineViewport(page);
+}
+
+export async function expectStableHistoryStartGutter(page: Page): Promise<void> {
+  const gutter = page.getByTestId("older-history-slot");
+  await expect(gutter).toBeAttached();
+  await expect
+    .poll(() => gutter.evaluate((element) => element.getBoundingClientRect().height))
+    .toBe(32);
+}
+
+export async function scrollTimelinePromptIntoView(page: Page, prompt: string): Promise<void> {
+  const timeline = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  const row = timeline.getByTestId("user-message").filter({ hasText: prompt });
+  await row.scrollIntoViewIfNeeded();
+  await expect(row).toBeVisible();
+  await expect
+    .poll(async () => (await readTimelineViewport(page)).scrollTop)
+    .toBeGreaterThan(HISTORY_START_THRESHOLD_PX);
+}
+
+export async function rememberTimelinePresentation(
+  page: Page,
+  prompt: string,
+): Promise<TimelinePresentationSnapshot> {
+  const timeline = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  const row = timeline.getByTestId("user-message").filter({ hasText: prompt });
+  await expect(row).toBeVisible();
+  const marker = `timeline-presentation-${Date.now()}`;
+  await row.evaluate((element, value) => {
+    element.dataset.timelinePresentation = value;
+  }, marker);
+  return {
+    marker,
+    position: await rememberTimelinePromptPosition(page, prompt),
+    viewport: await rememberTimelineViewport(page),
+  };
+}
+
+export async function expectTimelinePresentationUnchanged(
+  page: Page,
+  before: TimelinePresentationSnapshot,
+): Promise<void> {
+  await expect(page.locator(`[data-timeline-presentation="${before.marker}"]`)).toBeVisible();
+  await expectTimelinePromptPositionPreserved(page, before.position);
+  await expect.poll(async () => rememberTimelineViewport(page)).toEqual(before.viewport);
+}
+
+export async function expectTimelineViewportAnchoredAfterPrepend(
+  page: Page,
+  before: TimelineViewportSnapshot,
+): Promise<void> {
+  await expect
+    .poll(async () => (await readTimelineViewport(page)).scrollHeight)
+    .toBeGreaterThan(before.scrollHeight);
+  await waitForTimelineGeometryToSettle(page);
+  const after = await readTimelineViewport(page);
+  const contentGrowth = after.scrollHeight - before.scrollHeight;
+  const scrollAdjustment = after.scrollTop - before.scrollTop;
+  expect(Math.abs(contentGrowth - scrollAdjustment)).toBeLessThanOrEqual(2);
+}
+
+export async function rememberOlderHistoryLoadingOperation(
+  page: Page,
+): Promise<OlderHistoryLoadingOperation> {
+  const slot = page.getByTestId("load-older-history-spinner");
+  await expect(slot).toBeVisible();
+  const marker = `older-history-loading-${Date.now()}`;
+  await slot.evaluate((element, operationMarker) => {
+    const candidates = [element, ...Array.from(element.querySelectorAll("*"))];
+    const animated = candidates.find(
+      (candidate) => getComputedStyle(candidate).animationName !== "none",
+    );
+    if (!(animated instanceof HTMLElement)) {
+      throw new Error("Expected the older-history loader to contain an animated element");
+    }
+    animated.dataset.olderHistoryLoadingOperation = operationMarker;
+  }, marker);
+  const animated = page.locator(`[data-older-history-loading-operation="${marker}"]`);
+  await expect
+    .poll(async () => {
+      const startTime = await animated.evaluate((element) => element.getAnimations()[0]?.startTime);
+      return typeof startTime === "number" ? startTime : null;
+    })
+    .not.toBeNull();
+  const animationStartTime = await animated.evaluate((element) => {
+    const startTime = element.getAnimations()[0]?.startTime;
+    return typeof startTime === "number" ? startTime : null;
+  });
+  return { animationStartTime, marker };
+}
+
+export async function expectSameOlderHistoryLoadingOperation(
+  page: Page,
+  operation: OlderHistoryLoadingOperation,
+): Promise<void> {
+  const animated = page.locator(`[data-older-history-loading-operation="${operation.marker}"]`);
+  await expect(animated).toBeVisible();
+  const animationStartTime = await animated.evaluate((element) => {
+    const startTime = element.getAnimations()[0]?.startTime;
+    return typeof startTime === "number" ? startTime : null;
+  });
+  expect(animationStartTime).toBe(operation.animationStartTime);
+}
+
+export async function expectTimelineAtHistoryStart(page: Page): Promise<void> {
+  await expect
+    .poll(async () => (await readTimelineViewport(page)).scrollTop)
+    .toBeLessThanOrEqual(HISTORY_START_THRESHOLD_PX);
+}
+
+export async function holdBootstrapTimelinePage(
+  page: Page,
+  agent: LongTimelineAgent,
+): Promise<BootstrapTimelineGate> {
+  return delayAgentBootstrapTailResponse(page, agent.agentId);
+}
+
+export async function sendLiveTurnBeforeHydration(agent: LongTimelineAgent): Promise<string> {
+  await agent.client.sendAgentMessage(agent.agentId, LIVE_BEFORE_HYDRATION_PROMPT);
+  await agent.client.waitForFinish(agent.agentId, 15_000);
+  return LIVE_BEFORE_HYDRATION_PROMPT;
+}
+
+export async function scrollTimelineToOldestLoadedEdge(page: Page): Promise<void> {
+  const scroll = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  await scroll.hover();
+  await page.mouse.wheel(0, -20_000);
+  await page.evaluate(
+    () =>
+      new Promise<void>((resolve) => {
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+      }),
+  );
+  await scroll.evaluate((element) => {
+    if (!(element instanceof HTMLElement)) {
+      throw new Error("Agent chat scroll element is not an HTMLElement");
+    }
+    element.scrollTop = 0;
+    element.dispatchEvent(new Event("scroll", { bubbles: true }));
+  });
+}
+
+export async function userScrollsTimelineToHistoryStart(page: Page): Promise<void> {
+  const scroll = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  await scroll.hover();
+  for (let step = 0; step < 60; step += 1) {
+    if ((await readTimelineViewport(page)).scrollTop <= HISTORY_START_THRESHOLD_PX) {
+      break;
+    }
+    await page.mouse.wheel(0, -1_000);
+    await page.evaluate(
+      () =>
+        new Promise<void>((resolve) => {
+          requestAnimationFrame(() => resolve());
+        }),
+    );
+  }
+  await expect
+    .poll(async () => (await readTimelineViewport(page)).scrollTop)
+    .toBeLessThanOrEqual(HISTORY_START_THRESHOLD_PX);
+}
+
+export async function userNavigatesTimelineToHistoryStartWithKeyboard(page: Page): Promise<void> {
+  const scroll = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  await scroll.focus();
+  await page.keyboard.press("Home");
+  await expect
+    .poll(async () => (await readTimelineViewport(page)).scrollTop)
+    .toBeLessThanOrEqual(HISTORY_START_THRESHOLD_PX);
+}
+
+export async function scrollTimelineToNewestLoadedEdge(page: Page): Promise<void> {
+  const scroll = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  await scroll.evaluate((element) => {
+    if (!(element instanceof HTMLElement)) {
+      throw new Error("Agent chat scroll element is not an HTMLElement");
+    }
+    element.scrollTop = element.scrollHeight;
+    element.dispatchEvent(new Event("scroll", { bubbles: true }));
+  });
+}
+
+export async function scrollTimelineUntilOlderHistoryIsReachable(
+  page: Page,
+  oldestPrompt: string,
+): Promise<void> {
+  const scroll = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  const prompt = scroll.getByText(oldestPrompt, { exact: true });
+  for (let attempt = 0; attempt < 10; attempt += 1) {
+    if ((await prompt.count()) > 0) {
+      await expect(prompt).toBeVisible();
+      return;
+    }
+    const previousHeight = await readTimelineViewport(page);
+    await userScrollsTimelineToHistoryStart(page);
+    await expect
+      .poll(async () => (await readTimelineViewport(page)).scrollHeight)
+      .toBeGreaterThan(previousHeight.scrollHeight);
+    await waitForTimelineGeometryToSettle(page);
+  }
+  await expect(prompt).toBeVisible();
+}
+
+async function readTimelineViewport(page: Page): Promise<TimelineViewportSnapshot> {
+  const scroll = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  return scroll.evaluate((element) => {
+    if (!(element instanceof HTMLElement)) {
+      throw new Error("Agent chat scroll element is not an HTMLElement");
+    }
+    return { scrollHeight: element.scrollHeight, scrollTop: element.scrollTop };
+  });
+}
+
+async function waitForTimelineGeometryToSettle(page: Page): Promise<void> {
+  const scroll = page.locator('[data-testid="agent-chat-scroll"]:visible').first();
+  await scroll.evaluate(
+    (element) =>
+      new Promise<void>((resolve, reject) => {
+        if (!(element instanceof HTMLElement)) {
+          reject(new Error("Agent chat scroll element is not an HTMLElement"));
+          return;
+        }
+        const startedAt = performance.now();
+        let stableFrames = 0;
+        let previous = `${element.scrollTop}:${element.scrollHeight}`;
+        const sample = () => {
+          const current = `${element.scrollTop}:${element.scrollHeight}`;
+          stableFrames = current === previous ? stableFrames + 1 : 0;
+          previous = current;
+          if (stableFrames >= 4) {
+            resolve();
+            return;
+          }
+          if (performance.now() - startedAt > 5_000) {
+            reject(new Error("Timeline geometry did not settle"));
+            return;
+          }
+          requestAnimationFrame(sample);
+        };
+        requestAnimationFrame(sample);
+      }),
+  );
+}

packages/app/e2e/support/helpers/timeline-resume.ts

@@ -0,0 +1,68 @@
+import { expect, type Page } from "@playwright/test";
+import type { installDaemonWebSocketGate } from "./daemon-websocket-gate";
+import type { LongTimelineAgent } from "./timeline-pagination";
+import { expectReconnectingToastGone, expectReconnectingToastVisible } from "./workspace-ui";
+
+type DaemonWebSocketGate = Awaited<ReturnType<typeof installDaemonWebSocketGate>>;
+
+export interface TimelineRequestCounts {
+  after: number;
+  tail: number;
+}
+
+export interface BackgroundTimelineTurns {
+  firstPrompt: string;
+  newestPrompt: string;
+}
+
+function backgroundPrompt(index: number): string {
+  return `timeline-resume-background-${index}: emit 1 coalesced agent stream updates`;
+}
+
+export async function commitTimelineTurnsWhileDisconnected(
+  agent: LongTimelineAgent,
+  count: number,
+): Promise<BackgroundTimelineTurns> {
+  for (let index = 0; index < count; index += 1) {
+    await agent.client.sendAgentMessage(agent.agentId, backgroundPrompt(index));
+    await agent.client.waitForFinish(agent.agentId, 15_000);
+  }
+  return {
+    firstPrompt: backgroundPrompt(0),
+    newestPrompt: backgroundPrompt(count - 1),
+  };
+}
+
+export function rememberTimelineRequestCounts(gate: DaemonWebSocketGate): TimelineRequestCounts {
+  return {
+    after: gate.getTimelineRequestCount("after"),
+    tail: gate.getTimelineRequestCount("tail"),
+  };
+}
+
+export function expectOneTailCheckWithoutCatchUpPages(
+  gate: DaemonWebSocketGate,
+  before: TimelineRequestCounts,
+): void {
+  expect(gate.getTimelineRequestCount("tail") - before.tail).toBe(1);
+  expect(gate.getTimelineRequestCount("after") - before.after).toBe(0);
+}
+
+export async function disconnectViewedTimeline(
+  page: Page,
+  gate: DaemonWebSocketGate,
+): Promise<void> {
+  await gate.drop();
+  await expectReconnectingToastVisible(page);
+}
+
+export async function restoreViewedTimelineWithHeldTail(
+  page: Page,
+  gate: DaemonWebSocketGate,
+): Promise<void> {
+  gate.holdNextServerMessage("fetch_agent_timeline_response");
+  gate.restore();
+  await gate.waitForHeldServerMessage();
+  gate.releaseHeldServerMessage();
+  await expectReconnectingToastGone(page);
+}

packages/app/e2e/support/helpers/with-workspace.ts

@@ -0,0 +1,117 @@
+import { execSync } from "node:child_process";
+import path from "node:path";
+import type { Page } from "@playwright/test";
+import { waitForTabBar } from "./launcher";
+import { selectWorkspaceInSidebar } from "./sidebar";
+import { createTempGitRepo, resolveTempRoot } from "./workspace";
+import {
+  connectWorkspaceSetupClient,
+  openHomeWithProject,
+  type WorkspaceSetupDaemonClient,
+} from "./workspace-setup";
+
+export interface CreatedWorkspace {
+  workspaceId: string;
+  repoPath: string;
+  navigateTo(): Promise<void>;
+}
+
+export interface WithWorkspaceOptions {
+  worktree?: boolean;
+  prefix?: string;
+}
+
+export type WithWorkspace = (options?: WithWorkspaceOptions) => Promise<CreatedWorkspace>;
+
+interface WorktreeRecord {
+  repoPath: string;
+  worktreePath: string;
+}
+
+export interface WithWorkspaceHandle {
+  withWorkspace: WithWorkspace;
+  cleanup: () => Promise<void>;
+}
+
+export function createWithWorkspace(page: Page): WithWorkspaceHandle {
+  let client: WorkspaceSetupDaemonClient | null = null;
+  const repos: Array<{ cleanup: () => Promise<void> }> = [];
+  const worktrees: WorktreeRecord[] = [];
+  const projectIds = new Set<string>();
+
+  const withWorkspace: WithWorkspace = async (options) => {
+    if (!client) {
+      client = await connectWorkspaceSetupClient();
+    }
+    const prefix = options?.prefix ?? (options?.worktree ? "wt-" : "ws-");
+    const repo = await createTempGitRepo(prefix);
+    repos.push(repo);
+
+    let workspacePath = repo.path;
+    if (options?.worktree) {
+      const tempRoot = await resolveTempRoot();
+      workspacePath = path.join(
+        tempRoot,
+        `paseo-wt-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+      );
+      const branchName = `paseo-wt-${Date.now()}`;
+      execSync(
+        `git worktree add ${JSON.stringify(workspacePath)} -b ${JSON.stringify(branchName)} main`,
+        { cwd: repo.path, stdio: "ignore" },
+      );
+      worktrees.push({ repoPath: repo.path, worktreePath: workspacePath });
+      // Register the parent project so the sidebar lists it before we navigate.
+      const added = await client.addProject(repo.path);
+      if (!added.project) {
+        throw new Error(added.error ?? `Failed to add project ${repo.path}`);
+      }
+      projectIds.add(added.project.projectId);
+    }
+
+    const created = await client.createWorkspace({
+      source: { kind: "directory", path: workspacePath },
+    });
+    if (!created.workspace) {
+      throw new Error(created.error ?? `Failed to create workspace ${workspacePath}`);
+    }
+    const workspaceId = created.workspace.id;
+    projectIds.add(created.workspace.projectId);
+
+    return {
+      workspaceId,
+      repoPath: workspacePath,
+      navigateTo: async () => {
+        await openHomeWithProject(page, repo.path);
+        await selectWorkspaceInSidebar(page, workspaceId);
+        await waitForTabBar(page);
+      },
+    };
+  };
+
+  return {
+    withWorkspace,
+    cleanup: async () => {
+      if (client) {
+        for (const projectId of projectIds) {
+          await client.removeProject(projectId).catch(() => undefined);
+        }
+      }
+      for (const { repoPath, worktreePath } of worktrees) {
+        try {
+          execSync(`git worktree remove ${JSON.stringify(worktreePath)} --force`, {
+            cwd: repoPath,
+            stdio: "ignore",
+          });
+        } catch {
+          // Best-effort cleanup so the original test failure is preserved.
+        }
+      }
+      for (const repo of repos) {
+        await repo.cleanup();
+      }
+      if (client) {
+        await client.close().catch(() => undefined);
+      }
+    },
+  };
+}

packages/app/e2e/support/helpers/workspace-lifecycle.ts

@@ -0,0 +1,32 @@
+import { expect, type Page } from "@playwright/test";
+import { clickNewChat, clickNewTerminal } from "./launcher";
+import { setupDeterministicPrompt, waitForTerminalContent } from "./terminal-perf";
+
+function terminalSurface(page: Page) {
+  return page.locator('[data-testid="terminal-surface"]').first();
+}
+
+function composerInput(page: Page) {
+  return page.getByRole("textbox", { name: "Message agent..." }).first();
+}
+
+export async function expectTerminalCwd(page: Page, expectedPath: string): Promise<void> {
+  const terminal = terminalSurface(page);
+  await expect(terminal).toBeVisible({ timeout: 20_000 });
+  await terminal.click();
+  await setupDeterministicPrompt(page, `SENTINEL_${Date.now()}`);
+  await terminal.pressSequentially("pwd\n", { delay: 0 });
+  await waitForTerminalContent(page, (text) => text.includes(expectedPath), 10_000);
+}
+
+export async function createStandaloneTerminalFromLauncher(page: Page): Promise<void> {
+  await clickNewTerminal(page);
+  await expect(terminalSurface(page)).toBeVisible({ timeout: 20_000 });
+}
+
+export async function createAgentChatFromLauncher(page: Page): Promise<void> {
+  await clickNewChat(page);
+  await expect(composerInput(page)).toBeVisible({ timeout: 15_000 });
+  await expect(composerInput(page)).toBeEditable({ timeout: 15_000 });
+  await expect(page.getByTestId("agent-loading")).toHaveCount(0);
+}

packages/app/e2e/support/helpers/workspace-setup.ts

@@ -0,0 +1,315 @@
+import { realpathSync } from "node:fs";
+import { expect, type Page } from "@playwright/test";
+import type { DaemonClient as InternalDaemonClient } from "@getpaseo/client/internal/daemon-client";
+import { parseHostWorkspaceRouteFromPathname } from "../../../src/utils/host-routes";
+import { gotoAppShell } from "./app";
+import { connectDaemonClient } from "./daemon-client-loader";
+import { getServerId } from "./server-id";
+import { withProjectOwnership } from "./project-ownership";
+import { switchWorkspaceViaSidebar } from "./workspace-ui";
+import type { SessionOutboundMessage } from "@getpaseo/protocol/messages";
+
+type WorkspaceSetupDaemonClient = Pick<
+  InternalDaemonClient,
+  | "close"
+  | "addProject"
+  | "connect"
+  | "createPaseoWorktree"
+  | "createWorkspace"
+  | "fetchAgent"
+  | "fetchAgents"
+  | "fetchWorkspaces"
+  | "listTerminals"
+  | "removeProject"
+  | "subscribeRawMessages"
+>;
+
+export type WorkspaceSetupProgressPayload = Extract<
+  SessionOutboundMessage,
+  { type: "workspace_setup_progress" }
+>["payload"];
+
+export type { WorkspaceSetupDaemonClient };
+
+export async function connectWorkspaceSetupClient(): Promise<WorkspaceSetupDaemonClient> {
+  const client = await connectDaemonClient<WorkspaceSetupDaemonClient>({
+    clientIdPrefix: "workspace-setup",
+  });
+  return withProjectOwnership(client);
+}
+
+export async function openProjectViaDaemon(
+  client: WorkspaceSetupDaemonClient,
+  repoPath: string,
+): Promise<{ id: string; name: string; workspaceDirectory: string }> {
+  const result = await client.createWorkspace({
+    source: { kind: "directory", path: repoPath },
+  });
+  if (!result.workspace || result.error) {
+    throw new Error(result.error ?? `Failed to create workspace ${repoPath}`);
+  }
+  return {
+    id: result.workspace.id,
+    name: result.workspace.name,
+    workspaceDirectory: result.workspace.workspaceDirectory,
+  };
+}
+
+export async function seedProjectForWorkspaceSetup(
+  client: WorkspaceSetupDaemonClient,
+  repoPath: string,
+): Promise<void> {
+  const result = await client.addProject(repoPath);
+  if (!result.project || result.error) {
+    throw new Error(result.error ?? `Failed to add project ${repoPath}`);
+  }
+}
+
+export function projectNameFromPath(repoPath: string): string {
+  return repoPath.replace(/\/+$/, "").split("/").findLast(Boolean) ?? repoPath;
+}
+
+export async function openHomeWithProject(page: Page, repoPath: string): Promise<void> {
+  await gotoAppShell(page);
+  await expect(
+    page
+      .locator('[data-testid^="sidebar-project-row-"]')
+      .filter({ hasText: projectNameFromPath(repoPath) })
+      .first(),
+  ).toBeVisible({ timeout: 30_000 });
+}
+
+function createWorkspaceButton(page: Page, repoPath: string) {
+  return page.getByRole("button", {
+    name: `Create a new workspace for ${projectNameFromPath(repoPath)}`,
+  });
+}
+
+async function revealWorkspaceButton(page: Page, repoPath: string): Promise<void> {
+  await page
+    .locator('[data-testid^="sidebar-project-row-"]')
+    .filter({ hasText: projectNameFromPath(repoPath) })
+    .first()
+    .hover();
+}
+
+export async function createWorkspaceFromSidebar(page: Page, repoPath: string): Promise<void> {
+  const button = createWorkspaceButton(page, repoPath);
+  await revealWorkspaceButton(page, repoPath);
+  await expect(button).toBeVisible({ timeout: 30_000 });
+  await expect(button).toBeEnabled({ timeout: 30_000 });
+  await button.click();
+  await expect(page).toHaveURL(/\/new\?/, { timeout: 30_000 });
+  await expect(page.getByRole("textbox", { name: "Message agent..." }).first()).toBeVisible({
+    timeout: 30_000,
+  });
+}
+
+export async function getCurrentWorkspaceIdFromRoute(page: Page): Promise<string> {
+  await expect
+    .poll(
+      () => parseHostWorkspaceRouteFromPathname(new URL(page.url()).pathname)?.workspaceId ?? null,
+      { timeout: 30_000 },
+    )
+    .not.toBeNull();
+
+  const workspaceId =
+    parseHostWorkspaceRouteFromPathname(new URL(page.url()).pathname)?.workspaceId ?? null;
+  if (!workspaceId) {
+    throw new Error(`Expected a workspace route but found ${page.url()}`);
+  }
+
+  return workspaceId;
+}
+
+function workspaceSetupDialog(page: Page) {
+  return page.getByTestId("workspace-setup-dialog");
+}
+
+export async function createChatAgentFromWorkspaceSetup(
+  page: Page,
+  input: { message: string },
+): Promise<void> {
+  const messageInput = page.getByRole("textbox", { name: "Message agent..." }).first();
+  await expect(messageInput).toBeVisible({ timeout: 15_000 });
+  await messageInput.fill(input.message);
+  await messageInput.press("Enter");
+}
+
+/**
+ * @deprecated The new workspace screen no longer has a standalone terminal button.
+ * Use the daemon API to create a workspace, then open a terminal from the launcher.
+ */
+export async function createStandaloneTerminalFromWorkspaceSetup(page: Page): Promise<void> {
+  await workspaceSetupDialog(page)
+    .getByRole("button", { name: /^Terminal Create the workspace/i })
+    .click();
+}
+
+export async function waitForWorkspaceSetupDialogToClose(
+  page: Page,
+  timeoutMs = 45_000,
+): Promise<void> {
+  const dialog = workspaceSetupDialog(page);
+
+  try {
+    await expect(dialog).toHaveCount(0, { timeout: timeoutMs });
+  } catch (error) {
+    const dialogText = (await dialog.textContent().catch(() => null))?.replace(/\s+/g, " ").trim();
+    throw new Error(
+      dialogText
+        ? `Workspace setup dialog stayed open. Visible text: ${dialogText}`
+        : `Workspace setup dialog did not close within ${timeoutMs}ms`,
+      { cause: error },
+    );
+  }
+}
+
+export async function expectSetupPanel(page: Page): Promise<void> {
+  // If the setup panel is already visible (auto-opened), we're done.
+  const panel = page.getByTestId("workspace-setup-panel");
+  if (await panel.isVisible().catch(() => false)) {
+    return;
+  }
+  // Otherwise open it manually via workspace header actions menu.
+  // Use the specific testID to avoid matching the sidebar kebab which shares
+  // the same "Workspace actions" accessibility label.
+  const actionsButton = page.getByTestId("workspace-header-menu-trigger");
+  await expect(actionsButton).toBeVisible({ timeout: 10_000 });
+  await actionsButton.click();
+  const showSetup = page.getByTestId("workspace-header-show-setup");
+  await expect(showSetup).toBeVisible({ timeout: 5_000 });
+  await showSetup.click();
+  await expect(panel).toBeVisible({ timeout: 30_000 });
+}
+
+export async function expectSetupStatus(
+  page: Page,
+  status: "Running" | "Completed" | "Failed",
+): Promise<void> {
+  await expect(page.getByTestId("workspace-setup-status")).toContainText(status, {
+    timeout: 30_000,
+  });
+}
+
+export async function expectSetupLogContains(page: Page, text: string): Promise<void> {
+  await expect(page.getByTestId("workspace-setup-log")).toContainText(text, {
+    timeout: 30_000,
+  });
+}
+
+export async function expectNoSetupMessage(page: Page): Promise<void> {
+  await expect(
+    page.getByText("No setup commands ran for this workspace.", { exact: true }),
+  ).toBeVisible({
+    timeout: 30_000,
+  });
+}
+
+export async function createWorkspaceThroughDaemon(
+  client: WorkspaceSetupDaemonClient,
+  input: { cwd: string; worktreeSlug: string },
+): Promise<{ id: string; name: string }> {
+  const result = await client.createPaseoWorktree(input);
+  if (!result.workspace || result.error) {
+    throw new Error(result.error ?? `Failed to create workspace for ${input.cwd}`);
+  }
+  return {
+    id: result.workspace.id,
+    name: result.workspace.name,
+  };
+}
+
+export async function findWorktreeWorkspaceForProject(
+  client: WorkspaceSetupDaemonClient,
+  repoPath: string,
+): Promise<{
+  id: string;
+  name: string;
+  projectRootPath: string;
+  workspaceDirectory: string;
+}> {
+  const payload = await client.fetchWorkspaces();
+  const normalizedRepoPath = realpathSync(repoPath);
+  const workspace =
+    payload.entries.find(
+      (entry) =>
+        entry.projectRootPath === normalizedRepoPath &&
+        entry.workspaceDirectory !== normalizedRepoPath,
+    ) ?? null;
+  if (!workspace) {
+    throw new Error(`Failed to find created worktree workspace for ${repoPath}`);
+  }
+  return {
+    id: workspace.id,
+    name: workspace.name,
+    projectRootPath: workspace.projectRootPath,
+    workspaceDirectory: workspace.workspaceDirectory,
+  };
+}
+
+export async function fetchWorkspaceById(
+  client: WorkspaceSetupDaemonClient,
+  workspaceId: string,
+): Promise<{
+  id: string;
+  name: string;
+  workspaceDirectory: string;
+  projectRootPath: string;
+}> {
+  const payload = await client.fetchWorkspaces();
+  const workspace = payload.entries.find((entry) => entry.id === workspaceId) ?? null;
+  if (!workspace) {
+    throw new Error(`Workspace not found: ${workspaceId}`);
+  }
+  return workspace;
+}
+
+export async function navigateToWorkspaceViaSidebar(
+  page: Page,
+  workspaceId: string,
+): Promise<void> {
+  await switchWorkspaceViaSidebar({
+    page,
+    serverId: getServerId(),
+    workspaceId,
+  });
+}
+
+export async function openWorkspaceScriptsMenu(page: Page): Promise<void> {
+  await page.getByTestId("workspace-scripts-button").click();
+  await expect(page.getByTestId("workspace-scripts-menu")).toBeVisible({ timeout: 10_000 });
+}
+
+export async function startWorkspaceScriptFromMenu(page: Page, scriptName: string): Promise<void> {
+  await page.getByTestId(`workspace-scripts-start-${scriptName}`).click();
+}
+
+export async function closeWorkspaceScriptsMenu(page: Page): Promise<void> {
+  await page.getByTestId("workspace-scripts-menu-backdrop").click();
+}
+
+export async function waitForWorkspaceSetupProgress(
+  client: WorkspaceSetupDaemonClient,
+  predicate: (payload: WorkspaceSetupProgressPayload) => boolean,
+  timeoutMs = 30_000,
+): Promise<WorkspaceSetupProgressPayload> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      unsubscribe();
+      reject(new Error(`Timed out waiting for workspace_setup_progress after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    const unsubscribe = client.subscribeRawMessages((message) => {
+      if (message.type !== "workspace_setup_progress") {
+        return;
+      }
+      if (!predicate(message.payload)) {
+        return;
+      }
+      clearTimeout(timeout);
+      unsubscribe();
+      resolve(message.payload);
+    });
+  });
+}

packages/app/e2e/support/helpers/workspace-tabs.ts

@@ -0,0 +1,118 @@
+import { expect, type Page } from "@playwright/test";
+
+export async function getWorkspaceTabTestIds(page: Page): Promise<string[]> {
+  const tabs = page.locator('[data-testid^="workspace-tab-"]');
+  const count = await tabs.count();
+  const ids: string[] = [];
+  for (let index = 0; index < count; index += 1) {
+    const testId = await tabs.nth(index).getAttribute("data-testid");
+    if (testId && !ids.includes(testId)) {
+      ids.push(testId);
+    }
+  }
+  return ids;
+}
+
+function visibleTestId(page: Page, testId: string) {
+  return page.getByTestId(testId).filter({ visible: true });
+}
+
+export async function waitForWorkspaceTabsVisible(page: Page): Promise<void> {
+  await expect(visibleTestId(page, "workspace-tabs-row").first()).toBeVisible({
+    timeout: 30_000,
+  });
+  await expect(visibleTestId(page, "workspace-new-agent-tab-inline").first()).toBeVisible({
+    timeout: 30_000,
+  });
+}
+
+export async function getVisibleWorkspaceAgentTabIds(page: Page): Promise<string[]> {
+  const tabs = page.locator('[data-testid^="workspace-tab-agent_"]').filter({ visible: true });
+  const count = await tabs.count();
+  const ids: string[] = [];
+  for (let index = 0; index < count; index += 1) {
+    const testId = await tabs.nth(index).getAttribute("data-testid");
+    if (testId && !ids.includes(testId)) {
+      ids.push(testId);
+    }
+  }
+  return ids;
+}
+
+export async function expectOnlyWorkspaceAgentTabsVisible(
+  page: Page,
+  expectedAgentIds: string[],
+): Promise<void> {
+  const expected = new Set(expectedAgentIds.map((id) => `workspace-tab-agent_${id}`));
+  const visible = await getVisibleWorkspaceAgentTabIds(page);
+  const unexpected = visible.filter((id) => !expected.has(id));
+
+  expect(unexpected).toEqual([]);
+  expect(visible.length).toBe(expected.size);
+  for (const expectedId of expectedAgentIds) {
+    await expect(visibleTestId(page, `workspace-tab-agent_${expectedId}`).first()).toBeVisible({
+      timeout: 30_000,
+    });
+  }
+}
+
+export async function ensureWorkspaceAgentPaneVisible(page: Page): Promise<void> {
+  const toggle = page.getByTestId("workspace-explorer-toggle").first();
+  if (!(await toggle.isVisible().catch(() => false))) {
+    return;
+  }
+  const isExpanded = (await toggle.getAttribute("aria-expanded")) === "true";
+  if (isExpanded) {
+    await toggle.click();
+    await expect(toggle).toHaveAttribute("aria-expanded", "false", {
+      timeout: 10_000,
+    });
+  }
+}
+
+export async function expectWorkspaceTabsAbsent(page: Page): Promise<void> {
+  await expect(page.getByTestId("workspace-tabs-row")).toHaveCount(0);
+}
+
+export async function expectNoTerminalTabs(page: Page): Promise<void> {
+  await expect(page.locator('[data-testid^="workspace-tab-terminal_"]')).toHaveCount(0);
+}
+
+export async function clickFirstTerminalTab(
+  page: Page,
+  options?: { timeout?: number },
+): Promise<void> {
+  const tab = page.locator('[data-testid^="workspace-tab-terminal_"]').first();
+  await expect(tab).toBeVisible({ timeout: options?.timeout ?? 30_000 });
+  await tab.click();
+}
+
+export async function expectFirstTerminalTabContains(page: Page, text: string): Promise<void> {
+  await expect(page.locator('[data-testid^="workspace-tab-terminal_"]').first()).toContainText(
+    text,
+  );
+}
+
+export async function expectTerminalTabOpen(
+  page: Page,
+  options?: { timeout?: number },
+): Promise<void> {
+  await expect(
+    page.locator('[data-testid^="workspace-tab-terminal_"]').filter({ visible: true }).first(),
+  ).toBeVisible({ timeout: options?.timeout ?? 30_000 });
+}
+
+export async function sampleWorkspaceTabIds(
+  page: Page,
+  options: { durationMs?: number; intervalMs?: number } = {},
+): Promise<string[][]> {
+  const durationMs = options.durationMs ?? 2_500;
+  const intervalMs = options.intervalMs ?? 50;
+  const snapshots: string[][] = [];
+  const start = Date.now();
+  while (Date.now() - start <= durationMs) {
+    snapshots.push(await getWorkspaceTabTestIds(page));
+    await page.waitForTimeout(intervalMs);
+  }
+  return snapshots;
+}

packages/app/e2e/support/helpers/workspace-ui.ts

@@ -0,0 +1,143 @@
+import { expect, type Page } from "@playwright/test";
+import { buildHostWorkspaceRoute } from "@/utils/host-routes";
+import { gotoHome } from "./app";
+import { expectAppRoute } from "./route-assertions";
+
+export async function openNewAgentComposer(page: Page): Promise<void> {
+  await gotoHome(page);
+}
+
+/**
+ * Wait for the sidebar to show at least one project row. Use this after a spec
+ * seeds a workspace/project; zero-project flows need their own assertion.
+ */
+export async function waitForSidebarHydration(page: Page, timeout = 60_000): Promise<void> {
+  await page
+    .locator('[data-testid^="sidebar-project-row-"]')
+    .first()
+    .waitFor({ state: "visible", timeout });
+}
+
+export async function waitForNoProjectsInSidebar(page: Page, timeout = 60_000): Promise<void> {
+  await page.getByTestId("sidebar-project-empty-state").waitFor({ state: "visible", timeout });
+}
+
+function workspaceRowLocator(page: Page, serverId: string, workspaceId: string) {
+  return page.getByTestId(`sidebar-workspace-row-${serverId}:${workspaceId}`).first();
+}
+
+export async function expectSidebarWorkspaceSelected(input: {
+  page: Page;
+  serverId: string;
+  workspaceId: string;
+  selected?: boolean;
+}): Promise<void> {
+  const row = workspaceRowLocator(input.page, input.serverId, input.workspaceId);
+  await expect(row).toBeVisible({ timeout: 30_000 });
+  const expected = input.selected === false ? "false" : "true";
+
+  const hasDataSelected = await row.getAttribute("data-selected");
+  if (hasDataSelected !== null) {
+    await expect(row).toHaveAttribute("data-selected", expected, {
+      timeout: 30_000,
+    });
+    return;
+  }
+
+  await expect(row).toHaveAttribute("aria-selected", expected, {
+    timeout: 30_000,
+  });
+}
+
+export async function switchWorkspaceViaSidebar(input: {
+  page: Page;
+  serverId: string;
+  workspaceId: string;
+}): Promise<void> {
+  const row = workspaceRowLocator(input.page, input.serverId, input.workspaceId);
+  await expect(row).toBeVisible({ timeout: 30_000 });
+  await row.click();
+
+  const targetWorkspaceRoute = buildHostWorkspaceRoute(input.serverId, input.workspaceId);
+  await expectAppRoute(input.page, targetWorkspaceRoute, { timeout: 30_000 });
+}
+
+/**
+ * Wait for a workspace's sidebar row to appear, confirming the workspace
+ * descriptor has been hydrated into the session store.
+ */
+export async function waitForWorkspaceInSidebar(
+  page: Page,
+  input: { serverId: string; workspaceId: string },
+): Promise<void> {
+  await workspaceRowLocator(page, input.serverId, input.workspaceId).waitFor({
+    state: "visible",
+    timeout: 60_000,
+  });
+}
+
+export async function expectWorkspaceHeader(
+  page: Page,
+  input: { title: string; subtitle: string },
+): Promise<void> {
+  const titleLocator = page.getByTestId("workspace-header-title").filter({ visible: true });
+  const subtitleLocator = page.getByTestId("workspace-header-subtitle").filter({ visible: true });
+
+  await expect(titleLocator.first()).toHaveText(input.title, {
+    timeout: 30_000,
+  });
+  await expect(subtitleLocator.first()).toHaveText(input.subtitle, {
+    timeout: 30_000,
+  });
+}
+
+export async function expectReconnectingToastVisible(
+  page: Page,
+  options?: { timeout?: number },
+): Promise<void> {
+  await expect(page.getByTestId("agent-reconnecting-toast")).toBeVisible({
+    timeout: options?.timeout ?? 30_000,
+  });
+}
+
+export async function expectReconnectingToastGone(
+  page: Page,
+  options?: { timeout?: number },
+): Promise<void> {
+  await expect(page.getByTestId("agent-reconnecting-toast")).toHaveCount(0, {
+    timeout: options?.timeout ?? 30_000,
+  });
+}
+
+export async function expectHostConnectingOrOffline(
+  page: Page,
+  options?: { timeout?: number },
+): Promise<void> {
+  await expect(
+    page.getByText(/^Connecting$|localhost is offline|Cannot reach localhost/i),
+  ).toBeVisible({ timeout: options?.timeout ?? 30_000 });
+}
+
+export async function expectMenuButtonVisible(page: Page): Promise<void> {
+  await expect(page.getByTestId("menu-button")).toBeVisible();
+}
+
+export async function expectWorkspaceHeaderAbsent(page: Page): Promise<void> {
+  await expect(page.getByTestId("workspace-header-title")).toHaveCount(0);
+}
+
+export function workspaceDeckEntryLocator(page: Page, serverId: string, workspaceId: string) {
+  return page.getByTestId(`workspace-deck-entry-${serverId}:${workspaceId}`);
+}
+
+export async function expectWorkspaceDeckEntryCount(page: Page, count: number): Promise<void> {
+  await expect(page.locator('[data-testid^="workspace-deck-entry-"]')).toHaveCount(count);
+}
+
+export async function seedWorkspaceActivity(page: Page, marker: string): Promise<void> {
+  const input = page.getByRole("textbox", { name: "Message agent..." });
+  await expect(input).toBeEditable({ timeout: 30_000 });
+  await input.fill(marker);
+  await input.press("Enter");
+  await expect(page).toHaveURL(/\/workspace\//, { timeout: 30_000 });
+}

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

@@ -0,0 +1,187 @@
+import { execSync } from "node:child_process";
+import { mkdtemp, writeFile, rm, mkdir, realpath } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+const TEMP_CLEANUP_RETRIES = 5;
+const TEMP_CLEANUP_RETRY_DELAY_MS = 100;
+
+interface TempRepo {
+  path: string;
+  branchHeads: Record<string, string>;
+  cleanup: () => Promise<void>;
+}
+
+export interface TempDirectory {
+  path: string;
+  cleanup: () => Promise<void>;
+}
+
+/**
+ * The temp root for E2E fixtures. On macOS we resolve symlinks (/tmp →
+ * /private/tmp) so fixture paths match the daemon's resolved paths; on Windows
+ * `/tmp` doesn't exist, so fall back to the OS temp dir.
+ */
+export async function resolveTempRoot(): Promise<string> {
+  return process.platform === "win32" ? tmpdir() : await realpath("/tmp");
+}
+
+async function configureRemote(input: {
+  repoPath: string;
+  withRemote: boolean;
+  originUrl: string | undefined;
+}): Promise<void> {
+  const { repoPath, withRemote, originUrl } = input;
+  if (withRemote) {
+    // Deterministic local remote to avoid relying on external auth/network in e2e.
+    const remoteDir = path.join(repoPath, "remote.git");
+    await mkdir(remoteDir, { recursive: true });
+    execSync(`git init --bare -b main ${remoteDir}`, { cwd: repoPath, stdio: "ignore" });
+    execSync(`git remote add origin ${remoteDir}`, { cwd: repoPath, stdio: "ignore" });
+    execSync("git push -u origin --all", { cwd: repoPath, stdio: "ignore" });
+    if (originUrl) {
+      // Relabel origin to a display URL after the local tracking remote is set
+      // up, so project grouping shows the remote's owner/repo while branch
+      // tracking refs still resolve locally (no fetch from the synthetic URL).
+      execSync(`git remote set-url origin ${JSON.stringify(originUrl)}`, {
+        cwd: repoPath,
+        stdio: "ignore",
+      });
+    }
+    return;
+  }
+  if (originUrl) {
+    // Daemon reads origin for project grouping; no fetch occurs, so a synthetic URL is fine.
+    execSync(`git remote add origin ${JSON.stringify(originUrl)}`, {
+      cwd: repoPath,
+      stdio: "ignore",
+    });
+  }
+}
+
+export const createTempGitRepo = async (
+  prefix = "paseo-e2e-",
+  options?: {
+    withRemote?: boolean;
+    originUrl?: string;
+    paseoConfig?: Record<string, unknown>;
+    files?: Array<{ path: string; content: string }>;
+    branches?: string[];
+  },
+): Promise<TempRepo> => {
+  // Keep E2E repo paths short so terminal prompt + typed commands stay visible without zsh clipping.
+  const repoPath = await mkdtemp(path.join(await resolveTempRoot(), prefix));
+  const withRemote = options?.withRemote ?? false;
+
+  execSync("git init -b main", { cwd: repoPath, stdio: "ignore" });
+  execSync('git config user.email "e2e@paseo.test"', { cwd: repoPath, stdio: "ignore" });
+  execSync('git config user.name "Paseo E2E"', { cwd: repoPath, stdio: "ignore" });
+  execSync("git config commit.gpgsign false", { cwd: repoPath, stdio: "ignore" });
+  await writeFile(path.join(repoPath, "README.md"), "# Temp Repo\n");
+  if (options?.paseoConfig) {
+    await writeFile(
+      path.join(repoPath, "paseo.json"),
+      JSON.stringify(options.paseoConfig, null, 2),
+    );
+  }
+  for (const file of options?.files ?? []) {
+    const filePath = path.join(repoPath, file.path);
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, file.content);
+  }
+  execSync("git add README.md", { cwd: repoPath, stdio: "ignore" });
+  if (options?.paseoConfig) {
+    execSync("git add paseo.json", { cwd: repoPath, stdio: "ignore" });
+  }
+  for (const file of options?.files ?? []) {
+    execSync(`git add ${JSON.stringify(file.path)}`, { cwd: repoPath, stdio: "ignore" });
+  }
+  execSync('git commit -m "Initial commit"', { cwd: repoPath, stdio: "ignore" });
+
+  const branchHeads: Record<string, string> = {};
+  const branches = Array.from(new Set(options?.branches ?? []));
+  for (const branch of branches) {
+    if (branch !== "main") {
+      execSync(`git checkout -b ${JSON.stringify(branch)} main`, {
+        cwd: repoPath,
+        stdio: "ignore",
+      });
+    }
+    const markerPath = `.paseo-e2e-${branch.replace(/[^a-zA-Z0-9._-]/g, "-")}.txt`;
+    await writeFile(path.join(repoPath, markerPath), `branch ${branch}\n`);
+    execSync(`git add ${JSON.stringify(markerPath)}`, { cwd: repoPath, stdio: "ignore" });
+    execSync(`git commit -m ${JSON.stringify(`Add ${branch} marker`)}`, {
+      cwd: repoPath,
+      stdio: "ignore",
+    });
+    branchHeads[branch] = execSync(`git rev-parse ${JSON.stringify(branch)}`, {
+      cwd: repoPath,
+      stdio: "pipe",
+    })
+      .toString()
+      .trim();
+    execSync("git checkout main", { cwd: repoPath, stdio: "ignore" });
+  }
+
+  await configureRemote({ repoPath, withRemote, originUrl: options?.originUrl });
+
+  return {
+    path: repoPath,
+    branchHeads,
+    cleanup: async () => {
+      await rm(repoPath, {
+        recursive: true,
+        force: true,
+        maxRetries: TEMP_CLEANUP_RETRIES,
+        retryDelay: TEMP_CLEANUP_RETRY_DELAY_MS,
+      });
+    },
+  };
+};
+
+/**
+ * A plain (non-git) directory opened as a project. The daemon shows its
+ * basename as the project name, since there's no remote to group under.
+ */
+export async function createTempDirectory(prefix = "paseo-e2e-dir-"): Promise<TempDirectory> {
+  const dirPath = await mkdtemp(path.join(await resolveTempRoot(), prefix));
+  await writeFile(path.join(dirPath, "README.md"), "# Temp Directory\n");
+  return {
+    path: dirPath,
+    cleanup: async () => {
+      await rm(dirPath, {
+        recursive: true,
+        force: true,
+        maxRetries: TEMP_CLEANUP_RETRIES,
+        retryDelay: TEMP_CLEANUP_RETRY_DELAY_MS,
+      });
+    },
+  };
+}
+
+export async function readWorktreeBranchInfo({ worktreePath }: { worktreePath: string }): Promise<{
+  currentBranch: string;
+  hasAncestor: (ref: string) => boolean;
+}> {
+  const currentBranch = execSync("git branch --show-current", {
+    cwd: worktreePath,
+    stdio: "pipe",
+  })
+    .toString()
+    .trim();
+
+  return {
+    currentBranch,
+    hasAncestor: (ref: string) => {
+      try {
+        execSync(`git merge-base --is-ancestor ${JSON.stringify(ref)} HEAD`, {
+          cwd: worktreePath,
+          stdio: "ignore",
+        });
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  };
+}