pi-crew 0.9.51 → 0.9.53

package/docs/fixes/bug-010-child-process-api-key-filtered.md

@@ -1,109 +0,0 @@
-# Bug #10: Child-Process Silent Timeout — MINIMAX_API_KEY Filtered Out
-
-**Date:** 2026-05-19
-**Severity:** HIGH
-**Type:** Bug (not design issue)
-**Status:** OPEN — Fix applied, pending verification
-
-## Summary
-
-Background child-process workers silently time out after 300 seconds with zero output
-because `MINIMAX_API_KEY` is filtered out by `sanitizeEnvSecrets()` before the child
-process is spawned. The child Pi has no API credentials to call the model.
-
-## Root Cause
-
-In `src/runtime/child-pi.ts` line 159-161:
-
-```typescript
-function buildChildPiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv): SpawnOptions {
-  const filteredEnv = sanitizeEnvSecrets(env);  // ← STRIPS ALL *API_KEY* VARS
-  return {
-    cwd,
-    env: { ...filteredEnv, PI_CREW_PARENT_PID: String(process.pid) },
-    ...
-  };
-}
-```
-
-The `sanitizeEnvSecrets()` function (in `src/utils/env-filter.ts`) uses a deny-list
-pattern to filter out keys matching secret patterns:
-
-```typescript
-SECRET_KEY_PATTERN = /(?:^|[_.-])(token|api[-_]?key|password|passwd|secret|credential|authorization|private[-_]?key)(?:$|[_.-])/i;
-```
-
-`MINIMAX_API_KEY` matches this pattern because `_API_KEY` contains `api_key` as a
-substring, which matches the `api[-_]?key` part of the regex.
-
-### Why foreground (live-session) works fine
-
-The live-session runtime in `live-session-runtime.ts` uses the SAME parent Pi session
-that already has the API key loaded. There's no separate child process — the live
-session inherits the parent's environment directly. No `sanitizeEnvSecrets()` call.
-
-### Why background (child-process) fails
-
-1. `team action='run'` with async=true → `background-runner.ts` → `child-pi.ts`
-2. Child Pi is spawned via `spawn()` with `buildChildPiSpawnOptions()`
-3. `buildChildPiSpawnOptions` calls `sanitizeEnvSecrets()` which strips `MINIMAX_API_KEY`
-4. Child Pi starts with no API key → cannot authenticate with MiniMax → hangs silently
-5. After 300s of no output, `response_timeout` fires and kills the process
-
-## Evidence
-
-All 7+ failed background workers show the same pattern:
-- `worker.spawned` — PID confirmed, process is alive
-- `task.attention` — 223+ seconds of idle (no stdout, no stderr, no jsonEvents)
-- `worker.response_timeout` — "No output for 300000ms"
-- `worker.exit` — `exitCode=null` (SIGTERM kill)
-
-No error output because the child Pi can't even report an auth failure — it simply
-silently waits for a model response that never comes.
-
-## Fix
-
-**File:** `src/runtime/child-pi.ts`
-
-In `buildChildPiSpawnOptions()`, change the `sanitizeEnvSecrets()` call to preserve
-model provider API keys:
-
-```typescript
-function buildChildPiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv): SpawnOptions {
-  // Preserve model provider API keys (MINIMAX_API_KEY, OPENAI_API_KEY, etc.)
-  // These are needed by the child Pi to call the configured model provider.
-  const filteredEnv = sanitizeEnvSecrets(env, {
-    allowList: ["MINIMAX_*", "OPENAI_*", "ANTHROPIC_*", "GOOGLE_*", "AZURE_*", "AWS_*", "ZEU_*", "ZERODEV_*", "*_API_KEY", "*_TOKEN", "*_SECRET"],
-  });
-  return {
-    cwd,
-    env: { ...filteredEnv, PI_CREW_PARENT_PID: String(process.pid) },
-    stdio: ["pipe", "pipe", "pipe"],
-    detached: process.platform !== "win32",
-    windowsHide: true,
-  };
-}
-```
-
-This uses the allow-list mode of `sanitizeEnvSecrets()` which only preserves keys
-matching the globs. All other secret-like keys (passwords, credentials, etc.) are still
-stripped. Only model API keys needed for the child process to call the LLM are
-preserved.
-
-## Why this is safe
-
-- Model API keys are not sensitive in the same way as passwords — they're designed
-  to be passed to API endpoints
-- The allow-list is specific to known provider prefixes — it doesn't blanket-allow
-  all env vars
-- Other secrets (DB passwords, internal credentials) are still filtered out
-- The `PI_CREW_PARENT_PID` is added after filtering so it won't conflict
-
-## Verification Plan
-
-1. Apply the fix to `src/runtime/child-pi.ts`
-2. Restart Pi to reload the extension
-3. Run a background team (e.g., `team action='run', team='research', async=true`)
-4. Verify the child process produces output within the first 30 seconds
-5. Compare env of child process (add temporary debug logging) to confirm
-   `MINIMAX_API_KEY` is present

