pi-crew 0.2.20 → 0.2.22

package/docs/fixes/bug-006-foreground-cancel-concurrent.md

@@ -0,0 +1,78 @@
+# Bug #6: Foreground fast-fix team cancelled after explore — ROOT CAUSE CONFIRMED
+
+| Field | Value |
+|---|---|
+| **Severity** | 🔴 HIGH |
+| **Status** | Root cause confirmed, 100% reproducible |
+| **Affected** | Foreground team runs when concurrent tool calls happen |
+| **Symptom** | Explore completes with zero output, run immediately cancelled |
+
+## Reproduce (100%)
+
+1. Start a foreground fast-fix team run
+2. While it's running, call ANY other team action (get, plan, settings, etc.)
+3. Result: Explore "completes" with `outputLength=0, jsonEvents=0, toolUses=0` → run cancelled
+
+## Without concurrent calls
+
+Same fast-fix run with NO other tool calls → **completes successfully** with `jsonEvents=120`, full output.
+
+## Root Cause
+
+When multiple tool calls happen concurrently with a foreground live-session run:
+
+1. Foreground run starts, spawns live-session agent for explore
+2. User calls `team get`, `team plan`, `team settings`, etc.
+3. Pi processes these tool calls in the same session
+4. Pi may trigger **auto-compaction** (context grows from tool outputs)
+5. Compaction or context operation **interrupts the live-session agent**
+6. Live-session agent's prompt returns with **zero output** (`outputLength:0`)
+7. team-runner marks task as "completed" (exit code 0, but no output)
+8. Next phase transition fails — run gets `"caller_cancelled"` abort
+
+### Evidence chain
+
+```
+Successful run (no concurrent calls):
+  live-session.prompt_done: elapsedMs=30888, jsonEvents=30, outputLength=20894
+  → All 3 tasks complete
+
+Failed run (with concurrent tool calls):
+  live-session.prompt_done: elapsedMs=32304, jsonEvents=0, outputLength=0
+  → Explore "completes" with nothing, run immediately cancelled
+```
+
+The `"outputLength":0` is the smoking gun — the live-session agent's prompt completed
+without producing any output because Pi was busy processing other tool calls.
+
+### Key difference in status.json
+
+| Field | Successful | Failed |
+|---|---|---|
+| jsonEvents | 120 | 0 |
+| toolUses | many | 0 |
+| output | full context | empty |
+
+## Fix suggestions
+
+### Option A: Queue concurrent tool calls during foreground run
+When a foreground run is active, queue other team tool calls instead of processing immediately.
+
+### Option B: Protect live-session prompt from interruption
+In `live-session-runtime.ts`, add a guard that prevents context operations during `session.prompt()`.
+
+### Option C: Detect zero-output completion as failure
+In `team-runner.ts`, when a live-session task completes with `outputLength=0` and `toolUses=0`, treat it as a failure and retry instead of proceeding.
+
+### Option D: Warn user
+When foreground run is active and user calls another team action, return a warning:
+"Foreground run is active. Concurrent operations may interrupt the running agent."
+
+## Files
+
+```
+pi-crew/src/extension/register.ts          — startForegroundRun(), concurrent tool handling
+pi-crew/src/runtime/live-session-runtime.ts — promptWithTimeout(), output capture
+pi-crew/src/runtime/team-runner.ts          — task completion handling
+pi-crew/src/extension/registration/compaction-guard.ts — auto-compaction during runs
+```

package/docs/fixes/bug-007-async-notifier-stale-ctx.md

