pi-crew 0.11.38 → 0.11.39

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-crew",
-	"version": "0.11.38",
+	"version": "0.11.39",
 	"description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
 	"author": "baphuongna",
 	"license": "MIT",
@@ -118,7 +118,7 @@
 		"smoke:pi": "pi install .",
 		"smoke:release": "node scripts/release-smoke.mjs",
 		"prepack": "node scripts/clean-strip-types.mjs",
-		"prepublishOnly": "npm run ci",
+		"prepublishOnly": "node scripts/prepublish-ci.mjs",
 		"test:fast": "npm run test:critical && npm run test:bundle",
 		"check:wc-gate": "node scripts/wc-gate.mjs"
 	},

package/skills/real-test-pi-crew/SKILL.md

@@ -119,6 +119,7 @@ End-to-end verification discipline for pi-crew changes. Distilled from the broke
 | `src/ui/` | T1 → (T5|T6) → T13 |
 | `src/config/` (kể cả migration-validator) | T1 → T11c |
 | `src/runtime/child-pi/` (spawn/kill/steer) | T7 → T9g |
+| `src/runtime/process/**` (reap-group.ts / run-descendant-sweep.ts) + `child-pi-kill.ts` exited-root branch + `orphan-reaper.ts` identity admission + `crash-recovery.ts` terminal-sweep lane + state fields `childPgid/childStartTime/childUid` + heartbeat `pgid/starttime/uid` (wave-11 class: runtime spawn/kill/teardown + startup reconcile + state schema ADDITIVE) | T1 → pinned unit `test/unit/runtime/process/{reap-group,run-descendant-sweep}.test.ts` + `test/unit/runtime/recovery/reconcile-terminal-run-descendant-sweep.test.ts` + `test/unit/runtime/stale-reconciler-run-descendant-sweep.test.ts` + `test/unit/runtime/stale-reconciler-reap-escalation.test.ts` (5 file / 78 tests @ `f578c223`) → **integration live repro** `node scripts/test-runner.mjs test/integration/run-descendant-sweep-live.test.ts` (A1–A5: spawn leak THẬT → sweep reap ~100 ms; **negative control bắt buộc SỐNG**: no-marker / interactive-tty / parent-còn-sống) → off-path proof `PI_CREW_REAP_GROUP=0` + `PI_CREW_REAP_RUN_DESCENDANTS=0` (unit xanh trên CẢ hai trạng thái switch; KHÔNG để ambient `=0` sót lại làm run thật câm) → T9a `team action='doctor' focus='zombies'` (mảng `runDescendants` report-only + dòng cảnh báo no descent proof ⇒ NOT reaped) |
 | `src/runtime/mcp-proxy.ts` / `src/runtime/model/pi-args.ts` (worker argv build + MCP role-gate — G2/G3 surface, SDD-2) | T7 (`argv-flags.smoke.ts` với `PI_CREW_SMOKE=1`) → T9b-W loadout theo role (post-G2: read-only KHÔNG có MCP trên live-session path là ĐÚNG — xem mục full-loadout sanity 9b) + pinned suites `mcp-proxy.test.ts` / `phase6-runtime-hardening.test.ts` / `child-pi-timeout`+`child-pi-surface` (argv/spill) |
 | `src/runtime/async-runner.ts` / `src/runtime/background-runner.ts` (spawn, allowlist, entry-guard, `executeBackgroundRun` core) | T1 → T9b async (event `async.spawned` KHÔNG được có `data.inline:true` — battery phải chứng minh runner DETACHED thật) → T7; đụng `BACKGROUND_RUNNER_ENV_ALLOWLIST` → thêm T10b/T10c (quirk F4-2026-08-30: mux env bị strip ⇒ async headless âm thầm) |
 | `src/runtime/surface/` | T10a → T10b → T10c (dò herdr bằng `HERDR_ENV=1`, KHÔNG phải `$TMUX`) |
@@ -189,6 +190,10 @@ End-to-end verification discipline for pi-crew changes. Distilled from the broke
 
 > **2026-10-22 update (wave 10 — pi-subagents lessons port, v0.11.38, commits `b1288e3b`..`0ca9b552`, battery report `docs/real-test/reports/real-test-2026-10-22-wave10-pisub-lessons-battery.md`)**: 10 ports — W10-1 worker cache-retention split (`PI_CACHE_RETENTION=short` cho headless single-run; surface/RPC warm giữ parent default); W10-2 memoized green verify-gate theo tree OID (xem row verify-gate); W10-3 mailbox typed reason enum + strict replyTo routing (+ hardening `c95bb761`: findAskResponse iterate-past-mismatch, misroute-then-resend không park tới deadline, taskId-anchored filter); W10-4 `check-slop-rules` gate (3 scanner, ratchet 41 — row mới); W10-5 decision-drift guardian (critic/oracle inherited-decisions + DRIFT-BLOCK → verdict degrade `none`, fail-closed); W10-6 budget-boundary policy text (delegation-patterns: budgets chặn read-tools KHÔNG phải mutation-tools; elapsed-timeout KHÔNG phải mutation-safe boundary); W10-7 usage baseline-reconcile (per-attempt usage + note observability-only khi gap >5%); W10-8 read-lane same-tree guard (`git status --porcelain` gồm untracked → note `unexpectedMutation`, leader quyết); W10-9 typed JSON verification gates (row verify-gate); W10-10 CHANGELOG wave-10 + 2 lessons evidence-closed (spawn/parallel REVISED-BY-MEASUREMENT, declaration-pinning NOT-APPLICABLE). Battery coverage T1/T3/T4/T8/T7×3/T9a/T9g/T11a/c/j/T12 — PASS (unit 9876, integration 143, slop/lazy/staleness/size/bundle exit 0). Live-caught: verifier worker `cacheRead:11072` (prompt-cache reuse trên worker — evidence trực quan cho fork-cache PoC); T9b-W partial-honest (3-role spawn-path xanh thay full-loadout checklist). Hướng dẫn: đổi `src/runtime/verification/` hoặc task-runner post-execution → ngoài rows hiện có THÊM probe memo-hit (re-gate same-tree same-host → `verify-gate-memo: HIT`); đổi `prompt-runtime.ts` findAskResponse → chạy `ask-tool-replyto-routing.test.ts` (5) + `mailbox-replyto-reason.test.ts` (8) — 13 tests pin misroute-resend + taskId-anchor.
 
