pi-crew 0.1.49 → 0.2.0

package/docs/refactor-tasks-phase6.md

@@ -1,662 +0,0 @@
-# Phase 6 Refactor Plan — Robustness sau test 0.1.27/0.1.29 + nợ kỹ thuật từ source-runtime-refactor-map
-
-> Xuất xứ:
-> - Test thực tế run `team_20260428152644_2ae0dce7` (parallel-research, 10/10 completed) trên pi-crew@0.1.27.
-> - Re-read source 28/04/2026 sau bump 0.1.28 (responseTimeoutMs 15s→5m) và 0.1.29 (republish).
-> - Findings còn lại từ `docs/source-runtime-refactor-map.md` (subagent runtime consolidation, model-routing persistence, adaptive planner repair).
->
-> Phase 5 đã hoàn tất (UI/footer/select-list/theme hot-reload). Phase 6 tập trung **runtime hardening + maintainability**, không phá public API.
-
-## Quy ước chung (giữ nguyên từ Phase 5)
-- Không phá vỡ public API: tool actions, slash commands, config schema, schema.json.
-- Sau mỗi task: `npx tsc --noEmit` + `npm run test:unit` (`test:integration` khi đụng runtime/spawn/state).
-- Không thêm runtime dependency mới ngoài stdlib + peer deps đã có (`pi-coding-agent`, `pi-ai`, `pi-agent-core`, `pi-tui`, `jiti`).
-- Mỗi task = 1 commit độc lập, có thể revert riêng. Test name bám sát hành vi (`describe`/`it` đặt theo contract chứ không theo file).
-- Default behavior không đổi (backward-compat); cải tiến hành vi đi qua opt-in env/config khi có nguy cơ regression.
-- Mỗi task có Acceptance + Verification + Risk/Rollback. Trước khi mở PR phải `npm run ci` (typecheck + test:unit + test:integration + npm pack --dry-run).
-
-## Roadmap tổng quan
-
-| Tier | Workstream | Số task | Ước tính | Ưu tiên |
-|---|---|---|---|---|
-| **1** | Background runner & async robustness | T60–T62 | 0.5 ngày | P0 — chặn rủi ro silent fail |
-| **1** | Concurrency hard cap | T63 | 0.25 ngày | P0 — chặn user override DoS |
-| **2** | Resume durability cho synthesize/write | T64–T66 | 1 ngày | P1 — nâng cao reliability |
-| **2** | Adaptive planner repair/retry | T67 | 0.5 ngày | P1 — giảm block rate |
-| **2** | Model routing persistence | T68–T69 | 0.5 ngày | P1 — observability |
-| **3** | register.ts modularization | T70–T72 | 1 ngày | P2 — maintainability |
-| **3** | Subagent runtime consolidation | T73–T75 | 1.5 ngày | P2 — debt theo refactor map |
-| **3** | Skills builtin + docs self-contained | T76–T78 | 0.5 ngày | P3 — polish |
-| **4** | Tests, smoke, CHANGELOG | T79–T81 | 0.5 ngày | P0 (cuối phase) |
-
-Tổng: **22 task / ~6.25 ngày**, có thể ship theo nhiều mini-release (0.1.30, 0.1.31, …).
-
-## Tiến độ triển khai
-
-| Task | Trạng thái | Commit / ghi chú |
-|---|---|---|
-| T60 | ✅ Done | `bfd9bc8` — jiti loader resolution/fail-fast |
-| T61 | ✅ Done | `bfd9bc8` — async early-exit guard |
-| T62 | ✅ Done | `bfd9bc8` — async startup marker |
-| T63 | ✅ Done | `bfd9bc8` — concurrency hard cap + opt-out |
-| T64 | ✅ Done | checkpoint phases + child-stdout-final/artifact-written resume recovery |
-| T65 | ✅ Done | async notifier marks quiet dead background runners failed with `async.died` |
-| T66 | ✅ Done | `5e495dc` — replay pending mailbox on resume |
-| T67 | ✅ Done | adaptive plan repair for malformed JSON, oversized plans, and role aliases |
-| T68 | ✅ Done | `1f92b8a` — persisted model routing metadata |
-| T69 | ✅ Done | `1f92b8a` — agent records carry routing metadata |
-| T70 | ✅ Done | `register.ts` split to ≤200 lines with commands, team tool, subagent tools, artifact cleanup modules |
-| T71 | ✅ Done | `team-tool.ts` split to ≤300 lines with status/inspect/lifecycle/cancel/plan modules |
-| T72 | ✅ Done | `task-runner.ts` split to ≤300 lines with prompt/progress/state/live/result helper modules |
-| T73 | ✅ Done | `src/subagents/*` entrypoints added and runtime call-sites migrated |
-| T74 | ✅ Done | live-session APIs routed through `src/subagents/live/*` with dynamic task-runner import |
-| T75 | ✅ Done | `1004589` + explicit subagent depth/role spawn tests |
-| T76 | ✅ Done | `f6ece8e` — built-in coding skills |
-| T77 | ✅ Done | `9e54acd` — self-contained architecture docs |
-| T78 | ✅ Done | `9e54acd` — runtime flow docs |
-| T79 | ✅ Done | multi-shard, no-wrapper spawn, and async restart recovery smokes covered |
-| T80 | ✅ Done | package snapshot guards docs/skills/jiti/pi manifest packaging |
-| T81 | ✅ Done | changelog release prep notes added; no publish/version bump performed |
-
----
-
-## Tier 1 — Robustness chặn rủi ro silent fail (P0)
-
-### Task #60 — `background-runner.ts` fail-fast nếu jiti loader không tồn tại
-
-**Lý do (evidence)**: `src/runtime/background-runner.ts` `getBackgroundRunnerCommand()` xây cứng đường dẫn:
-```ts
-const jitiRegisterPath = path.join(packageRoot, "node_modules", "jiti", "lib", "jiti-register.mjs");
-return { args: ["--import", pathToFileURL(jitiRegisterPath).href, runnerPath, ...], loader: "jiti" };
-```
-Nếu user xóa `node_modules/jiti` (npm prune, monorepo hoisting bất thường, broken install), `spawn(process.execPath, ...)` không fail ở Node parent — child sẽ exit lỗi ngay nhưng parent không capture được vì stdout đã `child.unref()` + đóng `logFd`. Background log chỉ chứa `[pi-crew] background loader=jiti` rồi im lặng. Run sẽ kẹt ở status `running` cho đến khi `process-status.hasStaleAsyncProcess` mark stale (>10 phút).
-
-**Đích**: `src/runtime/background-runner.ts`
-
-**Steps**:
-1. Trước khi `spawn`, kiểm tra `fs.existsSync(jitiRegisterPath)`. Nếu thiếu → throw `Error` với message rõ ràng:
-   ```
-   pi-crew background runner cannot start: jiti loader not found at
-   <jitiRegisterPath>. Reinstall pi-crew (`pi install npm:pi-crew`) or
-   ensure node_modules/jiti is present.
-   ```
-2. Caller (`team-tool/run.ts` qua `spawnBackgroundTeamRun`) đã có try/catch — đảm bảo error propagate ra notify cho user.
-3. Append error vào `events.jsonl` qua `appendEvent(eventsPath, { type: "async.failed", message })` trước khi throw.
-4. Mở rộng: thêm fallback path tìm jiti trong `require.resolve.paths()` của parent module (Windows monorepo hoist) — nếu primary path missing thì thử `path.join(packageRoot, "..", "..", "node_modules", "jiti", "lib", "jiti-register.mjs")` (npm hoisting 2 cấp). Nếu cả hai miss thì mới throw.
-
-**Acceptance**:
-- Khi `node_modules/jiti/lib/jiti-register.mjs` thiếu → `spawnBackgroundTeamRun` throw với message hướng dẫn reinstall.
-- Khi user dùng monorepo hoisting (jiti ở root workspace) → vẫn resolve được.
-- `events.jsonl` có entry `async.failed` trước khi spawn.
-- Không regression với case có jiti (path 1 hit).
-
-**Tests**: `test/unit/background-runner.fail-fast.test.ts`
-- Stub `fs.existsSync` để giả lập miss → assert throw với pattern `/jiti loader not found/`.
-- Stub hoist path tồn tại → assert dùng path thay thế.
-- Cleanup không leak global state (`vi`-style spy + restore).
-
-**Verification**:
-```bash
-npx tsc --noEmit
-node --experimental-strip-types --test test/unit/background-runner.fail-fast.test.ts
-```
-
-**Risk/Rollback**: Risk thấp — chỉ thêm sanity check trước spawn. Rollback bằng cách revert commit.
-
-**Security/Perf notes**: Không I/O bổ sung trong hot path (chỉ 1 stat khi spawn background). Không log đường dẫn đầy đủ ở mức user message để tránh lộ home directory; dùng `shortenPath()` từ `utils/visual.ts` nếu có.
-
----
-
-### Task #61 — Capture early-exit của background runner (drain `background.log`)
-
-**Lý do**: Hiện sau `child.unref(); fs.closeSync(logFd);` parent quên child. Nếu background-runner.ts lỗi cú pháp/import (không phải jiti missing nhưng vẫn fail), log chỉ chứa stderr Node. Status tool báo `Async: pid=X alive=false` sau khi process exit, nhưng manifest status vẫn `running`. User phải đợi `hasStaleAsyncProcess` (10 phút) mới detect.
-
-**Đích**: `src/extension/team-tool/run.ts` (caller) và `src/runtime/process-status.ts`
-
-**Steps**:
-1. Trong caller, lưu `pid` ngay sau spawn. Schedule một check sau ~3s (`setTimeout` + `unref`) gọi `checkProcessLiveness(pid)`:
-   - Nếu `alive=false` AND manifest vẫn `running` AND chưa có event `async.started` → đọc `background.log` (last 4KB), append event `async.failed` với log tail và `updateRunStatus(manifest, "failed", "Background runner exited within 3s; see background.log")`.
-2. Cancel `setTimeout` nếu trong khoảng đó status đã chuyển khác `running`.
-3. Đảm bảo không double-write status nếu background process đã write `async.failed` từ catch block.
-
-**Acceptance**:
-- Background runner exit ngay → run status chuyển `failed` trong ≤4s với reason có tail log.
-- Background runner chạy bình thường → không có false positive.
-
-**Tests**: `test/integration/background-early-exit.test.ts`
-- Mock `spawnBackgroundTeamRun` với child exit ngay (set `PI_TEAMS_MOCK_CHILD_PI=fail-immediate` + extend mock branch).
-
-**Verification**: `npm run test:integration -- background-early-exit`
-
-**Risk/Rollback**: Cần test kỹ với case async hợp lệ; rollback bằng feature flag `PI_CREW_ASYNC_EARLY_EXIT_GUARD=0`.
-
----
-
-### Task #62 — `async.started` event timeout & marker file
-
-**Lý do**: Bổ sung `T61`. Background runner ghi `async.started` vào `events.jsonl` ở dòng đầu `main()`. Nếu file `events.jsonl` bị lock (Windows), event không append được. Caller hiện không có cơ chế chờ confirm.
-
-**Đích**: `src/runtime/async-runner.ts` + `src/runtime/background-runner.ts`
-
-**Steps**:
-1. Background runner ghi marker file `state/runs/{runId}/async.pid` chứa `{pid, startedAt}` ngay sau khi `appendEvent("async.started")` thành công.
-2. Caller (T61) khi healthcheck 3s đọc thêm marker file: nếu marker tồn tại → coi như runner đã start ổn.
-3. Bổ sung `process-status.hasAsyncStartMarker(runId)`.
-
-**Acceptance**: Marker tồn tại sau khi async runner startup; healthcheck dùng marker khi events.jsonl không khả dụng (Windows lock fallback).
-
-**Tests**: unit cho `hasAsyncStartMarker` (file exists/missing/parse error).
-
-**Verification**: `npm run test:unit`
-
----
-
-### Task #63 — Hard cap cho `limits.maxConcurrentWorkers`
-
-**Lý do**: `src/runtime/concurrency.ts.resolveBatchConcurrency()` dùng `limits.maxConcurrentWorkers` user truyền **không cap**. User config `limits.maxConcurrentWorkers=64` → 64 child Pi process spawn song song → DoS local. `parallel-utils.MAX_PARALLEL_CONCURRENCY=4` chỉ áp ở subagent runner cấp thấp, không bảo vệ scheduler.
-
-**Đích**: `src/runtime/concurrency.ts`, `src/config/defaults.ts`, `src/config/config.ts`
-
-**Steps**:
-1. Thêm `DEFAULT_CONCURRENCY.hardCap = 8` vào `defaults.ts`.
-2. Trong `resolveBatchConcurrency`, sau `requested = limitMax ?? teamMax ?? workflowMax ?? defaultWorkflowConcurrency`:
-   ```ts
-   const cap = positiveInteger(input.hardCap) ?? DEFAULT_CONCURRENCY.hardCap;
-   const effective = Math.min(requested, cap);
-   ```
-3. Khi `effective < requested`, ghi `reason` thêm `;capped:${cap}` để observability.
-4. Cho phép user opt-out qua `config.limits.allowUnboundedConcurrency=true` (gated qua warning event `limits.unbounded` + log dòng đầu run, default false).
-5. Cập nhật `schema.json` + `config-schema.ts` cho field mới.
-
-**Acceptance**:
-- `limits.maxConcurrentWorkers=64` (default) → effective=8, reason chứa `capped:8`.
-- `limits.maxConcurrentWorkers=64, allowUnboundedConcurrency=true` → effective=64, có event warning.
-- Không regression cho values hợp lý (≤8).
-
-**Tests**: `test/unit/concurrency.cap.test.ts`
-- 4 case: requested=2 (no cap), requested=12 (cap=8), unbounded flag (no cap), workflow=parallel-research workflowMax=4 (no cap).
-
-**Verification**: `npx tsc --noEmit && node --experimental-strip-types --test test/unit/concurrency.cap.test.ts`
-
-**Risk/Rollback**: Có thể vô tình giảm throughput cho user power-user. Mitigate bằng `allowUnboundedConcurrency` flag. Rollback: revert + bump major nếu user đã dựa vào behavior cũ (chưa rõ).
-
-**Security/Perf notes**: Bảo vệ memory/cpu local; mỗi child Pi consume ~200MB RAM. 8 = 1.6GB worst case, hợp lý cho dev machine.
-
----
-
-## Tier 2 — Reliability nâng cao (P1)
-
-### Task #64 — Resume detection: synthesize/write checkpoint
-
-**Lý do**: `team-runner.executeTeamRun` không biết task synthesize/write đã completed một phần khi crash giữa chừng. Khi resume (`team resume runId`), task `synthesize` re-run từ đầu, gọi LLM lại tốn cost. Risk #5 trong test report.
-
-**Đích**: `src/runtime/task-runner.ts`, `src/state/state-store.ts`, `src/state/types.ts`
-
-**Steps**:
-1. Mở rộng `TeamTaskState` thêm `checkpoint?: { phase: "started" | "child-spawned" | "child-stdout-final" | "artifact-written"; updatedAt: string; childPid?: number }`.
-2. `runTeamTask` ghi checkpoint qua `saveRunTasks` ở 4 điểm:
-   - Trước `runChildPi` (`started`)
-   - Sau `child.pid` có (`child-spawned` + pid)
-   - Khi nhận `isFinalAssistantEvent` (`child-stdout-final`)
-   - Sau `writeArtifact` (`artifact-written`)
-3. `team-tool.handleResume` xét checkpoint:
-   - Nếu `checkpoint.phase === "artifact-written"` mà status vẫn `running` → mark `completed` (recovery, không re-run).
-   - Nếu `checkpoint.phase === "child-stdout-final"` → cố parse output từ `transcripts/{taskId}.jsonl` last lines, nếu có valid `message_end` thì mark `completed` mà không re-spawn.
-   - Else → re-queue.
-
-**Acceptance**:
-- Crash sau khi artifact ghi xong → resume mark `completed` không re-run LLM.
-- Crash giữa stdout streaming → resume cố recover từ transcript; nếu không thành công thì re-run.
-- State migration backward-compat (task cũ không có `checkpoint` → resume hoạt động như cũ).
-
-**Tests**: `test/integration/resume-checkpoint.test.ts`
-- 3 case: pre-spawn crash, mid-stream crash, post-artifact crash.
-
-**Verification**: `npm run test:integration -- resume-checkpoint`
-
-**Risk/Rollback**: Touch durable state shape. Cần migration: nếu task không có `checkpoint`, treat như chưa start. Rollback: revert + xóa field optional khỏi types.
-
----
-
-### Task #65 — Resume cho async background run sau parent crash
-
-**Lý do**: Khi parent Pi session crash, background runner vẫn chạy; manifest cập nhật bình thường. Nhưng nếu **background runner crash** (ví dụ jiti corrupted, OOM), không có ai mark run failed cho đến `hasStaleAsyncProcess` 10 phút sau. Status sẽ misleading.
-
-**Đích**: `src/runtime/process-status.ts`, `src/extension/async-notifier.ts`
-
-**Steps**:
-1. Mở rộng `async-notifier.ts.startAsyncRunNotifier`: với mỗi run đang `running`, mỗi `notifierIntervalMs` (5s) check `checkProcessLiveness(async.pid)`. Nếu `alive=false` VÀ run status `running` AND không có event nào trong 30s gần nhất → `updateRunStatus(manifest, "failed", "Background runner died unexpectedly; check background.log")`.
-2. Bổ sung guard: chỉ thực hiện nếu chưa có event `async.completed`/`async.failed` (avoid double-write).
-
-**Acceptance**: Background runner kill -9 → trong ≤30s status chuyển `failed`, có event `async.died`.
-
-**Tests**: `test/integration/async-died.test.ts` (mock spawn process exit ngẫu nhiên).
-
-**Verification**: `npm run test:integration -- async-died`
-
-**Risk/Rollback**: False positive khi event log chậm flush. Mitigate: chỉ trigger khi không alive AND last event > 30s. Rollback: revert async-notifier hook.
-
----
-
-### Task #66 — Mailbox replay khi resume
-
-**Lý do**: `state/mailbox` có inbox/outbox JSONL nhưng resume không re-deliver pending messages. Risk #5 mở rộng.
-
-**Đích**: `src/state/mailbox.ts`, `src/extension/team-tool/api.ts`
-
-**Steps**:
-1. Khi resume, đọc `mailbox/delivery.json`. Mọi message `direction=inbox` chưa `acked=true` → re-emit trong batch đầu.
-2. Add `validate-mailbox repair=true` vào doctor checks để cleanup stale messages > 7 ngày.
-
-**Acceptance**: Resume sau crash giữa khi mailbox có 3 message pending → 3 message được redelivered.
-
-**Tests**: `test/unit/mailbox-replay.test.ts`
-
-**Verification**: `npm run test:unit`
-
----
-
-### Task #67 — Adaptive planner repair/retry trước khi block
-
-**Lý do**: `team-runner.injectAdaptivePlanIfReady` block ngay khi `__test__parseAdaptivePlan` fail (oversize >12 task / JSON malformed / role không hợp lệ). User phải re-run từ đầu. Refactor map đã ghi nhận: "Add adaptive planner repair/retry for invalid JSON instead of immediate block when safe."
-
-**Đích**: `src/runtime/team-runner.ts`, `agents/planner.md`
-
-**Steps**:
-1. Khi parse fail, thay vì return `missingPlan: true` ngay, thử **repair**:
-   - Nếu JSON malformed → spawn 1 child Pi tiny (planner role, model rẻ — Haiku/gpt-5-nano) với prompt: `Fix the following JSON to comply with the adaptive plan schema. Return only ADAPTIVE_PLAN_JSON_START ... ADAPTIVE_PLAN_JSON_END.\n<failed_text>`. Cap retry = 1, timeout 60s.
-   - Nếu oversize (>12 task) → tự trim phases tail tới ≤12 task, ghi event `adaptive.plan_trimmed`.
-   - Nếu role không hợp lệ → map sang role gần nhất (`reviewer`→`code-reviewer` nếu team có) hoặc skip task đó nếu phase không trống.
-2. Nếu repair fail → mới block (giữ behavior hiện tại). Ghi event `adaptive.plan_repair_failed`.
-3. Persist repair attempt vào `metadata/adaptive-repair.json` để debug.
-
-**Acceptance**:
-- Plan JSON malformed nhỏ (thiếu `}`) → repair fix → run tiếp.
-- Plan 15 task → trim còn 12, run tiếp với warning.
-- Plan với role lạ → map hoặc skip task; nếu không cứu được thì block với explain rõ ràng.
-
-**Tests**: `test/unit/adaptive-repair.test.ts` (3 fixture: malformed, oversize, invalid-role).
-
-**Verification**: `npm run test:unit -- adaptive-repair`
-
-**Risk/Rollback**: Có thể ăn thêm 1 model call. Mitigate: chỉ retry khi cost < 0.001 USD ước tính (Haiku tier). Rollback: env `PI_CREW_ADAPTIVE_REPAIR=0`.
-
----
-
-### Task #68 — Persist model routing (requested → selected → fallback chain → reason)
-
-**Lý do**: Refactor map: "Move model routing transparency into persisted task/subagent records: requested model, selected model, fallback chain, fallback reason." Hiện task state chỉ có `modelAttempts: ModelAttemptSummary[]` (model + success + error) nhưng không persist `requestedModel` ban đầu user/agent yêu cầu, cũng như reason vì sao chuyển fallback.
-
-**Đích**: `src/runtime/model-fallback.ts`, `src/state/types.ts`, `src/runtime/task-runner.ts`
-
-**Steps**:
-1. Mở rộng `TeamTaskState.modelRouting?: { requested?: string; resolved: string; fallbackChain: string[]; reason?: string; usedAttempt: number }`.
-2. `buildConfiguredModelCandidates` trả thêm `requestedModel` (model agent.md / step.model trước fallback).
-3. `runTeamTask` write `modelRouting` cùng `modelAttempts`.
-4. `team-tool.handleStatus` render section `Model routing:` nếu có. Dashboard agent rows hiển thị `model · ≥requested:claude-sonnet-4-5 → openai-codex/gpt-5.5 (rate-limit)`.
-
-**Acceptance**:
-- Task chạy thành công lần 1 → `usedAttempt=0`, `fallbackChain` chứa chain config (không cần markFallback).
-- Task fallback từ A → B vì rate-limit → `reason: "rate-limit"`, `usedAttempt=1`.
-- Status output có dòng `Model routing` cho mỗi task có routing data.
-
-**Tests**: `test/unit/model-routing.test.ts`
-
-**Verification**: `npm run test:unit`
-
-**Risk/Rollback**: Task state shape mở rộng — backward-compat (field optional). Rollback: revert types + hide UI.
-
----
-
-### Task #69 — Subagent records lưu model routing
-
-**Lý do**: Liên quan T68 nhưng cho `crew-agent-records` (file-backed agent status hiển thị ở dashboard). Hiện chỉ có `model` field (latest selected); cần `requestedModel` + `fallbackChain`.
-
-**Đích**: `src/runtime/crew-agent-records.ts`
-
-**Steps**:
-1. Mở rộng `CrewAgentRecord` thêm `routing?: TeamTaskState["modelRouting"]`.
-2. `recordFromTask` map từ `task.modelRouting`.
-3. `live-run-sidebar` render `routing` ở chỗ model row.
-
-**Tests**: snapshot trong `test/unit/crew-agent-records.test.ts`.
-
-**Verification**: `npm run test:unit`
-
----
-
-## Tier 3 — Maintainability & debt cleanup (P2)
-
-### Task #70 — Tách `register.ts` thành sub-modules theo lifecycle
-
-**Lý do**: `src/extension/register.ts` ~38KB trộn: lifecycle, RPC, manifest cache, foreground controller, sidebar, widget, mascot, command parsing, subagent manager, viewers. Quy tắc AGENTS.md "Keep `index.ts` minimal; register functionality from `src/extension/register.ts`. Prefer small modules over large orchestrator files." Đã có sub-folders `registration/` + `team-tool/` nhưng register.ts vẫn lớn.
-
-**Đích**: `src/extension/register.ts` → split
-
-**Steps**:
-1. Tách thành 5 module:
-   - `src/extension/registration/lifecycle.ts` — session_start/session_before_switch/session_shutdown handlers + cleanupRuntime.
-   - `src/extension/registration/widget-loop.ts` — widget interval, sidebar lifecycle (`openLiveSidebar`, `liveSidebarTimer`).
-   - `src/extension/registration/foreground-runner.ts` — `startForegroundRun` + `foregroundControllers`.
-   - `src/extension/registration/subagent-tools.ts` — Agent/get_subagent_result/steer_subagent + crew_* aliases.
-   - `src/extension/registration/commands.ts` — đăng ký toàn bộ slash command (`/teams`, `/team-run`, …).
-2. `register.ts` còn lại chỉ là wiring (≤200 dòng): tạo state, gọi các module.
-3. Giữ public API (export `registerPiTeams`, `__test__subagentSpawnParams`).
-
-**Acceptance**: 
-- `register.ts` ≤200 dòng.
-- Mỗi module mới ≤300 dòng.
-- Tests cũ pass không thay đổi.
-- Thêm test snapshot cho commands list (đảm bảo không drop command nào).
-
-**Tests**: `test/unit/registration.commands-coverage.test.ts` (assert 25 commands đăng ký).
-
-**Verification**: `npx tsc --noEmit && npm run test`
-
-**Risk/Rollback**: Refactor lớn — risk regression. Mitigate: tách từng commit nhỏ (1 module / commit). Rollback: revert lần lượt.
-
----
-
-### Task #71 — Tách `team-tool.ts` actions còn lại
-
-**Lý do**: `src/extension/team-tool.ts` ~32KB. Đã có `team-tool/{api,run,doctor}.ts`. Còn `handleStatus`, `handleEvents`, `handleArtifacts`, `handleWorktrees`, `handleResume`, `handleCancel`, `handleSummary`, `handleCleanup`, `handleForget`, `handlePrune`, `handleExport`, `handleImport`, `handleImports` ở file chính.
-
-**Đích**: `src/extension/team-tool.ts` → split
-
-**Steps**:
-1. Tạo `src/extension/team-tool/{status,events,artifacts,resume,lifecycle-actions}.ts`.
-2. `team-tool.ts` chỉ giữ router (`handleTeamTool`) + `handleList`/`handleGet` (đã ngắn).
-
-**Acceptance**: `team-tool.ts` ≤300 dòng. Mỗi sub-module ≤300 dòng.
-
-**Tests**: existing pass.
-
-**Verification**: `npm run test`
-
----
-
-### Task #72 — Tách `task-runner.ts`
-
-**Lý do**: `src/runtime/task-runner.ts` ~28KB chứa: prompt building, child-pi orchestration, artifact writing, verification evidence, transcripts, retry logic, mailbox bridge.
-
-**Đích**: split thành:
-- `task-runner/prompt-builder.ts` (renderTaskPrompt + readOnlyRoleInstructions + coordinationBridgeInstructions).
-- `task-runner/artifact-writer.ts` (writeTaskInputs/Outputs/Transcripts/Diff).
-- `task-runner/retry.ts` (model fallback retry loop).
-- `task-runner/index.ts` exports `runTeamTask`.
-
-**Acceptance**: Mỗi module ≤300 dòng. Public function signature không đổi.
-
-**Tests**: existing pass + snapshot prompt cho mỗi role (4 role).
-
-**Verification**: `npm run test:integration -- task-runner`
-
----
-
-### Task #73 — Consolidate `child-pi` + `async-runner` + `subagent-manager` thành `src/subagents/`
-
-**Lý do**: Refactor map (đã ghi nhận từ Phase 0): "Consolidate subagent runtime into `src/subagents/*` or equivalent durable-first module." Hiện 3 file rải rác:
-- `src/runtime/child-pi.ts` (435 dòng) — spawn pi CLI con
-- `src/runtime/async-runner.ts` (~50 dòng) — entrypoint background
-- `src/runtime/subagent-manager.ts` (~290 dòng) — Agent tool backend
-
-**Đích**: tạo folder `src/subagents/` chứa:
-- `src/subagents/spawn.ts` (lift từ child-pi.ts)
-- `src/subagents/observer.ts` (ChildPiLineObserver + compactor)
-- `src/subagents/manager.ts` (lift từ subagent-manager.ts)
-- `src/subagents/async-entry.ts` (lift từ async-runner.ts)
-- `src/subagents/index.ts` re-export public API
-
-Để các file `runtime/child-pi.ts` thành thin re-export (deprecated path) cho 1–2 release rồi xóa.
-
-**Acceptance**:
-- Import paths cũ vẫn hoạt động (re-export shim).
-- Không thay đổi logic; chỉ move + group.
-- Tests cũ pass.
-
-**Tests**: existing.
-
-**Verification**: `npm run ci`
-
-**Risk/Rollback**: Nhiều file đổi import. Mitigate: làm bằng IDE rename/move chứ không edit thủ công. Rollback: revert.
-
----
-
-### Task #74 — Tách live-session runtime khỏi child-process
-
-**Lý do**: `src/runtime/live-session-runtime.ts` (~14KB) gating sau cờ experimental, nhưng vẫn import từ `task-runner` chính. Nếu mai có người bật `PI_CREW_ENABLE_EXPERIMENTAL_LIVE_SESSION`, code path xen lẫn dễ break.
-
-**Đích**: di chuyển `live-session-runtime.ts` + `live-agent-control/manager` + `live-agent-control-realtime.ts` vào `src/subagents/live/` (subdirectory mới của T73).
-
-**Acceptance**: `runtime/runtime-resolver.ts` chỉ phụ thuộc qua `subagents/live`. Default flow (child-process) không import live module.
-
-**Tests**: existing.
-
----
-
-### Task #75 — Subagent depth/permission hardening
-
-**Lý do**: `pi-args.checkCrewDepth` đã check `PI_CREW_DEPTH` env. Cần test thêm: subagent gọi recursive (Agent tool trong agent) > maxDepth → block + clear message.
-
-**Đích**: `src/subagents/manager.ts`, `src/runtime/pi-args.ts`
-
-**Steps**:
-1. Add explicit test cho recursive spawn.
-2. Bổ sung `role-permission.ts` để chặn agent có role `read_only` không được gọi tool `Agent`/`crew_agent`.
-
-**Tests**: `test/unit/subagent-depth.test.ts`, `test/unit/role-permission.spawn.test.ts`.
-
-**Verification**: `npm run test:unit`
-
----
-
-## Tier 3 — Polish (P3)
-
-### Task #76 — Skills builtin: extract từ `Source/awesome-agent-skills` + adapt
-
-**Lý do**: `pi.skills` trong package.json khai báo `./skills` nhưng folder chỉ có `.gitkeep`. Có thể adapt 5–10 skill cốt lõi từ `Source/awesome-agent-skills/README.md`, `Source/oh-my-claudecode/skills/`, `Source/superpowers/`.
-
-**Đích**: `skills/`
-
-**Steps**:
-1. Chọn 5 skill phù hợp coding:
-   - `safe-bash` (gate dangerous commands)
-   - `verify-evidence` (final assistant must include changed files + verification)
-   - `git-master` (commit hygiene + Conventional Commits)
-   - `read-only-explorer` (forbid edits when role is explorer/analyst)
-   - `task-packet` (enforce scope/inputs/outputs section)
-2. Mỗi skill là file `.md` trong `skills/{name}/SKILL.md` + optional helper scripts.
-3. Adapt mà không copy nguyên văn (giữ MIT compliance + ghi nguồn trong NOTICE.md).
-4. Reference từ `agents/*.md` qua `skills: safe-bash, verify-evidence` frontmatter.
-
-**Acceptance**:
-- 5 skill files ≤500 dòng mỗi file.
-- NOTICE.md cập nhật source attribution.
-- Test discovery: `discover-skills.ts` (có chưa? — bổ sung nếu chưa có) trả về 5.
-
-**Tests**: `test/unit/skills.discovery.test.ts`.
-
-**Verification**: `npm run test:unit -- skills.discovery`
-
-**Risk/Rollback**: Có thể inflate package size. Mitigate: skills nhỏ ≤4KB mỗi cái.
-
----
-
-### Task #77 — `docs/architecture.md` self-contained
-
-**Lý do**: `pi-teams/docs/architecture.md` hiện trỏ ra `../docs/pi-crew-source-review-and-lessons.md`, `../docs/pi-crew-architecture.md`, `../docs/pi-crew-mvp-plan.md` — các file nằm ngoài package, sẽ broken khi npm publish.
-
-**Đích**: `pi-teams/docs/architecture.md`
-
-**Steps**:
-1. Inline nội dung kiến trúc cốt lõi (3 layer: extension/runtime/state, lifecycle diagram, durable run state, autonomous routing).
-2. Bỏ reference ra file workspace bên ngoài.
-3. Thêm sequence diagram ASCII cho run flow (extension → team-runner → task-runner → child-pi → state).
-4. Liên kết tới `usage.md`, `resource-formats.md`, `live-mailbox-runtime.md`, `publishing.md` (đều trong package).
-
-**Acceptance**:
-- File ≤600 dòng, không link out-of-package.
-- `npm pack --dry-run` ship đầy đủ docs/.
-
-**Verification**: manual review + `npm pack --dry-run`.
-
----
-
-### Task #78 — `docs/runtime-flow.md` (mới) + sequence diagram
-
-**Lý do**: Onboarding contributor cần một biểu đồ/text mô tả full flow. Hiện rải rác giữa architecture.md, source-runtime-refactor-map.md, refactor-tasks.md.
-
-**Đích**: tạo mới `pi-teams/docs/runtime-flow.md`
-
-**Steps**:
-1. ASCII sequence diagram: user → handleTeamTool(run) → executeTeamRun → resolveBatchConcurrency → runTeamTask → runChildPi → child stdout → ChildPiLineObserver → onJsonEvent → updateRunStatus → notify.
-2. Bảng "trigger → handler" cho mỗi action (`run`, `resume`, `cancel`, ...).
-3. Liệt kê env var ảnh hưởng (`PI_TEAMS_*`, `PI_CREW_*`, `PI_CODING_AGENT_DIR`).
-
-**Acceptance**: Document ≤400 dòng, tự đứng được không cần đọc thêm.
-
----
-
-## Tier 4 — Tests, smoke, release (P0 cuối phase)
-
-### Task #79 — Integration smoke: Windows process visibility + multi-shard fanout
-
-**Lý do**: Refactor map: "Add real integration smoke scripts for Windows process visibility, async restart recovery, and multi-shard fanout." Test report user vừa gửi đã chứng minh fanout chạy được, nhưng cần script lặp lại được.
-
-**Đích**: `test/integration/`
-
-**Steps**:
-1. `test/integration/windows-no-blank-console.test.ts`: spawn `pi --version` qua `pi-spawn.getPiSpawnCommand` với `windowsHide:true` → assert process spawned, no console window (heuristic: `child.spawnargs` không chứa `cmd /c start`).
-2. `test/integration/multi-shard-fanout.test.ts`: dùng `expandParallelResearchWorkflow` với fixture `Source/pi-*` mock (5 thư mục dummy) → assert 4 shard sinh ra, mỗi shard có ≥1 path, dependency synthesize đúng tất cả shard.
-3. `test/integration/async-restart-recovery.test.ts`: spawn background, kill -9, gọi `team status` → mark failed trong ≤30s (T65 dependency).
-
-**Acceptance**: 3 test pass trên Windows runner CI.
-
-**Verification**: `npm run test:integration`
-
----
-
-### Task #80 — Update `npm pack --dry-run` snapshot + `schema.json`
-
-**Lý do**: Sau khi thêm config field (T63 `allowUnboundedConcurrency`), `schema.json` exported và `config-schema.ts` cần đồng bộ.
-
-**Đích**: `schema.json`, `src/schema/config-schema.ts`
-
-**Steps**:
-1. Regenerate `schema.json` từ TypeBox schema (script `scripts/generate-schema.ts` nếu có; nếu không thì update manually + diff review).
-2. `npm pack --dry-run` capture file list, snapshot vào test (`test/unit/package-files.test.ts`).
-
-**Acceptance**: schema.json reflect mọi field config; snapshot test verify không drop file ship.
-
----
-
-### Task #81 — CHANGELOG + release prep
-
-**Lý do**: Theo AGENTS.md global Section 2, mỗi PR cần Files & Rationale + Tests + Risks/Rollback. Phase 6 sẽ ship qua nhiều mini-release.
-
-**Đích**: `CHANGELOG.md`
-
-**Steps**:
-1. Thêm sections theo nhóm Tier:
-   - `## 0.1.30 — async/concurrency hardening` (T60–T63, T79).
-   - `## 0.1.31 — resume durability + adaptive repair` (T64–T67).
-   - `## 0.1.32 — model routing observability` (T68–T69).
-   - `## 0.2.0 — refactor: subagent runtime + register split` (T70–T75) — minor bump vì internal API thay đổi.
-   - `## 0.2.1 — skills + docs` (T76–T78).
-2. Mỗi entry follow format: `### Added / Changed / Fixed / Breaking Changes`.
-
-**Acceptance**: CHANGELOG đầy đủ; `npm version` script chạy clean.
-
----
-
-## Phụ lục A — Acceptance gate cho mỗi mini-release
-
-Trước khi tag/publish:
-
-```bash
-# Hard gate
-npm run typecheck
-npm run test:unit
-npm run test:integration
-npm pack --dry-run
-
-# Soft gate (manual)
-/team-doctor    # in Pi smoke session
-/team-validate
-/team-autonomy status
-
-# Cross-platform
-# Trigger CI ubuntu/windows/macos workflow trước khi tag
-```
-
-## Phụ lục B — Bảng phụ thuộc giữa task
-
-```
-T60 ──► T61 ──► T62
-                ▲
-T63 (độc lập) ──┘
-T64 ──► T65 ──► T66
-T67 (độc lập)
-T68 ──► T69
-T70 ──► T71 ──► T72
-T73 ──► T74 ──► T75 (cần T70 ổn định trước)
-T76 (độc lập)
-T77 ──► T78
-T79 phụ thuộc T63 (concurrency cap), T65 (async-died)
-T80 phụ thuộc T63
-T81 sau cùng
-```
-
-## Phụ lục C — Ánh xạ mỗi task ↔ rủi ro/follow-up đã nêu
-
-| Task | Nguồn yêu cầu |
-|---|---|
-| T60–T62 | Test report risk #2 + Phase analysis "fail-fast nếu jiti fail" |
-| T63 | Test report risk #4 |
-| T64–T66 | Test report risk #5 + refactor map "async restart recovery" |
-| T67 | refactor-map "adaptive planner repair/retry" |
-| T68–T69 | refactor-map "model routing transparency persisted" |
-| T70–T72 | AGENTS.md "small modules" + analysis "register.ts/team-tool.ts/task-runner.ts cồng kềnh" |
-| T73–T75 | refactor-map "consolidate subagent runtime into src/subagents/*" |
-| T76 | analysis "skills/ trống" |
-| T77–T78 | analysis "doc kiến trúc trỏ ra ngoài package" + onboarding |
-| T79 | refactor-map "real integration smoke scripts" |
-| T80–T81 | release hygiene |
-
-## Phụ lục D — "Reply with" template cho mỗi PR
-
-Mỗi PR Phase 6 phải tuân thủ AGENTS.md Section 10:
-
-```
-Summary: <1 dòng impact>
-Plan:
-- <bước 1>
-- <bước 2>
-
-Files & Rationale:
-- src/.../...: <lý do>
-
-Tests:
-- <test name>: <kịch bản>
-
-Verification:
-- npx tsc --noEmit → Passed
-- npm run test:unit → 0 failed / N passed
-- npm run test:integration → 0 failed / N passed
-- npm pack --dry-run → file list match snapshot
-
-Risks & Rollback:
-- <rủi ro>
-- <feature flag / revert plan>
-
-Security & Perf Notes:
-- <OWASP / RAM / IO>
-```
-
----
-
-**Khuyến nghị triển khai**:
-1. Đi theo thứ tự Tier (P0 → P3); không pha trộn refactor lớn (T70–T75) với hardening (T60–T67).
-2. Mỗi Tier ship 1 mini-release để có baseline ổn định trước Tier kế.
-3. Trước Tier 3 (T70–T75) chạy full test trên CI Windows + macOS để bắt regression cross-platform.
-4. Sau mỗi task: chạy `/team-doctor` trong Pi session để smoke; mở dashboard `/team-dashboard` xác nhận không stale.