@@ -0,0 +1,112 @@
+# Bug #7: Async notifier "stale ctx detected; stopping notifier" — không restart
+
+| Field | Value |
+|---|---|
+| **Severity** | 🔴 HIGH |
+| **Status** | Root cause confirmed, fix pending |
+| **Affected** | Tất cả pi-crew users sau khi Pi session restarts/compacts |
+| **Symptom** | Sau restart/compact, notifier dừng hoàn toàn — không còn nhận notifications cho run completions |
+
+## Mô tả
+
+Sau khi Pi restart (hoặc /clear, /compact, session switch), xuất hiện error:
+```
+[pi-crew] async notifier stale ctx detected; stopping notifier.
+```
+
+Sau đó, pi-crew **không còn deliver notifications** cho run completions. Background runs hoàn thành nhưng user không được báo.
+
+## Root cause
+
+### Flow bình thường (mong đợi):
+
+```
+Pi session_start event
+  → sessionGeneration++
+  → currentCtx = newCtx
+  → cleanupRuntime() (stop old notifier)
+  → startAsyncRunNotifier(newCtx, ...)
+  → New notifier hoạt động với newCtx ✅
+```
+
+### Flow bị lỗi:
+
+```
+1. Old notifier interval tick fires
+2. isCurrent(generation) check → true (generation chưa increment)
+3. ctx.ui.notify() called
+4. Pi đã invalidate old ctx → throw Error("This extension ctx is stale...")
+5. Catch block: message.includes("stale") → true
+6. stopAsyncRunNotifier(state) → clearInterval(interval)
+7. console.error("stale ctx detected; stopping notifier.")
+8. ❌ Notifier stopped permanently
+```
+
+Vấn đề: **session_start handler** CHƯA kịp chạy để start new notifier.
+
+### Tại sao session_start chưa chạy?
+
+Khi Pi invalidate ctx, old notifier interval **vẫn đang chạy** (clearInterval chưa được gọi). Interval tick xảy ra **trước khi** `cleanupRuntime()` hoặc `session_start` handler chạy. Đây là **race condition** giữa:
+- Old notifier's setInterval tick
+- Pi's session shutdown/start event sequence
+
+### Code location
+
+**`/home/bom/source/my_pi/pi-crew/src/extension/async-notifier.ts`**, line 103-112:
+```typescript
+} catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes("stale") || message.includes("session replacement") || message.includes("old ctx")) {
+        console.error(`[pi-crew] async notifier stale ctx detected; stopping notifier.`);
+        try { stopAsyncRunNotifier(state); } catch { /* ignore */ }
+        return;  // ❌ Stops the interval, never restarts
+    }
+}
+```
+
+### Why it matters
+
+- User restarts Pi → notifier dies → background runs complete silently
+- User phải manually check `team status` để biết runs hoàn thành
+- Ảnh hưởng UX nghiêm trọng: pi-crew "câm" sau restart
+
+## Fix
+
+### Option A: Silent swallow stale errors (recommended)
+
+Thay vì stop notifier, chỉ **skip notification** này và chờ session_start restart notifier với new ctx:
+
+```typescript
+} catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes("stale") || message.includes("session replacement") || message.includes("old ctx")) {
+        // Don't stop — session_start will create a new notifier with the new ctx.
+        // This old notifier's isCurrent guard will return false on next tick,
+        // making it effectively dormant until cleaned up.
+        return;
+    }
+    console.error(`[pi-crew] async notifier error: ${message}`);
+}
+```
+
+Rationale: `isCurrent` guard sẽ return false sau khi `sessionGeneration++` → old notifier interval vẫn chạy nhưng không làm gì (silent). New notifier từ `session_start` sẽ hoạt động bình thường.
+
+### Option B: Add explicit restart mechanism
+
+Add `restartAsyncRunNotifier()` function và gọi từ `session_start` handler. Nhưng Option A đơn giản hơn và đủ.
+
+## Key files
+
+```
+pi-crew/src/extension/async-notifier.ts  — startAsyncRunNotifier(), stopAsyncRunNotifier()
+pi-crew/src/extension/register.ts         — session_start handler, isCurrent guard
+```
+
+## Pi SDK reference
+
+Pi's `ExtensionRunner.invalidate()` sets `staleMessage` → `assertActive()` throws:
+```
+"This extension ctx is stale after session replacement or reload. 
+Do not use a captured pi or command ctx after ctx.newSession(), 
+ctx.fork(), ctx.switchSession(), or ctx.reload()."
+```

package/docs/fixes/bug-008-child-process-silent-timeout.md

