pi-crew 0.2.3 → 0.2.5

package/docs/runtime-flow.md

@@ -1,148 +1,148 @@
-# pi-crew Runtime Flow
-
-This document is a compact map of the runtime paths used by `pi-crew`.
-
-## Main sequence
-
-```text
-User / model
-  │ calls team({ action: "run", ... }) or /team-run
-  ▼
-handleTeamTool()
-  │ validates schema and routes action
-  ▼
-handleRun()
-  ├─ discoverTeams/discoverWorkflows/discoverAgents
-  ├─ validateWorkflowForTeam
-  ├─ expandParallelResearchWorkflow when applicable
-  ├─ createRunManifest + tasks.json + goal artifact
-  ├─ if async=true ─────────────────────────────────────────────┐
-  │   spawnBackgroundTeamRun()                                  │
-  │     ├─ resolve jiti-register.mjs                            │
-  │     ├─ fail-fast if jiti missing                            │
-  │     ├─ node --import jiti-register.mjs background-runner.ts  │
-  │     └─ parent schedules early-exit guard                    │
-  │                                                            ▼
-  │   background-runner.ts
-  │     ├─ append async.started
-  │     ├─ write async.pid startup marker
-  │     ├─ rediscover team/workflow/agents
-  │     └─ executeTeamRun()
-  │
-  └─ if foreground/default
-      ├─ startForegroundRun schedules session-bound run, or
-      └─ executeTeamRun inline for scaffold/non-scheduled paths
-
-executeTeamRun()
-  ├─ write run.running
-  ├─ materialize queued/running agent records lazily
-  ├─ build task graph index
-  ├─ while queued tasks exist
-  │   ├─ taskGraphSnapshot
-  │   ├─ resolveBatchConcurrency
-  │   ├─ getReadyTasks
-  │   ├─ append task.progress batch event
-  │   ├─ mapConcurrent ready batch
-  │   │   └─ runTeamTask()
-  │   │       ├─ prepare workspace/worktree
-  │   │       ├─ build task packet
-  │   │       ├─ render prompt + dependency context
-  │   │       ├─ choose model candidates from Pi config
-  │   │       ├─ spawn child Pi process
-  │   │       ├─ ChildPiLineObserver parses stdout/stderr
-  │   │       ├─ append per-agent events/output
-  │   │       ├─ update agent progress/task state
-  │   │       ├─ parse final JSONL/session usage
-  │   │       └─ write result/log/transcript/metadata artifacts
-  │   ├─ merge task updates monotonically
-  │   ├─ optional adaptive plan injection
-  │   ├─ save tasks/agents/progress
-  │   └─ write batch artifact
-  ├─ policy closeout
-  └─ run.completed / run.failed / run.blocked / run.cancelled
-```
-
-## Action router
-
-| Action | Handler | Purpose |
-|---|---|---|
-| `run` | `team-tool/run.ts` | Create and execute a run, foreground or async. |
-| `status` | `team-tool.ts` | Show manifest/tasks/agents/events and mark stale async runs failed. |
-| `summary` | `session-summary.ts`/summary handler | Write/read run summary artifact. |
-| `events` | `team-tool.ts` | Tail durable run events. |
-| `artifacts` | `team-tool.ts` | List run artifacts. |
-| `resume` | `team-tool.ts` | Requeue failed/cancelled/skipped/running tasks. |
-| `cancel` | `team-tool.ts` | Mark queued/running tasks cancelled and request foreground interrupt. |
-| `forget` | `run-maintenance.ts` | Delete run state/artifacts with confirmation. |
-| `prune` | `run-maintenance.ts` | Remove old finished runs with confirmation. |
-| `export` | `run-export.ts` | Create portable run bundle. |
-| `import` / `imports` | `run-import.ts` / `import-index.ts` | Store/list imported bundles. |
-| `config` | `config.ts` + config action | Show/update user/project config. |
-| `doctor` | `team-tool/doctor.ts` | Platform/resource/runtime diagnostics. |
-| `validate` | `validate-resources.ts` | Validate agents/teams/workflows. |
-| `recommend` | `team-recommendation.ts` | Suggest team/workflow/action for a goal. |
-| management | `management.ts` | Create/update/delete/rename teams, agents, workflows. |
-| API | `team-tool/api.ts` | File-backed observability/control/mailbox API. |
-
-## Worker modes
-
-| Mode | Behavior |
-|---|---|
-| `child-process` | Default. Launches real child `pi` processes per task. |
-| `scaffold` | Explicit dry-run. No child Pi worker execution. |
-| `live-session` | Experimental/gated in-process/live agent path. |
-| `auto` | Resolves to child-process unless config/env requests otherwise. |
-
-## Important files
-
-```text
-src/extension/register.ts              Pi extension entry/wiring
-src/extension/team-tool/run.ts         run creation and foreground/async split
-src/runtime/background-runner.ts       detached async entrypoint
-src/runtime/async-runner.ts            background spawn command/options
-src/runtime/team-runner.ts             workflow/task graph scheduler
-src/runtime/task-runner.ts             single task execution
-src/runtime/child-pi.ts                child Pi process and output observer
-src/runtime/model-fallback.ts          configured model candidates/routing
-src/runtime/concurrency.ts             batch concurrency decisions
-src/runtime/process-status.ts          pid/liveness/stale detection
-src/state/state-store.ts               manifest/tasks persistence
-src/state/event-log.ts                 JSONL run events
-src/runtime/crew-agent-records.ts      aggregate + per-agent status files
-```
-
-## Environment variables
-
-| Env | Effect |
-|---|---|
-| `PI_CREW_EXECUTE_WORKERS=0` | Disable real workers, use scaffold behavior. |
-| `PI_TEAMS_EXECUTE_WORKERS=0` | Legacy alias for worker disable. |
-| `PI_CREW_ENABLE_EXPERIMENTAL_LIVE_SESSION=1` | Allow experimental live-session runtime. |
-| `PI_CREW_MOCK_LIVE_SESSION=success` | Test hook for live-session mock. |
-| `PI_TEAMS_MOCK_CHILD_PI` | Test hook for mocked child Pi execution. |
-| `PI_CREW_DEPTH`, `PI_CREW_MAX_DEPTH` | Canonical subagent recursion guard. |
-| `PI_TEAMS_DEPTH`, `PI_TEAMS_MAX_DEPTH` | Legacy recursion guard aliases. |
-| `PI_TEAMS_HOME` | Override user config/state home in tests. |
-| `PI_TEAMS_PI_BIN` | Override child `pi` executable. |
-| `PI_CODING_AGENT_DIR` | Override Pi settings/models directory for model discovery. |
-| `PI_CREW_ASYNC_EARLY_EXIT_GUARD=0` | Disable 3s background early-exit guard. |
-
-## State transition summary
-
-```text
-queued/planning/running  ── completed
-                         ├─ failed
-                         ├─ blocked
-                         └─ cancelled
-```
-
-Task states follow the same durable contract plus `skipped`. Terminal states are monotonic during parallel merge.
-
-## Observability tips
-
-- Use `/team-dashboard` for a UI overview.
-- Use `team status runId=...` for canonical state and stale async detection.
-- Read `background.log` for early import/spawn errors.
-- Read `events.jsonl` for event chronology.
-- Read `agents/{taskId}/status.json` for per-agent model/progress/tool status.
-- Read `artifacts/{runId}/transcripts/{taskId}.jsonl` for raw child Pi transcript.
+# pi-crew Runtime Flow
+
+This document is a compact map of the runtime paths used by `pi-crew`.
+
+## Main sequence
+
+```text
+User / model
+  │ calls team({ action: "run", ... }) or /team-run
+  ▼
+handleTeamTool()
+  │ validates schema and routes action
+  ▼
+handleRun()
+  ├─ discoverTeams/discoverWorkflows/discoverAgents
+  ├─ validateWorkflowForTeam
+  ├─ expandParallelResearchWorkflow when applicable
+  ├─ createRunManifest + tasks.json + goal artifact
+  ├─ if async=true ─────────────────────────────────────────────┐
+  │   spawnBackgroundTeamRun()                                  │
+  │     ├─ resolve jiti-register.mjs                            │
+  │     ├─ fail-fast if jiti missing                            │
+  │     ├─ node --import jiti-register.mjs background-runner.ts  │
+  │     └─ parent schedules early-exit guard                    │
+  │                                                            ▼
+  │   background-runner.ts
+  │     ├─ append async.started
+  │     ├─ write async.pid startup marker
+  │     ├─ rediscover team/workflow/agents
+  │     └─ executeTeamRun()
+  │
+  └─ if foreground/default
+      ├─ startForegroundRun schedules session-bound run, or
+      └─ executeTeamRun inline for scaffold/non-scheduled paths
+
+executeTeamRun()
+  ├─ write run.running
+  ├─ materialize queued/running agent records lazily
+  ├─ build task graph index
+  ├─ while queued tasks exist
+  │   ├─ taskGraphSnapshot
+  │   ├─ resolveBatchConcurrency
+  │   ├─ getReadyTasks
+  │   ├─ append task.progress batch event
+  │   ├─ mapConcurrent ready batch
+  │   │   └─ runTeamTask()
+  │   │       ├─ prepare workspace/worktree
+  │   │       ├─ build task packet
+  │   │       ├─ render prompt + dependency context
+  │   │       ├─ choose model candidates from Pi config
+  │   │       ├─ spawn child Pi process
+  │   │       ├─ ChildPiLineObserver parses stdout/stderr
+  │   │       ├─ append per-agent events/output
+  │   │       ├─ update agent progress/task state
+  │   │       ├─ parse final JSONL/session usage
+  │   │       └─ write result/log/transcript/metadata artifacts
+  │   ├─ merge task updates monotonically
+  │   ├─ optional adaptive plan injection
+  │   ├─ save tasks/agents/progress
+  │   └─ write batch artifact
+  ├─ policy closeout
+  └─ run.completed / run.failed / run.blocked / run.cancelled
+```
+
+## Action router
+
+| Action | Handler | Purpose |
+|---|---|---|
+| `run` | `team-tool/run.ts` | Create and execute a run, foreground or async. |
+| `status` | `team-tool.ts` | Show manifest/tasks/agents/events and mark stale async runs failed. |
+| `summary` | `session-summary.ts`/summary handler | Write/read run summary artifact. |
+| `events` | `team-tool.ts` | Tail durable run events. |
+| `artifacts` | `team-tool.ts` | List run artifacts. |
+| `resume` | `team-tool.ts` | Requeue failed/cancelled/skipped/running tasks. |
+| `cancel` | `team-tool.ts` | Mark queued/running tasks cancelled and request foreground interrupt. |
+| `forget` | `run-maintenance.ts` | Delete run state/artifacts with confirmation. |
+| `prune` | `run-maintenance.ts` | Remove old finished runs with confirmation. |
+| `export` | `run-export.ts` | Create portable run bundle. |
+| `import` / `imports` | `run-import.ts` / `import-index.ts` | Store/list imported bundles. |
+| `config` | `config.ts` + config action | Show/update user/project config. |
+| `doctor` | `team-tool/doctor.ts` | Platform/resource/runtime diagnostics. |
+| `validate` | `validate-resources.ts` | Validate agents/teams/workflows. |
+| `recommend` | `team-recommendation.ts` | Suggest team/workflow/action for a goal. |
+| management | `management.ts` | Create/update/delete/rename teams, agents, workflows. |
+| API | `team-tool/api.ts` | File-backed observability/control/mailbox API. |
+
+## Worker modes
+
+| Mode | Behavior |
+|---|---|
+| `child-process` | Default. Launches real child `pi` processes per task. |
+| `scaffold` | Explicit dry-run. No child Pi worker execution. |
+| `live-session` | Experimental/gated in-process/live agent path. |
+| `auto` | Resolves to child-process unless config/env requests otherwise. |
+
+## Important files
+
+```text
+src/extension/register.ts              Pi extension entry/wiring
+src/extension/team-tool/run.ts         run creation and foreground/async split
+src/runtime/background-runner.ts       detached async entrypoint
+src/runtime/async-runner.ts            background spawn command/options
+src/runtime/team-runner.ts             workflow/task graph scheduler
+src/runtime/task-runner.ts             single task execution
+src/runtime/child-pi.ts                child Pi process and output observer
+src/runtime/model-fallback.ts          configured model candidates/routing
+src/runtime/concurrency.ts             batch concurrency decisions
+src/runtime/process-status.ts          pid/liveness/stale detection
+src/state/state-store.ts               manifest/tasks persistence
+src/state/event-log.ts                 JSONL run events
+src/runtime/crew-agent-records.ts      aggregate + per-agent status files
+```
+
+## Environment variables
+
+| Env | Effect |
+|---|---|
+| `PI_CREW_EXECUTE_WORKERS=0` | Disable real workers, use scaffold behavior. |
+| `PI_TEAMS_EXECUTE_WORKERS=0` | Legacy alias for worker disable. |
+| `PI_CREW_ENABLE_EXPERIMENTAL_LIVE_SESSION=1` | Allow experimental live-session runtime. |
+| `PI_CREW_MOCK_LIVE_SESSION=success` | Test hook for live-session mock. |
+| `PI_TEAMS_MOCK_CHILD_PI` | Test hook for mocked child Pi execution. |
+| `PI_CREW_DEPTH`, `PI_CREW_MAX_DEPTH` | Canonical subagent recursion guard. |
+| `PI_TEAMS_DEPTH`, `PI_TEAMS_MAX_DEPTH` | Legacy recursion guard aliases. |
+| `PI_TEAMS_HOME` | Override user config/state home in tests. |
+| `PI_TEAMS_PI_BIN` | Override child `pi` executable. |
+| `PI_CODING_AGENT_DIR` | Override Pi settings/models directory for model discovery. |
+| `PI_CREW_ASYNC_EARLY_EXIT_GUARD=0` | Disable 3s background early-exit guard. |
+
+## State transition summary
+
+```text
+queued/planning/running  ── completed
+                         ├─ failed
+                         ├─ blocked
+                         └─ cancelled
+```
+
+Task states follow the same durable contract plus `skipped`. Terminal states are monotonic during parallel merge.
+
+## Observability tips
+
+- Use `/team-dashboard` for a UI overview.
+- Use `team status runId=...` for canonical state and stale async detection.
+- Read `background.log` for early import/spawn errors.
+- Read `events.jsonl` for event chronology.
+- Read `agents/{taskId}/status.json` for per-agent model/progress/tool status.
+- Read `artifacts/{runId}/transcripts/{taskId}.jsonl` for raw child Pi transcript.

