Harden runtime integrity and diagnostics

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

@@ -10,6 +10,14 @@ description: >
 
 Use `hack` as the primary interface for local-first development.
 
+## Integration freshness
+
+- These instructions were generated by hack CLI v3.3.5; 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: `b8663fad3ef4` (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.
@@ -65,12 +73,13 @@ Use `hack` as the primary interface for local-first development.
 - Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.branch/compose.<branch>.override.yml`.
 - Managed via CLI: `.hack/.internal/extra-hosts.json` (use `hack internal extra-hosts ...` commands).
 - Lifecycle runtime files: `.hack/.internal/lifecycle/state.json`, `.hack/.internal/lifecycle/*.log`.
-- Ignore rules: hack owns a committed `.hack/.gitignore` (self-healing on init/up) covering machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`, `tickets/`); keep it committed, and if generated files leaked into git, `hack doctor --fix` untracks them (files stay on disk).
+- Ignore rules: hack owns a committed `.hack/.gitignore` (self-healing on init/up) covering machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`); keep it committed, and if generated files leaked into git, `hack doctor --fix` untracks them (files stay on disk).
 
 ## 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.
 - `hack doctor` flags divergent secret keys and dev_host collisions across checkouts.
 
 ## Advanced networking (extra_hosts + local proxies/tunnels)
@@ -110,11 +119,17 @@ Use `hack` as the primary interface for local-first development.
 
 - Put host setup in `.hack/hack.config.json` under `startup`/`lifecycle` (not ad-hoc terminal tabs).
 - Use `lifecycle.up.before` for pre-start hooks and `lifecycle.processes` for long-running host tasks.
+- Lifecycle hooks and processes receive the selected overlay's `global` values plus `host` overrides; service-scoped values remain container-specific unless a host command explicitly selects that scope.
 - For fixed-port host helpers such as SSM tunnels or local proxies, set `singleton.ports` and usually `onConflict: "adopt"` so Hack reuses a healthy existing listener instead of starting duplicate tunnel stacks.
 - `singleton` is a listener guard, not process ownership transfer; adopted external processes are left running on `hack down`.
 - Inspect lifecycle status via `hack projects --details` and stream via `hack logs <service-or-process>`.
 - Lifecycle session recovery is ownership-proven: Hack adopts healthy token-, definition-, and environment-matched sessions, replaces owned stale sessions, and refuses to kill same-name sessions without deterministic ownership proof.
 - `hack doctor --fix` reaps an orphan lifecycle session only when mux ownership is proven and its Compose instance is absent; unverified same-name sessions are never modified.
+- After `hack up` or `hack restart`, running services and successful one-shot services (`exited` with code 0) count as successful; other states return `E_STARTUP_INCOMPLETE`, and `hack doctor` warns about containers stuck in `Created`.
+- Detached startup is bounded; a hung Compose operation returns `E_STARTUP_TIMEOUT`, terminates its process group, and `hack doctor --fix` can start exact containers left in `Created`.
+- 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.
 
 ## Workspaces (mux-managed, tmux-first by default)
 
@@ -171,7 +186,8 @@ Use `hack` as the primary interface for local-first development.
 
 ## Agent integration maintenance
 
-- Project-level hack commands auto-check integration drift and attempt auto-sync (docs/skills/MCP).
+- Project-level hack commands auto-check integration drift and attempt auto-sync (project docs, client skills/rules, shared global skills, and MCP).
+- When drift is detected, Hack reports it before repair and tells the agent to reload after repair; it never silently leaves the session using cached rules.
 - Set `HACK_SETUP_SYNC_MODE=warn` to only warn, or `HACK_SETUP_SYNC_MODE=off` to disable.
 - Refresh project + user integrations: `hack setup sync --all-scopes`
 - Audit integration state only: `hack setup sync --all-scopes --check`
@@ -190,7 +206,3 @@ Use `hack` as the primary interface for local-first development.
 - Init patterns: `hack agent patterns`
 - MCP (no-shell only): `hack setup mcp`
 - MCP install (explicit): `hack mcp install --all --scope project`
-
-## Optional extensions
-
-- A local git-backed tickets extension exists (`hack tickets`) — only use it when the project explicitly uses it.

.cursor/rules/hack.mdc

@@ -5,6 +5,14 @@
 Hack v3 is local-first. This project uses `hack` for local runtime orchestration (compose + DNS/TLS + logs + sessions).
 Prefer `hack` when shell access is available. Use MCP only when shell access is unavailable.
 
+## Integration freshness
+
+- These instructions were generated by hack CLI v3.3.5; 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: `b8663fad3ef4` (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.
@@ -29,12 +37,13 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 - Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.branch/compose.<branch>.override.yml`.
 - Managed via CLI: `.hack/.internal/extra-hosts.json` (use `hack internal extra-hosts ...` commands).
 - Lifecycle runtime files: `.hack/.internal/lifecycle/state.json`, `.hack/.internal/lifecycle/*.log`.
-- Ignore rules: hack owns a committed `.hack/.gitignore` (self-healing on init/up) covering machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`, `tickets/`); keep it committed, and if generated files leaked into git, `hack doctor --fix` untracks them (files stay on disk).
+- Ignore rules: hack owns a committed `.hack/.gitignore` (self-healing on init/up) covering machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`); keep it committed, and if generated files leaked into git, `hack doctor --fix` untracks them (files stay on disk).
 
 ## 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.
 - `hack doctor` flags divergent secret keys and dev_host collisions across checkouts.
 
 ## Standard workflow
@@ -58,11 +67,17 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 
 - Put host setup in `.hack/hack.config.json` under `startup`/`lifecycle` (not ad-hoc terminal tabs).
 - Use `lifecycle.up.before` for pre-start hooks and `lifecycle.processes` for long-running host tasks.
+- Lifecycle hooks and processes receive the selected overlay's `global` values plus `host` overrides; service-scoped values remain container-specific unless a host command explicitly selects that scope.
 - For fixed-port host helpers such as SSM tunnels or local proxies, set `singleton.ports` and usually `onConflict: "adopt"` so Hack reuses a healthy existing listener instead of starting duplicate tunnel stacks.
 - `singleton` is a listener guard, not process ownership transfer; adopted external processes are left running on `hack down`.
 - Inspect lifecycle status via `hack projects --details` and stream via `hack logs <service-or-process>`.
 - Lifecycle session recovery is ownership-proven: Hack adopts healthy token-, definition-, and environment-matched sessions, replaces owned stale sessions, and refuses to kill same-name sessions without deterministic ownership proof.
 - `hack doctor --fix` reaps an orphan lifecycle session only when mux ownership is proven and its Compose instance is absent; unverified same-name sessions are never modified.
+- After `hack up` or `hack restart`, running services and successful one-shot services (`exited` with code 0) count as successful; other states return `E_STARTUP_INCOMPLETE`, and `hack doctor` warns about containers stuck in `Created`.
+- Detached startup is bounded; a hung Compose operation returns `E_STARTUP_TIMEOUT`, terminates its process group, and `hack doctor --fix` can start exact containers left in `Created`.
+- 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.
 
 ## Host-side env helpers
 
@@ -74,16 +89,13 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 
 ## Agent integration maintenance
 
-- Project-level hack commands auto-check integration drift and attempt auto-sync (docs/skills/MCP).
+- Project-level hack commands auto-check integration drift and attempt auto-sync (project docs, client skills/rules, shared global skills, and MCP).
+- When drift is detected, Hack reports it before repair and tells the agent to reload after repair; it never silently leaves the session using cached rules.
 - Set `HACK_SETUP_SYNC_MODE=warn` to only warn, or `HACK_SETUP_SYNC_MODE=off` to disable.
 - Refresh project + user integrations: `hack setup sync --all-scopes`
 - Audit integration state only: `hack setup sync --all-scopes --check`
 - Remove generated integration artifacts: `hack setup sync --all-scopes --remove`
 - After upgrading CLI: `hack update` then `hack setup sync --all-scopes`
 - When changing hack itself: interface or behavior changes must update docs/ in the same change (regenerate the CLI reference with `bun run docs:cli-reference`).
 
-## Optional extensions
-
-- A local git-backed tickets extension exists (`hack tickets`) — only use it when the project explicitly uses it.
-
 # END HACK INTEGRATION