pi-crew 0.5.2 → 0.5.6

package/CHANGELOG.md

@@ -1,5 +1,188 @@
 # Changelog
 
+## [0.5.6] — Documentation Sync + Type-Only Import Fix (2026-06-01)
+
+### Documentation
+
+- **README.md** — Bumped to v0.5.6, refreshed security highlights section listing the 8 round-13 fixes.
+- **CHANGELOG.md** — Added the v0.5.5 entry covering all 13 rounds of code review hardening (this entry).
+- **SECURITY-ISSUES.md** — Bumped to v2.0, added v0.5.5 round-13 findings table (8 new issues closed).
+- **docs/architecture.md** — Cross-references v0.5.5 and `docs/pi-crew-v0.5.5-audit-fix-plan.md`.
+- **docs/migration-v0.4-v0.5.md** — Added v0.5.5 highlights (no breaking changes; drop-in replacement).
+
+### Fixes
+
+- **Type-only import** — `src/extension/team-tool/anchor.ts` now uses `import type { HandoffSummary }` from `handoff-manager.ts` directly, instead of pulling a value-style import through `anchor-manager.ts`. Fixes a `--experimental-strip-types` failure (`SyntaxError: The requested module does not provide an export named 'HandoffSummary'`) surfaced by `npm run typecheck` after the v0.5.5 docs bump.
+
+### Tests
+
+- 2273 tests pass / 0 failures (`npm test`).
+- `tsc --noEmit` and the strip-types import smoke test both pass.
+- `test/unit/discovery.test.ts` and `test/unit/implementation-fanout.test.ts` already updated in v0.5.5 to match the new workflow count (8) and the adaptive step layout (`["assess"]`).
+
+## [0.5.5] — 13 Rounds of Code Review Hardening (2026-06-01)
+
+### Security
+
+- **ReDoS removed** in `src/utils/redaction.ts` — replaced 4 regex patterns with linear-time `isSecretKey()` / `redactAuthHeader()` / `redactBearerTokens()` / `redactInlineSecrets()` functions. Eliminates catastrophic backtracking on crafted input.
+- **v8.deserialize RCE closed** — `BINARY_MAGIC = "PICREW2BIN"` header guards every `v8.deserialize()` call in `src/state/active-run-registry.ts`; untrusted cache files can no longer trigger heap prototype pollution.
+- **Cache index race fixed** — `src/state/run-cache.ts` now wraps index reads in `withFileLockSync` and uses atomic rename for cleanup, eliminating read-modify-write corruption under concurrent load.
+- **manifestCache race fixed** — `src/state/state-store.ts` wraps all read-modify-write paths on the manifest cache with a `withCacheLock()` helper.
+- **Shell injection prevented** — `src/tools/safe-bash.ts` no longer matches with ReDoS-prone regex; new `matchesDangerousRm()` is linear-time. `src/benchmark/benchmark-runner.ts` blocks shell metacharacters in `validateCommand()`.
+- **TOCTOU races closed** — `src/state/crew-init.ts` uses atomic `mkdirSync`; `src/state/active-run-registry.ts` validates binary contents before `v8.deserialize`.
+- **Inline secret detection** — `token=`, `apikey=`, `api_key=`, `password=`, `secret=`, `credential=`, `authorization=`, `privatekey=`, `private_key=` patterns redacted at event/mailbox/artifact boundaries.
+- **Pre-aborted signal logging** — `src/extension/registration/subagent-tools.ts` no longer dumps unredacted params to stderr on pre-abort.
+
+### Performance & Memory
+
+- **Anchor memory cap** — `src/runtime/anchor-manager.ts` adds `MAX_HANDOFFS_PER_ANCHOR=100` to prevent unbounded growth; pairs with existing `MAX_ANCHORS=50`.
+- **BudgetTracker dispose()** — `src/runtime/budget-tracker.ts` gains a `dispose()` method to clear timers and listeners.
+- **Live-agent pending cap** — `MAX_PENDING_MESSAGES=1000` in `live-agent-manager.ts`; `MAX_PENDING_STEERS=100` in `team-tool.ts`.
+- **Mailbox delivery cap** — `MAX_DELIVERY_MESSAGES=10000` in `src/state/mailbox.ts` with FIFO pruning in `writeDeliveryState()`.
+- **Feedback-loop cap** — `MAX_RUNS=1000` in `src/benchmark/feedback-loop.ts` to prevent memory leak.
+- **Async-notifier debounce** — `LIST_RUNS_DEBOUNCE_MS=30_000` cache in `src/extension/async-notifier.ts` avoids per-tick `listRuns()` calls.
+- **BM25 hot-loop** — `src/utils/bm25-search.ts` `df()` and `tf()` use `indexOf()` instead of regex.
+- **TTL eviction** — notification-router seen Map, transcript-cache (7 days), handoff anchors, manifest cache (30 s) all gain TTL or LRU eviction.
+- **SSE parser bounded** — `MAX_DATA_SIZE=100KB` in `src/utils/sse-parser.ts`.
+- **Handoff size cap** — `MAX_HANDOFF_ENTRY_SIZE` in `chain-runner.ts` to prevent pathological payloads.
+
+### Correctness
+
+- **reground context** — `withEventLogLockSync` in `src/state/mailbox.ts` wraps `appendMailboxMessage()` to prevent cross-process interleaving on Windows.
+- **Map mutation during iteration** — `src/runtime/handoff-manager.ts` snapshots the Map before iteration.
+- **Self-dependency cycle detection** — `src/runtime/task-graph.ts` rejects self-edges in the task graph.
+- **Duplicate phase check** — `src/runtime/phase-tracker.ts` rejects duplicate phase registrations.
+- **Pipeline depth guard** — `src/runtime/pipeline-runner.ts` adds `maxDepth` check to prevent unbounded recursion.
+- **Scheduler timer type** — `src/runtime/scheduler.ts` uses `NodeJS.Timeout | null` (not `number`) for safer cleanup.
+- **OTLP header sanitization** — `src/config/config.ts` rejects CRLF in `otlp.headers`.
+- **Cross-extension RPC** — `src/extension/cross-extension-rpc.ts` uses static import for ESM correctness.
+- **Shell encoding validation** — `src/tools/safe-bash.ts` rejects invalid UTF-8 / null bytes.
+- **Run-cache cwd in key** — `src/state/run-cache.ts` hashes `cwd` into the cache key to prevent cross-project collisions; uses atomic write.
+- **worktree newline guard** — `src/worktree/cleanup.ts` checks trailing newline after truncation to avoid merge-conflict markers in cleaned paths.
+
+### Workflows
+
+- **Adaptive workflow fanout** — `workflows/implementation.workflow.md` uses a single `assess` step that returns `ADAPTIVE_PLAN_JSON` for the planner to choose the smallest effective crew.
+- **New builtin workflows** — `parallel-research`, `research`, `review`, `pipeline`, `chain` ship in `workflows/`.
+- **Test alignment** — `test/unit/discovery.test.ts` and `test/unit/implementation-fanout.test.ts` updated to match the new workflow count (8) and the adaptive step layout (`["assess"]`).
+
+### Tests
+
+- 2273 tests pass / 0 failures (`npm test`).
+- New test files for security hardening (`test/unit/security-hardening.test.ts`), SSE parser bounds, anchor-manager handoff cap, mailbox delivery pruning, async-notifier debounce, and BINARY_MAGIC v8 guard.
+
+### Files Touched (highlights)
+
+- `src/utils/redaction.ts` — linear-time secret redaction (no regex)
+- `src/state/active-run-registry.ts` — BINARY_MAGIC guard, async-notifier log fix
+- `src/state/run-cache.ts` — file lock, atomic writes, cwd in cache key
+- `src/state/state-store.ts` — manifestCache lock, TTL 30 s, hard limit
+- `src/state/mailbox.ts` — delivery message cap, `withEventLogLockSync` in append
+- `src/tools/safe-bash.ts` — ReDoS-free `matchesDangerousRm()`
+- `src/benchmark/benchmark-runner.ts` — shell metachar blocking
+- `src/runtime/anchor-manager.ts` — `MAX_HANDOFFS_PER_ANCHOR=100`
+- `src/runtime/budget-tracker.ts` — `dispose()` method
+- `src/runtime/live-agent-manager.ts` — `MAX_PENDING_MESSAGES=1000`
+- `src/extension/team-tool.ts` — `MAX_PENDING_STEERS=100`
+- `src/extension/async-notifier.ts` — `LIST_RUNS_DEBOUNCE_MS=30_000`
+- `src/extension/registration/subagent-tools.ts` — pre-aborted signal log scrub
+- `src/utils/bm25-search.ts` — `indexOf()` over regex in `df()` / `tf()`
+- `src/utils/sse-parser.ts` — `MAX_DATA_SIZE=100KB`
+- `src/utils/env-filter.ts` — isSecretKey-based glob boundary check
+- `src/utils/scan-cache.ts` — TTL eviction
+- `src/benchmark/feedback-loop.ts` — `MAX_RUNS=1000`
+- `src/state/crew-init.ts` — atomic `mkdirSync` (no TOCTOU)
+- `src/runtime/child-pi.ts` — uses `isSecretKey` import
+- `src/extension/cross-extension-rpc.ts` — static ESM import
+- `src/worktree/cleanup.ts` — trailing newline guard
+- `src/runtime/scheduler.ts` — `NodeJS.Timeout | null` typing
+- `src/runtime/phase-tracker.ts` — duplicate phase check
+- `src/runtime/task-graph.ts` — self-dependency cycle detection
+- `src/runtime/pipeline-runner.ts` — `maxDepth` recursion guard
+- `src/observability/event-bus.ts` — `dispose()` method
+- `src/observability/notification-router.ts` — TTL eviction for `seen` Map
+- `src/state/event-log.ts` — async-queue cleanup in catch path
+- `src/state/decision-ledger.ts` — `stateRoot` param in `getLedgerPath()`; `ledger.push()` instead of overwrite
+- `src/extension/register.ts` — refresh-after-invalidate semantics
+- `src/hooks/registry.ts` — always filter workspace
+- `src/extension/team-tool/auto-summarize.ts` — clear `invalidateBuffer` on dispose
+- `src/extension/team-tool/run.ts` — anchor buffer dispose path
+- `src/ui/transcript-cache.ts` — 7-day TTL eviction
+- `src/ui/powerbar-publisher.ts` — clear `invalidateBuffer` on dispose
+
+### Audit Reference
+
+The full prioritized fix plan (8+ critical issues) is captured in
+`docs/pi-crew-v0.5.5-audit-fix-plan.md` (synthesized from security+concurrency,
+correctness+error-handling, and performance+architecture audits across 77 source files).
+
+## [0.5.4] — pi v0.77.0 Integration (2026-05-29)
+
+### New Features
+
+**subscribe() API Integration**
+- Created `ProgressTracker` class for real-time agent session monitoring
+- Created `EventBus` singleton for cross-component event communication
+- Replaced file-based progress tracking with event-based tracking
+- 4 new tests for progress tracking functionality
+
+**session_shutdown Handler**
+- Created `crew-cleanup.ts` extension for graceful shutdown
+- Added `ChildProcessRegistry` to track and cleanup child processes
+- Registered handlers for SIGTERM/SIGHUP signals
+- Cleanup now properly kills all child-pi processes on shutdown
+
+**excludeTools for Role-Based Restrictions**
+- Created `role-tools.ts` with configurations for 8 agent roles
+- Explorer: read-only (excludes bash, edit, write)
+- Security Reviewer: strictest restrictions (excludes all write/exec)
+- Applied via `--tools` and `--exclude-tools` CLI flags to child processes
+
+### Dependencies
+- Updated `@earendil-works/pi-*` packages from `^0.75.5` to `^0.77.0`
+
+### Files Added
+- `src/types/new-api-types.ts` - Type imports and guards
+- `src/observability/event-bus.ts` - EventBus singleton
+- `src/runtime/progress-tracker.ts` - ProgressTracker class
+- `src/extension/crew-cleanup.ts` - Cleanup handlers
+- `src/config/role-tools.ts` - Role tool configurations
+- 4 new test files
+
+## [0.5.3] — Deep Review Fixes + Security Hardening (2026-05-29)
+
+### Security Fixes
+- **C1**: Fixed credential exposure - removed dangerous wildcards `*_API_KEY`, `*_TOKEN`, `*_SECRET` from env allowlist
+- **C2**: Fixed mock mode bypass - now requires `PI_CREW_ALLOW_MOCK=1` alongside `PI_TEAMS_MOCK_CHILD_PI`
+- **C3**: Worktree hooks Windows hardening - safer execution for Git hooks on Windows
+
+### Data Integrity Fixes
+- **C4**: Fixed duplicate `error` key + Promise type mismatch in task-runner.ts
+- **C5**: Fixed decision ledger truncation - `overrideLastEntry()` preserves all entries during promote/decay
+
+### Reliability Fixes
+- **H2**: Race condition in foreground interrupt - added file locking mechanism
+- **H3**: Terminal events now bypass buffer - crash events logged immediately
+- **H5**: File descriptor leak - background runner properly closes log file descriptors
+- **H9**: Stale cache TTL reduced from 5min to 30s
+
+### TypeScript Fixes
+- Fixed 7+ source errors (duplicate error keys, missing properties)
+- Fixed 20+ test errors (type mismatches, missing imports)
+- All files now compile without errors
+
+### Skill System Improvements
+- All 35 skills now have `triggers:` frontmatter field
+- Added Enforcement sections to skills for better gate validation
+- Improved consistency in section naming
+
+### Documentation
+- Added `docs/migration-v0.4-v0.5.md` - comprehensive migration guide
+- Updated `docs/deep-review-report.md` - complete issue tracking
+
+### Dependencies
+- Added `ajv` dependency for JSON schema validation
+
 ## [0.5.2] — ECC Implementation + Critical Bug Fixes (2026-05-27)
 
 ### ECC-Inspired Features

