pi-crew 0.8.14 → 0.9.0

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

@@ -1,24 +1,24 @@
-# Bug #7: Async notifier "stale ctx detected; stopping notifier" — không restart
+# Bug #7: Async notifier "stale ctx detected; stopping notifier" — does not restart
 
 | Field | Value |
 |---|---|
 | **Severity** | 🔴 HIGH |
 | **Status** | Root cause confirmed, fix pending |
-| **Affected** | Tất cả pi-crew users sau khi Pi session restarts/compacts |
-| **Symptom** | Sau restart/compact, notifier dừng hoàn toàn — không còn nhận notifications cho run completions |
+| **Affected** | All pi-crew users after a Pi session restarts/compacts |
+| **Symptom** | After restart/compact, the notifier stops completely — run-completion notifications are no longer received |
 
-## Mô tả
+## Description
 
-Sau khi Pi restart (hoặc /clear, /compact, session switch), xuất hiện error:
+After Pi restarts (or /clear, /compact, session switch), the following error appears:
 ```
 [pi-crew] async notifier stale ctx detected; stopping notifier.
 ```
 
-Sau đó, pi-crew **không còn deliver notifications** cho run completions. Background runs hoàn thành nhưng user không được báo.
+After that, pi-crew **no longer delivers notifications** for run completions. Background runs finish, but the user is never notified.
 
 ## Root cause
 
-### Flow bình thường (mong đợi):
+### Normal flow (expected):
 
 ```
 Pi session_start event
@@ -26,28 +26,28 @@ Pi session_start event
   → currentCtx = newCtx
   → cleanupRuntime() (stop old notifier)
   → startAsyncRunNotifier(newCtx, ...)
-  → New notifier hoạt động với newCtx ✅
+  → New notifier runs with newCtx ✅
 ```
 
-### Flow bị lỗi:
+### Buggy flow:
 
 ```
 1. Old notifier interval tick fires
-2. isCurrent(generation) check → true (generation chưa increment)
+2. isCurrent(generation) check → true (generation hasn't incremented yet)
 3. ctx.ui.notify() called
-4. Pi đã invalidate old ctx → throw Error("This extension ctx is stale...")
+4. Pi has already invalidated the old ctx → throws Error("This extension ctx is stale...")
 5. Catch block: message.includes("stale") → true
 6. stopAsyncRunNotifier(state) → clearInterval(interval)
 7. console.error("stale ctx detected; stopping notifier.")
 8. ❌ Notifier stopped permanently
 ```
 
-Vấn đề: **session_start handler** CHƯA kịp chạy để start new notifier.
+The problem: the **session_start handler** hasn't had a chance to run yet to start the new notifier.
 
-### Tại sao session_start chưa chạy?
+### Why hasn't session_start run yet?
 
