pi-crew 0.1.43 → 0.1.44

package/docs/research-phase10-distillation.md

@@ -0,0 +1,199 @@
+# Phase 10: Source Distillation & Development Roadmap
+
+> Synthesized from deep-reads of `pi-mono`, `pi-subagents`, and `pi-crew@melihmucuk` reference fork.
+> Date: 2026-05-04
+
+---
+
+## 1. Source Insights
+
+### 1.1 pi-mono (v0.72.1)
+
+| Insight | Impact on pi-crew |
+|---|---|
+| **Compact read rendering** — AGENTS.md, SKILL.md, Pi docs auto-collapsed in TUI | Our agents' prompts that reference these files still work, but users won't see full content inline. Ensure tool-call descriptions are self-contained. |
+| **Session resource cleanup registry** — Providers register cleanup fns; `dispose()` calls all | Our `child-pi.ts` should register cleanup for child processes. Currently we handle SIGINT/beforeExit — align with Pi's new `registerSessionResourceCleanup()`. |
+| **Codex WebSocket SSE fallback** — Transparent fallback on WS failure | No direct impact, but note: child Pi processes may switch transports mid-session. |
+| **Xiaomi per-region token plan providers** | No impact — provider list is internal to Pi. |
+| **Model catalog generator with overrides** | Our `model-fallback.ts` should track new models as Pi adds them. |
+
+### 1.2 pi-subagents (v0.24.0)
+
+| Insight | Impact on pi-crew |
+|---|---|
+| **Chain directories** — Dedicated `.pi/chains/` and `~/.pi/agent/chains/` | Our workflows are similar but directory-based discovery with `listMarkdownFilesRecursive` is a good pattern. |
+| **Supervisor contact** — Children call `contact_supervisor` | Our mailbox system already serves this purpose, but subagent-initiated communication is one-directional. Consider adding `supervisor_contact` event for child→parent. |
+| **Model thinking levels** — Respect `thinking` from agent frontmatter | We already have `model-fallback.ts` but don't propagate thinking levels to child Pi. |
+| **Session-scoped status** — Filter status by session | Our `run-index.ts` already merges scopes, but individual run status should be session-scoped to avoid cross-contamination. |
+| **Foreground kept alive during intercom** | Our `completion-guard.ts` handles some of this, but the pattern of pausing parent while child waits for supervisor is worth aligning. |
+| **File-only outputs** — Some subagents only write to files | Our `task-output-context.ts` already supports file-only output extraction. Validate compatibility. |
+| **Packaged recursive agents** — Agents can spawn sub-agents | Our task-runner already supports this via child Pi, but we should document the recursive depth guard. |
+| **UI simplification** — Removed overlays, consolidated to tool actions | Our dashboard is more advanced but we should ensure TUI simplicity is preserved. |
+
+### 1.3 pi-crew reference fork (melihmucuk v1.0.14)
+
+| Insight | Impact on pi-crew |
+|---|---|
+| **CrewRuntime singleton** — Process-level, survives session replacement | Our `crew-agent-runtime.ts` is similar but not a true singleton. Consider hardening. |
+| **DeliveryCoordinator** — Routes results to owner session, queues when inactive | We lack this pattern. Our result delivery goes through artifacts + notification, but not session-aware routing. |
+| **Ownership model** — `abortOwned()` returns `{ abortedIds, missingIds, foreignIds }` | Our `cancel.ts` returns `results[]` but doesn't distinguish foreign IDs. Adopt. |
+| **Interactive subagents** — `interactive: true` → `waiting` state, `crew_respond`/`crew_done` | We don't have this. Our agents run to completion. Interactive subagents would enable oracle/planner patterns. |
+| **Overflow recovery** — Detect context overflow → compaction → auto_retry → recovered, with 120s timeout | We have no overflow recovery. Child Pi processes that hit context limits silently fail. |
+| **3-tier agent discovery with JSON overrides** | Our discovery uses teams/agents/workflows with schema validation. JSON overrides for model/thinking/tools are worth adding. |
+| **BootstrapSession** — Excludes own extension, uses `SessionManager.create().newSession()` | Our `child-pi.ts` uses `--extension` flags. Align with Pi 0.65+ `session_start` API. |
+| **Bundled subagents inherit parent model** | Our `model-fallback.ts` resolves model chain differently. Consider simplifying. |
+
+---
+
+## 2. Distilled Development Axes
+
+### Axis A: Runtime Hardening (Critical)
+
+**A1. Session-aware result delivery**
+- Current: Results go to artifacts + notification router
+- Target: Add `DeliveryCoordinator` pattern that routes results to the **owner session** specifically, queues when inactive, flushes on `session_start`
+- Why: Prevents result loss when a session is replaced/reloaded; matches Pi's lifecycle
+
+**A2. Overflow recovery for child processes**
+- Current: Child Pi hitting context limits fails silently or with generic errors
+- Target: Detect `agent_end` → `compaction_start/end` → `auto_retry_start/end` event sequence; mark task as `"overflow_recovering"` → `"recovered"` or `"failed"`
+- Why: Long tasks with large context currently fail unrecoverably
+
+**A3. Interactive subagent protocol**
+- Current: All agents run to completion; no mid-run interaction
+- Target: `interactive: true` in agent frontmatter → agent pauses after response, enters `waiting` state; parent sends `crew_respond` to continue, `crew_done` to finalize
+- Why: Enables oracle (decision evaluation), planner (multi-turn refinement), and any agent that needs human/team guidance mid-task
+
+**A4. Session resource cleanup alignment**
+- Current: SIGINT + beforeExit handlers
+- Target: Register cleanup via Pi's `registerSessionResourceCleanup()` when available; fall back to current handlers
+- Why: Aligns with Pi's new lifecycle; prevents orphan processes on session reload
+
+### Axis B: Discovery & Configuration (High)
+
+**B1. JSON config overrides for agents/teams**
+- Current: Agent frontmatter is the sole source of truth
+- Target: `~/.pi/agent/pi-crew.json` (global) and `.pi/pi-crew.json` (project) can override `model`, `thinking`, `tools`, `skills` for any agent
+- Why: Per-project model tuning without editing bundled agents; environment-specific tool access
+
+**B2. Thinking level propagation**
+- Current: Agent frontmatter has `model` but no `thinking` field
+- Target: Add `thinking` to agent schema; propagate to child Pi via `--thinking` flag or session params
+- Why: Aligns with Pi's thinking levels; cost control for expensive models
+
+**B3. Parent model inheritance for bundled agents**
+- Current: `model-fallback.ts` has a complex chain with config fallbacks
+- Target: Simplify: agent frontmatter model → parent session model → config default
+- Why: Reduces configuration burden; bundled agents work with whatever model the parent uses
+
+### Axis C: Ownership & Safety (High)
+
+**C1. Foreign-aware ownership model**
+- Current: `cancel.ts` returns flat results array
+- Target: `cancelOwned(runId, taskIds)` returns `{ abortedIds, missingIds, foreignIds }`; tool responses clearly distinguish "you can't abort foreign tasks"
+- Why: Prevents confusion in multi-session scenarios; security improvement
+
+**C2. Supervisor contact event (child→parent)**
+- Current: Mailbox is parent→child only; child can write artifacts
+- Target: Add `supervisor_contact` event type where child signals "I need a decision" with structured data; parent can respond via mailbox or `steer_subagent`
+- Why: Enables interactive subagent protocol (A3); currently children are fire-and-forget
+
+**C3. Session-scoped status filtering**
+- Current: `run-index.ts` merges project + user scope runs
+- Target: Default status/inspect to session-scoped; cross-scope access only via explicit `scope:` parameter
+- Why: Prevents accidental cross-contamination; matches pi-subagents' session scoping
+
+### Axis D: Compatibility & Polish (Medium)
+
+**D1. Compact read rendering awareness**
+- Current: Agent prompts reference AGENTS.md, SKILL.md, etc.
+- Target: Ensure agent prompts are self-contained enough that collapsed reads don't lose critical instructions; add fallback descriptions in team/workflow frontmatter
+- Why: Pi v0.72+ collapses these files in TUI; agents still receive full content via tool calls
+
+**D2. Pi 0.65+ API alignment**
+- Current: `child-pi.ts` uses CLI flags (`--model`, `--extension`, etc.)
+- Target: When Pi SDK exposes `SessionManager.create()` + `session_start` event in extension API, migrate child session creation to programmatic API
+- Why: More reliable than CLI flag parsing; better lifecycle control; Pi is moving toward SDK-first
+
+**D3. UI simplification**
+- Current: Full dashboard with 6 panes
+- Target: Ensure each pane works as a standalone tool action; no pane depends on another's state. Consider adding compact/expanded modes.
+- Why: pi-subagents removed overlays entirely; our dashboard should be usable without full TUI
+
+### Axis E: Observability Gaps (Medium)
+
+**E1. Overflow recovery metrics**
+- Add `tasks_overflow_recovering` and `tasks_overflow_recovered` counters to MetricRegistry
+
+**E2. Interactive subagent state tracking**
+- Add `tasks_waiting` state to heartbeat/watcher; track wait duration
+
+**E3. Foreign ownership audit logging**
+- Log foreign access attempts with session ID; detect potential conflicts
+
+---
+
+## 3. Priority Matrix
+
+| Priority | Item | Axis | Effort | Impact |
+|---|---|---|---|---|
+| 🔴 P0 | A1: Session-aware result delivery | A | M | High — prevents result loss |
+| 🔴 P0 | A2: Overflow recovery for child processes | A | M | High — long tasks currently fail silently |
+| 🟡 P1 | C1: Foreign-aware ownership model | C | S | High — security + UX |
+| 🟡 P1 | A4: Session resource cleanup alignment | A | S | Medium — aligns with Pi lifecycle |
+| 🟡 P1 | B1: JSON config overrides | B | M | Medium — per-project customization |
+| 🟡 P1 | B2: Thinking level propagation | B | S | Medium — cost control |
+| 🟡 P1 | D1: Compact read rendering awareness | D | S | Medium — compatibility |
+| 🟢 P2 | A3: Interactive subagent protocol | A | L | High — enables oracle/planner |
+| 🟢 P2 | B3: Parent model inheritance | B | S | Low — simplification |
+| 🟢 P2 | C2: Supervisor contact event | C | M | Medium — depends on A3 |
+| 🟢 P2 | C3: Session-scoped status | C | S | Low — UX improvement |
+| 🟢 P2 | D2: Pi 0.65+ API alignment | D | L | Low — future-proofing |
+| 🟢 P2 | D3: UI simplification | D | M | Low — nice to have |
+| 🔵 P3 | E1-E3: Observability gaps | E | S | Low — monitoring |
+
+---
+
+## 4. Implementation Order (Proposed)
+
+### Phase 10a: Runtime Hardening (P0 + P1)
+1. **A1: DeliveryCoordinator** — session-aware result routing
+2. **A2: OverflowRecoveryTracker** — detect context overflow → compaction → retry
+3. **C1: Foreign-aware ownership** — `abortOwned()` with foreign detection
+4. **A4: Session resource cleanup** — `registerSessionResourceCleanup()` adapter
+
+### Phase 10b: Discovery & Configuration (P1)
+5. **B1: JSON config overrides** — `.pi/pi-crew.json` per-project settings
+6. **B2: Thinking level propagation** — `thinking` frontmatter field
+7. **D1: Compact read awareness** — self-contained agent prompts
+
+### Phase 10c: Interactive Protocol (P2)
+8. **A3: Interactive subagent** — `waiting` state + `crew_respond`/`crew_done` pattern
+9. **C2: Supervisor contact event** — child→parent communication channel
+10. **B3: Parent model inheritance** — simplified resolve chain
+
+### Phase 10d: Polish & Compatibility (P2-P3)
+11. **C3: Session-scoped status** — default filter to session
+12. **D3: UI compact/expanded modes** — standalone pane usability
+13. **E1-E3: Observability gaps** — overflow, waiting, foreign metrics
+14. **D2: Pi 0.65+ API alignment** — programmatic session creation (when SDK available)
+
+---
+
+## 5. Key Code References
+
+| Pattern | Source File | Lines |
+|---|---|---|
+| Compact read rendering | `pi-mono/packages/coding-agent/src/core/tools/read.ts` | `CompactReadClassification`, `formatCompactReadCall()` |
+| Session resource cleanup | `pi-mono/packages/ai/src/session-resources.ts` | `registerSessionResourceCleanup()`, `cleanupSessionResources()` |
+| Codex WS SSE fallback | `pi-mono/packages/ai/src/providers/openai-codex-responses.ts` | `isWebSocketSseFallbackActive()` |
+| Chain directories | `pi-subagents/src/agents/agents.ts` | `getUserChainDir()`, `resolveNearestProjectChainDirs()` |
+| Supervisor contact | `pi-subagents/src/runs/shared/supervisor-contact.ts` | `contact_supervisor` event |
+| Thinking levels | `pi-subagents/src/agents/agents.ts` | frontmatter `thinking` field |
+| Session scoping | `pi-subagents/src/runs/foreground/foreground-run-queue.ts` | session-scoped filtering |
+| CrewRuntime singleton | `pi-crew-ref/extension/runtime/crew-runtime.ts` | Process-level singleton |
+| DeliveryCoordinator | `pi-crew-ref/extension/runtime/delivery-coordinator.ts` | Owner-session routing |
+| Ownership model | `pi-crew-ref/extension/integration/tools/crew-abort.ts` | `abortOwned()` |
+| Interactive subagent | `pi-crew-ref/extension/runtime/subagent-state.ts` | `waiting` state |
+| Overflow recovery | `pi-crew-ref/extension/runtime/overflow-recovery.ts` | `OverflowRecoveryTracker` |
+| Bootstrap session | `pi-crew-ref/extension/bootstrap-session.ts` | Extension exclusion, parent model |

