feat(e2e): multi-run isolation for real-provider E2E (Phase 2)

Centralize branch-namespace identity in scripts/e2e-namespace.sh
(e2e/pr/<n>/<provider>/run-<id>-<attempt> and
e2e/branch/<sanitized-id>/<provider>/run-<id>-<attempt>, with a
content-hash suffix so differently-slashed branch names can't collide),
sourced by e2e-harness.sh, the new e2e-namespace-cleanup.sh, and
e2e-janitor.sh -- one canonical implementation, not several drifting
apart.

Implement the three-layer cleanup hierarchy the isolation model needs:
- Layer 1 (scripts/e2e-harness.sh cleanup): unchanged in spirit, now
  deletes only this run's own uniquely-named branch.
- Layer 2 (scripts/e2e-namespace-cleanup.sh + new
  .github/workflows/e2e-pr-cleanup.yml / e2e-branch-cleanup.yml):
  authoritative on PR close or source-branch delete, removes the whole
  e2e/pr/<n>/** or e2e/branch/<id>/** namespace. PR cleanup uses
  pull_request_target with no ref: override on checkout, so it only
  ever runs this repo's own trusted code/secrets, never the closing
  PR's branch.
- Layer 3 (scripts/e2e-janitor.sh + new .github/workflows/e2e-janitor.yml,
  scheduled every 6h): TTL sweep (24h default) of any leftover e2e/**
  branch via generic git for-each-ref/push --delete, tolerant of
  already-deleted refs.

Removes e2e-harness.sh's old ad hoc sweep subcommand/gfs-e2e-<provider>-*
naming, superseded by the above.

ci.yml's provider-e2e job: E2E_WORKDIR now pinned per
run-id/run-attempt/provider under  (was a shared
e2e-<provider> dir), E2E_PR_NUMBER/E2E_SOURCE_BRANCH passed through for
provision, and a per-source/provider concurrency group
(cancel-in-progress: true) so a repeated push/rerun cancels its own
predecessor -- cancellation is not a cleanup mechanism, so this is only
possible because every run still gets its own unique branch regardless.

Rewrites docs/testing/real-provider-e2e.md's isolation model with a
Mermaid diagram of the cleanup hierarchy.

Verification: npx eslint . -- 0 errors; npm run build -- clean;
npx vitest run -- 527 passed; yaml.safe_load on all touched/new workflow
files; bash -n on all new/changed scripts; functional dry-runs of the
namespace/janitor/cleanup logic against throwaway local git repos; real
end-to-end run against a live local Gitea sandbox (14/14 E2E tests
passed) with the new harness code.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: ClaudiaFang

.github/workflows/ci.yml

@@ -50,6 +50,8 @@ jobs:
               - 'src/utils/symlink.ts'
               - 'e2e/**'
               - 'scripts/e2e-harness.sh'
+              - 'scripts/e2e-namespace.sh'
+              - 'scripts/e2e-namespace-cleanup.sh'
               - 'scripts/run-e2e.sh'
               - 'package.json'
               - 'package-lock.json'
@@ -80,6 +82,19 @@ jobs:
       max-parallel: 3
       matrix:
         provider: [github, gitlab, gitea]
+    # One group per source (PR number, else branch)/provider, so a repeated
+    # push or a workflow rerun cancels its own predecessor instead of piling
+    # up runner/provider load -- but this is NOT a cleanup mechanism (see
+    # scripts/e2e-harness.sh's per-run branch naming): a cancelled run's
+    # branch can still be mid-delete when the next one starts, which is
+    # exactly why every run gets its own unique branch regardless of
+    # cancellation. `concurrency:` at job level *does* support the `matrix`
+    # context (unlike job-level `if:`, see the comment below), so each
+    # matrix leg gets its own group.
+    concurrency:
+      group: >-
+        e2e-${{ github.event.pull_request.number && format('pr-{0}', github.event.pull_request.number) || format('branch-{0}', github.ref_name) }}-${{ matrix.provider }}
+      cancel-in-progress: true
     env:
       E2E_GITHUB_OWNER: ${{ vars.E2E_GITHUB_OWNER }}
       E2E_GITHUB_REPO: ${{ vars.E2E_GITHUB_REPO }}
@@ -91,6 +106,17 @@ jobs:
       E2E_GITLAB_PROJECT_ID: ${{ secrets.E2E_GITLAB_PROJECT_ID }}
       E2E_GITLAB_TOKEN: ${{ secrets.E2E_GITLAB_TOKEN }}
       E2E_KEEP_BRANCH: ${{ github.event.inputs.keep_branch }}
+      # Identity inputs for scripts/e2e-namespace.sh (via e2e-harness.sh's
+      # `provision`): PR runs get e2e/pr/<number>/**, everything else
+      # (push/workflow_dispatch/schedule) is a branch-only run under
+      # e2e/branch/<id>/**. github.head_ref is only set for pull_request
+      # events; ref_name covers push/dispatch/schedule.
+      E2E_PR_NUMBER: ${{ github.event.pull_request.number }}
+      E2E_SOURCE_BRANCH: ${{ github.head_ref || github.ref_name }}
+      # Unique per run_id/run_attempt/provider so a previous killed job's
+      # local files can never leak into this one -- never a shared/reused
+      # directory across runs (see docs/testing/real-provider-e2e.md).
+      E2E_WORKDIR: ${{ runner.temp }}/git-files-sync-e2e/${{ github.run_id }}/${{ github.run_attempt }}/${{ matrix.provider }}
     steps:
       # Per-provider gate (needs `matrix`, so it runs as a step, not the job-level
       # `if:` above -- see the comment on that `if:` for why). A fork PR (head repo
@@ -139,30 +165,25 @@ jobs:
         if: steps.gate.outputs.run == 'true'
 
       # Arrange/Assert/cleanup are Shell + Git (scripts/e2e-harness.sh); Act
-      # stays production TypeScript (npx vitest). $E2E_WORKDIR is fixed for
-      # the whole job so all four steps below share the same run state/
-      # generated runtime adapters (see scripts/e2e-harness.sh's own
-      # `workdir` comment) -- set once here rather than depending on each
-      # step's own default.
+      # stays production TypeScript (npx vitest). E2E_WORKDIR/E2E_PR_NUMBER/
+      # E2E_SOURCE_BRANCH are set once at job level (see the job `env:`
+      # above) so all steps below share the same run state/identity.
       - name: Provision isolated branch/container
         if: steps.gate.outputs.run == 'true'
         env:
           E2E_PROVIDER: ${{ matrix.provider }}
-          E2E_WORKDIR: ${{ runner.temp }}/e2e-${{ matrix.provider }}
         run: scripts/e2e-harness.sh provision
 
       - name: Seed baseline fixture
         if: steps.gate.outputs.run == 'true'
         env:
           E2E_PROVIDER: ${{ matrix.provider }}
-          E2E_WORKDIR: ${{ runner.temp }}/e2e-${{ matrix.provider }}
         run: scripts/e2e-harness.sh seed
 
       - name: Run provider E2E (production TypeScript, real provider)
         if: steps.gate.outputs.run == 'true'
         env:
           E2E_PROVIDER: ${{ matrix.provider }}
-          E2E_WORKDIR: ${{ runner.temp }}/e2e-${{ matrix.provider }}
         run: |
           set -a
           # shellcheck disable=SC1091
@@ -175,14 +196,17 @@ jobs:
         if: steps.gate.outputs.run == 'true'
         env:
           E2E_PROVIDER: ${{ matrix.provider }}
-          E2E_WORKDIR: ${{ runner.temp }}/e2e-${{ matrix.provider }}
         run: scripts/e2e-harness.sh verify
 
+      # `if: always()` -- cleanup is best-effort, never a prerequisite for
+      # the next run (see scripts/e2e-harness.sh's cmd_cleanup and
+      # docs/testing/real-provider-e2e.md's cleanup hierarchy); a
+      # cancelled/killed job still gets a shot at this step, but the next
+      # run never depends on it succeeding.
       - name: Cleanup
         if: always() && steps.gate.outputs.run == 'true'
         env:
           E2E_PROVIDER: ${{ matrix.provider }}
-          E2E_WORKDIR: ${{ runner.temp }}/e2e-${{ matrix.provider }}
         run: scripts/e2e-harness.sh cleanup
 
   # Aggregates the matrix into a single required status so branch protection

.github/workflows/e2e-branch-cleanup.yml

@@ -0,0 +1,52 @@
+name: E2E branch cleanup
+
+# Layer 2 of the cleanup hierarchy (docs/testing/real-provider-e2e.md):
+# authoritative for the e2e/branch/<id>/** namespace once its source branch
+# is deleted. `delete` events always run from the default branch's workflow
+# file (the deleted ref can't supply one), so this is inherently trusted --
+# no `pull_request_target`-style checkout concern applies here.
+on:
+  delete:
+
+permissions:
+  contents: read
+
+jobs:
+  cleanup:
+    name: E2E branch cleanup / ${{ matrix.provider }}
+    if: github.event.ref_type == 'branch'
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Gitea has no persistent branches to clean up -- its whole
+        # container is torn down per-run by scripts/e2e-harness.sh cleanup.
+        provider: [github, gitlab]
+    # Same group naming as the provider-e2e job in ci.yml
+    # (e2e-branch-<source-branch>-<provider>) so this cleanup queues
+    # behind, rather than races, an E2E run still in flight for the same
+    # branch/provider. cancel-in-progress: false -- must never cancel an
+    # active E2E run, only run after it.
+    concurrency:
+      group: e2e-branch-${{ github.event.ref }}-${{ matrix.provider }}
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Delete e2e/branch/<id>/** namespace
+        env:
+          E2E_PROVIDER: ${{ matrix.provider }}
+          # github.event.ref's exact format (full "refs/heads/foo" vs short
+          # "foo") isn't consistently documented across event types; strip
+          # any refs/heads/ prefix so this always matches the short branch
+          # name ci.yml's provider-e2e job used at provision time
+          # (github.head_ref || github.ref_name -- both already short).
+          E2E_SOURCE_BRANCH_RAW: ${{ github.event.ref }}
+          E2E_GITHUB_OWNER: ${{ vars.E2E_GITHUB_OWNER }}
+          E2E_GITHUB_REPO: ${{ vars.E2E_GITHUB_REPO }}
+          E2E_GITHUB_TOKEN: ${{ secrets.E2E_GITHUB_TOKEN }}
+          E2E_GITLAB_PROJECT_ID: ${{ secrets.E2E_GITLAB_PROJECT_ID }}
+          E2E_GITLAB_TOKEN: ${{ secrets.E2E_GITLAB_TOKEN }}
+        run: |
+          export E2E_SOURCE_BRANCH="${E2E_SOURCE_BRANCH_RAW#refs/heads/}"
+          scripts/e2e-namespace-cleanup.sh

.github/workflows/e2e-janitor.yml

@@ -0,0 +1,48 @@
+name: E2E janitor
+
+# Layer 3 of the cleanup hierarchy (docs/testing/real-provider-e2e.md):
+# TTL-based garbage collection of e2e/** branches on the dedicated E2E
+# sandbox repos, independent of whether layer 1 (current-run cleanup, in
+# scripts/e2e-harness.sh) or layer 2 (PR-close / branch-delete cleanup, in
+# e2e-pr-cleanup.yml / e2e-branch-cleanup.yml) ever ran -- covers runner
+# crashes, forced cancellations, workflow timeouts, and cleanup-step
+# failures in either of the other two layers. Scheduled, not triggered by
+# any repo event, so it always runs from the default branch's own workflow
+# file/scripts.
+on:
+  schedule:
+    - cron: '0 */6 * * *'
+  workflow_dispatch:
+    inputs:
+      ttl_hours:
+        description: 'Delete e2e/** branches older than this many hours'
+        default: '24'
+
+permissions:
+  contents: read
+
+jobs:
+  janitor:
+    name: E2E janitor / ${{ matrix.provider }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Gitea has no persistent branches to sweep -- its whole container
+        # is torn down per-run by scripts/e2e-harness.sh cleanup.
+        provider: [github, gitlab]
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Sweep stale e2e/** branches
+        env:
+          E2E_PROVIDER: ${{ matrix.provider }}
+          TTL_HOURS: ${{ github.event.inputs.ttl_hours }}
+          E2E_GITHUB_OWNER: ${{ vars.E2E_GITHUB_OWNER }}
+          E2E_GITHUB_REPO: ${{ vars.E2E_GITHUB_REPO }}
+          E2E_GITHUB_TOKEN: ${{ secrets.E2E_GITHUB_TOKEN }}
+          E2E_GITLAB_PROJECT_ID: ${{ secrets.E2E_GITLAB_PROJECT_ID }}
+          E2E_GITLAB_TOKEN: ${{ secrets.E2E_GITLAB_TOKEN }}
+        run: |
+          [ -n "$TTL_HOURS" ] && export E2E_JANITOR_TTL_SECONDS=$((TTL_HOURS * 3600))
+          scripts/e2e-janitor.sh

.github/workflows/e2e-pr-cleanup.yml

@@ -0,0 +1,52 @@
+name: E2E PR cleanup
+
+# Layer 2 of the cleanup hierarchy (docs/testing/real-provider-e2e.md):
+# authoritative for the e2e/pr/<number>/** namespace once a PR closes,
+# merged or not. `pull_request_target` (not `pull_request`) so this always
+# runs the workflow file from the base branch -- trusted code -- with
+# `contents: read`+secrets available even for a fork PR, while never
+# checking out or executing anything from the closing PR's own branch (see
+# the checkout step below: no `ref:` override, so it resolves to the base
+# branch/trusted commit that triggered the event, never the PR head).
+on:
+  pull_request_target:
+    types: [closed]
+
+permissions:
+  contents: read
+
+jobs:
+  cleanup:
+    name: E2E PR cleanup / ${{ matrix.provider }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Gitea has no persistent branches to clean up -- its whole
+        # container is torn down per-run by scripts/e2e-harness.sh cleanup.
+        provider: [github, gitlab]
+    # Same group naming as the provider-e2e job in ci.yml
+    # (e2e-pr-<number>-<provider>) so this cleanup queues behind, rather
+    # than races, an E2E run still in flight for the same PR/provider.
+    # cancel-in-progress: false -- this must never cancel an active E2E run;
+    # it only needs to run after it.
+    concurrency:
+      group: e2e-pr-${{ github.event.pull_request.number }}-${{ matrix.provider }}
+      cancel-in-progress: false
+    steps:
+      # No `ref:` -- actions/checkout defaults to the commit that triggered
+      # this pull_request_target event, which is the base branch, not the
+      # PR head. This is the trust boundary: only ever this repo's own
+      # scripts run, never anything from the PR being closed.
+      - uses: actions/checkout@v6
+
+      - name: Delete e2e/pr/${{ github.event.pull_request.number }}/** namespace
+        env:
+          E2E_PROVIDER: ${{ matrix.provider }}
+          E2E_PR_NUMBER: ${{ github.event.pull_request.number }}
+          E2E_GITHUB_OWNER: ${{ vars.E2E_GITHUB_OWNER }}
+          E2E_GITHUB_REPO: ${{ vars.E2E_GITHUB_REPO }}
+          E2E_GITHUB_TOKEN: ${{ secrets.E2E_GITHUB_TOKEN }}
+          E2E_GITLAB_PROJECT_ID: ${{ secrets.E2E_GITLAB_PROJECT_ID }}
+          E2E_GITLAB_TOKEN: ${{ secrets.E2E_GITLAB_TOKEN }}
+        run: scripts/e2e-namespace-cleanup.sh