fix(runtime): prevent polling and stale worktree cache buildup (#71)

## Summary

- stop injecting `CHOKIDAR_USEPOLLING=true` and `WATCHPACK_POLLING=true`
into every generated service while preserving explicit user-authored
values
- make implicit `hack down` recover a uniquely owned same-checkout
runtime after a linked-worktree branch rename, and fail safely when
ownership is ambiguous
- add confirmation-gated `hack down --prune-caches` cleanup for exact
Compose-owned disposable cache volumes
- support any framework or language through the top-level Compose volume
label `hack.cache.disposable: "true"`; retain the narrow built-in
`.next` destination rule for existing Next caches
- document the root cause, contracts, safety boundaries, and
intentionally omitted noisy doctor checks

## Root cause

Hack's Compose generator unconditionally forced Chokidar and Watchpack
polling on every discovered service, including non-Next services.
Separately, linked-worktree branch renames changed the inferred Compose
project name, so an implicit `hack down` could succeed against an empty
target while leaving the checkout's real stopped runtime and cache
volumes behind. Ordinary Compose down correctly preserves named volumes,
but Hack had no project-scoped lifecycle for disposable branch build
caches.

The observed OrbStack/Next incident combined those Hack behaviors with
project-authored amd64 emulation and large persistent `.next` volumes.
This PR fixes only the behavior Hack owns; it does not rewrite project
platform or healthcheck configuration.

## Safety boundaries

- watcher defaults are runtime-agnostic and use native container-runtime
file notifications; explicit service-level polling remains supported
- branch retargeting requires the exact canonical checkout path and
Compose project family
- zero owned runtimes keep the inferred target; one is retargeted;
multiple fail and require explicit `--branch`
- cache cleanup is local-only, opt-in, previewed/confirmation-gated, and
requires `--yes` for JSON/noninteractive use
- candidates must be named volumes observed on exact target containers
with matching Compose project/service labels
- `docker volume inspect` must independently prove the exact Compose
project and logical-volume labels
- a cache must either be mounted exclusively at `.next` destinations or
explicitly carry `hack.cache.disposable=true`
- unlabeled `.turbo`, Postgres, Redis, application-data, bind,
foreign-project, and sibling-checkout volumes are preserved
- deletion uses exact `docker volume rm <name>` calls only; there is no
`down -v`, force removal, name matching, or broad prune

Already-orphaned volumes with no surviving container are deliberately
left alone because Hack cannot prove their former checkout and mount
destination safely.

## Verification

- 70 focused tests / 304 assertions passed across Compose generation,
linked-worktree targeting, down orchestration, disposable-volume
verification, lifecycle startup regression coverage, generated agent
guidance, and CLI-reference drift
- real Docker-tier E2E creates a Compose-labeled `.turbo` cache plus an
adjacent durable volume, writes data to both, runs `hack down
--prune-caches --yes --json`, proves the cache is removed, and mounts
the durable volume read-only to prove its data survived
- `bun run typecheck`
- `bun run check`
- `bun x ultracite check` (543 files after the E2E addition)
- `bun run privacy:check`
- `bun index.ts setup sync --all-scopes --check`
- `git diff --check`
- hosted secret scan, runtime-image builds, macOS test/build job, and
Docker E2E job pass

Local Docker execution was intentionally skipped because OrbStack and
the user's projects remain stopped; the local E2E isolation canary
passed and the Docker scenario executed successfully in isolated hosted
CI. No Event Agent, MSP, sick.email, OrbStack, Docker Desktop, or
machine-wide service was started locally. The prior real OrbStack A/B
evidence supports native watching, while the exact cleanup workflow now
has real standard-Docker coverage.

## Release decision

Yes: this is a user-visible runtime correctness fix and the Conventional
Commit / PR title intentionally carries a `fix` release signal. This
repository does not currently use a separate changeset artifact for this
flow.

Author: roodboi

.claude/settings.json

@@ -16,10 +16,7 @@
     "hack": {
       "type": "stdio",
       "command": "hack",
-      "args": [
-        "mcp",
-        "serve"
-      ]
+      "args": ["mcp", "serve"]
     }
   }
 }

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

@@ -12,11 +12,11 @@ Use `hack` as the primary interface for local-first development.
 
 ## Integration freshness
 