+> **2026-10-24 update (wave 11 — worker descendant reaping, commits `ed32c582`→`f578c223` gồm dist rebuild; report `docs/real-test/reports/real-test-2026-10-24-wave11-descendant-reaping.md`)**: (1) **Root cause KHÔNG phải "worker quên kill con"** — pi's bash tool spawn MỖI command `detached:true` (mỗi command một process group riêng, là con của pi worker chứ không nằm trong group worker) nên pid-only SIGTERM không bao giờ tới cháu; run `team_20261022110510_cefb9164af126460` terminal xong mà 6 cháu bash sống 24 h (~390 MB RSS). (2) **Surface mới `src/runtime/process/reap-group.ts` (F5)** — NƠI DUY NHẤT được signal một POSIX process group: `reapGroup` + `assertSafeGroup` (ladder từ chối 8 rung: POSIX + /proc đọc được; pgid nguyên > 1 — không bao giờ `kill(-1/0/1)`; không phải group/pid/parent của MÌNH theo REAL pgrp đọc từ `/proc` qua `selfIdentity()` — fix CRITICAL #1 host `setsid`; leader-proof = identity sống HOẶC snapshot caller chứng minh `pid===pgid` leader + starttime — snapshot không còn là identity thay thế, fix MAJOR #2 blind kill; same-uid; real-pgid == requested (PID-reuse); starttime bắt buộc; snapshot-starttime khớp live) + escalation SIGTERM (đồng bộ, postmortem-safe) → bounded poll → SIGKILL (timer unref — `drainReapEscalations()` / `flushReapEscalationsSync()` sở hữu rung cuối trên session shutdown). Wired: `child-pi-kill.ts` nhánh exited-root (snapshot pgid/starttime/uid TRƯỚC khi root chết; 60 s sweep prune) + `orphan-reaper.ts` admission bằng identity-proven (không còn tin `allowedPids` mù; scrub `PI_CREW_*` vẫn bắt buộc trước test). Kill switch `PI_CREW_REAP_GROUP=0`, default ON, FORWARD sang background runner (env-allowlist — switch không forward = câm im lặng). (3) **Surface mới `src/runtime/process/run-descendant-sweep.ts` (F7)** — `collectRunDescendants`/`reapRunDescendants` quét `/proc` (1 snapshot/pass, `buildProcSnapshot`) match marker mạnh→yếu: `run-id` (`PI_CREW_BROKER_RUN_ID` — 11b.4: marker KHÔNG phải proof, nhánh còn đòi một parent ĐÃ GHI ÂM (runner/worker/surface pane) ĐÃ CHẾT), `task-id` (`PI_CREW_KIND=subagent`+`PI_CREW_TASK_ID`+dead parent), `parent-pid` (`PI_CREW_PARENT_PID` chết — đúng dạng sự cố). Guard: same-uid, không phải self/ancestor, starttime ≥ runStart−60 s, **skip tty (lý do `interactive-tty`)**, leader chết hoặc là candidate khác, `surfacePids` sống bị loại. Kill switch `PI_CREW_REAP_RUN_DESCENDANTS=0` (no-op hoàn toàn, cũng forward sang runner). (4) **Startup lane** `crash-recovery.ts` `selectUnsweptTerminalRunIds`: mọi run terminal (`completed|failed|cancelled`) chưa có `descendantSweepAt`, `updatedAt` ≥ 60 s (grace cho pane), CŨ NHẤT TRƯỚC, cap 25/pass, window 200; `descendantSweepPending` retry sau 10 phút (HIGH-2: sweep-fail không leak vĩnh viễn). (5) **Doctor** `focus=zombies`: mảng `runDescendants` (report-only, dry-run) + cảnh báo process không chứng minh được descent ⇒ NOT reaped. (6) **State additive**: `TaskCheckpointState.childPgid/childStartTime/childUid` + `WorkerHeartbeatState.pgid/starttime/uid` — optional, record cũ degrade pid-only. (7) **Battery** (decision-table row mới): T1 + 5 unit suite (78 tests) + integration live repro A1–A5 (leak thật bị reap 91–121 ms, 3 negative control sống, 3/3 chạy ổn định) + off-path `=0` cả 2 switch + doctor dry-run; **ambient `PI_CREW_REAP_*=0` làm live repro câm — scrub trước khi chạy thật** (row Failure symptoms mới).
+
+> **2026-10-24 đính chính (wave 11c — battery findings F1+F2, mục 4b/7b của `docs/real-test/reports/real-test-2026-10-24-wave11-battery.md`)**: (1) **F2 sync-run miss ĐÃ FIX** — run sync/foreground không có `manifest.async.pid` nên leak mang `PI_CREW_PARENT_PID=<session pi pid>` không bao giờ qua descent proof (đúng rule 11 — an toàn nhưng bỏ sót vĩnh viễn). Từ 11c mọi manifest mới record `sessionPid` (= `process.pid` tại `createRunManifest`); `sweepTerminalRunDescendants` + doctor dry-run đưa nó vào `proofParents` với guard dead-only như mọi parent khác — session còn sống ⇒ KHÔNG là proof (user có thể đang dùng). Run async vẫn dùng `async.pid` primary. Battery addendum sẽ chứng minh bằng E2E sync-leak thật. (2) **F1 test-isolation ĐÃ FIX** — suite `run-descendant-sweep.test.ts` giờ pin `PI_CREW_REAP_RUN_DESCENDANTS=1` trong beforeEach (restore verbatim afterEach, pattern của `stale-reconciler-run-descendant-sweep`): 17/78 test không đỏ nữa khi ambient `=0`; pinned 78→82 (a20 + g8–g10); decision-table yêu cầu "unit xanh trên CẢ HAI trạng thái switch" giữ nguyên.
+
 ## Core principle: disk ≠ live Pi
 
 Two locations hold pi-crew state:
@@ -1258,6 +1263,7 @@ When a tier fails, the recovery is usually quick. Match the symptom to the cause
 | `team action='goal' budgetTotal=100000` rejected at validation ("must be equal to constant / must be number") | pi-ai stringifies numeric args on `Literal("")` unions; budgetTotal lacked the stringified-number branch its sibling budget params have. Fixed 2026-09-21 | Workaround pre-fix: `config.budgetUnlimited:true` (note: in config, NOT top-level) |
 | `team action='schedule' interval=<ms>` always says `Invalid schedule "<N>ms". Use "5m", …` | handle-schedule builds `${interval}ms`; both interval parsers lacked an `ms` unit — every numeric interval died. Fixed 2026-09-21 | The suggested "5m" formats only work via `cron`/`once` params, not `interval` (interval is schema-typed as a plain ms number) |
 | Runs keep appearing under one scheduled job; children of YOUR pi process; machine thrashing | **Interval ≥ 2^31-1 ms (≥24.8 days) overflowed the Node timer to a 1ms hot loop** (fixed 2026-09-22 — clamped hops). Check `.crew/audit/prune.jsonl` for interleaved auto-prunes. Contain: remove job, then `pkill -f '[b]ackground-runner.ts --cwd <root>'` | Any new timer scheduling must clamp below MAX_TIMER_DELAY_MS — grep for `setInterval(`/`setTimeout(` with computed delays |
+| Live sweep/reap probe chạy "xanh" nhưng KHÔNG process nào bị reap (doctor `runDescendants` liệt kê mà không có gì chết) | **Ambient `PI_CREW_REAP_GROUP=0` / `PI_CREW_REAP_RUN_DESCENDANTS=0` còn trong shell** (sót từ probe off-path trước) — cả 2 switch default ON và được FORWARD sang background runner, ambient là đủ để câm sạch cả sweep lẫn group-reap; ngược lại quên set khi test off-path thì nhánh degrade không được chứng minh | Trước MỌI live repro: `env \| grep PI_CREW_REAP` phải RỖNG; chỉ set `=0` CHỦ ĐÍCH khi chạy nhánh off-path (unit phải xanh trên CẢ hai trạng thái switch), unset ngay sau (wave 11 lesson — 2 kill switch KHÔNG được set ngoài ý muốn theo cả 2 hướng) |
 
 ## Release gate — battery → push → GitHub Actions GREEN → publish (canonical, 2026-10-14)
 
@@ -1270,7 +1276,7 @@ corpse → xóa file socket + rebind (STEAL lock) — fix bằng 3-strike takeov
 **Quy trình BẮT BUỘC cho mọi release (theo thứ tự, không bỏ bước):**
 
 1. Cập nhật skill (wave entry) + CHANGELOG heading cho version sắp release — commit.
-2. Chạy battery theo decision table (đủ tier cho paths đổi) — xanh hết.
+2. Chạy battery theo decision table (đủ tier cho paths đổi) — xanh hết, **kể cả integration live repro khi row đó yêu cầu** (vd wave 11 → `test/integration/run-descendant-sweep-live.test.ts` A1–A5 PHẢI xanh trước publish — live repro là tier duy nhất chứng minh sweep giết leak thật mà không đụng process của operator).
 3. `npm version patch` (tạo release commit + tag).
 4. `git push origin main --follow-tags` — pre-push hook tự chạy full unit local.
 5. **`gh run watch <runId> --exit-status` (hoặc poll `gh run list`) — CHỜ matrix 3-OS XANH TOÀN BỘ.**
