[cdeust]

Summary

Fixes #747: tests_py/hooks/test_entry.py::test_entry_matches_launcher_on_benign_event hung in communicate() on the launcher subprocess (test_entry.py:98) until the 300 s pytest timeout, which aborted the full suite at about 61 %.

Root cause (reproduced, not inferred)

At the issue's base 02c3cf00, scripts/launcher.py ran launcher_deps.ensure_all_deps(deps_dir) whenever the module was mcp_server.hooks.session_start. That is a synchronous uv pip install of the ML set (torch, sentence-transformers, flashrank, about 1 GB) inside the hook process. It ignored CORTEX_EMBEDDING_ZERO_DOWNLOAD, which the test's hermetic env sets. When the deps directory's ML stamp did not name the current uv.lock (the main checkout's deps/.cortex-deps-stamp-ml.json is still in the pre-ADR-1104 format: {"python", "pins"}, no lock/set key), the SessionStart launch reinstalled the whole set before it ran the hook, and the test waited on that.

It was not stdin, a lock or a detached grandchild holding the pipe. Every Popen spawn site under mcp_server/hooks and scripts/launcher_ml.py passes stdin=DEVNULL and sends stdout and stderr to a log or DEVNULL. Line 90 (mcp_server.hooks.entry) installs no dependencies (module docstring), so the launcher subprocess at line 98 was the only one that could block.

I reproduced it by running scripts/launcher.py mcp_server.hooks.session_start under the test's own hermetic_hook_env, with an empty CLAUDE_PLUGIN_DATA and a uv shim first on PATH. The shim passes --version/export through to the real uv 0.11.3, records every pip install along with the ML packages its requirement file names, and refuses the install:

=== BEFORE: scripts/launcher.py at 02c3cf00 (issue base)
CORTEX_EMBEDDING_ZERO_DOWNLOAD = 1
launcher exit 0
uv pip install: 45 packages; ML packages named: []
uv pip install: 70 packages; ML packages named: [flashrank sentence-transformers torch ]

=== AFTER: scripts/launcher.py at 66ce3a4e
CORTEX_EMBEDDING_ZERO_DOWNLOAD = 1
launcher exit 0
uv pip install: 45 packages; ML packages named: []

ADR-1104 (#749, 8a4112f2) already removed the in-band install: the ML set now goes to one detached launcher_ml job, and that job is gated by the zero-download opt-out. #749 did not close #747, and nothing pinned the fix. If someone put the in-band install back, no fast test would fail. Only test_entry.py would catch it, by hanging for 300 s again.

This change

tests_py/scripts/test_launcher_hook_deps.py runs the real launcher.main() in a child process for every hook that .claude-plugin/plugin.json wires. The module names are parsed from the manifest's hook commands, and every command must name one. The install seams (ensure_deps, ensure_all_deps, launcher_ml.start) and runpy.run_module are replaced by recorders. The test requires:

• every hook launch installs the base set and nothing else;
• the SessionStart launch hands the ML set to the background job (launcher_ml.start is called with the plugin-data deps dir).

The test has no timeout= and no sleep.

Evidence

The new test fails against the old behaviour. I put back the 02c3cf00 branch (if install_deps or module == "mcp_server.hooks.session_start": ensure_all_deps) in scripts/launcher.py:

E       AssertionError: assert ['base+ml'] == ['base']
FAILED tests_py/scripts/test_launcher_hook_deps.py::test_a_hook_launch_installs_only_the_base_set[mcp_server.hooks.session_start]
FAILED tests_py/scripts/test_launcher_hook_deps.py::test_session_start_hands_the_ml_set_to_the_background_job
2 failed, 11 passed in 7.11s

With the launcher unchanged: 13 passed.

Checks on the final head 66ce3a4e (rebased on 7e4864d2):

• pytest tests_py/hooks/test_entry.py: 19 passed in 14.80s, exit 0
• pytest tests_py/hooks/: 882 passed, 2 skipped, 13 subtests passed in 133.52s, exit 0
• uvx ruff@0.16.6 check / format --check, and ruff@0.16.10 (the CI lint pin): all passed, 3649 files already formatted
• python scripts/check_craftsmanship.py (with and without --base origin/main): Craftsmanship gate: OK
• python scripts/check_no_deps_invariant.py: clean

I did not run the full suite locally (resources). CI runs it.

Not in this PR (adjacent)

• test_entry.py still runs the launcher against CLAUDE_PLUGIN_ROOT/deps (the checkout's deps/), because CLAUDE_PLUGIN_DATA is unset. On a fresh checkout, or after a uv.lock change, the first launcher call does a networked uv pip install of the base set (45 packages) inside the test. That is bounded and no longer a hang, but the test depends on the network and writes into the checkout.
• The main checkout's deps/.cortex-deps-stamp-ml.json is still in the pre-ADR-1104 format. This is harmless now (set_ready("ml") is False, so the background job is the one that reinstalls).

🤖 Generated with Claude Code

https://claude.ai/code/session_01VH9JM8qvKiJysP16BmAxAU

[cdeust]

ZETETIC-REVIEW: APPROVE
head: 66ce3a4

Le test lance le vrai launcher.main() dans un processus enfant. La liste des hooks vient de plugin.json. Pas de timeout ni de sleep comme verdict. Il échoue si l'install ML revient dans un hook. Le correctif cité, #749 (8a4112f), est bien ancêtre de main. 13 passed en local. Merge après CI verte.