fix: remove the races behind the e2e flakes and the product bugs they exposed

.github/workflows/ci.yml

@@ -93,9 +93,11 @@ jobs:
       - name: Check API site content and links
         run: bun run site:check
 
-  validate:
+  changes:
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    timeout-minutes: 5
+    outputs:
+      code: ${{ steps.changes.outputs.code }}
 
     steps:
       - name: Check out repository
@@ -128,50 +130,85 @@ jobs:
 
           echo "code=$code" >> "$GITHUB_OUTPUT"
 
+  unit:
+    needs: changes
+    if: needs.changes.outputs.code == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
       - name: Set up Bun
-        if: steps.changes.outputs.code == 'true'
         uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
         with:
           bun-version: 1.4.2
 
       - name: Install dependencies
-        if: steps.changes.outputs.code == 'true'
         run: bun install --frozen-lockfile
 
       - name: Type check
-        if: steps.changes.outputs.code == 'true'
         # Bun executes and bundles TypeScript without ever checking it, so
         # tsc --noEmit (strict tsconfig) is the only thing standing between
         # a type error and main. Cheapest check, so it runs first.
         run: bun run typecheck
 
       - name: Audit dependencies for vulnerabilities
-        if: steps.changes.outputs.code == 'true'
         # Fails the build on a moderate-or-higher advisory against the
         # installed tree, so new advisories surface on the PR rather than by
         # manual `bun audit`. Low-severity advisories are reported but do not
         # block. Renovate (lockFileMaintenance + osvVulnerabilityAlerts) is the
         # primary remediation path; this is the backstop.
         run: bun audit --audit-level=moderate
 
-      - name: Install Playwright Chromium and WebKit
-        if: steps.changes.outputs.code == 'true'
-        run: bunx playwright install --with-deps chromium webkit
-
       - name: Run unit and integration tests
-        if: steps.changes.outputs.code == 'true'
-        run: bun test
+        # `bun test --parallel=4`: four worker processes, each running whole
+        # files in isolation, the committed timings starting the slowest
+        # files first. Real-process tests wait for the events they assert on
+        # rather than for fixed delays, so they hold under the contention of
+        # four workers on a four-core runner.
+        run: bun run test:ci
 
       - name: Run license audit
-        if: steps.changes.outputs.code == 'true'
         run: bun run check:licenses
 
       - name: Build standalone executable
-        if: steps.changes.outputs.code == 'true'
         run: bun run build
 
+      # The smoke test drives the compiled binary with Chromium; the unit
+      # suite needs no browser. Browsers are cached per Playwright version;
+      # the system libraries they link against are installed every run.
+      - name: Resolve Playwright version
+        id: playwright
+        run: echo "version=$(jq -r .version node_modules/playwright-core/package.json)" >> "$GITHUB_OUTPUT"
+
+      - name: Restore Playwright Chromium
+        id: browsers
+        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ runner.arch }}-${{ steps.playwright.outputs.version }}-chromium
+
+      - name: Install Playwright Chromium
+        if: steps.browsers.outputs.cache-hit != 'true'
+        run: bunx playwright install --with-deps chromium
+
+      - name: Install Playwright Chromium system dependencies
+        if: steps.browsers.outputs.cache-hit == 'true'
+        run: bunx playwright install-deps chromium
+
+      - name: Save Playwright Chromium
+        if: steps.browsers.outputs.cache-hit != 'true'
+        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.cache/ms-playwright
+          key: ${{ steps.browsers.outputs.cache-primary-key }}
+
       - name: Smoke-test the compiled binary
-        if: steps.changes.outputs.code == 'true'
         # Catches compile-mode-only bugs the e2e suite misses: it runs in
         # dev mode against tests/e2e/server.ts, not against ./dist/uatu.
         # The feature-folder refactor (PR #57) shipped two such bugs that
@@ -180,18 +217,171 @@ jobs:
         # whose init never ran at boot.
         run: bun run smoke
 
