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

roodboi · roodboi · commit 80a8dd28f7b3 · 2026-07-09T15:40:47.000-04:00
diff --git a/.codex/skills/hack-cli/SKILL.md b/.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)
diff --git a/.cursor/rules/hack.mdc b/.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
diff --git a/AGENTS.md b/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):
diff --git a/CLAUDE.md b/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):
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -122,6 +122,13 @@ 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`. 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 and `hack down` terminates the
+persisted leaderless group. A live group leader without its saved pane PID is not trusted as lifecycle
+ownership because the PID may have been reused.
+
 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 +274,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`)
diff --git a/docs/core.md b/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
 
diff --git a/src/agents/instruction-source.ts b/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.",
     ],
   },
diff --git a/src/commands/doctor.ts b/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"}`,
diff --git a/src/commands/project.ts b/src/commands/project.ts
@@ -594,6 +594,11 @@ async function resolveEffectiveBranchForCommand(opts: {
     projectRoot: opts.project.projectRoot,
     autoBranchEnabled: resolveWorktreeAutoBranch(cfg),
   });
+  if (resolved.source === "detached-worktree") {
+    throw new CliUsageError(
+      "Detached linked worktree cannot auto-select an isolated instance. Pass --branch <name>, or set worktree.auto_branch=false to target the base instance explicitly."
+    );
+  }
   if (resolved.source === "worktree" && resolved.branch) {
     const message = `Linked worktree detected → using branch instance "${resolved.branch}" (override with --branch <name>, disable with worktree.auto_branch=false)`;
     if (opts.noticeToStderr === true) {
diff --git a/src/lib/branches.ts b/src/lib/branches.ts
@@ -160,7 +160,11 @@ export async function touchBranchUsage(opts: {
   return { updated: true, created, path: read.path };
 }
 
-export type EffectiveBranchSource = "explicit" | "worktree" | "none";
+export type EffectiveBranchSource =
+  | "explicit"
+  | "worktree"
+  | "detached-worktree"
+  | "none";
 
 export type EffectiveBranchResolution = {
   /** Branch instance slug to target, or null for the base instance. */
@@ -178,8 +182,10 @@ export type EffectiveBranchResolution = {
  * - otherwise, in a LINKED git worktree with `autoBranchEnabled` (config
  *   `worktree.auto_branch`, default true), default to the sanitized current
  *   git branch name (`source: "worktree"`)
- * - primary checkouts, non-git paths, detached HEAD, and opted-out projects
- *   resolve to the base instance (`branch: null`, `source: "none"`)
+ * - a detached linked worktree is reported separately so callers can refuse
+ *   an implicit base instance instead of colliding with the primary checkout
+ * - primary checkouts, non-git paths, and opted-out projects resolve to the
+ *   base instance (`branch: null`, `source: "none"`)
  */
 export async function resolveEffectiveBranch(opts: {
   readonly explicitBranch: string | null;
@@ -206,7 +212,11 @@ export async function resolveEffectiveBranch(opts: {
     repoRoot: opts.projectRoot,
   });
   if (!gitBranch) {
-    return { branch: null, source: "none", gitBranch: null };
+    return {
+      branch: null,
+      source: "detached-worktree",
+      gitBranch: null,
+    };
   }
 
   const slug = sanitizeBranchSlug(gitBranch);
diff --git a/src/lib/project-lifecycle-hygiene.ts b/src/lib/project-lifecycle-hygiene.ts
@@ -7,6 +7,7 @@ import { readLifecycleState } from "./lifecycle-runtime.ts";
 import {
   type ProcessSnapshotRow,
   readProcessSnapshot,
+  resolveLeaderlessPersistedLifecycleProcessGroupIds,
   resolvePersistedLifecycleProcessGroupIds,
 } from "./project-lifecycle-processes.ts";
 
@@ -17,6 +18,7 @@ export type StaleLifecycleStateEntry = {
 
 export type LifecycleHygieneInspection = {
   readonly staleEntries: readonly StaleLifecycleStateEntry[];
+  readonly orphanedProcessGroups: readonly number[];
 };
 
 /** Inspect persisted lifecycle state for entries whose mux session is gone. */
@@ -25,7 +27,7 @@ export async function inspectProjectLifecycleHygiene(opts: {
 }): Promise<LifecycleHygieneInspection> {
   const entries = await readLifecycleState({ projectDir: opts.projectDir });
   if (entries.length === 0) {
-    return { staleEntries: [] };
+    return { staleEntries: [], orphanedProcessGroups: [] };
   }
 
   const [sessionsByBackend, snapshot] = await Promise.all([
@@ -50,11 +52,20 @@ export function inspectLifecycleStateEntries(opts: {
   readonly snapshot: readonly ProcessSnapshotRow[];
 }): LifecycleHygieneInspection {
   const staleEntries: StaleLifecycleStateEntry[] = [];
+  const orphanedProcessGroups = new Set<number>();
 
   for (const entry of opts.entries) {
     const sessions = opts.sessionsByBackend.get(entry.backend);
     const sessionPresent = sessions?.has(entry.sessionName) ?? false;
     if (sessionPresent) {
+      const leaderlessGroups =
+        resolveLeaderlessPersistedLifecycleProcessGroupIds({
+          lifecycleEntry: entry,
+          snapshot: opts.snapshot,
+        });
+      for (const processGroupId of leaderlessGroups) {
+        orphanedProcessGroups.add(processGroupId);
+      }
       continue;
     }
 
@@ -67,7 +78,12 @@ export function inspectLifecycleStateEntries(opts: {
     });
   }
 
-  return { staleEntries };
+  return {
+    staleEntries,
+    orphanedProcessGroups: [...orphanedProcessGroups].sort(
+      (left, right) => left - right
+    ),
+  };
 }
 
 async function listSessionsByBackend(): Promise<
diff --git a/src/lib/project-lifecycle-processes.ts b/src/lib/project-lifecycle-processes.ts
@@ -103,10 +103,49 @@ export function resolveLifecycleProcessGroupIdsForTmuxState(opts: {
     }
   }
 
-  return collectDescendantProcessGroupIds({
+  const discoveredGroups = collectDescendantProcessGroupIds({
     snapshot: opts.snapshot,
     rootPids: [...rootPids],
   });
+  const leaderlessGroups = resolveLeaderlessPersistedLifecycleProcessGroupIds({
+    lifecycleEntry: opts.lifecycleEntry,
+    snapshot: opts.snapshot,
+  });
+  return [...new Set([...discoveredGroups, ...leaderlessGroups])].sort(
+    (left, right) => left - right
+  );
+}
+
+/** Recover persisted groups whose original leader is gone but members remain. */
+export function resolveLeaderlessPersistedLifecycleProcessGroupIds(opts: {
+  readonly lifecycleEntry: LifecycleStateEntry | null;
+  readonly snapshot: readonly ProcessSnapshotRow[];
+}): number[] {
+  const groups = new Set<number>();
+
+  for (const processInfo of opts.lifecycleEntry?.processes ?? []) {
+    const processGroupId = processInfo.processGroupId;
+    if (!(processGroupId && processGroupId > 1)) {
+      continue;
+    }
+    const persistedPaneStillExists =
+      processInfo.panePid !== undefined &&
+      opts.snapshot.some((row) => row.pid === processInfo.panePid);
+    const groupLeaderStillExists = opts.snapshot.some(
+      (row) => row.pid === processGroupId
+    );
+    const groupHasMembers = opts.snapshot.some(
+      (row) => row.processGroupId === processGroupId
+    );
+    if (
+      !(persistedPaneStillExists || groupLeaderStillExists) &&
+      groupHasMembers
+    ) {
+      groups.add(processGroupId);
+    }
+  }
+
+  return [...groups].sort((left, right) => left - right);
 }
 
 /** Recover live lifecycle process groups from persisted metadata when mux panes are gone. */
@@ -121,14 +160,17 @@ export function resolvePersistedLifecycleProcessGroupIds(opts: {
   });
 }
 
-/** Only trust persisted lifecycle pane metadata when a matching mux session was observed live. */
+/** Trust all live roots with a session, or only leaderless persisted groups without one. */
 export function resolveLifecycleStopProcessGroupIds(opts: {
   readonly matchedLiveSession: boolean;
   readonly lifecycleEntry: LifecycleStateEntry | null;
   readonly snapshot: readonly ProcessSnapshotRow[];
 }): number[] {
   if (!opts.matchedLiveSession) {
-    return [];
+    return resolveLeaderlessPersistedLifecycleProcessGroupIds({
+      lifecycleEntry: opts.lifecycleEntry,
+      snapshot: opts.snapshot,
+    });
   }
   return resolvePersistedLifecycleProcessGroupIds({
     lifecycleEntry: opts.lifecycleEntry,
diff --git a/tests/agent-instruction-source.test.ts b/tests/agent-instruction-source.test.ts
@@ -138,6 +138,7 @@ test("linked worktree guidance is present in every surface", () => {
   for (const rendered of Object.values(RENDERED_SURFACES)) {
     expect(rendered).toContain("Linked git worktrees");
     expect(rendered).toContain("HACK_ENV_SECRET_KEY");
+    expect(rendered).toContain("detached linked worktree");
     expect(rendered).toContain("worktree.auto_branch=false");
   }
 });
diff --git a/tests/branches-effective-branch.test.ts b/tests/branches-effective-branch.test.ts
@@ -107,7 +107,7 @@ test("primary checkout resolves to the base instance", async () => {
   expect(resolved.branch).toBeNull();
 });
 
-test("detached HEAD in a linked worktree resolves to the base instance", async () => {
+test("detached HEAD in a linked worktree refuses an implicit base instance", async () => {
   const fixture = await createFixture({ branch: "feature/detach-me" });
   await runGit(["checkout", "--detach"], fixture.linkedRoot);
 
@@ -117,6 +117,20 @@ test("detached HEAD in a linked worktree resolves to the base instance", async (
     autoBranchEnabled: true,
   });
 
+  expect(resolved.source).toBe("detached-worktree");
+  expect(resolved.branch).toBeNull();
+});
+
+test("worktree.auto_branch=false explicitly allows the base instance from detached HEAD", async () => {
+  const fixture = await createFixture({ branch: "feature/detached-opt-out" });
+  await runGit(["checkout", "--detach"], fixture.linkedRoot);
+
+  const resolved = await resolveEffectiveBranch({
+    explicitBranch: null,
+    projectRoot: fixture.linkedRoot,
+    autoBranchEnabled: false,
+  });
+
   expect(resolved.source).toBe("none");
   expect(resolved.branch).toBeNull();
 });
diff --git a/tests/e2e/scenarios/worktree-branch-default.ts b/tests/e2e/scenarios/worktree-branch-default.ts
@@ -3,6 +3,7 @@ import {
   expect,
   expectExit,
   extractJsonObject,
+  runCommand,
   type Scenario,
 } from "../harness.ts";
 
@@ -96,5 +97,52 @@ export const worktreeBranchDefaultScenario: Scenario = {
       message: `explicit --branch should win over the worktree default, got "${optOutUrl}"`,
       result: optOut,
     });
+
+    const detach = await runCommand({
+      argv: ["git", "checkout", "--detach"],
+      cwd: worktreePath,
+    });
+    expectExit({
+      result: detach,
+      codes: [0],
+      message: "failed to detach the linked worktree fixture",
+    });
+
+    const detachedOpen = await ctx.cli({
+      args: ["open", "--json"],
+      cwd: worktreePath,
+    });
+    expectExit({
+      result: detachedOpen,
+      codes: [1],
+      message: "detached linked worktree must refuse an implicit base instance",
+    });
+    expect({
+      that:
+        detachedOpen.combined.includes("Detached linked worktree") &&
+        detachedOpen.combined.includes("--branch <name>"),
+      message:
+        "detached worktree failure must explain the safe explicit override",
+      result: detachedOpen,
+    });
+
+    const detachedExplicit = await ctx.cli({
+      args: ["open", "--json", "--branch", "detached-review"],
+      cwd: worktreePath,
+    });
+    expectExit({
+      result: detachedExplicit,
+      codes: [0],
+      message:
+        "explicit branch should remain available from detached worktrees",
+    });
+    const detachedExplicitUrl =
+      extractJsonObject<OpenPayload>({ text: detachedExplicit.stdout })?.url ??
+      "";
+    expect({
+      that: detachedExplicitUrl.includes("detached-review"),
+      message: `explicit detached branch URL should carry the requested slug, got "${detachedExplicitUrl}"`,
+      result: detachedExplicit,
+    });
   },
 };
diff --git a/tests/project-lifecycle-hygiene.test.ts b/tests/project-lifecycle-hygiene.test.ts
diff --git a/tests/project-lifecycle-processes.test.ts b/tests/project-lifecycle-processes.test.ts
diff --git a/tests/run-exec-branch-default.test.ts b/tests/run-exec-branch-default.test.ts
