feat(native): repair the hack.local DNS route to the native relay

[roodboi]

Summary

Product decision (2026-10-12): keep hack.local as the default dev-host root. Under the native backend, the HTTPS relay listens on 127.0.0.1, but a Docker-era install routes .hack.local to Docker Caddy (address=/.hack.local/172.30.0.2). This adds an authorized, reversible native repair.

• Doctor reporting: native hack doctor on macOS adds a native hack.local route check. --json carries a hackLocalRoute object (status, closed reason, old/new line, resolver action, relay port, receipt state, next command). Details name lines by number. They never repeat file contents, and control characters are replaced.
• Repair (hack doctor --fix): rewrites only the single Hack-managed address=/.hack.local/<old> line to 127.0.0.1 in place. It never adds a second line. .hack, .hack.gy and every other byte stay the same, including a leading UTF-8 BOM. It creates /etc/resolver/hack.local (nameserver 127.0.0.1) only when the file is missing.
• Preconditions: each unmet precondition is a closed refusal reason:
  • relay-not-verified: the relay owner must be verified via inspectActiveNativeHttpsOwner, and its receipted port must accept a TCP connection on 127.0.0.1.
  • no-managed-line, unmanaged-line: exactly one exact-format line must exist, with no include-dir or subdomain claims.
  • foreign-target: the target must be one Hack wrote (172.30.0.2 or ::1).
  • old-target-live: the old target must not answer on :443 within 1.5 s.
  • foreign-resolver
  • pending-receipt, invalid-receipt
  • non-interactive: this refusal names hack doctor --fix.
  • declined
  • busy: another repair or rollback holds the lock.
  • restart-unavailable: the dnsmasq launchd job cannot be restarted safely. This is checked after the prompt and before any effect.
  • inputs-changed: everything is inspected again after the prompt.
• Privilege: uses the same native path as the existing native DNS and CA code. That is confirmSafe plus sudo -v for the macOS prompt, then bounded sudo -n steps through runNativeDnsAttachedCommand. The resolver is created with the existing privileged resolver script, which is now exported as runPrivilegedResolverOperation. dnsmasq restarts through the verified launchd job (prepareNativeDnsLaunchdRestart), then the DNS cache is flushed and live DNS is verified with dig and dscacheutil. Hack never handles a password.
• Receipt and lock: <native-home>/native-dns/hack-local-route.json (0600, in a 0700 directory owned by the user). It records the old and new line, the SHA-256 of the exact file bytes before and after, the resolver action and identity, and timestamps. It is published as pending before any effect and becomes applied after live verification. Its old line must be one of the managed single-line forms, and its paths must be absolute and free of control characters. Repair and rollback hold an exclusive lock (hack-local-route.json.lock, published with link(); a lock whose holder pid no longer exists is taken over once).
• Automatic cleanup: if a step fails, the cleanup restores the earlier line. It restarts dnsmasq only when the cleanup changed something or a restart was already attempted. When the failure came before any change, it reports "nothing was changed" and marks the receipt rolled-back. It never overwrites a concurrent edit: that case keeps the receipt pending.
• Rollback: hack global dns deactivate --domain hack.local needs a terminal (non-interactive otherwise, naming the command). It restores the exact earlier line and verifies the whole-file hash. It removes the resolver only if the repair created it and its identity still matches, then restarts dnsmasq. If dnsmasq is not running or the job is ambiguous, it still restores the file and says that dnsmasq was not restarted. A receipt whose line does not reproduce its own hashes refuses with invalid-receipt and is never written.
• Recovery cannot get stuck: sometimes dnsmasq.conf changed after the repair (for example a Docker-era hack doctor --fix rewrote the roots), or the receipt names another path. The rollback command then never writes the file. After a plain confirmation (no administrator prompt) it marks the receipt released and leaves dnsmasq.conf and any resolver as they are. That clears a pending receipt, and Doctor inspects the current file again.
• Dead end fixed: before this change, hack global dns preview|activate|deactivate with no --domain resolved to hack.local, which the planner always refuses. Now a built-in default gives a closed CliUsageError that names --domain <custom>, hack doctor --fix and the rollback command. A configured custom default_domain still works as documented. preview --domain hack.local shows the repair proposal without changing anything. activate --domain hack.local points to hack doctor --fix.
• Docs: docs/guides/native-candidate.md and docs/guides/init-project.md are updated, including the recovery path for a drifted receipt and a note that a non-443 HACK_NATIVE_HTTPS_PORT still needs the port in *.hack.local URLs. docs/reference/cli.md is regenerated (summary changes only; no change in this rework).