package/docs/research-phase11-distillation.md

@@ -0,0 +1,201 @@
+# Phase 10+ Deep Distillation — Round 2
+
+**Date**: 2026-05-04
+**Sources**: `pi-mono` v0.72.1 (`324aa1d`), `pi-subagents` v0.24.0 (`3ee17de`), `pi-crew` ref v1.0.14 (`c0631a3`)
+
+## Executive Summary
+
+Sau khi deep-read lần 2 vào runtime internals của cả 3 repos, phát hiện **15 insights mới** chưa được implement trong pi-crew. Phân thành 4 axes: Runtime Architecture, Extension API Adoption, Observability/Reliability, và Developer Experience.
+
+---
+
+## Axis F: Runtime Architecture Alignment
+
+### F1. Process-Level Singleton for CrewRuntime ⭐⭐⭐
+**Source**: pi-crew ref `crew-runtime.ts`
+**Finding**: Module-level singleton (`export const crewRuntime = new CrewRuntime()`) sống xuyên suốt process lifetime. Khi Pi thay extension instance (session switch), singleton vẫn tồn tại vì Node.js module cache. New extension instance chỉ cần gọi `crewRuntime.activateSession(binding)`.
+**Current pi-crew**: Mỗi session tạo mới state. Chưa có survive-across-session mechanism.
+**Action**: Refactor `SubagentManager` thành process-level singleton với `activateSession()` pattern. In-flight child processes survive session switches.
+
+### F2. Fire-and-Forget Spawn với Immediate ID Return ⭐⭐⭐
+**Source**: pi-crew ref `crew-runtime.ts`
+**Finding**: `spawn()` tạo state → return ID ngay lập tức → chạy `spawnSession()` async (fire-and-forget). Caller không block.
+**Current pi-crew**: `runChildPi` là async block. Task runner phải await.
+**Action**: Tách spawn thành sync ID allocation + async execution. Task runner fire-and-forget, poll status qua event log.
+
+### F3. Final Drain Window Pattern ⭐⭐
+**Source**: pi-subagents `execution.ts`
+**Finding**: Khi `message_end` với `stopReason === "stop"` và không có tool calls → start 1s grace timer → SIGTERM → 3s → SIGKILL. Giúp child process flush output cuối cùng.
+**Current pi-crew**: Child Pi timeout đơn giản, không có grace period sau completion signal.
+**Action**: Implement `FINAL_STOP_GRACE_MS` drain window trong `child-pi.ts`.
+
+### F4. Atomic JSON Writes cho Status Persistence ⭐⭐
+**Source**: pi-subagents `async-execution.ts`
+**Finding**: `writeAtomicJson()` ghi file temp → rename. Tránh torn writes khi process crash giữa chừng.
+**Current pi-crew**: `JSON.stringify` + `writeFileSync` trực tiếp — rủi ro torn write.
+**Action**: Implement `writeAtomicJson()` utility. Apply cho status.json, manifest writes.
+
+### F5. Two-Level Process Hierarchy cho Async ⭐
+**Source**: pi-subagents `subagent-runner.ts`
+**Finding**: Orchestrator spawn runner (detached) → runner spawn Pi children. Runner track PIDs, write status.json. Orchestrator poll status.json.
+**Current pi-crew**: Async run chỉ fire background, không có intermediate runner process.
+**Action**: (Low priority) Xem xét thêm intermediate runner cho reliable async tracking.
+
+### F6. Stale Run Reconciler — Three-Phase Pattern ⭐⭐
+**Source**: pi-subagents `stale-run-reconciler.ts`
+**Finding**: 3-phase: (1) check result file exists → use it, (2) check PID liveness, (3) for dead PIDs → repair immediately, for alive PIDs → fail only if stale > 24h.
+**Current pi-crew**: Có `crash-recovery.ts` nhưng chưa có full 3-phase reconciliation.
+**Action**: Nâng cấp crash recovery với 3-phase pattern: result-check → PID-check → stale-threshold.
+
+---
+
+## Axis G: Extension API Adoption
+
+### G1. `session_before_compact` Hook — Custom Compaction ⭐⭐⭐
+**Source**: pi-mono `extensions/types.ts`
+**Finding**: Hook `session_before_compact` returns `{ cancel?, compaction?: CompactionResult }`. Extensions có thể **thay thế hoàn toàn** compaction logic — bao gồm structured details (artifact indices, version markers). Đây là extensibility point mạnh nhất.
+**Current pi-crew**: `compaction-guard.ts` chỉ phát hiện compaction events, không can thiệp.
+**Action**: Implement `session_before_compact` handler để cung cấp structured compaction thay vì raw text summarization. Preserve team run state across compaction.
+
+### G2. `session_before_switch` Hook — Pre-Switch State Save ⭐⭐
+**Source**: pi-mono `extensions/types.ts`
+**Finding**: `session_before_switch` fires trước khi Pi switches session (new/resume). Return `{ cancel? }`. Pi-crew có thể save in-memory state → file trước khi switch.
+**Current pi-crew**: Không hook vào session switch. State mất khi switch.
+**Action**: Hook `session_before_switch` để flush pending deliveries và save subagent state snapshot.
+
+### G3. `resources_discover` Hook — Dynamic Agent/Team Discovery ⭐⭐⭐
+**Source**: pi-mono `extensions/types.ts`
+**Finding**: `resources_discover` event returns `{ additionalSkillPaths?, additionalPromptPaths?, additionalThemePaths? }`. Extensions có thể dynamically inject resources.
+**Current pi-crew**: Discovery chỉ đọc từ filesystem. Không dynamic.
+**Action**: Hook `resources_discover` để inject team-specific skills/prompts dựa trên config. VD: auto-inject `safe-bash` skill cho projects có `package.json`.
+
+### G4. `before_agent_start` — System Prompt Override ⭐⭐
+**Source**: pi-mono `extensions/types.ts`
+**Finding**: Can inject `message` and/or override `systemPrompt` before agent loop begins. Powerful for child agents.
+**Current pi-crew**: Child Pi system prompt built từ task packet, không override qua hook.
+**Action**: (Low priority — already handled via task packet prompt builder)
+
+### G5. `tool_result` Event — Post-Execution Output Modification ⭐
+**Source**: pi-mono `extensions/types.ts`
+**Finding**: Can modify tool output `content`, `details`, `isError` after execution. Useful for enrichment/filtering.
+**Current pi-crew**: Không hook vào tool results.
+**Action**: Hook `tool_result` cho `team` tool để enrich output với structured metadata (run URL, artifact count, duration).
+
+### G6. `input` Event — User Input Interception ⭐
+**Source**: pi-mono `extensions/types.ts`
+**Finding**: Can transform user input text/images or fully handle it (`action: "continue" | "transform" | "handled"`).
+**Current pi-crew**: Không intercept user input.
+**Action**: Hook `input` để detect `@team-name` mentions → auto-route to team run.
+
+---
+
+## Axis H: Observability & Reliability Gaps
+
+### H1. Completion Mutation Guard ⭐⭐
+**Source**: pi-subagents `completion-guard.ts`
+**Finding**: Sau khi subagent trả về "success", check xem nếu task là "implementation" nhưng **không có file edits** → mutate completion thành warning. Tránh false-positive completions.
+**Current pi-crew**: Task complete khi child Pi exits 0. Không verify actual work done.
+**Action**: Implement completion guard: verify artifacts exist, files changed, hoặc output non-trivial.
+
+### H2. Snapshot-Before-Emit Pattern ⭐
+**Source**: pi-subagents `execution.ts`
+**Finding**: Progress object snapshotted (spread) trước mỗi `onUpdate` callback. Tránh mutation during callback.
+**Current pi-crew**: Task state mutated directly, events emit references.
+**Action**: Snapshot task state trước khi emit events để avoid race conditions.
+
+### H3. Intercom Bridge với Delivery Confirmation ⭐⭐
+**Source**: pi-subagents `intercom-bridge.ts`
+**Finding**: Bidirectional intercom: `deliverSubagentResultIntercomEvent()` emit event → wait for confirmation với 500ms timeout. Agent injection pattern: mutate config để add `contact_supervisor` tool + instructions.
+**Current pi-crew**: Có `supervisor-contact.ts` parse từ stdout, nhưng không có bidirectional confirmation.
+**Action**: Nếu Pi expose intercom API, upgrade supervisor contact thành bidirectional với delivery confirmation.
+
+### H4. writeAtomicJson Utility ⭐⭐
+**Source**: pi-subagents (pervasive)
+**Finding**: Atomic file writes used everywhere: status, manifest, results. Pattern: `writeFileSync(path + ".tmp", data) → renameSync(path + ".tmp", path)`.
+**Action**: Shared utility trong `src/utils/atomic-write.ts`.
+
+---
+
+## Axis I: Developer Experience
+
+### I1. Tool Presentation — Emoji + Grouping ⭐
+**Source**: pi-crew ref `tool-presentation.ts`
+**Finding**: `crew_spawn` renders "🚀 Spawning {agent}...", `crew_respond` renders "💬 Sending response...". Grouped tool calls have custom collapse UI.
+**Current pi-crew**: Tool output plain text.
+**Action**: Add emoji prefixes và structured formatting cho tool output.
+
+### I2. renderCall/renderResult cho Team Tool ⭐⭐
+**Source**: pi-mono `tools/index.ts`
+**Finding**: `ToolDefinition` supports `renderCall` và `renderResult` callbacks returning TUI Components. Allows rich rendering in Pi terminal UI.
+**Current pi-crew**: Không có custom renderers.
+**Action**: Implement `renderCall` cho `team` tool để show spinner/agent-list thay vì raw JSON. Implement `renderResult` để show summary dashboard.
+
+### I3. Prompt Snippet + Guidelines trong Tool Definition ⭐
+**Source**: pi-mono `tools/index.ts`
+**Finding**: `promptSnippet` — one-liner in system prompt. `promptGuidelines` — bullets appended to system prompt. Tools without `promptSnippet` are excluded from LLM awareness.
+**Current pi-crew**: Tool description chỉ trong JSON schema description.
+**Action**: Khi Pi hỗ trợ `promptSnippet`/`promptGuidelines` trong custom tools, adopt để improve LLM tool usage.
+
+---
+
+## Priority Matrix
+
+| ID | Feature | Impact | Effort | Priority |
+|---|---|---|---|---|
+| F1 | Process-level singleton | High | High | P1 |
+| F2 | Fire-and-forget spawn | Medium | Medium | P2 |
+| F3 | Final drain window | Medium | Low | P2 |
+| F4 | Atomic JSON writes | High | Low | P1 |
+| F5 | Two-level async hierarchy | Low | High | P3 |
+| F6 | 3-phase stale reconciliation | Medium | Medium | P2 |
+| G1 | Custom compaction hook | High | Medium | P1 |
+| G2 | Pre-switch state save | Medium | Low | P2 |
+| G3 | Dynamic resource discovery | High | Medium | P1 |
+| G4 | System prompt override | Low | Low | P3 |
+| G5 | Post-execution output mod | Low | Low | P3 |
+| G6 | User input interception | Medium | Medium | P3 |
+| H1 | Completion mutation guard | High | Low | P1 |
+| H2 | Snapshot-before-emit | Medium | Low | P2 |
+| H3 | Bidirectional intercom | Medium | High | P3 |
+| H4 | writeAtomicJson utility | High | Low | P1 |
+| I1 | Tool presentation emojis | Low | Low | P3 |
+| I2 | Custom TUI renderers | High | High | P2 (when API available) |
+| I3 | Prompt snippet/guidelines | Medium | Low | P3 (when API available) |
+
+---
+
+## Recommended Implementation Order
+
+### Phase 11a: Reliability Foundations (F4 + H4 + H1 + H2)
+- `src/utils/atomic-write.ts` — writeAtomicJson utility
+- Apply atomic writes to all manifest/state writes
+- Completion mutation guard for task results
+- Snapshot-before-emit for task state events
+
+### Phase 11b: Extension API Hooks (G1 + G2 + G3)
+- `session_before_compact` handler — structured compaction
+- `session_before_switch` handler — pre-switch state flush
+- `resources_discover` handler — dynamic skill/prompt injection
+
+### Phase 11c: Runtime Architecture (F1 + F2 + F3)
+- Refactor SubagentManager → process-level singleton
+- Fire-and-forget spawn pattern
+- Final drain window for child process cleanup
+
+### Phase 11d: Reconciliation & Recovery (F6 + H3)
+- 3-phase stale run reconciliation
+- Upgrade supervisor contact toward bidirectional (if API available)
+
+---
+
+## Already Implemented (Phase 10a-10d) ✅
+- DeliveryCoordinator (session-aware routing with queue/flush)
+- OverflowRecoveryTracker (compaction → retry state machine)
+- Foreign-aware cancel (ownership detection)
+- Session resource cleanup adapter
+- Interactive subagent waiting state + respond action
+- Supervisor contact parsing from child stdout
+- Parent model inheritance
+- Session-scoped run listing
+- Observability metrics for overflow/waiting/supervisor
+- Skills override + .pi/pi-crew.json config path

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.1.43",
+  "version": "0.1.44",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/src/agents/discover-agents.ts

