pi-crew 0.8.13 → 0.9.0

package/docs/code-review-2026-05-11.md

@@ -1,30 +1,30 @@
 # Code Review Findings — pi-crew (2026-05-11)
 
 Reviewer: Droid (Factory)
-Scope: toàn bộ `pi-crew/` (src + schema + worktree + state + extension), read-only.
-Phương pháp: đối chiếu code với `AGENTS.md` (project + workspace), kiểm tra security/concurrency/cleanup theo OWASP + best practices.
+Scope: the entire `pi-crew/` directory (src + schema + worktree + state + extension), read-only.
+Method: cross-referenced code against `AGENTS.md` (project + workspace), reviewed security/concurrency/cleanup per OWASP + best practices.
 
 ---
 
-## Tóm tắt mức độ
+## Severity Summary
 
-| ID | Severity | Khu vực | Tiêu đề |
+| ID | Severity | Area | Title |
 |---|---|---|---|
-| BUG-001 | **High** | Schema / Tool dispatch | `action: "retry"` bị schema từ chối nhưng có handler |
-| BUG-002 | **High** | Artifact integrity | `contentHash` không khớp với bytes đã ghi xuống đĩa |
-| BUG-003 | Medium | AGENTS.md compliance | 12 vị trí `await import(...)` vi phạm rule "no dynamic inline imports" |
-| BUG-004 | Medium | Concurrency | `withRunLockSync` và `withRunLock` xử lý stale-lock khác nhau |
-| BUG-005 | Medium | Worktree lifecycle | `git worktree add -b <branch>` fail khi branch đã tồn tại từ run cũ |
-| BUG-006 | Low/Med | Worktree | `linkNodeModulesIfPresent` không kiểm tra source là directory |
-| BUG-007 | Low | Worktree setup hook | Hook lỗi/non-JSON bị nuốt hoàn toàn, không log |
-| NIT-001 | Low | API hygiene | `__test__renameWithRetry` được gọi từ production path |
-| NIT-002 | Low | Code style | Empty-string argv flag trong `git worktree remove` |
-| NIT-003 | Low | Immutability | `executedConfig.runtime` bị mutate khi resume |
-| NIT-004 | Low | Redaction | Cần verify transcript trên đĩa luôn được redact |
+| BUG-001 | **High** | Schema / Tool dispatch | `action: "retry"` rejected by schema but has a handler |
+| BUG-002 | **High** | Artifact integrity | `contentHash` does not match the bytes written to disk |
+| BUG-003 | Medium | AGENTS.md compliance | 12 `await import(...)` sites violate the "no dynamic inline imports" rule |
+| BUG-004 | Medium | Concurrency | `withRunLockSync` and `withRunLock` handle stale locks differently |
+| BUG-005 | Medium | Worktree lifecycle | `git worktree add -b <branch>` fails when the branch already exists from a previous run |
+| BUG-006 | Low/Med | Worktree | `linkNodeModulesIfPresent` does not verify the source is a directory |
+| BUG-007 | Low | Worktree setup hook | Errored / non-JSON hook output is swallowed entirely with no log |
+| NIT-001 | Low | API hygiene | `__test__renameWithRetry` is called from a production code path |
+| NIT-002 | Low | Code style | Empty-string argv flag in `git worktree remove` |
+| NIT-003 | Low | Immutability | `executedConfig.runtime` is mutated on resume |
+| NIT-004 | Low | Redaction | Need to verify the transcript on disk is always redacted |
 
 ---
 
-## BUG-001 — `action: "retry"` bị schema từ chối nhưng có handler
+## BUG-001 — `action: "retry"` rejected by schema but has a handler
 
 **Severity:** High
 **Files:**
@@ -33,9 +33,9 @@ Phương pháp: đối chiếu code với `AGENTS.md` (project + workspace), ki
 - `src/extension/team-tool.ts:264` (dispatch)
 - `src/extension/team-tool/cancel.ts` (`handleRetry`)
 
-### Mô tả
+### Description
 
