fix(runtime): clean descendant lifecycle groups

Author: roodboi

docs/architecture.md

@@ -126,9 +126,10 @@ Lifecycle state is checkout-local at `.hack/.internal/lifecycle/state.json`. Eac
 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 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.
+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

src/lib/project-lifecycle-processes.ts

@@ -134,14 +134,20 @@ export function resolveLeaderlessPersistedLifecycleProcessGroupIds(opts: {
     const groupLeaderStillExists = opts.snapshot.some(
       (row) => row.pid === processGroupId
     );
-    const groupHasMembers = opts.snapshot.some(
-      (row) => row.processGroupId === processGroupId
-    );
+    const groupMemberPids = opts.snapshot
+      .filter((row) => row.processGroupId === processGroupId)
+      .map((row) => row.pid);
     if (
       !(persistedPaneStillExists || groupLeaderStillExists) &&
-      groupHasMembers
+      groupMemberPids.length > 0
     ) {
-      groups.add(processGroupId);
+      const descendantGroups = collectDescendantProcessGroupIds({
+        snapshot: opts.snapshot,
+        rootPids: groupMemberPids,
+      });
+      for (const descendantGroup of descendantGroups) {
+        groups.add(descendantGroup);
+      }
     }
   }
 

tests/project-lifecycle-hygiene.test.ts

@@ -58,9 +58,10 @@ test("inspectLifecycleStateEntries reports leaderless groups behind a live mux s
     snapshot: [
       { pid: 501, ppid: 1, processGroupId: 500 },
       { pid: 502, ppid: 501, processGroupId: 500 },
+      { pid: 503, ppid: 502, processGroupId: 503 },
     ],
   });
 
   expect(inspection.staleEntries).toEqual([]);
-  expect(inspection.orphanedProcessGroups).toEqual([500]);
+  expect(inspection.orphanedProcessGroups).toEqual([500, 503]);
 });

tests/project-lifecycle-processes.test.ts

@@ -188,7 +188,7 @@ test("resolveLifecycleProcessGroupIdsForTmuxState ignores recycled process group
   expect(groups).toEqual([]);
 });
 
-test("resolveLifecycleProcessGroupIdsForTmuxState recovers a persisted leaderless group", () => {
+test("resolveLifecycleProcessGroupIdsForTmuxState recovers a persisted leaderless group and descendants", () => {
   const groups = resolveLifecycleProcessGroupIdsForTmuxState({
     lifecycleEntry: {
       composeProject: "event-agent",
@@ -211,10 +211,11 @@ test("resolveLifecycleProcessGroupIdsForTmuxState recovers a persisted leaderles
     snapshot: [
       { pid: 501, ppid: 1, processGroupId: 500 },
       { pid: 502, ppid: 501, processGroupId: 500 },
+      { pid: 503, ppid: 502, processGroupId: 503 },
     ],
   });
 
-  expect(groups).toEqual([500]);
+  expect(groups).toEqual([500, 503]);
 });
 
 test("resolvePersistedLifecycleProcessGroupIds recovers live groups without a mux session", () => {
@@ -297,13 +298,14 @@ test("resolveLifecycleStopProcessGroupIds skips a leaderless persisted group wit
     snapshot: [
       { pid: 501, ppid: 1, processGroupId: 500 },
       { pid: 502, ppid: 501, processGroupId: 500 },
+      { pid: 503, ppid: 502, processGroupId: 503 },
     ],
   });
 
   expect(groups).toEqual([]);
 });
 
-test("resolveLifecycleStopProcessGroupIds recovers a leaderless persisted group with a live mux session", () => {
+test("resolveLifecycleStopProcessGroupIds recovers a leaderless persisted group and descendants with a live mux session", () => {
   const groups = resolveLifecycleStopProcessGroupIds({
     matchedLiveSession: true,
     lifecycleEntry: {
@@ -326,10 +328,12 @@ test("resolveLifecycleStopProcessGroupIds recovers a leaderless persisted group
     snapshot: [
       { pid: 501, ppid: 1, processGroupId: 500 },
       { pid: 502, ppid: 501, processGroupId: 500 },
+      { pid: 503, ppid: 502, processGroupId: 503 },
+      { pid: 504, ppid: 503, processGroupId: 504 },
     ],
   });
 
-  expect(groups).toEqual([500]);
+  expect(groups).toEqual([500, 503, 504]);
 });
 
 test("wrapLifecyclePersistentCommand uses external kill for process-group cleanup", () => {