[roodboi]

Summary

Native containers did not receive HACK_BRANCH, HACK_DEV_HOST, HACK_DEV_URL, HACK_ALIAS_URL, the current-service URL fields or HACK_RUNTIME_METADATA, although docs/cli.md promised them with no backend qualifier (found by a HACK-1163 acceptance run on the M3, next ccf526c). The native up path (handleNativeUp → startNativeProject) only delivered managed project env; buildRuntimeHostMetadataOverride was used only by the Compose path.

Design: public env, not managed delivery

The suggested fix was to merge the metadata into the managed (private) environment. That is not safe in the current runtime:

• Managed delivery wraps a service with the private launcher. The launcher requires a pinned absolute entrypoint and a numeric user (launcher::validate, image_process::apply_private). Images like busybox, node, postgres and redis would fail to start, including the accept-native-frontend.py fixture.
• Every declared bare key must be supplied on native one-off run-service (execution_environment_missing). Fresh exec also replaces values rather than inheriting them.

So native up adds the metadata as public environment in the normalized Compose that native review checks:

• src/lib/runtime-host-metadata.ts: a new shared buildRuntimeHostMetadataEnvironments holds the metadata logic, so both backends emit the same keys and document shape. It takes an optional HTTPS port: URLs include :PORT unless the port is 443; host variables never include a port. The Compose override bytes are unchanged (checked against the origin/next implementation for 16 input combinations, and pinned by a byte-exact test).
• src/backends/native-runtime-metadata.ts: applyNativeRuntimeMetadata runs after branch rewriting, adaptation and AWS, so the reviewed bytes are final.
  • Inputs: the route labels (normalized the way review does: lowercase, trailing dot removed), the effective branch (the review identity's branch when deferred), the base dev/alias hosts, and <project>--<branch> as the Compose project name.
  • Keys a service already declares are skipped. That includes the bare keys that Hack-managed project env adds, so explicit project values win.
  • List-form env keeps its shape, and $ is escaped.
  • verifyNativeRuntimeMetadataRoutes refuses before serving unless every active service's reviewed routing.hostnames match the advertised hosts.
• startNativeProject takes a new optional runtimeMetadata selection, which handleNativeUp supplies. The port is taken from opts.https. preflightNativeRestart reviews the same input.
• Retained graphs: the run mapping records runtimeMetadata: true. A restore re-adds metadata only for graphs that recorded it. Legacy retained graphs are restored exactly as admitted, so upgrading does not break their strict restore identity. A recorded graph restored without a selection fails early, before any effect.
• packages/runtime-core/src/project/hostname_change.rs: the hostname-change fingerprint now ignores the 10 reserved metadata keys in the normalized Compose document only (map and list env), because that is where Hack generates them. Their values follow the hostnames, so without this change, metadata would have blocked hostname-only retaining restarts (domain migration, as exercised by accept-native-frontend.py). The original .hack/docker-compose.yml is not masked: a HACK_* value the user declares there is an ordinary literal (Hack never overrides a declared key), so changing it still refuses. Any other env literal still counts. A change to metadata alone still refuses, because the graph proof requires changed routes.
• hack exec inherits the container's static env. Native hack run uses the admitted service environment.

Consumer guidance

src/agents/instruction-source.ts said containers receive HACK_RUNTIME_METADATA, HACK_DEV_URL and the other fields without qualification. It now says Compose-backed and native image projects receive them, and authored .hack/hack.project.json projects do not yet. The plugin bundle (bun run generate:agent-plugins) and the checked-in surfaces (.codex/skills/hack-cli, .cursor/rules/hack.mdc, examples/basic/AGENTS.md and CLAUDE.md, rendered through their installers with an explicit project root) are regenerated. The content revision is now 7c86dd4dda99, and the new hack-cli-skill and cursor-rules render fingerprints are appended to KNOWN_RENDER_FINGERPRINTS.

Authored native path (tryNativeAuthoredCommand)

It has the same gap, and so does the authored Compose renderer: no HACK_* metadata anywhere. It is not covered here. Authored env is compiled by the Rust config compiler into an environment_plan, and the authored frontend has no routing. Adding metadata needs a new compiler binding kind. Docs now state that authored .hack/hack.project.json configuration does not deliver these variables yet.

Validation

• bun test focused: tests/native-runtime-metadata.test.ts (new), tests/runtime-host-metadata.test.ts, tests/native-project-start.test.ts, restart, run, branch and input, the native-compose-adoption suites (projection, generation, branch, source-bind-generation), and tests/integration-ownership.test.ts. Result: 288 pass, 1 skip, 0 fail. New cases:
  • Branch native input carries values with port 8443, using a real project fixture, branch rewrite and project env.
  • A project-env HACK_DEV_URL overrides the metadata and stays private.
  • Base instance (no branch) has portless URLs for 443 or no port.
  • Native output has the same keys and values as the Compose builder.
  • A reviewed route mismatch refuses before serve.
  • Start and restart preflight review byte-identical metadata; legacy runs get none.
  • The mapping flag is persisted.
  • The Compose override bytes are unchanged.
• bun run --cwd packages/cli typecheck: 0 errors. bun run --cwd packages/cli check: 0 errors (34 existing warnings in other files). Changed tests linted.
• Rust 1.97.1: bun run check:local (fmt + clippy -D warnings) and bun run test:local both pass (1134 tests). Tests: runtime_metadata_follows_hostnames_but_other_environment_still_counts, and user_declared_metadata_keys_still_count_in_the_original (a user-declared HACK_DEV_URL change in map or list env still changes the fingerprint; generated metadata differences in the normalized document do not).
• Polish tests, each proven by a mutation that makes it fail:
  • Rust: masking the original document too makes user_declared_metadata_keys_still_count_in_the_original fail.
  • tests/native-project-start.test.ts "restart preflight refuses runtime host metadata that differs from reviewed routes": removing the verifyNativeRuntimeMetadataRoutes call in preflightNativeRestart makes it fail.
  • tests/native-up-runtime-metadata-selection.test.ts (new, CLI level through upCommand.handler with startNativeProject and authored dispatch mocked, temp HACK_HOME, no Docker): checks that handleNativeUp passes { devHost, aliasHost, projectName } for a branch with an OAuth alias and for a base instance without one. Removing the runtimeMetadata selection makes both cases fail.
• Guidance: integration-ownership, agent-plugin-generation, agent-instruction-source, skill-references, hack-init-skill, onboarding-* and shared-agent-skill tests pass. Root bun run typecheck and bun run check pass.
• Combined focused run after the polish (start, restart, run, branch, input, metadata, adoption projection/generation/branch/source-bind-generation, project-up-startup-state, integration-ownership): 348 pass, 1 skip, 0 fail. One earlier run of the same set timed out in native-compose-adoption-generation while a cargo build ran at the same time. That file passes alone, and the whole set passes on a rerun without the build.
• Unit tests inject runners; none use real Docker or OrbStack.

Gaps

• Not run on a live native runtime. No M3 or acceptance-script run has checked that containers see the env, that one-off/exec inherit it, or that domain-migration retaining restarts still pass with metadata present. Re-run scripts/accept-native-frontend.py and the HACK-1163 check.
• Changing HACK_NATIVE_HTTPS_PORT alone for a retained graph now refuses the retaining start. So does selecting or removing the native HTTPS frontend when its port is not 443, because the advertised URLs gain or lose the port. Both cases are documented in docs/cli.md and docs/guides/native-candidate.md; the workaround is to start with the original frontend selection and port.
• Retained graphs from earlier releases get metadata only after their next start without retained data.
• An unrouted graph with an HTTPS selection still advertises the selected port in HACK_DEV_URL, even though no frontend runs for it.
• Authored native and authored-Compose paths remain uncovered (see above).

🤖 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 (30.1s) — Native --profile must succeed/ native-config-process-policy (30.1s) — Native --profile must succeed	View Logs

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