pi-crew 0.9.27 → 0.9.29

package/docs/REVIEW-FINDINGS-2026-07-CORE.md

@@ -0,0 +1,139 @@
+# pi-crew — Core Engine Review (2026-07)
+
+Review **bộ core** (scheduler, vòng đời child process, state durability/concurrency, worktree isolation, conflict detection) — KHÔNG phải lớp ngoài (lint/deps/hygiene, xem `docs/REVIEW-FINDINGS-2026-07.md`).
+
+- Phiên bản: **v0.9.28** · Node **v22.14.0** · Windows (win32 10.0.22631)
+- Phạm vi đọc sâu (~9K dòng core): `runtime/team-runner.ts`, `runtime/task-runner.ts`, `runtime/child-pi.ts`, `runtime/live-session-runtime.ts`, `runtime/background-runner.ts`, `runtime/goal-loop-runner.ts`, `runtime/stale-reconciler.ts`, `state/state-store.ts`, `state/event-log.ts`, `state/atomic-write.ts`, `state/mailbox.ts`, `worktree/worktree-manager.ts`, `worktree/cleanup.ts`, `utils/conflict-detect.ts`, `config/config.ts`.
+- Phương pháp: 4 luồng deep-read song song + **verify trực tiếp** từng finding trọng yếu bằng đọc lại source (trích dẫn file:line).
+
+## Legend
+
+| Ký hiệu | Nghĩa |
+|---------|-------|
+| ✅ Verified | Đã đọc trực tiếp source, xác nhận cơ chế + file:line |
+| 🔬 Cần repro | Cơ chế hợp lý qua đọc code, **chưa kết luận** — cần dựng test repro để chốt |
+| 🔴 HIGH · 🟡 MEDIUM · ⚪ LOW | Mức nghiêm trọng |
+
+---
+
+## Nhóm A — Findings đã VERIFY trực tiếp trên source
+
+### C1 🔴 ✅ Conflict không phát hiện được trên file CRLF (Windows)
+
+- **File:** `src/utils/conflict-detect.ts:190, 101, 202`
+- **Bằng chứng:** scanner `const lines = text.split("\n");` (190); so khớp chính xác `if (line === SEPARATOR)` với `SEPARATOR = "======="` (26/101); `matchMarker` yêu cầu `if (line.charCodeAt(prefix.length) !== 32 /* space */) return null;` (202). Trên file CRLF, git ghi `=======\r\n` → sau `split("\n")` thành `"=======\r"` ≠ `"======="`; closer `>>>>>>>​\r` có `charCodeAt(7)===13` (CR) ≠ 32.
+- **Bất đối xứng chứng minh:** hàm write-path (`expandContentTokens`) tại dòng 429 *có* strip CR: `const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;` — nhưng scanner (190) thì không.
+- **Tác động:** conflict trong file CRLF không được phát hiện (false negative) → agent tưởng merge sạch và commit code còn `<<<<<<<`/`=======`/`>>>>>>>`. Project có target Windows (CI matrix + nhiều xử lý Windows) nên đây là lỗi thực tế.
+- **Fix đề xuất:** strip trailing `\r` mỗi dòng trong scanner (mirror dòng 429), giữ CR khi re-splice để round-trip byte-accurate. Có thể mở rộng match ≥7 ký tự marker (`^<{7,}(\s|$)`) để chịu `merge.conflictMarkerSize > 7`.
+- **Verify:** unit test feed buffer conflict với `\r\n` → assert 1 block đúng `startLine/separatorLine/endLine`; test LF cũ vẫn pass.
+
+### C2 🔴 ✅ Run toàn task lỗi vẫn bị đánh dấu `completed`
+
+- **File:** `src/runtime/stale-reconciler.ts:66-71`
+- **Bằng chứng:** `checkResultFile` tính `allTerminal` gồm cả `failed`/`cancelled`; khi true: `manifest.status = "completed"; saveRunManifest(manifest);` — gán trực tiếp, bỏ qua `canTransitionRunStatus`.
+- **Tác động:** run crash mà mọi task `failed`/`cancelled` vẫn được stamp `completed` → báo thành công sai, UI/logic downstream key theo `status==="completed"` hiểu nhầm.
+- **Fix đề xuất:** suy ra status cuối từ outcome task: `completed` chỉ khi không có task `failed`; ngược lại `failed` (hoặc `cancelled` nếu toàn cancelled); đi qua `updateRunStatus`/`canTransitionRunStatus`.
+- **Verify:** test `reconcile` với toàn task `failed` → manifest `failed`; mixed failed+completed → `failed`.
+
+### C3 🔴 ✅ Crash-recovery ghi state KHÔNG atomic
+
+- **File:** `src/runtime/stale-reconciler.ts:496, 504`
+- **Bằng chứng:** nhánh quét orphan-temp dùng `fs.writeFileSync(tasksPath, JSON.stringify(result.repairedTasks, null, 2))` (496) và `fs.writeFileSync(manifestPath, JSON.stringify(updated, null, 2))` (504) — không temp+rename, không fsync, không lock. Phần còn lại của state layer dùng `atomicWriteJson`.
+- **Tác động:** crash/đọc-đồng-thời giữa lúc ghi → `manifest.json`/`tasks.json` rách → `JSON.parse` fail → run vĩnh viễn không đọc được. Chính đường phục hồi lại corrupt state.
+- **Fix đề xuất:** dùng `atomicWriteJson`/`saveRunManifest`/`saveRunTasks` và bọc read-modify-write trong `withRunLockSync`.
+- **Verify:** test inject mid-write crash (mock `writeFileSync` throw sau N byte) → assert manifest vẫn parse được; assert dùng temp+rename (không để lại `.tmp`).
+
+### C4 🔴 ✅ Mất dữ liệu khi reuse worktree "dirty"
+
+- **File:** `src/worktree/worktree-manager.ts:626-637`
+- **Bằng chứng:**
+  ```ts
+  const dirtyStatus = git(worktreePath, ["status", "--porcelain"]);
+  if (dirtyStatus.trim()) {
+      logInternalError("worktree.reused.dirty", ...);
+      git(worktreePath, ["checkout", "--", "."]);
+      git(worktreePath, ["clean", "-fd"]);   // xóa cả file chưa track
+  }
+  ```
+- **Tác động:** reuse worktree (vd resume sau crash) **hard-discard** thay đổi chưa commit + file untracked, chỉ `logInternalError`, **không có force gate**. Trái AGENTS.md "Worktree cleanup must preserve dirty worktrees unless `force`".
+- **Fix đề xuất:** trước khi discard, commit-to-branch/stash (như `cleanup.ts`) hoặc yêu cầu `force`/opt-in; tối thiểu snapshot diff artifact.
+- **Verify:** test reuse worktree có file untracked + tracked edit → assert thay đổi còn khôi phục được (branch/stash/artifact), không mất trắng.
+
+### C5 🟡 ✅ Rò rỉ worktree + branch khi setup-hook/seed lỗi
+
+- **File:** `src/worktree/worktree-manager.ts:650-682` (async: 790-821)
+- **Bằng chứng:** `let worktreeCreated = false;` (650) được set `true` (662) nhưng **không bao giờ đọc**. `runSetupHook(...)` (682) + `overlaySeedPaths` chạy *sau* khi worktree/branch đã tạo; catch chỉ dọn khi `git worktree add` fail. `runSetupHook` throw khi hook lỗi; `normalizeSeedPaths` throw khi seed path traversal/absolute/symlink.
+- **Tác động:** hook/seed lỗi để lại worktree dir + branch `pi-crew/<run>/<task>` mồ côi → lần sau vướng guard "already checked out", buộc `cleanup force=true`.
+- **Fix đề xuất:** bọc `runSetupHook`/`linkNodeModules`/`overlaySeedPaths` trong try/catch, khi lỗi chạy `git worktree remove --force` + `git branch -D` (best-effort) trước khi rethrow, gate bằng `worktreeCreated`.
+- **Verify:** test `setupHook` exit non-zero → `prepareTaskWorkspace` throw AND `git worktree list` không còn path, branch bị xóa.
+
+### C6 🟡 ✅ `worktree.seedPaths` bị nuốt (tính năng chết)
+
+- **File:** `src/config/config.ts:734-745`
+- **Bằng chứng:** `parseWorktreeConfig` chỉ build `setupHook`, `setupHookTimeoutMs`, `linkNodeModules`. `seedPaths` không được parse dù có trong type (`config/types.ts` `seedPaths?: string[]`) và schema (`schema/config-schema.ts`). `worktree-manager` đọc `loadedConfig.config.worktree?.seedPaths ?? []` → luôn `[]`. `updateConfig` re-serialize `parseConfig(current)` → xóa cả `seedPaths` sửa tay.
+- **Tác động:** seedPaths cấu hình toàn cục không bao giờ được overlay vào worktree; feature im lặng không hoạt động.
+- **Fix đề xuất:** thêm `seedPaths: parseStringList(obj.seedPaths)` (validated array) vào `parseWorktreeConfig` + đưa vào điều kiện "some defined".
+- **Verify:** unit `parseConfig({ worktree: { seedPaths: ["a","b"] } })` trả đúng; integration copy seed vào worktree.
+
+### C7 🟡 ✅ `withEventLogLockAsync` phá mutual-exclusion
+
+- **File:** `src/state/event-log.ts:383-394` (và cleanup `asyncQueues` ~591-609)
+- **Bằng chứng:**
+  ```ts
+  const prev = asyncLocks.get(queueKey) ?? Promise.resolve();
+  const next = prev.then(async () => { await fn(); });
+  asyncLocks.set(queueKey, next);
+  try { await next; } finally { asyncLocks.delete(queueKey); }  // xóa vô điều kiện
+  ```
+- **Tác động:** khi ≥3 flush chồng lấn, `finally` của caller cũ `delete(queueKey)` xóa nhầm `next` mới (tail đang chờ); caller kế đọc `undefined` → chạy song song với batch trước → `appendEventBatchInsideLock` xen kẽ: trùng `seq`, rotation đua append → mất event. Reachable khi buffered throughput cao.
+- **Fix đề xuất:** compare-and-delete: `if (asyncLocks.get(queueKey) === next) asyncLocks.delete(queueKey);` — áp dụng cả cleanup `asyncQueues`.
+- **Verify:** test bắn 3+ flush chồng lấn với `fn` đo "in critical section" counter → assert ≤1 và `seq` unique/monotonic.
+
+### C8 🟡 ✅ Steer "wrap up" qua stdin là dead code + log spam
+
+- **File:** `src/runtime/child-pi.ts:388, 1139-1166`
+- **Bằng chứng:** spawn `stdio: ["ignore", "pipe", "pipe"]` (388) → `child.stdin` là `null`; block `if (child.stdin?.writable) { ... child.stdin.write(steerPayload) }` (1139-1146) không bao giờ chạy; nhánh `else` `logInternalError("child-pi.steer-not-writable", ...)` (1165) log **mỗi lần** chạm soft-limit.
+- **Tác động:** soft-limit steer không tới worker → worker luôn chạy tới `maxTurns+graceTurns` rồi hard-abort (lãng phí turn/token, mất cơ hội wrap-up); log nhiễu.
+- **Fix đề xuất:** hoặc spawn `stdio:["pipe","pipe","pipe"]` + xử lý backpressure/EPIPE nếu muốn steer qua stdin; hoặc xóa block stdin, chỉ dựa file-based steering (`PI_CREW_STEERING_FILE`) + hard-abort và bỏ log `steer-not-writable`.
+- **Verify:** test assert (a) steer được ghi khi soft-limit, hoặc (b) không có log `steer-not-writable`.
+
+### C9 🟡 ✅ `cleanup` auto-commit dirty không cần `force`
+
+- **File:** `src/worktree/cleanup.ts:130-207`
+- **Bằng chứng:** nhánh `if (dirty)` luôn chạy `git add -A` → `git commit` → `git branch` → `["worktree","remove","--force",...]` bất kể `options.force`; chỉ nhánh non-dirty mới `if (options.force) args.push("--force")`.
+- **Tác động:** `team cleanup runId=X` (không force) stage mọi file untracked (`-A`) và commit vào branch mới → rủi ro commit secrets/build artifacts; trái contract "preserve dirty unless force".
+- **Fix đề xuất:** gate commit-and-remove-dirty sau `options.force` (hoặc option `commitDirty`); khi không force → giữ worktree + chỉ emit diff artifact.
+- **Verify:** test `cleanupRunWorktrees(manifest, { force: false })` trên worktree dirty → assert được preserve (không commit/remove) và nằm trong `result.preserved`.
+
+---
+
+## Nhóm B — Cần dựng test repro trước khi kết luận (🔬)
+
+Cơ chế đã đọc thấy nhưng **chưa chốt**; mỗi item kèm kế hoạch repro.
+
+| ID | Mức | File:line | Nghi vấn | Repro plan |
+|----|-----|-----------|----------|------------|
+| B1 | 🔴 | `runtime/team-runner.ts:773-786` | catch downgrade dựa `refreshTaskGraphQueues(input.tasks)`; nếu `input.tasks` là snapshot start (còn `queued`) → late-throw ghi đè task đã `completed` thành `failed` | Run 2 task: A completed+persist; ép `executeTeamRunCore` throw trước khi return; assert `tasks.json` giữ A `completed` |
+| B2 | 🟡 | `runtime/task-runner.ts:667-691` | model-fallback re-resolve tính `alt` nhưng loop thoát → không bao giờ thử alt model | Chain 1 model trả 429 retryable + re-resolve ra candidate mới → assert `runChildPi` gọi lần 2 với alt |
+| B3 | 🟡 | `runtime/team-runner.ts:1400-1408` | retry re-chạy `runTeamTask` lần `maxAttempts+1` khi task *throw* | Mock `runTeamTask` luôn throw → assert gọi đúng `maxAttempts` lần, task trả `failed` |
+| B4 | 🟡 | `runtime/child-pi.ts:1461-1518` | post-exit stdio guard gắn trong handler `exit` → listener không chạy → guard no-op → risk treo | Fake ChildProcess với stdout/stderr không emit `end/close`; emit `exit`; assert `destroy` được gọi trong `hardMs` |
+| B5 | 🟡 | `runtime/child-pi.ts:985` | `AbortSignal` đã aborted trước gọi vẫn spawn child | Gọi `runChildPi` với signal đã abort → assert không spawn, kết quả `cancelled` |
+| B6 | 🟡 | `runtime/child-pi.ts:88-113` | `taskkill` (Windows) spawn không có listener `error` → uncaught crash parent | Windows: stub PATH để `taskkill` không resolve → assert log internal error, không crash |
+| B7 | 🟡 | `state/event-log.ts` (sync vs async) | 2 đường append cùng `events.jsonl` dùng lock khác nhau, cross-process không lock → trùng `seq`/torn lines | 2 process hammer `appendEventAsync`/`appendEvent` payload >4KB → assert mọi line parse, `seq` unique |
+| B8 | 🟡 | `state/mailbox.ts:475` | rotation chạy ngoài append lock → truncate mất message | Stress 2 loop `appendMailboxMessage` vượt ngưỡng rotate → assert đọc lại đúng số message |
+| B9 | 🟡 | `state/atomic-write.ts:266-276` | Windows `unlink(dest)` trước `rename` mở cửa sổ ENOENT/mất manifest | Windows: reader lặp trong lúc overwrite → assert không thấy ENOENT; giả lập rename fail sau unlink → file cũ còn nguyên |
+| B10 | 🟡 | `state/state-store.ts:565-599` | `updateRunStatus` check-then-write không lock → lost update | 2 `updateRunStatus` từ cùng base manifest → assert đúng 1 thành công, transition hợp lệ |
+| B11 | 🟡 | `worktree/worktree-manager.ts:601-620` | `sanitizeBranchPart` va chạm (vd `foo.bar` vs `foo-bar`) → 2 task dùng chung worktree | 2 task ID khác nhau 1 ký tự bị strip → assert worktree/branch khác nhau hoặc lỗi rõ ràng |
+| B12 | 🟡 | `worktree/worktree-manager.ts:410-430` | vài lệnh git (`for-each-ref`, `worktree prune`) không dùng `gitEnv()` sanitize → rò rỉ secrets | Assert child env của các call site không có `GIT_*`/secret vars |
+
+---
+
+## Ưu tiên đề xuất
+
+1. **P0 (correctness / mất dữ liệu):** C1, C4, C3, C2.
+2. **P1 (đúng đắn / rò rỉ):** C7, C5, C6, C9, B1.
+3. **P2:** C8, nhóm child-pi lifecycle (B4/B5/B6), mailbox/atomic-write Windows (B8/B9).
+
+**Fix đầu tiên đã chọn: C1 (CRLF conflict false-negative).** Phác thảo: trong `scanFileForConflictsSync`/`scanConflictLines`, strip trailing `\r` mỗi dòng trước khi so khớp marker/separator (mirror logic dòng 429), và giữ `\r` khi ghi lại để round-trip byte-accurate; thêm unit test CRLF + giữ test LF cũ pass; chạy `npm run typecheck` + `test/unit/conflict-detect.test.ts` + `delta-conflict.test.ts`.
+
+> Nhóm B: theo quyết định 2026-07, sẽ **dựng test repro** để xác nhận trước khi kết luận/sửa. Chưa treat như confirmed.

