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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
Verify remote viewers in browser and enforce complete forwarding coverage
Deed92c035a0af3
diff --git a/cli/.gitignore b/cli/.gitignoreindex f6fc48fa4..3e29143c6 100644--- a/cli/.gitignore+++ b/cli/.gitignore@@ -3,5 +3,6 @@ dist/.env*.tsbuildinfo.DS_Store+coverage/# The Docker rig's pinned computer id — local to this checkout.docker/remote-machine/.rig.envdiff --git a/cli/package.json b/cli/package.jsonindex 6acd338e7..83fece5ac 100644--- a/cli/package.json+++ b/cli/package.json@@ -13,6 +13,7 @@"start": "node dist/cli.js","test": "vitest run","test:dsh-updates": "vitest run --config vitest.dsh-updates.config.ts",+ "test:remote-viewers": "vitest run --config vitest.viewer.config.ts","test:cursor-e2e": "RUN_CURSOR_E2E=1 vitest run src/engines/cursor/localE2e.spec.ts","test:tmux-real": "RUN_REAL_TMUX_DISCOVERY=1 vitest run src/lib/tmuxAgentDiscovery.real.spec.ts --reporter=verbose","test:herdr-real": "RUN_REAL_HERDR=1 vitest run src/lib/herdrBackend.real.spec.ts --reporter=verbose",diff --git a/cli/src/backendSocket.spec.ts b/cli/src/backendSocket.spec.tsindex 9270c5b78..9bef7a600 100644--- a/cli/src/backendSocket.spec.ts+++ b/cli/src/backendSocket.spec.ts@@ -15,6 +15,35 @@ import { randomUUID } from 'node:crypto'import { fakeGridAnswers, installFakeGrid, type FakeGrid } from './lib/__fixtures__/fakeGrid.js'import { clearGridMcpUrlCache } from './lib/gridMcpUrl.js'+describe('viewer forwarding authentication', () => {+ it('requires encryption and a web-role session remotely, while permitting trusted local clients', async () => {+ const socket = new BackendSocket('token')+ const internals = socket as any+ const handle = vi.spyOn(socket.viewerForwarder, 'handle').mockImplementation(() => {})+ const role = vi.spyOn(internals.e2ee, 'sessionRole').mockReturnValue('web')+ const frame = { type: 'viewer_request', payload: { streamId: 'v', agentId: 'a' } }+ const unwrap = vi.spyOn(internals.e2ee, 'unwrapDown').mockReturnValue(frame)+ await internals.dispatchDown(frame, 'remote')+ expect(unwrap).not.toHaveBeenCalled()+ expect(handle).not.toHaveBeenCalled()+ const encrypted = { type: 'viewer_request', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'fixture' } } }+ role.mockReturnValue('device')+ await internals.dispatchDown(encrypted, 'remote')+ expect(handle).not.toHaveBeenCalled()+ role.mockReturnValue('web')+ await internals.dispatchDown(encrypted, 'remote')+ expect(handle).toHaveBeenCalledWith('remote', 'viewer_request', frame.payload)+ socket.registerLocalClient('local:viewer', { sendFrame: () => true, sendBinary: () => true })+ await internals.dispatchDown(frame, 'local:viewer')+ expect(handle).toHaveBeenCalledWith('local:viewer', 'viewer_request', frame.payload)+ handle.mockClear()+ await internals.dispatchDown({ type: 'viewer_arbitrary', payload: {} }, 'local:viewer')+ expect(handle).not.toHaveBeenCalled()+ await socket.unregisterLocalClient('local:viewer')+ await socket.stop()+ })+})+const wsMock = vi.hoisted(() => {const instances: MockWebSocket[] = []diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.tsindex 60083ed1e..0df17a0e0 100644--- a/cli/src/backendSocket.ts+++ b/cli/src/backendSocket.ts@@ -1182,7 +1182,7 @@ export class BackendSocket {}// Client→adapter encrypted frames: chat messages plus trusted web control actions. Plaintext// passes through for legacy/device transition paths; undecryptable ciphertext is dropped.- if (!local && isEncryptedDownType(type)) {+ if (!local && (isEncryptedDownType(type) || VIEWER_DOWN_TYPES.has(type))) {if (type !== 'message' && type !== 'question_response' && !isWrapped(frame.payload)) {const requestId = (frame.payload as { requestId?: unknown } | undefined)?.requestIdif (requestId !== undefined) this.emitReply(connId, type, requestId, { error: 'E2EE_REQUIRED' })diff --git a/cli/src/dsh/viewer.spec.ts b/cli/src/dsh/viewer.spec.tsindex f70a163f3..0b81c963a 100644--- a/cli/src/dsh/viewer.spec.ts+++ b/cli/src/dsh/viewer.spec.ts@@ -87,6 +87,22 @@ describe('DshViewerManager', () => {expect(spawned).toHaveLength(1)})+ it('forwards only a running viewer on the allocated loopback port', async () => {+ setup()+ expect(manager!.forwardingUrl('a1')).toBeNull()+ await manager!.start('a1', dsh({ command: 'v', url: 'http://127.0.0.1:${port}/' }), '/ws')+ expect(manager!.forwardingUrl('a1')).toBe('http://127.0.0.1:4790/')+ await manager!.stop('a1')+ expect(manager!.forwardingUrl('a1')).toBeNull()+ })++ it.each(['http://127.0.0.1:22/', 'http://example.com:${port}/', 'https://127.0.0.1:${port}/'])('does not forward a manifest URL outside its managed HTTP port: %s', async (url) => {+ setup()+ await manager!.start('a1', dsh({ command: 'v', url }), '/ws')+ expect(manager!.url('a1')).not.toBeNull()+ expect(manager!.forwardingUrl('a1')).toBeNull()+ })+it('republishes when the verdict names an artifact, and only when the URL changes', async () => {const { urls } = setup()await manager!.start('a1', dsh({ command: 'v', url: 'http://127.0.0.1:${port}/?file=${artifact}' }), '/ws')diff --git a/cli/src/lib/e2ee/core.ts b/cli/src/lib/e2ee/core.tsindex a1fb8b565..9dd3e5850 100644--- a/cli/src/lib/e2ee/core.ts+++ b/cli/src/lib/e2ee/core.ts@@ -381,8 +381,6 @@ export const ENCRYPTED_DOWN_TYPES = new Set<string>([// The desktop's pane colours for this machine's tmux sessions (lib/hostTheme.ts). Same trap as// above if missing: the envelope would never be opened and the app would wait out its timeout.'theme_set',- // Viewer HTTP/WebSocket bytes and control travel only inside the paired machine session.- 'viewer_request', 'viewer_data', 'viewer_ack', 'viewer_end', 'viewer_close','device_e2ee_pair', 'e2ee_pairings_list', 'e2ee_pairing_unpair','e2ee_pairings_unpair_all', 'e2ee_browser_link_create',// Remote terminal control is always pairwise E2EE. The relay may route by outer type/connId but mustdiff --git a/cli/src/lib/e2ee/relayClient.ts b/cli/src/lib/e2ee/relayClient.tsindex e6c70ec15..0273c4387 100644--- a/cli/src/lib/e2ee/relayClient.ts+++ b/cli/src/lib/e2ee/relayClient.ts@@ -14,6 +14,7 @@ import * as C from './core.js'import { deriveTerminalBinaryKey, openTerminalBinary, sealTerminalBinary, type TerminalBinaryClear } from '../terminalBinary.js'import { pwCpaceGenerator, pwContext, stretchPassword } from './passwordPake.js'import { ReplayWindow } from './replayWindow.js'+import { VIEWER_DOWN_TYPES } from '../viewerWire.js'type Frame = Record<string, unknown>@@ -106,7 +107,8 @@ export class RelaySessionCrypto {/** Encrypt an outgoing (local app → remote machine) frame if its type requires it. */wrapOutgoing(frame: Frame): Frame {const type = frame.type as string | undefined- if (!type || !this.c2s || !C.isEncryptedDownType(type)) return frame+ // CLI-to-CLI viewer forwarding is a negotiated extension; the shared crypto core stays byte-identical.+ if (!type || !this.c2s || (!C.isEncryptedDownType(type) && !VIEWER_DOWN_TYPES.has(type))) return frameconst payload = C.wrapPayload(this.c2s, 'p', this.c2sCounter++, type, undefined, frame.payload)return { ...frame, payload }}diff --git a/cli/src/lib/remoteViewerRelay.spec.ts b/cli/src/lib/remoteViewerRelay.spec.tsindex b278fd7e7..8c9db3b21 100644--- a/cli/src/lib/remoteViewerRelay.spec.ts+++ b/cli/src/lib/remoteViewerRelay.spec.ts@@ -1,6 +1,6 @@import { afterEach, expect, it } from 'vitest'import { once } from 'node:events'-import { createServer, request } from 'node:http'+import { createServer } from 'node:http'import type { AddressInfo } from 'node:net'import { WebSocket, WebSocketServer } from 'ws'import { BackendSocket, type Frame } from '../backendSocket.js'@@ -11,10 +11,11 @@ import { E2eeStore } from './e2ee/store.js'import { b64e, fingerprint, newIdentity } from './e2ee/core.js'import { MachinePeerStore } from './e2ee/machinePeers.js'import { RemoteRelayPool } from './remoteRelay.js'-import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'import { tmpdir } from 'node:os'import { join } from 'node:path'import type { InstalledDsh } from '../dsh/installed.js'+import { spawn } from 'node:child_process'const cleanup: Array<() => unknown | Promise<unknown>> = []afterEach(async () => { for (const close of cleanup.splice(0).reverse()) await close() })@@ -70,10 +71,25 @@ it('desktop local-ws → relay → E2EE → daemon → spawned viewer, includingconst dir = mkdtempSync(join(tmpdir(), 'harness-viewer-e2e-'))cleanup.push(() => rmSync(dir, { recursive: true, force: true }))writeFileSync(join(dir, 'viewer.mjs'), `import http from 'node:http';+import { WebSocketServer } from ${JSON.stringify(import.meta.resolve('ws'))};const server = http.createServer((req, res) => {if (req.url === '/events') { res.writeHead(200, {'Content-Type': 'text/event-stream'}); res.write('data: encrypted-live-output\\n\\n'); }- else res.end('<html>encrypted-viewer-output<img src="/asset.svg"></html>');+ else if (req.url === '/asset.svg') { res.writeHead(200, {'Content-Type': 'image/svg+xml'}); res.end('<svg xmlns="http://www.w3.org/2000/svg" width="80" height="80"><circle cx="40" cy="40" r="30" fill="green"/></svg>'); }+ else if (req.url === '/api' && req.method === 'POST') {+ if (req.headers.origin !== 'http://127.0.0.1:' + process.env.HARNESS_VIEWER_PORT) { res.writeHead(403).end(); return; }+ req.pipe(res);+ }+ else res.end(${JSON.stringify(`<html><body>encrypted-viewer-output<img src="/asset.svg"><script>+Promise.all([+ fetch('/asset.svg').then(r => { if (!r.ok) throw Error('asset'); return r.text(); }),+ fetch('/api', {method:'POST', body:'browser-post'}).then(r => r.text()).then(t => { if(t !== 'browser-post') throw Error('POST'); }),+ new Promise((resolve, reject) => { const e = new EventSource('/events'); e.onmessage = event => { e.close(); event.data === 'encrypted-live-output' ? resolve() : reject(Error('SSE')); }; e.onerror = reject; }),+ new Promise((resolve, reject) => { const w = new WebSocket(location.origin.replace('http:', 'ws:') + '/ws'); w.onopen = () => w.send('browser-websocket'); w.onmessage = e => { w.close(); e.data === 'browser-websocket' ? resolve() : reject(Error('WebSocket')); }; w.onerror = reject; }),+]).then(() => document.body.setAttribute('data-viewer-test', 'passed')).catch(e => document.body.setAttribute('data-viewer-test', 'failed:' + e));+</script></body></html>`)});});+const wss = new WebSocketServer({server});+wss.on('connection', ws => ws.on('message', (data, binary) => ws.send(data, {binary})));server.listen(Number(process.env.HARNESS_VIEWER_PORT), '127.0.0.1');`)const manager = new DshViewerManager({onUrl: (agentId, viewerUrl) => {@@ -85,7 +101,7 @@ server.listen(Number(process.env.HARNESS_VIEWER_PORT), '127.0.0.1');`)cleanup.push(() => manager.stopAll())const dsh: InstalledDsh = {id: 'test/viewer', realDir: dir, dir, source: '', ref: null, commit: null, linked: false, installedAt: 0,- manifest: { spec: 1, id: 'test/viewer', name: 'Viewer test', engine: 'claude', viewer: { command: `${JSON.stringify(process.execPath)} viewer.mjs`, url: 'http://127.0.0.1:${port}/?file=${artifact}' } },+ manifest: { spec: 1, id: 'test/viewer', name: 'Viewer test', engine: 'claude', viewer: { command: `'${process.execPath.replaceAll("'", "'\\''")}' viewer.mjs`, url: 'http://127.0.0.1:${port}/?file=${artifact}' } },}const pool = new RemoteRelayPool({ accessToken: async () => 'fixture-token' } as never, base, localIdentity, peers)@@ -99,10 +115,10 @@ server.listen(Number(process.env.HARNESS_VIEWER_PORT), '127.0.0.1');`)cleanup.push(() => desktop.terminate())const frames: Frame[] = []desktop.on('message', (raw) => frames.push(JSON.parse(raw.toString())))- async function until(predicate: () => boolean): Promise<void> {- const deadline = Date.now() + 5000- while (!predicate()) {- if (Date.now() > deadline) throw new Error('E2E condition did not arrive')+ async function until(predicate: () => boolean | Promise<boolean>, detail = 'E2E condition'): Promise<void> {+ const deadline = Date.now() + 10_000+ while (!await predicate()) {+ if (Date.now() > deadline) throw new Error(`${detail} did not arrive`)await new Promise((resolve) => setTimeout(resolve, 10))}}@@ -119,6 +135,47 @@ server.listen(Number(process.env.HARNESS_VIEWER_PORT), '127.0.0.1');`)const localOrigin = new URL(url).originconst page = await fetch(localOrigin + bootstrap.headers.get('location'), { headers: { cookie } })expect(await page.text()).toContain('encrypted-viewer-output')+ if (process.env.HARNESS_VIEWER_BROWSER) {+ const profile = join(dir, 'browser-profile')+ const browser = spawn(process.env.HARNESS_VIEWER_BROWSER, [+ '--headless', '--disable-gpu', '--no-first-run', '--no-default-browser-check',+ '--disable-background-networking', '--disable-component-update',+ `--user-data-dir=${profile}`, '--remote-debugging-port=0', '--remote-debugging-address=127.0.0.1', 'about:blank',+ ], { stdio: 'ignore' })+ const exited = once(browser, 'exit')+ let devtools: WebSocket | undefined+ try {+ await until(() => existsSync(join(profile, 'DevToolsActivePort')), 'Browser debugger')+ const [port, path] = readFileSync(join(profile, 'DevToolsActivePort'), 'utf8').trim().split('\n')+ devtools = new WebSocket(`ws://127.0.0.1:${port}${path}`)+ await once(devtools, 'open')+ let nextId = 0+ const pending = new Map<number, (response: any) => void>()+ devtools.on('message', (raw) => {+ const response = JSON.parse(raw.toString())+ const done = pending.get(response.id)+ pending.delete(response.id)+ done?.(response)+ })+ const command = (method: string, params: Record<string, unknown> = {}, sessionId?: string): Promise<any> => new Promise((resolve, reject) => {+ const id = ++nextId+ pending.set(id, (r) => r.error ? reject(new Error(JSON.stringify(r.error))) : resolve(r.result))+ devtools!.send(JSON.stringify({ id, method, params, sessionId }))+ })+ const { targetId } = await command('Target.createTarget', { url: 'about:blank' })+ const { sessionId } = await command('Target.attachToTarget', { targetId, flatten: true })+ await command('Page.navigate', { url }, sessionId)+ await until(async () => {+ const { result } = await command('Runtime.evaluate', { expression: "document.body?.getAttribute('data-viewer-test')", returnByValue: true }, sessionId)+ if (result.value?.startsWith('failed')) throw new Error(result.value)+ return result.value === 'passed'+ }, 'Browser assets, POST, SSE and WebSocket checks')+ } finally {+ devtools?.terminate()+ browser.kill('SIGTERM')+ await exited+ }+ }const live = await fetch(localOrigin + '/events', { headers: { cookie } })const reader = live.body!.getReader()expect(new TextDecoder().decode((await reader.read()).value)).toContain('encrypted-live-output')@@ -142,4 +199,4 @@ server.listen(Number(process.env.HARNESS_VIEWER_PORT), '127.0.0.1');`)expect(code).toBe(4404)await expect(fetch(restarted)).rejects.toThrow()expect(peers.get(machineId)).toBeNull()-}, 20_000)+}, 40_000)diff --git a/cli/src/lib/viewerWire.spec.ts b/cli/src/lib/viewerWire.spec.tsindex b02ac8bbe..52776d314 100644--- a/cli/src/lib/viewerWire.spec.ts+++ b/cli/src/lib/viewerWire.spec.ts@@ -35,6 +35,18 @@ describe('viewer stream lifecycle and failure handling', () => {active.write(Buffer.from('data'))await vi.advanceTimersByTimeAsync(30001)expect(active.destroyed).toBe(true)+ // Upload credit is not an HTTP response. A fully accepted POST still needs a header deadline.+ const upload = new ViewerWire('c', () => true)+ upload.write(Buffer.from('body'))+ upload.handle('viewer_ack', { bytes: 4 })+ await vi.advanceTimersByTimeAsync(30001)+ expect(upload.destroyed).toBe(true)+ // Headers do not forgive a stalled body in the opposite direction either.+ const duplex = new ViewerWire('d', () => true)+ duplex.write(Buffer.from('body'))+ duplex.ready()+ await vi.advanceTimersByTimeAsync(30001)+ expect(duplex.destroyed).toBe(true)})it('handles failed sends, cancellation with queued writes and data arriving after close', () => {diff --git a/cli/src/lib/viewerWire.ts b/cli/src/lib/viewerWire.tsindex e7f97d5a0..e75334c1d 100644--- a/cli/src/lib/viewerWire.ts+++ b/cli/src/lib/viewerWire.ts@@ -33,6 +33,7 @@ export class ViewerWire extends Duplex {private receiveCredit = VIEWER_WINDOW_BYTESprivate heldAck = 0private incomingEnded = false+ private responseReady = falseprivate peerClosed = falseprivate pending: { bytes: Buffer; offset: number; done: (error?: Error | null) => void } | null = nullprivate deadline: NodeJS.Timeout@@ -46,7 +47,10 @@ export class ViewerWire extends Duplex {}/** The HTTP headers arrived. An idle SSE/WebSocket is valid; stalled writes still have a deadline. */- ready(): void { clearTimeout(this.deadline) }+ ready(): void {+ this.responseReady = true+ if (this.credit === VIEWER_WINDOW_BYTES) clearTimeout(this.deadline)+ }private armDeadline(): void {clearTimeout(this.deadline)@@ -112,7 +116,7 @@ export class ViewerWire extends Duplex {return}this.credit += Number(bytes)- if (this.credit === VIEWER_WINDOW_BYTES) clearTimeout(this.deadline)+ if (this.credit === VIEWER_WINDOW_BYTES && this.responseReady) clearTimeout(this.deadline)else this.armDeadline()this.flushPending()} else if (type === 'viewer_data') {diff --git a/cli/vitest.viewer.config.ts b/cli/vitest.viewer.config.tsnew file mode 100644index 000000000..9e3b22f31--- /dev/null+++ b/cli/vitest.viewer.config.ts@@ -0,0 +1,24 @@+import { defineConfig } from 'vitest/config'+import base from './vitest.config.js'++/** The forwarding implementation has a per-file 100% coverage gate, including failure paths. */+export default defineConfig({+ test: {+ ...base.test,+ include: [+ 'src/lib/viewerWire.spec.ts',+ 'src/lib/viewerForwarder.spec.ts',+ 'src/lib/remoteViewerProxy.spec.ts',+ 'src/lib/remoteViewerProxy.faults.spec.ts',+ 'src/lib/remoteViewerRelay.spec.ts',+ ],+ coverage: {+ enabled: true,+ provider: 'v8',+ include: ['src/lib/viewerWire.ts', 'src/lib/viewerForwarder.ts', 'src/lib/remoteViewerProxy.ts'],+ reporter: ['text', 'json-summary', 'json', 'html'],+ reportsDirectory: 'coverage/remote-viewers',+ thresholds: { perFile: true, statements: 100, branches: 100, functions: 100, lines: 100 },+ },+ },+})diff --git a/desktop/README.md b/desktop/README.mdindex e9a5b4206..3e024b146 100644--- a/desktop/README.md+++ b/desktop/README.md@@ -66,6 +66,18 @@ Install the companion CLI's npm dependencies first; ffmpeg must be on PATH.The smoke test does not use a real account or remote machine. It verifies the OSlaunch URI; playback in the native viewer is a separate manual check.+## Viewers on linked machines++Open a harness on a linked machine and its viewer appears beside the terminal. The local CLI+forwards it through the existing encrypted machine connection, including interactive controls,+streaming updates and WebSockets. Both computers need a forwarding-capable Harness CLI. An older+remote CLI shows update guidance in the viewer pane; reconnect after updating it.++The local viewer endpoint is private to the machine connection and closes on disconnect or+revocation. This feature uses your existing machine access; it does not create a public share link.+Embedded viewers remain macOS-only. See the+[remote viewer plan](../docs/plans/2026-09-17-004-remote-viewers.md) for compatibility and tests.+## Local Codex profilesNew Agent → Codex discovers local profiles when the Harness CLI advertisesdiff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dartindex 87c1250db..e2dbb6432 100644--- a/desktop/lib/state/app_state.dart+++ b/desktop/lib/state/app_state.dart@@ -4380,8 +4380,9 @@ class AppNotifier extends ChangeNotifier {final agent = machine?.agents.where((a) => a.id == agentId).firstOrNull;if (machine == null ||agent == null ||- (agent.viewerUrl == null && agent.viewerError == null))+ (agent.viewerUrl == null && agent.viewerError == null)) {return;+ }_dismissedViewers.remove(_viewerKey(machineId, agentId));_syncViewerPane(machine, agent);notifyListeners();diff --git a/docs/plans/2026-09-17-001-zero-to-one-ideas.md b/docs/plans/2026-09-17-001-zero-to-one-ideas.mdindex 444d2eb0d..43cc367e1 100644--- a/docs/plans/2026-09-17-001-zero-to-one-ideas.md+++ b/docs/plans/2026-09-17-001-zero-to-one-ideas.md@@ -143,10 +143,10 @@ agent's terminal can run code as Bob's user, on Bob's machine:## Gaps found on the way (not zero-to-one, but they will hurt soon)-- **Viewers do not work across machines.** A harness running on another machine cannot show its viewer- pane in the app; `store/agents/godogen/README.md` names forwarding a viewer from a linked remote- machine as a platform requirement still to build. Harness is multi-machine by design, so this is a- core gap — and step 1 of sharing needs the same forwarding, safely.+- **Remote viewers — implemented.** The desktop's CLI forwards a linked machine's viewer through its+ existing encrypted connection; both CLIs need the forwarding-capable version. See+ [the implementation and validation plan](2026-09-17-004-remote-viewers.md). This preserves the+ owner's interactive viewer access; read-only public sharing still needs its own restrictions.- **Harness updates — implemented.** Installed packages track their source commit, the catalogidentifies published revisions, and the Store shows "Update". `harness dsh update <id>` and theStore upgrade packages while preserving workspaces and restoring the previous package if setup ordiff --git a/docs/plans/2026-09-17-004-remote-viewers.md b/docs/plans/2026-09-17-004-remote-viewers.mdnew file mode 100644index 000000000..3d3cb6eb7--- /dev/null+++ b/docs/plans/2026-09-17-004-remote-viewers.md@@ -0,0 +1,84 @@+# Remote harness viewers++Status: implemented on `codex/remote-viewers` · 2026-09-17++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+deployment is required. This uses the existing trusted machine link and preserves the owner's+interactive viewer access. Public watch links and collaborator permissions remain separate work.++## Connection++1. The remote daemon owns the viewer process and its allocated loopback port. It advertises+ `viewerForwarding: 1` inside the authenticated E2EE welcome.+2. The desktop's CLI rewrites viewer URLs in agent lists, creation/restart replies, and agent+ updates. Each remote agent gets a distinct local HTTP origin. Public HTTP(S) viewer URLs keep+ their existing behavior.+3. A short-lived bootstrap URL sets an HttpOnly, SameSite cookie and redirects to the viewer's+ original path, query and fragment. Root-relative assets and WebSocket URLs keep working.+4. HTTP requests, response metadata and streaming bytes travel as pairwise encrypted `viewer_*`+ frames on the existing WebSocket relay. Terminal WebRTC negotiation stays independent.+5. The remote endpoint resolves the agent through the viewer manager. It accepts only a currently+ running HTTP loopback viewer on the port the manager allocated. Requests cannot choose another+ host or port. HTTP redirects are returned to the browser, never followed by the daemon.++HTTP bodies stream in both directions, including POST, Range responses and EventSource. WebSocket+upgrades preserve subprotocols and carry their binary byte stream. Request Host, Origin and Referer,+same-origin response redirects, and viewer cookies are translated between the two origins. The+bootstrap cookie and unrelated local cookies never leave the desktop's computer.++## Bounds and cleanup++- 32 KiB data frames with a 128 KiB credit window per direction. A stalled consumer applies+ backpressure; files are not loaded into memory in full.+- At most 64 active streams per client, 256 per remote daemon, and 64 local viewer gateways per+ machine connection. Requests awaiting response headers or transfer credit time out after 30 seconds.+- Only authenticated web-role sessions or trusted local CLI clients can request a forward.+ 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+ 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.+- Older remote CLIs produce a viewer pane with update guidance. Local bind failures produce a+ recoverable viewer error while still returning the agent RPC.++## Compatibility and validation++Embedded viewers retain the desktop's macOS requirement. Mobile and direct-to-relay viewer builds+without a local CLI do not gain this forwarding path. A viewer should use relative URLs or+`location.origin` for assets and sockets; hard-coded remote loopback URLs inside JavaScript, HTML,+CSS or CSP are not rewritten. Forwarded viewers must use HTTP on their managed loopback port.++`cd cli && npm run test:remote-viewers` enforces **100% statements, branches, functions and lines on+each of the three new forwarding modules**. It includes network integration, malicious/malformed+requests, cancellation, resource limits and fault injection. It does not claim 100% coverage of the+entire CLI or desktop application.++The end-to-end test uses a desktop local WebSocket, the production relay pool, real E2EE identities,+the production remote daemon dispatcher, a viewer process launched by `DshViewerManager`, and an+opaque loopback backend fixture. It checks response streaming, ciphertext on the relay, restart,+and trust revocation. Set `HARNESS_VIEWER_BROWSER` to a Chromium executable to also run a fresh browser+profile through bootstrap cookies, root-relative assets, POST, SSE and WebSockets:++```sh+cd cli+HARNESS_VIEWER_BROWSER='/Applications/Google Chrome.app/Contents/MacOS/Google Chrome' npm run test:remote-viewers+```++Coverage reports are in `cli/coverage/remote-viewers/`. Desktop tests in `web_pane_test.dart` cover+update guidance, dismissal, recovery and the existing viewer layout. All fixtures use temporary+identities/workspaces and require no real account or model invocation.++Validation recorded on 2026-09-17:++- 68 feature tests passed with the isolated Chrome browser check enabled.+- Each forwarding module reached 100% statements, branches, functions and lines: 476 statements,+ 305 branches, 86 functions and 337 executable lines in total.+- 192 surrounding daemon, local WebSocket, viewer-manager and E2EE regression tests passed.+- 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; native WKWebView rendering is covered by the existing app+integration rather than instantiated by Flutter widget tests.diff --git a/store/agents/godogen/README.md b/store/agents/godogen/README.mdindex d8f53660a..6b5d35f61 100644--- a/store/agents/godogen/README.md+++ b/store/agents/godogen/README.md@@ -8,9 +8,9 @@ The starter, **Alpine Drift**, is a small playable snowboarding course. Orbit thExplore, then switch to Play: steer, jump, collect gates, reach the finish, and restart. Itsgeometry is procedural; opening and changing the starter needs no asset-service account.-Use the desktop app on the machine running this harness. The current app loads viewer URLs-directly; forwarding a viewer from a linked remote machine is a platform requirement still-to implement. This limitation also applies to the other local web viewers.+The macOS desktop app can show this viewer locally or from a linked remote machine. Remote viewing+requires the forwarding-capable Harness CLI on both computers; older remote CLIs show update+guidance. The viewer remains interactive, including Play and workspace build controls.## Use