Run the review server headless and route remote reviews through a gateway

[thesiti92]

Stacked PR 2 of 9 for remote reviews (base: main; #934, the rename, is merged). Review in order; each PR builds and passes its suites on its own.

Manual test plan

Purpose. The CLI can run the review server in the background on any machine (server start --detach, server stop, server reset-id, remote attach), and Desktop's local server gains a gateway that merges, routes and streams other machines' reviews. There is no SSH yet: the dev-only DEV_FAST_REVIEW_REMOTE_HOSTS_FILE hands the gateway its hosts.

Setup. Worktree at origin/remote/2-headless-server-gateway. R up a && R install a. Create the remote review (ID=...).

Steps.

1. R ssh a -- whiteboard server status --json → ready: true with serverId: the fixture's whiteboard api started a headless server, since no Desktop is on the host.
2. R ssh a -- whiteboard server stop → Stopped the Whiteboard server (process N).; server status now fails as not ready.
3. R ssh a -- whiteboard remote attach --json → one JSON line between WHITEBOARD-REMOTE-BEGIN and WHITEBOARD-REMOTE-END: event: "remote.attach", url: http://127.0.0.1:<port>, token, startedServer: true, diffr. Again → startedServer: false, same url.
4. P=$(R forward a <port>) → prints a free local port.
5. printf '[{"alias":"devbox","endpoint":{"url":"http://127.0.0.1:%s","token":"%s"}}]' $P <token> > $H/hosts.json.
6. Launch with DEV_REVIEW_HOME=$H DEV_FAST_REVIEW_REMOTE_HOSTS_FILE=$H/hosts.json pnpm dev; set the Desktop API helpers.
7. api /remote-hosts → [{"alias":"devbox","serverId":"…","state":"online"}].
8. api /reviews-api → the array holds Remote-order with "host":"devbox", "hostState":"online".
9. api /reviews-api/$ID → the remote review, answered through the forward.
10. Open Remote-order in Desktop, then edit wb-test-a $ID "Edited on the remote." → the text appears in the open tab without a reload.
11. S wb-test-a 'bash -s -- Pushed' < /tmp/wb-push.sh → a tab "Pushed" opens in Desktop.

Negative checks.

• curl -s -X DELETE -H "x-review-token: $TOK" $URL/reviews-api/$ID → 404 This route is not available for a review on another machine.
• Hosts file with a wrong token → state: "offline", detail devbox is offline: it did not accept the token.
• Add a second entry devbox2 with the same endpoint → devbox2 is duplicate ("… report the same server id …"); Remote-order is listed once.
• R pause a → offline within about 35 s (30 s heartbeat + 3 s health timeout); the review stays listed with hostState: "offline". R resume a → online.
• R ssh a -- whiteboard server reset-id while the server runs → refused A Whiteboard server is using … Stop it first, then run whiteboard server reset-id again.
• R install a --version 0.0.2-e2e; R ssh a -- whiteboard server stop, rerun step 3–5 → incompatible, detail devbox runs Whiteboard 0.0.2-e2e; this Desktop runs 0.2.0. Install Whiteboard 0.2.0 on devbox.
• Write not json to the hosts file → Desktop's output (the pnpm dev terminal) logs [Whiteboard gateway] Cannot read remote hosts from …: SyntaxError., with no file contents.
• A remote may send the laptop only authoringCapabilities, openApiReview and focusWindow, and never open another machine's review: not manually drivable; covered by src/server/review-gateway-pushes.test.ts and src/server/global-verb-relay.test.ts.

Cleanup. Common cleanup; rm $H/hosts.json first (it holds a token).

Common setup for all plans

Common setup (read once)

• Test each PR in a worktree at its head branch: git -C <core> worktree add --detach ../review-prN origin/<head>, then pnpm install there. Run everything below from that worktree root.
• Helpers (bash or zsh):

R() { node apps/review-desktop/scripts/e2e/remote/remote.mjs "$@"; }
export WB_TEST_RUN=manual-$$                  # before the first `R up`
S() { ssh -F /tmp/wbt.$WB_TEST_RUN/ssh_config "$@"; }   # host aliases are wb-test-<name>
H=/tmp/wb-home-$WB_TEST_RUN                   # isolated Desktop home
mkdir -p $H/review-desktop/state/user-data/User
echo '{"review.experimental.remoteHosts.enabled": true}' > $H/review-desktop/state/user-data/User/settings.json
awk '/createRemoteReview = String.raw`/{f=1;next} /^`;/{f=0} f' apps/review-desktop/scripts/e2e/journeys/remote-host.mjs > /tmp/wb-review.sh
sed -e 's/open\\":false/open\\":true/' -e 's/wbrepo/wbrepo2/g' /tmp/wb-review.sh > /tmp/wb-push.sh
edit() { printf '{"sessionId":"%s","edit":{"type":"insert","content":{"type":"markdown","markdown":"%s"}}}' "$2" "$3" | S "$1" 'whiteboard api session_edit -'; }

• Launch (dev build only; a packaged build ignores both env vars): DEV_REVIEW_HOME=$H DEV_FAST_REVIEW_SSH_CONFIG=/tmp/wbt.$WB_TEST_RUN/ssh_config pnpm dev (prefix DEV_FAST_REVIEW_DESKTOP_BACKGROUND=1 to keep it from taking focus).
• Desktop API: D=$(ls $H/review-desktop/instances/dev-*.json); URL=$(node -p "require('$D').url"); TOK=$(node -p "require('$D').token"); api() { curl -s -H "x-review-token: $TOK" "$URL$1"; }
• A remote review: ID=$(S wb-test-a 'bash -s -- Remote-order' < /tmp/wb-review.sh | head -1) (repo ~/wbrepo, review "Remote-order" with a prose line and a code peek of f.ts). /tmp/wb-push.sh is the same with open: true in ~/wbrepo2.
• Settings: ⌘, → region Remote hosts → type the alias in SSH alias → Add.
• Fork unit tests: (cd apps/review-desktop && TSX_TSCONFIG_PATH=tsconfig.test.json node --import tsx --test --test-force-exit <files>). Package tests: pnpm --filter @dev.fast/whiteboard test <files>.
• Journeys: stage a runtime per apps/review-desktop/scripts/e2e/TESTING.md ("Staging the runtime"), then node apps/review-desktop/scripts/e2e/run.mjs --runtime "$REVIEW_E2E_RUNTIME" --journey <name>.
• The harness has pause/resume (there is no unpause).
• Cleanup, every plan: quit Desktop first (its ssh masters count as leftovers), then R down --all; R verify-clean; rm -rf $H /tmp/wb-*.sh. Without an aws sso login session verify-clean also prints AWS could not be checked and exits 1; no other line may appear.