archy/tests/apps/terminal-handler/README.md

Actual terminal-handler transport qualification

Objective: real CLIPopup/xterm → actual authenticated HTTP/WebSocket handler → private tmux, with typed command output, retained history, same-session reconnect and visible desktop/mobile history. This replaces neither installed login/tool qualification nor device, independent review or whole-D09 acceptance.

terminal_transport_tests::actual_handler_private_tmux_history_and_reconnect is an ignored backend test. It bootstraps a synthetic owner/session, uses a fresh state/workspace/tmux directory and serves only fixture assets outside the actual API handler. All terminal HTTP and WebSocket requests take production routes. It checks anonymous/foreign-origin refusal, real session creation/input/resize, history beyond visible rows, reconnect, real Chromium at1440/390 and refusal to silently recreate a killed session. The browser's WebSocket wrapper only records real socket objects; it does not manufacture responses. Reconnect must reach OPEN and execute/render a fresh command, not merely preserve an old buffer. Typed commands cannot contain their own expected expanded output markers. The native test runs the driver from the existing readonly, artifact-verified /workspace source export; a historical image-baked driver copy is not executed. Thus a driver-only correction can reuse identical prepared packages/UI assets without another package acquisition or asset build (new source binding still required).

Separate admitted phases

1. Source/controller checks: Rust formatting/parser, Node/Bash syntax and python3 tests/apps/test-terminal-handler-runner.py. These six fake-engine contracts execute neither Cargo, backend tests nor real containers. They cover missing artifacts, mixed modes/extra filters, changed source, zero-test false greens, cleanup failure, fixed resource/namespace dispatch and owned cleanup. They are not transport qualification.
2. Fixture preparation: invoke build-terminal-handler-runtime.sh from an inspected committed checkout with an empty output directory, immutable local browser image and matching locked frontend directory. A separately admitted user unit must impose1GiB/no swap/1CPU/TasksMax256, a420-second total deadline and bounded stop/cleanup. The script rejects an unbounded parent. Its UI-only child has1GiB/1CPU/256pids/90seconds/network-none. Its separate public-package child has1GiB/1CPU/128pids/180seconds, private networking with host-loopback mapping disabled, and no host mounts. Only public signed Debian package acquisition is networked. It installs tmux into its own disposable root, retains package versions/tool hashes, copies exact fixture assets/driver and commits a local immutable test image with a fail-closed default entrypoint. The control-plane image commit is limited to60seconds inside the bounded parent. Both owned containers must disappear and inventory must match. The resulting image/inputs/receipts are retained, not published or deployed.
3. Changed-test compilation: archive the exact candidate into a separate source export (no .git, dirty uploads or live tree transfer). Use the existing scripts/test-backend-isolated.sh compile-only path with ARCHY_TEST_CLOUD_COMPILE_ONLY=1, the exact compiler and new fixture-runtime image, public registry cache and fresh artifact export. Leave ARCHY_TEST_TERMINAL_FIXTURE unset. This uses the existing8GiB/offline/locked compile harness, not Cloud execution. Source/compiler/runtime/binary bindings are retained. New tests cannot be claimed on an older binary.
4. Cached transport runtime: after separate manager/resource admission, run scripts/test-backend-isolated.sh with ARCHY_TEST_TERMINAL_FIXTURE=1, ARCHY_TEST_ISOLATOR=podman, exact ARCHY_TEST_REPO, ARCHY_TEST_IMAGE, ARCHY_TEST_TERMINAL_RUNTIME_IMAGE, ARCHY_TEST_REUSE_ARTIFACT and an existing empty ARCHY_TEST_EVIDENCE_DIR. No extra test arguments or compilation/export flags are accepted. The runner has no Cargo fallback. Runtime is network-none/private PID/private IPC/read-only/cap-drop-all/no-new-privileges, 3GiB/no swap/2CPU/256pids/120seconds; attach is bounded to140seconds. Use a separately bounded parent and cleanup deadline. Only exact readonly source, verified binary, empty resolver and screenshot output are mounted. Root, service state, runtime sockets and temporary data are private empty tmpfs. Host network/PID/IPC namespaces and the host-only canary must be inaccessible. The test must be listed exactly once and its result must report exactly one pass, not a successful empty filter.
5. Evaluate receipts: retain test exit separately from cleanup/inventory failure, inspect actual1440/390 screenshots, bind all assets/artifacts and preserve failures. No retry, extension, foreign cleanup or installed-node credit is implicit. A subsequent change needs its own source/artifact binding and admission, not replay of an earlier resource clearance.

Public package acquisition, changed-source compilation and runtime each require current capacity/ownership clearance; this README grants no reservation. Never run the ignored test directly on an installed host or reuse its synthetic owner bootstrap as a production route.