@@ -1434,6 +1440,8 @@ Use this to answer "đủ full tính năng chưa?" without re-deriving. Every us
 | No-op writer gating (metric-sink crewRoot, prune-audit bail) | `src/observability/metric-sink.ts`, `src/extension/run-maintenance.ts` | `test/unit/extension/no-op-writers-no-crew-root.test.ts` (8) |
 | Worker-dashboard keybinding override (`.pi/teams`) | `src/ui/keybinding-map.ts` | `test/unit/ui/keybinding-map-override.test.ts` (8) |
 | Steer delivery incl. boot window (pre-bind retry) | `src/prompt/prompt-runtime.ts` (poll + `createSeenSteerIdSet.unmark`), `src/runtime/child-pi/child-pi-spawn.ts:283` (env), `src/runtime/task-runner/child-executor.ts:562` (filename) | `prompt-runtime-steer-boot-window.test.ts` (4) + **Tier 9g** live (watcher at +0.5s; lab variant with `PI_CREW_STEERING_FILE` + `pi --extension <repo>/src/prompt/prompt-runtime.ts`) |
+| Worker process-GROUP reaping (wave 11a F5 — đường group-signal DUY NHẤT) | `src/runtime/process/reap-group.ts` (`reapGroup` / `assertSafeGroup` guard-ladder 8 rung + escalation SIGTERM→poll→SIGKILL + `flushReapEscalationsSync`), wired `child-pi-kill.ts` exited-root (snapshot pgid/starttime trước khi root chết) + `orphan-reaper.ts` identity-proven admission | unit `node scripts/test-runner.mjs test/unit/runtime/process/reap-group.test.ts`; kill switch `PI_CREW_REAP_GROUP=0` (default ON — degrade về pid-only pre-wave; được FORWARD sang background runner); live: spawn worker có group con → kill root → group bị reap; **negative control bắt buộc: process cùng uid nhưng ngoài ladder (không leader-proof / không snapshot khớp) phải SỐNG** |
+| Run-descendant sweep (wave 11b F7 — reap leak sống sót SAU run terminal) | `src/runtime/process/run-descendant-sweep.ts` (`collectRunDescendants`/`reapRunDescendants`, 1 snapshot `/proc`/pass) + `crash-recovery.ts` `selectUnsweptTerminalRunIds` lane (terminal ≥ 60 s, oldest-first, cap 25/pass, window 200, retry `descendantSweepPending` 10 phút) | unit sweep suites (xem decision-table row wave 11) + **integration live repro** `node scripts/test-runner.mjs test/integration/run-descendant-sweep-live.test.ts` (A1–A5) + report `docs/real-test/reports/real-test-2026-10-24-wave11-descendant-reaping.md`; kill switch `PI_CREW_REAP_RUN_DESCENDANTS=0` (no-op hoàn toàn); marker ladder `PI_CREW_BROKER_RUN_ID` (nhánh run-id cần recorded parent ĐÃ CHẾT) → `PI_CREW_KIND=subagent`+`PI_CREW_TASK_ID` → `PI_CREW_PARENT_PID`; **negative control bắt buộc: no-marker / interactive-tty / parent-sống phải SỐNG** |
 
 ---
 

package/src/config/env-allowlist-registry.ts

@@ -225,6 +225,14 @@ const CREW_ENV_FORWARDING_DECL: Record<string, CrewEnvForwardDecision> = {
 		kind: "gap",
 		reason: "v0.11.36 sandbox network profile (share|off) read in the PARENT spawn path only — deliberately never forwarded to children",
 	},
+	PI_CREW_REAP_GROUP: allowlist(
+		["background-runner"],
+		"fix-wave 11a process-group reap kill switch — read by the reaping code (reap-group.ts resolveReapGroupEnabled) which ALSO runs inside the detached background runner; unforwarded it would be silently inert there (wave 11a review MINOR #7). Not forwarded to children: a worker must not be able to disable its own reaping",
+	),
+	PI_CREW_REAP_RUN_DESCENDANTS: allowlist(
+		["background-runner"],
+		"fix-wave 11b run-scoped descendant sweep kill switch (run-descendant-sweep.ts resolveRunDescendantSweepEnabled) — the stale reconciler that drives the sweep also runs inside the detached background runner, so the same inert-switch argument as PI_CREW_REAP_GROUP applies. Not forwarded to children: a worker must not be able to disable its own reaping",
+	),
 	PI_CREW_STEERING_FILE: { kind: "child-write", reason: "child-pi-spawn per-run steering JSONL" },
 	PI_CREW_MAX_OUTPUT: { kind: "child-write", reason: "pi-args emits agent.maxTokens into built.env" },
 	PI_CREW_RPC_SECRET: { kind: "child-write", reason: "shared HMAC secret handed to the child at spawn — secret name, never allowlisted" },
