pi-crew 0.8.13 → 0.9.0

package/docs/followup-review-round3-2026-05-12.md

@@ -1,60 +1,60 @@
 # Follow-up Review — pi-crew (2026-05-12, round 3)
 
-Tác giả: Droid (Factory) | Liên quan: `docs/code-review-2026-05-11.md`, `docs/followup-plan-2026-05-12.md`, `docs/followup-review-2026-05-12.md`. HEAD: `5bee878`.
+Author: Droid (Factory) | Related: `docs/code-review-2026-05-11.md`, `docs/followup-plan-2026-05-12.md`, `docs/followup-review-2026-05-12.md`. HEAD: `5bee878`.
 
-Đây là vòng review sau khi commit `5bee878` đã giải quyết C1–C6. Mục tiêu: rà soát các module chưa được soi kỹ (event-log, atomic-write, child-pi, redaction, sleep, hooks, cleanup) để tìm rủi ro còn lại.
+This is the review round after commit `5bee878` resolved C1–C6. Goal: scrutinize the modules not yet examined closely (event-log, atomic-write, child-pi, redaction, sleep, hooks, cleanup) to find remaining risks.
 
-## Tóm tắt kết quả
+## Result summary
 
 - `npm run typecheck` → Passed
 - `npm run check:lazy-imports` → Passed
 - `npm run test:unit` → **1418 tests / 1415 pass / 0 fail / 3 skip** (212s)
 
-Codebase ở trạng thái ổn định. Các phát hiện dưới đây là **risk thấp** hoặc **defense-in-depth**, không phải bug khẩn.
+The codebase is in a stable state. The findings below are **low risk** or **defense-in-depth**, not urgent bugs.
 
 ---
 
-## Phần A — Phát hiện mới
+## Part A — New findings
 
-### D1 — `event-log.appendEvent` không lock, JSONL có thể interleave trên Windows
+### D1 — `event-log.appendEvent` has no lock, JSONL may interleave on Windows
 
-**Severity:** Medium | **Effort:** ~30 phút | **File:** `src/state/event-log.ts:148`
+**Severity:** Medium | **Effort:** ~30 minutes | **File:** `src/state/event-log.ts:148`
 
-**Hiện trạng:**
+**Current state:**
 ```ts
 fs.appendFileSync(eventsPath, `${JSON.stringify(redactSecrets(fullEvent))}\n`, "utf-8");
 ```
 
-**Vấn đề:**
-- `fs.appendFileSync` trên POSIX chỉ atomic cho write nhỏ hơn `PIPE_BUF` (~4 KiB). Event JSON đầy đủ (có data, metadata, transcripts) có thể vượt ngưỡng → interleave dòng giữa 2 process (parent + background-runner).
-- Trên Windows, append KHÔNG atomic cho mọi kích thước; 2 process append cùng eventsPath có thể tạo dòng JSON xen lẫn → `JSON.parse(line)` ở `readEvents`/`scanSequence` throw và bỏ qua dòng.
-- Hệ quả: mất event, sequence số tăng nhảy, "appended: false" được trả về trong path khác (size-limit) nhưng path bình thường không có hint.
+**Problem:**
+- `fs.appendFileSync` on POSIX is only atomic for writes smaller than `PIPE_BUF` (~4 KiB). A full event JSON (with data, metadata, transcripts) can exceed that → interleaved lines between 2 processes (parent + background-runner).
+- On Windows, append is NOT atomic at any size; 2 processes appending to the same eventsPath can produce interleaved JSON lines → `JSON.parse(line)` in `readEvents`/`scanSequence` throws and skips the line.
+- Consequence: lost events, sequence numbers jumping, "appended: false" is returned in a different path (size-limit) but the normal path gives no hint.
 
-**Trigger:** chạy `background-runner` song song với parent ghi event trên cùng `eventsPath` (vd. cancel + retry liên tục).
+**Trigger:** running `background-runner` in parallel with the parent writing events to the same `eventsPath` (e.g. cancel + retry in succession).
 