@@ -80,6 +80,7 @@ function applyAgentOverrides(agents: AgentConfig[], cwd: string): AgentConfig[]
 				fallbackModels: override.fallbackModels === false ? undefined : override.fallbackModels ?? agent.fallbackModels,
 				thinking: override.thinking === false ? undefined : override.thinking ?? agent.thinking,
 				tools: override.tools === false ? undefined : override.tools ?? agent.tools,
+				skills: override.skills === false ? undefined : override.skills ?? agent.skills,
 				override: { source: "config", path: loaded.path },
 			};
 		});

package/src/config/config.ts

@@ -80,6 +80,7 @@ export interface AgentOverrideConfig {
 	fallbackModels?: string[] | false;
 	thinking?: string | false;
 	tools?: string[] | false;
+	skills?: string[] | false;
 }
 
 export interface CrewAgentsConfig {
@@ -189,6 +190,14 @@ export function projectConfigPath(cwd: string): string {
 	return path.join(projectCrewRoot(cwd), "config.json");
 }
 
+/**
+ * Alternative project config path: `.pi/pi-crew.json` in the project root.
+ * This is a convenience path alongside the standard `config.json` in crewRoot.
+ */
+export function projectPiCrewJsonPath(cwd: string): string {
+	return path.join(cwd, ".pi", "pi-crew.json");
+}
+
 function withoutUndefined<T extends Record<string, unknown>>(value: T): Partial<T> {
 	return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined)) as Partial<T>;
 }
