feat(open): prefer OAuth alias URLs

## Summary

- make OAuth alias hosts the automatic browser-facing default when OAuth
is enabled
- add project-level `open.prefer` and one-shot `hack open --prefer
<auto|alias|dev>` controls
- apply the preference consistently to service shorthand,
linked-worktree branch URLs, and `hack branch open`
- preserve explicit URLs and fully qualified hostnames exactly as
entered
- update generated config/schema, CLI reference, docs, and agent
guidance

## Why

Projects that enable OAuth need browser-facing `.hack.gy` aliases for
callbacks and shared cookie domains, while `dev_host` should remain the
stable primary routing identity. Previously `hack open` always returned
the primary `.hack` host, forcing applications and agents to reconstruct
or redirect to the alias themselves.

## User impact

With the default `open.prefer: auto`, `hack open` now opens the alias
whenever `oauth.enabled` is true and falls back to the dev host
otherwise. Users can pin either behavior in project config or override
one invocation. Container-to-container traffic remains on Compose DNS.

## Validation

- `bun run check`
- `bunx tsc -p packages/cli/tsconfig.json --noEmit`
- `bun run build`
- focused unit/documentation tests: 34 passed
- `bun tests/e2e/run.ts --only=worktree-branch-default`
- full unit suite: 915 passed, 5 skipped; the sole failure is the
existing sandbox-only `ps` EPERM in `daemon-command.test.ts`
- full local E2E: 8 scenarios passed; lifecycle process-table scenario
is likewise sandbox-blocked by `ps`

## Release signal

Feature change; publish as a minor release.

Author: roodboi

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

@@ -12,11 +12,11 @@ Use `hack` as the primary interface for local-first development.
 
 ## Integration freshness
 
-- These instructions were generated by hack CLI v3.3.6; treat cached rules from another version as potentially stale.
+- These instructions were generated by hack CLI v3.4.1; treat cached rules from another version as potentially stale.
 - 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: `64098e5ae1ea` (version alone is not a freshness guarantee).
+- Content revision: `902b04fe1469` (version alone is not a freshness guarantee).
 
 ## Product boundary
 
@@ -52,6 +52,7 @@ Use `hack` as the primary interface for local-first development.
 - Primary host comes from `dev_host` (default: `<project>.hack`).
 - Subdomain pattern is `<sub>.<dev_host>` (for example: `api.myapp.hack`).
 - OAuth alias (when enabled) also routes `<dev_host>.<tld>` and `<sub>.<dev_host>.<tld>` (default tld: `gy`).
+- Browser launches automatically prefer a routed OAuth alias when enabled; custom development hosts outside `.hack` stay on the primary host. Set `open.prefer` or pass `hack open --prefer <auto|alias|dev>` to override.
 - Not every compose service is routable: only services with Caddy labels and on `hack-dev` are exposed.
 - Required labels for HTTP services: `caddy`, `caddy.reverse_proxy`, `caddy.tls=internal`.
 - Quick checks: `hack open`, `hack open <sub>`, `hack open --json`.
@@ -70,7 +71,7 @@ Use `hack` as the primary interface for local-first development.
 - Source-of-truth files: `.hack/docker-compose.yml`, `.hack/hack.config.json`, `.hack/hack.env.default.yaml`, and optional `.hack/hack.env.<overlay>.yaml`.
 - Worktree-local env override files: `.hack/hack.env.local.yaml` and `.hack/hack.env.<overlay>.local.yaml`.
 - Local-only files: `.hack.secret.key`, optional `.hack/.env` compatibility output, `.hack/.env.state.json`, and `.hack/.internal/` (runtime/local machine state; keep gitignored).
-- Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.branch/compose.<branch>.override.yml`.
+- Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.internal/compose.runtime.override.yml`, `.hack/.branch/compose.<branch>.override.yml`, `.hack/.branch/compose.<branch>.runtime.override.yml`.
 - Managed via CLI: `.hack/.internal/extra-hosts.json` (use `hack internal extra-hosts ...` commands).
 - Lifecycle runtime files: `.hack/.internal/lifecycle/state.json`, `.hack/.internal/lifecycle/*.log`.
 - Ignore rules: hack owns a committed `.hack/.gitignore` (self-healing on init/up) covering machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`); keep it committed, and if generated files leaked into git, `hack doctor --fix` untracks them (files stay on disk).
@@ -104,7 +105,7 @@ Use `hack` as the primary interface for local-first development.
 - Command inside an already-running service container: `hack exec <service> -- <cmd...>`.
 - Host script that needs hack-stored env: `hack host exec --env <overlay> --scope <service> -- <cmd...>` — this is THE way to run repo scripts; never read .env files directly.
 - Interactive host shell with injected env: `hack host shell --env <overlay> --scope <service>`.
-- Call a service over HTTP (from the host or between containers): use its Caddy hostname `https://<sub>.<dev_host>`; discover routable URLs with `hack open --json`.
+- Browser/host URL: use `hack open <service> --json` (OAuth aliases are preferred when enabled). Container-to-container traffic should use Compose DNS.
 
 ## Logs (default is compose)
 

.cursor/rules/hack.mdc

@@ -7,11 +7,11 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 
 ## Integration freshness
 
-- These instructions were generated by hack CLI v3.3.6; treat cached rules from another version as potentially stale.
+- These instructions were generated by hack CLI v3.4.1; treat cached rules from another version as potentially stale.
 - 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: `64098e5ae1ea` (version alone is not a freshness guarantee).
+- Content revision: `902b04fe1469` (version alone is not a freshness guarantee).
 
 ## Product boundary
 
@@ -34,7 +34,7 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 - Source-of-truth files: `.hack/docker-compose.yml`, `.hack/hack.config.json`, `.hack/hack.env.default.yaml`, and optional `.hack/hack.env.<overlay>.yaml`.
 - Worktree-local env override files: `.hack/hack.env.local.yaml` and `.hack/hack.env.<overlay>.local.yaml`.
 - Local-only files: `.hack.secret.key`, optional `.hack/.env` compatibility output, `.hack/.env.state.json`, and `.hack/.internal/` (runtime/local machine state; keep gitignored).
-- Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.branch/compose.<branch>.override.yml`.
+- Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.internal/compose.runtime.override.yml`, `.hack/.branch/compose.<branch>.override.yml`, `.hack/.branch/compose.<branch>.runtime.override.yml`.
 - Managed via CLI: `.hack/.internal/extra-hosts.json` (use `hack internal extra-hosts ...` commands).
 - Lifecycle runtime files: `.hack/.internal/lifecycle/state.json`, `.hack/.internal/lifecycle/*.log`.
 - Ignore rules: hack owns a committed `.hack/.gitignore` (self-healing on init/up) covering machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`); keep it committed, and if generated files leaked into git, `hack doctor --fix` untracks them (files stay on disk).
@@ -61,7 +61,7 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 - Command inside an already-running service container: `hack exec <service> -- <cmd...>`.
 - Host script that needs hack-stored env: `hack host exec --env <overlay> --scope <service> -- <cmd...>` — this is THE way to run repo scripts; never read .env files directly.
 - Interactive host shell with injected env: `hack host shell --env <overlay> --scope <service>`.
-- Call a service over HTTP (from the host or between containers): use its Caddy hostname `https://<sub>.<dev_host>`; discover routable URLs with `hack open --json`.
+- Browser/host URL: use `hack open <service> --json` (OAuth aliases are preferred when enabled). Container-to-container traffic should use Compose DNS.
 
 ## Lifecycle + startup
 

AGENTS.md

