pi-crew 0.9.50 → 0.9.52

package/docs/coding-agent-optimization.md

@@ -1,268 +0,0 @@
-# coding-agent Changes: Optimization Opportunities for pi-crew
-
-**Date:** 2026-05-28  
-**Source:** Direct analysis of `packages/coding-agent/` commits (133 commits in May 2026)  
-**Focus:** Changes that can help pi-crew work better, faster, or more reliably
-
----
-
-## Executive Summary
-
-**133 coding-agent commits in May 2026.** Many are internal fixes, but several directly impact pi-crew's child-process spawning and RPC communication. This doc focuses on actionable optimization opportunities.
-
----
-
-## 1. HIGH IMPACT — Direct pi-crew Benefit
-
-### A. RPC Backpressure Handling (`d0d1d8ed`, `ce0e801d`)
-
-**Problem:** Large bash output could block RPC stdout, causing backpressure and hangs.
-
-**Solution:** pi now uses async stdout writes with backpressure signaling:
-
-```typescript
-// rpc-mode.ts
-const output = async (obj: ...): Promise<void> => {
-  await writeRawStdout(serializeJsonLine(obj));
-};
-```
-
-**pi-crew relevance:** `child-pi.ts` already has backpressure handling (line ~560 `stdout.resume()` / `stdout.pause()`). **This fix improves the underlying child process's stdout handling.** When pi-crew spawns a child Pi, that child now handles large output better.
-
-**Optimization opportunity:** Consider adding explicit backpressure acknowledgment in `child-pi.ts` — currently it uses `stdout.pause()` but doesn't explicitly signal to pi when it's ready to resume. pi now handles this internally.
-
-### B. Child Process Exit Handling (`e007fcd0`)
-
-**Problem:** When a child process exits unexpectedly, pending RPC requests would hang forever.
-
-**Solution:** RpcClient now tracks child process exit and rejects pending requests:
-
-```typescript
-// rpc-client.ts
-childProcess.once("exit", (code, signal) => {
-  const error = this.createProcessExitError(code, signal);
-  this.exitError = error;
-  this.rejectPendingRequests(error);
-});
-```
-
-**pi-crew relevance:** **Critical.** pi-crew's `child-pi.ts` spawns child Pi processes. If the child exits unexpectedly (OOM, crash, SIGKILL), pi-crew should:
-1. Capture the exit code/signal
-2. Reject any pending operations
-3. Log the error with stderr context
-
-**Current gap:** `child-pi.ts` captures exit codes but doesn't propagate stderr context when rejecting pending work.
-
-### C. Bash Output Truncation Fix (`f9530678`)
-
-**Problem:** Bash truncation counted lines incorrectly when output ended with a newline.
-
-**Fix:** `OutputAccumulator` now correctly tracks `completedLines` vs `totalLines`:
-
-```typescript
-// output-accumulator.ts
-this.completedLines = 0;
-this.totalLines = 0;
-this.hasOpenLine = false;
-// ...
-const lines = splitLinesForCounting(content);
-// If content ends with \n, pop the empty final line
-```
-
-**pi-crew relevance:** pi-crew shows task output in `team action='status'`. If the output is truncated, the line count is now accurate. **No code change needed** — this is internal to pi.
-
-### D. Session ID Naming (`52dc08c1`)
-
-**New feature:** Users can specify explicit session IDs with `--session-id <name>`.
-
-**pi-crew relevance:** Could enable named sessions for:
-- `team action='run'` with `inheritContext: true` → pass named session instead of JSON
-- Debugging: label sessions by task/team
-- Cross-reference: match pi-crew run IDs to pi session IDs
-
-**Implementation:** `assertValidSessionId(id)` validates format (`^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$`).
-
-### E. Compact Read Output (`373bd128`)
-
-**New feature:** Large file reads are collapsed by default, with "Show more" toggle.
-
-**pi-crew relevance:** Tasks that read large files now show cleaner output in logs/UI. **No code change needed.**
-
----
-
-## 2. MEDIUM IMPACT — Optimization Opportunities
-
-### A. `excludeFromContext` Flag (`61babc24`)
-
-**New RPC command:**
-```typescript
-{ type: "bash", command: "ls -la", excludeFromContext: true }
-```
-
-When `excludeFromContext: true`, the bash command output is **not included in the agent's context**. This prevents noisy commands (e.g., `ls -la` in large directories) from consuming context tokens.
-
-**pi-crew opportunity:** pi-crew could add a `--no-context` flag to `team action='run'` that maps to `excludeFromContext: true` for certain agent operations. Currently, all agent operations contribute to context.
-
-**Implementation would be in:** `child-pi.ts` → when spawning, pass `excludeFromContext: true` for non-essential commands.
-
-### B. Async Tool Operations (`e9146a5f`, `ba09f1c9`)
-
-**Change:** Tools (read, write, edit) now use async operations instead of sync.
-
-**pi-crew relevance:** Tasks that run many file operations will be faster (non-blocking I/O). **No code change needed.**
-
-### C. Edit Tool Unified Patch (`60a55a23`)
-
-**New feature:** Edit tool results now include a `patch` field (standard unified diff):
-
-```typescript
-// edit.ts
-export interface EditToolDetails {
-  diff: string;         // Display-oriented diff
-  patch: string;        // Standard unified patch
-  firstChangedLine?: number;
-}
-```
-
-**pi-crew opportunity:** `team action='status'` could show the unified patch instead of display diff, enabling:
-- More precise change tracking
-- `git apply` compatibility for rollback
-- Better diff visualization in logs
-
-**Implementation would be in:** `task-runner.ts` → capture `toolResult.details.patch` instead of `toolResult.details.diff`.
-
-### D. HTTP Idle Timeout (`849f9d9c`)
-
-**Change:** Coding-agent now configures HTTP idle timeout for network requests.
-
-**pi-crew relevance:** When pi-crew tasks make HTTP requests (e.g., calling external APIs), the idle timeout prevents hanging connections. **No code change needed** — this is internal to pi's HTTP client.
-
-### E. Retry Marking for Agent End Events (`c685b273`)
-
-**Change:** When an agent retries a turn, the `agent_end` event is now marked as a retry.
-
-**pi-crew relevance:** `team action='status'` could show retry count. Currently, pi-crew tracks task retries via `run_recovery` hook but doesn't surface retry reasons.
-
----
-
-## 3. LOW IMPACT — Nice to Know
-
-### A. Theme Detection (`f4f0ac7a`, `088987b2`)
-
-Update notes shown on startup. Themes listed by content name.
-
-**No action needed.**
-
-### B. OpenCode Session Headers (`42379a37`)
-
-Session headers for OpenCode provider (Qwen models).
-
-**No action needed.**
-
-### C. Clipboard Sidecar (`3f89350c`)
-
-Bun binaries now include clipboard helper.
-
-**No action needed.**
-
-### D. Path Handling Fix (`c100620b`)
-
-Corrected path resolution for pattern matching.
-
-**No action needed.**
-
----
-
-## 4. Optimization Roadmap (Priority Order)
-
-### Priority 1: Child Process Exit Handling
-
-**Gap:** `child-pi.ts` captures exit code but doesn't reject pending work with stderr context.
-
-**Current code:** `child-pi.ts` line ~635
-```typescript
-const wasGraceAborted = softLimitReached && turnCount >= ...
-```
-
-**Missing:** When child exits unexpectedly, propagate `exitError` to any pending operations.
-
-**Fix:**
-```typescript
-// In child-pi.ts, handle unexpected exit
-childProcess.once("exit", (code, signal) => {
-  const exitError = new Error(
-    `Agent process exited (code=${code} signal=${signal}). Stderr: ${stderr}`
-  );
-  // Reject any pending operations
-  // Log exitError to event log
-});
-```
-
-### Priority 2: `excludeFromContext` Integration
-
-**New capability in pi:** Commands can opt out of context.
-
-**pi-crew opportunity:** Add config flag to `team action='run'`:
-```
-team action='run' goal='...' exclude-context-bash=true
-```
-
-This would mark intermediate/staging bash commands as `excludeFromContext: true`.
-
-**Implementation:**
-1. Add `excludeContextBash?: boolean` to `PiTeamsAutonomousConfig`
-2. In `child-pi.ts`, wrap commands with `excludeFromContext` flag
-
-### Priority 3: Edit Tool Patch Capture
-
-**Current:** `task-runner.ts` captures `toolResult.details.diff` for reporting.
-
-**Opportunity:** Capture `toolResult.details.patch` for:
-- Rollback capability (`git apply` patch)
-- Precise change tracking
-- Better visualization
-
-**Implementation:** Change `task-runner.ts` line ~1114 to read `details.patch` instead of `details.diff`.
-
-### Priority 4: Session ID Alignment
-
-**New capability:** `--session-id <name>` for explicit session naming.
-
-**pi-crew opportunity:** Align pi session IDs with pi-crew run IDs:
-```
-pi --session-id "crew-run-{runId}"
-```
-
-This would enable:
-- Easy cross-reference between pi sessions and pi-crew runs
-- Named resume: `pi --session crew-run-abc` resumes a specific run
-- Better debugging in `.crew/sessions/`
-
----
-
-## 5. Key Files to Watch
-
-| File | Significance |
-|------|-------------|
-| `packages/coding-agent/src/modes/rpc/rpc-mode.ts` | RPC protocol — pi-crew's child communicates via this |
-| `packages/coding-agent/src/modes/rpc/rpc-client.ts` | Client that handles child process lifecycle |
-| `packages/coding-agent/src/core/session-manager.ts` | Session naming, fork, resume |
-| `packages/coding-agent/src/core/tools/bash.ts` | Bash execution with backpressure |
-| `packages/coding-agent/src/core/tools/output-accumulator.ts` | Output truncation logic |
-| `packages/coding-agent/src/core/tools/edit.ts` | Edit tool with unified patch |
-
----
-
-## 6. Summary
-
-| Category | Finding | Action |
-|----------|---------|--------|
-| **Critical** | Child exit handling improved | Verify `child-pi.ts` rejects pending work on unexpected exit |
-| **Opportunity** | `excludeFromContext` flag | Add to `team action='run'` config |
-| **Opportunity** | Edit tool unified patch | Capture in `task-runner.ts` for rollback |
-| **Nice-to-have** | Session ID alignment | Align pi session IDs with pi-crew run IDs |
-| **No action** | Bash truncation fix | Already benefits pi-crew (internal) |
-| **No action** | Compact reads | Already benefits pi-crew (internal) |
-| **No action** | Async tools | Already benefits pi-crew (internal) |
-
-**Primary recommendation:** Implement Priority 1 (child exit handling) and Priority 2 (excludeFromContext) in `child-pi.ts`.