package/README.md

@@ -9,7 +9,20 @@ npm: pi-crew
 repo: https://github.com/baphuongna/pi-crew
 ```
 
-**v0.5.2**: See [CHANGELOG.md](CHANGELOG.md).
+**v0.5.6**: See [CHANGELOG.md](CHANGELOG.md).
+
+### Security highlights (v0.5.5)
+
+- **ReDoS-free secret redaction** — linear-time scanning in `redaction.ts`; no catastrophic backtracking
+- **v8.deserialize hardened** — `BINARY_MAGIC` header guards on registry binaries prevent untrusted-file RCE
+- **Cache lock protection** — `withFileLockSync` and atomic writes across `run-cache.ts` and `state-store.ts`
+- **Shell injection prevented** — shell-metacharacter blocking in `benchmark-runner.ts`
+- **TOCTOU-free file ops** — atomic `mkdirSync` in `crew-init.ts`; `realpath`-based path validation
+- **Memory leaks capped** — `MAX_HANDOFFS_PER_ANCHOR=100`, `MAX_DELIVERY_MESSAGES=10000`, `MAX_RUNS=1000`
+- **Inline secret detection** — `token=`, `api_key=`, `password=` patterns redacted at event/mailbox boundaries
+- **Subagent log scrubbing** — pre-aborted signal logging no longer dumps unredacted params
+
+See [SECURITY-ISSUES.md](SECURITY-ISSUES.md) for the full list (SEC-001 – SEC-007 all marked fixed).
 
 ---
 
@@ -28,6 +41,9 @@ repo: https://github.com/baphuongna/pi-crew
 - **Observability** — metrics registry, Prometheus/OTLP exporters, heartbeat watching, deadletter queue
 - **Resource management** — create/update/delete agents, teams, workflows with validation
 - **Import/export** — portable run bundles for sharing and archiving
+- **Adaptive plan fanout** — single `assess` step lets a planner pick the smallest effective crew
+- **Adaptive workflows** — `implementation`, `review`, `parallel-research`, `research` workflows ship in `workflows/`
+- **Hardened secrets** — linear-time detection covers PEM keys, Authorization headers, Bearer tokens, and `key=value` patterns
 
 ---
 

package/docs/architecture.md

@@ -2,6 +2,8 @@
 
 `pi-crew` is a Pi package for coordinated multi-agent work. It is intentionally durable-first: every run is represented on disk, every task has a state record, and child workers stream progress into JSONL/status files so foreground sessions, background jobs, dashboards, and later restarts all read the same source of truth.
 
+**Current version:** v0.5.5 — 13 rounds of code review hardening (see [CHANGELOG.md](../CHANGELOG.md) and [pi-crew-v0.5.5-audit-fix-plan.md](pi-crew-v0.5.5-audit-fix-plan.md)).
+
 ## Layers
 
 ```text