package/docs/REVIEW-FINDINGS-2026-07.md

@@ -0,0 +1,125 @@
+# pi-crew — Review & Upgrade Findings (2026-07)
+
+Tổng hợp review toàn bộ project và các cơ hội nâng cấp/cải thiện, kèm **bằng chứng verification thực tế** (đã chạy lệnh, không suy đoán).
+
+- Phiên bản đánh giá: **v0.9.28**
+- Môi trường kiểm chứng: Node **v22.14.0**, npm **10.9.2**, Windows (win32 10.0.22631)
+- Quy mô: **453** file nguồn (`src/**/*.ts`, ~**93.206** dòng), **652** file test
+- Quy ước mức độ: 🔴 Cao · 🟡 Trung bình · ⚪ Thấp/Hygiene
+- Quy ước effort: S (<0.5 ngày) · M (0.5–2 ngày) · L (>2 ngày)
+
+> **Review bộ core** (scheduler, child-process lifecycle, state durability/concurrency, worktree, conflict detection): xem `docs/REVIEW-FINDINGS-2026-07-CORE.md` — 9 finding đã verify trực tiếp + 12 finding cần repro.
+
+## Baseline health (đã verify)
+
+| Kiểm tra | Lệnh | Kết quả | Bằng chứng |
+|----------|------|---------|------------|
+| Typecheck | `npm run typecheck` | ✅ PASS (16.7s) | `tsc --noEmit` OK + `strip-types import ok` |
+| Unit test (mẫu) | `test/unit/{token-counter,conflict-detect,model-fallback}.test.ts` | ✅ 80/80 pass (0.67s) | node:test summary `# fail 0` |
+| Unit suite (full) | `npm run test:unit` | ⚠️ chậm — vượt 420s cục bộ (timeout) | ~5800 test, budget CI 15 phút |
+| Lint | `npm run lint` | ❌ FAIL — 6 lỗi (FIXABLE) | `assist/source/organizeImports` |
+| Deps | `npm outdated` | ⚠️ 5 gói lỗi thời | xem F5/F6 |
+
+## Bảng tổng hợp findings
+
+| ID | Vấn đề | Mức | Effort | Khu vực |
+|----|--------|-----|--------|---------|
+| F1 | `npm run lint`/`npm run ci` fail — 6 lỗi import-sort | 🟡 | S | Chất lượng |
+| F2 | `.gitignore` có dòng nối sai + trùng lặp | 🟡 | S | Hygiene/Git |
+| F3 | CI không gate `lint`/`format`/`check:*` (khác local `ci`) | 🟡 | S | CI |
+| F4 | Artifact bug: thư mục `undefined/.pi/teams/...` | 🟡 | M | Runtime/paths |
+| F5 | Deps minor an toàn cần nâng (biome/tsx/esbuild) | ⚪ | S | Deps |
+| F6 | Deps major cần plan (diff 5→9, TypeScript 7) | ⚪ | M-L | Deps |
+| F7 | Unit suite chậm (>7 phút cục bộ) — DX | ⚪ | M | Test/DX |
+| F8 | API `@deprecated` còn tồn tại — dọn ở bản major | ⚪ | S | Maintainability |
+| F9 | Thư mục rác ở root (đã dọn 2026-07) | ⚪ | S | Hygiene |
+
+---
+
+## 🟡 Mức Trung bình
+
+### F1 — `npm run lint` fail với 6 lỗi import-sort
+
+**Bằng chứng:** `npm run lint` → exit 1, `Found 6 errors`, tất cả gắn nhãn `FIXABLE` (`assist/source/organizeImports`).
+
+File liên quan:
+- `src/extension/crew-vibes/index.ts`
+- `src/prompt/prompt-runtime.ts`
+- `src/runtime/cross-extension-rpc.ts`
+- `test/unit/api-key-scoping.test.ts`
+- `test/unit/rpc-hmac-auth.test.ts`
+- `test/unit/token-counter.test.ts`
+
+**Tác động:** `npm run ci` (pipeline "full CI" ghi trong CLAUDE.md) fail cục bộ ở bước `lint`. CI trên GitHub không bắt (xem F3) nên lỗi tồn tại âm thầm.
+
+**Giải pháp:** `biome check --write` (auto-fix reorder import). **Verify:** `npm run lint` → 0 errors.
+
+### F2 — `.gitignore` có dòng nối sai + trùng lặp
+
+**Bằng chứng:** dòng `!.crew/graphs/.gitkeepfallow-audit-report/` — negation `!.crew/graphs/.gitkeep` bị nối nhầm với `fallow-audit-report/` (nghi do merge/paste). Hệ quả: cả 2 pattern đều không hoạt động đúng. Ngoài ra có trùng lặp: `dist/` (x2), `.crew/worktrees/` (x2), `/.crew/` vs `/.crew`.
+
+**Giải pháp:** tách lại thành 2 dòng đúng (`!.crew/graphs/.gitkeep` và `fallow-audit-report/`) + gộp dòng trùng. **Verify:** `git check-ignore -v .crew/graphs/.gitkeep` và `git check-ignore -v fallow-audit-report/x`.
+
+### F3 — CI không gate lint/format/check
+
+**Bằng chứng:** `.github/workflows/ci.yml` job `test` chỉ chạy: `npm run typecheck`, `npm test`, `npm pack --dry-run`. KHÔNG có `npm run lint`, `format:check`, hay `check:*`. Local `npm run ci` thì có → drift (F1 minh chứng: lint đỏ nhưng CI vẫn xanh).
+
+**Giải pháp:** thêm 1 job `quality` chạy `npm run lint && npm run format:check` (hoặc gọi `npm run ci` trực tiếp). **Verify:** push nhánh → xem GitHub Actions.
+
+### F4 — Artifact bug: thư mục `undefined/.pi/teams/...`
+
+**Bằng chứng:** tồn tại thư mục thật ở root: `undefined/.pi/teams/state/runs` (layout `.pi/teams` legacy). Một code path đã resolve base root thành chuỗi `"undefined"` (nhiều khả năng `path.join(String(rootUndefined), ".pi", "teams")` hoặc template literal `${cwd}` với `cwd` undefined). Là dữ liệu untracked (không thuộc git, không match `.gitignore`).
+
+**Giải pháp:**
+1. Dọn thư mục (đã thực hiện 2026-07, xem F9).
+2. Root-cause + guard: chặn ghi state khi root resolve về undefined/empty (throw hoặc fallback rõ ràng) tại các điểm resolve crewRoot trong `src/utils/paths.ts` / `src/state/crew-init.ts`.
+
+**Verify:** thêm unit test cho path-resolver khi input undefined → không tạo path `"undefined"`.
+
+---
+
+## ⚪ Mức Thấp / Hygiene / Deps
+
+### F5 — Deps minor an toàn
+
+**Bằng chứng (`npm outdated`):**
+
+| Gói | Current | Latest | Loại |
+|-----|---------|--------|------|
+| `@biomejs/biome` | 2.4.15 | 2.5.3 | minor |
+| `tsx` | 4.22.3 | 4.23.0 | minor |
+| `esbuild` | 0.28.0 | 0.28.1 | patch |
+
+Lưu ý: `@earendil-works/pi-*` current 0.77.0 > "latest" 0.74.2 → đang dùng kênh pre-release, **không** hạ.
+
+**Giải pháp:** nâng 3 gói trên. **Verify:** `npm run typecheck && npm run lint && npm run test:unit (mẫu)`.
+
+### F6 — Deps major (cần story riêng)
+
+`diff` 5.2.2 → 9.0.0 (đổi ESM/API, ảnh hưởng `conflict-detect`), `typescript` 5.9.3 → 7.0.2 (native compiler, còn sớm cho production typecheck). → tách story: `docs/stories/US-DEPS-major-upgrade.md`.
+
+### F7 — Unit suite chậm (DX)
+
+**Bằng chứng:** `npm run test:unit` vượt 420s cục bộ. `scripts/test-runner.mjs` ghi chú ~5800 test, budget 15 phút trên Windows CI. Có sẵn `npm run test:changed` nhưng không phải mặc định vòng dev.
+
+**Giải pháp (đề xuất):** sharding hoặc khuyến nghị `test:changed` cho vòng dev; giữ full suite cho CI.
+
+### F8 — API `@deprecated` còn tồn tại
+
+**Bằng chứng:** `src/state/event-log.ts` (sync `appendEvent`), `src/ui/tool-render.ts`, `src/runtime/stale-reconciler.ts` (legacy error builder), `src/runtime/team-runner.ts` (`mergeTaskUpdates` cũ), `src/extension/pi-api.ts` (drift detector removed). → gỡ ở bản major kế tiếp sau khi xác nhận không còn caller ngoài test-compat.
+
+### F9 — Dọn thư mục rác ở root (ĐÃ THỰC HIỆN 2026-07)
+
+Đã xóa (được người dùng ủy quyền):
+- `undefined/` — artifact bug (F4)
+- `tmp-glyph-previews/` — untracked (2 entries)
+- `.test-artifacts-tmp/`, `.test-artifacts-tmp2/` — ignored, do test bỏ lại (3 entries mỗi cái)
+
+---
+
+## Ưu tiên đề xuất
+
+1. **P0 (quick win):** F1 (fix lint) + F2 (fix .gitignore).
+2. **P1:** F3 (CI gate lint) + F4 (root-cause bug undefined).
+3. **P2:** F5 (minor deps) → F7 (test DX).
+4. **Backlog:** F6 (major deps, story riêng) + F8 (dọn deprecated ở major).

