Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

Record remote viewer deployment and physical machine validation

Deed2debfaac029
diff --git a/docs/plans/2026-09-17-004-remote-viewers.md b/docs/plans/2026-09-17-004-remote-viewers.md
index d9d0016db..6e0f0a3ee 100644
--- a/docs/plans/2026-09-17-004-remote-viewers.md
+++ b/docs/plans/2026-09-17-004-remote-viewers.md
@@ -1,6 +1,6 @@
# Remote harness viewers
-Status: implemented on `codex/remote-viewers` · 2026-09-17
+Status: implemented on `codex/remote-viewers` · validation updated 2026-09-18
A harness on a linked machine opens its viewer beside its terminal in the desktop app. Both
machines need the forwarding-capable CLI. No public listener, inbound port, SSH tunnel, or relay
@@ -37,9 +37,10 @@ bootstrap cookie and unrelated local cookies never leave the desktop's computer.
Plaintext viewer replies and group-encrypted viewer replies are rejected by the desktop's relay.
- The gateway checks Host, Origin, Referer and fetch metadata, and requires its own bootstrap cookie.
Viewer cookies use a distinct namespace for each gateway, including across loopback ports.
-- Stopping/restarting a viewer, disconnecting/deselecting a machine, or revoking/evicting its E2EE
+- Stopping/restarting the viewer process, disconnecting/deselecting a machine, or revoking/evicting its E2EE
session closes the associated forwarding resources. Detach does this immediately, even while the
existing terminal relay connection lingers for reconnect. Artifact changes reuse the local origin.
+- Restarting only the model/agent process keeps its healthy viewer running, matching local behavior.
- Older remote CLIs produce a viewer pane with update guidance. Local bind failures produce a
recoverable viewer error while still returning the agent RPC.
@@ -79,6 +80,96 @@ Validation recorded on 2026-09-17:
- 23 desktop agent-model/viewer-pane tests passed; modified Dart files passed analysis.
- CLI type checking and build passed.
-The backend in these tests is an opaque relay fixture, not the hosted production service. The
-browser check exercises Chromium. Flutter widget tests verify viewer state and layout; they do
-not instantiate native WKWebView.
+The fast suite's backend is an opaque relay fixture. The deployment and physical-host tests below
+exercise the repository backend and hosted relay separately. Flutter widget tests verify viewer state
+and layout; they do not instantiate native WKWebView.
+
+## Deployment and physical-host validation — 2026-09-18
+
+The original 283 passing tests did **not** include a store viewer across physical machines. Additional
+checks were added after reviewing that gap. The coverage percentage above still applies only to the
+three forwarding modules; it is not whole-application coverage or a guarantee for every harness.
+
+| Local client | Harness host | Relay | What was exercised |
+| --- | --- | --- | --- |
+| iMac Home (`violet4.lan`, Intel/x64), Chrome | Same host, direct viewer URLs | None | Blender, Marp, Manim and Godogen viewer pages and assets |
+| iMac Home, two independent CLI processes | Same host, disposable workspaces | Two repository backend processes, real MongoDB and Redis | Real password linking; four store viewer commands; interactions; agent restart; backend-process outage/recovery; trust revocation |
+| iMac Home, Chrome and native WKWebView | M2 (`mac.lan`, Apple Silicon/arm64), separate daemon built from this branch | Hosted `https://harness-api.autonomous.ai` | All four store viewers loaded in both browser engines; interactions in Chrome; concurrent terminal traffic; large files and ranges |
+
+The physical run used the existing M2 installation's store packages with new test workspaces and a
+separate machine registration, identity, registry, auth directory and tmux socket. Its existing daemon,
+projects and trust relationships were not replaced. iMac Office was reachable and inventoried through
+Harness, but no viewer test was run there. The physical direction tested was **M2 → iMac Home**.
+Both disposable M2 machine registrations returned HTTP 200 on deletion after their peers stopped.
+The test bootstrap harness was deleted and a subsequent agent listing confirmed that both bootstrap
+IDs were absent. Logs, screenshots and fixture workspaces were retained for review.
+
+Specific assertions:
+
+- Blender's model viewer rendered a small valid glTF. A 12 MiB + 17 byte transfer matched its SHA-256
+ hash, a 1 MiB range returned HTTP 206, and a HEAD request succeeded in the local deployment test.
+ Remote terminal input was echoed while the physical-host download was in progress; terminal WebRTC
+ negotiated through TURN while viewer requests used the WebSocket relay.
+- Marp rendered the starter deck, navigated slides, received a live file edit over SSE in the local
+ deployment test, and remained usable after the real agent restart RPC on both topologies.
+- Manim's video viewer played and sought within a generated, decodable MP4. The video also played in
+ the native WKWebView probe.
+- Godogen's real starter project built and became playable. Keyboard input moved its player through
+ the forwarded iframe in Chrome; the same viewer reached a playable state in WKWebView.
+- The fast encrypted fixture also completed assets, POST, SSE and WebSocket round trips in native
+ WKWebView, in addition to Chrome. The 68-test suite remained at 100% on all four coverage metrics.
+- Killing a local backend process closed the local gateways; reconnecting restored the viewer.
+ The separate local deployment test revoked trust, removed the client's persisted pin, closed the
+ gateway, and deleted its test agents.
+- Revoking the disposable identity on M2 through its local owner API interrupted an active SSE
+ response at iMac Home, closed the local gateway and removed the persisted pin. A fresh handshake
+ using the revoked identity was refused by the hosted path with `NO_PEER_LINK`.
+
+These are **viewer transport tests**. Model CLIs are deterministic echo fixtures; Blender geometry and
+Manim media are generated fixtures, not model-produced work. The physical peer starts with temporary
+identity pins; the password-pairing flow is exercised by the full local deployment test. The WebKit
+probe uses an actual native WKWebView with the pane's JavaScript/media settings, but it does **not**
+launch the complete Flutter desktop app. Mobile, Linux clients, reverse direction, other store
+harnesses, and a prolonged network impairment/soak test are not covered by these results.
+
+### Reproduce
+
+`cli/scripts/remote-viewers-stack.ts` owns its processes, databases, identities and tmux sockets. It
+requires installed dependencies in `cli`, `backend`, `store/agents/godogen`,
+`store/agents/marp/toolchain` and `store/viewers/model-viewer`, plus tmux, ffmpeg and Chrome.
+`HARNESS_E2E_SERVICES_DIR` names a separate npm directory containing `mongodb-memory-server` and
+`redis-memory-server`; the recorded run used versions 11.2.0 and 0.17.1. Existing binaries can be
+selected with `HARNESS_E2E_MONGOD` and `HARNESS_E2E_REDIS_SERVER`.
+
+```sh
+cd cli
+HARNESS_VIEWER_STACK=1 HARNESS_E2E_SERVICES_DIR=/path/to/test-services \
+ node --import tsx scripts/remote-viewers-stack.ts
+npx tsc --noEmit -p tsconfig.viewer-tests.json
+```
+
+The macOS native probe can be enabled in the fast suite and physical-host runner:
+
+```sh
+swiftc -module-cache-path /tmp/viewer-swift-cache scripts/viewer-webkit.swift -o /tmp/viewer-webkit
+HARNESS_VIEWER_BROWSER='/Applications/Google Chrome.app/Contents/MacOS/Google Chrome' \
+ HARNESS_VIEWER_WEBKIT=/tmp/viewer-webkit npm run test:remote-viewers
+```
+
+For an explicitly selected physical host, `remote-viewer-live.ts init <client-dir>` creates a disposable
+client key and prints only its public key. On the remote host, `remote-viewer-peer.ts <client-pub>
+<new-peer-dir>` starts a separate daemon using its already-installed store packages and already-signed-in
+account. Both runners require `HARNESS_VIEWER_LIVE_TEST=1`. Copy only the resulting public
+`peer-info.json` back to the client, then run:
+
+```sh
+HARNESS_VIEWER_LIVE_TEST=1 HARNESS_VIEWER_WEBKIT=/tmp/viewer-webkit \
+ node --import tsx scripts/remote-viewer-live.ts run /path/to/client-dir /path/to/peer-info.json
+```
+
+The peer automatically stops after one hour, or when a `stop` file is created in its peer directory.
+It removes its test machine registration, terminates its daemon and tmux socket, and removes the copied
+auth directory. Logs and fixture workspaces remain for review. The client writes `results.json` and
+screenshots to its own directory. `HARNESS_VIEWER_REVOKE_CHECK=1` runs a separate active-stream
+revocation check: after `READY_FOR_REVOCATION`, invoke `/api/revoke-all` on **that disposable daemon's
+printed loopback port**, then stop the peer. This check writes `results-revocation.json`.