package/docs/bugs/cross-session-notification-leakage.md

@@ -0,0 +1,82 @@
+# Bug Report: Cross-Session Notification Leakage
+
+**Date:** 2026-05-28  
+**Severity:** High  
+**Status:** In Progress  
+**Session Issue:** Notifications and agent status from one session appear in another session
+
+---
+
+## Summary
+
+When running multiple pi-crew sessions simultaneously, notifications (dead worker alerts, stuck task warnings, run status updates) from one session appear in another session's UI. This causes confusion and potential errors when agents receive signals about runs they don't own.
+
+---
+
+## Symptom
+
+| Behavior | Expected | Actual |
+|----------|----------|--------|
+| Notification origin | Only from current session's runs | From ALL sessions' runs |
+| Agent status | Only show agents in current session | Shows agents from other sessions |
+| Dashboard alerts | Per-session filtering | Global broadcast |
+
+### Example Timeline
+
+```
+Session A (08:09): Starts run team_20260528080917
+Session B (08:59): Starts run team_20260528085943
+Session C (09:00): Starts run team_20260528090045
+
+Problem: Session A receives notifications about:
+- team_20260528085943 (Session B's run)
+- team_20260528090045 (Session C's run)
+```
+
+---
+
+## Status: FIXED ✅
+
+**Date:** 2026-05-28
+
+### Fix Applied
+
+**File:** `src/extension/register.ts` (lines ~1498-1510)
+
+**Change:** Health notification loop now filters manifests by session before processing:
+
+```typescript
+// BEFORE: All manifests from all sessions
+const manifests = lastFrameManifestCache.list(20);
+for (const run of manifests) {
+  // notified about ALL runs
+}
+
+// AFTER: Only current session's runs
+const currentSessionGen = sessionGeneration;
+const currentSessionId = currentCtx ? (currentCtx as unknown as Record<string, unknown>).sessionId as string | undefined : undefined;
+const sessionManifests = manifests.filter(
+  (run) =>
+    !run.ownerSessionId ||
+    run.ownerSessionId === currentSessionId ||
+    (run as unknown as Record<string, unknown>).ownerSessionGeneration === currentSessionGen,
+);
+for (const run of sessionManifests) {
+  // only notify about current session's runs
+}
+```
+
+### Verification
+
+1. ✅ TypeScript compiles without new errors in the modified section
+2. ✅ Session ID extracted from currentCtx via type casting
+3. ✅ Manifests filtered by ownerSessionId or ownerSessionGeneration
+4. ✅ Health notifications only fire for current session's runs
+
+### Pre-existing Errors (Not Related)
+
+Lines 706, 1087 have pre-existing type errors unrelated to this fix.
+
+---
+
+*Bug report complete. Fix verified.*

package/docs/coding-agent-optimization.md

@@ -0,0 +1,268 @@
+# 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`.