-- These instructions were generated by hack CLI v3.4.1; treat cached rules from another version as potentially stale.
+- These instructions were generated by hack CLI v3.5.0; treat cached rules from another version as potentially stale.
 - At session start, audit project and global integrations with `hack setup sync --all-scopes --check`.
 - If anything is stale, missing, or deprecated, run `hack setup sync --all-scopes`, then reload the agent session so cached instructions are replaced.
 - Never copy or hand-edit generated Hack rules to refresh them; update the CLI and run the sync command.
-- Content revision: `902b04fe1469` (version alone is not a freshness guarantee).
+- Content revision: `1319d93c89c3` (version alone is not a freshness guarantee).
 
 ## Product boundary
 
@@ -81,6 +81,7 @@ Use `hack` as the primary interface for local-first development.
 - Secret key inherits from the primary checkout automatically through the shared git common dir; set `HACK_ENV_SECRET_KEY` for CI or detached environments.
 - `hack up` in a linked worktree defaults to a branch instance named after the worktree's git branch; a detached linked worktree requires an explicit `--branch`, unless config `worktree.auto_branch=false` explicitly opts into the base instance.
 - Before `hack up` or `hack restart` auto-targets a new branch instance, Hack warns when the same worktree already owns a non-terminal instance; pass `--branch <name>` to make the target explicit.
+- Implicit `hack down` retargets a uniquely owned same-checkout runtime after a Git branch rename, including Created and stopped containers; when multiple runtimes belong to the checkout, pass `--branch <name>` explicitly.
 - `hack doctor` flags divergent secret keys and dev_host collisions across checkouts.
 
 ## Advanced networking (extra_hosts + local proxies/tunnels)
@@ -131,6 +132,7 @@ Use `hack` as the primary interface for local-first development.
 - Target only affected services with `hack up <service...> --detach`, `hack restart <service...>`, or `hack env apply --service <service>`; scoped operations skip project lifecycle hooks and implicit dependency startup.
 - Use `hack env explain <KEY> --env <overlay> --service <service> --target <host|compose>` for redacted source, precedence, availability, and delivery diagnostics.
 - Dependency installer services are detected generically by command or `hack.dependencies.bootstrap=true`; registry env references are preflighted before container mutation. Optional `hack.dependencies.cache-volume`, `hack.dependencies.lockfiles`, and `hack.dependencies.runtime-files` labels enable lockfile/runtime-keyed volumes shared across compatible worktrees.
+- `hack down --prune-caches` can remove only confirmed Compose-owned named volumes mounted exclusively at `.next` destinations or explicitly labeled `hack.cache.disposable=true`; it is confirmation-gated, requires `--yes` for JSON/scripted runs, and never performs broad volume pruning.
 
 ## Workspaces (mux-managed, tmux-first by default)
 

.cursor/mcp.json

@@ -2,10 +2,7 @@
   "mcpServers": {
     "hack": {
       "command": "hack",
-      "args": [
-        "mcp",
-        "serve"
-      ]
+      "args": ["mcp", "serve"]
     }
   }
 }

.cursor/rules/hack.mdc

@@ -7,11 +7,11 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 
 ## Integration freshness
 
-- These instructions were generated by hack CLI v3.4.1; treat cached rules from another version as potentially stale.
+- These instructions were generated by hack CLI v3.5.0; treat cached rules from another version as potentially stale.
 - At session start, audit project and global integrations with `hack setup sync --all-scopes --check`.
 - If anything is stale, missing, or deprecated, run `hack setup sync --all-scopes`, then reload the agent session so cached instructions are replaced.
 - Never copy or hand-edit generated Hack rules to refresh them; update the CLI and run the sync command.
-- Content revision: `902b04fe1469` (version alone is not a freshness guarantee).
+- Content revision: `1319d93c89c3` (version alone is not a freshness guarantee).
 
 ## Product boundary
 
@@ -44,6 +44,7 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 - Secret key inherits from the primary checkout automatically through the shared git common dir; set `HACK_ENV_SECRET_KEY` for CI or detached environments.
 - `hack up` in a linked worktree defaults to a branch instance named after the worktree's git branch; a detached linked worktree requires an explicit `--branch`, unless config `worktree.auto_branch=false` explicitly opts into the base instance.
 - Before `hack up` or `hack restart` auto-targets a new branch instance, Hack warns when the same worktree already owns a non-terminal instance; pass `--branch <name>` to make the target explicit.