package/docs/bugs/bug-quota-display-truncation.md

@@ -0,0 +1,223 @@
+# Bug: Provider quota display truncated to "W..." during sub-agent runs
+
+**Status:** FIXED via custom footer (`ctx.ui.setFooter`). See "Resolution" below.
+**Severity:** Cosmetic
+**Affected:** `src/extension/crew-vibes/` (provider quota renderer)
+**Reporter:** user (live observation, 2026-07-09)
+
+> Correction: the earlier "UNFIXABLE IN EXTENSION LAYER / WONTFIX" verdict was
+> wrong on two counts. (1) The `spreadLine` U+00A0 full-width padding (from
+> commit `f0baee9`) was described as "reverted attempt 1" but was in fact still
+> ACTIVE and was the direct cause — it padded our row to the full terminal width
+> using `process.stdout.columns` (which differs from pi's real render width),
+> guaranteeing overflow and right-truncation of the quota. (2) Option A (custom
+> footer) was never actually attempted; it is viable and is what the fix uses.
+
+---
+
+## Symptom
+
+When pi-crew spawns sub-agents, the provider quota text in pi's footer
+status bar is truncated. User reported seeing:
+
+```
+⚙ lr • MiniMax-M3 75k o Orbit                                                                             Minimax 5h ▬▬▬ 29% 1h6m W...
+```
+
+The `Wk ▬▬▬▬▬▬▬▬ 19% 1d4h` segment (weekly quota bar + percent + reset) is
+chopped to just `W` followed by the dim ellipsis `...`.
+
+## Root cause
+
+`@earendil-works/pi-coding-agent` (pi) joins ALL extension statuses into
+ONE footer line via `ctx.ui.setStatus()`, sorted alphabetically by key,
+then calls `truncateToWidth(joined, width, "...")` if joined width
+exceeds terminal width.
+
+Source: `dist/modes/interactive/components/footer.js` lines 213–222:
+
+```js
+const sortedStatuses = Array.from(extensionStatuses.entries())
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([, text]) => sanitizeStatusText(text));
+const statusLine = sortedStatuses.join(" ");
+lines.push(truncateToWidth(statusLine, width, theme.fg("dim", "...")));
+```
+
+Concretely, the joined line becomes:
+
+```
+pi-crew  + " " + pi-crew-bar  + " " + pi-crew-quota
+(widget)    (capacity)          (provider quota)
+```
+
+When sub-agents spawn, `pi-crew` widget text (worker counts, queue,
+model name — `statusSummary()` in `src/ui/widget/widget-model.ts`)
+grows from ~10 chars to ~50-80 chars. The joined line exceeds terminal
+width, and `truncateToWidth` chops the RIGHT side first — which is
+where our provider quota lives. Result: weekly bar lost.
+
+## Why naive fixes don't work
+
+The extension knows only its OWN status text, not other extensions'
+status texts. Several "obvious" fixes were attempted (all reverted):
+
+### Attempt 1 — Right-align quota with U+00A0 padding
+
+Prepend non-breaking spaces (U+00A0, which `sanitizeStatusText` does
+not collapse) to push quota to the right edge of `process.stdout.columns`.
+
+```ts
+const cols = process.stdout.columns || 120;
+const pad = Math.max(0, cols - quotaWidth - capWidth - 1);
+const padded = capText + "\u00A0".repeat(pad) + quotaText;
+setCapacityStatus(ctx, config, padded);
+```
+
+**Why it fails:** pad accounts for our row's own capacity+quota width
+but NOT for `pi-crew` widget text or `pi-sub-bar` text that prepends
+ours. When those grow during sub-agent spawn, joined line exceeds
+cols and pi's `truncateToWidth` chops quota anyway.
+
+### Attempt 2 — Subtract capacity width dynamically
+
+Cache `lastCapacityText` so we know our own row's capacity width when
+padding quota:
+
+```ts
+const capWidth = lastCapacityText ? visibleLen(lastCapacityText) : 0;
+const pad = Math.max(0, cols - quotaWidth - capWidth - 1);
+```
+
+**Why it fails:** still doesn't account for `pi-crew` widget width or
+other extensions' widths. Same overflow problem.
+
+### Attempt 3 — Reserve buffer for other extensions
+
+```ts
+const otherReserve = Math.floor(cols * 0.5);
+const pad = Math.max(0, cols - quotaWidth - capWidth - 1 - otherReserve);
+```
+
+**Why it fails:** heuristic, not exact. 50% may be too much (quota
+gets pushed left and looks unbalanced) or too little (still overflows).
+Padding is not "dynamic" in the sense of reacting to actual other
+status widths.
+
+### Attempt 4 — Split into widget via setWidget("...", [cap, quota])
+
+`setWidget()` with `placement: "belowEditor"` renders a Container with
+one Text component per array entry → 2 separate lines below editor,
+not subject to joined status truncation.
+
+**Why it fails:** moves the display out of the footer status bar to
+below the editor. User wanted it in the footer (status bar), not in
+a new visual zone.
+
+## Viable fixes (none attempted; documenting for future)
+
+### A. Custom footer via `setFooter(factory)`
+
+Pi exposes `ctx.ui.setFooter((tui, theme, footerData) => Component)` —
+extensions can replace the entire footer. The factory receives
+`footerData.getExtensionStatuses()` so we still see other extensions'
+statuses.
+
+Implementation outline:
+1. Build a custom `FooterComponent` that renders cwd + stats + our
+   2 lines (capacity + quota right-aligned).
+2. Call `ctx.ui.setFooter(factory)` on `session_start`.
+3. On `session_shutdown`, call `ctx.ui.setFooter(undefined)` to restore
+   pi's built-in footer.
+
+Cost: ~150 LoC + need to mirror pi's built-in footer logic (cwd,
+branch, token stats, model, etc.) so we don't lose any info.
+
+### B. Patch pi-coding-agent upstream
+
+Request that pi support multi-line extension status — e.g., add a
+`setStatus(key, lines: string[])` overload that puts each entry on its
+own line, OR a `setStatusLine(position, key, text)` that allows
+pinning a status to line 1 vs line 2.
+
+Cost: requires upstream PR + waiting for new pi release.
+
+### C. Shorten quota to always fit
+
+Drop the weekly bar entirely (or shrink to 1-2 chars). Quota becomes
+`Minimax 5h 29%` (~15 chars). Even if `pi-crew` widget text is 80 chars
+and capacity is 22 chars, total = 80+1+22+1+15 = 119, fits in 120 cols
+usually.
+
+Cost: loses reset timers and weekly bar visualization. User originally
+wanted the bars.
+
+## Why the 5 prior attempts all failed (same root cause)
+
+All five fought the truncation from INSIDE `setStatus`, where an extension
+cannot see (a) the `pi-crew` widget status width that grows during sub-agent
+runs, (b) other extensions' widths, (c) pi's real render width, and where pi
+always right-truncates the joined line:
+
+- `81859e6` — split into `pi-crew-quota` key. pi joins all keys onto one line;
+  quota still rightmost → still chopped. (Misdiagnosed as slot-overwrite.)
+- `a74e453` — NBSP pad by `cols - quotaWidth - 1`. Ignores capacity + widget
+  widths → overflow → chop.
+- `a9eb30e` — NBSP pad by `cols - quotaWidth - capWidth - 1`. Still ignores the
+  widget width and other extensions → overflow.
+- `900737c` — `setWidget(belowEditor)` 2-line. Works (no truncation) but sits
+  below the editor, not in the footer. Rejected.
+- `5e56b63` — one status line + NBSP pad (`process.stdout.columns`). Same flaw
+  as #2/#3, plus a width source that disagrees with pi's actual render width.
+
+## Resolution (implemented)
+
+Definitive fix = option A, **custom footer via `ctx.ui.setFooter(factory)`** —
+the one approach none of the 5 attempts tried. It sidesteps every failure mode
+above because the footer `Component`'s `render(width)` receives pi's REAL render
+width and we own the line layout, so the meters get their own line(s) that the
+join can never truncate.
+
+- `src/extension/crew-vibes/footer.ts` — `CrewVibesFooter implements Component`.
+  Reproduces pi's built-in footer lines (pwd/branch/session; token stats + cost
+  + context% + model + thinking) from `ctx.sessionManager`/`ctx.model`/
+  `ctx.getContextUsage()`/`footerData`, keeps other extensions' statuses on the
+  joined line (still truncated, like pi), and renders **capacity + quota on a
+  dedicated line** using the real width. When the terminal is too narrow, the
+  meters wrap to two lines (capacity above, quota right-aligned below).
+- `src/extension/crew-vibes/index.ts` — installs the footer on `session_start`
+  (and re-install/remove in `applyConfig`), restores pi's built-in footer with
+  `setFooter(undefined)` on disable/`session_shutdown`, drops the `spreadLine`
+  padding, stores the raw provider-usage snapshot (rendered by the footer), and
+  tracks thinking level via the `thinking_level_select` event.
+- `src/ui/pi-ui-compat.ts` — added a guarded `setFooter()` wrapper (no-op on
+  hosts that predate the API).
+
+Accepted fidelity trade-offs (pi does not expose these to extensions):
+- The `(auto)` compaction indicator is always shown (matches pi's default);
+  the toggle state is not observable.
+- Thinking level comes from `thinking_level_select`; before the first switch it
+  shows the default ("off").
+
+Proof: `test/unit/crew-vibes.test.ts` adds two tests — quota stays fully visible
+while an overflowing status line is truncated, and the meters wrap to two lines
+on a narrow terminal.
+
+## How to revert fully
+
+If you want to wipe all 5 reverted commits from history:
+
+```bash
+git revert f74adae 7588b26 0f0905d a61d5de dced96a  # the 5 reverts above
+```
+
+Or just leave them — they're labeled "Revert ..." so it's clear what
+they undo.
+
+## References
+
+- pi footer rendering: `/home/bom/.nvm/versions/node/v22.23.1/lib/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/components/footer.js:213-222`
+- pi truncateToWidth: `node_modules/@earendil-works/pi-tui/dist/utils.js:821`
+- pi-crew widget status source: `src/ui/widget/widget-model.ts:77-99` (`statusSummary()`)
+- crew-vibes provider rendering: `src/extension/crew-vibes/render.ts:158-194` (`renderProviderUsage()`)
+- crew-vibes quota publish: `src/extension/crew-vibes/index.ts` (`publishProviderQuota()`)

package/docs/stories/README.md

@@ -13,7 +13,9 @@ Story-sized work packets for pi-crew development.
 
 ## Active Stories
 
-No active stories. Pick from backlog or create new ones via feature intake.
+| ID | Title | Lane | Status |
+|----|-------|------|--------|
+| US-DEPS-major-upgrade | Nâng cấp deps major (diff 5→9, TypeScript 7) | normal | planned |
 
 ## Completed Stories (from review rounds)
 

package/docs/stories/US-DEPS-major-upgrade.md

@@ -0,0 +1,62 @@
+# US-DEPS-major-upgrade — Nâng cấp dependencies major
+
+- **Lane:** normal (Dependency) — có thể tách thành 2 patch độc lập
+- **Status:** planned
+- **Nguồn:** `docs/REVIEW-FINDINGS-2026-07.md` (F6)
+- **Ngày tạo:** 2026-07-09
+
+## Overview
+
+`npm outdated` (Node v22.14.0, v0.9.28) cho thấy 2 gói lệch **major**:
+
+| Gói | Current | Latest | Rủi ro |
+|-----|---------|--------|--------|
+| `diff` | 5.2.2 | 9.0.0 | API/ESM breaking |
+| `typescript` | 5.9.3 | 7.0.2 | compiler mới (native) |
+
+Cả hai KHÔNG gộp chung; mỗi cái là một patch riêng có validation độc lập.
+
+## Phần A — `diff` 5 → 9
+
+### Design
+- `diff` v6+ chuyển sang ESM-first và tinh chỉnh chữ ký hàm (`structuredPatch`, `diffLines`, `applyPatch`...). Cần rà soát mọi import.
+- Điểm chạm chính: `src/utils/conflict-detect.ts` (và bất kỳ nơi nào import `diff`).
+
+### Exec plan
+1. `git grep -n "from \"diff\"" src test` để liệt kê toàn bộ callsite.
+2. Đọc CHANGELOG của `diff` v6/v7/v8/v9, lập bảng breaking → mapping.
+3. `npm i diff@9`, sửa callsite theo API mới.
+4. Chạy `npm run typecheck` + test liên quan (`conflict-detect.test.ts`, `delta-conflict.test.ts`).
+
+### Validation
+- `npm run typecheck` → PASS
+- `node scripts/test-runner.mjs ... test/unit/conflict-detect.test.ts test/unit/delta-conflict.test.ts` → pass
+- `npm run test:unit` full → không hồi quy
+
+## Phần B — `typescript` 5.9 → 7.0
+
+### Design
+- TS 7.0 là compiler native (tsgo). Cần đánh giá:
+  - Tương thích flags trong `tsconfig.json` (`allowImportingTsExtensions`, `NodeNext`, `strict`).
+  - Tương thích với `tsx`/strip-types runtime path (index.ts import qua `--experimental-strip-types`).
+  - Khả năng phát sinh lỗi type mới do compiler chặt hơn.
+- Rủi ro cao hơn A; cân nhắc chờ hệ sinh thái ổn định (còn sớm giữa 2026).
+
+### Exec plan
+1. Thử trên nhánh riêng: `npm i -D typescript@7`.
+2. `npm run typecheck` — thu thập toàn bộ lỗi mới, phân loại.
+3. Nếu lỗi ít/định vị được → sửa; nếu diện rộng → hoãn, ghi decision.
+4. Xác nhận `tsx` + strip-types vẫn chạy (`node --experimental-strip-types -e "await import('./index.ts')"`).
+
+### Validation
+- `npm run typecheck` → PASS
+- `npm run test:unit` → không hồi quy
+- Cold-start bench (`npm run bench`) → không xấu đi
+
+## Rollback
+- Mỗi phần là 1 commit độc lập; revert commit tương ứng nếu hồi quy.
+- Giữ `package-lock.json` cũ để pin lại nhanh.
+
+## Ghi chú quyết định
+- Ưu tiên Phần A trước (rủi ro thấp hơn, phạm vi hẹp).
+- Phần B nên có `docs/decisions/` entry trước khi merge (thay đổi toolchain cốt lõi).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.27",
+  "version": "0.9.29",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",
@@ -103,7 +103,7 @@
     "@earendil-works/pi-tui": "*"
   },
   "dependencies": {
-    "@sinclair/typebox": "^0.34.49",
+    "@sinclair/typebox": "^0.34.50",
     "acorn": "^8.17.0",
     "ajv": "^8.20.0",
     "cli-highlight": "^2.1.11",
@@ -112,13 +112,13 @@
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.15",
+    "@biomejs/biome": "^2.5.3",
     "@earendil-works/pi-agent-core": "^0.77.0",
     "@earendil-works/pi-ai": "^0.77.0",
     "@earendil-works/pi-coding-agent": "^0.77.0",
     "@earendil-works/pi-tui": "^0.77.0",
     "esbuild": "^0.28.1",
-    "tsx": "^4.22.3",
+    "tsx": "^4.23.0",
     "typescript": "^5.9.3"
   },
   "peerDependenciesMeta": {

package/src/agents/agent-config.ts

@@ -83,6 +83,8 @@ export interface AgentConfig {
 	contextMode?: "fresh" | "fork";
 	/** Maximum turns for this agent. Overrides runtime config if set. */
 	maxTurns?: number;
+	/** Cap on output tokens per API call. Set via PI_CREW_MAX_OUTPUT_TOKENS env in child. */
+	maxTokens?: number;
 	/** Effort level for this agent. Controls how much work the agent puts in. */
 	effort?: "low" | "medium" | "high";
 	/** Tools to explicitly forbid for this agent. Takes precedence over allowedTools. */

package/src/agents/discover-agents.ts

@@ -431,6 +431,10 @@ function parseAgentFile(filePath: string, source: ResourceSource): AgentConfig |
 				const n = Number.parseInt(frontmatter.maxTurns, 10);
 				return Number.isFinite(n) && n > 0 ? n : undefined;
 			})(),
