ops-warden/docs/development/safe-unit-tests.md

Safe unit-test entry point

Use make test, or .venv/bin/python -I scripts/run_unit_tests.py. Dependencies must already be installed; this path does not run uv, synchronize or download. UNIT_PYTHON may select another existing interpreter. PHASE_MEMORY_REPO remains an explicit local source option. Pass pytest options with TEST_ARGS, for example make test TEST_ARGS='-q tests/test_safe_unit_runner.py'.

The launcher creates an empty temporary HOME and temporary fixture root and starts an isolated (-I) Python interpreter with a constructed environment. Caller token, proxy, Python, pytest, XDG and Warden configuration variables are never copied or inventoried. Third-party pytest plugin autoload is disabled. Tests can explicitly introduce synthetic variables with monkeypatch, but allowed children always get the original temporary HOME and a fresh environment, never those variables.

Before pytest import/collection, a Python audit hook and subprocess wrapper:

• deny file opens outside the selected source roots, installed interpreter/library roots and fixture root; writes through open are limited to the fixture root;
• deny sockets, DNS and process creation except the closed fixture inventory;
• refuse shell, executable, preexec and inherited-FD overrides outside that inventory;
• install the same file/socket/process denial before executing every allowed Python child, including BrowserInputs' exact validator code and reverified copied module hashes. Validator children cannot start further processes.

The process inventory in scripts/run_unit_tests.py is intentionally small: BrowserInputs validation, four metadata-checker scripts with fixed argument shapes, the exact original-intent restart probe, the synthetic containment print, and closed guard-regression probes. Metadata checkers receive only fixture output paths. Only the generated-artifact checker child can run the exact read-only Git log/status queries for this repository's catalog, with global/system config and optional locks disabled, hooks disabled and fsmonitor disabled. Those local Git commands are not provider operations.

Two reviewed non-Python cases remain: exact-byte, temporary contract-double scripts with a closed argv list, and five exact fixed printf commands used by existing transport tests. They run Bash without profile/rc startup and without inherited environment; no arbitrary shell text, provider binary, SSH, kubectl or OpenBao command is permitted. Default unit selection excludes four integration-marked SSH-keygen tests. Selecting them explicitly does not grant their native commands.

Only test_desk.py::test_approve_flow_http_dry receives a network lease. It may bind 127.0.0.1:0 and connect to the endpoint actually allocated to that test's socket. DNS is replaced by numeric fixture resolution. Another loopback service (e.g. the real Hub on port 8000), Unix sockets and remote endpoints stay denied. The lease and registered endpoints are cleared after the test.

Coverage tests now use the explicit public declaration projection snapshot in tests/fixtures/workload-coverage, with provenance hashes. They compare the published source snapshot rather than silently consulting the workstation HOME. Run the existing coverage report separately with an explicit estate root when measuring current estate state. Tests of the acknowledged NetKingdom source use --netkingdom-root (default: sibling source checkout), never a HOME symlink. The optional Phase Memory library's one existing public coordination-profile fixture is explicitly readable alongside its source; no runtime memory store is inherited.

This is an accident guard for trusted unit tests, not a security sandbox for hostile Python, native extensions or hostile installed dependencies. It does not revoke already-open descriptors, prevent every filesystem mutation syscall, or provide OS process/network isolation. Fixed Bash/Git fixture processes rely on the reviewed executable and source/argument shapes; Python audit hooks do not run inside those binaries. Do not run untrusted test code under a privileged runtime. Direct pytest bypasses this launcher and is not equivalent validation. No production Warden boundary, grant, catalog, source pin or owner credential changes.