pi-crew 0.1.49 → 0.2.0

package/docs/research-pi-coding-agent.md

@@ -1,357 +0,0 @@
-# Research: pi-mono coding-agent Deep Read
-
-> Ngày: 2026-04-29 | Read-only research | Source: `source/pi-mono/packages/coding-agent/`
-
-## 1. Vai trò trong monorepo
-
-`@mariozechner/pi-coding-agent` là package trung tâm nhất của pi-mono. Nó chứa CLI binary `pi`,
-toàn bộ agent session lifecycle, extension host system, 3 run modes, 7 built-in tools, session
-persistence, compaction, branch summarization, và SDK cho programmatic usage.
-
-Package version: `0.70.5` (lockstep với toàn bộ monorepo).
-
-## 2. Cấu trúc source
-
-```
-src/
-├── cli.ts                        # Binary entry point (shebang #!/usr/bin/env node)
-├── main.ts                       # CLI logic: parse args, dispatch mode (731 dòng)
-├── index.ts                      # Public API exports (~250 dòng re-exports)
-├── config.ts                     # Path constants (agentDir, VERSION, APP_NAME)
-├── cli/                          # CLI subsystems
-│   ├── args.ts                   # Argument parsing (yargs-style)
-│   ├── file-processor.ts         # @file argument expansion
-│   ├── initial-message.ts        # Build initial prompt from args/stdin
-│   ├── list-models.ts            # --list-models output
-│   └── session-picker.ts         # Interactive session selection
-├── core/                         # ═══ CORE LAYER ═══
-│   ├── agent-session.ts          # AgentSession class (3099 dòng) — TRUNG TÂM
-│   ├── agent-session-runtime.ts  # AgentSessionRuntime wrapper (session replacement)
-│   ├── agent-session-services.ts # Dịch vụ tạo cwd-bound runtime
-│   ├── sdk.ts                    # createAgentSession() public factory (~408 dòng)
-│   ├── session-manager.ts        # Session file I/O, entries, tree (1425 dòng)
-│   ├── settings-manager.ts       # settings.json manager (~1069 dòng)
-│   ├── system-prompt.ts          # System prompt builder (172 dòng)
-│   ├── resource-loader.ts        # Load extensions/skills/prompts/themes (~920 dòng)
-│   ├── model-registry.ts         # Model + auth registry
-│   ├── model-resolver.ts         # Model resolution / scope / fallback
-│   ├── keybindings.ts            # Keybinding manager (KeybindingsManager)
-│   ├── messages.ts               # AgentMessage type definitions + converters
-│   ├── bash-executor.ts          # Bash execution abstraction layer
-│   ├── prompt-templates.ts       # File-based prompt templates (@file expansion)
-│   ├── skills.ts                 # Skill loading + formatting for system prompt
-│   ├── slash-commands.ts         # 21 built-in slash commands
-│   ├── event-bus.ts              # Shared event bus for cross-extension communication
-│   ├── footer-data-provider.ts   # Footer data provider (git branch + extension statuses)
-│   ├── auth-storage.ts           # API key / OAuth credential storage
-│   ├── auth-guidance.ts          # User-facing auth error messages
-│   ├── extensions/               # ═══ EXTENSION SYSTEM ═══
-│   │   ├── types.ts              # Type surface (1545 dòng)
-│   │   ├── loader.ts             # jiti-based extension loader (~607 dòng)
-│   │   ├── runner.ts             # ExtensionRunner lifecycle manager (~1024 dòng)
-│   │   ├── wrapper.ts            # Tool wrapping utilities
-│   │   └── index.ts              # Re-exports (~170 dòng)
-│   ├── compaction/               # ═══ COMPACTION ═══
-│   │   ├── compaction.ts         # Context compaction logic (~840 dòng)
-│   │   ├── branch-summarization.ts # Tree navigation summarization (~356 dòng)
-│   │   ├── utils.ts              # File ops tracking + serialization
-│   │   └── index.ts
-│   └── tools/                    # ═══ BUILT-IN TOOLS ═══
-│       ├── index.ts              # Tool registry + factories (~198 dòng)
-│       ├── read.ts               # File reading with truncation
-│       ├── bash.ts               # Shell command execution
-│       ├── edit.ts               # Exact text replacement
-│       ├── write.ts              # File creation/overwrite
-│       ├── grep.ts               # Regex search
-│       ├── find.ts               # File name search
-│       ├── ls.ts                 # Directory listing
-│       ├── file-mutation-queue.ts # Serialized file writes
-│       ├── truncate.ts           # Output truncation strategies
-│       └── render-utils.ts
-├── modes/                        # ═══ RUN MODES ═══
-│   ├── index.ts                  # Re-exports
-│   ├── interactive/              # Interactive TUI mode (5470 dòng)
-│   │   ├── interactive-mode.ts   # Main TUI loop + all slash commands
-│   │   ├── components/           # 30+ TUI components (assistant messages, diffs, editors...)
-│   │   └── theme/                # Theme engine (JSON-based, hot-reload)
-│   ├── print-mode.ts             # Non-interactive / JSON output mode
-│   └── rpc/                      # JSON-RPC mode for embedding (parent-child protocol)
-│       ├── rpc-mode.ts           # RPC server loop
-│       ├── rpc-client.ts         # RPC client for SDK/programmatic use
-│       ├── rpc-types.ts          # JSON-RPC message types
-│       └── jsonl.ts              # JSONL output formatting
-└── utils/                        # Shared utilities
-    ├── clipboard.ts              # Clipboard integration
-    ├── frontmatter.ts            # YAML frontmatter parser
-    ├── shell.ts                  # Shell detection/config
-    ├── paths.ts                  # Path utilities
-    └── sleep.ts                  # Promise-based sleep
-```
-
-## 3. Các file chính - số dòng
-
-| File | Dòng | Mô tả |
-|---|---|---|
-| `modes/interactive/interactive-mode.ts` | 5470 | Interactive TUI + tất cả 21 slash command handlers |
-| `core/agent-session.ts` | 3099 | AgentSession class: prompt, compaction, bash, model management |
-| `core/extensions/types.ts` | 1545 | Toàn bộ type surface cho extension system |
-| `core/session-manager.ts` | 1425 | Session file I/O, entry types, tree operations |
-| `core/settings-manager.ts` | ~1069 | JSON settings management (global + project) |
-| `core/extensions/runner.ts` | ~1024 | ExtensionRunner: event emission, context binding |
-| `core/resource-loader.ts` | ~920 | Unified loader for extensions/skills/prompts/themes |
-| `core/compaction/compaction.ts` | ~840 | Compaction logic + cut-point detection |
-| `main.ts` | 731 | CLI entry: arg parsing → mode dispatch |
-| `core/extensions/loader.ts` | ~607 | jiti-based TypeScript module loading |
-
-## 4. Luồng thực thi chính
-
-### 4.1 Startup sequence (`main.ts`)
-
-```
-main(args)
-  ├── parseArgs(args)                          # Parse CLI flags
-  ├── resolveAppMode()                         # interactive | print | json | rpc
-  ├── runMigrations()                          # Upgrade old session formats
-  ├── createSessionManager()                   # new/fork/continue/resume/in-memory
-  ├── createAgentSessionRuntime(createRuntime) # Build full runtime
-  │     └── createRuntime(cwd, agentDir, sessionManager)
-  │           ├── createAgentSessionServices()  # authStorage, modelRegistry, resourceLoader
-  │           ├── resolveModelScope()           # --models flag → scoped models
-  │           ├── buildSessionOptions()         # model, thinking, tools, scopedModels
-  │           └── createAgentSessionFromServices() → AgentSession
-  ├── readPipedStdin()                         # Pipe support
-  ├── prepareInitialMessage()                  # text + images
-  └── dispatch:
-        ├── interactive → new InteractiveMode(runtime).run()
-        ├── print/json  → runPrintMode(runtime, {...})
-        └── rpc         → runRpcMode(runtime)
-```
-
-### 4.2 AgentSession.prompt() lifecycle
-
-```
-session.prompt(text)
-  ├── parseSkillBlock()                  # <skill name="..." location="...">
-  ├── expandPromptTemplate()             # @file expansion
-  ├── emitInput()                        # Extension can transform/block input
-  ├── emitBeforeAgentStart()             # Extension can inject custom message / swap system prompt
-  ├── agent.runAgentLoop()
-  │     ├── context → extension transform messages
-  │     ├── before_provider_request → extension modify payload
-  │     ├── streamSimple(model, context, ...)
-  │     ├── after_provider_response → extension observe response
-  │     ├── tool_call → extension intercept/block/mutate args
-  │     ├── tool_execution_start/update/end
-  │     ├── tool_result → extension modify result
-  │     └── auto-compaction check (after turn_end)
-  └── emitAgentEnd()
-```
-
-### 4.3 Run modes
-
-| Mode | Class/Function | Đặc điểm |
-|---|---|---|
-| **Interactive** | `InteractiveMode` (5470 dòng) | Full TUI: chat history, editor, widgets, themes, overlays, keybindings |
-| **Print/JSON** | `runPrintMode()` | Pipe/script: plain text or JSON mode, no TUI |
-| **RPC** | `runRpcMode()` | JSON-RPC 2.0 over stdin/stdout — dùng làm child process protocol |
-
-## 5. AgentSession class chi tiết
-
-### 5.1 Properties
-
-```typescript
-class AgentSession {
-  readonly agent: Agent;                    // Core agent instance
-  readonly sessionManager: SessionManager;  // Session file I/O
-  readonly settingsManager: SettingsManager;// Settings
-
-  // Model access
-  get model(): Model<any> | undefined;
-  get thinkingLevel(): ThinkingLevel;
-  get scopedModels(): Array<{model, thinkingLevel}>;
-
-  // Tool access
-  get toolNames(): string[];               // Currently active tools
-  get tools(): ToolInfo[];                 // All registered tools with metadata
-  getAllTools(): ToolInfo[];
-
-  // Context
-  getContextUsage(): ContextUsage | undefined;
-  isIdle(): boolean;
-
-  // Core operations
-  prompt(text, options?): Promise<void>;   // Send user message
-  abort(): void;                           // Abort current operation
-  shutdown(): void;                        // Graceful shutdown
-
-  // Model management
-  cycleModel(forward?): ModelCycleResult;  // Ctrl+P cycling
-  setModel(model): Promise<boolean>;       // Switch model
-  setThinkingLevel(level): void;
-
-  // Compaction
-  compact(options?): void;                 // Manual compaction
-  getSessionStats(): SessionStats;         // Usage stats
-}
-```
-
-### 5.2 Internal state machine
-
-Key internal flags:
-- `_steeringMessages[]` / `_followUpMessages[]`: Queued messages
-- `_compactionAbortController` / `_autoCompactionAbortController`: Compaction control
-- `_overflowRecoveryAttempted`: Context overflow recovery flag
-- `_retryAttempt` / `_retryPromise`: Auto-retry state
-- `_bashAbortController` / `_pendingBashMessages[]`: Bash execution state
-- `_turnIndex`: Current turn counter
-
-### 5.3 Tool hooks
-
-`_installAgentToolHooks()` installs interceptors on the Agent instance:
-- `beforeToolCall`: Check if extension wants to intercept/block
-- `onToolResult`: Check if extension wants to modify result
-
-## 6. Session Persistence (`session-manager.ts`)
-
-### 6.1 Session file format
-
-JSONL file (`.pi/sessions/{id}.jsonl`) với các entry types:
-
-| Entry Type | Purpose | Fields |
-|---|---|---|
-| `session` | Header | version, id, timestamp, cwd, parentSession |
-| `message` | AgentMessage (user/assistant/toolResult) | message |
-| `thinking_level_change` | Thinking level change | thinkingLevel |
-| `model_change` | Model switch | provider, modelId |
-| `compaction` | Compaction summary | summary, firstKeptEntryId, tokensBefore, details |
-| `branch_summary` | Branch navigation | summary, fromId, details |
-| `custom_message` | Extension-defined for LLM context | customType, content, display, details |
-| `custom` | Extension state (not in LLM context) | customType, data |
-
-Current version: `CURRENT_SESSION_VERSION = 3`
-
-### 6.2 Session tree
-
-- Mỗi session có `parentSession` reference (khi fork)
-- `SessionManager.forkFrom()` tạo session mới
-- `buildSessionContext()` dựng messages từ entries (cả compaction + branch summary)
-- `navigateTree()` di chuyển giữa các branch trong cùng session
-
-## 7. Compaction System
-
-### 7.1 Auto-compaction (`compaction/compaction.ts`)
-
-Default settings:
-```
-reserveTokens: 16384    # Dành cho system prompt + LLM response
-keepRecentTokens: 20000 # Giữ các messages gần đây
-```
-
-Process:
-1. `shouldCompact()` — kiểm tra context usage sau mỗi turn
-2. `findCutPoint()` — tìm vị trí cắt dựa vào file operations
-3. `prepareCompaction()` — build messagesToSummarize + turnPrefixMessages
-4. `compact()` — serialize → LLM summarize → return CompactionResult
-5. SessionManager lưu `CompactionEntry` + tạo session mới (reload)
-
-### 7.2 Branch summarization (`compaction/branch-summarization.ts`)
-
-Khi user navigate session tree, tạo summary của branch hiện tại:
-- `collectEntriesForBranchSummary()` — thu thập entries cần summarize
-- `prepareBranchEntries()` — extract messages + file operations
-- `generateBranchSummary()` — gọi LLM tạo summary
-
-### 7.3 Cut-point strategy
-
-Tìm cut-point dựa trên:
-- File operations: ưu tiên cắt ở điểm không có pending file modifications
-- Assistant messages: không cắt giữa tool calls
-- Keep recent tokens: giữ ít nhất `keepRecentTokens` cuối cùng
-
-## 8. Built-in Tools
-
-7 tools, mỗi tool có 2 representations:
-- `AgentTool` — runtime execution contract
-- `ToolDefinition` — type-safe definition với schema + render
-
-| Tool | File | Key params | Đặc điểm |
-|---|---|---|---|
-| `read` | `tools/read.ts` | path, offset, limit | Head/tail truncation, image support |
-| `bash` | `tools/bash.ts` | command, timeout | AbortController, timeout |
-| `edit` | `tools/edit.ts` | path, edits[{oldText,newText}] | Exact replacement, multi-edit |
-| `write` | `tools/write.ts` | path, content | Overwrite/create |
-| `grep` | `tools/grep.ts` | pattern, path | Regex search |
-| `find` | `tools/find.ts` | pattern, path | File name glob |
-| `ls` | `tools/ls.ts` | path | Directory listing |
-
-**File mutation queue** (`file-mutation-queue.ts`): Serializes write operations to prevent
-parallel tool conflicts. Used internally by edit/write tools.
-
-## 9. Settings Manager (`settings-manager.ts`)
-
-Quản lý `settings.json` với các section:
-
-| Section | Key settings | Default |
-|---|---|---|
-| `compaction` | enabled, reserveTokens, keepRecentTokens | true, 16384, 20000 |
-| `retry` | enabled, maxRetries, baseDelayMs | true, 3, 2000 |
-| `retry.provider` | timeoutMs, maxRetries, maxRetryDelayMs | (SDK defaults) |
-| `terminal` | showImages, imageWidthCells, clearOnShrink, showTerminalProgress | true, 60, false, false |
-| `images` | autoResize, blockImages | true, false |
-| `thinkingBudgets` | minimal, low, medium, high | (per-level defaults) |
-| `markdown` | codeBlockIndent | "  " |
-
-Scope: global (`~/.pi/agent/settings.json`) + project-local (`.pi/settings.json`).
-
-## 10. Slash Commands
-
-21 built-in commands (`slash-commands.ts`):
-
-| Command | Purpose |
-|---|---|
-| `settings` | Open settings menu |
-| `model` | Select model (selector UI) |
-| `scoped-models` | Enable/disable models for Ctrl+P |
-| `export` | Export session (HTML/JSONL) |
-| `import` | Import session from JSONL |
-| `share` | Share as GitHub gist |
-| `copy` | Copy last message |
-| `name` | Set session display name |
-| `session` | Show session info + stats |
-| `changelog` | Show changelog |
-| `hotkeys` | Show keyboard shortcuts |
-| `fork` | Fork from previous message |
-| `clone` | Duplicate session |
-| `tree` | Navigate session tree |
-| `login`/`logout` | Auth management |
-| `new` | Start new session |
-| `compact` | Manual compaction |
-| `resume` | Resume different session |
-| `reload` | Reload extensions/skills/themes |
-| `quit` | Exit |
-
-## 11. RPC Mode
-
-JSON-RPC 2.0 protocol qua stdin/stdout:
-
-```typescript
-// Request
-{ "jsonrpc": "2.0", "id": 1, "method": "prompt", "params": { "text": "..." } }
-
-// Response
-{ "jsonrpc": "2.0", "id": 1, "result": { "messages": [...], "usage": {...} } }
-
-// Notification (no id)
-{ "jsonrpc": "2.0", "method": "event", "params": { "type": "message_start", ... } }
-```
-
-Đây là protocol chính cho parent-child communication trong pi-subagents và pi-crew.
-
-## 12. Các điểm đáng chú ý
-
-1. **Interactive mode quá lớn** (5470 dòng) — chứa hầu hết slash command implementations
-2. **AgentSession quá lớn** (3099 dòng) — mixed concerns: prompt, compaction, bash, lifecycle
-3. **Extension type surface** (1545 dòng) — rất comprehensive nhưng complex
-4. **Lockstep versioning** — tất cả packages cùng version 0.70.5
-5. **jiti-based extension loading** — cho phép TypeScript extensions không cần compile
-6. **Virtual modules** — cho Bun compiled binary, bundle sẵn các dependencies

