pi-crew 0.9.51 → 0.9.52

package/docs/REVIEW-FINDINGS-2026-06

@@ -1,357 +0,0 @@
-# pi-crew — Findings & Remediation (2026-06)
-
-Tổng hợp chi tiết các **Vấn đề & Rủi ro** từ 3 lượt đánh giá (tổng quan dự án, subagent/quản-lý-context, hiệu năng) kèm **giải pháp xử lý chi tiết và tối ưu**.
-
-- Phiên bản đánh giá: v0.9.16
-- Môi trường kiểm chứng: Node v22.14.0, Windows; `npm ci` + `tsc --noEmit` (PASS) + `test:unit` (5747/5778 pass) + `npm run bench`.
-- 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)
-
-## Bảng tổng hợp
-
-| ID | Vấn đề | Mức | Effort | Khu vực |
-|----|--------|-----|--------|---------|
-| H1 | 4 lỗ hổng "high" trong dependencies | 🔴 | M | Bảo mật/deps |
-| H2 | Cold-start nặng — bundle ESM chưa được bật | 🔴 | M | Hiệu năng |
-| H3 | `register()` p95 ~461ms (register.ts phình to) | 🔴 | M-L | Hiệu năng |
-| M1 | 7 unit test fail trên Windows (test phụ thuộc shell) | 🟡 | S-M | Test/CI |
-| M2 | Biome cấu hình nhưng không enforce trong CI | 🟡 | S | Chất lượng |
-| M3 | iterative-retrieval không được nối + scoring thô sơ | 🟡 | M | Context |
-| M4 | `contextMode: fork` là metadata no-op | 🟡 | M | Context |
-| M5 | Phối hợp cross-worker chỉ ở mức prompt, không enforce | 🟡 | L | Runtime |
-| M6 | Warm pool là stub — mỗi task trả full cold-start | 🟡 | L | Hiệu năng |
-| M7 | `appendEventBuffered` không caller + chưa có bench chứng minh | 🟡 | S-M | Hiệu năng |
-| M8 | Baseline bench không tái lập + không nằm trong CI | 🟡 | M | Hiệu năng/CI |
-| L1 | State runtime bị commit vào git (14 file `.crew/`) | ⚪ | S | Hygiene |
-| L2 | File orchestrator quá lớn | ⚪ | L | Maintainability |
-| L3 | Doc sprawl (~60 file, nhiều báo cáo one-off) | ⚪ | S | Docs |
-| L4 | Prompt bloat ở node fan-in (dependencies không prune) | ⚪ | M | Context |
-| L5 | `loadMode: "lean"` chỉ là gợi ý prompt | ⚪ | S | Context |
-| L6 | Ngưỡng truncation trên mẫu nhỏ + token heuristic char/4 | ⚪ | S | Context |
-
----
-
-## 🔴 Mức Cao
-
-### H1 — 4 lỗ hổng "high" trong dependencies
-
-**Bằng chứng:** `npm audit` → 5 lỗ hổng (1 low, 4 high).
-- `@earendil-works/pi-coding-agent <=0.79.7`: XSS HTML export (GHSA-7v5m-pr3q-6453), load project-local extension không duyệt (GHSA-mqxh-6gq7-558m), priv-esc temp path trên Linux dùng chung (GHSA-jfgx-wxx8-mp94), race `auth.json` lộ credential (GHSA-r95r-rj6r-c39x).
-- Transitive: `undici 8.0.0–8.4.1`, `protobufjs <=7.6.2`, `ws 8.0.0–8.20.1`.
-- `esbuild 0.27.3–0.28.0` (dev): arbitrary file read khi chạy dev server trên Windows.
-
-**Nguyên nhân gốc:** đây là **peer/dev-dependency** (host Pi cung cấp lúc runtime; không bundle vào package publish). Nhưng pi-coding-agent là **runtime host** nên người dùng cuối vẫn chịu rủi ro.
-
-**Tác động:** không trực tiếp trong code pi-crew, nhưng đụng tới host runtime mà extension chạy bên trong → cần theo dõi, không "tự nhận trách nhiệm fix" code bên thứ ba.
-
-**Giải pháp chi tiết (tối ưu):**
-1. **Tách rủi ro do mình kiểm soát vs host:**
-   - Nâng dev-only ngay: `npm i -D esbuild@^0.28.1` (file-read chỉ ảnh hưởng dev server, low effort).
-   - `undici`/`protobufjs`/`ws` đến từ pi-coding-agent → không tự pin được, chỉ giải quyết qua việc nâng peer.
-2. **Nâng peer range có kiểm soát:** đổi `peerDependencies`/`devDependencies` `@earendil-works/*` từ `^0.77.0` sang range bao gồm `>=0.80.2` (bản đã vá), nhưng **giữ `peerDependenciesMeta.optional=true`** để không ép người dùng. Chạy lại bộ test + smoke (`npm run smoke:pi`) vì 0.80.x là breaking với 0.77.
-3. **Thêm gate CI cho deps:** thêm step `npm audit --audit-level=high --omit=dev` (chỉ fail trên prod-deps high) để không bị nhiễu bởi dev-only. pi-crew prod-deps (`typebox/acorn/ajv/cli-highlight/diff/jiti/yaml`) hiện sạch → gate này xanh và bắt được regression thật sau này.
-4. **Tài liệu hóa** trong `SECURITY-ISSUES.md`: ghi rõ "các advisory này thuộc host pi-coding-agent, đã vá ở 0.80.2; pi-crew khuyến nghị host >=0.80.2".
-
-**Rủi ro fix:** nâng peer 0.77→0.80 là breaking ở API host → bắt buộc chạy full `npm run ci` + `smoke:pi` trên 3 OS trước khi release.
-
----
-
-### H2 — Cold-start nặng: bundle ESM đã build nhưng chưa được bật
-
-**Bằng chứng:**
-- `package.json#pi.extensions = ["./index.ts"]` → Pi nạp **TS nguồn** qua strip-types/jiti, parse từng file.
-- `scripts/build-bundle.mjs` đã tạo `dist/index.mjs` (~1.4MB) + sourcemap, peer-deps external. Comment trong script tự nói "ready to flip".
-- `package.json#files` **không có** `dist/` → kể cả flip cũng chưa publish bundle.
-- Bench: `register-startup.import.p95` là metric nặng nhất; báo cáo perf dự phóng flip → ≤250ms.
-
-**Nguyên nhân gốc:** bước cuối (flip entrypoint + đưa dist vào publish + prebuild) chưa làm; ADR 0006 dừng ở "Proposed/ready".
-
-**Giải pháp chi tiết (tối ưu — dual-ship an toàn):**
-1. **Prebuild khi publish:** thêm script
-   ```jsonc
-   "prepublishOnly": "npm run build:bundle",
-   "prepack": "npm run build:bundle"
-   ```
-2. **Đưa bundle vào package:** thêm `"dist/"` vào `package.json#files`.
-3. **Flip entrypoint có fallback:** trỏ `pi.extensions` sang bundle khi có, giữ TS làm fallback khi chạy từ clone chưa build. Cách an toàn nhất là một entry mỏng:
-   ```jsonc
-   "pi": { "extensions": ["./dist/index.mjs"], "skills": ["./skills"] }
-   ```
-   và **giữ `index.ts`** cho dev (chạy `tsc`/test từ source). Nếu Pi loader hỗ trợ `exports`-resolution, có thể dùng conditional exports để ưu tiên dist và fallback ts.
-4. **Smoke 3-OS bắt buộc** (`scripts/release-smoke.mjs` + `smoke:pi`) trước khi merge — vì entrypoint là bề mặt nạp extension.
-5. **Đo lại** `npm run bench` sau flip, cập nhật `baseline.json` theo runner (xem M8).
-
-**Lợi ích:** giảm cold-start import p95 mạnh nhất trong tất cả đòn bẩy (dự phóng −50%).
-
-**Rủi ro fix:** bundle sai external → kéo nhầm peer-deps; mitigate bằng `external` đã cấu hình sẵn + smoke import test (`node -e "import('./dist/index.mjs')"`).
-
----
-
-### H3 — `register()` p95 ~461ms (register.ts 2195 dòng, nhiều static import)
-
-**Bằng chứng:** bench hiện tại `register-startup.register.p95 = 461ms` (baseline cũ 24ms; chênh vượt mức nhiễu môi trường). `src/extension/register.ts` = 2195 dòng, đầu file import tĩnh hàng chục module (notification-router, run-snapshot-cache, scheduler, observability, powerbar, render-scheduler...).
-
-**Nguyên nhân gốc:** nhiều khởi tạo + import được thực thi tại thời điểm `register()` dù phần lớn người dùng không mở dashboard/observability/powerbar trong session đó.
-
-**Giải pháp chi tiết (tối ưu):**
-1. **Profile chính xác trước khi cắt:** `npm run profile:startup` → mở `.cpuprofile` trong Chrome DevTools, xác định top frames trong `register()`.
-2. **Đẩy khởi tạo sang on-demand** (theo đúng pattern LAZY đã có):
-   - Observability (`MetricRegistry`, metric-sink, event-to-metric, OTLP): chỉ khởi tạo khi `observability.enabled` hoặc khi `/team-metrics` được gọi lần đầu.
-   - Dashboard/sidebar/powerbar: khởi tạo lười khi user mở overlay/segment đầu tiên (LiveRunSidebar đã lazy — mở rộng cho run-snapshot-cache, render-scheduler).
-   - Scheduler/heartbeat-watcher: chỉ start khi có run active đầu tiên, không phải tại register.
-3. **Tách register thành các "feature installer" nhỏ** (xem L2) gọi sau khi nhận tín hiệu cần thiết, để `register()` chỉ làm phần tối thiểu: đăng ký tool + slash command (rẻ) và hoãn phần UI/telemetry.
-4. **Thêm bench guard riêng cho register** (`bench:check`) sau khi cải thiện để chống tái phình.
-
-**Rủi ro fix:** lười hóa khởi tạo có thể đổi thứ tự side-effect (vd widget không hiện ngay). Mitigate: giữ một "warm-up" idle-callback khởi tạo nền sau first paint (đã có `runtime-warmup.ts`/`startRuntimeWarmup` — tận dụng nó).
-
----
-
-## 🟡 Mức Trung bình
-
-### M1 — 7 unit test fail trên Windows (test phụ thuộc shell POSIX)
-
-**Bằng chứng (`test:unit`, 7 fail):**
-- `benchmark.test.ts`: `runBenchmarkSuite computes total counts` (judge `echo ok`).
-- `verification-gates.test.ts` x3: `runPhaseGates ...` (lệnh `echo 'hello'`, `exit 1`).
-- `verification-env-sanitize.test.ts` x2 (secret env qua subprocess shell).
-- `issue-29-pi-paths.test.ts`: subprocess exit code.
-Tất cả dùng cú pháp shell POSIX (`echo 'x'`, `exit 1`) chạy trên `cmd.exe` → behavior khác → assertion sai (vd length 1 thay vì 2).
-
-**Nguyên nhân gốc:** test giả định shell POSIX, không guard `win32`, trong khi repo đã có tiền lệ skip test Unix-only (commit `a75be5e`, `4089b0e`).
-
-**Tác động:** `npm test` đỏ trên máy dev Windows dù logic lõi đúng → giảm tín hiệu, dễ "quen với màu đỏ".
-
-**Giải pháp chi tiết (tối ưu — cross-platform thật, không chỉ skip):**
-1. **Thay command fixtures bằng lệnh cross-platform** thay vì skip, để vẫn có độ phủ trên Windows:
-   - `echo 'hello'` → dùng `node -e "process.stdout.write('hello')"` (chạy giống nhau mọi OS).
-   - `exit 1` → `node -e "process.exit(1)"`.
-   Cách này giữ assertion length/status đúng trên cả 3 OS.
-2. **Với test thực sự Unix-only** (vd SIGKILL-timer), giữ guard `{ skip: process.platform === 'win32' }` kèm comment lý do (đồng nhất với pattern hiện có).
-3. **Thêm trục Windows vào CI matrix** (nếu chưa chạy unit trên windows-latest) để bắt regression loại này sớm.
-4. **Helper dùng chung:** tạo `test/fixtures/cross-platform-cmd.ts` export `OK_CMD`, `FAIL_CMD`, `PRINT_SECRET_CMD` để mọi test command dùng cùng nguồn.
-
-**Rủi ro fix:** thấp; chỉ đổi fixtures test.
-
----
-
-### M2 — Biome cấu hình nhưng không enforce trong CI
-
-**Bằng chứng:** `biome.json` đầy đủ (formatter+linter+assist) nhưng `npm run ci` = `typecheck && check:lazy-imports && test && pack` — **không gọi biome**. `npx biome check .` → 1938 errors + 383 warnings. Bóc tách: ~1840 là formatting/import-sort; **lint thật**: 162 `noUnusedVariables`, 146 `noExplicitAny` (warn), **52 `noControlCharactersInRegex`**, 9 `noAssignInExpressions`, 13 `noUselessEscapeInRegex`...
-
-**Nguyên nhân gốc:** linter tồn tại nhưng chưa được đưa vào gate → drift tích lũy.
-
-**Tác động:** chất lượng không được bảo vệ; đặc biệt **52 control-char-in-regex** có thể là lỗi parse/ReDoS thật.
-
-**Giải pháp chi tiết (tối ưu — đưa về xanh theo từng bước, không "big-bang"):**
-1. **Tách format khỏi lint để giảm ồn:**
-   - Một lần: `npx biome format --write .` (chỉ format, diff lớn nhưng cơ học, review nhanh) → loại ~1840 lỗi formatting/import.
-   - Commit riêng "style: biome format" để không lẫn với fix logic.
-2. **Sửa nhóm lint thật theo mức rủi ro:**
-   - Ưu tiên 52 `noControlCharactersInRegex` + 13 `noUselessEscapeInRegex`: rà từng regex, escape đúng hoặc dùng `\x00`-style explicit; đây là nhóm có thể ẩn bug.
-   - 9 `noAssignInExpressions`: tách assignment ra khỏi điều kiện.
-   - 162 `noUnusedVariables`: xóa/đánh dấu `_` prefix.
-   - 146 `noExplicitAny` (đang `warn`): theo AGENTS.md "avoid any" — chuyển dần sang `unknown`+validation; có thể giữ `warn` tạm thời.
-3. **Đưa vào CI tăng dần:** thêm `"lint": "biome check --linter-enabled=true --formatter-enabled=false ."` vào `ci` với `--max-diagnostics` hợp lý; bật `format --check` sau khi bước (1) xong.
-4. **Hook pre-commit** (đã gợi ý trong AGENTS.md global): chạy biome trên staged files để chặn drift mới.
-
-**Rủi ro fix:** format-write tạo diff lớn → làm trong PR riêng, không kèm thay đổi logic.
-
----
-
-### M3 — iterative-retrieval không được nối vào runtime + scoring thô sơ
-
-**Bằng chứng:** `src/runtime/task-runner/context-retrieval.ts` export `scoreRelevance/hasConverged/refineQuery/shouldContinue`; grep toàn `src/` → **chỉ tự tham chiếu nội bộ**, không caller nào ở prompt-builder/task-runner. Doc module ghi "actual file discovery is delegated to the caller" nhưng caller không tồn tại. Scoring là keyword-match (comment thừa nhận "in production would be replaced by embedding-based similarity").
-
-**Nguyên nhân gốc:** tính năng được scaffold (logic scoring) nhưng phần "discovery + vòng lặp" chưa wire.
-
-**Tác động:** capability được kỳ vọng (worker tự khám phá context theo vòng) thực chất không hoạt động → kỳ vọng sai về chất lượng context.
-
-**Giải pháp chi tiết (chọn 1 trong 2 hướng, tránh để code "lửng"):**
-- **Hướng A — Wire thật (nếu muốn giữ tính năng):**
-  1. Trong `prompt-builder.renderTaskPrompt`, sau khi dựng workspace tree, chạy vòng retrieval: từ `step.task`+`goal` sinh `RetrievalQuery` (keyword tách từ task), dùng **`grep`/`glob` thật** (ripgrep qua child) làm "discovery" thay cho heuristic in-memory; chấm điểm bằng số match + vị trí path (BM25-lite) thay cho `scoreRelevance` keyword đơn thuần.
-  2. Giới hạn `MAX_CYCLES=3` (đã có), inject top-N file path (không nội dung) vào prompt như "Suggested files to read", để worker chủ động `read`.
-  3. Thêm unit test cho convergence trên fixture repo.
-- **Hướng B — Hạ cấp rõ ràng (nếu chưa ưu tiên):**
-  1. Đánh dấu module `@experimental` + thêm `// NOT WIRED:` ở đầu file, hoặc move sang `src/runtime/experimental/`.
-  2. Cập nhật doc để không quảng bá là tính năng đang chạy.
-
-**Khuyến nghị:** Hướng A với discovery bằng ripgrep là tối ưu (tận dụng tool có sẵn, không cần embedding hạ tầng).
-
----
-
-### M4 — `contextMode: fresh|fork` là metadata no-op trong runtime mặc định
-
-**Bằng chứng:** `contextMode` được parse (`discover-agents.ts:261`), serialize, hiện trên UI overlay, có trong schema — nhưng grep cho thấy **không consumer runtime** (pi-args/child-pi) đổi hành vi theo nó. Child luôn `--no-session` (fresh). `inheritProjectContext` thì wired thật (env + `prompt-runtime.stripProjectContext`).
-
-**Nguyên nhân gốc:** "fork" (kế thừa session cha) chỉ khả thi ở live-session experimental, không phải child-process mặc định; field được expose mà chưa có đường thực thi.
-
-**Tác động:** user đặt `contextMode: fork` tưởng có hiệu lực nhưng bị bỏ qua âm thầm.
-
-**Giải pháp chi tiết (tối ưu — fail-loud + thực thi đúng nơi):**
-1. **Validate-time cảnh báo:** trong `discover-agents`/`validateResources`, nếu agent dùng `contextMode: fork` mà runtime hiệu lực là `child-process`, emit warning rõ ràng ("fork chỉ hỗ trợ ở live-session; sẽ chạy như fresh").
-2. **Thực thi tối thiểu cho child-process:** "fork" đầy đủ (chia sẻ conversation) không khả thi với process tách rời, nhưng có thể xấp xỉ bằng cách **seed dependency-context/parent-summary** mạnh hơn (truyền summary của parent vào prompt) — đặt sau cờ và đặt tên đúng kỳ vọng.
-3. **Hoặc** giới hạn schema: chỉ chấp nhận `fork` khi `runtime.mode=live-session`, ngược lại reject ở validate (đỡ ngộ nhận).
-
-**Khuyến nghị:** bước (1)+(3) trước (rẻ, fail-loud); (2) khi có nhu cầu thật.
-
----
-
-### M5 — Phối hợp cross-worker chỉ ở mức prompt, không enforce
-
-**Bằng chứng:** `coordinationBridgeInstructions` (prompt-builder) yêu cầu worker "pause and request sequencing/ownership" khi nghi đụng file chung — nhưng là chỉ dẫn mềm, phụ thuộc model tuân thủ. Không có khóa file/ownership ở tầng scheduler.
-
-**Nguyên nhân gốc:** thiết kế durable+parallel ưu tiên cô lập qua worktree, nhưng với workspace dùng chung (single mode) thì hai worker song song vẫn có thể ghi đè nhau.
-
-**Tác động:** rủi ro trùng việc/ghi đè/merge-conflict khi fan-out trên cùng vùng file (giảm nhẹ nhờ worktree mode).
-
-**Giải pháp chi tiết (tối ưu — phòng thủ theo lớp):**
-1. **Ưu tiên worktree isolation cho task ghi:** khi `workspaceMode=single` và có ≥2 task song song cùng khai báo `writes`/`reads` chồng nhau → scheduler tự nâng lên worktree hoặc serialize (đã có concurrency engine; thêm bước phát hiện chồng path).
-2. **File-lease ở scheduler:** cho mỗi batch, tính giao của `step.reads/writes`; nếu giao khác rỗng giữa các task ready → không xếp chúng vào cùng batch (chuyển sang tuần tự). Đây là enforce cứng, rẻ, dựa trên metadata đã có.
-3. **Conflict-detect sau merge** (đã có `conflict-detect.ts`/`delta-conflict.ts`): nâng từ "phát hiện" lên "chặn closeout" khi phát hiện hai worker sửa cùng symbol/file.
-4. Giữ coordination prompt như lớp mềm bổ sung.
-
-**Rủi ro fix:** giảm song song trong vài trường hợp (đánh đổi đúng đắn lấy tốc độ) — chấp nhận được; có thể đặt sau cờ `limits.serializeOnPathOverlap` (default on).
-
----
-
-### M6 — Warm pool là stub: mỗi task trả full Pi cold-start
-
-**Bằng chứng:** `child-pi-pool.ts:50 acquirePooledChild()` luôn `return null` → mọi task spawn tiến trình `pi` mới. ADR 0008 mô tả pool nhưng bị chặn bởi handshake runtime của Pi (`PI_CREW_POOL_HEALTH=1` chưa có).
-
-**Nguyên nhân gốc:** phụ thuộc tính năng phía Pi runtime (wait-for-prompt handshake) chưa tồn tại.
-
-**Tác động:** trong child-process mode, chi phí per-task lớn nhất là Pi cold-start (lặp lại mỗi task) → throughput thấp khi nhiều task nhỏ.
-
-**Giải pháp chi tiết (tối ưu — giảm chi phí mà không cần chờ Pi):**
-1. **Ngắn hạn (không cần handshake):**
-   - **Batch nhiều micro-task vào một worker:** với các task nhỏ cùng role/cwd không phụ thuộc nhau, gộp thành một prompt nhiều mục cho 1 child → cắt N cold-start xuống 1. Thêm cờ workflow `coalesceMicroTasks`.
-   - **Tái dùng artifact/context cache giữa task** (đã có manifest-cache, findRepoRoot TTL-LRU) để giảm phần khởi tạo lặp.
-2. **Trung hạn (khi Pi có handshake):** hiện thực `acquirePooledChild` theo ADR 0008, prewarm `resolveWarmPoolSize` child ở idle, health-check `PI_CREW_POOL_HEALTH`.
-3. **Đo & công khai giới hạn:** thêm bench per-task spawn cost + ghi rõ trong docs throughput hiện tại để set kỳ vọng.
-
-**Rủi ro fix:** coalesce micro-task làm giảm cô lập per-task (một task lỗi ảnh hưởng nhóm) → chỉ áp cho task read-only/độc lập, kèm guard.
-
----
-
-### M7 — `appendEventBuffered` không có caller + chưa có bench chứng minh lợi ích
-
-**Bằng chứng:** `event-log.ts:647 appendEventBuffered` tồn tại (xử lý terminal-bypass, overflow-reject, timer.unref) nhưng grep toàn `src/` → **không caller nào**. `task.progress` vẫn đi qua `appendEvent` đồng bộ (sync lock + fsync). Bench `event-append` đo "serial vs one-file-per-append", **không** đo đường buffered → lợi ích chưa được chứng minh.
-
-**Nguyên nhân gốc:** caller-migration 2.2 còn treo; API ship trước, đo và wire sau.
-
-**Tác động:** bỏ lỡ giảm lock-churn dưới tải progress cao; đồng thời có "code chết" gây hiểu nhầm đã tối ưu.
-
-**Giải pháp chi tiết (tối ưu — đo trước, wire sau, hoặc xóa):**
-1. **Thêm bench đúng đối tượng:** mở rộng `event-append.bench.ts` thêm scenario `buffered` (N `task.progress` qua `appendEventBuffered` rồi `flushEventLogBuffer`) so với `serial`. Chỉ wire nếu buffered thắng rõ ở p95.
-2. **Nếu thắng — wire có chọn lọc:** đổi **chỉ** `task.progress` (sự kiện tần suất cao, không-terminal) ở `team-runner`/`task-runner` sang `appendEventBuffered`; **giữ** `appendEvent` cho sự kiện terminal/lifecycle (durability). Đảm bảo gọi `flushEventLogBuffer` ở các điểm: trước khi đọc events cho status/dashboard, và ở shutdown/cleanup.
-3. **Nếu không thắng — xóa API** để tránh code chết, ghi lại quyết định trong `docs/decisions/`.
-4. Thêm test crash-semantics (kill giữa buffer) để chốt caveat "mất event trong buffer khi kill -9" là chấp nhận được với progress.
-
-**Rủi ro fix:** event ordering — buffered vẫn đi qua `appendEventInsideLock` tuần tự nên seq monotonic được giữ; cần test khẳng định.
-
----
-
-### M8 — Baseline bench không tái lập across môi trường + không nằm trong CI
-
-**Bằng chứng:** `baseline.json` ghim Node v24/máy cụ thể; chạy ở Node v22 cho "regression" giả khổng lồ (import 520ms→2049ms, register 24ms→461ms). `npm run ci` không gọi bench (baseline doc xác nhận "bench does not run as part of npm test").
-
-**Nguyên nhân gốc:** baseline tuyệt đối, một-máy; gate thủ công.
-
-**Tác động:** không bắt được regression hiệu năng thật giữa các lần; số liệu dễ gây hiểu nhầm.
-
-**Giải pháp chi tiết (tối ưu — đo tương đối, gate trong CI):**
-1. **Re-baseline theo runner:** trong CI, mỗi lần chạy: capture baseline trên chính runner đó từ commit gốc (merge-base), rồi so commit hiện tại trên **cùng máy/cùng Node** → loại nhiễu môi trường. Hoặc lưu baseline theo khóa `{os, nodeMajor}`.
-2. **Chuyển sang chỉ số tương đối nội-tiến-trình** cho các metric nhạy môi trường: đo register **so với** một baseline đo ngay trong cùng tiến trình (vd tỉ lệ với một micro-benchmark chuẩn) thay vì ms tuyệt đối.
-3. **Đưa `bench:check` vào CI** như job riêng (không chặn unit test), `THRESHOLD_PCT=15`, chỉ chạy trên một OS cố định để ổn định.
-4. **Pin Node trong dev/CI** (`.nvmrc`/`engines`) để giảm phương sai (hiện baseline v24 nhưng máy chạy v22).
-
-**Rủi ro fix:** thấp; cải thiện tooling.
-
----
-
-## ⚪ Mức Thấp / Hygiene
-
-### L1 — State runtime bị commit vào git
-
-**Bằng chứng:** `git ls-files .crew` → 14 file (`state/subagents/*.json`, `audit/prune.jsonl`). `.gitignore` đã ignore `/.crew/` → đang hiển thị "deleted" trong working tree.
-
-**Giải pháp:**
-1. `git rm --cached -r .crew/state .crew/audit` (giữ file trên đĩa, bỏ khỏi index).
-2. Commit "chore: untrack runtime crew state".
-3. Xác nhận `.gitignore` đã chặn (đã có `/.crew/` + allowlist `!.crew/artifacts/`, `!.crew/graphs/`). Đảm bảo không vô tình commit lại qua allowlist.
-
-**Rủi ro:** thấp; không xóa file đĩa. Lưu ý đây là file người dùng đang theo dõi → chỉ untrack, không xóa.
-
----
-
-### L2 — File orchestrator quá lớn
-
-**Bằng chứng:** `register.ts` 2195, `team-runner.ts` 2087, `config.ts` 1439, `task-runner.ts` 1434, `team-tool.ts` 1436 — trái nguyên tắc AGENTS.md "prefer small modules over large orchestrator files".
-
-**Giải pháp (incremental, không refactor lớn một lần):**
-1. `register.ts` → tách theo "feature installer": `registration/observability.ts`, `registration/ui.ts`, `registration/lifecycle.ts` (đã có `registration/commands.ts` làm mẫu). Việc này phục vụ trực tiếp H3 (lazy register).
-2. `team-runner.ts` → tách scheduler-loop vs batch-exec vs closeout-policy (một phần đã tách `adaptive-plan.ts`).
-3. Đặt ngưỡng cảnh báo độ lớn file trong review checklist (vd >1000 dòng cần lý do).
-
-**Rủi ro:** medium (đụng module nóng) → mỗi lần tách kèm `npm test` đầy đủ.
-
----
-
-### L3 — Doc sprawl
-
-**Bằng chứng:** `docs/` ~60 file gồm nhiều báo cáo one-off (`pi-crew-v0.5.x-audit-fix-plan` x10, `pi-crew-test-roundN` x6, nhiều `followup-review-*`).
-
-**Giải pháp:**
-1. Tạo `docs/archive/` và chuyển các báo cáo lịch sử one-off vào đó.
-2. Giữ ở `docs/` gốc các "source of truth" sống: ARCHITECTURE, FEATURE_INTAKE, TEST_MATRIX, HARNESS, usage, troubleshooting.
-3. Thêm `docs/README.md` index trỏ tới tài liệu sống vs lưu trữ.
-
-**Rủi ro:** thấp.
-
----
-
-### L4 — Prompt bloat ở node fan-in (dependencies không được prune)
-
-**Bằng chứng:** `task-output-context.ts` áp pruning (staleness) cho `sharedReads` nhưng **không** cho danh sách `dependencies`. Mỗi dep inline tới 32KB (`MAX_RESULT_INLINE_BYTES`) + structuredResults JSON + artifacts + usage. Task fan-in nhiều dep → prompt phồng.
-
-**Giải pháp chi tiết:**
-1. **Ngân sách context tổng cho dependencies:** đặt `MAX_TOTAL_DEP_INLINE_BYTES` (vd 96KB); khi vượt, ưu tiên giữ inline cho dep mới nhất/quan trọng nhất, các dep còn lại chỉ giữ `resultPath`+`fullOutputPath` (tee) để worker tự `read` khi cần.
-2. **Xếp hạng dep:** theo `status` (failed/needs-attention trước), recency, và độ liên quan tới `step.task`.
-3. **Tận dụng tee sẵn có:** với dep bị hạ xuống path-only, đảm bảo `fullOutputPath` luôn có (đã có hạ tầng tee).
-
-**Rủi ro:** thấp–medium; thêm test cho fan-in lớn.
-
----
-
-### L5 — `loadMode: "lean"` chỉ là gợi ý prompt
-
-**Bằng chứng:** `toolGuidanceBlock` chỉ in hint; comment: "actual tool filtering at the Pi level is a future optimisation (Phase 3.2+)". Việc giới hạn tool thật đến từ `resolveToolPolicy`/`--tools`.
-
-**Giải pháp:**
-1. **Nối lean → tool policy thật:** khi `loadMode=lean` và có `defaultTools`, đưa `defaultTools` vào allowlist `--tools` của `buildPiWorkerArgs` (giao với policy hiện có), để "lean" có hiệu lực thật chứ không chỉ prompt.
-2. Cập nhật doc/`resolveToolPolicy` để `loadMode` là một nguồn allowlist hợp lệ.
-
-**Rủi ro:** thấp; cần test để chắc không siết nhầm tool cần thiết.
-
----
-
-### L6 — Ngưỡng truncation trên mẫu nhỏ + token heuristic char/4
-
-**Bằng chứng:** `MAX_RESULT_INLINE_BYTES=32_000` tinh chỉnh từ "27 result artifacts, max 9226 bytes"; token est = char/4 (`tool-output-pruner`).
-
-**Giải pháp:**
-1. **Thu thập phân phối thật hơn:** log kích thước result/shared-read theo thời gian (đã có metrics) → tinh chỉnh ngưỡng theo p95/p99 thực, không phải mẫu 27.
-2. **Token est chính xác hơn khi cần quyết định prune lớn:** dùng ước lượng theo model tokenizer nếu Pi expose, hoặc giữ char/4 nhưng thêm hệ số theo loại nội dung (code vs văn xuôi).
-3. Đặt ngưỡng vào config (`observability`/`limits`) để tinh chỉnh không cần đổi code.
-
-**Rủi ro:** thấp.
-
----
-
-## Thứ tự thực thi đề xuất
-
-1. **Quick wins (S):** L1 (untrack state), M1 (cross-platform test fixtures), H1 bước dev-only esbuild, M2 bước `biome format --write` + thêm lint vào CI.
-2. **Đòn bẩy hiệu năng (M):** H2 (flip bundle + smoke), M8 (bench trong CI theo runner), M7 (bench buffered → wire/xóa).
-3. **Chất lượng context (M):** M3 (wire/đánh dấu retrieval), M4 (fail-loud contextMode), L4 (ngân sách dep), L5 (lean→tool policy).
-4. **Cấu trúc & throughput (L):** H3 + L2 (tách register, lazy khởi tạo), M5 (file-lease scheduler), M6 (coalesce micro-task; pool khi Pi sẵn sàng).
-5. **Theo dõi liên tục:** H1 nâng peer 0.80.x (sau smoke 3-OS), L3 (archive docs), L6 (tinh chỉnh ngưỡng theo metric thật).

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

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

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