[roodboi]

Summary

Two hack doctor fixes.

• HACK-1316: doctor no longer follows a symlinked .hack or .hack/.internal. Before this fix, doctor --fix deleted a file outside the project.
• HACK-1311: doctor now reports an adopted (hack config adopt) project correctly, and doctor --fix completes in one. Before this fix, doctor refused the project as native input, the --fix plan threw, and --fix with tracked generated files failed after it had already changed the Git index.

Rework after review (commit ff7f11e1)

The verifier found one blocking defect in the first version (ffbc4ffd):

• Defect. In an active adopted project whose generated files are tracked by Git (for example a committed .hack.secret.key), hack doctor --fix --no-interactive exited 1 with E_NATIVE_PROJECT_UNSUPPORTED. It did this after git rm --cached had already run, so .hack/.gitignore was not written and the later fix steps (hackd, Docker networks, Caddy and the rest) never ran.
• Root cause. maybeUntrackGeneratedFiles selected the adopted project, ran git rm --cached, and then called ensureHackDirGitignore. That writer calls assertLegacyProjectDirectory, which throws ProjectInputSelectionError("native") for an active adoption (src/lib/project-input-selection.ts).
• Fix. For an adopted project, the step now changes only the Git index. It still adds a committed .hack.secret.key to the root .gitignore, which is not an adoption input. It leaves the adoption's .hack/.gitignore unchanged and says so in a closed note: Removed N path(s) from the git index. Left .hack/.gitignore unchanged: an adopted Compose project's .hack/ belongs to 'hack config adopt'. The plan line names the same change. Legacy projects behave exactly as before.
• Docs. docs/reference/native-compose-adoption.md now matches the code: --fix leaves .hack/.gitignore unchanged and adds a committed key to the root .gitignore.
• Test gaps closed.
  • The findDoctorLegacyProjectContext guards on the later --fix steps had no regression test. The new test runs the whole --fix flow with Docker reachable and --migrate-env-config, so the lifecycle, incomplete-runtime and env-migration steps run against the adopted project.
  • The writer's refusal before mkdir (HACK-1316) had no test. A new unit test covers it.

Update: merge with next at 5c9cc82e (commits 0d6aa587, 51244fc9)