+- Implicit `hack down` retargets a uniquely owned same-checkout runtime after a Git branch rename, including Created and stopped containers; when multiple runtimes belong to the checkout, pass `--branch <name>` explicitly.
 - `hack doctor` flags divergent secret keys and dev_host collisions across checkouts.
 
 ## Standard workflow
@@ -78,6 +79,7 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 - Target only affected services with `hack up <service...> --detach`, `hack restart <service...>`, or `hack env apply --service <service>`; scoped operations skip project lifecycle hooks and implicit dependency startup.
 - Use `hack env explain <KEY> --env <overlay> --service <service> --target <host|compose>` for redacted source, precedence, availability, and delivery diagnostics.
 - Dependency installer services are detected generically by command or `hack.dependencies.bootstrap=true`; registry env references are preflighted before container mutation. Optional `hack.dependencies.cache-volume`, `hack.dependencies.lockfiles`, and `hack.dependencies.runtime-files` labels enable lockfile/runtime-keyed volumes shared across compatible worktrees.
+- `hack down --prune-caches` can remove only confirmed Compose-owned named volumes mounted exclusively at `.next` destinations or explicitly labeled `hack.cache.disposable=true`; it is confirmation-gated, requires `--yes` for JSON/scripted runs, and never performs broad volume pruning.
 
 ## Host-side env helpers
 

AGENTS.md