-**Fix đề xuất:**
-1. Wrap `appendEvent` trong `withRunLockSync(manifest, () => { ... })` — đảm bảo exclusive access.
-2. Hoặc dùng `fs.openSync(..., O_APPEND | O_WRONLY)` + retry với advisory lock (`flock` POSIX, `LockFileEx` Windows — qua npm package `proper-lockfile`).
-3. Phương án nhẹ nhất: chuyển sang `appendEventAsync` qua queue/serialize.
+**Proposed fix:**
+1. Wrap `appendEvent` in `withRunLockSync(manifest, () => { ... })` — ensures exclusive access.
+2. Or use `fs.openSync(..., O_APPEND | O_WRONLY)` + retry with an advisory lock (`flock` POSIX, `LockFileEx` Windows — via the npm package `proper-lockfile`).
+3. Lightest option: switch to `appendEventAsync` via a queue/serialize.
 
-**Test cần thêm:** stress test ở `test/integration/`: 2 process append đồng thời 100 events mỗi bên → assert tổng số dòng parse OK = 200.
+**Tests to add:** stress test in `test/integration/`: 2 processes each appending 100 events concurrently → assert total parseable line count = 200.
 
 ---
 
-### D2 — `event-log.sequenceCache` Map leak theo số lượng runs
+### D2 — `event-log.sequenceCache` Map leaks by number of runs
 
-**Severity:** Low | **Effort:** ~10 phút | **File:** `src/state/event-log.ts:60`
+**Severity:** Low | **Effort:** ~10 minutes | **File:** `src/state/event-log.ts:60`
 
-**Hiện trạng:**
+**Current state:**
 ```ts
 const sequenceCache = new Map<string, { size: number; mtimeMs: number; seq: number }>();
 ```
 
-**Vấn đề:**
-- Module-level map, không bao giờ evict. Mỗi `eventsPath` (1 per run) chiếm 1 entry. Long-running parent process (vd. live-session-runtime) duy trì nhiều ngày → cache có thể tới hàng nghìn entries.
-- Memory không lớn (~100 bytes/entry) nhưng vô hạn.
+**Problem:**
+- Module-level map, never evicts. Each `eventsPath` (1 per run) takes 1 entry. A long-running parent process (e.g. live-session-runtime) running for many days → the cache could reach thousands of entries.
+- Memory isn't large (~100 bytes/entry) but is unbounded.
 
-**Fix đề xuất:** dùng LRU đơn giản (Map có max size, evict oldest khi vượt ngưỡng), hoặc clear sau khi run kết thúc:
+**Proposed fix:** use a simple LRU (Map with a max size, evict oldest when exceeding the threshold), or clear after the run ends:
 ```ts
 export function evictSequenceCache(eventsPath: string): void {
 	sequenceCache.delete(eventsPath);
@@ -64,11 +64,11 @@ export function evictSequenceCache(eventsPath: string): void {
 
 ---
 
-### D3 — `atomicWriteFileAsync` có fallback "matches" → sync không có (parity)
+### D3 — `atomicWriteFileAsync` has a "matches" fallback → sync path doesn't (parity)
 
-**Severity:** Low | **Effort:** ~15 phút | **File:** `src/state/atomic-write.ts:122-138`
+**Severity:** Low | **Effort:** ~15 minutes | **File:** `src/state/atomic-write.ts:122-138`
 
-**Hiện trạng:**
+**Current state:**
 ```ts
 // async path:
 try { await renameWithRetryAsync(...); }
@@ -79,15 +79,15 @@ catch (renameError) {
 	throw renameError;
 }
 
