diff --git a/.claude/skills/verify-clerk-android/SKILL.md b/.claude/skills/verify-clerk-android/SKILL.md
index 5b8f5a7b9..35abf406a 100644
--- a/.claude/skills/verify-clerk-android/SKILL.md
+++ b/.claude/skills/verify-clerk-android/SKILL.md
@@ -1,11 +1,11 @@
 ---
 name: verify-clerk-android
-description: Drive the clerk-android SDK UI (AuthView, UserButton, UserProfileView, OrganizationSwitcher, session tasks) in the :e2e host app on an Android emulator against a real Clerk development instance that the CLI creates and deletes, and capture video, screenshots, and the app log as evidence. Use it to prove any change to source/api, source/ui, or the :e2e host works before calling it done, to reproduce a UI bug, or to run the golden regression specs.
+description: Drive the clerk-android SDK UI (AuthView, UserButton, UserProfileView, OrganizationSwitcher, session tasks) in the :e2e host app on an Android emulator, on this machine or on a CI runner, against a real Clerk development instance that the CLI creates and deletes, and capture video, screenshots, and the app log as evidence. Use it to prove any change to source/api, source/ui, or the :e2e host works before calling it done, to reproduce a UI bug, or to run the golden regression specs.
 ---
 
 # verify-clerk-android
 
-`e2e-tests/bin/control-clerk-android` is a control CLI over [e2e](https://github.com/tester-army/e2e). It builds the debug APK of `:e2e`, the test app that this file calls the host, boots an emulator, creates one Clerk application for the worktree, seeds `+clerk_test` users, runs specs, and keeps the evidence.
+`e2e-tests/bin/control-clerk-android` is a control CLI over [e2e](https://github.com/tester-army/e2e). It builds the debug APK of `:e2e`, the test app that this file calls the host, boots an emulator, creates one Clerk application for the worktree, seeds `+clerk_test` users, runs specs, and keeps the evidence. The emulator runs on this machine when this machine can run it, and on a CI runner when it cannot. The CLI chooses and says which, and every verb, spec, and evidence file is the same either way.
 
 The tests are an ordinary e2e project. `e2e.config.ts` and `specs/` run under `npx e2e run` when the environment names a device, a build of the test app, and a development instance's keys. The CLI sits on top: it makes those three for a run and keeps the evidence. [The package README](../../../e2e-tests/README.md) has the commands for a run by hand and what such a run leaves out.
 
@@ -24,6 +24,8 @@ A machine needs these once:
 
 The first `up` writes the `Clerk_Verify_Pixel` AVD when the machine has none. An AVD you already have is never changed.
 
+A machine that cannot run the emulator, such as one with no SDK or a Linux machine with no KVM, needs only Node 24 (24.8 or newer), the credential, and access to GitHub. The CLI then borrows an emulator on a CI runner, as the end of this section describes.
+
 ```console
 $ npm ci --prefix e2e-tests   # once per worktree
 $ e2e-tests/bin/control-clerk-android doctor
@@ -49,6 +51,20 @@ The CLI drives only the lane emulators it boots. Any other emulator on a lane po
 
 Each worktree runs its own agent-device daemon from its own `node_modules`, with state under `.verify/agent-device/`, and `down` stops it.
 
+When this machine cannot run the emulator, `up` borrows one on a GitHub Actions runner. The runner session builds a pushed commit, never your working tree, so the loop is commit, push, `up`. This `up` forces the runner with `--backend remote`. Its first line, one of its `wait` lines, and its last line:
+
+```console
+$ git commit -am "..." && git push
+$ e2e-tests/bin/control-clerk-android up --backend remote
+backend remote  forced by --backend remote
+wait    run <run> has waited 14s, now for the tunnel on ubuntu-24.04
+device  Clerk_Verify_Pixel on ubuntu-24.04  remote  leased by this worktree  installed android-cba5fdb5c161
+```
+
+With no flag, the first line gives the reason instead, such as `backend remote  local is out: there is no /dev/kvm, so this machine has no hardware virtualization for the emulator; the device runs on a CI runner (ubuntu-24.04 unless --runner names another), started through verify-remote.yml on clerk/clerk-android`.
+
+A session runs on a free GitHub-hosted runner. Allow about ten minutes for the first `up` on a runner, most of that the first Gradle build. `--runner blacksmith-4vcpu-ubuntu-2404` on `up` leases a Blacksmith runner instead, which is billed by the minute. A session holds its runner until it stops, so run `down` as soon as you are done. `--backend local` or `--backend remote` forces the choice, and `--runner <label>` names another runner label. [references/remote.md](references/remote.md) has how the CLI chooses, what a session needs from this machine, the labels, the cost, and what crosses the tunnel.
+
 ## Doctor
 
 ```console
@@ -61,6 +77,8 @@ Before the first `up`, `build` is the one failing check, and its fix is `e2e-tes
 
 `doctor --live` also proves that the credential can create, configure, and delete an application. It creates one application, configures it, compares it with the standard file, and deletes it, unless this worktree already holds one.
 
+With the remote backend, plain `doctor` checks that GitHub has your commit. It starts no workflow run and pushes nothing. `doctor --live` starts one short session on a free runner, with no emulator, to prove that a session can start.
+
 ## Drive
 
 Input only goes through specs. A spec is a TypeScript file that uses the `host` fixture from `specs/fixtures.ts` and e2e's `screen` locators.
@@ -75,6 +93,8 @@ $ e2e-tests/bin/control-clerk-android screen --png                       # plus
 
 `run --all` runs every golden spec. `run` also takes `--grep <regex>`, `--retries <n>`, `--no-video`, and `--wait <seconds>`. `--retries <n>` runs a failed test again, up to `n` more times. The default is 0, so a run of your own change shows exactly what happened. [references/cli.md](references/cli.md) has every flag, the `--json` output, and the exit codes.
 
+With a remote session, an edit to the app reaches the emulator only through a pushed commit: commit and push, then `run` again, and the same session builds it. A commit that only touches specs needs no push, because specs run from this machine.
+
 ```ts
 import { tapMiddle } from '../../compose.ts';
 import { test, expect } from '../../fixtures.ts';
@@ -102,7 +122,7 @@ The home is the host's own screen. With no active session it shows `Signed out`
 
 The host has a small flow of its own only where the SDK has no view for one. `Sign in` and `Sign in full screen` show `AuthView`, `Custom sign-in` opens a form built on the SDK's API, and `Sign out` calls `Clerk.auth.signOut()`. When a change needs a fact or a flow that no SDK view covers, add it to the home as a real app would show it, such as a button and its visible result, and assert on that.
 
-Locate with test tags, `screen.getByTestId('clerk.auth.start.identifier')`. The SDK's tags start with `clerk.`, and `source/ui/src/main/java/com/clerk/ui/ClerkTestTags.kt` lists them. The host's own tags start with `e2e.`, except those of the custom sign-in form, which start with `verify.customSignIn.`, and `e2e/src/main/java/com/clerk/e2e/E2ETags.kt` lists them. All of these tags are internal test hooks and may change. Fall back to visible text only where nothing is tagged. Every spec keeps at least one exact assertion on a test tag or on visible text.
+Locate with test tags, `screen.getByTestId('clerk.auth.start.identifier')`. The SDK's tags start with `clerk.`, and `source/ui/src/main/java/com/clerk/ui/ClerkTestTags.kt` lists them. The host's own tags start with `e2e.`, except those of the custom sign-in form, which start with `verify.customSignIn.`, and `e2e/src/main/java/com/clerk/e2e/E2ETags.kt` lists them. All of these tags are internal test hooks and may change. Fall back to visible text only where nothing is tagged. Every spec keeps at least one exact assertion on a test tag or on visible text. To assert on the text of a node, use `await expect(locator).toHaveText('...')`.
 
 ### Signing in
 
@@ -125,13 +145,13 @@ A spec names no instance. Most specs run on the standard settings and declare no
 
 ### Golden and explored specs
 
-Golden specs under `specs/golden/<feature>/` are committed and cover the Feature Map in `features/`. Prove your own change, and leave the rest of the golden specs to the `Verify end-to-end tests` workflow (`.github/workflows/verify-e2e.yml`). The release workflow runs every one of them unchanged before it creates a release, and publishes nothing when one fails. When your change is to behavior a golden spec already covers, that spec is your proof: run it. Run another feature's specs yourself when you changed code that feature shares, because nothing else runs them until a release, and a failure there stops the release.
+Golden specs under `specs/golden/<feature>/` are committed and cover the Feature Map in `features/`. Prove your own change, and leave the rest of the golden specs to the `Verify end-to-end tests` workflow (`.github/workflows/verify-e2e.yml`). The release workflow runs every one of them unchanged before it creates a release, and publishes nothing when one fails. When your change is to behavior a golden spec already covers, that spec is your proof: run it. A spec covers a behavior only when it asserts on it. A spec that passes through the screen you changed without checking what you changed is not your proof. Run another feature's specs yourself when you changed code that feature shares, because nothing else runs them until a release, and a failure there stops the release.
 
 For new work, write a spec under `specs/explored/`, which is gitignored and does not exist in a fresh worktree. Run it, read the screen it ended on with `screen`, and fix locators from that output until it passes. A failing spec prints `FAIL`, the first assertion message, and the path of its failure page, which lists every step, the screen tree at the failure, and a screenshot. `run` exits 1.
 
 With `--retries`, a test that fails and then passes prints `flaky` and the error of its failed attempt, and a `flaky` line under the results counts such tests. `run.json` records the test as `flaky` with its `attempts`, never as passed, and `run` exits 0. The failure page of the failed attempt and the files of every attempt stay in the run directory. A test that fails on every attempt prints `FAIL`, and `run` exits 1.
 
-When the change adds or changes a user-facing behavior, the PR commits the spec into `specs/golden/<feature>/`, with its settings file if it has one, and updates the feature file. A golden spec sits one folder deeper, so its import of the fixture changes with the move:
+When the change adds or changes what the SDK does, the PR commits the spec into `specs/golden/<feature>/`, with its settings file if it has one, and updates the feature's page and its line in `features/README.md`. A change to wording or appearance alone does not earn a golden spec, because a spec that pins a label fails on the next change of wording: leave that spec in `specs/explored/`. A golden spec sits one folder deeper, so its import of the fixture changes with the move:
 
 ```console
 $ mkdir -p e2e-tests/specs/golden/<feature> && mv e2e-tests/specs/explored/probe.e2e.ts e2e-tests/specs/golden/<feature>/
@@ -164,20 +184,34 @@ Proof standards: drive the real user path. The video and the screenshots show th
 
 After a run, the CLI searches the run directory for every secret the run used (the Platform API key, secret keys, tickets, the passwords the tests typed, and a GitHub token in `GITHUB_TOKEN` or `GH_TOKEN`), and for any token shaped like a JWT. A hit marks the file tainted in `run.json`, and a tainted run cannot be attached.
 
+A remote run is laid out the same. Its `run.json` also has `remote`, with `provider`, `runner`, and `builtSha`, and its video is recorded on the runner's emulator and then fetched.
+
 ```console
 $ e2e-tests/bin/control-clerk-android attach <run-id> --pr <n>                       # video and every screenshot
 $ e2e-tests/bin/control-clerk-android attach <run-id> --pr <n> --screenshot profile  # video and one screenshot
 ```
 
-`attach` posts once per run with `gh pr comment --attach`, and says so when the `gh` on this machine has no such flag. It refuses a run that is tainted, failed, or whose `app.log` names a user that the run did not create. Without it, name the run id in the PR and say the evidence was not attached.
+`attach` puts the video and the screenshots in the description of the pull request with `gh pr edit --attach`. It writes one block: a line that names the run, the device, and the commit, then the files, between the comments `<!-- verify-evidence:android -->` and `<!-- /verify-evidence:android -->`. The first `attach` adds the block after the description. A later `attach` replaces the block, so the description holds the latest run and the media does not pile up. `attach` changes nothing outside the block. Keep both comments or remove both: `attach` refuses a description that has one without the other, or either one twice. A comment counts only when it is a whole line outside a code fence, so a description can quote one in a sentence or show a whole block as an example.
+
+`attach` reads the description again just before it writes, and builds on the newer text once if it changed. It cannot see an edit that someone saves while the files upload, and that edit is lost, so do not edit the description while `attach` runs.
+
+On a machine whose `gh` can attach, `attach` edits the description itself and prints `posted`. That needs gh 2.99.0 or newer, whose `gh pr edit` has `--attach`. It uploads a run to a PR once, and a second `attach` of the same run and PR prints `already posted`.
+
+`attach` always tries `gh pr edit --attach` itself first, on every kind of machine, and hands off only when that cannot work. On a machine whose `gh` cannot attach, such as a cloud sandbox, it hands the files of a remote run to the session's runner and prints `handed off`. Run it before `down`. The evidence reaches the description after `down` ends the session, when the `verify-attach` workflow publishes it. Its line says that the session reported the result, links the session's run, and names the account that started the session and the commit the run was made at. That workflow publishes only to the open pull request of the session's branch, and only when the commit the session started on and the commit of the run are both commits of that pull request. So open the pull request before `up`. A later push does not lose the evidence: the line then says that the pull request has newer commits. To show the newer commit, `run` and `attach` again, which replaces the block. `attach` checks the pull request first, and fails with the reason when the workflow would refuse it.
+
+When this machine cannot attach and there is no session to hand the files to, or the hand-off fails, `attach` fails and says which. Then name the run id in the PR and say that the evidence was not attached. A run on a local emulator has no session, so its fix is a newer `gh`. [The emulator on a CI runner](references/remote.md) has what the repository needs before a hand-off can be published, and its limits.
+
+`attach` refuses a run that is tainted, failed, or whose `app.log` names a user that the run did not create.
 
 Attach the run of your own change. Run your new or changed spec on its own and attach that run, so the PR video shows only the behavior the change is about. If you ran other golden specs too, cite that run's id in the PR.
 
+On a local emulator, work in this order: commit, `run` the spec of your change, `git push`, open the pull request, `attach`, then `down`. Commit first, so that the line `attach` writes names a commit the pull request holds. In the pull request, name the run id and the specs you ran, and say what you did not run.
+
 ## Cleanup
 
 ```console
 $ e2e-tests/bin/control-clerk-android down --dry-run   # what it would release, delete, and stop
-$ e2e-tests/bin/control-clerk-android down             # kill the lane emulator, delete this worktree's application with every user in it, stop this worktree's agent-device daemon
+$ e2e-tests/bin/control-clerk-android down             # kill the lane emulator or end the remote session, delete this worktree's application with every user in it, stop this worktree's agent-device daemon
 $ e2e-tests/bin/control-clerk-android down --stale     # also finish cleanup left by a crashed run in this worktree
 ```
 
@@ -185,6 +219,8 @@ $ e2e-tests/bin/control-clerk-android down --stale     # also finish cleanup lef
 
 `down` does not stop an agent-device daemon that a by-hand `npx e2e run` left running, because the CLI did not start it. `npx agent-device daemon stop` stops it, as `e2e-tests/README.md` says.
 
+With a remote session `down` ends the runner job and deletes `.verify/remote/<session>/`. No other checkout ends it. A session that nobody ends stops itself after 15 idle minutes, and always after 60.
+
 It never deletes `.verify/runs/`, and it prints how many runs it kept (`--json` lists their ids). Evidence lives inside the worktree, so `git worktree remove` deletes it. Copy the runs you need out first.
 
 `up` builds the app with a Gradle daemon, and `down` leaves that daemon running. It exits by itself after three hours without a build. `./gradlew --stop` from the repo root stops it at once, with every other idle daemon of the same Gradle version. `down` also leaves the `adb` server running, as Android Studio does. `adb kill-server` stops it.
@@ -195,5 +231,7 @@ If a worktree is removed without `down`, the next `up` or `run` in any worktree
 
 - `src/core/`, `specs/support/`, `specs/fixtures.ts`, and `e2e.config.ts` are shared with the same package in clerk-ios and in clerk/javascript. They are byte copies of the same files in clerk-ios, and `src/core/MANIFEST` pins them. Change them there first, run `node e2e-tests/src/core/manifest.ts --write`, then copy them here. Nothing under `specs/` or `e2e.config.ts` imports the CLI, and `test/seam.test.ts` fails when a file does.
 - `src/platform/android/` boots and owns lanes. The package in clerk/javascript holds copies of its files, so a change here goes there too. `src/host.ts`, `src/host-app.ts`, `specs/app.ts`, `specs/compose.ts`, `specs/phone.ts`, and `specs/totp.ts` are this repo's own.
+- A remote session runs in `.github/workflows/verify-remote.yml`. Its code is `src/core/remote/` (the session agent that runs on the runner, the GitHub Actions provider, and the tunnel), `src/platform/android/session-device.ts`, and `src/platform/android/session-lane.ts`. A running session keeps the `src/core/` of the commit it started on, so after a change to a file that `src/core/MANIFEST` lists, commit, push, `down`, then `up`.
+- `.github/workflows/verify-attach.yml` publishes the evidence that `attach` hands to a session's runner, with `.github/scripts/verify-attach.mjs`. It reads the manifest that `src/core/remote/handoff.ts` writes. It and `src/core/publish.ts` each replace the block the other wrote, and each applies the same rules to the comments and to the start of the line. So a change to the manifest, the comments, or those rules is a change in both places. `node --test .github/scripts/verify-attach.test.mjs` runs its tests.
 - `npm test --prefix e2e-tests` runs the CLI's unit tests with no network, keys, or emulator, and `npm run typecheck --prefix e2e-tests` runs `tsc`. The `e2e-runner-tests` job of `.github/workflows/android-test.yml` runs both on a pull request that changes the package.
 - `.github/workflows/verify-e2e.yml` runs `up`, `run --all --retries 1 --github-report`, and `down` on an emulator on a CI runner. The release workflow (`.github/workflows/manual-release.yml`) calls it before it creates the release, and publishes to Maven Central only when it passed. Nothing runs it for a pull request. `gh workflow run verify-e2e.yml --ref <branch>` starts it by hand on any branch. A test that fails and then passes is reported as flaky and does not fail the job. It needs the repository secret `MOBILE_VERIFICATION_PLATFORM_API_KEY` and fails without it. The repository variable `VERIFY_CI_RUNNER` names a runner label other than `ubuntu-24.04`.
diff --git a/.claude/skills/verify-clerk-android/features/README.md b/.claude/skills/verify-clerk-android/features/README.md
index 349fbb094..6be050acf 100644
--- a/.claude/skills/verify-clerk-android/features/README.md
+++ b/.claude/skills/verify-clerk-android/features/README.md
@@ -29,7 +29,7 @@ Clerk's test mode makes all of this safe to type into the real app.
 
 The names come from `source/ui/src/main/java/com/clerk/ui/ClerkTestTags.kt`. They are internal test hooks and may change.
 
-On the standard instance an email sign-in starts on the email-link screen ("Check your email"), so a spec switches to the email code through `Use another method`. For a phone sign-in, tap `clerk.auth.start.identifierSwitcher`, fill `clerk.auth.start.phoneNumber` with the ten digits of the seeded user's phone, and continue. A user with a password sees the password screen first and reaches the SMS code through `Use another method`. For sign-up, launch with `authMode: 'signUp'`, fill the email from `host.newEmail()` into `clerk.auth.start.identifier`, continue, fill the run password into `clerk.auth.signUp.password`, continue, then type the code into `clerk.auth.signUp.code`.
+On the standard instance an email sign-in for a user with no password goes straight to the email code screen ("Check your email"). The email link is off there. For a phone sign-in, tap `clerk.auth.start.identifierSwitcher`, fill `clerk.auth.start.phoneNumber` with the ten digits of the seeded user's phone, and continue. A user with a password sees the password screen first and reaches the SMS code through `Use another method`. For sign-up, launch with `authMode: 'signUp'`, fill the email from `host.newEmail()` into `clerk.auth.start.identifier`, continue, fill the run password into `clerk.auth.signUp.password`, continue, then type the code into `clerk.auth.signUp.code`.
 
 ## Feature entry contract
 
@@ -46,4 +46,4 @@ Each feature file starts with an H1 title and one paragraph describing the user-
 - [Session tasks](./session-tasks.md) covers the setup-MFA and choose-organization tasks after sign-in, the setup-MFA task after sign-up, and finishing the setup-MFA task with an authenticator code.
 - [Organizations](./organizations.md) covers creating an organization from OrganizationSwitcher.
 
-Not mapped: a password sign-in past the password screen, completing the setup-MFA task with an SMS code, social providers (no real OAuth on emulators), passkeys, and biometrics.
+Not mapped: a password sign-in past the password screen, the email link (off on the standard instance), completing the setup-MFA task with an SMS code, social providers (no real OAuth on emulators), passkeys, and biometrics.
diff --git a/.claude/skills/verify-clerk-android/features/sign-in-email-code.md b/.claude/skills/verify-clerk-android/features/sign-in-email-code.md
index 6a4ac2c62..92adabcee 100644
--- a/.claude/skills/verify-clerk-android/features/sign-in-email-code.md
+++ b/.claude/skills/verify-clerk-android/features/sign-in-email-code.md
@@ -1,14 +1,14 @@
 # Sign in with an email code
 
-An existing user enters their email, asks for a one-time code instead of the email link, and signs in with the code.
+An existing user enters their email, gets a one-time code, and signs in with the code.
 
 ## Sub-features
 
-- `complete` reaches the email code screen for an existing test user through `Use another method`, stays on it, types `424242`, and lands signed in.
+- `complete` reaches the email code screen for an existing test user straight from Continue, stays on it, types `424242`, and lands signed in.
 
 ## How to get to it (user POV)
 
-- Open sign-in, type the email, tap Continue. On the standard instance the email-link screen ("Check your email") opens first. Tap `Use another method`, then `Email code to <email>`.
+- Open sign-in, type the email, tap Continue. On the standard instance a user with no password lands on the email code screen ("Check your email"). Type the code.
 
 ## Driving it with verify
 
@@ -16,11 +16,11 @@ Preconditions:
 
 - The spec seeds a `+clerk_test` user on the standard instance and launches with `authMode: 'signIn'`, then taps `e2e.auth.signInFullScreen`.
 
-- **Request code.** Run `e2e-tests/bin/control-clerk-android run sign-in-email-code/complete`. It fills `clerk.auth.start.identifier`, taps `clerk.auth.start.continue`, waits for `clerk.auth.signIn.useAnotherMethod`, taps it and `clerk.auth.signIn.alternativeMethod.email_code`, expects `clerk.auth.signIn.code`, and expects it still on screen 3 seconds later, with the email on the code screen. Screenshot `code-screen`.
+- **Request code.** Run `e2e-tests/bin/control-clerk-android run sign-in-email-code/complete`. It fills `clerk.auth.start.identifier`, taps `clerk.auth.start.continue`, expects `clerk.auth.signIn.code`, and expects it still on screen 3 seconds later, with the email on the code screen. Screenshot `code-screen`.
 - **Complete.** After the code screen it fills `CLERK_TEST_CODE` and waits for the home to show `Signed in as` the seeded user's email with that user's ID. Screenshot `signed-in`.
 - **Proof.** The spec passes, and screenshot `signed-in` shows the home with the seeded user's email and ID.
 
 ## Gotchas
 
-- The spec checks the code field a second time after 3 seconds. A sign-in that shows the code screen for a moment and then returns to the email-link screen would pass a single visibility check.
-- The email-link screen and the email code screen both have the title "Check your email". The code field, `clerk.auth.signIn.code`, tells them apart.
+- The spec checks the code field a second time after 3 seconds. A sign-in that shows the code screen for a moment and then leaves it would pass a single visibility check.
+- The standard instance has the email link off, because a test address gets no mail, so a run has no link to follow. With the link on, AuthView opens the email-link screen first. It has the same title as the code screen, "Check your email", and no code field, so `clerk.auth.signIn.code` tells them apart. A spec that needs the link declares `auth_email.sign_in_strategies` in a settings file.
diff --git a/.claude/skills/verify-clerk-android/references/cli.md b/.claude/skills/verify-clerk-android/references/cli.md
index fd612ee41..d7bf8b060 100644
--- a/.claude/skills/verify-clerk-android/references/cli.md
+++ b/.claude/skills/verify-clerk-android/references/cli.md
@@ -3,9 +3,9 @@
 ## Verbs and flags
 
 ```console
-e2e-tests/bin/control-clerk-android doctor [--backend auto|local] [--live]
-e2e-tests/bin/control-clerk-android up [--backend auto|local] [--wait <seconds>]
-e2e-tests/bin/control-clerk-android run <feature | feature/spec | path.e2e.ts>... | --all [--backend auto|local] [--grep <regex>] [--retries <n>] [--github-report] [--no-video] [--wait <seconds>]
+e2e-tests/bin/control-clerk-android doctor [--backend auto|local|remote] [--runner <label>] [--live]
+e2e-tests/bin/control-clerk-android up [--backend auto|local|remote] [--runner <label>] [--wait <seconds>]
+e2e-tests/bin/control-clerk-android run <feature | feature/spec | path.e2e.ts>... | --all [--backend auto|local|remote] [--runner <label>] [--grep <regex>] [--retries <n>] [--github-report] [--no-video] [--wait <seconds>]
 e2e-tests/bin/control-clerk-android screen [--png]
 e2e-tests/bin/control-clerk-android attach <run-id> --pr <n> [--screenshot <label>]...
 e2e-tests/bin/control-clerk-android down [--stale] [--dry-run]
@@ -15,7 +15,7 @@ Every verb takes `--json` and then prints one `{ "ok": ... }` object. Exit codes
 
 `--github-report` is for a CI job. After the run, `run` hands the results of every settings group to `@e2e-dev/github` as one report. The reporter writes that report to the job summary. When the event of the job names a pull request and the step has a `GITHUB_TOKEN` that may write pull request comments, it also posts one comment and updates that same comment on later runs. `run` prints one `github` line that says what the reporter did, the reporter never changes the exit code, and nothing is reported for a run whose files hold a secret. Without the flag, `run` reports nothing to GitHub.
 
-`--backend auto` is the default and leaves the choice to the CLI.
+`--backend auto` is the default and leaves the choice to the CLI. `--runner` names the runner label of a remote session. With the local backend it is a usage error, and `doctor` takes it only with `--live`.
 
 ## `--wait`
 
@@ -23,6 +23,7 @@ Every verb takes `--json` and then prints one `{ "ok": ... }` object. Exit codes
 - It does not bound the wait for an `up` already running in this worktree. `run` waits for that `up` with no limit and prints that it is waiting.
 - Waiters get no turn order. When a lane frees, any waiting worktree can take it.
 - When the budget runs out, the verb exits 3 with `POOL_FULL` or `DEVICE_BUSY`.
+- A remote session has no lane pool, so there `--wait` only bounds the wait for another verb in this worktree.
 
 While it waits, the CLI prints a `wait` line naming each lane and the worktree that holds it, prints it again when that changes, and prints `still waiting after <n>s` every minute otherwise.
 
diff --git a/.claude/skills/verify-clerk-android/references/instances.md b/.claude/skills/verify-clerk-android/references/instances.md
index b589caf37..c945dc9ff 100644
--- a/.claude/skills/verify-clerk-android/references/instances.md
+++ b/.claude/skills/verify-clerk-android/references/instances.md
@@ -4,7 +4,7 @@
 
 ## The standard settings
 
-`src/core/instances/base.json` defines the standard instance, with everything that can coexist switched on: email code, email link, phone code, password, username, TOTP, backup codes, organizations, and social buttons. It has two parts.
+`src/core/instances/base.json` defines the standard instance, with everything that can coexist switched on except the email link: email code, phone code, password, username, TOTP, backup codes, organizations, and social buttons. The email link is off so that an email sign-in opens on the code screen. It has two parts.
 
 - `config` is the whole body of the Platform API request that puts an instance on the standard settings.
 - `environment` lists the 62 leaves of the instance's public `/v1/environment` that a spec cannot run without. One of them, `user_settings.actions.delete_self`, has no `config` key. A new application lets a user delete their own account, and the check fails if Clerk changes that.
diff --git a/.claude/skills/verify-clerk-android/references/remote.md b/.claude/skills/verify-clerk-android/references/remote.md
new file mode 100644
index 000000000..0d0c8e1ee
--- /dev/null
+++ b/.claude/skills/verify-clerk-android/references/remote.md
@@ -0,0 +1,116 @@
+# The emulator on a CI runner
+
+When this machine cannot run the emulator, the CLI borrows one on a GitHub Actions runner and drives it through a tunnel. Every verb, spec, and evidence file is the same. `SKILL.md` has the loop: commit, push, `up`, `run`, `down`.
+
+## How the CLI chooses
+
+`up`, `run`, and `doctor` print the choice and the reason on a `backend` line. This machine runs the emulator itself when all of these hold:
+
+- It runs macOS or Linux.
+- On Linux, `/dev/kvm` exists and this user can open it for reading and writing. A machine with no `/dev/kvm` is told so first and offered no fix, because nothing installed on it would help.
+- It has an Android SDK with `emulator/emulator` and `platform-tools/adb`. The CLI looks in `ANDROID_HOME`, then `ANDROID_SDK_ROOT`, then `~/Library/Android/sdk` on macOS or `~/Android/Sdk` on Linux, then any SDK whose `platform-tools` or `emulator` directory is on `PATH`.
+- That SDK has the system image `system-images;android-36;google_apis;arm64-v8a` on an ARM machine or `system-images;android-36;google_apis;x86_64` on an Intel or AMD one. When a `Clerk_Verify_Pixel` AVD already exists, the image that AVD names counts instead.
+
+The check reads files and runs no tool. When something is missing, the `backend` line names it and, where a command fixes it, prints the command after `to run it here:`. A missing lane AVD or a missing Java 21 does not send you to a runner, because each has a quick fix on this machine. On Linux there is no bundled JBR, so set `JAVA_HOME` to a Java 21 JDK.
+
+`--backend local` or `--backend remote` forces one, and fails with `UNSUPPORTED` and a fix when this machine cannot use it. A worktree that holds a lease keeps that lease's backend until `down`.
+
+## What a session needs from this machine
+
+- Node 24, at 24.8.0 or newer. On any other Node the CLI reruns itself under `node@24` through `npx` and says so.
+- A pushed branch that holds `.github/workflows/verify-remote.yml`.
+- A GitHub token that may dispatch that workflow. The CLI takes the token from `GH_TOKEN`, then `GITHUB_TOKEN`, then `gh auth token`.
+- Network access to `*.trycloudflare.com`, `api.clerk.com`, and `*.clerk.accounts.dev`.
+- The Platform API credential, as for a local lane.
+
+It needs no Android SDK, no JDK, and no `adb`.
+
+A cloud environment can install `gh` once, in its setup script, so that a session does not have to. `attach` needs a `gh` whose `gh pr edit` has `--attach`, which is 2.99.0 or newer:
+
+```bash
+#!/bin/bash
+if ! gh pr edit --help 2>/dev/null | grep -q -- --attach; then
+  V=$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/cli/cli/releases/latest | sed -n 's|.*/tag/v||p')
+  case "$V" in [0-9]*.[0-9]*.[0-9]*) ;; *) V=2.102.0 ;; esac
+  curl -fsSL "https://github.com/cli/cli/releases/download/v${V}/gh_${V}_linux_amd64.tar.gz" | tar -xz -C /tmp \
+    && install -m 0755 "/tmp/gh_${V}_linux_amd64/bin/gh" /usr/local/bin/gh \
+    || echo "setup: gh ${V} install failed"
+fi
+gh --version || true
+```
+
+Without it, `doctor` reports `gh-attach` with its fix, and `attach` hands the evidence to the session's runner, as described below.
+
+REST starts, reads, and ends sessions. `git push` gets a commit you make to GitHub so the session can build it. Without push access you can still verify any commit GitHub already has.
+
+Node ignores `HTTPS_PROXY` unless told to honor it, so the CLI decides: it goes through the proxy when the direct path to GitHub does not work, and reruns itself with the proxy in effect for itself, e2e, and agent-device. `doctor`'s `remote-env` line says which path it took and why.
+
+## Builds
+
+A session builds a pushed commit, never your working tree. The runner builds the `:e2e` APK while it downloads the system image and boots the emulator, and the cold Gradle build is the long part. Run `up` as soon as you have pushed, then write the spec while it builds. While a runner is not ready, `up` prints `wait run <id> has waited <n>s, now for <what>`, which names the label it is waiting on.
+
+`up` starts the session's run on your branch as GitHub has it. The run builds only the commit it was started on, or a later commit of that branch. When HEAD is not on that branch on GitHub, or is behind it, the run fails at the step `Read the request` and no session starts. Push or pull, then run `up` again. A detached HEAD has no branch, so `doctor` and `up` fail until you switch to a branch that GitHub has.
+
+After an edit to the app, commit and push, then `run` again. `run` sees that the app sources changed, asks the same session to build the new commit, and runs once it is installed. The session builds it only when GitHub shows it as a later commit of the branch the session was started on. After a rebase or an amend, the pushed commit is not a later commit of that branch, and the build fails with `BUILD_FAILED`. Run `down`, then `up`. That build is incremental. Uncommitted changes to the app sources, or a HEAD that GitHub does not have, fail with `BUILD_FAILED` and the fix `git commit` or `git push`. A commit that only touches specs or docs needs no push, because specs run from this machine.
+
+A session keeps the package's code of the commit it started on. The build steps in `src/platform/android/session-device.ts` are read again from each commit it builds. The session agent in `src/core/` and the workflow steps are not: after a push that changes a file that `src/core/MANIFEST` lists, `up` and `run` fail with `NOT_READY` and the fix `down`, then `up`.
+
+## Cost and lifetime
+
+A session holds a CI runner until it stops, and on a Blacksmith label it is billed by the minute. It stops itself after 15 minutes without a call from the CLI, and always after 60 minutes. The CLI ends a session that is not ready 40 minutes after it asked for the build, and `up` then fails with `NOT_READY`. `down` stops it at once. After an idle stop, the next `up` or `run` prints `lost ... renewing` and starts a new session. A session with under two minutes left before its cap is replaced the same way. Set `VERIFY_REMOTE_IDLE_MINUTES` or `VERIFY_REMOTE_CAP_MINUTES` before `up` to change either.
+
+Each checkout has a random id, and its sessions carry it. When the checkout holds no lease, `up` and `run` end any session with that id that is still running, and `down --stale` does so at any time. The idle stop ends whatever they miss, such as the session of a checkout that was deleted.
+
+## Evidence from a machine that cannot attach
+
+`attach` always tries `gh pr edit --attach` itself first, on every kind of machine, and hands off only when that cannot work. The hand-off sends the evidence of a remote run to the session's runner. It sends the video and the screenshots from the sealed run directory, with a manifest that names the run, the pull request, the device, the commit, and each file's size and SHA-256. The files travel over the session's tunnel, with the session's token, in pieces of 1 MiB. The session job keeps them in one directory and uploads that directory as the artifact `verify-evidence` when the job ends. The artifact holds nothing else of the session.
+
+`.github/workflows/verify-attach.yml` then runs, from the default branch. It downloads the artifact, checks every file against the manifest and against its own limits, and puts the block in the description with `gh pr edit --attach`. It never runs anything from the branch or from the artifact. The workflow did not run the tests, so the line it writes says that the session reported the result, links the session's run in the Actions tab, and names the account that started that run, as GitHub records it.
+
+The repository needs this set up once:
+
+1. `verify-remote.yml`, `verify-attach.yml`, and `.github/scripts/verify-attach.mjs` are on the default branch. GitHub starts `verify-attach.yml` only from there, so until then a hand-off succeeds and nothing is published.
+2. A machine account has write access to the repository.
+3. That account has a fine-grained personal access token that is limited to this repository and has the permission "Pull requests: read and write".
+4. The repository has an environment named `verify-evidence`, and its deployment branches are limited to the default branch.
+5. The token is the secret `VERIFY_EVIDENCE_TOKEN` of that environment. The repository has no repository secret of that name.
+
+Do not store the token as a repository secret. Anyone who can push a branch can add a workflow to it, and a workflow on any branch can read a repository secret. A secret of an environment that allows only the default branch reaches only jobs that run on the default branch, and the job of `verify-attach.yml` is one.
+
+Without the environment or its secret, the workflow prints a notice and publishes nothing.
+
+The workflow publishes only when all of these hold. Otherwise it prints the reason in its run and publishes nothing.
+
+- The pull request that `--pr` names is open, and its branch is in this repository, not in a fork.
+- Its branch is the branch the session was started on.
+- The commit the run was made at is one of the pull request's commits.
+- The commit that branch had when `up` started the session is one of them too. GitHub lists the first 250 commits of a pull request, and the workflow reads no further. When a longer pull request has either commit past the first 250, the workflow says so and publishes nothing. Squash or rebase the branch to 250 commits or fewer, or attach from a machine whose `gh` can attach.
+- The hand-off has at least one file.
+- The description has the two evidence comments of the platform once each, or neither.
+- A description without the comments does not end inside a code fence that is never closed.
+
+`attach` checks the same rules before it sends anything, and fails with the reason.
+
+A push after the run does not lose the evidence. The line in the block names the commit the run was made at, and when the pull request has moved on it ends with "The pull request has newer commits." To show the newer commit, `run` again and `attach` again in the same session, which replaces the block. The session builds the new commit, and no new session is needed. After a rewrite of the branch's history that removes either commit, `down` and `up` before the next `run`.
+
+A hand-off holds one video of up to 100 MiB and screenshots of up to 10 MiB each, with at most 50 files and 150 MiB in all. A session keeps one hand-off, and a later `attach` in the same session replaces it. `down` gives a session that holds evidence up to five minutes to upload it before it cancels the run.
+
+The runs of `verify-attach` for one branch take turns, and each one publishes.
+
+The workflow reads the description again just before it writes. An edit that someone saves after that read, and before `gh` has uploaded the files and written the description, is overwritten. That is a few seconds for screenshots and up to a few minutes for a large video. `attach` on a machine whose `gh` can attach has the same window.
+
+If the description has no evidence a few minutes after `down`, read the newest run of `verify-attach` in the Actions tab of the repository. It says what it refused and why.
+
+## Runner labels
+
+The default label is `ubuntu-24.04`, a GitHub-hosted runner that costs nothing for a public repository. It names the Ubuntu version, so a new `ubuntu-latest` image cannot change the machine under the emulator. The session's 60 minutes start when the runner starts, so about 50 are left after `up`.
+
+`--runner blacksmith-4vcpu-ubuntu-2404` uses a Blacksmith runner instead, which is billed by the minute. `verify-remote.yml` starts a session only on `ubuntu-24.04`, `ubuntu-latest`, or `blacksmith-4vcpu-ubuntu-2404`, and fails its first job for any other label. To add a label, add it to the `Check the runner label` step there; it needs Linux x64 with KVM, the Android SDK command-line tools, and `sudo`. A held session keeps its label, and `--runner` with another label fails until `down`.
+
+Before the session's runner starts, a job of a few seconds reads the request. That job runs on `ubuntu-latest`, a free GitHub-hosted label, whatever the session's label.
+
+The session boots `Clerk_Verify_Pixel` through the same code as a local lane, on the `x86_64` build of the same Android 36 image, so the panel, the locale, and the lane mark match. It is the only emulator on that machine.
+
+## Secrets
+
+The Platform API key and the instance's secret key never leave this machine, and in a cloud environment the Platform API key never enters it. The session's bearer token is made here, lives in `.verify/remote/<session>/token`, and is deleted by `down`. GitHub sees only the token's SHA-256. The runner sees sign-in tickets and publishable keys as launch arguments. It uploads one artifact, which holds only the files that `attach` handed off, and it uploads no log and no build. The tunnel ends TLS at Cloudflare, so Cloudflare can read what crosses it, and the tunnel's host name is public while the session lives. Every route on it needs the bearer.
diff --git a/.github/workflows/android-test.yml b/.github/workflows/android-test.yml
index 23ff4e978..b068dd1e5 100644
--- a/.github/workflows/android-test.yml
+++ b/.github/workflows/android-test.yml
@@ -17,6 +17,7 @@ jobs:
       WATCHED: >-
         e2e-tests
         .github/workflows/android-test.yml
+        .github/workflows/verify-remote.yml
     steps:
       - uses: actions/checkout@v7
         with:
diff --git a/.github/workflows/verify-remote.yml b/.github/workflows/verify-remote.yml
new file mode 100644
index 000000000..a4a93632e
--- /dev/null
+++ b/.github/workflows/verify-remote.yml
@@ -0,0 +1,194 @@
+name: verify-remote
+run-name: verify-remote ${{ inputs.owner }}/${{ inputs.session }}
+
+on:
+  workflow_dispatch:
+    inputs:
+      owner:
+        description: Random id of the driver's checkout, so it can find and end its own sessions
+        required: true
+      session:
+        description: Session id the driver chose
+        required: true
+      request:
+        description: The session request as one JSON string (src/core/remote/protocol.ts)
+        required: true
+
+permissions:
+  contents: read
+
+env:
+  PACKAGE: e2e-tests
+
+jobs:
+  plan:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      mode: ${{ steps.plan.outputs.mode }}
+      runner: ${{ steps.plan.outputs.runner }}
+      device: ${{ steps.plan.outputs.device }}
+      sha: ${{ steps.plan.outputs.sha }}
+      timeout: ${{ steps.plan.outputs.timeout }}
+      request: ${{ steps.plan.outputs.request }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          sparse-checkout: e2e-tests/src/core
+          persist-credentials: false
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+      - name: Read the request
+        id: plan
+        env:
+          VERIFY_REQUEST: ${{ inputs.request }}
+          GITHUB_TOKEN: ${{ github.token }}
+        run: node "$PACKAGE/src/core/remote/session-agent.ts" plan
+      - name: Check the runner label
+        if: steps.plan.outputs.mode == 'session'
+        env:
+          RUNNER_LABEL: ${{ steps.plan.outputs.runner }}
+        run: |
+          case "$RUNNER_LABEL" in
+            ubuntu-24.04 | ubuntu-latest | blacksmith-4vcpu-ubuntu-2404) ;;
+            *)
+              echo "::error title=verify-remote::no session started: the runner label $RUNNER_LABEL is not ubuntu-24.04, ubuntu-latest, or blacksmith-4vcpu-ubuntu-2404"
+              exit 1
+              ;;
+          esac
+
+  session:
+    needs: plan
+    if: needs.plan.outputs.mode == 'session'
+    runs-on: ${{ needs.plan.outputs.runner }}
+    timeout-minutes: ${{ fromJSON(needs.plan.outputs.timeout) }}
+    env:
+      VERIFY_SESSION_REQUEST: ${{ needs.plan.outputs.request }}
+      # agent-device reaps its daemon and its device lease after five idle minutes by default.
+      AGENT_DEVICE_DAEMON_IDLE_TIMEOUT_MS: "0"
+      AGENT_DEVICE_LEASE_TTL_MS: "21600000"
+      AGENT_DEVICE_LEASE_MAX_TTL_MS: "21600000"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ needs.plan.outputs.sha || github.sha }}
+          persist-credentials: false
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+      - uses: actions/setup-java@v6
+        if: needs.plan.outputs.device != ''
+        with:
+          java-version: "21"
+          distribution: zulu
+      - uses: gradle/actions/setup-gradle@v6
+        if: needs.plan.outputs.device != ''
+
+      - name: Make the work directory and name the device
+        id: device
+        env:
+          DEVICE: ${{ needs.plan.outputs.device }}
+        run: |
+          set -euo pipefail
+          mkdir -p "$RUNNER_TEMP/verify-remote"
+          echo "VERIFY_SESSION_WORK=$RUNNER_TEMP/verify-remote" >> "$GITHUB_ENV"
+          if [ "$RUNNER_OS" = Linux ] && [ -n "$DEVICE" ]; then
+            [ -x "$ANDROID_HOME/platform-tools/adb" ] || "$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" --install platform-tools < /dev/null > /dev/null
+            echo "$ANDROID_HOME/platform-tools" >> "$GITHUB_PATH"
+            echo "serial=$(node "$PACKAGE/src/platform/android/session-lane.ts" serial)" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Start the session agent and tunnel
+        id: tunnel
+        env:
+          VERIFY_SESSION_DEVICE_ID: ${{ steps.device.outputs.serial }}
+          VERIFY_SESSION_DEVICE_NAME: ${{ needs.plan.outputs.device }}
+          VERIFY_SESSION_DEVICE_MODULE: e2e-tests/src/platform/android/session-device.ts
+          GITHUB_TOKEN: ${{ github.token }}
+          CLOUDFLARED_VERSION: "2026.9.3"
+          CLOUDFLARED_SHA256: 77e26d8d900e0b8469f416239d14b5f296525fdf79fee6f511ef55609e3fbac2
+        run: |
+          set -euo pipefail
+          WORK="$VERIFY_SESSION_WORK"
+          [ "$(uname -s)-$(uname -m)" = Linux-x86_64 ] || { echo "::error::a session needs a Linux x64 runner, and this one is $(uname -s)-$(uname -m)"; exit 1; }
+          curl -fsSL --retry 3 --retry-delay 2 --retry-all-errors -o "$WORK/cloudflared" "https://github.com/cloudflare/cloudflared/releases/download/$CLOUDFLARED_VERSION/cloudflared-linux-amd64"
+          echo "$CLOUDFLARED_SHA256  $WORK/cloudflared" | shasum -a 256 -c -
+          chmod +x "$WORK/cloudflared"
+          VERIFY_SESSION_CLOUDFLARED="$WORK/cloudflared" \
+            nohup node "$PACKAGE/src/core/remote/session-agent.ts" serve > "$WORK/agent.log" 2>&1 &
+          disown
+          for _ in $(seq 1 150); do
+            [ -s "$WORK/tunnel" ] && break
+            pgrep -f 'session-agent.ts serve' > /dev/null || { echo "::error::the session agent ended before a tunnel came up"; break; }
+            sleep 1
+          done
+          [ -s "$WORK/tunnel" ] || { echo "::error::no tunnel came up"; tail -n 20 "$WORK/agent.log" "$WORK/tunnel.log" || true; exit 1; }
+          echo "host=$(cat "$WORK/tunnel")" >> "$GITHUB_OUTPUT"
+
+      - name: verify-remote tunnel ${{ steps.tunnel.outputs.host }}
+        run: "true"
+
+      - name: Start the emulator
+        if: steps.device.outputs.serial != ''
+        run: |
+          set -euo pipefail
+          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules > /dev/null
+          sudo udevadm control --reload-rules
+          sudo udevadm trigger --name-match=kvm
+          IMAGE="system-images;android-36;google_apis;x86_64"
+          "$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" --install "$IMAGE" emulator < /dev/null > "$VERIFY_SESSION_WORK/sdkmanager.log" 2>&1 \
+            || { echo "::error::sdkmanager could not install $IMAGE"; tail -20 "$VERIFY_SESSION_WORK/sdkmanager.log"; exit 1; }
+          nohup node "$PACKAGE/src/platform/android/session-lane.ts" boot "$VERIFY_SESSION_WORK" > "$VERIFY_SESSION_WORK/lane.log" 2>&1 &
+          disown
+
+      - name: Install the package's pinned tools
+        timeout-minutes: 10
+        run: |
+          set -euo pipefail
+          npm ci --prefix "$PACKAGE" --no-audit --no-fund
+          "$PACKAGE/node_modules/.bin/agent-device" --version
+
+      - name: Wait for the emulator
+        if: steps.device.outputs.serial != ''
+        timeout-minutes: 6
+        run: |
+          until [ -f "$VERIFY_SESSION_WORK/lane-ready" ]; do
+            if [ -f "$VERIFY_SESSION_WORK/lane-failed" ]; then
+              echo "::error::the emulator did not boot: $(cat "$VERIFY_SESSION_WORK/lane-failed")"
+              tail -20 "$HOME/.verify/emulators/android-1.log" || true
+              exit 1
+            fi
+            sleep 2
+          done
+          cat "$VERIFY_SESSION_WORK/lane.log"
+
+      - name: Mark the device ready
+        run: touch "$VERIFY_SESSION_WORK/device-ready"
+
+      - name: Hold the session
+        run: |
+          set -uo pipefail
+          while [ ! -f "$VERIFY_SESSION_WORK/ended" ]; do
+            pgrep -f 'session-agent.ts serve' > /dev/null || [ -f "$VERIFY_SESSION_WORK/ended" ] || { echo "::error::the session agent died"; tail -30 "$VERIFY_SESSION_WORK/agent.log"; exit 1; }
+            sleep 3
+          done
+          echo "session ended: $(cat "$VERIFY_SESSION_WORK/ended")"
+
+      - name: Shut down
+        if: always()
+        env:
+          SERIAL: ${{ steps.device.outputs.serial }}
+        run: |
+          pkill -f 'session-agent.ts serve' || true
+          if [ -n "$SERIAL" ]; then adb -s "$SERIAL" emu kill || true; fi
+
+      - name: Keep the evidence that attach handed off
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: verify-evidence
+          path: ${{ runner.temp }}/verify-remote/evidence/
+          if-no-files-found: ignore
+          retention-days: 3
+          compression-level: 0
diff --git a/AGENTS.md b/AGENTS.md
index 0713b0479..5ad92006b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -17,10 +17,10 @@ Don't leave commented-out code.
 
 ## Verifying changes
 
-Prove every change to `source/api`, `source/ui`, or the `:e2e` host on an emulator before calling it done, and put the screenshots or video on the pull request. How you prove it is up to you. The verification skill in this repository is one way. An app of your own that exercises the change is just as good. If you could not run it on a device at all, say so in the pull request.
+Prove every change to `source/api`, `source/ui`, or the `:e2e` host on an emulator before calling it done, and put the screenshots or video on the pull request. How you prove it is up to you. The verification skill in this repository is one way, and it also works on a machine with no device. An app of your own that exercises the change is just as good. If you could not run it on a device at all, say so in the pull request.
 
-The skill is `.claude/skills/verify-clerk-android/`. The tests and the CLI that runs them are in `e2e-tests/`. Read the skill's `SKILL.md`, then `.claude/skills/verify-clerk-android/features/README.md` for the feature you touched. The skill needs a Clerk Platform API key, which Clerk team members have.
+The skill is `.claude/skills/verify-clerk-android/`. The tests and the CLI that runs them are in `e2e-tests/`. Read the skill's `SKILL.md`, then the page for the feature you touched, which `.claude/skills/verify-clerk-android/features/README.md` lists. This works on any machine: where the machine can run the Android emulator it runs there, and anywhere else the same commands borrow one on a CI runner. The skill needs a Clerk Platform API key, which Clerk team members have.
 
-The loop is `doctor`, `up`, `run`, `down`, and `attach`, each a verb of `e2e-tests/bin/control-clerk-android`.
+The loop is `doctor`, `up`, `run`, `screen`, `attach`, and `down`, each a verb of `e2e-tests/bin/control-clerk-android`.
 
 Use only test users: `+clerk_test` emails, phones 555-0100 to 555-0199, and the code `424242`. Never type real credentials.
diff --git a/e2e-tests/specs/golden/sign-in-email-code/complete.e2e.ts b/e2e-tests/specs/golden/sign-in-email-code/complete.e2e.ts
index adc6a2bf4..689ad07aa 100644
--- a/e2e-tests/specs/golden/sign-in-email-code/complete.e2e.ts
+++ b/e2e-tests/specs/golden/sign-in-email-code/complete.e2e.ts
@@ -6,10 +6,6 @@ test('signs in with the email code', async ({ host, screen }) => {
   await host.tap(host.app.signInFullScreen);
   await host.fill(screen.getByTestId('clerk.auth.start.identifier'), user.email);
   await host.tap(screen.getByTestId('clerk.auth.start.continue'));
-  const anotherMethod = screen.getByTestId('clerk.auth.signIn.useAnotherMethod');
-  await expect(anotherMethod).toBeVisible({ timeout: 20_000 });
-  await host.tap(anotherMethod);
-  await host.tap(screen.getByTestId('clerk.auth.signIn.alternativeMethod.email_code'));
   const code = screen.getByTestId('clerk.auth.signIn.code');
   await expect(code).toBeVisible({ timeout: 20_000 });
   await new Promise((resolve) => setTimeout(resolve, 3000));
diff --git a/e2e-tests/specs/support/config.ts b/e2e-tests/specs/support/config.ts
index 7a9f18375..3a4f452a6 100644
--- a/e2e-tests/specs/support/config.ts
+++ b/e2e-tests/specs/support/config.ts
@@ -1,10 +1,12 @@
+import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { E2EConfig } from 'e2e';
-import { mobile } from '@e2e-dev/mobile';
+import { mobile, type DeviceProvider } from '@e2e-dev/mobile';
 import { readAgent } from './agent.ts';
-import type { Target, TestApp } from './inputs.ts';
+import type { Device, Target, TestApp } from './inputs.ts';
+import { Secret } from './secret.ts';
 
 export const ASSERTION_TIMEOUT_MS = 10_000;
 export const TEST_TIMEOUT_MS = 240_000;
@@ -13,6 +15,21 @@ export const PACKAGE_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '
 
 type Env = Readonly<Record<string, string | undefined>>;
 
+export function engineDevice(device: Device): readonly string[] | DeviceProvider {
+  if (device.kind === 'local') return [device.id];
+  const token = new Secret('session-bearer', readFileSync(device.tokenFile, 'utf8').trim());
+  return {
+    name: 'borrowed',
+    acquire: async () => ({
+      id: device.id,
+      deviceId: device.id,
+      device: device.id,
+      daemon: token.use('e2e-provider-lease', (authToken) => ({ baseUrl: device.daemonUrl, authToken })),
+    }),
+    release: async () => {},
+  };
+}
+
 const requireOnlyForAnAgent = createRequire(import.meta.url);
 
 function agentConfig(env: Env): Pick<E2EConfig, 'agents' | 'cache'> {
@@ -29,7 +46,7 @@ export function composeE2EConfig(app: TestApp, target: Target, env: Env): E2ECon
     targets: [
       {
         name: target.platform,
-        engine: mobile({ platform: target.platform, device: [target.device.id], session: target.session, videoTouches: false }),
+        engine: mobile({ platform: target.platform, device: engineDevice(target.device), session: target.session, videoTouches: false }),
         app: { bundleId: app.id(target.platform), appPath: target.build.path ?? undefined },
       },
     ],
diff --git a/e2e-tests/specs/support/device.ts b/e2e-tests/specs/support/device.ts
index 320a15410..96b26ba2e 100644
--- a/e2e-tests/specs/support/device.ts
+++ b/e2e-tests/specs/support/device.ts
@@ -1,8 +1,9 @@
 import { execFile } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import type { Device } from './inputs.ts';
+import { Secret } from './secret.ts';
 import type { Platform } from './types.ts';
 
 export interface CommandLine {
@@ -19,7 +20,13 @@ export interface CommandResult {
 export type CommandRunner = (command: string, args: readonly string[]) => Promise<CommandResult>;
 
 export function agentDevice(device: Device, platform: Platform): { readonly selector: readonly string[]; readonly env: Readonly<Record<string, string>> } {
-  return { selector: ['--platform', platform, platform === 'ios' ? '--udid' : '--serial', device.id], env: {} };
+  const selector = ['--platform', platform, platform === 'ios' ? '--udid' : '--serial', device.id];
+  if (device.kind === 'local') return { selector, env: {} };
+  const token = new Secret('session-bearer', readFileSync(device.tokenFile, 'utf8').trim());
+  return {
+    selector: [...selector, '--daemon-base-url', device.daemonUrl],
+    env: token.use('agent-device-daemon', (plain) => ({ AGENT_DEVICE_DAEMON_AUTH_TOKEN: plain })),
+  };
 }
 
 const REVERSE_FLAGS: ReadonlySet<string> = new Set(['--list', '--no-rebind', '--remove', '--remove-all']);
diff --git a/e2e-tests/specs/support/inputs.ts b/e2e-tests/specs/support/inputs.ts
index 4762cde78..2da4da7bc 100644
--- a/e2e-tests/specs/support/inputs.ts
+++ b/e2e-tests/specs/support/inputs.ts
@@ -4,10 +4,9 @@ import type { AppEntry, Platform, PublishableKey, RunId } from './types.ts';
 
 type Env = Readonly<Record<string, string | undefined>>;
 
-export interface Device {
-  readonly kind: 'local';
-  readonly id: string;
-}
+export type Device =
+  | { readonly kind: 'local'; readonly id: string }
+  | { readonly kind: 'borrowed'; readonly id: string; readonly daemonUrl: string; readonly tokenFile: string };
 
 export interface AppBuild {
   readonly path: string | null;
@@ -46,6 +45,8 @@ const NAMES = {
   platform: 'CLERK_E2E_PLATFORM',
   device: 'CLERK_E2E_DEVICE',
   session: 'CLERK_E2E_DEVICE_SESSION',
+  daemonUrl: 'CLERK_E2E_DEVICE_DAEMON_URL',
+  daemonTokenFile: 'CLERK_E2E_DEVICE_DAEMON_TOKEN_FILE',
   appPath: 'CLERK_E2E_APP_PATH',
   devServer: 'CLERK_E2E_DEV_SERVER',
   publishableKey: 'CLERK_PUBLISHABLE_KEY',
@@ -84,7 +85,12 @@ function readDevice(platform: Platform, env: Env): Device {
   const { id: shape, expects, listedBy } = DEVICES[platform];
   if (id === null) throw new Error(`${NAMES.device} is not set; set it to the id of a booted device, which \`${listedBy}\` prints`);
   if (!shape.test(id)) throw new Error(`${NAMES.device} is ${id}, which is not ${expects}, so copy the id that \`${listedBy}\` prints`);
-  return { kind: 'local', id };
+  const daemonUrl = given(env, NAMES.daemonUrl);
+  if (daemonUrl === null) return { kind: 'local', id };
+  if (!/^https?:\/\/\S+$/.test(daemonUrl)) throw new Error(`${NAMES.daemonUrl} is ${daemonUrl}, which is not the http or https address of an agent-device daemon`);
+  const tokenFile = given(env, NAMES.daemonTokenFile);
+  if (tokenFile === null) throw new Error(`${NAMES.daemonUrl} is set and ${NAMES.daemonTokenFile} is not; the daemon of a borrowed device needs its token file`);
+  return { kind: 'borrowed', id, daemonUrl, tokenFile };
 }
 
 export function readTarget(app: TestApp, env: Env): Target {
@@ -147,6 +153,7 @@ export function inputsEnv(inputs: Inputs): Readonly<Record<string, string>> {
   return {
     [NAMES.platform]: target.platform,
     [NAMES.device]: target.device.id,
+    ...(target.device.kind === 'borrowed' ? { [NAMES.daemonUrl]: target.device.daemonUrl, [NAMES.daemonTokenFile]: target.device.tokenFile } : {}),
     [NAMES.session]: target.session,
     ...(target.build.path === null ? {} : { [NAMES.appPath]: target.build.path }),
     ...(target.build.devServer === null ? {} : { [NAMES.devServer]: target.build.devServer }),
diff --git a/e2e-tests/specs/support/types.ts b/e2e-tests/specs/support/types.ts
index af4fe4392..e04896523 100644
--- a/e2e-tests/specs/support/types.ts
+++ b/e2e-tests/specs/support/types.ts
@@ -36,7 +36,7 @@ export interface SecretLike {
   use<T>(sink: SecretSink, fn: (plain: string) => T): T;
 }
 
-export type SecretSink = 'bapi-authorization' | 'launch-argument' | 'platform-authorization' | 'one-password-read' | 'bapi-user-password' | 'device-input' | 'gateway-provider' | 'e2e-agent-environment' | 'test-process-environment';
+export type SecretSink = 'bapi-authorization' | 'launch-argument' | 'agent-device-daemon' | 'e2e-provider-lease' | 'github-authorization' | 'session-bearer' | 'platform-authorization' | 'one-password-read' | 'bapi-user-password' | 'device-input' | 'gateway-provider' | 'e2e-agent-environment' | 'test-process-environment';
 
 export interface HostLaunch {
   readonly verifyPublishableKey: PublishableKey;
diff --git a/e2e-tests/src/core/MANIFEST b/e2e-tests/src/core/MANIFEST
index 13ba3456a..fb7a3a7a6 100644
--- a/e2e-tests/src/core/MANIFEST
+++ b/e2e-tests/src/core/MANIFEST
@@ -3,40 +3,50 @@ f1ac21eeca82c1f04cbb42f0b77d51c798c71842a5a0b97a4660c3265ab601b6  specs/fixtures
 38e8e99663059810b616b591dfd79bdcc7781f72b7269875294f3702b3edde84  specs/support/agent.ts
 6d1ef7700a89e19d0b1214d5a6815ba757d02857c555b8bf108f2e0c9a64aad3  specs/support/busy-runner.ts
 b272dcd59155f0beff1eb1bc5ce7e3e2283d9e0e16e0639ef7eb6d8edbde9b3f  specs/support/clerk.ts
-bf7db40cc9dc4a514c3b057a34e8500e5d95130da3cbe6d0607162d3b68a28c2  specs/support/config.ts
-3d77b71e24d5c3293213392dd4d9b050b9de63a26f07d362610c22bf84b8c495  specs/support/device.ts
+6c658e254cb6ad8ba9f3d05638941e0809e6709f0abb8096340559b2f81b156a  specs/support/config.ts
+be45e0eb42f715d603c179c7a86750949ff2ee3cc0da73082179801fe1b8f2ab  specs/support/device.ts
 cec7a42bf8d35e174fd3387cbcc638c01bacda74fc15ea1b14eda8abaa200d34  specs/support/fill.ts
-03721b0676578a55448949a5af422beaf5bda727a2568bc5f3e0fad212c40a2c  specs/support/inputs.ts
+7415ccd89f715d40ca74796a5b235aab02e640c8674d457d3912955ab67146e1  specs/support/inputs.ts
 1772127f0a42d10003f16e5a59197180f4731837e0a00d2d1717f0b0f1bdfe8b  specs/support/launch.ts
 2065bc90a33659fd8f5a6e54e8b0fa57a50edc415063d4ac7e0dab744972e1b7  specs/support/secret.ts
 7446b59792b957f2ace72e6c2eceb305bde25378d1f879e2884706c3d7f9f3a4  specs/support/tapping.ts
-55260df9db466d21ba3a74e9ea16844f7bcda536b1e0d580b7d1ac17da257a05  specs/support/types.ts
+df955a42a2bd4ca1780f56837ebb9c832c68e97f74a35764d42a32e44b28286b  specs/support/types.ts
 7bdb018b337d923e96ada265abfebafd75c6fd07188ab313117effdc893e32d7  specs/support/typing.ts
 10bcf31d87a05655fc263ed810a0e10c0b63a77265720d7f22f3720052f67c38  specs/support/waiting.ts
 792ec6414c7e95446346abe2db850f6e4cc865a7c83a21892166fae969654277  src/core/agent.ts
 1b144b8f7362be2019f578bbdf94b7e6fe3196440de5c79d4f790fa8394374e3  src/core/broker.ts
 7c741449c755524bba80f1ce314554293003a34f7f7c30696015ba1c0c3dc1ab  src/core/claims.ts
 1fc59d13e7197e6c7099c0467744b978d498d1fe409c88254d44e2f99913a7b5  src/core/clerk.ts
-15dbedb7314bf057a92cabd7900ba7533bb8ec16f6e2ede792e8ecd2b922bfa1  src/core/cli.ts
-c658cd8472299371aee318f152d7a183f10e576dc0fba26904c3352f10cf5c36  src/core/devices.ts
+51f330273bb083139ff2f5f7ee3a7b616ba614c83cd050c188d5f224631050d6  src/core/cli.ts
+4aeacea985f5ef80001e5695feec53182abb9695eb07130898568743755fc8af  src/core/devices.ts
 3ae461d6aa75a2cefac0392a9ad124aec4105ac25b9320371743e2ea90fe2202  src/core/driver.ts
 b59071aaefeec02dea89bd25615f8ada0da0a51e805a2523011b8b591e7435d3  src/core/e2e.ts
 8c0ae6c44155105ce15011176bc630c59d6b4a2d2aa050f3fad4aa9674386ad8  src/core/evidence.ts
 27bfd4ce59937aa8c97d9fd6849cf52f3da05626fbc9388385f4b5e684577d36  src/core/exec.ts
 e2075f17f52ded8dea64d8a2473820396ca5ac1a22db59f21a092da28e55911f  src/core/github-report.ts
-699d3a0f0b92831da4fccfa5160aa0541e5d95029281dbef264eda2a49003850  src/core/instances/base.json
+721453f519bba1374dcf11aaae58f7af06e5555be756df6d3beaf52a9c2a2eda  src/core/instances/base.json
 cf6aa68be73e4abaf3b63d5d84c2e9eee6197412f607ec53d0f05f7b058db420  src/core/instances/instances.ts
 3f880f72c3356d67be9ab147c3d52d3dc90a388ba16dec009543a6c8cd93a9e2  src/core/instances/platform.ts
 26c8c052d7a87ff5401cd3dfc61ae7b1acde0966a3675e92567b9afde0ea96c6  src/core/instances/settings.ts
 7272293ca6be682c1a049ac7ee9fd54255721231b7da0fe11af5bbeb50e7e712  src/core/instances/throwaway.ts
 39a849e9c07ce23e8a1be9f50a136690deba3cd22b153d66cc3f9f2f53d88576  src/core/keys.ts
-72e7a64c6974afdc4612084d2e838075a9ce0edb6c676b23c266b8026400badc  src/core/launch.d.mts
-1287fc7e3328699e104c7bc50d3cd9bf9fbfec9efe764592c98e90e56033273d  src/core/launch.mjs
+16dd19df532749577769bfc0bf08e89872bda040a93fba584ee32fa44f9dfdbb  src/core/launch.d.mts
+098d3eef9d2521054f235f47e8658efb71d482087b927645489fc2240a03f5e8  src/core/launch.mjs
 a0ee9e4bfd34d4659685108e5e54eb1ec2aff6248236c358e6d3b14b2e2ff6a0  src/core/ledgers.ts
-8d533755b21beb1e1d74d160e2740c0b1c4c4b4bc0c33f8fac75083ffeb03e75  src/core/manifest.ts
-1f38ad65e58f7b4b62bb2c84bd4a5a16f5481cfb6c5f9b4b2ba059677d900bf3  src/core/publish.ts
+afab94a970286c40d6857b03ae4fa39ec59786274beacf6f1e77f6530bf46c54  src/core/manifest.ts
+c8f71088aa30904b8c69196f6df9bae968a5de16d2007d7e5e569feef3ff8246  src/core/publish.ts
+0f016cc412897b66038f56ce4c15b5b633bf8ca2c29eda05dbe28bf17fb29fd2  src/core/remote/backend.ts
+37fc42707be7d8bd5f0313a664a8465287ebb0970c520c0e0617f6ff6c9a614e  src/core/remote/github.ts
+2ed83b089a07969efe4369e027b8840f4c4b7b8fe055058fb22f44cf289618d6  src/core/remote/handoff.ts
+2ec436b2c53b34269e0b62ab54e41e4d9a55146cccc46f0f31591db05cdbf5c1  src/core/remote/preflight.ts
+bb69fe1f3581942285894c0901d02889c08b4293e4d9db77934fe3cdd2d4a399  src/core/remote/protocol.ts
+5a4ee0e7ed20feaeb711b1527083299b432d3fc0b7f428b636678a8a2f57581f  src/core/remote/recipe.ts
+bbb997d036c320257783f9c576497e4f02cde99a9cc8d164c4dfde40f76e4421  src/core/remote/session-agent.ts
+12df6d34398f8d1dce753839be00a0dc50f2c6de00638e4e4a43f8570912b403  src/core/remote/session.ts
+d614ee5c98a85d15037b744a67404496273f62985fd7d6a049cacfd5ab335503  src/core/remote/settings.ts
+e734336ea3b345057b69193790e2efce9a662c67ec5b4a426c811f999b45ccdb  src/core/remote/tunnel.ts
 685eabf010c7f63d076cfd3da1a681b5cc8024720538c1bf3a99792b563d8b60  src/core/slot.ts
 a8838aaf1fa9e4a6bc4e350ea674079201da76c5962656039b96db2505591aed  src/core/state.ts
-ce8fad4756866cc6940d1fcc653640cabcc47861c34185d98211e67b9a4a5847  src/core/types.ts
-5b137ac609685c490ac00b1d1ebce0ca0bb540316bfc14bb6c7a6e5b49cfa32e  src/core/verbs.ts
-56d2be8ec46aa0e0cf89747933e03f41fa7f3e6bed7e2a56b9d0b6e5e4db03e3  src/core/workspace.ts
+5d9bd1c8120b1ae77a1c42c40248f3b73cb1fce4c61e8c78ae21778a8ec3b39d  src/core/types.ts
+e0be9be1adfbfeec510d86a97e75d4b18b032712b6653daf2674458051ae6254  src/core/verbs.ts
+9be1816773216373548ec9933978b53ace3d3bfdba17b72c1e5ed6d8aef80f62  src/core/workspace.ts
diff --git a/e2e-tests/src/core/cli.ts b/e2e-tests/src/core/cli.ts
index 6c7fa99fe..372289cb6 100644
--- a/e2e-tests/src/core/cli.ts
+++ b/e2e-tests/src/core/cli.ts
@@ -6,6 +6,7 @@ import { takeAgent } from './agent.ts';
 import { PLATFORM_CREDENTIAL_VARIABLES } from './launch.mjs';
 import { redact } from '../../specs/support/secret.ts';
 import { leaseLine } from './devices.ts';
+import { RUNNER_LABEL } from './remote/protocol.ts';
 import { count } from './state.ts';
 import { createInstances } from './instances/instances.ts';
 import { verbs, type Deps } from './verbs.ts';
@@ -28,9 +29,9 @@ import {
 const VERBS: readonly Verb[] = ['doctor', 'up', 'run', 'screen', 'attach', 'down'];
 
 const USAGE_FIX = [
-  '{cli} doctor [--platform p] [--backend auto|local] [--live]',
-  '{cli} up [--platform p] [--backend auto|local] [--wait <seconds>]',
-  '{cli} run <feature|feature/spec|path.e2e.ts>... | --all [--platform p] [--backend auto|local] [--grep re] [--retries <n>] [--github-report] [--no-video] [--wait <seconds>]',
+  '{cli} doctor [--platform p] [--backend auto|local|remote] [--live [--runner <label>]]',
+  '{cli} up [--platform p] [--backend auto|local|remote] [--runner <label>] [--wait <seconds>]',
+  '{cli} run <feature|feature/spec|path.e2e.ts>... | --all [--platform p] [--backend auto|local|remote] [--runner <label>] [--grep re] [--retries <n>] [--github-report] [--no-video] [--wait <seconds>]',
   '{cli} screen [--platform p] [--png]',
   '{cli} attach <run-id> --pr <n> [--screenshot label]...',
   '{cli} down [--platform p] [--stale] [--dry-run]',
@@ -42,9 +43,9 @@ const usage = (message: string) => new VerifyFailure('USAGE', message, USAGE_FIX
 type FlagSpec = Readonly<Record<string, 'value' | 'bool' | 'list'>>;
 
 const FLAGS: Readonly<Record<Verb, FlagSpec>> = {
-  doctor: { platform: 'value', backend: 'value', live: 'bool' },
-  up: { platform: 'value', backend: 'value', wait: 'value' },
-  run: { platform: 'value', backend: 'value', all: 'bool', grep: 'value', retries: 'value', 'github-report': 'bool', 'no-video': 'bool', wait: 'value' },
+  doctor: { platform: 'value', backend: 'value', runner: 'value', live: 'bool' },
+  up: { platform: 'value', backend: 'value', runner: 'value', wait: 'value' },
+  run: { platform: 'value', backend: 'value', runner: 'value', all: 'bool', grep: 'value', retries: 'value', 'github-report': 'bool', 'no-video': 'bool', wait: 'value' },
   screen: { platform: 'value', png: 'bool' },
   attach: { pr: 'value', screenshot: 'list' },
   down: { platform: 'value', stale: 'bool', 'dry-run': 'bool' },
@@ -58,8 +59,13 @@ function platformFlag(value: string | undefined): Platform | undefined {
 
 function backendFlag(value: string | undefined): BackendKind | undefined {
   if (value === undefined || value === 'auto') return undefined;
-  if (value === 'local') return value;
-  throw usage(`--backend must be auto or local, not ${value}`);
+  if (value === 'local' || value === 'remote') return value;
+  throw usage(`--backend must be auto, local, or remote, not ${value}`);
+}
+
+function runnerFlag(value: string | undefined): string | undefined {
+  if (value !== undefined && !RUNNER_LABEL.test(value)) throw usage(`--runner must be a runner label such as ubuntu-latest, not ${value}`);
+  return value;
 }
 
 function positiveInt(flag: string, value: string | undefined, fallback: number | undefined): number {
@@ -112,12 +118,14 @@ export function parseArgv(argv: readonly string[]): Invocation {
   };
   const platform = platformFlag(values.get('platform'));
   const backend = backendFlag(values.get('backend'));
-  const base = { ...(platform === undefined ? {} : { platform }), ...(backend === undefined ? {} : { backend }) };
+  const runner = runnerFlag(values.get('runner'));
+  const base = { ...(platform === undefined ? {} : { platform }), ...(backend === undefined ? {} : { backend }), ...(runner === undefined ? {} : { runner }) };
 
   let command: Command;
   switch (verb) {
     case 'doctor':
       noPositionals();
+      if (runner !== undefined && !bools.has('live')) throw usage('--runner names the runner of the session that doctor --live starts; add --live or drop --runner');
       command = { verb, ...base, live: bools.has('live') };
       break;
     case 'up':
@@ -228,7 +236,11 @@ function render(value: VerbResult, packageDir: string): string[] {
       return lines;
     }
     case 'attach':
-      return [`${value.alreadyPosted ? 'already posted' : 'posted'}  ${value.posted.map((p) => basename(p)).join(', ')}  ${value.commentUrl}`];
+      if (value.via === 'gh') return [`${value.alreadyPosted ? 'already posted' : 'posted'}  ${value.posted.map((p) => basename(p)).join(', ')}  in the description of ${value.prUrl}`];
+      return [
+        `handed off  ${value.handedOff.map((p) => basename(p)).join(', ')}  to the session's runner (${value.sessionRunUrl}), because ${value.because}`,
+        `next        {cli} down ends the session; the verify-attach workflow then puts the evidence in the description of PR #${value.pr}`,
+      ];
     case 'down':
       return [
         ...(value.dryRun
diff --git a/e2e-tests/src/core/devices.ts b/e2e-tests/src/core/devices.ts
index effb62ff4..dca5dbc8b 100644
--- a/e2e-tests/src/core/devices.ts
+++ b/e2e-tests/src/core/devices.ts
@@ -32,7 +32,8 @@ export interface LeaseOutcome {
   readonly build: BuildView;
 }
 
-export const deviceOf = (lease: Lease): Device => ({ kind: 'local', id: lease.deviceId });
+export const deviceOf = (lease: Lease): Device =>
+  lease.backend === 'local' ? { kind: 'local', id: lease.deviceId } : { kind: 'borrowed', id: lease.deviceId, daemonUrl: `${lease.baseUrl}/agent-device`, tokenFile: lease.tokenFile };
 
 export function backendFor(host: HostAdapter, platform: Platform, kind: BackendKind): DeviceBackend {
   const backend = host.backends.find((b) => b.platform === platform && b.kind === kind);
@@ -77,7 +78,7 @@ export function leaseView(backend: DeviceBackend, lease: Lease, renewed: boolean
     backend: lease.backend,
     device: backend.describe(lease),
     installedBuild: lease.installedBuild,
-    expiresAt: null,
+    expiresAt: lease.backend === 'remote' ? lease.expiresAt : null,
     renewed,
   };
 }
@@ -112,8 +113,20 @@ export function readBuiltApp(workspace: Workspace, key: BuildKey): LocalBuild |
   return existsSync(app.path) ? app : null;
 }
 
-async function ensureBuild(host: HostAdapter, platform: Platform, workspace: Workspace, backend: DeviceBackend, progress: (line: string) => void): Promise<{ app: BuiltApp; view: BuildView }> {
+async function ensureBuild(host: HostAdapter, platform: Platform, workspace: Workspace, backend: DeviceBackend, held: Lease | null, heldIsAlive: boolean, progress: (line: string) => void): Promise<{ app: BuiltApp; view: BuildView }> {
   const key = await computeBuildKey(host, platform, backend.kind, workspace.worktree);
+  if (backend.sourceCommit !== undefined) {
+    const builtForThisApp = held !== null && held.backend === 'remote' && held.installedBuild === key ? held.builtSha : null;
+    const onSession = heldIsAlive ? builtForThisApp : null;
+    const sourceSha =
+      onSession ??
+      (await backend.sourceCommit({ worktree: workspace.worktree, inputs: host.buildInputs(platform, backend.kind) }).catch((error: unknown) => {
+        if (builtForThisApp !== null && error instanceof VerifyFailure && error.code === 'BUILD_FAILED') return builtForThisApp;
+        throw error;
+      }));
+    const app: BuiltApp = { platform, key, appId: host.appId(platform), path: null, source: 'github-actions', sourceSha };
+    return { app, view: { platform, key, source: app.source, reused: onSession !== null, seconds: 0 } };
+  }
   const existing = readBuiltApp(workspace, key);
   if (existing !== null) return { app: existing, view: { platform, key, source: existing.source, reused: true, seconds: 0 } };
   const started = Date.now();
@@ -144,13 +157,16 @@ export async function ensureLease(
   requested: BackendKind | undefined,
   workspace: Workspace,
   host: HostAdapter,
-  options: { readonly waitSeconds: number; readonly progress: (line: string) => void; readonly instances: Instances; readonly retryWith: string },
+  options: { readonly waitSeconds: number; readonly runner?: string; readonly progress: (line: string) => void; readonly instances: Instances; readonly retryWith: string },
 ): Promise<LeaseOutcome> {
   const { platform } = lock;
   const held = workspace.readLease(platform);
   if (held !== null && requested !== undefined && held.backend !== requested) {
     throw new VerifyFailure('NOT_READY', `this worktree holds a ${held.backend} ${platform} lease, not ${requested}`, '{cli} down');
   }
+  if (held !== null && held.backend === 'remote' && options.runner !== undefined && held.runner !== options.runner) {
+    throw new VerifyFailure('NOT_READY', `this worktree holds a session on ${held.runner}, not ${options.runner}`, '{cli} down, then rerun with --runner');
+  }
   const choice = selectBackend(host, platform, requested, held);
   const { backend } = choice;
   options.progress(`backend ${describeChoice(choice)}`);
@@ -160,15 +176,15 @@ export async function ensureLease(
   }
   await finishOrphanLedgers(workspace.home, resolve(workspace.worktree), options.instances, options.progress);
 
-  const { app, view: build } = await ensureBuild(host, platform, workspace, backend, options.progress);
-  const builtBy = build.reused ? 'reused' : `built in ${build.seconds}s`;
+  const state = held === null ? 'held' : await backend.check(held);
+  const { app, view: build } = await ensureBuild(host, platform, workspace, backend, held, state === 'held', options.progress);
+  const builtBy = app.source === 'local' ? (build.reused ? 'reused' : `built in ${build.seconds}s`) : `commit ${app.sourceSha.slice(0, 12)}  ${build.reused ? 'already on the session' : 'the session builds it'}`;
   options.progress(`build   ${build.key}  ${build.source}  ${builtBy}`);
 
   let lease: Lease | null = held;
   let renewed = false;
-  const state = lease === null ? 'held' : await backend.check(lease);
   if (lease !== null && state !== 'held') {
-    options.progress(`${'lost'.padEnd(7)} ${backend.describe(lease)}  renewing`);
+    options.progress(`${(state === 'expiring' ? 'ending' : 'lost').padEnd(7)} ${backend.describe(lease)}  renewing`);
     await releaseLease(workspace, backend, lease);
     lease = null;
     renewed = true;
@@ -180,14 +196,14 @@ export async function ensureLease(
     }
     const intent = { id: newEntryId(), kind: 'lease-intent' as const, platform, backend: backend.kind, worktree: workspace.worktree };
     workspace.append(intent);
-    const acquired = await backend.acquire({ platform, worktree: workspace.worktree, waitSeconds: options.waitSeconds, app, retryWith: options.retryWith, progress: options.progress });
+    const acquired = await backend.acquire({ platform, worktree: workspace.worktree, waitSeconds: options.waitSeconds, app, ...(options.runner === undefined ? {} : { runner: options.runner }), retryWith: options.retryWith, progress: options.progress });
     workspace.writeLease(acquired);
     workspace.append({
       id: newEntryId(),
       kind: 'lease-held',
       platform,
       backend: backend.kind,
-      sessionId: null,
+      sessionId: acquired.backend === 'remote' ? acquired.session : null,
       deviceId: acquired.deviceId,
     });
     workspace.append({ id: newEntryId(), kind: 'done', ref: intent.id });
diff --git a/e2e-tests/src/core/instances/base.json b/e2e-tests/src/core/instances/base.json
index 0ee4e5c55..91b04239b 100644
--- a/e2e-tests/src/core/instances/base.json
+++ b/e2e-tests/src/core/instances/base.json
@@ -31,8 +31,7 @@
       "immutable": false,
       "required_for_sign_up": true,
       "sign_in_strategies": [
-        "email_code",
-        "email_link"
+        "email_code"
       ],
       "used_for_sign_in": true,
       "used_for_sign_up": true,
@@ -184,7 +183,6 @@
   "environment": {
     "auth_config.first_factors": [
       "email_code",
-      "email_link",
       "oauth_google",
       "password",
       "phone_code",
@@ -257,8 +255,7 @@
     ],
     "user_settings.attributes.backup_code.used_for_second_factor": true,
     "user_settings.attributes.email_address.first_factors": [
-      "email_code",
-      "email_link"
+      "email_code"
     ],
     "user_settings.attributes.first_name.enabled": true,
     "user_settings.attributes.last_name.enabled": true,
diff --git a/e2e-tests/src/core/launch.d.mts b/e2e-tests/src/core/launch.d.mts
index 2b51fed2c..5c9eefe82 100644
--- a/e2e-tests/src/core/launch.d.mts
+++ b/e2e-tests/src/core/launch.d.mts
@@ -3,3 +3,5 @@ export const AGENT_CREDENTIAL_VARIABLES: readonly string[];
 export const INSTANCE_SECRET_VARIABLES: readonly string[];
 export function supportsNode(version: string): boolean;
 export function ensureRuntime(): Promise<void>;
+export function proxyPort(proxy: URL): number;
+export function chooseEgress(observed: { readonly proxyListens: boolean; readonly directConnects: boolean; readonly tokenStatusDirect: number | null }): { readonly proxy: boolean; readonly why: string };
diff --git a/e2e-tests/src/core/launch.mjs b/e2e-tests/src/core/launch.mjs
index 448f47970..010b3a5b9 100644
--- a/e2e-tests/src/core/launch.mjs
+++ b/e2e-tests/src/core/launch.mjs
@@ -1,5 +1,6 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
+import net from 'node:net';
 import { delimiter, dirname } from 'node:path';
 
 export const PLATFORM_CREDENTIAL_VARIABLES = ['CLERK_PLATFORM_API_KEY', 'CLERK_PLATFORM_API_KEY_FILE', 'VERIFY_PLATFORM_KEY_REFERENCE'];
@@ -20,6 +21,19 @@ function rerun(command, args, env) {
   });
 }
 
+function accepts(host, port) {
+  return new Promise((resolve) => {
+    const socket = net.connect({ host, port, timeout: 1500 });
+    const done = (ok) => {
+      socket.destroy();
+      resolve(ok);
+    };
+    socket.on('connect', () => done(true));
+    socket.on('timeout', () => done(false));
+    socket.on('error', () => done(false));
+  });
+}
+
 export async function ensureRuntime() {
   if (!supportsNode(process.versions.node)) {
     const withoutKey = Object.fromEntries(Object.entries(process.env).filter(([name]) => !PLATFORM_CREDENTIAL_VARIABLES.includes(name) && !AGENT_CREDENTIAL_VARIABLES.includes(name) && !INSTANCE_SECRET_VARIABLES.includes(name)));
@@ -34,4 +48,35 @@ export async function ensureRuntime() {
     else console.error(`FAIL  node  ${message}\n      fix: ${fix}`);
     process.exit(3);
   }
+
+  const proxy = process.env.HTTPS_PROXY || process.env.https_proxy;
+  if (!proxy || process.env.NODE_USE_ENV_PROXY !== undefined) return;
+  let url;
+  try {
+    url = new URL(proxy);
+  } catch {
+    return;
+  }
+  const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
+  const choice = chooseEgress({
+    proxyListens: await accepts(url.hostname, proxyPort(url)),
+    directConnects: await accepts('api.github.com', 443),
+    tokenStatusDirect: token ? await fetch('https://api.github.com/rate_limit', { headers: { Authorization: `Bearer ${token}`, 'User-Agent': 'verify-remote' }, signal: AbortSignal.timeout(5000) }).then((response) => response.status, () => 0) : null,
+  });
+  process.env.VERIFY_EGRESS_WHY = choice.why;
+  if (!choice.proxy) return;
+  const local = 'localhost,127.0.0.1,::1';
+  const noProxy = process.env.NO_PROXY || process.env.no_proxy;
+  process.exit(await rerun(process.execPath, process.argv.slice(1), { ...process.env, NODE_USE_ENV_PROXY: '1', NO_PROXY: noProxy ? `${noProxy},${local}` : local }));
+}
+
+export function proxyPort(proxy) {
+  return Number(proxy.port || (proxy.protocol === 'https:' ? 443 : 80));
+}
+
+export function chooseEgress({ proxyListens, directConnects, tokenStatusDirect }) {
+  if (!proxyListens) return { proxy: false, why: 'HTTPS_PROXY is set but nothing accepts connections there' };
+  if (!directConnects || tokenStatusDirect === 0) return { proxy: true, why: 'a direct connection to api.github.com fails' };
+  if (tokenStatusDirect === 401) return { proxy: true, why: "GitHub rejects this machine's token on a direct connection, so the proxy is where the real credential is added" };
+  return { proxy: false, why: tokenStatusDirect === null ? 'a direct connection to api.github.com works' : 'a direct connection to api.github.com works and GitHub accepts the token on it' };
 }
diff --git a/e2e-tests/src/core/manifest.ts b/e2e-tests/src/core/manifest.ts
index 7ee6f652a..5f21f564b 100644
--- a/e2e-tests/src/core/manifest.ts
+++ b/e2e-tests/src/core/manifest.ts
@@ -37,6 +37,14 @@ export function manifestDrift(): readonly string[] {
   return [...names].filter((name) => committed.get(name) !== actual.get(name)).sort();
 }
 
+export function coreVersion(): string {
+  try {
+    return createHash('sha256').update(readFileSync(MANIFEST_FILE)).digest('hex').slice(0, 12);
+  } catch {
+    return 'unknown';
+  }
+}
+
 if (import.meta.main && process.argv.includes('--write')) {
   writeFileSync(MANIFEST_FILE, computeManifest());
 }
diff --git a/e2e-tests/src/core/publish.ts b/e2e-tests/src/core/publish.ts
index 407152303..adf77ff70 100644
--- a/e2e-tests/src/core/publish.ts
+++ b/e2e-tests/src/core/publish.ts
@@ -1,40 +1,141 @@
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join, relative, sep } from 'node:path';
 import { run as defaultRunner, type Runner } from './exec.ts';
 import type { Publishable } from './evidence.ts';
-import { VerifyFailure, type AttachResult, type EvidencePath, type HostAdapter } from './types.ts';
+import { VerifyFailure, type AttachResult, type EvidencePath, type EvidenceSummary, type HostAdapter, type Platform } from './types.ts';
 
 interface Posted {
   readonly pr: number;
-  readonly commentUrl: string;
+  readonly prUrl: string;
   readonly posted: readonly EvidencePath[];
 }
 
-function tally(results: Publishable['results']): string {
-  const flaky = results.filter((r) => r.status === 'flaky').length;
-  return `${results.filter((r) => r.status === 'passed').length} of ${results.length} passed${flaky === 0 ? '' : `, ${flaky} flaky (passed only on a retry)`}.`;
+export interface EvidenceMedia {
+  readonly alt: string;
+  readonly ref: string;
 }
 
-export function commentBody(evidence: Publishable): string {
-  const lines = [
-    `verify run \`${evidence.run}\` on ${evidence.platform} (${evidence.device}), build \`${evidence.build}\`, ${tally(evidence.results)}`,
-    '',
-    ...evidence.results.map((r) => `- ${r.status}: \`${r.spec.path}\` ${r.title}`),
-  ];
-  for (const group of evidence.settings) {
-    if (group.askedBy === null) continue;
-    const results = evidence.results.filter((r) => group.specs.includes(r.spec.path));
-    lines.push('', `Instance settings \`${group.label}\` (declared by \`${group.askedBy}\`): ${tally(results)}`);
+export function summarize(evidence: Publishable): EvidenceSummary {
+  return {
+    run: evidence.run,
+    platform: evidence.platform,
+    device: evidence.device.replace(/[^A-Za-z0-9 ._()-]/g, '-').replace(/^[^A-Za-z0-9]+/, '').slice(0, 64) || 'device',
+    commit: evidence.gitHead,
+    passed: evidence.results.filter((r) => r.status === 'passed').length,
+    flaky: evidence.results.filter((r) => r.status === 'flaky').length,
+    total: evidence.results.length,
+  };
+}
+
+export const evidenceMarkers = (platform: Platform): { readonly start: string; readonly end: string } => ({
+  start: `<!-- verify-evidence:${platform} -->`,
+  end: `<!-- /verify-evidence:${platform} -->`,
+});
+
+const BLOCK_LINE_START = 'verify run `';
+
+// GitHub plays a video only from a URL that is alone in its paragraph, and `gh pr edit --attach` rewrites a reference to that URL only there.
+export function evidenceBlock(summary: EvidenceSummary, media: readonly EvidenceMedia[]): string {
+  const { start, end } = evidenceMarkers(summary.platform);
+  const flaky = summary.flaky === 0 ? '' : `, ${summary.flaky} flaky (passed only on a retry)`;
+  const line = `${BLOCK_LINE_START}${summary.run}\` on \`${summary.device}\` at \`${summary.commit.slice(0, 12)}\`, ${summary.passed} of ${summary.total} passed${flaky}.`;
+  return [start, '', line, ...media.flatMap((m) => ['', `![${m.alt}](${m.ref})`]), '', end].join('\n');
+}
+
+export class CannotPostHere extends VerifyFailure {
+  readonly why: string;
+  constructor(why: string, message: string, fix: string) {
+    super('NOT_READY', message, fix);
+    this.why = why;
+  }
+}
+
+export type BlockEdit = { readonly ok: true; readonly body: string; readonly was: 'added' | 'replaced' } | { readonly ok: false; readonly why: string; readonly fix: string };
+
+const ONE_PAIR_OF_MARKERS = 'leave one pair of those markers in the description, or none';
+
+function fencedCode(text: string): { readonly fences: readonly (readonly [number, number])[]; readonly neverCloses: boolean } {
+  const fences: [number, number][] = [];
+  let open: { readonly char: string; readonly length: number; readonly at: number } | null = null;
+  let inHtmlComment = false;
+  for (let at = 0; at <= text.length; ) {
+    const newline = text.indexOf('\n', at);
+    const lineEnd = newline === -1 ? text.length : newline;
+    const line = text.slice(at, lineEnd).replace(/\r$/, '');
+    const fence = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+    if (open === null && (inHtmlComment || /^ {0,3}<!--/.test(line))) {
+      inHtmlComment = !line.includes('-->');
+    } else if (fence !== null) {
+      const ticks = fence[1]!;
+      const rest = fence[2]!;
+      if (open === null && !(ticks[0] === '`' && rest.includes('`'))) open = { char: ticks[0]!, length: ticks.length, at };
+      else if (open !== null && ticks[0] === open.char && ticks.length >= open.length && rest.trim() === '') {
+        fences.push([open.at, lineEnd]);
+        open = null;
+      }
+    }
+    if (newline === -1) break;
+    at = newline + 1;
+  }
+  if (open !== null) fences.push([open.at, text.length]);
+  return { fences, neverCloses: open !== null };
+}
+
+function linesThatAre(text: string, marker: string): number[] {
+  const { fences } = fencedCode(text);
+  const found: number[] = [];
+  for (let at = text.indexOf(marker); at !== -1; at = text.indexOf(marker, at + marker.length)) {
+    const end = at + marker.length;
+    const startsItsLine = at === 0 || text[at - 1] === '\n';
+    const endsItsLine = end === text.length || text[end] === '\n' || text.startsWith('\r\n', end);
+    if (startsItsLine && endsItsLine && !fences.some(([from, to]) => at > from && at < to)) found.push(at);
+  }
+  return found;
+}
+
+export function withEvidenceBlock(body: string, platform: Platform, lines: string): BlockEdit {
+  const { start, end } = evidenceMarkers(platform);
+  const starts = linesThatAre(body, start);
+  const ends = linesThatAre(body, end);
+  const newline = body.includes('\r\n') ? '\r\n' : '\n';
+  const block = lines.replaceAll('\n', newline);
+  if (starts.length === 0 && ends.length === 0) {
+    if (fencedCode(body).neverCloses) return { ok: false, why: 'ends inside a code fence that is never closed', fix: 'close that code fence' };
+    const gap = body === '' ? '' : body.endsWith('\n') ? newline : `${newline}${newline}`;
+    return { ok: true, body: `${body}${gap}${block}`, was: 'added' };
   }
-  return lines.join('\n');
+  if (starts.length !== 1 || ends.length !== 1) return { ok: false, why: `has \`${start}\` ${starts.length} times and \`${end}\` ${ends.length} times`, fix: ONE_PAIR_OF_MARKERS };
+  if (ends[0]! < starts[0]!) return { ok: false, why: `has \`${end}\` before \`${start}\``, fix: ONE_PAIR_OF_MARKERS };
+  if (!body.slice(starts[0]! + start.length, ends[0]!).trimStart().startsWith(BLOCK_LINE_START)) return { ok: false, why: `has text between \`${start}\` and \`${end}\` that is not an evidence block`, fix: ONE_PAIR_OF_MARKERS };
+  return { ok: true, body: `${body.slice(0, starts[0]!)}${block}${body.slice(ends[0]! + end.length)}`, was: 'replaced' };
 }
 
-const ATTACH_FIX = 'install a gh build whose `gh pr comment` has --attach';
+const ATTACH_FIX = 'install gh 2.99.0 or newer, whose `gh pr edit` has --attach';
 
 export async function missingAttach(runner: Runner): Promise<{ readonly why: string; readonly fix: string } | null> {
-  const help = await runner('gh', ['pr', 'comment', '--help']);
+  const help = await runner('gh', ['pr', 'edit', '--help']);
   if (help.code === 0 && help.stdout.includes('--attach')) return null;
-  return { why: help.code === 0 ? 'this gh has no `gh pr comment --attach`' : 'gh is not installed', fix: ATTACH_FIX };
+  return { why: help.code === 0 ? 'this gh has no `gh pr edit --attach`' : 'gh is not installed', fix: ATTACH_FIX };
+}
+
+export function chooseFiles(evidence: Publishable, screenshots: 'all' | readonly string[]): { readonly videos: readonly EvidencePath[]; readonly shots: Publishable['screenshots'] } {
+  if (screenshots === 'all') return { videos: evidence.videos, shots: evidence.screenshots };
+  const shots = screenshots.map((label) => {
+    const shot = evidence.screenshots.find((s) => s.label === label);
+    if (shot === undefined) {
+      throw new VerifyFailure('USAGE', `run ${evidence.run} has no screenshot labelled ${label}`, `use one of: ${evidence.screenshots.map((s) => s.label).join(', ') || '(none)'}`);
+    }
+    return shot;
+  });
+  return { videos: evidence.videos, shots };
+}
+
+async function readDescription(runner: Runner, repo: string, pr: number): Promise<{ readonly body: string; readonly url: string }> {
+  const viewed = await runner('gh', ['pr', 'view', String(pr), '--repo', repo, '--json', 'body,url']);
+  if (viewed.code !== 0) throw new CannotPostHere('gh pr view failed', `gh pr view failed: ${viewed.stderr.trim()}`, 'check `gh auth status` and that the PR exists');
+  const parsed = JSON.parse(viewed.stdout) as { readonly body?: string | null; readonly url?: string };
+  return { body: parsed.body ?? '', url: parsed.url ?? '' };
 }
 
 export async function postToPullRequest(
@@ -48,28 +149,47 @@ export async function postToPullRequest(
   const postedFile = join(dir, `posted-${pr}.json`);
   if (existsSync(postedFile)) {
     const previous = JSON.parse(readFileSync(postedFile, 'utf8')) as Posted;
-    return { verb: 'attach', commentUrl: previous.commentUrl, posted: previous.posted, alreadyPosted: true };
+    return { verb: 'attach', via: 'gh', prUrl: previous.prUrl, posted: previous.posted, alreadyPosted: true };
   }
-  const chosen =
-    screenshots === 'all'
-      ? evidence.screenshots
-      : screenshots.map((label) => {
-          const shot = evidence.screenshots.find((s) => s.label === label);
-          if (shot === undefined) {
-            throw new VerifyFailure('USAGE', `run ${evidence.run} has no screenshot labelled ${label}`, `use one of: ${evidence.screenshots.map((s) => s.label).join(', ') || '(none)'}`);
-          }
-          return shot;
-        });
-  const files = [...evidence.videos, ...chosen.map((s) => s.path)];
+  const { videos, shots } = chooseFiles(evidence, screenshots);
+  const files = [...videos, ...shots.map((s) => s.path)];
   const missing = files.length === 0 ? null : await missingAttach(runner);
-  if (missing !== null) throw new VerifyFailure('NOT_READY', `${missing.why}, so the video and screenshots of run ${evidence.run} cannot be posted`, missing.fix);
-  const args = ['pr', 'comment', String(pr), '--repo', host.githubRepo, '--body', commentBody(evidence), ...files.flatMap((f) => ['--attach', f])];
-  const result = await runner('gh', args);
-  if (result.code !== 0) {
-    throw new VerifyFailure('NOT_READY', `gh pr comment failed: ${result.stderr.trim()}`, 'check `gh auth status` and that the PR exists');
+  if (missing !== null) throw new CannotPostHere(missing.why, `${missing.why}, so the video and screenshots of run ${evidence.run} cannot be posted`, missing.fix);
+
+  const ref = (file: EvidencePath): string => `./${relative(dir, file).split(sep).join('/')}`;
+  const block = evidenceBlock(summarize(evidence), [
+    ...videos.map((video) => ({ alt: basename(video), ref: ref(video) })),
+    ...shots.map((shot) => ({ alt: shot.label, ref: ref(shot.path) })),
+  ]);
+
+  let current = await readDescription(runner, host.githubRepo, pr);
+  let next: string | null = null;
+  for (let attempt = 0; attempt < 2 && next === null; attempt += 1) {
+    const edit = withEvidenceBlock(current.body, evidence.platform, block);
+    if (!edit.ok) {
+      throw new VerifyFailure('NOT_READY', `the description of PR #${pr} ${edit.why}, so the evidence of run ${evidence.run} has no one place to go`, `${edit.fix}, then rerun`);
+    }
+    const again = await readDescription(runner, host.githubRepo, pr);
+    if (again.body === current.body) next = edit.body;
+    else current = again;
+  }
+  if (next === null) {
+    throw new VerifyFailure('NOT_READY', `the description of PR #${pr} changed twice while the evidence of run ${evidence.run} was being placed, so nothing was written`, 'rerun {cli} attach once nobody is editing the description');
+  }
+
+  const scratch = mkdtempSync(join(tmpdir(), 'verify-attach-'));
+  try {
+    const bodyFile = join(scratch, 'body.md');
+    writeFileSync(bodyFile, next);
+    const result = await runner('gh', ['pr', 'edit', String(pr), '--repo', host.githubRepo, '--body-file', bodyFile, ...files.flatMap((f) => ['--attach', ref(f)])], { cwd: dir });
+    if (result.code !== 0) {
+      throw new CannotPostHere('gh pr edit failed', `gh pr edit failed: ${result.stderr.trim()}`, 'check `gh auth status` and that you can edit the PR; a file that did upload is in the description already');
+    }
+    const prUrl = /https:\/\/github\.com\/\S+/.exec(result.stdout)?.[0] ?? current.url;
+    const posted: Posted = { pr, prUrl, posted: files };
+    writeFileSync(postedFile, `${JSON.stringify(posted, null, 2)}\n`);
+    return { verb: 'attach', via: 'gh', prUrl, posted: files, alreadyPosted: false };
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
   }
-  const commentUrl = /https:\/\/github\.com\/\S+/.exec(result.stdout)?.[0] ?? result.stdout.trim();
-  const posted: Posted = { pr, commentUrl, posted: files };
-  writeFileSync(postedFile, `${JSON.stringify(posted, null, 2)}\n`);
-  return { verb: 'attach', commentUrl, posted: files, alreadyPosted: false };
 }
diff --git a/e2e-tests/src/core/remote/backend.ts b/e2e-tests/src/core/remote/backend.ts
new file mode 100644
index 000000000..54316f040
--- /dev/null
+++ b/e2e-tests/src/core/remote/backend.ts
@@ -0,0 +1,277 @@
+import { createWriteStream, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import type { ReadableStream } from 'node:stream/web';
+import { run, sleep } from '../exec.ts';
+import { VerifyFailure, type AcquireRequest, type DeviceBackend, type EvidencePath, type Recording, type RemoteLease } from '../types.ts';
+import { apiMessage, currentBranch, endSession, liveRuns, openGitHub, startRun, viewRun, waitForStep, waitReporter, type GitHub } from './github.ts';
+import { HANDOFF_VERSION, HandoffRefused, describeFile, parseHandoffManifest, pullRequestMismatch, type HandoffManifest } from './handoff.ts';
+import { coreVersion } from '../manifest.ts';
+import { withEvidenceBlock } from '../publish.ts';
+import { remoteDoctorChecks } from './preflight.ts';
+import { BUILD_TIMEOUT_MINUTES, STEP, type SessionHealth } from './protocol.ts';
+import { firstHealth, sendEvidence, sessionCall, sessionHealth, tunnelUrl, type SessionRef } from './session.ts';
+import { forgetSession, newSessionRequest, saveToken, savedDriverId, type RemoteDeps, type RemoteSettings } from './settings.ts';
+
+const READY_DEADLINE_MS = (BUILD_TIMEOUT_MINUTES + 5) * 60_000;
+const EXPIRING_MS = 2 * 60_000;
+
+const COMMITS_PER_PAGE = 100;
+const COMMIT_PAGES = 3;
+
+async function pullRequestCommits(hub: GitHub, pr: number): Promise<readonly string[]> {
+  const shas: string[] = [];
+  for (let page = 1; page <= COMMIT_PAGES; page += 1) {
+    const listed = await hub.api('GET', `/pulls/${pr}/commits?per_page=${COMMITS_PER_PAGE}&page=${page}`);
+    if (listed.status !== 200 || !Array.isArray(listed.json)) throw new VerifyFailure('NOT_READY', `could not read the commits of PR #${pr}: ${apiMessage(listed)}`, 'retry {cli} attach');
+    shas.push(...(listed.json as readonly { readonly sha: string }[]).map((commit) => commit.sha));
+    if (listed.json.length < COMMITS_PER_PAGE) break;
+  }
+  return shas;
+}
+
+export function remoteBackend(settings: RemoteSettings, deps: RemoteDeps = { env: process.env, runner: run }): DeviceBackend<RemoteLease> {
+  const { platform } = settings;
+  let opened: Promise<GitHub> | undefined;
+  const github = () => (opened ??= deps.github?.() ?? openGitHub({ repo: settings.repo, workflow: settings.workflow, env: deps.env, runner: deps.runner }));
+  const runUrl = (runId: string) => `https://github.com/${settings.repo}/actions/runs/${runId}`;
+
+  function assertSameCore(health: SessionHealth): void {
+    const mine = coreVersion();
+    if (health.core === mine) return;
+    throw new VerifyFailure(
+      'NOT_READY',
+      `the session runs verify core ${health.core} and this checkout has ${mine}, so its agent may not have the routes this CLI calls`,
+      'commit and push the changes to the files MANIFEST lists, then {cli} down and {cli} up',
+    );
+  }
+
+  function describeBuild(health: SessionHealth): string {
+    const build = health.build;
+    if (build.state === 'none') return 'no build';
+    return `build ${build.sha.slice(0, 12)} ${build.state}${build.state === 'building' ? ` ${build.seconds}s` : ''}`;
+  }
+
+  async function waitForBuild(lease: RemoteLease, sha: string, progress: (line: string) => void): Promise<Extract<SessionHealth['build'], { state: 'built' }>> {
+    const deadline = Date.now() + READY_DEADLINE_MS;
+    let last = '';
+    for (;;) {
+      const health = await sessionHealth(lease);
+      if (health === null) {
+        const state = await viewRun(await github(), lease.providerRef);
+        if (state.status === 'completed') throw new VerifyFailure('LEASE_LOST', `the session ended (${state.conclusion ?? 'no conclusion'}) while it was building`, `read ${runUrl(lease.providerRef)} for why, then {cli} up`);
+      } else {
+        if (health.build.state === 'failed' && health.build.sha === sha) {
+          throw new VerifyFailure('BUILD_FAILED', `the session could not build ${sha.slice(0, 12)}:\n${health.build.tail}`, 'fix the build error above, commit, push, then rerun {cli} up');
+        }
+        if (health.build.state === 'timed-out' && health.build.sha === sha) {
+          throw new VerifyFailure(
+            'NOT_READY',
+            `the session stopped the build of ${sha.slice(0, 12)} after ${BUILD_TIMEOUT_MINUTES} minutes on ${lease.runner}, the longest it lets one build run. The build reported no error before that. Its last lines:\n${health.build.tail}`,
+            'rerun {cli} up, and the same session builds again from what the stopped build left; if that build is stopped too, {cli} down, then {cli} up --runner <a faster runner label>',
+          );
+        }
+        if (health.build.state === 'built' && health.build.sha === sha && health.device?.ready === true && health.daemon) return health.build;
+        const line = `wait    ${describeBuild(health)}; device ${health.device?.ready === true ? 'ready' : 'booting'}; agent-device ${health.daemon ? 'up' : 'starting'}`;
+        const coarse = line.replace(/ \d+s/, '');
+        if (coarse !== last) progress(line);
+        last = coarse;
+      }
+      if (Date.now() >= deadline) {
+        await endSession(await github(), lease.providerRef, lease).catch(() => undefined);
+        throw new VerifyFailure('NOT_READY', `the session was not ready ${READY_DEADLINE_MS / 60_000} minutes after the build was asked for (${health === null ? 'it does not answer' : describeBuild(health)}), so it was ended`, `read ${runUrl(lease.providerRef)}, then {cli} up`);
+      }
+      await sleep(8000);
+    }
+  }
+
+  const backend: DeviceBackend<RemoteLease> = {
+    kind: 'remote',
+    platform,
+    requirement: settings.requirement,
+    availability: () => ({ usable: true, why: `the device runs on a CI runner (${settings.runner} unless --runner names another), started through ${settings.workflow} on ${settings.repo}` }),
+
+    async sourceCommit(input) {
+      const status = await deps.runner('git', ['status', '--porcelain', '--', ...input.inputs], { cwd: input.worktree });
+      const files = status.stdout.split('\n').filter((line) => line.length > 3).map((line) => line.slice(3));
+      if (files.length > 0) {
+        throw new VerifyFailure(
+          'BUILD_FAILED',
+          `a remote session builds a pushed commit, and this tree has uncommitted changes to the app: ${files.slice(0, 5).join(', ')}${files.length > 5 ? `, and ${files.length - 5} more` : ''}`,
+          'git commit the changes and git push, then rerun',
+        );
+      }
+      const sha = (await deps.runner('git', ['rev-parse', 'HEAD'], { cwd: input.worktree })).stdout.trim();
+      const found = await (await github()).api('GET', `/commits/${sha}`);
+      if (found.status !== 200) {
+        throw new VerifyFailure('BUILD_FAILED', `a remote session builds a pushed commit, and GitHub does not have ${sha.slice(0, 12)} (${found.status})`, 'git push, then rerun');
+      }
+      return sha;
+    },
+
+    async acquire(request: AcquireRequest) {
+      const hub = await github();
+      const ref = await currentBranch(deps.runner, request.worktree);
+      const { request: order, token } = newSessionRequest(settings, deps, { ...(request.runner === undefined ? {} : { runner: request.runner }), device: settings.device, sha: request.app.source === 'local' ? null : request.app.sourceSha });
+      const tokenFile = saveToken(settings, order.session, token);
+      request.progress(`device  remote ${platform}  starting session ${order.session} on ${order.runner} (idle stop ${order.idleMinutes} min, cap ${order.capMinutes} min)`);
+      let runId: string | null = null;
+      let session: SessionRef | null = null;
+      try {
+        runId = await startRun(hub, order, { ref });
+        request.progress(`device  remote ${platform}  run ${runId}  ${runUrl(runId)}`);
+        const host = await waitForStep(hub, runId, STEP.tunnelPattern, 20 * 60, waitReporter(request.progress, runId, { plan: settings.plumbingRunner, session: order.runner }));
+        session = { baseUrl: tunnelUrl(host), tokenFile };
+        const health = await firstHealth(session, 180);
+        if (health === null || health.device === null) throw new VerifyFailure('NOT_READY', `the session's tunnel at ${host} did not answer with a device`, `read ${runUrl(runId)}`);
+        assertSameCore(health);
+        request.progress(`device  remote ${platform}  tunnel up, ${health.device.name} on ${order.runner}`);
+        return {
+          backend: 'remote',
+          provider: 'github-actions',
+          platform,
+          session: order.session,
+          providerRef: runId,
+          baseUrl: session.baseUrl,
+          tokenFile,
+          deviceId: health.device.id,
+          deviceName: health.device.name,
+          runner: order.runner,
+          expiresAt: health.capAt,
+          builtSha: null,
+          acquiredAt: new Date().toISOString(),
+          installedBuild: null,
+        };
+      } catch (error) {
+        const ended = runId === null ? null : await endSession(hub, runId, session).catch((failure: Error) => ({ problem: failure.message }));
+        forgetSession(settings, order.session);
+        if (runId === null || ended === null || ended.problem === null) throw error;
+        throw new VerifyFailure('NOT_READY', `${(error as Error).message}; and the run it started could not be ended: ${ended.problem}`, `open ${runUrl(runId)} and cancel it`);
+      }
+    },
+
+    async check(lease) {
+      if (!existsSync(lease.tokenFile)) return 'lost';
+      let health = await sessionHealth(lease);
+      for (let i = 0; i < 3 && health === null; i += 1) {
+        await sleep(3000);
+        health = await sessionHealth(lease);
+      }
+      if (health === null) {
+        const state = await viewRun(await github(), lease.providerRef);
+        if (state.status === 'completed') return 'lost';
+        throw new VerifyFailure('NOT_READY', `the session is still running (${runUrl(lease.providerRef)}) but its tunnel does not answer`, 'retry in a minute; if it stays unreachable, {cli} down, then {cli} up');
+      }
+      if (health.ending !== null) return 'lost';
+      assertSameCore(health);
+      return Date.parse(lease.expiresAt) - Date.now() < EXPIRING_MS ? 'expiring' : 'held';
+    },
+
+    async install(lease, app, progress) {
+      if (app.source === 'local') throw new VerifyFailure('BUILD_FAILED', 'a remote session builds a pushed commit and this build names none', '{cli} down, then {cli} up');
+      const sha = app.sourceSha;
+      const started = await sessionCall(lease, `/__sim/build?sha=${sha}`, { method: 'POST' });
+      if (started.status !== 202) throw new VerifyFailure('BUILD_FAILED', `the session refused to build ${sha.slice(0, 12)}: ${started.status} ${await started.text()}`, '{cli} down, then {cli} up');
+      const built = await waitForBuild(lease, sha, progress);
+      progress(`build   ${app.key}  github-actions  ${sha.slice(0, 12)} ${built.incremental ? 'rebuilt' : 'built'} in ${built.seconds}s on ${lease.runner}`);
+      return { ...lease, builtSha: sha };
+    },
+
+    async release(lease) {
+      const ended = await endSession(await github(), lease.providerRef, lease.baseUrl === '' ? null : lease);
+      if (ended.problem !== null) throw new VerifyFailure('NOT_READY', ended.problem, `open ${runUrl(lease.providerRef)} and cancel it, then {cli} down`);
+      forgetSession(settings, lease.session);
+    },
+
+    async reapable(owner) {
+      const mine = savedDriverId(settings);
+      if (owner === undefined || mine === null) return [];
+      const running = await github().then(liveRuns).catch(() => []);
+      return running
+        .filter((live) => live.owner === mine && live.session.startsWith(platform))
+        .map((live) => ({
+          backend: 'remote' as const,
+          provider: 'github-actions' as const,
+          platform,
+          session: live.session,
+          providerRef: live.runId,
+          baseUrl: '',
+          tokenFile: join(settings.sessionsDir, live.session, 'token'),
+          deviceId: '',
+          deviceName: settings.device,
+          runner: '',
+          expiresAt: live.createdAt,
+          builtSha: null,
+          acquiredAt: live.createdAt,
+          installedBuild: null,
+        }));
+    },
+
+    async startRecording(lease, into) {
+      const started = await sessionCall(lease, '/__sim/record/start', { method: 'POST' });
+      if (started.status !== 200) throw new VerifyFailure('NOT_READY', `the session did not start recording: ${started.status} ${await started.text()}`, 'rerun with --no-video');
+      const file = join(into, 'video.mp4') as EvidencePath;
+      const recording: Recording = {
+        process: null,
+        async stop() {
+          const stopped = await sessionCall(lease, '/__sim/record/stop', { method: 'POST', timeoutMs: 90_000 });
+          if (stopped.status !== 200) return file;
+          const download = await sessionCall(lease, '/__sim/record/file', { timeoutMs: 300_000 });
+          if (download.status === 200 && download.body !== null) await pipeline(Readable.fromWeb(download.body as ReadableStream), createWriteStream(file));
+          return file;
+        },
+      };
+      return recording;
+    },
+
+    async logs(lease, since, extraPredicate) {
+      const params = new URLSearchParams({ since: since.toISOString() });
+      if (extraPredicate !== undefined) params.set('predicate', extraPredicate);
+      const response = await sessionCall(lease, `/__sim/logs?${params}`, { timeoutMs: 120_000 });
+      return response.status === 200 ? response.text() : `the session returned no logs (${response.status})`;
+    },
+
+    async handOffEvidence(lease, bundle, progress) {
+      const { run } = bundle.summary;
+      const wouldNot = (why: string, fix: string): VerifyFailure => new VerifyFailure('NOT_READY', `the verify-attach workflow would not put the evidence of run ${run} on PR #${bundle.pr}: ${why}`, fix);
+      if (bundle.files.length === 0) throw wouldNot('the run has no video and no screenshot, and the workflow publishes nothing without a file', '{cli} run again without --no-video, then attach');
+      const health = await sessionHealth(lease);
+      if (health === null || health.ending !== null) {
+        throw new VerifyFailure('LEASE_LOST', `the session (${runUrl(lease.providerRef)}) ${health === null ? 'does not answer' : 'is ending'}, so it cannot take the evidence of run ${run}`, '{cli} up, run again, and attach before {cli} down');
+      }
+      const hub = await github();
+      const [session, pull] = await Promise.all([hub.api('GET', `/actions/runs/${lease.providerRef}`), hub.api('GET', `/pulls/${bundle.pr}`)]);
+      if (session.status !== 200) throw new VerifyFailure('NOT_READY', `could not read run ${lease.providerRef}: ${apiMessage(session)}`, `open ${runUrl(lease.providerRef)}`);
+      if (pull.status !== 200) throw new VerifyFailure('NOT_READY', `could not read PR #${bundle.pr} of ${settings.repo}: ${apiMessage(pull)}`, 'pass the number of an open pull request of this branch as --pr');
+      const started = session.json as { readonly head_branch: string; readonly head_sha: string };
+      const pr = pull.json as { readonly state: string; readonly body: string | null; readonly commits: number; readonly head: { readonly ref: string; readonly sha: string; readonly repo: { readonly full_name: string } | null } };
+      const mismatch = pullRequestMismatch(
+        { state: pr.state, headRepo: pr.head.repo?.full_name ?? null, headRef: pr.head.ref, commits: await pullRequestCommits(hub, bundle.pr), commitCount: pr.commits },
+        { repo: settings.repo, headBranch: started.head_branch, startedOn: started.head_sha, runCommit: bundle.summary.commit },
+      );
+      if (mismatch !== null) throw wouldNot(mismatch.why, mismatch.fix);
+      const place = withEvidenceBlock(pr.body ?? '', bundle.summary.platform, '');
+      if (!place.ok) throw wouldNot(`its description ${place.why}, so the evidence has no one place to go`, `${place.fix}, then rerun {cli} attach`);
+      let manifest: HandoffManifest;
+      try {
+        manifest = parseHandoffManifest(JSON.stringify({ v: HANDOFF_VERSION, pr: bundle.pr, ...bundle.summary, files: bundle.files.map((file) => describeFile(file.name, file.path)) }));
+      } catch (error) {
+        if (!(error instanceof HandoffRefused)) throw error;
+        throw new VerifyFailure('NOT_READY', `the evidence of run ${run} cannot be handed to the runner: ${error.message}`, 'attach fewer or smaller files with --screenshot, or rerun with --no-video');
+      }
+      try {
+        await sendEvidence(lease, manifest, new Map(bundle.files.map((file) => [file.name, file.path])), progress);
+      } catch (error) {
+        if (error instanceof VerifyFailure) throw error;
+        throw new VerifyFailure('NOT_READY', `the hand-off of run ${run} failed: ${(error as Error).message}`, 'run {cli} attach again while the session is up');
+      }
+      return { sessionRun: lease.providerRef, sessionRunUrl: runUrl(lease.providerRef) };
+    },
+
+    describe: (lease) => `${lease.deviceName} on ${lease.runner === '' ? `run ${lease.providerRef}` : lease.runner}`,
+
+    doctorChecks: (options) => remoteDoctorChecks(settings, deps, github, options),
+  };
+  return backend;
+}
diff --git a/e2e-tests/src/core/remote/github.ts b/e2e-tests/src/core/remote/github.ts
new file mode 100644
index 000000000..f37d46583
--- /dev/null
+++ b/e2e-tests/src/core/remote/github.ts
@@ -0,0 +1,280 @@
+import { existsSync } from 'node:fs';
+import type { Runner } from '../exec.ts';
+import { sleep } from '../exec.ts';
+import { Secret } from '../../../specs/support/secret.ts';
+import { VerifyFailure } from '../types.ts';
+import { RUN_TITLE, type SessionRequest } from './protocol.ts';
+import { sessionCall, type SessionRef } from './session.ts';
+
+export type TokenSource = 'GH_TOKEN' | 'GITHUB_TOKEN' | 'gh' | 'none';
+
+export interface ApiResponse {
+  readonly status: number;
+  readonly json: unknown;
+  readonly headers: Headers;
+  readonly firstRefusalWithToken?: string;
+}
+
+export interface GitHub {
+  readonly repo: string;
+  readonly workflow: string;
+  readonly tokenSource: TokenSource;
+  api(method: 'GET' | 'POST', path: string, body?: unknown): Promise<ApiResponse>;
+}
+
+export interface GitHubOptions {
+  readonly repo: string;
+  readonly workflow: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly runner: Runner;
+  readonly retryDelayMs?: number;
+}
+
+const TRANSIENT_RETRIES = 3;
+
+export async function openGitHub(options: GitHubOptions): Promise<GitHub> {
+  const { env } = options;
+  let tokenSource: TokenSource = 'none';
+  let token: Secret<'github-token'> | null = null;
+  const fromEnv = (['GH_TOKEN', 'GITHUB_TOKEN'] as const).find((name) => (env[name] ?? '') !== '');
+  if (fromEnv !== undefined) {
+    tokenSource = fromEnv;
+    token = new Secret('github-token', env[fromEnv]!);
+  } else {
+    const gh = await options.runner('gh', ['auth', 'token']);
+    if (gh.code === 0 && gh.stdout.trim() !== '') {
+      tokenSource = 'gh';
+      token = new Secret('github-token', gh.stdout.trim());
+    }
+  }
+  const base = (env.GITHUB_API_URL ?? 'https://api.github.com').replace(/\/$/, '');
+  return {
+    repo: options.repo,
+    workflow: options.workflow,
+    tokenSource,
+    async api(method, path, body) {
+      const send = async (authorized: boolean): Promise<ApiResponse> => {
+        const headers: Record<string, string> = { Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28', 'User-Agent': 'verify-remote' };
+        if (body !== undefined) headers['Content-Type'] = 'application/json';
+        if (authorized) token?.use('github-authorization', (plain) => (headers.Authorization = `Bearer ${plain}`));
+        const response = await fetch(`${base}/repos/${options.repo}${path}`, { method, headers, body: body === undefined ? undefined : JSON.stringify(body), redirect: 'manual', signal: AbortSignal.timeout(30_000) });
+        const text = await response.text();
+        let json: unknown = null;
+        try {
+          json = text === '' ? null : JSON.parse(text);
+        } catch {
+          json = null;
+        }
+        return { status: response.status, json, headers: response.headers };
+      };
+      let first = await send(true);
+      for (let attempt = 1; method === 'GET' && first.status >= 500 && attempt <= TRANSIENT_RETRIES; attempt += 1) {
+        await sleep(attempt * (options.retryDelayMs ?? 1500));
+        first = await send(true);
+      }
+      if (method !== 'GET' || token === null || (first.status !== 401 && first.status !== 403)) return first;
+      return { ...(await send(false)), firstRefusalWithToken: message(first) };
+    },
+  };
+}
+
+export const CLOUD_GITHUB_ACCESS =
+  'A 403 on git push means this machine\'s GitHub credential may not push to the repository. In a cloud sandbox that credential belongs to the sandbox\'s GitHub integration, and someone who administers the organization gives the integration access to the repository. REST calls there can use another credential, so they may work while a push is refused';
+
+export function gitFailure(output: string): string {
+  const lines = output.trim().split('\n').map((line) => line.trim()).filter((line) => line !== '');
+  const remote = lines.filter((line) => line.startsWith('remote:')).map((line) => line.replace(/^remote:\s*/, ''));
+  return [...remote, lines.at(-1) ?? 'no output'].filter((line, i, all) => all.indexOf(line) === i).join(' | ');
+}
+
+const message = (response: ApiResponse): string => `${response.status}${typeof (response.json as { message?: unknown } | null)?.message === 'string' ? ` ${(response.json as { message: string }).message}` : ''}`;
+
+export interface StartOptions {
+  readonly ref: string;
+  readonly readableWithinMs?: number;
+}
+
+async function untilReadable(github: GitHub, runId: string, withinMs: number): Promise<void> {
+  const deadline = Date.now() + withinMs;
+  while ((await github.api('GET', `/actions/runs/${runId}`)).status !== 200 && Date.now() < deadline) await sleep(Math.min(1500, withinMs / 4));
+}
+
+async function findRun(github: GitHub, query: string, matches: (run: { id: number; display_title: string }) => boolean, seconds: number): Promise<string | null> {
+  const deadline = Date.now() + seconds * 1000;
+  for (;;) {
+    const listed = await github.api('GET', `/actions/workflows/${github.workflow}/runs?per_page=20&${query}`);
+    const runs = ((listed.json as { workflow_runs?: { id: number; display_title: string }[] } | null)?.workflow_runs ?? []).filter(matches);
+    if (runs[0] !== undefined) return String(runs[0].id);
+    if (Date.now() >= deadline) return null;
+    await sleep(3000);
+  }
+}
+
+const isRunOf = (request: Pick<SessionRequest, 'owner' | 'session'>) => (run: { display_title: string }): boolean => {
+  const title = RUN_TITLE.exec(run.display_title);
+  return title !== null && title[1] === request.owner && title[2] === request.session;
+};
+
+export async function startRun(github: GitHub, request: SessionRequest, options: StartOptions): Promise<string> {
+  const dispatched = await github.api('POST', `/actions/workflows/${github.workflow}/dispatches`, {
+    ref: options.ref,
+    inputs: { owner: request.owner, session: request.session, request: JSON.stringify(request) },
+    return_run_details: true,
+  });
+  const byDispatch = async (runId: string): Promise<string> => {
+    await untilReadable(github, runId, options.readableWithinMs ?? 60_000);
+    return runId;
+  };
+  const late = `{cli} down --stale ends it once it shows at https://github.com/${github.repo}/actions/workflows/${github.workflow}`;
+  if (dispatched.status === 200 || dispatched.status === 204) {
+    const direct = (dispatched.json as { workflow_run_id?: number } | null)?.workflow_run_id;
+    const runId = direct !== undefined ? String(direct) : await findRun(github, 'event=workflow_dispatch', isRunOf(request), 180);
+    if (runId === null) throw new VerifyFailure('NOT_READY', `GitHub accepted the dispatch of ${github.workflow} but no run for session ${request.session} appeared in 3 minutes; if it starts later it bills until it idles out`, late);
+    return byDispatch(runId);
+  }
+  const dispatchRefused = message(dispatched);
+  if (dispatched.status >= 500) {
+    const runId = await findRun(github, 'event=workflow_dispatch', isRunOf(request), 60);
+    if (runId === null) throw new VerifyFailure('NOT_READY', `GitHub answered the dispatch of ${github.workflow} with ${dispatchRefused}, and no run for session ${request.session} appeared in a minute`, `run the command again; if a run for this session starts late, ${late}`);
+    return byDispatch(runId);
+  }
+  throw new VerifyFailure(
+    'NOT_READY',
+    `could not start a session: GitHub refused the dispatch of ${github.workflow} (${dispatchRefused})`,
+    `a session needs permission to dispatch ${github.workflow} on ${github.repo}; push the branch that holds ${github.workflow} first if GitHub has never seen it. ${CLOUD_GITHUB_ACCESS}`,
+  );
+}
+
+export interface RunView {
+  readonly status: string;
+  readonly conclusion: string | null;
+  readonly url: string;
+}
+
+export async function viewRun(github: GitHub, runId: string): Promise<RunView> {
+  const response = await github.api('GET', `/actions/runs/${runId}`);
+  if (response.status !== 200) throw new VerifyFailure('NOT_READY', `could not read run ${runId}: ${message(response)}`, `open https://github.com/${github.repo}/actions/runs/${runId}`);
+  const run = response.json as { status: string; conclusion: string | null; html_url: string };
+  return { status: run.status, conclusion: run.conclusion, url: run.html_url };
+}
+
+export interface JobView {
+  readonly name: string;
+  readonly status: string;
+  readonly steps: readonly { readonly name: string; readonly status: string; readonly conclusion: string | null }[];
+}
+
+export async function viewJobs(github: GitHub, runId: string): Promise<readonly JobView[]> {
+  const response = await github.api('GET', `/actions/runs/${runId}/jobs?per_page=30`);
+  if (response.status !== 200) return [];
+  type Wire = { name: string; status: string; conclusion: string | null; steps?: { name: string; status: string; conclusion: string | null }[] };
+  return ((response.json as { jobs?: Wire[] } | null)?.jobs ?? []).map((job) => ({
+    name: job.name,
+    status: job.status,
+    steps: (job.steps ?? []).map((step) => ({ name: step.name, status: step.status, conclusion: step.conclusion })),
+  }));
+}
+
+export function publishedStep(jobs: readonly JobView[], pattern: RegExp): string | null {
+  for (const job of jobs) {
+    for (const step of job.steps) {
+      const found = pattern.exec(step.name)?.[1];
+      if (found !== undefined && found !== '') return found;
+    }
+  }
+  return null;
+}
+
+export async function waitForStep(github: GitHub, runId: string, pattern: RegExp, seconds: number, onWait?: (run: RunView, jobs: readonly JobView[]) => void): Promise<string> {
+  const deadline = Date.now() + seconds * 1000;
+  for (;;) {
+    const jobs = await viewJobs(github, runId);
+    const found = publishedStep(jobs, pattern);
+    if (found !== null) return found;
+    const run = await viewRun(github, runId);
+    if (run.status === 'completed') {
+      const failed = jobs.flatMap((job) => job.steps.filter((step) => step.conclusion === 'failure').map((step) => `${job.name}: ${step.name}`));
+      throw new VerifyFailure('NOT_READY', `run ${runId} ended (${run.conclusion ?? 'no conclusion'}) before it published${failed.length > 0 ? `; failed at ${failed.join(', ')}` : ''}`, `read ${run.url}`);
+    }
+    if (Date.now() >= deadline) throw new VerifyFailure('NOT_READY', `run ${runId} published nothing within ${seconds}s (it is ${run.status})`, `read ${run.url}; a runner label with no free machine stays queued`);
+    onWait?.(run, jobs);
+    await sleep(4000);
+  }
+}
+
+export function waitReporter(progress: (line: string) => void, runId: string, labels: { readonly plan: string; readonly session: string }): (run: RunView, jobs: readonly JobView[]) => void {
+  const began = Date.now();
+  let last = '';
+  let lastAt = 0;
+  return (_run, jobs) => {
+    const session = jobs.find((job) => job.name === 'session');
+    const plan = jobs.find((job) => job.name === 'plan');
+    const what =
+      session === undefined
+        ? plan?.status === 'in_progress'
+          ? `its request to be read on ${labels.plan}`
+          : `a ${labels.plan} runner to read its request`
+        : session.status === 'queued'
+          ? `a ${labels.session} runner`
+          : `the tunnel on ${labels.session}`;
+    if (what === last && Date.now() - lastAt < 60_000) return;
+    progress(`wait    run ${runId} has waited ${Math.round((Date.now() - began) / 1000)}s, now for ${what}`);
+    last = what;
+    lastAt = Date.now();
+  };
+}
+
+async function waitForRunEnd(github: GitHub, runId: string, seconds: number): Promise<RunView> {
+  const deadline = Date.now() + seconds * 1000;
+  for (;;) {
+    const run = await viewRun(github, runId);
+    if (run.status === 'completed' || Date.now() >= deadline) return run;
+    await sleep(4000);
+  }
+}
+
+async function cancelRun(github: GitHub, runId: string): Promise<string | null> {
+  const response = await github.api('POST', `/actions/runs/${runId}/cancel`);
+  return response.status === 202 || response.status === 409 ? null : message(response);
+}
+
+export interface LiveRun {
+  readonly runId: string;
+  readonly owner: string;
+  readonly session: string;
+  readonly createdAt: string;
+}
+
+export async function liveRuns(github: GitHub): Promise<readonly LiveRun[]> {
+  const out: LiveRun[] = [];
+  for (const status of ['in_progress', 'queued'] as const) {
+    const listed = await github.api('GET', `/actions/workflows/${github.workflow}/runs?per_page=50&status=${status}`);
+    for (const run of (listed.json as { workflow_runs?: { id: number; display_title: string; created_at: string }[] } | null)?.workflow_runs ?? []) {
+      const title = RUN_TITLE.exec(run.display_title);
+      if (title !== null) out.push({ runId: String(run.id), owner: title[1]!, session: title[2]!, createdAt: run.created_at });
+    }
+  }
+  return out;
+}
+
+export async function currentBranch(runner: Runner, worktree: string): Promise<string> {
+  const branch = (await runner('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: worktree })).stdout.trim();
+  if (branch === '' || branch === 'HEAD') throw new VerifyFailure('NOT_READY', 'HEAD is detached, so there is no branch to start a session from', 'git switch -c <branch>, then git push -u origin <branch>');
+  return branch;
+}
+
+// A cancelled job abandons the step that uploads the evidence, so a session that holds evidence gets longer to end by itself.
+const ARTIFACT_UPLOAD_SECONDS = 300;
+
+export async function endSession(github: GitHub, runId: string, ref: SessionRef | null): Promise<{ readonly conclusion: string | null; readonly cancelled: boolean; readonly problem: string | null }> {
+  const stopped = ref !== null && existsSync(ref.tokenFile) ? await sessionCall(ref, '/__sim/stop', { method: 'POST', timeoutMs: 15_000 }).catch(() => null) : null;
+  const holdsEvidence = stopped?.status === 200 && ((await stopped.json().catch(() => null)) as { evidence?: unknown } | null)?.evidence != null;
+  let run = await waitForRunEnd(github, runId, ref === null ? 0 : holdsEvidence ? ARTIFACT_UPLOAD_SECONDS : 90);
+  if (run.status === 'completed') return { conclusion: run.conclusion, cancelled: false, problem: null };
+  const refused = await cancelRun(github, runId);
+  run = await waitForRunEnd(github, runId, 60);
+  if (run.status === 'completed') return { conclusion: run.conclusion, cancelled: true, problem: null };
+  return { conclusion: null, cancelled: refused === null, problem: `run ${runId} is still ${run.status}${refused === null ? '' : ` and the cancel was refused (${refused})`}; it ends itself on idle or at its cap` };
+}
+
+export { message as apiMessage };
diff --git a/e2e-tests/src/core/remote/handoff.ts b/e2e-tests/src/core/remote/handoff.ts
new file mode 100644
index 000000000..05bc2d9b3
--- /dev/null
+++ b/e2e-tests/src/core/remote/handoff.ts
@@ -0,0 +1,231 @@
+import { createHash } from 'node:crypto';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Platform } from '../types.ts';
+
+export const HANDOFF_VERSION = 1 as const;
+
+export const HANDOFF = {
+  artifact: 'verify-evidence',
+  directory: 'evidence',
+  staging: 'evidence.partial',
+  manifestFile: 'manifest.json',
+} as const;
+
+const MIB = 1024 * 1024;
+
+export const HANDOFF_LIMITS = {
+  manifestBytes: 16 * 1024,
+  files: 50,
+  videos: 1,
+  imageBytes: 10 * MIB,
+  videoBytes: 100 * MIB,
+  totalBytes: 150 * MIB,
+  chunkBytes: MIB,
+  chunkBodyBytes: 1_500_000,
+  pr: 9_999_999,
+  tests: 10_000,
+} as const;
+
+export interface HandoffFile {
+  readonly name: string;
+  readonly bytes: number;
+  readonly sha256: string;
+}
+
+export interface HandoffManifest {
+  readonly v: typeof HANDOFF_VERSION;
+  readonly pr: number;
+  readonly run: string;
+  readonly platform: Platform;
+  readonly device: string;
+  readonly commit: string;
+  readonly passed: number;
+  readonly flaky: number;
+  readonly total: number;
+  readonly files: readonly HandoffFile[];
+}
+
+const SHAPE = {
+  run: /^r\d{8}-\d{6}-[0-9a-f]{4}$/,
+  device: /^[A-Za-z0-9][A-Za-z0-9 ._()-]{0,63}$/,
+  commit: /^[0-9a-f]{40}$/,
+  sha256: /^[0-9a-f]{64}$/,
+  fileName: /^[A-Za-z0-9][A-Za-z0-9._-]{0,95}\.(png|jpg|mp4)$/,
+} as const;
+
+const MANIFEST_KEYS = ['v', 'pr', 'run', 'platform', 'device', 'commit', 'passed', 'flaky', 'total', 'files'];
+const FILE_KEYS = ['name', 'bytes', 'sha256'];
+
+export class HandoffRefused extends Error {
+  readonly status: 400 | 409 | 413;
+  readonly have: number | undefined;
+  constructor(status: 400 | 409 | 413, message: string, have?: number) {
+    super(message);
+    this.status = status;
+    this.have = have;
+  }
+}
+
+const refuse = (message: string): never => {
+  throw new HandoffRefused(400, message);
+};
+
+function record(value: unknown, keys: readonly string[], what: string): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return refuse(`${what} is not an object`);
+  const extra = Object.keys(value).filter((key) => !keys.includes(key));
+  if (extra.length > 0 || Object.keys(value).length !== keys.length) return refuse(`${what} must have exactly the keys ${keys.join(', ')}`);
+  return value as Record<string, unknown>;
+}
+
+function whole(value: unknown, min: number, max: number, what: string): number {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < min || value > max) return refuse(`${what} must be a whole number from ${min} to ${max}`);
+  return value;
+}
+
+function shaped(value: unknown, pattern: RegExp, what: string): string {
+  if (typeof value !== 'string' || !pattern.test(value)) return refuse(`${what} is missing or malformed`);
+  return value;
+}
+
+export const isVideo = (name: string): boolean => name.endsWith('.mp4');
+
+export function parseHandoffManifest(text: string): HandoffManifest {
+  if (Buffer.byteLength(text) > HANDOFF_LIMITS.manifestBytes) refuse(`the manifest is over ${HANDOFF_LIMITS.manifestBytes} bytes`);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return refuse('the manifest is not JSON');
+  }
+  const raw = record(parsed, MANIFEST_KEYS, 'the manifest');
+  if (raw.v !== HANDOFF_VERSION) refuse(`manifest version ${String(raw.v)} is not ${HANDOFF_VERSION}`);
+  if (raw.platform !== 'ios' && raw.platform !== 'android') refuse('platform must be ios or android');
+  if (!Array.isArray(raw.files) || raw.files.length < 1 || raw.files.length > HANDOFF_LIMITS.files) refuse(`files must be a list of 1 to ${HANDOFF_LIMITS.files}`);
+  const files = (raw.files as unknown[]).map((entry, i): HandoffFile => {
+    const file = record(entry, FILE_KEYS, `file ${i + 1}`);
+    const name = shaped(file.name, SHAPE.fileName, `the name of file ${i + 1}`);
+    return { name, bytes: whole(file.bytes, 1, isVideo(name) ? HANDOFF_LIMITS.videoBytes : HANDOFF_LIMITS.imageBytes, `the size of ${name}`), sha256: shaped(file.sha256, SHAPE.sha256, `the sha256 of ${name}`) };
+  });
+  if (new Set(files.map((file) => file.name.toLowerCase())).size !== files.length) refuse('two files have the same name');
+  if (files.filter((file) => isVideo(file.name)).length > HANDOFF_LIMITS.videos) refuse(`at most ${HANDOFF_LIMITS.videos} video`);
+  if (files.reduce((sum, file) => sum + file.bytes, 0) > HANDOFF_LIMITS.totalBytes) refuse(`the files are over ${HANDOFF_LIMITS.totalBytes} bytes in all`);
+  const manifest: HandoffManifest = {
+    v: HANDOFF_VERSION,
+    pr: whole(raw.pr, 1, HANDOFF_LIMITS.pr, 'pr'),
+    run: shaped(raw.run, SHAPE.run, 'run'),
+    platform: raw.platform as Platform,
+    device: shaped(raw.device, SHAPE.device, 'device'),
+    commit: shaped(raw.commit, SHAPE.commit, 'commit'),
+    passed: whole(raw.passed, 0, HANDOFF_LIMITS.tests, 'passed'),
+    flaky: whole(raw.flaky, 0, HANDOFF_LIMITS.tests, 'flaky'),
+    total: whole(raw.total, 1, HANDOFF_LIMITS.tests, 'total'),
+    files,
+  };
+  if (manifest.passed + manifest.flaky < 1 || manifest.passed + manifest.flaky > manifest.total) refuse('passed and flaky must count at least one test and at most total');
+  return manifest;
+}
+
+export const MOST_COMMITS_GITHUB_LISTS = 250;
+
+export interface PullRequestView {
+  readonly state: string;
+  readonly headRepo: string | null;
+  readonly headRef: string;
+  readonly commits: readonly string[];
+  readonly commitCount: number;
+}
+
+export interface PullRequestMismatch {
+  readonly why: string;
+  readonly fix: string;
+}
+
+const ITS_OWN_PULL_REQUEST =
+  "it accepts only the open pull request of the session's branch, and only when the commit the session started on and the commit of the run are both commits of that pull request; git push, then {cli} run again and attach, or after a rewrite of the branch's history {cli} down and {cli} up first";
+const FEWER_COMMITS = `it can check a commit only against the first ${MOST_COMMITS_GITHUB_LISTS} commits of a pull request; squash or rebase the branch to ${MOST_COMMITS_GITHUB_LISTS} commits or fewer, git push, then {cli} down, {cli} up, run again and attach, or run {cli} attach on a machine whose gh can attach`;
+
+export function pullRequestMismatch(pull: PullRequestView, session: { readonly repo: string; readonly headBranch: string; readonly startedOn: string; readonly runCommit: string }): PullRequestMismatch | null {
+  const refused = (why: string): PullRequestMismatch => ({ why, fix: ITS_OWN_PULL_REQUEST });
+  if (pull.state !== 'open') return refused(`it is ${pull.state}`);
+  if (pull.headRepo !== session.repo) return refused(`its branch is in ${pull.headRepo ?? 'a deleted fork'}, not in ${session.repo}`);
+  if (pull.headRef !== session.headBranch) return refused(`its branch is ${pull.headRef} and the session runs on ${session.headBranch}`);
+  for (const [what, commit] of [['the session started on', session.startedOn], ['the run was made at', session.runCommit]] as const) {
+    if (pull.commits.includes(commit)) continue;
+    if (pull.commitCount > MOST_COMMITS_GITHUB_LISTS) {
+      return { why: `it has ${pull.commitCount} commits, GitHub lists only the first ${MOST_COMMITS_GITHUB_LISTS}, and ${what} ${commit.slice(0, 12)}, which is not among those`, fix: FEWER_COMMITS };
+    }
+    return refused(`${what} ${commit.slice(0, 12)}, which is not one of its commits`);
+  }
+  return null;
+}
+
+const sha256File = (path: string): string => createHash('sha256').update(readFileSync(path)).digest('hex');
+
+export function describeFile(name: string, path: string): HandoffFile {
+  return { name, bytes: statSync(path).size, sha256: sha256File(path) };
+}
+
+export interface EvidenceReceiver {
+  begin(body: string | null): { readonly ok: true };
+  chunk(body: string | null): { readonly ok: true; readonly bytes: number };
+  commit(): { readonly ok: true; readonly run: string; readonly files: number; readonly bytes: number };
+  held(): string | null;
+}
+
+export function evidenceReceiver(work: string): EvidenceReceiver {
+  const staging = join(work, HANDOFF.staging);
+  const kept = join(work, HANDOFF.directory);
+  let receiving: { readonly manifest: HandoffManifest; readonly sizes: Map<string, number> } | null = null;
+  let heldRun: string | null = null;
+
+  return {
+    begin(body) {
+      if (body === null) throw new HandoffRefused(413, `the manifest is over ${HANDOFF_LIMITS.manifestBytes} bytes`);
+      const manifest = parseHandoffManifest(body);
+      rmSync(staging, { recursive: true, force: true });
+      mkdirSync(staging, { recursive: true });
+      writeFileSync(join(staging, HANDOFF.manifestFile), `${JSON.stringify(manifest)}\n`);
+      receiving = { manifest, sizes: new Map(manifest.files.map((file) => [file.name, 0])) };
+      return { ok: true };
+    },
+
+    chunk(body) {
+      if (receiving === null) throw new HandoffRefused(409, 'no hand-off has begun');
+      if (body === null) throw new HandoffRefused(413, `a chunk request is at most ${HANDOFF_LIMITS.chunkBodyBytes} bytes`);
+      let raw: Record<string, unknown>;
+      try {
+        raw = record(JSON.parse(body), ['name', 'offset', 'data'], 'the chunk');
+      } catch (error) {
+        throw error instanceof HandoffRefused ? error : new HandoffRefused(400, 'the chunk is not JSON');
+      }
+      const declared = receiving.manifest.files.find((file) => file.name === raw.name);
+      if (declared === undefined) throw new HandoffRefused(400, 'the manifest names no such file');
+      const have = receiving.sizes.get(declared.name)!;
+      if (raw.offset !== have) throw new HandoffRefused(409, `${declared.name} is at ${have} bytes`, have);
+      if (typeof raw.data !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(raw.data)) throw new HandoffRefused(400, 'data must be base64');
+      const data = Buffer.from(raw.data, 'base64');
+      if (data.length === 0 || data.length > HANDOFF_LIMITS.chunkBytes) throw new HandoffRefused(413, `a chunk holds 1 to ${HANDOFF_LIMITS.chunkBytes} bytes`);
+      if (have + data.length > declared.bytes) throw new HandoffRefused(413, `${declared.name} would pass the ${declared.bytes} bytes its manifest declares`);
+      appendFileSync(join(staging, declared.name), data);
+      receiving.sizes.set(declared.name, have + data.length);
+      return { ok: true, bytes: have + data.length };
+    },
+
+    commit() {
+      if (receiving === null) throw new HandoffRefused(409, 'no hand-off has begun');
+      const { manifest, sizes } = receiving;
+      for (const file of manifest.files) {
+        if (sizes.get(file.name) !== file.bytes) throw new HandoffRefused(409, `${file.name} has ${sizes.get(file.name)} of ${file.bytes} bytes`);
+        if (sha256File(join(staging, file.name)) !== file.sha256) throw new HandoffRefused(409, `${file.name} does not have the sha256 its manifest declares`);
+      }
+      rmSync(kept, { recursive: true, force: true });
+      renameSync(staging, kept);
+      receiving = null;
+      heldRun = manifest.run;
+      return { ok: true, run: manifest.run, files: manifest.files.length, bytes: manifest.files.reduce((sum, file) => sum + file.bytes, 0) };
+    },
+
+    held: () => (heldRun !== null && existsSync(kept) ? heldRun : null),
+  };
+}
diff --git a/e2e-tests/src/core/remote/preflight.ts b/e2e-tests/src/core/remote/preflight.ts
new file mode 100644
index 000000000..ba1b6fadf
--- /dev/null
+++ b/e2e-tests/src/core/remote/preflight.ts
@@ -0,0 +1,233 @@
+import net from 'node:net';
+import { arch, platform as osPlatform, release } from 'node:os';
+import type { Runner } from '../exec.ts';
+import { proxyPort } from '../launch.mjs';
+import { VerifyFailure, type DoctorCheck, type DoctorCheckId, type DoctorOptions } from '../types.ts';
+import { CLOUD_GITHUB_ACCESS, apiMessage, currentBranch, endSession, gitFailure, liveRuns, startRun, viewJobs, waitForStep, waitReporter, type ApiResponse, type GitHub } from './github.ts';
+import { STEP } from './protocol.ts';
+import { daemonHealthy, firstHealth, sessionHealth, tunnelUrl, type SessionRef } from './session.ts';
+import { forgetSession, newSessionRequest, saveToken, savedDriverId, type RemoteDeps, type RemoteSettings } from './settings.ts';
+import { TUNNEL } from './tunnel.ts';
+
+const CLOUD_FIX = `add ${TUNNEL.allowedHost} to the allowed domains of the environment this command runs in`;
+
+function check(id: DoctorCheckId, ok: boolean, detail: string, fix: string): DoctorCheck {
+  return ok ? { id, ok, detail } : { id, ok, detail, fix };
+}
+
+const notRun = (id: DoctorCheckId, why: string): DoctorCheck => ({ id, ok: true, state: 'not-run', detail: `not run: ${why}` });
+const blockedBy = (id: DoctorCheckId, failed: DoctorCheckId, why = ''): DoctorCheck => notRun(id, `needs ${failed}${why === '' ? '' : ` (${why})`}`);
+
+const ONLY_LIVE = 'doctor starts no workflow run without --live';
+
+const failureText = (error: unknown): string => {
+  const cause = (error as { cause?: { code?: string; message?: string } }).cause;
+  return `${(error as Error).message}${cause === undefined ? '' : ` (${cause.code ?? cause.message ?? ''})`}`;
+};
+
+function proxyOf(env: RemoteDeps['env']): URL | null {
+  const raw = env.HTTPS_PROXY ?? env.https_proxy;
+  if (raw === undefined || raw === '') return null;
+  try {
+    return new URL(raw);
+  } catch {
+    return null;
+  }
+}
+
+export function connectThroughProxy(proxy: URL, host: string, timeoutMs = 10_000): Promise<{ readonly status: number; readonly line: string }> {
+  return new Promise((resolve) => {
+    const socket = net.connect(proxyPort(proxy), proxy.hostname);
+    const authorization = proxy.username === '' || proxy.password === '' ? '' : `Proxy-Authorization: Basic ${Buffer.from(`${decodeURIComponent(proxy.username)}:${decodeURIComponent(proxy.password)}`).toString('base64')}\r\n`;
+    let seen = '';
+    const finish = (status: number, line: string) => {
+      socket.destroy();
+      resolve({ status, line });
+    };
+    socket.setTimeout(timeoutMs, () => finish(0, 'the proxy did not answer'));
+    socket.on('error', (error) => finish(0, `the proxy is unreachable: ${error.message}`));
+    socket.on('connect', () => socket.write(`CONNECT ${host}:443 HTTP/1.1\r\nHost: ${host}:443\r\n${authorization}\r\n`));
+    socket.on('data', (chunk: Buffer) => {
+      seen += chunk.toString('latin1');
+      const end = seen.indexOf('\r\n');
+      if (end < 0) return;
+      const line = seen.slice(0, end);
+      finish(Number(/^HTTP\/\d\.\d (\d{3})/.exec(line)?.[1] ?? 0), line);
+    });
+  });
+}
+
+export async function egressCheck(id: DoctorCheckId, host: string, env: RemoteDeps['env'], fix: string, request: typeof fetch = fetch): Promise<DoctorCheck> {
+  const proxy = proxyOf(env);
+  const usesProxy = proxy !== null && env.NODE_USE_ENV_PROXY === '1';
+  if (usesProxy) {
+    const connect = await connectThroughProxy(proxy, host);
+    if (connect.status !== 200) return check(id, false, `blocked: the proxy at ${proxy.host} answered the CONNECT to ${host} with "${connect.line}"`, fix);
+  }
+  const via = usesProxy ? ` through the proxy at ${proxy.host}` : '';
+  try {
+    const response = await request(`https://${host}/`, { redirect: 'manual', signal: AbortSignal.timeout(15_000) });
+    const fromCloudflare = response.headers.has('cf-ray') || response.headers.get('server') === 'cloudflare';
+    if (fromCloudflare) return check(id, true, `reached ${host}${via}: HTTP ${response.status} from cloudflare`, '');
+    return check(id, false, `blocked: ${host} answered HTTP ${response.status}${via} without Cloudflare's headers, so something between this machine and the host answered in its place`, fix);
+  } catch (error) {
+    return check(id, false, `no response from ${host}${via}: ${failureText(error)}`, fix);
+  }
+}
+
+async function environmentCheck(github: GitHub, deps: RemoteDeps, worktree: string): Promise<DoctorCheck> {
+  const npm = await deps.runner('npm', ['--version']);
+  const gh = await deps.runner('gh', ['--version']);
+  const remote = (await deps.runner('git', ['remote', 'get-url', 'origin'], { cwd: worktree })).stdout.trim();
+  const remoteKind = /^(git@|ssh:)/.test(remote) ? 'ssh' : /^https?:\/\/(127\.0\.0\.1|localhost)/.test(remote) ? 'a local git proxy' : /^https?:/.test(remote) ? 'https' : 'unknown';
+  const proxy = proxyOf(deps.env);
+  const why = deps.env.VERIFY_EGRESS_WHY === undefined ? '' : ` (${deps.env.VERIFY_EGRESS_WHY})`;
+  const egress = proxy === null ? 'direct (no HTTPS_PROXY)' : deps.env.NODE_USE_ENV_PROXY === '1' ? `through the proxy at ${proxy.host}${why}` : `direct, not through the proxy at ${proxy.host}${why}`;
+  const detail = [
+    `${osPlatform()} ${arch()} ${release()}`,
+    `npm ${npm.code === 0 ? npm.stdout.trim() : 'missing'}`,
+    `gh ${gh.code === 0 ? 'present' : 'absent'}`,
+    `GitHub token from ${github.tokenSource === 'none' ? 'nowhere' : github.tokenSource}`,
+    `origin over ${remoteKind}`,
+    `egress ${egress}`,
+  ].join('; ');
+  return check('remote-env', npm.code === 0, detail, 'install npm with Node 24');
+}
+
+async function gitChecks(settings: RemoteSettings, runner: Runner, worktree: string): Promise<readonly DoctorCheck[]> {
+  const git = (args: readonly string[]) => runner('git', args, { cwd: worktree, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
+  let branch: string;
+  try {
+    branch = await currentBranch(runner, worktree);
+  } catch (error) {
+    const failure = error as VerifyFailure;
+    return [check('git-fetch', false, failure.message, failure.fix), blockedBy('git-push', 'git-fetch')];
+  }
+  const fetched = await git(['fetch', '--dry-run', '--no-tags', 'origin', branch]);
+  const pushOwn = await git(['push', '--dry-run', 'origin', `HEAD:refs/heads/${branch}`]);
+  return [
+    check('git-fetch', fetched.code === 0, fetched.code === 0 ? `git fetch origin ${branch} works` : `git fetch origin ${branch} failed: ${gitFailure(fetched.stderr)}`, `git push -u origin ${branch}, and check the remote with git remote -v`),
+    check(
+      'git-push',
+      pushOwn.code === 0,
+      pushOwn.code === 0 ? `dry-run push of ${branch} is accepted` : `dry-run push of ${branch} failed: ${gitFailure(pushOwn.stderr)}`,
+      `verifying a commit you make here needs git push access to ${settings.repo}, because a remote session builds a pushed commit; verifying a commit GitHub already has needs only REST. ${CLOUD_GITHUB_ACCESS}`,
+    ),
+  ];
+}
+
+const withAndWithoutToken = (response: ApiResponse): string => `${apiMessage(response)}${response.firstRefusalWithToken === undefined ? '' : ` without the token (with it: ${response.firstRefusalWithToken})`}`;
+
+async function restCheck(settings: RemoteSettings, github: GitHub): Promise<DoctorCheck> {
+  const fix = `check network access to api.github.com. ${CLOUD_GITHUB_ACCESS}`;
+  try {
+    const repo = await github.api('GET', '');
+    const runs = await github.api('GET', '/actions/runs?per_page=1');
+    const ok = repo.status === 200 && runs.status === 200;
+    const left = repo.headers.get('x-ratelimit-remaining');
+    const tokenRefused = repo.firstRefusalWithToken !== undefined || runs.firstRefusalWithToken !== undefined;
+    return check(
+      'github-rest',
+      ok,
+      `repository ${withAndWithoutToken(repo)}, workflow runs ${withAndWithoutToken(runs)}${left === null ? '' : `, ${left} requests left this hour`}${ok && tokenRefused ? `; reads of ${settings.repo} work, but GitHub refuses this machine's token, so starting a session will fail` : ''}`,
+      fix,
+    );
+  } catch (error) {
+    return check('github-rest', false, `api.github.com did not answer: ${failureText(error)}`, fix);
+  }
+}
+
+async function commitCheck(github: GitHub, runner: Runner, worktree: string): Promise<DoctorCheck> {
+  const sha = (await runner('git', ['rev-parse', 'HEAD'], { cwd: worktree })).stdout.trim();
+  const found = await github.api('GET', `/commits/${sha}`).catch(() => null);
+  return check('remote-commit', found?.status === 200, found?.status === 200 ? `GitHub has HEAD ${sha.slice(0, 12)}` : `GitHub does not have HEAD ${sha.slice(0, 12)} (${found === null ? 'no answer' : found.status})`, 'git push; a remote session builds the pushed commit');
+}
+
+const LIVE_CHECKS = ['live-session', 'live-sim-health', 'live-daemon-health', 'live-device', 'live-stop'] as const satisfies readonly DoctorCheckId[];
+const NO_DEVICE = 'this session boots no device; --runner <label> names a runner that has one';
+
+async function liveChecks(settings: RemoteSettings, deps: RemoteDeps, github: GitHub, options: DoctorOptions): Promise<readonly DoctorCheck[]> {
+  const withDevice = options.runner !== undefined;
+  const { request, token } = newSessionRequest(settings, deps, {
+    runner: options.runner ?? settings.plumbingRunner,
+    device: withDevice ? settings.device : null,
+    sha: null,
+    idleMinutes: 3,
+    capMinutes: withDevice ? 20 : 10,
+  });
+  const tokenFile = saveToken(settings, request.session, token);
+  const checks: DoctorCheck[] = [];
+  const began = Date.now();
+  const seconds = () => Math.round((Date.now() - began) / 1000);
+  const runUrl = (runId: string) => `https://github.com/${settings.repo}/actions/runs/${runId}`;
+  let runId: string | null = null;
+  let session: SessionRef | null = null;
+  try {
+    runId = await startRun(github, request, { ref: await currentBranch(deps.runner, options.worktree) });
+    options.progress(`live    session ${request.session} is run ${runId} on ${request.runner}; it stops itself after 3 idle minutes`);
+    const host = await waitForStep(github, runId, STEP.tunnelPattern, 15 * 60, waitReporter(options.progress, runId, { plan: settings.plumbingRunner, session: request.runner }));
+    session = { baseUrl: tunnelUrl(host), tokenFile };
+    checks.push(check('live-session', true, `run ${runId} on ${request.runner} published its tunnel ${seconds()}s after the dispatch`, ''));
+
+    const health = await firstHealth(session, 120);
+    checks.push(check('live-sim-health', health !== null, health === null ? '/__sim/health did not answer 200 with the bearer' : `/__sim/health answered through the tunnel ${seconds()}s in`, CLOUD_FIX));
+
+    let daemon = false;
+    let deviceReady = !withDevice;
+    const deadline = Date.now() + (withDevice ? 12 : 4) * 60_000;
+    while (health !== null && Date.now() < deadline && !(daemon && deviceReady)) {
+      daemon = daemon || (await daemonHealthy(session));
+      deviceReady = deviceReady || (await sessionHealth(session))?.device?.ready === true;
+      if (!(daemon && deviceReady)) await new Promise((done) => setTimeout(done, 5000));
+    }
+    checks.push(check('live-daemon-health', daemon, daemon ? `/agent-device/health answered through the tunnel ${seconds()}s in` : '/agent-device/health never answered ok', `read ${runUrl(runId)}`));
+    if (withDevice) checks.push(check('live-device', deviceReady, deviceReady ? `${settings.device} was ready on ${request.runner} ${seconds()}s in` : `${settings.device} was not ready in time`, `read ${runUrl(runId)}; --runner needs a runner image that has a device named ${settings.device}`));
+  } catch (error) {
+    const failure = error instanceof VerifyFailure ? error : new VerifyFailure('NOT_READY', failureText(error), 'run doctor again');
+    const steps = LIVE_CHECKS.filter((id) => id !== 'live-stop' && (withDevice || id !== 'live-device'));
+    const failed = steps.find((id) => !checks.some((c) => c.id === id)) ?? 'live-session';
+    checks.push(check(failed, false, failure.message, failure.fix));
+  } finally {
+    if (runId !== null) {
+      const stopAt = Date.now();
+      const ended = await endSession(github, runId, session);
+      const sessionJob = (await viewJobs(github, runId)).find((job) => job.name === 'session');
+      checks.push(
+        check(
+          'live-stop',
+          ended.problem === null && !ended.cancelled,
+          ended.problem ?? `${ended.cancelled ? 'the stop route did not end the run, so it was cancelled' : 'the stop route ended the run'}: run ${ended.conclusion}, session job ${sessionJob?.status ?? 'not started'} ${Math.round((Date.now() - stopAt) / 1000)}s after the stop`,
+          `open ${runUrl(runId)} and cancel it`,
+        ),
+      );
+    }
+    forgetSession(settings, request.session);
+  }
+  const firstFailure = checks.find((c) => !c.ok)?.id ?? 'live-session';
+  return LIVE_CHECKS.map((id) => checks.find((c) => c.id === id) ?? (id === 'live-device' && !withDevice ? notRun(id, NO_DEVICE) : blockedBy(id, firstFailure)));
+}
+
+export async function remoteDoctorChecks(settings: RemoteSettings, deps: RemoteDeps, openHub: () => Promise<GitHub>, options: DoctorOptions): Promise<{ readonly toolchain: readonly DoctorCheck[]; readonly device: readonly DoctorCheck[] }> {
+  const github = await openHub();
+  const toolchain = [await environmentCheck(github, deps, options.worktree)];
+  const device: DoctorCheck[] = [...(await gitChecks(settings, deps.runner, options.worktree))];
+  const rest = await restCheck(settings, github);
+  device.push(rest);
+  const commit = rest.ok ? await commitCheck(github, deps.runner, options.worktree) : blockedBy('remote-commit', 'github-rest');
+  device.push(commit);
+  const failed: DoctorCheckId | null = !rest.ok ? 'github-rest' : !commit.ok ? 'remote-commit' : null;
+  device.push(await egressCheck('tunnel-egress', TUNNEL.probeHost, deps.env, CLOUD_FIX));
+  device.push(await egressCheck('clerk-egress', 'api.clerk.com', deps.env, 'add api.clerk.com and *.clerk.accounts.dev to the allowed domains; the driver creates test instances, test users, and sign-in tickets there'));
+  if (rest.ok) {
+    const owner = savedDriverId(settings);
+    const mine = owner === null ? [] : (await liveRuns(github)).filter((run) => run.owner === owner);
+    device.push(check('remote-sessions', true, mine.length === 0 ? 'no session of this checkout is running' : `running for this checkout and billed until ended: ${mine.map((run) => `${run.session} (run ${run.runId})`).join(', ')}; {cli} down ends a leased session and {cli} down --stale ends any other`, ''));
+  }
+  if (!options.live) {
+    options.progress('doctor  git and REST reads only: nothing was started; rerun with --live to start one short session, which proves the rest');
+    device.push(...LIVE_CHECKS.map((id) => notRun(id, ONLY_LIVE)));
+  } else {
+    device.push(...(failed === null ? await liveChecks(settings, deps, github, options) : LIVE_CHECKS.map((id) => blockedBy(id, failed))));
+  }
+  return { toolchain, device };
+}
diff --git a/e2e-tests/src/core/remote/protocol.ts b/e2e-tests/src/core/remote/protocol.ts
new file mode 100644
index 000000000..7643081f8
--- /dev/null
+++ b/e2e-tests/src/core/remote/protocol.ts
@@ -0,0 +1,133 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import type { CommandLine } from '../exec.ts';
+import type { Platform } from '../types.ts';
+
+export const REQUEST_VERSION = 1 as const;
+
+export interface SessionRequest {
+  readonly v: typeof REQUEST_VERSION;
+  readonly session: string;
+  readonly owner: string;
+  readonly platform: Platform;
+  readonly runner: string;
+  readonly device: string | null;
+  readonly sha: string | null;
+  readonly idleMinutes: number;
+  readonly capMinutes: number;
+  readonly tokenSha256: string;
+}
+
+export const LIMITS = { idleMinutes: { min: 1, max: 120 }, capMinutes: { min: 2, max: 360 } } as const;
+
+export const RUNNER_LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+const SHAPE = {
+  session: /^[a-z0-9]{4,24}$/,
+  owner: /^[a-f0-9]{12}$/,
+  runner: RUNNER_LABEL,
+  device: /^[A-Za-z0-9][A-Za-z0-9 ._()-]{0,63}$/,
+  sha: /^[0-9a-f]{40}$/,
+  tokenSha256: /^[0-9a-f]{64}$/,
+} as const;
+
+export class RequestError extends Error {}
+
+function whole(name: 'idleMinutes' | 'capMinutes', value: unknown): number {
+  const { min, max } = LIMITS[name];
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < min || value > max) throw new RequestError(`${name} must be a whole number from ${min} to ${max}`);
+  return value;
+}
+
+export function parseRequest(text: string): SessionRequest {
+  let raw: Record<string, unknown>;
+  try {
+    const parsed: unknown = JSON.parse(text);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) throw new Error('not an object');
+    raw = parsed as Record<string, unknown>;
+  } catch {
+    throw new RequestError('the request is not a JSON object');
+  }
+  if (raw.v !== REQUEST_VERSION) throw new RequestError(`request version ${String(raw.v)} is not ${REQUEST_VERSION}`);
+  const field = (name: keyof typeof SHAPE, nullable = false): string | null => {
+    const value = raw[name];
+    if (nullable && value === null) return null;
+    if (typeof value !== 'string' || !SHAPE[name].test(value)) throw new RequestError(`${name} is missing or malformed`);
+    return value;
+  };
+  if (raw.platform !== 'ios' && raw.platform !== 'android') throw new RequestError('platform must be ios or android');
+  const request: SessionRequest = {
+    v: REQUEST_VERSION,
+    session: field('session')!,
+    owner: field('owner')!,
+    platform: raw.platform,
+    runner: field('runner')!,
+    device: field('device', true),
+    sha: field('sha', true),
+    idleMinutes: whole('idleMinutes', raw.idleMinutes),
+    capMinutes: whole('capMinutes', raw.capMinutes),
+    tokenSha256: field('tokenSha256')!,
+  };
+  if (request.idleMinutes > request.capMinutes) throw new RequestError('idleMinutes cannot exceed capMinutes');
+  return request;
+}
+
+export const sha256Hex = (value: string): string => createHash('sha256').update(value).digest('hex');
+
+export function matchesToken(tokenSha256: string, presented: string): boolean {
+  const given = Buffer.from(sha256Hex(presented), 'hex');
+  const want = Buffer.from(tokenSha256, 'hex');
+  return given.length === want.length && timingSafeEqual(given, want);
+}
+
+export const STEP = {
+  tunnelPattern: /^verify-remote tunnel ([a-z0-9.-]+)$/,
+} as const;
+
+export const RUN_TITLE = /(?:^|[ /])([a-f0-9]{12})\/([a-z0-9]{4,24})$/;
+
+export type BuildState =
+  | { readonly state: 'none' }
+  | { readonly state: 'building'; readonly sha: string; readonly seconds: number }
+  | { readonly state: 'built'; readonly sha: string; readonly seconds: number; readonly incremental: boolean }
+  | { readonly state: 'failed'; readonly sha: string; readonly seconds: number; readonly tail: string }
+  | { readonly state: 'timed-out'; readonly sha: string; readonly seconds: number; readonly tail: string };
+
+export const BUILD_TIMEOUT_MINUTES = 45;
+
+export type EndReason = 'stop' | 'idle' | 'cap' | 'tunnel-lost' | 'signal';
+
+export interface SessionHealth {
+  readonly core: string;
+  readonly device: { readonly id: string; readonly name: string; readonly ready: boolean } | null;
+  readonly daemon: boolean;
+  readonly build: BuildState;
+  readonly capAt: string;
+  readonly ending: EndReason | null;
+}
+
+export interface SessionDevice {
+  build(work: string): readonly CommandLine[];
+  readonly record: {
+    start(file: string): CommandLine;
+    stop?(file: string): readonly CommandLine[];
+    collect?(file: string): readonly CommandLine[];
+  };
+  logs(since: Date, predicate: string | null): CommandLine;
+}
+export interface SessionDeviceRef {
+  readonly id: string;
+  readonly platform: Platform;
+}
+export type SessionDeviceFactory = (device: SessionDeviceRef) => SessionDevice;
+
+export type RecipeRequest =
+  | { readonly op: 'build'; readonly work: string }
+  | { readonly op: 'record'; readonly file: string }
+  | { readonly op: 'logs'; readonly since: string; readonly predicate: string | null };
+
+export interface RecipeAnswers {
+  readonly build: readonly CommandLine[];
+  readonly record: { readonly start: CommandLine; readonly stop: readonly CommandLine[] | null; readonly collect: readonly CommandLine[] };
+  readonly logs: CommandLine;
+}
+
diff --git a/e2e-tests/src/core/remote/recipe.ts b/e2e-tests/src/core/remote/recipe.ts
new file mode 100644
index 000000000..ebe510c1c
--- /dev/null
+++ b/e2e-tests/src/core/remote/recipe.ts
@@ -0,0 +1,20 @@
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { RecipeAnswers, RecipeRequest, SessionDevice, SessionDeviceFactory, SessionDeviceRef } from './protocol.ts';
+
+export function answer(device: SessionDevice, request: RecipeRequest): RecipeAnswers[RecipeRequest['op']] {
+  switch (request.op) {
+    case 'build':
+      return device.build(request.work);
+    case 'record':
+      return { start: device.record.start(request.file), stop: device.record.stop?.(request.file) ?? null, collect: device.record.collect?.(request.file) ?? [] };
+    case 'logs':
+      return device.logs(new Date(request.since), request.predicate);
+  }
+}
+
+if (import.meta.main) {
+  const asked = JSON.parse(process.argv[2] ?? '') as { readonly device: SessionDeviceRef; readonly request: RecipeRequest };
+  const module = (await import(pathToFileURL(resolve(process.env.VERIFY_SESSION_DEVICE_MODULE ?? '')).href)) as { default: SessionDeviceFactory };
+  process.stdout.write(JSON.stringify(answer(module.default(asked.device), asked.request)));
+}
diff --git a/e2e-tests/src/core/remote/session-agent.ts b/e2e-tests/src/core/remote/session-agent.ts
new file mode 100644
index 000000000..0132db7c4
--- /dev/null
+++ b/e2e-tests/src/core/remote/session-agent.ts
@@ -0,0 +1,490 @@
+import { spawn, type ChildProcess } from 'node:child_process';
+import { Resolver } from 'node:dns/promises';
+import { appendFileSync, createReadStream, existsSync, mkdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import http, { type IncomingMessage, type ServerResponse } from 'node:http';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  BUILD_TIMEOUT_MINUTES,
+  RequestError,
+  matchesToken,
+  parseRequest,
+  type BuildState,
+  type EndReason,
+  type RecipeAnswers,
+  type RecipeRequest,
+  type SessionDeviceRef,
+  type SessionHealth,
+  type SessionRequest,
+} from './protocol.ts';
+import type { CommandLine, ExecResult } from '../exec.ts';
+import { coreVersion } from '../manifest.ts';
+import { HANDOFF_LIMITS, HandoffRefused, evidenceReceiver } from './handoff.ts';
+import { TUNNEL } from './tunnel.ts';
+
+const AGENT_ROUTES = ['/agent-device', '/health', '/rpc', '/upload', '/artifacts'];
+const DAEMON_GRACE_MS = 60_000;
+const COMMAND_TIMEOUT_MS = 30_000;
+const PUBLIC_RESOLVERS = ['1.1.1.1', '8.8.8.8'];
+const RECIPE = fileURLToPath(new URL('./recipe.ts', import.meta.url));
+const PINNED_AGENT_DEVICE = fileURLToPath(new URL('../../../node_modules/.bin/agent-device', import.meta.url));
+
+function setOutputs(file: string | undefined, values: Readonly<Record<string, string>>): void {
+  const text = Object.entries(values).map(([key, value]) => `${key}=${value}\n`).join('');
+  if (file === undefined || file === '') process.stdout.write(text);
+  else appendFileSync(file, text);
+}
+
+type Env = Readonly<Record<string, string | undefined>>;
+type GitHubGet = (path: string) => Promise<unknown>;
+
+const COMMIT = /^[0-9a-f]{40}$/;
+
+function githubOf(env: Env): GitHubGet {
+  const base = `${(env.GITHUB_API_URL ?? 'https://api.github.com').replace(/\/$/, '')}/repos/${env.GITHUB_REPOSITORY ?? ''}`;
+  const token = env.GITHUB_TOKEN ?? '';
+  return async (path) => {
+    try {
+      const response = await fetch(`${base}${path}`, {
+        headers: { Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28', 'User-Agent': 'verify-remote', ...(token === '' ? {} : { Authorization: `Bearer ${token}` }) },
+        signal: AbortSignal.timeout(30_000),
+      });
+      return response.ok ? await response.json() : null;
+    } catch {
+      return null;
+    }
+  };
+}
+
+function takeGitHub(env: NodeJS.ProcessEnv): GitHubGet {
+  const get = githubOf(env);
+  delete env.GITHUB_TOKEN;
+  return get;
+}
+
+async function isALaterCommitOfTheBranch(sha: string, dispatched: string, ref: string, get: GitHubGet): Promise<boolean> {
+  const branch = /^refs\/heads\/(.+)$/.exec(ref)?.[1];
+  if (branch === undefined || !COMMIT.test(dispatched)) return false;
+  const found = (await get(`/git/ref/heads/${branch.split('/').map(encodeURIComponent).join('/')}`)) as { readonly object?: { readonly sha?: unknown } } | null;
+  const head = found?.object?.sha;
+  if (typeof head !== 'string' || !COMMIT.test(head)) return false;
+  const comesAfter = async (later: string, earlier: string): Promise<boolean> => ((await get(`/compare/${earlier}...${later}`)) as { readonly status?: unknown } | null)?.status === 'ahead';
+  return (await comesAfter(sha, dispatched)) && (sha === head || (await comesAfter(head, sha)));
+}
+
+export async function plan(env: Env, get: GitHubGet = githubOf(env)): Promise<number> {
+  let request: SessionRequest;
+  try {
+    request = parseRequest((env.VERIFY_REQUEST ?? '').trim());
+  } catch (error) {
+    if (!(error instanceof RequestError)) throw error;
+    console.log(`::notice title=verify-remote::no session started: ${error.message}`);
+    setOutputs(env.GITHUB_OUTPUT, { mode: 'none' });
+    return 0;
+  }
+  const dispatched = env.GITHUB_SHA ?? '';
+  const ref = env.GITHUB_REF ?? '';
+  if (request.sha !== null && request.sha !== dispatched && !(await isALaterCommitOfTheBranch(request.sha, dispatched, ref, get))) {
+    console.log(
+      `::error title=verify-remote::no session started: the request asks for commit ${request.sha}. This run was dispatched on ${dispatched}, and GitHub does not show the requested commit as a later commit of ${ref}. Push that commit to the branch, or pull the branch, then start the session again.`,
+    );
+    return 1;
+  }
+  setOutputs(env.GITHUB_OUTPUT, {
+    mode: 'session',
+    runner: request.runner,
+    device: request.device ?? '',
+    sha: request.sha ?? '',
+    timeout: String(request.capMinutes + 10),
+    request: JSON.stringify(request),
+  });
+  return 0;
+}
+
+function json(res: ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(JSON.stringify(body));
+}
+
+function bearer(req: IncomingMessage): string | null {
+  return /^Bearer +(\S.*)$/i.exec((req.headers.authorization ?? '').trim())?.[1] ?? null;
+}
+
+const isAgentRoute = (pathname: string): boolean => AGENT_ROUTES.some((route) => pathname === route || pathname.startsWith(`${route}/`));
+
+function exitOf(child: ChildProcess): Promise<number> {
+  return new Promise((done) => {
+    child.on('error', () => done(127));
+    child.on('close', (code) => done(code ?? 1));
+  });
+}
+
+function stopGroup(child: ChildProcess | null): void {
+  if (child?.pid === undefined || child.exitCode !== null) return;
+  const signal = (name: NodeJS.Signals) => {
+    try {
+      process.kill(-child.pid!, name);
+    } catch {
+      child.kill(name);
+    }
+  };
+  signal('SIGTERM');
+  setTimeout(() => child.exitCode === null && signal('SIGKILL'), 10_000).unref();
+}
+
+async function runBriefly(commands: readonly CommandLine[]): Promise<void> {
+  for (const step of commands) {
+    const child = spawn(step.command, [...step.args], { cwd: step.cwd, stdio: 'ignore' });
+    const timer = setTimeout(() => child.kill('SIGKILL'), COMMAND_TIMEOUT_MS);
+    await exitOf(child);
+    clearTimeout(timer);
+  }
+}
+
+async function capture(command: CommandLine, options: { readonly timeoutMs: number; readonly limit: number }): Promise<ExecResult> {
+  const child = spawn(command.command, [...command.args], { cwd: command.cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+  const kept = { stdout: '', stderr: '' };
+  const keep = (stream: 'stdout' | 'stderr') => (chunk: Buffer) => (kept[stream] = (kept[stream] + chunk.toString()).slice(-options.limit));
+  child.stdout.on('data', keep('stdout'));
+  child.stderr.on('data', keep('stderr'));
+  const timer = setTimeout(() => child.kill('SIGKILL'), options.timeoutMs);
+  const code = await exitOf(child);
+  clearTimeout(timer);
+  return { code, ...kept };
+}
+
+async function recipe<Op extends RecipeRequest['op']>(device: SessionDeviceRef, request: Extract<RecipeRequest, { op: Op }>): Promise<RecipeAnswers[Op]> {
+  const asked = await capture({ command: process.execPath, args: [RECIPE, JSON.stringify({ device, request })] }, { timeoutMs: COMMAND_TIMEOUT_MS, limit: 1_000_000 });
+  if (asked.code !== 0) {
+    const lines = asked.stderr.split('\n').map((line) => line.trim()).filter((line) => line !== '');
+    throw new Error(`the device module of the checked-out commit could not answer ${request.op}: ${lines.find((line) => /^\w*Error\b/.test(line)) ?? lines.slice(-3).join(' | ')}`);
+  }
+  return JSON.parse(asked.stdout) as RecipeAnswers[Op];
+}
+
+function readBody(req: IncomingMessage, limit: number): Promise<string | null> {
+  return new Promise((done) => {
+    let text = '';
+    let over = false;
+    req.on('data', (chunk: Buffer) => {
+      over ||= text.length + chunk.length > limit;
+      if (!over) text += chunk.toString();
+    });
+    req.on('end', () => done(over ? null : text));
+    req.on('error', () => done(null));
+  });
+}
+
+async function serve(env: NodeJS.ProcessEnv): Promise<void> {
+  const request = parseRequest(env.VERIFY_SESSION_REQUEST ?? '');
+  const dispatched = env.GITHUB_SHA ?? '';
+  const dispatchedRef = env.GITHUB_REF ?? '';
+  const github = takeGitHub(env);
+  const work = resolve(env.VERIFY_SESSION_WORK ?? 'verify-remote-work');
+  const port = Number(env.VERIFY_SESSION_PORT ?? 3199);
+  const agentPort = Number(env.VERIFY_SESSION_AGENT_PORT ?? 4310);
+  const deviceId = env.VERIFY_SESSION_DEVICE_ID ?? '';
+  const deviceName = env.VERIFY_SESSION_DEVICE_NAME ?? deviceId;
+  mkdirSync(work, { recursive: true });
+
+  const device: SessionDeviceRef | null = deviceId === '' ? null : { id: deviceId, platform: request.platform };
+  const core = coreVersion();
+  const evidence = evidenceReceiver(work);
+
+  const minuteMs = Number(env.VERIFY_SESSION_MINUTE_MS ?? 60_000);
+  const tickMs = Math.min(5000, minuteMs / 6);
+  const startedAt = Date.now();
+  const capAt = startedAt + request.capMinutes * minuteMs;
+  const idleMs = request.idleMinutes * minuteMs;
+  let lastDriverAt = startedAt;
+  let token: string | null = null;
+  let ending: EndReason | null = null;
+  let daemonOkAt = 0;
+  let proxy: ChildProcess | null = null;
+  let proxyStartedAt = 0;
+  let recorder: ({ readonly child: ChildProcess; readonly exited: Promise<number>; readonly file: string } & Pick<RecipeAnswers['record'], 'stop' | 'collect'>) | null = null;
+  let build: BuildState = { state: 'none' };
+  let buildChild: ChildProcess | null = null;
+  let buildGeneration = 0;
+  let buildSettled: Promise<unknown> = Promise.resolve();
+  let buildBegan = 0;
+  let builtOnce = false;
+
+  const logFile = (name: 'agent-device-proxy' | 'build' | 'tunnel') => join(work, `${name}.log`);
+  const scrub = (text: string): string => (token === null ? text : text.split(token).join('<token>'));
+  const log = (name: Parameters<typeof logFile>[0], chunk: Buffer | string): void => appendFileSync(logFile(name), scrub(chunk.toString()));
+
+  const tunnel = spawn(env.VERIFY_SESSION_CLOUDFLARED ?? TUNNEL.binary, [...TUNNEL.command(port)], { stdio: ['ignore', 'pipe', 'pipe'] });
+  let tunnelSeen = '';
+  let tunnelHost: string | null = null;
+  async function publishTunnelOncePublicDnsHasIt(host: string): Promise<void> {
+    const pastThisMachinesDnsCache = new Resolver({ timeout: 2000, tries: 1 });
+    pastThisMachinesDnsCache.setServers(PUBLIC_RESOLVERS);
+    const deadline = Date.now() + (env.VERIFY_SESSION_SKIP_DNS === '1' ? 0 : 90_000);
+    while (Date.now() < deadline) {
+      if (await pastThisMachinesDnsCache.resolve4(host).then((found) => found.length > 0, () => false)) break;
+      await new Promise((done) => setTimeout(done, 1000));
+    }
+    writeFileSync(join(work, 'tunnel'), host);
+  }
+  const onTunnel = (chunk: Buffer) => {
+    log('tunnel', chunk);
+    if (tunnelHost !== null) return;
+    tunnelSeen += chunk.toString();
+    tunnelHost = TUNNEL.hostPattern.exec(tunnelSeen)?.[1] ?? null;
+    if (tunnelHost !== null) void publishTunnelOncePublicDnsHasIt(tunnelHost);
+  };
+  tunnel.stdout.on('data', onTunnel);
+  tunnel.stderr.on('data', onTunnel);
+  void exitOf(tunnel).then(() => end('tunnel-lost'));
+
+  function ensureProxy(): void {
+    if (token === null || proxy !== null || ending !== null) return;
+    const child = spawn(env.VERIFY_SESSION_AGENT_DEVICE ?? PINNED_AGENT_DEVICE, ['proxy', '--host', '127.0.0.1', '--port', String(agentPort)], {
+      env: { ...process.env, AGENT_DEVICE_DAEMON_AUTH_TOKEN: token },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    proxy = child;
+    proxyStartedAt = Date.now();
+    child.stdout.on('data', (chunk: Buffer) => log('agent-device-proxy', chunk));
+    child.stderr.on('data', (chunk: Buffer) => log('agent-device-proxy', chunk));
+    void exitOf(child).then(() => {
+      if (proxy === child) proxy = null;
+    });
+  }
+
+  async function checkDaemon(): Promise<void> {
+    if (proxy === null) return;
+    const healthy = await fetch(`http://127.0.0.1:${agentPort}/health`, { signal: AbortSignal.timeout(4000) })
+      .then(async (response) => response.ok && /"ok":\s*true/.test(await response.text()))
+      .catch(() => false);
+    if (healthy) daemonOkAt = Date.now();
+    if (Date.now() - Math.max(daemonOkAt, proxyStartedAt) > DAEMON_GRACE_MS) proxy?.kill('SIGTERM');
+  }
+
+  function runCommands(commands: readonly CommandLine[], stopped: () => boolean, tail: string[]): Promise<number> {
+    return commands.reduce<Promise<number>>(async (previous, step) => {
+      const code = await previous;
+      if (code !== 0 || stopped()) return code === 0 ? 1 : code;
+      log('build', `\n$ ${step.command} ${step.args.join(' ')}\n`);
+      const child = spawn(step.command, [...step.args], { cwd: step.cwd, stdio: ['ignore', 'pipe', 'pipe'], detached: true });
+      buildChild = child;
+      const collect = (chunk: Buffer) => {
+        log('build', chunk);
+        for (const line of chunk.toString().split('\n')) if (line.trim() !== '') tail.push(line);
+        tail.splice(0, Math.max(0, tail.length - 30));
+      };
+      child.stdout.on('data', collect);
+      child.stderr.on('data', collect);
+      return exitOf(child);
+    }, Promise.resolve(0));
+  }
+
+  function startBuild(sha: string): void {
+    if (device === null) return;
+    if ((build.state === 'building' || build.state === 'built') && build.sha === sha) return;
+    buildGeneration += 1;
+    stopGroup(buildChild);
+    const generation = buildGeneration;
+    buildBegan = Date.now();
+    const began = buildBegan;
+    const incremental = builtOnce;
+    const tail: string[] = [];
+    let timedOut = false;
+    const stopped = (): boolean => timedOut || generation !== buildGeneration;
+    const timeout = setTimeout(() => {
+      if (generation !== buildGeneration) return;
+      timedOut = true;
+      stopGroup(buildChild);
+    }, BUILD_TIMEOUT_MINUTES * minuteMs);
+    build = { state: 'building', sha, seconds: 0 };
+    rmSync(logFile('build'), { force: true });
+    const checkout: CommandLine[] = [
+      { command: 'git', args: ['fetch', '--no-tags', '--depth=1', 'origin', sha] },
+      { command: 'git', args: ['checkout', '--force', '--detach', sha] },
+    ];
+    const target = device;
+    const checkoutThenBuild = async (): Promise<number> => {
+      if (sha !== dispatched && !(await isALaterCommitOfTheBranch(sha, dispatched, dispatchedRef, github))) {
+        tail.push(`this session builds ${dispatched}, the commit it was started on, and later commits of ${dispatchedRef}. GitHub does not show ${sha} as one. Push it to that branch, or run down and then up to start a session on it.`);
+        return 1;
+      }
+      const checkedOut = await runCommands(checkout, stopped, tail);
+      if (checkedOut !== 0) return checkedOut;
+      try {
+        return await runCommands(await recipe(target, { op: 'build', work }), stopped, tail);
+      } catch (error) {
+        tail.push((error as Error).message);
+        return 1;
+      }
+    };
+    buildSettled = buildSettled.then(checkoutThenBuild).then((code) => {
+      clearTimeout(timeout);
+      if (generation !== buildGeneration) return;
+      const seconds = Math.round((Date.now() - began) / 1000);
+      if (code === 0 && !timedOut) {
+        builtOnce = true;
+        build = { state: 'built', sha, seconds, incremental };
+      } else {
+        build = { state: timedOut ? 'timed-out' : 'failed', sha, seconds, tail: scrub(tail.join('\n')) };
+      }
+    });
+  }
+
+  function health(): SessionHealth {
+    const now = Date.now();
+    return {
+      core,
+      device: device === null ? null : { id: deviceId, name: deviceName, ready: existsSync(join(work, 'device-ready')) },
+      daemon: proxy !== null && now - daemonOkAt < 3 * tickMs,
+      build: build.state === 'building' ? { ...build, seconds: Math.round((now - buildBegan) / 1000) } : build,
+      capAt: new Date(capAt).toISOString(),
+      ending,
+    };
+  }
+
+  async function stopRecording(): Promise<number> {
+    if (recorder === null) return 0;
+    const current = recorder;
+    recorder = null;
+    if (current.stop === null) current.child.kill('SIGINT');
+    else await runBriefly(current.stop);
+    const code = await Promise.race([current.exited, new Promise<null>((done) => setTimeout(() => done(null), COMMAND_TIMEOUT_MS))]);
+    if (code === null) {
+      current.child.kill('SIGKILL');
+      await current.exited;
+    }
+    await runBriefly(current.collect);
+    return existsSync(current.file) ? statSync(current.file).size : 0;
+  }
+
+  function end(reason: EndReason): void {
+    if (ending !== null) return;
+    ending = reason;
+    void (async () => {
+      await stopRecording().catch(() => 0);
+      buildGeneration += 1;
+      stopGroup(buildChild);
+      proxy?.kill('SIGTERM');
+      await new Promise((done) => setTimeout(done, 500));
+      tunnel.kill('SIGTERM');
+      server.close();
+      writeFileSync(join(work, 'ended'), `${JSON.stringify({ reason, at: new Date().toISOString(), minutes: Math.round((Date.now() - startedAt) / 6000) / 10 })}\n`);
+      process.exit(0);
+    })();
+  }
+
+  async function handleSim(req: IncomingMessage, res: ServerResponse, url: URL): Promise<void> {
+    const route = `${req.method} ${url.pathname.slice('/__sim'.length)}`;
+    switch (route) {
+      case 'GET /health':
+        return json(res, 200, health());
+      case 'POST /build': {
+        const sha = url.searchParams.get('sha') ?? '';
+        if (!/^[0-9a-f]{40}$/.test(sha)) return json(res, 400, { error: 'sha must be a full commit id' });
+        if (device === null) return json(res, 409, { error: 'this session has no device to build for' });
+        startBuild(sha);
+        return json(res, 202, health());
+      }
+      case 'POST /record/start': {
+        if (device === null) return json(res, 409, { error: 'this session has no device to record' });
+        await stopRecording();
+        const file = join(work, 'recording.mp4');
+        rmSync(file, { force: true });
+        const { start, stop, collect } = await recipe(device, { op: 'record', file });
+        const child = spawn(start.command, [...start.args], { cwd: start.cwd, stdio: 'ignore' });
+        recorder = { child, exited: exitOf(child), file, stop, collect };
+        return json(res, 200, { ok: true });
+      }
+      case 'POST /record/stop':
+        if (recorder === null) return json(res, 409, { error: 'not recording' });
+        return json(res, 200, { ok: true, bytes: await stopRecording() });
+      case 'GET /record/file': {
+        const file = join(work, 'recording.mp4');
+        if (!existsSync(file)) return json(res, 404, { error: 'no recording' });
+        res.writeHead(200, { 'content-type': 'video/mp4', 'content-length': String(statSync(file).size) });
+        createReadStream(file).pipe(res);
+        return;
+      }
+      case 'GET /logs': {
+        if (device === null) return json(res, 409, { error: 'this session has no device' });
+        const asked = new Date(url.searchParams.get('since') ?? Date.now() - 600_000);
+        const since = Number.isNaN(asked.getTime()) ? new Date(Date.now() - 600_000) : asked;
+        const command = await recipe(device, { op: 'logs', since: since.toISOString(), predicate: url.searchParams.get('predicate') });
+        const child = spawn(command.command, [...command.args], { cwd: command.cwd, stdio: ['ignore', 'pipe', 'ignore'] });
+        res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' });
+        child.stdout.pipe(res);
+        child.on('error', () => res.end());
+        return;
+      }
+      case 'POST /evidence/begin':
+        return json(res, 200, evidence.begin(await readBody(req, HANDOFF_LIMITS.manifestBytes)));
+      case 'POST /evidence/chunk':
+        return json(res, 200, evidence.chunk(await readBody(req, HANDOFF_LIMITS.chunkBodyBytes)));
+      case 'POST /evidence/commit':
+        return json(res, 200, evidence.commit());
+      case 'POST /stop':
+        json(res, 200, { ok: true, evidence: evidence.held() });
+        end('stop');
+        return;
+      default:
+        return json(res, 404, { error: `no route ${route}` });
+    }
+  }
+
+  function authorized(req: IncomingMessage): boolean {
+    const presented = bearer(req);
+    if (presented === null || !matchesToken(request.tokenSha256, presented)) return false;
+    token ??= presented;
+    lastDriverAt = Date.now();
+    return true;
+  }
+
+  const forwarded = (req: IncomingMessage) => ({ ...req.headers, 'x-forwarded-proto': 'https' });
+
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    if (!authorized(req)) return json(res, 403, { error: 'session token required' });
+    if (url.pathname.startsWith('/__sim/')) {
+      handleSim(req, res, url).catch((error: Error) => (error instanceof HandoffRefused ? json(res, error.status, { error: error.message, have: error.have }) : json(res, 500, { error: error.message })));
+      return;
+    }
+    if (!isAgentRoute(url.pathname)) return json(res, 404, { error: `no route ${url.pathname}` });
+    if (proxy === null) return json(res, 503, { error: 'agent-device is not up yet' });
+    const upstream = http.request({ host: '127.0.0.1', port: agentPort, method: req.method, path: req.url, headers: forwarded(req) }, (up) => {
+      res.writeHead(up.statusCode ?? 502, up.headers);
+      up.pipe(res);
+    });
+    upstream.on('error', (error) => {
+      if (!res.headersSent) res.writeHead(502, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ error: `agent-device is unreachable: ${error.message}` }));
+    });
+    req.pipe(upstream);
+  });
+
+  setInterval(() => {
+    if (ending !== null) return;
+    const now = Date.now();
+    if (now >= capAt) return end('cap');
+    if (now - lastDriverAt >= idleMs) return end('idle');
+    ensureProxy();
+    void checkDaemon();
+  }, tickMs);
+  process.on('SIGTERM', () => end('signal'));
+  process.on('SIGINT', () => end('signal'));
+
+  server.listen(port, '127.0.0.1', () => {
+    console.log(`verify-remote session ${request.session} on :${port}, idle stop ${request.idleMinutes} min, cap ${request.capMinutes} min`);
+    if (request.sha !== null) startBuild(request.sha);
+  });
+}
+
+if (import.meta.main) {
+  const [command] = process.argv.slice(2);
+  if (command === 'plan') process.exitCode = await plan(process.env);
+  else if (command === 'serve') await serve(process.env);
+  else {
+    console.error('usage: session-agent.ts plan | serve');
+    process.exit(2);
+  }
+}
diff --git a/e2e-tests/src/core/remote/session.ts b/e2e-tests/src/core/remote/session.ts
new file mode 100644
index 000000000..2f19eb5aa
--- /dev/null
+++ b/e2e-tests/src/core/remote/session.ts
@@ -0,0 +1,106 @@
+import { closeSync, openSync, readFileSync, readSync } from 'node:fs';
+import { sleep } from '../exec.ts';
+import { Secret } from '../../../specs/support/secret.ts';
+import { VerifyFailure } from '../types.ts';
+import { HANDOFF_LIMITS, type HandoffManifest } from './handoff.ts';
+import type { SessionHealth } from './protocol.ts';
+import { TUNNEL, isTunnelHost } from './tunnel.ts';
+
+export interface SessionRef {
+  readonly baseUrl: string;
+  readonly tokenFile: string;
+}
+
+function sessionToken(ref: SessionRef): Secret<'session-bearer'> {
+  return new Secret('session-bearer', readFileSync(ref.tokenFile, 'utf8').trim());
+}
+
+export function tunnelUrl(host: string): string {
+  if (!isTunnelHost(host)) throw new VerifyFailure('NOT_READY', `the session published ${host}, which is not under ${TUNNEL.allowedHost}`, 'do not send the session token there; {cli} down, then {cli} up');
+  return `https://${host}`;
+}
+
+export async function sessionCall(ref: SessionRef, path: string, init: { readonly method?: 'GET' | 'POST'; readonly json?: unknown; readonly timeoutMs?: number } = {}): Promise<Response> {
+  tunnelUrl(new URL(ref.baseUrl).host);
+  const body = init.json === undefined ? {} : { body: JSON.stringify(init.json) };
+  return sessionToken(ref).use('session-bearer', (plain) =>
+    fetch(`${ref.baseUrl}${path}`, {
+      method: init.method ?? 'GET',
+      headers: { Authorization: `Bearer ${plain}`, ...(init.json === undefined ? {} : { 'Content-Type': 'application/json' }) },
+      ...body,
+      signal: AbortSignal.timeout(init.timeoutMs ?? 30_000),
+    }),
+  );
+}
+
+export async function sessionHealth(ref: SessionRef): Promise<SessionHealth | null> {
+  try {
+    const response = await sessionCall(ref, '/__sim/health', { timeoutMs: 15_000 });
+    return response.status === 200 ? ((await response.json()) as SessionHealth) : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function firstHealth(ref: SessionRef, seconds: number): Promise<SessionHealth | null> {
+  const deadline = Date.now() + seconds * 1000;
+  for (;;) {
+    const health = await sessionHealth(ref);
+    if (health !== null || Date.now() >= deadline) return health;
+    await new Promise((done) => setTimeout(done, 3000));
+  }
+}
+
+export async function daemonHealthy(ref: SessionRef): Promise<boolean> {
+  try {
+    const response = await sessionCall(ref, '/agent-device/health', { timeoutMs: 15_000 });
+    return response.status === 200 && /"ok":\s*true/.test(await response.text());
+  } catch {
+    return false;
+  }
+}
+
+interface EvidenceAnswer {
+  readonly status: number;
+  readonly error: string;
+  readonly have: number | undefined;
+}
+
+export async function sendEvidence(ref: SessionRef, manifest: HandoffManifest, paths: ReadonlyMap<string, string>, progress: (line: string) => void, retryDelayMs = 1000): Promise<void> {
+  const post = async (step: 'begin' | 'chunk' | 'commit', json: unknown): Promise<EvidenceAnswer> => {
+    try {
+      const response = await sessionCall(ref, `/__sim/evidence/${step}`, { method: 'POST', json, timeoutMs: 120_000 });
+      const body = (await response.json().catch(() => null)) as { readonly error?: string; readonly have?: number } | null;
+      return { status: response.status, error: body?.error ?? '', have: body?.have };
+    } catch (error) {
+      if (error instanceof VerifyFailure) throw error;
+      return { status: 0, error: (error as Error).message, have: undefined };
+    }
+  };
+  const refused = (what: string, answer: EvidenceAnswer) => new Error(`the session did not take ${what}: ${answer.status === 0 ? answer.error : `${answer.status} ${answer.error}`}`);
+
+  const began = await post('begin', manifest);
+  if (began.status !== 200) throw refused('the manifest', began);
+  for (const file of manifest.files) {
+    const fd = openSync(paths.get(file.name)!, 'r');
+    try {
+      const buffer = Buffer.alloc(HANDOFF_LIMITS.chunkBytes);
+      for (let offset = 0, read = 0; (read = readSync(fd, buffer, 0, buffer.length, offset)) > 0; offset += read) {
+        const data = buffer.subarray(0, read).toString('base64');
+        for (let attempt = 0; ; attempt += 1) {
+          const answer = await post('chunk', { name: file.name, offset, data });
+          const landedOnAnEarlierAttempt = answer.status === 409 && answer.have === offset + read;
+          if (answer.status === 200 || landedOnAnEarlierAttempt) break;
+          const worthAnotherTry = answer.status === 0 || answer.status >= 500;
+          if (!worthAnotherTry || attempt >= 2) throw refused(`${file.name} at byte ${offset}`, answer);
+          await sleep(retryDelayMs * (attempt + 1));
+        }
+      }
+    } finally {
+      closeSync(fd);
+    }
+    progress(`handoff ${file.name}  ${file.bytes} bytes`);
+  }
+  const committed = await post('commit', {});
+  if (committed.status !== 200) throw refused('the hand-off', committed);
+}
diff --git a/e2e-tests/src/core/remote/settings.ts b/e2e-tests/src/core/remote/settings.ts
new file mode 100644
index 000000000..2386453ab
--- /dev/null
+++ b/e2e-tests/src/core/remote/settings.ts
@@ -0,0 +1,83 @@
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Runner } from '../exec.ts';
+import { VerifyFailure, type Platform } from '../types.ts';
+import type { GitHub } from './github.ts';
+import { LIMITS, REQUEST_VERSION, RequestError, parseRequest, sha256Hex, type SessionRequest } from './protocol.ts';
+
+export interface RemoteSettings {
+  readonly platform: Platform;
+  readonly repo: string;
+  readonly workflow: string;
+  readonly sessionsDir: string;
+  readonly runner: string;
+  readonly plumbingRunner: string;
+  readonly device: string;
+  readonly idleMinutes: number;
+  readonly capMinutes: number;
+  readonly requirement: string;
+}
+
+export interface RemoteDeps {
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly runner: Runner;
+  readonly github?: () => Promise<GitHub>;
+}
+
+function minutes(env: RemoteDeps['env'], name: 'VERIFY_REMOTE_IDLE_MINUTES' | 'VERIFY_REMOTE_CAP_MINUTES', fallback: number, limits: { readonly min: number; readonly max: number }): number {
+  const raw = env[name];
+  if (raw === undefined || raw === '') return fallback;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < limits.min || value > limits.max) throw new VerifyFailure('USAGE', `${name}=${raw} is not a whole number from ${limits.min} to ${limits.max}`, `unset ${name} or set it within range`);
+  return value;
+}
+
+export function savedDriverId(settings: RemoteSettings): string | null {
+  const file = join(settings.sessionsDir, 'owner');
+  if (!existsSync(file)) return null;
+  const saved = readFileSync(file, 'utf8').trim();
+  return /^[a-f0-9]{12}$/.test(saved) ? saved : null;
+}
+
+export function driverId(settings: RemoteSettings): string {
+  const saved = savedDriverId(settings);
+  if (saved !== null) return saved;
+  const id = randomBytes(6).toString('hex');
+  mkdirSync(settings.sessionsDir, { recursive: true, mode: 0o700 });
+  writeFileSync(join(settings.sessionsDir, 'owner'), `${id}\n`, { mode: 0o600 });
+  return id;
+}
+
+export function newSessionRequest(settings: RemoteSettings, deps: RemoteDeps, input: { readonly runner?: string; readonly device: string | null; readonly sha: string | null; readonly idleMinutes?: number; readonly capMinutes?: number }): { readonly request: SessionRequest; readonly token: string } {
+  const token = randomBytes(32).toString('hex');
+  const capMinutes = input.capMinutes ?? minutes(deps.env, 'VERIFY_REMOTE_CAP_MINUTES', settings.capMinutes, LIMITS.capMinutes);
+  const draft: SessionRequest = {
+    v: REQUEST_VERSION,
+    session: `${settings.platform}${randomBytes(3).toString('hex')}`,
+    owner: driverId(settings),
+    platform: settings.platform,
+    runner: input.runner ?? settings.runner,
+    device: input.device,
+    sha: input.sha,
+    idleMinutes: Math.min(capMinutes, input.idleMinutes ?? minutes(deps.env, 'VERIFY_REMOTE_IDLE_MINUTES', settings.idleMinutes, LIMITS.idleMinutes)),
+    capMinutes,
+    tokenSha256: sha256Hex(token),
+  };
+  try {
+    return { request: parseRequest(JSON.stringify(draft)), token };
+  } catch (error) {
+    if (!(error instanceof RequestError)) throw error;
+    throw new VerifyFailure('USAGE', `the session request is not valid: ${error.message}`, 'check --runner (a runner label such as ubuntu-latest) and the device name in src/host.ts');
+  }
+}
+
+export function saveToken(settings: RemoteSettings, session: string, token: string): string {
+  const dir = join(settings.sessionsDir, session);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = join(dir, 'token');
+  writeFileSync(file, token, { mode: 0o600 });
+  return file;
+}
+
+export const forgetSession = (settings: RemoteSettings, session: string): void => rmSync(join(settings.sessionsDir, session), { recursive: true, force: true });
diff --git a/e2e-tests/src/core/remote/tunnel.ts b/e2e-tests/src/core/remote/tunnel.ts
new file mode 100644
index 000000000..9d8af784b
--- /dev/null
+++ b/e2e-tests/src/core/remote/tunnel.ts
@@ -0,0 +1,12 @@
+export const TUNNEL = {
+  allowedHost: '*.trycloudflare.com',
+  allowedSuffix: '.trycloudflare.com',
+  probeHost: 'api.trycloudflare.com',
+  binary: 'cloudflared',
+  command: (port: number): readonly string[] => ['tunnel', '--no-autoupdate', '--url', `http://127.0.0.1:${port}`],
+  hostPattern: /https:\/\/((?!api\.)[a-z0-9-]+\.trycloudflare\.com)/,
+} as const;
+
+export function isTunnelHost(host: string): boolean {
+  return /^[a-z0-9-]+(\.[a-z0-9-]+)+$/.test(host) && host.endsWith(TUNNEL.allowedSuffix) && host !== TUNNEL.probeHost;
+}
diff --git a/e2e-tests/src/core/types.ts b/e2e-tests/src/core/types.ts
index d580634e8..dac87578c 100644
--- a/e2e-tests/src/core/types.ts
+++ b/e2e-tests/src/core/types.ts
@@ -48,18 +48,20 @@ export interface ApplicationView {
   readonly name: string;
 }
 
-export type BackendKind = 'local';
+export type BackendKind = 'local' | 'remote';
+export type RemoteProvider = 'github-actions';
 
 export type SpecSelection = { readonly all: true } | { readonly selectors: readonly string[] };
 
 export type Command =
-  | { readonly verb: 'doctor'; readonly platform?: Platform; readonly backend?: BackendKind; readonly live: boolean }
-  | { readonly verb: 'up'; readonly platform?: Platform; readonly backend?: BackendKind; readonly waitSeconds: number }
+  | { readonly verb: 'doctor'; readonly platform?: Platform; readonly backend?: BackendKind; readonly runner?: string; readonly live: boolean }
+  | { readonly verb: 'up'; readonly platform?: Platform; readonly backend?: BackendKind; readonly runner?: string; readonly waitSeconds: number }
   | {
       readonly verb: 'run';
       readonly selection: SpecSelection;
       readonly platform?: Platform;
       readonly backend?: BackendKind;
+      readonly runner?: string;
       readonly grep?: string;
       readonly video: boolean;
       readonly retries: number;
@@ -110,7 +112,7 @@ export type DoctorCheckId =
   | 'node' | 'xcode' | 'jdk' | 'e2e-pins' | 'template' | 'proxy-trust'
   | 'settings' | 'build' | 'gh-attach' | 'core-drift' | 'stale-claims' | 'lane-ports'
   | 'instances' | 'clerk-api' | 'agent'
-  | 'backend'
+  | 'backend' | 'remote-env' | 'git-fetch' | 'git-push' | 'github-rest' | 'remote-commit' | 'tunnel-egress' | 'clerk-egress' | 'remote-sessions'
   | `live-${string}`;
 
 interface DoctorCheckBase {
@@ -177,13 +179,31 @@ export interface ScreenResult {
   readonly png: ScratchPath | null;
 }
 
-export interface AttachResult {
-  readonly verb: 'attach';
-  readonly commentUrl: string;
-  readonly posted: readonly EvidencePath[];
-  readonly alreadyPosted: boolean;
+export interface EvidenceSummary {
+  readonly run: RunId;
+  readonly platform: Platform;
+  readonly device: string;
+  readonly commit: string;
+  readonly passed: number;
+  readonly flaky: number;
+  readonly total: number;
 }
 
+export interface EvidenceBundle {
+  readonly pr: number;
+  readonly summary: EvidenceSummary;
+  readonly files: readonly { readonly name: string; readonly path: EvidencePath }[];
+}
+
+export interface HandOffReceipt {
+  readonly sessionRun: string;
+  readonly sessionRunUrl: string;
+}
+
+export type AttachResult =
+  | { readonly verb: 'attach'; readonly via: 'gh'; readonly prUrl: string; readonly posted: readonly EvidencePath[]; readonly alreadyPosted: boolean }
+  | ({ readonly verb: 'attach'; readonly via: 'runner'; readonly pr: number; readonly handedOff: readonly EvidencePath[]; readonly because: string } & HandOffReceipt);
+
 export type DownResult =
   | {
       readonly verb: 'down';
@@ -225,7 +245,12 @@ export interface LocalBuild extends BuiltAppBase {
   readonly source: 'local';
   readonly path: ScratchPath;
 }
-export type BuiltApp = LocalBuild;
+export interface SessionBuild extends BuiltAppBase {
+  readonly source: 'github-actions';
+  readonly path: null;
+  readonly sourceSha: string;
+}
+export type BuiltApp = LocalBuild | SessionBuild;
 export type BuildSource = BuiltApp['source'];
 
 export type DeviceName = `verify-${Platform}-${number}`;
@@ -242,7 +267,20 @@ export interface LocalLease extends LeaseBase {
   readonly deviceId: string;
   readonly claimNonce: string;
 }
-export type Lease = LocalLease;
+export interface RemoteLease extends LeaseBase {
+  readonly backend: 'remote';
+  readonly provider: RemoteProvider;
+  readonly session: string;
+  readonly providerRef: string;
+  readonly baseUrl: string;
+  readonly tokenFile: string;
+  readonly deviceId: string;
+  readonly deviceName: string;
+  readonly runner: string;
+  readonly expiresAt: string;
+  readonly builtSha: string | null;
+}
+export type Lease = LocalLease | RemoteLease;
 
 export type LedgerEntry =
   | { readonly id: string; readonly kind: 'lease-intent'; readonly platform: Platform; readonly backend: BackendKind; readonly worktree: string }
@@ -278,6 +316,7 @@ export interface EvidenceRecord {
   readonly dirty: boolean;
   readonly platform: Platform;
   readonly backend: BackendKind;
+  readonly remote: { readonly provider: RemoteProvider; readonly runner: string; readonly builtSha: string | null } | null;
   readonly device: string;
   readonly build: BuildKey;
   readonly results: readonly SpecResult[];
@@ -327,6 +366,7 @@ export interface AcquireRequest {
   readonly worktree: string;
   readonly waitSeconds: number;
   readonly app: BuiltApp;
+  readonly runner?: string;
   readonly retryWith: string;
   readonly progress: (line: string) => void;
 }
@@ -349,6 +389,7 @@ export interface Availability {
 
 export interface DoctorOptions {
   readonly live: boolean;
+  readonly runner?: string;
   readonly worktree: string;
   readonly progress: (line: string) => void;
 }
@@ -357,13 +398,15 @@ export interface DeviceBackend<L extends Lease = Lease> {
   readonly kind: BackendKind;
   readonly platform: Platform;
   availability(): Availability;
+  sourceCommit?(input: { readonly worktree: string; readonly inputs: readonly string[] }): Promise<string>;
   acquire(request: AcquireRequest): Promise<L>;
-  check(lease: L): Promise<'held' | 'lost'>;
+  check(lease: L): Promise<'held' | 'lost' | 'expiring'>;
   install(lease: L, app: BuiltApp, progress: (line: string) => void): Promise<L>;
   release(lease: L): Promise<void>;
   reapable(owner?: string): Promise<readonly L[]>;
   startRecording(lease: L, into: EvidencePath): Promise<Recording>;
   logs(lease: L, since: Date, extraPredicate?: string): Promise<string>;
+  handOffEvidence?(lease: L, bundle: EvidenceBundle, progress: (line: string) => void): Promise<HandOffReceipt>;
   describe(lease: L): string;
   readonly requirement: string;
   doctorChecks(options: DoctorOptions): Promise<{ readonly toolchain: readonly DoctorCheck[]; readonly device: readonly DoctorCheck[] }>;
diff --git a/e2e-tests/src/core/verbs.ts b/e2e-tests/src/core/verbs.ts
index 330b90b3e..4c2a6c36c 100644
--- a/e2e-tests/src/core/verbs.ts
+++ b/e2e-tests/src/core/verbs.ts
@@ -1,5 +1,5 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { isOrphaned, readClaims } from './claims.ts';
 import { check, type AppliedInstance, type Instances } from './instances/instances.ts';
 import { STANDARD, SettingsRefused, planGroups, readSpecText, settingsFileOf, sourceHash, straySettingsFile, type SettingsGroup } from './instances/settings.ts';
@@ -20,7 +20,7 @@ import { protectGitHubTokens, reportToGitHub } from './github-report.ts';
 import { isRunning, type Runner } from './exec.ts';
 import { ledgerAgentDeviceDaemon, processesIn, readDaemonInfo, stopProcesses, type ProcessEntry } from './ledgers.ts';
 import { SHARED_ROOTS, manifestDrift } from './manifest.ts';
-import { missingAttach, postToPullRequest } from './publish.ts';
+import { CannotPostHere, chooseFiles, missingAttach, postToPullRequest, summarize } from './publish.ts';
 import { redact } from '../../specs/support/secret.ts';
 import { count } from './state.ts';
 import { newEntryId, parseRunId, type Workspace } from './workspace.ts';
@@ -35,8 +35,10 @@ import {
   type DoctorCheck,
   type DoctorReport,
   type DownResult,
+  type EvidenceBundle,
   type EvidencePath,
   type EvidenceRecord,
+  type HandOffReceipt,
   type HostAdapter,
   type InstanceView,
   type Lease,
@@ -87,8 +89,12 @@ const platformOf = (host: HostAdapter, platform: Platform | undefined): Platform
   return chosen;
 };
 
-function chooseBackend(deps: Deps, platform: Platform, command: { readonly backend?: BackendKind }): BackendChoice {
-  return selectBackend(deps.host, platform, command.backend, deps.workspace.readLease(platform));
+function chooseBackend(deps: Deps, platform: Platform, command: { readonly backend?: BackendKind; readonly runner?: string }): BackendChoice {
+  const choice = selectBackend(deps.host, platform, command.backend, deps.workspace.readLease(platform));
+  if (command.runner !== undefined && choice.backend.kind === 'local') {
+    throw new VerifyFailure('USAGE', '--runner names a CI runner and the local backend has none', 'drop --runner, or pass --backend remote');
+  }
+  return choice;
 }
 
 function readJson(file: string): Record<string, unknown> | null {
@@ -98,6 +104,7 @@ function readJson(file: string): Record<string, unknown> | null {
 export async function doctor(deps: Deps, command: Extract<Command, { verb: 'doctor' }>): Promise<DoctorReport> {
   const { host, workspace, runner } = deps;
   const platform = platformOf(host, command.platform);
+  const held = workspace.readLease(platform);
   const choice = chooseBackend(deps, platform, command);
   const { backend } = choice;
   const packageDir = workspace.packageDir;
@@ -107,6 +114,7 @@ export async function doctor(deps: Deps, command: Extract<Command, { verb: 'doct
   checks.push(check('node', supportsNode(node), node, 'install Node 24.8.0 or newer on 24 (nvm install 24)'));
   const backendChecks = await backend.doctorChecks({
     live: command.live,
+    ...(command.runner === undefined ? {} : { runner: command.runner }),
     worktree: workspace.worktree,
     progress: deps.progress,
   });
@@ -131,14 +139,19 @@ export async function doctor(deps: Deps, command: Extract<Command, { verb: 'doct
 
   const key = await computeBuildKey(host, platform, backend.kind, workspace.worktree);
   const up = ['{cli} up', ...(host.platforms.length > 1 ? [`--platform ${platform}`] : []), ...(command.backend === undefined ? [] : [`--backend ${command.backend}`])].join(' ');
-  const built = readBuiltApp(workspace, key);
-  checks.push(check('build', built !== null, built === null ? `no ${host.appId(platform)} build for ${key}` : `${key} at ${built.path}`, up));
+  if (backend.sourceCommit === undefined) {
+    const built = readBuiltApp(workspace, key);
+    checks.push(check('build', built !== null, built === null ? `no ${host.appId(platform)} build for ${key}` : `${key} at ${built.path}`, up));
+  } else {
+    const onSession = held !== null && held.backend === 'remote' && held.installedBuild === key;
+    checks.push(check('build', onSession, onSession ? `${key} (commit ${held.builtSha?.slice(0, 12) ?? 'unknown'}) is on the session's device` : `no session holds a ${host.appId(platform)} build for ${key}`, `commit and push, then ${up}`));
+  }
 
   const noAttach = await missingAttach(runner);
   checks.push(
     noAttach === null
-      ? check('gh-attach', true, 'gh pr comment supports --attach', '')
-      : { id: 'gh-attach', ok: true, state: 'warning', detail: `${noAttach.why}, so \`{cli} attach\` cannot post a run's video and screenshots from this machine`, fix: noAttach.fix },
+      ? check('gh-attach', true, 'gh pr edit supports --attach', '')
+      : { id: 'gh-attach', ok: true, state: 'warning', detail: `${noAttach.why}, so \`{cli} attach\` cannot put a run's video and screenshots in a pull request description from this machine`, fix: noAttach.fix },
   );
 
   const stale = readClaims(workspace.claimsDir, platform).filter(isOrphaned);
@@ -178,7 +191,7 @@ export async function up(deps: Deps, command: Extract<Command, { verb: 'up' }>):
   chooseBackend(deps, platform, command);
   return deps.workspace.withAcquireLock(platform, async (lock) => {
     const [leased, instances] = await leaseWithInstances(deps, { willChange: false }, () =>
-      ensureLease(lock, command.backend, deps.workspace, deps.host, { waitSeconds: command.waitSeconds, progress: deps.progress, instances: deps.instances, retryWith: '{cli} up --wait <seconds>' }),
+      ensureLease(lock, command.backend, deps.workspace, deps.host, { waitSeconds: command.waitSeconds, ...(command.runner === undefined ? {} : { runner: command.runner }), progress: deps.progress, instances: deps.instances, retryWith: '{cli} up --wait <seconds>' }),
     );
     const outcome = { ...leased, devServer: await startRuntime(deps, leased.lease), instances };
     return { verb: 'up', leases: [outcome.view], builds: [outcome.build], instances: outcome.instances };
@@ -249,7 +262,7 @@ export async function leaseForRun<T>(deps: Deps, platform: Platform, command: Ex
     deviceWait,
     async (lock) => {
       const [leased, up] = await leaseWithInstances(deps, instances, () =>
-        ensureLease(lock, command.backend, deps.workspace, deps.host, { waitSeconds: command.waitSeconds, progress: deps.progress, instances: deps.instances, retryWith }),
+        ensureLease(lock, command.backend, deps.workspace, deps.host, { waitSeconds: command.waitSeconds, ...(command.runner === undefined ? {} : { runner: command.runner }), progress: deps.progress, instances: deps.instances, retryWith }),
       );
       const outcome: RuntimeOutcome = { ...leased, devServer: await startRuntime(deps, leased.lease), instances: up };
       deps.progress(leaseLine(outcome.view));
@@ -466,6 +479,7 @@ export async function runVerb(deps: Deps, command: Extract<Command, { verb: 'run
         dirty: git.dirty,
         platform,
         backend: lease.backend,
+        remote: lease.backend === 'remote' ? { provider: lease.provider, runner: lease.runner, builtSha: lease.builtSha } : null,
         device: outcome.view.device,
         build: outcome.app.key,
         results,
@@ -566,7 +580,32 @@ export async function attach(deps: Deps, command: Extract<Command, { verb: 'atta
   if (!existsSync(dir)) throw new VerifyFailure('USAGE', `no run ${run} in ${deps.workspace.root}/runs`, 'pass a run id that `{cli} run` printed');
   const record = readRecord(dir);
   const publishable = assertPublishable(record, loggedUserIds(dir));
-  return postToPullRequest(publishable, dir, deps.host, command.pr, command.screenshots, deps.runner);
+  try {
+    return await postToPullRequest(publishable, dir, deps.host, command.pr, command.screenshots, deps.runner);
+  } catch (error) {
+    if (!(error instanceof CannotPostHere) || record.backend !== 'remote') throw error;
+    const unattached = `name run ${run} in the PR and say that the evidence was not attached`;
+    const session = sessionToHandOffTo(deps, record);
+    if (typeof session === 'string') throw new VerifyFailure('NOT_READY', `${error.message}, and ${session}`, `${unattached}; to attach it, {cli} run again and {cli} attach before {cli} down`);
+    const { videos, shots } = chooseFiles(publishable, command.screenshots);
+    const files = [...videos, ...shots.map((shot) => shot.path)];
+    try {
+      const receipt = await session.handOff({ pr: command.pr, summary: summarize(publishable), files: files.map((path) => ({ name: basename(path), path })) }, deps.progress);
+      return { verb: 'attach', via: 'runner', pr: command.pr, handedOff: files, because: error.why, ...receipt };
+    } catch (failure) {
+      if (!(failure instanceof VerifyFailure)) throw failure;
+      throw new VerifyFailure(failure.code, `${error.message}, and ${failure.message}`, `${failure.fix}; until then, ${unattached}`);
+    }
+  }
+}
+
+function sessionToHandOffTo(deps: Deps, record: EvidenceRecord): { readonly handOff: (bundle: EvidenceBundle, progress: (line: string) => void) => Promise<HandOffReceipt> } | string {
+  const lease = deps.workspace.readLease(record.platform);
+  if (lease === null || lease.backend !== 'remote') return `this worktree holds no session now, so nothing can take the evidence to a runner`;
+  if (Date.parse(record.startedAt) < Date.parse(lease.acquiredAt)) return `run ${record.run} ran before the session that is up now started`;
+  const backend = backendFor(deps.host, record.platform, 'remote');
+  const handOffEvidence = backend.handOffEvidence?.bind(backend);
+  return handOffEvidence === undefined ? `the ${record.platform} remote backend takes no evidence` : { handOff: (bundle, progress) => handOffEvidence(lease, bundle, progress) };
 }
 
 interface DownPlan {
@@ -576,7 +615,7 @@ interface DownPlan {
   readonly staleIntents: readonly string[];
 }
 
-const leaseIdentity = (lease: Lease): string => `local:${lease.claimNonce}`;
+const leaseIdentity = (lease: Lease): string => (lease.backend === 'local' ? `local:${lease.claimNonce}` : `remote:${lease.session}`);
 
 async function planDown(deps: Deps, command: Extract<Command, { verb: 'down' }>): Promise<DownPlan> {
   const { host, workspace } = deps;
diff --git a/e2e-tests/src/core/workspace.ts b/e2e-tests/src/core/workspace.ts
index 7dc69c294..7a5894719 100644
--- a/e2e-tests/src/core/workspace.ts
+++ b/e2e-tests/src/core/workspace.ts
@@ -86,6 +86,11 @@ function parseLease(text: string, file: string): Lease {
     if (r.deviceName !== `verify-${r.platform}-${r.slot}`) throw bad();
     return { ...(r as object), installedBuild } as Lease;
   }
+  if (r.backend === 'remote') {
+    const strings = ['provider', 'session', 'providerRef', 'baseUrl', 'tokenFile', 'deviceId', 'deviceName', 'runner', 'expiresAt'];
+    if (strings.some((name) => typeof r[name] !== 'string')) throw bad();
+    return { ...(r as object), installedBuild, builtSha: typeof r.builtSha === 'string' ? r.builtSha : null } as Lease;
+  }
   throw bad();
 }
 
diff --git a/e2e-tests/src/host-app.ts b/e2e-tests/src/host-app.ts
index 54a55526b..150d5cd6a 100644
--- a/e2e-tests/src/host-app.ts
+++ b/e2e-tests/src/host-app.ts
@@ -1,5 +1,8 @@
 import { join } from 'node:path';
+import type { CommandLine } from './core/exec.ts';
 
 export const APK = join('e2e', 'build', 'outputs', 'apk', 'debug', 'e2e-debug.apk');
 
 export const ASSEMBLE_HOST = [':e2e:assembleDebug', '--console=plain', '--quiet'] as const;
+
+export const assembleHost = (): CommandLine => ({ command: './gradlew', args: [...ASSEMBLE_HOST] });
diff --git a/e2e-tests/src/host.ts b/e2e-tests/src/host.ts
index 49c0047d7..9f518db88 100644
--- a/e2e-tests/src/host.ts
+++ b/e2e-tests/src/host.ts
@@ -3,12 +3,14 @@ import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { run } from './core/exec.ts';
 import { withoutClerkKeys } from './core/keys.ts';
+import { remoteBackend } from './core/remote/backend.ts';
 import { VerifyFailure, type HostAdapter, type ScratchPath } from './core/types.ts';
 import { localAndroidBackend } from './platform/android/local.ts';
-import { resolveJavaHome, sdkRoot } from './platform/android/sdk.ts';
+import { AVD_NAME, resolveJavaHome, sdkRoot } from './platform/android/sdk.ts';
 import { APK, ASSEMBLE_HOST } from './host-app.ts';
 import { APP_ID, app } from '../specs/app.ts';
 
+const PACKAGE_DIR = fileURLToPath(new URL('../', import.meta.url));
 const WORKTREE = fileURLToPath(new URL('../../', import.meta.url));
 const GITHUB_REPO = 'clerk/clerk-android';
 
@@ -32,5 +34,19 @@ export const host: HostAdapter = {
     copyFileSync(join(WORKTREE, APK), path);
     return { platform, key, appId: APP_ID, path, source: 'local' };
   },
-  backends: [localAndroidBackend()],
+  backends: [
+    localAndroidBackend(),
+    remoteBackend({
+      platform: 'android',
+      repo: GITHUB_REPO,
+      workflow: 'verify-remote.yml',
+      sessionsDir: join(PACKAGE_DIR, '.verify', 'remote'),
+      runner: 'ubuntu-24.04',
+      plumbingRunner: 'ubuntu-latest',
+      device: AVD_NAME,
+      idleMinutes: 15,
+      capMinutes: 60,
+      requirement: 'a pushed branch and access to GitHub Actions on clerk/clerk-android',
+    }),
+  ],
 };
diff --git a/e2e-tests/src/platform/android/emulator.ts b/e2e-tests/src/platform/android/emulator.ts
index b16ae0511..d7b0c956c 100644
--- a/e2e-tests/src/platform/android/emulator.ts
+++ b/e2e-tests/src/platform/android/emulator.ts
@@ -1,3 +1,4 @@
+import type { CommandLine } from '../../core/exec.ts';
 import { AVD_NAME } from './sdk.ts';
 
 export const RECORD_SIZE = '720x1608';
@@ -6,6 +7,7 @@ export const LOG_FILTER = ['ClerkVerify:V', 'ClerkLog:V', 'OkHttp:V', 'ReactNati
 const SOFTWARE_GPU = ['-gpu', 'swiftshader_indirect'];
 const WITHOUT_THE_180_SECOND_CAP = ['--time-limit', '0'];
 const SHELL_WRITABLE_BEFORE_STORAGE_MOUNTS = '/data/local/tmp';
+const INTERRUPT_ON_THE_DEVICE_SO_THE_MP4_GETS_ITS_MOOV_ATOM = 'pkill -INT screenrecord';
 
 export function emulatorArgs(port: number, os: NodeJS.Platform): readonly string[] {
   return ['-avd', AVD_NAME, '-read-only', '-no-window', '-no-audio', '-no-boot-anim', ...(os === 'linux' ? SOFTWARE_GPU : []), '-port', String(port)];
@@ -42,4 +44,19 @@ export const logcatArgs = (since: Date, extraPredicate?: string | null): readonl
 
 export const recordingOnDevice = (name: string): string => `${SHELL_WRITABLE_BEFORE_STORAGE_MOUNTS}/verify-${name}.mp4`;
 
+export const LANE_READY = 'lane-ready';
+export const LANE_FAILED = 'lane-failed';
+
+export const waitForLane = (work: string): CommandLine => ({
+  command: 'sh',
+  args: ['-c', `until [ -f "$0/${LANE_READY}" ]; do if [ -f "$0/${LANE_FAILED}" ]; then echo "the emulator did not boot: $(cat "$0/${LANE_FAILED}")"; exit 1; fi; sleep 1; done`, work],
+});
+
 export const screenrecordArgs = (deviceFile: string): readonly string[] => ['shell', 'screenrecord', '--size', RECORD_SIZE, ...WITHOUT_THE_180_SECOND_CAP, deviceFile];
+
+export const stopScreenrecordArgs: readonly string[] = ['shell', `${INTERRUPT_ON_THE_DEVICE_SO_THE_MP4_GETS_ITS_MOOV_ATOM}; i=0; while pidof screenrecord > /dev/null && [ $i -lt 100 ]; do sleep 0.2; i=$((i+1)); done`];
+
+export const collectRecordingArgs = (deviceFile: string, file: string): readonly (readonly string[])[] => [
+  ['pull', deviceFile, file],
+  ['shell', 'rm', '-f', deviceFile],
+];
diff --git a/e2e-tests/src/platform/android/session-device.ts b/e2e-tests/src/platform/android/session-device.ts
new file mode 100644
index 000000000..663e5d52d
--- /dev/null
+++ b/e2e-tests/src/platform/android/session-device.ts
@@ -0,0 +1,20 @@
+import type { SessionDeviceFactory } from '../../core/remote/protocol.ts';
+import { APK, assembleHost } from '../../host-app.ts';
+import { collectRecordingArgs, installArgs, logcatArgs, recordingOnDevice, screenrecordArgs, stopScreenrecordArgs, waitForLane } from './emulator.ts';
+
+const RECORDING = recordingOnDevice('session');
+
+const sessionDevice: SessionDeviceFactory = ({ id: serial }) => {
+  const adb = (args: readonly string[]) => ({ command: 'adb', args: ['-s', serial, ...args] });
+  return {
+    build: (work) => [assembleHost(), waitForLane(work), adb(installArgs(APK))],
+    record: {
+      start: () => adb(screenrecordArgs(RECORDING)),
+      stop: () => [adb(stopScreenrecordArgs)],
+      collect: (file) => collectRecordingArgs(RECORDING, file).map(adb),
+    },
+    logs: (since, predicate) => adb(logcatArgs(since, predicate)),
+  };
+};
+
+export default sessionDevice;
diff --git a/e2e-tests/src/platform/android/session-lane.ts b/e2e-tests/src/platform/android/session-lane.ts
new file mode 100644
index 000000000..aaa9b5cf1
--- /dev/null
+++ b/e2e-tests/src/platform/android/session-lane.ts
@@ -0,0 +1,27 @@
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { BuiltApp } from '../../core/types.ts';
+import { LANE_READY, LANE_FAILED } from './emulator.ts';
+import { laneSerial, localAndroidBackend } from './local.ts';
+
+const SLOT = 1;
+
+if (import.meta.main) {
+  const [command, work = '.'] = process.argv.slice(2);
+  if (command === 'serial') {
+    console.log(laneSerial(SLOT));
+  } else if (command === 'boot') {
+    try {
+      const lease = await localAndroidBackend().acquire({ platform: 'android', worktree: process.cwd(), waitSeconds: 0, app: null as unknown as BuiltApp, retryWith: '', progress: (line) => console.log(line) });
+      if (lease.deviceId !== laneSerial(SLOT)) throw new Error(`the lane came up as ${lease.deviceId}, not ${laneSerial(SLOT)}`);
+      writeFileSync(join(work, LANE_READY), `${lease.deviceId}\n`);
+    } catch (error) {
+      writeFileSync(join(work, LANE_FAILED), `${(error as Error).message}\n`);
+      console.error((error as Error).message);
+      process.exit(1);
+    }
+  } else {
+    console.error('usage: session-lane.ts serial | boot <work-dir>');
+    process.exit(2);
+  }
+}
diff --git a/e2e-tests/test/android.test.ts b/e2e-tests/test/android.test.ts
index 4113cffe7..59305e59f 100644
--- a/e2e-tests/test/android.test.ts
+++ b/e2e-tests/test/android.test.ts
@@ -9,7 +9,7 @@ import { describe, it } from 'node:test';
 import { isRunning, run } from '../src/core/exec.ts';
 import type { EvidencePath, LocalLease } from '../src/core/types.ts';
 import { readClaim, takeSlot } from '../src/core/claims.ts';
-import { LOG_FILTER, RECORD_SIZE, emulatorArgs, laneSettingsCommand, laneSettingsHold, laneSettingsReadCommand, logFilter, logcatSince } from '../src/platform/android/emulator.ts';
+import { LANE_FAILED, LANE_READY, LOG_FILTER, RECORD_SIZE, collectRecordingArgs, emulatorArgs, laneSettingsCommand, laneSettingsHold, laneSettingsReadCommand, logFilter, logcatSince, stopScreenrecordArgs, waitForLane } from '../src/platform/android/emulator.ts';
 import { lanePort, localAndroidBackend, laneSerial, parseAdbDevices, startScreenrecord, terminateGroup } from '../src/platform/android/local.ts';
 import { ensureLaneAvd, jdkCheck, localAvailability, resolveJavaHome, sdkRoot, systemImage, type Machine } from '../src/platform/android/sdk.ts';
 
@@ -523,3 +523,29 @@ describe('whether this machine can run the emulator', () => {
     assert.ok(unset.at(join(unset.home, '.android', 'avd')));
   });
 });
+
+describe('what a remote session runs on its emulator', () => {
+  it('holds the install until the lane boot has finished, and fails the build with the boot\'s own error', async () => {
+    const work = mkdtempSync(join(tmpdir(), 'verify-recipe-'));
+    const wait = waitForLane(work);
+    const waiting = run(wait.command, wait.args);
+    await new Promise((resolve) => setTimeout(resolve, 300));
+    writeFileSync(join(work, LANE_READY), 'emulator-5560\n');
+    assert.equal((await waiting).code, 0);
+
+    const failed = mkdtempSync(join(tmpdir(), 'verify-recipe-'));
+    writeFileSync(join(failed, LANE_FAILED), 'no KVM here\n');
+    const refuse = waitForLane(failed);
+    const result = await run(refuse.command, refuse.args);
+    assert.equal(result.code, 1);
+    assert.match(result.stdout, /the emulator did not boot: no KVM here/);
+  });
+
+  it('stops screenrecord on the device and waits for it to exit, then pulls the file and deletes it there', () => {
+    assert.match(stopScreenrecordArgs.join(' '), /^shell pkill -INT screenrecord; .*while pidof screenrecord/);
+    assert.deepEqual(collectRecordingArgs('/data/local/tmp/verify-session.mp4', '/work/recording.mp4'), [
+      ['pull', '/data/local/tmp/verify-session.mp4', '/work/recording.mp4'],
+      ['shell', 'rm', '-f', '/data/local/tmp/verify-session.mp4'],
+    ]);
+  });
+});
diff --git a/e2e-tests/test/cli.test.ts b/e2e-tests/test/cli.test.ts
index b39bd2eca..5bc681792 100644
--- a/e2e-tests/test/cli.test.ts
+++ b/e2e-tests/test/cli.test.ts
@@ -20,8 +20,10 @@ describe('parseArgv', () => {
   it('parses every verb', () => {
     assert.deepEqual(parseArgv(['doctor']).command, { verb: 'doctor', live: false });
     assert.deepEqual(parseArgv(['doctor', '--platform', 'ios', '--backend', 'local']).command, { verb: 'doctor', platform: 'ios', backend: 'local', live: false });
+    assert.deepEqual(parseArgv(['doctor', '--backend', 'remote', '--live', '--runner', 'ubuntu-latest']).command, { verb: 'doctor', backend: 'remote', runner: 'ubuntu-latest', live: true });
     assert.deepEqual(parseArgv(['up', '--backend', 'auto']).command, { verb: 'up', waitSeconds: 0 });
-    assert.throws(() => parseArgv(['up', '--backend', 'elsewhere']), /auto or local/);
+    assert.throws(() => parseArgv(['up', '--backend', 'elsewhere']), /auto, local, or remote/);
+    assert.throws(() => parseArgv(['up', '--runner', 'bad label; rm']), /runner label/);
     assert.deepEqual(parseArgv(['up', '--wait', '300']).command, { verb: 'up', waitSeconds: 300 });
     assert.deepEqual(parseArgv(['up']).command, { verb: 'up', waitSeconds: 0 });
     assert.deepEqual(parseArgv(['run', 'auth-start', 'sign-up/request-code']).command, {
@@ -69,6 +71,7 @@ describe('parseArgv', () => {
       ['frobnicate'],
       ['Doctor'],
       ['doctor', '--wait', '3'],
+      ['doctor', '--backend', 'remote', '--runner', 'ubuntu-latest'],
       ['up', '--png'],
       ['run'],
       ['run', 'x', '--all'],
@@ -168,7 +171,7 @@ describe('doctor output', () => {
     backend: { ios: 'local' },
     checks: [
       { id: 'node', ok: true, detail: '24.15.0' },
-      { id: 'gh-attach', ok: true, state: 'warning', detail: 'gh pr comment has no --attach', fix: 'install one that has' },
+      { id: 'gh-attach', ok: true, state: 'warning', detail: 'gh pr edit has no --attach', fix: 'install one that has' },
       { id: 'live-session', ok: true, state: 'not-run', detail: 'not run: needs --live' },
     ],
   };
@@ -176,7 +179,7 @@ describe('doctor output', () => {
   it('labels a warning and a check that was not run, and neither fails doctor', () => {
     let out = '';
     createOutput(false, '/tmp', 'bin/control-x', { write: (t: string) => (out += t) }, { write: () => true }).result(report);
-    assert.deepEqual(out.trimEnd().split('\n'), ['ok    node          24.15.0', 'warn  gh-attach     gh pr comment has no --attach', '      fix: install one that has', 'skip  live-session  not run: needs --live']);
+    assert.deepEqual(out.trimEnd().split('\n'), ['ok    node          24.15.0', 'warn  gh-attach     gh pr edit has no --attach', '      fix: install one that has', 'skip  live-session  not run: needs --live']);
     assert.equal(exitCodeFor(report), 0);
   });
 
diff --git a/e2e-tests/test/device-command.test.ts b/e2e-tests/test/device-command.test.ts
index 4a13b6ed2..6898d6bd8 100644
--- a/e2e-tests/test/device-command.test.ts
+++ b/e2e-tests/test/device-command.test.ts
@@ -1,11 +1,38 @@
 import '../testing/git-env.ts';
 import assert from 'node:assert/strict';
-import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, readdirSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { describe, it } from 'node:test';
+import { afterEach, describe, it } from 'node:test';
 import { deviceCommand, deviceToolCommand, type CommandRunner } from '../specs/support/device.ts';
 import type { Device } from '../specs/support/inputs.ts';
+import { run } from '../src/core/exec.ts';
+import { coreVersion } from '../src/core/manifest.ts';
+import { remoteBackend } from '../src/core/remote/backend.ts';
+import type { GitHub } from '../src/core/remote/github.ts';
+import type { SessionHealth } from '../src/core/remote/protocol.ts';
+import { VerifyFailure, type RemoteLease } from '../src/core/types.ts';
+
+const realFetch = globalThis.fetch;
+afterEach(() => void (globalThis.fetch = realFetch));
+
+function remoteLease(platform: 'ios' | 'android'): RemoteLease {
+  const tokenFile = join(mkdtempSync(join(tmpdir(), 'verify-command-')), 'token');
+  writeFileSync(tokenFile, 'd'.repeat(64));
+  return { backend: 'remote', provider: 'github-actions', platform, session: `${platform}abc123`, providerRef: '7', baseUrl: 'https://quick-fox.trycloudflare.com', tokenFile, deviceId: 'emulator-5554', deviceName: 'Pixel', runner: 'linux', expiresAt: new Date(Date.now() + 3_600_000).toISOString(), builtSha: null, acquiredAt: '', installedBuild: null };
+}
+
+function tunnel(reply: (path: string) => { status: number; body: unknown }): { readonly calls: { path: string; method: string; authorization: string | null; body: unknown }[] } {
+  const calls: { path: string; method: string; authorization: string | null; body: unknown }[] = [];
+  globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const url = new URL(String(input));
+    assert.equal(url.host, 'quick-fox.trycloudflare.com');
+    calls.push({ path: url.pathname, method: init?.method ?? 'GET', authorization: new Headers(init?.headers).get('authorization'), body: typeof init?.body === 'string' ? JSON.parse(init.body) : null });
+    const { status, body } = reply(url.pathname);
+    return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
+  }) as typeof fetch;
+  return { calls };
+}
 
 describe('the device tool', () => {
   it('is adb on the device for shell and for reverse to a TCP port, and nothing that reaches the files or sockets of the machine adb runs on', () => {
@@ -50,3 +77,63 @@ describe('deviceCommand', () => {
     await assert.rejects(deviceCommand(device, 'android', ['pull', '/sdcard/x', 'x'], { runner: async () => assert.fail('ran') }), /no android device command starts with pull/);
   });
 });
+
+describe('a session started from another core', () => {
+  const health = (core: string | undefined): SessionHealth =>
+    ({ core, device: { id: 'emulator-5554', name: 'Pixel', ready: true }, daemon: true, build: { state: 'none' }, capAt: '', ending: null }) as SessionHealth;
+  const backend = () =>
+    remoteBackend(
+      { platform: 'android', repo: 'clerk/clerk-android', workflow: 'verify-remote.yml', sessionsDir: mkdtempSync(join(tmpdir(), 'verify-core-')), runner: 'linux', plumbingRunner: 'ubuntu-latest', device: 'Pixel', idleMinutes: 15, capMinutes: 60, requirement: '' },
+      { env: {}, runner: run, github: async () => assert.fail('a session that answers is not looked up at GitHub') },
+    );
+
+  it('is held when its agent has this checkout\'s core', async () => {
+    tunnel(() => ({ status: 200, body: health(coreVersion()) }));
+    assert.equal(await backend().check(remoteLease('android')), 'held');
+  });
+
+  it('is refused, not renewed, when its agent has another core, with the fix that gets both onto one commit', async () => {
+    for (const core of ['0123456789ab', undefined]) {
+      tunnel(() => ({ status: 200, body: health(core) }));
+      await assert.rejects(backend().check(remoteLease('android')), (error: VerifyFailure) => error.code === 'NOT_READY' && error.message.includes(coreVersion()) && error.fix === 'commit and push the changes to the files MANIFEST lists, then {cli} down and {cli} up');
+    }
+  });
+});
+
+describe('acquiring a session whose agent has another core', () => {
+  it('asks that session to stop through its tunnel and keeps no lease or token', async () => {
+    const sessionsDir = mkdtempSync(join(tmpdir(), 'verify-acquire-'));
+    const tunnelCalls: string[] = [];
+    globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+      const url = new URL(String(input));
+      tunnelCalls.push(`${init?.method ?? 'GET'} ${url.host}${url.pathname}`);
+      const body = url.pathname === '/__sim/stop' ? { ok: true } : ({ core: '0123456789ab', device: { id: 'emulator-5560', name: 'Pixel', ready: false }, daemon: false, build: { state: 'none' }, capAt: '', ending: null } satisfies SessionHealth);
+      return new Response(JSON.stringify(body), { status: 200 });
+    }) as typeof fetch;
+    const hubCalls: string[] = [];
+    const hub: GitHub = {
+      repo: 'clerk/clerk-android',
+      workflow: 'verify-remote.yml',
+      tokenSource: 'none',
+      async api(method, path) {
+        hubCalls.push(`${method} ${path}`);
+        if (path.endsWith('/dispatches')) return { status: 200, json: { workflow_run_id: 9 }, headers: new Headers() };
+        if (path.includes('/jobs')) return { status: 200, json: { jobs: [{ name: 'session', status: 'in_progress', conclusion: null, steps: [{ name: 'verify-remote tunnel quick-fox.trycloudflare.com', status: 'completed', conclusion: 'success' }] }] }, headers: new Headers() };
+        const stopped = tunnelCalls.some((call) => call.endsWith('/__sim/stop'));
+        return { status: 200, json: { status: stopped ? 'completed' : 'in_progress', conclusion: stopped ? 'success' : null, html_url: 'https://github.com/x' }, headers: new Headers() };
+      },
+    };
+    const backend = remoteBackend(
+      { platform: 'android', repo: 'clerk/clerk-android', workflow: 'verify-remote.yml', sessionsDir, runner: 'linux', plumbingRunner: 'ubuntu-latest', device: 'Pixel', idleMinutes: 15, capMinutes: 60, requirement: '' },
+      { env: {}, runner: async () => ({ code: 0, stdout: 'my-branch\n', stderr: '' }), github: async () => hub },
+    );
+    const progress: string[] = [];
+    await assert.rejects(
+      backend.acquire({ platform: 'android', worktree: '/w', waitSeconds: 0, app: { sourceSha: 'f'.repeat(40) } as never, retryWith: '', progress: (line) => progress.push(line) }),
+      (error: VerifyFailure) => error.code === 'NOT_READY' && error.message.includes('0123456789ab') && error.fix.includes('{cli} down and {cli} up'),
+    );
+    assert.deepEqual(tunnelCalls, ['GET quick-fox.trycloudflare.com/__sim/health', 'POST quick-fox.trycloudflare.com/__sim/stop']);
+    assert.equal(hubCalls.some((call) => call.endsWith('/cancel')), false, 'a session that stops when asked is not cancelled');
+    assert.deepEqual(readdirSync(sessionsDir), ['owner'], 'the token of the session that was ended is gone');
+  });
+});
diff --git a/e2e-tests/test/evidence.test.ts b/e2e-tests/test/evidence.test.ts
index dc518e413..152f8efb4 100644
--- a/e2e-tests/test/evidence.test.ts
+++ b/e2e-tests/test/evidence.test.ts
@@ -8,12 +8,12 @@ import { describe, it } from 'node:test';
 import { newTestEmail } from '../specs/support/clerk.ts';
 import { assertPublishable, loggedUserIds, sealEvidence } from '../src/core/evidence.ts';
 import type { Runner } from '../src/core/exec.ts';
-import { commentBody, postToPullRequest } from '../src/core/publish.ts';
+import { evidenceBlock, evidenceMarkers, postToPullRequest, summarize, withEvidenceBlock } from '../src/core/publish.ts';
 import { Secret } from '../specs/support/secret.ts';
 import { attach } from '../src/core/verbs.ts';
 import { newRunId } from '../specs/support/inputs.ts';
 import { openWorkspace } from '../src/core/workspace.ts';
-import type { BuildKey, EvidencePath, EvidenceRecord, HostAdapter, RunId } from '../src/core/types.ts';
+import type { BuildKey, EvidencePath, EvidenceRecord, EvidenceSummary, HostAdapter, RunId } from '../src/core/types.ts';
 
 const OWN_USER = 'user_own';
 
@@ -30,6 +30,7 @@ function partialRecord(dir: EvidencePath, run: RunId): Omit<EvidenceRecord, 'sea
     dirty: false,
     platform: 'ios',
     backend: 'local',
+    remote: null,
     device: 'verify-ios-1',
     build: 'ios-000000000000' as BuildKey,
     results: [
@@ -116,14 +117,153 @@ describe('assertPublishable', () => {
   });
 });
 
-describe('the comment attach posts', () => {
+describe('the evidence block of a pull request description', () => {
+  const summary: EvidenceSummary = { run: 'r20261008-052713-253e' as RunId, platform: 'ios', device: 'iPhone Air on xcode-27', commit: '0f50b597b1c2d3e4f5a60718293a4b5c6d7e8f90', passed: 3, flaky: 0, total: 3 };
+  const media = [{ alt: 'video.mp4', ref: './video.mp4' }, { alt: 'profile', ref: './profile.png' }];
+  const block = evidenceBlock(summary, media);
+
+  it('is one line built from the run, then each file alone in its own paragraph, between the markers of its platform', () => {
+    assert.equal(
+      block,
+      [
+        '<!-- verify-evidence:ios -->',
+        '',
+        'verify run `r20261008-052713-253e` on `iPhone Air on xcode-27` at `0f50b597b1c2`, 3 of 3 passed.',
+        '',
+        '![video.mp4](./video.mp4)',
+        '',
+        '![profile](./profile.png)',
+        '',
+        '<!-- /verify-evidence:ios -->',
+      ].join('\n'),
+    );
+    assert.match(evidenceBlock({ ...summary, passed: 1, flaky: 1, total: 2 }, []), /, 1 of 2 passed, 1 flaky \(passed only on a retry\)\.$/m);
+  });
+
   it('counts a test that passed only on a retry apart from the passed ones', () => {
     const { dir, run } = runDir();
     const base = partialRecord(dir, run);
     const record = sealEvidence(dir, { ...base, results: [base.results[0]!, { ...base.results[0]!, title: 'b', status: 'flaky', attempts: 2, error: 'tap failed' }] }, []);
-    const body = commentBody(assertPublishable(record, [OWN_USER]));
-    assert.match(body, /, 1 of 2 passed, 1 flaky \(passed only on a retry\)\.$/m);
-    assert.match(body, /^- flaky: `specs\/explored\/a\.e2e\.ts` b$/m);
+    assert.deepEqual(summarize(assertPublishable(record, [OWN_USER])), { run, platform: 'ios', device: 'verify-ios-1', commit: 'abc', passed: 1, flaky: 1, total: 2 });
+  });
+
+  it('goes after a description that has no block, and leaves that description as it was', () => {
+    for (const body of ['## Summary\r\n\r\nFixes the button.  \r\n', 'no newline at the end', 'ends with one\n']) {
+      const edit = withEvidenceBlock(body, 'ios', block);
+      assert.ok(edit.ok && edit.was === 'added');
+      assert.ok(edit.body.startsWith(body), JSON.stringify(body));
+      assert.match(edit.body.slice(body.length), /^(\n{1,2}|(\r\n){1,2})<!-- verify-evidence:ios -->/);
+      assert.ok(edit.body.replaceAll('\r\n', '\n').endsWith(block));
+    }
+    assert.deepEqual(withEvidenceBlock('', 'ios', block), { ok: true, body: block, was: 'added' });
+  });
+
+  it('replaces the block that is there and keeps every byte before and after it', () => {
+    const before = '## Summary\r\n\r\nText above.  \n\n';
+    const after = '\n\n- [x] a checklist\r\n<!-- /verify-evidence:android -->\ttrailing\n';
+    const old = evidenceBlock({ ...summary, run: 'r20261007-010101-aaaa' as RunId }, [{ alt: 'old', ref: 'https://github.com/user-attachments/assets/1' }]);
+    const edit = withEvidenceBlock(`${before}${old}${after}`, 'ios', block);
+    assert.deepEqual(edit, { ok: true, body: `${before}${block.replaceAll('\n', '\r\n')}${after}`, was: 'replaced' });
+    assert.equal(edit.ok && edit.body.includes('r20261007-010101-aaaa'), false);
+  });
+
+  it('keeps the block of the other platform', () => {
+    const android = evidenceBlock({ ...summary, platform: 'android', device: 'Pixel 9' }, []);
+    const edit = withEvidenceBlock(`intro\n\n${android}\n`, 'ios', block);
+    assert.deepEqual(edit, { ok: true, body: `intro\n\n${android}\n\n${block}`, was: 'added' });
+  });
+
+  it('takes a marker only when it is a whole line, so a description may quote one', () => {
+    const { start, end } = evidenceMarkers('ios');
+    const quoting = `The block sits between \`${start}\` and \`${end}\`.\n\n    ${start}\n    indented, so not a marker\n    ${end}\n`;
+    assert.deepEqual(withEvidenceBlock(quoting, 'ios', block), { ok: true, body: `${quoting}\n${block}`, was: 'added' });
+  });
+
+  const bodyAfter = (body: string, lines: string = block): string => {
+    const edit = withEvidenceBlock(body, 'ios', lines);
+    assert.ok(edit.ok, body);
+    return edit.body;
+  };
+
+  it('writes the block with the line endings of the description, added or replaced', () => {
+    const crlf = block.replaceAll('\n', '\r\n');
+    const old = evidenceBlock({ ...summary, run: 'r20261007-010101-aaaa' as RunId }, media);
+    const oldCrlf = old.replaceAll('\n', '\r\n');
+    assert.deepEqual(withEvidenceBlock(`intro\r\n\r\n${oldCrlf}\r\noutro`, 'ios', block), { ok: true, body: `intro\r\n\r\n${crlf}\r\noutro`, was: 'replaced' });
+    assert.equal(bodyAfter('intro\r\n'), `intro\r\n\r\n${crlf}`);
+    assert.equal(bodyAfter('one\r\ntwo'), `one\r\ntwo\r\n\r\n${crlf}`);
+    assert.equal(bodyAfter(`intro\n\n${old}\n`), `intro\n\n${block}\n`);
+    for (const body of [`intro\r\n\r\n${oldCrlf}\r\noutro`, 'intro\r\n']) assert.equal(/[^\r]\n/.test(bodyAfter(body)), false, 'no bare line feed');
+  });
+
+  it('replaces the block that the verify-attach workflow writes for a handed-off run', () => {
+    const published = [
+      '<!-- verify-evidence:ios -->',
+      '',
+      'verify run `r20261007-010101-aaaa`, as reported by [the session](https://github.com/clerk/clerk-ios/actions/runs/37731397352) that `octocat` started: 3 of 3 passed on `iPhone Air on xcode-27` at `0f50b597b1c2`.',
+      '',
+      '![video.mp4](https://github.com/user-attachments/assets/1)',
+      '',
+      '<!-- /verify-evidence:ios -->',
+    ].join('\n');
+    assert.deepEqual(withEvidenceBlock(`intro\n\n${published}\n`, 'ios', block), { ok: true, body: `intro\n\n${block}\n`, was: 'replaced' });
+  });
+
+  it('refuses to replace text between two markers that is not a block it wrote', () => {
+    const { start, end } = evidenceMarkers('ios');
+    const notes = `${start}\nIMPORTANT reviewer notes that are not evidence\n${end}\n`;
+    assert.deepEqual(withEvidenceBlock(notes, 'ios', block), { ok: false, why: `has text between \`${start}\` and \`${end}\` that is not an evidence block`, fix: 'leave one pair of those markers in the description, or none' });
+  });
+
+  it('takes no marker from inside a code fence, so a description may show a whole example block', () => {
+    const example = evidenceBlock({ ...summary, run: 'r20261007-010101-aaaa' as RunId }, media);
+    const later = evidenceBlock({ ...summary, run: 'r20261009-020202-bbbb' as RunId }, media);
+    const fences = [['```', '```'], ['```markdown', '```'], ['~~~~', '~~~~~'], ['   ```', '```  '], ['```\n```not the end, it has text after the ticks', '```'], ['```\n~~~', '```'], ['````\n```', '````']] as const;
+    for (const [open, close] of fences) {
+      const documented = `The block looks like this:\n\n${open}\n${example}\n${close}\n`;
+      const added = withEvidenceBlock(documented, 'ios', block);
+      assert.deepEqual(added, { ok: true, body: `${documented}\n${block}`, was: 'added' }, open);
+      const replaced = withEvidenceBlock(bodyAfter(documented), 'ios', later);
+      assert.deepEqual(replaced, { ok: true, body: `${documented}\n${later}`, was: 'replaced' }, open);
+    }
+  });
+
+  it('still takes a marker after a fence that closed, and one beside a line that only looks like a fence', () => {
+    const real = evidenceBlock({ ...summary, run: 'r20261007-010101-aaaa' as RunId }, media);
+    for (const before of ['```\ncode\n```\n\n', 'Use ```three ticks``` inline.\n\n', '```three ticks``` that open a line are inline code too.\n\n', '    ```\n\n', '``\n\n']) {
+      assert.deepEqual(withEvidenceBlock(`${before}${real}\n`, 'ios', block), { ok: true, body: `${before}${block}\n`, was: 'replaced' }, JSON.stringify(before));
+    }
+  });
+
+  it('opens no fence at a fence line inside an HTML comment, so the next attach finds the block it wrote', () => {
+    const later = evidenceBlock({ ...summary, run: 'r20261009-020202-bbbb' as RunId }, media);
+    for (const hidden of ['<!--\n```\n-->\n\nintro\n', '<!-- a note\r\n~~~\r\nstill the note -->\r\n', 'intro\n   <!--\n```\n']) {
+      const again = withEvidenceBlock(bodyAfter(hidden), 'ios', later);
+      assert.equal(again.ok && again.was, 'replaced', JSON.stringify(hidden));
+      assert.equal(again.ok && again.body.split('<!-- verify-evidence:ios -->').length, 2, 'one block, not two');
+    }
+    assert.equal(bodyAfter(`\`\`\`\n<!--\n\`\`\`\n\n${later}\n`), `\`\`\`\n<!--\n\`\`\`\n\n${block}\n`, 'a comment inside a fence is code, and the fence still closes');
+  });
+
+  it('refuses a description that ends inside a code fence that never closes, where a block would be code and never found again', () => {
+    for (const unclosed of ['intro\n\n```\ncode\n', 'intro\r\n~~~~ js\r\ncode', '```']) {
+      assert.deepEqual(withEvidenceBlock(unclosed, 'ios', block), { ok: false, why: 'ends inside a code fence that is never closed', fix: 'close that code fence' }, JSON.stringify(unclosed));
+    }
+    const earlier = evidenceBlock({ ...summary, run: 'r20261007-010101-aaaa' as RunId }, media);
+    assert.equal(bodyAfter(`intro\n\n${earlier}\n\n~~~\ncode\n`), `intro\n\n${block}\n\n~~~\ncode\n`, 'a block before the open fence is still replaced');
+  });
+
+  it('refuses a description whose markers are doubled, halved, or out of order, and says which', () => {
+    const { start, end } = evidenceMarkers('ios');
+    const refused = (body: string): string => {
+      const edit = withEvidenceBlock(body, 'ios', block);
+      assert.equal(edit.ok, false, body);
+      return edit.ok ? '' : edit.why;
+    };
+    assert.equal(refused(`${block}\n\n${block}`), `has \`${start}\` 2 times and \`${end}\` 2 times`);
+    assert.equal(refused(`text\n${start}\nno end`), `has \`${start}\` 1 times and \`${end}\` 0 times`);
+    assert.equal(refused(`no start\n${end}\n`), `has \`${start}\` 0 times and \`${end}\` 1 times`);
+    assert.equal(refused(`${end}\n${start}`), `has \`${end}\` before \`${start}\``);
   });
 });
 
@@ -140,15 +280,31 @@ describe('assertPublishable and the groups of a run', () => {
 
 describe('attach', () => {
   const host = { repo: 'clerk-ios', githubRepo: 'clerk/clerk-ios' } as HostAdapter;
+  const PR_URL = 'https://github.com/clerk/clerk-ios/pull/9';
 
-  function recordingRunner(attachFlag = true): { runner: Runner; calls: (readonly string[])[] } {
-    const calls: (readonly string[])[] = [];
-    const runner: Runner = async (command, args) => {
-      if (args.includes('--help')) return { code: 0, stdout: attachFlag ? '      --attach file   Attach a file\n' : '  -b, --body text   The comment body text\n', stderr: '' };
-      calls.push([command, ...args]);
-      return { code: 0, stdout: 'https://github.com/clerk/clerk-ios/pull/9#issuecomment-1\n', stderr: '' };
+  function fakeGh(options: { readonly attachFlag?: boolean; readonly body?: string; readonly onView?: (views: number, pr: { body: string }) => void } = {}) {
+    const pr = { body: options.body ?? '## Summary\n\nFixes the button.\n' };
+    const edits: { readonly args: readonly string[]; readonly cwd: string | undefined; readonly bodyFile: string }[] = [];
+    let views = 0;
+    const runner: Runner = async (command, args, runOptions) => {
+      assert.equal(command, 'gh');
+      if (args.includes('--help')) return { code: 0, stdout: options.attachFlag === false ? '  -b, --body text   Set the new body.\n' : '      --attach file   Attach a file\n', stderr: '' };
+      if (args[1] === 'view') {
+        views += 1;
+        options.onView?.(views, pr);
+        return { code: 0, stdout: JSON.stringify({ body: pr.body, url: PR_URL }), stderr: '' };
+      }
+      const bodyFile = readFileSync(args[args.indexOf('--body-file') + 1]!, 'utf8');
+      edits.push({ args, cwd: runOptions?.cwd, bodyFile });
+      pr.body = bodyFile.replace(/\]\(\.\/[^)]+\)/g, '](https://github.com/user-attachments/assets/uploaded)');
+      return { code: 0, stdout: `${PR_URL}\n`, stderr: '' };
     };
-    return { runner, calls };
+    return { runner, pr, edits };
+  }
+
+  function publishableRun() {
+    const { dir, run } = runDir();
+    return { dir, run, publishable: assertPublishable(sealEvidence(dir, partialRecord(dir, run), []), [OWN_USER]) };
   }
 
   it('never calls gh for a run that fails the gate', async () => {
@@ -158,43 +314,88 @@ describe('attach', () => {
     writeFileSync(join(dir, 'video.mp4'), 'x');
     writeFileSync(join(dir, 'app.log'), hostLogLine('user_foreign'));
     sealEvidence(dir, partialRecord(dir, run), []);
-    const { runner, calls } = recordingRunner();
+    const calls: string[] = [];
+    const runner: Runner = async (command) => (calls.push(command), { code: 0, stdout: '', stderr: '' });
     const deps = { host, workspace, runner, env: {}, progress: () => undefined, instances: heldInstances() };
     await assert.rejects(attach(deps, { verb: 'attach', run, pr: 9, screenshots: 'all' }), { code: 'EVIDENCE_UNSAFE' });
     assert.equal(calls.length, 0);
   });
 
-  it('posts once with --repo and --attach, then reports alreadyPosted', async () => {
-    const { dir, run } = runDir();
-    const record = sealEvidence(dir, partialRecord(dir, run), []);
-    const publishable = assertPublishable(record, [OWN_USER]);
-    const { runner, calls } = recordingRunner();
-    const first = await postToPullRequest(publishable, dir, host, 9, 'all', runner);
-    const second = await postToPullRequest(publishable, dir, host, 9, 'all', runner);
-    assert.equal(calls.length, 1);
-    const args = calls[0]!;
-    assert.deepEqual(args.slice(0, 6), ['gh', 'pr', 'comment', '9', '--repo', 'clerk/clerk-ios']);
-    assert.deepEqual(args.filter((_, i) => args[i - 1] === '--attach'), [join(dir, 'video.mp4'), join(dir, 'screenshots', 'profile.png')]);
-    assert.equal(first.alreadyPosted, false);
-    assert.equal(second.alreadyPosted, true);
-    assert.equal(second.commentUrl, 'https://github.com/clerk/clerk-ios/pull/9#issuecomment-1');
+  it('puts the block after the description with gh pr edit, from the run directory, and uploads a run only once', async () => {
+    const { dir, run, publishable } = publishableRun();
+    const gh = fakeGh();
+    const first = await postToPullRequest(publishable, dir, host, 9, 'all', gh.runner);
+    const second = await postToPullRequest(publishable, dir, host, 9, 'all', gh.runner);
+    assert.equal(gh.edits.length, 1);
+    const edit = gh.edits[0]!;
+    assert.deepEqual(edit.args.slice(0, 5), ['pr', 'edit', '9', '--repo', 'clerk/clerk-ios']);
+    assert.deepEqual(edit.args.filter((_, i) => edit.args[i - 1] === '--attach'), ['./video.mp4', './screenshots/profile.png']);
+    assert.equal(edit.cwd, dir);
+    assert.equal(
+      edit.bodyFile,
+      `## Summary\n\nFixes the button.\n\n<!-- verify-evidence:ios -->\n\nverify run \`${run}\` on \`verify-ios-1\` at \`abc\`, 1 of 1 passed.\n\n![video.mp4](./video.mp4)\n\n![profile](./screenshots/profile.png)\n\n<!-- /verify-evidence:ios -->`,
+    );
+    assert.equal(existsSync(edit.args[edit.args.indexOf('--body-file') + 1]!), false, 'the copy of the description is not kept');
+    assert.deepEqual(first, { verb: 'attach', via: 'gh', prUrl: PR_URL, posted: [join(dir, 'video.mp4'), join(dir, 'screenshots', 'profile.png')], alreadyPosted: false });
+    assert.deepEqual(second, { ...first, alreadyPosted: true });
     assert.ok(existsSync(join(dir, 'posted-9.json')));
-    const other = await postToPullRequest(publishable, dir, host, 10, 'all', runner);
-    assert.equal(other.alreadyPosted, false);
-    assert.equal(calls.length, 2);
-    assert.equal(calls[1]![3], '10');
+    await postToPullRequest(publishable, dir, host, 10, 'all', gh.runner);
+    assert.equal(gh.edits[1]!.args[2], '10');
   });
 
-  it('posts nothing and names the fix when gh pr comment has no --attach', async () => {
-    const { dir, run } = runDir();
-    const publishable = assertPublishable(sealEvidence(dir, partialRecord(dir, run), []), [OWN_USER]);
-    const { runner, calls } = recordingRunner(false);
-    await assert.rejects(postToPullRequest(publishable, dir, host, 9, 'all', runner), {
+  it('replaces the block of an earlier run, so a second run does not pile up media', async () => {
+    const earlier = publishableRun();
+    const later = publishableRun();
+    const gh = fakeGh();
+    await postToPullRequest(earlier.publishable, earlier.dir, host, 9, 'all', gh.runner);
+    gh.pr.body += '\nReviewer note added below the block.\n';
+    await postToPullRequest(later.publishable, later.dir, host, 9, ['profile'], gh.runner);
+    assert.equal(gh.pr.body.split('<!-- verify-evidence:ios -->').length, 2);
+    assert.equal(gh.pr.body.includes(earlier.run), false);
+    assert.ok(gh.pr.body.includes(later.run));
+    assert.ok(gh.pr.body.startsWith('## Summary\n\nFixes the button.\n\n<!-- verify-evidence:ios -->'));
+    assert.ok(gh.pr.body.endsWith('<!-- /verify-evidence:ios -->\nReviewer note added below the block.\n'));
+  });
+
+  it('posts nothing and names the fix when gh pr edit has no --attach', async () => {
+    const { dir, run, publishable } = publishableRun();
+    const gh = fakeGh({ attachFlag: false });
+    await assert.rejects(postToPullRequest(publishable, dir, host, 9, 'all', gh.runner), {
       code: 'NOT_READY',
-      message: `this gh has no \`gh pr comment --attach\`, so the video and screenshots of run ${run} cannot be posted`,
-      fix: 'install a gh build whose `gh pr comment` has --attach',
+      message: `this gh has no \`gh pr edit --attach\`, so the video and screenshots of run ${run} cannot be posted`,
+      fix: 'install gh 2.99.0 or newer, whose `gh pr edit` has --attach',
     });
-    assert.deepEqual(calls, []);
+    assert.deepEqual(gh.edits, []);
     assert.equal(existsSync(join(dir, 'posted-9.json')), false);
   });
+
+  it('builds on the newer description when someone edits it between the read and the write', async () => {
+    const { dir, publishable } = publishableRun();
+    const gh = fakeGh({ onView: (views, pr) => void (views === 2 && (pr.body = 'Rewritten by a reviewer.\n')) });
+    await postToPullRequest(publishable, dir, host, 9, 'all', gh.runner);
+    assert.equal(gh.edits.length, 1);
+    assert.ok(gh.edits[0]!.bodyFile.startsWith('Rewritten by a reviewer.\n\n<!-- verify-evidence:ios -->'));
+  });
+
+  it('writes nothing when the description changes twice, and says so', async () => {
+    const { dir, run, publishable } = publishableRun();
+    const gh = fakeGh({ onView: (views, pr) => void (pr.body = `edit ${views}\n`) });
+    await assert.rejects(postToPullRequest(publishable, dir, host, 9, 'all', gh.runner), {
+      code: 'NOT_READY',
+      message: `the description of PR #9 changed twice while the evidence of run ${run} was being placed, so nothing was written`,
+    });
+    assert.deepEqual(gh.edits, []);
+    assert.equal(existsSync(join(dir, 'posted-9.json')), false);
+  });
+
+  it('writes nothing to a description whose markers are broken, and says which', async () => {
+    const { dir, run, publishable } = publishableRun();
+    const gh = fakeGh({ body: 'text\n<!-- verify-evidence:ios -->\nthe end marker was deleted\n' });
+    await assert.rejects(postToPullRequest(publishable, dir, host, 9, 'all', gh.runner), {
+      code: 'NOT_READY',
+      message: `the description of PR #9 has \`<!-- verify-evidence:ios -->\` 1 times and \`<!-- /verify-evidence:ios -->\` 0 times, so the evidence of run ${run} has no one place to go`,
+      fix: 'leave one pair of those markers in the description, or none, then rerun',
+    });
+    assert.deepEqual(gh.edits, []);
+  });
 });
diff --git a/e2e-tests/test/handoff.test.ts b/e2e-tests/test/handoff.test.ts
new file mode 100644
index 000000000..2a8bfaa73
--- /dev/null
+++ b/e2e-tests/test/handoff.test.ts
@@ -0,0 +1,534 @@
+import '../testing/git-env.ts';
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, it } from 'node:test';
+import { heldInstances } from '../testing/fake-instances.ts';
+import { createOutput } from '../src/core/cli.ts';
+import { sealEvidence } from '../src/core/evidence.ts';
+import { run as realRunner, type Runner } from '../src/core/exec.ts';
+import { remoteBackend } from '../src/core/remote/backend.ts';
+import type { GitHub } from '../src/core/remote/github.ts';
+import { HANDOFF_LIMITS, HandoffRefused, evidenceReceiver, parseHandoffManifest, pullRequestMismatch, type HandoffManifest } from '../src/core/remote/handoff.ts';
+import type { RemoteSettings } from '../src/core/remote/settings.ts';
+import { attach, type Deps } from '../src/core/verbs.ts';
+import { openWorkspace } from '../src/core/workspace.ts';
+import { VerifyFailure, type BuildKey, type DeviceBackend, type EvidenceBundle, type EvidencePath, type EvidenceRecord, type HostAdapter, type Lease, type RemoteLease, type RunId } from '../src/core/types.ts';
+
+const sha256 = (data: string | Buffer): string => createHash('sha256').update(data).digest('hex');
+const COMMIT = '0f50b597b1c2d3e4f5a60718293a4b5c6d7e8f90';
+const VIDEO = Buffer.from('a video that is longer than one chunk of five bytes');
+const SHOT = Buffer.from('png bytes');
+
+const good: HandoffManifest = {
+  v: 1,
+  pr: 669,
+  run: 'r20261008-052713-253e',
+  platform: 'ios',
+  device: 'iPhone Air on xcode-27',
+  commit: COMMIT,
+  passed: 3,
+  flaky: 0,
+  total: 3,
+  files: [
+    { name: 'video.mp4', bytes: VIDEO.length, sha256: sha256(VIDEO) },
+    { name: 'profile.png', bytes: SHOT.length, sha256: sha256(SHOT) },
+  ],
+};
+
+describe('the hand-off manifest', () => {
+  const parse = (change: Record<string, unknown>) => parseHandoffManifest(JSON.stringify({ ...good, ...change }));
+  const file = (change: Record<string, unknown>) => parse({ files: [{ ...good.files[1]!, ...change }] });
+
+  it('accepts a run with a video and screenshots', () => {
+    assert.deepEqual(parseHandoffManifest(JSON.stringify(good)), good);
+  });
+
+  it('refuses a run with no file, which the publishing workflow refuses too', () => {
+    assert.throws(() => parse({ files: [] }), /files must be a list of 1 to 50/);
+  });
+
+  it('refuses every field that is missing, malformed, or out of range', () => {
+    const refused: readonly [string, () => unknown][] = [
+      ['text that is not JSON', () => parseHandoffManifest('{')],
+      ['a list', () => parseHandoffManifest('[]')],
+      ['another version', () => parse({ v: 2 })],
+      ['a key the schema does not have', () => parse({ note: 'free text' })],
+      ['a missing key', () => parseHandoffManifest(JSON.stringify({ ...good, device: undefined }))],
+      ['a run id of another shape', () => parse({ run: 'r20261008-052713-253e; rm -rf /' })],
+      ['a PR number that is text', () => parse({ pr: '669' })],
+      ['a PR number that is not whole', () => parse({ pr: 6.5 })],
+      ['a PR number of zero', () => parse({ pr: 0 })],
+      ['a third platform', () => parse({ platform: 'web' })],
+      ['a device with markdown in it', () => parse({ device: 'iPhone `Air` [x](http://evil)' })],
+      ['a short commit', () => parse({ commit: 'abc1234' })],
+      ['a negative count', () => parse({ passed: -1 })],
+      ['no passing test', () => parse({ passed: 0, flaky: 0 })],
+      ['more passing tests than tests', () => parse({ passed: 4 })],
+      ['files that are not a list', () => parse({ files: 'video.mp4' })],
+      ['more files than the cap', () => parse({ files: Array.from({ length: HANDOFF_LIMITS.files + 1 }, (_, i) => ({ ...good.files[1]!, name: `s${i}.png` })) })],
+      ['two videos', () => parse({ files: [good.files[0]!, { ...good.files[0]!, name: 'second.mp4' }] })],
+      ['two files with one name', () => parse({ files: [good.files[1]!, { ...good.files[1]!, name: 'Profile.png' }] })],
+      ['a name with a path separator', () => file({ name: '../profile.png' })],
+      ['a name with a backslash', () => file({ name: 'a\\profile.png' })],
+      ['a name that starts with a dot', () => file({ name: '.profile.png' })],
+      ['a name that starts with a dash', () => file({ name: '-profile.png' })],
+      ['a name with a space', () => file({ name: 'my profile.png' })],
+      ['an extension outside png, jpg, mp4', () => file({ name: 'profile.svg' })],
+      ['a name with no extension', () => file({ name: 'profile' })],
+      ['a name that is too long', () => file({ name: `${'a'.repeat(120)}.png` })],
+      ['an empty file', () => file({ bytes: 0 })],
+      ['an image over its cap', () => file({ bytes: HANDOFF_LIMITS.imageBytes + 1 })],
+      ['a video over its cap', () => parse({ files: [{ ...good.files[0]!, bytes: HANDOFF_LIMITS.videoBytes + 1 }] })],
+      ['a sha256 of another shape', () => file({ sha256: 'abc' })],
+      ['a file with a key the schema does not have', () => file({ path: '/etc/passwd' })],
+      ['a manifest over its size cap', () => parseHandoffManifest(JSON.stringify(good).padEnd(HANDOFF_LIMITS.manifestBytes + 1, ' '))],
+    ];
+    for (const [what, attempt] of refused) assert.throws(attempt, HandoffRefused, what);
+  });
+
+  it('refuses files that are within their own caps and over the total', () => {
+    const images = Array.from({ length: 6 }, (_, i) => ({ name: `s${i}.png`, bytes: HANDOFF_LIMITS.imageBytes, sha256: sha256('x') }));
+    assert.throws(() => parse({ files: [{ ...good.files[0]!, bytes: HANDOFF_LIMITS.videoBytes }, ...images] }), /over 157286400 bytes in all/);
+  });
+});
+
+describe('the rule for which pull request a session may publish to', () => {
+  const STARTED_ON = 'd'.repeat(40);
+  const session = { repo: 'clerk/clerk-ios', headBranch: 'feature/change', startedOn: STARTED_ON, runCommit: COMMIT };
+  const pull = { state: 'open', headRepo: 'clerk/clerk-ios', headRef: 'feature/change', commits: [STARTED_ON, COMMIT], commitCount: 2 };
+  const why = (...asked: Parameters<typeof pullRequestMismatch>): string | undefined => pullRequestMismatch(...asked)?.why;
+
+  it('accepts the open pull request of the session branch that holds the commit the session started on and the commit of the run', () => {
+    assert.equal(pullRequestMismatch(pull, session), null);
+    assert.equal(pullRequestMismatch({ ...pull, commits: [COMMIT] }, { ...session, startedOn: COMMIT }), null, 'a run at the commit the session started on');
+  });
+
+  it('accepts a pull request that has newer commits than the run', () => {
+    assert.equal(pullRequestMismatch({ ...pull, commits: [STARTED_ON, COMMIT, 'b'.repeat(40)] }, session), null);
+  });
+
+  it('refuses a closed one, a fork, another branch, and one that lacks either commit, and says which', () => {
+    assert.equal(why({ ...pull, state: 'closed' }, session), 'it is closed');
+    assert.equal(why({ ...pull, headRepo: 'someone/clerk-ios' }, session), 'its branch is in someone/clerk-ios, not in clerk/clerk-ios');
+    assert.equal(why({ ...pull, headRepo: null }, session), 'its branch is in a deleted fork, not in clerk/clerk-ios');
+    assert.equal(why({ ...pull, headRef: 'main' }, session), 'its branch is main and the session runs on feature/change');
+    assert.equal(why({ ...pull, commits: [COMMIT] }, session), 'the session started on dddddddddddd, which is not one of its commits');
+    assert.equal(why({ ...pull, commits: [STARTED_ON] }, session), 'the run was made at 0f50b597b1c2, which is not one of its commits');
+  });
+
+  it('says that GitHub lists only the first 250 commits when a longer pull request does not show a commit, and gives a fix that can change that', () => {
+    const listed = Array.from({ length: 250 }, (_, i) => i.toString(16).padStart(40, '0'));
+    const long = { ...pull, commits: listed, commitCount: 300 };
+    const refused = pullRequestMismatch(long, session);
+    assert.equal(refused?.why, 'it has 300 commits, GitHub lists only the first 250, and the session started on dddddddddddd, which is not among those');
+    assert.match(refused?.fix ?? '', /squash or rebase the branch to 250 commits or fewer, .* or run \{cli\} attach on a machine whose gh can attach$/);
+    assert.equal(why({ ...long, commits: [STARTED_ON, ...listed.slice(1)] }, session), 'it has 300 commits, GitHub lists only the first 250, and the run was made at 0f50b597b1c2, which is not among those');
+    assert.equal(pullRequestMismatch({ ...long, commits: [STARTED_ON, COMMIT, ...listed.slice(2)] }, session), null, 'both commits are among the first 250');
+    const short = pullRequestMismatch({ ...long, commitCount: 250 }, session);
+    assert.equal(short?.why, 'the session started on dddddddddddd, which is not one of its commits');
+    assert.notEqual(short?.fix, refused?.fix);
+  });
+});
+
+describe('the receiver in the session job', () => {
+  const chunk = (name: string, offset: number, data: Buffer) => JSON.stringify({ name, offset, data: data.toString('base64') });
+  const status = (attempt: () => unknown): number => {
+    try {
+      attempt();
+    } catch (error) {
+      if (error instanceof HandoffRefused) return error.status;
+      throw error;
+    }
+    return 200;
+  };
+
+  function received() {
+    const work = mkdtempSync(join(tmpdir(), 'verify-handoff-'));
+    writeFileSync(join(work, 'agent.log'), 'the session agent keeps other files here');
+    const receiver = evidenceReceiver(work);
+    receiver.begin(JSON.stringify(good));
+    return { work, receiver };
+  }
+
+  it('keeps the manifest and the files in one directory, and only once every file is whole', () => {
+    const { work, receiver } = received();
+    receiver.chunk(chunk('video.mp4', 0, VIDEO.subarray(0, 20)));
+    assert.equal(existsSync(join(work, 'evidence')), false, 'a hand-off in progress is not what the job uploads');
+    assert.equal(receiver.held(), null);
+    assert.throws(() => receiver.commit(), (error: HandoffRefused) => error.status === 409 && error.message === `video.mp4 has 20 of ${VIDEO.length} bytes`, 'a commit with bytes missing is refused');
+    assert.deepEqual(receiver.chunk(chunk('video.mp4', 20, VIDEO.subarray(20))), { ok: true, bytes: VIDEO.length });
+    receiver.chunk(chunk('profile.png', 0, SHOT));
+    assert.deepEqual(receiver.commit(), { ok: true, run: good.run, files: 2, bytes: VIDEO.length + SHOT.length });
+    assert.deepEqual(readdirSync(work).sort(), ['agent.log', 'evidence']);
+    assert.deepEqual(readdirSync(join(work, 'evidence')).sort(), ['manifest.json', 'profile.png', 'video.mp4']);
+    assert.deepEqual(readFileSync(join(work, 'evidence', 'video.mp4')), VIDEO);
+    assert.deepEqual(JSON.parse(readFileSync(join(work, 'evidence', 'manifest.json'), 'utf8')), good);
+    assert.equal(receiver.held(), good.run);
+  });
+
+  it('refuses a chunk for a file the manifest does not name, so no request chooses a path', () => {
+    const { work, receiver } = received();
+    for (const name of ['../agent.log', '/etc/passwd', 'other.png', 'manifest.json']) assert.equal(status(() => receiver.chunk(chunk(name, 0, SHOT))), 400, name);
+    assert.equal(readFileSync(join(work, 'agent.log'), 'utf8'), 'the session agent keeps other files here');
+    assert.deepEqual(readdirSync(join(work, 'evidence.partial')), ['manifest.json']);
+  });
+
+  it('takes a file in order only, and tells a sender that repeats a chunk how much it has', () => {
+    const { receiver } = received();
+    receiver.chunk(chunk('video.mp4', 0, VIDEO.subarray(0, 20)));
+    assert.throws(() => receiver.chunk(chunk('video.mp4', 0, VIDEO.subarray(0, 20))), (error: HandoffRefused) => error.status === 409 && error.have === 20);
+    assert.equal(status(() => receiver.chunk(chunk('video.mp4', 30, VIDEO.subarray(30)))), 409);
+  });
+
+  it('refuses bytes past the size the manifest declares, a chunk over the chunk cap, and a body over the body cap', () => {
+    const { receiver } = received();
+    assert.equal(status(() => receiver.chunk(chunk('profile.png', 0, Buffer.concat([SHOT, SHOT])))), 413);
+    const large = evidenceReceiver(mkdtempSync(join(tmpdir(), 'verify-handoff-')));
+    large.begin(JSON.stringify({ ...good, files: [{ ...good.files[0]!, bytes: 4 * HANDOFF_LIMITS.chunkBytes }] }));
+    assert.throws(() => large.chunk(chunk('video.mp4', 0, Buffer.alloc(HANDOFF_LIMITS.chunkBytes + 1))), (error: HandoffRefused) => error.status === 413 && error.message === 'a chunk holds 1 to 1048576 bytes');
+    assert.deepEqual(large.chunk(chunk('video.mp4', 0, Buffer.alloc(HANDOFF_LIMITS.chunkBytes))), { ok: true, bytes: HANDOFF_LIMITS.chunkBytes });
+    assert.equal(status(() => receiver.chunk(null)), 413, 'the agent passes null for a body it stopped reading at the cap');
+    assert.equal(status(() => evidenceReceiver(mkdtempSync(join(tmpdir(), 'verify-handoff-'))).begin(null)), 413);
+  });
+
+  it('refuses a chunk that is not the JSON it expects', () => {
+    const { receiver } = received();
+    for (const body of ['not json', '[]', JSON.stringify({ name: 'profile.png', offset: 0 }), JSON.stringify({ name: 'profile.png', offset: 0, data: 'not base64 !' }), JSON.stringify({ name: 'profile.png', offset: 0, data: '' })]) {
+      assert.equal(status(() => receiver.chunk(body)), 400, body);
+    }
+  });
+
+  it('refuses to commit bytes that do not have the sha256 the manifest declares', () => {
+    const { work, receiver } = received();
+    receiver.chunk(chunk('video.mp4', 0, VIDEO));
+    receiver.chunk(chunk('profile.png', 0, Buffer.from('PNG BYTES')));
+    assert.equal(status(() => receiver.commit()), 409);
+    assert.equal(existsSync(join(work, 'evidence')), false);
+  });
+
+  it('replaces an earlier hand-off with a later one, and refuses a manifest that does not parse', () => {
+    const { work, receiver } = received();
+    receiver.chunk(chunk('video.mp4', 0, VIDEO));
+    receiver.chunk(chunk('profile.png', 0, SHOT));
+    receiver.commit();
+    assert.equal(status(() => receiver.begin(JSON.stringify({ ...good, run: 'nope' }))), 400);
+    assert.equal(receiver.held(), good.run, 'a refused manifest leaves the kept hand-off alone');
+    const later = { ...good, run: 'r20261008-060000-aaaa', files: [good.files[1]!] };
+    receiver.begin(JSON.stringify(later));
+    receiver.chunk(chunk('profile.png', 0, SHOT));
+    receiver.commit();
+    assert.deepEqual(readdirSync(join(work, 'evidence')).sort(), ['manifest.json', 'profile.png']);
+    assert.equal(receiver.held(), later.run);
+    assert.equal(status(() => receiver.chunk(chunk('profile.png', 0, SHOT))), 409, 'nothing is appended after a commit');
+  });
+});
+
+const LEASE: RemoteLease = { backend: 'remote', provider: 'github-actions', platform: 'ios', session: 'ios0000aa', providerRef: '37731397352', baseUrl: 'https://session.trycloudflare.com', tokenFile: '', deviceId: 'UDID', deviceName: 'iPhone Air', runner: 'xcode-27', expiresAt: '2026-10-08T06:00:00Z', builtSha: COMMIT, acquiredAt: '2026-10-08T05:00:00.000Z', installedBuild: null };
+
+function remoteRun(options: { readonly backend?: EvidenceRecord['backend']; readonly lease?: Lease | null; readonly startedAt?: string; readonly handOff?: DeviceBackend['handOffEvidence'] | null; readonly gh?: (args: readonly string[]) => { readonly code: number; readonly stdout: string; readonly stderr: string } } = {}) {
+  const packageDir = mkdtempSync(join(tmpdir(), 'verify-handoff-verb-'));
+  const workspace = openWorkspace({ packageDir, worktree: packageDir, home: join(packageDir, 'home') });
+  const { run, dir } = workspace.newRun();
+  mkdirSync(join(dir, 'screenshots'));
+  writeFileSync(join(dir, 'video.mp4'), VIDEO);
+  writeFileSync(join(dir, 'screenshots', 'profile.png'), SHOT);
+  const backend = options.backend ?? 'remote';
+  sealEvidence(
+    dir,
+    {
+      run,
+      startedAt: options.startedAt ?? '2026-10-08T05:27:13.000Z',
+      finishedAt: '2026-10-08T05:30:00.000Z',
+      repo: 'clerk-ios',
+      gitHead: COMMIT,
+      dirty: false,
+      platform: 'ios',
+      backend,
+      remote: backend === 'remote' ? { provider: 'github-actions', runner: 'xcode-27', builtSha: COMMIT } : null,
+      device: 'iPhone Air on xcode-27',
+      build: 'ios-000000000000' as BuildKey,
+      results: [{ spec: { kind: 'explored', path: 'specs/explored/a.e2e.ts', feature: null }, title: 'a', platform: 'ios', status: 'passed', seconds: 1, attempts: 1, error: null, skipReason: null, skippedBy: null, tags: [], failurePage: null, failureScreen: null, failureScreenshot: null }],
+      videos: [join(dir, 'video.mp4') as EvidencePath],
+      screenshots: [{ label: 'profile', path: join(dir, 'screenshots', 'profile.png') as EvidencePath }],
+      appLog: null,
+      e2eReport: join(dir, 'e2e', 'report.json') as EvidencePath,
+      identities: [],
+      settings: [{ label: 'standard', askedBy: null, specs: ['specs/explored/a.e2e.ts'], application: null, changed: false, held: true, e2eReport: join(dir, 'e2e', 'report.json') as EvidencePath }],
+    },
+    [],
+  );
+  if (options.lease !== null) workspace.writeLease(options.lease ?? { ...LEASE, tokenFile: join(packageDir, 'token') });
+  const bundles: EvidenceBundle[] = [];
+  const handOffEvidence: DeviceBackend['handOffEvidence'] = options.handOff === undefined ? async (_lease, bundle) => (bundles.push(bundle), { sessionRun: '37731397352', sessionRunUrl: 'https://github.com/clerk/clerk-ios/actions/runs/37731397352' }) : (options.handOff ?? undefined);
+  const remote = { kind: 'remote', platform: 'ios', ...(handOffEvidence === undefined ? {} : { handOffEvidence }) } as unknown as DeviceBackend;
+  const host = { repo: 'clerk-ios', githubRepo: 'clerk/clerk-ios', backends: [remote] } as unknown as HostAdapter;
+  const ghCalls: string[] = [];
+  const gh = options.gh ?? (() => ({ code: 0, stdout: '  -b, --body text   Set the new body.\n', stderr: '' }));
+  const runner: Runner = async (_command, args) => (ghCalls.push(args.slice(0, 2).join(' ') === 'pr edit' && !args.includes('--help') ? 'pr edit --attach' : args.slice(0, 3).join(' ')), gh(args));
+  const deps: Deps = { host, workspace, runner, env: {}, progress: () => undefined, instances: heldInstances() };
+  return { deps, run, dir, bundles, ghCalls };
+}
+
+describe('attach on a machine whose gh cannot attach', () => {
+  it('hands the sealed files of a borrowed-device run to the session, and says what happens next', async () => {
+    const { deps, run, dir, bundles, ghCalls } = remoteRun();
+    const result = await attach(deps, { verb: 'attach', run, pr: 669, screenshots: 'all' });
+    assert.deepEqual(ghCalls, ['pr edit --help'], 'gh was asked first, and it cannot attach');
+    assert.deepEqual(bundles, [
+      {
+        pr: 669,
+        summary: { run, platform: 'ios', device: 'iPhone Air on xcode-27', commit: COMMIT, passed: 1, flaky: 0, total: 1 },
+        files: [
+          { name: 'video.mp4', path: join(dir, 'video.mp4') },
+          { name: 'profile.png', path: join(dir, 'screenshots', 'profile.png') },
+        ],
+      },
+    ]);
+    assert.deepEqual(result, {
+      verb: 'attach',
+      via: 'runner',
+      pr: 669,
+      handedOff: [join(dir, 'video.mp4'), join(dir, 'screenshots', 'profile.png')],
+      because: 'this gh has no `gh pr edit --attach`',
+      sessionRun: '37731397352',
+      sessionRunUrl: 'https://github.com/clerk/clerk-ios/actions/runs/37731397352',
+    });
+    let out = '';
+    createOutput(false, '/tmp', 'bin/control-x', { write: (text: string) => (out += text) }, { write: () => true }).result(result);
+    assert.deepEqual(out.trimEnd().split('\n'), [
+      "handed off  video.mp4, profile.png  to the session's runner (https://github.com/clerk/clerk-ios/actions/runs/37731397352), because this gh has no `gh pr edit --attach`",
+      'next        bin/control-x down ends the session; the verify-attach workflow then puts the evidence in the description of PR #669',
+    ]);
+  });
+
+  const ghThatHasAttach = (edit: { readonly code: number; readonly stdout: string; readonly stderr: string }, view = { code: 0, stdout: JSON.stringify({ body: 'A description.\n', url: 'https://github.com/clerk/clerk-ios/pull/669' }), stderr: '' }) => (args: readonly string[]) => {
+    if (args.includes('--help')) return { code: 0, stdout: '      --attach file   Attach a file\n', stderr: '' };
+    return args[1] === 'view' ? view : edit;
+  };
+
+  it('tries gh pr edit --attach itself first for a borrowed-device run, and hands nothing off when that works', async () => {
+    const { deps, run, dir, bundles, ghCalls } = remoteRun({ gh: ghThatHasAttach({ code: 0, stdout: 'https://github.com/clerk/clerk-ios/pull/669\n', stderr: '' }) });
+    const result = await attach(deps, { verb: 'attach', run, pr: 669, screenshots: 'all' });
+    assert.deepEqual(result, { verb: 'attach', via: 'gh', prUrl: 'https://github.com/clerk/clerk-ios/pull/669', posted: [join(dir, 'video.mp4'), join(dir, 'screenshots', 'profile.png')], alreadyPosted: false });
+    assert.deepEqual(ghCalls, ['pr edit --help', 'pr view 669', 'pr view 669', 'pr edit --attach']);
+    assert.deepEqual(bundles, [], 'nothing went to the session');
+  });
+
+  it('hands off only after its own gh pr edit --attach was tried and refused, as a sandbox proxy refuses an upload', async () => {
+    const order: string[] = [];
+    const refusedUpload = ghThatHasAttach({ code: 1, stdout: '', stderr: '415 Request bodies must declare Content-Type: application/json\n' });
+    const { deps, run, ghCalls } = remoteRun({
+      gh: (args) => (order.push(args.includes('--attach') ? 'gh pr edit --attach' : 'gh'), refusedUpload(args)),
+      handOff: async () => (order.push('hand-off'), { sessionRun: '1', sessionRunUrl: 'https://github.com/clerk/clerk-ios/actions/runs/1' }),
+    });
+    const result = await attach(deps, { verb: 'attach', run, pr: 669, screenshots: 'all' });
+    assert.equal(result.via === 'runner' && result.because, 'gh pr edit failed');
+    assert.equal(ghCalls.at(-1), 'pr edit --attach');
+    assert.deepEqual(order.slice(-2), ['gh pr edit --attach', 'hand-off']);
+  });
+
+  it('hands off when gh cannot read the pull request, as it cannot where GraphQL is blocked', async () => {
+    const { deps, run, bundles, ghCalls } = remoteRun({ gh: ghThatHasAttach({ code: 0, stdout: '', stderr: '' }, { code: 1, stdout: '', stderr: 'GraphQL: blocked\n' }) });
+    const result = await attach(deps, { verb: 'attach', run, pr: 669, screenshots: 'all' });
+    assert.equal(result.via === 'runner' && result.because, 'gh pr view failed');
+    assert.deepEqual(ghCalls, ['pr edit --help', 'pr view 669']);
+    assert.equal(bundles.length, 1);
+  });
+
+  it('hands off only the screenshots that were asked for', async () => {
+    const { deps, run, bundles } = remoteRun();
+    await attach(deps, { verb: 'attach', run, pr: 669, screenshots: [] });
+    assert.deepEqual(bundles[0]!.files.map((file) => file.name), ['video.mp4']);
+  });
+
+  const failure = async (deps: Deps, run: RunId): Promise<VerifyFailure> => {
+    try {
+      await attach(deps, { verb: 'attach', run, pr: 669, screenshots: 'all' });
+    } catch (error) {
+      if (error instanceof VerifyFailure) return error;
+      throw error;
+    }
+    throw new Error('attach did not fail');
+  };
+
+  it('says that the session is gone, and to name the run in the PR', async () => {
+    const { deps, run, bundles } = remoteRun({ lease: null });
+    const error = await failure(deps, run);
+    assert.equal(error.message, `this gh has no \`gh pr edit --attach\`, so the video and screenshots of run ${run} cannot be posted, and this worktree holds no session now, so nothing can take the evidence to a runner`);
+    assert.equal(error.fix, `name run ${run} in the PR and say that the evidence was not attached; to attach it, {cli} run again and {cli} attach before {cli} down`);
+    assert.deepEqual(bundles, []);
+  });
+
+  it('does not hand a remote run to the local device that the worktree holds now', async () => {
+    const local: Lease = { backend: 'local', platform: 'ios', slot: 1, deviceName: 'verify-ios-1', deviceId: 'UDID', claimNonce: 'n', acquiredAt: '2026-10-08T05:00:00.000Z', installedBuild: null };
+    const { deps, run, bundles } = remoteRun({ lease: local });
+    assert.match((await failure(deps, run)).message, /this worktree holds no session now, so nothing can take the evidence to a runner$/);
+    assert.deepEqual(bundles, []);
+  });
+
+  it('does not hand a run to a session that started after it', async () => {
+    const { deps, run, bundles } = remoteRun({ startedAt: '2026-10-08T04:00:00.000Z' });
+    assert.match((await failure(deps, run)).message, /ran before the session that is up now started$/);
+    assert.deepEqual(bundles, []);
+  });
+
+  it('says why a hand-off failed, and still to name the run in the PR', async () => {
+    const { deps, run } = remoteRun({ handOff: async () => { throw new VerifyFailure('NOT_READY', 'the hand-off failed: 502', 'run {cli} attach again while the session is up'); } });
+    const error = await failure(deps, run);
+    assert.match(error.message, /cannot be posted, and the hand-off failed: 502$/);
+    assert.equal(error.fix, `run {cli} attach again while the session is up; until then, name run ${run} in the PR and say that the evidence was not attached`);
+  });
+
+  it('keeps the plain failure for a run on a local device, which has no session', async () => {
+    const { deps, run, bundles } = remoteRun({ backend: 'local' });
+    const error = await failure(deps, run);
+    assert.equal(error.message, `this gh has no \`gh pr edit --attach\`, so the video and screenshots of run ${run} cannot be posted`);
+    assert.equal(error.fix, 'install gh 2.99.0 or newer, whose `gh pr edit` has --attach');
+    assert.deepEqual(bundles, []);
+  });
+});
+
+describe('the remote backend before it sends evidence', () => {
+  const settings: RemoteSettings = { platform: 'ios', repo: 'clerk/clerk-ios', workflow: 'verify-remote.yml', sessionsDir: '/nonexistent', runner: 'xcode-27', plumbingRunner: 'ubuntu-latest', device: 'iPhone Air', idleMinutes: 15, capMinutes: 60, requirement: 'a pushed branch' };
+  const STARTED_ON = 'd'.repeat(40);
+  const OPEN = { state: 'open', body: '## Summary\r\n\r\nFixes the button.\r\n', head: { ref: 'feature/change', sha: COMMIT, repo: { full_name: 'clerk/clerk-ios' } } };
+
+  interface Case {
+    readonly pull?: unknown;
+    readonly commits?: readonly string[];
+    readonly health?: unknown;
+    readonly files?: EvidenceBundle['files'];
+  }
+
+  async function handOff(options: Case = {}) {
+    const dir = mkdtempSync(join(tmpdir(), 'verify-handoff-backend-'));
+    writeFileSync(join(dir, 'token'), 'b'.repeat(64));
+    writeFileSync(join(dir, 'video.mp4'), VIDEO);
+    const bundle: EvidenceBundle = {
+      pr: 669,
+      summary: { run: good.run as RunId, platform: 'ios', device: good.device, commit: COMMIT, passed: 3, flaky: 0, total: 3 },
+      files: options.files ?? [{ name: 'video.mp4', path: join(dir, 'video.mp4') as EvidencePath }],
+    };
+    const commits = options.commits ?? [STARTED_ON, COMMIT];
+    const asked: string[] = [];
+    const hub: GitHub = {
+      repo: settings.repo,
+      workflow: settings.workflow,
+      tokenSource: 'none',
+      api: async (_method, path) => {
+        asked.push(path);
+        const page = /^\/pulls\/669\/commits\?per_page=100&page=(\d+)$/.exec(path);
+        if (page !== null) return { status: 200, json: commits.slice((Number(page[1]) - 1) * 100, Number(page[1]) * 100).map((sha) => ({ sha })), headers: new Headers() };
+        return { status: 200, json: path.startsWith('/pulls/') ? (options.pull ?? OPEN) : { head_branch: 'feature/change', head_sha: STARTED_ON }, headers: new Headers() };
+      },
+    };
+    const sent: string[] = [];
+    const health = options.health === undefined ? { ending: null } : options.health;
+    const realFetch = globalThis.fetch;
+    globalThis.fetch = async (input) => {
+      const path = new URL(String(input)).pathname;
+      if (path === '/__sim/health') return health === null ? new Response('gone', { status: 502 }) : Response.json(health);
+      sent.push(path);
+      return Response.json({ ok: true });
+    };
+    try {
+      const receipt = await remoteBackend(settings, { env: {}, runner: realRunner, github: async () => hub }).handOffEvidence!({ ...LEASE, tokenFile: join(dir, 'token') }, bundle, () => undefined);
+      return { receipt, error: null, sent, asked };
+    } catch (error) {
+      if (error instanceof VerifyFailure) return { receipt: null, error, sent, asked };
+      throw error;
+    } finally {
+      globalThis.fetch = realFetch;
+    }
+  }
+
+  const refusal = async (options: Case): Promise<{ readonly error: VerifyFailure; readonly sent: readonly string[] }> => {
+    const { error, sent } = await handOff(options);
+    assert.ok(error !== null, 'the hand-off was not refused');
+    return { error, sent };
+  };
+  const wouldNot = `the verify-attach workflow would not put the evidence of run ${good.run} on PR #669: `;
+
+  it('sends a run made after a push in the same session, though the session started on an earlier commit', async () => {
+    const { receipt, sent } = await handOff();
+    assert.deepEqual(sent, ['/__sim/evidence/begin', '/__sim/evidence/chunk', '/__sim/evidence/commit']);
+    assert.deepEqual(receipt, { sessionRun: '37731397352', sessionRunUrl: 'https://github.com/clerk/clerk-ios/actions/runs/37731397352' });
+  });
+
+  it('sends a run whose pull request has moved on to newer commits', async () => {
+    const newer = 'b'.repeat(40);
+    const { error, sent } = await handOff({ pull: { ...OPEN, head: { ...OPEN.head, sha: newer } }, commits: [STARTED_ON, COMMIT, newer] });
+    assert.equal(error, null);
+    assert.deepEqual(sent, ['/__sim/evidence/begin', '/__sim/evidence/chunk', '/__sim/evidence/commit']);
+  });
+
+  it('sends nothing for a pull request the publishing workflow would refuse, and says which rule', async () => {
+    const fork = await refusal({ pull: { ...OPEN, head: { ...OPEN.head, repo: { full_name: 'someone/clerk-ios' } } } });
+    assert.equal(fork.error.code, 'NOT_READY');
+    assert.equal(fork.error.message, `${wouldNot}its branch is in someone/clerk-ios, not in clerk/clerk-ios`);
+    assert.deepEqual(fork.sent, []);
+    const closed = await refusal({ pull: { ...OPEN, state: 'closed' } });
+    assert.equal(closed.error.message, `${wouldNot}it is closed`);
+    assert.deepEqual(closed.sent, []);
+  });
+
+  it('sends nothing when the commit the session started on, or the commit of the run, is not a commit of the pull request', async () => {
+    const rewritten = await refusal({ commits: ['e'.repeat(40), COMMIT] });
+    assert.equal(rewritten.error.message, `${wouldNot}the session started on dddddddddddd, which is not one of its commits`);
+    assert.match(rewritten.error.fix, /git push, then \{cli\} run again and attach, or after a rewrite of the branch's history \{cli\} down and \{cli\} up first$/);
+    assert.deepEqual(rewritten.sent, []);
+    const unpushed = await refusal({ commits: [STARTED_ON, 'e'.repeat(40)] });
+    assert.equal(unpushed.error.message, `${wouldNot}the run was made at 0f50b597b1c2, which is not one of its commits`);
+    assert.deepEqual(unpushed.sent, []);
+  });
+
+  it('finds the commit the session started on in a later page of a long pull request', async () => {
+    const many = Array.from({ length: 230 }, (_, i) => i.toString(16).padStart(40, '0'));
+    const found = await handOff({ commits: [...many, STARTED_ON, COMMIT] });
+    assert.equal(found.error, null);
+    assert.equal(found.asked.filter((path) => path.includes('/commits?')).length, 3);
+    assert.equal((await handOff()).asked.filter((path) => path.includes('/commits?')).length, 1);
+  });
+
+  it('sends nothing for a pull request with more commits than GitHub lists when the commits of the run are past the listing, and does not say to start a new session', async () => {
+    const listed = Array.from({ length: 250 }, (_, i) => i.toString(16).padStart(40, '0'));
+    const long = await refusal({ pull: { ...OPEN, commits: 300 }, commits: listed });
+    assert.equal(long.error.message, `${wouldNot}it has 300 commits, GitHub lists only the first 250, and the session started on dddddddddddd, which is not among those`);
+    assert.match(long.error.fix, /squash or rebase the branch to 250 commits or fewer/);
+    assert.deepEqual(long.sent, []);
+  });
+
+  it('sends nothing when the description ends inside a code fence that never closes, as the workflow would refuse it', async () => {
+    const unclosed = await refusal({ pull: { ...OPEN, body: 'How to run it:\r\n\r\n```sh\r\nmake test\r\n' } });
+    assert.equal(unclosed.error.message, `${wouldNot}its description ends inside a code fence that is never closed, so the evidence has no one place to go`);
+    assert.equal(unclosed.error.fix, 'close that code fence, then rerun {cli} attach');
+    assert.deepEqual(unclosed.sent, []);
+  });
+
+  it('sends nothing when the markers in the description would make the workflow refuse, and says which', async () => {
+    const halved = await refusal({ pull: { ...OPEN, body: 'text\r\n<!-- verify-evidence:ios -->\r\nthe end marker was deleted\r\n' } });
+    assert.equal(halved.error.message, `${wouldNot}its description has \`<!-- verify-evidence:ios -->\` 1 times and \`<!-- /verify-evidence:ios -->\` 0 times, so the evidence has no one place to go`);
+    assert.equal(halved.error.fix, 'leave one pair of those markers in the description, or none, then rerun {cli} attach');
+    assert.deepEqual(halved.sent, []);
+    const notes = await refusal({ pull: { ...OPEN, body: '<!-- verify-evidence:ios -->\nreviewer notes\n<!-- /verify-evidence:ios -->\n' } });
+    assert.match(notes.error.message, /that is not an evidence block, so the evidence has no one place to go$/);
+    assert.equal((await handOff({ pull: { ...OPEN, body: null } })).error, null, 'a pull request with no description takes the block');
+  });
+
+  it('sends nothing for a run with no video and no screenshot', async () => {
+    const empty = await refusal({ files: [] });
+    assert.equal(empty.error.message, `${wouldNot}the run has no video and no screenshot, and the workflow publishes nothing without a file`);
+    assert.deepEqual(empty.sent, []);
+  });
+
+  it('says that the session is gone when it does not answer or is ending', async () => {
+    const gone = await refusal({ health: null });
+    assert.equal(gone.error.code, 'LEASE_LOST');
+    assert.match(gone.error.message, /does not answer, so it cannot take the evidence of run r20261008-052713-253e$/);
+    assert.match((await refusal({ health: { ending: 'idle' } })).error.message, /is ending, so it cannot take the evidence/);
+    assert.deepEqual(gone.sent, []);
+  });
+});
diff --git a/e2e-tests/test/host.test.ts b/e2e-tests/test/host.test.ts
index 6d1822c2b..d8a6f744e 100644
--- a/e2e-tests/test/host.test.ts
+++ b/e2e-tests/test/host.test.ts
@@ -1,13 +1,22 @@
 import '../testing/git-env.ts';
 import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { describe, it } from 'node:test';
+import { selectBackend } from '../src/core/devices.ts';
 import { resolveSpecs } from '../src/core/e2e.ts';
 import { STANDARD, declaredIn, planGroups, readSpecText, settingsOf } from '../src/core/instances/settings.ts';
 import type { InstanceSettings } from '../src/core/types.ts';
 import { host } from '../src/host.ts';
+import { LANE_FAILED, LANE_READY, LOG_FILTER, RECORD_SIZE } from '../src/platform/android/emulator.ts';
+import { localAndroidBackend } from '../src/platform/android/local.ts';
+import { systemImage, type Machine } from '../src/platform/android/sdk.ts';
+import sessionDevice from '../src/platform/android/session-device.ts';
 
 const PACKAGE_DIR = join(import.meta.dirname, '..');
+const scratch = mkdtempSync(join(tmpdir(), 'verify-host-'));
+const machine = (overrides: Partial<Machine> = {}): Machine => ({ os: 'darwin', arch: 'arm64', home: scratch, env: {}, kvm: join(scratch, 'kvm'), ...overrides });
 
 describe('the clerk-android golden specs', () => {
   const MFA: InstanceSettings = { config: { auth_multi_factor: { required_for_sign_up: true } }, environment: { 'user_settings.sign_up.mfa.required': true } };
@@ -33,3 +42,47 @@ describe('the clerk-android golden specs', () => {
     for (const group of plan.slice(1)) assert.equal(group.settings.askedBy, group.specs[0]!.path);
   });
 });
+
+describe('the clerk-android host with a remote device', () => {
+  it('tries the local emulator first and falls back to a runner, saying why', () => {
+    assert.deepEqual(host.backends.map((b) => `${b.platform} ${b.kind}`), ['android local', 'android remote']);
+    const runner = 'the device runs on a CI runner \\(ubuntu-24\\.04 unless --runner names another\\), started through verify-remote\\.yml on clerk\\/clerk-android$';
+    const choose = (on: Machine) => selectBackend({ ...host, backends: [localAndroidBackend({ machine: on }), host.backends[1]!] }, 'android', undefined, null);
+    const noKvm = choose(machine({ os: 'linux', arch: 'x64' }));
+    assert.equal(noKvm.backend.kind, 'remote');
+    assert.match(noKvm.why, new RegExp(`^local is out: there is no .*kvm, so this machine has no hardware virtualization for the emulator; ${runner}`));
+    const noSdk = choose(machine());
+    assert.match(noSdk.why, new RegExp(`^local is out: no Android SDK with an emulator and adb .*\\(to run it here: .*ANDROID_HOME.*\\); ${runner}`));
+  });
+
+  it('gives the session workflow the image and the boot files this code uses', () => {
+    const workflow = readFileSync(join(PACKAGE_DIR, '..', '.github', 'workflows', 'verify-remote.yml'), 'utf8');
+    assert.ok(workflow.includes(`IMAGE="${systemImage(machine({ os: 'linux', arch: 'x64' }))}"`), 'the runner installs the image the lane AVD names');
+    for (const file of [LANE_READY, LANE_FAILED]) assert.ok(workflow.includes(`$VERIFY_SESSION_WORK/${file}`), file);
+    assert.ok(workflow.includes('src/platform/android/session-lane.ts" boot "$VERIFY_SESSION_WORK"'));
+  });
+
+  describe('in a session', () => {
+    const device = sessionDevice({ id: 'emulator-5560', platform: 'android' });
+    const line = (command: { command: string; args: readonly string[] }) => `${command.command} ${command.args.join(' ')}`;
+
+    it('assembles the e2e host, waits for the emulator, then installs the debug APK it built', () => {
+      const steps = device.build('/work');
+      assert.deepEqual(steps.map((step) => step.command), ['./gradlew', 'sh', 'adb']);
+      assert.deepEqual(steps[0]!.args, [':e2e:assembleDebug', '--console=plain', '--quiet']);
+      assert.equal(steps[1]!.args.at(-1), '/work');
+      assert.equal(line(steps[2]!), 'adb -s emulator-5560 install -r -t e2e/build/outputs/apk/debug/e2e-debug.apk');
+    });
+
+    it('records to a file on the emulator, stops screenrecord there, then pulls the file', () => {
+      const record = device.record;
+      assert.equal(line(record.start('/work/recording.mp4')), `adb -s emulator-5560 shell screenrecord --size ${RECORD_SIZE} --time-limit 0 /data/local/tmp/verify-session.mp4`);
+      assert.match(line(record.stop!('/work/recording.mp4')[0]!), /^adb -s emulator-5560 shell pkill -INT screenrecord; /);
+      assert.deepEqual(record.collect!('/work/recording.mp4').map(line), ['adb -s emulator-5560 pull /data/local/tmp/verify-session.mp4 /work/recording.mp4', 'adb -s emulator-5560 shell rm -f /data/local/tmp/verify-session.mp4']);
+    });
+
+    it('reads the same logcat tags as the local lane', () => {
+      assert.equal(line(device.logs(new Date(1_791_014_000_123), 'Expo:V')), `adb -s emulator-5560 logcat -d -v threadtime -T 1791014000.123 ${[...LOG_FILTER.slice(0, -1), 'Expo:V', '*:S'].join(' ')}`);
+    });
+  });
+});
diff --git a/e2e-tests/test/lease-flow.test.ts b/e2e-tests/test/lease-flow.test.ts
index 582f52e29..12a0b5c9d 100644
--- a/e2e-tests/test/lease-flow.test.ts
+++ b/e2e-tests/test/lease-flow.test.ts
@@ -110,11 +110,21 @@ describe('lease flow', () => {
       id: 'gh-attach',
       ok: true,
       state: 'warning',
-      detail: "this gh has no `gh pr comment --attach`, so `{cli} attach` cannot post a run's video and screenshots from this machine",
-      fix: 'install a gh build whose `gh pr comment` has --attach',
+      detail: "this gh has no `gh pr edit --attach`, so `{cli} attach` cannot put a run's video and screenshots in a pull request description from this machine",
+      fix: 'install gh 2.99.0 or newer, whose `gh pr edit` has --attach',
     });
   });
 
+  it('refuses --runner with the local backend as a usage error, before it builds, leases, or checks anything', async () => {
+    const { deps, events } = setup(0);
+    const usage = (error: VerifyFailure) => error.code === 'USAGE' && error.message === '--runner names a CI runner and the local backend has none' && error.fix === 'drop --runner, or pass --backend remote';
+    await assert.rejects(up(deps, { verb: 'up', runner: 'some-label', waitSeconds: 0 }), usage);
+    await assert.rejects(leaseForRun(deps, 'ios', { ...runCommand, runner: 'some-label' }, { willChange: false }, async () => undefined), usage);
+    await assert.rejects(doctor(deps, { verb: 'doctor', runner: 'some-label', live: true }), usage);
+    assert.deepEqual(events, []);
+    assert.equal(existsSync(deps.workspace.root), false);
+  });
+
   it('leases no device when no Platform API credential works', async () => {
     const { deps, events } = setup(0);
     const noCredential: Deps['instances'] = { ...deps.instances, access: async () => Promise.reject(new VerifyFailure('KEYS_MISSING', 'no Clerk Platform API credential works here', 'set one')) };
diff --git a/e2e-tests/test/remote-backend.test.ts b/e2e-tests/test/remote-backend.test.ts
new file mode 100644
index 000000000..5088274e2
--- /dev/null
+++ b/e2e-tests/test/remote-backend.test.ts
@@ -0,0 +1,189 @@
+import '../testing/git-env.ts';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, it } from 'node:test';
+import { run } from '../src/core/exec.ts';
+import { remoteBackend } from '../src/core/remote/backend.ts';
+import type { GitHub } from '../src/core/remote/github.ts';
+import { driverId, newSessionRequest, type RemoteSettings } from '../src/core/remote/settings.ts';
+import { BUILD_TIMEOUT_MINUTES, type SessionHealth } from '../src/core/remote/protocol.ts';
+import { VerifyFailure, type BuildKey, type BuiltApp, type RemoteLease } from '../src/core/types.ts';
+
+function repo(): { dir: string; git: (...args: string[]) => string } {
+  const dir = mkdtempSync(join(tmpdir(), 'verify-remote-'));
+  const git = (...args: string[]) => execFileSync('git', ['-c', 'user.name=t', '-c', 'user.email=t@example.com', ...args], { cwd: dir, encoding: 'utf8' }).trim();
+  git('init', '-q');
+  writeFileSync(join(dir, 'App.swift'), 'app');
+  writeFileSync(join(dir, 'README.md'), 'docs');
+  git('add', '-A');
+  git('commit', '-q', '-m', 'one');
+  return { dir, git };
+}
+
+const settings = (dir: string): RemoteSettings => ({
+  platform: 'ios',
+  repo: 'clerk/clerk-ios',
+  workflow: 'verify-remote.yml',
+  sessionsDir: join(dir, '.verify', 'remote'),
+  runner: 'paid-mac',
+  plumbingRunner: 'ubuntu-latest',
+  device: 'iPhone Air',
+  idleMinutes: 15,
+  capMinutes: 60,
+  requirement: 'a pushed branch',
+});
+
+function github(routes: (method: string, path: string) => { status: number; json: unknown }): { hub: GitHub; calls: string[] } {
+  const calls: string[] = [];
+  const hub: GitHub = { repo: 'clerk/clerk-ios', workflow: 'verify-remote.yml', tokenSource: 'none', api: async (method, path) => (calls.push(`${method} ${path}`), { ...routes(method, path), headers: new Headers() }) };
+  return { hub, calls };
+}
+
+describe('the remote backend owns the build', () => {
+  const input = (dir: string) => ({ worktree: dir, inputs: ['App.swift'] });
+
+  it('names the pushed HEAD as the commit to build', async () => {
+    const { dir, git } = repo();
+    const { hub } = github(() => ({ status: 200, json: {} }));
+    assert.equal(await remoteBackend(settings(dir), { env: {}, runner: run, github: async () => hub }).sourceCommit!(input(dir)), git('rev-parse', 'HEAD'));
+  });
+
+  it('refuses a tree whose app sources are edited, and says to commit and push', async () => {
+    const { dir } = repo();
+    writeFileSync(join(dir, 'App.swift'), 'edited');
+    const { hub } = github(() => ({ status: 200, json: {} }));
+    await assert.rejects(
+      remoteBackend(settings(dir), { env: {}, runner: run, github: async () => hub }).sourceCommit!(input(dir)),
+      (error: VerifyFailure) => error.code === 'BUILD_FAILED' && error.message.includes('App.swift') && error.fix.includes('git push'),
+    );
+  });
+
+  it('ignores edits outside the app sources', async () => {
+    const { dir } = repo();
+    writeFileSync(join(dir, 'README.md'), 'edited docs');
+    const { hub } = github(() => ({ status: 200, json: {} }));
+    assert.ok(await remoteBackend(settings(dir), { env: {}, runner: run, github: async () => hub }).sourceCommit!(input(dir)));
+  });
+
+  it('refuses a commit GitHub does not have', async () => {
+    const { dir } = repo();
+    const { hub } = github(() => ({ status: 422, json: { message: 'No commit found' } }));
+    await assert.rejects(
+      remoteBackend(settings(dir), { env: {}, runner: run, github: async () => hub }).sourceCommit!(input(dir)),
+      (error: VerifyFailure) => error.code === 'BUILD_FAILED' && error.fix.startsWith('git push'),
+    );
+  });
+});
+
+describe('the remote backend waits for the session to build', () => {
+  const SHA = 'a'.repeat(40);
+  const realFetch = globalThis.fetch;
+
+  async function installOnASessionWhoseBuildIs(build: SessionHealth['build']): Promise<{ failure: VerifyFailure; asked: string[] }> {
+    const { dir } = repo();
+    const session = join(dir, '.verify', 'remote', 'ios0000cc');
+    mkdirSync(session, { recursive: true });
+    writeFileSync(join(session, 'token'), 'f'.repeat(64));
+    const lease: RemoteLease = { backend: 'remote', provider: 'github-actions', platform: 'ios', session: 'ios0000cc', providerRef: '7', baseUrl: 'https://quick-fox.trycloudflare.com', tokenFile: join(session, 'token'), deviceId: 'UDID-1', deviceName: 'iPhone Air', runner: 'free-mac', expiresAt: '2026-10-13T18:00:00.000Z', builtSha: null, acquiredAt: '2026-10-13T17:00:00.000Z', installedBuild: null };
+    const app: BuiltApp = { platform: 'ios', key: 'ios-k1' as BuildKey, appId: 'com.example.app', path: null, source: 'github-actions', sourceSha: SHA };
+    const health: SessionHealth = { core: 'unread', device: { id: 'UDID-1', name: 'iPhone Air', ready: true }, daemon: true, build, capAt: '2026-10-13T18:00:00.000Z', ending: null };
+    const asked: string[] = [];
+    globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+      const url = new URL(String(input));
+      asked.push(`${init?.method ?? 'GET'} ${url.pathname}${url.search}`);
+      return url.pathname === '/__sim/build' ? Response.json(health, { status: 202 }) : Response.json(health);
+    }) as typeof fetch;
+    try {
+      const { hub } = github(() => ({ status: 200, json: {} }));
+      const failure = await remoteBackend(settings(dir), { env: {}, runner: run, github: async () => hub }).install(lease, app, () => undefined).then(
+        () => assert.fail('the install did not fail'),
+        (error: VerifyFailure) => error,
+      );
+      return { failure, asked };
+    } finally {
+      globalThis.fetch = realFetch;
+    }
+  }
+
+  it('says a build that the session stopped at its limit ran out of time, and to run up again', { timeout: 20_000 }, async () => {
+    const { failure, asked } = await installOnASessionWhoseBuildIs({ state: 'timed-out', sha: SHA, seconds: BUILD_TIMEOUT_MINUTES * 60, tail: 'build   pnpm install took 412s\nbuild   xcodebuild Release (JS embedded)' });
+    assert.deepEqual(asked, [`POST /__sim/build?sha=${SHA}`, 'GET /__sim/health']);
+    assert.equal(failure.code, 'NOT_READY');
+    assert.equal(
+      failure.message,
+      'the session stopped the build of aaaaaaaaaaaa after 45 minutes on free-mac, the longest it lets one build run. The build reported no error before that. Its last lines:\nbuild   pnpm install took 412s\nbuild   xcodebuild Release (JS embedded)',
+    );
+    assert.equal(failure.fix, 'rerun {cli} up, and the same session builds again from what the stopped build left; if that build is stopped too, {cli} down, then {cli} up --runner <a faster runner label>');
+  });
+
+  it('says a build that exited with an error failed, and to fix the error', async () => {
+    const { failure } = await installOnASessionWhoseBuildIs({ state: 'failed', sha: SHA, seconds: 61, tail: 'error: no such module' });
+    assert.deepEqual([failure.code, failure.message, failure.fix], ['BUILD_FAILED', 'the session could not build aaaaaaaaaaaa:\nerror: no such module', 'fix the build error above, commit, push, then rerun {cli} up']);
+  });
+});
+
+describe('session settings', () => {
+  const dir = () => mkdtempSync(join(tmpdir(), 'verify-remote-settings-'));
+
+  it('takes the runner label from the flag, then the default', () => {
+    const s = settings(dir());
+    const ask = (env: Record<string, string>, runner?: string) => newSessionRequest(s, { env, runner: run }, { ...(runner === undefined ? {} : { runner }), device: 'iPhone Air', sha: null }).request;
+    assert.equal(ask({}).runner, 'paid-mac');
+    assert.equal(ask({}, 'other').runner, 'other');
+    assert.equal(ask({ VERIFY_REMOTE_IDLE_MINUTES: '5', VERIFY_REMOTE_CAP_MINUTES: '30' }).idleMinutes, 5);
+    assert.equal(ask({ VERIFY_REMOTE_IDLE_MINUTES: '5', VERIFY_REMOTE_CAP_MINUTES: '30' }).capMinutes, 30);
+    assert.throws(() => ask({ VERIFY_REMOTE_CAP_MINUTES: '100000' }), VerifyFailure);
+  });
+
+  it('refuses a runner label the workflow would reject, before anything is started', () => {
+    assert.throws(
+      () => newSessionRequest(settings(dir()), { env: {}, runner: run }, { runner: 'mac; curl evil', device: null, sha: null }),
+      (error: VerifyFailure) => error.code === 'USAGE' && error.fix.includes('--runner'),
+    );
+  });
+
+  it('never puts the bearer in the request', () => {
+    const { request, token } = newSessionRequest(settings(dir()), { env: {}, runner: run }, { device: null, sha: null });
+    assert.equal(JSON.stringify(request).includes(token), false);
+  });
+
+  it('gives each checkout its own id, even at the same path, and keeps it', () => {
+    const first = settings(dir());
+    assert.match(driverId(first), /^[a-f0-9]{12}$/);
+    assert.equal(driverId(first), driverId(first));
+    assert.notEqual(driverId(first), driverId(settings(dir())));
+  });
+});
+
+describe('reaping', () => {
+  it('lists only the live session runs of this checkout and this platform', async () => {
+    const { dir } = repo();
+    const s = settings(dir);
+    const mine = driverId(s);
+    const { hub } = github((_method, path) => ({
+      status: 200,
+      json: {
+        workflow_runs: path.includes('status=in_progress')
+          ? [
+              { id: 1, display_title: `verify-remote ${mine}/iosaaaaaa`, created_at: '2026-10-05T00:00:00Z' },
+              { id: 2, display_title: 'verify-remote 0123456789ab/iosbbbbbb', created_at: '2026-10-05T00:00:00Z' },
+              { id: 4, display_title: `verify-remote ${mine}/androiddddd`, created_at: '2026-10-05T00:00:00Z' },
+              { id: 5, display_title: `verify-remote ${mine}/probeeeeee`, created_at: '2026-10-05T00:00:00Z' },
+            ]
+          : [{ id: 3, display_title: `verify-remote verify-remote/${mine}/ioscccccc`, created_at: '2026-10-05T00:00:00Z' }],
+      },
+    }));
+    const backend = remoteBackend(s, { env: {}, runner: run, github: async () => hub });
+    assert.deepEqual((await backend.reapable(dir)).map((lease) => [lease.providerRef, lease.session]), [['1', 'iosaaaaaa'], ['3', 'ioscccccc']]);
+    assert.deepEqual(await backend.reapable(), []);
+  });
+
+  it('reaps nothing, and does not fail, when GitHub cannot be reached', async () => {
+    const { dir } = repo();
+    const backend = remoteBackend(settings(dir), { env: {}, runner: run, github: async () => { throw new Error('offline'); } });
+    assert.deepEqual(await backend.reapable(dir), []);
+  });
+});
diff --git a/e2e-tests/test/remote-contract.test.ts b/e2e-tests/test/remote-contract.test.ts
new file mode 100644
index 000000000..5a7ef1947
--- /dev/null
+++ b/e2e-tests/test/remote-contract.test.ts
@@ -0,0 +1,309 @@
+import '../testing/git-env.ts';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync, mkdtempSync } from 'node:fs';
+import net from 'node:net';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, it } from 'node:test';
+import { composeE2EConfig, engineDevice } from '../specs/support/config.ts';
+import { agentDevice } from '../specs/support/device.ts';
+import { inputsEnv, readTarget } from '../specs/support/inputs.ts';
+import { deviceOf } from '../src/core/devices.ts';
+import { chooseEgress, proxyPort } from '../src/core/launch.mjs';
+import { usedSecretValues } from '../specs/support/secret.ts';
+import type { ApiResponse, GitHub } from '../src/core/remote/github.ts';
+import { HANDOFF } from '../src/core/remote/handoff.ts';
+import { connectThroughProxy, egressCheck, remoteDoctorChecks } from '../src/core/remote/preflight.ts';
+import { RUN_TITLE, STEP } from '../src/core/remote/protocol.ts';
+import type { RemoteSettings } from '../src/core/remote/settings.ts';
+import type { LocalLease, RemoteLease } from '../src/core/types.ts';
+import { IOS_APP, SAMPLE_INPUTS } from '../testing/sample-inputs.ts';
+
+describe('the session workflow and the driver agree', () => {
+  const workflow = readFileSync(join(execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: import.meta.dirname, encoding: 'utf8' }).trim(), '.github', 'workflows', 'verify-remote.yml'), 'utf8');
+  const names = [...workflow.matchAll(/^\s+- name: (.+)$/gm)].map((m) => m[1]!);
+  const evaluated = (template: string, value: string) => template.replace(/\$\{\{[^}]+\}\}/, value);
+
+  it('publishes the tunnel in a step name, which the jobs route returns while the job still runs', () => {
+    const tunnel = names.find((name) => name.startsWith('verify-remote tunnel'))!;
+    assert.equal(STEP.tunnelPattern.exec(evaluated(tunnel, 'quick-fox.trycloudflare.com'))?.[1], 'quick-fox.trycloudflare.com');
+  });
+
+  it('titles runs the way the driver looks for them', () => {
+    const request = { owner: '0123456789ab', session: 'iosaaaaaa' };
+    assert.match(workflow, /^run-name: verify-remote \$\{\{ inputs\.owner \}\}\/\$\{\{ inputs\.session \}\}$/m);
+    assert.deepEqual(RUN_TITLE.exec(`verify-remote ${request.owner}/${request.session}`)?.slice(1), [request.owner, request.session]);
+  });
+
+  it('names the job that holds the runner `session`, which is how the driver tells its queue from the plan job\'s', () => {
+    assert.match(workflow, /^  session:\n    needs: plan$/m);
+  });
+
+  it('lets the plan step ask GitHub whether a requested commit is on the dispatched branch, with the read-only token of the run', () => {
+    const planStep = workflow.split(/\n(?= {6}- )/).find((step) => step.includes('session-agent.ts" plan'))!;
+    assert.match(planStep, /^ {10}GITHUB_TOKEN: \$\{\{ github\.token \}\}$/m);
+    assert.match(workflow, /^permissions:\n {2}contents: read\n\n/m);
+  });
+
+  it('lets the session agent ask GitHub the same of every commit it is later asked to build', () => {
+    const agentStep = workflow.split(/\n(?= {6}- )/).find((step) => step.includes('session-agent.ts" serve'))!;
+    assert.match(agentStep, /^ {10}GITHUB_TOKEN: \$\{\{ github\.token \}\}$/m);
+  });
+
+  it('gives the agent the files and variables it waits on', () => {
+    for (const needle of ['VERIFY_SESSION_REQUEST', 'VERIFY_SESSION_WORK', 'VERIFY_SESSION_DEVICE_ID', 'VERIFY_SESSION_DEVICE_MODULE', 'VERIFY_SESSION_CLOUDFLARED', '$WORK/tunnel', 'device-ready', '$VERIFY_SESSION_WORK/ended', 'persist-credentials: false']) {
+      assert.ok(workflow.includes(needle), needle);
+    }
+  });
+
+  it('uploads one artifact, the directory that attach filled, and nothing else of the session', () => {
+    assert.ok(workflow.includes('$RUNNER_TEMP/verify-remote'), 'the agent works in the directory whose evidence folder is uploaded');
+    const uploads = workflow.split(/\n(?= {6}- )/).filter((step) => step.includes('upload-artifact'));
+    assert.equal(uploads.length, 1, 'a public artifact is where a sign-in ticket could leak, so the logs and the build of a session are never uploaded');
+    const upload = uploads[0]!;
+    assert.match(upload, new RegExp(`^ {10}name: ${HANDOFF.artifact}$`, 'm'));
+    assert.match(upload, new RegExp(`^ {10}path: \\$\\{\\{ runner\\.temp \\}\\}/verify-remote/${HANDOFF.directory}/$`, 'm'));
+    assert.match(upload, /^ {8}if: always\(\)$/m, 'a session that idles out or fails still hands over what attach gave it');
+    assert.match(upload, /^ {10}if-no-files-found: ignore$/m);
+  });
+
+  it('runs the agent-device the package pins, installed from its lockfile, and no global one', () => {
+    assert.ok(workflow.includes('npm ci --prefix "$PACKAGE"'));
+    const invocations = workflow.split('\n').map((line) => line.trim()).filter((line) => /agent-device"? (--version|prepare)/.test(line));
+    assert.ok(invocations.length > 0);
+    for (const line of invocations) assert.ok(line.startsWith('"$PACKAGE/node_modules/.bin/agent-device" '), line);
+    assert.doesNotMatch(workflow, /npm (install|i) (-g|--global)/);
+  });
+});
+
+describe('agent-device calls', () => {
+  it('points at the local device with no secret', () => {
+    const lease = { backend: 'local', platform: 'ios', deviceId: 'UDID-1' } as LocalLease;
+    assert.deepEqual(agentDevice(deviceOf(lease), 'ios'), { selector: ['--platform', 'ios', '--udid', 'UDID-1'], env: {} });
+  });
+
+  it('points at a remote daemon and passes the bearer in the environment, registered for redaction', () => {
+    const tokenFile = join(mkdtempSync(join(tmpdir(), 'verify-token-')), 'token');
+    writeFileSync(tokenFile, 'e'.repeat(64));
+    const lease = { backend: 'remote', platform: 'ios', deviceId: 'UDID-2', baseUrl: 'https://x.trycloudflare.com', tokenFile } as RemoteLease;
+    const call = agentDevice(deviceOf(lease), 'ios');
+    assert.deepEqual(call.selector, ['--platform', 'ios', '--udid', 'UDID-2', '--daemon-base-url', 'https://x.trycloudflare.com/agent-device']);
+    assert.deepEqual(call.env, { AGENT_DEVICE_DAEMON_AUTH_TOKEN: 'e'.repeat(64) });
+    assert.ok(usedSecretValues().includes('e'.repeat(64)));
+  });
+});
+
+describe('a borrowed device as the tests are told of it', () => {
+  const tokenFile = join(mkdtempSync(join(tmpdir(), 'verify-token-')), 'token');
+  writeFileSync(tokenFile, `${'f'.repeat(64)}\n`);
+  const lease = { backend: 'remote', platform: 'ios', deviceId: 'AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE', baseUrl: 'https://x.trycloudflare.com', tokenFile } as RemoteLease;
+  const target = { platform: 'ios' as const, device: deviceOf(lease), session: 'verify-ios-abc', build: { path: null, devServer: null } };
+
+  it('is its id, the address of its daemon, and the file that holds the daemon token, and reads back the same', () => {
+    assert.deepEqual(target.device, { kind: 'borrowed', id: 'AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE', daemonUrl: 'https://x.trycloudflare.com/agent-device', tokenFile });
+    const env = inputsEnv({ ...SAMPLE_INPUTS, target });
+    assert.deepEqual([env.CLERK_E2E_DEVICE_DAEMON_URL, env.CLERK_E2E_DEVICE_DAEMON_TOKEN_FILE], ['https://x.trycloudflare.com/agent-device', tokenFile]);
+    assert.equal(JSON.stringify(env).includes('f'.repeat(64)), false, 'the token itself is not in the environment the CLI writes');
+    assert.deepEqual(readTarget(IOS_APP, env), target);
+  });
+
+  it('needs the token file with the daemon address, and an address that is one', () => {
+    const env = inputsEnv({ ...SAMPLE_INPUTS, target });
+    assert.throws(() => readTarget(IOS_APP, { ...env, CLERK_E2E_DEVICE_DAEMON_TOKEN_FILE: undefined }), /CLERK_E2E_DEVICE_DAEMON_TOKEN_FILE is not/);
+    assert.throws(() => readTarget(IOS_APP, { ...env, CLERK_E2E_DEVICE_DAEMON_URL: 'x.trycloudflare.com' }), /is not the http or https address of an agent-device daemon/);
+  });
+
+  it('reaches e2e as a device that is already there, with the daemon token read from its file when e2e asks', async () => {
+    const config = composeE2EConfig(IOS_APP, target, {});
+    assert.equal(JSON.stringify(config).includes('f'.repeat(64)), false, 'the token is not in the composed config');
+    const provider = engineDevice(target.device);
+    assert.ok(!Array.isArray(provider) && 'acquire' in provider);
+    assert.deepEqual(await provider.acquire({} as unknown as Parameters<typeof provider.acquire>[0]), {
+      id: 'AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE',
+      deviceId: 'AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE',
+      device: 'AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE',
+      daemon: { baseUrl: 'https://x.trycloudflare.com/agent-device', authToken: 'f'.repeat(64) },
+    });
+    assert.ok(usedSecretValues().includes('f'.repeat(64)));
+  });
+});
+
+describe('choosing between a direct connection and HTTPS_PROXY', () => {
+  it('happens in plain JavaScript that imports only Node built-ins, so a Node too old to load TypeScript can still run it and hand over to Node 24', () => {
+    const source = readFileSync(join(import.meta.dirname, '..', 'src', 'core', 'launch.mjs'), 'utf8');
+    const imported = [...source.matchAll(/\bfrom\s+'([^']+)'/g)].map((match) => match[1]!);
+    assert.ok(imported.length > 0);
+    assert.deepEqual(imported.filter((specifier) => !specifier.startsWith('node:')), []);
+    assert.doesNotMatch(source, /\bimport\s*\(/);
+  });
+
+  it('keeps a Mac with a debugging proxy exported on its direct connection', () => {
+    assert.equal(chooseEgress({ proxyListens: true, directConnects: true, tokenStatusDirect: null }).proxy, false);
+    assert.equal(chooseEgress({ proxyListens: true, directConnects: true, tokenStatusDirect: 200 }).proxy, false);
+    assert.equal(chooseEgress({ proxyListens: false, directConnects: true, tokenStatusDirect: null }).proxy, false);
+  });
+
+  it('uses the proxy in a sandbox whose token only works through it, although a direct connection opens', () => {
+    const choice = chooseEgress({ proxyListens: true, directConnects: true, tokenStatusDirect: 401 });
+    assert.equal(choice.proxy, true);
+    assert.match(choice.why, /rejects this machine's token on a direct connection/);
+  });
+
+  it('probes an https proxy on 443 and an http proxy on 80 when the URL names no port', () => {
+    assert.equal(proxyPort(new URL('https://proxy.example')), 443);
+    assert.equal(proxyPort(new URL('http://proxy.example')), 80);
+    assert.equal(proxyPort(new URL('https://proxy.example:8443')), 8443);
+    assert.equal(proxyPort(new URL('http://proxy.example:3128')), 3128);
+  });
+
+  it('uses the proxy when it is the only way out', () => {
+    assert.equal(chooseEgress({ proxyListens: true, directConnects: false, tokenStatusDirect: null }).proxy, true);
+    assert.equal(chooseEgress({ proxyListens: true, directConnects: true, tokenStatusDirect: 0 }).proxy, true);
+  });
+});
+
+describe('egress checks', () => {
+  async function proxyAnswering(line: string): Promise<{ url: URL; close: () => void }> {
+    const server = net.createServer((socket) => socket.once('data', () => socket.end(`${line}\r\n\r\n`)));
+    await new Promise<void>((done) => server.listen(0, '127.0.0.1', done));
+    return { url: new URL(`http://127.0.0.1:${(server.address() as net.AddressInfo).port}`), close: () => server.close() };
+  }
+
+  it('reports a refused CONNECT as blocked, with the proxy status line and the fix', async () => {
+    const proxy = await proxyAnswering('HTTP/1.1 403 Forbidden');
+    try {
+      assert.deepEqual(await connectThroughProxy(proxy.url, 'x.trycloudflare.com'), { status: 403, line: 'HTTP/1.1 403 Forbidden' });
+      const check = await egressCheck('tunnel-egress', 'x.trycloudflare.com', { HTTPS_PROXY: proxy.url.href, NODE_USE_ENV_PROXY: '1' }, 'allow the host');
+      assert.equal(check.ok, false);
+      assert.match(check.detail, /^blocked: the proxy at 127\.0\.0\.1:\d+ answered the CONNECT to x\.trycloudflare\.com with "HTTP\/1\.1 403 Forbidden"$/);
+      assert.equal(check.fix, 'allow the host');
+    } finally {
+      proxy.close();
+    }
+  });
+
+  it('sends the credentials of the proxy URL with the CONNECT, percent-decoded, and sends none when the URL has no password, as Node does', async () => {
+    const heads: string[] = [];
+    const expected = `Proxy-Authorization: Basic ${Buffer.from('us@er:p:ss').toString('base64')}`;
+    const server = net.createServer((socket) =>
+      socket.once('data', (head: Buffer) => {
+        heads.push(head.toString('latin1'));
+        socket.end(`HTTP/1.1 ${heads.at(-1)!.split('\r\n').includes(expected) ? '200 Connection established' : '407 Proxy Authentication Required'}\r\n\r\n`);
+      }),
+    );
+    await new Promise<void>((done) => server.listen(0, '127.0.0.1', done));
+    const at = `127.0.0.1:${(server.address() as net.AddressInfo).port}`;
+    try {
+      assert.deepEqual(await connectThroughProxy(new URL(`http://us%40er:p%3Ass@${at}`), 'x.trycloudflare.com'), { status: 200, line: 'HTTP/1.1 200 Connection established' });
+      assert.equal((await connectThroughProxy(new URL(`http://${at}`), 'x.trycloudflare.com')).status, 407);
+      assert.equal(heads[1], 'CONNECT x.trycloudflare.com:443 HTTP/1.1\r\nHost: x.trycloudflare.com:443\r\n\r\n');
+      await connectThroughProxy(new URL(`http://useronly@${at}`), 'x.trycloudflare.com');
+      assert.equal(heads[2], heads[1]);
+    } finally {
+      server.close();
+    }
+  });
+
+  it('counts only an answer with Cloudflare headers as reached, because a sandbox can answer in the host\'s place', async () => {
+    const answering = (status: number, headers: Record<string, string>) => (async () => new Response('', { status, headers })) as typeof fetch;
+    const reached = await egressCheck('clerk-egress', 'api.clerk.com', {}, 'allow the host', answering(404, { server: 'cloudflare', 'cf-ray': 'abc' }));
+    assert.deepEqual(reached, { id: 'clerk-egress', ok: true, detail: 'reached api.clerk.com: HTTP 404 from cloudflare' });
+    const intercepted = await egressCheck('clerk-egress', 'api.clerk.com', {}, 'allow the host', answering(403, {}));
+    assert.equal(intercepted.ok, false);
+    assert.match(intercepted.detail, /^blocked: api\.clerk\.com answered HTTP 403 without Cloudflare's headers/);
+    assert.equal(intercepted.fix, 'allow the host');
+  });
+
+  it('says so when the proxy itself is unreachable', async () => {
+    assert.equal((await connectThroughProxy(new URL('http://127.0.0.1:9'), 'x.trycloudflare.com')).status, 0);
+  });
+});
+
+describe('doctor for the remote backend', () => {
+  const settings = (): RemoteSettings => ({ platform: 'ios', repo: 'clerk/clerk-ios', workflow: 'verify-remote.yml', sessionsDir: join(mkdtempSync(join(tmpdir(), 'verify-doctor-')), 'remote'), runner: 'paid-mac', plumbingRunner: 'ubuntu-latest', device: 'iPhone Air', idleMinutes: 15, capMinutes: 60, requirement: '' });
+  const answer = (status: number, json: unknown = {}, firstRefusalWithToken?: string): ApiResponse => ({ status, json, headers: new Headers(), ...(firstRefusalWithToken === undefined ? {} : { firstRefusalWithToken }) });
+  const offline = { HTTPS_PROXY: 'http://127.0.0.1:9', NODE_USE_ENV_PROXY: '1' };
+  const git = (pushFails: boolean) => async (command: string, args: readonly string[]) => {
+    if (command === 'git' && args[0] === 'push' && pushFails) {
+      return { code: 128, stdout: '', stderr: "remote: the app has no access to this repository\nfatal: unable to access 'https://github.com/clerk/clerk-ios/': The requested URL returned error: 403\n" };
+    }
+    return { code: 0, stdout: args.includes('--abbrev-ref') ? 'my-branch\n' : 'f'.repeat(40), stderr: '' };
+  };
+
+  it('prints every check even when GitHub refuses everything, and says what each skipped check needed', async () => {
+    const github: GitHub = { repo: 'clerk/clerk-ios', workflow: 'verify-remote.yml', tokenSource: 'GH_TOKEN', api: async () => answer(401, { message: 'Bad credentials' }) };
+    const { device } = await remoteDoctorChecks(settings(), { env: offline, runner: git(true) }, async () => github, { live: true, worktree: '/w', progress: () => undefined });
+    const byId = Object.fromEntries(device.map((c) => [c.id, c]));
+    for (const id of ['git-fetch', 'git-push', 'github-rest', 'remote-commit', 'tunnel-egress', 'clerk-egress', 'live-session', 'live-sim-health', 'live-daemon-health', 'live-device', 'live-stop']) {
+      assert.ok(byId[id] !== undefined, `${id} is printed`);
+    }
+    assert.match(byId['git-push']!.detail, /the app has no access to this repository \| fatal: unable to access .* 403/);
+    assert.match(byId['git-push']!.fix!, /A 403 on git push means this machine's GitHub credential may not push to the repository/);
+    assert.equal(byId['github-rest']!.ok, false);
+    assert.equal(byId['live-session']!.detail, 'not run: needs github-rest');
+    assert.equal(byId['live-stop']!.detail, 'not run: needs github-rest');
+    assert.equal(byId['live-stop']!.state, 'not-run');
+  });
+
+  it('with --live, prints live-device as not run when the session never starts, with or without --runner', async () => {
+    const neverStarts = (): GitHub => ({
+      repo: 'clerk/clerk-ios',
+      workflow: 'verify-remote.yml',
+      tokenSource: 'gh',
+      api: async (method) => (method === 'POST' ? answer(401, { message: 'Bad credentials' }) : answer(200, { workflow_runs: [] })),
+    });
+    const live = async (runner?: string) => {
+      const { device } = await remoteDoctorChecks(settings(), { env: offline, runner: git(true) }, async () => neverStarts(), { live: true, ...(runner === undefined ? {} : { runner }), worktree: '/w', progress: () => undefined });
+      return Object.fromEntries(device.map((c) => [c.id, c]));
+    };
+    const plain = await live();
+    assert.equal(plain['live-session']!.ok, false);
+    assert.equal(plain['live-device']!.detail, 'not run: this session boots no device; --runner <label> names a runner that has one');
+    assert.equal(plain['live-stop']!.detail, 'not run: needs live-session');
+    assert.equal((await live('some-mac'))['live-device']!.detail, 'not run: needs live-session');
+  });
+
+  it('without --live reads only: starts no run, writes nothing, and says what --live would prove', async () => {
+    const calls: string[] = [];
+    const github: GitHub = { repo: 'clerk/clerk-ios', workflow: 'verify-remote.yml', tokenSource: 'gh', api: async (method, path) => (calls.push(`${method} ${path}`), answer(200, { workflow_runs: [] })) };
+    const reads = git(false);
+    const runner: typeof reads = (command, args) => (calls.push(`${command} ${args.join(' ')}`), reads(command, args));
+    const progress: string[] = [];
+    const s = settings();
+    const { device } = await remoteDoctorChecks(s, { env: offline, runner }, async () => github, { live: false, worktree: '/w', progress: (line) => void progress.push(line) });
+    assert.deepEqual(calls.filter((call) => call.startsWith('POST') || (call.startsWith('git push') && !call.includes('--dry-run'))), []);
+    assert.equal(existsSync(s.sessionsDir), false, 'no owner id is made for a doctor that starts nothing');
+    const unrun = ['live-session', 'live-sim-health', 'live-daemon-health', 'live-device', 'live-stop'];
+    assert.deepEqual(device.filter((c) => c.state === 'not-run').map((c) => c.id), unrun);
+    for (const c of device.filter((c) => unrun.includes(c.id))) assert.deepEqual([c.ok, c.detail], [true, 'not run: doctor starts no workflow run without --live'], c.id);
+    assert.equal(device.find((c) => c.id === 'remote-commit')!.ok, true);
+    assert.deepEqual(progress, ['doctor  git and REST reads only: nothing was started; rerun with --live to start one short session, which proves the rest']);
+  });
+
+  it('keeps reading a public repository when the token is refused, and says the token is the problem', async () => {
+    const github: GitHub = {
+      repo: 'clerk/clerk-ios',
+      workflow: 'verify-remote.yml',
+      tokenSource: 'GH_TOKEN',
+      api: async (method, path) => (method === 'POST' ? answer(401, { message: 'Bad credentials' }) : path.includes('/workflows/') ? answer(200, { workflow_runs: [] }) : answer(200, {}, '401 Bad credentials')),
+    };
+    const { device } = await remoteDoctorChecks(settings(), { env: offline, runner: git(true) }, async () => github, { live: true, worktree: '/w', progress: () => undefined });
+    const byId = Object.fromEntries(device.map((c) => [c.id, c]));
+    assert.equal(byId['github-rest']!.ok, true);
+    assert.match(byId['github-rest']!.detail, /repository 200 without the token \(with it: 401 Bad credentials\).*GitHub refuses this machine's token/);
+    assert.equal(byId['remote-commit']!.ok, true);
+    assert.equal(byId['live-session']!.ok, false);
+    assert.match(byId['live-session']!.detail, /GitHub refused the dispatch of verify-remote\.yml \(401 Bad credentials\)/);
+    assert.match(byId['live-session']!.fix!, /the sandbox's GitHub integration/);
+  });
+
+  it('with --live, starts no session for a HEAD that GitHub does not have', async () => {
+    const calls: string[] = [];
+    const github: GitHub = { repo: 'clerk/clerk-ios', workflow: 'verify-remote.yml', tokenSource: 'gh', api: async (method, path) => (calls.push(`${method} ${path}`), path.startsWith('/commits/') ? answer(422) : answer(200, { workflow_runs: [] })) };
+    const { device } = await remoteDoctorChecks(settings(), { env: offline, runner: git(false) }, async () => github, { live: true, worktree: '/w', progress: () => undefined });
+    assert.equal(device.find((c) => c.id === 'live-session')!.detail, 'not run: needs remote-commit');
+    assert.equal(calls.some((call) => call.startsWith('POST')), false);
+  });
+});
+
diff --git a/e2e-tests/test/remote-lease-flow.test.ts b/e2e-tests/test/remote-lease-flow.test.ts
new file mode 100644
index 000000000..fb9794873
--- /dev/null
+++ b/e2e-tests/test/remote-lease-flow.test.ts
@@ -0,0 +1,194 @@
+import '../testing/git-env.ts';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { heldInstances } from '../testing/fake-instances.ts';
+import { describe, it } from 'node:test';
+import { doctor, down, up, type Deps } from '../src/core/verbs.ts';
+import { openWorkspace } from '../src/core/workspace.ts';
+import { VerifyFailure, type BuiltApp, type DeviceBackend, type HostAdapter, type RemoteLease } from '../src/core/types.ts';
+
+const shaOf = (app: BuiltApp): string | null => (app.source === 'local' ? null : app.sourceSha);
+
+function setup() {
+  const dir = mkdtempSync(join(tmpdir(), 'verify-remote-flow-'));
+  execFileSync('git', ['init', '-q'], { cwd: dir });
+  writeFileSync(join(dir, 'app.swift'), 'one');
+  const events: string[] = [];
+  const progress: string[] = [];
+  const finished: string[] = [];
+  let sha = 'a'.repeat(40);
+  let health: 'held' | 'lost' = 'held';
+  let pushed = true;
+  let stuck = false;
+  const lease = (session: string): RemoteLease => ({ backend: 'remote', provider: 'github-actions', platform: 'ios', session, providerRef: '1', baseUrl: 'https://x.trycloudflare.com', tokenFile: join(dir, 'token'), deviceId: 'UDID', deviceName: 'iPhone Air', runner: 'mac-runner', expiresAt: '2026-10-05T01:00:00Z', builtSha: null, acquiredAt: '', installedBuild: null });
+  let sessions = 0;
+  const inputsAskedFor: string[] = [];
+  const remote = {
+    kind: 'remote',
+    platform: 'ios',
+    requirement: 'a pushed branch',
+    availability: () => ({ usable: true, why: 'a device on a runner' }),
+    async sourceCommit(): Promise<string> {
+      if (!pushed) throw new VerifyFailure('BUILD_FAILED', 'GitHub does not have HEAD', 'git push, then rerun');
+      return sha;
+    },
+    reapable: async () => [],
+    check: async () => health,
+    async acquire(request: { app: BuiltApp; runner?: string }) {
+      sessions += 1;
+      events.push(`acquire sha=${shaOf(request.app)?.slice(0, 1)} runner=${request.runner ?? 'default'}`);
+      return { ...lease(`s${sessions}`), ...(request.runner === undefined ? {} : { runner: request.runner }) };
+    },
+    async install(held: RemoteLease, app: BuiltApp): Promise<RemoteLease> {
+      events.push(`install ${held.session} sha=${shaOf(app)?.slice(0, 1)}`);
+      return { ...held, builtSha: shaOf(app) };
+    },
+    async release(held: RemoteLease) {
+      events.push(`release ${held.session}`);
+      if (stuck) throw new VerifyFailure('NOT_READY', 'the run would not end', 'cancel it');
+    },
+    describe: (held: RemoteLease) => `${held.deviceName} on ${held.runner}`,
+    doctorChecks: async () => ({ toolchain: [], device: [] }),
+  } as unknown as DeviceBackend;
+  const local = { kind: 'local', platform: 'ios', requirement: 'a Mac with Xcode', availability: () => ({ usable: false, why: 'the iOS simulator needs macOS and this machine runs linux' }) } as unknown as DeviceBackend;
+  const host = {
+    repo: 'clerk-ios',
+    platforms: ['ios'],
+    backends: [local, remote],
+    appId: () => 'com.clerk.E2EHost',
+    entry: () => ({ kind: 'binary' }),
+    buildInputs: (_platform: string, backend: string) => (inputsAskedFor.push(backend), ['app.swift']),
+    build: async () => {
+      throw new Error('a backend that builds must never trigger a local build');
+    },
+  } as unknown as HostAdapter;
+  const workspace = openWorkspace({ packageDir: dir, worktree: dir, home: join(dir, 'home') });
+  const deps: Deps = {
+    host,
+    workspace,
+    runner: async () => ({ code: 1, stdout: '', stderr: '' }),
+    env: {},
+    progress: (line: string) => void progress.push(line),
+    instances: heldInstances({ finish: async (ledger) => (finished.push(ledger.worktree), []) }),
+  };
+  const edit = (text: string, newSha: string) => {
+    writeFileSync(join(dir, 'app.swift'), text);
+    sha = newSha.repeat(40);
+  };
+  return { deps, events, progress, edit, commit: (newSha: string) => (sha = newSha.repeat(40)), lose: () => (health = 'lost'), unpush: () => (pushed = false), stick: () => (stuck = true), finished, inputsAskedFor };
+}
+
+describe('lease flow with a backend that builds the app', () => {
+  it('falls through to remote on a machine that cannot run the device, says why, and builds nothing locally', async () => {
+    const { deps, events, progress, inputsAskedFor } = setup();
+    const result = await up(deps, { verb: 'up', waitSeconds: 0 });
+    assert.deepEqual([...new Set(inputsAskedFor)], ['remote'], 'the host learns which backend the build is for');
+    assert.equal(progress[0], 'backend remote  local is out: the iOS simulator needs macOS and this machine runs linux; a device on a runner');
+    assert.deepEqual(events, ['acquire sha=a runner=default', 'install s1 sha=a']);
+    assert.equal(result.leases[0]!.backend, 'remote');
+    assert.equal(result.builds[0]!.source, 'github-actions');
+    const held = deps.workspace.readLease('ios') as RemoteLease;
+    assert.equal(held.builtSha, 'a'.repeat(40));
+    assert.equal(held.installedBuild, result.builds[0]!.key);
+  });
+
+  it('rebuilds on the held session after an edit instead of leasing a new one', async () => {
+    const { deps, events, edit } = setup();
+    await up(deps, { verb: 'up', waitSeconds: 0 });
+    await up(deps, { verb: 'up', waitSeconds: 0 });
+    assert.equal(events.length, 2, 'an unchanged tree neither leases nor installs again');
+    edit('two', 'b');
+    await up(deps, { verb: 'up', waitSeconds: 0 });
+    assert.deepEqual(events.slice(2), ['install s1 sha=b']);
+    assert.equal((deps.workspace.readLease('ios') as RemoteLease).builtSha, 'b'.repeat(40));
+  });
+
+  it('leases a new session when the held one has stopped itself', async () => {
+    const { deps, events, progress, lose } = setup();
+    await up(deps, { verb: 'up', waitSeconds: 0 });
+    lose();
+    const result = await up(deps, { verb: 'up', waitSeconds: 0 });
+    assert.deepEqual(events.slice(2), ['release s1', 'acquire sha=a runner=default', 'install s2 sha=a']);
+    assert.ok(progress.some((line) => line.startsWith('lost    iPhone Air on mac-runner')));
+    assert.equal(result.leases[0]!.renewed, true);
+  });
+
+  it('asks the new session for the commit the branch has now when a commit that left the app alone was pushed after the lost one built', async () => {
+    const { deps, events, commit, lose } = setup();
+    await up(deps, { verb: 'up', waitSeconds: 0 });
+    commit('b');
+    lose();
+    await up(deps, { verb: 'up', waitSeconds: 0 });
+    assert.deepEqual(events.slice(2), ['release s1', 'acquire sha=b runner=default', 'install s2 sha=b']);
+    assert.equal((deps.workspace.readLease('ios') as RemoteLease).builtSha, 'b'.repeat(40));
+  });
+
+  it('asks the new session for the commit the lost one built when the newer commit left the app alone and is not pushed', async () => {
+    const { deps, events, commit, lose, unpush } = setup();
+    await up(deps, { verb: 'up', waitSeconds: 0 });
+    commit('b');
+    unpush();
+    lose();
+    await up(deps, { verb: 'up', waitSeconds: 0 });
+    assert.deepEqual(events.slice(2), ['release s1', 'acquire sha=a runner=default', 'install s2 sha=a']);
+  });
+
+  it('passes --runner to the session and refuses a different label while a session is held', async () => {
+    const { deps, events } = setup();
+    await up(deps, { verb: 'up', runner: 'free-mac', waitSeconds: 0 });
+    assert.equal(events[0], 'acquire sha=a runner=free-mac');
+    await assert.rejects(up(deps, { verb: 'up', runner: 'other-mac', waitSeconds: 0 }), (error: VerifyFailure) => error.code === 'NOT_READY' && error.message.includes('free-mac'));
+  });
+
+  it('doctor reports the chosen backend and whether the session holds the current build', async () => {
+    const { deps } = setup();
+    const before = await doctor(deps, { verb: 'doctor', live: false });
+    assert.deepEqual(before.backend, { ios: 'remote' });
+    assert.match(before.checks.find((c) => c.id === 'backend')!.detail, /^remote  local is out:/);
+    assert.equal(before.checks.find((c) => c.id === 'build')!.ok, false);
+    assert.equal(before.checks.find((c) => c.id === 'build')!.fix, 'commit and push, then {cli} up');
+    const forced = await doctor({ ...deps, host: { ...deps.host, platforms: ['ios', 'android'] } }, { verb: 'doctor', platform: 'ios', backend: 'remote', live: false });
+    assert.equal(forced.checks.find((c) => c.id === 'build')!.fix, 'commit and push, then {cli} up --platform ios --backend remote');
+    await up(deps, { verb: 'up', waitSeconds: 0 });
+    const after = await doctor(deps, { verb: 'doctor', live: false });
+    assert.equal(after.checks.find((c) => c.id === 'build')!.ok, true);
+    assert.match(after.checks.find((c) => c.id === 'build')!.detail, /commit aaaaaaaaaaaa/);
+  });
+
+  it('needs no push for a commit that leaves the app sources alone', async () => {
+    const { deps, events, unpush } = setup();
+    await up(deps, { verb: 'up', waitSeconds: 0 });
+    unpush();
+    await up(deps, { verb: 'up', waitSeconds: 0 });
+    assert.equal(events.length, 2, 'the session already holds this build, so an unpushed spec or docs commit is fine');
+  });
+
+  it('still asks for a push once the app sources change', async () => {
+    const { deps, edit, unpush } = setup();
+    await up(deps, { verb: 'up', waitSeconds: 0 });
+    edit('two', 'b');
+    unpush();
+    await assert.rejects(up(deps, { verb: 'up', waitSeconds: 0 }), (error: VerifyFailure) => error.code === 'BUILD_FAILED' && error.fix.startsWith('git push'));
+  });
+
+  it('down finishes the instances even when the session will not end, then reports the session', async () => {
+    const { deps, stick, finished } = setup();
+    await up(deps, { verb: 'up', waitSeconds: 0 });
+    stick();
+    await assert.rejects(down(deps, { verb: 'down', stale: false, dryRun: false }), (error: VerifyFailure) => error.message === 'the run would not end');
+    assert.deepEqual(finished, [deps.workspace.worktree]);
+    assert.ok(deps.workspace.readLease('ios') !== null, 'the lease stays so a later down can retry');
+  });
+
+  it('down releases the session', async () => {
+    const { deps, events } = setup();
+    await up(deps, { verb: 'up', waitSeconds: 0 });
+    const result = await down(deps, { verb: 'down', stale: false, dryRun: false });
+    assert.equal(events.at(-1), 'release s1');
+    assert.equal(result.dryRun === false && result.released[0]!.device, 'iPhone Air on mac-runner');
+    assert.equal(deps.workspace.readLease('ios'), null);
+  });
+});
diff --git a/e2e-tests/test/remote.test.ts b/e2e-tests/test/remote.test.ts
new file mode 100644
index 000000000..bcee4c552
--- /dev/null
+++ b/e2e-tests/test/remote.test.ts
@@ -0,0 +1,245 @@
+import '../testing/git-env.ts';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { describe, it } from 'node:test';
+import { selectBackend } from '../src/core/devices.ts';
+import type { ExecResult } from '../src/core/exec.ts';
+import { openGitHub, publishedStep, startRun, waitReporter, type GitHub, type JobView } from '../src/core/remote/github.ts';
+import { RUN_TITLE, RequestError, STEP, matchesToken, parseRequest, sha256Hex, type SessionRequest } from '../src/core/remote/protocol.ts';
+import { tunnelUrl } from '../src/core/remote/session.ts';
+import { TUNNEL } from '../src/core/remote/tunnel.ts';
+import { VerifyFailure, type DeviceBackend, type HostAdapter } from '../src/core/types.ts';
+
+const token = 'a'.repeat(64);
+const request: SessionRequest = {
+  v: 1,
+  session: 'ios12ab34',
+  owner: '0123456789ab',
+  platform: 'ios',
+  runner: 'blacksmith-6vcpu-macos-27',
+  device: 'iPhone Air',
+  sha: 'f'.repeat(40),
+  idleMinutes: 15,
+  capMinutes: 60,
+  tokenSha256: sha256Hex(token),
+};
+
+describe('session request', () => {
+  it('round-trips a valid request and accepts no device and no commit', () => {
+    assert.deepEqual(parseRequest(JSON.stringify(request)), request);
+    assert.deepEqual(parseRequest(JSON.stringify({ ...request, device: null, sha: null })), { ...request, device: null, sha: null });
+  });
+
+  it('refuses anything a shell or a runs-on could misread', () => {
+    const bad: Record<string, unknown>[] = [
+      { runner: 'ubuntu-latest; curl evil' },
+      { runner: '${{ secrets.X }}' },
+      { device: 'iPhone"; rm -rf /' },
+      { sha: 'main' },
+      { session: '../x' },
+      { owner: 'someone' },
+      { capMinutes: 100000 },
+      { idleMinutes: 0 },
+      { idleMinutes: 61 },
+      { tokenSha256: token.slice(1) },
+      { v: 2 },
+    ];
+    for (const change of bad) assert.throws(() => parseRequest(JSON.stringify({ ...request, ...change })), RequestError, JSON.stringify(change));
+    assert.throws(() => parseRequest('docs: an ordinary commit message'), RequestError);
+  });
+
+  it('recognizes the bearer by its hash and nothing else', () => {
+    assert.equal(matchesToken(request.tokenSha256, token), true);
+    assert.equal(matchesToken(request.tokenSha256, `${token}x`), false);
+    assert.equal(matchesToken(request.tokenSha256, request.tokenSha256), false);
+  });
+
+  it('titles a run so the owner and session can be read back', () => {
+    assert.deepEqual(RUN_TITLE.exec(`verify-remote ${request.owner}/${request.session}`)?.slice(1), [request.owner, request.session]);
+    assert.equal(RUN_TITLE.exec('verify-remote feature/some-branch'), null);
+  });
+});
+
+describe('the step-name channel', () => {
+  const job = (steps: readonly string[]): JobView => ({ name: 'session', status: 'in_progress', steps: steps.map((name) => ({ name, status: 'completed', conclusion: 'success' })) });
+
+  it('reads the tunnel host, and reads nothing before the step has its value', () => {
+    assert.equal(publishedStep([job(['Set up job', 'verify-remote tunnel quick-fox-jumps.trycloudflare.com'])], STEP.tunnelPattern), 'quick-fox-jumps.trycloudflare.com');
+    assert.equal(publishedStep([job(['Set up job', 'verify-remote tunnel '])], STEP.tunnelPattern), null);
+    assert.equal(publishedStep([job(['verify-remote tunnel ${{ steps.tunnel.outputs.host }}'])], STEP.tunnelPattern), null);
+  });
+
+  it('refuses to send the bearer to a host outside the tunnel domain', () => {
+    assert.equal(tunnelUrl('quick-fox-jumps.trycloudflare.com'), 'https://quick-fox-jumps.trycloudflare.com');
+    for (const host of ['evil.example.com', 'trycloudflare.com.evil.example', 'x.trycloudflare.com:8443', 'x.trycloudflare.com/@evil', TUNNEL.probeHost]) {
+      assert.throws(() => tunnelUrl(host), VerifyFailure, host);
+    }
+  });
+
+  it('does not take the address cloudflared asks for a tunnel as the tunnel', () => {
+    const refused = 'ERR failed to request quick Tunnel: Post "https://api.trycloudflare.com/tunnel": context deadline exceeded';
+    assert.equal(TUNNEL.hostPattern.exec(refused), null);
+    assert.equal(TUNNEL.hostPattern.exec(`${refused}\n|  https://quick-fox-jumps.trycloudflare.com  |`)?.[1], 'quick-fox-jumps.trycloudflare.com');
+  });
+});
+
+describe('starting a run', () => {
+  function fakeGitHub(dispatchStatus: number, runs: readonly { id: number; display_title: string }[]): { github: GitHub; calls: string[]; dispatched: unknown[] } {
+    const calls: string[] = [];
+    const dispatched: unknown[] = [];
+    const github: GitHub = {
+      repo: 'clerk/clerk-ios',
+      workflow: 'verify-remote.yml',
+      tokenSource: 'none',
+      async api(method, path, body) {
+        calls.push(`${method} ${path}`);
+        if (path.endsWith('/dispatches')) dispatched.push(body);
+        if (path.endsWith('/dispatches')) return { status: dispatchStatus, json: dispatchStatus === 200 ? { workflow_run_id: 41 } : dispatchStatus === 204 ? null : { message: 'Resource not accessible by integration' }, headers: new Headers() };
+        return { status: 200, json: { workflow_runs: runs }, headers: new Headers() };
+      },
+    };
+    return { github, calls, dispatched };
+  }
+  const ok = (): ExecResult => ({ code: 0, stdout: '', stderr: '' });
+
+  it('uses the run id a dispatch returns', async () => {
+    const { github, dispatched } = fakeGitHub(200, []);
+    assert.equal(await startRun(github, request, { ref: 'feature/branch' }), '41');
+    assert.deepEqual(dispatched[0], { ref: 'feature/branch', inputs: { owner: request.owner, session: request.session, request: JSON.stringify(request) }, return_run_details: true });
+  });
+
+  it('finds its own run by title when a dispatch answers 204 with no run id', async () => {
+    const { github, calls } = fakeGitHub(204, [
+      { id: 51, display_title: `verify-remote ${request.owner}/iosother11` },
+      { id: 52, display_title: `verify-remote ${request.owner}/${request.session}` },
+    ]);
+    assert.equal(await startRun(github, request, { ref: 'feature/branch' }), '52');
+    assert.ok(calls.some((call) => call.includes('event=workflow_dispatch')), 'it lists dispatched runs to find the one titled with its owner and session');
+  });
+
+  it('says which queue a run waits in and for how long, once per change', () => {
+    const lines: string[] = [];
+    const report = waitReporter((line) => lines.push(line.replace(/\d+s/, 'Ns')), '41', { plan: 'paid-small', session: 'paid-mac' });
+    const jobs = (...list: [string, string][]): JobView[] => list.map(([name, status]) => ({ name, status, steps: [] }));
+    const view = { status: 'queued', conclusion: null, url: '' };
+    report(view, []);
+    report(view, jobs(['plan', 'queued']));
+    report(view, jobs(['plan', 'in_progress']));
+    report(view, jobs(['plan', 'completed'], ['session', 'queued']));
+    report(view, jobs(['plan', 'completed'], ['session', 'in_progress']));
+    assert.deepEqual(lines, [
+      'wait    run 41 has waited Ns, now for a paid-small runner to read its request',
+      'wait    run 41 has waited Ns, now for its request to be read on paid-small',
+      'wait    run 41 has waited Ns, now for a paid-mac runner',
+      'wait    run 41 has waited Ns, now for the tunnel on paid-mac',
+    ]);
+  });
+
+  it('hands out a dispatched run only once GitHub can read it, because the first reads are 404', async () => {
+    let reads = 0;
+    const github: GitHub = {
+      repo: 'clerk/clerk-ios',
+      workflow: 'verify-remote.yml',
+      tokenSource: 'none',
+      api: async (_method, path) => (path.endsWith('/dispatches') ? { status: 200, json: { workflow_run_id: 41 }, headers: new Headers() } : { status: (reads += 1) < 3 ? 404 : 200, json: {}, headers: new Headers() }),
+    };
+    assert.equal(await startRun(github, request, { ref: 'b', readableWithinMs: 400 }), '41');
+    assert.equal(reads, 3);
+  });
+
+  it('asks with plain REST and a token from the environment, runs no gh, and hands back a redirect instead of following it to a host a cloud sandbox may not reach', async () => {
+    const server = http.createServer((_req, res) => res.writeHead(302, { location: 'https://elsewhere.invalid/artifact.zip' }).end());
+    await new Promise<void>((done) => server.listen(0, '127.0.0.1', done));
+    try {
+      const hub = await openGitHub({ repo: 'clerk/clerk-ios', workflow: 'verify-remote.yml', env: { GITHUB_TOKEN: 'x', GITHUB_API_URL: `http://127.0.0.1:${(server.address() as AddressInfo).port}` }, runner: async (command) => assert.fail(`ran ${command}`) });
+      assert.equal(hub.tokenSource, 'GITHUB_TOKEN');
+      const answer = await hub.api('GET', '/actions/artifacts/1/zip');
+      assert.equal(answer.status, 302);
+      assert.equal(answer.headers.get('location'), 'https://elsewhere.invalid/artifact.zip');
+    } finally {
+      server.close();
+    }
+  });
+
+  it('retries a read that GitHub answers with a 5xx, and never a write', async () => {
+    const seen: string[] = [];
+    const server = http.createServer((req, res) => {
+      seen.push(`${req.method} ${req.url}`);
+      res.writeHead(req.method === 'GET' && seen.filter((line) => line.startsWith('GET')).length >= 3 ? 200 : 502, { 'content-type': 'application/json' }).end('{}');
+    });
+    await new Promise<void>((done) => server.listen(0, '127.0.0.1', done));
+    try {
+      const hub = await openGitHub({ repo: 'clerk/clerk-ios', workflow: 'verify-remote.yml', env: { GH_TOKEN: 'x', GITHUB_API_URL: `http://127.0.0.1:${(server.address() as AddressInfo).port}` }, runner: async () => ok(), retryDelayMs: 1 });
+      assert.equal((await hub.api('GET', '/actions/runs/1')).status, 200);
+      assert.equal(seen.length, 3);
+      assert.equal((await hub.api('POST', '/actions/runs/1/cancel')).status, 502);
+      assert.equal(seen.length, 4, 'a refused cancel is reported, not sent again');
+    } finally {
+      server.close();
+    }
+  });
+
+  it('takes the run a dispatch started although GitHub answered it with a 5xx', async () => {
+    const { github, calls } = fakeGitHub(502, [{ id: 61, display_title: `verify-remote ${request.owner}/${request.session}` }]);
+    assert.equal(await startRun(github, request, { ref: 'feature/branch' }), '61');
+    assert.ok(calls.some((call) => call.includes('event=workflow_dispatch')));
+  });
+
+  it('says to run again when a dispatch answered with a 5xx starts no run within a minute', async (t) => {
+    t.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
+    const { github } = fakeGitHub(503, []);
+    let settled = false;
+    const outcome = startRun(github, request, { ref: 'feature/branch' })
+      .then(() => assert.fail('it handed out a run'), (error: VerifyFailure) => error)
+      .finally(() => (settled = true));
+    while (!settled) {
+      await new Promise((flushed) => setImmediate(flushed));
+      t.mock.timers.tick(3000);
+    }
+    const failure = await outcome;
+    assert.equal(failure.code, 'NOT_READY');
+    assert.equal(failure.message, `GitHub answered the dispatch of verify-remote.yml with 503 Resource not accessible by integration, and no run for session ${request.session} appeared in a minute`);
+    assert.match(failure.fix, /^run the command again; .*\{cli\} down --stale ends it/);
+  });
+
+  it('names the refusal when GitHub refuses the dispatch', async () => {
+    const { github } = fakeGitHub(403, []);
+    await assert.rejects(startRun(github, request, { ref: 'b' }), (error: VerifyFailure) => error.code === 'NOT_READY' && error.message.includes('403 Resource not accessible by integration') && error.fix.includes('permission to dispatch verify-remote.yml on clerk/clerk-ios'));
+  });
+});
+
+describe('backend selection', () => {
+  const backend = (kind: 'local' | 'remote', usable: boolean, why: string, fix?: string) =>
+    ({ kind, platform: 'ios', requirement: `${kind} needs`, availability: () => ({ usable, why, ...(fix === undefined ? {} : { fix }) }) }) as unknown as DeviceBackend;
+  const host = (backends: DeviceBackend[]) => ({ repo: 'clerk-ios', backends }) as unknown as HostAdapter;
+
+  it('takes local where the machine can run the device and says why', () => {
+    const choice = selectBackend(host([backend('local', true, 'this Mac runs the simulator itself'), backend('remote', true, 'a runner')]), 'ios', undefined, null);
+    assert.equal(choice.backend.kind, 'local');
+    assert.equal(choice.why, 'this Mac runs the simulator itself');
+  });
+
+  it('falls through to remote and names why local is out', () => {
+    const choice = selectBackend(host([backend('local', false, 'the iOS simulator needs macOS and this machine runs linux'), backend('remote', true, 'a runner')]), 'ios', undefined, null);
+    assert.equal(choice.backend.kind, 'remote');
+    assert.equal(choice.why, 'local is out: the iOS simulator needs macOS and this machine runs linux; a runner');
+  });
+
+  it('prints what would make an unusable backend usable, and gives it as the fix when that backend is forced', () => {
+    const noKvm = backend('local', false, 'no kvm', 'add the udev rule');
+    const hosted = host([noKvm, backend('remote', true, 'a runner')]);
+    assert.equal(selectBackend(hosted, 'ios', undefined, null).why, 'local is out: no kvm (to run it here: add the udev rule); a runner');
+    assert.throws(() => selectBackend(hosted, 'ios', 'local', null), (error: VerifyFailure) => error.code === 'UNSUPPORTED' && error.message === '--backend local cannot run here: no kvm' && error.fix === 'add the udev rule');
+    assert.throws(() => selectBackend(host([noKvm]), 'ios', undefined, null), (error: VerifyFailure) => error.message === 'no ios backend runs on this machine (local: no kvm (to run it here: add the udev rule))' && error.fix === 'run on local needs');
+  });
+
+  it('lets --backend force either way, and keeps the backend of a held lease', () => {
+    const both = host([backend('local', true, 'x'), backend('remote', true, 'y')]);
+    assert.equal(selectBackend(both, 'ios', 'remote', null).backend.kind, 'remote');
+    assert.equal(selectBackend(both, 'ios', undefined, { backend: 'remote' } as never).backend.kind, 'remote');
+    const linux = host([backend('local', false, 'the iOS simulator needs macOS and this machine runs linux'), backend('remote', true, 'y')]);
+    assert.throws(() => selectBackend(linux, 'ios', 'local', null), (error: VerifyFailure) => error.code === 'UNSUPPORTED' && error.message.includes('needs macOS'));
+    assert.match(selectBackend(both, 'ios', undefined, { backend: 'remote' } as never).why, /already holds a remote lease/);
+  });
+});
diff --git a/e2e-tests/test/run-groups.test.ts b/e2e-tests/test/run-groups.test.ts
index 2ccb2e180..17eabb24a 100644
--- a/e2e-tests/test/run-groups.test.ts
+++ b/e2e-tests/test/run-groups.test.ts
@@ -9,7 +9,7 @@ import { exitCodeFor } from '../src/core/cli.ts';
 import { assertPublishable, readRecord } from '../src/core/evidence.ts';
 import { createInstances } from '../src/core/instances/instances.ts';
 import { SettingsRefused, settingsFileOf } from '../src/core/instances/settings.ts';
-import { commentBody } from '../src/core/publish.ts';
+import { summarize } from '../src/core/publish.ts';
 import { runVerb, type Deps } from '../src/core/verbs.ts';
 import { openWorkspace } from '../src/core/workspace.ts';
 import { VerifyFailure, type BuildKey, type Command, type DeviceBackend, type HostAdapter, type InstanceSettings, type LocalLease, type ScratchPath } from '../src/core/types.ts';
@@ -253,10 +253,7 @@ describe('a run whose spec files declare different settings', () => {
 
     assert.match(result.next, /^\{cli\} attach /);
     assert.equal(exitCodeFor(result), 0);
-    const comment = commentBody(assertPublishable(record, []));
-    assert.ok(comment.includes(`Instance settings \`${ORG_LABEL}\` (declared by \`${CHOOSE_ORG}\`): 1 of 1 passed.`));
-    assert.ok(comment.includes(`Instance settings \`${MFA_LABEL}\` (declared by \`${COMPLETE_MFA}\`): 2 of 2 passed.`));
-    assert.equal(comment.includes('Instance settings `standard`'), false);
+    assert.deepEqual(summarize(assertPublishable(record, [])), { run: record.run, platform: 'ios', device: record.device, commit: record.gitHead, passed: 5, flaky: 0, total: 5 });
 
     w.lines.length = 0;
     await runVerb(w.deps(), RUN_ALL);
@@ -271,7 +268,6 @@ describe('a run whose spec files declare different settings', () => {
     assert.deepEqual(w.invocations().map((invocation) => invocation.output.split('/').at(-1)), ['e2e']);
     assert.equal(w.lines.some((line) => /groups in this run/.test(line)), false);
     assert.deepEqual(record.settings.map((group) => [group.label, group.changed, group.e2eReport]), [['standard', false, join(dir, 'e2e', 'report.json')]], 'the application was put on the standard file before the run drove, so the group changed nothing');
-    assert.equal(commentBody(assertPublishable(record, [])).includes('Instance settings'), false);
   });
 
   it('opens the Platform credential before it leases a device when the run will change settings', async () => {
diff --git a/e2e-tests/test/session-agent.test.ts b/e2e-tests/test/session-agent.test.ts
new file mode 100644
index 000000000..9c5dec026
--- /dev/null
+++ b/e2e-tests/test/session-agent.test.ts
@@ -0,0 +1,458 @@
+import '../testing/git-env.ts';
+import assert from 'node:assert/strict';
+import { execFileSync, spawn, type ChildProcess } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import http from 'node:http';
+import net from 'node:net';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { after, describe, it } from 'node:test';
+import { coreVersion } from '../src/core/manifest.ts';
+import { HANDOFF_LIMITS, parseHandoffManifest } from '../src/core/remote/handoff.ts';
+import { sendEvidence } from '../src/core/remote/session.ts';
+import { plan } from '../src/core/remote/session-agent.ts';
+import { sha256Hex, type SessionHealth, type SessionRequest } from '../src/core/remote/protocol.ts';
+
+const here = import.meta.dirname;
+const token = 'b'.repeat(64);
+const base: SessionRequest = { v: 1, session: 'ios0000aa', owner: '0123456789ab', platform: 'ios', runner: 'test-runner', device: 'Test Phone', sha: null, idleMinutes: 5, capMinutes: 10, tokenSha256: sha256Hex(token) };
+const children: ChildProcess[] = [];
+after(() => children.forEach((child) => child.kill('SIGKILL')));
+
+const sleep = (ms: number) => new Promise((done) => setTimeout(done, ms));
+async function until<T>(read: () => Promise<T | null> | T | null, what: string, ms = 60_000): Promise<T> {
+  const deadline = Date.now() + ms;
+  for (;;) {
+    const value = await read();
+    if (value !== null) return value;
+    if (Date.now() > deadline) throw new Error(`timed out waiting for ${what}`);
+    await sleep(100);
+  }
+}
+
+let nextPort = 21000 + Math.floor(Math.random() * 4000);
+async function freePort(): Promise<number> {
+  for (let tries = 0; tries < 200; tries += 1) {
+    const candidate = (nextPort += 1);
+    const free = await new Promise<boolean>((done) => {
+      const probe = net.createServer();
+      probe.once('error', () => done(false));
+      probe.listen(candidate, '127.0.0.1', () => probe.close(() => done(true)));
+    });
+    if (free) return candidate;
+  }
+  throw new Error('no free port for a session agent in 200 tries');
+}
+
+function repoWithCommit(): { dir: string; sha: string; commit(text: string): string; git(...args: string[]): string; comesBefore(earlier: string, later: string): boolean; knownOnlyToGitHub(sha: string): string } {
+  const dir = mkdtempSync(join(tmpdir(), 'verify-agent-repo-'));
+  const git = (...args: string[]) => execFileSync('git', ['-c', 'user.name=t', '-c', 'user.email=t@example.com', ...args], { cwd: dir, encoding: 'utf8' }).trim();
+  git('init', '-q');
+  const parents = new Map<string, string | null>();
+  const headOrNone = (): string | null => {
+    try {
+      return git('rev-parse', '-q', '--verify', 'HEAD');
+    } catch {
+      return null;
+    }
+  };
+  const commit = (text: string) => {
+    const parent = headOrNone();
+    writeFileSync(join(dir, 'app.txt'), text);
+    git('add', '-A');
+    git('commit', '-q', '-m', text);
+    const made = git('rev-parse', 'HEAD');
+    parents.set(made, parent);
+    return made;
+  };
+  const sha = commit('one');
+  git('remote', 'add', 'origin', dir);
+  const comesBefore = (earlier: string, later: string): boolean => {
+    for (let at = parents.get(later) ?? null; at !== null; at = parents.get(at) ?? null) if (at === earlier) return true;
+    return false;
+  };
+  const knownOnlyToGitHub = (made: string): string => (parents.set(made, headOrNone()), made);
+  return { dir, sha, commit, git, comesBefore, knownOnlyToGitHub };
+}
+
+const GITHUB_TOKEN = 'ghs_unitTestOnly';
+const servers: http.Server[] = [];
+after(() => servers.forEach((server) => server.close()));
+
+async function gitHubWith(repo: { readonly sha: string; comesBefore(earlier: string, later: string): boolean }) {
+  let branchHead = repo.sha;
+  const { comesBefore } = repo;
+  const authorizations = new Set<string | undefined>();
+  const server = http.createServer((req, res) => {
+    authorizations.add(req.headers.authorization);
+    const path = (req.url ?? '').replace(/^\/repos\/clerk\/sample/, '');
+    const [, base, head] = /^\/compare\/([0-9a-f]{40})\.\.\.([0-9a-f]{40})$/.exec(path) ?? [];
+    const found =
+      path === '/git/ref/heads/feature/change'
+        ? { object: { sha: branchHead } }
+        : base !== undefined && head !== undefined
+          ? { status: base === head ? 'identical' : comesBefore(base, head) ? 'ahead' : comesBefore(head, base) ? 'behind' : 'diverged' }
+          : null;
+    res.writeHead(found === null ? 404 : 200, { 'content-type': 'application/json' }).end(JSON.stringify(found ?? { message: 'Not Found' }));
+  });
+  servers.push(server);
+  await new Promise<void>((listening) => server.listen(0, '127.0.0.1', listening));
+  const { port } = server.address() as { port: number };
+  return {
+    authorizations,
+    push: (sha: string) => (branchHead = sha),
+    stop: () => new Promise((stopped) => server.close(stopped)),
+    env: { GITHUB_API_URL: `http://127.0.0.1:${port}`, GITHUB_REPOSITORY: 'clerk/sample', GITHUB_SHA: repo.sha, GITHUB_REF: 'refs/heads/feature/change', GITHUB_TOKEN },
+  };
+}
+
+async function startAgent(request: SessionRequest, options: { readonly cwd?: string; readonly device?: boolean; readonly deviceModule?: string; readonly minuteMs?: number; readonly agentDevice?: boolean; readonly env?: Readonly<Record<string, string>> } = {}) {
+  const work = mkdtempSync(join(tmpdir(), 'verify-agent-'));
+  const port = await freePort();
+  const agentPort = await freePort();
+  const bin = join(work, 'bin');
+  mkdirSync(bin);
+  const script = (name: string, file: string) => writeFileSync(join(bin, name), `#!/bin/sh\nexec "${process.execPath}" "${join(here, '..', 'testing', file)}" "$@"\n`, { mode: 0o755 });
+  script('cloudflared', 'fake-tunnel.ts');
+  if (options.agentDevice === true) script('agent-device', 'fake-agent-device.ts');
+  const child = spawn(process.execPath, [join(here, '..', 'src', 'core', 'remote', 'session-agent.ts'), 'serve'], {
+    cwd: options.cwd ?? work,
+    env: {
+      PATH: `${bin}:/usr/bin:/bin`,
+      VERIFY_SESSION_REQUEST: JSON.stringify(request),
+      VERIFY_SESSION_WORK: work,
+      VERIFY_SESSION_PORT: String(port),
+      VERIFY_SESSION_AGENT_PORT: String(agentPort),
+      VERIFY_SESSION_CLOUDFLARED: join(bin, 'cloudflared'),
+      VERIFY_SESSION_AGENT_DEVICE: join(bin, 'agent-device'),
+      VERIFY_SESSION_SKIP_DNS: '1',
+      ...(options.minuteMs === undefined ? {} : { VERIFY_SESSION_MINUTE_MS: String(options.minuteMs) }),
+      ...(options.device === false ? {} : { VERIFY_SESSION_DEVICE_ID: 'UDID-1', VERIFY_SESSION_DEVICE_NAME: 'Test Phone', VERIFY_SESSION_DEVICE_MODULE: options.deviceModule ?? join(here, '..', 'testing', 'fake-session-device.ts') }),
+      ...options.env,
+    },
+    stdio: 'ignore',
+  });
+  children.push(child);
+  const exited = new Promise<number>((done) => child.on('close', (code) => done(code ?? 1)));
+  const call = (path: string, init: { method?: string; bearer?: string | null; body?: string } = {}) =>
+    fetch(`http://127.0.0.1:${port}${path}`, { method: init.method ?? 'GET', headers: init.bearer === null ? {} : { Authorization: `Bearer ${init.bearer ?? token}` }, ...(init.body === undefined ? {} : { body: init.body }) });
+  await until(() => (existsSync(join(work, 'tunnel')) ? true : null), 'the tunnel file');
+  await until(() => call('/__sim/health', { bearer: null }).then((r) => r.status).catch(() => null), 'the agent to listen');
+  const health = async () => (await (await call('/__sim/health')).json()) as SessionHealth;
+  return { work, port, call, health, exited };
+}
+
+describe('plan', () => {
+  const outputsOf = (text: string) => Object.fromEntries(text.trim().split('\n').map((line) => line.split(/=(.*)/s, 2) as [string, string]));
+  const noGitHub = async (path: string): Promise<never> => assert.fail(`asked GitHub for ${path}`);
+
+  it('turns a request into job outputs and anything else into mode=none', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'verify-plan-'));
+    const out = join(dir, 'out');
+    writeFileSync(out, '');
+    assert.equal(await plan({ GITHUB_OUTPUT: out, VERIFY_REQUEST: `${JSON.stringify(base)}\n` }, noGitHub), 0);
+    const outputs = outputsOf(readFileSync(out, 'utf8'));
+    assert.equal(outputs.mode, 'session');
+    assert.equal(outputs.runner, 'test-runner');
+    assert.equal(outputs.timeout, '20');
+    assert.deepEqual(JSON.parse(outputs.request!), base);
+    writeFileSync(out, '');
+    assert.equal(await plan({ GITHUB_OUTPUT: out, VERIFY_REQUEST: 'feat: an ordinary commit' }, noGitHub), 0);
+    assert.equal(readFileSync(out, 'utf8'), 'mode=none\n');
+  });
+
+  describe('when the request names a commit to build', () => {
+    const DISPATCHED = 'd'.repeat(40);
+    const LATER = 'e'.repeat(40);
+    const HEAD = 'f'.repeat(40);
+    const ELSEWHERE = 'a'.repeat(40);
+
+    async function planned(sha: string, github: Readonly<Record<string, unknown>> = {}, ref = 'refs/heads/feature/change') {
+      const out = join(mkdtempSync(join(tmpdir(), 'verify-plan-')), 'out');
+      writeFileSync(out, '');
+      const asked: string[] = [];
+      const code = await plan({ GITHUB_OUTPUT: out, GITHUB_SHA: DISPATCHED, GITHUB_REF: ref, VERIFY_REQUEST: JSON.stringify({ ...base, sha }) }, async (path) => (asked.push(path), github[path] ?? null));
+      const written = readFileSync(out, 'utf8');
+      return { code, written, outputs: outputsOf(written), asked };
+    }
+    const branchAt = (head: string) => ({ '/git/ref/heads/feature/change': { object: { sha: head } } });
+
+    it('starts a session at the commit the run was dispatched on, and asks GitHub nothing', async () => {
+      const same = await planned(DISPATCHED);
+      assert.deepEqual([same.code, same.outputs.mode, same.outputs.sha, same.asked], [0, 'session', DISPATCHED, []]);
+    });
+
+    it('starts a session at a later commit of the branch the run was dispatched on', async () => {
+      const atHead = await planned(LATER, { ...branchAt(LATER), [`/compare/${DISPATCHED}...${LATER}`]: { status: 'ahead' } });
+      assert.deepEqual([atHead.code, atHead.outputs.sha], [0, LATER]);
+      const beforeHead = await planned(LATER, { ...branchAt(HEAD), [`/compare/${DISPATCHED}...${LATER}`]: { status: 'ahead' }, [`/compare/${LATER}...${HEAD}`]: { status: 'ahead' } });
+      assert.deepEqual([beforeHead.code, beforeHead.outputs.sha], [0, LATER]);
+    });
+
+    it('starts no session, and fails the step, for a commit that is not on the branch the run was dispatched on', async () => {
+      const refused = [
+        ['a commit of another branch that was cut from this one', { ...branchAt(HEAD), [`/compare/${DISPATCHED}...${ELSEWHERE}`]: { status: 'ahead' }, [`/compare/${ELSEWHERE}...${HEAD}`]: { status: 'diverged' } }],
+        ['a commit that shares no later history with the dispatch commit', { ...branchAt(HEAD), [`/compare/${DISPATCHED}...${ELSEWHERE}`]: { status: 'diverged' }, [`/compare/${ELSEWHERE}...${HEAD}`]: { status: 'ahead' } }],
+        ['an earlier commit of the branch', { ...branchAt(HEAD), [`/compare/${DISPATCHED}...${ELSEWHERE}`]: { status: 'behind' }, [`/compare/${ELSEWHERE}...${HEAD}`]: { status: 'ahead' } }],
+        ['any commit when GitHub does not answer', {}],
+      ] as const;
+      for (const [what, github] of refused) {
+        const { code, written } = await planned(ELSEWHERE, github);
+        assert.deepEqual([code, written], [1, ''], what);
+      }
+      const onATag = await planned(LATER, { '/git/ref/heads/v1': { object: { sha: LATER } }, [`/compare/${DISPATCHED}...${LATER}`]: { status: 'ahead' } }, 'refs/tags/v1');
+      assert.deepEqual([onATag.code, onATag.written, onATag.asked], [1, '', []], 'a tag has no later commits');
+    });
+  });
+});
+
+describe('session agent', () => {
+  it('publishes the tunnel host, refuses every route without the bearer, and stops on request', async () => {
+    const agent = await startAgent(base);
+    assert.equal(readFileSync(join(agent.work, 'tunnel'), 'utf8'), 'fake-session-host.trycloudflare.com');
+    for (const path of ['/__sim/health', '/agent-device/health', '/health', '/rpc', '/anything']) {
+      const refused = await agent.call(path, { bearer: null });
+      assert.equal(refused.status, 403, path);
+      assert.deepEqual(await refused.json(), { error: 'session token required' });
+    }
+    assert.equal((await agent.call('/__sim/health', { bearer: 'c'.repeat(64) })).status, 403);
+    const health = await agent.health();
+    assert.deepEqual(health.device, { id: 'UDID-1', name: 'Test Phone', ready: false });
+    assert.equal(health.core, coreVersion(), 'a driver compares this with its own core before it drives the session');
+    writeFileSync(join(agent.work, 'device-ready'), '');
+    assert.equal((await agent.health()).device?.ready, true);
+    const stopped = await agent.call('/__sim/stop', { method: 'POST' });
+    assert.equal(stopped.status, 200);
+    assert.deepEqual(await stopped.json(), { ok: true, evidence: null });
+    assert.equal(await agent.exited, 0);
+    assert.equal((JSON.parse(readFileSync(join(agent.work, 'ended'), 'utf8')) as { reason: string }).reason, 'stop');
+  });
+
+  it('ends itself when the driver goes silent', async () => {
+    const agent = await startAgent({ ...base, idleMinutes: 1, capMinutes: 100 }, { minuteMs: 1500 });
+    assert.equal(await agent.exited, 0);
+    assert.equal((JSON.parse(readFileSync(join(agent.work, 'ended'), 'utf8')) as { reason: string }).reason, 'idle');
+  });
+
+  it('does not let a caller without the bearer keep it alive', async () => {
+    const agent = await startAgent({ ...base, idleMinutes: 1, capMinutes: 100 }, { minuteMs: 1500 });
+    const stranger = setInterval(() => void agent.call('/__sim/health', { bearer: null }).catch(() => undefined), 100);
+    try {
+      assert.equal(await agent.exited, 0);
+    } finally {
+      clearInterval(stranger);
+    }
+    assert.equal((JSON.parse(readFileSync(join(agent.work, 'ended'), 'utf8')) as { reason: string }).reason, 'idle');
+  });
+
+  it('starts agent-device only once it knows the bearer, forwards to it, and keeps the bearer out of its log', async () => {
+    const agent = await startAgent(base, { agentDevice: true, minuteMs: 600 });
+    assert.equal((await agent.call('/agent-device/health')).status, 503, 'the first authorized call is what teaches the agent the bearer');
+    const forwarded = await until(async () => { const r = await agent.call('/agent-device/health'); return r.status === 200 ? ((await r.json()) as { path: string; authorized: boolean }) : null; }, 'agent-device to come up');
+    assert.deepEqual(forwarded, { ok: true, path: '/agent-device/health', authorized: true });
+    assert.equal((await agent.call('/agent-device/health', { bearer: null })).status, 403);
+    assert.equal((await until(async () => { const h = await agent.health(); return h.daemon ? h : null; }, 'the daemon to report healthy')).daemon, true);
+    const log = readFileSync(join(agent.work, 'agent-device-proxy.log'), 'utf8');
+    assert.match(log, /Daemon auth token: <token>/);
+    assert.equal(log.includes(token), false);
+    await agent.call('/__sim/stop', { method: 'POST' });
+    await agent.exited;
+  });
+
+  it('ends itself at the cap even while the driver keeps calling', async () => {
+    const agent = await startAgent({ ...base, idleMinutes: 2, capMinutes: 2 }, { minuteMs: 1500 });
+    const poll = setInterval(() => void agent.call('/__sim/health').catch(() => undefined), 200);
+    try {
+      assert.equal(await agent.exited, 0);
+    } finally {
+      clearInterval(poll);
+    }
+    assert.equal((JSON.parse(readFileSync(join(agent.work, 'ended'), 'utf8')) as { reason: string }).reason, 'cap');
+  });
+
+  it('builds the commit it is asked for, rebuilds a newer one, and reports a failed build', async () => {
+    const repo = repoWithCommit();
+    const github = await gitHubWith(repo);
+    const agent = await startAgent({ ...base, sha: repo.sha }, { cwd: repo.dir, env: github.env });
+    const built = (sha: string) => until(async () => { const b = (await agent.health()).build; return b.state !== 'building' && b.state !== 'none' && b.sha === sha ? b : null; }, `build of ${sha}`);
+    const first = await built(repo.sha);
+    assert.equal(first.state, 'built');
+    assert.equal(first.state === 'built' && first.incremental, false);
+    assert.equal(readFileSync(join(agent.work, 'built'), 'utf8'), 'one');
+
+    const second = github.push(repo.commit('two'));
+    assert.equal((await agent.call(`/__sim/build?sha=${second}`, { method: 'POST' })).status, 202);
+    const rebuilt = await built(second);
+    assert.equal(rebuilt.state === 'built' && rebuilt.incremental, true);
+    assert.equal(readFileSync(join(agent.work, 'built'), 'utf8'), 'two');
+
+    assert.equal((await agent.call('/__sim/build?sha=main', { method: 'POST' })).status, 400);
+    const missing = github.push(repo.knownOnlyToGitHub('0'.repeat(40)));
+    await agent.call(`/__sim/build?sha=${missing}`, { method: 'POST' });
+    const failed = await built(missing);
+    assert.equal(failed.state, 'failed');
+    assert.doesNotMatch(failed.state === 'failed' ? failed.tail : '', /GitHub does not show/, 'the fetch failed, not the question to GitHub');
+    await agent.call('/__sim/stop', { method: 'POST' });
+    await agent.exited;
+  });
+
+  it('builds only the commit it was started on and later commits of that branch, whoever asks with the session token', async () => {
+    const repo = repoWithCommit();
+    const earlier = repo.sha;
+    const started = repo.commit('two');
+    const github = await gitHubWith({ ...repo, sha: started });
+    const agent = await startAgent({ ...base, sha: started }, { cwd: repo.dir, env: github.env });
+    const built = (sha: string) => until(async () => { const b = (await agent.health()).build; return b.state !== 'building' && b.state !== 'none' && b.sha === sha ? b : null; }, `build of ${sha}`);
+    assert.equal((await built(started)).state, 'built');
+    assert.deepEqual([...github.authorizations], [], 'the commit it was started on needs no question');
+
+    repo.git('checkout', '-q', '-b', 'another-branch');
+    const elsewhere = repo.commit('code of another branch');
+    repo.git('checkout', '-q', '-');
+    for (const [what, sha] of [['a commit of another branch that was cut from this one', elsewhere], ['an earlier commit of the branch', earlier]] as const) {
+      assert.equal((await agent.call(`/__sim/build?sha=${sha}`, { method: 'POST' })).status, 202, what);
+      const refused = await built(sha);
+      assert.equal(refused.state, 'failed', what);
+      assert.match(refused.state === 'failed' ? refused.tail : '', new RegExp(`^this session builds ${started}, the commit it was started on, and later commits of refs/heads/feature/change\\. GitHub does not show ${sha} as one\\.`), what);
+      assert.equal(readFileSync(join(agent.work, 'built'), 'utf8'), 'two', `${what} was not built`);
+      assert.equal(repo.git('rev-parse', 'HEAD'), started, `${what} was not checked out`);
+    }
+    assert.deepEqual([...github.authorizations], [`Bearer ${GITHUB_TOKEN}`], 'it asks GitHub with the token of the run');
+
+    const later = repo.commit('three');
+    const latest = github.push(repo.commit('four'));
+    for (const sha of [later, latest]) {
+      await agent.call(`/__sim/build?sha=${sha}`, { method: 'POST' });
+      assert.equal((await built(sha)).state, 'built');
+    }
+
+    await github.stop();
+    const unanswered = repo.commit('five');
+    await agent.call(`/__sim/build?sha=${unanswered}`, { method: 'POST' });
+    assert.equal((await built(unanswered)).state, 'failed', 'a commit GitHub does not vouch for is not built');
+    assert.equal(readFileSync(join(agent.work, 'built'), 'utf8'), 'four');
+    await agent.call('/__sim/stop', { method: 'POST' });
+    await agent.exited;
+  });
+
+  it('gives the commands that build a commit an environment without the token it asks GitHub with', async () => {
+    const repo = repoWithCommit();
+    writeFileSync(join(repo.dir, 'device.ts'), `export default () => ({ build: (work) => [{ command: process.execPath, args: ['-e', "require('fs').writeFileSync(require('path').join(process.argv[1], 'built'), 'token ' + process.env.GITHUB_TOKEN)", work] }] });\n`);
+    const started = repo.commit('one');
+    const agent = await startAgent({ ...base, sha: started }, { cwd: repo.dir, deviceModule: 'device.ts', env: (await gitHubWith({ ...repo, sha: started })).env });
+    await until(async () => ((await agent.health()).build.state === 'built' ? true : null), 'the build');
+    assert.equal(readFileSync(join(agent.work, 'built'), 'utf8'), 'token undefined');
+    await agent.call('/__sim/stop', { method: 'POST' });
+    await agent.exited;
+  });
+
+  it('builds each commit with the recipe that commit holds, not the one the session started on', async () => {
+    const repo = repoWithCommit();
+    const recipeOf = (label: string) =>
+      `export default () => ({ build: (work) => [{ command: process.execPath, args: ['-e', "require('fs').writeFileSync(require('path').join(process.argv[1], 'built'), '${label} recipe built ' + require('fs').readFileSync('app.txt', 'utf8'))", work] }] });\n`;
+    writeFileSync(join(repo.dir, 'device.ts'), recipeOf('first'));
+    const first = repo.commit('one');
+    const github = await gitHubWith({ ...repo, sha: first });
+    const agent = await startAgent({ ...base, sha: first }, { cwd: repo.dir, deviceModule: 'device.ts', env: github.env });
+    const built = (sha: string) => until(async () => { const b = (await agent.health()).build; return b.state !== 'building' && b.state !== 'none' && b.sha === sha ? b : null; }, `build of ${sha}`);
+    assert.equal((await built(first)).state, 'built');
+    assert.equal(readFileSync(join(agent.work, 'built'), 'utf8'), 'first recipe built one');
+
+    writeFileSync(join(repo.dir, 'device.ts'), recipeOf('second'));
+    const second = github.push(repo.commit('two'));
+    await agent.call(`/__sim/build?sha=${second}`, { method: 'POST' });
+    assert.equal((await built(second)).state, 'built');
+    assert.equal(readFileSync(join(agent.work, 'built'), 'utf8'), 'second recipe built two');
+
+    writeFileSync(join(repo.dir, 'device.ts'), 'export default () => { throw new Error("this module is broken"); };\n');
+    const third = github.push(repo.commit('three'));
+    await agent.call(`/__sim/build?sha=${third}`, { method: 'POST' });
+    const failed = await built(third);
+    assert.equal(failed.state, 'failed');
+    assert.match(failed.state === 'failed' ? failed.tail : '', /could not answer build: .*this module is broken/);
+    await agent.call('/__sim/stop', { method: 'POST' });
+    await agent.exited;
+  });
+
+  it('stops and collects a recording with the commands its own start named', async () => {
+    const agent = await startAgent({ ...base, platform: 'android' }, { env: { FAKE_DEVICE_RECORDER: 'on-device' } });
+    assert.equal((await agent.call('/__sim/record/start', { method: 'POST' })).status, 200);
+    await sleep(300);
+    const stopped = (await (await agent.call('/__sim/record/stop', { method: 'POST' })).json()) as { bytes: number };
+    assert.ok(stopped.bytes > 0);
+    assert.equal(await (await agent.call('/__sim/record/file')).text(), 'pulled from android UDID-1');
+    await agent.call('/__sim/stop', { method: 'POST' });
+    await agent.exited;
+  });
+
+  it('records, serves the file, and reads device logs', async () => {
+    const agent = await startAgent(base);
+    assert.equal((await agent.call('/__sim/record/start', { method: 'POST' })).status, 200);
+    await sleep(500);
+    assert.equal((await agent.call('/__sim/record/start', { method: 'POST' })).status, 200, 'a recorder left by a run that died is replaced, not an error');
+    await sleep(500);
+    const stopped = (await (await agent.call('/__sim/record/stop', { method: 'POST' })).json()) as { bytes: number };
+    assert.ok(stopped.bytes > 0);
+    assert.equal(await (await agent.call('/__sim/record/file')).text(), 'video of UDID-1');
+    assert.match(await (await agent.call('/__sim/logs?predicate=extra')).text(), /log line for UDID-1 extra/);
+    await agent.call('/__sim/stop', { method: 'POST' });
+    await agent.exited;
+  });
+
+  it('takes evidence from the CLI over the tunnel routes, keeps it in one directory, and says so when it stops', async () => {
+    const agent = await startAgent(base);
+    const dir = mkdtempSync(join(tmpdir(), 'verify-agent-run-'));
+    const video = Buffer.alloc(HANDOFF_LIMITS.chunkBytes + 4096, 'v');
+    const shot = Buffer.from('png bytes');
+    writeFileSync(join(dir, 'video.mp4'), video);
+    writeFileSync(join(dir, 'profile.png'), shot);
+    writeFileSync(join(dir, 'token'), token);
+    const sha256 = (data: Buffer) => createHash('sha256').update(data).digest('hex');
+    const manifest = parseHandoffManifest(
+      JSON.stringify({ v: 1, pr: 669, run: 'r20261008-052713-253e', platform: 'ios', device: 'Test Phone on test-runner', commit: 'a'.repeat(40), passed: 1, flaky: 0, total: 1, files: [{ name: 'video.mp4', bytes: video.length, sha256: sha256(video) }, { name: 'profile.png', bytes: shot.length, sha256: sha256(shot) }] }),
+    );
+    for (const step of ['begin', 'chunk', 'commit']) assert.equal((await agent.call(`/__sim/evidence/${step}`, { method: 'POST', bearer: null, body: '{}' })).status, 403, step);
+    assert.equal((await agent.call('/__sim/evidence/begin', { method: 'POST', body: JSON.stringify({ ...manifest, run: 'nope' }) })).status, 400);
+    assert.equal((await agent.call('/__sim/evidence/begin', { method: 'POST', body: JSON.stringify(manifest).padEnd(HANDOFF_LIMITS.manifestBytes + 1, ' ') })).status, 413);
+
+    const realFetch = globalThis.fetch;
+    const lines: string[] = [];
+    let lostOneAnswer = false;
+    globalThis.fetch = async (input, init) => {
+      const url = new URL(String(input));
+      assert.equal(url.host, 'fake-session-host.trycloudflare.com');
+      const response = await realFetch(`http://127.0.0.1:${agent.port}${url.pathname}${url.search}`, init);
+      if (url.pathname === '/__sim/evidence/chunk' && !lostOneAnswer && (JSON.parse(String(init?.body)) as { offset: number }).offset > 0) {
+        lostOneAnswer = true;
+        throw new TypeError('fetch failed');
+      }
+      return response;
+    };
+    try {
+      await sendEvidence({ baseUrl: 'https://fake-session-host.trycloudflare.com', tokenFile: join(dir, 'token') }, manifest, new Map([['video.mp4', join(dir, 'video.mp4')], ['profile.png', join(dir, 'profile.png')]]), (line) => void lines.push(line), 10);
+    } finally {
+      globalThis.fetch = realFetch;
+    }
+    assert.equal(lostOneAnswer, true, 'the sender went on after an answer it never got, because the agent said it had the bytes');
+    assert.deepEqual(lines, [`handoff video.mp4  ${video.length} bytes`, `handoff profile.png  ${shot.length} bytes`]);
+    assert.deepEqual(readdirSync(join(agent.work, 'evidence')).sort(), ['manifest.json', 'profile.png', 'video.mp4']);
+    assert.deepEqual(readFileSync(join(agent.work, 'evidence', 'video.mp4')), video);
+    assert.deepEqual(JSON.parse(readFileSync(join(agent.work, 'evidence', 'manifest.json'), 'utf8')), manifest);
+    assert.equal(existsSync(join(agent.work, 'evidence.partial')), false);
+
+    assert.equal((await agent.call('/__sim/evidence/chunk', { method: 'POST', body: 'x'.repeat(HANDOFF_LIMITS.chunkBodyBytes + 1) })).status, 409, 'nothing is being received after a commit');
+    assert.deepEqual(await (await agent.call('/__sim/stop', { method: 'POST' })).json(), { ok: true, evidence: 'r20261008-052713-253e' });
+    await agent.exited;
+    assert.deepEqual(readdirSync(join(agent.work, 'evidence')).sort(), ['manifest.json', 'profile.png', 'video.mp4'], 'the evidence outlives the agent, for the step that uploads it');
+  });
+
+  it('has no device routes when the session was started without a device', async () => {
+    const agent = await startAgent({ ...base, device: null }, { device: false });
+    assert.equal((await agent.health()).device, null);
+    assert.equal((await agent.call('/__sim/record/start', { method: 'POST' })).status, 409);
+    assert.equal((await agent.call(`/__sim/build?sha=${'a'.repeat(40)}`, { method: 'POST' })).status, 409);
+    await agent.call('/__sim/stop', { method: 'POST' });
+    await agent.exited;
+  });
+});
diff --git a/e2e-tests/test/session-build-limit.test.ts b/e2e-tests/test/session-build-limit.test.ts
new file mode 100644
index 000000000..19b1ee721
--- /dev/null
+++ b/e2e-tests/test/session-build-limit.test.ts
@@ -0,0 +1,132 @@
+import '../testing/git-env.ts';
+import assert from 'node:assert/strict';
+import { execFileSync, spawn, type ChildProcess } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import net from 'node:net';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { after, describe, it } from 'node:test';
+import { sha256Hex, type SessionHealth, type SessionRequest } from '../src/core/remote/protocol.ts';
+
+const here = import.meta.dirname;
+const token = 'c'.repeat(64);
+const children: ChildProcess[] = [];
+after(() => children.forEach((child) => child.kill('SIGKILL')));
+
+const sleep = (ms: number) => new Promise((done) => setTimeout(done, ms));
+
+let nextPort = 26000 + Math.floor(Math.random() * 4000);
+async function freePort(): Promise<number> {
+  for (let tries = 0; tries < 200; tries += 1) {
+    const candidate = (nextPort += 1);
+    const free = await new Promise<boolean>((done) => {
+      const probe = net.createServer();
+      probe.once('error', () => done(false));
+      probe.listen(candidate, '127.0.0.1', () => probe.close(() => done(true)));
+    });
+    if (free) return candidate;
+  }
+  throw new Error('no free port for a session agent in 200 tries');
+}
+
+const SLOW_UNTIL_STARTED_ONCE = `const fs = require('fs'); const mark = require('path').join(process.argv[1], 'started'); if (fs.existsSync(mark)) { console.log('finished what the stopped build left'); } else { fs.writeFileSync(mark, ''); console.log('build   xcodebuild Release'); setInterval(() => {}, 1000); }`;
+const NEVER_ENDS_THE_FIRST_TIME = `export default () => ({ build: (work) => [{ command: process.execPath, args: ['-e', ${JSON.stringify(SLOW_UNTIL_STARTED_ONCE)}, work] }] });\n`;
+
+const LEAVE_A_FILE = `require('fs').writeFileSync(require('path').join(process.argv[1], 'ran-after-the-limit'), '');`;
+const ANSWERS_AFTER_THE_LIMIT = `await new Promise((done) => setTimeout(done, 6000));\nexport default () => ({ build: (work) => [{ command: process.execPath, args: ['-e', ${JSON.stringify(LEAVE_A_FILE)}, work] }] });\n`;
+
+const EXIT_ZERO_WHEN_STOPPED = `process.on('SIGTERM', () => process.exit(0)); console.log('build   gradle assembleDebug'); setInterval(() => {}, 1000);`;
+const EXITS_ZERO_WHEN_STOPPED = `export default () => ({ build: () => [{ command: process.execPath, args: ['-e', ${JSON.stringify(EXIT_ZERO_WHEN_STOPPED)}] }] });\n`;
+
+function repoWithDevice(deviceModule: string): { dir: string; sha: string } {
+  const dir = mkdtempSync(join(tmpdir(), 'verify-build-limit-'));
+  const git = (...args: string[]) => execFileSync('git', ['-c', 'user.name=t', '-c', 'user.email=t@example.com', ...args], { cwd: dir, encoding: 'utf8' }).trim();
+  git('init', '-q');
+  writeFileSync(join(dir, 'device.ts'), deviceModule);
+  git('add', '-A');
+  git('commit', '-q', '-m', 'one');
+  git('remote', 'add', 'origin', dir);
+  return { dir, sha: git('rev-parse', 'HEAD') };
+}
+
+async function startAgent(repo: { readonly dir: string; readonly sha: string }, minuteMs: number) {
+  const work = mkdtempSync(join(tmpdir(), 'verify-build-limit-work-'));
+  const port = await freePort();
+  const bin = join(work, 'bin');
+  mkdirSync(bin);
+  writeFileSync(join(bin, 'cloudflared'), `#!/bin/sh\nexec "${process.execPath}" "${join(here, '..', 'testing', 'fake-tunnel.ts')}" "$@"\n`, { mode: 0o755 });
+  const request: SessionRequest = { v: 1, session: 'ios0000bb', owner: '0123456789ab', platform: 'ios', runner: 'test-runner', device: 'Test Phone', sha: repo.sha, idleMinutes: 120, capMinutes: 360, tokenSha256: sha256Hex(token) };
+  const child = spawn(process.execPath, [join(here, '..', 'src', 'core', 'remote', 'session-agent.ts'), 'serve'], {
+    cwd: repo.dir,
+    env: {
+      PATH: `${bin}:/usr/bin:/bin`,
+      VERIFY_SESSION_REQUEST: JSON.stringify(request),
+      VERIFY_SESSION_WORK: work,
+      VERIFY_SESSION_PORT: String(port),
+      VERIFY_SESSION_AGENT_PORT: String(await freePort()),
+      VERIFY_SESSION_CLOUDFLARED: join(bin, 'cloudflared'),
+      VERIFY_SESSION_AGENT_DEVICE: join(bin, 'agent-device'),
+      VERIFY_SESSION_SKIP_DNS: '1',
+      VERIFY_SESSION_MINUTE_MS: String(minuteMs),
+      VERIFY_SESSION_DEVICE_ID: 'UDID-1',
+      VERIFY_SESSION_DEVICE_NAME: 'Test Phone',
+      VERIFY_SESSION_DEVICE_MODULE: 'device.ts',
+      GITHUB_SHA: repo.sha,
+      GITHUB_REF: 'refs/heads/feature/change',
+    },
+    stdio: 'ignore',
+  });
+  children.push(child);
+  const exited = new Promise<number>((done) => child.on('close', (code) => done(code ?? 1)));
+  const call = (path: string, method: 'GET' | 'POST' = 'GET') => fetch(`http://127.0.0.1:${port}${path}`, { method, headers: { Authorization: `Bearer ${token}` } });
+  const settledBuild = async (): Promise<SessionHealth['build']> => {
+    for (const deadline = Date.now() + 60_000; Date.now() < deadline; await sleep(100)) {
+      if (!existsSync(join(work, 'tunnel'))) continue;
+      const { build } = (await (await call('/__sim/health')).json()) as SessionHealth;
+      if (build.state !== 'building' && build.state !== 'none') return build;
+    }
+    throw new Error('the build did not settle in 60 seconds');
+  };
+  return { call, settledBuild, exited, work };
+}
+
+describe('the longest a session lets one build run', () => {
+  it('stops a build at the limit, reports that as its own state with the last lines, and builds again when asked', async () => {
+    const repo = repoWithDevice(NEVER_ENDS_THE_FIRST_TIME);
+    const agent = await startAgent(repo, 100);
+
+    const stopped = await agent.settledBuild();
+    assert.equal(stopped.state, 'timed-out');
+    assert.equal(stopped.state === 'timed-out' && stopped.sha, repo.sha);
+    assert.equal(stopped.state === 'timed-out' && stopped.tail.split('\n').at(-1), 'build   xcodebuild Release');
+
+    assert.equal((await agent.call(`/__sim/build?sha=${repo.sha}`, 'POST')).status, 202);
+    const again = await agent.settledBuild();
+    assert.deepEqual([again.state, again.state === 'built' && again.sha], ['built', repo.sha]);
+
+    await agent.call('/__sim/stop', 'POST');
+    assert.equal(await agent.exited, 0);
+  });
+
+  it('starts no further command once the limit has passed while none was running', async () => {
+    const agent = await startAgent(repoWithDevice(ANSWERS_AFTER_THE_LIMIT), 100);
+
+    const stopped = await agent.settledBuild();
+    assert.equal(stopped.state, 'timed-out');
+    assert.equal(existsSync(join(agent.work, 'ran-after-the-limit')), false);
+
+    await agent.call('/__sim/stop', 'POST');
+    assert.equal(await agent.exited, 0);
+  });
+
+  it('reports the limit, not a finished build, when the stopped command exits 0', async () => {
+    const agent = await startAgent(repoWithDevice(EXITS_ZERO_WHEN_STOPPED), 100);
+
+    const stopped = await agent.settledBuild();
+    assert.equal(stopped.state, 'timed-out');
+    assert.equal(stopped.state === 'timed-out' && stopped.tail.split('\n').at(-1), 'build   gradle assembleDebug');
+
+    await agent.call('/__sim/stop', 'POST');
+    assert.equal(await agent.exited, 0);
+  });
+});
diff --git a/e2e-tests/test/settings.test.ts b/e2e-tests/test/settings.test.ts
index cd2740df8..a91ddbab3 100644
--- a/e2e-tests/test/settings.test.ts
+++ b/e2e-tests/test/settings.test.ts
@@ -32,7 +32,7 @@ describe('the standard file', () => {
     const pinned = configLeaves(standardFile().config);
     assert.equal(pinned['auth_multi_factor.required_for_sign_up'], false);
     assert.equal(pinned['organization_settings.force_organization_selection'], false);
-    assert.deepEqual(pinned['auth_email.sign_in_strategies'], ['email_code', 'email_link'], 'a list is one leaf');
+    assert.deepEqual(pinned['auth_email.sign_in_strategies'], ['email_code'], 'a list is one leaf');
   });
 });
 
diff --git a/e2e-tests/test/tunnel-wait.test.ts b/e2e-tests/test/tunnel-wait.test.ts
new file mode 100644
index 000000000..a9cccfc71
--- /dev/null
+++ b/e2e-tests/test/tunnel-wait.test.ts
@@ -0,0 +1,42 @@
+import '../testing/git-env.ts';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, it } from 'node:test';
+
+const workflow = readFileSync(join(import.meta.dirname, '..', '..', '.github', 'workflows', 'verify-remote.yml'), 'utf8');
+
+describe('the workflow step that waits for the tunnel', () => {
+  const lines = workflow.split('\n').map((line) => line.trim());
+  const step = lines.indexOf('- name: Start the session agent and tunnel');
+  const first = lines.findIndex((line, at) => at > step && /^for _ in \$\(seq 1 \d+\); do$/.test(line));
+  const last = lines.findIndex((line, at) => at > first && line.startsWith('[ -s "$WORK/tunnel" ] ||'));
+  const wait = lines.slice(first, last + 1).join('\n');
+
+  function waited(agent: 'running' | 'gone', tunnel: 'published' | 'none'): { status: number | null; stdout: string } {
+    const work = mkdtempSync(join(tmpdir(), 'verify-tunnel-wait-'));
+    mkdirSync(join(work, 'bin'));
+    writeFileSync(join(work, 'bin', 'pgrep'), `#!/bin/sh\nexit ${agent === 'running' ? 0 : 1}\n`, { mode: 0o755 });
+    if (tunnel === 'published') writeFileSync(join(work, 'tunnel'), 'quick-fox.trycloudflare.com');
+    writeFileSync(join(work, 'agent.log'), 'verify-remote session ios0000aa on :3199\n');
+    writeFileSync(join(work, 'tunnel.log'), 'failed to request quick Tunnel\n');
+    const ran = spawnSync('bash', ['-c', wait], { env: { PATH: `${join(work, 'bin')}:${process.env.PATH}`, WORK: work }, encoding: 'utf8', timeout: 20_000 });
+    rmSync(work, { recursive: true, force: true });
+    return { status: ran.status, stdout: ran.stdout };
+  }
+
+  it('fails within seconds, with both logs, when the agent has ended and no tunnel came up', () => {
+    assert.ok(step > 0 && first > step && last > first, 'the wait loop is in the workflow');
+    const { status, stdout } = waited('gone', 'none');
+    assert.equal(status, 1);
+    assert.ok(stdout.startsWith('::error::the session agent ended before a tunnel came up\n::error::no tunnel came up\n'), stdout);
+    assert.ok(stdout.includes('verify-remote session ios0000aa on :3199'), stdout);
+    assert.ok(stdout.includes('failed to request quick Tunnel'), stdout);
+  });
+
+  it('goes on as soon as the tunnel is published', () => {
+    assert.deepEqual(waited('running', 'published'), { status: 0, stdout: '' });
+  });
+});
diff --git a/e2e-tests/testing/fake-agent-device.ts b/e2e-tests/testing/fake-agent-device.ts
new file mode 100644
index 000000000..508f77a28
--- /dev/null
+++ b/e2e-tests/testing/fake-agent-device.ts
@@ -0,0 +1,11 @@
+import http from 'node:http';
+
+const port = Number(process.argv[process.argv.indexOf('--port') + 1]);
+const token = process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN ?? '';
+console.log(`Daemon auth token: ${token}`);
+http
+  .createServer((req, res) => {
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ ok: true, path: req.url, authorized: req.headers.authorization === `Bearer ${token}` }));
+  })
+  .listen(port, '127.0.0.1');
diff --git a/e2e-tests/testing/fake-session-device.ts b/e2e-tests/testing/fake-session-device.ts
new file mode 100644
index 000000000..eedb0df7e
--- /dev/null
+++ b/e2e-tests/testing/fake-session-device.ts
@@ -0,0 +1,19 @@
+import { join } from 'node:path';
+import type { SessionDeviceFactory } from '../src/core/remote/protocol.ts';
+
+const node = process.execPath;
+const write = (file: string, text: string) => ({ command: node, args: ['-e', `require('fs').writeFileSync(${JSON.stringify(file)}, ${JSON.stringify(text)})`] });
+
+const fake: SessionDeviceFactory = ({ id: deviceId, platform }) => ({
+  build: (work) => [{ command: node, args: ['-e', `require('fs').writeFileSync(${JSON.stringify(join(work, 'built'))}, require('fs').readFileSync('app.txt', 'utf8'))`] }],
+  record:
+    process.env.FAKE_DEVICE_RECORDER === 'on-device'
+      ? {
+          start: (file) => ({ command: node, args: ['-e', `const fs = require('fs'); setInterval(() => fs.existsSync(${JSON.stringify(`${file}.stop`)}) && process.exit(0), 50)`] }),
+          stop: (file) => [write(`${file}.stop`, '')],
+          collect: (file) => [write(file, `pulled from ${platform} ${deviceId}`)],
+        }
+      : { start: (file) => ({ command: node, args: ['-e', `process.on('SIGINT', () => { require('fs').writeFileSync(${JSON.stringify(file)}, 'video of ${deviceId}'); process.exit(0); }); setInterval(() => {}, 1000)`] }) },
+  logs: (_since, predicate) => ({ command: node, args: ['-e', `console.log('log line for ${deviceId} ${predicate ?? ''}')`] }),
+});
+export default fake;
diff --git a/e2e-tests/testing/fake-tunnel.ts b/e2e-tests/testing/fake-tunnel.ts
new file mode 100644
index 000000000..22de0da16
--- /dev/null
+++ b/e2e-tests/testing/fake-tunnel.ts
@@ -0,0 +1,2 @@
+console.error('INF |  https://fake-session-host.trycloudflare.com  |');
+setInterval(() => undefined, 1000);