pi-crew 0.1.49 → 0.2.0

package/docs/research/SESSION-SUMMARY-2026-05-08.md

@@ -1,146 +0,0 @@
-# pi-crew Session Summary — 2026-05-08
-
-## What Was Done
-
-### 1. Full Code Review → 10 Bug Fixes
-- **Verdict: FAIL** (2 CRITICAL + 1 HIGH)
-- All 10 bugs fixed: C1, C2, H1-H4, M1, M2, L1, L3
-- Verified: `npm run typecheck` ✅, `npm test` 991/994 pass
-
-### 2. Deep Research on oh-my-pi (v14.7.6)
-- `git pull` → 55 files changed, +906/-249 lines
-- **CRITICAL DISCOVERY**: oh-my-pi uses IN-PROCESS execution (subagent runs in same process as parent)
-- pi-crew uses CHILD-PROCESS execution (extension-based architecture)
-- This explains WHY pi-crew needs `parent-guard.ts` and oh-my-pi doesn't
-
-### 3. Live-Session Production-Ready Upgrade
-- **9 phases implemented** (Phase 0-8): experimental flag removal, yield enforcement, AJV schema validation, AbortSignal, MCP proxy, extension runner, semaphore, IRC, health monitoring
-- **All verified** with typecheck + tests
-
-### 4. Parity Gaps G1-G6 Closed
-| Gap | Feature | Status |
-|-----|---------|--------|
-| G1 | Custom Tool Injection (submit_result + irc) | ✅ Done |
-| G2 | MCP Proxy (functional) | ✅ Done |
-| G3 | AJV Schema Validation | ✅ Done |
-| G4 | respondAsBackground | ✅ Done |
-| G5 | Extension Runner | ✅ Done |
-| G6 | toolChoice Workaround | ✅ Done |
-
-### 5. Orphaned Run Cleanup
-- `cancelOrphanedRuns()` — cancels orphaned project-level runs
-- `purgeStaleActiveRunIndex()` — scans active-run-index.json for stale entries
-- Integrated into: `cleanupRuntime()` + `session_start` event
-
-### 6. Parent Guard (OS-Level Child Cleanup)
-- **`parent-guard.ts`** — workers self-monitor parent PID, auto-exit if parent dies
-- **`PI_CREW_PARENT_PID`** env var injected into all child spawns
-- **Why**: pi-crew uses child processes (unlike oh-my-pi's in-process), so parent death doesn't auto-kill children
-
-### 7. P1 Action Items from New Research
-- ✅ **`scrubProcessEnv()`** — Added to `background-runner.ts` (macOS malloc fix)
-- ⚠️ **Fetch URL syntax** — pi-crew doesn't have a fetch tool (low priority)
-- ⚠️ **rewriteStaticImports** — pi-crew doesn't have JS code eval (low priority)
-
----
-
-## Files Changed (This Session)
-
-### Modified (23 files)
-```
-src/config/defaults.ts           — Phase 0: DEFAULT_LIVE_SESSION = true
-src/extension/register.ts        — P0: purgeStaleActiveRunIndex + cleanupRuntime
-src/runtime/async-runner.ts     — P1: PI_CREW_PARENT_PID + sentinel
-src/runtime/background-runner.ts — P1: scrubProcessEnv + parent-guard
-src/runtime/child-pi.ts         — P1: PI_CREW_PARENT_PID injection
-src/runtime/crash-recovery.ts   — P0: cancelOrphanedRuns + purgeStaleActiveRunIndex
-src/runtime/live-agent-manager.ts — G4: non-blocking IRC
-src/runtime/live-session-runtime.ts — Phases 0-8, G1, G6
-src/runtime/parallel-utils.ts   — Phase 6: mapConcurrentWithSignal
-src/runtime/runtime-resolver.ts — Phase 0: removed experimental flag
-src/runtime/subprocess-tool-registry.ts — H3: emit for error results
-src/runtime/task-runner.ts      — H4: try/catch
-src/runtime/task-runner/live-executor.ts — Phase 2: outputSchema passthrough
-src/runtime/team-runner.ts      — P1: executeTeamRunCore try/catch
-src/runtime/yield-handler.ts    — Phase 2 + G3: AJV validation
-src/state/event-log-rotation.ts — C2, M1, L3: compaction + rotation
-src/ui/run-event-bus.ts          — M2: non-blocking emit
-src/utils/sse-parser.ts         — L1: non-greedy event parsing
-src/extension/team-tool/parallel-dispatch.ts — C1, H1, H2: error handling
-```
-
-### Created (14 files)
-```
-src/runtime/custom-tools/submit-result-tool.ts  — G1: submit_result tool
-src/runtime/custom-tools/irc-tool.ts             — G1: irc DM/broadcast tool
-src/runtime/live-extension-bridge.ts            — G5: SDK-verified extension bridge
-src/runtime/live-irc.ts                          — Phase 7: IRC routing
-src/runtime/live-session-health.ts               — Phase 8: health monitoring
-src/runtime/mcp-proxy.ts                         — G2: functional MCP proxy
-src/runtime/orphan-sentinel.ts                   — (deprecated, parent-guard.ts used instead)
-src/runtime/parent-guard.ts                      — P1: parent PID watchdog
-src/runtime/semaphore.ts                         — Phase 6: Semaphore + fail-fast
-docs/research/AGENT-LIFECYCLE-COMPARISON.md     — Edge case analysis
-docs/research/LIVE-SESSION-PRODUCTION-READY-PLAN.md — 9-phase plan
-docs/research/OH-MY-PI-DEEP-RESEARCH-v14.7.6.md — v14.7.6 deep research
-docs/research/REMAINING-GAPS-PLAN.md            — G1-G6 plan + status
-```
-
----
-
-## Architecture Insights
-
-### Why pi-crew needs parent-guard (vs oh-my-pi)
-```
-oh-my-pi: Agent objects in-process → process.exit() = all dead (OS guarantee)
-pi-crew:  Worker processes separate → parent dies → workers live forever
-         → parent-guard.ts: worker polls parent PID, self-terminates on death
-```
-
-### pi-crew's Extension-Based Architecture
-- **pi-crew is a Pi extension** (not built-in)
-- Cannot embed in Pi's process → must use child processes
-- Child process isolation is actually a FEATURE (fault tolerance)
-- But needs explicit cleanup mechanisms (parent-guard, stale index purge)
-
-### Parent-guard Design (Final)
-```typescript
-// Workers check parent liveness THEMSELVES
-startParentGuard(parentPid: number): void {
-  const interval = setInterval(() => {
-    if (!isPidAlive(parentPid)) {
-      clearInterval(interval);
-      process.exit(124);  // self-terminate
-    }
-  }, 3000);
-}
-```
-
----
-
-## Test Results
-- `npm run typecheck` — ✅ pass
-- `npm test` — 991/994 pass, 3 skipped, 0 failures
-- P0/P1 tests (crash-recovery, active-run-registry, stale-reconciler, team-runner): **19/19 pass**
-
----
-
-## Next Steps (Not Done — Low Priority)
-1. **Loop limit** — `/loop 10` iteration limits (oh-my-pi feature)
-2. **rewriteStaticImports** — ESM imports in JS code eval
-3. **Fetch URL syntax** — pi-crew doesn't have fetch tool
-4. **hideThinkingSummary** — model config option
-
----
-
-## Commit Message Suggestion
-```
-feat: live-session production-ready + orphaned run cleanup + parent guard
-
-- Live-session: Phase 0-8 (yield, AJV, AbortSignal, MCP, extension, semaphore, IRC, health)
-- Parity: G1-G6 (custom tools, MCP proxy, schema validation, async IRC, extension bridge, toolChoice)
-- Orphan cleanup: purgeStaleActiveRunIndex() + cancelOrphanedRuns()
-- Parent guard: workers self-terminate when parent dies (PI_CREW_PARENT_PID)
-- scrubProcessEnv: macOS malloc fix for child shells
-- Bug fixes: C1, C2, H1-H4, M1, M2, L1, L3 (from code review)
-```

package/docs/research/UI-RESPONSIVENESS-AUDIT.md

@@ -1,173 +0,0 @@
-# UI Responsiveness Audit — Agent Spawn Visibility
-
-> Date: 2026-05-08
-> Issue: Khi user nháy 1 click "team run" trên UI, không thấy rõ agent đang chạy thật hay không.
-
-## 1. Vấn đề
-
-User gọi `team action='run'` (foreground) hoặc `team action='parallel'` → team runner spawn agents → nhưng widget/dashboard không cập nhật ngay lập tức. User phải đợi 1-2 giây hoặc nhấn refresh mới thấy agents.
-
-**Hệ quả**: User không biết agent đã spawn thành công hay thất bại → nháy thêm lần nữa → duplicate runs.
-
-## 2. Root Cause Analysis
-
-### 2.1 Event Flow (foreground run)
-
-```
-handleRun()                           [extension thread]
-  → executeTeamRun()                  [extension thread]
-    → runTeamTask()                   [extension thread]
-      → registerStreamBridge()        [line 75, event bridge ready]
-      → upsertCrewAgent()             [line 99, writes agents.json]
-      → appendEvent("task.started")   [line 100, writes events.jsonl]
-      → runChildPi()                  [line ~168, spawns child process]
-        → child.onJsonEvent()         [callback from child stdout]
-          → bridgeEventFromJsonEvent()
-            → runEventBus.emit()      [emits worker_status event]
-              → snapshotCache.invalidate()
-              → CrewWidgetComponent.invalidate()
-              → RenderScheduler.schedule()
-```
-
-### 2.2 Timing Gaps
-
-| Step | Time | Widget shows |
-|------|------|-------------|
-| handleRun() starts | 0ms | Old state (no run) |
-| upsertCrewAgent() writes agents.json | ~50ms | Still old state (cache TTL) |
-| task.started event written | ~60ms | Still old state |
-| Child process spawned | ~200ms | Still old state |
-| Child stdout first JSON event | ~2-5s | **First update!** |
-| Snapshot cache refresh | +500ms TTL | Updated |
-
-**Gap**: 2-5 giây từ lúc user nhấn đến khi UI hiển thị "1 running".
-
-### 2.3 Cụ thể
-
-1. **Snapshot cache TTL = 500ms**: Sau khi `agents.json` được ghi, cache chỉ refresh sau khi TTL expire. Nhưng ngay cả khi TTL pass, `refreshIfStale()` check file stamps → detect change → rebuild. OK, nhưng phải đợi next `renderTick()`.
-
-2. **Preload loop interval = 1000ms** (`DEFAULT_UI.refreshMs`): Background preload chạy mỗi 1 giây → đọc agents.json + events → update snapshot. Nhưng trong giây đầu tiên, agent chưa visible.
-
-3. **Event bridge chỉ hoạt động khi child process output**: `bridgeEventFromJsonEvent()` emit qua `runEventBus` chỉ khi child process gửi JSON events qua stdout. Child process phải start → load Pi → initialize → mới output event đầu tiên. Lost time: 2-5s.
-
-4. **Không có "immediate emit" khi task started**: `appendEvent("task.started")` ghi vào file nhưng không emit qua `runEventBus`. Event bridge chỉ active khi child output events.
-
-5. **Async run**: Background run spawn process riêng → parent process không nhận events → UI chỉ update qua preload loop (1s polling).
-
-## 3. Fixes
-
-### Fix 1: Emit `runEventBus` event ngay khi task started (HIGH IMPACT)
-
-**File**: `src/runtime/task-runner.ts`
-
-Sau `upsertCrewAgent()` + `appendEvent("task.started")`, emit ngay qua `runEventBus`:
-
-```typescript
-// Line ~100, after appendEvent("task.started")
-streamBridge?.handler({
-    runId: manifest.runId,
-    taskId: task.id,
-    eventType: "task.started",
-    timestamp: Date.now(),
-});
-```
-
-**Impact**: UI nhận event ngay → invalidate snapshot cache → widget hiển thị "1 running" trong ~100ms thay vì 2-5s.
-
-### Fix 2: Snapshot cache invalidate on `upsertCrewAgent` (MEDIUM IMPACT)
-
-**File**: `src/runtime/crew-agent-records.ts`
-
-After `saveCrewAgents()`, emit invalidate event:
-
-```typescript
-import { runEventBus } from "../ui/run-event-bus.ts";
-
-export function upsertCrewAgent(manifest, record) {
-    // ... existing code ...
-    saveCrewAgents(manifest, merged);
-    writeCrewAgentStatus(manifest, record);
-    // NEW: Immediate UI notification
-    runEventBus.emit({
-        type: "worker_status",
-        runId: manifest.runId,
-        taskId: record.taskId,
-        data: { status: record.status, role: record.role },
-    });
-}
-```
-
-**Impact**: Mỗi lần agent state thay đổi → UI invalidate ngay. Nhưng tốn thêm import + emit overhead.
-
-### Fix 3: Foreground run — emit event after manifest saved (MEDIUM IMPACT)
-
-**File**: `src/extension/team-tool/run.ts`
-
-Sau khi `saveRunManifest()` với status "running", emit:
-
-```typescript
-import { runEventBus } from "../../ui/run-event-bus.ts";
-
-// After saveRunManifest(manifest with status "running")
-runEventBus.emit({
-    type: "run_state",
-    runId: manifest.runId,
-    data: { status: "running" },
-});
-```
-
-**Impact**: Dashboard biết run đã bắt đầu ngay, không phải đợi child process output.
-
-### Fix 4: Widget spinner animation cho "just spawned" agents (LOW IMPACT)
-
-**File**: `src/ui/crew-widget.ts`
-
-Trong `agentActivity()`, nếu agent status "running" nhưng chưa có `progress.currentTool` và chưa có `startedAt` gần đây (< 5s):
-
-```typescript
-if (agent.status === "running") {
-    const age = agent.startedAt ? Date.now() - new Date(agent.startedAt).getTime() : Infinity;
-    if (age < 5000 && !agent.progress?.currentTool) return "spawning…";
-    return agent.progress?.currentTool ? "…" : "thinking…";
-}
-```
-
-**Impact**: User thấy "spawning…" thay vì "thinking…" → biết agent đang được khởi tạo.
-
-### Fix 5: RenderScheduler immediate schedule on run start (HIGH IMPACT)
-
-**File**: `src/extension/register.ts`
-
-Khi `handleRun()` finish (run started), gọi `renderScheduler.schedule()` ngay thay vì đợi preload loop:
-
-```typescript
-// In handleRun(), after run started
-renderScheduler?.schedule();
-```
-
-**Impact**: UI refresh ngay sau khi run started, không đợi preload loop.
-
-## 4. Priority Matrix
-
-| Fix | Impact | Effort | Priority |
-|-----|--------|--------|----------|
-| Fix 1: Emit on task.started | HIGH | LOW | **P0** |
-| Fix 2: Emit on upsertCrewAgent | MEDIUM | LOW | **P1** |
-| Fix 3: Emit on manifest saved | MEDIUM | LOW | **P1** |
-| Fix 4: "spawning…" indicator | LOW | LOW | **P2** |
-| Fix 5: Immediate schedule | HIGH | LOW | **P0** |
-
-## 5. Async Run Specific
-
-Background runs (`async: true`) không thể emit events qua `runEventBus` vì chạy trong process riêng. Options:
-
-1. **Watch manifest file changes**: Dùng `fs.watch()` trên `manifest.json` → invalidate cache khi status change
-2. **Child → Parent IPC**: Background process ghi events vào JSONL → parent poll/read
-3. **Acceptable latency**: Với preload loop 1s, async run visible trong ~1-2s — acceptable cho background tasks
-
-## 6. Recommended Implementation Order
-
-1. **Fix 1 + Fix 5** (P0): Emit event + immediate render on foreground run start
-2. **Fix 4** (P2): "spawning…" indicator cho better UX
-3. **Fix 2** (P1): Broader event emission on agent state changes
-4. **Fix 3** (P1): Dashboard-level run start notification

package/docs/research-awesome-agent-skills-distillation.md

@@ -1,100 +0,0 @@
-# Awesome Agent Skills Distillation for pi-crew
-
-Date: 2026-05-05
-Source repo: `source/awesome-agent-skills` at `859172a` after fast-forward pull from `VoltAgent/awesome-agent-skills`.
-
-## Source Character
-
-`awesome-agent-skills` is a curated index/README of external agent skills, not a vendored skill-source tree. pi-crew should not copy external skill text from linked repositories. This distillation uses high-level themes from the index plus selected detailed reads of linked skills, rewritten as pi-crew-native workflows rather than vendored text.
-
-## Detailed Links Read
-
-Accessible raw GitHub links inspected:
-
-- `obra/superpowers`:
-  - `verification-before-completion/SKILL.md` — evidence before claims; fresh command output required.
-  - `systematic-debugging/SKILL.md` — no fixes without root-cause investigation; four-phase debug loop.
-  - `subagent-driven-development/SKILL.md` — fresh subagent context, staged review checkpoints, DONE/NEEDS_CONTEXT/BLOCKED handling.
-  - `requesting-code-review/SKILL.md` — review early/often with explicit base/head context.
-  - `receiving-code-review/SKILL.md` — verify feedback before implementing; push back with technical evidence.
-  - `using-git-worktrees/SKILL.md` — detect existing isolation, prefer native worktree tools, verify clean baseline.
-  - `finishing-a-development-branch/SKILL.md` — verify tests before merge/PR/discard options.
-  - `test-driven-development/SKILL.md` — red/green/refactor; tests must fail for the intended reason.
-  - `writing-skills/SKILL.md` — trigger-only descriptions, progressive skill structure, pressure-test skills.
-
-Blocked/unavailable in this environment:
-
-- `officialskills.sh` pages for Trail of Bits/OpenAI returned HTTP 403 when fetched directly.
-- Some README paths have moved or are directory-based; missing paths were not treated as source of truth.
-
-Relevant source themes:
-
-- Trail of Bits: clarification, audit context, differential review, insecure defaults, sharp edges, static analysis, testing handbook.
-- OpenAI/Sentry/CodeRabbit/Garry Tan: security review, threat modeling, PR/code review, QA, guardrails, release/deploy verification.
-- Obra/NeoLab community skills: subagent-driven development, testing with subagents, worktrees, verification before completion, recursive decomposition, review checkpoints.
-- Context-engineering entries: context degradation, compression, memory systems, tool design, evaluation frameworks.
-- Skill quality standards: specific descriptions, progressive disclosure, no absolute paths, scoped tools.
-- Security notice: skills are curated but not audited; external skill content can contain prompt injection, tool poisoning, malware payloads, or unsafe data handling.
-
-## Added pi-crew Skills
-
-### `requirements-to-task-packet`
-
-Purpose: convert ambiguous work into task packets with assumptions, scope, non-goals, acceptance criteria, verification, and escalation conditions.
-
-Primary roles: `analyst`, `planner`.
-
-### `secure-agent-orchestration-review`
-
-Purpose: security-review workflow for delegation, skill loading, tool access, prompts, artifacts, config, and session/state ownership.
-
-Primary role: `security-reviewer`.
-
-### `multi-perspective-review`
-
-Purpose: structured review protocol separating correctness, security, tests, maintainability, operator experience, and compatibility.
-
-Primary roles: `reviewer`, `critic`.
-
-### `verification-before-done`
-
-Purpose: completion gate requiring targeted checks, typecheck/integration/full test escalation, evidence, artifacts, risks, and rollback notes.
-
-Primary roles: `executor`, `test-engineer`, `verifier`.
-
-### `context-artifact-hygiene`
-
-Purpose: prevent context poisoning, lost-in-middle failures, stale artifacts, absolute-path leakage, and poor handoffs.
-
-Primary roles: `explorer`, `writer`.
-
-### `systematic-debugging`
-
-Purpose: reproduce/trace/hypothesize/fix loop for failing tests, blocked runs, config pollution, provider/runtime errors, and stale state.
-
-Not currently default-mapped to avoid skill-budget bloat; can be requested by `skill: "systematic-debugging"` or added to future debug workflows.
-
-## Default Role Mapping Changes
-
-Updated `src/runtime/skill-instructions.ts` to use the new distilled skills while keeping prompt budgets small:
-
-- `explorer`: `read-only-explorer`, `context-artifact-hygiene`
-- `analyst`: `read-only-explorer`, `requirements-to-task-packet`
-- `planner`: `delegation-patterns`, `requirements-to-task-packet`
-- `critic`: `read-only-explorer`, `multi-perspective-review`
-- `executor`: `state-mutation-locking`, `safe-bash`, `verification-before-done`
-- `reviewer`: `read-only-explorer`, `multi-perspective-review`
-- `security-reviewer`: `secure-agent-orchestration-review`, `ownership-session-security`
-- `test-engineer`: `verification-before-done`, `safe-bash`
-- `verifier`: `verification-before-done`, `runtime-state-reader`
-- `writer`: `context-artifact-hygiene`, `verify-evidence`
-
-## Rationale
-
-The selected skills are generic, pi-crew-native, and immediately useful for team orchestration. Vendor/framework-specific skills from the index were intentionally skipped because pi-crew is a TypeScript Pi extension and should not bake in unrelated platform instructions.
-
-## Follow-up Ideas
-
-- Add workflow-level `skills:` defaults for debug/recovery workflows that include `systematic-debugging`.
-- Add a `skill-supply-chain-audit` skill if pi-crew later imports external skill bundles automatically.
-- Add documentation to README describing `skill` override usage and project `skills/<name>/SKILL.md` overrides.