feat(runtime): expose branch-safe host metadata (#66)

## Summary

- inject versioned, non-secret runtime host metadata into every Compose
service
- expose branch-qualified public route maps plus current-service
convenience fields
- make `up`, `restart`, targeted restart, `run`, and `exec` inspection
consume consistent generated Compose overrides
- extract and directly test branch-host rewriting
- document Compose-DNS vs public-URL usage and bump agent-integration
freshness

## Runtime contract

Containers receive `HACK_RUNTIME_METADATA`, `HACK_DEV_URL`,
`HACK_ALIAS_URL`, `HACK_SERVICE_NAME`, `HACK_SERVICE_URL`, and
`HACK_SERVICE_URLS`. The versioned JSON document includes all routable
services, avoiding lossy service-name-to-env-key conversion. Explicit
project env values retain precedence for backward compatibility.

## Verification

- `bun test` — 897 pass, 5 skip, 0 fail
- focused metadata/branch/run/exec/agent tests — 27 pass, 0 fail
- `bun run check`
- `bun run typecheck`
- `bun run build`
- Docker E2E `worktree-parallel-up` — primary and branch containers
expose distinct URLs; metadata survives restart

## Release decision

This is a user-facing runtime capability and should produce a
feature/minor release signal. The Conventional Commit title
intentionally uses `feat(runtime)`.

## Landing order

PR #65 should land first; then this branch should be updated from `main`
before merge so its `project.ts` changes include the completion-gate
fixes.

Author: roodboi

.codex/skills/hack-cli/SKILL.md

@@ -16,7 +16,7 @@ Use `hack` as the primary interface for local-first development.
 - At session start, audit project and global integrations with `hack setup sync --all-scopes --check`.
 - If anything is stale, missing, or deprecated, run `hack setup sync --all-scopes`, then reload the agent session so cached instructions are replaced.
 - Never copy or hand-edit generated Hack rules to refresh them; update the CLI and run the sync command.
-- Content revision: `eef2b0142b95` (version alone is not a freshness guarantee).
+- Content revision: `64098e5ae1ea` (version alone is not a freshness guarantee).
 
 ## Product boundary
 
@@ -154,6 +154,7 @@ Use `hack` as the primary interface for local-first development.
 - Use a branch instance when you need two versions running at once (PR review, experiments, migrations) or want to keep a stable environment while testing another branch.
 - Target one with `--branch <name>` on up/open/logs/down (for example: `hack up --branch <name> --detach`).
 - Linked worktrees pick a branch instance automatically (see Linked git worktrees).
+- Containers receive `HACK_RUNTIME_METADATA` plus `HACK_DEV_URL`, `HACK_ALIAS_URL`, and current-service URL fields derived from effective Caddy routes. Use Compose DNS for internal traffic and this metadata for browser-facing links, OAuth callbacks, and webhooks.
 
 ## Run commands inside services
 

.cursor/rules/hack.mdc

@@ -11,7 +11,7 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 - At session start, audit project and global integrations with `hack setup sync --all-scopes --check`.
 - If anything is stale, missing, or deprecated, run `hack setup sync --all-scopes`, then reload the agent session so cached instructions are replaced.
 - Never copy or hand-edit generated Hack rules to refresh them; update the CLI and run the sync command.
-- Content revision: `eef2b0142b95` (version alone is not a freshness guarantee).
+- Content revision: `64098e5ae1ea` (version alone is not a freshness guarantee).
 
 ## Product boundary
 

AGENTS.md

@@ -214,7 +214,7 @@ Integration freshness:
 - At session start, audit project and global integrations with `hack setup sync --all-scopes --check`.
 - If anything is stale, missing, or deprecated, run `hack setup sync --all-scopes`, then reload the agent session so cached instructions are replaced.
 - Never copy or hand-edit generated Hack rules to refresh them; update the CLI and run the sync command.
-- Content revision: `eef2b0142b95` (version alone is not a freshness guarantee).
+- Content revision: `64098e5ae1ea` (version alone is not a freshness guarantee).
 
 Product boundary:
 - Supported v3 surface: project init, up/down/restart, open, logs, env, host exec/shell, sessions, doctor, and daemon.
@@ -336,6 +336,7 @@ Branch instances (parallel envs):
 - Use a branch instance when you need two versions running at once (PR review, experiments, migrations) or want to keep a stable environment while testing another branch.
 - Target one with `--branch <name>` on up/open/logs/down (for example: `hack up --branch <name> --detach`).
 - Linked worktrees pick a branch instance automatically (see Linked git worktrees).
+- Containers receive `HACK_RUNTIME_METADATA` plus `HACK_DEV_URL`, `HACK_ALIAS_URL`, and current-service URL fields derived from effective Caddy routes. Use Compose DNS for internal traffic and this metadata for browser-facing links, OAuth callbacks, and webhooks.
 
 Run commands inside services:
 - One-off: `hack run <service> <cmd...>` (uses `docker compose run --rm`)

CLAUDE.md

@@ -84,7 +84,7 @@ Integration freshness:
 - At session start, audit project and global integrations with `hack setup sync --all-scopes --check`.
 - If anything is stale, missing, or deprecated, run `hack setup sync --all-scopes`, then reload the agent session so cached instructions are replaced.
 - Never copy or hand-edit generated Hack rules to refresh them; update the CLI and run the sync command.
-- Content revision: `eef2b0142b95` (version alone is not a freshness guarantee).
+- Content revision: `64098e5ae1ea` (version alone is not a freshness guarantee).
 
 Product boundary:
 - Supported v3 surface: project init, up/down/restart, open, logs, env, host exec/shell, sessions, doctor, and daemon.
@@ -206,6 +206,7 @@ Branch instances (parallel envs):
 - Use a branch instance when you need two versions running at once (PR review, experiments, migrations) or want to keep a stable environment while testing another branch.
 - Target one with `--branch <name>` on up/open/logs/down (for example: `hack up --branch <name> --detach`).
 - Linked worktrees pick a branch instance automatically (see Linked git worktrees).
+- Containers receive `HACK_RUNTIME_METADATA` plus `HACK_DEV_URL`, `HACK_ALIAS_URL`, and current-service URL fields derived from effective Caddy routes. Use Compose DNS for internal traffic and this metadata for browser-facing links, OAuth callbacks, and webhooks.
 
 Run commands inside services:
 - One-off: `hack run <service> <cmd...>` (uses `docker compose run --rm`)

docs/cli.md

@@ -158,6 +158,52 @@ Opt out:
 
 The primary checkout is unchanged: no `--branch` means the base instance.
 
+### Runtime host metadata
+
+Containers started by `hack up`, `hack restart`, and `hack run` receive the effective instance and
+public-route metadata. This keeps server-generated links, OAuth callbacks, webhooks, and other
+browser-facing URLs isolated when the same project runs in multiple worktrees.
+
+| Variable | Value |
+| --- | --- |
+| `HACK_BRANCH` | Effective branch slug, or an empty string for the base instance |
+| `HACK_COMPOSE_PROJECT` | Effective Compose project name |
+| `HACK_DEV_HOST` / `HACK_DEV_URL` | Effective root development host and HTTPS URL |
+| `HACK_ALIAS_HOST` / `HACK_ALIAS_URL` | Effective OAuth alias host and URL, when enabled |
+| `HACK_SERVICE_NAME` | Current Compose service name |
+| `HACK_SERVICE_URL` | Current service's first public URL, when routable |
+| `HACK_SERVICE_URLS` | JSON array of every public URL for the current service |
+| `HACK_RUNTIME_METADATA` | Versioned JSON document containing the instance hosts and every routable service's URL list |
+
+Example `HACK_RUNTIME_METADATA` for a branch instance:
+
+```json
+{
+  "version": 1,
+  "branch": "feature-x",
+  "composeProject": "demo--feature-x",
+  "hosts": {
+    "dev": "feature-x.demo.hack",
+    "alias": "feature-x.demo.hack.gy"
+  },
+  "services": {
+    "web": {
+      "urls": ["https://feature-x.demo.hack"]
+    },
+    "api": {
+      "urls": ["https://api.feature-x.demo.hack"]
+    }
+  }
+}
+```
+
+The service map is derived from effective Caddy routes; unroutable services are omitted. Use
+Compose DNS names such as `http://api:3000` for container-to-container traffic and runtime metadata
+only when a public/browser-reachable URL is required. Explicit project env values retain precedence
+over generated metadata for backward compatibility. Existing containers receive the contract after
+their next `hack up` or `hack restart`; `hack exec` observes the values already stored in the running
+container.
+
 Linked worktrees also inherit the project secret key automatically from the primary checkout
 through the shared git common dir, so you don't need to copy `.hack.secret.key` by hand. Set
 `HACK_ENV_SECRET_KEY` for CI or fully detached environments. `hack doctor` flags divergent secret

src/agents/instruction-source.ts

@@ -247,6 +247,7 @@ export const INSTRUCTION_SECTIONS: readonly InstructionSection[] = [
       "Use a branch instance when you need two versions running at once (PR review, experiments, migrations) or want to keep a stable environment while testing another branch.",
       "Target one with `--branch <name>` on up/open/logs/down (for example: `hack up --branch <name> --detach`).",
       "Linked worktrees pick a branch instance automatically (see Linked git worktrees).",
+      "Containers receive `HACK_RUNTIME_METADATA` plus `HACK_DEV_URL`, `HACK_ALIAS_URL`, and current-service URL fields derived from effective Caddy routes. Use Compose DNS for internal traffic and this metadata for browser-facing links, OAuth callbacks, and webhooks.",
     ],
   },
   {

src/agents/integration-revision.ts

@@ -3,4 +3,4 @@
  * source test recomputes this value and fails whenever guidance changes
  * without a revision update.
  */
-export const HACK_AGENT_INTEGRATION_CONTENT_REVISION = "eef2b0142b95";
+export const HACK_AGENT_INTEGRATION_CONTENT_REVISION = "64098e5ae1ea";