-TypeBox schema `TeamToolParams` định nghĩa `action` là một `Type.Union` của các `Type.Literal`. Danh sách literal **không có** `"retry"`:
+The TypeBox schema `TeamToolParams` defines `action` as a `Type.Union` of `Type.Literal` values. The literal list **does not include** `"retry"`:
 
 ```ts
 // src/schema/team-tool-schema.ts:18-49
@@ -47,43 +47,43 @@ action: Type.Optional(Type.Union([
     Type.Literal("list"),
     Type.Literal("get"),
     Type.Literal("cancel"),
-    // ... KHÔNG có Type.Literal("retry") ở đây
+    // ... there is NO Type.Literal("retry") here
     Type.Literal("resume"),
     Type.Literal("respond"),
     ...
 ])),
 ```
 
-Nhưng TypeScript interface lại **có** `"retry"`:
+But the TypeScript interface **does include** `"retry"`:
 
 ```ts
 // src/schema/team-tool-schema.ts:95
 action?: "run" | "parallel" | "plan" | "status" | "list" | "get" | "cancel" | "retry" | "resume" | ...;
 ```
 
-Và `handleTeamTool` dispatch nó:
+And `handleTeamTool` dispatches it:
 
 ```ts
 // src/extension/team-tool.ts:264
 case "retry": return handleRetry(params, ctx);
 ```
 
-### Hậu quả
+### Consequences
 
-- Khi pi-coding-agent validate tool params bằng TypeBox schema (cách thông thường để gate input từ LLM), call `team {action: "retry"}` bị **reject ngay tại validation layer**, không bao giờ chạm tới `handleRetry`.
-- TS interface vs TypeBox schema lệch nhau, code path `handleRetry` là **dead code** từ góc nhìn tool runtime.
+- When pi-coding-agent validates tool params via the TypeBox schema (the usual way to gate input from the LLM), a call like `team {action: "retry"}` is **rejected at the validation layer** and never reaches `handleRetry`.
+- The TS interface and TypeBox schema are out of sync; from the tool runtime's perspective, the `handleRetry` code path is **dead code**.
 
-### Cách reproduce
+### How to reproduce
 
 ```bash
-# Từ pi REPL hoặc qua tool API:
+# From the pi REPL or via the tool API:
 team(action="retry", runId="<id>")
 # → schema validation error "must be equal to one of the allowed values"
 ```
 
-### Fix đề xuất
+### Suggested fix
 
-Thêm literal vào union và đồng bộ test:
+Add the literal to the union and sync the tests:
 
 ```ts
 // src/schema/team-tool-schema.ts
@@ -91,13 +91,13 @@ action: Type.Optional(Type.Union([
     Type.Literal("run"),
     ...
     Type.Literal("cancel"),
-    Type.Literal("retry"),   // ← thêm dòng này
+    Type.Literal("retry"),   // ← add this line
     Type.Literal("resume"),
     ...
 ])),
 ```
 
-Và thêm test trong `test/unit/team-tool-schema.test.ts`:
+And add a test in `test/unit/team-tool-schema.test.ts`:
 
 ```ts
 test("schema accepts action: retry", () => {
@@ -108,12 +108,12 @@ test("schema accepts action: retry", () => {
 
 ---
 
-## BUG-002 — `writeArtifact` ghi nội dung đã redact nhưng hash bytes gốc
+## BUG-002 — `writeArtifact` writes redacted content but hashes the original bytes
 
 **Severity:** High
 **File:** `src/state/artifact-store.ts:106-129`
 
-### Mô tả
+### Description
 
 ```ts
 // src/state/artifact-store.ts:117-121