-Khi Pi invalidate ctx, old notifier interval **vẫn đang chạy** (clearInterval chưa được gọi). Interval tick xảy ra **trước khi** `cleanupRuntime()` hoặc `session_start` handler chạy. Đây là **race condition** giữa:
-- Old notifier's setInterval tick
+When Pi invalidates ctx, the old notifier interval **is still running** (clearInterval hasn't been called yet). The interval tick occurs **before** `cleanupRuntime()` or the `session_start` handler runs. This is a **race condition** between:
+- The old notifier's setInterval tick
 - Pi's session shutdown/start event sequence
 
 ### Code location
@@ -67,21 +67,21 @@ Khi Pi invalidate ctx, old notifier interval **vẫn đang chạy** (clearInterv
 ### Why it matters
 
 - User restarts Pi → notifier dies → background runs complete silently
-- User phải manually check `team status` để biết runs hoàn thành
-- Ảnh hưởng UX nghiêm trọng: pi-crew "câm" sau restart
+- The user has to manually check `team status` to learn that runs finished
+- Severe UX impact: pi-crew goes "silent" after a restart
 
 ## Fix
 
-### Option A: Silent swallow stale errors (recommended)
+### Option A: Silently swallow stale errors (recommended)
 
-Thay vì stop notifier, chỉ **skip notification** này và chờ session_start restart notifier với new ctx:
+Instead of stopping the notifier, just **skip this notification** and let session_start restart the notifier with the new ctx:
 
 ```typescript
 } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     if (message.includes("stale") || message.includes("session replacement") || message.includes("old ctx")) {
         // Don't stop — session_start will create a new notifier with the new ctx.
-        // This old notifier's isCurrent guard will return false on next tick,
+        // This old notifier's isCurrent guard will return false on the next tick,
         // making it effectively dormant until cleaned up.
         return;
     }
@@ -89,11 +89,11 @@ Thay vì stop notifier, chỉ **skip notification** này và chờ session_start
 }
 ```
 
-Rationale: `isCurrent` guard sẽ return false sau khi `sessionGeneration++` → old notifier interval vẫn chạy nhưng không làm gì (silent). New notifier từ `session_start` sẽ hoạt động bình thường.
+Rationale: the `isCurrent` guard will return false once `sessionGeneration++` runs → the old notifier interval keeps running but does nothing (silent). The new notifier from `session_start` will work normally.
 
-### Option B: Add explicit restart mechanism
+### Option B: Add an explicit restart mechanism
 
-Add `restartAsyncRunNotifier()` function và gọi từ `session_start` handler. Nhưng Option A đơn giản hơn và đủ.
+Add a `restartAsyncRunNotifier()` function and call it from the `session_start` handler. But Option A is simpler and sufficient.
 
 ## Key files
 

package/docs/followup-plan-2026-05-12.md

@@ -1,22 +1,22 @@
 # Follow-up Plan — pi-crew (2026-05-12)
 
-Tác giả: Droid (Factory) | Liên quan: `docs/code-review-2026-05-11.md`, commits `2aebf33`, `7c5b3c2`.
+Author: Droid (Factory) | Related: `docs/code-review-2026-05-11.md`, commits `2aebf33`, `7c5b3c2`.
 
-Tài liệu này tổng hợp các điểm tồn đọng SAU khi đã fix BUG-001..BUG-007 + NIT-001..NIT-004, gồm:
-1. **Quan ngại nhỏ** phát sinh từ chính các fix vừa apply.
-2. **Gaps mới phát hiện** khi review lại toàn bộ `pi-crew/` lần nữa.
+This document consolidates the outstanding items AFTER fixing BUG-001..BUG-007 + NIT-001..NIT-004, comprising:
+1. **Minor concerns** arising from the fixes just applied.
+2. **Newly discovered gaps** found when re-reviewing the entire `pi-crew/` codebase.
 
-Tất cả mục đều có ước lượng effort, mức ưu tiên, file/đoạn code liên quan, và đề xuất fix cụ thể.
+Every item includes an effort estimate, priority level, related file/code section, and a concrete fix proposal.
 
 ---
 
-## Phần A — Điều chỉnh các "quan ngại nhỏ" của fix vừa apply
+## Part A — Adjusting minor concerns from the fixes just applied
 
-### A1 — `branchExists` chỉ check local ref → bỏ sót remote-tracking branch
+### A1 — `branchExists` only checks local ref → misses remote-tracking branches
 
-**Severity:** Low | **Effort:** ~20 phút | **File:** `src/worktree/worktree-manager.ts:100-107`
+**Severity:** Low | **Effort:** ~20 minutes | **File:** `src/worktree/worktree-manager.ts:100-107`
 
-**Hiện trạng:**
+**Current state:**
 ```ts
 function branchExists(repoRoot: string, branch: string): boolean {
   try {
@@ -26,11 +26,11 @@ function branchExists(repoRoot: string, branch: string): boolean {
 }
 ```
 
-**Vấn đề:**
-- Chỉ check `refs/heads/<branch>`. Nếu repo có remote-tracking `refs/remotes/origin/<branch>` (push từ máy khác) mà chưa có local, hàm trả `false` → đi vào nhánh `worktree add -b <branch> HEAD` → git có thể fail với "a branch named ... already exists" (vì git tạo local branch từ remote) hoặc tạo local branch divergent với remote.
-- Hiếm trong workflow đơn-máy nhưng dễ gặp với CI/runner shared repo.
+**Problem:**
+- Only checks `refs/heads/<branch>`. If the repo has a remote-tracking `refs/remotes/origin/<branch>` (pushed from another machine) but no local one yet, the function returns `false` → enters the `worktree add -b <branch> HEAD` branch → git may fail with "a branch named ... already exists" (because git creates a local branch from the remote) or create a local branch divergent from the remote.
+- Rare in single-machine workflows but easily hit with CI/runner shared repos.
 
-**Fix đề xuất:**
+**Proposed fix:**
 ```ts
 function branchExists(repoRoot: string, branch: string): { local: boolean; remoteOnly: boolean } {
   let local = false;
@@ -56,32 +56,32 @@ if (exists.local) {
 }
 ```
 
-**Test cần thêm:** `test/unit/worktree-manager.test.ts`:
-1. Mock `git for-each-ref` trả về remote-tracking → assert không throw.
-2. Branch tồn tại cả local lẫn remote → ưu tiên local (reuse).
+**Tests to add:** `test/unit/worktree-manager.test.ts`:
+1. Mock `git for-each-ref` returning a remote-tracking ref → assert no throw.
+2. Branch exists in both local and remote → prefer local (reuse).
 
 ---
 
-### A2 — `resolveJitiRegisterPath` fallback giờ bắt buộc `exists()` check
+### A2 — `resolveJitiRegisterPath` fallback now requires an `exists()` check
 
-**Severity:** Low | **Effort:** ~10 phút | **File:** `src/runtime/async-runner.ts:33-39`
+**Severity:** Low | **Effort:** ~10 minutes | **File:** `src/runtime/async-runner.ts:33-39`
 
-**Hiện trạng:**
+**Current state:**
 ```ts
 try {
   const fromRequire = jitiRegisterPathFromPackageJson(requireFromHere.resolve("jiti/package.json"));
-  if (exists(fromRequire)) return fromRequire;   // ← thêm exists() check
+  if (exists(fromRequire)) return fromRequire;   // ← added exists() check
 } catch { /* Fall through. */ }
 return undefined;
 ```
 
-**Vấn đề:**
-- Behaviour cũ: `require.resolve()` thành công → push vào candidates → return path (giả định `lib/jiti-register.mjs` luôn tồn tại bên cạnh `package.json`).
-- Behaviour mới: thêm `exists()` check → nếu test mock `exists` chỉ accept đúng 1 path khác, fallback luôn fail. Behaviour ổn cho production (file luôn tồn tại), nhưng giảm robustness với jiti packaging exotic (vd. `lib` được rename trong distro).
-- Không thực sự là bug, chỉ là defensive change.
+**Problem:**
+- Old behavior: `require.resolve()` succeeds → push into candidates → return path (assumes `lib/jiti-register.mjs` always exists next to `package.json`).
+- New behavior: adds an `exists()` check → if the test mock for `exists` only accepts one different path, the fallback always fails. The behavior is fine for production (file always exists), but reduces robustness with exotic jiti packaging (e.g. `lib` renamed in a distro build).
+- Not really a bug, just a defensive change.
 
-**Fix đề xuất:**
-Giữ nguyên `exists()` check (an toàn hơn), nhưng thêm 1 fallback nữa với `path.join(dirname, "register.mjs")` cho các phiên bản jiti khác nhau, và log diagnostic event khi cả 2 đều miss:
+**Proposed fix:**
+Keep the `exists()` check (safer), but add another fallback with `path.join(dirname, "register.mjs")` for different jiti versions, and log a diagnostic event when both miss:
 
 ```ts
 try {
@@ -96,41 +96,41 @@ try {
 return undefined;
 ```
 
-**Test cần thêm:** `test/unit/async-runner.test.ts`:
-- Case `lib/jiti-register.mjs` missing nhưng `register.mjs` tồn tại → resolver return.
+**Tests to add:** `test/unit/async-runner.test.ts`:
+- Case where `lib/jiti-register.mjs` is missing but `register.mjs` exists → resolver returns it.
 
 ---
 
-### A3 — Test alias `__test__renameWithRetry*` trở thành `const`, có thể vô hiệu monkey-patch
+### A3 — Test alias `__test__renameWithRetry*` became a `const`, may disable monkey-patching
 
-**Severity:** Info | **Effort:** ~5 phút | **File:** `src/state/atomic-write.ts:73, 91`
+**Severity:** Info | **Effort:** ~5 minutes | **File:** `src/state/atomic-write.ts:73, 91`
 
-**Hiện trạng:**
+**Current state:**
 ```ts
 export const __test__renameWithRetry = renameWithRetry;
 ```
 
-**Vấn đề:**
-- Nếu test cũ làm `import * as mod from "../atomic-write.ts"; mod.__test__renameWithRetry = mockFn;` → assignment fail (read-only) hoặc không có effect trên `atomicWriteFile` (nó gọi `renameWithRetry` local).
-- Hiện tại không có test nào trong repo monkey-patch field này (`Grep` confirm), nên không phải bug.
+**Problem:**
+- If old tests do `import * as mod from "../atomic-write.ts"; mod.__test__renameWithRetry = mockFn;` → the assignment fails (read-only) or has no effect on `atomicWriteFile` (which calls the local `renameWithRetry`).
+- Currently no test in the repo monkey-patches this field (`Grep` confirmed), so it's not a bug.
 
-**Fix đề xuất:**
-- Giữ nguyên alias (zero impact thực tế).
-- Hoặc xoá hẳn 2 alias để giảm surface: chỉ export `renameWithRetry`, `renameWithRetryAsync`. Update test nếu có chỗ dùng alias.
+**Proposed fix:**
+- Keep the alias as-is (zero practical impact).
+- Or remove both aliases to reduce the API surface: only export `renameWithRetry`, `renameWithRetryAsync`. Update tests if any use the alias.
 
-**Action:** chỉ làm khi cần dọn dẹp API surface, không khẩn cấp.
+**Action:** only do this when cleaning up the API surface; not urgent.
 
 ---
 
-## Phần B — Gaps mới phát hiện khi review lại
+## Part B — Newly discovered gaps from re-review
 
-### B1 — `bash` hardcoded → broken trên Windows (root cause của 8 test fail)
+### B1 — `bash` hardcoded → broken on Windows (root cause of 8 test failures)
 
-**Severity:** Medium | **Effort:** ~45 phút | **Files:**
+**Severity:** Medium | **Effort:** ~45 minutes | **Files:**
 - `src/runtime/post-checks.ts:82`
 - `src/runtime/iteration-hooks.ts:137`
 
-**Hiện trạng:**
+**Current state:**
 ```ts
 // post-checks.ts:82
 const output = execFileSync("bash", [scriptPath], { ... });
@@ -139,13 +139,13 @@ const output = execFileSync("bash", [scriptPath], { ... });
 const child = spawn("bash", [hookScriptPath], { ... });
 ```
 
-**Vấn đề:**
-- Trên Windows, `bash` thường không có trên PATH (trừ khi cài Git Bash/WSL). 8 tests fail hiện tại đều do điều này.
-- Code path nóng (post-task check, iteration hook) → user Windows không dùng được tính năng này.
-- Comment trong file đã ghi "Spawns `bash <script>`" → docs cũng cần update.
+**Problem:**
+- On Windows, `bash` is usually not on the PATH (unless Git Bash/WSL is installed). All 8 currently failing tests are due to this.
+- Hot code path (post-task check, iteration hook) → Windows users cannot use this feature.
+- The comment in the file says "Spawns `bash <script>`" → docs need updating too.
 
-**Fix đề xuất:**
-1. Tìm bash thông minh:
+**Proposed fix:**
+1. Resolve bash intelligently:
 ```ts
 function resolveBashCmd(): string {
   if (process.platform !== "win32") return "bash";
@@ -160,26 +160,26 @@ function resolveBashCmd(): string {
   return "bash"; // last resort — let spawn fail with clearer error
 }
 ```
-2. Thay 2 chỗ `"bash"` bằng `resolveBashCmd()`.
-3. Trên Windows, nếu script là `.ps1` → dùng `powershell -File`; nếu `.cmd/.bat` → spawn trực tiếp.
-4. Hoặc đơn giản hơn: skip test nếu `!isScriptRunnable("bash")`.
+2. Replace both `"bash"` occurrences with `resolveBashCmd()`.
+3. On Windows, if the script is `.ps1` → use `powershell -File`; if `.cmd/.bat` → spawn directly.
+4. Or simpler: skip the test if `!isScriptRunnable("bash")`.
 
-**Test cần thêm:**
-- Trên CI Linux: tests hiện tại pass.
-- Trên Windows: skip nếu không có bash, hoặc tạo `.ps1` variant.
-- Mock test cho `resolveBashCmd()` với platform stub.
+**Tests to add:**
+- On Linux CI: current tests pass.
+- On Windows: skip if bash is unavailable, or create a `.ps1` variant.
+- Mock test for `resolveBashCmd()` with a platform stub.
 
 ---
 
-### B2 — Thiếu test trực tiếp cho `worktree-manager.ts` (covers BUG-005, BUG-006)
+### B2 — Missing direct tests for `worktree-manager.ts` (covers BUG-005, BUG-006)
 
-**Severity:** Medium | **Effort:** ~1h | **File:** thiếu `test/unit/worktree-manager.test.ts`
+**Severity:** Medium | **Effort:** ~1h | **File:** missing `test/unit/worktree-manager.test.ts`
 
-**Vấn đề:**
-- BUG-005 fix (`branchExists` + `pruneStaleWorktrees`) và BUG-006 fix (`isDirectory()` check) **không có test trực tiếp**.
-- Code review đã flag điều này nhưng commit fix chỉ thêm test cho schema.
+**Problem:**
+- The BUG-005 fix (`branchExists` + `pruneStaleWorktrees`) and BUG-006 fix (`isDirectory()` check) have **no direct tests**.
+- The code review flagged this, but the fix commit only added tests for the schema.
 
-**Fix đề xuất:** tạo `test/unit/worktree-manager.test.ts` với (sử dụng `tmpdir` + real git):
+**Proposed fix:** create `test/unit/worktree-manager.test.ts` with (using `tmpdir` + real git):
 
 ```ts
 import { test } from "node:test";
@@ -214,15 +214,15 @@ test("linkNodeModulesIfPresent rejects when node_modules is a file", () => {
 
 ---
 
-### B3 — `artifact-store.ts` thiếu test cho hash/size integrity (covers BUG-002)
+### B3 — `artifact-store.ts` missing tests for hash/size integrity (covers BUG-002)
 
-**Severity:** Medium | **Effort:** ~20 phút | **File:** thiếu `test/unit/artifact-store.test.ts`
+**Severity:** Medium | **Effort:** ~20 minutes | **File:** missing `test/unit/artifact-store.test.ts`
 
-**Vấn đề:**
-- BUG-002 fix đổi hash từ `options.content` sang `redactSecretString(options.content)` đảm bảo `contentHash` khớp bytes trên đĩa.
-- Không có test verify điều này. Có `api-artifact-security.test.ts` nhưng không assert hash.
+**Problem:**
+- The BUG-002 fix changed the hash from `options.content` to `redactSecretString(options.content)` ensuring `contentHash` matches the bytes on disk.
+- There is no test verifying this. There's `api-artifact-security.test.ts` but it doesn't assert the hash.
 
-**Fix đề xuất:** tạo `test/unit/artifact-store.test.ts`:
+**Proposed fix:** create `test/unit/artifact-store.test.ts`:
 ```ts
 import { test } from "node:test";
 import assert from "node:assert/strict";
@@ -256,14 +256,14 @@ test("writeArtifact: rejects path traversal", () => {
 
 ---
 
-### B4 — Thiếu test parity sync vs async cho lock retry (covers BUG-004)
+### B4 — Missing sync vs async parity test for lock retry (covers BUG-004)
 
-**Severity:** Low | **Effort:** ~30 phút | **File:** mở rộng `test/unit/locks-race.test.ts`
+**Severity:** Low | **Effort:** ~30 minutes | **File:** extend `test/unit/locks-race.test.ts`
 
-**Vấn đề:**
-- Fix BUG-004 đồng bộ hoá behaviour sync ↔ async (cả 2 cùng retry tới deadline). `locks-race.test.ts` chỉ test sơ bộ; không có case `rmSync` race + assert lock được acquire sau retry trên cả sync và async.
+**Problem:**
+- The BUG-004 fix synchronized sync ↔ async behavior (both retry up to the deadline). `locks-race.test.ts` only tests superficially; there's no case for `rmSync` race + asserting the lock is acquired after retry for both sync and async.
 
-**Fix đề xuất:** thêm 2 test:
+**Proposed fix:** add 2 tests:
 ```ts
 test("withRunLockSync retries when rmSync fails once on stale lock", async () => {
   // Create stale lock, monkey-patch fs.rmSync first call → throw EBUSY
@@ -277,11 +277,11 @@ test("withRunLock (async) and withRunLockSync exhibit identical stale-lock recov
 
 ---
 
-### B5 — `runSetupHook` không filter dangerous env vars khi spawn hook
+### B5 — `runSetupHook` doesn't filter dangerous env vars when spawning the hook
 
-**Severity:** Low (defense-in-depth) | **Effort:** ~15 phút | **File:** `src/worktree/worktree-manager.ts:67-88`
+**Severity:** Low (defense-in-depth) | **Effort:** ~15 minutes | **File:** `src/worktree/worktree-manager.ts:67-88`
 
-**Hiện trạng:**
+**Current state:**
 ```ts
 const result = spawnSync(nodeHook ? process.execPath : hookPath, ..., {
   cwd: worktreePath,
@@ -289,17 +289,17 @@ const result = spawnSync(nodeHook ? process.execPath : hookPath, ..., {
   input: JSON.stringify({...}),
   timeout: cfg.setupHookTimeoutMs ?? 30_000,
   shell: false,
-  // ← KHÔNG truyền env → spawn dùng process.env (full inherit)
+  // ← Does NOT pass env → spawn uses process.env (full inherit)
 });
 ```
 
-**Vấn đề:**
-- Hook chạy với `process.env` đầy đủ → có thể leak `API_KEY`, `*_TOKEN`, `OPENAI_KEY`, etc. Đối lập với `post-checks.ts` và `iteration-hooks.ts` (đã restrict env).
+**Problem:**
+- The hook runs with the full `process.env` → may leak `API_KEY`, `*_TOKEN`, `OPENAI_KEY`, etc. In contrast, `post-checks.ts` and `iteration-hooks.ts` already restrict env.
 - AGENTS.md security baseline: "env-secret filtering before spawn".
 
-**Fix đề xuất:**
+**Proposed fix:**
 ```ts
-import { sanitizeEnvSecrets } from "../utils/redaction.ts"; // hoặc tương đương
+import { sanitizeEnvSecrets } from "../utils/redaction.ts"; // or equivalent
 
 const result = spawnSync(..., {
   cwd: worktreePath,
@@ -311,15 +311,15 @@ const result = spawnSync(..., {
 });
 ```
 
-(Tận dụng helper đã có trong `child-pi.ts` — refactor thành util chung.)
+(Leverage the existing helper in `child-pi.ts` — refactor into a shared util.)
 
 ---
 
-### B6 — `prepareTaskWorkspace` không có assertion về branch sanity sau `branchExists`
+### B6 — `prepareTaskWorkspace` has no assertion about branch sanity after `branchExists`
 
-**Severity:** Info | **Effort:** ~10 phút | **File:** `src/worktree/worktree-manager.ts:127-133`
+**Severity:** Info | **Effort:** ~10 minutes | **File:** `src/worktree/worktree-manager.ts:127-133`
 
-**Hiện trạng:**
+**Current state:**
 ```ts
 pruneStaleWorktrees(repoRoot);
 if (branchExists(repoRoot, branch)) {
@@ -327,10 +327,10 @@ if (branchExists(repoRoot, branch)) {
 }
 ```
 
-**Vấn đề:**
-- Nếu branch hiện đang **checked out** ở một worktree khác (chưa bị prune), `git worktree add <path> <branch>` sẽ fail. Cần catch và emit hint rõ hơn cho user.
+**Problem:**
+- If the branch is currently **checked out** in another worktree (not yet pruned), `git worktree add <path> <branch>` will fail. We should catch this and emit a clearer hint to the user.
 
-**Fix đề xuất:** wrap với try/catch, parse error message, throw error có actionable message:
+**Proposed fix:** wrap with try/catch, parse the error message, throw an error with an actionable message:
 ```ts
 try {
   git(repoRoot, ["worktree", "add", worktreePath, branch]);
@@ -345,11 +345,11 @@ try {
 
 ---
 
-### B7 — `team-tool.ts` có 1 lazy-import `handleRun` không theo style `// LAZY: <reason>`
+### B7 — `team-tool.ts` has 1 lazy-import `handleRun` not following the `// LAZY: <reason>` style
 
-**Severity:** Info | **Effort:** ~2 phút | **File:** `src/extension/team-tool.ts:56-62`
+**Severity:** Info | **Effort:** ~2 minutes | **File:** `src/extension/team-tool.ts:56-62`
 
-**Hiện trạng:**
+**Current state:**
 ```ts
 // Lazy-loaded: run.ts pulls in spawnBackgroundTeamRun, resolveCrewRuntime, etc.
 // Static import fails silently in some jiti contexts (child-process), leaving handleRun undefined.
@@ -357,13 +357,13 @@ import type { handleRun as HandleRunFn } from "./team-tool/run.ts";
 let _cachedHandleRun: typeof HandleRunFn | undefined;
 async function handleRun(...args: Parameters<typeof HandleRunFn>): Promise<...> {
   if (!_cachedHandleRun) {
-    const mod = await import("./team-tool/run.ts");   // ← thiếu // LAZY: marker
+    const mod = await import("./team-tool/run.ts");   // ← missing // LAZY: marker
     ...
   }
 }
 ```
 
-**Fix đề xuất:** thêm marker để đồng nhất với 11 chỗ còn lại đã được đánh dấu:
+**Proposed fix:** add the marker to align with the other 11 already-marked sites:
 ```ts
 async function handleRun(...) {
   if (!_cachedHandleRun) {
@@ -376,42 +376,42 @@ async function handleRun(...) {
 
 ---
 
-### B8 — `redaction-transcript-roundtrip.test.ts` chưa tồn tại (NIT-004)
+### B8 — `redaction-transcript-roundtrip.test.ts` doesn't exist yet (NIT-004)
 
-**Severity:** Low | **Effort:** ~30 phút | **File:** thiếu test mới
+**Severity:** Low | **Effort:** ~30 minutes | **File:** missing new test
 
-**Vấn đề:**
-- Code review NIT-004 đề xuất test verify rằng transcript trên đĩa và artifact result đều không chứa secret raw. Hiện chưa có test này.
+**Problem:**
+- Code review NIT-004 suggested a test verifying that the transcript on disk and the artifact result both contain no raw secrets. This test doesn't exist yet.
 
-**Fix đề xuất:** tạo `test/unit/redaction-transcript-roundtrip.test.ts`:
-1. Tạo fake transcript JSONL với line chứa `OPENAI_API_KEY=sk-abc...`.
-2. Call `appendTranscript` (qua `child-pi` helper export).
-3. Read file → assert không có secret raw.
-4. Call recovery path → assert artifact result cũng đã redact.
+**Proposed fix:** create `test/unit/redaction-transcript-roundtrip.test.ts`:
+1. Create a fake transcript JSONL with a line containing `OPENAI_API_KEY=sk-abc...`.
+2. Call `appendTranscript` (via the `child-pi` helper export).
+3. Read the file → assert no raw secret.
+4. Call the recovery path → assert the artifact result is also redacted.
 
 ---
 
-### B9 — CI grep-check chặn `await import(...)` không marker
+### B9 — CI grep-check to block `await import(...)` without a marker
 
-**Severity:** Low | **Effort:** ~15 phút | **File:** thêm script + GitHub Actions
+**Severity:** Low | **Effort:** ~15 minutes | **File:** add script + GitHub Actions
 
-**Vấn đề:**
-- Code review BUG-003 Option A đề xuất "thêm grep-check trong CI để chặn dynamic import không marker". Chưa làm.
+**Problem:**
+- Code review BUG-003 Option A proposed "add a grep-check in CI to block unmarked dynamic imports". Not done yet.
 
-**Fix đề xuất:** tạo `scripts/check-lazy-imports.mjs`:
+**Proposed fix:** create `scripts/check-lazy-imports.mjs`:
 ```js
 import { execSync } from "node:child_process";
 const out = execSync(
   `git grep -nE 'await import\\(' -- 'src/**/*.ts' | grep -v '// LAZY:'`,
   { encoding: "utf-8" }
 ).split("\n").filter((l) => l && !l.includes("// LAZY:"));
-// Hoặc kiểm tra dòng ngay trước có chứa `// LAZY:`
+// Or check that the preceding line contains `// LAZY:`
 if (out.length > 0) {
   console.error("Dynamic imports without `// LAZY:` marker:\n" + out.join("\n"));
   process.exit(1);
 }
 ```
-Thêm vào `package.json`:
+Add to `package.json`:
 ```json
 "scripts": {
   "check:lazy-imports": "node scripts/check-lazy-imports.mjs",
@@ -421,43 +421,43 @@ Thêm vào `package.json`:
 
 ---
 
-## Ưu tiên thực hiện
+## Implementation priority
 
-| # | Item | Severity | Effort | Khuyến nghị |
+| # | Item | Severity | Effort | Recommendation |
 |---|---|---|---|---|
-| 1 | B1 (bash portability) | Medium | 45 phút | Sprint hiện tại — fix 8 test fail trên Windows |
-| 2 | B2 (worktree test) | Medium | 1h | Sprint hiện tại — regression guard cho BUG-005/006 |
-| 3 | B3 (artifact-store test) | Medium | 20 phút | Sprint hiện tại — verify BUG-002 fix |
-| 4 | A1 (branchExists remote-tracking) | Low | 20 phút | Sprint kế tiếp |
-| 5 | B5 (setup-hook env filter) | Low | 15 phút | Sprint kế tiếp — defense-in-depth |
-| 6 | B6 (worktree checked-out hint) | Info | 10 phút | Sprint kế tiếp — UX |
-| 7 | B7 (LAZY marker đồng nhất) | Info | 2 phút | Lúc nào cũng được |
-| 8 | B4 (lock parity test) | Low | 30 phút | Sprint kế tiếp |
-| 9 | B8 (redaction roundtrip test) | Low | 30 phút | Sprint kế tiếp |
-| 10 | B9 (CI grep-check) | Low | 15 phút | Sprint kế tiếp |
-| 11 | A2 (async-runner fallback robust) | Low | 10 phút | Không cấp bách |
-| 12 | A3 (test alias cleanup) | Info | 5 phút | Tuỳ ý |
-
-**Tổng effort ưu tiên 1 (medium):** ~2h 5 phút.
-**Tổng effort ưu tiên 2 (low):** ~1h 50 phút.
+| 1 | B1 (bash portability) | Medium | 45 minutes | Current sprint — fix 8 failing tests on Windows |
+| 2 | B2 (worktree test) | Medium | 1h | Current sprint — regression guard for BUG-005/006 |
+| 3 | B3 (artifact-store test) | Medium | 20 minutes | Current sprint — verify BUG-002 fix |
+| 4 | A1 (branchExists remote-tracking) | Low | 20 minutes | Next sprint |
+| 5 | B5 (setup-hook env filter) | Low | 15 minutes | Next sprint — defense-in-depth |
+| 6 | B6 (worktree checked-out hint) | Info | 10 minutes | Next sprint — UX |
+| 7 | B7 (LAZY marker consistency) | Info | 2 minutes | Anytime |
+| 8 | B4 (lock parity test) | Low | 30 minutes | Next sprint |
+| 9 | B8 (redaction roundtrip test) | Low | 30 minutes | Next sprint |
+| 10 | B9 (CI grep-check) | Low | 15 minutes | Next sprint |
+| 11 | A2 (async-runner fallback robust) | Low | 10 minutes | Not urgent |
+| 12 | A3 (test alias cleanup) | Info | 5 minutes | Optional |
+
+**Total effort priority 1 (medium):** ~2h 5 minutes.
+**Total effort priority 2 (low):** ~1h 50 minutes.
 
 ---
 
-## Đề xuất commit batches
+## Proposed commit batches
 
 - **Batch 1 (must-fix):** B1 + B2 + B3 → 1 PR "test+portability hardening" (~2h).
 - **Batch 2 (nice-to-have):** A1 + B5 + B6 + B7 + B9 → 1 PR "worktree + lazy-import polish" (~1h).
 - **Batch 3 (test debt):** B4 + B8 → 1 PR "additional regression tests" (~1h).
-- **Defer:** A2, A3 cho đến khi có user-visible issue.
+- **Defer:** A2, A3 until there's a user-visible issue.
 
 ---
 
-## Điểm tích cực sau review lần 2
+## Positive notes after round 2 review
 
-- Tất cả 7 BUG + 4 NIT từ code review trước đã được fix với commit rõ ràng, có test cho schema.
-- Comment `// LAZY:` đã được thêm consistent ở 11/12 site dynamic import.
-- Lock retry logic giờ thống nhất sync ↔ async (cả 2 đều có deadline + retry).
-- Worktree handle resume crash đúng cách (prune + branchExists fallback).
-- Artifact `contentHash` giờ verifiable bằng `sha256(fs.readFileSync(desc.path))`.
-- Không còn `any` type trong `src/` (grep confirm).
-- `node_modules/jiti` resolution robust với mọi monorepo layout.
+- All 7 BUGs + 4 NITs from the prior code review have been fixed with clear commits, with tests for the schema.
+- The `// LAZY:` comment has been consistently added at 11/12 dynamic import sites.
+- Lock retry logic is now unified sync ↔ async (both have deadline + retry).
+- Worktree handle crash resume works correctly (prune + branchExists fallback).
+- Artifact `contentHash` is now verifiable via `sha256(fs.readFileSync(desc.path))`.
+- No more `any` types in `src/` (grep confirmed).
+- `node_modules/jiti` resolution is robust across any monorepo layout.