Merge pull request #61 from hack-dance/codex/event-agent-runtime-repair

fix(runtime): isolate detached worktrees and recover orphan groups

Author: roodboi

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

@@ -70,7 +70,7 @@ Use `hack` as the primary interface for local-first development.
 ## 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; opt out with config `worktree.auto_branch=false` or an explicit `--branch`.
+- `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.
 - `hack doctor` flags divergent secret keys and dev_host collisions across checkouts.
 
 ## Advanced networking (extra_hosts + local proxies/tunnels)

.cursor/rules/hack.mdc

@@ -34,7 +34,7 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 ## 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; opt out with config `worktree.auto_branch=false` or an explicit `--branch`.
+- `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.
 - `hack doctor` flags divergent secret keys and dev_host collisions across checkouts.
 
 ## Standard workflow

AGENTS.md

@@ -261,7 +261,7 @@ Project files (managed vs generated):
 
 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; opt out with config `worktree.auto_branch=false` or an explicit `--branch`.
+- `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.
 - `hack doctor` flags divergent secret keys and dev_host collisions across checkouts.
 
 Advanced networking (extra_hosts + local proxies/tunnels):

CLAUDE.md

@@ -131,7 +131,7 @@ Project files (managed vs generated):
 
 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; opt out with config `worktree.auto_branch=false` or an explicit `--branch`.
+- `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.
 - `hack doctor` flags divergent secret keys and dev_host collisions across checkouts.
 
 Advanced networking (extra_hosts + local proxies/tunnels):

docs/architecture.md

@@ -122,6 +122,16 @@ Projects can run host-side hooks around `hack up/down` and start managed host pr
 local proxies/tunnels). Processes are started inside a mux session (tmux or zellij) so they have a
 stable home and can be torn down on `hack down`.
 
+Lifecycle state is checkout-local at `.hack/.internal/lifecycle/state.json`. For tmux processes, the
+saved process group belongs to the wrapped user command rather than its mux pane shell. Each compose
+instance has its own entry, so starting a branch instance does not replace the base instance's entry
+in the same checkout. Cleanup reconciles the saved process group with the live process table; if the group
+leader exited while members remain, `hack doctor` reports the orphan. `hack down` terminates the
+persisted leaderless group and descendant process groups only while a matching lifecycle mux session
+still proves ownership; without that session, cleanup stays non-destructive because the numeric PGID
+may have been reused. A live group leader without its saved pane PID is likewise not trusted as
+lifecycle ownership.
+
 For fixed-port helpers such as SSM/database/search tunnels, lifecycle config can also declare a
 `singleton` listener set. This lets Hack reuse an already-running equivalent helper or fail fast on
 partial conflicts instead of launching a competing duplicate supervisor. The intent is to reduce local
@@ -267,6 +277,10 @@ the primary checkout through the shared git common dir (see "Project env + secre
 `hack doctor` checks for divergent secret keys and `dev_host` collisions across checkouts sharing the
 same repo.
 
+If the linked worktree is detached, Hack refuses to silently target the base compose project because
+there is no branch name from which to derive an isolated instance. Pass `--branch <name>` to select
+one, or set `worktree.auto_branch=false` to opt into the base instance explicitly.
+
 ## Files and directories
 
 - `~/.hack/` (default; override the whole root with `HACK_HOME`)

docs/cli.md

@@ -94,6 +94,10 @@ branch when no `--branch` is passed (`worktree.auto_branch`), so two checkouts n
 same hostnames. A one-line notice is printed to stderr when the default kicks in, so captured
 stdout stays clean.
 
+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

docs/core.md

@@ -31,7 +31,9 @@ alive. You do not need gateway, remote nodes, or extension setup to use this pat
   `HACK_NO_INTERACTIVE=1`) so scripted/agent runs never block on prompts.
 - In a linked git worktree, `hack up` defaults to a branch instance named after the worktree's git
   branch (`worktree.auto_branch`), and the secret key is inherited automatically from the primary
-  checkout via the shared git common dir.
+  checkout via the shared git common dir. A detached linked worktree has no branch name to derive;
+  pass `--branch <name>`, or set `worktree.auto_branch=false` when intentionally targeting the base
+  instance.
 
 ## When to leave core
 

docs/lifecycle.md

@@ -212,8 +212,8 @@ Lifecycle session name:
 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.
-- For tmux-backed lifecycle sessions, Hack also persists pane PID and process-group metadata to
-  `.hack/.internal/lifecycle/state.json`, with per-hook/process output logged to
+- 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 when the persisted lifecycle entry no longer has a live mux session and points operators to `hack down` so cleanup and state removal happen through the supported path. `hack doctor --fix` does not tear down lifecycle sessions itself — use `hack down` for that.
 

src/agents/instruction-source.ts

@@ -122,7 +122,7 @@ export const INSTRUCTION_SECTIONS: readonly InstructionSection[] = [
     surfaces: ALL_SURFACES,
     bullets: [
       "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; opt out with config `worktree.auto_branch=false` or an explicit `--branch`.",
+      "`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.",
       "`hack doctor` flags divergent secret keys and dev_host collisions across checkouts.",
     ],
   },

src/commands/doctor.ts

@@ -1845,7 +1845,10 @@ async function checkProjectLifecycleHygiene({
   const inspection = await inspectProjectLifecycleHygiene({
     projectDir: ctx.projectDir,
   });
-  if (inspection.staleEntries.length === 0) {
+  if (
+    inspection.staleEntries.length === 0 &&
+    inspection.orphanedProcessGroups.length === 0
+  ) {
     return {
       name: "lifecycle hygiene",
       status: "ok",
@@ -1854,15 +1857,19 @@ async function checkProjectLifecycleHygiene({
     };
   }
 
-  const orphanedGroups = new Set<number>();
+  const orphanedGroups = new Set<number>(inspection.orphanedProcessGroups);
   for (const entry of inspection.staleEntries) {
     for (const group of entry.liveProcessGroups) {
       orphanedGroups.add(group);
     }
   }
 
   const details = [
-    `${inspection.staleEntries.length} stale lifecycle state entr${inspection.staleEntries.length === 1 ? "y" : "ies"}`,
+    ...(inspection.staleEntries.length > 0
+      ? [
+          `${inspection.staleEntries.length} stale lifecycle state entr${inspection.staleEntries.length === 1 ? "y" : "ies"}`,
+        ]
+      : []),
     ...(orphanedGroups.size > 0
       ? [
           `${orphanedGroups.size} orphaned lifecycle process group${orphanedGroups.size === 1 ? "" : "s"}`,