package/docs/comparison-pi-subagents-vs-pi-crew.md

@@ -1,303 +0,0 @@
-# Architecture Comparison: pi-subagents3 vs pi-crew
-
-> Date: 2026-05-12  
-> Source: `@tintinweb/pi-subagents` v0.7.1 (6.082 LOC, 28 files) vs `pi-crew` v0.2.3 (35.809 LOC, ~200+ files)
-
----
-
-## 1. Overview
-
-| Criterion | pi-subagents3 | pi-crew |
-|---|---|---|
-| **Author** | tintinweb | baphuongna |
-| **Version** | 0.7.1 | 0.2.3 |
-| **Goal** | Single subagent (Agent tool) — spawn, resume, steer | Team orchestration — multi-agent workflows, phases, parallel dispatch |
-| **LOC** | ~6.000 | ~36.000 |
-| **Entry point** | `src/index.ts` (1.885 lines — monolith) | `index.ts` → `register.ts` (668 lines) → modular registration |
-| **Architecture** | Simple, direct, single-agent focus | Layered, event-driven, state-machine based |
-| **Peer deps** | pi-ai ≥0.70.5, pi-coding-agent ≥0.70.5, pi-tui ≥0.70.5 | pi-coding-agent (runtime) |
-| **Npm deps** | `@sinclair/typebox`, `croner`, `nanoid` | 0 (zero runtime dependencies) |
-| **Test runner** | vitest | Node built-in `--experimental-strip-types` |
-| **Subprocess model** | **In-process** (reuses Pi SDK `createAgentSession`) | **Out-of-process** (spawn child Pi instance via `child-pi.ts`) |
-
----
-
-## 2. Core architecture
-
-### 2.1 pi-subagents3 — In-process Agent Sessions
-
-```
-┌─────────────────────────────────────────────┐
-│              index.ts (1885 LOC)             │
-│  Extension entry: tools, commands, menus,    │
-│  lifecycle hooks, settings, scheduling       │
-├─────────┬──────────┬──────────┬──────────────┤
-│agent-   │agent-    │agent-    │schedule.ts   │
-│runner   │manager   │types     │ScheduleStore │
-│(310 LOC)│(310 LOC) │(140 LOC) │(365 LOC)     │
-├─────────┴──────────┴──────────┴──────────────┤
-│ memory.ts │ prompts.ts │ context.ts │ env.ts │
-│ worktree  │ model-     │ settings   │ usage  │
-│           │ resolver   │            │        │
-├──────────────────────────────────────────────┤
-│           Pi SDK (createAgentSession)         │
-│     In-process, shared event loop            │
-└──────────────────────────────────────────────┘
-```
-
-**Key characteristics:**
-- Agent runs **in the same process** as the parent Pi session
-- Uses `createAgentSession()` + `session.prompt()` — direct Pi SDK API
-- Tool filtering, extension binding, skill preloading in-process
-- Event subscription (`session.subscribe()`) to track turns, tool uses, streaming text
-- A single huge `index.ts` file contains nearly all the logic
-
-### 2.2 pi-crew — Out-of-process Child Workers
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                   register.ts (668 LOC)                  │
-│  Extension entry: lifecycle, commands, tool registration  │
-├────────────────┬─────────────────┬───────────────────────┤
-│  team-tool.ts  │  team-runner.ts │  subagent-manager.ts  │
-│  (344 LOC)     │  (945 LOC)      │  (400 LOC)            │
-│  Tool handler  │  Workflow engine │  Agent tracking       │
-├────────────────┴─────────────────┴───────────────────────┤
-│  child-pi.ts (461 LOC) │ task-runner.ts (459 LOC)        │
-│  Subprocess spawn      │ Per-worker execution             │
-├─────────────────────────┬───────────────────────────────┤
-│     State Layer         │        UI Layer                │
-│  state-store.ts         │  crew-widget.ts                │
-│  event-log.ts           │  run-dashboard.ts              │
-│  locks.ts               │  transcript-viewer.ts          │
-│  atomic-write.ts        │  powerbar-publisher.ts         │
-├─────────────────────────┴───────────────────────────────┤
-│       Pi CLI (child process via spawn)                   │
-│     Isolated process, independent event loop             │
-└─────────────────────────────────────────────────────────┘
-```
-
-**Key characteristics:**
-- Worker runs **in a separate process** — spawns `pi` CLI child process
-- Communicates via JSON events on stdout (`--json-output` mode)
-- State persistence: JSONL event log, manifest files, atomic writes
-- Distributed architecture: team → workflow → phases → tasks → workers
-- Full isolation: crash recovery, stuck detection, deadletter
-
----
-
-## 3. Detailed module-by-module comparison
-
-### 3.1 Agent Execution
-
-| Aspect | pi-subagents3 | pi-crew |
-|---|---|---|
-| **Runtime** | `createAgentSession()` in-process | `spawn("pi", [...])` child process |
-| **Tool access** | Direct — `session.setActiveToolsByName()` | Limited by child Pi args |
-| **Context sharing** | `buildParentContext()` — copy conversation | None (isolated by design) |
-| **Steering** | `session.steer(message)` — immediate in-process | `child.stdin.write()` — JSON event |
-| **Resume** | `resumeAgent(session, prompt)` — reuse session | Re-spawn child process |
-| **Turn limits** | Soft limit → steer "wrap up" → hard abort | `--max-turns` CLI arg → child exit |
-| **Grace turns** | Configurable (default 5) | N/A |
-| **Streaming** | `session.subscribe()` — real-time deltas | JSON event polling on stdout |
-| **Compaction** | Tracked via `compaction_end` events | Child handles independently |
-| **Memory overhead** | Low (shared process) | High (separate Node.js process) |
-| **Isolation** | Process-shared (same memory space) | Process-isolated (crash-safe) |
-| **Max concurrent** | Queue with configurable limit (default 4) | Queue with configurable limit (default 4) |
-
-### 3.2 Agent Configuration
-
-| Aspect | pi-subagents3 | pi-crew |
-|---|---|---|
-| **Built-in agents** | 3: general-purpose, Explore, Plan | 10: explorer, planner, executor, reviewer, verifier, analyst, critic, writer, security-reviewer, test-engineer |
-| **Custom agents** | `.md` files in `.pi/agents/` or `~/.pi/agents/` | `.md` files in `agents/` (project) |
-| **Agent config** | 22 fields: systemPrompt, promptMode, extensions, skills, model, thinking, maxTurns, memory, isolation, disallowedTools... | agent-config.ts: name, systemPrompt (frontmatter), maxTurns |
-| **Prompt mode** | `replace` (standalone) or `append` (parent twin) | Always replace (isolated subprocess) |
-| **Tool filtering** | Allowlist (builtinToolNames) + denylist (disallowedTools) + extension filter | CLI arg `--allowed-tools` |
-| **Model lock** | Per-agent model in config | Per-agent model in frontmatter |
-| **Thinking level** | Per-agent `thinking` field | Per-agent `thinkingLevel` in frontmatter |
-| **Agent discovery** | `custom-agents.ts` → `.md` frontmatter parse | `discover-agents.ts` → `.md` frontmatter parse |
-
-### 3.3 Memory / Persistence
-
-| Aspect | pi-subagents3 | pi-crew |
-|---|---|---|
-| **Agent memory** | ✅ Persistent MEMORY.md per agent (user/project/local scope) | ❌ No built-in agent memory |
-| **Memory tools** | Injected dynamically based on write capability | N/A |
-| **State persistence** | In-memory AgentRecord + JSON schedule store | Full state machine: manifest.json + events.jsonl + tasks.json |
-| **Crash recovery** | Worktree prune on dispose | Detect interrupted runs, deadletter, stuck-blocked notifications |
-| **Locking** | PID-based file lock for schedule store | `mkdirSync` atomic lock + PID stale detection for event log |
-| **Atomic writes** | temp+rename (POSIX) | Full atomic-write.ts with O_NOFOLLOW, symlink checks, sync/async parity |
-
-### 3.4 Scheduling
-
-| Aspect | pi-subagents3 | pi-crew |
-|---|---|---|
-| **Scheduling** | ✅ Full scheduler: cron (6-field), interval, one-shot | ❌ No scheduling |
-| **Cron engine** | `croner` library | N/A |
-| **Persistence** | Session-scoped JSON with PID-locked store | N/A |
-| **Queue bypass** | `bypassQueue: true` for scheduled fires | N/A |
-| **Events** | `subagents:scheduled` (added/removed/fired/error) | N/A |
-| **Master switch** | `schedulingEnabled` setting (strips tool param) | N/A |
-
-### 3.5 Worktree Isolation
-
-| Aspect | pi-subagents3 | pi-crew |
-|---|---|---|
-| **Worktree support** | ✅ `createWorktree()` / `cleanupWorktree()` | ✅ Full `worktree-manager.ts` (8.8 KB) |
-| **Branch management** | Auto-branch, auto-commit changes | Branch freshness, reuse, file node_modules skip |
-| **Error handling** | Strict — throws if worktree creation fails | Retry + fallback |
-| **Cleanup** | On completion (success or error) + prune on dispose | On completion + cleanup.ts + branch-freshness |
-
-### 3.6 Cross-extension Communication
-
-| Aspect | pi-subagents3 | pi-crew |
-|---|---|---|
-| **RPC protocol** | ✅ Event bus RPC: ping/spawn/stop | ✅ Event bus RPC: ping/spawn/status/cancel |
-| **Protocol version** | v2 | Versioned |
-| **Reply envelope** | `{ success: true, data? }` / `{ success: false, error }` | Similar |
-| **Singleton access** | `Symbol.for("pi-subagents:manager")` on globalThis | `globalThis.__piCrewRuntimeCleanup` |
-
-### 3.7 UI / TUI
-
-| Aspect | pi-subagents3 | pi-crew |
-|---|---|---|
-| **Agent widget** | `agent-widget.ts` (518 LOC) — overlay | `crew-widget.ts` (16 KB) — sidebar + dashboard |
-| **Conversation viewer** | `conversation-viewer.ts` (243 LOC) | `transcript-viewer.ts` (13.9 KB) — JSONL-based |
-| **Schedule menu** | `schedule-menu.ts` (104 LOC) | N/A |
-| **Dashboard** | N/A (overlay-based) | `run-dashboard.ts` (22.7 KB) — multi-pane |
-| **Status bar** | Inline status in overlay | `powerbar-publisher.ts` (8.9 KB) |
-| **Live sidebar** | N/A | `live-run-sidebar.ts` (8.6 KB) |
-| **Notification render** | Custom `renderCall` / `renderResult` | `notification-router.ts` + `notification-sink.ts` |
-| **Context % indicator** | ✅ Token count + context % (colored) + compaction count | ❌ No context indicator |
-
-### 3.8 Settings / Configuration
-
-| Aspect | pi-subagents3 | pi-crew |
-|---|---|---|
-| **Settings file** | `.pi/subagents.json` (project) + `~/.pi/agent/subagents.json` (global) | `config.ts` → `.pi/crew-config.json` + `defaults.ts` |
-| **Runtime settings** | maxConcurrent, defaultMaxTurns, graceTurns, defaultJoinMode, schedulingEnabled | maxConcurrent, telemetry, notifications |
-| **Validation** | `sanitize()` with ceiling values | `config.ts` schema validation |
-| **Hot reload** | Apply on change + emit event | Load on register |
-
----
-
-## 4. Unique features
-
-### pi-subagents3 has but pi-crew doesn't:
-
-1. **In-process agent sessions** — Zero subprocess overhead, direct Pi SDK access, shared event loop
-2. **Persistent agent memory** — MEMORY.md per agent with 3 scopes (user/project/local), auto-injected tools
-3. **Soft turn limit + grace period** — Steer "wrap up" before hard-aborting, configurable grace turns
-4. **Scheduling** — Full cron/interval/one-shot scheduler with croner, session-scoped persistence
-5. **Parent context inheritance** — `inheritContext` forks the conversation for the subagent
-6. **Append mode** — Agent runs as a "twin" of the parent (inherits system prompt + tools)
-7. **Context % indicator** — Live context window utilization (%), compaction count (↻N)
-8. **Agent memory tools** — Dynamic tool injection based on write capability (read-only vs read-write)
-9. **Skill preloading** — Load skill content directly into the system prompt (string[])
-10. **Batch grouping** — 100ms debounce batches multiple background completions into 1 notification
-11. **Cancelable nudges** — 200ms hold before sending a notification, get_subagent_result cancels the nudge
-12. **Agent creation wizard** — `/agents` → spawn an agent to create an agent config .md file
-
-### pi-crew has but pi-subagents3 doesn't:
-
-1. **Team orchestration** — Multi-agent teams with workflows, phases, parallel dispatch
-2. **Workflow engine** — Declarative workflow definitions (step → agent → gate → next)
-3. **Out-of-process isolation** — Child Pi process, crash-safe, independent event loop
-4. **Full state machine** — manifest.json + tasks.json + events.jsonl, durable persistence
-5. **Crash recovery** — Detect interrupted runs, deadletter queue, stuck-blocked detection
-6. **Mailbox system** — Interactive respond/nudge/ack workflow for waiting tasks
-7. **Heartbeat monitoring** — `heartbeat-watcher.ts` + gradient-based health tracking
-8. **Observability** — Metrics registry, OTLP exporter, Prometheus exporter
-9. **Run export/import** — Bundle/unbundle runs for cross-machine sharing
-10. **Live session management** — Live IRC, live agent control, live extension bridge
-11. **UI dashboard** — Multi-pane dashboard with agents/capabilities/health/mailbox/progress
-12. **Run snapshot cache** — Efficient state snapshots for UI rendering
-13. **Delivery coordination** — Overflow recovery, delivery coordinator for message routing
-14. **i18n** — Internationalization support
-15. **Post-checks** — Configurable post-execution verification hooks
-16. **Iteration hooks** — Pre/post iteration hooks for external integrations
-17. **Model fallback chain** — Multi-model fallback with cost tracking
-18. **Compaction summary** — Context compaction for long-running agents
-19. **Task quality scoring** — Automatic quality assessment of task outputs
-20. **Agent capability inventory** — Dynamic tool/skill capability detection
-
----
-
-## 5. Pros and cons analysis
-
-### pi-subagents3
-
-**Pros:**
-- **Simple**: ~6K LOC, easy to understand and maintain
-- **Performance**: In-process, zero subprocess overhead, shared memory
-- **Deep features**: Memory, scheduling, context inheritance, turn management are very detailed
-- **SDK-first**: Uses the Pi SDK directly, fully leveraging the API
-- **Interactive**: Resume, steer, conversation viewer are very smooth
-- **Settings**: Hot-reload, master switch for features
-
-**Cons:**
-- **Monolith**: `index.ts` 1.885 lines — hard to maintain, hard to test
-- **No team support**: No workflow, phases, parallel dispatch
-- **Crash propagation**: Agent crash affects the parent process
-- **Limited observability**: No metrics, export, monitoring
-- **No run persistence**: Agent record is in-memory only (except the schedule store)
-
-### pi-crew
-
-**Pros:**
-- **Strong architecture**: Layered, event-driven, state-machine based
-- **Team orchestration**: Workflow engine with phases, parallel, gates
-- **Crash isolation**: Out-of-process workers, child crash doesn't affect parent
-- **Full persistence**: JSONL event log, manifest, atomic writes
-- **Observability**: Metrics, OTLP, Prometheus, heartbeat monitoring
-- **Modular**: 200+ files, each file one responsibility
-- **Enterprise features**: Export/import, i18n, compaction, quality scoring
-
-**Cons:**
-- **Complex**: 36K LOC, steep learning curve
-- **Subprocess overhead**: Each worker spawns its own process (RAM, startup time)
-- **No memory**: Agents have no persistent memory between sessions
-- **No scheduling**: No cron/interval/one-shot
-- **No context inheritance**: Workers run isolated, can't see parent context
-- **No soft turn limit**: Hard cutoff, no grace period
-- **No interactive steer**: Cannot steer a worker after spawning
-
----
-
-## 6. Recommendations
-
-### What pi-crew should learn from pi-subagents3:
-
-1. **Persistent agent memory** — The MEMORY.md pattern is very valuable for long-running projects
-2. **Soft turn limit + grace period** — More elegant than hard abort
-3. **Scheduling** — Cron/interval scheduling for automated tasks
-4. **Context % indicator** — Helps the parent LLM know how much room the subagent has left
-5. **Batch notification grouping** — Reduces noise when many workers complete simultaneously
-6. **In-process mode** (optional) — For lightweight tasks that don't need process isolation
-7. **Cancelable nudges** — Avoid notification spam
-8. **Agent settings hot-reload** — Change settings without restarting
-
-### What pi-subagents3 should learn from pi-crew:
-
-1. **Modular architecture** — Split `index.ts` into multiple files
-2. **State persistence** — Durable state instead of in-memory only
-3. **Crash recovery** — Detect interrupted runs, deadletter
-4. **Observability** — Metrics, monitoring, health checks
-5. **Team support** — Multi-agent workflows
-6. **Out-of-process option** — For heavy tasks needing isolation
-7. **Run export/import** — Cross-machine sharing
-
----
-
-## 7. Conclusion
-
-**pi-subagents3** is a **focused** extension — it does one thing very well: spawn and manage individual subagents. It leverages the Pi SDK maximally, in-process, interactive, with deep features like memory and scheduling.
-
-**pi-crew** is an **orchestration platform** — broader scope, strong in team workflows, state management, crash recovery, and enterprise features. But much more complex, and missing some "nice-to-have" features that pi-subagents3 has.
-
-The two extensions **complement** each other more than they compete:
-- pi-subagents3 for **quick, interactive subagent tasks** (code review, exploration, one-off analysis)
-- pi-crew for **complex, multi-phase team workflows** (full feature implementation, multi-perspective review, parallel research)
-
-An ideal architecture might combine both: use pi-subagents3's in-process execution for lightweight tasks, and pi-crew's orchestration layer for complex workflows.

package/docs/decisions/0001-durable-state.md

@@ -1,41 +0,0 @@
-# 0001 Durable State as Source of Truth
-
-Date: 2026-05-11
-
-## Status
-
-Accepted
-
-## Context
-
-pi-crew runs can last minutes to hours. Runs may be started from foreground
-sessions, background processes, or async workers. Multiple observers (TUI
-dashboard, status commands, event hooks) need to see the same run state.
-
-## Decision
-
-All run state is stored on disk as JSON files:
-- `manifest.json` — run metadata, status, config
-- `tasks.json` — task graph with statuses
-- `events.jsonl` — append-only event log
-- `agents/{taskId}/status.json` — per-agent state
-
-All reads go through state store. All writes use atomic write helpers and
-run-level locks (`withRunLockSync`).
-
-## Alternatives Considered
-
-1. In-memory state with periodic flush. Rejected: lost on crash, inconsistent across processes.
-2. Database (SQLite). Rejected: adds native dependency, overkill for append-mostly data.
-
-## Consequences
-
-Positive:
-- Crash recovery is possible by reading state from disk
-- Multiple processes can observe the same run
-- Event log provides audit trail
-
-Tradeoffs:
-- File I/O on every state mutation (mitigated by atomic writes)
-- Windows EBUSY/EPERM requires retry logic
-- Lock contention under heavy concurrent access

package/docs/decisions/0002-child-process-for-async.md

@@ -1,42 +0,0 @@
-# 0002 Child-Process for Async Runners
-
-Date: 2026-05-12
-
-## Status
-
-Accepted
-
-## Context
-
-pi-crew supports two runtime modes for task execution:
-- `live-session`: in-process, reuses current Pi agent session
-- `child-process`: spawns a new Node process via `child-pi.ts`
-
-Async runs (background runner, async runner) start from the current session but
-continue after the session ends. Live-session mode requires the parent Pi agent
-to be alive — it uses the same in-process tools and session context.
-
-## Decision
-
-Async runners MUST use `child-process` mode. The `live-session` mode is only
-available for foreground runs within the current Pi agent session.
-
-Runtime policy enforces: `runtimeResolver` overrides any `live-session` request
-to `child-process` when the run is async.
-
-## Alternatives Considered
-
-1. Allow live-session for async. Rejected: crashes when parent session ends, resource leaks.
-2. Persist and restore live-session. Rejected: in-process state (timers, handles) cannot be serialized.
-
-## Consequences
-
-Positive:
-- Async runs survive session shutdown
-- No zombie timers or leaked handles from dead sessions
-- Clean process isolation
-
-Tradeoffs:
-- Child process startup overhead (~2-5s)
-- No shared in-process state between parent and child
-- Requires all runtime config to be serializable