feat(native): warn value-free on stale env at native exec and audit env keys in native doctor

[roodboi]

Summary (HACK-1140 native follow-up, HACK-1127 follow-up; unit E3)

HACK-1140: stale env warning for native exec

#301 added a value-free stale-env warning for Compose hack exec. Native image-project exec and authored native exec now run the same check.

• Record. The foreground hack up / hack restart records salted HMAC-SHA256 digests of the env selection it delivered, using the same digest code as feat(exec): warn value-free when a running service's env changed since start #301 (compose-env-fingerprint.ts). The record is written once the run is ready and is bound to that run id. It lives in .hack/.internal/native-env-fingerprints/<sha256(owner, branch)>.json: one file per instance, mode 0600, written with a temp file and rename. It holds no key name or value. Authored records also store the public --env and --profile selectors.
  • Image projects digest the Compose-file env resolved for the run's env name. This is captured before adaptation, AWS and runtime metadata, so time-varying credentials cannot cause false warnings. The callback is startNativeProject({ onEnvironmentReady }).
  • Authored projects digest the compiler-selected managed values that privateDelivery sends. The new serveNativeAuthoredProject({ onEnvironmentSelected }) observer is synchronous and receives digests only. privateDelivery now shares the projection with exec through selectNativeAuthoredManagedEnvironment. Its payload is unchanged.