package/docs/runtime-migration-in-process-analysis.md

@@ -0,0 +1,250 @@
+# Phân tích: Chuyển pi-crew hoàn toàn sang in-process execution
+
+> Ngày: 2026-05-12  
+> Câu hỏi: Nếu chuyển hẳn sang in-process giống pi-subagents3 thì sao?
+
+---
+
+## 1. Hiện trạng
+
+pi-crew có **3 runtime modes**, child-process là default:
+
+```
+scaffold      → không chạy workers (dry-run)
+child-process → spawn `pi` CLI subprocess per worker (DEFAULT)
+live-session  → createAgentSession() in-process per worker
+```
+
+### Code liên quan child-process
+
+| File | LOC | Vai trò |
+|---|---|---|
+| `child-pi.ts` | 461 | Subprocess lifecycle, stdout parsing, kill process tree |
+| `pi-args.ts` | 165 | Build CLI args cho child `pi` process |
+| `pi-spawn.ts` | 167 | Detect `pi` binary path (local/global) |
+| `post-exit-stdio-guard.ts` | 86 | Drain child stdout sau exit, hard kill timer |
+| `async-runner.ts` | 153 | Spawn background team runs ( detached process) |
+| **Tổng** | **1.032** | **Code chỉ dùng cho child-process** |
+
+### Code liên quan live-session (đã có sẵn)
+
+| File | LOC | Vai trò |
+|---|---|---|
+| `live-session-runtime.ts` | 600 | In-process execution, soft turn limit, yield, custom tools |
+| `runtime-resolver.ts` | 92 | Auto-detect available runtime |
+| `task-runner/live-executor.ts` | 95 | Adapter: live-session → task-runner interface |
+
+### Files sử dụng child-process path
+
+- `task-runner.ts` — 8 references, ~120 dòng logic riêng child-process (heartbeat, progress, model retry)
+- `register.ts` — `terminateActiveChildPiProcesses()` cleanup
+- `doctor.ts` — diagnose child-process issues
+- `async-runner.ts` — spawn background team runs
+
+### Tests liên quan
+
+- ~37 test files reference child-process / mock child
+- ~3 test files reference live-session mock
+- Tất cả integration tests dùng `PI_TEAMS_MOCK_CHILD_PI` — **cần rewrite** nếu bỏ child-process
+
+---
+
+## 2. Nếu chuyển hẳn sang in-process
+
+### 2.1 Những gì ĐƯỢC
+
+#### Lợi tức tức thì
+
+| Metric | child-process | in-process | Cải thiện |
+|---|---|---|---|
+| Memory / worker | ~150 MB | ~15 MB | **10× nhẹ hơn** |
+| 4 workers peak | ~600 MB thêm | ~60 MB thêm | **540 MB tiết kiệm** |
+| Startup / worker | 2-4s | 200-500ms | **8× nhanh hơn** |
+| Team startup (3 phases) | 6-12s overhead | ~1s overhead | **6-12× nhanh hơn** |
+| Steering | ❌ | ✅ | **Tính năng mới** |
+| Resume | ❌ | ✅ | **Tính năng mới** |
+| Context inheritance | ❌ | ✅ (parentContext) | **Tính năng mới** |
+| Live tool activity | ❌ | ✅ | **Tính năng mới** |
+| Yield/submit_result | ✅ (JSON event) | ✅ (custom tool) | Parity |
+| Worktree isolation | ✅ | ✅ | Parity |
+
+#### Lợi tức kiến trúc
+
+- **Xóa ~1.000 LOC** subprocess management code
+- Đơn giản hóa `task-runner.ts` (bỏ 120 dòng child-process logic)
+- Bỏ `post-exit-stdio-guard.ts`, `pi-spawn.ts`, `pi-args.ts` subprocess overhead
+- Bỏ `responseTimeoutMs`, `hardKillMs`, `postExitStdioGuardMs` — không cần kill process tree
+- **Zero npm dependencies cho execution** (hiện cần `jiti` cho async-runner TypeScript loading)
+
+### 2.2 Những gì MẤT
+
+#### ❌ Process isolation — biggest loss
+
+```
+child-process:  worker crash → worker dies → parent continues
+in-process:     worker crash → có thể crash parent → toàn bộ team mất
+```
+
+Pi SDK `createAgentSession()` đã handle phần lớn errors, nhưng:
+- **Unhandled promise rejection** trong session
+- **Infinite loop** trong custom tool
+- **OOM** — một session ăn hết memory ảnh hưởng tất cả
+- **Node.js segfault** — rare nhưng khi xảy ra = chết hết
+
+#### ❌ Async background team runs
+
+`async-runner.ts` spawn một **detached process** chạy team khi user close terminal. In-process không thể — process chết khi terminal close.
+
+**Giải pháp:** Giữ `async-runner.ts` riêng cho background runs — nó spawn cả team runner, không phải individual workers.
+
+#### ❌ Depth guard đơn giản
+
+`checkCrewDepth()` đếm `PI_CREW_PARENT_PID` env var. In-process không có process boundary → đếm depth khó hơn. Cần dùng global counter hoặc thread-local.
+
+#### ❌ 37+ test files cần update
+
+Tất cả integration tests dùng `PI_TEAMS_MOCK_CHILD_PI`. Cần chuyển sang `PI_CREW_MOCK_LIVE_SESSION` hoặc viết mock mới.
+
+#### ❌ `_CrewRuntimeKind` type union
+
+`"scaffold" | "child-process" | "live-session"` → nếu bỏ child-process thì chỉ còn `"scaffold" | "in-process"`. Breaking change cho config.
+
+### 2.3 Rủi ro cụ thể
+
+| Rủi ro | Mức độ | Chi tiết |
+|---|---|---|
+| Parent crash | **Medium** | Unhandled error in agent session → parent dies. Pi SDK wraps大部分 nhưng không phải 100%. |
+| Memory pressure | **Medium** | 4 in-process sessions + context windows có thể chiếm >500MB trong cùng heap. V8 GC pause. |
+| Extension conflicts | **Low** | In-process extensions có thể conflict (global state, tool registry). Đã có filter nhưng edge cases. |
+| Recursive team calls | **Low** | `team` tool trong agent session → infinite recursion. Đã filter nhưng cần guarantee. |
+| Background runs | **Solved** | Giữ `async-runner.ts` riêng, chỉ spawn 1 detached process cho full team. |
+| Breaking config | **Low** | User đang set `mode: "child-process"` → cần migration path. |
+
+---
+
+## 3. Hai hướng đi
+
+### Hướng A: Bỏ hoàn toàn child-process (giống pi-subagents3)
+
+```
+                 ┌─────────────────────────┐
+                 │   task-runner.ts         │
+                 │   runtime = "in-process" │
+                 ├─────────────────────────┤
+                 │ live-session-runtime.ts  │
+                 │ createAgentSession()     │
+                 │ session.prompt()         │
+                 │ session.steer()          │
+                 ├─────────────────────────┤
+                 │    Pi SDK (shared)       │
+                 └─────────────────────────┘
+```
+
+**Xóa:** `child-pi.ts`, `pi-args.ts`, `pi-spawn.ts`, `post-exit-stdio-guard.ts` (~879 LOC)  
+**Giữ:** `async-runner.ts` (cho background team runs — spawn 1 process cho cả team, không phải per-worker)  
+**Đổi:** `task-runner.ts` → bỏ child-process branch, chỉ dùng live-session  
+**Đổi:** Tất cả 37+ test files  
+
+**Pros:** Clean architecture, đơn giản nhất, maintenance thấp nhất  
+**Cons:** Mất crash isolation cho per-worker, nhiều test cần rewrite
+
+### Hướng B: Live-session default + child-process opt-in (khuyến nghị)
+
+```
+                 ┌─────────────────────────────────┐
+                 │        task-runner.ts            │
+                 │   default: live-session          │
+                 │   opt-in: child-process          │
+                 │   background: async-runner       │
+                 ├──────────┬───────────────────────┤
+                 │ in-proc  │  child-process         │
+                 │ (fast)   │  (isolated, fallback)  │
+                 └──────────┴───────────────────────┘
+```
+
+**Đổi:** `runtime-resolver.ts` → `"auto"` prefer live-session  
+**Giữ:** Tất cả child-process code (fallback)  
+**Giữ:** Tất cả tests  
+**Thêm:** Config `"riskyIsolation": true"` cho executor role auto-use child-process  
+
+**Pros:** Best of both worlds, zero breaking change  
+**Cons:** Vẫn maintain 2 code paths
+
+---
+
+## 4. Khuyến nghị: Hướng B
+
+**Không nên bỏ child-process hoàn toàn** — quá rủi ro cho production. Thay vào đó:
+
+### Bước 1: Đổi default runtime (nhanh, ít rủi ro)
+
+```typescript
+// runtime-resolver.ts
+// Trước: "auto" → luôn child-process
+// Sau:   "auto" → thử live-session, fallback child-process
+
+export async function resolveCrewRuntime(config, env) {
+    const requestedMode = config.runtime?.mode ?? "auto";
+    if (requestedMode === "auto") {
+        const live = await isLiveSessionRuntimeAvailable(1500, env);
+        if (live.available) return liveCaps(requestedMode);
+        return { ...childCaps(requestedMode), fallback: "child-process", reason: live.reason };
+    }
+    // Explicit modes still work
+    if (requestedMode === "child-process") return childCaps(requestedMode);
+    if (requestedMode === "live-session") { /* ... */ }
+    // ...
+}
+```
+
+### Bước 2: Thêm per-role isolation policy
+
+```json
+// crew-config.json
+{
+  "runtime": {
+    "mode": "auto",
+    "isolationPolicy": {
+      "executor": "child-process",   // risky code changes → isolated
+      "test-engineer": "child-process", // test runs → isolated
+      "default": "in-process"         // everything else → fast
+    }
+  }
+}
+```
+
+### Bước 3: Observability cho in-process errors
+
+```typescript
+// Wrap session.prompt() với global error handler
+process.on('unhandledRejection', (err) => {
+    logInternalError('live-session.unhandled', err);
+    // Don't crash — attempt recovery
+});
+```
+
+### Lợi tức dự kiến Hướng B
+
+| | Hiện tại | Sau Bước 1 | Sau Bước 2 |
+|---|---|---|---|
+| **Default runtime** | child-process | live-session (auto) | live-session + per-role |
+| **Memory (4 workers)** | ~910 MB | ~370 MB | ~450 MB (mix) |
+| **Startup** | 2-4s/worker | 200-500ms/worker | Mix |
+| **Crash isolation** | ✅ all | ✅ fallback | ✅ risky roles |
+| **Steering** | ❌ | ✅ | ✅ |
+| **Breaking changes** | — | None | None |
+| **Code xóa** | — | 0 | 0 (giữ fallback) |
+| **Tests cần đổi** | — | 0 | 0 |
+
+---
+
+## 5. Kết luận
+
+**Không nên chuyển hẳn 100% in-process.** Lý do:
+
+1. **Crash isolation quá quan trọng** cho executor/test-engineer roles — những agent này chạy code, write files, có thể infinite loop
+2. **Background runs cần detached process** — không thể in-process
+3. **37+ test files cần rewrite** — chi phí migration cao
+4. **Breaking change** cho users đang dùng `mode: "child-process"`
+
+**Thay vào đó: Đổi default sang live-session + giữ child-process làm fallback/opt-in.** Đây chính là thiết kế sẵn của `resolveCrewRuntime()` — chỉ cần flip default trong `"auto"` mode. Zero code xóa, zero breaking change, users tự chọn khi cần isolation.