• 0d6aa587 merges origin/next at 5c9cc82e (fix(native): give storage proofs their own budget outside the start phase #375, fix(project): leave read-only .hack/.gitignore alone and report symlinked .hack in doctor #407, fix(env): share global Compose env references and refuse an oversized environment #412) with no conflicts. fix(project): leave read-only .hack/.gitignore alone and report symlinked .hack in doctor #407 changes the same .hack/.gitignore code in doctor: the repair helper now returns { changed, readOnly } and the untrack step can leave a read-only file alone. After the merge, the adopted branch of the untrack step still skips the .hack/.gitignore writer, and only the legacy branch uses fix(project): leave read-only .hack/.gitignore alone and report symlinked .hack in doctor #407's read-only handling.

• 51244fc9 is a one-line docs fix. docs/reference/native-compose-adoption.md listed every check that doctor skips for an adopted project except the .hack/.gitignore check. The code already skips it.

• The verifier's repro, rerun on the merged head. It is the verifier's own scratch test: retainedSourceBindFixture, a real git init, git add -f .hack.secret.key, adopt (prepare and publish), then runCli doctor --fix --no-interactive, with shell run mocked. The output has no E_NATIVE_PROJECT_UNSUPPORTED. git ls-files is empty, .hack/.gitignore is not created, the closed note above is printed, the adoption is still active, and the later steps run (the global daemon start call and the closing Re-run: hack doctor note).

• Why that run still exits 1. Doctor's exit code comes from the checks that run before --fix. This is existing behavior and is the same for legacy projects. The verifier's harness makes every non-Git exec fail, so docker daemon is an error, and the committed key is an error in the generated files and env key checks. The PR's doctor-fix-adopted-project test makes Docker reachable. Its .hack/.env.state.json case exits 0. Its key case exits 1 only because of the committed-key error.

• Mutations rerun on the merged head, each killing its test for the intended reason:

  Mutation	Result
  Adopted untrack step writes .hack/.gitignore again (ffbc4ffd behavior)	doctor-fix-adopted-project 0/2, with E_NATIVE_PROJECT_UNSUPPORTED in the output
  findDoctorLegacyProjectContext no longer skips an adopted project (survived the first review)	doctor-fix-adopted-project 0/2, with E_NATIVE_PROJECT_UNSUPPORTED
  Writer's pre-mkdir refusal removed (survived the first review)	compose-env-at-rest 15/16; "the writer refuses a symlinked .hack before creating .internal behind it" fails

Root cause

HACK-1316: symlinked .hack/.internal

src/lib/compose-env-at-rest.ts checked that .hack/.internal was a real directory, but only inside readReplaceablePrivateFile, and it never checked .hack. When that read refused, inspectEntry called lstat(path) to choose between absent and unverifiable. That lstat followed the .internal link, found the outside compose.env.override.yml, and classified it as unverifiable. With includeUnverifiable, the --fix removal then ran lstat, rename and unlink through the same link, which deleted the outside file. The stale-aside sweep ran readdir on the linked directory before any symlink check, so it could also unlink .remove-shaped files in the outside directory.

HACK-1311: adopted projects

An active or pending adoption makes inspectProjectInputsAtRoot classify the root as native. Doctor's first step, assertLegacyProjectDiscovery, therefore threw E_NATIVE_PROJECT_UNSUPPORTED. Every project check and buildDoctorRemediationPlanLines call findProjectContext, which throws the same refusal. Every --fix step that writes legacy project files does too.

Fix

HACK-1316 (src/lib/compose-env-at-rest.ts)

• One no-follow ownership check now covers both .hack and .hack/.internal. The writer and every read, removal and sweep use it.

• A new refused state covers these cases:

  • a symlinked or non-directory .hack or .hack/.internal;
  • a symlinked or non-regular override.

  Doctor reports it with a closed, value-free message. A refused override is never eligible for removal.

• Removal returns before the sweep when the directories are not real. It checks the directory identities again before the move and before each aside unlink. The aside listing runs only on the held directory.

• The writer refuses a linked .hack or .internal before mkdir, so it creates nothing through the link.

HACK-1311 (src/commands/doctor.ts, src/lib/doctor-adopted-project.ts)

• Doctor selects an active or pending adoption first, with selectLegacyComposeAdoptedRoot, the selector that adopted ps, logs and the other adopted commands use. The legacy-discovery refusal runs only when no adoption is found.
• Checks for an adopted project:
  • The project check names the adopted root. A pending adoption is a warning that asks for explicit recovery.
  • The env key, tracked generated files and Compose env at rest checks run against the adopted root.
  • Each check that reads adoption-owned inputs is listed as not checked.
  • Agent integrations use the adopted root, and sessions mux uses global settings.
• --fix for an adopted project:
  • The plan says it leaves the adoption's inputs, retained containers and state alone, and it skips env migration.
  • Lifecycle, incomplete-runtime and env-migration repairs treat the project as having no legacy project.
  • Untracking generated files changes only the Git index (see the rework above).
• The legacy project-check block moved unchanged into runProjectChecks, to stay under the complexity limit. The fix(native): keep Compose-only projects on the Compose backend with closed refusals #365 compose backend features check and the fix(env): keep decrypted Compose env values off disk #357 env-at-rest adopted fallback are unchanged.

There are no CLI surface changes and no agent-guidance changes.

Tests

Test	Proves	Mutation that kills it
doctor-fix-adopted-project (new), 2 cases: a committed .hack.secret.key and a committed .hack/.env.state.json	Real runCli doctor --fix --no-interactive --migrate-env-config in an adopted fixture with a real git init. Docker is reachable through the mock, and Git runs only on the fixture with no global or system config. Each case checks: no E_NATIVE_PROJECT and no canary or key text; the exact plan line and step note; the closing notes, which prove every later step ran; git ls-files is empty and the file is unchanged on disk; the root .gitignore gets the key entry only in the key case, and .hack/.gitignore is not created; the receipt is unchanged, the adoption is still active, and no stub engine command or project run call happens. Exit code: 0 for the env state file. For the key it is 1, because the env key check reports the committed key as an error before --fix runs. That is existing doctor behavior.	ffbc4ffd behavior (always write .hack/.gitignore): 0/2 pass, exit 1. findDoctorLegacyProjectContext no longer skipping adopted projects: 0/2 pass, exit 1. Plan line reverted to the legacy wording: 0/2 pass.
compose-env-at-rest: "the writer refuses a symlinked .hack before creating .internal behind it" (new)	A link to an outside directory without .internal gets nothing created behind it, and the refusal is closed.	Writer's pre-mkdir refusal removed: fails (this mutation survived before).
doctor-fix-noninteractive: "doctor --fix leaves a file behind a symlinked .hack/.internal untouched (HACK-1316)"	Real runCli doctor --fix: the outside file survives, and the plan and notes do not name it.	origin/next's helper: fails with ENOENT, because the outside file was deleted.
compose-env-at-rest: symlinked .hack and .hack/.internal (2 cases)	refused state, closed message, no repair planned, no asides removed with a stale-aged clock, writer refusal, outside contents byte-identical.	Old helper: both fail. Directory list without .hack: the .hack case fails. inspectEntry always unverifiable: the symlinked-override case fails.
doctor-adopted-project: doctor --json and the --fix plan in an adopted project	Closed project message, the checks that run, the not-applicable list, the exact plan, the receipt unchanged, no container start or stop.	Adopted branch of runProjectChecks disabled: fails. Preflight forced back to legacy discovery: fails.

All tests use temporary directories only. They do not touch the real HOME, ~/.hack, the Docker socket, the keychain or launchd.

Evidence

• Toolchain. Bun 1.4.2 (mise x bun@1.4.2), bun install --frozen-lockfile. bun.lock is unchanged.
• Local gates on the current head 51244fc9 (M5):
  • bun run --cwd packages/cli typecheck: 0 errors.
  • Root bun run check: exit 0, including privacy-check: ok (34 existing warnings in other files).
  • Biome on the 7 changed source and test files: clean.
  • gitleaks 8.30.1: gitleaks dir over a git log -p origin/next..HEAD export: no leaks.
• Focused tests at 51244fc9, each file run on its own with --timeout 120000 (the M5 was under heavy load), all passing:
  • compose-env-at-rest 16, doctor-fix-noninteractive 10, doctor-adopted-project 2, doctor-fix-adopted-project 2
  • native-compose-backend-features 13, native-compose-backend-features-cli 15, compose-env-at-rest-cli 9
  • doctor-command 28, doctor-json 3, doctor-generated-files 11, doctor-env-key 31, doctor-utils 8, doctor-worktree 6
  • From fix(project): leave read-only .hack/.gitignore alone and report symlinked .hack in doctor #407 and fix(env): share global Compose env references and refuse an oversized environment #412, which touch the same code: hack-gitignore 14, project-env-config 58, project-env-hydrate 18, compose-env-shared-references 6
• The five doctor --fix and at-rest files also pass together in one process (41/41), which checks that the scoped module mocks do not interfere.
• Under the same load, doctor-fix-adopted-project with Bun's default 5 s timeout failed in a fixture hook. It passes with the longer timeout. This is load, not a code change.
• Full suite on the M3: not run. The runner for 91dae070 waited about 6.5 hours and never got the shared CI lock. I stopped it and queued a runner for 51244fc9, which waited about 50 minutes. During that time the lock directory had existed since 12:37 with no suite process running on the M3, several other units were also waiting, and free space was about 57.6 GiB, under the 58 GiB floor. I did not touch the lock, since I could not prove who owned it. I stopped my runner. It created no worktree or ref.
• Hosted CI: all 16 checks pass on the current head 51244fc9 (run 39839971608): the full-suite test job (39 min), all four docker-e2e shards, candidate core, config compiler, runtime state models, and secret scan. Earlier heads 0a94d881, a2470049 and 91dae070 also passed.

Remaining gaps

• No M3 full suite. It did not run because the shared lock was blocked and free space was under the floor (see Evidence). The hosted full-suite test job ran at 51244fc9 on ubuntu, not on macOS.
• Symlinked .hack now refused by the writer. A Compose command that renders the env override now refuses a symlinked .hack, not only a symlinked .internal. This matches the existing .hack/.env rule. A project that relied on writing through a linked .hack will see a closed refusal.
• Small race window remains. Directory identities are checked again before each move and unlink, not held as open descriptors. A same-user swap in that window remains, as already documented for the move-aside window.
• Other generated files can be committed again. For an adopted project, --fix does not add the untracked generated files under .hack/ to any ignore file. Only the key gets a root .gitignore entry. The note asks the user to keep them out of later commits.
• --fix with a committed key exits 1. The exit code reflects the checks that ran before the fix, for legacy and adopted projects alike. The fix itself completes and removes the key from the Git index, which is what the tracked-key checks read.
• Pending adoption not tested. The pending-adoption warning has no test: the fixture has no cheap pending state.
• Native backend skips adopted project checks. With HACK_RUNTIME_BACKEND=native, native doctor still skips project checks for an adopted project. This is unchanged.

Refs HACK-1316
Refs HACK-1311

🤖 Generated with Claude Code

[linear-code]

HACK-1311

HACK-1316