[roodboi]

Update at 9fe1186: this merges next at 1f5a905, bringing in #499, #557–#564, #566 and #568–#570.

The text merge was clean, but typecheck found one semantic conflict. #563 added a file-owner case that passes its own timeout, and this PR's two-argument test wrapper in tests/native-compose-file-owner.test.ts rejected the third argument. The wrapper now forwards a case timeout, and the file's 60 s budget stays the floor.

Checked on Bun 1.4.4, with the config compiler built with Rust 1.97.1:

• tsc passes, and Biome passes.
• The file-owner tests, the fixture git spawn scan, and the env, doctor and lifecycle files: 507 pass, 0 fail.

Update at 72661c0: merged next at 1df527b (#545, #419, #337). The e2e fixture conflict was two import additions; both are kept. This PR's git spawn scan then caught three spawns that arrived on next with their own git environment: tests/project-env-worktree-local.test.ts, tests/env-legacy-service-scope.test.ts (which keeps its private HOME and now commits with the shared fixture identity) and tests/e2e/scenarios/worktree-parallel-up.ts. All three now use fixtureGitEnv. Focused tests on Bun 1.4.4, with the scan and the env, doctor and lifecycle files: 478 pass, 0 fail. Typecheck, Biome and gitleaks pass. The e2e scenario change is covered only by hosted docker-e2e.

Current state (head ba522c9, 2 Nov)

Fixes the three findings of the independent review of a16f361. origin/next (8621d90) is merged in. The older notes below describe earlier heads.

• Scanner: each git spawn call is now checked inside its own parentheses, ignoring brackets in string text, with inline negative controls. It also recognizes run from src/lib/shell.ts and flags Bun shell templates that start with git. An argv held in a variable is a documented gap. The stricter scan found one real unrouted spawn from next, in tests/env-set-local-contract.test.ts, now routed.
• Native stop: the last ownership check before compose down is bounded by the smaller of the probe timeout and the time left, less a reserve for the child: a fifth of the budget above 1 s, at most 5 s. A slow engine is refused as probe-timeout before any child runs, and hack down --recover completes the stop.
• Budget: tests/fixture-hermeticity.test.ts has a 120 s case budget, because a case outlived the 5 s default on a loaded host. No assertion changed.

Verified locally with Bun 1.4.2 and a private HOME, HACK_HOME and DOCKER_CONFIG, HACK_DAEMON_AUTOSTART_DISABLE=1 and DOCKER_HOST at a missing socket, at load about 8-15:

• Three runs each, all passing: fixture-hermeticity, env-set-local-contract, checkout-write-guard, native-compose-stop-admission. One run each, passing: native-compose-storage-witness-command, native-compose-file-owner.
• 11 mutations of the new checks were each caught, then reverted.
• packages/cli typecheck, Biome on the changed files and gitleaks over a16f361..ba522c9 pass. Hosted CI on this head is not yet confirmed here.

Open: tests/native-compose-down-command.test.ts still fails under this load (HACK-1768). A paired run gave 9 failures with this change and 9 without. Owner decision from the review: with the timeout unset, a hung engine now takes up to 60 s, not 15 s, to refuse each ownership query in a native down.

Current state (head f3619d8, 2 Nov)

Rework after the failed verification of 0f51025. origin/next (ae032e7) is merged in.

• Ownership probe: an ownership query in native down kept a fixed 15 s bound and ignored HACK_COMPOSE_STARTUP_TIMEOUT_MS, and no option or env input could change it. It now follows that budget, at least 15 s and at most the probe's 60 s ceiling. Other operations keep 15 s. On an unset host, a hung engine now takes up to 60 s, not 15 s, to refuse a native down.
• Docs: docs/env.md now says a regular-file .hack/.internal gives E_CONFIG_INVALID for env set and env unset, which matches their real output. docs/cli.md describes the new bound.
• Budget: the dependent route finalizer cases have a named budget.

Verified locally with Bun 1.4.2, a private HOME, HACK_HOME and DOCKER_CONFIG, and no docker on PATH:

• tests/native-compose-storage-witness-command.test.ts passed 5 of 5 runs at load about 10 and 5 of 5 at load 33-98.
• A new slow-engine case reproduces the exact refusal (effect-ownership, probe-timeout) when the wiring is removed.
• packages/cli typecheck, Biome on the changed files and gitleaks pass.

Open: tests/native-compose-down-command.test.ts failed 10-11 of 14 cases at load 30-60 with this change. Many hit invoke's 15 s kill (exit 137), including up calls this change does not touch; the exit 1 failures were not diagnosed. Without the wiring it failed 11 of 14 at load 30-54 and 13 of 14 at load 62-162. At load 13-20 this head failed 4 of 14: two exit 137 and two down --recover exit 1. This file uses invoke's default 1 s budget, so the query bound stays at the old 15 s and the fix cannot change its results. The file has not been run at idle. Hosted CI at this head is still to be read.

Summary

Follow-ups from HACK-1459 (items 1-6 plus its comment) and the HACK-1460 flake. Test fixtures no longer read the caller's Git or Docker environment, load-sensitive cases get named budgets sized for their work, a timed-out case can no longer break the next one, and one env refusal gets a stable code.

Root causes

1. Hermeticity (HACK-1459 item 1 and comment). Fixture git calls in about 50 test files inherited the runner's environment.
   • An exported GIT_DIR/GIT_WORK_TREE sent the fixture's init/commit/worktree add into that repository. tests/native-env-metadata.test.ts cleared those variables in beforeEach, but its fixture runs in beforeAll, before that.
   • Under a private HOME, git still read the contributor's $XDG_CONFIG_HOME/git/config, whose core.hooksPath guard refused fixture commits. That is the actual cause of the local-only failure of native-compose-generation "real linked worktree ...". The fixture already set its identity with -c user.*; it fails on the hook, not the identity.
2. down --recover storage-witness cases fail locally. DOCKER_HOST did not cause this. The cases fail the same way with and without it, and with a private or a real HOME. invoke() defaults HACK_COMPOSE_STARTUP_TIMEOUT_MS to 1 s, and down --recover bounds its owned stop by that budget. On a loaded host (load average 60-150 here) the stop's synthetic Docker processes take longer than 1 s, so the CLI reports native_compose_effect_refusal {effect-execution, private-uncertain} instead of E_COMPOSE_FAILED. With a 60 s budget the same run gave E_COMPOSE_FAILED at load average 108. Two more wall-clock bounds expired under load: the in-process carrier deadline (Date.now() + 30_000, which gave "witness missing ... uncertain") and invoke's 15 s kill (exit 137).
3. native-env-metadata beforeAll (items 2-3). The template build (five git processes) had Bun's 5 s hook budget. Bun starts afterAll as soon as beforeAll times out, while the build keeps creating native-env-metadata-template-* directories. Probe: a 200 ms hook budget with a 300 ms body showed afterAll running while the body was still in progress.
4. HACK-1460 file-owner. The up cancellation case had an explicit 5 s budget. Other cases had 15 or 30 s. When a case times out, Bun runs afterEach while the body keeps running, and that body reads the module-level store/root, which the next beforeEach replaces. A late body can therefore act on the next case's store. That is how one timeout becomes "state unsafe" in the next case.
5. Items 4-6.
   • Item 4: since fix(storage): bound storage helper probes by the carrier's remaining budget #437, a hung helper start is bounded only by the carrier's remaining budget, so it reports storage-budget. That is the right reason, because the remedy is the budget variable that the summary names. The code, the probe-budget test and the reference already agreed; the doc and the test now state it explicitly.
   • Item 5: hack env hydrate with a .hack/.internal file is refused by the earlier legacy adoption-state check (ENOTDIR counts as an input access failure, never as absence), so it reports E_CONFIG_INVALID. docs/env.md said E_PATH_CONFLICT.
   • Item 6: EnvLayerLockRefusedError was an uncoded ClosedCliError, so the CLI printed it without an E_* prefix and --json reported E_UNEXPECTED.

Fix

• New tests/helpers/fixture-git.ts: fixtureGitEnv(), fixtureGitShellEnv() (for src/lib/shell.ts), runFixtureGit[Sync]().
  • It builds the environment from PATH/TMPDIR plus the caller's values.
  • It removes every GIT_* variable, DOCKER_HOST/DOCKER_CONTEXT and the runner's HOME/XDG_CONFIG_HOME.
  • It sets GIT_CONFIG_GLOBAL=/dev/null, GIT_CONFIG_NOSYSTEM=1, a fixed author and committer identity, and GIT_TERMINAL_PROMPT=0.
  • gitEnv lets a test set a Git variable on purpose (used for GIT_INDEX_FILE and GIT_CEILING_DIRECTORIES).
• Every fixture git spawn in tests/ goes through it (about 50 files). The e2e runCommand gets an exactEnv option. The checkout write guard drops a caller's repository variables but keeps the contributor's config.
• tests/fixture-hermeticity.test.ts:
  • Exports GIT_DIR, the work tree, the index, the object directory, the common dir, a hostile GIT_CONFIG_GLOBAL and a hostile identity, then runs every fixture route. The scratch repository stays byte-for-byte unchanged, and no hostile hook runs.
  • A fixture HOME's own .gitconfig cannot add hooks, signing or identity.
  • An ambient DOCKER_HOST/DOCKER_CONTEXT never reaches fixture git or the private CLI env.
  • A source scan refuses any new fixture git spawn that does not use the helper.
• native-compose-storage-witness-command: named RECOVERY_DEADLINE_MS (30 s), CLI_COMMAND_TIMEOUT_MS (45 s) and a 3 min case budget. The carrier deadline uses the product default. The source-unavailable recovery case also runs with an ambient DOCKER_HOST at a missing socket plus a DOCKER_CONTEXT.
• native-env-metadata: named TEMPLATE_BUDGET_MS (60 s) on both hooks. afterAll waits for the build to settle, and a build that outlives that wait removes its own directory.
• native-compose-file-owner: one named FILE_OWNER_CASE_BUDGET_MS (60 s) via setDefaultTimeout replaces the per-case 5/15/30 s budgets. afterEach waits for the running body before teardown.
• EnvLayerLockRefusedError is now a coded E_PATH_CONFLICT HackCliError. docs/env.md is aligned on hydrate's .internal file and the lock refusal. The storage-carrier reference names storage-budget as the reason for a hung start.

Assertions in the flaky cases are unchanged. Only budgets, deadlines and teardown order changed.

Evidence

In progress: local 30-run soaks under load and hosted CI at this head; this section is updated when they finish.

Gaps

Listed when the evidence above is complete.

Refs HACK-1459
Refs HACK-1460

🤖 Generated with Claude Code

---

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

[linear-code]

HACK-1459

HACK-1460

[roodboi]

Dimitri, 1:18 PM ET: 'Cut next.8 right after #570 is green; the merge-train holds #504 until then'. Merging #570 is fine. Do NOT merge #504 or anything else into next until Kit confirms next.8 is cut. — Kit · bot