Linux/WSL2 bootstrap keeps a newer native Claude Code: the pin is a floor (stacked on #159)

[seathatflowsinourveins]

Stacked on #159

This branch is #159 merged onto current main (merge commit 939bff6), plus one commit of its own: 9e47304. Review only 9e47304. In the merge, the only textual conflict was two manifests/evidence.json hashes, for adoption/bootstrap.md and adoption/platforms/macos-arm64.md; both files auto-merged and were re-hashed.

Merge #159 first. This branch then rebases onto main as that one commit. Squash-merging this PR on its own would also land all of #159.

#159 also has a semantic conflict with main. #171 moved new machines to v2026.09.24.1, so test_pages_mentioning_a_changed_install_input_say_so now requires "changed after v2026.09.24.1". Merged onto current main, #159 fails that test with 6 errors, because its notes in adoption/bootstrap.md step 2 and adoption/platforms/macos-arm64.md name v2026.09.23.1. 9e47304 changes those notes to name v2026.09.24.1. The install inputs are byte-identical at both tags, so the notes stay true. #159 needs the same change when it merges main.

Why

adoption/bootstrap-linux.sh's install_native always ran "$bin" install <pin>. On a Linux/WSL2 host whose native updater (latest channel) is ahead of the pin, every bootstrap re-run moved Claude Code back to the pin and dropped the newer release's fixes. #159 fixed this downgrade on macOS only; its notes list "Linux can still downgrade" as out of scope.

What

1. Linux install_native is now byte-identical to macOS's. It carries Adoption hygiene: native Claude Code pin is a floor (2.1.281), ai-memory assistant capture opt-in, ignore Claude Code local state #159's floor:
   • If ~/.local/bin/<bin> --version starts with a dotted numeric version at or above the pin, that launcher is kept. Versions are compared field by field as base-10 numbers, so 2.1.99 is older than 2.1.281.
   • A kept launcher means nothing is downloaded or installed. The script logs Kept installed claude-code <v>, and install_pin skips its Installed line.
   • A missing, older, non-numeric or failing launcher gets the unchanged install: fetch checks the SHA-256 before the binary runs.
   • A new test fails if the two scripts' copies of the function ever differ.
2. adoption/pins-linux-x86_64.json: the claude-code install_note now describes the floor. It used to say the Linux script still reinstalls the pin every time.
3. adoption/bootstrap.md step 2:
   • The stale sentence "Linux/WSL2's script and pins are the same at v2026.09.23 as on main" now says what actually differs at that tag, checked with git show v2026.09.23:…: the script installs the npm claude-code 2.1.278 pin and has no --configure-claude-user-profile step, and the pin file has no markitdown, tavily-cli, orx or agent-browser pin.
   • The claude-code note now names v2026.09.24.1 and covers both scripts.
4. Platform pages: adoption/platforms/linux-wsl2.md step 1 gains the Linux "changed after v2026.09.24.1" note. The floor paragraph in adoption/platforms/macos-arm64.md now names v2026.09.24.1 and says Linux runs the same install_native.
5. Evidence: manifests/evidence.json is re-hashed for every changed file with host_receipts.register_file, each path passed as a separate argument. manifests/evidence.json itself is left off that list. It has no entry for itself, and registering it would add an entry hashing its own pre-write bytes.

Change from the request: the task asked for a "changed after v2026.09.23.1" note. Since #171, the docs test requires the pinned tag, v2026.09.24.1, so the notes name that tag.

How verified (locally on macOS arm64, where /bin/bash is 3.2)

• Validators: scripts/validate.py, scripts/validate_convergence.py --all-recorded --root . (18 records valid) and scripts/host_receipts.py validate all exit 0.
• Other CI gates, run locally: release_due.py --strict-if-repinned origin/main, new_host_grand_list.py --check, component_matrix.py --check, build_ecosystem.py --check, validate_catalogs.py, validate_foundation.py and landscape.py all exit 0.
• Linters: shellcheck -S style (0.11.0) on both bootstrap scripts and bash -n are clean.
• Adoption test modules (all 7 test_adoption_* modules plus test_render_config): 341 tests, 35 skipped. There is 1 failure and 6 errors, none caused by this PR:
  • LlamaWrapperQuotingTests fails the same way on an untouched origin/main tree. On a real Mac, System Integrity Protection strips DYLD_LIBRARY_PATH; Adoption hygiene: native Claude Code pin is a floor (2.1.281), ai-memory assistant capture opt-in, ignore Claude Code local state #159 recorded the same failure.
  • The 6 EmbedAcceptanceScriptTests errors come from the local session sandbox blocking a bind to 127.0.0.1 (PermissionError: [Errno 1] Operation not permitted). Outside the sandbox, the class passes 8 of 8.
• New NativeInstallFloorTests in tests/test_adoption_bootstrap.py: 6 tests, covering 5 kept launchers and 7 cases that must install.
  • fetch, install_native and install_pin are extracted unchanged from bootstrap-linux.sh and run against a one-pin fixture. Only curl is shimmed.
  • Where the host's sha256sum lacks GNU's --check --status (macOS), a sha256sum shim runs shasum -a 256 with fetch's own arguments, so the checksum is still really compared.
  • Also covered: a checksum mismatch still fails closed, and a kept launcher whose bin_dir is ~/.local/bin is not replaced by the exec wrapper.
• Mutation checks:
  • Against origin/main's bootstrap-linux.sh, 7 checks fail: the 5 kept versions, the kept launcher in ~/.local/bin, and the shared-function check. The install-path tests pass on both versions, because that path is unchanged.
  • Deleting install_pin's early return for a kept launcher makes 6 checks fail.
• Full python3 -m unittest, run locally inside the session sandbox: 3946 tests, 510 skipped, 1 failure and 36 errors. None come from this PR:
  • The 1 failure is the same LlamaWrapperQuotingTests failure described above.
  • 34 errors are PermissionError: [Errno 1] Operation not permitted from the sandbox: loopback binds, ps and paths. They are in test_offhost_app_state, test_order_throughput, test_research_workflow, test_adaptive_paper_metrics, test_native_maintenance (the application-delivery portability tests) and EmbedAcceptanceScriptTests. Outside the sandbox, those modules pass 158 of 158.
  • 2 are setUpClass errors in test_catalog_freshness_propose. The test commits a generated docs/ecosystem/index.html in a scratch repository, and this machine's global git pre-commit hook (gitleaks) refuses that commit. The same 2 errors occur on a clean origin/main tree (76 tests).

CI

• 19 checks pass; 3 main-only jobs are skipped.
• validate ran the full suite on Linux (3950 tests), where GNU sha256sum is used and no shim is needed. validate-macos gates on the adoption test modules (284 tests) and on the full suite on macos-15 (exit 0).
• bootstrap-linux ran on a fresh ubuntu-24.04 runner with no ~/.local/bin/claude. It logged Installed claude-code 2.1.281 (native), and claude --version printed 2.1.281 (Claude Code). So the checksum-verified install still runs when no launcher exists (run 36007047862). bootstrap-macos and bootstrap-macos-brew show the same. A fresh runner never has a launcher to keep, so CI cannot exercise the kept path; the new tests cover it.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.