• Lifetime (same documented semantics as feat(exec): warn value-free when a running service's env changed since start #301). When the foreground ends, it removes the record only if the record is still its own (salt-bound). A restart drops the scope's record once the previous run is stopping. That is the image down hook and the authored onStopped hook. So a failed restart, or a run that never becomes ready, leaves no record, and exec stays silent rather than guessing.
• Exec. The check runs after the command is admitted and completes, so a refused request resolves no env. It still writes ahead of the captured output. It resolves the same selection again, compares only when the record's run equals the current run, and writes one closed line to stderr. Exec still runs, its exit code is unchanged, and stdout stays the command's output.
  • authored: WARNING: Env for service "web" changed since it started; this exec uses the env it started with. Run \hack restart` to apply the current env.`
  • image: ... the running service still uses the env it started with. ... Native image exec sends freshly resolved values to the exec itself, so the warning is about the running service.
  • The service name appears only if it matches the Compose service-name grammar. The hint is hack restart because native restart is whole-project.
• A missing record, a record from another run, a legacy mapping without an env name, a changed env name, and any resolution failure all produce no warning.
• Bounded authored check. The authored exec check gets the exec's cancellation signal, combined with a 5 s timeout (NATIVE_AUTHORED_EXEC_STALE_ENV_TIMEOUT_MS). The signal reaches input acquisition. The advisory step also settles as soon as that signal aborts, even if the resolution has not finished. Ctrl-C during the check returns 130 at once and writes no output. After the timeout, the command's output and exit code follow with no warning. A failed check also writes no warning.
• Not covered by this PR. Two exec paths still run no stale-env check; they are left as a HACK-1140 follow-up, and docs/env.md now says so:
  • an authored .hack/hack.project.json project on the Compose backend (tryNativeComposeCommand -> savedCommand)
  • a project switched with hack config adopt (tryLegacyComposeAdoptedCommand, exec in the retained containers)

HACK-1127: env-key diagnostic in native Doctor and nested public copies

• handleNativeDoctor now runs the existing "env key" check when it runs inside a project. Outside a project, native Doctor output is unchanged, with no skip warning.
• env-key-public-path now also finds copies in nested public/, static/, dist/, build/, out/, www/, _site/, .next/ and .output/ directories, such as apps/web/public/.hack.secret.key.
  • The walk is breadth-first in name order and bounded: at most 6 levels deep, 4096 directories and 100,000 entries.
  • It skips node_modules and .git, never follows symlinked directories, and passes over unreadable directories.
  • Subjects are project-relative. A path that cannot be spelled portably is reported as <unprintable-path>/.hack.secret.key with a generic remedy.
  • Root-level findings are unchanged.
• runCheck now clears its timeout timer once a check settles. Before this change, a fast check with timeoutMs kept native Doctor alive until the deadline (about 5 s).

Docs: docs/env.md (the hack exec row, the stale-env section, and the env-key table and walk bounds). The CLI surface and agent guidance did not change. bun run docs:cli-reference produced no diff, and plugin renders are untouched.

Validation (local, macOS arm64; no Docker, real HOME, keychain or sudo)

Rework (head 7afb8048)

Fixes for the verifier's findings on a4497fe9:

• Session ownership guard: the restart test now waits for the restart's queued write, asserts it, then asserts the record still belongs to the restart after the previous session's late release(), and is gone only after the restart's own release.
• Walk bounds: findNestedPublicArtifactDirs is exported with an optional limits test seam. Production uses the documented constants. New tests:
  • the directory bound stops breadth-first after N directories
  • the entry bound counts every entry read, including files
  • the real default stops at 4096 directories through inspectProjectEnvKey: with 4094 fillers, zz/public is found; one more filler hides it
• Cancellation and latency: see Bounded authored check above. New tryNativeAuthoredCommand tests:
  • Ctrl-C during a check that ignores its signal returns 130, the seam's signal is aborted, and nothing is written
  • a check that never settles is cut at the bound: the output follows, the exit code is kept, there is no warning, and the seam's signal is aborted
  • negative control: a warning resolved after the bound, or a rejected check, writes nothing
• Docs: the hack exec row names the covered native families. The stale-env section describes the bound and lists the two uncovered exec paths.

Tests

• bun test tests/native-exec-stale-env.test.ts: 24 pass (21 before). Covers:
  • the store: 0600, value-free, per-scope isolation, tampered/foreign records read as absent, salt-bound forget
  • the session: record, restart drop, late release of the previous run, never-ready, unwritable
  • the warning text
  • image and authored resolvers with stub run loaders and env resolvers
  • runNativeProjectExec with a stub exec: warning on stderr ahead of output, stdout unchanged, no check for a refused exec
  • tryNativeAuthoredCommand with stub exec, serve and stop seams: exec warning, up records while ready and removes on exit, never-ready writes nothing, a failed restart drops the record
• tests/native-project-start.test.ts: 70 pass. The digest is reported once, right after the mapping save and before ready. It matches the prepared (pre-adaptation) env and contains no value. A failing observer never fails startup.
• tests/native-authored-project-start.test.ts: 41 pass on a4497fe9 (see the load note under remaining gaps). With the real managed-input fixture, the observer fires before ready, and its digest matches the delivered TOKEN value (unchanged) and differs for an edited one. A selection without managed keys digests an empty set, and a throwing observer never fails startup. The existing delivery-payload assertions still pass.
• tests/doctor-env-key.test.ts: 31 pass (28 before). Covers nested monorepo copies (apps/web/public, packages/site/dist, apps/docs/.next), skipping node_modules/.git/symlinks, the depth, directory and entry bounds, and unprintable paths.
• tests/native-ca-doctor-cli.test.ts: 4 pass, using privateCliEnv. Native Doctor in a fixture project reports the env key check with the nested public finding, and the output contains no key text or fixture path. The existing test now runs from an isolated cwd.
• Affected suites, combined: 613 of 616 pass across 28 files. Included: compose-env-staleness, project-exec-command, project-up-startup-state, native-project-exec, native-project-restart, native-authored-command/-restart/-exec/-oneoff/-logs, native-exec-environment, native-up-runtime-metadata-selection, doctor-*, integration-ownership, cli-spawn-env-isolation.
• env-command-matrix and skill-references: pass.
• bun run --cwd packages/cli typecheck: clean.
• bun run --cwd packages/cli check: 0 errors. The 34 warnings are pre-existing. Changed tests were linted explicitly and are clean.
• Rework run on 7afb8048 (load average 17 to 19):
  • native-exec-stale-env, doctor-env-key, native-project-start, native-ca-doctor-cli, integration-ownership, cli-spawn-env-isolation, native-authored-project-exec and native-authored-project-oneoff: 235 pass, 0 fail.
  • native-authored-command, native-authored-command-dispatch, native-exec-stale-env and native-authored-project-exec: 155 pass, 0 fail.
  • compose-env-staleness, the doctor-* suites, project-exec-command and project-execution-routing: pass.
  • packages/cli typecheck: exit 0. packages/cli check: exit 0 with 0 errors and the same 34 pre-existing warnings. Biome on the changed files is clean.
  • docs:cli-reference: no diff.
• Rework mutation checks: all 11 mutations made at least one test fail (11/11 killed):
  • release forgets without the salt (the mutant that previously survived)
  • directory bound removed; entry bound removed (both previously survived)
  • default directory bound off by one
  • entries counted as directories only
  • beforeOutput gets a fresh signal instead of the exec's
  • resolver not given the signal
  • no settle-on-abort race
  • no timeout
  • beforeOutput unwired
  • a failed check surfaces a value
  • A post-abort write guard survived because the race already covers that case, so the guard was removed rather than left untested.
• Original mutation checks: all 17 mutations made at least one test fail (17/17 killed):
  • both resolvers forced silent
  • run binding removed
  • release keeps its own record
  • forget ignores the salt
  • restart drop removed
  • ready commit removed
  • authored and image exec warning writes removed
  • native start never reports, or reports adapted env
  • authored delivery observer removed
  • nested walk disabled, node_modules not skipped, depth unbounded
  • native Doctor skips the check, or always adds it

Negative controls

• Identical env, no record, a record from another run, a legacy mapping, a changed env name, a different service and a resolution failure all produce no warning. Each is tested.
• Warnings, records and Doctor output were checked against the synthetic before/after values and key names. None appear.
• A run that never becomes ready writes nothing (.hack/ stays empty). A refused image exec runs no env resolution.

Remaining gaps (host-bound)

• No live native runtime run. The handleNativeUp wiring in project.ts (session creation, onEnvironmentReady, and the restart down drop) is three lines of plumbing. The functions it composes are tested, but the wiring itself has no direct test, because exercising it needs the native runtime. An end-to-end check (up, edit env, exec, restart) on a host with the native candidate is still open.
• The authored exec check acquires inputs again after a completed exec, which can add compiler and env-resolution latency. This happens only when a record for the current run exists, and it is capped at 5 s and cancellable. A real native host has not measured that latency.
• The image-project exec check does not receive a signal, and the exec it follows takes none either. It resolves only the Compose-file env, with no compiler run. The verifier did not flag it, and this PR leaves it unchanged.
• Under host load (load average 17 to 26), tests/native-authored-project-start.test.ts fails intermittently with "Startup fixture settlement unconfirmed" and 5 s timeouts. In the rework run it passed 18 to 24 of 41. The verifier saw the same suite fail in all 3 runs on base 8d9dc22e under the same load. This rework does not touch that file or its code under test. The PR's two new tests in it pass when run alone.
• Pre-existing failures on the base, also failing in a clean export of 8d9dc22e:
  • tests/native-authored-project-recovery.test.ts: 2 no-host recovery cases
  • tests/mcp-repeat-install.test.ts: 2 stdio rollback cases

🤖 Generated with Claude Code

---

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