package/docs/research-source-pi-crew-reference.md

@@ -1,174 +0,0 @@
-# Research: `source/pi-crew` as New Reference Source
-
-Date: 2026-04-29
-Reference source: `D:/my/my_project/source/pi-crew` (`@melihmucuk/pi-crew@1.0.14`, commit `c0631a3`)
-Current target: `D:/my/my_project/pi-crew` (`pi-crew@0.1.34`)
-Research run: `team_20260429091311_8047706b`
-
-> Note: the parallel research run produced useful artifacts, but child workers were marked failed because they did not exit within 5s after their final assistant message. The source audit content was still captured in result/shared artifacts.
-
-## Executive Summary
-
-`source/pi-crew` is a compact, in-process subagent orchestration extension. It is not a team/workflow engine; instead, it focuses on fast non-blocking subagent sessions, owner-routed steering-message delivery, interactive subagents, and context-overflow recovery. It is valuable as a reference for **session-native subagent runtime**, **delivery semantics**, and **minimal interactive worker UX**.
-
-Current `pi-crew` is more powerful and durable: child Pi workers, teams/workflows, task graph scheduling, worktrees, mailbox, event logs, dashboard, notifications, and recovery state. The best path is not replacement; it is selective porting of patterns into `pi-crew`'s existing `live-session-runtime` / `SubagentManager` as an optional session-native lane.
-
-## Source File Map
-
-| Area | Reference files |
-|---|---|
-| Extension entry/session hooks | `source/pi-crew/extension/index.ts` |
-| Runtime singleton | `source/pi-crew/extension/runtime/crew-runtime.ts` |
-| Delivery routing | `source/pi-crew/extension/runtime/delivery-coordinator.ts` |
-| State model/registry | `source/pi-crew/extension/runtime/subagent-state.ts`, `source/pi-crew/extension/runtime/subagent-registry.ts` |
-| Overflow recovery | `source/pi-crew/extension/runtime/overflow-recovery.ts` |
-| Session bootstrap | `source/pi-crew/extension/bootstrap-session.ts` |
-| Agent discovery | `source/pi-crew/extension/agent-discovery.ts` |
-| Tool registration | `source/pi-crew/extension/integration/register-tools.ts`, `source/pi-crew/extension/integration/tools/*.ts` |
-| Message renderers | `source/pi-crew/extension/integration/register-renderers.ts` |
-| Message formatting | `source/pi-crew/extension/subagent-messages.ts` |
-| Status widget | `source/pi-crew/extension/status-widget.ts` |
-| Architecture doc | `source/pi-crew/docs/architecture.md` |
-
-## Architecture Observations
-
-### Reference `source/pi-crew`
-
-- Process-level singleton `CrewRuntime` survives Pi runtime/session replacement and rebinds on `session_start`.
-- Subagents are in-process SDK `AgentSession`s created with `createAgentSession()`.
-- Parent/child linkage uses `SessionManager.newSession({ parentSession })`.
-- Subagent resource loading filters out the pi-crew extension through `extensionsOverride` to prevent recursive `crew_spawn` loops.
-- Results are delivered through Pi-native `sendMessage()` with explicit idle/streaming semantics.
-- Interactive subagents are first-class: `interactive: true` workers enter `waiting`; parent continues with `crew_respond`; cleanup is explicit with `crew_done`.
-- Overflow recovery tracks `agent_end`, `compaction_start/end`, and `auto_retry_start/end` events around `session.prompt()`.
-- State is in-memory only; subagent session files remain for post-hoc `/resume` inspection.
-
-### Current `pi-crew`
-
-- Primary runtime is child Pi process execution with durable `.crew/state` manifests and artifacts.
-- It has workflow/team abstractions, task graphs, worktree support, event log, mailbox, dashboard panes, render scheduler, notifications, and diagnostic exports.
-- It already has `live-session-runtime.ts`, but the current product surface centers on durable child-process workers rather than interactive in-process subagents.
-
-## Extension API Patterns Worth Reusing
-
-| Pattern | Reference source | Why it matters for current `pi-crew` |
-|---|---|---|
-| Owner-routed delivery by `sessionManager.getSessionId()` | `delivery-coordinator.ts` | Avoids sending async worker results to the wrong active session after `/resume`, `/new`, `/fork`, or multi-session use. |
-| Idle vs streaming delivery split | `subagent-messages.ts`, `delivery-coordinator.ts` | Prevents messages from getting stuck: idle sessions need `triggerTurn`; streaming sessions need `deliverAs: "steer"`. |
-| Deferred pending flush via `setTimeout(0)` | `delivery-coordinator.ts` | Avoids lost JSONL/custom-message persistence during resume before listeners reconnect. |
-| `extensionsOverride` filter | `bootstrap-session.ts` | Required for any in-process worker lane to prevent recursive subagent spawning. |
-| Fire-and-forget interactive response | `crew-respond.ts`, `crew-runtime.ts` | Lets parent stay responsive while an interactive worker continues in background. |
-| No duplicate done message | `crew-done.ts` | Avoids repeating the last subagent response during cleanup. |
-| Source-specific abort reasons | `crew-abort.ts`, `index.ts` shutdown handlers | Better diagnostics than generic "aborted by user". |
-| Emergency unrestricted abort command | `register-command.ts` | Useful escape hatch distinct from owner-scoped tool actions. |
-| Overflow tracker around SDK prompt | `overflow-recovery.ts` | Better UX for context overflow/compaction/retry in session-native workers. |
-
-## Key Differences / Non-Goals
-
-| Dimension | Reference `source/pi-crew` | Current `pi-crew` |
-|---|---|---|
-| Runtime | In-process `AgentSession` | Child Pi processes + durable orchestration |
-| State | In-memory map | Durable manifests/event logs/artifacts |
-| Scope | Flat subagent spawn/respond/done | Teams, workflows, task graph, worktrees |
-| Result UX | Pi steering/custom messages | Tool results, mailbox, dashboard, async status |
-| Interactive workers | Native | Not yet first-class |
-| Worktree isolation | None | First-class |
-| Replay/restart | Limited | Strong durable recovery |
-
-Do **not** replace the current runtime wholesale. Reference `source/pi-crew` lacks durable state, worktrees, workflow scheduling, artifact indexing, and the Phase 8 operator experience. Its best value is a narrower session-native execution lane and delivery correctness patterns.
-
-## Recommendations
-
-### P0 — Adopt Delivery Semantics for Async/Live Results
-
-Implement or adapt a small owner-routed delivery coordinator in current `pi-crew`:
-
-- Key by owner `sessionId`, not session file.
-- Queue pending messages when owner inactive.
-- On `session_start`, flush pending messages on next macrotask.
-- Use idle/streaming split:
-  - idle: `sendMessage(payload, { triggerTurn: true })`
-  - streaming: `sendMessage(payload, { deliverAs: "steer", triggerTurn: true })`
-- Keep current mailbox/event-log as durable source of truth; use delivery coordinator only for live UX.
-
-Likely target files:
-
-- `pi-crew/src/extension/register.ts`
-- `pi-crew/src/runtime/subagent-manager.ts`
-- `pi-crew/src/runtime/live-session-runtime.ts`
-- `pi-crew/src/extension/notification-router.ts`
-
-### P1 — Add Optional Session-Native Subagent Lane
-
-Build an opt-in lane on top of existing `live-session-runtime.ts` rather than changing the default child-process runtime:
-
-- `runtime.mode = "child-process" | "live-session" | "auto"` already exists conceptually; tighten semantics.
-- Use `SessionManager.newSession({ parentSession })` and `createAgentSession()` for in-process workers.
-- Filter `pi-crew` out of subagent resource loader extensions.
-- Persist minimal metadata to existing `.crew/state` so dashboards/recovery still work.
-
-This can reduce process startup overhead and blank console issues, while preserving child-process isolation as the safe default.
-
-### P1 — Introduce Interactive Worker Semantics
-
-Add first-class interactive subagents without disrupting teams:
-
-- New status: `waiting` for interactive background workers.
-- `crew_agent_respond` / `crew_agent_done` or extend existing `crew_agent_steer` semantics.
-- Fire-and-forget response: parent tool returns immediately; worker response arrives as mailbox/steering message.
-- `done` performs cleanup only; no duplicate response.
-
-Likely target files:
-
-- `pi-crew/src/runtime/crew-agent-records.ts`
-- `pi-crew/src/runtime/subagent-manager.ts`
-- `pi-crew/src/extension/registration/subagent-tools.ts`
-- `pi-crew/src/state/mailbox.ts`
-- `pi-crew/src/ui/dashboard-panes/agents-pane.ts`
-
-### P2 — Port Overflow Recovery Tracker for Live Sessions
-
-For session-native workers, wrap `AgentSession.prompt()` with an event tracker similar to `source/pi-crew/extension/runtime/overflow-recovery.ts`:
-
-- Track `compaction_start/end` and `auto_retry_start/end`.
-- Report recovered context overflow separately from hard failure.
-- Emit durable event-log records and dashboard health hints.
-
-This should not apply to child Pi workers directly; they already have process/transcript supervision.
-
-### P2 — Improve Abort Reason Taxonomy
-
-Adopt explicit abort source reasons across all worker paths:
-
-- tool-triggered abort
-- command-triggered emergency abort
-- session quit cleanup
-- session replacement detach/deactivate
-- watchdog timeout
-- stale heartbeat kill
-
-This improves diagnostics, notification routing, and Phase 9 reliability work.
-
-## Risks
-
-- In-process sessions reduce OS/process isolation; failures or leaks may affect the parent Pi process.
-- `extensionsOverride` is mandatory; missing it risks recursive subagent spawning.
-- Pi SDK internals may shift; keep this lane optional and covered by integration tests.
-- Delivery semantics must not bypass durable mailbox/event log; live messages are convenience, not source of truth.
-- Interactive workers can linger in memory; require TTL/status visibility and explicit cleanup.
-
-## Suggested Follow-Up Plan
-
-1. Write a focused design doc: `docs/research-session-native-runtime-plan.md`.
-2. Spike delivery coordinator only; no runtime swap.
-3. Add tests for idle/streaming/inactive owner delivery behavior.
-4. Add optional `live-session` worker lane behind config.
-5. Add interactive worker status/actions after live delivery is stable.
-
-## Research Artifacts
-
-- `D:/my/my_project/.crew/artifacts/team_20260429091311_8047706b/results/01_discover.txt`
-- `D:/my/my_project/.crew/artifacts/team_20260429091311_8047706b/results/02_explore-shard-1.txt`
-- `D:/my/my_project/.crew/artifacts/team_20260429091311_8047706b/results/03_explore-shard-2.txt`
-- `D:/my/my_project/.crew/artifacts/team_20260429091311_8047706b/results/04_explore-shard-3.txt`
-- `D:/my/my_project/.crew/artifacts/team_20260429091311_8047706b/batches/01_discover+02_explore-shard-1+03_explore-shard-2+04_explore-shard-3.md`