package/docs/fixes/bug-011-spawn-pi-enoent.md

@@ -1,92 +0,0 @@
-# Bug #11: Background Runner "spawn pi ENOENT" — pi binary not in PATH
-
-**Date:** 2026-05-19
-**Severity:** 🔴 HIGH
-**Type:** Regression (broken in current session)
-**Status:** ✅ Fixed — added `resolvePiCliScript()` call for non-Windows platforms
-
-## Summary
-
-Background async team runs fail immediately with "spawn pi ENOENT" because the `getPiSpawnCommand()` function returns `command: "pi"` without resolving the full path on non-Windows platforms. When the detached background-runner process starts with a minimal PATH environment, it cannot find the `pi` binary.
-
-## Root Cause
-
-In `src/runtime/pi-spawn.ts` line 153-171:
-
-```typescript
-export function getPiSpawnCommand(args: string[]): PiSpawnCommand {
-  // ...
-  if (process.platform === "win32") {
-    const script = resolvePiCliScript();  // ← Only called on Windows!
-    if (script) return { command: process.execPath, args: [script, ...args] };
-  }
-  return { command: "pi", args };  // ← Returns bare "pi" on Linux/macOS!
-}
-```
-
-On Windows, the full path to the Pi entry point script is resolved via `resolvePiCliScript()`. On Linux/macOS, the function returns `command: "pi"` which relies on PATH lookup. When the detached background-runner process inherits a minimal PATH, `pi` is not found → `ENOENT`.
-
-## Why Live-Session Works
-
-Live-session runs use `child-pi.ts` → `getPiSpawnCommand()` for spawning child workers, but the parent Pi session has the full PATH including `/home/bom/.nvm/versions/node/v22.22.0/bin`. However, there was also a live-session failure in round 3 with "caller_cancelled" — likely a different issue (compaction guard, Bug #6).
-
-## Why Earlier Async Runs Worked
-
-Earlier async runs (before current session) had workers that:
-1. Spawned successfully (`worker.spawned` event with real PID)
-2. Ran for 5 minutes producing zero output
-3. Timed out with `response_timeout`
-
-Those were the SAME underlying bug (#10/8): `MINIMAX_API_KEY` filtered out. But they DID find the `pi` binary — meaning something changed in the current session that broke the PATH further.
-
-The NEW "spawn pi ENOENT" failure in the current session test is a SEPARATE issue: the background runner itself can't find `pi`, not just the child workers.
-
-## Fix
-
-**File:** `src/runtime/pi-spawn.ts`
-
-Changed from:
-
-```typescript
-if (process.platform === "win32") {
-  const script = resolvePiCliScript();
-  if (script) return { command: process.execPath, args: [script, ...args] };
-}
-return { command: "pi", args };
-```
-
-To:
-
-```typescript
-if (process.platform === "win32") {
-  const script = resolvePiCliScript();
-  if (script) return { command: process.execPath, args: [script, ...args] };
-}
-// Linux/macOS: also resolve the full path so child processes can find 'pi' even if
-// PATH is minimal (e.g. in detached background-runner processes). Fall back to "pi"
-// only if resolution fails.
-const script = resolvePiCliScript();
-if (script) return { command: process.execPath, args: [script, ...args] };
-return { command: "pi", args };
-```
-
-`resolvePiCliScript()` on Linux walks from `argv[1]` upward to find the pi-crew package root, then locates the Pi CLI script from the package bin. This gives an absolute path that doesn't depend on PATH.
-
-## Why `resolvePiCliScript()` Works
-
-On Linux, `process.argv[1]` for the running Node process points to the pi-crew entry script. Walking up the directory tree finds the `@mariozechner/pi-coding-agent` package root, then reads its `bin.pi` field to get the absolute path to the Pi CLI script (e.g., `/home/bom/.nvm/versions/node/v22.22.0/lib/node_modules/@mariozechner/pi-coding-agent/dist/cli.cjs`).
-
-This absolute path is then passed to `process.execPath` (Node.js) as the first argument, so the child process runs with:
-```
-node /path/to/pi/dist/cli.cjs [args]
-```
-
-This doesn't need PATH at all.
-
-## Verification Plan
-
-1. Restart Pi to reload pi-crew with the fix
-2. Run `team action='run', async=true` with a simple research task
-3. Verify `worker.spawned` events appear within 5 seconds
-4. Verify workers produce output within 60 seconds (not 300s timeout)
-5. Verify final run status is `completed` not `failed`

package/docs/fixes/bug-012-essential-env-stripped.md

@@ -1,89 +0,0 @@
-# Bug #12: Child-process crash "Failed to run npm root -g" — essential env vars stripped
-
-**Date:** 2026-05-19
-**Severity:** 🔴 HIGH
-**Type:** Bug (regression from Bug #10 fix)
-**Status:** ✅ Fixed — added essential env vars to allow-list
-
-## Summary
-
-Child Pi workers crash immediately after spawning with:
-```
-Error: Failed to run npm root -g: undefined
-    at DefaultPackageManager.runNpmCommandSync (...)
-    at DefaultPackageManager.getGlobalNpmRoot (...)
-```
-
-The child Pi starts but can't find `npm` because `PATH` was stripped from its environment.
-
-## Root Cause
-
-**Bug #10's fix introduced Bug #12.** The `sanitizeEnvSecrets()` function in allow-list mode ONLY preserves keys matching the allow-list. All other keys are stripped. The Bug #10 fix used an allow-list that only included model provider API keys, but stripped ALL other env vars including essential ones like `PATH`, `HOME`, `USER`, etc.
-
-```typescript
-// Bug #10 fix (BROKEN):
-const filteredEnv = sanitizeEnvSecrets(env, {
-  allowList: [
-    "MINIMAX_*", "OPENAI_*", "*_API_KEY", "*_TOKEN", "*_SECRET",
-    // Missing: PATH, HOME, USER, etc.
-  ],
-});
-// Result: child process gets ONLY model API keys, nothing else
-// → Child can't find npm/node/PATH → crashes immediately
-```
-
-**The `sanitizeEnvSecrets` allow-list mode works like this:**
-- With allow-list: preserve ONLY keys matching the list, strip everything else
-- Without allow-list: strip only keys matching SECRET_KEY_PATTERN, preserve everything else
-
-So the Bug #10 fix preserved `MINIMAX_API_KEY` but stripped `PATH`, making it impossible for the child Pi to find `npm`.
-
-## Why It Looked Like "spawn pi ENOENT" Before (Bug #11)
-
-In the previous session, background workers failed with `spawn pi ENOENT` immediately because:
-1. `getPiSpawnCommand()` returned bare `"pi"` without path resolution (Bug #11)
-2. The detached background runner had minimal PATH
-3. Fix: added `resolvePiCliScript()` for non-Windows (Bug #11 fix)
-
-After Bug #11 fix + Pi restart, workers spawn OK but crash with `npm root -g` error because:
-1. `getPiSpawnCommand()` now resolves full path
-2. Child process starts but has no `PATH` → can't find `npm`
-3. Pi's package manager calls `npm root -g` → fails with ENOENT
-
-## Fix Applied
-
-**File:** `src/runtime/child-pi.ts` — `buildChildPiSpawnOptions()`
-
-Added essential non-secret env vars to the allow-list:
-
-```typescript
-const filteredEnv = sanitizeEnvSecrets(env, {
-  allowList: [
-    // Model provider API keys (Bug #10)
-    "MINIMAX_*", "OPENAI_*", "ANTHROPIC_*", "GOOGLE_*",
-    "AZURE_*", "AWS_*", "ZEU_*", "ZERODEV_*",
-    "*_API_KEY", "*_TOKEN", "*_SECRET",
-    // Essential non-secret vars (Bug #12 fix)
-    "PATH", "HOME", "USER", "SHELL", "TERM", "LANG", "LC_*", "XDG_*",
-    "NVM_*", "NODE_*", "npm_*", "PI_*", "PI_CREW_*", "PI_TEAMS_*",
-  ],
-});
-```
-
-This preserves both:
-1. Model provider API keys (Bug #10 fix)
-2. Essential environment variables so child process can function (Bug #12 fix)
-
-## Why Not Use Deny-List Mode?
-
-In deny-list mode (no allow-list), `SECRET_KEY_PATTERN` strips any key matching secret patterns including `MINIMAX_API_KEY` (because `_API_KEY` matches the pattern). This was the original Bug #10 root cause.
-
-The allow-list approach is correct — we just need to include both model API keys AND essential env vars.
-
-## Verification
-
-After this fix, background workers should:
-1. Spawn successfully (Bug #11 verified)
-2. Find `npm` and `node` via PATH (Bug #12 verified)
-3. Authenticate with MiniMax via `MINIMAX_API_KEY` (Bug #10 verified)
-4. Produce output within 60 seconds (not 300s timeout)

package/docs/fixes/bug-013-background-runner-death.md

@@ -1,84 +0,0 @@
-# Bug #13 Fix: Background Runner Death — Full Fix
-
-**Date**: 2026-05-19  
-**Root Cause**: Background runner process dies ~59s after spawning — likely OOM killer or external SIGKILL  
-**Status**: ✅ Fixed (3-layer protection)
-
-## Problem
-
-Background runner process (PID 512666) died ~59 seconds after spawning. Workers spawned but produced zero output. The stale reconciler detected the dead PID and repaired the run.
-
-Key evidence:
-- `async.started` event written (runner started successfully)
-- Workers spawned (PIDs 512751, 512759)
-- No output from workers (Bug #10: MINIMAX_API_KEY stripped)
-- `pid_dead` found at 14:19:04 (~59s after start)
-- No `async.failed` event written (SIGKILL can't be caught)
-- dmesg OOM was for different PID (vitest PID 2910570)
-
-## Fixes Applied (3 Layers)
-
-### Layer 1: Heartbeat Mechanism (prevents false repairs)
-
-Files: `src/runtime/background-runner.ts`, `src/runtime/stale-reconciler.ts`
-
-The background runner writes a `heartbeat.json` file every 15 seconds with PID, timestamp, and memory usage. The stale reconciler checks the heartbeat before declaring a PID dead:
-- If heartbeat is < 5 minutes old → treat as alive (don't repair)
-- If heartbeat is > 5 minutes old AND PID is dead → repair
-
-This prevents the stale reconciler from false-positive repairs when the runner was killed by SIGKILL.
-
-### Layer 2: Memory Limit (prevents OOM kills)
-
-File: `src/runtime/async-runner.ts`
-
-Added `--max-old-space-size=512` to the background runner's Node.js arguments:
-```typescript
-const memoryLimit = "--max-old-space-size=512";
-// args: [memoryLimit, "--import", loaderPath, runnerPath, ...]
-```
-
-This limits V8 heap to 512MB (generous for the lightweight runner). Without this limit, Node.js defaults to ~1.5GB on 64-bit, which combined with jiti compilation and child processes can exhaust system memory and trigger the OOM killer.
-
-### Layer 3: Signal Handlers + Memory Monitoring (diagnostic)
-
-File: `src/runtime/background-runner.ts`
-
-1. **SIGTERM/SIGINT handlers**: Log `async.failed` event before exiting. This distinguishes:
-   - OOM/SIGKILL: no event written (can't catch SIGKILL)
-   - SIGTERM/SIGINT: event written with signal name
-   - Normal exit: `async.completed` event
-
-2. **Memory monitoring in heartbeat**: Each heartbeat writes `heapUsedMb` and `rssMb`:
-   ```json
-   { "pid": 12345, "at": 1718794685321, "runId": "...", "memory": { "heapUsedMb": 87, "rssMb": 145 } }
-   ```
-   This allows post-mortem analysis — if `rssMb` was climbing before death, OOM is confirmed.
-
-## Files Modified
-
-| File | Change |
-|---|---|
-| `src/runtime/async-runner.ts` | Added `--max-old-space-size=512` to background runner args |
-| `src/runtime/background-runner.ts` | Heartbeat with memory stats; SIGTERM/SIGINT handlers |
-| `src/runtime/stale-reconciler.ts` | Heartbeat-aware PID liveness check (from earlier fix) |
-
-## Verification
-
-```bash
-cd /home/bom/source/my_pi/pi-crew
-npx tsc --noEmit  # No errors
-```
-
-## Diagnosis Flow (Post-Fix)
-
-When a background runner dies:
-
-1. Check events for `async.failed` with `signal: "SIGTERM"/"SIGINT"` → signal kill (Layer 3)
-2. Check `heartbeat.json` for `memory.rssMb` → if climbing → OOM (Layer 2 prevents)
-3. Check `heartbeat.json` for `at` timestamp → if fresh → false-positive repair prevented (Layer 1)
-4. No `async.failed` event AND stale heartbeat → SIGKILL/OOM (uncatchable)
-
-## Remaining Risk
-
-If the Linux OOM killer sends SIGKILL (uncatchable), the background runner will die without writing any event. The heartbeat mechanism prevents false repairs for 5 minutes, giving time for investigation. The memory limit (`--max-old-space-size=512`) significantly reduces the chance of triggering the OOM killer by keeping the runner's memory footprint small.

package/docs/fixes/bug-014-infinite-retry-loop-needs-attention.md

@@ -1,82 +0,0 @@
-# Bug #14 Fix: Infinite Retry Loop — needs_attention Task Re-scheduled
-
-**Date**: 2026-05-20  
-**Root Cause**: `needs_attention` task status had `queue: "blocked"` instead of `queue: "done"` in task graph  
-**Status**: ✅ Fixed
-
-## Problem
-
-When a task ended with `needs_attention` status (worker completed without calling `submit_result`), the team-runner kept re-scheduling the task in an infinite loop.
-
-### Symptoms
-- 942 `task.started` events for `01_explore`
-- 1882 `task.needs_attention` events
-- Task `01_explore` had `status: "running"` but `finishedAt: "2026-05-20T01:57:46.097Z"` (finished but status was "running")
-- `queue: "blocked"` in task graph for `needs_attention` tasks
-- No `task.completed` events
-
-### Run Data (from `team_20260520015649_42079220e6ef2860`)
-```
-Task 01_explore:
-  status: running
-  stepId: explore
-  graph.queue: blocked
-  dependsOn: []
-  finishedAt: 2026-05-20T01:57:46.114Z
-```
-
-## Root Cause
-
-In `src/runtime/task-graph-scheduler.ts`, the `withQueue()` function assigned `queue: "done"` only for `"completed"` and `"skipped"` statuses, but NOT for `"needs_attention"`:
-
-```typescript
-// BEFORE (bug):
-if (task.status === "completed" || task.status === "skipped") {
-    return { ...task, graph: { ...task.graph, queue: "done" } };
-}
-return { ...task, graph: { ...task.graph, queue: "blocked" } };
-```
-
-This meant `needs_attention` tasks got `queue: "blocked"`, making them appear in `taskGraphSnapshot(tasks).ready` as "ready" even though they were terminal.
-
-The team-runner's main loop:
-1. Computed `effectiveReady` from `taskGraphSnapshot(tasks).ready`
-2. `effectiveReady` included tasks with `queue: "blocked"` (because they had `needs_attention` status)
-3. These tasks were added to `readyBatch` and re-spawned
-
-## Fix
-
-Added `needs_attention` to the terminal status check in `withQueue()`:
-
-```typescript
-// AFTER (fix):
-if (task.status === "completed" || task.status === "skipped" || task.status === "needs_attention") {
-    return { ...task, graph: { ...task.graph, queue: "done" } };
-}
-```
-
-## File Changed
-
-| File | Change |
-|---|---|
-| `src/runtime/task-graph-scheduler.ts` | Added `needs_attention` to terminal queue assignment |
-
-## Verification
-
-```bash
-cd /home/bom/source/my_pi/pi-crew
-npx tsc --noEmit  # No errors
-```
-
-After fix, `needs_attention` tasks have `queue: "done"` in task graph, so they won't be re-scheduled.
-
-## Related Behavior
-
-- `needs_attention` already correctly blocks phase advancement in `team-runner.ts` (`terminalStatuses` includes `needs_attention`)
-- `needs_attention` correctly does NOT satisfy DAG dependencies (only `completed` does)
-- Phase advancement checks `terminalStatuses.has(task.status)` which includes `needs_attention`
-
-This ensures:
-1. `needs_attention` tasks are treated as terminal (don't block phases)
-2. `needs_attention` tasks have `queue: "done"` (don't get re-scheduled)
-3. Downstream tasks with `dependsOn` on a `needs_attention` task correctly stay blocked

package/docs/fixes/bug-015-background-runner-sigterm.md

@@ -1,65 +0,0 @@
-# Bug #15: Background Runner Receives SIGTERM ~3s After Spawn
-
-## Status: ✅ Fixed — Disabled async by default
-
-## Fix Applied: Disable Async by Default
-**File:** `src/extension/team-tool/run.ts`
-```typescript
-// Background runners are disabled by default because Pi infrastructure sends SIGTERM to
-// async children ~3s after spawn (Bug #15). Set to true to enable background runs.
-// const runAsync = params.async ?? loadedConfig.config.asyncByDefault ?? false;
-const runAsync = false; // TEMP: always false until SIGTERM issue is fixed
-```
-
-**Verification (2026-05-20):** Full 4-task team run `team_20260520091127_8bcd4ca6f9fa84f5` completed successfully in ~4 minutes using foreground blocking mode. 01_explore, 02_plan, 03_execute, 04_verify all completed with `status=completed`. No SIGTERM because no background runner was spawned.
-
-**Root Cause:** Pi CLI infrastructure sends SIGTERM to async background runners ~3s after spawn. `setsid:true` does not work in Node.js 22.22.0. No fix available from pi-crew side — requires Pi infrastructure change or Node.js fix.
-
-## Symptom (Historical)
-All async background runners die with SIGTERM approximately 3 seconds after spawning, regardless of workload or configuration. The SIGTERM comes from the Pi CLI process.
-
-## Timeline (from events.jsonl)
-```
-06:56:31.549  async.spawned   (background runner created, pid noted)
-06:56:32.466  async.started   (background runner main() begins executing)
-06:56:32.691  worker.spawned 01_explore (child Pi worker spawned)
-06:56:32.706  worker.spawned 02_plan (child Pi worker spawned)
-06:56:35.713  async.failed   SIGTERM received from pi process (ppid=1509889)
-                → background runner exits with code 143
-```
-
-## Root Cause Analysis
-
-### Pi Infrastructure Cleanup — CONFIRMED
-Pi CLI infrastructure sends SIGTERM to direct children when the tool call that spawned them returns. This is normal cleanup behavior for detached processes.
-
-**Evidence:**
-- SIGTERM sender PID = Pi process (1509889) — exactly where `crew_agent` tool runs
-- SIGTERM arrives at a consistent ~3s interval after `async.started`
-- No OOM, no dmesg entries, no pi-crew internal kill(SIGTERM) calls exist
-- Pi source has SIGTERM handling for subprocess cleanup
-
-### setsid Bug in Node.js 22.22.0 — Confirmed
-`setsid: true` does not actually create a new session in Node.js 22.22.0. The background runner remains in the Pi process's process group (PGID=1509889). This was confirmed by direct testing showing that `detached: true` + `setsid: true` does NOT result in the child having its own PGID.
-
-### Key Discovery: Orphaned Workers Survive
-After SIGTERM kills the background runner, orphaned workers continue running:
-```
-07:03:39.148  SIGTERM → background runner DIES but orphaned workers CONTINUE
-07:08:39      stale-reconciler detects dead heartbeat → cancel orphaned tasks
-```
-
-This proves:
-1. Child workers are properly detached (PPID=1 or independent PG)
-2. Pi only sends SIGTERM to **direct children** (background runner), not grandchildren
-3. The issue is that background-runner is a direct child and gets killed
-
-## Files Modified
-```
-src/extension/team-tool/run.ts — runAsync = false (disabled async by default)
-```
-
-## Future Considerations
-1. **Re-enable async** when Pi infrastructure is fixed or Node.js setsid works correctly
-2. **Shell wrapper approach** — spawn via `/bin/sh -c 'exec setsid node ...'` as intermediate process
-3. **Report to Pi maintainers** — the Pi infrastructure's cleanup behavior may need adjustment for long-running async workers

package/docs/fixes/bug-017-background-runner-session-shutdown.md

@@ -1,66 +0,0 @@
-# Bug #17: Background Runner Dies at ~35s — Root Cause
-
-## Summary
-
-Background runners (async mode) were dying ~35 seconds after spawn — before workers could complete. This was NOT caused by Pi's `killTrackedDetachedChildren` mechanism or any external kill signal.
-
-## Root Cause
-
-**`session_shutdown` fires frequently during normal operation**, not just on exit.
-
-Pi's agent-session fires `session_shutdown` for:
-- `session_fork` — when a subagent/fork session starts
-- `session_resume` — when resuming a previous session
-- `session_new` — when creating a new session
-
-Every time `session_shutdown` fires, pi-crew's `cleanupRuntime()` was called:
-
-```typescript
-// register.ts - OLD CODE (BUG #17)
-pi.on("session_shutdown", () => cleanupRuntime());
-
-// Inside cleanupRuntime():
-for (const manifest of manifestCache.list(50)) {
-    if (manifest.async?.pid !== undefined && checkProcessLiveness(manifest.async.pid).alive) {
-        killProcessPid(manifest.async.pid);  // ← THIS KILLED THE RUNNER
-    }
-}
-```
-
-Since `session_shutdown` fires every 30-35 seconds during normal operation (whenever the agent session forks/resumes), this kill loop terminated the background runner almost immediately.
-
-## Why setsid+detached didn't fully help
-
-`detached: true` + `setsid: true` gives the runner its own session and process group, making it immune to terminal signals and process group kills. However, `killProcessPid(pid)` sends `SIGKILL` directly to the specific PID — and since the kill loop was actively reading the manifest cache, it knew the exact runner PID to kill.
-
-## The Fix
-
-Comment out the async runner kill loop in `cleanupRuntime()`:
-
-```typescript
-// register.ts - FIXED CODE
-// NOTE: Background runners are designed to outlive the Pi session.
-// Do NOT kill them on session_shutdown — they manage their own lifecycle.
-// (The kill loop was commented out here)
-```
-
-Async runners are designed to outlive the parent Pi session. They self-terminate when:
-- The run completes (async.completed event written)
-- The run fails (async.failed event written)  
-- The stale reconciler detects they're truly dead
-- They detect their parent (Pi) is gone via parent-guard
-
-## Files Changed
-
-- `src/extension/register.ts` — commented out killAsync loop in cleanupRuntime
-
-## Verification
-
-After the fix, a background runner (PID 55515) with systemd-run survived 160+ seconds and completed its lifecycle normally (timed out at 5 min due to unresponsive model — different issue).
-
-## Related Investigation
-
-- `systemd-run --user` was tested as an alternative spawn method — it works and provides additional isolation
-- `setsid: true` is confirmed working in Node.js 22.22.0 (creates own session/PGID)
-- The strace diagnostic was crucial: showed PID 20654 (Pi bash child) calling `kill(-20533, SIGTERM/SIGKILL)` on all old runner PIDs — this was Pi's cleanup hitting the strace wrapper's PID, not the runner itself
-- Final spawn uses `spawn()` with `detached: true`, `setsid: true as any`, stdio ignored, unref'd — clean and minimal

package/docs/fixes/bug-017-background-runner-sigkill-double-fork.md

@@ -1,28 +0,0 @@
-# Bug #17: Background Runner Killed by Pi's SIGKILL After Tool Execution
-
-## Status: ✅ Fixed — Direct spawn with SIGTERM ignore-all
-
-## Symptom
-Background runner process dies silently ~7 seconds after spawning. No error events, no catch blocks fire. The process simply disappears.
-
-## Root Cause
-Pi's infrastructure sends SIGTERM to child processes when tool execution completes. The background runner (spawned by the team tool) receives these SIGTERMs and, with the original signal handler that checked `isPiProcess()`, would exit on non-Pi SIGTERMs. Even after fixing the SIGTERM handler to ignore all, the runner was being killed during jiti compilation of `team-runner.ts` — likely due to the runner being in Pi's process group.
-
-## Fix Applied
-**Direct spawn with `setsid: true` and ignore-all SIGTERM handler:**
-
-1. **`async-runner.ts`**: Spawn runner directly (no double-fork detacher) with `detached: true, setsid: true` — runner gets its own session/process group
-2. **`background-runner.ts`**: SIGTERM handler ignores ALL SIGTERMs (removed `isPiProcess()` check), since with setsid the runner is its own session leader
-3. **`background-runner.ts`**: Removed `process.exit(1)` from unhandled rejection guard — now just sets exitCode and continues
-4. **`child-pi.ts`**: Added `setsid: true` to child Pi spawn options — workers get their own PGIDs, preventing cascade kills
-
-## What Didn't Work
-- **Double-fork (detacher)**: Created an intermediate "detacher" process that spawned the runner then exited. The runner died at t+7s even with detacher alive. Root cause unclear — possibly fd inheritance issue or jiti compilation interaction.
-- **`setsid` only**: With setsid but without ignore-all SIGTERM handler, runner received SIGTERMs and exited.
-- **Ignore SIGTERM from Pi only**: With `isPiProcess()` check, SIGTERMs from systemd (after double-fork reparenting) weren't ignored.
-
-## Verification
-- Direct spawn runner alive after 2+ minutes ✅
-- Workers spawned and running ✅
-- SIGTERMs properly ignored ✅
-- `sleep 60` via double-fork survived (rules out Pi directly killing random PIDs) ✅