+  e2e:
+    needs: changes
+    if: needs.changes.outputs.code == 'true'
+    name: e2e (${{ matrix.name }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    strategy:
+      # Every leg runs to the end so the merged report shows all failures.
+      fail-fast: false
+      matrix:
+        include:
+          # The functional project runs in two legs split by file list
+          # (UATU_E2E_LEG, see playwright.config.ts), balanced by measured
+          # worker time; each leg runs the config's 4 workers.
+          - name: leg 1 of 2
+            id: leg-1
+            leg: "1"
+            args: --project=e2e
+          - name: leg 2 of 2
+            id: leg-2
+            leg: "2"
+            args: --project=e2e
+          # The timing-budget suites (tagged @perf) run apart, with the perf
+          # project's own lower worker limit, so neighbouring workers cannot
+          # eat into their frame and interaction budgets.
+          - name: perf
+            id: perf
+            args: --project=perf
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: 1.4.2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Resolve Playwright version
+        id: playwright
+        run: echo "version=$(jq -r .version node_modules/playwright-core/package.json)" >> "$GITHUB_OUTPUT"
+
+      - name: Restore Playwright Chromium and WebKit
+        id: browsers
+        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ runner.arch }}-${{ steps.playwright.outputs.version }}-chromium-webkit
+
+      - name: Install Playwright Chromium and WebKit
+        if: steps.browsers.outputs.cache-hit != 'true'
+        run: bunx playwright install --with-deps chromium webkit
+
+      - name: Install Playwright system dependencies
+        if: steps.browsers.outputs.cache-hit == 'true'
+        run: bunx playwright install-deps chromium webkit
+
+      - name: Save Playwright Chromium and WebKit
+        if: steps.browsers.outputs.cache-hit != 'true'
+        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.cache/ms-playwright
+          key: ${{ steps.browsers.outputs.cache-primary-key }}
+
       - name: Run Playwright end-to-end tests
-        if: steps.changes.outputs.code == 'true'
-        run: bun run test:e2e
+        env:
+          # CI reports as a blob per leg; e2e-report merges them into the
+          # HTML report when a leg fails.
+          PLAYWRIGHT_BLOB_OUTPUT_NAME: report-${{ matrix.id }}.zip
+          UATU_E2E_LEG: ${{ matrix.leg }}
+        run: bun run test:e2e ${{ matrix.args }}
 
