pi-crew 0.1.49 → 0.2.0

package/docs/research/CAVEMAN-DEEP-RESEARCH.md

@@ -1,281 +0,0 @@
-# Caveman Deep Research — Agent Communication Optimization
-
-> Source: `source/caveman/` (github.com/JuliusBrussee/caveman)
-> Date: 2026-05-08
-> Purpose: Apply caveman patterns to optimize pi-crew inter-agent communication
-
----
-
-## 1. Executive Summary
-
-Caveman là một hệ thống **token compression** cho AI coding agents. Core insight: **LLM output trung bình 65-75% là filler** (articles, hedging, pleasantries). Bỏ filler → giảm token, tăng tốc, giảm cost, **không mất accuracy** (thậm chí tăng 26% theo paper arXiv:2604.00025).
-
-**Áp dụng cho pi-crew**: Worker output được inject vào main context của Pi parent. Nếu worker output dùng caveman-style → main context live lâu hơn, nhiều task hơn per session.
-
----
-
-## 2. Architecture Overview
-
-```
-caveman/
-├── skills/           # Behavior definition (SKILL.md)
-│   ├── caveman/      # Core: intensity levels, rules
-│   ├── cavecrew/     # Decision guide for delegation
-│   ├── caveman-commit/   # Terse commit messages
-│   ├── caveman-review/   # One-line PR reviews
-│   ├── caveman-help/     # Quick-reference card
-│   ├── caveman-stats/    # Token usage tracker
-│   └── compress/     # Memory file compression
-├── agents/           # Subagent definitions
-│   ├── cavecrew-investigator.md  # Read-only locator (haiku)
-│   ├── cavecrew-builder.md       # 1-2 file surgical editor
-│   └── cavecrew-reviewer.md      # Diff reviewer (haiku)
-├── hooks/            # Claude Code integration
-│   ├── caveman-activate.js       # SessionStart: inject rules
-│   ├── caveman-mode-tracker.js   # Per-turn reinforcement
-│   ├── caveman-config.js         # Shared config + symlink-safe I/O
-│   └── caveman-stats.js          # Lifetime token tracking
-├── mcp-servers/
-│   └── caveman-shrink/           # MCP middleware proxy
-├── caveman-compress/             # File compression tool
-│   └── scripts/
-│       ├── compress.py   # Orchestrator
-│       ├── validate.py   # Structural preservation validator
-│       └── detect.py     # File type detection
-├── evals/            # Three-arm eval harness
-└── benchmarks/       # Real API token counts
-```
-
----
-
-## 3. Core Patterns Applicable to pi-crew
-
-### 3.1 Structured Output Contracts (KEY INSIGHT)
-
-Caveman's biggest innovation is not the compression itself — it's the **output contracts**:
-
-**investigator**: `path:line — symbol — ≤6 word note`
-**builder**: `path:line-range — change ≤10 words. verified: re-read OK.`
-**reviewer**: `path:line: emoji severity: problem. fix.`
-
-These are **machine-parseable** — main thread can grep with regex, no ambiguity.
-
-**pi-crew application**: Worker prompt templates should include structured output contracts:
-```
-# Output Contract
-Your response MUST follow this format:
-<artifact_path>:<line_range> — <≤10 word change summary>
-verified: <re-read OK | mismatch @ path:line>
-```
-
-### 3.2 Context Budget Awareness
-
-Caveman's core thesis: **subagent tool-results get injected into main context verbatim**. Every token a subagent emits is a token the main agent can't use later.
-
-Quantified impact:
-- Vanilla `Explore` subagent: ~2000 tokens per result
-- `cavecrew-investigator`: ~700 tokens per result
-- Over 20 delegations: **26,000 tokens saved** = entire context window of a small model
-
-**pi-crew application**: Worker output gets read back by Pi parent via `readFile(artifactPath)`. If workers emit caveman-style output → Pi parent can process more tasks per session before context exhaustion.
-
-### 3.3 Intensity Levels
-
-| Level | Token Savings | When to Use |
-|-------|--------------|-------------|
-| lite | ~40% | User-facing summaries, final reports |
-| full | ~65% | Inter-agent communication (default) |
-| ultra | ~75% | Internal worker → coordinator messages |
-
-**pi-crew application**: Add `outputStyle` to worker prompts:
-- explorer → ultra (only paths/symbols needed)
-- executor → full (some explanation needed for verification)
-- reviewer → full (findings must be clear)
-- writer → lite (user reads output directly)
-
-### 3.4 Auto-Clarity Rule
-
-Caveman drops compression for:
-- Security warnings
-- Irreversible action confirmations
-- Multi-step sequences with ambiguous ordering
-- User confusion / repeated questions
-
-**pi-crew application**: Worker prompts should include auto-clarity override:
-```
-Drop compression for: security findings, destructive operations,
-ambiguous multi-step instructions. Resume compression after.
-```
-
-### 3.5 MCP Proxy Compression (caveman-shrink)
-
-`caveman-shrink` wraps any MCP server, compresses `description` fields in `tools/list` responses:
-
-```
-Before: "This tool allows you to search for files in the filesystem..."
-After:  "Search files in filesystem."
-```
-
-**pi-crew application**: pi-crew's MCP proxy (`mcp-proxy.ts`) could compress tool descriptions before passing to workers, reducing input token cost per tool call.
-
----
-
-## 4. Compression Techniques
-
-### 4.1 Protected Segments (from compress.js)
-
-```javascript
-const PROTECTED_PATTERNS = [
-  /```[\s\S]*?```/g,           // fenced code blocks
-  /`[^`\n]+`/g,                // inline code
-  /\bhttps?:\/\/\S+/gi,        // URLs
-  /\b[\w.-]*[\/\\][\w.\/\\-]+/g, // paths
-  /\b[A-Z][A-Za-z0-9]*(?:_[A-Z][A-Za-z0-9]*)+\b/g, // CONST_CASE
-  /\b\w+\.\w+(?:\.\w+)*\(\)?/g,   // dotted.method()
-  /[A-Za-z_][A-Za-z0-9_]*\s*\([^)]*\)/g, // function calls
-  /\b\d+\.\d+\.\d+\b/g,       // version numbers
-];
-```
-
-Process: Replace protected segments with sentinels → compress remaining prose → restore sentinels.
-
-### 4.2 Prose Compression Rules
-
-```javascript
-// Remove categories:
-FILLERS: just, really, basically, actually, simply, quite, very, essentially, literally
-PLEASANTRIES: please, kindly, thank you, thanks, sure, certainly, of course
-HEDGES: perhaps, maybe, might, could potentially, would like to, I think
-LEADERS: I'll, I will, I can, you can, we will, let me, let's
-ARTICLES: a, an, the (before lowercase words)
-
-// Pattern: [thing] [action] [reason]. [next step].
-```
-
-### 4.3 Validation (from validate.py)
-
-After compression, validate:
-- Heading count and order preserved
-- Code blocks byte-identical
-- URLs preserved exactly
-- File paths preserved
-- Inline code preserved
-- Bullet structure maintained (±15% tolerance)
-
-**pi-crew application**: When workers produce structured output, validate format before injecting into parent context. Bad format → retry with targeted fix (caveman's "cherry-pick fix" pattern).
-
----
-
-## 5. Delegation Decision Matrix (from cavecrew)
-
-| Task | Use | Why |
-|------|-----|-----|
-| "Where is X defined" | investigator | Read-only, structured paths |
-| Same + suggestions | vanilla Explore | Need prose |
-| 1-2 file surgical edit | builder | Bounded scope |
-| 3+ file refactor | main thread | Builder refuses |
-| Review diff for bugs | reviewer | One-line findings |
-| Deep code review | vanilla Code Reviewer | Need rationale |
-
-**pi-crew application**: Planner agent should use similar decision matrix when assigning tasks to workers. Key rule: **if output will be consumed by another agent, compress it. If a human reads it, use normal prose.**
-
----
-
-## 6. Security Patterns (from caveman-config.js)
-
-### 6.1 Symlink-Safe File I/O
-
-```javascript
-// Flag file write pattern:
-1. Check parent dir is not symlink (or resolve + verify ownership)
-2. Check target file is not symlink
-3. Write to temp file with O_NOFOLLOW | O_EXCL
-4. fchmod 0600
-5. rename temp → target (atomic)
-```
-
-**pi-crew application**: pi-crew's `atomic-write.ts` should adopt similar symlink guards, especially for `agents.json` (the file that caused the ghost agent bug).
-
-### 6.2 Sensitive File Detection (from compress.py)
-
-```python
-SENSITIVE_BASENAMES = .env, .netrc, credentials, secrets, passwords, id_rsa, *.pem, *.key
-SENSITIVE_DIRS = .ssh, .aws, .gnupg, .kube, .docker
-SENSITIVE_TOKENS = secret, credential, password, apikey, token, privatekey
-```
-
-**pi-crew application**: Workers should refuse to read/compress files matching these patterns. Add to worker prompt constraints.
-
----
-
-## 7. Eval Methodology
-
-### Three-Arm Harness
-
-| Arm | System Prompt | Purpose |
-|-----|--------------|---------|
-| `__baseline__` | none | Raw model output |
-| `__terse__` | "Answer concisely." | Control for generic terseness |
-| `<skill>` | "Answer concisely." + SKILL.md | Isolated skill contribution |
-
-**Honest delta = skill vs terse, NOT skill vs baseline.**
-
-**pi-crew application**: When measuring worker efficiency, compare against "answer concisely" control, not against verbose baseline. This avoids claiming compression wins that are just generic terseness.
-
----
-
-## 8. Specific pi-crew Integration Plan
-
-### Phase 1: Structured Output Contracts ✅ DONE
-
-Commit `a335dfc`. Implemented `buildOutputContract(role)` in `live-session-runtime.ts`.
-Explorer, executor, reviewer, security-reviewer, verifier, writer all have structured format templates.
-
-### Phase 2: Prose Compression in Worker Prompts ✅ DONE
-
-Commit `a335dfc`. Implemented `buildCommunicationStyle(role)` with lite/full/ultra levels.
-Explorer = ultra, writer = lite, all others = full.
-
-### Phase 3: Tool Description Compression ✅ DONE
-
-Commit `pending`. Created `prose-compressor.ts` — pure TypeScript implementation of caveman's compress.js.
-Compressed custom tool descriptions (submit_result, irc).
-SDK-managed tool descriptions need Pi SDK support for mutation (documented as `compressSessionToolDescriptions` stub).
-
-### Phase 4: Output Validation ✅ DONE
-
-Created `output-validator.ts` with:
-- `validateWorkerOutput(role, output)` — checks format + structural preservation
-- `parseReviewerFindings(output)` — extracts structured findings from reviewer output
-- `parseExplorerResults(output)` — extracts structured results from explorer output
-- `validateCompressionPreservation(original, compressed)` — checks code blocks, URLs, inline code, headings
-
-### Phase 5: Intensity by Role ✅ DONE
-
-Commit `a335dfc`. `ROLE_INTENSITY` map in `live-session-runtime.ts`.
-
----
-
-## 9. Expected Impact
-
-| Metric | Before | After | Improvement |
-|--------|--------|-------|-------------|
-| Avg worker output tokens | ~800 | ~300 | **62%** |
-| Parent context capacity (tasks/session) | ~15 | ~30 | **2x** |
-| Tool description tokens (input) | ~200/tool | ~80/tool | **60%** |
-| Review finding parse accuracy | ~70% | ~95% | **+25%** |
-
----
-
-## 10. Key Takeaways
-
-1. **Output contracts > compression** — structured format is the real win, not shorter prose ✅
-2. **Context budget is finite** — every worker token = one less parent token ✅
-3. **Validate, don't trust** — compress then validate structural preservation ✅
-4. **Auto-clarity > always-compress** — security/destructive = normal English ✅
-5. **Three-arm eval** — measure against "be concise" control, not verbose baseline 📋
-6. **Symlink-safe I/O** — protect predictable file paths from symlink attacks ✅
-7. **Sensitive file denylist** — never ship credentials to third-party APIs ✅
-8. **Role-based intensity** — explorer gets ultra, writer gets lite, executor gets full ✅
-9. **Tool description compression** — compress descriptions to reduce input tokens ✅ (SDK support pending)
-10. **Parse structured output** — extract findings/results from worker output ✅

package/docs/research/COMPARISON_OH_MY_PI_VS_PI_CREW.md

@@ -1,264 +0,0 @@
-# ⚖️ So sánh kiến trúc: oh-my-pi vs pi-crew
-
-> Dựa trên deep research cả hai codebase (oh-my-pi v14.7.3 + pi-crew HEAD)
-
----
-
-## 1. Tổng quan kiến trúc
-
-```
-                        oh-my-pi                              pi-crew
-┌──────────────────────────────────────┐  ┌──────────────────────────────────────┐
-│          Main Process                │  │       Pi Parent Process              │
-│                                      │  │                                      │
-│  ┌────────────────────────────────┐  │  │  Pi CLI (coding agent)               │
-│  │  AgentSession (in-process)     │  │  │    │                                 │
-│  │  ├─ TaskTool → createSession() │  │  │    │ team tool → team-runner.ts       │
-│  │  │   ├─ AgentSession #1        │  │  │    │   ├─ task-runner.ts             │
-│  │  │   ├─ AgentSession #2        │  │  │    │   │   ├─ child-pi.ts → spawn() │
-│  │  │   └─ AgentSession #N        │  │  │    │   │   │   ├─ Pi child #1     │
-│  │  │                             │  │  │    │   │   │   ├─ Pi child #2     │
-│  │  ├─ EventBus (in-process)      │  │  │    │   │   │   └─ Pi child #N     │
-│  │  ├─ AgentRegistry (global)     │  │  │    │   │                              │
-│  │  └─ SessionObserverRegistry    │  │  │    │   ├─ state-store (files)        │
-│  └────────────────────────────────┘  │  │    │   ├─ manifest.json              │
-│                                      │  │    │   ├─ tasks.json                 │
-│  Tất cả trong 1 process              │  │    │   ├─ events.jsonl               │
-│  → Không IPC, không serialization    │  │    │   └─ artifacts/                 │
-│  → Direct object references          │  │    │                                  │
-│  → Real-time event streaming         │  │    │ File-based coordination           │
-└──────────────────────────────────────┘  └──────────────────────────────────────┘
-```
-
----
-
-## 2. So sánh chi tiết từng subsystem
-
-### 2.1 Execution Model
-
-| | oh-my-pi | pi-crew |
-|---|---------|---------|
-| **Model** | In-process `AgentSession` | Child process `spawn("pi", ...)` |
-| **Isolation** | Shared memory, shared event loop | Process-isolated, independent event loop |
-| **Startup time** | ~ms (just object creation) | ~seconds (new Pi process boot) |
-| **Communication** | Direct method calls | stdout/stderr IPC + file artifacts |
-| **Memory** | Shared heap — agents see each other | Separate heaps — no shared state |
-| **Failure blast radius** | 1 crashed agent → potential process crash | 1 crashed child → parent unaffected |
-| **Concurrency** | `Semaphore` + `mapWithConcurrencyLimit` | `mapConcurrent` + `resolveBatchConcurrency` |
-| **Model fallback** | Per-agent `model[]` patterns | `buildConfiguredModelRouting` with candidates loop |
-
-**pi-crew advantage**: Process isolation — crashed worker không ảnh hưởng parent.
-**oh-my-pi advantage**: Shared memory — zero IPC overhead, direct event streaming, IRC messaging.
-
-### 2.2 Subagent Lifecycle
-
-```
-oh-my-pi:                           pi-crew:
-pending → running → completed       queued → running → completed
-                    ↘ failed                         ↘ failed
-                    ↘ aborted                         ↘ cancelled
-                                                      ↘ waiting (mailbox)
-                                                      ↘ skipped
-```
-
-| | oh-my-pi | pi-crew |
-|---|---------|---------|
-| **Entry** | `TaskTool.execute()` | `team tool run` → `team-runner.ts` |
-| **Discovery** | `discoverAgents()` — bundled + .md files | `discoverAgents()` — agents/ dir + .md files |
-| **Definition format** | YAML frontmatter in .md | YAML frontmatter in .md |
-| **Output submission** | **`yield` tool** (enforced, 3 retries) | **exit code + stdout** (parsed post-hoc) |
-| **Recursion control** | `maxRecursionDepth` + `spawns[]` | `maxTaskDepth` env var |
-| **Adaptive planning** | N/A | **Adaptive plan injection** — planner dynamically creates tasks |
-| **Retry** | N/A (yield reminder only) | `executeWithRetry` — configurable retry policy |
-| **Policy engine** | N/A | `evaluateCrewPolicy` + recovery ledger |
-| **Plan approval** | N/A | `planApproval` flow for implementation workflow |
-| **Effectiveness guard** | N/A | `evaluateRunEffectiveness` — severity levels |
-
-**pi-crew advantages**: Retry policy, adaptive planning, policy engine, plan approval, effectiveness guards.
-**oh-my-pi advantages**: Yield enforcement (structured output), spawns[] recursion control.
-
-### 2.3 Inter-Subagent Communication
-
-| | oh-my-pi | pi-crew |
-|---|---------|---------|
-| **Primary mechanism** | **IRC tool** — peer-to-peer messaging | **Mailbox** — async message queue |
-| **Registry** | `AgentRegistry.global()` — process singleton | `manifest.json` + `crew-agent-records.json` |
-| **Addressing** | Agent ID (`"0-Main"`, `"3-explore-abc"`) | Task ID (`"01_discover"`, `"02_plan"`) |
-| **Reply mechanism** | `respondAsBackground()` — ephemeral side-channel | `respond` team tool action |
-| **Anti-deadlock** | Side-channel doesn't block recipient's main loop | N/A — mailbox is fire-and-forget |
-| **Broadcast** | `irc({ op: "send", to: "all" })` | No broadcast |
-| **Visibility** | `listVisibleTo()` — all running/idle agents | `status` team tool — shows all tasks |
-| **Event channels** | 3 dedicated channels (event, progress, lifecycle) | 1 `task.progress` event (coalesced) |
-| **Steering** | `agent.steer()` — inject message mid-turn | `cancel` + `respond` team tool actions |
-| **Context sharing** | `context.md` file + `contextFiles[]` | `dependencyContext` + `task-output-context.ts` |
-
-**oh-my-pi advantages**: Real-time IRC, anti-deadlock side-channel, broadcast, steering mid-turn.
-**pi-crew advantages**: Async mailbox (persists to disk), dependency context (auto-collects upstream outputs), more coordination patterns via team tool.
-
-### 2.4 Progress Tracking
-
-| | oh-my-pi | pi-crew |
-|---|---------|---------|
-| **Event source** | `AgentEvent` subscription (in-process) | JSON lines from child stdout + transcript.jsonl |
-| **Debounce** | 150ms coalescing | 500ms agent record + 1000ms progress event |
-| **Tracked data** | toolName, toolArgs, tokens, recentOutput (8 lines), intent | toolName, toolCount, tokens, recentOutput (20 lines), usage |
-| **Heartbeat** | N/A (shared process = instant status) | `worker-heartbeat.ts` — file-based heartbeat |
-| **Attention detection** | N/A | `agent-control.ts` — `needs_attention`, `long_running`, consecutive failures |
-| **Crash recovery** | N/A | `crash-recovery.ts`, `stale-reconciler.ts`, `overflow-recovery.ts` |
-| **Deadletter** | N/A | `deadletter.ts` — tracks permanently failed tasks |
-
-**oh-my-pi advantages**: Real-time events (no file polling needed), 150ms fast updates.
-**pi-crew advantages**: Crash recovery, stale reconciliation, attention detection, deadletter — much more robust for unreliable environments.
-
-### 2.5 UI Rendering
-
-| | oh-my-pi | pi-crew |
-|---|---------|---------|
-| **Main display** | `SessionObserverOverlay` — full transcript viewer | `RunDashboard` — multi-pane dashboard |
-| **Progress bar** | `statusLine` with subagent count | `powerbar-publisher.ts` — segment-based |
-| **Transcript** | Incremental JSONL reading, expand/collapse per entry | `transcript-viewer.ts` — syntax-highlighted, diff rendering |
-| **Agent config UI** | `AgentDashboard` (1120 lines) — two-column agent manager | N/A (config via YAML files) |
-| **Dashboard panes** | N/A (single overlay) | 7 panes: agents, progress, mailbox, health, metrics, capability, transcript |
-| **Anti-flicker** | 150ms progress coalesce, viewport-only render | `file-coalescer.ts` (200ms TTL), `render-scheduler.ts` |
-| **Snapshot cache** | N/A (in-process = instant) | `run-snapshot-cache.ts` (777 lines) — file mtime-based cache |
-| **Live streaming** | `message_update` events (text_delta) in real-time | JSON stdout line parsing (batched) |
-
-**oh-my-pi advantages**: Real-time streaming, entry-based expand/collapse, agent configuration UI.
-**pi-crew advantages**: Richer dashboard (7 panes), syntax highlighting, diff rendering, snapshot caching for multiple runs.
-
-### 2.6 Tool Access Control
-
-| | oh-my-pi | pi-crew |
-|---|---------|---------|
-| **Mechanism** | `agent.tools[]` in frontmatter → passed to `createAgentSession` | `permissionForRole()` → read_only vs read_write |
-| **Granularity** | Per-agent tool whitelist | Per-role permission level |
-| **MCP proxy** | `createMCPProxyTools()` — reuse parent's connections | N/A |
-| **Plan mode** | Restrict to `["read", "search", "find", "lsp", "web_search"]` | `permissionForRole("planner") === "read_only"` |
-| **LoadMode** | `"essential"` vs `"discoverable"` per tool | N/A (just added `toolGuidanceBlock`) |
-| **Recursion tool** | Auto-add `"task"` tool when `spawns` defined | N/A (no subagent spawning from workers) |
-
-### 2.7 Isolation & Merge
-
-| | oh-my-pi | pi-crew |
-|---|---------|---------|
-| **Isolation modes** | worktree, fuse-overlay, fuse-projfs | worktree only |
-| **Merge modes** | patch, branch | patch (auto-captured) |
-| **Commit style** | AI-generated or simple | N/A |
-| **Nested repos** | `NestedRepoPatch` support | N/A |
-
----
-
-## 3. Feature Matrix
-
-| Feature | oh-my-pi | pi-crew |
-|---------|:--------:|:-------:|
-| In-process execution | ✅ | ❌ (child process) |
-| Process isolation | ❌ | ✅ |
-| Yield tool enforcement | ✅ | ❌ |
-| IRC messaging | ✅ | ❌ (mailbox only) |
-| Broadcast messaging | ✅ | ❌ |
-| Steering mid-turn | ✅ | ❌ (cancel/respond only) |
-| Anti-deadlock side-channel | ✅ | ❌ |
-| Real-time event streaming | ✅ | ❌ (file-based) |
-| Adaptive planning | ❌ | ✅ |
-| Retry policy | ❌ | ✅ |
-| Policy engine | ❌ | ✅ |
-| Plan approval flow | ❌ | ✅ |
-| Effectiveness guard | ❌ | ✅ |
-| Crash recovery | ❌ | ✅ |
-| Stale reconciliation | ❌ | ✅ |
-| Deadletter tracking | ❌ | ✅ |
-| Attention detection | ❌ | ✅ |
-| Mailbox (async) | ❌ | ✅ |
-| Dependency context | ❌ | ✅ |
-| Multi-run dashboard | ❌ | ✅ |
-| Syntax highlighting | ❌ | ✅ |
-| Diff rendering | ❌ | ✅ |
-| Snapshot caching | ❌ | ✅ |
-| Agent configuration UI | ✅ | ❌ |
-| MCP proxy tools | ✅ | ❌ |
-| Worktree isolation | ✅ | ✅ |
-| FUSE/ProjFS isolation | ✅ | ❌ |
-| Branch-based merge | ✅ | ❌ |
-
----
-
-## 4. Phân tích gap — pi-crew thiếu gì
-
-### Gap 1: Real-time Event Streaming (HIGH)
-- **oh-my-pi**: In-process EventBus → events arrive in <1ms
-- **pi-crew**: File-based (write manifest → poll) → 500-1000ms latency
-- **Impact**: UI flickers, feels "chập chờn", delayed progress updates
-- **Solution path**: WebSocket/pipe from child Pi → parent, or use Pi's JSON event stream directly
-
-### Gap 2: Structured Output (MEDIUM)
-- **oh-my-pi**: `yield` tool enforces structured output with JTD schema
-- **pi-crew**: Parse stdout + transcript post-hoc
-- **Impact**: Fragile output parsing, no schema validation
-- **Solution path**: Add output schema support to task packets, or use exit code conventions
-
-### Gap 3: Inter-Worker Communication (MEDIUM)
-- **oh-my-pi**: IRC tool + AgentRegistry + side-channel
-- **pi-crew**: Mailbox (fire-and-forget) + dependency context (read-only)
-- **Impact**: Workers can't coordinate in real-time
-- **Solution path**: Enhanced mailbox with reply support, or IPC bridge
-
-### Gap 4: Steering/Cancellation Granularity (LOW)
-- **oh-my-pi**: `steer()` injects messages mid-turn, `interruptMode: "immediate"`
-- **pi-crew**: `cancel` kills child process, `respond` adds to mailbox
-- **Impact**: Can't course-correct a running worker without killing it
-- **Solution path**: Pi's native `steer` support (if exposed via CLI)
-
-### Gap 5: Agent Configuration UI (LOW)
-- **oh-my-pi**: Full `AgentDashboard` — enable/disable, model override, AI agent creation
-- **pi-crew**: Edit YAML files manually
-- **Impact**: Poor UX for agent management
-- **Solution path**: Build a similar dashboard component in pi-crew
-
----
-
-## 5. Phân tích gap — oh-my-pi thiếu gì (pi-crew có)
-
-### pi-crew Advantage 1: Process Isolation
-Crashed worker → parent unaffected. Critical for production reliability.
-
-### pi-crew Advantage 2: Adaptive Planning
-`implementation` workflow dynamically injects tasks based on planner output. No equivalent in oh-my-pi.
-
-### pi-crew Advantage 3: Robustness Layer
-- Retry policy with backoff
-- Crash recovery + stale reconciliation
-- Deadletter tracking
-- Effectiveness guard with severity levels
-- Policy engine with block/escalate/notify
-
-### pi-crew Advantage 4: Dependency Context
-Auto-collects upstream task outputs and feeds them to downstream tasks. oh-my-pi only shares `context.md`.
-
-### pi-crew Advantage 5: Rich Dashboard
-7 specialized panes vs oh-my-pi's single overlay. Better for monitoring multiple parallel runs.
-
----
-
-## 6. Kết luận
-
-| Aspect | Winner | Reason |
-|--------|--------|--------|
-| **Execution speed** | oh-my-pi | In-process, zero IPC |
-| **Reliability** | pi-crew | Process isolation + crash recovery |
-| **Communication** | oh-my-pi | IRC + side-channel + steering |
-| **Coordination** | pi-crew | Adaptive planning + dependency context |
-| **UI richness** | pi-crew | 7 dashboard panes + syntax highlighting |
-| **UI responsiveness** | oh-my-pi | Real-time events + 150ms coalescing |
-| **Robustness** | pi-crew | Retry + deadletter + effectiveness guard |
-| **Tool control** | oh-my-pi | Per-agent whitelist + MCP proxy |
-| **Configuration UX** | oh-my-pi | Agent dashboard with AI creation |
-
-**Tóm lại**: pi-crew mạnh về **reliability và coordination**, yếu về **real-time responsiveness và inter-worker communication**. oh-my-pi mạnh về **speed và real-time**, yếu về **robustness và fault tolerance**.
-
-**Priority improvements cho pi-crew**:
-1. 🔴 Real-time event streaming → giảm UI flicker
-2. 🟡 Structured output enforcement → giảm parsing fragility
-3. 🟡 Inter-worker communication → tăng coordination capability
-4. 🟢 Agent configuration UI → tăng UX
-5. 🟢 Steering granularity → tăng control fidelity