Skip to content

Native Qualification Console Panel Design

Jump to bottom
sergio velderrain edited this page Nov 12, 2026 · 1 revision

Native Qualification Console Panel Design

Status

Proposed design for SYS-REQ-035, REQ-134, and TEST-135. It authorizes no installation, implementation, VM operation, or live benchmark run. The existing Remmina candidate does not implement this design.

RDP Component

Use the version-matched Apache Guacamole 1.6.0 client and server, including guacd and libguac-client-rdp, hosted as a private VS Code WebviewPanel integration. Apache's release page identifies 1.6.0 as the current release; the official manual documents RDP, interactive credential prompting, loopback guacd binding, clipboard controls, and RDP drive redirection. The package source, release checksum, and signature must be verified and pinned before implementation; the client, server, and protocol components must use the same release. The browser RDP protocol remains the transport implementation; the project must not hand-roll RDP.

Sources: Apache Guacamole releases, Guacamole 1.6.0 configuration manual, Guacamole 1.6.0 client API.

Trust Boundaries

  • The VS Code extension host owns one panel session and asks the host-side native-trial controller for a short-lived capability bound to the exact grant digest, run ID, VM UUID, panel-session ID, allowed setup inputs, and expiry.
  • The session controller owns the monotonic SETUP -> LOCKING -> READ_ONLY -> CAPTURING -> REVIEWING -> ACTION -> CLOSED state machine. The WebView's disabled controls are presentation only; the gateway enforces the authoritative phase on every input event.
  • The guacd listener binds to 127.0.0.1 and accepts a session only through the per-run client gateway. The RDP target is exactly 127.0.0.1:<grant-sealed-host-port> for guest port 3389; no other host, address, or port is accepted.
  • The Guacamole client, server, and gateway share an ephemeral per-run runtime directory under current-user-private storage. The session controller owns creation and cleanup; directories are mode 0700, contain no frame captures, and are removed on close, expiry, teardown, or disconnect. A stale directory is removed only after validating its run/session binding.

Input And Phase Lock

During SETUP, the panel forwards only viewport-bounded keyboard and mouse events. Clipboard copy/paste is disabled (disable-copy=true, disable-paste=true); RDP drive redirection and SFTP are disabled; audio, printing, touch, session recording, host-global shortcuts, and arbitrary command/action routes are disabled. recording-path and typescript-path are not configured. Guest credentials are requested interactively by Guacamole; credential values, input payloads, and panel capabilities are not written to persistent configuration or URLs, and logs use a level/configuration that never records these values.

On an authorized Capture Desktop request, the controller transitions SETUP -> LOCKING, rejects new input events, drains and acknowledges the bounded in-flight input queue, commits the gateway's READ_ONLY state, and only then requests Capture Desktop. If draining, lock confirmation, or capture start fails, the run refuses or stops; the controller never reopens SETUP. Controller loss fails closed. Setup input intentionally defines the guest desktop state at capture start; no operator input is permitted during capture, review, or the model-selected action.

The setup baseline is a private, redacted setup-baseline.json containing only run ID, VM UUID, grant digest, hashed panel-session ID, synthetic task ID, phase-transition timestamps, and keyboard/mouse event counts. It contains no keystrokes, text, pointer coordinates, screenshots, or frame data. A separate action receipt binds the grant digest, run ID, VM UUID, MCP server and tool, model-selected candidate, event ID, and outcome; the panel gateway cannot issue or repeat that action.

Data Handling

The application does not persist raw frames or input payloads to files, logs, receipts, or evidence. Frames exist only in the bounded live session buffer and are cleared on close, expiry, teardown, or disconnect. Guacamole graphical/text recording is disabled by omitting recording paths. The implementation and tests make no claim to disable operating-system swap or crash dumps.

Verification Gates

Before implementation, record the exact Guacamole release artifacts and verified hashes/signatures, container or process isolation, WebView origin/CSP, private session-token transport, credential prompt behavior, and log configuration. Offline tests must exercise the complete phase state machine, input races at the lock barrier, stale/cross-run capabilities, event-size/rate bounds, disabled clipboard/device channels, no recording, credential/log/storage scans, MCP action receipt provenance, and cleanup/orphan recovery. Live acceptance follows TEST-135 and requires the separate authorized exact-UUID trial.

Clone this wiki locally