[verified] Bind managed-lock test imports to HARNESS_ROOT

2026-10-14 14:17:46 +00:00
parent f5ef03418e
commit c06a2da159
2 changed files with 95 additions and 1 deletions
@@ -1,5 +1,45 @@
 # Canonical harness tests

+## Installation-root prerequisite
+
+Before executing the suite, provide `HARNESS_ROOT` in the process environment.
+It names the installation root containing `harness/` and `repositories/`, not
+the `harness/` directory itself. For the current installation, configure the
+current agent's `$HERMES_HOME/.env` with:
+
+```dotenv
+HARNESS_ROOT=/opt/data/gitea-agent
+```
+
+The tests consume the environment supplied by Hermes; they do not open or
+source `.env` files, search other profiles, or implement a second configuration
+loader. When running outside Hermes, supply the variable explicitly:
+
+```sh
+export HARNESS_ROOT=/opt/data/gitea-agent
+python3 -B "$HARNESS_ROOT/harness/tests/run.py"
+```
+
+On another system, replace the value with that installation's absolute root.
+The managed-lock subprocess contention test requires a nonempty, existing
+absolute directory and compares its resolved location with the installation
+containing the test file. Missing, empty, relative, nonexistent, non-directory,
+or different-installation values raise an explicit `HARNESS_ROOT` error before
+creating a lock or starting the contention subprocess. There is no fallback to
+`Path.cwd()` or to the test-file-derived root. Only the validated import root
+is passed as a subprocess argument; no `.env` contents are read or serialized.
+This test-only prerequisite does not change the production lock implementation
+or the canonical runner's source-bound collection behavior; `--collect-only`
+does not require the variable.
+
+An external-cwd regression runs only the contention test from a temporary
+working directory, with `PYTHONPATH` removed and an explicit fixture
+`HARNESS_ROOT`, using isolated Python and bounded subprocess timeouts. Invalid
+configuration coverage checks that neither lock acquisition nor subprocess
+execution occurs. It does not recursively invoke the entire suite.
+
+## Running the canonical suite
+
 The canonical runner is anchored to its own source tree and works from any
 current directory. From the repository root: