pi-crew 0.9.50 → 0.9.52

package/docs/fix-plan-disabletools-exit-null.md

@@ -1,219 +0,0 @@
-# Fix Plan — HB-003a: `ctx.agent({disableTools:true})` returns `exit null`
-
-> **Status:** PROPOSED (planning only — not yet implemented)
-> **Discovered:** 2026-06-24 real-world smoke testing (see `CHANGELOG.md` "Known issues")
-> **Severity:** medium (blocks the `disableTools:true` verdict-judge pattern; workaround exists)
-> **Owner:** TBD
-> **Related:** HB-004 (smoke-test harness), commits `c55d3e2` + `ab481e6` (sibling bugs already fixed)
-
-## 1. Problem statement (confirmed evidence)
-
-`ctx.agent({disableTools: true})` (and the equivalent direct `runChildPi({agent:{disableTools:true}})`)
-returns `exitCode: null` (process killed by signal) instead of `0`, **only when the
-calling process exits promptly after the promise resolves.** If the caller stays alive
-~10s after `runChildPi` resolves, `exitCode` comes back `0` correctly.
-
-### Repro matrix (all verified 2026-06-24)
-
-| Scenario | disableTools | Caller keep-alive | Result |
-|---|---|---|---|
-| `pi --no-tools ...` standalone | yes | n/a | ✅ exit 0, correct answer |
-| `runChildPi` + keep-alive 10s | yes | yes | ✅ exitCode=0, finalDrain=true |
-| `runChildPi` + exit immediately | yes | no | ❌ exitCode=null |
-| `runChildPi` (has tools) | no | either | ✅ exitCode=0 |
-| DWF `ctx.agent({disableTools:true})` | yes | (workflow) | ❌ exit null |
-
-### What the lifecycle events show (failing case)
-
-```
-spawned → exit(code=null) → close(code=null)
-```
-
-**Notably ABSENT:** `final_drain`, `hard_kill`, `response_timeout` lifecycle events.
-So the signal did NOT come from `child-pi.ts`'s own timers. `stdout` *does* contain
-the model's answer — pi produced output, then died via signal.
-
-## 2. Root-cause hypotheses (to confirm in Phase 0)
-
-### ✅ PHASE 0 COMPLETE — root cause confirmed (2026-06-24)
-
-**Root cause: erroneous steer-backpressure kill at `child-pi.ts:716-726`** (NOT the
-final-drain race hypothesised in H1).
-
-When `maxTurns` is reached on a `turn_end` event, the code injects a "wrap up"
-steer by writing to `child.stdin`. Node's `writable.write()` returns `false` when
-the internal buffer is above the high-water mark (normal backpressure) OR when
-the stream is draining. The current code treats **any** `false` return as a
-fatal injection failure and calls `killProcessTree(child.pid, child)` → SIGTERM.
-
-This fires deterministically for the `ctx.agent({maxTurns:1, disableTools:true})`
-pattern (and the smoke-test repro): with `--no-tools`, pi finishes in exactly one
-real turn, so `turn_end` arrives the instant the answer is ready; pi has nothing
-more to read from stdin, the write returns `false`, and the worker is killed mid-
-answer. The answer IS in stdout, but exit comes back `null` (SIGTERM).
-
-**Repro confirmed via Phase-0 instrumentation** (`PI_TEAMS_DEBUG=1`):
-```
-[pi-crew:child-pi.kill-process-tree-invoked] pid=783270 called from:
-    at killProcessTree (src/runtime/child-pi.ts:102:23)
-    at Object.onJsonEvent (src/runtime/child-pi.ts:731:11)   ← steer-backpressure kill
-```
-maxTurns=1 × 5 runs: 3/5 exit=null (flaky, depends on OS buffer state).
-maxTurns=5 × 5 runs: 5/5 exit=0 (soft limit not hit on turn 1).
-
-**The `disableTools` correlation was a red herring** — the real trigger is
-`maxTurns:1` (the smoke workflow happened to combine both). Any single-turn
-agent call hitting `maxTurns` on its first `turn_end` can reproduce this.
-
-### Original hypotheses (kept for the audit trail)
-
-The killer was initially unidentified because the `signal` arg of the `exit`
-event was discarded. The leading hypotheses, in priority order:
-
-- **H1 (DISPROVEN): final-drain timer race.** Instrumentation showed
-  `forcedFinalDrain=false` on failing runs — the final-drain timer was armed but
-  never fired. The SIGTERM came from elsewhere.
-- **H2 (DISPROVEN): pi self-terminates via signal.** stdout contains the answer;
-  the kill-process-tree caller stack points squarely at the steer-injection path.
-- **H3 (already ruled out): external signal / parent-guard.** `startParentGuard`
-  is never invoked in `src/`; abort would set `cancelled:true` (it stayed false).
-
-## 3. Phased plan
-
-### Phase 0 — Diagnostic (READ-ONLY, no behavior change)  [~0.5 day]
-
-Goal: identify the exact signal and the code path that sent it. **No fix yet.**
-
-1. **Capture the signal.** In `child.on("exit", (code, signal) => ...)`, add `signal`
-   to the `exitStatus` record and to the `exit` lifecycle event payload. Also capture
-   `forcedFinalDrain`, `hardKilled`, `finalDrainTimer` truthiness, and a timestamp
-   relative to spawn. This is the single highest-value change — it turns the bug from
-   "exit null, cause unknown" into "exit null via SIGTERM at T+Xms while timer armed".
-2. **Add a focused repro workflow** `.crew/workflows/debug/dwf-disabletools.dwf.ts`
-   already exists — extend it to log `exitStatus` (signal, forcedFinalDrain, timing).
-   Re-run until the captured data distinguishes H1 vs H2.
-3. **Confirm H1 with a log-only check:** temporarily log the wall-clock time of
-   `forcedFinalDrain = true` vs the `exit` event. If `exit` precedes the assignment,
-   H1 is confirmed.
-4. **Exit Phase 0** with a written finding (append to this file's §2): which signal,
-   which path, deterministic repro steps.
-
-**Deliverable:** amended §2 with the confirmed root cause; no commit to `main`
-beyond the read-only instrumentation (kept behind a debug flag or reverted).
-
-### Phase 1 — Fix  [~0.5 day]
-
-**Confirmed fix: stop killing the worker on a normal backpressure `write() === false`.**
-
-At `child-pi.ts:723-726`:
-```ts
-const writeSucceeded = child.stdin.write(steerPayload);
-if (!writeSucceeded) {
-  logInternalError("child-pi.steer-backpressure", ...);
-  steerInjectionFailed = true;
-  killProcessTree(child.pid, child);   // ← BUG: backpressure is not fatal
-}
-```
-
-`Writable.write()` returning `false` is **normal backpressure** — Node buffers the
-write and emits `'drain'` later. It does NOT mean the write failed. Killing the
-worker on it destroys a perfectly good answer (stdout already has it). The
-original intent was to handle a genuinely unwritable stdin (the `else` branch at
-line 727 logs `steer-not-writable` and ALSO kills — that one is more defensible
-but still too aggressive).
-
-**Proposed change:** keep the steer-injection best-effort. On `write() === false`,
-simply wait for `'drain'` (or do nothing — the soft-limit steer is advisory). If
-the worker ignores it and runs past `maxTurns + graceTurns`, the existing hard-
-abort at line 735 (`turnCount >= maxTurns + graceTurns`) already terminates it.
-
-```ts
-const writeSucceeded = child.stdin.write(steerPayload);
-if (!writeSucceeded) {
-  // Backpressure: Node buffered the write and will flush on 'drain'. This is
-  // NOT a failure — do NOT kill the worker. The steer is advisory; if the worker
-  // keeps running, the hard-abort at maxTurns + graceTurns (line ~735) handles it.
-  logInternalError("child-pi.steer-backpressure", new Error("stdin write returned false (normal backpressure); steer buffered, worker NOT killed"), `pid=${child.pid}`);
-}
-```
-
-Keep the `else` branch (stdin not writable at all) as-is for now, but downgrade
-it too in a follow-up — a closed stdin after the worker is done is also not fatal.
-
-**Verification gate:** the repro matrix in §1 must go all-green with `exitCode=0`
-and the answer present in stdout, run **10× consecutively** (the bug is flaky at
-~60%, so a single pass is insufficient). No regression in the existing
-`test/unit/child-pi-*.test.ts` suites (5 files, ~85 tests). Add a unit test that
-fakes a `child.stdin` whose `write()` returns `false` and asserts the worker is
-NOT killed and the buffered write eventually flushes.
-
-### Phase 2 — Regression prevention (HB-004)  [~1 day]
-
-Land the smoke-test harness proposed in `HB-004` so this class of bug is caught by
-CI, not only by live runs. Gate behind `PI_CREW_SMOKE=1` (token cost). Minimum:
-one workflow per feature family that actually shells out to real `pi`
-(`agent` plain, `agent`+schema, `agent`+disableTools, `pipeline`, `phase`/`log`).
-Add a CI job (manual-dispatch workflow) that runs the smoke suite on
-ubuntu/windows/macos × Node 22.
-
-## 4. Files touched (estimate)
-
-| Phase | File | Change |
-|---|---|---|
-| 0 | `src/runtime/child-pi.ts` | capture `signal` + timing in `exit`/`exitStatus` (log-only) |
-| 0 | `.crew/workflows/debug/dwf-disabletools.dwf.ts` | extend logging |
-| 1 | `src/runtime/child-pi.ts` | Fix A: `finalDrainArmed` + close-handler override |
-| 1 | `test/unit/child-pi-*.test.ts` | add race-simulation unit test (fake child emitting exit before forcedFinalDrain) |
-| 2 | `test/smoke/*.dwf.ts` (new) | HB-004 harness |
-| 2 | `.github/workflows/smoke.yml` (new) | manual-dispatch smoke CI |
-| 1 | `CHANGELOG.md`, `docs/troubleshooting.md` | move "Known issues" entry to "Fixed"; remove workaround note |
-
-## 5. Test plan
-
-- **Phase 0:** before/after instrumentation output showing the captured signal.
-- **Phase 1 unit:** a unit test that injects a fake child process whose `exit`
-  fires with `code=null` *before* the timer callback runs, asserting `finalExitCode === 0`
-  and that stdout content is preserved. This is the regression guard for the race.
-- **Phase 1 real-binary (manual):** re-run the §1 repro matrix; all rows ✅.
-- **Phase 1 regression:** `npm run test:unit` + `npm run test:integration` green;
-  typecheck + lazy-imports clean; TABS.
-- **Phase 2 CI:** smoke workflow green on all 3 OSes.
-
-## 6. Risk analysis
-
-| Risk | Likelihood | Mitigation |
-|---|---|---|
-| Fix A hides a *real* crash as a clean exit | medium | Telemetry log (`final-drain-zero-exit` style) on the override; only override when stdout is non-empty AND finalDrain timer was armed. Never override `responseTimeoutHit` or `abortRequested` paths. |
-| Race fix changes behavior for the common (has-tools) path | low | The `finalDrainArmed` condition only adds to the existing `forcedFinalDrain` branch; has-tools path already sets `forcedFinalDrain=true` normally. Unit test covers both. |
-| Cross-platform signal differences (Windows has no signals) | medium | Windows already uses `taskkill`/`undefined` signal semantics; Fix A keys off `exitCode === null` which is platform-consistent for signal/force-kill death. Verify on Windows CI. |
-| Phase 0 instrumentation itself changes timing | low | Keep it log-only; use monotonic `performance.now()`; revert before merge if it perturbs the race. |
-
-## 7. Out of scope
-
-- P2-2 VM sandbox / isolated-vm (separate, v1.5).
-- Refactoring the 919-line `child-pi.ts` (tempting but out of scope; surgical fix only).
-- Changing the final-drain timeout constants (`FINAL_DRAIN_MS=5s`, `HARD_KILL_MS=3s`).
-- The `runKind:'goal-loop'` foreground-dispatch note from smoke testing (separate item).
-
-## 8. Open questions for Phase 0 — ANSWERED (2026-06-24)
-
-All three resolved by the Phase-0 root-cause finding (steer-backpressure kill,
-NOT the final-drain race). Kept for the audit trail.
-
-1. **ANSWERED: not the final-drain timer.** The keep-alive case returned `exitCode=0`
-   by coincidence — the SIGTERM came from `killProcessTree` on the steer-injection
-   path (`child-pi.ts:731`), not the final-drain timer (`forcedFinalDrain=false`
-   on failing runs). Keep-alive merely changed the OS-buffer state so the stdin
-   `write()` happened to return `true`. Red herring.
-2. **ANSWERED: yes — the steer-injection path (`child-pi.ts:716-726`).** Stack
-   capture under `PI_TEAMS_DEBUG=1` proved `killProcessTree` was invoked from
-   `onJsonEvent` on a `turn_end` where `maxTurns` was reached and `stdin.write()`
-   returned `false` (normal backpressure, mis-treated as fatal).
-3. **ANSWERED: no extension self-termination.** The kill stack is entirely
-   inside `child-pi.ts`; the prompt-runtime extension is not on the stack.
-
----
-
-**Recommendation:** execute Phase 0 first (cheap, read-only, removes all guesswork),
-then pick Fix A or B based on the finding. Do NOT implement Phase 1 blind — the bug
-is in core runtime and a wrong fix could mask real crashes across every agent call.

package/docs/fixes/BATCH_A_H1_H2.md

@@ -1,86 +0,0 @@
-# Batch A: H1 + H2 Fixes
-
-Date: 2026-05-18
-
-## H1: Event-log silent loss when exceeding MAX_EVENTS_BYTES (50MB)
-
-### File
-`src/state/event-log.ts`
-
-### Problem
-When the event log file exceeds 50MB, events are dropped immediately (including terminal events) but `appendCounter` is not incremented → compaction is never triggered.
-
-### Fix applied
-In `appendEventInsideLock`:
-
-1. **Prioritize terminal events**: check `isTerminal = TERMINAL_EVENT_TYPES.has(fullEvent.type)` first
-2. **Non-terminal events exceeding the limit** → call `compactEventLog()` immediately (don't wait for counter % 100)
-3. **If still over the limit after compaction** → call `rotateEventLog()`
-4. **Only drop the event** when a non-terminal event is still over the limit after compaction + rotation
-5. **Terminal events are always persisted** regardless of size
-
-```ts
-const isTerminal = TERMINAL_EVENT_TYPES.has(fullEvent.type);
-let skippedDueToSize = false;
-if (!isTerminal && fs.existsSync(eventsPath)) {
-    const stat = fs.statSync(eventsPath);
-    if (stat.size > MAX_EVENTS_BYTES) {
-        try {
-            compactEventLog(eventsPath);
-        } catch (error) {
-            logInternalError("event-log.immediate-compact", error, `eventsPath=${eventsPath}`);
-        }
-        if (fs.existsSync(eventsPath)) {
-            const afterCompact = fs.statSync(eventsPath);
-            if (afterCompact.size > MAX_EVENTS_BYTES) {
-                rotateEventLog(eventsPath);
-            }
-        }
-    }
-}
-```
-
-### Verification
-```bash
-npm run typecheck  # PASSED
-```
-
----
-
-## H2: Mailbox appendFileSync has no cross-process lock
-
-### File
-`src/state/mailbox.ts`
-
-### Problem
-`appendMailboxMessage` uses `fs.appendFileSync`, which is not atomic on Windows.
-
-### Fix applied
-Import and wrap the append in `withEventLogLockSync`:
-
-```ts
-import { withEventLogLockSync } from "./event-log.ts";
-
-// In appendMailboxMessage:
-withEventLogLockSync(mailboxFile(manifest, complete.direction, complete.taskId), () => {
-    fs.appendFileSync(mailboxFile(manifest, complete.direction, complete.taskId), `${JSON.stringify(redactSecrets(complete))}\n`, "utf-8");
-});
-```
-
-### Verification
-```bash
-npm run typecheck  # PASSED
-```
-
----
-
-## Changed Files
-- `src/state/event-log.ts`
-- `src/state/mailbox.ts`
-
-## Verification Evidence
-```
-> npm run typecheck
-> tsc --noEmit && node --experimental-strip-types -e "await import('./index.ts'); console.log('strip-types import ok')"
-strip-types import ok
-```

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

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

@@ -1,112 +0,0 @@
-# Bug #7: Async notifier "stale ctx detected; stopping notifier" — does not restart
-
-| Field | Value |
-|---|---|
-| **Severity** | 🔴 HIGH |
-| **Status** | Root cause confirmed, fix pending |
-| **Affected** | All pi-crew users after a Pi session restarts/compacts |
-| **Symptom** | After restart/compact, the notifier stops completely — run-completion notifications are no longer received |
-
-## Description
-
-After Pi restarts (or /clear, /compact, session switch), the following error appears:
-```
-[pi-crew] async notifier stale ctx detected; stopping notifier.
-```
-
-After that, pi-crew **no longer delivers notifications** for run completions. Background runs finish, but the user is never notified.
-
-## Root cause
-
-### Normal flow (expected):
-
-```
-Pi session_start event
-  → sessionGeneration++
-  → currentCtx = newCtx
-  → cleanupRuntime() (stop old notifier)
-  → startAsyncRunNotifier(newCtx, ...)
-  → New notifier runs with newCtx ✅
-```
-
-### Buggy flow:
-
-```
-1. Old notifier interval tick fires
-2. isCurrent(generation) check → true (generation hasn't incremented yet)
-3. ctx.ui.notify() called
-4. Pi has already invalidated the old ctx → throws 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
-```
-
-The problem: the **session_start handler** hasn't had a chance to run yet to start the new notifier.
-
-### Why hasn't session_start run yet?
-
-When Pi invalidates ctx, the old notifier interval **is still running** (clearInterval hasn't been called yet). The interval tick occurs **before** `cleanupRuntime()` or the `session_start` handler runs. This is a **race condition** between:
-- The 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
-- The user has to manually check `team status` to learn that runs finished
-- Severe UX impact: pi-crew goes "silent" after a restart
-
-## Fix
-
-### Option A: Silently swallow stale errors (recommended)
-
-Instead of stopping the notifier, just **skip this notification** and let session_start restart the notifier with the 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 the next tick,
-        // making it effectively dormant until cleaned up.
-        return;
-    }
-    console.error(`[pi-crew] async notifier error: ${message}`);
-}
-```
-
-Rationale: the `isCurrent` guard will return false once `sessionGeneration++` runs → the old notifier interval keeps running but does nothing (silent). The new notifier from `session_start` will work normally.
-
-### Option B: Add an explicit restart mechanism
-
-Add a `restartAsyncRunNotifier()` function and call it from the `session_start` handler. But Option A is simpler and sufficient.
-
-## 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

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

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