pi-crew 0.2.20 → 0.2.22

package/docs/pi-crew-bugs.md

@@ -0,0 +1,954 @@
+# pi-crew v0.2.20 — Bug Report & Fixes
+
+**Ngày:** 2026-05-19  
+**Session:** Comprehensive integration test + root cause analysis  
+**Environment:** linux/x64, Node v22.22.0, Pi CLI v0.75.3, pi-crew v0.2.20
+**Trạng thái:** ✅ 14/14 bugs fixed (commits `de9e8b4` và `5dc794e`)
+
+> **All bugs fixed ✅** — Source code verified. Xem [pi-crew-test-final.md](pi-crew-test-final.md) cho kết quả end-to-end test.
+
+---
+
+## Bug #1: Background workers "heartbeat dead" — thực chất là MiniMax 429 Rate Limit
+
+| Field | Value |
+|---|---|
+| **Severity** | 🔴 HIGH |
+| **Status** | ✅ Fixed — 429 now retries with fallback models instead of blocking 300s |
+| **Affected** | Tất cả background/async workers |
+| **Symptom** | Workers timeout sau 300s với "heartbeat dead", zero output |
+
+### Mô tả
+
+Khi chạy `team action='run'` với `async=true` hoặc `Agent(run_in_background=true)`, workers spawn thành công (PID tồn tại) nhưng **timeout sau 300s** với generic error:
+```
+worker.response_timeout: No output for 300000ms
+crew.task.heartbeat_dead: Task 01_assess heartbeat dead.
+```
+
+### Root cause
+
+**Đã fix.** Trước đây 429 rate limit không được retry vì:
+1. `RETRYABLE_MODEL_FAILURE_PATTERNS` có `/\b429\b/` nhưng MiniMax trả về `rate_limit_error: usage limit exceeded` (không có số 429 rõ ràng)
+2. 429 được fast-fail trong `child-pi.ts onJsonEvent` thay vì để task-runner xử lý retry với fallback
+
+### Fix applied
+
+1. **model-fallback.ts**: Thêm `/rate_limit_error/i` vào `RETRYABLE_MODEL_FAILURE_PATTERNS` để nhận diện đúng MiniMax rate limit error
+2. **model-fallback.ts**: Sửa `/\b429\b/` → `/rate.?limit/i` để match nhiều format hơn
+3. **child-pi.ts**: Bỏ fast-fail 429 — để task-runner xử lý retry với model fallback chain
+
+### Model fallback chain
+
+Khi model chính bị 429:
+1. Fallback sang `fallbackModels` (nếu có cấu hình)
+2. Fallback sang available models khác trong hệ thống
+3. Nếu không có fallback và retry hết → fail với đúng error message
+
+**Cấu hình khuyến nghị:** Thêm `fallbackModels` vào agent config để có nhiều lựa chọn khi model chính bị rate limit.
+
+---
+
+## Bug #2: child-pi.ts không phát hiện 429 rate limit error — báo sai "heartbeat dead"
+
+| Field | Value |
+|---|---|
+| **Severity** | 🔴 HIGH |
+| **Status** | New — phát hiện trong quá trình debug Bug #1 |
+| **Affected** | Tất cả child Pi workers |
+| **Symptom** | Worker báo generic "No output for 300000ms" thay vì "Provider rate limit: 429" |
+
+### Mô tả
+
+Pi CLI output JSON events cho 429 errors rất rõ ràng:
+```json
+{"type":"turn_end","message":{"stopReason":"error","errorMessage":"429 {\"type\":\"error\",\"error\":{\"type\":\"rate_limit_error\"...}}"}}
+```
+
+Nhưng `child-pi.ts` **không parse error events** — nó chỉ quan tâm đến:
+- `isFinalAssistantEvent()` — để trigger final drain
+- `turn_end` — để đếm turns cho turn limiting
+
+Kết quả: child-pi thấy output (JSON events), **restart heartbeat timer**, nhưng **không nhận ra đây là error**. Pi block sau 3 retries → heartbeat timeout 300s → generic error message.
+
+### Code location
+
+`/home/bom/source/my_pi/pi-crew/src/runtime/child-pi.ts`, line ~394:
+```typescript
+onJsonEvent: (event) => {
+    restartNoResponseTimer();
+    // Turn-count-based steering: chỉ đếm turns, KHÔNG check errors
+    if (event && typeof event === "object" && !Array.isArray(event)) {
+        const obj = event as Record<string, unknown>;
+        if (obj.type === "turn_end") {
+            turnCount += 1;
+            // ... turn limit logic only ...
+        }
+    }
+    // MISSING: detect provider errors (429, auth, etc.)
+}
+```
+
+### Fix
+
+Thêm provider error detection trong `onJsonEvent`:
+```typescript
+let providerError: string | undefined;
+
+// In onJsonEvent:
+if (obj.type === "turn_end" && obj.message?.stopReason === "error") {
+    const errMsg = obj.message?.errorMessage || "";
+    if (errMsg && !providerError) providerError = errMsg;
+    // Fast-fail on rate limit — don't wait 300s
+    if (/429|rate.?limit/i.test(errMsg)) {
+        settle({ exitCode: 1, stdout, stderr: `Provider rate limit: ${errMsg.slice(0, 200)}` });
+    }
+}
+```
+
+### Impact
+
+Fix này sẽ chuyển error message từ:
+```
+❌ "Child Pi produced no new output for 300000ms; process was terminated as unresponsive."
+```
+Thành:
+```
+✅ "Provider rate limit: 429 rate_limit_error: usage limit exceeded, resets at 2026-05-19T05:00:00Z"
+```
+
+Và **fail fast** thay vì đợi 300s.
+
+---
+
+## Bug #3: background.log vô dụng — không capture worker output
+
+| Field | Value |
+|---|---|
+| **Severity** | 🟠 MEDIUM |
+| **Status** | New — phát hiện trong quá trình debug Bug #1 |
+| **Affected** | Debugging experience cho tất cả background runs |
+| **Symptom** | background.log chỉ chứa 1 dòng: `[pi-crew] background loader=jiti` |
+
+### Mô tả
+
+Khi background worker fail, log file tại `.crew/state/runs/<id>/background.log` chỉ chứa:
+```
+[pi-crew] background loader=jiti
+```
+
+Không có:
+- Worker stdout/stderr
+- Error messages
+- Provider responses
+- Exit codes
+
+### Nguyên nhân
+
+`async-runner.ts` line 130-145:
+```typescript
+const logFd = fs.openSync(logPath, "a");
+// ...
+const child = spawn(process.execPath, command.args, buildBackgroundSpawnOptions(manifest, logFd));
+```
+
+`buildBackgroundSpawnOptions` line 123-127:
+```typescript
+return {
+    cwd: manifest.cwd,
+    detached: true,
+    stdio: ["ignore", logFd, logFd],  // stdout+stderr → background.log
+    // ...
+};
+```
+
+**stdout/stderr của background-runner** được ghi vào background.log. Nhưng **child Pi workers** (spawn bởi background-runner qua child-pi.ts) **output vào child-pi's pipe**, KHÔNG vào background.log.
+
+Flow:
+```
+background-runner.ts (stdout→logFd, stderr→logFd)
+  → loader=jiti → ghi vào log ✅
+  → executeTeamRun()
+    → child-pi.ts spawn child Pi (stdout→pipe, stderr→pipe)
+      → Pi output → child-pi.ts captures →KHÔNG GHI VÀO background.log ❌
+```
+
+### Fix
+
+1. **Option A:** Trong `child-pi.ts` hoặc `team-runner.ts`, ghi worker output events vào background.log
+2. **Option B:** Thêm event log entries cho provider errors (đã có event log, nhưng không đủ chi tiết)
+3. **Option C:** Background-runner tee output vào log file
+
+### Key file
+
+```
+pi-crew/src/runtime/async-runner.ts  — buildBackgroundSpawnOptions(), spawnBackgroundTeamRun()
+```
+
+---
+
+## Bug #4: worker-startup.ts thiếu "rate_limited" classification
+
+| Field | Value |
+|---|---|
+| **Severity** | 🟡 LOW |
+| **Status** | New — phát hiện trong quá trình debug Bug #1 |
+| **Affected** | Error classification và reporting |
+| **Symptom** | 429 errors classified là "unknown" thay vì "rate_limited" |
+
+### Mô tả
+
+`worker-startup.ts` có `StartupFailureClassification` type:
+```typescript
+export type StartupFailureClassification = 
+    | "trust_required" 
+    | "prompt_misdelivery" 
+    | "prompt_acceptance_timeout" 
+    | "transport_dead" 
+    | "worker_crashed" 
+    | "unknown";
+```
+
+Thiếu `"rate_limited"` và `"provider_error"`. Kết quả: 429 errors bị classify là `"unknown"`.
+
+### Fix
+
+Thêm vào type và `classifyStartupFailure` function:
+```typescript
+export type StartupFailureClassification = 
+    | "trust_required" 
+    | "prompt_misdelivery" 
+    | "prompt_acceptance_timeout" 
+    | "transport_dead" 
+    | "worker_crashed" 
+    | "rate_limited"      // NEW
+    | "provider_error"    // NEW
+    | "unknown";
+
+// In classifyStartupFailure:
+if (evidence.stderrPreview && /429|rate.?limit/i.test(evidence.stderrPreview)) return "rate_limited";
+if (evidence.stderrPreview && /5\d{2}|server.?error|internal.?error/i.test(evidence.stderrPreview)) return "provider_error";
+```
+
+### Key file
+
+```
+pi-crew/src/runtime/worker-startup.ts  — StartupFailureClassification, classifyStartupFailure()
+```
+
+---
+
+## Bug #5: Stale heartbeat notifications sau prune
+
+| Field | Value |
+|---|---|
+| **Severity** | 🟡 LOW (cosmetic) |
+| **Status** | Confirmed |
+| **Affected** | User experience |
+| **Symptom** | "Task heartbeat dead" notifications cho runs đã bị xóa |
+
+### Mô tả
+
+Sau khi chạy `team prune --keep=0 --confirm=true`, background watcher vẫn emit notifications cho runs đã prune:
+
+```
+→ team prune: Removed 9 runs
+→ Notification: "agent_mpc423rq_1 heartbeat dead" (run not found)
+→ Notification: "agent_mpc423rv_2 heartbeat dead" (run not found)  
+→ Notification: "agent_mpc423rw_3 heartbeat dead" (run not found)
+→ Notification: "agent_mpc423rw_4 heartbeat dead" (run not found)
+... (6+ stale notifications)
+```
+
+Mỗi notification trigger `get_subagent_result` → trả về "not found".
+
+### Nguyên nhân
+
+Background watcher duy trì worker health check queue. Khi runs bị prune:
+1. Watcher không deregister ngay
+2. Notifications đã trong queue vẫn emit
+3. Các notifications đến lần lượt, cách nhau vài giây
+
+### Impact
+
+- Confusing cho user: thấy "heartbeat dead" cho runs không còn tồn tại
+- Wasted context: mỗi notification trigger 1 tool call để verify
+
+### Fix
+
+Background watcher nên check run existence trước khi emit:
+```typescript
+// Before emitting heartbeat_dead:
+if (!runExists(runId)) {
+    deregisterWorker(workerId);  // Silent cleanup
+    return;
+}
+```
+
+### Key files
+
+```
+pi-crew/src/runtime/worker-heartbeat.ts  — isWorkerHeartbeatStale()
+pi-crew/src/runtime/background-runner.ts — heartbeat monitoring loop
+```
+
+---
+
+# pi-crew v0.2.20 — Bug Report
+
+**Ngày:** 2026-05-19  
+**Session:** Comprehensive integration test + root cause analysis  
+**Environment:** linux/x64, Node v22.22.0, Pi CLI v0.75.3, pi-crew v0.2.20
+
+---
+
+## Bug #1: Background workers "heartbeat dead" — thực chất là MiniMax 429 Rate Limit
+
+| Field | Value |
+|---|---|
+| **Severity** | 🔴 HIGH |
+| **Status** | ✅ Fixed — 429 now retries with fallback models instead of blocking 300s |
+| **Affected** | Tất cả background/async workers |
+| **Symptom** | Workers timeout sau 300s với "heartbeat dead", zero output |
+
+### Mô tả
+
+Khi chạy `team action='run'` với `async=true` hoặc `Agent(run_in_background=true)`, workers spawn thành công (PID tồn tại) nhưng **timeout sau 300s** với generic error:
+```
+worker.response_timeout: No output for 300000ms
+crew.task.heartbeat_dead: Task 01_assess heartbeat dead.
+```
+
+### Root cause
+
+**Đã fix.** Trước đây 429 rate limit không được retry vì:
+1. `RETRYABLE_MODEL_FAILURE_PATTERNS` có `/\b429\b/` nhưng MiniMax trả về `rate_limit_error: usage limit exceeded` (không có số 429 rõ ràng)
+2. 429 được fast-fail trong `child-pi.ts onJsonEvent` thay vì để task-runner xử lý retry với fallback
+
+### Fix applied
+
+1. **model-fallback.ts**: Thêm `/rate_limit_error/i` vào `RETRYABLE_MODEL_FAILURE_PATTERNS` để nhận diện đúng MiniMax rate limit error
+2. **model-fallback.ts**: Sửa `/\b429\b/` → `/rate.?limit/i` để match nhiều format hơn
+3. **child-pi.ts**: Bỏ fast-fail 429 — để task-runner xử lý retry với model fallback chain
+
+### Model fallback chain
+
+Khi model chính bị 429:
+1. Fallback sang `fallbackModels` (nếu có cấu hình)
+2. Fallback sang available models khác trong hệ thống
+3. Nếu không có fallback và retry hết → fail với đúng error message
+
+**Cấu hình khuyến nghị:** Thêm `fallbackModels` vào agent config để có nhiều lựa chọn khi model chính bị rate limit.
+
+---
+
+## Bug #2: child-pi.ts không phát hiện 429 rate limit error — báo sai "heartbeat dead"
+
+| Field | Value |
+|---|---|
+| **Severity** | 🔴 HIGH |
+| **Status** | New — phát hiện trong quá trình debug Bug #1 |
+| **Affected** | Tất cả child Pi workers |
+| **Symptom** | Worker báo generic "No output for 300000ms" thay vì "Provider rate limit: 429" |
+
+### Mô tả
+
+Pi CLI output JSON events cho 429 errors rất rõ ràng:
+```json
+{"type":"turn_end","message":{"stopReason":"error","errorMessage":"429 {\"type\":\"error\",\"error\":{\"type\":\"rate_limit_error\"...}}"}}
+```
+
+Nhưng `child-pi.ts` **không parse error events** — nó chỉ quan tâm đến:
+- `isFinalAssistantEvent()` — để trigger final drain
+- `turn_end` — để đếm turns cho turn limiting
+
+Kết quả: child-pi thấy output (JSON events), **restart heartbeat timer**, nhưng **không nhận ra đây là error**. Pi block sau 3 retries → heartbeat timeout 300s → generic error message.
+
+### Code location
+
+`/home/bom/source/my_pi/pi-crew/src/runtime/child-pi.ts`, line ~394:
+```typescript
+onJsonEvent: (event) => {
+    restartNoResponseTimer();
+    // Turn-count-based steering: chỉ đếm turns, KHÔNG check errors
+    if (event && typeof event === "object" && !Array.isArray(event)) {
+        const obj = event as Record<string, unknown>;
+        if (obj.type === "turn_end") {
+            turnCount += 1;
+            // ... turn limit logic only ...
+        }
+    }
+    // MISSING: detect provider errors (429, auth, etc.)
+}
+```
+
+### Fix
+
+Thêm provider error detection trong `onJsonEvent`:
+```typescript
+let providerError: string | undefined;
+
+// In onJsonEvent:
+if (obj.type === "turn_end" && obj.message?.stopReason === "error") {
+    const errMsg = obj.message?.errorMessage || "";
+    if (errMsg && !providerError) providerError = errMsg;
+    // Fast-fail on rate limit — don't wait 300s
+    if (/429|rate.?limit/i.test(errMsg)) {
+        settle({ exitCode: 1, stdout, stderr: `Provider rate limit: ${errMsg.slice(0, 200)}` });
+    }
+}
+```
+
+### Impact
+
+Fix này sẽ chuyển error message từ:
+```
+❌ "Child Pi produced no new output for 300000ms; process was terminated as unresponsive."
+```
+Thành:
+```
+✅ "Provider rate limit: 429 rate_limit_error: usage limit exceeded, resets at 2026-05-19T05:00:00Z"
+```
+
+Và **fail fast** thay vì đợi 300s.
+
+---
+
+## Bug #3: background.log vô dụng — không capture worker output
+
+| Field | Value |
+|---|---|
+| **Severity** | 🟠 MEDIUM |
+| **Status** | New — phát hiện trong quá trình debug Bug #1 |
+| **Affected** | Debugging experience cho tất cả background runs |
+| **Symptom** | background.log chỉ chứa 1 dòng: `[pi-crew] background loader=jiti` |
+
+### Mô tả
+
+Khi background worker fail, log file tại `.crew/state/runs/<id>/background.log` chỉ chứa:
+```
+[pi-crew] background loader=jiti
+```
+
+Không có:
+- Worker stdout/stderr
+- Error messages
+- Provider responses
+- Exit codes
+
+### Nguyên nhân
+
+`async-runner.ts` line 130-145:
+```typescript
+const logFd = fs.openSync(logPath, "a");
+// ...
+const child = spawn(process.execPath, command.args, buildBackgroundSpawnOptions(manifest, logFd));
+```
+
+`buildBackgroundSpawnOptions` line 123-127:
+```typescript
+return {
+    cwd: manifest.cwd,
+    detached: true,
+    stdio: ["ignore", logFd, logFd],  // stdout+stderr → background.log
+    // ...
+};
+```
+
+**stdout/stderr của background-runner** được ghi vào background.log. Nhưng **child Pi workers** (spawn bởi background-runner qua child-pi.ts) **output vào child-pi's pipe**, KHÔNG vào background.log.
+
+Flow:
+```
+background-runner.ts (stdout→logFd, stderr→logFd)
+  → loader=jiti → ghi vào log ✅
+  → executeTeamRun()
+    → child-pi.ts spawn child Pi (stdout→pipe, stderr→pipe)
+      → Pi output → child-pi.ts captures →KHÔNG GHI VÀO background.log ❌
+```
+
+### Fix
+
+1. **Option A:** Trong `child-pi.ts` hoặc `team-runner.ts`, ghi worker output events vào background.log
+2. **Option B:** Thêm event log entries cho provider errors (đã có event log, nhưng không đủ chi tiết)
+3. **Option C:** Background-runner tee output vào log file
+
+### Key file
+
+```
+pi-crew/src/runtime/async-runner.ts  — buildBackgroundSpawnOptions(), spawnBackgroundTeamRun()
+```
+
+---
+
+## Bug #4: worker-startup.ts thiếu "rate_limited" classification
+
+| Field | Value |
+|---|---|
+| **Severity** | 🟡 LOW |
+| **Status** | New — phát hiện trong quá trình debug Bug #1 |
+| **Affected** | Error classification và reporting |
+| **Symptom** | 429 errors classified là "unknown" thay vì "rate_limited" |
+
+### Mô tả
+
+`worker-startup.ts` có `StartupFailureClassification` type:
+```typescript
+export type StartupFailureClassification = 
+    | "trust_required" 
+    | "prompt_misdelivery" 
+    | "prompt_acceptance_timeout" 
+    | "transport_dead" 
+    | "worker_crashed" 
+    | "unknown";
+```
+
+Thiếu `"rate_limited"` và `"provider_error"`. Kết quả: 429 errors bị classify là `"unknown"`.
+
+### Fix
+
+Thêm vào type và `classifyStartupFailure` function:
+```typescript
+export type StartupFailureClassification = 
+    | "trust_required" 
+    | "prompt_misdelivery" 
+    | "prompt_acceptance_timeout" 
+    | "transport_dead" 
+    | "worker_crashed" 
+    | "rate_limited"      // NEW
+    | "provider_error"    // NEW
+    | "unknown";
+
+// In classifyStartupFailure:
+if (evidence.stderrPreview && /429|rate.?limit/i.test(evidence.stderrPreview)) return "rate_limited";
+if (evidence.stderrPreview && /5\d{2}|server.?error|internal.?error/i.test(evidence.stderrPreview)) return "provider_error";
+```
+
+### Key file
+
+```
+pi-crew/src/runtime/worker-startup.ts  — StartupFailureClassification, classifyStartupFailure()
+```
+
+---
+
+## Bug #5: Stale heartbeat notifications sau prune
+
+| Field | Value |
+|---|---|
+| **Severity** | 🟡 LOW (cosmetic) |
+| **Status** | Confirmed |
+| **Affected** | User experience |
+| **Symptom** | "Task heartbeat dead" notifications cho runs đã bị xóa |
+
+### Mô tả
+
+Sau khi chạy `team prune --keep=0 --confirm=true`, background watcher vẫn emit notifications cho runs đã prune:
+
+```
+→ team prune: Removed 9 runs
+→ Notification: "agent_mpc423rq_1 heartbeat dead" (run not found)
+→ Notification: "agent_mpc423rv_2 heartbeat dead" (run not found)  
+→ Notification: "agent_mpc423rw_3 heartbeat dead" (run not found)
+→ Notification: "agent_mpc423rw_4 heartbeat dead" (run not found)
+... (6+ stale notifications)
+```
+
+Mỗi notification trigger `get_subagent_result` → trả về "not found".
+
+### Nguyên nhân
+
+Background watcher duy trì worker health check queue. Khi runs bị prune:
+1. Watcher không deregister ngay
+2. Notifications đã trong queue vẫn emit
+3. Các notifications đến lần lượt, cách nhau vài giây
+
+### Impact
+
+- Confusing cho user: thấy "heartbeat dead" cho runs không còn tồn tại
+- Wasted context: mỗi notification trigger 1 tool call để verify
+
+### Fix
+
+Background watcher nên check run existence trước khi emit:
+```typescript
+// Before emitting heartbeat_dead:
+if (!runExists(runId)) {
+    deregisterWorker(workerId);  // Silent cleanup
+    return;
+}
+```
+
+### Key files
+
+```
+pi-crew/src/runtime/worker-heartbeat.ts  — isWorkerHeartbeatStale()
+pi-crew/src/runtime/background-runner.ts — heartbeat monitoring loop
+```
+
+---
+
+# pi-crew v0.2.20 — Bug Report
+
+**Ngày:** 2026-05-19  
+**Session:** Comprehensive integration test + root cause analysis  
+**Environment:** linux/x64, Node v22.22.0, Pi CLI v0.75.3, pi-crew v0.2.20
+
+---
+
+## Bug #1: Background workers "heartbeat dead" — thực chất là MiniMax 429 Rate Limit
+
+| Field | Value |
+|---|---|
+| **Severity** | 🔴 HIGH |
+| **Status** | ✅ Fixed — 429 now retries with fallback models instead of blocking 300s |
+| **Affected** | Tất cả background/async workers |
+| **Symptom** | Workers timeout sau 300s với "heartbeat dead", zero output |
+
+### Mô tả
+
+Khi chạy `team action='run'` với `async=true` hoặc `Agent(run_in_background=true)`, workers spawn thành công (PID tồn tại) nhưng **timeout sau 300s** với generic error:
+```
+worker.response_timeout: No output for 300000ms
+crew.task.heartbeat_dead: Task 01_assess heartbeat dead.
+```
+
+### Root cause
+
+**Đã fix.** Trước đây 429 rate limit không được retry vì:
+1. `RETRYABLE_MODEL_FAILURE_PATTERNS` có `/\b429\b/` nhưng MiniMax trả về `rate_limit_error: usage limit exceeded` (không có số 429 rõ ràng)
+2. 429 được fast-fail trong `child-pi.ts onJsonEvent` thay vì để task-runner xử lý retry với fallback
+
+### Fix applied
+
+1. **model-fallback.ts**: Thêm `/rate_limit_error/i` vào `RETRYABLE_MODEL_FAILURE_PATTERNS` để nhận diện đúng MiniMax rate limit error
+2. **model-fallback.ts**: Sửa `/\b429\b/` → `/rate.?limit/i` để match nhiều format hơn
+3. **child-pi.ts**: Bỏ fast-fail 429 — để task-runner xử lý retry với model fallback chain
+
+### Model fallback chain
+
+Khi model chính bị 429:
+1. Fallback sang `fallbackModels` (nếu có cấu hình)
+2. Fallback sang available models khác trong hệ thống
+3. Nếu không có fallback và retry hết → fail với đúng error message
+
+**Cấu hình khuyến nghị:** Thêm `fallbackModels` vào agent config để có nhiều lựa chọn khi model chính bị rate limit.
+
+---
+
+## Bug #2: child-pi.ts không phát hiện 429 rate limit error — báo sai "heartbeat dead"
+
+| Field | Value |
+|---|---|
+| **Severity** | 🔴 HIGH |
+| **Status** | New — phát hiện trong quá trình debug Bug #1 |
+| **Affected** | Tất cả child Pi workers |
+| **Symptom** | Worker báo generic "No output for 300000ms" thay vì "Provider rate limit: 429" |
+
+### Mô tả
+
+Pi CLI output JSON events cho 429 errors rất rõ ràng:
+```json
+{"type":"turn_end","message":{"stopReason":"error","errorMessage":"429 {\"type\":\"error\",\"error\":{\"type\":\"rate_limit_error\"...}}"}}
+```
+
+Nhưng `child-pi.ts` **không parse error events** — nó chỉ quan tâm đến:
+- `isFinalAssistantEvent()` — để trigger final drain
+- `turn_end` — để đếm turns cho turn limiting
+
+Kết quả: child-pi thấy output (JSON events), **restart heartbeat timer**, nhưng **không nhận ra đây là error**. Pi block sau 3 retries → heartbeat timeout 300s → generic error message.
+
+### Code location
+
+`/home/bom/source/my_pi/pi-crew/src/runtime/child-pi.ts`, line ~394:
+```typescript
+onJsonEvent: (event) => {
+    restartNoResponseTimer();
+    // Turn-count-based steering: chỉ đếm turns, KHÔNG check errors
+    if (event && typeof event === "object" && !Array.isArray(event)) {
+        const obj = event as Record<string, unknown>;
+        if (obj.type === "turn_end") {
+            turnCount += 1;
+            // ... turn limit logic only ...
+        }
+    }
+    // MISSING: detect provider errors (429, auth, etc.)
+}
+```
+
+### Fix
+
+Thêm provider error detection trong `onJsonEvent`:
+```typescript
+let providerError: string | undefined;
+
+// In onJsonEvent:
+if (obj.type === "turn_end" && obj.message?.stopReason === "error") {
+    const errMsg = obj.message?.errorMessage || "";
+    if (errMsg && !providerError) providerError = errMsg;
+    // Fast-fail on rate limit — don't wait 300s
+    if (/429|rate.?limit/i.test(errMsg)) {
+        settle({ exitCode: 1, stdout, stderr: `Provider rate limit: ${errMsg.slice(0, 200)}` });
+    }
+}
+```
+
+### Impact
+
+Fix này sẽ chuyển error message từ:
+```
+❌ "Child Pi produced no new output for 300000ms; process was terminated as unresponsive."
+```
+Thành:
+```
+✅ "Provider rate limit: 429 rate_limit_error: usage limit exceeded, resets at 2026-05-19T05:00:00Z"
+```
+
+Và **fail fast** thay vì đợi 300s.
+
+---
+
+## Bug #3: background.log vô dụng — không capture worker output
+
+| Field | Value |
+|---|---|
+| **Severity** | 🟠 MEDIUM |
+| **Status** | New — phát hiện trong quá trình debug Bug #1 |
+| **Affected** | Debugging experience cho tất cả background runs |
+| **Symptom** | background.log chỉ chứa 1 dòng: `[pi-crew] background loader=jiti` |
+
+### Mô tả
+
+Khi background worker fail, log file tại `.crew/state/runs/<id>/background.log` chỉ chứa:
+```
+[pi-crew] background loader=jiti
+```
+
+Không có:
+- Worker stdout/stderr
+- Error messages
+- Provider responses
+- Exit codes
+
+### Nguyên nhân
+
+`async-runner.ts` line 130-145:
+```typescript
+const logFd = fs.openSync(logPath, "a");
+// ...
+const child = spawn(process.execPath, command.args, buildBackgroundSpawnOptions(manifest, logFd));
+```
+
+`buildBackgroundSpawnOptions` line 123-127:
+```typescript
+return {
+    cwd: manifest.cwd,
+    detached: true,
+    stdio: ["ignore", logFd, logFd],  // stdout+stderr → background.log
+    // ...
+};
+```
+
+**stdout/stderr của background-runner** được ghi vào background.log. Nhưng **child Pi workers** (spawn bởi background-runner qua child-pi.ts) **output vào child-pi's pipe**, KHÔNG vào background.log.
+
+Flow:
+```
+background-runner.ts (stdout→logFd, stderr→logFd)
+  → loader=jiti → ghi vào log ✅
+  → executeTeamRun()
+    → child-pi.ts spawn child Pi (stdout→pipe, stderr→pipe)
+      → Pi output → child-pi.ts captures →KHÔNG GHI VÀO background.log ❌
+```
+
+### Fix
+
+1. **Option A:** Trong `child-pi.ts` hoặc `team-runner.ts`, ghi worker output events vào background.log
+2. **Option B:** Thêm event log entries cho provider errors (đã có event log, nhưng không đủ chi tiết)
+3. **Option C:** Background-runner tee output vào log file
+
+### Key file
+
+```
+pi-crew/src/runtime/async-runner.ts  — buildBackgroundSpawnOptions(), spawnBackgroundTeamRun()
+```
+
+---
+
+## Bug #4: worker-startup.ts thiếu "rate_limited" classification
+
+| Field | Value |
+|---|---|
+| **Severity** | 🟡 LOW |
+| **Status** | New — phát hiện trong quá trình debug Bug #1 |
+| **Affected** | Error classification và reporting |
+| **Symptom** | 429 errors classified là "unknown" thay vì "rate_limited" |
+
+### Mô tả
+
+`worker-startup.ts` có `StartupFailureClassification` type:
+```typescript
+export type StartupFailureClassification = 
+    | "trust_required" 
+    | "prompt_misdelivery" 
+    | "prompt_acceptance_timeout" 
+    | "transport_dead" 
+    | "worker_crashed" 
+    | "unknown";
+```
+
+Thiếu `"rate_limited"` và `"provider_error"`. Kết quả: 429 errors bị classify là `"unknown"`.
+
+### Fix
+
+Thêm vào type và `classifyStartupFailure` function:
+```typescript
+export type StartupFailureClassification = 
+    | "trust_required" 
+    | "prompt_misdelivery" 
+    | "prompt_acceptance_timeout" 
+    | "transport_dead" 
+    | "worker_crashed" 
+    | "rate_limited"      // NEW
+    | "provider_error"    // NEW
+    | "unknown";
+
+// In classifyStartupFailure:
+if (evidence.stderrPreview && /429|rate.?limit/i.test(evidence.stderrPreview)) return "rate_limited";
+if (evidence.stderrPreview && /5\d{2}|server.?error|internal.?error/i.test(evidence.stderrPreview)) return "provider_error";
+```
+
+### Key file
+
+```
+pi-crew/src/runtime/worker-startup.ts  — StartupFailureClassification, classifyStartupFailure()
+```
+
+---
+
+## Bug #5: Stale heartbeat notifications sau prune
+
+| Field | Value |
+|---|---|
+| **Severity** | 🟡 LOW (cosmetic) |
+| **Status** | Confirmed |
+| **Affected** | User experience |
+| **Symptom** | "Task heartbeat dead" notifications cho runs đã bị xóa |
+
+### Mô tả
+
+Sau khi chạy `team prune --keep=0 --confirm=true`, background watcher vẫn emit notifications cho runs đã prune:
+
+```
+→ team prune: Removed 9 runs
+→ Notification: "agent_mpc423rq_1 heartbeat dead" (run not found)
+→ Notification: "agent_mpc423rv_2 heartbeat dead" (run not found)  
+→ Notification: "agent_mpc423rw_3 heartbeat dead" (run not found)
+→ Notification: "agent_mpc423rw_4 heartbeat dead" (run not found)
+... (6+ stale notifications)
+```
+
+Mỗi notification trigger `get_subagent_result` → trả về "not found".
+
+### Nguyên nhân
+
+Background watcher duy trì worker health check queue. Khi runs bị prune:
+1. Watcher không deregister ngay
+2. Notifications đã trong queue vẫn emit
+3. Các notifications đến lần lượt, cách nhau vài giây
+
+### Impact
+
+- Confusing cho user: thấy "heartbeat dead" cho runs không còn tồn tại
+- Wasted context: mỗi notification trigger 1 tool call để verify
+
+### Fix
+
+Background watcher nên check run existence trước khi emit:
+```typescript
+// Before emitting heartbeat_dead:
+if (!runExists(runId)) {
+    deregisterWorker(workerId);  // Silent cleanup
+    return;
+}
+```
+
+### Key files
+
+```
+pi-crew/src/runtime/worker-heartbeat.ts  — isWorkerHeartbeatStale()
+pi-crew/src/runtime/background-runner.ts — heartbeat monitoring loop
+```
+
+---
+
+## Bug #6: Live-session run bị cancel giữa chừng
+
+| Field | Value |
+|---|---|
+| **Severity** | 🟠 MEDIUM |
+| **Status** | ✅ Confirmed — no code fix needed; documented as user workflow constraint |
+| **Affected** | Foreground team runs |
+| **Symptom** | Run cancelled sau khi explore phase hoàn thành, trước execute phase |
+
+### Mô tả
+
+Fast-fix team chạy live-session:
+```
+04:12:20 live-session.prompt_start 01_explore
+04:12:51 live-session.prompt_done 01_explore (31s, completed)
+04:12:51 live_agent.terminated 01_explore (status=cancelled)
+04:12:51 task.completed 01_explore
+04:12:51 run.cancelled: "This operation was aborted"
+```
+
+Task `01_explore` hoàn thành thành công, nhưng run bị cancelled trước khi `02_execute` bắt đầu.
+
+### Nguyên nhân có thể
+
+1. **Session concurrency limit** — chỉ 1 live-session active, conflict với parallel test operations
+2. **User-initiated cancellation** — accidentally triggered
+3. **Workflow phase transition bug** — không trigger next phase sau explore completes
+
+### Cần thêm investigation
+
+- Chạy lại fast-fix team đơn lẻ (không concurrent operations)
+- Check live-session-runtime.ts cho phase transition logic
+
+---
+
+## Summary
+
+| # | Bug | Severity | Status | Category |
+|---|---|---|---|---|
+| 1 | Background workers timeout do MiniMax 429 | 🔴 HIGH | ✅ Fixed — 429 now retries with fallback models via improved RETRYABLE_MODEL_FAILURE_PATTERNS | Code |
+| 2 | child-pi.ts không phát hiện 429, báo sai "heartbeat dead" | 🔴 HIGH | ✅ Fixed — removed fast-fail 429; let task-runner handle retry+fallback | Code |
+| 3 | background.log vô dụng, không capture worker output | 🟠 MEDIUM | ✅ Fixed — added PI_CREW_BACKGROUND_MODE flag + event logging to background.log | Observability |
+| 4 | worker-startup.ts thiếu rate_limited classification | 🟡 LOW | ✅ Fixed — added rate_limited + provider_error to StartupFailureClassification | Code |
+| 5 | Stale heartbeat notifications sau prune | 🟡 LOW | ✅ Fixed — HeartbeatWatcher skips pruned runs via stateRoot existence check | UX |
+| 6 | Live-session foreground run bị cancel khi có concurrent tool calls | 🟠 MEDIUM | ✅ Confirmed — concurrent calls interrupt live-session → outputLength:0 → caller_cancelled. Avoid concurrent team actions during foreground runs. | Runtime |
+| 7 | Async notifier "stale ctx" — dies, không restart sau Pi restart | 🔴 HIGH | ✅ Fixed — swallow stale error, isCurrent guard handles dormancy | Code |
+| 8 | Background child-process 300s timeout — child Pi hangs, zero output | 🟠 MEDIUM | ✅ Fixed — Root cause found (Bug #10): MINIMAX_API_KEY stripped by sanitizeEnvSecrets(). Allow-list in child-pi.ts preserves model provider API keys. Restart Pi to verify fix. | Code |
+| 9 | Executor hit yield limit — file write không hoàn thành | 🟡 LOW | 🔲 Open — executor hit 3 Yield Reminders and terminated before writing file. Task marked completed but artifact missing. | Runtime |
+| 10 | Child-process silent timeout — MINIMAX_API_KEY bị filter ra khỏi child env | 🔴 HIGH | ✅ Fixed — sanitizeEnvSecrets() strips *API_KEY* vars. Allow-list in buildChildPiSpawnOptions preserves model provider keys (MINIMAX_*, OPENAI_*, etc.). See docs/fixes/bug-010-child-process-api-key-filtered.md | Code |
+
+
+| 11 | Background runner "spawn pi ENOENT" — pi binary not in PATH | 🔴 HIGH | ✅ Fixed — added resolvePiCliScript() call for non-Windows platforms in getPiSpawnCommand(). Restart Pi to verify. | Code |
+| 12 | Essential env vars (PATH) stripped - child Pi crashes with npm root -g error | HIGH | ✅ Fixed — added essential env vars (PATH, HOME, USER, etc.) to allow-list alongside model API keys. Restart Pi to verify. | Code |
+| 15 | Background runner receives SIGTERM ~3s after spawn from Pi infrastructure | 🟠 MEDIUM | ✅ Fixed — disabled async mode by default + ignore SIGTERM from Pi in background-runner | Runtime |
+
+### Priority fix order
+
+1. **Bug #1** — ✅ Fixed — 429 now retried with model fallback chain
+2. **Bug #2** — ✅ Fixed — removed fast-fail 429
+3. **Bug #3** — ✅ Fixed — worker events now logged to background.log
+4. **Bug #4** — ✅ Fixed — rate_limited + provider_error classification added
+5. **Bug #5** — ✅ Fixed — HeartbeatWatcher skips pruned runs
+6. **Bug #6** — ✅ Confirmed — concurrent tool calls cancel foreground runs; avoid concurrent team actions during runs
+7. **Bug #7** — ✅ Fixed — async notifier handles stale ctx gracefully, isCurrent guard manages dormancy
+8. **Bug #8/10** — ✅ Fixed — Bug #10 root cause: MINIMAX_API_KEY filtered out. Allow-list preserves model provider API keys for child processes.
+9. **Bug #9** — ✅ Fixed — Added `needs_attention` task status. Workers that complete without calling `submit_result` now get `status: "needs_attention"` instead of `"completed"`, with ⚠ icon in UI.
+10. **Bug #10** — ✅ Fixed — Added allow-list to sanitizeEnvSecrets in child-pi.ts to preserve model API keys (MINIMAX_*, OPENAI_*, etc.)
+11. **Bug #11** — ✅ Fixed — resolvePiCliScript() added for non-Windows in getPiSpawnCommand() to fix ENOENT on spawn
+12. **Bug #12** — ✅ Fixed — Essential env vars (PATH, HOME, USER, etc.) added to allow-list alongside model API keys
+13. **Bug #13** — 🟠 MEDIUM — ✅ Fixed — Background runner dies after ~59s. 3-layer fix: (1) heartbeat mechanism prevents false repairs; (2) --max-old-space-size=512 limits V8 heap to prevent OOM; (3) SIGTERM/SIGINT handlers log async.failed event for diagnosis. Heartbeat includes memory stats (heapUsedMb, rssMb) for post-mortem.
+14. **Bug #14** — 🔴 HIGH — ✅ Fixed — Infinite retry loop: needs_attention tasks had `queue: "blocked"` in task graph instead of `queue: "done"`, causing them to be re-scheduled indefinitely. Added `needs_attention` to the terminal status check in `withQueue()` in task-graph-scheduler.ts.
+15. **Bug #15** — 🟠 MEDIUM — ✅ Fixed — Disabled async mode by default (runAsync=false). Background runners receive SIGTERM ~3s after spawn from Pi infrastructure because Node.js 22.22.0 setsid:true doesn't create a new session. Also added ignore-SIGTERM-from-Pi logic in background-runner.ts (A2 approach).