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.

Verify remote viewers in browser and enforce complete forwarding coverage

Deed92c035a0af3
diff --git a/cli/.gitignore b/cli/.gitignore
index 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.env
diff --git a/cli/package.json b/cli/package.json
index 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.ts
index 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.ts
index 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)?.requestId
if (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.ts
index 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.ts
index 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 must
diff --git a/cli/src/lib/e2ee/relayClient.ts b/cli/src/lib/e2ee/relayClient.ts
index 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 frame
const 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.ts
index 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, including
const 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).origin
const 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.ts
index 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.ts
index 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_BYTES
private heldAck = 0
private incomingEnded = false
+ private responseReady = false
private peerClosed = false
private pending: { bytes: Buffer; offset: number; done: (error?: Error | null) => void } | null = null
private 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.ts
new file mode 100644
index 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.md
index 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 OS
launch 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 profiles
New Agent → Codex discovers local profiles when the Harness CLI advertises
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index 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.md
index 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 catalog
identifies published revisions, and the Store shows "Update". `harness dsh update <id>` and the
Store upgrade packages while preserving workspaces and restoring the previous package if setup or
diff --git a/docs/plans/2026-09-17-004-remote-viewers.md b/docs/plans/2026-09-17-004-remote-viewers.md
new file mode 100644
index 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.md
index 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 th
Explore, then switch to Play: steer, jump, collect gates, reach the finish, and restart. Its
geometry 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