package/docs/stories/README.md

@@ -0,0 +1,30 @@
+# Stories
+
+Story-sized work packets for pi-crew development.
+
+## Status Values
+
+| Status | Meaning |
+|--------|---------|
+| planned | Accepted, not started |
+| in_progress | Actively being worked |
+| completed | Done with evidence |
+| blocked | Waiting on external input |
+
+## Active Stories
+
+No active stories. Pick from backlog or create new ones via feature intake.
+
+## Completed Stories (from review rounds)
+
+| ID | Title | Lane | Result |
+|----|-------|------|--------|
+| RR-001 | Depth guard for nested live-session | normal | commit 2640d5e |
+| RR-002 | Windows EBUSY retry | normal | commit ceb8c60 |
+| RR-003 | Harden live-session resource management | normal | commit c7bd455 |
+| RR-004 | Stale task/agent repair | normal | commit d6d466d |
+| RR-005 | Async runner child-process enforcement | high-risk | commit 2486051 |
+| RR-006 | Live-session resource leak fix | normal | commit 7a25644 |
+| RR-007 | Double cleanupTempDir guard | tiny | commit 5f47e92 |
+| RR-008 | Review round 8 (8 issues) | normal | commit 4e75ba8 |
+| RR-009 | Review round 9 (5 issues) | normal | commit f3d29cc |

