chore(release): cut 0.1.86

Adds the /grok SEO landing page (and its auto-generated route/sitemap
entries), the /agents directory card, and the Grok line in the ACP
catalog docs, following the Grok Build provider added to the in-app
catalog.

.agents/skills/release-beta/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: release-beta
+description: Cut a beta release of Paseo. Use when the user says "release beta", "cut a beta", "ship a beta", "beta release", or "/release-beta". Betas are silent release candidates — no changelog, no website move.
+user-invocable: true
+---
+
+# Release beta
+
+Read `docs/release.md` in the Paseo repo and follow the **Beta flow** section end-to-end. Run the **Beta release** completion checklist at the bottom of that doc.
+
+Key rule the doc enforces — betas don't touch `CHANGELOG.md`. Don't draft release notes.

.agents/skills/release-stable/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: release-stable
+description: Cut a stable release of Paseo (fresh patch or promote from beta). Use when the user says "release stable", "ship stable", "promote", "release:patch", "release:promote", or "/release-stable".
+user-invocable: true
+---
+
+# Release stable
+
+Read `docs/release.md` in the Paseo repo and follow the **Standard release (patch)** flow if cutting fresh, or the **Beta flow** promotion step if promoting an existing beta. Run the **Stable release (or promotion)** completion checklist at the bottom of that doc.
+
+The doc covers the changelog (required for stable), the pre-release sanity check (required for stable), and the post-release babysit pattern. Don't skip steps.

.claude/skills/release-beta

@@ -0,0 +1 @@
+../../.agents/skills/release-beta

.claude/skills/release-stable

@@ -0,0 +1 @@
+../../.agents/skills/release-stable

.github/workflows/ci.yml

@@ -12,6 +12,11 @@ concurrency:
   group: ci-${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
+env:
+  # CI does not use the CUDA execution provider, and the onnxruntime-node
+  # postinstall download from NuGet is large enough to make npm ci flaky.
+  ONNXRUNTIME_NODE_INSTALL: skip
+
 jobs:
   format:
     runs-on: ubuntu-latest
@@ -64,18 +69,18 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Build highlight dependency
-        run: npm run build --workspace=@getpaseo/highlight
-
-      - name: Build relay dependency
-        run: npm run build --workspace=@getpaseo/relay
-
-      - name: Build server dependency
-        run: npm run build --workspace=@getpaseo/server
+      - name: Build server stack
+        run: npm run build:server
 
       - name: Typecheck all packages
         run: npm run typecheck
 
+      - name: Verify public package contents
+        run: |
+          npm pack --dry-run --ignore-scripts --workspace=@getpaseo/protocol
+          npm pack --dry-run --ignore-scripts --workspace=@getpaseo/client
+          npm pack --dry-run --ignore-scripts --workspace=@getpaseo/server
+
   server-tests:
     strategy:
       fail-fast: false
@@ -99,20 +104,18 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Install Claude Code CLI for provider tests
-        run: npm install -g @anthropic-ai/claude-code
+      - name: Install agent CLIs for provider tests
+        run: npm install -g @anthropic-ai/claude-code opencode-ai
 
-      - name: Build highlight dependency
-        run: npm run build --workspace=@getpaseo/highlight
-
-      - name: Build relay dependency
-        run: npm run build --workspace=@getpaseo/relay
+      - name: Build server dependencies
+        run: npm run build:server-deps
 
       - name: Run server tests
         run: npm run test --workspace=@getpaseo/server
         env:
           CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
 
   desktop-tests:
     strategy:
@@ -131,14 +134,8 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Build highlight dependency
-        run: npm run build --workspace=@getpaseo/highlight
-
-      - name: Build relay dependency
-        run: npm run build --workspace=@getpaseo/relay
-
-      - name: Build server dependency
-        run: npm run build --workspace=@getpaseo/server
+      - name: Build server stack
+        run: npm run build:server
 
       - name: Run desktop tests
         run: npm run test --workspace=@getpaseo/desktop
@@ -159,12 +156,37 @@ jobs:
       - name: Install Playwright browsers
         run: npx playwright install --with-deps chromium
 
-      - name: Build highlight dependency
-        run: npm run build --workspace=@getpaseo/highlight
+      - name: Build app dependencies
+        run: npm run build:app-deps
 
       - name: Run app unit tests
         run: npm run test --workspace=@getpaseo/app
 
+  sdk-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build client dependencies
+        run: npm run build:client
+
+      - name: Run protocol tests
+        run: npm run test --workspace=@getpaseo/protocol
+
+      - name: Run client tests
+        run: npm run test --workspace=@getpaseo/client
+
+      - name: Typecheck client examples
+        run: npm run typecheck:examples --workspace=@getpaseo/client
+
   playwright:
     runs-on: ubuntu-latest
     steps:
@@ -181,14 +203,11 @@ jobs:
       - name: Install Playwright browsers
         run: npx playwright install --with-deps chromium
 
-      - name: Build highlight dependency
-        run: npm run build --workspace=@getpaseo/highlight
+      - name: Build app dependencies
+        run: npm run build:app-deps
 
-      - name: Build relay dependency
-        run: npm run build --workspace=@getpaseo/relay
-
-      - name: Build server dependency
-        run: npm run build --workspace=@getpaseo/server
+      - name: Build server stack
+        run: npm run build:server
 
       - name: Install agent CLIs for provider tests
         run: npm install -g @anthropic-ai/claude-code @openai/codex@0.105.0 opencode-ai
@@ -222,7 +241,7 @@ jobs:
         run: npm ci
 
       - name: Build relay
-        run: npm run build --workspace=@getpaseo/relay
+        run: npm run build:relay
 
       - name: Run relay tests
         run: npm run test --workspace=@getpaseo/relay
@@ -248,9 +267,6 @@ jobs:
       - name: Install agent CLIs for provider tests
         run: npm install -g @anthropic-ai/claude-code @openai/codex@0.105.0 opencode-ai
 
-      - name: Build highlight dependency
-        run: npm run build --workspace=@getpaseo/highlight
-
       - name: Run CLI tests
         run: npm run test --workspace=@getpaseo/cli
         env:

.github/workflows/deploy-app.yml

@@ -28,8 +28,8 @@ jobs:
         env:
           NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Build highlight dependency
-        run: npm run build --workspace=@getpaseo/highlight
+      - name: Build app dependencies
+        run: npm run build:app-deps
 
       - name: Typecheck
         run: npm run typecheck --workspace=@getpaseo/app

.github/workflows/deploy-website.yml

@@ -5,6 +5,7 @@ on:
     branches: [main]
     paths:
       - "CHANGELOG.md"
+      - "public-docs/**"
       - "packages/website/**"
       - "package.json"
       - "package-lock.json"

.github/workflows/desktop-release.yml

@@ -183,6 +183,14 @@ jobs:
           fi
           gh release upload "$RELEASE_TAG" "${files[@]}" --clobber --repo "${{ github.repository }}"
 
+      - name: Upload desktop artifacts to workflow
+        if: env.SHOULD_PUBLISH != 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: desktop-macos-${{ matrix.electron_arch }}
+          path: ${{ env.DESKTOP_PACKAGE_PATH }}/release/*.dmg
+          retention-days: 7
+
       - name: Upload manifest artifact
         if: env.SHOULD_PUBLISH == 'true' && env.IS_SMOKE_TAG != 'true'
         uses: actions/upload-artifact@v4
@@ -273,6 +281,14 @@ jobs:
           fi
           gh release upload "$RELEASE_TAG" "${files[@]}" --clobber --repo "${{ github.repository }}"
 
+      - name: Upload desktop artifacts to workflow
+        if: env.SHOULD_PUBLISH != 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: desktop-linux
+          path: ${{ env.DESKTOP_PACKAGE_PATH }}/release/*
+          retention-days: 7
+
       - name: Upload manifest artifact
         if: env.SHOULD_PUBLISH == 'true' && env.IS_SMOKE_TAG != 'true'
         uses: actions/upload-artifact@v4
@@ -360,6 +376,14 @@ jobs:
           fi
           gh release upload "$RELEASE_TAG" "${files[@]}" --clobber --repo "${{ github.repository }}"
 
+      - name: Upload desktop artifacts to workflow
+        if: env.SHOULD_PUBLISH != 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: desktop-windows
+          path: ${{ env.DESKTOP_PACKAGE_PATH }}/release/*
+          retention-days: 7
+
       - name: Upload manifest artifact
         if: env.SHOULD_PUBLISH == 'true' && env.IS_SMOKE_TAG != 'true'
         uses: actions/upload-artifact@v4

.github/workflows/nix.yml

@@ -10,6 +10,8 @@ on:
       - "package.json"
       - "package-lock.json"
       - "packages/highlight/**"
+      - "packages/protocol/**"
+      - "packages/client/**"
       - "packages/server/**"
       - "packages/relay/**"
       - "packages/cli/**"

.gitignore

@@ -6,6 +6,7 @@ build/
 dist/
 .next/
 out/
+result
 
 # Environment variables
 .env

CLAUDE.md

@@ -2,7 +2,7 @@
 
 Paseo is a mobile app for monitoring and controlling your local AI coding agents from anywhere. Your dev environment, in your pocket. Connects directly to your actual development environment — your code stays on your machine.
 
-**Supported agents:** Claude Code, Codex, and OpenCode.
+**Supported agents:** Claude Code, Codex, GitHub Copilot, OpenCode, and Pi.
 
 ## Repository map
 
@@ -32,6 +32,7 @@ At the start of non-trivial work, list `docs/` and skim anything relevant to the
 | [docs/design.md](docs/design.md)                               | Theme tokens — colors, fonts, spacing, radii, icons                                                                            |
 | [docs/hover.md](docs/hover.md)                                 | Hover — the canonical pattern (plain View + onPointerEnter/Leave, separate inner Pressable) and the three ways agents break it |
 | [docs/unistyles.md](docs/unistyles.md)                         | Unistyles gotchas — `useUnistyles()` is forbidden, alternatives in order                                                       |
+| [docs/floating-panels.md](docs/floating-panels.md)             | Anchored popovers — Portal/Modal escape for Android, lifecycle gates, keyboard-shared-value, status-bar offset, the flash      |
 | [docs/file-icons.md](docs/file-icons.md)                       | Material icon theme integration for the file explorer                                                                          |
 | [docs/providers.md](docs/providers.md)                         | Adding a new agent provider end-to-end                                                                                         |
 | [docs/custom-providers.md](docs/custom-providers.md)           | Custom provider config: Z.AI, Alibaba/Qwen, ACP agents, profiles, custom binaries                                              |
@@ -70,8 +71,9 @@ See [docs/development.md](docs/development.md) for full setup, build sync requir
   - Never re-run a test suite that another agent already ran and reported green — trust the result.
   - For full suite verification, push to CI and check GitHub Actions instead.
 - **Always run typecheck and lint after every change.**
-- **Build workspace packages before diagnosing cross-package type errors.** This repo consumes generated declarations across workspaces. If typecheck fails in a package that depends on another workspace (especially CLI depending on server/daemon types), rebuild the owning package first so `dist` declarations are current:
-  - `npm run build:daemon` — rebuild highlight, relay, server, and CLI when daemon/server/CLI types may be stale.
+- **Build workspace packages before diagnosing cross-package type errors.** This repo consumes generated declarations across workspaces. If typecheck fails in a package that depends on another workspace, rebuild the owning stack first so `dist` declarations are current:
+  - `npm run build:client` — rebuild protocol and client declarations.
+  - `npm run build:server` — rebuild highlight, relay, protocol, client, server, and CLI when server/CLI types may be stale.
   - Do not patch inferred callback parameters or add local duplicate types just to silence stale declaration errors.
 - **Run `npm run format` before committing.** This repo uses Biome for formatting. Do not manually fix formatting — let the formatter handle it.
 - **Always use npm scripts for linting and formatting.** Do not run tools directly with `npx eslint`, `npx oxfmt`, `npx oxlint`, or package-local binaries. For targeted checks, pass file paths through the npm script:

README.md

@@ -17,9 +17,12 @@
   <a href="https://discord.gg/jz8T2uahpH">
     <img src="https://img.shields.io/badge/Discord-555?logo=discord" alt="Discord">
   </a>
+  <a href="https://www.reddit.com/r/PaseoAI/">
+    <img src="https://img.shields.io/badge/Reddit-555?logo=reddit" alt="Reddit">
+  </a>
 </p>
 
-<p align="center">One interface for all your Claude Code, Codex and OpenCode agents.</p>
+<p align="center">One interface for Claude Code, Codex, Copilot, OpenCode, and Pi agents.</p>
 
 <p align="center">
   <img src="https://paseo.sh/hero-mockup.png" alt="Paseo app screenshot" width="100%">
@@ -34,7 +37,7 @@
 Run agents in parallel on your own machines. Ship from your phone or your desk.
 
 - **Self-hosted:** Agents run on your machine with your full dev environment. Use your tools, your configs, and your skills.
-- **Multi-provider:** Claude Code, Codex, and OpenCode through the same interface. Pick the right model for each job.
+- **Multi-provider:** Claude Code, Codex, Copilot, OpenCode, and Pi through the same interface. Pick the right model for each job.
 - **Voice control:** Dictate tasks or talk through problems in voice mode. Hands-free when you need it.
 - **Cross-device:** iOS, Android, desktop, web, and CLI. Start work at your desk, check in from your phone, script it from the terminal.
 - **Privacy-first:** Paseo doesn't have any telemetry, tracking, or forced log-ins.
@@ -49,7 +52,9 @@ You need at least one agent CLI installed and configured with your credentials:
 
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
 - [Codex](https://github.com/openai/codex)
+- [GitHub Copilot](https://github.com/features/copilot/cli/)
 - [OpenCode](https://github.com/anomalyco/opencode)
+- [Pi](https://pi.dev)
 
 ### Desktop app (recommended)
 
@@ -129,8 +134,8 @@ npm run dev:app
 npm run dev:desktop
 npm run dev:website
 
-# build the daemon
-npm run build:daemon
+# build the server stack
+npm run build:server
 
 # repo-wide checks
 npm run typecheck

SECURITY.md

@@ -46,6 +46,8 @@ By default, the daemon binds to `127.0.0.1`. With no password configured, the lo
 
 The daemon also supports an optional shared-secret password (set via `auth.password` in `config.json` or the `PASEO_PASSWORD` env var; stored bcrypt-hashed). When configured, every HTTP request must carry `Authorization: Bearer <password>` and every WebSocket upgrade must include a `Sec-WebSocket-Protocol: paseo.bearer.<password>` subprotocol. Browser WebSocket cannot set custom headers, which is why the token rides in the subprotocol. Health (`GET /api/health`) and CORS preflight (`OPTIONS`) are exempt. The password is intended for direct-TCP exposure (e.g. `tcp://host:port?ssl=true&password=...`); it is **not** a substitute for the relay's E2E encryption when traversing untrusted networks.
 
+Connected clients are trusted operators of the daemon user. File previews follow that authority: a preview request may read any regular file the daemon process can read, while keeping path normalization and symlink checks in the daemon file service. Workspace-relative paths remain a UI convenience, not a security boundary.
+
 If you expose the daemon beyond loopback, such as by binding to `0.0.0.0`, forwarding it through a tunnel or reverse proxy, or publishing it from a Docker container, you are responsible for restricting and securing that access. Setting a password is strongly recommended in that case.
 
 For remote access, use the relay connection. It is the supported path for reaching the daemon off-machine, and it adds end-to-end encryption plus a pairing handshake before commands are accepted.

docs/agent-lifecycle.md

@@ -27,6 +27,8 @@ Both look the same in storage. This is an accepted limitation — see [Limitatio
 
 Archive is a **soft delete**: the agent record stays on disk with `archivedAt` set, the runtime is closed, and the agent disappears from active lists. Archive is **global** — it lives on the server and propagates to every connected client.
 
+`create_agent_request` can opt an agent into `autoArchive`. In that mode the daemon archives the agent after the first terminal turn event (`turn_completed`, `turn_failed`, or `turn_canceled`). If the same request created a Paseo worktree through its `worktree` field, auto-archive archives that worktree too, which removes the agent records inside the worktree.
+
 Archiving runs through `AgentManager.archiveAgent` (`packages/server/src/server/agent/agent-manager.ts`):
 
 1. Snapshot the current session into the registry
@@ -54,7 +56,7 @@ The asymmetry is intentional: a subagent's home is the parent's track, not the t
 
 ## The subagents track
 
-The collapsible section above the composer in an agent's pane (`packages/app/src/subagents/subagents-section.tsx`). Membership rule (`packages/app/src/subagents/subagents.ts`):
+The collapsible track above the composer in an agent's pane (`packages/app/src/subagents/track.tsx`). Membership rule (`packages/app/src/subagents/select.ts`):
 
 ```
 parentAgentId === thisAgent.id  AND  !archivedAt

docs/android.md

@@ -27,17 +27,21 @@ Or from `packages/app`:
 
 ```bash
 # Debug
-APP_VARIANT=development npx expo prebuild --platform android --non-interactive
-APP_VARIANT=development npx expo run:android --variant=debug
+npx cross-env APP_VARIANT=development expo prebuild --platform android --non-interactive
+npx cross-env APP_VARIANT=development expo run:android --variant=debug
 
 # Release
-APP_VARIANT=production npx expo prebuild --platform android --non-interactive
-APP_VARIANT=production npx expo run:android --variant=release
+npx cross-env APP_VARIANT=production expo prebuild --platform android --non-interactive
+npx cross-env APP_VARIANT=production expo run:android --variant=release
 
 # Clear generated Android project
 rm -rf android
 ```
 
+### React version lockstep
+
+Keep `react` and `react-dom` pinned to the React version embedded by the current `react-native` release. React Native `0.81.x` embeds `react-native-renderer` `19.1.0`, so `packages/app` must use React `19.1.0`. Bumping React to a newer patch can build successfully but crash at JS startup on Android with `Incompatible React versions`, leaving the app on the native splash screen.
+
 ## Screenshots
 
 ```bash
@@ -48,24 +52,28 @@ adb exec-out screencap -p > screenshot.png
 
 Stable tag pushes like `v0.1.0` trigger:
 
-- `packages/app/.eas/workflows/release-mobile.yml` on Expo servers (iOS + Android build + submit)
-- `.github/workflows/android-apk-release.yml` on GitHub Actions (APK asset on GitHub Release)
+- The EAS GitHub app on Expo servers (iOS + Android production builds + store submit). There is no workflow file in this repo for it.
+- `.github/workflows/android-apk-release.yml` on GitHub Actions (APK asset on GitHub Release).
+
+iOS auto-submits to App Store review via a Fastlane lane after EAS uploads to TestFlight. Android auto-submits to the Play Store via EAS-managed credentials.
 
 Beta tags like `v0.1.1-beta.1` only trigger the GitHub APK workflow. They publish a GitHub prerelease APK for testing and do not submit to the stores.
 
-`android-v*` tags also trigger only the GitHub APK workflow — useful when you want to ship an APK without going through stores. Both workflows also support `workflow_dispatch`; the GitHub APK one takes an existing `tag` input so you can rebuild without cutting a new tag.
+`android-v*` tags also trigger only the GitHub APK workflow — useful when you want to ship an APK without going through stores. The GitHub APK workflow supports `workflow_dispatch` with an existing `tag` input so you can rebuild without cutting a new tag.
 
 ### Useful commands
 
 ```bash
 cd packages/app
 
-# List recent workflow runs
-npx eas workflow:runs --workflow release-mobile.yml --limit 10
+# Recent builds
+npx eas build:list --limit 10 --non-interactive --json | jq '.[] | {platform, status, appVersion, gitCommitHash}'
 
-# Inspect a run
-npx eas workflow:view <run-id>
-
-# Stream logs for a failed job
-npx eas workflow:logs <job-id> --non-interactive --all-steps
+# Inspect a build (the printed `Logs` URL opens the build's Expo dashboard page,
+# which has a Submissions section showing the auto-submit to the Play Store).
+npx eas build:view <build-id>
 ```
+
+The Play Console (Internal testing → Production tracks) is the final confirmation that the binary reached the store.
+
+See [docs/release.md](release.md) for the full mobile-build babysitting flow.

docs/architecture.md

@@ -22,13 +22,13 @@ Your code never leaves your machine. Paseo is local-first.
             │  (Node.js)  │
             └──────┬──────┘
                    │
-      ┌────────────┼────────────┐
-      │            │            │
-┌─────▼─────┐ ┌───▼────┐ ┌────▼─────┐
-│  Claude   │ │ Codex  │ │ OpenCode │
-│  Agent    │ │ Agent  │ │  Agent   │
-│  SDK      │ │ Server │ │          │
-└───────────┘ └────────┘ └──────────┘
+      ┌────────────┼────────────┬────────────┬────────────┐
+      │            │            │            │            │
+┌─────▼─────┐ ┌───▼────┐ ┌──────▼─────┐ ┌────▼─────┐ ┌────▼────┐
+│  Claude   │ │ Codex  │ │  Copilot   │ │ OpenCode │ │   Pi    │
+│  Agent    │ │ Agent  │ │   Agent    │ │  Agent   │ │ Agent   │
+│  SDK      │ │ Server │ │    ACP     │ │          │ │         │
+└───────────┘ └────────┘ └────────────┘ └──────────┘ └─────────┘
 ```
 
 ## Components at a glance
@@ -68,9 +68,20 @@ All paths are under `packages/server/src/`.
 | `server/schedule/`              | Cron-based scheduled agents                                                  |
 | `server/loop-service.ts`        | Looping agent runs that retry until an exit condition                        |
 | `server/chat/`                  | Chat rooms for agent-to-agent and human-to-agent messaging                   |
-| `client/daemon-client.ts`       | Client library for connecting to the daemon (used by CLI and app)            |
-| `shared/messages.ts`            | Zod schemas for the entire wire protocol                                     |
-| `shared/binary-frames/`         | Terminal stream and file transfer binary frame codecs                        |
+
+### `packages/protocol` — Wire schemas and shared protocol types
+
+The source of truth for WebSocket messages, binary frame codecs, endpoint parsing,
+agent timeline types, provider config schemas, and other values shared by daemon
+and clients. Server, app, CLI, and `@getpaseo/client` all depend on this package;
+it does not depend on the server.
+
+### `packages/client` — Daemon client library and SDK facade
+
+Owns the low-level daemon WebSocket driver plus the higher-level `PaseoClient`
+facade. App and CLI may import the low-level driver from
+`@getpaseo/client/internal/daemon-client` during migration, while new SDK-shaped
+code imports from `@getpaseo/client`.
 
 ### `packages/app` — Mobile + web client (Expo)
 
@@ -79,7 +90,9 @@ Cross-platform React Native app that connects to one or more daemons.
 - Expo Router navigation (`/h/[serverId]/workspace/[workspaceId]`, `/h/[serverId]/agent/[agentId]`, etc.)
 - `HostRuntimeController` manages saved host connections, reconnection, and per-host runtime state
 - `SessionContext` wraps the daemon client for the active session
+- Composer UI and submit/draft behavior live in `packages/app/src/composer/`; screens and panels should integrate it from there instead of dropping composer internals into `components/`, `hooks/`, or `screens/workspace/`
 - Timeline reducers in `timeline/session-stream-reducers.ts` handle compaction, gap detection, sequence-based deduplication
+- Timeline sync correctness is documented in [docs/timeline-sync.md](timeline-sync.md): live streams are for immediacy, `fetch_agent_timeline_request` is authoritative, and catch-up is paged but complete.
 - Voice features: dictation (STT) and voice agent (realtime)
 
 ### `packages/cli` — Command-line client
@@ -107,7 +120,7 @@ Enables remote access when the daemon is behind a firewall.
 - Relay server is zero-knowledge — it routes encrypted bytes, cannot read content
 - Client and daemon channels with identical API (`createClientChannel`, `createDaemonChannel`)
 - Pairing via QR code transfers the daemon's public key to the client
-- Self-hosted relays opt into TLS with `daemon.relay.useTls` or `PASEO_RELAY_USE_TLS=true`
+- Self-hosted relays opt into TLS with `daemon.relay.useTls` or `PASEO_RELAY_USE_TLS=true`; the public (client-facing) TLS setting can be overridden independently via `daemon.relay.publicUseTls` or `PASEO_RELAY_PUBLIC_USE_TLS`
 
 See [SECURITY.md](../SECURITY.md) for the full threat model.
 
@@ -125,7 +138,7 @@ TanStack Router + Cloudflare Workers. Serves paseo.sh.
 
 ## WebSocket protocol
 
-All clients speak the same WebSocket protocol over a single connection that mixes JSON text frames and a small binary framing for terminal streams. Schemas live in `packages/server/src/shared/messages.ts`.
+All clients speak the same WebSocket protocol over a single connection that mixes JSON text frames and a small binary framing for terminal streams. Schemas live in `packages/protocol/src/messages.ts`.
 
 **Handshake:**
 
@@ -146,6 +159,8 @@ There is no dedicated welcome message; the server emits a `status` session messa
 
 **Top-level WS envelopes** are `hello`, `recording_state`, `ping`/`pong`, and `session` (which wraps the rich union of session messages).
 
+Client liveness checks use the top-level JSON `ping`/`pong` envelope, not a session RPC and not RFC6455 protocol ping. The app runs through browser and React Native WebSocket APIs, which do not expose protocol ping, so this envelope is the portable way to test the direct or relay data path. Session RPC timeouts are operation failures and must not be treated as proof that the socket is dead.
+
 New session RPCs use dotted names with `.request` and `.response` suffixes, such as `checkout.github.set_auto_merge.request` and `checkout.github.set_auto_merge.response`. See [rpc-namespacing.md](rpc-namespacing.md) for the convention and migration rules for older flat RPC names.
 
 **Notable session message types:**
@@ -208,23 +223,24 @@ initializing → idle ⇄ running
 - **AgentManager** is the source of truth for agent state and broadcasts updates to all subscribers
 - Timeline is append-only with epochs (each run starts a new epoch). Storage uses sequence numbers for client-side dedup; the default fetch page is 200 items
 - Timeline row `timestamp` values are canonical daemon-owned timestamps. Providers may supply original replay timestamps, but clients must not guess timestamp trust or hide time UI based on local clock heuristics.
-- Events stream to all subscribed clients in real time
+- Events stream to connected clients in real time; correctness is backed by authoritative timeline fetches and paged-to-completion catch-up.
 - Agent state persists to `$PASEO_HOME/agents/{cwd-with-dashes}/{agent-id}.json` (timeline rows live alongside the record)
 
 ## Agent providers
 
 Each provider implements the `AgentClient` interface in `agent/agent-sdk-types.ts`. Provider implementations live in `agent/providers/`.
 
-The three first-class, user-facing providers are Claude Code, Codex, and OpenCode. Additional adapters exist in the same directory for ACP-compatible agents and internal use:
+The built-in, user-facing providers are Claude Code, Codex, Copilot, OpenCode, and Pi. Additional adapters exist in the same directory for ACP-compatible agents and internal use:
 
 | Provider           | Wraps                                | Session format                                     |
 | ------------------ | ------------------------------------ | -------------------------------------------------- |
 | Claude (`claude/`) | Anthropic Agent SDK                  | `~/.claude/projects/{cwd}/{session-id}.jsonl`      |
 | Codex              | Codex AppServer (`codex-app-server`) | `~/.codex/sessions/{date}/rollout-{ts}-{id}.jsonl` |
+| Copilot            | GitHub Copilot via ACP               | Provider-managed                                   |
 | OpenCode           | OpenCode server / CLI                | Provider-managed                                   |
-| Cursor / Copilot   | ACP wrapper (`acp-agent`)            | Provider-managed                                   |
+| Cursor             | ACP wrapper (`acp-agent`)            | Provider-managed                                   |
 | Generic ACP        | ACP wrapper                          | Provider-managed                                   |
-| Pi-direct          | Direct Anthropic API call            | Stateless                                          |
+| Pi                 | Local Pi RPC process                 | Provider-managed                                   |
 | Mock load test     | In-process fake                      | In-memory                                          |
 
 All providers:

docs/custom-providers.md

@@ -24,6 +24,7 @@ Provider IDs must be lowercase alphanumeric with hyphens (`/^[a-z][a-z0-9-]*$/`)
 - [Extending a built-in provider](#extending-a-built-in-provider)
 - [Z.AI (Zhipu) coding plan](#zai-zhipu-coding-plan)
 - [Alibaba Cloud (Qwen) coding plan](#alibaba-cloud-qwen-coding-plan)
+- [Codex with a custom OpenAI-compatible endpoint](#codex-with-a-custom-openai-compatible-endpoint)
 - [Multiple profiles for the same provider](#multiple-profiles-for-the-same-provider)
 - [Custom binary for a provider](#custom-binary-for-a-provider)
 - [Disabling a provider](#disabling-a-provider)
@@ -59,29 +60,7 @@ Required fields for custom providers:
 - `extends` — which built-in provider to inherit from (or `"acp"`)
 - `label` — display name in the UI
 
-### Codex with an OpenAI-compatible endpoint
-
-Custom providers that extend `"codex"` can point Codex at an OpenAI-compatible API by setting `OPENAI_BASE_URL` and `OPENAI_API_KEY` in the provider `env`. Paseo still passes those variables through to the Codex app-server process, and also maps them into Codex's thread config (`model_provider` / `model_providers`) because Codex reads provider routing from config rather than from `OPENAI_BASE_URL`.
-
-```json
-{
-  "agents": {
-    "providers": {
-      "my-codex": {
-        "extends": "codex",
-        "label": "My Codex",
-        "env": {
-          "OPENAI_API_KEY": "sk-...",
-          "OPENAI_BASE_URL": "https://custom-relay.example.com"
-        },
-        "models": [{ "id": "custom-model", "label": "Custom Model", "isDefault": true }]
-      }
-    }
-  }
-}
-```
-
-If the base URL does not end in `/v1`, Paseo appends `/v1` for Codex's OpenAI-compatible provider config. If it already ends in `/v1`, Paseo leaves it as-is.
+See [Codex with a custom OpenAI-compatible endpoint](#codex-with-a-custom-openai-compatible-endpoint) below for the dedicated Codex example.
 
 ---
 
@@ -206,6 +185,62 @@ For pay-as-you-go, use `ANTHROPIC_API_KEY` with a standard Model Studio key (`sk
 
 ---
 
+## Codex with a custom OpenAI-compatible endpoint
+
+Codex talks to OpenAI's Responses API by default. Custom providers that extend `"codex"` can point Codex at any OpenAI-compatible endpoint (OpenRouter, LiteLLM, vLLM, llama.cpp server, an internal gateway, etc.) by setting `OPENAI_BASE_URL` and `OPENAI_API_KEY` in the provider `env`.
+
+Paseo passes those variables through to the Codex app-server process **and** maps them into Codex's thread config under `model_provider` / `model_providers`, because Codex reads provider routing from config rather than from `OPENAI_BASE_URL` alone.
+
+### Setup
+
+```json
+{
+  "agents": {
+    "providers": {
+      "my-codex": {
+        "extends": "codex",
+        "label": "My Codex",
+        "description": "Codex via custom OpenAI-compatible endpoint",
+        "env": {
+          "OPENAI_API_KEY": "sk-...",
+          "OPENAI_BASE_URL": "https://custom-relay.example.com"
+        },
+        "models": [{ "id": "custom-model", "label": "Custom Model", "isDefault": true }]
+      }
+    }
+  }
+}
+```
+
+### What Paseo wires up
+
+Under the hood, for each custom Codex provider Paseo injects this into Codex's config:
+
+```toml
+model_provider = "my-codex"
+
+[model_providers.my-codex]
+name = "My Codex"
+base_url = "https://custom-relay.example.com/v1"
+wire_api = "responses"
+env_key = "OPENAI_API_KEY"
+requires_openai_auth = false
+```
+
+- `base_url` — taken from `OPENAI_BASE_URL`. If it does not already end in `/v1`, Paseo appends `/v1`. Trailing slashes are stripped.
+- `wire_api` — always `"responses"` (OpenAI Responses API protocol).
+- `env_key` — set to `"OPENAI_API_KEY"` when that env var is present and non-empty, so Codex reads the key from the same env var Paseo passes through.
+- `requires_openai_auth` — forced to `false` when `OPENAI_API_KEY` is provided, so Codex skips its built-in OpenAI login flow.
+
+### Notes
+
+- The endpoint must speak the OpenAI **Responses API**, not just chat completions. Many gateways (OpenRouter, LiteLLM) support both — pick the Responses-compatible route.
+- Set `models` explicitly. Custom endpoints expose their own model IDs (`anthropic/claude-opus-4-7`, `qwen/qwen3-coder`, `local/llama`, etc.), and Paseo does not discover them automatically for Codex.
+- To run multiple endpoints side-by-side, define multiple entries that each extend `"codex"` with different IDs, labels, and env. Each appears as its own provider in the app.
+- If you only want to override the binary (e.g. a nightly Codex build) without changing the endpoint, omit `OPENAI_BASE_URL` and use `command` instead — see [Custom binary for a provider](#custom-binary-for-a-provider).
+
+---
+
 ## Multiple profiles for the same provider
 
 You can create multiple entries that extend the same built-in provider. Each gets its own entry in the provider list with independent credentials, models, and environment.
@@ -339,6 +374,8 @@ The [Agent Client Protocol (ACP)](https://agentclientprotocol.com) is an open st
 
 ACP agents communicate over JSON-RPC 2.0 on stdio. Paseo spawns the agent process and talks to it through stdin/stdout.
 
+Paseo also ships an in-app ACP provider catalog for common agents, including Cursor, DeepAgents, DeepSeek TUI, DimCode, Gemini CLI, Hermes, Qwen Code, and Kimi Code. Catalog entries create the same `extends: "acp"` provider config shown below.
+
 ### Adding a generic ACP provider
 
 Set `extends: "acp"` and provide a `command`:

docs/data-model.md

@@ -139,8 +139,9 @@ Single file, validated with `PersistedConfigSchema`.
     listen: "127.0.0.1:6767",
     hostnames: true | string[],   // legacy alias `allowedHosts` is migrated on load
     mcp: { enabled: boolean, injectIntoAgents: boolean },
+    appendSystemPrompt: string,    // appended to supported provider system/developer prompts
     cors: { allowedOrigins: string[] },
-    relay: { enabled: boolean, endpoint: string, publicEndpoint: string, useTls: boolean },
+    relay: { enabled: boolean, endpoint: string, publicEndpoint: string, useTls: boolean, publicUseTls: boolean },
     auth: { password: string }    // bcrypt hash, optional
   },
   app: {
@@ -154,7 +155,10 @@ Single file, validated with `PersistedConfigSchema`.
     // ProviderOverrideSchema; legacy entries with `command: { mode, ... }` are migrated to the
     // current shape on load via `migrateProviderSettings`. Custom provider IDs must declare
     // `extends` (one of the built-ins or `"acp"`) and `label`. See `provider-launch-config.ts`.
-    providers: Record<providerId, ProviderOverride>
+    providers: Record<providerId, ProviderOverride>,
+    metadataGeneration: {
+      providers: [{ provider, model?, thinkingOptionId? }]
+    }
   },
   features: {
     dictation: { enabled, stt: { provider, model, language, confidenceThreshold } },
@@ -170,6 +174,10 @@ Single file, validated with `PersistedConfigSchema`.
 
 All fields are optional with sensible defaults.
 
+`agents.metadataGeneration.providers` controls the preferred structured-generation fallback order for daemon-side metadata tasks such as commit messages, PR text, branch names, and generated agent titles. Entries are tried first in the configured order, then Paseo falls through to dynamically discovered defaults and finally the current selection when available.
+
+Local speech model ids are intentionally narrow: STT uses `parakeet-tdt-0.6b-v2-int8`, TTS uses `kokoro-en-v0_19`, and turn detection uses the bundled Silero VAD model.
+
 ---
 
 ## 3. Schedule

docs/development.md

@@ -43,6 +43,22 @@ In any worktree-style or portless setup, never assume default ports.
 `http://127.0.0.1:9223` so renderer CPU profiles can be captured through CDP.
 Override the port with `PASEO_ELECTRON_REMOTE_DEBUGGING_PORT` when `9223` is busy.
 
+### Desktop macOS compositor watchdog
+
+macOS display sleep can leave Chromium's GPU-process display link — the vsync
+source that drives frame production — stuck on a stale display. The compositor
+then stops producing frames and the window looks frozen: unresponsive to clicks
+and keys even though the renderer and every process stay alive. It self-recovers
+after a few minutes, which is too long for a foreground app.
+
+`setupDarwinCompositorWatchdog`
+(`packages/desktop/src/window/compositor-watchdog/index.ts`) guards against
+this. It polls the renderer for frame production every couple of seconds and,
+after a sustained stall while the window is visible and unlocked, restarts the
+GPU process so Chromium rebuilds the display link. The probe is skipped while
+the screen is locked or the window is hidden or minimized, since a window
+legitimately stops producing frames then.
+
 ### Daemon logs
 
 Check `$PASEO_HOME/daemon.log` for daemon logs. The default level is `info`; set
@@ -93,23 +109,28 @@ Every `scripts` entry with `"type": "service"` receives these environment variab
 }
 ```
 
-## Build sync gotchas
+## Built workspace packages
 
-The daemon and CLI consume sibling workspaces from compiled `dist/` output, not `src/`. When you change a workspace that something else imports, rebuild the producer first or the consumer will speak a stale protocol and fail with handshake warnings, timeouts, or stale type errors.
+Package imports resolve through package exports to compiled `dist/` output, not sibling `src/` files. This is true in local dev and in published packages: the app, daemon, CLI, and SDK consumers should all exercise the same runtime paths.
 
-The fastest way to keep this consistent is to rebuild the whole daemon stack with one command:
+`npm run dev`, `npm run dev:server`, and `npm run dev:app` build the workspace packages they need once, then keep `@getpaseo/protocol` and `@getpaseo/client` fresh with TypeScript watch builds while the daemon or Expo runs. If you change protocol schemas or client code outside those watch workflows, rebuild the producer before trusting runtime behavior.
+
+Use the named root build targets instead of remembering workspace dependency chains:
 
 ```bash
-npm run build:daemon
+npm run build:client       # protocol -> client
+npm run build:server-deps  # highlight -> relay -> protocol -> client
+npm run build:server       # server-deps -> server -> cli
+npm run build:app-deps     # highlight -> protocol -> client -> expo-two-way-audio
 ```
 
-This rebuilds, in order, `@getpaseo/highlight` → `@getpaseo/relay` → `@getpaseo/server` → `@getpaseo/cli`. Use it whenever you have changed any of those four and need clean cross-package types or runtime behavior.
+Use `npm run build:server` whenever you have changed any daemon/server-facing package and need clean cross-package types or runtime behavior.
 
 For tighter loops, you can rebuild a single workspace:
 
-- Changed `packages/relay/src/*`: `npm run build --workspace=@getpaseo/relay` (server imports `@getpaseo/relay` from `dist/*`).
-- Changed `packages/server/src/client/*` (especially `daemon-client.ts`) or shared WS protocol types: `npm run build --workspace=@getpaseo/server` (CLI imports `@getpaseo/server` via package exports resolving to `dist/*`).
-- Changed `packages/highlight/src/*`: `npm run build --workspace=@getpaseo/highlight` (server depends on it).
+- Changed `packages/protocol/src/*` or `packages/client/src/*`: `npm run build:client`.
+- Changed `packages/server/src/*`, `packages/cli/src/*`, `packages/relay/src/*`, or `packages/highlight/src/*`: `npm run build:server`.
+- Changed app build dependencies: `npm run build:app-deps`.
 
 ## CLI reference
 
@@ -171,6 +192,20 @@ Point Playwright MCP at the running Expo web target. Under `npm run dev` (macOS/
 
 Do NOT use browser history (back/forward). Always navigate by clicking UI elements or using `browser_navigate` with the full URL — the app uses client-side routing and browser history breaks state.
 
+## App web deploys
+
+`packages/app` exports a single-page Expo web app and deploys the `dist/`
+directory to Cloudflare Pages with `npm run deploy:web --workspace=@getpaseo/app`.
+
+PWA install metadata lives in `packages/app/public/manifest.json` and is linked
+from `packages/app/public/index.html`. Keep the install icons in `public/` so
+Cloudflare serves them from stable root URLs after `expo export`.
+
+Do not add service-worker caching casually. Paseo is a live control surface for
+agents, and an aggressive service worker can strand installed users on stale web
+code. If offline behavior becomes a product requirement, add it deliberately
+with an update strategy and test the installed-app upgrade path.
+
 ## Expo troubleshooting
 
 ```bash

docs/diagnostics/git-snapshot-startup-reshaping-2026-05-27.md

@@ -0,0 +1,211 @@
+# Git Snapshot Startup Reshaping - 2026-05-27
+
+## What changed
+
+The sidebar PR badge no longer has a special per-row fetch path. It is derived from the workspace snapshot, the same way the sidebar already gets branch/diff metadata.
+
+```text
+daemon startup / workspace subscription
+  -> WorkspaceGitService.refreshSnapshot(cwd)
+    -> getCheckoutSnapshotFacts(cwd)
+    -> getCheckoutStatus(cwd, { facts })
+    -> getCheckoutShortstat(cwd, { facts })
+    -> getPullRequestStatus(cwd, github, ..., { facts })
+    -> WorkspaceGitRuntimeSnapshot
+  -> session workspace descriptor githubRuntime.pullRequest
+  -> app useSidebarWorkspacesList()
+  -> SidebarWorkspaceEntry.prHint
+  -> Sidebar row badge + hover card checks
+```
+
+The remaining `checkout_pr_status_request` path is still present for explicit PR surfaces and compatibility, but the sidebar row badge no longer calls `useWorkspacePrHint()` and therefore no longer generates ad hoc checkout PR status requests per visible row.
+
+## Shared Git Facts
+
+`getCheckoutSnapshotFacts()` is now the first git read in the workspace snapshot builder. It gathers facts that were previously rediscovered by separate functions:
+
+- worktree root: `rev-parse --show-toplevel`
+- current branch: `rev-parse --abbrev-ref HEAD`
+- origin remote URL
+- Paseo worktree ownership and stored base ref
+- resolved base ref and best comparison base
+- main repo root
+- branch remote/merge config
+- tracked origin branch
+- pull request lookup target for fork/PR worktrees
+
+Those facts are then passed through `CheckoutContext` so status, shortstat, and PR status reuse the same answers instead of independently re-reading them.
+
+## Current Data Flow
+
+```text
+Workspace subscription / fetch_workspaces
+  -> session workspace registry
+  -> workspaceGitService.getSnapshot(cwd, includeGitHub)
+     -> refresh queue/throttle/dedupe per normalized cwd
+     -> refreshGitSnapshot()
+        -> getCheckoutSnapshotFacts()
+        -> getCheckoutStatus({ facts })
+        -> getCheckoutShortstat({ facts })
+     -> refreshGitHubSnapshot()
+        -> getPullRequestStatus({ facts })
+     -> cached WorkspaceGitRuntimeSnapshot
+  -> WorkspaceDescriptorPayload.gitRuntime
+  -> WorkspaceDescriptorPayload.githubRuntime
+  -> app session store
+  -> useSidebarWorkspacesList()
+     -> diffStat from descriptor
+     -> prHint from descriptor.githubRuntime.pullRequest
+```
+
+## Startup Benchmark
+
+Added deterministic real-home benchmark:
+
+`packages/server/scripts/benchmark-startup-git-real-home.ts`
+
+The script freezes the current Paseo home using the same metadata-copy shape as `scripts/dev-home.sh`: JSON under `agents`, JSON under `projects`, and `config.json`. It then starts an isolated in-process daemon against that frozen home, subscribes to workspaces/agents, records git invocations through `runGitCommand`, and reports elapsed time, git count, max concurrency, CPU, and memory deltas.
+
+The frozen home used for the comparison contained 22 workspaces.
+
+### Before/After
+
+| run         | code shape                 | client shape                              | git commands | failures | elapsed |
+| ----------- | -------------------------- | ----------------------------------------- | -----------: | -------: | ------: |
+| baseline    | before change              | legacy sidebar PR fanout                  |          529 |       20 | 39039ms |
+| split check | after change               | legacy sidebar PR fanout                  |          375 |       15 | 39039ms |
+| after       | after change               | snapshot-only sidebar, no PR badge fanout |          372 |       15 | 31273ms |
+| after 2     | after service fact sharing | snapshot-only sidebar, no PR badge fanout |          308 |       15 | 31334ms |
+
+The server-side fact reuse accounts for nearly all measured git command reduction: `529 -> 375` (`-154`, `-29.1%`) even when the old PR fanout is still forced. Removing the sidebar fanout removes the ad hoc request path, but in this run it only changed command count by `3` because the refreshed workspace snapshots already carried the PR data by the time the fanout ran.
+
+The second pass shares checkout facts between workspace observation setup and snapshot refresh. That removes another `64` git commands from the same frozen-home run: `372 -> 308` (`-17.2%` from the previous after, `-41.8%` from baseline).
+
+### Baseline: before change + legacy PR fanout
+
+```json
+{
+  "scenario": "legacyPrFanout",
+  "workspaceCount": 22,
+  "elapsedMs": 39039,
+  "git": {
+    "total": 529,
+    "failed": 20,
+    "maxConcurrent": 8,
+    "byCommand": [
+      { "key": "show-ref --verify --quiet refs/heads/main", "count": 66 },
+      { "key": "rev-parse --git-common-dir", "count": 58 },
+      { "key": "rev-parse --abbrev-ref HEAD", "count": 50 },
+      { "key": "rev-parse --git-dir", "count": 36 },
+      { "key": "show-ref --verify --quiet refs/remotes/origin/main", "count": 35 },
+      { "key": "symbolic-ref --quiet refs/remotes/origin/HEAD", "count": 35 },
+      { "key": "config --get remote.origin.url", "count": 32 },
+      { "key": "ls-files --others --exclude-standard", "count": 18 },
+      { "key": "rev-parse --absolute-git-dir", "count": 18 },
+      { "key": "merge-base HEAD origin/main", "count": 17 },
+      { "key": "rev-parse --show-toplevel", "count": 14 },
+      { "key": "status --porcelain", "count": 14 }
+    ]
+  },
+  "process": {
+    "cpuUserMs": 2009,
+    "cpuSystemMs": 2428,
+    "rssDeltaMb": -1.5,
+    "heapUsedDeltaMb": 16.9
+  }
+}
+```
+
+### After: after change + snapshot-only sidebar
+
+```json
+{
+  "scenario": "snapshotOnly",
+  "workspaceCount": 22,
+  "elapsedMs": 31273,
+  "git": {
+    "total": 372,
+    "failed": 15,
+    "maxConcurrent": 8,
+    "byCommand": [
+      { "key": "config --get remote.origin.url", "count": 35 },
+      { "key": "show-ref --verify --quiet refs/heads/main", "count": 34 },
+      { "key": "rev-parse --git-common-dir", "count": 31 },
+      { "key": "show-ref --verify --quiet refs/remotes/origin/main", "count": 22 },
+      { "key": "status --porcelain", "count": 22 },
+      { "key": "ls-files --others --exclude-standard", "count": 18 },
+      { "key": "rev-parse --absolute-git-dir", "count": 18 },
+      { "key": "merge-base HEAD origin/main", "count": 17 },
+      { "key": "rev-parse --abbrev-ref HEAD", "count": 17 },
+      { "key": "rev-parse --show-toplevel", "count": 17 },
+      { "key": "symbolic-ref --quiet refs/remotes/origin/HEAD", "count": 17 },
+      { "key": "rev-list --count main..origin/main", "count": 7 }
+    ]
+  },
+  "process": {
+    "cpuUserMs": 1871,
+    "cpuSystemMs": 2152,
+    "rssDeltaMb": 4.4,
+    "heapUsedDeltaMb": 8.8
+  }
+}
+```
+
+### After 2: shared service-level facts
+
+```json
+{
+  "scenario": "snapshotOnly",
+  "workspaceCount": 22,
+  "elapsedMs": 31334,
+  "git": {
+    "total": 308,
+    "failed": 15,
+    "maxConcurrent": 8,
+    "byCommand": [
+      { "key": "show-ref --verify --quiet refs/heads/main", "count": 31 },
+      { "key": "rev-parse --git-common-dir", "count": 26 },
+      { "key": "show-ref --verify --quiet refs/remotes/origin/main", "count": 22 },
+      { "key": "ls-files --others --exclude-standard", "count": 18 },
+      { "key": "status --porcelain", "count": 18 },
+      { "key": "merge-base HEAD origin/main", "count": 17 },
+      { "key": "config --get remote.origin.url", "count": 13 },
+      { "key": "rev-parse --abbrev-ref HEAD", "count": 13 },
+      { "key": "rev-parse --absolute-git-dir", "count": 13 },
+      { "key": "rev-parse --show-toplevel", "count": 13 },
+      { "key": "symbolic-ref --quiet refs/remotes/origin/HEAD", "count": 13 },
+      { "key": "fetch origin --prune", "count": 5 }
+    ]
+  },
+  "process": {
+    "cpuUserMs": 1817,
+    "cpuSystemMs": 1869,
+    "rssDeltaMb": 16.7,
+    "heapUsedDeltaMb": 10.4
+  }
+}
+```
+
+## Snapshot Equivalence Guard
+
+Added a focused utility test proving that status, shortstat, and PR status return the same data when run from shared snapshot facts. The same test records git calls and asserts the facts-backed path does not re-run:
+
+- `rev-parse --show-toplevel`
+- `rev-parse --abbrev-ref HEAD`
+
+Test:
+
+`packages/server/src/utils/checkout-git.test.ts` -> `reuses checkout snapshot facts across status, shortstat, and PR status reads`
+
+## Remaining Waste Visible In Baseline
+
+This pass reshaped the data flow and removed the sidebar PR badge special path. It did not try to optimize every command.
+
+The benchmark still shows repeated per-workspace reads that are candidates for the next pass:
+
+- base ref existence checks still repeat as `show-ref` probes.
+- default branch resolution still repeats `symbolic-ref refs/remotes/origin/HEAD`.
+- repo common-dir lookup is lower, but still above the apparent git workspace count.
+- shortstat still runs its own merge-base/diff/untracked scan per workspace.
+
+The important invariant now is clearer: sidebar-visible git data should flow from `WorkspaceGitService` snapshots, and snapshot builders should receive reusable git facts through `CheckoutContext`.

docs/diagnostics/opencode-provider-snapshot-timeout-2026-05-27.md

@@ -0,0 +1,389 @@
+# OpenCode Provider Snapshot Startup Timeout Diagnosis - 2026-05-27
+
+## Answer
+
+The startup timeout is real OpenCode provider snapshot work, not an agent resume path.
+
+In the dev-style copied-home reproduction, the OpenCode snapshot misses the 30s budget because several expensive things stack:
+
+1. Paseo starts from a copied `PASEO_HOME` containing 4,851 agent records.
+2. Clients ask for provider snapshots for three cwd scopes at almost the same time:
+   - `/Users/moboudra`
+   - `/Users/moboudra/dev/paseo`
+   - `/Users/moboudra/dev/blankpage/editor`
+3. Each OpenCode snapshot runs two OpenCode SDK calls:
+   - `GET /provider?directory=...` through `client.provider.list()`
+   - `GET /agent?directory=...` through `client.app.agents()`
+4. One cold `opencode serve` process is shared by the three cwd scopes. It took 8.562s to become ready.
+5. After OpenCode was listening, Paseo issued six OpenCode HTTP calls concurrently.
+6. The OpenCode `/provider` responses are large: about 3,549,620 decompressed bytes per cwd.
+7. During the same window, the daemon was still doing heavy startup workspace git work. In the exact 18:14:19-18:14:43 window, the daemon log has 292 git spawn/close events.
+8. The `/provider` calls eventually succeeded, but too late: they completed about 32.2s-32.5s after the snapshot fetch started, while the snapshot timeout is 30s.
+
+So the root cause is:
+
+```text
+Cold OpenCode server startup + three concurrent cwd snapshots + large OpenCode /provider responses + daemon startup git contention causes client.provider.list() to complete after Paseo's 30s snapshot budget.
+```
+
+More precise wording: the contention is machine-level process/CPU/filesystem contention created by daemon startup work, especially git work. It is not proven to be an OpenCode internal lock or a Paseo-only event-loop issue. A daemon-free repro with only OpenCode plus an external git storm slowed the same six OpenCode calls from about 1s to about 30s total.
+
+Manual settings refresh works because it runs after startup contention is gone and uses `force: true`, which creates fresh OpenCode runtime/server state. The same OpenCode provider refreshes then complete in about 1.7s-2.2s.
+
+The daemon does not auto-retry error snapshots. A failed provider snapshot is cached as `status: "error"` until an explicit refresh resets it to loading.
+
+## Follow-up: Normal Copied-Home Startup Check
+
+I later reran a normal dev-daemon startup against a fresh copy of the same Paseo home metadata and drove the app startup request path:
+
+```text
+fetchWorkspaces
+fetchAgents
+getProvidersSnapshot(home scope)
+getProvidersSnapshot(first workspace scope)
+```
+
+That run did not reproduce the 30s OpenCode timeout.
+
+```text
+home scope:
+  OpenCode ready at ~8s
+  availability: 1.6s
+  fetch total: 5.2s
+
+first workspace scope:
+  OpenCode ready at ~26s
+  availability: 2.0s
+  fetch total: 15.4s
+```
+
+The slowest OpenCode operation in that successful run was the workspace-scoped `/provider` response body read: `13.6s`. The daemon log had no `Timed out refreshing OpenCode` entry and no OpenCode provider snapshot failure.
+
+This means the timeout is reproducible under the heavier multi-scope startup contention captured below, but it is not guaranteed on every copied-home dev startup.
+
+## Reproduction Used
+
+The user's correction was right: the useful reproduction is not a random isolated home. It must match `dev.sh` worktree behavior.
+
+Relevant scripts:
+
+- `scripts/dev.sh`
+- `scripts/dev-daemon.sh`
+- `scripts/dev-home.sh`
+
+`dev-home.sh` only seeds this metadata into the dev home:
+
+```text
+agents/**/*.json
+projects/**/*.json
+config.json
+```
+
+It does not copy `chat`, `loops`, `schedules`, sockets, pid files, logs, or worktree contents.
+
+I ran a separate daemon, not the main daemon:
+
+```text
+PASEO_HOME=/var/folders/xl/kkk9drfd3ms_t8x7rmy4z6900000gn/T/paseo-devseed.Wms6pi
+PASEO_LISTEN=127.0.0.1:51116
+PASEO_LOG_LEVEL=trace
+```
+
+Startup facts:
+
+```text
+18:13:39.552 Agent storage initialized: 712ms
+18:13:39.559 Workspace registries bootstrapped: 719ms
+18:13:39.961 Agent registry loaded: 4851 records
+18:13:39.972 Server listening: http://127.0.0.1:51116
+```
+
+The probe then connected four client sessions and requested:
+
+- workspaces
+- active agents
+- provider snapshots for home, paseo, and blankpage/editor
+
+Client-visible result:
+
+```text
+18:14:30.263 /Users/moboudra/dev/blankpage/editor opencode error:
+  OpenCode app.agents timed out after 10s
+
+18:14:41.687 /Users/moboudra/dev/paseo opencode error:
+  Timed out refreshing OpenCode after 30000ms
+
+18:14:41.688 /Users/moboudra opencode error:
+  Timed out refreshing OpenCode after 30000ms
+```
+
+## Exact OpenCode Timeline
+
+OpenCode snapshot requests began at `18:14:10`.
+
+Availability checks:
+
+```text
+18:14:10.780 opencode availability start for /Users/moboudra
+18:14:10.787 opencode availability start for /Users/moboudra/dev/paseo
+18:14:10.800 opencode availability start for /Users/moboudra/dev/blankpage/editor
+
+18:14:11.363 paseo availability complete: 576ms
+18:14:11.376 home availability complete: 597ms
+18:14:11.391 blankpage availability complete: 591ms
+```
+
+OpenCode server acquisition:
+
+```text
+18:14:11.364 OpenCode server spawn start: opencode serve --port 56376
+18:14:19.926 OpenCode server listening after 8562ms
+```
+
+Six SDK calls were then issued:
+
+```text
+18:14:19.931 GET /provider directory=/Users/moboudra/dev/paseo
+18:14:19.931 GET /agent    directory=/Users/moboudra/dev/paseo
+18:14:19.931 GET /provider directory=/Users/moboudra
+18:14:19.931 GET /agent    directory=/Users/moboudra
+18:14:19.931 GET /provider directory=/Users/moboudra/dev/blankpage/editor
+18:14:19.936 GET /agent    directory=/Users/moboudra/dev/blankpage/editor
+```
+
+Why six:
+
+| Cwd                                    | Why that scope exists                                      | Model call                              | Mode call                         |
+| -------------------------------------- | ---------------------------------------------------------- | --------------------------------------- | --------------------------------- |
+| `/Users/moboudra`                      | home/settings provider snapshot                            | `client.provider.list()` -> `/provider` | `client.app.agents()` -> `/agent` |
+| `/Users/moboudra/dev/paseo`            | workspace-scoped provider snapshot for the Paseo workspace | `client.provider.list()` -> `/provider` | `client.app.agents()` -> `/agent` |
+| `/Users/moboudra/dev/blankpage/editor` | workspace/agent cwd snapshot for blankpage/editor          | `client.provider.list()` -> `/provider` | `client.app.agents()` -> `/agent` |
+
+Multiple clients can request the same snapshot scope during startup, but non-forced provider loads are deduped by `(cwd, provider)`. Different cwd scopes are separate loads. Three cwd scopes times two OpenCode SDK calls each is the six OpenCode calls in this repro.
+
+Headers arrived before the 30s timeout:
+
+| Call        | Cwd                             | Headers after request |
+| ----------- | ------------------------------- | --------------------- |
+| `/provider` | `/Users/moboudra`               | 6.462s                |
+| `/agent`    | `/Users/moboudra`               | 6.681s                |
+| `/agent`    | `/Users/moboudra/dev/paseo`     | 6.681s                |
+| `/provider` | `/Users/moboudra/dev/paseo`     | 8.192s                |
+| `/provider` | `/Users/moboudra/dev/blankpage` | 8.654s                |
+| `/agent`    | `/Users/moboudra/dev/blankpage` | 8.649s                |
+
+But body consumption and completion lagged:
+
+```text
+18:14:29.380 /agent home complete, total app.agents duration 9450ms
+18:14:29.813 /agent paseo complete, total app.agents duration 9883ms
+18:14:30.263 /agent blankpage timed out at 10s
+18:14:31.332 /agent blankpage body finally finished, after the 10s app.agents timeout
+
+18:14:41.687 paseo snapshot outer 30s timeout fires
+18:14:41.688 home snapshot outer 30s timeout fires
+
+18:14:43.593 /provider home completes, provider.list duration 23664ms, total listModels 32218ms
+18:14:43.798 /provider blankpage completes, provider.list duration 23868ms, total listModels 32411ms
+18:14:43.839 /provider paseo completes, provider.list duration 23911ms, total listModels 32476ms
+```
+
+The useful `/provider` results arrived about 1.9s-2.2s after the snapshot manager had already marked home and paseo as failed.
+
+## Why Settings Refresh Works
+
+After the daemon settled, I ran the same refresh path through the daemon on port `51116`, using `refreshProvidersSnapshot({ providers: ["opencode"] })`.
+
+Results:
+
+```text
+home refresh:
+  total: 2165ms
+  status: ready
+  models: 409
+  modes: 5
+
+/Users/moboudra/dev/paseo refresh:
+  total: 1675ms
+  status: ready
+  models: 409
+  modes: 5
+
+/Users/moboudra/dev/blankpage/editor refresh:
+  total: 1794ms
+  status: ready
+  models: 409
+  modes: 5
+```
+
+Trace details for the manual-style refresh:
+
+```text
+OpenCode server acquisition: 708ms-1291ms
+/agent completion: 433ms-592ms after request start
+/provider completion: 524ms-618ms after request start
+```
+
+That proves the startup failure is not bad credentials, not a permanently wedged OpenCode install, and not OpenCode generally taking more than 30s. It is startup timing and contention.
+
+## Minimal OpenCode-Only Repros
+
+### OpenCode Only, No Daemon, No Artificial Load
+
+I started a fresh `opencode serve`, waited for stdout `listening on`, then issued the same six HTTP calls concurrently:
+
+```text
+GET /provider?directory=/Users/moboudra
+GET /agent?directory=/Users/moboudra
+GET /provider?directory=/Users/moboudra/dev/paseo
+GET /agent?directory=/Users/moboudra/dev/paseo
+GET /provider?directory=/Users/moboudra/dev/blankpage/editor
+GET /agent?directory=/Users/moboudra/dev/blankpage/editor
+```
+
+Three runs:
+
+| Run | `opencode serve` ready | All six calls complete |
+| --- | ---------------------- | ---------------------- |
+| 1   | 1376ms                 | 1295ms                 |
+| 2   | 906ms                  | 1050ms                 |
+| 3   | 939ms                  | 898ms                  |
+
+Slowest individual call in those runs:
+
+```text
+/provider /Users/moboudra/dev/paseo: 1270ms total
+/agent /Users/moboudra/dev/blankpage/editor: 1251ms total
+```
+
+So six concurrent OpenCode calls alone are not the bug.
+
+### OpenCode Only Plus External Git Storm, No Daemon
+
+I then ran the same OpenCode-only six-call test while an external shell spawned repeated git commands across the same real workspaces/worktrees. This did not use the Paseo daemon.
+
+Result:
+
+```text
+opencode serve ready: 15479ms
+all six OpenCode calls complete: 15176ms after server ready
+combined cold-start + calls: about 30655ms
+```
+
+Individual calls under the external git storm:
+
+| Call        | Cwd                                    |   Total |
+| ----------- | -------------------------------------- | ------: |
+| `/provider` | `/Users/moboudra`                      | 10684ms |
+| `/agent`    | `/Users/moboudra`                      | 10767ms |
+| `/provider` | `/Users/moboudra/dev/paseo`            | 13220ms |
+| `/agent`    | `/Users/moboudra/dev/paseo`            | 13147ms |
+| `/provider` | `/Users/moboudra/dev/blankpage/editor` | 14675ms |
+| `/agent`    | `/Users/moboudra/dev/blankpage/editor` | 15038ms |
+
+This is the daemon-free minimal evidence that process/filesystem contention can push the same OpenCode cold-start + six-call workload to the same 30s boundary.
+
+## Why It Does Not Retry
+
+`ProviderSnapshotManager.getSnapshot()` only starts background warmup for:
+
+- no existing snapshot
+- missing providers
+- entries still in `loading` with no active load
+
+When refresh fails, `refreshProvider()` stores:
+
+```text
+status: "error"
+error: "Timed out refreshing OpenCode after 30000ms"
+```
+
+An `error` entry is not treated as stale/loading by `getSnapshot()`, so normal reads keep returning the cached error.
+
+Settings refresh calls `refresh_providers_snapshot_request`, which routes to:
+
+```text
+refreshSettingsSnapshot()
+clearCachedProviders()
+resetSnapshotToLoading()
+refreshProviders(... force: true)
+```
+
+That is why you have to force a manual refresh.
+
+## Git Work During The Repro
+
+This is not the final optimization report, but it matters for the timeout because it overlaps exactly with OpenCode response handling.
+
+Total git commands in the dev-style copied-home daemon log:
+
+```text
+632 spawned
+632 closed
+```
+
+Top cwd counts:
+
+| Count | Cwd                                                                                   |
+| ----: | ------------------------------------------------------------------------------------- |
+|    44 | `/Users/moboudra/.paseo/worktrees/1luy0po7/merry-ladybug`                             |
+|    44 | `/Users/moboudra/.paseo/worktrees/1luy0po7/hopeful-eel`                               |
+|    44 | `/Users/moboudra/.paseo/worktrees/1luy0po7/fix-compaction-cancel-loading`             |
+|    44 | `/Users/moboudra/.paseo/worktrees/1luy0po7/fix-archive-worktree-session-history`      |
+|    44 | `/Users/moboudra/.paseo/worktrees/0vpo9h4b/breezy-toad`                               |
+|    36 | `/Users/moboudra/.paseo/worktrees/steering-policy-refactor-detached`                  |
+|    36 | `/Users/moboudra/.paseo/worktrees/1luy0po7/integration-session-mcp-command-stack`     |
+|    36 | `/Users/moboudra/.paseo/worktrees/1luy0po7/fix-provider-diagnostic-binary-resolution` |
+|    36 | `/Users/moboudra/.paseo/worktrees/1luy0po7/feat-voice-runtime-on-demand`              |
+|    36 | `/Users/moboudra/.paseo/worktrees/1luy0po7/feat-find-in-pane`                         |
+|    36 | `/Users/moboudra/.paseo/worktrees/1luy0po7/epic-paseo-client-sdk`                     |
+|    24 | `/Users/moboudra/dev/paseo`                                                           |
+|    24 | `/Users/moboudra/dev/blankpage/editor`                                                |
+|    24 | `/Users/moboudra/dev/faro/main`                                                       |
+|    24 | `/Users/moboudra/dev/konbert/web`                                                     |
+|    24 | `/Users/moboudra/dev/paseo-cloud`                                                     |
+
+In the exact OpenCode pressure window, `18:14:19` through `18:14:43`, there were:
+
+```text
+142 git command spawns
+150 git command closes
+```
+
+The main repeated command shapes were:
+
+```text
+76  git rev-parse --show-toplevel
+72  git status --porcelain
+72  git show-ref --verify --quiet refs/remotes/origin/main
+72  git show-ref --verify --quiet refs/heads/main
+16  git config --get branch.main.remote
+16  git config --get branch.main.merge
+16  git rev-list --count main..origin/main
+16  git rev-list --count origin/main..main
+```
+
+## Original `log.txt` Alignment
+
+The original startup showed the same home and paseo outer timeout shape:
+
+```text
+16:04:22.466 /Users/moboudra/dev/paseo:
+  Timed out refreshing OpenCode after 30000ms
+
+16:04:22.482 /Users/moboudra:
+  Timed out refreshing OpenCode after 30000ms
+```
+
+The original logs did not include SDK fetch/header/body timing, so they could only show the wrapper-level timeout. The dev-style copied-home reproduction with instrumentation now shows the missing link: the `/provider` calls completed just after the 30s snapshot budget.
+
+## Files Instrumented For Diagnosis
+
+Temporary trace instrumentation was added to:
+
+- `packages/server/src/server/agent/provider-snapshot-manager.ts`
+- `packages/server/src/server/agent/providers/opencode-agent.ts`
+- `packages/server/src/server/agent/providers/opencode/runtime.ts`
+- `packages/server/src/server/agent/providers/opencode/server-manager.ts`
+
+The instrumentation is behavior-neutral and only emits trace logs.

docs/diagnostics/startup-sequence-analysis-2026-05-27.md

@@ -0,0 +1,381 @@
+# Daemon Startup Sequence Analysis - 2026-05-27
+
+Source log: `log.txt` at repository root.
+
+Scope: current sliced startup log, starting at daemon worker startup and ending after workspace registry reconciliation and the first OpenCode heartbeat.
+
+This report is descriptive only. It does not propose optimizations.
+
+## Executive Summary
+
+The daemon becomes ready quickly, then does a heavy post-listen startup pass driven by reconnecting clients and workspace/app hydration.
+
+- Worker start: `16:03:46.678`, line 1.
+- Server listening: `16:03:48.285`, line 47, elapsed `602ms`.
+- First client hello: `16:03:50.285`, line 66.
+- Workspace registries reconciled: `16:04:33.666`, line 1777, elapsed `45983ms`.
+
+The startup shape is therefore:
+
+- Daemon listen readiness: about `0.6s`.
+- Client reconnect plus workspace/app/provider hydration: about `45s`.
+- No git commands after workspace registry reconciliation in this slice.
+
+## Method
+
+I parsed structured trace lines from `log.txt`, especially:
+
+- `Git command closed`
+- `agent.session.inbound`
+- `agent.session.outbound`
+- `ws_slow_request`
+- provider snapshot warnings
+- provider resume events
+
+Important limitation: git command logs do not carry a websocket request id, so per-request attribution is inferred from timing and server code paths. Per-workspace git counts, command shapes, durations, and failures are exact for this log.
+
+Relevant code paths checked:
+
+- `packages/server/src/server/session.ts`
+  - `fetch_workspaces_request` calls `syncWorkspaceGitObservers(payload.entries)`.
+  - `checkout_status_request` calls `workspaceGitService.getSnapshot(resolvedCwd)`.
+  - `checkout_pr_status_request` calls `workspaceGitService.getSnapshot(cwd)`.
+- `packages/server/src/server/workspace-git-service.ts`
+  - checkout snapshot/root resolution uses `git rev-parse --show-toplevel`.
+  - snapshot refresh collects dirty state, upstream/ahead/behind, ref existence, and base divergence.
+- `packages/app/src/contexts/session-context.tsx`
+  - initial workspace hydration calls `client.fetchWorkspaces({ sort: activity_at desc, subscribe, page limit 200 })`.
+- `packages/app/src/hooks/use-sidebar-workspaces-list.ts`
+  - sidebar workspace refresh also calls `client.fetchWorkspaces({ sort: activity_at desc, page limit 200 })`.
+
+## Startup Timeline
+
+| time           | line | event                                                              |
+| -------------- | ---: | ------------------------------------------------------------------ |
+| `16:03:46.678` |    1 | `DaemonRunner` starts daemon worker                                |
+| `16:03:47.683` |    4 | worker spawned                                                     |
+| `16:03:47.684` |    6 | daemon keypair loaded                                              |
+| `16:03:48.281` |   44 | bootstrap complete, ready to listen                                |
+| `16:03:48.285` |   47 | server listening on `0.0.0.0:6767`                                 |
+| `16:03:50.274` |   60 | first websocket awaiting hello                                     |
+| `16:03:50.285` |   66 | first client connected via hello                                   |
+| `16:04:22.466` |  987 | OpenCode provider snapshot timeout for `/Users/moboudra/dev/paseo` |
+| `16:04:22.482` | 1002 | OpenCode provider snapshot timeout for `/Users/moboudra`           |
+| `16:04:24.183` | 1201 | OpenCode provider subscribe starts                                 |
+| `16:04:24.183` | 1202 | OpenCode provider subscribe ready                                  |
+| `16:04:24.306` | 1214 | OpenCode server connected event                                    |
+| `16:04:25.933` | 1321 | OpenCode agent resumed from persistence                            |
+| `16:04:33.666` | 1777 | workspace registries reconciled                                    |
+| `16:04:34.197` | 1783 | OpenCode heartbeat                                                 |
+| `16:04:44.200` | 1789 | OpenCode heartbeat                                                 |
+
+## Git Command Totals
+
+Total git commands in the sliced startup: `444`.
+
+| phase                           | commands | failures | summed process time |
+| ------------------------------- | -------: | -------: | ------------------: |
+| daemon bootstrap before listen  |       13 |        4 |               445ms |
+| post-listen before first client |        1 |        0 |              2020ms |
+| client reconnect + reconcile    |      430 |       71 |            120813ms |
+| after reconcile                 |        0 |        0 |                 0ms |
+| total                           |      444 |       75 |            123278ms |
+
+Summed process time is not wall-clock time. Many commands overlap.
+
+## Git Command Categories
+
+| category                                             | commands | failures | summed process time | max duration |
+| ---------------------------------------------------- | -------: | -------: | ------------------: | -----------: |
+| ahead/behind: `rev-list --count ...`                 |      115 |       30 |             35815ms |       1557ms |
+| refs: `show-ref --verify --quiet ...`                |       86 |        2 |             14680ms |       1303ms |
+| upstream config: `config --get branch.*`             |       85 |       13 |             26437ms |       1624ms |
+| root detection: `rev-parse --show-toplevel`          |       80 |       30 |             24164ms |       1426ms |
+| dirty status: `status --porcelain`                   |       50 |        0 |             12670ms |       2020ms |
+| base divergence: `rev-list --left-right --count ...` |       28 |        0 |              9512ms |       1085ms |
+
+What those categories mean in the app:
+
+- Root detection: determine whether a cwd is inside a git repo and find its checkout root.
+- Dirty status: show dirty/clean workspace state.
+- Upstream config and ahead/behind: show branch tracking and sync state.
+- Ref existence and base divergence: compare checkout branch against candidate base refs for checkout/PR status.
+
+## Per-Workspace Git Work
+
+Columns:
+
+- `phase`: `pre/warm/reconnect/after`
+- `cats`: `root/dirty/upstream/ahead/refs/base/other`
+- `total_ms`: summed process time for that workspace
+
+| workspace                                                               | cmds | fail | phase      | cats              | total_ms | max_ms | window                      | failing command shapes                                                                                                                                                                                                                                                                        |
+| ----------------------------------------------------------------------- | ---: | ---: | ---------- | ----------------- | -------: | -----: | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `~/.paseo/worktrees/1luy0po7/fix-compaction-cancel-loading`             |   33 |    9 | `0/0/33/0` | `3/3/3/9/12/3/0`  |     8255 |   1460 | `16:03:52.908-16:04:24.019` | `3x config --get branch.fix-compaction-cancel-loading.remote`; `3x rev-list --count fix-compaction-cancel-loading..origin/fix-compaction-cancel-loading`; `3x rev-list --count origin/fix-compaction-cancel-loading..fix-compaction-cancel-loading`                                           |
+| `~/.paseo/worktrees/1luy0po7/hopeful-eel`                               |   33 |    9 | `0/0/33/0` | `3/3/3/9/12/3/0`  |     8468 |   1544 | `16:03:53.245-16:04:27.334` | `3x config --get branch.feat/markdown-annotations.remote`; `3x rev-list --count feat/markdown-annotations..origin/feat/markdown-annotations`; `3x rev-list --count origin/feat/markdown-annotations..feat/markdown-annotations`                                                               |
+| `~/.paseo/worktrees/1luy0po7/merry-ladybug`                             |   33 |    9 | `0/0/33/0` | `3/3/3/9/12/3/0`  |     7154 |   1099 | `16:03:53.696-16:04:29.644` | `3x config --get branch.feat/mcp-configuration.remote`; `3x rev-list --count feat/mcp-configuration..origin/feat/mcp-configuration`; `3x rev-list --count origin/feat/mcp-configuration..feat/mcp-configuration`                                                                              |
+| `~/dev/paseo`                                                           |   30 |    0 | `2/0/28/0` | `5/5/10/10/0/0/0` |     7457 |   1624 | `16:03:48.171-16:04:27.284` |                                                                                                                                                                                                                                                                                               |
+| `~/.paseo/worktrees/0vpo9h4b/dazzling-duck`                             |   27 |    0 | `0/0/27/0` | `3/3/6/6/6/3/0`   |     7617 |   1269 | `16:03:51.918-16:04:23.971` |                                                                                                                                                                                                                                                                                               |
+| `~/.paseo/worktrees/1luy0po7/epic-paseo-client-sdk`                     |   27 |    0 | `0/0/27/0` | `3/3/6/6/6/3/0`   |     7428 |   1426 | `16:03:52.445-16:04:23.991` |                                                                                                                                                                                                                                                                                               |
+| `~/.paseo/worktrees/1luy0po7/fix-provider-diagnostic-binary-resolution` |   27 |    0 | `0/0/27/0` | `3/3/6/6/6/3/0`   |     7764 |   1091 | `16:03:52.681-16:04:23.971` |                                                                                                                                                                                                                                                                                               |
+| `~/dev/emdash`                                                          |   22 |    6 | `0/0/22/0` | `2/2/2/6/8/2/0`   |     3031 |    453 | `16:04:27.351-16:04:29.583` | `2x config --get branch.heads/main.remote`; `2x rev-list --count heads/main..origin/heads/main`; `2x rev-list --count origin/heads/main..heads/main`                                                                                                                                          |
+| `~/dev/opencode`                                                        |   22 |    4 | `0/0/22/0` | `2/2/2/6/8/2/0`   |     2279 |    313 | `16:04:24.058-16:04:24.970` | `2x rev-list --count ecosystem-paseo..origin/ecosystem-paseo`; `2x rev-list --count origin/ecosystem-paseo..ecosystem-paseo`                                                                                                                                                                  |
+| `~/.paseo/worktrees/1luy0po7/integration-session-mcp-command-stack`     |   18 |    0 | `0/0/18/0` | `3/3/6/6/0/0/0`   |     7467 |   1242 | `16:03:53.781-16:04:23.971` |                                                                                                                                                                                                                                                                                               |
+| `~/dev/blankpage/editor`                                                |   18 |    0 | `2/0/16/0` | `3/3/6/6/0/0/0`   |     2418 |    520 | `16:03:48.174-16:04:26.411` |                                                                                                                                                                                                                                                                                               |
+| `~/dev/konbert/web`                                                     |   18 |    0 | `1/1/16/0` | `3/3/6/6/0/0/0`   |     7324 |   2020 | `16:03:48.190-16:04:23.685` |                                                                                                                                                                                                                                                                                               |
+| `~/dev/openchamber`                                                     |   12 |    0 | `0/0/12/0` | `2/2/4/4/0/0/0`   |     1554 |    336 | `16:04:27.399-16:04:29.616` |                                                                                                                                                                                                                                                                                               |
+| `~/dev/superset`                                                        |   12 |    0 | `0/0/12/0` | `2/2/4/4/0/0/0`   |     1019 |    215 | `16:04:27.341-16:04:29.617` |                                                                                                                                                                                                                                                                                               |
+| `~/dev/t3code`                                                          |   12 |    0 | `0/0/12/0` | `2/2/4/4/0/0/0`   |     2761 |    588 | `16:04:27.356-16:04:29.603` |                                                                                                                                                                                                                                                                                               |
+| `~/.paseo/worktrees/0vpo9h4b/breezy-toad`                               |   11 |    5 | `0/0/11/0` | `1/1/1/3/4/1/0`   |     6465 |   1290 | `16:03:51.307-16:04:18.112` | `1x config --get branch.fix/user-delete-dark-mode.remote`; `1x rev-list --count fix/user-delete-dark-mode..origin/fix/user-delete-dark-mode`; `1x rev-list --count origin/fix/user-delete-dark-mode..fix/user-delete-dark-mode`; `2x show-ref --verify --quiet refs/remotes/origin/my-branch` |
+| `~/.paseo/worktrees/1luy0po7/fix-archive-worktree-session-history`      |   11 |    3 | `0/0/11/0` | `1/1/1/3/4/1/0`   |     4303 |    757 | `16:03:52.539-16:04:19.011` | `1x config --get branch.fix-archive-worktree-session-history.remote`; `1x rev-list --count fix-archive-worktree-session-history..origin/fix-archive-worktree-session-history`; `1x rev-list --count origin/fix-archive-worktree-session-history..fix-archive-worktree-session-history`        |
+| `~/.paseo/worktrees/0vpo9h4b/codex-github-mention-implement-db-garbage` |    9 |    0 | `0/0/9/0`  | `1/1/2/2/2/1/0`   |     4986 |   1005 | `16:03:51.261-16:04:16.878` |                                                                                                                                                                                                                                                                                               |
+| `~/.paseo/worktrees/1luy0po7/feat-find-in-pane`                         |    9 |    0 | `0/0/9/0`  | `1/1/2/2/2/1/0`   |     5273 |   1130 | `16:03:52.391-16:04:17.682` |                                                                                                                                                                                                                                                                                               |
+| `~/.paseo/worktrees/1luy0po7/feat-voice-runtime-on-demand`              |    9 |    0 | `0/0/9/0`  | `1/1/2/2/2/1/0`   |     5176 |    839 | `16:03:52.110-16:04:18.254` |                                                                                                                                                                                                                                                                                               |
+| `~/.paseo/worktrees/steering-policy-refactor-detached`                  |    9 |    0 | `0/0/9/0`  | `1/1/2/2/2/1/0`   |     5993 |   1243 | `16:03:53.984-16:04:17.673` |                                                                                                                                                                                                                                                                                               |
+| `~/dev/faro/main`                                                       |    6 |    0 | `2/0/4/0`  | `1/1/2/2/0/0/0`   |     4964 |   1603 | `16:03:48.168-16:04:03.748` |                                                                                                                                                                                                                                                                                               |
+| `~/dev/paseo-cloud`                                                     |    6 |    0 | `2/0/4/0`  | `1/1/2/2/0/0/0`   |     2123 |   1154 | `16:03:48.159-16:03:56.377` |                                                                                                                                                                                                                                                                                               |
+| `~/dev/assistant`                                                       |    3 |    3 | `1/0/2/0`  | `3/0/0/0/0/0/0`   |       85 |     29 | `16:03:48.165-16:04:24.048` | `3x rev-parse --show-toplevel`                                                                                                                                                                                                                                                                |
+| `~/dev/benchmark/dashboard-2026-05-25/review`                           |    3 |    3 | `1/0/2/0`  | `3/0/0/0/0/0/0`   |      224 |    105 | `16:03:48.197-16:04:26.560` | `3x rev-parse --show-toplevel`                                                                                                                                                                                                                                                                |
+| `~/dev/research/orchestrator-worker`                                    |    3 |    3 | `1/0/2/0`  | `3/0/0/0/0/0/0`   |      285 |    144 | `16:03:48.194-16:04:26.575` | `3x rev-parse --show-toplevel`                                                                                                                                                                                                                                                                |
+| `/tmp`                                                                  |    2 |    2 | `0/0/2/0`  | `2/0/0/0/0/0/0`   |      113 |     77 | `16:04:27.388-16:04:27.471` | `2x rev-parse --show-toplevel`                                                                                                                                                                                                                                                                |
+| `~/dev`                                                                 |    2 |    2 | `0/0/2/0`  | `2/0/0/0/0/0/0`   |       86 |     58 | `16:04:27.384-16:04:27.457` | `2x rev-parse --show-toplevel`                                                                                                                                                                                                                                                                |
+| `~/dev/benchmark/dashboard-2026-05-25/01-claude-opus`                   |    2 |    2 | `0/0/2/0`  | `2/0/0/0/0/0/0`   |      216 |    185 | `16:04:26.525-16:04:26.543` | `2x rev-parse --show-toplevel`                                                                                                                                                                                                                                                                |
+| `~/dev/benchmark/dashboard-2026-05-25/02-codex-gpt55`                   |    2 |    2 | `0/0/2/0`  | `2/0/0/0/0/0/0`   |       98 |     68 | `16:04:26.353-16:04:26.554` | `2x rev-parse --show-toplevel`                                                                                                                                                                                                                                                                |
+| `~/dev/benchmark/dashboard-2026-05-25/03-opencode-zai-glm51`            |    2 |    2 | `0/0/2/0`  | `2/0/0/0/0/0/0`   |      209 |    158 | `16:04:26.512-16:04:26.576` | `2x rev-parse --show-toplevel`                                                                                                                                                                                                                                                                |
+| `~/dev/benchmark/dashboard-2026-05-25/04-opencode-zen-minimax27`        |    2 |    2 | `0/0/2/0`  | `2/0/0/0/0/0/0`   |      148 |    101 | `16:04:26.431-16:04:26.549` | `2x rev-parse --show-toplevel`                                                                                                                                                                                                                                                                |
+| `~/dev/benchmark/dashboard-2026-05-25/05-opencode-zen-kimi26`           |    2 |    2 | `0/0/2/0`  | `2/0/0/0/0/0/0`   |      231 |    172 | `16:04:26.517-16:04:26.577` | `2x rev-parse --show-toplevel`                                                                                                                                                                                                                                                                |
+| `~/dev/benchmark/dashboard-2026-05-25/06-opencode-or-deepseek4pro`      |    2 |    2 | `0/0/2/0`  | `2/0/0/0/0/0/0`   |       93 |     73 | `16:04:27.365-16:04:27.380` | `2x rev-parse --show-toplevel`                                                                                                                                                                                                                                                                |
+| `~/dev/benchmark/dashboard-2026-05-25/07-opencode-zen-gemini35flash`    |    2 |    2 | `0/0/2/0`  | `2/0/0/0/0/0/0`   |       78 |     66 | `16:04:27.363-16:04:27.375` | `2x rev-parse --show-toplevel`                                                                                                                                                                                                                                                                |
+| `~/dev/benchmark/dashboard-2026-05-25/08-opencode-zen-gpt55`            |    2 |    2 | `0/0/2/0`  | `2/0/0/0/0/0/0`   |      120 |     65 | `16:04:27.359-16:04:27.430` | `2x rev-parse --show-toplevel`                                                                                                                                                                                                                                                                |
+| `~/dev/assistant/game`                                                  |    1 |    1 | `1/0/0/0`  | `1/0/0/0/0/0/0`   |       13 |     13 | `16:03:48.155-16:03:48.155` | `1x rev-parse --show-toplevel`                                                                                                                                                                                                                                                                |
+
+## Git Failure Shape
+
+There were 75 nonzero git exits.
+
+Most failures were not timeouts. They were expected probe failures:
+
+- Non-repo checks: `rev-parse --show-toplevel` fails for paths that are not git repositories.
+- Missing upstream config: `config --get branch.<branch>.remote` fails for branches without configured upstream.
+- Missing remote branch graph: `rev-list --count <branch>..origin/<branch>` fails when the remote branch/ref does not exist.
+- Missing ref checks: `show-ref --verify --quiet refs/remotes/origin/my-branch` fails when a candidate ref does not exist.
+
+The `~/dev/opencode` git failures are branch graph probes for `ecosystem-paseo` versus `origin/ecosystem-paseo`, not OpenCode provider startup failures.
+
+## Inbound Client Work
+
+Inbound session messages during the startup window:
+
+| request                           | count |
+| --------------------------------- | ----: |
+| `client_heartbeat`                |    19 |
+| `checkout_pr_status_request`      |    18 |
+| `fetch_agents_request`            |    11 |
+| `fetch_workspaces_request`        |     9 |
+| `get_providers_snapshot_request`  |     9 |
+| `project_icon_request`            |     9 |
+| `fetch_agent_timeline_request`    |     7 |
+| `clear_agent_attention`           |     6 |
+| `list_terminals_request`          |     5 |
+| `subscribe_terminals_request`     |     5 |
+| `list_available_editors_request`  |     2 |
+| `subscribe_checkout_diff_request` |     2 |
+| `checkout_status_request`         |     1 |
+| `fetch_agent_request`             |     1 |
+| `file_explorer_request`           |     1 |
+| `read_project_config_request`     |     1 |
+| `workspace_setup_status_request`  |     1 |
+
+Inbound by client:
+
+| client                                                      | count | top work                                                                                                                                                                                                           |
+| ----------------------------------------------------------- | ----: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Electron `cid_d555...`, origin `http://localhost:8082`      |    68 | `checkout_pr_status_request:18`, `project_icon_request:9`, `clear_agent_attention:6`, `fetch_agent_timeline_request:4`, `fetch_workspaces_request:3`, `fetch_agents_request:3`, `get_providers_snapshot_request:3` |
+| HeadlessChrome `cid_d39...`, origin `http://localhost:8081` |    13 | `client_heartbeat:4`, `fetch_workspaces_request:2`, `fetch_agents_request:2`, `get_providers_snapshot_request:2`                                                                                                   |
+| local web `cid_a2b...`, origin `http://localhost:6767`      |    13 | `client_heartbeat:4`, `fetch_workspaces_request:2`, `fetch_agents_request:2`, `get_providers_snapshot_request:2`                                                                                                   |
+| Android `cid_24c...`, origin `http://10.0.2.2:6767`         |    11 | `client_heartbeat:2`, `fetch_workspaces_request:2`, `fetch_agents_request:2`, `get_providers_snapshot_request:2`                                                                                                   |
+| `cid_70d...`, host `0.0.0.0:6767`                           |     2 | `fetch_agents_request:2`                                                                                                                                                                                           |
+
+## Outbound Client Work
+
+Outbound session messages during the startup window:
+
+| message                            | count |
+| ---------------------------------- | ----: |
+| `providers_snapshot_update`        |   129 |
+| `workspace_update`                 |    81 |
+| `checkout_status_update`           |    76 |
+| `agent_update`                     |    47 |
+| `checkout_pr_status_response`      |    18 |
+| `fetch_agents_response`            |    11 |
+| `fetch_workspaces_response`        |     9 |
+| `get_providers_snapshot_response`  |     9 |
+| `project_icon_response`            |     9 |
+| `fetch_agent_timeline_response`    |     7 |
+| `list_terminals_response`          |     5 |
+| `terminals_changed`                |     5 |
+| `list_available_editors_response`  |     2 |
+| `subscribe_checkout_diff_response` |     2 |
+| `checkout_status_response`         |     1 |
+| `fetch_agent_response`             |     1 |
+| `file_explorer_response`           |     1 |
+| `read_project_config_response`     |     1 |
+| `workspace_setup_status_response`  |     1 |
+
+Provider snapshot updates were large and repeated:
+
+- Around lines 982-986: five `providers_snapshot_update` messages, each `215932` bytes.
+- Around lines 997-1001: five `providers_snapshot_update` messages, each `215898` bytes.
+- Around lines 1250-1254: five `providers_snapshot_update` messages, each `414735` bytes.
+
+## Slow Requests
+
+Slow requests logged during startup:
+
+| time           |                           request | duration | client                | line |
+| -------------- | --------------------------------: | -------: | --------------------- | ---: |
+| `16:04:29.702` |    `fetch_agent_timeline_request` |  39372ms | HeadlessChrome        | 1767 |
+| `16:04:29.702` |    `fetch_agent_timeline_request` |  39212ms | Electron              | 1768 |
+| `16:04:29.702` |    `fetch_agent_timeline_request` |  38914ms | local web             | 1769 |
+| `16:04:33.665` |      `checkout_pr_status_request` |  20181ms | Electron              | 1776 |
+| `16:04:08.109` | `subscribe_checkout_diff_request` |  17618ms | Electron              |  565 |
+| `16:04:29.702` |    `fetch_agent_timeline_request` |  16216ms | Electron              | 1770 |
+| `16:04:06.624` |    `fetch_agent_timeline_request` |  16134ms | Electron              |  524 |
+| `16:04:29.396` |      `checkout_pr_status_request` |  15911ms | Electron              | 1671 |
+| `16:04:29.256` |      `checkout_pr_status_request` |  15772ms | Electron              | 1651 |
+| `16:04:29.149` |      `checkout_pr_status_request` |  15665ms | Electron              | 1638 |
+| `16:04:29.054` |      `checkout_pr_status_request` |  15569ms | Electron              | 1628 |
+| `16:04:28.932` |      `checkout_pr_status_request` |  15448ms | Electron              | 1611 |
+| `16:04:28.809` |      `checkout_pr_status_request` |  15324ms | Electron              | 1601 |
+| `16:04:28.672` |      `checkout_pr_status_request` |  15188ms | Electron              | 1582 |
+| `16:04:28.555` |      `checkout_pr_status_request` |  15071ms | Electron              | 1567 |
+| `16:04:28.421` |      `checkout_pr_status_request` |  14936ms | Electron              | 1556 |
+| `16:04:28.323` |      `checkout_pr_status_request` |  14839ms | Electron              | 1549 |
+| `16:04:28.324` |         `checkout_status_request` |  14839ms | Electron              | 1550 |
+| `16:04:28.189` |      `checkout_pr_status_request` |  14705ms | Electron              | 1536 |
+| `16:04:29.634` |            `fetch_agents_request` |  14590ms | `0.0.0.0:6767` client | 1759 |
+| `16:04:28.006` |      `checkout_pr_status_request` |  14522ms | Electron              | 1526 |
+| `16:04:27.628` |      `checkout_pr_status_request` |  14143ms | Electron              | 1496 |
+| `16:04:27.061` |      `checkout_pr_status_request` |  13576ms | Electron              | 1405 |
+| `16:04:29.645` |            `fetch_agents_request` |  13384ms | `0.0.0.0:6767` client | 1762 |
+| `16:04:02.812` |    `fetch_agent_timeline_request` |  12321ms | Electron              |  440 |
+| `16:04:25.740` |      `checkout_pr_status_request` |  12256ms | Electron              | 1309 |
+| `16:04:25.352` |      `checkout_pr_status_request` |  11867ms | Electron              | 1296 |
+| `16:04:04.217` |    `fetch_agent_timeline_request` |  11751ms | Android               |  462 |
+| `16:04:25.155` |      `checkout_pr_status_request` |  11671ms | Electron              | 1284 |
+| `16:04:23.196` |             `fetch_agent_request` |   9711ms | Electron              | 1070 |
+| `16:04:17.563` |            `project_icon_request` |   4079ms | Electron              |  877 |
+| `16:03:53.022` |  `list_available_editors_request` |   2533ms | Electron              |  254 |
+| `16:04:15.703` |            `project_icon_request` |   2218ms | Electron              |  824 |
+| `16:04:15.696` |            `project_icon_request` |   2211ms | Electron              |  822 |
+| `16:04:15.694` |            `project_icon_request` |   2209ms | Electron              |  820 |
+| `16:04:15.103` |           `file_explorer_request` |   1618ms | Electron              |  806 |
+| `16:04:14.107` |          `list_terminals_request` |    621ms | Electron              |  764 |
+| `16:03:50.945` |          `list_terminals_request` |    614ms | HeadlessChrome        |  156 |
+
+The checkout PR requests are especially clustered: 18 Electron `checkout_pr_status_request` messages arrive together at `16:04:13.484`, lines 699-716. Their slow-request completions drain over the next ~20s, with `inflightRequests` dropping from 20 to 0.
+
+## Provider Findings
+
+### OpenCode
+
+OpenCode provider snapshot refresh had two timeouts:
+
+| time           | line | cwd                         | error                                         |
+| -------------- | ---: | --------------------------- | --------------------------------------------- |
+| `16:04:22.466` |  987 | `/Users/moboudra/dev/paseo` | `Timed out refreshing OpenCode after 30000ms` |
+| `16:04:22.482` | 1002 | `/Users/moboudra`           | `Timed out refreshing OpenCode after 30000ms` |
+
+These are provider snapshot failures, not OpenCode agent resume failures.
+
+The persisted OpenCode agent did resume:
+
+| time           | line | event                                                 |
+| -------------- | ---: | ----------------------------------------------------- |
+| `16:04:24.183` | 1201 | `provider.opencode.subscribe.start`                   |
+| `16:04:24.183` | 1202 | `provider.opencode.subscribe.ready`                   |
+| `16:04:24.306` | 1214 | raw event `server.connected`                          |
+| `16:04:25.933` | 1321 | `Agent resumed from persistence`, provider `opencode` |
+| `16:04:34.197` | 1783 | raw event `server.heartbeat`                          |
+| `16:04:44.200` | 1789 | raw event `server.heartbeat`                          |
+
+There are no `provider.opencode.subscribe.error` or OpenCode agent fatal errors in this slice.
+
+OpenCode-related git:
+
+- `~/dev/opencode` had 22 git commands.
+- Four failed.
+- The failed commands were branch graph probes for `ecosystem-paseo` versus `origin/ecosystem-paseo`.
+- Those failures are git state/probe failures, not OpenCode provider process failures.
+
+### Codex
+
+Codex provider startup observations:
+
+- `provider.codex.spawn` appears multiple times for provider snapshot/config discovery.
+- A persisted Codex agent resumes successfully at `16:04:06.357`, line 518.
+- Debug logs show failed reads of Codex saved config defaults, but these are debug-level and do not become provider startup warnings/errors in this slice.
+- There are unhandled Codex trace event types such as remote-control/status and thread/goal status, but no Codex timeout or fatal provider startup failure in this slice.
+
+### Claude
+
+Claude agents resume successfully:
+
+| time           | line | client   | agent                                  |
+| -------------- | ---: | -------- | -------------------------------------- |
+| `16:04:02.540` |  434 | Electron | `f884552a-1383-4dba-8583-7ae0b6a62353` |
+| `16:04:03.772` |  456 | Android  | `0c89a057-05f2-4e23-9895-84c8e1952310` |
+
+## What Work The App Asked For
+
+The startup work visible in the app/server protocol is:
+
+- Workspace list/sidebar hydration:
+  - `fetch_workspaces_request`, 9 total.
+  - This asks for the workspace list sorted by `activity_at desc`, usually page limit 200.
+  - On the server this triggers workspace git observer sync and workspace update flushing.
+
+- Agent list and agent detail hydration:
+  - `fetch_agents_request`, 11 total.
+  - `fetch_agent_request`, 1 total.
+  - `fetch_agent_timeline_request`, 7 total.
+  - Timeline requests are among the slowest requests in this slice.
+
+- Checkout/PR status UI:
+  - `checkout_pr_status_request`, 18 total, all Electron.
+  - `checkout_status_request`, 1 total.
+  - `subscribe_checkout_diff_request`, 2 total.
+  - These correspond to git snapshot consumers and are clustered during Electron reconnect.
+
+- Provider/model/mode UI:
+  - `get_providers_snapshot_request`, 9 total.
+  - `providers_snapshot_update`, 129 outbound updates.
+  - OpenCode provider snapshot refresh times out twice during this flow.
+
+- Workspace chrome:
+  - `project_icon_request`, 9 total.
+  - `file_explorer_request`, 1 total.
+
+- Terminal panel:
+  - `list_terminals_request`, 5 total.
+  - `subscribe_terminals_request`, 5 total.
+  - `terminals_changed`, 5 outbound updates.
+
+- Attention state:
+  - `clear_agent_attention`, 6 total.
+  - Some failures appear while clearing attention for persisted agents, but these are not provider startup failures.
+
+## Concrete Waste-Looking Work, Without Optimizing Yet
+
+The log shows repeated work in these exact forms:
+
+- 444 git commands total, but only 14 complete before the first client hello. The rest are post-listen startup/client hydration work.
+- Several workspaces get repeated full checkout snapshot patterns:
+  - three 33-command worktrees each get `3` root checks, `3` dirty checks, `3` upstream config probes, `9` ahead/behind probes, `12` ref checks, and `3` base divergence checks.
+  - three 27-command worktrees each get `3` root checks, `3` dirty checks, `6` upstream config probes, `6` ahead/behind probes, `6` ref checks, and `3` base divergence checks.
+  - `~/dev/paseo` gets `5` root checks, `5` dirty checks, `10` upstream config probes, and `10` ahead/behind probes.
+- Electron sends 18 `checkout_pr_status_request` messages at the same timestamp, then they drain slowly over ~20s.
+- Provider snapshot updates are broadcast very frequently: 129 outbound `providers_snapshot_update` messages, including large repeated payloads around 216KB and 415KB.
+- OpenCode snapshot refresh times out twice after 30s, but the actual OpenCode agent connection/resume succeeds.
+
+Again, this section names repeated work observed in the startup. It does not claim which repetition should be removed.

docs/floating-panels.md

@@ -0,0 +1,179 @@
+# Floating Panels
+
+Anchored popovers — tooltips, hover cards, dropdowns, autocompletes — that visually
+float above an anchor element on iOS, Android, and web. This doc captures the
+non-obvious traps. It is **not** a tutorial; it assumes you have seen the
+canonical files and are trying to add or change one.
+
+## Canonical files
+
+| File                                     | Use case                                                          |
+| ---------------------------------------- | ----------------------------------------------------------------- |
+| `components/ui/combobox.tsx`             | Anchored picker with search; mobile falls back to bottom sheet    |
+| `components/ui/tooltip.tsx`              | Non-interactive hover/long-press tooltip                          |
+| `components/workspace-hover-card.tsx`    | Desktop-web hover card with measure + computePosition + Portal    |
+| `components/ui/autocomplete-popover.tsx` | Slash-command autocomplete anchored to the focused composer input |
+
+Each handles a different mix of concerns: combobox owns input focus, tooltip is
+non-interactive, hover-card is web-only desktop, autocomplete keeps the composer
+input focused while its scrollable list lives in a Portal. There is no shared
+"floating panel" primitive yet — when a fifth use case shows up we can revisit;
+until then prefer copying the closest file and trimming.
+
+## Gotcha 1 — Android touch hit-test by parent bounds
+
+On Android, a child View whose bounds fall outside its parent's bounds renders
+correctly (with `overflow: visible`, the default) but **does not receive touch
+events**. `ViewGroup.dispatchTouchEvent` filters touches by the parent's hit
+rect first, then iterates children. A touch in the overflowing region never
+reaches the parent, let alone the child. iOS and web do not share this rule —
+iOS hit-test descends into overflowing children, web uses standard CSS pointer
+events. This is the bug that put autocomplete on this path: the popover was
+positioned `bottom: 100%` of its parent and worked on iOS/web for months;
+Android touches sailed straight through to the chat scroll view behind it.
+
+Two escape hatches in the codebase:
+
+- **`Modal`** (combobox, tooltip on native) — opens a new Android window, so
+  hit-testing starts fresh in that window. Side effect: a Modal opening on
+  Android can detach the IME from an underlying TextInput. Fine for combobox
+  (it has its own input) and tooltip (no input). **Not** fine for autocomplete
+  (the composer's input must stay focused so the user keeps typing).
+- **`<Portal>` from `@gorhom/portal`** (hover-card, autocomplete-popover) —
+  hoists the React subtree to a fixed mount point whose bounds cover the
+  screen. Same window, same IME, hit-test works because the new parent is
+  full-screen. This is the right default when you must keep IME attachment.
+  Choose the host by layer: app-global overlays use the root host; content
+  overlays can use the current `FloatingPanelPortalHost` so sliding sidebars
+  cover them.
+
+Choose Modal vs Portal by whether the underlying input can lose its keyboard.
+
+## Gotcha 2 — Portal breaks lifecycle and coordinate-system inheritance
+
+A Portal escapes Android's hit-test, but it also escapes two things you were
+quietly relying on:
+
+- **Lifecycle.** The portal'd subtree mounts at the app root, not inside your
+  component's natural ancestor chain. When the user navigates away, your
+  component may stay mounted (offscreen, in a tab) — the popover stays with it.
+  Gate `visible` on a screen-focus signal. For panes inside `agent-panel`, the
+  `isPaneFocused` prop already exists and flips on pane switches; pass
+  `visible={isYourOwnVisible && isPaneFocused}`.
+- **Transforms.** The composer is wrapped in a Reanimated `Animated.View` with
+  `translateY: -keyboardShift` (see `use-keyboard-shift-style.ts`). The chat
+  content has the same transform applied (`agent-panel.tsx:939`). They move
+  together because they share the SharedValue. A portal'd popover is outside
+  the composer tree — it does not get that transform unless you apply it
+  yourself.
+- **Layering.** The default root host renders after app content, so it sits
+  above compact sidebars. Content overlays that must sit below sidebars should
+  use the current `FloatingPanelPortalHost`.
+- **Coordinate systems.** `measureInWindow` gives window coordinates. A Portal
+  renders inside its host, not necessarily at window origin. Position anchored
+  content relative to the host: `anchorRect - hostRect`. This is what
+  `measureFloatingPanelPortalHost()` is for.
+
+The fix for transforms is Gotcha 3.
+
+## Gotcha 3 — Reanimated transforms vs `measureInWindow`
+
+`measureInWindow` returns the view's _current_ screen position. In theory that
+includes Reanimated-applied transforms (Reanimated updates native view
+properties, and Android's `getLocationInWindow` reads transformed coords). In
+practice it's racy — the measurement may snapshot mid-animation, and on Android
+with Reanimated worklets the result is not always stable.
+
+If the panel cannot stay inside the transformed ancestor, do not try to track
+the keyboard by re-measuring on every frame. Instead,
+**slave the popover's transform to the same SharedValue the composer uses**:
+
+1. Snapshot `openShift = shift.value` at the moment you measure the anchor.
+2. Apply `useAnimatedStyle(() => ({ transform: [{ translateY: openShift.value - shift.value }] }))`
+   to the popover wrapper.
+
+When `shift` equals `openShift`, the translate is 0 and the popover sits at
+the measured position. When the keyboard moves afterward, the delta translates
+the popover by exactly the amount the composer translates. They move in
+lockstep, no re-measurement needed.
+
+Re-measure on `Keyboard.addListener('keyboardDidShow'|'keyboardDidHide')` only
+to refresh the snapshot if the keyboard was mid-transition when the popover
+opened.
+
+## Gotcha 4 — Host-relative positioning before platform offsets
+
+The generic anchored-overlay rule is:
+
+1. Measure the anchor with `measureInWindow`.
+2. Measure the Portal host with `measureFloatingPanelPortalHost(hostName)`.
+3. Position with anchor coordinates relative to the host:
+
+```ts
+left = anchorRect.x - hostRect.x;
+bottom = hostRect.height - (anchorRect.y - hostRect.y) + offset;
+```
+
+Do this before adding any platform offset. If anchor and host are both measured
+with `measureInWindow`, Android's status-bar coordinate behavior cancels out.
+Only add a status-bar offset when the render surface is not measured in the same
+coordinate system. See `tooltip.tsx` for that separate case.
+
+## Gotcha 5 — The two-measurement flash
+
+If your popover needs `top` (or `left`) computed from both:
+
+- the anchor's screen position (`anchorRect` from `measureInWindow`), **and**
+- the popover's own size (`contentSize` from `onLayout`),
+
+then a naïve implementation will flash through three positions on every open:
+
+1. **Frame 1** — render with `top: -9999` (or any placeholder) while waiting
+   for either measurement. Wrapper has no `width`, so the inner content lays
+   out at its natural (often narrow) intrinsic width.
+2. **Frame 2** — `anchorRect` lands. Wrapper now has `width: anchorRect.width`.
+   But the stale `onLayout` from frame 1 has already set `contentSize` to the
+   narrow-width dimensions. `top = anchorRect.y - wrongHeight - gap` — visible
+   at the wrong spot.
+3. **Frame 3** — real `onLayout` fires with the correct width. `contentSize`
+   updates. Position snaps to the right place.
+
+The visible jump in frame 2 is the flash. Two pieces solve it, and you need
+both:
+
+- **Do not mount the floating content until `anchorRect` is set.** Return
+  `null` until then. This prevents the bad-width onLayout from happening at
+  all.
+- **Once `anchorRect` is set but `contentSize` isn't, render the wrapper with
+  the final width but `opacity: 0`.** The first visible paint is at the
+  correct position. This is the combobox pattern —
+  `shouldHideDesktopContent` at `combobox.tsx:481, 876`. **Do not** use
+  `top: -9999` as the placeholder; the layout work still happens at -9999 and
+  any subsequent state-flash is visible when you flip back.
+
+The "render invisible to measure, then reveal" pattern is the canonical
+solution to chicken-and-egg positioning in this codebase. Reach for it before
+anything fancier.
+
+## Recipe for a new anchored panel
+
+Before you write a new one, ask:
+
+1. **Can the underlying input lose its keyboard?** If yes, use Modal (simpler).
+   If no, use Portal.
+2. **Does the panel need to dismiss on screen change?** Almost always yes —
+   gate `visible` on an upstream focus prop (`isPaneFocused` or similar).
+3. **Is the panel rendered in a Portal host?** Measure the host too. Never use
+   raw window coordinates as local Portal coordinates.
+4. **Does the panel sit above something that moves with the keyboard?** If
+   yes, slave a Reanimated transform to the same SharedValue (Gotcha 3).
+   If no, you can probably skip the transform entirely.
+5. **Will the panel's content height vary?** If yes, you need both
+   `anchorRect` and `contentSize` for positioning → apply Gotcha 5 (return
+   null until anchor, then opacity-0 until contentSize). If no — content has
+   a known fixed max height — you might be able to use bottom-anchored
+   positioning (`bottom: windowHeight - anchor.y + gap`) and skip the
+   `contentSize` round-trip entirely. **But only if the height is genuinely
+   bounded**. Verify before you commit.
+
+Then copy the closest canonical file and trim.

docs/glossary.md

@@ -3,27 +3,34 @@
 Authoritative terminology. UI label wins. Don't invent synonyms; use what's here.
 
 - **Project** — Logical grouping of workspaces sharing a git remote (or main repo root). UI: "Project" / "Add project". Code: `ProjectSummary` (`packages/app/src/utils/projects.ts:22`), `projectKey` (`packages/server/src/server/workspace-registry-model.ts:16`). Forbidden: "Repo", "Repository" as UI label.
-- **Workspace** — One concrete `cwd` on one daemon, with git state; belongs to exactly one project. UI: "Workspace". Code: `WorkspaceDescriptorPayload` (`packages/server/src/shared/messages.ts:2178`). Don't confuse with: Branch (one branch can back many workspaces via worktrees). Forbidden: "Folder", "Directory" as UI label.
+- **Workspace** — One concrete `cwd` on one daemon, with git state; belongs to exactly one project. UI: "Workspace". Code: `WorkspaceDescriptorPayload` (`packages/protocol/src/messages.ts:2178`). Don't confuse with: Branch (one branch can back many workspaces via worktrees). Forbidden: "Folder", "Directory" as UI label.
 - **Workspace kind** — `"directory" | "local_checkout" | "worktree"`. Code: `PersistedWorkspaceKind` (`packages/server/src/server/workspace-registry-model.ts:8`).
-- **Agent** — One AI coding agent run on a daemon (one provider, one model, one cwd, one timeline). UI: "Agent" / "New Agent". Code: `AgentSnapshotPayload` (`packages/server/src/shared/messages.ts:608`). Forbidden: "Task", "Job", "Run".
-- **Daemon** — Local Paseo server process; identified by `serverId`. UI: "Daemon" (system contexts only). Code: `serverId` in `ServerInfoStatusPayloadSchema` (`packages/server/src/shared/messages.ts:1936`), `DaemonClient` (`packages/server/src/client/daemon-client.ts`).
+- **Agent** — One AI coding agent run on a daemon (one provider, one model, one cwd, one timeline). UI: "Agent" / "New Agent". Code: `AgentSnapshotPayload` (`packages/protocol/src/messages.ts:608`). Forbidden: "Task", "Job", "Run".
+- **Daemon** — Local Paseo server process; identified by `serverId`. UI: "Daemon" (system contexts only). Code: `serverId` in `ServerInfoStatusPayloadSchema` (`packages/protocol/src/messages.ts:1936`), `DaemonClient` (`packages/client/src/daemon-client.ts`).
 - **Host** — Client-side connection profile pointing at a daemon; bundles one or more `HostConnection`s. UI: "Host" / "Add host" / "Switch host". Code: `HostProfile` (`packages/app/src/types/host-connection.ts:37`). Forbidden: "Connection" (means `HostConnection`, not host).
 - **Project host entry** — One row in a project for a single (project, daemon) pair, aggregating that daemon's workspaces in the project. Internal. Code: `ProjectHostEntry` (`packages/app/src/utils/projects.ts:11`). Don't introduce "Checkout" as a synonym.
-- **Placement** — One workspace's relationship to its project (projectKey, projectName, git checkout snapshot). Internal. Code: `ProjectPlacementPayload` (`packages/server/src/shared/messages.ts:2113`).
-- **Branch** — Plain git branch. UI: "Switch branch". Code: `currentBranch` in `WorkspaceGitRuntimePayloadSchema` (`packages/server/src/shared/messages.ts:2136`); `BranchSwitcher` (`packages/app/src/components/branch-switcher.tsx`).
-- **Worktree** — Paseo-managed git worktree (`~/.paseo/worktrees/{name}`); also a `workspaceKind` value. UI: CLI + `paseo.json` keys (`worktree.setup`, `worktree.teardown`) only. Code: `ProjectCheckoutLiteGitPaseoPayload` (`packages/server/src/shared/messages.ts:2092`); CLI `paseo worktree` (`packages/cli/src/commands/worktree/index.ts:8`). Forbidden: "Checkout" as a synonym.
+- **Placement** — One workspace's relationship to its project (projectKey, projectName, git checkout snapshot). Internal. Code: `ProjectPlacementPayload` (`packages/protocol/src/messages.ts:2113`).
+- **Branch** — Plain git branch. UI: "Switch branch". Code: `currentBranch` in `WorkspaceGitRuntimePayloadSchema` (`packages/protocol/src/messages.ts:2136`); `BranchSwitcher` (`packages/app/src/components/branch-switcher.tsx`).
+- **Worktree** — Paseo-managed git worktree (`~/.paseo/worktrees/{name}`); also a `workspaceKind` value. UI: CLI + `paseo.json` keys (`worktree.setup`, `worktree.teardown`) only. Code: `ProjectCheckoutLiteGitPaseoPayload` (`packages/protocol/src/messages.ts:2092`); CLI `paseo worktree` (`packages/cli/src/commands/worktree/index.ts:8`). Forbidden: "Checkout" as a synonym.
 - **Repository / Remote** — Internal git inputs (`remoteUrl`, `mainRepoRoot`) used to derive `projectKey`. No UI label.
 - **Session** — Per-client connection to a daemon. Internal. Code: `Session` (`packages/server/src/server/session.ts`). Don't confuse with: provider-side agent session log.
 - **Profile** — Internal name for the persisted shape of a host. Code: `HostProfile` (`packages/app/src/types/host-connection.ts:37`). Never user-facing.
-- **Provider** — Agent backend (Claude Code, Codex, OpenCode). UI: "Provider". Code: `ProviderSnapshotEntry` (`packages/server/src/shared/messages.ts:198`).
-- **Model** — A specific LLM offered by a provider. UI: "Model" / "Select model". Code: `AgentModelDefinition` (`packages/server/src/shared/messages.ts:187`).
-- **Terminal** — Workspace-scoped PTY shell streamed over the binary mux channel. UI: "Terminal". Code: `TerminalStreamFrame` (`packages/server/src/shared/terminal-stream-protocol.ts`).
-- **Schedule** — Cron-style trigger that creates remote agents. UI: CLI only (`paseo schedule`). Code: `ScheduleCreateRequest` (re-exported from `packages/server/src/shared/messages.ts`). Don't confuse with: Loop (iterative re-execution of one agent).
-- **Mode** — Provider-specific operational mode (plan, default, full-access, …). UI: icon-only. Code: `modeId` in `AgentSessionConfig` (`packages/server/src/shared/messages.ts:257`).
-- **Attachment** — GitHub PR or Issue bound to an agent prompt. UI: "Attach issue or PR". Code: `AgentAttachment` (`packages/server/src/shared/messages.ts:782`).
+- **Provider** — Agent backend (Claude Code, Codex, Copilot, OpenCode, Pi). UI: "Provider". Code: `ProviderSnapshotEntry` (`packages/protocol/src/messages.ts:198`).
+- **Model** — A specific LLM offered by a provider. UI: "Model" / "Select model". Code: `AgentModelDefinition` (`packages/protocol/src/messages.ts:187`).
+- **Terminal** — Workspace-scoped PTY shell streamed over the binary mux channel. UI: "Terminal". Code: `TerminalStreamFrame` (`packages/protocol/src/terminal-stream-protocol.ts`).
+- **Schedule** — Cron-style trigger that creates remote agents. UI: CLI only (`paseo schedule`). Code: `ScheduleCreateRequest` (re-exported from `packages/protocol/src/messages.ts`). Don't confuse with: Loop (iterative re-execution of one agent).
+- **Mode** — Provider-specific operational mode (plan, default, full-access, …). UI: icon-only. Code: `modeId` in `AgentSessionConfig` (`packages/protocol/src/messages.ts:257`).
+- **Attachment** — GitHub PR or Issue bound to an agent prompt. UI: "Attach issue or PR". Code: `AgentAttachment` (`packages/protocol/src/messages.ts:782`).
+- **Composer** — The whole prompt surface for sending work to an agent. Code: `Composer` (`packages/app/src/composer/index.tsx`). Don't call this "message input" except for the text-entry subcomponent.
+- **Composer input** — The text-entry surface inside the composer. Code: `MessageInput` (`packages/app/src/composer/input/input.tsx`).
+- **Composer toolbar** — The bottom control row inside the composer input. Contains agent controls, attachment button, voice controls, and stop/send controls. Code: `leftContent`, `beforeVoiceContent`, and `rightContent` slots in `MessageInput` (`packages/app/src/composer/input/input.tsx`). Forbidden: "Status bar".
+- **Agent controls** — Provider, model, mode, thinking, and provider-feature controls for an agent or draft agent. Code: `AgentControls` / `DraftAgentControls` (`packages/app/src/composer/agent-controls/index.tsx`). Forbidden: "Agent status bar".
+- **Composer footer** — Optional area rendered below the composer input but still inside the keyboard-shifted composer layout. Code: `Composer.footer` (`packages/app/src/composer/index.tsx`).
+- **Composer track** — A contextual lane above the composer input. Specific tracks use the `<thing> track` form: **Queue track**, **Subagents track**. Code: queue track inside `Composer` (`packages/app/src/composer/index.tsx`), `SubagentsTrack` (`packages/app/src/subagents/track.tsx`).
+- **Attachment tray** — The selected-attachments row inside the composer input, above the text input. Code: `renderAttachmentTray` (`packages/app/src/composer/index.tsx`). Forbidden: "Attachment bar".
 - **Conflict** — Two distinct senses; do NOT use the bare word in UI copy without qualifying which: (a) **stale-write conflict** on `paseo.json` ("Config changed on disk", code `stale_project_config`, `packages/app/src/screens/project-settings-screen.tsx:593`); (b) **git merge conflict** (no current UI string).
 
 ## Inconsistencies (documented, not papered over)
 
 - CLI `--host <host>` description `"Daemon host target"` (`packages/cli/src/utils/command-options.ts:5`) blurs daemon/host; the app keeps them distinct.
-- `WorkspaceDescriptorPayloadSchema.workspaceKind` accepts legacy `"checkout"` on the wire (`packages/server/src/shared/messages.ts:2187`) while `PersistedWorkspaceKind` does not (`packages/server/src/server/workspace-registry-model.ts:8`).
+- `WorkspaceDescriptorPayloadSchema.workspaceKind` accepts legacy `"checkout"` on the wire (`packages/protocol/src/messages.ts:2187`) while `PersistedWorkspaceKind` does not (`packages/server/src/server/workspace-registry-model.ts:8`).

docs/mobile-testing.md

@@ -249,6 +249,23 @@ const { theme } = useUnistyles();
 
 Regular `View` components can safely use Unistyles dynamic styles — the conflict is specific to `Animated.View`.
 
+## Native Chat Stream Layout
+
+The native agent stream uses an inverted `FlatList`, so chat layout has three coordinate systems:
+
+- chronological stream order
+- strategy-ordered array order
+- native inverted cell visual order
+
+Do not compute stream neighbors, history/live-head seams, turn footer ownership, assistant block spacing, or tool sequence endings inside React render loops. Those policies live in `packages/app/src/agent-stream/layout.ts` and are unit-tested without React Native rendering.
+
+Platform-specific stream edges belong on `StreamStrategy`:
+
+- forward web uses the last history item as the history/live-head boundary and renders content before a footer
+- native inverted uses the first history item as the history/live-head boundary and compensates for inverted cell child order
+
+If a chat footer looks duplicated or appears above the assistant message on mobile, start with `packages/app/src/agent-stream/layout.test.ts`. Do not add a React Native renderer test for this class of bug; make the pure layout invariant fail first.
+
 ## iOS Simulator
 
 ```bash

docs/opencode-global-event-baseline.md

@@ -16,7 +16,7 @@ Replace the OpenCode provider's per-directory `/event` stream with OpenCode's `/
 Each OpenCode test file was run independently with:
 
 ```bash
-/opt/homebrew/bin/timeout 420s npx vitest run <file> --maxWorkers=1 --minWorkers=1
+/opt/homebrew/bin/timeout 420s npx vitest run <file> --maxWorkers=1
 ```
 
 ## Baseline
@@ -44,6 +44,6 @@ One live reasoning-dedup matrix run returned no reasoning content; an immediate
 - `npm run typecheck`
 - `npm run lint`
 - `git diff --check`
-- `npx vitest run packages/server/src/server/agent/providers/opencode-agent.test.ts --maxWorkers=1 --minWorkers=1`
-- `npx vitest run packages/server/src/server/agent/providers/opencode-agent.error-handling.real.e2e.test.ts --maxWorkers=1 --minWorkers=1`
-- `npx vitest run packages/server/src/server/daemon-e2e/opencode-initial-prompt-wait.real.e2e.test.ts --maxWorkers=1 --minWorkers=1`
+- `npx vitest run packages/server/src/server/agent/providers/opencode-agent.test.ts --maxWorkers=1`
+- `npx vitest run packages/server/src/server/agent/providers/opencode-agent.error-handling.real.e2e.test.ts --maxWorkers=1`
+- `npx vitest run packages/server/src/server/daemon-e2e/opencode-initial-prompt-wait.real.e2e.test.ts --maxWorkers=1`

docs/product.md

@@ -71,7 +71,7 @@ Anyone who builds software:
 
 - Desktop (Electron), mobile (iOS/Android), web, CLI
 - Built-in providers: Claude Code (Agent SDK), Codex (app-server), GitHub Copilot (ACP), OpenCode, Pi
-- One-click ACP provider catalog: Cursor, Hermes, Qwen Coder, Kimi Code, and others — plus custom ACP providers
+- One-click ACP provider catalog: Cursor, DeepSeek TUI, Hermes, Qwen Coder, Kimi Code, and others — plus custom ACP providers
 - Voice mode: dictate prompts or talk through problems hands-free
 - MCP server exposes the daemon to other agents (create_agent, send_agent_prompt, schedules, terminals, worktrees)
 - Scheduled agents (cron-style triggers) via app, CLI, and MCP

docs/providers.md

@@ -14,17 +14,37 @@ The only built-in ACP provider today is `copilot` (`copilot-acp-agent.ts`). `Gen
 
 Implement the `AgentClient` and `AgentSession` interfaces from `agent-sdk-types.ts` yourself. This gives full control but requires you to handle process management, streaming, permissions, and session persistence from scratch.
 
-Existing direct providers: `claude` (in `providers/claude/agent.ts`), `codex` (`codex-app-server-agent.ts`), `opencode` (`opencode-agent.ts`), `pi` (`pi-direct-agent.ts`). The dev-only `mock` provider (`mock-load-test-agent.ts`) is also direct.
+Existing direct providers: `claude` (in `providers/claude/agent.ts`), `codex` (`codex-app-server-agent.ts`), `opencode` (`opencode-agent.ts`), `pi` (`providers/pi/agent.ts`). The dev-only `mock` provider (`mock-load-test-agent.ts`) is also direct.
+
+Pi is a process-backed provider. Paseo requires the user to have the `pi` binary installed and talks to it through `pi --mode rpc`; the server package does not embed Pi's SDK/runtime packages.
+
+Paseo's per-agent and daemon-wide system prompts are passed to Pi with `--append-system-prompt`, so Pi keeps its default coding prompt while receiving Paseo's additional instructions.
+
+Pi MCP support depends on the open-source `pi-mcp-adapter` extension being loaded for the agent cwd. Probe with Pi RPC `get_commands`; the adapter registers an extension command named `mcp` (often with `sourceInfo.source` containing `pi-mcp-adapter`). When Paseo injects MCP servers into Pi, write a per-agent MCP config and pass it with `--mcp-config` instead of modifying user or project MCP files. For local HTTP servers such as Paseo's own `/mcp/agents` endpoint, explicitly disable adapter OAuth (`auth: false`, `oauth: false`) in the generated config.
+
+Pi import discovery reads Pi's persisted JSONL session files because Pi RPC does not expose a recent-session listing command. Resume and full history hydration still go through `pi --mode rpc` using the session file as `nativeHandle`.
+
+Pi RPC extension UI dialog requests (`select`, `input`, `editor`, `confirm`) are bridged into Paseo question permissions and answered with `extension_ui_response`. Pi extensions such as `ask_user` may chain dialogs: for example, a `select` can be followed by an optional-comment `input`. When an `ask_user` tool call declares `allowComment: true`, Paseo presents the selection and optional comment as one question permission, answers Pi's initial `select` immediately, then auto-answers the follow-up optional `input` with the comment the user already supplied (or an empty string). Preserve placeholders and optional/skip semantics for standalone optional inputs so the app can still distinguish "skip this optional input" from "cancel the whole dialog." Fire-and-forget extension UI requests such as notifications are intentionally ignored by the provider adapter unless Paseo grows first-class UI for them.
+
+OpenCode MCP injection is dynamic and session-scoped. Call OpenCode's `mcp.add` endpoint with the MCP server config and do not follow it with `mcp.connect`; `connect` only toggles MCP servers already present in OpenCode's own config. New OpenCode versions return `McpServerNotFoundError`/404 for `connect` after a dynamic add because the server is not config-backed, while older versions silently swallowed the same missing-config path.
+
+OpenCode owns user message IDs. Do not pass Paseo-generated IDs to OpenCode prompt APIs; let OpenCode create `msg*` IDs and record the user timeline item from the `message.updated` event.
+
+Draft metadata lookups should avoid creating provider sessions when the upstream provider has top-level APIs for that metadata. Prefer `AgentClient.listModels`, `listModes`, `listCommands`, or `listFeatures` over creating a scratch `AgentSession`; scratch sessions can show up as empty native sessions in provider import/history UIs.
 
 ---
 
 ## Provider Snapshot Refresh Contract
 
-The daemon keeps one global provider snapshot, keyed to the home directory, for settings, selectors, and old model/mode list requests. Snapshot reads may probe providers only while the snapshot is cold. Once an entry is warm, its `ready`, `error`, or `unavailable` state stays cached until the user forces a refresh from settings/provider management.
+The daemon keeps provider snapshots per resolved working directory. Missing or blank cwd resolves to the user's home directory. Workspace selectors and old model/mode list requests should pass the cwd that will launch the provider so providers with project-specific models or modes are probed in the right context. Settings/provider management intentionally uses the home-directory snapshot.
 
-Do not add TTL revalidation, focus-triggered refreshes, selector-open refreshes, or config-reload refreshes. Registry/config replacement may update visible metadata such as label, description, default mode, enabled state, and provider membership, but it must not spawn provider processes. If a provider needs to be re-probed after a config change, route that through the explicit settings refresh path.
+Snapshot reads may probe providers only while the requested cwd scope is cold. Once an entry is warm, its `ready`, `error`, or `unavailable` state stays cached until an explicit refresh. Do not add TTL revalidation, focus-triggered refreshes, selector-open refreshes, or config-reload refreshes. Selector-open refetches may read an already-loading or stale React Query, but they must not force provider probing on their own.
 
-Boundary tests should assert observable behavior: cold reads may call provider availability/model/mode discovery; warm reads and registry replacement must not; explicit full or targeted refreshes must.
+Settings refresh is the user-facing "forget stale provider knowledge everywhere" action. A settings refresh clears provider snapshot caches and in-flight loads across all cwd scopes, then immediately refreshes only the home-directory snapshot with `force: true`. Workspace snapshots are re-probed lazily on the next scoped read; do not fan out a settings refresh across every known workspace.
+
+Registry/config replacement may update visible metadata such as label, description, default mode, enabled state, and provider membership, but it must not spawn provider processes. If a provider needs to be re-probed after a config change, route that through the explicit settings refresh path.
+
+Boundary tests should assert observable behavior: cold reads may call provider availability/model/mode discovery for that cwd; warm reads and registry replacement must not; explicit workspace refreshes affect only one cwd; settings refresh wipes all scopes but immediately refreshes only home.
 
 ---
 

docs/release.md

@@ -2,12 +2,35 @@
 
 All workspaces share one version and release together.
 
+## Two steps
+
+A release has exactly two steps. The agent does the first, the user authorizes the second.
+
+**Preparation** (local, reversible — agent does this):
+
+- format, lint, typecheck all green
+- draft the changelog, show it to the user, wait for review
+- run the pre-release sanity check, surface findings to the user
+- confirm CI is green
+
+**Go-ahead** (user says "go ahead"):
+
+- commit the approved changelog
+- run the release
+
+Rules that apply to both steps:
+
+- Last-minute changes always need approval. Every time.
+- No code changes bundled into the changelog commit or the release commit. Code shims live in their own commit, reviewed on their own merits.
+- A sanity-check finding is information, not a directive. The agent surfaces it; the user decides.
+- Invoking a release skill is intent to start the flow, not blanket authorization to publish.
+
 ## Two paths
 
 There are two supported ways to ship from `main`:
 
 1. **Direct stable release**: you are ready to ship the current `main` commit to everyone immediately.
-2. **Beta flow**: you want public test builds first, but you are not ready for the website, npm, or production mobile release flows to move yet.
+2. **Beta flow**: silent release candidates. Betas don't touch the changelog, don't move the website, and don't publish npm or production mobile builds.
 
 ## Standard release (patch)
 
@@ -21,11 +44,11 @@ Before running any stable patch release command:
 npm run release:patch
 ```
 
-This bumps the version across all workspaces, runs checks, publishes to npm, and pushes the branch + tag (triggering `Desktop Release`, `Android APK Release`, EAS `release-mobile.yml`, and `Release Notes Sync` workflows).
+This bumps the version across all workspaces, runs checks, publishes to npm, and pushes the branch + tag. The tag push triggers `Desktop Release`, `Android APK Release`, and `Release Notes Sync` on GitHub Actions. EAS picks up the same tag via the EAS GitHub app and starts the iOS + Android store builds in parallel (see "Mobile builds (EAS)" below) — there is no `release-mobile.yml` in this repo.
 
-If asked to "release paseo" without specifying major/minor, treat it as a patch release.
+**Releases are always patch.** "Release paseo", "release stable", "ship stable", and similar always mean a patch bump from the previous stable. Never bump minor or major to trigger a build, ever — minor and major bumps are reserved for genuinely larger product cuts and require an explicit user instruction with the word "minor" or "major". If you find yourself reaching for `release:minor` to retrigger a failed build, you are doing the wrong thing — push a retry tag instead (see "Fixing a failed release build" below).
 
-Use the direct stable path when the current `main` changes are ready to become the public release immediately.
+**Stable means stable.** If the user says "stable" or "ship stable", do not ask whether they want a beta first. They picked stable; treat it as a direct stable release. Only run the beta flow when the user explicitly says "beta".
 
 ## Manual step-by-step
 
@@ -51,10 +74,11 @@ npm run release:promote          # Promote X.Y.Z-beta.N to stable X.Y.Z
 - `release:promote` creates a fresh stable tag like `v0.1.41`; the final release never reuses the beta tag
 - Desktop assets now come from the Electron package at `packages/desktop`
 - Beta releases use Electron's `beta` update channel. Users on the stable channel only receive stable releases; users on the beta channel receive beta releases and the final stable release when it is published.
-- **Do create a changelog entry for betas.** The beta entry is temporary and gets updated in place until promotion.
+- **Betas don't touch `CHANGELOG.md`.** Beta GitHub releases ship with empty notes — that's intentional. The changelog entry is written once, at promotion time, covering the full stable-to-stable diff. The release-notes sync script skips betas cleanly because no matching section exists.
 
 Use the beta path when you need to:
 
+- smoke a build yourself before promoting it to everyone
 - test a build manually in a Linux or Windows VM
 - send a build to a user who is hitting a specific problem
 - iterate on `beta.1`, `beta.2`, `beta.3`, and so on before deciding to ship broadly
@@ -147,6 +171,63 @@ If N+1 is a hotfix for a bug in N, dispatch `desktop-rollout.yml -f tag=v0.1.<N+
 - **Bootstrap caveat.** Clients running a build older than the rollout feature ignore `rolloutHours` and admit immediately. Rollout protection only applies to clients running the rollout-aware version or later.
 - **Up to ~30 min admission latency.** Renderer polls every 30 minutes, so a stable user may take up to that long to be evaluated against the rollout window.
 
+## Mobile builds (EAS)
+
+iOS and Android store builds are not in `.github/workflows`. They are triggered by the EAS GitHub app the moment the `v*` tag is pushed:
+
+- **Android (Play Store)** — EAS builds with profile `production` and auto-submits to the Play Store via `eas submit` (EAS-managed credentials, no Fastlane).
+- **iOS (TestFlight + App Store)** — EAS builds with profile `production`, uploads to TestFlight, and a Fastlane lane submits the build for App Store review.
+- **Android APK (GitHub Release asset)** — separate, via `.github/workflows/android-apk-release.yml`. This is the only Android-related workflow that lives in this repo.
+
+There is no `release-mobile.yml` in this repo. Earlier versions of these docs referenced one — that workflow was removed and the EAS GitHub app handles tag triggering directly.
+
+### Watching mobile builds from the terminal
+
+Use the EAS CLI from `packages/app/`:
+
+```bash
+cd packages/app
+
+# Recent builds (newest first). Pipe to jq for status only.
+npx eas build:list --limit 8 --non-interactive --json | jq '.[] | {platform, status, appVersion, gitCommitHash}'
+
+# Filter by platform.
+npx eas build:list --platform ios --limit 5 --non-interactive --json
+npx eas build:list --platform android --limit 5 --non-interactive --json
+
+# Inspect a specific build.
+npx eas build:view <build-id>
+
+# Stream logs for a build.
+npx eas build:view <build-id> --json | jq '.logFiles[]'
+```
+
+A build's `gitCommitHash` must match the release tag commit. `status` walks through `NEW` → `IN_QUEUE` → `IN_PROGRESS` → `FINISHED` (or `ERRORED`/`CANCELED`).
+
+Once a build is `FINISHED`, EAS auto-submits it to the store: Android via the `submit` block in `eas.json` (EAS-managed Play Console credentials), iOS via the Fastlane `submit_review` lane (uploads to TestFlight, then submits for App Store review). To confirm the submission landed, run `npx eas build:view <build-id>` and open the `Logs` URL it prints — the build's Expo dashboard page has a Submissions section listing each attempt with its store response. App Store Connect (TestFlight tab → ready for review) and the Play Console (Internal testing / Production tracks) are the final ground truth.
+
+### Babysitting mobile after a release
+
+The user rarely opens the Expo dashboard. A failed EAS build can sit silently until users complain about a stale version. After every stable release, set up a long-delay babysit that re-checks both EAS builds and GitHub Actions for the release tag. If anything is `ERRORED` or `FAILED`, surface it immediately. If everything is `FINISHED`/`SUCCESS`, confirm and stop.
+
+**Use a heartbeat schedule, never a new-agent schedule.** Babysitting fires back into the current conversation as a wake-up prompt — `target: "self"` in `mcp__paseo__create_schedule`. Never use `target: "new-agent"`. A new agent spawns a fresh conversation the user has to find and read; a heartbeat surfaces the build status inline in the conversation that owns the release, where it is impossible to miss. If you find yourself reaching for `new-agent` for a release babysit, you are about to ship a status report into a void.
+
+Pattern:
+
+```jsonc
+// mcp__paseo__create_schedule arguments
+{
+  "name": "vX.Y.Z release babysit heartbeat",
+  "every": "15m",
+  "maxRuns": 8, // covers ~2h of build + store-submission window
+  "target": "self", // heartbeat, NOT "new-agent"
+  "cwd": "/path/to/paseo",
+  "prompt": "Heartbeat: check vX.Y.Z release builds. Run gh run list + eas build:list, report concisely; flag any ERRORED/FAILED/CANCELED.",
+}
+```
+
+Tight cadence on purpose. The first run fires immediately, giving a near-real-time status check before the conversation closes. Subsequent runs at 15-minute intervals catch transitions quickly: a failed EAS build that errors at +20m should not wait until +50m to surface. Keep the prompt short — the heartbeat is a status probe, not a research task — and have it bail out as soon as everything is green so the remaining runs do not generate noise.
+
 ## Release notes on GitHub
 
 The GitHub Release body is populated automatically by the `Release Notes Sync` workflow (`.github/workflows/release-notes-sync.yml`). It triggers on every `v*` tag push and on any push to `main` that touches `CHANGELOG.md`, then runs `scripts/sync-release-notes-from-changelog.mjs` to mirror the matching changelog entry into the release body. You don't need to write release notes on GitHub manually — keep `CHANGELOG.md` correct and the workflow will sync it. To force a re-sync, dispatch the workflow with the tag input.
@@ -207,18 +288,15 @@ Release notes depend on the changelog heading format. The heading **must** be st
 
 ```
 ## X.Y.Z - YYYY-MM-DD
-## X.Y.Z-beta.N - YYYY-MM-DD
 ```
 
 No prefix (`v`), no extra text. The parser matches the first `## X.Y.Z` line to extract the version. A malformed heading will break download links on the homepage.
 
 ## Changelog policy
 
-- `CHANGELOG.md` includes stable releases and the current beta line.
-- The first beta inserts a top entry like `## 0.1.60-beta.1 - YYYY-MM-DD`.
-- The next beta updates that same top entry in place, for example from `0.1.60-beta.1` to `0.1.60-beta.2`.
-- Stable promotion updates that same entry in place, for example from `0.1.60-beta.2` to `0.1.60`.
-- Do not create duplicate entries for each beta on the same version line.
+- `CHANGELOG.md` only lists stable releases. Betas are silent.
+- The changelog entry is authored once, at stable promotion time, with the date set to the promotion day.
+- It covers the full diff from the previous stable tag, regardless of how many betas were cut in between.
 
 ## Changelog ownership
 
@@ -230,7 +308,20 @@ No prefix (`v`), no extra text. The parser matches the first `## X.Y.Z` line to
 The changelog is shown on the Paseo homepage. Write it for **end users**, not developers.
 
 - **Frame everything from the user's perspective.** Describe what changed in the app, not what changed in the code. Users care that "workspaces load instantly" — not that a component no longer remounts.
-- **Never mention component names, internal modules, or implementation details.** No `WorkingIndicator`, no `accumulatedUsage`, no `reconcileAndEmitWorkspaceUpdates`.
+- **Never mention component names, internal modules, or implementation details.** No `WorkingIndicator`, no `accumulatedUsage`, no `reconcileAndEmitWorkspaceUpdates`. Also no "virtualized lists", no "remount", no "memoization", no "debounced", no "fuzzy ranking", no "controlled input", no "uncontrolled input" — these are implementation words masquerading as user-facing copy.
+- **Concrete WRONG → RIGHT examples** (real mistakes from past releases):
+
+  | Wrong (implementation-facing)                                                       | Right (user-facing)                                         |
+  | ----------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+  | Switching layouts no longer remounts the active agent                               | Splitting a pane no longer loses your scroll position       |
+  | Model, mode, and thinking pickers — searchable virtualized lists with fuzzy ranking | Mobile model selector is faster and more straightforward    |
+  | Text inputs in mobile sheets no longer flicker while typing fast                    | Typing in mobile sheets no longer flickers                  |
+  | Compact web sheets no longer crash when swiped to dismiss                           | Sheets on mobile web no longer crash when swiped to dismiss |
+  | Reduced re-renders in the agent list                                                | Agent list scrolls smoothly                                 |
+  | Added debouncing to the search input                                                | Search results no longer lag behind typing                  |
+
+  Test: would a non-developer reader recognise what changed when using the app? If they'd need an engineer to translate ("what's a remount?"), the bullet is still implementation-facing — rewrite it as the symptom the user experiences.
+
 - **Collapse internal iterations.** If a feature was added and then fixed within the same release, just list the feature as working. Users never saw the broken version.
 - **Only list changes relative to the previous stable release.** The diff is `v(previous)..HEAD`. If something was introduced and fixed between those two tags, it never shipped — don't mention the fix.
   - **Common trap:** when drafting from `git log`, every commit looks like a separate bullet — including the "fix X" commits that landed on top of a brand-new feature in the same release window. Before listing a Fixed entry, check whether the thing being fixed was itself added in this same release. If so, drop the fix and fold it into the feature bullet.
@@ -241,9 +332,12 @@ The changelog is shown on the Paseo homepage. Write it for **end users**, not de
 
 Every bullet must be scannable at a glance. The changelog is not release documentation — it's a list.
 
+- **One sentence per bullet, max.** If a bullet contains two sentences, the second one is doing work that belongs in product docs, not the changelog. Cut it.
+- **No trailing periods.** Bullets are list items, not prose. Drop the period at the end of every bullet, including the period inside any bolded lead-in. `**Configurable terminal scrollback**` not `**Configurable terminal scrollback.**`.
 - **One line per bullet.** If a bullet wraps to three lines in a narrow column, it's too long.
 - **Split bullets that pack multiple distinct changes.** If a bullet uses "and", "plus", a comma list, or an em-dash to chain several independent improvements, break them into separate bullets — even when they share a theme or author. One bullet = one user-facing change.
 - **Trim qualifying clauses.** Drop "with a hint shown when…", "matching the CLI's behaviour", "across common install shapes". If the detail doesn't change whether a user cares, cut it.
+- **Lead with what the user can do, not the mechanism.** The reader cares about the capability, not how it works under the hood. Do not explain LAN vs WAN, TLS handshakes, IPC, the daemon-relay topology, or any internal concept the user has not asked about. "Self-hosted relays can use a different TLS setting for the public endpoint" — not "Self-hosted relays support a separate TLS setting for the public endpoint, so the daemon can reach the relay over the LAN while the phone reaches it over the public secure address." If a feature genuinely needs background to be understood, it belongs in product docs, with a one-line teaser in the changelog.
 - **Lead with the outcome.** "Windows: agents launch reliably from npm `.cmd` shims…" is better than "Windows: agents launch reliably across common install shapes. Claude, Codex, and OpenCode now start correctly…".
 - **Attribution follows the split.** When you split a dense bullet, move each PR/author to the bullet it belongs to. Never duplicate the same PR across multiple bullets.
 
@@ -286,7 +380,7 @@ Entries within each section (Added, Improved, Fixed) are ordered by user impact:
 
 ## Pre-release sanity check
 
-Before cutting any release (beta or stable), run a Codex review of the diff as a last line of defence against shipping bugs.
+Before cutting a **stable** release, run a Codex review of the diff as a last line of defence against shipping bugs. Skip this for betas — the beta itself is the smoke test, and gating each beta on a code review defeats the point of using betas as fast release candidates.
 
 Load the `paseo` skill and launch a **Codex 5.4** agent with a prompt like:
 
@@ -302,15 +396,19 @@ The agent's job is a deep sanity check, not a full code review. If it flags anyt
 
 ## Changelog scope
 
-The changelog always covers **stable-to-HEAD**:
-
-- **Beta release**: the diff and release notes cover `latest stable tag -> HEAD`. The current beta changelog entry is updated in place.
-- **Stable release**: the same changelog entry is promoted in place. It still captures the full delta from the previous stable release, not just what changed since the last beta.
-
-In other words, betas are checkpoints along the way; the changelog entry remains the single record for the final jump from one stable version to the next.
+The changelog covers **stable-to-stable**. Betas are not represented. When you promote, draft the entry from the diff between the previous stable tag and `HEAD`, ignoring beta tag boundaries — they're just checkpoints along the way.
 
 ## Completion checklist
 
+### Beta release
+
+- [ ] Working tree is clean and the intended commit is on `main`
+- [ ] `npm run release:beta:patch` (or `:next`) completes successfully
+- [ ] GitHub `Desktop Release` workflow for the `v*-beta.N` tag is green
+- [ ] GitHub `Android APK Release` workflow for the same tag is green
+
+### Stable release (or promotion)
+
 - [ ] Run the pre-release sanity check (see above) and address any findings
 - [ ] Ensure the intended release commit is already committed and the git worktree is clean before running any `release:*` patch/promote command
 - [ ] Ensure local `npm run typecheck` passes on that exact commit before running any `release:*` patch/promote command
@@ -319,4 +417,5 @@ In other words, betas are checkpoints along the way; the changelog entry remains
 - [ ] `npm run release:patch` or `npm run release:promote` completes successfully
 - [ ] GitHub `Desktop Release` workflow for the `v*` tag is green
 - [ ] GitHub `Android APK Release` workflow for the same tag is green
-- [ ] EAS `release-mobile.yml` workflow for the same tag is green
+- [ ] EAS iOS production build for the same tag completes and submits via Fastlane
+- [ ] EAS Android production build for the same tag completes and auto-submits to the Play Store

docs/rpc-namespacing.md

@@ -11,7 +11,7 @@ The namespace reads left to right:
 
 - Domain: `checkout`
 - Provider or subsystem: `github`
-- Operation: `set_auto_merge`
+- Operation: `set_auto_merge`; this segment is a verb, not a noun. If you would name an RPC `noun.request`, name it `get_noun.request` instead.
 - Direction: `request` or `response`
 
 Use dots, not slashes. Dots are protocol namespaces; slashes imply paths or transport routing.

docs/testing.md

@@ -102,16 +102,18 @@ When a test is labeled end-to-end, it calls the real service. No environment var
 
 Vitest picks up tests by suffix. The suffix tells the runner which category it belongs to.
 
-| Suffix                | What it is                                                                                         | Where it runs                                                                        |
-| --------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| `*.test.ts(x)`        | Unit test — pure, fast, no daemon                                                                  | `npm run test:unit`                                                                  |
-| `*.posix.test.ts`     | Unit test that needs POSIX-only behavior                                                           | unit, skipped on Windows                                                             |
-| `*.browser.test.ts`   | App test that needs a real browser (DOM)                                                           | `npm run test:browser` (Vitest browser mode, Playwright provider, headless Chromium) |
-| `*.e2e.test.ts`       | End-to-end against a real daemon                                                                   | `npm run test:e2e`                                                                   |
-| `*.real.e2e.test.ts`  | E2E that hits a real provider (Claude/Codex/OpenCode) — needs creds in `packages/server/.env.test` | `npm run test:integration:real` / `test:e2e:real`                                    |
-| `*.local.e2e.test.ts` | E2E that needs a local-only resource                                                               | `npm run test:integration:local` / `test:e2e:local`                                  |
+| Suffix                | What it is                                                                                                    | Where it runs                                                                        |
+| --------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `*.test.ts(x)`        | Unit test — pure, fast, no daemon                                                                             | `npm run test:unit`                                                                  |
+| `*.posix.test.ts`     | Unit test that needs POSIX-only behavior                                                                      | unit, skipped on Windows                                                             |
+| `*.browser.test.ts`   | App test that needs a real browser (DOM)                                                                      | `npm run test:browser` (Vitest browser mode, Playwright provider, headless Chromium) |
+| `*.e2e.test.ts`       | End-to-end against a real daemon                                                                              | `npm run test:e2e`                                                                   |
+| `*.real.e2e.test.ts`  | E2E that hits a real provider (Claude/Codex/Copilot/OpenCode/Pi) — needs creds in `packages/server/.env.test` | `npm run test:integration:real` / `test:e2e:real`                                    |
+| `*.local.e2e.test.ts` | E2E that needs a local-only resource                                                                          | `npm run test:integration:local` / `test:e2e:local`                                  |
 
-App-level Playwright browser E2E lives in `packages/app/e2e/*.spec.ts` and runs via `npm run test:e2e --workspace=@getpaseo/app` (separate from Vitest E2E).
+App-level Playwright browser E2E lives in `packages/app/e2e/*.spec.ts` and runs via `npm run test:e2e --workspace=@getpaseo/app` (separate from Vitest E2E). App Playwright specs that hit real providers use `*.real.spec.ts` and run through `npm run test:e2e:real --workspace=@getpaseo/app`; the default app E2E project ignores that suffix so CI does not need provider credentials.
+
+Live provider smoke tests belong in `*.real.e2e.test.ts`, not `*.test.ts`, even when guarded by environment variables. Default unit suites must use deterministic provider adapters/fakes so missing credits, auth outages, and upstream model drift do not block normal CI.
 
 ### Test setup
 
@@ -127,7 +129,7 @@ Test suites in this repo are heavy. Running them in bulk freezes the machine, es
 - For a broad sweep, redirect to a file and read it after: `npx vitest run <path> --bail=1 > /tmp/test-output.txt 2>&1`
 - Never re-run a suite another agent already reported green.
 - For full-suite confidence, push to CI and check GitHub Actions.
-- Never run Playwright E2E (`packages/app/e2e/*.spec.ts`) locally — defer to CI.
+- Never run the full Playwright E2E suite locally — defer whole-suite verification to CI. Targeted Playwright specs are allowed when you changed or need to prove that specific flow.
 
 ## Agent authentication in tests
 
@@ -155,3 +157,12 @@ If code isn't testable, refactor it. Signs:
 - Setup requires too much global state
 
 Aim for deep modules: small interface, deep implementation. Fewer methods = fewer tests needed, simpler params = simpler setup.
+
+## Two test categories, no others
+
+Every test in this repo lives in exactly one of these shapes:
+
+1. **Unit tests with ports and adapters** — production code receives its real-world dependencies (DB, HTTP, CLI process, clock, randomness, filesystem, other modules) through an injected interface. Tests wire a typed in-memory fake colocated with the production module. **No `vi.mock`, `vi.hoisted`, `vi.spyOn` of own exports, JSDOM, `@testing-library` component mounting, RN test renderer, monkey-patched globals, or fake-server fixtures.** If a test needs any of those, the production module is missing a port — fix the seam, then write the test against a fake adapter.
+2. **Real end-to-end tests** — real daemon, real network, real browser (Playwright for app code) or a real isolated server instance (for daemon code). No JSDOM, no mocked transport.
+
+Anything in between — component tests in JSDOM, vitest tests that mock the module under test, tests that assert on private state — is slop on its way out.

docs/timeline-sync.md

@@ -0,0 +1,42 @@
+# Timeline sync
+
+Agent chat delivery has two paths:
+
+1. **Live stream** — `agent_stream` WebSocket messages for immediacy.
+2. **Authoritative history** — `fetch_agent_timeline_request` for correctness.
+
+The invariant is:
+
+> If the daemon has committed timeline rows for an agent, any connected client that opens or resumes that agent eventually displays every row through the daemon's current tail.
+
+## Presence is not delivery
+
+Client heartbeat reports presence:
+
+- device type
+- app visibility
+- focused agent
+- last activity time
+
+Heartbeat is used for notification routing. It must not be used as a correctness gate for `agent_stream` delivery. A stale mobile focus heartbeat may affect whether the user gets notified; it must not make timeline rows disappear from the live stream.
+
+## Catch-up is paged but complete
+
+Large unbounded timeline responses can exceed relay frame limits, so catch-up uses bounded pages. Bounded does not mean partial.
+
+When the app fetches `direction: "after"` and the daemon responds with `hasNewer: true`, the app must immediately fetch the next page from `endCursor`. The catch-up is complete only when `hasNewer: false`.
+
+The first load of an agent without a local cursor is different: it fetches a bounded latest tail page. Older history remains user-driven by scrolling upward.
+
+## Resume behavior
+
+When a client resumes with a known cursor, it catches up after that cursor to completion. It does not replace the view with a latest tail page, because tail pagination can skip the middle of a long background run.
+
+When a client resumes without a cursor, it fetches the latest tail page.
+
+## Relevant code
+
+- Server live stream forwarding: `packages/server/src/server/session.ts`
+- App sync planning: `packages/app/src/timeline/timeline-sync-plan.ts`
+- App stream/timeline reducer: `packages/app/src/timeline/session-stream-reducers.ts`
+- Session wiring: `packages/app/src/contexts/session-context.tsx`

docs/unistyles.md

@@ -4,15 +4,17 @@ This app uses [`react-native-unistyles` v3](https://www.unistyl.es/) for theme-a
 
 That model is powerful, but it has sharp edges. Use this note when adding theme-dependent styles.
 
-## STOP — `useUnistyles()` Is Forbidden
+## STOP — `useUnistyles()` Is Banned
 
-**Do not call `useUnistyles()` unless every alternative below has been ruled out and you can explain in a code comment why.** The library authors themselves [strongly advise against it](https://www.unistyl.es/v3/references/use-unistyles):
+**Do not call `useUnistyles()`. Anywhere. New code MUST NOT add a call; existing call sites are tolerated only because nobody has rewritten them yet and will be converted as they are touched.** The library authors themselves [strongly advise against it](https://www.unistyl.es/v3/references/use-unistyles):
 
 > We strongly recommend **not using** this hook, as it will re-render your component on every change. This hook was created to simplify the migration process and should only be used when other methods fail.
 
-We have hit this gotcha repeatedly in Paseo. It manifests as periodic, lockstep re-renders of warm subtrees (agent streams, panels, sidebars) even when nothing the user can see has changed — confirmed in profiling: `AgentStreamView` re-rendering constantly with `theme` showing as the only changed input on every render. The hook subscribes the component to **all** Unistyles runtime changes (theme, breakpoint, insets, color scheme, scale) and returns a fresh object reference each call, which also breaks every downstream `useMemo`/`memo` boundary that includes a derived theme value.
+We have hit this gotcha repeatedly in Paseo. The hook subscribes the component to **every** Unistyles runtime change (theme, breakpoint, insets, color scheme, scale) and returns a fresh object reference each call. That means a periodic lockstep re-render of warm subtrees (agent streams, panels, sidebars) even when nothing the user can see has changed — confirmed in profiling, with `theme` as the only changed input every cycle. It also breaks every downstream `useMemo`/`memo` boundary that includes a derived theme value.
 
-Before reaching for `useUnistyles()`, work down this list of alternatives in order:
+Reviewers MUST reject PRs that introduce a new `useUnistyles()` call. There is no last-resort carveout. If you cannot solve a case with the alternatives below, file an issue and stop — do not paper over it with the hook.
+
+Use these alternatives in order:
 
 ### 1. `StyleSheet.create((theme) => ...)` — default
 
@@ -46,31 +48,9 @@ const ThemedBlur = withUnistyles(BlurView);
 
 (Mind the `> *` child-selector leak documented further down.)
 
-### 4. Lift the read into a tiny leaf component
+### 4. There is no "last resort"
 
-If only one prop in a large component needs a theme value at runtime, extract a small leaf component that calls `useUnistyles()` and accept its re-renders in isolation. Never let a whole stream / panel / sidebar / virtualized list subscribe.
-
-### 5. (Last resort) `useUnistyles()`
-
-Only acceptable when both of:
-
-- (a) The value is consumed by a 3rd-party library that cannot be wrapped with `withUnistyles` (per the upstream "When to use it?" list), AND
-- (b) The component is small, leaf-level, and not on a hot render path.
-
-If you add a new `useUnistyles()` call, leave a comment on the line explaining which of (a)/(b) applies and why each higher-priority alternative was ruled out.
-
-### Hot-path forbidden list
-
-Do not introduce `useUnistyles()` in or above any of these subtrees — re-renders here are observably expensive:
-
-- `AgentStreamView` and anything it renders (message rows, tool calls, plan card, todo list, activity log, compaction marker, copy buttons)
-- `AgentPanel` body (`packages/app/src/panels/agent-panel.tsx`)
-- `Composer` and `MessageInput`
-- `WorkspaceScreen` shell, `WorkspaceDesktopTabsRow`, deck wrapper
-- `LeftSidebar` row items, `SidebarWorkspaceList`, `CommandCenter`
-- Anything inside a virtualized list (`@tanstack/react-virtual`, `FlashList`)
-
-Reviewers must reject PRs that add `useUnistyles()` calls in these areas without a written justification matching the last-resort criteria above.
+There is no escape hatch. If none of (1)–(3) fit, the problem is upstream — fix it there or file an issue. The hook is not on the table.
 
 ## How Updates Propagate
 
@@ -80,6 +60,34 @@ The important detail: the automatic native path tracks `props.style`. It does no
 
 [`useUnistyles()`](https://www.unistyl.es/v3/references/use-unistyles) is different. It gives React access to the current theme/runtime and can make a component re-render when those values change. Use it for values that must be rendered through React props, such as icon colors or small escape hatches. Do not expect direct reads from `UnistylesRuntime` to re-render a component; [issue #817](https://github.com/jpudysz/react-native-unistyles/issues/817) is a useful reminder of that invariant.
 
+## Dynamic Pixel Styles On Web
+
+Avoid feeding changing pixel values such as `{ top, left }`, `{ maxHeight }`, or `{ minWidth }` into the `style` prop of Unistyles-managed React Native components on web. The web runtime hashes each distinct style object by value and appends a CSS rule to `#unistyles-web`; those rules are not reclaimed during the page lifetime, so pointer-driven positioning can turn into steady stylesheet growth.
+
+Use the inline style escape hatch below for high-churn values. Do not split a component into plain/web/native variants just to keep one measured value out of the CSS registry. Raw DOM wrappers are reserved for real DOM infrastructure, such as terminal hosts, virtualized web rows, or third-party drag wrappers.
+
+## Inline Style Escape Hatch
+
+When a style value is high-churn and must bypass Unistyles' CSS registry, keep the component on the normal Unistyles path and mark only that style object with `inlineUnistylesStyle`.
+
+```tsx
+import { inlineUnistylesStyle } from "@/styles/unistyles-inline-style";
+
+const styles = StyleSheet.create({
+  thumb: {
+    position: "absolute",
+  },
+});
+
+<View style={[styles.thumb, inlineUnistylesStyle({ height, transform: [{ translateY }] })]} />;
+```
+
+This uses Unistyles' own animated-style lane: ordinary styles still become Unistyles classes, while the marked style object stays in React Native's inline style array. Use it for measured geometry, scroll or drag transforms, and pressed/hovered/open state where generating CSS classes is the wrong ownership boundary.
+
+Do not split a component into plain and Unistyles variants just to handle one high-churn value. The component remains a normal Unistyles component; only the specific style object escapes.
+
+When a reusable component has a prop whose whole job is dynamic geometry, make that prop the seam. For example, `FloatingSurface.frameStyle` and `FloatingScrollView.style` own their own escape hatch so menu, tooltip, hover-card, and combobox callers can stay declarative instead of knowing about Unistyles internals.
+
 ## Main Gotcha: `contentContainerStyle`
 
 `ScrollView.contentContainerStyle` is the canonical trap. It looks like a style prop, but it is not the same prop that Unistyles' remapped native component registers by default. The upstream tutorial calls this out directly in its [ScrollView Background Issue](https://www.unistyl.es/v3/tutorial/settings-screen#scrollview-background-issue) section.

flake.nix

@@ -36,7 +36,7 @@
           paseo = paseo;
         }
         // nixpkgs.lib.optionalAttrs isLinux {
-          desktop = pkgs.callPackage ./nix/desktop-package.nix { };
+          desktop = pkgs.callPackage ./nix/desktop-package.nix { inherit paseo; };
         }
       );
 

lefthook.yml

@@ -4,6 +4,7 @@ pre-commit:
     - name: format
       glob: "*.{css,js,json,jsonc,jsx,md,ts,tsx,yaml,yml}"
       exclude:
+        - "package-lock.json"
         - "**/package-lock.json"
       run: npm run format:check:files -- {staged_files}
     - name: lint

nix/desktop-package.nix

@@ -9,10 +9,11 @@
   makeDesktopItem,
   electron,
   libuv,
-  # Shares the daemon's npm-deps hash — same package-lock.json, same fetcher.
-  # Override via `.override { npmDepsHash = "..."; }` if your nixpkgs computes a
-  # different value.
-  npmDepsHash ? lib.fileContents ./npm-deps.hash,
+  # Reuse the daemon's prebuilt npm-deps FOD. Same lockfile, same content —
+  # without this, the desktop drv produces a separately-named store path
+  # (`paseo-desktop-<v>-npm-deps`) and refetches the entire registry. Override
+  # the upstream hash via `paseo.override { npmDepsHash = "..."; }`.
+  paseo,
 }:
 
 buildNpmPackage rec {
@@ -21,7 +22,8 @@ buildNpmPackage rec {
 
   src = lib.cleanSourceWith {
     src = ./..;
-    filter = path: type:
+    filter =
+      path: type:
       let
         baseName = builtins.baseNameOf path;
         relPath = lib.removePrefix (toString ./..) path;
@@ -42,7 +44,7 @@ buildNpmPackage rec {
   };
 
   nodejs = nodejs_22;
-  inherit npmDepsHash;
+  inherit (paseo) npmDeps;
 
   # Prevent onnxruntime-node's install script from running during automatic
   # npm rebuild. We manually rebuild only node-pty in buildPhase.
@@ -71,10 +73,10 @@ buildNpmPackage rec {
     # Native deps (terminal emulation; libuv-linked on Linux)
     npm rebuild node-pty
 
-    # Daemon workspaces (highlight + relay + server + cli)
-    npm run build:daemon
+    # Server workspaces (highlight + relay + protocol + client + server + cli)
+    npm run build:server
 
-    # App workspace deps not covered by build:daemon
+    # App workspace deps not covered by build:server
     npm run build --workspace=@getpaseo/expo-two-way-audio
 
     # Expo web export for the Electron renderer

nix/module.nix

@@ -124,6 +124,17 @@ in
         default = true;
         description = "Whether to use TLS when connecting to the relay. Used when `relay.mode = \"remote\"`.";
       };
+
+      publicUseTls = lib.mkOption {
+        type = lib.types.nullOr lib.types.bool;
+        default = null;
+        description = ''
+          Whether the public (client-facing) relay endpoint uses TLS.
+          When `null` (default), the daemon falls back to `relay.useTls`.
+          Override when the internal path is plain `ws://` behind a
+          TLS-terminating reverse proxy.
+        '';
+      };
     };
 
     inheritUserEnvironment = lib.mkOption {
@@ -135,8 +146,9 @@ in
 
         When Paseo runs as a real user (not the default system user), AI agents
         need access to the user's tools (git, ssh, etc.). This adds the user's
-        NixOS profile and system paths so agents can use them without manually
-        setting PATH.
+        NixOS profile, home-manager profile (`~/.nix-profile/bin` and
+        `~/.local/state/nix/profile/bin`), and system paths so agents can use
+        them without manually setting PATH.
 
         Enabled by default when `user` is set to a non-default value.
       '';
@@ -221,23 +233,39 @@ in
         NODE_ENV = "production";
         PASEO_HOME = cfg.dataDir;
         PASEO_LISTEN = "${cfg.listenAddress}:${toString cfg.port}";
-      } // lib.optionalAttrs cfg.inheritUserEnvironment {
-        # mkForce overrides the default PATH from NixOS's systemd module (which
-        # only includes store paths for coreutils/grep/sed/systemd). Our PATH
-        # includes /run/current-system/sw/bin which is a superset of those.
-        PATH = lib.mkForce (lib.concatStringsSep ":" [
-          "/etc/profiles/per-user/${cfg.user}/bin"
-          "/run/current-system/sw/bin"
-          "/run/wrappers/bin"
-          "/nix/var/nix/profiles/default/bin"
-        ]);
-      } // lib.optionalAttrs (cfg.hostnames == true) {
+      } // lib.optionalAttrs cfg.inheritUserEnvironment (
+        let
+          # Match dataDir's convention. We can't read users.users.<name>.home
+          # because the user may be managed outside NixOS.
+          userHome = "/home/${cfg.user}";
+        in {
+          # mkForce overrides the default PATH from NixOS's systemd module (which
+          # only includes store paths for coreutils/grep/sed/systemd). When the
+          # daemon runs as a real user, also include home-manager profile paths
+          # so user-installed CLIs (claude, opencode, codex, ...) are reachable
+          # by agent processes the daemon spawns.
+          PATH = lib.mkForce (lib.concatStringsSep ":" (
+            lib.optionals (cfg.user != "paseo") [
+              "${userHome}/.nix-profile/bin"
+              "${userHome}/.local/state/nix/profile/bin"
+            ]
+            ++ [
+              "/etc/profiles/per-user/${cfg.user}/bin"
+              "/run/current-system/sw/bin"
+              "/run/wrappers/bin"
+              "/nix/var/nix/profiles/default/bin"
+            ]
+          ));
+        }
+      ) // lib.optionalAttrs (cfg.hostnames == true) {
         PASEO_HOSTNAMES = "true";
       } // lib.optionalAttrs (lib.isList cfg.hostnames && cfg.hostnames != [ ]) {
         PASEO_HOSTNAMES = lib.concatStringsSep "," cfg.hostnames;
       } // lib.optionalAttrs (cfg.relay.enable && cfg.relay.mode == "remote") {
         PASEO_RELAY_ENDPOINT = "${cfg.relay.host}:${toString cfg.relay.port}";
         PASEO_RELAY_USE_TLS = if cfg.relay.useTls then "true" else "false";
+      } // lib.optionalAttrs (cfg.relay.enable && cfg.relay.mode == "remote" && cfg.relay.publicUseTls != null) {
+        PASEO_RELAY_PUBLIC_USE_TLS = if cfg.relay.publicUseTls then "true" else "false";
       } // cfg.environment;
 
       serviceConfig = {

nix/npm-deps.hash

@@ -1 +1 @@
-sha256-1NkvtCT9TelnukukDD+jkIbwxLbWiNeMbXtJIzhTzv0=
+sha256-PYbY3Lk9+y2byl1mN9dVO4YGXLEZrmnuPYxDw59LE5g=

nix/package.nix

@@ -79,8 +79,8 @@ buildNpmPackage rec {
     # degrade when unavailable.
     npm rebuild node-pty
 
-    # Build all daemon packages in dependency order (defined in package.json)
-    npm run build:daemon
+    # Build all server packages in dependency order (defined in package.json)
+    npm run build:server
 
     runHook postBuild
   '';
@@ -88,47 +88,25 @@ buildNpmPackage rec {
   installPhase = ''
     runHook preInstall
 
+    # Compute the daemon's runtime closure by static module-graph tracing
+    # (@vercel/nft from supervisor-entrypoint.js, cli/dist/index.js, and the
+    # forked terminal-worker-process.js) plus an explicit list of non-JS
+    # assets read at runtime. The trace script is the single source of
+    # truth for what the daemon needs at $out — auditable in plain JS, no
+    # npm hoisting / .bin / workspace-symlink footguns.
     mkdir -p $out/lib/paseo
+    node scripts/trace-daemon.mjs > daemon-files.txt
 
-    # Copy root package metadata
+    while IFS= read -r path; do
+      [ -z "$path" ] && continue
+      mkdir -p "$out/lib/paseo/$(dirname "$path")"
+      cp -a "$path" "$out/lib/paseo/$path"
+    done < daemon-files.txt
+
+    # Root package.json lets node resolve the workspace layout when the
+    # CLI/server bin starts from $out.
     cp package.json $out/lib/paseo/
 
-    # Copy node_modules (preserving workspace symlinks)
-    cp -a node_modules $out/lib/paseo/
-
-    # Auto-detect which @getpaseo/* packages were built by build:daemon
-    # (they'll have a dist/ directory). Copy those and remove the rest.
-    for link in $out/lib/paseo/node_modules/@getpaseo/*; do
-      name=$(basename "$link")
-      if [ -d "packages/$name/dist" ]; then
-        mkdir -p "$out/lib/paseo/packages/$name"
-        cp "packages/$name/package.json" "$out/lib/paseo/packages/$name/"
-        cp -a "packages/$name/dist" "$out/lib/paseo/packages/$name/"
-        if [ -d "packages/$name/node_modules" ]; then
-          cp -a "packages/$name/node_modules" "$out/lib/paseo/packages/$name/"
-        fi
-      else
-        rm -f "$link"
-      fi
-    done
-
-    # Copy CLI bin entry
-    mkdir -p $out/lib/paseo/packages/cli/bin
-    cp packages/cli/bin/paseo $out/lib/paseo/packages/cli/bin/
-
-    # Copy extra server files referenced at runtime
-    for f in agent-prompt.md .env.example; do
-      if [ -f packages/server/$f ]; then
-        cp packages/server/$f $out/lib/paseo/packages/server/
-      fi
-    done
-
-    # Copy server scripts (including supervisor-entrypoint) needed by CLI
-    if [ -d packages/server/dist/scripts ]; then
-      mkdir -p $out/lib/paseo/packages/server/dist/scripts
-      cp -a packages/server/dist/scripts/* $out/lib/paseo/packages/server/dist/scripts/
-    fi
-
     # Create wrapper for the server entry point (for systemd / direct use)
     mkdir -p $out/bin
     makeWrapper ${nodejs}/bin/node $out/bin/paseo-server \

package.json

@@ -1,6 +1,6 @@
 {
   "name": "paseo",
-  "version": "0.1.76",
+  "version": "0.1.86",
   "private": true,
   "description": "Paseo: voice-controlled development environment with OpenAI Realtime API",
   "keywords": [
@@ -24,6 +24,8 @@
   "workspaces": [
     "packages/expo-two-way-audio",
     "packages/highlight",
+    "packages/protocol",
+    "packages/client",
     "packages/server",
     "packages/app",
     "packages/relay",
@@ -34,16 +36,24 @@
   "scripts": {
     "dev": "./scripts/dev.sh",
     "dev:win": "powershell ./scripts/dev.ps1",
-    "dev:server": "npm run dev --workspace=@getpaseo/server",
+    "dev:server": "npm run build:server-deps && concurrently --kill-others --names protocol,client,server --prefix-colors yellow,blue,cyan \"npm run watch:protocol\" \"npm run watch:client\" \"npm run dev:server:raw\"",
+    "dev:server:raw": "npm run dev --workspace=@getpaseo/server",
     "dev:app": "npm run start --workspace=@getpaseo/app",
     "dev:website": "npm run dev --workspace=@getpaseo/website",
     "postinstall": "node scripts/postinstall-patches.mjs",
     "prepare": "lefthook install --force",
     "build": "npm run build --workspaces --if-present",
     "build:highlight": "npm run build --workspace=@getpaseo/highlight",
-    "build:daemon": "npm run build --workspace=@getpaseo/highlight && npm run build --workspace=@getpaseo/relay && npm run build --workspace=@getpaseo/server && npm run build --workspace=@getpaseo/cli",
+    "build:relay": "npm run build --workspace=@getpaseo/relay",
+    "build:protocol": "npm run build --workspace=@getpaseo/protocol",
+    "build:client": "npm run build:protocol && npm run build --workspace=@getpaseo/client",
+    "build:server-deps": "npm run build:highlight && npm run build:relay && npm run build:client",
+    "build:server": "npm run build:server-deps && npm run build --workspace=@getpaseo/server && npm run build --workspace=@getpaseo/cli",
+    "build:app-deps": "npm run build:highlight && npm run build:client && npm run build --workspace=@getpaseo/expo-two-way-audio",
+    "watch:protocol": "tsc -p packages/protocol/tsconfig.json --watch --preserveWatchOutput",
+    "watch:client": "tsc -p packages/client/tsconfig.json --watch --preserveWatchOutput",
     "typecheck": "npm run typecheck --workspaces --if-present",
-    "typecheck:daemon": "npm run typecheck --workspace=@getpaseo/relay && npm run typecheck --workspace=@getpaseo/server && npm run typecheck --workspace=@getpaseo/cli",
+    "typecheck:server": "npm run typecheck --workspace=@getpaseo/relay && npm run typecheck --workspace=@getpaseo/protocol && npm run typecheck --workspace=@getpaseo/client && npm run typecheck --workspace=@getpaseo/server && npm run typecheck --workspace=@getpaseo/cli",
     "test": "npm run test --workspaces --if-present",
     "format": "oxfmt .",
     "format:files": "oxfmt",
@@ -63,7 +73,7 @@
     "web": "npm run web --workspace=@getpaseo/app",
     "dev:desktop": "npm run dev --workspace=@getpaseo/desktop",
     "dev:win:desktop": "npm run dev:win --workspace=@getpaseo/desktop",
-    "build:desktop": "npm run build:workspace-deps --workspace=@getpaseo/app && cd packages/app && cross-env PASEO_WEB_PLATFORM=electron npx expo export --platform web && cd ../.. && npm run build --workspace=@getpaseo/desktop --",
+    "build:desktop": "npm run build:app-deps && npm run build:server-deps && npm run build --workspace=@getpaseo/server && cd packages/app && cross-env PASEO_WEB_PLATFORM=electron npx expo export --platform web && cd ../.. && npm run build --workspace=@getpaseo/desktop --",
     "db:query": "npm run db:query --workspace=@getpaseo/server --",
     "cli": "npx tsx packages/cli/src/index.js",
     "version": "npm run version:sync-internal && npm run release:prepare && git add -A",
@@ -77,9 +87,9 @@
     "version:all:beta:major": "node scripts/set-release-version.mjs --mode beta-major",
     "version:all:beta:next": "node scripts/set-release-version.mjs --mode beta-next",
     "version:all:promote": "node scripts/set-release-version.mjs --mode promote",
-    "release:check": "npm run release:prepare && npm run typecheck --workspace=@getpaseo/highlight && npm run build --workspace=@getpaseo/highlight && npm run typecheck --workspace=@getpaseo/relay && npm run build --workspace=@getpaseo/relay && npm run typecheck --workspace=@getpaseo/server && npm run build --workspace=@getpaseo/server && npm run typecheck --workspace=@getpaseo/cli && npm run build --workspace=@getpaseo/cli && npm pack --dry-run --workspace=@getpaseo/highlight && npm pack --dry-run --workspace=@getpaseo/relay && npm pack --dry-run --workspace=@getpaseo/server && npm pack --dry-run --workspace=@getpaseo/cli",
-    "release:publish:dry-run": "npm publish --dry-run --workspace=@getpaseo/highlight --access public && npm publish --dry-run --workspace=@getpaseo/relay --access public && npm publish --dry-run --workspace=@getpaseo/server --access public && npm publish --dry-run --workspace=@getpaseo/cli --access public",
-    "release:publish": "npm publish --workspace=@getpaseo/highlight --access public && npm publish --workspace=@getpaseo/relay --access public && npm publish --workspace=@getpaseo/server --access public && npm publish --workspace=@getpaseo/cli --access public",
+    "release:check": "npm run release:prepare && npm run typecheck --workspace=@getpaseo/highlight && npm run typecheck --workspace=@getpaseo/relay && npm run typecheck --workspace=@getpaseo/protocol && npm run build:client && npm run typecheck --workspace=@getpaseo/client && npm run build:server && npm run typecheck --workspace=@getpaseo/server && npm run typecheck --workspace=@getpaseo/cli && npm pack --dry-run --workspace=@getpaseo/highlight && npm pack --dry-run --workspace=@getpaseo/relay && npm pack --dry-run --workspace=@getpaseo/protocol && npm pack --dry-run --workspace=@getpaseo/client && npm pack --dry-run --workspace=@getpaseo/server && npm pack --dry-run --workspace=@getpaseo/cli",
+    "release:publish:dry-run": "npm publish --dry-run --workspace=@getpaseo/highlight --access public && npm publish --dry-run --workspace=@getpaseo/relay --access public && npm publish --dry-run --workspace=@getpaseo/protocol --access public && npm publish --dry-run --workspace=@getpaseo/client --access public && npm publish --dry-run --workspace=@getpaseo/server --access public && npm publish --dry-run --workspace=@getpaseo/cli --access public",
+    "release:publish": "npm publish --workspace=@getpaseo/highlight --access public && npm publish --workspace=@getpaseo/relay --access public && npm publish --workspace=@getpaseo/protocol --access public && npm publish --workspace=@getpaseo/client --access public && npm publish --workspace=@getpaseo/server --access public && npm publish --workspace=@getpaseo/cli --access public",
     "release:push": "node scripts/push-current-release-tag.mjs",
     "release:beta:patch": "npm run release:check && npm run version:all:beta:patch && npm run release:push",
     "release:beta:minor": "npm run release:check && npm run version:all:beta:minor && npm run release:push",
@@ -93,6 +103,7 @@
   "devDependencies": {
     "@types/ws": "^8.5.14",
     "@typescript/native-preview": "7.0.0-dev.20260423.1",
+    "@vercel/nft": "^1.5.0",
     "concurrently": "^9.2.1",
     "cross-env": "^10.1.0",
     "get-port-cli": "^3.0.0",

packages/app/.eas/workflows/release-mobile.yml

@@ -41,7 +41,7 @@ jobs:
 
   submit_ios_for_review:
     name: Submit iOS for App Store review
-    needs: [submit_ios]
+    needs: [build_ios, submit_ios]
     environment: production
     runs_on: macos-medium
     steps:
@@ -49,4 +49,7 @@ jobs:
       - name: Install fastlane
         run: bundle install
       - name: Submit for review
-        run: bundle exec fastlane ios submit_review
+        run: |
+          export APP_VERSION="${{ needs.build_ios.outputs.app_version }}"
+          export APP_BUILD_VERSION="${{ needs.build_ios.outputs.app_build_version }}"
+          bundle exec fastlane ios submit_review

packages/app/.eas/workflows/resubmit-ios-review.yml

@@ -1,12 +1,21 @@
 name: Resubmit iOS for App Store review
 
 # Standalone re-trigger for the App Store review submission step. The iOS
-# binary is already uploaded to TestFlight via the main release-mobile flow;
-# this workflow just runs the fastlane submit_review lane against the latest
-# TestFlight build, without rebuilding or re-uploading.
+# binary is already uploaded to TestFlight via the EAS GitHub app's tag-push
+# build; this workflow just runs the fastlane submit_review lane against the
+# latest TestFlight build, without rebuilding or re-uploading.
 
 on:
-  workflow_dispatch: {}
+  workflow_dispatch:
+    inputs:
+      app_version:
+        type: string
+        required: false
+        description: "Marketing version to resubmit, e.g. 0.1.76. Leave empty to target the most recently uploaded iOS build."
+      app_build_version:
+        type: string
+        required: false
+        description: "CFBundleVersion to resubmit, e.g. 2. Only used when app_version is set."
 
 jobs:
   submit_ios_for_review:
@@ -18,4 +27,7 @@ jobs:
       - name: Install fastlane
         run: bundle install
       - name: Submit for review
-        run: bundle exec fastlane ios submit_review
+        run: |
+          export APP_VERSION="${{ inputs.app_version }}"
+          export APP_BUILD_VERSION="${{ inputs.app_build_version }}"
+          bundle exec fastlane ios submit_review

packages/app/Gemfile

@@ -1,3 +1,3 @@
 source "https://rubygems.org"
 
-gem "fastlane"
+gem "fastlane", "~> 2.234"

packages/app/e2e/00-sessions-empty.spec.ts

@@ -2,15 +2,12 @@
 // Sessions history is daemon-global — any agent created by a prior spec hides the empty state.
 // If the beforeAll probe below fails, a spec sorted before this file is creating agents.
 import { test } from "./fixtures";
-import {
-  connectArchiveTabDaemonClient,
-  expectSessionsEmptyState,
-  openSessions,
-} from "./helpers/archive-tab";
+import { connectSeedClient } from "./helpers/seed-client";
+import { expectSessionsEmptyState, openSessions } from "./helpers/archive-tab";
 
 test.describe("Sessions screen empty state", () => {
   test.beforeAll(async () => {
-    const client = await connectArchiveTabDaemonClient();
+    const client = await connectSeedClient();
     try {
       const history = await client.fetchAgentHistory({ page: { limit: 1 } });
       if (history.entries.length > 0) {

packages/app/e2e/acp-provider-catalog.spec.ts

@@ -1,5 +1,6 @@
 import { test } from "./fixtures";
 import { gotoAppShell, openSettings } from "./helpers/app";
+import { getServerId } from "./helpers/server-id";
 import {
   expectProviderInstalledInSettings,
   installAcpCatalogProvider,
@@ -12,19 +13,11 @@ const ACP_PROVIDER = {
   name: "Hermes",
 };
 
-function getSeededServerId(): string {
-  const serverId = process.env.E2E_SERVER_ID;
-  if (!serverId) {
-    throw new Error("E2E_SERVER_ID is not set (expected from Playwright globalSetup).");
-  }
-  return serverId;
-}
-
 test.describe("ACP provider catalog", () => {
   test("adds a catalog provider from settings", async ({ page }) => {
     await gotoAppShell(page);
     await openSettings(page);
-    await openSettingsHost(page, getSeededServerId());
+    await openSettingsHost(page, getServerId());
     await openAddProviderModal(page);
 
     await installAcpCatalogProvider(page, ACP_PROVIDER.name);

packages/app/e2e/archive-tab.spec.ts

@@ -1,12 +1,12 @@
 import { randomUUID } from "node:crypto";
 import { test } from "./fixtures";
+import { connectSeedClient } from "./helpers/seed-client";
 import { createTempGitRepo } from "./helpers/workspace";
 import {
   archiveAgentFromDaemon,
   archiveAgentFromSessions,
   clickSessionRow,
   closeWorkspaceAgentTab,
-  connectArchiveTabDaemonClient,
   createIdleAgent,
   expectArchivedAgentFocused,
   expectSessionRowArchived,
@@ -21,14 +21,14 @@ import {
 } from "./helpers/archive-tab";
 
 test.describe("Archive tab reconciliation", () => {
-  let client: Awaited<ReturnType<typeof connectArchiveTabDaemonClient>>;
+  let client: Awaited<ReturnType<typeof connectSeedClient>>;
   let tempRepo: { path: string; cleanup: () => Promise<void> };
 
   test.describe.configure({ timeout: 300_000 });
 
   test.beforeAll(async () => {
     tempRepo = await createTempGitRepo("archive-tab-");
-    client = await connectArchiveTabDaemonClient();
+    client = await connectSeedClient();
   });
 
   test.afterAll(async () => {

packages/app/e2e/client-slash-commands.spec.ts

@@ -0,0 +1,148 @@
+import { expect, test, type Page } from "./fixtures";
+import { composerLocator, expectComposerVisible, submitMessage } from "./helpers/composer";
+import { openAgentRoute, seedMockAgentWorkspace } from "./helpers/mock-agent";
+import {
+  expectSessionRowArchived,
+  expectWorkspaceTabHidden,
+  expectWorkspaceTabVisible,
+  openSessions,
+} from "./helpers/archive-tab";
+
+interface SlashCommandScenario {
+  agentId: string;
+  title: string;
+}
+
+const REPLACEMENT_PROMPT = "Replacement prompt after slash clear.";
+
+async function withOpenReadyMockAgent(
+  page: Page,
+  input: {
+    title: string;
+    model?: string;
+    modeId?: string;
+  },
+  run: (scenario: SlashCommandScenario) => Promise<void>,
+): Promise<void> {
+  const session = await seedMockAgentWorkspace({
+    repoPrefix: "client-slash-command-",
+    title: input.title,
+    model: input.model,
+    modeId: input.modeId,
+    initialPrompt: "Prepare a client slash command test agent.",
+  });
+
+  try {
+    await openAgentRoute(page, session);
+    await expectWorkspaceTabVisible(page, session.agentId);
+    await expectComposerVisible(page);
+
+    await run({ agentId: session.agentId, title: input.title });
+  } finally {
+    await session.cleanup();
+  }
+}
+
+async function runClientSlashCommand(page: Page, command: "/quit" | "/clear"): Promise<void> {
+  const input = composerLocator(page);
+  await expect(input).toBeEditable({ timeout: 30_000 });
+  await input.fill(command);
+  await expect(input).toHaveValue(command);
+  await input.press("Enter");
+}
+
+async function selectClientSlashCommand(page: Page, query: string, label: string): Promise<void> {
+  const input = composerLocator(page);
+  await expect(input).toBeEditable({ timeout: 30_000 });
+  await input.fill(query);
+  await expect(page.getByText(label, { exact: true }).first()).toBeVisible({ timeout: 30_000 });
+  await input.press("Enter");
+}
+
+async function expectAgentArchivedInSessions(page: Page, title: string): Promise<void> {
+  await openSessions(page);
+  await expectSessionRowArchived(page, title);
+}
+
+async function expectReplacementDraftMatchesPreviousSetup(page: Page): Promise<void> {
+  await expectComposerVisible(page);
+  await expect(
+    page.getByRole("button", { name: "Select model (Ten second stream)" }),
+  ).toBeVisible();
+  await expect(page.getByRole("button", { name: "Select agent mode (Load test)" })).toBeVisible();
+}
+
+async function createAgentFromReplacementDraft(page: Page): Promise<void> {
+  await submitMessage(page, REPLACEMENT_PROMPT);
+}
+
+async function waitForReplacementAgentId(page: Page, oldAgentId: string): Promise<string> {
+  let newAgentId: string | null = null;
+  await expect
+    .poll(
+      async () => {
+        const ids = await page
+          .locator('[data-testid^="workspace-tab-agent_"]')
+          .evaluateAll((nodes) =>
+            nodes.flatMap((node) => {
+              if (!(node instanceof HTMLElement)) {
+                return [];
+              }
+              const testId = node.getAttribute("data-testid") ?? "";
+              if (!testId.startsWith("workspace-tab-agent_")) {
+                return [];
+              }
+              if (node.offsetParent === null) {
+                return [];
+              }
+              return [testId.slice("workspace-tab-agent_".length)];
+            }),
+          );
+        newAgentId = ids.find((id) => id !== oldAgentId) ?? null;
+        return newAgentId;
+      },
+      { timeout: 30_000 },
+    )
+    .not.toBeNull();
+  if (!newAgentId) {
+    throw new Error("Replacement agent was not created.");
+  }
+  return newAgentId;
+}
+
+test.describe("Client slash commands", () => {
+  test("slash quit archives the active agent and removes its tab", async ({ page }) => {
+    await withOpenReadyMockAgent(page, { title: "Slash quit e2e" }, async ({ agentId, title }) => {
+      await runClientSlashCommand(page, "/quit");
+      await expectWorkspaceTabHidden(page, agentId);
+      await expectAgentArchivedInSessions(page, title);
+    });
+  });
+
+  test("slash quit selected from autocomplete archives immediately", async ({ page }) => {
+    await withOpenReadyMockAgent(
+      page,
+      { title: "Slash quit autocomplete e2e" },
+      async ({ agentId, title }) => {
+        await selectClientSlashCommand(page, "/qu", "/exit");
+        await expectWorkspaceTabHidden(page, agentId);
+        await expectAgentArchivedInSessions(page, title);
+      },
+    );
+  });
+
+  test("slash clear replaces the active agent with a matching draft", async ({ page }) => {
+    await withOpenReadyMockAgent(
+      page,
+      { title: "Slash clear e2e", model: "ten-second-stream", modeId: "load-test" },
+      async ({ agentId, title }) => {
+        await runClientSlashCommand(page, "/clear");
+        await expectWorkspaceTabHidden(page, agentId);
+        await expectReplacementDraftMatchesPreviousSetup(page);
+        await createAgentFromReplacementDraft(page);
+        await waitForReplacementAgentId(page, agentId);
+        await expectAgentArchivedInSessions(page, title);
+      },
+    );
+  });
+});

packages/app/e2e/codex-plan-approval.spec.ts

@@ -1,16 +1,6 @@
 import { expect, test } from "./fixtures";
-import { buildHostWorkspaceRoute } from "@/utils/host-routes";
 import { allowPermission, waitForPermissionPrompt } from "./helpers/permissions";
-import { connectTerminalClient } from "./helpers/terminal-perf";
-import { createTempGitRepo } from "./helpers/workspace";
-
-function getServerId(): string {
-  const serverId = process.env.E2E_SERVER_ID;
-  if (!serverId) {
-    throw new Error("E2E_SERVER_ID is not set.");
-  }
-  return serverId;
-}
+import { openAgentRoute, seedMockAgentWorkspace } from "./helpers/mock-agent";
 
 test.describe("Codex plan approval", () => {
   test("shows a single actionable plan panel and removes it after implementation starts", async ({
@@ -18,29 +8,14 @@ test.describe("Codex plan approval", () => {
   }) => {
     test.setTimeout(180_000);
 
-    const repo = await createTempGitRepo("codex-plan-approval-");
-    const client = await connectTerminalClient();
+    const session = await seedMockAgentWorkspace({
+      repoPrefix: "codex-plan-approval-",
+      title: "Codex plan approval e2e",
+      initialPrompt: "Emit synthetic plan approval.",
+    });
 
     try {
-      const workspaceResult = await client.openProject(repo.path);
-      if (!workspaceResult.workspace) {
-        throw new Error(workspaceResult.error ?? `Failed to open project ${repo.path}`);
-      }
-
-      const agent = await client.createAgent({
-        provider: "mock",
-        cwd: repo.path,
-        title: "Codex plan approval e2e",
-        modeId: "load-test",
-        model: "ten-second-stream",
-        initialPrompt: "Emit synthetic plan approval.",
-      });
-
-      const agentUrl = `${buildHostWorkspaceRoute(
-        getServerId(),
-        repo.path,
-      )}?open=${encodeURIComponent(`agent:${agent.id}`)}`;
-      await page.goto(agentUrl);
+      await openAgentRoute(page, session);
 
       await waitForPermissionPrompt(page, 120_000);
 
@@ -54,8 +29,7 @@ test.describe("Codex plan approval", () => {
       });
       await expect(page.getByTestId("timeline-plan-card")).toHaveCount(0);
     } finally {
-      await client.close();
-      await repo.cleanup();
+      await session.cleanup();
     }
   });
 });

packages/app/e2e/composer-attachments.spec.ts

@@ -23,16 +23,12 @@ import {
   expectGithubAttachmentPill,
   openGithubWorkspace,
 } from "./helpers/composer";
-import {
-  connectNewWorkspaceDaemonClient,
-  delayBrowserAgentCreatedStatus,
-  openNewWorkspaceComposer,
-  openProjectViaDaemon,
-} from "./helpers/new-workspace";
+import { delayBrowserAgentCreatedStatus, openNewWorkspaceComposer } from "./helpers/new-workspace";
 import { gotoAppShell } from "./helpers/app";
 import { waitForSidebarHydration, switchWorkspaceViaSidebar } from "./helpers/workspace-ui";
-import { createTempGitRepo } from "./helpers/workspace";
+import { seedWorkspace } from "./helpers/seed-client";
 import { hasGithubAuth, createTempGithubRepo } from "./helpers/github-fixtures";
+import { getServerId } from "./helpers/server-id";
 
 const MINIMAL_PNG = Buffer.from(
   "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
@@ -237,27 +233,23 @@ test.describe("Composer attachments", () => {
 
   test("composer is locked while new workspace agent is being created", async ({ page }) => {
     test.setTimeout(120_000);
-    const serverId = process.env.E2E_SERVER_ID;
-    if (!serverId) throw new Error("E2E_SERVER_ID is not set.");
+    const serverId = getServerId();
 
-    const repo = await createTempGitRepo("attach-lock-");
     const agentCreatedDelay = await delayBrowserAgentCreatedStatus(page);
-    const daemonClient = await connectNewWorkspaceDaemonClient();
+    const workspace = await seedWorkspace({ repoPrefix: "attach-lock-" });
 
     try {
-      const openedProject = await openProjectViaDaemon(daemonClient, repo.path);
-
       await gotoAppShell(page);
       await waitForSidebarHydration(page);
       await switchWorkspaceViaSidebar({
         page,
         serverId,
-        targetWorkspacePath: openedProject.workspaceId,
+        targetWorkspacePath: workspace.workspaceId,
       });
 
       await openNewWorkspaceComposer(page, {
-        projectKey: openedProject.projectKey,
-        projectDisplayName: openedProject.projectDisplayName,
+        projectKey: workspace.projectId,
+        projectDisplayName: workspace.projectDisplayName,
       });
       await fillComposerDraft(page, "lock test prompt");
       const createButton = page
@@ -277,8 +269,7 @@ test.describe("Composer attachments", () => {
       await expectComposerEditable(page);
     } finally {
       agentCreatedDelay.release();
-      await daemonClient.close().catch(() => undefined);
-      await repo.cleanup();
+      await workspace.cleanup();
     }
   });
 });

packages/app/e2e/composer-autocomplete.spec.ts

@@ -0,0 +1,483 @@
+import { expect, test, type Page } from "./fixtures";
+import { composerLocator, expectComposerVisible } from "./helpers/composer";
+import { openAgentRoute, seedMockAgentWorkspace } from "./helpers/mock-agent";
+import { expectWorkspaceTabVisible } from "./helpers/archive-tab";
+import { daemonWsRoutePattern } from "./helpers/daemon-port";
+
+const TEST_COMMANDS = [
+  {
+    name: "tdd",
+    description: "Write a red test, verify it fails for the right reason, implement to green",
+    argumentHint: "",
+  },
+  {
+    name: "help",
+    description: "Show help for the current agent session and available slash commands",
+    argumentHint: "",
+  },
+  {
+    name: "hello",
+    description: "Insert a friendly greeting prompt into the current composer",
+    argumentHint: "",
+  },
+  {
+    name: "heapdump",
+    description: "Dump the JavaScript heap for local desktop debugging",
+    argumentHint: "",
+  },
+  {
+    name: "health",
+    description: "Show runtime health checks and connection diagnostics",
+    argumentHint: "",
+  },
+  {
+    name: "history",
+    description: "Summarize recent session history",
+    argumentHint: "",
+  },
+  {
+    name: "handoff",
+    description: "Prepare a complete handoff note for another agent",
+    argumentHint: "[agent]",
+  },
+  {
+    name: "hover",
+    description: "Audit hover behavior in desktop web surfaces",
+    argumentHint: "",
+  },
+  {
+    name: "harness",
+    description: "Inspect the local test harness configuration",
+    argumentHint: "",
+  },
+  {
+    name: "hydrate",
+    description: "Refresh persisted state used by the current workspace",
+    argumentHint: "",
+  },
+  {
+    name: "highlight",
+    description: "Highlight important changes in the active diff",
+    argumentHint: "",
+  },
+  {
+    name: "home",
+    description: "Navigate back to the workspace home surface",
+    argumentHint: "",
+  },
+  {
+    name: "host",
+    description: "Inspect host connection metadata",
+    argumentHint: "",
+  },
+] as const;
+
+interface PopoverFrame {
+  exists: boolean;
+  top: number;
+  bottom: number;
+  height: number;
+  opacity: number;
+  display: string;
+  visibility: string;
+  timestamp: number;
+}
+
+interface PopoverFrameRecorderWindow extends Window {
+  __composerAutocompleteFrames?: PopoverFrame[];
+  __stopComposerAutocompleteFrameRecorder?: () => void;
+}
+
+async function getTopTestIdAtPoint(page: Page, x: number, y: number) {
+  return page.evaluate(
+    ([pointX, pointY]) => {
+      const element = document.elementFromPoint(pointX, pointY);
+      return element?.closest("[data-testid]")?.getAttribute("data-testid") ?? null;
+    },
+    [x, y],
+  );
+}
+
+async function installListCommandsStub(page: Page): Promise<void> {
+  await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
+    const server = ws.connectToServer();
+
+    ws.onMessage((message) => {
+      server.send(message);
+    });
+
+    server.onMessage((message) => {
+      if (typeof message !== "string") {
+        ws.send(message);
+        return;
+      }
+
+      try {
+        const parsed = JSON.parse(message) as {
+          type?: string;
+          message?: {
+            type?: string;
+            payload?: {
+              commands?: unknown;
+              error?: string | null;
+            };
+          };
+        };
+        if (
+          parsed.type === "session" &&
+          parsed.message?.type === "list_commands_response" &&
+          parsed.message.payload
+        ) {
+          parsed.message.payload.commands = TEST_COMMANDS;
+          parsed.message.payload.error = null;
+          ws.send(JSON.stringify(parsed));
+          return;
+        }
+      } catch {
+        // Forward non-JSON frames unchanged.
+      }
+
+      ws.send(message);
+    });
+  });
+}
+
+async function openReadyMockAgent(
+  page: Page,
+  options?: { expectWorkspaceTab?: boolean },
+): Promise<{
+  cleanup: () => Promise<void>;
+}> {
+  const session = await seedMockAgentWorkspace({
+    repoPrefix: "autocomplete-popover-",
+    title: "Autocomplete popover regression",
+  });
+
+  try {
+    await openAgentRoute(page, session);
+    if (options?.expectWorkspaceTab !== false) {
+      await expectWorkspaceTabVisible(page, session.agentId);
+    }
+    await expectComposerVisible(page);
+    return { cleanup: session.cleanup };
+  } catch (error) {
+    await session.cleanup();
+    throw error;
+  }
+}
+
+async function visiblePopoverBox(
+  page: Page,
+): Promise<{ top: number; bottom: number; height: number }> {
+  const popover = page.getByTestId("composer-autocomplete-popover");
+  await expect(popover).toBeVisible({ timeout: 30_000 });
+  await expect
+    .poll(
+      async () =>
+        popover.evaluate((element) => {
+          const style = window.getComputedStyle(element);
+          return Number(style.opacity);
+        }),
+      { timeout: 30_000 },
+    )
+    .toBeGreaterThan(0.95);
+  const box = await popover.boundingBox();
+  if (!box) {
+    throw new Error("Autocomplete popover did not produce a bounding box.");
+  }
+  return {
+    top: box.y,
+    bottom: box.y + box.height,
+    height: box.height,
+  };
+}
+
+async function startPopoverFrameRecorder(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    const win = window as PopoverFrameRecorderWindow;
+    win.__composerAutocompleteFrames = [];
+    let active = true;
+
+    const record = () => {
+      if (!active) return;
+
+      const element = document.querySelector('[data-testid="composer-autocomplete-popover"]');
+      if (element instanceof HTMLElement) {
+        const rect = element.getBoundingClientRect();
+        const style = window.getComputedStyle(element);
+        win.__composerAutocompleteFrames?.push({
+          exists: true,
+          top: rect.top,
+          bottom: rect.bottom,
+          height: rect.height,
+          opacity: Number(style.opacity),
+          display: style.display,
+          visibility: style.visibility,
+          timestamp: performance.now(),
+        });
+      } else {
+        win.__composerAutocompleteFrames?.push({
+          exists: false,
+          top: 0,
+          bottom: 0,
+          height: 0,
+          opacity: 0,
+          display: "none",
+          visibility: "hidden",
+          timestamp: performance.now(),
+        });
+      }
+
+      window.requestAnimationFrame(record);
+    };
+
+    win.__stopComposerAutocompleteFrameRecorder = () => {
+      active = false;
+    };
+    window.requestAnimationFrame(record);
+  });
+}
+
+async function stopPopoverFrameRecorder(page: Page): Promise<PopoverFrame[]> {
+  return page.evaluate(() => {
+    const win = window as PopoverFrameRecorderWindow;
+    win.__stopComposerAutocompleteFrameRecorder?.();
+    return win.__composerAutocompleteFrames ?? [];
+  });
+}
+
+function visiblePopoverFrames(frames: PopoverFrame[]): PopoverFrame[] {
+  return frames.filter(
+    (frame) =>
+      frame.exists &&
+      frame.height > 0 &&
+      frame.opacity > 0.95 &&
+      frame.display !== "none" &&
+      frame.visibility !== "hidden",
+  );
+}
+
+function formatFrame(frame: PopoverFrame | undefined): string {
+  if (!frame) return "none";
+  return JSON.stringify({
+    top: Math.round(frame.top),
+    bottom: Math.round(frame.bottom),
+    height: Math.round(frame.height),
+    opacity: frame.opacity,
+  });
+}
+
+function expectPopoverFramesStable(frames: PopoverFrame[]): void {
+  const visibleFrames = visiblePopoverFrames(frames);
+  expect(visibleFrames.length).toBeGreaterThan(0);
+
+  const finalFrame = visibleFrames[visibleFrames.length - 1];
+  const jumpingFrame = visibleFrames.find(
+    (frame) =>
+      Math.abs(frame.top - finalFrame.top) > 4 ||
+      Math.abs(frame.bottom - finalFrame.bottom) > 4 ||
+      Math.abs(frame.height - finalFrame.height) > 4,
+  );
+
+  expect(
+    jumpingFrame,
+    `expected first visible popover paint to be stable; first=${formatFrame(
+      visibleFrames[0],
+    )} jumping=${formatFrame(jumpingFrame)} final=${formatFrame(finalFrame)}`,
+  ).toBeUndefined();
+}
+
+function expectPopoverDoesNotDisappearAfterFirstVisible(frames: PopoverFrame[]): void {
+  const firstVisibleIndex = frames.findIndex(
+    (frame) =>
+      frame.exists &&
+      frame.height > 0 &&
+      frame.opacity > 0.95 &&
+      frame.display !== "none" &&
+      frame.visibility !== "hidden",
+  );
+  expect(firstVisibleIndex).toBeGreaterThanOrEqual(0);
+
+  const hiddenFrame = frames
+    .slice(firstVisibleIndex)
+    .find((frame) => !frame.exists || frame.opacity < 0.95);
+  expect(
+    hiddenFrame,
+    `expected mounted popover to stay visible while filtering; hidden=${formatFrame(hiddenFrame)}`,
+  ).toBeUndefined();
+}
+
+test.describe("Composer autocomplete", () => {
+  test("does not flash at the wrong position on the first slash command paint", async ({
+    page,
+  }) => {
+    await installListCommandsStub(page);
+    const agent = await openReadyMockAgent(page);
+
+    try {
+      const input = composerLocator(page);
+      await expect(input).toBeEditable({ timeout: 30_000 });
+      await input.click();
+
+      await startPopoverFrameRecorder(page);
+      await page.keyboard.type("/");
+      await expect(page.getByText("/help", { exact: true })).toBeVisible({ timeout: 30_000 });
+      await page.waitForTimeout(250);
+      const frames = await stopPopoverFrameRecorder(page);
+
+      expectPopoverFramesStable(frames);
+    } finally {
+      await agent.cleanup();
+    }
+  });
+
+  test("does not jump when deleting a slash command search", async ({ page }) => {
+    await installListCommandsStub(page);
+    const agent = await openReadyMockAgent(page);
+
+    try {
+      const input = composerLocator(page);
+      await expect(input).toBeEditable({ timeout: 30_000 });
+
+      await input.fill("/he");
+      const popover = page.getByTestId("composer-autocomplete-popover");
+      await expect(popover.getByText("/help", { exact: true }).first()).toBeVisible({
+        timeout: 30_000,
+      });
+      const beforeDelete = await visiblePopoverBox(page);
+
+      await input.press("Backspace");
+      await expect(input).toHaveValue("/h");
+      await expect(popover.getByText("/history", { exact: true }).first()).toBeVisible({
+        timeout: 30_000,
+      });
+      const afterDelete = await visiblePopoverBox(page);
+
+      expect(Math.abs(afterDelete.bottom - beforeDelete.bottom)).toBeLessThanOrEqual(4);
+      expect(afterDelete.height).toBeGreaterThan(beforeDelete.height);
+    } finally {
+      await agent.cleanup();
+    }
+  });
+
+  test("shrinks to filtered slash command results without moving the bottom edge", async ({
+    page,
+  }) => {
+    await installListCommandsStub(page);
+    const agent = await openReadyMockAgent(page);
+
+    try {
+      const input = composerLocator(page);
+      await expect(input).toBeEditable({ timeout: 30_000 });
+
+      await input.fill("/");
+      const popover = page.getByTestId("composer-autocomplete-popover");
+      await expect(popover.getByText("/help", { exact: true }).first()).toBeVisible({
+        timeout: 30_000,
+      });
+      const allCommands = await visiblePopoverBox(page);
+
+      await input.fill("/tdd");
+      await expect(popover.getByText("/tdd", { exact: true }).first()).toBeVisible({
+        timeout: 30_000,
+      });
+      const oneCommand = await visiblePopoverBox(page);
+
+      expect(Math.abs(oneCommand.bottom - allCommands.bottom)).toBeLessThanOrEqual(4);
+      expect(oneCommand.height).toBeLessThan(allCommands.height - 40);
+    } finally {
+      await agent.cleanup();
+    }
+  });
+
+  test("stays visible while filtering slash command results", async ({ page }) => {
+    await installListCommandsStub(page);
+    const agent = await openReadyMockAgent(page);
+
+    try {
+      const input = composerLocator(page);
+      await expect(input).toBeEditable({ timeout: 30_000 });
+
+      await input.fill("/");
+      const popover = page.getByTestId("composer-autocomplete-popover");
+      await expect(popover.getByText("/help", { exact: true }).first()).toBeVisible({
+        timeout: 30_000,
+      });
+
+      await startPopoverFrameRecorder(page);
+      await page.keyboard.type("tdd", { delay: 40 });
+      await expect(popover.getByText("/tdd", { exact: true }).first()).toBeVisible({
+        timeout: 30_000,
+      });
+      await page.waitForTimeout(250);
+      const frames = await stopPopoverFrameRecorder(page);
+
+      expectPopoverDoesNotDisappearAfterFirstVisible(frames);
+    } finally {
+      await agent.cleanup();
+    }
+  });
+
+  test("stays anchored to the composer when the desktop sidebar is open", async ({ page }) => {
+    await installListCommandsStub(page);
+    const agent = await openReadyMockAgent(page);
+
+    try {
+      await expect(page.getByTestId("sidebar-sessions")).toBeVisible({ timeout: 30_000 });
+      const input = composerLocator(page);
+      await expect(input).toBeEditable({ timeout: 30_000 });
+
+      await input.fill("/");
+      const popover = page.getByTestId("composer-autocomplete-popover");
+      await expect(popover.getByText("/help", { exact: true }).first()).toBeVisible({
+        timeout: 30_000,
+      });
+
+      const composerBox = await page.getByTestId("message-input-root").boundingBox();
+      const popoverBox = await popover.boundingBox();
+      expect(composerBox).not.toBeNull();
+      expect(popoverBox).not.toBeNull();
+
+      expect(Math.abs(popoverBox!.x - composerBox!.x)).toBeLessThanOrEqual(4);
+      expect(Math.abs(popoverBox!.width - composerBox!.width)).toBeLessThanOrEqual(4);
+    } finally {
+      await agent.cleanup();
+    }
+  });
+
+  test.describe("compact sidebar layering", () => {
+    test.use({ viewport: { width: 390, height: 844 }, isMobile: true, hasTouch: true });
+
+    test("keeps the mobile agent sidebar above autocomplete", async ({ page }) => {
+      await installListCommandsStub(page);
+      const agent = await openReadyMockAgent(page, { expectWorkspaceTab: false });
+
+      try {
+        const input = composerLocator(page);
+        await expect(input).toBeEditable({ timeout: 30_000 });
+
+        await input.fill("/");
+        const popover = page.getByTestId("composer-autocomplete-popover");
+        await expect(popover.getByText("/help", { exact: true }).first()).toBeVisible({
+          timeout: 30_000,
+        });
+
+        await page.getByRole("button", { name: "Open menu" }).click();
+        await expect(page.getByTestId("sidebar-sessions")).toBeInViewport({ timeout: 5_000 });
+
+        const popoverBox = await popover.boundingBox();
+        expect(popoverBox).not.toBeNull();
+
+        const topTestId = await getTopTestIdAtPoint(
+          page,
+          popoverBox!.x + popoverBox!.width / 2,
+          popoverBox!.y + popoverBox!.height / 2,
+        );
+
+        expect(topTestId).not.toBe("composer-autocomplete-popover");
+      } finally {
+        await agent.cleanup();
+      }
+    });
+  });
+});

packages/app/e2e/desktop-updates.spec.ts

@@ -1,5 +1,6 @@
 import { test } from "./fixtures";
 import { gotoAppShell } from "./helpers/app";
+import { getServerId } from "./helpers/server-id";
 import {
   loadRealDaemonState,
   injectDesktopBridge,
@@ -17,20 +18,12 @@ import {
   expectDaemonStatusVersion,
 } from "./helpers/desktop-updates";
 
-function getSeededServerId(): string {
-  const serverId = process.env.E2E_SERVER_ID;
-  if (!serverId) {
-    throw new Error("E2E_SERVER_ID is not set (expected from Playwright globalSetup).");
-  }
-  return serverId;
-}
-
 // No Playwright Electron runner exists; we simulate the desktop bridge via
 // addInitScript so Electron-gated UI activates without a real Electron process.
 test.describe("Desktop updates", () => {
   test("update banner appears in the sidebar when an app update is available", async ({ page }) => {
     await injectDesktopBridge(page, {
-      serverId: getSeededServerId(),
+      serverId: getServerId(),
       updateAvailable: true,
       latestVersion: "1.2.3",
     });
@@ -41,7 +34,7 @@ test.describe("Desktop updates", () => {
 
   test("clicking install shows the installing state on the callout", async ({ page }) => {
     await injectDesktopBridge(page, {
-      serverId: getSeededServerId(),
+      serverId: getServerId(),
       updateAvailable: true,
       latestVersion: "1.2.3",
       slowInstall: true,
@@ -58,7 +51,7 @@ test.describe("Desktop daemon management", () => {
   test("disabling built-in daemon management shows confirm dialog with correct copy", async ({
     page,
   }) => {
-    const serverId = getSeededServerId();
+    const serverId = getServerId();
     await injectDesktopBridge(page, {
       serverId,
       manageBuiltInDaemon: true,
@@ -74,7 +67,7 @@ test.describe("Desktop daemon management", () => {
   });
 
   test("cancelling the confirm dialog leaves the daemon management toggle on", async ({ page }) => {
-    const serverId = getSeededServerId();
+    const serverId = getServerId();
     await injectDesktopBridge(page, {
       serverId,
       manageBuiltInDaemon: true,
@@ -89,7 +82,7 @@ test.describe("Desktop daemon management", () => {
   });
 
   test("confirming the dialog disables built-in daemon management", async ({ page }) => {
-    const serverId = getSeededServerId();
+    const serverId = getServerId();
     await injectDesktopBridge(page, {
       serverId,
       manageBuiltInDaemon: true,
@@ -106,7 +99,7 @@ test.describe("Desktop daemon management", () => {
   test("daemon status panel renders version, PID, and log path from the real daemon", async ({
     page,
   }) => {
-    const serverId = getSeededServerId();
+    const serverId = getServerId();
     const realState = await loadRealDaemonState();
     await injectDesktopBridge(page, {
       serverId,
@@ -124,7 +117,7 @@ test.describe("Desktop daemon management", () => {
   });
 
   test("stopping and restarting the daemon updates the PID", async ({ page }) => {
-    const serverId = getSeededServerId();
+    const serverId = getServerId();
     const realState = await loadRealDaemonState();
     await injectDesktopBridge(page, {
       serverId,

packages/app/e2e/file-explorer-collapse.spec.ts

@@ -9,41 +9,31 @@ import {
   openFileFromExplorer,
 } from "./helpers/file-explorer";
 import { gotoWorkspace } from "./helpers/launcher";
-import { createTempGitRepo } from "./helpers/workspace";
-import {
-  connectWorkspaceSetupClient,
-  type WorkspaceSetupDaemonClient,
-} from "./helpers/workspace-setup";
+import { seedWorkspace, type SeededWorkspace } from "./helpers/seed-client";
 
-let tempRepo: { path: string; cleanup: () => Promise<void> };
-let workspaceId: string;
-let seedClient: WorkspaceSetupDaemonClient;
+let workspace: SeededWorkspace;
 
 test.beforeAll(async () => {
-  tempRepo = await createTempGitRepo("file-explorer-collapse-", {
-    files: [
-      { path: "assets/logo.png", content: "image bytes for explorer e2e\n" },
-      { path: "docs/guide.md", content: "# Guide\n" },
-    ],
+  workspace = await seedWorkspace({
+    repoPrefix: "file-explorer-collapse-",
+    repo: {
+      files: [
+        { path: "assets/logo.png", content: "image bytes for explorer e2e\n" },
+        { path: "docs/guide.md", content: "# Guide\n" },
+      ],
+    },
   });
-  seedClient = await connectWorkspaceSetupClient();
-  const result = await seedClient.openProject(tempRepo.path);
-  if (!result.workspace) {
-    throw new Error(result.error ?? "Failed to seed workspace");
-  }
-  workspaceId = result.workspace.id;
 });
 
 test.afterAll(async () => {
-  await seedClient?.close();
-  await tempRepo?.cleanup();
+  await workspace?.cleanup();
 });
 
 test.describe("File explorer collapse", () => {
   test("collapses an opened image file parent folder and still expands other folders", async ({
     page,
   }) => {
-    await gotoWorkspace(page, workspaceId);
+    await gotoWorkspace(page, workspace.workspaceId);
     await openFileExplorer(page);
 
     await expandFolder(page, "assets");

packages/app/e2e/fixtures.ts

@@ -1,4 +1,5 @@
 import { test as base, expect, type Page } from "@playwright/test";
+import { getE2EDaemonPort } from "./helpers/daemon-port";
 import { buildCreateAgentPreferences, buildSeededHost } from "./helpers/daemon-registry";
 import { createWithWorkspace, type WithWorkspace } from "./helpers/with-workspace";
 
@@ -17,20 +18,8 @@ const test = base.extend<{ paseoE2ESetup: void; withWorkspace: WithWorkspace }>(
   },
   paseoE2ESetup: [
     async ({ page }, provide, testInfo) => {
-      const daemonPort = process.env.E2E_DAEMON_PORT;
+      const daemonPort = getE2EDaemonPort();
       const metroPort = process.env.E2E_METRO_PORT;
-      if (!daemonPort) {
-        throw new Error(
-          "E2E_DAEMON_PORT is not set. Refusing to run e2e against the default daemon (e.g. localhost:6767). " +
-            "Ensure Playwright `globalSetup` starts the e2e daemon and exports E2E_DAEMON_PORT.",
-        );
-      }
-      if (daemonPort === "6767") {
-        throw new Error(
-          "E2E_DAEMON_PORT is 6767. Refusing to run e2e against the default local daemon. " +
-            "Fix Playwright globalSetup to start an isolated test daemon and export its port.",
-        );
-      }
       if (!metroPort) {
         throw new Error(
           "E2E_METRO_PORT is not set. Ensure Playwright `globalSetup` starts Metro and exports E2E_METRO_PORT.",

packages/app/e2e/global-setup.ts

@@ -188,7 +188,7 @@ async function isOpenAiApiKeyUsable(apiKey: string | undefined): Promise<boolean
 let daemonProcess: ChildProcess | null = null;
 let metroProcess: ChildProcess | null = null;
 let paseoHome: string | null = null;
-let fakeGhBinDir: string | null = null;
+let fakeToolBinDir: string | null = null;
 let relayProcess: ChildProcess | null = null;
 
 function resolveOptionalPaseoHomeEnv(value: string | undefined): string | null {
@@ -209,8 +209,8 @@ interface OfferPayload {
   relay: { endpoint: string };
 }
 
-async function createFakeGhBin(): Promise<string> {
-  const binDir = await mkdtemp(path.join(tmpdir(), "paseo-e2e-gh-bin-"));
+async function createFakeToolBin(): Promise<string> {
+  const binDir = await mkdtemp(path.join(tmpdir(), "paseo-e2e-tool-bin-"));
   const ghPath = path.join(binDir, "gh");
   await writeFile(
     ghPath,
@@ -284,6 +284,27 @@ forwardToRealGh();
 `,
   );
   await chmod(ghPath, 0o755);
+
+  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);
+  }
+
   return binDir;
 }
 
@@ -300,7 +321,7 @@ function ensureRelayBuildArtifact(repoRoot: string): void {
   }
 
   console.log("[e2e] Building @getpaseo/relay for daemon startup");
-  execSync("npm run build --workspace=@getpaseo/relay", {
+  execSync("npm run build:relay", {
     cwd: repoRoot,
     stdio: "inherit",
   });
@@ -516,13 +537,22 @@ async function awaitRelayReady(
   }
 }
 
-async function startRelay(): Promise<number> {
+async function getAvailablePortExcluding(excludedPorts: Set<number>): Promise<number> {
+  for (;;) {
+    const port = await getAvailablePort();
+    if (!excludedPorts.has(port)) {
+      return port;
+    }
+  }
+}
+
+async function startRelay(excludedPorts: Set<number>): Promise<number> {
   const relayDir = path.resolve(__dirname, "..", "..", "relay");
   const maxRelayStartupAttempts = 5;
   let lastRelayStartupError: unknown = null;
 
   for (let attempt = 1; attempt <= maxRelayStartupAttempts; attempt += 1) {
-    const relayPort = await getAvailablePort();
+    const relayPort = await getAvailablePortExcluding(excludedPorts);
     const buffer = createLineBuffer();
     const state: RelayStreamState = { failureLine: null, readyForSelectedPort: false };
 
@@ -599,7 +629,8 @@ interface DaemonSpawnArgs {
   relayPort: number;
   metroPort: number;
   paseoHome: string;
-  fakeGhBinDir: string;
+  fakeToolBinDir: string;
+  editorRecordPath: string;
   dictation: DictationConfig;
   buffer: ReturnType<typeof createLineBuffer>;
 }
@@ -613,8 +644,9 @@ function startDaemon(args: DaemonSpawnArgs): ChildProcess {
     cwd: serverDir,
     env: {
       ...process.env,
-      PATH: `${args.fakeGhBinDir}${path.delimiter}${process.env.PATH ?? ""}`,
+      PATH: `${args.fakeToolBinDir}${path.delimiter}${process.env.PATH ?? ""}`,
       PASEO_HOME: args.paseoHome,
+      PASEO_E2E_EDITOR_RECORD_PATH: args.editorRecordPath,
       PASEO_SERVER_ID: "srv_e2e_test_daemon",
       PASEO_LISTEN: `0.0.0.0:${args.port}`,
       PASEO_RELAY_ENDPOINT: `127.0.0.1:${args.relayPort}`,
@@ -678,9 +710,9 @@ async function performCleanup(shouldRemovePaseoHome: boolean): Promise<void> {
   } else if (paseoHome) {
     console.log(`[e2e] Preserving PASEO_HOME: ${paseoHome}`);
   }
-  if (fakeGhBinDir) {
-    await rm(fakeGhBinDir, { recursive: true, force: true });
-    fakeGhBinDir = null;
+  if (fakeToolBinDir) {
+    await rm(fakeToolBinDir, { recursive: true, force: true });
+    fakeToolBinDir = null;
   }
 }
 
@@ -694,7 +726,8 @@ export default async function globalSetup() {
   const requestedPaseoHome = resolveOptionalPaseoHomeEnv(process.env.E2E_PASEO_HOME);
   const shouldRemovePaseoHome = !requestedPaseoHome && process.env.E2E_KEEP_PASEO_HOME !== "1";
   paseoHome = requestedPaseoHome ?? (await mkdtemp(path.join(tmpdir(), "paseo-e2e-home-")));
-  fakeGhBinDir = await createFakeGhBin();
+  const editorRecordPath = path.join(paseoHome, "editor-open-records.jsonl");
+  fakeToolBinDir = await createFakeToolBin();
   const metroLineBuffer = createLineBuffer();
   const daemonLineBuffer = createLineBuffer();
 
@@ -705,14 +738,15 @@ export default async function globalSetup() {
   const dictation = await resolveDictationConfig();
 
   try {
-    const relayPort = await startRelay();
+    const relayPort = await startRelay(new Set([port, metroPort]));
     metroProcess = startMetro(metroPort, metroLineBuffer);
     daemonProcess = startDaemon({
       port,
       relayPort,
       metroPort,
       paseoHome,
-      fakeGhBinDir,
+      fakeToolBinDir,
+      editorRecordPath,
       dictation,
       buffer: daemonLineBuffer,
     });
@@ -742,6 +776,7 @@ export default async function globalSetup() {
     process.env.E2E_RELAY_DAEMON_PUBLIC_KEY = offer.daemonPublicKeyB64;
     process.env.E2E_METRO_PORT = String(metroPort);
     process.env.E2E_PASEO_HOME = paseoHome;
+    process.env.E2E_EDITOR_RECORD_PATH = editorRecordPath;
     console.log(
       `[e2e] Test daemon started on port ${port}, Metro on port ${metroPort}, home: ${paseoHome}`,
     );

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

@@ -1,9 +1,4 @@
 import { expect, type Page } from "@playwright/test";
-import path from "node:path";
-import { pathToFileURL } from "node:url";
-import { randomUUID } from "node:crypto";
-import { createNodeWebSocketFactory, type NodeWebSocketFactory } from "./node-ws-factory";
-import { buildHostWorkspaceRoute } from "../../src/utils/host-routes";
 
 const NEAR_BOTTOM_THRESHOLD_PX = 72;
 
@@ -14,157 +9,6 @@ export interface ScrollMetrics {
   distanceFromBottom: number;
 }
 
-export interface SeededAgent {
-  id: string;
-  title: string;
-  expectedTailText: string;
-  url: string;
-  workspaceUrl: string;
-}
-
-export interface DaemonClientInstance {
-  connect(): Promise<void>;
-  close(): Promise<void>;
-  createAgent(options: {
-    provider: string;
-    model: string;
-    thinkingOptionId: string;
-    modeId: string;
-    cwd: string;
-    title: string;
-    initialPrompt: string;
-  }): Promise<{ id: string }>;
-  sendAgentMessage(agentId: string, text: string): Promise<void>;
-  waitForFinish(agentId: string, timeout?: number): Promise<{ status: string }>;
-}
-
-function getDaemonWsUrl(): string {
-  const daemonPort = process.env.E2E_DAEMON_PORT;
-  if (!daemonPort) {
-    throw new Error("E2E_DAEMON_PORT is not set.");
-  }
-  return `ws://127.0.0.1:${daemonPort}/ws`;
-}
-
-function getServerId(): string {
-  const serverId = process.env.E2E_SERVER_ID;
-  if (!serverId) {
-    throw new Error("E2E_SERVER_ID is not set.");
-  }
-  return serverId;
-}
-
-function buildReplyBlock(label: string, lineCount = 14): string {
-  return Array.from({ length: lineCount }, (_, index) => {
-    const line = (index + 1).toString().padStart(2, "0");
-    return `${label} line ${line} anchor verification text keeps wrapping stable across resize and composer growth.`;
-  }).join("\n");
-}
-
-function buildProtocolMessage(label: string, lineCount = 14): string {
-  return [
-    "For every message in this chat, reply with exactly the text after the final line `REPLY:`.",
-    "Do not add extra words, bullets, markdown fences, or tool calls.",
-    "REPLY:",
-    buildReplyBlock(label, lineCount),
-  ].join("\n");
-}
-
-function buildReplyMessage(label: string, lineCount = 14): string {
-  return ["REPLY:", buildReplyBlock(label, lineCount)].join("\n");
-}
-
-export function createReplyTurn(label: string): {
-  message: string;
-  expectedReply: string;
-} {
-  return {
-    message: buildReplyMessage(label),
-    expectedReply: buildReplyBlock(label),
-  };
-}
-
-interface DaemonClientConfig {
-  url: string;
-  clientId: string;
-  clientType: "cli";
-  webSocketFactory?: NodeWebSocketFactory;
-}
-
-async function loadDaemonClientConstructor(): Promise<
-  new (config: DaemonClientConfig) => DaemonClientInstance
-> {
-  const repoRoot = path.resolve(__dirname, "../../../../");
-  const moduleUrl = pathToFileURL(
-    path.join(repoRoot, "packages/server/dist/server/server/exports.js"),
-  ).href;
-  const mod = (await import(moduleUrl)) as {
-    DaemonClient: new (config: DaemonClientConfig) => DaemonClientInstance;
-  };
-  return mod.DaemonClient;
-}
-
-export async function connectDaemonClient(): Promise<DaemonClientInstance> {
-  const DaemonClient = await loadDaemonClientConstructor();
-  const webSocketFactory = createNodeWebSocketFactory();
-  const client = new DaemonClient({
-    url: getDaemonWsUrl(),
-    clientId: `app-e2e-${randomUUID()}`,
-    clientType: "cli",
-    webSocketFactory,
-  });
-  await client.connect();
-  return client;
-}
-
-export async function seedBottomAnchorAgent(input: {
-  client: DaemonClientInstance;
-  cwd: string;
-  title?: string;
-  turnCount?: number;
-  lineCount?: number;
-}): Promise<SeededAgent> {
-  const title = input.title ?? `bottom-anchor-${Date.now()}`;
-  const turnCount = Math.max(3, input.turnCount ?? 5);
-  const lineCount = Math.max(14, input.lineCount ?? 14);
-  const created = await input.client.createAgent({
-    provider: "codex",
-    model: "gpt-5.4-mini",
-    thinkingOptionId: "low",
-    modeId: "full-access",
-    cwd: input.cwd,
-    title,
-    initialPrompt: buildProtocolMessage(`${title}-turn-00`, lineCount),
-  });
-  const initialFinish = await input.client.waitForFinish(created.id, 120000);
-  if (initialFinish.status !== "idle") {
-    throw new Error(
-      `Expected seeded agent ${created.id} to become idle after initial prompt, got ${initialFinish.status}.`,
-    );
-  }
-
-  let expectedTailText = buildReplyBlock(`${title}-turn-00`, lineCount);
-  for (let index = 1; index < turnCount; index += 1) {
-    const label = `${title}-turn-${index.toString().padStart(2, "0")}`;
-    expectedTailText = buildReplyBlock(label, lineCount);
-    await input.client.sendAgentMessage(created.id, buildReplyMessage(label, lineCount));
-    const finish = await input.client.waitForFinish(created.id, 120000);
-    if (finish.status !== "idle") {
-      throw new Error(
-        `Expected seeded agent ${created.id} to become idle after turn ${index}, got ${finish.status}.`,
-      );
-    }
-  }
-
-  return {
-    id: created.id,
-    title,
-    expectedTailText,
-    url: `${buildHostWorkspaceRoute(getServerId(), input.cwd)}?open=${encodeURIComponent(`agent:${created.id}`)}`,
-    workspaceUrl: buildHostWorkspaceRoute(getServerId(), input.cwd),
-  };
-}
-
 function getVisibleChatScroll(page: Page) {
   return page.locator('[data-testid="agent-chat-scroll"]:visible').first();
 }
@@ -201,48 +45,6 @@ export async function readScrollMetrics(page: Page): Promise<ScrollMetrics> {
   });
 }
 
-export async function scrollUpFromBottom(page: Page, pixels: number): Promise<void> {
-  const scrollViewport = getVisibleChatScroll(page);
-  await expect(scrollViewport).toHaveCount(1, { timeout: 30000 });
-  let remaining = Math.max(0, pixels);
-  while (remaining > 0) {
-    const delta = Math.min(240, remaining);
-    await scrollViewport.evaluate((element: Element, step: number) => {
-      const scrollContainer = element as HTMLElement;
-      scrollContainer.dispatchEvent(
-        new WheelEvent("wheel", {
-          deltaY: -step,
-          bubbles: true,
-          cancelable: true,
-        }),
-      );
-      scrollContainer.scrollTop = Math.max(0, scrollContainer.scrollTop - step);
-      scrollContainer.dispatchEvent(new Event("scroll", { bubbles: true }));
-    }, delta);
-    remaining -= delta;
-
-    if ((await readScrollMetrics(page)).distanceFromBottom > NEAR_BOTTOM_THRESHOLD_PX) {
-      return;
-    }
-  }
-}
-
-export async function waitForAgentReady(page: Page, expectedTailText?: string): Promise<void> {
-  await expect(getVisibleChatScroll(page)).toBeVisible({ timeout: 60000 });
-  await expect(page.getByRole("textbox", { name: "Message agent..." }).first()).toBeVisible({
-    timeout: 60000,
-  });
-  await expect(page.getByTestId("agent-loading")).toHaveCount(0, { timeout: 60000 });
-  if (expectedTailText) {
-    await expect
-      .poll(async () => {
-        const metrics = await readScrollMetrics(page);
-        return metrics.contentHeight;
-      })
-      .toBeGreaterThan(0);
-  }
-}
-
 export async function expectNearBottom(page: Page): Promise<void> {
   await expect
     .poll(async () => {
@@ -252,15 +54,6 @@ export async function expectNearBottom(page: Page): Promise<void> {
     .toBeLessThanOrEqual(NEAR_BOTTOM_THRESHOLD_PX);
 }
 
-export async function expectDetachedFromBottom(page: Page): Promise<void> {
-  await expect
-    .poll(async () => {
-      const metrics = await readScrollMetrics(page);
-      return metrics.distanceFromBottom;
-    })
-    .toBeGreaterThan(NEAR_BOTTOM_THRESHOLD_PX);
-}
-
 export async function waitForContentGrowth(
   page: Page,
   previousContentHeight: number,
@@ -273,11 +66,3 @@ export async function waitForContentGrowth(
     .toBeGreaterThan(previousContentHeight);
   return readScrollMetrics(page);
 }
-
-export async function getChatContainerKey(page: Page): Promise<string | null> {
-  return getVisibleChatScroll(page).evaluate((element) => {
-    const nativeId = (element as HTMLElement).id;
-    const prefix = "agent-chat-scroll-";
-    return nativeId.startsWith(prefix) ? nativeId.slice(prefix.length) : null;
-  });
-}

packages/app/e2e/helpers/app.ts

@@ -1,8 +1,5 @@
 import { expect, type Page } from "@playwright/test";
-
-function escapeRegex(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
+import { escapeRegex } from "./regex";
 
 export const gotoAppShell = async (page: Page) => {
   await page.goto("/");

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

@@ -1,9 +1,8 @@
 import { randomUUID } from "node:crypto";
-import path from "node:path";
-import { pathToFileURL } from "node:url";
 import { expect, type Page } from "@playwright/test";
 import { buildCreateAgentPreferences, buildSeededHost } from "./daemon-registry";
-import { createNodeWebSocketFactory, type NodeWebSocketFactory } from "./node-ws-factory";
+import { getE2EDaemonPort } from "./daemon-port";
+import { getServerId } from "./server-id";
 import { waitForWorkspaceTabsVisible } from "./workspace-tabs";
 import {
   buildHostAgentDetailRoute,
@@ -17,100 +16,40 @@ export interface ArchiveTabAgent {
   cwd: string;
 }
 
-interface ArchiveTabDaemonClient {
-  connect(): Promise<void>;
-  close(): Promise<void>;
-  createAgent(options: {
-    provider: string;
-    model: string;
-    thinkingOptionId?: string;
-    modeId: string;
-    cwd: string;
-    title: string;
-    initialPrompt?: string;
-  }): Promise<{ id: string }>;
-  archiveAgent(agentId: string): Promise<{ archivedAt: string }>;
-  waitForFinish(agentId: string, timeout?: number): Promise<{ status: string }>;
-  waitForAgentUpsert(
-    agentId: string,
-    predicate: (snapshot: { status: string }) => boolean,
-    timeout?: number,
-  ): Promise<{ status: string }>;
-  fetchAgentHistory(options?: {
-    page?: { limit: number };
-  }): Promise<{ entries: Array<{ id: string }> }>;
-}
-
-function getDaemonPort(): string {
-  const daemonPort = process.env.E2E_DAEMON_PORT;
-  if (!daemonPort) {
-    throw new Error("E2E_DAEMON_PORT is not set.");
-  }
-  if (daemonPort === "6767") {
-    throw new Error("E2E_DAEMON_PORT must not point at the developer daemon.");
-  }
-  return daemonPort;
-}
-
-function getServerId(): string {
-  const serverId = process.env.E2E_SERVER_ID;
-  if (!serverId) {
-    throw new Error("E2E_SERVER_ID is not set.");
-  }
-  return serverId;
-}
-
-function getDaemonWsUrl(): string {
-  return `ws://127.0.0.1:${getDaemonPort()}/ws`;
-}
-
 function buildSeededStoragePayload() {
   const nowIso = new Date().toISOString();
   return {
     daemon: buildSeededHost({
       serverId: getServerId(),
-      endpoint: `127.0.0.1:${getDaemonPort()}`,
+      endpoint: `127.0.0.1:${getE2EDaemonPort()}`,
       nowIso,
     }),
     preferences: buildCreateAgentPreferences(getServerId()),
   };
 }
 
-interface ArchiveTabDaemonClientConfig {
-  url: string;
-  clientId: string;
-  clientType: "cli";
-  webSocketFactory?: NodeWebSocketFactory;
-}
-
-async function loadDaemonClientConstructor(): Promise<
-  new (config: ArchiveTabDaemonClientConfig) => ArchiveTabDaemonClient
-> {
-  const repoRoot = path.resolve(__dirname, "../../../../");
-  const moduleUrl = pathToFileURL(
-    path.join(repoRoot, "packages/server/dist/server/server/exports.js"),
-  ).href;
-  const mod = (await import(moduleUrl)) as {
-    DaemonClient: new (config: ArchiveTabDaemonClientConfig) => ArchiveTabDaemonClient;
-  };
-  return mod.DaemonClient;
-}
-
-export async function connectArchiveTabDaemonClient(): Promise<ArchiveTabDaemonClient> {
-  const DaemonClient = await loadDaemonClientConstructor();
-  const webSocketFactory = createNodeWebSocketFactory();
-  const client = new DaemonClient({
-    url: getDaemonWsUrl(),
-    clientId: `app-e2e-archive-tab-${randomUUID()}`,
-    clientType: "cli",
-    webSocketFactory,
-  });
-  await client.connect();
-  return client;
+/**
+ * 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;
+    cwd: string;
+    title: string;
+  }): Promise<{ id: string }>;
+  waitForAgentUpsert(
+    agentId: string,
+    predicate: (snapshot: { status: string }) => boolean,
+    timeout?: number,
+  ): Promise<{ status: string }>;
 }
 
 export async function createIdleAgent(
-  client: ArchiveTabDaemonClient,
+  client: IdleAgentSeedClient,
   input: { cwd: string; title: string },
 ): Promise<ArchiveTabAgent> {
   const created = await client.createAgent({
@@ -136,7 +75,7 @@ export async function createIdleAgent(
 }
 
 export async function archiveAgentFromDaemon(
-  client: ArchiveTabDaemonClient,
+  client: { archiveAgent(agentId: string): Promise<{ archivedAt: string }> },
   agentId: string,
 ): Promise<void> {
   await client.archiveAgent(agentId);

packages/app/e2e/helpers/composer.ts

@@ -1,9 +1,10 @@
 import { expect, type Page } from "@playwright/test";
 import { buildHostWorkspaceRoute } from "@/utils/host-routes";
 import { createTempGitRepo } from "./workspace";
-import { connectTerminalClient, type TerminalPerfDaemonClient } from "./terminal-perf";
+import { connectSeedClient, type SeedDaemonClient } from "./seed-client";
 import { connectWorkspaceSetupClient, openHomeWithProject } from "./workspace-setup";
 import { selectWorkspaceInSidebar } from "./sidebar";
+import { getServerId } from "./server-id";
 import { waitForTabBar } from "./launcher";
 
 function composerInput(page: Page) {
@@ -145,7 +146,7 @@ export async function selectGithubOption(
 }
 
 export interface MockAgentSetup {
-  client: TerminalPerfDaemonClient;
+  client: SeedDaemonClient;
   repo: Awaited<ReturnType<typeof createTempGitRepo>>;
 }
 
@@ -154,11 +155,10 @@ export async function startRunningMockAgent(
   page: Page,
   opts: { prefix: string; model: string; prompt: string },
 ): Promise<MockAgentSetup> {
-  const serverId = process.env.E2E_SERVER_ID;
-  if (!serverId) throw new Error("E2E_SERVER_ID is not set.");
+  const serverId = getServerId();
 
   const repo = await createTempGitRepo(opts.prefix);
-  const client = await connectTerminalClient();
+  const client = await connectSeedClient();
   const opened = await client.openProject(repo.path);
   if (!opened.workspace) throw new Error(opened.error ?? "Failed to open project");
   const agent = await client.createAgent({

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

@@ -0,0 +1,55 @@
+import { randomUUID } from "node:crypto";
+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(): string {
+  return `ws://127.0.0.1:${getE2EDaemonPort()}/ws`;
+}
+
+export interface ConnectDaemonClientOptions {
+  clientIdPrefix: string;
+  appVersion?: string;
+}
+
+/**
+ * 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(),
+    clientId: `${options.clientIdPrefix}-${randomUUID()}`,
+    clientType: "cli",
+    appVersion: options.appVersion,
+    webSocketFactory: createNodeWebSocketFactory(),
+  });
+  await client.connect();
+  return client;
+}

packages/app/e2e/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 Playwright globalSetup).");
+  }
+  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/helpers/desktop-updates.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { expect, type Page } from "@playwright/test";
 import { openSettings } from "./app";
+import { getE2EDaemonPort } from "./daemon-port";
 import { openSettingsHost } from "./settings";
 
 interface DaemonApiStatus {
@@ -26,9 +27,8 @@ export interface RealDaemonState {
  * E2E_PASEO_HOME directory. Call this in Node test code (not in the browser).
  */
 export async function loadRealDaemonState(): Promise<RealDaemonState> {
-  const port = process.env.E2E_DAEMON_PORT;
+  const port = getE2EDaemonPort();
   const paseoHome = process.env.E2E_PASEO_HOME;
-  if (!port) throw new Error("E2E_DAEMON_PORT not set — globalSetup must run first");
   if (!paseoHome) throw new Error("E2E_PASEO_HOME not set — globalSetup must run first");
 
   const resp = await fetch(`http://127.0.0.1:${port}/api/status`);

packages/app/e2e/helpers/launcher.ts

@@ -1,17 +1,10 @@
 import { expect, type Page } from "@playwright/test";
 import { buildHostWorkspaceRoute } from "../../src/utils/host-routes";
 import { createTempGitRepo } from "./workspace";
+import { getServerId } from "./server-id";
 
 // ─── Navigation ────────────────────────────────────────────────────────────
 
-function getServerId(): string {
-  const serverId = process.env.E2E_SERVER_ID;
-  if (!serverId) {
-    throw new Error("E2E_SERVER_ID is not set (expected from Playwright globalSetup).");
-  }
-  return serverId;
-}
-
 /** Navigate to a workspace and wait for the tab bar to appear. */
 export async function gotoWorkspace(page: Page, cwd: string): Promise<void> {
   const route = buildHostWorkspaceRoute(getServerId(), cwd);

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

@@ -0,0 +1,69 @@
+import type { Page } from "@playwright/test";
+import { buildHostWorkspaceRoute } from "../../src/utils/host-routes";
+import { seedWorkspace, type SeedDaemonClient } from "./seed-client";
+import { getServerId } from "./server-id";
+
+export interface MockAgentWorkspace {
+  agentId: 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,
+      title: options.title,
+      modeId: options.modeId ?? "load-test",
+      model: options.model ?? "ten-second-stream",
+      initialPrompt: options.initialPrompt,
+      featureValues: options.featureValues,
+    });
+    return {
+      agentId: agent.id,
+      cwd: workspace.repoPath,
+      client: workspace.client,
+      cleanup: workspace.cleanup,
+    };
+  } catch (error) {
+    await workspace.cleanup();
+    throw error;
+  }
+}
+
+export function buildAgentRoute(cwd: string, agentId: string): string {
+  return `${buildHostWorkspaceRoute(getServerId(), cwd)}?open=${encodeURIComponent(
+    `agent:${agentId}`,
+  )}`;
+}
+
+/** 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: { cwd: string; agentId: string },
+): Promise<void> {
+  await page.goto(buildAgentRoute(input.cwd, input.agentId));
+  await page.waitForURL(
+    (url) => url.pathname.includes("/workspace/") && !url.searchParams.has("open"),
+    { timeout: 60_000 },
+  );
+}

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

@@ -1,14 +1,12 @@
-import { randomUUID } from "node:crypto";
-import path from "node:path";
-import { pathToFileURL } from "node:url";
 import { expect, type Page } from "@playwright/test";
-import type { DaemonClient as ServerDaemonClient } from "@server/client/daemon-client";
+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 { expectWorkspaceHeader, workspaceLabelFromPath } from "./workspace-ui";
-import { createNodeWebSocketFactory, type NodeWebSocketFactory } from "./node-ws-factory";
 
 type NewWorkspaceDaemonClient = Pick<
-  ServerDaemonClient,
+  InternalDaemonClient,
   | "archivePaseoWorktree"
   | "archiveWorkspace"
   | "close"
@@ -17,13 +15,6 @@ type NewWorkspaceDaemonClient = Pick<
   | "openProject"
 >;
 
-interface NewWorkspaceDaemonClientConfig {
-  url: string;
-  clientId: string;
-  clientType: "cli";
-  webSocketFactory?: NodeWebSocketFactory;
-}
-
 type OpenProjectPayload = Awaited<ReturnType<NewWorkspaceDaemonClient["openProject"]>>;
 
 export interface OpenedProject {
@@ -33,34 +24,6 @@ export interface OpenedProject {
   workspaceName: string;
 }
 
-function getDaemonPort(): string {
-  const daemonPort = process.env.E2E_DAEMON_PORT;
-  if (!daemonPort) {
-    throw new Error("E2E_DAEMON_PORT is not set.");
-  }
-  if (daemonPort === "6767") {
-    throw new Error("E2E_DAEMON_PORT must not point at the developer daemon.");
-  }
-  return daemonPort;
-}
-
-function getDaemonWsUrl(): string {
-  return `ws://127.0.0.1:${getDaemonPort()}/ws`;
-}
-
-async function loadDaemonClientConstructor(): Promise<
-  new (config: NewWorkspaceDaemonClientConfig) => NewWorkspaceDaemonClient
-> {
-  const repoRoot = path.resolve(__dirname, "../../../../");
-  const moduleUrl = pathToFileURL(
-    path.join(repoRoot, "packages/server/dist/server/server/exports.js"),
-  ).href;
-  const mod = (await import(moduleUrl)) as {
-    DaemonClient: new (config: NewWorkspaceDaemonClientConfig) => NewWorkspaceDaemonClient;
-  };
-  return mod.DaemonClient;
-}
-
 function requireWorkspace(payload: OpenProjectPayload) {
   if (payload.error) {
     throw new Error(payload.error);
@@ -83,16 +46,9 @@ function parseWorkspaceIdFromPageUrl(page: Page, serverId: string): string | nul
 }
 
 export async function connectNewWorkspaceDaemonClient(): Promise<NewWorkspaceDaemonClient> {
-  const DaemonClient = await loadDaemonClientConstructor();
-  const webSocketFactory = createNodeWebSocketFactory();
-  const client = new DaemonClient({
-    url: getDaemonWsUrl(),
-    clientId: `app-e2e-new-workspace-${randomUUID()}`,
-    clientType: "cli",
-    webSocketFactory,
+  return connectDaemonClient<NewWorkspaceDaemonClient>({
+    clientIdPrefix: "app-e2e-new-workspace",
   });
-  await client.connect();
-  return client;
 }
 
 export async function openProjectViaDaemon(
@@ -327,12 +283,7 @@ export interface AgentCreatedDelayControl {
 export async function delayBrowserAgentCreatedStatus(
   page: Page,
 ): Promise<AgentCreatedDelayControl> {
-  const daemonPort = process.env.E2E_DAEMON_PORT;
-  if (!daemonPort) {
-    throw new Error("E2E_DAEMON_PORT is not set.");
-  }
-
-  const daemonPortPattern = new RegExp(`:${daemonPort.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
+  const daemonPortPattern = daemonWsRoutePattern();
   const createRequestIds = new Set<string>();
   const delayedForwards: Array<() => void> = [];
   let releaseRequested = false;

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

@@ -3,6 +3,7 @@ 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";
 
 // --- Navigation ---
 
@@ -170,19 +171,13 @@ export async function unblockPaseoConfigWrites(repoPath: string): Promise<void>
 
 // --- WebSocket helpers ---
 
-function buildDaemonPortPattern(): RegExp {
-  const port = process.env.E2E_DAEMON_PORT;
-  if (!port) throw new Error("E2E_DAEMON_PORT not set — globalSetup must run first");
-  return new RegExp(`:${port.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
-}
-
 // Proxies all daemon WS traffic transparently until a read_project_config_request
 // is seen, then closes that connection (triggering readQuery.isError). Subsequent
 // connections pass through so the Reload action can succeed.
 export async function installReadTransportFailure(page: Page): Promise<void> {
   let armed = true;
 
-  await page.routeWebSocket(buildDaemonPortPattern(), (ws) => {
+  await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
     const server = ws.connectToServer();
 
     ws.onMessage((message) => {
@@ -230,7 +225,7 @@ export async function installDaemonConnectionGate(
   let acceptingConnections = true;
   const activeSockets = new Set<WebSocketRoute>();
 
-  await page.routeWebSocket(buildDaemonPortPattern(), (ws) => {
+  await page.routeWebSocket(daemonWsRoutePattern(), (ws) => {
     if (!acceptingConnections) {
       void ws.close({ code: 1001 });
       return;

packages/app/e2e/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/helpers/rename.ts

@@ -0,0 +1,40 @@
+import { type Page } from "@playwright/test";
+
+/**
+ * Listens for outbound WebSocket "session" frames of a given inner message type
+ * and accumulates them. The returned array is populated in-place as frames arrive.
+ */
+export function captureWsSessionFrames<T extends Record<string, unknown>>(
+  page: Page,
+  messageType: string,
+  extract: (inner: Record<string, unknown>) => T,
+): T[] {
+  const captured: T[] = [];
+  page.on("websocket", (ws) => {
+    ws.on("framesent", (frame) => {
+      const raw = frame.payload;
+      const text = typeof raw === "string" ? raw : raw.toString("utf8");
+      try {
+        const outer = JSON.parse(text) as { type?: string; message?: Record<string, unknown> };
+        if (outer.type === "session" && outer.message?.type === messageType) {
+          captured.push(extract(outer.message));
+        }
+      } catch {
+        // Ignore non-JSON and binary frames.
+      }
+    });
+  });
+  return captured;
+}
+
+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/helpers/rewind-flow.ts

@@ -0,0 +1,341 @@
+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;
+  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(cwd: string, agentId: string): string {
+  return `${buildHostWorkspaceRoute(getServerId(), cwd)}?open=${encodeURIComponent(
+    `agent:${agentId}`,
+  )}`;
+}
+
+async function openAgent(page: Page, input: { cwd: string; agentId: string }): Promise<void> {
+  await page.goto(agentRoute(input.cwd, 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";
+}): 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 opened = await client.openProject(input.cwd);
+  if (!opened.workspace) {
+    throw new Error(opened.error ?? `Failed to open project ${input.cwd}`);
+  }
+  const agent = await client.createAgent({
+    ...fullAccessConfig(input.provider),
+    cwd: input.cwd,
+    title: `rewind-flow-${input.provider}-${randomUUID()}`,
+  });
+  const handle = {
+    page: input.page,
+    client,
+    agentId: agent.id,
+    cwd: input.cwd,
+    provider: input.provider,
+  };
+  await openAgent(input.page, { cwd: input.cwd, agentId: agent.id });
+  return handle;
+}
+
+export async function closeAgent(handle: AgentHandle): Promise<void> {
+  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?: "canonical"; limit?: number },
+    ) => Promise<{ epoch?: string }>;
+  };
+  const timeline = await client.fetchAgentTimeline(handle.agentId, {
+    direction: "tail",
+    projection: "canonical",
+    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/helpers/seed-client.ts

@@ -0,0 +1,145 @@
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import { connectDaemonClient } from "./daemon-client-loader";
+import { createTempDirectory, createTempGitRepo } from "./workspace";
+
+/**
+ * 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>;
+  openProject(cwd: string): Promise<{
+    workspace: {
+      id: string;
+      name: string;
+      projectId: string;
+      projectDisplayName: string;
+      projectRootPath: string;
+      workspaceDirectory: string;
+    } | null;
+    error: string | null;
+  }>;
+  createTerminal(
+    cwd: string,
+    name?: string,
+  ): Promise<{
+    terminal: { id: string; name: string; cwd: string } | null;
+    error: string | null;
+  }>;
+  createAgent(options: {
+    provider: string;
+    cwd: string;
+    title?: string;
+    modeId?: string;
+    model?: string;
+    thinkingOptionId?: string;
+    featureValues?: Record<string, unknown>;
+    initialPrompt?: string;
+  }): Promise<{ id: string; status: string }>;
+  fetchAgents(options?: { scope?: "active" }): Promise<{
+    entries: Array<{ agent: { id: string; cwd: string; title?: string | null } }>;
+  }>;
+  updateAgent(agentId: string, updates: { name?: string }): Promise<void>;
+  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 }>;
+  fetchAgentHistory(options?: {
+    page?: { limit: number };
+  }): Promise<{ entries: Array<{ 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(): Promise<SeedDaemonClient> {
+  return connectDaemonClient<SeedDaemonClient>({
+    clientIdPrefix: "seed",
+    appVersion: loadAppVersion(),
+  });
+}
+
+/**
+ * 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;
+  /** Stable project identity the daemon groups workspaces under. */
+  projectId: 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;
+  /** 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();
+  try {
+    const opened = await client.openProject(project.path);
+    if (!opened.workspace) {
+      throw new Error(opened.error ?? `Failed to open project ${project.path}`);
+    }
+    return {
+      client,
+      repoPath: project.path,
+      workspaceId: opened.workspace.id,
+      workspaceName: opened.workspace.name,
+      workspaceDirectory: opened.workspace.workspaceDirectory,
+      projectId: opened.workspace.projectId,
+      projectDisplayName: opened.workspace.projectDisplayName,
+      cleanup: async () => {
+        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/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 Playwright globalSetup).");
+  }
+  return serverId;
+}

packages/app/e2e/helpers/settings.ts

@@ -1,9 +1,6 @@
 import { expect, type Page } from "@playwright/test";
-import { requireServerId } from "./sidebar";
-
-function escapeRegex(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
+import { escapeRegex } from "./regex";
+import { getServerId } from "./server-id";
 
 const SECTION_LABELS = {
   general: "General",
@@ -113,13 +110,13 @@ export async function expectHostSettingsUrl(page: Page, serverId: string): Promi
 }
 
 export async function verifyLegacyHostSettingsRedirect(page: Page): Promise<void> {
-  const serverId = requireServerId();
+  const serverId = getServerId();
   await page.goto(`/h/${encodeURIComponent(serverId)}/settings`);
   await expectHostSettingsUrl(page, serverId);
 }
 
 export async function openCompactSettingsHost(page: Page): Promise<void> {
-  const serverId = requireServerId();
+  const serverId = getServerId();
   await openSettingsHost(page, serverId);
   await expectHostSettingsUrl(page, serverId);
 }
@@ -159,7 +156,7 @@ export async function expectDiagnosticsContent(page: Page): Promise<void> {
 }
 
 export async function expectAboutContent(page: Page): Promise<void> {
-  await expect(page.getByText("Version", { exact: true }).first()).toBeVisible();
+  await expect(page.getByText("App version", { exact: true }).first()).toBeVisible();
 }
 
 export async function expectGeneralContent(page: Page): Promise<void> {
@@ -168,7 +165,7 @@ export async function expectGeneralContent(page: Page): Promise<void> {
 
 export async function expectHostLabelDisplayed(page: Page): Promise<void> {
   await expect(page.getByTestId("host-page-label-edit-button")).toBeVisible();
-  await expect(page.getByTestId("host-page-label-input")).toHaveCount(0);
+  await expect(page.getByTestId("host-page-rename-modal-input")).toHaveCount(0);
 }
 
 export async function clickEditHostLabel(page: Page): Promise<void> {
@@ -176,9 +173,9 @@ export async function clickEditHostLabel(page: Page): Promise<void> {
 }
 
 export async function expectHostLabelEditMode(page: Page, expectedLabel: string): Promise<void> {
-  await expect(page.getByTestId("host-page-label-input")).toBeVisible();
-  await expect(page.getByTestId("host-page-label-input")).toHaveValue(expectedLabel);
-  await expect(page.getByTestId("host-page-label-save")).toBeVisible();
+  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> {

packages/app/e2e/helpers/sidebar.ts

@@ -1,15 +1,8 @@
 import { expect, type Page } from "@playwright/test";
-
-export function requireServerId(): string {
-  const serverId = process.env.E2E_SERVER_ID;
-  if (!serverId) {
-    throw new Error("E2E_SERVER_ID is not set (expected from Playwright globalSetup).");
-  }
-  return serverId;
-}
+import { getServerId } from "./server-id";
 
 export async function selectWorkspaceInSidebar(page: Page, workspaceId: string): Promise<void> {
-  const row = page.getByTestId(`sidebar-workspace-row-${requireServerId()}:${workspaceId}`);
+  const row = page.getByTestId(`sidebar-workspace-row-${getServerId()}:${workspaceId}`);
   await expect(row).toBeVisible({ timeout: 30_000 });
   await row.click();
 }
@@ -24,9 +17,10 @@ export async function openMobileAgentSidebar(page: Page): Promise<void> {
   await page.getByRole("button", { name: "Open menu" }).click();
 }
 
-// force=true: the overlay covers the button when the mobile sidebar is open.
 export async function closeMobileAgentSidebar(page: Page): Promise<void> {
-  await page.getByRole("button", { name: "Close menu" }).click({ force: true });
+  const closeButton = page.getByTestId("sidebar-close");
+  await expect(closeButton).toBeInViewport({ timeout: 5_000 });
+  await closeButton.click({ force: true });
 }
 
 // The mobile sidebar panel animates via translateX; toBeInViewport reflects the rendered position.

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

@@ -1,5 +1,6 @@
 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";
@@ -78,7 +79,7 @@ class StartupScenario {
     }
 
     for (const port of this.blockedEndpointPorts) {
-      await this.page.routeWebSocket(new RegExp(`:${escapeRegex(port)}\\b`), async (ws) => {
+      await this.page.routeWebSocket(wsRoutePatternForPort(port), async (ws) => {
         await ws.close({ code: 1008, reason: "Blocked unreachable startup test host." });
       });
     }
@@ -227,7 +228,3 @@ function buildStoredHost(input: {
 function buildStoredCreateAgentPreferences(serverId: string) {
   return buildCreateAgentPreferences(serverId);
 }
-
-function escapeRegex(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}

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

@@ -1,11 +1,7 @@
 import type { Page } from "@playwright/test";
 import { createTempGitRepo } from "./workspace";
-import {
-  connectTerminalClient,
-  navigateToTerminal,
-  setupDeterministicPrompt,
-  type TerminalPerfDaemonClient,
-} from "./terminal-perf";
+import { navigateToTerminal, setupDeterministicPrompt } from "./terminal-perf";
+import { connectSeedClient, type SeedDaemonClient } from "./seed-client";
 
 interface TempRepo {
   path: string;
@@ -19,12 +15,12 @@ export interface TerminalInstance {
 }
 
 export class TerminalE2EHarness {
-  readonly client: TerminalPerfDaemonClient;
+  readonly client: SeedDaemonClient;
   readonly tempRepo: TempRepo;
   readonly workspaceId: string;
 
   private constructor(input: {
-    client: TerminalPerfDaemonClient;
+    client: SeedDaemonClient;
     tempRepo: TempRepo;
     workspaceId: string;
   }) {
@@ -35,7 +31,7 @@ export class TerminalE2EHarness {
 
   static async create(input: { tempPrefix: string }): Promise<TerminalE2EHarness> {
     const tempRepo = await createTempGitRepo(input.tempPrefix);
-    const client = await connectTerminalClient();
+    const client = await connectSeedClient();
     const seedResult = await client.openProject(tempRepo.path);
     if (!seedResult.workspace) {
       await client.close().catch(() => {});

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

@@ -1,96 +1,6 @@
 import { expect, type Page } from "@playwright/test";
-import path from "node:path";
-import { pathToFileURL } from "node:url";
-import { randomUUID } from "node:crypto";
-import { createNodeWebSocketFactory, type NodeWebSocketFactory } from "./node-ws-factory";
 import { buildHostWorkspaceRoute } from "../../src/utils/host-routes";
-
-export interface TerminalPerfDaemonClient {
-  connect(): Promise<void>;
-  close(): Promise<void>;
-  openProject(cwd: string): Promise<{
-    workspace: { id: string; name: string; projectRootPath: string } | null;
-    error: string | null;
-  }>;
-  createTerminal(
-    cwd: string,
-    name?: string,
-  ): Promise<{
-    terminal: { id: string; name: string; cwd: string } | null;
-    error: string | null;
-  }>;
-  createAgent(options: {
-    provider: string;
-    cwd: string;
-    title?: string;
-    modeId?: string;
-    model?: string;
-    thinkingOptionId?: string;
-    featureValues?: Record<string, unknown>;
-    initialPrompt?: string;
-  }): Promise<{ id: string; status: string }>;
-  sendAgentMessage(agentId: string, text: string): Promise<void>;
-  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 }>;
-}
-
-function getDaemonWsUrl(): string {
-  const daemonPort = process.env.E2E_DAEMON_PORT;
-  if (!daemonPort) {
-    throw new Error("E2E_DAEMON_PORT is not set.");
-  }
-  return `ws://127.0.0.1:${daemonPort}/ws`;
-}
-
-function getServerId(): string {
-  const serverId = process.env.E2E_SERVER_ID;
-  if (!serverId) {
-    throw new Error("E2E_SERVER_ID is not set.");
-  }
-  return serverId;
-}
-
-interface TerminalPerfDaemonClientConfig {
-  url: string;
-  clientId: string;
-  clientType: "cli";
-  webSocketFactory?: NodeWebSocketFactory;
-}
-
-async function loadDaemonClientConstructor(): Promise<
-  new (config: TerminalPerfDaemonClientConfig) => TerminalPerfDaemonClient
-> {
-  const repoRoot = path.resolve(__dirname, "../../../../");
-  const moduleUrl = pathToFileURL(
-    path.join(repoRoot, "packages/server/dist/server/server/exports.js"),
-  ).href;
-  const mod = (await import(moduleUrl)) as {
-    DaemonClient: new (config: TerminalPerfDaemonClientConfig) => TerminalPerfDaemonClient;
-  };
-  return mod.DaemonClient;
-}
-
-export async function connectTerminalClient(): Promise<TerminalPerfDaemonClient> {
-  const DaemonClient = await loadDaemonClientConstructor();
-  const webSocketFactory = createNodeWebSocketFactory();
-  const client = new DaemonClient({
-    url: getDaemonWsUrl(),
-    clientId: `terminal-perf-${randomUUID()}`,
-    clientType: "cli",
-    webSocketFactory,
-  });
-  await client.connect();
-  return client;
-}
+import { getServerId } from "./server-id";
 
 export function buildTerminalWorkspaceUrl(workspaceId: string, terminalId: string): string {
   const serverId = getServerId();

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

@@ -1,10 +1,9 @@
 import { execSync } from "node:child_process";
-import { realpath } from "node:fs/promises";
 import path from "node:path";
 import type { Page } from "@playwright/test";
 import { waitForTabBar } from "./launcher";
 import { selectWorkspaceInSidebar } from "./sidebar";
-import { createTempGitRepo } from "./workspace";
+import { createTempGitRepo, resolveTempRoot } from "./workspace";
 import {
   connectWorkspaceSetupClient,
   openHomeWithProject,
@@ -49,7 +48,7 @@ export function createWithWorkspace(page: Page): WithWorkspaceHandle {
 
     let workspacePath = repo.path;
     if (options?.worktree) {
-      const tempRoot = await realpath("/tmp");
+      const tempRoot = await resolveTempRoot();
       workspacePath = path.join(
         tempRoot,
         `paseo-wt-${Date.now()}-${Math.random().toString(36).slice(2)}`,

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

@@ -1,59 +1,25 @@
 import { realpathSync } from "node:fs";
-import path from "node:path";
-import { randomUUID } from "node:crypto";
-import { pathToFileURL } from "node:url";
 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 { createNodeWebSocketFactory, type NodeWebSocketFactory } from "./node-ws-factory";
+import { connectDaemonClient } from "./daemon-client-loader";
+import { getServerId } from "./server-id";
 import { switchWorkspaceViaSidebar } from "./workspace-ui";
-import type { SessionOutboundMessage } from "@server/shared/messages";
+import type { SessionOutboundMessage } from "@getpaseo/protocol/messages";
 
-interface WorkspaceSetupDaemonClient {
-  connect(): Promise<void>;
-  close(): Promise<void>;
-  openProject(cwd: string): Promise<{
-    workspace: {
-      id: string;
-      name: string;
-      workspaceDirectory: string;
-      projectRootPath: string;
-    } | null;
-    error: string | null;
-  }>;
-  createPaseoWorktree(input: { cwd: string; worktreeSlug?: string }): Promise<{
-    workspace: {
-      id: string;
-      name: string;
-      workspaceDirectory: string;
-      projectRootPath: string;
-    } | null;
-    error: string | null;
-  }>;
-  fetchWorkspaces(): Promise<{
-    entries: Array<{
-      id: string;
-      name: string;
-      workspaceDirectory: string;
-      projectRootPath: string;
-    }>;
-  }>;
-  fetchAgents(): Promise<{
-    entries: Array<{
-      agent: { id: string; cwd: string; workspaceId?: string | null };
-    }>;
-  }>;
-  fetchAgent(agentId: string): Promise<{
-    agent: { id: string; cwd: string } | null;
-    project: unknown;
-  } | null>;
-  listTerminals(cwd: string): Promise<{
-    cwd?: string;
-    terminals: Array<{ id: string; cwd: string; name: string }>;
-    error?: string | null;
-  }>;
-  subscribeRawMessages(handler: (message: SessionOutboundMessage) => void): () => void;
-}
+type WorkspaceSetupDaemonClient = Pick<
+  InternalDaemonClient,
+  | "close"
+  | "connect"
+  | "createPaseoWorktree"
+  | "fetchAgent"
+  | "fetchAgents"
+  | "fetchWorkspaces"
+  | "listTerminals"
+  | "openProject"
+  | "subscribeRawMessages"
+>;
 
 export type WorkspaceSetupProgressPayload = Extract<
   SessionOutboundMessage,
@@ -62,58 +28,30 @@ export type WorkspaceSetupProgressPayload = Extract<
 
 export type { WorkspaceSetupDaemonClient };
 
-function getDaemonWsUrl(): string {
-  const daemonPort = process.env.E2E_DAEMON_PORT;
-  if (!daemonPort) {
-    throw new Error("E2E_DAEMON_PORT is not set.");
-  }
-  return `ws://127.0.0.1:${daemonPort}/ws`;
-}
-
-async function loadDaemonClientConstructor(): Promise<
-  new (config: {
-    url: string;
-    clientId: string;
-    clientType: "cli";
-    webSocketFactory?: NodeWebSocketFactory;
-  }) => WorkspaceSetupDaemonClient
-> {
-  const repoRoot = path.resolve(process.cwd(), "../..");
-  const moduleUrl = pathToFileURL(
-    path.join(repoRoot, "packages/server/dist/server/server/exports.js"),
-  ).href;
-  const mod = (await import(moduleUrl)) as {
-    DaemonClient: new (config: {
-      url: string;
-      clientId: string;
-      clientType: "cli";
-      webSocketFactory?: NodeWebSocketFactory;
-    }) => WorkspaceSetupDaemonClient;
-  };
-  return mod.DaemonClient;
-}
-
 export async function connectWorkspaceSetupClient(): Promise<WorkspaceSetupDaemonClient> {
-  const DaemonClient = await loadDaemonClientConstructor();
-  const webSocketFactory = createNodeWebSocketFactory();
-  const client = new DaemonClient({
-    url: getDaemonWsUrl(),
-    clientId: `workspace-setup-${randomUUID()}`,
-    clientType: "cli",
-    webSocketFactory,
-  });
-  await client.connect();
-  return client;
+  return connectDaemonClient<WorkspaceSetupDaemonClient>({ clientIdPrefix: "workspace-setup" });
+}
+
+export async function openProjectViaDaemon(
+  client: WorkspaceSetupDaemonClient,
+  repoPath: string,
+): Promise<{ id: string; name: string; workspaceDirectory: string }> {
+  const result = await client.openProject(repoPath);
+  if (!result.workspace || result.error) {
+    throw new Error(result.error ?? `Failed to open project ${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.openProject(repoPath);
-  if (!result.workspace || result.error) {
-    throw new Error(result.error ?? `Failed to open project ${repoPath}`);
-  }
+  await openProjectViaDaemon(client, repoPath);
 }
 
 export function projectNameFromPath(repoPath: string): string {
@@ -320,11 +258,11 @@ export async function navigateToWorkspaceViaSidebar(
   page: Page,
   workspaceId: string,
 ): Promise<void> {
-  const serverId = process.env.E2E_SERVER_ID;
-  if (!serverId) {
-    throw new Error("E2E_SERVER_ID is not set.");
-  }
-  await switchWorkspaceViaSidebar({ page, serverId, targetWorkspacePath: workspaceId });
+  await switchWorkspaceViaSidebar({
+    page,
+    serverId: getServerId(),
+    targetWorkspacePath: workspaceId,
+  });
 }
 
 export async function openWorkspaceScriptsMenu(page: Page): Promise<void> {

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

@@ -1,6 +1,7 @@
 import { expect, type Page } from "@playwright/test";
 import { buildHostWorkspaceRoute } from "@/utils/host-routes";
 import { gotoHome } from "./app";
+import { escapeRegex } from "./regex";
 
 export async function openNewAgentComposer(page: Page): Promise<void> {
   await gotoHome(page);
@@ -23,10 +24,6 @@ export function workspaceLabelFromPath(value: string): string {
   return parts[parts.length - 1] ?? normalized;
 }
 
-function escapeRegex(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
 function candidateWorkspaceIds(inputPath: string): string[] {
   const trimmed = inputPath.replace(/\/+$/, "");
   const candidates = new Set<string>([trimmed]);

packages/app/e2e/helpers/workspace.ts

@@ -9,6 +9,20 @@ interface TempRepo {
   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;
@@ -22,6 +36,15 @@ async function configureRemote(input: {
     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) {
@@ -44,9 +67,7 @@ export const createTempGitRepo = async (
   },
 ): Promise<TempRepo> => {
   // Keep E2E repo paths short so terminal prompt + typed commands stay visible without zsh clipping.
-  // Resolve symlinks (macOS: /tmp → /private/tmp) so paths match the daemon's resolved paths.
-  const tempRoot = process.platform === "win32" ? tmpdir() : await realpath("/tmp");
-  const repoPath = await mkdtemp(path.join(tempRoot, prefix));
+  const repoPath = await mkdtemp(path.join(await resolveTempRoot(), prefix));
   const withRemote = options?.withRemote ?? false;
 
   execSync("git init -b main", { cwd: repoPath, stdio: "ignore" });
@@ -110,6 +131,21 @@ export const createTempGitRepo = async (
   };
 };
 
+/**
+ * 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 });
+    },
+  };
+}
+
 export async function readWorktreeBranchInfo({ worktreePath }: { worktreePath: string }): Promise<{
   currentBranch: string;
   hasAncestor: (ref: string) => boolean;

packages/app/e2e/launcher-tab.spec.ts

@@ -1,5 +1,4 @@
 import { test, expect } from "./fixtures";
-import { createTempGitRepo } from "./helpers/workspace";
 import {
   gotoWorkspace,
   assertNewChatTileVisible,
@@ -16,30 +15,19 @@ import {
   terminalSurfaceLocator,
 } from "./helpers/launcher";
 import { expectComposerVisible, composerLocator } from "./helpers/composer";
-import { expectTerminalSurfaceVisible } from "./helpers/terminal-perf";
-import {
-  connectTerminalClient,
-  setupDeterministicPrompt,
-  type TerminalPerfDaemonClient,
-} from "./helpers/terminal-perf";
+import { expectTerminalSurfaceVisible, setupDeterministicPrompt } from "./helpers/terminal-perf";
+import { seedWorkspace, type SeededWorkspace } from "./helpers/seed-client";
 
 // ─── Shared state ──────────────────────────────────────────────────────────
 
-let tempRepo: { path: string; cleanup: () => Promise<void> };
-let workspaceId: string;
-let seedClient: TerminalPerfDaemonClient;
+let workspace: SeededWorkspace;
 
 test.beforeAll(async () => {
-  tempRepo = await createTempGitRepo("launcher-e2e-");
-  seedClient = await connectTerminalClient();
-  const result = await seedClient.openProject(tempRepo.path);
-  if (!result.workspace) throw new Error(result.error ?? "Failed to seed workspace");
-  workspaceId = result.workspace.id;
+  workspace = await seedWorkspace({ repoPrefix: "launcher-e2e-" });
 });
 
 test.afterAll(async () => {
-  if (seedClient) await seedClient.close();
-  if (tempRepo) await tempRepo.cleanup();
+  await workspace?.cleanup();
 });
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -48,7 +36,7 @@ test.afterAll(async () => {
 
 test.describe("Tab creation", () => {
   test("Cmd+T opens a new agent tab with composer", async ({ page }) => {
-    await gotoWorkspace(page, workspaceId);
+    await gotoWorkspace(page, workspace.workspaceId);
 
     await pressNewTabShortcut(page);
 
@@ -56,7 +44,7 @@ test.describe("Tab creation", () => {
   });
 
   test("opening two new tabs creates two draft tabs", async ({ page }) => {
-    await gotoWorkspace(page, workspaceId);
+    await gotoWorkspace(page, workspace.workspaceId);
 
     const countBefore = await countTabsOfKind(page, "draft");
 
@@ -75,7 +63,7 @@ test.describe("Tab creation", () => {
   });
 
   test("clicking new agent tab creates a draft tab", async ({ page }) => {
-    await gotoWorkspace(page, workspaceId);
+    await gotoWorkspace(page, workspace.workspaceId);
 
     await clickNewChat(page);
 
@@ -88,7 +76,7 @@ test.describe("Tab creation", () => {
 
   test("clicking terminal button creates a standalone terminal", async ({ page }) => {
     test.setTimeout(45_000);
-    await gotoWorkspace(page, workspaceId);
+    await gotoWorkspace(page, workspace.workspaceId);
 
     await clickNewTerminal(page);
 
@@ -100,7 +88,7 @@ test.describe("Tab creation", () => {
   });
 
   test("tab bar shows action buttons per pane", async ({ page }) => {
-    await gotoWorkspace(page, workspaceId);
+    await gotoWorkspace(page, workspace.workspaceId);
     await assertSingleNewTabButton(page);
     await assertNewChatTileVisible(page);
     await assertTerminalTileVisible(page);
@@ -117,26 +105,16 @@ test.describe("Terminal title propagation", () => {
   // must re-render before the assertion deadline. Allow retries.
   test.describe.configure({ retries: 2 });
 
-  let client: TerminalPerfDaemonClient;
-
-  test.beforeAll(async () => {
-    client = await connectTerminalClient();
-  });
-
-  test.afterAll(async () => {
-    if (client) await client.close();
-  });
-
   test.skip("terminal tab title updates from OSC title escape sequence", async ({ page }) => {
     test.setTimeout(60_000);
 
-    const result = await client.createTerminal(tempRepo.path, "title-test");
+    const result = await workspace.client.createTerminal(workspace.repoPath, "title-test");
     if (!result.terminal) throw new Error(`Failed to create terminal: ${result.error}`);
     const terminalId = result.terminal.id;
 
     try {
       // Navigate to workspace and open a terminal
-      await gotoWorkspace(page, workspaceId);
+      await gotoWorkspace(page, workspace.workspaceId);
       await clickNewTerminal(page);
 
       await expectTerminalSurfaceVisible(page);
@@ -153,19 +131,19 @@ test.describe("Terminal title propagation", () => {
       // Wait for the tab to reflect the new title
       await waitForTabWithTitle(page, testTitle, 15_000);
     } finally {
-      await client.killTerminal(terminalId).catch(() => {});
+      await workspace.client.killTerminal(terminalId).catch(() => {});
     }
   });
 
   test.skip("title debouncing coalesces rapid changes", async ({ page }) => {
     test.setTimeout(60_000);
 
-    const result = await client.createTerminal(tempRepo.path, "debounce-test");
+    const result = await workspace.client.createTerminal(workspace.repoPath, "debounce-test");
     if (!result.terminal) throw new Error(`Failed to create terminal: ${result.error}`);
     const terminalId = result.terminal.id;
 
     try {
-      await gotoWorkspace(page, workspaceId);
+      await gotoWorkspace(page, workspace.workspaceId);
       await clickNewTerminal(page);
 
       await expectTerminalSurfaceVisible(page);
@@ -188,7 +166,7 @@ test.describe("Terminal title propagation", () => {
       // The tab should eventually settle on the final title
       await waitForTabWithTitle(page, finalTitle, 15_000);
     } finally {
-      await client.killTerminal(terminalId).catch(() => {});
+      await workspace.client.killTerminal(terminalId).catch(() => {});
     }
   });
 });
@@ -199,7 +177,7 @@ test.describe("Terminal title propagation", () => {
 
 test.describe("Tab transitions (no flash)", () => {
   test("New agent tab transition has no blank intermediate tab state", async ({ page }) => {
-    await gotoWorkspace(page, workspaceId);
+    await gotoWorkspace(page, workspace.workspaceId);
 
     // Sample tabs at high frequency across the transition
     const snapshots = await sampleTabsDuringTransition(page, () => clickNewChat(page), 2_000, 30);
@@ -221,7 +199,7 @@ test.describe("Tab transitions (no flash)", () => {
 
   test("Terminal transition completes within visual budget", async ({ page }) => {
     test.setTimeout(30_000);
-    await gotoWorkspace(page, workspaceId);
+    await gotoWorkspace(page, workspace.workspaceId);
 
     const elapsed = await measureTileTransition(
       page,
@@ -237,7 +215,7 @@ test.describe("Tab transitions (no flash)", () => {
   });
 
   test("New agent tab click shows composer without flash", async ({ page }) => {
-    await gotoWorkspace(page, workspaceId);
+    await gotoWorkspace(page, workspace.workspaceId);
 
     const elapsed = await measureTileTransition(
       page,

packages/app/e2e/new-workspace.spec.ts

@@ -26,6 +26,7 @@ import {
   selectPickerOptionByKeyboard,
 } from "./helpers/new-workspace";
 import { createTempGitRepo, readWorktreeBranchInfo } from "./helpers/workspace";
+import { getServerId } from "./helpers/server-id";
 import {
   expectSidebarWorkspaceSelected,
   expectWorkspaceHeader,
@@ -61,10 +62,7 @@ test.describe("New workspace flow", () => {
   });
 
   test("sidebar workspace navigation updates URL and header", async ({ page }) => {
-    const serverId = process.env.E2E_SERVER_ID;
-    if (!serverId) {
-      throw new Error("E2E_SERVER_ID is not set.");
-    }
+    const serverId = getServerId();
 
     const firstRepo = await createTempGitRepo("workspace-nav-a-");
     const secondRepo = await createTempGitRepo("workspace-nav-b-");
@@ -118,10 +116,7 @@ test.describe("New workspace flow", () => {
   });
 
   test("same-project workspaces switch content without requiring refresh", async ({ page }) => {
-    const serverId = process.env.E2E_SERVER_ID;
-    if (!serverId) {
-      throw new Error("E2E_SERVER_ID is not set.");
-    }
+    const serverId = getServerId();
 
     const repo = await createTempGitRepo("workspace-nav-same-project-");
 
@@ -201,10 +196,7 @@ test.describe("New workspace flow", () => {
   test("clicking new workspace redirects, renders header, shows sidebar row, and keeps one agent tab", async ({
     page,
   }) => {
-    const serverId = process.env.E2E_SERVER_ID;
-    if (!serverId) {
-      throw new Error("E2E_SERVER_ID is not set.");
-    }
+    const serverId = getServerId();
 
     const tempRepo = await createTempGitRepo("new-workspace-");
 
@@ -276,10 +268,7 @@ test.describe("New workspace flow", () => {
   });
 
   test("redirects to the optimistic draft tab before agent creation resolves", async ({ page }) => {
-    const serverId = process.env.E2E_SERVER_ID;
-    if (!serverId) {
-      throw new Error("E2E_SERVER_ID is not set.");
-    }
+    const serverId = getServerId();
 
     const tempRepo = await createTempGitRepo("new-workspace-optimistic-");
     const agentCreatedDelay = await delayBrowserAgentCreatedStatus(page);
@@ -355,10 +344,7 @@ test.describe("New workspace flow", () => {
   });
 
   test("selected branch becomes the base of a new workspace worktree", async ({ page }) => {
-    const serverId = process.env.E2E_SERVER_ID;
-    if (!serverId) {
-      throw new Error("E2E_SERVER_ID is not set.");
-    }
+    const serverId = getServerId();
 
     const tempRepo = await createTempGitRepo("new-workspace-ref-", {
       branches: ["main", "dev"],

packages/app/e2e/pr-pane.spec.ts

@@ -10,6 +10,7 @@ import { gotoWorkspace } from "./helpers/launcher";
 import { hasGithubAuth, createTempGithubRepo, type GhRepoFixture } from "./helpers/github-fixtures";
 import {
   connectWorkspaceSetupClient,
+  openProjectViaDaemon,
   type WorkspaceSetupDaemonClient,
 } from "./helpers/workspace-setup";
 
@@ -50,11 +51,8 @@ test.describe("PR pane", () => {
     });
 
     for (const pr of repoFixture.prs) {
-      const result = await seedClient.openProject(pr.localPath);
-      if (!result.workspace) {
-        throw new Error(result.error ?? `Failed to open project ${pr.localPath}`);
-      }
-      workspaceByTitle.set(pr.title, result.workspace.id);
+      const workspace = await openProjectViaDaemon(seedClient, pr.localPath);
+      workspaceByTitle.set(pr.title, workspace.id);
     }
   });
 

packages/app/e2e/projects-settings.spec.ts

@@ -1,8 +1,7 @@
 import { chmod, readFile } from "node:fs/promises";
 import path from "node:path";
 import { expect, test as base } from "./fixtures";
-import { connectNewWorkspaceDaemonClient, openProjectViaDaemon } from "./helpers/new-workspace";
-import { createTempGitRepo } from "./helpers/workspace";
+import { seedWorkspace } from "./helpers/seed-client";
 import {
   blockPaseoConfigWrites,
   bumpPaseoConfigOnDisk,
@@ -63,38 +62,36 @@ const initialPaseoConfig = {
 
 const test = base.extend<ProjectsSettingsFixtures>({
   editableProject: async ({ page: _page }, provide) => {
-    const client = await connectNewWorkspaceDaemonClient();
-    const repo = await createTempGitRepo("projects-settings-", {
-      paseoConfig: initialPaseoConfig,
+    const workspace = await seedWorkspace({
+      repoPrefix: "projects-settings-",
+      repo: { paseoConfig: initialPaseoConfig },
     });
-    const openedProject = await openProjectViaDaemon(client, repo.path);
 
     await provide({
-      name: openedProject.projectDisplayName,
-      path: repo.path,
+      name: workspace.projectDisplayName,
+      path: workspace.repoPath,
     });
 
-    await client.close();
     // Defensive: restore directory write permission in case the test left it blocked
-    // (write_failed test), so that repo.cleanup() can remove files inside.
-    await chmod(repo.path, 0o755).catch(() => undefined);
-    await repo.cleanup();
+    // (write_failed test), so that cleanup can remove files inside.
+    await chmod(workspace.repoPath, 0o755).catch(() => undefined);
+    await workspace.cleanup();
   },
   gitlabRemoteProject: async ({ page: _page }, provide) => {
-    const client = await connectNewWorkspaceDaemonClient();
-    const repo = await createTempGitRepo("projects-settings-gitlab-", {
-      paseoConfig: initialPaseoConfig,
-      originUrl: "https://gitlab.com/acme/app.git",
+    const workspace = await seedWorkspace({
+      repoPrefix: "projects-settings-gitlab-",
+      repo: {
+        paseoConfig: initialPaseoConfig,
+        originUrl: "https://gitlab.com/acme/app.git",
+      },
     });
-    const openedProject = await openProjectViaDaemon(client, repo.path);
 
     await provide({
-      name: openedProject.projectDisplayName,
-      path: repo.path,
+      name: workspace.projectDisplayName,
+      path: workspace.repoPath,
     });
 
-    await client.close();
-    await repo.cleanup();
+    await workspace.cleanup();
   },
 });
 

packages/app/e2e/rewind-flow.claude.real.spec.ts

@@ -0,0 +1,7 @@
+import { defineRewindFlowSpec } from "./rewind-flow.shared";
+
+defineRewindFlowSpec({
+  provider: "claude",
+  rewindMode: "both",
+  fileReverted: true,
+});

packages/app/e2e/rewind-flow.codex.real.spec.ts

@@ -0,0 +1,7 @@
+import { defineRewindFlowSpec } from "./rewind-flow.shared";
+
+defineRewindFlowSpec({
+  provider: "codex",
+  rewindMode: "conversation",
+  fileReverted: false,
+});

packages/app/e2e/rewind-flow.opencode.real.spec.ts

@@ -0,0 +1,8 @@
+import { defineRewindFlowSpec } from "./rewind-flow.shared";
+
+defineRewindFlowSpec({
+  provider: "opencode",
+  initialRewindMode: "both",
+  rewindMode: "both",
+  fileReverted: true,
+});

packages/app/e2e/rewind-flow.pi.real.spec.ts

@@ -0,0 +1,7 @@
+import { defineRewindFlowSpec } from "./rewind-flow.shared";
+
+defineRewindFlowSpec({
+  provider: "pi",
+  rewindMode: "conversation",
+  fileReverted: false,
+});

packages/app/e2e/rewind-flow.shared.ts

@@ -0,0 +1,88 @@
+import { mkdtempSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { test } from "./fixtures";
+import {
+  assertChatTranscript,
+  assertComposerIdle,
+  assertFileContains,
+  assertFileExists,
+  assertFileMissing,
+  cleanupRewindFlow,
+  launchAgent,
+  rewindMessage,
+  sendMessage,
+  type AgentHandle,
+  type RewindFlowMode,
+  type RewindFlowProvider,
+} from "./helpers/rewind-flow";
+
+const FILE_PROMPT = "Use the Write tool to create ./qa.txt with the exact content: PASEO_QA_TOKEN";
+
+interface RewindFlowCase {
+  provider: RewindFlowProvider;
+  initialRewindMode?: RewindFlowMode;
+  rewindMode: RewindFlowMode;
+  fileReverted: boolean;
+}
+
+export function defineRewindFlowSpec(input: RewindFlowCase): void {
+  test.describe(`rewind flow - ${input.provider}`, () => {
+    test.setTimeout(600_000);
+
+    test("rewinds conversation and file-write turns without transcript drift", async ({ page }) => {
+      const cwd = realpathSync(
+        mkdtempSync(path.join(tmpdir(), `paseo-rewind-flow-${input.provider}-`)),
+      );
+      let handle: AgentHandle | undefined;
+
+      try {
+        handle = await launchAgent({
+          page,
+          provider: input.provider,
+          cwd,
+          mode: "full-access",
+        });
+
+        await sendMessage(handle, "hello");
+        await assertChatTranscript(handle, [
+          { role: "user", text: "hello" },
+          { role: "assistant", text: /.+/ },
+        ]);
+
+        await rewindMessage(handle, 0, input.initialRewindMode ?? "conversation");
+        await assertChatTranscript(handle, []);
+        await assertComposerIdle(handle);
+
+        await sendMessage(handle, "hello");
+        await assertChatTranscript(handle, [
+          { role: "user", text: "hello" },
+          { role: "assistant", text: /.+/ },
+        ]);
+
+        await sendMessage(handle, FILE_PROMPT);
+        await assertFileContains(path.join(cwd, "qa.txt"), "PASEO_QA_TOKEN");
+        await assertChatTranscript(handle, [
+          { role: "user", text: "hello" },
+          { role: "assistant", text: /.+/ },
+          { role: "user", text: /Use the Write tool/ },
+          { role: "assistant", text: /.+/ },
+        ]);
+
+        await rewindMessage(handle, 1, input.rewindMode);
+        if (input.fileReverted) {
+          await assertFileMissing(path.join(cwd, "qa.txt"));
+        } else {
+          await assertFileExists(path.join(cwd, "qa.txt"));
+        }
+        await assertChatTranscript(handle, [
+          { role: "user", text: "hello" },
+          { role: "assistant", text: /.+/ },
+        ]);
+        await assertComposerIdle(handle);
+      } finally {
+        await cleanupRewindFlow({ handle, cwd });
+      }
+    });
+  });
+}

packages/app/e2e/rewind-menu.ui-contract.spec.ts

@@ -0,0 +1,132 @@
+import { expect, test, type Page } from "./fixtures";
+import { openAgentRoute, seedMockAgentWorkspace } from "./helpers/mock-agent";
+import {
+  composerLocator,
+  expectComposerDraft,
+  expectComposerVisible,
+  fillComposerDraft,
+  submitMessage,
+} from "./helpers/composer";
+
+// UI plumbing contract against the dev mock provider. Real-provider behavior is tested in `daemon-e2e/*-rewind.real.e2e.test.ts`.
+
+async function expectUserMessageCount(page: Page, expected: number): Promise<void> {
+  await expect(page.getByTestId("user-message")).toHaveCount(expected);
+}
+
+test.describe("Rewind sheet", () => {
+  test("rewinds from a user message sheet option", async ({ page }) => {
+    const firstPrompt = "emit 1 coalesced agent stream updates for first rewind turn.";
+    const secondPrompt = "Prepare deleted rewind turn assistant content.";
+    const replacementPrompt = "emit 1 coalesced agent stream updates for replacement rewind turn.";
+    const session = await seedMockAgentWorkspace({
+      repoPrefix: "rewind-e2e-",
+      title: "Rewind e2e",
+      initialPrompt: firstPrompt,
+    });
+
+    try {
+      await openAgentRoute(page, session);
+      await expectComposerVisible(page);
+
+      await expect(page.getByText(firstPrompt, { exact: true })).toBeVisible();
+      await expectUserMessageCount(page, 1);
+      await submitMessage(page, secondPrompt);
+      await expect(page.getByText(secondPrompt, { exact: true })).toBeVisible();
+      await expect(page.getByText("Cycle 1", { exact: true })).toBeVisible();
+      await expectUserMessageCount(page, 2);
+
+      await page.getByText(firstPrompt, { exact: true }).hover();
+      await page.getByTestId("rewind-menu-trigger").first().click();
+      const rewindSheet = page.getByTestId("rewind-menu-content");
+      await expect(rewindSheet).toBeVisible();
+      await expect(
+        rewindSheet.getByText("This action cannot be undone", { exact: true }),
+      ).toBeVisible();
+      await page.getByTestId("rewind-menu-conversation").click();
+
+      await expect(page.getByTestId("rewind-menu-content")).toHaveCount(0);
+      await expect(page.getByText(secondPrompt, { exact: true })).toHaveCount(0);
+      await expect(page.getByText("Cycle 1", { exact: true })).toHaveCount(0);
+      await expectUserMessageCount(page, 1);
+      await expectComposerDraft(page, firstPrompt);
+
+      await submitMessage(page, replacementPrompt);
+      await expect(page.getByText(replacementPrompt, { exact: true })).toBeVisible();
+      await expect(page.getByText(secondPrompt, { exact: true })).toHaveCount(0);
+      await expect(page.getByText("Cycle 1", { exact: true })).toHaveCount(0);
+      await expectUserMessageCount(page, 2);
+
+      await fillComposerDraft(page, "");
+      await composerLocator(page).evaluate((element) => element.blur());
+      await page.getByText(replacementPrompt, { exact: true }).hover();
+      await page.getByTestId("rewind-menu-trigger").last().click();
+      await expect(page.getByTestId("rewind-menu-content")).toBeVisible();
+      await page.getByTestId("rewind-menu-files").click();
+      await expect(page.getByTestId("rewind-menu-content")).toHaveCount(0);
+      await expectComposerDraft(page, "");
+      await expectUserMessageCount(page, 2);
+
+      const preservedDraft = "Keep this human draft after rewind.";
+      await fillComposerDraft(page, preservedDraft);
+      await composerLocator(page).evaluate((element) => element.blur());
+      await page.getByText(replacementPrompt, { exact: true }).hover();
+      await page.getByTestId("rewind-menu-trigger").last().click();
+      await expect(page.getByTestId("rewind-menu-content")).toBeVisible();
+      await page.getByTestId("rewind-menu-files").click();
+      await expect(page.getByTestId("rewind-menu-content")).toHaveCount(0);
+      await expectComposerDraft(page, preservedDraft);
+      await expectUserMessageCount(page, 2);
+
+      await fillComposerDraft(page, "");
+      await composerLocator(page).evaluate((element) => element.blur());
+      await page.getByText(replacementPrompt, { exact: true }).hover();
+      await page.getByTestId("rewind-menu-trigger").last().click();
+      await expect(page.getByTestId("rewind-menu-content")).toBeVisible();
+      await page.getByTestId("rewind-menu-both").click();
+      await expect(page.getByTestId("rewind-menu-content")).toHaveCount(0);
+      await expectComposerDraft(page, replacementPrompt);
+      await expectUserMessageCount(page, 1);
+    } finally {
+      await session.cleanup();
+    }
+  });
+
+  test("surfaces rewind failures without crashing the page", async ({ page }) => {
+    const firstPrompt = "emit 1 coalesced agent stream updates for failed rewind turn.";
+    const rewindError = "No file checkpoint found for message rewind-failure-e2e.";
+    const session = await seedMockAgentWorkspace({
+      repoPrefix: "rewind-failure-e2e-",
+      title: "Rewind failure e2e",
+      initialPrompt: firstPrompt,
+      featureValues: {
+        mockRewindError: rewindError,
+      },
+    });
+
+    try {
+      await openAgentRoute(page, session);
+      await expectComposerVisible(page);
+
+      await expect(page.getByText(firstPrompt, { exact: true })).toBeVisible();
+
+      await page.getByText(firstPrompt, { exact: true }).hover();
+      await page.getByTestId("rewind-menu-trigger").first().click();
+      const rewindSheet = page.getByTestId("rewind-menu-content");
+      await expect(rewindSheet).toBeVisible();
+      await expect(
+        rewindSheet.getByText("This action cannot be undone", { exact: true }),
+      ).toBeVisible();
+      await page.getByTestId("rewind-menu-conversation").click();
+
+      await expect(page.getByTestId("app-toast-message")).toHaveText(rewindError);
+      await expect(page.getByText("Uncaught Error")).toHaveCount(0);
+
+      await page.getByText(firstPrompt, { exact: true }).hover();
+      await page.getByTestId("rewind-menu-trigger").first().click();
+      await expect(page.getByTestId("rewind-menu-content")).toBeVisible();
+    } finally {
+      await session.cleanup();
+    }
+  });
+});

packages/app/e2e/settings-host-page.spec.ts

@@ -1,6 +1,8 @@
 import { test } from "./fixtures";
 import { gotoAppShell, openSettings } from "./helpers/app";
+import { getE2EDaemonPort } from "./helpers/daemon-port";
 import { TEST_HOST_LABEL } from "./helpers/daemon-registry";
+import { getServerId } from "./helpers/server-id";
 import {
   expectSettingsHeader,
   openSettingsHost,
@@ -16,28 +18,12 @@ import {
   expectLocalHostEntryFirst,
 } from "./helpers/settings";
 
-function getSeededServerId(): string {
-  const serverId = process.env.E2E_SERVER_ID;
-  if (!serverId) {
-    throw new Error("E2E_SERVER_ID is not set (expected from Playwright globalSetup).");
-  }
-  return serverId;
-}
-
-function getSeededDaemonPort(): string {
-  const port = process.env.E2E_DAEMON_PORT;
-  if (!port) {
-    throw new Error("E2E_DAEMON_PORT is not set (expected from Playwright globalSetup).");
-  }
-  return port;
-}
-
 test.describe("Settings host page", () => {
   test("host page shows seeded label, connection endpoint, inject MCP toggle, and all action rows", async ({
     page,
   }) => {
-    const serverId = getSeededServerId();
-    const port = getSeededDaemonPort();
+    const serverId = getServerId();
+    const port = getE2EDaemonPort();
 
     await gotoAppShell(page);
     await openSettings(page);
@@ -51,7 +37,7 @@ test.describe("Settings host page", () => {
   });
 
   test("clicking the label pencil reveals the inline editor", async ({ page }) => {
-    const serverId = getSeededServerId();
+    const serverId = getServerId();
 
     await gotoAppShell(page);
     await openSettings(page);
@@ -65,7 +51,7 @@ test.describe("Settings host page", () => {
   test("host page does not render pair-device or daemon-lifecycle rows for a remote daemon", async ({
     page,
   }) => {
-    const serverId = getSeededServerId();
+    const serverId = getServerId();
 
     await gotoAppShell(page);
     await openSettings(page);
@@ -85,7 +71,7 @@ test.describe("Settings host page", () => {
   test("navigating to /settings/hosts/[serverId] directly renders the host page", async ({
     page,
   }) => {
-    const serverId = getSeededServerId();
+    const serverId = getServerId();
 
     await gotoAppShell(page);
     await page.goto(`/settings/hosts/${encodeURIComponent(serverId)}`);
@@ -97,7 +83,7 @@ test.describe("Settings host page", () => {
   });
 
   test("sidebar pins the local daemon host first with a Local marker", async ({ page }) => {
-    const serverId = getSeededServerId();
+    const serverId = getServerId();
 
     // Simulate the Electron desktop bridge so `useIsLocalDaemon` resolves the
     // seeded host to the local daemon. `manageBuiltInDaemon: false` (returned

packages/app/e2e/settings-toggle-tab-regression.spec.ts

@@ -1,21 +1,9 @@
 import { buildHostAgentDetailRoute, buildHostWorkspaceRoute } from "@/utils/host-routes";
 import { expect, test } from "./fixtures";
-import {
-  archiveAgentFromDaemon,
-  connectArchiveTabDaemonClient,
-  createIdleAgent,
-  openWorkspaceWithAgents,
-} from "./helpers/archive-tab";
+import { createIdleAgent, openWorkspaceWithAgents } from "./helpers/archive-tab";
 import { waitForTabBar, expectAgentTabActive } from "./helpers/launcher";
-import { createTempGitRepo } from "./helpers/workspace";
-
-function getServerId(): string {
-  const serverId = process.env.E2E_SERVER_ID;
-  if (!serverId) {
-    throw new Error("E2E_SERVER_ID is not set.");
-  }
-  return serverId;
-}
+import { seedWorkspace } from "./helpers/seed-client";
+import { getServerId } from "./helpers/server-id";
 
 async function pressSettingsToggleShortcut(page: import("@playwright/test").Page) {
   const modifier = process.platform === "darwin" ? "Meta" : "Control";
@@ -61,20 +49,17 @@ test.describe("Settings toggle tab regression", () => {
     page,
   }) => {
     const serverId = getServerId();
-    const client = await connectArchiveTabDaemonClient();
-    const repo = await createTempGitRepo("settings-toggle-tab-");
-    const agentIds: string[] = [];
+    const workspace = await seedWorkspace({ repoPrefix: "settings-toggle-tab-" });
 
     try {
-      const firstAgent = await createIdleAgent(client, {
-        cwd: repo.path,
+      const firstAgent = await createIdleAgent(workspace.client, {
+        cwd: workspace.repoPath,
         title: `settings-toggle-a-${Date.now()}`,
       });
-      const secondAgent = await createIdleAgent(client, {
-        cwd: repo.path,
+      const secondAgent = await createIdleAgent(workspace.client, {
+        cwd: workspace.repoPath,
         title: `settings-toggle-b-${Date.now()}`,
       });
-      agentIds.push(firstAgent.id, secondAgent.id);
 
       await openWorkspaceWithAgents(page, [firstAgent, secondAgent]);
       await waitForTabBar(page);
@@ -89,7 +74,7 @@ test.describe("Settings toggle tab regression", () => {
       await expectSendBehavior(page, "interrupt");
 
       await pressSettingsToggleShortcut(page);
-      await expect(page).toHaveURL(buildHostWorkspaceRoute(serverId, repo.path));
+      await expect(page).toHaveURL(buildHostWorkspaceRoute(serverId, workspace.repoPath));
       await waitForTabBar(page);
       await expectAgentTabActive(page, secondAgent.id);
 
@@ -97,11 +82,7 @@ test.describe("Settings toggle tab regression", () => {
       await waitForTabBar(page);
       await expectAgentTabActive(page, secondAgent.id);
     } finally {
-      for (const agentId of agentIds) {
-        await archiveAgentFromDaemon(client, agentId).catch(() => undefined);
-      }
-      await client.close().catch(() => undefined);
-      await repo.cleanup();
+      await workspace.cleanup();
     }
   });
 
@@ -109,31 +90,28 @@ test.describe("Settings toggle tab regression", () => {
     page,
   }) => {
     const serverId = getServerId();
-    const client = await connectArchiveTabDaemonClient();
-    const repo = await createTempGitRepo("agent-route-refresh-");
-    const agentIds: string[] = [];
+    const workspace = await seedWorkspace({ repoPrefix: "agent-route-refresh-" });
 
     try {
-      const firstAgent = await createIdleAgent(client, {
-        cwd: repo.path,
+      const firstAgent = await createIdleAgent(workspace.client, {
+        cwd: workspace.repoPath,
         title: `agent-route-refresh-a-${Date.now()}`,
       });
-      const secondAgent = await createIdleAgent(client, {
-        cwd: repo.path,
+      const secondAgent = await createIdleAgent(workspace.client, {
+        cwd: workspace.repoPath,
         title: `agent-route-refresh-b-${Date.now()}`,
       });
-      agentIds.push(firstAgent.id, secondAgent.id);
 
       await openAgentRouteAndExpectFocused({
         page,
         serverId,
-        workspaceId: repo.path,
+        workspaceId: workspace.repoPath,
         agentId: firstAgent.id,
       });
       await openAgentRouteAndExpectFocused({
         page,
         serverId,
-        workspaceId: repo.path,
+        workspaceId: workspace.repoPath,
         agentId: secondAgent.id,
       });
 
@@ -143,11 +121,7 @@ test.describe("Settings toggle tab regression", () => {
         await expectAgentTabActive(page, secondAgent.id);
       }
     } finally {
-      for (const agentId of agentIds) {
-        await archiveAgentFromDaemon(client, agentId).catch(() => undefined);
-      }
-      await client.close().catch(() => undefined);
-      await repo.cleanup();
+      await workspace.cleanup();
     }
   });
 });

packages/app/e2e/sidebar-workspace-rename.spec.ts

@@ -0,0 +1,115 @@
+import { execSync } from "node:child_process";
+import { test, expect, type Page } from "./fixtures";
+import { gotoAppShell } from "./helpers/app";
+import { seedWorkspace } from "./helpers/seed-client";
+import { captureWsSessionFrames } from "./helpers/rename";
+import { getServerId } from "./helpers/server-id";
+
+function workspaceRowTestId(workspaceId: string): string {
+  return `sidebar-workspace-row-${getServerId()}:${workspaceId}`;
+}
+
+function workspaceRenameModalTestId(workspaceId: string, suffix: string): string {
+  return `sidebar-workspace-rename-modal-${getServerId()}:${workspaceId}-${suffix}`;
+}
+
+async function openRenameModal(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();
+
+  const renameItem = page.getByTestId(`sidebar-workspace-menu-rename-${serverId}:${workspaceId}`);
+  await expect(renameItem).toBeVisible({ timeout: 10_000 });
+  await renameItem.click();
+
+  const input = page.getByTestId(workspaceRenameModalTestId(workspaceId, "input"));
+  await expect(input).toBeVisible({ timeout: 10_000 });
+  return input;
+}
+
+test.describe("Sidebar workspace rename", () => {
+  test("renaming via kebab updates the branch name on disk and in the sidebar", async ({
+    page,
+  }) => {
+    const workspace = await seedWorkspace({ repoPrefix: "sidebar-rename-" });
+
+    try {
+      expect(workspace.workspaceName).toBe("main");
+
+      const renameRequests = captureWsSessionFrames(
+        page,
+        "checkout.rename_branch.request",
+        (inner) => ({
+          branch: String(inner.branch ?? ""),
+          cwd: String(inner.cwd ?? ""),
+        }),
+      );
+
+      await gotoAppShell(page);
+      await expect(page.getByTestId(workspaceRowTestId(workspace.workspaceId))).toBeVisible({
+        timeout: 30_000,
+      });
+
+      const input = await openRenameModal(page, workspace.workspaceId);
+      await expect(input).toHaveValue("main");
+      await input.fill("Feature Rename 2");
+
+      await page.getByTestId(workspaceRenameModalTestId(workspace.workspaceId, "submit")).click();
+
+      await expect(input).toHaveCount(0, { timeout: 15_000 });
+      await expect(page.getByTestId(workspaceRowTestId(workspace.workspaceId))).toContainText(
+        "feature-rename-2",
+        { timeout: 15_000 },
+      );
+
+      expect(renameRequests.length).toBeGreaterThan(0);
+      expect(renameRequests.at(-1)).toEqual({
+        branch: "feature-rename-2",
+        cwd: workspace.workspaceDirectory,
+      });
+
+      const currentBranchOnDisk = execSync("git branch --show-current", {
+        cwd: workspace.repoPath,
+        stdio: "pipe",
+      })
+        .toString()
+        .trim();
+      expect(currentBranchOnDisk).toBe("feature-rename-2");
+    } finally {
+      await workspace.cleanup();
+    }
+  });
+
+  test("rename surfaces server errors inline and keeps the modal open", async ({ page }) => {
+    const workspace = await seedWorkspace({
+      repoPrefix: "sidebar-rename-error-",
+      repo: { branches: ["taken"] },
+    });
+
+    try {
+      await gotoAppShell(page);
+      const input = await openRenameModal(page, workspace.workspaceId);
+      await expect(input).toHaveValue("main");
+
+      await input.fill("taken");
+      await page.getByTestId(workspaceRenameModalTestId(workspace.workspaceId, "submit")).click();
+
+      const errorNode = page.getByTestId(
+        workspaceRenameModalTestId(workspace.workspaceId, "error"),
+      );
+      await expect(errorNode).toBeVisible({ timeout: 15_000 });
+      await expect(errorNode).toContainText(/already exists|branch/i);
+      await expect(input).toBeVisible();
+      await expect(page.getByTestId(workspaceRowTestId(workspace.workspaceId))).toContainText(
+        "main",
+      );
+    } finally {
+      await workspace.cleanup();
+    }
+  });
+});

packages/app/e2e/sidebar-workspace.spec.ts

@@ -1,6 +1,3 @@
-import { execSync } from "node:child_process";
-import { mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
 import path from "node:path";
 import { test, expect } from "./fixtures";
 import { gotoAppShell } from "./helpers/app";
@@ -10,59 +7,17 @@ import {
   expectMobileAgentSidebarVisible,
   openMobileAgentSidebar,
 } from "./helpers/sidebar";
-import { createTempGitRepo } from "./helpers/workspace";
+import { seedWorkspace } from "./helpers/seed-client";
 import { expectWorkspaceHeader } from "./helpers/workspace-ui";
-import { connectWorkspaceSetupClient } from "./helpers/workspace-setup";
+import { getServerId } from "./helpers/server-id";
+import { escapeRegex } from "./helpers/regex";
 
-function getServerId(): string {
-  const serverId = process.env.E2E_SERVER_ID;
-  if (!serverId) {
-    throw new Error("E2E_SERVER_ID is not set (expected from Playwright globalSetup).");
-  }
-  return serverId;
-}
+const GITHUB_REMOTE_URL = "https://github.com/test-owner/test-repo.git";
 
 function getWorkspaceRowTestId(workspaceId: string): string {
   return `sidebar-workspace-row-${getServerId()}:${workspaceId}`;
 }
 
-function escapeRegex(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-function setGitHubRemote(repoPath: string): void {
-  execSync("git remote set-url origin https://github.com/test-owner/test-repo.git", {
-    cwd: repoPath,
-    stdio: "ignore",
-  });
-}
-
-async function createTempDirectory(prefix = "paseo-e2e-dir-") {
-  const tempRoot = process.platform === "win32" ? tmpdir() : await realpath("/tmp");
-  const dirPath = await mkdtemp(path.join(tempRoot, prefix));
-  await writeFile(path.join(dirPath, "README.md"), "# Temp Directory\n");
-  return {
-    path: dirPath,
-    cleanup: async () => {
-      await rm(dirPath, { recursive: true, force: true });
-    },
-  };
-}
-
-async function openProjectViaDaemon(
-  client: Awaited<ReturnType<typeof connectWorkspaceSetupClient>>,
-  cwd: string,
-): Promise<{ id: string; name: string }> {
-  const result = await client.openProject(cwd);
-  if (!result.workspace || result.error) {
-    throw new Error(result.error ?? `Failed to open project ${cwd}`);
-  }
-  return {
-    id: result.workspace.id,
-    name: result.workspace.name,
-  };
-}
-
 async function openWorkspaceFromSidebar(
   page: import("@playwright/test").Page,
   workspaceId: string,
@@ -92,15 +47,15 @@ async function waitForSidebarWorkspace(page: import("@playwright/test").Page, wo
 
 test.describe("Sidebar workspace list", () => {
   test("project with GitHub remote shows owner/repo name in sidebar", async ({ page }) => {
-    const client = await connectWorkspaceSetupClient();
-    const repo = await createTempGitRepo("sidebar-remote-", { withRemote: true });
+    const workspace = await seedWorkspace({
+      repoPrefix: "sidebar-remote-",
+      repo: { withRemote: true, originUrl: GITHUB_REMOTE_URL },
+    });
 
     try {
-      setGitHubRemote(repo.path);
-      const workspace = await openProjectViaDaemon(client, repo.path);
       await gotoAppShell(page);
       await waitForSidebarProject(page, "test-owner/test-repo");
-      await waitForSidebarWorkspace(page, workspace.id);
+      await waitForSidebarWorkspace(page, workspace.workspaceId);
 
       const projectRow = page
         .locator('[data-testid^="sidebar-project-row-"]')
@@ -108,81 +63,73 @@ test.describe("Sidebar workspace list", () => {
         .first();
 
       await expect(projectRow).toBeVisible({ timeout: 30_000 });
-      await expect(projectRow).not.toContainText(path.basename(repo.path));
+      await expect(projectRow).not.toContainText(path.basename(workspace.repoPath));
     } finally {
-      await client.close();
-      await repo.cleanup();
+      await workspace.cleanup();
     }
   });
 
   test("project shows workspace under it", async ({ page }) => {
-    const client = await connectWorkspaceSetupClient();
-    const repo = await createTempGitRepo("sidebar-workspace-under-project-");
+    const workspace = await seedWorkspace({ repoPrefix: "sidebar-workspace-under-project-" });
 
     try {
-      const workspace = await openProjectViaDaemon(client, repo.path);
       await gotoAppShell(page);
 
-      await waitForSidebarProject(page, path.basename(repo.path));
-      await waitForSidebarWorkspace(page, workspace.id);
+      await waitForSidebarProject(page, path.basename(workspace.repoPath));
+      await waitForSidebarWorkspace(page, workspace.workspaceId);
     } finally {
-      await client.close();
-      await repo.cleanup();
+      await workspace.cleanup();
     }
   });
 
   test("non-git project shows directory name", async ({ page }) => {
-    const client = await connectWorkspaceSetupClient();
-    const project = await createTempDirectory("sidebar-directory-");
+    const workspace = await seedWorkspace({ repoPrefix: "sidebar-directory-", git: false });
 
     try {
-      await openProjectViaDaemon(client, project.path);
       await gotoAppShell(page);
 
-      const projectRow = await waitForSidebarProject(page, path.basename(project.path));
-      await expect(projectRow).toContainText(path.basename(project.path));
+      const directoryName = path.basename(workspace.repoPath);
+      const projectRow = await waitForSidebarProject(page, directoryName);
+      await expect(projectRow).toContainText(directoryName);
     } finally {
-      await client.close();
-      await project.cleanup();
+      await workspace.cleanup();
     }
   });
 
   test("workspace header shows correct title and subtitle", async ({ page }) => {
-    const client = await connectWorkspaceSetupClient();
-    const repo = await createTempGitRepo("sidebar-header-", { withRemote: true });
+    const workspace = await seedWorkspace({
+      repoPrefix: "sidebar-header-",
+      repo: { withRemote: true, originUrl: GITHUB_REMOTE_URL },
+    });
 
     try {
-      setGitHubRemote(repo.path);
-      const workspace = await openProjectViaDaemon(client, repo.path);
       await gotoAppShell(page);
       await waitForSidebarProject(page, "test-owner/test-repo");
-      await waitForSidebarWorkspace(page, workspace.id);
-      await openWorkspaceFromSidebar(page, workspace.id);
+      await waitForSidebarWorkspace(page, workspace.workspaceId);
+      await openWorkspaceFromSidebar(page, workspace.workspaceId);
 
       await expectWorkspaceHeader(page, {
-        title: workspace.name,
+        title: workspace.workspaceName,
         subtitle: "test-owner/test-repo",
       });
     } finally {
-      await client.close();
-      await repo.cleanup();
+      await workspace.cleanup();
     }
   });
 
   test("git project shows branch name in workspace row", async ({ page }) => {
-    const client = await connectWorkspaceSetupClient();
-    const repo = await createTempGitRepo("sidebar-branch-");
+    const workspace = await seedWorkspace({ repoPrefix: "sidebar-branch-" });
 
     try {
-      const workspace = await openProjectViaDaemon(client, repo.path);
       await gotoAppShell(page);
-      await waitForSidebarProject(page, path.basename(repo.path));
+      await waitForSidebarProject(page, path.basename(workspace.repoPath));
 
-      expect(workspace.name).toBe("main");
-      await expect(await waitForSidebarWorkspace(page, workspace.id)).toContainText("main");
+      expect(workspace.workspaceName).toBe("main");
+      await expect(await waitForSidebarWorkspace(page, workspace.workspaceId)).toContainText(
+        "main",
+      );
     } finally {
-      await client.close();
-      await repo.cleanup();
+      await workspace.cleanup();
     }
   });
 });

packages/app/e2e/startup-loading.spec.ts

@@ -1,22 +1,8 @@
 import { test } from "./fixtures";
+import { getE2EDaemonPort } from "./helpers/daemon-port";
+import { getServerId } from "./helpers/server-id";
 import { startupScenario } from "./helpers/startup-dsl";
 
-function getE2EDaemonPort(): string {
-  const port = process.env.E2E_DAEMON_PORT;
-  if (!port) {
-    throw new Error("E2E_DAEMON_PORT is not set.");
-  }
-  return port;
-}
-
-function getE2EServerId(): string {
-  const serverId = process.env.E2E_SERVER_ID;
-  if (!serverId) {
-    throw new Error("E2E_SERVER_ID is not set.");
-  }
-  return serverId;
-}
-
 test.describe("Startup loading presentation", () => {
   test("mobile reconnect keeps connection recovery actions visible", async ({ page }) => {
     const startup = await startupScenario(page)
@@ -49,7 +35,7 @@ test.describe("Startup loading presentation", () => {
   test("host-route refresh does not render route chrome around the bootstrap splash", async ({
     page,
   }) => {
-    const serverId = getE2EServerId();
+    const serverId = getServerId();
     const startup = await startupScenario(page)
       .withPendingDesktopDaemon()
       .withBlockedPort(getE2EDaemonPort())

packages/app/e2e/terminal-performance.spec.ts

@@ -1,14 +1,10 @@
 import { test, expect } from "./fixtures";
-import { createTempGitRepo } from "./helpers/workspace";
+import { TerminalE2EHarness } from "./helpers/terminal-dsl";
 import {
-  connectTerminalClient,
-  navigateToTerminal,
-  setupDeterministicPrompt,
   waitForTerminalContent,
   measureKeystrokeLatency,
   computePercentile,
   round2,
-  type TerminalPerfDaemonClient,
   type LatencySample,
 } from "./helpers/terminal-perf";
 
@@ -20,43 +16,26 @@ const RUN_MANUAL_TERMINAL_PERF = process.env.PASEO_TERMINAL_PERF_E2E === "1";
 const terminalPerfDescribe = RUN_MANUAL_TERMINAL_PERF ? test.describe : test.describe.skip;
 
 terminalPerfDescribe("Terminal wire performance", () => {
-  let client: TerminalPerfDaemonClient;
-  let tempRepo: { path: string; cleanup: () => Promise<void> };
-  let workspaceId: string;
+  let harness: TerminalE2EHarness;
 
   test.beforeAll(async () => {
-    tempRepo = await createTempGitRepo("perf-");
-    client = await connectTerminalClient();
-    // Seed the workspace in the daemon so the app can resolve the path
-    const seedResult = await client.openProject(tempRepo.path);
-    if (!seedResult.workspace) throw new Error(seedResult.error ?? "Failed to seed workspace");
-    workspaceId = seedResult.workspace.id;
+    harness = await TerminalE2EHarness.create({ tempPrefix: "perf-" });
   });
 
   test.afterAll(async () => {
-    if (client) {
-      await client.close();
-    }
-    if (tempRepo) {
-      await tempRepo.cleanup();
-    }
+    await harness?.cleanup();
   });
 
   test("throughput: bulk terminal output renders within budget", async ({ page }, testInfo) => {
     test.setTimeout(90_000);
 
-    const result = await client.createTerminal(tempRepo.path, "throughput");
-    if (!result.terminal) {
-      throw new Error(`Failed to create terminal: ${result.error}`);
-    }
-    const terminalId = result.terminal.id;
-
+    const created = await harness.createTerminal({ name: "throughput" });
     try {
-      await navigateToTerminal(page, { workspaceId, terminalId });
-      await setupDeterministicPrompt(page);
+      await harness.openTerminal(page, { terminalId: created.id });
+      await harness.setupPrompt(page);
 
       const sentinel = `PERF_DONE_${Date.now()}`;
-      const terminal = page.locator('[data-testid="terminal-surface"]');
+      const terminal = harness.terminalSurface(page);
       const startMs = Date.now();
 
       await terminal.pressSequentially(`seq 1 ${LINE_COUNT}; echo ${sentinel}\n`, { delay: 0 });
@@ -97,25 +76,20 @@ terminalPerfDescribe("Terminal wire performance", () => {
         `${LINE_COUNT} lines should render within ${THROUGHPUT_BUDGET_MS}ms`,
       ).toBeLessThan(THROUGHPUT_BUDGET_MS);
     } finally {
-      await client.killTerminal(terminalId).catch(() => {});
+      await harness.killTerminal(created.id);
     }
   });
 
   test("keystroke latency: echo round-trip under budget", async ({ page }, testInfo) => {
     test.setTimeout(60_000);
 
-    const result = await client.createTerminal(tempRepo.path, "latency");
-    if (!result.terminal) {
-      throw new Error(`Failed to create terminal: ${result.error}`);
-    }
-    const terminalId = result.terminal.id;
-
+    const created = await harness.createTerminal({ name: "latency" });
     try {
-      await navigateToTerminal(page, { workspaceId, terminalId });
-      await setupDeterministicPrompt(page);
+      await harness.openTerminal(page, { terminalId: created.id });
+      await harness.setupPrompt(page);
 
       // Ensure clean prompt state
-      const terminal = page.locator('[data-testid="terminal-surface"]');
+      const terminal = harness.terminalSurface(page);
       await terminal.press("Control+c");
       await page.waitForTimeout(200);
 
@@ -166,7 +140,7 @@ terminalPerfDescribe("Terminal wire performance", () => {
         `Keystroke p95 latency should be under ${KEYSTROKE_P95_BUDGET_MS}ms`,
       ).toBeLessThan(KEYSTROKE_P95_BUDGET_MS);
     } finally {
-      await client.killTerminal(terminalId).catch(() => {});
+      await harness.killTerminal(created.id);
     }
   });
 });

packages/app/e2e/terminal-protocol-query.spec.ts

@@ -0,0 +1,61 @@
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { test, expect } from "./fixtures";
+import { TerminalE2EHarness } from "./helpers/terminal-dsl";
+import { getTerminalBufferText, waitForTerminalContent } from "./helpers/terminal-perf";
+
+const OSC11_CAPTURE_SCRIPT = `
+let captured = Buffer.alloc(0);
+
+function finish() {
+  process.stdout.write("PASEO_OSC11_CAPTURE:" + JSON.stringify(captured.toString("latin1")) + "\\n");
+  process.exit(0);
+}
+
+process.stdout.write("\\x1b]11;?\\x07");
+if (process.stdin.isTTY) {
+  process.stdin.setRawMode(true);
+}
+process.stdin.resume();
+process.stdin.on("data", (chunk) => {
+  captured = Buffer.concat([captured, chunk]);
+  if (captured.includes(Buffer.from("rgb:"))) {
+    finish();
+  }
+});
+setTimeout(finish, 700);
+`;
+
+test.describe("Terminal protocol queries", () => {
+  let harness: TerminalE2EHarness;
+
+  test.beforeAll(async () => {
+    harness = await TerminalE2EHarness.create({ tempPrefix: "terminal-protocol-query-" });
+    await writeFile(path.join(harness.tempRepo.path, "osc11-capture.cjs"), OSC11_CAPTURE_SCRIPT);
+  });
+
+  test.afterAll(async () => {
+    await harness?.cleanup();
+  });
+
+  test("does not send browser OSC 11 color-query replies back to the PTY", async ({ page }) => {
+    const terminalInstance = await harness.createTerminal({ name: "osc11-query" });
+    try {
+      await harness.openTerminal(page, { terminalId: terminalInstance.id });
+      await harness.setupPrompt(page);
+
+      const terminal = harness.terminalSurface(page);
+      await terminal.pressSequentially("node osc11-capture.cjs\n", { delay: 0 });
+
+      await waitForTerminalContent(page, (text) => text.includes("PASEO_OSC11_CAPTURE:"), 10_000);
+      await page.waitForTimeout(500);
+
+      const text = await getTerminalBufferText(page);
+
+      expect(text).toContain("rgb:0b0b/0b0b/0b0b");
+      expect(text).not.toContain("rgb:ffff/ffff/ffff");
+    } finally {
+      await harness.killTerminal(terminalInstance.id);
+    }
+  });
+});

packages/app/e2e/user-message-contract.ui-contract.spec.ts

@@ -0,0 +1,63 @@
+import { expect, test, type Page } from "./fixtures";
+import { openAgentRoute, seedMockAgentWorkspace } from "./helpers/mock-agent";
+import {
+  composerLocator,
+  expectComposerEditable,
+  expectComposerVisible,
+  fillComposerDraft,
+  submitMessage,
+} from "./helpers/composer";
+
+async function expectUserMessageCount(page: Page, expected: number): Promise<void> {
+  await expect(page.getByTestId("user-message")).toHaveCount(expected, { timeout: 15_000 });
+}
+
+async function expectIdleComposer(page: Page): Promise<void> {
+  await expectComposerEditable(page);
+  await expect(page.getByRole("button", { name: /stop|cancel/i })).toHaveCount(0, {
+    timeout: 15_000,
+  });
+}
+
+async function expectNoLoadingRegressionAfterIdle(page: Page): Promise<void> {
+  await expectIdleComposer(page);
+  await page.waitForTimeout(1_000);
+  await expectIdleComposer(page);
+}
+
+test.describe("User message UI contract", () => {
+  test("dedupes mock provider user_message echoes across multi-turn sends", async ({ page }) => {
+    const session = await seedMockAgentWorkspace({
+      repoPrefix: "user-message-contract-e2e-",
+      title: "User message contract e2e",
+    });
+    const prompts = [
+      "emit 1 coalesced agent stream updates for user message contract turn one.",
+      "emit 1 coalesced agent stream updates for user message contract turn two.",
+      "emit 1 coalesced agent stream updates for user message contract turn three.",
+    ];
+
+    try {
+      await openAgentRoute(page, session);
+      await expectComposerVisible(page);
+
+      for (let index = 0; index < prompts.length; index += 1) {
+        const prompt = prompts[index]!;
+        await submitMessage(page, prompt);
+        await expect(page.getByText(prompt, { exact: true })).toBeVisible({ timeout: 15_000 });
+        await expect(page.getByText("stress-update-0", { exact: true }).first()).toBeVisible({
+          timeout: 15_000,
+        });
+        await expectUserMessageCount(page, index + 1);
+        await expectNoLoadingRegressionAfterIdle(page);
+      }
+
+      await fillComposerDraft(page, "append");
+      await composerLocator(page).evaluate((element) => element.blur());
+      await expectUserMessageCount(page, 3);
+      await expectIdleComposer(page);
+    } finally {
+      await session.cleanup();
+    }
+  });
+});

packages/app/e2e/workspace-agent-tab-rename.spec.ts

@@ -0,0 +1,75 @@
+import { randomUUID } from "node:crypto";
+import { test, expect, type Page } from "./fixtures";
+import { seedWorkspace } from "./helpers/seed-client";
+import { createIdleAgent, expectWorkspaceTabVisible } from "./helpers/archive-tab";
+import { waitForWorkspaceTabsVisible } from "./helpers/workspace-tabs";
+import { buildHostAgentDetailRoute } from "@/utils/host-routes";
+import { captureWsSessionFrames, renameModalInput, renameModalSubmit } from "./helpers/rename";
+import { getServerId } from "./helpers/server-id";
+
+async function openAgentInWorkspace(page: Page, agent: { id: string; cwd: string }) {
+  await page.goto(buildHostAgentDetailRoute(getServerId(), agent.id, agent.cwd));
+  await page.waitForURL(
+    (url) => url.pathname.includes("/workspace/") && !url.searchParams.has("open"),
+    { timeout: 60_000 },
+  );
+  await waitForWorkspaceTabsVisible(page);
+  await expectWorkspaceTabVisible(page, agent.id);
+}
+
+test.describe("Workspace agent tab rename", () => {
+  test("right-click rename sends update_agent_request and updates the tab label", async ({
+    page,
+  }) => {
+    test.setTimeout(120_000);
+
+    const workspace = await seedWorkspace({ repoPrefix: "workspace-agent-rename-" });
+
+    try {
+      const initialTitle = `agent-rename-${randomUUID().slice(0, 8)}`;
+      const agent = await createIdleAgent(workspace.client, {
+        cwd: workspace.repoPath,
+        title: initialTitle,
+      });
+
+      const updateFrames = captureWsSessionFrames(page, "update_agent_request", (inner) => ({
+        agentId: String(inner.agentId ?? ""),
+        name: String(inner.name ?? ""),
+        requestId: String(inner.requestId ?? ""),
+      }));
+
+      await openAgentInWorkspace(page, agent);
+
+      const tab = page.getByTestId(`workspace-tab-agent_${agent.id}`).first();
+      await expect(tab).toContainText(initialTitle, { timeout: 15_000 });
+
+      await tab.click({ button: "right" });
+      await expect(page.getByTestId(`workspace-tab-context-agent_${agent.id}`)).toBeVisible({
+        timeout: 10_000,
+      });
+      const renameItem = page.getByTestId(`workspace-tab-context-agent_${agent.id}-rename`);
+      await expect(renameItem).toBeVisible({ timeout: 10_000 });
+      await renameItem.click();
+
+      const modalPrefix = `workspace-tab-rename-modal-agent-${agent.id}`;
+      const input = renameModalInput(page, modalPrefix);
+      await expect(input).toBeVisible({ timeout: 10_000 });
+      await expect(input).toHaveValue(initialTitle);
+
+      const renamed = "My Renamed Agent";
+      await input.fill(renamed);
+      await renameModalSubmit(page, modalPrefix).click();
+
+      await expect(input).toHaveCount(0, { timeout: 15_000 });
+      await expect(tab).toContainText(renamed, { timeout: 15_000 });
+
+      expect(updateFrames.length).toBeGreaterThan(0);
+      const lastFrame = updateFrames.at(-1)!;
+      expect(lastFrame.agentId).toBe(agent.id);
+      expect(lastFrame.name).toBe(renamed);
+      expect(lastFrame.requestId.length).toBeGreaterThan(0);
+    } finally {
+      await workspace.cleanup();
+    }
+  });
+});