<!-- Original: docs/env.md; revision: 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; SHA-256: 20390c487a179fd03e4ba9512f44b74fc304c713e0c6bf6265140481e0ae1b6a; URL: https://hack.foo/docs/v5/env -->
# Env & secrets

Hack now uses repo-level env overlay files as the canonical project env model.

The short version:

- commit `.hack/hack.env.default.yaml`
- optionally commit `.hack/hack.env.<overlay>.yaml`
- use `.hack/hack.env.local.yaml` and `.hack/hack.env.<overlay>.local.yaml` for worktree-local overrides
- keep `.hack.secret.key` out of git, or provide `HACK_ENV_SECRET_KEY`
- let `hack up`, `hack run`, `hack restart`, `hack host exec`, `hack host shell`, and env-aware session flows inject values directly at runtime
- use `hack env materialize` only when you explicitly need a compatibility `.hack/.env`

## Current model

Canonical env state lives at the repo root:

- `.hack/hack.env.default.yaml`
- `.hack/hack.env.<overlay>.yaml`
- `.hack/hack.env.local.yaml`
- `.hack/hack.env.<overlay>.local.yaml`

Legacy compatibility note:

- if an older repo already tracks `.hack/hack.env.local.yaml` as the shared `--env local` overlay, Hack keeps reading that file as the shared overlay
- in that compatibility case, worktree-local default overrides are written to `.hack/hack.env.default.local.yaml` so `--local` mutations do not overwrite tracked shared config

Compatibility and local-only state still lives under `.hack/`:

- `.hack/.env`
- `.hack/.env.state.json`
- `.hack/.internal/...`

Encryption key material is local-only by default:

- `.hack.secret.key`
- or `HACK_ENV_SECRET_KEY`

`hack init` now scaffolds `.hack/hack.env.default.yaml` by default.

## Ignore rules (committed `.hack/.gitignore`)

Hack owns a committed `.hack/.gitignore` that keeps machine-local generated
files out of git. Because the file is committed, fresh clones and linked git
worktrees inherit the rules with zero setup. It covers (patterns relative to
`.hack/`):

- `.internal/`
- `.branch/`
- `.env`
- `.env.state.json`
- `hack.env.local.yaml`
- `hack.env.*.local.yaml`
- `.hack.env*.tmp` (staging files an interrupted env write can leave behind)
- `tickets/` (retained only to contain retired machine-local ticket caches during upgrades)

How it is maintained:

- created by `hack init` for a new project, and refreshed when you write
  machine-local env overrides (`hack env set --local`, `hack env hydrate`)
- in an existing project without it (for example one an earlier Hack version
  initialized), `hack doctor` reports the "hack gitignore" check as a warning,
  and `hack doctor --fix` creates the file, or restores its managed block,
  as its own step. Commit the result so fresh clones and worktrees get the
  rules. `hack init` does not repair an existing project unless you confirm
  overwriting its scaffold files. Hack never writes
  through a symlinked `.hack/.gitignore` or `.hack/` (including a `.hack/`
  that links outside the repository); doctor reports that case and leaves it
  alone. Doctor asks git about the project root (the directory that holds
  `.hack/`), not about `.hack/` itself. So when the project root is not a git
  checkout, the check reports "Skipped (not a git checkout)" even if `.hack/`
  links into another repository; Hack still refuses to write through that
  link.
- a read-only `.hack/.gitignore` is never replaced, the same policy as for
  `info/exclude`. A file with no write permission bit (for example mode 0444)
  is read-only for every user, root included; otherwise Hack asks the
  operating system whether you may write it. Hack checks the mode bits first,
  so an access control list (ACL) that grants you write access to a 0444 file
  does not make it writable for Hack; add a write bit instead. When it lacks
  the managed block, `hack doctor` warns and names the fix (make it writable,
  then run
  `hack doctor --fix`), and `--fix` leaves it unchanged. `hack env set --local`
  and `hack env hydrate` still write the local layer, print the same warning
  on stderr (so `--json` output on stdout stays valid JSON), and leave the
  file unchanged. Interactive `hack init` that overwrites an existing scaffold
  prints the same warning and leaves the file unchanged. A read-only file that
  already has the block is fine.
- runtime commands (`hack up`, `down`, `restart`, `run`, `exec`) never write
  into your working tree to set up ignores, so they leave `git status`
  unchanged. Before they write `.hack/.internal/` or `.hack/.branch/` files,
  they add the same patterns, anchored at the repository root, to a marked
  block in the repository's `info/exclude` (resolved with
  `git rev-parse --git-common-dir`, so one block covers every linked
  worktree). Env commands that write `.hack/.env` (`hack env set` without an
  env config, `hack env materialize`) do the same. That file is local to your
  clone and never committed. The update
  is best-effort: if git is unavailable, or `info/` or `info/exclude` is a
  symlink or not writable, Hack leaves it alone and the command still runs.
  "Not writable" follows the `.hack/.gitignore` rule above: an `info/exclude`
  with no write permission bit is left alone even for root or when an ACL
  grants write.
- never commit `.hack/.internal/`: it holds machine-local generated state that
  runtime commands rewrite. If it is tracked, `hack doctor --fix` untracks it.
- the entries live inside a marked, hack-managed block; anything you add
  outside the markers is preserved on every rewrite
- the root `.gitignore` still gets a `.hack.secret.key` entry when the secret
  key is first generated (the key lives at the repo root, not under `.hack/`).
  Hack writes that entry before the key, so if the entry cannot be written, no
  key is created. Before a `--secret` set or hydrate uses an existing
  checkout-local key that git does not ignore, Hack adds the entry; if it
  cannot, or a later rule re-includes the key, the command is refused and
  nothing is encrypted with that key. The refusal names the cause: either the
  entry could not be written, or the file already lists the key and a later
  rule (such as `!.hack.secret.key`) re-includes it, which you need to remove
- outside git there is nothing to commit, so an existing key does not need the
  entry and Hack does not recreate a deleted root `.gitignore` for it. Hack
  does not run when you later turn the directory into a repository with
  `git init`, so it cannot add the entry at that moment. If the entry is
  missing then, `hack doctor` reports `env-key-unignored` (see
  [Key strength and exposure](#secret-key-handling)), and the first `--secret` set or
  hydrate in the new repository adds the entry before it uses the key, or is
  refused
- older repos that added `.hack/.internal/` to the root `.gitignore` keep
  working; the entries are equivalent and nothing is removed

Leak detection and repair:

- `hack doctor` runs a "generated files" check: it lists any of the paths
  above (including retired `.hack/tickets/` caches, plus `.hack.secret.key`) that are tracked in git, except a tracked
  `.hack/hack.env.local.yaml`, which is never flagged because older repos may
  intentionally track it as the shared `--env local` overlay (see the legacy
  compatibility note above)
- a tracked `.hack.secret.key` is reported as an error — it is a committed
  secret; rotate it after untracking
- `hack doctor --fix` untracks the offenders with `git rm --cached` (files
  stay on disk) and re-ensures `.hack/.gitignore`; commit the removal
- `--fix` and `--migrate-env-config` cannot be combined with `--json`; run the repair and JSON audit separately so a mutating request is never silently ignored.
  run them separately from a JSON-mode invocation

## File format

Each env file is YAML with:

- `version: 1`
- `environment`
- `secretsprovider: project_key`
- `values`

`values` is split by scope:

- `global`: values applied everywhere
- `<service>`: values applied only for that compose service
- `host`: optional overrides applied to host execution (`hack host exec`, `hack host shell`, and lifecycle hooks/processes)

Example:

```yaml
version: 1
environment: default
secretsprovider: project_key
values:
  global:
    GLOBAL_FLAG: "true"
    API_BASE_URL: "https://api.example.com"
  api:
    PORT: "4000"
    SERVICE_TOKEN:
      secure: v1:...
```

Plaintext values are written as scalars. Secret values are written as `{ secure: ... }`.

## Merge rules

Hack resolves env in this order:

1. load `.hack/hack.env.default.yaml`
2. if `--env=<name>` is selected, load `.hack/hack.env.<name>.yaml`
3. in a linked git worktree, load the primary checkout's `.hack/hack.env.local.yaml`
4. if `--env=<name>` is selected, load the primary checkout's `.hack/hack.env.<name>.local.yaml`
5. load this checkout's `.hack/hack.env.local.yaml`
6. if `--env=<name>` is selected, load this checkout's `.hack/hack.env.<name>.local.yaml`
7. merge `values.global`
8. if a service scope is requested, merge `values.<service>` on top

Worktree-local overrides win over shared repo overlays. Service values override global values.
Primary local overlays are read live, without copying or creating files. Checkout-local
overrides always win over primary local overlays; `hack env set --local` writes only to
the current checkout. Inheritance is disabled by `CI=1` or `CI=true`,
`HACK_EXECUTION_MODE=slim` or `codex`, `HACK_WORKTREE_INHERIT_LOCAL=0` (also
`false`, `off`, or `no`), or `"worktree": { "inherit_local": false }` in
`.hack/hack.config.json`. Symlinked primary project directories are ignored;
symlinked, non-regular, or unreadable primary local files are rejected, and an
unreadable `.hack/hack.config.json` in a linked worktree is an error rather than a
silent opt-in. Checkout paths containing newlines never inherit. A worktree
whose only env input is an inherited overlay still uses the YAML commands. If every
input of a materialized `.hack/.env` later disappears (including by opting out),
`hack doctor` reports the output as obsolete.

Host execution applies `host` values last. This includes `hack host exec`, `hack host shell`,
and lifecycle hooks/processes, which all run on the host rather than in Compose.

Projects can set a default overlay in `.hack/hack.config.json`:

```json
{
  "env": {
    "defaultOverlay": "qa"
  }
}
```

Use `--env=base` to bypass that default and read only `.hack/hack.env.default.yaml`
(plus local overrides). `default` and `none` are aliases for `base`, in any case, on every
command that accepts `--env`; an overlay file named after one of those spellings is never
selected by name. Any other value must already be a canonical overlay name: lowercase
letters and digits joined by single hyphens (`^[a-z0-9]+(-[a-z0-9]+)*$`, for example
`qa` or `qa-2`), at most 128 characters long; surrounding whitespace is ignored. Hack
never rewrites a requested name, so `QA`, `q_a`, `X=1` or a name longer than 128
characters is refused with a fixed `Invalid --env value.` message (`E_USAGE` under
`--json`) that does not repeat the argument, before any project file is read or any
child process starts. The limit keeps every file name Hack derives from the overlay
name, such as the layer's lock, within the usual 255-byte file name limit.
See the [command and delivery matrix](#command-and-delivery-matrix) for what each command
does with the selection.

## Metadata-only planning API

Repository integrations can call `resolveProjectEnvMetadata` from
`src/lib/project-env-config.ts` to inspect modern env bindings without obtaining a
key or decrypting values. Pass `projectRoot`, `projectDir`, and `serviceNames`;
optional `envName` selects an overlay, omission uses the project default, and
`null` bypasses that default.

The result contains selection and file paths, declared and unknown scope names,
and per-target key metadata (`scope` and `secret`) for Compose and host execution.
It contains no plaintext values, ciphertext, merged config, or raw layers. It
reads the same ordered files and uses the same scope projection as
`resolveProjectEnvConfig`: later layers override earlier ones, null removes an
earlier binding, and a later value can reintroduce it. Linked worktrees inherit
primary local layers before their own local overrides, subject to the existing
inheritance settings. If a service is named `host`, that scope remains a service
scope rather than an override applied to every host target.

A `null` result means no modern env configuration exists; it does not inspect or
resolve legacy `.env` or secret-store values. Callers retain responsibility for
their existing legacy fallback. Selected managed-env layer reads distinguish a
missing path from a failed read or a dangling symlink. Only regular files
(including readable symlinks to regular files inside the real project root) are read;
invalid or unreadable layers throw a value-free error without YAML excerpts or a nested cause. Project configuration
selection keeps its existing semantics. Metadata inspection never writes key
files or materializes `.env`.

Paths, variable names and scope names can still disclose private project details;
keep this metadata private. It is not portable plan serialization or an atomic
snapshot/admission check. It does not establish that encrypted values can be
decrypted or that runtime injection will succeed.

## Runtime behavior

Direct runtime injection is the default path.

Hack reads the canonical YAML files and injects the resolved env directly into:

- `hack up`
- `hack run`
- `hack restart`
- lifecycle host processes
- `hack host exec`
- `hack host shell`
- `hack session start --env ... --service ...`
- `hack session exec --env ... --service ...`

That means `.hack/.env` is no longer the primary runtime source of truth.

On the Compose backend, Hack still generates `.hack/.internal/compose.env.override.yml`
so each service gets its own environment. The file holds no values: each entry is a
`${HACK_ENV_<digest>_<KEY>}` reference, and Hack passes the resolved values to
`docker compose` through its process environment. Nothing Hack writes there contains a
decrypted value, whether `up` succeeds, fails or is interrupted. The file is written
with mode 0600, and Hack refuses to write through a symlink at that path. A value
reaches the container literally, `$` included.

Only the `docker compose` invocations that read the override (`up`, `run`, `exec`,
`ps` and the dependency cache initialization) receive the `HACK_ENV_*` values. The other
`docker` commands Hack runs around Compose, such as `docker inspect`, `docker logs` and
`docker events` for dependency cache progress and reuse, get the same environment
without them.

Because the file holds only references, a `docker compose -f
.hack/.internal/compose.env.override.yml ...` command run outside Hack (a script, an IDE
integration or a test harness) gets a blank value for every managed variable, with only a
per-variable warning from Compose. Use `hack run` or `hack exec`, or supply the same
`HACK_ENV_*` variables to that command.

A value that a service gets from the global scope uses one `HACK_ENV_*` reference shared
by every such service. A key that a service scope sets keeps a reference of its own for
that service. The Compose client environment therefore grows with the distinct values,
not with services times keys: twenty services that share one 64 KiB global value add
about 64 KiB, not 1.25 MiB. The choice follows which scope sets each key, so the
override file still holds no value. One safety check does compare values: if a key that
the resolved scopes call global has a value for a service that differs from the global
value, that service keeps a reference of its own for the key, so the container still gets
its own value. In that case the file shows that the service's value differs from the
global value, but never the value itself or its length. With a normal env config the
scopes and values come from the same resolution and always agree, so this check never
changes the file. Compose also receives each global
value under its own name for `${KEY}` interpolation in your Compose file, so a global
value reaches the `docker compose` process twice.

The operating system limits the arguments and environment of a new process (`ARG_MAX`):
1 MiB in total on macOS, and on Linux a quarter of the stack size limit (2 MiB with the
default 8 MiB stack, at most 6 MiB), plus 128 KiB (`MAX_ARG_STRLEN`) for a single
`NAME=value` string. Hack measures the environment the `docker compose` process would
get (your shell environment plus the managed values) before it writes the override or
starts Compose. It keeps 64 KiB for the Compose arguments. When the environment does not
fit, `up`, `restart`, `run` and `exec` fail with `E_ENV_TOO_LARGE`. The message and the
`--json` detail name the limit (`ARG_MAX` or `MAX_ARG_STRLEN`) and give byte counts only,
never a name or a value. To fix it, make large values smaller or remove them (for
example, mount a large credential as a file and pass its path), set a value once in the
global scope instead of in each service scope, or unset large variables in the shell
that runs `hack`.

When you upgrade from an earlier version, read the two subsections at the end of this
section: managed values that contain `$` now reach containers differently, and an
override written by the earlier version can still hold values.

`hack env materialize` is manual by design. Use it only when you need a compatibility file for an external tool that expects `.env` on disk.

Hack writes `.hack/.env` and `.hack/.env.<overlay>` (from `materialize`, legacy
`hack env set`, and the daemon env route) with mode `0600` by atomic replace: a
private temporary file in `.hack/` is written, fsynced and renamed over the target,
so readers never see a partial file. An existing file with group or other access is
tightened to `0600` even when its contents are unchanged. These write and update paths
refuse, with a fixed message that names no file or value, an env file that is a symlink
(including a dangling one) or not a regular file, or one whose `.hack` directory is a
symlink. Replace the link with a regular file or directory to continue. Code paths
that only read an env file do not apply this check and still follow a symlink.

For host execution, `hack host exec`, `hack host shell`, and lifecycle hooks/processes use a host-local view.
That means Hack prefers host-usable values when it can:

- explicit `host` scope values override the normal `global` + `<service>` merge
- common container-only hostnames such as `host.docker.internal` and compose service hosts are rewritten to `127.0.0.1`

Use `--target compose` if you explicitly want the container-oriented compose view instead.

### Upgrading: managed values that contain `$`

Earlier versions wrote each value into the override literally, so Compose interpolated
a `$` inside a managed value: `$VAR` and `${VAR}` became the host or Compose value of
`VAR` (blank when unset), and `$$` became `$`. Now Compose substitutes each reference
once and does not interpolate the value, so the container receives the value exactly as
stored, `$` included. If a managed value contains `$`:

- the container sees a different value after the upgrade, and the next `hack up`
  recreates that service's containers because their configuration changed;
- a value that relied on interpolation (for example `${HOME}/data`) now reaches the
  container unexpanded; store the expanded value instead;
- a value that escaped `$` as `$$` now reaches the container as `$$`; store a single `$`.

Values without `$` reach containers unchanged, and their containers are not recreated.

### Overrides from earlier versions

An override written by an earlier Hack version can still hold literal values. The next
`hack up`, `hack restart`, `hack run` or `hack exec` replaces it or, when it renders no
override, removes it. `hack down` removes it before its lifecycle hooks, the remote target
or `docker compose down` run, so a failed hook, a remote target or a failed Compose down
does not keep it. `hack doctor` reports such a file in its "compose env at rest" check
(counts only, never values), and `hack doctor --fix` removes it.

A legacy adoption (`hack config adopt`) pins the override's exact bytes and file
identity for as long as the adoption exists, and adopted commands never rewrite it. So:

- `hack config adopt`, `hack config adopt --stop` and `hack config adopt --dry-run`
  refuse a literal override before they prepare anything. Run `hack up` once so Hack
  rewrites it with references, then adopt.
- A preparation that an earlier version made over a literal override is never
  published. If it has no interrupted stop or pending switch, doctor names
  `hack up` followed by `hack config adopt --stop`: there is no active adoption to roll
  back, and `hack up` starts the originals. For an interrupted stop, `hack config adopt --recover --stop` (which retries
  the stop, then publishes) and `hack config adopt --recover` (which completes a pending switch) refuse
  before any original file moves. The switch stays journaled as pending, and the error
  names `hack config adopt --recover --rollback` as the step that releases it. After that
  rollback, run `hack up` and adopt again.
- An active adoption made by an earlier version over a literal override keeps that file. Hack
  never removes it while a prepared, active or pending adoption exists, because removal
  would make the adoption refuse to load. `hack doctor` reports it with this next step.
  To drop the values, stop the adopted containers (`hack down`), run
  `hack config adopt --rollback`, run `hack up` so Hack rewrites the file with references,
  then adopt again with `hack config adopt --stop`.

A removal first moves the file aside, then checks what it moved. If a concurrent Hack
command had just replaced it with a value-free file, that file is put back rather than
deleted. Between the move and the put-back the path is briefly absent, so a Compose
command started by that concurrent Hack command at that moment can fail to find it; run
the command again. If Hack is killed between the move and the delete, the moved file
(`.hack/.internal/.compose.env.override.yml.<id>.remove`) can hold values. `hack doctor`
reports such files by count, and the next removal, `hack doctor --fix`, or `hack up`,
`hack restart`, `hack run` or `hack exec` deletes each one once it is more than a minute
old. A newer one may belong to a removal that is still running, so it is left alone.

Every step that touches the override first checks, without following a symlink, that
`.hack` and `.hack/.internal` are real directories and that the override is a regular
file; a step that moves or deletes something checks the directories again first. If
`.hack`, `.hack/.internal` or the override is a symlink or not a regular file or
directory, a Compose command that renders the override refuses with a fixed message,
and `hack doctor` reports a fixed refusal that names no value. Neither `hack doctor --fix`,
a removal nor the sweep of leftover `.remove` files lists, reads, moves or deletes
anything behind the link. Replace the link with a regular directory or file.

## Choosing the right execution surface

- `hack host exec` / `hack host shell`: run on your host machine with Hack-resolved env injected.
- `hack run <service> ...`: run a one-off command in the compose network with an ephemeral service container.
- `hack exec <service> ...`: run inside an already-running container when you specifically need that container's live filesystem or process context.

For host execution, `--scope` means "which env scope should Hack inject", not "where should this run."
For example, `hack host exec --scope api -- bun db:migrate` still runs on the host.

## Command and delivery matrix

Every command that accepts `--env` resolves it with the same rule: omitted selects
the configured default overlay (`env.defaultOverlay`); `base`, `default` or `none`
selects base layers only; any other value must be a canonical overlay name and selects
that overlay. The table lists every such command; `tests/env-command-matrix.test.ts`
fails when a command gains or loses `--env` without a matching row, or when a row's selectors
drift from the CLI. Commands not listed here refuse `--env` as an option that is not
valid for them (arguments after a standalone `--` belong to the child command).

The **Selectors** column lists the env-related flags each command accepts.
`--service` selects a Compose service scope, `--scope` selects the env scope injected
into a host command, and `--target` on env and host commands chooses the `host` or
`compose` env view. On `up`, `down` and `restart`, `--target` is execution routing
(`auto|local|remote`), not an env view.

| Command | Selectors | Resolution timing | Refresh path | Native and compose limits |
| --- | --- | --- | --- | --- |
| `hack up` | `--env`, `--target` | Once, when services are created; values go into Compose containers and lifecycle hooks/processes, and the selection is recorded for the running stack. | `hack restart` or `hack env apply --service <service>`; editing env files does not change running containers. | Authored native projects receive the same selection before dispatch. |
| `hack down` | `--env`, `--target` | At teardown, for lifecycle down hooks only; omitted reuses a named overlay recorded for the running stack, else the configured default. | None; nothing is delivered to containers. | The native runtime backend refuses `--env`. |
| `hack restart` | `--env`, `--target` | When services are recreated; omitted reuses a named overlay recorded for the running stack, else the configured default, and an explicit `--env` (including `base`) wins. | This is the refresh path for the whole stack or the named services. | Authored native projects receive the same selection before dispatch. |
| `hack run` | `--env` | Per invocation, for the new one-off container. | Each run resolves again. | The native runtime backend refuses `--env`; restart with the selection first. |
| `hack exec` | `--env` | Checked at invocation against the env recorded for the running stack; the command runs with the env the container was created with. Compose exec and native-runtime exec (Compose-file and authored native projects) warn on stderr when the service's resolved env changed since it started. | `hack restart <service>` (or `hack restart --env <name>`); native projects restart as a whole with `hack restart` | Compose refuses when the requested env differs from the env recorded for the running stack; the native runtime backend refuses `--env`. |
| `hack env list` | `--env`, `--service` | Per invocation, read-only; secret values are masked unless `--show-secrets`. | Not needed. | Reads files; no runtime required. |
| `hack env get` | `--env`, `--service` | Per invocation; prints exactly one plaintext value to stdout. | Not needed. | Reads files; refuses native project inputs. |
| `hack env explain` | `--env`, `--service`, `--target` | Per invocation; reports source, precedence and delivery without the value. | Not needed. | Reads files; no runtime required. |
| `hack env apply` | `--env`, `--service` | Runs `hack restart <service>` with the same `--env`, recreating one service. | This is the refresh path for one service. | `--service` is required. |
| `hack env add` | `--env`, `--service` | Selects the file written (`hack.env.<name>.yaml`, or the base file for `base`/`default`/`none`; `--local` writes the local variant). | Running workloads keep old values until `hack env apply` or `hack restart`. | Mutates only env files. |
| `hack env set` | `--env`, `--service` | Alias for `hack env add`, except that it refuses a dangling layer link. | Same as `hack env add`. | Mutates only env files. |
| `hack env hydrate` | `--env`, `--service` | Selects the local file written, as for `hack env add --local`; imports every entry in one commit. | Same as `hack env add`. | Mutates only the machine-local env file; refuses a git-tracked one. |
| `hack env unset` | `--env`, `--service` | Selects the file the key is removed from, as for `hack env add`. | Same as `hack env add`. | Mutates only env files. |
| `hack env materialize` | `--env`, `--service` | Writes `.hack/.env` once, at invocation. | Rerun `hack env materialize`. | Compatibility output for external tools; runtime injection does not depend on it. |
| `hack env exec` | `--env`, `--service`, `--target` | Per invocation, into one host command (host view by default). | Each invocation resolves again. | Runs on the host, not in a container. |
| `hack env shell` | `--env`, `--service`, `--target` | When the shell starts. | Start a new shell. | Runs on the host, not in a container. |
| `hack host exec` | `--env`, `--scope`, `--target` | Per invocation, into one host command (host view by default). | Each invocation resolves again. | Runs on the host, not in a container. |
| `hack host shell` | `--env`, `--scope`, `--target` | When the shell starts. | Start a new shell. | Runs on the host, not in a container. |
| `hack config validate` | `--env` | Per invocation; resolves the native selection without reading managed env documents. | Not needed. | Authored native projects only; cannot be combined with `--file`. |
| `hack config plan` | `--env` | Per invocation; metadata only (names, scopes, secret flags), never decrypted. | Not needed. | Authored native projects only. |
| `hack project target` | `--env`, `--service` | Per invocation, read-only; reports the overlay selection (explicit, project default or base) without reading env files or values. | Not needed. | Selection only: overlay existence is not checked; no runtime required. |
| `hack project task list` | `--env` | Per invocation, read-only; selects the overlay that each recipe's reviewed env scope is compared with, without reading env files or values. | Not needed. | Selection only; lists recipes and runs nothing, so no runtime is required. |
| `hack project task inspect` | `--env` | Per invocation, read-only; as for `hack project task list`, for one recipe. | Not needed. | Selection only; runs nothing, so no runtime is required. |
| `hack session start` | `--env`, `--service` | When the workspace is created; the name gains `.env-<name>` (`.env-base` for base spellings), and `--up` runs `hack up -d` with the same selection. | Start a new workspace or pass `--env` to `hack session exec`. | Injects into the workspace shell, not into containers. |
| `hack session exec` | `--env`, `--service` | Per command; omitted reuses the selection encoded in the workspace name. | Each command resolves again. | Injects into the workspace command, not into containers. |

### Stale env warning on `hack exec`

`hack up` and `hack restart` record, for each Compose service they create, a keyed
digest of the env set delivered to it. The digest lives in Hack-managed runtime state
(`.hack/.internal/runtime-state.json`) and holds no key name or value. `hack exec`
resolves the same env set again and, when the digest differs, prints one fixed warning
to stderr that names the service and suggests `hack restart <service>`. The command
still runs with the env the container was created with, and stdout stays the target
command's output. The warning never prints a key or value.

The check is advisory. Identical env, state written before this check existed, and a
service whose last targeted restart failed produce no warning. `hack up <service>`,
`hack restart <service>` and `hack env apply --service <service>` refresh only the
named services' digests.

Projects on the native runtime backend run the same check. The foreground `hack up` or `hack restart` records
value-free digests of the env selection it delivered once the run is ready, in
`.hack/.internal/native-env-fingerprints/` (one file per instance, mode 0600). The
record is bound to that run and removed when the foreground ends. `hack exec` resolves
the same selection again: for a Compose-file (image) project, the env for the run's
recorded env name; for an authored project, the managed values for the recorded
`--env` and `--profile` selection. When they differ, it prints one fixed warning to
stderr that names the service and suggests `hack restart`, since native restart is
whole-project. An image-project exec receives freshly resolved values itself, so its
warning says the running service still uses the env it started with. A restart drops
the record once the previous run stops, so a failed restart produces no warning. A
record from another run, a missing record, or any resolution failure produces no
warning. An authored-project check is bounded: after five seconds without a result
it is skipped and the command's output and exit code follow as usual. Ctrl-C during
the check ends the command with exit code 130 without waiting for it.

Two exec paths do not run this check yet: an authored `.hack/hack.project.json`
project on the Compose backend (see
[native configuration with Compose](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/native-compose-commands.md)), and an
existing Compose project switched with
[`hack config adopt`](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/native-compose-adoption.md), whose exec runs in the
retained containers.

MCP tools accept no env selector. They run the CLI without `--env`, so each row's
omitted-`--env` behavior applies.

An overlay name is a label for a set of env files. It implies no production authority
and no network or instance isolation: a `prod` overlay still runs on the local stack,
and two overlays share the same instance unless you choose a separate branch instance.

## Common commands

Inspect resolved env:

```bash
hack env list
hack env list --env qa
hack env list --env qa --service api
hack env list --json
hack env list --show-secrets
hack env explain GITHUB_TOKEN --env runner --service installer --target compose
```

`hack env explain` never prints the value. It reports availability, secret classification,
selected/effective scope, source file and precedence, and whether the value is delivered to host
lifecycle code or Compose. Recreate just one service after an env change with:

```bash
hack env apply --service api --env qa
```

`--show-secrets` prints secret values in plaintext instead of the masked default; use it deliberately.

Read one value explicitly:

```bash
hack env get SERVICE_TOKEN --service api
hack env get SERVICE_TOKEN --service api --env qa
hack env get API_BASE_URL --env default
```

`hack env get KEY_NAME` writes exactly the resolved UTF-8 value to stdout, with
**no added newline**, quotes, label, or JSON envelope. Empty values succeed with
zero output bytes. Multiline content and trailing newlines are preserved; shell
command substitution may itself remove trailing newlines. Missing or deleted
values exit nonzero with an error on stderr and empty stdout. Invalid arguments,
malformed env files, and unavailable or denied keys/backends also fail without
printing values, ciphertext, or raw backend errors. `--json` and `--show-secrets`
are not accepted by `get`; help is available separately with `--help`.

Omitting `--env` uses the configured default overlay. `--env default` (also
`--env base` or `--env none`) selects base layers, including local overrides.
An absent optional overlay keeps the existing base/local fallback behavior.
`--service api` selects global plus service values using the same layer ordering
as runtime injection; the default scope is `global`. Linked worktrees use the
same primary-local inheritance and checkout-local precedence as other env flows.
`get` returns that stored scope's value without host-address rewriting.

This explicit command needs no running containers and adds no confirmation.
Existing native keychain authorization still applies. Modern YAML secrets decrypt
only the requested winning entry, so an unrelated missing key or corrupt encrypted
value does not force disclosure or block a plaintext read. Legacy projects retain
their configured backend and declared-key lookup; only the requested overlay/base
key is fetched. The existing encrypted-file backend internally decrypts its sealed
bundle. Empty legacy values are returned as present by `get`; legacy runtime
injection keeps its existing empty-value fallback behavior.

`get` does not migrate or materialize env files, write plaintext artifacts, or add
secret values to diagnostics, MCP tools, or audit output. Treat its stdout as a
secret when the requested value is sensitive; avoid redirecting it into logs or
committed files. Use `hack env explain KEY_NAME` for inspection without disclosure.

Add or update values:

```bash
hack env add API_BASE_URL https://api.example.com
hack env add --env qa API_BASE_URL https://qa.example.com
hack env add API_BASE_URL https://api.example.com --local
```

`hack env set` still works as a compatibility alias for `hack env add`, but `add` is the primary UX now.
The two differ on an in-project dangling layer link: `set` refuses it and `add` replaces it.

### Entering secret values

Never pass a secret value as a command argument: arguments land in shell history and are
visible to other local users and tools through process listings. Use one of these instead:

```bash
# Pipe the value from a secret manager or file; it never appears in argv.
<secret-source> | hack env add SERVICE_TOKEN --service api --secret --value-stdin
hack env add SERVICE_TOKEN --service api --secret --value-stdin < token.txt

# In an interactive terminal, omit the value to use the hidden prompt.
hack env add SERVICE_TOKEN --service api --secret
```

`--value-stdin` works on `hack env add` and `hack env set`, with or without `--secret`.
It reads all of stdin, up to 64 KiB, and strips exactly one trailing newline (`\n` or
`\r\n`), so `printf '%s\n' "$value"` and `printf '%s' "$value"` store the same value; any
further trailing newlines are kept. It refuses, with a fixed message that never repeats the
input and without writing anything:

- an interactive terminal on stdin (pipe the value, or drop `--value-stdin` for the hidden prompt)
- a value argument alongside the flag, including `KEY=value`
- a missing key argument
- empty input, input over 64 KiB, invalid UTF-8, or a NUL byte
- input that has not reached end of file within 30 seconds, for example a pipe whose writer
  never closes it, or an inherited stdin that nothing writes to. Close the pipe after writing
  the value, or redirect from a file. `HACK_ENV_VALUE_STDIN_TIMEOUT_MS` sets the deadline
  (1,000–600,000 ms).

Calls to the OS keychain (macOS Keychain, or the Secret Service over the D-Bus session bus on
Linux) are bounded too. With no desktop session, a locked keychain, or a session bus that never
answers, the call fails after 60 seconds with a fixed message instead of waiting. The outcome of a
timed-out write or delete is unknown, so check it once the keychain responds. For unattended
hosts, use the `encrypted_file` secrets backend with its key file in place or
`HACK_SECRETS_FILE_KEY` set; without either, that backend also reads its key from the keychain.
`HACK_KEYCHAIN_TIMEOUT_MS` sets this deadline (1,000–600,000 ms).

`--local` writes to the worktree-local override file (`.hack/hack.env.local.yaml` or
`.hack/hack.env.<overlay>.local.yaml`) instead of the shared repo env file — use it for
per-checkout values you don't want to commit.

With no env layers yet, `hack env set --local` writes legacy `.hack/.env` (or
`.hack/.env.<overlay>`), including when a `hack.env.json` contract exists.
Use `hack env add --local` to migrate first and then write the machine-local layer.
Contract migration writes `plain_env` values from legacy dotenv files to the gitignored
machine-local layer, never a tracked layer, and refuses a `plain_env` value that comes only
from your shell. It reports each moved key and destination path, without values. It refuses
a local destination already tracked by Git. Values declared as `keychain` migrate to tracked
layers as ciphertext.
Migration requires effective ignore protection before writing plaintext. It refuses
an outdated read-only `.hack/.gitignore` or a local destination that Git does not ignore.
Without `hack.env.json`, `set --local` still writes `.hack/.env`; if a contract is
added later, migration keeps those values machine-local too.

Repeating `hack env add` or `hack env set` with the value already stored is a no-op: when
the existing secret decrypts to the same value under the current key, its ciphertext is
kept, so once Hack has written the file it stays byte-identical and Git shows no change.
A hand-edited file (comments, other formatting, or no `global: {}`) is normalized on the
first repeat and stays byte-identical after that. A different value, a plain entry
becoming secret, or an entry that does not decrypt under the current key gets new
ciphertext with a fresh IV. Each command writes one key; a script that sets several keys
is not atomic across them. To write many machine-local values in one commit, use
`hack env hydrate` (below).

Each env file write goes to a hidden `.<file>.<id>.tmp` file in the same directory and
replaces the file by rename, so an interrupted write leaves the previous file in place.
A write killed before the rename can leave that staging file behind. It holds the whole
new layer, so `.hack/.gitignore` ignores `.hack.env*.tmp`, and you can delete it. Hack
does not remove it on the next write, because another write may still be using it. The
rename has these effects:

- a symlinked YAML env layer is allowed only when its fully resolved path stays inside
  the project's real root. Relative links and link chains are resolved at each hop; a
  root behind a symlink works too. An allowed link keeps its link, the write lands at
  its target, and the staging file is created next to that target
- outside targets (including dangling outside links), sibling-prefix escapes and link
  loops are refused with a closed, value-free error before reading values from stdin
  or writing decrypted or hydrated output. This applies to the base, tracked overlays
  and local layers, including init scaffold writes; mutation discovery checks all named
  YAML layers, including case-variant names on case-insensitive filesystems.
  `hack doctor --fix` reports an error for a `.hack` linked outside the project
  and leaves the link and outside files in place
- `hack env set` and `hack env unset` refuse an in-project symlink whose target does not
  exist with `E_PATH_CONFLICT`, and strict planning and hydrate reads refuse it too. Replace
  or remove the link, then retry. `hack env add` replaces that link with a regular file
- the writer rechecks both the layer and its resolved destination before staging and
  commit. These path checks narrow concurrent-swap races; they are not an atomic
  filesystem fence against a directory changed after the last check
- a hard link is broken: the env file gets a new inode, and any other name for the old
  file keeps the previous contents
- the directory must be writable, even when the env file itself is writable; if it is
  not (for example a `.hack` directory at mode `0555`), Hack refuses with a one-line
  error that names the env file and says its directory is not writable

A rename does not need write access to the file it replaces, so Hack checks that access
itself before it stages anything. It refuses to replace an existing env file that it
cannot read, that is not a regular file, that is not writable, or whose owner and group
it cannot keep (for example a root-owned file left by an earlier `sudo hack`). `hack env
unset` refuses an env file it cannot read in the same way, rather than reporting that
there is nothing to remove. The error is one line under every `HACK_LOGGER` backend
(`HACK_DEBUG=1` adds the stack), names the file and the reason, never a value, and the
file is left as it was. Fix the file's permissions or ownership and run the command
again. A rewrite keeps the file's permission bits, owner and group.

This includes a file you own whose group you are not a member of. Without root, the new
file cannot be given that group, so Hack refuses rather than let the file fall back to
your default group: keeping group-readable permission bits under a different group could let other
accounts read it (on macOS the default group is usually `staff`, which every local
account belongs to). Such a file usually comes from moving it (`mv`) out of a directory
with another group, for example `/tmp` on macOS, where new files take the directory's
group `wheel`, or from being removed from the file's group. Run `chgrp <your-group>
<file>` and run the command again.

The other files these commands write fail the same way. These are `.hack/.gitignore`
(`--local` and `hydrate`), `.hack.secret.key` (the first `--secret` value, including
the key lock Hack takes in the git directory first), the repository root `.gitignore`
entry for that key, and `.hack/.internal/` (the `hydrate` lock). If a write is denied,
the filesystem is read-only, the disk or quota is full, a parent path is not a
directory, or a directory is in the way of a file, Hack prints one line. That line
names the file or directory Hack was writing, gives the reason and says what to fix. It
never shows the raw system error, the hidden staging file name or the lock's staging
file. An env file on a read-only filesystem is reported as a read-only filesystem, not
as a file that is not writable.

Each of these lines starts with a stable code, and `--json` puts the same code and
message in the envelope:

- `E_PERMISSION`: permission denied, a read-only filesystem, or an owner or group Hack
  cannot keep. A `.hack` directory you cannot search (for example mode `0644`) and one
  you cannot write (for example mode `0555`) both give this code.
- `E_NO_SPACE`: the disk or the disk quota is full.
- `E_PATH_CONFLICT`: a path is the wrong kind of entry, such as a file where Hack needs
  a directory, a directory where Hack needs a file (including a `.hack/.gitignore` that
  is a directory or a symlink), or a `.hack/.internal` that `hack env hydrate` finds to
  be a symlink (dangling or not). A file name or path that is too long for the
  filesystem is reported with this code too; use a shorter `--env` overlay name or
  move the project to a shorter path.
- `E_CONFIG_INVALID`: `hack env hydrate` could not check its project inputs. A
  `.hack/.internal` that is a file gives this code with `Cannot inspect Hack project
  inputs. Check filesystem permissions and paths before retrying. Values omitted.`:
  Hack cannot tell whether the private state it keeps inside `.hack/.internal`
  exists, so it stops before hydrating instead of treating it as absent. Replace
  the file with a directory (or remove it), then retry.
- `E_LOCKED`: the project env key lock (`<git common dir>/.hack.secret.key.lock`, taken
  by the first `--secret` value) stayed held for the whole 10-second wait. Nothing was
  written. Another hack command may be creating the key; retry when it finishes. If no
  other hack command is running, the lock is stale (for example its process ID now
  belongs to an unrelated process, which Hack never treats as abandoned): remove the
  lock file the message names, then retry.

The first `--secret` value also works on a filesystem without hard links, such as ExFAT
or FAT on a USB drive. Hack normally publishes the key file and its locks with a hard
link, so they appear complete or not at all. Where that is not possible, it creates an
empty placeholder exclusively and renames the complete file over it, which keeps the
same rules: an existing file or symlink is never replaced or followed, and a reader
never sees a partial file. If Hack is killed between those two steps, an empty
`.hack.secret.key` or lock file is left behind. Hack refuses it rather than use or
replace it; remove it and run the command again. ExFAT and FAT do not store Unix
permissions, so on such a drive the key file is not limited to your user the way mode
`0600` limits it elsewhere.

If you omit `key`, `value`, or `--service`, `hack env add` prompts for them interactively.
Pass `--no-interactive` (or set `HACK_NO_INTERACTIVE=1`) for scripted/agent usage: the
command applies documented defaults or fails fast with `E_INTERACTIVE_REQUIRED` instead of
blocking on a prompt. In scripts, supply secret values with `--value-stdin` rather than as
arguments. `hack env unset` and `hack env set` accept `--local` and
`--no-interactive` too.

Remove a value:

```bash
hack env unset API_BASE_URL
hack env unset SERVICE_TOKEN --service api --env qa
hack env unset API_BASE_URL --local
```

### Concurrent writes to one env file

Hack env commands that change an env file never silently lose another command's change.
`hack env set`, `hack env add`, `hack env unset` and `hack env hydrate` each read the
file, change it and replace it while holding that file's write lock,
`.hack/.internal/<file name>.lock` (for example `.hack/.internal/hack.env.yaml.lock`).
The same applies to the legacy `.hack/.env` files. So when several commands change
different keys of the same file at once, every change is kept. A command
that finds the lock held waits up to 10 seconds, then stops with a one-line message that
names the file and its lock and says nothing was written; run it again. The lock is
released when the command ends. If a command is killed while it holds the lock, the next
command takes the lock over once it confirms that process has exited.

Hack never removes a lock it cannot prove is abandoned. That includes a lock file that
is not a complete Hack receipt, one owned by another user or writable by others, and one
that names a process ID now used by an unrelated live process. In those cases every
retry would wait and fail the same way, so the message also says what to do: if no
`hack env` command is running, remove the lock file it names and retry. If a command was
killed while it was taking over an abandoned lock, it leaves `<lock>.recovery` behind,
and the message says the recovery guard is busy and names both paths; when no `hack env`
command is running, remove both and retry. `hack env hydrate` reports the same message
when it cannot get the env file's lock.

`.hack/.internal/` is ignored by the managed `.hack/.gitignore`, so lock files never show
in `git status`. If `.hack/.internal` is a symlink, dangling or not, these commands
refuse with one `E_PATH_CONFLICT` line instead of creating the lock through it. If it is a
regular file, they refuse with one `E_CONFIG_INVALID` line (`Cannot inspect Hack project
inputs...`) and write nothing. If you cannot write the directory that
holds the env file (for example a read-only checkout), no lock is taken: no command can
replace the file there, so a command that changes nothing still succeeds and one that
would change the file is refused as before.

Programs that do not take this lock, such as an editor or Hack v4, are not kept out. For
`hack.env*.yaml` files, `hack env set`, `add`, `unset` and `hydrate` also check that the
file still has the contents they read just before replacing it. If it changed, the
command writes nothing and stops with a retryable conflict ("The file changed while it
was being replaced; nothing was written."), or, for `hydrate`, a `concurrent_write`
refusal. That check narrows the window in which such a program's write can be
overwritten, but cannot close it.

### Hydrate machine-local values in one step

`hack env hydrate` imports many values into the machine-local layer at once, for example
when a new checkout or machine pulls its secrets from a secret manager. Tracked defaults
stay in `hack.env.default.yaml`; hydration writes only the gitignored local layer
(`.hack/hack.env.local.yaml`, or `.hack/hack.env.<overlay>.local.yaml` with `--env`).

```bash
# Pipe KEY=value lines from a secret manager; values never appear in argv.
<secret-source> | hack env hydrate --secret

# Or read a file, or a pipe such as <(secret-source).
hack env hydrate --secret --file .secrets.env
hack env hydrate --secret --file secrets.json --format json --env qa --service api
```

Input comes only from piped stdin or `--file`, never from arguments, and is at most
1 MiB. The default `env` format is strict, one entry per line:

- blank lines and lines starting with `#` are skipped, and an `export ` prefix is allowed
- `KEY=value`, where the key matches `^[A-Z_][A-Z0-9_]*$`; an unquoted value is the
  rest of the line with surrounding spaces removed, and `#` inside it is part of the value
- `'...'` is literal; `"..."` accepts `\n`, `\r`, `\t`, `\"` and `\\`; a quoted value
  must close on the same line, followed only by spaces or a `# comment`
- empty values, repeated keys and `${VAR}` expansion are not supported

`--format json` takes one object whose values are non-empty strings. A key that
appears twice is refused, as in the `env` format; it is not resolved by keeping the
last value. One malformed entry refuses the whole input. The message gives only the line number, never the
line, and nothing is written.

`--secret` encrypts every imported value; without it the values are stored as plain
entries in the local layer. A plain import refuses to replace a key that the local
layer already stores as a secret, so repeat an import with the same flags it was first
run with. `--service` picks one scope for all entries (default
`global`). The output and `--json` result list the added, updated and unchanged keys,
never values.

Hydration is idempotent and all-or-nothing:

- An entry that already holds its value is left alone: a secret keeps its ciphertext
  and a plain number keeps its YAML type. When nothing changes, the file is not
  rewritten, so comments and formatting survive and Git shows no change.
- A changed value gets new ciphertext with a fresh IV.
- Local entries that are not in the input, other scopes, and removal markers for other
  keys are kept. A key in the input replaces that key's local entry, including a
  value you set by hand with `--local`.
- The whole new layer is written to a staging file and published by one rename, so an
  interrupted hydration leaves the previous layer, with every key at its old value.

Hydration refuses, without changing the layer, when:

- git tracks the target local layer
- the project is in a git checkout but git cannot say whether it tracks the local layer,
  for example after a `safe.directory` refusal, with a damaged index, or with git not
  installed (outside any git checkout, hydration proceeds)
- the local layer exists but is not a valid env file, for example invalid YAML, the
  wrong `version`, or a scope that is not a mapping; fix or remove it first
- a secret already in the local layer does not decrypt under the project env key, or no
  key is available (`.hack.secret.key` is used before `HACK_ENV_SECRET_KEY`, as when
  values are read)
- `--secret` is used, no `.hack.secret.key` exists, and `HACK_ENV_SECRET_KEY` is set
  (a new key file would replace that key for every layer)
- `--secret` is not used and an imported key is stored as a secret in the target scope;
  re-run with `--secret`, or remove the key with `hack env unset <key> --local` first
- another `hack env hydrate` for the same project is running, or an interrupted one left
  a stale lock (see below)
- the local layer changed between hydration's read and its rename, by a program that
  does not take the env file's write lock (for example an editor or Hack v4)
- hydration waited 10 seconds for the env file's write lock without getting it

Concurrent hydrations are serialized by `.hack/.internal/env-hydrate.lock`, which holds
the owner's process ID. A hydration that is killed (for example with SIGKILL) cannot
remove it; the next hydration then reports the stale lock and its path instead of taking
it over. Remove the file once no hydration is running. `hack env set --local` does not
take this lock, but hydration also holds the local file's write lock (see
[Concurrent writes to one env file](#concurrent-writes-to-one-env-file)), so a
concurrent `hack env set --local` waits for the hydration and both changes are kept.

Materialize a compatibility `.hack/.env`:

```bash
hack env materialize
hack env materialize --env qa
hack env materialize --env qa --service api
```

Run a host command with injected env:

```bash
hack host exec -- bun db:migrate
hack host exec --env qa --scope api -- bun db:migrate
hack host exec --env qa --scope api --target compose -- bun test
```

Cancelling `hack host exec` or `hack env exec` with SIGINT or SIGTERM forwards
the signal to the command. Commands run in an owned process group,
so cancellation also stops their descendants, escalating to SIGKILL after two
seconds if necessary. Hack returns 130 for SIGINT and 143 for SIGTERM. Interactive
commands use a supervisor in their own foreground group on the same terminal,
preserving stdin, separate output streams, and Ctrl-Z/foreground resume. Piped
stdin also retains the controlling terminal, so commands can open `/dev/tty`
for native authentication prompts. The
supervisor holds group ownership until cancellation cleanup finishes. SIGKILL cannot be forwarded; supervisors must terminate the
whole owned process tree when force-killing a wrapper. Commands have no implicit
time limit, and normal completion preserves the command's exit status.

When you want to inspect an injected value, avoid `hack host exec -- echo $VAR`. Your current
shell expands `$VAR` before Hack starts the child process, so the command often sees an empty
string.

Use one of these instead:

```bash
hack host exec -- printenv APPLE_TEAM_ID
hack host exec -- sh -lc 'printf "%s\n" "$APPLE_TEAM_ID"'
hack host exec --shell 'echo $APPLE_TEAM_ID'
```

Open a host shell with injected env:

```bash
hack host shell
hack host shell --env qa --scope api
hack host shell --env qa --scope api --target compose
```

Example with an explicit host override:

```yaml
version: 1
environment: default
secretsprovider: project_key
values:
  global:
    DATABASE_URL:
      secure: v1:...
    REDISHOST: redis
  host:
    REDISHOST: "127.0.0.1"
```

## Sessions and env

Session flows can now carry env selection too.

Examples:

```bash
hack session start my-project --env qa --service api --detach
hack session exec my-project.env-qa.svc-api --env qa --service api "bun db:migrate"
```

When you pass `--env` or `--service`, Hack creates a stable scoped workspace name instead of reusing the plain default workspace. That prevents one shell from silently inheriting the wrong env selection.

## Secret key handling

Secret values in the YAML files are encrypted with the project key.
The [env and secrets threat model](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/security/env-secrets-threat-model.md) lists what
this protects against and the gaps that are still open.

Default behavior:

- generate `.hack.secret.key` the first time you add a secret
- add `.hack.secret.key` to `.gitignore`
- decrypt secrets from `.hack.secret.key` on the local machine
- linked git worktrees can reuse the primary checkout's `.hack.secret.key` when the worktree copy is missing

Linked worktree behavior:

- when a repo uses linked git worktrees, Hack prefers a shared key under the git common dir
- sibling worktrees can decrypt the same committed secrets without manually copying gitignored files
- if a checkout-local `.hack.secret.key` exists, it still wins for that checkout
- `hack up` in a linked worktree auto-selects a branch instance (`worktree.auto_branch`); that
  selection determines which instance's resolved env is the one actually injected, so keep the
  key readable from every checkout that runs `hack up`

Linked worktrees also read the primary checkout's eligible local YAML overrides
(`hack.env.local.yaml`, or its legacy-compatible local-default path, and the selected
`hack.env.<overlay>.local.yaml`). Resolution order is checkout tracked default and
overlay, primary local default and overlay, then checkout local default and overlay.
The resolved file list includes inherited paths. Primary tracked configuration,
legacy `.env`, runtime state and unrelated ignored files are not inherited.

Local values override inherited values. A YAML `null` entry explicitly removes a
value supplied by earlier layers; deleting the entry instead reveals the earlier
value again. `hack env unset KEY --local` in an inheriting linked worktree records
that removal without modifying the primary file. A later `set --local` replaces it.
Inheritance reads current files each time and never copies them into the worktree.
Invalid inherited files and redirected file paths fail explicitly.

Set `worktree.inherit_local: false` in the checkout's Hack config to disable local
file inheritance. CI (`CI=1` or `CI=true`) and slim/Codex execution mode disable it
automatically. This setting does not change the existing secret-key lookup order
below. Missing primary local files are optional; retained encrypted values still
require the selected checkout's valid decryption key.

Full read order for decrypting secrets (first match wins):

1. checkout-local `.hack.secret.key`
2. shared key under the git common dir
3. the primary checkout's key, inherited automatically for a linked worktree that has neither of the above
4. `HACK_ENV_SECRET_KEY`

Write-path guarantees in a linked worktree (first secret added from any checkout):

- an existing checkout-local key is reused as-is
- otherwise an existing shared key (git common dir) is reused
- otherwise the primary checkout's key is adopted by copying it to the shared location, so sibling checkouts converge on one key
- only then is a new key generated, and it is written to the shared location — never silently to the checkout
- concurrent first use from several checkouts converges on one key: when no key exists, creation runs under a cooperative lock at `<git common dir>/.hack.secret.key.lock`, and a key file is published only when complete, never empty or partial (Hack v4 writers do not take the lock; on a filesystem without hard links, such as ExFAT, an empty placeholder is visible for a moment before the complete key replaces it)
- if the shared location cannot be resolved (git unavailable) or written, Hack falls back to a checkout-local key and prints a loud divergence warning
- `hack doctor` flags divergent `.hack.secret.key` contents across checkouts with the exact paths

Key strength and exposure (`hack doctor` "env key" check):

`hack doctor` and `hack doctor --json` audit the checkout-local key, the shared key
under the git common dir and, in a linked worktree, the primary checkout's key. When
no key file exists, the check classifies `HACK_ENV_SECRET_KEY` instead. The check is
read-only. It never prints key bytes or absolute paths, and `--fix` does not act on it.
Each finding names a project-relative subject and the exact command to run from the
project root. `--json` adds an `envKey` object to the check with `status` and
`findings` (`code`, `status`, `subject`, `remedy`). The native runtime backend's
`hack doctor` runs the same check inside a project.

Nested public artifact directories are found with a bounded walk from the project
root: at most six levels deep, 4096 directories and 100,000 entries. It skips
`node_modules` and `.git`, does not follow symlinked directories, and reports a path
it cannot spell portably as `<unprintable-path>/.hack.secret.key`.

| Code | Status | Meaning |
| --- | --- | --- |
| `env-key-ok` | ok | key material is a regular, private, 256-bit-class file |
| `env-key-absent` | ok | no key file and no `HACK_ENV_SECRET_KEY` |
| `env-key-weak-permissions` | warn | group or others have access; suggests `chmod 600` |
| `env-key-wrong-owner` | warn | the file is not owned by the current user |
| `env-key-wrong-length` | warn | shorter than the 43-character base64url form of a 256-bit key, or empty |
| `env-key-low-entropy` | warn | long enough but repetitive (estimated under 128 bits) |
| `env-key-unignored` | warn | the checkout-local key is not ignored by git, so `git status` offers it for commit (for example after `git init` in a directory whose root `.gitignore` entry was removed); suggests adding it to the root `.gitignore` |
| `env-key-symlink` | error | the key path is a symlink; Hack refuses symlinked keys |
| `env-key-not-regular` | error | the key path is a directory or another non-file entry |
| `env-key-unreadable` | error | unreadable, oversized or not UTF-8 |
| `env-key-tracked` | error | a file named `.hack.secret.key` is tracked by git at any depth |
| `env-key-public-path` | error | a key copy sits directly in `public/`, `static/`, `dist/`, `build/`, `out/`, `www/`, `_site/`, `.next/` or `.output/`, at the project root or in a nested package such as `apps/web/public/` |

Hack derives the AES-256-GCM key by hashing the key text with SHA-256, so key
strength is the entropy of that text. Generated keys are 32 random bytes in base64url.
For a weak, tracked or published key, rotation is required. Preserve a private,
recoverable copy of the old key and encrypted inputs before changing either.
Recover each selected secret with the old key, then re-add it with the new key
using the hidden prompt or `--value-stdin`; never put secret values in arguments.
Individual atomic writes do not make this sequence a crash-safe rotation transaction.
See the [env security decision and rotation gates](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/security/env-secrets.md).

CI and managed container fallback:

- if `.hack.secret.key` is missing, Hack falls back to `HACK_ENV_SECRET_KEY`

That makes this model usable in CI and portable container images without committing the key file.

Published container paths:

- slim managed-container base: `hackdance/hack:slim` — the supported CI / managed-container story
- full remote runtime: `hackdance/hack:latest` — serves the remote/node surface, which is
  experimental and unsupported (hidden behind `hack help --all`); only relevant if you have
  explicitly opted into that surface

In both cases, inject `HACK_ENV_SECRET_KEY` from the runtime or secret manager instead of copying
`.hack.secret.key` into the image.

## Legacy repos and migration

Older repos may still have:

- `.hack/hack.env.json`
- `.hack/.env`
- `.hack/.env.<overlay>`
- configured secret backends via `hack env backend`

Hack still detects and reads that legacy format, but the preferred migration path is:

```bash
hack doctor --migrate-env-config
```

That migrates the repo into:

- `.hack/hack.env.default.yaml`
- `.hack/hack.env.<overlay>.yaml`
- `.hack/hack.env.local.yaml` and `.hack/hack.env.<overlay>.local.yaml` for plain values
- `.hack.secret.key` when needed

Tracked layers receive secret-backed ciphertext, not legacy plaintext.

The migration runs the same way on the Compose and native backends: it changes project
files only, so native `hack doctor --migrate-env-config` needs no Docker and no native
runtime.

`hack.env.json` and the Compose file are shared, git-tracked configuration, so the
migration never deletes or edits a git-tracked file without your consent. Interactively,
doctor lists the git-tracked files that may change before it migrates, and asks before it
removes `env_file` entries from a tracked Compose file and, separately, before it removes
git-tracked legacy files such as `hack.env.json`. A file whose git status can't be read
inside a git checkout counts as tracked. A run that can't prompt (no TTY,
`HACK_NO_INTERACTIVE`, or `--no-interactive`) refuses with `E_INTERACTIVE_REQUIRED` before
any doctor step writes, naming each tracked file it would delete or edit, unless you pass
`--accept-tracked-env-changes`:

```bash
hack doctor --migrate-env-config --no-interactive --accept-tracked-env-changes
```

The list is conservative; with a contract it can include `hack.config.json`, which the
migration rewrites when it still holds legacy keys such as `defaultEnvConfig`, and a legacy
dotenv file the migration ends up keeping. Commit the changes so teammates get them.

Commands that need env values, such as `hack env exec`, also migrate a
project that has `hack.env.json` and no env layers, without asking. That migration reports
each moved key, never its value, and removes a legacy `.hack/.env` or `.hack/.env.<overlay>`
file only when every entry now lives in an env layer, Compose no longer names it as
`env_file`, Compose doesn't interpolate a key from it that the env layers now set only for a
service, and git doesn't track it, so no second plaintext copy stays behind. It keeps
`hack.env.json`, never edits the Compose file and never deletes a git-tracked file; it names
a kept file and says why. Run `hack doctor --migrate-env-config` for those
changes. Like doctor, it rewrites legacy keys in `hack.config.json`.

A repo that has no `.hack/hack.env.json` is migrated as well. Its values live only in
`.hack/.env` and `.hack/.env.<overlay>`, which are gitignored and may hold passwords or
API keys, so the migration keeps them out of tracked files: each `.hack/.env` entry
becomes a plaintext global value in the gitignored machine-local layer
`hack.env.local.yaml`, and each overlay entry that differs from `.hack/.env` becomes a
global value in `hack.env.<overlay>.local.yaml`. These machine-local layers are created
as private (mode 0600) files and never replace an existing entry. The tracked `hack.env.default.yaml`, and
`hack.env.<overlay>.yaml` for each migrated overlay, are written with no values, so the
repo switches to env layers. Teammates do not receive these values through git; share
the ones they need with `hack env set` (plain settings) or `hack env set --secret`
(encrypted) after the migration.

A repo with no legacy env file gets only an empty `hack.env.default.yaml`.

Once this is committed, a teammate's own `.hack/.env` and overlays may stop reaching services,
because their checkout now uses env layers. Hack compares those files with what the layers
deliver. For any value the layers don't deliver, `hack up` warns and doctor reports it. For a
value in `.hack/.env`, `hack env materialize` also refuses, so the file isn't replaced; it doesn't
write overlay files, so an overlay value doesn't stop it. They run
`hack doctor --migrate-env-config` to move those values to their own local layers, adding to a
local layer that already exists and making it private (mode 0600). A value equal to what the
layers deliver isn't copied, so later team changes still reach them. A key the local layer sets
differently refuses (`E_PATH_CONFLICT`), and so does a local layer that can't be read as an env
layer (`E_CONFIG_INVALID`), which is left as it is. Adding to a layer drops its YAML comments. Messages name valid keys, count malformed entries and name unreadable files,
and never show a value. This comparison skips a `.hack/.env` with a valid materialization state.
A migration that runs for another reason, such as an overlay value, also checks that file's text,
as described below. With nothing else to migrate, doctor reports that the project already uses env
layers without checking the text, and a later `hack env materialize` replaces the file. Tell
teammates when you commit the migration.

Migrated values are global, so a service added later receives them too, and so do host lifecycle
hooks. A migrated value also takes precedence over the same variable exported in your shell,
including for Compose interpolation.

This migration refuses, with a one-line `E_*` error, writes nothing and keeps the legacy
files, when:

- a key does not match `^[A-Z_][A-Z0-9_]*$`, for example a lowercase name or a line
  that starts with `export ` (`E_CONFIG_INVALID`). The error counts the keys per file but
  does not show them, because a malformed line may hold a value. Rename or remove them;
- a legacy file is named `.hack/.env.default`, `.hack/.env.local` or
  `.hack/.env.<name>.local`, whose layer would be the default or a machine-local layer
  rather than an overlay (`E_CONFIG_INVALID`). Rename or remove it;
- a legacy `.hack/.env.<name>` file has a name that is not an overlay name (lowercase
  letters, digits and single dashes), such as `.env.staging.old` or `.env.Prod`
  (`E_CONFIG_INVALID`). The error names such files. Rename or remove them; a renamed
  overlay is then selected by its new name (`--env <new-name>`). Template and
  backup copies (`.env.example`, `.env.sample`, `.env.template`, `.env.dist`, `.env.bak`,
  `.env.backup`, `.env.old`, `.env.orig`) are not overlays: they are neither migrated
  nor offered for cleanup;
- Compose `env_file` uses one of those template or backup copies (`E_CONFIG_INVALID`), so
  its values would be lost. Rename the file to an overlay name or move it out of `.hack`,
  and update `env_file` to match;
- Compose `env_file` uses an overlay such as `.env.staging` that holds values of its own
  and is not `env.defaultOverlay` (`E_CONFIG_INVALID`). Compose loads that file on every
  launch, but after the migration a launch without `--env` would not select the overlay,
  so the service would lose those values. Set `env.defaultOverlay` to it, or remove the
  `env_file` entry and select the overlay with `--env`;
- an entry named like an env layer (`.hack/hack.env.*.yaml`) is a dangling symlink, a
  directory or another non-file (`E_PATH_CONFLICT`). With a symlinked layer inside the project,
  or with nothing to move, `hack doctor` reports that the repo already uses env layers and
  migrates nothing, and it never writes through the link. It can still remove `.hack/.env*`
  entries from `env_file` in the Compose file, and a service then stops receiving a value only
  that file set, so move such values first with `hack env set --local`. A `.hack` or a layer
  linked outside the project is refused with a closed error, and the link and outside files
  stay as they are;
- outside a git checkout, `hack.env.local.yaml` sets `environment: local`, so it serves as the
  `local` overlay and base values written there wouldn't reach the default env
  (`E_CONFIG_INVALID`). If it's meant to be your machine-local layer, set its `environment` to
  `default`, then retry;
- git tracks a machine-local layer it would write, or, in a git checkout, git cannot
  report whether it does (`E_PATH_CONFLICT`);
- in a git checkout, git does not ignore a machine-local layer it would write, for
  example because `.hack/.gitignore` is read-only and lacks Hack's managed block
  (`E_PATH_CONFLICT`). Make `.hack/.gitignore` writable, or ignore the path, and retry;
- a migrated value would replace a service or host value in an env layer, in the base or in
  an overlay, including an overlay a linked worktree inherits from its primary checkout
  (`E_CONFIG_INVALID`). A machine-local global value outranks a service or host value in an
  earlier layer, so that target would silently switch. The error names the keys, targets and
  envs, never values. Remove the key from the legacy file, or change that value in its layer;
- a key the legacy files set is also set in a Compose service's own `environment`
  (`E_CONFIG_INVALID`). Compose ranks `environment` above `env_file`, but migrated values
  become global layer values that Hack applies after `environment`, so the service would
  switch to the `.env` value. This includes an entry that only refers to its own key
  (`PORT: ${PORT}`), whose result can differ when an overlay or the shell sets the key. The error names the keys and services, never values.
  Remove the key from the legacy `.env` file or overlay that sets it, or from that service's `environment`, then retry;
- a service does not list a legacy file with values to migrate in `env_file` (`E_CONFIG_INVALID`).
  Migrated values are global and reach every service, including third-party images, so that
  service would receive values it never had. This includes a file no service lists, whose values
  today reach only Compose interpolation. Listing the file for each service is how you accept
  that. Otherwise, move those values out of the file and set them with
  `hack env set --service` after migrating, or keep them in your shell. Values Compose interpolates
  need the shell or a listed file, because service values do not reach interpolation. The error
  names files, services and keys, never values;
- Compose uses a top-level `include`, a service `extends`, a `!reset` or `!override` tag, a
  variable or a `~` in an `env_file` path, a file listed twice in one `env_file`, or a `format`
  on an `env_file` entry (`E_CONFIG_INVALID`), so the migration cannot tell which values services
  receive. Write those `env_file` entries directly in the Compose file, each file once, with a
  plain path and no `format`;
- a key the legacy files set is also set in another file a Compose service uses as
  `env_file` (`E_CONFIG_INVALID`), including as `export KEY=value`, `KEY: value`, a bare `KEY`
  or after a closing quote (`A='x' KEY=value`), for the same reason: that file stays in Compose, but the
  migrated value would override it. The check does not look at the order of the entries,
  or expand variables in an `env_file` path. Remove the key from one of the files, then retry;
- a legacy entry is one Compose reads differently from Hack (`E_CONFIG_INVALID`): an unquoted
  inline comment (`PORT=3000 # dev`), a `$` outside single quotes, a `\` in a quoted value (such
  as `\n` in a PEM key), text after a closing quote (`A='x' B=2`), or a line without `=` (`A: 1`,
  or a bare `A`). The value would change or be lost. The error counts entries per file and never
  shows them. Write each value on its own line, in single quotes, with real line breaks and no
  backslashes, or remove the line;
- a service lists legacy files in an order that gives a key a different value from the migrated
  layers (`E_CONFIG_INVALID`), such as `env_file: [.env.staging, .env]` with `.env.staging` as the
  default overlay. Compose lets the last file win, but the default overlay always wins over
  `.hack/.env` in env layers. List `.env` first, or make the files agree;
- the default overlay sets a key differently from `.hack/.env`, and Compose reads that key: its
  name appears anywhere in the Compose file or another `env_file` (`${KEY}`, a bare `build.args`
  entry, a secret's `environment:`), or it is a `COMPOSE_*` setting (`E_CONFIG_INVALID`). Compose
  takes it from `.hack/.env` today, but the overlay value would apply after the migration. Make
  the two files agree or stop using the key in Compose;
- a migrated `.hack/.env` value would replace what an overlay's layers deliver for a key its legacy
  overlay file doesn't set (`E_CONFIG_INVALID`), because a local base outranks tracked and inherited
  overlay layers. Remove the key from `.hack/.env`, or set the value you want in that legacy overlay
  file, creating it if needed; the Compose `env_file` checks above then apply to that file;
- env layers include a symlink while legacy values remain undelivered (`E_PATH_CONFLICT`).
  Replace linked layers with regular files containing the intended layer content, then retry
  `hack doctor --migrate-env-config`. The migration does not write through a linked layer;
- `.hack/.env` has a state file, env layers exist, and its text isn't what `hack env materialize`
  would write (`E_PATH_CONFLICT`). The file is out of date or was edited by hand, and Hack can't
  tell which. If it's generated, move any value of your own with `hack env set --local`, then run
  `hack env materialize`, which replaces it. If it's your own file, delete `.hack/.env.state.json`
  so it's read as a legacy file, but not for generated output, whose values would then migrate as
  your own. When the text does match, the migration doesn't read the file or offer it for cleanup;
- `.hack/.env` has a state entry that can't be read or parsed, such as a dangling link, and env
  layers exist (`E_PATH_CONFLICT`). If `.env` is your own file, delete `.hack/.env.state.json`. If
  it's generated output you don't need, delete both, then run `hack env materialize`;
- a legacy file sets a key that Docker, its build tools or the process read from their
  environment (`E_CONFIG_INVALID`): `DOCKER_*`, `BUILDKIT_*`, `BUILDX_*`, a proxy setting,
  `SOURCE_DATE_EPOCH`, `HOME` or `PATH`. After the migration it would reach the Docker client too.
  Remove it from the legacy file, and set it in your shell or for one service with
  `hack env set --service --local` after migrating;
- the Compose file is not a single YAML document this check can read, such as several `---`
  documents (`E_CONFIG_INVALID`). Merge it into one document;
- `.hack/.env` or a legacy overlay is a symlink to a file outside `.hack`
  (`E_PATH_CONFLICT`), so its values would be copied from elsewhere into this project's
  layers. Replace the link with a regular file in `.hack`, or remove it;
- the Compose file exists but cannot be read (`E_PERMISSION`), so the migration can't tell which
  values services receive. Make it a readable regular file, then retry;
- an env layer can't be read or resolved (`E_CONFIG_INVALID`), for example it doesn't parse or its
  project env key is missing, including a layer for an overlay you don't use, so the migration
  can't tell which values the layers already deliver. The error names the file or gives the
  `hack env list` command that shows the problem. Fix it, then retry;
- a legacy `.hack/.env` or overlay file exists but cannot be read, for example mode 000
  or a dangling symlink (`E_PERMISSION`), so its values would be lost. A symlinked overlay
  that resolves to a readable file inside `.hack` is migrated like a regular one; cleanup
  removes only the link, never its target.

A refused migration keeps the legacy source files. Earlier layer merges or ignore-rule
updates may remain, and removing newly created layers after a failure can itself fail.
Check the layers and ignore rules before retrying; migration compares the values again.

With `hack.env.json`, the migration refuses (`E_CONFIG_INVALID`) when a `plain_env` value comes only
from your shell, because it would otherwise be saved to a plaintext file you didn't ask for. This applies to commands
that migrate implicitly, such as `hack env exec`. Simply skipping the value isn't enough, because
env layers don't read the contract, so services would stop receiving it. The error names the key and
never the value, and gives the commands for the scope the contract declares:

1. Run one command without the variable, so the migration runs: `env -u KEY hack env exec -- true`.
   Add a `-u` for each key it names.
2. Set it for the declared scope: `hack env set KEY --service <name> --local --value-stdin`, or
   without `--service` for a key the contract doesn't scope. `--local` alone delivers it to every
   service, so keep `--service` for a scoped key.
3. If an overlay file also sets the key, the migration moves that value to the overlay's
   machine-local layer, which outranks the local base, so the overlay keeps it. To change it:
   `hack env set KEY --env <overlay> --local --value-stdin`, with `--service` as above.
   The error prints a command only for a name the CLI accepts. It names an overlay file `--env`
   can't select, such as `.env.My_Staging` or `.env.default`, or a service `--service` can't. Fix
   those before step 1, because env layers don't read the contract once the project migrates.
4. Keep it exported if Compose interpolation, or a host command run without that service's scope,
   reads a key you set with `--service`, because a service value doesn't reach them. A value set
   without `--service` does reach them, and overrides your shell.

The refusal comes before Hack provisions any secret-store key. If plaintext values are mirrored to a
secret backend whose key isn't available, Hack can't tell whether a key your shell sets is also in
the backend, so it refuses that key the same way. Make the backend's key available and retry. If the
backend has nothing stored yet and `HACK_SECRETS_DISABLE_KEYCHAIN_FALLBACK` isn't set, you can run
these steps instead, and the migration creates its key; set the key only if the backend doesn't hold
it. Any other backend failure, such as a corrupt store, stops the migration with that error.

With `hack.env.json`, the migration also refuses (`E_CONFIG_INVALID`), writing no env layer, an
overlay named `default`, `local` or `<name>.local`, in any case, that sets a value of its own, because
it would replace the base layer or write a machine-local file, and a contract service that isn't a
valid env scope when a value would be written for it, because no read could parse that layer. A
legacy `.env.default` or `.env.local` refuses even when it sets no value of its own, and so does a
different-case spelling of either, through the destination check. A
secret backend's key may already have been created by then. The migration also refuses, writing nothing
itself, a `hack.env.json` it can't open or read as a contract, and it doesn't quote the file. Earlier
`hack doctor` steps, such as creating `.hack/.gitignore`, can still have run.

With `hack.env.json`, the migration discovers only regular `.hack/.env.<overlay>` files, so a
symlinked overlay is not migrated. It refuses (`E_PATH_CONFLICT`) when `.hack/.env` or a
configured default overlay is a symlink, wherever it points, because another file's values,
such as a machine-local `.env.local`, would otherwise be copied into this project's env layers.

Without `hack.env.json`, nothing lists values kept in a secret backend, so none are
migrated: set them again with `hack env set --secret` after the migration. In that case `.hack/hack.config.json`, and
any secret backend it configures, is left unchanged. The migration changes project files
only, so it runs even when Docker is not reachable; the other `--migrate-env-config`
repairs still need Docker. As with any migration, `hack doctor` then offers to remove the
legacy `.hack/.env*` files that Compose no longer references (a non-interactive run
accepts for untracked files, and for git-tracked ones only with `--accept-tracked-env-changes`).
Files Compose still names as `env_file` are offered only when the Compose repair
removed those references. Without `hack.env.json`, a legacy file that git tracks, or one
whose status git cannot report in a git checkout, is never offered, because the migrated
values now live only in this machine's local layers.

Doctor offers legacy dotenv files for cleanup only when every parsed entry was
delivered to an env layer. Files containing undeclared or undelivered entries stay
on disk; the cleanup report lists their key names and omits their values. This
also applies to untracked overlays such as `.env.bak` and `.env.example`.
Doctor also keeps `.hack/.env` when the contract scopes a key in it to services
(`services: [...]`) and the Compose file or another `env_file` it lists names that key,
for example in `${KEY}`. Compose reads `.hack/.env` for interpolation on its own, and
service values don't reach interpolation, so removing the file would drop that value.
To remove the file, set the key without `--service` or export it in your shell.
Migration refuses a legacy `.env.default` overlay before writing env layers,
because it would overwrite the base `hack.env.default.yaml` layer. Rename that
legacy overlay and update its project references before retrying.
It also refuses `.env.local`, whose tracked overlay path would collide with the
machine-local base layer. Rename that legacy overlay before migration.
All tracked and effective local destinations are checked for collisions before any
writes, including compatibility paths. For example, `.env.staging` together with
`.env.staging.local` is refused because both would write `hack.env.staging.local.yaml`.
Collision checks include case-only aliases for checkouts with case-insensitive filenames.
If a legacy dotenv file cannot be read, migration refuses cleanup and leaves
legacy artifacts in place. Env layers may already have been written; check read
access and preserve the remaining entries before cleaning up manually.

`hack doctor` also warns when a repo still depends on the old format. Its `env mode`
check reports an error, not the legacy format, when a `.hack/hack.env.*.yaml` entry is a
dangling symlink or another non-file.
For modern env repos, `hack doctor` also warns when materialized compatibility output in
`.hack/.env` or `.hack/.env.state.json` is stale and points to `hack env materialize`.

The legacy `.hack/.env` holds one value per key, with no per-service values. In a legacy
project, `hack env set` and `hack env unset` change only that global value, so they refuse
`--service <service>` with a usage error instead of ignoring it (an invalid scope is refused
the same way in both formats). `--service global`, or no `--service`, still works. Migrate to
env layers first with `hack doctor --migrate-env-config`, which also converts a project that
has only `.hack/.env` (see above), then set or unset the service-scoped value.

Values migrated from `.hack/.env` live in the machine-local layer, and a later layer wins
over a more specific scope in an earlier one. So to override a migrated key for one service,
add `--local`: `hack env set KEY --service api --local`. Without it the new value goes to the
tracked default layer, where the migrated global value in `hack.env.local.yaml` still wins
and the command has no effect on the runtime value.

`hack env set` and `hack env unset` choose between the env layers and the legacy file by
looking for `.hack/hack.env.*.yaml` entries, `hack.env.default.yaml` included. A regular
file, or a symlink inside the project to one, counts as an env layer. An entry linked outside
the project is refused with a closed error. Any other entry with a layer name, such
as a dangling symlink or a directory, is refused with `E_PATH_CONFLICT`. Nothing is
written either way, and neither silently selects the legacy `.hack/.env`. Replace or remove the entry,
then retry. Reads refuse the same way: `hack env list`, `hack env explain` and runtime
env injection stop with `E_PATH_CONFLICT` on a selected layer entry that is not a regular
file (such as a dangling `hack.env.default.yaml`), and with a closed one-line error on one
that cannot be read, instead of falling back to the legacy file.

## Compatibility notes

The modern YAML env model is the canonical repo format today.

Some older surfaces are still compatibility-oriented:

- `hack env backend ...` remains relevant for legacy repos and older secret-store configurations.
  The `encrypted_file` store (also used by the `cloud` shim) is replaced atomically
  with mode `0600`, and set/delete hold an in-process queue plus a cooperative
  `<store>.lock` so concurrent writers, including separate processes, do not lose
  updates. A store path that is a symlink is refused for writes. Explicit key
  provisioning also uses an atomic mode-`0600` replacement and refuses symlinked
  key paths or immediate parent directories. A key generated on first use is
  published only when no key file exists, so concurrent first users adopt the key
  published first instead of replacing it under a store already encrypted with
  it. This protects individual key writes;
  it does not make key replacement and store re-encryption a crash-safe rotation
  transaction. Keep the previous key until recovery has been verified. The v1 store
  envelope and legacy `v1:` values authenticate no associated data: they are not
  bound to a path, project or variable name beyond the scoped key inside the
  encrypted store plaintext
- the daemon's env HTTP route (used by the macOS app) reads and writes the legacy dotenv-shaped
  contract (`source: 'plain_env'|'keychain'`, `resolvedFrom: 'dotenv'/'process'/'keychain'/'portable_backend'`),
  not the modern YAML `hack env list --json` shape; there is no web dashboard surface anymore

If you are writing new docs or new project setup flows, document the YAML overlay model first and treat `.hack/hack.env.json` as legacy migration context.

## Recommended project policy

- Commit `.hack/hack.env.default.yaml`
- Commit `.hack/hack.env.<overlay>.yaml` when the overlay is team-shared
- Never commit `.hack.secret.key`
- Prefer `hack env add` over hand-editing encrypted values
- Enter secrets with `--value-stdin` or the hidden prompt, never as command arguments
- Prefer direct runtime injection over materializing `.hack/.env`
- Use `hack host exec` or env-aware sessions for host-side scripts like migrations, generators, and admin tasks

## Related docs

- [Initialize a project](/docs/v5/guides/init-project)
- [Sessions](/docs/v5/sessions)
- [CLI reference](/docs/v5/cli)
- [Env and secrets threat model](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/security/env-secrets-threat-model.md): assets, trust boundaries, current mitigations and open gaps
- [Env secret security decision and rotation gates](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/security/env-secrets.md)


### Host command lifetime and diagnostics

`hack host exec` and `hack env exec` record payload-free execution metadata under
`$HACK_HOME/host-commands` (normally `~/.hack/host-commands`). Records contain the
executable basename, project, process identities, owned process group, intended
lifetime, elapsed time, exit/cancellation/timeout outcome, and final child CPU/RSS
accounting. Arguments, shell strings, environment values and command output are
not recorded. Completed records expire after seven days during later executions;
interrupted records remain available for review. A diagnostic storage failure
warns on stderr and preserves command execution and exit status.

```sh
hack host exec --timeout 60 -- bun scripts/check.ts </dev/null
hack env exec --timeout 30 -- bun scripts/probe.ts </dev/null
hack host exec --lifetime persistent -- bun run dev
hack host ps --json
hack host ps --project my-project
```

`--timeout` is a positive number of seconds. It sends SIGTERM to the owned process
group, escalates after two seconds, and returns 124. It currently requires
non-TTY stdin; piping input or redirecting from `/dev/null` preserves a safe group
boundary without changing interactive terminal job control. There is no default
timeout. `--lifetime persistent` declares intent and does not detach or create a
mux session; it cannot be combined with a timeout. Persistent commands still
respond to explicit cancellation. Use lifecycle processes or `hack session` for
managed persistent workspaces.

`hack host ps` also inspects existing lifecycle sessions using their stored mux
ownership evidence. It is read-only: missing wrappers and unverified groups are
reported for review and never killed. A PID must match its recorded start time
before live command metrics are attributed to it. Lifecycle definition freshness
is not revalidated by this resource snapshot. Commands started before tracking was
available cannot be retroactively assigned ownership.

Live CPU time is the cumulative CPU of currently observed tree/group members;
short-lived descendants already gone are not included. Final CPU comes from the
OS-reaped child resource usage and is a separate accounting source. RSS sums may
count shared memory more than once. Missing observations are null, not zero.
SIGKILL cannot be intercepted: interrupted records may lack a completion result,
and group members without a surviving identity are explicitly unverified.

See [runtime performance diagnostics](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/performance.md) for project-listing timings,
container details, watcher measurements and read-only cleanup previews.

### Disabling native keychain access

`HACK_SECRETS_DISABLE_KEYCHAIN_FALLBACK=1` disables native keychain reads, writes,
and deletes, including `hack secrets`, project keychain stores, and macOS node
auth tokens. All three operations throw an explicit disabled error.
Encrypted-file stores still accept a configured key file or `HACK_SECRETS_FILE_KEY`,
and can generate a new key file when no encrypted store exists.

`bun test` loads `tests/preload.ts`, which sets this flag and replaces `Bun.secrets`
with an in-memory backend. Tests that exercise keychain behavior can temporarily
clear the flag; the preload still prevents native keychain access. Child CLI
processes inherit the flag, so tests must pass it through when supplying a custom
process environment. The in-memory backend is cleared after each test.


---

<!-- Original: docs/lifecycle.md; revision: 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; SHA-256: 4b5f32c9082e98346f0e37fc516901460cced89a7df4ba820639d114b7fba758; URL: https://hack.foo/docs/v5/lifecycle -->
# Lifecycle (startup hooks + host processes)

Many projects need host-side setup around `hack up` (auth, local proxies, tunnels). Lifecycle config lets you run short-lived commands and manage long-running host processes alongside the project runtime.

Lifecycle is configured in `.hack/hack.config.json` under `lifecycle`.

You can also use a shorthand `startup` array for common `hack up` startup flows.

For project-wide `up` and `restart`, Hack resolves hook environment and checks registry
credentials before running `lifecycle.up.before`. After successful preparation, it
renders internal host, branch, dependency-cache and runtime-metadata overrides for
Compose. Extra-host registrations made by a before hook therefore apply on that same
start; replacements and removals are reflected too. Explicit extra hosts also work
when internal DNS and TLS are disabled. This does not reload arbitrary project config
or replace the hook environment after a hook runs.

A failed before hook prevents the Compose up phase. Service-scoped operations retain
their existing behavior and do not run project-wide hooks. Hook code should use the
supported integration that owns its host registrations rather than hand-editing Hack's
generated internal files.

## Why `singleton` exists

Some lifecycle-managed helpers bind fixed local ports and are easy to start outside Hack:

- AWS SSM port-forwarding tunnels
- local API or database proxies
- search/dashboard tunnels

Without an ownership hint, `hack up` can only assume it should launch the configured command again. If a
matching helper is already running manually, or a previous reconnect loop already restored it, that can
create duplicate supervisors, partial port conflicts, or aggressive cleanup/restart churn.

`singleton` exists to make those fixed-port helpers explicit. It gives Hack a conservative rule:

- start the helper when none of its expected listeners exist
- adopt the existing helper when every expected port is already occupied and the config opts into reuse
- fail fast on partial occupancy instead of trying to replace part of a live tunnel stack

That keeps Hack local-first and predictable. It avoids turning "something equivalent is already running"
into "kill and recreate it", which is especially important for brittle port-forwarding workflows.

Adoption only checks that every configured port is occupied. It is not a health, identity, or readiness
check: an unrelated service that happens to hold the same ports is adopted too, and an adopted tunnel may
still be reconnecting. When the wrong listener would matter, pair `onConflict: "adopt"` with a
`lifecycle.up.before` hook that verifies the listener's identity (for example, a request to a known
endpoint) and fails when it does not match.

The [shared host helper lifecycle contract](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/shared-host-lifecycle.md) defines the
identity-verified alternative: adoption only after the listener names the expected helper and upstream,
exact PID-plus-start-time claims, serialized starters, and release that never signals a foreign
process. Projects use it through [`lifecycle.sharedHelpers`](#shared-helpers); `singleton` is unchanged.

## Config

```json
{
  "$schema": "https://schemas.hack/hack.config.schema.json",
  "lifecycle": {
    "up": {
      "before": [
        { "name": "aws sso login", "command": "aws sso login", "cwd": "." },
        {
          "name": "aws-ssm-proxy",
          "command": "bun run proxy",
          "cwd": "packages/infra",
          "persistent": true,
          "singleton": {
            "ports": [3306, 9200, 9201, 8443, 8444, 8445],
            "onConflict": "adopt"
          }
        }
      ],
      "after": []
    },
    "down": {
      "before": [],
      "after": []
    },
    "processes": [
      {
        "name": "aws-proxy",
        "command": "bun run dev:aws-proxy",
        "cwd": "."
      }
    ]
  }
}
```

## Startup shorthand

`startup` is a concise alias for startup hooks/processes:

- `persistent: false` (default) maps to `lifecycle.up.before`
- `persistent: true` maps to `lifecycle.processes`

```json
{
  "$schema": "https://schemas.hack/hack.config.schema.json",
  "startup": [
    {
      "name": "aws sso",
      "run": "aws sso login",
      "persistent": false
    },
    {
      "name": "aws-ssm-proxy",
      "run": "cd packages/infra && bun run proxy",
      "persistent": true,
      "singleton": {
        "ports": [3306, 9200, 9201, 8443, 8444, 8445],
        "onConflict": "adopt"
      }
    }
  ]
}
```

Each startup item can be:

- a string command (one-shot startup hook), or
- an object with:
- `run` (or `command`) required
- `name` optional
- `cwd` optional
- `persistent` optional boolean (default `false`)
- `singleton` optional object with `ports` and optional `onConflict`

`cwd` is always resolved from the repo root (not from `.hack/`).

A `persistent: true` startup entry with no `name` gets a generated name (`startup-1`, `startup-2`, ...
in config order). That generated name is what shows up as the window name and what you pass to
`hack logs <name>`, so naming persistent entries explicitly makes logs easier to find.

### Hooks

Hook lists live under:
- `lifecycle.up.before`
- `lifecycle.up.after`
- `lifecycle.down.before`
- `lifecycle.down.after`

Each entry can be either:
- a string (shell command), or
- an object:
- `name` (optional): label for logs
- `command` (required): shell command
- `cwd` (optional): working directory; relative paths are resolved from repo root
- `persistent` (optional): `true` means "start this as a managed lifecycle process"
- `singleton` (optional): local listener policy with:
- `ports` required array of local TCP listener ports
- `onConflict` optional `"adopt"` or `"fail"` (default `"fail"`)

Hooks run on the host as `sh -c <command>`. Failures stop the operation.
Commands inherit the CLI process environment (including PATH), plus resolved project env vars.

`persistent` behavior:
- In `lifecycle.up.before`, `persistent: true` starts the command in the lifecycle mux session and immediately continues to the next hook.
- Ordering is preserved: each persistent hook is started in sequence before moving to later hooks.
- In other hook lists (`up.after`, `down.before`, `down.after`), `persistent` is ignored and the hook runs as a normal blocking command.

`singleton` behavior:
- Hack checks the configured local TCP listener ports before starting the lifecycle process.
- If none of the configured ports are in use, Hack starts the process normally.
- If all configured ports already have listeners and `onConflict` is `"adopt"`, Hack skips startup, records an adoption note, and leaves the external process alone on `hack down`.
- If only some configured ports are already occupied, Hack fails fast instead of launching a competing partial replacement.
- If all configured ports already have listeners and `onConflict` is omitted or `"fail"`, Hack stops with an explicit error so the operator can decide whether to stop or reuse the existing process.

Important boundaries:
- `singleton` is a listener-level guard, not a health, identity, or readiness check. Adopt only checks that every configured port is occupied; pair it with a `lifecycle.up.before` identity check when a foreign listener on the same port would cause harm.
- Adoption means "Hack observed the full expected local listener set and will not start another copy". It does not mean Hack now owns or can safely tear down that external process.
- `hack down` only stops processes Hack actually launched inside the lifecycle session. Adopted external listeners are intentionally left alone.

### Processes

Long-running processes live under `lifecycle.processes` and are objects with:
- `name` (required): stable identifier (used for window naming)
- `command` (required): shell command (run in a mux session shell)
- `cwd` (optional): working directory (defaults to repo root)
- `singleton` (optional): listener-ownership policy with `ports` and `onConflict`

Processes receive the resolved env contract (see `env.md`) as their environment.

### Shared helpers

`lifecycle.sharedHelpers` declares host helpers that several branches (or projects) share
through one fixed loopback port, under the
[shared host helper contract](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/shared-host-lifecycle.md). Unlike `singleton`, a
listener is adopted only after it proves its identity, and Hack stops a helper only when it
started it and the last branch using it is released.

```json
{
  "lifecycle": {
    "sharedHelpers": [
      {
        "name": "issuer-bridge",
        "command": ["bun", "run", "bridge"],
        "cwd": "tools/issuer-bridge",
        "port": 4100,
        "upstreamEnv": "ISSUER_UPSTREAM",
        "env": ["ISSUER_TOKEN"]
      }
    ]
  }
}
```

- `name` (required): helper kind. The helper must answer `GET http://127.0.0.1:<port><identityPath>`
  with JSON `{"helper": "<name>", "upstream": "<upstream>"}` (an optional `pid` must be its own).
- `command` (required): argv array, executed directly, never through a shell string.
- `port` (required): the loopback port. `name` and `port` must be unique in the list.
- `upstream` or `upstreamEnv` (exactly one): the upstream this instance needs, literally or
  from a variable in the resolved lifecycle env (then the CLI environment). Use
  `upstreamEnv` with an env overlay when branches need different upstreams.
- `identityPath` (default `/__hack/identity`), `cwd` (repo-root relative),
  `enabled` (default `true`), `readyTimeoutMs` (default 30000, at most 600000).
- `env`: variable names passed to the helper. It also gets `PATH`; nothing else from the
  CLI environment is inherited. A listed name that is not set fails `hack up`.

An invalid `sharedHelpers` entry is refused, not skipped: `hack up`, `hack down` and
`hack restart` fail with `E_LIFECYCLE_FAILED` before any hook, helper, lifecycle process or
Compose command runs. This is stricter than other config parse errors, which these commands
only warn about. Fix the entry and run the command again.

Behavior:
- `hack up` and `hack restart` ensure each helper after `lifecycle.up.before` hooks and before
  `lifecycle.processes`. Each instance (`<project>` or `<project>--<branch>`) is one holder.
  A healthy helper is reused; an identity-matching helper someone else started is adopted;
  otherwise Hack starts it and waits until its identity endpoint answers.
- A port held by anything else (another helper, the wrong upstream, a silent listener) fails
  `hack up` with `E_LIFECYCLE_FAILED` and a closed reason; that process is left running.
  Messages never include upstreams, argv or environment values.
- If `hack up` fails later, or receives SIGINT/SIGTERM at any point while helpers or
  lifecycle processes start, Hack releases only the holders that run added and stops a
  helper it had just started. Overlapping `hack up` runs of the same instance are ordered by
  an instance lock; an earlier run's rollback never releases a holder after a later run of
  that instance has started (the holder stays recorded until `hack down`). Holders of
  containers that may still be running are kept instead (see below).
- A disabled helper (`enabled: false`) needs none of its `env` or `upstreamEnv` values.
- A project with `sharedHelpers` and a lifecycle session (lifecycle processes or a
  persistent `up.before` hook) needs tmux for that session. With zellij selected,
  `hack up` and `hack restart` fail with `E_LIFECYCLE_FAILED` before any hook,
  helper or process runs: zellij records the session's ownership after creating
  it, so an interrupted start could leave a session `hack down` cannot reclaim.
  Install tmux or set `sessions.mux` to `tmux`. If the selection changes to zellij
  while hooks run, the start fails when it chooses the session's backend, before
  creating the session, and rolls back the helper holders it added. zellij
  support is tracked in HACK-1849.
- `hack down` releases the instance's holder. A helper still used by another branch keeps
  running; the last release stops a helper Hack started and never signals an adopted one.
  Down releases every helper the instance acquired, recorded at start, so removing or
  renaming an entry (or switching to a revision without it) does not strand its holder.
- A release that fails or cannot confirm the stop keeps the claim and fails `hack down` and
  `hack restart` with `E_LIFECYCLE_FAILED` (non-zero exit, the helper names in `detail`).
  Fix the claim and run `hack down` again.
- Holders are released only after the instance's containers and lifecycle session
  stopped. `hack restart` keeps the containers running, so it keeps their holders and
  reuses the helpers. Once a detached `hack up` or `hack restart` started the
  containers, a later failure (such as a failing `up.after` hook) stops the lifecycle
  processes but keeps the holders for `hack down`. If Compose fails or times out while
  starting containers (including a failed restart repair), the holders are kept unless
  `docker compose ps` confirms that no container of the instance may still run.
  SIGINT/SIGTERM once a container start has begun keeps the holders too (the start may
  still be starting services). If `docker compose down` fails, times out or is interrupted, the holders are
  kept (with a warning) and the command fails with Compose's error; run `hack down`
  again. A successful `docker compose down` is not enough on its own: it uses the current
  Compose file without `--remove-orphans`, so a container of a service the file no longer
  declares (an orphan) can keep running while Compose exits 0. Before releasing the
  holders, Hack therefore lists every container labelled with the instance's Compose
  project (`com.docker.compose.project=<project>`, orphans included). It releases them
  only when none is running, restarting, paused or in another state that may run
  (created, exited and dead containers do not count). If one may still run, or the
  listing fails or times out, the holders are kept, the warning names the containers (or
  the failed check), and the down fails with `E_LIFECYCLE_FAILED`. Stop the remaining
  containers (for example with `docker compose -p <project> down --remove-orphans`), then
  run `hack down` again to release the holders. If the session stop fails or cannot be confirmed (including when tmux cannot
  say whether the session exists), the session's processes may still use the helpers: `hack
  down`, `hack restart` and native retirement keep every holder, warn, and fail the same
  way. Run `hack down` again once the session can be stopped. Likewise, an up whose failed
  start kept its lifecycle session (its stop could not be confirmed) keeps the holders it
  added.
- A `hack down` that overlaps a `hack up` of the same instance (same branch):
  - `hack down` marks the instance as stopping once the down is committed: after its
    `lifecycle.down.before` hooks succeed (and, on the native path, after the ownership and
    finalization rechecks that follow them), right before Compose or graph shutdown. A down
    refused before that point supersedes nothing. Its release
    removes the instance's operation record. Both advance the instance's shutdown
    generation.
  - A down supersedes every `hack up` of the instance whose lifecycle preparation began
    before it, even after a later `hack up` succeeds. Preparation begins just before the
    `lifecycle.up.before` hooks run, so a down that completes while those hooks run also
    supersedes that up: it fails with `E_LIFECYCLE_FAILED` before starting any helper. The
    later up's helpers need not be the earlier up's (an entry may have been disabled or
    changed), so the earlier up never counts as current again.
  - **Prevented during preparation.** A `hack up` checks the instance right before its
    containers start (after detached image preparation, before an attached `up`, and at the
    end of native preparation). If a down marked or released it by then, that up fails with
    `E_LIFECYCLE_FAILED` and starts no container.
  - **Detected after launch, not prevented.** The check takes the instance lock only
    briefly, so a down can still complete between the check and container start, or while
    containers start. The up checks again after Compose returns: a detached up then fails
    with `E_LIFECYCLE_FAILED` (its containers may already run); an attached up only checks
    after Compose exits. In that case run `hack down` for the branch (`--branch <name>`) to
    stop the containers, then `hack up` again.
- Two overlapping `hack up` runs of the same instance, with no down in between:
  - The newer up does not supersede the earlier one: an earlier, slower up still starts,
    because the newer up holds the same helpers.
  - The up that created the lifecycle session stops it on failure (or SIGINT/SIGTERM) only
    if no other up adopted it since. Hack records each session adoption and creation under
    the shared helper instance lock, so this holds whichever up ensured its helpers first.
    An up that only adopted the session never stops it.
  - An up whose lifecycle session another up replaced while it was still starting (its
    entry was still pending) fails with an error saying so. It does not publish over the
    replacement, start processes or set environment in it, or stop it; the replacement
    stays owned and `hack down` can stop it.
  - These guarantees hold for tmux commands that finish within their time limit
    (15 s). Hack stops waiting for a command that does not, and treats its outcome
    as unknown, but a stalled tmux server can still apply it later. A late kill
    or window command from an earlier up can then stop or change a newer up's
    session of the same branch; `hack down` and `hack up` recover it. A late
    session creation leaves an empty session that the next `hack up` refuses;
    stop it with tmux. Closing this gap is tracked in HACK-1849.
  - A failed up releases only the helper holders it added, and only while it is the latest
    up of the instance to have its helpers ready and no `hack down` has started since
    (including one that was interrupted); otherwise the next `hack down` releases them.
  - The failed up's other failure handling is unchanged (for example, it still clears the
    instance's runtime-state entry), so check `hack ps --branch <name>` after such an
    overlap.
  - This applies to projects with `sharedHelpers`. If the shared helper instance lock stays
    busy for 10 s (for example, a third up is still waiting for a slow helper), ownership
    cannot be decided: the failed up keeps the lifecycle session and its helper holders,
    warns, and leaves them for `hack down` to stop.
- Claims live under `~/.hack/shared-helpers/<name>-<port>/` (or `$HACK_HOME`), shared by
  every project and branch that uses that helper name and port.
- Helpers are not part of the lifecycle mux session and do not appear in `hack logs`.

## Visibility

Lifecycle output is now surfaced across CLI/runtime views:

- `hack logs` includes lifecycle hook/process output alongside compose logs.
- `hack logs <service>` supports lifecycle service names, including persistent process names.
- `hack projects --details` includes a `Startup & lifecycle` section with hooks + persistent processes.
- Runtime inventories include persistent lifecycle processes as synthetic services.
- The macOS project detail view includes a `Startup & Lifecycle` section in the main project overview.

## Runtime behavior

### `hack up`

1. Resolve env contract (and optionally prompt for missing required env in interactive shells).
2. Run `lifecycle.up.before` hooks in order.
3. For `up.before` hooks with `persistent: true`, start each as a managed lifecycle process and continue immediately.
4. Start lifecycle processes (if any) inside the same dedicated lifecycle session.
5. Run `docker compose up` (or `up -d` when `--detach`).
6. Run `lifecycle.up.after` hooks.

Before starting persistent work, Hack reconciles the expected lifecycle session with
`.hack/.internal/lifecycle/state.json`:

- A session whose mux ownership token, saved definition hash, and live process windows all match is
  adopted without starting duplicate processes.
- A token-owned stale session is replaced. Pre-ownership tmux sessions are replaced only when saved
  state, checkout path, creation time, and window count provide deterministic legacy ownership proof.
- A same-name session without matching ownership proof is left untouched and `hack up` fails with an
  actionable collision error.

If the operation later fails in Compose or `up.after`, Hack removes only the lifecycle session created
by that operation. The same exact-token cleanup runs for supported `SIGINT` and `SIGTERM` paths, including
signals received while the mux session is still being initialized.

### `hack down`

1. Run `lifecycle.down.before` hooks.
2. Run `docker compose down`.
3. Stop lifecycle processes by killing the lifecycle session.
4. Run `lifecycle.down.after` hooks.

If `lifecycle.down.before` fails, shutdown is aborted before Compose or lifecycle processes are
stopped. `hack restart` preserves the same guard semantics during its down phase.

If a concurrent foreground finalizer removes the same owned lifecycle session during shutdown,
Hack accepts a fresh, explicit absence check. Missing ownership metadata by itself, a changed token,
or an unavailable session check still refuses cleanup.

### `hack restart`

`hack restart` runs the down lifecycle hooks and stops owned host processes, but preserves the
current Compose runtime until preflight succeeds. It then force-recreates services and attempts a
repair start if recreation fails. This avoids destroying a healthy stack before env and registry
checks have passed. `hack restart <service...>` is service-scoped: it skips project-wide lifecycle
hooks, initializes declared shared dependency caches before replacing their selected consumers,
uses `--no-deps`, and verifies only the selected services. Failed cache initialization leaves the
existing consumers running.
From the primary checkout, it targets only the base Compose/lifecycle instance. A linked worktree uses
its isolated derived branch instance, and `--branch <name>` targets only that explicit branch.

### `--json`

`hack up`, `hack down`, and `hack restart` accept `--json`. A lifecycle hook failure surfaces as
`{ok: false, error: {code: 'E_LIFECYCLE_FAILED', message}}`; a `docker compose` failure surfaces as
`E_COMPOSE_FAILED`. If Compose exits successfully but one or more containers remain `created`, exit
non-zero, or enter another failed runtime state, Hack returns `E_STARTUP_INCOMPLETE`. Successful
one-shot services (`exited` with code 0) are reported under `services.completed` and do not fail startup.
Hack recognizes dependency installers, services labeled `hack.service.one-shot=true`, and services
referenced by another service with Compose `condition: service_completed_successfully`. An unrelated
service that merely exits zero is still treated as incomplete startup.
Lifecycle failures are one of the primary consumers of the `--json` error envelope,
since hook and process startup are common failure points around `hack up`.

## Sessions backend

Lifecycle processes run inside the configured mux backend (tmux or zellij), using the same selection rules as `hack session`.

Config:
- Project: `.hack/hack.config.json` → `sessions.mux = auto|tmux|zellij|none`
- Env override: `HACK_SESSIONS_MUX=auto|tmux|zellij|none`

Lifecycle session name:
- No branch: `<project>--lifecycle`
- With `--branch <name>`: `<project>--lifecycle-<branch>`

Lifecycle hooks and processes run on the host. They receive the selected overlay's `global` values
plus `host` overrides, with `host` taking precedence. Service-scoped values remain container-specific
unless a host command explicitly selects that scope with `hack host exec --scope <service>`.

Notes:
- If no mux backend is available, lifecycle process startup fails with an actionable error.
- Teardown is implemented by killing the lifecycle session; anything running inside that session will be stopped.
- Current lifecycle sessions carry the same random ownership token in mux metadata and persisted state.
  Cleanup requires an exact token match; deterministic names alone never authorize session teardown.
- Healthy-session adoption also matches a stable SHA-256 fingerprint of the effective overlay and
  sorted lifecycle environment. Environment names, keys, and values are never persisted; changing an
  overlay or value replaces the owned session so host helpers cannot retain stale configuration.
- For tmux-backed lifecycle sessions, Hack also persists the pane PID and the wrapped command's actual
  process-group metadata to `.hack/.internal/lifecycle/state.json`, with per-hook/process output logged to
  `.hack/.internal/lifecycle/*.log`. If tmux pane state disappears before teardown, `hack down` still uses that persisted metadata to clean up any live lifecycle process groups instead of leaving orphaned host processes behind.
- `hack doctor` reports stale lifecycle state, leaderless process groups, ownership collisions, and
  ownership-proven sessions with no running Compose instance. Recently updated sessions are treated
  as possible in-flight startups for five minutes and stay untouched. `hack doctor --fix` reaps only
  established orphans after rechecking runtime liveness and mux ownership; unverified same-name
  sessions stay untouched.
- Runtime hygiene also warns when regular Compose services are stuck in `Created`, including stacks
  left behind by an interrupted startup. This check is diagnostic only; inspect the explicit target
  with `hack ps --json` before deciding whether to retry or tear it down.

## Tips

- For long-running setup commands, use either `lifecycle.processes` or `lifecycle.up.before` with `persistent: true`.
- For local proxy/tunnel helpers that bind fixed ports, prefer `singleton.ports` with `onConflict: "adopt"` so `hack up` can reuse an already-running external tunnel instead of racing it. Adopt only checks that every configured port is occupied, not health, identity, or readiness; pair it with a `lifecycle.up.before` identity check.
- Keep non-persistent hooks short and deterministic.
- Store lifecycle secrets in `hack.env.*.yaml` as encrypted `secure:` values and prefer runtime injection over relying on `.hack/.env`.
- If a hook requires interactive auth (e.g. browser-based SSO), it will still work; it runs with `stdin: inherit`.
- Global `--no-interactive` (or `HACK_NO_INTERACTIVE=1`) affects only the env-prompt step in `hack up`
  (step 1 above): with prompting disallowed, missing required env is never prompted for — the run
  fails fast with an actionable error instead of blocking on a prompt, following the same
  `--no-interactive` convention used across the CLI (documented defaults or `E_INTERACTIVE_REQUIRED`).
  It does not change hook `stdin` behavior — a hook that itself blocks on interactive auth still
  blocks under `--no-interactive`.


---

<!-- Original: docs/sessions.md; revision: 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; SHA-256: b8d2db60393945b8bfe2319be7021c47f04e0ca7c53f6c37fc82ef354c5a4ae8; URL: https://hack.foo/docs/v5/sessions -->
# Sessions

Sessions are **persistent project workspaces**. They keep a repo-root shell alive across terminal restarts, SSH reconnects, and long-running agent work so you can return to the same context instead of rebuilding it each time.

The guided default is **tmux**:
- `hack session` opens a tmux-first interactive picker
- `hack session start <project>` reuses the default project workspace unless you ask for an isolated one
- `hack session start <project> --env qa --service api` creates a stable env-scoped workspace when you need a specific overlay
- `hack setup tmux` installs the recommended popup binding so the picker is easy to reach from tmux

Other mux backends still exist. `sessions.mux=auto` prefers tmux and falls back to zellij when tmux is unavailable, and you can explicitly set `sessions.mux=zellij` if that is your preferred backend. The interactive onboarding and pane tooling are tmux-first today.

## Quick start

```bash
# Interactive picker for existing workspaces and new project workspaces
hack session

# Reuse the default workspace for a project, or create it if needed
hack session start <project>

# Create an env-scoped workspace for one overlay/service combination
hack session start <project> --env qa --service api --detach

# List active workspaces
hack session list

# Attach to an existing workspace by name
hack session attach <workspace>

# Queue a command in a running workspace
hack session exec <workspace> "bun test"

# Queue a command with injected env for that run
hack session exec <workspace> --env qa --service api "bun db:migrate"

# Stop a workspace
hack session stop <workspace>

# Capture recent output (defaults to active pane)
hack session capture <workspace>

# Tail workspace output for a short window (defaults to active pane)
hack session tail <workspace>

# List panes in a workspace
hack session panes <workspace>
```

## Core flows

### Interactive picker

Running `hack session` without arguments opens an interactive picker showing:
- **Active workspaces**: running workspaces from the configured mux backend(s), with attached status when the backend can report it
- **Available projects**: registered projects that do not currently have a default workspace

When selecting an attached session, you can choose to:
- **Attach**: detach other clients and take over the workspace
- **Create isolated**: start a separate long-running workspace such as `project--2`

This is the recommended entry point when you want to resume a project context but do not remember the exact workspace name.

`hack session` with no subcommand is inherently interactive (it prompts with a picker) and is not a
scripted/agent entry point. For scripted or agent-driven runs, use `hack session start <project>`
(optionally with `--detach`) or `hack session list --json` instead of the bare picker.

### Start and create

```bash
# Reuse the default project workspace (creates it if needed)
hack session start my-project

# Force creation of an isolated numbered workspace
hack session start my-project --new

# Create an isolated workspace with a custom suffix
hack session start my-project --name agent-1
# Creates: my-project--agent-1

# Prepare services before creating or attaching
hack session start my-project --up

# Create or reuse without attaching the current terminal
hack session start my-project --detach

# Create a stable env-scoped workspace
hack session start my-project --env qa --service api --detach
```

Default behavior is deliberate:
- The first workspace for a project is just the project name, for example `my-project`
- Passing `--env` or `--service` creates a stable scoped workspace name such as `my-project.env-qa.svc-api`
- `--new` or `--name` creates an isolated workspace for a second agent, experiment, or review lane
- `--detach` keeps the workspace alive for another tool or terminal to attach later

Workspaces are created at the project's repo root, not the `.hack/` directory.

### Attach

```bash
# Attach to an existing workspace
hack session attach my-project

# From inside tmux, this switches clients instead of nesting tmux
```

Use `attach` when you already know which workspace you want. If you are already inside tmux, hack switches clients instead of nesting tmux inside tmux. When attaching, tmux detaches other clients to avoid terminal size conflicts across multiple devices.
If the workspace is running in zellij, hack attaches to that named session directly instead.

### Stop

```bash
hack session stop <workspace>
```

`stop` kills the underlying mux session (`backend.killSession`) outright — anything still running
inside it, including a long-lived dev server or an in-progress agent task, is terminated. There is
no graceful shutdown step; if you need cleanup hooks to run first, do that before stopping.

### Exec

```bash
# Send a command to a running workspace
hack session exec my-project "bun test"

# tmux: sends the command + Enter to the active pane
# zellij: opens a new pane and runs the command because there is no active-pane equivalent

# Inject a selected overlay/service into the queued command
hack session exec my-project.env-qa.svc-api --env qa --service api "bun db:migrate"
```

Use `exec` when you want to drive a persistent workspace from another terminal, script, or agent without attaching interactively first.

If you pass `--env` or `--service`, Hack resolves the selected project env and injects it into the queued command without materializing `.hack/.env`.

### Listing panes (tmux only)

Use `hack session panes` to list panes with useful metadata (target, active flag, window/pane indices, command, path).

```bash
# List panes (NDJSON start/log/end)
hack session panes my-project

# Explicit NDJSON output (same as the default)
hack session panes my-project --json

# Single JSON object output
hack session panes my-project --pretty
```

`--json` and `--pretty` are mutually exclusive; passing both is an error.

### Capturing output (tmux only)

`hack session capture` emits NDJSON events by default for machine parsing (start/log/end). By default it targets the active pane; use `--target` to select a specific pane. Use `--pretty` for raw pane output; `--json` and `--pretty` are mutually exclusive.

```bash
# Capture last 200 lines (default) as NDJSON
hack session capture my-project

# Capture a specific pane target and line count (tmux pane targets use `:` and `.`)
hack session capture my-project --target my-project:0.1 --lines 500

# Human-friendly raw output
hack session capture my-project --pretty
```

### Tailing output (tmux only)

`hack session tail` also emits NDJSON events by default and stops after `--max-ms` (default 5000), polling every `--interval-ms` (default 500). By default it tails the active pane; use `--target` to select a specific pane. `--json` and `--pretty` are mutually exclusive.

```bash
# Poll capture-pane and emit only new lines for 5s (default)
hack session tail my-project

# Customize polling interval and max duration
hack session tail my-project --interval-ms 250 --max-ms 10000

# Human-friendly raw output
hack session tail my-project --pretty
```

## Remote access with SSH

Use `hack ssh` to get connection info for remote access:

```bash
# Interactive: choose Tailscale or direct SSH
hack ssh

# Use Tailscale SSH
hack ssh --tailscale

# Use direct SSH with hostname
hack ssh --direct --host 192.168.1.100

# Specify user and port
hack ssh --host example.com --user dev --port 2222

# Connect directly to a workspace
hack ssh my-session
```

### What `hack ssh` shows

1. **SSH command**: Copy-paste command to connect
2. **QR code**: Scan with mobile SSH apps (Blink, Termius)
3. **Active workspaces**: List of active workspaces on this machine, including the active mux backend when known
4. **Action picker**: Done or connect to a workspace

When you connect to an existing workspace, hack uses that workspace's backend. When you create a new one from the SSH flow, hack uses the configured default backend (`sessions.mux`).

### Tailscale setup

If Tailscale is stopped or not connected, `hack ssh` will prompt to start it:

```
Tailscale is stopped
? Turn on Tailscale? › yes
Starting Tailscale...
Tailscale connected!
```

### Terminal size conflicts

When multiple clients attach to the same tmux workspace, terminal size can get messed up. The session commands use `tmux attach -d` to detach other clients, avoiding this issue.

If you're already in tmux and want to switch workspaces without detaching:

```bash
# Inside tmux: prefix + s to open session switcher
# Or use the tmux command:
tmux switch-client -t <session>
```

## Configuration

Project config: `.hack/hack.config.json`

```json
{
  "sessions": {
    "mux": "auto"
  }
}
```

Values:
- `auto` (default): prefer tmux, fall back to zellij
- `tmux`: require tmux
- `zellij`: require zellij
- `none`: disable sessions

Env override: `HACK_SESSIONS_MUX=auto|tmux|zellij|none`

Global default:

```bash
hack config set --global sessions.mux zellij
```

Recommended onboarding:

```bash
# Install the tmux popup binding that launches the picker
hack setup tmux

# Keep tmux as the guided default, but switch globally if your team prefers zellij
hack config set --global sessions.mux zellij
```


---

<!-- Original: docs/guides/development-runtime-safety.md; revision: 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; SHA-256: 3dba0f7ef07c956b21781d7f281593b76854f9239c9b2793147abc0c048b23c7; URL: https://hack.foo/docs/v5/guides/development-runtime-safety -->
# Development runtime safety

Hack's development defaults must preserve hot reload without manufacturing host-wide CPU, memory,
or storage pressure. This guide records the runtime contract added after the 2026-07-30
OrbStack/Next investigation.

## Root cause and scope

The generated Compose path used to inject both `CHOKIDAR_USEPOLLING=true` and
`WATCHPACK_POLLING=true` into every discovered service. The injection was unconditional: Next and
non-Next services, small repos and bind-mounted monorepos, and runtimes with working native file
notifications all received the same polling policy. In the observed Apple Silicon workload,
polling combined with an unnecessary `linux/amd64` override and multi-gigabyte persistent `.next`
volumes. The result was sustained emulation/watcher CPU, very high cumulative writes, and a large
set of stopped branch containers and cache volumes.

The bounded comparison removed those project-level overrides without changing application code:
the Next 16 development server ran as native arm64, hot reload remained available through native
notifications, and idle container CPU settled near zero. A slow-filesystem warning remained for the
`.next` volume, which identifies storage as a latency factor but does not justify forcing polling.

Hack owns only two parts of that failure chain:

1. generated Compose defaults must not impose polling;
2. lifecycle targeting and optional cache cleanup must not silently abandon branch-owned resources.

Image platform selection and application health-check cadence remain explicit project configuration.
Hack does not rewrite them.

## File watching contract

Generated services rely on the container runtime's native file notifications. Hack does not add
Chokidar or Watchpack polling variables. A project can still set either variable on an individual
service when a measured runtime requires it:

```yaml
services:
  web:
    environment:
      CHOKIDAR_USEPOLLING: "true"
      WATCHPACK_POLLING: "750"
```

Keep polling service-scoped and measure CPU plus write activity after enabling it. Next's local
development guidance notes that Docker filesystem access on macOS and Windows can be slower than
host-local development; OrbStack likewise documents that bind mounts cross the macOS boundary
while named volumes remain on the Linux side. Those storage tradeoffs are separate from watcher
correctness.

## Branch rename contract

An implicit `hack down` in a linked worktree uses Docker's Compose labels and exact
`com.docker.compose.project.working_dir` evidence:

- no owned runtime: use the current sanitized Git branch, preserving normal behavior;
- exactly one owned runtime: target it, including when it is Created or stopped and the Git branch
  now has a different name;
- multiple owned runtimes: fail before Compose mutation and require `--branch <name>`;
- explicit `--branch`: always target that branch without inference;
- detached HEAD: continue to require an explicit branch;
- primary checkout: continue to target the base instance by default.

Canonical checkout paths prevent one worktree from stopping a sibling's runtime.

## Disposable cache cleanup contract

Ordinary `hack down` preserves every named volume. `hack down --prune-caches` is a narrow,
confirmation-gated addition for build caches. It removes only exact volume names observed on the
target containers, then independently verifies the volume's Compose project and logical-volume
labels. A named volume is eligible when every observed destination ends in `.next`, or when the
top-level Compose volume explicitly declares `hack.cache.disposable: "true"`.

The explicit label makes cleanup framework-agnostic without guessing whether destinations such as
`.turbo`, `target`, `.gradle`, or a generic `cache` directory contain disposable output:

```yaml
services:
  worker:
    volumes:
      - build-cache:/app/target

volumes:
  build-cache:
    labels:
      hack.cache.disposable: "true"
```

Runtime inventory mount records now expose the Docker volume `name` separately from `source`
(the engine storage path), so callers can inspect the same removal identity without guessing.

The cleanup intentionally excludes:

- bind mounts;
- database, Redis, application-upload, and dependency volumes unless explicitly marked disposable;
- external or unlabeled non-Next volumes;
- volumes owned by another Compose project or checkout;
- loose volume-name matches.

Use `--yes` only after reviewing the same project-scoped evidence. Hack does not infer disposability
from arbitrary volume names or mount paths because those signals cannot distinguish generated build
output from durable application data.

## Doctor boundary

This change does not add threshold-based doctor warnings for CPU, stopped-instance counts, volume
size, or `linux/amd64` on arm64. Those signals can be legitimate and require image/platform or
workload context that static configuration cannot prove. The generated-polling regression tests,
branch-ownership resolution, and confirmation-gated cleanup are deterministic; policy guesses are
left out of doctor until Hack can make them equally actionable.

## References

- [Next.js local development](https://nextjs.org/docs/app/guides/local-development)
- [Next.js Turbopack reference](https://nextjs.org/docs/app/api-reference/turbopack)
- [OrbStack volumes and mounts](https://docs.orbstack.dev/docker/file-sharing)
- [OrbStack efficiency](https://docs.orbstack.dev/efficiency)


---

<!-- Original: docs/guides/macos-browser-network.md; revision: 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; SHA-256: d88bddbf02f023f1238ce3a64d0bb6112c722939efc8c0c5cccc8329cc5f5b7b; URL: https://hack.foo/docs/v5/guides/macos-browser-network -->
# macOS browser cannot reach a local service

A successful terminal request does not prove that a browser can reach the same
service. On macOS 15 and later, Local Network access is controlled per application;
Apple exempts command-line tools launched from Terminal or SSH. See Apple's
[Local Network privacy explanation](https://developer.apple.com/documentation/technotes/tn3179-understanding-local-network-privacy)
and [permission settings guide](https://support.apple.com/guide/mac-help/mchla4f49138/mac).

## `.local` names need a one-time grant outside Safari

New projects use `<project>.hack.local` by default. macOS applies Local Network
privacy by name as well as by address: Apple's TN3179 treats a `.local` lookup
as local network activity because `.local` is the multicast DNS (Bonjour)
namespace. A browser that opens `https://my-app.hack.local` therefore needs
Local Network access, even though Hack's resolver answers with a loopback
address.

- **Safari** opens `.local` names without this permission.
- **Chrome, Firefox and other browsers** need it once per app. macOS asks the
  first time; if you declined, enable it in **System Settings → Privacy &
  Security → Local Network**, then fully quit and reopen the browser.

On macOS, Hack prints one hint line on stderr when a command opens or prints a
`.local` browser URL (`hack open`, `hack branch open`, `hack status` and
`hack projects`, and Doctor's browser check). The hint is shown at most once per
command and never appears inside `--json` output. Hack does not read, request or
change this permission for you.

If you prefer not to grant the permission, use a name outside `.local`:

- **OAuth alias:** enable `oauth.enabled` (or `hack init --oauth`) and open the
  project's `<project>.hack.gy` alias. `hack open` prefers it automatically;
  `hack open --prefer alias` requires it.
- **Custom suffix:** choose a dedicated suffix under `hack.gy`, for example
  `dev.hack.gy`. With the native candidate, run
  `hack global dns preview --domain dev.hack.gy` and then
  `hack global dns activate --domain dev.hack.gy`
  (see [native candidate DNS](/docs/v5/native/full-reference)). With the Docker-backed
  stack, set `hack config set --global default_domain <suffix>` and run
  `hack global install` (see [Initialize a project](/docs/v5/guides/init-project)).
  Existing project hosts are not migrated automatically.

Avoiding `.local` avoids only the name-based rule. Address-based checks still
apply, so verify the exact origin in the browser as described below.

## Diagnose a browser failure

Run `hack doctor` first. DNS, resolver, Caddy, project services and certificate trust
have separate checks. The browser check remains unverified until you report an
observation; Doctor does not read the browser's permissions or its private data.

## Compare the same URL

Open your local service URL in the affected browser, then report what you observed:

```sh
hack doctor --browser-url https://admin.my-project.hack.local --browser-result fails
```

Use your actual hostname, including a legacy or custom domain if configured. The
URL must be an HTTPS origin (no path beyond `/`, credentials, query or fragment).
Choose a safe, read-only root page that needs no authentication. Doctor makes a bounded request with
normal certificate verification, without browser cookies or following redirects.

`--browser-result` accepts:

| Value | Observation |
| --- | --- |
| `unknown` | You have not checked the browser yet (the default). |
| `works` | The same URL loaded successfully in the affected browser. |
| `fails` | The browser failed; the cause is unknown. |
| `permission-denied` | You observed a Local Network denial or confirmed that the affected app's permission is off. |

If CLI HTTPS succeeds while the browser fails, Doctor identifies a browser-specific
boundary and suggests checking Local Network access. This is a possible cause, not
proof: browser certificate state, proxy settings or extensions can also differ.
A CLI DNS, TLS, connection, redirect or unsuccessful HTTP response keeps the comparison
ambiguous; address those findings before attributing the failure to privacy.
A redirect response proves only that the original endpoint responded, not that
its destination works. Browser results are your report, not an automated test.

## Recover and verify in the browser

1. Open **System Settings → Privacy & Security → Local Network** and inspect the
   affected browser or app. If access is disabled and you intend to allow it,
   enable that app's access yourself.
2. Fully quit and reopen that browser, then open the **same URL** again. If it
   works, rerun the command with `--browser-result works` to record the recheck.
3. If it still fails, retain the exact browser error and compare Doctor's other
   findings. Certificate errors need the
   [macOS certificate trust checks](/docs/v5/guides/macos-certificate-trust). If the app is
   absent from Local Network settings, absence alone does not establish denial.

Doctor, including `--fix`, does not change these privacy settings or restart your
browser. Do not disable TLS verification, reset system privacy databases or turn
off network security to make the diagnostic pass. The check is macOS-specific;
other platforms report it as not applicable.


---

<!-- Original: docs/guides/macos-certificate-trust.md; revision: 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; SHA-256: cc0f6df0095daf76f3b5c3c42d20173cd813c0948155276590a975817cc1cd06; URL: https://hack.foo/docs/v5/guides/macos-certificate-trust -->
# macOS certificate trust

After Caddy rotates its local root CA, an older trusted certificate with a similar
name does not establish trust in the new root. `hack doctor` checks the exported
CA's validity dates, exact certificate identity in the System keychain, macOS TLS
trust evaluation, and inclusion in Hack's host CA bundle.
It also reads the public root from the running Caddy container and compares its
certificate bytes with the export. An old export, old keychain entry and old host
bundle agreeing with one another cannot establish that Caddy's current root is
trusted. An unavailable runtime is reported as unverified, not healthy.

Run `hack global trust` to export the current root from the running Caddy instance,
install it in the System keychain, and refresh the host trust bundle and shell
environment. The keychain step uses the local administrator prompt. Never send an
administrator password to an agent or put it in a command. Non-interactive runs
skip this step when sudo would need a password; host environment preparation can
still finish independently.

`hack doctor --fix` can offer the same repair. After installation, Hack verifies
trust again before reporting success. Fully quit and reopen Chrome if it retains
the old trust state. Existing roots are preserved because another local service
may still depend on them.

Refreshing a stale public CA export is a separate confirmation from system trust.
Doctor rechecks the running root after confirmation and replaces only the export;
it leaves an existing export intact if the runtime cannot be verified. It refuses
symlink or non-regular export destinations. An expired, not-yet-valid, malformed
or non-CA certificate is refused before native import or host trust-bundle changes.
The export must contain exactly one PEM certificate, with no appended certificates
or other content, and fit within 64 KiB.
Trusting an expired root cannot renew it: investigate Caddy's PKI state first.

These checks concern the exported root and host configuration. They do not prove
that every running service presents a valid leaf certificate or that an existing
browser process has refreshed its trust state.

## Superseded Caddy roots

Each Caddy rotation or reinstall can leave an older root in the System keychain.
Doctor's `superseded caddy roots` check lists them. It reads the same System
keychain listing as the trust check and counts self-issued CA certificates with
the current root's subject but different certificate bytes. It ignores the year
in Caddy's root name, so a stale `2025 ECC Root` belongs with a live
`2026 ECC Root`. It also counts how many are expired or not yet valid. The
current root and roots with unrelated names are never counted.

The check is informational. A superseded root is never accepted as current trust.
Doctor and `hack doctor --fix` never remove keychain certificates, because
another local service may still depend on an older root. The JSON output adds a
`supersededRoots` object with `count`, `expired`, `notYetValid` and up to 32
public SHA-256 fingerprints (`sha256`), and nothing else. Both the Docker and
native Doctor paths run this check.

To remove a superseded root yourself:

1. Run `hack doctor --json > doctor-before.json` and note the
   `superseded caddy roots` count and the SHA-256 fingerprint you intend to remove.
2. List the matching keychain entries with their hashes:
   `security find-certificate -a -Z -c "Caddy Local Authority" /Library/Keychains/System.keychain`.
   Find the entry whose `SHA-256 hash` line equals a fingerprint from Doctor and
   copy the `SHA-1 hash` from that same entry. Use only a fingerprint that Doctor
   listed. A name match alone is not enough.
3. In your own terminal, run
   `sudo security delete-certificate -Z <SHA-1> /Library/Keychains/System.keychain`.
   Enter your password only at the native macOS administrator prompt. Never give
   an administrator password to an agent or put it in a command.
4. Run `hack doctor --json > doctor-after.json` and confirm that the count dropped
   and the removed fingerprint is gone. The current root's trust check must still
   pass.

The two files are a before and after record. That check holds only counts and
public fingerprints, but the full Doctor report holds other local details, so
review both files before you share them.


---

<!-- Original: docs/guides/codex-managed-environments.md; revision: 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; SHA-256: ad34fe362f5e09b3c290c680023924d03a5d839da1cab8f3e5dd953eefb9ed5e; URL: https://hack.foo/docs/v5/guides/codex-managed-environments -->
# Hack in Codex Cloud and remote development environments

Use the existing repository, its encrypted env configuration, and its pinned
dependencies to prepare a development environment on another machine. Start by
choosing the target and Hack version explicitly. A portable CLI installation gives
you env resolution and host commands; starting a full application also requires
that project's runtime, services, network access, and credentials.

The optional `hack-remote` skill guides this workflow. A plugin on your laptop does
not install Hack or enroll a cloud machine. Confirm that the skill is available in
the target task, for example through the repository's supported skill location.

## Choose the execution path

| Target | Useful existing path | Check before starting the app |
| --- | --- | --- |
| Codex Cloud or a managed CI container | Portable/slim CLI and the repository's host commands | Toolchain, key injection during the task, network access, and required services |
| Existing remote development machine with Docker | Hack's Compose workflow | Working Docker Engine and Compose, project dependencies, lifecycle hooks, routing needs |
| Apple Silicon Mac testing v5 | Explicit native prerelease channel | Verified bundle, provider preparation, isolated native home, application acceptance |

The native prerelease installer currently targets Apple Silicon macOS. It is not a
Linux installer or a qualified nested-VM provisioning path. See
[candidate installation](/docs/v5/native/install) and
[native candidate preparation](/docs/v5/native/full-reference). Do not use the unsupported
Hack node/gateway/dispatch surface as a fallback.

For an existing remote machine, establish its identity and the intended checkout
before installation. Read `AGENTS.md`, inspect `git status --short`, and check
`uname -s` and `uname -m`. Creating a cloud machine, publishing or sharing an
environment, and making privileged host changes require authority for that target
and effect. Ordinary setup should reuse the project's existing development path.

## Select a CLI without replacing another channel

Use a reviewed absolute executable path throughout setup and verification. Check
its `--version` and `--help`; do not assume the first `hack` on PATH is the desired
version. An installed native candidate must use its channel launcher, for example
`$HOME/.hack-next/bin/hack-next`. That launcher selects the verified executor and
the version's private homes. Running its raw `hack-cli` binary is not equivalent.

For a portable installation, select a published stable release that contains
`hack-codex-install.sh` and the matching platform archive. Download and review the
script from that same tag. This example uses a caller-supplied approved tag and a
dedicated installation path:

```sh
set -euo pipefail
: "${HACK_INSTALL_TAG:?Set the approved release tag before running this script}"

curl --fail --location --proto '=https' --proto-redir '=https' --tlsv1.2 \
  "https://github.com/hack-dance/hack/releases/download/${HACK_INSTALL_TAG}/hack-codex-install.sh" \
  --output hack-codex-install.sh
```

Review the downloaded script and the release's source and artifact identity before
running it. Select unused dedicated destinations, or the same installation you
intend to update:

```sh
HACK_INSTALL_TAG="$HACK_INSTALL_TAG" \
HACK_INSTALL_BIN="$HOME/.local/share/hack-portable/bin" \
HACK_INSTALL_ASSETS="$HOME/.local/share/hack-portable/assets" \
  bash ./hack-codex-install.sh

hack_cli="$HOME/.local/share/hack-portable/bin/hack"
"$hack_cli" --version
```

The portable installer downloads its platform archive over HTTPS; it does not
implement the native prerelease installer's receipt, inventory, and signature
checks. Use your environment's artifact verification policy. Do not point the
portable installer at a native prerelease archive or claim that installing it also
provisioned a VM.

The wrapper defaults to `HACK_EXECUTION_MODE=codex`, disables Docker event watching,
and selects its installed assets. It does not need the Bun runtime to execute its
compiled Hack CLI. Install the project's own toolchain separately. For a Bun
project, use the repository's pinned Bun version and:

```sh
bun install --frozen-lockfile
```

Resolve lockfile failures instead of silently running an unlocked install. Keep
the same rule in maintenance scripts and when a new branch changes dependencies.

Container systems that accept a custom base image can use a reviewed, pinned digest
of `hackdance/hack:slim` or `ghcr.io/hack-dance/hack:slim`, then add project-specific
tools. Do not assume that an arbitrary managed cloud environment accepts a custom
image. The slim image includes Hack and Bun; it does not provide every language or
application dependency.

## Inject the project key for the correct lifetime

Hack resolves committed `.hack/hack.env.default.yaml`, overlays, and local
overrides. A fresh independent checkout can receive its decryption key through
`HACK_ENV_SECRET_KEY`. Use the target's approved secret manager or direct runtime
injection; enter the value through the provider's secret UI, never through chat,
command arguments, logs, or a checked-in setup script.

The key must be available to the Hack process that decrypts the env. Hack requires
the actual key bytes. An HTTPS proxy secret placeholder cannot satisfy local
decryption. Use non-production access for development and inspect variable names
or masked metadata when checking configuration. Do not copy `.hack.secret.key` into
images, shell profiles, prepared filesystem snapshots, or dependency caches. Do not
save decrypted env to extend the lifetime of an injected key. See
[Env & secrets](/docs/v5/env) for key precedence and linked-worktree behavior.

### Current Codex Cloud

Current Cloud records an Install script and Start skill; publication captures the
prepared filesystem, and new tasks use it. Repository refresh preserves caches but
does not rerun installation or startup. Review prepared files before publishing,
then test a new task. See [Cloud environments](https://learn.chatgpt.com/docs/environments/cloud-environments).

Request `HACK_ENV_SECRET_KEY` as a direct environment variable, preferably a
personal value scoped to this environment. It is visible to programs in the task.
Network secrets instead supply proxy placeholders for HTTPS requests, so they are
unsuitable for this key. Configure and test required service access separately.
See [environment variables and network secrets](https://learn.chatgpt.com/docs/environments/cloud-environments#configure-environment-variables-and-network-secrets).

Put deterministic tool and dependency installation in the Install script. Put the
selected CLI, env overlay, start command, and readiness check in the Start skill.
Only publish or share when requested. Keep credentials out of prepared files.

### Legacy Codex Cloud

The [legacy environment guide](https://learn.chatgpt.com/docs/environments/cloud-environment)
describes a different lifecycle: secrets are available only during setup and are
removed before the agent phase. Setup exports do not persist. Cached containers
can resume with an optional maintenance script.

For this path, a setup-only key does not authorize or enable later decryption.
Use a separately approved runtime injection mechanism or a secret-free task. Never
write the key or decrypted values into cached files to work around the boundary.
Report runtime credentials as unavailable until a fresh agent-phase check proves
otherwise.

## Verify env resolution without printing secrets

The examples below assume `hack_cli` is the selected absolute executable and
`project_root` is the intended absolute checkout. These are shell variables, not
Hack configuration keys. Set `HACK_NO_INTERACTIVE=1` and `NO_COLOR=1` in the target
command environment so unattended commands fail instead of hanging at prompts.

Replace `DATABASE_URL` with a required key name from the project, and `default`
with the intended non-production overlay. `env explain` reports provenance without
the value. The child checks presence without printing it:

```sh
"$hack_cli" env explain DATABASE_URL --path "$project_root" --env default --json
"$hack_cli" host exec --path "$project_root" --env default \
  -- sh -c 'test -n "$DATABASE_URL"'
```

For service-scoped values, add `--scope SERVICE` to `host exec` and
`--service SERVICE` to `env explain`. Commands run on the current machine with
Hack's resolved env. `host exec` defaults to host-oriented addresses;
`--target compose` selects container-oriented values but does not enter or start a
container. Run the repository's documented test or development command through
`host exec` when it has a supported host workflow. Inspect that command's logging
before providing real secrets.

Do not use `env get`, `env list --show-secrets`, `printenv`, or a shell env dump as a
credential check. A presence check proves injection only; an application health
check must prove that required services are reachable and credentials work.

## Start only a supported runtime

For an existing Compose project, verify the target engine and Compose client:

```sh
docker info >/dev/null
docker compose version
```

These are capability checks; use Hack to start and manage the application's
services. A missing engine is a provisioning requirement, not a reason to retry
`hack up` or assume Docker-in-Docker or nested virtualization will work. Engine
installation requires an authorized host setup. Likewise, installing the native
candidate does not prepare its provider or activate routing/trust.

Once the chosen runtime is ready, inspect the project's lifecycle hooks for the
remote target, then run:

```sh
"$hack_cli" up --detach --path "$project_root" --env default --json
"$hack_cli" ps --path "$project_root" --json
```

Use a bounded application health request and one meaningful development operation
to verify readiness. A running container alone is insufficient. Machine-wide
`hack global` operations and Loki-backed logs are unavailable in slim mode, which
skips Caddy, CoreDNS, Loki, Grafana, local CA/TLS bootstrap, and daemon Docker event
watching. A project that requires those surfaces needs the appropriate authorized
host setup or its documented portable development path.

Record the target, selected CLI path/version, overlay name, start/readiness result,
and remaining gap without credentials. Preserve existing services and application
data; cleanup applies only to resources this task owns and is authorized to remove.

## Contributor checks and current limits

`scripts/portable-container-smoke.sh` exercises an isolated synthetic project in a
CI-built slim image: it injects a synthetic key after removing the fixture key
file, then checks env resolution and host execution. Run it with:

```sh
bun run smoke:portable-container
```

This proves the portable env/host-command contract for that image. It does not
prove Codex Cloud skill loading, secret lifetime in a real task, Docker availability
there, or v5 native application startup on Linux.

For Hack contributors using a reviewed source checkout, the repo-local
`scripts/install-codex-slim.sh` and `scripts/maintain-codex-slim.sh` are separate
helpers. The source wrapper requires the pinned Bun runtime and references that
checkout; it is not the compiled release installer. Use a dedicated destination
when testing it beside another Hack version.

Automatic lightweight runtime provisioning on arbitrary fresh cloud machines,
native Linux qualification, and a complete fresh Codex Cloud application run remain
separate acceptance work. Report them explicitly rather than treating a successful
CLI installation or env test as full application readiness.


---

<!-- Original: docs/reference/cli.md; revision: 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; SHA-256: a45bea6506367cd962825f246839e7e4af71628bee5e59c87771f15c5abf2b4f; URL: https://hack.foo/docs/v5/reference/cli -->
# hack CLI reference

This reference omits the retired agent instruction-management commands (`hack setup sync`, standalone `hack setup` exports and `hack agent prime`), which refuse in v5. See [Agent integrations](/docs/v5/integrations) for the opt-in plugin and MCP setup.

<!-- GENERATED FILE — do not edit. Regenerate with: bun run docs:cli-reference -->


Run `hack help <command>` for the same content in the terminal. Global options: `--no-interactive` (or `HACK_NO_INTERACTIVE=1`); JSON shapes vary by command and backend. See [Command and output contracts](/docs/v5/reference/command-contracts) for envelopes, bare reports and streamed records.

## Project

## `hack project`

Inspect or manage project metadata

### Usage

```bash
hack project <subcommand> [options]
```

### Subcommands

| Command | Summary |
| --- | --- |
| `hack project owner` | Inspect project ownership |
| `hack project target` | Inspect the exact project, checkout, instance and service a command would target (read-only, provisional) |
| `hack project task` | Discover reviewed task recipes without running them (read-only, provisional) |

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack project owner`

Inspect project ownership

### Usage

```bash
hack project owner <subcommand> [options]
```

### Subcommands

| Command | Summary |
| --- | --- |
| `hack project owner show` | Show the local ownership metadata for the current project |

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack project target`

Inspect the exact project, checkout, instance and service a command would target (read-only, provisional)

### Usage

```bash
hack project target [options]
```

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--branch <name>` | Run against a branch-specific instance (compose name + hostnames) |
| `--service <service>` | Also resolve one Compose service of the target |
| `--env <name|base|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `--expect-generation <id>` | Refuse unless the project's config generation still equals this id |
| `--json` | Output JSON (machine-readable) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack project task`

Discover reviewed task recipes without running them (read-only, provisional)

### Usage

```bash
hack project task <subcommand> [options]
```

### Subcommands

| Command | Summary |
| --- | --- |
| `hack project task list` | List reviewed task recipes and refusals for the target (read-only, provisional; runs nothing) |
| `hack project task inspect <task>` | Show one reviewed task recipe: argv, service, env scope, effects and pins (read-only, provisional; runs nothing) |

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack init`

Initialize a repo (generate .hack/ with compose + config)

### Usage

```bash
hack init [options]
```

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--manual` | Skip discovery and define services manually (or generate a minimal compose in --auto) |
| `--auto` | Run non-interactive init with sensible defaults |
| `--name <slug>` | Project slug (default: repo name) |
| `--dev-host <host>` | DEV_HOST override (new projects use global default_domain, or hack.local) |
| `--oauth` | Enable OAuth-safe alias host |
| `--oauth-tld <tld>` | OAuth alias TLD override (default: gy) |
| `--no-discovery` | Skip discovery and generate a minimal compose |
| `--with <claude|codex>` | After init, hand the onboarding prompt to an agent CLI (prints the prompt when the CLI is missing or the run is non-interactive) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack up [services...]`

Start project services (docker compose up)

### Usage

```bash
hack up [services...] [options]
```

### Arguments

| Arg | Description |
| --- | --- |
| `services` |  |

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--env <name|base|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `--branch <name>` | Run against a branch-specific instance (compose name + hostnames) |
| `--detach, -d` | Run in background (docker compose up -d) |
| `--profile <name[,name...]>` | Enable one or more compose profiles (comma-separated) |
| `--target <auto|local|remote>` | Execution target routing (auto routes to remote when project execution mode requires it) |
| `--json` | Output JSON (machine-readable) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack down`

Stop project services (docker compose down)

### Usage

```bash
hack down [options]
```

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--env <name|base|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `--branch <name>` | Run against a branch-specific instance (compose name + hostnames) |
| `--profile <name[,name...]>` | Enable one or more compose profiles (comma-separated) |
| `--target <auto|local|remote>` | Execution target routing (auto routes to remote when project execution mode requires it) |
| `--prune-caches` | After down, remove confirmed Compose-owned disposable cache volumes |
| `--remove-data` | Native backend: delete a stopped project's owned data volumes so the next up starts fresh (asks first) |
| `--yes` | Confirm --prune-caches or --remove-data without prompting |
| `--json` | Output JSON (machine-readable) |
| `--recover` | Explicitly reconcile an interrupted native stop, or stop the services of a native run whose foreground owner exited, while retaining data |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack restart [services...]`

Restart the project or selected services

### Usage

```bash
hack restart [services...] [options]
```

### Arguments

| Arg | Description |
| --- | --- |
| `services` |  |

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--env <name|base|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `--branch <name>` | Run against a branch-specific instance (compose name + hostnames) |
| `--profile <name[,name...]>` | Enable one or more compose profiles (comma-separated) |
| `--target <auto|local|remote>` | Execution target routing (auto routes to remote when project execution mode requires it) |
| `--json` | Output JSON (machine-readable) |
| `--recover-frontend` | Recover an interrupted native frontend after proving its owner and effects are gone |
| `--expect-finalization-attempt <32-hex>` | Require this exact interrupted native frontend attempt |
| `--expect-frontend-pid <pid>` | Previously observed frontend PID (required only for legacy v1 state) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack ps`

Show project status (docker compose ps)

### Usage

```bash
hack ps [options]
```

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--branch <name>` | Run against a branch-specific instance (compose name + hostnames) |
| `--profile <name[,name...]>` | Enable one or more compose profiles (comma-separated) |
| `--json` | Output JSON (machine-readable) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack tui`

Open the project TUI (services + logs)

### Usage

```bash
hack tui [options]
```

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack run <service> [cmd...]`

Run a one-off command in a service container (docker compose run --rm)

### Usage

```bash
hack run [options] <service> [cmd...]
```

Everything from `<cmd>` on is passed to the command unchanged, including flags such as `--version` or `--help`. Put Hack options before it; a leading `--` is optional.

### Arguments

| Arg | Description |
| --- | --- |
| `service` |  |
| `cmd` |  |

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--env <name|base|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `--branch <name>` | Run against a branch-specific instance (compose name + hostnames) |
| `--workdir <path>` | Working directory inside the container (docker compose run -w) |
| `--profile <name[,name...]>` | Enable one or more compose profiles (comma-separated) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack exec <service> [cmd...]`

Run a command in an already-running service container (docker compose exec)

### Usage

```bash
hack exec [options] <service> [cmd...]
```

Everything from `<cmd>` on is passed to the command unchanged, including flags such as `--version` or `--help`. Put Hack options before it; a leading `--` is optional.

### Arguments

| Arg | Description |
| --- | --- |
| `service` |  |
| `cmd` |  |

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--env <name|base|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `--branch <name>` | Run against a branch-specific instance (compose name + hostnames) |
| `--workdir <path>` | Working directory inside the container (docker compose run -w) |
| `--profile <name[,name...]>` | Enable one or more compose profiles (comma-separated) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack logs [service]`

Tail logs (compose by default; Loki for queries/history via --loki/--query)

### Usage

```bash
hack logs [service] [options]
```

### Arguments

| Arg | Description |
| --- | --- |
| `service` |  |

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--branch <name>` | Run against a branch-specific instance (compose name + hostnames) |
| `--follow, -f` | Follow logs (default for `hack logs`) |
| `--no-follow` | Print logs and exit (do not follow) |
| `--tail <n>` | Tail last N log lines (default: 200) |
| `--pretty` | Pretty-print logs (best-effort JSON parsing + formatting) |
| `--json` | Output JSON (machine-readable) |
| `--profile <name[,name...]>` | Enable one or more compose profiles (comma-separated) |
| `--compose` | Read logs directly from docker compose (bypass Loki) |
| `--loki` | Force Loki backend (do not fall back to docker compose logs) |
| `--services <csv>` | Filter Loki logs by service(s), comma-separated (e.g. api,www) |
| `--query <logql>` | Raw LogQL selector/query (overrides auto selector built from project + services) |
| `--since <time>` | Start time for Loki logs (RFC3339 or duration like 15m) |
| `--until <time>` | End time for Loki logs (RFC3339 or duration like 15m) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack open [target]`

Open a project URL (OAuth alias by default when enabled; otherwise dev host)

### Usage

```bash
hack open [target] [options]
```

### Arguments

| Arg | Description |
| --- | --- |
| `target` |  |

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--branch <name>` | Run against a branch-specific instance (compose name + hostnames) |
| `--prefer <auto|alias|dev>` | Browser host preference (auto uses the OAuth alias when enabled) |
| `--json` | Output JSON (machine-readable) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack branch`

Manage branch aliases for a project

### Usage

```bash
hack branch <subcommand> [options]
```

### Subcommands

| Command | Summary |
| --- | --- |
| `hack branch add <name>` | Register a branch alias for this project |
| `hack branch list` | List registered branch aliases for this project |
| `hack branch remove <name>` | Remove a branch alias for this project |
| `hack branch open <name>` | Open the branch host in a browser |

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack branch add <name>`

Register a branch alias for this project

### Usage

```bash
hack branch add <name> [options]
```

### Arguments

| Arg | Description |
| --- | --- |
| `name` |  |

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--note <text>` | Optional note for the branch entry |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack branch list`

List registered branch aliases for this project

### Usage

```bash
hack branch list [options]
```

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack branch remove <name>`

Remove a branch alias for this project

### Usage

```bash
hack branch remove <name> [options]
```

### Arguments

| Arg | Description |
| --- | --- |
| `name` |  |

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack branch open <name>`

Open the branch host in a browser

### Usage

```bash
hack branch open <name> [options]
```

### Arguments

| Arg | Description |
| --- | --- |
| `name` |  |

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--prefer <auto|alias|dev>` | Browser host preference (auto uses the OAuth alias when enabled) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack config`

Read/write legacy config or validate native project configuration

### Usage

```bash
hack config <subcommand> [options]
```

### Subcommands

| Command | Summary |
| --- | --- |
| `hack config get <key>` | Read a value from hack.config.json |
| `hack config set <key> <value>` | Update a value in hack.config.json |
| `hack config validate` | Validate native configuration and selected local overlays without starting workloads |
| `hack config plan` | Inspect native environment binding completeness without decrypting or starting workloads |
| `hack config import` | Preview a bounded legacy config and Compose conversion without writes |
| `hack config adopt` | Explicitly adopt a stopped, verified existing Compose instance |

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack config get <key>`

Read a value from hack.config.json

### Usage

```bash
hack config get <key> [options]
```

### Arguments

| Arg | Description |
| --- | --- |
| `key` |  |

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--global` | Read/write global ~/.hack/hack.config.json |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack config set <key> <value>`

Update a value in hack.config.json

### Usage

```bash
hack config set <key> <value> [options]
```

### Arguments

| Arg | Description |
| --- | --- |
| `key` |  |
| `value` |  |

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--global` | Read/write global ~/.hack/hack.config.json |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack config validate`

Validate native configuration and selected local overlays without starting workloads

### Usage

```bash
hack config validate [options]
```

Uses the matching bundled Rust compiler. Without --file, discovers a native project and resolves permitted worktree-local overlay and routing settings. --file validates only the explicit document. With HACK_RUNTIME_BACKEND=native, a selected workload image that is not a sha256: content ID refuses with the native consumer's native_graph_admission code. Neither mode reads env values, writes state, or starts workloads.

### Options

| Option | Description |
| --- | --- |
| `--file <path>` | Validate only this native project JSON file, without discovery or local overrides |
| `--profile <names>` | Comma-separated declared native profiles |
| `--domain <suffix>` | Select the generated native routing domain suffix |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--env <name|base|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `--json` | Output JSON (machine-readable) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack config plan`

Inspect native environment binding completeness without decrypting or starting workloads

### Usage

```bash
hack config plan [options]
```

Resolves the native project, permitted local env selection and routing preview, then inspects managed-env names, winning scopes and secret flags. Managed YAML is parsed by its existing owner; keys and values are never decrypted or returned. Required unresolved refs return a nonzero exit. This experimental report does not establish runtime admission or enable native execution; use config validate for validation without managed-document reads.

### Options

| Option | Description |
| --- | --- |
| `--profile <names>` | Comma-separated declared native profiles |
| `--domain <suffix>` | Select the generated native routing domain suffix |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--env <name|base|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `--json` | Output JSON (machine-readable) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack config import`

Preview a bounded legacy config and Compose conversion without writes

### Usage

```bash
hack config import [options]
```

Requires --dry-run. Inspects the exact .hack/hack.config.json and docker-compose.yml pair, reports field mappings/refusals, and validates complete private candidates in memory. Does not export a draft, adopt resources, read keys or change project selection.

### Options

| Option | Description |
| --- | --- |
| `--dry-run` | Preview only; adoption and draft export are unavailable |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--json` | Output JSON (machine-readable) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack config adopt`

Explicitly adopt a stopped, verified existing Compose instance

### Usage

```bash
hack config adopt [options]
```

Qualifies a strict static legacy subset with exact existing data volumes. --dry-run reports fields without writes. Adoption journals the stopped format switch and holds original files for rollback; retained-container commands never create replacement data. Requires an upgraded launcher and the Compose backend, also for --dry-run; on another backend, rerun with HACK_RUNTIME_BACKEND=compose. Verified linked Git checkouts retain explicit existing identities. Local inheritance, generated overrides and container recreation remain unsupported.

### Options

| Option | Description |
| --- | --- |
| `--stop` | Explicitly journal and stop the exact original containers before adopting; never removes data anchors |
| `--dry-run` | Read-only field, compiler and existing-resource preview |
| `--rollback` | Restore the exact held legacy inputs after the original containers are stopped |
| `--recover` | Explicitly repair interrupted adoption or rollback using the saved original binding |
| `--branch <value>` | Select the exact existing branch instance |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--json` | Output JSON (machine-readable) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack session`

Manage persistent project workspaces with tmux-first onboarding

### Usage

```bash
hack session <subcommand> [options]
```

Sessions keep a project workspace alive across terminal restarts, SSH reconnects, and long-running agent work. The guided default is tmux, including `hack setup tmux` for a popup picker. Other mux backends such as zellij still exist through `sessions.mux`, but the interactive session tooling is tmux-first today.

### Subcommands

| Command | Summary |
| --- | --- |
| `hack session list` | List active workspaces |
| `hack session start [project]` | Reuse the default project workspace or create an isolated one |
| `hack session stop <workspace>` | Stop a workspace |
| `hack session attach <workspace>` | Attach to an existing workspace |
| `hack session exec <workspace> <command>` | Send a command to a running workspace |
| `hack session panes <workspace>` | List panes in a tmux workspace |
| `hack session capture <workspace>` | Capture recent output from a tmux workspace |
| `hack session tail <workspace>` | Tail output from a tmux workspace |

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack session list`

List active workspaces

### Usage

```bash
hack session list [options]
```

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack session start [project]`

Reuse the default project workspace or create an isolated one

### Usage

```bash
hack session start [project] [options]
```

Reuse the default project workspace when it already exists, or create an isolated long-running workspace with --new or --name. Use --detach when another tool should keep the workspace alive without attaching your terminal.

### Arguments

| Arg | Description |
| --- | --- |
| `project` | Project name or path |

### Options

| Option | Description |
| --- | --- |
| `--up` | Run hack up -d before creating or attaching |
| `--new` | Create an isolated workspace instead of reusing the default project workspace |
| `--name <value>` | Suffix for an isolated workspace name (for example: agent-1 -> project--agent-1) |
| `--detach, -d` | Create or reuse the workspace without attaching (for GUI/non-TTY use) |
| `--env <name|base|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `--service <global|service>` | Inject env for the selected scope (global or a service name) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack session stop <workspace>`

Stop a workspace

### Usage

```bash
hack session stop <workspace> [options]
```

### Arguments

| Arg | Description |
| --- | --- |
| `workspace` | Workspace name |

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack session attach <workspace>`

Attach to an existing workspace

### Usage

```bash
hack session attach <workspace> [options]
```

Attach to a running workspace by name. Tmux switches clients instead of nesting tmux inside tmux, while zellij attaches to the named session directly.

### Arguments

| Arg | Description |
| --- | --- |
| `workspace` | Workspace name |

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack session exec <workspace> <command>`

Send a command to a running workspace

### Usage

```bash
hack session exec [options] <workspace> <command>
```

`<command>` is one argument: quote a command that has its own arguments or flags, as in `"npm --version"`. Put Hack options before it; a leading `--` is optional.

Queue a command in the workspace without opening a new interactive attach flow. Tmux sends it to the active pane; zellij opens a new pane for the command. This is useful for long-running agents, background checks, or remote follow-up work.

### Arguments

| Arg | Description |
| --- | --- |
| `workspace` | Workspace name |
| `command` | Command to execute in workspace |

### Options

| Option | Description |
| --- | --- |
| `--env <name|base|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `--service <global|service>` | Inject env for the selected scope (global or a service name) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack session panes <workspace>`

List panes in a tmux workspace

### Usage

```bash
hack session panes <workspace> [options]
```

### Arguments

| Arg | Description |
| --- | --- |
| `workspace` | Workspace name |

### Options

| Option | Description |
| --- | --- |
| `--json` | Output JSON (machine-readable) |
| `--pretty` | Pretty-print logs (best-effort JSON parsing + formatting) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack session capture <workspace>`

Capture recent output from a tmux workspace

### Usage

```bash
hack session capture <workspace> [options]
```

### Arguments

| Arg | Description |
| --- | --- |
| `workspace` | Workspace name |

### Options

| Option | Description |
| --- | --- |
| `--target <target>` | Tmux pane target (default: active pane) |
| `--lines <n>` | Number of lines to capture (default: 200) |
| `--json` | Output JSON (machine-readable) |
| `--pretty` | Pretty-print logs (best-effort JSON parsing + formatting) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack session tail <workspace>`

Tail output from a tmux workspace

### Usage

```bash
hack session tail <workspace> [options]
```

### Arguments

| Arg | Description |
| --- | --- |
| `workspace` | Workspace name |

### Options

| Option | Description |
| --- | --- |
| `--target <target>` | Tmux pane target (default: active pane) |
| `--lines <n>` | Number of lines to capture (default: 200) |
| `--interval-ms <ms>` | Polling interval in milliseconds (default: 500) |
| `--max-ms <ms>` | Stop tailing after N milliseconds (default: 5000) |
| `--json` | Output JSON (machine-readable) |
| `--pretty` | Pretty-print logs (best-effort JSON parsing + formatting) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## Global infrastructure

## `hack global`

Manage machine-wide infra (DNS/TLS, Caddy proxy, logs)

### Usage

```bash
hack global <subcommand> [options]
```

### Subcommands

| Command | Summary |
| --- | --- |
| `hack global install` | Bootstrap ~/.hack and start Caddy + Grafana/Loki/Alloy |
| `hack global dns` | Manage scoped native custom-domain DNS |
| `hack global up` | Start global infra containers |
| `hack global down` | Stop global infra containers |
| `hack global status` | Show status for global infra (containers + networks) |
| `hack global logs [service]` | Tail global infra logs (caddy\|grafana\|loki\|alloy) |
| `hack global ca` | Export Caddy Local CA cert (print path or PEM) |
| `hack global cert <hosts...>` | Generate local TLS certs via mkcert (for non-Caddy services) |
| `hack global trust` | Trust Caddy Local CA (macOS) so https://*.hack is trusted |
| `hack global logs-reset` | Wipe Loki, Grafana and Alloy volumes (fresh logs, dashboards and Alloy read positions) |
| `hack global authorize` | Authorize passwordless DNS recovery commands on macOS |

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack global install`

Bootstrap ~/.hack and start Caddy + Grafana/Loki/Alloy

### Usage

```bash
hack global install [options]
```

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack global dns`

Manage scoped native custom-domain DNS

### Usage

```bash
hack global dns <subcommand> [options]
```

### Subcommands

| Command | Summary |
| --- | --- |
| `hack global dns preview` | Preview a scoped native custom-domain DNS claim or the hack.local relay repair without changing the host |
| `hack global dns activate` | Activate only the selected native custom-domain DNS suffix |
| `hack global dns deactivate` | Remove an owned native custom-domain DNS suffix, or undo the hack.local relay repair |

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack global up`

Start global infra containers

### Usage

```bash
hack global up [options]
```

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack global down`

Stop global infra containers

### Usage

```bash
hack global down [options]
```

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack global status`

Show status for global infra (containers + networks)

### Usage

```bash
hack global status [options]
```

### Options

| Option | Description |
| --- | --- |
| `--json` | Output JSON (machine-readable) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack global logs [service]`

Tail global infra logs (caddy\|grafana\|loki\|alloy)

### Usage

```bash
hack global logs [service] [options]
```

### Arguments

| Arg | Description |
| --- | --- |
| `service` |  |

### Options

| Option | Description |
| --- | --- |
| `--follow, -f` | Follow logs (default for `hack logs`) |
| `--no-follow` | Print logs and exit (do not follow) |
| `--tail <n>` | Tail last N log lines (default: 200) |
| `--pretty` | Pretty-print logs (best-effort JSON parsing + formatting) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack global ca`

Export Caddy Local CA cert (print path or PEM)

### Usage

```bash
hack global ca [options]
```

### Options

| Option | Description |
| --- | --- |
| `--print` | Print the CA cert PEM to stdout (instead of printing its path) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack global cert <hosts...>`

Generate local TLS certs via mkcert (for non-Caddy services)

### Usage

```bash
hack global cert <hosts...> [options]
```

Uses mkcert to generate a cert/key pair under ~/.hack/certs (or --out).

### Arguments

| Arg | Description |
| --- | --- |
| `hosts` |  |

### Options

| Option | Description |
| --- | --- |
| `--install` | Run mkcert -install before generating certs |
| `--out <dir>` | Directory for generated cert/key (default: ~/.hack/certs) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack global trust`

Trust Caddy Local CA (macOS) so https://*.hack is trusted

### Usage

```bash
hack global trust [options]
```

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack global logs-reset`

Wipe Loki, Grafana and Alloy volumes (fresh logs, dashboards and Alloy read positions)

### Usage

```bash
hack global logs-reset [options]
```

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack global authorize`

Authorize passwordless DNS recovery commands on macOS

### Usage

```bash
hack global authorize [options]
```

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack status`

Show project status (shortcut for `hack projects --details`)

### Usage

```bash
hack status [options]
```

### Options

| Option | Description |
| --- | --- |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--include-global` | Include global infra projects under ~/.hack (e.g. logging stack) |
| `--all` | Include unregistered docker compose projects (best-effort) |
| `--meta` | Include git/worktree/session/env metadata (implies --details) |
| `--json` | Output JSON (machine-readable) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack usage`

Show resource usage across running projects

### Usage

```bash
hack usage [options]
```

### Options

| Option | Description |
| --- | --- |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--details` | Show per-container usage and mount types |
| `--include-global` | Include global infra projects under ~/.hack (e.g. logging stack) |
| `--watch` | Refresh usage continuously |
| `--interval <value>` | Refresh interval (ms) for --watch |
| `--no-host` | Skip host process metrics |
| `--json` | Output JSON (machine-readable) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack projects`

Show all projects (registry + running docker compose)

### Usage

```bash
hack projects <subcommand> [options]
```

### Subcommands

| Command | Summary |
| --- | --- |
| `hack projects prune` | Remove stale registry entries and stop orphaned containers |

### Options

| Option | Description |
| --- | --- |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--details` | Show per-project service tables |
| `--summary` | Return compact project counts with --json; load details with --project |
| `--timings` | Write numeric listing phase timings to stderr (requires --json) |
| `--no-daemon` | Read runtime directly instead of the daemon cache |
| `--meta` | Include git/worktree/session/env metadata (implies --details) |
| `--include-global` | Include global infra projects under ~/.hack (e.g. logging stack) |
| `--all` | Include unregistered docker compose projects (best-effort) |
| `--json` | Output JSON (machine-readable) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack projects prune`

Remove stale registry entries and stop orphaned containers

### Usage

```bash
hack projects prune [options]
```

### Options

| Option | Description |
| --- | --- |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--include-global` | Include global infra projects under ~/.hack (e.g. logging stack) |
| `--dry-run` | Report prune candidates without changing registry entries or containers |
| `--json` | Output JSON (machine-readable) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## Diagnostics

## `hack log-pipe`

Read log lines from stdin and pretty-print them (best-effort JSON parsing)

### Usage

```bash
hack log-pipe [options]
```

### Options

| Option | Description |
| --- | --- |
| `--format <auto|docker-compose|plain>` | How to parse incoming lines from stdin (default: auto) |
| `--stream <stdout|stderr>` | Treat stdin as stdout or stderr (stderr forces ERROR level + writes to stderr) (default: stdout) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack doctor`

Validate local setup for the selected runtime, routing, trust and project

### Usage

```bash
hack doctor [options]
```

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--fix` | Attempt safe auto-remediations (network + CoreDNS + CA) |
| `--migrate-env-config` | Migrate legacy hack.env.json/.env state to the new env config files |
| `--accept-tracked-env-changes` | With --migrate-env-config and no prompt, allow deleting or editing git-tracked files (hack.env.json, the Compose file) |
| `--domain-migration preview|apply|rollback` | Preview, apply, or roll back only this project's hack.local migration |
| `--json` | Output JSON (machine-readable) |
| `--browser-url https://app.hack` | HTTPS origin manually tested in the browser (no path or credentials) |
| `--browser-result unknown|works|fails|permission-denied` | Your manual browser observation for --browser-url (default: unknown) |
| `--branch <name>` | Run against a branch-specific instance (compose name + hostnames) |
| `--native-cleanup inspect` | Inspect one mapped native graph's pending cleanup without recovery or stop replay |
| `--native-run-mapping inspect|repair|release` | Inspect a native run mapping, explicitly repair it after filesystem device renumbering, or release one another native home left after a clean stop |
| `--expect-selection <64-hex>` | Require the exact run-mapping recovery inspection selection |
| `--accept-legacy-device-rebind` | Explicitly accept legacy migration without proof of original filesystem volume continuity |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack crash-capture`

Capture OrbStack/system/docker diagnostics into .tmp for post-failure triage

### Usage

```bash
hack crash-capture [options]
```

Collects structured snapshots after a runtime failure: hack status/logs, docker state, OrbStack process details, and filtered macOS unified logs.

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--since <duration>` | Look-back window for system logs (for example: 30m, 2h) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack daemon`

Manage the local hack daemon (hackd)

### Usage

```bash
hack daemon <subcommand> [options]
```

### Subcommands

| Command | Summary |
| --- | --- |
| `hack daemon start` | Start hackd (local daemon) |
| `hack daemon stop` | Stop hackd |
| `hack daemon restart` | Restart hackd |
| `hack daemon status` | Show hackd status |
| `hack daemon metrics` | Show hackd metrics |
| `hack daemon logs` | Show hackd logs |
| `hack daemon clear` | Clear stale hackd pid/socket files |
| `hack daemon install` | Install hackd as a launchd service (macOS) |
| `hack daemon uninstall` | Uninstall hackd launchd service (macOS) |

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack daemon start`

Start hackd (local daemon)

### Usage

```bash
hack daemon start [options]
```

### Options

| Option | Description |
| --- | --- |
| `--foreground` | Run hackd in the foreground (debug) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack daemon stop`

Stop hackd

### Usage

```bash
hack daemon stop [options]
```

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack daemon restart`

Restart hackd

### Usage

```bash
hack daemon restart [options]
```

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack daemon status`

Show hackd status

### Usage

```bash
hack daemon status [options]
```

### Options

| Option | Description |
| --- | --- |
| `--json` | Output JSON (machine-readable) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack daemon metrics`

Show hackd metrics

### Usage

```bash
hack daemon metrics [options]
```

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack daemon logs`

Show hackd logs

### Usage

```bash
hack daemon logs [options]
```

### Options

| Option | Description |
| --- | --- |
| `--tail <n>` | Tail last N log lines (default: 200) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack daemon clear`

Clear stale hackd pid/socket files

### Usage

```bash
hack daemon clear [options]
```

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack daemon install`

Install hackd as a launchd service (macOS)

### Usage

```bash
hack daemon install [options]
```

### Options

| Option | Description |
| --- | --- |
| `--run-at-load` | Start hackd automatically on login |
| `--no-run-at-load` | Do not start hackd automatically on login |
| `--gui-only` | Only run in GUI sessions (default) |
| `--no-gui-only` | Run in all session types (including SSH) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack daemon uninstall`

Uninstall hackd launchd service (macOS)

### Usage

```bash
hack daemon uninstall [options]
```

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack update`

Update hack to the latest release

### Usage

```bash
hack update [options]
```

Downloads and installs the latest stable hack release from GitHub.

Notes:
- Refuses to self-update when running from a Homebrew install, local dev wrapper, or symlink install.
- Updates the current hack binary and refreshes assets.

### Options

| Option | Description |
| --- | --- |
| `--check` | Check for updates (do not install) |
| `--yes` | Apply update without prompting |
| `--tag <tag>` | Update to a specific release tag (e.g. v1.4.0) |
| `--json` | Output JSON (machine-readable) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack version`

Print version

### Usage

```bash
hack version [options]
```

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack help [path...]`

Show help for a command (e.g. hack help global logs)

### Usage

```bash
hack help [path...] [options]
```

### Arguments

| Arg | Description |
| --- | --- |
| `path` |  |

### Options

| Option | Description |
| --- | --- |
| `--all` | Include experimental (unsupported) commands in help output |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## Agents

## `hack mcp`

Manage MCP server integrations for coding agents

### Usage

```bash
hack mcp <subcommand> [options]
```

### Subcommands

| Command | Summary |
| --- | --- |
| `hack mcp serve` | Run the MCP server over stdio |
| `hack mcp print` | Print MCP config snippets |

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack mcp serve`

Run the MCP server over stdio

### Usage

```bash
hack mcp serve [options]
```

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack mcp print`

Print MCP config snippets

### Usage

```bash
hack mcp print [options]
```

### Options

| Option | Description |
| --- | --- |
| `--bundle <directory>` | Select a verified candidate MCP bundle (requires --cli) |
| `--cli <executable>` | Pin the Hack executable used by candidate MCP tools |
| `--runtime-directory <directory>` | Select a private candidate MCP socket directory |
| `--scope <user|project>` | Write MCP config to user or project scope (default: user) |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--all` | Target all supported clients |
| `--cursor` | Target Cursor MCP config |
| `--claude` | Target Claude CLI MCP config |
| `--codex` | Target Codex MCP config |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack setup`

Explicit opt-in skills and MCP; legacy automation is retired

### Usage

```bash
hack setup <subcommand> [options]
```

### Subcommands

| Command | Summary |
| --- | --- |
| `hack setup tmux` | Install the recommended tmux binding for hack workspaces |
| `hack setup migrate` | Migrate standalone skills to the hack plugin; preserve Cursor rules |

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack setup tmux`

Install the recommended tmux binding for hack workspaces

### Usage

```bash
hack setup tmux [options]
```

### Options

| Option | Description |
| --- | --- |
| `--check` | Check whether integration is installed |
| `--remove` | Remove integration files/config |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack setup migrate`

Migrate standalone skills to the hack plugin; preserve Cursor rules

### Usage

```bash
hack setup migrate [options]
```

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--global` | Migrate user-scope files under HOME instead of the project |
| `--all-scopes` | Migrate both project and user-scope files |
| `--claude` | Limit to Claude Code files (default: all clients) |
| `--codex` | Limit to Codex files (default: all clients) |
| `--cursor` | Limit to Cursor files (default: all clients) |
| `--skip-plugin-check <clients>` | Treat the plugin as verified for these comma-separated clients (claude, codex, cursor, or all) after checking it loads yourself |
| `--apply` | Remove the previewed Hack-owned standalone files after backing them up (default: read-only preview) |
| `--rollback-manifest <manifest>` | Restore the exact files recorded in a migration backup manifest |
| `--json` | Output JSON (machine-readable) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack agent`

Agent utilities

### Usage

```bash
hack agent <subcommand> [options]
```

### Subcommands

| Command | Summary |
| --- | --- |
| `hack agent patterns` | Print agent init patterns guide |
| `hack agent init` | Print agent init prompt |
| `hack agent onboard` | Print the project onboarding prompt (agent-assisted setup) |

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack agent patterns`

Print agent init patterns guide

### Usage

```bash
hack agent patterns [options]
```

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack agent init`

Print agent init prompt

### Usage

```bash
hack agent init [options]
```

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--client, -c <cursor|claude|codex|print>` | Open init prompt in an agent client (or print) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack agent onboard`

Print the project onboarding prompt (agent-assisted setup)

### Usage

```bash
hack agent onboard [options]
```

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## Secrets & env

## `hack secrets`

Manage secrets in OS keychain (Bun.secrets)

### Usage

```bash
hack secrets <subcommand> [options]
```

### Subcommands

| Command | Summary |
| --- | --- |
| `hack secrets set [name]` | Store a secret |
| `hack secrets get [name]` | Print a secret (exit 1 if missing) |
| `hack secrets delete [name]` | Delete a stored secret |

### Options

| Option | Description |
| --- | --- |
| `--service <service>` | Override Bun.secrets service name (default: hack-cli) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack secrets set [name]`

Store a secret

### Usage

```bash
hack secrets set [name] [options]
```

### Arguments

| Arg | Description |
| --- | --- |
| `name` |  |

### Options

| Option | Description |
| --- | --- |
| `--service <service>` | Override Bun.secrets service name (default: hack-cli) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack secrets get [name]`

Print a secret (exit 1 if missing)

### Usage

```bash
hack secrets get [name] [options]
```

### Arguments

| Arg | Description |
| --- | --- |
| `name` |  |

### Options

| Option | Description |
| --- | --- |
| `--service <service>` | Override Bun.secrets service name (default: hack-cli) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack secrets delete [name]`

Delete a stored secret

### Usage

```bash
hack secrets delete [name] [options]
```

Asks for confirmation before deleting. Without a TTY (or with HACK_NO_INTERACTIVE / --no-interactive)
the deletion is refused with E_INTERACTIVE_REQUIRED unless --yes is passed.

### Arguments

| Arg | Description |
| --- | --- |
| `name` |  |

### Options

| Option | Description |
| --- | --- |
| `--service <service>` | Override Bun.secrets service name (default: hack-cli) |
| `--yes` | Confirm the deletion without prompting (required without a TTY or with HACK_NO_INTERACTIVE) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## Integrations

## `hack env`

Set project env vars and local secrets

### Usage

```bash
hack env <subcommand> [options]
```

### Subcommands

| Command | Summary |
| --- | --- |
| `hack env list` | List resolved env values for the selected overlay |
| `hack env get <key>` | Print one resolved env value without an added newline |
| `hack env explain <key>` | Explain a resolved env value without revealing it |
| `hack env apply` | Recreate one service with its resolved env |
| `hack env add [key] [value]` | Add or update an env value |
| `hack env set [key] [value]` | Alias for env add |
| `hack env hydrate` | Import many values into the machine-local env layer at once |
| `hack env materialize` | Write a compatibility .env file from the selected overlay |
| `hack env exec [command...]` | Run a host command with project env injected |
| `hack env shell` | Open a host shell with project env injected |
| `hack env unset [key]` | Remove an env value from the canonical config |
| `hack env backend` | Manage env/secret storage backend strategy |

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack env list`

List resolved env values for the selected overlay

### Usage

```bash
hack env list [options]
```

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--env <name|base|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `--json` | Output JSON (machine-readable) |
| `--show-secrets` | Print secret values (keychain) in plaintext |
| `--service <global|service>` | Target scope (global or a discovered service name) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack env get <key>`

Print one resolved env value without an added newline

### Usage

```bash
hack env get <key> [options]
```

Read one global or service value without starting a runtime. Empty values succeed; missing values fail. Omit --env to use the configured default, or use --env default for base layers. Plaintext is written only to stdout; errors go to stderr.

### Arguments

| Arg | Description |
| --- | --- |
| `key` |  |

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--env <name|base|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `--service <global|service>` | Target scope (global or a discovered service name) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack env explain <key>`

Explain a resolved env value without revealing it

### Usage

```bash
hack env explain <key> [options]
```

### Arguments

| Arg | Description |
| --- | --- |
| `key` |  |

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--env <name|base|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `--json` | Output JSON (machine-readable) |
| `--service <global|service>` | Target scope (global or a discovered service name) |
| `--target <host|compose>` | Env view for host commands (default: host rewrites container-oriented addresses for local host execution) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack env apply`

Recreate one service with its resolved env

### Usage

```bash
hack env apply [options]
```

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--env <name|base|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `--json` | Output JSON (machine-readable) |
| `--service <global|service>` | Target scope (global or a discovered service name) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack env add [key] [value]`

Add or update an env value

### Usage

```bash
hack env add [key] [value] [options]
```

Non-secret values may be passed as arguments. For secrets, pipe the value with --value-stdin (for example `<secret-source> \| hack env add API_TOKEN --secret --value-stdin`) or omit the value in a terminal to use the hidden prompt, so the value never appears in argv, shell history, or process listings.

### Arguments

| Arg | Description |
| --- | --- |
| `key` |  |
| `value` |  |

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--env <name|base|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `--secret` | Store value as an encrypted secure entry |
| `--value-stdin` | Read the value from piped stdin (max 64 KiB, one trailing newline stripped) so it never appears in argv or shell history |
| `--local` | Write to the worktree-local env override file instead of the shared repo env file |
| `--service <global|service>` | Target scope (global or a discovered service name) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack env set [key] [value]`

Alias for env add

### Usage

```bash
hack env set [key] [value] [options]
```

Same value rules as `hack env add`: pipe secrets with --value-stdin or use the hidden prompt instead of passing them as arguments.

### Arguments

| Arg | Description |
| --- | --- |
| `key` |  |
| `value` |  |

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--env <name|base|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `--secret` | Store value as an encrypted secure entry |
| `--value-stdin` | Read the value from piped stdin (max 64 KiB, one trailing newline stripped) so it never appears in argv or shell history |
| `--local` | Write to the worktree-local env override file instead of the shared repo env file |
| `--service <global|service>` | Target scope (global or a discovered service name) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack env hydrate`

Import many values into the machine-local env layer at once

### Usage

```bash
hack env hydrate [options]
```

Reads KEY=value entries from piped stdin or --file (never from arguments) and writes them, in one atomic commit, to the worktree-local env file (`hack.env.local.yaml`, or `hack.env.<overlay>.local.yaml` with --env). Tracked env files are never written. Repeating an import with the same values changes nothing; other local entries are kept. Values are never printed.

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--env <name|base|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `--json` | Output JSON (machine-readable) |
| `--secret` | Store value as an encrypted secure entry |
| `--service <global|service>` | Target scope (global or a discovered service name) |
| `--file <path>` | Read entries from this file (or a pipe such as <(producer)) instead of stdin |
| `--format <env|json>` | Input format: KEY=value lines (env, default) or one JSON object of string values (json) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack env materialize`

Write a compatibility .env file from the selected overlay

### Usage

```bash
hack env materialize [options]
```

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--env <name|base|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `--service <global|service>` | Target scope (global or a discovered service name) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack env exec [command...]`

Run a host command with project env injected

### Usage

```bash
hack env exec [options] [command...]
```

Everything from `<command>` on is passed to the command unchanged, including flags such as `--version` or `--help`. Put Hack options before it; a leading `--` is optional.

Inject the selected Hack env overlay directly into a one-off host command without materializing .hack/.env. To inspect a value, prefer `printenv KEY` or `sh -lc 'printf "%s\n" "$KEY"'`; `echo $KEY` expands in your current shell before Hack injects env.

### Arguments

| Arg | Description |
| --- | --- |
| `command` |  |

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--env <name|base|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `--service <global|service>` | Target scope (global or a discovered service name) |
| `--target <host|compose>` | Env view for host commands (default: host rewrites container-oriented addresses for local host execution) |
| `--shell <command>` | Run a shell command string via /bin/sh -lc after env injection so `$VAR` expansion happens inside the child shell |
| `--timeout <seconds>` | Bound a non-TTY host command; terminate its process group and return 124 on expiry |
| `--lifetime <command|persistent>` | Declare intended lifetime for diagnostics (default: command; does not detach) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack env shell`

Open a host shell with project env injected

### Usage

```bash
hack env shell [options]
```

Start an interactive host shell with the selected Hack env overlay injected into the process environment.

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--env <name|base|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `--service <global|service>` | Target scope (global or a discovered service name) |
| `--target <host|compose>` | Env view for host commands (default: host rewrites container-oriented addresses for local host execution) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack env unset [key]`

Remove an env value from the canonical config

### Usage

```bash
hack env unset [key] [options]
```

### Arguments

| Arg | Description |
| --- | --- |
| `key` |  |

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--env <name|base|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `--local` | Write to the worktree-local env override file instead of the shared repo env file |
| `--service <global|service>` | Target scope (global or a discovered service name) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack env backend`

Manage env/secret storage backend strategy

### Usage

```bash
hack env backend <subcommand> [options]
```

### Subcommands

| Command | Summary |
| --- | --- |
| `hack env backend status` | Show configured env/secret backend strategy |
| `hack env backend use <backend>` | Select env/secret backend strategy |

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


## `hack host`

Run host-side commands with project env injected

### Usage

```bash
hack host <subcommand> [options]
```

Use hack host when a command should run on your host machine, not inside the compose network, but still needs Hack-resolved env and host-local rewrites.

### Subcommands

| Command | Summary |
| --- | --- |
| `hack host ps` | Inspect host command lifetimes, CPU and lifecycle ownership (read-only) |
| `hack host exec [command...]` | Run a host command with project env injected |
| `hack host shell` | Open a host shell with project env injected |

### Options

| Option | Description |
| --- | --- |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack host ps`

Inspect host command lifetimes, CPU and lifecycle ownership (read-only)

### Usage

```bash
hack host ps [options]
```

### Options

| Option | Description |
| --- | --- |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--json` | Output JSON (machine-readable) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack host exec [command...]`

Run a host command with project env injected

### Usage

```bash
hack host exec [options] [command...]
```

Everything from `<command>` on is passed to the command unchanged, including flags such as `--version` or `--help`. Put Hack options before it; a leading `--` is optional.

Run a one-off command on the host with the selected Hack env overlay injected. Use --scope when you want service-scoped values without running inside that service container. To inspect a value, prefer `printenv KEY` or `sh -lc 'printf "%s\n" "$KEY"'`; `echo $KEY` expands in your current shell before Hack injects env.

### Arguments

| Arg | Description |
| --- | --- |
| `command` |  |

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--env <name|base|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `--scope <global|service>` | Resolve values for one env scope while still running the command on the host |
| `--target <host|compose>` | Env view for host commands (default: host rewrites container-oriented addresses for local host execution) |
| `--shell <command>` | Run a shell command string via /bin/sh -lc after env injection so `$VAR` expansion happens inside the child shell |
| `--timeout <seconds>` | Bound a non-TTY host command; terminate its process group and return 124 on expiry |
| `--lifetime <command|persistent>` | Declare intended lifetime for diagnostics (default: command; does not detach) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |

## `hack host shell`

Open a host shell with project env injected

### Usage

```bash
hack host shell [options]
```

Start an interactive host shell with the selected Hack env overlay injected. Use --scope when you want service-scoped values without running inside that service container.

### Options

| Option | Description |
| --- | --- |
| `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
| `--env <name|base|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `--scope <global|service>` | Resolve values for one env scope while still running the command on the host |
| `--target <host|compose>` | Env view for host commands (default: host rewrites container-oriented addresses for local host execution) |
| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | Show help |
| `--version, -v` | Show version |


---

<!-- Original: docs/reference.md; revision: 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; SHA-256: 5163cc04bc4f6551e03d7ffeda67b7caffc7bc2ba2caeac566f8b8e59b5da35e; URL: https://hack.foo/docs/v5/reference -->
# Reference

## CLI & architecture

- [CLI overview](/docs/v5/cli) — supported command surface and the running-things decision guide
- [CLI reference (generated, exhaustive)](/docs/v5/reference/cli) — every command and flag, rendered from the spec (regenerate: `bun run docs:cli-reference`)
- [Architecture](/docs/v5/architecture)
- [Core docs](/docs/v5/core)
- [Docs information architecture](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/docs-ia.md)

## Environment & sessions

- [Environment model](/docs/v5/env)
- [Lifecycle & startup](/docs/v5/lifecycle)
- [Shared host helper lifecycle](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/shared-host-lifecycle.md) — identity-verified adoption, exact process claims and release rules for helpers shared across branches
- [Sessions](/docs/v5/sessions)
- [Agent-first setup](/docs/v5/guides/agent-first-setup)

## Native runtime (experimental)

- [Native candidate guide](/docs/v5/native/full-reference)
- [Native configuration validation](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/native-config-compiler.md) — the authored `.hack/hack.project.json` compiler contract
- [Native configuration with Compose](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/native-compose-commands.md) — the Compose command owner for authored projects
- [Authored configuration with the native runtime](/docs/v5/native/authored-commands) — the explicit native backend command slices and their support matrix
- [Application benchmark protocol](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/application-benchmark-protocol.md) — the frozen matched benchmark artifacts, workloads, order, sample counts and budgets

## Extensions

- [Extensions](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/extensions.md)
- [Creating an extension](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/guides/create-extension.md)
- [Integrations](/docs/v5/integrations)
- [MCP tool contract](/docs/v5/reference/mcp-tools) — every MCP tool: annotations, inputs, argv, results, and the value-free env tools
- [MCP logs contract](/docs/v5/reference/mcp-logs) — cutoff versus backend failure for the MCP log tools, and the cursor/handle decision
- [AX target and result contract](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/ax-target-result-contract.md) — provisional target schema, closed refusals and the read-only `hack project target` inspector
- [AX task catalog contract](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/ax-task-catalog.md) — provisional reviewed-recipe catalog, closed refusals and the read-only `hack project task list|inspect` commands


---

<!-- Original: docs/guides/prereleases.md; revision: 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; SHA-256: cacf03d53ef0935b9775533cb72499a2563273811e9fed73395209d0a3e0d985; URL: https://hack.foo/docs/v5/guides/prereleases -->
# V5 prerelease channel

V5 native prereleases use a separate release and installation channel. Stable
Homebrew `hack` keeps its existing executable and state. A candidate is selected
explicitly through `hack-next`; installing one does not migrate a project, start a
VM, install DNS or trust, or replace stable Hack.

The first supported package is for Apple Silicon macOS. Provider installation,
native project adaptations and host routing remain explicit prerequisites in the
[native candidate guide](/docs/v5/native/full-reference). A packaged candidate is not a claim
of full Compose parity, lower resource use, or compatibility with every project.

## Supported platforms and capabilities

Published candidate release notes link to this section at the candidate's own tag.
It lists what a candidate package covers. It does not list every project the
candidate can run.

### Supported platform

- `darwin-arm64`: the native candidate archive for Apple Silicon macOS. This is
  the only platform recorded in `prerelease.json` and accepted by the installer.

### Unsupported platforms and surfaces

- Intel (x86_64) macOS. The installer refuses before it changes a channel.
- Linux and Windows packages. The bundled Linux guest relay runs inside the
  candidate VM; it is not a Linux host package.
- Homebrew installation of a candidate. Candidate releases never update the
  stable Homebrew formula.
- Remote, gateway, node and dispatch workflows, and the retained macOS app.
- Retired hosted account, team and dashboard flows, Hack Tickets, and the built-in
  GitHub and Linear integrations.

### Candidate capability limits

The [native candidate guide](/docs/v5/native/full-reference) qualifies a bounded subset.
These limits still apply to a packaged candidate:

- Changing the environment overlay, profiles or target of a retained native graph,
  and pruning dependency caches. See
  [frontend integration status](/docs/v5/native/full-reference#frontend-integration-status).
- Installers that modify source files in the writable development source mode. See
  [explicit writable development source](/docs/v5/native/full-reference#explicit-writable-development-source).
- Named users or groups for private environment delivery. They refuse instead of
  running as root. See the private delivery notes at the end of
  [explicit cleanup after a dead foreground owner](/docs/v5/native/full-reference#explicit-cleanup-after-a-dead-foreground-owner).
- Local registries without an explicit opt-in, registries signed by a private
  certificate authority, mutable tags passed directly to `fetch-image`, images over
  the configured image budget, and images without a Linux ARM64 variant. See
  [registry image acquisition without Docker](/docs/v5/native/full-reference#registry-image-acquisition-without-docker).
- Copied or relocated candidate pools. See
  [manual candidate upgrade and rollback](/docs/v5/native/full-reference#manual-candidate-upgrade-and-rollback).
- Downgrading onto newer state: an older candidate that refuses state written by
  a newer one is not a rollback. See [manual candidate upgrade and rollback](/docs/v5/native/full-reference#manual-candidate-upgrade-and-rollback).

## Versions and artifacts

Candidate versions have the form `5.0.0-next.N`, where `N` is a positive integer
without leading zeros. The matching Git tag is `v5.0.0-next.N`. Each version is
immutable: a failed or superseded release gets a new number rather than replacing
its tag or assets.

The native archive is named `hack-5.0.0-next.N-darwin-arm64-native.tar.gz`. It
contains the complete frontend, executor, guest relay, storage root witness and its
byte manifest, config compiler and schemas, shared MCP bundle, launcher, provider
pins, guide, checksums and `prerelease.json` provenance. The compiled frontend
reports the candidate version. The provenance records the exact source commit and
platform; filenames alone do not establish either.

Packaging accepts exactly the files and order that `scripts/build-native-candidate.sh`
checksums for a versioned build, with fixed modes for the storage witness (`0500`),
its manifest and schemas (`0600`), and the config compiler (`0755`). The witness
manifest must match the witness bytes and the planned source revision.

Verify the archive checksum and every bundled file before executing the candidate.
The macOS executable signatures are ad-hoc code-integrity checks. They do not
establish a publisher identity or Apple notarization. The pinned official GitHub
release is the distribution source.

## Prepare and publish

Preparation and publication are separate operations. Preparation validates the
version and source, builds the complete native package, and retains reviewable
artifacts without creating a Git tag or release.

After the channel workflow is merged into `next`, dispatch the existing `Release`
workflow on that branch with an explicit version and its full commit SHA:

```sh
gh workflow run release.yml --ref next \
  -f channel=prerelease \
  -f prerelease_version=5.0.0-next.1 \
  -f source_revision=FULL_NEXT_COMMIT_SHA \
  -f publish_prerelease=false
```

Use the intended candidate's actual SHA in place of `FULL_NEXT_COMMIT_SHA` and an
unused version number. Download the `v5-prerelease-VERSION` Actions artifact from
that run to review the archive, provenance and checksum. The reusable candidate
workflow resolves from the same commit as its caller; no new default-branch
workflow registration is needed for this entry point.

A local versioned build uses the same native bundle builder and requires a clean,
committed source checkout:

```sh
mise exec -- scripts/build-native-candidate.sh /absolute/new/candidate-bundle \
  --version=5.0.0-next.1
```

This builds software and provenance only; it does not reserve the version number,
create a tag, or publish a release.

Publication requires an explicit publish request for the exact protected `next`
commit, successful checks for that commit, and approval through a configured
`v5-prerelease` GitHub environment. An environment without required reviewers is
not an approval gate. Publication refuses missing protection or approval, changed
source, failed checks, and an existing tag or release.

To request publication after reviewing the candidate, dispatch the same command
with `publish_prerelease=true`. The workflow checks protection and exact-head CI
before scheduling review, then checks the head, checks, human approval and tag
absence again before publication. Only the first attempt of a workflow run can
publish. If publication fails after creating a tag, preserve it for inspection
and use a new version; do not force-push or overwrite it.

The verifier reads classic check requirements from the branch's protection
summary and combines them with effective ruleset requirements. These reads use
the workflow's existing repository read permissions. Missing policy metadata or
failed API reads refuse publication; no administrative token is required.

Candidate releases are marked as GitHub prereleases and excluded from “latest.”
They never update the stable Homebrew formula. The stable release workflow rejects
prerelease tags; stable semantic releases continue to use `main`.

The branch dispatch and same-commit workflow selection follow GitHub's
[manual dispatch](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/manually-run-a-workflow)
and [reusable workflow](https://docs.github.com/en/actions/how-tos/reuse-automations/reuse-workflows)
contracts. The publish build runs on the Apple Silicon `macos-15` runner; application
VM tests remain on a separately qualified native host.

## Install, upgrade and return to stable

Use the [candidate installer guide](/docs/v5/native/install) for the explicit
version-pinned installation commands and lifecycle controls. The installer keeps
candidate bundles and homes separate from stable `hack` and `~/.hack`; it does not
change shell configuration or silently select a candidate.

Bundles from `5.0.0-next.3` onward add the storage root witness and its manifest.
A channel created by the `5.0.0-next.1` or `5.0.0-next.2` installer keeps that
release's `manager.py`, which refuses the new layout by design rather than
selecting files it cannot verify. Before upgrading such a channel, stop its
runtimes, download and review the newer tag's installer, run its `upgrade-manager`
against the existing root, then run `upgrade`. See
[upgrade and return to a retained candidate](/docs/v5/native/install#upgrade-and-return-to-a-retained-candidate).
A fresh `--root` does not need this step.

Channels created by the `5.0.0-next.3`, `next.4` or `next.5` installer share one
manager. It accepts at most 17 archive members, the exact size of the layout those
releases ship, and no file names beyond it. Later installers use a fixed 64-member
ceiling, but every member must still be a reviewed name in a complete group. A
later bundle that adds a file therefore needs the same `upgrade-manager` step
first. Upgrading with that newer installer against such a channel also refuses
until you run it, and leaves the channel unchanged.

A truncated, interrupted or oversized official download is a refused installation.
The installer removes only the staging directory that attempt created. It leaves
the current selection, retained bundles and homes unchanged. Retry the same version
after the network problem is resolved.

An upgrade retains the previous bundle and home. Selection changes require the
owning candidate CLI to confirm quiescence. A running runtime, timeout, malformed
receipt or uncertain ownership blocks the switch. Stop owned applications through
their ordinary commands before retrying; a failed probe is not evidence of an idle
runtime.

Rollback selects a retained, verified candidate installation. Each installation
keeps its own home; selecting a different one does not copy VM disks, credentials
or application data. Returning to stable selects the existing stable executable
and its original Docker state. Preserve candidate data for a later retry rather
than trying to make a v4 executable read v5 receipts.

Before accepting a candidate for a project, verify normal start, status, logs,
exec, run, restart and retaining shutdown, then exercise its browser sign-in,
data-backed pages and assets. Record the bundle version and source commit with
the result. Unit tests, hosted CI and a responding health endpoint do not replace
that application check.


---

<!-- Original: docs/guides/native-candidate.md; revision: 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; SHA-256: 4003ad523eb47de2929db84f83590764d19d7c34306a51fc3a49b95f70cde8f6; URL: https://hack.foo/docs/v5/native/full-reference -->
# Opt-in native candidate bundle

`hack-native` is an experimental Apple Silicon macOS executor installed alongside
Hack's supported CLI. It does not replace `hack`, select a Docker context, migrate
projects, or install DNS or trust automatically. Its graph commands support a
bounded subset;
this bundle is not application parity or release qualification.

Build with the repository's pinned Bun 1.4.4, Rust 1.97.1 and Zig 0.15.2 toolchain, Python 3,
and the Rust `aarch64-unknown-linux-musl` standard library already installed. The
build requires a clean checkout and refuses missing prerequisites; it does not install toolchains:

```sh
mise exec -- scripts/build-native-candidate.sh /absolute/new/hack-native-bundle
```

The executor includes `native-config-plan` for explicitly selected authored
projects. Packaging checks the copied executable's pure native planner with a
private synthetic project and requires the candidate home to remain empty. This
checks compiled planning capability; it does not start a provider, change the
default backend or qualify live authored execution.

The destination must not exist. The bundle contains `hack-native`, the static Linux
ARM64 `hack-relay-guest`, `hack-storage-root-witness` with its `native-storage-tool.json`
byte manifest, compiled normal CLI `hack-cli`, the `hack-v5` entrypoint,
the compiled `hack-config-compiler`, generated `hack.project.schema.json` and
`hack.local.schema.json`, provider pins, this guide, `SHA256SUMS`, and one content-addressed shared MCP bundle
under `mcp/BUNDLE_ID/`. Its manifest and native adapter, owner, and compiled backend
are included in the outer checksums. The relay uses
the committed guest Cargo lockfile and Zig linker wrapper, with a separate build
target directory. Packaging verifies its ELF architecture and absence of an
interpreter or shared-library requirements before publishing the bundle. It contains no provider installation, runtime
state, project data, or credentials. It can be copied outside the source checkout;
Rust, Zig, Bun and the checkout are not needed to run the resulting executable.
Host system utilities and the pinned provider remain runtime prerequisites.

Authored persistent mounts resolve the witness tool only from the explicitly selected
native binary's sibling bundle, before hooks or native startup. The helper is built from
the same checkout with the pinned musl target and Zig linker; packaging checks static
Linux ARM64 ELF structure and records its hash, size and source revision. Admission holds
both manifest and helper descriptors, rejects changed bytes or file identities, and passes
the captured path/hash to Rust for independent admission before provider effects. No
download, host execution or emulation fallback occurs. Saved inspection and cleanup use
the already installed, receipt-pinned guest helper and do not require the host artifact.
The byte manifest is not proof of kernel ABI, durable storage or application acceptance.
The first supported qualification corpus is explicit UID/GID0 Bun with SQLite; arbitrary
owner changes and stock PostgreSQL handoff remain refused pending separate qualification.
For versioned candidate packages, channel rules and publishing gates are described
in the [prerelease guide](https://github.com/hack-dance/hack/blob/next/docs/guides/prereleases.md),
and the separate `hack-next` installation path is described in the
[candidate installer guide](https://github.com/hack-dance/hack/blob/next/docs/guides/candidate-install.md).
The build re-signs the compiled frontend, config compiler, and MCP backend with local ad-hoc signatures and
strictly verifies all macOS executables before generating checksums. This checks
code integrity; an ad-hoc signature does not establish a publisher identity or
provide Apple notarization. Verify `SHA256SUMS` after copying the complete bundle.
`hack-relay-guest` runs inside the Linux guest, not on macOS. For graph dependency
selections, set `artifact` to this bundled file's absolute path and
`artifact_sha256` to its entry in `SHA256SUMS`; the runtime verifies it again before
delivery. The `native-stream-relay` feature does not replace this dependency relay.

The compiler and both generated schemas stay beside `hack-cli` as one checksummed
group. Packaging and installation refuse partial, changed, or aliased groups. The
compiler is executable; the schemas are private data. Older bundles with no compiler
or only the complete compiler/project-schema pair remain installable and selectable.
A local schema always requires the compiler and project schema alongside it.
An existing channel with an older retained installer must explicitly run `upgrade-manager` with the reviewed installer before selecting
a bundle with the new group, or use a fresh channel root. This upgrades the manager;
it does not migrate the retained runtime homes.

Shared MCP remains opt-in. Select the verified nested bundle with the existing
installer; substitute `--cursor` or `--codex` as needed:

```sh
/absolute/bundle/hack-cli mcp install --claude --scope user \
  --bundle /absolute/bundle/mcp/BUNDLE_ID --cli /absolute/bundle/hack-cli
```

This selects the normal CLI for tool calls. It does not activate a native project
runtime or change other clients. Keep the complete bundle while clients reference
it. To return to standard stdio, remove the selected client's Hack entry and
reinstall it without bundle options. Channel rollback does not rewrite those client
entries. Older prereleases without MCP assets remain installable. The candidate
installer verifies the complete nested inventory, identity, checksums, modes and
code signatures before selection; it never auto-enrolls clients.

Verify the copied bundle, create a dedicated home, and explicitly select it:

```sh
cd /absolute/copied/hack-native-bundle
shasum -a 256 -c SHA256SUMS
mkdir -m 700 /absolute/private/candidate-home
./hack-native --candidate-root /absolute/private/candidate-home info --json
./hack-native --candidate-root /absolute/private/candidate-home --version
```

The home must already exist, be owned by the current user, and have mode `0700`.
Use its canonical absolute path without symlink components (on macOS, use
`/private/tmp` rather than `/tmp`). Every command requires this explicit home,
including help and version. Its `checkout` field is the historical receipt name
for this stable home; `channel` reports `installed-candidate`. State remains under
`<home>/.hack-local`. Keep this home fixed across binary upgrades: receipts and
child processes bind to its identity. Moving an executable is supported; moving
an active home or adopting another installation's state is not.

Run the normal project CLI through the bundle's `hack-v5` entrypoint:

```sh
export HACK_NATIVE_HOME=/absolute/private/candidate-home
/absolute/copied/hack-native-bundle/hack-v5 ps --path /absolute/project
```

Keep the bundle together and invoke this entrypoint by its full path (do not copy
or symlink only the script). With `HACK_RUNTIME_BACKEND` unset (or `native`) it
selects the native backend and the adjacent executor, even if an inherited
`HACK_NATIVE_BINARY` selects another binary. An explicit
`HACK_RUNTIME_BACKEND=compose` runs the same bundled CLI on the Compose backend
with your own Hack home and existing global routing services. It needs no
`HACK_NATIVE_HOME` and removes the native selectors. Other values refuse with exit
code 64. The [candidate installer guide](https://github.com/hack-dance/hack/blob/next/docs/guides/candidate-install.md#test-both-backends)
describes Compose testing and its shared-state limits: run stable `hack global up`,
then any stable `hack doctor` or `hack doctor --fix`, then stable `hack daemon stop`,
confirm `pgrep -fl "hack daemon start"` prints nothing, and run no stable `hack`
command while the candidate uses your Hack home. Stable `hack global up` (v4.2.0)
starts a stopped `hackd` again, and so does stable `hack doctor --fix` (it asks
first only in a terminal). If the check lists a process, the guide gives the
launchd remedy. The entrypoint turns off daemon autostart in newer builds, so the
candidate does not start the stable `hackd` on its own: a candidate
`hack doctor --fix` skips its `hackd` repair without asking and prints the
command to run yourself, which runs the stable CLI. Do not commit the
project's generated `.hack/.internal/` directory; newer generators rewrite files
such as `compose.override.yml`. The entrypoint preserves arguments, exit codes and
signals through `exec`, and never replaces the installed `hack`. Project-specific
native adaptation, dependency and routing selections remain explicit; this entrypoint
does not prepare a provider or migrate existing projects. An unversioned local
build reports the repository package version. A versioned prerelease build reports
its explicit candidate version and includes source provenance. The `hack-v5`
entrypoint alone does not identify a published release. Unsupported native workflows still
report their existing refusal rather than falling back to Docker.

Native `up` accepts an explicit branch or the branch inferred from a linked Git
worktree when its exact source root can be shared with a fresh or matching pool.
The runtime checks source compatibility before startup hooks; `restart` repeats
this check before stopping the existing graph. A different root in an occupied
pool is refused. This does not dynamically add mounts to a running VM: simultaneous
worktrees with different source roots still require separate pools.

Unfiltered writable source sharing still requires `HACK_NATIVE_SHARED_SOURCE=1`.
An exact repository at `$HOME/.codex/worktrees/<id>/<repo>` is allowed only when
bounded Git registration metadata verifies its worktree root, common directory and
backlink. The enclosing Codex directories are never exported. Sensitive ancestors,
aliases and unsafe ownership or permissions remain refused.

The internal planning path accepts a canonical lowercase DNS-label `--branch`.
It gives each checkout/branch pair a separate enrollment and source namespace;
omitting the selector preserves existing base-instance identities. The frontend
rewrites declared project, service, legacy and OAuth route names after applying
native aliases, then carries the same branch selector through original review,
normalized review, source capture and execution review. Original Compose files
and private environment values are unchanged. Hostnames outside the configured
project bases remain explicit, unchanged claims; normal route collision checks
still apply. A same-checkout branch namespace does not create an isolated source
tree. These planning contracts do not qualify multiple independent source roots
inside one VM pool.

An existing frontend branch mapping may retain a graph admitted before native
branch namespaces. If its current scoped review differs, the frontend first
checks native selection against that exact saved run, owner, namespace and plan:
restore selection for a stopped graph, or authenticated service selection for an
active graph. A native unbranched review of the same canonical project and unchanged
original Compose must then return the saved namespace. Only that retained run
continues with unbranched review and execution arguments and keeps its original
adapted route labels, before branch hostname rewriting. This preserves legacy
source contracts that did not enroll hostname changes. The selected generation,
restore selection and shared-source semantic compatibility are checked again
before admission; mappings, graph receipts and ownership namespaces are not
rewritten. Active legacy restart also rechecks its service, container, boot and
receipt generation after compatibility review, before cleanup eligibility. A
changed selection refuses before stopping the graph. This preflight check does
not make cleanup atomic with that generation; existing ownership and frontend
finalization checks still apply. Fresh and already branch-scoped graphs keep
their normal branch namespace. This compatibility path does not authorize
adopting an unrelated branch or project.

## Compose projects that stay on the Compose backend

In v5, an unchanged Compose project (`.hack/hack.config.json` with
`.hack/docker-compose.yml`) that uses any of the following features runs on the
Compose backend. Native support for them is planned after v5.

| Compose feature | Kept on the Compose backend when |
| --- | --- |
| External network | A top-level network sets `external: true` or `external: {name: ...}`. A reviewed `x-hack-isolated: true` replacement is not external: it creates an owned internal bridge. A network that the selected adaptation (`HACK_NATIVE_ADAPTATION` or the committed `.hack/native/adaptation.json`; see [Native settings files](#native-settings-files)) lists in `isolatedNetworks` gets the same replacement, so it is not external either. |
| External volume | A top-level volume sets `external: true` or `external: {name: ...}`. The native runtime only creates volumes it owns, and there is no native replacement for an external volume. |
| Reserved ownership label | A service, network or volume label key starts with `com.docker.compose.`, `io.hack-local.`, `io.hack.native-config.`, `io.hack.native-file.` or `io.hack.storage-witness.`. Compose, the native runtime and native-config Compose use these labels to prove which resources they own. |
| Build outside the basic form | A service `build` is not the basic form that [`hack config import --dry-run`](/docs/v5/native/config-import#pure-basic-build-preview) accepts (a relative context and optional relative `dockerfile` and `target`), or the service also sets `image`. Build arguments, secrets, SSH, cache options, platforms and other build options are outside the basic form. With `HACK_NATIVE_BUILDS=1` (see below), only a build field other than `context`, `dockerfile`, `target` and `args`, or `image` together with `build`, counts; native build admission reviews the values of those four fields itself. |
| Non-native platform | A service sets a `platform` other than `linux/arm64` or `linux/arm64/v8`, for example `linux/amd64`. The native VM runs Linux arm64. A missing or `null` `platform` is unset and passes. `linux/amd64` passes only for a service that the `HACK_NATIVE_ADAPTATION` selection opts in to [amd64 emulation](#amd64-emulation-with-rosetta-2); every other platform value stays on the Compose backend. |

Native `hack up` and `hack restart` check for these features after selecting the
project and before branch, environment, lifecycle, storage or runtime work. They
refuse with `E_NATIVE_PROJECT_UNSUPPORTED` and one line that names each feature
found, without network or volume names, label keys, paths or platform values.
Nothing is started, stopped or written. Every service is checked, including
services outside the selected profiles.

The check reads only `.hack/docker-compose.yml`, as native start does. It does not
merge Compose override files, follow `extends` or `include`, or read environment
defaults such as `DOCKER_DEFAULT_PLATFORM`: a platform counts only when a service
sets its `platform` field. The native runtime's own review reports `extends` and
`include` as unsupported fields.

The check applies the selected adaptation first, as native start does:
`HACK_NATIVE_ADAPTATION`, else the committed `.hack/native/adaptation.json` or the
`adaptation.<env>.json` for `--env <env>`. Without `--env`, a network counts as
isolated only when every committed adaptation that could apply isolates it, because
the effective env is not known yet. An unchanged Compose file whose external network is listed in
`isolatedNetworks` therefore stays on native, and native start replaces that
network with an owned isolated one. A `linux/amd64` service that `amd64Emulation`
opts in stays on native the same way. The selection is read only when the Compose
file has an external network or a non-native platform. If it cannot be read, is not
version 1, its `isolatedNetworks` is not a list of unique names, or its
`amd64Emulation` is invalid, the command refuses with the same one-line
`E_CONFIG_INVALID` message native start gives, before any runtime request.

To run such a project, select the Compose backend:

```sh
HACK_RUNTIME_BACKEND=compose hack up
```

The bundle's `hack-v5` entrypoint and the `hack-next` launcher accept the same
selection; see [Test both backends](https://github.com/hack-dance/hack/blob/next/docs/guides/candidate-install.md#test-both-backends).

Other labels keep their native behavior. Routing (`caddy*`) and dependency cache
(`hack.dependencies.*`) labels are reviewed as before, and other ordinary labels
are refused with the general native configuration refusal.

Hack's own one-shot marker is not an ownership label. A service labeled exactly
`hack.service.one-shot: "true"` (or `hack.service.one-shot=true` in list form),
the label [`hack config import --dry-run`](/docs/v5/native/config-import)
reports as `compose_one_shot_job`, is reviewed natively as a one-shot: the review
plan marks it `one_shot`, and native `up` waits for it to exit successfully
instead of waiting for it to keep running. The marker adds no container label.
Only that exact key is recognized. Any other `hack.*` key, including another
`hack.service.*` key, is still refused (`external_route_or_owner_label` in the
native review), and a marker next to a reserved ownership label does not exempt
it. The native review also refuses a marker whose value is not the string
`true` (`invalid_one_shot_label`), a one-shot with `restart: always` or
`unless-stopped` (`nonterminating_one_shot`), and a one-shot that also declares
routing labels (`one_shot_route_conflict`).

`hack config adopt`, including `--dry-run`, still requires the Compose backend,
because it reads and adopts the Compose backend's existing containers and
volumes. On the native backend it refuses before reading anything and names the
rerun: `HACK_RUNTIME_BACKEND=compose hack config adopt --dry-run`. See
[Legacy Compose adoption](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/native-compose-adoption.md).

Native image-project `up` builds Compose `build:` services only when you opt in
with `HACK_NATIVE_BUILDS=1` (and the usual `HACK_NATIVE_SHARED_SOURCE=1`). Without
it, a `build:` service refuses before any hook or VM effect and names the variable.
With it:

- Accepted forms are `build: <context>` and a mapping of `context`, `dockerfile`,
  `target` and `args`. Paths follow Compose (the context is relative to the Compose
  file, the Dockerfile to the context) and must stay inside the project. `args` may be
  a mapping of literal strings or numbers, or a list of `KEY=VALUE` literals. Any `$`
  interpolation, a list item without `=` (host variable inheritance), `null`, other
  build keys (`secrets`, `ssh`, `cache_from`, `platforms`, `network` and the rest),
  remote contexts and `image` together with `build` refuse. Values are never shown.
- Build args are not secrets: as with Docker, the image records them in its history.
  A build arg whose value equals a `hack env` secret value of this project and
  environment refuses before any hook or VM effect, naming the service and the
  argument but never the value. The refusal does not suggest the Compose backend,
  because a Compose build would record the value in the image history too. Pass
  secrets with BuildKit build secrets instead; native builds do not support them yet.
- Every build refusal names the service. A refusal from the runtime's build source
  policy (for example a base image that is not a public Docker Hub reference) says
  that it is the build source policy and what to change. Other build failures name
  the service and keep the runtime's message.
- After the runtime is up, each distinct build runs once with
  `runtime build-image` (below), and its filtered output streams to your terminal.
  Every service with that build is then pinned to the built content ID, so review,
  readiness and restore treat it like an image service.
- An existing image for the same build inputs is reused without building. Set
  `HACK_NATIVE_REBUILD=1` to build again; base-image tags then resolve again too.
  Edits to other files in the context do not trigger a rebuild, as with Compose.
- Restoring an unchanged retained run uses the retained images and never builds; if
  one is missing, `up` refuses and asks you to start fresh. `hack restart` also never
  builds: it reuses the running or retained image, or refuses before stopping anything.
- "Unchanged" means the same Compose bytes. A run that mounts no project source and
  uses no dependency cache still restores after its Compose file was edited and put
  back, or after any project file was touched; build-context edits do not rebuild it.
  Its review then differs only in the project source inventory (file sizes and
  modification times), which such a run never reads, and restore keeps the retained
  ownership plan, images and data.
- As with Compose `up`, only build services in the selected profiles are built and
  pinned. A build service in a profile you did not select is not built, and restore
  and restart need no image for it; selecting its profile in a later fresh `up` builds
  it then. Native builds are `linux/arm64` only; `platform: linux/amd64` is still
  refused.

Native review reads Compose `ports` without reading environment values. Each
entry may be short (`[host_ip:][published:]target[/protocol]`, with an IPv6 host
in brackets such as `[::1]:8080:80`) or long (`target`, `published`, `host_ip`,
`protocol`). The host IP and published port may each be one interpolation with a
literal default, such as `"${SEARCH_BIND:-127.0.0.1}:${SEARCH_PORT:-8108}:8108"`.
Native always uses the literal default, even when the variable is set, and warns
with `interpolated_port_default`; the plan records only the variable names. A
reference without a literal default (`${PORT}`, `${PORT:?message}`), a nested
default, an interpolated target or protocol, or one reference that spans several
components is an `unresolved_port_binding` error at
`services.<name>.ports[<index>]`. The review still reports every other finding,
and a service in an unselected profile does not block the plan.

Native publishes only on host loopback. `127.0.0.1` and `::1` are kept. A bare
port or an all-interface binding (`0.0.0.0`, `::`) is narrowed to `127.0.0.1` or
`::1`, with a `proposed_loopback_binding` warning. Compose would bind every
interface in that case; native does not expose development services to the
network. A specific non-loopback address, such as a LAN address, is an
`unsupported_host_binding` error. Keep such a project on the Compose backend.

Native foreground `hack up` publishes the reviewed ports of active services on
host `127.0.0.1`. Each published port is forwarded through an owned application
bridge to the container's target port, after the graph is ready. The rules:

- Only TCP with an explicit host port is published. UDP, an engine-assigned host
  port (a bare `"3000"`), and IPv6 loopback (`::1`) publication are refused with
  `graph_port_publication`; keep those projects on the Compose backend.
- One graph publishes at most 16 ports. Routes and published ports share the
  pool's 32 application bridge sockets.
- Two active services, two graphs in the same pool, or a graph and any other
  host process cannot hold the same host port. Before graph admission, and again
  under the provider lease just before binding, native refuses a host port that
  already accepts connections on `127.0.0.1` (`published_port_in_use`, or
  `E_CONFIG_INVALID` from the frontend check). The other listener is left
  untouched.
- A connection is forwarded only to the container incarnation the bridge was
  started for. A replaced container does not receive traffic from an older
  publication.
- Stopping the foreground owner (Ctrl-C) closes each host listener before its
  bridge and the containers stop, then retires the publication. Dead-owner
  cleanup retires a publication only after proving its owner is gone. A
  retaining restart publishes the same ports again.
- `graph run` and other non-foreground paths do not publish ports and keep
  refusing them with `graph_subset`.

The loopback check is point-in-time. A process that binds the same port on all
interfaces between the check and native's own bind can still share loopback
traffic with it; stop such listeners before `hack up`.

`hack doctor` reports the same features for the current project in its
`compose backend features` check. With `--json`, the check's `composeBackend.features`
lists the closed names `external_network`, `external_volume`, `reserved_label`,
`unsupported_build` and `foreign_platform`. On the native backend a found feature
is a warning; on the Compose backend it is informational. Native doctor applies
the same adaptation selection as native `up` without `--env` before it reports. When it
finds an external network, the message also names the `isolatedNetworks` selection
above, which keeps that network's project on native.

A basic build is not one of these features, but without `HACK_NATIVE_BUILDS=1`
native image-project `up` refuses it, so doctor does not report it as ok then. On the
native backend the check warns, names the variable and the next steps (set
`HACK_NATIVE_BUILDS=1`, preview the authored native conversion with
`hack config import --dry-run`, or select the Compose backend), and its JSON adds
`composeBackend.nativeUpRefusals: ["basic_build"]`. On the Compose backend the same
note is informational. With `HACK_NATIVE_BUILDS=1` set, doctor classifies builds the
way native builds admit them and reports no basic-build refusal.

Publication control tokens are delivered to the relay through a one-shot inherited
pipe (`--control-fd 0`), never through process arguments. The relay reads exactly
32 lowercase hexadecimal bytes, requires EOF, and closes the descriptor before
binding its listeners. Missing, malformed, or stalled input refuses startup; the
old token argument form is not accepted. Rebuild the runtime and relay together.

Tmux lifecycle sessions receive their owner token and environment through
`source-file -` on stdin. The owner token stays in the session environment;
existing sessions with the older owner option remain readable.
Commands sent to an existing tmux pane receive selected environment values through
a one-shot mode-0600 file inside a private mode-0700 temporary directory. The CLI's
internal launcher reads and removes that payload before starting the command,
preserving keys such as `UID` without value-bearing arguments. Leading command-local
assignments override selected values; the existing pane shell still parses multiline
commands and pipelines. The command keeps the pane's terminal stdin. Failed sends
remove their staged payload; if the pane never executes a successfully sent command,
the private payload remains until it is consumed or explicitly cleaned up.

Native `up` and `restart` also stay in the foreground in every project:
`--detach` refuses with one `E_USAGE` line. Run `hack up` in its own terminal and
keep it open, use `hack ps` and `hack logs` from another terminal, and press
Ctrl-C to stop it. For detached startup, use the Compose backend.

Foreground image-project `up` prints each startup step (input, runtime, images,
services) and one ready line, `Project is ready (SERVICES; run RUN)`, after the
graph is ready and its run mapping is published. Under it, `up` lists each routed
service's reviewed hostnames as HTTPS URLs (with the `HACK_NATIVE_HTTPS_PORT`
port unless it is 443) and the published loopback ports. Without the native
HTTPS frontend it says that routes are not served on this host. Ctrl-C prints the
stop sequence and, once owned cleanup is confirmed, one stopped line that says
whether named volumes and the stopped run mapping were kept (`Native project
stopped.` when no run mapping was published). Until the ready line,
startup holds the runtime's exclusive provider lease, so graph admission cannot
interleave with another operation. A `hack ps` from another terminal during that
window waits briefly, then reports that the runtime is busy (`runtime_busy`,
exit 0) instead of failing. After the ready line, `hack ps` and `hack logs` run
alongside the foreground command.

While the project runs, foreground `up` reports each service container that stops,
as attached Compose `up` does (`SERVICE exited with code N`), including one-shot
services. It keeps running while any service runs; once every service container has
stopped, it prints that, stops the graph through the ordinary owned cleanup and exits
0, like Compose `up` without `--abort-on-container-exit`. A service whose restart
policy has a pending restart (`restarting`) is not stopped: `up` keeps running and
reports the service only if it later exits for good, for example when `on-failure:N`
runs out of retries. Unlike Compose, the exit that triggered an engine restart is
not printed separately. The monitor reads
`graph observe`, which takes no provider lease, so it never contends with `ps`, `logs`
or `exec`.

Runtime refusals print their code and, when the runtime marks its message as a fixed
literal that cannot carry values, that message and the service it concerns (for
example `Service web: Pinned image architecture or implicit volumes are
incompatible.`). Formatted runtime messages stay omitted. A start refused before the
runtime reserved any graph state reports that nothing was created and no cleanup is
needed, with the startup diagnostic, instead of unconfirmed cleanup.

### Network aliases and the Compose project name

Native review accepts `networks.<name>.aliases` on a service attachment, as
Compose does: each alias is an extra DNS name for that service on that network
only. Aliases must be literal DNS names (letters, digits, `-`, `_` and dots; case
is folded), at most 8 per attachment. Interpolated aliases and the other
attachment keys (`ipv4_address`, `ipv6_address`, `priority`, `link_local_ips`,
`mac_address`, `driver_opts`) remain `unsupported_field`. Native networking keeps
one owner per DNS name, where Compose would round-robin: an alias that two active
services declare on one network, an alias that is another active service's name
on a network both join, or an alias that is also one of the same service's
`extra_hosts` names refuses with `network_alias_collision`. When one of the two
services is left inactive by the selected profiles, review reports the warning
`inactive_network_alias_collision` instead; selecting that profile refuses. The
graph verifies every reviewed alias as part of each container's identity. `hack
run` one-off containers keep only the service name, so they never become a second
owner. Aliases are part of the reviewed plan: changing one is an ordinary plan
change, never a hostname-only change.

Compose also supplies its project name to interpolation as `COMPOSE_PROJECT_NAME`
and names each container `<project>-<service>-1`, which other containers can
resolve. When a service references `COMPOSE_PROJECT_NAME`, native `up` and
`restart` declare the instance's Compose project name (the same `<project>` or
`<project>--<branch>` the Compose backend passes to `docker compose -p`) as the
normalized document's top-level `name`. Review then binds the variable to that
name (warning `compose_project_name_binding`) and adds the container name as an
alias on every network the service joins, under the same collision rules. No
caller can supply a different value. The name must follow Compose's rule
(lowercase letters, digits, `-` and `_`, starting with a letter or digit), and a
container name longer than one 63-byte DNS label refuses with
`compose_container_alias_too_long`. A document that does not reference the
variable keeps identical normalized bytes and gets no container-name aliases, so
a hard-coded `<project>-<service>-1` name does not resolve natively; use the
service name or `${COMPOSE_PROJECT_NAME}`. Without a declared name, for example
when the internal planning path reviews the original file directly, review warns
with `compose_project_name_unbound` and execution refuses with
`execution_environment_missing`. Plans and receipts that carry the new fields are
not readable by older bundles; clean up with the owning bundle.

## Manual candidate upgrade and rollback

Manual candidate bundles are selected by their full path. The separate
[prerelease installer](https://github.com/hack-dance/hack/blob/next/docs/guides/candidate-install.md) manages verified versioned selections
with independent homes; it does not migrate runtime data. `hack-v5 update` refuses before discovering an
installed binary or contacting a release server; install a separately reviewed,
complete bundle to change the candidate.

1. Keep the previous complete bundle and its `SHA256SUMS`. Copy the new bundle into
   a separate directory and verify every checksum before using it. A checksum
   failure or incomplete copy is a failed installation; preserve it for inspection.
2. Retain application data with ordinary `down` for each owned graph, confirm its
   foreground owner and host processes have retired, and stop the owned candidate
   runtime. Keep existing bundles in place while any of their child processes live.
3. Select the new bundle's `hack-v5` by its full path with the same canonical
   mode-`0700` `HACK_NATIVE_HOME`. Check its `info` identity and update any explicitly
   selected guest-relay artifact paths to the verified complete bundle. Normal
   frontend `up` validates the retained selection offline, resumes its clean owned
   VM once if stopped, and then repeats live retained-data and restore-generation
   checks. Restore the application and read back a saved data marker before accepting
   the upgrade. A restore selection (`--expect-generation`) or recovery selection
   reviewed by an older bundle can use the previous retained-volume encoding (see the
   [volume identity audit](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/volume-identity.md)) and then refuses as
   changed even when no volume changed: run the review and selection again with the
   new bundle.
4. For rollback, retain-stop the new candidate in the same way, select the previous
   verified bundle with the same home, and repeat application/data readback. A prior
   binary refusing newer state is an unsupported downgrade, not a successful rollback.
   Preserve that state; do not rewrite receipts or adopt another home's data.

The provider runs with a short temporary HOME alias, `/private/tmp/hkl-<owner>`, a
symlink to `<home>/.hack-local/run/smolvm/home` that keeps its Unix socket paths
within the macOS length limit. A clean `runtime down` keeps this alias, so no other
local user can take its name while the pool is stopped. It removes only the provider
socket files the stop proved closed, through the real data directory.

Host cleanup or a reboot can still remove the alias. For a clean stop, observation
commands such as `runtime status` accept the absent alias and create nothing, and the
next `runtime up`, `runtime recover` or approved-host update restores the exact alias
under the pool lock before using it. If another entry (a file, a directory, another
user's link) holds that path by then, it is never followed, replaced or removed: the
pool records a fresh random `/private/tmp/hkl-*` alias in its receipt and creates
that one instead. A pool with dependency sockets refuses a fresh alias with
`socket_alias_collision`, because its provider record pins those socket paths under the
original alias; remove the entry at that path and retry.

For any other receipt with an absent alias, normal commands report
`provider_home_missing`; they do not initialize another pool or recreate the alias
during observation. Explicit `runtime recover --json` can restore only that
absent exact alias, after verifying the receipt-bound dead provider, both recorded
disks, free VM lock, closed disk handles, and no active provider command. Existing
files, directories, foreign links, a live or reused PID, and uncertain ownership
refuse without replacement. Recovery rechecks the receipt before exclusive creation,
then validates socket absence and flushes the disks before recording
`recovered-unclean`. If those final checks fail, it reports
`provider_home_restored_recovery_incomplete`, keeps the exact owned alias and retained
data, and requires inspection before retry. No guest is started by alias recovery.
Interrupted starts without a recorded process or both identified disks remain
outside this repair path.

A physical macOS reboot may also renumber the mounted filesystem device. Strict
disk and source checks still refuse a changed device number; missing-HOME recovery
does not waive them. For an offline **stock pool**, inspect the separate migration:

```sh
./hack-native --candidate-root /absolute/private/candidate-home runtime host-filesystem-recovery --json
./hack-native --candidate-root /absolute/private/candidate-home runtime recover-host-filesystem --expect-sha256 <selection_sha256> --accept-legacy-device-rebind --json
./hack-native --candidate-root /absolute/private/candidate-home runtime recover --json
```

Review the inspection before selecting its hash. This explicit legacy migration
requires an absent recorded provider whose start predates the current host boot,
no active provider commands, exclusive existing operation/VM locks and closed disk
handles. Both disk inodes, sizes and ext4 UUIDs, the exact source path/inode and its
ownership must be unchanged; only one common old-to-new device-number change is
allowed. The inspection is read-only. Publication atomically changes only the
owner's disk and source device numbers, retaining its phase and process record.
Normal commands keep their strict identity checks.

Legacy receipts have no original host boot UUID or filesystem volume UUID. Calendar
timestamps corroborate a reboot, and matching retained file identities constrain
the migration, but neither proves original volume continuity. The opt-in explicitly
accepts that limitation; copied or relocated pools are outside this procedure.
Prepared-base pools and pending owner/network/activation updates require separate
recovery and are refused. A torn owner publication preserves `owner.pending` and
blocks another migration; do not delete or adopt that file manually.

This does not start the VM, restore HOME, retire stale sockets or rewrite historical
graph receipts. Use ordinary recovery afterward. Historical shared-source graphs
retain the prior identity and may require verified cleanup plus a new generation;
successful metadata migration alone does not establish application recovery.

After that explicit provider recovery and one audited VM boot, a retained graph
from the immediately preceding guest boot can still carry old host device numbers
in its publisher, relay-control, and dependency-socket receipts. Inspect and select
one run's host-pin recovery separately:

```sh
./hack-native --candidate-root /absolute/private/candidate-home graph inspect-host-pin-recovery --run-id <run-id> --json
./hack-native --candidate-root /absolute/private/candidate-home graph recover-host-pins --run-id <run-id> --expect-selection <selection_sha256> --accept-legacy-device-rebind --json
./hack-native --candidate-root /absolute/private/candidate-home graph recover-cleanup --run-id <run-id> --expect-receipt <original_receipt_sha256> --json
./hack-native --candidate-root /absolute/private/candidate-home graph retire-recovered-publisher --run-id <run-id> --expect-owner <owner> --json
```

The first command only inspects. The second publishes a private, exact-run
witness before cleanup; it changes no graph, publisher, control, or dependency
receipt. It requires the provider's repaired current disks/source, unchanged
recorded inodes and raw receipts, dead owners whose recorded starts precede the
current physical host boot, refused socket listeners, and the immediate guest
boot transition. It also binds retained volume names and actual labels. Cleanup
and retirement can use the witness only for those selected old pins; ordinary
reads and later publisher generations remain strict. Missing or foreign pins,
active listeners, changed resources, pending journals, or further guest boots
refuse without adopting another run. A completed older cleanup journal is
retained as history and does not itself block a later selected generation.

Legacy receipts do not identify the original APFS volume. This explicit
device-number rebind cannot prove pre-reboot volume continuity. Completing these
commands retains the old run's data and proves cleanup of its dead generation;
it does not migrate `graph.source.shared`, restore the application, establish
route readiness, or claim overall v5 acceptance. Same-run source continuity
requires a separate explicit witness-bound transition after cleanup and
publisher retirement. If macOS removed the foreground or relay-control
directory itself during reboot, this command refuses: the old pin receipts no
longer exist, and absent pathnames cannot stand in for their recorded owner
identities. That case requires a separate selected absence-recovery procedure.

When a **physical host reboot** removed both the deterministic foreground
publication root and this run's relay-control root, inspect the distinct
absence path with the private original provider Owner and its exact
pre-migration host-filesystem inspection:

```sh
./hack-native --candidate-root /absolute/private/candidate-home graph inspect-absent-publication-cleanup --run-id <run-id> --original-owner-file <private-original-owner.json> --host-inspection-file <private-inspection.json> --json
./hack-native --candidate-root /absolute/private/candidate-home graph recover-absent-publication-cleanup --run-id <run-id> --original-owner-file <private-original-owner.json> --host-inspection-file <private-inspection.json> --expect-selection <selection_sha256> --retain-data --accept-unpinned-post-reboot --json
```

Inspection does not create a publication root. A failed selected action can
leave only its private lock reservation; inspection recognizes that exact
lock-only state. Recovery locks the foreground publication before acquiring
the VM lease, then durably records the selected absence before any cleanup.
It retains volumes, verifies the stopped receipt, and records a separate
absent-publisher retirement. Ordinary publication and cleanup cannot infer
ownership from missing paths. The old foreground PID and original physical
volume are not proved by legacy graph receipts; this path requires explicit
acceptance of that post-reboot limitation and refuses a changed boot, present
or foreign publication, stale selection, pending state, or changed resources.
An interrupted recovery can resume only its exact selected intent on the same
host and immediate guest boot. A later successful restore treats this witness
as history; it never grants cleanup of the new generation.

This operation does not change historical shared-source device identity.
Source-mounted projects require the separate selected source-continuity step
before normal same-run restore. The command's stopped/data-retained result is
not proof of application startup or routing.

The frontend project-run mapping also records directory device numbers. If native
inspection succeeds after provider recovery but ordinary project commands refuse
the mapping, inspect the exact instance with the current bundle:

```sh
./hack-v5 doctor --path /absolute/project --branch my-instance --native-run-mapping inspect --json
./hack-v5 doctor --path /absolute/project --branch my-instance --native-run-mapping repair --expect-selection <selectionSha256> --accept-legacy-device-rebind --json
```

Omitting `--branch` uses the same linked-worktree default as project commands;
detached linked worktrees require an explicit instance. Inspection writes nothing.
A mapping that still matches the checkout reports `state: "current"` with its run,
the native graph phase (or `null` while the pool is stopped), whether the graph's
run, owner, namespace and plan match the mapping, and `repairRequired: false`.
Only a mapping whose scope no longer matches goes through the legacy device-rebind
inspection below, which returns the `selectionSha256` that repair requires.
Repair requires the exact selection and explicit acceptance of unproven original
filesystem volume continuity. It changes only the three scope directory device
numbers, preserving canonical paths, inodes, branch, run, owner, plan, environment
selection, profiles and AWS selector. The selected graph and current project share
must still match native authority. An audit copy retains the original private
mapping. Held locks, pending restart state, substituted directories, stale hashes
and changed native identities refuse publication.

This is a metadata repair, not an app restart: it does not retire sockets, modify
graph history, remove data or establish browser readiness. Doctor's ordinary
`--fix` never applies it. Run the normal project command separately after reviewing
the result; its existing native graph and ownership checks still apply.

#### A run mapping from another native home

Each launcher version has its own native home, but the run mapping lives in the
project. After an upgrade, a mapping the previous version left behind names that
version's home. Project commands from the new home (`ps`, `up`, `down`,
`doctor --native-cleanup inspect`) refuse it with a line that names the owning home
and what to do:

- **Stopped cleanly.** The owning home's frontend records show that the run's latest
  `hack up` acknowledged confirmed graph cleanup, HTTPS retirement and down hooks.
  The refusal names the exact release command. Inspection reports
  `state: "foreign-home"`, `owner: "stopped"` and the `selectionSha256` it needs:

  ```sh
  ./hack-v5 doctor --path /absolute/project --native-run-mapping inspect --json
  ./hack-v5 doctor --path /absolute/project --native-run-mapping release --expect-selection <selectionSha256> --json
  ```

- **Live.** The owning frontend's PID still exists. The refusal names the home and
  PID. Stop it with Ctrl-C in that `hack up`, or run `hack down` with the version
  that owns that home, then retry. Release refuses.
- **Interrupted or unproven.** The frontend exited without acknowledging cleanup, or
  the home has no readable record for the run (for example a legacy mapping, or a
  home that was moved or replaced). Use the owning version's
  `hack doctor --native-cleanup inspect` and `hack down`. Release refuses.

Release proves ownership; it never just overwrites. The stored scope must differ
from this checkout in its native home only, that home must still be the recorded
directory, and the release holds the owning home's finalization lock, so that home
cannot start the run again meanwhile. A retained `hack up` in the owning home records
an admission under that same lock before its last mapping check and before any
runtime effect, and keeps it until it registers its own frontend lifetime. Release
refuses while an admission exists (a live startup is reported as live; one whose
startup exited is reported as interrupted). Owning homes from versions without this
admission record are not covered by it. A changed selection, held project locks or a
pending restart refuse, as does a down-hook journal that is owed, unknown or another
run's. A completed record of the same run, which a successful stop keeps, is allowed.
Release removes only the project's mapping and keeps its exact bytes in an audit
file beside it. The previous home's
graph and named volumes stay in that home; this home's next `hack up` starts the
instance with fresh data.

Compatibility is qualified for specific bundle hashes and state formats. The
displayed version alone does not establish frontend/executor or downgrade
compatibility. V4 and candidate homes remain separate; this procedure does not
migrate V4 data into the candidate or replace the installed `hack`. DNS, trust and
client configuration are outside this bundle-selection procedure.

Provider setup is separate and explicit. Obtain the exact archives identified in
`provider-pins.json`, then run:

```sh
./hack-native --candidate-root /absolute/private/candidate-home runtime prepare --archive /absolute/smolvm-archive.tar.gz
./hack-native --candidate-root /absolute/private/candidate-home runtime prepare-engine --archive /absolute/docker-archive.tgz
./hack-native --candidate-root /absolute/private/candidate-home runtime prepare-network-tools --directory /absolute/private/pinned-apks
./hack-native --candidate-root /absolute/private/candidate-home runtime probe --json
```

Preparation keeps each archive it extracted (`providers/smolvm-installing/release.tar.gz`
and `providers/docker-installing/release.tgz`). If something outside Hack changes a
prepared tree, for example a cleanup or backup tool that prunes empty directories,
every start refuses with `artifact_digest_mismatch` and the message names the repair.
A stopped runtime's `runtime status` and `runtime down` still work, because they run
nothing from the tree, so an installer quiescence check is not blocked. To repair the
tree, stop the runtime and run:

```sh
./hack-native --candidate-root /absolute/private/candidate-home runtime repair-provider-tree --json
```

The repair holds the provider lock and requires a stopped (or uninitialized) runtime.
It requires the preparation record to match this executor's pins and the kept archive
to be an owned regular file with the pinned SHA-256. It then copies and hashes the
archive again, extracts it, checks the code signature (SmolVM), and requires the fresh
tree to match the digest recorded at preparation. Only then does it rename the changed
tree aside as `providers/<tree>-changed-<id>` and put the fresh tree in its place. It
keeps the changed tree for inspection and never deletes it; remove it yourself once
you no longer need it. Runtime state, disks and volumes under `run/` are not touched.
An intact tree is reported with `repaired: false`. A repair that fails a check changes
no tree and keeps its private `-repairing-` staging directory. Without a kept archive the repair
refuses (`provider_repair_unavailable`); prepare a fresh candidate home instead.

The pins also name a BuildKit client (`buildx`, `darwin-arm64`) for native image
builds. Prepare it before using `HACK_NATIVE_BUILDS=1`; it is optional otherwise:

```sh
./hack-native --candidate-root /absolute/private/candidate-home runtime prepare-builder --archive /absolute/docker-buildx
```

The command takes the exact release file named in `provider-pins.json`. It checks
the SHA-256 before it changes any state, then copies the file into private candidate
state and checks its code signature. If a prepared client exists, the command checks
it again and does not replace it. If the prepared tree changes, `runtime probe`
refuses; it reports `builder_prepared` when the client is present and unchanged.

`runtime build-image --request <file> --json` builds one image in the running
runtime's engine with that client. Native `up` calls it for `build:` services when
`HACK_NATIVE_BUILDS=1` is set; you can also run it directly. The request is a private
JSON file (a singly linked, mode-`0600` file owned by you):

```json
{"version": 1, "project_root": "/absolute/project", "context": "app",
 "dockerfile": "Dockerfile", "target": null, "args": {"NAME": "literal"},
 "policy": "missing", "timeout_seconds": 1800}
```

- The context and Dockerfile must be inside the project and reached without symlinks.
  The Dockerfile is read, never run, to find every image it can pull. Each image must
  be a public Docker Hub reference; it is pinned to a digest before the build starts.
  Base images with stored `ONBUILD` triggers refuse. The client builds from a private
  copy of the Dockerfile and ignore rules that were scanned, so editing either file
  during the build has no effect on it.
- Build arguments are not secrets, exactly as with Docker: the built image records
  their values in its history, and an argument that selects a base image appears in
  the resolved base references that the receipt and the result report. Never pass a
  secret as a build argument. BuildKit build secrets are the right mechanism for
  secrets; native builds do not support them yet.
- Every build runs under a BuildKit source policy: only the pinned base images
  resolve as images, and network sources (`ADD` of an `http`, `https` or git URL, and
  image blob sources) are denied. The engine would otherwise fetch those from outside
  the isolated build network. The policy also covers sources that a base image's
  stored `ONBUILD` triggers add; such bases refuse before the build anyway.
- Argument values reach the client only through a private definition file (mode
  `0600`, removed after the build), never its command line or its environment; the
  client's environment is a fixed list of its own settings. Names must be plain
  identifiers. Names BuildKit or buildx interpret themselves (`BUILDKIT_*`,
  `BUILDX_*`, `SOURCE_DATE_EPOCH`) and the platform arguments refuse.
- Build output is shown on stderr after filtering, as defense in depth: every
  argument value is replaced with `[redacted]`, also when quoted or escaped the way
  the client prints values, terminal control characters are removed, lines are cut at
  16 KiB and output stops after 4 MiB.
- `missing` reuses a verified image for the same build key without running the client;
  `rebuild` always builds. The key covers the Dockerfile and `.dockerignore` bytes,
  target, arguments and versions, not the context's other files (as with Compose).
- The runtime must have network egress and the isolated build network that a runtime
  started by this version sets up. An older runtime refuses with
  `native_build_runtime_restart`: stop it and start it again.
- `runtime down` refuses while a build runs. Ctrl-C or SIGTERM cancels the build and
  stops the client's whole process group; so does the time budget (default 30 minutes,
  at most 2 hours). Both also apply while base images resolve, before the client
  starts: the budget covers the whole operation.
- A cold build needs at least 6 GiB free on the runtime's storage disk, or twice the
  last image of the same build if that is larger; otherwise it refuses with
  `native_build_storage` and deletes nothing. After each successful build, BuildKit's
  cache is pruned to 8 GiB. The cache holds only build steps; pruning never removes
  images, containers or volumes.

`runtime reclaim-build-images --json` removes build images that a newer build of the
same key replaced. It keeps every image a build receipt names as current, every image
that any retained run's saved state mentions, every image a container still uses (the
engine refuses those), and every image whose ownership labels are not exactly this
runtime's. Each removal deletes that one image only, never its untagged parent
images. It refuses while a build runs, and removes nothing if it cannot read all
saved run state. The report lists removed images and why each other one was kept.

Before startup, network-tool preparation additionally requires all four pinned
Alpine aarch64 APKs in a current-user-owned private directory (mode `0700`), with
regular, singly linked mode-`0600` files. Acquire the matching public package bytes;
the command never downloads packages or accepts substitute versions.

The pinned files come from the Alpine **v3.19** `main` repository for `aarch64`
(`https://dl-cdn.alpinelinux.org/alpine/v3.19/main/aarch64/`). Other Alpine
releases, such as v3.20, publish packages with the same file names but different
bytes; those fail the hash check below.

| File | SHA-256 |
| --- | --- |
| `iptables-1.8.10-r3.apk` | `31ab6343f1f3d0fbbf290c4dcf0430b2d08e8073e516e13530dfab25b097d467` |
| `libmnl-1.0.5-r2.apk` | `d15e6313880bdd14959f42c1556b4a810ef4894992ae9f73b148126f0cc6021d` |
| `libnftnl-1.2.6-r0.apk` | `ec1c2b02869fc65bcf7a1105e3a7ac5df1bd9a8bd8b399cb6cf650dd3112c021` |
| `libxtables-1.8.10-r3.apk` | `f0accefde240ece6722479b46cb014d7d2f745af7d796e8eec3ced53571e1088` |

All APKs are validated before candidate state is changed. Installation publishes a
complete private directory atomically; an existing installation is revalidated and
reused without overwriting files. Corrupt installs or interrupted
`network-tools-installing` staging are retained and refused for manual review.
The executor bundle includes no APKs; prepare them explicitly before `runtime up`.
This command changes only host candidate artifacts and does not boot or modify a VM.

Preparation verifies the pinned archive hashes before extraction; SmolVM also
requires its existing signature verification. No fallback to global providers or
v4 state is enabled. Runtime startup is a further explicit operation subject to
host resource admission. Read `--help` for the candidate command surface.

The development profile reserves the declared 32 GiB storage disk and 10 GiB
overlay ceiling plus 16 GiB of host disk space before a fresh startup. Starting
again on a verified running pool, or restarting an exactly clean stopped pool whose
last `down` completed, reuses existing disks and reserves only the 16 GiB host
reserve; `runtime probe --profile development --json` reports the basis in
`disk_budget_basis`, and `retained_reserve_refusal` names why a stopped pool's
disks were charged again. A restart uses that reserve only when free disk is
below the fresh budget; with enough room it starts on the fresh budget as before.
Any other stopped pool keeps the fresh budget. The
unchanged memory budget is a 10 GiB free-plus-file-cache estimate: 6 GiB guest,
2 GiB provisional provider overhead and 2 GiB host reserve. Normal and warning
macOS pressure can qualify only with that headroom, normal thermal/performance
state and stable swapouts. Development samples before the startup lease and again
under the lease before allocation, keeping the same swapout baseline across both
windows.
Critical, unknown or incomplete observations refuse; there is no bypass option.
It reports host load without refusing solely because unrelated jobs raise the
one-minute average. The research profile keeps its normal-only pressure policy,
16 GiB raw-free-memory floor, 100 GiB disk floor and host-load qualification
envelope.

For live Development effects, the host headroom floor is 2 GiB under normal
pressure and 4 GiB under warning, plus measured provider footprint above the
6 GiB guest and 2 GiB provisional overhead estimate. Changed swapouts and thermal
warnings still refuse effects. This does not cap provider footprint or qualify
runtime efficiency. Admission JSON records the numeric pressure level and typed
state; the legacy `memory_pressure_normal` boolean remains false for warning.
Saved reports do not grant resource authority.

The normal `hack-runtime-candidate` / `hack-local` development build remains bound
to its source checkout, including when all Cargo features are enabled. Only the
separate `hack-native` binary opts into installed-home discovery. Existing provider
and receipt ownership checks remain in force.

For an existing owned graph, bounded service diagnostics use its run identifier:

```sh
./hack-native --candidate-root /absolute/private/candidate-home graph logs --run-id RUN_ID --service web --tail 200 --json
./hack-native --candidate-root /absolute/private/candidate-home graph exec --run-id RUN_ID --service web --json -- /bin/echo hello
```

Both commands select the current container and recheck its boot, receipt generation
and ownership before reading or executing. Logs include exited services, default to
200 lines (maximum 1,000), and return bounded, UTF-8-lossy text with a truncation flag.
`lines` lists the retained lines in engine order, so stdout and stderr interleave by
time; `stdout` and `stderr` hold the same lines per stream. Retention keeps whole
lines, newest first, within 32 KiB of JSON text and sets `truncated` when older lines
were dropped. Only a single line longer than that budget is cut. `hack logs SERVICE
--no-follow` prints `lines` in that order, each to its own stream. Authored projects
return only `stdout` and `stderr`, and each stream also stays within 16 KiB of JSON
text: older whole lines go first, and a newest line longer than that keeps its most
recent bytes.

`graph observe --run-id RUN_ID --json` reports each service container's current state
(`running` with the engine's health, `exited` with its code, `dead`, `created`,
`absent` or `unknown`) without taking the provider lease. It only reads, checks each
recorded container's ownership, runs no probes and grants no authority; foreground
`hack up` polls it to report service exits.

`project plan` without `--json` exits non-zero (`plan_diagnostics`) after printing a
report that contains an error diagnostic. With `--json` it exits 0 and the report is
the result: `diagnostics` and `enrollment_compatible` carry the outcome, because Hack
plans original input that its normalization adapts afterwards.
Exec requires a running service and returns Base64 stdout/stderr to preserve arbitrary
bytes, an exit code, and a truncation flag. The CLI also exits with the command's exit
code. Retained exec output is limited to 1 MiB per stream.

Exec is noninteractive: stdin is closed, no TTY is allocated, and arguments are passed
literally without an implicit shell. The default wait is 30 seconds, configurable up
to 120 with `--timeout-seconds`. Timeout or transport failure means completion is
uncertain: the command may still run, and Hack does not replay it. Exec inherits the container's static environment. When the selected service has a
committed private environment attachment on the current boot, it reuses that
service's exact read-only launcher mounts and original expiry. No values are copied
into engine metadata, and exec never renews credentials. With the current launcher,
managed exec resolves a command name such as `bun` against PATH inside the selected
container after applying its environment; an explicit path still runs literally.
Older launcher mounts require a restart before using command names. Changing
overlays is unsupported. Neither command persists application output in runtime
receipts; output can contain sensitive application values and should be handled
accordingly.

## Explicit normalized public Compose input

A frontend can pass a reviewed public Compose document without replacing the
original configuration or relaxing source exclusions. Add all three flags to
`project plan`, `project capture`, `project publish-source`, `project verify-source`,
or fresh `graph run` / `graph serve`:

```text
--normalized-file /absolute/public-normalized.yml
--expect-original <sha256-of-original-compose-bytes>
--expect-namespace <reviewed-workspace-namespace>
```

Keep `--file` pointing to the original Compose file inside the selected project;
relative paths retain that file's directory as their base. Obtain the namespace
from `hack-native --candidate-root HOME plan --project PROJECT --json`. Review the
normalized `project plan` result, then pass that exact `--expect-plan` to capture,
publication, and graph execution. Every operation rechecks the original hash and
namespace. The normalized file must be a nonempty regular file of at most 256 KiB;
symlink files and hardlinked files are refused. Its bytes are retained in memory,
not copied into candidate state. The input is public configuration only: managed
secrets still use the separate `graph serve --environment-stdin` private envelope.

The file-based enrollment, source-sync, `graph restart`, and `graph restore`
commands do not accept normalized input. A stopped normalized graph instead uses
`graph restore-selection --run-id RUN_ID --json`, followed by `graph serve-restore`
with the same run and original input identity, the returned
`--expect-generation`, a freshly reviewed plan, and fresh environment, dependency
and route selections.
Normal foreground `hack restart` performs this selection and retained-data restore.
It verifies the old containers and networks are absent and the retained volumes
still have their recorded identities; it does not silently create replacement data.
When the original Compose file is unchanged, retained startup also selects the
authenticated container image IDs from that stopped graph. Mutable tags are not
resolved again for those services. Missing images still refuse native admission;
this selection never replaces generation, source or resource checks. Changing the
original Compose file uses normal image resolution and the existing compatibility
rules, rather than silently adopting an old image for a new declaration.

Editing the Compose file of a stopped graph and running `hack up` again reconciles
the same run, as `docker compose up` does. Every container and network is
recreated from the new review, so changed commands, images, environment and added
or removed services take effect. A named volume whose key the run already retains
is reattached under its recorded name after the same label and identity checks; a
newly declared volume is created fresh; a retained volume the new file no longer
declares stays owned and unmounted until `hack down --remove-data` (Compose also
keeps project volumes). Retained data is only ever reattached to the run and
namespace that created it.

Graphs with `hack.dependencies.*` caches reconcile the same way. A cache's identity
covers only its own inputs: the initializer's service definition and resolved
command, entrypoint, environment and user, the cache declaration, its image, the
declared lockfile and runtime-file contents, and the cache volume layout: every
service that mounts the cache volume, with its target, subpath and `:ro` mode. Any
of those services can write the shared contents, so adding, removing or changing
such a mount is a cache input; mounts stay as declared, as in Compose and v4, and
are not forced read-only. Caches are shared across linked worktrees and branch
instances only while every service other than the initializers mounts them
read-only. A service that mounts the cache read-write can change its contents
through its own image, command, environment or source, which the identity does not
cover, so that cache is scoped to this checkout and branch instance and never
shared. To share it again, mount it with `:ro` in the other services. A run created
by an earlier build whose cache has such a writer moves to its own instance cache
once instead of reusing the shared one. Any other edit to another service, such as an
environment value on the app, keeps the cache. An edit to one of those inputs,
including a lockfile, selects the cache for the new identity as a fresh `up` would, so the initializer installs into it; the old cache
is shared and is only released by this run. Each such `up` publishes the current
source snapshot. A retained named volume is never reused as a dependency cache:
declaring one refuses and names the service and the `hack.dependencies.cache-volume`
field. Caches recorded by earlier builds, whose identity also covered the whole
Compose file, are kept while that file is unchanged and replaced once on the first
edit. Live source, a cache scope carried across a source-device rebind or a pending
initializer cache release keep the narrower rules below: a Compose edit other than
a routed hostname change refuses there with `graph_plan_change_unsupported`, and a
hostname change mixed with other edits refuses with `graph_hostname_change` and the
service name. Every refusal says to revert the edit, or to run
`hack down --remove-data` and then `hack up`. `hack restart` of a stopped graph
refuses and points to `hack up`.
For a shared-source graph that reconciliation does not select (live source, a
carried cache scope, a pending source-device rebind or initializer cache release)
and that was admitted with a retained compatibility contract, ordinary
source-content edits may change the reviewed plan ID: restart checks the stable
execution, exclusion, mount and dependency-cache inputs before cleanup and again
under the provider lease. The original installer publication and graph ownership
remain pinned. Changed configuration or cache inputs refuse before cleanup;
older receipts without that contract continue to refuse source-edited restart.
Source exclusions and runtime ownership checks remain in force. Existing commands
without normalization flags keep their file-based behavior.

New normalized shared-source graphs also capture a separate hostname-change
contract. A retaining restart can change only the literal hostnames of already
routed services: the service set, upstream ports, TLS settings, probes, commands,
environment declarations, images, mounts, networks and volumes must stay the same.
The one exception is the reserved
[runtime host metadata](/docs/v5/cli#runtime-host-metadata) keys (`HACK_BRANCH`,
`HACK_COMPOSE_PROJECT`, `HACK_DEV_*`, `HACK_ALIAS_*`, `HACK_SERVICE_*` and
`HACK_RUNTIME_METADATA`) that Hack generates into the normalized Compose: their
public values are derived from the hostnames, so the normalized fingerprint ignores
them. A value you declare for one of these keys in `.hack/docker-compose.yml` is an
ordinary literal, so changing it still refuses. A metadata change without a hostname
change also still refuses. This includes changing `HACK_NATIVE_HTTPS_PORT`, and also
selecting or removing the native HTTPS frontend when its port is not 443, because the
advertised URLs gain or lose that port. Start the retained graph with the HTTPS
frontend selection and port it was admitted with.
Both original and normalized Compose declarations are checked; only fingerprints
are retained. Changed dependency-cache inputs still refuse. The old ownership
plan and named data identities remain fixed, while normalized input provenance and
route intent advance together. Returning to the old names requires the same
checks. Existing hostname claims are checked before cleanup and again at publication.
Older receipts without this contract cannot be retrofitted from their redacted
plans and continue to refuse hostname changes.

`doctor --domain-migration apply` remains a file-only operation. It retains old
aliases and does not restart the graph or activate DNS/trust. Run an explicit
retaining restart after reviewing its changes, and separately verify the exact
browser origin. A successful file rollback likewise requires a retaining restart
to change running routes; it does not imply a live migration succeeded.

Graph execution respects the declared container root mode: `read_only: true`
keeps the root read-only, while false or omitted permits a writable container
layer. Removing the owned container discards that layer; use named volumes for
durable data. Source bind mounts still require read-only publication. Writable
container layers do not imply writable source synchronization.

A service `restart` policy (`always`, `unless-stopped`, `on-failure` or
`on-failure:N`) becomes the guest engine's own restart policy, so restart timing,
backoff, retry counting and the manual-stop rule follow Docker. `no` or omission
keeps automatic restarts off. A one-shot service with `service_completed_successfully`
readiness accepts only `on-failure[:N]`, which retries until it succeeds or its
retries run out; `always` and `unless-stopped` refuse there, as in Compose. While
the engine waits to start the next incarnation, `hack ps` reports the service as
`restarting`, and it satisfies no readiness goal. A policy-restarted container
keeps its container ID but gets a new start time, so Hack treats it as a new
incarnation: any proof bound to the previous one refuses rather than adopting it.

The port and route bridges that serve published `ports` and local HTTPS routes
are bound to one incarnation and cannot yet follow a restart (HACK-1935). A
routed service, or a service with published `ports`, therefore starts without its
restart policy: the container runs with the engine policy `no`, and native
review reports `restart_policy_not_applied` for it. Foreground `up` prints one
line per affected service before startup, for example `Service web: restart:
unless-stopped is not applied. Restart policies are not applied yet to services
with published ports or routes (HACK-1935); the service starts without automatic
restarts.` Other services in the same project keep their policy. For the same
reason the graph refuses a restart policy, with `graph_restart_policy`, on other
services with a native HTTP probe, services with host dependencies, services
that receive managed environment values (delivery is single-use and
time-bounded) and dependency-cache initializers. Remove the `restart` key from
those services, or keep them on the Compose backend.

Every owned stop first sets the engine policy back to `no` and confirms that with a
fresh inspection, then requests the stop. A restart that was already pending is
cancelled by the stop, and cleanup still requires an observation that is neither
running nor restarting before it deletes anything. A guest engine restart or VM
reboot while a graph is still owned restarts its `always` and `unless-stopped`
containers, as Docker does; owned cleanup or recovery stops and removes them.
`hack run` one-off containers never inherit the service restart policy.

An image that declares `VOLUME` (for example a database image) runs natively only
when the service mounts a named volume at each declared path, as in
`db-data:/var/lib/postgresql/data`. Hack never creates an anonymous volume: a declared
path without exactly one whole named volume of the project refuses with
`graph_image_volume_uncovered`, and a read-only (`:ro`) mount, a bind mount, a
`volume.subpath` mount or a dependency-cache volume at that path does not count. On first use the engine copies
the image directory's contents, owner and mode into the new, empty volume; later runs
mount the retained data unchanged. With Docker's default capabilities (see
[Container capabilities and the security model](#container-capabilities-and-the-security-model)),
an image entrypoint that starts as root and hands the data directory to another
user (`chown` and then a user switch) works. A service whose `cap_drop` removes a
capability that handoff needs (`CHOWN`, `DAC_OVERRIDE`, `FOWNER`, `SETUID` or
`SETGID`, or `ALL`) without adding it back fails there; set an explicit numeric
`user:` that matches the image's data user instead. `hack doctor` warns about that
case and about data services on mutable image tags. A native graph can own at most
16 named volumes, dependency caches included.

### Container capabilities and the security model

On the native backend, the development VM is the isolation boundary between
project code and your Mac. Containers inside the VM are a compatibility layer: they
give each service the process environment it would have under Docker, not a second
security sandbox. This matches how the Compose backend runs on Docker.

Compose-file services therefore get Docker's default Linux capability set for
the pinned engine (Docker 29.5.2): `CHOWN`, `DAC_OVERRIDE`, `FSETID`, `FOWNER`,
`MKNOD`, `NET_RAW`, `SETGID`, `SETUID`, `SETFCAP`, `SETPCAP`, `NET_BIND_SERVICE`,
`SYS_CHROOT`, `KILL` and `AUDIT_WRITE`. Stock images that start as root, change the
owner of their data directory and then switch to an unprivileged user (most
database images do this) work without a `user:` override. `no-new-privileges`
stays on, so a process cannot gain capabilities through setuid or file-capability
binaries. `privileged: true` is refused.

`cap_add` and `cap_drop` follow Docker's rules. Names are case-insensitive, and the
`CAP_` prefix is optional. `cap_drop` removes names from the default set, and
`cap_add` is applied after it, so a name in both lists is kept. `cap_drop: [ALL]`
keeps only the names in `cap_add`. `cap_drop` accepts any capability the engine
knows. Unknown names are refused, as Docker refuses them. Interpolated names are
not resolved and are refused as unknown.

`cap_add` accepts the default names plus a closed set whose effect stays inside
the container's own namespaces or cgroup limits: `NET_ADMIN` and `NET_BROADCAST`
(the container's own network namespace), `SYS_NICE` (scheduling and NUMA policy,
often declared for database images), `IPC_LOCK` (memory locking, still charged to
the memory limit) and `IPC_OWNER` (the container's own IPC namespace). Plan review
refuses every other addition with `capability_refused`, including `cap_add: [ALL]`.
One VM can host several projects and worktrees, and Hack runs its own helpers
inside service containers. These refused capabilities would act on that shared
kernel or on those helpers:

- `SYS_ADMIN`, `SYS_MODULE`, `SYS_RAWIO`, `DAC_READ_SEARCH` and `BPF` are known
  container escape or kernel attack primitives.
- `SYS_TIME`, `SYS_PACCT`, `SYSLOG`, `PERFMON`, `AUDIT_CONTROL`, `AUDIT_READ`,
  `MAC_ADMIN`, `MAC_OVERRIDE`, `WAKE_ALARM` and `BLOCK_SUSPEND` act on the VM as a
  whole: its clock, accounting, kernel log, performance events, audit or security
  modules, or power management.
- `SYS_PTRACE` would let an application trace Hack's in-container helpers (the
  dependency relay and the HTTP probe), bypassing the kernel's ptrace restrictions.
- `LINUX_IMMUTABLE` could make files in Hack-owned volumes impossible to remove
  during cleanup.
- `SYS_RESOURCE`, `SYS_BOOT`, `SYS_TTY_CONFIG`, `LEASE` and `CHECKPOINT_RESTORE`
  have no reviewed development use case yet.

Hack always writes the effective set explicitly (`CapDrop: ["ALL"]` plus `CapAdd`),
rather than relying on the engine's implicit default. Startup compares that exact
set against the inspected container. Authored native services, persistent-data
initializers and Hack's helper containers keep every capability dropped.

A stopped graph whose containers were created by an earlier candidate (with every
capability dropped) differs from this profile. `graph restart` on such a graph
refuses with `graph_config_mismatch`; it never adopts the old containers. Normal
`hack restart` and `hack up` recreate the containers around the retained volumes,
so they use the new profile.

The normal-CLI integration helpers prepare modern environment overlays and
worktree inheritance in memory, with null declarations in public normalized
configuration. An explicit AWS profile adapter can replace the recognized
read-only `${HOME}/.aws:/root/.aws:ro` mount with temporary, service-scoped
credentials. It preserves unrelated mounts and refuses custom credential-file
selectors. Credentials are not written to Compose or the project snapshot, and
are not automatically renewed after expiry. Normal native foreground `hack up`
uses these adapters within the capability limits described below.

### Compose fields with a native meaning

Native review accepts these Compose fields. Where the native result differs from
Compose, review reports a warning; nothing is dropped silently. A plan that does not
use a field keeps its earlier plan ID. A plan or receipt that does use one is refused
by an older bundle, so clean up such a graph with the bundle that started it.

- `depends_on.<service>.required: false`. When the selected profiles disable the
  target, the edge is skipped with the warning `optional_dependency_inactive`, as in
  Compose. When the target is active, native waits for its `condition` exactly as for
  a required dependency and fails startup if the condition is never met. Compose may
  only warn there, so review reports `optional_dependency_enforced`. A target that
  does not exist is still `missing_dependency`, and `restart: true` is still refused.
- `stdin_open: true` keeps the container's stdin open, so it never reaches EOF.
  No host input is attached, as with `hack up` on Compose. `tty: true` is accepted
  but no pseudo-terminal is allocated: stdout and stderr stay separate, and review
  reports `terminal_not_allocated`. Programs that need a real terminal (colors,
  prompts) stay on the Compose backend.
- A `caddy` hostname label with `caddy.tls: internal` and no `caddy.reverse_proxy`
  proxies nothing, so native treats it as inert: no route, hostname claim or relay is
  created, and review reports `inert_route_declaration`. The hostnames still appear
  in [runtime host metadata](/docs/v5/cli#runtime-host-metadata), as on Compose. Any
  other partial or extra `caddy*` label set is still refused. Inert hostnames are
  ordinary literals for a retaining hostname change, and
  `HACK_NATIVE_ADAPTATION` `additionalHostnames` refuses an inert service.
- Nested interpolation defaults such as `${A:-${B:-fallback}}` resolve inner
  expressions first, as Compose does, up to four levels and within the shared 1 MiB
  expanded budget. Only the `:-` and `:+` operators are supported at every level;
  `?`, unbraced `$NAME` and `$(...)` inside a default word are refused. A word that
  is not selected is still checked, but its inputs are not required.
- A reference to a Hack-managed value of the same service, for example
  `${TOKEN:-fallback}` when Hack delivers `TOKEN` to that service, refuses with
  `execution_environment_owner`. Managed values are delivered privately and are
  never interpolated into commands, users, health checks or other values, and a
  default is never used in their place. Declare the key bare (`TOKEN:` or `- TOKEN`)
  to receive the managed value.

## Registry image acquisition without Docker

The candidate can fetch a **digest-pinned image from any OCI distribution registry**
without Docker, OrbStack or a running guest: Docker Hub, GitHub Container Registry,
Google Artifact Registry and Container Registry, Quay, Amazon ECR, and private
registries on their own host names.

```sh
./hack-native --candidate-root /absolute/private/candidate-home runtime fetch-image \
  --reference '[registry/]repository@sha256:REVIEWED_MANIFEST_DIGEST' \
  --archive /absolute/private/new-image.tar
```

For an existing mutable image declaration, resolve it explicitly first:

```sh
./hack-native --candidate-root /absolute/private/candidate-home runtime resolve-image \
  --reference '[registry/]repository:tag' --json
```

Image references are normalized as the Docker CLI does before any request:
`alpine` is `docker.io/library/alpine:latest`, `alpine:3.21` is
`docker.io/library/alpine:3.21`, and `user/img` is `docker.io/user/img:latest`.
`index.docker.io` becomes `docker.io`. Tags, digests, registries, ports and
nested repository paths are kept as written; Docker Hub references must name a
`namespace/repository`. Repository names must be lowercase, and a normalized
name is limited to 255 bytes. Uppercase digests and malformed registry ports are
refused. Check a reference without network, credentials or candidate state:

```sh
./hack-native --candidate-root /absolute/private/candidate-home runtime admit-image \
  --reference 'alpine:3.21' --json
```

It returns the canonical `reference` and a `kind` of `docker_hub`, `registry` or
`image_id`; an unacquirable reference refuses with `registry_image`. Native
foreground `hack up` runs this admission for every authored service image before
startup hooks, the VM or any provider starts. Compose plan review applies the
same syntax rules, keeps the authored image text in the reviewed plan, and does
not change existing plan identities.

### Local registries

A registry on this host or its local network is refused unless it is named
exactly: `localhost` and `*.localhost`, loopback, private, link-local, CGNAT and
multicast IPv4 literals (including numeric spellings such as `0x7f.0.0.1`),
single-label hosts such as `registry:5000`, and mDNS `.local` names. The same
rule applies to the address a connection actually uses: a public-looking name
that resolves to any address that is not globally reachable unicast is refused
with `registry_local_address`. That includes loopback, private (including IPv6
`fc00::/7`), link-local, CGNAT, benchmarking (`198.18.0.0/15`), documentation,
multicast, reserved and other special-purpose blocks, local-use NAT64
(`64:ff9b:1::/48`), and IPv6 forms that embed such an IPv4 address. IP literals
follow the same rule. This covers the registry, its redirects
and its token endpoint. A private registry on an internal network therefore
also needs an explicit opt-in. Allow one
with `--allow-local-registry [http://]host[:port]` (repeatable) on `admit-image`,
`resolve-image`, `fetch-image` and `ensure-image`. Without `http://` the registry
must serve HTTPS; with it, plain HTTP is used for that registry only. Native
`hack up` reads a comma-separated list from `HACK_NATIVE_LOCAL_REGISTRIES`, for
example `HACK_NATIVE_LOCAL_REGISTRIES=http://localhost:5000`.

### Registry credentials

Requests start anonymous. When a registry answers `401`, the candidate first
requests an anonymous Bearer token, then uses the host user's existing Docker
credentials, in the Docker CLI's order: a `credHelpers` entry for the registry,
then `credsStore`, then an `auths` entry (`auth`, `username`/`password` or
`identitytoken`). Helpers run as `docker-credential-NAME get` from `PATH`; a
helper may show its own approval prompt, such as a keychain prompt, and is
stopped with its process group after 60 seconds. Processes a helper leaves
running cannot extend that wait. The configuration is `~/.docker/config.json`, or
`--docker-config DIR` (native `hack up` passes `DOCKER_CONFIG` when set).

Credential lookup is read-only: nothing is logged in, stored, erased or rewritten.
Credentials and tokens stay in memory for one acquisition, are sent only to the
registry's own origin or its token endpoint, never to a redirected blob host,
and never appear in output, receipts or errors. Only a `401` from the registry
origin itself is answered; a redirected blob host that refuses access fails with
`registry_redirect_refused` and no token or credential request. Docker Hub
tokens come only from `auth.docker.io`. For other registries, an anonymous token
may come from the registry origin or a public HTTPS host, but Docker credentials
are sent only to a token endpoint on the registry origin, or over HTTPS on port
443 at the registry's own host name or a parent domain of it (for example
`gitlab.com` for `registry.gitlab.com`). Any other token endpoint refuses with
`registry_realm_refused` before credentials are read. Run `docker login` (or
your registry's helper setup) yourself before acquiring a private image.

### Content, budgets and limits

Omitting the tag selects `latest`. Resolution returns `pinned_reference`,
`source_digest`, `manifest_digest`, `image_id` and `platform`; it downloads only
bounded metadata and verifies one unambiguous Linux ARM64 image configuration.
Pass the returned **pinned reference** to `fetch-image`, not the original tag.
Resolution creates no archive or runtime state and does not prove that all image
layers fit the budget or that the application starts. A missing tag or object
reports `registry_image_not_found`; no replacement image is selected.

The archive must not already exist. The result reports `source_digest`, the selected
Linux ARM64 `manifest_digest`, config `image_id`, `archive_sha256`, and archive size.
Pass that exact archive, hash and image ID to `runtime load-image` after preparing
the candidate guest. Fetching and importing remain separate operations.

The fetch accepts OCI and Docker v2 indexes and manifests. It verifies the pinned
index or manifest, the selected ARM64 manifest, the config and every layer against
its descriptor digest and size while streaming them to disk, then validates the
assembled archive again before publishing it. Layers may be gzip, zstd (including
multiple and skippable frames) or uncompressed tar, at most 128 per image; foreign,
non-distributable and external-URL layers refuse. The importer checks each decoded
layer against the config's `diff_ids`.

Sizes are bounded by an explicit, configurable budget instead of a fixed cap:

| Budget | Default | Range | Flag | `hack up` setting |
| --- | --- | --- | --- | --- |
| Compressed archive per image | 2 GiB | 16 MiB to 8 GiB | `--image-budget-mib N` | `HACK_NATIVE_IMAGE_BUDGET_MIB` |
| Decoded content per image | 5 times the archive budget | follows the archive budget | none | none |
| Image cache total | 16 GiB | 16 MiB to 256 GiB, at least one image budget | `--image-cache-mib N` | `HACK_NATIVE_IMAGE_CACHE_MIB` |

The manifest states every layer size, so an image larger than the archive budget
or the cache's remaining budget refuses before any layer transfer or disk write.
`load-image` applies the same flags. The whole acquisition has a 360-second
deadline; each layer request allows at least 1 MiB/s. Native `hack up` gives one
`ensure-image` request 10 minutes for acquisition and import, and a completed
archive is reused on the next attempt. Redirects stay on the registry origin,
Docker Hub's known blob hosts, or (for other registries) public HTTPS hosts on
port 443; local destinations and embedded credentials refuse. Proxy settings are
not used. TLS uses the bundled public root certificates, so a registry signed by
a private certificate authority is not reachable yet. Host names are classified
before connecting, and resolved addresses are checked again before each
connection (see [Local registries](#local-registries)).

No implicit image refresh occurs. Keep the archive only as long as needed for owned
imports; fetch does not install a background cache or cleanup daemon. The complete
archive is synced, validated and published without replacing an existing path.
A failed write or verification leaves no final archive; process interruption may
retain a hidden temporary file beside the requested output. A directory-sync failure
reports that a complete archive was published but durability could not be confirmed.

`runtime ensure-image --reference REF [--emulation native|prefer-native|amd64] --json`
resolves, caches and imports one image into the running pool; the image policy flags
described above follow `--json`. Without `--emulation`
(or with `native`) it admits Linux arm64 only. `prefer-native` selects arm64 when the
index publishes it and otherwise the exact `linux/amd64` image; `amd64` selects only
`linux/amd64`. The result's `platform` names the imported platform, which the image
configuration must confirm. An amd64 archive is cached under its own address, never
reused for arm64, and imports only into a pool booted with translation; see
[amd64 emulation with Rosetta 2](#amd64-emulation-with-rosetta-2).

### Explicit writable development source

An isolated development pool can opt into a direct host project mount with
`runtime up --profile development --project-share /absolute/project --unfiltered-source`.
`graph run` and `graph serve` select that mount with `--shared-source`.
This shares the entire approved project, including ignored local files, with guest
read/write access. Filtered source publication remains the default. Do not use the
unfiltered mode for a checkout whose local files must remain hidden from its services.
Only the exact canonical project root is accepted; home/credential directories,
aliased roots, and changes to a running pool's mount intent are refused.

One development pool can host several project roots and linked worktrees, so one
installed native home serves every project on the machine. The first root is the
pool's primary share. Native `up` in another root adds that root itself when the
pool is **stopped**, before any lifecycle hook runs, with the same unfiltered-source
consent the first root gave; the share is mounted at the next boot. The explicit
form is `runtime project-share add --project-share /absolute/other-project --unfiltered-source --json`.
A running pool's mounts never change: `up` in a root outside the set refuses before
hooks and says to stop the projects using the pool (`down` in each), stop the pool
(`runtime down --json` on the native home), and run `up` again. Remove an additional root (for
example a deleted worktree) from a stopped pool with
`runtime project-share remove --project-share /absolute/old-worktree --json`; removal
refuses with `project_share_in_use` while any retained graph still names that
share, and the primary share is never removed. A pool holds at most eight shares.
Boot refuses with `project_share_stale` while any share's root moved, changed or
was removed. Every update is journaled like the stopped network extension, and
startup refuses while the journal is unfinished.

Projects in one pool are separated the way Compose projects in one Docker VM are:
each graph binds only its own root's share (bind paths stay under that share),
graph namespaces derive from the canonical root and branch, cleanup acts on one
run's own labelled resources, and resource admission is one budget per pool. The
VM boundary between projects that separate pools gave no longer applies inside one
pool. Legacy device-rebind and host-pin recovery stay single-root and refuse on a
pool with additional shares.

Shared-source graphs with dependency caches still require a freshly published
source revision. Cache initializer services read that immutable publication through
read-only source mounts; their named cache volumes remain writable. This prevents
concurrent host edits from changing the inputs halfway through installation.
Other services use the direct host mount with their declared read/write mode.
Because virtiofs preserves host ownership, those services keep `DAC_OVERRIDE`
(part of the default capability set) even when `cap_drop` removes it. This allows
root processes to access the explicitly shared tree; it does not bypass a read-only
mount.
An installer that needs to modify source files is not supported in this mode yet.
Restart after dependency-input changes with a new review and publication.
Moving or deleting a project prevents further activation, but does not prevent
owned runtime teardown. Teardown never removes the shared host tree.

Service CPU and memory limits are optional. Services without an explicit Compose
limit share the admitted VM pool (Docker `NanoCpus: 0` and `Memory: 0`); the VM's
CPU and memory admission bounds remain unchanged. Explicit limits retain per-service
validation and aggregate reservation checks, and graphs remain limited to 32
services. This preserves ordinary Compose omission semantics; it makes no
performance guarantee or claim about fairness between workloads.

### Frontend integration status

Two native frontends exist. An authored `.hack/hack.project.json` project is owned
by `src/lib/native-authored-command.ts`, which admits only the bounded macOS slices
in the [authored command contract](/docs/v5/native/authored-commands):
foreground `up` and `restart`, owner-mediated `down` and `down --recover`, saved-run
`ps`, finite `logs --no-follow`, noninteractive `exec` and bounded one-off `run`.
One-off `run` refuses members with source, persistent-data or private-env mounts;
`restart` requires a proven stop before a fresh foreground start. The
rest of this section describes the older Compose-file native frontend for
`.hack/hack.config.json` projects with a Compose file, which keeps its own
command coverage below.

Authored native `up` and `restart` deliver the same
[runtime host metadata](/docs/v5/cli#runtime-host-metadata) as native image projects.
The configuration compiler carries it as public `runtime` bindings in the reviewed
source selection, below managed values and authored directives, and the runtime
adds it to each workload's public environment, never to private delivery. A
selected non-443 `HACK_NATIVE_HTTPS_PORT` appears in `HACK_DEV_URL` (authored
native graphs are not routed, so they have no alias or service URLs); a partial HTTPS selection refuses before any input or runtime
work. `exec` observes the values stored in the running container, and one-off
`run` uses the admitted environment.

Explicit `HACK_RUNTIME_BACKEND=native` with absolute `HACK_NATIVE_BINARY` and
`HACK_NATIVE_HOME` selects native observations for normal `hack ps` and bounded
`hack logs SERVICE --no-follow`. They verify the project/branch run mapping
against the current native graph. Logs do not support following or Loki options.
A project with no admitted mapping reports not started. `hack ps` keeps container
observations separate from the last graph receipt; an exited container's state
shows its exit code, as in Compose (`exited (1)`). For a ready foreground graph,
it also checks the live owner: `owner_unconfirmed` means the
owner could not be authenticated, while `runtime_degraded` means its runtime check
failed. A stopped candidate runtime is an ordinary state for `ps`: with a mapping
present it exits 0 and reports `runtime_not_running` (no phase, no service rows),
and text output prints "Native runtime is not running; no services are running."
A provider lease held for the whole bounded read, for example by a starting
foreground `up`, is also an ordinary state: `ps` exits 0 and reports
`runtime_busy` (no phase, no service rows). Reads retry brief lease contention.
`hack ps --json` prints the standard `{ok: true, data}` envelope; `data` holds
`backend: "native"`, `status` (`not_started`, `runtime_not_running`,
`runtime_busy`, `observed`, `owner_unconfirmed` or `runtime_degraded`), `run`,
`phase` and `items`. Bounded
logs refuse a stopped runtime with `E_DOCKER_UNAVAILABLE` and exit 1. Native `exec` and `run` refresh admitted host dependencies once before
command selection and managed environment preparation. They proceed only with
fresh ownership and runtime proof, even if containers still appear running.
Unconfirmed ownership or an incomplete refresh requires inspection and explicit
retaining recovery; command requests are never replayed.
Foreground whole-project `hack up` additionally requires
`HACK_NATIVE_SHARED_SOURCE=1` or `"sharedSource": true` in the
[machine settings](#native-settings-files): it exposes the exact
project tree, including ignored files, with each mount's declared write mode. Use
an explicitly prepared candidate home and the binary from a complete native bundle.
It acquires public images, privately supplies managed environment values, runs
lifecycle hooks, and publishes the run mapping after native readiness. Ctrl-C waits
for owned cleanup and keeps the stopped run mapping and named volumes after
confirming cleanup. The VM remains available until explicit runtime shutdown.
If startup fails after the graph started resources and the frontend cannot
confirm their cleanup, it publishes the authenticated failed run as the project's
run mapping before exiting, so `hack ps`, `hack down` and
`hack doctor --native-cleanup inspect` select that run instead of reporting the
project as not started; nothing is stopped or replayed to do so. When the
receipt itself cannot be authenticated, nothing is recorded and the runtime
journal keeps the graph for explicit recovery. When the graph owner exited
before reserving any runtime state (for example a configuration refusal during
execution compilation), inspection finds no journal for the run: startup then
reports the failure code and that nothing was created, instead of an
unconfirmed cleanup.

Managed values are declared on every authored service, so the reviewed plan is the
same for every profile selection, but they are delivered only to the services the
reviewed plan marks active. A service outside the selected profiles receives none.

A fresh start that fails or is interrupted before it publishes its run mapping,
and whose compute cleanup is confirmed, leaves no run that `ps`, `down` or a later `up` can select; the next fresh start
creates a new run with new volumes. After confirming compute cleanup, `up` therefore
removes that unpublished graph's volumes with `graph cleanup --remove-data` and
confirms the removed receipt; shared dependency caches are only released. It still
reports the original startup failure. A retained or restored run, and a run whose
mapping write was attempted (its reply may have been lost), keep their data. When
removal is not confirmed, `up` prints one line naming the run and the explicit
`graph cleanup --run-id RUN --remove-data --json` request, and keeps the graph.

Ctrl-C (or SIGTERM) on a ready graph whose `up.after` completed stops the project the
way `hack down` does on the Compose backend: `down.before` runs first, then graph
cleanup, then lifecycle-process retirement, then `down.after`. Hooks use the
environment selection of the running `up`. A second Ctrl-C cancels a running down
hook and proceeds to cleanup; a canceled `down.before` is not followed by
`down.after`. A failed `down.before` still stops the graph, because you asked to
exit, and the command reports `E_LIFECYCLE_FAILED`; a failed `down.after` reports
the same after cleanup was confirmed. Ctrl-C while `up.after` is still running stops
the graph without any down hook. With down hooks declared, the graph owner runs in
its own process group, so the terminal's interrupt reaches only the `hack` frontend,
which decides when the owner stops. Each down hook run by Ctrl-C also runs in its own
process group with stdin closed. Canceling it signals the whole group (SIGTERM, then
SIGKILL once the hook's shell exits or after a two-second grace), and output from a
canceled hook is drained for at most that grace, so a child such as `sleep` in
`sleep 600; echo finished` cannot keep the stop waiting. The frontend keeps handling
interrupts until `down.after` and its finalization acknowledgement are settled.

A private, value-free journal beside the run mapping records an intent before each
down hook starts and its known completion after the hook's process exits. It holds
only the run identity, a random writer identity and a phase, never commands, values
or output. A later `hack down` reads it: completed (or failed) phases are not rerun;
phases still owed, for example after the frontend was killed before or between the
hooks, run once; a phase that started but whose completion is unknown (the frontend
or `down` died while it ran) refuses with `E_LIFECYCLE_FAILED` "Native down hook
completion is unknown; inspect before retrying." and nothing is replayed. That
refusal also blocks the next `up` before any hook. After checking what the
interrupted hook did, remove `.hack/.internal/native-runs/*.down-hooks.json` to
clear it. A `hack down` from another terminal and the frontend's Ctrl-C claim the
same journal record, so concurrent stops run each hook at most once. If that `hack
down` is still running `down.before` when you press Ctrl-C, the frontend says so and
waits for the hook to finish before it stops the graph; it runs `down.before` itself
only if the other attempt failed and handed the record back. Press Ctrl-C again to
stop without waiting. A new `up`
supersedes any other leftover record; it does not run an earlier generation's owed
hooks. Projects without down hooks keep the previous stop behavior and write no
journal.

Without that grant, `up` and `restart` refuse with `E_PERMISSION` before any stop or
runtime request; set it and run the command again.

This initial foreground path does not support detached/JSON startup, selected
services, or the Compose features listed in
[Compose projects that stay on the Compose backend](#compose-projects-that-stay-on-the-compose-backend),
such as external networks. `--detach`, `--json`, `--target` and service names
each refuse with a one-line `E_USAGE` message that names the option and the supported
form: run `hack up` in the foreground in its own terminal and use `hack ps` and
`hack logs` from another. Routed services and host dependencies require the
explicit native selections described below. Unsupported Compose or environment input
(for example a service `env_file`, or a project `.env` without managed env) and
unreviewed route labels refuse with `E_NATIVE_PROJECT_UNSUPPORTED`. The input
refusal names its cause and, where known, the service and Compose field (for
example `service api field env_file`), never values or file contents. Secret
managed env without a project env key refuses with `E_CONFIG_INVALID` and names the
recovery actions; other unreadable managed env refuses with `E_CONFIG_INVALID`
without layer excerpts. Invalid branch
hosts, project adaptations, AWS selections and changed fresh-exec environments refuse
with `E_CONFIG_INVALID`, as do an unbounded `--profile` selection, a malformed
`HACK_NATIVE_DEPENDENCIES` listener selection and an occupied HTTPS port. A runtime
reply, saved mapping or retained graph that changed or cannot be confirmed (for example
a startup receipt for another run, or a mapping owned by another run) is an integrity
or ownership refusal, not a configuration one: it prints one closed line naming what
was not confirmed, and `--json` reports it as `E_UNEXPECTED`. Each prints one closed
line and drops nothing. Existing
`hack.dependencies.*` cache declarations publish the reviewed source snapshot and
require successful initializer completion before dependent services start. Cache
initializers receive immutable source mounts and writable named cache volumes;
workspace installs that write elsewhere still require explicit volume mappings.
An isolated trial of a real 14-service application reached native readiness, completed Google
sign-in, and rendered authenticated search results and images over browser-trusted
HTTPS. A normal `restart` kept its run and Redis data after a source edit. This does
not establish every application workflow, crash recovery or comparative performance.
Native `down` requests retaining cleanup from the graph owner and verifies container
absence while keeping the exact run mapping. It then retires that branch's owned host
lifecycle processes before running after hooks. A stopped graph (after a foreground
stop or a previous recovery) also retires remaining owned host processes without
replaying guest cleanup; it runs only down hooks the journal above still owes, once,
after the original frontend's finalization is acknowledged. Uncertain ownership
refuses retirement and leaves the retained mapping intact.
Before capturing live bridge helpers for cleanup, the owner retires an exited
helper only after confirming its current guest boot, run, container, network and
reservation. An interrupted retirement requires a fresh exit observation or an
exact stopped slot fence with the allocation and socket absent. A live, replaced
or unconfirmed helper remains a refusal; named volumes and sibling runs retain
their existing ownership protections.
Successful `down` also requires acknowledgement of the exact frontend attempt
captured before cleanup. Missing, changed or unacknowledged finalization refuses
success even when compute is already stopped; the run mapping and volumes remain
available for explicit recovery. Restart retains its own captured finalization
barrier so its selected dead-frontend recovery can run before replacement startup.
If the foreground owner concurrently retires its tmux session, cleanup accepts a
fresh explicit absence proof. Missing ownership metadata or an unsuccessful query
alone does not prove absence, and retirement preserves any replacement owner's state.
The next ordinary `up` verifies that
stopped receipt and restores the same run and volumes, including when its clean owned
VM has been stopped. It requires the retained frontend's exact finalization to be
acknowledged before hooks, storage preparation, VM startup or shared HTTPS admission.
This observation never recovers an interrupted frontend automatically, and the later
startup ownership check still refuses a concurrent replacement. Offline `graph retained-preflight` returns durable eligibility
only; it never fabricates volume observations or a restore generation. Startup checks
the saved environment, profiles and AWS selector before hooks and binds the exact
owner and receipt selection to `runtime up` with paired `--expect-retained-run` and
`--expect-retained-selection` flags. Native startup holds publication retirement and
revalidates the selection under the provider lease and immediately before boot. After
resume, live inspection must still prove absent compute and present owned volumes;
the existing restore selection pins the current boot and volume identities. Cancellation
or timeout has an uncertain outcome and never replays runtime up or graph restore.
It refuses an active, changed
or uncertain mapping rather than allocating a new data volume. When a Compose edit changes
the graph's images, volumes or other resources, the retained data cannot be adopted and
`up` says so. Either revert the edit, or discard the data explicitly with
`hack down --remove-data` (Compose parity: `docker compose down --volumes`). It works only
on a stopped project: run `hack down` first. It asks for confirmation (`--yes` skips the
question; `--json` requires `--yes`), runs no lifecycle hooks, and asks the graph owner to
delete only the volumes that this run created. Shared dependency caches are released, not
deleted. The request uses `graph cleanup --remove-data --retained-only`: the runtime
re-checks that the graph is still stopped while holding the lock a restore also needs, so if `hack up` in
another terminal restored the run in the meantime, removal refuses
(`graph_cleanup_not_retained`) instead of stopping it, and nothing is deleted. The run
mapping is retired only after every owned volume is confirmed absent, so
the next `up` starts a new run with new empty volumes. If removal is interrupted or
cannot be confirmed, the mapping is kept and running the same command again resumes from
the owner's durable cleanup intent. Ctrl-C (SIGINT) or SIGTERM ends the owned runtime
request and releases the operation lock before the command fails. If the process is
killed outright, the rerun reclaims the abandoned lock only after its recorded process has
exited; a live owner, or a lock held by restart or recovery, still refuses. Output names
no volumes or paths. Down hooks resolve
fresh managed host values using the environment selection saved by `up`; hook output goes to stderr with `--json`. A before-hook failure
prevents cleanup; an after-hook failure reports that graph cleanup already completed.
Environment/profile/target changes and cache pruning remain unsupported.

New mappings record the effective overlay name, or explicit `null` for base-only
configuration; no environment values are persisted. New readers accept legacy
mappings with missing selection, but refuse down hooks for those mappings rather
than guessing an overlay. Missing selected overlay files also refuse before cleanup.
Older binaries may reject extended mappings: this is backward state-reading
compatibility, not support for rolling back binaries over new state.
Whole-project foreground `restart` retains the recorded environment, AWS selector,
profiles, run identity and data volumes. It checks development runtime admission
(including disk headroom), reviews the normalized plan, and verifies each selected
host dependency listener before cleanup. For unchanged original Compose input,
active preflight reuses the admitted immutable image IDs, matching retained startup
even if a registry tag has moved. It authenticates the complete live graph through
native service selection and rechecks the same receipt generation, container and
boot after review. Completed initializer services remain eligible. Edited original
input uses ordinary image resolution and compatibility review; image reuse grants
no authority to bypass native source, resource or ownership checks.
Executable selections rediscover the
current listener; fixed-PID selections require a deliberate update when their
listener changes. Preflight remains immediate and does not adopt an unverified
process at the same port.
It saves a pending restart intent and waits for the previous frontend
to confirm graph, HTTPS and lifecycle cleanup before starting its replacement.
Changed selections and unknown legacy startup/finalization records refuse before
cleanup. A failed replacement retains its intent: retry `restart` after resolving
the reported problem; a fresh `up` cannot bypass it. When the saved intent confirms
cleanup, retry independently inspects the exact native run: its journal must be
complete, containers and networks absent, and retained volumes present. A matching
retained frontend mapping may remain; the mapping and intent alone do not prove
cleanup. Retry still reviews the public dependency intent and all source, plan,
environment, network and admission checks. It captures
listener identities after the startup hooks recreate them, rather than requiring
already stopped listeners before those hooks run. An interrupted operation lock
requires ownership inspection rather than automatic removal. Restart does not
implicitly migrate a shared pool's network policy or interrupt other projects.
When an interrupted frontend cannot write that final acknowledgement, an explicit
`restart --recover-frontend --expect-finalization-attempt <32-hex>` can resume
the saved, already-cleaned restart intent. It can also preflight an exact graph
that was stopped before the frontend saved an intent: fresh native observations
must prove absent containers/networks and present retained volumes, and repeat
that proof after review before cleanup. The normal intent, retaining down,
frontend recovery and startup sequence still runs. An active graph keeps its
authenticated service selection and live-listener checks; uncertain observations
cannot select the stopped path. Stopped preflight retains the admitted
image IDs when the original Compose input is unchanged, matching retained startup
instead of resolving mutable tags again. Changed original input keeps normal
image resolution and the existing compatibility checks. New attempts retain their frontend
PID and HTTPS port in the private token. Older v1 attempts additionally require
`--expect-frontend-pid <previously-observed-pid>`; a guessed PID is not recovery
evidence. Recovery requires the exact stopped graph receipt with its volumes
present and containers/networks absent, no managed HTTPS authority or owner
lock, a free recorded HTTPS port, and empty lifecycle state. Legacy recovery
also refuses while another packaged Hack frontend is running. The separate
recovery marker records that the old owner was proved gone; it does not claim
the old frontend ran its finalizers. A live or uncertain owner still refuses,
and no managed state file should be edited to bypass the refusal.
Before restore, the explicit recovery path also retires the exact dead graph
publisher only when its completed dead-owner cleanup receipt, current boot,
retained volumes, absent compute, and host relay cleanup still match. The
publisher's socket and owner record are moved under a durable inode-pinned
journal; interruption between those moves resumes against the same identities.
The backend operation is also available as
`graph retire-recovered-publisher --run-id RUN --expect-owner OWNER --json`.
An ordinary clean restart does not run this recovery operation.
The in-development native `run` path requires a running project started by a
matching candidate. It creates a separate service container with fresh managed
environment values and the admitted image, mounts, dependency cache and network.
It does not publish service ports or aliases. Commands are noninteractive and
bounded to 300 seconds; omitted arguments retain the service's default command.
The CLI returns command output and exit status only after owned job cleanup is
confirmed. There is no automatic command replay or fallback to Compose.
`run` uses the running project's environment and profiles. `--env` and `--profile`
are optional; when given they must equal the selection recorded at startup
(profiles compare as a set). A different selection, or a legacy mapping without
recorded selectors, refuses with `E_USAGE` before any runtime request. An empty
value (`--env ""`, `--profile ""`, or one that is only spaces or commas) also
refuses with `E_USAGE`: it does not mean "inherit" or an empty selection. Omit
the option to inherit. A profile list is empty only when every entry is, so
`--profile "web,"` asks for `web`. On the native backend the empty check runs
first, before the project is selected, so an authored `hack.project.json`
project refuses an empty value with the same `E_USAGE` line rather than its
`E_NATIVE_PROJECT_UNSUPPORTED` refusal of any `--env` or `--profile`. An
authored project on the Compose backend refuses an empty value with the same
line before any compiler work, so every native `run` agrees; a legacy Compose
project keeps its meaning, where an empty `--env` selects the base layers.
Native `exec` uses the running service environment. An empty `--env` or
`--profile` refuses with one closed `E_USAGE` line before the project is
selected, for authored and legacy projects alike. A non-empty value also
refuses: a legacy project with the same line, an authored project with its
`E_NATIVE_PROJECT_UNSUPPORTED` refusal, as for `run`.
`run` never restarts the project to change its selection.
Services with no managed environment values also support `run`; they keep the
admitted image's environment without creating a private environment mount or
launcher. The one-off request still carries an explicit empty, identity-bound
envelope. Its original deadline remains binding through container creation and
start even when there are no environment mounts; expiry refuses a new effect
without blocking owned cleanup. Missing or malformed delivery refuses, as do
values for another service; ordinary graph startup environment delivery retains
its nonempty requirement.

The running-project noninteractive path has a live smoke check against a real multi-service application:
`hack run www -- bun --version` completed after a same-run restart, and a command
exiting 7 returned its stdout and exit status. Both left no job resource and
preserved the healthy parent graph and its volume identities. An
interrupted one-off also completed explicit dead-owner cleanup with data retained.
Closing a live one-off client confirmed exact job removal while the parent remained
`ready-observed`, with the same volumes and healthy HTTPS route.
Stopped-project bootstrap, interactive input, and repeated crash recovery after a
restored one-off remain open. An uncertain shutdown retains its mapping and evidence
for recovery; do not delete managed state to retry.

After starting an owned native pool, `runtime ensure-image --reference REF --json`
resolves a registry tag (including Docker Hub shorthand such as `alpine:3.21`) or
accepts an explicit digest, reuses the verified
archive cache, and imports through the existing content-ID-checked loader. Tags
are resolved on each call; a warm explicit digest needs no registry request.
It accepts the [image policy flags](#registry-image-acquisition-without-docker).
The cache holds at most 64 archives within its configured budget (16 GiB by
default); an incomplete or conflicting entry requires inspection, and the command
never prunes existing data. Lowering a budget keeps existing entries readable, but
the loader refuses an archive larger than the current per-image budget. This command
is a startup building block, not evidence of complete normal `hack up` support.

Explicit Compose `shm_size` supports positive sizes up to 1 GiB, including
`shm_size: 1gb`; omission retains Docker's 64 MiB default. This tmpfs ceiling is
not preallocated memory and is not added again to graph memory reservations.
Actual shared-memory allocation remains constrained by an explicit container
memory cap, when present, and by the admitted VM pool. Restart review preserves
the exact shared-memory setting; zero, malformed and oversized values are refused.


For a project using the recognized read-only AWS home mount, explicit
`HACK_NATIVE_AWS_PROFILE` (and optional `HACK_NATIVE_AWS_REGION`) applies the
service-scoped AWS adapter after the normal login hook. It removes only recognized
AWS mounts/selectors and supplies temporary credentials through private stdin.
Expired or unsupported profiles fail startup; credentials are not persisted or
refreshed automatically. Unrecognized mounts and other unsupported bindings still
refuse admission. Because the exported credentials are a startup snapshot, the
foreground prints one value-free line to stderr ten minutes before they expire and
another at expiry: `AWS credentials delivered to N services expire at HH:MM; run
hack restart to renew.` `hack exec` keeps exporting fresh values for each request.

### gcloud Application Default Credentials (file mode)

For a project whose services bind the gcloud ADC file read-only, for example
`~/.config/gcloud/application_default_credentials.json:/config/adc.json:ro`,
explicit `HACK_NATIVE_GCLOUD_ADC=file` applies the gcloud adapter after the normal
login hook, beside the AWS adapter. Accepted sources are that path written with
`~`, `${HOME}`, `$HOME` or the absolute home directory, in short syntax with `:ro`
or long syntax `{type: bind, source, target, read_only: true}` with no other keys.
The target must be an absolute container file path outside `/proc`, `/sys`, `/dev`,
`/run` and `/var/run` that no other mount or tmpfs of the service equals, contains
or sits under. Writable or directory mounts, other gcloud paths and two matches in
one service refuse; so does selecting the adapter when no service matches.
`GOOGLE_APPLICATION_CREDENTIALS`, when declared, must equal the mount target and
stays public. `CLOUDSDK_CONFIG`, `CLOUDSDK_AUTH_ACCESS_TOKEN_FILE`,
`CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE`, `GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES`,
`GCE_METADATA_HOST` and `GCE_METADATA_IP` in a selected service refuse. Ambient
`GOOGLE_APPLICATION_CREDENTIALS` and `CLOUDSDK_CONFIG` on the host are not consulted.

The adapter reads only `<home>/.config/gcloud/application_default_credentials.json`:
a regular file (not a symlink) owned by you, not group- or world-writable, 1 to 16 KiB
of UTF-8 JSON, unchanged during the read. It admits `authorized_user` credentials and
`impersonated_service_account` credentials whose source is `authorized_user`.
`service_account` key files are refused, as are `external_account` types and any
`credential_source`, whose host files, URLs or executables do not exist in the guest.
It then runs `gcloud auth application-default print-access-token` once with prompts
disabled, a clean environment and a 30-second limit, and discards the token unread.
A missing `gcloud` refuses with a message naming the CLI; a failed mint or an ADC
file that changed during startup refuses. Other refusals use one closed line with
values omitted.

Each selected service then loses the bind mount from public Compose and receives
the same bytes as a private file member through the version 2 private envelope. The
runtime stages it mode 0400 for the container's numeric user in that container's
environment allocation and binds it read-only at the authored target. A service
with no other private values keeps its own entrypoint and health check; only a
numeric image or Compose user is required.

File mode places the ADC refresh token inside the VM for the container's lifetime.
That is no wider than the Compose bind mount it replaces: only the selected services
receive it, as a read-only snapshot owned by the container user, retired with the
container. Google client libraries refresh access tokens from it over normal
egress. Host re-login or revocation is not propagated; run `hack restart` to deliver
a fresh snapshot. The run mapping records only `gcloud: {"mode": "file"}`; restart
and retained restore keep that selection and deliver a fresh copy into new
allocations. `hack exec` delivers nothing new: the file is already in the
container, and exec only rechecks the mount and selectors. One-off `run` does not
apply the adapter. A mapping with a gcloud selection refuses on earlier candidates.

New immutable source captures use manifest schema 2: the revision binds both
selected content and its selection receipt. This prevents an ignored mountpoint
appearing after startup from colliding with an earlier publication containing the
same bytes under a different selection. Existing schema-1 manifests remain
verifiable; they are not rewritten or deleted. Cache keys still derive from their
declared dependency inputs and execution identity.

Source inventory and immutable captures exclude agent-local directories, including
`.codex`, `.claude`, `.cursor`, and `.agents`, at any depth. This also excludes
Cursor skill aliases into `.agents`; those aliases do not block project planning.
Application symlinks into excluded directories and explicit source mounts of those
directories are still refused. Adding the Cursor exclusion changes source-selection
identity for affected projects; existing reviewed receipts are not silently adopted.
These exclusions do not filter an explicitly authorized writable host project share.

Normal native foreground startup requests outbound public internet access by
default. Package downloads and external APIs do not require per-host configuration.
This does not publish inbound ports or grant host-service access; the provider's
private, loopback and metadata-address restrictions remain separate.

Set `HACK_NATIVE_ALLOW_HOSTS` only to opt into restricted outbound access: a
comma-separated list of at most 32 unique lowercase DNS names, such as
`registry.npmjs.org,example.com`. Wildcards, IP addresses, local names, whitespace,
trailing dots and empty entries are refused before lifecycle hooks. The provider
permits each selected domain and its subdomains, including TTL-learned public
addresses; this is not a URL, port or exact-host-only policy. Redirect destinations
also need approval in this optional mode.

Existing pools retain their network policy. To change an existing pool to the
normal internet mode, stop its owned runtime and run:

```sh
./bundle/hack-native --candidate-root /absolute/private/candidate-home runtime network internet --json
```

The transition preserves disks and caches and does not start the VM. Remove
`HACK_NATIVE_ALLOW_HOSTS` for subsequent normal foreground starts. Startup refuses
a policy mismatch instead of silently changing an existing pool.

To add an approved host to an existing pool, first stop the owned runtime, then
explicitly extend its policy:

```sh
./bundle/hack-native --candidate-root /absolute/private/candidate-home runtime network extend \
  --allow-host pkg-npm.githubusercontent.com --json
```

This preserves disks and caches and does not start the VM. It supports additive
changes to an existing approved-host policy, not switching an isolated pool to
networked mode or removing hosts. A recorded interrupted transition blocks startup until
the same command reconciles its exact before/after states. Incomplete staging or
foreign changes remain refused for inspection. Include the resulting
complete host list in `HACK_NATIVE_ALLOW_HOSTS` on subsequent foreground starts;
ordinary startup still refuses a different policy.

Normal native foreground startup recognizes the bounded `caddy`,
`caddy.reverse_proxy`, and `caddy.tls` label contract alongside dependency-cache
labels. It requests minimum bridge capacity for declared routed services before pool
startup and enrolls only active routes from native review. A fresh pool creates that
capacity; an existing pool with equal or greater capacity is reused unchanged.
Insufficient capacity refuses startup without resizing or replacing the pool.
The internal `runtime up --minimum-bridge-sockets N` command expresses this
requirement; `--bridge-sockets N` retains its exact-capacity contract. Neither
option promises free slots: graph admission still reserves those separately.
Host dependencies use the equivalent `--minimum-dependency-sockets N` selection;
`--dependency-sockets N` remains exact. Each direction can independently request
an exact capacity or a minimum. The combined physical transport limit still applies
to the pool's actual capacities, including any spare slots. A minimum does not resize
an existing pool or guarantee that enough slots are currently free.
Each routed service
must already declare a matching `healthcheck.x-hack-http` (see
[Native HTTP readiness probe](#native-http-readiness-probe)); command healthchecks
and missing probes are not replaced or inferred. Native review still validates
hostnames, ports, networks and labels. Foreground graph ownership supervises and
retires Unix route publishers. Without explicit HTTPS selection, this enrollment does not start a hostname authority
or Caddy HTTPS server. It never installs trust, configures DNS, or widens an existing pool.

The frontend requests `--route-slot SERVICE=auto` for each active route. The
native graph owner selects distinct free ingress slots across the whole pool
under its mutation lock and reserves the complete route set before starting its
route relays or publishers. Slots held by another graph, including slots awaiting
cleanup, remain unavailable. Insufficient capacity refuses the reservation without
publishing a partial route set. Internal callers can still select an exact slot
with `--route-slot SERVICE=N`; a busy slot is refused rather than reassigned.
Retained starts resolve automatic selections again against current ownership.
This allocation does not resize a pool or enable multi-worktree source sharing.
Shared HTTPS lifetime uses separate graph leases.

An empty shared HTTPS configuration left by failed startup is not a released
lease. The experimental source API `archiveEmptyNativeHttpsOwner` can archive
only the explicitly selected generation and configuration digest after proving
the original observed spawner exited, the selected endpoint/port/authority and
publications are absent, and the same pool incarnation remains running. It
preserves configuration bytes/inodes and Caddy data. Current startup and archival
share a short admission lock; uncertain intent publication retains its barriers
for inspection. Older binaries do not honor that lock and must remain quiescent
during this explicit recovery. Changed, active or ambiguous state refuses; this
is neither automatic recovery nor a public CLI command.

A nonempty shared HTTPS owner from the immediately preceding guest boot requires
a separate retaining recovery. The selected graph must already have an exact
current completed dead-owner cleanup proof, a retired publisher, retained volumes
and no compute, bridge, publication or hostname authority. Stop other uses of the
recorded frontend, runtime and Caddy executables first; legacy binaries do not
honor the new admission lock. Recovery refuses a live or uncertain process using
any of these executable paths, including Caddy serving another candidate home.

Explicit `restart --recover-frontend --expect-finalization-attempt ATTEMPT` can
select this transition for its exact v3 finalization lease. The internal native
operation binds every lease field:

```sh
./hack-native --candidate-root /absolute/private/candidate-home runtime archive-previous-boot-shared-https \
  --run-id RUN --expect-owner-generation GENERATION --expect-lease-id LEASE \
  --expect-attempt ATTEMPT --expect-owner OWNER --expect-namespace NAMESPACE \
  --expect-plan PLAN --json
```

The operation holds shared HTTPS admission, retired-publisher protection and the
provider cleanup lease while checking the immediate boot transition, original
executable hashes, owner/lease files, CA and exclusive port availability. It
archives original owner and lease files by same-filesystem rename and signals no
process. A present control socket and parent must match their selected identities
and be inactive; the socket is renamed within its unchanged parent. If both
socket and parent are absent,
that absence must remain true throughout archival, alongside the independent
process, port and graph proofs. A partial or replaced socket path refuses.

An interrupted archive retains its journal and admission barrier. Only the exact
selection with a verified dead recovery process can resume; do not remove lock
files or synthesize missing ownership records. Completion preserves Caddy data,
volumes and original lease evidence. Explicit frontend recovery consumes that
completion as a distinct recovery proof, never as an ordinary live-owner lease
release. Keep other shared HTTPS startup quiescent until frontend finalization
completes. A newer active owner blocks completed-archive replay; this recovery
does not adopt or stop it. Archival alone does not start the application or
establish browser access.

Normal foreground startup also selects `--auto-dependency-slots`. Each graph's
logical dependency groups receive distinct physical pool slots under the provider
lock. The complete assignment is recorded before listeners bind, so concurrent
starts and a crash before binding cannot claim the same capacity. Cleanup verifies
owned graph resources, closes its dependency listeners, and releases its reservation
before reporting success. A sibling graph's reservations and listeners remain owned
by that sibling. Low-level callers without this flag keep exact slot semantics and
must also respect existing reservations.

`graph dependency-reservations --json` inspects the durable claims. A dead owner
that never enrolled a graph can release a coherent claim with
`graph recover-dependency-reservation --run-id RUN --expect-reservation SHA256`.
Recovery verifies the owner is dead and any recorded socket still has its original
identity and no listener. Torn records and sockets without complete ownership
evidence remain unavailable; do not delete them to force allocation. Recovery of an
already enrolled graph requires verified graph cleanup instead.

`HACK_NATIVE_DEPENDENCIES`, or `dependencies` in the
[machine settings](#native-settings-files), selects a regular JSON file with
explicit host listeners; the variable takes an absolute path. The CLI reads it after lifecycle hooks, so a hook can
prepare current listeners before selection. For example:

```json
{
  "version": 1,
  "dependencies": [{
    "service": "web",
    "binding": "search",
    "guest_port": 443,
    "aliases": ["search.example.com"],
    "host_pid": 12345,
    "host_port": 8443
  }]
}
```

Replace the example PID with the actual listener process. Up to 128 service-specific
bindings and eight exact aliases per binding are supported, within 32 listening transports shared with the pool's route bridges.

When several services need the same binding, version 2 lets one entry list them
with `services` instead of repeating the entry for each `service`:

```json
{
  "version": 2,
  "dependencies": [{
    "services": ["web", "worker", "api"],
    "binding": "search",
    "guest_port": 443,
    "aliases": ["search.example.com"],
    "host_executable": "/usr/local/bin/tunnel",
    "host_port": 8443
  }]
}
```

Hack expands each such entry into one version 1 entry per listed service, in order,
with the same binding, ports and host authority, and then validates the result exactly
as version 1. Each listed service receives the binding's aliases that it declares as
`host-gateway` extra hosts (native review accepts no others), so when every listed
service declares every alias, both forms produce the same dependency plan. The limits
count expanded entries: at most 128 bindings in all. An entry sets at most one of
`service` and `services`; a version 2 entry that names neither applies to every service
that declares one of its aliases, as described with project-wide host aliases
below. A service listed twice, or a binding name used by more than one entry, refuses
as a duplicate. Version 1 files keep working unchanged.

For a listener started or rotated by a lifecycle hook, replace `host_pid` with
`"host_executable": "/absolute/path/to/the/listener-binary"`. Hack discovers
the current PID after the hooks and again before restart cleanup, requiring one
same-user process with that exact executable and an exclusive IPv4 loopback
listener on `host_port`. It passes the discovered PID to native review without
rewriting the private selection file. The native dependency plan pins the
process and socket generation again before admitting the graph. A missing,
ambiguous, wrong-executable or substituted listener refuses; an already running
graph stays up when restart preflight refuses. Fixed `host_pid` selections remain
supported and carry no permission to follow a replacement process.

Executable selections may also set `"host_supervisor_depth": 2` when a retained
wrapper launches a replaceable session process which launches the listener.
The depth is an integer from 1 through 8 and defaults to 1 (the immediate parent);
it is forbidden with a fixed-PID-only selector. Hack captures exactly that
many ancestry links, pins the final ancestor's PID, native start time, user and
executable, and retains the intermediate executable paths in order. A retry may
replace intermediate processes only beneath that exact live ancestor, with the
same executable chain and user. Native review rechecks the complete bounded
lineage twice; it never searches for a common ancestor or infers a stable wrapper.
Bindings sharing one listening transport must select the same executable, depth
and reviewed ownership policy. A replaced ancestor, changed chain, adopted
listener or inconsistent shared selection refuses before relay grants change.

A listener that Hack itself starts can instead be selected by its owner, with no
PID, path or depth in the file. Replace the authority fields with exactly one of:

- `"host_lifecycle": "NAME"`: a persistent `up.before` hook (its `name`, or
  `hook-N` when unnamed) or a `lifecycle.processes` entry of this instance. Hack
  reads the pane PID from its lifecycle state and requires the live tmux session
  to carry the recorded ownership token and that pane to be alive. zellij
  sessions record no pane PID and refuse.
- `"host_shared_helper": "NAME"`: an enabled `lifecycle.sharedHelpers` entry
  whose claim is `owned` and `ready`, lists this instance as a holder, and whose
  PID and birth time are live. An adopted helper refuses.

After the hooks, Hack asks native discovery for the one same-user exclusive IPv4
loopback listener on `host_port` and requires it to be the owner process or its
descendant within eight ancestry links; it then proves the owner again. A
listener outside the owner's tree refuses with "Native host dependency listener
does not run under its selected owner"; this includes a listener the hook only
adopted, or one that detached (for example with `ssh -f`), even if it was started
by the hook. Use a `host_executable` selection for those. A listener deeper than
the owner is reviewed as an executable selection at the discovered depth whose
final ancestor must be exactly that owner process (PID and native start time), so
a refresh follows replacements only beneath it. An owner that is itself the
listener is a fixed-PID selection without replacement authority. Bindings sharing
a host port must name the same owner. The owner names never reach native review,
and the frontend never persists the resolved PIDs. Restart preflight resolves the
same owners against the running instance; a cleaned retry validates the intent
only and resolves owners after its hooks.

Startup allows up to 60 seconds total for persistent hooks to create all selected
listeners, with cancellable waits and bounded read-only discovery requests. It
retries only native endpoint-identity refusals; malformed selections and other
failures stop immediately. A refusal is one `E_CONFIG_INVALID` line that names the
reason and the affected entry by position, service, binding, aliases, guest port and
host port, each shown only after it validates. For example, a listener that never
appears on the selected port reports `no listener owned by host_executable answered
on host_port before the discovery deadline`. Host PIDs, executable paths and the
contents of unrecognized fields are never printed. A listener must pass the complete ownership checks
before any VM or graph effects. Restart preflight does not wait or stop the graph
when its current selection cannot be verified.

For an already ready foreground graph, `graph refresh-dependencies --run-id RUN
--json` asks its authenticated live owner to refresh stale admitted listeners.
With a packaged candidate, invoke it as:

```sh
./hack-native --candidate-root /absolute/private/candidate-home graph refresh-dependencies --run-id RUN_ID --json
```

Only `host_executable` selections (including owner-scoped selections deeper than
their owner) can follow a replacement, using the original
executable, host port and unchanged same-user ancestor selected by
`host_supervisor_depth`, retaining the reviewed intermediate executable chain. A matching
executable or port alone is insufficient. Missing or ambiguous listeners,
replaced supervisors, fixed-PID drift and changed ownership refuse. The owner
retains the admitted services, bindings, aliases, guest ports and transport slots;
the request cannot add or edit them. Successful refresh changes affected relay
generations without restarting application containers or replacing volumes.
An unchanged graph returns a verified no-op.

A service declared `completed` that has successfully exited can share those
dependencies with running services. Refresh checks its exact container, image and
original start time, and requires exited state, PID zero, exit code zero and no
dead or OOM state. It journals retirement before revoking every historical binding
and proving the old helpers absent. Its receipt then records `relay_startup` phase
`completed` with no helper process records; it receives no replacement grant or
helper. Running siblings still refresh together. Started/healthy services that
exit, and failed completed jobs, refuse this path. One-off commands retain the
admitted template and create fresh job intent; this state never permits exec in
the stopped container.

When a physical dependency slot is used only by completed jobs, refresh can select
a replacement for later one-off commands under the same executable and ancestry
policy. A separate empty fence requires every old target to be retired, preserves
the exact graph and old generation, and commits the new endpoint before future job
admission. It issues no grant or helper for the completed containers. A later
one-off uses fresh job intent and credentials; old credentials remain revoked.
An interrupted empty fence refuses further admission until ordinary owned cleanup
and restart, and is never retried or replayed automatically.

The rebind journal's optional `completed_services` and per-slot `terminal_only`
fields record terminal retirement and empty fences explicitly. Older journals
without these fields remain readable, but a previous bundle cannot be assumed to
understand the new completed startup phase.
Use the current owning bundle for retaining cleanup and journal archival before
selecting an older bundle; do not substitute an older binary against active state.

If a required startup listener exits with a service declared `started` or
`healthy`, the stopped receipt preserves the owned service name, container ID and
exit observation before cleanup, including exit code zero. A successful
`completed` service is not recorded as a startup failure. This evidence contains
no command, environment or application log values. Older bundles may refuse the
new zero-exit evidence; use the owning bundle for diagnosis and retaining cleanup.

A host-dependency listener's transport usually ends before the engine records the
container's own exit, for example when a quick initializer finishes. Startup then
re-inspects the container for up to 10 seconds before it classifies the exit, so a
`completed` service that exits 0 is accepted and a crashing service reports its own
exit. Only a container that still runs after that window reports
`graph_startup_running_listener_lost`.

Startup cleanup removes a failed service's container and its logs. Before that
cleanup, the foreground owner reads a bounded tail of each failed service: the
recorded startup failure first, then other failed services by name, at most three.
Each tail holds Docker's last 64 lines of the service, with at most 4 KiB of
whole lines per stream (stdout and stderr), so at most 8 KiB per service. A line
is never cut; a single line over the bound is omitted and the report says lines
were omitted. The tail travels only in the foreground failure reply. The runtime
never writes it to the receipt, journal or any other file, so persisted failure
evidence stays value-free.

The frontend still holds the managed environment values it delivered. It redacts
all of them, for every service, from the tail before printing it under the
startup failure report, and it never saves the tail or the report:

- Terminal escape sequences are removed first.
- A value of four or more characters is replaced as `[REDACTED]` wherever it
  occurs, even inside a longer word. Its JSON-escaped form and each line of a
  multi-line value that is four or more characters long, with and without
  surrounding whitespace, are replaced too.
- A value of one to three characters is replaced only as a whole token: not next
  to a letter, digit or underscore. Values like `1` or `on` therefore do not
  shred unrelated output.
- Other control characters except tab and newline are shown as U+FFFD.

Private credential files, such as gcloud Application Default Credentials, are
redacted the same way: the whole file text, each of its lines, and every JSON string
value of four or more characters, such as a refresh token or private key. When a
service received a credential file that is not UTF-8 text, or looks like JSON but
does not parse, its output is withheld from the report instead; read it with
`hack logs SERVICE`.

Redaction covers only managed values and credential files. Application output can
still hold other sensitive data, such as values a service read from its own files.

A Docker container can remain `created` with a nonzero error when its first start
fails before a process runs. Retaining shutdown accepts this state only with
verified ownership, no running PID, no pause/restart/dead state and no OOM flag.
The original exit code remains failure evidence; it does not become a successful
application exit or a claim that Hack sent a stop request.

If that failure interrupted enrolled cleanup, the candidate frontend can inspect
and select a separate retaining recovery after the exact native foreground has
exited. The private controls are `graph inspect-interrupted-start-cleanup
--run-id RUN --json` and `graph recover-interrupted-start-cleanup --run-id RUN
--expect-selection SHA256 --retain-data --json`. They require the same guest
boot, exact dead foreground, matching pending coordinator operation, and unchanged
selected resources and retained volumes. The relay publication must either match
its original pinned owner or have both owner and socket absent after foreground
exit. The absent pair is bound to the existing operation lock, unchanged parent
identity and exact selected coordinator owner, process, publication and attempt;
a mixed pair, live process or replaced lock refuses recovery. This is not a
general retry of a coordinator effect. Its own journal records each cleanup step.
Shared dependency caches stay retained, with their original cache bindings and
volume provenance rechecked at effect and completion boundaries.
An uncertain stop is never sent again merely because the container still appears
running. A crash between stop intent and request can therefore require later
terminal evidence before recovery can advance.
Likewise, a pending guest helper, probe or environment deletion advances only
after complete absence is independently verified. An interruption partway through
a guest cleanup script can remain fenced; this control does not replay that
script or guarantee automatic recovery from every internal deletion boundary.

Successful recovery requires independent compute, helper, probe and environment
absence, then current cleanup acknowledgement, exact publisher retirement and
dependency reservation release. The frontend rechecks retained data and completes
its existing finalization contract. It still reports the original startup failure.
If retirement is interrupted after acknowledgement, a bounded native journal hint
prompts fresh inspection of the exact original selection before finishing only
the remaining publisher and reservation transitions. The hint grants no effect
authority, and a stopped graph alone does not establish complete retirement.
Completed recovery journals remain as evidence. A later interrupted startup on
the same retained run cannot reuse that earlier generation's selection: native
recovery reports `graph_interrupted_start_cleanup_stale`. Archiving a completed
journal at the verified restore boundary is a separate follow-up; never remove
the journal manually to enable another recovery.
A component acknowledgement is not application readiness, and this recovery does
not diagnose or fix an upstream engine panic. Changed or incomplete evidence
remains available for inspection; do not remove journals or ownership pins to retry.

Native `hack exec` and `hack run` make this request once with a 180-second frontend
budget before selecting their command or reading managed environment values.
If refresh refuses, the frontend preserves only reviewed native error identifiers
such as `provider_busy` or `graph_owner_recovery: graph_dependency_rebind_incomplete`.
Subprocess text and unknown codes remain omitted. These diagnostics do not confirm
whether refresh effects occurred or authorize replay; the command is not dispatched.
`ps` and `logs` remain observations and do not request refresh. Authenticated relay
traffic reports a stale endpoint to the foreground owner, which attempts bounded
refresh without idle polling. The owner also watches each admitted replaceable
listener process for exit (a kernel exit notice, not a scan), so a replaced
listener is refreshed before the next request reaches it. Attempts run one at a
time. When no replacement is listening yet, the refusal happens before any
effect, and the owner retries after 1, 2, 4, 8, 15 and 30 seconds; after that only
a new stale notice re-arms it. Once a rebind has written its journal and not
completed, the owner never retries automatically. The affected application
request can fail; it is never replayed, and later traffic can use a verified
replacement. The explicit
operation is also available before traffic. Refresh does not renew startup
environment allocations. A lost reply or interrupted transition is never replayed.
Partial transitions remain fenced and refuse new admission; inspect owned state and
complete retaining cleanup/restart to rebuild the relays. Ordinary recovery keeps
the run's persistent volumes. Do not delete managed journals or mappings to retry.

Bindings in different services targeting the same pinned host listener can share
a transport slot; authentication, cancellation and expiry remain per binding.
The CLI groups selections by host PID and port in first-appearance order, and
native review requires the complete captured endpoint identities to match.
Multiple bindings within one service retain distinct slots.
Aliases must match the service's declared `extra_hosts` entries targeting
`host-gateway`. No general host-gateway access is enabled. Native dependency review
pins the same-user process and exclusive loopback listener generation, then checks
that identity again during admission. A stale PID, replaced listener, undeclared
alias, extra field, symlink or malformed file refuses admission. This file contains
selection metadata only, never credentials. It does not adopt or stop the selected
host process; lifecycle hooks retain ownership of listeners they launch.
Restart preflight checks those selected listeners before stopping the graph.
Startup admission repeats the check after lifecycle hooks, so a listener that
changes between preflight and startup still refuses without adopting it; the
stopped run and its volumes remain available for a corrected retry.
Selected services receive `init: true` when omitted because the guest relay launcher
requires a reaping init process. An explicit `init: false` is refused, not replaced.

Project-wide host aliases from `internal.extra_hosts` in `hack.config.json`, plus
checkout-local `hack internal extra-hosts` entries, follow the Compose backend:
native `up` and `restart` declare each one on every service as a `host-gateway`
extra host. Native has no general host gateway, so every profile-active service
must then have a selected binding for each alias it declares. A missing binding
refuses with `E_NATIVE_PROJECT_UNSUPPORTED` ("Native host alias has no reviewed
host dependency binding; configuration was not dropped."), before any runtime
work; with no dependency selection at all it refuses before lifecycle hooks.
The refusal lists every unbound alias with the services that declare it and
where it comes from: the service's Compose `extra_hosts`, `internal.extra_hosts`
in project configuration, this checkout's `.hack/.internal/extra-hosts.json`, or
the main checkout's map that a linked worktree inherits. It then names the
`aliases` a binding needs and how to remove the alias instead
(`hack internal extra-hosts unset <alias>` hides an inherited entry in this
worktree). Listener values are never printed.
An entry whose target is not `host-gateway` (for example a fixed address), a name
that is not an exact lowercase DNS name, or a service that already maps the name
to a different target also refuses. Service-declared names are matched in the
form native execution compiles them to: Compose interpolation resolved as the
native runtime resolves it (no ambient environment, so `${UNSET:-word}` selects
`word` and `${UNSET:+word}` selects nothing), then one trailing dot removed and
lowercased. So a service that declares `API.Example.` or
`${UNSET_PREFIX:+x-}api.example` is covered by a binding for `api.example` and
does not receive a second copy of a project-wide `api.example`. A service whose
declarations compile to the same alias twice refuses with `E_CONFIG_INVALID`,
naming the service and alias, before any runtime work; native execution would
refuse it only after the VM started. A name that refers to a required variable,
a Hack-managed value or `COMPOSE_PROJECT_NAME` is left to native review and
execution. Earlier native builds ignored these entries,
which let a container resolve the public name instead of the local listener.
Native reads these aliases before lifecycle hooks, because they are part of the
reviewed configuration; unlike the Compose backend, a hook that changes them makes
`up` refuse after hook cleanup. The check after hooks reads `hack.config.json` and
the checkout-local alias map again, so an edit to either is caught. A local alias map
that exists but cannot be read refuses with `E_CONFIG_INVALID` instead of being
treated as empty. Projects without project-wide aliases are unchanged.
Unlike a Compose host gateway, which reaches every host port, a service reaches
each alias only on the one guest port its binding selects.

To avoid repeating one listener for every service, a version 2 selection names
each binding once:

```json
{
  "version": 2,
  "dependencies": [{
    "binding": "search",
    "aliases": ["search.example.com"],
    "guest_port": 443,
    "host_port": 8443,
    "host_executable": "/absolute/path/to/the/listener-binary"
  }]
}
```

Without `services`, the entry applies to every profile-active service that
declares one of its aliases, and each service receives only the aliases it
declares. `"services": ["web", "worker"]` limits it to those services, in that
order, each of which must declare at least one of the aliases; `"service": "web"`
is shorthand for a one-element list, and an entry sets at most one of the two.
The CLI expands the entry into the version 1 bindings shown above before
discovery and review. The same listener authority applies to every expanded
binding, and the 128-binding and 32-transport limits apply after expansion. A
repeated binding name, an alias no selected service declares, both `service` and
`services`, or an unknown or inactive service refuses.

Fresh pools reserve the number of distinct dependency transports from that
selection. Existing pool capacity cannot be silently widened. The selection is copied into the temporary exact-plan
dependency request and removed when foreground startup exits. No durable listener
authority is inferred from a saved selection file. Image-only services omit graph
shared-source mode; active project bind mounts still use the explicit project share.

#### Native HTTP readiness probe

`healthcheck.x-hack-http` declares the readiness probe native startup uses for a
service. It must be the only key in that service's `healthcheck`: it cannot be
combined with `test`, `disable`, `interval`, `timeout`, `start_period`,
`start_interval` or `retries`. Docker Compose ignores the extension field. All six
fields are required, and no other field is accepted:

| Field | Type and range | Meaning |
| --- | --- | --- |
| `port` | integer, 1–65535 | Container port the probe connects to on the container's loopback address (`127.0.0.1`). For a routed service it must equal the port in `caddy.reverse_proxy: "{{upstreams PORT}}"`. |
| `path` | string, starts with `/`, at most 512 bytes | Request path. Only printable ASCII without spaces is accepted; `#` is refused. The probe sends `GET <path>` with `Host: 127.0.0.1:<port>`. |
| `interval_ms` | integer, 10–3600000 | Time from the start of one request to the start of the next. |
| `timeout_ms` | integer, 1–60000 | Limit for connecting, sending the request and reading the response headers. |
| `retries` | integer, 1–100 | Consecutive failed samples that make the service unhealthy. |
| `start_period_ms` | integer, 0–3600000 | Startup grace. Failures in this period do not count until the first success. |

A sample succeeds only when the response status line is `HTTP/1.1` or `HTTP/1.0`
with a `2xx` status. A redirect (`3xx`) or any other status is a failure, so point
`path` at an endpoint that answers `2xx` without a redirect. A service is starting
until its first success, healthy after a success, and unhealthy after `retries`
consecutive counted failures. Failures count once the service has succeeded once or
the start period has ended; one success resets the count. A sample older than
`interval_ms + timeout_ms + 1000` milliseconds counts as unhealthy.

```yaml
services:
  web:
    labels:
      caddy: web.hack.local
      caddy.reverse_proxy: "{{upstreams 3000}}"
      caddy.tls: internal
    healthcheck:
      x-hack-http:
        port: 3000
        path: /health
        interval_ms: 1000
        timeout_ms: 2000
        retries: 60
        start_period_ms: 120000
```

`hack init` writes this probe with path `/` and the values above for each routed
service when the native backend is selected. The `httpProbes` adaptation below
accepts only `port` and `path` and fills the other four fields with the same values.

For projects whose checked-in Compose file needs explicit native health probes,
an adaptation file adds them. Commit it as `.hack/native/adaptation.json` (see
[Native settings files](#native-settings-files)), or select any absolute JSON file
with `HACK_NATIVE_ADAPTATION`. This leaves the Compose file unchanged and preserves
its identity in native review. Only the following bounded adaptations are accepted:

```json
{
  "version": 1,
  "isolatedNetworks": ["hack-dev"],
  "httpProbes": {"web": {"port": 3000, "path": "/health"}},
  "additionalHostnames": {"web": ["web.hack.local"]},
  "additionalHostAliases": {"web": ["host.docker.internal"]},
  "workspaceCache": {
    "volume": "node_modules",
    "root": "/app",
    "workspaces": ["apps/web", "packages/db"]
  },
  "amd64Emulation": {
    "default": "prefer-native",
    "services": {"legacy-worker": "amd64", "db": "native"}
  }
}
```

Networks must already be declared external; selection explicitly replaces their
connectivity with the owned isolated network. Native `up`, `restart` and doctor
then treat those networks as owned, not as external Compose networks (see
[Compose projects that stay on the Compose backend](#compose-projects-that-stay-on-the-compose-backend)). Probes apply only when no existing
healthcheck is present. Additional hostnames append to existing Caddy labels.
Additional host aliases append explicit `host-gateway` declarations and still need
separate pinned dependency selections; they do not enable general host access or
override fixed-address aliases. Conflicts are refused. Choose actual application
health endpoints; a probe is an application readiness contract, not a workaround
for failed startup.

The optional workspace cache layout mounts subdirectories of the existing declared
dependency volume at each workspace's `node_modules`. This allows an installer to
populate nested workspace dependencies while its project source remains read-only.
Every service already consuming the root dependency volume receives the same layout,
including the root mount's read-only setting. Unrelated services are unchanged.
The layout participates in native dependency-cache identity. This shares compatible
workspace installations; it does not implement a cross-project package store or
claim deduplication across different lockfiles.

### amd64 emulation with Rosetta 2

The native VM is Linux arm64. On an Apple silicon Mac with Rosetta 2 installed
(`softwareupdate --install-rosetta`), `amd64Emulation` lets selected services run
`linux/amd64` images under Rosetta 2 x86_64 translation inside the VM. It is off unless
the selection opts a service in, and each service takes one mode:

| Mode | Image platform |
| --- | --- |
| `native` (default) | Linux arm64 only. A declared `platform: linux/amd64` keeps the project on the Compose backend. |
| `prefer-native` | The arm64 variant when the image publishes one, so multi-arch images stay native even when the service declares `linux/amd64`. An image that publishes only `linux/amd64` runs under emulation. |
| `amd64` | The `linux/amd64` variant under emulation, even when the image also publishes arm64. Use it when the workload needs x86_64 binaries, for example prebuilt native modules. |

`default` sets the mode for every service without its own entry in `services`; omit it
to keep `native`. A named service must exist, a service that declares a Linux arm64
`platform` cannot opt in, and an unknown mode refuses with `E_CONFIG_INVALID`. Only the
exact `linux/amd64` platform is emulated; microarchitecture variants such as `v3` and
other platforms are never selected.

When any service opts in, native `up` requests a pool with translation
(`runtime up --amd64-emulation`). A fresh pool is created with SmolVM's `--rosetta`;
a stopped pool is updated with `machine update --rosetta` before it starts; a running
pool without translation refuses with `amd64_emulation_restart_required` and nothing is
stopped. Stop every native project that uses the pool, then start again. A pool keeps
translation once it has it, so other projects sharing it are unaffected: their services
still resolve arm64 images. Without Rosetta 2 the start refuses with
`amd64_emulation_unavailable` before any VM effect.

Every boot audits translation against the pool's recorded intent: the provider's
stored machine setting, its running configuration, and the guest's `binfmt_misc`
`rosetta` registration (the x86_64 ELF match with the fixed `rosetta-wrapper`
interpreter). A pool without translation must have no such registration. The image
cache keeps amd64 archives separate from arm64 ones. Under `prefer-native`, a cached
amd64 archive is reused only after the pinned image is confirmed not to publish arm64.
The runtime admits an amd64 image only for an opted-in service
(`x-hack-amd64-emulation: prefer-native` or `amd64` in the reviewed Compose service,
which the adaptation writes) in a pool booted with translation. A service that is not
opted in still refuses a declared `linux/amd64` in native review.

The mode is part of the reviewed plan. Restart and restored `up` reuse a service's
retained image only when the retained graph recorded the same mode for it; after a mode
change the service's image is selected again under the new mode.

Emulated services are slower than native ones and can behave differently from arm64
builds. `hack doctor` on the native backend reports an `amd64 emulation` warning with
the number of opted-in services in each mode (counts only, no service names), and
names the Rosetta 2 install command when it is missing.

### Native settings files

Every native selection above can also come from a file, so a project runs with plain
`hack up` instead of a set of exported variables. There are two kinds of file, because
they carry different authority:

| File | Holds | Where | Commit it? |
| --- | --- | --- | --- |
| Project adaptation | The adaptation above (`isolatedNetworks`, `httpProbes`, `additionalHostnames`, `additionalHostAliases`, `workspaceCache`, `amd64Emulation`) | `.hack/native/adaptation.json`, and optionally `.hack/native/adaptation.<env>.json` | Yes. Every checkout and worktree shares it. |
| Machine settings | Grants and host authority: the project share, the AWS profile, host dependency files, HTTPS, prepared base and approved hosts | `${XDG_CONFIG_HOME:-$HOME/.config}/hack/native/<project>/settings.json` | Never. It is per machine. |

The project adaptation has the same authority as the Compose file it adapts. It grants
nothing: its schema is the closed adaptation schema above, so a grant such as
`sharedSource` in it refuses with `E_CONFIG_INVALID`. Hack reads only
`adaptation.json` and `adaptation.<env>.json` from `.hack/native/`, where `<env>` is
a lowercase env name. `hack doctor` warns about any other file there.

The machine settings file lives outside the project because the project tree is
shared read/write with the native VM: a container could rewrite a grant stored in the
tree before the next `up`. `<project>` is the project name Hack uses (the Compose
`name:`, else `name` in `hack.config.json`, else the directory name), lowercased with
other characters replaced by `-`. Linked worktrees and branch instances of one project
therefore find the same machine file.

Any checkout can claim a project name, so the file grants only the checkouts it lists
in `projectRoots`: absolute paths of project roots (at most 16). Hack compares the
canonical path of the current project root with the canonical path of each entry, so a
symbolic link to a listed root works. An entry that no longer exists is skipped. Branch
instances share their checkout's root; list each linked worktree you want to grant.
Create the file once per machine:

```sh
dir="${XDG_CONFIG_HOME:-$HOME/.config}/hack/native/my-app"
mkdir -p -m 700 "$dir"
chmod 700 "$dir"
touch "$dir/settings.json" && chmod 600 "$dir/settings.json"
```

```json
{
  "version": 1,
  "projectRoots": ["/absolute/path/to/my-app"],
  "sharedSource": true,
  "aws": {"profile": "dev-sso", "region": "us-east-1"},
  "dependencies": "dependencies.json",
  "dependenciesByEnv": {"qa": "dependencies.qa.json"},
  "https": {"caddyBinary": "/opt/caddy/bin/caddy", "caddySha256": "<sha256>", "port": 443},
  "preparedBase": {"mode": "prefer"},
  "allowHosts": ["registry.npmjs.org"]
}
```

Every field except `version` and `projectRoots` is optional. The other fields match
the variables:

| Field | Variable it stands for |
| --- | --- |
| `sharedSource` (`true` or `false`) | `HACK_NATIVE_SHARED_SOURCE=1` |
| `aws.profile`, `aws.region` | `HACK_NATIVE_AWS_PROFILE`, `HACK_NATIVE_AWS_REGION` |
| `dependencies`, `dependenciesByEnv` | `HACK_NATIVE_DEPENDENCIES` |
| `https.caddyBinary`, `https.caddySha256`, `https.port` | `HACK_NATIVE_CADDY_BINARY`, `HACK_NATIVE_CADDY_SHA256`, `HACK_NATIVE_HTTPS_PORT` |
| `preparedBase.mode` (`prefer`, `require` or `off`), `preparedBase.store` | `HACK_NATIVE_PREPARED_BASE`, `HACK_NATIVE_PREPARED_BASE_STORE` |
| `allowHosts` (a list) | `HACK_NATIVE_ALLOW_HOSTS` (a comma-separated list) |

`dependencies` and `dependenciesByEnv` name host dependency files (the format above)
in the same directory: plain file names, never paths. The machine settings do not
select the adaptation, the native binary or the native home. A `gcloud` field or any
other field refuses.

Hack refuses the machine file with `E_CONFIG_INVALID` before any branch, lifecycle,
storage or runtime work unless all of these hold:

- the directory is a real directory owned by you with mode `0700`;
- the directory is outside the project root, and the project root is not inside it;
- `settings.json` is a regular file owned by you with mode `0600`, not a symbolic or
  hard link, at most 64 KiB, and unchanged while it is read;
- every field is valid, including a field that a variable overrides. `aws.profile`
  and `aws.region` must be selectors that native AWS adaptation accepts, and so must
  `HACK_NATIVE_AWS_PROFILE` and `HACK_NATIVE_AWS_REGION`.

Before it reads any other field, Hack refuses the file with `E_PERMISSION` when
`projectRoots` is missing or does not list the current project root. The refusal
happens before any lifecycle hook runs, even when variables override every setting.
A file written before `projectRoots` existed therefore grants nothing: add the
project root to it to grant that checkout again.

A missing directory or file means no machine settings.

**Precedence.** For each setting, a variable that is set wins entirely, even when it
is empty, then the machine settings, then the committed project file. Values are never
merged. For example, `HACK_NATIVE_ADAPTATION` replaces the committed adaptation, and
`HACK_NATIVE_SHARED_SOURCE=0` withholds a share that the machine file grants. A
non-empty `HACK_NATIVE_AWS_PROFILE` selects the AWS variables; `HACK_NATIVE_AWS_REGION`
without it is ignored, as before. Existing scripts that export the variables keep
their exact behavior.

**Per-env files.** `adaptation.<env>.json` and `dependenciesByEnv.<env>` replace the
base file for runs whose effective env is `<env>`: the `--env` you pass, the env a
retained run recorded, or the project's default env. This holds even when the project
has no `hack.env.*` files, or has `hack.env.default.yaml` but no `hack.env.<env>.yaml`.
Otherwise the base file applies. A fresh start, a retained start and a restart of one
run therefore always select the same files. The run records which managed env files
its env had at startup (none, the base only, or the overlay). A later `restart`,
retained `up` or fresh `exec` refuses when that changed, and names the file: an
overlay that existed is gone, or an overlay (or, for a run started without any, a
managed env file) appeared. To apply an appeared file, run `hack down`, then `hack up`.
`down` hooks of such a run get the values it started with (none, or the base values),
so `down` is not blocked. A removed overlay can be restored to keep the run; `down`
hooks of a run that started with it refuse, naming the file, until it is restored.

**Identity and recovery.** Settings resolution only reads files. It writes no state,
so Ctrl-C needs no cleanup, and `down`, `ps`, `logs`, `exec` and `run` keep using the
saved run mapping without reading the settings. A file-selected run and a
variable-selected run with the same contents review the same native plan, so
`restart` retains the run either way.

`hack doctor` on the native backend adds a `native settings` check. It reports where
each setting came from (`env`, `machine`, `project` or `unset`), never its value, and
the machine settings path with your home shown as `~`. With `--json`, the check's
`nativeSettings` holds `origins`, `adaptationFiles`, `machineSettings` and closed
`warnings`:

| Warning | Meaning |
| --- | --- |
| `shared_source_not_granted` | Native `up` and `restart` refuse until the project share is granted. |
| `internal_dns_tls_not_applied` | `internal.dns` and `internal.tls` in `hack.config.json` are not applied on native, so containers cannot reach routes by their HTTPS names. Set both to `false` to silence it. |
| `routes_without_probes` | `routesWithoutProbes` routed services have no native HTTP probe after the adaptation for the default env; native `up` refuses them. |
| `compose_profiles_ignored` | `COMPOSE_PROFILES` is set in the environment, but native selects profiles only from `--profile`. Managed `COMPOSE_PROFILES` values are not inspected. |
| `aws_region_without_profile` | `HACK_NATIVE_AWS_REGION` is set without `HACK_NATIVE_AWS_PROFILE` and is ignored. |
| `unread_project_settings_files` | `.hack/native/` holds files other than `adaptation*.json`; Hack does not read them. |

An invalid settings file makes the check an error with the same closed line native
`up` prints. Each adaptation file (the base and every `adaptation.<env>.json`) is
checked against the Compose file with the validator native `up` uses. The check runs no runtime request, credential export or network call.

### Optional prepared base for a fresh pool

A prepared base formats a **new** pool's disks from an independently verified snapshot of a
sanitized seed pool instead of the stock templates. It changes only pool creation: the first pool
in a candidate home, or one recreated during recovery. Existing pools and graph starts inside a
running pool are unchanged. It is off unless selected and is macOS APFS only.

Build and verify a base in a private store on the same volume as the candidate home. The installed
candidate defaults to `<HACK_NATIVE_HOME>/prepared-bases`; pass `--store /absolute/private/store` to
use another:

```sh
./bundle/hack-native --candidate-root /absolute/private/candidate-home runtime prepared-base build --profile development --json
./bundle/hack-native --candidate-root /absolute/private/candidate-home runtime prepared-base verify --base-id BASE_ID --json
./bundle/hack-native --candidate-root /absolute/private/candidate-home runtime prepared-base status --profile development --json
```

`build` boots a disposable seed pool from cloned providers, with no project, sockets, graphs or
credentials. It installs network tools under the base owner, removes per-pool identity and
runtime residue, and publishes the stopped disks. `verify` boots a separate disposable verifier
from the published base and reads both disks before any setup; a base becomes usable only after it
passes. Both need the same host admission as a development pool while they run, and both delete
their disposable machine afterwards. If one is interrupted, `status` lists its work root under
`abandoned_work`, and the next `build` or `verify` removes it before starting, except while a
provider still runs there. `status` also reports each base under `bases`.

Then select it for normal foreground startup:

```sh
export HACK_NATIVE_PREPARED_BASE=prefer   # or require; unset or off disables
export HACK_NATIVE_PREPARED_BASE_STORE=/absolute/private/store   # optional
```

`prefer` uses the newest verified base bound to the pool's provider, engine, network-tools and
capacity pins, and otherwise keeps the stock templates; `runtime status` records the reason.
`require` refuses before creating the pool. An existing pool ignores the selection. Remove a base
with `runtime prepared-base remove --base-id BASE_ID`; a pool never depends on its base after the
first start.

`scripts/accept-native-frontend.py` checks this path end to end for one owned linked worktree.
- It builds and verifies a base, then runs ordinary `hack-v5 up` with `require`, so the frontend
  creates the pool from that base with the worktree as its exact share.
- It checks healthy HTTPS against the home's private Caddy root and writes a `/data` marker.
- It runs `down`, edits the served file on the host, and runs `up` again. It then requires the
  same run in a new container, HTTPS serving exactly the edit, and the marker.
- Finally it disposes of the pool, base, provider alias and fixture with readbacks.

It prints its plan unless `--run` is given and is a correctness check only. On any failure, or
when its `--budget` runs out, it issues no further commands and keeps all state for diagnosis.
The only process it can terminate is one of its own bounded commands, whose direct child
`subprocess.run` kills when its timeout expires; it never signals a foreground or a VM. Ambient
`HACK_NATIVE_*` variables are dropped, so only its declared selections reach the candidate. Its
stand-in controls run with
`python3 -m unittest discover -s tests/python -p test_native_frontend_acceptance.py`.

Add `--domain-migration` to qualify domain changes in that same linked worktree.
This opt-in starts with legacy `.hack` and OAuth `.hack.gy` project/service aliases,
runs the real Doctor preview and application, then performs a retaining restart
and requires every old/new `.hack.local` route to serve the exact source. Another
restart after Doctor rollback must restore the original route set and stop serving
the removed aliases. Both transitions retain the run, owner, plan, volume bindings
and exact data marker. Commands infer the branch from the linked checkout. The
driver also checks exact original file bytes/modes, unchanged primary checkout,
preview without effects, and refusal to roll back over an independent file edit.
Only audited `graph inspect` and `runtime status` observations may repeat an exact
structured `provider_busy` refusal, within a 15-second observation budget and the
overall run budget. Every attempt retains its output and result. Other errors,
malformed replies and timeouts stop the run; mutations, refresh and exec never
use this re-observation path.

The resulting `evidence/domain-roundtrip.json` records this narrower proof separately.
It does not qualify a simultaneously running sibling graph, system DNS, certificate
trust or a browser session: HTTPS uses the fixture's private root and `--resolve`.
Complete any normal-origin browser check separately before marking that acceptance
criterion complete. The driver never installs trust or DNS and still disposes its
owned fixture after success; there is no indefinite browser handoff or global change.
For a manual browser check, request a fresh phase-specific query (for example,
`/index.txt?phase=<unique-run-and-phase>`) and require the current fixture marker.
A new tab can still display cached content from an earlier certificate or route;
it does not prove a new TLS connection. Use an uncached request for both positive
checks and expected certificate-rejection controls, without bypassing warnings.

### Optional native HTTPS frontend

For routed foreground startup, explicitly set all three public selections:
`HACK_NATIVE_CADDY_BINARY` (absolute host Caddy executable),
`HACK_NATIVE_CADDY_SHA256` (its lowercase SHA256), and
`HACK_NATIVE_HTTPS_PORT` (1–65535, including 443). Unrouted graphs do not start
this frontend. The selected process and managed hostname authority belong to the
foreground invocation; unexpected loss aborts the graph and reports failure.
They close after graph cleanup, while private Caddy data and its CA remain under
`<native-home>/native-https/data`. An occupied frontend owner is refused.

The selected port must be available to the current host user. On hosts that restrict
port 443, use an unprivileged test port such as 18443 or separately configure
authorized host forwarding. Startup checks bind permission and leaves existing
listeners untouched; it never elevates privileges automatically.

Startup verifies each reviewed hostname using loopback, SNI, Host, and the private
CA, without relying on DNS or installing system trust. It requests the service's
reviewed native HTTP health path and requires a 2xx response, matching the guest
readiness policy. It does not render `/` merely to verify an alias. The guest
readiness probes remain required; a health response does not establish a usable
browser session. DNS and user-approved trust setup are separate prerequisites for
normal browser access.

With the native backend selected, `hack doctor --json` inspects the active
frontend owner, the exact Caddy listener and root certificate, and macOS
System-keychain trust. A retained root file or an older same-name certificate
does not count as current trust. Doctor also lists superseded Caddy roots still
in the System keychain, by count and SHA-256 fingerprint. It never removes them;
see [Superseded Caddy roots](/docs/v5/guides/macos-certificate-trust#superseded-caddy-roots)
for the removal steps you run yourself. To check a real app route, pass an exact HTTPS
origin with `--browser-url`; Doctor verifies that hostname over loopback with
the live root, checks that every host DNS answer points at its IPv4 loopback
relay, and reports normal macOS TLS separately. `--browser-result` records
your manual observation for that origin; CLI success alone does not prove a
browser session works.

The native candidate refuses `hack global install`: that command owns the
Docker global stack and could change installed v4 routing. For a dedicated
custom suffix alongside v4, run `hack global dns preview --domain v5.hack.gy`
and then `hack global dns activate --domain v5.hack.gy`. Without `--domain`,
these commands use the global `default_domain` only when it is a custom suffix;
changing that shared setting also changes the installed v4 CLI's default. With a
built-in default such as `hack.local`, they stop with a usage message that names
`hack doctor --fix` and the rollback command below. Preview is read-only;
activation shows the exact scoped claim and requires interactive confirmation
and a native administrator prompt. Run it from a terminal; the bounded privileged
steps preserve that terminal's sudo authorization and report the underlying
command failure if a step fails. If you approve but the administrator prompt
does not complete (it times out after 120 seconds, is interrupted, rejects the
password, or Hack is not the terminal's foreground job), activation fails during
authorization with that cause, says nothing changed, and suggests running
`sudo -v` in the same terminal first. Only answering no is reported as denied. Before changing files, the candidate checks that
the root-owned Homebrew system launchd job matches the inspected dnsmasq command
and configuration. It restarts that verified job directly through launchctl, so
activation does not need Homebrew metadata downloads as root. Missing, changed or
ambiguous service ownership refuses. It adds one owned dnsmasq include file and
one resolver file pointing the selected suffix to 127.0.0.1, while leaving
the built-in v4 DNS rules intact. An existing or overlapping foreign claim,
uninspected configuration source, or uncertain prior activation refuses.
Activation verifies direct and system DNS and conditionally removes only its
own files if verification fails. To remove this scoped claim, use
`hack global dns deactivate --domain v5.hack.gy`. It requires a matching active
private receipt and unchanged file identities across confirmation, then removes
only those two owned files, restarts dnsmasq and verifies the parent fallback.
The private receipt becomes `inactive` after proof so a later activation can
reuse the suffix. An interrupted activation retains a `pending` receipt; an
interrupted deactivation retains a `removing` receipt. Both refuse automatic
retry until the partial state has been reviewed and explicitly recovered; do
not delete these files or receipts blindly. The built-in `hack`,
`hack.local`, and `hack.gy` roots cannot be claimed wholesale by this command;
a dedicated `v5.hack.gy` subtree is supported when its v4 parent is verified.
Existing project hosts and reviewed routes are not migrated.
A suffix outside `.local`, such as `v5.hack.gy`, also avoids the macOS
Local Network grant that browsers other than Safari need for `.local` names;
see [macOS browser connectivity](/docs/v5/guides/macos-browser-network).

DNS activation alone does not prove that an app route, certificate, port 443,
or OAuth redirect is ready. Use `hack doctor --browser-url` for the exact app
origin and test the browser session. Google OAuth requires a separately
registered compatible redirect origin; `.local` may be rejected by the provider.

`hack doctor --fix --browser-url https://your-app.hack.local` can install only
the verified live root after interactive confirmation and the native macOS
administrator prompt. It checks the owner, root and route again after that
prompt and verifies trust after installation. A missing, stale or changed owner
refuses repair. The native `hack global trust` path directs you to this scoped
Doctor command instead of falling back to Docker's exported CA. The native
trust repair does not set up DNS or a browser's Local Network permission.
Both authorization and installation retain the caller's controlling terminal,
so terminal-scoped sudo authorization remains valid during the bounded repair.

Doctor's progress spinner stops before any repair asks a question. It stays off
through the native administrator prompt and the privileged steps that follow,
then resumes, so sudo's `Password:` prompt (or the Touch ID sheet) stays
visible. Doctor runs repairs one at a time. The administrator prompt (`sudo -v`)
runs in the terminal's foreground process group before any `sudo -n` step. If it
does not complete, the CA repair reports an error that names the cause and
suggests running `sudo -v` in the same terminal first. sudo itself prints
`a password is required` when its first password read is interrupted or times
out.

`hack.local` stays the default dev-host root. An older Docker-era install routes
it to Docker Caddy with `address=/.hack.local/172.30.0.2` in Homebrew's
`dnsmasq.conf`, which the native loopback relay cannot serve. On macOS, native
`hack doctor` reports a `native hack.local route` check (JSON field
`hackLocalRoute`), and `hack doctor --fix` proposes a separate DNS repair. It
rewrites only that one Hack-managed line to `address=/.hack.local/127.0.0.1`,
in place. It never adds a second line for the suffix, and the `.hack` and
`.hack.gy` lines and every other byte stay unchanged. If
`/etc/resolver/hack.local` is missing, the repair creates it with
`nameserver 127.0.0.1`. The repair proceeds only when all of these hold:

- The native relay owner is verified and listening on 127.0.0.1 at its receipted port.
- `dnsmasq.conf`, every `dnsmasq.d/*.conf` include file and the resolver file
  are bounded regular UTF-8 files with one link and are not symlinks.
- Neither `dnsmasq.conf` nor an include file loads a DNS source Hack did not
  inspect: `conf-file`, `conf-script`, `addn-hosts`, `hostsdir`, `servers-file`,
  or a `conf-dir` other than `<brew>/etc/dnsmasq.d,*.conf`.
- The line has the exact Hack-managed form and is the only `.hack.local` claim,
  including `dnsmasq.d` include files.
- The target is one Hack wrote (`172.30.0.2` or `::1`).
- The old target does not answer on port 443 within 1.5 seconds, so a running
  Docker Caddy is never broken.
- Any existing resolver file contains only `nameserver 127.0.0.1`.

Each unmet condition is a closed refusal reason: `relay-not-verified`,
`dnsmasq-config-missing`, `unreadable-config`, `uninspected-config-source`,
`no-managed-line`, `unmanaged-line`, `foreign-target`, `foreign-resolver`,
`old-target-live`, `pending-receipt`, `invalid-receipt`, `non-interactive`,
`declined`, `authorization-failed`, `busy`, `restart-unavailable` or
`inputs-changed`. `declined` means you answered no to the confirmation.
`authorization-failed` means you approved, but the native administrator prompt
did not complete: it timed out after 120 seconds, was interrupted, rejected the
password, or Hack was not the terminal's foreground job. Run `sudo -v` in the
same terminal, then rerun `hack doctor --fix` (or the rollback command). Refusal details
name files and lines by number and never repeat file contents. The repair needs interactive confirmation and the native macOS
administrator prompt; without a terminal it refuses and names `hack doctor --fix`
to run in one. Only one repair or rollback runs at a time; a second one refuses
with `busy`. After the prompt the repair checks that the dnsmasq launchd job can
be restarted (`restart-unavailable` otherwise), then inspects everything again
and refuses if anything changed. Before changing files it writes a private
receipt to `<native-home>/native-dns/hack-local-route.json` with the old line,
new line, SHA-256 hashes of the exact file bytes and timestamps. It replaces the
file atomically and keeps every other byte, including a leading byte-order mark.
It then restarts the verified dnsmasq launchd job, flushes the DNS cache and
verifies live resolution. If a later step fails, it restores the earlier line
automatically; when the failure came before any change, it reports that nothing
changed. `hack global dns preview --domain hack.local` shows the same proposal
without changing anything.

The repair routes names to 127.0.0.1 but does not change ports. With a
`HACK_NATIVE_HTTPS_PORT` other than 443, such as 18443, URLs still need that
port, for example `https://app.hack.local:18443`. The confirmation prompt names
the relay port.

To undo the repair, run `hack global dns deactivate --domain hack.local`. It
needs a terminal and refuses with `non-interactive` and the same command
otherwise. It refuses with `unreadable-config` and changes nothing when
`dnsmasq.conf` is not a bounded regular UTF-8 file. It restores the exact earlier line and verifies the whole-file hash
against the receipt. It removes the resolver file only if the repair created it
and its identity still matches, then restarts dnsmasq. If dnsmasq is not
running, or the job cannot be restarted safely, the rollback still restores the
file and says that dnsmasq was not restarted; the line loads on its next start.

An interrupted repair leaves a `pending` receipt, and Doctor refuses another
repair until the same rollback command handles it. Sometimes `dnsmasq.conf`
changed after the repair, for example when a Docker-era `hack doctor --fix` or
`hack global install` rewrote the built-in roots. In that case, or when the
receipt names another `dnsmasq.conf` path, restoring would overwrite those
changes. The rollback command then never writes the file. Instead, after a
plain confirmation, it marks the receipt `released` and leaves `dnsmasq.conf`
and any resolver file as they are. Doctor then inspects the current file again.
Restore the recorded line yourself only if you still want the earlier route. A
Docker-era `hack doctor --fix` or `hack global install` still rewrites all
three built-in roots to whichever target answers, which can undo the native
repair.

The runtime's read-only `runtime inspect-host-listener --pid PID --port PORT
--executable /absolute/caddy --json` reports the selected same-user loopback
listener identity. The optional `--peer-port PEER_PORT` proves Caddy accepted
that exact still-open TLS socket, including when Caddy enables `SO_REUSEPORT`.
Doctor and native startup use the peer proof before accepting a TLS route.
A PID, file path or listener fingerprint alone is not proof of an owned
frontend or CA.

The probe pins its TCP connection to loopback independently of SNI and Host.
Failed HTTPS verification reports a reviewed TLS/transport error code or
`VERIFICATION_TIMEOUT_HANDSHAKE` / `VERIFICATION_TIMEOUT_RESPONSE`, without peer values. Unknown errors use
`TLS_OR_TRANSPORT_ERROR`. Startup saves the project run mapping only after these
checks succeed. Confirmed graph cleanup preserves the original startup error. If final
inspection or cleanup cannot be confirmed, the error instead reports retained-state
uncertainty alongside the sanitized startup diagnostic. Any published mapping remains
intact; inspect owned runtime and bridge state before retrying. A native cleanup
error code is included when available, without its raw output or message. When a
foreground owner refuses cleanup, the CLI also preserves its bounded cause code
alongside `graph_owner_recovery`; raw owner diagnostics remain omitted. Failed
cleanup is never automatically replayed.

Stop failures can also include `stop_failures` version 1 with at most 32 distinct
admitted service names and fixed stages: `connect_timeout`, `connect`, `timeout`,
`response`, `worker`, `transport` or `deadline`. `response` covers a rejected or
unreadable response; these stages describe the request failure, not whether the
container stopped. A batch sends at most four stops at a time and joins every
stop worker before the failure is returned. Only `connect` and `connect_timeout`
are retried inside the batch, because no request reached the engine; these stages
mean the engine stayed unreachable for that stop's 30-second retry window or the
batch deadline. Container IDs, response bodies, transport messages and credentials are
omitted. The authenticated foreground client validates the private receipt and
checks matching service membership and container generations before and after
the request. Detail never grants retry or deletion authority.

### Inspect a partial retaining shutdown

A pending cleanup of started container generations is different from a failed
container start. A completed historical startup journal does not make the pending
shutdown eligible for interrupted-start recovery. The native `graph inspect`
response includes a read-only `pending_cleanup` version 1 hint when applicable:
`partial_shutdown`, `interrupted_startup_candidate` or `unclassified`. A startup
candidate must still pass the separate exact native selection before recovery;
the hint itself is not an ownership, cleanup or acknowledgement proof.

Inspect a mapped project through the selected candidate:

```sh
HACK_NATIVE_HOME=/absolute/private/candidate-home /absolute/bundle/hack-v5 doctor \
  --native-cleanup inspect --path /absolute/project --branch feature-api --json
```

Omit `--branch` for the base instance, or let linked-worktree auto-selection use
the configured branch policy. This command performs only native graph inspection,
reports aggregate container/volume observations and returns exit status 1 when
cleanup is pending. Missing volumes are reported as absent, not presumed retained.
It does not run hooks, repeat `down`, retire a publisher, restart the pool, repair
trust or acknowledge cleanup. The JSON envelope describes a successful inspection;
the exit status separately indicates pending cleanup. Older executors without the
hint report `unclassified` rather than inventing eligibility.

Preserve the run mapping and private receipt. For a partial ready-graph shutdown,
same-boot uncertain stops remain fenced; use the explicit previous-boot cleanup
flow below. Before stopping a pool, review every graph using it: a pool restart
affects live siblings. Stop/start must remain explicit, with the same pool identity
and profile, network, source and socket selections. Select the exact receipt hash
and follow the two-step recovery, then retire its exact recovered publisher and
independently verify container absence, retained volumes and unaffected sibling
data. Another boot rollover, changed receipts, missing data or stale ownership
refuses recovery. Do not edit journals, fabricate relay acknowledgement or repeat
stop requests to get past that refusal. Application restoration and frontend
finalization are separate checks after native cleanup succeeds.

Graphs without ingress routes use the same guarded flow. Recovery binds the
persisted empty pre-effect route selection to the pending cleanup and verifies
the dead predecessor publication. That selection belongs to the interrupted
operation; replacing a selection from an older restored generation still requires
independent restore-history proof.

### Quarantine a corrupted disposable build cache

Some frameworks keep a regenerable build cache inside a named volume next to other
generated output. When such a cache is corrupted (for example a Turbopack checksum
mismatch reported as a misleading `Module not found`), you can move exactly that
cache directory aside. Nothing is deleted, and other volumes and directories are
unchanged.

First declare the regenerable directories on the volume in the Compose file. Paths
are relative to the volume root. List at most eight distinct directories; one entry
cannot contain another:

```yaml
volumes:
  www_next:
    x-hack-disposable-cache:
      - dev/cache/turbopack
```

The declaration is part of the reviewed plan. It is recorded in the graph receipt
when the graph is admitted, and only a receipt-recorded entry can be selected later.
A volume that is also a shared dependency cache cannot declare disposable
directories. Declaring a path grants no automatic cleanup.

Stop the graph with an ordinary retaining `down` (phase `stopped-data-retained`).
With the owned runtime running, inspect the single target. This step is read-only:

```sh
./hack-native --candidate-root /absolute/private/candidate-home graph inspect-cache-quarantine \
  --run-id <run-id> --volume www_next --path dev/cache/turbopack --json
```

The response reports the target's `target_bytes` (regular-file bytes),
`allocated_bytes`, `entries` and a `selection_sha256`. The selection binds the exact
receipt bytes, the volume name, creation time and root directory identity, the
target directory identity and the measured bytes. Review it, then quarantine:

```sh
./hack-native --candidate-root /absolute/private/candidate-home graph quarantine-cache \
  --run-id <run-id> --volume www_next --path dev/cache/turbopack \
  --expect-selection <selection_sha256> --json
```

These commands, and `resolve-cache-quarantine` below, hold the provider mutation
lease. They refuse when any of these is true:

- the graph is active, its journal is incomplete, or interrupted cleanup is pending
- the path is not exactly a declared entry, or is absolute, traversing or empty
- the volume is missing, carries foreign ownership labels, or has changed
  incarnation (any inspected field other than `CreatedAt` differs, or the guest
  observes a different `_data` directory, as after the volume was removed and
  recreated under the same name)
- any container mounts the volume, including stopped containers
- a component of the path, or the target itself, is a symbolic link or not a
  directory
- the target directory was replaced after inspection

The guest renames the directory under a lock on the volume root into
`/var/lib/docker/volumes/<volume>/hack-quarantine/<id>`. That directory is beside
the volume's `_data` root, and no container can mount it. Before the rename the
guest checks that the source and the quarantine directory are on the same mount
(the same `findmnt` mount ID, not only the same device number). A rename within
one mount cannot fail with a cross-device error, so `mv` never falls back to
copying and then deleting the source. The result reports `quarantined_bytes` and
`reclaimed_bytes: 0`. The bytes remain for diagnosis until the owning volume
itself is explicitly removed (for example `graph cleanup --remove-data`). Restart,
restore and ordinary cleanup never collect them. Then use a normal retaining
restart. The framework regenerates its cache.

Quarantined bytes are outside the volume's `_data` directory. Docker's disk-usage
report, and therefore `graph storage-inventory`, does not count them, so the inventory
undercounts a volume that holds a quarantine. Every `inspect-cache-quarantine`
result, including `target_absent`, reports `retained_quarantine_records` and
`retained_quarantine_bytes`: the recorded bytes still held in the current
incarnation of that volume.

The first quarantine of a volume creates `hack-quarantine` beside `_data`. Docker's
`local` driver reports a volume's `CreatedAt` from the modification time of that
directory, so the reported value changes. The selection records `CreatedAt` as
observed evidence, but it is not volume identity: the move still settles, a pending
record still resumes, and its bytes are still counted. A digest reviewed before an
earlier quarantine of the same volume no longer matches; inspect again. If the
volume changes during the guest effect, the command fails with
`graph_cache_quarantine_unsettled` and the record stays pending for explicit resume
or resolution. A failed recheck inspection or guest directory-identity read instead
returns `graph_cache_quarantine_unobserved`: the command could not observe the
volume after a possible effect. It makes no claim that the volume changed. The
record stays pending, and explicit resolution can settle it once observation is
available again.

Retained-volume recovery and removal use stable inspection fields plus the guest
`_data` device/inode, so a quarantine does not invalidate their selection. See the
[volume identity audit](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/volume-identity.md) for covered workflows,
excluded protocols, and compatibility limits.

A successful guest exit with an unrecognized or truncated MOVE reply also reports
`graph_cache_quarantine_unsettled`: bytes may have moved, so the record stays pending
for explicit resume or resolution.

Volume identity has a residual inode-reuse risk. If an external actor removes and
recreates the volume between IDENTITY and MOVE with the same inspection fields and
reused device/inode numbers, quarantine cannot detect the replacement. Exclude
external volume removal/recreation during quarantine; the provider lease serializes
Hack mutations only. A Hack-written generation nonce is deferred because existing
volumes need a durable enrollment and interrupted-enrollment recovery contract;
quarantine must not silently create or repair identity for an existing volume.

A private record under the candidate home's `run/cache-quarantine/` is written
before the guest effect and marked `quarantined` after the guest syncs the move.
If the command is interrupted, `inspect-cache-quarantine` reports the recorded
digest with one of two phases:

- `resume_required`: the receipt and volume are unchanged. Repeat
  `quarantine-cache` with the same selection. Resumption accepts the recorded
  directory either still at its source or already at its destination with the
  same inode. It refuses a regenerated directory, a different destination or
  both present, and never moves new bytes.
- `resolve_required`: resumption is no longer possible, for example because a
  restart changed the receipt, or because the move keeps refusing. Settle the
  record without moving anything:

  ```sh
  ./hack-native --candidate-root /absolute/private/candidate-home graph resolve-cache-quarantine \
    --run-id <run-id> --volume www_next --path dev/cache/turbopack \
    --expect-selection <recorded selection_sha256> --json
  ```

  Under the same lease, consumer and ownership checks, the guest reads the
  recorded destination under the volume root lock. The record becomes
  `quarantined` when the recorded directory (same inode) is there, and
  `abandoned` when the destination is absent, which means nothing was moved. Any
  other layout, such as a symbolic-link quarantine directory or a different
  directory at the destination, refuses. After resolution, inspect again for a
  fresh selection.

You can also resolve a record that could still be resumed. While a record is
pending, other quarantines of that volume are refused. A torn record write
refuses automatic replay. Records are retained as diagnosis evidence and are not
collected automatically. Each volume admits at most 16 records, and the candidate
home holds at most 1024. Volume names are specific to a run, so a new run starts
with a fresh per-volume budget. When the global limit is reached, every new
quarantine is refused; this candidate has no command that collects records.

This operation does not classify the cause of the corruption. One checksum error
does not show an interrupted write or a storage integrity fault. Container health
also does not prove that application routes work; check the public route
separately after restart.

### Explicit cleanup after a dead foreground owner

`hack up` and `hack restart` refuse a run whose foreground publication is still
present and name the next step: a running owner must be stopped with Ctrl-C or
`hack down`; an owner that exited while its services were running is stopped by
`hack down --recover`. That command selects the run's exact receipt with the
read-only `graph foreground-owner --run-id RUN --json` and then uses the
same-boot `graph recover-live-owner` described below, retaining data and
retiring the stale publication. If the frontend that owned the run also exited
before confirming its cleanup, `hack down --recover` prints the exact
`hack restart --recover-frontend --expect-finalization-attempt ATTEMPT` step.
An owner that exited before its restore was admitted is reported, with data
retained, but no command retires that attempt yet.

Read-only `hack ps` and `hack logs` hold the provider lease only briefly. Native
startup, retained-start eligibility, restore admission, inspections inside
mutating commands and owned foreground cleanup wait out such a holder within a
bound instead of failing, so polling status during `up` or `restart` does not
make them fail or strand a foreground publication.

For a fully ready graph whose foreground owner died while its pool remains on the
same boot, `graph recover-live-owner --run-id RUN --expect-receipt SHA256` selects
only that graph. It requires matching dead foreground and relay-owner identities,
unchanged receipt and resource inventories, and exclusive publication locks. The
relay endpoint may also be absent after the managed owner exited: both relay files
must be absent under the original held operation lock, and the exact dead
foreground process and ready receipt must select the control root derived for
this run, runtime owner, and current guest boot. Recovery persists that absence
witness and rechecks its directory/lock identity, process death, endpoint absence,
and receipt bytes at cleanup boundaries. A partial publication, replacement
endpoint or lock, legacy unscoped root, or changed receipt is refused. This path
does not recreate relay metadata or invent a live-owner acknowledgement. The
operation stops verified guest dependency listeners, removes owned containers and
network resources, retains persistent data, retires stale foreground and relay
publications, and releases the graph's dependency reservation before unlocking the
pool. It does not restart the pool. Pending startup, one-off or dependency
rebind state is refused. A completed dependency refresh is accepted only for the
current boot and exact ready receipt generation, with matching terminal services
and helper markers. After owned absence is independently verified, its journal is
archived before stale publications are retired. An interrupted archive resumes
from the committed cleanup proof and exact journal bytes; it never replays refresh.
Completion records owner-death evidence independently of
the live relay acknowledgement protocol.
When a restored publisher is admitted, older absence-retirement records remain
validated history; the exact current cleanup proof supplies retention authority.

Before the main recovery intent, the operation journals and normalizes owned
bridge reservations that never launched (`reserved` with no relay intent) or whose
exact reservation-v1 helper has exited. The journal binds the original receipt,
boot, owner witnesses and complete same-run bridge inventory. It resumes confirmed
stop/removal interruptions, including canonical pending fence writes, without
removing a replacement socket, helper, allocation or reservation. A helper may
remove its own socket on exit; its exact process identity and retained private
socket receipt remain required. An originally live, unchanged bridge that exits
before main intent enrollment can be added to the journal with fresh exit proof.
Starting reservations, unknown or partial metadata, added assignments and replaced
identities refuse. Live helpers are left for the existing main recovery path;
other graphs are not selected. The normalizer does not run on an existing main
intent retry. Completed normalization journals are generation-bound history after
an independently verified retained restore.

After completion, retained restore can create a fresh owner;
`graph retire-recovered-publisher --run-id RUN --expect-owner OWNER` remains an
idempotent compatibility operation. Interrupted cleanup retains its journal for an
explicit retry with the original receipt hash. A pool boot
change, replaced process or socket evidence, or ambiguous ownership refuses recovery.
The separate previous-boot operation below preserves its existing ownership
requirements.

If current-boot cleanup is already confirmed and retained data is intact, but
the dead foreground publisher still has its owner and socket while its operation
lock pathname is missing, ordinary retirement must refuse. First inspect with
`graph inspect-missing-publication-lock --run-id RUN --json`. After placing the
exact candidate home in a maintenance window that prevents older Hack binaries
and background clients from starting new operations, use
`graph retire-missing-publication-lock --run-id RUN --expect-selection SHA256 --accept-quiesced-candidate-home`.
The explicit action creates a selected private replacement lock, then reuses the
current-boot cleanup proof and publisher-retirement journal. It does not alter
graph receipts, guest resources or retained volumes. An interrupted repair
blocks ordinary publication until the same selected operation resumes and its
completion is verified. The CLI cannot itself prove that older binaries obey
the publication gate; process listings alone do not establish that maintenance
window. Keep the VM and its guest boot unchanged during this recovery.

An interrupted publisher can also leave its separate relay-control publication
after cleanup is acknowledged. Selected acknowledged retirement verifies that
relay's exact dead process, socket and confirmed cleanup operation before removing
its publication. A durable record bound to that publisher permits an exact retry
after interruption; records from earlier publishers grant no authority over a
replacement. Restore checks for incomplete retirement before reserving dependency
slots or creating a relay listener. Relay admission shares the existing bounded
provider-admission deadline when waiting for a concurrent recovery operation.

Repeating a completed missing-lock repair can finish the same stopped generation's
relay retirement. If the graph has moved to a later generation, the old completion
is historical evidence only. A failed current cleanup or ownership check is not
permission to discard files; preserve the evidence and use the selected recovery
operation.

A graph with completed host-dependency startup and no inbound routes can also use
its exact dead relay publication as the previous-boot proof; an empty bridge
registry alone never grants cleanup authority.
A completed previous-boot or same-boot recovery may remain as historical evidence
after restore.
When its exact stopped receipt remains in bounded restore history, that receipt
must match the completion proof. After history eviction, only a self-consistent
proof for the same graph and a different container generation can be treated as
inert history; the verified truncated history must independently contain a later
stopped generation. This does not establish the evicted completion hash as current
authority. Same-boot history also requires validated listener retirement.
Incomplete, foreign, one-off, conflicting or missing-history records
refuse without modification. Current owner, boot, process, receipt and resource
checks still authorize cleanup independently, including on retries.
A later previous-boot recovery may archive that validated older completion even
after its exact stopped receipt has been evicted. It preserves the original proof
bytes and inode by renaming it; it does not reconstruct an evicted receipt or use
historical evidence as current cleanup authority. Pending or incomplete proofs,
changed graph identities and an unchanged container generation still refuse.
Retention and recovered-publisher retirement prefer a completed previous-boot
proof that matches the exact current stopped receipt. An older same-boot proof
must still pass historical validation; its presence cannot redirect these
operations away from the current proof. Pending, incomplete, malformed or
conflicting same-boot records continue to refuse both operations.
An already completed prior-boot dependency archive is likewise historical
metadata. Restore may leave it untouched after validating its original generation,
boot, journal and exact artifact hashes, with no active or pending journal and an
independently confirmed current retention proof. Eviction of its old stopped
receipt does not require repeating completed archival. First-time or interrupted
archival still requires the exact selected cleanup proof and ownership checks.
An explicitly requested data removal can select a completed same-boot recovery
after publisher retirement. It pins the exact completion, current guest boot and
archived publisher identity; retries keep the selected proof source and refuse
changed evidence. This does not fabricate a relay acknowledgement. Native routed recovery has been
qualified with repeated owner crashes, retained data and an unaffected sibling's
HTTPS route; this does not establish normal source-mounted worktree parity.

`graph recover-cleanup --run-id <run> --expect-receipt <sha256>` is a retaining,
explicit two-step recovery for a failed enrolled graph. Select the SHA256 of its
private `state.json` receipt while the owned runtime is confirmed stopped. The
first invocation records the exact receipt, dead foreground owner, and old boot;
it returns `awaiting-runtime-start` without guest effects. After explicit ordinary
`runtime up`, repeat the same command and original receipt hash. Recovery requires
the same pool incarnation and the selected previous boot, removes only verified
owned containers and networks, and retains named volumes and dependency caches.
It neither marks incomplete package caches valid nor replays initializers.

If a foreground owner died after its graph reached `ready-observed` and the pool
has already restarted once, the same explicit command can select recovery on that
immediate successor boot. It requires the retained dead-owner identity, exact receipt
hash, and bridge assignments belonging to the recorded previous boot. The recovery
intent pins those assignments before effects and refuses replacements on retry.
Do not restart again to attempt this path: another boot rollover invalidates the
previous-boot evidence. Old guest helper absence follows the verified boot transition;
it is not recorded as a live helper acknowledgement.

Recovery retains its own durable intent and completion evidence. It does not forge
a relay acknowledgement. A normalized graph can explicitly retire its recovered
publisher and select a fresh foreground restore using the retained data. Missing
or replaced foreground evidence, pending graph journals, unfinished explicit page-cache release, changed
inventories, another boot rollover, and unsupported prior cleanup enrollment
refuse. Preserve these files and use the reported reconciliation path rather than
editing receipts. Receipt-only export/prune still requires its existing relay
acknowledgement. Runtime restart and actual cleanup remain explicit operations.

After recovery completes, explicitly remove that graph's retained data with:

```sh
./hack-native --candidate-root /absolute/private/candidate-home graph cleanup --run-id RUN_ID --remove-data --json
```

This separate destructive request requires the retained dead-owner identity and
completed recovery evidence on the same boot. It also works after explicit
`retire-recovered-publisher`: the archived publisher must match the recovery's exact
owner fingerprint and completed receipt, with unchanged archived record, socket and
lock identities. No application restore is required first. Partial retirement,
missing evidence or another boot still refuses removal. Ordinary acknowledged
cleanup keeps its own authority even when an older recovery record exists.
Before removal it verifies the receipt's ownership labels and journals the current
volume inventory. Retries refuse changed ownership or replacements relative to
that removal inventory. The older recovery receipt does not independently pin a
volume's creation timestamp before the first removal request. An interrupted
removal can resume against its recorded inventory; it does not authorize removal of
another graph's volumes. Recovery alone continues to preserve data. Keep the
recovery evidence until cleanup finishes; deleting it is not a repair.

Private environment delivery preserves the selected numeric image or Compose
`User`, including UID-only values. Docker resolves the application's primary and
supplementary groups from the image; the wrapper does not replace them with group
zero. UID-only private files and relay/probe helpers use group zero as their own
storage/helper metadata, not as the application's identity. Payload files remain
owner-only mode 0400 with exact UID, regular-file, single-link, size, and no-follow
checks. Named users/groups remain unsupported for private delivery and refuse
instead of silently becoming root. An image with no user retains Docker's normal
root default; an explicit Compose numeric user takes precedence.

Services with private environment values and services with host dependency
bindings (including every service when project-wide host aliases exist) run their
process through a wrapper. The wrapper runs exactly what Docker would: the image
or Compose `entrypoint` followed by `command` (with no entrypoint, `command`
alone), and a bare executable name such as `docker-entrypoint.sh` or the
`mysqladmin` of `CMD mysqladmin ping` is resolved through the container's own
PATH after the environment is applied. A shell-form health check (`CMD-SHELL`
or a string `test`) runs through the image's shell (`/bin/sh -c` by default), as
Docker runs it. Stock images therefore need no absolute paths. What a wrapper
still cannot run is an empty process, a health test that names no executable, a
named (non-numeric) user, a stop signal other than SIGTERM, SIGINT, SIGQUIT or
SIGKILL, and a volume target at `/`, `/run` or a reserved wrapper path. Native
`up` refuses the Compose-declared cases before the VM starts, and the runtime
checks settings inherited from the pinned image before reserving anything. Both
name every refused service and field at once (for example
`service db user (use a numeric UID or UID:GID)`). `hack doctor` on the native
backend reports the Compose-declared cases in its `native process wrappers`
check, for every service native may wrap. Only profile-active services are
checked by `up` and `restart`; a service behind an unselected profile never runs
and cannot block them, so `doctor` lists such services as information only.

### Approved-host DNS on pool restart

The pinned Smol provider re-resolves approved hosts at each boot and appends the
results to its retained runtime CIDRs. The candidate accepts at most 512 runtime
entries, including duplicates, only when all original pinned addresses remain
present and every entry is a canonical public IPv4 `/32` or IPv6 `/128` address.
Private, loopback, metadata, broader subnet, missing-pin and oversized results
remain refused. The durable provider database must still match the approved host
list and original CIDRs exactly; restarting does not expand the approved hosts.

This audit trusts fresh DNS resolution by the pinned provider. It does not
independently prove which hostname produced each added address. Existing dynamic
DNS and descendant-host policy semantics remain unchanged.

Native HTTPS startup probes each reviewed alias at its service's reviewed native
HTTP health path. A 2xx response qualifies directly. Redirects (301, 302, 303,
307, 308) qualify only when their chain ends at a verified 2xx response from another
reviewed alias of the same service and health path. Redirect targets must use HTTPS,
port443 or the selected frontend port, and no credentials, query or fragment.
Cycles, external names and cross-service redirects refuse startup. Every request
still connects to loopback with the selected private CA and the alias as SNI/Host;
redirect URLs never select network destinations. Response headers are bounded to
8KiB; malformed headers and duplicate Location fields are refused. Only bounded
headers are parsed and returned; unrelated repeated headers such as Set-Cookie
are allowed.

### Normal native exec

With the same explicit native binary/home selection used for `up`, run
`hack exec --path /absolute/project SERVICE -- /bin/echo hello`. The command targets
the current owned project/branch mapping, preserves binary stdout/stderr and the
command exit code, and never falls back to Compose. It is noninteractive, with a
30-second observation budget; a timeout may leave the command running and is not
retried. `--env` and `--profile` changes are refused. A command name such as `bun`
uses the selected container's PATH; no host PATH or implicit shell is used. Normal
`hack exec` resolves the saved startup overlay and AWS profile again, and delivers
fresh selected-service values through private stdin.
Each request binds the reviewed plan, current container and generation, and has
its own short ingress lifetime. Startup leases and files are not renewed or rewritten.
The allocation is selected from the current container's exact read-only mounts and
checked against its committed current-boot intent. Historical allocations retained
by earlier restores do not compete with this selection; pending, mismatched or
ambiguous mounted allocations are refused.
Legacy mappings without explicit selectors and services with older launcher mounts
refuse before execution; restart with the matching candidate to adopt this path.
Services without managed values use ordinary exec. The native live qualification
of this fresh-delivery path remains separate from its unit and transport tests.


Managed HTTPS authority startup uses the same five-second provider-lock admission
budget as ordinary pool startup. This lets a brief concurrent graph inspection
finish before admission. Pool identity, socket ownership and certificate admission
are checked only after the lock is acquired; expiry refuses with `provider_busy`
and no authority is published. Serving and cleanup are never replayed.

An authority child that exits before readiness can supply a bounded structured
native error code without exposing its stderr. Malformed, oversized or missing
output leaves the cause unknown. The `authority-ready` diagnostic now covers only
readiness; later socket-identity, permission-port and Caddyfile failures have
separate stages. These classifications do not acknowledge cleanup or permit an
owner to be adopted or replaced.

A detached HTTPS helper that fails during startup may retain a generation-bound
`startup-failure.json` beside its owner configuration. The CLI reports only the
reviewed startup stage and an allowlisted native error code; child output, paths
and application values are omitted. If lease cleanup also fails, the original
acquisition diagnostic remains visible alongside the unconfirmed cleanup status.
This record is diagnostic evidence only: it does not acknowledge retirement or
permit a replacement owner. A missing record (including a helper crash before
publication) leaves the cause unknown. Preserve the retained owner and finalization
records for inspection; do not delete them to force another startup.

When an HTTPS owner refuses an exact lease release, it now attempts a bounded
failure response containing only the release stage and a reviewed native error
code. The client verifies the complete lease identity and rejects extra or
noncanonical protocol data. This response is not a release acknowledgement and
never triggers a retry: transport loss still leaves the outcome unconfirmed.
For example, an observed `graph-verification: provider_busy` would locate the
refusal without exposing native stderr; it would not prove cleanup completed or
permit another owner to start. Preserve the original records while investigating.


---

<!-- Original: docs/reference/native-config-import.md; revision: 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; SHA-256: a91021b91b3a87593fe16979c0e30b131add0c3c67e7dda72e7629c6480b0ac2; URL: https://hack.foo/docs/v5/native/config-import -->
# Read-only native import preview

`hack config import --dry-run --path /exact/project/root --json` previews a
bounded conversion of the active `.hack/hack.config.json` and
`.hack/docker-compose.yml` pair. It does not discover an ancestor project.
The JSON report contains source document names, field pointers, line/column
positions, mapping status and fixed refusal codes. Human output uses the same
information. Neither output includes authored values, compiler plans or hashes.
`--dry-run` is required; adoption and draft export are unavailable.

A complete preview means every authored field belongs to the supported subset
and the resulting private candidate passes the matching native compiler in memory.
It does not write `hack.project.json`, change active input selection, register
projects, read managed environment values or keys, or inspect/change engine
resources. Any refusal discards the private candidate; no partial conversion is
reported as successful.

An unchanged project that uses an external network (one that the
`HACK_NATIVE_ADAPTATION` selection does not list in `isolatedNetworks`), a reserved
ownership label, a build outside the basic form below, or a non-arm64 platform
stays on the Compose backend in v5. Native `up` refuses those features before any work, and
`hack doctor` reports them; see
[Compose projects that stay on the Compose backend](/docs/v5/native/full-reference#compose-projects-that-stay-on-the-compose-backend).
That check uses the same basic build mapping as this preview.

## Supported subset

| Legacy input | Native mapping |
| --- | --- |
| Required explicit canonical `name` | The same project name; no directory-name fallback |
| String `$schema` | Editor metadata; no runtime field |
| `defaultEnvConfig`, `default_env_config`, `env.defaultOverlay`, `env.default_overlay` | `environment.default_overlay`; all present aliases must select the same overlay |
| Boolean `worktree.auto_branch` / `autoBranch` and `inherit_local` / `inheritLocal` | The equivalent native worktree policy; conflicting aliases refuse |
| Optional Compose `name` | Must exactly equal the explicit project name |
| Image-only services and explicit completion jobs | The same logical workload names and image strings |
| Basic build-only services and explicit completion jobs | String context or a closed object containing `context`, `dockerfile`, `target`; legacy `.hack` context rebased to the checkout root |
| Array or bounded string `command` and `entrypoint` | Explicit native exec arrays; Compose string words are split without an implicit shell, complete `$$` pairs become literal `$` arguments, and an empty entrypoint remains explicit |
| `working_dir`, boolean `init` | `working_directory`, `init` |
| `pull_policy` of `always`, `never`, `missing` for images, or `build` for builds | The same authored acquisition intent; omitted policy stays omitted |
| Service `restart` of `no`, `always`, `unless-stopped`, `on-failure[:N]` | Native restart intent; retry counts must fit a positive u32; jobs accept only explicit `no` or omission |
| String `stop_signal`, `stop_grace_period` | Native shutdown signal/grace, validated by the compiler |
| String environment map or `KEY=value` list | Native `default` bindings, preserving managed-value precedence and empty values |
| One explicitly declared project-owned Compose `bridge` network with boolean `internal`, attached explicitly to every workload and optional static aliases | The same logical native bridge policy and per-workload aliases; no implicit default attachment or physical-ID claim |
| Nonempty canonical `profiles` lists | Native workload selection and the union of declared profiles |
| Short `depends_on` lists, or long edges with `service_started` / `service_healthy` | Native service `started` / `ready` edges; `required` must be absent/true and `restart` absent/false |
| Long edges with `service_completed_successfully` | The referenced declaration becomes a native job; the edge becomes `job` / `completed` |
| Exact `hack.service.one-shot: "true"` label map or singleton `hack.service.one-shot=true` label list | An explicit standalone native job; the known marker is consumed as semantic provenance, without adding resource labels |
| `healthcheck.test: [CMD, executable, ...args]` with authored positive `interval`, `timeout`, `retries` | Native exec readiness; complete argument dollar pairs decode once, and the compiler validates timings |
| File-only top-level `configs` and `secrets` | Checkout-relative native file declarations, rebased from the known `.hack` Compose source directory |
| Explicit service `configs` and `secrets` grants | Native read-only file mounts with canonical Linux targets and normalized `0444` permission intent |

Names in this slice use lowercase letters, digits and single hyphen separators.
Overlay aliases additionally accept ASCII case, underscores and spaces and apply
the existing overlay-name normalization; path-like or punctuation-based spellings
refuse. All alias spellings and their original source positions remain in the
report. In command and entrypoint arrays or strings, every dollar must be part
of a complete `$$` pair; the report marks decoded or split fields as normalized
while retaining the raw authored source. String words support ASCII space,
tab, CR and LF separators, single or double quoting, adjacent quoted segments,
empty quoted arguments and backslash escapes. They never imply `/bin/sh -c`;
an explicit shell executable and `-c` argument remain ordinary exec words.
Unquoted shell control characters, unmatched quotes, dangling escapes, a first
empty executable word, single or odd dollars, `$VAR` and `${VAR}` refuse.
Omitted or explicit null command/entrypoint keeps Compose's image-default behavior. Empty or
whitespace-only entrypoint explicitly clears the image entrypoint; empty or
whitespace-only command refuses because the native command model cannot express
Compose's explicit empty override. Outside argv and basic build paths, dollars in runtime strings and NUL in runtime values refuse
rather than inheriting ambient environment. Environment list entries without `=`, duplicate
names, nulls and non-string values refuse. Each environment entry is reviewed on its own:
only an interpolated or otherwise unsupported entry is refused, at its own pointer such as
`/services/web/environment/FROM_ENV` or `/services/web/environment/1`, while literal
siblings in the same map or list stay mapped. Any refused entry still makes the whole
preview incomplete.

Every unknown field remains a refusal, including fields in inactive profiles.
Advanced builds, volumes/bind mounts, other network shapes, ports, other labels,
routes, host/lifecycle settings, `env_file`, deployment options and extensions
are outside the first slice. They cannot be silently omitted from a complete
conversion.

The network mapping accepts one or exactly two named non-default, non-ingress
bridges. Each requires explicit `internal: true` or `false` and optional
`driver: bridge`; every workload, including inactive jobs, must explicitly
attach to one or both declared bridges. Each declared bridge must be used. Unknown
network/attachment fields, custom physical names, external networks, IPAM,
driver options, implicit or mixed default attachments, and duplicate or
workload-colliding aliases refuse. Import preview preserves the authored
logical topology; it does not claim that a running Compose bridge belongs to
the project. The separate adoption owner must prove the existing bridge and
container endpoints before a retained-ID transition.

Completion roles are discovered before declarations are converted, including
inactive declarations. A completed target or explicit one-shot keeps its authored
argv, entrypoint, environment and other supported fields under `jobs`; original
field positions remain in the report with native job targets. Unmarked installers,
command text, service names, `restart: no` and observed exit zero do not infer jobs.
The same target cannot also satisfy a started or healthy service edge. Undeclared
completed targets, optional or restart-propagating edges, mixed or noncanonical
one-shot labels, job health checks and non-`no` job restart policies refuse. Omitted
job restart stays omitted; no native default is invented. Supported profile fields
remain authored selection, and unsupported fields in inactive jobs still refuse.

This is pure conversion, not retained-job adoption. Versions 1–5 do not qualify job
ordering, completion, recovery or replay. The distinct [version-7 retained owner](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/native-compose-adoption.md)
qualifies only its closed static/default-network family. A job import preview does not upgrade a
receipt, launch or recreate a container, transfer ownership, or qualify application
migration. Two-worktree data acceptance remains a separate live gate.

The service-only adoption baseline continues to refuse jobs. Only the version-7
owner selects its distinct completed-job baseline after verifying the closed
static family. Symbolic conversion is not an ownership grant.

Pure preview can preserve a completed job's explicit attachment and aliases on
these owned bridges. Retained storage/adoption still refuses custom-network
job combinations: neither the job nor network receipt proves their combined
ordering, endpoint ownership, recovery or replay.

Health intervals and timeouts must use integer `ms`, `s`, `m` or `h` durations
that fit the compiler's positive u32 milliseconds. Missing or zero timings,
`CMD-SHELL`, string probes, `NONE`, disabled probes, `start_period` and
`start_interval` refuse: image health settings and image `SHELL` are not acquired,
and the native contract cannot express all of those options. Explicit `disable:
false` is the default enabled setting. Optional edges and restart propagation
refuse. Completed-job conversion is supported as described above; retained-job
execution has its own version and family boundary. Unknown HTTP/TCP fields also refuse.
The compiler rejects missing, cyclic or inactive dependency targets and ready
edges whose target has no explicit readiness. Refusals include inactive profiles.

## File declarations and grants

Only own `{file: string}` declarations are supported, including unused declarations.
Relative paths are lexically rebased from `.hack` into the checkout; `../settings`
becomes `settings`. Absolute paths, checkout escapes and unsupported source options
refuse. No referenced material is read or inspected. Complete dollar pairs in file
paths and grant targets decode once; ambient interpolation refuses.

Declaring a file does not grant access. Explicit short or long workload grants map
to read-only mounts. A short config targets `/<name>`; a short secret targets
`/run/secrets/<name>`. Long grants require `source` and may select a canonical
absolute target; a secret basename target is placed under `/run/secrets`.
Omitted mode, quoted `"0444"` and numeric `292` normalize to `"0444"`.
UID/GID, alternate modes and unknown grant fields refuse, including inactive
services and converted jobs. Bare YAML `0444` becomes unsupported decimal `444`; explicit `0o444`
retains the parser's compatibility refusal. Quoted `"0444"` and numeric `292`
are supported. The compiler validates source references and target overlaps.
For converted jobs, grant provenance retains the original `/services/<name>`
source positions and points to the published `/jobs/<name>/mounts` fields.
File recognition remains preview-only; combining a job or build with a file
grant does not authorize retained adoption of any of those feature families.

These are Linux declaration defaults. Compose's file-backed binds can ignore
permission options, so this preview does not establish original file modes or
runtime binding equivalence. The ordinary retained-adoption baseline still refuses
file declarations and grants before private values, keys or engine probes. The
separate [retained-file owner](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/native-compose-adoption.md) requires original bind
and material proof for its closed config-0444 and protected secret-0400/0600 subset;
preview completeness does not provide that authority or qualify ordinary secret
permissions. See Docker's
[config grants](https://docs.docker.com/reference/compose-file/services/#configs)
and [secret grants](https://docs.docker.com/reference/compose-file/services/#secrets).

## Pure basic build preview

The [Compose build contract](https://docs.docker.com/reference/compose-file/build/)
allows a short context string or an object. This preview accepts only relative
local context paths and optional relative `dockerfile` and canonical `target`.
It converts the raw `.hack/docker-compose.yml` declaration: legacy context paths
start at `.hack/`, while native contexts start at the checkout root. Thus
`build: ..` maps to native context `.`, `build: .` maps to `.hack`, and
`context: ../app` maps to `app`. An object without `context` uses the legacy
default directory `.hack`. An omitted Dockerfile remains omitted for the native
compiler's `Dockerfile` default; an explicit Dockerfile stays relative to the
build context. Lexical path normalization and complete `$$` pair decoding do not
read files or evaluate environment variables. Source pointers and positions
remain those of the raw declaration, and the report contains no path values.
For a converted job, native build target pointers use `/jobs/<name>/build` while
source pointers retain the original `/services/<name>/build` declaration.

Context paths escaping the checkout root, Dockerfiles escaping their context,
absolute/home-relative/remote paths, ambiguous dollar expressions and malformed
fields refuse. Build arguments, cache options, SSH, secrets, labels, network,
inline Dockerfiles, platforms, tags and every other build option remain refused,
even when empty or in an inactive profile. `build.pull` is unsupported; the
workload's `pull_policy: build` is a separate supported acquisition requirement.
Combined `build` and `image` refuse because the native model requires exactly one
source. Invalid builds cannot fall back to an authored image or a default policy.

Long directory binds with explicit `bind.create_host_path: false` can map to
native source mounts. Literal relative sources are resolved from the legacy
`.hack/docker-compose.yml` directory, then expressed relative to the checkout;
`../src` becomes `src`, and `..` becomes `.`. Read-only and read-write access are
preserved. Absolute paths, checkout escapes, interpolation, propagation,
consistency and SELinux options refuse. Explicit Git and managed-state source
subdirectories also refuse; an existing whole-checkout bind remains possible.

Short bind syntax has different missing-path behavior: Compose may create a host
directory. It therefore remains refused by general conversion preview. The
separate [retained directory owner](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/native-compose-adoption.md#retained-directory-binds)
can qualify a short bind only after verifying that the exact authored directory
already exists and is mounted by the original container with identical access.
Neither path creates missing directories. Directory/file-grant and other retained
feature intersections remain unqualified.

This expands read-only preview only. The image-only retained baseline remains
closed. A separate [proof-bearing basic-build owner](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/native-compose-adoption.md#retained-basic-builds)
qualifies current included source and exact existing images before adoption; a
complete pure preview never supplies that authority. The mapper runs no Compose
normalization, builder or runtime command, and does not validate Dockerfile
contents, path existence or filesystem identity. The authoritative compiler still
must validate the whole private candidate before a complete CLI preview; actual
build import and adoption acceptance remain open.

The maintained config-only correspondence gate is
`bun scripts/check-native-config-import-build.ts`. Select the prepared matching
sidecar with an absolute `HACK_CONFIG_COMPILER_BINARY` and the installed standalone
Compose plugin with an absolute `HACK_IMPORT_COMPOSE_BINARY`. It compares the
actual normalized Compose projections of the raw legacy and compiled/rendered
native inputs for default context, checkout-root context, nested Dockerfile/stage
and literal dollars, including an inactive profile selected explicitly for the
comparison. Context and lexically resolved Dockerfile paths must match; stage, source and
policy presence must remain exact. These are Compose's serialized config strings,
including its escaped-dollar representation; the comparison does not decode them
again or certify the builder's actual filesystem paths. No builder or engine command is admitted.
Compose receives an isolated empty Docker configuration and a nonexistent engine
socket. The aggregate gate is bounded to 90 seconds with bounded child captures.
An optional fresh absolute `HACK_IMPORT_BUILD_EVIDENCE_DIR` retains private
captures and the result; a failure keeps its temporary evidence and returns
nonzero. The result records matched projections and requires the command's final
zero exit; it cannot independently certify completion after a late write or
cancellation. This proves config correspondence, not build or adoption acceptance.

## Parsing and input boundary

The pinned maintained `yaml` AST parser checks decoded key uniqueness, strict
syntax and source positions. JSON additionally passes strict `JSON.parse` syntax
validation before AST inspection; escaped equivalent JSON keys still refuse.
Exactly one document is required. YAML anchors, aliases, merge keys, explicit tags
and directives refuse. YAML 1.1 compatibility warnings also refuse, so ambiguous
plain scalars such as `on` require explicit quotes. Input bytes, AST nodes and
depth have fixed budgets. Parser diagnostics contain no source excerpts.

Selected files must be bounded readable regular files with one hard link.
Symlinked roots/directories/files, missing or competing authored inputs, invalid
UTF-8 and changed input identities or bytes refuse. Stable descriptor reads and
final rechecks surround compiler validation; they do not lock external editors.
Cancellation stops the owned compiler and returns a fixed redacted error.

Presence of root `.env`, `.hack/.env` or `.hack/hack.local.json` explicitly
refuses this first slice without reading them. Linked worktrees and separate Git
directories use `.git` files; those layouts explicitly refuse, including when
the selected project is nested beneath that Git root. Ordinary `.git` directories
are inspected only for marker type and identity.

The private owner result freezes its report and candidate. The candidate is
non-enumerable and available only through explicit private API access; ordinary
JSON serialization and object spread contain the report alone. Public callers
must never serialize that candidate into logs, receipts or command output.

## Identity and remaining adoption work

Preview preserves the explicit logical project name, service names and supported
authored intent. It does not transfer registry IDs, Compose project/resource
ownership, named volumes, checkout/worktree identity or saved runtime generations.
Existing managed environment files remain untouched; their values are not copied
into the authored candidate.

NC04 adoption remains open. Locked publication, input-family transition, local and
linked-worktree policy, unsupported intent conversion, existing resource ownership,
volume reuse and recovery require separate implementation and acceptance.
A successful preview is neither execution admission nor application acceptance.

The separate private [legacy Compose binding prerequisite](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/native-compose-adoption.md)
can verify qualified existing instance and named-volume identities without changing
configuration or resources. It does not expand this command's conversion subset
or complete the adoption transaction.


---

<!-- Original: docs/reference/native-authored-commands.md; revision: 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; SHA-256: 46a6a60da4baaa3a3bc26a062016e6206fd481cad097e1fd51935f42aca52aa2; URL: https://hack.foo/docs/v5/native/authored-commands -->
# Experimental authored configuration with the native runtime

An explicit `HACK_RUNTIME_BACKEND=native` selection delegates an authored
`.hack/hack.project.json` project to the separate native foreground owner. The
current command slice supports whole-project foreground `up` and `restart`,
owner-mediated `down` and explicit stored-generation `down --recover`, saved-run
`ps`, finite service `logs --no-follow`, noninteractive service `exec` and one-off
service `run` on macOS with an absolute `HACK_NATIVE_BINARY` and private canonical
`HACK_NATIVE_HOME`. It requires
the caller's separately prepared native provider pool and matching runtime binary.
It does not install or select a runtime automatically. An omitted backend continues
to use the [Compose command owner](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/native-compose-commands.md).

This bounded native consumer requires each service's `image` to be an immutable
`sha256:` image **content ID**, such as the `image_id` returned by a successful
[`runtime ensure-image`](/docs/v5/native/full-reference#registry-image-acquisition-without-docker)
acquisition. Keep that acquisition's pinned-reference and archive evidence. A
registry tag or `repository@sha256:manifest-digest` is not the content ID. The
native planner (`graph native plan` and `frontend-plan`) refuses it with the same
closed `native_graph_admission` code that execution uses, so `up` fails at its
`native-plan` stage before it reserves a startup intent. `config validate` reports the
same refusal when `HACK_RUNTIME_BACKEND=native` is set; without it, validation stays
backend-neutral because Compose runs tags and digests. Do not substitute a mutable
image or bypass the image identity guard.

```sh
HACK_RUNTIME_BACKEND=native \
HACK_NATIVE_BINARY=/absolute/candidate/hack-native \
HACK_NATIVE_HOME=/absolute/private/candidate-home \
./dist/hack --path /absolute/project up
```

The native planner admits image workloads, exec readiness, initializer jobs
and dependencies with the ordinary project network and outbound mode. It also
admits one read-only project source mount per selected workload, using the existing
`host-mounted` source mode and root `.`. The provider pool must already contain
the exact explicitly approved unfiltered live project share. That existing
virtiofs share grants the guest writable access to the whole tree; only the
individual workload bind is read-only. This command does not enroll the share or
change pool mounts. Host edits remain visible. A selected
directory allows descendant edits; a selected regular file allows in-place edits
but refuses replacement of its inode. Selected path/ancestor aliases, identity
or permission changes refuse, while exact owned shutdown remains possible after
the host source is moved or deleted and preserves host data.

Writable source mounts, source acquisition, file inputs and routing
remain outside this bounded frontend. The existing
closed two-owned-bridge graph capability keeps its separate receipt and refuses
source/storage intersections. Finite typed host lifecycle hooks use the supervised
frontend owner described below. Unsupported intent must
refuse before managed value resolution and provider work. Early typed input
capability refusals retain `E_NATIVE_PROJECT_UNSUPPORTED` without exposing
compiler diagnostics or creating native source/start/run authority. `--detach`,
`--json` for `up` and `restart`, service subsets and unsupported lifecycle operations except
owner-mediated `down` refuse before input acquisition. `--branch` supplies an explicit native namespace; its omission uses
the canonical project namespace without inferring a Git branch. Profile and env
selection keep their compiler contracts. `--env base` bypasses inherited overlays
with an explicit base selection; omitting `--env` retains the authored/local default.

The separate persistent-storage capability requires the runtime's pinned sibling
witness tool and retains its own ownership and recovery checks. It cannot be combined
with the supervised host-process capability below.

## Support matrix

Every slice requires macOS; any other host refuses before input acquisition. Each
row lists the admitted form and the requests that refuse with
`E_NATIVE_PROJECT_UNSUPPORTED` before managed value resolution, compiler work or
provider contact. A refusal names no option value, path or project detail.

| Command | Supported form | Refuses before input acquisition |
| --- | --- | --- |
| `up` | Whole-project foreground; `--branch`, `--profile` and `--env` (including `--env base`) keep their compiler contracts | `--detach`, `--json`, `--recover`, service subsets, single-service, command, workdir, follow, tail and format options, other unsupported options |
| `down` | Whole-project owner-mediated stop of a ready generation through its live foreground owner or private no-host endpoint | `--json`, `--detach`, `--profile` and `--env` overrides, service subsets including an empty selection, single-service, command, workdir, follow, tail and format options |
| `down --recover` | Explicit retirement of a complete stored generation whose owners are dead, or of a pending startup intent that never reserved runtime state; omit `--profile` | `--json`, `--detach`, explicit empty or named `--profile`, `--env` overrides, service subsets, single-service, command, workdir, follow, tail and format options |
| `ps` | `ps` and `ps --json` for the exact saved project and explicit `--branch` | `--profile`, `--env`, service subsets or a single service, `--recover`, `--detach`, command, workdir, follow, tail and format options |
| `logs` | `logs SERVICE --no-follow` with `--tail` from 1 through 1000 (default 200), plain or `--json` | Follow mode (the default), omitted, multiple or malformed service selection, non-integer or out-of-range `--tail`, pretty format, time and query filters, `--profile`, `--env`, `--recover`, `--detach`, command and workdir options |
| `exec` | `exec SERVICE -- COMMAND ARG...` with closed stdin, no TTY and an optional absolute `--workdir` | Empty command or empty first argument, NUL bytes, more than 256 arguments, an argument over 16 KiB or 64 KiB in total, relative `--workdir`, interactive or TTY input, `--json`, `--profile`, `--env`, service subsets, follow, tail and format options, `--recover`, `--detach` |
| `run` | `run SERVICE -- COMMAND ARG...` through a ready foreground owner, closed stdin, no TTY, optional absolute `--workdir`; member must have no mounts | The `exec` option refusals above; source, persistent-data or private-env mounts refuse before the one-off effect |
| `restart` | Whole-project proven stop followed by fresh foreground `up`; `--branch`, `--profile` and `--env` select the fresh generation | Service subsets, `--json`, `--detach`, `--target`, recovery and other unsupported foreground options; missing or unproven stop prevents startup |

Both backends remain experimental. This table records the refusal boundary of the
current slices; it is not a parity claim against the Compose owner and does not
report installed live acceptance.

## Foreground `up`

Startup shares the configured `HACK_COMPOSE_STARTUP_TIMEOUT_MS` budget across
input preparation and native review, with a native maximum of 300000 milliseconds.
Each startup compiler call is bounded by the time the startup budget has left,
capped at 60 seconds, rather than by a fixed 10-second clock. Compiler calls outside
startup (the down hooks' input check after Ctrl-C or a stop request, and checks after
ready) have no startup budget and take the 60-second cap, so a slow host does not
fail a graceful stop (HACK-1458). A start that fails or is cancelled after host
processes began and before its startup intent exists stops those processes, or ends
the launch it had begun through its own session token, before it returns. A
teardown it cannot prove keeps the host process records retained. If the graph fails
before Ready after reserving the startup intent, host teardown additionally requires
the original producer and readers to settle and the original graph group to be
absent. Startup reacquires unchanged host inputs under the hard-stop signal, then
authenticates an exact Removed receipt and absent resource observations before
stopping the owned host session. A live, foreign, unknown or unreserved receipt,
changed input, or hard cancellation keeps this attempt retained.
Startup refusals identify a fixed owning stage and, when available, a closed
compiler or native error code. They omit arbitrary errors, child output, paths and
values. If startup fails before publishing a receipt and the later retirement
inspection also refuses, the captured native startup code takes precedence over
the inspection code. That preserves the failure's owning boundary; it does not
prove cleanup. Retained bindings and recovery requirements stay in force.
These diagnostics do not grant retry or cleanup authority.

A native consumer can refuse after the startup intent is reserved but before it
reserves any runtime journal, for example when its review changes, the engine
cannot be reached or startup is canceled. (A `repository@sha256:` image used to
reach execution this way; the planner now refuses it first.) Such a run has no receipt, so the
Removed retirement inspection can never succeed. After the consumer process has
settled, startup asks the native runtime to inspect the exact run. Startup retires
the startup intent and its source envelope only when the runtime refuses
`native_graph_unreserved`: the run's journal directory is exactly absent under
private state directories, and no foreground owner is published for the run. The
failure then reports outcome `unreserved` with the original native code, and `ps`
reports `not_started`. Any other inspection result keeps the attempt retained.
Examples include `native_graph_receipt` for damaged or foreign evidence,
`native_graph_foreground` for a published owner, and a stopped runtime. This
applies only to attempts without lifecycle hooks, host processes or a live-stop
owner. A canceled startup that retains nothing (`not-started`, such as Ctrl-C
during preflight, `unreserved`, or confirmed removal) prints a cancellation note
and exits 130; a canceled start that retained evidence still fails.
Readiness requires authenticated current observations and unchanged input before
publication. The foreground owner remains attached until owned shutdown finishes;
Ctrl-C requests that shutdown. Exact durable Removed evidence retires the tagged
native run and startup intent. Unknown, changed or live cleanup retains the attempt
and refuses replay; a missing ready mapping does not authorize a fresh start.

On macOS, `up --detach` and `restart --detach` refuse with `E_USAGE` and the same
one-line message as an image project: native `up` runs in the foreground only, so run
it without `--detach` in its own terminal, use `ps` and `logs` from another terminal,
and press Ctrl-C to stop it.

After native review and before it reserves the startup intent, `up` asks the runtime
for its read-only status. A stopped runtime (any phase other than `running`, or a dead
runtime process) refuses at stage `reservation` with native code `runtime_not_running`.
The CLI reports `E_DOCKER_UNAVAILABLE`: "Native runtime is not running; nothing was
started." No intent is retained, so `ps` keeps reporting `not_started`. An inconclusive
status reply does not refuse. The check is advisory: if the runtime stops after it,
the start fails later and, when its intent was already reserved, keeps that evidence;
the CLI then still reports `E_DOCKER_UNAVAILABLE`, and `ps` reports `pending` until the
retained attempt is inspected.

## Saved-run `ps`

`ps` and `ps --json` issue one authenticated current status request for the exact
saved project and explicit branch selection. Text output lists service, container,
current state and current health. JSON uses the ordinary result envelope with
`data.backend: "native"`, `data.status`, `data.run`, historical `data.phase`, and
`data.items`; each item includes service, container, state, health and exitCode.
Only fresh runtime observations supply state and health. Stored readiness and phase
do not prove that a service is still live.

A project with no saved attempt reports `not_started`; a retained startup intent
without a Ready mapping reports `pending` with no confirmed service rows. `pending`
covers a start that is still in progress and a failed start whose reserved intent was
retained as evidence; Hack does not guess which, because only the owner's cleanup proof
may retire that intent. When no startup is running, `down --recover` can retire the
attempt if it never reserved runtime state (see below). When a
Ready generation is saved but the candidate runtime is stopped (native code
`runtime_not_running`, or the authenticated `native_graph_foreground` control code
with that exact cause), `ps` exits 0 and reports `runtime_not_running` with the
saved `data.run`, a null `data.phase` and no items; text output prints
"Native runtime is not running; no services are running." A dead
owner, uncertain recovery, changed selection, or malformed or mismatched reply
refuses with unconfirmed status. The reader holds and rechecks project, private
directories, saved record identities and the selected executable across its single
bounded request. It does not compile or read authored values, resolve env, run
hooks, start workloads, repair state or perform cleanup. Cancellation waits for the
owned request to settle. Profiles, env overrides, service subsets and other `ps`
options are unsupported. Finite one-off `run` and whole-project `restart` are
described below.

## Owner-mediated `down` and `down --recover`

Ordinary whole-project `down` asks the live foreground owner of a ready generation
to stop. A finite-hook generation uses the private per-run capability described
under host lifecycle hooks below. `down` also supports a ready no-host generation, including
persistent-storage plans. Its private no-host endpoint is issued by the original
held startup admission before public Ready. It asks that same foreground owner to
stop; no host declaration, hook permit, new controller or stored-PID signal is
created. Success requires authenticated Removed, the original child and detached
group's settlement, and exact endpoint/start/Ready/source retirement. Compute
shutdown retains persistent data; this command adds no volume deletion authority.
A missing, changed or dead endpoint refuses. Partial publication or retirement
keeps startup evidence blocked. Legacy no-host version 1 records remain ineligible for dead-owner recovery.
New version 2 records capture the original native child while its foreground
owns it: PID, birth, executable identities, UID, host boot session, process group
and session. Recovery uses two bounded complete process-metadata observations. It refuses
any occupied original PID, including reuse or a zombie, and every live member of
its former group or session. Unknown live membership refuses. Explicit zombie
rows whose identity and state match both observations remain in the result, with
unavailable session membership counted separately. This proves no live members
at the observations; it does not prove the numeric group/session is absent.
It never signals a saved numeric group. The original owner separately publishes
one bound settlement observation only after its captured exit, drain and existing
group-absence check. That observation cannot replace fresh recovery checks.
A live SID lookup race permits an entirely fresh attempt only if a complete
bounded reread positively observes that PID missing. Both earlier observations
and their SID mappings are discarded; two new complete observations must fit the
original monotonic budget, including any further proven disappearance. Disappeared
PIDs remain only as denial facts: any reappearance in a later census or diagnostic
reread refuses. State changes, still-live or unavailable rows, failed rereads and
exhausted budget refuse. No individual row is skipped and no deadline is renewed.

Darwin's [ps state implementation](https://github.com/apple-oss-distributions/adv_cmds/blob/main/ps/print.c)
maps `SZOMB` to `Z`. The [XNU exit path](https://github.com/apple-oss-distributions/xnu/blob/main/bsd/kern/kern_exit.c)
waits active asynchronous I/O and invalidates open files before publishing that
state. Zombie process-group metadata can persist until reap, so unavailable SID
on a stable `Z` row is distinct from unknown live membership. Changed, disappeared
or newly observed zombie identities refuse rather than borrowing stale state.

The existing recovery owner retains its leases and exact Ready/start/source,
native owner and receipt bindings before and after cleanup. It phase-retires only
the admitted endpoint and optional settlement record after authenticated Removed
and null observations. Replaced, malformed, live or unknown evidence stays retained.
Graph4 recovery additionally requires all data enrolled and the exact installed
tool root/helper assertion, matching the native owner; source and topology
families remain separately refused. These source controls do not qualify installed
kill/recover/up or retained SQL behavior.
Portable private-filesystem and stand-in lifecycle controls cover this boundary;
installed Source4 SQL retention through public down/up remains a separate runtime gate.

`down --recover` explicitly retires a complete stored native generation whose
foreground publisher and frontend admission owner are both dead on the same host
boot. New version 4 native publications use the kernel boot-session UUID, which
remains independent of calendar clock correction. Recovery requires the exact stored Ready,
startup intent and private source envelope, and the original guest incarnation.
Live owners, older version 2 dead publications, partial startup, pending writes,
changed files and rebooted guests refuse. Env/profile changes, service subsets and
`--json` are unsupported for this operation. It neither recompiles authored input
nor acquires managed values or starts a provider.
Omit `--profile` to recover the stored generation; explicit empty or named profile
overrides both refuse.

Repeating `down --recover` after confirmed retirement is a read-only no-op,
including when authenticated completed recovery history remains. It does not
contact the native runtime or acquire recovery locks. Incomplete recovery,
pending writes, retained owner records and changed history still select recovery
or refuse; they do not qualify for the no-op.

When the selection has a retained startup intent but no Ready mapping and no
recovery intent, `down --recover` takes a different path. It handles only an
incomplete startup that never reserved runtime state. One example is an attempt
retained by an earlier CLI before this retirement existed. The command first
takes a fresh startup admission. A live or interrupted foreground CLI still holds
that admission, so the command refuses as busy in that case. It also requires that
no Ready mapping, lifecycle-hook owner or live-stop owner exists. It then inspects
the exact run. It retires the start intent and the validated source envelope only
when the native runtime refuses `native_graph_unreserved`. It removes the source
first, so an interrupted retirement keeps the start intent blocking. Any receipt,
any other refusal, or a successful inspection retains every file. This path does
not compile input, acquire values, serve a run or touch guest resources.

The closed version 3 publication and version 1 recovery selector remain supported
with their original calendar boot qualifier; clock drift conservatively refuses
that legacy recovery. New version 4 owners use version 2 UUID selectors. Missing,
malformed or unavailable UUIDs refuse; no old record is migrated or given inferred
session authority. PID birth/executable, peer, inode, gate and run-lock checks remain.

Recovery commits a distinct private intent before calling the Rust cleanup owner.
The original raw selectors and resource inventory remain fixed through retries;
current cleanup phases may advance. Before retiring each frontend file, the owner
inspects the exact native receipt and requires all resources Removed with null
observations. A committed retirement phase alone permits the corresponding file's
expected absence. Pending writes and replacements remain retained refusals. The
recovery lease blocks ordinary startup throughout this work. Completed frontend
history is archived under fresh startup admission before a later generation can
start; incomplete history never permits automatic takeover. Persistent data stays
retained, and no recovery operation reboots the guest or allocates new resources.

Dead recovery lease takeover retains its private directory and commits the exact
next owner file before replacing the old owner. A recorded candidate may be pending
or already published after interruption; both forms must match the saved inode and
bytes before a fresh lease is issued. Separate committed release flags authorize
only the corresponding owner/directory absence. An unrecorded pending candidate
and an interrupted completed-history hardlink archive remain retained refusals;
this operation does not repair arbitrary partial lock or file publications.

The native receipt and source paths are distinct from strict Compose v1 artifacts.
Image-only graph receipts remain v2; source-bearing graph receipts use a closed v3
binding, distinct from the existing foreground publication-owner v3. Ready/control
envelopes remain v2. Dead-owner recovery of source-bearing receipts is not admitted
by the separately qualified image-only recovery path. No native hash substitutes
for a normalized Compose hash. Source and fake-driver
checks do not qualify an installed frontend, a live provider, the full authored
corpus, actual dead-owner recovery or resource overhead; those remain separate gates.

## Whole-project `restart`

`restart` with `HACK_RUNTIME_BACKEND=native` stops the current authored generation
and then starts a fresh foreground generation in one command. The stop half is the
same owner-mediated whole-project `down`: it asks the live foreground owner, or the
private no-host endpoint of a ready no-host generation, to stop and requires
authenticated Removed with exact endpoint/start/Ready/source retirement. Nothing
starts until that proof completes. A missing, changed or dead owner, an uncertain
stop or a cancellation during the stop refuses with `E_LIFECYCLE_FAILED`, restarts
nothing and retains the selected state; a project with no running generation
refuses here, so use `up`. Compute shutdown retains persistent data, and the fresh
generation reuses the same project and `--branch` namespace, so persistent-data
identity is unchanged across the cycle. This command adds no volume deletion,
data migration or dead-owner recovery authority.

The start half is the ordinary foreground `up`. It reacquires input and managed
values, performs a fresh native review and remains attached until owned shutdown.
`--profile` and `--env` (including `--env base`) select the fresh generation exactly
as on `up`; the stopped generation's selection is not reused. Because the start
half is `up`, `host.up.before`, `host.up.after` and `host.processes` run again
exactly as on `up`, after the stopped generation's `host.down.before`,
`host.down.after` and process stop completed. Startup refusals keep the `up`
contract: a fixed owning stage, a closed compiler or native code and
`E_STARTUP_INCOMPLETE`, `E_NATIVE_PROJECT_UNSUPPORTED` or, for a stopped runtime,
`E_DOCKER_UNAVAILABLE`. Retained startup evidence
from an incomplete retirement refuses the fresh start without replay. A Ctrl-C that
arrives after the proven stop and before the fresh start returns 130 with nothing
restarted. Each half uses the configured `HACK_COMPOSE_STARTUP_TIMEOUT_MS` budget
separately; neither renews the other.

Service subsets, `--json`, detached restart, `--target` and the frontend recovery
options refuse with `E_NATIVE_PROJECT_UNSUPPORTED` before input acquisition or any
stop request. Portable stand-in controls cover the stop-then-start ordering,
failed-stop retention and cancellation between the halves; installed live restart
acceptance remains a separate host-serialized gate.

## Finite service logs

An already running authored foreground owner supports `logs SERVICE --no-follow`
on macOS. `--tail` defaults to 200 and accepts integers from 1 through 1000;
`--json` returns separate stdout/stderr strings and a truncation flag. Plain output
preserves those two streams. Follow mode, pretty formatting, time/query filters,
profiles, environment overrides and multiple service selections refuse before any
input or runtime operation. This is a finite log-read capability, not full logs parity.

The read uses the existing authenticated native control socket and exact admitted
service/container, guest boot and run receipt. It refuses a dead/wrong owner,
changed authored project/local/source-envelope files, changed frontend mapping,
resource replacement or a container restart during the read. The live owner keeps
value-free input identity/hash pins; it does not reacquire managed values. Source
mounts and persistent-data bindings retain their existing current ownership checks.

Log tails use the Engine's existing limits: at most 1000 lines, a 4 MiB response
transport bound, and 16 KiB of JSON-encoded text per output stream with explicit
truncation. One 15-second observation budget covers the Engine, source and storage
guest checks, within the existing bounded control reply. Cancellation or incomplete
child/output settlement
withholds the result; it never stops the foreground owner or retries a query. Logs
may contain application values and are returned only to the requesting caller;
they are never journaled or included in refusal diagnostics. A stopped candidate
runtime refuses with `E_DOCKER_UNAVAILABLE` ("Native runtime is not running; no
service logs are available.") and exit 1. Offline controls do
not qualify a live provider or application log behavior.

## Finite service exec

`exec SERVICE -- COMMAND ARG...` sends one command to an already running authored
service through its authenticated foreground owner. Arguments are literal, including
empty arguments, spaces and shell characters. `--workdir` selects an absolute guest
directory; the service's existing environment and user remain in force. Stdin is
closed and no TTY is allocated. Interactive input, TTY control, env/profile overrides,
multiple services and JSON formatting are unsupported. No shell is inserted.

The owner verifies the admitted service, full resource ownership, guest boot, image,
container start generation and current source/data bindings before each exec
transport and after completion. The current input and hook permit remain pinned.
A changed owner, member, source or container restart withholds the result. This does
not start, restart or recover a project and does not acquire managed values.

One 30-second observation budget includes identity proofs and the Engine's existing
single exec create, attached start and completion inspection. Known completion
preserves the command's exit code and binary stdout/stderr, with up to 1 MiB per
stream and an explicit truncation notice. Cancellation or timeout settles the local
request but cannot prove guest command termination. Unknown guest completion
admits no command output and warns that effects may have occurred. Once a validated
completion is being written, cancellation returns 130 and prevents remaining writes;
already-written bytes cannot be retracted. No request is replayed and the foreground
project is not stopped. Inspect the service before
deciding whether another command is appropriate. Offline controls do not qualify
installed native exec or live application behavior.

## Finite one-off service run

`run SERVICE -- COMMAND ARG...` sends one command to the authenticated foreground
owner of a running authored project, which runs it in a fresh one-off container
rather than inside the service's running member. The owner derives the container
from the exact admitted member it inspects: the same immutable image, the member's
effective environment, entrypoint, user and working directory (`--workdir` selects
an absolute guest directory instead), the same dropped capabilities and process
policy, and the member's network namespace, so the command reaches the project's
other services exactly as the member does. The one-off never joins a project
network as its own endpoint, never carries the service alias or canonical member
name, and never registers as the service's member; `ps`, `logs` and `exec`
continue to observe the original member. Arguments are literal, including empty
arguments, spaces and shell characters; no shell is inserted. Stdin is closed and
no TTY is allocated.

The owner verifies the admitted service, full resource ownership, guest boot, image,
container start generation and current source/data bindings before each create,
start, wait, log read and removal transport and after completion. It publishes a
value-free pending record for the one-off before the create effect and discards it
only after the one-off's proven removal. A one-off whose member carries mounts
(live source, persistent data or private environment delivery) refuses before any
effect; its container would otherwise need its own admitted bindings. An omitted
command, `--profile`, `--env`, service subsets, `--json`, detached execution, TTY or
interactive input refuse before input acquisition or any owner request. This does
not start, restart or recover a project and does not acquire managed values.

One 30-second observation budget covers the identity proofs, the create, start and
completion wait, a bounded log read and the forced removal. Known completion
preserves the command's exit code and binary stdout/stderr, with up to 1 MiB per
stream and an explicit truncation notice. A timed-out, interrupted or unproven step
withholds output and keeps the one-off container and its pending record; the next
whole-project `down`, or `down --recover` for a dead owner, removes every recorded
one-off before it stops the canonical members, and a record whose container is
already absent is discarded without effects. A recorded container whose labels do
not match the exact run, review, owner and token is never removed. Cancellation
settles the local request but cannot prove guest completion; once a validated
completion is being written, cancellation returns 130 and prevents remaining writes.
No request is replayed and the foreground project is not stopped. Portable
stand-in and fake-engine controls cover the derivation, record lifecycle and reap
ordering; installed native run and live application behavior remain separate gates.

## Finite host lifecycle hooks

The experimental foreground frontend admits typed `host.up.before`, `host.up.after`,
`host.down.before` and `host.down.after` commands. Every phase and selected host
environment binding is checked before the first hook. Unsupported workload capabilities still refuse; no intent is
stripped to make the graph acceptable. Normal standalone `graph native plan`, `run`
and `serve` continue to refuse host intent. The frontend alone uses an explicit
version 3 private source envelope and immutable finite-hook permit. Existing graph
receipts and source version 2 keep their meanings.

`up.before` runs after pure native capability review. The frontend then reacquires
input and managed environment selection and performs a fresh native review before
starting workloads. Hook selection, project, source/worktree policy and selected
profiles and authored semantic identity must remain identical. Managed bindings are
reacquired without authorizing a changed workload declaration. `up.after` runs after authenticated native readiness;
current readiness and inputs are checked again before publishing frontend readiness.
The original configured startup budget includes both phases. Commands retain ordered
exec/shell, cwd, environment target, unset and inherited-terminal semantics through
the existing supervised shell owner.

For a ready finite-hook generation, ordinary whole-project `down` contacts the live
foreground owner using a private per-run capability. Ctrl-C makes the same stop
request. `down.before` must succeed before native shutdown starts; a failed phase
leaves the supervisor and runtime live and cannot be replayed. A second interrupt
explicitly cancels the finite hook and requests exact native cleanup. `down.after`
runs only after authenticated native Removed and successful `down.before`. Down
hooks have no new arbitrary duration ceiling; the shell owner supervises cancellation
and process-group settlement. A down client timeout does not replay or cancel the
foreground operation. Detached startup and service subsets remain unsupported;
whole-project `restart` issues this same stop request before its fresh start.
Known nonzero `down.after` completion reports failure after retiring the stopped
generation. Unknown completion keeps the frontend bindings and hook intent together;
it cannot silently make a new generation eligible.

A distinct private hook owner records intent before each phase, captured child groups
and known completion after child exit and group absence. Commands, values and raw
errors are never journalled. Unknown completion blocks a new generation. Explicit
dead-owner recovery performs no hooks or credential acquisition: the existing native
owner first proves exact Removed, and only fully completed, unchanged hook records
may retire. An interrupted host phase, pre-ready hook-only attempt or ambiguous child
retains evidence and requires separate resolution; no automatic hook replay or
inferred completion is supplied.

Portable controls and synthetic runtime acceptance are distinct from live provider
acceptance. Full NC05 corpus acceptance is still required.

## Supervised host processes

The native foreground frontend also admits normalized `host.processes` with startup
`up` and exit `stop_on_down`, using the same Hack lifecycle mux controller as the
ordinary CLI. Processes start after successful `up.before` and remain owned through
workload readiness. After exact native Removed, the frontend stops its captured
process groups before `down.after` and retires their owner only after known stop.
Startup keeps the configured startup deadline; a running process has no added
duration ceiling. This slice requires tmux because its existing backend supplies
the captured group identity needed for stop; zellij remains unsupported here.

An explicit private source-version5 permit binds the frontend owner, run, project,
branch, semantic selection and process-owner/ready documents. Ordinary standalone
native graph commands still refuse host intent. Source version3 finite hooks and
native receipt versions2–5 retain their meanings. This capability refuses live-source,
persistent-storage and owned-topology intersections before effects.

Commands, cwd and managed values reach the supervised client through a private
one-use local socket. The mux command contains only the internal client and opaque
socket path; managed values are not placed in argv, mux environment or journals.
Compiler-verified HTTP(S) host-binding references resolve to loopback only for host
context, or to an explicit external hostname. Workload/guest, routed and TCP
references remain unsupported until their delivery owners are integrated.

Dead-owner recovery first proves the exact native Removed result, then uses the
saved complete process metadata and current controller token to stop only the
captured groups. A missing session requires those groups already absent; a PID
alone never authorizes a signal. Changed metadata, foreign tokens or an interrupted
launch without a complete ready/state pair retain evidence and cannot replay the
process or hooks. Portable real-child controls do not qualify the retained Event
Agent's tunnels, guest access or routing; live corpus acceptance remains open.


---

<!-- Original: docs/reference/mcp-tools.md; revision: 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; SHA-256: 7b91c7bfef94096dc7f2ba26d742c6095d90545ea6a9332540f297e50bdb15c7; URL: https://hack.foo/docs/v5/reference/mcp-tools -->
# MCP tool contract

`hack mcp serve` exposes the tools below to MCP clients that have no shell. Each
tool runs one `hack` CLI command as a child process, with the session's captured
working directory and environment, and `HACK_NO_INTERACTIVE=1`. When a shell is
available, run the CLI command directly instead.

This page is the contract for tool names, annotations, inputs, the argv each tool
runs, and result shapes. The log tools have their own page:
[MCP logs contract](/docs/v5/reference/mcp-logs).

## Tools

The annotation class is published in `tools/list`:

- `read-only`: `readOnlyHint: true`. The tool only inspects state.
- `additive`: `readOnlyHint: false`, `destructiveHint: false`. The tool starts
  or restarts local runtime state but does not remove it.
- `destructive`: `readOnlyHint: false`, `destructiveHint: true`. The tool can
  stop, replace or overwrite local state, or run an arbitrary command.

Every tool sets `openWorldHint: false`. Mutating tools set `idempotentHint: false`.

| Tool | Class | CLI command |
| --- | --- | --- |
| `hack.projects.list` | read-only | `hack projects --json` |
| `hack.project.status` | read-only | `hack ps --json` |
| `hack.project.up` | additive | `hack up --detach` |
| `hack.project.down` | destructive | `hack down` |
| `hack.project.restart` | additive | `hack restart` |
| `hack.project.run` | destructive | `hack run -- <service> [cmd...]` |
| `hack.project.logs.snapshot` | read-only | `hack logs --json --no-follow` |
| `hack.project.logs.tail` | read-only | `hack logs --json` |
| `hack.project.open` | read-only | `hack open --json` (never launches a browser) |
| `hack.project.init` | destructive | `hack init --auto` |
| `hack.project.exec` | destructive | `hack exec -- <service> <cmd...>` |
| `hack.project.doctor` | read-only | `hack doctor --json` |
| `hack.project.env.explain` | read-only | `hack env explain --json -- <key>` |
| `hack.project.env.keys` | read-only | `hack env list --json` |
| `hack.project.instances` | read-only | `hack projects --json --project=<name>` |
| `hack.project.target` | read-only | `hack project target --json` (provisional) |
| `hack.project.task.list` | read-only | `hack project task list --json` (provisional; runs nothing) |
| `hack.project.task.inspect` | read-only | `hack project task inspect --json -- <task>` (provisional; runs nothing) |

## Project selection

Project-scoped tools accept at most one of `projectName`, `repoRoot` or `path`.
With none, the session's working directory selects the project.

- `projectName` must name a registered project (`~/.hack/projects.json`).
- `repoRoot` and `path` must exist and lie inside a registered project's repo
  root or project directory.
- With no selection, the working directory must contain a hack project or lie
  inside a registered one.

`hack.project.doctor` passes a named project to the CLI as `--path=<repo root>`,
because `hack doctor` has no `--project` option.

`hack.project.instances` needs a registered project name, because
`hack projects` selects by name only. A path, or the working directory when
nothing is selected, maps to the registered project whose repo root or project
directory contains it. When registrations are nested, the deepest one wins. Two
different registrations at the same root are refused as `ambiguous_project`. A
project that has a `.hack/` directory but no registration is refused; run
`hack projects` or any project command in it to register it.

## Inputs and identifiers

Inputs are validated before any child process starts. Unknown input fields are
dropped, so they never reach the CLI argv.

- `service`, `services`, `profiles`, open `target`, and the env tools' `env` and
  `service` must match `^[A-Za-z0-9][A-Za-z0-9_.-]*$`.
- `branch` must match `^[A-Za-z0-9][A-Za-z0-9_./-]*$`.
- Env `key` must match `^[A-Za-z_][A-Za-z0-9_]*$`. Scoped `service.KEY` syntax is
  not accepted. Use the `service` input for the scope.
- Identifiers are at most 253 characters. None of these patterns can start with
  `-`, so no identifier can be read as an option.
- Numeric limits are positive integers. A value above the ceiling is refused,
  not clamped: `tail` and `maxEvents` up to 10,000, `maxMs` up to 60,000, and
  `timeoutMs` up to 600,000.

Option values are always fused (`--branch=<value>`). Positional values that come
from the caller follow `--`, so the CLI parser ends option parsing before them.

## Results

Every result has the same structured content:

| Field | Meaning |
| --- | --- |
| `ok` | The child exited 0 (for the log tools, see the logs contract) |
| `command` | The argv that ran, or `""` when refused before spawn |
| `exitCode` | The child's exit code (1 for a refusal) |
| `stdout`, `stderr` | Captured child output (withheld for the env tools; `stdout` withheld for instances) |
| `data` | Parsed or projected result, when the tool defines one |
| `outputTruncated` | `true` when output reached the 8 MiB capture limit, or this payload was cut to the result size limit |
| `spawned` | `false` only on a refusal: no child, no audit line |
| `error` | Closed refusal or backend error: `code`, `reason`, `message` |

When `ok` is `false`, the result also has `isError: true`. Output above the
8 MiB capture limit stops the command, and `data` is omitted so that a prefix is
never presented as a complete result. The log tools are the exception, as their
contract describes.

### Result size limit

Every tool's serialized result is limited to 9.5 MiB of UTF-8, measured after
JSON escaping. MCP SDK clients on stdio close the connection when a message passes
10 MiB. The rest of that margin covers the JSON-RPC envelope. The 8 MiB capture
limit cannot do this job, because it counts raw output, and a result repeats that
output and escapes it.

A result within the limit is unchanged. Above it, the server removes data in this
order:

1. `content` text. It becomes JSON of at most 256 KiB with the same shape as
   `structuredContent`, carrying less output and its own `outputTruncated: true`.
   If `structuredContent` now fits, it is complete and has no such flag.
2. For the log tools, `stdout`, then whole events from the end. See the
   [logs contract](/docs/v5/reference/mcp-logs). For other tools, `data`, then the end of `stdout`.
3. The end of `stderr`, past its first 16 KiB, which step 2 cannot take.

A payload that was cut has `outputTruncated: true`, and its `stderr` ends with a
fixed line saying to use the CLI for full output. A cut never splits a code point.
`ok` and `exitCode` still describe the command, so a command that succeeded stays
`ok` with `data` omitted. Run the equivalent CLI command when full output is needed.

### Refusals

A refusal happens before any child process exists. Its `error.reason` is one of
`invalid_arguments`, `conflicting_project_selection`, `invalid_project_name`,
`ambiguous_project`, `project_not_found`, `path_not_found`,
`path_not_registered`, `no_project_context` and `init_path_required`. The code is
`E_USAGE` or `E_PROJECT_NOT_FOUND`. The message is fixed text. It never repeats
caller input or registry values. For `invalid_arguments`, the message names the
rejected input fields, using only the tool's own schema keys.

## `hack.project.exec`

Runs a command in a service container that is already running (`docker compose
exec`). `hack.project.run` starts a new one-off container instead. Exec never
starts a container, and the CLI fails when the service is not running.

- Required: `service` and `cmd`, with at least one entry.
- Optional: project selection, `branch`, `profiles`, `workdir` and `timeoutMs`
  (default 120,000).
- Argv: `hack exec [--project=…|--path=…] [--branch=…] [--profile=…]
  [--workdir=…] -- <service> <cmd...>`. Entries in `cmd` such as `--help` or
  `--branch` reach the container command and are never parsed by hack.
- `data.limits` echoes `{ timeoutMs, outputBytes }`. `outputBytes` is the shared
  8 MiB capture limit.

## `hack.project.doctor`

Runs read-only setup diagnostics: `hack doctor [--path=…] [--branch=…] --json`.
The argv set is closed. `--fix`, `--migrate-env-config`, `--domain-migration`,
`--native-cleanup`, `--native-run-mapping`, browser observations and legacy
rebind acceptance are never passed. The CLI also refuses `--json` together with
`--fix`.

`data` is the CLI's JSON result envelope, with `data.checks`, `data.summary` and
`data.counts`. When any check reports an error, the CLI exits 1, so `ok` is
`false` while `data` still carries the full report.

## `hack.project.env.explain`

Explains one env key without its value:
`hack env explain [--project=…|--path=…] [--env=…] [--service=…] [--target=…]
--json -- <key>`.

- Required: `key`. Optional: project selection, `env` (overlay; `base` or
  `default` selects base layers only), `service` (scope; default `global`) and
  `target` (`host` or `compose`).
- `data` is an allowlisted projection: `key`, `available`, `secret`, `format`,
  `environment`, `requested_scope`, `effective_scope`, `target`,
  `delivered_to`, `source` and `precedence`. Any other field in the CLI output is
  dropped.

## `hack.project.env.keys`

Lists env key names with metadata: `hack env list [--project=…|--path=…]
[--env=…] [--service=…] --json`. `--show-secrets` is never passed, and there is
no input for it.

`data` is `{ format, environment, selected_scope, scopes, keys,
missing_required }`. Each entry in `keys` is `{ key, secret, required, source,
resolved_from, services }`. `secret` is `true` when the CLI reports the key as
`keychain`-backed. Row values, materialized values, storage locations and
warning text are dropped. A row whose key does not match the env key pattern is
dropped whole.

### Value-free output

`hack env list --json` prints plaintext values, and CLI errors can quote env
files. Both env tools therefore withhold the child's output:

- `stdout` is always `""`.
- `stderr` is `""` on success. On failure it is a fixed message that tells you
  to run the same `hack env` command in a terminal.
- `data` carries only the allowlisted fields above. It is `null` when the CLI
  printed no parseable JSON object.

`command` still shows the argv, which contains the key name but no values. The
MCP audit log records the same argv.

## `hack.project.instances`

Lists a registered project's runtime instances: `hack projects --json
--project=<name>`. It reads the project's `runtime` and `branch_runtime`
entries, so it lists only instances that currently have containers, running or
stopped. A configured branch that was never started is not listed.

`data` is `{ project, found, runtime_ok, instances }`. `instances` lists the
default instance first, when it has containers, as `branch: null`. Each branch
instance follows, in CLI order. Each instance is `{ branch, compose_project,
working_dir, services }`, and each service is `{ service, containers, running }`
with container counts. Both counts include lifecycle-process containers, which
the CLI adds to the service with the process name. `stdout` is always `""`: the raw listing can cover other
projects and carries container labels, mounts and networks, which `data` omits.
`stderr` is returned as captured. `found` is `false` when the project is
registered but the CLI listing does not include it.

## `hack.project.target`

Resolves the exact target a command would act on: `hack project target --json
[--project=…] [--path=…] [--branch=…] [--service=…] [--env=…]
[--expect-generation=…]`. The tool, its inputs and the result schema are
provisional; see the [AX target and result contract](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/ax-target-result-contract.md).

- Inputs: `projectName`, `path`, `branch`, `service`, `env` and
  `expectGeneration`, all optional.
- Unlike the other project tools, selection is not resolved by the MCP server.
  `projectName` and `path` are passed through, both of them when both are
  given, so the CLI owns every resolution refusal (for example
  `conflicting_selectors`) and the MCP result matches the CLI exactly.
- `data` is the CLI's JSON envelope, re-validated against the contract, or
  `null` when the output does not match it. A detail-less error is accepted
  only as a parser `E_USAGE` refusal, so an `E_UNEXPECTED` fault message never
  reaches `data`. `stdout` is always `""`, because
  `data` carries the same envelope. `stderr` is returned as captured.
- The command never probes the engine, writes the registry or changes Git.

## `hack.project.task.list` and `hack.project.task.inspect`

List or inspect the reviewed task recipes in the target project's
`.hack/tasks.json`: `hack project task list --json` and `hack project task
inspect --json -- <task>`, with the same `projectName`, `path`, `branch`,
`env` and `expectGeneration` inputs as `hack.project.target` (no `service`;
each recipe names its own). The tools, inputs and schemas are provisional;
see the [AX task catalog contract](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/ax-task-catalog.md).

- `task` (inspect only) must match the task id grammar; a malformed id is
  refused before spawning, as `invalid_arguments` with `spawned: false`.
- Selection is passed through unresolved, so every refusal comes from the
  CLI and matches it exactly.
- `data` is the CLI's JSON envelope, re-validated against the contract, or
  `null` when the output does not match it. A refused recipe never carries
  its argv or text, and a result never carries a recipe the catalog's checks
  would refuse. `stdout` is always `""`.
- Nothing is executed. The results say `authority: "none"` and
  `execution: "unavailable"`; there is no task execution tool.

## Audit log

Every spawned command appends one JSON line to `$HACK_HOME/mcp-audit.log` (by
default `~/.hack/mcp-audit.log`): `ts`, `tool`, `command` and `exit_code`.
Refusals write nothing.


---

<!-- Original: docs/reference/mcp-logs.md; revision: 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; SHA-256: 6c2e21c4931ba9f139d0468edd18b9a1dd14bc6f819e231053e70596b3d05b02; URL: https://hack.foo/docs/v5/reference/mcp-logs -->
# MCP logs contract

This page covers the `hack.project.logs.tail` and `hack.project.logs.snapshot`
MCP tools. Both tools run `hack logs --json` once per call and return the stream
events they collected. When a shell is available, use `hack logs` directly.

## Outcomes

Each call ends in exactly one outcome.

| Outcome | `ok` | `isError` | `data.cutoff` | `error` |
| --- | --- | --- | --- | --- |
| Complete: the backend ended the stream and exited 0 | `true` | absent | `null` | absent |
| Cutoff: the server stopped at one of its bounds | `true` | absent | set | absent |
| Backend failure | `false` | `true` | `null` | `backend_error` |

A cutoff is a success. The collected events are valid. The stream simply
continued past the bound. `data.cutoff` is `{ "bound": ..., "limit": ... }`:

- `events`: `maxEvents` log events were collected (tail only). Only
  `type: "log"` events count. `start`, `heartbeat`, `error` and `end` events
  are returned in `data.events` but do not use up the limit.
- `time`: the collection window ended. For tail this is `maxMs`. For snapshot
  it is the fixed 120 second command timeout.
- `bytes`: stdout plus stderr reached the 8 MiB capture limit.
  `outputTruncated` is `true`, and `data` still carries every event parsed
  before the cut. The cut never splits a UTF-8 code point. A trailing partial
  line can be present in `stdout`, but it is never parsed as an event.

After a cutoff, the server stopped the child process, so `exitCode` is often
non-zero. Use `ok` and `data.cutoff` to read the result, not `exitCode`.
`data.stop_reason` (tail only) keeps its earlier values: `eof`, `max_events`,
`timeout`, `output_limit`, `cancelled` or `interrupted`.

The whole result is also limited to 9.5 MiB, because SDK clients drop the
connection above 10 MiB. See [Result size limit](/docs/v5/reference/mcp-tools#result-size-limit).
Over that limit, `content` becomes a smaller view (below), and `stdout` in
`structuredContent` is cut before any event. Events go next, from the end, always
as whole events. `outputTruncated` is `true` whenever `structuredContent` was
cut. When events were removed from a successful collection:

- `data.cutoff` is `{ "bound": "bytes", "limit": 9961472 }`, replacing a `null`
  or an earlier cutoff. A collection that completed is reported as cut, because
  the result no longer holds all of it.
- `data.count` is the number of events kept.
- `data.stop_reason` still says why collection stopped, so it can be `eof` beside
  a byte cutoff.

A backend failure stays a failure: `ok` is `false`, `error` is unchanged and
`data.cutoff` stays `null`, even if events were removed.

The `content` text is JSON with the same shape as `structuredContent`, in a
256 KiB view. It keeps fewer events, and when it removes events its own
`data.cutoff.limit` is `262144`. A client should read `structuredContent` when it
can.

A backend failure is not a truncated success. It is reported when the stream
contains an `error` event or an `end` event with a reason other than `eof` or
`closed`, or when the child exits non-zero at the end of the stream. The error
is closed: `code` is `E_UNEXPECTED`, `reason` is `backend_error`, and `message`
is fixed text that never repeats backend output, caller input or the query.
Raw `stdout` and `stderr` are still returned, as they are for other tools.

Failure evidence counts only before the server stops the child. A child that
writes `error` or `end` events, or exits non-zero, in response to the server's
own stop signal still produces a cutoff. The byte bound is an exception for
events: every retained byte was written before the child was signalled, and
nothing after the cut is parsed, so an `error` or failing `end` event in the
returned prefix is still a backend failure. For the `events` and `time` bounds,
an `error` event that the backend wrote just before the stop but that the server
read after it is reported as a cutoff. The server cannot tell it apart from an
event written in response to the stop.

## Reconnects and repeated calls

The server keeps no log state between calls. Every call starts a new backend
stream:

- A repeated call does not replay events from an earlier call, and it does not
  continue after the earlier call's last event.
- A cancelled request, or a session that closes mid-call, stops the backend
  process group. The interrupted call's events are not delivered later, to this
  session or to a reconnected one.

To continue a stream approximately, call again with `since` set to the last
event's `ts`. `since` selects the Loki backend and cannot be combined with
`compose`. Expect overlap at the boundary and remove duplicates on the client.

## Container restarts

A restart of the logged container does not change the contract. A tail that
spans the restart still ends in one outcome within its bound. Compose may
reattach to the restarted container from a coarse timestamp, so a tail that
spans the restart can repeat a few lines from before it. A snapshot taken after
the restart holds each line once, in order, and a new tail starts from the
current output.

## Verification

`tests/mcp-logs-contract.test.ts` checks each outcome against a scripted stub
backend. The `mcp-logs-compose` scenario in the optional `docker-e2e` CI job
checks the same outcomes through `hack mcp serve` against a real Compose
project (see `tests/e2e/README.md`). It does not cover the Loki backend or the
native/authored logs path.

## Decision: no handles, cursors or idempotency keys (no-go)

Status: no-go for now (HACK-1134). This decision adds no cursor implementation.

We considered three additions:

- A stream handle, so a later call can attach to a running tail.
- A resume cursor, so a later call can continue after the last returned event.
- An idempotency key, so a retried call returns the same result.

Reasons for no-go:

1. **The backends have no exact cursor.** Hack's compose path accepts only
   `tail`, and `docker compose logs` itself offers only timestamp filters that
   can repeat or skip lines with the same timestamp. The lifecycle log
   companion is a file tail. Loki selects by time range, and its timestamps
   are not unique. A cursor would promise gapless, duplicate-free resume that
   Hack cannot deliver, least of all for the default compose backend.
2. **A handle needs state that does not survive the common reconnect.** A
   stdio MCP client reconnects by starting a new `hack mcp serve` process, so
   in-memory handles are lost. Keeping them on disk under `HACK_HOME` would add
   retained log data, plus ownership, expiry and cleanup rules. Logs can hold
   secrets, so that retention is a risk.
3. **Idempotency adds nothing to a read.** Both tools are read-only and
   annotated `readOnlyHint`. A retry is already safe. It returns current data
   rather than a replay, and that is the documented behavior above.
4. **Bounded calls already cover the need.** Agents call tail with a small
   window, read `data.cutoff`, and call again with `since` when they need more.

Revisit this decision (go) only when all of these are true:

- A backend exposes a stable, monotonic position, such as a daemon-owned log
  index.
- Hack has a daemon-owned buffer with defined retention, ownership and secret
  handling.
- A real agent workflow shows that `since` overlap is not good enough.


---

<!-- Editorial source: docs/versions/v5/index.md; based on 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; URL: https://hack.foo/docs/v5 -->
# Documentation

Hack runs the whole project on your machine: services, environment, secrets,
local HTTPS URLs, startup helpers and logs, all from a small `.hack/` folder
committed with the repository. One command starts a repo. Projects and branches
run side by side without colliding. Nothing is hosted.

v5 is the same CLI and project model as v4 with a new runtime layer underneath.
Docker Compose stays the default backend. The native backend (beta, Apple Silicon
macOS) is opt-in and ships only through the `hack-next` channel, not in the stable
archives or the Homebrew formula. Read [Upgrade from v4](/docs/v5/upgrade) for what
changed and what was retired.

Start with [Install](/docs/v5/install), then [Getting started](/docs/v5/getting-started).

## Understand the project

- [Core concepts](/docs/v5/core): projects, services, instances and local URLs.
- [Environment and secrets](/docs/v5/env): committed configuration with encrypted values.
- [Lifecycle](/docs/v5/lifecycle): hooks, tunnels and host helpers that start with the project.
- [Sessions](/docs/v5/sessions): persistent terminal workspaces per project.

## Do a task

- [Run and inspect a project](/docs/v5/guides/run-project)
- [Choose where a command runs](/docs/v5/guides/run-commands)
- [Work on another branch](/docs/v5/guides/parallel-work)
- [Share environment and secrets](/docs/v5/guides/share-environment)
- [Manage helpers and tunnels](/docs/v5/guides/project-helpers)
- [Use a cloud agent or another host](/docs/v5/guides/cloud-environments)
- [Try the native backend (beta)](/docs/v5/native/full-reference)

## Native backend (beta)

A second way to run the same project on an Apple Silicon Mac. Hack starts its own
small Linux virtual machine instead of using a Docker app. It is opt-in, and Compose
stays the default.

- [Overview](/docs/v5/native/overview): what it is, what it is not, and why to try it.
- [Try it](/docs/v5/native/try-it): install, run one project on native, switch back.
- [What works and known limits](/docs/v5/native/limits)

## Work with an agent

[Agent handoff](/docs/v5/agent-handoff) gives an agent this version's documentation
exports and a short brief. [Agent integrations](/docs/v5/integrations) covers the
optional `hack` plugin, its skills and the separate MCP server.

## Find details or diagnose a problem

Use the [CLI overview](/docs/v5/cli) to choose a command, the
[command reference](/docs/v5/reference/cli) for flags, the
[reference index](/docs/v5/reference/overview) for schemas and agent interfaces, and
[Architecture](/docs/v5/architecture) for the runtime model. When something looks
wrong, run `hack doctor` on the machine running Hack and follow its diagnosis.


---

<!-- Editorial source: docs/versions/v5/install.md; based on 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; URL: https://hack.foo/docs/v5/install -->
# Install

v5 is in prerelease. Stable Hack today is the v4 line, installed with Homebrew or
the release installer. v5 prereleases install beside it through a separate
channel, `hack-next`, so you can try v5 without touching your stable setup. When
5.0.0 ships, the Homebrew formula and release installer move to v5.

## Prerequisites

- A running Docker-compatible engine with Docker Compose for the default backend.
  Check it with `docker info` and `docker compose version`.
- For the native backend (beta): an Apple Silicon Mac. See
  [Native backend (beta)](/docs/v5/native/overview).
- Local DNS and certificate trust are set up once per machine by `hack global
  install` and can ask for native approval.

v5 prerelease bundles are published for Apple Silicon macOS only. Other platforms
stay on stable v4 until 5.0.0.

## Install the current prerelease

Each prerelease has an immutable tag, `v5.0.0-next.N`. Download the bootstrap
from the release you want and run it:

```sh
curl --fail --location --proto '=https' --tlsv1.2 \
  https://github.com/hack-dance/hack/releases/download/v5.0.0-next.12/hack-next-install.sh \
  --output hack-next-install.sh
less hack-next-install.sh
sh hack-next-install.sh
"$HOME/.hack-next/bin/hack-next" --version
```

The bootstrap pins its manager checksum and release version. It installs into
`~/.hack-next`, does not edit your PATH or shell profile, and leaves the stable
`hack` executable and `~/.hack` untouched. Installing does not migrate projects,
start a VM, or change DNS or trust.

Newer prereleases are listed on the [releases page](https://github.com/hack-dance/hack/releases).
Replace the tag in the URL to install a different one. The
[prerelease channel guide](/docs/v5/guides/prereleases) explains versioning, platform
support and the installer in detail.

## Choose a backend

The `hack` CLI runs on Docker Compose unless you select native with
`HACK_RUNTIME_BACKEND=native`. The `hack-next` launcher is the exception: it
exists to test the native candidate, so it selects native by default and
version-private homes. To run the prerelease CLI on Compose against your
ordinary Hack home:

```sh
export HACK_RUNTIME_BACKEND=compose
"$HOME/.hack-next/bin/hack-next" --version
```

The export applies to every later `hack-next` command in that shell. A one-off
`HACK_RUNTIME_BACKEND=compose` prefix selects Compose for that command only; the
next command without it runs native again. Unset the variable before native testing.

On Compose, the prerelease shares project state with stable v4. Do not run both
against the same home at the same time, including their daemons. The
[prerelease install page](/docs/v5/native/install#backends-and-homes) gives
the exact order: stop the stable daemon first, then run the prerelease.

The rest of these docs write `hack` for the v5 CLI. During the prerelease, in the
shell where you exported the backend, run the examples through the launcher:

```sh
hack() { "$HOME/.hack-next/bin/hack-next" "$@"; }
```

This shell function lasts for the session and does not touch your PATH or the
stable `hack` executable in other shells.

## Set up local routing

Once per machine:

```sh
hack global install
```

This configures shared local routing, DNS and certificate trust. Read its prompts.
Continue with [Getting started](/docs/v5/getting-started).


---

<!-- Editorial source: docs/versions/v5/getting-started.md; based on 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; URL: https://hack.foo/docs/v5/getting-started -->
# Getting started

Complete [Install](/docs/v5/install) first. These steps use the default Docker Compose
backend. For the native backend (beta), read
[Try the native backend](/docs/v5/native/try-it) after this page.

## Initialize one project

From a repository you own:

```sh
cd your-project
hack init
```

Review the generated `.hack/` files before starting anything. Keep configuration in
git and keep the secret key and local state out of it. For an existing Compose
project, custom domains or agent-assisted setup, follow
[Project setup](/docs/v5/guides/init-project).

## Start, inspect and stop

```sh
hack up --detach
hack open
hack ps
hack logs --no-follow --tail 50
```

Expected: the declared services start, `open` prints or opens the instance URL,
and `ps` shows service state. Visit the app and run its own health check. A URL or
a running container alone does not prove the app works. If startup fails, read the
error and run `hack doctor` before trying again.

```sh
hack down
```

Stop releases project-owned runtime processes. It does not delete application
data or prune shared caches. [Run and inspect](/docs/v5/guides/run-project) covers
selected services and log history.

## Next

- [Core concepts](/docs/v5/core) explains projects, services and instances.
- [Work on another branch](/docs/v5/guides/parallel-work) runs a second instance beside the first.
- [Agent handoff](/docs/v5/agent-handoff) gives a coding agent the same documentation.


---

<!-- Editorial source: docs/versions/v5/upgrade.md; based on 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; URL: https://hack.foo/docs/v5/upgrade -->
# Upgrade from v4

v5 keeps the v4 project model and commands. Your `.hack/` folder, encrypted env
values, branch instances, lifecycle processes and sessions carry over. What changes
is the runtime layer underneath and the product boundary around it.

## What stays the same

- Docker Compose is still the default backend. `hack up`, `hack down`, `hack
  logs`, `hack env`, `hack host exec` and the rest behave as in v4.
- Project configuration stays in `.hack/`. There is no required config rewrite.
- Shared local routing, `.hack.local` names and certificate trust are unchanged.

## What is new

- **Native backend (beta).** On Apple Silicon macOS, through the `hack-next`
  channel, `HACK_RUNTIME_BACKEND=native` runs explicitly prepared projects without Docker. It supports a bounded command
  subset and is qualified project by project. See
  [Native backend (beta)](/docs/v5/native/overview).
- **A config compiler.** `hack config validate`, `config plan`, `config import
  --dry-run` and `config adopt --dry-run` inspect and preview native configuration
  without starting workloads. See [Native config import](/docs/v5/native/config-import).
- **A separate prerelease channel.** `hack-next` installs immutable `5.0.0-next.N`
  builds beside stable Hack. See [Install](/docs/v5/install).
- **Stricter command parsing.** Hack options go before the command tail. For
  `exec`, `run` and `host exec`, everything after the service or `--` is passed
  through unchanged, so a child's `--json` or `--help` is never read as a Hack flag.
- **Safer env handling.** `hack env hydrate` imports values from a file or stdin
  so secrets never appear in command arguments.

## What was retired

These shipped in earlier major versions and are gone from v5. Use ordinary tools
in their place.

| Retired | Use instead |
| --- | --- |
| Hosted accounts, organizations and teams | Nothing to replace; Hack is local-only |
| The web dashboard | `hack status`, `hack ps`, `hack tui` |
| Hack Tickets | The tracker your project already uses |
| Built-in GitHub and Linear integrations | `git`, `gh` and the tracker's own CLI |
| Automatic agent instruction injection (`hack setup sync`, primer hooks, injected rules) | The opt-in `hack` plugin and `hack agent onboard`; see [Agent integrations](/docs/v5/integrations) |

Remote, gateway, node and dispatch commands and the macOS app remain in the
repository but are unsupported. They are hidden from `hack help` and warn when
invoked.

## Upgrade path

1. Keep stable v4 installed. Install the current prerelease with `hack-next` as
   described in [Install](/docs/v5/install).
2. Run one project on the prerelease using the Compose backend. Stop the stable
   daemon first; v4 and the prerelease must not run against the same home at once.
3. Check the application itself: sign-in, data-backed pages, and anything written
   before a restart that must still be there after it.
4. Only then try the native backend on a disposable project, following
   [Try the native backend](/docs/v5/native/try-it).

When 5.0.0 ships, `brew upgrade hack` or the release installer moves the stable
executable to v5. Projects need no changes to keep running on Compose.


---

<!-- Editorial source: docs/versions/v5/agent-handoff.md; based on 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; URL: https://hack.foo/docs/v5/agent-handoff -->
# Give an agent the right context

Read this version's [LLM index](/v5/llms.txt) or [full corpus](/v5/llms-full.txt).
They contain only the selected version's public docs:

```text
https://hack.foo/v5/llms.txt
https://hack.foo/v5/llms-full.txt
```

A useful brief for your agent:

```text
Read the Hack v5 documentation index and the repository's existing agent policy.
Confirm the Hack executable, version, backend, host, project and intended instance
before changing anything. Inspect running services before starting another
instance. Keep secret values out of chat and command arguments. Verify the
application's own health, not just the CLI exit status. Do not create or modify
agent policy, hooks, rules or skills as a side effect.
```

Agents with shell access can use the CLI directly. `hack agent onboard` prints a
project onboarding prompt for an existing repository; `hack init --with claude|codex`
hands first setup to an agent. Neither writes instruction files into your repository.

[Agent integrations](/docs/v5/integrations) describes the optional `hack` plugin,
whose skills give Codex, Claude Code and Cursor Hack guidance, and the separate
`hack-mcp` plugin for clients without shell access. A plugin installed on your
laptop does not install anything in a cloud agent; see
[Use a cloud agent or another host](/docs/v5/guides/cloud-environments).


---

<!-- Editorial source: docs/versions/v5/guides/run-project.md; based on 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; URL: https://hack.foo/docs/v5/guides/run-project -->
# Run and inspect a project

Use this after [Getting started](/docs/v5/getting-started). The examples use the
default Compose backend.

## Start or restart

```sh
hack up --detach
hack ps
hack open
hack restart web
```

Replace `web` with a declared service. Restarting one service skips the project
lifecycle; read the [command reference](/docs/v5/reference/cli) before relying on
hooks or implicit dependencies. Check the app after a restart.

## Read logs

```sh
hack logs web --no-follow --tail 100
hack logs web
hack logs --loki --since 2h --pretty
```

The first command is a finite snapshot. The second follows live output until
Ctrl-C. Loki history needs the global logging stack running on that host and is
unavailable in slim environments.

## Stop

```sh
hack down
```

Use ordinary shutdown after review. Inspect reported failures rather than issuing
broad cleanup commands. `hack projects prune --project <name>` scopes stale
registry and container cleanup to one project family.

## Native backend

On the native backend, startup is foreground, logs are finite snapshots, and
`--detach`, following logs and some service subsets are not available. See
[Native authored commands](/docs/v5/native/authored-commands) for the
exact supported forms.


---

<!-- Editorial source: docs/versions/v5/guides/run-commands.md; based on 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; URL: https://hack.foo/docs/v5/guides/run-commands -->
# Choose where a command runs

Use `exec` when the target service is already running. Use `run` for a one-off
command in a fresh service container. Use `host exec` for a command that must run
on the current host with the project's resolved environment.

```sh
hack exec web -- node --version
hack run web node --version
hack host exec --scope web -- node --version
```

Replace `web` and the command with your project's actual service and tool. The
three examples report the installed Node version in three execution contexts; they
install nothing. The host path needs Node on the host.

Hack options go before the command tail. After the service name or `--`, everything
is passed through unchanged, so a child's `--json` or `--help` is never read as a
Hack flag.

An agent uses the same model. Ask it to read project instructions, select the
intended host and instance, and inspect state before running data-changing
commands such as migrations, which need their own project-specific checks.

On the native backend, `exec` requires a noninteractive command with closed stdin,
and one-off `run` is bounded. See
[Native authored commands](/docs/v5/native/authored-commands).


---

<!-- Editorial source: docs/versions/v5/guides/parallel-work.md; based on 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; URL: https://hack.foo/docs/v5/guides/parallel-work -->
# Work on another branch

Start from a configured repository. Read
[Worktrees and watchers](/docs/v5/guides/development-runtime-safety) before choosing
shared or isolated files.

```sh
git worktree add ../project-review -b review-work
cd ../project-review
hack up --detach
hack open
hack ps
```

A linked worktree selects a branch instance automatically, named after the branch,
with its own hostnames such as `api.review-work.<project>.hack.local`. A detached
worktree needs an explicit `--branch <name>`. Stop the instance from its owning
checkout when finished.

A separate branch instance does not isolate external databases, shared
bind-mounted files or credentials. Coordinate with people and agents: name the
checkout and branch, assign service and file ownership, and keep one owner for
lifecycle operations against an instance.

On the native backend, branch selection is explicit (`--branch`) and needs the
prepared source share described in [the native reference](/docs/v5/native/full-reference#explicit-writable-development-source).


---

<!-- Editorial source: docs/versions/v5/guides/share-environment.md; based on 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; URL: https://hack.foo/docs/v5/guides/share-environment -->
# Share environment and secrets

Read [Environment and secrets](/docs/v5/env) before choosing a backend. Commit
shareable configuration; keep decryption keys and local overrides separate.

```sh
hack env list
```

Inspect masked values and provenance rather than printing credentials. Scope
values to the intended service/overlay. A linked worktree can inherit the primary
checkout's key; a separate host needs its own approved runtime delivery mechanism.

For encrypted-file storage, possession of the project key grants decryption of
values encrypted with it. Keep an approved backup separate from the repository.
Git access and secret access are different grants. Removing someone's repository
access does not erase keys or values already copied to their machine. Follow the
implemented backend's rotation/revocation procedure; do not assume a universal
`hack` revocation or secret-manager synchronization command exists.

## External secret managers

Use the provider's approved authentication flow and the backend contract in the
matching reference. An illustrative integration reads a single required value
through the provider CLI and sends it directly into a supported hidden/standard-
input path; do not put it in shell arguments, chat, logs or cached files. Exact
write commands and provider support differ by version, so no generic sync command
is implied here. Verify masked metadata, then the app's actual service access.


---

<!-- Editorial source: docs/versions/v5/guides/project-helpers.md; based on 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; URL: https://hack.foo/docs/v5/guides/project-helpers -->
# Manage helpers and tunnels

Use a lifecycle process when the project needs a long-running host helper, such as
a development tunnel or database proxy. Use an up-before hook for a finite setup
or authentication check. This makes the dependency visible in project configuration
instead of relying on an extra terminal tab.

Read [Lifecycle](/docs/v5/lifecycle) for this version's concrete configuration
schema and examples. Keep tool installation separate from login: a cloud SSO login
may require the person to complete its browser flow, and credentials must not be
committed or printed. Check the approved CLI profile and target before starting a
tunnel. A listener existing on a port does not prove it is the correct tunnel.

Declare readiness and ownership using the supported lifecycle contract. Reuse an
existing healthy listener only when the configuration explicitly supports adoption;
shutdown must preserve externally owned processes. Confirm the helper's expected
connection and the app's health after startup. No tunnel, public endpoint or cloud
login is created by reading this guide.


---

<!-- Editorial source: docs/versions/v5/guides/cloud-environments.md; based on 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; URL: https://hack.foo/docs/v5/guides/cloud-environments -->
# Use a cloud agent or another host

Choose the execution environment first:

- **Your local machine:** Hack uses that machine's services, configuration and routing.
- **A cloud coding-agent environment:** install and run Hack inside the provider's VM/container, subject to its runtime, persistence, secret and network rules.
- **An existing remote development host:** Hack runs locally on that host; SSH or an agent is transport, not a built-in Hack fleet controller.
- **An application hosting service:** deploying an app to ECS or an agent runtime is a separate workflow. Hack does not translate project configuration into a deployment there.

Use [Managed environments](/docs/v5/guides/codex-managed-environments) for the
version-specific installation contract. Verify OS/CPU architecture, matching
release asset, project toolchain, Docker daemon and Compose (for that runtime),
bind mounts, network access, task-time credentials and startup after snapshot
restore. Installing a CLI does not supply a Docker daemon or laptop certificate
trust. A macOS native bundle does not install on an Ubuntu cloud VM.

## Named platform compatibility

These are documentation-based assessments, not successful Hack application tests:

| Platform | Supported prerequisite evidence | Remaining verification |
| --- | --- | --- |
| [Cursor cloud agents](https://cursor.com/docs/cloud-agent) | Provider-managed Ubuntu; inspect current environment/Docker documentation | Nested Docker, mounts, startup and task-time secrets for your app |
| [boat.dev](https://boat.dev) | Provider documents Linux VMs, SSH and Docker | Architecture, matching asset, persistence and app readiness |
| [Google Jules](https://jules.google/docs/environment/) | Managed task VM; use its current tool/setup contract | Secret lifetime, daemon availability and app health |
| [Google Cloud Workstations](https://cloud.google.com/workstations/docs/overview) | Managed workstation environment | Actual image, Docker access and persistent paths |
| code.computer | Exact product documentation could not be retrieved during review | Identity and runtime contract unverified; no setup recipe claimed |
| [Amazon ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html) | App container hosting; Fargate is not a privileged Docker host | No verified Hack deployment adapter or full host-runtime integration |
| Personal fleet | Ordinary CLI installation per compatible existing host | Per-host runtime, access, state and routing qualification |

Use provider-approved secret injection at task time. Do not bake project keys into
images or snapshots. Provider setup scripts, build snapshots and service startup
may have different lifetimes. Test the actual application after every fresh task
or resumed host. Remote/gateway/node/dispatch commands are outside the supported
setup described here.


---

<!-- Editorial source: docs/versions/v5/reference/overview.md; based on 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; URL: https://hack.foo/docs/v5/reference/overview -->
# Reference and contracts

Start with the [CLI overview](/docs/v5/cli) to choose a command and the
[generated command reference](/docs/v5/reference/cli) for usage and flags.
[Command and output contracts](/docs/v5/reference/command-contracts) adds the deeper leaf sections,
the public flag inventory and command-specific JSON and log records. A command
being listed is not proof that every backend accepts it; the native backend
supports a bounded subset described in
[Native authored commands](/docs/v5/native/authored-commands).

## Configuration

[Environment and secrets](/docs/v5/env), [Lifecycle](/docs/v5/lifecycle) and
[Architecture](/docs/v5/architecture) explain the project configuration model.
[Configuration fields](/docs/v5/reference/configuration-fields) lists the project JSON, environment
YAML and branch registry fields.

For the native backend, the config compiler publishes a
[project schema](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/packages/config-compiler/generated/hack.project.schema.json)
and a [local override schema](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/packages/config-compiler/generated/hack.local.schema.json).
[Authored schema fields](/docs/v5/reference/authored-schema-fields) lists every declared property.
Schema membership defines document shape; runtime admission is checked separately.
[Native config import](/docs/v5/native/config-import) covers previewing
and adopting existing Compose configuration.

## Agent interfaces

[MCP tools](/docs/v5/reference/mcp-tools) specifies the public tool annotations,
inputs and results of `hack mcp serve`. [MCP logs](/docs/v5/reference/mcp-logs)
explains finite cutoffs and cursor behavior. [MCP fields and results](/docs/v5/reference/mcp-fields)
lists every registered tool's declarations. Internal runtime protocols are not
public MCP APIs. [Agent integrations](/docs/v5/integrations) is the setup path.

## Reports

[Project and env reports](/docs/v5/reference/project-env-reports) details the inventory, metadata,
env-list and restart-wrapper projections. [Diagnostic reports](/docs/v5/reference/diagnostic-reports)
lists the doctor, update and host telemetry types.

## Provenance

Field inventories on this site were audited against the `5.0.0-next.5` source and
carry that label; the generated command reference and runtime guides follow the
pinned release shown in each page's footer. Retired hosted, dashboard and Tickets
surfaces and the unsupported gateway, node and dispatch commands are not public
APIs and are omitted from the published command reference.


---

<!-- Editorial source: docs/versions/v5/reference/configuration-fields.md; based on 28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc; source label: next.5 field audit; URL: https://hack.foo/docs/v5/reference/configuration-fields -->
# Configuration fields

This field inventory was audited against the `5.0.0-next.5` source and has not been requalified against later prereleases. The [generated command reference](/docs/v5/reference/cli) and the pinned runtime guides take precedence where they differ.

This reference describes v5 (next.5). Use [Environment and secrets](/docs/v5/env) and [Lifecycle](/docs/v5/lifecycle) for workflows. Fields below come from the version-pinned schema and readers, not a newer checkout.

The published native launcher accepts a narrower authored project model. This legacy JSON/Compose reference does not establish native feature support. Start with [Native configuration import](/docs/v5/native/config-import) and the authored schemas linked from [Reference](/docs/v5/reference/overview).

## Project JSON

The legacy project file is `.hack/hack.config.json`. Requiredness below is relative to the containing schema object or union variant. An optional parent does not become required because a child is required. Repeated paths describe different variants. The schema requires `name` and `dev_host`; the reader has compatibility fallbacks. A schema constraint is not proof the reader validates it. No schema default is declared for these fields.

| Field | Type | Within this variant | Constraints | Schema location | Evidence |
| --- | --- | --- | --- | --- | --- |
| `$schema` | `string` | Optional | — | `#/properties/$schema` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `name` | `string` | Required | — | `#/properties/name` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `dev_host` | `string` | Required | — | `#/properties/dev_host` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `defaultEnvConfig` | `string` | Optional | — | `#/properties/defaultEnvConfig` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `default_env_config` | `string` | Optional | — | `#/properties/default_env_config` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `logs` | `object` | Optional | `{"additionalProperties":true}` | `#/properties/logs` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `logs.follow_backend` | `string` | Optional | `{"enum":["compose","loki"]}` | `#/properties/logs/properties/follow_backend` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `logs.snapshot_backend` | `string` | Optional | `{"enum":["compose","loki"]}` | `#/properties/logs/properties/snapshot_backend` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `logs.clear_on_down` | `boolean` | Optional | — | `#/properties/logs/properties/clear_on_down` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `logs.retention_period` | `string` | Optional | — | `#/properties/logs/properties/retention_period` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `internal` | `object` | Optional | `{"additionalProperties":true}` | `#/properties/internal` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `internal.dns` | `boolean` | Optional | — | `#/properties/internal/properties/dns` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `internal.tls` | `boolean` | Optional | — | `#/properties/internal/properties/tls` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `internal.extra_hosts` | `object` | Optional | `{"additionalProperties":{"type":"string"}}` | `#/properties/internal/properties/extra_hosts` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `oauth` | `object` | Optional | `{"additionalProperties":true}` | `#/properties/oauth` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `oauth.enabled` | `boolean` | Optional | — | `#/properties/oauth/properties/enabled` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `oauth.tld` | `string` | Optional | — | `#/properties/oauth/properties/tld` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `open` | `object` | Optional | `{"additionalProperties":true}` | `#/properties/open` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `open.prefer` | `string` | Optional | `{"enum":["auto","alias","dev"]}` | `#/properties/open/properties/prefer` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `worktree` | `object` | Optional | `{"additionalProperties":true}` | `#/properties/worktree` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `worktree.auto_branch` | `boolean` | Optional | — | `#/properties/worktree/properties/auto_branch` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `worktree.inherit_local` | `boolean` | Optional | — | `#/properties/worktree/properties/inherit_local` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `sessions` | `object` | Optional | `{"additionalProperties":true}` | `#/properties/sessions` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `sessions.mux` | `string` | Optional | `{"enum":["auto","tmux","zellij","none"]}` | `#/properties/sessions/properties/mux` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `startup` | `array` | Optional | — | `#/properties/startup` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `startup[].name` | `string` | Optional | — | `#/properties/startup/items/anyOf/1/properties/name` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `startup[].run` | `string` | Optional | — | `#/properties/startup/items/anyOf/1/properties/run` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `startup[].command` | `string` | Optional | — | `#/properties/startup/items/anyOf/1/properties/command` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `startup[].cwd` | `string` | Optional | — | `#/properties/startup/items/anyOf/1/properties/cwd` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `startup[].persistent` | `boolean` | Optional | — | `#/properties/startup/items/anyOf/1/properties/persistent` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `startup[].singleton` | `object` | Optional | `{"additionalProperties":false}` | `#/properties/startup/items/anyOf/1/properties/singleton` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `startup[].singleton.ports` | `array` | Required | `{"minItems":1,"uniqueItems":true}` | `#/properties/startup/items/anyOf/1/properties/singleton/properties/ports` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `startup[].singleton.onConflict` | `string` | Optional | `{"enum":["adopt","fail"]}` | `#/properties/startup/items/anyOf/1/properties/singleton/properties/onConflict` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle` | `object` | Optional | `{"additionalProperties":false}` | `#/properties/lifecycle` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.up` | `object` | Optional | `{"additionalProperties":false}` | `#/properties/lifecycle/properties/up` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.up.before` | `array` | Optional | — | `#/properties/lifecycle/properties/up/properties/before` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.up.before[].name` | `string` | Optional | — | `#/properties/lifecycle/properties/up/properties/before/items/anyOf/1/properties/name` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.up.before[].command` | `string` | Required | — | `#/properties/lifecycle/properties/up/properties/before/items/anyOf/1/properties/command` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.up.before[].cwd` | `string` | Optional | — | `#/properties/lifecycle/properties/up/properties/before/items/anyOf/1/properties/cwd` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.up.before[].persistent` | `boolean` | Optional | — | `#/properties/lifecycle/properties/up/properties/before/items/anyOf/1/properties/persistent` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.up.before[].singleton` | `object` | Optional | `{"additionalProperties":false}` | `#/properties/lifecycle/properties/up/properties/before/items/anyOf/1/properties/singleton` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.up.before[].singleton.ports` | `array` | Required | `{"minItems":1,"uniqueItems":true}` | `#/properties/lifecycle/properties/up/properties/before/items/anyOf/1/properties/singleton/properties/ports` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.up.before[].singleton.onConflict` | `string` | Optional | `{"enum":["adopt","fail"]}` | `#/properties/lifecycle/properties/up/properties/before/items/anyOf/1/properties/singleton/properties/onConflict` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.up.after` | `array` | Optional | — | `#/properties/lifecycle/properties/up/properties/after` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.up.after[].name` | `string` | Optional | — | `#/properties/lifecycle/properties/up/properties/after/items/anyOf/1/properties/name` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.up.after[].command` | `string` | Required | — | `#/properties/lifecycle/properties/up/properties/after/items/anyOf/1/properties/command` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.up.after[].cwd` | `string` | Optional | — | `#/properties/lifecycle/properties/up/properties/after/items/anyOf/1/properties/cwd` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.up.after[].persistent` | `boolean` | Optional | — | `#/properties/lifecycle/properties/up/properties/after/items/anyOf/1/properties/persistent` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.up.after[].singleton` | `object` | Optional | `{"additionalProperties":false}` | `#/properties/lifecycle/properties/up/properties/after/items/anyOf/1/properties/singleton` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.up.after[].singleton.ports` | `array` | Required | `{"minItems":1,"uniqueItems":true}` | `#/properties/lifecycle/properties/up/properties/after/items/anyOf/1/properties/singleton/properties/ports` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.up.after[].singleton.onConflict` | `string` | Optional | `{"enum":["adopt","fail"]}` | `#/properties/lifecycle/properties/up/properties/after/items/anyOf/1/properties/singleton/properties/onConflict` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.down` | `object` | Optional | `{"additionalProperties":false}` | `#/properties/lifecycle/properties/down` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.down.before` | `array` | Optional | — | `#/properties/lifecycle/properties/down/properties/before` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.down.before[].name` | `string` | Optional | — | `#/properties/lifecycle/properties/down/properties/before/items/anyOf/1/properties/name` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.down.before[].command` | `string` | Required | — | `#/properties/lifecycle/properties/down/properties/before/items/anyOf/1/properties/command` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.down.before[].cwd` | `string` | Optional | — | `#/properties/lifecycle/properties/down/properties/before/items/anyOf/1/properties/cwd` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.down.before[].persistent` | `boolean` | Optional | — | `#/properties/lifecycle/properties/down/properties/before/items/anyOf/1/properties/persistent` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.down.before[].singleton` | `object` | Optional | `{"additionalProperties":false}` | `#/properties/lifecycle/properties/down/properties/before/items/anyOf/1/properties/singleton` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.down.before[].singleton.ports` | `array` | Required | `{"minItems":1,"uniqueItems":true}` | `#/properties/lifecycle/properties/down/properties/before/items/anyOf/1/properties/singleton/properties/ports` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.down.before[].singleton.onConflict` | `string` | Optional | `{"enum":["adopt","fail"]}` | `#/properties/lifecycle/properties/down/properties/before/items/anyOf/1/properties/singleton/properties/onConflict` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.down.after` | `array` | Optional | — | `#/properties/lifecycle/properties/down/properties/after` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.down.after[].name` | `string` | Optional | — | `#/properties/lifecycle/properties/down/properties/after/items/anyOf/1/properties/name` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.down.after[].command` | `string` | Required | — | `#/properties/lifecycle/properties/down/properties/after/items/anyOf/1/properties/command` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.down.after[].cwd` | `string` | Optional | — | `#/properties/lifecycle/properties/down/properties/after/items/anyOf/1/properties/cwd` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.down.after[].persistent` | `boolean` | Optional | — | `#/properties/lifecycle/properties/down/properties/after/items/anyOf/1/properties/persistent` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.down.after[].singleton` | `object` | Optional | `{"additionalProperties":false}` | `#/properties/lifecycle/properties/down/properties/after/items/anyOf/1/properties/singleton` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.down.after[].singleton.ports` | `array` | Required | `{"minItems":1,"uniqueItems":true}` | `#/properties/lifecycle/properties/down/properties/after/items/anyOf/1/properties/singleton/properties/ports` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.down.after[].singleton.onConflict` | `string` | Optional | `{"enum":["adopt","fail"]}` | `#/properties/lifecycle/properties/down/properties/after/items/anyOf/1/properties/singleton/properties/onConflict` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.processes` | `array` | Optional | — | `#/properties/lifecycle/properties/processes` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.processes[].name` | `string` | Required | — | `#/properties/lifecycle/properties/processes/items/properties/name` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.processes[].command` | `string` | Required | — | `#/properties/lifecycle/properties/processes/items/properties/command` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.processes[].cwd` | `string` | Optional | — | `#/properties/lifecycle/properties/processes/items/properties/cwd` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.processes[].singleton` | `object` | Optional | `{"additionalProperties":false}` | `#/properties/lifecycle/properties/processes/items/properties/singleton` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.processes[].singleton.ports` | `array` | Required | `{"minItems":1,"uniqueItems":true}` | `#/properties/lifecycle/properties/processes/items/properties/singleton/properties/ports` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `lifecycle.processes[].singleton.onConflict` | `string` | Optional | `{"enum":["adopt","fail"]}` | `#/properties/lifecycle/properties/processes/items/properties/singleton/properties/onConflict` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `controlPlane` | `object` | Optional | `{"additionalProperties":true}` | `#/properties/controlPlane` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `controlPlane.tui` | `object` | Optional | `{"additionalProperties":true}` | `#/properties/controlPlane/properties/tui` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `controlPlane.tui.logs` | `object` | Optional | `{"additionalProperties":true}` | `#/properties/controlPlane/properties/tui/properties/logs` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `controlPlane.tui.logs.maxEntries` | `number` | Optional | — | `#/properties/controlPlane/properties/tui/properties/logs/properties/maxEntries` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `controlPlane.tui.logs.maxLines` | `number` | Optional | — | `#/properties/controlPlane/properties/tui/properties/logs/properties/maxLines` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `controlPlane.tui.logs.historyTailStep` | `number` | Optional | — | `#/properties/controlPlane/properties/tui/properties/logs/properties/historyTailStep` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `controlPlane.usage` | `object` | Optional | `{"additionalProperties":true}` | `#/properties/controlPlane/properties/usage` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `controlPlane.usage.watchIntervalMs` | `number` | Optional | — | `#/properties/controlPlane/properties/usage/properties/watchIntervalMs` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `controlPlane.usage.historySize` | `number` | Optional | — | `#/properties/controlPlane/properties/usage/properties/historySize` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `controlPlane.daemon` | `object` | Optional | `{"additionalProperties":true}` | `#/properties/controlPlane/properties/daemon` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |
| `controlPlane.daemon.autoStart` | `boolean` | Optional | — | `#/properties/controlPlane/properties/daemon/properties/autoStart` | [source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/templates.ts#L401) |


### Aliases and selection

Prefer `env.defaultOverlay` for the default overlay. The reader checks `env.defaultOverlay` before `env.default_overlay`; nested env selection precedes legacy `defaultEnvConfig`, which in turn precedes `default_env_config`. These nested fields are read even though the legacy generated schema does not enumerate the `env` object. `worktree.autoBranch` is an alias of `worktree.auto_branch`; a non-null snake_case value is selected before the camelCase alias, then parsed as a boolean. Use one spelling rather than conflicting aliases.

`worktree.inheritLocal` is also read as an alias of `worktree.inherit_local` in this version; the same non-null snake_case precedence applies. It controls eligible local configuration inheritance in the legacy linked-worktree path; it does not make every ignored file or native state inheritable.

### Effective fallbacks

| Field | Fallback | Scope |
| --- | --- | --- |
| `logs.follow_backend` | `"compose"` | consumer fallback, not schema default |
| `logs.snapshot_backend` | `"loki"` | consumer fallback, can fall back or be explicitly forced |
| `startup[].persistent` | `false` | reader/workflow default documented in lifecycle |
| `worktree.auto_branch` | `true` | reader/caller default; linked checkouts only |
| `values.global` | `{}` | parser normalization |
| `environment` | `null` | selected layer environment fallback, not a fixed literal |
| `branchRegistry.branches` | `[]` | missing-file writer default, not proof invalid files are rewritten |


Log preferences are not forced backend selection. Follow mode prefers Compose; snapshots prefer Loki, with consumer-specific fallback. `startup[].persistent` defaults false. Linked-worktree auto-branch selection defaults on in the legacy Compose path; an ordinary checkout remains the base instance. Follow the runtime-specific command guide.

### Hooks and processes

`startup` accepts string shorthand or objects. Startup objects require at least one of `run` or `command`. The reader prefers `run` and drops entries whose selected command is empty. They accept optional `name`/`cwd`, and `persistent` (false by default). `lifecycle.up.before/after` and `lifecycle.down.before/after` are hook arrays; their command-object variants require `command`. Do not transfer the startup-only `run` spelling to every hook. `lifecycle.processes` names long-lived processes and requires `name` and `command`. `singleton.ports` contains unique positive ports; `singleton.onConflict` selects `adopt` or `fail`. Read [Lifecycle](/docs/v5/lifecycle) for working-directory origins, ordering, ownership and failure behavior.

### Scope exclusions

Retained gateway, cluster, supervisor, shared/broker ownership and extension-manager fields are not a supported hosted product API. Legacy secret-backend strategy fields are separate from the managed YAML format below. Neither permissive unknown keys nor a retained schema field makes a backend qualified. Internal daemon, guest and compiler transport types are not public API specifications.

## Managed environment YAML

Files such as `.hack/hack.env.default.yaml` use `values`, not the older JSON `vars` format. Use `hack env` to manage values and [Share environment and secrets](/docs/v5/guides/share-environment) for key handling. Examples must use placeholders, never real secret values.

| Field | Type / requirement |
| --- | --- |
| `version` | literal 1; required |
| `environment` | string; optional; reader falls back to selected file/layer environment |
| `secretsprovider` | literal project_key; required |
| `values` | scope-to-entry map; required object |
| `values.{scope}` | key-to-value map; each scope must be an object; omitted global normalized to {} |
| `values.{scope}.{KEY}` | string \| number \| boolean \| null \| secure object; null accepted by parser and removal during later merge; scalar/secure accepted |
| `values.{scope}.{KEY}.secure` | nonempty string; required for object-valued stored entry; ciphertext format is interpreted elsewhere |


`version: 1`, `secretsprovider: project_key`, and an object `values` are required. Each scope is an object. Scope names match `^[a-z0-9][a-z0-9._-]*$`; keys match `^[A-Z_][A-Z0-9_]*$`. Missing `values.global` becomes an empty object. The environment falls back to the selected layer; an example containing `environment: default` does not establish a universal default. Secure values require a nonempty `secure` string; valid shape alone does not prove decryption or key availability.

This version accepts YAML null as a removal marker.

The parser selects recognized fields; this is not a closed JSON-schema promise. The legacy `hack.env.json` schema describes a different file format.

## Branch registry

`.hack/hack.branches.json` records CLI-managed branch metadata, not live container ownership. Use branch commands rather than hand-editing runtime directories.

| Field | Type | Schema requirement | Constraints |
| --- | --- | --- | --- |
| `$schema` | `string` | Optional | `{}` |
| `version` | `integer` | Required | `{"const":1}` |
| `branches` | `array` | Required | `{}` |
| `branches[].name` | `string` | Required | `{"minLength":1}` |
| `branches[].slug` | `string` | Required | `{"pattern":"^[a-z0-9][a-z0-9-]*$","minLength":1}` |
| `branches[].note` | `string` | Optional | `{}` |
| `branches[].created_at` | `string` | Optional | `{"format":"date-time"}` |
| `branches[].last_used_at` | `string` | Optional | `{"format":"date-time"}` |


`name` is the human/Git branch name; `slug` is its runtime-safe identifier. `note` is an annotation. Usage updates fill a missing `created_at` and refresh `last_used_at`; neither timestamp proves a running instance or permits deleting data. A missing registry starts empty. Invalid JSON is reported. The parser drops invalid entries and narrows recognized fields, so it does not enforce every schema pattern/date format/unknown-key constraint.


---

<!-- Editorial source: docs/versions/v5/reference/mcp-fields.md; based on 28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc; source label: next.5 field audit; URL: https://hack.foo/docs/v5/reference/mcp-fields -->
# MCP fields and results

This field inventory was audited against the `5.0.0-next.5` source and has not been requalified against later prereleases. The [generated command reference](/docs/v5/reference/cli) and the pinned runtime guides take precedence where they differ.

Exact tool inputs for v5 (next.5). Start with [Agent integrations](/docs/v5/integrations) for setup. These are MCP JSON input names, not CLI flag spellings.

Registration does not establish backend compatibility. In particular, the native candidate has a narrower admission contract; a retained Compose tool is not an alternative native lifecycle API. A successful command result is not application health or readiness.

## Input rules

Schema-optional selectors can still have conditional requirements. `hack.project.init` requires `path` or `repoRoot`. Do not provide conflicting selectors. `service` and `services`, `compose` and `loki`, profiles and runtime selection interact through the command handler. The schema does not promise every combination succeeds.

Run timeout defaults to 120000 ms. Init uses a 180000 ms child timeout and exposes no timeout input. Log tail collection defaults to 200 events and 5000 ms. These are handler fallbacks, not schema defaults. An omitted log `tail` can be forwarded to the CLI, which has its own default.

`hack.project.exec` requires a nonempty `cmd` array (at least one entry); run allows cmd to be omitted. Exec also defaults to 120000 ms. Positive-integer limits are tail/maxEvents ≤10000, maxMs ≤60000, timeoutMs ≤600000. Identifier helpers impose a 253-character maximum and distinct service/profile, branch and env-key patterns. The MCP env-key grammar is broader than CLI uppercase keys; later CLI refusal is possible. See [MCP tools](/docs/v5/reference/mcp-tools) for exact validation and typed pre-spawn failures.

## `hack.projects.list`

[source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/mcp/server.ts#L535)

| Input | Presence | Type / validation | Meaning |
| --- | --- | --- | --- |
| `filter` | Optional | `string` | Filter by project name |
| `includeGlobal` | Optional | `boolean` | Include global infra projects |
| `includeUnregistered` | Optional | `boolean` | Include unregistered compose projects |


## `hack.project.status`

[source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/mcp/server.ts#L577)

| Input | Presence | Type / validation | Meaning |
| --- | --- | --- | --- |
| `projectName` | Optional | `string` | Registered project name (from ~/.hack/projects.json) |
| `repoRoot` | Optional | `string` | Repo root path (absolute or relative) |
| `path` | Optional | `string` | Path inside a repo (absolute or relative) |
| `branch` | Optional | `string; identifier rules` | See identifier and input rules. |
| `profiles` | Optional | `string; identifier rules` | Compose profile names |


## `hack.project.up`

[source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/mcp/server.ts#L619)

| Input | Presence | Type / validation | Meaning |
| --- | --- | --- | --- |
| `projectName` | Optional | `string` | Registered project name (from ~/.hack/projects.json) |
| `repoRoot` | Optional | `string` | Repo root path (absolute or relative) |
| `path` | Optional | `string` | Path inside a repo (absolute or relative) |
| `branch` | Optional | `string; identifier rules` | See identifier and input rules. |
| `profiles` | Optional | `string; identifier rules` | Compose profile names |


## `hack.project.down`

[source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/mcp/server.ts#L658)

| Input | Presence | Type / validation | Meaning |
| --- | --- | --- | --- |
| `projectName` | Optional | `string` | Registered project name (from ~/.hack/projects.json) |
| `repoRoot` | Optional | `string` | Repo root path (absolute or relative) |
| `path` | Optional | `string` | Path inside a repo (absolute or relative) |
| `branch` | Optional | `string; identifier rules` | See identifier and input rules. |
| `profiles` | Optional | `string; identifier rules` | Compose profile names |


## `hack.project.restart`

[source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/mcp/server.ts#L696)

| Input | Presence | Type / validation | Meaning |
| --- | --- | --- | --- |
| `projectName` | Optional | `string` | Registered project name (from ~/.hack/projects.json) |
| `repoRoot` | Optional | `string` | Repo root path (absolute or relative) |
| `path` | Optional | `string` | Path inside a repo (absolute or relative) |
| `branch` | Optional | `string; identifier rules` | See identifier and input rules. |
| `profiles` | Optional | `string; identifier rules` | Compose profile names |


## `hack.project.run`

[source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/mcp/server.ts#L734)

| Input | Presence | Type / validation | Meaning |
| --- | --- | --- | --- |
| `projectName` | Optional | `string` | Registered project name (from ~/.hack/projects.json) |
| `repoRoot` | Optional | `string` | Repo root path (absolute or relative) |
| `path` | Optional | `string` | Path inside a repo (absolute or relative) |
| `branch` | Optional | `string; identifier rules` | See identifier and input rules. |
| `profiles` | Optional | `string; identifier rules` | Compose profile names |
| `service` | Required | `string; identifier rules` | See identifier and input rules. |
| `cmd` | Optional | `string[]` | Command arguments |
| `workdir` | Optional | `string` | Working directory inside container |
| `timeoutMs` | Optional | `positive integer; ceiling in input rules` | See identifier and input rules. |


Tool-specific emitted data fields:

| Field | Type | Presence |
| --- | --- | --- |
| `data.limits` | `object` | Present in source shape |
| `data.limits.timeoutMs` | `number` | Present in source shape |


## `hack.project.logs.snapshot`

[source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/mcp/server.ts#L785)

| Input | Presence | Type / validation | Meaning |
| --- | --- | --- | --- |
| `projectName` | Optional | `string` | Registered project name (from ~/.hack/projects.json) |
| `repoRoot` | Optional | `string` | Repo root path (absolute or relative) |
| `path` | Optional | `string` | Path inside a repo (absolute or relative) |
| `branch` | Optional | `string; identifier rules` | See identifier and input rules. |
| `profiles` | Optional | `string; identifier rules` | Compose profile names |
| `service` | Optional | `string; identifier rules` | See identifier and input rules. |
| `services` | Optional | `string; identifier rules` | Multiple service names |
| `query` | Optional | `string` | Raw LogQL selector/query |
| `loki` | Optional | `boolean` | Force Loki backend |
| `compose` | Optional | `boolean` | Force docker compose backend |
| `tail` | Optional | `positive integer; ceiling in input rules` | See identifier and input rules. |
| `since` | Optional | `string` | Start time (RFC3339 or duration) |
| `until` | Optional | `string` | End time (RFC3339 or duration) |


Tool-specific emitted data fields:

| Field | Type | Presence |
| --- | --- | --- |
| `data.events` | `LogStreamEvent[]` | Present in source shape |
| `data.count` | `number` | Present in source shape |
| `data.cutoff` | `null or {bound, limit}` | Present in source shape |
| `data.limits` | `object` | Present in source shape |
| `data.limits.tail` | `number or null` | Present in source shape |


## `hack.project.logs.tail`

[source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/mcp/server.ts#L836)

| Input | Presence | Type / validation | Meaning |
| --- | --- | --- | --- |
| `projectName` | Optional | `string` | Registered project name (from ~/.hack/projects.json) |
| `repoRoot` | Optional | `string` | Repo root path (absolute or relative) |
| `path` | Optional | `string` | Path inside a repo (absolute or relative) |
| `branch` | Optional | `string; identifier rules` | See identifier and input rules. |
| `profiles` | Optional | `string; identifier rules` | Compose profile names |
| `service` | Optional | `string; identifier rules` | See identifier and input rules. |
| `services` | Optional | `string; identifier rules` | Multiple service names |
| `query` | Optional | `string` | Raw LogQL selector/query |
| `loki` | Optional | `boolean` | Force Loki backend |
| `compose` | Optional | `boolean` | Force docker compose backend |
| `tail` | Optional | `positive integer; ceiling in input rules` | See identifier and input rules. |
| `since` | Optional | `string` | Start time (RFC3339 or duration) |
| `until` | Optional | `string` | End time (RFC3339 or duration) |
| `maxEvents` | Optional | `positive integer; ceiling in input rules` | See identifier and input rules. |
| `maxMs` | Optional | `positive integer; ceiling in input rules` | See identifier and input rules. |


Tool-specific emitted data fields:

| Field | Type | Presence |
| --- | --- | --- |
| `data.events` | `LogStreamEvent[]` | Present in source shape |
| `data.count` | `number` | Present in source shape |
| `data.cutoff` | `null or {bound, limit}` | Present in source shape |
| `data.stop_reason` | `string (collector stop reason)` | Present in source shape |
| `data.duration_ms` | `number` | Present in source shape |
| `data.limits` | `object` | Present in source shape |
| `data.limits.tail` | `number or null` | Present in source shape |
| `data.limits.maxEvents` | `number` | Present in source shape |
| `data.limits.maxMs` | `number` | Present in source shape |


## `hack.project.open`

[source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/mcp/server.ts#L900)

| Input | Presence | Type / validation | Meaning |
| --- | --- | --- | --- |
| `projectName` | Optional | `string` | Registered project name (from ~/.hack/projects.json) |
| `repoRoot` | Optional | `string` | Repo root path (absolute or relative) |
| `path` | Optional | `string` | Path inside a repo (absolute or relative) |
| `branch` | Optional | `string; identifier rules` | See identifier and input rules. |
| `target` | Optional | `string; identifier rules` | See identifier and input rules. |


## `hack.project.init`

[source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/mcp/server.ts#L942)

| Input | Presence | Type / validation | Meaning |
| --- | --- | --- | --- |
| `projectName` | Optional | `string` | Registered project name (from ~/.hack/projects.json) |
| `repoRoot` | Optional | `string` | Repo root path (absolute or relative) |
| `path` | Optional | `string` | Path inside a repo (absolute or relative) |
| `name` | Optional | `string` | Project slug |
| `devHost` | Optional | `string` | DEV_HOST override |
| `oauth` | Optional | `boolean` | Enable OAuth alias host |
| `oauthTld` | Optional | `string` | OAuth alias TLD |
| `manual` | Optional | `boolean` | Skip discovery and generate a minimal compose |
| `noDiscovery` | Optional | `boolean` | Skip discovery even if available |


## `hack.project.exec`

[source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/mcp/server.ts#L1002)

| Input | Presence | Type / validation | Meaning |
| --- | --- | --- | --- |
| `projectName` | Optional | `string` | Registered project name (from ~/.hack/projects.json) |
| `repoRoot` | Optional | `string` | Repo root path (absolute or relative) |
| `path` | Optional | `string` | Path inside a repo (absolute or relative) |
| `branch` | Optional | `string; identifier rules` | See identifier and input rules. |
| `profiles` | Optional | `string; identifier rules` | Compose profile names |
| `service` | Required | `string; identifier rules` | See identifier and input rules. |
| `cmd` | Required | `string` | Command and arguments (at least one entry) |
| `workdir` | Optional | `string` | Working directory inside container |
| `timeoutMs` | Optional | `positive integer; ceiling in input rules` | See identifier and input rules. |


Tool-specific emitted data fields:

| Field | Type | Presence |
| --- | --- | --- |
| `data.limits` | `object` | Present in source shape |
| `data.limits.timeoutMs` | `number` | Present in source shape |
| `data.limits.outputBytes` | `number` | Present in source shape |


## `hack.project.doctor`

[source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/mcp/server.ts#L1061)

| Input | Presence | Type / validation | Meaning |
| --- | --- | --- | --- |
| `projectName` | Optional | `string` | Registered project name (from ~/.hack/projects.json) |
| `repoRoot` | Optional | `string` | Repo root path (absolute or relative) |
| `path` | Optional | `string` | Path inside a repo (absolute or relative) |
| `branch` | Optional | `string; identifier rules` | See identifier and input rules. |


## `hack.project.env.explain`

[source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/mcp/server.ts#L1096)

| Input | Presence | Type / validation | Meaning |
| --- | --- | --- | --- |
| `projectName` | Optional | `string` | Registered project name (from ~/.hack/projects.json) |
| `repoRoot` | Optional | `string` | Repo root path (absolute or relative) |
| `path` | Optional | `string` | Path inside a repo (absolute or relative) |
| `env` | Optional | `string; identifier rules` | See identifier and input rules. |
| `service` | Optional | `string; identifier rules` | See identifier and input rules. |
| `key` | Required | `string; env-key rules` | See identifier and input rules. |
| `target` | Optional | `"host" or "compose"` | Env view: host (default) or compose |


## `hack.project.env.keys`

[source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/mcp/server.ts#L1141)

| Input | Presence | Type / validation | Meaning |
| --- | --- | --- | --- |
| `projectName` | Optional | `string` | Registered project name (from ~/.hack/projects.json) |
| `repoRoot` | Optional | `string` | Repo root path (absolute or relative) |
| `path` | Optional | `string` | Path inside a repo (absolute or relative) |
| `env` | Optional | `string; identifier rules` | See identifier and input rules. |
| `service` | Optional | `string; identifier rules` | See identifier and input rules. |


## `hack.project.instances`

[source](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/mcp/server.ts#L1179)

| Input | Presence | Type / validation | Meaning |
| --- | --- | --- | --- |
| `projectName` | Optional | `string` | Registered project name (from ~/.hack/projects.json) |
| `repoRoot` | Optional | `string` | Repo root path (absolute or relative) |
| `path` | Optional | `string` | Path inside a repo (absolute or relative) |


## Prompt arguments

`hack-init` is a prompt, separate from `hack.project.init`. Mode defaults to existing-project. Prompt hints do not become init tool inputs.

A supplied `repoRoot` triggers inventory and replaces the mode/projectName/devHost hints.

| Argument | Presence | Declaration |
| --- | --- | --- |
| `arguments.repoRoot` | Optional | `string` |
| `arguments.mode` | Optional | `string` |
| `arguments.projectName` | Optional | `string` |
| `arguments.devHost` | Optional | `string` |


## Common result

The emitted MCP transport subset is `content[]` with `type`/`text`, `structuredContent`, and `isError` on failure. The table describes the common structured payload, not every SDK extension. When present, the error object contains required string code/reason/message fields. Optional `data` is declared unknown; it is not a machine-validated closed nested schema.

| Field | Type | Presence |
| --- | --- | --- |
| `structuredContent.ok` | `boolean` | Required |
| `structuredContent.outputTruncated` | `boolean` | Optional |
| `structuredContent.command` | `string` | Required |
| `structuredContent.exitCode` | `number` | Required |
| `structuredContent.stdout` | `string` | Required |
| `structuredContent.stderr` | `string` | Required |
| `structuredContent.data` | `unknown` | Optional |
| `structuredContent.spawned` | `literal false` | Optional |
| `structuredContent.error` | `object` | Optional |


Up/down/restart/init do not return a typed data status or readiness object. Open returns `data.url` without launching a browser. Status forwards the selected command JSON; a Compose result has project/branch/composeProject/items, and engine-specific item fields are open. Projects list forwards public CLI inventory JSON; consumers must tolerate version/runtime-specific metadata.

Run returns `data.limits.timeoutMs`; exec additionally reports an 8 MiB shared capture budget through `outputBytes`. Snapshot adds events/count/cutoff/limits.tail. Tail adds stop_reason/duration_ms and limits.maxEvents/maxMs. Omitted tail is echoed as null, not the child CLI default. Cutoff is null or `{bound,limit}` with bound events/bytes/time. A deliberate collection cutoff is distinct from backend failure. Tail counts only type:log events against maxEvents; start/heartbeat/error/end do not spend that counter.

### `McpEnvExplainData`

| Field | Type | Presence |
| --- | --- | --- |
| `key` | `string \\| null` | Required; null only if the type includes null |
| `available` | `boolean \\| null` | Required; null only if the type includes null |
| `secret` | `boolean \\| null` | Required; null only if the type includes null |
| `format` | `string \\| null` | Required; null only if the type includes null |
| `environment` | `string \\| null` | Required; null only if the type includes null |
| `requested_scope` | `string \\| null` | Required; null only if the type includes null |
| `effective_scope` | `string \\| null` | Required; null only if the type includes null |
| `target` | `string \\| null` | Required; null only if the type includes null |
| `delivered_to` | `readonly string[] \\| null` | Required; null only if the type includes null |
| `source` | `string \\| null` | Required; null only if the type includes null |
| `precedence` | `readonly string[] \\| null` | Required; null only if the type includes null |


### `McpEnvKeyEntry`

| Field | Type | Presence |
| --- | --- | --- |
| `key` | `string` | Required; null only if the type includes null |
| `secret` | `boolean` | Required; null only if the type includes null |
| `required` | `boolean \\| null` | Required; null only if the type includes null |
| `source` | `string \\| null` | Required; null only if the type includes null |
| `resolved_from` | `string \\| null` | Required; null only if the type includes null |
| `services` | `readonly string[] \\| null` | Required; null only if the type includes null |


### `McpEnvKeysData`

| Field | Type | Presence |
| --- | --- | --- |
| `format` | `string \\| null` | Required; null only if the type includes null |
| `environment` | `string \\| null` | Required; null only if the type includes null |
| `selected_scope` | `string \\| null` | Required; null only if the type includes null |
| `scopes` | `readonly string[] \\| null` | Required; null only if the type includes null |
| `keys` | `readonly McpEnvKeyEntry[]` | Required; null only if the type includes null |
| `missing_required` | `readonly string[]` | Required; null only if the type includes null |


### `McpInstanceService`

| Field | Type | Presence |
| --- | --- | --- |
| `service` | `string` | Required; null only if the type includes null |
| `containers` | `number` | Required; null only if the type includes null |
| `running` | `number` | Required; null only if the type includes null |


### `McpProjectInstance`

| Field | Type | Presence |
| --- | --- | --- |
| `branch` | `string \\| null` | Required; null only if the type includes null |
| `compose_project` | `string \\| null` | Required; null only if the type includes null |
| `working_dir` | `string \\| null` | Required; null only if the type includes null |
| `services` | `readonly McpInstanceService[]` | Required; null only if the type includes null |


### `McpInstancesData`

| Field | Type | Presence |
| --- | --- | --- |
| `project` | `string` | Required; null only if the type includes null |
| `found` | `boolean` | Required; null only if the type includes null |
| `runtime_ok` | `boolean \\| null` | Required; null only if the type includes null |
| `instances` | `readonly McpProjectInstance[]` | Required; null only if the type includes null |


The env projections withhold values, ciphertext and raw backend output. Projection null is different from a missing key. Instances describe discovered containers, not all configured branches. Doctor can return a nested CLI report under `data.data`; specialized engine and diagnostic subobjects remain open and are not exhaustively typed here.

## Log event fields

These are source types, not a closed validator for every parsed JSON line. Event type is start/log/heartbeat/error/end. Labels and fields are application-owned string maps. Do not enumerate application log keys as Hack API fields.

| Field | Type | Presence |
| --- | --- | --- |
| `data.events[].type` | `LogStreamEventType` | Required in declared source type |
| `data.events[].ts` | `string` | Required in declared source type |
| `data.events[].project` | `string` | Optional |
| `data.events[].backend` | `LogStreamBackend` | Optional |
| `data.events[].branch` | `string` | Optional |
| `data.events[].services` | `readonly string[]` | Optional |
| `data.events[].follow` | `boolean` | Optional |
| `data.events[].since` | `string` | Optional |
| `data.events[].until` | `string` | Optional |
| `data.events[].entry` | `LogJsonEntry` | Optional |
| `data.events[].message` | `string` | Optional |
| `data.events[].reason` | `string` | Optional |
| `data.events[].entry.source` | `"compose" \\| "loki"` | Required in declared source type |
| `data.events[].entry.message` | `string` | Required in declared source type |
| `data.events[].entry.raw` | `string` | Required in declared source type |
| `data.events[].entry.stream` | `"stdout" \\| "stderr"` | Optional |
| `data.events[].entry.project` | `string` | Optional |
| `data.events[].entry.service` | `string` | Optional |
| `data.events[].entry.instance` | `string` | Optional |
| `data.events[].entry.labels` | `Record<string, string>` | Optional |
| `data.events[].entry.timestamp` | `string` | Optional |
| `data.events[].entry.timestamp_ns` | `string` | Optional |
| `data.events[].entry.level` | `LogLevel` | Optional |
| `data.events[].entry.fields` | `Record<string, string>` | Optional |


## Contract boundaries

Nested engine/project/diagnostic variants and arbitrary application data remain open. Inspect the pinned public command source when handling a new variant; do not depend on private daemon/guest/compiler protocols. This field reference is source-reviewed and does not claim client-loading or cloud execution qualification.


---

<!-- Editorial source: docs/versions/v5/reference/authored-schema-fields.md; based on 28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc; source label: next.5 field audit; URL: https://hack.foo/docs/v5/reference/authored-schema-fields -->
# Authored schema fields

This field inventory was audited against the `5.0.0-next.5` source and has not been requalified against later prereleases. The [generated command reference](/docs/v5/reference/cli) and the pinned runtime guides take precedence where they differ.

The published next.5 authored schemas describe project and local override documents. They are distinct from [legacy configuration fields](/docs/v5/reference/configuration-fields). See [Native configuration import](/docs/v5/native/config-import) for the admitted import subset and [Authored commands](/docs/v5/native/authored-commands) for semantic validation.

A valid document shape does not establish runtime admission or provider availability. Defaults here are JSON-schema defaults, not promises of a running service. Requiredness is relative to the containing object or union variant: an optional parent remains optional. Dynamic maps are not a closed list of project-defined names. Definition names are authoring types, not internal transport APIs.

## Project document

[Pinned machine schema](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/packages/config-compiler/generated/hack.project.schema.json). Each pointer identifies a field declaration in that schema, including definitions and union variants.

| Field / schema pointer | Type or reference | Required here | Default | Meaning / constraints |
| --- | --- | --- | --- | --- |
| `configs`<br />`/properties/configs` | `{ [name]: FileConfig }` | No | Not declared |  {"additionalProperties":{"$ref":"#/$defs/FileConfig"}} |
| `environment`<br />`/properties/environment` | `EnvironmentSelection` | No | `{}` |  |
| `host`<br />`/properties/host` | `HostConfig` | No | Not declared |  |
| `host_bindings`<br />`/properties/host_bindings` | `{ [name]: HostBindingTarget }; {"propertyNames":{"maxLength":63,"minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","type":"string"}}` | No | Not declared |  {"additionalProperties":{"$ref":"#/$defs/HostBindingTarget"}} |
| `jobs`<br />`/properties/jobs` | `{ [name]: Workload & schema-defined }` | No | `{}` |  {"additionalProperties":{"allOf":[{"$ref":"#/$defs/Workload"},{"properties":{"restart":{"properties":{"kind":{"enum":["no","on-failure"]}}}}}]}} |
| `name`<br />`/properties/name` | `string` | Yes | Not declared |  |
| `networks`<br />`/properties/networks` | `{ [name]: Network }` | No | Not declared |  {"additionalProperties":{"$ref":"#/$defs/Network"}} |
| `open`<br />`/properties/open` | `OpenConfig` | No | Not declared |  |
| `profiles`<br />`/properties/profiles` | `array<string>` | No | `[]` |  |
| `routes`<br />`/properties/routes` | `Routes` | No | Not declared |  |
| `schema_version`<br />`/properties/schema_version` | `integer; {"minimum":1,"maximum":1}` | Yes | Not declared |  {"minimum":1,"maximum":1} |
| `secrets`<br />`/properties/secrets` | `{ [name]: FileSecret }` | No | Not declared |  {"additionalProperties":{"$ref":"#/$defs/FileSecret"}} |
| `services`<br />`/properties/services` | `{ [name]: Workload }` | No | `{}` |  {"additionalProperties":{"$ref":"#/$defs/Workload"}} |
| `source`<br />`/properties/source` | `Source` | No | `{"mode":"host-mounted","root":"."}` |  |
| `storage`<br />`/properties/storage` | `{ [name]: Storage }` | No | `{}` |  {"additionalProperties":{"$ref":"#/$defs/Storage"}} |
| `worktree`<br />`/properties/worktree` | `WorktreePolicy` | No | `{"auto_branch":true,"inherit_local":true}` |  |
| `context`<br />`/$defs/Build/properties/context` | `string` | Yes | Not declared |  |
| `dockerfile`<br />`/$defs/Build/properties/dockerfile` | `string` | No | `"Dockerfile"` |  |
| `target`<br />`/$defs/Build/properties/target` | `string` | No | Not declared |  |
| `exec`<br />`/$defs/Command/anyOf/0/properties/exec` | `array<string>; {"minItems":1}` | Yes | Not declared |  {"minItems":1} |
| `shell`<br />`/$defs/Command/anyOf/1/properties/shell` | `string` | Yes | Not declared |  |
| `condition`<br />`/$defs/Dependency/anyOf/0/properties/condition` | `ServiceCondition` | Yes | Not declared |  |
| `service`<br />`/$defs/Dependency/anyOf/0/properties/service` | `string` | Yes | Not declared |  |
| `condition`<br />`/$defs/Dependency/anyOf/1/properties/condition` | `JobCondition` | Yes | Not declared |  |
| `job`<br />`/$defs/Dependency/anyOf/1/properties/job` | `string` | Yes | Not declared |  |
| `kind`<br />`/$defs/EndpointReference/oneOf/0/properties/kind` | `"route"` | Yes | Not declared |  {"const":"route"} |
| `name`<br />`/$defs/EndpointReference/oneOf/0/properties/name` | `string` | Yes | Not declared |  |
| `kind`<br />`/$defs/EndpointReference/oneOf/1/properties/kind` | `"service"` | Yes | Not declared |  {"const":"service"} |
| `name`<br />`/$defs/EndpointReference/oneOf/1/properties/name` | `string` | Yes | Not declared |  |
| `port`<br />`/$defs/EndpointReference/oneOf/1/properties/port` | `integer; {"minimum":1,"maximum":65535}` | Yes | Not declared |  {"minimum":1,"maximum":65535} |
| `protocol`<br />`/$defs/EndpointReference/oneOf/1/properties/protocol` | `EndpointProtocol` | Yes | Not declared |  |
| `kind`<br />`/$defs/EndpointReference/oneOf/2/properties/kind` | `"host_binding"` | Yes | Not declared |  {"const":"host_binding"} |
| `name`<br />`/$defs/EndpointReference/oneOf/2/properties/name` | `string; {"minLength":1,"maxLength":63,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}` | Yes | Not declared |  {"minLength":1,"maxLength":63,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"} |
| `exec`<br />`/$defs/Entrypoint/anyOf/0/properties/exec` | `array<string>; {"prefixItems":[{"minLength":1,"type":"string"}]}` | Yes | Not declared |  |
| `shell`<br />`/$defs/Entrypoint/anyOf/1/properties/shell` | `string; {"minLength":1}` | Yes | Not declared |  {"minLength":1} |
| `default_overlay`<br />`/$defs/EnvironmentSelection/properties/default_overlay` | `string; {"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}` | No | Not declared |  {"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"} |
| `literal`<br />`/$defs/EnvironmentValue/anyOf/0/properties/literal` | `string` | Yes | Not declared |  |
| `default`<br />`/$defs/EnvironmentValue/anyOf/1/properties/default` | `string` | Yes | Not declared |  |
| `env_ref`<br />`/$defs/EnvironmentValue/anyOf/2/properties/env_ref` | `string; {"pattern":"^[A-Z_][A-Z0-9_]*$"}` | Yes | Not declared |  {"pattern":"^[A-Z_][A-Z0-9_]*$"} |
| `unset`<br />`/$defs/EnvironmentValue/anyOf/3/properties/unset` | `True` | Yes | Not declared |  |
| `endpoint`<br />`/$defs/EnvironmentValue/anyOf/4/properties/endpoint` | `EndpointReference` | Yes | Not declared |  |
| `file`<br />`/$defs/FileConfig/properties/file` | `string` | Yes | Not declared |  |
| `file`<br />`/$defs/FileSecret/anyOf/0/properties/file` | `string` | Yes | Not declared |  |
| `env_ref`<br />`/$defs/FileSecret/anyOf/1/properties/env_ref` | `string` | Yes | Not declared |  |
| `kind`<br />`/$defs/HostBindingTarget/oneOf/0/properties/kind` | `"host"` | Yes | Not declared |  {"const":"host"} |
| `port`<br />`/$defs/HostBindingTarget/oneOf/0/properties/port` | `integer; {"minimum":1,"maximum":65535}` | Yes | Not declared |  {"minimum":1,"maximum":65535} |
| `protocol`<br />`/$defs/HostBindingTarget/oneOf/0/properties/protocol` | `EndpointProtocol` | Yes | Not declared |  |
| `hostname`<br />`/$defs/HostBindingTarget/oneOf/1/properties/hostname` | `string; {"minLength":1,"maxLength":253}` | Yes | Not declared |  {"minLength":1,"maxLength":253} |
| `kind`<br />`/$defs/HostBindingTarget/oneOf/1/properties/kind` | `"external"` | Yes | Not declared |  {"const":"external"} |
| `port`<br />`/$defs/HostBindingTarget/oneOf/1/properties/port` | `integer; {"minimum":1,"maximum":65535}` | Yes | Not declared |  {"minimum":1,"maximum":65535} |
| `protocol`<br />`/$defs/HostBindingTarget/oneOf/1/properties/protocol` | `EndpointProtocol` | Yes | Not declared |  |
| `down`<br />`/$defs/HostConfig/properties/down` | `HostHooks` | No | `{"after":[],"before":[]}` |  |
| `processes`<br />`/$defs/HostConfig/properties/processes` | `{ [name]: HostProcess }` | No | `{}` |  {"additionalProperties":{"$ref":"#/$defs/HostProcess"}} |
| `up`<br />`/$defs/HostConfig/properties/up` | `HostHooks` | No | `{"after":[],"before":[]}` |  |
| `kind`<br />`/$defs/HostEnvTarget/oneOf/0/properties/kind` | `"host"` | Yes | Not declared |  {"const":"host"} |
| `kind`<br />`/$defs/HostEnvTarget/oneOf/1/properties/kind` | `"workload"` | Yes | Not declared |  {"const":"workload"} |
| `name`<br />`/$defs/HostEnvTarget/oneOf/1/properties/name` | `string` | Yes | Not declared |  |
| `command`<br />`/$defs/HostHook/properties/command` | `Command` | Yes | Not declared |  |
| `cwd`<br />`/$defs/HostHook/properties/cwd` | `string` | No | `"."` |  |
| `env_target`<br />`/$defs/HostHook/properties/env_target` | `HostEnvTarget` | No | `{"kind":"host"}` |  |
| `environment`<br />`/$defs/HostHook/properties/environment` | `{ [name]: EnvironmentValue }` | No | `{}` |  {"additionalProperties":{"$ref":"#/$defs/EnvironmentValue"}} |
| `name`<br />`/$defs/HostHook/properties/name` | `string` | Yes | Not declared |  |
| `after`<br />`/$defs/HostHooks/properties/after` | `array<HostHook>` | No | `[]` |  |
| `before`<br />`/$defs/HostHooks/properties/before` | `array<HostHook>` | No | `[]` |  |
| `command`<br />`/$defs/HostProcess/properties/command` | `Command` | Yes | Not declared |  |
| `cwd`<br />`/$defs/HostProcess/properties/cwd` | `string` | No | `"."` |  |
| `env_target`<br />`/$defs/HostProcess/properties/env_target` | `HostEnvTarget` | No | `{"kind":"host"}` |  |
| `environment`<br />`/$defs/HostProcess/properties/environment` | `{ [name]: EnvironmentValue }` | No | `{}` |  {"additionalProperties":{"$ref":"#/$defs/EnvironmentValue"}} |
| `exit`<br />`/$defs/HostProcess/properties/exit` | `HostExit` | No | `"stop_on_down"` |  |
| `singleton`<br />`/$defs/HostProcess/properties/singleton` | `HostSingleton` | No | Not declared |  |
| `startup`<br />`/$defs/HostProcess/properties/startup` | `HostStartup` | No | `"up"` |  |
| `on_conflict`<br />`/$defs/HostSingleton/properties/on_conflict` | `HostConflict` | No | `"fail"` |  |
| `ports`<br />`/$defs/HostSingleton/properties/ports` | `array<integer; {"minimum":1,"maximum":65535}>; {"minItems":1,"uniqueItems":true}` | Yes | Not declared |  {"minItems":1,"uniqueItems":true} |
| `hostname`<br />`/$defs/HttpRoute/properties/hostname` | `string` | Yes | Not declared |  |
| `port`<br />`/$defs/HttpRoute/properties/port` | `integer; {"minimum":1,"maximum":65535}` | Yes | Not declared |  {"minimum":1,"maximum":65535} |
| `protocol`<br />`/$defs/HttpRoute/properties/protocol` | `HttpProtocol` | No | `"http"` |  |
| `service`<br />`/$defs/HttpRoute/properties/service` | `string` | Yes | Not declared |  |
| `access`<br />`/$defs/Mount/anyOf/0/properties/access` | `Access` | Yes | Not declared |  |
| `source`<br />`/$defs/Mount/anyOf/0/properties/source` | `string` | Yes | Not declared |  |
| `target`<br />`/$defs/Mount/anyOf/0/properties/target` | `string` | Yes | Not declared |  |
| `access`<br />`/$defs/Mount/anyOf/1/properties/access` | `Access` | Yes | Not declared |  |
| `storage`<br />`/$defs/Mount/anyOf/1/properties/storage` | `string` | Yes | Not declared |  |
| `target`<br />`/$defs/Mount/anyOf/1/properties/target` | `string` | Yes | Not declared |  |
| `access`<br />`/$defs/Mount/anyOf/2/properties/access` | `Access` | Yes | Not declared |  |
| `config`<br />`/$defs/Mount/anyOf/2/properties/config` | `string` | Yes | Not declared |  |
| `gid`<br />`/$defs/Mount/anyOf/2/properties/gid` | `integer; {"minimum":0}` | No | Not declared |  {"minimum":0} |
| `mode`<br />`/$defs/Mount/anyOf/2/properties/mode` | `string; {"pattern":"^0[0-7]{3}$"}` | No | `"0444"` |  {"pattern":"^0[0-7]{3}$"} |
| `target`<br />`/$defs/Mount/anyOf/2/properties/target` | `string` | Yes | Not declared |  |
| `uid`<br />`/$defs/Mount/anyOf/2/properties/uid` | `integer; {"minimum":0}` | No | Not declared |  {"minimum":0} |
| `access`<br />`/$defs/Mount/anyOf/3/properties/access` | `Access` | Yes | Not declared |  |
| `gid`<br />`/$defs/Mount/anyOf/3/properties/gid` | `integer; {"minimum":0}` | No | Not declared |  {"minimum":0} |
| `mode`<br />`/$defs/Mount/anyOf/3/properties/mode` | `string; {"pattern":"^0[0-7]{3}$"}` | No | `"0444"` |  {"pattern":"^0[0-7]{3}$"} |
| `secret`<br />`/$defs/Mount/anyOf/3/properties/secret` | `string` | Yes | Not declared |  |
| `target`<br />`/$defs/Mount/anyOf/3/properties/target` | `string` | Yes | Not declared |  |
| `uid`<br />`/$defs/Mount/anyOf/3/properties/uid` | `integer; {"minimum":0}` | No | Not declared |  {"minimum":0} |
| `internal`<br />`/$defs/Network/properties/internal` | `boolean` | No | `false` |  |
| `aliases`<br />`/$defs/NetworkAttachment/properties/aliases` | `array<string>` | No | Not declared |  |
| `prefer`<br />`/$defs/OpenConfig/properties/prefer` | `OpenPreference` | No | `"auto"` |  |
| `command`<br />`/$defs/Readiness/oneOf/0/properties/command` | `Command` | Yes | Not declared |  |
| `interval`<br />`/$defs/Readiness/oneOf/0/properties/interval` | `string` | Yes | Not declared |  |
| `kind`<br />`/$defs/Readiness/oneOf/0/properties/kind` | `"exec"` | Yes | Not declared |  {"const":"exec"} |
| `retries`<br />`/$defs/Readiness/oneOf/0/properties/retries` | `integer; {"minimum":1,"maximum":4294967295}` | Yes | Not declared |  {"minimum":1,"maximum":4294967295} |
| `timeout`<br />`/$defs/Readiness/oneOf/0/properties/timeout` | `string` | Yes | Not declared |  |
| `interval`<br />`/$defs/Readiness/oneOf/1/properties/interval` | `string` | Yes | Not declared |  |
| `kind`<br />`/$defs/Readiness/oneOf/1/properties/kind` | `"http"` | Yes | Not declared |  {"const":"http"} |
| `path`<br />`/$defs/Readiness/oneOf/1/properties/path` | `string` | Yes | Not declared |  |
| `port`<br />`/$defs/Readiness/oneOf/1/properties/port` | `integer; {"minimum":1,"maximum":65535}` | Yes | Not declared |  {"minimum":1,"maximum":65535} |
| `retries`<br />`/$defs/Readiness/oneOf/1/properties/retries` | `integer; {"minimum":1,"maximum":4294967295}` | Yes | Not declared |  {"minimum":1,"maximum":4294967295} |
| `timeout`<br />`/$defs/Readiness/oneOf/1/properties/timeout` | `string` | Yes | Not declared |  |
| `interval`<br />`/$defs/Readiness/oneOf/2/properties/interval` | `string` | Yes | Not declared |  |
| `kind`<br />`/$defs/Readiness/oneOf/2/properties/kind` | `"tcp"` | Yes | Not declared |  {"const":"tcp"} |
| `port`<br />`/$defs/Readiness/oneOf/2/properties/port` | `integer; {"minimum":1,"maximum":65535}` | Yes | Not declared |  {"minimum":1,"maximum":65535} |
| `retries`<br />`/$defs/Readiness/oneOf/2/properties/retries` | `integer; {"minimum":1,"maximum":4294967295}` | Yes | Not declared |  {"minimum":1,"maximum":4294967295} |
| `timeout`<br />`/$defs/Readiness/oneOf/2/properties/timeout` | `string` | Yes | Not declared |  |
| `kind`<br />`/$defs/Restart/oneOf/0/properties/kind` | `"no"` | Yes | Not declared |  {"const":"no"} |
| `kind`<br />`/$defs/Restart/oneOf/1/properties/kind` | `"always"` | Yes | Not declared |  {"const":"always"} |
| `kind`<br />`/$defs/Restart/oneOf/2/properties/kind` | `"unless-stopped"` | Yes | Not declared |  {"const":"unless-stopped"} |
| `kind`<br />`/$defs/Restart/oneOf/3/properties/kind` | `"on-failure"` | Yes | Not declared |  {"const":"on-failure"} |
| `max_retries`<br />`/$defs/Restart/oneOf/3/properties/max_retries` | `integer; {"minimum":1,"maximum":4294967295}` | No | Not declared |  {"minimum":1,"maximum":4294967295} |
| `domain`<br />`/$defs/RouteAlias/anyOf/0/properties/domain` | `string` | Yes | Not declared |  |
| `origin`<br />`/$defs/RouteAlias/anyOf/1/properties/origin` | `string` | Yes | Not declared |  |
| `aliases`<br />`/$defs/Routes/properties/aliases` | `{ [name]: RouteAlias }` | No | `{}` |  {"additionalProperties":{"$ref":"#/$defs/RouteAlias"}} |
| `domain`<br />`/$defs/Routes/properties/domain` | `string` | No | Not declared |  |
| `http`<br />`/$defs/Routes/properties/http` | `{ [name]: HttpRoute }` | No | `{}` |  {"additionalProperties":{"$ref":"#/$defs/HttpRoute"}} |
| `oauth_alias`<br />`/$defs/Routes/properties/oauth_alias` | `string` | No | Not declared |  |
| `origin`<br />`/$defs/Routes/properties/origin` | `string` | No | Not declared |  |
| `grace`<br />`/$defs/Shutdown/properties/grace` | `string; {"pattern":"^[0-9]*[1-9][0-9]*(?:ms\|s\|m\|h)$"}` | No | Not declared |  {"pattern":"^[0-9]*[1-9][0-9]*(?:ms\|s\|m\|h)$"} |
| `signal`<br />`/$defs/Shutdown/properties/signal` | `ShutdownSignal` | No | Not declared |  |
| `mode`<br />`/$defs/Source/properties/mode` | `SourceMode` | No | `"host-mounted"` |  |
| `root`<br />`/$defs/Source/properties/root` | `string` | No | `"."` |  |
| `kind`<br />`/$defs/Storage/properties/kind` | `StorageKind` | Yes | Not declared |  |
| `scope`<br />`/$defs/Storage/properties/scope` | `StorageScope` | Yes | Not declared |  |
| `build`<br />`/$defs/Workload/properties/build` | `Build` | No | Not declared |  |
| `command`<br />`/$defs/Workload/properties/command` | `Command` | No | Not declared |  |
| `depends_on`<br />`/$defs/Workload/properties/depends_on` | `array<Dependency>` | No | `[]` |  |
| `entrypoint`<br />`/$defs/Workload/properties/entrypoint` | `Entrypoint` | No | Not declared |  |
| `environment`<br />`/$defs/Workload/properties/environment` | `{ [name]: EnvironmentValue }` | No | `{}` |  {"additionalProperties":{"$ref":"#/$defs/EnvironmentValue"}} |
| `image`<br />`/$defs/Workload/properties/image` | `string` | No | Not declared |  |
| `init`<br />`/$defs/Workload/properties/init` | `boolean` | No | Not declared |  |
| `mounts`<br />`/$defs/Workload/properties/mounts` | `array<Mount>` | No | `[]` |  |
| `networks`<br />`/$defs/Workload/properties/networks` | `{ [name]: NetworkAttachment }` | No | Not declared |  {"additionalProperties":{"$ref":"#/$defs/NetworkAttachment"}} |
| `profiles`<br />`/$defs/Workload/properties/profiles` | `array<string>` | No | `[]` |  |
| `pull_policy`<br />`/$defs/Workload/properties/pull_policy` | `PullPolicy` | No | Not declared |  |
| `readiness`<br />`/$defs/Workload/properties/readiness` | `Readiness` | No | Not declared |  |
| `restart`<br />`/$defs/Workload/properties/restart` | `Restart` | No | Not declared |  |
| `shutdown`<br />`/$defs/Workload/properties/shutdown` | `Shutdown` | No | Not declared |  |
| `working_directory`<br />`/$defs/Workload/properties/working_directory` | `string` | No | Not declared |  |
| `pull_policy`<br />`/$defs/Workload/oneOf/0/properties/pull_policy` | `"always" \| "never" \| "missing"` | No | Not declared |  {"enum":["always","never","missing"]} |
| `pull_policy`<br />`/$defs/Workload/oneOf/1/properties/pull_policy` | `"build"` | No | Not declared |  {"const":"build"} |
| `auto_branch`<br />`/$defs/WorktreePolicy/properties/auto_branch` | `boolean` | No | `true` |  |
| `inherit_local`<br />`/$defs/WorktreePolicy/properties/inherit_local` | `boolean` | No | `true` |  |
| `restart`<br />`/properties/jobs/additionalProperties/allOf/1/properties/restart` | `schema-defined` | No | Not declared |  |
| `kind`<br />`/properties/jobs/additionalProperties/allOf/1/properties/restart/properties/kind` | `"no" \| "on-failure"` | No | Not declared |  {"enum":["no","on-failure"]} |

### Type definitions

References in the property table use the following names. A question mark marks an optional property within its object. Array notation includes the element type. Object alternatives remain subject to their required/not constraints.

| Definition | Shape / allowed values |
| --- | --- |
| `Access` | `"read-only" \| "read-write"` |
| `Build` | `{ context: string; dockerfile?: string; target?: string }` |
| `Command` | `{ exec: array<string>; {"minItems":1} } \| { shell: string }` |
| `Dependency` | `{ condition: ServiceCondition; service: string } \| { condition: JobCondition; job: string }` |
| `EndpointProtocol` | `"http" \| "https" \| "tcp"` |
| `EndpointReference` | `{ kind: "route"; name: string } \| { kind: "service"; name: string; port: integer; {"minimum":1,"maximum":65535}; protocol: EndpointProtocol } \| { kind: "host_binding"; name: string; {"minLength":1,"maxLength":63,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"} }` |
| `Entrypoint` | `{ exec: array<string>; {"prefixItems":[{"minLength":1,"type":"string"}]} } \| { shell: string; {"minLength":1} }` |
| `EnvironmentSelection` | `{ default_overlay?: string; {"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"} }` |
| `EnvironmentValue` | `{ literal: string } \| { default: string } \| { env_ref: string; {"pattern":"^[A-Z_][A-Z0-9_]*$"} } \| { unset: True } \| { endpoint: EndpointReference }` |
| `FileConfig` | `{ file: string }` |
| `FileSecret` | `{ file: string } \| { env_ref: string }` |
| `HostBindingTarget` | `{ kind: "host"; port: integer; {"minimum":1,"maximum":65535}; protocol: EndpointProtocol } \| { hostname: string; {"minLength":1,"maxLength":253}; kind: "external"; port: integer; {"minimum":1,"maximum":65535}; protocol: EndpointProtocol }` |
| `HostConfig` | `{ down?: HostHooks; processes?: { [name]: HostProcess }; up?: HostHooks }` |
| `HostConflict` | `"fail" \| "adopt"` |
| `HostEnvTarget` | `{ kind: "host" } \| { kind: "workload"; name: string }` |
| `HostExit` | `"stop_on_down"` |
| `HostHook` | `{ command: Command; cwd?: string; env_target?: HostEnvTarget; environment?: { [name]: EnvironmentValue }; name: string }` |
| `HostHooks` | `{ after?: array<HostHook>; before?: array<HostHook> }` |
| `HostProcess` | `{ command: Command; cwd?: string; env_target?: HostEnvTarget; environment?: { [name]: EnvironmentValue }; exit?: HostExit; singleton?: HostSingleton; startup?: HostStartup }` |
| `HostSingleton` | `{ on_conflict?: HostConflict; ports: array<integer; {"minimum":1,"maximum":65535}>; {"minItems":1,"uniqueItems":true} }` |
| `HostStartup` | `"up"` |
| `HttpProtocol` | `"http" \| "https"` |
| `HttpRoute` | `{ hostname: string; port: integer; {"minimum":1,"maximum":65535}; protocol?: HttpProtocol; service: string }` |
| `JobCondition` | `"completed"` |
| `Mount` | `{ access: Access; source: string; target: string } \| { access: Access; storage: string; target: string } \| { access: Access; config: string; gid?: integer; {"minimum":0}; mode?: string; {"pattern":"^0[0-7]{3}$"}; target: string; uid?: integer; {"minimum":0} } \| { access: Access; gid?: integer; {"minimum":0}; mode?: string; {"pattern":"^0[0-7]{3}$"}; secret: string; target: string; uid?: integer; {"minimum":0} }` |
| `Network` | `{ internal?: boolean }` |
| `NetworkAttachment` | `{ aliases?: array<string> }` |
| `OpenConfig` | `{ prefer?: OpenPreference }` |
| `OpenPreference` | `"auto" \| "alias" \| "dev"` |
| `PullPolicy` | `"always" \| "never" \| "missing" \| "build"` |
| `Readiness` | `{ command: Command; interval: string; kind: "exec"; retries: integer; {"minimum":1,"maximum":4294967295}; timeout: string } \| { interval: string; kind: "http"; path: string; port: integer; {"minimum":1,"maximum":65535}; retries: integer; {"minimum":1,"maximum":4294967295}; timeout: string } \| { interval: string; kind: "tcp"; port: integer; {"minimum":1,"maximum":65535}; retries: integer; {"minimum":1,"maximum":4294967295}; timeout: string }` |
| `Restart` | `{ kind: "no" } \| { kind: "always" } \| { kind: "unless-stopped" } \| { kind: "on-failure"; max_retries?: integer; {"minimum":1,"maximum":4294967295} }` |
| `RouteAlias` | `{ domain: string } \| { origin: string }` |
| `Routes` | `{ aliases?: { [name]: RouteAlias }; domain?: string; http?: { [name]: HttpRoute }; oauth_alias?: string; origin?: string }` |
| `ServiceCondition` | `"started" \| "ready"` |
| `Shutdown` | `{ grace?: string; {"pattern":"^[0-9]*[1-9][0-9]*(?:ms\|s\|m\|h)$"}; signal?: ShutdownSignal }` |
| `ShutdownSignal` | `"SIGHUP" \| "SIGTERM" \| "SIGINT" \| "SIGQUIT" \| "SIGILL" \| "SIGTRAP" \| "SIGABRT" \| "SIGBUS" \| "SIGFPE" \| "SIGKILL" \| "SIGUSR1" \| "SIGSEGV" \| "SIGUSR2" \| "SIGPIPE" \| "SIGALRM" \| "SIGSTKFLT" \| "SIGCHLD" \| "SIGCONT" \| "SIGSTOP" \| "SIGTSTP" \| "SIGTTIN" \| "SIGTTOU" \| "SIGURG" \| "SIGXCPU" \| "SIGXFSZ" \| "SIGVTALRM" \| "SIGPROF" \| "SIGWINCH" \| "SIGIO" \| "SIGPWR" \| "SIGSYS"` |
| `Source` | `{ mode?: SourceMode; root?: string }` |
| `SourceMode` | `"host-mounted"` |
| `Storage` | `{ kind: StorageKind; scope: StorageScope }` |
| `StorageKind` | `"persistent"` |
| `StorageScope` | `"worktree"` |
| `True` | `true` |
| `Workload` | `{ build?: Build; command?: Command; depends_on?: array<Dependency>; entrypoint?: Entrypoint; environment?: { [name]: EnvironmentValue }; image?: string; init?: boolean; mounts?: array<Mount>; networks?: { [name]: NetworkAttachment }; profiles?: array<string>; pull_policy?: PullPolicy; readiness?: Readiness; restart?: Restart; shutdown?: Shutdown; working_directory?: string }; {"oneOf":[{"not":{"required":["build"]},"properties":{"pull_policy":{"enum":["always","never","missing"]}},"required":["image"]},{"not":{"required":["image"]},"properties":{"pull_policy":{"const":"build"}},"required":["build"]}]}` |
| `WorktreePolicy` | `{ auto_branch?: boolean; inherit_local?: boolean }` |

### Workload variants

A workload requires exactly one of image and build. Supplying both or neither is invalid. Other property defaults do not remove this oneOf requirement.

| Variant | Required | Forbidden | pull_policy when supplied |
| --- | --- | --- | --- |
| Existing image | image | build | always, never or missing |
| Build context | build | image | build only |

The pull_policy variant restrictions constrain supplied values; they do not make the optional pull_policy property required.

## Local override document

[Pinned machine schema](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/packages/config-compiler/generated/hack.local.schema.json). Each pointer identifies a field declaration in that schema, including definitions and union variants.

| Field / schema pointer | Type or reference | Required here | Default | Meaning / constraints |
| --- | --- | --- | --- | --- |
| `environment`<br />`/properties/environment` | `LocalEnvironment` | No | `{}` |  |
| `host_bindings`<br />`/properties/host_bindings` | `{ [name]: HostBindingTarget \| null }; {"propertyNames":{"maxLength":63,"minLength":1,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","type":"string"}}` | No | Not declared |  {"additionalProperties":{"anyOf":[{"$ref":"#/$defs/HostBindingTarget"},{"type":"null"}]}} |
| `open`<br />`/properties/open` | `LocalOpen` | No | Not declared |  |
| `routes`<br />`/properties/routes` | `LocalRoutes` | No | Not declared |  |
| `schema_version`<br />`/properties/schema_version` | `integer; {"minimum":1,"maximum":1}` | Yes | Not declared |  {"minimum":1,"maximum":1} |
| `kind`<br />`/$defs/HostBindingTarget/oneOf/0/properties/kind` | `"host"` | Yes | Not declared |  {"const":"host"} |
| `port`<br />`/$defs/HostBindingTarget/oneOf/0/properties/port` | `integer; {"minimum":1,"maximum":65535}` | Yes | Not declared |  {"minimum":1,"maximum":65535} |
| `protocol`<br />`/$defs/HostBindingTarget/oneOf/0/properties/protocol` | `EndpointProtocol` | Yes | Not declared |  |
| `hostname`<br />`/$defs/HostBindingTarget/oneOf/1/properties/hostname` | `string; {"minLength":1,"maxLength":253}` | Yes | Not declared |  {"minLength":1,"maxLength":253} |
| `kind`<br />`/$defs/HostBindingTarget/oneOf/1/properties/kind` | `"external"` | Yes | Not declared |  {"const":"external"} |
| `port`<br />`/$defs/HostBindingTarget/oneOf/1/properties/port` | `integer; {"minimum":1,"maximum":65535}` | Yes | Not declared |  {"minimum":1,"maximum":65535} |
| `protocol`<br />`/$defs/HostBindingTarget/oneOf/1/properties/protocol` | `EndpointProtocol` | Yes | Not declared |  |
| `default_overlay`<br />`/$defs/LocalEnvironment/properties/default_overlay` | `['string', 'null']; {"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}` | No | Not declared |  {"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"} |
| `prefer`<br />`/$defs/LocalOpen/properties/prefer` | `OpenPreference` | No | Not declared |  |
| `domain`<br />`/$defs/LocalRoutes/properties/domain` | `string` | No | Not declared |  |

### Type definitions

References in the property table use the following names. A question mark marks an optional property within its object. Array notation includes the element type. Object alternatives remain subject to their required/not constraints.

| Definition | Shape / allowed values |
| --- | --- |
| `EndpointProtocol` | `"http" \| "https" \| "tcp"` |
| `HostBindingTarget` | `{ kind: "host"; port: integer; {"minimum":1,"maximum":65535}; protocol: EndpointProtocol } \| { hostname: string; {"minLength":1,"maxLength":253}; kind: "external"; port: integer; {"minimum":1,"maximum":65535}; protocol: EndpointProtocol }` |
| `LocalEnvironment` | `{ default_overlay?: ['string', 'null']; {"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"} }` |
| `LocalOpen` | `{ prefer?: OpenPreference }` |
| `LocalRoutes` | `{ domain?: string }` |
| `OpenPreference` | `"auto" \| "alias" \| "dev"` |

## Array boundaries

Entrypoint.exec accepts an empty array. If it is nonempty, its first string must have at least one character; the prefixItems rule does not require a first element to exist. HostSingleton.ports is a nonempty unique array of integers from 1 through 65535, inclusive. The element and prefix constraints appear in the type declarations above.


---

<!-- Editorial source: docs/versions/v5/reference/command-contracts.md; based on 28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc; source label: next.5 field audit; URL: https://hack.foo/docs/v5/reference/command-contracts -->
# Command and output contracts

This field inventory was audited against the `5.0.0-next.5` source and has not been requalified against later prereleases. The [generated command reference](/docs/v5/reference/cli) and the pinned runtime guides take precedence where they differ.

Pinned source: `28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc`. This supplements the [generated command reference](/docs/v5/reference/cli). Command registration and document shape do not establish backend admission.

## Scope and coverage

The pinned source inventory has **92 leaves**, **335 leaf-owned option occurrences**, and **611 effective option occurrences**. The recommended v5 publication selection retains **84 leaves**, **288 own option occurrences** and **540 effective occurrences** (three global/built-in flags per leaf). Eight retiring agent-setup leaves and init's optional handoff flag are intentionally excluded; they remain available in the released source. The six additional leaf sections below complete the pinned generated reference within the retained command scope. No declared effective flags or short aliases are missing from matching sections; generic value placeholders explain initial spelling-only differences. Counts are occurrences, not unique names. Parent namespaces are not leaves.

Retired gateway/node/remote/dispatch, hosted account/team/Tickets, internal helpers, extension dispatch and fun commands are excluded. SSH remote access is excluded. Retained fields within local commands do not establish support for retired backends.

The retired agent instruction-management commands (`hack setup sync`, standalone `hack setup` exports and `hack agent prime`) are omitted; in v5 they refuse with a retirement notice. See [Agent integrations](/docs/v5/integrations).

## Global flags and parsing

Every leaf accepts `--no-interactive`, `--help, -h`, and `--version, -v`. The first also has `HACK_NO_INTERACTIVE=1`; it applies documented defaults or refuses required interaction. Help/version return early with status 0. These are the only inherited flags: parent options are not inherited. Omitted booleans parse false; omitted strings/numbers parse undefined. Handler/config fallbacks are separate. A nonboolean OptionSpec defaultValue supplies a value when the flag is present without its value; it is not an unconditional omitted-flag default.

## Additional command details

### `hack global dns preview`

Preview a scoped native custom-domain DNS claim or the hack.local relay repair without changing the host.

Arguments: none.

| Option | Type | Meaning / declared fallback |
| --- | --- | --- |
| `--json` | boolean | Output JSON (machine-readable) |
| `--domain v5.hack.gy` | string | Suffix to inspect: a custom suffix, or hack.local for the native relay repair (default: a custom global default_domain) |
| `--no-interactive` | boolean | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | boolean | Show help |
| `--version, -v` | boolean | Show version |

Source: `src/commands/global.ts:232 (globalDnsPreviewSpec)`. No command alias is declared.

### `hack global dns activate`

Activate only the selected native custom-domain DNS suffix.

Arguments: none.

| Option | Type | Meaning / declared fallback |
| --- | --- | --- |
| `--domain v5.hack.gy` | string | Custom suffix to activate (default: a custom global default_domain) |
| `--no-interactive` | boolean | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | boolean | Show help |
| `--version, -v` | boolean | Show version |

Source: `src/commands/global.ts:252 (globalDnsActivateSpec)`. No command alias is declared.

### `hack global dns deactivate`

Remove an owned native custom-domain DNS suffix, or undo the hack.local relay repair.

Arguments: none.

| Option | Type | Meaning / declared fallback |
| --- | --- | --- |
| `--domain v5.hack.gy` | string | Custom suffix to deactivate, or hack.local to undo the native relay repair (default: a custom global default_domain) |
| `--no-interactive` | boolean | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | boolean | Show help |
| `--version, -v` | boolean | Show version |

Source: `src/commands/global.ts:270 (globalDnsDeactivateSpec)`. No command alias is declared.

### `hack project owner show`

Show the local ownership metadata for the current project.

Arguments: none.

| Option | Type | Meaning / declared fallback |
| --- | --- | --- |
| `--path, -p <dir>` | string | Run a project command against a repo path (overrides cwd search) |
| `--project <name>` | string | Target a registered project by name (from ~/.hack/projects.json) |
| `--json` | boolean | Output JSON (machine-readable) |
| `--no-interactive` | boolean | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | boolean | Show help |
| `--version, -v` | boolean | Show version |

Source: `src/commands/project-admin.ts:16 (ownerShowSpec)`. No command alias is declared.

### `hack env backend status`

Show configured env/secret backend strategy.

Arguments: none.

| Option | Type | Meaning / declared fallback |
| --- | --- | --- |
| `--json` | boolean | Output JSON (machine-readable) |
| `--no-interactive` | boolean | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | boolean | Show help |
| `--version, -v` | boolean | Show version |

Source: `src/commands/env.ts:428 (backendStatusSpec)`. No command alias is declared.

### `hack env backend use <backend>`

Select env/secret backend strategy.

Arguments: `backend` — required.

| Option | Type | Meaning / declared fallback |
| --- | --- | --- |
| `--provider <aws\|gcp\|azure\|vault>` | string | Cloud secret provider when backend is cloud |
| `--store-path <path>` | string | Encrypted file path when backend is encrypted_file |
| `--key-path <path>` | string | Stable key file path when backend is encrypted_file |
| `--provision-key` | boolean | Provision a stable key file for encrypted_file backend |
| `--secret-project <id>` | string | Optional cloud project/account identifier |
| `--secret-prefix <prefix>` | string | Optional cloud secret name prefix |
| `--json` | boolean | Output JSON (machine-readable) |
| `--no-interactive` | boolean | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
| `--help, -h` | boolean | Show help |
| `--version, -v` | boolean | Show version |

Source: `src/commands/env.ts:437 (backendUseSpec)`. No command alias is declared.

## Complete public leaf and flag inventory

“Present” means a matching usage section; flags were compared separately. It does not prove every handler default is described. All rows also accept the three global/built-in flags above. Arguments are exact spec names.

| Leaf usage | Own flags (aliases and value hints) | Pinned generated section |
| --- | --- | --- |
| `hack global install` | none | Present |
| `hack global dns preview` | `--json`; `--domain v5.hack.gy` | Missing; drafted above |
| `hack global dns activate` | `--domain v5.hack.gy` | Missing; drafted above |
| `hack global dns deactivate` | `--domain v5.hack.gy` | Missing; drafted above |
| `hack global up` | none | Present |
| `hack global down` | none | Present |
| `hack global status` | `--json` | Present |
| `hack global logs [service]` | `--follow, -f`; `--no-follow`; `--tail <n>`; `--pretty` | Present |
| `hack global ca` | `--print` | Present |
| `hack global cert <hosts...>` | `--install`; `--out <dir>` | Present |
| `hack global trust` | none | Present |
| `hack global logs-reset` | none | Present |
| `hack global authorize` | none | Present |
| `hack status` | `--project <name>`; `--include-global`; `--all`; `--meta`; `--json` | Present |
| `hack usage` | `--project <name>`; `--details`; `--include-global`; `--watch`; `--interval <value>`; `--no-host`; `--json` | Present |
| `hack projects prune` | `--project <name>`; `--include-global`; `--dry-run`; `--json` | Present |
| `hack project owner show` | `--path, -p <dir>`; `--project <name>`; `--json` | Missing; drafted above |
| `hack init` | `--path, -p <dir>`; `--manual`; `--auto`; `--name <slug>`; `--dev-host <host>`; `--oauth`; `--oauth-tld <tld>`; `--no-discovery` | Present |
| `hack up [services...]` | `--path, -p <dir>`; `--project <name>`; `--env <name\|base\|default>`; `--branch <name>`; `--detach, -d`; `--profile <name[,name...]>`; `--target <auto\|local\|remote>`; `--json` | Present |
| `hack down` | `--path, -p <dir>`; `--project <name>`; `--env <name\|base\|default>`; `--branch <name>`; `--profile <name[,name...]>`; `--target <auto\|local\|remote>`; `--prune-caches`; `--yes`; `--json`; `--recover` | Present |
| `hack restart [services...]` | `--path, -p <dir>`; `--project <name>`; `--env <name\|base\|default>`; `--branch <name>`; `--profile <name[,name...]>`; `--target <auto\|local\|remote>`; `--json`; `--recover-frontend`; `--expect-finalization-attempt <32-hex>`; `--expect-frontend-pid <pid>` | Present |
| `hack ps` | `--path, -p <dir>`; `--project <name>`; `--branch <name>`; `--profile <name[,name...]>`; `--json` | Present |
| `hack tui` | `--path, -p <dir>`; `--project <name>` | Present |
| `hack run <service> [cmd...]` | `--path, -p <dir>`; `--project <name>`; `--env <name\|base\|default>`; `--branch <name>`; `--workdir <path>`; `--profile <name[,name...]>` | Present |
| `hack exec <service> [cmd...]` | `--path, -p <dir>`; `--project <name>`; `--env <name\|base\|default>`; `--branch <name>`; `--workdir <path>`; `--profile <name[,name...]>` | Present |
| `hack logs [service]` | `--path, -p <dir>`; `--project <name>`; `--branch <name>`; `--follow, -f`; `--no-follow`; `--tail <n>`; `--pretty`; `--json`; `--profile <name[,name...]>`; `--compose`; `--loki`; `--services <csv>`; `--query <logql>`; `--since <time>`; `--until <time>` | Present |
| `hack open [target]` | `--path, -p <dir>`; `--project <name>`; `--branch <name>`; `--prefer <auto\|alias\|dev>`; `--json` | Present |
| `hack branch add <name>` | `--path, -p <dir>`; `--project <name>`; `--note <text>` | Present |
| `hack branch list` | `--path, -p <dir>`; `--project <name>` | Present |
| `hack branch remove <name>` | `--path, -p <dir>`; `--project <name>` | Present |
| `hack branch open <name>` | `--path, -p <dir>`; `--project <name>`; `--prefer <auto\|alias\|dev>` | Present |
| `hack log-pipe` | `--format <auto\|docker-compose\|plain>`; `--stream <stdout\|stderr>` | Present |
| `hack doctor` | `--path, -p <dir>`; `--fix`; `--migrate-env-config`; `--domain-migration preview\|apply\|rollback`; `--json`; `--browser-url https://app.hack`; `--browser-result unknown\|works\|fails\|permission-denied`; `--branch <name>`; `--native-cleanup inspect`; `--native-run-mapping inspect\|repair`; `--expect-selection <64-hex>`; `--accept-legacy-device-rebind` | Present |
| `hack crash-capture` | `--path, -p <dir>`; `--since <duration>` | Present |
| `hack daemon start` | `--foreground` | Present |
| `hack daemon stop` | none | Present |
| `hack daemon restart` | none | Present |
| `hack daemon status` | `--json` | Present |
| `hack daemon metrics` | none | Present |
| `hack daemon logs` | `--tail <n>` | Present |
| `hack daemon clear` | none | Present |
| `hack daemon install` | `--run-at-load`; `--no-run-at-load`; `--gui-only`; `--no-gui-only` | Present |
| `hack daemon uninstall` | none | Present |
| `hack secrets set [name]` | `--service <service>` | Present |
| `hack secrets get [name]` | `--service <service>` | Present |
| `hack secrets delete [name]` | `--service <service>` | Present |
| `hack env list` | `--path, -p <dir>`; `--project <name>`; `--env <name\|base\|default>`; `--json`; `--show-secrets`; `--service <global\|service>` | Present |
| `hack env get <key>` | `--path, -p <dir>`; `--project <name>`; `--env <name\|base\|default>`; `--service <global\|service>` | Present |
| `hack env explain <key>` | `--path, -p <dir>`; `--project <name>`; `--env <name\|base\|default>`; `--json`; `--service <global\|service>`; `--target <host\|compose>` | Present |
| `hack env apply` | `--path, -p <dir>`; `--project <name>`; `--env <name\|base\|default>`; `--json`; `--service <global\|service>` | Present |
| `hack env add [key] [value]` | `--path, -p <dir>`; `--project <name>`; `--env <name\|base\|default>`; `--secret`; `--value-stdin`; `--local`; `--service <global\|service>` | Present |
| `hack env set [key] [value]` | `--path, -p <dir>`; `--project <name>`; `--env <name\|base\|default>`; `--secret`; `--value-stdin`; `--local`; `--service <global\|service>` | Present |
| `hack env materialize` | `--path, -p <dir>`; `--project <name>`; `--env <name\|base\|default>`; `--service <global\|service>` | Present |
| `hack env exec [command...]` | `--path, -p <dir>`; `--project <name>`; `--env <name\|base\|default>`; `--service <global\|service>`; `--target <host\|compose>`; `--shell <command>`; `--timeout <seconds>`; `--lifetime <command\|persistent>` | Present |
| `hack env shell` | `--path, -p <dir>`; `--project <name>`; `--env <name\|base\|default>`; `--service <global\|service>`; `--target <host\|compose>` | Present |
| `hack env unset [key]` | `--path, -p <dir>`; `--project <name>`; `--env <name\|base\|default>`; `--local`; `--service <global\|service>` | Present |
| `hack env backend status` | `--json` | Missing; drafted above |
| `hack env backend use <backend>` | `--provider <aws\|gcp\|azure\|vault>`; `--store-path <path>`; `--key-path <path>`; `--provision-key`; `--secret-project <id>`; `--secret-prefix <prefix>`; `--json` | Missing; drafted above |
| `hack host ps` | `--project <name>`; `--json` | Present |
| `hack host exec [command...]` | `--path, -p <dir>`; `--project <name>`; `--env <name\|base\|default>`; `--scope <global\|service>`; `--target <host\|compose>`; `--shell <command>`; `--timeout <seconds>`; `--lifetime <command\|persistent>` | Present |
| `hack host shell` | `--path, -p <dir>`; `--project <name>`; `--env <name\|base\|default>`; `--scope <global\|service>`; `--target <host\|compose>` | Present |
| `hack config get <key>` | `--path, -p <dir>`; `--project <name>`; `--global` | Present |
| `hack config set <key> <value>` | `--path, -p <dir>`; `--project <name>`; `--global` | Present |
| `hack config validate` | `--file <path>`; `--profile <names>`; `--domain <suffix>`; `--path, -p <dir>`; `--env <name\|base\|default>`; `--json` | Present |
| `hack config plan` | `--profile <names>`; `--domain <suffix>`; `--path, -p <dir>`; `--env <name\|base\|default>`; `--json` | Present |
| `hack config import` | `--dry-run`; `--path, -p <dir>`; `--json` | Present |
| `hack config adopt` | `--stop`; `--dry-run`; `--rollback`; `--recover`; `--branch <value>`; `--path, -p <dir>`; `--json` | Present |
| `hack mcp serve` | none | Present |
| `hack mcp print` | `--bundle <directory>`; `--cli <executable>`; `--runtime-directory <directory>`; `--scope <user\|project>`; `--path, -p <dir>`; `--all`; `--cursor`; `--claude`; `--codex` | Present |
| `hack setup tmux` | `--check`; `--remove` | Present |
| `hack session list` | none | Present |
| `hack session start [project]` | `--up`; `--new`; `--name <value>`; `--detach, -d`; `--env <name\|base\|default>`; `--service <global\|service>` | Present |
| `hack session stop <workspace>` | none | Present |
| `hack session attach <workspace>` | none | Present |
| `hack session exec <workspace> <command>` | `--env <name\|base\|default>`; `--service <global\|service>` | Present |
| `hack session panes <workspace>` | `--json`; `--pretty` | Present |
| `hack session capture <workspace>` | `--target <target>`; `--lines <n>`; `--json`; `--pretty` | Present |
| `hack session tail <workspace>` | `--target <target>`; `--lines <n>`; `--interval-ms <ms>`; `--max-ms <ms>`; `--json`; `--pretty` | Present |
| `hack agent patterns` | none | Present |
| `hack agent init` | `--path, -p <dir>`; `--client, -c <cursor\|claude\|codex\|print>` | Present |
| `hack agent onboard` | `--path, -p <dir>` | Present |
| `hack update` | `--check`; `--yes`; `--tag <tag>`; `--json` | Present |
| `hack version` | none | Present |
| `hack help [path...]` | `--all` | Present |

## Declared defaults and option semantics

This table preserves declarations/descriptions that state defaults. Other handler/backend defaults are not implied by absence here.

| Leaf / option | Source declaration |
| --- | --- |
| `hack global dns preview` / `--domain v5.hack.gy` | Suffix to inspect: a custom suffix, or hack.local for the native relay repair (default: a custom global default_domain) |
| `hack global dns activate` / `--domain v5.hack.gy` | Custom suffix to activate (default: a custom global default_domain) |
| `hack global dns deactivate` / `--domain v5.hack.gy` | Custom suffix to deactivate, or hack.local to undo the native relay repair (default: a custom global default_domain) |
| `hack global logs [service]` / `--follow, -f` | Follow logs (default for `hack logs`) |
| `hack global logs [service]` / `--tail <n>` | Tail last N log lines Flag-present fallback: `200`. |
| `hack global cert <hosts...>` / `--out <dir>` | Directory for generated cert/key (default: ~/.hack/certs) |
| `hack init` / `--auto` | Run non-interactive init with sensible defaults |
| `hack init` / `--name <slug>` | Project slug (default: repo name) |
| `hack init` / `--dev-host <host>` | DEV_HOST override (new projects use global default_domain, or hack.local) |
| `hack init` / `--oauth-tld <tld>` | OAuth alias TLD override (default: gy) |
| `hack up [services...]` / `--env <name\|base\|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `hack down` / `--env <name\|base\|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `hack restart [services...]` / `--env <name\|base\|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `hack run <service> [cmd...]` / `--env <name\|base\|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `hack exec <service> [cmd...]` / `--env <name\|base\|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `hack logs [service]` / `--follow, -f` | Follow logs (default for `hack logs`) |
| `hack logs [service]` / `--tail <n>` | Tail last N log lines Flag-present fallback: `200`. |
| `hack log-pipe` / `--format <auto\|docker-compose\|plain>` | How to parse incoming lines from stdin Flag-present fallback: `auto`. |
| `hack log-pipe` / `--stream <stdout\|stderr>` | Treat stdin as stdout or stderr (stderr forces ERROR level + writes to stderr) Flag-present fallback: `stdout`. |
| `hack doctor` / `--browser-result unknown\|works\|fails\|permission-denied` | Your manual browser observation for --browser-url (default: unknown) |
| `hack daemon logs` / `--tail <n>` | Tail last N log lines Flag-present fallback: `200`. |
| `hack daemon install` / `--gui-only` | Only run in GUI sessions (default) |
| `hack secrets set [name]` / `--service <service>` | Override Bun.secrets service name Flag-present fallback: `hack-cli`. |
| `hack secrets get [name]` / `--service <service>` | Override Bun.secrets service name Flag-present fallback: `hack-cli`. |
| `hack secrets delete [name]` / `--service <service>` | Override Bun.secrets service name Flag-present fallback: `hack-cli`. |
| `hack env list` / `--env <name\|base\|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `hack env get <key>` / `--env <name\|base\|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `hack env explain <key>` / `--env <name\|base\|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `hack env explain <key>` / `--target <host\|compose>` | Env view for host commands (default: host rewrites container-oriented addresses for local host execution) |
| `hack env apply` / `--env <name\|base\|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `hack env add [key] [value]` / `--env <name\|base\|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `hack env set [key] [value]` / `--env <name\|base\|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `hack env materialize` / `--env <name\|base\|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `hack env exec [command...]` / `--env <name\|base\|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `hack env exec [command...]` / `--target <host\|compose>` | Env view for host commands (default: host rewrites container-oriented addresses for local host execution) |
| `hack env exec [command...]` / `--lifetime <command\|persistent>` | Declare intended lifetime for diagnostics (default: command; does not detach) |
| `hack env shell` / `--env <name\|base\|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `hack env shell` / `--target <host\|compose>` | Env view for host commands (default: host rewrites container-oriented addresses for local host execution) |
| `hack env unset [key]` / `--env <name\|base\|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `hack host exec [command...]` / `--env <name\|base\|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `hack host exec [command...]` / `--target <host\|compose>` | Env view for host commands (default: host rewrites container-oriented addresses for local host execution) |
| `hack host exec [command...]` / `--lifetime <command\|persistent>` | Declare intended lifetime for diagnostics (default: command; does not detach) |
| `hack host shell` / `--env <name\|base\|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `hack host shell` / `--target <host\|compose>` | Env view for host commands (default: host rewrites container-oriented addresses for local host execution) |
| `hack config validate` / `--env <name\|base\|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `hack config plan` / `--env <name\|base\|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `hack mcp print` / `--scope <user\|project>` | Write MCP config to user or project scope Flag-present fallback: `user`. |
| `hack session start [project]` / `--new` | Create an isolated workspace instead of reusing the default project workspace |
| `hack session start [project]` / `--env <name\|base\|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `hack session exec <workspace> <command>` / `--env <name\|base\|default>` | Select an env overlay by name; omit for the configured default overlay, or use 'base' or 'default' for base layers only |
| `hack session capture <workspace>` / `--target <target>` | Tmux pane target (default: active pane) |
| `hack session capture <workspace>` / `--lines <n>` | Number of lines to capture Flag-present fallback: `200`. |
| `hack session tail <workspace>` / `--target <target>` | Tmux pane target (default: active pane) |
| `hack session tail <workspace>` / `--lines <n>` | Number of lines to capture Flag-present fallback: `200`. |
| `hack session tail <workspace>` / `--interval-ms <ms>` | Polling interval in milliseconds Flag-present fallback: `500`. |
| `hack session tail <workspace>` / `--max-ms <ms>` | Stop tailing after N milliseconds Flag-present fallback: `5000`. |

## Ownership inspection

`project owner show` searches from cwd or `--path`, or selects a registered `--project`; do not combine path/project. Missing project and config parse failures refuse. JSON success is a bare object and exits 0:

| Field | Type and meaning |
| --- | --- |
| `project_root` | string; resolved root |
| `project_slug` | string or null; sanitized configured name, null if blank |
| `ownership.mode` | local/shared |
| `ownership.owner_type` | user/team/organization |
| `ownership.owner_id` | string or null |
| `ownership.managed_by` | local/broker |

Defaults are local/user/null/local. These are retained local metadata, not hosted team/broker support. No owner mutation leaf exists here.

## Env backend strategy

Status reads effective settings for cwd's project when found, global settings otherwise. It takes no project/path/env selectors. Use writes **global** settings and rereads global settings. It does not migrate YAML project-key values or establish cloud-provider qualification.

Backend is required: exactly `keychain`, `encrypted_file` or `cloud`. Provider accepts exactly `aws|gcp|azure|vault` and is required for cloud even if a provider was previously configured. Invalid nonempty backend/provider is a usage error. Inputs are trimmed; empty optional paths/project/prefix are omitted. Store/key paths apply only to encrypted_file; cloud project/prefix apply only with cloud/provider. Omitted settings are retained. Provision-key defaults false and applies only to encrypted_file.

Fresh schema defaults: keychain, allow_env_auth_refs true, store_plaintext_in_backend false; file path `~/.hack/secrets.enc.json`, key path `~/.hack/secrets-file.key`; cloud prefix `hack`, provider/project unspecified. These are config defaults, not flag defaults reapplied on every use. The key environment variable name is `HACK_SECRETS_FILE_KEY`. Providers describe retained compatibility strategies, not qualified cloud onboarding.

Both JSON successes are bare objects and return 0:

| Field | status | use |
| --- | --- | --- |
| `backend` | selected enum | selected enum |
| `allow_env_auth_refs` | boolean | boolean |
| `store_plaintext_in_backend` | boolean | boolean |
| `encrypted_file` | object: string path/keyPath | same |
| `encrypted_file_key_env` | string variable name | same |
| `cloud` | object: optional provider/project strings, string secretPrefix; undefined properties omitted | same |
| `status` | object below | absent |
| `encrypted_file_key_provisioned` | absent | null or {keyPath:string, source:env/file/keychain/generated} |

Status has string storage_mode/trust_model/portability/plaintext_compatibility and classification. Classification has string trust_model/custody/portability and shared_state (local_only/plaintext_compatible/portable_bundle/broker_managed). These descriptive names do not grant remote/team features.

## JSON results and exits

The generated page's universal envelope claim is too broad. Decode by command and backend. The shared helper emits `{ok:true,data:T}` or `{ok:false,error:{code,message,detail?}}`; detail is unknown. Its mapper returns 0/1. Handlers can instead return child exit codes, bare objects, reports or JSON-lines.

Thrown usage errors with an explicit `--json` token become E_USAGE; other thrown errors preserve HackCliError codes or become E_UNEXPECTED, with exit 1. Returning 1 directly does not automatically create an error envelope. Unknown command or namespace paths may print help and exit 1. Help/version return early with status 0, including when JSON was requested. Valid JSON alone proves neither success nor readiness.

| Command | Output contract | Exit / open shape |
| --- | --- | --- |
| up/down/restart, retained Compose owner | shared envelope; data action (up/down/restart), project:string, branch:string/null, composeProject:string, services.{started,completed,stopped,failed}:sorted string arrays, durationMs:number; optional cacheVolumesRemoved:string[] | JSON up implies detach. Structured startup/lifecycle failures use error envelope. |
| ps, Compose | bare {project,branch,composeProject,items}; branch nullable; items parsed engine records | daemon-assisted JSON may be forwarded; engine rows are open. Compose failure can return child nonzero with stderr and no success object. |
| open | bare {url:string} | JSON reports URL; does not launch browser |
| projects/status | bare listing below | runtime_ok false is report data, not necessarily command failure |
| projects prune | shared envelope, preview/apply variants below | dry-run reports candidates; apply reports removals |
| project owner show | bare ownership object above | success 0 |
| env backend status/use | bare strategy objects above | success 0 |
| env list | bare modern-YAML or legacy report below | raw report may include values |
| env apply | forwards restart service --path repo with selected env/JSON flags | returns child restart output and exit code, not an env-list report; native subset/JSON limits still apply |
| env explain | bare value-free explanation below | inspect available/scope; no value |
| doctor | shared envelope with checks[], summary:string[], counts.{ok,warn,error}:numbers | can emit ok:true and exit 1 when checks contain errors |
| usage | bare projects[], total nullable, host[], host_total nullable, runtime_ok:boolean, runtime_error nullable; details adds containers[] | failures exit 1; optional error string. No samples exits 0 with warning:no_usage_samples. Watch uses the interactive redraw path even with JSON selected; do not treat watch as a JSON report stream. |
| global status | bare generated_at/caddy/logging/networks/gateway/summary | exits 0 even if summary health false; gateway is retained unsupported data, excluded from public contract |
| daemon status | bare report below | running returns 0; starting/stale/unavailable may return 1 |
| host ps | bare {generatedAt,snapshotAvailable,commands,lifecycle} | timestamp string, availability boolean; nested telemetry remains specialized |
| session panes/capture/tail | JSON-lines events below | no shared envelope |
| update | command-owned object with ok:boolean, string error on failure | error is not shared error.{code,message}; success varies by check/install outcome; exit follows ok |

Config get has no JSON flag: non-string values serialize as JSON, strings print plainly. Daemon metrics prints retained metrics JSON without a JSON flag; nested internal transport data is not a supported general API. MCP serve speaks MCP; log-pipe formats a stream. Other leaves without JSON do not inherit it.

### Report details

Direct projects/status fields: generated_at, filter, include_global, include_unregistered, include_meta, runtime_ok, runtime_error, runtime_checked_at, runtime_last_ok_at, runtime_reset_at, runtime_reset_count, runtime_reset_summary, runtime_reset_changes, runtime_last_repair_at, runtime_repair_action, runtime_repair_outcome, runtime_next_step, projects[]. Optional detail_level:summary selects summary projection. Project records use summary/full projections with optional meta. Nullable recovery metadata is not liveness proof; nested engine/meta variants remain open.

Prune preview and apply are separate shapes. Apply includes runtimeOk/runtimeError, removedRegistryEntries[] (id/name/repoRoot/projectDir/reason), removedOrphanedProjects[] (project/workingDir/reason/containerCount), removedContainerCount. Preview includes dryRun:true, runtimeOk, registryCandidates[] (name/projectDir/reason), orphanedProjects[] and candidateContainerCount. It does not add runtimeError merely because apply has it. Orphan records are typed in the table below.

Doctor checks contain id/status/detail/durationMs; status is ok/warn/error. summary is string[]; counts are numbers. Additional diagnostics depend on version/check and remain specialized shapes.

Daemon status fields: status, running, api_ok, api_reachable, api_compatible, process_running, stale, stale_reason, issue, next_step, pid, socket_path, socket_exists, log_path, log_exists, launchd. Launchd is null or {installed,loaded,running,pid,exit_status,plist_path}. Unavailable/nullable observations must not be treated as proof of process absence or authority to signal a PID.

Env explain: key:string, available/secret:boolean, format:project_env_config_v1/legacy_env_contract; environment/effective_scope/source:string|null; requested_scope:string, target:host/compose, delivered_to/precedence:string[]. It emits no value.

Env list: project and env_selection (requested/default/effective selections, overlay_path, overlay_exists). Modern YAML adds format:project_env_config_v1, selected_scope, scopes, files, unknown_scopes, status/storage descriptions, vars[], missing_required. Legacy reports have storage/status, materialization and key projections. Rows in vars[] contain key/required/source/services/resolved_from/storage/value. Secret values are masked unless show-secrets is explicitly selected; ordinary plaintext is not thereby hidden. Modern reports include materialized when show-secrets is selected, otherwise materialized_keys. Legacy reports additionally contain warnings[] (kind/key/overlay_path/services/message). CLI reports differ from MCP's narrower value-free keys projection. Nested modern/legacy variants remain versioned report shapes; application values are not new stable reference keys.

## Compose/Loki log records

Logs JSON is newline-delimited events, not an array or envelope. Finite snapshots and follow share vocabulary. Follow is default; no-follow requests finite output. Omitted tail falls back to 200. JSON conflicts with pretty; compose conflicts with explicit Loki selection (loki/services/query/since/until); follow with until refuses.

| Event field | Presence / type |
| --- | --- |
| type | required start/log/heartbeat/error/end |
| ts | required string; ISO generation time or log entry timestamp |
| backend | optional in declared type; builders include compose/loki |
| project/branch | optional strings, omitted without context |
| services | optional string[], start context when supplied |
| follow | optional boolean; start builder includes it |
| since/until | optional strings, start context when supplied |
| entry | optional LogJsonEntry; log includes it |
| message | optional string; error includes it |
| reason | optional string; end includes nonempty reason |

Compose ends with eof or exit:<code>. Loki finite snapshots can end without reason; handled query failure emits error/end(error), follow ends closed/error. Error can precede start. Heartbeat has a builder, but these emitters do not establish periodic delivery. End settles a stream, not a workload.

| Entry field | Type / meaning |
| --- | --- |
| source | required compose/loki |
| message/raw | required strings: parsed message/original line |
| stream | optional stdout/stderr, Compose |
| project/service/instance | optional strings from context/prefix/labels |
| labels | optional string-to-string map, Loki |
| timestamp | optional ISO string |
| timestamp_ns | optional nanosecond timestamp string, not number |
| level | optional debug/info/warn/error after normalization |
| fields | optional string-to-string map of application fields |

Optional fields are omitted, not declared nullable. Map keys are open application data. The TypeScript declaration is not a runtime-validated closed JSON schema. Global logs has no JSON option.

## Session JSON-lines

Panes/capture/tail are tmux inspection surfaces and default to JSON unless pretty is selected. Capture/tail default to active target and 200 lines. Tail defaults interval-ms to 500 and max-ms to 5000. JSON and pretty together refuse. Panes snapshots emit start, log per pane, end(snapshot); capture emits log per captured line and end(snapshot). Tail emits changes and a finite budget ends with timeout. Refusals can precede event creation.

All events have type start/log/error/end, ts:string (ISO), session:string. Pane logs add pane:{target:string,active:boolean,windowIndex:number,windowName:string,paneIndex:number,command:string,path:string|null}. Capture/tail events also have target:string, lines:number, follow:boolean, optional intervalMs/maxMs:number. Log adds line:string; error adds message:string; end may add reason:string. These are separate from project log entry/backend events.

## Remaining limits

Leaf/flag presence is reconciled. Handler defaults outside the reviewed tables are not an exhaustive semantic audit. Engine rows, optional diagnostic subtypes, listing metadata, update success variants, nested env variants and candidate reports remain bounded open/specialized shapes. No closed schema, backend parity, client-loading proof or installed runtime acceptance is claimed. Config-file/MCP field work remains in the separate audit. Private compiler/daemon/guest/provider protocols and retired APIs are excluded.

## v5 native support limits

The inventory preserves retained Compose contracts. A listed flag is not proof of native admission. next.5 has no project task leaves; no newer task/target contract is backported.

Authored native projects require explicit native backend selection on macOS, separately prepared matching provider/runtime, absolute native binary and private native home. The pinned TypeScript authored frontend admits whole-project foreground up/restart, owner-mediated down and explicit bounded recovery, saved-run ps, finite service logs with no-follow, noninteractive service exec and one-off run at source level. Up/restart refuse detach/JSON and service subsets. Source/storage/routing/network/lifecycle admission remains bounded by the pinned authored-command guide. This is experimental support, not Compose parity.

Authored native ps JSON uses the shared envelope: data.backend:native, status:not_started/pending/runtime_not_running/observed, run/phase:string|null, items[]. Authored items have service/container/state:string, health:string|null, exitCode:number|null. The separate legacy native projection has statuses not_started/runtime_not_running/observed/owner_unconfirmed/runtime_degraded and item fields service:string, container:string|null, phase/state:string, health:string|null, exitCode:number|null. Fresh observations supply health/state; saved readiness/phase is historical. Ownership uncertainty can refuse.

The legacy native graph logs path returns bare {backend:native,run,service,container,stdout,stderr,truncated}; strings except truncated:boolean (container reflects selected owned row). Authored finite logs uses the same top-level names with container:string; neither should be parsed as Compose/Loki events. Authored service grammar is [A-Za-z0-9_.-]{1,128}, and tail is an integer 1–1000, default 200. Only bounded service/no-follow/tail/JSON selection is admitted; profiles, explicit backend overrides, service lists, query/time filters and pretty refuse. The retained legacy native Compose frontend has narrower admissions than authored native: do not borrow authored run/restart support.

### Candidate-only DNS

The source hint v5.hack.gy is an example suffix, not a fixed literal. Omission uses configured **custom** global default_domain; an unset/built-in default does not silently claim hack.local/hack/hack.gy.

All three leaves require explicit macOS native candidate selection. Preview performs inspection, not host writes. Custom preview JSON: {ok:true,data:{domain,status,dnsmasqPath,resolverPath,receiptPath,address,activation}}. Fields are strings except activation:string[]; status available/active describes disk/receipt state, not live DNS proof.

Explicit hack.local preview returns a route report with dnsmasqPath/resolverPath/receiptPath:string, receiptState nullable, status current/repairable/refused. Current adds relayPort and optional command; repairable adds oldLine/newLine/resolverAction/relayPort/command; refused adds reason/detail and optional command. Preview can exit 0 with refused data.status.

Activate has no JSON and refuses hack.local, which uses doctor repair. Making a new custom claim requires interactive confirmation/admin authorization and unchanged inspected inputs; an already active claim is verified. Deactivate has no JSON: it removes only an owned custom claim and verifies fallback resolution, or explicitly rolls back hack.local repair. Changed/unproven inputs refuse. There is no yes/force bypass flag.

### Other v5 report differences

Config validate/plan print candidate reports directly, with transport_version/ok and diagnostics or success projections. Transport failure is {transport_version:1,ok:false,error:{code,message}}. Import dry-run and adopt preview print complete/fields reports; completed adoption has its own operation report. These evolving CLI projections do not publish internal compiler transport, plan, journal or guest DTOs.

Listing can add filter_redacted:true; v4 lacks this. Doctor adds check-dependent supersededRoots/hackLocalRoute/envKey diagnostics; nested variants remain specialized.

Sensitive env-get failures use fixed stderr-only text and status 1, even if unsupported JSON was supplied. This does not add a JSON option.

## Parent command sections

These sections are also present in the pinned reference. Some parents handle direct invocation (for example projects/session); namespace options do not pass to children. Counts above count terminal leaves only.

| Section | Own options; all also have global/built-ins |
| --- | --- |
| `hack project` |  |
| `hack project owner` |  |
| `hack branch` |  |
| `hack config` |  |
| `hack session` |  |
| `hack global` |  |
| `hack global dns` |  |
| `hack projects` | `--project <name>`; `--details`; `--summary`; `--timings`; `--no-daemon`; `--meta`; `--include-global`; `--all`; `--json` |
| `hack daemon` |  |
| `hack mcp` |  |
| `hack setup` |  |
| `hack agent` |  |
| `hack secrets` | `--service <service>` |
| `hack env` |  |
| `hack env backend` |  |
| `hack host` |  |

## Stable shared error codes

`E_DOCKER_UNAVAILABLE`, `E_GLOBAL_INFRA_DOWN`, `E_CONFIG_PARSE`, `E_CONFIG_INVALID`, `E_PROJECT_NOT_FOUND`, `E_NATIVE_PROJECT_CONFLICT`, `E_NATIVE_PROJECT_UNSUPPORTED`, `E_NATIVE_COMPOSE_PROXY_ACCESS`, `E_SERVICE_NOT_FOUND`, `E_COMPOSE_FAILED`, `E_STARTUP_INCOMPLETE`, `E_DEPENDENCY_BOOTSTRAP_FAILED`, `E_STARTUP_TIMEOUT`, `E_LIFECYCLE_FAILED`, `E_ENV_KEY_MISSING`, `E_PERMISSION`, `E_INTERACTIVE_REQUIRED`, `E_USAGE`, `E_UNEXPECTED`. Optional error.detail is unknown; direct-return failures need not use this envelope.

Update success fields: ok:true, current/latest:string, updateAvailable/installed:boolean, target:{platform:string,arch:string}, binaryPath/assetsDir:string, optional mutagen provisioning report. Handled failure is {ok:false,error:string}. 

DNS relay-report fields: relayPort:number; oldLine/newLine/command/detail:string; resolverAction:keep/create; receiptState is null or the retained repair receipt state. Custom address is a string. Report paths/lines are descriptive and do not grant ownership or repair authority.

## Typed corrections for generated value placeholders

These were display-only mismatches, not missing flags. The generated `<value>` placeholder means a value is required when the flag is used; none of these options has a short alias or an OptionSpec defaultValue.

| Command / exact spelling | Type | Omission / handler behavior |
| --- | --- | --- |
| `hack usage --interval <value>` | number, milliseconds | Omitted: configured usage.watchIntervalMs. Finite positive input is floored and clamped to at least 250 ms; nonpositive/invalid resolved interval falls back to 2000 ms. Watch uses human redraw output. |
| `hack session start [project] --name <value>` | string; workspace suffix | Omitted: reuse base workspace unless --new requests the next numeric suffix. A truthy supplied suffix is passed to the session-name builder; it is not a project selector. |
| `hack config adopt --branch <value>` | string; exact existing branch instance | Omitted: no explicit branch option. This selects existing adoption identity; it does not create a branch or inherit to other config leaves. |

## Prune preview field types

The preview uses the shared success envelope. Its data object is:

| Field | Type / meaning |
| --- | --- |
| dryRun | literal true |
| runtimeOk | boolean; whether runtime inventory succeeded |
| registryCandidates | array of {name:string, projectDir:string, reason:string} |
| orphanedProjects | array of {project:string, workingDir:string|null, reason:string, containerIds:readonly string[]} |
| candidateContainerCount | number; sum of orphan container IDs |

Preview omits runtimeError. A successful envelope describes a completed preview, not a guarantee that the runtime is healthy. Apply has the distinct removal fields already listed above. Neither form is permission to delete resources.

## Exact native admission and launcher boundary

All claims here are **source admission**, not runtime-verified or installed-release support.

| Path at next.5 | Exact evidence and boundary |
| --- | --- |
| Authored TypeScript frontend | src/lib/native-compose-command.ts:2380 dispatches selected authored input to tryNativeAuthoredCommand. src/lib/native-authored-command.ts:273 commandMode explicitly admits run through assertCommandOptions; :182 assertForegroundOptions admits restart. RUNNERS at :602 and :621 call the separate authored one-off and restart implementations. |
| Authored run | src/lib/native-authored-command.ts:765 assertCommandOptions requires macOS, a single service, nonempty literal argv and optional absolute workdir; rejects JSON, profiles/env overrides, service lists, recover/detach/log options and unsupported options. src/backends/native-authored-exec-options.ts:3 caps argv at 256, each argument at 16 KiB, total at 64 KiB, forbids NUL; workdir at most 4096 bytes. Command execution also requires closed stdin/no TTY and a proven live authored owner; no generic execution fallback is promised. |
| Authored restart | src/lib/native-authored-command.ts:527 runRestart uses restartNativeAuthoredProject, sequencing proven owned stop before fresh foreground startup. :182 refuses detach/JSON/recover/subsets/command/workdir/log options and non-macOS. Failure can leave the project stopped; no automatic replay or cross-backend restart guarantee. |
| Legacy native graph | A separate backend/source path, not evidence for authored one-off run/restart. Its retained public frontend refusal boundary must remain separate; graph-internal operation names are not public project-command support. |
| Relocatable candidate launcher | scripts/hack-v5.sh:4–15 requires absolute HACK_NATIVE_HOME and adjacent executable hack-cli/hack-native; sets native backend/binary and forwards argv to adjacent hack-cli. It has no independent command-admission matrix. This establishes source forwarding only, not that every published/installed bundle contains a matching capable frontend/executor/provider. |
| Checkout launcher | hack-local:1–23 is a separate checkout-bound entry point into hack-runtime-candidate, not the relocatable public frontend or an installed-artifact qualification. |

The pinned comparison table and authored dispatch describe different admission boundaries. Use the source-specific distinctions above; source admission does not qualify a provider or application. Installed matching-bundle acceptance and live provider behavior remain unverified. Task leaves absent at next.5 remain excluded.


---

<!-- Editorial source: docs/versions/v5/reference/project-env-reports.md; based on 28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc; source label: next.5 field audit; URL: https://hack.foo/docs/v5/reference/project-env-reports -->
# Project inventory and environment reports

This field inventory was audited against the `5.0.0-next.5` source and has not been requalified against later prereleases. The [generated command reference](/docs/v5/reference/cli) and the pinned runtime guides take precedence where they differ.

Public report shapes at `28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc`. This page describes CLI projections, not private daemon/compiler/guest protocols. See [Command and output contracts](/docs/v5/reference/command-contracts) for envelope and exit semantics.

## Project inventory

`hack projects --json` and status inventory emit a bare report. `--summary` selects the summary projection; `--meta` adds optional metadata. Missing or null observations mean unavailable/unknown, not proof that resources or processes do not exist. Runtime health in report data is separate from exit status.

| Selection | Report effect |
| --- | --- |
| Default full listing | projects[] contains serialized project views, runtime observations, sessions, worktrees and lifecycle descriptions |
| --summary | detail_level is summary; rows contain identity/status and counts instead of full nested runtime views |
| --meta | meta is present on each row; it may be null |

### Project metadata types

The following declarations are copied from the pinned public metadata producers. Optional properties may be omitted. Nullable properties are present but may be null. Raw metadata contains repository paths and command descriptions; it is not a redacted sharing format. Ownership shared/broker names are retained compatibility metadata, not hosted team management or an access-control API.

[Pinned src/lib/project-meta.ts](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/lib/project-meta.ts).

```ts
export type GitWorktreeMeta = {
  readonly path: string;
  readonly head: string | null;
  readonly branch: string | null;
  readonly detached: boolean;
};

export type GitMeta = {
  readonly isRepo: boolean;
  readonly head: string | null;
  readonly branch: string | null;
  readonly detached: boolean | null;
  readonly dirty: boolean | null;
  readonly localBranchCount: number | null;
  readonly worktrees: readonly GitWorktreeMeta[] | null;
  readonly error: string | null;
};

export type HackBranchesMeta = {
  readonly path: string;
  readonly parseError: string | null;
  readonly branches: readonly BranchEntry[];
};

export type EnvVarMeta = {
  readonly key: string;
  readonly required: boolean;
  readonly source: HackEnvSource;
  readonly services: readonly string[] | null;
  readonly description?: string;
  readonly resolvedFrom:
    | "dotenv"
    | "process"
    | "keychain"
    | "portable_backend"
    | null;
  readonly hasValue: boolean;
};

export type EnvMeta = {
  readonly contractPath: string;
  readonly contractExists: boolean;
  readonly contractParseError: string | null;
  readonly vars: readonly EnvVarMeta[];
  readonly missingRequired: readonly string[];
};

export type SessionsMeta = {
  readonly sessions: readonly MuxSession[];
};

export type ComposeBuildServiceMeta = {
  readonly service: string;
  readonly build: boolean;
  readonly context: string | null;
  readonly dockerfile: string | null;
  readonly dockerfilePath: string | null;
  readonly dockerfileExists: boolean | null;
};

export type ComposeBuildMeta = {
  readonly services: readonly ComposeBuildServiceMeta[];
};

export type ProjectMeta = {
  readonly ownership: ProjectOwnershipConfig | null;
  readonly configError: string | null;
  readonly git: GitMeta;
  readonly hackBranches: HackBranchesMeta;
  readonly env: EnvMeta;
  readonly sessions: SessionsMeta;
  readonly composeBuild: ComposeBuildMeta;
};

```

[Pinned src/lib/branches.ts](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/lib/branches.ts).

```ts
export type BranchEntry = {
  readonly name: string;
  readonly slug: string;
  readonly note?: string;
  readonly created_at?: string;
  readonly last_used_at?: string;
};

```

[Pinned src/mux/mux-backend.ts](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/mux/mux-backend.ts).

```ts
export type MuxBackendName = "tmux" | "zellij";

export type MuxSession = {
  readonly backend: MuxBackendName;
  readonly name: string;
  readonly attached: boolean | null;
  readonly path: string | null;
  readonly windows: number | null;
  readonly createdAt: string | null;
};

```

[Pinned src/lib/hack-env.ts](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/lib/hack-env.ts).

```ts
export type HackEnvSource = "plain_env" | "keychain";

```

[Pinned src/lib/project.ts](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/lib/project.ts).

```ts
export type ProjectOwnershipMode = "local" | "shared";

export type ProjectOwnershipOwnerType = "user" | "team" | "organization";

export type ProjectOwnershipManager = "local" | "broker";

export interface ProjectOwnershipConfig {
  readonly mode: ProjectOwnershipMode;
  readonly ownerType: ProjectOwnershipOwnerType;
  readonly ownerId: string | null;
  readonly managedBy: ProjectOwnershipManager;
}

```

### Serialized runtime observations

The public runtime projection uses snake_case names and arrays, not the internal Map representation. It contains project:string, working_dir:string|null and services[]. Each service has service:string and containers[]. Container fields: id/state/status/name/ports:string; working_dir/image:string|null; labels:string-map|null; mounts[] and networks[]. Mount fields: type/source/destination/mode:string, name:string|null, rw:boolean|null. Network fields: name:string, ip_address/gateway:string|null, aliases:string[]. Labels and engine state strings remain open values.

The raw ps items[] engine report is a different surface from this normalized projects[].runtime projection. Do not infer that an open engine report makes Hack-owned wrapper fields unknowable.

### Sessions and lifecycle in full project rows

Full-row sessions[] uses name:string, backend:tmux|zellij, source:hack|external, attached:boolean, path:string|null, windows:number|null and created_at:number|null. This numeric creation observation is distinct from the metadata MuxSession.createdAt string|null above; do not silently convert one contract into the other.

worktrees is null or an array of path:string, branch:string|null and last_seen_at:string. lifecycle is null or an object with up_before/up_after/down_before/down_after arrays and processes[]. Hook rows carry name:string|null, command:string, cwd:string|null and service:string; persistent:true is emitted only when true. Process rows require name/command/service:string and cwd:string|null.

## Environment list reports

Raw CLI env reports can contain values. Default secret masking does not make an entire report value-free: plaintext values still appear. Use a value-free inspection interface for agent metadata, and avoid copying raw env reports into logs or messages. These examples describe shapes only and contain no real values.

The legacy contract and managed YAML contract are separate variants. Both use vars[] in raw CLI output. MCP env.keys, where available, returns a narrower keys[] projection and withholds raw stdout/stderr.

| Field | Legacy contract | Managed YAML |
| --- | --- | --- |
| project | string | string |
| env_selection | requested/default/effective/overlay_path:string or null; overlay_exists:boolean | same public field names |
| format | omitted in legacy list | project_env_config_v1 |
| status | classification plus summary/detail strings | YAML classification plus summary/detail strings |
| storage | legacy contract/local/portable compatibility report | canonical YAML/project-key report; contract member is not added by this builder |
| warnings | array of warning records | not emitted by modern list builder |
| vars | array of resolved variable records | array of selected-scope records |
| missing_required | string[] | empty array in modern list builder |
| files/scopes/unknown_scopes/selected_scope | omitted | string[]/string[]/string[]/string |
| materialized_keys | omitted | sorted string[] unless values were explicitly requested |
| materialized | omitted | string map only on explicit value-output path |

### Variable records

| Field | Legacy | Managed YAML |
| --- | --- | --- |
| key | string | string |
| required | boolean from contract | false |
| source | plain_env or keychain | plain_env or keychain (secret marker) |
| services | string[] or null | winning non-global scope as one-element array, otherwise null |
| resolved_from | dotenv/process/keychain/portable_backend or null | project_env_config |
| storage | HackEnvValueStorageJson | kind/plaintext-or-secret, backend/project_env_config, location:string, mode/yaml, trust_model:string, classification |
| value | string or null; secret default mask is *** | string; secret default mask is *** |

The source field is a compatibility label: keychain on a managed YAML record marks a secret; it does not mean that YAML ciphertext moved to OS keychain storage. Files and scopes are selected by the matching version parser. v4 rejects YAML null; v5 uses it as a removal marker.

### Legacy storage and classification types

These type names describe serialized report metadata. A retained backend/classification value is not qualification of every backend or hosted shared-state feature. Modern YAML storage has its own concrete projection described above.

```ts
export type HackEnvSharedState =
  | "local_only"
  | "plaintext_compatible"
  | "portable_bundle"
  | "broker_managed";
```

```ts
export type HackEnvJsonClassification = {
  readonly trust_model: string;
  readonly custody: string;
  readonly portability: string;
  readonly shared_state: HackEnvSharedState;
};
```

```ts
export type HackEnvValueStorageJson = {
  readonly kind: "plaintext" | "secret";
  readonly backend: string;
  readonly location: string;
  readonly mode: string;
  readonly trust_model: string;
  readonly classification: HackEnvJsonClassification;
};
```

```ts
export type HackEnvStorageJson = {
  readonly contract: {
    readonly path: string;
    readonly trust_model: string;
    readonly classification: HackEnvJsonClassification;
  };
  readonly local_plaintext: {
    readonly path: string;
    readonly exists: boolean;
    readonly trust_model: string;
    readonly mirrored_to_backend: boolean;
    readonly fallback: {
      readonly enabled: boolean;
      readonly source: string;
      readonly trust_model: string;
      readonly classification: HackEnvJsonClassification;
    };
    readonly classification: HackEnvJsonClassification;
  };
  readonly local_secrets: {
    readonly backend: string;
    readonly location: string;
    readonly mode: string;
    readonly provider: string | null;
    readonly trust_model: string;
    readonly classification: HackEnvJsonClassification;
  };
  readonly portable_state: {
    readonly status: string;
    readonly trust_model: string;
    readonly message: string;
    readonly classification: HackEnvJsonClassification;
  };
  readonly compatibility_mode: {
    readonly plaintext_target: string;
    readonly secret_backend: string;
    readonly plaintext_mirrored_to_backend: boolean;
    readonly summary: string;
  };
};
```

```ts
export type HackEnvAggregateStatusJson = HackEnvJsonClassification & {
  readonly summary: string;
  readonly detail: string;
};
```

### Legacy warnings

Warnings contain kind:overlay_plaintext_ignored_for_secret_contract, key:string, overlay_path:string, services:string[]|null and message:string. This is a report of contract/source mismatch; it is not a secret value. Missing-required names are reported separately.

## Scope and provenance

[Project view serializer](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/lib/project-views.ts), [runtime serializer](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/lib/runtime-projects.ts), [env output builders](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/commands/env.ts), and [env storage serializers](https://github.com/hack-dance/hack/blob/28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc/src/lib/hack-env-status.ts) are the authority for these projections. This documents public fields from source, not successful runtime, cloud or client qualification. Unknown application map keys and external engine values are intentionally open; owned report fields above are not treated as open merely because the JSON emitter returns `Record<string, unknown>`.

## Applying environment changes

`hack env apply` is a service restart wrapper. It does not return the env-list report above: it forwards restart, a concrete service, --path and selected env/JSON arguments, then returns the child exit code/output. Service/JSON forms remain subject to that version and backend admission. This is not an atomic multi-service env transaction.

next.5 validates the service and env selection before forwarding. A selected base/default form becomes the validated base argument; raw invalid input is not forwarded. The published native launcher does not gain subset/JSON restart support from this wrapper.

## Listing field types

--summary and --timings require --json. --summary cannot be combined with --meta or --details. Timings are a separate numeric diagnostic record on stderr; they do not change stdout into a timing envelope.

| Top-level field | Type / presence |
| --- | --- |
| generated_at | string timestamp |
| filter | string or null |
| include_global/include_unregistered/include_meta | boolean |
| detail_level | summary when summary selected; otherwise omitted |
| runtime_ok | boolean |
| runtime_error/runtime_checked_at/runtime_last_ok_at/runtime_reset_at/runtime_reset_summary/runtime_last_repair_at/runtime_repair_action/runtime_next_step | string or null |
| runtime_reset_count | number |
| runtime_reset_changes | string[] |
| runtime_repair_outcome | stabilized, manual_action_required or null |
| projects | project row array |

filter_redacted:true is emitted only when a filter applies but its derived label must not be echoed. This field is absent from v4.

Summary rows contain project_id:string|null; name:string; repo_root/dev_host:string|null; status:running/stopped/missing/unregistered/unavailable/unknown; runtime_status below; defined_service_count:number|null; host_process_count/container_count/running_container_count/branch_count/session_count:number. Counts describe the gathered snapshot, not ongoing ownership or liveness.

runtime_status is running/stopped/missing/unknown/not_configured/unavailable in this version.

Full and summary rows are separate projections. Full rows share project_id/name/repo_root/dev_host/status/runtime_status, but omit the summary-only defined_service_count, host_process_count, container_count, running_container_count, branch_count and session_count. Full rows contain project_dir:string|null; ownership:compatibility object|null with mode/owner_type/owner_id/managed_by; defined_services/extensions_enabled/features:string[]|null; service_hosts:string-to-string-array map|null; runtime_configured:boolean|null; normalized runtime|null; branch_runtime array of branch:string plus runtime; sessions/worktrees/lifecycle as described above; kind:registered/unregistered. The ownership data is descriptive, not authorization for hosted features.

Either v5 projection can add input_diagnostic; when present, it contains code and message strings for authored/legacy input selection. It is omitted on normal rows; v4 does not emit it.

## Managed YAML classification values

Managed YAML does not use the legacy classification enum above. The exact classification groups emitted by the modern builder are:

| Group | trust_model | custody | portability | shared_state |
| --- | --- | --- | --- | --- |
| YAML aggregate/portable state | repo_managed_env_config | repo_tracked_env_config | portable_with_out_of_band_key | repo_managed_overlay |
| Compatibility plaintext | compatibility_output | local_plaintext_file | local_only | compatibility_only |
| Local project key | local_secret_key | local_secret_key | local_only | local_only |


---

<!-- Editorial source: docs/versions/v5/reference/diagnostic-reports.md; based on 28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc; source label: next.5 field audit; URL: https://hack.foo/docs/v5/reference/diagnostic-reports -->
# Diagnostic reports

This field inventory was audited against the `5.0.0-next.5` source and has not been requalified against later prereleases. The [generated command reference](/docs/v5/reference/cli) and the pinned runtime guides take precedence where they differ.

Pinned source: `28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc`. Consumer-visible JSON projections only. R = required; optional means omitted, never implicitly null. A listed null union is emitted as null. Arrays may be empty unless stated otherwise. Source admission is not runtime/provider qualification. All examples are synthetic; paths and values are placeholders.

The retired setup-sync report is excluded from this reference; `hack setup sync` refuses in v5. See [Agent integrations](/docs/v5/integrations).

## Report and exit rules

Doctor emits the shared `{ok:true,data:DoctorJsonData}` envelope even when a completed check has status error; those checks make the command exit 1. Warnings alone do not. Top-level thrown failures can instead use the shared failure envelope. A diagnostic report is not repair or deletion authority.

Update JSON is its own UpdateOutput union. Handled ok:false has a string error and exits 1; ok:true exits 0. The optional mutagen report appears after a successful update installation. An already-available dependency yields available:true/installed:false/path:string; successful provisioning yields available:true and the actual installation result. Provisioning failure can still leave top-level ok:true/installed:true; inspect mutagen.warning/available. Path null means no dependency found. Omitted warning is distinct from an empty string.  A synthetic provisioning fragment is `{"available":false,"installed":false,"path":null,"warning":"<provisioning diagnostic>"}`.

Host ps emits a bare HostPsReport and returns 0 after gathering observations, including when the process snapshot is unavailable. It does not return an envelope. snapshotAvailable:false and nullable live metrics mean unknown observation, not proof of stopped processes. Command records carry no argv, environment or output. Record parsing strips unrecognized properties. All current serializer fields are documented below despite its broad inferred/Record return types.


Next.5 update refuses the explicitly selected native candidate with its handled ok:false/error:string result. No broader native self-update capability is implied.

## Doctor diagnostic meaning

supersededRoots appears only on the superseded Caddy roots check and only when inventory succeeded. The exact check id is superseded caddy roots. Absence is not count 0; unavailable inventory is a warning. count counts unique superseded DER fingerprints; expired and notYetValid are subsets. sha256 contains sorted uppercase public SHA-256 fingerprints, capped at 32, so its length can be less than count. The current root is excluded; this report neither establishes trust nor selects certificates for removal.

hackLocalRoute appears on the native hack.local route check. current maps to doctor ok; repairable/refused map to warn. The serializer emits the three precise variants below: paths are descriptive strings, receiptState is nullable, and oldLine/newLine are validated managed-form lines, not arbitrary file contents. The exact check id is native hack.local route; failed dependency inspection can produce a warning check with hackLocalRoute omitted. This is not a private receipt contract.

envKey appears only on the env key check (id: env key), and remains omitted if inspection cannot produce that projection. findings are ordered most severe first; aggregate status is their highest severity. A clean result has one env-key-ok or env-key-absent finding. subject is a fixed label or project-relative subject; remedy is a string suggestion or null. env-key-ok and env-key-absent have status ok and remedy null. Symlink/not-regular/unreadable/tracked/public-path findings are error; weak-permissions/wrong-owner/wrong-length/low-entropy are warn. Neither bytes nor absolute key paths are exposed; doctor never runs the remedy. EnvKeyCandidate/inspection inputs are private and omitted here.

## Host telemetry interpretation

All HostCommandObservation fields are emitted, including explicit nulls. Stored status is running/exited/cancelled/timed_out; the observer preserves completed statuses and can replace running with unknown/orphaned/interrupted. unknown means snapshot or wrapper birth identity unavailable. running requires the original wrapper identity; orphaned means wrapper absent but original child identified; interrupted means neither identified while an unfinished record remains.

Identity is PID plus birth/start time, not PID alone. observedPids includes the observed child tree and proven owned-group members. unverifiedGroupPids is populated only when child identity is unavailable but matching numeric group members exist; it confers no signaling authority. Group-members attention takes precedence over wrapper-loss attention. Persistent orphaned commands use persistent_wrapper_lost; other orphaned commands use wrapper_lost; interrupted uses completion_unknown.

elapsedMs on command rows is wall time from stored start to finish/now, clamped at zero. cpuTimeMs/maxRssBytes are stored child-completion metrics; liveCpuTimeMs/liveRssBytes sum current proven members or are null without child identity. cpuAccounting labels stored-finish versus live-snapshot mode; it does not make absent metrics non-null.

Lifecycle rows come from registered projects/worktrees with persisted sessions. owned-healthy/owned-stale/legacy-owned allow proven group selection; absent/foreign/unknown do not. Unknown can mean missing backend or failed inspection. With owned state and an available snapshot, an empty member set gives live CPU/RSS 0, while elapsedMs is null. Without owned state/snapshot, live CPU/RSS are null. Absent sessions add session_absent_review_state; foreign adds ownership_unverified; other attention is null. Definition source is persisted, not proof current definitions were compared successfully. No private state-file/ownership-token schema is published. Millisecond metrics are durations/CPU time; RSS fields are bytes.

## Candidate CLI reports

These leaves exist only at next.5 and remain experimental. validate --file prints ValidateFileSuccess or a diagnostic failure; discovery validation prints ValidateResolvedSuccess. Each exits 0 for ok:true and 1 for ok:false. Validate does not read managed env values or start workloads. plan prints PlanSuccess, but exits 0 only when ok:true AND environment_plan.complete AND file_plan.complete is not false. Therefore ok:true with incomplete bindings is an exit-1 report, not successful execution or runtime admission. Transport/request exceptions print CandidateTransportFailure and exit 1. Argument errors can use the top-level shared E_USAGE failure instead.

The CLI prints only its returned result. The helper-only envelope is stripped before serialization. routing_inputs_required is an intermediate probe signal: project preparation consumes it and resolves routing again; it is not added to these final report tables. Compiler request/handshake, raw authored input, private candidates, environment metadata input envelopes, guest/provider DTOs and journals are not public CLI report objects.

The CLI wrapper exposes plan as an opaque compiler-owned `Record<string, unknown>`. Its internal producer Plan DTO is not a stable public API here. Authored document shapes are documented separately in [Authored schema fields](/docs/v5/reference/authored-schema-fields); the explicit CLI wrapper fields below remain separate report contracts.

NativeConfigDiagnostic.code is a nonempty string; ImportField.code is declared string. Neither is a declared closed enum. NativeConfigDiagnostic line/column are positive safe integers, pointer is a JSON pointer (empty for document root); compile diagnostics may omit document, while resolved and environment/file planning diagnostics require a recognized document role. Messages are strings, never permission to run suggested actions.

EnvironmentPlan maps workload and destination names to typed bindings. Managed bindings expose names/scope/secret metadata, never resolved secret values. Literal/default bindings can contain authored plaintext; runtime bindings contain generated public metadata. Host bindings reject runtime kind. Host report keys identify declared hooks/process targets, not arbitrary backend objects. FilePlan reports bindings without reading file material; uid/gid are omitted unless supplied, never implicitly null. Plan/environment/file complete flags describe offline completeness only. Current file-plan diagnostics are specifically missing_env_reference at project pointers; they are not application errors. File target paths are normalized; mode is a four-character octal string matching 0[0-7]{3} (fallback 0444). File uid/gid are integers 0–4294967295 when supplied. Resolved endpoint/route ports are integers 1–65535. These are report shape constraints, not proof of runtime admission.

RoutingResolution is a URL/domain preview: aliases/routes are caller-named maps with closed value types. No DNS, trust, OAuth or application acceptance is established. Optional branch is omitted when absent; oauth_alias is explicitly null when unavailable. HostBindingResolution bindings and removed maps have finite origin choices, and removed records overridden/deleted authored bindings rather than authorizing host mutations.

Import requires dry-run and prints only NativeImportReport, never candidate. report_version is 1; complete is a preview result, adoption always not_performed. Fields are sorted by document then pointer by nativeImportResult. target is optional, typically present on mapped exact/normalized rows; a refused row may retain a target from an earlier mapping, so it is not mutually exclusive with refused. Code is a string namespace, not arbitrary source values. Refusals use fixed root coordinates when no specific location can be exposed. Complete false exits 1; true exits 0. The preview neither exports inputs nor adopts resources.

Adopt preview differs from import: it has no report_version and adds containers/volumes/stop only when complete:true. A refused preview omits all three. Requested stop in dry-run is prospective, not proof any container stopped. Apply/recover/rollback success is AdoptionApplied; original_data is always retained. A nonzero stop can return before any success JSON is emitted. Other handled adoption errors become E_CONFIG_INVALID in the shared error envelope. Optional error.detail.legacy_adoption_publication_refusal is exactly LegacyComposePublicationRefusal; absence is omitted. These closed stage/reason labels convey a last reached boundary, not recovery authority or a private journal schema.

The generated model keeps Workload image/build optional at the TypeScript representation level. Valid authored input requires exactly one image/build variant; schemas constrain pull_policy accordingly. This model table documents report types and does not loosen authored schema validation or claim all normalized capabilities are executable.

## Synthetic examples

Doctor warning fragment (a completed warning is not an error exit):

~~~json
{"id":"env key","status":"warn","detail":"<fixed diagnostic>","durationMs":1,"envKey":{"status":"warn","findings":[{"code":"env-key-weak-permissions","status":"warn","subject":"<relative-subject>","remedy":"<suggested action>"}]}}
~~~

Refused import report (exit 1, no candidate material):

~~~json
{"report_version":1,"complete":false,"adoption":"not_performed","fields":[{"document":"config","pointer":"","line":1,"column":1,"status":"refused","code":"unsafe_changed_or_unavailable_input"}]}
~~~

## Typed payload records

Each numbered variant below is a distinct object alternative; nested named records are listed separately. Field counts count table rows, including repeated fields in distinct alternatives. Alias definitions and their literal choices are counted separately.

### DoctorResult

Source: `src/commands/doctor.ts:1388 (finishDoctorJson)`.

| Field | Type | Presence |
| --- | --- | --- |
| `ok` | `true` | required |
| `data` | `DoctorJsonData` | required |


### DoctorJsonData.counts

Source: `src/commands/doctor.ts:1345 (DoctorJsonData)`.

| Field | Type | Presence |
| --- | --- | --- |
| `ok` | `number` | required |
| `warn` | `number` | required |
| `error` | `number` | required |


### DoctorJsonData

Source: `src/commands/doctor.ts:1345 (DoctorJsonData)`.

| Field | Type | Presence |
| --- | --- | --- |
| `checks` | `DoctorJsonCheck[]` | required |
| `summary` | `string[]` | required |
| `counts` | `DoctorJsonData.counts` | required |


### DoctorJsonCheck

Source: `src/commands/doctor.ts:1332 (DoctorJsonCheck)`.

| Field | Type | Presence |
| --- | --- | --- |
| `id` | `string` | required |
| `status` | `CheckStatus` | required |
| `detail` | `string` | required |
| `durationMs` | `number` | required |
| `supersededRoots` | `SupersededRootInventory` | optional; omitted when absent |
| `hackLocalRoute` | `HackLocalRouteReport` | optional; omitted when absent |
| `envKey` | `EnvKeyInspection` | optional; omitted when absent |


### SupersededRootInventory

Source: `src/lib/mac-ca-trust.ts:23 (SupersededRootInventory)`.

| Field | Type | Presence |
| --- | --- | --- |
| `count` | `number` | required |
| `expired` | `number` | required |
| `notYetValid` | `number` | required |
| `sha256` | `string[]` | required |


### HackLocalRouteReport.current

Source: `src/lib/native-hack-local-route.ts:711 (reportHackLocalRoute)`.

| Field | Type | Presence |
| --- | --- | --- |
| `status` | `"current"` | required |
| `dnsmasqPath` | `string` | required |
| `resolverPath` | `string` | required |
| `receiptPath` | `string` | required |
| `receiptState` | `"pending" \| "applied" \| "rolled-back" \| "released" \| null` | required |
| `relayPort` | `number` | required |
| `command` | `string` | optional; only applied receipt emits rollback command |


### HackLocalRouteReport.repairable

Source: `src/lib/native-hack-local-route.ts:711 (reportHackLocalRoute)`.

| Field | Type | Presence |
| --- | --- | --- |
| `status` | `"repairable"` | required |
| `dnsmasqPath` | `string` | required |
| `resolverPath` | `string` | required |
| `receiptPath` | `string` | required |
| `receiptState` | `"pending" \| "applied" \| "rolled-back" \| "released" \| null` | required |
| `oldLine` | `string` | required |
| `newLine` | `string` | required |
| `resolverAction` | `"keep" \| "create"` | required |
| `relayPort` | `number` | required |
| `command` | `string` | required |


### HackLocalRouteReport.refused

Source: `src/lib/native-hack-local-route.ts:711 (reportHackLocalRoute)`.

| Field | Type | Presence |
| --- | --- | --- |
| `status` | `"refused"` | required |
| `dnsmasqPath` | `string` | required |
| `resolverPath` | `string` | required |
| `receiptPath` | `string` | required |
| `receiptState` | `"pending" \| "applied" \| "rolled-back" \| "released" \| null` | required |
| `reason` | `HackLocalRouteRefusal` | required |
| `detail` | `string` | required |
| `command` | `string` | optional; only pending-receipt adds rollback command |


### EnvKeyInspection

Source: `src/lib/doctor-env-key.ts:52 (EnvKeyInspection)`.

| Field | Type | Presence |
| --- | --- | --- |
| `status` | `EnvKeyFindingStatus` | required |
| `findings` | `EnvKeyFinding[]` | required |


### EnvKeyFinding

Source: `src/lib/doctor-env-key.ts:43 (EnvKeyFinding)`.

| Field | Type | Presence |
| --- | --- | --- |
| `code` | `EnvKeyDiagnosticCode` | required |
| `status` | `EnvKeyFindingStatus` | required |
| `subject` | `string` | required |
| `remedy` | `string \| null` | required |


### UpdateOutput — variant 1.target

Source: `src/commands/update.ts:418 (UpdateOutput)`.

| Field | Type | Presence |
| --- | --- | --- |
| `platform` | `string` | required |
| `arch` | `string` | required |


### UpdateOutput — variant 1

Source: `src/commands/update.ts:418 (UpdateOutput)`.

| Field | Type | Presence |
| --- | --- | --- |
| `ok` | `true` | required |
| `current` | `string` | required |
| `latest` | `string` | required |
| `updateAvailable` | `boolean` | required |
| `installed` | `boolean` | required |
| `target` | `UpdateOutput — variant 1.target` | required |
| `binaryPath` | `string` | required |
| `assetsDir` | `string` | required |
| `mutagen` | `MutagenProvisionResult` | optional; omitted when absent |


### UpdateOutput — variant 2

Source: `src/commands/update.ts:418 (UpdateOutput)`.

| Field | Type | Presence |
| --- | --- | --- |
| `ok` | `false` | required |
| `error` | `string` | required |


### MutagenProvisionResult

Source: `src/commands/update.ts:295 (MutagenProvisionResult)`.

| Field | Type | Presence |
| --- | --- | --- |
| `available` | `boolean` | required |
| `installed` | `boolean` | required |
| `path` | `string \| null` | required |
| `warning` | `string` | optional; omitted when absent |


### HostPsReport

Source: `src/commands/host-ps.ts:33 (hostPsCommand)`.

| Field | Type | Presence |
| --- | --- | --- |
| `generatedAt` | `string (ISO timestamp)` | required |
| `snapshotAvailable` | `boolean` | required |
| `commands` | `HostCommandObservation[]` | required |
| `lifecycle` | `LifecycleObservation[]` | required |


### HostCommandObservation

Source: `src/lib/host-command-observation.ts:242 (observeHostCommand)`.

| Field | Type | Presence |
| --- | --- | --- |
| `version` | `1` | required |
| `id` | `string (UUID)` | required |
| `project` | `string` | required |
| `projectRoot` | `string` | required |
| `executable` | `string (basename only)` | required |
| `wrapper` | `ProcessIdentity` | required |
| `child` | `ProcessIdentity` | required |
| `ownsProcessGroup` | `boolean` | required |
| `processGroupId` | `positive integer \| null` | required |
| `lifetime` | `"command" \| "persistent" \| "bounded"` | required |
| `timeoutMs` | `positive number \| null` | required |
| `startedAt` | `string (ISO timestamp)` | required |
| `finishedAt` | `string (ISO timestamp) \| null` | required |
| `status` | `"running" \| "exited" \| "cancelled" \| "timed_out" \| "unknown" \| "orphaned" \| "interrupted"` | required |
| `exitCode` | `integer \| null` | required |
| `cpuTimeMs` | `nonnegative number \| null` | required |
| `maxRssBytes` | `nonnegative number \| null` | required |
| `elapsedMs` | `nonnegative number` | required |
| `observedPids` | `number[]` | required |
| `unverifiedGroupPids` | `number[]` | required |
| `liveCpuTimeMs` | `number \| null` | required |
| `liveRssBytes` | `number \| null` | required |
| `cpuAccounting` | `"reaped_child" \| "live_tree_snapshot"` | required |
| `ownership` | `"pid_and_start_time" \| "unverified"` | required |
| `attention` | `"group_members_require_review" \| "persistent_wrapper_lost" \| "wrapper_lost" \| "completion_unknown" \| null` | required |


### ProcessIdentity

Source: `src/lib/host-command-observation.ts:13 (identitySchema)`.

| Field | Type | Presence |
| --- | --- | --- |
| `pid` | `positive integer` | required |
| `birth` | `string \| null` | required |


### LifecycleObservation

Source: `src/commands/host-ps.ts:121 (observeLifecycleEntry)`.

| Field | Type | Presence |
| --- | --- | --- |
| `project` | `string` | required |
| `projectRoot` | `string` | required |
| `branch` | `string \| null` | required |
| `session` | `string` | required |
| `backend` | `"tmux" \| "zellij"` | required |
| `lifetime` | `"persistent"` | required |
| `ownership` | `"absent" \| "owned-healthy" \| "owned-stale" \| "legacy-owned" \| "foreign" \| "unknown"` | required |
| `definitionSource` | `"persisted"` | required |
| `processGroupIds` | `number[]` | required |
| `observedPids` | `number[]` | required |
| `liveCpuTimeMs` | `number \| null` | required |
| `liveRssBytes` | `number \| null` | required |
| `elapsedMs` | `number \| null` | required |
| `attention` | `"session_absent_review_state" \| "ownership_unverified" \| null` | required |


### ValidateFileSuccess

Source: `src/lib/native-config-compiler.ts:108 (NativeConfigCompileResult)`.

| Field | Type | Presence |
| --- | --- | --- |
| `transport_version` | `1` | required |
| `ok` | `true` | required |
| `plan` | `Readonly<Record<string, unknown>>` | required |
| `semantic_hash` | `string (64 lowercase hex)` | required |
| `declared_workloads` | `Record<string, WorkloadKind>` | optional at CLI boundary; current generated producer emits it |
| `host_env_targets` | `HostEnvTargets` | optional; omitted when absent |


### ValidateResolvedSuccess

Source: `src/lib/native-config-compiler.ts:91 (NativeConfigResolveResult)`.

| Field | Type | Presence |
| --- | --- | --- |
| `transport_version` | `1` | required |
| `ok` | `true` | required |
| `plan` | `Readonly<Record<string, unknown>>` | required |
| `semantic_hash` | `string (64 lowercase hex)` | required |
| `declared_workloads` | `Record<string, WorkloadKind>` | optional at CLI boundary; current generated producer emits it |
| `host_env_targets` | `HostEnvTargets` | optional; omitted when absent |
| `local_resolution` | `NativeLocalResolution` | required |
| `routing_resolution` | `RoutingResolution` | optional; omitted when not selected |
| `host_binding_resolution` | `HostBindingResolution` | optional; omitted when absent |


### PlanSuccess

Source: `src/lib/native-config-compiler.ts:100 (NativeConfigPlanResult)`.

| Field | Type | Presence |
| --- | --- | --- |
| `transport_version` | `1` | required |
| `ok` | `true` | required |
| `plan` | `Readonly<Record<string, unknown>>` | required |
| `semantic_hash` | `string (64 lowercase hex)` | required |
| `declared_workloads` | `Record<string, WorkloadKind>` | required |
| `host_env_targets` | `HostEnvTargets` | optional; omitted when absent |
| `local_resolution` | `NativeLocalResolution` | required |
| `routing_resolution` | `RoutingResolution` | optional; omitted when not selected |
| `host_binding_resolution` | `HostBindingResolution` | optional; omitted when absent |
| `environment_plan` | `EnvironmentPlan` | required |
| `file_plan` | `FilePlan` | optional; omitted when no file report |


### CandidateDiagnosticFailure

Source: `src/lib/native-config-compiler.ts:108 (NativeConfigCompileResult)`.

| Field | Type | Presence |
| --- | --- | --- |
| `transport_version` | `1` | required |
| `ok` | `false` | required |
| `diagnostics` | `NativeConfigDiagnostic[] (nonempty)` | required |


### CandidateTransportFailure

Constructed by the CLI handler catch path; config plan has the same failure shape.

Source: `src/commands/config-validate.ts:58 (configValidateCommand)`.

| Field | Type | Presence |
| --- | --- | --- |
| `transport_version` | `1` | required |
| `ok` | `false` | required |
| `error` | `CandidateError` | required |


### CandidateError

Source: `src/lib/native-config-compiler.ts:124 (NativeConfigCompilerError)`.

| Field | Type | Presence |
| --- | --- | --- |
| `code` | `string` | required |
| `message` | `string` | required |


### NativeConfigDiagnostic

Source: `src/lib/native-config-compiler.ts:68 (NativeConfigDiagnostic)`.

| Field | Type | Presence |
| --- | --- | --- |
| `code` | `string` | required |
| `pointer` | `string` | required |
| `message` | `string` | required |
| `line` | `number` | required |
| `column` | `number` | required |
| `document` | `NativeConfigDocumentRole` | optional; omitted when absent |


### NativeLocalResolution

Source: `src/lib/native-config-compiler.ts:83 (NativeLocalResolution)`.

| Field | Type | Presence |
| --- | --- | --- |
| `overlay` | `string \| null` | required |
| `origin` | `"project" \| "primary_local" \| "checkout_local" \| "explicit"` | required |
| `auto_branch` | `boolean` | required |
| `inherit_local` | `boolean` | required |
| `resolution_hash` | `string` | required |


### NativeImportReport

Source: `src/lib/native-config-import-plan.ts:44 (NativeImportReport)`.

| Field | Type | Presence |
| --- | --- | --- |
| `report_version` | `1` | required |
| `complete` | `boolean` | required |
| `adoption` | `"not_performed"` | required |
| `fields` | `ImportField[]` | required |


### ImportField

Source: `src/lib/native-config-import-parser.ts:18 (ImportField)`.

| Field | Type | Presence |
| --- | --- | --- |
| `document` | `ImportDocument` | required |
| `pointer` | `string` | required |
| `line` | `number` | required |
| `column` | `number` | required |
| `status` | `"exact" \| "normalized" \| "refused"` | required |
| `code` | `string` | required |
| `target` | `string` | optional; omitted when absent |


### AdoptionPreview.refused

Source: `src/lib/native-compose-adoption-preview.ts:37 (previewLegacyComposeAdoption)`.

| Field | Type | Presence |
| --- | --- | --- |
| `complete` | `false` | required |
| `adoption` | `"not_performed"` | required |
| `fields` | `ImportField[]` | required |


### AdoptionPreview.complete

Source: `src/lib/native-compose-adoption-preview.ts:37 (previewLegacyComposeAdoption)`.

| Field | Type | Presence |
| --- | --- | --- |
| `complete` | `true` | required |
| `adoption` | `"not_performed"` | required |
| `containers` | `number` | required |
| `volumes` | `number` | required |
| `stop` | `"requested" \| "not_requested"` | required |
| `fields` | `ImportField[]` | required |


### AdoptionApplied

Source: `src/commands/config-adopt.ts:168 (apply)`.

| Field | Type | Presence |
| --- | --- | --- |
| `adoption_version` | `1` | required |
| `owner` | `"legacy-compose"` | required |
| `status` | `"active" \| "rolled-back"` | required |
| `original_data` | `"retained"` | required |


### LegacyComposePublicationRefusal

Source: `src/lib/native-compose-adoption-publication-diagnostics.ts:4 (LegacyComposePublicationRefusal)`.

| Field | Type | Presence |
| --- | --- | --- |
| `stage` | `\| "publication-state" \| "publication-inputs" \| "publication-layout" \| "publication-compiler" \| "publication-stopped" \| "publication-routing" \| "publication-originals-directory" \| "publication-hold-original" \| "publication-install-native" \| "publication-sync" \| "publication-save-native" \| "publication-finish-native" \| "publication-active-candidate" \| "publication-final-inputs" \| "publication-final-stopped" \| "publication-final-directories" \| "publication-save-active" \| "publication-save-active-context" \| "publication-save-active-previous" \| "publication-save-active-staging" \| "publication-save-active-staged-context" \| "publication-save-active-latest" \| "publication-save-active-routing" \| "publication-save-active-receipt" \| "publication-save-active-rename" \| "publication-save-active-sync" \| "publication-save-active-published" \| "publication-save-active-final-context" \| "publication-save-active-decode" \| "publication-close-originals"` | required |
| `reason` | `\| "legacy-state" \| "legacy-busy" \| "legacy-changed" \| "legacy-unsupported" \| "legacy-cancelled" \| "private-state" \| "private-busy" \| "private-uncertain" \| "private-stale" \| "compiler-transport" \| "proof-deadline" \| "unclassified"` | required |


### EndpointReference — variant 1

Source: `packages/config-compiler/generated/native-config.ts:15 (EndpointReference)`.

| Field | Type | Presence |
| --- | --- | --- |
| `kind` | `"route"` | required |
| `name` | `string` | required |


### EndpointReference — variant 2

Source: `packages/config-compiler/generated/native-config.ts:15 (EndpointReference)`.

| Field | Type | Presence |
| --- | --- | --- |
| `kind` | `"service"` | required |
| `name` | `string` | required |
| `port` | `number` | required |
| `protocol` | `EndpointProtocol` | required |


### EndpointReference — variant 3

Source: `packages/config-compiler/generated/native-config.ts:15 (EndpointReference)`.

| Field | Type | Presence |
| --- | --- | --- |
| `kind` | `"host_binding"` | required |
| `name` | `string` | required |


### HostEnvTarget — variant 1

Source: `packages/config-compiler/generated/native-config.ts:28 (HostEnvTarget)`.

| Field | Type | Presence |
| --- | --- | --- |
| `kind` | `"host"` | required |


### HostEnvTarget — variant 2

Source: `packages/config-compiler/generated/native-config.ts:28 (HostEnvTarget)`.

| Field | Type | Presence |
| --- | --- | --- |
| `kind` | `"workload"` | required |
| `name` | `string` | required |


### HostBindingTarget — variant 1

Source: `packages/config-compiler/generated/native-config.ts:16 (HostBindingTarget)`.

| Field | Type | Presence |
| --- | --- | --- |
| `kind` | `"host"` | required |
| `port` | `number` | required |
| `protocol` | `EndpointProtocol` | required |


### HostBindingTarget — variant 2

Source: `packages/config-compiler/generated/native-config.ts:16 (HostBindingTarget)`.

| Field | Type | Presence |
| --- | --- | --- |
| `kind` | `"external"` | required |
| `hostname` | `string` | required |
| `port` | `number` | required |
| `protocol` | `EndpointProtocol` | required |


### EnvironmentPlan

Source: `packages/config-compiler/generated/native-config.ts:22 (EnvironmentPlan)`.

| Field | Type | Presence |
| --- | --- | --- |
| `plan_version` | `1` | required |
| `overlay` | `string \| null` | required |
| `overlay_exists` | `boolean` | required |
| `complete` | `boolean` | required |
| `workloads` | `{ [key in string]: { [key in string]: EnvironmentBinding } }` | required |
| `host` | `{ [key in string]: HostEnvironmentPlan }` | optional; omitted when absent |
| `warnings` | `Array<ResolveDiagnostic>` | required |
| `diagnostics` | `Array<ResolveDiagnostic>` | required |


### EnvironmentBinding — variant 1

Source: `packages/config-compiler/generated/native-config.ts:7 (EnvironmentBinding)`.

| Field | Type | Presence |
| --- | --- | --- |
| `kind` | `"managed"` | required |
| `key` | `string` | required |
| `scope` | `string` | required |
| `secret` | `boolean` | required |


### EnvironmentBinding — variant 2

Source: `packages/config-compiler/generated/native-config.ts:7 (EnvironmentBinding)`.

| Field | Type | Presence |
| --- | --- | --- |
| `kind` | `"literal"` | required |
| `value` | `string` | required |


### EnvironmentBinding — variant 3

Source: `packages/config-compiler/generated/native-config.ts:7 (EnvironmentBinding)`.

| Field | Type | Presence |
| --- | --- | --- |
| `kind` | `"default"` | required |
| `value` | `string` | required |


### EnvironmentBinding — variant 4

Source: `packages/config-compiler/generated/native-config.ts:7 (EnvironmentBinding)`.

| Field | Type | Presence |
| --- | --- | --- |
| `kind` | `"endpoint"` | required |
| `reference` | `EndpointReference` | required |
| `target` | `EndpointTarget` | required |


### EnvironmentBinding — variant 5

Source: `packages/config-compiler/generated/native-config.ts:7 (EnvironmentBinding)`.

| Field | Type | Presence |
| --- | --- | --- |
| `kind` | `"runtime"` | required |
| `value` | `string` | required |


### EndpointTarget — variant 1

Source: `packages/config-compiler/generated/native-config.ts:21 (EndpointTarget)`.

| Field | Type | Presence |
| --- | --- | --- |
| `kind` | `"route"` | required |
| `origin` | `string` | required |


### EndpointTarget — variant 2

Source: `packages/config-compiler/generated/native-config.ts:21 (EndpointTarget)`.

| Field | Type | Presence |
| --- | --- | --- |
| `kind` | `"service"` | required |
| `name` | `string` | required |
| `port` | `number` | required |
| `protocol` | `EndpointProtocol` | required |


### EndpointTarget — variant 3

Source: `packages/config-compiler/generated/native-config.ts:21 (EndpointTarget)`.

| Field | Type | Presence |
| --- | --- | --- |
| `kind` | `"host"` | required |
| `context` | `EndpointContext` | required |
| `port` | `number` | required |
| `protocol` | `EndpointProtocol` | required |


### EndpointTarget — variant 4

Source: `packages/config-compiler/generated/native-config.ts:21 (EndpointTarget)`.

| Field | Type | Presence |
| --- | --- | --- |
| `kind` | `"external"` | required |
| `hostname` | `string` | required |
| `port` | `number` | required |
| `protocol` | `EndpointProtocol` | required |


### HostEnvironmentPlan

Source: `packages/config-compiler/generated/native-config.ts:5 (HostEnvironmentPlan)`.

| Field | Type | Presence |
| --- | --- | --- |
| `env_target` | `HostEnvTarget` | required |
| `bindings` | `{ [key in string]: EnvironmentBinding }` | required |


### ResolveDiagnostic

Source: `packages/config-compiler/generated/native-config.ts:80 (ResolveDiagnostic)`.

| Field | Type | Presence |
| --- | --- | --- |
| `document` | `DocumentRole` | required |
| `code` | `string` | required |
| `message` | `string` | required |
| `pointer` | `string` | required |
| `line` | `number` | required |
| `column` | `number` | required |


### FilePlan

Source: `packages/config-compiler/generated/native-config.ts:13 (FilePlan)`.

| Field | Type | Presence |
| --- | --- | --- |
| `plan_version` | `1` | required |
| `complete` | `boolean` | required |
| `workloads` | `{ [key in string]: Array<FileBinding> }` | required |
| `diagnostics` | `Array<ResolveDiagnostic>` | required |


### FileBinding

Source: `packages/config-compiler/generated/native-config.ts:12 (FileBinding)`.

| Field | Type | Presence |
| --- | --- | --- |
| `kind` | `FileKind` | required |
| `name` | `string` | required |
| `source` | `FileBindingSource` | required |
| `target` | `string` | required |
| `access` | `Access` | required |
| `mode` | `string` | required |
| `uid` | `number` | optional; omitted when absent |
| `gid` | `number` | optional; omitted when absent |


### FileBindingSource — variant 1

Source: `packages/config-compiler/generated/native-config.ts:11 (FileBindingSource)`.

| Field | Type | Presence |
| --- | --- | --- |
| `kind` | `"file"` | required |
| `file` | `string` | required |


### FileBindingSource — variant 2

Source: `packages/config-compiler/generated/native-config.ts:11 (FileBindingSource)`.

| Field | Type | Presence |
| --- | --- | --- |
| `kind` | `"managed"` | required |
| `key` | `string` | required |
| `scope` | `string` | required |
| `secret` | `boolean` | required |


### HostBindingResolution

Source: `packages/config-compiler/generated/native-config.ts:19 (HostBindingResolution)`.

| Field | Type | Presence |
| --- | --- | --- |
| `bindings` | `{ [key in string]: ResolvedHostBinding }` | required |
| `removed` | `{ [key in string]: HostBindingOrigin }` | required |


### ResolvedHostBinding

Source: `packages/config-compiler/generated/native-config.ts:18 (ResolvedHostBinding)`.

| Field | Type | Presence |
| --- | --- | --- |
| `target` | `HostBindingTarget` | required |
| `origin` | `HostBindingOrigin` | required |


### RoutingResolution

Source: `packages/config-compiler/generated/native-config.ts:45 (RoutingResolution)`.

| Field | Type | Presence |
| --- | --- | --- |
| `domain` | `string` | required |
| `domain_origin` | `DomainOrigin` | required |
| `project_origin` | `string` | required |
| `aliases` | `{ [key in string]: string }` | required |
| `oauth_alias` | `string \| null` | required |
| `open_preference` | `OpenPreference` | required |
| `open_preference_origin` | `OpenPreferenceOrigin` | required |
| `open_origin` | `string` | required |
| `branch` | `string` | optional; omitted when absent |
| `routes` | `{ [key in string]: ResolvedHttpRoute }` | required |


### ResolvedHttpRoute

Source: `packages/config-compiler/generated/native-config.ts:44 (ResolvedHttpRoute)`.

| Field | Type | Presence |
| --- | --- | --- |
| `service` | `string` | required |
| `port` | `number` | required |
| `protocol` | `HttpProtocol` | required |
| `origin` | `string` | required |
| `aliases` | `{ [key in string]: string }` | required |


### HostEnvTargets

Source: `packages/config-compiler/generated/native-config.ts:33 (HostEnvTargets)`.

| Field | Type | Presence |
| --- | --- | --- |
| `include_default` | `boolean` | required |
| `workloads` | `Array<string>` | required |

## Scalar, enum and collection aliases

| Name | Exact type / choices | Pinned source |
| --- | --- | --- |
| `WorkloadKind` | `"service" \| "job"` | `packages/config-compiler/generated/native-config.ts:74 (WorkloadKind)` |
| `CheckStatus` | `"ok" \| "warn" \| "error"` | `src/commands/doctor.ts:190 (CheckStatus)` |
| `HackLocalRouteReport` | `HackLocalRouteReport.current \| HackLocalRouteReport.repairable \| HackLocalRouteReport.refused (serializer variants)` | `src/lib/native-hack-local-route.ts:711 (reportHackLocalRoute)` |
| `HackLocalRouteRefusal` | `\| "invalid-receipt" \| "pending-receipt" \| "relay-not-verified" \| "dnsmasq-config-missing" \| "unreadable-config" \| "uninspected-config-source" \| "no-managed-line" \| "unmanaged-line" \| "foreign-target" \| "foreign-resolver" \| "old-target-live" \| "non-interactive" \| "declined" \| "authorization-failed" \| "busy" \| "restart-unavailable" \| "inputs-changed" \| "no-receipt"` | `src/lib/native-hack-local-route.ts:71 (HackLocalRouteRefusal)` |
| `EnvKeyDiagnosticCode` | `\| "env-key-ok" \| "env-key-absent" \| "env-key-symlink" \| "env-key-not-regular" \| "env-key-unreadable" \| "env-key-weak-permissions" \| "env-key-wrong-owner" \| "env-key-tracked" \| "env-key-public-path" \| "env-key-wrong-length" \| "env-key-low-entropy"` | `src/lib/doctor-env-key.ts:28 (EnvKeyDiagnosticCode)` |
| `EnvKeyFindingStatus` | `"ok" \| "warn" \| "error"` | `src/lib/doctor-env-key.ts:41 (EnvKeyFindingStatus)` |
| `NativeConfigDocumentRole` | `\| "project" \| "primary_local" \| "checkout_local" \| "request"` | `src/lib/native-config-compiler.ts:77 (NativeConfigDocumentRole)` |
| `ImportDocument` | `\| "config" \| "compose" \| "primary_local" \| "checkout_local"` | `src/lib/native-config-import-parser.ts:13 (ImportDocument)` |
| `EndpointProtocol` | `"http" \| "https" \| "tcp"` | `packages/config-compiler/generated/native-config.ts:14 (EndpointProtocol)` |
| `HttpProtocol` | `"http" \| "https"` | `packages/config-compiler/generated/native-config.ts:37 (HttpProtocol)` |
| `OpenPreference` | `"auto" \| "alias" \| "dev"` | `packages/config-compiler/generated/native-config.ts:39 (OpenPreference)` |
| `Access` | `"read-only" \| "read-write"` | `packages/config-compiler/generated/native-config.ts:64 (Access)` |
| `EndpointContext` | `"workload" \| "host"` | `packages/config-compiler/generated/native-config.ts:20 (EndpointContext)` |
| `DocumentRole` | `"project" \| "primary_local" \| "checkout_local" \| "request"` | `packages/config-compiler/generated/native-config.ts:79 (DocumentRole)` |
| `FileKind` | `"config" \| "secret"` | `packages/config-compiler/generated/native-config.ts:10 (FileKind)` |
| `HostBindingOrigin` | `"project" \| "primary_local" \| "checkout_local"` | `packages/config-compiler/generated/native-config.ts:17 (HostBindingOrigin)` |
| `DomainOrigin` | `"default" \| "global" \| "project" \| "primary_local" \| "checkout_local" \| "explicit"` | `packages/config-compiler/generated/native-config.ts:42 (DomainOrigin)` |
| `OpenPreferenceOrigin` | `"default" \| "project" \| "primary_local" \| "checkout_local"` | `packages/config-compiler/generated/native-config.ts:43 (OpenPreferenceOrigin)` |

## Contract boundaries

The CLI wrapper exposes plan as an opaque compiler-owned record, not a stable public Plan DTO. Its matching private producer model is intentionally excluded. Other named CLI projection records above have documented fields and typed dynamic map values. Shared error.detail remains unknown by its public contract. A report shape is not runtime/provider/client qualification.


---

<!-- Editorial source: docs/versions/v5/integrations.md; based on 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; URL: https://hack.foo/docs/v5/integrations -->
# Use Hack with an agent

With shell access, an agent can use the CLI directly. Complete [Install](/docs/v5/install),
make the intended `hack` executable available on the agent's PATH, and give it this
version's [documentation index](/v5/llms.txt) or [full corpus](/v5/llms-full.txt).
Plugins and MCP are optional additions. They do not install Hack or prepare its
runtime.

v5 retired automatic instruction injection. Hack no longer writes `AGENTS.md` or
`CLAUDE.md` sections, Cursor rules, session hooks or global skill copies, and the
old `hack setup sync` and `hack agent prime` paths refuse with a retirement notice.
Existing customized files are left alone. Guidance now arrives through the
plugin below, which the client's own plugin manager installs and updates.

## The `hack` plugin

The `hack` plugin ships eight skills and nothing else: no hooks, no rules, no MCP
server.

| Skill | Purpose |
| --- | --- |
| hack-cli | Everyday workflows: services, URLs, logs, exec and workspaces |
| hack-branches | Parallel branch instances and aliases |
| hack-env | Env layers and value-safe configuration changes |
| hack-diagnose | Read-first diagnosis and the error-code reference |
| hack-init | Project onboarding through the CLI's onboarding prompt |
| hack-install | Installation and executable or channel selection |
| hack-remote | Prepare a project on another host or in a cloud environment |
| hack-feedback | Report a Hack problem with redacted evidence |

Install it from this repository's marketplace:

```sh
# Codex
codex plugin marketplace add hack-dance/hack
codex plugin add hack@hack-dance

# Claude Code
claude plugin marketplace add hack-dance/hack --sparse .claude-plugin plugins/hack plugins/hack-mcp
claude plugin install hack@hack-dance
```

In Cursor, install Hack from Customize. The plugin finds `hack` on the client's
PATH; during the prerelease that is whichever executable you put there. The
[plugin README](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/plugins/hack/README.md)
has per-client notes. A plugin registered in a client is not proof that it loaded;
check the client's plugin list.

## The separate `hack-mcp` plugin

Clients without shell access can add `hack-mcp`. It declares one stdio server,
`hack mcp serve`, and no skills. Use one Hack MCP registration per client, either
this plugin or a single `hack mcp install` entry, never both. The
[MCP tools](/docs/v5/reference/mcp-tools) and [MCP logs](/docs/v5/reference/mcp-logs)
references describe the tool surface and its finite log cutoffs.

## Project onboarding

`hack agent onboard` prints an onboarding prompt for an existing project, and
`hack init --with claude|codex` hands a new project's setup to an agent. Both
describe the work to do; neither installs skills or edits client configuration.
See [Explicit agent setup](/docs/v5/guides/agent-first-setup).


---

<!-- Editorial source: docs/versions/v5/guides/agent-first-setup.md; based on 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; URL: https://hack.foo/docs/v5/guides/agent-first-setup -->
# Give an agent an explicit project task

Start with [Install](/docs/v5/install) and [Getting started](/docs/v5/getting-started).
Decide which executable and backend the agent should use before asking it to change
project configuration. Agent setup is optional; a shell-capable client can use the
CLI and the [LLM index](/v5/llms.txt) directly.

A useful task names the project, the host it runs on, the Hack version and the
expected outcome. Ask the agent to inspect existing configuration before changing
it and to verify the application's own behavior afterwards.

## Onboarding prompt

`hack agent onboard` prints an onboarding prompt for an existing repository. It
inventories the repo and describes what a Hack setup should cover. It installs
nothing. Review the prompt, then hand it to your agent. `hack init --with
claude|codex` does the same for a new project and launches the selected agent.

The `hack-init` skill in the [hack plugin](/docs/v5/integrations) asks the CLI for this
same prompt, so an agent with the plugin can onboard a project on request.

## Policy stays with its owner

Hack does not modify `AGENTS.md`, `CLAUDE.md`, client rule files or global agent
settings, and it does not run guidance checks or skill updates. Repository policy
is yours. Project environment injection and lifecycle hooks are runtime features;
follow [Environment and secrets](/docs/v5/env) and [Lifecycle](/docs/v5/lifecycle)
when they are part of the requested work.

## Clients without a shell

A client without shell access can use the separate MCP server; see
[Agent integrations](/docs/v5/integrations#the-separate-hack-mcp-plugin) and
[MCP tools](/docs/v5/reference/mcp-tools).


---

<!-- Editorial source: docs/versions/v5/guides/init-project.md; based on 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; URL: https://hack.foo/docs/v5/guides/init-project -->
# Project setup

Complete [Install](/docs/v5/install) and [Getting started](/docs/v5/getting-started).
This page covers an existing repository: an app that already has Compose files,
one that needs custom domains, or one you want an agent to configure.

## Initialize

```sh
cd your-project
hack init
```

`hack init` detects an existing `docker-compose.yml`, asks about services and
domains, and writes `.hack/`: the Compose file Hack manages, `hack.config.json`,
the default env YAML and a `.gitignore` for machine-local state. Review the files
and commit them. To hand setup to an agent instead, run
`hack init --with claude` or `hack init --with codex`.

For an existing project, `hack agent onboard` prints an onboarding prompt that
describes the services, env and routing a Hack setup should cover. See
[Explicit agent setup](/docs/v5/guides/agent-first-setup).

## Check the result

```sh
hack up --detach
hack open
hack doctor
```

`hack doctor` reports missing prerequisites, routing problems and configuration
drift. Review each repair before `hack doctor --fix`.

## Native backend

Native execution needs more than `hack init`: a prepared provider pool, an
explicitly adapted project and a private native home. Read
[Try the native backend](/docs/v5/native/try-it) first. `hack config validate`,
`config plan` and `config import --dry-run` preview native configuration without
starting anything; see [Native config import](/docs/v5/native/config-import).
Installing v5 does not convert a Compose project or move its data.


---

<!-- Editorial source: docs/versions/v5/cli.md; based on 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; URL: https://hack.foo/docs/v5/cli -->
# CLI Overview

Hack is the local-first CLI surface. This page is a supported-surface overview with the
running-things decision guide; for exhaustive per-command options and flags, see the generated
[CLI reference](/docs/v5/reference/cli) (`bun run docs:cli-reference`, or `hack help <command>` in the
terminal).

## Core commands

- `hack init` — generate `.hack/` (compose + config); `--with claude|codex` also hands off to
  agent-assisted onboarding
- `hack up` / `hack down` / `hack restart`
- `hack open` — open/print the project URL
- `hack logs` — tail logs (compose by default; Loki via `--loki`/`--query`)
- `hack ps` / `hack status` — project status
- `hack projects` — registry + running instances; `hack projects prune --project <name>` safely scopes stale registry/container cleanup to one project family (omit `--project` only for an intentional machine-wide prune)
  entries and stops orphaned containers
- `hack env` — env values and local secrets
- `hack host exec` / `hack host shell` — host commands/shells with Hack-resolved env injected
- `hack run <service> [cmd...]` — one-off command in a fresh service container
- `hack exec <service> -- <cmd...>` — command in an already-running service container
- `hack session` — persistent project workspaces (tmux-first)
- `hack doctor` / `hack doctor --fix` — validate and repair local setup
- `hack daemon` — optional local daemon for faster JSON project status
- `hack agent onboard` — agent-assisted onboarding for existing projects
- `hack agent onboard` — print an onboarding prompt for an existing project
- Optional agent interfaces — the [`hack` plugin, its skills and the separate MCP server](/docs/v5/integrations)

Interactive diagnostics use compact status rows: healthy groups stay on one line, while warnings
and errors expand with wrapped detail and recovery guidance. `hack doctor --json` remains the stable,
fully detailed automation surface. Generic macOS resolver setup is shown only when those resolver
checks need attention.

On macOS, a healthy terminal connection does not establish browser connectivity.
Use `hack doctor --browser-url https://your-service.hack.local --browser-result fails`
to compare a manually observed browser failure with a verified CLI HTTPS request.
See [macOS browser connectivity](/docs/v5/guides/macos-browser-network) for supported
observations, Local Network permission guidance and the required browser recheck.

On the native backend, `hack doctor` adds a `native settings` check. It reports where each native
selection comes from (`env`, `machine`, `project` or `unset`) without its value, and warns about
project configuration that native `up` refuses or does not apply. The committed
`.hack/native/adaptation.json` and the per-machine
`${XDG_CONFIG_HOME:-$HOME/.config}/hack/native/<project>/settings.json` replace exported
`HACK_NATIVE_*` variables; a variable that is set still wins. The machine file applies
only to the project roots listed in its `projectRoots`. See
[Native settings files](/docs/v5/native/full-reference#native-settings-files).

Project names in the registry and `--project`/MCP selectors use the same lowercase,
hyphenated key: for example, `my_app` selects `my-app`. Existing registry spellings
remain readable aliases; a later registration of that checkout canonicalizes the
name while preserving its project ID. This does not rename Compose projects,
volumes, hosts or the name in project configuration.

Because a `--project` argument is sometimes a pasted value, Hack never prints the
argument or a slug derived from it. A value containing `=` or other characters
outside a project name is refused with fixed text. An alias spelling that matches
no registered project is not named either: errors say "Unknown project", and
`hack projects --json`/`hack status --json` report `"filter": null` with
`"filter_redacted": true` (and filter without the daemon).

If multiple registrations share a canonical name, selection refuses all aliases,
including an exact spelling. Inspect `hack projects` and use `--path` to address a
specific checkout before renaming or pruning the conflicting registration. A
missing checkout does not authorize another repository to take over its identity;
automatic relocation requires proof that both checkouts belong to the same Git
worktree family. Independent clones remain separate even when their remotes match.
Prune also refuses colliding aliases without a project filter, and checks runtime
working directories against registered checkout/worktree paths before treating a
runtime name as an alias. Inspect the conflicting entries before retrying cleanup.

Lookup, registration updates and removal also refuse a selected project ID that
belongs to multiple entries, even if one checkout is missing. Removal checks every
requested ID under the registry lock before deleting any entry; an ambiguous ID
leaves the entire batch unchanged. Creating a registration also refuses an ID
collision. Unrelated duplicate IDs remain visible and do not block operations on
unique IDs. Optional registration touches defer on ambiguity so they do not break
read commands. Updates persist newly observed last-seen or configured host
metadata even when no existing field changes.

Project resolution for `exec`, `run`, `ps`, `logs`, `open` and host env commands
does not refresh the global project registry. A held registration lock therefore
does not block their resolution or require a retry just to update last-seen metadata.
Use a checkout/path directly, or an existing registry entry with `--project`;
`hack init`, project lifecycle registration and `hack projects` discovery maintain
registrations. Optional `hack projects` discovery coalesces unchanged observations
for one minute and defers refresh when the registry lock is busy. Stale optional
upserts check before Git and configuration discovery, then again before staging
an owner, so an observed busy lock avoids work that would be discarded. These
observations never grant ownership: an apparently absent lock still requires
atomic acquisition. New or changed checkouts are recorded when the lock is available.
A registry touch reuses its configuration and canonical checkout paths for
freshness and any update. A later configuration change is picked up by the next
invocation, even within the one-minute freshness interval. Updates still reread
the registry under the lock so they preserve concurrent registrations. An unchanged
primary checkout refresh skips Git discovery only after that locked reread confirms
its paths, configuration, and unique registration. It still removes missing sibling
records; changed or ambiguous registrations use the normal Git checks.
Registration combines repository identity and branch discovery in one Git call for
ordinary committed checkouts; repositories without commits and unusual ref output
retain separate branch discovery. Linked worktrees still verify their shared
repository identity before joining an existing registration.
Explicit registry mutations wait up to ten seconds with jittered retries, reread
the registry under the lock, and publish complete updates by atomic rename.
A slow live writer is never evicted
because its lock is old. A confirmed dead owner can be recovered; an occupied or
reused PID is treated as live, and uncertain ownership is preserved.

Recovery is serialized separately so competing cleanup attempts cannot delete a
new writer's lock. If a recovery process itself crashes, its recovery guard may
need offline inspection after all writers have stopped; age alone never authorizes
removing it. Interrupted writes may leave uniquely named `.tmp` or `.owner` files
beside `projects.json`; these are never used as registry input. Preserve the current
registry and inspect ownership before removing abandoned files. This concurrency
guarantee applies to cooperating v5 writers. Older v4 writers sharing the same
registry still use their older lock protocol; use separate `HACK_HOME` directories
when running the two versions concurrently.

Run `hack help` for the full command list, or `hack help --all` to include hidden unsupported
experimental commands. Every command and flag on this page is also in the generated
[CLI reference](/docs/v5/reference/cli).

Hosted auth/account/org/team, built-in GitHub and Linear workflows, and Hack Tickets are outside the
CLI surface. Use native `git` and `gh` for repository collaboration.

## Unsupported experimental

These commands remain source-available but are outside the supported product. They are
hidden from default `hack --help` (see `hack help --all`) and print a warning when invoked:

- `hack remote`
- `hack gateway`
- `hack node`
- `hack dispatch`

Historical remote guides are excluded from the supported documentation.

## Agent/scripted ergonomics

- `--json` on `hack up`/`down`/`restart`/`doctor` emits a `{ok, data | error: {code, message}}`
  envelope with stable `E_*` error codes. `--json` on `hack up` implies `--detach`.
- A `--path` (or working directory) without a `.hack/` project reports `E_PROJECT_NOT_FOUND`
  from `up`, `down`, `restart`, `ps`, `logs`, `run`, `exec`, `open`, `tui`, `branch ...`,
  `config get`/`set`, `env ...`, `host exec`/`shell` and `project owner`/`target`/`task`, for
  example `hack ps -p <dir> --json` and `hack branch list -p <dir>`. Under `--json` it is one
  error envelope; without `--json` it is one closed error message, `E_PROJECT_NOT_FOUND: <message>`,
  and no stack trace. The logger decides how it looks: the console logger (`HACK_LOGGER=console`)
  prints one line, `ERROR: E_PROJECT_NOT_FOUND: ...`, on stderr; gum prints one line with a styled
  `ERROR` level on stderr; and clack prints two lines on stdout, its `│` guide line and then the
  message after a `■` marker. `project target` and
  `project task` use their own message, and `target` adds a
  `detail`. These commands report something else:
  - `tui` without a terminal refuses for that reason first.
  - `env get` never prints a failure reason, since its output is raw values: it prints one fixed
    line on stderr, with or without `--json`.
  - `config validate`, `plan`, `import` and `adopt` read native configuration and keep their own
    refusals: `E_NATIVE_PROJECT_UNSUPPORTED` for `validate`/`plan`, a refused preview for
    `import --dry-run`, and `E_CONFIG_INVALID` for `adopt`.
  - `init`, `doctor`, `crash-capture`, and the `setup`, `mcp` and `agent` commands do not need a
    project.

  `tests/missing-project-error-code.test.ts` pins each command that takes `--path`.
- Known Hack errors and closed native runtime refusals print their message only, never a stack
  trace; set `HACK_DEBUG=1` to add the stack. Unexpected exceptions always print their stack.
- `--no-interactive` (or `HACK_NO_INTERACTIVE=1`) is a global flag: commands never prompt — they
  apply documented defaults or fail fast with `E_INTERACTIVE_REQUIRED`.
- A run whose stdin or stdout is not a TTY (piped input, an agent harness, CI) is treated the same
  way, with or without the flag: the command resolves every prompt by its documented
  non-interactive policy within milliseconds and never waits on a prompt. Confirmations that have
  a safe default apply it (`hack env unset KEY` removes the key; `hack doctor --fix` applies safe
  remediations and skips destructive ones with a note); prompts that need a real answer fail
  closed with `E_INTERACTIVE_REQUIRED`, naming the flag or argument that makes the invocation
  scriptable (for example `hack update --yes`, `hack mcp --all`, `hack session attach <name>`,
  `hack secrets delete <name> --yes`, `hack ssh --host <host>`). Destructive confirmations without
  such a flag decline or refuse; they never proceed on their own.
  Set `HACK_NO_INTERACTIVE=1` explicitly in scripts anyway so the intent is visible.
- `NO_COLOR` (or `HACK_NO_COLOR`) disables colored/decorated output.

Automatic agent instruction management is retired in v5. `hack setup sync`, the
standalone `hack setup cursor|claude|codex|agents` exports and `hack agent prime` refuse with a
retirement notice, and ordinary commands, `hack update` and `hack doctor --fix` never write agent
files. Guidance arrives through the opt-in `hack` plugin; see
[Agent integrations](/docs/v5/integrations).

## First-run path

```bash
hack global install
hack init
hack up --detach
hack open
```

Agent-assisted alternative for a new repo: `hack init --with claude|codex`. For an existing
project without `.hack/`, use `hack agent onboard`. See
[Agent-first setup](/docs/v5/guides/agent-first-setup).

`--with both` has been removed. Choose `--with claude` or `--with codex`;
a second-agent review is a separate, explicitly requested workflow.

### Browser URL preference

`hack open` keeps `dev_host` as the primary routing identity, but automatically opens the OAuth
alias (for example, `myapp.hack.gy`) when `oauth.enabled` is true. Service shorthand and branch
instances follow the same preference, so `hack open api --branch feature-x` resolves the
branch-qualified alias URL.

Set `open.prefer` in `.hack/hack.config.json` to `auto` (the default), `alias`, or `dev`. Override
one invocation with `hack open --prefer <auto|alias|dev>`. Explicit URLs and fully qualified host
targets are preserved. Selecting `alias` without an enabled OAuth alias fails with recovery
guidance instead of silently opening the dev host. For a custom `dev_host` outside Hack's managed
`.hack` namespace, `auto` keeps the development host because Hack does not synthesize a Caddy alias
route for it.

## Running things (decision guide)

- One-off command in a fresh service container (deps started as needed): `hack run <service> <cmd...>`.
- 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>`.
- Browser/host URL: use `hack open <service> --json`; OAuth aliases are preferred when enabled.
- Container-to-container traffic: use Compose DNS rather than routing back through Caddy.

For `run`, `exec`, `host exec`, `env exec`, `x` and the Beta `dispatch run`, Hack options go before
the child command.
From the child command's first word on, every argument belongs to the child, including flags
that Hack also defines: `hack run web bun --version` runs `bun --version` in the container
rather than printing Hack's version, and a child `--json` does not switch Hack's own error output
to JSON. A `--` before the child command is optional and is not passed on; a later `--` (as in
`hack run web npm test -- --watch`) reaches the child unchanged.

### Option parsing

Hack parses options with the resolved command's own options plus the global ones, so each command
keeps its own short flags and option types. `-p` is `--path` for project commands (`init`, `up`,
`down`, `ps`, `logs`, `env ...`, `config ...`, `setup ...`) and `--port` for `hack ssh`. Both
refusals below are `E_USAGE`:

- A long option that only another command declares is refused as
  `Option(s) not valid for "<command>": --<option>`, for example `hack doctor --follow`.
- A short spelling the command does not declare is unknown to it, even when another command
  declares it. `hack doctor -f` refuses as `Unknown option '-f'. To specify a positional argument
  starting with a '-', ...`, the same refusal as a spelling no command declares, such as `-x`.
  (`-f` is `--follow` for `logs` and `global logs`.) In a group of short flags, such as `-fd`, the refusal
  names the first unknown letter without its dash (`Unknown option 'f'`).

An option placed before the command name, as in `hack -p <dir> up`, is read as that command reads
it. There is one remaining edge: when a spelling placed before the command name is a flag in one
command and takes a value in another, Hack reads it as a flag, so it never consumes the command
name. No spelling in the current CLI has this conflict. Put options after the command name to
avoid it.

Per-command parsing replaced one parse over every command's options. Comparing the old and new
parsers on edge cases found two differences:

- The intended one: `-p <dir>` on a project command (for example `up -p /x` or
  `--no-interactive up -p /x`) now sets `--path`. The old parser set `ssh`'s `--port`, which the
  command then refused.
- A short spelling only another command declares is still refused, with different text. The old
  parser read it as that command's long option and refused it as not valid: `doctor -f` and
  `doctor -d` gave `Option(s) not valid for "doctor": --follow` and `--detach`, `ps -fd` gave
  `--follow, --detach`, and `doctor -c --json` (`-c` takes a value for `agent init`) gave an
  "argument is ambiguous" error. Each now gives `Unknown option '<spelling>'`, and `ps -fd` gives
  `Unknown option 'f'`.

These cases parse the same as before: `--help --all`, `help --all`, `-- up`,
`--json run web tool --json`, `--path /x up`, `logs --tail`, `up --tail`, `ssh --path /x` and
`x ext cmd -p 1` (where `-p 1` belongs to the extension command).
`tests/cli-per-command-options.test.ts` pins the short-spelling refusal for every short spelling
that `doctor` does not declare.

`session exec` takes the workspace command as one argument, so quote a command that has its own
arguments or flags: `hack session exec ws "npm --version"`. Hack options go before it, and an
unquoted `hack session exec ws npm --version` refuses with a hint to quote the command instead
of printing Hack's version.

Service-scoped runtime changes do not run project-wide lifecycle hooks and do not start Compose
dependencies implicitly, except declared shared-cache installers needed by the selected services:

```bash
hack up api worker --env qa --detach
hack restart api --env qa
hack env apply --service api --env qa
```

Full detached startup and inspection are bounded. A timeout returns `E_STARTUP_TIMEOUT`, terminates
the Compose process group, and leaves an explicit repair path instead of hanging indefinitely.
`hack doctor --fix` starts exact project containers left in `Created`; it never removes those
containers as part of this repair.

## Dependency bootstrap integrity

Hack detects package-manager install services by their command or by the explicit
`hack.dependencies.bootstrap=true` Compose label. Before such a service can mutate the runtime,
Hack scans `.npmrc`, `.yarnrc.yml`, and `bunfig.toml` for `${VAR}` credential references and fails
with `E_ENV_KEY_MISSING` when the selected Hack overlay cannot supply them. Values are never
printed.

Detached Compose startup runs in two phases, each with its own budget:

| Phase | Compose invocation | Default | Variable | Range (ms) |
| --- | --- | --- | --- | --- |
| Image build/pull and container creation | `up --no-start` | 30 minutes | `HACK_COMPOSE_IMAGE_TIMEOUT_MS` | 1,000–14,400,000 |
| Start and dependency wait | `up -d --no-build` | 90 seconds | `HACK_COMPOSE_STARTUP_TIMEOUT_MS` | 1,000–3,600,000 |

A first-time build or a large image pull therefore does not consume the start
budget. Raise the budget for the phase that was hit, on the host CLI invocation
rather than in a container's environment:

```sh
# Slow first build or pull of a large image
HACK_COMPOSE_IMAGE_TIMEOUT_MS=3600000 hack up --detach
# Slow container start or a dependency that is slow to become healthy
HACK_COMPOSE_STARTUP_TIMEOUT_MS=300000 hack up --detach
HACK_COMPOSE_STARTUP_TIMEOUT_MS=300000 hack restart
```

Detached startup and restart reject invalid values before project preparation or
teardown. Full and service-scoped startup/restart use the same settings. The
startup notice reports both effective budgets. On expiry, `E_STARTUP_TIMEOUT`
names the phase that was hit, its budget, and the variable that raises it; with
`--json`, `error.detail` carries `composePhase` (`images` or `start`),
`budgetMs`, and `budgetEnv`. The start budget covers container start and Compose
`depends_on` waiting, not lifecycle hooks or an end-to-end application readiness
deadline. A restart repair attempt has its own budgets and is reported
separately. Foreground `up` stays a single unbounded Compose invocation; `down`
retains its separate 90-second limit. A native `down` reads that limit from
`HACK_COMPOSE_STARTUP_TIMEOUT_MS`, and each check that it still owns its containers
may use that time too, at least 15 and at most 60 seconds. The last check before
`compose down` must also leave about a fifth of that limit, at most 5 seconds, for the
stop itself; otherwise `down` refuses before it starts Compose, and `hack down --recover`
completes the stop.

On timeout, Hack terminates the owned Compose process group of that phase. After an
image-phase timeout no container was started by that attempt, but containers may
have been created or recreated. After a start-phase timeout containers may still be
running. Inspect `hack ps` and `hack logs` before retrying. Raising a budget does not
fix a failed installer or prove readiness.

Services with `pull_policy: always` still pull again in the start phase because
Compose applies that policy on every `up`; such pulls count against the start
budget.

Native authored projects with persistent storage also prove their storage with
short-lived helper containers. Each helper proof (one storage carrier: dependency
check, target observation, helper create, policy, start, response and cleanup) has
its own budget, separate from the start budget:

| Budget | Default | Variable | Range (ms) |
| --- | --- | --- | --- |
| One native storage carrier | 90 seconds | `HACK_NATIVE_STORAGE_TIMEOUT_MS` | 1,000–600,000 |

`HACK_COMPOSE_STARTUP_TIMEOUT_MS` neither shortens nor lengthens a storage proof:
carriers follow only `HACK_NATIVE_STORAGE_TIMEOUT_MS`. Native
`up` and `restart` image builds use the image budget (`HACK_COMPOSE_IMAGE_TIMEOUT_MS`),
and the start budget begins only after builds end. Native pulls of `image:` services
still happen during container start and count against the start budget. Storage
proofs that run while a native `up` or `restart` builds and starts workloads do not
consume either budget: their elapsed time extends the current phase's deadline, and
each proof stays bounded by its own carrier budget. Each Docker command inside a carrier
is bounded by that carrier's remaining budget (reads at most 60 seconds), so a slow
helper start on a loaded host can use the budget rather than a fixed 15-second cap.
Helper cleanup keeps its own 10–60 second bound.

The two variables bound different things:

- Per proof: each storage carrier ends within `HACK_NATIVE_STORAGE_TIMEOUT_MS` (S).
- Per phase: the storage time excluded from one `up` or `restart` image or start
  deadline may total at most 16 × S or 1 hour, whichever is smaller (24 minutes at
  the 90-second default; 1 hour from S = 225,000 up). Each phase has its own cap,
  and its deadline moves later by at most that cap. A proof that would start after
  the cap is spent is refused before it runs, and a proof that ends past the cap
  refuses the phase.
- Whole phase: the image phase therefore ends within
  `HACK_COMPOSE_IMAGE_TIMEOUT_MS`, and the start phase within
  `HACK_COMPOSE_STARTUP_TIMEOUT_MS`, each plus its cap, plus at most one in-flight
  guard proof. Raising S raises both the per-proof bound and the cap; raising the
  image or start budget never changes either.

When a carrier budget or the whole-phase cap runs out, the command reports the
closed effect reason `storage-budget` in `error.detail.native_compose_effect_refusal`,
and the human summary names `HACK_NATIVE_STORAGE_TIMEOUT_MS`. A refusal with its own
cause, such as a helper policy refusal, keeps that reason even when it is caught after
the carrier deadline; raising the storage budget does not address it. Exhaustion leaves the
same retained, uncertain state as any other storage refusal; inspect saved state
before retrying.

To share dependency data only across worktrees with the same lockfile/runtime fingerprint, label
the bootstrap service with a logical top-level Compose volume:

```yaml
services:
  install-workspace:
    image: oven/bun:1.3.9
    platform: linux/arm64 # choose the actual installer target platform
    command: bun install --frozen-lockfile
    labels:
      hack.dependencies.bootstrap: "true"
      hack.dependencies.cache-volume: workspace-dependencies
      hack.dependencies.lockfiles: bun.lock,package.json
      hack.dependencies.runtime-files: .mise.toml
    volumes:
      - workspace-dependencies:/app/node_modules
```

Hack generates a content-addressed volume name from the declared files and installer
image, platform and build configuration. Compatible branch instances select the same
volume; changing these inputs selects a new one. Specify the installer's Compose
`platform` explicitly, or set `DOCKER_DEFAULT_PLATFORM`. When platform or runtime
configuration is unresolved, Hack warns and leaves the original Compose volume
configuration in effect instead of guessing the remote Docker host's architecture.
Explicit volume names or external
volumes can still be shared by Compose; remove that sharing yourself if isolation
is required. No service name such as `deps` is special.

This identity covers declared configuration, not mutable image-tag contents, build
context contents or later Compose overrides. Pin installer images by digest and
include build/runtime source inputs in `hack.dependencies.runtime-files` where
needed. Installers still own serialization, successful-completion markers and
recovery of partial output. Sharing a volume does not provide those guarantees.
The expanded fingerprint selects new volumes on upgrade; old caches are retained.

For explicitly immutable initialization, the opt-in
[`locked-v1` installer protocol](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/guides/dependency-cache-protocol.md) adds writer
exclusion, verified readiness and fresh-generation recovery. It requires a strict
producer/consumer layout; ordinary cache labels do not enable it automatically.

`hack run` uses the same dependency-volume override as `up` and `restart`, including
in linked worktrees. It skips dependency startup only when the target is running
in the requested environment and its inspected mounts contain the selected cache
volumes. Changed fingerprints, uncertain container identity, or caches mounted only
by other services leave dependency reconciliation to Compose. This does not certify
cache completeness or skip installer/generation commands by itself.

`hack exec` uses the existing container and its existing mounts. After changing a
lockfile/runtime input, use `hack restart` to move the long-running service to the
new cache; a successful one-off `run` does not remount that existing service.
Unlabelled services retain their existing behavior. Old cache volumes are retained;
this change does not prune caches or application data.

Before a scoped `up`, `restart`, or a consumer `run`, Hack executes each needed cache installer
with the same Compose files and selected service environment, using `run --rm --no-deps`.
Installers must be idempotent and coordinate concurrent writers (for example, a lock and a ready
marker inside the volume). They run even for warm caches so an empty or interrupted cache cannot
be mistaken for a ready one. No project lifecycle hook or unrelated dependency is started.
A failed installer leaves existing consumer containers untouched; JSON lifecycle commands return
`E_DEPENDENCY_BOOTSTRAP_FAILED`. Each initializer in detached scoped `up` and targeted `restart` uses the configured
`HACK_COMPOSE_STARTUP_TIMEOUT_MS` budget and reports `E_STARTUP_TIMEOUT` on expiry.
That budget also covers any installer image pull or build, because `run` acquires
the image itself. The subsequent Compose launch has its own phased budgets. Consumer `run` and foreground
scoped `up` retain a separate ten-minute initializer deadline.

## Branch instances and linked worktrees

`--branch <name>` on `hack up/down/restart/ps/logs/open/run/exec` targets a separate branch
instance (compose project `<name>--<branch>`, hostnames prefixed with the branch).

In a linked git worktree, these commands default the branch instance to the sanitized current git
branch when no `--branch` is passed (`worktree.auto_branch`), so two checkouts never fight over the
same hostnames. A one-line notice is printed to stderr when the default kicks in, so captured
stdout stays clean.

Before `up` or `restart`, Hack also checks for a non-terminal instance previously started from the
same worktree. If the worktree's current branch would auto-target a different Compose project, Hack
prints a warning naming both the existing and new targets. Pass `--branch <name>` to make the target
explicit.

`hack down` applies a stricter ownership rule. When a linked worktree's Git branch was renamed and
that exact checkout owns one differently named Compose runtime, implicit down targets the existing
runtime instead of succeeding against an empty newly derived name. Running, Created, and stopped
containers all count as ownership evidence. If the checkout owns multiple runtimes, implicit down
fails and lists them; pass `--branch <name>` to select one. Exact checkout paths and Compose project
families are required, so Hack never retargets to a sibling checkout.

A detached linked worktree has no branch name to derive, so these commands fail instead of silently
targeting the base instance. Pass `--branch <name>` to select an isolated instance, or set
`worktree.auto_branch` to `false` only when intentionally opting into the base instance.

Opt out:

- pass `--branch <name>` explicitly (always wins), or
- set `worktree.auto_branch` to `false` in `.hack/hack.config.json` to target the base instance.

The primary checkout is unchanged: no `--branch` means the base instance.

### Local configuration in linked worktrees

Linked worktrees read eligible primary-checkout local env overrides and managed
extra-host aliases at command time. Later primary changes are visible without
copying files. Tracked project config, generated overrides, runtime state and other
ignored files stay checkout-local. Set `worktree.inherit_local` to `false` in the
worktree's `hack.config.json` to disable inheritance. `HACK_WORKTREE_INHERIT_LOCAL=0`
does the same for the Compose path; the experimental graph runner follows the config
setting only. Slim/Codex execution mode and CI (`CI=1` or `CI=true`) disable this
inheritance automatically.

For Compose aliases, explicit local `internal.extra_hosts` takes precedence over
inherited dynamic aliases, and local dynamic aliases take precedence over both.
`hack internal extra-hosts unset <host>` in a linked checkout hides an inherited
alias without changing the primary. `set` replaces that local removal with an
override. `list --origins` shows each effective dynamic alias and its source file;
plain `list` retains its hostname-to-target JSON format. Successful `up.before`
hooks can create or remove aliases for the same `up` or `restart` operation.

Missing primary configuration is optional. Invalid inherited alias data or
redirected inherited files fail explicitly instead of silently changing routing.
These commands manage the Compose path; the experimental graph runner's direct
Compose-input handling is a separate qualification boundary.

### Branch registry and usage

Runtime commands never write tracked files. `hack up/down/restart/run/exec` record when a
branch instance was last used in machine-local `.hack/.internal/branch-usage.json` (ignored by the
committed `.hack/.gitignore`, one per checkout), so `git status` stays clean in a linked worktree.

`.hack/hack.branches.json` is the optional, committed branch registry. Only `hack branch add` and
`hack branch remove` create or change it, and they record identity (`name`, `slug`, `note`,
`created_at`) but no usage timestamp. Existing registries that already carry `last_used_at` are left
as they are: runtime commands stop rewriting them, and `hack branch list` and `hack projects`
show the machine-local time when this checkout has one, falling back to the committed value. You
can delete the old `last_used_at` fields by hand at any time.

### Disposable cache volumes

Compose preserves named volumes on ordinary `down`, which is correct for application data but can
leave branch-specific build caches behind. Use the explicit cleanup path when those caches are
disposable:

```bash
hack down --prune-caches
# scripted:
hack down --prune-caches --yes --json
```

Hack recognizes named volumes mounted only at `.next` destinations as disposable Next build
caches. For any other framework, library, or language, mark the top-level Compose volume explicitly:

```yaml
services:
  web:
    volumes:
      - turbo-cache:/app/.turbo

volumes:
  turbo-cache:
    labels:
      hack.cache.disposable: "true"
```

The label applies to the exact volume, so the same contract works for Rust `target`, Gradle, Go,
Python, or other generated caches without relying on names or destination guesses.

Hack snapshots mounts before stopping the target and considers a volume removable only when all of
these are true:

- the container belongs to the exact targeted Compose project and checkout;
- the mount type is a named volume;
- `docker volume inspect` independently reports both the exact
  `com.docker.compose.project` label and a `com.docker.compose.volume` label;
- every observed destination's final path segment is `.next`, or the volume itself has
  `hack.cache.disposable=true`.

Interactive cleanup shows the exact volumes, services, and destinations and defaults to “no.”
`--json` and other scripted use must add `--yes`; otherwise the command fails before down with
`E_INTERACTIVE_REQUIRED`. Postgres, Redis, dependency, application-data, bind, external, unlabeled
non-Next, and sibling-checkout volumes do not satisfy the removal contract unless a project author
deliberately marks that exact Compose volume disposable. Hack deliberately does not run broad
`docker volume prune` or `docker compose down -v`.

### Runtime host metadata

Containers started by `hack up`, `hack restart`, and `hack run` receive the effective instance and
public-route metadata. This applies to `.hack/docker-compose.yml` projects and to authored
`.hack/hack.project.json` projects, on the default Compose backend and on the native backend
(`HACK_RUNTIME_BACKEND=native`). It keeps server-generated links, OAuth callbacks, webhooks, and
other browser-facing URLs isolated when the same project runs in multiple worktrees. Every path
emits the same keys and document shape from the same shared builder.

| 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 and routed by Hack |
| `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.

With the Compose backend, Hack materializes this contract in generated, machine-local Compose
overrides. Do not edit or commit `.hack/.internal/compose.runtime.override.yml` or
`.hack/.branch/compose.<branch>.runtime.override.yml`; runtime commands refresh them and keep them
out of `git status` (see [ignore rules](/docs/v5/env#ignore-rules-committed-hackgitignore)).

With the native backend, foreground `hack up` and `hack restart` add the same values to the
normalized Compose input that native review checks. They are public container environment, not
private managed values, so `hack exec` and native `hack run` see them too. The service URLs come
from the reviewed route labels, and startup refuses before serving if they differ from the reviewed
route plan. When a native HTTPS frontend is selected with a port other than 443
(`HACK_NATIVE_HTTPS_PORT`), `HACK_DEV_URL`, `HACK_ALIAS_URL` and every service URL include that
port; host variables never do. Native-specific limits:

- A graph whose data was retained by an earlier release is restored exactly as it was admitted and
  does not gain these variables. It receives them after it is next started without retained data.
- These values are part of the retained graph's reviewed input. A retaining restart that changes
  only route hostnames (for example a domain migration) remains supported, because the generated
  metadata keys are excluded from the hostname-change fingerprint. Values you declare for these
  keys in `.hack/docker-compose.yml` still count. Changing the native HTTPS port, or selecting or
  removing the native HTTPS frontend when its port is not 443, changes the metadata without a
  hostname change, so the retained graph refuses to start. Start it with its original HTTPS
  frontend selection and port.

For an authored `.hack/hack.project.json` project, the configuration compiler carries the values as
public `runtime` bindings (see the [compiler reference](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/native-config-compiler.md)), so
they are reviewed with the rest of the plan and are never managed or secret values. The precedence
matches Compose-file projects: a managed project env value or any authored `environment` directive
for one of these keys (literal, default, reference, endpoint or `unset`) wins over the generated
value. The hosts come from the compiler's routing resolution:

- `HACK_DEV_HOST` is the resolved project origin's host (for example
  `feature-x.demo.hack.local`). Without a routing resolution it is the compiler's generated
  `<name>.hack.local`, prefixed with the selected branch when there is one.
- `HACK_ALIAS_HOST` is the host of the alias named by `routes.oauth_alias`, when set.
- Service URLs list each `routes.http` route for that service in route-name order, the route origin
  before its aliases, so `HACK_SERVICE_URL` is the development origin.
- `HACK_BRANCH` is the routing resolution's branch, or the selected `--branch` instance when no
  routing resolution exists.
- On the Compose backend `HACK_COMPOSE_PROJECT` is the instance's actual Compose project
  (`hack-nc-...`), and URLs are portless. On the native backend it is `<name>` or
  `<name>--<branch>`, as for native image projects, and URLs carry a selected non-443
  `HACK_NATIVE_HTTPS_PORT`. Authored native graphs are not routed, so they have no alias and no
  service URLs; the port appears only in `HACK_DEV_URL`.

Authored native `hack exec` sees the values stored in the running container, and native one-off
`hack run` uses the admitted service environment. A graph started before this release gains them
on its next `hack up` or `hack restart`.

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
keys and `dev_host` collisions across checkouts.

## Environment model

Canonical env files:

- `.hack/hack.env.default.yaml`
- `.hack/hack.env.<overlay>.yaml`
- `.hack/hack.env.local.yaml` (worktree-local override)
- `.hack/hack.env.<overlay>.local.yaml` (worktree-local override)

Use `hack env add`, `hack env unset`, `hack env list`, and `hack env materialize` to manage them.
Use `hack host exec` and `hack host shell` when you want Hack-resolved env injected into host-side
commands.

Use `--local` on env mutations when you want to write to the worktree-local override file instead
of the shared repo file.

`hack env materialize` is only for compatibility output. `hack doctor` will tell you when the
materialized `.hack/.env` or `.hack/.env.state.json` is stale and should be regenerated.

## Project files

Hack owns a committed `.hack/.gitignore` (created by `init`; for an existing project without it,
`doctor` warns and `doctor --fix` creates or repairs it; a read-only or symlinked file is reported
and never replaced) that ignores
machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`,
`hack.env*.local.yaml`). The retired `tickets/` path remains ignored only so upgrades cannot
recommit legacy machine-local caches. Keep `.hack/.gitignore` committed. Runtime commands (`up`,
`down`, `restart`, `run`, `exec`) do not write it: they add the same patterns to the repository's
local `info/exclude`, so `git status` stays unchanged. Never commit `.hack/.internal/`. If generated
files ever leak into git, `hack doctor --fix` untracks them (the files stay on disk). Runtime metadata is written to
`.internal/compose.runtime.override.yml` for the base instance and
`.branch/compose.<branch>.runtime.override.yml` for branch instances. See [Architecture](/docs/v5/architecture)
for the full file map.

The global config root defaults to `~/.hack`; override it with `HACK_HOME` (an absolute path;
a relative value is refused). An empty or relative `HOME` falls back to the OS home directory.
A non-default `HACK_HOME` disables hackd launchd management, host-trust launchd
environment registration, and native DNS launchd inspection/restarts. Set
`HACK_LAUNCHD_ALLOW_ISOLATED_HOME=1` to opt in to these host-wide effects.
`HACK_LAUNCHD_DISABLE=1` always disables launchd access, including with that opt-in.

## Lifecycle

Use `.hack/hack.config.json` `lifecycle` or `startup` for host-side setup instead of ad-hoc
terminal tabs.

For fixed-port helpers such as AWS SSM tunnels or local proxies, declare `singleton.ports`.
Use `onConflict: "adopt"` only when an existing full listener set is equivalent and should be
reused. Adoption does not transfer process ownership: `hack down` leaves adopted external listeners
running.

See [Lifecycle](/docs/v5/lifecycle) for the full model.


---

<!-- Editorial source: docs/versions/v5/core.md; based on 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; URL: https://hack.foo/docs/v5/core -->
# Core concepts

Hack keeps the parts needed to run a project together: services, environment,
secrets, local URLs, startup helpers and logs. The setup lives in `.hack/` in the
repository, so teammates and agents use the same definition.

## Project, service and instance

A **project** is a repository with Hack configuration. A **service** is one part of
that project, such as a web app, API or database. An **instance** is a running copy
of the project. Branch instances let you run different versions side by side, each
at its own URL.

New projects get `https://<project>.hack.local` with per-service subdomains such as
`api.<project>.hack.local`. Existing `.hack` names, `.hack.gy` OAuth aliases and
custom domains keep working. Use `hack open` to find an instance's URL rather than
guessing a port or hostname.

## Backends

The **Compose backend** is the default. It runs services with Docker Compose behind
shared local routing. Every command on this site works there.

The **native backend** is beta and opt-in. On Apple Silicon macOS it runs an
explicitly prepared project without Docker, with a bounded command subset. Select it
with `HACK_RUNTIME_BACKEND=native`. Read [the native backend overview](/docs/v5/native/overview)
before using it; a Compose example does not imply native support for the same flag.

## Start, inspect and stop

```sh
hack up --detach
hack open
hack ps
hack logs --pretty
```

`hack up` starts the declared services and the project lifecycle. `hack ps` shows
service state, including stopped one-shot containers with their exit codes. `hack
logs` reads service output. When finished:

```sh
hack down
```

If startup fails, read the error and run `hack doctor`. Review what a repair
touches before applying it with `hack doctor --fix`.

## Keep configuration with the project

[Environment and secrets](/docs/v5/env) explains committed configuration and
per-value encryption. Keep the decryption key out of git. [Lifecycle](/docs/v5/lifecycle)
declares startup hooks and host helpers such as tunnels, so they start with the
project instead of in a spare terminal tab.

## Work on more than one branch

In a linked git worktree, `hack up` defaults to a branch instance named after the
branch. The secret key is inherited from the primary checkout. A detached worktree
needs an explicit `--branch <name>`. See [Work on another branch](/docs/v5/guides/parallel-work)
and [Worktrees and watchers](/docs/v5/guides/development-runtime-safety).

## Use Hack from an agent or script

Agents use the same CLI. `--json` returns structured results with stable error codes
and `--no-interactive` prevents a command from waiting for input. No plugin, server
or account is required. [Agent handoff](/docs/v5/agent-handoff) and
[Agent integrations](/docs/v5/integrations) cover the optional extras.


---

<!-- Editorial source: docs/versions/v5/native/install.md; based on 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; URL: https://hack.foo/docs/v5/native/install -->
# Install a native prerelease beside stable Hack

v5 prereleases ship for Apple Silicon macOS as immutable `5.0.0-next.N` bundles.
The shell bootstrap on each release installs a standalone manager and the selected
bundle into a private `~/.hack-next` channel. It does not replace Homebrew `hack`,
edit your PATH or shell profile, convert projects, move volumes, enable DNS or
trust, or start a VM. [Install](/docs/v5/install) has the download and run steps.

Run the candidate explicitly:

```sh
"$HOME/.hack-next/bin/hack-next" --version
"$HOME/.hack-next/bin/hack-next" ps --path /absolute/project
```

## Backends and homes

`hack-next` selects the native backend by default, with version-private native and
CLI homes, so candidate state never mixes with stable state. Set
`HACK_RUNTIME_BACKEND=compose` to run the same verified bundle on Compose against
your ordinary Hack home. Any other value refuses before the candidate starts.

On Compose, stable `hack` and the candidate share project and configuration state.
Never run both at once against the same home, including their daemons. Before a
Compose run: `hack global up`, any stable `hack doctor` or `hack doctor --fix`, then
`hack daemon stop`, and confirm `pgrep -fl "hack daemon start"` prints nothing.

## Upgrade and roll back

Each release is a new immutable version directory with its own homes. Selecting a
different retained bundle switches software, not data: an older candidate that
refuses state written by a newer one is not a successful rollback. Stop and verify
ownership of active workloads before changing versions, and keep stable v4
available until each project's own workflow passes on the candidate.

Every invocation re-verifies the retained bundle bytes, receipts and macOS code
signatures and refuses on any mismatch. The
[prerelease channel guide](/docs/v5/guides/prereleases) covers versioning,
platform support and publication gates in full.


---

<!-- Editorial source: docs/versions/v5/architecture.md; based on 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; URL: https://hack.foo/docs/v5/architecture -->
# Architecture

Hack is a local CLI that turns a small committed `.hack/` folder into a running
project: services, environment, secrets, trusted HTTPS, logs and host-side helpers.
Everything runs on the developer's machine. There is no hosted component.

Two kinds of state exist. **Global state** under `~/.hack/` (overridable with
`HACK_HOME`) holds the shared infrastructure every project uses: the proxy, DNS,
the logging stack, the project registry and the optional daemon. **Project state**
under `<repo>/.hack/` holds that project's definition and is committed, apart from
machine-local generated files that Hack keeps ignored.

## System overview

```mermaid
---
title: Hack on one developer machine
---
flowchart LR
  Agent["Coding agent"] -->|"same CLI, --json"| CLI["hack CLI"]

  subgraph Project["Project (.hack/ in the repo)"]
    direction TB
    Config["Compose file,<br/>config, env YAML"]
    Services["Service containers"]
    Helpers["Host helpers<br/>(tunnels, hooks)"]
    Config -->|"Compose backend"| Services
    Config -->|"lifecycle"| Helpers
  end

  subgraph Global["Global infrastructure (~/.hack)"]
    direction TB
    Caddy["Caddy proxy<br/>TLS + routing"]
    CoreDNS["CoreDNS"]
    Logs["Alloy → Loki → Grafana"]
    Hackd["hackd (optional)"]
  end

  CLI -->|"hack up"| Config
  CLI -->|"hack global install"| Global
  Services -->|"labels"| Caddy
  Services -->|"stdout/stderr"| Logs
  CoreDNS -.->|"*.hack.local → Caddy"| Services
  Hackd -.->|"docker events"| Services
  Caddy -->|"https://myapp.hack.local"| Browser["Browser"]
  Logs -->|"https://logs.hack.local"| Browser

  classDef idle stroke-width:1.6px
  class Hackd idle
```

- **Caddy** terminates TLS with a locally trusted CA and routes
  `https://<service>.<project>.hack.local` to containers by their Docker labels.
  Existing `.hack` names, `.hack.gy` OAuth aliases and custom domains route the
  same way.
- **CoreDNS** gives containers the same `*.hack.local` names as the host, so a
  service can call another service by its public local URL.
- **Alloy, Loki and Grafana** collect container logs and keep searchable history.
- **hackd** is an optional daemon that caches Docker state for fast `--json`
  status. The CLI works without it.
- **Schemas** for the project config files are served by Caddy at
  `https://schemas.hack.local` for editor validation.

## Backends

The CLI reads the same `.hack/` project on either backend. **Docker Compose** is the
default and runs everywhere Hack runs. The **native backend** is opt-in and
experimental: on Apple Silicon macOS it runs an explicitly prepared project inside
a provider-managed Linux VM pool without Docker, with its own routing and a bounded
command subset.

```mermaid
---
title: One project, two backends
---
flowchart LR
  Repo[".hack/ project"]
  CLI["hack CLI"]
  Repo --> CLI
  CLI -->|"default"| Compose
  CLI -->|"HACK_RUNTIME_BACKEND=native"| Native

  subgraph Compose["Compose backend"]
    direction TB
    DC["docker compose"] --> C1["Service containers"]
    C1 --> GlobalCaddy["Global Caddy + CoreDNS"]
  end

  subgraph Native["Native backend (opt-in, macOS arm64)"]
    direction TB
    Plan["Config compiler<br/>validate / plan"] --> Exec["hack-native executor"]
    Exec --> Pool["Provider VM pool"]
    Pool --> N1["Workloads + relay"]
    N1 --> NativeHttps["Shared HTTPS owner"]
  end

  classDef live stroke-width:1.6px
  classDef wait stroke-width:1.6px
  class Compose live
  class Native wait
```

The native backend selects a verified executor binary and a private native home,
plans the project through the config compiler, and runs workloads under a
foreground owner process that holds the run until it is stopped. Its supported
commands are whole-project `up` and `restart`, owner-mediated `down`, saved-run
`ps`, finite `logs`, and noninteractive `exec` and `run`. See
[the native backend guide](/docs/v5/native/full-reference) and
[native authored commands](/docs/v5/native/authored-commands). A Compose flag
in these docs does not imply native support.

## Global vs project scope

- Global scope (`~/.hack`)
  - Caddy proxy on 80/443, routing by Docker labels
  - CoreDNS for container DNS (`*.hack.local` and legacy `*.hack` → Caddy)
  - macOS DNS helper: dnsmasq plus `/etc/resolver` entries pointing at Caddy
  - Logging stack (Alloy → Loki → Grafana)
  - Global config `hack.config.json` and the project registry `projects.json`
  - Networks `hack-dev` (ingress) and `hack-logging`
- Project scope (`.hack`)
  - `docker-compose.yml` defines services and Caddy labels
  - `hack.config.json` stores the project name, dev host, log preferences, OAuth
    alias and browser launch preference
  - `hack.env.default.yaml` and optional overlays hold committed env, with
    per-value encryption for secrets
  - `hack.branches.json` is an optional committed branch registry
  - `.internal/` and `.branch/` hold generated, machine-local files. Hack
    rewrites them on every run; keep them out of Git. `hack doctor` reports tracked
    copies and `hack doctor --fix` untracks them.

## Project lifecycle

`hack up` and `hack down` run more than Compose. Hooks and managed host processes
declared in `.hack/hack.config.json` run around the services, inside a dedicated
tmux or zellij session that Hack owns and can tear down. The exact ordering is in
[Lifecycle](/docs/v5/lifecycle).

```mermaid
---
title: hack up and hack down
---
stateDiagram-v2
  direction TB
  [*] --> ResolveEnv : hack up
  ResolveEnv --> UpBefore : env contract ok
  UpBefore --> Processes : hooks done
  Processes --> ComposeUp : session owned
  ComposeUp --> UpAfter : services started
  UpAfter --> Running
  state failure <<choice>>
  UpBefore --> failure : hook failed
  ComposeUp --> failure : compose failed
  UpAfter --> failure : hook failed
  failure --> Failed : own session removed
  Running --> DownBefore : hack down
  DownBefore --> ComposeDown : hooks done
  DownBefore --> Running : hook failed, abort
  ComposeDown --> StopProcesses : services stopped
  StopProcesses --> DownAfter : session killed
  DownAfter --> [*]
  note right of Processes
    Adopts a session only when its
    ownership token, definition hash
    and live windows all match.
  end note
  classDef live stroke-width:1.6px
  classDef fail stroke-width:1.6px
  class Running live
  class Failed fail
```

Lifecycle state is checkout-local at `.hack/.internal/lifecycle/state.json`, one
entry per instance. A random token mirrored in the mux session and in that state
proves ownership. Teardown never trusts a session name or a reused process group
on its own: `hack down` stops the saved process groups only while a matching
session still proves ownership, and `hack doctor --fix` removes a stale session
only when its instance is absent and a second check agrees. Fixed-port helpers
such as database or SSM tunnels can declare a `singleton` listener set so Hack
reuses an equivalent helper instead of starting a competing one; see
[shared host helper lifecycle](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/shared-host-lifecycle.md).

## Environment and secrets

Env lives in committed YAML. Secrets are encrypted per value with a key that stays
out of Git. At runtime Hack merges the layers below and injects the result into
Compose, host commands and lifecycle processes. Nothing decrypted rests on disk:
the generated Compose override holds only `${HACK_ENV_...}` references and the
values travel through the `docker compose` process environment.

```mermaid
---
title: Env resolution order
---
flowchart LR
  subgraph Committed["Committed with the repo"]
    direction TB
    D["hack.env.default.yaml"] --> O["hack.env.&lt;overlay&gt;.yaml<br/>(--env)"]
  end
  subgraph Local["Machine-local overrides"]
    direction TB
    PL["primary checkout<br/>hack.env.local.yaml"] --> POL["primary checkout<br/>hack.env.&lt;overlay&gt;.local.yaml"]
    POL --> L["this checkout<br/>hack.env.local.yaml"]
    L --> OL["this checkout<br/>hack.env.&lt;overlay&gt;.local.yaml"]
  end
  subgraph Scope["Scope"]
    direction TB
    G["values.global"] --> S["values.&lt;service&gt;"]
    S --> H["host values<br/>(host exec, hooks)"]
  end
  O --> PL
  OL --> G
  H --> R["Effective env"]
  classDef idle stroke-width:1.6px
  class PL,POL idle
```

Later layers win. The primary-checkout layers apply only in a linked git worktree,
which also inherits the primary checkout's secret key through the shared git
directory. `HACK_ENV_SECRET_KEY` covers CI and other detached environments.
[Environment and secrets](/docs/v5/env) covers the file format, delivery matrix,
rotation and the external secret-store backends.

## Internal DNS and TLS

When `internal.dns` and `internal.tls` are enabled, `hack up` writes a Compose
override that points each service at CoreDNS, mounts Caddy's local CA and the
combined trust bundle, sets the usual `SSL_CERT_FILE`-style variables, and adds
`extra_hosts` entries for runtimes that ignore custom DNS. Containers then use the
same `https://*.hack.local` names as the host. If Caddy's IP changes,
`hack status` and `hack doctor` warn and `hack restart` refreshes the mapping.

```mermaid
---
title: A request from one service to another
---
sequenceDiagram
  autonumber
  participant Web as web container
  participant DNS as CoreDNS
  participant Caddy
  participant Api as api container
  Web->>DNS: resolve api.myapp.hack.local
  DNS-->>Web: A record = Caddy IP
  Web->>Caddy: HTTPS request (local CA trusted)
  Caddy->>Api: route by container labels
  Api-->>Web: response
```

## Workflow: init, up, logs

```mermaid
---
title: First run of a project
---
sequenceDiagram
  autonumber
  participant User
  participant CLI as hack
  participant Docker
  participant Caddy
  participant Loki
  User->>CLI: hack init
  CLI-->>User: wrote .hack/ files
  User->>CLI: hack up --detach
  CLI->>CLI: resolve env, run up.before hooks
  CLI->>Docker: docker compose up -d
  Docker->>Caddy: labels → routes
  Docker->>Loki: logs via Alloy
  CLI-->>User: https://myapp.hack.local
  User->>CLI: hack logs
  alt compose backend
    CLI->>Docker: docker compose logs
  else loki backend
    CLI->>Loki: LogQL query or tail
  end
```

## Branch instances

`--branch <name>` generates a per-branch Compose override that prefixes hostnames
(`api.myapp.hack.local` → `api.<branch>.myapp.hack.local`) and the Compose project
name, so parallel checkouts never collide on ports or names. In a linked git
worktree, `hack up` selects a branch instance named after the branch automatically.
A detached worktree has no branch to derive a name from, so Hack refuses to target
the base instance silently; pass `--branch`, or set `worktree.auto_branch=false`.

```mermaid
---
title: Checkouts and instances
---
flowchart LR
  P["Primary checkout<br/>(main)"] -->|"hack up"| B["Base instance<br/>myapp.hack.local"]
  W["Linked worktree<br/>(feature-x)"] -->|"hack up"| F["Branch instance<br/>feature-x.myapp.hack.local"]
  D["Detached worktree"] -->|"hack up"| R{"branch name?"}
  R -->|"--branch review"| V["Branch instance<br/>review.myapp.hack.local"]
  R -->|"none"| X["Refused"]
  classDef ok stroke-width:1.6px
  classDef fail stroke-width:1.6px
  class B,F,V ok
  class X fail
```

`hack doctor` checks linked checkouts for divergent secret keys and `dev_host`
collisions. See [Worktrees and watchers](/docs/v5/guides/development-runtime-safety).

## Logging pipeline

`hack logs` has two backends. **compose** streams `docker compose logs` directly
and is the default for following output. **loki** adds searchable history and
LogQL filters and is the default for snapshots (`--no-follow`), falling back to
Compose with a one-line notice when Loki has nothing for the selection.
`hack logs --json` emits NDJSON `start`, `log`, `error` and `end` events for
agents and the TUI.

```mermaid
---
title: Where a log line goes
---
flowchart LR
  C["Service containers"] -->|"stdout/stderr"| A["Alloy"]
  A -->|"push"| L["Loki"]
  L -->|"LogQL"| Q["hack logs --loki"]
  C -->|"docker compose logs"| F["hack logs"]
  L -->|"Explore"| G["Grafana<br/>logs.hack.local"]
  Q --> T["Terminal / NDJSON"]
  F --> T
```

Alloy discovers containers by polling Docker every five seconds and includes exited
containers, so a one-shot service such as a migration is shipped after it stops as
long as Docker keeps the container. A container removed between two polls never
reaches Loki; use `hack logs --compose` or the command's own output for those.
Alloy keeps its read positions in a named volume across `hack global down` and
`up`; `hack global logs-reset` clears positions and Loki data together. Loki
retention defaults to one week in the global template; per-project
`logs.retention_period` applies when `hack down` prunes logs.

## Daemon (hackd)

`hackd` is an optional local daemon that watches Docker events and keeps a cached
view of running containers behind a Unix socket at `~/.hack/daemon/hackd.sock`.
It powers `hack projects --json` and streaming consumers such as the TUI and MCP.
`hack ps` queries Compose directly so failed startups are visible immediately. If
the daemon is missing or version-mismatched, the CLI falls back to direct Docker
calls.

```mermaid
---
title: Cached status
---
flowchart LR
  CLI["hack projects --json"] -->|"GET /v1/projects"| H["hackd"]
  TUI["hack tui / MCP"] -->|"stream"| H
  H -->|"docker events"| D["Docker Engine"]
  H -->|"full inspect every 30s"| D
  H --- Cache["In-memory cache"]
  classDef idle stroke-width:1.6px
  class H idle
```

The daemon treats the container runtime as ephemeral: it fingerprints the engine,
detects resets, performs one bounded refresh, and marks cached state stale with
`runtime_*` metadata when the runtime is unavailable. Scripted and noninteractive
commands never autostart it. v5 prerelease launchers (`hack-next`, `hack-v5`)
never autostart it either, because autostart would run the stable daemon on PATH;
`hack doctor --fix` under those launchers skips its hackd repair and names the
command to run yourself. On macOS the launchd service belongs to the default
`~/.hack` root only; an isolated `HACK_HOME` runs hackd directly.

## Native backend internals

The native backend is built around explicit ownership: every run has one owner,
every resource it creates is recorded before it can outlive the frontend, and
cleanup is confirmed rather than assumed. These rules are checked against finite
TLA+ models under `tests/models/tla/`; the charts below are drawn from those
specifications, and [the model coverage map](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/v5-model-coverage.md)
records what each model does and does not prove.

### Foreground startup owner

A foreground `hack up` on the native backend serves the run until it is ready or
fails. Readiness publishes the run mapping. A failure after resources were created
must leave them owned: either cleanup is confirmed, or the frontend's final
read-only inspection authenticates the owner receipt and records it.

```mermaid
---
title: Owner · native foreground startup
---
stateDiagram-v2
  direction TB
  [*] --> idle
  idle --> serving : Serve
  serving --> serving : StartResources
  serving --> ready : Ready [resources present]
  serving --> failed : Fail
  ready --> failed : Fail
  state inspect <<choice>>
  failed --> inspect : Inspect
  inspect --> exited : ExitConfirmed [cleanup confirmed]
  inspect --> exited : ExitUnconfirmed [receipt authenticated, owner recorded]
  inspect --> exited : ExitUnconfirmed [receipt refused]
  exited --> [*]
  note right of ready
    INV NoUnprovenOwner: a mapping is
    published only by readiness or an
    authenticated receipt.
  end note
  note right of exited
    INV NoUnownedResources: resources that
    outlive the frontend under an
    authenticated receipt are recorded.
  end note
  classDef live stroke-width:1.6px
  classDef ok stroke-width:1.6px
  classDef fail stroke-width:1.6px
  class serving live
  class ready ok
  class failed fail
```

Source: [`Owner.tla`](https://github.com/hack-dance/hack/blob/next/tests/models/tla/native-startup-owner/Owner.tla). A refused
inspection is a known coverage gap: nothing can be authenticated, so only the
runtime journal retains the graph.

### Interrupted restart

`hack restart` saves a `prepared` intent bound to the exact old run, asks the old
run's owner to stop, and marks the intent `cleaned` only after that stop is
confirmed. `hack up` refuses while an intent is pending, so an interrupted restart
must always leave a state that `hack restart` itself accepts.

```mermaid
---
title: RestartIntent · hack restart under interruption
---
stateDiagram-v2
  direction TB
  [*] --> idle
  idle --> stopping : BeginRestart [intent prepared]
  stopping --> stopping : Request [owner asked to stop]
  stopping --> starting : StopConfirmed [intent cleaned]
  starting --> done : Ready [intent none]
  state interrupted <<choice>>
  stopping --> interrupted : Interrupt or Crash
  starting --> interrupted : Interrupt or Crash
  interrupted --> canceled : [own process group, stop finished]
  interrupted --> failed : [intent kept]
  canceled --> [*]
  failed --> idle : BeginRestart [resumes prepared or cleaned intent]
  done --> [*]
  note right of failed
    INV NoRecoveryLoop: when no restart
    is running, either hack up or
    hack restart accepts the state.
  end note
  classDef live stroke-width:1.6px
  classDef ok stroke-width:1.6px
  classDef fail stroke-width:1.6px
  class stopping,starting live
  class done,canceled ok
  class failed fail
```

Source: [`RestartIntent.tla`](https://github.com/hack-dance/hack/blob/next/tests/models/tla/native-restart-intent/RestartIntent.tla).
The restart's stop request runs in its own process group so a terminal Ctrl-C
reaches only the restart frontend and lets the stop finish.

### Shared HTTPS owner

Native runs on one machine share a single HTTPS owner. Clients lease it, prove
cleanup, and release; the owner may begin closing only once no lease remains.

```mermaid
---
title: SharedHttps · owner lifetime
---
stateDiagram-v2
  direction LR
  [*] --> active
  active --> active : Acquire / Release
  active --> closing : BeginClose [no leases]
  closing --> closed : FinishClose
  active --> failed : OwnerCrash
  closing --> failed : OwnerCrash
  closed --> [*]
  note right of closing
    INV NoPrematureShutdown: closing
    with a live lease is unsafe.
  end note
  classDef live stroke-width:1.6px
  classDef ok stroke-width:1.6px
  classDef fail stroke-width:1.6px
  class active live
  class closed ok
  class failed fail
```

Source: [`SharedHttps.tla`](https://github.com/hack-dance/hack/blob/next/tests/models/tla/shared-https-lifetime/SharedHttps.tla).

Other models cover registry writers and lock recovery, publication journals,
persistent data enrollment, dependency rebinding, engine restart policies and MCP
startup. A finite model checks a property over a bounded domain; it does not
qualify the installed binary, real filesystems or an application.

## Files and directories

- `~/.hack/` (default; override the whole root with an absolute `HACK_HOME`)
  - `hack.config.json` (global config and extension settings)
  - `projects.json` (project registry; `hack projects prune` removes stale entries)
  - `daemon/hackd.sock`, `daemon/hackd.pid`, `daemon/hackd.log` (capped at 5 MiB)
  - `caddy/docker-compose.yml`, `caddy/Corefile`
  - `logging/docker-compose.yml`, `logging/alloy.alloy`, `logging/loki.yaml`, `logging/grafana/`
  - `schemas/hack.config.schema.json`, `schemas/hack.branches.schema.json`
  - `certs/` (mkcert output for non-Caddy services)
- `<repo>/.hack/`
  - `docker-compose.yml`, `hack.config.json`, optional `hack.branches.json`
  - `.gitignore` (committed; created by `init` and repaired by `doctor --fix`)
  - `hack.env.default.yaml` and optional `hack.env.<overlay>.yaml` (committed env)
  - `hack.env.local.yaml` and `hack.env.<overlay>.local.yaml` (worktree-local)
  - `.env` (only when explicitly materialized) and `.env.state.json`
  - `.internal/compose.override.yml`, `compose.env.override.yml`, `compose.runtime.override.yml`
  - `.internal/extra-hosts.json`, `.internal/branch-usage.json`
  - `.internal/lifecycle/state.json` and `.internal/lifecycle/*.log`
  - `.branch/compose.<branch>.override.yml` and `.branch/compose.<branch>.runtime.override.yml`
  - `hack.project.json` and `native/adaptation.json` (native backend only)

## Key design choices

- Docker Compose is the default execution substrate for predictability and portability.
- Caddy routes by container label, so no project carries reverse-proxy config.
- CoreDNS gives containers the same `*.hack.local` namespace as the host.
- Logs default to `docker compose logs` for speed; Loki holds history and filtering.
- The daemon keeps JSON queries fast without becoming a dependency.
- Config lives beside each repo in `.hack/` so projects stay isolated and portable.
- The native backend records ownership before effects and confirms cleanup, and
  those rules are model-checked.

## Unsupported retained surfaces

Remote, gateway, node and dispatch code, the extension dispatcher and the macOS
app remain in the repository for explicit maintenance. They are outside the
supported local CLI and are hidden from default help. See
[unsupported retained surfaces](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/extensions.md).


---

<!-- Editorial source: docs/versions/v5/native/overview.md; based on 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; URL: https://hack.foo/docs/v5/native/overview -->
# Native backend (beta)

The native backend is a second way for Hack to run your project. It is a beta for
Apple Silicon Macs. Docker Compose is still the default, and nothing changes for a
project unless you choose native for it.

## What it is

Hack needs something to run your services in. Today that is Docker Compose, which
needs a Docker app running on your machine.

With the native backend, Hack runs your Compose project in a small Linux virtual
machine that Hack owns. Docker runs inside that machine, so you do not need Docker
Desktop or OrbStack on the Mac. Hack starts the machine, checks it, and cleans up
after it.

It is not a different container format. Your images and your Compose file are the
same. All your native projects share one virtual machine, the way Compose projects
share one Docker machine.

Your project stays the same. The `.hack/` folder, the commands (`hack up`,
`hack down`, `hack logs`) and your env and secrets are the same on both backends.

## What it is not

- **Not the default.** Compose runs your project unless you select native.
- **Not in stable Hack.** It ships only through the separate `hack-next` channel.
  The stable release archives and the Homebrew formula do not contain it.
- **Not for every platform.** It runs on Apple Silicon macOS only. Intel Macs,
  Linux and Windows use Compose.
- **Not a full replacement for Compose yet.** It supports a limited set of commands
  and Compose features. See [what works and known limits](/docs/v5/native/limits).
- **Not a migration.** Trying native does not convert your project or move your
  data. Your stable setup is left alone.
- **Not proven faster or lighter.** We have published no measurement that compares
  native with Compose, so we make no speed, memory or battery claims.
- **Not a wall between projects.** Native projects share one virtual machine.

## Why try it

What you get today:

- **No Docker Desktop install or licence.** Hack brings what it needs.
- **Ports stay on your machine.** A Compose port bound to every network interface
  (`0.0.0.0`) is narrowed to your own machine, so a dev service is not open to the
  network you are on.
- **You can limit where containers connect.** An optional list names the hosts your
  containers may reach.
- **Risky container settings are refused.** For example, `privileged: true` does not
  run.
- **Images are checked when pulled.** Hack verifies each image against its digest, a
  fingerprint of its exact contents.
- **Crashes are handled in the open.** Hack detects a crashed run and cleans it up
  with an explicit command. `hack down` keeps your data.
- **Safe to try.** `hack-next` installs beside stable Hack with its own files. It
  does not edit your PATH, your stable `hack`, or `~/.hack`.

What you give up today:

- Following logs live.
- Interactive shells in a container.
- UDP ports.
- Automatic restart for services that publish a port.
- A one-command setup. Preparing the runtime is still manual.

Use Compose if you need any of these.

## Who should try it

Try it if you use an Apple Silicon Mac, you are comfortable testing beta software,
and you have a project you can afford to break. Start with a disposable project
and synthetic data.

Stay on Compose if you need every Compose feature, you work on Linux or an Intel
Mac, or the project holds data you cannot lose.

## Where to go next

1. [Try it](/docs/v5/native/try-it): install, run one project on native, and switch back.
2. [What works and known limits](/docs/v5/native/limits).
3. [Reference](/docs/v5/native/reference): the detailed pages, by topic.


---

<!-- Editorial source: docs/versions/v5/native/try-it.md; based on 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; URL: https://hack.foo/docs/v5/native/try-it -->
# Try the native backend (beta)

This page takes one project to the native backend and back. You need an Apple
Silicon Mac. Read [what works and known limits](/docs/v5/native/limits) first, and use a project
you can afford to break.

Nothing here changes your stable Hack. Stable `hack`, `~/.hack` and your Compose
projects keep working the whole time.

## 1. Install the candidate

The native backend ships in v5 prereleases. Each prerelease has a fixed tag,
`v5.0.0-next.N`. Download the installer from the release you want, read it, then
run it:

```sh
curl --fail --location --proto '=https' --proto-redir '=https' --tlsv1.2 \
  https://github.com/hack-dance/hack/releases/download/v5.0.0-next.12/hack-next-install.sh \
  --output hack-next-install.sh
less hack-next-install.sh
sh hack-next-install.sh
"$HOME/.hack-next/bin/hack-next" --version
```

Everything goes into `~/.hack-next`. The installer does not edit your PATH, start a
virtual machine, or change DNS or certificate trust. Newer prereleases are on the
[releases page](https://github.com/hack-dance/hack/releases). For details, see
[Install](/docs/v5/install) and [Install the prerelease](/docs/v5/native/install).

## 2. Prepare the runtime

The native backend needs its virtual machine software set up once per installed
version. This step is manual today. Follow the provider setup steps in
[the native reference](/docs/v5/native/full-reference#manual-candidate-upgrade-and-rollback).

## 3. Check the project

Ask Hack whether the project can run on native before you start it:

```sh
"$HOME/.hack-next/bin/hack-next" doctor --path /absolute/project
```

`hack-next` selects the native backend by default. If the project uses a Compose
feature that native does not support, `doctor` names it. Starting the project would
refuse with `E_NATIVE_PROJECT_UNSUPPORTED` and change nothing. See
[Compose features that stay on Compose](/docs/v5/native/limits#compose-features-that-stay-on-compose).

## 4. Run it

```sh
"$HOME/.hack-next/bin/hack-next" up --path /absolute/project
```

Native `up` runs in the foreground and holds the project until you stop it. From a
second terminal:

```sh
"$HOME/.hack-next/bin/hack-next" ps --path /absolute/project
"$HOME/.hack-next/bin/hack-next" logs api --no-follow --path /absolute/project
"$HOME/.hack-next/bin/hack-next" down --path /absolute/project
```

Then check the application itself: sign in, load a page that reads data, restart,
and confirm the data is still there. A green status alone does not prove the
application works.

## 5. Switch back to Compose

You have two ways back.

**Use stable Hack.** Run `hack up` in the project as you always did. The native
test did not touch your stable setup.

**Run the same prerelease on Compose.** Set one variable:

```sh
HACK_RUNTIME_BACKEND=compose "$HOME/.hack-next/bin/hack-next" up --path /absolute/project
```

On Compose the prerelease uses your normal Hack home, the same one stable Hack
uses. Do not run both against it at once. Stop the stable daemon first; the order is
in [Stop stable hackd before a Compose run](/docs/v5/install#choose-a-backend).

Data does not move between backends. A database you filled on native is not in your
Compose volumes, and the other way round.

## Remove it

Stable Hack never depended on the candidate. To upgrade, roll back or stop using
`hack-next`, see
[Upgrade, roll back and return to stable](/docs/v5/native/install#upgrade-and-roll-back).


---

<!-- Editorial source: docs/versions/v5/native/limits.md; based on 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; URL: https://hack.foo/docs/v5/native/limits -->
# Native backend (beta): what works and known limits

The native backend supports part of what Compose supports. When a project needs
something outside that part, Hack refuses and tells you. It does not guess, and it
does not fall back to Docker without telling you.

## Platform

| Platform | Native backend |
| --- | --- |
| Apple Silicon macOS | Supported, through `hack-next` |
| Intel macOS | Not supported. The installer refuses before changing anything. |
| Linux and Windows | Not supported. Use the Compose backend. |
| Stable `hack` (Homebrew or the release installer) | Does not contain the native backend |

## Commands that work

| You want to | Native today |
| --- | --- |
| Start the whole project | `hack up`, in the foreground |
| Restart the whole project | `hack restart` |
| Stop the project | `hack down`, and `hack down --recover` after a crash |
| See what is running | `hack ps` |
| Read logs | `hack logs <service> --no-follow` |
| Run a command in a running service | `hack exec`, without an interactive terminal |
| Run a one-off command | `hack run`, for services without source, data or private env mounts |
| Preview without starting | `hack config validate`, `hack config plan`, `hack config import --dry-run`, `hack config adopt --dry-run` |

The exact rules for each command are in
[native authored commands](/docs/v5/native/authored-commands).

## Not supported yet

- Following logs live, or querying log history with Loki.
- Interactive `exec` sessions.
- Changing the env overlay, profiles or target of a project that is already
  running. Stop it and start it again.
- Starting or restarting single services. Native starts and restarts the whole
  project.
- UDP ports. Only TCP ports with an explicit host port are published.
- Automatic restart for services that publish a port.
- A one-command setup. Preparing the runtime is manual.

## Compose features that stay on Compose

A project that uses any of these runs on the Compose backend in v5. Native `up`
refuses with `E_NATIVE_PROJECT_UNSUPPORTED`, names the feature, and starts nothing.

| Compose feature | Why it stays on Compose |
| --- | --- |
| External networks | Native only uses networks it creates and owns |
| External volumes | Native only uses volumes it creates and owns |
| Labels Hack or Compose reserve | These labels prove which tool owns a resource |
| Builds beyond a basic `context`, `dockerfile` and `target` | Build arguments, secrets, SSH and cache options are not supported |
| Platforms other than Linux arm64 | The virtual machine runs Linux arm64. `linux/amd64` works only for services you opt in to emulation. |

Details and the exact checks:
[Compose projects that stay on the Compose backend](/docs/v5/native/full-reference#compose-projects-that-stay-on-the-compose-backend).

## Other limits

- **Shared machine.** All native projects run in one virtual machine. They are
  separated the way Compose projects are, not by a machine each.
- **Images.** Images need a Linux arm64 variant. Local registries need an explicit
  opt-in. Registries signed by a private certificate authority are not supported.
- **Data.** Data does not move between backends, or between prerelease versions.
  Each new prerelease starts with fresh native state.
- **Rollback.** An older prerelease may refuse state written by a newer one. That
  is a refusal, not a rollback.
- **Speed and resources.** Not measured in public yet. Do not assume native is
  faster or lighter than Compose.

The full list is under
[candidate capability limits](/docs/v5/guides/prereleases#candidate-capability-limits).

## When something is refused

A refusal is a result, not a bug to work around. Hack prints a one-line error with
a stable code and changes nothing. Do not loosen security settings, raise limits or
delete Hack's state to get past it. Run the project on Compose, and
[tell us](https://github.com/hack-dance/hack/issues) which feature you needed.


---

<!-- Editorial source: docs/versions/v5/native/reference.md; based on 4e51bc3f8119e154f49e040e606b6ed7f727d6d3; URL: https://hack.foo/docs/v5/native/reference -->
# Native backend (beta): reference

The detailed material, by topic. Start with the [overview](/docs/v5/native/overview) and
[try it](/docs/v5/native/try-it) if you have not used the native backend yet.

## Install and versions

- [Install](/docs/v5/install) and [Install the prerelease](/docs/v5/native/install): the `hack-next` channel,
  running both backends, upgrade and rollback.
- [Prerelease channel](/docs/v5/guides/prereleases): versions, platforms and what a
  release contains.

## Commands and configuration

- [Native authored commands](/docs/v5/native/authored-commands): exactly
  what `up`, `restart`, `down`, `ps`, `logs`, `exec` and `run` do on native.
- [Native config import](/docs/v5/native/config-import): preview and adopt
  an existing project's configuration.
- [Native settings files](/docs/v5/native/full-reference#native-settings-files):
  the committed project file and the per-machine file that replace exported
  variables.

## The full native reference

[The native backend reference](/docs/v5/native/full-reference) is one long page. These
are its main sections:

| Topic | Section |
| --- | --- |
| Which projects stay on Compose | [Compose projects that stay on the Compose backend](/docs/v5/native/full-reference#compose-projects-that-stay-on-the-compose-backend) |
| Runtime setup, upgrade and rollback | [Manual candidate upgrade and rollback](/docs/v5/native/full-reference#manual-candidate-upgrade-and-rollback) |
| How a Compose file is read | [Explicit normalized public Compose input](/docs/v5/native/full-reference#explicit-normalized-public-compose-input) |
| Container permissions | [Container capabilities and the security model](/docs/v5/native/full-reference#container-capabilities-and-the-security-model) |
| Pulling images | [Registry image acquisition without Docker](/docs/v5/native/full-reference#registry-image-acquisition-without-docker) |
| Registry sign-in | [Registry credentials](/docs/v5/native/full-reference#registry-credentials) |
| Sharing your source tree | [Explicit writable development source](/docs/v5/native/full-reference#explicit-writable-development-source) |
| What each command supports | [Frontend integration status](/docs/v5/native/full-reference#frontend-integration-status) |
| Intel-only images | [amd64 emulation with Rosetta 2](/docs/v5/native/full-reference#amd64-emulation-with-rosetta-2) |
| Local HTTPS | [Optional native HTTPS frontend](/docs/v5/native/full-reference#optional-native-https-frontend) |
| After a crash | [Explicit cleanup after a dead foreground owner](/docs/v5/native/full-reference#explicit-cleanup-after-a-dead-foreground-owner) |

## How it works

- [Architecture: backends](/docs/v5/architecture#backends) shows the two backends side
  by side.
- [Architecture: native backend internals](/docs/v5/architecture#native-backend-internals)
  explains ownership, startup and cleanup with state charts.
- [Model coverage](https://github.com/hack-dance/hack/blob/4e51bc3f8119e154f49e040e606b6ed7f727d6d3/docs/reference/v5-model-coverage.md) lists what the formal models
  check and what they do not.