chore(release): cut 0.1.43

Closes #173

.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: [boudra]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.github/workflows/android-apk-release.yml

@@ -4,6 +4,7 @@ on:
   push:
     tags:
       - "v*"
+      - "android-v*"
   workflow_dispatch:
     inputs:
       tag:
@@ -16,7 +17,7 @@ concurrency:
   cancel-in-progress: false
 
 env:
-  RELEASE_TAG: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag || github.ref_name }}
+  SOURCE_TAG: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag || github.ref_name }}
 
 jobs:
   publish-android-apk:
@@ -31,6 +32,36 @@ jobs:
           fetch-depth: 0
           ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag || github.ref }}
 
+      - name: Resolve release tag
+        shell: bash
+        run: node scripts/emit-release-env.mjs --source-tag "$SOURCE_TAG" >> "$GITHUB_ENV"
+
+      - name: Ensure GitHub release exists
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if gh release view "$RELEASE_TAG" --repo "${{ github.repository }}" >/dev/null 2>&1; then
+            exit 0
+          fi
+
+          release_args=(
+            release create "$RELEASE_TAG"
+            --repo "${{ github.repository }}"
+            --title "Paseo $RELEASE_TAG"
+            --generate-notes
+          )
+
+          if [[ "$IS_PRERELEASE" == "true" ]]; then
+            release_args+=(--prerelease)
+          fi
+
+          if ! gh "${release_args[@]}"; then
+            echo "Release creation raced with another workflow; continuing."
+          fi
+
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
@@ -94,24 +125,6 @@ jobs:
           echo "asset_name=$asset_name" >> "$GITHUB_OUTPUT"
           echo "asset_path=$asset_path" >> "$GITHUB_OUTPUT"
 
-      - name: Wait for GitHub release tag
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        shell: bash
-        run: |
-          set -euo pipefail
-          for attempt in $(seq 1 90); do
-            if gh release view "$RELEASE_TAG" --repo "${{ github.repository }}" >/dev/null 2>&1; then
-              echo "Found release for tag $RELEASE_TAG"
-              exit 0
-            fi
-            echo "Release for $RELEASE_TAG is not available yet (attempt $attempt/90)."
-            sleep 20
-          done
-
-          echo "Timed out waiting for GitHub release tag $RELEASE_TAG."
-          exit 1
-
       - name: Upload APK to GitHub Release
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/deploy-app.yml

@@ -2,11 +2,11 @@ name: Deploy App
 
 on:
   push:
-    branches: [main]
-    paths:
-      - 'packages/app/**'
-      - 'packages/server/src/**'
-      - '.github/workflows/deploy-app.yml'
+    tags:
+      - 'v*'
+      - '!v*-rc.*'
+      - 'app-v*'
+      - '!app-v*-rc.*'
   workflow_dispatch:
 
 jobs:
@@ -28,6 +28,9 @@ jobs:
         env:
           NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Build highlight dependency
+        run: npm run build --workspace=@getpaseo/highlight
+
       - name: Typecheck
         run: npm run typecheck --workspace=@getpaseo/app
 

.github/workflows/deploy-website.yml

@@ -9,10 +9,13 @@ on:
       - 'package-lock.json'
       - 'patches/**'
       - '.github/workflows/deploy-website.yml'
+  release:
+    types: [published, edited]
   workflow_dispatch:
 
 jobs:
   deploy:
+    if: ${{ github.event_name != 'release' || (!github.event.release.prerelease && !github.event.release.draft) }}
     runs-on: ubuntu-latest
 
     steps:

.github/workflows/desktop-release.yml

@@ -5,25 +5,50 @@ on:
     tags:
       - 'v*'
       - 'desktop-v*'
+      - 'desktop-macos-v*'
+      - 'desktop-linux-v*'
+      - 'desktop-windows-v*'
   workflow_dispatch:
     inputs:
       tag:
         description: 'Existing tag to build (e.g. v0.1.0)'
         required: true
         type: string
+      platform:
+        description: 'Optional desktop platform to build.'
+        required: false
+        default: 'all'
+        type: choice
+        options:
+          - all
+          - macos
+          - linux
+          - windows
 
 concurrency:
   group: desktop-release-${{ github.ref }}
   cancel-in-progress: false
 
+env:
+  SOURCE_TAG: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag || github.ref_name }}
+  DESKTOP_WORKSPACE: '@getpaseo/desktop'
+  DESKTOP_PACKAGE_PATH: 'packages/desktop'
+
 jobs:
-  publish-tauri:
+  publish-macos:
+    if: ${{ (github.event_name == 'workflow_dispatch' && (github.event.inputs.platform == 'all' || github.event.inputs.platform == 'macos')) || (github.event_name == 'push' && (startsWith(github.ref_name, 'v') || startsWith(github.ref_name, 'desktop-v') || startsWith(github.ref_name, 'desktop-macos-v'))) }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runner: macos-14
+            electron_arch: arm64
+          - runner: macos-15-intel
+            electron_arch: x64
     permissions:
       contents: write
       packages: read
-    runs-on: macos-latest
-    env:
-      RELEASE_TAG: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag || github.ref_name }}
+    runs-on: ${{ matrix.runner }}
 
     steps:
       - uses: actions/checkout@v4
@@ -31,83 +56,299 @@ jobs:
           fetch-depth: 0
           ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag || github.ref }}
 
+      - name: Resolve release metadata
+        shell: bash
+        run: node scripts/emit-release-env.mjs --source-tag "$SOURCE_TAG" >> "$GITHUB_ENV"
+
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
           node-version: '22'
           cache: 'npm'
+          cache-dependency-path: package-lock.json
           registry-url: 'https://npm.pkg.github.com'
           scope: '@boudra'
 
-      - name: Install Rust stable
-        uses: dtolnay/rust-toolchain@stable
-        with:
-          targets: aarch64-apple-darwin
-
       - name: Install JS dependencies
         run: npm ci
         env:
           NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Build web app for Tauri
-        run: npm run build:web --workspace=@getpaseo/app
-
-      - name: Set desktop version from tag
+      - name: Set desktop package version from tag
         shell: bash
         run: |
           node <<'NODE'
           const fs = require('node:fs');
           const path = require('node:path');
 
-          const rawTag = process.env.RELEASE_TAG;
-          if (!rawTag) throw new Error('RELEASE_TAG env var is missing');
+          const version = process.env.DESKTOP_VERSION;
+          if (!version) throw new Error('DESKTOP_VERSION env var is missing');
 
-          const version = rawTag.replace(/^desktop-/, '').replace(/^v/, '');
-          console.log(`Using desktop version ${version} from tag ${rawTag}`);
-
-          const tauriConfPath = path.join('packages', 'desktop', 'src-tauri', 'tauri.conf.json');
-          const tauriConfText = fs.readFileSync(tauriConfPath, 'utf8');
-          const tauriRe = /("version"\s*:\s*")([^"]+)(")/;
-          if (!tauriRe.test(tauriConfText)) {
-            throw new Error(`Failed to find version field in ${tauriConfPath}`);
-          }
-          fs.writeFileSync(tauriConfPath, tauriConfText.replace(tauriRe, `$1${version}$3`));
-
-          const cargoTomlPath = path.join('packages', 'desktop', 'src-tauri', 'Cargo.toml');
-          const cargoLines = fs.readFileSync(cargoTomlPath, 'utf8').split(/\r?\n/);
-          let inPackage = false;
-          let updated = false;
-          const nextLines = cargoLines.map((line) => {
-            if (/^\[package\]\s*$/.test(line)) inPackage = true;
-            else if (inPackage && /^\[/.test(line)) inPackage = false;
-
-            if (inPackage && /^version\s*=\s*".*"\s*$/.test(line)) {
-              updated = true;
-              return `version = "${version}"`;
-            }
-            return line;
-          });
-          if (!updated) throw new Error(`Failed to update Cargo package version in ${cargoTomlPath}`);
-          fs.writeFileSync(cargoTomlPath, `${nextLines.join('\n')}\n`);
+          const packageJsonPath = path.join(process.env.DESKTOP_PACKAGE_PATH, 'package.json');
+          const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+          packageJson.version = version;
+          fs.writeFileSync(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`);
           NODE
 
-      - name: Build and publish Tauri release
-        uses: tauri-apps/tauri-action@v0
+      - name: Build web app for desktop
+        run: npm run build:web --workspace=@getpaseo/app
+
+      - name: Build desktop release
+        shell: bash
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
-          APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
-          APPLE_SIGNING_IDENTITY: ${{ secrets.APPLE_SIGNING_IDENTITY }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          EP_GH_IGNORE_TIME: true
+          CSC_LINK: ${{ secrets.APPLE_CERTIFICATE }}
+          CSC_KEY_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
           APPLE_ID: ${{ secrets.APPLE_ID }}
-          APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
           APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
-          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
-          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
+        run: |
+          set -euo pipefail
+          publish_mode="never"
+          publish_args=()
+          if [[ "$IS_SMOKE_TAG" != "true" ]]; then
+            publish_mode="always"
+            publish_args+=("-c.publish.releaseType=$RELEASE_TYPE")
+          fi
+
+          npm run build --workspace="$DESKTOP_WORKSPACE" -- --publish "$publish_mode" --mac --${{ matrix.electron_arch }} "${publish_args[@]}"
+
+      - name: Upload manifest artifact
+        if: env.IS_SMOKE_TAG != 'true'
+        uses: actions/upload-artifact@v4
         with:
-          projectPath: packages/desktop
-          tagName: ${{ env.RELEASE_TAG }}
-          releaseName: Paseo Desktop ${{ env.RELEASE_TAG }}
-          releaseBody: See the assets to download and install this version.
-          releaseDraft: false
-          prerelease: false
-          args: --target aarch64-apple-darwin
+          name: mac-manifest-${{ matrix.electron_arch }}
+          path: ${{ env.DESKTOP_PACKAGE_PATH }}/release/latest-mac.yml
+          retention-days: 1
+
+  finalize-mac-manifest:
+    needs: [publish-macos]
+    if: ${{ needs.publish-macos.result == 'success' }}
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Resolve release tag
+        shell: bash
+        run: node scripts/emit-release-env.mjs --source-tag "$SOURCE_TAG" >> "$GITHUB_ENV"
+
+      - name: Download manifest artifacts
+        if: env.IS_SMOKE_TAG != 'true'
+        uses: actions/download-artifact@v4
+        with:
+          pattern: mac-manifest-*
+
+      - name: Merge manifests
+        if: env.IS_SMOKE_TAG != 'true'
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          node <<'NODE'
+          const fs = require('node:fs');
+
+          // Simple YAML parser for electron-builder's latest-mac.yml format
+          function parseManifest(text) {
+            const lines = text.split('\n');
+            const result = { files: [] };
+            let currentFile = null;
+
+            for (const line of lines) {
+              if (line.startsWith('version:')) result.version = line.split(': ')[1].trim();
+              else if (line.startsWith('path:')) result.path = line.split(': ')[1].trim();
+              else if (line.startsWith('sha512:') && !currentFile) result.sha512 = line.split(': ')[1].trim();
+              else if (line.startsWith('releaseDate:')) result.releaseDate = line.split(': ')[1].trim().replace(/'/g, '');
+              else if (line.trim().startsWith('- url:')) {
+                currentFile = { url: line.trim().replace('- url: ', '') };
+                result.files.push(currentFile);
+              } else if (line.trim().startsWith('sha512:') && currentFile) {
+                currentFile.sha512 = line.trim().split(': ')[1].trim();
+              } else if (line.trim().startsWith('size:') && currentFile) {
+                currentFile.size = parseInt(line.trim().split(': ')[1].trim(), 10);
+                currentFile = null;
+              }
+            }
+            return result;
+          }
+
+          function toYaml(manifest) {
+            let out = `version: ${manifest.version}\n`;
+            out += `files:\n`;
+            for (const f of manifest.files) {
+              out += `  - url: ${f.url}\n`;
+              out += `    sha512: ${f.sha512}\n`;
+              out += `    size: ${f.size}\n`;
+            }
+            out += `path: ${manifest.path}\n`;
+            out += `sha512: ${manifest.sha512}\n`;
+            out += `releaseDate: '${manifest.releaseDate}'\n`;
+            return out;
+          }
+
+          const arm64Text = fs.readFileSync('mac-manifest-arm64/latest-mac.yml', 'utf8');
+          const x64Text = fs.readFileSync('mac-manifest-x64/latest-mac.yml', 'utf8');
+
+          const arm64 = parseManifest(arm64Text);
+          const x64 = parseManifest(x64Text);
+
+          // Merge: all files from both, default path points to arm64 zip
+          const merged = {
+            version: arm64.version,
+            files: [...arm64.files, ...x64.files],
+            path: arm64.path,
+            sha512: arm64.sha512,
+            releaseDate: arm64.releaseDate || x64.releaseDate,
+          };
+
+          const output = toYaml(merged);
+          fs.writeFileSync('latest-mac.yml', output);
+          console.log('Merged manifest:\n' + output);
+          NODE
+
+      - name: Upload merged manifest to release
+        if: env.IS_SMOKE_TAG != 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh release upload "$RELEASE_TAG" latest-mac.yml --clobber --repo "${{ github.repository }}"
+
+  publish-linux:
+    if: ${{ (github.event_name == 'workflow_dispatch' && (github.event.inputs.platform == 'all' || github.event.inputs.platform == 'linux')) || (github.event_name == 'push' && (startsWith(github.ref_name, 'v') || startsWith(github.ref_name, 'desktop-v') || startsWith(github.ref_name, 'desktop-linux-v'))) }}
+    permissions:
+      contents: write
+      packages: read
+    runs-on: ubuntu-22.04
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag || github.ref }}
+
+      - name: Resolve release metadata
+        shell: bash
+        run: node scripts/emit-release-env.mjs --source-tag "$SOURCE_TAG" >> "$GITHUB_ENV"
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+          cache-dependency-path: package-lock.json
+          registry-url: 'https://npm.pkg.github.com'
+          scope: '@boudra'
+
+      - name: Install JS dependencies
+        run: npm ci
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set desktop package version from tag
+        shell: bash
+        run: |
+          node <<'NODE'
+          const fs = require('node:fs');
+          const path = require('node:path');
+
+          const version = process.env.DESKTOP_VERSION;
+          if (!version) throw new Error('DESKTOP_VERSION env var is missing');
+
+          const packageJsonPath = path.join(process.env.DESKTOP_PACKAGE_PATH, 'package.json');
+          const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+          packageJson.version = version;
+          fs.writeFileSync(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`);
+          NODE
+
+      - name: Build web app for desktop
+        run: npm run build:web --workspace=@getpaseo/app
+
+      - name: Build desktop release
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          EP_GH_IGNORE_TIME: true
+        run: |
+          set -euo pipefail
+          publish_mode="never"
+          publish_args=()
+          if [[ "$IS_SMOKE_TAG" != "true" ]]; then
+            publish_mode="always"
+            publish_args+=("-c.publish.releaseType=$RELEASE_TYPE")
+          fi
+
+          npm run build --workspace="$DESKTOP_WORKSPACE" -- --publish "$publish_mode" --linux --x64 "${publish_args[@]}"
+
+  publish-windows:
+    if: ${{ (github.event_name == 'workflow_dispatch' && (github.event.inputs.platform == 'all' || github.event.inputs.platform == 'windows')) || (github.event_name == 'push' && (startsWith(github.ref_name, 'v') || startsWith(github.ref_name, 'desktop-v') || startsWith(github.ref_name, 'desktop-windows-v'))) }}
+    permissions:
+      contents: write
+      packages: read
+    runs-on: windows-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag || github.ref }}
+
+      - name: Resolve release metadata
+        shell: bash
+        run: node scripts/emit-release-env.mjs --source-tag "$SOURCE_TAG" >> "$GITHUB_ENV"
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+          cache-dependency-path: package-lock.json
+          registry-url: 'https://npm.pkg.github.com'
+          scope: '@boudra'
+
+      - name: Install JS dependencies
+        run: npm ci
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set desktop package version from tag
+        shell: bash
+        run: |
+          node <<'NODE'
+          const fs = require('node:fs');
+          const path = require('node:path');
+
+          const version = process.env.DESKTOP_VERSION;
+          if (!version) throw new Error('DESKTOP_VERSION env var is missing');
+
+          const packageJsonPath = path.join(process.env.DESKTOP_PACKAGE_PATH, 'package.json');
+          const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+          packageJson.version = version;
+          fs.writeFileSync(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`);
+          NODE
+
+      - name: Build workspace dependencies
+        run: npm run build:workspace-deps --workspace=@getpaseo/app
+
+      - name: Build web app for desktop
+        shell: pwsh
+        run: |
+          $patchPath = (Get-Item "$env:GITHUB_WORKSPACE/scripts/metro-config-windows-loader-patch.cjs").FullName
+          $env:NODE_OPTIONS = "--require=$patchPath"
+          npx expo export --platform web
+        working-directory: packages/app
+
+      - name: Build desktop release
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          EP_GH_IGNORE_TIME: true
+        run: |
+          set -euo pipefail
+          publish_mode="never"
+          publish_args=()
+          if [[ "$IS_SMOKE_TAG" != "true" ]]; then
+            publish_mode="always"
+            publish_args+=("-c.publish.releaseType=$RELEASE_TYPE")
+          fi
+
+          npm run build --workspace="$DESKTOP_WORKSPACE" -- --publish "$publish_mode" --win --x64 "${publish_args[@]}"

.github/workflows/fix-nix-hash.yml

@@ -0,0 +1,45 @@
+name: Fix Nix hash
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'package.json'
+      - 'package-lock.json'
+  pull_request:
+    paths:
+      - 'package.json'
+      - 'package-lock.json'
+
+permissions:
+  contents: write
+
+jobs:
+  fix-nix-hash:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref || github.ref }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - uses: cachix/install-nix-action@v31
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+
+      - name: Fix lockfile and update hash
+        run: ./scripts/update-nix.sh
+
+      - name: Commit changes
+        run: |
+          git diff --quiet package-lock.json nix/package.nix && exit 0
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add package-lock.json nix/package.nix
+          git commit -m "fix: update lockfile signatures and Nix hash"
+          git push

.github/workflows/nix-build.yml

@@ -0,0 +1,59 @@
+name: Nix Build
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'nix/**'
+      - 'flake.nix'
+      - 'flake.lock'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'packages/highlight/**'
+      - 'packages/server/**'
+      - 'packages/relay/**'
+      - 'packages/cli/**'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'nix/**'
+      - 'flake.nix'
+      - 'flake.lock'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'packages/highlight/**'
+      - 'packages/server/**'
+      - 'packages/relay/**'
+      - 'packages/cli/**'
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    continue-on-error: false
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: cachix/install-nix-action@v31
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+
+      - name: Build Nix package
+        run: nix build .#default -o result
+
+      - name: Verify lockfile is complete
+        # npm silently omits resolved/integrity fields in workspace monorepos.
+        # Nix needs them for offline builds. See https://github.com/npm/cli/issues/4460
+        run: |
+          node scripts/fix-lockfile.mjs package-lock.json
+          git diff --exit-code package-lock.json || {
+            echo "ERROR: package-lock.json has missing resolved/integrity fields."
+            echo "This is a known npm bug: https://github.com/npm/cli/issues/4460"
+            echo "Run 'node scripts/fix-lockfile.mjs' and commit the result."
+            exit 1
+          }
+
+      - name: Check npmDepsHash is up to date
+        run: ./scripts/update-nix.sh --check

.github/workflows/release-notes-sync.yml

@@ -0,0 +1,67 @@
+name: Release Notes Sync
+
+on:
+  push:
+    tags:
+      - "v*"
+    branches:
+      - main
+    paths:
+      - "CHANGELOG.md"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag to sync (e.g. v0.1.14). Leave empty to use top changelog entry."
+        required: false
+        type: string
+      create_if_missing:
+        description: "Create release if missing (normally only needed for tag events)."
+        required: false
+        default: false
+        type: boolean
+
+concurrency:
+  group: release-notes-sync-${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag || github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  sync-release-notes:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Sync release body from changelog
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          EVENT_NAME: ${{ github.event_name }}
+          REF: ${{ github.ref }}
+          INPUT_TAG: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/') && github.ref_name || github.event.inputs.tag }}
+          INPUT_CREATE_IF_MISSING: ${{ github.event.inputs.create_if_missing }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          args=(--repo "$REPO")
+
+          if [ -n "${INPUT_TAG:-}" ]; then
+            args+=(--tag "$INPUT_TAG")
+          fi
+
+          create_if_missing="false"
+          if [ "$EVENT_NAME" = "push" ] && [[ "$REF" == refs/tags/v* ]]; then
+            create_if_missing="true"
+          elif [ "$EVENT_NAME" = "workflow_dispatch" ] && [ "${INPUT_CREATE_IF_MISSING:-false}" = "true" ]; then
+            create_if_missing="true"
+          fi
+
+          if [ "$create_if_missing" = "true" ]; then
+            args+=(--create-if-missing)
+          fi
+
+          node scripts/sync-release-notes-from-changelog.mjs "${args[@]}"

.github/workflows/server-ci.yml

@@ -36,8 +36,17 @@ jobs:
       - name: Install server dependencies
         run: npm install --workspace=@getpaseo/server --include-workspace-root
 
+      - name: Build highlight dependency
+        run: npm run build --workspace=@getpaseo/highlight
+
+      - name: Build relay dependency
+        run: npm run build --workspace=@getpaseo/relay
+
       - name: Typecheck
         run: npm run typecheck --workspace=@getpaseo/server
 
       - name: Test
         run: npm run test --workspace=@getpaseo/server
+        env:
+          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

.gitignore

@@ -46,6 +46,9 @@ test-results/
 # Vercel
 .vercel/
 
+# Expo
+.expo/
+
 # Misc
 *.pem
 .vercel
@@ -71,6 +74,12 @@ valknut-report.json/
 **/.paseo-provider-history/
 .claude/settings.local.json
 **/.claude/settings.local.json
+.claude/scheduled_tasks.lock
+.claude/worktrees/
 .plans/
 packages/server/src/server/fixtures/dictation/dictation-debug-largest.wav
 packages/server/src/server/fixtures/dictation/dictation-debug-largest.transcript.txt
+
+/artifacts
+packages/desktop/.cache/
+packages/desktop/src-tauri/resources/managed-runtime/

.mise.toml

@@ -0,0 +1,9 @@
+[env]
+ANDROID_HOME = "{{env.HOME}}/.local/share/mise/installs/android-sdk/1.0"
+_.path = [
+  "{{env.HOME}}/.local/share/mise/installs/android-sdk/1.0/platform-tools",
+  "{{env.HOME}}/.local/share/mise/installs/android-sdk/1.0/emulator",
+]
+
+[tools]
+java = "17"

.prettierignore

@@ -1,21 +0,0 @@
-# Dependencies
-node_modules
-
-# Build outputs
-dist
-.next
-.expo
-build
-*.tsbuildinfo
-
-# Coverage
-coverage
-
-# Lock files
-*.lock
-package-lock.json
-
-# Generated
-android
-ios
-.turbo

.prettierrc

@@ -1,7 +0,0 @@
-{
-  "semi": false,
-  "singleQuote": true,
-  "trailingComma": "es5",
-  "tabWidth": 2,
-  "printWidth": 100
-}

.tool-versions

@@ -1,2 +1,4 @@
-rust 1.85.1
-nodejs 22.20.0
+rust        1.85.1
+nodejs      22.20.0
+java        21
+android-sdk latest

CHANGELOG.md

@@ -1,6 +1,383 @@
 # Changelog
 
-## [0.1.9] - 2026-02-17
+## 0.1.43 - 2026-04-02
+
+### Added
+- Copilot agent support via ACP base provider — connect GitHub Copilot as a new agent type.
+- Searchable model favorites — quickly find and pin preferred models.
+- Slash command support for OpenCode agents.
+
+### Improved
+- Refined model selector UX with better mobile sheet behavior.
+- Workspace status now uses amber alert styling for "needs input" state.
+- Themed scrollbar on message input for consistent styling.
+
+### Fixed
+- Ctrl+C/V copy and paste now works correctly in the terminal on Windows and Linux.
+- Shell arguments with spaces are now properly quoted on Windows.
+- Claude models with 1M context support are now correctly reported.
+
+## 0.1.42 - 2026-04-01
+
+### Fixed
+- Fixed Claude Code failing to launch on Windows when installed to a path with spaces (e.g. `C:\Program Files\...`).
+
+## 0.1.41 - 2026-04-01
+
+### Fixed
+- Fixed agent spawning on Windows — all providers (Claude, Codex, OpenCode) now use shell mode so npm shims and `.cmd` wrappers resolve correctly.
+- Fixed terminal creation on Windows defaulting to a Unix shell instead of `cmd.exe`.
+- Fixed path handling across the app to support Windows drive-letter paths (`C:\...`) and UNC paths (`\\...`).
+- Fixed executable resolution on Windows to work with `nvm4w` and similar Node version managers.
+- Eliminated white flash on window resize in dark mode by setting the native window background color to match the theme.
+- Fixed titlebar drag region — replaced the fragile pointer-event approach with VS Code's proven static CSS `app-region: drag` pattern.
+- Fixed context menu for copy/paste across the desktop app.
+- Fixed shortcut rebinding UI to show held modifier keys and recognize additional keys (Tab, Delete, Home, End, Page Up/Down, Insert, F1–F12).
+- Removed the 40-item cap on activity timeline output so long agent sessions display their full history.
+
+### Improved
+- Improved light mode theming with dedicated workspace background, scrollbar handle colors, and lighter shadows.
+- Window controls overlay on Windows/Linux reduced from 48px to 29px height for a more compact titlebar.
+
+## 0.1.40 - 2026-04-01
+
+### Added
+- Workspace tabs can now be closed in batches.
+
+### Improved
+- Provider model lists are now cached per server and provider, reducing redundant model lookups in the UI.
+
+### Fixed
+- OpenCode reasoning content no longer appears duplicated as assistant text.
+- Daemon no longer crashes when a Codex binary is missing or fails to spawn.
+- Archive tab now correctly reconciles agent visibility after archiving.
+- File diff tracking in workspaces now works correctly on Linux.
+- iPad layout now renders correctly in desktop mode.
+- macOS auto-updater now correctly delivers both arm64 and x64 binaries — previously whichever architecture finished building last would overwrite the other's update manifest.
+
+## 0.1.39 - 2026-03-30
+
+### Added
+- **Terminal management from the CLI** — new `paseo terminal` command group lets you list, create, and interact with workspace terminals without leaving your terminal.
+- **Material file icons in the explorer** — the file explorer tree now shows language-specific icons (TypeScript, JSON, Markdown, etc.) so you can spot files at a glance.
+
+### Fixed
+- Fixed iOS sidebar scroll flicker caused by redundant overflow clipping.
+- Centralized window controls padding into a shared hook, eliminating layout inconsistencies across platforms.
+
+## 0.1.38 - 2026-03-30
+
+### Fixed
+- Fixed daemon startup race where the app could time out connecting on first launch because the PID file advertised a listen address before the server was ready.
+- Fixed daemon log rotation losing startup traces — trace-level WebSocket logs no longer include full message payloads.
+
+## 0.1.37 - 2026-03-29
+
+### Added
+- Custom window controls on Windows and Linux — the native titlebar is replaced with overlay controls that match the app's design.
+- Desktop file logging with electron-log for easier debugging of daemon and app issues.
+
+### Fixed
+- Fixed broken PATH propagation and Claude binary resolution on Windows.
+- Dictation errors now show a visible toast instead of failing silently.
+
+## 0.1.36 - 2026-03-27
+
+### Fixed
+- Fixed Windows drive-letter path handling across the codebase.
+- Fixed stale Nix hash with automatic lockfile-change detection.
+
+### Added
+- Added metrics collection and terminal performance tests.
+
+## 0.1.35 - 2026-03-26
+
+### Improved
+- Faster app startup by redirecting to the welcome screen immediately and showing host connection status inline.
+- Codex file deletions now display correctly as removed lines in diffs.
+- OpenCode questions are now surfaced in the permission UI.
+
+### Fixed
+- Fixed queued prompt dispatch after idle transition.
+- Replaced bash-only `mapfile` with a portable `while-read` loop in the chat script.
+
+### Added
+- Added support for Nix and NixOS installation.
+
+## 0.1.34 - 2026-03-25
+
+### Added
+- Added `paseo archive` as a top-level alias for `paseo agent archive`.
+- Added the `PASEO_AGENT_ID` environment variable for Claude and Codex agents.
+- Added a redesigned command autocomplete with a detail card and dropdown styling.
+- Linked Android download surfaces to the Google Play Store.
+
+### Improved
+- Autonomous turns now complete gracefully on interrupt instead of being canceled.
+- Thinking/model selection now always resolves to a real option instead of showing a generic Default choice.
+- Restored per-provider form preferences and removed the Auto model fallback.
+- Improved Codex activity logs with clearer tool-call summaries.
+- Reduced unnecessary re-renders in the agent panel and input area for smoother interaction.
+- Improved chat transcript readability.
+
+### Fixed
+- Fixed `paseo send --no-wait` not taking effect.
+- Fixed stale abort results contaminating replacement turns after an interrupt.
+- Fixed Claude interrupt handling and autonomous wake reliability.
+- Fixed nested Claude Code session detection and provider availability checks.
+- Fixed agent input focus scoping across panels.
+- Fixed terminal snapshot ordering when subscribing.
+- Fixed `chat read --since` to accept message IDs.
+- Fixed keyboard pane focus syncing with the active panel.
+- Fixed assistant text selection on web.
+- Fixed archived-agent notifications still appearing in chat rooms.
+- Fixed the attach-images button interaction in the message composer.
+- Pruned wrong-platform native binaries from Electron desktop builds.
+
+## 0.1.33 - 2026-03-23
+
+### Fixed
+- Fixed the desktop app failing to reopen after closing on macOS — the daemon and agent processes were registering with Launch Services as instances of the main app, blocking subsequent launches.
+- Fixed dictation not working in the packaged desktop app — the microphone entitlement was missing from the hardened runtime configuration.
+- Fixed leaked Claude Code child processes when agents were closed — the SDK query stream was not being properly shut down.
+- The notification test button now surfaces errors instead of failing silently.
+
+## 0.1.32 - 2026-03-23
+
+### Added
+- Fully rebindable keyboard shortcuts with chord support — all shortcuts are now declarative with proper Cmd (Mac) vs Ctrl (Windows/Linux) separation.
+- Migrated the desktop app from Tauri to Electron, with macOS notarization, code signing, and Linux Wayland support.
+- Added line numbers and word-wrap toggle to file previews.
+- Added an archived agent callout with an unarchive button so you can restore agents directly from the chat view.
+- Added workspace kind indicators in the sidebar (e.g. worktree vs standalone).
+- Expanded diff syntax highlighting to cover more languages.
+- Added status bar tooltips for project and agent status.
+
+### Improved
+- Redesigned the mobile tab switcher as a compact header row with quick access to new agents and terminals.
+- Streamlined workspace creation — worktrees are now created inline with a single action instead of a multi-step flow.
+- Agent history now streams from disk on reconnect, so you see past messages immediately instead of a blank screen.
+- Automatic cleanup of stale workspaces: deleted worktree directories and fully-archived workspaces are pruned automatically.
+- After archiving a workspace, the app now redirects to the next available workspace instead of leaving you on a dead screen.
+- Reopening an archived agent tab now keeps it open instead of collapsing back to archived state.
+- Reduced unnecessary re-renders across the workspace screen, sidebar, and agent list for smoother scrolling and interaction.
+- Agent list no longer refreshes in the background when the screen is unfocused, saving resources.
+- Desktop key repeat now works correctly on macOS.
+- Desktop notifications on macOS are more reliable.
+- Daemon startup no longer blocks on model downloads.
+- Better error messages from the daemon — RPC errors now include the actual underlying details.
+
+### Fixed
+- Fixed user messages appearing as assistant output in the timeline when messages contained structured content blocks.
+- Fixed archived workspace routing so navigating to an archived session no longer breaks the app.
+- Fixed Linux AppImage failing to launch on Wayland-only desktops.
+- Fixed desktop window drag coordinates being applied when they shouldn't be.
+
+## 0.1.30 - 2026-03-19
+
+### Added
+- Added terminal tabs, split pane controls, and drop previews for workspace layouts.
+- Added a combined model selector and agent mode visuals across key UI surfaces.
+- Added Open Graph metadata improvements for richer website sharing previews.
+
+### Improved
+- Improved workspace navigation with better active-workspace tracking and keyboard-driven pane interactions.
+- Improved terminal scrollbar behavior, pane focus handling, and status bar/message input spacing.
+- Improved project picker path display and general workspace UI polish.
+
+### Fixed
+- Fixed agent startup reliability by tightening PATH resolution and surfacing missing provider binaries in status.
+- Fixed workspace route syncing, drag hit areas, and git diff panel header styling regressions.
+- Fixed website mobile horizontal scrolling and ensured the workspace audio module builds during EAS installs.
+
+## 0.1.28 - 2026-03-15
+
+### Added
+- Added OpenCode build and plan modes.
+- Added website landing pages for Claude Code, Codex, and OpenCode.
+
+### Improved
+- Improved the git action menu for more reliable repository actions.
+- Improved the mobile settings screen, workspace header actions, and welcome screen presentation.
+- Updated the website hero copy and added a sponsor callout section.
+
+### Fixed
+- Fixed assistant file links so they open the correct workspace files from chat.
+
+## 0.1.27 - 2026-03-13
+
+### Added
+- Added voice runtime with new audio engine architecture for voice interactions.
+- Added Grep tool support in Claude tool-call mapping.
+- Added ability to open workspace files directly from agent chat messages.
+- Added desktop notifications via a custom native bridge.
+
+### Improved
+- Improved image picker, markdown rendering, and UI interactions.
+- Improved shell environment detection using shell-env.
+
+### Fixed
+- Fixed platform-specific markdown link rendering.
+- Fixed Linux AppImage CLI resource paths.
+- Fixed Codex replacement stream being killed by stale turn notifications.
+
+## 0.1.26 - 2026-03-12
+
+### Added
+- Added single-instance desktop behavior, Android APK download access, and refreshed splash screen styling.
+- Added bundled Codex and OpenCode binaries in the server so setup no longer depends on global installs.
+- Added Windows support with improved cross-platform shell execution.
+
+### Improved
+- Improved desktop runtime behavior on Windows by suppressing console windows and defaulting app data to `~/.paseo`.
+- Added a Discord link to the website navigation.
+
+### Fixed
+- Fixed desktop Claude agent startup from the managed runtime and rotated logs correctly on restart.
+- Fixed the home route to hide browser chrome when appropriate.
+- Fixed Expo Metro compatibility by updating the `exclusionList` import.
+- Fixed noisy shell output interfering with executable lookup.
+- Fixed Windows resource-path handling by stripping the extended-length path prefix.
+
+## 0.1.25 - 2026-03-11
+
+### Fixed
+- Fixed desktop app failing to start the built-in daemon on fresh macOS installs. The DMG was not notarized and code-signing stripped entitlements from the bundled Node runtime, causing Gatekeeper to block execution.
+- Fixed Linux AppImage build by restoring the AppImage bundle format and stripping CUDA dependencies from onnxruntime.
+
+## 0.1.24 - 2026-03-10
+
+### Improved
+- Improved command center keyboard navigation and new tab shortcut.
+- Simplified desktop release pipeline for faster and more reliable builds.
+
+## 0.1.21 - 2026-03-10
+### Improved
+- Improved desktop release reliability by fixing the Windows managed-runtime build path during GitHub Actions releases.
+
+### Fixed
+- Fixed a desktop release CI failure caused by a Unix-only server build script on Windows runners.
+- Fixed server CI to build the relay dependency before running tests, restoring relay E2EE test coverage on clean runners.
+- Fixed a Claude redesign test that depended on the local Claude CLI being installed.
+
+## 0.1.20 - 2026-03-10
+### Added
+- Added workspace sidebar git actions with quick diff stats and archive controls.
+- Added refreshed website downloads and homepage presentation for desktop installs.
+
+### Improved
+- Desktop release packaging now rebuilds and validates the bundled managed runtime during CI, improving installer reliability for macOS users.
+- Improved desktop and web stream rendering, settings polish, and React 19.1.4 compatibility.
+
+### Fixed
+- Fixed Claude interrupt/restart regressions and strengthened managed-daemon smoke coverage for desktop releases.
+
+## 0.1.19 - 2026-03-09
+### Added
+- Added a draft GitHub release flow so maintainers can upload and review desktop and Android release assets before publishing the final release.
+
+## 0.1.18 - 2026-03-06
+### Added
+- Added a desktop `Mod+W` shortcut to close the current tab.
+
+### Improved
+- New and newly selected terminals now take focus automatically so you can type immediately.
+- Kept newly created workspaces and projects in a more stable order in the sidebar.
+- Improved project naming for GitHub remotes and expanded project icon discovery to Phoenix `priv/static` assets.
+- Updated the website desktop download link to use the universal macOS DMG.
+
+### Fixed
+- Restored automatic agent metadata generation for Claude runs.
+
+## 0.1.17 - 2026-03-06
+### Added
+- New workspace-first navigation model with workspace tabs, file tabs, and sortable tab groups.
+- Keyboard shortcuts for workspace and tab navigation, with shortcut badges in the sidebar.
+- Workspace-level archive actions with improved worktree archiving flow and context menu support.
+- In-chat task notifications rendered as synthetic tool-call events for clearer status tracking.
+
+### Improved
+- Desktop builds now ship as a universal macOS binary (Apple Silicon + Intel).
+- More reliable workspace routing and tab identity handling across refreshes and deep links.
+- Better sidebar drag-and-drop behavior with explicit drag handles and nested list interactions.
+- Smoother terminal/file rendering and WebGL-backed terminal performance improvements.
+- Stronger provider error surfacing and updated Claude model/runtime handling.
+
+### Fixed
+- Fixed orphan workspace runs caused by non-canonical tab routes.
+- Fixed mobile terminal tab remount/routing restore issues.
+- Fixed agent metadata title/branch update reliability.
+- Fixed stream/timeline ordering and cursor synchronization issues in the app.
+- Fixed reversed edge-wheel scroll behavior in chat/tool stream views.
+
+## 0.1.16 - 2026-02-22
+### Added
+- Update the Paseo desktop app and local daemon directly from Settings.
+- Microphone and notification permission controls in Settings.
+- Thinking/reasoning mode — agents can use extended thinking when the provider supports it.
+- Autonomous run mode — let agents keep working without manual approval at each step.
+- `paseo wait` now shows a snapshot of recent agent activity while you wait.
+
+### Improved
+- Smoother streaming with less UI flicker and scroll jumping during long agent runs.
+- Faster agent sidebar list rendering.
+- Archiving an agent now stops it first instead of archiving a half-running session.
+- Agent titles no longer reset when refreshing.
+- More reliable relay connections.
+
+### Fixed
+- Fixed Claude background tasks desyncing the chat.
+- Fixed duplicate user messages appearing in the timeline.
+- Fixed a startup crash caused by an OpenCode SDK update.
+- Fixed spurious "needs attention" notifications from background agent activity.
+
+## 0.1.15 - 2026-02-19
+### Added
+- Added a public changelog page on the website so users can browse release notes.
+
+### Improved
+- Redesigned the website get-started experience into a clearer two-step flow.
+- Simplified website GitHub navigation and changelog headings.
+- Improved app draft/new-agent UX with clearer working directory placeholder and empty-state messaging.
+- Enabled drag interactions in previously unhandled areas on the desktop draft screen.
+- Hid empty filter groups in the left sidebar.
+
+### Fixed
+- Fixed archived-agent navigation by redirecting archived agent routes to draft.
+- Fixed duplicate `/rewind` user-message behavior.
+
+## 0.1.14 - 2026-02-19
+### Added
+- Added Claude `/rewind` command support.
+- Added slash command access in the draft agent composer.
+- Added `@` workspace file autocomplete in chat prompts.
+- Added support for pasting images directly into prompt attachments.
+- Added optimistic image previews for pending user message attachments.
+- Added shared desktop/web overlay scroll handles, including file preview panes.
+
+### Improved
+- Improved worktree flow after shipping, including better merged PR detection.
+- Improved draft workflow by enabling the explorer sidebar immediately after CWD selection.
+- Improved new worktree-agent defaults by prefilling CWD to the main repository.
+- Improved desktop command autocomplete behavior to match combobox interactions.
+- Improved git sync UX by simplifying sync labels and only showing Sync when a branch diverges from origin.
+- Improved desktop settings and permissions UX on desktop.
+- Improved scrollbar visibility, drag interactions, tracking, and animation timing on web/desktop.
+
+### Fixed
+- Fixed worktree archive/setup lifecycle issues, including terminal cleanup and archive timing.
+- Fixed worktree path collisions by hashing CWD for collision-safe worktree roots.
+- Fixed terminal sizing when switching back to an agent session.
+- Fixed accidental terminal closure risk by adding confirmation for running shell commands.
+- Fixed archive loading-state consistency across the sidebar and agent screen.
+- Fixed autocomplete popover stability and workspace suggestion ranking.
+- Fixed dictation timeouts caused by dangling non-final segments.
+- Fixed server lock ownership when spawned as a child process by using parent PID ownership.
+- Fixed hidden directory leakage in server CWD suggestions.
+- Fixed agent attention notification payload consistency across providers.
+- Fixed daemon version badge visibility in settings when daemon version data is unavailable.
+
+## 0.1.9 - 2026-02-17
 ### Improved
 - Unified structured-output generation through a single shared schema-validation and retry pipeline.
 - Reused provider availability checks for structured generation fallback selection.
@@ -11,7 +388,7 @@
 - Fixed `run --output-schema` failures where providers returned empty `lastMessage` by recovering from timeline assistant output.
 - Fixed internal commit message, pull request text, and agent metadata generation to follow one consistent structured pipeline.
 
-## [0.1.8] - 2026-02-17
+## 0.1.8 - 2026-02-17
 ### Added
 - Added a cross-platform confirm dialog flow for daemon restarts.
 
@@ -23,10 +400,10 @@
 - Fixed stuck "send while running" recovery across app and server session handling.
 - Fixed Claude session identity preservation when reloading existing agents.
 - Fixed combobox option behavior and related interactions.
-- Fixed Tauri file-drop listener cleanup to avoid uncaught unlisten errors.
+- Fixed desktop file-drop listener cleanup to avoid uncaught unlisten errors.
 - Fixed web tool-detail wheel event routing at scroll edges.
 
-## [0.1.7] - 2026-02-16
+## 0.1.7 - 2026-02-16
 ### Added
 - Improved agent workspace flows with better directory suggestions.
 - Added iOS TestFlight and Android app access request forms on the website.
@@ -40,11 +417,11 @@
 - Fixed CLI version output issues.
 - Hardened server runtime loading for local speech dependencies.
 
-## [0.1.6] - 2026-02-16
+## 0.1.6 - 2026-02-16
 ### Notes
 - No major visible product changes in this patch release.
 
-## [0.1.5] - 2026-02-16
+## 0.1.5 - 2026-02-16
 ### Added
 - Added terminal reattach support and better worktree terminal handling.
 - Added global keyboard shortcut help in the app.
@@ -55,7 +432,7 @@
 - Improved terminal streaming reliability and lifecycle handling.
 - Preserved explorer tab state so context survives navigation better.
 
-## [0.1.4] - 2026-02-14
+## 0.1.4 - 2026-02-14
 ### Added
 - Added voice capability status reporting in the client.
 - Added background local speech model downloads with runtime gating.
@@ -73,7 +450,7 @@
 - Fixed stale relay client timer behavior.
 - Fixed unnecessary git diff header auto-scroll on collapse.
 
-## [0.1.3] - 2026-02-12
+## 0.1.3 - 2026-02-12
 ### Added
 - Added CLI onboarding command.
 - Added CLI `--output-schema` support for structured agent output.
@@ -89,11 +466,11 @@
 ### Fixed
 - Fixed dev runner entry issues and sherpa TTS initialization behavior.
 
-## [0.1.2] - 2026-02-11
+## 0.1.2 - 2026-02-11
 ### Notes
 - No major visible product changes in this patch release.
 
-## [0.1.1] - 2026-02-11
+## 0.1.1 - 2026-02-11
 
 ### Added
 - Initial `0.1.x` release line.

CLAUDE.md

@@ -1,222 +1,52 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-Paseo is a mobile app for monitoring and controlling your local AI coding agents from anywhere. Your dev environment, in your pocket.
-
-**Key features:**
-- Real-time streaming of agent output
-- Voice commands for hands-free interaction
-- Push notifications when tasks complete
-- Multi-agent orchestration across projects
-
-**Not a cloud sandbox** - Paseo connects directly to your actual development environment. Your code stays on your machine.
+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.
 
-## Monorepo Structure
+## Repository map
 
 This is an npm workspace monorepo:
 
-- **packages/server**: The Paseo daemon that runs on your machine. Manages agent processes, provides WebSocket API for real-time streaming, and exposes an MCP server for agent control.
-- **packages/app**: Cross-platform client (Expo). Connects to one or more servers, displays agent output, handles voice input, and sends push notifications.
-- **packages/cli**: The `paseo` CLI that is used to manage the deamon, and acts as a client to it with  Docker-style commands like `paseo run/ls/logs/wait`
-- **packages/website**: Marketing site at paseo.sh (TanStack Router + Cloudflare Workers).
+- `packages/server` — Daemon: agent lifecycle, WebSocket API, MCP server
+- `packages/app` — Mobile + web client (Expo)
+- `packages/cli` — Docker-style CLI (`paseo run/ls/logs/wait`)
+- `packages/relay` — E2E encrypted relay for remote access
+- `packages/desktop` — Electron desktop wrapper
+- `packages/website` — Marketing site (paseo.sh)
 
-## Development Server
+## Documentation
 
-The `npm run dev` script automatically picks an available port for the development server.
+| Doc | What's in it |
+|---|---|
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | System design, package layering, WebSocket protocol, agent lifecycle, data flow |
+| [docs/CODING_STANDARDS.md](docs/CODING_STANDARDS.md) | Type hygiene, error handling, state design, React patterns, file organization |
+| [docs/TESTING.md](docs/TESTING.md) | TDD workflow, determinism, real dependencies over mocks, test organization |
+| [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) | Dev server, build sync gotchas, CLI reference, agent state, Playwright MCP |
+| [docs/RELEASE.md](docs/RELEASE.md) | Release playbook, draft releases, completion checklist |
+| [docs/ANDROID.md](docs/ANDROID.md) | App variants, local/cloud builds, EAS workflows |
+| [docs/DESIGN.md](docs/DESIGN.md) | How to design features before implementation |
+| [SECURITY.md](SECURITY.md) | Relay threat model, E2E encryption, DNS rebinding, agent auth |
 
-When running in a worktree or alongside the main checkout, set `PASEO_HOME` to isolate state:
+## Quick start
 
 ```bash
-PASEO_HOME=~/.paseo-blue npm run dev
+npm run dev                          # Start daemon + Expo in Tmux
+npm run cli -- ls -a -g              # List all agents
+npm run cli -- daemon status         # Check daemon status
+npm run typecheck                    # Always run after changes
 ```
 
-- `PASEO_HOME` – path for runtime state (agent data, sockets, etc.). Defaults to `~/.paseo`; set this to a unique directory when running a secondary server instance.
+See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for full setup, build sync requirements, and debugging.
 
-## Running and checking logs
+## Critical rules
 
-Both the server and Expo app are running in a Tmux session. See CLAUDE.local.md for system-specific session details.
+- **NEVER restart the main Paseo daemon on port 6767 without permission** — it manages all running agents. If you're an agent, restarting it kills your own process.
+- **NEVER assume a timeout means the service needs restarting** — timeouts can be transient.
+- **NEVER add auth checks to tests** — agent providers handle their own auth.
+- **Always run typecheck after every change.**
 
 ## Debugging
 
-### Daemon and CLI
 
-The Paseo daemon communicates via WebSocket. In the main checkout:
-- Daemon runs at `localhost:6767`
-- Expo app at `localhost:8081`
-- State lives in `$PASEO_HOME`
-
-In worktrees or when running `npm run dev`, ports and home directories may differ. Never assume the defaults.
-
-Use `npm run cli` to run the local CLI (instead of the globally linked `paseo` which points to the main checkout). Always run `npm run cli -- --help` or load the `/paseo` skill before using it - do not guess commands.
-
-Use `--host <host:port>` to point the CLI at a different daemon (e.g., `--host localhost:7777`).
-
-### Quick reference CLI commands
-
-```bash
-npm run cli -- ls -a -g              # List all agents globally
-npm run cli -- ls -a -g --json       # Same, as JSON
-npm run cli -- inspect <id>          # Show detailed agent info
-npm run cli -- logs <id>             # View agent timeline
-npm run cli -- daemon status         # Check daemon status
-```
-
-### Agent state
-
-Agent data is stored at:
-```
-$PASEO_HOME/agents/{cwd-with-dashes}/{agent-id}.json
-```
-
-To find an agent by ID:
-```bash
-find $PASEO_HOME/agents -name "{agent-id}.json"
-```
-
-To find an agent by title or other content:
-```bash
-rg -l "some title text" $PASEO_HOME/agents/
-rg -l "spiteful-toad" $PASEO_HOME/agents/
-```
-
-### Provider session files
-
-Get the session ID from the agent JSON file (`persistence.sessionId`), then:
-
-**Claude sessions:**
-```
-~/.claude/projects/{cwd-with-dashes}/{session-id}.jsonl
-```
-
-**Codex sessions:**
-```
-~/.codex/sessions/{YYYY}/{MM}/{DD}/rollout-{timestamp}-{session-id}.jsonl
-```
-
-## Android
-
-Take screenshots like this: `adb exec-out screencap -p > screenshot.png`
-
-### Android variants (vanilla Expo)
-
-Use `APP_VARIANT` in `packages/app/app.config.js` to control app name + package ID (no custom Gradle flavor plugin):
-
-- `production` -> app name `Paseo`, package `sh.paseo`
-- `development` -> app name `Paseo Debug`, package `sh.paseo.debug`
-
-EAS profiles live in `packages/app/eas.json` as `development`, `production`, and `production-apk`.
-
-`development` uses Android `debug`.
-
-### Local build + install (Android device)
-
-From `packages/app`:
-
-```bash
-# development (debug)
-APP_VARIANT=development npx expo prebuild --platform android --clean --non-interactive
-APP_VARIANT=development npx expo run:android --variant=debug
-
-# production (release)
-APP_VARIANT=production npx expo prebuild --platform android --clean --non-interactive
-APP_VARIANT=production npx expo run:android --variant=release
-```
-
-From repo root:
-
-```bash
-npm run android:development
-npm run android:production
-```
-
-`npm run android:prod` and `npm run android:release` are aliases for `npm run android:production`.
-
-### Cloud build + submit (EAS Workflows)
-
-Tag pushes like `v0.1.0` trigger `packages/app/.eas/workflows/release-mobile.yml` on Expo servers.
-Tag pushes like `v0.1.0` also trigger `.github/workflows/android-apk-release.yml` on GitHub Actions to publish an APK asset on the matching GitHub Release.
-
-That workflow does:
-- Build iOS with the `production` profile
-- Build Android with the `production` profile
-- Submit each build with the `production` submit profile
-
-Useful commands:
-
-```bash
-# List recent mobile workflow runs
-cd packages/app && npx eas workflow:runs --workflow release-mobile.yml --limit 10
-
-# Inspect one run (jobs, status, outputs)
-cd packages/app && npx eas workflow:view <run-id>
-
-# Stream logs for all steps in one failed job
-cd packages/app && npx eas workflow:logs <job-id> --non-interactive --all-steps
-```
-
-## Testing with Playwright MCP
-
-**CRITICAL:** When asked to test the app, you MUST use the Playwright MCP connecting to Metro at `http://localhost:8081`.
-
-Use the Playwright MCP to test the app in Metro web. Navigate to `http://localhost:8081` to interact with the app UI.
-
-**Important:** 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 navigation breaks the state.
-
-## Expo troubleshooting
-
-Run `npx expo-doctor` to diagnose version mismatches and native module issues.
-
-## Release playbook
-
-Use the scripted release flow from repo root. Avoid manual version bumps, manual tags, or ad hoc publish commands unless debugging.
-
-```bash
-# Recommended: full patch release (bump, check, publish, push branch+tag)
-npm run release:patch
-
-# Manual, step-by-step fallback:
-npm run version:all:patch  # npm version across all workspaces (creates commit + local tag)
-npm run release:check
-npm run release:publish
-npm run release:push       # pushes HEAD and current version tag (triggers desktop + Android APK + EAS mobile workflows)
-```
-
-Notes:
-- `version:all:*` bumps the root package version and runs the root `version` lifecycle script to sync workspace versions and internal `@getpaseo/*` dependency versions before the release commit/tag is created.
-- `release:prepare` refreshes workspace `node_modules` links to prevent stale local package types during release checks.
-- If `release:publish` fails after a successful publish of one workspace, re-run `npm run release:publish`; npm will skip already-published versions and continue where possible.
-- If a user asks to "release paseo" (without specifying major/minor), treat it as a patch release and run `npm run release:patch`.
-- All workspaces share one version by design. Keep versions synchronized and release together.
-- The website Mac download CTA URL is derived from `packages/website/package.json` version at build time, so no manual update is required after release.
-
-Release completion checklist:
-- `npm run release:patch` completes successfully.
-- GitHub `Desktop Release` workflow for the new `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 (Expo queues can take longer on the free plan).
-
-## Orchestrator Mode
-
-- **When agent control tool calls fail**, make sure you list agents before trying to launch another one. It could just be a wait timeout.
-- **Always prefix agent titles** so we can tell which ones are running under you (e.g., "🎭 Feature Implementation", "🎭 Design Discussion").
-- **Launch agents in the most permissive mode**: Use full access or bypass permissions mode.
-- **Set cwd to the repository root** - The agent's working directory should usually be the repo root
-
-**CRITICAL: ALWAYS RUN TYPECHECK AFTER EVERY CHANGE.**
-
-## Agent Authentication
-
-All agent providers (Claude, Codex, OpenCode) handle their own authentication outside of environment variables. They are authenticated without providing any extra configuration—Paseo does not manage API keys or tokens for agents.
-
-**Do not add auth checks to tests.** If auth fails for whatever reason, let the user know instead of patching the code or adding conditional skips.
-
-## NEVER DO THESE THINGS
-
-- **NEVER restart the main Paseo daemon on port 6767 without permission** - This is the production daemon that launches and manages agents. If you are reading this, you are probably running as an agent under it. Restarting it will kill your own process and all other running agents. The daemon is managed by the user in Tmux.
-- **NEVER assume a timeout means the service needs restarting** - Timeouts can be transient network issues, not service failures
-- **NEVER add authentication checks to tests** - Agent providers handle their own auth. If tests fail due to auth issues, report it rather than adding conditional skips or env var checks
+Find the complete daemon logs and traces in the $PASEO_HOME/daemon.log

LICENSE

@@ -1,21 +1,671 @@
-MIT License
+Copyright (c) 2025-present Mohamed Boudra
 
-Copyright (c) 2025 Mohamed Boudra
+Portions of this software are licensed as follows:
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+* All third party components incorporated into the Paseo Software are
+  licensed under the original license provided by the owner of the
+  applicable component.
+* All content outside of the above mentioned restrictions is available
+  under the "AGPLv3" license as defined below.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

README.md

@@ -4,39 +4,107 @@
 
 <h1 align="center">Paseo</h1>
 
-<p align="center">Manage coding agents from your phone and desktop.</p>
+<p align="center">One interface for all your Claude Code, Codex and OpenCode agents.</p>
 
 <p align="center">
-  <img src="https://paseo.sh/paseo-mockup.png" alt="Paseo app screenshot" width="100%">
+  <img src="https://paseo.sh/hero-mockup.png" alt="Paseo app screenshot" width="100%">
+</p>
+
+<p align="center">
+  <img src="https://paseo.sh/mobile-mockup.png" alt="Paseo mobile app" width="100%">
 </p>
 
 ---
 
-> [!WARNING]
-> **Early development** — Features may break or change without notice. Use at your own risk.
+Run agents in parallel on your own machines. Ship from your phone or your desk.
 
-Paseo is a self-hosted daemon for Claude Code, Codex, and OpenCode. Agents run on your machine with your full dev environment. Connect from phone, desktop, or web.
+- **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.
+- **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.
 
 ## Getting Started
 
+Paseo runs a local server called the daemon that manages your coding agents. Clients like the desktop app, mobile app, web app, and CLI connect to it.
+
+### Prerequisites
+
+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)
+- [OpenCode](https://github.com/anomalyco/opencode)
+
+### Desktop app (recommended)
+
+Download it from [paseo.sh/download](https://paseo.sh/download) or the [GitHub releases page](https://github.com/getpaseo/paseo/releases). Open the app and the daemon starts automatically. Nothing else to install.
+
+To connect from your phone, scan the QR code shown in Settings.
+
+### CLI / headless
+
+Install the CLI and start Paseo:
+
 ```bash
 npm install -g @getpaseo/cli
 paseo
 ```
 
-Then open the app and connect to your daemon.
+This shows a QR code in the terminal. Connect from any client. This path is useful for servers and remote machines.
 
 For full setup and configuration, see:
 - [Docs](https://paseo.sh/docs)
 - [Configuration reference](https://paseo.sh/docs/configuration)
 
+## CLI
+
+Everything you can do in the app, you can do from the terminal.
+
+```bash
+paseo run --provider claude/opus-4.6 "implement user authentication"
+paseo run --provider codex/gpt-5.4 --worktree feature-x "implement feature X"
+
+paseo ls                           # list running agents
+paseo attach abc123                # stream live output
+paseo send abc123 "also add tests" # follow-up task
+
+# run on a remote daemon
+paseo --host workstation.local:6767 run "run the full test suite"
+```
+
+See the [full CLI reference](https://paseo.sh/docs/cli) for more.
+
+## Orchestration skills (Unstable)
+
+Experimental skills that teach agents how to use the Paseo CLI to orchestrate other agents. I am updating these very frequently as I learn new things, expect changes without notice, might be coupled to my own setup, use at your own risk.
+
+```bash
+npx skills add getpaseo/paseo
+```
+
+Then use them in any agent conversation:
+
+```bash
+# Use handoff when you discuss something with an agent but want another one to implement.
+# I use this to plan with Claude and then handoff to Codex to implement.
+/paseo-handoff hand off the authentication fix to codex 5.4 in a worktree
+
+# Use loops when you have clear acceptance criteria (aka Ralph loops).
+/paseo-loop loop a codex agent to fix the backend tests, use sonnet to verify, max 10 iterations
+
+# Orchestrator teaches the agent how to create teams and manage them via a chat room.
+# Very opinionated and expects both Codex and Claude to work.
+/paseo-orchestrator spin up a team to implement the database refactor, use chat to coordinate. use claude to plan and codex to implement and review
+```
+
 ## Development
 
 Quick monorepo package map:
 - `packages/server`: Paseo daemon (agent process orchestration, WebSocket API, MCP server)
 - `packages/app`: Expo client (iOS, Android, web)
 - `packages/cli`: `paseo` CLI for daemon and agent workflows
-- `packages/desktop`: Tauri desktop app
+- `packages/desktop`: Electron desktop app
 - `packages/relay`: Relay package for remote connectivity
 - `packages/website`: Marketing site and documentation (`paseo.sh`)
 
@@ -49,12 +117,16 @@ npm run dev
 # run individual surfaces
 npm run dev:server
 npm run dev:app
+npm run dev:desktop
 npm run dev:website
 
+# build the daemon
+npm run build:daemon
+
 # repo-wide checks
 npm run typecheck
 ```
 
 ## License
 
-MIT
+AGPL-3.0

SECURITY.md

@@ -51,4 +51,4 @@ Paseo wraps agent CLIs (Claude Code, Codex, OpenCode) but does not manage their
 
 ## Reporting vulnerabilities
 
-If you discover a security vulnerability, please report it privately by emailing mo@faro.so. Do not open a public issue.
+If you discover a security vulnerability, please report it privately by emailing hello@moboudra.com. Do not open a public issue.

app.json

@@ -0,0 +1,5 @@
+{
+  "android": {
+    "package": "com.moboudra.paseo"
+  }
+}

biome.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "includes": ["**", "!*.lock"]
+  },
+  "formatter": {
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "trailingCommas": "all",
+      "semicolons": "always"
+    }
+  },
+  "css": {
+    "parser": {
+      "cssModules": true,
+      "tailwindDirectives": true
+    }
+  },
+  "linter": {
+    "enabled": false
+  }
+}

cli-client-id

@@ -0,0 +1 @@
+cid_518a41c4c44340aea1120d2b760fc6c6

docs/ANDROID.md

@@ -0,0 +1,69 @@
+# Android
+
+## App variants
+
+Controlled by `APP_VARIANT` in `packages/app/app.config.js` (vanilla Expo, no custom Gradle plugin):
+
+| Variant | App name | Package ID |
+|---|---|---|
+| `production` | Paseo | `sh.paseo` |
+| `development` | Paseo Debug | `sh.paseo.debug` |
+
+EAS profiles: `development`, `production`, and `production-apk` in `packages/app/eas.json`.
+
+`development` uses Android `debug`.
+
+## Local build + install
+
+From repo root:
+
+```bash
+npm run android:development    # Debug build
+npm run android:production     # Release build
+npm run android:clear          # Remove generated Android project
+```
+
+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
+
+# Release
+APP_VARIANT=production npx expo prebuild --platform android --non-interactive
+APP_VARIANT=production npx expo run:android --variant=release
+
+# Clear generated Android project
+rm -rf android
+```
+
+## Screenshots
+
+```bash
+adb exec-out screencap -p > screenshot.png
+```
+
+## Cloud build + submit (EAS)
+
+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)
+
+Release candidate tags like `v0.1.1-rc.1` only trigger the GitHub APK workflow. They publish a GitHub prerelease APK for testing and do not submit to the stores.
+
+### Useful commands
+
+```bash
+cd packages/app
+
+# List recent workflow runs
+npx eas workflow:runs --workflow release-mobile.yml --limit 10
+
+# 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
+```

docs/ARCHITECTURE.md

@@ -0,0 +1,192 @@
+# Architecture
+
+Paseo is a client-server system for monitoring and controlling local AI coding agents. The daemon runs on your machine, manages agent processes, and streams their output in real time over WebSocket. Clients (mobile app, CLI, desktop app) connect to the daemon to observe and interact with agents.
+
+Your code never leaves your machine. Paseo is local-first.
+
+## System overview
+
+```
+┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+│  Mobile App  │    │     CLI     │    │ Desktop App │
+│   (Expo)     │    │ (Commander) │    │ (Electron)  │
+└──────┬───────┘    └──────┬──────┘    └──────┬──────┘
+       │                   │                  │
+       │    WebSocket      │    WebSocket     │    Managed subprocess
+       │    (direct or     │    (direct)      │    + WebSocket
+       │     via relay)    │                  │
+       └───────────┬───────┴──────────────────┘
+                   │
+            ┌──────▼──────┐
+            │   Daemon    │
+            │  (Node.js)  │
+            └──────┬──────┘
+                   │
+      ┌────────────┼────────────┐
+      │            │            │
+┌─────▼─────┐ ┌───▼────┐ ┌────▼─────┐
+│  Claude   │ │ Codex  │ │ OpenCode │
+│  Agent    │ │ Agent  │ │  Agent   │
+│  SDK      │ │ Server │ │          │
+└───────────┘ └────────┘ └──────────┘
+```
+
+## Components at a glance
+
+- **Daemon:** Local server that spawns and manages agent processes and exposes the WebSocket API.
+- **App:** Cross-platform Expo client for iOS, Android, web, and the shared UI used by desktop.
+- **CLI:** Terminal interface for agent workflows that can also start and manage the daemon.
+- **Desktop app:** Electron wrapper around the web app that bundles and auto-manages its own daemon.
+- **Relay:** Optional encrypted bridge for remote access without opening ports directly.
+
+## Packages
+
+### `packages/server` — The daemon
+
+The heart of Paseo. A Node.js process that:
+
+- Listens for WebSocket connections from clients
+- Manages agent lifecycle (create, run, stop, resume, archive)
+- Streams agent output in real time via a timeline model
+- Exposes an MCP server for agent-to-agent control
+- Optionally connects outbound to a relay for remote access
+
+**Key modules:**
+
+| Module | Responsibility |
+|---|---|
+| `bootstrap.ts` | Daemon initialization: HTTP server, WS server, agent manager, storage, relay |
+| `websocket-server.ts` | WebSocket connection management, hello/welcome handshake, binary multiplexing |
+| `session.ts` | Per-client session state, timeline subscriptions, terminal operations |
+| `agent/agent-manager.ts` | Agent lifecycle state machine, timeline tracking, subscriber management |
+| `agent/agent-storage.ts` | File-backed JSON persistence at `$PASEO_HOME/agents/` |
+| `agent/mcp-server.ts` | MCP server for sub-agent creation, permissions, timeouts |
+| `providers/` | Provider adapters: Claude (Agent SDK), Codex (AppServer), OpenCode |
+| `relay-transport.ts` | Outbound relay connection with E2E encryption |
+| `client/daemon-client.ts` | Client library for connecting to the daemon (used by CLI and app) |
+
+### `packages/app` — Mobile + web client (Expo)
+
+Cross-platform React Native app that connects to one or more daemons.
+
+- Expo Router navigation (`/h/[serverId]/agents`, etc.)
+- `DaemonRegistryContext` manages saved daemon connections
+- `SessionContext` wraps the daemon client for the active session
+- `Stream` model handles timeline with compaction, gap detection, sequence-based deduplication
+- Voice features: dictation (STT) and voice agent (realtime)
+
+### `packages/cli` — Command-line client
+
+Commander.js CLI with Docker-style commands:
+
+- `paseo agent ls/run/stop/logs/inspect/wait/send/attach`
+- `paseo daemon start/stop/restart/status/pair`
+- `paseo permit allow/deny/ls`
+- `paseo provider ls/models`
+- `paseo worktree ls/archive`
+
+Communicates with the daemon via the same WebSocket protocol as the app.
+
+### `packages/relay` — E2E encrypted relay
+
+Enables remote access when the daemon is behind a firewall.
+
+- ECDH key exchange + AES-256-GCM encryption
+- 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
+
+See [SECURITY.md](../SECURITY.md) for the full threat model.
+
+### `packages/desktop` — Desktop app (Electron)
+
+Electron wrapper for macOS, Linux, and Windows.
+
+- Can spawn the daemon as a managed subprocess
+- Native file access for workspace integration
+- Same WebSocket client as mobile app
+
+### `packages/website` — Marketing site
+
+TanStack Router + Cloudflare Workers. Serves paseo.sh.
+
+## WebSocket protocol
+
+All clients speak the same binary-multiplexed WebSocket protocol.
+
+**Handshake:**
+
+```
+Client → Server:  WSHelloMessage { id, clientId, version, timestamp }
+Server → Client:  WSWelcomeMessage { clientId, daemonVersion, sessionId, capabilities }
+```
+
+**Message types:**
+
+- `agent_update` — Agent state changed (status, title, labels)
+- `agent_stream` — New timeline event from a running agent
+- `workspace_update` — Workspace state changed
+- `agent_permission_request` — Agent needs user approval for a tool call
+- Command-response pairs for fetch, list, create, etc.
+
+**Binary multiplexing:**
+
+Terminal I/O and agent streaming share the same connection via `BinaryMuxFrame`:
+- Channel 0: control messages
+- Channel 1: terminal data
+- 1-byte channel ID + 1-byte flags + variable payload
+
+## Agent lifecycle
+
+```
+initializing → idle → running → idle (or error → closed)
+                 ↑        │
+                 └────────┘  (agent completes a turn, awaits next prompt)
+```
+
+- **AgentManager** tracks up to 200 timeline items per agent
+- Timeline is append-only with epochs (each run starts a new epoch)
+- Events stream to all subscribed clients in real time
+- Agent state persists to `$PASEO_HOME/agents/{cwd-with-dashes}/{agent-id}.json`
+
+## Agent providers
+
+Each provider implements a common `AgentClient` interface:
+
+| Provider | Wraps | Session format |
+|---|---|---|
+| Claude | Anthropic Agent SDK | `~/.claude/projects/{cwd}/{session-id}.jsonl` |
+| Codex | CodexAppServer | `~/.codex/sessions/{date}/rollout-{ts}-{id}.jsonl` |
+| OpenCode | OpenCode CLI | Provider-managed |
+
+All providers:
+- Handle their own authentication (Paseo does not manage API keys)
+- Support session resume via persistence handles
+- Map tool calls to a normalized `ToolCallDetail` type
+- Expose provider-specific modes (plan, default, full-access)
+
+## Data flow: running an agent
+
+1. Client sends `CreateAgentRequestMessage` with config (prompt, cwd, provider, model, mode)
+2. Session routes to `AgentManager.create()`
+3. AgentManager creates a `ManagedAgent`, initializes provider session
+4. Provider runs the agent → emits `AgentStreamEvent` items
+5. Events append to the agent timeline, broadcast to all subscribed clients
+6. Tool calls are normalized to `ToolCallDetail` (shell, read, edit, write, search, etc.)
+7. Permission requests flow: agent → server → client → user decision → server → agent
+
+## Storage
+
+```
+$PASEO_HOME/
+├── agents/{cwd-with-dashes}/{agent-id}.json   # Agent state + config
+├── projects/projects.json                      # Project registry
+├── projects/workspaces.json                    # Workspace registry
+└── daemon.log                                  # Daemon trace logs
+```
+
+## Deployment models
+
+1. **Local daemon** (default): `paseo daemon start` on `127.0.0.1:6767`
+2. **Managed desktop**: Electron app spawns daemon as subprocess
+3. **Remote + relay**: Daemon behind firewall, relay bridges with E2E encryption

docs/CODING_STANDARDS.md

@@ -0,0 +1,174 @@
+# Coding Standards
+
+These standards apply to all code changes: features, bug fixes, refactors, and performance work.
+
+## Core principles
+
+- **Zero complexity budget** — justify every abstraction with specific benefits
+- **Fully typed TypeScript** — no `any`, no untyped boundaries
+- **YAGNI** — build features and abstractions only when needed
+- **Functional and declarative** over object-oriented
+- **`interface`** over `type` when possible
+- **`function` declarations** over arrow function assignments
+- **Single-purpose functions** — one function, one job
+- **Design for edge cases through types** rather than explicit handling
+- **Don't catch errors** unless there's a strong reason to
+- **No index.ts barrel files** that only re-export — they create unnecessary indirection
+- **No "while I'm at it" improvements** — stay focused on the task
+
+## Type hygiene
+
+### Infer from schemas
+
+Never hand-write a TypeScript type that can be inferred from a Zod schema.
+
+```typescript
+// Bad: duplicate type that can drift
+const schema = z.object({ procedure: z.string(), args: z.record(z.unknown()) });
+type RPCArgs = { procedure: string; args: Record<string, unknown> };
+
+// Good: infer from schema
+type RPCArgs = z.infer<typeof schema>;
+```
+
+### Named types over inline
+
+No complex inline types in public function signatures.
+
+```typescript
+// Bad
+function enqueueJob(input: { userId: string; priority: "low" | "normal" | "high" }) {}
+
+// Good
+interface EnqueueJobInput { userId: string; priority: "low" | "normal" | "high" }
+function enqueueJob(input: EnqueueJobInput) {}
+```
+
+### Object parameters
+
+If a function needs more than one argument, use a single object parameter.
+
+```typescript
+// Bad: positional args
+function createToolCall(provider: string, toolName: string, payload: unknown) {}
+
+// Good: object param
+interface CreateToolCallInput { provider: string; toolName: string; payload: unknown }
+function createToolCall(input: CreateToolCallInput) {}
+```
+
+### One canonical type per concept
+
+Don't redefine the same concept in different layer-specific shapes (`RpcX`, `DbX`, `UiX`). Keep one canonical type and add explicit layer wrappers that reference it.
+
+```typescript
+// Bad: duplicated fields across layers
+type RpcToolCall = { toolName: string; args: Record<string, unknown>; requestId: string };
+type DbToolCall = { toolName: string; args: Record<string, unknown>; id: string; createdAt: Date };
+
+// Good: canonical type + wrappers
+type ToolCall = { toolName: string; args: Record<string, unknown> };
+type ToolCallRequest = { requestId: string; toolCall: ToolCall };
+type ToolCallRecord = { id: string; createdAt: Date; toolCall: ToolCall };
+```
+
+## Make impossible states impossible
+
+Use discriminated unions instead of bags of booleans and optionals.
+
+```typescript
+// Bad
+interface FetchState { isLoading: boolean; error?: Error; data?: Data }
+
+// Good
+type FetchState =
+  | { status: "idle" }
+  | { status: "loading" }
+  | { status: "error"; error: Error }
+  | { status: "success"; data: Data };
+```
+
+## Optionality is a design decision
+
+Don't mark fields optional to avoid migrations. Decide deliberately:
+
+1. Is optionality actually needed?
+2. If there are distinct valid states → discriminated union
+3. If value can be intentionally empty → explicit `null`
+4. Keep optionality at real boundaries (external input), then resolve it
+
+## Validate at boundaries, trust internally
+
+Parse external data once at the boundary with schema validation. Then use typed values everywhere else.
+
+```typescript
+// Bad: optional chaining because shape is unclear
+const value = response?.data?.items?.[0]?.name;
+
+// Good: validate at boundary, trust the types
+const parsed = responseSchema.parse(rawResponse);
+const value = parsed.data.items[0].name;
+```
+
+## Error handling
+
+- **Fail explicitly** — if caller requests X and X is unavailable, throw rather than silently returning Y
+- **Use typed domain errors** — not plain `Error`. Carry structured metadata for handling, logging, and user messaging
+- **Preserve error semantics** — don't collapse meaningful typed errors into generic `Error`
+
+```typescript
+class TimeoutError extends Error {
+  constructor(
+    public readonly operation: string,
+    public readonly waitedMs: number,
+  ) {
+    super(`${operation} timed out after ${waitedMs}ms`);
+    this.name = "TimeoutError";
+  }
+}
+```
+
+## Keep logic density low
+
+Avoid packing branching, lookup, and transformation into single dense expressions.
+
+```typescript
+// Bad: nested ternaries + inline lookups
+const billing = shouldUseLegacy(account)
+  ? getLegacy(account)
+  : buildBilling(account, rates.find((r) => r.region === account.region));
+
+// Good: named steps, then assemble
+const rate = rates.find((r) => r.region === account.region);
+if (!rate) throw new MissingRateError(account.region);
+const billing = shouldUseLegacy(account) ? getLegacy(account) : buildBilling(account, rate);
+```
+
+## Centralize policy
+
+When the same discriminator (`plan`, `provider`, `kind`, `status`) is checked across multiple files, centralize it into a policy model. A new case should require editing one place, not many.
+
+## React: keep components dumb
+
+- Components render state and dispatch events — they don't compute transitions
+- If a component has more than two interacting `useState` calls, extract a state machine or reducer
+- `useRef` for mutable coordination state (flags, timers) is a smell — model states explicitly
+- Never mirror a source of truth into local state; derive from it
+- Test state logic as pure functions without rendering
+
+## File organization
+
+- Organize by domain first (`providers/claude/`), not by technical type (`tool-parsers/`)
+- Name files after the main export (`create-toolcall.ts`)
+- Use `index.ts` as an entrypoint, not a dumping ground
+- Collocate tests with implementation (`thing.ts` + `thing.test.ts`)
+
+## Refactoring contract
+
+Refactoring is structure work, not feature work.
+
+- Preserve behavior by default, especially user-facing behavior
+- Do not remove features to simplify code without explicit approval
+- Have a verification strategy before you start
+- Fully migrate callers and remove old paths in the same refactor
+- No fallback behavior by default — prefer explicit error over silent degradation

docs/DESIGN.md

@@ -0,0 +1,73 @@
+# Designing Features
+
+How to think through a feature before writing code.
+
+## Start from the user
+
+Even for backend work, start from the user's perspective:
+
+- What problem does this solve?
+- What triggers it? User action, schedule, event?
+- What does success look like from the user's perspective?
+- What data does it need? Where does that data come from?
+
+## Map existing code
+
+Before designing anything new, understand what exists:
+
+- Where does similar functionality live?
+- What patterns does the codebase already use?
+- What layers exist? (See [ARCHITECTURE.md](./ARCHITECTURE.md))
+- What types and data shapes are already defined?
+
+New features rarely mean only new code. Usually they require modifying existing interfaces, extending existing types, or refactoring to accommodate the new functionality. Identify what needs to change, not just what needs to be added.
+
+## Define verification before implementation
+
+Before designing the solution, define how you'll know it works:
+
+- What tests will prove this feature is correct?
+- At what layer? Unit, integration, E2E?
+- What's the simplest way to verify the core behavior?
+
+If you can't define verification, you don't understand the feature well enough yet.
+
+## Design the shape
+
+### Data
+
+- What types are needed?
+- Use discriminated unions — make impossible states impossible
+- One canonical type per concept (see [CODING_STANDARDS.md](./CODING_STANDARDS.md))
+
+### Layers
+
+- What belongs in each layer?
+- Where are the boundaries?
+- What does each layer expose to the layer above?
+
+### Interactions
+
+- How does data flow through the system?
+- What triggers what?
+- Where do side effects happen?
+
+### Refactoring
+
+- What existing code needs to change?
+- Is existing code testable enough? If not, that's part of the plan.
+
+## Create a concrete plan
+
+Once the design is clear:
+
+1. **Acceptance criteria** — specific, verifiable outcomes (not "should work well" but "returns X when given Y")
+2. **Ordered steps** — what to build first (usually: types, then lowest layer, then up)
+3. **What to refactor** before adding new code
+4. **How to verify** each step
+
+## Principles
+
+- **Fit, don't force** — new code should fit existing patterns, or refactor first
+- **Simple** — the best design is the simplest one that works
+- **Verify early** — define how to test before designing the implementation

docs/DEVELOPMENT.md

@@ -0,0 +1,130 @@
+# Development
+
+## Prerequisites
+
+- Node.js (see `.tool-versions` for exact version)
+- npm workspaces (comes with Node)
+
+## Running the dev server
+
+```bash
+npm run dev
+```
+
+The dev script automatically picks an available port. Both the server and Expo app run in a Tmux session — see `CLAUDE.local.md` for system-specific session details.
+
+### Running alongside the main checkout
+
+Set `PASEO_HOME` to isolate state when running a second instance (e.g., in a worktree):
+
+```bash
+PASEO_HOME=~/.paseo-blue npm run dev
+```
+
+- `PASEO_HOME` — path for runtime state (agents, sockets, etc.). Defaults to `~/.paseo`.
+
+### Default ports
+
+In the main checkout:
+- Daemon: `localhost:6767`
+- Expo app: `localhost:8081`
+
+In worktrees or with `npm run dev`, ports may differ. Never assume defaults.
+
+### Daemon logs
+
+Check `$PASEO_HOME/daemon.log` for trace-level logs.
+
+## Build sync gotchas
+
+### Relay → Daemon
+
+When changing `packages/relay/src/*`, rebuild before running the daemon:
+
+```bash
+npm run build --workspace=@getpaseo/relay
+```
+
+The Node daemon imports `@getpaseo/relay` from `packages/relay/dist/*`, not `src/*`.
+
+### Server → CLI
+
+When changing `packages/server/src/client/*` (especially `daemon-client.ts`) or shared WS protocol types, rebuild before running CLI commands:
+
+```bash
+npm run build --workspace=@getpaseo/server
+```
+
+The CLI imports `@getpaseo/server` via package exports resolving to `dist/*`. Stale `dist` means the CLI speaks an old protocol and fails with handshake warnings or timeouts.
+
+## CLI reference
+
+Use `npm run cli` to run the local CLI (instead of the globally installed `paseo` which points to the main checkout).
+
+```bash
+npm run cli -- ls -a -g              # List all agents globally
+npm run cli -- ls -a -g --json       # Same, as JSON
+npm run cli -- inspect <id>          # Show detailed agent info
+npm run cli -- logs <id>             # View agent timeline
+npm run cli -- daemon status         # Check daemon status
+```
+
+Use `--host <host:port>` to point the CLI at a different daemon:
+
+```bash
+npm run cli -- --host localhost:7777 ls -a
+```
+
+## Agent state
+
+Agent data lives at:
+
+```
+$PASEO_HOME/agents/{cwd-with-dashes}/{agent-id}.json
+```
+
+Find an agent by ID:
+```bash
+find $PASEO_HOME/agents -name "{agent-id}.json"
+```
+
+Find by content:
+```bash
+rg -l "some title text" $PASEO_HOME/agents/
+```
+
+## Provider session files
+
+Get the session ID from the agent JSON (`persistence.sessionId`), then:
+
+**Claude:**
+```
+~/.claude/projects/{cwd-with-dashes}/{session-id}.jsonl
+```
+
+**Codex:**
+```
+~/.codex/sessions/{YYYY}/{MM}/{DD}/rollout-{timestamp}-{session-id}.jsonl
+```
+
+## Testing with Playwright MCP
+
+Use Playwright MCP connecting to Metro at `http://localhost:8081` for UI testing.
+
+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.
+
+## Expo troubleshooting
+
+```bash
+npx expo-doctor
+```
+
+Diagnoses version mismatches and native module issues.
+
+## Typecheck
+
+Always run typecheck after changes:
+
+```bash
+npm run typecheck
+```

docs/FILE_ICONS.md

@@ -0,0 +1,109 @@
+# File Icons
+
+The file explorer uses colored SVG icons from [`material-icon-theme`](https://github.com/material-extensions/vscode-material-icon-theme) (installed as a dev dependency in `packages/app`).
+
+Icons are inlined as SVG strings in:
+
+```
+packages/app/src/components/material-file-icons.ts
+```
+
+This file is auto-generated. Do not edit it by hand.
+
+## How it works
+
+- `SVG_ICONS` maps icon names (e.g. `"typescript"`) to raw SVG strings
+- `EXTENSION_TO_ICON` maps file extensions (e.g. `"ts"`) to icon names
+- `getFileIconSvg(fileName)` returns the SVG string for a given filename, falling back to a generic file icon
+
+## Adding a new icon
+
+1. Find the icon name in the material-icon-theme manifest:
+
+```bash
+node -e "
+const m = require('./node_modules/material-icon-theme/dist/material-icons.json');
+console.log('fileExtensions:', m.fileExtensions['YOUR_EXT']);
+console.log('languageIds:', m.languageIds['YOUR_LANG']);
+"
+```
+
+2. Verify the SVG exists:
+
+```bash
+cat node_modules/material-icon-theme/icons/ICON_NAME.svg
+```
+
+3. Add two things to `material-file-icons.ts`:
+
+   - The SVG string in `SVG_ICONS`:
+     ```ts
+     "icon_name": `<svg ...>...</svg>`,
+     ```
+
+   - The extension mapping in `EXTENSION_TO_ICON`:
+     ```ts
+     "ext": "icon_name",
+     ```
+
+4. Run `npm run typecheck` to verify.
+
+## Currently included icons
+
+53 unique icons covering these extensions:
+
+| Extension(s) | Icon |
+|---|---|
+| `ts` | typescript |
+| `tsx` | react_ts |
+| `js` | javascript |
+| `jsx` | react |
+| `py` | python |
+| `go` | go |
+| `rs` | rust |
+| `rb` | ruby |
+| `java` | java |
+| `kt` | kotlin |
+| `c` | c |
+| `cpp` | cpp |
+| `h` | h |
+| `hpp` | hpp |
+| `cs` | csharp |
+| `swift` | swift |
+| `dart` | dart |
+| `ex`, `exs` | elixir |
+| `erl` | erlang |
+| `hs` | haskell |
+| `clj` | clojure |
+| `scala` | scala |
+| `ml` | ocaml |
+| `r` | r |
+| `lua` | lua |
+| `zig` | zig |
+| `nix` | nix |
+| `php` | php |
+| `html` | html |
+| `css` | css |
+| `scss` | sass |
+| `less` | less |
+| `json` | json |
+| `yml`, `yaml` | yaml |
+| `xml` | xml |
+| `toml` | toml |
+| `md`, `markdown` | markdown |
+| `sql` | database |
+| `graphql`, `gql` | graphql |
+| `sh`, `bash` | console |
+| `tf` | terraform |
+| `hcl` | hcl |
+| `vue` | vue |
+| `svelte` | svelte |
+| `astro` | astro |
+| `wasm` | webassembly |
+| `svg` | svg |
+| `png`, `jpg`, `jpeg`, `gif`, `webp`, `ico` | image |
+| `txt` | document |
+| `conf`, `cfg`, `ini` | settings |
+| `lock` | lock |
+| `groovy` | groovy |
+| `gradle` | gradle |

docs/PRODUCT.md

@@ -0,0 +1,74 @@
+# Product
+
+What Paseo is, who it's for, and where it's going.
+
+## What is Paseo
+
+Paseo is a next-generation development environment built around agents. One interface to run, monitor, and interact with coding agents across desktop, mobile, terminal, and web.
+
+The development workflow is shifting from manually editing files to orchestrating agents that do the editing. Paseo is built for that workflow.
+
+## Core philosophy
+
+Freedom and flexibility. Every design decision follows from this:
+
+- **Multi-provider** — Use any coding agent harness. Pick the right model for each job, switch freely as the landscape shifts. No vendor-lock in.
+- **Cross-device** — Desktop, mobile, web, CLI. Start work at your desk, check progress from your phone, script from the terminal.
+- **Self-hosted** — The daemon runs on your machine. Your code, your keys, your environment. No inference markup, no cloud dependency.
+- **Respectful** - No telemetry, no forced cloud, no forced accounts
+- **Open source** — AGPL-3.0. Users can inspect, fork, and contribute.
+- **BYOK** — Bring your own keys. Use your subsidized plans and first-party provider pricing. Paseo adds zero cost on top.
+
+## How it works
+
+### Projects and workspaces
+
+Projects are grouped in the sidebar, detected automatically from your filesystem and tagged by git remote when available.
+
+Each project opens as a workspace. For git projects, the default workspace is the main checkout. Users can create additional workspaces, which are isolated copies (git worktrees) where agents work without affecting main.
+
+### Inside a workspace
+
+A workspace is a flexible canvas:
+- Launch multiple agents side by side in split panes
+- Open terminals alongside agents
+- Mix and match providers within the same workspace
+
+### The daemon
+
+Paseo is a client-server system. The daemon (Node.js) runs on your machine, manages agent processes, and streams output in real time over WebSocket. Clients connect to the daemon — locally or remotely.
+
+This architecture means:
+- The daemon can run on any machine: laptop, VM, remote server
+- Multiple clients can connect simultaneously
+- Agents keep running when you close the app
+
+## Target user
+
+Anyone who builds software:
+
+- Care about owning their tools and their data
+- Use multiple AI providers and want to switch freely
+- Run agents on real tasks across real projects
+- Want to work from multiple devices
+
+## What compounds over time
+
+- **Trust** — Showing up daily, shipping in public, being open source. Earned slowly, lost quickly.
+- **Community contributions** — Code, packaging, skills, agent configs. Contributors become advocates.
+- **Ecosystem** — Skills, integrations, shared configs. Community-built content that makes the platform more valuable.
+
+## Strategic bets
+
+1. **Models commoditize.** Value moves to the orchestration layer. The best model changes monthly — the workflow layer stays.
+2. **Multi-provider wins.** No single provider stays on top. Developers want the best model for each task.
+3. **The daemon as infrastructure.** Server/client architecture enables deployment anywhere.
+4. **Open source outlasts funding.** Open source communities are resilient. Contributors become advocates.
+
+## Current state (March 2026)
+
+- Desktop (Electron), mobile (iOS/Android), web, CLI
+- Providers: Claude Code (Agent SDK), Codex (app-server), OpenCode
+- Daily releases
+- Community contributions starting (packaging, bug fixes)
+- Key UX: split panes, keybinding customization, workspace model

docs/PROVIDERS.md

@@ -0,0 +1,359 @@
+# Adding a New Provider to Paseo
+
+This guide walks through adding a new agent provider end-to-end. There are two integration patterns, and this doc covers both.
+
+## Two Integration Patterns
+
+### ACP (Agent Client Protocol) -- recommended
+
+Extend `ACPAgentClient`. The base class handles process spawning, stdio transport, session lifecycle, streaming, permissions, and model discovery. You provide configuration (command, modes, capabilities) and optionally override `isAvailable()` for auth checks.
+
+Existing ACP providers: `claude-acp`, `copilot`.
+
+### Direct
+
+Implement the `AgentClient` and `AgentSession` interfaces yourself. This gives full control but requires you to handle process management, streaming, permissions, and session persistence from scratch.
+
+Existing direct providers: `claude`, `codex`, `opencode`.
+
+---
+
+## ACP Provider Checklist
+
+### 1. Create the provider class
+
+Create `packages/server/src/server/agent/providers/{name}-agent.ts`.
+
+Define capabilities, modes, and a thin subclass of `ACPAgentClient`:
+
+```ts
+import type { Logger } from "pino";
+import type { AgentCapabilityFlags, AgentMode } from "../agent-sdk-types.js";
+import type { ProviderRuntimeSettings } from "../provider-launch-config.js";
+import { ACPAgentClient } from "./acp-agent.js";
+
+const MY_PROVIDER_CAPABILITIES: AgentCapabilityFlags = {
+  supportsStreaming: true,
+  supportsSessionPersistence: true,
+  supportsDynamicModes: true,
+  supportsMcpServers: true,
+  supportsReasoningStream: true,
+  supportsToolInvocations: true,
+};
+
+const MY_PROVIDER_MODES: AgentMode[] = [
+  {
+    id: "default",
+    label: "Default",
+    description: "Standard agent mode",
+  },
+  // Add more modes as needed
+];
+
+type MyProviderClientOptions = {
+  logger: Logger;
+  runtimeSettings?: ProviderRuntimeSettings;
+};
+
+export class MyProviderACPAgentClient extends ACPAgentClient {
+  constructor(options: MyProviderClientOptions) {
+    super({
+      provider: "my-provider",        // Must match the ID used everywhere else
+      logger: options.logger,
+      runtimeSettings: options.runtimeSettings,
+      defaultCommand: ["my-agent-binary", "--acp"],  // CLI command to spawn
+      defaultModes: MY_PROVIDER_MODES,
+      capabilities: MY_PROVIDER_CAPABILITIES,
+    });
+  }
+
+  // Override isAvailable() if the provider needs specific auth/env vars
+  override async isAvailable(): Promise<boolean> {
+    if (!(await super.isAvailable())) {
+      return false;  // Binary not found
+    }
+    return Boolean(process.env["MY_PROVIDER_API_KEY"]);
+  }
+}
+```
+
+The `super.isAvailable()` call checks that the binary from `defaultCommand` is on `$PATH`. Override only to add credential checks on top.
+
+For reference, here is how Copilot does it -- no auth override needed because the CLI handles auth itself:
+
+```ts
+export class CopilotACPAgentClient extends ACPAgentClient {
+  constructor(options: CopilotACPAgentClientOptions) {
+    super({
+      provider: "copilot",
+      logger: options.logger,
+      runtimeSettings: options.runtimeSettings,
+      defaultCommand: ["copilot", "--acp"],
+      defaultModes: COPILOT_MODES,
+      capabilities: COPILOT_CAPABILITIES,
+    });
+  }
+
+  override async isAvailable(): Promise<boolean> {
+    return super.isAvailable();
+  }
+}
+```
+
+### 2. Add to the provider manifest
+
+In `packages/server/src/server/agent/provider-manifest.ts`, add mode definitions with UI metadata (icons, color tiers) and a provider definition entry.
+
+First, define the modes with visual metadata:
+
+```ts
+const MY_PROVIDER_MODES: AgentProviderModeDefinition[] = [
+  {
+    id: "default",
+    label: "Default",
+    description: "Standard agent mode",
+    icon: "ShieldCheck",
+    colorTier: "safe",
+  },
+  {
+    id: "autonomous",
+    label: "Autonomous",
+    description: "Runs without prompting",
+    icon: "ShieldOff",
+    colorTier: "dangerous",
+  },
+];
+```
+
+Available `colorTier` values: `"safe"`, `"moderate"`, `"dangerous"`, `"planning"`.
+Available `icon` values: `"ShieldCheck"`, `"ShieldAlert"`, `"ShieldOff"`.
+
+Then add to the `AGENT_PROVIDER_DEFINITIONS` array:
+
+```ts
+export const AGENT_PROVIDER_DEFINITIONS: AgentProviderDefinition[] = [
+  // ... existing providers ...
+  {
+    id: "my-provider",
+    label: "My Provider",
+    description: "Short description of the provider",
+    defaultModeId: "default",
+    modes: MY_PROVIDER_MODES,
+    // Optional: enable voice
+    voice: {
+      enabled: true,
+      defaultModeId: "default",
+      defaultModel: "some-model",
+    },
+  },
+];
+```
+
+### 3. Add the factory to the provider registry
+
+In `packages/server/src/server/agent/provider-registry.ts`, import your class and add a factory entry:
+
+```ts
+import { MyProviderACPAgentClient } from "./providers/my-provider-agent.js";
+
+const PROVIDER_CLIENT_FACTORIES: Record<string, ProviderClientFactory> = {
+  // ... existing factories ...
+  "my-provider": (logger, runtimeSettings) =>
+    new MyProviderACPAgentClient({
+      logger,
+      runtimeSettings: runtimeSettings?.["my-provider"],
+    }),
+};
+```
+
+### 4. Add a provider icon (app)
+
+Create `packages/app/src/components/icons/my-provider-icon.tsx` following the pattern from existing icons (e.g., `claude-icon.tsx`):
+
+```tsx
+import Svg, { Path } from "react-native-svg";
+
+interface MyProviderIconProps {
+  size?: number;
+  color?: string;
+}
+
+export function MyProviderIcon({ size = 16, color = "currentColor" }: MyProviderIconProps) {
+  return (
+    <Svg width={size} height={size} viewBox="0 0 24 24" fill={color}>
+      <Path d="..." />
+    </Svg>
+  );
+}
+```
+
+Then register it in `packages/app/src/components/provider-icons.ts`:
+
+```ts
+import { MyProviderIcon } from "@/components/icons/my-provider-icon";
+
+const PROVIDER_ICONS: Record<string, typeof Bot> = {
+  claude: ClaudeIcon as unknown as typeof Bot,
+  codex: CodexIcon as unknown as typeof Bot,
+  "my-provider": MyProviderIcon as unknown as typeof Bot,
+};
+```
+
+If no icon is registered, the app falls back to a generic `Bot` icon from lucide.
+
+### 5. Add E2E test config
+
+In `packages/server/src/server/daemon-e2e/agent-configs.ts`, add your provider:
+
+```ts
+export const agentConfigs = {
+  // ... existing configs ...
+  "my-provider": {
+    provider: "my-provider",
+    model: "default-model-id",
+    modes: {
+      full: "autonomous",   // Mode with no permission prompts
+      ask: "default",       // Mode that requires permission approval
+    },
+  },
+} as const satisfies Record<string, AgentTestConfig>;
+```
+
+Add an availability check in `isProviderAvailable()`:
+
+```ts
+case "my-provider":
+  return (
+    isCommandAvailable("my-agent-binary") &&
+    Boolean(process.env.MY_PROVIDER_API_KEY)
+  );
+```
+
+Add to the `allProviders` array:
+
+```ts
+export const allProviders: AgentProvider[] = [
+  "claude",
+  "claude-acp",
+  "codex",
+  "copilot",
+  "opencode",
+  "my-provider",
+];
+```
+
+### 6. Run typecheck
+
+```bash
+npm run typecheck
+```
+
+This is required after every change per project rules.
+
+---
+
+## Direct Provider Checklist
+
+If your agent does not speak ACP, implement the interfaces from `agent-sdk-types.ts` directly.
+
+### Interfaces to implement
+
+**`AgentClient`** -- factory for sessions and model listing:
+
+```ts
+interface AgentClient {
+  readonly provider: AgentProvider;
+  readonly capabilities: AgentCapabilityFlags;
+  createSession(config: AgentSessionConfig, launchContext?: AgentLaunchContext): Promise<AgentSession>;
+  resumeSession(handle: AgentPersistenceHandle, overrides?: Partial<AgentSessionConfig>, launchContext?: AgentLaunchContext): Promise<AgentSession>;
+  listModels(options?: ListModelsOptions): Promise<AgentModelDefinition[]>;
+  isAvailable(): Promise<boolean>;
+  // Optional:
+  listPersistedAgents?(options?: ListPersistedAgentsOptions): Promise<PersistedAgentDescriptor[]>;
+}
+```
+
+**`AgentSession`** -- a running agent conversation:
+
+```ts
+interface AgentSession {
+  readonly provider: AgentProvider;
+  readonly id: string | null;
+  readonly capabilities: AgentCapabilityFlags;
+  run(prompt: AgentPromptInput, options?: AgentRunOptions): Promise<AgentRunResult>;
+  startTurn(prompt: AgentPromptInput, options?: AgentRunOptions): Promise<{ turnId: string }>;
+  subscribe(callback: (event: AgentStreamEvent) => void): () => void;
+  streamHistory(): AsyncGenerator<AgentStreamEvent>;
+  getRuntimeInfo(): Promise<AgentRuntimeInfo>;
+  getAvailableModes(): Promise<AgentMode[]>;
+  getCurrentMode(): Promise<string | null>;
+  setMode(modeId: string): Promise<void>;
+  getPendingPermissions(): AgentPermissionRequest[];
+  respondToPermission(requestId: string, response: AgentPermissionResponse): Promise<void>;
+  describePersistence(): AgentPersistenceHandle | null;
+  interrupt(): Promise<void>;
+  close(): Promise<void>;
+  // Optional:
+  listCommands?(): Promise<AgentSlashCommand[]>;
+  setModel?(modelId: string | null): Promise<void>;
+  setThinkingOption?(thinkingOptionId: string | null): Promise<void>;
+}
+```
+
+### Steps
+
+1. Create `packages/server/src/server/agent/providers/{name}-agent.ts` implementing both interfaces
+2. Add to the provider manifest (same as ACP step 2 above)
+3. Add factory to the registry (same as ACP step 3 above)
+4. Add icon (same as ACP step 4 above)
+5. Add E2E config (same as ACP step 5 above)
+6. Run typecheck
+
+---
+
+## Testing
+
+### Manual testing with the CLI
+
+Start the daemon if not already running, then:
+
+```bash
+# Launch an agent with your provider
+paseo run --provider my-provider
+
+# Launch with a specific model and mode
+paseo run --provider my-provider --model some-model --mode default
+
+# List running agents
+paseo ls -a -g
+
+# Check if the provider reports models
+paseo models --provider my-provider
+```
+
+### E2E test patterns
+
+The E2E configs in `agent-configs.ts` expose two helpers:
+
+- `getFullAccessConfig(provider)` -- returns config for a session with no permission prompts
+- `getAskModeConfig(provider)` -- returns config for a session that triggers permission requests
+
+Tests use `isProviderAvailable(provider)` to skip when the binary or credentials are missing, so CI will not fail for providers that are not installed.
+
+---
+
+## Gotchas
+
+**Mode IDs can be URIs.** ACP providers like Copilot use full URIs as mode IDs (e.g., `"https://agentclientprotocol.com/protocol/session-modes#agent"`). Never assume mode IDs are simple strings. The manifest `defaultModeId` must match exactly.
+
+**Models and modes are discovered dynamically.** ACP providers report available models and modes at runtime via the protocol. The static definitions in `provider-manifest.ts` are used for UI scaffolding (icons, color tiers) but the runtime values from the agent process are the source of truth.
+
+**`AgentProvider` is always `string`.** The type alias is `type AgentProvider = string`. Provider IDs are validated against the manifest at runtime, not at the type level.
+
+**Auth patterns vary.** Some providers need API keys in env vars (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`), some use OAuth tokens (`CLAUDE_CODE_OAUTH_TOKEN`), some use auth files (`~/.codex/auth.json`), and some handle auth entirely in their CLI binary (Copilot). Your `isAvailable()` method should check whatever is needed.
+
+**The manifest mode list and the agent class mode list are separate.** The manifest in `provider-manifest.ts` includes UI metadata (`icon`, `colorTier`). The agent class defines modes without UI metadata (just `id`, `label`, `description`). Keep them in sync.
+
+**`defaultCommand` is a tuple.** The first element is the binary name, the rest are default arguments. The base class uses this to find the executable and spawn the process.
+
+**Runtime settings can override the command.** Users can configure custom binary paths or environment variables per provider via `ProviderRuntimeSettings`. Your factory in the registry should pass `runtimeSettings?.["your-provider"]` through to the constructor.

docs/RELEASE.md

@@ -0,0 +1,132 @@
+# Release
+
+All workspaces share one version and release together.
+
+## 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. **Release candidate flow**: you want public test builds first, but you are not ready for the website, npm, or production mobile release flows to move yet.
+
+## Standard release (patch)
+
+```bash
+npm run release:patch
+```
+
+This bumps the version across all workspaces, runs checks, publishes to npm, and pushes the branch + tag (triggering desktop, APK, and EAS mobile workflows).
+
+If asked to "release paseo" without specifying major/minor, treat it as a patch release.
+
+Use the direct stable path when the current `main` changes are ready to become the public release immediately.
+
+## Manual step-by-step
+
+```bash
+npm run release:check        # Typecheck, build, dry-run pack
+npm run version:all:patch    # Bump version, create commit + tag
+npm run release:publish      # Publish to npm
+npm run release:push         # Push HEAD + tag (triggers CI workflows)
+```
+
+## Release candidate flow
+
+```bash
+npm run release:rc:patch       # Bump to X.Y.Z-rc.1, push commit + tag
+# ... test desktop and APK prerelease assets from GitHub Releases ...
+npm run release:rc:next        # Optional: cut X.Y.Z-rc.2, rc.3, ...
+npm run release:promote        # Promote X.Y.Z-rc.N to stable X.Y.Z
+```
+
+- RC tags are published GitHub prereleases like `v0.1.41-rc.1`
+- RCs publish desktop assets and APKs for testing, but they do not publish npm packages and do not trigger the production web/mobile release flows
+- `release:promote` creates a fresh stable tag like `v0.1.41`; the final release never reuses the RC tag
+- Desktop assets now come from the Electron package at `packages/desktop`
+- **Do NOT create a changelog entry for RCs.** The changelog remains stable-only. RC release notes are generated automatically so the website stays pinned to the latest published stable release.
+
+Use the RC path when you need to:
+
+- test a build manually in a Linux or Windows VM
+- send a build to a user who is hitting a specific problem
+- iterate on `rc.1`, `rc.2`, `rc.3`, and so on before deciding to ship broadly
+
+## Website behavior
+
+- The website download page points to GitHub's latest published **stable** release.
+- Published RC prereleases are public on GitHub Releases, but they do **not** become the website download target.
+- The website only moves when you publish the final stable release tag like `v0.1.41`.
+
+## Fixing a failed release build
+
+**NEVER bump the version to fix a build problem.** New versions are reserved for meaningful product changes (features, fixes, improvements). Build/CI failures are fixed on the current version.
+
+**Do not rely on `workflow_dispatch` for tagged code fixes.** The `workflow_dispatch` trigger runs the workflow file from the default branch but checks out the code at the tag ref (`ref: ${{ inputs.tag }}`). That means fixes committed to `main` won't change the tagged source tree being built. `workflow_dispatch` only helps when the fix lives in the workflow file itself.
+
+To retry a failed workflow, **always push a retry tag** on the commit you want to build. Reusing the same tag name is expected: move it with `git tag -f ...` and push it with `--force` so the workflow rebuilds the commit you actually want.
+
+Prefer a tag push over `workflow_dispatch` whenever you are rebuilding release code or release assets.
+
+The retry tag patterns below still work and remain the supported way to rebuild specific release targets:
+
+```bash
+# Desktop (all platforms)
+git tag -f desktop-v0.1.28 HEAD && git push origin desktop-v0.1.28 --force
+
+# Desktop (single platform)
+git tag -f desktop-macos-v0.1.28 HEAD && git push origin desktop-macos-v0.1.28 --force
+git tag -f desktop-linux-v0.1.28 HEAD && git push origin desktop-linux-v0.1.28 --force
+git tag -f desktop-windows-v0.1.28 HEAD && git push origin desktop-windows-v0.1.28 --force
+
+# Android APK
+git tag -f android-v0.1.28 HEAD && git push origin android-v0.1.28 --force
+
+# RC
+git tag -f v0.1.29-rc.2 HEAD && git push origin v0.1.29-rc.2 --force
+```
+
+This ensures the checkout ref matches the actual code on `main` with the fix included.
+
+- `vX.Y.Z` or `vX.Y.Z-rc.N` rebuilds the full tagged release
+- `desktop-vX.Y.Z` rebuilds desktop for all desktop platforms only
+- `desktop-macos-vX.Y.Z`, `desktop-linux-vX.Y.Z`, and `desktop-windows-vX.Y.Z` rebuild only that desktop platform
+- `android-vX.Y.Z` rebuilds the Android APK release only
+
+## Notes
+
+- `version:all:*` bumps root + syncs workspace versions and `@getpaseo/*` dependency versions
+- `release:prepare` refreshes workspace `node_modules` links to prevent stale types
+- `npm run dev:desktop` and `npm run build:desktop` target the Electron desktop package in `packages/desktop`
+- If `release:publish` partially fails, re-run it — npm skips already-published versions
+- The website uses GitHub's latest published release API for download links, so published RC prereleases do not replace the stable download target.
+
+## Changelog format
+
+Stable release notes depend on the changelog heading format. The heading **must** be strictly followed:
+
+```
+## X.Y.Z - 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` is for **final stable releases only**.
+- Do not add or edit changelog entries while iterating on RCs.
+- Write the proper changelog entry when you are cutting the final stable release that comes after the RC cycle.
+- Between stable releases, keep changelog work out of the repo until the final release is ready.
+
+## Changelog ownership
+
+- **Only Claude should write changelog entries.**
+- If you are Codex and a stable release needs a changelog entry, launch a Claude agent with Paseo to draft it, then review and commit the result.
+
+## Completion checklist
+
+- [ ] Update `CHANGELOG.md` with user-facing release notes (features, fixes — not refactors)
+- [ ] Verify the changelog heading follows strict `## X.Y.Z - YYYY-MM-DD` format
+- [ ] `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

docs/TESTING.md

@@ -0,0 +1,123 @@
+# Testing
+
+## Philosophy
+
+Tests prove behavior, not structure. Every test should answer: "what user-visible or API-visible behavior does this verify?"
+
+## Test-driven development
+
+Work in vertical slices: one test, one implementation, repeat. Each test responds to what you learned from the previous cycle.
+
+```
+RIGHT (vertical):
+  RED→GREEN: test1→impl1
+  RED→GREEN: test2→impl2
+  RED→GREEN: test3→impl3
+
+WRONG (horizontal):
+  RED:   test1, test2, test3, test4, test5
+  GREEN: impl1, impl2, impl3, impl4, impl5
+```
+
+Writing all tests first then all implementation produces bad tests — you end up testing imagined behavior instead of actual behavior.
+
+## Determinism first
+
+Tests must produce the same result every run:
+
+- No conditional assertions or branching paths
+- No reliance on timing, randomness, or network jitter
+- No weak assertions (`toBeTruthy`, `toBeDefined`)
+- Assert the full intended behavior, not fragments
+
+```typescript
+// Bad: conditional and weak
+it("creates a tool call", async () => {
+  const result = await createToolCall(input);
+  if (result.ok) {
+    expect(result.id).toBeDefined();
+  }
+});
+
+// Good: deterministic and explicit
+it("returns timeout error when provider times out", async () => {
+  const result = await createToolCall(input);
+  expect(result).toEqual({
+    ok: false,
+    error: { code: "PROVIDER_TIMEOUT", waitedMs: 30000 },
+  });
+});
+```
+
+## Flaky tests are a bug
+
+Never remove a test because it's flaky. Find the variance source (time, randomness, race condition, shared state, non-deterministic output, environment drift) and fix it.
+
+## Real dependencies over mocks
+
+Mocks are not the default. They require an explicit decision.
+
+- **Database**: real test database, not a mock
+- **APIs**: real APIs with test/sandbox credentials, not request mocks
+- **File system**: temporary directory that gets cleaned up, not fs mocks
+
+Ask: "will this still hold with real dependencies at runtime?" If no, don't mock.
+
+### Use swappable adapters instead
+
+When you need test isolation, design code so dependencies are injectable:
+
+```typescript
+interface EmailSender {
+  send(to: string, body: string): Promise<void>;
+}
+
+// Production
+const realSender: EmailSender = { send: sendgrid.send };
+
+// Test: in-memory adapter
+function createTestEmailSender() {
+  const sent: Array<{ to: string; body: string }> = [];
+  return {
+    send: async (to: string, body: string) => { sent.push({ to, body }); },
+    sent,
+  };
+}
+```
+
+## End-to-end means end-to-end
+
+When a test is labeled end-to-end, it calls the real service. No environment variable gates, no conditional skipping, no mocking the external dependency.
+
+## Test organization
+
+- Collocate tests with implementation: `thing.ts` + `thing.test.ts`
+- Extract complex setup into reusable helpers
+- Test bodies should read like plain English
+- Build a vocabulary of test helpers that make complex flows simple
+
+## Agent authentication in tests
+
+Agent providers handle their own auth. Do not add auth checks, environment variable gates, or conditional skips to tests. If auth fails, report it.
+
+## Debugging with tests
+
+Use the test as your debugging ground:
+
+1. Add temporary logging to the code under test
+2. Run the test, observe actual values
+3. Trace the flow end-to-end through test output
+4. Confirm each assumption with actual output
+5. Remove logging when done
+
+The test output is the source of truth, not your reading of the code.
+
+## Design for testability
+
+If code isn't testable, refactor it. Signs:
+- You want to reach for a mock
+- You can't inject a dependency
+- You need to test private internals
+- Setup requires too much global state
+
+Aim for deep modules: small interface, deep implementation. Fewer methods = fewer tests needed, simpler params = simpler setup.

flake.lock

@@ -0,0 +1,27 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1772963539,
+        "narHash": "sha256-9jVDGZnvCckTGdYT53d/EfznygLskyLQXYwJLKMPsZs=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "9dcb002ca1690658be4a04645215baea8b95f31d",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,59 @@
+{
+  description = "Paseo - self-hosted daemon for AI coding agents";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+  };
+
+  outputs =
+    {
+      self,
+      nixpkgs,
+    }:
+    let
+      supportedSystems = [
+        "x86_64-linux"
+        "aarch64-linux"
+        "x86_64-darwin"
+        "aarch64-darwin"
+      ];
+      forAllSystems = nixpkgs.lib.genAttrs supportedSystems;
+      pkgsFor = system: import nixpkgs { inherit system; };
+    in
+    {
+      packages = forAllSystems (
+        system:
+        let
+          pkgs = pkgsFor system;
+          paseo = pkgs.callPackage ./nix/package.nix { };
+        in
+        {
+          default = paseo;
+          paseo = paseo;
+        }
+      );
+
+      nixosModules.default = self.nixosModules.paseo;
+      nixosModules.paseo =
+        { pkgs, lib, ... }:
+        {
+          imports = [ ./nix/module.nix ];
+          services.paseo.package = lib.mkDefault self.packages.${pkgs.stdenv.hostPlatform.system}.default;
+        };
+
+      devShells = forAllSystems (
+        system:
+        let
+          pkgs = pkgsFor system;
+        in
+        {
+          default = pkgs.mkShell {
+            packages = [
+              pkgs.nodejs_22
+              pkgs.python3
+            ];
+          };
+        }
+      );
+    };
+}

nix/module.nix

@@ -0,0 +1,172 @@
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+
+let
+  cfg = config.services.paseo;
+in
+{
+  options.services.paseo = {
+    enable = lib.mkEnableOption "Paseo, a self-hosted daemon for AI coding agents";
+
+    package = lib.mkPackageOption pkgs "paseo" { };
+
+    user = lib.mkOption {
+      type = lib.types.str;
+      default = "paseo";
+      description = "User account under which Paseo runs.";
+    };
+
+    group = lib.mkOption {
+      type = lib.types.str;
+      default = "paseo";
+      description = "Group under which Paseo runs.";
+    };
+
+    dataDir = lib.mkOption {
+      type = lib.types.str;
+      default =
+        if cfg.user == "paseo"
+        then "/var/lib/paseo"
+        else "/home/${cfg.user}/.paseo";
+      defaultText = lib.literalExpression ''
+        if cfg.user == "paseo"
+        then "/var/lib/paseo"
+        else "/home/''${cfg.user}/.paseo"
+      '';
+      description = "Directory for Paseo state (PASEO_HOME). Stores agent data, config, and logs.";
+    };
+
+    port = lib.mkOption {
+      type = lib.types.port;
+      default = 6767;
+      description = "Port for the Paseo daemon to listen on.";
+    };
+
+    listenAddress = lib.mkOption {
+      type = lib.types.str;
+      default = "127.0.0.1";
+      description = "Address for the Paseo daemon to bind to.";
+    };
+
+    openFirewall = lib.mkOption {
+      type = lib.types.bool;
+      default = false;
+      description = "Whether to open the firewall for the Paseo daemon port.";
+    };
+
+    allowedHosts = lib.mkOption {
+      type = lib.types.either (lib.types.enum [ true ]) (lib.types.listOf lib.types.str);
+      default = [ ];
+      example = [ ".example.com" "myhost.local" ];
+      description = ''
+        Hosts allowed to connect to the Paseo daemon (DNS rebinding protection).
+        Localhost and IP addresses are always allowed by default.
+
+        Use a leading dot to match a domain and all its subdomains
+        (e.g. `".example.com"` matches `example.com` and `foo.example.com`).
+
+        Set to `true` to allow any host (not recommended).
+      '';
+    };
+
+    relay = {
+      enable = lib.mkOption {
+        type = lib.types.bool;
+        default = true;
+        description = "Whether to enable the relay connection for remote access via app.paseo.sh.";
+      };
+    };
+
+    inheritUserEnvironment = lib.mkOption {
+      type = lib.types.bool;
+      default = cfg.user != "paseo";
+      defaultText = lib.literalExpression ''cfg.user != "paseo"'';
+      description = ''
+        Whether to include the user's profile PATH in the service environment.
+
+        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.
+
+        Enabled by default when `user` is set to a non-default value.
+      '';
+    };
+
+    environment = lib.mkOption {
+      type = lib.types.attrsOf lib.types.str;
+      default = { };
+      example = lib.literalExpression ''
+        {
+          PASEO_RELAY_ENDPOINT = "relay.paseo.sh:443";
+        }
+      '';
+      description = "Extra environment variables for the Paseo daemon.";
+    };
+  };
+
+  config = lib.mkIf cfg.enable {
+    users.users.${cfg.user} = lib.mkIf (cfg.user == "paseo") {
+      isSystemUser = true;
+      group = cfg.group;
+      home = cfg.dataDir;
+    };
+
+    users.groups.${cfg.group} = lib.mkIf (cfg.group == "paseo") { };
+
+    systemd.tmpfiles.rules = [
+      "d ${cfg.dataDir} 0700 ${cfg.user} ${cfg.group} - -"
+    ];
+
+    systemd.services.paseo = {
+      description = "Paseo - self-hosted daemon for AI coding agents";
+      after = [ "network.target" ];
+      wantedBy = [ "multi-user.target" ];
+
+      environment = {
+        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.allowedHosts == true) {
+        PASEO_ALLOWED_HOSTS = "true";
+      } // lib.optionalAttrs (lib.isList cfg.allowedHosts && cfg.allowedHosts != [ ]) {
+        PASEO_ALLOWED_HOSTS = lib.concatStringsSep "," cfg.allowedHosts;
+      } // cfg.environment;
+
+      serviceConfig = {
+        Type = "simple";
+        User = cfg.user;
+        Group = cfg.group;
+
+        ExecStart =
+          "${cfg.package}/bin/paseo-server"
+          + lib.optionalString (!cfg.relay.enable) " --no-relay";
+
+        Restart = "on-failure";
+        RestartSec = 5;
+
+        # Graceful shutdown (server handles SIGTERM with a 10s timeout)
+        KillSignal = "SIGTERM";
+        TimeoutStopSec = 15;
+      };
+    };
+
+    environment.systemPackages = [ cfg.package ];
+
+    networking.firewall.allowedTCPPorts = lib.mkIf cfg.openFirewall [ cfg.port ];
+  };
+}

nix/package.nix

@@ -0,0 +1,144 @@
+{
+  lib,
+  stdenv,
+  buildNpmPackage,
+  nodejs_22,
+  python3,
+  makeWrapper,
+  # node-pty needs libuv headers on Linux
+  libuv,
+}:
+
+buildNpmPackage rec {
+  pname = "paseo";
+  version = (builtins.fromJSON (builtins.readFile ../package.json)).version;
+
+  src = lib.cleanSourceWith {
+    src = ./..;
+    filter = path: type:
+      let
+        baseName = builtins.baseNameOf path;
+        relPath = lib.removePrefix (toString ./..) path;
+      in
+      # Exclude non-daemon workspace contents (keep package.json for workspace resolution)
+      !(lib.hasPrefix "/packages/app/src" relPath)
+      && !(lib.hasPrefix "/packages/app/assets" relPath)
+      && !(lib.hasPrefix "/packages/app/android" relPath)
+      && !(lib.hasPrefix "/packages/app/ios" relPath)
+      && !(lib.hasPrefix "/packages/website/src" relPath)
+      && !(lib.hasPrefix "/packages/website/public" relPath)
+      && !(lib.hasPrefix "/packages/desktop/src" relPath)
+      && !(lib.hasPrefix "/packages/desktop/src-tauri" relPath)
+      # Exclude test fixtures and debug files
+      && !(lib.hasSuffix ".test.ts" baseName)
+      && !(lib.hasSuffix ".e2e.test.ts" baseName)
+      && baseName != "node_modules"
+      && baseName != ".git"
+      && baseName != ".paseo"
+      && baseName != ".DS_Store";
+  };
+
+  nodejs = nodejs_22;
+
+  # To update: run `nix build` with lib.fakeHash, copy the `got:` hash.
+  # CI auto-updates this when package-lock.json changes (see .github/workflows/).
+  npmDepsHash = "sha256-0fzdnz2LQ0IRk2wbe0/wORylp7mgU0gl2fAs8my4Eok=";
+
+  # Prevent onnxruntime-node's install script from running during automatic
+  # npm rebuild (it tries to download from api.nuget.org, which fails in the sandbox).
+  # We manually rebuild only node-pty in buildPhase.
+  npmRebuildFlags = [ "--ignore-scripts" ];
+
+  nativeBuildInputs = [
+    python3 # for node-gyp (node-pty compilation)
+    makeWrapper
+  ];
+
+  buildInputs = lib.optionals stdenv.hostPlatform.isLinux [
+    libuv
+  ];
+
+  # Don't use the default npm build hook — we need a custom build sequence
+  dontNpmBuild = true;
+
+  buildPhase = ''
+    runHook preBuild
+
+    # Rebuild only node-pty (native addon for terminal emulation).
+    # Speech-related native modules (sherpa-onnx, onnxruntime-node) are
+    # intentionally left unbuilt — they're lazily loaded and gracefully
+    # degrade when unavailable.
+    npm rebuild node-pty
+
+    # Build all daemon packages in dependency order (defined in package.json)
+    npm run build:daemon
+
+    runHook postBuild
+  '';
+
+  installPhase = ''
+    runHook preInstall
+
+    mkdir -p $out/lib/paseo
+
+    # Copy root package metadata
+    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 \
+      --add-flags "$out/lib/paseo/packages/server/dist/server/server/index.js" \
+      --set NODE_ENV production
+
+    # Create wrapper for the CLI
+    makeWrapper ${nodejs}/bin/node $out/bin/paseo \
+      --add-flags "$out/lib/paseo/packages/cli/dist/index.js" \
+      --set NODE_PATH "$out/lib/paseo/node_modules"
+
+    runHook postInstall
+  '';
+
+  meta = {
+    description = "Self-hosted daemon for Claude Code, Codex, and OpenCode";
+    homepage = "https://github.com/getpaseo/paseo";
+    license = lib.licenses.agpl3Plus;
+    mainProgram = "paseo";
+    platforms = lib.platforms.linux ++ lib.platforms.darwin;
+  };
+}

package.json

@@ -1,8 +1,10 @@
 {
   "name": "paseo",
-  "version": "0.1.13",
+  "version": "0.1.43",
   "private": true,
   "workspaces": [
+    "packages/expo-two-way-audio",
+    "packages/highlight",
     "packages/server",
     "packages/app",
     "packages/relay",
@@ -12,49 +14,66 @@
   ],
   "scripts": {
     "dev": "./scripts/dev.sh",
-    "dev:server": "NODE_ENV=development tsx packages/server/scripts/daemon-runner.ts --dev",
+    "dev:server": "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",
     "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",
     "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",
     "test": "npm run test --workspaces --if-present",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
     "start": "npm run start --workspace=@getpaseo/server",
     "android": "npm run android --workspace=@getpaseo/app",
     "android:development": "npm run android:development --workspace=@getpaseo/app",
-    "android:prod": "npm run android:prod --workspace=@getpaseo/app",
     "android:production": "npm run android:production --workspace=@getpaseo/app",
-    "android:release": "npm run android:prod --workspace=@getpaseo/app",
+    "android:release": "npm run android:production --workspace=@getpaseo/app",
+    "android:clear": "npm run android:clear --workspace=@getpaseo/app",
+    "android:clean": "npm run android:clean --workspace=@getpaseo/app",
     "ios": "npm run ios --workspace=@getpaseo/app",
     "web": "npm run web --workspace=@getpaseo/app",
     "dev:desktop": "npm run dev --workspace=@getpaseo/desktop",
-    "build:desktop": "npm run build --workspace=@getpaseo/desktop",
+    "build:desktop": "npm run version:sync-internal && npm run build:web --workspace=@getpaseo/app && npm run build --workspace=@getpaseo/desktop",
     "cli": "npx tsx packages/cli/src/index.js",
     "version": "npm run version:sync-internal && npm run release:prepare && git add -A",
     "version:sync-internal": "node scripts/sync-workspace-versions.mjs",
     "release:prepare": "npm install --workspaces --include-workspace-root",
-    "version:all:patch": "npm version patch --include-workspace-root --message \"chore(release): cut %s\"",
-    "version:all:minor": "npm version minor --include-workspace-root --message \"chore(release): cut %s\"",
-    "version:all:major": "npm version major --include-workspace-root --message \"chore(release): cut %s\"",
-    "release:check": "npm run release:prepare && npm run typecheck --workspace=@getpaseo/relay && npm run typecheck --workspace=@getpaseo/server && npm run typecheck --workspace=@getpaseo/cli && npm run build --workspace=@getpaseo/relay && npm run build --workspace=@getpaseo/server && npm run build --workspace=@getpaseo/cli && 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/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/relay --access public && npm publish --workspace=@getpaseo/server --access public && npm publish --workspace=@getpaseo/cli --access public",
+    "version:all:patch": "node scripts/set-release-version.mjs --mode patch",
+    "version:all:minor": "node scripts/set-release-version.mjs --mode minor",
+    "version:all:major": "node scripts/set-release-version.mjs --mode major",
+    "version:all:rc:patch": "node scripts/set-release-version.mjs --mode rc-patch",
+    "version:all:rc:minor": "node scripts/set-release-version.mjs --mode rc-minor",
+    "version:all:rc:major": "node scripts/set-release-version.mjs --mode rc-major",
+    "version:all:rc:next": "node scripts/set-release-version.mjs --mode rc-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:push": "node scripts/push-current-release-tag.mjs",
-    "release:patch": "npm run version:all:patch && npm run release:check && npm run release:publish && npm run release:push",
-    "release:minor": "npm run version:all:minor && npm run release:check && npm run release:publish && npm run release:push",
-    "release:major": "npm run version:all:major && npm run release:check && npm run release:publish && npm run release:push"
+    "release:rc:patch": "npm run release:check && npm run version:all:rc:patch && npm run release:push",
+    "release:rc:minor": "npm run release:check && npm run version:all:rc:minor && npm run release:push",
+    "release:rc:major": "npm run release:check && npm run version:all:rc:major && npm run release:push",
+    "release:rc:next": "npm run release:check && npm run version:all:rc:next && npm run release:push",
+    "release:promote": "npm run release:check && npm run version:all:promote && npm run release:publish && npm run release:push",
+    "release:patch": "npm run release:check && npm run version:all:patch && npm run release:publish && npm run release:push",
+    "release:minor": "npm run release:check && npm run version:all:minor && npm run release:publish && npm run release:push",
+    "release:major": "npm run release:check && npm run version:all:major && npm run release:publish && npm run release:push"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.4.8",
     "concurrently": "^9.2.1",
-    "prettier": "^3.5.3",
     "get-port-cli": "^3.0.0",
     "knip": "^5.82.1",
     "patch-package": "^8.0.1",
+    "react": "19.1.4",
+    "react-dom": "19.1.4",
     "typescript": "^5.9.3"
   },
   "description": "Paseo: voice-controlled development environment with OpenAI Realtime API",
+  "homepage": "https://paseo.sh",
   "keywords": [
     "openai",
     "realtime",
@@ -63,12 +82,22 @@
     "development",
     "mcp"
   ],
-  "author": "moboudra",
-  "license": "MIT",
+  "author": {
+    "name": "Mohamed Boudra",
+    "email": "hello@moboudra.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/getpaseo/paseo.git"
+  },
+  "license": "AGPL-3.0-or-later",
   "overrides": {
-    "lightningcss": "1.30.1"
+    "lightningcss": "1.30.1",
+    "react": "19.1.4",
+    "react-dom": "19.1.4"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.11"
+    "@anthropic-ai/claude-agent-sdk": "^0.2.11",
+    "@modelcontextprotocol/sdk": "^1.27.1"
   }
 }

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

@@ -4,6 +4,7 @@ on:
   push:
     tags:
       - "v*"
+      - "!v*-rc.*"
   workflow_dispatch: {}
 
 jobs:

packages/app/app.config.js

@@ -65,8 +65,7 @@ export default {
     ios: {
       supportsTablet: true,
       infoPlist: {
-        NSMicrophoneUsageDescription:
-          "This app needs access to the microphone for voice commands.",
+        NSMicrophoneUsageDescription: "This app needs access to the microphone for voice commands.",
         ITSAppUsesNonExemptEncryption: false,
       },
       bundleIdentifier: variant.packageId,
@@ -92,14 +91,15 @@ export default {
         "android.permission.CAMERA",
       ],
       package: variant.packageId,
-      ...(variant.googleServicesFile
-        ? { googleServicesFile: variant.googleServicesFile }
-        : {}),
+      ...(variant.googleServicesFile ? { googleServicesFile: variant.googleServicesFile } : {}),
     },
     web: {
       output: "single",
       favicon: "./assets/images/favicon.png",
     },
+    autolinking: {
+      searchPaths: ["../../node_modules", "./node_modules"],
+    },
     plugins: [
       "expo-router",
       [
@@ -143,6 +143,7 @@ export default {
     experiments: {
       typedRoutes: true,
       reactCompiler: true,
+      autolinkingModuleResolution: true,
     },
     extra: {
       router: {},

packages/app/e2e/agent-details-sheet.spec.ts

@@ -1,37 +0,0 @@
-import { test, expect } from "./fixtures";
-import { createAgent, ensureHostSelected, gotoHome, setWorkingDirectory } from "./helpers/app";
-import { createTempGitRepo } from "./helpers/workspace";
-
-test("agent details sheet shows IDs and copy toast", async ({ page }) => {
-  test.setTimeout(120_000);
-  const repo = await createTempGitRepo();
-  const prompt = "Respond with exactly: Hello";
-
-  try {
-    await gotoHome(page);
-    await setWorkingDirectory(page, repo.path);
-    await ensureHostSelected(page);
-    await createAgent(page, prompt);
-
-    await page.getByTestId("agent-overflow-menu").click();
-    await page.getByTestId("agent-menu-details").click();
-
-    await expect(page.getByTestId("agent-details-sheet")).toBeVisible();
-
-    await expect(page.getByTestId("agent-details-agent-id")).toBeVisible();
-    await expect(page.getByTestId("agent-details-agent-id-value")).not.toHaveText(
-      "Not available"
-    );
-
-    await expect(page.getByTestId("agent-details-persistence-session-id")).toBeVisible();
-    await expect(
-      page.getByTestId("agent-details-persistence-session-id-value")
-    ).not.toHaveText("Not available", { timeout: 90_000 });
-
-    await page.getByTestId("agent-details-agent-id").click();
-    await expect(page.getByTestId("app-toast")).toBeVisible();
-    await expect(page.getByTestId("app-toast-message")).toHaveText(/copied/i);
-  } finally {
-    await repo.cleanup();
-  }
-});

packages/app/e2e/agent-timeline-hydration.spec.ts

@@ -1,34 +0,0 @@
-import { test, expect } from './fixtures';
-import { createAgent, ensureHostSelected, gotoHome, setWorkingDirectory } from './helpers/app';
-import { createTempGitRepo } from './helpers/workspace';
-
-test('agent timeline hydrates after reload via fetch_agent_timeline_request', async ({ page }) => {
-  const repo = await createTempGitRepo();
-  const marker = 'TIMELINE_HYDRATION_OK';
-  const prompt = `Respond with exactly: ${marker}`;
-
-  try {
-    await gotoHome(page);
-    await setWorkingDirectory(page, repo.path);
-    await ensureHostSelected(page);
-    await createAgent(page, prompt);
-
-    const assistantMessage = page
-      .getByTestId('assistant-message')
-      .filter({ hasText: marker })
-      .first();
-    await expect(assistantMessage).toBeVisible({ timeout: 120000 });
-
-    await page.reload({ waitUntil: 'commit' });
-    await expect(page).toHaveURL(/\/agent\//);
-    await expect(page.getByTestId('agent-loading')).toHaveCount(0, { timeout: 30000 });
-    await expect(page.getByText(prompt, { exact: true }).first()).toBeVisible({
-      timeout: 30000,
-    });
-    await expect(
-      page.getByTestId('assistant-message').filter({ hasText: marker }).first()
-    ).toBeVisible({ timeout: 30000 });
-  } finally {
-    await repo.cleanup();
-  }
-});

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

@@ -0,0 +1,106 @@
+import { randomUUID } from "node:crypto";
+import { test } from "./fixtures";
+import { createTempGitRepo } from "./helpers/workspace";
+import {
+  archiveAgentFromDaemon,
+  archiveAgentFromSessions,
+  connectArchiveTabDaemonClient,
+  createIdleAgent,
+  expectSessionRowVisible,
+  expectWorkspaceArchiveOutcome,
+  openSessions,
+  openWorkspaceWithAgents,
+  primeAdditionalPage,
+  resetSeededPageState,
+  reloadWorkspace,
+} from "./helpers/archive-tab";
+
+test.describe("Archive tab reconciliation", () => {
+  let client: Awaited<ReturnType<typeof connectArchiveTabDaemonClient>>;
+  let tempRepo: { path: string; cleanup: () => Promise<void> };
+
+  test.beforeAll(async () => {
+    tempRepo = await createTempGitRepo("archive-tab-");
+    client = await connectArchiveTabDaemonClient();
+  });
+
+  test.afterAll(async () => {
+    await client?.close();
+    await tempRepo?.cleanup();
+  });
+
+  test("non-UI archive prunes the archived tab across open pages and reload", async ({ page }) => {
+    const archived = await createIdleAgent(client, {
+      cwd: tempRepo.path,
+      title: `cli-archive-${randomUUID().slice(0, 8)}`,
+    });
+    const surviving = await createIdleAgent(client, {
+      cwd: tempRepo.path,
+      title: `cli-control-${randomUUID().slice(0, 8)}`,
+    });
+    const passivePage = await page.context().newPage();
+
+    try {
+      await primeAdditionalPage(passivePage);
+      await resetSeededPageState(page);
+      await resetSeededPageState(passivePage);
+      await openSessions(page);
+      await expectSessionRowVisible(page, archived.title);
+      await expectSessionRowVisible(page, surviving.title);
+      await openSessions(passivePage);
+      await expectSessionRowVisible(passivePage, archived.title);
+      await expectSessionRowVisible(passivePage, surviving.title);
+      await openWorkspaceWithAgents(page, [archived, surviving]);
+      await openWorkspaceWithAgents(passivePage, [archived, surviving]);
+      await archiveAgentFromDaemon(client, archived.id);
+      await expectWorkspaceArchiveOutcome(page, {
+        archivedAgentId: archived.id,
+        survivingAgentId: surviving.id,
+      });
+      await expectWorkspaceArchiveOutcome(passivePage, {
+        archivedAgentId: archived.id,
+        survivingAgentId: surviving.id,
+      });
+      await reloadWorkspace(passivePage, tempRepo.path);
+      await expectWorkspaceArchiveOutcome(passivePage, {
+        archivedAgentId: archived.id,
+        survivingAgentId: surviving.id,
+      });
+    } finally {
+      await passivePage.close();
+    }
+  });
+
+  test("Sessions archive prunes the archived tab across open pages", async ({ page }) => {
+    const archived = await createIdleAgent(client, {
+      cwd: tempRepo.path,
+      title: `ui-archive-${randomUUID().slice(0, 8)}`,
+    });
+    const surviving = await createIdleAgent(client, {
+      cwd: tempRepo.path,
+      title: `ui-control-${randomUUID().slice(0, 8)}`,
+    });
+    const passivePage = await page.context().newPage();
+
+    try {
+      await primeAdditionalPage(passivePage);
+      await resetSeededPageState(page);
+      await resetSeededPageState(passivePage);
+      await openWorkspaceWithAgents(page, [archived, surviving]);
+      await openWorkspaceWithAgents(passivePage, [archived, surviving]);
+      await openSessions(page);
+      await archiveAgentFromSessions(page, { agentId: archived.id, title: archived.title });
+      await reloadWorkspace(page, tempRepo.path);
+      await expectWorkspaceArchiveOutcome(page, {
+        archivedAgentId: archived.id,
+        survivingAgentId: surviving.id,
+      });
+      await expectWorkspaceArchiveOutcome(passivePage, {
+        archivedAgentId: archived.id,
+        survivingAgentId: surviving.id,
+      });
+    } finally {
+      await passivePage.close();
+    }
+  });
+});

packages/app/e2e/checkout-ship.spec.ts

@@ -1,428 +0,0 @@
-import path from 'node:path';
-import { appendFile, mkdtemp, rm, writeFile, realpath } from 'node:fs/promises';
-import { execSync } from 'node:child_process';
-import { tmpdir } from 'node:os';
-import { test, expect, type Page } from './fixtures';
-import {
-  ensureHostSelected,
-  gotoHome,
-  setWorkingDirectory,
-} from './helpers/app';
-import { createTempGitRepo } from './helpers/workspace';
-
-test.describe.configure({ mode: 'serial', timeout: 120000 });
-
-function getChangesScope(page: Page) {
-  return page.locator('[data-testid="explorer-content-area"]:visible').first();
-}
-
-function getChangesHeader(page: Page) {
-  return getChangesScope(page).getByTestId('changes-header');
-}
-
-async function selectChangesView(page: Page, view: 'working' | 'base') {
-  // Defensive: close any open dropdown menus (their backdrops intercept clicks).
-  const primaryBackdrop = page.getByTestId('changes-primary-cta-menu-backdrop');
-  if (await primaryBackdrop.isVisible().catch(() => false)) {
-    await primaryBackdrop.click({ force: true });
-    await expect(primaryBackdrop).toHaveCount(0);
-  }
-  const overflowBackdrop = page.getByTestId('changes-overflow-content-backdrop');
-  if (await overflowBackdrop.isVisible().catch(() => false)) {
-    await overflowBackdrop.click({ force: true });
-    await expect(overflowBackdrop).toHaveCount(0);
-  }
-
-  const scope = getChangesScope(page);
-  const modeToggle = scope.getByTestId('changes-diff-status').first();
-  const expected = view === 'working' ? 'Uncommitted' : 'Committed';
-  if (!(await modeToggle.isVisible().catch(() => false))) {
-    return;
-  }
-  const current = ((await modeToggle.innerText().catch(() => '')) ?? '').trim();
-  if (current !== expected) {
-    await modeToggle.click();
-  }
-  await expect(modeToggle).toContainText(expected, { timeout: 10000 });
-}
-
-async function openChangesOverflowMenu(page: Page) {
-  const menuButton = getChangesScope(page).locator('[data-testid="changes-overflow-menu"]:visible').first();
-  await expect(menuButton).toBeVisible();
-  await menuButton.click();
-}
-
-async function openChangesPrimaryMenu(page: Page) {
-  const scope = getChangesScope(page);
-  const caret = scope.getByTestId('changes-primary-cta-caret').first();
-  await expect(caret).toBeVisible();
-  await caret.click();
-  // Menu content is rendered via a portal, so don't scope it to the explorer content area.
-  await expect(page.getByTestId('changes-primary-cta-menu')).toBeVisible();
-}
-
-async function openChangesPanel(page: Page, options?: { expectGit?: boolean }) {
-  const changesHeader = getChangesHeader(page);
-  if (!(await changesHeader.isVisible())) {
-    const explorerHeader = page.getByTestId('explorer-header');
-    if (await explorerHeader.isVisible()) {
-      const changesTab = explorerHeader.getByText('Changes', { exact: true });
-      if (await changesTab.isVisible().catch(() => false)) {
-        await changesTab.click();
-      } else {
-        const overflowMenu = page.getByTestId('agent-overflow-menu').first();
-        await expect(overflowMenu).toBeVisible({ timeout: 10000 });
-        await overflowMenu.click();
-        await page.getByText(/view changes/i).first().click();
-      }
-    } else {
-      const overflowMenu = page.getByTestId('agent-overflow-menu').first();
-      await expect(overflowMenu).toBeVisible({ timeout: 10000 });
-      await overflowMenu.click();
-      await page.getByText(/view changes/i).first().click();
-    }
-  }
-  await expect(changesHeader).toBeVisible({ timeout: 30000 });
-  if (options?.expectGit === false) {
-    return;
-  }
-  const changesScope = getChangesScope(page);
-  await expect(changesScope.getByTestId('changes-not-git')).toHaveCount(0, {
-    timeout: 30000,
-  });
-  await expect(changesScope.getByTestId('changes-branch')).not.toHaveText('Not a git repository', {
-    timeout: 30000,
-  });
-}
-
-async function sendPrompt(page: Page, prompt: string) {
-  const input = page.getByRole('textbox', { name: 'Message agent...' });
-  await expect(input).toBeEditable();
-  await input.fill(prompt);
-  await input.press('Enter');
-}
-
-async function waitForAssistantText(page: Page, text: string) {
-  const assistantMessage = page.getByTestId('assistant-message').filter({ hasText: text }).last();
-  await expect(assistantMessage).toBeVisible({ timeout: 60000 });
-  return assistantMessage;
-}
-
-async function createAgentAndWait(page: Page, message: string) {
-  const input = page.getByRole('textbox', { name: 'Message agent...' });
-  await expect(input).toBeEditable();
-  await input.fill(message);
-  await input.press('Enter');
-  await expect(page).toHaveURL(/\/agent\//, { timeout: 120000 });
-  await expect(page.getByText(message, { exact: true })).toBeVisible();
-}
-
-async function requestCwd(page: Page) {
-  await sendPrompt(page, 'Run `pwd` and respond with exactly: CWD: <path>');
-  const message = await waitForAssistantText(page, 'CWD:');
-  // The assistant streams tokens; make sure we capture the full path (not a partial prefix).
-  await expect.poll(async () => (await message.textContent()) ?? '', { timeout: 60000 }).toContain('/worktrees/');
-  const content = (await message.textContent()) ?? '';
-  const match = content.match(/CWD:\s*(\S+)/);
-  if (!match) {
-    throw new Error(`Expected agent to respond with "CWD: <path>", got: ${content}`);
-  }
-  return match[1].trim();
-}
-
-async function selectAttachWorktree(page: Page, branchName: string) {
-  await page.getByTestId('worktree-attach-toggle').click();
-  const picker = page.getByTestId('worktree-attach-picker');
-  await expect(picker).toBeVisible();
-
-  // Wait a bit for the worktree list to load
-  await page.waitForTimeout(1000);
-
-  await picker.click();
-
-  // Wait a bit for animation
-  await page.waitForTimeout(500);
-
-  const sheet = page.getByLabel('Bottom Sheet', { exact: true });
-  const backdrop = page.getByRole('button', { name: 'Bottom sheet backdrop' }).first();
-
-  await expect.poll(async () => {
-    const sheetVisible = await sheet.isVisible().catch(() => false);
-    const backdropVisible = await backdrop.isVisible().catch(() => false);
-    // Also check if branch name is visible directly
-    const branchVisible = await page.getByText(branchName, { exact: true }).first().isVisible().catch(() => false);
-    return sheetVisible || backdropVisible || branchVisible;
-  }, { timeout: 10000 }).toBeTruthy();
-  const sheetVisible = await sheet.isVisible().catch(() => false);
-  const scope = sheetVisible ? sheet : page;
-  const preferredOption = scope.getByText(branchName, { exact: true }).first();
-  if (await preferredOption.isVisible().catch(() => false)) {
-    await preferredOption.click();
-    await expect(picker).toContainText(branchName);
-    return;
-  }
-
-  const options = scope.locator('[data-testid^="worktree-attach-option-"]');
-  const optionCount = await options.count();
-  if (optionCount === 0) {
-    throw new Error(`No worktree options were available in the attach picker`);
-  }
-  const fallbackOption = options.first();
-  const fallbackLabel = ((await fallbackOption.innerText()) ?? "").trim();
-  await fallbackOption.click();
-  if (fallbackLabel.length > 0) {
-    await expect(picker).toContainText(fallbackLabel);
-  }
-}
-
-async function enableCreateWorktree(page: Page) {
-  const createToggle = page.getByTestId('worktree-create-toggle');
-  const willCreateLabel = page.getByText(/Will create:/);
-  if (await willCreateLabel.isVisible()) {
-    return;
-  }
-  const readyLabel = page.getByText(
-    /Run isolated from|Run in an isolated directory/
-  );
-  await expect(readyLabel).toBeVisible({ timeout: 30000 });
-  await createToggle.click({ force: true });
-  await expect(willCreateLabel).toBeVisible({ timeout: 30000 });
-}
-
-async function refreshUncommittedMode(page: Page) {
-  await selectChangesView(page, 'base');
-  await selectChangesView(page, 'working');
-}
-
-async function refreshChangesTab(page: Page) {
-  const header = page.locator('[data-testid="explorer-header"]:visible').first();
-  await header.getByText('Files', { exact: true }).first().click();
-  await header.getByText('Changes', { exact: true }).first().click();
-}
-
-function normalizeTmpPath(value: string) {
-  if (value.startsWith('/var/')) {
-    return `/private${value}`;
-  }
-  return value;
-}
-
-test('checkout-first Changes panel ship loop', async ({ page }) => {
-  const repo = await createTempGitRepo('paseo-e2e-', { withRemote: true });
-  const nonGitDir = await mkdtemp(path.join(tmpdir(), 'paseo-e2e-non-git-'));
-
-  try {
-    await gotoHome(page);
-    await setWorkingDirectory(page, repo.path);
-    await ensureHostSelected(page);
-
-    await enableCreateWorktree(page);
-    await createAgentAndWait(page, 'Respond with exactly: READY');
-    await waitForAssistantText(page, 'READY');
-
-    await openChangesPanel(page);
-    const branchLabelLocator = getChangesScope(page).getByTestId('changes-branch');
-    await expect
-      .poll(async () => (await branchLabelLocator.innerText()).trim(), { timeout: 30000 })
-      .not.toBe('Unknown');
-    const branchNameFromUi = (await branchLabelLocator.innerText()).trim();
-    expect(branchNameFromUi.length).toBeGreaterThan(0);
-
-    const firstCwd = await requestCwd(page);
-    const worktreeBranch = execSync('git rev-parse --abbrev-ref HEAD', {
-      cwd: firstCwd,
-      encoding: 'utf8',
-    }).trim();
-    expect(worktreeBranch.length).toBeGreaterThan(0);
-    const [resolvedCwd, resolvedRepo] = await Promise.all([
-      realpath(firstCwd).catch(() => firstCwd),
-      realpath(repo.path).catch(() => repo.path),
-    ]);
-    const normalizedRepo = normalizeTmpPath(resolvedRepo);
-    const normalizedCwd = normalizeTmpPath(resolvedCwd);
-    const expectedMarker = `${path.sep}worktrees${path.sep}`;
-    expect(normalizedCwd.includes(expectedMarker)).toBeTruthy();
-
-    await page.getByTestId('sidebar-new-agent').click();
-    await expect(page).toHaveURL(/\/agent\/?$/);
-
-    await setWorkingDirectory(page, repo.path);
-    await ensureHostSelected(page);
-    await selectAttachWorktree(page, worktreeBranch);
-    await createAgentAndWait(page, 'Respond with exactly: READY2');
-    await waitForAssistantText(page, 'READY2');
-
-    const secondCwd = await requestCwd(page);
-    expect(secondCwd).toBe(firstCwd);
-
-    await sendPrompt(page, "Respond with exactly: OK");
-    await waitForAssistantText(page, "OK");
-
-    const readmePath = path.join(firstCwd, 'README.md');
-    await appendFile(readmePath, '\nFirst change\n');
-
-    await refreshUncommittedMode(page);
-    await expect(getChangesScope(page).getByText('README.md', { exact: true })).toBeVisible({
-      timeout: 30000,
-    });
-    await getChangesScope(page).getByTestId('diff-file-0-toggle').first().click();
-    await expect(page.getByText('First change')).toBeVisible();
-    const primaryCta = getChangesScope(page).getByTestId('changes-primary-cta').first();
-    await expect(primaryCta).toBeVisible();
-    await expect(primaryCta).toContainText('Commit');
-
-    await primaryCta.click();
-    await expect
-      .poll(() => {
-        try {
-          return execSync('git status --porcelain', {
-            cwd: firstCwd,
-            encoding: 'utf8',
-            env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' },
-          }).trim();
-        } catch {
-          return null;
-        }
-      }, { timeout: 30000 })
-      .toBe('');
-    await openChangesPanel(page);
-    await selectChangesView(page, 'working');
-    await expect(getChangesScope(page).getByText('No uncommitted changes')).toBeVisible({
-      timeout: 30000,
-    });
-    await expect(getChangesScope(page).getByTestId('changes-primary-cta')).not.toContainText('Commit');
-
-    await selectChangesView(page, 'base');
-    await expect(getChangesScope(page).getByText('README.md', { exact: true })).toBeVisible({
-      timeout: 30000,
-    });
-
-    // Push once from the menu so the branch has an origin/<branch> ref.
-    await openChangesPrimaryMenu(page);
-    await page.getByTestId('changes-menu-push').click();
-    await expect
-      .poll(() => {
-        try {
-          execSync(`git show-ref --verify --quiet refs/remotes/origin/${worktreeBranch}`, { cwd: firstCwd });
-          return true;
-        } catch {
-          return false;
-        }
-      }, { timeout: 30000 })
-      .toBe(true);
-
-    const notesPath = path.join(firstCwd, 'notes.txt');
-    await writeFile(notesPath, 'Second change\n');
-
-    await refreshUncommittedMode(page);
-    await refreshChangesTab(page);
-    await expect(getChangesScope(page).getByText('notes.txt', { exact: true })).toBeVisible({
-      timeout: 30000,
-    });
-    await expect(getChangesScope(page).getByText('README.md', { exact: true })).toHaveCount(0);
-    await expect(getChangesScope(page).getByTestId('changes-primary-cta')).toContainText('Commit');
-
-    await selectChangesView(page, 'base');
-    await expect(getChangesScope(page).getByText('README.md', { exact: true })).toBeVisible({
-      timeout: 30000,
-    });
-
-    await getChangesScope(page).getByTestId('changes-primary-cta').click();
-    await expect
-      .poll(() => {
-        try {
-          return execSync('git status --porcelain', {
-            cwd: firstCwd,
-            encoding: 'utf8',
-            env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' },
-          }).trim();
-        } catch {
-          return null;
-        }
-      }, { timeout: 30000 })
-      .toBe('');
-    await openChangesPanel(page);
-    await selectChangesView(page, 'working');
-    await expect(getChangesScope(page).getByText('No uncommitted changes')).toBeVisible({ timeout: 30000 });
-    await expect(getChangesScope(page).getByTestId('changes-primary-cta')).not.toContainText('Commit');
-
-    await selectChangesView(page, 'base');
-    await expect(getChangesScope(page).getByText('README.md', { exact: true })).toBeVisible({
-      timeout: 30000,
-    });
-    await expect(getChangesScope(page).getByText('notes.txt', { exact: true })).toBeVisible({
-      timeout: 30000,
-    });
-
-    // Push is now the primary action (origin/<branch> exists and we're ahead of it).
-    const pushPrimary = getChangesScope(page).getByTestId('changes-primary-cta').first();
-    await expect(pushPrimary).toContainText(/push/i, { timeout: 30000 });
-    await pushPrimary.click();
-    // Regression check: the primary CTA stays in place while pushing.
-    await expect(pushPrimary).toBeVisible();
-    await page.waitForTimeout(50);
-    await expect(pushPrimary).toBeVisible();
-
-    await expect
-      .poll(() => {
-        try {
-          const count = execSync(
-            `git rev-list --count origin/${worktreeBranch}..${worktreeBranch}`,
-            { cwd: firstCwd, encoding: 'utf8' }
-          ).trim();
-          return Number.parseInt(count, 10);
-        } catch {
-          return null;
-        }
-      }, { timeout: 30000 })
-      .toBe(0);
-
-    // Merge to base in the main worktree (worktree branches can't always check out base refs in-place).
-    // This avoids UI flakiness around ship actions while still validating the diff panel end-to-end.
-    execSync("git checkout main", { cwd: repo.path });
-    execSync(`git -c commit.gpgsign=false merge --no-edit ${worktreeBranch}`, { cwd: repo.path });
-    execSync("git push", { cwd: repo.path });
-
-    await selectChangesView(page, 'base');
-    await expect(getChangesScope(page).getByText(/No changes vs/i)).toBeVisible({
-      timeout: 60000,
-    });
-    await refreshChangesTab(page);
-    await expect(getChangesScope(page).getByTestId('changes-primary-cta')).toHaveCount(0, { timeout: 30000 });
-
-    await openChangesOverflowMenu(page);
-    await expect(page.getByTestId('changes-menu-archive-worktree')).toBeVisible();
-    await page.getByTestId('changes-menu-archive-worktree').click();
-    // Archiving a worktree deletes agents and redirects to home
-    await expect(page).toHaveURL(/\/agent\/?$/, { timeout: 30000 });
-    await setWorkingDirectory(page, repo.path);
-    await ensureHostSelected(page);
-    // Repo inspection is async; wait until git options are interactive again.
-    await expect(page.getByText('Inspecting repository…')).toHaveCount(0, { timeout: 30000 });
-    await page.getByTestId('worktree-attach-toggle').click();
-    await expect(page.getByTestId('worktree-attach-picker')).toBeVisible({ timeout: 30000 });
-    await page.getByTestId('worktree-attach-picker').click();
-    await expect(page.getByText(worktreeBranch, { exact: true })).toHaveCount(0);
-    const attachSheet = page.getByLabel('Bottom Sheet', { exact: true });
-    if (await attachSheet.isVisible().catch(() => false)) {
-      await page.getByTestId('dropdown-sheet-close').click({ force: true });
-      await expect(attachSheet).toBeHidden({ timeout: 30000 });
-    }
-    await page.getByTestId('worktree-attach-toggle').click();
-    await expect(page.getByTestId('worktree-attach-picker')).toBeHidden({ timeout: 30000 });
-
-    await setWorkingDirectory(page, nonGitDir);
-    // Wait for git options to disappear (repo inspection is async and the git section can briefly render stale UI).
-    await expect(page.getByTestId('worktree-attach-toggle')).toHaveCount(0, { timeout: 30000 });
-    await expect(page.getByTestId('worktree-attach-picker')).toHaveCount(0);
-    await createAgentAndWait(page, 'Respond with exactly: NON-GIT');
-    await waitForAssistantText(page, 'NON-GIT');
-    await openChangesPanel(page, { expectGit: false });
-    await expect(getChangesScope(page).getByTestId('changes-not-git')).toBeVisible();
-    await expect(getChangesScope(page).getByTestId('changes-primary-cta')).toHaveCount(0);
-    await expect(getChangesScope(page).getByTestId('changes-overflow-menu')).toHaveCount(0);
-  } finally {
-    await rm(nonGitDir, { recursive: true, force: true });
-    await repo.cleanup();
-  }
-});

packages/app/e2e/create-agent.spec.ts

@@ -1,29 +0,0 @@
-import { test, expect } from './fixtures';
-import { createAgent, ensureHostSelected, gotoHome, setWorkingDirectory } from './helpers/app';
-import { createTempGitRepo } from './helpers/workspace';
-
-test('create agent in a temp repo', async ({ page }) => {
-  const repo = await createTempGitRepo();
-  const prompt = "Respond with exactly: Hello";
-
-  try {
-    await gotoHome(page);
-    await setWorkingDirectory(page, repo.path);
-    await ensureHostSelected(page);
-    await createAgent(page, prompt);
-
-    // Verify user message is shown in the stream
-    await expect(page.getByText(prompt, { exact: true })).toBeVisible();
-
-    // Verify we used a fast model (do not fall back to a default like Sonnet).
-    await page.getByTestId('agent-overflow-menu').click();
-    await expect(page.getByText('Model', { exact: true })).toBeVisible();
-    await expect(page.getByTestId('agent-overflow-content').getByText(/haiku/i)).toBeVisible();
-
-    // Wait for agent response containing "Hello" within an assistant message
-    const assistantMessage = page.getByTestId('assistant-message').filter({ hasText: 'Hello' });
-    await expect(assistantMessage).toBeVisible({ timeout: 30000 });
-  } finally {
-    await repo.cleanup();
-  }
-});

packages/app/e2e/daemon-connectivity.spec.ts

@@ -1,19 +0,0 @@
-import { test, expect } from './fixtures';
-import { gotoHome, openSettings } from './helpers/app';
-
-test('daemon is connected in settings', async ({ page }) => {
-  const daemonPort = process.env.E2E_DAEMON_PORT;
-  const serverId = process.env.E2E_SERVER_ID;
-  if (!daemonPort) {
-    throw new Error('E2E_DAEMON_PORT is not set (expected from globalSetup).');
-  }
-  if (!serverId) {
-    throw new Error('E2E_SERVER_ID is not set (expected from globalSetup).');
-  }
-
-  await gotoHome(page);
-  await openSettings(page);
-
-  await expect(page.getByText(`127.0.0.1:${daemonPort}`)).toBeVisible();
-  await expect(page.getByTestId(`daemon-card-${serverId}`).getByText('Online', { exact: true })).toBeVisible();
-});

packages/app/e2e/delete-agent-persists.spec.ts

@@ -1,55 +0,0 @@
-import { test, expect } from './fixtures';
-import { ensureHostSelected, gotoHome, setWorkingDirectory } from './helpers/app';
-import { createTempGitRepo } from './helpers/workspace';
-
-test('deleting an agent persists after reload', async ({ page }) => {
-  const repo = await createTempGitRepo();
-  const nonce = Math.random().toString(36).slice(2, 10);
-  const prompt = `respond-ready-${nonce}`;
-
-  try {
-    await gotoHome(page);
-    await setWorkingDirectory(page, repo.path);
-    await ensureHostSelected(page);
-
-    // Create agent (via message input) so it shows up in the sidebar list.
-    const input = page.getByRole('textbox', { name: 'Message agent...' });
-    await expect(input).toBeEditable();
-    await input.fill(prompt);
-    await input.press('Enter');
-    await page.waitForURL(/\/agent\//, { waitUntil: 'commit' });
-    // Wait for the initial turn to complete so the agent can be archived (web uses a hover action).
-    const stopOrCancel = page.getByRole('button', { name: /Stop agent|Canceling agent/ });
-    await stopOrCancel.first().waitFor({ state: 'visible', timeout: 30000 }).catch(() => undefined);
-    await expect(stopOrCancel).toHaveCount(0, { timeout: 120000 });
-
-    const match = page.url().match(/\/agent\/([^/]+)\/([^/?#]+)/);
-    if (!match) {
-      throw new Error(`Expected /agent/:serverId/:agentId URL, got ${page.url()}`);
-    }
-    const serverId = decodeURIComponent(match[1]);
-    const agentId = decodeURIComponent(match[2]);
-
-    // Return home and delete via long-press in the agent list.
-    await gotoHome(page);
-    const rowTestId = `agent-row-${serverId}-${agentId}`;
-    const agentRow = page.getByTestId(rowTestId).first();
-    await expect(agentRow).toBeVisible({ timeout: 30000 });
-
-    // Web UX: hover shows a quick-archive icon. (Long-press is touch-oriented and unreliable on desktop web.)
-    await agentRow.hover();
-    const quickArchive = page.getByTestId(`agent-archive-${serverId}-${agentId}`).first();
-    await expect(quickArchive).toBeVisible({ timeout: 10000 });
-    await quickArchive.click({ force: true });
-
-    // Ensure deletion finished before reload (avoids races).
-    await expect(page.getByTestId(rowTestId)).toHaveCount(0, { timeout: 30000 });
-
-    // A full reload should not bring the agent back.
-    await page.reload();
-    await expect(page.getByRole('textbox', { name: 'Message agent...' })).toBeVisible();
-    await expect(page.getByTestId(rowTestId)).toHaveCount(0, { timeout: 30000 });
-  } finally {
-    await repo.cleanup();
-  }
-});

packages/app/e2e/dictation-web.spec.ts

@@ -1,227 +0,0 @@
-import { test, expect } from './fixtures';
-import { createAgent, ensureHostSelected, gotoHome, setWorkingDirectory } from './helpers/app';
-import { createTempGitRepo } from './helpers/workspace';
-import type { Page } from '@playwright/test';
-import { readFile } from 'node:fs/promises';
-import path from 'node:path';
-
-async function addFakeMicrophone(page: Page) {
-  const fixturePath = path.resolve(__dirname, 'fixtures', 'recording.webm');
-  const base64Audio = (await readFile(fixturePath)).toString('base64');
-  const mimeType = 'audio/webm;codecs=opus';
-
-  return page.addInitScript(({ base64Audio, mimeType }) => {
-    const mic = {
-      active: 0,
-      getUserMediaCalls: 0,
-      stopCalls: 0,
-      lastRecorder: null as null | { state: string },
-    };
-    (window as any).__mic = mic;
-
-    (window as any).isSecureContext = true;
-
-    const nav = navigator as any;
-    if (!nav.mediaDevices) {
-      nav.mediaDevices = {};
-    }
-    nav.mediaDevices.getUserMedia = async () => {
-      mic.getUserMediaCalls += 1;
-      mic.active += 1;
-      const track = {
-        stop: () => {
-          mic.stopCalls += 1;
-          mic.active = Math.max(0, mic.active - 1);
-        },
-      };
-      return {
-        getTracks: () => [track],
-      };
-    };
-
-    const blobFromBase64 = (base64: string, mimeType: string): Blob => {
-      const binaryString = atob(base64);
-      const bytes = new Uint8Array(binaryString.length);
-      for (let i = 0; i < binaryString.length; i++) {
-        bytes[i] = binaryString.charCodeAt(i);
-      }
-      return new Blob([bytes], { type: mimeType });
-    };
-
-    class FakeMediaRecorder extends EventTarget {
-      public static isTypeSupported() {
-        return true;
-      }
-
-      public state: 'inactive' | 'recording' = 'inactive';
-      public mimeType: string;
-      public ondataavailable: ((event: { data: Blob }) => void) | null = null;
-      public onerror: ((event: unknown) => void) | null = null;
-
-      constructor(_stream: unknown, options?: MediaRecorderOptions) {
-        super();
-        this.mimeType = options?.mimeType ?? 'audio/webm';
-        mic.lastRecorder = this;
-      }
-
-      public start() {
-        this.state = 'recording';
-      }
-
-      public stop() {
-        if (this.state !== 'recording') {
-          throw new Error('Not recording');
-        }
-        this.state = 'inactive';
-        try {
-          this.ondataavailable?.({
-            data: blobFromBase64(base64Audio, mimeType),
-          });
-        } catch (err) {
-          this.onerror?.(err);
-        }
-        this.dispatchEvent(new Event('stop'));
-      }
-    }
-
-    (window as any).MediaRecorder = FakeMediaRecorder;
-  }, { base64Audio, mimeType });
-}
-
-test('dictation hotkeys do not trigger on background screens', async ({ page }) => {
-  await addFakeMicrophone(page);
-
-  const repo = await createTempGitRepo();
-  try {
-    await gotoHome(page);
-    await ensureHostSelected(page);
-    await setWorkingDirectory(page, repo.path);
-    await createAgent(page, 'Respond with exactly: Hello');
-
-    await expect(page).toHaveURL(/\/agent\//);
-    await expect(page.getByRole('textbox', { name: 'Message agent...' })).toBeEditable();
-
-    await page.keyboard.press('Control+d');
-    await page.waitForTimeout(200);
-
-    const calls = await page.evaluate(() => (window as any).__mic.getUserMediaCalls as number);
-    const active = await page.evaluate(() => (window as any).__mic.active as number);
-
-    expect(calls).toBe(1);
-    expect(active).toBe(1);
-
-    await page.keyboard.press('Escape');
-    await expect
-      .poll(async () => page.evaluate(() => (window as any).__mic.active as number))
-      .toBe(0);
-  } finally {
-    await repo.cleanup();
-  }
-});
-
-test('dictation transcribes fixture via real STT', async ({ page }) => {
-  await addFakeMicrophone(page);
-
-  const repo = await createTempGitRepo();
-  try {
-    await gotoHome(page);
-    await ensureHostSelected(page);
-    await setWorkingDirectory(page, repo.path);
-    await createAgent(page, 'Respond with exactly: Hello');
-
-    await expect(page).toHaveURL(/\/agent\//);
-    await expect(page.getByRole('textbox', { name: 'Message agent...' })).toBeEditable();
-
-    await page.keyboard.press('Control+d');
-    await expect
-      .poll(async () => page.evaluate(() => (window as any).__mic.active as number))
-      .toBe(1);
-
-    const initialCopyMessageCount = await page
-      .getByRole('button', { name: 'Copy message' })
-      .count();
-
-    await page.keyboard.press('Control+d');
-
-    await expect
-      .poll(
-        async () => page.getByRole('button', { name: 'Copy message' }).count(),
-        { timeout: 60_000 }
-      )
-      .toBeGreaterThan(initialCopyMessageCount);
-  } finally {
-    await repo.cleanup();
-  }
-});
-
-test('cancel stops mic even if recorder is already inactive', async ({ page }) => {
-  await addFakeMicrophone(page);
-
-  const repo = await createTempGitRepo();
-  try {
-    await gotoHome(page);
-    await ensureHostSelected(page);
-    await setWorkingDirectory(page, repo.path);
-    await createAgent(page, 'Respond with exactly: Hello');
-
-    await expect(page).toHaveURL(/\/agent\//);
-    await expect(page.getByRole('textbox', { name: 'Message agent...' })).toBeEditable();
-
-    await page.keyboard.press('Control+d');
-    await expect
-      .poll(async () => page.evaluate(() => (window as any).__mic.active as number))
-      .toBe(1);
-
-    await page.evaluate(() => {
-      const mic = (window as any).__mic as { lastRecorder: null | { state: string } };
-      if (mic.lastRecorder) {
-        mic.lastRecorder.state = 'inactive';
-      }
-    });
-
-    await page.keyboard.press('Escape');
-    await expect
-      .poll(async () => page.evaluate(() => (window as any).__mic.active as number))
-      .toBe(0);
-  } finally {
-    await repo.cleanup();
-  }
-});
-
-test('dictation confirm+send does not dispatch after navigating away', async ({ page }) => {
-  await addFakeMicrophone(page);
-
-  const repo = await createTempGitRepo();
-  try {
-    await gotoHome(page);
-    await setWorkingDirectory(page, repo.path);
-    await ensureHostSelected(page);
-    await createAgent(page, 'Respond with exactly: Hello');
-
-    await expect(page).toHaveURL(/\/agent($|\/)/);
-    await expect(page.getByRole('textbox', { name: 'Message agent...' })).toBeEditable();
-
-    await page.keyboard.press('Control+d');
-    await expect
-      .poll(async () => page.evaluate(() => (window as any).__mic.active as number))
-      .toBe(1);
-
-    await page.keyboard.press('Control+d');
-
-    const newAgentButton = page.getByTestId('sidebar-new-agent');
-    await expect(newAgentButton).toBeVisible();
-    await newAgentButton.click();
-    await expect(page).toHaveURL(/\/agent\/?$/);
-
-    await page.waitForTimeout(10_000);
-
-    const agentEntry = page.getByText(repo.path).first();
-    await expect(agentEntry).toBeVisible();
-    await agentEntry.click();
-    await expect(page).toHaveURL(/\/agent($|\/)/);
-
-    await expect(page.getByText(/voice note/i)).not.toBeVisible();
-  } finally {
-    await repo.cleanup();
-  }
-});

packages/app/e2e/fixtures.ts

@@ -1,11 +1,12 @@
-import { test as base, expect, type Page } from '@playwright/test';
+import { test as base, expect, type Page } from "@playwright/test";
+import { buildCreateAgentPreferences, buildSeededHost } from "./helpers/daemon-registry";
 
 // Extend base test to provide dynamic baseURL from global-setup
 const test = base.extend({
   baseURL: async ({}, use) => {
     const metroPort = process.env.E2E_METRO_PORT;
     if (!metroPort) {
-      throw new Error('E2E_METRO_PORT not set - globalSetup must run first');
+      throw new Error("E2E_METRO_PORT not set - globalSetup must run first");
     }
     await use(`http://localhost:${metroPort}`);
   },
@@ -18,19 +19,19 @@ test.beforeEach(async ({ page }) => {
   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.'
+      "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') {
+  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.'
+      "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.'
+      "E2E_METRO_PORT is not set. Ensure Playwright `globalSetup` starts Metro and exports E2E_METRO_PORT.",
     );
   }
 
@@ -38,17 +39,17 @@ test.beforeEach(async ({ page }) => {
   // This blocks both HTTP and WS attempts to :6767 (before any navigation).
   await page.route(/:(6767)\b/, (route) => route.abort());
   await page.routeWebSocket(/:(6767)\b/, async (ws) => {
-    await ws.close({ code: 1008, reason: 'Blocked connection to localhost:6767 during e2e.' });
+    await ws.close({ code: 1008, reason: "Blocked connection to localhost:6767 during e2e." });
   });
 
   const entries: string[] = [];
   consoleEntries.set(page, entries);
 
-  page.on('console', (message) => {
+  page.on("console", (message) => {
     entries.push(`[console:${message.type()}] ${message.text()}`);
   });
 
-  page.on('pageerror', (error) => {
+  page.on("pageerror", (error) => {
     entries.push(`[pageerror] ${error.message}`);
   });
 
@@ -56,40 +57,21 @@ test.beforeEach(async ({ page }) => {
   const seedNonce = Math.random().toString(36).slice(2);
   const serverId = process.env.E2E_SERVER_ID;
   if (!serverId) {
-    throw new Error('E2E_SERVER_ID is not set - expected from Playwright globalSetup.');
+    throw new Error("E2E_SERVER_ID is not set - expected from Playwright globalSetup.");
   }
-  const testDaemon = {
+  const testDaemon = buildSeededHost({
     serverId,
-    label: 'localhost',
-    connections: [
-      {
-        id: `direct:127.0.0.1:${daemonPort}`,
-        type: 'direct',
-        endpoint: `127.0.0.1:${daemonPort}`,
-      },
-    ],
-    preferredConnectionId: `direct:127.0.0.1:${daemonPort}`,
-    createdAt: nowIso,
-    updatedAt: nowIso,
-  };
-
-  const createAgentPreferences = {
-    // Ensure create flow never uses a remembered host from the developer's real app.
-    serverId: testDaemon.serverId,
-    // Keep e2e fast/cheap by default.
-    provider: 'claude',
-    providerPreferences: {
-      claude: { model: 'haiku' },
-      codex: { model: 'gpt-5.1-codex-mini' },
-    },
-  };
+    endpoint: `127.0.0.1:${daemonPort}`,
+    nowIso,
+  });
+  const createAgentPreferences = buildCreateAgentPreferences(testDaemon.serverId);
 
   await page.addInitScript(
     ({ daemon, preferences, seedNonce }) => {
       // `addInitScript` runs on every navigation (including reloads). Some tests intentionally
       // override storage and reload; they can opt out of seeding for the *next* navigation by
       // setting this flag before the reload.
-      const disableOnceKey = '@paseo:e2e-disable-default-seed-once';
+      const disableOnceKey = "@paseo:e2e-disable-default-seed-once";
       const disableValue = localStorage.getItem(disableOnceKey);
       if (disableValue) {
         localStorage.removeItem(disableOnceKey);
@@ -98,15 +80,15 @@ test.beforeEach(async ({ page }) => {
         }
       }
 
-      localStorage.setItem('@paseo:e2e', '1');
-      localStorage.setItem('@paseo:e2e-seed-nonce', seedNonce);
+      localStorage.setItem("@paseo:e2e", "1");
+      localStorage.setItem("@paseo:e2e-seed-nonce", seedNonce);
 
       // Hard-reset anything that could point to a developer's real daemon.
-      localStorage.setItem('@paseo:daemon-registry', JSON.stringify([daemon]));
-      localStorage.removeItem('@paseo:settings');
-      localStorage.setItem('@paseo:create-agent-preferences', JSON.stringify(preferences));
+      localStorage.setItem("@paseo:daemon-registry", JSON.stringify([daemon]));
+      localStorage.removeItem("@paseo:settings");
+      localStorage.setItem("@paseo:create-agent-preferences", JSON.stringify(preferences));
     },
-    { daemon: testDaemon, preferences: createAgentPreferences, seedNonce }
+    { daemon: testDaemon, preferences: createAgentPreferences, seedNonce },
   );
 });
 
@@ -120,9 +102,9 @@ test.afterEach(async ({ page }, testInfo) => {
     return;
   }
 
-  await testInfo.attach('browser-console', {
-    body: entries.join('\n'),
-    contentType: 'text/plain',
+  await testInfo.attach("browser-console", {
+    body: entries.join("\n"),
+    contentType: "text/plain",
   });
 });
 

packages/app/e2e/git-diff-sticky-headers.spec.ts

@@ -1,99 +0,0 @@
-import path from 'node:path';
-import { appendFile } from 'node:fs/promises';
-import { test, expect, type Page } from './fixtures';
-import { ensureHostSelected, gotoHome, setWorkingDirectory } from './helpers/app';
-import { createTempGitRepo } from './helpers/workspace';
-
-test.describe.configure({ timeout: 90000 });
-
-function getChangesScope(page: Page) {
-  return page.locator('[data-testid="explorer-content-area"]:visible').first();
-}
-
-async function openChangesPanel(page: Page) {
-  const changesHeader = getChangesScope(page).getByTestId('changes-header');
-  if (!(await changesHeader.isVisible())) {
-    const explorerHeader = page.getByTestId('explorer-header');
-    if (await explorerHeader.isVisible()) {
-      await page.getByText('Changes', { exact: true }).click();
-    } else {
-      const overflowMenu = page.getByTestId('agent-overflow-menu').first();
-      await expect(overflowMenu).toBeVisible({ timeout: 10000 });
-      await overflowMenu.click();
-      await page.getByText('View Changes', { exact: true }).click();
-    }
-  }
-  await expect(changesHeader).toBeVisible();
-}
-
-async function refreshUncommittedMode(page: Page) {
-  const scope = getChangesScope(page);
-  const toggle = scope.getByTestId('changes-diff-status').first();
-  await expect(toggle).toBeVisible({ timeout: 30000 });
-
-  const currentLabel = (await toggle.innerText()).trim();
-  await toggle.click();
-  await expect.poll(async () => (await toggle.innerText()).trim()).not.toBe(currentLabel);
-
-  const nextLabel = (await toggle.innerText()).trim();
-  await toggle.click();
-  await expect.poll(async () => (await toggle.innerText()).trim()).not.toBe(nextLabel);
-}
-
-async function createAgentAndWait(page: Page, message: string) {
-  const input = page.getByRole('textbox', { name: 'Message agent...' });
-  await expect(input).toBeEditable();
-  await input.fill(message);
-  await input.press('Enter');
-  await expect(page).toHaveURL(/\/agent\//, { timeout: 120000 });
-  await expect(page.getByText(message, { exact: true })).toBeVisible();
-}
-
-test('keeps file header sticky while scrolling within a long diff', async ({ page }) => {
-  const repo = await createTempGitRepo('paseo-e2e-sticky-');
-
-  try {
-    await gotoHome(page);
-    await setWorkingDirectory(page, repo.path);
-    await ensureHostSelected(page);
-    await createAgentAndWait(page, 'Respond with exactly: READY');
-
-    await openChangesPanel(page);
-
-    const readmePath = path.join(repo.path, 'README.md');
-    const lines = Array.from({ length: 400 }, (_, idx) => `Sticky header line ${idx}\n`).join('');
-    await appendFile(readmePath, `\n${lines}`);
-
-    await refreshUncommittedMode(page);
-
-    const scope = getChangesScope(page);
-    await expect(scope.getByText('README.md', { exact: true })).toBeVisible({ timeout: 30000 });
-
-    const fileToggle = scope.getByTestId('diff-file-0-toggle').first();
-    await fileToggle.click();
-
-    const markerLine = scope.getByText('Sticky header line 250').first();
-    await expect(markerLine).toBeVisible({ timeout: 30000 });
-
-    const scroll = scope.getByTestId('git-diff-scroll').first();
-    await expect(scroll).toBeVisible();
-
-    await expect.poll(async () => {
-      return await scroll.evaluate((el) => (el.scrollHeight ?? 0) > (el.clientHeight ?? 0));
-    }).toBe(true);
-
-    await scroll.hover();
-    for (let i = 0; i < 12; i++) {
-      await page.mouse.wheel(0, 700);
-    }
-
-    await expect.poll(async () => {
-      return await scroll.evaluate((el) => el.scrollTop ?? 0);
-    }).toBeGreaterThan(0);
-
-    await expect(scope.getByText('Sticky header line 390').first()).toBeVisible({ timeout: 30000 });
-    await expect(fileToggle).toBeVisible();
-  } finally {
-    await repo.cleanup();
-  }
-});

packages/app/e2e/global-setup.ts

@@ -1,20 +1,28 @@
-import { spawn, type ChildProcess, execSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { mkdtemp, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import path from 'node:path';
-import net from 'node:net';
-import { Buffer } from 'node:buffer';
-import dotenv from 'dotenv';
+import { spawn, type ChildProcess, execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import net from "node:net";
+import { Buffer } from "node:buffer";
+import dotenv from "dotenv";
+
+type WaitForServerOptions = {
+  host?: string;
+  timeoutMs?: number;
+  label: string;
+  childProcess?: ChildProcess | null;
+  getRecentOutput?: () => string;
+};
 
 async function getAvailablePort(): Promise<number> {
   return new Promise((resolve, reject) => {
     const server = net.createServer();
-    server.once('error', reject);
+    server.once("error", reject);
     server.listen(0, () => {
       const address = server.address();
-      if (!address || typeof address === 'string') {
-        server.close(() => reject(new Error('Failed to acquire port')));
+      if (!address || typeof address === "string") {
+        server.close(() => reject(new Error("Failed to acquire port")));
         return;
       }
       server.close(() => resolve(address.port));
@@ -22,23 +30,153 @@ async function getAvailablePort(): Promise<number> {
   });
 }
 
-async function waitForServer(port: number, timeout = 15000): Promise<void> {
+function createLineBuffer(maxLines = 120): { add: (line: string) => void; dump: () => string } {
+  const lines: string[] = [];
+  return {
+    add(line: string) {
+      lines.push(line);
+      if (lines.length > maxLines) {
+        lines.shift();
+      }
+    },
+    dump() {
+      return lines.join("\n");
+    },
+  };
+}
+
+function formatRecentOutput(getRecentOutput?: () => string): string {
+  if (!getRecentOutput) {
+    return "";
+  }
+  const output = getRecentOutput().trim();
+  if (!output) {
+    return "";
+  }
+  return `\nRecent output:\n${output}`;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitForServer(port: number, options: WaitForServerOptions): Promise<void> {
+  const { host = "127.0.0.1", timeoutMs = 15000, label, childProcess, getRecentOutput } = options;
   const start = Date.now();
-  while (Date.now() - start < timeout) {
+  let lastConnectionError: unknown = null;
+
+  while (Date.now() - start < timeoutMs) {
+    if (childProcess && childProcess.exitCode !== null) {
+      const signal = childProcess.signalCode ? `, signal ${childProcess.signalCode}` : "";
+      throw new Error(
+        `${label} exited before listening on ${host}:${port} (exit code ${childProcess.exitCode}${signal}).${formatRecentOutput(getRecentOutput)}`,
+      );
+    }
+
     try {
       await new Promise<void>((resolve, reject) => {
-        const socket = net.connect(port, 'localhost', () => {
+        const socket = net.connect(port, host, () => {
           socket.end();
           resolve();
         });
-        socket.on('error', reject);
+        socket.setTimeout(1000, () => {
+          socket.destroy();
+          reject(new Error(`Connection timed out to ${host}:${port}`));
+        });
+        socket.on("error", reject);
       });
       return;
-    } catch {
+    } catch (error) {
+      lastConnectionError = error;
       await new Promise((r) => setTimeout(r, 100));
     }
   }
-  throw new Error(`Server did not start on port ${port} within ${timeout}ms`);
+
+  const reason =
+    lastConnectionError instanceof Error
+      ? ` Last connection error: ${lastConnectionError.message}`
+      : "";
+  throw new Error(
+    `${label} did not start on ${host}:${port} within ${timeoutMs}ms.${reason}${formatRecentOutput(getRecentOutput)}`,
+  );
+}
+
+function parseRelayStartupFailure(line: string): string | null {
+  const clean = stripAnsi(line);
+  if (/Address already in use/i.test(clean)) {
+    return clean;
+  }
+  if (/failed: ::bind\(/i.test(clean)) {
+    return clean;
+  }
+  if (/Fatal uncaught/i.test(clean)) {
+    return clean;
+  }
+  return null;
+}
+
+async function stopProcess(child: ChildProcess | null): Promise<void> {
+  if (!child) {
+    return;
+  }
+  if (child.exitCode !== null || child.signalCode !== null) {
+    return;
+  }
+  child.kill("SIGTERM");
+  await new Promise<void>((resolve) => {
+    const timeout = setTimeout(() => {
+      if (child.exitCode === null && child.signalCode === null) {
+        child.kill("SIGKILL");
+      }
+      resolve();
+    }, 5000);
+    child.once("exit", () => {
+      clearTimeout(timeout);
+      resolve();
+    });
+  });
+}
+
+function summarizeOpenAiErrorBody(body: string): string {
+  const trimmed = body.trim();
+  if (!trimmed) {
+    return "empty response body";
+  }
+  if (trimmed.length <= 240) {
+    return trimmed;
+  }
+  return `${trimmed.slice(0, 240)}…`;
+}
+
+async function isOpenAiApiKeyUsable(apiKey: string | undefined): Promise<boolean> {
+  const key = apiKey?.trim();
+  if (!key) {
+    return false;
+  }
+
+  try {
+    const response = await fetch("https://api.openai.com/v1/models?limit=1", {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${key}`,
+      },
+    });
+    if (response.ok) {
+      return true;
+    }
+    const body = await response.text();
+    console.warn(
+      `[e2e] OPENAI_API_KEY probe failed (${response.status}): ${summarizeOpenAiErrorBody(body)}`,
+    );
+    return false;
+  } catch (error) {
+    console.warn(
+      `[e2e] OPENAI_API_KEY probe request failed: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+    return false;
+  }
 }
 
 let daemonProcess: ChildProcess | null = null;
@@ -54,192 +192,364 @@ type OfferPayload = {
 };
 
 function stripAnsi(input: string): string {
-  return input.replace(/\u001b\[[0-9;]*m/g, '');
+  return input.replace(/\u001b\[[0-9;]*m/g, "");
+}
+
+function ensureRelayBuildArtifact(repoRoot: string): void {
+  const relayDistEntry = path.join(repoRoot, "packages/relay/dist/e2ee.js");
+  if (existsSync(relayDistEntry)) {
+    return;
+  }
+
+  console.log("[e2e] Building @getpaseo/relay for daemon startup");
+  execSync("npm run build --workspace=@getpaseo/relay", {
+    cwd: repoRoot,
+    stdio: "inherit",
+  });
 }
 
 function decodeOfferFromFragmentUrl(url: string): OfferPayload {
-  const marker = '#offer=';
+  const marker = "#offer=";
   const idx = url.indexOf(marker);
   if (idx === -1) {
     throw new Error(`missing ${marker} fragment: ${url}`);
   }
   const encoded = url.slice(idx + marker.length);
-  const json = Buffer.from(encoded, 'base64url').toString('utf8');
+  const json = Buffer.from(encoded, "base64url").toString("utf8");
   const offer = JSON.parse(json) as Partial<OfferPayload>;
-  if (offer.v !== 2) throw new Error('offer.v missing/invalid');
-  if (!offer.serverId) throw new Error('offer.serverId missing');
-  if (!offer.daemonPublicKeyB64) throw new Error('offer.daemonPublicKeyB64 missing');
-  if (!offer.relay?.endpoint) throw new Error('offer.relay.endpoint missing');
+  if (offer.v !== 2) throw new Error("offer.v missing/invalid");
+  if (!offer.serverId) throw new Error("offer.serverId missing");
+  if (!offer.daemonPublicKeyB64) throw new Error("offer.daemonPublicKeyB64 missing");
+  if (!offer.relay?.endpoint) throw new Error("offer.relay.endpoint missing");
   return offer as OfferPayload;
 }
 
 export default async function globalSetup() {
-  const repoRoot = path.resolve(__dirname, '../../..');
-  const envTestPath = path.join(repoRoot, '.env.test');
+  const repoRoot = path.resolve(__dirname, "../../..");
+  ensureRelayBuildArtifact(repoRoot);
+  const envTestPath = path.join(repoRoot, ".env.test");
   if (existsSync(envTestPath)) {
     dotenv.config({ path: envTestPath });
   }
 
   const port = await getAvailablePort();
-  const relayPort = await getAvailablePort();
+  let relayPort = 0;
   const metroPort = await getAvailablePort();
-  paseoHome = await mkdtemp(path.join(tmpdir(), 'paseo-e2e-home-'));
+  paseoHome = await mkdtemp(path.join(tmpdir(), "paseo-e2e-home-"));
+  let relayLineBuffer = createLineBuffer();
+  const metroLineBuffer = createLineBuffer();
+  const daemonLineBuffer = createLineBuffer();
 
-  const relayDir = path.resolve(__dirname, '..', '..', 'relay');
-  relayProcess = spawn(
-    'npx',
-    ['wrangler', 'dev', '--local', '--ip', '127.0.0.1', '--port', String(relayPort)],
-    {
-      cwd: relayDir,
-      env: { ...process.env },
-      stdio: ['ignore', 'pipe', 'pipe'],
-      detached: false,
-    }
-  );
-
-  relayProcess.stdout?.on('data', (data: Buffer) => {
-    const lines = data.toString().split('\n').filter((l) => l.trim());
-    for (const line of lines) {
-      console.log(`[relay] ${line}`);
-    }
-  });
-  relayProcess.stderr?.on('data', (data: Buffer) => {
-    const lines = data.toString().split('\n').filter((l) => l.trim());
-    for (const line of lines) {
-      console.error(`[relay] ${line}`);
-    }
-  });
-
-  await waitForServer(relayPort, 30000);
-
-  // Start Metro bundler on dynamic port
-  const appDir = path.resolve(__dirname, '..');
-  metroProcess = spawn('npx', ['expo', 'start', '--web', '--port', String(metroPort)], {
-    cwd: appDir,
-    env: {
-      ...process.env,
-      BROWSER: 'none', // Don't auto-open browser
-    },
-    stdio: ['ignore', 'pipe', 'pipe'],
-    detached: false,
-  });
-
-  metroProcess.stdout?.on('data', (data: Buffer) => {
-    const lines = data.toString().split('\n').filter((l) => l.trim());
-    for (const line of lines) {
-      console.log(`[metro] ${line}`);
-    }
-  });
-
-  metroProcess.stderr?.on('data', (data: Buffer) => {
-    console.error(`[metro] ${data.toString().trim()}`);
-  });
-
-  const serverDir = path.resolve(__dirname, '../../..', 'packages/server');
-  const tsxBin = execSync('which tsx').toString().trim();
-
-  let offerPayload: OfferPayload | null = null;
-  let offerResolve: (() => void) | null = null;
-  const offerPromise = new Promise<void>((resolve) => {
-    offerResolve = resolve;
-  });
-
-  daemonProcess = spawn(tsxBin, ['src/server/index.ts'], {
-    cwd: serverDir,
-    env: {
-      ...process.env,
-      PASEO_HOME: paseoHome,
-      PASEO_SERVER_ID: 'srv_e2e_test_daemon',
-      PASEO_LISTEN: `0.0.0.0:${port}`,
-      PASEO_RELAY_ENDPOINT: `127.0.0.1:${relayPort}`,
-      PASEO_CORS_ORIGINS: `http://localhost:${metroPort}`,
-      // Keep e2e bootstrap fast and deterministic; terminal/sidebar tests do not need speech.
-      PASEO_DICTATION_ENABLED: "0",
-      PASEO_VOICE_MODE_ENABLED: "0",
-      NODE_ENV: 'development',
-    },
-    stdio: ['ignore', 'pipe', 'pipe'],
-    detached: false,
-  });
-
-  let stdoutBuffer = '';
-  daemonProcess.stdout?.on('data', (data: Buffer) => {
-    stdoutBuffer += data.toString('utf8');
-    const lines = stdoutBuffer.split('\n');
-    stdoutBuffer = lines.pop() ?? '';
-    for (const line of lines) {
-      const trimmed = line.trim();
-      if (!trimmed) continue;
-      if (!offerPayload) {
-        const clean = stripAnsi(trimmed);
-        try {
-          const obj = JSON.parse(clean) as { msg?: string; url?: string };
-          if (obj.msg === 'pairing_offer' && typeof obj.url === 'string') {
-            offerPayload = decodeOfferFromFragmentUrl(obj.url);
-            offerResolve?.();
-          }
-        } catch {
-          const match = clean.match(/https?:\/\/[^\s"]+#offer=[A-Za-z0-9_-]+/);
-          if (match && clean.includes('pairing_offer')) {
-            try {
-              offerPayload = decodeOfferFromFragmentUrl(match[0]);
-              offerResolve?.();
-            } catch {
-              // ignore parsing failures
-            }
-          }
-        }
-      }
-      console.log(`[daemon] ${trimmed}`);
-    }
-  });
-
-  daemonProcess.stderr?.on('data', (data: Buffer) => {
-    console.error(`[daemon] ${data.toString().trim()}`);
-  });
-
-  // Wait for both daemon and Metro to be ready
-  await Promise.all([
-    waitForServer(port),
-    waitForServer(metroPort, 120000), // Metro can take longer to start
-  ]);
-
-  // Wait for daemon to emit a pairing offer (includes relay session ID).
-  await Promise.race([
-    offerPromise,
-    new Promise((_, reject) =>
-      setTimeout(() => reject(new Error('Timed out waiting for pairing_offer log')), 15000)
-    ),
-  ]);
-  if (!offerPayload) {
-    throw new Error('pairing_offer was not parsed from daemon logs');
-  }
-  const offer = offerPayload as OfferPayload;
-
-  process.env.E2E_DAEMON_PORT = String(port);
-  process.env.E2E_RELAY_PORT = String(relayPort);
-  process.env.E2E_SERVER_ID = offer.serverId;
-  process.env.E2E_RELAY_DAEMON_PUBLIC_KEY = offer.daemonPublicKeyB64;
-  process.env.E2E_METRO_PORT = String(metroPort);
-  console.log(`[e2e] Test daemon started on port ${port}, Metro on port ${metroPort}, home: ${paseoHome}`);
-
-  return async () => {
-    if (daemonProcess) {
-      daemonProcess.kill('SIGTERM');
-      daemonProcess = null;
-    }
-    if (metroProcess) {
-      metroProcess.kill('SIGTERM');
-      metroProcess = null;
-    }
-    if (relayProcess) {
-      relayProcess.kill('SIGTERM');
-      relayProcess = null;
-    }
+  const cleanup = async () => {
+    await Promise.all([
+      stopProcess(daemonProcess),
+      stopProcess(metroProcess),
+      stopProcess(relayProcess),
+    ]);
+    daemonProcess = null;
+    metroProcess = null;
+    relayProcess = null;
     if (paseoHome) {
       await rm(paseoHome, { recursive: true, force: true });
       paseoHome = null;
     }
-    console.log('[e2e] Test daemon stopped');
   };
+
+  const openAiUsable = await isOpenAiApiKeyUsable(process.env.OPENAI_API_KEY);
+  const defaultLocalModelsDir = path.join(
+    process.env.HOME ?? "",
+    ".paseo",
+    "models",
+    "local-speech",
+  );
+  const hasDefaultLocalModelsDir =
+    defaultLocalModelsDir.trim().length > 0 && existsSync(defaultLocalModelsDir);
+  const dictationProvider = openAiUsable ? "openai" : "local";
+
+  if (dictationProvider === "local" && !hasDefaultLocalModelsDir) {
+    throw new Error(
+      "OpenAI key is not usable and local speech models are unavailable at ~/.paseo/models/local-speech. " +
+        "Either provide a valid OPENAI_API_KEY or install local speech models before running app e2e tests.",
+    );
+  }
+
+  const localModelsDir = dictationProvider === "local" ? defaultLocalModelsDir : null;
+  console.log(
+    `[e2e] Dictation STT provider: ${dictationProvider}${openAiUsable ? "" : " (OpenAI probe failed)"}`,
+  );
+
+  try {
+    const relayDir = path.resolve(__dirname, "..", "..", "relay");
+    const maxRelayStartupAttempts = 5;
+    let relayStarted = false;
+    let lastRelayStartupError: unknown = null;
+
+    for (let attempt = 1; attempt <= maxRelayStartupAttempts; attempt += 1) {
+      relayPort = await getAvailablePort();
+      relayLineBuffer = createLineBuffer();
+      let relayStartupFailureLine: string | null = null;
+      let relayReadyForSelectedPort = false;
+
+      relayProcess = spawn(
+        "npx",
+        ["wrangler", "dev", "--local", "--ip", "127.0.0.1", "--port", String(relayPort)],
+        {
+          cwd: relayDir,
+          env: { ...process.env },
+          stdio: ["ignore", "pipe", "pipe"],
+          detached: false,
+        },
+      );
+
+      relayProcess.stdout?.on("data", (data: Buffer) => {
+        const lines = data
+          .toString()
+          .split("\n")
+          .filter((line) => line.trim());
+        for (const line of lines) {
+          relayLineBuffer.add(`[stdout] ${line}`);
+          const failure = parseRelayStartupFailure(line);
+          if (failure) {
+            relayStartupFailureLine = failure;
+          }
+          const clean = stripAnsi(line);
+          const readyMatch = clean.match(/Ready on .*:(\d+)\b/i);
+          if (readyMatch && Number(readyMatch[1]) === relayPort) {
+            relayReadyForSelectedPort = true;
+          }
+          console.log(`[relay] ${line}`);
+        }
+      });
+      relayProcess.stderr?.on("data", (data: Buffer) => {
+        const lines = data
+          .toString()
+          .split("\n")
+          .filter((line) => line.trim());
+        for (const line of lines) {
+          relayLineBuffer.add(`[stderr] ${line}`);
+          const failure = parseRelayStartupFailure(line);
+          if (failure) {
+            relayStartupFailureLine = failure;
+          }
+          const clean = stripAnsi(line);
+          const readyMatch = clean.match(/Ready on .*:(\d+)\b/i);
+          if (readyMatch && Number(readyMatch[1]) === relayPort) {
+            relayReadyForSelectedPort = true;
+          }
+          console.error(`[relay] ${line}`);
+        }
+      });
+
+      try {
+        await waitForServer(relayPort, {
+          label: "Relay dev server",
+          timeoutMs: 30000,
+          childProcess: relayProcess,
+          getRecentOutput: relayLineBuffer.dump,
+        });
+
+        const readyDeadline = Date.now() + 5000;
+        while (
+          !relayReadyForSelectedPort &&
+          relayStartupFailureLine === null &&
+          relayProcess?.exitCode === null &&
+          relayProcess?.signalCode === null &&
+          Date.now() < readyDeadline
+        ) {
+          await sleep(100);
+        }
+
+        if (relayStartupFailureLine) {
+          throw new Error(`Relay startup failed: ${relayStartupFailureLine}`);
+        }
+        if (!relayReadyForSelectedPort) {
+          throw new Error(
+            `Relay process did not report ready for selected port ${relayPort}.${formatRecentOutput(
+              relayLineBuffer.dump,
+            )}`,
+          );
+        }
+        if (relayProcess.exitCode !== null || relayProcess.signalCode !== null) {
+          throw new Error(
+            `Relay process exited before startup completed (exit code ${relayProcess.exitCode}, signal ${relayProcess.signalCode}).${formatRecentOutput(
+              relayLineBuffer.dump,
+            )}`,
+          );
+        }
+
+        relayStarted = true;
+        break;
+      } catch (error) {
+        lastRelayStartupError = error;
+        await stopProcess(relayProcess);
+        relayProcess = null;
+      }
+    }
+
+    if (!relayStarted) {
+      const message =
+        lastRelayStartupError instanceof Error
+          ? lastRelayStartupError.message
+          : String(lastRelayStartupError);
+      throw new Error(
+        `Failed to start relay dev server after ${maxRelayStartupAttempts} attempts. ${message}`,
+      );
+    }
+
+    // Start Metro bundler on dynamic port
+    const appDir = path.resolve(__dirname, "..");
+    metroProcess = spawn("npx", ["expo", "start", "--web", "--port", String(metroPort)], {
+      cwd: appDir,
+      env: {
+        ...process.env,
+        BROWSER: "none", // Don't auto-open browser
+      },
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: false,
+    });
+
+    metroProcess.stdout?.on("data", (data: Buffer) => {
+      const lines = data
+        .toString()
+        .split("\n")
+        .filter((line) => line.trim());
+      for (const line of lines) {
+        metroLineBuffer.add(`[stdout] ${line}`);
+        console.log(`[metro] ${line}`);
+      }
+    });
+
+    metroProcess.stderr?.on("data", (data: Buffer) => {
+      const lines = data
+        .toString()
+        .split("\n")
+        .filter((line) => line.trim());
+      for (const line of lines) {
+        metroLineBuffer.add(`[stderr] ${line}`);
+        console.error(`[metro] ${line}`);
+      }
+    });
+
+    const serverDir = path.resolve(__dirname, "../../..", "packages/server");
+    const tsxBin = execSync("which tsx").toString().trim();
+
+    let offerPayload: OfferPayload | null = null;
+    let offerResolve: (() => void) | null = null;
+    const offerPromise = new Promise<void>((resolve) => {
+      offerResolve = resolve;
+    });
+
+    daemonProcess = spawn(tsxBin, ["src/server/index.ts"], {
+      cwd: serverDir,
+      env: {
+        ...process.env,
+        PASEO_HOME: paseoHome,
+        PASEO_SERVER_ID: "srv_e2e_test_daemon",
+        PASEO_LISTEN: `0.0.0.0:${port}`,
+        PASEO_RELAY_ENDPOINT: `127.0.0.1:${relayPort}`,
+        PASEO_CORS_ORIGINS: `http://localhost:${metroPort}`,
+        PASEO_DICTATION_ENABLED: openAiUsable ? "1" : "0",
+        PASEO_VOICE_MODE_ENABLED: openAiUsable ? "1" : "0",
+        ...(openAiUsable
+          ? {
+              PASEO_DICTATION_STT_PROVIDER: "openai",
+              PASEO_VOICE_STT_PROVIDER: "openai",
+              PASEO_VOICE_TTS_PROVIDER: "openai",
+            }
+          : {}),
+        ...(localModelsDir ? { PASEO_LOCAL_MODELS_DIR: localModelsDir } : {}),
+        NODE_ENV: "development",
+      },
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: false,
+    });
+
+    let stdoutBuffer = "";
+    daemonProcess.stdout?.on("data", (data: Buffer) => {
+      stdoutBuffer += data.toString("utf8");
+      const lines = stdoutBuffer.split("\n");
+      stdoutBuffer = lines.pop() ?? "";
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        daemonLineBuffer.add(`[stdout] ${trimmed}`);
+        if (!offerPayload) {
+          const clean = stripAnsi(trimmed);
+          try {
+            const obj = JSON.parse(clean) as { msg?: string; url?: string };
+            if (obj.msg === "pairing_offer" && typeof obj.url === "string") {
+              offerPayload = decodeOfferFromFragmentUrl(obj.url);
+              offerResolve?.();
+            }
+          } catch {
+            const match = clean.match(/https?:\/\/[^\s"]+#offer=[A-Za-z0-9_-]+/);
+            if (match && clean.includes("pairing_offer")) {
+              try {
+                offerPayload = decodeOfferFromFragmentUrl(match[0]);
+                offerResolve?.();
+              } catch {
+                // ignore parsing failures
+              }
+            }
+          }
+        }
+        console.log(`[daemon] ${trimmed}`);
+      }
+    });
+
+    daemonProcess.stderr?.on("data", (data: Buffer) => {
+      const lines = data
+        .toString()
+        .split("\n")
+        .filter((line) => line.trim());
+      for (const line of lines) {
+        daemonLineBuffer.add(`[stderr] ${line}`);
+        console.error(`[daemon] ${line}`);
+      }
+    });
+
+    // Wait for both daemon and Metro to be ready
+    await Promise.all([
+      waitForServer(port, {
+        label: "Paseo daemon",
+        childProcess: daemonProcess,
+        getRecentOutput: daemonLineBuffer.dump,
+      }),
+      waitForServer(metroPort, {
+        label: "Metro web server",
+        timeoutMs: 120000, // Metro can take longer to start
+        childProcess: metroProcess,
+        getRecentOutput: metroLineBuffer.dump,
+      }),
+    ]);
+
+    // Wait for daemon to emit a pairing offer (includes relay session ID).
+    await Promise.race([
+      offerPromise,
+      new Promise((_, reject) =>
+        setTimeout(() => reject(new Error("Timed out waiting for pairing_offer log")), 15000),
+      ),
+    ]);
+    if (!offerPayload) {
+      throw new Error("pairing_offer was not parsed from daemon logs");
+    }
+    const offer = offerPayload as OfferPayload;
+
+    process.env.E2E_DAEMON_PORT = String(port);
+    process.env.E2E_RELAY_PORT = String(relayPort);
+    process.env.E2E_SERVER_ID = offer.serverId;
+    process.env.E2E_RELAY_DAEMON_PUBLIC_KEY = offer.daemonPublicKeyB64;
+    process.env.E2E_METRO_PORT = String(metroPort);
+    console.log(
+      `[e2e] Test daemon started on port ${port}, Metro on port ${metroPort}, home: ${paseoHome}`,
+    );
+
+    return async () => {
+      await cleanup();
+      console.log("[e2e] Test daemon stopped");
+    };
+  } catch (error) {
+    await cleanup();
+    throw error;
+  }
 }

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

@@ -0,0 +1,281 @@
+import { expect, type Page } from "@playwright/test";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { randomUUID } from "node:crypto";
+import { buildHostWorkspaceRoute } from "../../src/utils/host-routes";
+
+const NEAR_BOTTOM_THRESHOLD_PX = 72;
+
+export type ScrollMetrics = {
+  offsetY: number;
+  contentHeight: number;
+  viewportHeight: number;
+  distanceFromBottom: number;
+};
+
+export type SeededAgent = {
+  id: string;
+  title: string;
+  expectedTailText: string;
+  url: string;
+  workspaceUrl: string;
+};
+
+export type 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),
+  };
+}
+
+async function loadDaemonClientConstructor(): Promise<
+  new (config: {
+    url: string;
+    clientId: string;
+    clientType: "cli";
+  }) => DaemonClientInstance
+> {
+  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";
+    }) => DaemonClientInstance;
+  };
+  return mod.DaemonClient;
+}
+
+export async function connectDaemonClient(): Promise<DaemonClientInstance> {
+  const DaemonClient = await loadDaemonClientConstructor();
+  const client = new DaemonClient({
+    url: getDaemonWsUrl(),
+    clientId: `app-e2e-${randomUUID()}`,
+    clientType: "cli",
+  });
+  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.1-codex-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();
+}
+
+export async function readScrollMetrics(page: Page): Promise<ScrollMetrics> {
+  return getVisibleChatScroll(page).evaluate((root: Element) => {
+    const candidates = [root, ...Array.from(root.querySelectorAll("*"))]
+      .filter((element): element is HTMLElement => element instanceof HTMLElement)
+      .filter((element) => {
+        const tagName = element.tagName.toLowerCase();
+        const isEditable =
+          tagName === "textarea" ||
+          tagName === "input" ||
+          element.getAttribute("contenteditable") === "true";
+        return !isEditable && element.scrollHeight - element.clientHeight > 1;
+      });
+    const scrollElement =
+      candidates.sort(
+        (left, right) =>
+          right.scrollHeight - right.clientHeight - (left.scrollHeight - left.clientHeight),
+      )[0] ?? (root as HTMLElement);
+
+    const offsetY = Math.max(0, scrollElement.scrollTop);
+    const contentHeight = Math.max(0, scrollElement.scrollHeight);
+    const viewportHeight = Math.max(0, scrollElement.clientHeight);
+    const distanceFromBottom = Math.max(0, contentHeight - (offsetY + viewportHeight));
+
+    return {
+      offsetY,
+      contentHeight,
+      viewportHeight,
+      distanceFromBottom,
+    };
+  });
+}
+
+export async function 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 () => {
+      const metrics = await readScrollMetrics(page);
+      return metrics.distanceFromBottom;
+    })
+    .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,
+): Promise<ScrollMetrics> {
+  await expect
+    .poll(async () => {
+      const metrics = await readScrollMetrics(page);
+      return metrics.contentHeight;
+    })
+    .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,16 +1,19 @@
-import { expect, type Page } from '@playwright/test';
+import { expect, type Page } from "@playwright/test";
+import { buildCreateAgentPreferences, buildSeededHost } from "./daemon-registry";
 
 function escapeRegex(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
 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).');
+    throw new Error("E2E_DAEMON_PORT is not set (expected from Playwright globalSetup).");
   }
-  if (port === '6767') {
-    throw new Error('E2E_DAEMON_PORT is 6767. Refusing to run e2e against the default local daemon.');
+  if (port === "6767") {
+    throw new Error(
+      "E2E_DAEMON_PORT is 6767. Refusing to run e2e against the default local daemon.",
+    );
   }
   return port;
 }
@@ -20,67 +23,58 @@ async function ensureE2EStorageSeeded(page: Page): Promise<void> {
   const expectedEndpoint = `127.0.0.1:${port}`;
   const expectedServerId = process.env.E2E_SERVER_ID;
   if (!expectedServerId) {
-    throw new Error('E2E_SERVER_ID is not set (expected from Playwright globalSetup).');
+    throw new Error("E2E_SERVER_ID is not set (expected from Playwright globalSetup).");
   }
 
-  const needsReset = await page.evaluate(({ expectedEndpoint, expectedServerId }) => {
-    const raw = localStorage.getItem('@paseo:daemon-registry');
-    if (!raw) return true;
-    try {
-      const parsed = JSON.parse(raw);
-      if (!Array.isArray(parsed) || parsed.length !== 1) return true;
-      const entry = parsed[0] as any;
-      if (entry?.serverId !== expectedServerId) return true;
-      const connections = entry?.connections;
-      if (!Array.isArray(connections)) return true;
-      if (connections.some((c: any) => c?.type === 'direct' && typeof c?.endpoint === 'string' && /:6767\b/.test(c.endpoint))) return true;
-      return !connections.some((c: any) => c?.type === 'direct' && c?.endpoint === expectedEndpoint);
-    } catch {
-      return true;
-    }
-  }, { expectedEndpoint, expectedServerId });
+  const needsReset = await page.evaluate(
+    ({ expectedEndpoint, expectedServerId }) => {
+      const raw = localStorage.getItem("@paseo:daemon-registry");
+      if (!raw) return true;
+      try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed) || parsed.length !== 1) return true;
+        const entry = parsed[0] as any;
+        if (entry?.serverId !== expectedServerId) return true;
+        const connections = entry?.connections;
+        if (!Array.isArray(connections)) return true;
+        if (
+          connections.some(
+            (c: any) =>
+              c?.type === "directTcp" &&
+              typeof c?.endpoint === "string" &&
+              /:6767\b/.test(c.endpoint),
+          )
+        )
+          return true;
+        return !connections.some(
+          (c: any) => c?.type === "directTcp" && c?.endpoint === expectedEndpoint,
+        );
+      } catch {
+        return true;
+      }
+    },
+    { expectedEndpoint, expectedServerId },
+  );
 
   if (!needsReset) {
     return;
   }
 
   const nowIso = new Date().toISOString();
+  const daemon = buildSeededHost({
+    serverId: expectedServerId,
+    endpoint: expectedEndpoint,
+    nowIso,
+  });
+  const preferences = buildCreateAgentPreferences(expectedServerId);
   await page.evaluate(
-    ({ expectedEndpoint, nowIso, expectedServerId }) => {
-      localStorage.setItem('@paseo:e2e', '1');
-      localStorage.setItem(
-        '@paseo:daemon-registry',
-        JSON.stringify([
-          {
-            serverId: expectedServerId,
-            label: 'localhost',
-            connections: [
-              {
-                id: `direct:${expectedEndpoint}`,
-                type: 'direct',
-                endpoint: expectedEndpoint,
-              },
-            ],
-            preferredConnectionId: `direct:${expectedEndpoint}`,
-            createdAt: nowIso,
-            updatedAt: nowIso,
-          },
-        ])
-      );
-      localStorage.setItem(
-        '@paseo:create-agent-preferences',
-        JSON.stringify({
-          serverId: expectedServerId,
-          provider: 'claude',
-          providerPreferences: {
-            claude: { model: 'haiku' },
-            codex: { model: 'gpt-5.1-codex-mini' },
-          },
-        })
-      );
-      localStorage.removeItem('@paseo:settings');
+    ({ daemon, preferences }) => {
+      localStorage.setItem("@paseo:e2e", "1");
+      localStorage.setItem("@paseo:daemon-registry", JSON.stringify([daemon]));
+      localStorage.setItem("@paseo:create-agent-preferences", JSON.stringify(preferences));
+      localStorage.removeItem("@paseo:settings");
     },
-    { expectedEndpoint, nowIso, expectedServerId }
+    { daemon, preferences },
   );
 
   await page.reload();
@@ -91,80 +85,131 @@ async function assertE2EUsesSeededTestDaemon(page: Page): Promise<void> {
   const expectedEndpoint = `127.0.0.1:${port}`;
   const expectedServerId = process.env.E2E_SERVER_ID;
   if (!expectedServerId) {
-    throw new Error('E2E_SERVER_ID is not set (expected from Playwright globalSetup).');
+    throw new Error("E2E_SERVER_ID is not set (expected from Playwright globalSetup).");
   }
 
   const snapshot = await page.evaluate(() => {
-    const registryRaw = localStorage.getItem('@paseo:daemon-registry');
-    const prefsRaw = localStorage.getItem('@paseo:create-agent-preferences');
+    const registryRaw = localStorage.getItem("@paseo:daemon-registry");
+    const prefsRaw = localStorage.getItem("@paseo:create-agent-preferences");
     return { registryRaw, prefsRaw };
   });
 
   if (!snapshot.registryRaw) {
-    throw new Error('E2E expected @paseo:daemon-registry to be set before app load.');
+    throw new Error("E2E expected @paseo:daemon-registry to be set before app load.");
   }
 
   let registry: any;
   try {
     registry = JSON.parse(snapshot.registryRaw);
   } catch {
-    throw new Error('E2E expected @paseo:daemon-registry to be valid JSON.');
+    throw new Error("E2E expected @paseo:daemon-registry to be valid JSON.");
   }
 
   if (!Array.isArray(registry) || registry.length !== 1) {
     throw new Error(
-      `E2E expected @paseo:daemon-registry to contain exactly 1 daemon (got ${Array.isArray(registry) ? registry.length : 'non-array'}).`
+      `E2E expected @paseo:daemon-registry to contain exactly 1 daemon (got ${Array.isArray(registry) ? registry.length : "non-array"}).`,
     );
   }
 
   const daemon = registry[0];
-  if (typeof daemon?.serverId !== 'string' || daemon.serverId.length === 0) {
-    throw new Error(`E2E expected seeded daemon to have a string serverId (got ${String(daemon?.serverId)}).`);
+  if (typeof daemon?.serverId !== "string" || daemon.serverId.length === 0) {
+    throw new Error(
+      `E2E expected seeded daemon to have a string serverId (got ${String(daemon?.serverId)}).`,
+    );
   }
   if (daemon.serverId !== expectedServerId) {
-    throw new Error(`E2E expected seeded daemon serverId to be ${expectedServerId} (got ${daemon.serverId}).`);
+    throw new Error(
+      `E2E expected seeded daemon serverId to be ${expectedServerId} (got ${daemon.serverId}).`,
+    );
   }
 
   const connections: unknown = daemon?.connections;
   if (
     !Array.isArray(connections) ||
-    !connections.some((c: any) => c?.type === 'direct' && c?.endpoint === expectedEndpoint)
+    !connections.some((c: any) => c?.type === "directTcp" && c?.endpoint === expectedEndpoint)
   ) {
     throw new Error(
-      `E2E expected seeded daemon connections to include direct ${expectedEndpoint} (got ${JSON.stringify(connections)}).`
+      `E2E expected seeded daemon connections to include directTcp ${expectedEndpoint} (got ${JSON.stringify(connections)}).`,
     );
   }
-  if (Array.isArray(connections) && connections.some((c: any) => c?.type === 'direct' && typeof c?.endpoint === 'string' && /:6767\b/.test(c.endpoint))) {
-    throw new Error(`E2E detected a daemon endpoint pointing at :6767 (${JSON.stringify(connections)}).`);
+  if (
+    Array.isArray(connections) &&
+    connections.some(
+      (c: any) =>
+        c?.type === "directTcp" && typeof c?.endpoint === "string" && /:6767\b/.test(c.endpoint),
+    )
+  ) {
+    throw new Error(
+      `E2E detected a daemon endpoint pointing at :6767 (${JSON.stringify(connections)}).`,
+    );
   }
 
   if (!snapshot.prefsRaw) {
-    throw new Error('E2E expected @paseo:create-agent-preferences to be set before app load.');
+    throw new Error("E2E expected @paseo:create-agent-preferences to be set before app load.");
   }
   try {
     const prefs = JSON.parse(snapshot.prefsRaw) as any;
     if (prefs?.serverId !== daemon.serverId) {
       throw new Error(
-        `E2E expected create-agent-preferences.serverId to match seeded daemon serverId (${daemon.serverId}) (got ${String(prefs?.serverId)}).`
+        `E2E expected create-agent-preferences.serverId to match seeded daemon serverId (${daemon.serverId}) (got ${String(prefs?.serverId)}).`,
       );
     }
   } catch (error) {
     if (error instanceof Error) throw error;
-    throw new Error('E2E expected @paseo:create-agent-preferences to be valid JSON.');
+    throw new Error("E2E expected @paseo:create-agent-preferences to be valid JSON.");
   }
 }
 
-export const gotoHome = async (page: Page) => {
-  await page.goto('/');
+export const gotoAppShell = async (page: Page) => {
+  await page.goto("/");
   await ensureE2EStorageSeeded(page);
-  await expect(page.getByText('New agent', { exact: true }).first()).toBeVisible();
-  await expect(page.getByRole('textbox', { name: 'Message agent...' })).toBeVisible();
+};
+
+export const gotoHome = async (page: Page) => {
+  await gotoAppShell(page);
+  const composer = page.getByRole("textbox", { name: "Message agent..." });
+  if (
+    !(await composer
+      .first()
+      .isVisible()
+      .catch(() => false))
+  ) {
+    const addProjectCta = page.getByText("Add a project", { exact: true }).first();
+    const addProjectSidebar = page.getByText("Add project", { exact: true }).first();
+    const newAgentButton = page.getByText("New agent", { exact: true }).first();
+
+    await expect
+      .poll(
+        async () =>
+          (await addProjectCta.isVisible().catch(() => false)) ||
+          (await addProjectSidebar.isVisible().catch(() => false)) ||
+          (await newAgentButton.isVisible().catch(() => false)),
+        { timeout: 10000 },
+      )
+      .toBe(true);
+
+    if (await addProjectCta.isVisible().catch(() => false)) {
+      await addProjectCta.click();
+    } else if (await addProjectSidebar.isVisible().catch(() => false)) {
+      await addProjectSidebar.click();
+    } else {
+      await newAgentButton.click();
+    }
+  }
+  await expect(composer.first()).toBeVisible({ timeout: 30000 });
 };
 
 export const openSettings = async (page: Page) => {
-  // Navigate directly to settings page
-  await page.goto('/settings');
-  await expect(page).toHaveURL(/\/settings$/);
+  const serverId = process.env.E2E_SERVER_ID;
+  if (!serverId) {
+    throw new Error("E2E_SERVER_ID is not set (expected from Playwright globalSetup).");
+  }
+
+  // Navigate through the real app control so route changes stay aligned with UI behavior.
+  const settingsButton = page.locator('[data-testid="sidebar-settings"]:visible').first();
+  await expect(settingsButton).toBeVisible();
+  await settingsButton.click();
+  await expect(page).toHaveURL(new RegExp(`/h/${escapeRegex(serverId)}/settings$`));
 };
 
 export const setWorkingDirectory = async (page: Page, directory: string) => {
@@ -173,23 +218,19 @@ export const setWorkingDirectory = async (page: Page, directory: string) => {
     .first();
   await expect(workingDirectorySelect).toBeVisible({ timeout: 30000 });
 
-  const legacyInput = page.getByRole('textbox', { name: '/path/to/project' }).first();
-  const directorySearchInput = page.getByRole('textbox', { name: /search directories/i }).first();
-  const worktreePicker = page.getByTestId('worktree-attach-picker');
-  const worktreeSheetTitle = page.getByText('Select worktree', { exact: true });
+  const legacyInput = page.getByRole("textbox", { name: "/path/to/project" }).first();
+  const directorySearchInput = page.getByRole("textbox", { name: /search directories/i }).first();
+  const worktreePicker = page.getByTestId("worktree-attach-picker");
+  const worktreeSheetTitle = page.getByText("Select worktree", { exact: true }).first();
   const closeBottomSheet = async () => {
-    const bottomSheetBackdrop = page
-      .getByRole('button', { name: 'Bottom sheet backdrop' })
-      .first();
-    const bottomSheetHandle = page
-      .getByRole('slider', { name: 'Bottom sheet handle' })
-      .first();
+    const bottomSheetBackdrop = page.getByRole("button", { name: "Bottom sheet backdrop" }).first();
+    const bottomSheetHandle = page.getByRole("slider", { name: "Bottom sheet handle" }).first();
     for (let attempt = 0; attempt < 3; attempt += 1) {
       if (!(await bottomSheetBackdrop.isVisible())) {
         return;
       }
       await bottomSheetBackdrop.click({ force: true });
-      await page.keyboard.press('Escape').catch(() => undefined);
+      await page.keyboard.press("Escape").catch(() => undefined);
       await page.waitForTimeout(200);
     }
     if (await bottomSheetBackdrop.isVisible()) {
@@ -209,7 +250,7 @@ export const setWorkingDirectory = async (page: Page, directory: string) => {
     if (!(await worktreeSheetTitle.isVisible()) && !(await worktreePicker.isVisible())) {
       return;
     }
-    const attachToggle = page.getByTestId('worktree-attach-toggle');
+    const attachToggle = page.getByTestId("worktree-attach-toggle");
     if (await attachToggle.isVisible()) {
       await attachToggle.click({ force: true });
       await page.waitForTimeout(200);
@@ -230,26 +271,23 @@ export const setWorkingDirectory = async (page: Page, directory: string) => {
       await closeBottomSheet();
       await workingDirectorySelect.click({ force: true });
     }
-    await expect
-      .poll(async () => pickerInputVisible(), { timeout: 10000 })
-      .toBe(true);
+    await expect.poll(async () => pickerInputVisible(), { timeout: 10000 }).toBe(true);
   }
 
-  const trimmedDirectory = directory.replace(/\/+$/, '');
-  const activeInput =
-    (await directorySearchInput.isVisible().catch(() => false))
-      ? directorySearchInput
-      : legacyInput;
+  const trimmedDirectory = directory.replace(/\/+$/, "");
+  const activeInput = (await directorySearchInput.isVisible().catch(() => false))
+    ? directorySearchInput
+    : legacyInput;
 
   await activeInput.fill(trimmedDirectory);
 
   if (activeInput === directorySearchInput) {
     // Combobox custom rows can be either plain path labels or prefixed labels.
     const plainOption = page
-      .getByText(new RegExp(`^${escapeRegex(trimmedDirectory)}$`, 'i'))
+      .getByText(new RegExp(`^${escapeRegex(trimmedDirectory)}$`, "i"))
       .first();
     const prefixedUseOption = page
-      .getByText(new RegExp(`^Use "${escapeRegex(trimmedDirectory)}"$`, 'i'))
+      .getByText(new RegExp(`^Use "${escapeRegex(trimmedDirectory)}"$`, "i"))
       .first();
 
     if (await plainOption.isVisible().catch(() => false)) {
@@ -258,33 +296,38 @@ export const setWorkingDirectory = async (page: Page, directory: string) => {
       await prefixedUseOption.click({ force: true });
     } else {
       // Fallback: accept highlighted option (directory suggestion).
-      await activeInput.press('Enter');
+      await activeInput.press("Enter");
     }
   } else {
     // Legacy path picker fallback.
-    await activeInput.press('Enter');
+    await activeInput.press("Enter");
   }
 
   // Wait for picker to close.
   await expect(activeInput).not.toBeVisible({ timeout: 10000 });
 
   const directoryCandidates = new Set<string>([trimmedDirectory]);
-  if (trimmedDirectory.startsWith('/var/')) {
+  if (trimmedDirectory.startsWith("/var/")) {
     directoryCandidates.add(`/private${trimmedDirectory}`);
   }
-  if (trimmedDirectory.startsWith('/private/var/')) {
-    directoryCandidates.add(trimmedDirectory.replace(/^\/private/, ''));
+  if (trimmedDirectory.startsWith("/private/var/")) {
+    directoryCandidates.add(trimmedDirectory.replace(/^\/private/, ""));
   }
-  const basename = trimmedDirectory.split('/').filter(Boolean).pop() ?? trimmedDirectory;
+  const basename = trimmedDirectory.split("/").filter(Boolean).pop() ?? trimmedDirectory;
 
-  await expect.poll(async () => {
-    const text = await workingDirectorySelect.innerText().catch(() => '');
-    if (text.includes(basename)) return true;
-    for (const candidate of directoryCandidates) {
-      if (text.includes(candidate)) return true;
-    }
-    return false;
-  }, { timeout: 30000 }).toBe(true);
+  await expect
+    .poll(
+      async () => {
+        const text = await workingDirectorySelect.innerText().catch(() => "");
+        if (text.includes(basename)) return true;
+        for (const candidate of directoryCandidates) {
+          if (text.includes(candidate)) return true;
+        }
+        return false;
+      },
+      { timeout: 30000 },
+    )
+    .toBe(true);
 };
 
 export const ensureHostSelected = async (page: Page) => {
@@ -302,19 +345,21 @@ export const ensureHostSelected = async (page: Page) => {
     }
 
     const fix = await page.evaluate(() => {
-      const registryRaw = localStorage.getItem('@paseo:daemon-registry');
-      const prefsRaw = localStorage.getItem('@paseo:create-agent-preferences');
-      if (!registryRaw || !prefsRaw) return { ok: false, reason: 'missing storage' } as const;
+      const registryRaw = localStorage.getItem("@paseo:daemon-registry");
+      const prefsRaw = localStorage.getItem("@paseo:create-agent-preferences");
+      if (!registryRaw || !prefsRaw) return { ok: false, reason: "missing storage" } as const;
       const registry = JSON.parse(registryRaw) as any[];
       const prefs = JSON.parse(prefsRaw) as any;
-      if (!Array.isArray(registry) || registry.length !== 1) return { ok: false, reason: 'registry shape' } as const;
+      if (!Array.isArray(registry) || registry.length !== 1)
+        return { ok: false, reason: "registry shape" } as const;
       const serverId = registry[0]?.serverId;
-      if (typeof serverId !== 'string' || serverId.length === 0) return { ok: false, reason: 'missing serverId' } as const;
+      if (typeof serverId !== "string" || serverId.length === 0)
+        return { ok: false, reason: "missing serverId" } as const;
       prefs.serverId = serverId;
-      localStorage.setItem('@paseo:create-agent-preferences', JSON.stringify(prefs));
+      localStorage.setItem("@paseo:create-agent-preferences", JSON.stringify(prefs));
       // Prevent the fixture's init-script from overwriting the corrected prefs on reload.
-      const nonce = localStorage.getItem('@paseo:e2e-seed-nonce') ?? '1';
-      localStorage.setItem('@paseo:e2e-disable-default-seed-once', nonce);
+      const nonce = localStorage.getItem("@paseo:e2e-seed-nonce") ?? "1";
+      localStorage.setItem("@paseo:e2e-disable-default-seed-once", nonce);
       return { ok: true } as const;
     });
 
@@ -326,20 +371,22 @@ export const ensureHostSelected = async (page: Page) => {
     await assertE2EUsesSeededTestDaemon(page);
   }
 
-  const input = page.getByRole('textbox', { name: 'Message agent...' });
+  const input = page.getByRole("textbox", { name: "Message agent..." });
   await expect(input).toBeVisible();
 
   if (await input.isEditable()) {
     return;
   }
 
-  const selectHostLabel = page.getByText('Select host', { exact: true });
+  const selectHostLabel = page.getByText("Select host", { exact: true });
   if (await selectHostLabel.isVisible()) {
     await selectHostLabel.click();
 
     // E2E safety: we enforce a single seeded daemon, so the option should be unambiguous.
-    const localhostOption = page.getByText('localhost', { exact: true }).first();
-    const daemonIdOption = page.getByText(process.env.E2E_SERVER_ID ?? 'srv_e2e_test_daemon', { exact: true }).first();
+    const localhostOption = page.getByText("localhost", { exact: true }).first();
+    const daemonIdOption = page
+      .getByText(process.env.E2E_SERVER_ID ?? "srv_e2e_test_daemon", { exact: true })
+      .first();
 
     if (await localhostOption.isVisible()) {
       await localhostOption.click();
@@ -353,18 +400,90 @@ export const ensureHostSelected = async (page: Page) => {
 };
 
 export const createAgent = async (page: Page, message: string) => {
-  const input = page.getByRole('textbox', { name: 'Message agent...' });
+  const input = page.getByRole("textbox", { name: "Message agent..." });
   await expect(input).toBeEditable();
+  await preferFastThinkingOption(page);
   await input.fill(message);
-  await input.press('Enter');
+  await input.press("Enter");
 
-  // Expo Router navigations can be "same-document" updates, so avoid waiting for a full `load`.
-  await page.waitForURL(/\/agent\//, { waitUntil: 'commit' });
+  // The composer may remain on the draft screen briefly while the initial run starts,
+  // so assert the user-visible result instead of forcing one route shape here.
+  await expect(page).toHaveURL(/\/(workspace|agent|new-agent)(\/|$|\?)/, { timeout: 30000 });
   await expect(page.getByText(message, { exact: true }).first()).toBeVisible({
     timeout: 30000,
   });
 };
 
+async function preferFastThinkingOption(page: Page): Promise<void> {
+  const providerTrigger = page
+    .locator(
+      '[data-testid="agent-provider-selector"]:visible, [data-testid="draft-provider-select"]:visible',
+    )
+    .first();
+  if (await providerTrigger.isVisible().catch(() => false)) {
+    const providerText = ((await providerTrigger.innerText().catch(() => "")) ?? "").trim();
+    if (!/codex/i.test(providerText)) {
+      return;
+    }
+  }
+
+  const thinkingTrigger = page.getByTestId("agent-thinking-selector").first();
+  if (!(await thinkingTrigger.isVisible().catch(() => false))) {
+    return;
+  }
+
+  const currentThinkingLabel = ((await thinkingTrigger.innerText().catch(() => "")) ?? "")
+    .trim()
+    .toLowerCase();
+  if (/\b(low|minimal|off)\b/.test(currentThinkingLabel)) {
+    return;
+  }
+
+  await thinkingTrigger.click();
+  const menu = page.getByTestId("agent-thinking-menu").first();
+  if (!(await menu.isVisible().catch(() => false))) {
+    return;
+  }
+
+  const preferredLabels = ["low", "minimal", "off", "medium"];
+  let selected = false;
+  for (const label of preferredLabels) {
+    const option = menu
+      .getByRole("button", { name: new RegExp(`^${escapeRegex(label)}$`, "i") })
+      .first();
+    if (await option.isVisible().catch(() => false)) {
+      await option.click({ force: true });
+      selected = true;
+      break;
+    }
+  }
+
+  if (!selected) {
+    const options = menu.getByRole("button");
+    const count = await options.count();
+    for (let index = 0; index < count; index += 1) {
+      const option = options.nth(index);
+      const label = ((await option.innerText().catch(() => "")) ?? "").trim();
+      if (!label) {
+        continue;
+      }
+      if (label.toLowerCase() === currentThinkingLabel) {
+        continue;
+      }
+      await option.click({ force: true });
+      selected = true;
+      break;
+    }
+  }
+
+  if (!selected) {
+    await page.keyboard.press("Escape").catch(() => undefined);
+    return;
+  }
+
+  await expect(menu).not.toBeVisible({ timeout: 5000 });
+}
+
 export interface AgentConfig {
   directory: string;
   provider?: string;
@@ -374,54 +493,124 @@ export interface AgentConfig {
 }
 
 export const selectProvider = async (page: Page, provider: string) => {
-  const providerLabel = page.getByText('PROVIDER', { exact: true }).first();
-  await expect(providerLabel).toBeVisible();
-  await providerLabel.click();
+  const normalizedProvider = provider.trim();
+  if (!normalizedProvider) {
+    throw new Error("Provider must be a non-empty string.");
+  }
 
-  const option = page.getByText(provider, { exact: true }).first();
+  const providerTrigger = page
+    .locator(
+      '[data-testid="agent-provider-selector"]:visible, [data-testid="draft-provider-select"]:visible',
+    )
+    .first();
+  if (
+    await providerTrigger
+      .getByText(new RegExp(`^${escapeRegex(normalizedProvider)}$`, "i"))
+      .first()
+      .isVisible()
+      .catch(() => false)
+  ) {
+    return;
+  }
+
+  if (await providerTrigger.isVisible().catch(() => false)) {
+    await providerTrigger.click();
+  } else {
+    const providerLabel = page.getByText("PROVIDER", { exact: true }).first();
+    await expect(providerLabel).toBeVisible();
+    await providerLabel.click();
+  }
+
+  const dialog = page.getByRole("dialog").last();
+  const searchInput = dialog.getByRole("textbox", { name: /search provider/i }).first();
+  if (await searchInput.isVisible().catch(() => false)) {
+    await searchInput.fill(normalizedProvider);
+  }
+
+  const option = dialog.getByText(new RegExp(`^${escapeRegex(normalizedProvider)}$`, "i")).first();
   await expect(option).toBeVisible();
   await option.click();
 };
 
 export const selectModel = async (page: Page, model: string) => {
-  const modelLabel = page.getByText('MODEL', { exact: true }).first();
-  await expect(modelLabel).toBeVisible();
-  await modelLabel.click();
+  const normalizedModel = model.trim();
+  if (!normalizedModel) {
+    throw new Error("Model must be a non-empty string.");
+  }
+
+  const modelTrigger = page
+    .locator(
+      '[data-testid="agent-model-selector"]:visible, [data-testid="draft-model-select"]:visible',
+    )
+    .first();
+  if (
+    await modelTrigger
+      .getByText(new RegExp(`^${escapeRegex(normalizedModel)}$`, "i"))
+      .first()
+      .isVisible()
+      .catch(() => false)
+  ) {
+    return;
+  }
+
+  if (await modelTrigger.isVisible().catch(() => false)) {
+    await modelTrigger.click();
+  } else {
+    const modelLabel = page.getByText("MODEL", { exact: true }).first();
+    await expect(modelLabel).toBeVisible();
+    await modelLabel.click();
+  }
 
   // Wait for the model dropdown to open
-  const searchInput = page.getByRole('textbox', { name: /search model/i });
+  const searchInput = page.getByRole("textbox", { name: /search model/i });
   await expect(searchInput).toBeVisible({ timeout: 10000 });
 
   // Type to search/filter models
-  await searchInput.fill(model);
+  await searchInput.fill(normalizedModel);
 
-  const dialog = page.getByRole('dialog');
-  const option = dialog
-    .getByText(new RegExp(`^${escapeRegex(model)}$`, 'i'))
+  const dialog = page.getByRole("dialog");
+  const exactOption = dialog
+    .getByText(new RegExp(`^${escapeRegex(normalizedModel)}$`, "i"))
     .first();
-  await expect(option).toBeVisible({ timeout: 30000 });
-  await option.click({ force: true });
+  const exactVisible = await exactOption.isVisible().catch(() => false);
+  if (exactVisible) {
+    await exactOption.click({ force: true });
+  } else {
+    // Modern labels include version suffixes (for example "Haiku 4.5"), so
+    // select the first filtered result using keyboard confirm.
+    await searchInput.press("Enter");
+  }
 
   // Wait for dropdown to close
+  if (await searchInput.isVisible().catch(() => false)) {
+    await page.keyboard.press("Escape").catch(() => undefined);
+  }
   await expect(searchInput).not.toBeVisible({ timeout: 5000 });
 };
 
 export const selectMode = async (page: Page, mode: string) => {
-  const modeLabel = page.getByText('MODE', { exact: true }).first();
-  await expect(modeLabel).toBeVisible();
-  await modeLabel.click();
+  const modeTrigger = page
+    .locator(
+      '[data-testid="agent-mode-selector"]:visible, [data-testid="draft-mode-select"]:visible',
+    )
+    .first();
+  if (await modeTrigger.isVisible().catch(() => false)) {
+    await modeTrigger.click();
+  } else {
+    const modeLabel = page.getByText("MODE", { exact: true }).first();
+    await expect(modeLabel).toBeVisible();
+    await modeLabel.click();
+  }
 
   // Wait for the mode dropdown to open
-  const searchInput = page.getByRole('textbox', { name: /search mode/i });
+  const searchInput = page.getByRole("textbox", { name: /search mode/i });
   await expect(searchInput).toBeVisible({ timeout: 10000 });
 
   // Type to filter modes
   await searchInput.fill(mode);
 
-  const dialog = page.getByRole('dialog');
-  const option = dialog
-    .getByText(new RegExp(`^${escapeRegex(mode)}$`, 'i'))
-    .first();
+  const dialog = page.getByRole("dialog");
+  const option = dialog.getByText(new RegExp(`^${escapeRegex(mode)}$`, "i")).first();
   await expect(option).toBeVisible();
   await option.click({ force: true });
 
@@ -449,26 +638,36 @@ export const createAgentWithConfig = async (page: Page, config: AgentConfig) =>
   await createAgent(page, config.prompt);
 };
 
+export const createAgentInRepo = async (
+  page: Page,
+  config: Pick<AgentConfig, "directory" | "prompt">,
+) => {
+  await gotoHome(page);
+  await ensureHostSelected(page);
+  await setWorkingDirectory(page, config.directory);
+  await createAgent(page, config.prompt);
+};
+
 export const waitForPermissionPrompt = async (page: Page, timeout = 30000) => {
-  const promptText = page.getByTestId('permission-request-question').first();
+  const promptText = page.getByTestId("permission-request-question").first();
   await expect(promptText).toBeVisible({ timeout });
 };
 
 export const allowPermission = async (page: Page) => {
-  const acceptButton = page.getByTestId('permission-request-accept').first();
+  const acceptButton = page.getByTestId("permission-request-accept").first();
   await expect(acceptButton).toBeVisible({ timeout: 5000 });
   await acceptButton.click();
 };
 
 export const denyPermission = async (page: Page) => {
-  const denyButton = page.getByTestId('permission-request-deny').first();
+  const denyButton = page.getByTestId("permission-request-deny").first();
   await expect(denyButton).toBeVisible({ timeout: 5000 });
   await denyButton.click();
 };
 
 export async function waitForAgentFinishUI(page: Page, timeout = 30000) {
   // Wait for the stop button to disappear
-  const stopButton = page.getByRole('button', { name: /stop|cancel/i });
+  const stopButton = page.getByRole("button", { name: /stop|cancel/i });
 
   // First, let's debug what's happening - wait a bit to see the state
   await page.waitForTimeout(2000);
@@ -485,9 +684,11 @@ export async function waitForAgentFinishUI(page: Page, timeout = 30000) {
     const toolCallResult = page.getByText(/permission.*denied|denied|blocked/i);
 
     // Wait for the tool call result to appear
-    await expect(toolCallResult).toBeVisible({ timeout: 10000 }).catch(() => {
-      // If no specific message, just wait for the button to disappear
-    });
+    await expect(toolCallResult)
+      .toBeVisible({ timeout: 10000 })
+      .catch(() => {
+        // If no specific message, just wait for the button to disappear
+      });
 
     // Now wait for the stop button to disappear
     await expect(stopButton).not.toBeVisible({ timeout });

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

@@ -0,0 +1,257 @@
+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 { waitForWorkspaceTabsVisible } from "./workspace-tabs";
+import { buildHostAgentDetailRoute, buildHostSessionsRoute, buildHostWorkspaceRoute } from "@/utils/host-routes";
+
+export type ArchiveTabAgent = {
+  id: string;
+  title: string;
+  cwd: string;
+};
+
+type 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 }>;
+};
+
+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()}`,
+      nowIso,
+    }),
+    preferences: buildCreateAgentPreferences(getServerId()),
+  };
+}
+
+async function loadDaemonClientConstructor(): Promise<
+  new (config: {
+    url: string;
+    clientId: string;
+    clientType: "cli";
+  }) => ArchiveTabDaemonClient
+> {
+  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";
+    }) => ArchiveTabDaemonClient;
+  };
+  return mod.DaemonClient;
+}
+
+export async function connectArchiveTabDaemonClient(): Promise<ArchiveTabDaemonClient> {
+  const DaemonClient = await loadDaemonClientConstructor();
+  const client = new DaemonClient({
+    url: getDaemonWsUrl(),
+    clientId: `app-e2e-archive-tab-${randomUUID()}`,
+    clientType: "cli",
+  });
+  await client.connect();
+  return client;
+}
+
+export async function createIdleAgent(
+  client: ArchiveTabDaemonClient,
+  input: { cwd: string; title: string },
+): Promise<ArchiveTabAgent> {
+  const created = await client.createAgent({
+    provider: "codex",
+    model: "gpt-5.1-codex-mini",
+    thinkingOptionId: "low",
+    modeId: "full-access",
+    cwd: input.cwd,
+    title: input.title,
+    initialPrompt: "Reply with exactly READY.",
+  });
+  const finished = await client.waitForFinish(created.id, 120_000);
+  if (finished.status !== "idle") {
+    throw new Error(`Expected agent ${created.id} to become idle, got ${finished.status}.`);
+  }
+  return {
+    id: created.id,
+    title: input.title,
+    cwd: input.cwd,
+  };
+}
+
+export async function archiveAgentFromDaemon(
+  client: ArchiveTabDaemonClient,
+  agentId: string,
+): Promise<void> {
+  await client.archiveAgent(agentId);
+}
+
+export async function primeAdditionalPage(page: Page): Promise<void> {
+  const seedNonce = randomUUID();
+  const { daemon, preferences } = buildSeededStoragePayload();
+
+  await page.route(/:(6767)\b/, (route) => route.abort());
+  await page.routeWebSocket(/:(6767)\b/, async (ws) => {
+    await ws.close({ code: 1008, reason: "Blocked connection to localhost:6767 during e2e." });
+  });
+  await page.addInitScript(
+    ({ daemon, preferences, seedNonce }) => {
+      const disableOnceKey = "@paseo:e2e-disable-default-seed-once";
+      const disableValue = localStorage.getItem(disableOnceKey);
+      if (disableValue) {
+        localStorage.removeItem(disableOnceKey);
+        if (disableValue === seedNonce) {
+          return;
+        }
+      }
+
+      localStorage.setItem("@paseo:e2e", "1");
+      localStorage.setItem("@paseo:e2e-seed-nonce", seedNonce);
+      localStorage.setItem("@paseo:daemon-registry", JSON.stringify([daemon]));
+      localStorage.removeItem("@paseo:settings");
+      localStorage.setItem("@paseo:create-agent-preferences", JSON.stringify(preferences));
+    },
+    { daemon, preferences, seedNonce },
+  );
+  await page.goto("/");
+}
+
+export async function resetSeededPageState(page: Page): Promise<void> {
+  const { daemon, preferences } = buildSeededStoragePayload();
+  await page.goto("/");
+  await page.evaluate(
+    ({ daemon, preferences }) => {
+      localStorage.clear();
+      localStorage.setItem("@paseo:e2e", "1");
+      localStorage.setItem("@paseo:daemon-registry", JSON.stringify([daemon]));
+      localStorage.setItem("@paseo:create-agent-preferences", JSON.stringify(preferences));
+      localStorage.removeItem("@paseo:settings");
+    },
+    { daemon, preferences },
+  );
+  await page.goto("/");
+}
+
+export async function openWorkspaceWithAgents(
+  page: Page,
+  agents: [ArchiveTabAgent, ArchiveTabAgent],
+): Promise<void> {
+  const serverId = getServerId();
+  for (const agent of agents) {
+    await page.goto(buildHostAgentDetailRoute(serverId, agent.id, agent.cwd));
+    await waitForWorkspaceTabsVisible(page);
+    await expectWorkspaceTabVisible(page, agent.id);
+  }
+}
+
+export async function expectWorkspaceTabVisible(page: Page, agentId: string): Promise<void> {
+  await expect(page.getByTestId(`workspace-tab-agent_${agentId}`).first()).toBeVisible({
+    timeout: 30_000,
+  });
+}
+
+export async function expectWorkspaceTabHidden(page: Page, agentId: string): Promise<void> {
+  await expect(page.getByTestId(`workspace-tab-agent_${agentId}`)).toHaveCount(0, {
+    timeout: 30_000,
+  });
+}
+
+export async function expectWorkspaceArchiveOutcome(
+  page: Page,
+  input: { archivedAgentId: string; survivingAgentId: string },
+): Promise<void> {
+  await expectWorkspaceTabHidden(page, input.archivedAgentId);
+  await expectWorkspaceTabVisible(page, input.survivingAgentId);
+}
+
+export async function reloadWorkspace(page: Page, workspaceId: string): Promise<void> {
+  const serverId = getServerId();
+  await page.goto(buildHostWorkspaceRoute(serverId, workspaceId));
+  await waitForWorkspaceTabsVisible(page);
+}
+
+export async function openSessions(page: Page): Promise<void> {
+  const sessionsButton = page.getByTestId("sidebar-sessions");
+  await expect(sessionsButton).toBeVisible({ timeout: 30_000 });
+  await sessionsButton.click();
+  await expect(page).toHaveURL(new RegExp(`${buildHostSessionsRoute(getServerId())}$`), {
+    timeout: 30_000,
+  });
+  await expect(page.getByText("Sessions", { exact: true }).last()).toBeVisible({
+    timeout: 30_000,
+  });
+}
+
+function getSessionRowByTitle(page: Page, title: string) {
+  return page.locator('[data-testid^="agent-row-"]').filter({ hasText: title }).first();
+}
+
+export async function expectSessionRowVisible(page: Page, title: string): Promise<void> {
+  await expect(getSessionRowByTitle(page, title)).toBeVisible({ timeout: 30_000 });
+}
+
+export async function expectSessionRowArchived(page: Page, title: string): Promise<void> {
+  await expect(getSessionRowByTitle(page, title)).toContainText("Archived", { timeout: 30_000 });
+}
+
+export async function archiveAgentFromSessions(
+  page: Page,
+  input: { agentId: string; title: string },
+): Promise<void> {
+  const row = getSessionRowByTitle(page, input.title);
+  await expect(row).toBeVisible({ timeout: 30_000 });
+  const box = await row.boundingBox();
+  if (!box) {
+    throw new Error(`Could not read bounding box for session row ${input.agentId}.`);
+  }
+
+  await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
+  await page.mouse.down();
+  await page.waitForTimeout(900);
+  await page.mouse.up();
+
+  const archiveButton = page.getByTestId("agent-action-archive").first();
+  await expect(archiveButton).toBeVisible({ timeout: 10_000 });
+  await archiveButton.click();
+  await expectSessionRowArchived(page, input.title);
+}

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

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

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

@@ -0,0 +1,228 @@
+import type { Page } from "@playwright/test";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { randomUUID } from "node:crypto";
+import { buildHostWorkspaceRoute } from "../../src/utils/host-routes";
+
+export type TerminalPerfDaemonClient = {
+  connect(): Promise<void>;
+  close(): Promise<void>;
+  createTerminal(
+    cwd: string,
+    name?: string,
+  ): Promise<{
+    terminal: { id: string; name: string; cwd: string } | null;
+    error: string | null;
+  }>;
+  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;
+}
+
+async function loadDaemonClientConstructor(): Promise<
+  new (config: { url: string; clientId: string; clientType: "cli" }) => TerminalPerfDaemonClient
+> {
+  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";
+    }) => TerminalPerfDaemonClient;
+  };
+  return mod.DaemonClient;
+}
+
+export async function connectTerminalClient(): Promise<TerminalPerfDaemonClient> {
+  const DaemonClient = await loadDaemonClientConstructor();
+  const client = new DaemonClient({
+    url: getDaemonWsUrl(),
+    clientId: `terminal-perf-${randomUUID()}`,
+    clientType: "cli",
+  });
+  await client.connect();
+  return client;
+}
+
+export function buildTerminalWorkspaceUrl(cwd: string, terminalId: string): string {
+  const serverId = getServerId();
+  const route = buildHostWorkspaceRoute(serverId, cwd);
+  return `${route}?open=${encodeURIComponent(`terminal:${terminalId}`)}`;
+}
+
+export async function getTerminalBufferText(page: Page): Promise<string> {
+  return page.evaluate(() => {
+    const term = (window as any).__paseoTerminal;
+    if (!term) {
+      return "";
+    }
+    const buf = term.buffer.active;
+    const lines: string[] = [];
+    for (let i = 0; i < buf.length; i++) {
+      const line = buf.getLine(i);
+      if (line) {
+        lines.push(line.translateToString(true));
+      }
+    }
+    return lines.join("\n");
+  });
+}
+
+export async function waitForTerminalContent(
+  page: Page,
+  predicate: (text: string) => boolean,
+  timeout: number,
+): Promise<void> {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    const text = await getTerminalBufferText(page);
+    if (predicate(text)) {
+      return;
+    }
+    await page.waitForTimeout(50);
+  }
+  throw new Error(`Terminal content did not match predicate within ${timeout}ms`);
+}
+
+export async function navigateToTerminal(
+  page: Page,
+  input: { cwd: string; terminalId: string },
+): Promise<void> {
+  // Boot the app at the workspace route directly.
+  // The fixtures.ts beforeEach addInitScript seeds localStorage on every navigation,
+  // so the daemon registry is already configured when the app starts.
+  const workspaceRoute = buildHostWorkspaceRoute(getServerId(), input.cwd);
+  await page.goto(workspaceRoute);
+
+  // Wait for daemon connection (sidebar shows host label)
+  await page.getByText("localhost", { exact: true }).first().waitFor({ state: "visible", timeout: 15_000 });
+
+  // The workspace should now query listTerminals and discover our terminal.
+  // Click the terminal tab if it auto-appeared, or wait for it.
+  const terminalSurface = page.locator('[data-testid="terminal-surface"]');
+  const surfaceVisible = await terminalSurface.isVisible().catch(() => false);
+
+  if (!surfaceVisible) {
+    // Terminal tab might not be focused — look for it in the tab row and click it
+    const terminalTab = page.locator(`[data-testid="workspace-tab-terminal:${input.terminalId}"]`);
+    const tabExists = await terminalTab.isVisible({ timeout: 5_000 }).catch(() => false);
+
+    if (tabExists) {
+      await terminalTab.click();
+    } else {
+      // Terminal tab not yet created — click "New terminal tab" to create one through the UI
+      const newTerminalBtn = page.getByRole("button", { name: "New terminal tab" });
+      await newTerminalBtn.waitFor({ state: "visible", timeout: 10_000 });
+      await newTerminalBtn.click();
+    }
+  }
+
+  // Wait for terminal surface to be visible
+  await terminalSurface.waitFor({ state: "visible", timeout: 15_000 });
+
+  // Wait for loading overlay to disappear (terminal attached)
+  await page
+    .locator('[data-testid="terminal-attach-loading"]')
+    .waitFor({ state: "hidden", timeout: 10_000 })
+    .catch(() => {
+      // overlay may never appear if attachment is instant
+    });
+
+  await terminalSurface.click();
+}
+
+export async function setupDeterministicPrompt(page: Page, sentinel?: string): Promise<void> {
+  const tag = sentinel ?? `READY_${Date.now()}`;
+  const terminal = page.locator('[data-testid="terminal-surface"]');
+
+  await terminal.pressSequentially(`echo ${tag}\n`, { delay: 0 });
+  await waitForTerminalContent(page, (text) => text.includes(tag), 10_000);
+
+  await terminal.pressSequentially("export PS1='$ '\n", { delay: 0 });
+  await page.waitForTimeout(300);
+}
+
+export type LatencySample = {
+  char: string;
+  latencyMs: number;
+};
+
+/**
+ * Measures keystroke echo round-trip latency.
+ *
+ * Starts a high-resolution timer on the browser keydown event (capture phase)
+ * and stops it when xterm.js finishes parsing the echoed write. This measures
+ * the full path: keydown → WebSocket → daemon PTY echo → WebSocket → xterm render.
+ */
+export async function measureKeystrokeLatency(page: Page, char: string): Promise<number> {
+  await page.evaluate(() => {
+    const term = (window as any).__paseoTerminal;
+    if (!term) {
+      throw new Error("__paseoTerminal not available");
+    }
+
+    const state = ((window as any).__perfKeystroke = {
+      promise: null as Promise<number> | null,
+    });
+
+    state.promise = new Promise<number>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        document.removeEventListener("keydown", onKeyDown, true);
+        reject(new Error("keystroke echo timeout (5s)"));
+      }, 5000);
+
+      function onKeyDown() {
+        document.removeEventListener("keydown", onKeyDown, true);
+        const start = performance.now();
+        const disposable = term.onWriteParsed(() => {
+          clearTimeout(timeout);
+          disposable.dispose();
+          resolve(performance.now() - start);
+        });
+      }
+
+      document.addEventListener("keydown", onKeyDown, true);
+    });
+  });
+
+  await page.keyboard.press(char);
+
+  return page.evaluate(() => (window as any).__perfKeystroke.promise);
+}
+
+export function computePercentile(samples: number[], p: number): number {
+  const sorted = [...samples].sort((a, b) => a - b);
+  const index = Math.ceil((p / 100) * sorted.length) - 1;
+  return sorted[Math.max(0, index)];
+}
+
+export function round2(value: number): number {
+  return Math.round(value * 100) / 100;
+}

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

@@ -0,0 +1,52 @@
+import { expect, type Page } from "@playwright/test";
+
+export async function getWorkspaceTabTestIds(page: Page): Promise<string[]> {
+  const tabs = page.locator('[data-testid^="workspace-tab-"]');
+  const count = await tabs.count();
+  const ids: string[] = [];
+  for (let index = 0; index < count; index += 1) {
+    const testId = await tabs.nth(index).getAttribute("data-testid");
+    if (testId && !ids.includes(testId)) {
+      ids.push(testId);
+    }
+  }
+  return ids;
+}
+
+export async function waitForWorkspaceTabsVisible(page: Page): Promise<void> {
+  await expect(page.getByTestId("workspace-tabs-row").first()).toBeVisible({
+    timeout: 30_000,
+  });
+  await expect(page.getByTestId("workspace-new-agent-tab").first()).toBeVisible({
+    timeout: 30_000,
+  });
+}
+
+export async function ensureWorkspaceAgentPaneVisible(page: Page): Promise<void> {
+  const toggle = page.getByTestId("workspace-explorer-toggle").first();
+  if (!(await toggle.isVisible().catch(() => false))) {
+    return;
+  }
+  const isExpanded = (await toggle.getAttribute("aria-expanded")) === "true";
+  if (isExpanded) {
+    await toggle.click();
+    await expect(toggle).toHaveAttribute("aria-expanded", "false", {
+      timeout: 10_000,
+    });
+  }
+}
+
+export async function sampleWorkspaceTabIds(
+  page: Page,
+  options: { durationMs?: number; intervalMs?: number } = {},
+): Promise<string[][]> {
+  const durationMs = options.durationMs ?? 2_500;
+  const intervalMs = options.intervalMs ?? 50;
+  const snapshots: string[][] = [];
+  const start = Date.now();
+  while (Date.now() - start <= durationMs) {
+    snapshots.push(await getWorkspaceTabTestIds(page));
+    await page.waitForTimeout(intervalMs);
+  }
+  return snapshots;
+}

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

@@ -0,0 +1,74 @@
+import { expect, type Page } from "@playwright/test";
+import { buildHostWorkspaceRoute } from "@/utils/host-routes";
+import { gotoHome } from "./app";
+
+export async function openNewAgentComposer(page: Page): Promise<void> {
+  await gotoHome(page);
+}
+
+export function workspaceLabelFromPath(value: string): string {
+  const normalized = value.replace(/\\/g, "/").replace(/\/+$/, "");
+  const parts = normalized.split("/").filter(Boolean);
+  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]);
+  if (trimmed.startsWith("/var/")) {
+    candidates.add(`/private${trimmed}`);
+  }
+  if (trimmed.startsWith("/private/var/")) {
+    candidates.add(trimmed.replace(/^\/private/, ""));
+  }
+  return Array.from(candidates);
+}
+
+function workspaceRowLocator(page: Page, serverId: string, workspacePath: string) {
+  const ids = candidateWorkspaceIds(workspacePath).map(
+    (id) => `[data-testid="sidebar-workspace-row-${serverId}:${id}"]`,
+  );
+  return page.locator(ids.join(",")).first();
+}
+
+export async function switchWorkspaceViaSidebar(input: {
+  page: Page;
+  serverId: string;
+  targetWorkspacePath: string;
+}): Promise<void> {
+  const row = workspaceRowLocator(input.page, input.serverId, input.targetWorkspacePath);
+  await expect(row).toBeVisible({ timeout: 30_000 });
+  await row.click();
+
+  const targetWorkspaceRoute = buildHostWorkspaceRoute(input.serverId, input.targetWorkspacePath);
+  await expect(input.page).toHaveURL(new RegExp(escapeRegex(targetWorkspaceRoute)), {
+    timeout: 30_000,
+  });
+}
+
+export async function expectWorkspaceHeader(
+  page: Page,
+  input: { title: string; subtitle: string },
+): Promise<void> {
+  const titleLocator = page.getByTestId("workspace-header-title");
+  const subtitleLocator = page.getByTestId("workspace-header-subtitle");
+
+  await expect(titleLocator.first()).toHaveText(input.title, {
+    timeout: 30_000,
+  });
+  await expect(subtitleLocator.first()).toHaveText(input.subtitle, {
+    timeout: 30_000,
+  });
+}
+
+export async function seedWorkspaceActivity(page: Page, marker: string): Promise<void> {
+  const input = page.getByRole("textbox", { name: "Message agent..." });
+  await expect(input).toBeEditable({ timeout: 30_000 });
+  await input.fill(marker);
+  await input.press("Enter");
+  await expect(page).toHaveURL(/\/workspace\//, { timeout: 30_000 });
+}

packages/app/e2e/helpers/workspace.ts

@@ -1,7 +1,7 @@
-import { execSync } from 'node:child_process';
-import { mkdtemp, writeFile, rm, mkdir } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import path from 'node:path';
+import { execSync } from "node:child_process";
+import { mkdtemp, writeFile, rm, mkdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
 
 type TempRepo = {
   path: string;
@@ -9,26 +9,29 @@ type TempRepo = {
 };
 
 export const createTempGitRepo = async (
-  prefix = 'paseo-e2e-',
-  options?: { withRemote?: boolean }
+  prefix = "paseo-e2e-",
+  options?: { withRemote?: boolean },
 ): Promise<TempRepo> => {
-  const repoPath = await mkdtemp(path.join(tmpdir(), prefix));
+  // Keep E2E repo paths short so terminal prompt + typed commands stay visible without zsh clipping.
+  const tempRoot = process.platform === "win32" ? tmpdir() : "/tmp";
+  const repoPath = await mkdtemp(path.join(tempRoot, prefix));
   const withRemote = options?.withRemote ?? false;
 
-  execSync('git init -b main', { cwd: repoPath, stdio: 'ignore' });
-  execSync('git config user.email "e2e@paseo.test"', { cwd: repoPath, stdio: 'ignore' });
-  execSync('git config user.name "Paseo E2E"', { cwd: repoPath, stdio: 'ignore' });
-  await writeFile(path.join(repoPath, 'README.md'), '# Temp Repo\n');
-  execSync('git add README.md', { cwd: repoPath, stdio: 'ignore' });
-  execSync('git commit -m "Initial commit"', { cwd: repoPath, stdio: 'ignore' });
+  execSync("git init -b main", { cwd: repoPath, stdio: "ignore" });
+  execSync('git config user.email "e2e@paseo.test"', { cwd: repoPath, stdio: "ignore" });
+  execSync('git config user.name "Paseo E2E"', { cwd: repoPath, stdio: "ignore" });
+  execSync("git config commit.gpgsign false", { cwd: repoPath, stdio: "ignore" });
+  await writeFile(path.join(repoPath, "README.md"), "# Temp Repo\n");
+  execSync("git add README.md", { cwd: repoPath, stdio: "ignore" });
+  execSync('git commit -m "Initial commit"', { cwd: repoPath, stdio: "ignore" });
 
   if (withRemote) {
     // Deterministic local remote to avoid relying on external auth/network in e2e.
-    const remoteDir = path.join(repoPath, 'remote.git');
+    const remoteDir = path.join(repoPath, "remote.git");
     await mkdir(remoteDir, { recursive: true });
-    execSync(`git init --bare -b main ${remoteDir}`, { cwd: repoPath, stdio: 'ignore' });
-    execSync(`git remote add origin ${remoteDir}`, { cwd: repoPath, stdio: 'ignore' });
-    execSync('git push -u origin main', { cwd: repoPath, stdio: 'ignore' });
+    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 main", { cwd: repoPath, stdio: "ignore" });
   }
 
   return {

packages/app/e2e/host-onboarding-direct.spec.ts

@@ -1,42 +0,0 @@
-import { test, expect } from './fixtures';
-
-test('no hosts shows welcome; direct connection adds host and lands on agent create', async ({ page }) => {
-  const daemonPort = process.env.E2E_DAEMON_PORT;
-  const serverId = process.env.E2E_SERVER_ID;
-  if (!daemonPort) {
-    throw new Error('E2E_DAEMON_PORT is not set (expected from globalSetup).');
-  }
-  if (!serverId) {
-    throw new Error('E2E_SERVER_ID is not set (expected from globalSetup).');
-  }
-
-  await page.addInitScript(() => {
-    localStorage.setItem('@paseo:daemon-registry', JSON.stringify([]));
-    localStorage.removeItem('@paseo:create-agent-preferences');
-    localStorage.removeItem('@paseo:settings');
-  });
-
-  await page.goto('/');
-
-  await expect(page.getByText('Welcome to Paseo', { exact: true })).toBeVisible();
-
-  await page.getByText('Direct connection', { exact: true }).click();
-
-  await page.getByPlaceholder('host:6767').fill(`127.0.0.1:${daemonPort}`);
-
-  await page.getByText('Connect', { exact: true }).click();
-
-  // First-time connection prompts for an optional label.
-  const nameModal = page.getByTestId('name-host-modal');
-  const showedNameModal = await nameModal
-    .waitFor({ state: 'visible', timeout: 5000 })
-    .then(() => true)
-    .catch(() => false);
-  if (showedNameModal) {
-    await nameModal.getByTestId('name-host-skip').click();
-  }
-
-  await expect(page.getByTestId('sidebar-new-agent')).toBeVisible();
-  await expect(page.getByText(serverId, { exact: true })).toBeVisible();
-  await expect(page.getByText('Online', { exact: true })).toBeVisible({ timeout: 15000 });
-});

packages/app/e2e/host-removal.spec.ts

@@ -1,109 +0,0 @@
-import { test, expect } from './fixtures';
-
-test('host removal removes the host from UI and persists after reload', async ({ page }) => {
-  const daemonPort = process.env.E2E_DAEMON_PORT;
-  const seededServerId = process.env.E2E_SERVER_ID;
-  if (!daemonPort) {
-    throw new Error('E2E_DAEMON_PORT is not set (expected from globalSetup).');
-  }
-  if (!seededServerId) {
-    throw new Error('E2E_SERVER_ID is not set (expected from globalSetup).');
-  }
-
-  const extraPort = Number(daemonPort) + 1;
-  const extraEndpoint = `127.0.0.1:${extraPort}`;
-  const nowIso = new Date().toISOString();
-
-  const extraDaemon = {
-    serverId: 'srv_e2e_extra_daemon',
-    label: 'extra',
-    connections: [
-      { id: `direct:${extraEndpoint}`, type: 'direct', endpoint: extraEndpoint },
-    ],
-    preferredConnectionId: `direct:${extraEndpoint}`,
-    createdAt: nowIso,
-    updatedAt: nowIso,
-  };
-
-  const seededTestDaemon = {
-    serverId: seededServerId,
-    label: 'localhost',
-    connections: [
-      { id: `direct:127.0.0.1:${daemonPort}`, type: 'direct', endpoint: `127.0.0.1:${daemonPort}` },
-    ],
-    preferredConnectionId: `direct:127.0.0.1:${daemonPort}`,
-    createdAt: nowIso,
-    updatedAt: nowIso,
-  };
-
-  const seedOnceKey = `@paseo:e2e-host-removal-seeded:${Math.random().toString(36).slice(2)}`;
-
-  // Add a second host once (fixtures seed the primary host on every navigation).
-  await page.addInitScript(
-    ({ daemon, seededTestDaemon, seedOnceKey }) => {
-      if (localStorage.getItem(seedOnceKey)) {
-        return;
-      }
-
-      const raw = localStorage.getItem('@paseo:daemon-registry');
-      let parsed: any[] = [];
-      if (raw) {
-        try {
-          parsed = JSON.parse(raw);
-        } catch {
-          parsed = [];
-        }
-      }
-      const list = Array.isArray(parsed) ? parsed : [];
-      localStorage.setItem(seedOnceKey, '1');
-
-      const next = [...list];
-      const hasSeeded = next.some((entry: any) => entry && entry.serverId === seededTestDaemon.serverId);
-      if (!hasSeeded) {
-        next.push(seededTestDaemon);
-      }
-
-      const alreadyPresent = next.some((entry: any) => entry && entry.serverId === daemon.serverId);
-      if (!alreadyPresent) {
-        next.push(daemon);
-      }
-
-      localStorage.setItem('@paseo:daemon-registry', JSON.stringify(next));
-    },
-    { daemon: extraDaemon, seededTestDaemon, seedOnceKey }
-  );
-
-  await page.goto('/settings');
-
-  await expect(page.getByText('extra', { exact: true }).first()).toBeVisible();
-  await expect(page.getByText(extraEndpoint, { exact: true }).first()).toBeVisible();
-
-  await page.getByTestId(`daemon-menu-trigger-${extraDaemon.serverId}`).click();
-  await page.getByTestId(`daemon-menu-remove-${extraDaemon.serverId}`).click();
-  await expect(page.getByTestId('remove-host-confirm-modal')).toBeVisible();
-  await page.getByTestId('remove-host-confirm').click();
-
-  await expect(page.getByText(extraEndpoint, { exact: true })).toHaveCount(0);
-  await page.waitForFunction(
-    (serverId) => {
-      const raw = localStorage.getItem('@paseo:daemon-registry');
-      if (!raw) return false;
-      try {
-        const parsed = JSON.parse(raw);
-        return Array.isArray(parsed) && !parsed.some((entry: any) => entry && entry.serverId === serverId);
-      } catch {
-        return false;
-      }
-    },
-    extraDaemon.serverId,
-    { timeout: 10000 }
-  );
-
-  // Prevent the fixture from overwriting storage on reload; verify persistence.
-  await page.evaluate(() => {
-    const nonce = localStorage.getItem('@paseo:e2e-seed-nonce') ?? '1';
-    localStorage.setItem('@paseo:e2e-disable-default-seed-once', nonce);
-  });
-  await page.reload();
-  await expect(page.getByText(extraEndpoint, { exact: true })).toHaveCount(0);
-});

packages/app/e2e/host-selection.spec.ts

@@ -1,118 +0,0 @@
-import { test, expect } from './fixtures';
-import { ensureHostSelected, gotoHome } from './helpers/app';
-
-test('new agent auto-selects the previous host', async ({ page }) => {
-  await gotoHome(page);
-  await ensureHostSelected(page);
-
-  await gotoHome(page);
-
-  // The selected host should be restored after a full reload without manual selection.
-  await expect(page.getByText('localhost', { exact: true }).first()).toBeVisible();
-  const input = page.getByRole('textbox', { name: 'Message agent...' });
-  await expect(input).toBeEditable({ timeout: 30000 });
-});
-
-test('new agent respects serverId in the URL', async ({ page }) => {
-  const daemonPort = process.env.E2E_DAEMON_PORT;
-  const serverId = process.env.E2E_SERVER_ID;
-  if (!daemonPort) {
-    throw new Error('E2E_DAEMON_PORT is not set (expected from globalSetup).');
-  }
-  if (!serverId) {
-    throw new Error('E2E_SERVER_ID is not set (expected from globalSetup).');
-  }
-
-  // Ensure this test's storage is deterministic even under parallel load.
-  const nowIso = new Date().toISOString();
-  const testDaemon = {
-    serverId,
-    label: 'localhost',
-    connections: [
-      {
-        id: `direct:127.0.0.1:${daemonPort}`,
-        type: 'direct',
-        endpoint: `127.0.0.1:${daemonPort}`,
-      },
-    ],
-    preferredConnectionId: `direct:127.0.0.1:${daemonPort}`,
-    createdAt: nowIso,
-    updatedAt: nowIso,
-  };
-  const createAgentPreferences = {
-    serverId: testDaemon.serverId,
-    provider: 'claude',
-    providerPreferences: {
-      claude: { model: 'haiku' },
-      codex: { model: 'gpt-5.1-codex-mini' },
-    },
-  };
-
-  await page.goto('/settings');
-  await page.evaluate(
-    ({ daemon, preferences }) => {
-      const nonce = localStorage.getItem('@paseo:e2e-seed-nonce') ?? '1';
-      localStorage.setItem('@paseo:e2e-disable-default-seed-once', nonce);
-      localStorage.setItem('@paseo:daemon-registry', JSON.stringify([daemon]));
-      localStorage.setItem('@paseo:create-agent-preferences', JSON.stringify(preferences));
-      localStorage.removeItem('@paseo:settings');
-    },
-    { daemon: testDaemon, preferences: createAgentPreferences }
-  );
-  await page.reload();
-  await expect(page.getByText('Online', { exact: true }).first()).toBeVisible({ timeout: 20000 });
-
-  await page.goto(`/?serverId=${encodeURIComponent(serverId)}`);
-  await expect(page.getByText('New agent', { exact: true }).first()).toBeVisible();
-
-  const input = page.getByRole('textbox', { name: 'Message agent...' });
-  await expect(input).toBeEditable({ timeout: 30000 });
-});
-
-test('new agent auto-selects first online host when no preference is stored', async ({ page }) => {
-  const daemonPort = process.env.E2E_DAEMON_PORT;
-  const serverId = process.env.E2E_SERVER_ID;
-  if (!daemonPort) {
-    throw new Error('E2E_DAEMON_PORT is not set (expected from globalSetup).');
-  }
-  if (!serverId) {
-    throw new Error('E2E_SERVER_ID is not set (expected from globalSetup).');
-  }
-
-  const nowIso = new Date().toISOString();
-  const testDaemon = {
-    serverId,
-    label: 'localhost',
-    connections: [
-      {
-        id: `direct:127.0.0.1:${daemonPort}`,
-        type: 'direct',
-        endpoint: `127.0.0.1:${daemonPort}`,
-      },
-    ],
-    preferredConnectionId: `direct:127.0.0.1:${daemonPort}`,
-    createdAt: nowIso,
-    updatedAt: nowIso,
-  };
-
-  await page.goto('/');
-  await page.evaluate(
-    ({ daemon }) => {
-      const nonce = localStorage.getItem('@paseo:e2e-seed-nonce') ?? '1';
-      localStorage.setItem('@paseo:e2e-disable-default-seed-once', nonce);
-      localStorage.setItem('@paseo:daemon-registry', JSON.stringify([daemon]));
-      localStorage.removeItem('@paseo:create-agent-preferences');
-      localStorage.removeItem('@paseo:settings');
-    },
-    { daemon: testDaemon }
-  );
-
-  await page.reload();
-  await expect(page.getByText('New agent', { exact: true }).first()).toBeVisible();
-  await expect(page.getByText('Online', { exact: true }).first()).toBeVisible({ timeout: 20000 });
-
-  // Host should be auto-selected (no manual selection required).
-  await expect(page.getByText('localhost', { exact: true }).first()).toBeVisible();
-  const input = page.getByRole('textbox', { name: 'Message agent...' });
-  await expect(input).toBeEditable({ timeout: 30000 });
-});

packages/app/e2e/keyboard-shortcuts-dialog.spec.ts

@@ -1,17 +0,0 @@
-import { test, expect } from "./fixtures";
-import { gotoHome } from "./helpers/app";
-
-test("question mark opens keyboard shortcuts dialog", async ({ page }) => {
-  await gotoHome(page);
-  await page.getByTestId("menu-button").first().focus();
-
-  await page.keyboard.press("Shift+/");
-
-  const dialog = page.getByTestId("keyboard-shortcuts-dialog");
-  const content = page.getByTestId("keyboard-shortcuts-dialog-content");
-
-  await expect(dialog).toBeVisible({ timeout: 10000 });
-  await expect(content).toBeVisible({ timeout: 10000 });
-  await expect(content).toContainText("Show keyboard shortcuts");
-  await expect(content).toContainText("Toggle left sidebar");
-});

packages/app/e2e/manual-host-port.spec.ts

@@ -1,58 +0,0 @@
-import { test, expect } from './fixtures';
-
-test('manual host add accepts host:port only and persists a direct connection', async ({ page }) => {
-  const daemonPort = process.env.E2E_DAEMON_PORT;
-  const serverId = process.env.E2E_SERVER_ID;
-  if (!daemonPort) {
-    throw new Error('E2E_DAEMON_PORT is not set (expected from globalSetup).');
-  }
-  if (!serverId) {
-    throw new Error('E2E_SERVER_ID is not set (expected from globalSetup).');
-  }
-
-  // Override the default fixture seeding for this navigation (must run before app boot).
-  await page.addInitScript(() => {
-    localStorage.setItem('@paseo:daemon-registry', JSON.stringify([]));
-    localStorage.removeItem('@paseo:settings');
-  });
-  await page.goto('/settings');
-
-  await page.getByText('+ Add connection', { exact: true }).click();
-  await page.getByText('Direct connection', { exact: true }).click();
-
-  const input = page.getByPlaceholder('host:6767');
-  await expect(input).toBeVisible();
-  await input.fill(`127.0.0.1:${daemonPort}`);
-
-  await page.getByText('Connect', { exact: true }).click();
-
-  const nameModal = page.getByTestId('name-host-modal');
-  await expect(nameModal).toBeVisible({ timeout: 15000 });
-  await nameModal.getByTestId('name-host-skip').click();
-
-  await expect(page.getByTestId('sidebar-new-agent')).toBeVisible();
-  await expect(page.getByText('Online', { exact: true })).toBeVisible({ timeout: 15000 });
-
-  await page.waitForFunction(
-    ({ port, serverId }) => {
-      const raw = localStorage.getItem('@paseo:daemon-registry');
-      if (!raw) return false;
-      try {
-        const parsed = JSON.parse(raw);
-        if (!Array.isArray(parsed) || parsed.length !== 1) return false;
-        const entry = parsed[0];
-        return (
-          entry?.serverId === serverId &&
-          Array.isArray(entry?.connections) &&
-          entry.connections.some(
-            (conn: any) => conn?.type === 'direct' && conn?.endpoint === `127.0.0.1:${port}`
-          )
-        );
-      } catch {
-        return false;
-      }
-    },
-    { port: daemonPort, serverId },
-    { timeout: 10000 }
-  );
-});

packages/app/e2e/pairing-offer-parsing.spec.ts

@@ -1,68 +0,0 @@
-import { test, expect } from './fixtures';
-import { Buffer } from 'node:buffer';
-
-function encodeBase64Url(input: string): string {
-  return Buffer.from(input, 'utf8')
-    .toString('base64')
-    .replace(/\+/g, '-')
-    .replace(/\//g, '_')
-    .replace(/=+$/g, '');
-}
-
-test('pairing flow accepts #offer=ConnectionOfferV2 and stores relay-only host', async ({ page }) => {
-  // Override the default fixture seeding for this test.
-  await page.goto('/settings');
-  await page.evaluate(() => {
-    const nonce = localStorage.getItem('@paseo:e2e-seed-nonce') ?? '1';
-    localStorage.setItem('@paseo:e2e-disable-default-seed-once', nonce);
-    localStorage.setItem('@paseo:daemon-registry', JSON.stringify([]));
-    localStorage.removeItem('@paseo:settings');
-  });
-  await page.reload();
-
-  const offer = {
-    v: 2 as const,
-    serverId: 'e2e-server-123',
-    daemonPublicKeyB64: Buffer.from('e2e-public-key', 'utf8').toString('base64'),
-    relay: { endpoint: 'relay.local:443' },
-  };
-
-  const offerUrl = `https://app.paseo.sh/#offer=${encodeBase64Url(JSON.stringify(offer))}`;
-
-  await page.getByText('+ Add connection', { exact: true }).click();
-  await page.getByText('Paste pairing link', { exact: true }).click();
-
-  const input = page.getByPlaceholder('https://app.paseo.sh/#offer=...');
-  await expect(input).toBeVisible();
-  await input.fill(offerUrl);
-
-  await page.getByText('Pair', { exact: true }).click();
-
-  await expect(page.getByTestId('sidebar-new-agent')).toBeVisible();
-
-  await page.waitForFunction(
-    ({ expected }) => {
-      const raw = localStorage.getItem('@paseo:daemon-registry');
-      if (!raw) return false;
-      try {
-        const parsed = JSON.parse(raw);
-        if (!Array.isArray(parsed) || parsed.length !== 1) return false;
-        const entry = parsed[0];
-        const relayId = `relay:${expected.relay.endpoint}`;
-        return (
-          entry?.serverId === expected.serverId &&
-          Array.isArray(entry?.connections) &&
-          entry.connections.length === 1 &&
-          entry.connections[0]?.id === relayId &&
-          entry.connections[0]?.type === 'relay' &&
-          entry.connections[0]?.relayEndpoint === expected.relay.endpoint &&
-          entry.connections[0]?.daemonPublicKeyB64 === expected.daemonPublicKeyB64
-        );
-      } catch {
-        return false;
-      }
-    },
-    { expected: offer },
-    { timeout: 10000 }
-  );
-});

packages/app/e2e/permission-prompt.spec.ts

@@ -1,93 +0,0 @@
-import { existsSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
-import path from 'node:path';
-import { test, expect } from './fixtures';
-import {
-  createAgentWithConfig,
-  waitForPermissionPrompt,
-  allowPermission,
-  denyPermission,
-} from './helpers/app';
-import { createTempGitRepo } from './helpers/workspace';
-
-const FILE_CONTENT = 'Hello from permission test';
-
-function buildWriteCommand(filePath: string): string {
-  return `bash -lc 'sleep 2; printf "${FILE_CONTENT}" > "${filePath}"'`;
-}
-
-test.describe('permission prompts', () => {
-  test('allow permission creates the file', async ({ page }) => {
-    const repo = await createTempGitRepo();
-    const uniqueFilename = `test-allow-${Date.now()}.txt`;
-    const filePath = path.join(repo.path, uniqueFilename);
-    const shellCommand = buildWriteCommand(filePath);
-    const prompt = [
-      `Use your shell tool to run exactly this command:`,
-      shellCommand,
-      `Do not write outside this exact path.`,
-    ].join(' ');
-
-    try {
-      await createAgentWithConfig(page, {
-        directory: repo.path,
-        model: 'haiku',
-        mode: 'Always Ask',
-        prompt,
-      });
-
-      await waitForPermissionPrompt(page, 30000);
-
-      await allowPermission(page);
-
-      // Wait for file to be created
-      await expect
-        .poll(() => existsSync(filePath), {
-          message: `File ${filePath} should exist after allowing permission`,
-          timeout: 30000,
-        })
-        .toBe(true);
-
-      // After allowing, the file should be created successfully
-      // The tool call count might still be 1 if the UI updates quickly
-      const fileContent = await readFile(filePath, 'utf-8');
-      expect(fileContent.trim()).toBe(FILE_CONTENT);
-    } finally {
-      await repo.cleanup();
-    }
-  });
-
-  test('deny permission does not create the file', async ({ page }) => {
-    const repo = await createTempGitRepo();
-    const uniqueFilename = `test-deny-${Date.now()}.txt`;
-    const filePath = path.join(repo.path, uniqueFilename);
-    const shellCommand = buildWriteCommand(filePath);
-    const prompt = [
-      `Use your shell tool to run exactly this command:`,
-      shellCommand,
-      `Do not write outside this exact path.`,
-    ].join(' ');
-
-    try {
-      await createAgentWithConfig(page, {
-        directory: repo.path,
-        model: 'haiku',
-        mode: 'Always Ask',
-        prompt,
-      });
-
-      await waitForPermissionPrompt(page, 30000);
-
-      await denyPermission(page);
-
-      await expect(page.getByText(/denied by the user|permission\/authorization check/i)).toBeVisible({
-        timeout: 30_000,
-      });
-
-      expect(existsSync(filePath)).toBe(false);
-
-    } finally {
-      await repo.cleanup();
-    }
-  });
-});

packages/app/e2e/preserve-prompt-on-error.spec.ts

@@ -1,25 +0,0 @@
-import { test, expect } from './fixtures';
-import { gotoHome, ensureHostSelected, setWorkingDirectory } from './helpers/app';
-
-test('preserves prompt text when trying to create agent with non-existent directory', async ({ page }) => {
-  const nonExistentDir = '/non/existent/directory/that/does/not/exist';
-  const promptText = `Test prompt that should be preserved ${Date.now()}`;
-
-  await gotoHome(page);
-  await ensureHostSelected(page);
-  await setWorkingDirectory(page, nonExistentDir);
-
-  // Enter prompt text
-  const input = page.getByRole('textbox', { name: 'Message agent...' });
-  await expect(input).toBeEditable();
-  await input.fill(promptText);
-
-  // Try to submit - this should fail with an error about the directory not existing
-  await input.press('Enter');
-
-  // Verify error message is displayed (error includes the path)
-  await expect(page.getByText(/Working directory does not exist/)).toBeVisible();
-
-  // Verify the prompt text is still preserved in the input
-  await expect(input).toHaveValue(promptText);
-});

packages/app/e2e/relay-fallback-connect.spec.ts

@@ -1,42 +0,0 @@
-import { test, expect } from './fixtures';
-
-test('connects via relay when direct endpoints fail', async ({ page }) => {
-  const relayPort = process.env.E2E_RELAY_PORT;
-  const serverId = process.env.E2E_SERVER_ID;
-  const daemonPublicKeyB64 = process.env.E2E_RELAY_DAEMON_PUBLIC_KEY;
-  if (!relayPort || !serverId || !daemonPublicKeyB64) {
-    throw new Error(
-      'E2E_RELAY_PORT, E2E_SERVER_ID, or E2E_RELAY_DAEMON_PUBLIC_KEY is not set (expected from globalSetup).'
-    );
-  }
-
-  const nowIso = new Date().toISOString();
-  const relayEndpoint = `127.0.0.1:${relayPort}`;
-
-  const host = {
-    serverId,
-    label: 'relay-daemon',
-    connections: [
-      { id: 'direct:127.0.0.1:9', type: 'direct', endpoint: '127.0.0.1:9' },
-      { id: `relay:${relayEndpoint}`, type: 'relay', relayEndpoint, daemonPublicKeyB64 },
-    ],
-    preferredConnectionId: 'direct:127.0.0.1:9',
-    createdAt: nowIso,
-    updatedAt: nowIso,
-  };
-
-  // Override the default fixture seeding for this test.
-  await page.goto('/settings');
-  await page.evaluate((daemon) => {
-    const nonce = localStorage.getItem('@paseo:e2e-seed-nonce') ?? '1';
-    localStorage.setItem('@paseo:e2e-disable-default-seed-once', nonce);
-    localStorage.setItem('@paseo:daemon-registry', JSON.stringify([daemon]));
-    localStorage.removeItem('@paseo:settings');
-  }, host);
-  await page.reload();
-
-  // Should eventually connect through the relay connection.
-  const card = page.getByTestId(`daemon-card-${serverId}`);
-  await expect(card.getByText('Relay', { exact: true })).toBeVisible({ timeout: 20000 });
-  await expect(card.getByText('Online', { exact: true })).toBeVisible({ timeout: 20000 });
-});

packages/app/e2e/relay-stability.spec.ts

@@ -1,57 +0,0 @@
-import { test, expect } from './fixtures';
-
-test('relay connection stays stable across multiple tabs', async ({ page }) => {
-  const relayPort = process.env.E2E_RELAY_PORT;
-  const serverId = process.env.E2E_SERVER_ID;
-  const daemonPublicKeyB64 = process.env.E2E_RELAY_DAEMON_PUBLIC_KEY;
-  if (!relayPort || !serverId || !daemonPublicKeyB64) {
-    throw new Error(
-      'E2E_RELAY_PORT, E2E_SERVER_ID, or E2E_RELAY_DAEMON_PUBLIC_KEY is not set (expected from globalSetup).'
-    );
-  }
-
-  const nowIso = new Date().toISOString();
-  const relayEndpoint = `127.0.0.1:${relayPort}`;
-
-  const host = {
-    serverId,
-    label: 'relay-daemon',
-    connections: [
-      { id: 'direct:127.0.0.1:9', type: 'direct', endpoint: '127.0.0.1:9' },
-      { id: `relay:${relayEndpoint}`, type: 'relay', relayEndpoint, daemonPublicKeyB64 },
-    ],
-    preferredConnectionId: 'direct:127.0.0.1:9',
-    createdAt: nowIso,
-    updatedAt: nowIso,
-  };
-
-  // Use relay by making the direct endpoint intentionally fail.
-  await page.goto('/settings');
-  await page.evaluate((daemon) => {
-    const nonce = localStorage.getItem('@paseo:e2e-seed-nonce') ?? '1';
-    localStorage.setItem('@paseo:e2e-disable-default-seed-once', nonce);
-    localStorage.setItem('@paseo:daemon-registry', JSON.stringify([daemon]));
-    localStorage.removeItem('@paseo:settings');
-  }, host);
-  await page.reload();
-
-  const card = page.getByTestId(`daemon-card-${serverId}`);
-  await expect(card.getByText('Relay', { exact: true })).toBeVisible({ timeout: 20000 });
-  await expect(card.getByText('Online', { exact: true })).toBeVisible({ timeout: 20000 });
-
-  // Open a second tab. It should be able to connect independently without forcing disconnect churn.
-  const page2 = await page.context().newPage();
-  await page2.route(/:(6767)\b/, (route) => route.abort());
-  await page2.routeWebSocket(/:(6767)\b/, async (ws) => {
-    await ws.close({ code: 1008, reason: 'Blocked connection to localhost:6767 during e2e.' });
-  });
-  await page2.goto('/settings');
-  const card2 = page2.getByTestId(`daemon-card-${serverId}`);
-  await expect(card2.getByText('Relay', { exact: true })).toBeVisible({ timeout: 20000 });
-  await expect(card2.getByText('Online', { exact: true })).toBeVisible({ timeout: 20000 });
-
-  // Stability window: keep both tabs open and ensure they remain online.
-  await page.waitForTimeout(30_000);
-  await expect(card.getByText('Online', { exact: true })).toBeVisible();
-  await expect(card2.getByText('Online', { exact: true })).toBeVisible();
-});

packages/app/e2e/sidebar-new-agent-clones-selected.spec.ts

@@ -1,23 +0,0 @@
-import { test, expect } from './fixtures';
-import { createAgent, ensureHostSelected, gotoHome, setWorkingDirectory } from './helpers/app';
-import { createTempGitRepo } from './helpers/workspace';
-
-test('sidebar New Agent opens a fresh create screen', async ({ page }) => {
-  const repoA = await createTempGitRepo();
-
-  try {
-    await gotoHome(page);
-    await ensureHostSelected(page);
-
-    await setWorkingDirectory(page, repoA.path);
-    await createAgent(page, 'Agent A: respond with exactly A');
-    await expect(page).toHaveURL(/\/agent\//);
-
-    // Click sidebar New Agent and assert it does not carry over agent settings via URL.
-    await page.getByTestId('sidebar-new-agent').click();
-    await expect(page).toHaveURL(/\/agent\/?$/);
-    await expect(page).not.toHaveURL(new RegExp(encodeURIComponent(repoA.path)));
-  } finally {
-    await repoA.cleanup();
-  }
-});

packages/app/e2e/sidebar-project-filter-flash.spec.ts

@@ -1,130 +0,0 @@
-import { test, expect } from "./fixtures";
-import { gotoHome } from "./helpers/app";
-
-test("project filter dropdown never appears visibly at 0,0 on open", async ({ page }) => {
-  await gotoHome(page);
-
-  const trigger = page.getByText("Project", { exact: true }).first();
-  await expect(trigger).toBeVisible();
-
-  await page.evaluate(() => {
-    (window as any).__projectFilterFlashProbe = new Promise<{
-      targetFound: boolean;
-      visibleAtOrigin: boolean;
-      records: Array<{ left: number; top: number; opacity: number }>;
-    }>((resolve) => {
-      let target: HTMLElement | null = null;
-      const records: Array<{ left: number; top: number; opacity: number }> = [];
-
-      const capture = () => {
-        if (!target) return;
-        const style = getComputedStyle(target);
-        records.push({
-          left: Number.parseFloat(style.left || "0"),
-          top: Number.parseFloat(style.top || "0"),
-          opacity: Number.parseFloat(style.opacity || "1"),
-        });
-      };
-
-      const getContainer = (node: HTMLElement): HTMLElement | null => {
-        let current: HTMLElement | null = node;
-        while (current && current !== document.body) {
-          const style = getComputedStyle(current);
-          if (style.position === "absolute" && style.backgroundColor !== "rgba(0, 0, 0, 0)") {
-            return current;
-          }
-          current = current.parentElement;
-        }
-        return null;
-      };
-
-      const tryResolveTarget = (root: HTMLElement) => {
-        const stack = [root, ...Array.from(root.querySelectorAll<HTMLElement>("*"))];
-        for (const element of stack) {
-          if (!element.textContent?.includes("No projects")) continue;
-          const container = getContainer(element);
-          if (!container) continue;
-          target = container;
-          return true;
-        }
-        return false;
-      };
-
-      const finish = () => {
-        observer.disconnect();
-        if (!target) {
-          resolve({
-            targetFound: false,
-            visibleAtOrigin: false,
-            records: [],
-          });
-          return;
-        }
-
-        const visibleAtOrigin = records.some(
-          (entry) => entry.left <= 1 && entry.top <= 1 && entry.opacity > 0.01
-        );
-
-        resolve({
-          targetFound: true,
-          visibleAtOrigin,
-          records,
-        });
-      };
-
-      const sampleFrames = () => {
-        capture();
-        requestAnimationFrame(() => {
-          capture();
-          requestAnimationFrame(() => {
-            capture();
-            requestAnimationFrame(() => {
-              capture();
-              requestAnimationFrame(() => {
-                capture();
-                finish();
-              });
-            });
-          });
-        });
-      };
-
-      const observer = new MutationObserver((mutations) => {
-        for (const mutation of mutations) {
-          for (const added of Array.from(mutation.addedNodes)) {
-            if (!(added instanceof HTMLElement)) continue;
-            if (tryResolveTarget(added)) {
-              sampleFrames();
-              return;
-            }
-          }
-
-          if (
-            mutation.type === "attributes" &&
-            mutation.target instanceof HTMLElement &&
-            !target &&
-            tryResolveTarget(mutation.target)
-          ) {
-            sampleFrames();
-            return;
-          }
-        }
-      });
-
-      observer.observe(document.body, {
-        childList: true,
-        subtree: true,
-        attributes: true,
-        attributeFilter: ["style"],
-      });
-
-      setTimeout(() => finish(), 2500);
-    });
-  });
-
-  await trigger.click();
-  const probe = await page.evaluate(() => (window as any).__projectFilterFlashProbe);
-
-  expect(probe.targetFound).toBe(true);
-  expect(probe.visibleAtOrigin).toBe(false);
-});

packages/app/e2e/sidebar-toggle-tooltip.spec.ts

@@ -1,47 +0,0 @@
-import { test, expect } from './fixtures';
-import { gotoHome, openSettings } from './helpers/app';
-
-test('sidebar toggle shows tooltip on the right', async ({ page }) => {
-  await gotoHome(page);
-  await openSettings(page);
-
-  const menuButton = page.getByRole('button', { name: /menu/i }).first();
-  await expect(menuButton).toBeVisible();
-
-  // Baseline: tooltip should appear on keyboard focus (a11y requirement).
-  await menuButton.focus();
-
-  const tooltip = page.getByTestId('menu-button-tooltip');
-  await expect(tooltip).toBeVisible();
-  await expect(tooltip).toContainText('Toggle sidebar');
-  await expect(tooltip).toContainText(/⌘B|Ctrl\+\./);
-  await page.waitForTimeout(250);
-  await expect(tooltip).toBeVisible();
-
-  // Tooltip should also appear on hover.
-  await menuButton.blur();
-  await expect(tooltip).toHaveCount(0);
-  await menuButton.hover();
-  await expect(tooltip).toBeVisible();
-
-  const triggerBox = await menuButton.boundingBox();
-  const tooltipBox = await tooltip.boundingBox();
-  expect(triggerBox).not.toBeNull();
-  expect(tooltipBox).not.toBeNull();
-  if (!triggerBox || !tooltipBox) return;
-
-  // side=right => tooltip starts to the right of the trigger.
-  expect(tooltipBox.x).toBeGreaterThan(triggerBox.x + triggerBox.width - 1);
-  // Keep it reasonably close (should be ~trigger.right + offset).
-  const expectedX = triggerBox.x + triggerBox.width + 8;
-  expect(Math.abs(tooltipBox.x - expectedX)).toBeLessThanOrEqual(12);
-  expect(tooltipBox.width).toBeGreaterThanOrEqual(60);
-  expect(tooltipBox.width).toBeLessThanOrEqual(500);
-  expect(tooltipBox.height).toBeGreaterThanOrEqual(20);
-  expect(tooltipBox.height).toBeLessThanOrEqual(80);
-
-  // align=center => centers should be roughly aligned (allow some clamping tolerance).
-  const triggerCenterY = triggerBox.y + triggerBox.height / 2;
-  const tooltipCenterY = tooltipBox.y + tooltipBox.height / 2;
-  expect(Math.abs(triggerCenterY - tooltipCenterY)).toBeLessThanOrEqual(24);
-});

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

@@ -1,621 +0,0 @@
-import { test, expect, type Page } from "./fixtures";
-import {
-  createAgent,
-  ensureHostSelected,
-  gotoHome,
-  setWorkingDirectory,
-} from "./helpers/app";
-import { createTempGitRepo } from "./helpers/workspace";
-
-function parseAgentFromUrl(url: string): { serverId: string; agentId: string } {
-  const pathname = (() => {
-    try {
-      return new URL(url).pathname;
-    } catch {
-      return url;
-    }
-  })();
-
-  const modernMatch = pathname.match(/\/h\/([^/]+)\/agent\/([^/?#]+)/);
-  if (modernMatch) {
-    return {
-      serverId: decodeURIComponent(modernMatch[1]),
-      agentId: decodeURIComponent(modernMatch[2]),
-    };
-  }
-
-  const legacyMatch = pathname.match(/\/agent\/([^/]+)\/([^/?#]+)/);
-  if (legacyMatch) {
-    return {
-      serverId: decodeURIComponent(legacyMatch[1]),
-      agentId: decodeURIComponent(legacyMatch[2]),
-    };
-  }
-
-  throw new Error(`Expected /h/:serverId/agent/:agentId URL, got ${url}`);
-}
-
-async function openAgentFromSidebar(page: Page, serverId: string, agentId: string): Promise<void> {
-  await gotoHome(page);
-  const row = page.getByTestId(`agent-row-${serverId}-${agentId}`).first();
-  await expect(row).toBeVisible({ timeout: 30000 });
-  await row.click();
-  await expect
-    .poll(
-      () => {
-        try {
-          const parsed = parseAgentFromUrl(page.url());
-          return `${parsed.serverId}:${parsed.agentId}`;
-        } catch {
-          return "";
-        }
-      },
-      { timeout: 30000 }
-    )
-    .toBe(`${serverId}:${agentId}`);
-}
-
-async function openNewAgentDraft(page: Page): Promise<void> {
-  await gotoHome(page);
-  const newAgentButton = page.getByTestId("sidebar-new-agent").first();
-  await expect(newAgentButton).toBeVisible({ timeout: 30000 });
-  await newAgentButton.click();
-  await expect(page).toHaveURL(/\/agent\/?$/, { timeout: 30000 });
-  await expect(
-    page.locator('[data-testid="working-directory-select"]:visible').first()
-  ).toBeVisible({
-    timeout: 30000,
-  });
-}
-
-async function openTerminalsPanel(page: Page): Promise<void> {
-  let header = page.locator('[data-testid="explorer-header"]:visible').first();
-  if (!(await header.isVisible().catch(() => false))) {
-    const toggle = page.getByRole("button", {
-      name: /open explorer|close explorer|toggle explorer/i,
-    });
-    if (await toggle.first().isVisible().catch(() => false)) {
-      await toggle.first().click();
-    }
-  }
-
-  header = page.locator('[data-testid="explorer-header"]:visible').first();
-  await expect(header).toBeVisible({ timeout: 30000 });
-
-  const terminalsTab = page.getByTestId("explorer-tab-terminals").first();
-  await expect(terminalsTab).toBeVisible({ timeout: 30000 });
-  await terminalsTab.click();
-
-  await expect(page.getByTestId("terminals-header").first()).toBeVisible({
-    timeout: 30000,
-  });
-
-  await expect(page.getByTestId("terminal-surface").first()).toBeVisible({
-    timeout: 30000,
-  });
-}
-
-async function openFilesPanel(page: Page): Promise<void> {
-  const filesTab = page.getByTestId("explorer-tab-files").first();
-  await expect(filesTab).toBeVisible({ timeout: 30000 });
-  await filesTab.click();
-  await expect(page.getByTestId("files-pane-header").first()).toBeVisible({
-    timeout: 30000,
-  });
-}
-
-async function getDesktopAgentSidebarOpen(page: Page): Promise<boolean | null> {
-  return await page.evaluate(() => {
-    const raw = localStorage.getItem("panel-state");
-    if (!raw) {
-      return null;
-    }
-    try {
-      const parsed = JSON.parse(raw) as {
-        state?: { desktop?: { agentListOpen?: boolean } };
-      };
-      const value = parsed?.state?.desktop?.agentListOpen;
-      return typeof value === "boolean" ? value : null;
-    } catch {
-      return null;
-    }
-  });
-}
-
-
-async function selectNewestTerminalTab(page: Page): Promise<void> {
-  const tabs = page.locator('[data-testid^="terminal-tab-"]');
-  await expect(tabs.first()).toBeVisible({ timeout: 30000 });
-  await expect
-    .poll(async () => await tabs.count(), { timeout: 30000 })
-    .toBeGreaterThanOrEqual(2);
-  await tabs.last().click();
-}
-
-async function getFirstTerminalTabTestId(page: Page): Promise<string> {
-  const firstTab = page.locator('[data-testid^="terminal-tab-"]').first();
-  await expect(firstTab).toBeVisible({ timeout: 30000 });
-  const value = await firstTab.getAttribute("data-testid");
-  if (!value) {
-    throw new Error("Expected terminal tab test id");
-  }
-  return value;
-}
-
-async function runTerminalCommand(page: Page, command: string, expectedText: string): Promise<void> {
-  const surface = page.getByTestId("terminal-surface").first();
-  await expect(surface).toBeVisible({ timeout: 30000 });
-  await surface.click({ force: true });
-  await page.keyboard.type(command, { delay: 1 });
-  await page.keyboard.press("Enter");
-  await expect(surface).toContainText(expectedText, {
-    timeout: 30000,
-  });
-}
-
-async function runTerminalCommandWithPreEnterEcho(
-  page: Page,
-  command: string,
-  expectedText: string
-): Promise<void> {
-  const surface = page.getByTestId("terminal-surface").first();
-  await expect(surface).toBeVisible({ timeout: 30000 });
-  await surface.click({ force: true });
-  await page.keyboard.type(command, { delay: 1 });
-  await expect(surface).toContainText(command, {
-    timeout: 30000,
-  });
-  await page.keyboard.press("Enter");
-  await expect(surface).toContainText(expectedText, {
-    timeout: 30000,
-  });
-}
-
-async function expectAnsiColorApplied(page: Page, marker: string): Promise<void> {
-  await expect
-    .poll(
-      async () =>
-        await page.evaluate((target) => {
-          const terminal = (window as any).__paseoTerminal;
-          if (!terminal?.buffer?.active?.getLine || !terminal?.buffer?.active?.getNullCell) {
-            return false;
-          }
-
-          const buffer = terminal.buffer.active;
-          const nullCell = buffer.getNullCell();
-          const lineCount = buffer.length ?? 0;
-          const cols = terminal.cols ?? 0;
-
-          for (let y = 0; y < lineCount; y += 1) {
-            const line = buffer.getLine(y);
-            if (!line) continue;
-            const lineText = line.translateToString(true);
-            const index = lineText.indexOf(target);
-            if (index === -1) continue;
-
-            for (let x = index; x < index + target.length && x < cols; x += 1) {
-              const cell = line.getCell(x, nullCell);
-              if (!cell) continue;
-              if (!cell.isFgDefault()) {
-                return true;
-              }
-            }
-          }
-          return false;
-        }, marker),
-      { timeout: 30000 }
-    )
-    .toBe(true);
-}
-
-test("Terminals tab creates multiple terminals and streams command output", async ({ page }) => {
-  const repo = await createTempGitRepo("paseo-e2e-terminals-");
-
-  try {
-    await openNewAgentDraft(page);
-    await setWorkingDirectory(page, repo.path);
-    await ensureHostSelected(page);
-    await createAgent(page, "Reply with exactly: terminal smoke");
-
-    await openTerminalsPanel(page);
-    await expect(page.locator('[data-testid^="terminal-tab-"]').first()).toBeVisible({
-      timeout: 30000,
-    });
-
-    const preEnterEchoMarker = `typed-echo-${Date.now()}`;
-    await runTerminalCommandWithPreEnterEcho(
-      page,
-      `echo ${preEnterEchoMarker}`,
-      preEnterEchoMarker
-    );
-
-    const ansiMarker = `ansi-red-${Date.now()}`;
-    await runTerminalCommand(
-      page,
-      `printf '\\033[31m${ansiMarker}\\033[0m\\n'`,
-      ansiMarker
-    );
-    await expectAnsiColorApplied(page, ansiMarker);
-
-    const markerOne = `terminal-smoke-one-${Date.now()}`;
-    await runTerminalCommand(page, `echo ${markerOne}`, markerOne);
-
-    await page.getByTestId("terminals-create-button").first().click();
-    await selectNewestTerminalTab(page);
-
-    const markerTwo = `terminal-smoke-two-${Date.now()}`;
-    await runTerminalCommand(page, `echo ${markerTwo}`, markerTwo);
-  } finally {
-    await repo.cleanup();
-  }
-});
-
-test("terminal reattaches cleanly after heavy output and tab switches", async ({ page }) => {
-  const repo = await createTempGitRepo("paseo-e2e-terminal-reattach-");
-
-  try {
-    await openNewAgentDraft(page);
-    await setWorkingDirectory(page, repo.path);
-    await ensureHostSelected(page);
-    await createAgent(page, "hello");
-
-    await openTerminalsPanel(page);
-    await runTerminalCommand(
-      page,
-      "for i in $(seq 1 12000); do echo reattach-$i; done",
-      "reattach-12000"
-    );
-
-    for (let attempt = 0; attempt < 4; attempt += 1) {
-      await openFilesPanel(page);
-      await openTerminalsPanel(page);
-      await expect(page.getByText("Terminal stream ended. Reconnecting…")).toHaveCount(0, {
-        timeout: 30000,
-      });
-      await expect(page.getByTestId("terminal-attach-loading")).toHaveCount(0, {
-        timeout: 30000,
-      });
-    }
-
-    const marker = `reattach-health-${Date.now()}`;
-    await runTerminalCommand(page, `echo ${marker}`, marker);
-  } finally {
-    await repo.cleanup();
-  }
-});
-
-test("terminal keeps prompt echo visible after enter and backspace churn", async ({ page }) => {
-  const repo = await createTempGitRepo("paseo-e2e-terminal-echo-churn-");
-
-  try {
-    await openNewAgentDraft(page);
-    await setWorkingDirectory(page, repo.path);
-    await ensureHostSelected(page);
-    await createAgent(page, "hello");
-
-    await openTerminalsPanel(page);
-
-    const surface = page.getByTestId("terminal-surface").first();
-    await expect(surface).toBeVisible({ timeout: 30000 });
-    await surface.click({ force: true });
-
-    for (let iteration = 0; iteration < 40; iteration += 1) {
-      await page.keyboard.press("Enter");
-    }
-
-    const markerAfterEnters = `echo-visible-${Date.now()}`;
-    await page.keyboard.type(`echo ${markerAfterEnters}`, { delay: 0 });
-    await expect(surface).toContainText(`echo ${markerAfterEnters}`, {
-      timeout: 30000,
-    });
-    await page.keyboard.press("Enter");
-    await expect(surface).toContainText(markerAfterEnters, {
-      timeout: 30000,
-    });
-
-    const longSuffix = "x".repeat(120);
-    await page.keyboard.type(`echo ${longSuffix}`, { delay: 0 });
-    for (let iteration = 0; iteration < longSuffix.length; iteration += 1) {
-      await page.keyboard.press("Backspace");
-    }
-
-    const markerAfterBackspace = `echo-backspace-${Date.now()}`;
-    await page.keyboard.type(markerAfterBackspace, { delay: 0 });
-    await page.keyboard.press("Enter");
-    await expect(surface).toContainText(markerAfterBackspace, {
-      timeout: 30000,
-    });
-  } finally {
-    await repo.cleanup();
-  }
-});
-
-test("terminal remains interactive after alternate-screen enter/exit", async ({ page }) => {
-  const repo = await createTempGitRepo("paseo-e2e-terminal-alt-screen-");
-
-  try {
-    await openNewAgentDraft(page);
-    await setWorkingDirectory(page, repo.path);
-    await ensureHostSelected(page);
-    await createAgent(page, "hello");
-
-    await openTerminalsPanel(page);
-
-    const surface = page.getByTestId("terminal-surface").first();
-    await expect(surface).toBeVisible({ timeout: 30000 });
-    await surface.click({ force: true });
-
-    await page.keyboard.type(
-      "printf '\\033[?1049h\\033[2J\\033[HALT\\033[?1049l\\n'",
-      { delay: 0 }
-    );
-    await page.keyboard.press("Enter");
-
-    const marker = `post-alt-screen-${Date.now()}`;
-    await page.keyboard.type(`echo ${marker}`, { delay: 0 });
-    await page.keyboard.press("Enter");
-    await expect(surface).toContainText(marker, {
-      timeout: 30000,
-    });
-  } finally {
-    await repo.cleanup();
-  }
-});
-
-test("terminal tab is removed when shell exits", async ({ page }) => {
-  const repo = await createTempGitRepo("paseo-e2e-terminal-exit-");
-
-  try {
-    await openNewAgentDraft(page);
-    await setWorkingDirectory(page, repo.path);
-    await ensureHostSelected(page);
-    await createAgent(page, "Terminal exit flow");
-
-    await openTerminalsPanel(page);
-
-    const exitedTabTestId = await getFirstTerminalTabTestId(page);
-
-    const surface = page.getByTestId("terminal-surface").first();
-    await expect(surface).toBeVisible({ timeout: 30000 });
-    await surface.click({ force: true });
-    await page.keyboard.type("exit", { delay: 1 });
-    await page.keyboard.press("Enter");
-
-    await expect(page.getByTestId(exitedTabTestId)).toHaveCount(0, {
-      timeout: 30000,
-    });
-
-    await expect(page.locator('[data-testid^="terminal-tab-"]').first()).toBeVisible({
-      timeout: 30000,
-    });
-    const nextTabTestId = await getFirstTerminalTabTestId(page);
-    expect(nextTabTestId).not.toBe(exitedTabTestId);
-  } finally {
-    await repo.cleanup();
-  }
-});
-
-
-test("terminals are shared by agents on the same cwd", async ({ page }) => {
-  const repo = await createTempGitRepo("paseo-e2e-terminal-share-");
-
-  try {
-    await openNewAgentDraft(page);
-    await setWorkingDirectory(page, repo.path);
-    await ensureHostSelected(page);
-    await createAgent(page, "Agent one");
-    const first = parseAgentFromUrl(page.url());
-
-    await openNewAgentDraft(page);
-    await setWorkingDirectory(page, repo.path);
-    await ensureHostSelected(page);
-    await createAgent(page, "Agent two");
-    const second = parseAgentFromUrl(page.url());
-
-    expect(first.serverId).toBe(second.serverId);
-    expect(first.agentId).not.toBe(second.agentId);
-
-    await openAgentFromSidebar(page, first.serverId, first.agentId);
-    await openTerminalsPanel(page);
-    await page.getByTestId("terminals-create-button").first().click();
-    await selectNewestTerminalTab(page);
-
-    await openAgentFromSidebar(page, second.serverId, second.agentId);
-    await openTerminalsPanel(page);
-    await selectNewestTerminalTab(page);
-
-    const sharedMarker = `shared-terminal-${Date.now()}`;
-    await runTerminalCommand(page, `echo ${sharedMarker}`, sharedMarker);
-
-    await openAgentFromSidebar(page, first.serverId, first.agentId);
-    await openTerminalsPanel(page);
-    await selectNewestTerminalTab(page);
-    await expect(page.getByTestId("terminal-surface").first()).toContainText(sharedMarker, {
-      timeout: 30000,
-    });
-  } finally {
-    await repo.cleanup();
-  }
-});
-
-test("terminal captures escape and ctrl+c key input", async ({ page }) => {
-  const repo = await createTempGitRepo("paseo-e2e-terminal-keys-");
-
-  try {
-    await openNewAgentDraft(page);
-    await setWorkingDirectory(page, repo.path);
-    await ensureHostSelected(page);
-    await createAgent(page, "Terminal key combo capture");
-
-    await openTerminalsPanel(page);
-
-    const surface = page.getByTestId("terminal-surface").first();
-    await expect(surface).toBeVisible({ timeout: 30000 });
-    await surface.click({ force: true });
-
-    await page.keyboard.type("cat -v", { delay: 1 });
-    await page.keyboard.press("Enter");
-    await expect(surface).toContainText("cat -v", { timeout: 30000 });
-
-    await page.keyboard.press("Escape");
-    await expect(surface).toContainText("^[", { timeout: 30000 });
-
-    await page.keyboard.press("Control+C");
-    await expect(surface).toContainText("^C", { timeout: 30000 });
-
-    await page.keyboard.press("Control+B");
-    await expect(surface).toContainText("^B", { timeout: 30000 });
-
-    const marker = `terminal-key-capture-${Date.now()}`;
-    await page.keyboard.type(`echo ${marker}`, { delay: 1 });
-    await page.keyboard.press("Enter");
-    await expect(surface).toContainText(marker, { timeout: 30000 });
-  } finally {
-    await repo.cleanup();
-  }
-});
-
-test("Cmd+B toggles sidebar even when terminal is focused", async ({ page }) => {
-  const repo = await createTempGitRepo("paseo-e2e-terminal-cmd-b-");
-
-  try {
-    await openNewAgentDraft(page);
-    await setWorkingDirectory(page, repo.path);
-    await ensureHostSelected(page);
-    await createAgent(page, "Terminal Cmd+B");
-
-    await openTerminalsPanel(page);
-    const surface = page.getByTestId("terminal-surface").first();
-    await expect(surface).toBeVisible({ timeout: 30000 });
-    await surface.click({ force: true });
-
-    await expect
-      .poll(async () => await getDesktopAgentSidebarOpen(page), { timeout: 30000 })
-      .toBe(true);
-
-    await page.keyboard.press("Meta+B");
-    await expect
-      .poll(async () => await getDesktopAgentSidebarOpen(page), { timeout: 30000 })
-      .toBe(false);
-
-    await page.keyboard.press("Meta+B");
-    await expect
-      .poll(async () => await getDesktopAgentSidebarOpen(page), { timeout: 30000 })
-      .toBe(true);
-  } finally {
-    await repo.cleanup();
-  }
-});
-
-async function getTerminalRows(page: Page): Promise<number> {
-  return await page.evaluate(() => {
-    const terminal = (window as { __paseoTerminal?: { rows?: unknown } }).__paseoTerminal;
-    return typeof terminal?.rows === "number" ? terminal.rows : 0;
-  });
-}
-
-async function setExplorerContentBottomPadding(page: Page, padding: number): Promise<void> {
-  await page.evaluate((nextPadding) => {
-    const container = document.querySelector<HTMLElement>(
-      '[data-testid="explorer-content-area"]'
-    );
-    if (!container) {
-      return;
-    }
-    container.style.boxSizing = "border-box";
-    container.style.paddingBottom = nextPadding + "px";
-  }, padding);
-}
-
-async function getTerminalScrollbackDistance(page: Page): Promise<number> {
-  return await page.evaluate(() => {
-    const terminal = (
-      window as {
-        __paseoTerminal?: {
-          buffer?: { active?: { baseY?: unknown; viewportY?: unknown } };
-        };
-      }
-    ).__paseoTerminal;
-    const baseY = terminal?.buffer?.active?.baseY;
-    const viewportY = terminal?.buffer?.active?.viewportY;
-    if (typeof baseY !== "number" || typeof viewportY !== "number") {
-      return 0;
-    }
-    return Math.max(0, baseY - viewportY);
-  });
-}
-
-test("terminal viewport resizes and uses xterm scrollback", async ({ page }) => {
-  const repo = await createTempGitRepo("paseo-e2e-terminal-viewport-");
-
-  try {
-    await openNewAgentDraft(page);
-    await setWorkingDirectory(page, repo.path);
-    await ensureHostSelected(page);
-    await createAgent(page, "Viewport and scrollback test");
-
-    await openTerminalsPanel(page);
-
-    const initialViewport = page.viewportSize();
-    if (!initialViewport) {
-      throw new Error("Expected a viewport size");
-    }
-
-    await expect
-      .poll(() => getTerminalRows(page), { timeout: 30000 })
-      .toBeGreaterThan(0);
-    const initialRows = await getTerminalRows(page);
-
-    await setExplorerContentBottomPadding(page, 220);
-    await expect
-      .poll(() => getTerminalRows(page), { timeout: 30000 })
-      .toBeLessThan(initialRows);
-
-    await setExplorerContentBottomPadding(page, 0);
-    await expect
-      .poll(() => getTerminalRows(page), { timeout: 30000 })
-      .toBeGreaterThanOrEqual(initialRows);
-
-    const reducedHeight = Math.max(520, initialViewport.height - 220);
-    await page.setViewportSize({
-      width: initialViewport.width,
-      height: reducedHeight,
-    });
-
-    await expect
-      .poll(() => getTerminalRows(page), { timeout: 30000 })
-      .toBeLessThan(initialRows);
-
-    await page.setViewportSize(initialViewport);
-
-    await expect
-      .poll(() => getTerminalRows(page), { timeout: 30000 })
-      .toBeGreaterThanOrEqual(initialRows);
-
-    const scrollbackMarker = `scrollback-${Date.now()}`;
-    await runTerminalCommand(
-      page,
-      `for i in $(seq 1 180); do echo ${scrollbackMarker}-$i; done`,
-      `${scrollbackMarker}-180`
-    );
-
-    const surface = page.getByTestId("terminal-surface").first();
-    await surface.hover();
-    await page.mouse.wheel(0, -3000);
-
-    await expect
-      .poll(() => getTerminalScrollbackDistance(page), { timeout: 30000 })
-      .toBeGreaterThan(0);
-
-    const distanceAfterScrollUp = await getTerminalScrollbackDistance(page);
-
-    await surface.hover();
-    await page.mouse.wheel(0, 3000);
-
-    await expect
-      .poll(() => getTerminalScrollbackDistance(page), { timeout: 30000 })
-      .toBeLessThan(distanceAfterScrollUp);
-  } finally {
-    await repo.cleanup();
-  }
-});

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

@@ -0,0 +1,160 @@
+import { test, expect } from "./fixtures";
+import { createTempGitRepo } from "./helpers/workspace";
+import {
+  connectTerminalClient,
+  navigateToTerminal,
+  setupDeterministicPrompt,
+  waitForTerminalContent,
+  measureKeystrokeLatency,
+  computePercentile,
+  round2,
+  type TerminalPerfDaemonClient,
+  type LatencySample,
+} from "./helpers/terminal-perf";
+
+const LINE_COUNT = 50_000;
+const THROUGHPUT_BUDGET_MS = 30_000;
+const KEYSTROKE_SAMPLE_COUNT = 20;
+const KEYSTROKE_P95_BUDGET_MS = 150;
+
+test.describe("Terminal wire performance", () => {
+  let client: TerminalPerfDaemonClient;
+  let tempRepo: { path: string; cleanup: () => Promise<void> };
+
+  test.beforeAll(async () => {
+    tempRepo = await createTempGitRepo("perf-");
+    client = await connectTerminalClient();
+  });
+
+  test.afterAll(async () => {
+    if (client) {
+      await client.close();
+    }
+    if (tempRepo) {
+      await tempRepo.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;
+
+    try {
+      await navigateToTerminal(page, { cwd: tempRepo.path, terminalId });
+      await setupDeterministicPrompt(page);
+
+      const sentinel = `PERF_DONE_${Date.now()}`;
+      const terminal = page.locator('[data-testid="terminal-surface"]');
+      const startMs = Date.now();
+
+      await terminal.pressSequentially(`seq 1 ${LINE_COUNT}; echo ${sentinel}\n`, { delay: 0 });
+
+      await waitForTerminalContent(page, (text) => text.includes(sentinel), THROUGHPUT_BUDGET_MS + 15_000);
+
+      const elapsedMs = Date.now() - startMs;
+
+      // seq 1 N outputs each number on its own line
+      const estimatedBytes = Array.from(
+        { length: LINE_COUNT },
+        (_, i) => String(i + 1).length + 1,
+      ).reduce((a, b) => a + b, 0);
+      const throughputMBps = estimatedBytes / (1024 * 1024) / (elapsedMs / 1000);
+
+      const report = {
+        lineCount: LINE_COUNT,
+        estimatedBytes,
+        elapsedMs,
+        throughputMBps: round2(throughputMBps),
+      };
+
+      await testInfo.attach("throughput-report", {
+        body: JSON.stringify(report, null, 2),
+        contentType: "application/json",
+      });
+
+      console.log(
+        `[perf] Throughput: ${report.throughputMBps} MB/s — ${LINE_COUNT} lines in ${elapsedMs}ms`,
+      );
+
+      expect(elapsedMs, `${LINE_COUNT} lines should render within ${THROUGHPUT_BUDGET_MS}ms`).toBeLessThan(
+        THROUGHPUT_BUDGET_MS,
+      );
+    } finally {
+      await client.killTerminal(terminalId).catch(() => {});
+    }
+  });
+
+  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;
+
+    try {
+      await navigateToTerminal(page, { cwd: tempRepo.path, terminalId });
+      await setupDeterministicPrompt(page);
+
+      // Ensure clean prompt state
+      const terminal = page.locator('[data-testid="terminal-surface"]');
+      await terminal.press("Control+c");
+      await page.waitForTimeout(200);
+
+      const samples: LatencySample[] = [];
+      const chars = "abcdefghijklmnopqrst";
+
+      for (let i = 0; i < KEYSTROKE_SAMPLE_COUNT; i++) {
+        const char = chars[i % chars.length];
+        const latencyMs = await measureKeystrokeLatency(page, char);
+        samples.push({ char, latencyMs });
+        await page.waitForTimeout(50);
+      }
+
+      // Clean up typed characters
+      await terminal.press("Control+c");
+
+      const latencies = samples.map((s) => s.latencyMs);
+      const p50 = computePercentile(latencies, 50);
+      const p95 = computePercentile(latencies, 95);
+      const max = Math.max(...latencies);
+      const min = Math.min(...latencies);
+      const avg = latencies.reduce((a, b) => a + b, 0) / latencies.length;
+
+      const report = {
+        sampleCount: KEYSTROKE_SAMPLE_COUNT,
+        p50Ms: round2(p50),
+        p95Ms: round2(p95),
+        maxMs: round2(max),
+        minMs: round2(min),
+        avgMs: round2(avg),
+        samples: samples.map((s) => ({
+          char: s.char,
+          latencyMs: round2(s.latencyMs),
+        })),
+      };
+
+      await testInfo.attach("latency-report", {
+        body: JSON.stringify(report, null, 2),
+        contentType: "application/json",
+      });
+
+      console.log(
+        `[perf] Keystroke latency — p50: ${report.p50Ms}ms, p95: ${report.p95Ms}ms, max: ${report.maxMs}ms`,
+      );
+
+      expect(
+        p95,
+        `Keystroke p95 latency should be under ${KEYSTROKE_P95_BUDGET_MS}ms`,
+      ).toBeLessThan(KEYSTROKE_P95_BUDGET_MS);
+    } finally {
+      await client.killTerminal(terminalId).catch(() => {});
+    }
+  });
+});

packages/app/e2e/working-directory-combobox-positioning.spec.ts

@@ -1,158 +0,0 @@
-import { expect, test } from "./fixtures";
-import { gotoHome } from "./helpers/app";
-
-function escapeRegex(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-test("working directory combobox stays visually stable while typing search", async ({ page }) => {
-  await gotoHome(page);
-
-  const workingDirectorySelect = page
-    .locator('[data-testid="working-directory-select"]:visible')
-    .first();
-  await expect(workingDirectorySelect).toBeVisible();
-  await workingDirectorySelect.click({ force: true });
-
-  const searchInput = page.getByRole("textbox", { name: /search directories/i }).first();
-  await expect(searchInput).toBeVisible();
-
-  await page.evaluate(() => {
-    const trigger = document.querySelector('[data-testid="working-directory-select"]');
-    const searchInput = document.querySelector('input[placeholder="Search directories..."]');
-    const container = document.querySelector('[data-testid="combobox-desktop-container"]');
-    if (!(trigger instanceof HTMLElement)) {
-      throw new Error("Missing working-directory-select trigger.");
-    }
-    if (!(searchInput instanceof HTMLInputElement)) {
-      throw new Error("Missing working directory search input.");
-    }
-    if (!(container instanceof HTMLElement)) {
-      throw new Error("Missing combobox desktop container.");
-    }
-
-    const state = {
-      samples: 0,
-      underTriggerSamples: 0,
-      emptyWhileSearchingSamples: 0,
-      minSearchDelta: Number.POSITIVE_INFINITY,
-      maxSearchDelta: Number.NEGATIVE_INFINITY,
-      minContainerDelta: Number.POSITIVE_INFINITY,
-      maxContainerDelta: Number.NEGATIVE_INFINITY,
-      logs: [] as Array<{
-        reason: string;
-        query: string;
-        searchDelta: number;
-        containerDelta: number;
-        hasEmpty: boolean;
-        containerTop: number;
-        containerBottom: number;
-        triggerTop: number;
-        searchBottom: number;
-      }>,
-    };
-
-    const sample = (reason: string) => {
-      if (!document.body.contains(trigger) || !document.body.contains(searchInput) || !document.body.contains(container)) {
-        return;
-      }
-      const query = searchInput.value.trim();
-      if (!query) {
-        return;
-      }
-
-      const triggerRect = trigger.getBoundingClientRect();
-      const searchRect = searchInput.getBoundingClientRect();
-      const containerRect = container.getBoundingClientRect();
-      const hasEmpty = Boolean(container.querySelector('[data-testid="combobox-empty-text"]'));
-      const searchDelta = searchRect.bottom - triggerRect.top;
-      const containerDelta = containerRect.bottom - triggerRect.top;
-
-      state.samples += 1;
-      state.minSearchDelta = Math.min(state.minSearchDelta, searchDelta);
-      state.maxSearchDelta = Math.max(state.maxSearchDelta, searchDelta);
-      state.minContainerDelta = Math.min(state.minContainerDelta, containerDelta);
-      state.maxContainerDelta = Math.max(state.maxContainerDelta, containerDelta);
-      if (searchDelta > 2 || containerDelta > 2) {
-        state.underTriggerSamples += 1;
-      }
-      if (hasEmpty) {
-        state.emptyWhileSearchingSamples += 1;
-      }
-      if (state.logs.length < 80) {
-        state.logs.push({
-          reason,
-          query,
-          searchDelta,
-          containerDelta,
-          hasEmpty,
-          containerTop: containerRect.top,
-          containerBottom: containerRect.bottom,
-          triggerTop: triggerRect.top,
-          searchBottom: searchRect.bottom,
-        });
-      }
-    };
-
-    const mutationObserver = new MutationObserver(() => sample("mutation"));
-    mutationObserver.observe(container, {
-      childList: true,
-      subtree: true,
-      attributes: true,
-      characterData: true,
-    });
-
-    const resizeObserver = new ResizeObserver(() => sample("resize"));
-    resizeObserver.observe(container);
-    resizeObserver.observe(searchInput);
-
-    let rafId = 0;
-    const loop = () => {
-      sample("raf");
-      rafId = requestAnimationFrame(loop);
-    };
-    rafId = requestAnimationFrame(loop);
-
-    (window as any).__paseoComboboxObserver = {
-      stop: () => {
-        cancelAnimationFrame(rafId);
-        mutationObserver.disconnect();
-        resizeObserver.disconnect();
-        sample("stop");
-        return {
-          ...state,
-          minSearchDelta: state.samples > 0 ? state.minSearchDelta : 0,
-          maxSearchDelta: state.samples > 0 ? state.maxSearchDelta : 0,
-          minContainerDelta: state.samples > 0 ? state.minContainerDelta : 0,
-          maxContainerDelta: state.samples > 0 ? state.maxContainerDelta : 0,
-        };
-      },
-    };
-  });
-
-  const queries = [
-    "/tmp/paseo-stability-a",
-    "/tmp/paseo-stability-ab",
-    "/tmp/paseo-stability-abc",
-    "/tmp/paseo-stability-longer-branch",
-    "/tmp/paseo-stability-z",
-  ];
-
-  for (const query of queries) {
-    await searchInput.fill("");
-    await searchInput.type(query, { delay: 20 });
-    const customOption = page.getByText(new RegExp(`^${escapeRegex(query)}$`)).first();
-    await expect(customOption).toBeVisible();
-    await page.waitForTimeout(100);
-  }
-
-  const stats = await page.evaluate(() => (window as any).__paseoComboboxObserver.stop());
-  const debug = JSON.stringify(stats.logs.slice(-10));
-
-  expect(stats.samples, debug).toBeGreaterThan(20);
-  expect(stats.underTriggerSamples, debug).toBe(0);
-  expect(stats.emptyWhileSearchingSamples, debug).toBe(0);
-  expect(stats.maxSearchDelta - stats.minSearchDelta, debug).toBeLessThanOrEqual(3);
-  expect(stats.maxContainerDelta - stats.minContainerDelta, debug).toBeLessThanOrEqual(3);
-  expect(stats.maxContainerDelta, debug).toBeLessThanOrEqual(2);
-});

packages/app/eslint.config.js

@@ -1,10 +1,10 @@
 // https://docs.expo.dev/guides/using-eslint/
-const { defineConfig } = require('eslint/config');
-const expoConfig = require('eslint-config-expo/flat');
+const { defineConfig } = require("eslint/config");
+const expoConfig = require("eslint-config-expo/flat");
 
 module.exports = defineConfig([
   expoConfig,
   {
-    ignores: ['dist/*'],
+    ignores: ["dist/*"],
   },
 ]);

packages/app/index.ts

@@ -2,6 +2,10 @@
 import { polyfillCrypto } from "./src/polyfills/crypto";
 polyfillCrypto();
 
+// Polyfill screen.orientation for WebKitGTK desktop runtimes that lack the API.
+import { polyfillScreenOrientation } from "./src/polyfills/screen-orientation";
+polyfillScreenOrientation();
+
 // Configure Unistyles before Expo Router pulls in any components using StyleSheet.
 import "./src/styles/unistyles";
 import "expo-router/entry";

packages/app/metro.config.cjs

@@ -0,0 +1,86 @@
+const { getDefaultConfig } = require("expo/metro-config");
+const { resolve } = require("metro-resolver");
+const fs = require("fs");
+const path = require("path");
+
+const projectRoot = __dirname;
+const appNodeModulesRoot = path.resolve(projectRoot, "node_modules");
+const appSrcRoot = path.resolve(projectRoot, "src");
+const serverSrcRoot = path.resolve(projectRoot, "../server/src");
+const relaySrcRoot = path.resolve(projectRoot, "../relay/src");
+const customWebPlatform = (process.env.PASEO_WEB_PLATFORM ?? "")
+  .trim()
+  .replace(/^\./, "")
+  .toLowerCase();
+
+const config = getDefaultConfig(projectRoot);
+const defaultResolveRequest = config.resolver.resolveRequest ?? resolve;
+const escapedAppSrcRoot = appSrcRoot
+  .split(path.sep)
+  .map((segment) => segment.replace(/[|\\{}()[\]^$+*?.]/g, "\\$&"))
+  .join("[\\\\/]");
+const pathSeparatorPattern = "[\\\\/]";
+
+config.resolver.extraNodeModules = {
+  ...(config.resolver.extraNodeModules ?? {}),
+  react: path.join(appNodeModulesRoot, "react"),
+  "react-dom": path.join(appNodeModulesRoot, "react-dom"),
+  "react/jsx-runtime": path.join(appNodeModulesRoot, "react/jsx-runtime"),
+  "react/jsx-dev-runtime": path.join(appNodeModulesRoot, "react/jsx-dev-runtime"),
+};
+config.resolver.blockList = new RegExp(
+  `(^${escapedAppSrcRoot}${pathSeparatorPattern}.*\\.(test|spec)\\.(ts|tsx)$|${pathSeparatorPattern}__tests__${pathSeparatorPattern}.*)$`,
+);
+
+function isLocalModuleImport(moduleName) {
+  return (
+    moduleName.startsWith("./") ||
+    moduleName.startsWith("../") ||
+    moduleName.startsWith("@/") ||
+    path.isAbsolute(moduleName)
+  );
+}
+
+function resolveWithCustomWebOverlay(context, moduleName, platform) {
+  const shouldResolveCustomWebVariant =
+    platform === "web" &&
+    customWebPlatform.length > 0 &&
+    customWebPlatform !== "web" &&
+    isLocalModuleImport(moduleName);
+
+  if (shouldResolveCustomWebVariant) {
+    const overlayContext = {
+      ...context,
+      // Resolve only "<custom-platform>.<ext>" variants in overlay mode.
+      sourceExts: context.sourceExts.map((ext) => `${customWebPlatform}.${ext}`),
+      preferNativePlatform: false,
+    };
+
+    try {
+      return defaultResolveRequest(overlayContext, moduleName, null);
+    } catch {
+      // Ignore overlay misses and continue with normal web resolution.
+    }
+  }
+
+  return defaultResolveRequest(context, moduleName, platform);
+}
+
+config.resolver.resolveRequest = (context, moduleName, platform) => {
+  const origin = context.originModulePath;
+  if (
+    origin &&
+    (origin.startsWith(serverSrcRoot) || origin.startsWith(relaySrcRoot)) &&
+    moduleName.endsWith(".js")
+  ) {
+    const tsModuleName = moduleName.replace(/\.js$/, ".ts");
+    const candidatePath = path.resolve(path.dirname(origin), tsModuleName);
+    if (fs.existsSync(candidatePath)) {
+      return resolveWithCustomWebOverlay(context, tsModuleName, platform);
+    }
+  }
+
+  return resolveWithCustomWebOverlay(context, moduleName, platform);
+};
+
+module.exports = config;

packages/app/metro.config.js

@@ -1,45 +0,0 @@
-const { getDefaultConfig } = require("expo/metro-config");
-const { resolve } = require("metro-resolver");
-const fs = require("fs");
-const path = require("path");
-
-const projectRoot = __dirname;
-const monorepoRoot = path.resolve(projectRoot, "../..");
-const serverSrcRoot = path.resolve(projectRoot, "../server/src");
-const relaySrcRoot = path.resolve(projectRoot, "../relay/src");
-
-const config = getDefaultConfig(projectRoot);
-const defaultResolveRequest = config.resolver.resolveRequest ?? resolve;
-
-// This app imports TypeScript sources from sibling workspaces (server/relay).
-// Metro's default hierarchical lookup won't find hoisted deps when resolving
-// from those out-of-tree source files, so point Metro at the monorepo root.
-config.watchFolders = Array.from(
-  new Set([...(config.watchFolders ?? []), monorepoRoot])
-);
-config.resolver.nodeModulesPaths = Array.from(
-  new Set([
-    ...(config.resolver.nodeModulesPaths ?? []),
-    path.join(projectRoot, "node_modules"),
-    path.join(monorepoRoot, "node_modules"),
-  ])
-);
-
-config.resolver.resolveRequest = (context, moduleName, platform) => {
-  const origin = context.originModulePath;
-  if (
-    origin &&
-    (origin.startsWith(serverSrcRoot) || origin.startsWith(relaySrcRoot)) &&
-    moduleName.endsWith(".js")
-  ) {
-    const tsModuleName = moduleName.replace(/\.js$/, ".ts");
-    const candidatePath = path.resolve(path.dirname(origin), tsModuleName);
-    if (fs.existsSync(candidatePath)) {
-      return defaultResolveRequest(context, tsModuleName, platform);
-    }
-  }
-
-  return defaultResolveRequest(context, moduleName, platform);
-};
-
-module.exports = config;

packages/app/package.json

@@ -1,16 +1,18 @@
 {
   "name": "@getpaseo/app",
   "main": "index.ts",
-  "version": "0.1.13",
+  "version": "0.1.43",
   "private": true,
   "scripts": {
     "start": "expo start",
     "reset-project": "node ./scripts/reset-project.js",
+    "build:workspace-deps": "npm run build --workspace=@getpaseo/highlight && npm run build --workspace=@getpaseo/expo-two-way-audio",
+    "eas-build-post-install": "npm run build:workspace-deps",
     "android": "npm run android:development",
-    "android:development": "APP_VARIANT=development expo prebuild --platform android --clean --non-interactive && APP_VARIANT=development expo run:android --variant=debug",
-    "android:production": "APP_VARIANT=production expo prebuild --platform android --clean --non-interactive && APP_VARIANT=production expo run:android --variant=release",
-    "android:prod": "npm run android:production",
+    "android:development": "APP_VARIANT=development expo prebuild --platform android --non-interactive && APP_VARIANT=development expo run:android --variant=debug",
+    "android:production": "APP_VARIANT=production expo prebuild --platform android --non-interactive && APP_VARIANT=production expo run:android --variant=release",
     "android:release": "npm run android:production",
+    "android:clear": "node -e \"require('node:fs').rmSync('android', { recursive: true, force: true })\"",
     "ios": "expo run:ios",
     "ios:release": "expo run:ios --configuration Release",
     "web": "expo start --web",
@@ -20,27 +22,20 @@
     "test:e2e": "playwright test",
     "test:e2e:ui": "playwright test --ui",
     "build": "npm run build:web",
-    "build:web": "expo export --platform web",
-    "deploy:web": "npm run build:web && wrangler pages deploy dist --project-name paseo-app"
+    "build:web": "npm run build:workspace-deps && expo export --platform web",
+    "deploy:web": "npm run build:web && wrangler pages deploy dist --project-name paseo-app --branch main"
   },
   "dependencies": {
-    "@boudra/expo-two-way-audio": "^0.1.3",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
     "@expo/vector-icons": "^15.0.2",
     "@floating-ui/react-native": "^0.10.7",
-    "@getpaseo/server": "0.1.13",
+    "@getpaseo/expo-two-way-audio": "0.1.43",
+    "@getpaseo/highlight": "0.1.43",
+    "@getpaseo/server": "0.1.43",
     "@gorhom/bottom-sheet": "^5.2.6",
     "@gorhom/portal": "^1.0.14",
-    "@lezer/common": "^1.5.0",
-    "@lezer/css": "^1.3.0",
-    "@lezer/highlight": "^1.2.3",
-    "@lezer/html": "^1.3.13",
-    "@lezer/javascript": "^1.5.4",
-    "@lezer/json": "^1.0.3",
-    "@lezer/markdown": "^1.6.2",
-    "@lezer/python": "^1.1.18",
     "@react-native-async-storage/async-storage": "2.2.0",
     "@react-native-masked-view/masked-view": "^0.3.2",
     "@react-native/normalize-colors": "^0.81.5",
@@ -48,8 +43,15 @@
     "@react-navigation/elements": "^2.6.3",
     "@react-navigation/native": "^7.1.8",
     "@tanstack/react-query": "^5.90.11",
-    "@tauri-apps/api": "^2.9.1",
+    "@tanstack/react-virtual": "^3.13.21",
+    "@xterm/addon-clipboard": "^0.2.0",
     "@xterm/addon-fit": "^0.11.0",
+    "@xterm/addon-image": "^0.9.0",
+    "@xterm/addon-ligatures": "^0.10.0",
+    "@xterm/addon-search": "^0.16.0",
+    "@xterm/addon-unicode11": "^0.9.0",
+    "@xterm/addon-web-links": "^0.12.0",
+    "@xterm/addon-webgl": "^0.19.0",
     "@xterm/xterm": "^6.0.0",
     "base64-js": "^1.5.1",
     "buffer": "^6.0.3",
@@ -77,11 +79,10 @@
     "expo-system-ui": "~6.0.7",
     "expo-updates": "~29.0.12",
     "expo-web-browser": "~15.0.8",
-    "lezer-elixir": "^1.1.2",
     "lucide-react-native": "^0.546.0",
     "mnemonic-id": "^3.2.7",
-    "react": "19.1.0",
-    "react-dom": "19.1.0",
+    "react": "19.1.4",
+    "react-dom": "19.1.4",
     "react-native": "^0.81.5",
     "react-native-css": "^3.0.1",
     "react-native-draggable-flatlist": "^4.0.3",
@@ -89,7 +90,7 @@
     "react-native-gesture-handler": "~2.28.0",
     "react-native-keyboard-controller": "^1.19.2",
     "react-native-markdown-display": "^7.0.2",
-    "react-native-nitro-modules": "^0.30.0",
+    "react-native-nitro-modules": "0.33.8",
     "react-native-permissions": "^5.4.2",
     "react-native-popover-view": "^6.1.0",
     "react-native-reanimated": "~4.1.1",
@@ -110,6 +111,7 @@
     "eas-cli": "^16.24.1",
     "eslint": "^9.25.0",
     "eslint-config-expo": "~10.0.0",
+    "material-icon-theme": "^5.32.0",
     "playwright": "^1.56.1",
     "typescript": "~5.9.2",
     "vitest": "^3.2.4",

packages/app/playwright.config.ts

@@ -1,29 +1,33 @@
-import { defineConfig, devices } from '@playwright/test';
+import { defineConfig, devices } from "@playwright/test";
 
 // E2E_METRO_PORT is set dynamically by global-setup.ts after finding a free port
 // This allows multiple test runs in parallel across different worktrees
-const baseURL = process.env.E2E_BASE_URL ?? `http://localhost:${process.env.E2E_METRO_PORT ?? '8081'}`;
+const baseURL =
+  process.env.E2E_BASE_URL ?? `http://localhost:${process.env.E2E_METRO_PORT ?? "8081"}`;
 
 export default defineConfig({
-  testDir: './e2e',
-  globalSetup: './e2e/global-setup.ts',
+  testDir: "./e2e",
+  globalSetup: "./e2e/global-setup.ts",
   timeout: 60_000,
   expect: {
     timeout: 10_000,
   },
-  fullyParallel: true,
+  // E2E tests share a single daemon/relay/metro stack from global setup.
+  // Running tests concurrently causes cross-test contention and non-deterministic failures.
+  fullyParallel: false,
+  workers: 1,
   retries: process.env.CI ? 1 : 0,
-  reporter: [['list']],
+  reporter: [["list"]],
   use: {
     baseURL,
-    trace: 'retain-on-failure',
-    screenshot: 'only-on-failure',
-    video: 'retain-on-failure',
+    trace: "retain-on-failure",
+    screenshot: "only-on-failure",
+    video: "retain-on-failure",
   },
   projects: [
     {
-      name: 'Desktop Chrome',
-      use: { ...devices['Desktop Chrome'] },
+      name: "Desktop Chrome",
+      use: { ...devices["Desktop Chrome"] },
     },
   ],
   // Note: Metro is started by global-setup.ts on a dynamic port to allow parallel test runs

packages/app/playwright.firefox.config.ts

@@ -0,0 +1,29 @@
+import { defineConfig, devices } from "@playwright/test";
+
+const baseURL =
+  process.env.E2E_BASE_URL ?? `http://localhost:${process.env.E2E_METRO_PORT ?? "8081"}`;
+
+export default defineConfig({
+  testDir: "./e2e",
+  globalSetup: "./e2e/global-setup.ts",
+  timeout: 60_000,
+  expect: {
+    timeout: 10_000,
+  },
+  fullyParallel: false,
+  workers: 1,
+  retries: process.env.CI ? 1 : 0,
+  reporter: [["list"]],
+  use: {
+    baseURL,
+    trace: "retain-on-failure",
+    screenshot: "only-on-failure",
+    video: "retain-on-failure",
+  },
+  projects: [
+    {
+      name: "Desktop Firefox",
+      use: { ...devices["Desktop Firefox"] },
+    },
+  ],
+});

packages/app/playwright.webkit.tmp.config.ts

@@ -0,0 +1,29 @@
+import { defineConfig, devices } from "@playwright/test";
+
+const baseURL =
+  process.env.E2E_BASE_URL ?? `http://localhost:${process.env.E2E_METRO_PORT ?? "8081"}`;
+
+export default defineConfig({
+  testDir: "./e2e",
+  globalSetup: "./e2e/global-setup.ts",
+  timeout: 60_000,
+  expect: {
+    timeout: 10_000,
+  },
+  fullyParallel: false,
+  workers: 1,
+  retries: 0,
+  reporter: [["list"]],
+  use: {
+    baseURL,
+    trace: "retain-on-failure",
+    screenshot: "only-on-failure",
+    video: "retain-on-failure",
+  },
+  projects: [
+    {
+      name: "Desktop Safari",
+      use: { ...devices["Desktop Safari"] },
+    },
+  ],
+});

packages/app/public/index.html

@@ -0,0 +1,60 @@
+<!DOCTYPE html>
+<html lang="%LANG_ISO_CODE%">
+  <head>
+    <meta charset="utf-8" />
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1, shrink-to-fit=no, viewport-fit=cover"
+    />
+    <title>%WEB_TITLE%</title>
+    <!-- The `react-native-web` recommended style reset: https://necolas.github.io/react-native-web/docs/setup/#root-element -->
+    <style id="expo-reset">
+      /* These styles make the body full-height */
+      html,
+      body {
+        height: 100%;
+      }
+      /* These styles disable body scrolling if you are using <ScrollView> */
+      body {
+        overflow: hidden;
+      }
+      /* Prevent white flash before React mounts */
+      @media (prefers-color-scheme: dark) {
+        html, body {
+          background-color: #181B1A;
+        }
+      }
+      /* These styles make the root element full-height */
+      #root {
+        display: flex;
+        height: 100%;
+        flex: 1;
+      }
+    </style>
+    <style>
+      button,
+      a,
+      input,
+      textarea,
+      select,
+      [role='button'],
+      [role='link'],
+      [role='textbox'],
+      [role='combobox'],
+      [role='tab'],
+      [role='switch'],
+      [role='checkbox'],
+      [role='slider'],
+      [role='menuitem'],
+      [tabindex],
+      [contenteditable='true'] {
+        -webkit-app-region: no-drag !important;
+      }
+    </style>
+  </head>
+  <body>
+    <noscript>You need to enable JavaScript to run this app.</noscript>
+    <div id="root"></div>
+  </body>
+</html>

packages/app/scripts/reset-project.js

@@ -91,7 +91,7 @@ const moveDirectories = async (userInput) => {
         userInput === "y"
           ? `\n3. Delete the /${exampleDir} directory when you're done referencing it.`
           : ""
-      }`
+      }`,
     );
   } catch (error) {
     console.error(`❌ Error during script execution: ${error.message}`);
@@ -108,5 +108,5 @@ rl.question(
       console.log("❌ Invalid input. Please enter 'Y' or 'N'.");
       rl.close();
     }
-  }
+  },
 );

packages/app/src/app/+html.tsx

@@ -1,51 +0,0 @@
-import { ScrollViewStyleReset } from "expo-router/html";
-import type { PropsWithChildren } from "react";
-
-// Ensure Unistyles runs before Expo Router statically renders each page.
-import "../styles/unistyles";
-
-const webEcosystemStyles = /* css */ `
-  html {
-    touch-action: auto;
-  }
-
-  body {
-    overflow: auto;
-    overscroll-behavior: contain;
-    -webkit-user-select: text;
-    user-select: text;
-  }
-
-  body * {
-    -webkit-user-select: text;
-    user-select: text;
-  }
-`;
-
-function WebRespectfulStyleReset() {
-  return (
-    <style
-      id="paseo-web-ecosystem"
-      dangerouslySetInnerHTML={{ __html: webEcosystemStyles }}
-    />
-  );
-}
-
-export default function Root({ children }: PropsWithChildren) {
-  return (
-    <html lang="en">
-      <head>
-        <meta charSet="utf-8" />
-        <meta httpEquiv="X-UA-Compatible" content="IE=edge" />
-        <meta
-          name="viewport"
-          content="width=device-width, initial-scale=1, shrink-to-fit=no, user-scalable=yes, minimum-scale=1, maximum-scale=5"
-        />
-        {/* Reset scroll styles so React Native Web views behave like native. */}
-        <ScrollViewStyleReset />
-        <WebRespectfulStyleReset />
-      </head>
-      <body>{children}</body>
-    </html>
-  );
-}

packages/app/src/app/_layout.tsx

@@ -1,6 +1,12 @@
 import "@/styles/unistyles";
 import { polyfillCrypto } from "@/polyfills/crypto";
-import { Stack, usePathname, useRouter } from "expo-router";
+import {
+  Stack,
+  useGlobalSearchParams,
+  useNavigationContainerRef,
+  usePathname,
+  useRouter,
+} from "expo-router";
 import { SafeAreaProvider } from "react-native-safe-area-context";
 import { KeyboardProvider } from "react-native-keyboard-controller";
 import { GestureHandlerRootView, Gesture, GestureDetector } from "react-native-gesture-handler";
@@ -9,19 +15,36 @@ import { PortalProvider } from "@gorhom/portal";
 import { VoiceProvider } from "@/contexts/voice-context";
 import { useAppSettings } from "@/hooks/use-settings";
 import { useFaviconStatus } from "@/hooks/use-favicon-status";
-import { View, ActivityIndicator, Text } from "react-native";
+import { View, Text } from "react-native";
 import { UnistylesRuntime, useUnistyles } from "react-native-unistyles";
-import { darkTheme } from "@/styles/theme";
-import { DaemonRegistryProvider, useDaemonRegistry } from "@/contexts/daemon-registry-context";
-import { DaemonConnectionsProvider, useDaemonConnections } from "@/contexts/daemon-connections-context";
-import { MultiDaemonSessionHost } from "@/components/multi-daemon-session-host";
 import { QueryClientProvider } from "@tanstack/react-query";
-import { useState, useEffect, type ReactNode, useMemo, useRef } from "react";
+import {
+  getHostRuntimeStore,
+  useHosts,
+  useHostMutations,
+  useHostRuntimeClient,
+} from "@/runtime/host-runtime";
+import { shouldUseDesktopDaemon } from "@/desktop/daemon/desktop-daemon";
+import { loadSettingsFromStorage } from "@/hooks/use-settings";
+import { useColorScheme } from "@/hooks/use-color-scheme";
+import { SessionProvider } from "@/contexts/session-context";
+import type { HostProfile } from "@/types/host-connection";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useState,
+  useEffect,
+  type ReactNode,
+  useMemo,
+  useRef,
+} from "react";
 import { Platform } from "react-native";
 import * as Linking from "expo-linking";
 import * as Notifications from "expo-notifications";
-import { SlidingSidebar } from "@/components/sliding-sidebar";
+import { LeftSidebar } from "@/components/left-sidebar";
 import { DownloadToast } from "@/components/download-toast";
+import { UpdateBanner } from "@/desktop/updates/update-banner";
 import { ToastProvider } from "@/contexts/toast-context";
 import { usePanelStore } from "@/stores/panel-store";
 import { runOnJS, interpolate, Extrapolation, useSharedValue } from "react-native-reanimated";
@@ -33,47 +56,95 @@ import {
   HorizontalScrollProvider,
   useHorizontalScrollOptional,
 } from "@/contexts/horizontal-scroll-context";
-import { getIsTauri, getIsTauriMac } from "@/constants/layout";
-import { useTrafficLightPadding } from "@/utils/tauri-window";
+import { getIsElectronRuntime, isCompactFormFactor } from "@/constants/layout";
 import { CommandCenter } from "@/components/command-center";
+import { ProjectPickerModal } from "@/components/project-picker-modal";
 import { KeyboardShortcutsDialog } from "@/components/keyboard-shortcuts-dialog";
 import { useKeyboardShortcuts } from "@/hooks/use-keyboard-shortcuts";
 import { queryClient } from "@/query/query-client";
 import {
   WEB_NOTIFICATION_CLICK_EVENT,
   type WebNotificationClickDetail,
+  ensureOsNotificationPermission,
 } from "@/utils/os-notifications";
+import { getDesktopHost } from "@/desktop/host";
+import { updateDesktopWindowControls } from "@/desktop/electron/window";
 import { buildNotificationRoute } from "@/utils/notification-routing";
 import {
-  buildHostAgentDraftRoute,
+  buildHostRootRoute,
+  mapPathnameToServer,
+  parseServerIdFromPathname,
   parseHostAgentRouteFromPathname,
+  parseWorkspaceOpenIntent,
 } from "@/utils/host-routes";
+import { syncNavigationActiveWorkspace } from "@/stores/navigation-active-workspace-store";
 
 polyfillCrypto();
 
+export type HostRuntimeBootstrapState = {
+  phase: "starting-daemon" | "connecting" | "online" | "error";
+  error: string | null;
+  retry: () => void;
+};
+
+const HostRuntimeBootstrapContext = createContext<HostRuntimeBootstrapState>({
+  phase: "starting-daemon",
+  error: null,
+  retry: () => {},
+});
+
 function PushNotificationRouter() {
   const router = useRouter();
   const lastHandledIdRef = useRef<string | null>(null);
 
   useEffect(() => {
     if (Platform.OS === "web") {
+      let removeDesktopNotificationListener: (() => void) | null = null;
+      let cancelled = false;
+
+      if (getIsElectronRuntime()) {
+        void ensureOsNotificationPermission();
+
+        const unlistenResult = getDesktopHost()?.events?.on?.(
+          "notification-click",
+          (payload: unknown) => {
+            const data =
+              typeof payload === "object" &&
+              payload !== null &&
+              "data" in payload &&
+              typeof (payload as { data?: unknown }).data === "object" &&
+              (payload as { data?: unknown }).data !== null
+                ? (payload as { data: Record<string, unknown> }).data
+                : undefined;
+            router.push(buildNotificationRoute(data) as any);
+          },
+        );
+
+        void Promise.resolve(unlistenResult).then((unlisten) => {
+          if (typeof unlisten !== "function") {
+            return;
+          }
+          if (cancelled) {
+            unlisten();
+            return;
+          }
+          removeDesktopNotificationListener = unlisten;
+        });
+      }
+
       const target = globalThis as unknown as EventTarget;
       const openFromWebClick = (event: Event) => {
         const customEvent = event as CustomEvent<WebNotificationClickDetail>;
-        const route = buildNotificationRoute(customEvent.detail?.data);
         event.preventDefault();
-        router.push(route as any);
+        router.push(buildNotificationRoute(customEvent.detail?.data) as any);
       };
 
-      target.addEventListener(
-        WEB_NOTIFICATION_CLICK_EVENT,
-        openFromWebClick as EventListener
-      );
+      target.addEventListener(WEB_NOTIFICATION_CLICK_EVENT, openFromWebClick as EventListener);
+
       return () => {
-        target.removeEventListener(
-          WEB_NOTIFICATION_CLICK_EVENT,
-          openFromWebClick as EventListener
-        );
+        cancelled = true;
+        removeDesktopNotificationListener?.();
+        target.removeEventListener(WEB_NOTIFICATION_CLICK_EVENT, openFromWebClick as EventListener);
       };
     }
 
@@ -101,8 +172,7 @@ function PushNotificationRouter() {
       router.push(buildNotificationRoute(data) as any);
     };
 
-    const subscription =
-      Notifications.addNotificationResponseReceivedListener(openFromResponse);
+    const subscription = Notifications.addNotificationResponseReceivedListener(openFromResponse);
 
     void Notifications.getLastNotificationResponseAsync().then((response) => {
       if (response) {
@@ -118,63 +188,221 @@ function PushNotificationRouter() {
   return null;
 }
 
+function ManagedDaemonSession({ daemon }: { daemon: HostProfile }) {
+  const client = useHostRuntimeClient(daemon.serverId);
+
+  if (!client) {
+    return null;
+  }
+
+  return (
+    <SessionProvider key={daemon.serverId} serverId={daemon.serverId} client={client}>
+      {null}
+    </SessionProvider>
+  );
+}
+
+function HostSessionManager() {
+  const hosts = useHosts();
+
+  if (hosts.length === 0) {
+    return null;
+  }
+
+  return (
+    <>
+      {hosts.map((daemon) => (
+        <ManagedDaemonSession key={daemon.serverId} daemon={daemon} />
+      ))}
+    </>
+  );
+}
+
+function HostRuntimeBootstrapProvider({ children }: { children: ReactNode }) {
+  const [phase, setPhase] = useState<HostRuntimeBootstrapState["phase"]>("starting-daemon");
+  const [error, setError] = useState<string | null>(null);
+  const [retryToken, setRetryToken] = useState(0);
+  const retry = useCallback(() => {
+    setPhase("starting-daemon");
+    setError(null);
+    setRetryToken((current) => current + 1);
+  }, []);
+
+  useEffect(() => {
+    let cancelled = false;
+    const shouldManageDesktop = shouldUseDesktopDaemon();
+    const store = getHostRuntimeStore();
+
+    const init = async () => {
+      const settings = await loadSettingsFromStorage();
+      const isDesktopManaged = shouldManageDesktop && settings.manageBuiltInDaemon;
+      await store.loadFromStorage();
+      if (isDesktopManaged) {
+        setPhase("starting-daemon");
+        setError(null);
+        const bootstrapResult = await store.bootstrapDesktop();
+        if (!bootstrapResult.ok) {
+          if (!cancelled) {
+            setPhase("error");
+            setError(bootstrapResult.error);
+          }
+          return;
+        }
+
+        if (cancelled) {
+          return;
+        }
+
+        setPhase("connecting");
+        await store.addConnectionFromListenAndWaitForOnline({
+          listenAddress: bootstrapResult.listenAddress,
+          serverId: bootstrapResult.serverId,
+          hostname: bootstrapResult.hostname,
+        });
+        if (!cancelled) {
+          setPhase("online");
+          setError(null);
+        }
+      } else {
+        void store.bootstrap({ manageBuiltInDaemon: settings.manageBuiltInDaemon });
+        if (!cancelled) {
+          setPhase("online");
+          setError(null);
+        }
+      }
+    };
+
+    void init().catch((bootstrapError) => {
+      console.error("[HostRuntime] Failed to initialize store", bootstrapError);
+      if (cancelled) {
+        return;
+      }
+      if (shouldManageDesktop) {
+        setPhase("error");
+        setError(bootstrapError instanceof Error ? bootstrapError.message : String(bootstrapError));
+        return;
+      }
+      setPhase("online");
+      setError(null);
+    });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [retryToken]);
+
+  const state = useMemo<HostRuntimeBootstrapState>(
+    () => ({
+      phase,
+      error,
+      retry,
+    }),
+    [error, phase, retry],
+  );
+
+  return (
+    <HostRuntimeBootstrapContext.Provider value={state}>
+      {children}
+    </HostRuntimeBootstrapContext.Provider>
+  );
+}
+
+export function useStoreReady(): boolean {
+  return useContext(HostRuntimeBootstrapContext).phase === "online";
+}
+
+export function useHostRuntimeBootstrapState(): HostRuntimeBootstrapState {
+  return useContext(HostRuntimeBootstrapContext);
+}
+
 function QueryProvider({ children }: { children: ReactNode }) {
   return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
 }
 
+const rowStyle = { flex: 1, flexDirection: "row" } as const;
+const flexStyle = { flex: 1 } as const;
+
 interface AppContainerProps {
   children: ReactNode;
   selectedAgentId?: string;
+  chromeEnabled?: boolean;
 }
 
-function AppContainer({ children, selectedAgentId }: AppContainerProps) {
+function AppContainer({
+  children,
+  selectedAgentId,
+  chromeEnabled: chromeEnabledOverride,
+}: AppContainerProps) {
   const { theme } = useUnistyles();
-  const { daemons } = useDaemonRegistry();
-  const mobileView = usePanelStore((state) => state.mobileView);
-  const desktopAgentListOpen = usePanelStore((state) => state.desktop.agentListOpen);
-  const openAgentList = usePanelStore((state) => state.openAgentList);
+  const daemons = useHosts();
   const toggleAgentList = usePanelStore((state) => state.toggleAgentList);
   const toggleFileExplorer = usePanelStore((state) => state.toggleFileExplorer);
-  const horizontalScroll = useHorizontalScrollOptional();
+  const toggleBothSidebars = usePanelStore((state) => state.toggleBothSidebars);
+  const toggleFocusMode = usePanelStore((state) => state.toggleFocusMode);
+  const isFocusModeEnabled = usePanelStore((state) => state.desktop.focusModeEnabled);
 
-  const isMobile =
-    UnistylesRuntime.breakpoint === "xs" || UnistylesRuntime.breakpoint === "sm";
-  const chromeEnabled = daemons.length > 0;
-  const isOpen = chromeEnabled
-    ? isMobile
-      ? mobileView === "agent-list"
-      : desktopAgentListOpen
-    : false;
-  const openGestureEnabled =
-    chromeEnabled && isMobile && mobileView === "agent";
+  const isCompactLayout = isCompactFormFactor();
+  const chromeEnabled = chromeEnabledOverride ?? daemons.length > 0;
 
   useKeyboardShortcuts({
     enabled: chromeEnabled,
-    isMobile,
+    isMobile: isCompactLayout,
     toggleAgentList,
     selectedAgentId,
     toggleFileExplorer,
+    toggleBothSidebars,
+    toggleFocusMode,
   });
-  const {
-    translateX,
-    backdropOpacity,
-    windowWidth,
-    animateToOpen,
-    animateToClose,
-    isGesturing,
-  } = useSidebarAnimation();
 
-  // Track initial touch position for manual activation
+  const containerStyle = useMemo(
+    () => ({ flex: 1 as const, backgroundColor: theme.colors.surface0 }),
+    [theme.colors.surface0],
+  );
+
+  const content = (
+    <View style={containerStyle}>
+      <View style={rowStyle}>
+        {!isCompactLayout && chromeEnabled && !isFocusModeEnabled && (
+          <LeftSidebar selectedAgentId={selectedAgentId} />
+        )}
+        <View style={flexStyle}>{children}</View>
+      </View>
+      {isCompactLayout && chromeEnabled && <LeftSidebar selectedAgentId={selectedAgentId} />}
+      <DownloadToast />
+      <UpdateBanner />
+      <CommandCenter />
+      <ProjectPickerModal />
+      <KeyboardShortcutsDialog />
+    </View>
+  );
+
+  if (!isCompactLayout) {
+    return content;
+  }
+
+  return <MobileGestureWrapper chromeEnabled={chromeEnabled}>{content}</MobileGestureWrapper>;
+}
+
+function MobileGestureWrapper({
+  children,
+  chromeEnabled,
+}: {
+  children: ReactNode;
+  chromeEnabled: boolean;
+}) {
+  const mobileView = usePanelStore((state) => state.mobileView);
+  const openAgentList = usePanelStore((state) => state.openAgentList);
+  const horizontalScroll = useHorizontalScrollOptional();
+  const { translateX, backdropOpacity, windowWidth, animateToOpen, animateToClose, isGesturing } =
+    useSidebarAnimation();
   const touchStartX = useSharedValue(0);
+  const openGestureEnabled = chromeEnabled && mobileView === "agent";
 
-  // Open gesture: swipe right from anywhere to open sidebar (interactive drag)
-  // If any horizontal scroll is scrolled right, let the scroll view handle the gesture first
   const openGesture = useMemo(
     () =>
       Gesture.Pan()
         .enabled(openGestureEnabled)
         .manualActivation(true)
-        // Fail if 10px vertical movement happens first (allow vertical scroll)
         .failOffsetY([-10, 10])
         .onTouchesDown((event) => {
           const touch = event.changedTouches[0];
@@ -188,13 +416,11 @@ function AppContainer({ children, selectedAgentId }: AppContainerProps) {
 
           const deltaX = touch.absoluteX - touchStartX.value;
 
-          // If horizontal scroll is scrolled right, fail so ScrollView handles it
           if (horizontalScroll?.isAnyScrolledRight.value) {
             stateManager.fail();
             return;
           }
 
-          // Activate after 15px rightward movement
           if (deltaX > 15) {
             stateManager.activate();
           }
@@ -203,19 +429,17 @@ function AppContainer({ children, selectedAgentId }: AppContainerProps) {
           isGesturing.value = true;
         })
         .onUpdate((event) => {
-          // Start from closed position (-windowWidth) and move towards 0
           const newTranslateX = Math.min(0, -windowWidth + event.translationX);
           translateX.value = newTranslateX;
           backdropOpacity.value = interpolate(
             newTranslateX,
             [-windowWidth, 0],
             [0, 1],
-            Extrapolation.CLAMP
+            Extrapolation.CLAMP,
           );
         })
         .onEnd((event) => {
           isGesturing.value = false;
-          // Open if dragged more than 1/3 of sidebar or fast swipe
           const shouldOpen = event.translationX > windowWidth / 3 || event.velocityX > 500;
           if (shouldOpen) {
             animateToOpen();
@@ -238,62 +462,52 @@ function AppContainer({ children, selectedAgentId }: AppContainerProps) {
       isGesturing,
       horizontalScroll?.isAnyScrolledRight,
       touchStartX,
-    ]
+    ],
   );
 
-  // When sidebar is collapsed on desktop Tauri macOS, add left padding for traffic lights
-  const trafficLightPadding = useTrafficLightPadding();
-  const needsTrafficLightPadding = !isMobile && !isOpen && getIsTauriMac();
-
-  const content = (
-    <View style={{ flex: 1, backgroundColor: theme.colors.surface0 }}>
-      <View style={{ flex: 1, flexDirection: "row" }}>
-        {!isMobile && chromeEnabled && <SlidingSidebar selectedAgentId={selectedAgentId} />}
-        <View style={{ flex: 1, paddingLeft: needsTrafficLightPadding ? trafficLightPadding.left : 0 }}>
-          {children}
-        </View>
-      </View>
-      {isMobile && chromeEnabled && <SlidingSidebar selectedAgentId={selectedAgentId} />}
-      <DownloadToast />
-      <CommandCenter />
-      <KeyboardShortcutsDialog />
-    </View>
-  );
-
-  if (!isMobile) {
-    return content;
-  }
-
   return (
     <GestureDetector gesture={openGesture} touchAction="pan-y">
-      {content}
+      {children}
     </GestureDetector>
   );
 }
 
 function ProvidersWrapper({ children }: { children: ReactNode }) {
   const { settings, isLoading: settingsLoading } = useAppSettings();
-  const { daemons, isLoading: registryLoading, upsertDaemonFromOfferUrl } = useDaemonRegistry();
-  const isLoading = settingsLoading || registryLoading;
+  const { upsertConnectionFromOfferUrl } = useHostMutations();
+  const systemColorScheme = useColorScheme();
+  const { theme } = useUnistyles();
+  const resolvedTheme = settings.theme === "auto" ? (systemColorScheme ?? "light") : settings.theme;
 
   // Apply theme setting on mount and when it changes
   useEffect(() => {
-    if (isLoading) return;
+    if (settingsLoading) return;
     if (settings.theme === "auto") {
       UnistylesRuntime.setAdaptiveThemes(true);
     } else {
       UnistylesRuntime.setAdaptiveThemes(false);
       UnistylesRuntime.setTheme(settings.theme);
     }
-  }, [isLoading, settings.theme]);
+  }, [settingsLoading, settings.theme]);
 
-  if (isLoading) {
-    return <LoadingView />;
-  }
+  useEffect(() => {
+    if (settingsLoading || Platform.OS !== "web") {
+      return;
+    }
+
+    void updateDesktopWindowControls({
+      backgroundColor: theme.colors.surface0,
+      foregroundColor: theme.colors.foreground,
+    }).catch((error) => {
+      console.warn("[DesktopWindow] Failed to update window controls overlay", error);
+    });
+  }, [settingsLoading, resolvedTheme, theme.colors.foreground, theme.colors.surface0]);
 
   return (
     <VoiceProvider>
-      <OfferLinkListener upsertDaemonFromOfferUrl={upsertDaemonFromOfferUrl} />
+      <OfferLinkListener upsertDaemonFromOfferUrl={upsertConnectionFromOfferUrl} />
+      <HostSessionManager />
+      <FaviconStatusSync />
       {children}
     </VoiceProvider>
   );
@@ -316,7 +530,7 @@ function OfferLinkListener({
           if (cancelled) return;
           const serverId = (profile as any)?.serverId;
           if (typeof serverId !== "string" || !serverId) return;
-          router.replace(buildHostAgentDraftRoute(serverId) as any);
+          router.replace(buildHostRootRoute(serverId) as any);
         })
         .catch((error) => {
           if (cancelled) return;
@@ -324,7 +538,9 @@ function OfferLinkListener({
         });
     };
 
-    void Linking.getInitialURL().then(handleUrl).catch(() => undefined);
+    void Linking.getInitialURL()
+      .then(handleUrl)
+      .catch(() => undefined);
 
     const subscription = Linking.addEventListener("url", (event) => {
       handleUrl(event.url);
@@ -340,115 +556,134 @@ function OfferLinkListener({
 }
 
 function AppWithSidebar({ children }: { children: ReactNode }) {
+  const router = useRouter();
   const pathname = usePathname();
-  useFaviconStatus();
+  const params = useGlobalSearchParams<{ open?: string | string[] }>();
+  const hosts = useHosts();
+  const activeServerId = useMemo(() => parseServerIdFromPathname(pathname), [pathname]);
+  const shouldShowAppChrome = activeServerId !== null;
+
+  useEffect(() => {
+    if (!activeServerId || hosts.length === 0) {
+      return;
+    }
+    if (hosts.some((host) => host.serverId === activeServerId)) {
+      return;
+    }
+    router.replace(mapPathnameToServer(pathname, hosts[0]!.serverId) as any);
+  }, [activeServerId, hosts, pathname, router]);
 
   // Parse selectedAgentKey directly from pathname
   // useLocalSearchParams doesn't update when navigating between same-pattern routes
   const selectedAgentKey = useMemo(() => {
+    const workspaceMatch = pathname.match(/^\/h\/([^/]+)\/workspace\/[^/]+(?:\/|$)/);
+    const workspaceServerId = workspaceMatch?.[1]?.trim() ?? "";
+    const openValue = Array.isArray(params.open) ? params.open[0] : params.open;
+    const openIntent = parseWorkspaceOpenIntent(openValue);
+    if (workspaceServerId && openIntent?.kind === "agent") {
+      const agentId = openIntent.agentId.trim();
+      return agentId ? `${workspaceServerId}:${agentId}` : undefined;
+    }
+
     const match = parseHostAgentRouteFromPathname(pathname);
     return match ? `${match.serverId}:${match.agentId}` : undefined;
-  }, [pathname]);
+  }, [params.open, pathname]);
 
   return (
-    <AppContainer selectedAgentId={selectedAgentKey}>{children}</AppContainer>
+    <AppContainer
+      selectedAgentId={shouldShowAppChrome ? selectedAgentKey : undefined}
+      chromeEnabled={shouldShowAppChrome}
+    >
+      {children}
+    </AppContainer>
   );
 }
 
-function LoadingView({ message }: { message?: string } = {}) {
+function FaviconStatusSync() {
+  useFaviconStatus();
+  return null;
+}
+
+function RootStack() {
+  const storeReady = useStoreReady();
+  const { theme } = useUnistyles();
+
   return (
-    <View
-      style={{
-        flex: 1,
-        justifyContent: "center",
-        alignItems: "center",
-        backgroundColor: darkTheme.colors.surface0,
+    <Stack
+      screenOptions={{
+        headerShown: false,
+        animation: "none",
+        contentStyle: {
+          backgroundColor: theme.colors.surface0,
+        },
       }}
     >
-      <ActivityIndicator size="large" color={darkTheme.colors.foreground} />
-      {message ? (
-        <Text
-          style={{
-            color: darkTheme.colors.foregroundMuted,
-            marginTop: 16,
-            fontSize: 14,
-          }}
-        >
-          {message}
-        </Text>
-      ) : null}
-    </View>
+      <Stack.Protected guard={storeReady}>
+        <Stack.Screen name="welcome" />
+        <Stack.Screen name="settings" />
+        <Stack.Screen name="h/[serverId]/workspace/[workspaceId]" />
+        <Stack.Screen
+          name="h/[serverId]/agent/[agentId]"
+          options={{ gestureEnabled: false }}
+        />
+        <Stack.Screen name="h/[serverId]/index" />
+        <Stack.Screen name="h/[serverId]/sessions" />
+        <Stack.Screen name="h/[serverId]/open-project" />
+        <Stack.Screen name="h/[serverId]/settings" />
+        <Stack.Screen name="pair-scan" />
+      </Stack.Protected>
+      <Stack.Screen name="index" />
+    </Stack>
   );
 }
 
-function MissingDaemonView() {
-  return (
-    <View
-      style={{
-        flex: 1,
-        justifyContent: "center",
-        alignItems: "center",
-        padding: 24,
-        backgroundColor: darkTheme.colors.surface0,
-      }}
-    >
-      <ActivityIndicator size="small" color={darkTheme.colors.foreground} />
-      <Text
-        style={{
-          color: darkTheme.colors.foreground,
-          marginTop: 16,
-          textAlign: "center",
-        }}
-      >
-        No host configured. Open Settings to add a server URL.
-      </Text>
-    </View>
-  );
+function NavigationActiveWorkspaceObserver() {
+  const navigationRef = useNavigationContainerRef();
+
+  useEffect(() => {
+    syncNavigationActiveWorkspace(navigationRef);
+    const unsubscribeState = navigationRef.addListener("state", () => {
+      syncNavigationActiveWorkspace(navigationRef);
+    });
+    const unsubscribeReady = navigationRef.addListener("ready" as never, () => {
+      syncNavigationActiveWorkspace(navigationRef);
+    });
+    return () => {
+      unsubscribeState();
+      unsubscribeReady();
+    };
+  }, [navigationRef]);
+
+  return null;
 }
 
 export default function RootLayout() {
+  const { theme } = useUnistyles();
+
   return (
-    <GestureHandlerRootView style={{ flex: 1 }}>
+    <GestureHandlerRootView style={{ flex: 1, backgroundColor: theme.colors.surface0 }}>
+      <NavigationActiveWorkspaceObserver />
       <PortalProvider>
         <SafeAreaProvider>
           <KeyboardProvider>
-            <BottomSheetModalProvider>
-              <QueryProvider>
-                <DaemonRegistryProvider>
-                  <DaemonConnectionsProvider>
-                    <PushNotificationRouter />
-                    <MultiDaemonSessionHost />
-                    <ProvidersWrapper>
-                      <SidebarAnimationProvider>
-                        <HorizontalScrollProvider>
-                          <ToastProvider>
-                            <AppWithSidebar>
-                              <Stack
-                                screenOptions={{
-                                  headerShown: false,
-                                  animation: "none",
-                                }}
-                              >
-                                <Stack.Screen name="index" />
-                                <Stack.Screen
-                                  name="h/[serverId]/agent/[agentId]"
-                                  options={{ gestureEnabled: false }}
-                                />
-                                <Stack.Screen name="h/[serverId]/index" />
-                                <Stack.Screen name="h/[serverId]/agent/index" />
-                                <Stack.Screen name="h/[serverId]/agents" />
-                                <Stack.Screen name="h/[serverId]/settings" />
-                                <Stack.Screen name="pair-scan" />
-                              </Stack>
-                            </AppWithSidebar>
-                          </ToastProvider>
-                        </HorizontalScrollProvider>
-                      </SidebarAnimationProvider>
-                    </ProvidersWrapper>
-                  </DaemonConnectionsProvider>
-                </DaemonRegistryProvider>
-              </QueryProvider>
-            </BottomSheetModalProvider>
+            <QueryProvider>
+              <BottomSheetModalProvider>
+                <HostRuntimeBootstrapProvider>
+                  <PushNotificationRouter />
+                  <ProvidersWrapper>
+                    <SidebarAnimationProvider>
+                      <HorizontalScrollProvider>
+                        <ToastProvider>
+                          <AppWithSidebar>
+                            <RootStack />
+                          </AppWithSidebar>
+                        </ToastProvider>
+                      </HorizontalScrollProvider>
+                    </SidebarAnimationProvider>
+                  </ProvidersWrapper>
+                </HostRuntimeBootstrapProvider>
+              </BottomSheetModalProvider>
+            </QueryProvider>
           </KeyboardProvider>
         </SafeAreaProvider>
       </PortalProvider>

packages/app/src/app/h/[serverId]/agent/[agentId].tsx

@@ -1,17 +1,108 @@
-import { useLocalSearchParams } from "expo-router";
-import { AgentReadyScreen } from "@/screens/agent/agent-ready-screen";
+import { useEffect, useRef } from "react";
+import { useLocalSearchParams, useRouter } from "expo-router";
+import { useSessionStore } from "@/stores/session-store";
+import { useHostRuntimeClient, useHostRuntimeIsConnected } from "@/runtime/host-runtime";
+import { buildHostRootRoute } from "@/utils/host-routes";
+import { prepareWorkspaceTab } from "@/utils/workspace-navigation";
 
 export default function HostAgentReadyRoute() {
+  const router = useRouter();
   const params = useLocalSearchParams<{
     serverId?: string;
     agentId?: string;
   }>();
+  const redirectedRef = useRef(false);
+  const serverId = typeof params.serverId === "string" ? params.serverId : "";
+  const agentId = typeof params.agentId === "string" ? params.agentId : "";
+  const client = useHostRuntimeClient(serverId);
+  const isConnected = useHostRuntimeIsConnected(serverId);
+  const agentCwd = useSessionStore((state) => {
+    if (!serverId || !agentId) {
+      return null;
+    }
+    return state.sessions[serverId]?.agents?.get(agentId)?.cwd ?? null;
+  });
 
-  return (
-    <AgentReadyScreen
-      serverId={typeof params.serverId === "string" ? params.serverId : ""}
-      agentId={typeof params.agentId === "string" ? params.agentId : ""}
-    />
-  );
+  useEffect(() => {
+    if (redirectedRef.current) {
+      return;
+    }
+    if (!serverId || !agentId) {
+      redirectedRef.current = true;
+      router.replace("/" as any);
+      return;
+    }
+
+    const normalizedCwd = agentCwd?.trim();
+    if (normalizedCwd) {
+      redirectedRef.current = true;
+      router.replace(
+        prepareWorkspaceTab({
+          serverId,
+          workspaceId: normalizedCwd,
+          target: { kind: "agent", agentId },
+        }) as any,
+      );
+    }
+  }, [agentCwd, agentId, router, serverId]);
+
+  useEffect(() => {
+    if (redirectedRef.current) {
+      return;
+    }
+    if (!serverId || !agentId) {
+      return;
+    }
+    if (agentCwd?.trim()) {
+      return;
+    }
+    if (!client || !isConnected) {
+      redirectedRef.current = true;
+      router.replace(buildHostRootRoute(serverId) as any);
+    }
+  }, [agentCwd, agentId, client, isConnected, router, serverId]);
+
+  useEffect(() => {
+    if (redirectedRef.current) {
+      return;
+    }
+    if (!serverId || !agentId || !client || !isConnected) {
+      return;
+    }
+
+    let cancelled = false;
+    void client
+      .fetchAgent(agentId)
+      .then((result) => {
+        if (cancelled || redirectedRef.current) {
+          return;
+        }
+        const cwd = result?.agent?.cwd?.trim();
+        redirectedRef.current = true;
+        if (cwd) {
+          router.replace(
+            prepareWorkspaceTab({
+              serverId,
+              workspaceId: cwd,
+              target: { kind: "agent", agentId },
+            }) as any,
+          );
+          return;
+        }
+        router.replace(buildHostRootRoute(serverId) as any);
+      })
+      .catch(() => {
+        if (cancelled || redirectedRef.current) {
+          return;
+        }
+        redirectedRef.current = true;
+        router.replace(buildHostRootRoute(serverId) as any);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [agentId, client, isConnected, router, serverId]);
+
+  return null;
 }
-

packages/app/src/app/h/[serverId]/index.tsx

@@ -1,19 +1,82 @@
 import { useEffect } from "react";
-import { useLocalSearchParams, useRouter } from "expo-router";
-import { buildHostAgentDraftRoute } from "@/utils/host-routes";
+import { useLocalSearchParams, usePathname, useRouter } from "expo-router";
+import { useSessionStore } from "@/stores/session-store";
+import { useFormPreferences } from "@/hooks/use-form-preferences";
+import {
+  buildHostOpenProjectRoute,
+  buildHostRootRoute,
+  buildHostWorkspaceRoute,
+} from "@/utils/host-routes";
+import { prepareWorkspaceTab } from "@/utils/workspace-navigation";
+
+const HOST_ROOT_REDIRECT_DELAY_MS = 300;
 
 export default function HostIndexRoute() {
   const router = useRouter();
+  const pathname = usePathname();
   const params = useLocalSearchParams<{ serverId?: string }>();
   const serverId = typeof params.serverId === "string" ? params.serverId : "";
+  const { isLoading: preferencesLoading } = useFormPreferences();
+  const sessionAgents = useSessionStore((state) =>
+    serverId ? state.sessions[serverId]?.agents : undefined,
+  );
+  const sessionWorkspaces = useSessionStore((state) =>
+    serverId ? state.sessions[serverId]?.workspaces : undefined,
+  );
 
   useEffect(() => {
+    if (preferencesLoading) {
+      return;
+    }
     if (!serverId) {
       return;
     }
-    router.replace(buildHostAgentDraftRoute(serverId) as any);
-  }, [router, serverId]);
+    const rootRoute = buildHostRootRoute(serverId);
+    if (pathname !== rootRoute && pathname !== `${rootRoute}/`) {
+      return;
+    }
+    const timer = setTimeout(() => {
+      if (pathname !== rootRoute && pathname !== `${rootRoute}/`) {
+        return;
+      }
+
+      const visibleAgents = sessionAgents
+        ? Array.from(sessionAgents.values()).filter((agent) => !agent.archivedAt)
+        : [];
+      visibleAgents.sort(
+        (left, right) => right.lastActivityAt.getTime() - left.lastActivityAt.getTime(),
+      );
+
+      const visibleWorkspaces = sessionWorkspaces ? Array.from(sessionWorkspaces.values()) : [];
+      visibleWorkspaces.sort((left, right) => {
+        const leftTime = left.activityAt?.getTime() ?? Number.NEGATIVE_INFINITY;
+        const rightTime = right.activityAt?.getTime() ?? Number.NEGATIVE_INFINITY;
+        return rightTime - leftTime;
+      });
+
+      const primaryAgent = visibleAgents[0];
+      if (primaryAgent?.cwd?.trim()) {
+        router.replace(
+          prepareWorkspaceTab({
+            serverId,
+            workspaceId: primaryAgent.cwd.trim(),
+            target: { kind: "agent", agentId: primaryAgent.id },
+          }) as any,
+        );
+        return;
+      }
+
+      const primaryWorkspace = visibleWorkspaces[0];
+      if (primaryWorkspace?.id?.trim()) {
+        router.replace(buildHostWorkspaceRoute(serverId, primaryWorkspace.id.trim()) as any);
+        return;
+      }
+
+      router.replace(buildHostOpenProjectRoute(serverId) as any);
+    }, HOST_ROOT_REDIRECT_DELAY_MS);
+
+    return () => clearTimeout(timer);
+  }, [pathname, preferencesLoading, router, serverId, sessionAgents, sessionWorkspaces]);
 
   return null;
 }
-

packages/app/src/app/h/[serverId]/open-project.tsx

@@ -1,10 +1,9 @@
 import { useLocalSearchParams } from "expo-router";
-import { DraftAgentScreen } from "@/screens/agent/draft-agent-screen";
+import { OpenProjectScreen } from "@/screens/open-project-screen";
 
-export default function HostDraftAgentRoute() {
+export default function HostOpenProjectRoute() {
   const params = useLocalSearchParams<{ serverId?: string }>();
   const serverId = typeof params.serverId === "string" ? params.serverId : "";
 
-  return <DraftAgentScreen forcedServerId={serverId} />;
+  return <OpenProjectScreen serverId={serverId} />;
 }
-

packages/app/src/app/h/[serverId]/sessions.tsx

@@ -1,9 +1,9 @@
 import { useLocalSearchParams } from "expo-router";
-import { AgentsScreen } from "@/screens/agents-screen";
+import { SessionsScreen } from "@/screens/sessions-screen";
 
 export default function HostAgentsRoute() {
   const params = useLocalSearchParams<{ serverId?: string }>();
   const serverId = typeof params.serverId === "string" ? params.serverId : "";
 
-  return <AgentsScreen serverId={serverId} />;
+  return <SessionsScreen serverId={serverId} />;
 }

packages/app/src/app/h/[serverId]/workspace/[workspaceId]/_layout.tsx

@@ -0,0 +1,89 @@
+import { useEffect, useRef } from "react";
+import { useGlobalSearchParams, useLocalSearchParams, useRouter } from "expo-router";
+import type { WorkspaceTabTarget } from "@/stores/workspace-tabs-store";
+import { WorkspaceScreen } from "@/screens/workspace/workspace-screen";
+import {
+  buildHostWorkspaceRoute,
+  decodeWorkspaceIdFromPathSegment,
+  parseWorkspaceOpenIntent,
+  type WorkspaceOpenIntent,
+} from "@/utils/host-routes";
+import { prepareWorkspaceTab } from "@/utils/workspace-navigation";
+
+function getParamValue(value: string | string[] | undefined): string {
+  if (typeof value === "string") {
+    return value.trim();
+  }
+  if (Array.isArray(value)) {
+    const firstValue = value[0];
+    return typeof firstValue === "string" ? firstValue.trim() : "";
+  }
+  return "";
+}
+
+function getOpenIntentTarget(openIntent: WorkspaceOpenIntent): WorkspaceTabTarget {
+  if (openIntent.kind === "agent") {
+    return { kind: "agent", agentId: openIntent.agentId };
+  }
+  if (openIntent.kind === "terminal") {
+    return { kind: "terminal", terminalId: openIntent.terminalId };
+  }
+  if (openIntent.kind === "file") {
+    return { kind: "file", path: openIntent.path };
+  }
+  return { kind: "draft", draftId: openIntent.draftId };
+}
+
+export default function HostWorkspaceLayout() {
+  const router = useRouter();
+  const consumedIntentRef = useRef<string | null>(null);
+  const params = useLocalSearchParams<{
+    serverId?: string | string[];
+    workspaceId?: string | string[];
+  }>();
+  const globalParams = useGlobalSearchParams<{
+    open?: string | string[];
+  }>();
+  const serverId = getParamValue(params.serverId);
+  const workspaceValue = getParamValue(params.workspaceId);
+  const workspaceId = workspaceValue
+    ? (decodeWorkspaceIdFromPathSegment(workspaceValue) ?? "")
+    : "";
+  const openValue = getParamValue(globalParams.open);
+
+  useEffect(() => {
+    if (!openValue) {
+      return;
+    }
+
+    const consumptionKey = `${serverId}:${workspaceId}:${openValue}`;
+    if (consumedIntentRef.current === consumptionKey) {
+      return;
+    }
+    consumedIntentRef.current = consumptionKey;
+
+    const openIntent = parseWorkspaceOpenIntent(openValue);
+    const route = openIntent
+      ? prepareWorkspaceTab({
+          serverId,
+          workspaceId,
+          target: getOpenIntentTarget(openIntent),
+          pin: openIntent.kind === "agent",
+        })
+      : buildHostWorkspaceRoute(serverId, workspaceId);
+
+    router.replace(route as any);
+  }, [openValue, router, serverId, workspaceId]);
+
+  if (openValue) {
+    return null;
+  }
+
+  return (
+    <WorkspaceScreen
+      key={`${serverId}:${workspaceId}`}
+      serverId={serverId}
+      workspaceId={workspaceId}
+    />
+  );
+}

packages/app/src/app/h/[serverId]/workspace/[workspaceId]/index.tsx

@@ -0,0 +1,3 @@
+export default function HostWorkspaceIndexRoute() {
+  return null;
+}

packages/app/src/app/index.tsx

@@ -1,59 +1,65 @@
-import { useEffect, useMemo } from "react";
-import { ActivityIndicator, View } from "react-native";
-import { useRouter } from "expo-router";
-import { useUnistyles } from "react-native-unistyles";
-import { DraftAgentScreen } from "@/screens/agent/draft-agent-screen";
-import { useDaemonRegistry } from "@/contexts/daemon-registry-context";
-import { useFormPreferences } from "@/hooks/use-form-preferences";
-import { buildHostAgentDraftRoute } from "@/utils/host-routes";
+import { useEffect, useSyncExternalStore } from "react";
+import { usePathname, useRouter } from "expo-router";
+import { StartupSplashScreen } from "@/screens/startup-splash-screen";
+import {
+  useHostRuntimeBootstrapState,
+  useStoreReady,
+} from "@/app/_layout";
+import {
+  getHostRuntimeStore,
+  isHostRuntimeConnected,
+  useHosts,
+} from "@/runtime/host-runtime";
+import { buildHostRootRoute } from "@/utils/host-routes";
+
+const WELCOME_ROUTE = "/welcome";
+
+function useAnyOnlineHostServerId(serverIds: string[]): string | null {
+  const runtime = getHostRuntimeStore();
+
+  return useSyncExternalStore(
+    (onStoreChange) => runtime.subscribeAll(onStoreChange),
+    () => {
+      let firstOnlineServerId: string | null = null;
+      let firstOnlineAt: string | null = null;
+      for (const serverId of serverIds) {
+        const snapshot = runtime.getSnapshot(serverId);
+        const lastOnlineAt = snapshot?.lastOnlineAt ?? null;
+        if (!isHostRuntimeConnected(snapshot) || !lastOnlineAt) {
+          continue;
+        }
+        if (!firstOnlineAt || lastOnlineAt < firstOnlineAt) {
+          firstOnlineAt = lastOnlineAt;
+          firstOnlineServerId = serverId;
+        }
+      }
+      return firstOnlineServerId;
+    },
+    () => null,
+  );
+}
 
 export default function Index() {
   const router = useRouter();
-  const { theme } = useUnistyles();
-  const { daemons, isLoading: registryLoading } = useDaemonRegistry();
-  const { preferences, isLoading: preferencesLoading } = useFormPreferences();
-
-  const targetServerId = useMemo(() => {
-    if (daemons.length === 0) {
-      return null;
-    }
-    if (preferences.serverId) {
-      const match = daemons.find((daemon) => daemon.serverId === preferences.serverId);
-      if (match) {
-        return match.serverId;
-      }
-    }
-    return daemons[0]?.serverId ?? null;
-  }, [daemons, preferences.serverId]);
+  const pathname = usePathname();
+  const bootstrapState = useHostRuntimeBootstrapState();
+  const storeReady = useStoreReady();
+  const hosts = useHosts();
+  const anyOnlineServerId = useAnyOnlineHostServerId(hosts.map((host) => host.serverId));
 
   useEffect(() => {
-    if (registryLoading || preferencesLoading) {
+    if (!storeReady) {
       return;
     }
-    if (!targetServerId) {
+    if (pathname !== "/" && pathname !== "") {
       return;
     }
-    router.replace(buildHostAgentDraftRoute(targetServerId) as any);
-  }, [preferencesLoading, registryLoading, router, targetServerId]);
 
-  if (registryLoading || preferencesLoading) {
-    return (
-      <View
-        style={{
-          flex: 1,
-          justifyContent: "center",
-          alignItems: "center",
-          backgroundColor: theme.colors.surface0,
-        }}
-      >
-        <ActivityIndicator size="small" color={theme.colors.foregroundMuted} />
-      </View>
-    );
-  }
+    const targetRoute = anyOnlineServerId
+      ? buildHostRootRoute(anyOnlineServerId)
+      : WELCOME_ROUTE;
+    router.replace(targetRoute as any);
+  }, [anyOnlineServerId, pathname, router, storeReady]);
 
-  if (!targetServerId) {
-    return <DraftAgentScreen />;
-  }
-
-  return null;
+  return <StartupSplashScreen bootstrapState={bootstrapState} />;
 }

packages/app/src/app/pair-scan.tsx

@@ -5,16 +5,13 @@ import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { CameraView, useCameraPermissions } from "expo-camera";
 import type { BarcodeScanningResult } from "expo-camera";
-import { useDaemonRegistry } from "@/contexts/daemon-registry-context";
+import { useHosts, useHostMutations } from "@/runtime/host-runtime";
 import { useSessionStore } from "@/stores/session-store";
 import { NameHostModal } from "@/components/name-host-modal";
 import { decodeOfferFragmentPayload, normalizeHostPort } from "@/utils/daemon-endpoints";
-import { probeConnection } from "@/utils/test-daemon-connection";
+import { connectToDaemon } from "@/utils/test-daemon-connection";
 import { ConnectionOfferSchema } from "@server/shared/connection-offer";
-import {
-  buildHostAgentDraftRoute,
-  buildHostSettingsRoute,
-} from "@/utils/host-routes";
+import { buildHostRootRoute, buildHostSettingsRoute } from "@/utils/host-routes";
 
 const styles = StyleSheet.create((theme) => ({
   container: {
@@ -148,29 +145,36 @@ export default function PairScanScreen() {
     targetServerId?: string;
   }>();
   const source = typeof params.source === "string" ? params.source : "settings";
-  const sourceServerId =
-    typeof params.sourceServerId === "string" ? params.sourceServerId : null;
+  const sourceServerId = typeof params.sourceServerId === "string" ? params.sourceServerId : null;
   const targetServerId = typeof params.targetServerId === "string" ? params.targetServerId : null;
-  const { daemons, upsertDaemonFromOfferUrl, updateHost } = useDaemonRegistry();
+  const daemons = useHosts();
+  const { upsertConnectionFromOfferUrl: upsertDaemonFromOfferUrl, renameHost } = useHostMutations();
 
   const [permission, requestPermission] = useCameraPermissions();
   const [isPairing, setIsPairing] = useState(false);
   const lastScannedRef = useRef<string | null>(null);
-  const [pendingNameHost, setPendingNameHost] = useState<{ serverId: string; hostname: string | null } | null>(null);
+  const [pendingNameHost, setPendingNameHost] = useState<{
+    serverId: string;
+    hostname: string | null;
+  } | null>(null);
   const pendingNameHostname = useSessionStore(
     useCallback(
       (state) => {
         if (!pendingNameHost) return null;
-        return state.sessions[pendingNameHost.serverId]?.serverInfo?.hostname ?? pendingNameHost.hostname ?? null;
+        return (
+          state.sessions[pendingNameHost.serverId]?.serverInfo?.hostname ??
+          pendingNameHost.hostname ??
+          null
+        );
       },
-      [pendingNameHost]
-    )
+      [pendingNameHost],
+    ),
   );
 
   const returnToSource = useCallback(
     (serverId: string) => {
       if (source === "onboarding") {
-        router.replace(buildHostAgentDraftRoute(serverId) as any);
+        router.replace(buildHostRootRoute(serverId) as any);
         return;
       }
       if (source === "editHost" && targetServerId) {
@@ -189,7 +193,7 @@ export default function PairScanScreen() {
         router.replace(buildHostSettingsRoute(settingsServerId) as any);
       }
     },
-    [router, source, sourceServerId, targetServerId]
+    [router, source, sourceServerId, targetServerId],
   );
 
   const closeToSource = useCallback(() => {
@@ -237,11 +241,14 @@ export default function PairScanScreen() {
 
         if (targetServerId && offer.serverId !== targetServerId) {
           lastScannedRef.current = null;
-          Alert.alert("Wrong daemon", `That QR code belongs to ${offer.serverId}, not ${targetServerId}.`);
+          Alert.alert(
+            "Wrong daemon",
+            `That QR code belongs to ${offer.serverId}, not ${targetServerId}.`,
+          );
           return;
         }
 
-        await probeConnection(
+        const { client } = await connectToDaemon(
           {
             id: "probe",
             type: "relay",
@@ -250,6 +257,7 @@ export default function PairScanScreen() {
           },
           { serverId: offer.serverId },
         );
+        await client.close().catch(() => undefined);
 
         const isNewHost = !daemons.some((daemon) => daemon.serverId === offer.serverId);
         const profile = await upsertDaemonFromOfferUrl(offerUrl);
@@ -268,7 +276,7 @@ export default function PairScanScreen() {
         setIsPairing(false);
       }
     },
-    [daemons, isPairing, pendingNameHost, returnToSource, targetServerId, upsertDaemonFromOfferUrl]
+    [daemons, isPairing, pendingNameHost, returnToSource, targetServerId, upsertDaemonFromOfferUrl],
   );
 
   if (Platform.OS === "web") {
@@ -311,7 +319,7 @@ export default function PairScanScreen() {
           }}
           onSave={(label) => {
             const serverId = pendingNameHost.serverId;
-            void updateHost(serverId, { label }).finally(() => {
+            void renameHost(serverId, label).finally(() => {
               setPendingNameHost(null);
               returnToSource(serverId);
             });
@@ -332,10 +340,7 @@ export default function PairScanScreen() {
             <Text style={styles.permissionBody}>
               Allow camera access to scan the pairing QR code from your daemon.
             </Text>
-            <Pressable
-              style={styles.permissionButton}
-              onPress={() => void requestPermission()}
-            >
+            <Pressable style={styles.permissionButton} onPress={() => void requestPermission()}>
               <Text style={styles.permissionButtonText}>Grant permission</Text>
             </Pressable>
           </View>
@@ -354,9 +359,7 @@ export default function PairScanScreen() {
                 <View style={[styles.corner, styles.cornerBL]} />
                 <View style={[styles.corner, styles.cornerBR]} />
               </View>
-              <Text style={styles.helperText}>
-                Point your camera at the pairing QR code.
-              </Text>
+              <Text style={styles.helperText}>Point your camera at the pairing QR code.</Text>
               {isPairing ? (
                 <Text style={[styles.helperText, { color: theme.colors.foreground }]}>
                   Pairing…

packages/app/src/app/settings.tsx

@@ -0,0 +1,27 @@
+import { useEffect, useMemo } from "react";
+import { useRouter } from "expo-router";
+import { DraftAgentScreen } from "@/screens/agent/draft-agent-screen";
+import { useHosts } from "@/runtime/host-runtime";
+import { buildHostSettingsRoute } from "@/utils/host-routes";
+
+export default function LegacySettingsRoute() {
+  const router = useRouter();
+  const daemons = useHosts();
+
+  const targetServerId = useMemo(() => {
+    return daemons[0]?.serverId ?? null;
+  }, [daemons]);
+
+  useEffect(() => {
+    if (!targetServerId) {
+      return;
+    }
+    router.replace(buildHostSettingsRoute(targetServerId) as any);
+  }, [router, targetServerId]);
+
+  if (!targetServerId) {
+    return <DraftAgentScreen />;
+  }
+
+  return null;
+}

packages/app/src/app/welcome.tsx

@@ -0,0 +1,5 @@
+import { WelcomeScreen } from "@/components/welcome-screen";
+
+export default function WelcomeRoute() {
+  return <WelcomeScreen />;
+}

packages/app/src/attachments/local-file-attachment-store.ts

@@ -0,0 +1,205 @@
+import * as FileSystem from "expo-file-system/legacy";
+import {
+  type AttachmentStore,
+  type AttachmentStorageType,
+  type AttachmentMetadata,
+  type SaveAttachmentInput,
+} from "@/attachments/types";
+import {
+  blobToBase64,
+  fileUriToPath,
+  generateAttachmentId,
+  getFileExtensionFromName,
+  normalizeMimeType,
+  parseDataUrl,
+  pathToFileUri,
+} from "@/attachments/utils";
+
+const IMAGE_EXTENSION_BY_MIME_TYPE: Record<string, string> = {
+  "image/png": ".png",
+  "image/jpeg": ".jpg",
+  "image/jpg": ".jpg",
+  "image/gif": ".gif",
+  "image/webp": ".webp",
+  "image/avif": ".avif",
+  "image/heic": ".heic",
+  "image/heif": ".heif",
+  "image/tiff": ".tiff",
+  "image/bmp": ".bmp",
+  "image/svg+xml": ".svg",
+};
+
+function extensionForAttachment(params: { fileName?: string | null; mimeType: string }): string {
+  const fromName = getFileExtensionFromName(params.fileName);
+  if (fromName) {
+    return fromName;
+  }
+  return IMAGE_EXTENSION_BY_MIME_TYPE[params.mimeType] ?? ".img";
+}
+
+async function ensureDirectory(uri: string): Promise<void> {
+  const info = await FileSystem.getInfoAsync(uri);
+  if (info.exists && info.isDirectory) {
+    return;
+  }
+  await FileSystem.makeDirectoryAsync(uri, { intermediates: true });
+}
+
+async function writeFromSource(input: {
+  source: SaveAttachmentInput["source"];
+  targetUri: string;
+  mimeType: string;
+}): Promise<void> {
+  if (input.source.kind === "file_uri") {
+    const from = pathToFileUri(input.source.uri);
+    if (from === input.targetUri) {
+      return;
+    }
+    await FileSystem.copyAsync({ from, to: input.targetUri });
+    return;
+  }
+
+  if (input.source.kind === "data_url") {
+    const parsed = parseDataUrl(input.source.dataUrl);
+    const mimeType = normalizeMimeType(parsed.mimeType || input.mimeType);
+    const base64 = parsed.base64;
+    await FileSystem.writeAsStringAsync(input.targetUri, base64, {
+      encoding: FileSystem.EncodingType.Base64,
+    });
+    if (mimeType !== input.mimeType) {
+      return;
+    }
+    return;
+  }
+
+  const base64 = await blobToBase64(input.source.blob);
+  await FileSystem.writeAsStringAsync(input.targetUri, base64, {
+    encoding: FileSystem.EncodingType.Base64,
+  });
+}
+
+function attachmentUri(metadata: AttachmentMetadata): string {
+  return pathToFileUri(metadata.storageKey);
+}
+
+export function createLocalFileAttachmentStore(params: {
+  storageType: Extract<AttachmentStorageType, "desktop-file" | "native-file">;
+  baseDirectoryName: string;
+  resolvePreviewUrl: (attachment: AttachmentMetadata) => Promise<string>;
+  releasePreviewUrl?: (input: { attachment: AttachmentMetadata; url: string }) => Promise<void>;
+}): AttachmentStore {
+  const baseDirectory = FileSystem.cacheDirectory
+    ? `${FileSystem.cacheDirectory}${params.baseDirectoryName}/`
+    : null;
+
+  async function resolveTarget(input: SaveAttachmentInput): Promise<{
+    id: string;
+    mimeType: string;
+    fileName: string | null;
+    createdAt: number;
+    targetUri: string;
+    storageKey: string;
+  }> {
+    if (!baseDirectory) {
+      throw new Error("expo-file-system cacheDirectory is unavailable.");
+    }
+
+    await ensureDirectory(baseDirectory);
+
+    const id = input.id ?? generateAttachmentId();
+    const mimeTypeFromSource =
+      input.source.kind === "data_url"
+        ? parseDataUrl(input.source.dataUrl).mimeType
+        : input.source.kind === "blob"
+          ? input.source.blob.type
+          : undefined;
+    const mimeType = normalizeMimeType(input.mimeType ?? mimeTypeFromSource);
+    const fileName = input.fileName ?? null;
+    const extension = extensionForAttachment({ fileName, mimeType });
+    const createdAt = Date.now();
+    const targetUri = `${baseDirectory}${id}${extension}`;
+    const storageKey = fileUriToPath(targetUri);
+
+    return {
+      id,
+      mimeType,
+      fileName,
+      createdAt,
+      targetUri,
+      storageKey,
+    };
+  }
+
+  return {
+    storageType: params.storageType,
+
+    async save(input): Promise<AttachmentMetadata> {
+      const target = await resolveTarget(input);
+      await writeFromSource({
+        source: input.source,
+        targetUri: target.targetUri,
+        mimeType: target.mimeType,
+      });
+
+      const info = await FileSystem.getInfoAsync(target.targetUri);
+      const byteSize =
+        info.exists && typeof (info as { size?: number }).size === "number"
+          ? (info as { size: number }).size
+          : null;
+      return {
+        id: target.id,
+        mimeType: target.mimeType,
+        storageType: params.storageType,
+        storageKey: target.storageKey,
+        fileName: target.fileName,
+        byteSize,
+        createdAt: target.createdAt,
+      };
+    },
+
+    async encodeBase64({ attachment }): Promise<string> {
+      const uri = attachmentUri(attachment);
+      return await FileSystem.readAsStringAsync(uri, {
+        encoding: FileSystem.EncodingType.Base64,
+      });
+    },
+
+    async resolvePreviewUrl({ attachment }): Promise<string> {
+      return await params.resolvePreviewUrl(attachment);
+    },
+
+    ...(params.releasePreviewUrl
+      ? {
+          async releasePreviewUrl(input: {
+            attachment: AttachmentMetadata;
+            url: string;
+          }): Promise<void> {
+            await params.releasePreviewUrl?.(input);
+          },
+        }
+      : {}),
+
+    async delete({ attachment }): Promise<void> {
+      await FileSystem.deleteAsync(attachmentUri(attachment), { idempotent: true });
+    },
+
+    async garbageCollect({ referencedIds }): Promise<void> {
+      if (!baseDirectory) {
+        return;
+      }
+      await ensureDirectory(baseDirectory);
+      const entries = await FileSystem.readDirectoryAsync(baseDirectory);
+      await Promise.all(
+        entries.map(async (entryName) => {
+          const id = entryName.split(".", 1)[0] ?? "";
+          if (!id || referencedIds.has(id)) {
+            return;
+          }
+          await FileSystem.deleteAsync(`${baseDirectory}${entryName}`, {
+            idempotent: true,
+          });
+        }),
+      );
+    },
+  };
+}

packages/app/src/attachments/native/native-file-attachment-store.ts

@@ -0,0 +1,27 @@
+import { createLocalFileAttachmentStore } from "@/attachments/local-file-attachment-store";
+import { isAbsolutePath } from "@/utils/path";
+
+export function createNativeFileAttachmentStore() {
+  return createLocalFileAttachmentStore({
+    storageType: "native-file",
+    baseDirectoryName: "paseo-native-attachments",
+    resolvePreviewUrl: async (attachment) => {
+      if (attachment.storageKey.startsWith("file://")) {
+        return attachment.storageKey;
+      }
+      if (isAbsolutePath(attachment.storageKey)) {
+        if (attachment.storageKey.startsWith("/")) {
+          return `file://${attachment.storageKey}`;
+        }
+
+        // UNC paths: \\server\share -> file://server/share
+        if (attachment.storageKey.startsWith("\\\\")) {
+          return `file:${attachment.storageKey.replace(/\\/g, "/")}`;
+        }
+
+        return `file:///${attachment.storageKey.replace(/\\/g, "/")}`;
+      }
+      return attachment.storageKey;
+    },
+  });
+}