-      - name: Upload Playwright artifacts on failure
+      - name: Upload blob report
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: blob-report-${{ matrix.id }}
+          path: blob-report
+          retention-days: 3
+          if-no-files-found: ignore
+
+      - name: Upload Playwright test results on failure
         if: failure()
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
-          name: playwright-artifacts
-          path: |
-            playwright-report
-            test-results
+          name: playwright-test-results-${{ matrix.id }}
+          path: test-results
+          if-no-files-found: ignore
+
+  e2e-report:
+    needs: [changes, e2e]
+    # Only a failed run needs the HTML report, as before the split.
+    if: ${{ always() && needs.changes.outputs.code == 'true' && needs.e2e.result != 'success' && needs.e2e.result != 'skipped' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: 1.4.2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Download blob reports
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          pattern: blob-report-*
+          path: all-blob-reports
+          merge-multiple: true
+
+      - name: Merge into an HTML report
+        env:
+          PLAYWRIGHT_HTML_OPEN: never
+        run: bunx playwright merge-reports --reporter html ./all-blob-reports
+
+      - name: Upload Playwright report
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: playwright-report
+          path: playwright-report
+
+  # The single required check. Unit, build and e2e run as separate jobs;
+  # this one keeps the `validate` name the merge ruleset requires and passes
+  # only when every one of them passed, or all were skipped for a change
+  # that touches no code.
+  validate:
+    needs: [changes, unit, e2e]
+    if: ${{ always() }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Require every validation job
+        env:
+          CHANGES: ${{ needs.changes.result }}
+          CODE: ${{ needs.changes.outputs.code }}
+          UNIT: ${{ needs.unit.result }}
+          E2E: ${{ needs.e2e.result }}
+        run: |
+          if [ "$CHANGES" != "success" ]; then
+            echo "::error::Change classification finished '$CHANGES'."
+            exit 1
+          fi
+          if [ "$CODE" = "true" ]; then expected=success; else expected=skipped; fi
+          failed=0
+          for job in "unit:$UNIT" "e2e:$E2E"; do
+            if [ "${job#*:}" != "$expected" ]; then
+              echo "::error::Job ${job%%:*} finished '${job#*:}', expected '$expected'."
+              failed=1
+            fi
+          done
+          exit "$failed"
 
   validate-specs:
     runs-on: ubuntu-latest

ARCHITECTURE.md

@@ -477,6 +477,7 @@ Failure paths:
 
 - File no longer exists → Session throws → Routes returns 404 → `preview/mount.ts` shows the "no longer exists" empty state.
 - File is binary → Session throws `"document is binary"` → Routes returns 415 → `preview/binary.ts` or `preview/image.ts` renders the appropriate fallback (image for `.png` / `.jpg` / etc., a "not viewable" notice otherwise).
+- Anything else (a read error such as `EMFILE` or `EACCES`, a renderer that throws) → Routes returns 500 (`documentErrorStatus` in `server/render-dispatch.ts`) → `preview/mount.ts` says the file couldn't be loaded and retries with backoff (`preview/load-retry.ts`), as it does when the request gets no answer. A 404 is not retried: the `document` topic re-fetches when the file comes back.
 
 Pushed updates take a different path. The child emits state events on its internal `/api/events` route, and the hub fans them out to every subscribed page over `/api/hub/live` (see [Live delivery](#live-delivery)).
 
@@ -503,7 +504,7 @@ Every `appState` field has exactly one owning module: direct assignment (`appSta
 |---|---|
 | `selectedId`, `previewMode` | `shell/selection.ts` |
 | `followEnabled` | `shell/follow.ts` (the four follow-mode rules) |
-| `roots`, `repositories`, `scope`, `unscopedFingerprint` | `shell/events.ts` (`applyServerSnapshot`) |
+| `roots`, `repositories`, `scope`, `unscopedFingerprint` | `shell/events.ts` (`applyServerSnapshot`, module-private; boot enters through `adoptBootSnapshot`, which also records the snapshot's freshness so an older live frame is refused) |
 | `viewMode`, `wrap` | `preview/view-mode.ts` |
 | `viewLayout`, `splitRatio` | `preview/layout.ts` |
 | `diffStyle` | `preview/diff.ts` |

CLAUDE.md

@@ -195,10 +195,32 @@ is path-filtered (`.github/workflows/desktop-ci.yml`); it builds with plain
 
 - `bun run dev` — dev hub at `http://127.0.0.1:4702/` (`dev/hub.json`, user
   `dev` / password `dev`) with `testdata/watch-docs` registered and opened
-- `bun test` — unit suite (~18s)
+- `bun test` — unit suite, one file at a time (about 3 min on a CI runner)
+- `bun run test:ci` — the same suite in parallel, and what CI's required
+  `unit` job runs: `bun test --parallel=4` (four worker processes, each file
+  isolated) with `tests/unit-timings.json` starting the slowest files first;
+  the longest file, `src/hub/worktree-lifecycle.integration.test.ts`, sets
+  the floor (on a 6-core laptop about 70 s, against about 280 s one file at
+  a time). Under that contention a test must wait for the event it asserts
+  on (a process exit, a pump that has handled an event), never for a fixed
+  delay, and a test driving real processes or real Git may need a budget
+  above the 5 s default.
+  Refresh the timings with `bun run test:ci --update-timings` when files
+  move a lot
 - When developing Uatu inside a Hub-managed workspace, credential tests may
   discover Uatu's projected Git/SSH wrappers. Use a clean tool environment for
   those tests; do not change product behavior to accommodate nested projection.
-- `bun test:e2e` — Playwright suite (~5min, `workers: 1` serial)
+- `bun run test:e2e` — the whole Playwright suite, both projects (about 870
+  tests, 4 workers, `fullyParallel`, retries only on CI). CI splits the `e2e`
+  project into two legs by file list (`UATU_E2E_LEG=1`/`2`, see
+  `playwright.config.ts`; each leg takes about 15–17 min on a 4-core runner)
+  and runs `perf` in its own job, then merges their blob reports into one
+  HTML report. Unset, `UATU_E2E_LEG` runs the whole project.
+- `bun run test:e2e:perf` — only the `perf` project: tests tagged `@perf`
+  that hold a frame, interaction, or load budget (chat-follow-stability,
+  the long-output shell test, hub-live-stream), at most 2 workers.
+  `bun run test:e2e:no-perf` (the `e2e` project) skips them. Tag a new
+  budget test `@perf`; make deterministic work counters its pass criterion
+  and keep wall-clock time as evidence or a loose guard.
 - `bun run build` — compile the single-file `dist/uatu` binary
 - `bun run check:licenses` — license audit

CONTRIBUTING.md

@@ -110,7 +110,7 @@ same core checks as CI should pass:
 ```bash
 bun run typecheck
 bun audit --audit-level=moderate
-bun test
+bun run test:ci
 bun run check:licenses
 bun run build
 bun run smoke

api/contract.test.ts

@@ -43,7 +43,9 @@ type Streaming = { channels: Record<string, unknown>; schemas: Record<string, ob
 describe("API contract structure", () => {
   test("metadata, schemas, and all source examples validate", async () => {
     await validateApi();
-  });
+    // CPU-bound: about a second alone, several when other test files share the
+    // cores (`bun test --parallel`), so the default five seconds is no bound.
+  }, 30_000);
 
   test("OpenAPI operations exactly match the public inventory", async () => {
     const [openapi, inventory] = await Promise.all([

package.json

@@ -13,11 +13,14 @@
     "bench:render": "bun run scripts/bench-render.ts",
     "bench:chat": "bun run scripts/bench-chat.ts",
     "test": "bun test",
+    "test:ci": "bun test --parallel=4 --timings=tests/unit-timings.json",
     "typecheck": "tsc --noEmit",
     "check:licenses": "bun run src/shared/license-check.ts",
     "coverage:agents": "bun run scripts/agent-coverage.ts",
     "e2e:install": "playwright install chromium webkit",
     "test:e2e": "playwright test",
+    "test:e2e:perf": "playwright test --project=perf",
+    "test:e2e:no-perf": "playwright test --project=e2e",
     "test:e2e:headed": "playwright test --headed",
     "test:e2e:ui": "playwright test --ui",
     "test:e2e:debug": "playwright test --debug",