+			maxTokens: (() => {
+				const n = Number.parseInt(frontmatter.maxTokens, 10);
+				return Number.isFinite(n) && n > 0 ? n : undefined;
+			})(),
 			effort:
 				frontmatter.effort === "low" || frontmatter.effort === "medium" || frontmatter.effort === "high"
 					? frontmatter.effort

package/src/config/config.ts

@@ -741,6 +741,10 @@ function parseWorktreeConfig(value: unknown): CrewWorktreeConfig | undefined {
 		setupHook: setupHook ? setupHook : undefined,
 		setupHookTimeoutMs: parsePositiveInteger(obj.setupHookTimeoutMs, 300_000),
 		linkNodeModules: parseWithSchema(Type.Boolean(), obj.linkNodeModules),
+		// C6: seedPaths was declared in the type + schema but never parsed here, so
+		// loadedConfig.config.worktree?.seedPaths was always undefined -> the global
+		// worktree seed overlay (worktree-manager.ts) silently never applied.
+		seedPaths: parseStringList(obj.seedPaths),
 	};
 	return Object.values(worktree).some((entry) => entry !== undefined) ? worktree : undefined;
 }

package/src/extension/crew-vibes/config.ts

@@ -78,7 +78,7 @@ export const DEFAULT_CONFIG: CrewVibesConfig = {
 		labels: ["Orbit", "Cruise", "Warp", "Black Hole", "Supernova", "Big Bang"],
 		icons: ["", "", "", "", "", ""],
 		providerUsage: true,
-		providerRefreshMs: 300000,
+		providerRefreshMs: 120000,
 	},
 };