@@ -0,0 +1,100 @@
+# Bug #8: Background child-process 300s timeout — Silent hang
+
+| Field | Value |
+|---|---|
+| **Severity** | 🟠 MEDIUM |
+| **Status** | Root cause identified, fix partially applied |
+| **Affected** | All async/background team runs (child-process runtime) |
+
+## Symptom
+
+```
+worker.spawned: pid=177677 ✅ (real process spawned)
+worker.response_timeout: No output for 300000ms
+crew.task.heartbeat_dead: elapsedMs=300774
+worker.exit: exitCode=null (killed)
+Result: jsonEvents=0, toolUses=0, output.log=DOES NOT EXIST, stderr=EMPTY
+```
+
+## Root Cause
+
+Child Pi process:
+1. Spawned successfully (real OS process with valid PID)
+2. Ran completely SILENT — zero stdout, zero stderr for 5 minutes
+3. Timed out after 300s with no output
+4. Killed by SIGTERM
+
+**The process was alive but produced no output at all.** This is NOT:
+- ❌ Crash (would have stderr)
+- ❌ 429 rate limit (Round 1 fix handles this)
+- ❌ Model error (would have error output)
+
+**Possible causes:**
+1. MiniMax provider silently hangs in child-process context
+2. Child Pi startup error but stderr channel not capturing it
+3. Model called but produces empty response → child waits forever
+4. IPC communication failure between parent and child
+
+## Evidence
+
+```
+Event timeline (team_20260519090953_e6ddc7b21b0048fa):
+09:09:54.511Z  worker.spawned pid=177677
+09:13:38.075Z  task.attention: 223s idle (no observed activity)
+09:14:54.516Z  worker.response_timeout: No output for 300000ms
+              → stderr: NOT IN EVENT (timeoutStderr was empty/undefined)
+09:14:57.535Z  worker.exit exitCode=null (killed)
+```
+
+```
+Agent files: only status.json exists
+output.log: DOES NOT EXIST
+stderr.log: DOES NOT EXIST
+result: "(no output)" (11 bytes)
+```
+
+## Partial Fix Applied
+
+`timeoutStderr` is now captured and included in `response_timeout` events. However, in this case the stderr was empty — meaning the child process ran but produced nothing to stderr.
+
+## Files Involved
+
+```
+pi-crew/src/runtime/child-pi.ts    — spawn, timeout, stderr capture
+pi-crew/src/runtime/background-runner.ts — async run management
+pi-crew/src/runtime/task-runner.ts      — worker lifecycle
+```
+
+## Fix Suggestions
+
+### Fix A: Add stderr capture at spawn moment
+Capture any startup errors from child Pi's stderr pipe immediately after spawn.
+
+```typescript
+// In child-pi.ts, after child spawn:
+child.stderr?.on("data", (chunk) => {
+  stderr += chunk.toString();
+  // Also log to parent for debugging
+  console.error("[pi-crew:child-stderr]", chunk.toString());
+});
+```
+
+### Fix B: Reduce timeout for background workers
+For background/async runs, use shorter timeout (60s) since output should stream quickly.
+
+### Fix C: Detect silent spawn (no output within 30s = warning)
+If a worker spawns but produces zero output within 30s, emit a warning event.
+
+### Fix D: Add process startup verification
+Send a ping to the child Pi and expect a response within 10s. If no response, consider it a spawn failure.
+
+## Comparison: Live-session vs Child-process
+
+| Aspect | Live-session | Child-process |
+|---|---|---|
+| Startup | Immediate | Delayed (~1s) |
+| Model output | Streaming JSON | Silent hang |
+| Error visibility | Direct | Hidden (no stderr) |
+| Timeout | Works correctly | Silent 300s hang |
+
+This suggests the issue is specific to **child-process runtime with MiniMax model** — the model provider silently fails in the background subprocess context.

package/docs/fixes/bug-009-executor-yield-limit-needs-attention.md

