pi-crew 0.11.38 → 0.11.40

package/CHANGELOG.md

@@ -2,6 +2,109 @@
 
 ## [Unreleased]
 
+## [0.11.40] — fix wave 12: fixture teardown — test-harness orphan leaks (2026-10-24)
+
+Closes the leak class wave 11 exposed but did not own: the reaping wave made production descendants provable, and
+then two fixtures of the shape `node -e "process.on('SIGTERM',()=>{}); setInterval(...)"` were found alive **> 6 h**
+after their run completed, re-parented to systemd. Both were tests with `finally { child.kill() }` teardown — a
+pid-only signal that cannot reach a tree, is a no-op against a SIGTERM-swallower, and never runs at all when the
+spawn happens after the throw (SPEC `fixwave12-fixture-teardown-2026-10-24`).
+
+**Added — `test/helpers/fixture-process.ts` (the fixture counterpart of `src/runtime/process/reap-group.ts`).**
+- `spawnFixture` / `reapFixture` / `registerFixtureTrap`: pgid-correct fixture lifecycle. `spawnFixture` snapshots
+  identity (`readProcIdentity`) at spawn and normalises `pgid` to `pid` (a detached child leads its own group), so
+  the later group kill is pgid-reuse-proof; `reapFixture` escalates SIGTERM → SIGKILL and never throws (it runs in
+  `finally`, where a throw would mask the failure under test); a refusal that PROVES the pid is a stranger
+  (`starttime-mismatch`, `uid-mismatch`, `not-group-member`) signals nothing rather than pid-killing a recycled pid.
+- `spawnFixture` **refuses non-detached children** by throwing: a non-detached fixture shares the test runner's
+  group, so a group kill rooted at it would signal the runner, sibling test files and the harness.
+- `registerFixtureTrap` flushes registered handles **synchronously** on `exit`/`SIGINT`/`SIGTERM`, covering the abort
+  window where no `finally` runs.
+
+**Fixed — HIGH orphan leak (`test/integration/background-runner-sigint-cleanup.test.ts`).** The grandchild group is
+now reaped even when an assertion throws; the harness stays pid-only by design (documented in
+`test/helpers/README.md`).
+
+**Fixed — orphan risk in three more fixtures.** `test/unit/retrieval-orchestrator.test.ts` (the fake `rg` writes its
+pid/pgid and the group is reaped), `test/unit/runtime/child-pi/inference-broker.test.ts` (the live `pi` is spawned
+detached and its group reaped via `reapFixture`; the 90 s timer is demoted to a safety net, not the teardown), and
+`test/unit/runtime/process/reap-group.test.ts` (the `spawnTree` failure path reaps its own group — GAP-4).
+
+**Fixed — teardown race (`test/unit/extension/team-tool-steer-clamp.test.ts`).** `ENOTEMPTY` on `afterEach`: the
+fire-and-forget `appendEventAsync` re-creates the run directory after a plain `rmSync`. Now uses
+`removeDirWithRetry` (the existing helper) so the retry absorbs the async writer.
+
+**Added — `getuid?: () => number | undefined` seam** on `ReapGroupOptions`/`SweepOptions`, propagated to the sweep's
+`reapGroup` call site so discovery and group kill can never disagree about the uid (`process.getuid` is undefined on
+win32); this also removes 3 duplicated `process.getuid` monkeypatches from tests.
+
+**Tests.** `test/unit/runtime/process/getuid-seam.test.ts` (10 pins), `test/unit/helpers/fixture-process.test.ts`
+(5 pins: h1–h5), `test/helpers/README.md` (fixture lifecycle rules: detached ⇒ group reap with the spawn-time
+identity snapshot, non-detached ⇒ pid-only with the reason in a comment, never read identity in `finally`).
+
+**Fixed — shard regression.** `helpers: 180` weight registered in `scripts/test-runner.mjs` (wave 12a created
+`test/unit/helpers/`, which had no shard weight).
+
+**Docs.** real-test skill: wave-12 decision-table row, history entry, failure symptom, coverage row, and the
+wave-12d lesson (teardown of a directory with async writers must retry).
+
+**Battery (PASS).** 30/30 targeted runs, `test:critical` 124/124, full unit 10,009 pass / 2 load-flakes (adjudicated
+isolated ×3), integration 144/0, static gates 0, dist MATCH.
+
+## [0.11.39] — fix wave 11: worker descendant reaping (2026-10-24)
+
+Closes the leak that motivated the wave: run `team_20261022110510_cefb9164af126460` reached `completed` on
+2026-10-22 and six grandchild processes (`dpi-backend` ×5 + `caddy`, ~390 MB RSS) were still alive 24 h later.
+Root cause (SPEC `fixwave11-worker-reaping-2026-10-24` GAP-0): pi's bash tool spawns EVERY command with
+`detached: true`, so a worker's bash grandchildren own a process group that a group kill rooted at the worker can
+never reach.
+
+**11a — identity-proven group kill (F1–F4).**
+
+- `src/runtime/process/reap-group.ts` is now the ONE place that may signal a process group: a refusal ladder
+  (POSIX only, `pgid > 1`, never our own real pgrp, live-identity-or-leader-proof, same uid, member of the requested
+  group, starttime present + matching) plus a bounded SIGTERM → SIGKILL escalation. SIGTERM is delivered
+  synchronously; the SIGKILL rung is handed back as `pending` and owned by `drainReapEscalations()`
+  (stale reconciler) or `flushReapEscalationsSync()` (shutdown), never dropped.
+- `child-pi-kill.ts` (F1): an exited ROOT no longer means "nothing left" — when the snapshot proves the root led its
+  own group, the group is reaped.
+- `orphan-reaper.ts` (F2): recorded workers are reaped through the guarded group ladder when a pgid is known,
+  identity-proven candidates bypass the zombie-scan gate, and a scanner throw is now fail-open for proven candidates
+  instead of a blanket no-op.
+- `state/types.ts` + `child-executor.ts` (F3): `pgid`/`starttime`/`uid` are persisted on the checkpoint and worker
+  heartbeat (all optional — old records load unchanged), which is what makes identity proof real on the next run.
+- `frame-client.ts` (F4): the prototype RPC frame client spawns detached. The production RPC path uses the SDK
+  `RpcClient`, which exposes no spawn knob — those workers stay non-leaders.
+
+**11b — run-scoped descendant sweep (F7, the actual cure for GAP-0).**
+
+- New `src/runtime/process/run-descendant-sweep.ts`: `collectRunDescendants()` / `reapRunDescendants()` enumerate
+  `/proc`, match the pi-crew env markers a descendant INHERITED, and reap only through a group that can be proven.
+  Markers used (verified in src, none invented): `PI_CREW_BROKER_RUN_ID` (`child-pi-spawn.ts:382`) ⇒ `run-id`;
+  `PI_CREW_KIND=subagent` + `PI_CREW_TASK_ID` + `PI_CREW_PARENT_PID` in the recorded set ⇒ `task-id`;
+  a `PI_CREW_PARENT_PID` that is a recorded worker pid and is dead ⇒ `parent-pid`. `PI_CREW_RUN_ID` is deliberately
+  NOT matched (registry: `test-only`, no src writer).
+- Guards: Linux `/proc` only (else `[]`, fail-open); never self, never an ancestor, same uid only; the candidate must
+  have started no earlier than the run (> 60 s of pre-run clock skew rejected); the candidate's group must not be ours;
+  one signal per group per leader incarnation (idempotent across reconciler ticks); and an extra rung — a group whose
+  LEADER is alive and carries no marker is skipped (`leader-alive-unmatched`), so a live session's group is never hit.
+- Call sites: `stale-reconciler.ts` sweeps ONLY when the run is terminal, the process is not a worker
+  (`PI_CREW_KIND`/crew depth 0), and every recorded runner/worker pid is dead; `team-tool/doctor.ts` (`focus=zombies`)
+  reports the survivors as `runDescendants` — report-only, `dryRun: true`, nothing killed.
+- Kill switches: `PI_CREW_REAP_GROUP` (11a) and `PI_CREW_REAP_RUN_DESCENDANTS` (11b), both boolean, default ON, both
+  forwarded to the detached background runner (never to a worker) so a disable actually takes effect where the reaping
+  runs.
+
+**Known limitations** (unchanged by design, documented on the module and in the SPEC): a descendant that calls
+`setsid()` or runs inside its own container/init (`docker`, `systemd-run`) has a group we cannot prove and is left
+alone; pi's bash tool remains the primary source of detached grandchildren — the upstream fix (tracked, non-detached
+children for tool commands, or a cgroup/subreaper for the worker tree) is what would make this sweep unnecessary;
+and the sweep can only match processes that still carry the markers (a scrubbed env is invisible).
+
+**11c — sync-run descent proof + test pin (leader-approved options (a) + F1 fix).**
+
+- Record sync-run `manifest.sessionPid` so foreground-run leaks satisfy the descent proof (wave 11c): a sync run has no `async.pid`, so a leaked worker grandchild whose `PI_CREW_PARENT_PID` points at the session pi itself could never be proven and was skipped forever; `sessionPid` is recorded at creation and treated as a recorded parent (dead-only, like the others). Also pin `PI_CREW_REAP_RUN_DESCENDANTS` in the sweep suite's setup so the tests no longer depend on the ambient kill-switch state. Battery addendum: `docs/real-test/reports/real-test-2026-10-24-wave11-battery-addendum.md` (F1/F2 closed, verdict PASS).
+
 ## [0.11.38] — Wave 10: pi-subagents lessons (10 ports) + watchdog hung-alert hardening (WD-DEDUP / WD-STALE-RECORD / WD-DELIVER-GUARD)
 
 ### Fixed — watchdog alerts for FINISHED runs: delivery-time guard (WD-DELIVER-GUARD, root-caused 2026-10-23)