Add 5 pi extensions: pi-subagents, pi-crew, rpiv-pi, pi-interactive-shell, pi-intercom

extensions/pi-crew/docs/refactor-tasks-phase6.md

@@ -0,0 +1,662 @@
+# 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.