@@ -461,9 +469,13 @@ const BG_CREW_CORE_ORDER = [
 const BG_CREW_MODEL_ORDER = ["PI_CREW_MODEL", "PI_CREW_MODEL_FALLBACK_ORDER"] as const;
 const BG_CREW_STATE_ORDER = ["PI_CREW_STATE_BACKEND", "PI_CREW_CHILD_PI_MODE", "PI_CREW_CHILD_PI_POOL"] as const;
 const BG_CREW_TOOLS_ORDER = ["PI_CREW_TOOLS_MODIFIERS"] as const;
+// Wave 11a review (MINOR #7): the reap kill switch must be honoured by the
+// detached runner too — the runner (and the surface workers it spawns) own
+// kill/reap paths, so an unforwarded switch was silently inert there.
+const BG_CREW_REAP_ORDER = ["PI_CREW_REAP_GROUP", "PI_CREW_REAP_RUN_DESCENDANTS"] as const;
 const CHILD_CREW_DEPTH_ORDER = ["PI_CREW_DEPTH"] as const;
 
-const BG_CREW_GROUPS = [BG_CREW_CORE_ORDER, BG_CREW_MODEL_ORDER, BG_CREW_STATE_ORDER, BG_CREW_TOOLS_ORDER] as const;
+const BG_CREW_GROUPS = [BG_CREW_CORE_ORDER, BG_CREW_MODEL_ORDER, BG_CREW_STATE_ORDER, BG_CREW_TOOLS_ORDER, BG_CREW_REAP_ORDER] as const;
 
 /**
  * Generate the detached background-runner allowlist (exported AS
@@ -488,6 +500,7 @@ export function backgroundRunnerEnvAllowlist(): string[] {
 		...BG_CREW_MODEL_ORDER,
 		...BG_CREW_STATE_ORDER,
 		...BG_CREW_TOOLS_ORDER,
+		...BG_CREW_REAP_ORDER,
 	];
 }
 

package/src/config/env-vars.ts

@@ -321,6 +321,18 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 		default: 7_200_000,
 		doc: "max background run duration; default 2h (background-runner.ts:31)",
 	},
+	PI_CREW_REAP_GROUP: {
+		name: "PI_CREW_REAP_GROUP",
+		parser: "boolean",
+		default: true,
+		doc: "wave 11a kill switch for identity-proven PROCESS-GROUP reaping: '0'/'false' degrades child-pi-kill + orphan-reaper to their pre-wave pid-only paths (resolveReapGroupEnabled, reap-group.ts). FORWARDED to the detached background runner (env-allowlist-registry: PI_CREW_REAP_GROUP → background-runner) because the runner/worker process is the one that reaps its own children — an unforwarded switch would be silently inert there",
+	},
+	PI_CREW_REAP_RUN_DESCENDANTS: {
+		name: "PI_CREW_REAP_RUN_DESCENDANTS",
+		parser: "boolean",
+		default: true,
+		doc: "wave 11b kill switch for the RUN-SCOPED descendant sweep: '0'/'false' makes collectRunDescendants/reapRunDescendants (run-descendant-sweep.ts) a complete no-op. FORWARDED to the detached background runner (env-allowlist-registry: → background-runner) for the same reason as PI_CREW_REAP_GROUP: the reconciler that drives the sweep also runs there. Never forwarded to a worker",
+	},
 	PI_CREW_MAX_WORKERS: {
 		name: "PI_CREW_MAX_WORKERS",
 		parser: "int",

package/src/extension/registration/lifecycle-handlers.ts

@@ -42,6 +42,7 @@ import { tryRegisterSessionCleanup } from "../../runtime/session-resources.ts";
 import { createSessionSnapshot } from "../../runtime/session-snapshot.ts";
 import { applyCrewSettingsTiersToConfig, loadCrewSettingsTiers, scheduledJobsHiddenCountOf } from "../../runtime/settings-store.ts";
 import type { ReconcileResult } from "../../runtime/stale-reconciler.ts";
+import { flushReapEscalationsSync } from "../../runtime/stale-reconciler.ts";
 import { loadRunManifestById, saveRunManifest } from "../../state/stores/state-store.ts";
 import type { TeamRunManifest } from "../../state/types.ts";
 import { installInlinePanel } from "../../ui/inline-panel/index.ts";
@@ -166,6 +167,17 @@ function installSessionShutdownHandler(pi: ExtensionAPI, ctx: RegistrationContex
 		if (reason === "quit" || reason === "reload") {
 			// Actual shutdown — abort foreground runs and cleanup everything
 			ctx.cleanupRuntime();
+			// Wave 11a review (MAJOR #3): the group-reap SIGKILL rung is a chain of
+			// UNREF'd timers owned by an async escalation, and this handler is SYNC —
+			// without this flush the last rung is abandoned the moment the process
+			// exits. Delivered AFTER `cleanupRuntime()` so escalations armed by that
+			// cleanup are included. Each entry re-validates before signalling and the
+			// call never throws.
+			try {
+				flushReapEscalationsSync();
+			} catch (error) {
+				logInternalError("register.session-shutdown.flush-reap-escalations", error);
+			}
 		} else {
 			// Session switch (resume/new/fork) — cleanup resources but preserve foreground runs
 			ctx.cleanupSessionResourcesOnly();

package/src/extension/team-tool/doctor.ts

@@ -10,6 +10,7 @@ import { getPiTempBase } from "../../runtime/model/pi-args.ts";
 import { getRuntimeWarmupStatus } from "../../runtime/model/runtime-warmup.ts";
 import { currentSessionModel, sessionModelSnapshot } from "../../runtime/model/session-model.ts";
 import { getPiSpawnCommand } from "../../runtime/pi-spawn.ts";
+import { type RunDescendant, reapRunDescendants } from "../../runtime/process/run-descendant-sweep.ts";
 import { formatZombieReport, scanZombieSubagents, type ZombieScanResult } from "../../runtime/process/zombie-scanner.ts";
 import { launchScriptRegistry, sweepLaunchScripts, sweepOrphanLaunchScriptFiles } from "../../runtime/surface/launch-script.ts";
 import { surfaceProviderForCleanup } from "../../runtime/surface/resolve-surface.ts";
@@ -18,10 +19,12 @@ import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
 import { TeamToolParams } from "../../schema/team-tool-schema.ts";
 import { atomicWriteFile, atomicWriteJson } from "../../state/atomic-write.ts";
 import { TEAM_TERMINAL_RUN_STATUSES } from "../../state/contracts.ts";
+import { loadRunManifestById } from "../../state/stores/state-store.ts";
 import { allTeams, discoverTeams } from "../../teams/discover-teams.ts";
 import { type FatalFsCause, fsFailureLabel } from "../../utils/fs-errno.ts";
 import { projectCrewRoot, userCrewRoot } from "../../utils/paths.ts";
 import { allWorkflows, discoverWorkflows } from "../../workflows/discover-workflows.ts";
+import { listRecentRuns } from "../run-index.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { validateResources } from "../validate-resources.ts";
 import { configRecord, result, type TeamContext } from "./context.ts";
@@ -859,6 +862,121 @@ export function formatOrphanPaneReport(cleanup: DoctorSurfaceCleanupResult): str
 	return lines.join("\n");
 }
 
+/** How many recent TERMINAL runs the report-only descendant sweep inspects. */
+const RUN_DESCENDANT_SCAN_RUN_LIMIT = 5;
+
+/** One terminal run plus the surviving processes that still carry its markers. */
+export interface RunDescendantReport {
+	runId: string;
+	descendants: RunDescendant[];
+}
+
+/**
+ * Wave 11b (F7) — REPORT ONLY. pi's bash tool spawns every command `detached`,
+ * so a worker's grandchildren live in their own process groups and outlive the
+ * run (the 390 MB / 24 h leak after team_20261022110510 completed). This scan
+ * finds the survivors by the pi-crew env markers they inherited and lists them
+ * for the operator.
+ *
+ * Nothing is killed here BY CONSTRUCTION: `reapRunDescendants` is called with
+ * `dryRun: true`, which makes every candidate land in `skipped` with reason
+ * `dry-run` — the candidates themselves arrive in `descendants` for the report.
+ * The automatic reap is the stale reconciler's job (terminal runs only, never
+ * inside a worker), not the doctor's.
+ */
+export function collectRunDescendantReport(cwd: string, limit = RUN_DESCENDANT_SCAN_RUN_LIMIT): RunDescendantReport[] {
+	const reports: RunDescendantReport[] = [];
+	let inspected = 0;
+	let manifests: ReturnType<typeof listRecentRuns>;
+	try {
+		// A generous window: terminal runs are the only ones eligible, and old ones
+		// may dominate the recent list.
+		manifests = listRecentRuns(cwd, ORPHAN_RUN_SCAN_LIMIT * 5);
+	} catch {
+		return reports;
+	}
+	for (const manifest of manifests) {
+		if (inspected >= limit) break;
+		if (!TEAM_TERMINAL_RUN_STATUSES.has(manifest.status)) continue;
+		inspected += 1;
+		let loaded: ReturnType<typeof loadRunManifestById>;
+		try {
+			loaded = loadRunManifestById(cwd, manifest.runId);
+		} catch {
+			continue;
+		}
+		if (!loaded) continue;
+		const runnerPid = manifest.async?.pid;
+		// Wave 11c (F2): same proof-parent source as the automatic sweep, so the
+		// report lists exactly what the sweep would reap — a SYNC run's leak
+		// naming its dead session pi as parent.
+		const sessionPid = manifest.sessionPid;
+		const workerPids = [
+			...new Set(
+				loaded.tasks
+					.map((task) => task.heartbeat?.pid ?? task.checkpoint?.childPid)
+					.filter((pid): pid is number => typeof pid === "number" && Number.isInteger(pid) && pid > 1),
+			),
+		];
+		const startedAtMs = Date.parse(manifest.async?.spawnedAt ?? manifest.createdAt);
+		// 11b.3: the same surface-pane exclusion the automatic sweep applies — a
+		// LIVE pane pid is not a leak, so the report must not list it either.
+		const surfacePids = [
+			...new Set(
+				Object.values(manifest.surface?.workerPids ?? {}).filter(
+					(pid): pid is number => typeof pid === "number" && Number.isInteger(pid) && pid > 1,
+				),
+			),
+		];
+		const result = reapRunDescendants(
+			{
+				runId: manifest.runId,
+				...(runnerPid !== undefined ? { runnerPid } : {}),
+				workerPids,
+				...(sessionPid !== undefined ? { sessionPid } : {}),
+				...(surfacePids.length > 0 ? { surfacePids } : {}),
+				taskIds: loaded.tasks.map((task) => task.id),
+				startedAtMs: Number.isFinite(startedAtMs) ? startedAtMs : 0,
+			},
+			{ dryRun: true },
+		);
+		if (result.descendants.length > 0) reports.push({ runId: manifest.runId, descendants: result.descendants });
+	}
+	return reports;
+}
+
+/** Render {@link collectRunDescendantReport} for the zombies focus of doctor. */
+export function formatRunDescendantReport(reports: RunDescendantReport[]): string {
+	const lines: string[] = [];
+	lines.push("## Run descendants of terminal runs (report-only — nothing killed)");
+	lines.push("");
+	if (reports.length === 0) {
+		lines.push(`No surviving process matched a terminal run's pi-crew markers (last ${RUN_DESCENDANT_SCAN_RUN_LIMIT} terminal runs).`);
+		return lines.join("\n");
+	}
+	const total = reports.reduce((sum, report) => sum + report.descendants.length, 0);
+	lines.push(`Survivors: ${total} process(es) across ${reports.length} terminal run(s).`);
+	lines.push("Matched by inherited marker (run-id → task-id → parent-pid); the run-id marker alone is not proof of descent —");
+	lines.push("a candidate must also name a recorded parent of the run that is already dead. A descendant that called setsid or");
+	lines.push("runs in its own container cannot be proven and is not listed.");
+	lines.push("");
+	for (const report of reports) {
+		lines.push(`Run ${report.runId} — ${report.descendants.length} process(es):`);
+		for (const descendant of report.descendants) {
+			const rss = descendant.rssKb > 0 ? `${Math.round(descendant.rssKb / 1024)} MB` : "rss ?";
+			lines.push(`  - pid ${descendant.pid} pgid ${descendant.pgid ?? "?"} [${descendant.matchedBy}] ${rss} — ${descendant.cmd}`);
+		}
+	}
+	lines.push("");
+	lines.push("Automatic reaping happens in the stale reconciler, per candidate: it only signals a process that proves descent");
+	lines.push("(a recorded runner/worker parent that is already dead) inside a terminal run, that holds no controlling terminal,");
+	lines.push("and whose process group has a dead leader or a leader that is itself a candidate (a live unmatched leader blocks");
+	lines.push("the group). A same-uid process that merely inherited a run's env — an operator shell, or a service the run left");
+	lines.push("running — has no such proof and is deliberately NOT reaped, so a survivor listed above may stay alive by design.");
+	lines.push("Never runs inside a worker. PI_CREW_REAP_RUN_DESCENDANTS=0 disables it entirely.");
+	return lines.join("\n");
+}
+
 export async function handleDoctor(ctx: TeamContext, params: TeamToolParamsValue = {}): Promise<PiTeamsToolResult> {
 	// Sub-focus: zombie sub-agent scan + orphan surface-pane cleanup (T12). The
 	// process scan itself stays READ-ONLY — never kills a process. The pane
@@ -871,7 +989,11 @@ export async function handleDoctor(ctx: TeamContext, params: TeamToolParamsValue
 	if (params.focus === "zombies") {
 		const scan = scanZombieSubagents();
 		const cleanup = await cleanupOrphanSurfacePanes({ cwd: ctx.cwd, scan });
-		const text = `${formatZombieReport(scan)}\n\n${formatOrphanPaneReport(cleanup)}`;
+		// Wave 11b (F7): the zombie scan cannot see a terminal run's pi-bash
+		// grandchildren (they carry no PI_CREW_SURFACE and their recorded parent is
+		// the dead runner). The run-scoped sweep does — REPORT ONLY, dryRun.
+		const runDescendants = collectRunDescendantReport(ctx.cwd);
+		const text = `${formatZombieReport(scan)}\n\n${formatOrphanPaneReport(cleanup)}\n\n${formatRunDescendantReport(runDescendants)}`;
 		return result(
 			text,
 			{
@@ -884,6 +1006,8 @@ export async function handleDoctor(ctx: TeamContext, params: TeamToolParamsValue
 					// never pane-cleaned; see zombie-scanner.ts discriminator notes).
 					foreignPi: scan.foreign.length,
 					errors: scan.errors.length,
+					// Wave 11b: report-only count of a terminal run's surviving descendants.
+					runDescendants: runDescendants.reduce((sum, report) => sum + report.descendants.length, 0),
 					orphanPanes: cleanup.orphans.length,
 					panesClosed: cleanup.closed.length,
 					panesGone: cleanup.gone.length,

package/src/runtime/child-pi/child-pi-kill.ts

@@ -29,6 +29,7 @@ import { spawn } from "node:child_process";
 import { DEFAULT_CHILD_PI } from "../../config/defaults.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { TailCaptureStage } from "../compaction/compact-stages/tail-capture-stage.ts";
+import { type ProcIdentity, readProcIdentity, reapGroup, resolveReapGroupEnabled } from "../process/reap-group.ts";
 import { HARD_KILL_MS } from "./child-pi-constants.ts";
 import { adoptOwnedProcess, disposeAllOwnedProcesses, type OwnedProcess } from "./owned-process.ts";
 
@@ -44,6 +45,34 @@ const childHardKillTimers = new Map<number, NodeJS.Timeout>();
 // once the owner reaches its terminal state.
 const ownedByPid = new Map<number, OwnedProcess>();
 
+// Wave 11a (F1): the /proc identity snapshot of each registered child, taken
+// AT REGISTRATION (while the child is definitely alive). This is the only
+// pre-exit record of the child's pgid/starttime — once the root exits, /proc is
+// gone and `adoptOwnedProcess`'s live pgid resolution (owned-process.ts) has
+// nothing left to read, so a still-live group becomes unreachable. killProcessTree
+// uses this snapshot for the exited-root case; the 60 s sweep prunes it once the
+// owner is terminal.
+const identityByPid = new Map<number, ProcIdentity>();
+
+// Wave 11a injection seam (same shape as zombie-scanner.ts `__test`): tests seed
+// identity snapshots and swap the group reaper without a real child process.
+let reapGroupImpl: typeof reapGroup = reapGroup;
+export const __test = {
+	/** Seed the exit-time identity snapshot for a pid (as registerActiveChild would). */
+	seedIdentity(pid: number, identity: ProcIdentity | undefined): void {
+		if (identity === undefined) identityByPid.delete(pid);
+		else identityByPid.set(pid, identity);
+	},
+	/** Drop every seeded/recorded identity snapshot. */
+	clearIdentities(): void {
+		identityByPid.clear();
+	},
+	/** Replace the group reaper (undefined restores the real one). */
+	setReapGroup(fn: typeof reapGroup | undefined): void {
+		reapGroupImpl = fn ?? reapGroup;
+	},
+};
+
 // Periodic cleanup of dead child process entries to prevent memory leaks.
 // If a child process never emits exit/close (zombie), the entry would leak.
 setInterval(() => {
@@ -57,7 +86,10 @@ setInterval(() => {
 	// U15: prune adopted owners that reached terminal state (group confirmed
 	// gone via dispose or drain-reconcile). Non-terminal owners stay routable.
 	for (const [pid, owner] of ownedByPid) {
-		if (owner.terminated) ownedByPid.delete(pid);
+		if (!owner.terminated) continue;
+		ownedByPid.delete(pid);
+		// Wave 11a: the owner confirmed its group is gone — the snapshot is spent.
+		identityByPid.delete(pid);
 	}
 }, 60_000).unref();
 
@@ -69,6 +101,11 @@ export function registerActiveChild(pid: number, child: ChildProcess): void {
 	// (authoritative /proc check on Linux — the rpc branch child, spawned
 	// without detached, lands on the single-process fallback automatically).
 	ownedByPid.set(pid, adoptOwnedProcess(child, { name: `child-pi:${pid}` }));
+	// Wave 11a (F1): snapshot the identity NOW — the child is alive here, so
+	// /proc is readable. killProcessTree's exited-root branch reaps the group
+	// from this snapshot after the root is gone.
+	const identity = readProcIdentity(pid);
+	if (identity) identityByPid.set(pid, identity);
 }
 
 /**
@@ -220,7 +257,36 @@ export function killProcessTree(pid: number | undefined, child?: ChildProcess):
 		void owned.dispose();
 		return;
 	}
-	if (child && child.exitCode !== null) return;
+	if (child && child.exitCode !== null) {
+		// Wave 11a (F1): an EXITED ROOT IS NOT AN EMPTY GROUP. The root may have
+		// backgrounded descendants that are still alive in its process group; the
+		// pre-wave early-out returned here and left them running forever. We reap
+		// the group only when the registration-time snapshot PROVES the root was
+		// its own group leader (pgid === pid) — reapGroup re-validates everything
+		// (uid/pgid/starttime) and refuses on a recycled pgid. No snapshot, or a
+		// non-leader root, keeps the pre-wave behaviour exactly (no signal, and
+		// nothing logged above debug).
+		const identity = identityByPid.get(pid);
+		if (identity?.pgid === pid && resolveReapGroupEnabled()) {
+			const result = reapGroupImpl(pid, pid, { name: `child-pi:exited-root:${pid}`, expected: identity });
+			// MINOR #5 (review): the SIGKILL escalation is fire-and-forget here (this
+			// caller is sync), so it must be explicitly swallowed — `reapGroup` never
+			// rejects by contract, but a `void` promise is exactly what turns an
+			// unexpected rejection into a FATAL unhandled rejection on Node 22.
+			void result.pending.catch(() => {
+				/* settle-only: the escalation verdict is not actionable here */
+			});
+			identityByPid.delete(pid);
+		} else {
+			logInternalError(
+				"child-pi.kill-exited-root-no-snapshot",
+				new Error(`exited root pid=${pid} has no group-leader snapshot; no signal sent`),
+				`pid=${pid}`,
+				"debug",
+			);
+		}
+		return;
+	}
 	killProcessPid(pid);
 	child?.once("exit", () => clearHardKillTimer(pid));
 }

package/src/runtime/child-pi/child-pi-spawn.ts

@@ -198,6 +198,10 @@ export function buildChildPiSpawnOptions(
 		},
 		stdio: ["ignore", "pipe", "pipe"], // stdin=ignore: child doesn't wait for input; task comes via CLI args
 		detached: process.platform !== "win32",
+		// Wave 11a (GAP-5): `setsid` is NOT a Node spawn option — it is silently
+		// ignored. Group leadership comes from `detached` alone (POSIX setsid() in
+		// the child). Kept verbatim instead of deleted: removing it would suggest a
+		// behaviour change that never happened.
 		setsid: true,
 		// NOTE: setsid creates a new session; the child process becomes the session leader
 		// and its parent becomes that session leader (still the team-runner in the same

package/src/runtime/heartbeat/worker-heartbeat.ts

@@ -1,6 +1,10 @@
 export interface WorkerHeartbeatState {
 	workerId: string;
 	pid?: number;
+	/** Wave 11a (F3): spawn-time identity of `pid` (see `readProcIdentity`). */
+	pgid?: number;
+	starttime?: string;
+	uid?: number;
 	lastSeenAt: string;
 	lastStdoutAt?: string;
 	lastEventAt?: string;