@@ -536,6 +545,7 @@ function parseAgentOverride(value: unknown): AgentOverrideConfig | undefined {
 		fallbackModels: parseStringArrayOrFalse(obj.fallbackModels),
 		thinking: parseWithSchema(Type.Union([Type.String(), Type.Literal(false)]), obj.thinking),
 		tools: parseStringArrayOrFalse(obj.tools),
+		skills: parseStringArrayOrFalse(obj.skills),
 	};
 	return Object.values(override).some((entry) => entry !== undefined) ? override : undefined;
 }
@@ -731,6 +741,15 @@ export function loadConfig(cwd?: string): LoadedPiTeamsConfig {
 			const projectSafeConfig = sanitizeProjectConfig(projectPath, config, projectConfig.config);
 			warnings.push(...projectConfig.warnings.map((warning) => `${projectPath}: ${warning}`), ...projectSafeConfig.warnings);
 			config = mergeConfig(config, projectSafeConfig.config);
+			// Also load .pi/pi-crew.json from project root if it exists
+			const piCrewJsonPath = projectPiCrewJsonPath(cwd);
+			if (fs.existsSync(piCrewJsonPath)) {
+				const piCrewJsonConfig = parseConfigWithWarnings(readConfigRecord(piCrewJsonPath));
+				const piCrewJsonSafeConfig = sanitizeProjectConfig(piCrewJsonPath, config, piCrewJsonConfig.config);
+				warnings.push(...piCrewJsonConfig.warnings.map((warning) => `${piCrewJsonPath}: ${warning}`), ...piCrewJsonSafeConfig.warnings);
+				config = mergeConfig(config, piCrewJsonSafeConfig.config);
+				paths.push(piCrewJsonPath);
+			}
 		}
 		return { path: filePath, paths, config, warnings: warnings.length > 0 ? warnings : undefined };
 	} catch (error) {