[roodboi]

Follow-ups to #433 (HACK-1375) and #435 (HACK-1376), both already on next.

Root cause

1. The unset compare-and-swap was not tested. unsetProjectEnvValue passes expectedExisting: text to the layer write. If you delete that line, every lock, hydrate and config test still passes, because only the set path had a paused-writer conflict test.
2. Some layer locks can never be reclaimed, and the message did not say so. withEnvLayerLock reuses the projects-registry owner protocol. That protocol never removes a malformed receipt, a receipt it does not trust (another uid, or writable by group or others), a receipt whose PID now belongs to a live process, or a dead owner behind a leftover <lock>.recovery guard. In each of these cases every env set/add/unset/hydrate on the layer waited 10 s and then printed Another hack env command is writing <file>; … Retry when it finishes. No retry could ever succeed, and the message did not name the lock file.
3. A key can become unignored after a later git init. In a non-git directory, the first --secret creates the key and writes its root .gitignore entry. Outside git, an existing key deliberately triggers no .gitignore write. So if .gitignore is deleted and the directory then gets git init, the key is not ignored, and Hack is not running at that moment.
4. The re-include refusal named the wrong cause. The ignore probe that runs after the entry is in place produced the same "Hack could not add it to <.gitignore>" message as a failed write. That is wrong when .gitignore already contains .hack.secret.key followed by !.hack.secret.key.

Fix

• src/lib/env-layer-lock.ts: EnvLayerLockTimeoutError now has a reason (held | recovery_guard) and the lockPath. The message is still one value-free line with no stack:
  • held: Another hack env command is writing <file>; gave up after waiting 10s for its lock at <lock>. Nothing was written. Retry when it finishes. If no hack env command is running, Hack cannot reclaim that lock itself: remove <lock> and retry.
  • recovery_guard: when the registry reports a dead owner behind a busy guard, the message keeps the registry's recovery guard is busy (interrupted recovery requires offline inspection) detail and names both <lock>.recovery and <lock> as the files to remove.
  • The lock helper still never removes anything itself. src/lib/projects-registry-lock.ts is unchanged; the classification reads the registry's existing timeout detail. That file belongs to G73 / HACK-1377.
• src/lib/project-env-config.ts: projectEnvKeyUnignoredError now takes a cause. unwritable keeps the existing message. reincluded says the root .gitignore lists the key but a later rule in that file re-includes it, and asks the user to remove that rule. Once the entry is present, no deeper ignore file can apply to a key at the project root, so a later rule in that same file is the only possible cause.
• src/commands/doctor.ts: exports checkProjectEnvKey so the real doctor check can be tested end to end. It also moves a misplaced docblock onto that function. The check's behavior is unchanged.
• docs/env.md: documents unreclaimable locks and the recovery step, the re-include cause, and the git init decision. It also adds an env-key-unignored example to the doctor table.

Decision on a later git init (item 3)

Watching for git init is out of scope for env writes, because Hack runs no code when it happens. Outside git, an existing key still needs no entry, and Hack does not recreate a root .gitignore the user deleted. That behavior is unchanged and covered by the existing test. The guarantee comes back at the next Hack touchpoint:

• hack doctor's env key check reports env-key-unignored (warn) with a remedy. This check already existed; the new test proves it catches this exact sequence.
• The first --secret set or hydrate in the new repository adds the entry before it uses the key, or it refuses (fix(env): create the project key only after its root .gitignore entry #433 behavior).

Tests (each proven by mutation)

Test	Mutation that makes it fail
project-env-layer-lock: an unset refuses with a conflict when a writer that takes no lock changed the layer after its read. A spyOn pauses resolvePrimaryLocalProjectDir, the one awaited call between the local unset's read and its write. The test edits the layer, resumes, and expects AtomicWriteConflictError with the edit kept.	delete expectedExisting: text, from the unset: 1 fail
project-env-layer-lock: a layer lock Hack cannot reclaim… uses three receipts: malformed, group-writable with an exited PID, and PID 1 standing in for a reused PID. Set and unset each refuse with the exact message, the receipt is left untouched, and removing the named lock lets the retry succeed. The existing held-lock test asserts the new message too.	restore the old message: 2 fail
project-env-layer-lock: a dead owner behind an interrupted recovery guard… covers a set (300 ms wait) and a hydrate (default 10 s): both give the recovery_guard message with both paths, write nothing, and leave the lock and guard in place. After both are removed, the set succeeds.	classify the guard case as held: 1 fail
project-env-key-ignore: the re-include test now expects the reincluded message, does not contain "could not add it", and checks that .gitignore was not rewritten.	send unwritable for the post-entry probe: 1 fail
project-env-key-ignore: a key whose entry was removed before a later git init… runs the exact reported sequence through the source CLI, then the real checkProjectEnvKey: status warn, env-key-unignored, and no key bytes or absolute root in the output. The next --secret set repairs the entry and doctor returns ok.	drop inspectLocalKeyIgnored from doctor: 1 fail

Every fixture uses a private HOME, HACK_HOME, global config and Docker config, HACK_SECRETS_DISABLE_KEYCHAIN_FALLBACK=1, and git without global or system config. The env layer is written before any --secret. The in-process doctor call swaps in the same private environment and restores it afterwards.

Evidence

• Manual repro before the fix: (2) dead owner plus guard, and a malformed receipt, gave the old "Retry when it finishes." message. (3) after git init, git check-ignore exits 1 and git status lists .hack.secret.key. (4) gave the "could not add it" message. After the fix, the same script prints the messages above, and removing the named lock makes the retry exit 0.
• Focused: tests/project-env-layer-lock.test.ts 12/12 and tests/project-env-key-ignore.test.ts 8/8 pass locally.
• bun run check (includes privacy:check) exit 0. bun run --cwd packages/cli typecheck exit 0. gitleaks 8.30.1 (gitleaks dir on the git log -p origin/next..HEAD export): no leaks.
• The CLI surface and consumer agent guidance did not change, so no reference or plugin regeneration was needed.
• Full suite: hosted CI test at this PR head (see checks).

Gaps

• In a wider local run of 11 related env/doctor files, 13 tests in project-env-write-refusals, project-env-stable-ciphertext and project-env-worktree-key failed with beforeEach/afterEach hook timed out while the host load average was 51–60 on 18 cores. None of them asserts a message this PR changes. Hosted CI is the evidence for them.
• The refusal is still a ClosedCliError with no E_* code (as before). Adding a lock-busy code would change the error-code registry and its generated docs, so it is left for a separate decision.
• Classifying recovery_guard depends on the registry's existing timeout text. If G73 rewords that text, the guard test fails in the merge train rather than silently falling back to held.
• The held message cannot tell a live writer from an unreclaimable lock without parsing the receipt (code G73 is editing), so it covers both cases: retry, or remove the lock when no hack env command is running.
• The unset CAS test uses spyOn on an ESM namespace export (worktree-local-config.ts), in process and restored in finally.

Round 2: merge with current next

While this PR was being verified, next moved from 7d9c89f to 5208ee5 (#404, #446, #430, #439, #421, #448, #452, #405), and the PR became CONFLICTING.

• Merge commit 7ac7cbb merges origin/next (5208ee5) into the branch. The only conflict was the checkProjectEnvKey docblock in src/commands/doctor.ts, which fix(doctor): name explicit recovery rollback for a literal override a pending adoption pins #448 also moved. It is resolved to this PR's side: the extended docblock plus export async function checkProjectEnvKey. Compared with next, doctor.ts now differs only in those lines.
• No other code changed in this round. The diff against next is still the same 6 files.
• Gates on the merged head: bun run check (includes privacy:check) exit 0. bun run --cwd packages/cli typecheck exit 0. Focused tests project-env-layer-lock, project-env-key-ignore and cli-spawn-env-isolation pass 27/27 (--timeout 120000) under test: fail and contain process-state leaks between test files #405's new preloads. gitleaks 8.30.1 (gitleaks dir on the git log -p origin/next..HEAD export): no leaks.
• Full suite: hosted CI run 40056707145 at 7ac7cbb (base 5208ee5): test passed in 38m45s, plus docker-e2e 1-4/4, Candidate core (ubuntu), Config compiler (ubuntu x64/arm, macos-15-intel), Runtime state models, linux-process-lifetime, runtime-images and secret-scan. The two macos-latest jobs were still queued for a runner after about an hour. The earlier green run 39978726682 was at ed877f5, before the base moved, so it does not count for this head.

Refs HACK-1386

🤖 Generated with Claude Code

---

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

[linear-code]

HACK-1386