[roodboi]

Root cause

• HACK-1290: package.json pins packageManager: bun@1.4.2, and mise.toml, .tool-versions, every workflow and the runtime images use 1.4.2. Nothing checked the Bun that actually ran local gates, though. A Bun ahead of mise's shims on PATH (here mise's latest 1.4.3) skips the checkout's mise.toml. A Bun 1.4.2 macOS SIGSTOP difference made a test pass locally on 1.4.3 and then fail in CI.
• HACK-1294: the compiled-bundle CLI checks (scripts/check-config-compiler-cli.ts, scripts/check-native-{env,host,routing,endpoint,process,acquisition}-plan-cli.ts, scripts/check-native-config-import-cli.ts) ran only inside CI's macOS "Config compiler" job. No local command ran them, so a behavior change passed every local gate and failed CI.

Fix

• New scripts/check-bun-version.ts (bun run check:bun-version). It compares Bun.version with the exact packageManager pin. On a mismatch it exits 1 with the fix: mise x bun@<pin> -- bun run <script>. Setting HACK_ALLOW_BUN_VERSION_MISMATCH=1 (exactly 1) continues with a warning for a deliberate experiment.
• The guard runs first in root test, check and typecheck and in packages/cli test, check and typecheck. turbo.json passes the override through via globalPassThroughEnv, so package tasks honor it. CI already installs 1.4.2, and the .hack toolchain image installs from mise.toml, so both pass unchanged.
• New bun run check:native-plan-cli (scripts/check-native-plan-clis.ts). It runs the eight compiled-bundle checks one at a time, in CI order, and stops at the first failure. It refuses to start without dist/hack and dist/hack-config-compiler, and tells you how to build them.
• AGENTS.md and .ai/skills/hack-repo-verify/SKILL.md document the guard, the override and the new command. These are contributor-only files. Consumer guidance (src/agents/instruction-source.ts) did not change, so no plugin regeneration or render fingerprint is needed.

Tests

• tests/bun-version-guard.test.ts covers four things. First, the match, mismatch and override verdicts (only "1" overrides) and the rejection of inexact pins. Second, the real script exits 1 on a mismatch and 0 with the override, run in a temp copy with an isolated HOME. Third, mise.toml, .tool-versions and every literal workflow bun-version agree with packageManager. Fourth, every entry point starts with the guard, and turbo passes the override through.
• tests/native-plan-cli-wiring.test.ts fails when any scripts/check-native-*-plan-cli.ts, the config-import check or the config-compiler check is missing from the local command or from a CI step. It also checks that the runner refuses to start without the built bundle.
• Mutation-proven: each of these 8 mutations made at least one test fail, and the restored code passes 8/8.
  • Always match.
  • Treat any truthy override as 1.
  • Drop the exit code on a mismatch.
  • Remove one check from the list.
  • Remove the guard from root test.
  • Remove the guard from CLI typecheck.
  • Remove the turbo pass-through.
  • Ignore missing prerequisites.

Evidence (macOS arm64, local)

• Plain bun is 1.4.3:
  • bun run check:bun-version exits 1 with the message.
  • bun run test stops before turbo.
  • HACK_ALLOW_BUN_VERSION_MISMATCH=1 bun run typecheck --force warns at the root and inside @hack/cli:typecheck, which proves the pass-through, and both tasks succeed.
• mise x bun@1.4.2 -- bun run check:bun-version exits 0.
• bun run build, bun run build:config-compiler (rustc 1.97.1), then mise x bun@1.4.2 -- bun run check:native-plan-cli all pass. All eight checks pass, including acquisition (198 checks) and config import (49 checks).
• Bun 1.4.2 gates:
  • bun run --cwd packages/cli typecheck: 0 errors.
  • bun run --cwd packages/cli check: 0 errors (existing warnings only).
  • bun run check: passes.
  • bunx ultracite check on the changed files: clean.
  • bun run test (full suite, Bun 1.4.2, host load average 50 to 130 from parallel agents, 2h07m): the guard passed and turbo ran. 6785 tests passed and 1197 failed across 120 files. All 5 new tests passed in the suite.
  • I reran each of the 120 failing files serially with --timeout 60000. 99 files passed. 21 files still fail, all native-compose-* / native-authored-* source-CLI fixtures. Most fail with the fixture's inner 15 s SIGKILL (exit 137) or private-uncertain refusals.
  • Baseline A/B with origin/next's package.json, packages/cli/package.json and turbo.json restored on the same host gave identical results. native-compose-warm-up-command: same exit 137. native-compose-down-command plus native-compose-storage-fence-cost: 1 pass / 17 fail in both runs.
  • Direct bun test does not run any code this PR changes, so I count these failures as host and environment failures, not as caused by this change. I did not get a fully green local suite on this host.
• gitleaks 8.30.1 over origin/next..HEAD: no leaks.

Remaining gaps

• Raw bun test <paths> and bun index.ts do not run the guard. Only the bun run entry points do; this is documented.
• check:native-plan-cli covers the CLI checks only. CI's "Config compiler" job also lints those scripts, runs their transport tests, runs build:release and validates the schema corpus in Python. The docs say to lint changed scripts explicitly.
• This head (d9d6376d) is based on ec223cdb, the commit I ran the full suite against. next has since gained four unrelated commits (feat(agents): read-only reviewed task catalog #353, fix(env): keep stored ciphertext when a secret value is unchanged #340, feat(runtime-core): admit stopped clean development owners within reserve #344, fix(native): keep storage carrier commands alive through host stalls #356). None of them touches these files, and the head merges cleanly (git merge-tree). The focused tests also pass after rebasing onto 2f434217.
• Hosted CI on this head has not been observed yet.
• Found while testing, not fixed here: tests/setup-migrate-command.test.ts resets root = "" in afterEach. A CLI call that outlives its timed-out test then passes root: "" to privateCliEnv. That resolves to the checkout, so isolatedDockerClientEnv writes docker-client/config.json into the repository root. I saw this during the loaded full run. privateCliEnv should refuse an empty or relative root.

Refs HACK-1290
Refs HACK-1294

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[linear-code]

HACK-1290

HACK-1294