pi-crew 0.1.51 → 0.2.0

package/docs/refactor-tasks.md

@@ -1,1484 +0,0 @@
-# pi-crew Refactor & Optimization Backlog
-
-> Tài liệu này liệt kê chi tiết các task tối ưu/cải thiện cho `pi-crew/`, sắp xếp theo thứ tự ưu tiên thực hiện.
-> Task #1 (tách `register.ts` & `team-tool.ts`) đã hoàn thành — xem CHANGELOG hoặc `src/extension/team-tool/`, `src/extension/registration/`.
-
-Mỗi task gồm:
-- **Vấn đề (Problem)** — bug/inefficiency hiện tại
-- **Vị trí (Location)** — file:line
-- **Đề xuất (Proposed fix)** — cách sửa
-- **Verification** — lệnh test xác nhận
-- **Rủi ro (Risk)** — tác động/rollback
-
----
-
-## Trạng thái hoàn thành
-
-- [x] Task #1 — Tách `register.ts` & `team-tool.ts` (đã hoàn thành)
-- [x] Task #2 — Sửa `withRunLock` / `withRunLockSync` race condition + async blocking
-- [x] Task #3 — Tối ưu `nextSequence` trong `event-log.ts` (O(n²) → O(1))
-- [x] Task #4 — Cache `loadRunManifestById` resolution
-- [x] Task #5 — Memoize task-graph maps trong `team-runner` loop
-- [x] Task #6 — Cleanup timers trong `child-pi.ts`
-- [x] Task #7 — `useProjectState` walk-up tìm git root
-- [x] Task #8 — Gom hard-coded constants vào `config/defaults.ts`
-- [x] Task #9 — Validate config bằng TypeBox
-- [x] Task #10 — Tách `ensureMailbox` khỏi read path
-- [x] Task #11 — `injectAdaptivePlanIfReady` chạy ít hơn
-- [x] Task #12 — Bỏ `jiti` khỏi runtime dependencies
-- [x] Task #13 — `atomicWriteFile` non-blocking variant
-- [x] Task #14 — `defaultWorkflowConcurrency` đọc từ workflow frontmatter
-- [x] Task #15 — Logging cho silent catches
-- [x] Task #16 — Cosmetic & cleanup
-
-## #2 — Sửa `withRunLock` / `withRunLockSync` race condition + async blocking
-
-**Priority:** High — ảnh hưởng tính đúng đắn multi-process.
-
-### Vấn đề
-- File: `src/state/locks.ts`
-- `withRunLockSync`:
-  1. Check `existsSync(filePath)` → nếu stale thì `rmSync` rồi `writeFileSync(flag: "wx")`. Hai process cùng thấy stale có thể chạy `rmSync` đồng thời, một process `wx` thành công, process kia ném lỗi `EEXIST` ngay → caller phải retry thủ công nhưng không có cơ chế retry.
-  2. Lock chỉ tồn tại trong scope `fn()` — nếu `fn()` throw, lock được release qua `finally` (đúng), nhưng khoảng thời gian giữa check stale và create file là race window.
-- `withRunLock` (async) chỉ wrap `withRunLockSync`:
-  ```ts
-  export async function withRunLock<T>(manifest, fn, options) {
-      return withRunLockSync(manifest, () => fn(), options);
-  }
-  ```
-  ⇒ Lock giữ trong khi `fn()` async chạy, nhưng `withRunLockSync` trả về **Promise object ngay sau khi gọi `fn()`** chứ không đợi Promise resolve → lock release **trước khi** async work hoàn tất.
-
-### Đề xuất
-
-**Phương án A (nhỏ, bug-fix only):**
-```ts
-export async function withRunLock<T>(manifest: TeamRunManifest, fn: () => Promise<T>, options: RunLockOptions = {}): Promise<T> {
-    const filePath = lockPath(manifest);
-    const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    await acquireLockWithRetry(filePath, staleMs);
-    try {
-        return await fn();
-    } finally {
-        try { fs.rmSync(filePath, { force: true }); } catch {}
-    }
-}
-
-async function acquireLockWithRetry(filePath: string, staleMs: number): Promise<void> {
-    const deadline = Date.now() + staleMs * 2;
-    let attempt = 0;
-    while (true) {
-        try {
-            // O_CREAT | O_EXCL | O_WRONLY (atomic)
-            const fd = fs.openSync(filePath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o644);
-            fs.writeSync(fd, JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
-            fs.closeSync(fd);
-            return;
-        } catch (error) {
-            const code = (error as NodeJS.ErrnoException).code;
-            if (code !== "EEXIST") throw error;
-            // Check stale
-            try {
-                const stat = fs.statSync(filePath);
-                if (Date.now() - stat.mtimeMs > staleMs) {
-                    fs.rmSync(filePath, { force: true });
-                    continue;
-                }
-            } catch {}
-            if (Date.now() > deadline) throw new Error(`Run lock '${filePath}' busy.`);
-            await new Promise((resolve) => setTimeout(resolve, Math.min(250, 25 * 2 ** attempt)));
-            attempt++;
-        }
-    }
-}
-```
-
-**Phương án B (dùng thư viện):** Cài `proper-lockfile` (~13KB, MIT). API: `lockfile.lock(filePath, { stale, retries })`. Production-grade, nhưng thêm dependency.
-
-### Verification
-```powershell
-npx tsc --noEmit
-node --experimental-strip-types --test test/unit/api-locks.test.ts
-node --experimental-strip-types --test test/unit/resume-cancel.test.ts test/unit/mailbox-api.test.ts
-```
-
-Test mới cần thêm: 2 process đồng thời gọi `withRunLock` cùng manifest → đúng 1 thành công tại một thời điểm.
-
-### Rủi ro
-- API giữ nguyên (`withRunLock(manifest, fn, options)`) → backward compat.
-- Trên Windows, `O_EXCL` đôi khi flaky với antivirus — vẫn cần retry với backoff.
-
----
-
-## #3 — Tối ưu `nextSequence` trong `event-log.ts` (O(n²) → O(1))
-
-**Priority:** High — performance trên run dài (10k+ events).
-
-### Vấn đề
-- File: `src/state/event-log.ts:46-65`
-- Cache hit nhanh, nhưng cache miss = đọc toàn bộ file + `JSON.parse` mỗi line:
-  ```ts
-  for (const line of fs.readFileSync(eventsPath, "utf-8").split("\n")) {
-      const event = JSON.parse(line);
-      max = Math.max(max, event.metadata?.seq ?? 0);
-  }
-  ```
-- Mỗi process khác (background async runner, child Pi) ghi event → invalidate cache của process khác → mỗi append ở leader có thể trở thành full scan.
-- Kết quả: với 10k events, mỗi append ~5-50ms; tổng cộng O(n²).
-
-### Đề xuất
-
-Lưu seq counter vào file riêng `events.seq`:
-
-```ts
-// src/state/event-log.ts
-function seqFilePath(eventsPath: string): string {
-    return `${eventsPath}.seq`;
-}
-
-function nextSequence(eventsPath: string): number {
-    const seqPath = seqFilePath(eventsPath);
-    let current = 0;
-    try {
-        current = Number.parseInt(fs.readFileSync(seqPath, "utf-8").trim(), 10);
-        if (!Number.isFinite(current) || current < 0) current = 0;
-    } catch {
-        // First write or corrupted: scan once to recover
-        if (fs.existsSync(eventsPath)) {
-            for (const line of fs.readFileSync(eventsPath, "utf-8").split("\n")) {
-                if (!line.trim()) continue;
-                try { current = Math.max(current, (JSON.parse(line) as TeamEvent).metadata?.seq ?? 0); } catch { current++; }
-            }
-        }
-    }
-    const next = current + 1;
-    try {
-        atomicWriteFile(seqPath, String(next));
-    } catch {
-        // Best effort; sequence will recover on next read
-    }
-    return next;
-}
-```
-
-Hoặc tốt hơn: dùng **incremental tail-read** từ cached size offset:
-
-```ts
-const sequenceCache = new Map<string, { size: number; mtimeMs: number; seq: number; offset: number }>();
-
-function nextSequence(eventsPath: string): number {
-    if (!fs.existsSync(eventsPath)) return 1;
-    const stat = fs.statSync(eventsPath);
-    const cached = sequenceCache.get(eventsPath);
-    if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) return cached.seq + 1;
-
-    let max = cached?.seq ?? 0;
-    let startOffset = cached && cached.size < stat.size ? cached.offset : 0;
-    if (cached && cached.size > stat.size) { max = 0; startOffset = 0; } // file rotated
-
-    const fd = fs.openSync(eventsPath, "r");
-    try {
-        const buf = Buffer.alloc(stat.size - startOffset);
-        fs.readSync(fd, buf, 0, buf.length, startOffset);
-        for (const line of buf.toString("utf-8").split("\n")) {
-            if (!line.trim()) continue;
-            try { max = Math.max(max, (JSON.parse(line) as TeamEvent).metadata?.seq ?? 0); } catch { max++; }
-        }
-    } finally {
-        fs.closeSync(fd);
-    }
-    sequenceCache.set(eventsPath, { size: stat.size, mtimeMs: stat.mtimeMs, seq: max, offset: stat.size });
-    return max + 1;
-}
-```
-
-### Verification
-```powershell
-node --experimental-strip-types --test test/unit/event-metadata.test.ts test/unit/run-events-artifacts.test.ts test/unit/phase5-observability.test.ts
-```
-
-Benchmark mới (optional): append 10k events, đo tổng thời gian — kỳ vọng < 1s thay vì 10-30s.
-
-### Rủi ro
-- Phương án "seq file" đơn giản hơn, dễ verify; phải chú ý cleanup (`forget`/`prune` xóa luôn `.seq`).
-- Phương án incremental đọc đúng nhưng phức tạp hơn, cần test đặc biệt cho file rotation/truncate.
-
----
-
-## #4 — Cache `loadRunManifestById` resolution
-
-**Priority:** Medium — UI overhead (powerbar/sidebar 1Hz).
-
-### Vấn đề
-- File: `src/state/state-store.ts:104-115`
-- Mỗi lần gọi: 2 lần `fs.existsSync` + 2 lần `path.join` + `readFileSync`+`JSON.parse` cho cả manifest và tasks.
-- Được gọi từ:
-  - `live-run-sidebar.ts` (1Hz timer)
-  - `powerbar-publisher.ts` (1Hz)
-  - `crew-widget.ts` (1Hz)
-  - `subagent-helpers.refreshPersistedSubagentRecord`
-  - `team-tool.handleStatus/Cancel/Resume/Events/Artifacts/Summary/Worktrees/Forget/Cleanup/Export/Api`
-
-### Đề xuất
-
-Thêm tầng cache stat-based (giống `nextSequence`):
-
-```ts
-// src/state/state-store.ts
-interface ManifestCacheEntry {
-    manifest: TeamRunManifest;
-    tasks: TeamTaskState[];
-    manifestMtime: number;
-    tasksMtime: number;
-}
-const manifestCache = new Map<string, ManifestCacheEntry>();
-
-function resolvedStateRoot(cwd: string, runId: string): string | undefined {
-    const projectPath = path.join(projectPiRoot(cwd), "teams", "state", "runs", runId);
-    if (fs.existsSync(projectPath)) return projectPath;
-    const userPath = path.join(userPiRoot(), "extensions", "pi-crew", "runs", "state", "runs", runId);
-    return fs.existsSync(userPath) ? userPath : undefined;
-}
-
-export function loadRunManifestById(cwd: string, runId: string): { manifest: TeamRunManifest; tasks: TeamTaskState[] } | undefined {
-    const stateRoot = resolvedStateRoot(cwd, runId);
-    if (!stateRoot) return undefined;
-    const manifestPath = path.join(stateRoot, "manifest.json");
-    const tasksPath = path.join(stateRoot, "tasks.json");
-
-    let mStat: fs.Stats | undefined;
-    let tStat: fs.Stats | undefined;
-    try { mStat = fs.statSync(manifestPath); } catch { return undefined; }
-    try { tStat = fs.statSync(tasksPath); } catch {}
-
-    const cacheKey = `${stateRoot}`;
-    const cached = manifestCache.get(cacheKey);
-    if (cached && cached.manifestMtime === mStat.mtimeMs && cached.tasksMtime === (tStat?.mtimeMs ?? 0)) {
-        return { manifest: cached.manifest, tasks: cached.tasks };
-    }
-
-    const manifest = readJsonFile<TeamRunManifest>(manifestPath);
-    if (!manifest) return undefined;
-    const tasks = readJsonFile<TeamTaskState[]>(tasksPath) ?? [];
-    manifestCache.set(cacheKey, { manifest, tasks, manifestMtime: mStat.mtimeMs, tasksMtime: tStat?.mtimeMs ?? 0 });
-    return { manifest, tasks };
-}
-```
-
-Quan trọng: `saveRunManifest` / `saveRunTasks` phải invalidate cache:
-```ts
-export function saveRunManifest(manifest: TeamRunManifest): void {
-    atomicWriteJson(path.join(manifest.stateRoot, "manifest.json"), manifest);
-    manifestCache.delete(manifest.stateRoot); // OR: refresh entry
-}
-```
-
-### Verification
-```powershell
-node --experimental-strip-types --test test/unit/state-store.test.ts test/unit/team-run.test.ts test/unit/resume-cancel.test.ts test/unit/run-dashboard.test.ts test/unit/live-run-sidebar.test.ts
-```
-
-### Rủi ro
-- Cross-process: process A cache → process B ghi → process A vẫn dùng cache cũ trong tầng mtime check. mtime resolution thường ≥1ms nên acceptable.
-- **Memory leak**: cache không bound. Thêm LRU max 50 entries.
-
----
-
-## #5 — Memoize task-graph maps trong `team-runner` loop
-
-**Priority:** Medium — CPU/GC overhead trên run lớn (>100 tasks).
-
-### Vấn đề
-- File: `src/runtime/task-graph-scheduler.ts`
-- Mỗi function (`getReadyTasks`, `markTaskRunning`, `markTaskDone`, `cancelTaskSubtree`, `failTaskAndBlockChildren`, `taskGraphSnapshot`) đều build lại 3 maps:
-  - `completedStepIds(tasks)` — Set
-  - `taskById(tasks)` — Map
-  - `stepIdToTaskId(tasks)` — Map
-- Trong `executeTeamRun` loop, `refreshTaskGraphQueues` được gọi nhiều lần per iteration:
-  - `team-runner.ts:240` (getReadyTasks)
-  - `team-runner.ts:228` (taskGraphSnapshot)
-  - Mỗi snapshot/refresh = 3 maps × O(n)
-
-### Đề xuất
-
-Build maps 1 lần ở caller, truyền xuống:
-
-```ts
-// task-graph-scheduler.ts
-export interface TaskGraphIndex {
-    doneSteps: Set<string>;
-    byId: Map<string, TeamTaskState>;
-    byStepId: Map<string, string>;
-}
-
-export function buildTaskGraphIndex(tasks: TeamTaskState[]): TaskGraphIndex {
-    return {
-        doneSteps: completedStepIds(tasks),
-        byId: taskById(tasks),
-        byStepId: stepIdToTaskId(tasks),
-    };
-}
-
-export function refreshTaskGraphQueues(tasks: TeamTaskState[], index?: TaskGraphIndex): TeamTaskState[] {
-    const idx = index ?? buildTaskGraphIndex(tasks);
-    return tasks.map((task) => {
-        // ... use idx.doneSteps, idx.byId, idx.byStepId
-    });
-}
-```
-
-Trong `team-runner.executeTeamRun`:
-```ts
-while (tasks.some((task) => task.status === "queued")) {
-    const idx = buildTaskGraphIndex(tasks);
-    const snapshot = taskGraphSnapshot(tasks, idx);
-    const readyBatch = getReadyTasks(tasks, concurrency.selectedCount, idx);
-    // ...
-    tasks = mergeTaskUpdates(tasks, results);
-    // (rebuild index after mutations)
-}
-```
-
-Hoặc: memoize bằng WeakMap với task array reference làm key:
-```ts
-const indexCache = new WeakMap<TeamTaskState[], TaskGraphIndex>();
-function ensureIndex(tasks: TeamTaskState[]): TaskGraphIndex {
-    let idx = indexCache.get(tasks);
-    if (!idx) { idx = buildTaskGraphIndex(tasks); indexCache.set(tasks, idx); }
-    return idx;
-}
-```
-(Pattern này hoạt động vì `tasks.map()` luôn trả mảng mới → cache key đổi tự động khi mutation.)
-
-### Verification
-```powershell
-node --experimental-strip-types --test test/unit/task-graph-scheduler.test.ts test/unit/phase3-runtime.test.ts test/unit/phase4-runtime.test.ts test/unit/implementation-fanout.test.ts
-```
-
-### Rủi ro
-- Refactor lan rộng (5-6 callsite) nhưng giữ API cũ với optional param `index?` → backward compat.
-
----
-
-## #6 — Cleanup timers trong `child-pi.ts`
-
-**Priority:** Medium — leak nhẹ nhưng dễ tích lũy.
-
-### Vấn đề
-- File: `src/runtime/child-pi.ts:31-39`
-- `killProcessTree` schedule SIGKILL sau `HARD_KILL_MS`:
-  ```ts
-  setTimeout(() => { try { process.kill(-pid, "SIGKILL"); } catch { ... } }, HARD_KILL_MS).unref?.();
-  ```
-- Không clear khi child exit bình thường giữa SIGTERM-SIGKILL window. Trên hệ thống chạy nhiều run, hàng trăm timer pending mỗi giờ.
-
-### Đề xuất
-
-Track timer và clear trong `child.on('exit')`:
-
-```ts
-function killProcessTree(pid: number | undefined, child?: ChildProcess): void {
-    if (!pid || !Number.isInteger(pid) || pid <= 0) return;
-    try {
-        if (process.platform === "win32") {
-            spawn("taskkill", ["/pid", String(pid), "/t", "/f"], { stdio: "ignore", windowsHide: true });
-            return;
-        }
-        try { process.kill(-pid, "SIGTERM"); } catch { process.kill(pid, "SIGTERM"); }
-        const killTimer = setTimeout(() => {
-            try { process.kill(-pid, "SIGKILL"); } catch { try { process.kill(pid, "SIGKILL"); } catch {} }
-        }, HARD_KILL_MS);
-        killTimer.unref?.();
-        child?.once("exit", () => clearTimeout(killTimer));
-    } catch {
-        // Ignore shutdown races.
-    }
-}
-```
-
-Caller đã có `child` reference (từ `activeChildProcesses`), nên truyền xuống.
-
-### Verification
-```powershell
-node --experimental-strip-types --test test/unit/pi-spawn.test.ts test/unit/mock-child-run.test.ts
-```
-
-Manual check (Linux/Mac): chạy `node -e "process.exit()"` trong test, đảm bảo không có timer leak qua `process._getActiveHandles()`.
-
-### Rủi ro
-- Thấp: chỉ thêm clearTimeout khi exit. Behavior không đổi ở fast-exit case (timer vẫn fire nếu child chưa exit).
-
----
-
-## #7 — `useProjectState` walk-up tìm git root
-
-**Priority:** Medium — DX bug trong monorepo.
-
-### Vấn đề
-- File: `src/state/state-store.ts:21-23`
-  ```ts
-  function useProjectState(cwd: string): boolean {
-      return fs.existsSync(path.join(cwd, ".pi")) || fs.existsSync(path.join(cwd, ".git"));
-  }
-  ```
-- Nếu user `cd` vào subfolder của repo (ví dụ `pi-crew/src/`), không tìm thấy `.git` ngay → fallback `~/.pi/agent/extensions/pi-crew/runs/...` → state không phải project-local nữa.
-- Tương tự: `projectPiRoot(cwd) = path.join(cwd, ".pi")` → `.pi/` được tạo trong subfolder, không phải repo root.
-
-### Đề xuất
-
-```ts
-// src/utils/paths.ts
-export function findRepoRoot(cwd: string): string | undefined {
-    let current = path.resolve(cwd);
-    const root = path.parse(current).root;
-    while (current !== root) {
-        if (fs.existsSync(path.join(current, ".git")) || fs.existsSync(path.join(current, ".pi"))) {
-            return current;
-        }
-        const parent = path.dirname(current);
-        if (parent === current) break;
-        current = parent;
-    }
-    return undefined;
-}
-
-export function projectPiRoot(cwd: string): string {
-    return path.join(findRepoRoot(cwd) ?? cwd, ".pi");
-}
-```
-
-Và `useProjectState`:
-```ts
-function useProjectState(cwd: string): boolean {
-    return findRepoRoot(cwd) !== undefined;
-}
-```
-
-### Verification
-```powershell
-node --experimental-strip-types --test test/unit/state-store.test.ts test/unit/team-run.test.ts test/unit/discovery.test.ts test/unit/project-init.test.ts
-```
-
-Test mới: tạo fixture `tmp/repo/.git/`, chạy `loadConfig(tmp/repo/sub/folder)` → expect path resolve về `tmp/repo/.pi`.
-
-### Rủi ro
-- **Medium:** Có thể đổi semantics nếu user cố ý dùng subfolder làm pi-crew root. Cần check `discovery.test.ts` và `project-init.test.ts` không assume `cwd === root`.
-- Workaround: thêm config flag `pi-crew.useGitRoot: false` để giữ behavior cũ.
-
----
-
-## #8 — Gom hard-coded constants vào `config/defaults.ts`
-
-**Priority:** Low — DX/maintainability.
-
-### Vấn đề
-Các magic numbers rải rác:
-- `child-pi.ts`: `POST_EXIT_STDIO_GUARD_MS=3000`, `FINAL_DRAIN_MS=5000`, `HARD_KILL_MS=3000`, `MAX_CAPTURE_BYTES=256*1024`, `MAX_ASSISTANT_TEXT_CHARS=8192`, ...
-- `concurrency.ts`: `defaultWorkflowConcurrency` switch-case.
-- `event-log.ts`: `TERMINAL_EVENT_TYPES` set.
-- `state-store.ts`: paths.
-- `locks.ts`: `DEFAULT_STALE_MS=30_000`.
-
-### Đề xuất
-
-Tạo `src/config/defaults.ts`:
-```ts
-export const CrewDefaults = {
-    childPi: {
-        postExitStdioGuardMs: 3000,
-        finalDrainMs: 5000,
-        hardKillMs: 3000,
-        maxCaptureBytes: 256 * 1024,
-        maxAssistantTextChars: 8192,
-        maxToolResultChars: 1024,
-        maxToolInputChars: 2048,
-        maxCompactContentChars: 4096,
-    },
-    locks: {
-        defaultStaleMs: 30_000,
-    },
-    concurrency: {
-        workflows: { "parallel-research": 4, research: 2, implementation: 2, review: 2, default: 2 } as Record<string, number>,
-        fallback: 1,
-    },
-    ui: {
-        widgetRefreshMs: 1000,
-        sidebarRefreshMs: 1000,
-    },
-} as const;
-```
-
-Cập nhật từng file thay vì hard-code. Cho phép override qua `loadConfig(cwd).config`:
-```ts
-export function effectiveLimits(config: PiTeamsConfig): typeof CrewDefaults & { /* overrides */ } {
-    return {
-        ...CrewDefaults,
-        childPi: { ...CrewDefaults.childPi, ...(config.runtime?.childPi ?? {}) },
-    };
-}
-```
-
-### Verification
-```powershell
-npx tsc --noEmit
-node --experimental-strip-types --test  # full suite
-```
-
-### Rủi ro
-- Thấp: chỉ refactor constants. Test phải pass không đổi.
-
----
-
-## #9 — Validate config bằng TypeBox
-
-**Priority:** Low — chuẩn hóa, bắt config invalid sớm.
-
-### Vấn đề
-- File: `src/extension/team-tool/config-patch.ts`
-- `configPatchFromConfig` validate manual: ~40 dòng `typeof x === "number" && Number.isInteger(x) && x > 0 ? x : undefined`.
-- TypeBox đã có cho tool params (`team-tool-schema.ts`), nhưng config schema được load từ `loadConfig` không qua TypeBox — chỉ JSON parse.
-
-### Đề xuất
-
-Thêm `src/schema/config-schema.ts`:
-```ts
-import { Type, type Static } from "typebox";
-
-export const PiTeamsLimitsSchema = Type.Object({
-    maxConcurrentWorkers: Type.Optional(Type.Integer({ minimum: 1 })),
-    maxTaskDepth: Type.Optional(Type.Integer({ minimum: 1 })),
-    // ...
-});
-
-export const PiTeamsRuntimeSchema = Type.Object({
-    mode: Type.Optional(Type.Union([Type.Literal("auto"), Type.Literal("scaffold"), Type.Literal("child-process"), Type.Literal("live-session")])),
-    // ...
-});
-
-export const PiTeamsConfigSchema = Type.Object({
-    asyncByDefault: Type.Optional(Type.Boolean()),
-    executeWorkers: Type.Optional(Type.Boolean()),
-    limits: Type.Optional(PiTeamsLimitsSchema),
-    runtime: Type.Optional(PiTeamsRuntimeSchema),
-    // ...
-});
-
-export type PiTeamsConfig = Static<typeof PiTeamsConfigSchema>;
-```
-
-Trong `config.ts`:
-```ts
-import { Value } from "typebox/value";
-import { PiTeamsConfigSchema } from "../schema/config-schema.ts";
-
-export function loadConfig(cwd: string): { config: PiTeamsConfig; path: string; error?: string } {
-    const raw = readJsonFile(...);
-    const errors = [...Value.Errors(PiTeamsConfigSchema, raw)];
-    if (errors.length) {
-        return { config: defaultConfig(), path, error: errors.map(e => `${e.path}: ${e.message}`).join("; ") };
-    }
-    return { config: Value.Cast(PiTeamsConfigSchema, raw), path };
-}
-```
-
-### Verification
-```powershell
-node --experimental-strip-types --test test/unit/config.test.ts test/unit/config-update.test.ts test/unit/project-config.test.ts
-```
-
-### Rủi ro
-- Medium: thay đổi config validation → invalid config (đang silently bỏ qua) sẽ thành error → cần backward compat (downgrade error → warning hoặc dùng `Value.Cast` để cast best-effort).
-
----
-
-## #10 — Tách `ensureMailbox` khỏi read path
-
-**Priority:** Low — side effect không cần thiết ở read.
-
-### Vấn đề
-- File: `src/state/mailbox.ts:97-103`
-- `readMailbox()` luôn gọi `ensureMailbox()` → `mkdirSync` + 4× `writeFileSync` empty + 1× `writeFileSync` delivery.json nếu thiếu.
-- Read path không nên có side effects.
-
-### Đề xuất
-```ts
-function safeReadMailboxFile(filePath: string, direction: MailboxDirection): MailboxMessage[] {
-    if (!fs.existsSync(filePath)) return [];
-    return readMailboxFile(filePath, direction);
-}
-
-export function readMailbox(manifest: TeamRunManifest, direction?: MailboxDirection, taskId?: string): MailboxMessage[] {
-    // No ensureMailbox here
-    const directions = direction ? [direction] : ["inbox", "outbox"] as const;
-    return directions.flatMap((item) => safeReadMailboxFile(mailboxPath(manifest, item, taskId), item))
-        .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
-}
-
-export function appendMailboxMessage(...) {
-    ensureMailbox(manifest, message.taskId);  // Only here
-    // ...
-}
-```
-
-### Verification
-```powershell
-node --experimental-strip-types --test test/unit/mailbox-api.test.ts test/unit/mailbox-validation.test.ts
-```
-
-### Rủi ro
-- Thấp: append vẫn ensure dir → cấu trúc mailbox luôn được tạo khi cần.
-
----
-
-## #11 — `injectAdaptivePlanIfReady` chạy ít hơn
-
-**Priority:** Low-Medium — performance + log noise.
-
-### Vấn đề
-- File: `src/runtime/team-runner.ts`
-- `injectAdaptivePlanIfReady` được gọi 3 lần per scheduler iteration:
-  1. Initial (line ~244)
-  2. Mỗi vòng while (line ~268)
-  3. Sau mỗi batch (line ~308)
-- Mỗi lần đọc `assess` artifact + parse JSON nếu chưa inject. Đã có guard "tasks.some(adaptive-)" nhưng vẫn execute regex/IO.
-
-### Đề xuất
-
-Track flag trong manifest hoặc local state:
-```ts
-let adaptivePlanInjected = tasks.some((task) => task.stepId?.startsWith("adaptive-"));
-let adaptivePlanFailed = false;
-
-// Replace 3 invocations with:
-function maybeInjectAdaptive() {
-    if (adaptivePlanInjected || adaptivePlanFailed) return;
-    const r = injectAdaptivePlanIfReady({ manifest, tasks, workflow, team: input.team });
-    if (r.missingPlan) { adaptivePlanFailed = true; /* mark blocked */ }
-    if (r.injected) { adaptivePlanInjected = true; tasks = r.tasks; workflow = r.workflow; }
-}
-```
-
-### Verification
-```powershell
-node --experimental-strip-types --test test/unit/adaptive-implementation.test.ts test/unit/implementation-fanout.test.ts
-```
-
-### Rủi ro
-- Thấp: chỉ thay đổi điều kiện trigger, không thay đổi logic inject.
-
----
-
-## #12 — Bỏ `jiti` khỏi runtime dependencies
-
-**Priority:** Low — install size.
-
-### Vấn đề
-- `package.json` declare `"jiti": "^2.6.1"` trong `dependencies`.
-- Grep trong source: không có `import.*jiti` nào trong `src/`.
-
-### Đề xuất
-
-```powershell
-# Verify nothing imports jiti
-Select-String -Path "D:\my\my_project\pi-crew\src\*","D:\my\my_project\pi-crew\index.ts" -Pattern "jiti" -Recurse
-```
-
-Nếu không có hit → remove khỏi `dependencies`:
-```json
-"dependencies": {
-    "typebox": "^1.1.24"
-}
-```
-
-### Verification
-```powershell
-npm install
-npx tsc --noEmit
-npm test
-npm pack --dry-run
-```
-
-### Rủi ro
-- Thấp. Nếu dynamic require thì sẽ fail rõ ràng.
-
----
-
-## #13 — `atomicWriteFile` non-blocking variant
-
-**Priority:** Low — chỉ matter trên hot path.
-
-### Vấn đề
-- File: `src/state/atomic-write.ts:5-9`
-- `sleepSync` dùng `Atomics.wait` block thread chính:
-  ```ts
-  function sleepSync(ms: number): void {
-      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-  }
-  ```
-- `__test__renameWithRetry` retry up to 20 lần với backoff → có thể block 5+ giây trên main thread (Windows EBUSY/EPERM).
-
-### Đề xuất
-
-Thêm async variant cho hot path (saveRunTasks/saveRunManifest trong loop):
-```ts
-export async function atomicWriteFileAsync(filePath: string, content: string): Promise<void> {
-    await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
-    const tempPath = `${filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
-    try {
-        await fs.promises.writeFile(tempPath, content, "utf-8");
-        await renameWithRetryAsync(tempPath, filePath);
-    } catch (error) {
-        try { await fs.promises.rm(tempPath, { force: true }); } catch {}
-        throw error;
-    }
-}
-
-async function renameWithRetryAsync(tempPath: string, filePath: string, retries = 20): Promise<void> {
-    for (let attempt = 0; attempt <= retries; attempt++) {
-        try { await fs.promises.rename(tempPath, filePath); return; }
-        catch (error) {
-            if (!isRetryableRenameError(error) || attempt === retries) throw error;
-            await new Promise((r) => setTimeout(r, Math.min(250, 10 * 2 ** attempt)));
-        }
-    }
-}
-```
-
-Dùng trong `saveRunTasks`/`saveRunManifest` (gọi từ async context):
-```ts
-export async function saveRunManifestAsync(manifest: TeamRunManifest): Promise<void> {
-    await atomicWriteFileAsync(path.join(manifest.stateRoot, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
-}
-```
-
-### Verification
-```powershell
-node --experimental-strip-types --test test/unit/atomic-write.test.ts test/unit/state-store.test.ts
-```
-
-### Rủi ro
-- Medium: phải convert call chain sang async → nhiều file thay đổi. Có thể chỉ apply cho 1-2 hot path để tránh ripple.
-
----
-
-## #14 — `defaultWorkflowConcurrency` đọc từ workflow frontmatter
-
-**Priority:** Low — DX.
-
-### Vấn đề
-- File: `src/runtime/concurrency.ts:18-23`
-  ```ts
-  export function defaultWorkflowConcurrency(workflowName: string): number {
-      if (workflowName === "parallel-research") return 4;
-      if (workflowName === "research") return 2;
-      // ...
-  }
-  ```
-- User custom workflow không thể set default concurrency mà phải pass `team.maxConcurrency`.
-
-### Đề xuất
-
-`WorkflowConfig` đã có frontmatter loader. Thêm field:
-```ts
-// src/workflows/workflow-config.ts
-export interface WorkflowConfig {
-    // ...
-    maxConcurrency?: number;
-}
-```
-
-Cập nhật `resolveBatchConcurrency`:
-```ts
-export interface ResolveBatchConcurrencyInput {
-    workflowName: string;
-    workflowMaxConcurrency?: number;  // NEW
-    teamMaxConcurrency?: number;
-    limitMaxConcurrentWorkers?: number;
-    readyCount: number;
-    // ...
-}
-
-const requested = limitMax ?? teamMax ?? workflowMax ?? defaultByName ?? 1;
-```
-
-Trong `team-runner.ts:executeTeamRun`:
-```ts
-const concurrency = resolveBatchConcurrency({
-    workflowName: workflow.name,
-    workflowMaxConcurrency: workflow.maxConcurrency,  // pass through
-    // ...
-});
-```
-
-### Verification
-```powershell
-node --experimental-strip-types --test test/unit/concurrency.test.ts test/unit/parallel-research-dynamic.test.ts test/unit/workflow-validation.test.ts
-```
-
-### Rủi ro
-- Thấp: thêm optional field, backward compat.
-
----
-
-## #15 — Logging cho silent catches
-
-**Priority:** Low — observability.
-
-### Vấn đề
-
-Nhiều `try { ... } catch {}` nuốt lỗi:
-- `child-pi.ts`: `try { this.input.onJsonEvent?.(event); } catch {}` (line ~165)
-- `state-store.ts`: lock cleanup `catch {}`
-- `event-log.ts`: cache update `catch {}` (line ~93)
-- `team-tool.ts:handleCancel`: `try { saveCrewAgents(...); } catch {}`
-- `team-tool.ts:handleCancel`: `try { writeForegroundInterruptRequest(...); } catch {}`
-
-### Đề xuất
-
-Thêm helper `logInternalError`:
-```ts
-// src/utils/log.ts
-export function logInternalError(scope: string, error: unknown, eventsPath?: string): void {
-    const message = error instanceof Error ? error.message : String(error);
-    if (process.env.PI_TEAMS_DEBUG) {
-        console.error(`[pi-crew:${scope}] ${message}`);
-    }
-    if (eventsPath) {
-        try { appendEvent(eventsPath, { type: "internal.error", runId: "", message: `${scope}: ${message}` }); } catch {}
-    }
-}
-```
-
-Thay `catch {}` bằng `catch (e) { logInternalError("...", e); }` ở các điểm critical.
-
-### Verification
-```powershell
-$env:PI_TEAMS_DEBUG = "1"
-node --experimental-strip-types --test test/unit/runtime-hardening.test.ts
-```
-
-### Rủi ro
-- Thấp: chỉ thêm observability, không thay đổi behavior khi `PI_TEAMS_DEBUG` chưa set.
-
----
-
-## #16 — Cosmetic & cleanup
-
-### 16a. `tsconfig.json` duplicate include
-
-```json
-"include": [
-    "*.ts",
-    "src/**/*.ts",
-    "src/**/*.ts"  // <-- duplicate
-]
-```
-
-Sửa thành:
-```json
-"include": [
-    "*.ts",
-    "src/**/*.ts",
-    "test/**/*.ts"
-]
-```
-
-### 16b. Test folder structure
-
-90 unit tests không phân loại. Đề xuất:
-```
-test/
-  unit/         # pure logic (no fs, no spawn)
-  integration/  # spawn child Pi, tạo runs
-  fixtures/
-```
-
-Cập nhật `package.json`:
-```json
-"test:unit": "node --experimental-strip-types --test test/unit/*.test.ts",
-"test:integration": "node --experimental-strip-types --test test/integration/*.test.ts",
-"test": "npm run test:unit && npm run test:integration"
-```
-
-Move các file `phase[N]-*.test.ts`, `worktree-run.test.ts`, `mock-child-*.test.ts` sang `integration/`.
-
-### 16c. Subagent stuck-blocked notification
-
-File: `src/runtime/subagent-manager.ts`
-- `SubagentManager` callback chỉ trigger khi `completed/failed/cancelled/error`. Status `blocked` (run-level) không trigger.
-- Đề xuất: khi `record.runId` linked manifest có status `blocked`, tự động gọi callback.
-
-### Verification
-```powershell
-npx tsc --noEmit
-npm test
-```
-
-### Rủi ro
-- Thấp.
-
----
-
-## Thứ tự thực hiện đề xuất
-
-1. **#2** — Lock fix (correctness, multi-process)
-2. **#3** — Sequence O(n²) → O(1) (performance)
-3. **#4** — Cache loadRunManifestById (UI 1Hz overhead)
-4. **#6** — Cleanup child-pi timers (memory leak)
-5. **#7** — Walk-up git root (DX bug)
-6. **#5** — Memoize task-graph maps (CPU)
-7. **#11** — Adaptive plan trigger optimization
-8. **#10** — ensureMailbox khỏi read path
-9. **#8** — Gom constants
-10. **#13** — Async atomic write
-11. **#14** — Workflow.maxConcurrency
-12. **#9** — TypeBox validate config
-13. **#12** — Drop jiti
-14. **#15** — Internal error logging
-15. **#16** — Cosmetic
-
----
-
-## Quy ước test cho mỗi task
-
-Theo workflow `~/.factory/AGENTS.md` mục 11:
-
-```powershell
-# Sau mỗi thay đổi:
-Set-Location D:\my\my_project\pi-crew
-npx tsc --noEmit                                    # Type check
-node --experimental-strip-types --test test/unit/<related>.test.ts   # Targeted tests
-npm test                                            # Full suite (nếu thay đổi module core)
-```
-
-PR template (tham khảo `~/.factory/AGENTS.md` mục 10):
-```
-Summary: <task #N: short description>
-Plan: ...
-Files & Rationale: ...
-Tests: ...
-Verification:
-- npx tsc --noEmit → Passed
-- node --experimental-strip-types --test ... → N pass
-Risks & Rollback: ...
-```
-
----
-
-## Phase 2 — Follow-up Tasks (sau review #2–#16)
-
-> Phát hiện trong review ngày 28/04/2026 sau khi các task #2–#16 đã hoàn thành. Đây là các vấn đề lộ ra do fix tsconfig (#15) và một số chỗ chưa hoàn thiện.
-
-### Trạng thái Phase 2
-
-- [x] Task #17 — Fix 71 TS errors trong test files (CRITICAL)
-- [x] Task #18 — LRU bound cho `manifestCache` (MEDIUM)
-- [x] Task #19 — Cross-process cache staleness check (MEDIUM)
-- [x] Task #20 — Tách `ensureMailbox` (LOW)
-- [x] Task #21 — Giảm circular import giữa `team-tool.ts` ↔ `tool-result.ts` (đã fix trong review)
-- [x] Task #22 — Codemod `TeamContext` import (LOW)
-- [x] Task #23 — Subagent stuck-blocked notification (LOW)
-- [x] Task #24 — TypeBox config validation warnings (MEDIUM)
-- [x] Task #25 — `atomicWriteFileAsync` idempotent retry (LOW)
-
-### Thứ tự thực hiện đề xuất
-
-1. **#17** ✅ (CRITICAL — chặn CI) → hoàn thành
-2. **#18** + **#19** (MEDIUM — cùng file `state-store.ts`, gộp 1 PR)
-3. **#24** (MEDIUM — UX cải thiện rõ ràng)
-4. **#20** + **#22** (LOW — refactor cosmetic)
-5. **#23** (LOW — feature mới)
-6. **#25** (LOW — edge case hiếm)
-
----
-
-### Task #17 — Fix 71 TypeScript errors trong test files (CRITICAL)
-
-**Vấn đề:**
-Sau khi `tsconfig.json` được sửa để include `test/**/*.ts` (#15), 71 lỗi type pre-existing lộ ra. `src/` không có lỗi nào — toàn bộ ở `test/`. Tests vẫn chạy pass nhờ `node --experimental-strip-types` xoá type ở runtime, nhưng `npm run typecheck` (CI) sẽ fail.
-
-**Nguyên nhân:**
-`AgentToolResult.content` có kiểu `(TextContent | ImageContent)[]`. Test cũ dùng `result.content[0]?.text ?? ""` không hợp lệ vì `ImageContent` không có field `text`. Trước đây tests không bị typecheck nên không phát hiện.
-
-**Vị trí:** ~32 file trong `test/unit/` và `test/integration/` (số trong ngoặc = số lỗi):
-```
-test/integration/phase5-observability.test.ts (6)
-test/integration/phase6-control.test.ts       (2)
-test/integration/worktree-run.test.ts         (2)
-test/unit/agent-runtime-files.test.ts         (5)
-test/unit/api-claim.test.ts                   (1)
-test/unit/api-locks.test.ts                   (1)
-test/unit/async-stale.test.ts                 (2)
-test/unit/autonomy-config.test.ts             (3)
-test/unit/config-action.test.ts               (1)
-test/unit/crew-gap-lessons.test.ts            (4)
-test/unit/cross-extension-rpc.test.ts         (1)
-test/unit/doctor-smoke.test.ts                (1)
-test/unit/doctor-validation.test.ts           (4)
-test/unit/foreground-nonblocking.test.ts      (1)
-test/unit/help.test.ts                        (1)
-test/unit/import-list.test.ts                 (1)
-test/unit/lazy-agent-materialization.test.ts  (1)
-test/unit/live-agent-control.test.ts          (2)
-test/unit/live-control-realtime.test.ts       (1)
-test/unit/live-session-context.test.ts        (3)
-test/unit/live-session-runtime.test.ts        (4)
-test/unit/mailbox-api.test.ts                 (4)
-test/unit/mailbox-validation.test.ts          (1)
-test/unit/management-references.test.ts       (1)
-test/unit/project-init.test.ts                (1)
-test/unit/run-events-artifacts.test.ts        (4)
-test/unit/runtime-hardening.test.ts           (2)
-test/unit/subagent-manager.test.ts            (5)
-test/unit/summary.test.ts                     (2)
-test/unit/team-recommendation.test.ts         (1)
-test/unit/team-run.test.ts                    (2)
-test/unit/validate-resources.test.ts          (1)
-```
-
-**Đề xuất fix:**
-
-**Bước 1 — Tạo helper** trong `test/fixtures/tool-result-helpers.ts`:
-```ts
-export function textOf(result: { content?: Array<{ type: string; text?: string }> }): string {
-	return result.content
-		?.filter((item): item is { type: "text"; text: string } => item.type === "text" && typeof item.text === "string")
-		.map((item) => item.text)
-		.join("\n") ?? "";
-}
-
-export function firstText(result: { content?: Array<{ type: string; text?: string }> }): string {
-	const first = result.content?.find((item) => item.type === "text" && typeof item.text === "string");
-	return first?.text ?? "";
-}
-```
-
-**Bước 2 — Codemod** thay `result.content[0]?.text ?? ""` → `firstText(result)`:
-```powershell
-Get-ChildItem D:\my\my_project\pi-crew\test -Recurse -Filter *.test.ts | ForEach-Object {
-    $content = Get-Content $_.FullName -Raw
-    $new = $content -replace '(\w+)\.content\[0\]\?\.text \?\? ""', 'firstText($1)'
-    if ($new -ne $content) {
-        Set-Content $_.FullName $new -NoNewline
-    }
-}
-```
-Sau đó thêm `import { firstText } from "../fixtures/tool-result-helpers.ts";` vào mỗi file đã sửa.
-
-**Bước 3 — Sửa riêng** 5 lỗi trong `test/unit/subagent-manager.test.ts` (mock `SpawnRunner` trả `status: string`):
-```ts
-// Cũ
-const runner = async () => ({ content: [...], details: { action: "x", status: "ok" } });
-// Mới
-const runner: SpawnRunner = async () => ({ content: [...], details: { action: "x", status: "ok" as const } });
-```
-
-**Bước 4 — Sửa** 2 lỗi `cross-extension-rpc.test.ts(37)` & `live-control-realtime.test.ts(18)` — `setTimeout(...)` trả `number` không match `() => void | Promise<void>`. Bọc:
-```ts
-// Cũ
-setTimeout(() => doSomething(), 100);
-// Mới
-() => { setTimeout(() => doSomething(), 100); }
-```
-
-**Bước 5 — Sửa** `test/unit/live-session-context.test.ts(27)`: mock object thiếu các field bắt buộc của `TeamContext`. Thêm `as TeamContext` cast hoặc bổ sung field.
-
-**Verification:**
-```bash
-npx tsc --noEmit                                    # → 0 errors
-npm test                                            # → all pass
-npm run ci                                          # → typecheck + test + pack OK
-```
-
-**Risk:** Thấp — thuần test code, không ảnh hưởng runtime. Chạy `git diff test/` review trước khi commit để chắc codemod không thay nhầm.
-
----
-
-### Task #18 — LRU bound cho manifestCache (MEDIUM)
-
-**Vấn đề:**
-`manifestCache` trong `src/state/state-store.ts:29` là `Map<string, ManifestCacheEntry>` không có giới hạn. Trong long-running session với nhiều run (status query liên tục), Map có thể grow vô hạn → memory leak.
-
-**Vị trí:** `src/state/state-store.ts:29, 206`
-
-**Đề xuất fix:**
-```ts
-// config/defaults.ts
-export const DEFAULT_CACHE = {
-	manifestMaxEntries: 64,
-};
-
-// state-store.ts
-import { DEFAULT_CACHE } from "../config/defaults.ts";
-
-const manifestCache = new Map<string, ManifestCacheEntry>();
-
-function setManifestCache(stateRoot: string, entry: ManifestCacheEntry): void {
-	if (manifestCache.has(stateRoot)) manifestCache.delete(stateRoot); // refresh recency
-	manifestCache.set(stateRoot, entry);
-	while (manifestCache.size > DEFAULT_CACHE.manifestMaxEntries) {
-		const oldest = manifestCache.keys().next().value;
-		if (!oldest) break;
-		manifestCache.delete(oldest);
-	}
-}
-
-// Trong loadRunManifestById, đổi:
-// manifestCache.set(stateRoot, { ... });
-// thành:
-// setManifestCache(stateRoot, { ... });
-```
-
-**Verification:**
-```bash
-node --experimental-strip-types --test test/unit/state-store.test.ts
-# Thêm test mới: load 100 run khác nhau, verify manifestCache.size <= 64
-```
-
-**Risk:** Thấp — chỉ ảnh hưởng cache, không ảnh hưởng đúng đắn vì mtime invalidation vẫn đảm bảo data fresh.
-
----
-
-### Task #19 — Cross-process cache staleness check (MEDIUM)
-
-**Vấn đề:**
-`manifestCache` invalidate dựa trên `manifestStat.mtimeMs`. Trên Windows, mtime granularity ~1ms. Nếu process A ghi manifest tại t=0ms và process B đọc cùng lúc với cache cũ tại t=1ms, mtime có thể trùng → cache stale.
-
-**Vị trí:** `src/state/state-store.ts:175-208` (`loadRunManifestById`)
-
-**Đề xuất fix:**
-Kết hợp mtime + size (cheap):
-```ts
-interface ManifestCacheEntry {
-	manifest: TeamRunManifest;
-	tasks: TeamTaskState[];
-	manifestMtimeMs: number;
-	manifestSize: number;        // <-- thêm
-	tasksMtimeMs: number;
-	tasksSize: number;           // <-- thêm
-}
-
-// Validate
-if (cached
-    && cached.manifestMtimeMs === manifestStat.mtimeMs
-    && cached.manifestSize === manifestStat.size
-    && cached.tasksMtimeMs === tasksMtimeMs
-    && cached.tasksSize === (tasksStat?.size ?? 0)) {
-	return { manifest: cached.manifest, tasks: cached.tasks };
-}
-
-// Khi cache:
-manifestCache.set(stateRoot, {
-	manifest, tasks,
-	manifestMtimeMs: manifestStat.mtimeMs,
-	manifestSize: manifestStat.size,
-	tasksMtimeMs,
-	tasksSize: tasksStat?.size ?? 0,
-});
-```
-
-**Verification:**
-```bash
-node --experimental-strip-types --test test/unit/state-store.test.ts
-# Test mới: write manifest 2 lần liên tiếp với content khác nhau cùng mtime giả định, verify load lần 2 không trả cached
-```
-
-**Risk:** Thấp — chỉ thắt chặt validation, không loại trừ cache hit hợp lệ.
-
----
-
-### Task #20 — Tách ensureMailbox thành 2 hàm rõ ràng (LOW)
-
-**Vấn đề:**
-`ensureMailbox(manifest, taskId?)` trong `src/state/mailbox.ts:54-62` xử lý cả run-level và task-level. Dòng 60 gọi `mkdirSync(mailboxDir(manifest), ...)` lặp lại vì task path đã chứa run path. Code khó đọc, dễ regress khi thêm scope mới.
-
-**Vị trí:** `src/state/mailbox.ts:54-62`
-
-**Đề xuất fix:**
-```ts
-function ensureRunMailbox(manifest: TeamRunManifest): void {
-	fs.mkdirSync(mailboxDir(manifest), { recursive: true });
-	for (const direction of ["inbox", "outbox"] as const) {
-		const filePath = mailboxPath(manifest, direction);
-		if (!fs.existsSync(filePath)) fs.writeFileSync(filePath, "", "utf-8");
-	}
-	const delivery = deliveryPath(manifest);
-	if (!fs.existsSync(delivery)) {
-		fs.writeFileSync(delivery, `${JSON.stringify({ messages: {}, updatedAt: new Date().toISOString() }, null, 2)}\n`, "utf-8");
-	}
-}
-
-function ensureTaskMailbox(manifest: TeamRunManifest, taskId: string): void {
-	ensureRunMailbox(manifest); // task-level cần delivery.json ở run-level
-	fs.mkdirSync(taskMailboxDir(manifest, taskId), { recursive: true });
-	for (const direction of ["inbox", "outbox"] as const) {
-		const filePath = mailboxPath(manifest, direction, taskId);
-		if (!fs.existsSync(filePath)) fs.writeFileSync(filePath, "", "utf-8");
-	}
-}
-
-// Update tất cả call sites:
-//   ensureMailbox(manifest)             → ensureRunMailbox(manifest)
-//   ensureMailbox(manifest, taskId)     → ensureTaskMailbox(manifest, taskId)
-```
-
-**Verification:**
-```bash
-node --experimental-strip-types --test test/unit/mailbox-api.test.ts test/unit/mailbox-validation.test.ts
-```
-
-**Risk:** Thấp — refactor thuần, behavior không đổi.
-
----
-
-### Task #21 — ✅ ĐÃ HOÀN THÀNH trong review
-
-Giảm circular import giữa `team-tool.ts` ↔ `tool-result.ts`:
-- `src/extension/tool-result.ts` — đổi `import type { TeamToolDetails } from "./team-tool.ts"` → `from "./team-tool-types.ts"`
-- `src/extension/management.ts` — tương tự
-
-Cần verify thêm chưa có chỗ nào còn import xấu:
-```powershell
-Select-String -Path src\extension\*.ts,src\extension\**\*.ts -Pattern 'TeamToolDetails.*from "(\.\.?/)*team-tool\.ts"'
-```
-Nếu còn match → đổi sang `team-tool-types.ts`.
-
----
-
-### Task #22 — Codemod TeamContext import rời khỏi team-tool.ts (LOW)
-
-**Vấn đề:**
-`team-tool.ts:40` re-export `TeamContext` từ `./team-tool/context.ts`. Các file khác import qua `team-tool.ts` tạo dependency chain dài. Nên import trực tiếp từ `./team-tool/context.ts` để rõ chuỗi dependency.
-
-**Vị trí:** Search:
-```powershell
-Select-String -Path src\**\*.ts -Pattern 'TeamContext.*from "(\.\.?/)*extension/team-tool\.ts"'
-```
-
-**Đề xuất fix:**
-Đổi import sang `team-tool/context.ts`. Có thể giữ re-export ở `team-tool.ts` cho backward compat ngoài (extension API public).
-
-**Verification:**
-```bash
-npx tsc --noEmit
-npm test
-```
-
-**Risk:** Thấp — refactor pure.
-
----
-
-### Task #23 — Subagent stuck-blocked notification (LOW, từ #16c Phase 1)
-
-**Vấn đề:**
-`subagent-manager.ts` có status `"blocked"` trong `TERMINAL_RUN_STATUS` nhưng không có notification UI khi child run blocked > N phút. User không biết child đang stuck.
-
-**Vị trí:** `src/runtime/subagent-manager.ts`
-
-**Đề xuất fix:**
-
-1. Thêm constant trong `config/defaults.ts`:
-```ts
-export const DEFAULT_SUBAGENT = {
-	stuckBlockedNotifyMs: 5 * 60_000, // 5 phút
-};
-```
-
-2. Bổ sung field vào `SubagentRecord`:
-```ts
-export interface SubagentRecord {
-	// ... existing
-	stuckNotified?: boolean;
-}
-```
-
-3. Trong polling/watch loop kiểm tra child status:
-```ts
-import { DEFAULT_SUBAGENT } from "../config/defaults.ts";
-
-if (record.status === "blocked"
-    && record.startedAt
-    && Date.now() - record.startedAt > DEFAULT_SUBAGENT.stuckBlockedNotifyMs
-    && !record.stuckNotified) {
-	emitEvent("subagent.stuck-blocked", {
-		id: record.id,
-		runId: record.runId,
-		durationMs: Date.now() - record.startedAt,
-	});
-	record.stuckNotified = true;
-	savePersistedSubagentRecord(cwd, record);
-}
-```
-
-4. UI/dashboard subscribe event `subagent.stuck-blocked` hiển thị badge cảnh báo.
-
-**Verification:**
-Test mới `test/unit/subagent-stuck-notify.test.ts`:
-```ts
-test("subagent blocked > threshold emits stuck-blocked event", async () => {
-	const record = createRecord({ status: "blocked", startedAt: Date.now() - 10 * 60_000 });
-	const events: string[] = [];
-	checkSubagentStuck(record, (type) => events.push(type));
-	assert.ok(events.includes("subagent.stuck-blocked"));
-	assert.equal(record.stuckNotified, true);
-});
-```
-
-**Risk:** Thấp — feature mới, không ảnh hưởng path hiện có.
-
----
-
-### Task #24 — TypeBox config validation warnings (MEDIUM)
-
-**Vấn đề:**
-`config.ts` `parseConfig()` dùng `parseWithSchema` trả `undefined` khi schema fail → silent drop. User config sai sẽ bị bỏ qua không cảnh báo.
-
-**Vị trí:** `src/config/config.ts:189-207, parseConfig()`
-
-**Đề xuất fix:**
-
-1. Thêm hàm `validateConfigStrict` trả về warnings:
-```ts
-import { Value } from "typebox/value";
-import { PiTeamsConfigSchema } from "../schema/config-schema.ts";
-
-export interface ConfigValidation {
-	config: PiTeamsConfig;
-	warnings: string[];
-}
-
-export function validateConfigStrict(raw: unknown): ConfigValidation {
-	const warnings: string[] = [];
-	if (raw && typeof raw === "object" && !Value.Check(PiTeamsConfigSchema, raw)) {
-		for (const err of Value.Errors(PiTeamsConfigSchema, raw)) {
-			warnings.push(`Config invalid at ${err.path}: ${err.message}`);
-		}
-	}
-	return { config: parseConfig(raw), warnings };
-}
-```
-
-2. Thêm field `warnings` vào `LoadedPiTeamsConfig`:
-```ts
-export interface LoadedPiTeamsConfig {
-	config: PiTeamsConfig;
-	path: string;
-	paths: string[];
-	error?: string;
-	warnings?: string[];   // <-- thêm
-}
-```
-
-3. `loadConfig()` populate warnings từ cả user + project config:
-```ts
-export function loadConfig(cwd?: string): LoadedPiTeamsConfig {
-	const filePath = configPath();
-	const paths = cwd ? [filePath, projectConfigPath(cwd)] : [filePath];
-	const warnings: string[] = [];
-	try {
-		const userValidation = validateConfigStrict(readConfigRecord(filePath));
-		warnings.push(...userValidation.warnings.map((w) => `${filePath}: ${w}`));
-		let config = userValidation.config;
-		if (cwd) {
-			const projectValidation = validateConfigStrict(readConfigRecord(projectConfigPath(cwd)));
-			warnings.push(...projectValidation.warnings.map((w) => `${projectConfigPath(cwd)}: ${w}`));
-			config = mergeConfig(config, projectValidation.config);
-		}
-		return { path: filePath, paths, config, warnings: warnings.length ? warnings : undefined };
-	} catch (error) {
-		const message = error instanceof Error ? error.message : String(error);
-		return { path: filePath, paths, config: {}, error: message };
-	}
-}
-```
-
-4. UI hiển thị warnings trong action `team doctor` (`handleDoctor`).
-
-**Verification:**
-```bash
-node --experimental-strip-types --test test/unit/config-schema-validation.test.ts
-# Thêm test:
-//   - invalid config (e.g., notifierIntervalMs: 100) → warnings non-empty
-//   - valid config → warnings undefined
-```
-
-**Risk:** Thấp — chỉ thêm thông tin, không thay đổi runtime behavior. Backward-compat: nếu callers không đọc `warnings` thì không ảnh hưởng.
-
----
-
-### Task #25 — atomicWriteFileAsync idempotent retry (LOW)
-
-**Vấn đề:**
-`atomicWriteFileAsync` ghi temp + rename. Nếu 2 process song song write cùng `filePath`, đôi khi rename của process A vào lúc process B đã rename xong → `EPERM`/`EBUSY` Windows. Retry handle nhưng có thể spin nhiều lần không cần thiết.
-
-**Vị trí:** `src/state/atomic-write.ts:34-46`
-
-**Đề xuất fix:**
-Sau retry exhaust, kiểm tra nếu file đã tồn tại với content khớp mong muốn → coi như success (idempotent write):
-
-```ts
-export async function atomicWriteFileAsync(filePath: string, content: string): Promise<void> {
-	await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
-	const tempPath = `${filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
-	try {
-		await fs.promises.writeFile(tempPath, content, "utf-8");
-		try {
-			await __test__renameWithRetryAsync(tempPath, filePath);
-		} catch (renameError) {
-			// Idempotent fallback: nếu file đã có nội dung khớp → success
-			try {
-				const existing = await fs.promises.readFile(filePath, "utf-8");
-				if (existing === content) {
-					await fs.promises.rm(tempPath, { force: true });
-					return;
-				}
-			} catch {
-				// file không tồn tại hoặc không đọc được → throw original
-			}
-			throw renameError;
-		}
-	} catch (error) {
-		try {
-			await fs.promises.rm(tempPath, { force: true });
-		} catch (cleanupError) {
-			logInternalError("atomic-write.cleanupAsync", cleanupError, `tempPath=${tempPath}`);
-		}
-		throw error;
-	}
-}
-```
-
-**Verification:**
-Stress test mới `test/unit/atomic-write-concurrent.test.ts`:
-```ts
-test("100 concurrent writes of same content succeed", async () => {
-	const filePath = path.join(tmpDir, "concurrent.json");
-	await Promise.all(
-		Array.from({ length: 100 }, () => atomicWriteFileAsync(filePath, '{"v":1}'))
-	);
-	assert.equal(fs.readFileSync(filePath, "utf-8"), '{"v":1}');
-});
-```
-
-**Risk:** Trung bình — race rất hiếm, ưu tiên sau cùng. Cần test kỹ trên Windows + Linux để chắc fallback không hide bug.
-
----
-
-## Quick Reference — Verification cho mọi follow-up task
-
-```powershell
-Set-Location D:\my\my_project\pi-crew
-
-# Type check (PHẢI pass sau task #17)
-npx tsc --noEmit
-
-# Targeted tests
-node --experimental-strip-types --test test/unit/<file>.test.ts
-
-# Full unit suite
-npm run test:unit
-
-# Full CI
-npm run ci   # = typecheck + test + npm pack --dry-run
-```
-