@@ -210,11 +210,11 @@ Most formatting and common issues are automatically fixed by Biome. Run `bun x u
 Use `hack` as the single interface for local-first runtime orchestration (compose, DNS/TLS, logs, env, and persistent project workspaces).
 
 Integration freshness:
-- These instructions were generated by hack CLI v3.4.1; treat cached rules from another version as potentially stale.
+- These instructions were generated by hack CLI v3.5.0; treat cached rules from another version as potentially stale.
 - At session start, audit project and global integrations with `hack setup sync --all-scopes --check`.
 - If anything is stale, missing, or deprecated, run `hack setup sync --all-scopes`, then reload the agent session so cached instructions are replaced.
 - Never copy or hand-edit generated Hack rules to refresh them; update the CLI and run the sync command.
-- Content revision: `902b04fe1469` (version alone is not a freshness guarantee).
+- Content revision: `1319d93c89c3` (version alone is not a freshness guarantee).
 
 Product boundary:
 - Supported v3 surface: project init, up/down/restart, open, logs, env, host exec/shell, sessions, doctor, and daemon.
@@ -271,6 +271,7 @@ Linked git worktrees:
 - Secret key inherits from the primary checkout automatically through the shared git common dir; set `HACK_ENV_SECRET_KEY` for CI or detached environments.
 - `hack up` in a linked worktree defaults to a branch instance named after the worktree's git branch; a detached linked worktree requires an explicit `--branch`, unless config `worktree.auto_branch=false` explicitly opts into the base instance.
 - Before `hack up` or `hack restart` auto-targets a new branch instance, Hack warns when the same worktree already owns a non-terminal instance; pass `--branch <name>` to make the target explicit.
+- Implicit `hack down` retargets a uniquely owned same-checkout runtime after a Git branch rename, including Created and stopped containers; when multiple runtimes belong to the checkout, pass `--branch <name>` explicitly.
 - `hack doctor` flags divergent secret keys and dev_host collisions across checkouts.
 
 Advanced networking (extra_hosts + local proxies/tunnels):
@@ -316,6 +317,7 @@ Lifecycle + startup:
 - Target only affected services with `hack up <service...> --detach`, `hack restart <service...>`, or `hack env apply --service <service>`; scoped operations skip project lifecycle hooks and implicit dependency startup.
 - Use `hack env explain <KEY> --env <overlay> --service <service> --target <host|compose>` for redacted source, precedence, availability, and delivery diagnostics.
 - Dependency installer services are detected generically by command or `hack.dependencies.bootstrap=true`; registry env references are preflighted before container mutation. Optional `hack.dependencies.cache-volume`, `hack.dependencies.lockfiles`, and `hack.dependencies.runtime-files` labels enable lockfile/runtime-keyed volumes shared across compatible worktrees.
+- `hack down --prune-caches` can remove only confirmed Compose-owned named volumes mounted exclusively at `.next` destinations or explicitly labeled `hack.cache.disposable=true`; it is confirmation-gated, requires `--yes` for JSON/scripted runs, and never performs broad volume pruning.
 
 Workspaces (mux-managed, tmux-first by default):
 - Picker: `hack session` for persistent project workspaces.

CLAUDE.md

@@ -80,11 +80,11 @@ This project uses Obsidian for project context, specs, research, and progress tr
 Use `hack` as the single interface for local-first runtime orchestration (compose, DNS/TLS, logs, env, and persistent project workspaces).
 
 Integration freshness:
-- These instructions were generated by hack CLI v3.4.1; treat cached rules from another version as potentially stale.
+- These instructions were generated by hack CLI v3.5.0; treat cached rules from another version as potentially stale.
 - At session start, audit project and global integrations with `hack setup sync --all-scopes --check`.
 - If anything is stale, missing, or deprecated, run `hack setup sync --all-scopes`, then reload the agent session so cached instructions are replaced.
 - Never copy or hand-edit generated Hack rules to refresh them; update the CLI and run the sync command.
-- Content revision: `902b04fe1469` (version alone is not a freshness guarantee).
+- Content revision: `1319d93c89c3` (version alone is not a freshness guarantee).
 
 Product boundary:
 - Supported v3 surface: project init, up/down/restart, open, logs, env, host exec/shell, sessions, doctor, and daemon.
@@ -141,6 +141,7 @@ Linked git worktrees:
 - Secret key inherits from the primary checkout automatically through the shared git common dir; set `HACK_ENV_SECRET_KEY` for CI or detached environments.
 - `hack up` in a linked worktree defaults to a branch instance named after the worktree's git branch; a detached linked worktree requires an explicit `--branch`, unless config `worktree.auto_branch=false` explicitly opts into the base instance.
 - Before `hack up` or `hack restart` auto-targets a new branch instance, Hack warns when the same worktree already owns a non-terminal instance; pass `--branch <name>` to make the target explicit.
+- Implicit `hack down` retargets a uniquely owned same-checkout runtime after a Git branch rename, including Created and stopped containers; when multiple runtimes belong to the checkout, pass `--branch <name>` explicitly.
 - `hack doctor` flags divergent secret keys and dev_host collisions across checkouts.
 
 Advanced networking (extra_hosts + local proxies/tunnels):
@@ -186,6 +187,7 @@ Lifecycle + startup:
 - Target only affected services with `hack up <service...> --detach`, `hack restart <service...>`, or `hack env apply --service <service>`; scoped operations skip project lifecycle hooks and implicit dependency startup.
 - Use `hack env explain <KEY> --env <overlay> --service <service> --target <host|compose>` for redacted source, precedence, availability, and delivery diagnostics.
 - Dependency installer services are detected generically by command or `hack.dependencies.bootstrap=true`; registry env references are preflighted before container mutation. Optional `hack.dependencies.cache-volume`, `hack.dependencies.lockfiles`, and `hack.dependencies.runtime-files` labels enable lockfile/runtime-keyed volumes shared across compatible worktrees.
+- `hack down --prune-caches` can remove only confirmed Compose-owned named volumes mounted exclusively at `.next` destinations or explicitly labeled `hack.cache.disposable=true`; it is confirmation-gated, requires `--yes` for JSON/scripted runs, and never performs broad volume pruning.
 
 Workspaces (mux-managed, tmux-first by default):
 - Picker: `hack session` for persistent project workspaces.

docs/README.md

@@ -48,6 +48,8 @@ This section is easy to find, but it does not lead the product story.
 
 - New to `hack`: [Core docs](core.md)
 - Setting up with a coding agent: [Agent-first setup](guides/agent-first-setup.md)
+- Reviewing watcher, worktree-down, or disposable cache behavior:
+  [Development runtime safety](guides/development-runtime-safety.md)
 - Looking for command or API details: [Extensions & reference](reference.md), including the generated [CLI reference](reference/cli.md)
 - Need unsupported experimental remote workflows: [Beta workflows](beta.md)
 - Need the bucket definitions: [Docs information architecture](docs-ia.md)

docs/cli.md

@@ -166,6 +166,13 @@ same worktree. If the worktree's current branch would auto-target a different Co
 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.
@@ -177,6 +184,53 @@ Opt out:
 
 The primary checkout is unchanged: no `--branch` means the base instance.
 
+### 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