package/docs/stories/backlog.md

@@ -0,0 +1,36 @@
+# Story Backlog
+
+Candidate stories for future pi-crew development.
+
+## Epic: Reliability
+
+| ID | Title | Lane | Priority | Status |
+|----|-------|------|----------|--------|
+| US-001 | Lock-free event log rotation | normal | P2 | planned |
+| US-002 | Structured run-level lock cleanup | normal | P2 | planned |
+| US-003 | Dead letter queue for permanently failed tasks | normal | P3 | planned |
+
+## Epic: Performance
+
+| ID | Title | Lane | Priority | Status |
+|----|-------|------|----------|--------|
+| US-010 | Replace sleepSync busy-wait with proper async | normal | P3 | planned |
+| US-011 | Stream-based event log for large runs | normal | P3 | planned |
+| US-012 | Cache available models across runs | tiny | P3 | planned |
+
+## Epic: DX (Developer Experience)
+
+| ID | Title | Lane | Priority | Status |
+|----|-------|------|----------|--------|
+| US-020 | Interactive run dashboard in TUI | normal | P2 | planned |
+| US-021 | Run comparison (before/after) | normal | P3 | planned |
+| US-022 | Export run report as markdown | tiny | P3 | planned |
+
+## Epic: Integration
+
+| ID | Title | Lane | Priority | Status |
+|----|-------|------|----------|--------|
+| US-030 | Webhook notifications on run completion | normal | P3 | planned |
+| US-031 | GitHub Actions integration (report results as PR comment) | normal | P3 | planned |
+
+Create story packets from `docs/templates/story.md` when work is selected.

package/docs/templates/decision.md

@@ -0,0 +1,27 @@
+# NNNN Decision Title
+
+Date: YYYY-MM-DD
+
+## Status
+
+Proposed | Accepted | Superseded | Rejected
+
+## Context
+
+What problem, constraint, or ambiguity forced this decision?
+
+## Decision
+
+What did we decide?
+
+## Alternatives Considered
+
+1. Alternative.
+
+## Consequences
+
+Positive:
+- Item.
+
+Tradeoffs:
+- Item.