src/remote-control/ owns Remote Workspace contracts, explicit executor construction and Hub session adapters. The server exposes this surface only with Hub role and OCX_REMOTE_WORKSPACE_ENABLED=1. The side-effect-free activation guard loads no services. Existing Remote Hub provider routing remains in src/remote/ and is a separate capability.
src/remote-control/protocol.ts owns frame and identity contracts. src/remote-control/crypto.ts implements signed handshakes and directional encryption. src/remote-control/workspace-agent-protocol.ts parses bounded control messages; src/remote-control/workspace-rpc-framing.ts bounds reassembly allocation, count and expiry. Importing these modules starts no process or timer; incomplete reassembly owns expiry timers after an explicit call.
src/remote-control/workspace-agent-connection.ts intersects presence with enrollment authority and negotiates explicit session grants. src/remote-control/workspace-rpc.ts snapshots session/device/root/capabilities and rejects mismatches before invoking the executor. The paired Hub is trusted to select an approved root over authenticated WSS; workspace control traffic is not an untrusted opaque relay protocol.
src/remote-control/workspace-executor.ts checks approved root identity, relative paths, file size and write preconditions. File reads and write preconditions open descriptors nonblocking before verifying regular-file identity, so special files cannot wait for a peer during open. Its optional command runner lives in src/remote-control/workspace-command-runner.ts. Linux uses bubblewrap outside writable workspace roots and checks executable/parent permissions before invocation. The official Windows and macOS native helpers refuse commands; file tools remain independent of command availability.
src/remote-control/workspace-hub.ts, src/remote-control/workspace-device.ts and src/remote-control/workspace-sessions.ts own separate persisted state. src/remote-control/workspace-secret-store.ts requires private permissions and rejects access failures rather than treating them as first-run absence. Publication reuses src/config/atomic-write.ts; workspace file publication uses the remote-workspace publisher in src/lib/windows-atomic-replace.ts.
src/remote-control/workspace-runtime.ts is the lazy composition owner for Hub services. Codex, Claude and Pi adapters keep model processes on the Hub and expose selected remote tools. Their source configuration is not evidence of live CLI confinement. src/cli/remote-workspace.ts contains registered executor pair/agent/status handling; the machine-readable entries live in src/cli/capabilities.ts.
The optional terminal prototype in src/remote-control/host.ts invokes only a caller-supplied factory after authenticated traffic. src/remote-control/relay.ts routes opaque prototype envelopes after caller authorization. Neither is a production terminal service.
Regression coverage lives in tests/clients/remote-workspace-session-binding.test.ts, tests/clients/remote-workspace-secret-store.test.ts and the adjacent protocol, agent-wire, device, hub, sessions and command-runner tests. Real CLI and native confinement tests require their explicit environments; generic suite success does not certify those paths. Windows command support remains unavailable pending a verified lifecycle owner.
src/server/index.ts admits the opt-in pair exchange and bearer-authenticated agent upgrade after Origin and role checks. The unauthenticated loopback companion does not expose either endpoint. src/server/management-api.ts answers disabled workspace status before importing services; mutations require a dashboard session. src/server/management/remote-workspace-routes.ts reads bounded management JSON and uses the initialized Hub/session services.
The listener retains an awaited shutdown callback only after optional activation. It refuses initialization once stop begins, starts listener admission closure and workspace cleanup concurrently, and awaits session shutdown before closing Hub connections in a finally path. Listener drain completes after these owned sockets close; cleanup failures still propagate. src/server/ws-bridge.ts carries structural receive/open/close callbacks without importing concrete workspace services.
gui/src/pages/RemoteWorkspace.tsx defaults to read-only access, displays actual effective capabilities, and keeps Stop available while a prompt is pending. Error retries preserve draft text. The UI explains explicit Hub opt-in in each locale; no historical screenshot is evidence of the current surface.
Hub runtime admission counts pending create/resume starts as well as live handles against global and per-device limits; every outcome releases its reservation. Stop and shutdown reclaim late resumed handles before clearing ownership. Coordinator result size limits normalize both response text and success, so bridge and MCP callers receive consistent errors.
Prompt HTTP admission returns 202 with the existing session/event cursor; tracked operations publish terminal status for polling and attach a rejection observer immediately. Reconnect/resume cannot publish ready while a turn is active. The dashboard prefers newer local event cursors over stale polling, favors authoritative polling on ties, retains unconfirmed draft text with an uncertainty notice, and never retries prompt POSTs automatically.