@@ -0,0 +1,75 @@
+# Bug #9 Fix: Executor Yield Limit — New `needs_attention` Status
+
+**Date**: 2026-05-19  
+**Root Cause**: Executor agent completes work but doesn't call `submit_result` → yield enforcement sends 3 reminders → task marked `completed` with `exitCode: 0` → artifact missing/incomplete  
+**Status**: ✅ Fixed
+
+## Problem
+
+When an executor agent (or any live-session worker) completes its task but doesn't call the `submit_result` tool:
+
+1. The live-session runtime's yield enforcement loop runs (max 3 reminders × 500ms = 1.5s window)
+2. After 3 reminders with no `submit_result`, a `task.attention` event fires with `reason: "no_yield"`
+3. But the task is still marked `status: "completed"` with `exitCode: 0`
+4. The `resultArtifact` contains `liveResult.stdout || "(no output)"` — which may be empty
+5. The executor's actual file write was completed but never captured in the result artifact
+
+This means tasks that didn't properly submit their result appear "completed" in the UI, misleading users into thinking the work was done.
+
+## Fix
+
+Added a new `needs_attention` task status that is set when a worker completes without calling `submit_result`.
+
+### New Status: `needs_attention`
+
+- **Type**: Terminal status (like `completed`, `failed`, `cancelled`, `skipped`)
+- **Meaning**: Worker finished executing but didn't submit a result — work may or may not be complete
+- **Transitions**: `running → needs_attention`, `needs_attention → queued` (retry), `needs_attention → running` (re-run)
+- **Icon**: ⚠ (warning sign) in UI
+
+### Changes
+
+| File | Change |
+|---|---|
+| `src/state/contracts.ts` | Added `"needs_attention"` to `TEAM_TASK_STATUSES`, `TEAM_TERMINAL_TASK_STATUSES`, `TEAM_TASK_STATUS_TRANSITIONS`, `TEAM_EVENT_TYPES` |
+| `src/runtime/task-runner.ts` | Added `noYield` flag; when no yield detected → set `status: "needs_attention"` instead of `"completed"`, emit `"task.needs_attention"` event |
+| `src/runtime/crew-agent-runtime.ts` | Added `"needs_attention"` to `CrewAgentStatus` type; updated `taskStatusToAgentStatus()` |
+| `src/runtime/team-runner.ts` | Added `"needs_attention"` to `terminalStatuses` set for workflow phase advancement |
+| `src/runtime/stale-reconciler.ts` | Added `"needs_attention"` to `allTerminal` check |
+| `src/runtime/crash-recovery.ts` | Added `"needs_attention"` to `isTerminalTask()` |
+| `src/runtime/phase-progress.ts` | Added `"needs_attention"` to `TERMINAL_STATUSES` |
+| `src/runtime/task-display.ts` | Added ⚠ icon for `"needs_attention"` status |
+| `src/ui/snapshot-types.ts` | Added `needsAttention?: number` to `RunUiProgress` |
+| `src/ui/run-snapshot-cache.ts` | Track `"needs_attention"` tasks in progress calculation |
+| `src/ui/crew-widget.ts` | Added `"needs_attention"` to `ERROR_STATUSES`; added ⚠ icon |
+| `src/ui/run-event-bus.ts` | Added `"task.needs_attention"` to `WORKER_LIFECYCLE_TYPES` |
+| `src/config/defaults.ts` | Added `"task.needs_attention"` to `terminalEventTypes` |
+| `src/state/event-reconstructor.ts` | Added `"task.needs_attention"` event → `"needs_attention"` status mapping |
+| `src/observability/event-to-metric.ts` | Added `"crew.task.needs_attention"` metric |
+
+## Status Transition Graph (Updated)
+
+```
+queued → running → completed ✓
+                 → failed ✗
+                 → cancelled ■
+                 → needs_attention ⚠ (NEW)
+
+needs_attention → queued (retry)
+                → running (re-run)
+```
+
+## Verification
+
+```bash
+cd /home/bom/source/my_pi/pi-crew
+npx tsc --noEmit  # No errors
+npx vitest run test/unit/stale-reconciler.test.ts  # All 8 tests pass
+```
+
+## User Impact
+
+- Tasks that previously showed as "completed" (✓) with missing artifacts now show as "⚠ needs_attention"
+- Users can clearly see which tasks need manual review
+- Downstream tasks (verifier, etc.) will see the task as "needs_attention" instead of "completed" and can adjust behavior accordingly
+- Workflow phase advancement correctly treats `needs_attention` as a terminal status

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

@@ -0,0 +1,109 @@
+# 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

@@ -0,0 +1,92 @@
+# 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

@@ -0,0 +1,89 @@
+# 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)