# 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.