Bootstraps: declared, bounded version probes instead of --version on every bin entry - #251

Why

Both adoption bootstraps ended with "$installed_executable" --version on every file in $ECO_INSTALL_ROOT/bin. That call inherited the terminal's stdin, had no time bound, and never compared the output to the pin. Three binaries hang it:

• MCP Inspector 2.x: has no version flag. Its launcher (byte-identical in 2.7.0 and 2.8.0) defaults to web mode and forwards argv, so mcp-inspector --version serves the web UI with --version as an ad-hoc stdio server. The user saw spawn --version ENOENT in the UI.
• context-mode: starts its MCP stdio server on any argument other than its named subcommands and --help.
• socraticode: has no argument parsing at all, so any invocation starts its MCP stdio server.

With an interactive stdin, the report therefore blocked. I reproduced all three hangs under a bounded timeout.

What

• Declared probes: every pin in adoption/pins-*.json declares a version_probe, following the per-package practice of nixpkgs versionCheckHook and Homebrew test do.
  • exec probes run the pin's own command, with optional expect and match: minimum. Claude Code's pin is a floor.
  • npm-metadata probes read context-mode and socraticode through npm ls, so the package never runs.
  • Every exec probe was observed on the WSL host, including orx, tvly and agent-browser from their pinned artifacts.
• Shared report step: byte-identical in both scripts and bash 3.2 safe.
  • Stdin comes from /dev/null and fd 9 is closed.
  • Each probe runs in its own process group, with TERM at 30 s and KILL 2 s later. Leftovers are killed after the probe exits.
  • Every bin/ entry is listed with its link target but never run.
  • installed-versions.txt is written, and the script exits 5 if a probe fails. cleanup() stops an interrupted probe and frees the lock.
• Docs: adoption/bootstrap.md step 2, both platform pages (with changed after v2026.09.24.1 notes and a </dev/null workaround for released versions), the Inspector recipe row (read its version with npm ls) and both --help texts. render_config.py --verify closes stdin too.

How verified

• Tests: adoption suites 340 pass (1 skipped), with a real bash 3.2.57 (BASH32_BINARY) and shellcheck 0.11.0 at style severity. New tests/test_adoption_version_probes.py covers:
  • a server that forks a child;
  • an EOF reader (the context-mode shape);
  • wrong, longer and prefixed versions, and escaping;
  • floor edge cases;
  • a stale npm version or missing prefix;
  • a live bin/ symlink that must not run;
  • lock-fd inheritance;
  • Ctrl-C releasing the lock;
  • no leftover processes in the run's session.
• Mutations: all 15 regressions tried were caught, among them inherited stdin, no process group, no bound, a substring match, running the listing, a missing cleanup kill, and a TERM-stopped watchdog.
• Real run: bootstrap-linux.sh --profile semantic-rag into a disposable root, with the host's mcp-inspector, context-mode and socraticode seeded into bin/ and stdin held open. It exited 0, verified 3 of 3 pins, ran none of the seeded executables, and left no listener.
• Review: two rounds of independent adversarial review. All 19 findings that survived refutation are fixed.

Coordination

This touches the same files as #159 and #177, the Claude Code floor. The minimum match already treats claude-code as a floor. Whichever lands later merges main and re-registers hashes.

Lane: lane:foundation

🤖 Generated with Claude Code