Rework after verification (head 81a8720)

This rework addresses each verifier finding on efb278e:

• Stuck recovery: a drifted or path-mismatched receipt is now released by the rollback command, which writes nothing else.
• BOM and hashes: readStableNativeDnsFile now decodes with ignoreBOM: true, so strings round-trip to the exact bytes. Receipt hashes equal the raw file hashes, and rollback restores identical bytes (checked with Buffer.compare).
• Value-free diagnostics: unmanaged-line and foreign-target details no longer repeat the line or the target. Every human message and doctor message goes through printable().
• Unclosed failures: repair refuses with restart-unavailable, and rollback reports a skipped restart instead of throwing. A pre-write failure no longer reports "automatic restore failed".
• Receipt hardening: the old line is checked against the managed single-line forms, the paths must be absolute and control-free, and the resolver identity must be dev:ino.
• Concurrency: an exclusive lock covers repair and rollback.
• Merge: merged current next (3c7cf39). The only conflict was an additive one in doctor.ts (envKey and hackLocalRoute fields), and both were kept.

Validation

All on the pushed head 81a8720 (merged with next):

• tests/native-hack-local-route.test.ts (34 tests) injects file roots in a temp directory and a fake privileged runner. The runner refuses paths outside the temp resolver directory and asserts sudo -n. Relay, probe, restart, flush and verify are also fakes. Owner checks use an injected ownerUid seam. In addition to the earlier coverage, the tests cover:
  • release of a pending receipt after a file rewrite, then current
  • BOM bytes and raw hashes
  • rollback refusing non-interactive and declined
  • rollback rechecking both the file and the receipt after authorization
  • a receipt whose line does not reproduce its hashes
  • newline injection with matching hashes, control-character paths, relative paths and bad identities
  • path-mismatch release
  • cleanup not overwriting a concurrent edit
  • restart-unavailable, and rollback with no restart
  • the busy lock and takeover of a stale lock
  • hard-linked and foreign-owned dnsmasq.conf
  • a non-private or foreign-owned receipt directory
  • hostile line and path diagnostics
  • the restart retried during cleanup
• Mutation check: a scratch script mutated each of these 19 guards one at a time, and each mutation fails the suite (19 of 19 killed):
  • the rollback and repair non-interactive gates
  • the rollback and release rechecks
  • the restore hash check and both drift checks
  • the receipt path check
  • both lock checks and stale-lock liveness
  • dnsmasq nlink and owner
  • the receipt directory mode and owner
  • BOM preservation
  • the old-line format check
  • restart-only-when-needed and the cleanup restart retry
• tests/native-hack-local-route.test.ts, tests/native-hack-local-route-cli.test.ts and tests/native-ca-doctor-cli.test.ts: 40 pass.
• tests/integration-ownership.test.ts and tests/agent-plugin-generation.test.ts: 25 pass.
• Related suites: 169 pass and 2 skip. They are cli-reference-docs, doctor-command, doctor-env-key, doctor-fix-noninteractive, doctor-json, global-command (+macos), native-ca-doctor and the native-domain-dns-* suites.
• bun run --cwd packages/cli typecheck: exit 0. bun run --cwd packages/cli check: exit 0 with 34 warnings, none in changed files. An explicit biome check of the 8 changed TS files reports no diagnostics.
• bun run docs:cli-reference produces no diff. No consumer guidance changed, so no plugin regeneration was needed.

Gaps

• Not exercised against a real macOS host. The real privileged resolver create, the launchd kickstart, live dig and dscacheutil, and the Safari/Chrome/Firefox checks (including the Local Network grant) remain manual.
• /etc/resolver must already exist for resolver creation. The privileged script does not create the directory. Machines with a prior v4 install already have it.
• A Docker-era hack doctor --fix or hack global install still rewrites all three roots to whichever target answers, which can undo the native repair. This is documented, and the receipt can now be released afterwards.
• Stale-lock takeover has a narrow race if two runs find the same dead holder at once. Each run needs an interactive prompt, so this window is not reachable in practice. It is documented in code.
• Native hack doctor --fix without --browser-url still reports the existing CA-repair error. The DNS repair runs independently.
• No hosted CI status was reported on the previous head. CI on this head has not been checked here.

🤖 Generated with Claude Code

---

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

[blacksmith-sh]

Found 1 test failure on Blacksmith runners:

Failure

Test	View Logs
native-config-process-policy (36.4s) — Native --profile must succeed/ native-config-process-policy (36.4s) — Native --profile must succeed	View Logs

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