@@ -210,11 +210,11 @@ Most formatting and common issues are automatically fixed by Biome. Run `bun x u
 Use `hack` as the single interface for local-first runtime orchestration (compose, DNS/TLS, logs, env, and persistent project workspaces).
 
 Integration freshness:
-- These instructions were generated by hack CLI v3.3.6; treat cached rules from another version as potentially stale.
+- These instructions were generated by hack CLI v3.4.1; treat cached rules from another version as potentially stale.
 - 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: `64098e5ae1ea` (version alone is not a freshness guarantee).
+- Content revision: `902b04fe1469` (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.
@@ -245,6 +245,7 @@ Hostname routing + Caddy labels:
 - Primary host comes from `dev_host` (default: `<project>.hack`).
 - Subdomain pattern is `<sub>.<dev_host>` (for example: `api.myapp.hack`).
 - OAuth alias (when enabled) also routes `<dev_host>.<tld>` and `<sub>.<dev_host>.<tld>` (default tld: `gy`).
+- Browser launches automatically prefer a routed OAuth alias when enabled; custom development hosts outside `.hack` stay on the primary host. Set `open.prefer` or pass `hack open --prefer <auto|alias|dev>` to override.
 - Not every compose service is routable: only services with Caddy labels and on `hack-dev` are exposed.
 - Required labels for HTTP services: `caddy`, `caddy.reverse_proxy`, `caddy.tls=internal`.
 - Quick checks: `hack open`, `hack open <sub>`, `hack open --json`.
@@ -261,7 +262,7 @@ Project files (managed vs generated):
 - Source-of-truth files: `.hack/docker-compose.yml`, `.hack/hack.config.json`, `.hack/hack.env.default.yaml`, and optional `.hack/hack.env.<overlay>.yaml`.
 - Worktree-local env override files: `.hack/hack.env.local.yaml` and `.hack/hack.env.<overlay>.local.yaml`.
 - Local-only files: `.hack.secret.key`, optional `.hack/.env` compatibility output, `.hack/.env.state.json`, and `.hack/.internal/` (runtime/local machine state; keep gitignored).
-- Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.branch/compose.<branch>.override.yml`.
+- Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.internal/compose.runtime.override.yml`, `.hack/.branch/compose.<branch>.override.yml`, `.hack/.branch/compose.<branch>.runtime.override.yml`.
 - Managed via CLI: `.hack/.internal/extra-hosts.json` (use `hack internal extra-hosts ...` commands).
 - Lifecycle runtime files: `.hack/.internal/lifecycle/state.json`, `.hack/.internal/lifecycle/*.log`.
 - Ignore rules: hack owns a committed `.hack/.gitignore` (self-healing on init/up) covering machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`); keep it committed, and if generated files leaked into git, `hack doctor --fix` untracks them (files stay on disk).
@@ -291,7 +292,7 @@ Running things (decision guide):
 - Command inside an already-running service container: `hack exec <service> -- <cmd...>`.
 - Host script that needs hack-stored env: `hack host exec --env <overlay> --scope <service> -- <cmd...>` — this is THE way to run repo scripts; never read .env files directly.
 - Interactive host shell with injected env: `hack host shell --env <overlay> --scope <service>`.
-- Call a service over HTTP (from the host or between containers): use its Caddy hostname `https://<sub>.<dev_host>`; discover routable URLs with `hack open --json`.
+- Browser/host URL: use `hack open <service> --json` (OAuth aliases are preferred when enabled). Container-to-container traffic should use Compose DNS.
 
 Logs (default is compose):
 - Fast tail: `hack logs --pretty`

CLAUDE.md

@@ -80,11 +80,11 @@ This project uses Obsidian for project context, specs, research, and progress tr
 Use `hack` as the single interface for local-first runtime orchestration (compose, DNS/TLS, logs, env, and persistent project workspaces).
 
 Integration freshness:
-- These instructions were generated by hack CLI v3.3.6; treat cached rules from another version as potentially stale.
+- These instructions were generated by hack CLI v3.4.1; treat cached rules from another version as potentially stale.
 - 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: `64098e5ae1ea` (version alone is not a freshness guarantee).
+- Content revision: `902b04fe1469` (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.
@@ -115,6 +115,7 @@ Hostname routing + Caddy labels:
 - Primary host comes from `dev_host` (default: `<project>.hack`).
 - Subdomain pattern is `<sub>.<dev_host>` (for example: `api.myapp.hack`).
 - OAuth alias (when enabled) also routes `<dev_host>.<tld>` and `<sub>.<dev_host>.<tld>` (default tld: `gy`).
+- Browser launches automatically prefer a routed OAuth alias when enabled; custom development hosts outside `.hack` stay on the primary host. Set `open.prefer` or pass `hack open --prefer <auto|alias|dev>` to override.
 - Not every compose service is routable: only services with Caddy labels and on `hack-dev` are exposed.
 - Required labels for HTTP services: `caddy`, `caddy.reverse_proxy`, `caddy.tls=internal`.
 - Quick checks: `hack open`, `hack open <sub>`, `hack open --json`.
@@ -131,7 +132,7 @@ Project files (managed vs generated):
 - Source-of-truth files: `.hack/docker-compose.yml`, `.hack/hack.config.json`, `.hack/hack.env.default.yaml`, and optional `.hack/hack.env.<overlay>.yaml`.
 - Worktree-local env override files: `.hack/hack.env.local.yaml` and `.hack/hack.env.<overlay>.local.yaml`.
 - Local-only files: `.hack.secret.key`, optional `.hack/.env` compatibility output, `.hack/.env.state.json`, and `.hack/.internal/` (runtime/local machine state; keep gitignored).
-- Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.branch/compose.<branch>.override.yml`.
+- Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.internal/compose.runtime.override.yml`, `.hack/.branch/compose.<branch>.override.yml`, `.hack/.branch/compose.<branch>.runtime.override.yml`.
 - Managed via CLI: `.hack/.internal/extra-hosts.json` (use `hack internal extra-hosts ...` commands).
 - Lifecycle runtime files: `.hack/.internal/lifecycle/state.json`, `.hack/.internal/lifecycle/*.log`.
 - Ignore rules: hack owns a committed `.hack/.gitignore` (self-healing on init/up) covering machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`); keep it committed, and if generated files leaked into git, `hack doctor --fix` untracks them (files stay on disk).
@@ -161,7 +162,7 @@ Running things (decision guide):
 - Command inside an already-running service container: `hack exec <service> -- <cmd...>`.
 - Host script that needs hack-stored env: `hack host exec --env <overlay> --scope <service> -- <cmd...>` — this is THE way to run repo scripts; never read .env files directly.
 - Interactive host shell with injected env: `hack host shell --env <overlay> --scope <service>`.
-- Call a service over HTTP (from the host or between containers): use its Caddy hostname `https://<sub>.<dev_host>`; discover routable URLs with `hack open --json`.
+- Browser/host URL: use `hack open <service> --json` (OAuth aliases are preferred when enabled). Container-to-container traffic should use Compose DNS.
 
 Logs (default is compose):
 - Fast tail: `hack logs --pretty`

docs/architecture.md

@@ -62,7 +62,8 @@ graph LR
 
 - Project scope (`.hack`)
   - `docker-compose.yml` defines services + Caddy labels
-  - `hack.config.json` stores project name, dev host, log preferences, OAuth alias
+  - `hack.config.json` stores project name, dev host, log preferences, OAuth alias, and browser
+    launch preference (`open.prefer`)
   - `controlPlane.gateway.enabled` marks the project as gateway-capable
   - Optional overrides:
     - `.internal/compose.override.yml` (generated internal DNS/TLS injection)
@@ -321,9 +322,11 @@ one, or set `worktree.auto_branch=false` to opt into the base instance explicitl
   - `.env` (optional, only when explicitly materialized)
   - `.internal/compose.override.yml`
   - `.internal/compose.env.override.yml`
+  - `.internal/compose.runtime.override.yml`
   - `.internal/extra-hosts.json`
   - `.internal/lifecycle/state.json` and `.internal/lifecycle/*.log`
   - `.branch/compose.<branch>.override.yml`
+  - `.branch/compose.<branch>.runtime.override.yml`
 
 ## Key design choices