@@ -126,43 +126,43 @@ return {
     kind: options.kind,
     path: filePath,
     ...
-    sizeBytes: stats.size,       // ← size của bytes đã redact
-    contentHash,                 // ← hash của bytes gốc, chưa redact
+    sizeBytes: stats.size,       // ← size of the redacted bytes
+    contentHash,                 // ← hash of the original, pre-redaction bytes
     ...
 };
 ```
 
-`contentHash` được compute trên `options.content` (chưa redact) trong khi file trên đĩa là `redactSecretString(options.content)`. `sizeBytes` được lấy từ `fs.statSync(filePath)` → là size của bytes đã redact.
+`contentHash` is computed on `options.content` (pre-redaction) while the file on disk is `redactSecretString(options.content)`. `sizeBytes` is taken from `fs.statSync(filePath)` → it is the size of the redacted bytes.
 
-### Hậu quả
+### Consequences
 
-- Bất kỳ consumer nào "verify integrity" bằng cách re-hash file path sẽ luôn nhận digest **khác** với `contentHash` mỗi khi nội dung gốc có chứa secret pattern.
-- `sizeBytes` và `contentHash` không nhất quán với nhau (size là post-redaction, hash là pre-redaction).
-- Comment "Compute hash on original content for integrity verification" nói **lý do** nhưng hợp đồng vẫn sai: integrity check là đối chiếu hash với file trên đĩa, không phải với memory.
+- Any consumer that "verifies integrity" by re-hashing the file path will always get a digest **different** from `contentHash` whenever the original content contains a secret pattern.
+- `sizeBytes` and `contentHash` are inconsistent with each other (size is post-redaction, hash is pre-redaction).
+- The comment "Compute hash on original content for integrity verification" states the **rationale**, but the contract is still wrong: an integrity check compares the hash against the file on disk, not against an in-memory value.
 
-### Hai phương án sửa
+### Two ways to fix
 
-**Option A — Hash post-redaction (khuyến nghị):**
+**Option A — Hash post-redaction (recommended):**
 ```ts
 const content = redactSecretString(options.content);
 atomicWriteFile(filePath, content);
 const contentHash = hashContent(content);
 const stats = fs.statSync(filePath);
 ```
-Đảm bảo `contentHash === sha256(fs.readFileSync(filePath))`. Mất khả năng "trace back to pre-redaction source" — nhưng đó là behavior an toàn cho artifact-store.
+Guarantees `contentHash === sha256(fs.readFileSync(filePath))`. You lose the ability to "trace back to the pre-redaction source" — but that is the safe behavior for the artifact store.
 
-**Option B — Lưu cả hai field nếu cần:**
+**Option B — Store both fields if needed:**
 ```ts
 return {
     ...,
     contentHash,                  // pre-redaction (source-of-truth)
-    storedContentHash: hashContent(content),  // post-redaction (đúng với file)
+    storedContentHash: hashContent(content),  // post-redaction (matches the file)
     sizeBytes: stats.size,
 };
 ```
-Sau đó update `ArtifactDescriptor` trong `src/state/types.ts:8-16` và mọi consumer.
+Then update `ArtifactDescriptor` in `src/state/types.ts:8-16` and every consumer.
 
-### Cần thêm test
+### Test to add
 
 ```ts
 test("writeArtifact: contentHash matches bytes on disk", () => {
@@ -179,14 +179,14 @@ test("writeArtifact: contentHash matches bytes on disk", () => {
 
 ---
 
-## BUG-003 — 12 vị trí `await import(...)` vi phạm rule "Avoid dynamic inline imports"
+## BUG-003 — 12 `await import(...)` sites violate the "Avoid dynamic inline imports" rule
 
-**Severity:** Medium (rule violation, không phải runtime bug)
-**Rule nguồn:** `pi-crew/AGENTS.md` — "Avoid dynamic inline imports."
+**Severity:** Medium (rule violation, not a runtime bug)
+**Source rule:** `pi-crew/AGENTS.md` — "Avoid dynamic inline imports."
 
-### Danh sách vi phạm
+### List of violations
 
-| File | Line | Module được import lazy |
+| File | Line | Module lazily imported |
 |---|---|---|
 | `src/extension/team-tool.ts` | 35 | `../runtime/team-runner.ts` |
 | `src/extension/team-tool/run.ts` | 18 | `../../runtime/team-runner.ts` |
@@ -201,35 +201,35 @@ test("writeArtifact: contentHash matches bytes on disk", () => {
 | `src/runtime/yield-handler.ts` | 9 | `ajv` |
 | `src/ui/run-action-dispatcher.ts` | 8 | `../extension/team-tool.ts` |
 
-### Phân tích
+### Analysis
 
-Một số có comment giải thích lý do (extension/team-tool.ts:33-34):
+Some have a comment explaining the reason (extension/team-tool.ts:33-34):
 > Heavy runtime — lazy-loaded to avoid 1.4s import cost at extension registration. executeTeamRun is only called when a team run actually executes.
 
-Đây là tối ưu hợp lệ. Nhưng AGENTS.md đang nói absolute "avoid", không có exception. Hai cách giải quyết:
+This is a legitimate optimization. But AGENTS.md states an absolute "avoid" with no exceptions. Two ways to resolve:
 
-**Option A — Update AGENTS.md để hợp pháp hoá lazy boundary:**
+**Option A — Update AGENTS.md to legitimize the lazy boundary:**
 ```md
 - Avoid dynamic inline imports, EXCEPT at documented lazy-load boundaries
   to defer heavy runtime cost (mark with `// LAZY: <reason>`).
 ```
 
-**Option B — Refactor về top-level imports:**
-- Move heavy modules vào separate package hoặc dùng `import type` cho type-only, runtime import vào top.
-- Có thể vẫn giữ lazy cho `runtime-resolver.ts:40` (`@mariozechner/pi-coding-agent`) vì là peer dependency optional.
+**Option B — Refactor to top-level imports:**
+- Move heavy modules into a separate package, or use `import type` for type-only and a top-level runtime import.
+- You could keep the lazy import for `runtime-resolver.ts:40` (`@mariozechner/pi-coding-agent`) because it is an optional peer dependency.
 
 ### Recommendation
 
-Chọn **Option A**, thêm comment marker `// LAZY: <reason>` cho mỗi site và thêm grep-check trong CI để chặn dynamic import không marker.
+Choose **Option A**, add a `// LAZY: <reason>` marker comment to each site, and add a grep check in CI to block unmarked dynamic imports.
 
 ---
 
-## BUG-004 — `withRunLockSync` và `withRunLock` xử lý stale-lock khác nhau
+## BUG-004 — `withRunLockSync` and `withRunLock` handle stale locks differently
 
 **Severity:** Medium
 **File:** `src/state/locks.ts:50-91`
 
-### Mô tả
+### Description
 
 **Sync path** (`acquireLockWithRetry` → `readLockState`):
 ```ts
@@ -238,9 +238,9 @@ function readLockState(filePath: string, staleMs: number): boolean {
     if (!isLockStale(filePath, staleMs)) return false;
     try {
         fs.rmSync(filePath, { force: true });
-        return true;     // ← chỉ true khi rmSync thành công
+        return true;     // ← only true when rmSync succeeds
     } catch {
-        return false;    // ← throw sẽ xảy ra ở caller
+        return false;    // ← a throw will happen at the caller
     }
 }
 
@@ -271,23 +271,23 @@ async function acquireLockWithRetryAsync(...) {
     if (Date.now() > deadline) {
         throw new Error(`Run '...' is locked by another operation.`);
     }
-    readLockStateAsync(filePath, staleMs);    // ← không check return
+    readLockStateAsync(filePath, staleMs);    // ← return value not checked
     await sleep(delay);
     attempt++;
-    // ← luôn loop lại
+    // ← always loops again
 }
 ```
 
-### Hậu quả
+### Consequences
 
-- Sync version: nếu `rmSync` fail (file đang lock bởi process khác trên Windows), throw **ngay lập tức** lần đầu tiên thấy stale lock, không retry.
-- Async version: luôn retry tới `deadline`.
+- Sync version: if `rmSync` fails (file is locked by another process on Windows), it throws **immediately** the first time it sees a stale lock, with no retry.
+- Async version: always retries until the `deadline`.
 
-Inconsistent behavior → cùng một stale-lock + transient `rmSync` race có thể fail trong sync code path nhưng pass trong async path.
+Inconsistent behavior → the same stale-lock + transient `rmSync` race can fail in the sync code path but pass in the async path.
 
-### Fix đề xuất
+### Suggested fix
 
-Đồng bộ behavior: sync version cũng nên retry tới deadline:
+Align the behavior: the sync version should also retry until the deadline:
 
 ```ts
 function acquireLockWithRetry(filePath: string, staleMs: number): void {
@@ -303,7 +303,7 @@ function acquireLockWithRetry(filePath: string, staleMs: number): void {
             if (Date.now() > deadline) {
                 throw new Error(`Run '${path.basename(filePath)}' is locked by another operation.`);
             }
-            // Try to clear stale, but don't bail on rmSync error — let loop retry
+            // Try to clear the stale lock, but don't bail on an rmSync error — let the loop retry
             try {
                 if (isLockStale(filePath, staleMs)) fs.rmSync(filePath, { force: true });
             } catch { /* race — let loop retry */ }
@@ -314,18 +314,18 @@ function acquireLockWithRetry(filePath: string, staleMs: number): void {
 }
 ```
 
-### Test cần thêm
+### Test to add
 
-Mở rộng `test/unit/locks-race.test.ts` với case: stale lock + `rmSync` race (mock fs.rmSync để throw lần đầu, pass lần thứ hai) → assert lock được acquire sau retry.
+Expand `test/unit/locks-race.test.ts` with a case: stale lock + `rmSync` race (mock `fs.rmSync` to throw the first time and pass the second) → assert the lock is acquired after a retry.
 
 ---
 
-## BUG-005 — `git worktree add -b <branch>` fail khi branch đã tồn tại từ run cũ
+## BUG-005 — `git worktree add -b <branch>` fails when the branch already exists from a previous run
 
 **Severity:** Medium
 **File:** `src/worktree/worktree-manager.ts:100-114`
 
-### Mô tả
+### Description
 
 ```ts
 // worktree-manager.ts:100-114
@@ -336,16 +336,16 @@ if (fs.existsSync(worktreePath)) {
 git(repoRoot, ["worktree", "add", "-b", branch, worktreePath, "HEAD"]);
 ```
 
-Điều kiện reuse chỉ check `worktreePath` directory. Nhưng branch `pi-crew/<runId>/<taskId>` có thể tồn tại trong git mà worktree directory đã bị xoá thủ công (hoặc `cleanupRunWorktrees` xoá directory nhưng git worktree metadata còn).
+The reuse condition only checks the `worktreePath` directory. But the branch `pi-crew/<runId>/<taskId>` can exist in git while the worktree directory was deleted manually (or `cleanupRunWorktrees` deleted the directory while the git worktree metadata remained).
 
-### Hậu quả
+### Consequences
 
-- Sau crash hoặc cleanup không hoàn chỉnh, retry/resume run sẽ fail với git error: `fatal: a branch named 'pi-crew/.../...' already exists`.
-- User bị stuck, phải manual `git branch -D`.
+- After a crash or an incomplete cleanup, a retry/resume run fails with a git error: `fatal: a branch named 'pi-crew/.../...' already exists`.
+- The user gets stuck and must run `git branch -D` manually.
 
-### Fix đề xuất
+### Suggested fix
 
-Thêm branch existence check trước `add`:
+Add a branch-existence check before `add`:
 
 ```ts
 function branchExists(repoRoot: string, branch: string): boolean {
@@ -365,27 +365,27 @@ function pruneStaleWorktrees(repoRoot: string): void {
 // In prepareTaskWorkspace, before `git worktree add`:
 pruneStaleWorktrees(repoRoot);
 if (branchExists(repoRoot, branch)) {
-    // Option 1: reuse from existing branch
+    // Option 1: reuse the existing branch
     git(repoRoot, ["worktree", "add", worktreePath, branch]);
 } else {
     git(repoRoot, ["worktree", "add", "-b", branch, worktreePath, "HEAD"]);
 }
 ```
 
-### Test cần thêm
+### Test to add
 
-`test/unit/worktree-manager.test.ts` (chưa tồn tại):
-1. Create worktree, manual delete directory (`rm -rf` không qua git), branch still exists.
-2. Call `prepareTaskWorkspace` again → expect success, not fatal.
+`test/unit/worktree-manager.test.ts` (does not yet exist):
+1. Create a worktree, manually delete the directory (`rm -rf` outside of git), branch still exists.
+2. Call `prepareTaskWorkspace` again → expect success, not a fatal error.
 
 ---
 
-## BUG-006 — `linkNodeModulesIfPresent` không kiểm tra source là directory
+## BUG-006 — `linkNodeModulesIfPresent` does not verify the source is a directory
 
 **Severity:** Low/Medium
 **File:** `src/worktree/worktree-manager.ts:43-53`
 
-### Mô tả
+### Description
 
 ```ts
 function linkNodeModulesIfPresent(repoRoot: string, worktreePath: string): boolean {
@@ -401,10 +401,10 @@ function linkNodeModulesIfPresent(repoRoot: string, worktreePath: string): boole
 }
 ```
 
-- Nếu `repoRoot/node_modules` là **file** (hiếm nhưng có thể xảy ra với corrupt setup), `existsSync` vẫn true, symlink được tạo với type `"dir"/"junction"` → behavior không xác định, đặc biệt là junction trên Windows yêu cầu directory.
-- Nếu source là **symlink to dir**, có thể link chain → khó debug.
+- If `repoRoot/node_modules` is a **file** (rare but possible with a corrupt setup), `existsSync` is still true, and the symlink is created with type `"dir"/"junction"` → undefined behavior, especially since a junction on Windows requires a directory.
+- If the source is a **symlink to a directory**, a link chain can result → hard to debug.
 
-### Fix đề xuất
+### Suggested fix
 
 ```ts
 function linkNodeModulesIfPresent(repoRoot: string, worktreePath: string): boolean {
@@ -423,16 +423,16 @@ function linkNodeModulesIfPresent(repoRoot: string, worktreePath: string): boole
 }
 ```
 
-Dùng `statSync` (theo symlink) thay vì `existsSync` để cũng bắt case "source là dangling symlink".
+Use `statSync` (follows symlinks) instead of `existsSync` to also catch the "source is a dangling symlink" case.
 
 ---
 
-## BUG-007 — Setup hook lỗi/non-JSON bị nuốt hoàn toàn, không log
+## BUG-007 — Errored / non-JSON setup hook output is swallowed entirely with no log
 
 **Severity:** Low
 **File:** `src/worktree/worktree-manager.ts:75-89`
 
-### Mô tả
+### Description
 
 ```ts
 try {
@@ -447,9 +447,9 @@ try {
 }
 ```
 
-Hook trả về JSON parse error → return `[]` silently. User không biết hook đang chạy không đúng cho tới khi worktree thiếu paths.
+The hook returns a JSON parse error → returns `[]` silently. The user has no idea the hook is misbehaving until the worktree is missing paths.
 
-### Fix đề xuất
+### Suggested fix
 
 ```ts
 } catch (error) {
@@ -459,11 +459,11 @@ Hook trả về JSON parse error → return `[]` silently. User không biết ho
 }
 ```
 
-Hoặc nếu hook output không trống nhưng JSON parse fail → emit event vào event log của run.
+Alternatively, if the hook output is non-empty but JSON parsing fails → emit an event into the run's event log.
 
 ---
 
-## NIT-001 — `__test__renameWithRetry` được gọi từ production path
+## NIT-001 — `__test__renameWithRetry` called from a production code path
 
 **File:** `src/state/atomic-write.ts:55-67, 99`
 
@@ -479,11 +479,11 @@ export function atomicWriteFile(filePath: string, content: string): void {
 }
 ```
 
-Convention: tên `__test__` ngụ ý "chỉ dùng cho test, không stable". Production sử dụng nó là smell. Đổi tên thành `renameWithRetry` (public utility) và re-export bản test với alias.
+Convention: the `__test__` name implies "test-only, not stable." Using it in production is a code smell. Rename it to `renameWithRetry` (a public utility) and re-export the test version under an alias.
 
 ---
 
-## NIT-002 — Empty-string argv flag trong `git worktree remove`
+## NIT-002 — Empty-string argv flag in `git worktree remove`
 
 **File:** `src/worktree/cleanup.ts:64`
 
@@ -491,7 +491,7 @@ Convention: tên `__test__` ngụ ý "chỉ dùng cho test, không stable". Prod
 git(manifest.cwd, ["worktree", "remove", options.force ? "--force" : "", worktreePath].filter(Boolean));
 ```
 
-Pattern `cond ? "--force" : ""` rồi `.filter(Boolean)` hoạt động nhưng dễ gãy. Tốt hơn:
+The `cond ? "--force" : ""` then `.filter(Boolean)` pattern works but is fragile. Better:
 
 ```ts
 const args = ["worktree", "remove"];
@@ -502,7 +502,7 @@ git(manifest.cwd, args);
 
 ---
 
-## NIT-003 — `executedConfig.runtime` bị mutate khi resume
+## NIT-003 — `executedConfig.runtime` mutated on resume
 
 **File:** `src/extension/team-tool.ts:184-190`
 
@@ -514,7 +514,7 @@ if (!executedConfig.runtime?.mode && resumeManifest.runtimeResolution?.safety ==
 }
 ```
 
-Code có thể đang assume `effectiveRunConfig` trả về object mới. Cần verify và document immutability, hoặc thay bằng explicit clone:
+The code may be assuming `effectiveRunConfig` returns a fresh object. Verify and document immutability, or replace with an explicit clone:
 
 ```ts
 const executedConfig: PiTeamsConfig = {
@@ -524,9 +524,9 @@ const executedConfig: PiTeamsConfig = {
 
 ---
 
-## NIT-004 — Verify transcript trên đĩa luôn được redact
+## NIT-004 — Verify the transcript on disk is always redacted
 
-**File:** `src/runtime/child-pi.ts:148-152`, đối chiếu với `recoverCheckpointedTasks` (`src/extension/team-tool.ts:155-156`)
+**File:** `src/runtime/child-pi.ts:148-152`, cross-referenced with `recoverCheckpointedTasks` (`src/extension/team-tool.ts:155-156`)
 
 ```ts
 // child-pi.ts:148-152
@@ -537,7 +537,7 @@ function appendTranscript(input: ChildPiRunInput, line: string): void {
 }
 ```
 
-Transcript được redact qua `redactJsonLine` — good. Nhưng trong recovery path:
+The transcript is redacted via `redactJsonLine` — good. But in the recovery path:
 
 ```ts
 // team-tool.ts:155-156
@@ -549,44 +549,44 @@ const resultArtifact = writeArtifact(manifest.artifactsRoot, {
 });
 ```
 
-Vì `writeArtifact` lại redact thêm lần nữa (đã verify ở BUG-002), double-redaction là idempotent (`***` không match secret pattern). OK.
+Because `writeArtifact` redacts again (verified in BUG-002), double-redaction is idempotent (`***` does not match the secret pattern). OK.
 
-**Action:** thêm test `test/unit/redaction-transcript-roundtrip.test.ts`:
-1. Spawn mock child producing JSON line với secret.
-2. Read transcript file → assert không có secret raw.
-3. Run `recoverCheckpointedTasks` → assert result artifact cũng không có secret.
+**Action:** add a test `test/unit/redaction-transcript-roundtrip.test.ts`:
+1. Spawn a mock child producing a JSON line with a secret.
+2. Read the transcript file → assert it contains no raw secret.
+3. Run `recoverCheckpointedTasks` → assert the result artifact also contains no secret.
 
 ---
 
-## Gaps về test coverage
+## Test coverage gaps
 
-| Module | Trạng thái |
+| Module | Status |
 |---|---|
-| `src/worktree/worktree-manager.ts` | Chỉ có `branch-freshness.test.ts`. Thiếu test cho `prepareTaskWorkspace` (reuse path, branch mismatch, setupHook). |
-| `src/worktree/cleanup.ts` | Có `lifecycle-actions.test.ts` indirect. Thiếu test trực tiếp cho dirty-preserve + diff artifact. |
-| `src/state/locks.ts` (sync vs async parity) | `locks-race.test.ts` + `api-locks.test.ts` không assert sự khác biệt nêu ở BUG-004. |
-| `src/state/artifact-store.ts` | Cần test hash/size match (BUG-002). |
-| `src/schema/team-tool-schema.ts` | `team-tool-schema.test.ts` không có case cho `retry` (BUG-001). |
+| `src/worktree/worktree-manager.ts` | Only has `branch-freshness.test.ts`. Missing tests for `prepareTaskWorkspace` (reuse path, branch mismatch, setupHook). |
+| `src/worktree/cleanup.ts` | Has `lifecycle-actions.test.ts` indirectly. Missing a direct test for dirty-preserve + diff artifact. |
+| `src/state/locks.ts` (sync vs async parity) | `locks-race.test.ts` + `api-locks.test.ts` do not assert the difference described in BUG-004. |
+| `src/state/artifact-store.ts` | Needs a hash/size match test (BUG-002). |
+| `src/schema/team-tool-schema.ts` | `team-tool-schema.test.ts` has no case for `retry` (BUG-001). |
 
 ---
 
-## Điểm tích cực
+## Positives
 
-- **Path-traversal guards** trong `resolveInside` (`artifact-store.ts:96-105`) combine cả relative-segment check, `path.relative` check và `path.normalize + startsWith(base + sep)`.
-- **Atomic write** dùng `O_EXCL | O_NOFOLLOW`, post-open `fstatSync().isFile()` verification, Windows EPERM/EBUSY rename retry.
-- **Process management** trong `child-pi.ts` track PID trong `activeChildProcesses`, hỗ trợ `taskkill /T /F` (Win) + `process.kill(-pid, ...)` (POSIX), có hard-kill fallback và post-exit stdio guard.
-- **Env-secret filtering** trước khi spawn child Pi (`child-pi.ts:113`) dùng `SECRET_KEY_PATTERN` để loại token/api_key/password khỏi env.
-- **Default-safe execution**: `executeWorkers=false` / `PI_CREW_EXECUTE_WORKERS=0` / `PI_TEAMS_EXECUTE_WORKERS=0` block worker; `runtime.mode=scaffold` cho dry-run.
-- **Index.ts minimal**: đúng rule, chỉ 5 dòng.
-- **Lockstep destructive gates**: `delete` requires `confirm:true`, referenced resources block trừ khi `force:true` (verified ở `management.ts:344-353`).
+- **Path-traversal guards** in `resolveInside` (`artifact-store.ts:96-105`) combine a relative-segment check, a `path.relative` check, and a `path.normalize + startsWith(base + sep)` check.
+- **Atomic write** uses `O_EXCL | O_NOFOLLOW`, a post-open `fstatSync().isFile()` verification, and a Windows EPERM/EBUSY rename retry.
+- **Process management** in `child-pi.ts` tracks the PID in `activeChildProcesses`, supports `taskkill /T /F` (Win) + `process.kill(-pid, ...)` (POSIX), has a hard-kill fallback, and a post-exit stdio guard.
+- **Env-secret filtering** before spawning the child Pi (`child-pi.ts:113`) uses `SECRET_KEY_PATTERN` to strip token/api_key/password from the env.
+- **Default-safe execution**: `executeWorkers=false` / `PI_CREW_EXECUTE_WORKERS=0` / `PI_TEAMS_EXECUTE_WORKERS=0` block workers; `runtime.mode=scaffold` for dry-runs.
+- **Index.ts minimal**: follows the rule, only 5 lines.
+- **Lockstep destructive gates**: `delete` requires `confirm:true`, referenced resources block unless `force:true` (verified in `management.ts:344-353`).
 
 ---
 
-## Đề xuất ưu tiên fix
+## Suggested fix priority
 
-1. **BUG-001** (5 phút): thêm 1 dòng `Type.Literal("retry")` + 1 test.
-2. **BUG-002** (15 phút): chọn Option A, đổi thứ tự hash/write + thêm test integrity.
-3. **BUG-004** (30 phút): đồng bộ sync/async lock retry behavior + test.
-4. **BUG-005** (1 giờ): thêm branch existence check + worktree prune trước add, viết test.
-5. **BUG-003** (1 giờ): update AGENTS.md với rule exception cho lazy boundaries, thêm marker comments.
-6. Phần còn lại: batch trong release sau.
+1. **BUG-001** (5 minutes): add one line `Type.Literal("retry")` + 1 test.
+2. **BUG-002** (15 minutes): choose Option A, swap the hash/write order + add an integrity test.
+3. **BUG-004** (30 minutes): align the sync/async lock retry behavior + test.
+4. **BUG-005** (1 hour): add a branch-existence check + worktree prune before add, write tests.
+5. **BUG-003** (1 hour): update AGENTS.md with a rule exception for lazy boundaries, add marker comments.
+6. The rest: batch into a later release.