docs(worktrees): the local suite is slow, not hung; and uv venv picks cp314t (#813)

* docs(worktrees): the local suite is slow, not hung; uv venv picks cp314t

Two findings that had been reported as one cause. Measured 2026-09-03.

NO TEST HANGS. A sweep that exited 0 with a subprocess.communicate traceback
and no summary line was the CALLER giving up, not pytest. All three
communicate(timeout=) sites in tests/ catch it and call pytest.fail, so an
escaped one cannot come from a test. Local collection is 15597 items, and the
serial rate measured 269 tests in 250s on a box at 100 percent CPU.

Not the 042ef7f xdist controller hang. That one needs -n, shows a node down
line at 98-99 percent progress, and dies red at the step cap.

THE INSTALL FAILURE IS THE INTERPRETER, not watchfiles. uv venv --python 3.14
resolves to cpython-3.14.6+freethreaded (cp314t), which has no watchfiles
wheel; the same command on standard cp314 installs one. new.ps1 runs
python -m venv, which is why the documented path works.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(worktrees): record the completed run that settles the hang question

The first commit argued from the absence of a mechanism. This one adds the
positive evidence: CI's engine-leg selection under -n 8 finished here in
717.92s, "1 failed, 11480 passed, 833 skipped". It passed cleanly through the
96-to-99 percent window where the 042ef7f xdist hang starts, with no node
down line.

Durations settle hang-versus-slow: slowest setup 48.96s, slowest call 21.70s,
against --timeout=120. Slow tests exist; a test near the cap does not.

The one failure was contention, not a regression. test_accepts_seam.py gives
its sandbox child a 15-second wall budget and the box was saturated; the file
re-ran alone to "25 passed in 31.61s".

Also records the exit-code trap, which reproduced by accident: the run ended
with an echo, so the notification announced exit 0 over a red suite. The serial
projection drops to a shape rather than a measurement; its arm ran -v
unbuffered and is a lower bound on throughput.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: wshallwshall <mefordev@messagefoundry.org>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: 3 people

docs/WORKTREES.md

@@ -1060,3 +1060,90 @@ A fresh worktree has no `.venv` (it's git-ignored, exists only in the checkout i
 checkout's code no matter which worktree you run from — silently testing the wrong code. A
 per-worktree venv keeps each session honest. The cost is disk + ~a minute of install (pip's cache
 makes repeats fast).
+
+### Build it with `python -m venv`, because `uv venv` picks the free-threaded interpreter
+
+`scripts/worktree/new.ps1` runs `python -m venv`, which takes the PATH interpreter. Measured
+2026-09-03 on the shared Windows box, that is standard CPython 3.14.6, ABI tag `cp314`. `uv venv
+--python 3.14` resolves instead to `cpython-3.14.6+freethreaded`, ABI tag `cp314t`. Several pinned
+wheels do not exist for that tag.
+
+Same command, two interpreters, nothing else changed:
+
+| Interpreter | `uv pip install --only-binary :all: --no-cache watchfiles==1.2.0` |
+|---|---|
+| `cp314t` free-threaded | `watchfiles==1.2.0 has no usable wheels` |
+| `cp314` standard | `+ watchfiles==1.2.0` |
+
+Drop `--only-binary` and the free-threaded venv falls back to the sdist, which needs a Rust
+toolchain to build. That is the install failure sessions have been reporting.
+
+**The cause is the interpreter, not the package.** `watchfiles` does ship a cp314 wheel: the
+documented install ran here to exit 0 and used `watchfiles-1.2.0-cp314-cp314-win_amd64.whl`. Two
+sessions reporting opposite results were each right about their own interpreter, which is why the
+question stayed open. Check `.venv/Scripts/python.exe -VV` for the words `free-threading build`
+before you blame a dependency.
+
+## The full suite takes hours here, and a wrapper timeout reads as exit 0
+
+Measured 2026-09-03, fresh worktree, documented install.
+
+Local collection is **15597 items**. That is `tests` plus `packaging/messagefoundry-webconsole/tests`
+with the tooling tier included, and CI never runs that set in one call: `ci.yml` splits it into an
+engine leg and a separate web console job. Its measured leg times, their pool and their provenance
+are recorded above the `Tests (pytest)` step in
+[`.github/workflows/ci.yml`](../.github/workflows/ci.yml). Read them there.
+
+**Use workers, and run it in the background.** CI's engine-leg selection, under `-n 8` on this box,
+finished in twelve minutes:
+
+```
+1 failed, 11480 passed, 833 skipped, 55 warnings in 717.92s (0:11:57)
+```
+
+Serially it is hours. The rate measured 269 tests in 250 seconds over the first few hundred, which
+is a rough figure and a lower bound on throughput: that arm ran `-v` with unbuffered per-line
+writes, and the same box completed 12313 tests in twelve minutes once it had eight workers. Take
+"hours serially, minutes parallel" as the shape and do not quote the projection as a measurement.
+
+Contention is part of every number here. The box sat at 100 percent CPU with 2.2 GB of 31.7 GB free,
+all from other sessions. That one failure is the cost: `test_accepts_seam.py` gives its sandbox
+child a 15-second wall budget, which a saturated box misses, and the file re-ran alone to `25 passed
+in 31.61s`. **A red under contention is worth re-running alone before you believe it.**
+
+### Nothing is close to hanging, and the durations say so
+
+The slowest item in that run was 48.96s of setup, and the slowest call 21.70s, against a `--timeout`
+of 120. Slow tests exist. A test near the per-item cap does not.
+
+### A run with no summary line establishes nothing
+
+A foreground tool call cannot hold the suite. The Claude Code Bash tool caps a foreground `timeout`
+at ten minutes.
+
+When a caller's `subprocess.communicate(timeout=...)` gives up it raises `TimeoutExpired` in the
+**calling** process. The captured output is then that traceback, with no `N passed` or `N failed`
+line, and the caller can still exit 0. Read that shape as the wrapper giving up. It is not pytest
+hanging, and the exit code is answering a different question than the one you asked.
+
+Pytest itself never raises `TimeoutExpired`, and no test here lets one escape. All three
+`communicate(timeout=...)` sites in `tests/` catch it and call `pytest.fail`, so a test that tripped
+one would show as a named failure inside a normal summary. The wrapper that produced the reported
+traceback was not identified, so treat the ten-minute cap as the fitting mechanism rather than a
+measured one.
+
+**The reporting layer really does lose the exit code, and that reproduced here by accident.** The
+run quoted above ended `... && echo "ENGINE_RC=$?"`. Pytest returned 1 for its one failure, the
+`echo` returned 0, and the background task notification therefore announced `exit code 0` over a red
+suite. A trailing command replaces the exit status you were asking about. Read the summary line, not
+the status.
+
+### This is not the xdist controller hang, and merging the two would lose both
+
+`042ef7ff5` (PR #737) diagnosed a real hang. Under `-n`, a dead worker's replacement never reports
+ready, so the controller polls a silent queue until the step cap. Its signature is a `[gwN] node
+down: Not properly terminated` line at 98-99 percent progress, and the job dies red at
+`timeout-minutes`.
+
+A local run carrying no summary line, no `node down` line and exit 0 shares none of that. It also
+cannot share the mechanism, which needs `-n` to exist at all.