hack-dance · roodboi · Jul 10, 2026 · Jul 10, 2026 · Jul 10, 2026 · Jul 10, 2026
diff --git a/.codex/skills/hack-cli/SKILL.md b/.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
 

diff --git a/.cursor/rules/hack.mdc b/.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
 

diff --git a/AGENTS.md b/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`)

diff --git a/CLAUDE.md b/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`)

diff --git a/docs/cli.md b/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

diff --git a/src/agents/instruction-source.ts b/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.",
     ],
   },
   {

diff --git a/src/agents/integration-revision.ts b/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";