-// sync path: chỉ throw, không có fallback "matches".
+// sync path: just throws, no "matches" fallback.
 ```
 
-**Vấn đề:**
-- Async path "tha thứ" cho race condition (file đã được ghi đúng content bởi process khác). Sync path thì throw cứng.
-- Ngữ nghĩa khác nhau → khó debug khi có ai dùng sync với race.
-- Trường hợp này hiếm (cùng content), nhưng asymmetry là code smell.
+**Problem:**
+- The async path "forgives" the race condition (the file was already written with the correct content by another process). The sync path throws hard.
+- Different semantics → hard to debug when someone uses sync with a race.
+- This case is rare (identical content), but the asymmetry is a code smell.
 
-**Fix đề xuất:** thêm cùng fallback cho sync, hoặc xoá fallback khỏi async (chọn 1 quy ước nhất quán):
+**Proposed fix:** add the same fallback to sync, or remove the fallback from async (pick one consistent convention):
 ```ts
 } catch (renameError) {
 	try {
@@ -103,22 +103,22 @@ catch (renameError) {
 
 ---
 
-### D4 — `withRunLock` (async) chờ deadline cho active lock, `withRunLockSync` throw ngay
+### D4 — `withRunLock` (async) waits until the deadline for an active lock, `withRunLockSync` throws immediately
 
-**Severity:** Low | **Effort:** ~10 phút | **File:** `src/state/locks.ts:91-110`
+**Severity:** Low | **Effort:** ~10 minutes | **File:** `src/state/locks.ts:91-110`
 
-**Hiện trạng:**
-- Sync: `if (!isLockStale(...)) throw ...` → fail fast cho active lock.
-- Async: chỉ check stale trong `readLockStateAsync`, không throw cho active → loop chờ tới deadline (`staleMs * 2`, thường 60s).
+**Current state:**
+- Sync: `if (!isLockStale(...)) throw ...` → fail fast for an active lock.
+- Async: only checks staleness in `readLockStateAsync`, doesn't throw for active → loops waiting until the deadline (`staleMs * 2`, usually 60s).
 
-**Vấn đề:**
-- Test `withRunLockSync throws immediately on active (non-stale) lock` đã chứng minh sync throw ngay.
-- Async sẽ hang ~60s rồi mới throw → trải nghiệm cancel/retry chậm.
-- BUG-004 (round 1) đặt mục tiêu unify sync ↔ async, nhưng vẫn còn asymmetry semantic này.
+**Problem:**
+- The test `withRunLockSync throws immediately on active (non-stale) lock` proves sync throws immediately.
+- Async will hang ~60s then throw → slow cancel/retry experience.
+- BUG-004 (round 1) aimed to unify sync ↔ async, but this semantic asymmetry remains.
 
-**Fix đề xuất:** thống nhất theo 1 trong 2:
-- Sync: thêm short wait + retry tương tự async (chờ tối đa 1-2s rồi throw).
-- Async: throw ngay khi lock không stale (giống sync) — thường tốt hơn vì caller có thể tự retry với context cao hơn.
+**Proposed fix:** unify by one of:
+- Sync: add a short wait + retry like async (wait up to 1-2s then throw).
+- Async: throw immediately when the lock isn't stale (like sync) — usually better since the caller can retry with higher context.
 
 ```ts
 async function acquireLockWithRetryAsync(filePath: string, staleMs: number): Promise<void> {
@@ -141,25 +141,25 @@ async function acquireLockWithRetryAsync(filePath: string, staleMs: number): Pro
 }
 ```
 
-**Test cần thêm:** mirror test sync — `withRunLock async throws immediately on active (non-stale) lock`.
+**Tests to add:** mirror the sync test — `withRunLock async throws immediately on active (non-stale) lock`.
 
 ---
 
-### D5 — `sleep.ts` dùng `require()` trong ES module
+### D5 — `sleep.ts` uses `require()` in an ES module
 
-**Severity:** Low (style) | **Effort:** ~5 phút | **File:** `src/utils/sleep.ts:18`
+**Severity:** Low (style) | **Effort:** ~5 minutes | **File:** `src/utils/sleep.ts:18`
 
-**Hiện trạng:**
+**Current state:**
 ```ts
 const { execFileSync } = require("node:child_process") as typeof import("node:child_process");
 ```
 
-**Vấn đề:**
-- Project là ESM (`"type": "module"`). `require` chỉ work qua strip-types backward-compat — chưa chuẩn.
-- AGENTS.md: "Avoid dynamic inline imports, EXCEPT at documented lazy-load boundaries to defer heavy runtime cost (mark with `// LAZY: <reason>`)". `require` ở đây không có marker.
-- `child_process` không nặng — top-level import OK.
+**Problem:**
+- The project is ESM (`"type": "module"`). `require` only works via strip-types backward-compat — not clean.
+- AGENTS.md: "Avoid dynamic inline imports, EXCEPT at documented lazy-load boundaries to defer heavy runtime cost (mark with `// LAZY: <reason>`)". This `require` has no marker.
+- `child_process` isn't heavy — top-level import is fine.
 
-**Fix đề xuất:**
+**Proposed fix:**
 ```ts
 import { execFileSync } from "node:child_process";
 // ...
@@ -168,20 +168,20 @@ execFileSync("sleep", [(ms / 1000).toFixed(3)], { timeout: ms + 1000, stdio: "pi
 
 ---
 
-### D6 — `iteration-hooks.runIterationHook` chưa filter env như post-checks
+### D6 — `iteration-hooks.runIterationHook` doesn't filter env like post-checks
 
-**Severity:** Low | **Effort:** ~5 phút | **File:** `src/runtime/iteration-hooks.ts:140`
+**Severity:** Low | **Effort:** ~5 minutes | **File:** `src/runtime/iteration-hooks.ts:140`
 
-**Hiện trạng:**
+**Current state:**
 ```ts
 env: { PATH: process.env.PATH ?? "/usr/bin:/bin", HOME: process.env.HOME ?? "/tmp", USER: process.env.USER, LANG: process.env.LANG, PI_CREW_HOOK: "1" },
 ```
 
-**Vấn đề:**
-- Đã restrict thủ công, OK với Linux. Nhưng trên Windows thiếu `USERPROFILE`, `TEMP`, `TMP`, `ComSpec`, `SystemRoot` → script `.cmd/.ps1` có thể fail.
-- Post-checks.ts có cùng pattern (line 82) — không nhất quán với worktree-manager.runSetupHook đã chuyển sang `sanitizeEnvSecrets(..., { allowList: [...] })`.
+**Problem:**
+- Already restricted manually, OK for Linux. But on Windows it lacks `USERPROFILE`, `TEMP`, `TMP`, `ComSpec`, `SystemRoot` → `.cmd/.ps1` scripts may fail.
+- post-checks.ts has the same pattern (line 82) — inconsistent with worktree-manager.runSetupHook which moved to `sanitizeEnvSecrets(..., { allowList: [...] })`.
 
-**Fix đề xuất:** áp dụng `sanitizeEnvSecrets` với allowList, đồng nhất 3 chỗ (post-checks, iteration-hooks, setup-hook):
+**Proposed fix:** apply `sanitizeEnvSecrets` with an allowList, unifying all 3 sites (post-checks, iteration-hooks, setup-hook):
 ```ts
 import { sanitizeEnvSecrets } from "../utils/env-filter.ts";
 const HOOK_ENV_ALLOW = ["PATH", "HOME", "USER", "USERPROFILE", "TEMP", "TMP", "TMPDIR", "LANG", "LC_ALL", "ComSpec", "SystemRoot", "PI_*"];
@@ -189,30 +189,30 @@ const HOOK_ENV_ALLOW = ["PATH", "HOME", "USER", "USERPROFILE", "TEMP", "TMP", "T
 env: { ...sanitizeEnvSecrets(process.env, { allowList: HOOK_ENV_ALLOW }), PI_CREW_HOOK: "1" },
 ```
 
-**Lợi ích:**
-- 1 nguồn truth cho whitelist env hook.
-- Hỗ trợ Windows .cmd/.ps1 (USERPROFILE/TEMP cần thiết).
-- Tránh lặp code.
+**Benefits:**
+- 1 source of truth for the hook env whitelist.
+- Supports Windows .cmd/.ps1 (USERPROFILE/TEMP needed).
+- Avoids code duplication.
 
 ---
 
-### D7 — `cleanup.ts` git helper không force locale (consistency với worktree-manager)
+### D7 — `cleanup.ts` git helper doesn't force locale (consistency with worktree-manager)
 
-**Severity:** Info | **Effort:** ~2 phút | **File:** `src/worktree/cleanup.ts:15`
+**Severity:** Info | **Effort:** ~2 minutes | **File:** `src/worktree/cleanup.ts:15`
 
-**Hiện trạng:**
+**Current state:**
 ```ts
 function git(cwd: string, args: string[]): string {
 	return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
 }
 ```
 
-**Vấn đề:**
-- `worktree-manager.ts` đã force `LANG: "C", LC_ALL: "C"` (C5 round 2). `cleanup.ts` chưa.
-- Không gây bug hiện tại vì cleanup không parse error string; nhưng tương lai nếu thêm error parsing thì lại miss.
-- `branch-freshness.ts` cũng cùng vấn đề.
+**Problem:**
+- `worktree-manager.ts` already forces `LANG: "C", LC_ALL: "C"` (C5 round 2). `cleanup.ts` doesn't yet.
+- Doesn't cause a current bug because cleanup doesn't parse error strings; but if error parsing is added later, this gets missed again.
+- `branch-freshness.ts` has the same issue.
 
-**Fix đề xuất:** extract `git()` helper vào `src/utils/git-helper.ts` chung, dùng ở cả 3 file:
+**Proposed fix:** extract a `git()` helper into a shared `src/utils/git-helper.ts`, used by all 3 files:
 ```ts
 // src/utils/git-exec.ts
 import { execFileSync } from "node:child_process";
@@ -226,44 +226,44 @@ export function gitExec(cwd: string, args: string[]): string {
 
 ---
 
-### D8 — `redaction.PEM_PRIVATE_KEY_PATTERN` không giới hạn độ dài → tiềm năng ReDoS thấp
+### D8 — `redaction.PEM_PRIVATE_KEY_PATTERN` has no length limit → low ReDoS potential
 
-**Severity:** Info | **Effort:** ~5 phút | **File:** `src/utils/redaction.ts:7`
+**Severity:** Info | **Effort:** ~5 minutes | **File:** `src/utils/redaction.ts:7`
 
-**Hiện trạng:**
+**Current state:**
 ```ts
 const PEM_PRIVATE_KEY_PATTERN = /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g;
 ```
 
-**Vấn đề:**
-- Lazy `[\s\S]*?` an toàn về ReDoS, nhưng nếu input có 1 BEGIN mà không có END → backtrack tới hết string. Với JSONL transcript dài (10+ MB), regex sẽ scan toàn bộ.
-- Không phải ReDoS thực sự (linear), nhưng có thể chậm.
+**Problem:**
+- The lazy `[\s\S]*?` is ReDoS-safe, but if the input has a BEGIN without an END → backtracks to the end of the string. With a long JSONL transcript (10+ MB), the regex scans the whole thing.
+- Not a true ReDoS (linear), but can be slow.
 
-**Fix đề xuất:** thêm hard limit 64KB cho block PEM (PEM thực tế ~3KB):
+**Proposed fix:** add a hard 64KB limit for a PEM block (real PEM ~3KB):
 ```ts
 const PEM_PRIVATE_KEY_PATTERN = /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]{0,65536}?-----END [A-Z ]*PRIVATE KEY-----/g;
 ```
 
-Trade-off: PEM > 64KB không được redact đầy đủ. Hiếm trong thực tế.
+Trade-off: PEM > 64KB won't be fully redacted. Rare in practice.
 
 ---
 
-### D9 — `subagent-manager.persistedSubagentPath` không validate `id` → path traversal tiềm năng
+### D9 — `subagent-manager.persistedSubagentPath` doesn't validate `id` → potential path traversal
 
-**Severity:** Low | **Effort:** ~5 phút | **File:** `src/runtime/subagent-manager.ts:58`
+**Severity:** Low | **Effort:** ~5 minutes | **File:** `src/runtime/subagent-manager.ts:58`
 
-**Hiện trạng:**
+**Current state:**
 ```ts
 function persistedSubagentPath(cwd: string, id: string): string {
 	return path.join(projectCrewRoot(cwd), DEFAULT_PATHS.state.subagentsSubdir, `${id}.json`);
 }
 ```
 
-**Vấn đề:**
-- `id` đang được sinh nội bộ (`agent_${Date.now().toString(36)}_${counter.toString(36)}`) → an toàn.
-- Nhưng `readPersistedSubagentRecord(cwd, id)` được gọi với `id` từ external source (vd. `get_subagent_result` tool param). Nếu validation tool param thiếu, `id = "../../../etc/passwd"` có thể đọc file ngoài state dir.
+**Problem:**
+- `id` is currently generated internally (`agent_${Date.now().toString(36)}_${counter.toString(36)}`) → safe.
+- But `readPersistedSubagentRecord(cwd, id)` is called with `id` from an external source (e.g. `get_subagent_result` tool param). If tool param validation is missing, `id = "../../../etc/passwd"` could read a file outside the state dir.
 
-**Fix đề xuất:** validate `id` matches `^[a-z0-9_]+$`:
+**Proposed fix:** validate `id` matches `^[a-z0-9_]+$`:
 ```ts
 function isValidSubagentId(id: string): boolean {
 	return /^[a-z0-9_]+$/i.test(id) && id.length <= 128;
@@ -274,59 +274,59 @@ function persistedSubagentPath(cwd: string, id: string): string {
 }
 ```
 
-Kiểm tra schema tool `get_subagent_result` để xem có sanitize id chưa; nếu có thì D9 chỉ là defense-in-depth.
+Check the `get_subagent_result` tool schema to see if it sanitizes id already; if so, D9 is just defense-in-depth.
 
 ---
 
-## Ưu tiên thực hiện
+## Implementation priority
 
-| # | Item | Severity | Effort | Khuyến nghị |
+| # | Item | Severity | Effort | Recommendation |
 |---|---|---|---|---|
-| 1 | D1 (event-log concurrent append) | Medium | 30 phút | Sprint hiện tại — chống event loss/corruption |
-| 2 | D6 (hook env allowList nhất quán) | Low | 5 phút | Sprint hiện tại — đồng bộ với setup-hook fix |
-| 3 | D4 (async lock fail-fast cho active) | Low | 10 phút | Sprint hiện tại — UX cancel/retry |
-| 4 | D9 (subagent id validate) | Low | 5 phút | Sprint hiện tại — defense-in-depth |
-| 5 | D2 (sequenceCache eviction) | Low | 10 phút | Sprint kế tiếp |
-| 6 | D3 (atomic-write sync/async parity) | Low | 15 phút | Sprint kế tiếp |
-| 7 | D5 (sleep.ts ESM require) | Low | 5 phút | Sprint kế tiếp |
-| 8 | D7 (git helper consolidate) | Info | 2 phút | Lúc nào cũng được |
-| 9 | D8 (PEM regex limit) | Info | 5 phút | Lúc nào cũng được |
-
-**Tổng effort priority 1 (must-fix):** ~50 phút.
-**Tổng effort priority 2 (nice-to-have):** ~37 phút.
+| 1 | D1 (event-log concurrent append) | Medium | 30 minutes | Current sprint — prevent event loss/corruption |
+| 2 | D6 (consistent hook env allowList) | Low | 5 minutes | Current sprint — sync with the setup-hook fix |
+| 3 | D4 (async lock fail-fast for active) | Low | 10 minutes | Current sprint — cancel/retry UX |
+| 4 | D9 (subagent id validate) | Low | 5 minutes | Current sprint — defense-in-depth |
+| 5 | D2 (sequenceCache eviction) | Low | 10 minutes | Next sprint |
+| 6 | D3 (atomic-write sync/async parity) | Low | 15 minutes | Next sprint |
+| 7 | D5 (sleep.ts ESM require) | Low | 5 minutes | Next sprint |
+| 8 | D7 (git helper consolidate) | Info | 2 minutes | Anytime |
+| 9 | D8 (PEM regex limit) | Info | 5 minutes | Anytime |
+
+**Total effort priority 1 (must-fix):** ~50 minutes.
+**Total effort priority 2 (nice-to-have):** ~37 minutes.
 
 ---
 
-## Đề xuất commit batches
+## Proposed commit batches
 
-- **Batch 1 (correctness/security):** D1 + D9 + D4 → 1 PR "event-log lock + subagent id guard + async lock parity" (~45 phút).
-- **Batch 2 (hardening):** D6 + D7 + D2 → 1 PR "hook env allowList consolidation + git helper extract + cache eviction" (~20 phút).
-- **Batch 3 (polish):** D3 + D5 + D8 → 1 PR "atomic-write parity + ESM cleanup + redaction limit" (~25 phút).
+- **Batch 1 (correctness/security):** D1 + D9 + D4 → 1 PR "event-log lock + subagent id guard + async lock parity" (~45 minutes).
+- **Batch 2 (hardening):** D6 + D7 + D2 → 1 PR "hook env allowList consolidation + git helper extract + cache eviction" (~20 minutes).
+- **Batch 3 (polish):** D3 + D5 + D8 → 1 PR "atomic-write parity + ESM cleanup + redaction limit" (~25 minutes).
 
 ---
 
-## Điểm tích cực sau round 3
+## Positive notes after round 3
 
-- Tất cả C1–C6 (round 2) đã fix đúng theo spec.
-- 1418 tests pass (so với 1411 round trước → +7 test mới), 0 fail.
-- `npm run check:lazy-imports` đã chạy được trên Windows (sau khi loại bỏ `sed`).
-- `sanitizeEnvSecrets` có cả deny-list (default) và allow-list mode → flexibility tốt.
-- `resolveShellForScript` xử lý đúng `.bat/.cmd` chống CVE-2024-27980.
-- `parent-guard` polling tốt cho cross-platform (POSIX + Windows).
-- Redaction pipeline đa lớp (key-name + inline-substring + auth-header + bearer + PEM).
-- Atomic-write có O_EXCL + O_NOFOLLOW + post-open `isFile()` verify.
-- Subagent records persisted dưới redaction filter.
-- Background runner có `parent-guard` + cleanup tempdir + final-drain timer.
+- All C1–C6 (round 2) fixed correctly per spec.
+- 1418 tests pass (vs 1411 the previous round → +7 new tests), 0 fail.
+- `npm run check:lazy-imports` now runs on Windows (after removing `sed`).
+- `sanitizeEnvSecrets` has both a deny-list (default) and an allow-list mode → good flexibility.
+- `resolveShellForScript` correctly handles `.bat/.cmd` to guard against CVE-2024-27980.
+- `parent-guard` polling works well cross-platform (POSIX + Windows).
+- Multi-layer redaction pipeline (key-name + inline-substring + auth-header + bearer + PEM).
+- Atomic-write has O_EXCL + O_NOFOLLOW + post-open `isFile()` verification.
+- Subagent records persisted under the redaction filter.
+- Background runner has `parent-guard` + tempdir cleanup + final-drain timer.
 
 ---
 
-## Vùng KHÔNG có vấn đề nghiêm trọng (đã rà)
+## Areas with NO serious issues (reviewed)
 
-- `src/schema/team-tool-schema.ts` — TypeBox schema có đủ literal "retry", strict additionalProperties.
-- `src/state/artifact-store.ts` — path traversal blocking 2 lớp (`resolveInside` + `resolveRealContainedPath`), hash post-redaction.
+- `src/schema/team-tool-schema.ts` — TypeBox schema has the "retry" literal, strict additionalProperties.
+- `src/state/artifact-store.ts` — 2-layer path traversal blocking (`resolveInside` + `resolveRealContainedPath`), post-redaction hash.
 - `src/state/atomic-write.ts` — symlink-safe, O_EXCL, fd-based stat verification.
 - `src/worktree/worktree-manager.ts` — branchExists local+remote, prune stale, env filter, locale-safe error parse.
-- `src/runtime/async-runner.ts` — jiti + strip-types fallback, đa candidate path.
+- `src/runtime/async-runner.ts` — jiti + strip-types fallback, multi-candidate path.
 - `src/runtime/child-pi.ts` — env sanitize, redacted transcript, post-exit stdio guard, hard kill timer.
 - `src/runtime/parent-guard.ts` — kill(pid,0) cross-platform, unref'd interval.
 

package/docs/goals.md

@@ -0,0 +1,59 @@
+# Goal Loops (`team action='goal')
+
+pi-crew v0.9.0 introduces an autonomous goal loop, modeled on Claude Code's `/goal`.
+
+## What it does
+
+A goal loop turns a single objective into a long-running, self-directed multi-turn
+process:
+
+1. A **worker** agent does one turn of work (`executeTeamRun`).
+2. A separate **evaluator** model (the "goal-judge") reads the turn's transcript +
+   tool calls + verification results and returns a verdict:
+   `{ achieved: bool, reason: string, evidenceRefs?: string[] }`.
+3. If **not achieved**, the `reason` is prepended to the next turn's prompt and the
+   loop continues.
+4. Stops on: `achieved` / `maxTurns` reached / `budgetAbort` exceeded / `BLOCKED:` /
+   user `stop`.
+
+## Usage
+
+```
+team action='goal', config.subAction='start',
+      config.objective='Migrate src/auth from JS to TS. Done when tsc --noEmit=0 and test/auth passes.',
+      config.evaluatorModel='haiku',
+      config.maxTurns=20,
+      budgetTotal=500000
+```
+
+Sub-actions: `start | status | pause | resume | stop | step | clear`.
+
+Slash command: `/team-goal start --objective='...' --evaluatorModel='...'`
+
+## Design notes (see `research-findings/goal-workflow/`)
+
+- **One manifest per turn** — `TEAM_RUN_STATUS_TRANSITIONS` + `shouldMergeTaskUpdate`
+  block re-driving a terminal manifest, so each turn is a fresh `createRunManifest`.
+  The goal loop owns OUTER state in `GoalLoopState` at
+  `<crewRoot>/state/goals/<goalId>.json`.
+- **Feedback via `manifest.goal`** — the verdict's `reason` is composed into the next
+  turn's `manifest.goal` (re-read lazily each render). `session.steer` is NOT used
+  (it's a no-op for child-process runs).
+- **Budget via `collectRunMetrics`** — `budgetUsed = Σ over turns of collectRunMetrics(cwd, turnRunId).totalTokens`.
+  (`loadRunMetrics`/`saveRunMetrics` have 0 callers — do not use.)
+- **Judge lockdown** — the synthesized `goal-judge` AgentConfig sets `disableTools:true`
+  (Pi `--no-tools`), `excludeTools:[bash,read,write,edit]`, `inheritContext:false`,
+  `excludeContextBash:true`, `parentContext:undefined`, `maxTurns:1`. An empty
+  `tools:[]` is INSUFFICIENT because `pi-args.ts` skips empty arrays.
+- **Trust boundary** — the judge is capability-locked (no agency, only emits a verdict).
+
+## Background spawn
+
+The loop runs in the background via `runKind:'goal-loop'` (background-runner.ts
+dispatch). The handler `handleGoal('start')` writes the `GoalLoopState`; the
+background process calls `runGoalLoop` which loops `executeTeamRun` per turn.
+
+## Hooks
+
+- `before_goal_step` — fires before each turn.
+- `before_goal_abort` — fires before a budget/maxTurns abort.

package/docs/implementation-plan-top3.md

@@ -303,12 +303,12 @@ interface ParsedPr {
 
 **New tool:** `read-issue` / `read-pr`
 ```typescript
-// agents có thể gọi:
-// read({ path: "issue://123" }) → markdown của issue
-// read({ path: "pr://456" }) → markdown của PR
+// agents can call:
+// read({ path: "issue://123" }) → markdown of the issue
+// read({ path: "pr://456" }) → markdown of the PR
 ```
 
-**New slash command:** `/issue` hoặc dùng existing `/crew`:
+**New slash command:** `/issue` or use the existing `/crew`:
 ```
 /crew create-issue "Task failed: fix memory leak in cache" --labels=bug --assignee=me
 /crew link-issue TICKET-123 --task=explorer-1

package/docs/issue-29-analysis.md

@@ -182,8 +182,8 @@ For the `subagent-manager.ts` defense-in-depth: spawn a subagent whose `runner`
 - ✅ Issue reproduced in code (all 11 sites verified)
 - ✅ Root cause identified
 - ✅ Fix plan drafted
-- ❌ **Code changes NOT applied** (per user request: "chưa thực hiện sửa gì cả")
+- ❌ **Code changes NOT applied** (per user request: "nothing has been changed yet")
 - ❌ Tests NOT added
 - ❌ v0.6.2 NOT released
 
-Sẵn sàng apply khi user yêu cầu.
+Ready to apply when requested by the user.