pi-crew 0.2.2 → 0.2.4

package/docs/followup-review-round4-2026-05-13.md

@@ -0,0 +1,107 @@
+# Follow-up Review Round 4 — 2026-05-13
+
+Review of commits `c7bd455` through `5f47e92` (7 commits on top of `faa81e4`).
+
+## Summary
+
+These commits harden live-session runtime cleanup, async runner lifecycle, crew-agent persistence, and Windows test flakiness. Overall quality is high and the fixes address real production issues. However, one commit introduces a **regression** that breaks the resume/follow-up capability for completed live-session agents. Two other issues could cause crashes or races in edge cases.
+
+**All identified bugs have been fixed in commits `a8a43b4` through current working tree.**
+
+---
+
+## Critical — FIXED
+
+### BUG-014: `removeLiveAgentHandle` on normal completion destroys resume capability
+
+**File:** `src/runtime/live-session-runtime.ts` (finally block, line ~610)  
+**Commit:** `7a25644` → **Fixed in a8a43b4**
+
+The finally block calls `removeLiveAgentHandle(agentId)` for non-aborted completions. This **deletes the live-agent handle from the registry entirely**, including its terminal status.
+
+**Impact:** After a live-session task completes normally, `steerLiveAgent`, `followUpLiveAgent`, and `resumeLiveAgent` all fail with "Live agent '...' is not registered in this process."
+
+**Fix:** Added `disposeLiveAgentSession()` in `live-agent-manager.ts` — disposes session resources but keeps the handle in the registry for resume/follow-up.
+
+---
+
+## High — FIXED
+
+### BUG-015: `withAgentsLock` crashes on `EISDIR` from corrupted lock path
+
+**File:** `src/runtime/crew-agent-records.ts`  
+**Commit:** `c7bd455` → **Fixed in a8a43b4**
+
+`withAgentsLock` only caught `EEXIST`; if lock path was a directory, `EISDIR` crashed the process.
+
+**Fix:** Handle `EISDIR` by removing the directory and retrying.
+
+---
+
+## Medium — FIXED
+
+### BUG-016: `markActiveTasksAndAgentsFailed` lacks run-level lock, races with crash recovery
+
+**File:** `src/extension/async-notifier.ts`  
+**Commit:** `d6d466d` → **Fixed in current working tree**
+
+`markActiveTasksAndAgentsFailed` called `saveRunTasks` and `saveCrewAgents` without `withRunLockSync`. Crash recovery (`cancelOrphanedRuns`) uses `withRunLockSync`. Concurrent execution on the same run risks lost updates.
+
+**Fix:** Wrapped `markDeadAsyncRunIfNeeded` mutations inside `withRunLockSync(run, () => { ... })`. Also reloaded fresh manifest inside the lock to avoid operating on stale data.
+
+---
+
+## Low — FIXED
+
+### BUG-017: `safeDisposeLiveSession` catches all errors silently
+
+**File:** `src/runtime/live-agent-manager.ts`  
+**Commit:** `7a25644` → **Fixed in current working tree**
+
+Any exception from `dispose()` was swallowed without logging.
+
+**Fix:** Log disposal errors via `logInternalError`.
+
+### BUG-018: `effectiveRuntime` in `run.ts` is manually constructed
+
+**File:** `src/extension/team-tool/run.ts`  
+**Commit:** `2486051` → **Fixed in current working tree**
+
+The async fallback runtime was manually built field-by-field. If `CrewRuntimeCapabilities` gains a new required field, this site won't inherit it.
+
+**Fix:** Use spread of original runtime with overrides: `{ ...runtime, kind: "child-process", steer: false, resume: false, liveToolActivity: false, fallback: "child-process", reason: "..." }`.
+
+### NIT-007: `removeStaleAgentsLock` reads unlimited file size
+
+**File:** `src/runtime/crew-agent-records.ts`  
+**Commit:** `c7bd455` → **Fixed in current working tree**
+
+`fs.readFileSync(lockPath, "utf-8")` reads entire file into memory. Corrupted multi-megabyte file causes memory pressure.
+
+**Fix:** Check `fs.statSync(lockPath).size > 1024` before reading; skip stale removal if oversized.
+
+### NIT-008: `maxCollectedJsonEvents` cap is hardcoded at 200
+
+**File:** `src/runtime/live-session-runtime.ts`  
+**Commit:** `c7bd455` → **Fixed in current working tree**
+
+Long-running agents drop older JSON events needed for debugging/yield detection.
+
+**Fix:** Increased cap from 200 to 1000.
+
+---
+
+## Verification
+
+- `npm run typecheck` passes.
+- Targeted tests (`async-notifier`, `isolation-policy`, `live-agent-manager`, `live-session-runtime`, `team-tool-dispatch`) pass: **31 pass / 0 fail**.
+- Full unit test suite not run due to time constraints; no new failures observed in targeted runs.
+
+## Files Changed in Fixes
+
+- `src/extension/async-notifier.ts` — BUG-016 (run lock)
+- `src/runtime/live-agent-manager.ts` — BUG-014 (disposeLiveAgentSession), BUG-017 (log dispose errors)
+- `src/runtime/live-session-runtime.ts` — BUG-014 (use disposeLiveAgentSession), NIT-008 (cap 1000)
+- `src/runtime/crew-agent-records.ts` — BUG-015 (EISDIR), NIT-007 (size cap)
+- `src/extension/team-tool/run.ts` — BUG-018 (spread runtime)
+- `test/unit/live-agent-manager.test.ts` — test for disposeLiveAgentSession

package/docs/implementation-plan-top3.md

@@ -0,0 +1,333 @@
+# Implementation Plan: Top 3 Features from oh-my-pi v15
+
+> Date: 2026-05-13
+> Based on: `D:/my/my_project/source/oh-my-pi` research
+> Target: pi-crew v0.2.x
+
+---
+
+## Priority Order
+
+1. **Typed Crew Errors** — Quick win, no dependencies
+2. **Conflict Detection** — High value, standalone module
+3. **Issue-PR Protocol** — Medium complexity, GitHub integration
+
+---
+
+## 1. Typed Crew Errors
+
+### Why
+Current pi-crew uses generic `Error` types with string matching:
+```typescript
+catch (e) {
+  if (e instanceof Error && e.message.includes("deadletter")) { ... }
+}
+```
+
+Pattern from oh-my-pi: use typed sentinel errors with `instanceof` discrimination.
+
+### Files to create/modify
+
+**Create:** `src/runtime/errors/crew-errors.ts`
+
+```typescript
+/**
+ * Typed error sentinels for pi-crew operations.
+ * Follows oh-my-pi pattern from compaction/errors.ts.
+ */
+
+export class CrewCancelledError extends Error {
+  readonly name = "CrewCancelledError" as const;
+  constructor(message = "Crew run cancelled") { super(message); }
+}
+
+export class CrewTimeoutError extends Error {
+  readonly name = "CrewTimeoutError" as const;
+  constructor(public readonly maxDurationMs: number) {
+    super(`Crew run exceeded timeout of ${maxDurationMs}ms`);
+  }
+}
+
+export class CrewDeadletterError extends Error {
+  readonly name = "CrewDeadletterError" as const;
+  constructor(
+    public readonly agentId: string,
+    public readonly reason: string,
+  ) {
+    super(`Agent ${agentId} deadlettered: ${reason}`);
+  }
+}
+
+export class CrewAbortError extends Error {
+  readonly name = "CrewAbortError" as const;
+  constructor(message = "Crew run aborted") { super(message); }
+}
+
+export class CrewManifestError extends Error {
+  readonly name = "CrewManifestError" as const;
+  constructor(message: string, public readonly runId?: string) { super(message); }
+}
+
+export class CrewLockError extends Error {
+  readonly name = "CrewLockError" as const;
+  constructor(message: string, public readonly lockPath?: string) { super(message); }
+}
+
+/**
+ * Outcome of a crew run attempt.
+ * Used by RunTracker and HealthWatcher.
+ */
+export type CrewRunOutcome = "ok" | "cancelled" | "deadletter" | "failed" | "timeout" | "aborted";
+```
+
+**Update:** `src/runtime/task-runner.ts`, `src/runtime/team-runner.ts`, `src/runtime/crash-recovery.ts`
+
+Replace string matching with `instanceof` checks.
+
+### Implementation
+
+```bash
+# 1. Create file
+cat > src/runtime/errors/crew-errors.ts << 'EOF'
+// (content above)
+EOF
+
+# 2. Update imports in affected files
+# From: catch (e) { if (e instanceof Error && e.message.includes("deadletter")) ... }
+# To: catch (e) { if (e instanceof CrewDeadletterError) ... }
+```
+
+### Effort: LOW (1-2 hours)
+
+---
+
+## 2. Conflict Detection
+
+### Why
+When multiple pi-crew agents edit the same file in a worktree, git merge conflicts can occur. Current pi-crew has no conflict detection — agents see garbled `<<<<<<< HEAD` markers with no structured way to resolve them.
+
+### Architecture
+
+```
+pi-crew worktree agents edit files
+         ↓
+   WorktreeManager detects file change
+         ↓
+   ConflictDetector.scanFileForConflicts(path)
+         ↓
+   Returns ConflictBlock[] + registers in ConflictHistory
+         ↓
+   Read tool appends conflict warning footer
+         ↓
+   Agent calls write({ path: "conflict://<id>", content })
+         ↓
+   ConflictResolver.spliceConflict() → clean file
+```
+
+### Files to create
+
+**Create:** `src/utils/conflict-detect.ts` (fork from oh-my-pi, ~400 lines)
+
+Key exports:
+- `scanConflictLines(lines, firstLineNumber)` → `ConflictBlock[]`
+- `scanFileForConflicts(path)` → `{ blocks, scanTruncated }`
+- `ConflictHistory` class
+- `ConflictEntry` interface
+- `parseConflictUri(raw)` → `ParsedConflictUri | null`
+- `spliceConflict(text, entry, replacement)` → `string`
+- `expandContentTokens(content, entry)` → `string` (handles @ours/@theirs/@base/@both)
+- `renderConflictRegion(entry, scope)` → `{ lines, startLine }`
+- `formatConflictWarning(entries)` → `string`
+
+**Create:** `src/runtime/conflict-registry.ts`
+
+```typescript
+/**
+ * Global conflict registry for pi-crew.
+ * Attaches ConflictHistory to each live session.
+ */
+import { ConflictHistory, getConflictHistory } from "../utils/conflict-detect.ts";
+import type { LiveAgentHandle } from "./live-agent-manager.ts";
+
+export function getAgentConflicts(handle: LiveAgentHandle): ConflictHistory {
+  if (!handle.conflictHistory) {
+    handle.conflictHistory = new ConflictHistory();
+  }
+  return handle.conflictHistory;
+}
+```
+
+**Modify:** `src/extension/registration/tools/read-tool.ts`
+
+After reading file content:
+1. Call `scanConflictLines(lines, 1)`
+2. For each block, call `conflictHistory.register(...)`
+3. Append `formatConflictWarning(entries)` to output
+
+**Modify:** `src/extension/registration/tools/write-tool.ts`
+
+Add `conflict://<N>` handling:
+1. Parse URI with `parseConflictUri(path)`
+2. Look up `ConflictEntry` from `ConflictHistory`
+3. Call `expandContentTokens(content, entry)`
+4. Call `spliceConflict(originalText, entry, expandedContent)`
+5. Write result to `entry.absolutePath`
+
+### Integration points
+
+| File | Change |
+|------|--------|
+| `src/extension/registration/tools/read-tool.ts` | Append conflict warning to file content |
+| `src/extension/registration/tools/write-tool.ts` | Handle `conflict://` protocol |
+| `src/runtime/live-agent-manager.ts` | Add `conflictHistory?: ConflictHistory` to handle |
+| `src/utils/conflict-detect.ts` | New file (fork from oh-my-pi) |
+| `src/runtime/conflict-registry.ts` | New file (global registry) |
+
+### Edge cases to handle
+
+1. **Nested conflicts** — oh-my-pi handles by requiring strict marker shape
+2. **Multi-file conflicts** — `ConflictHistory.invalidatePath()` when file is resolved
+3. **Retry after partial resolution** — `ConflictEntry` id stays stable
+4. **Large files** — `scanFileForConflicts` caps at 10MB
+5. **Diff3 conflicts** — Support `|||||||` base section
+
+### Test plan
+
+```typescript
+// test/unit/conflict-detect.test.ts
+test("scanConflictLines detects single 2-way block", () => {
+  const lines = ["<<<<<<< HEAD", "our changes", "=======", "their changes", ">>>>>>> feature"];
+  const blocks = scanConflictLines(lines, 1);
+  assert(blocks.length === 1);
+  assert(blocks[0].oursLines[0] === "our changes");
+});
+
+test("scanConflictLines ignores non-column-0 markers", () => {
+  const lines = ["  <<<<<<< indented", "=======", ">>>>>>>"];
+  const blocks = scanConflictLines(lines, 1);
+  assert(blocks.length === 0);
+});
+
+test("scanConflictLines detects diff3 3-way block", () => {
+  // ...with ||||||| base marker
+});
+```
+
+### Effort: MEDIUM (4-8 hours)
+
+---
+
+## 3. Issue-PR Protocol
+
+### Why
+pi-crew workflow agents can benefit from issue/PR integration:
+- Create issue from failed task
+- Link workflow tasks to GitHub issues
+- PR review workflow (`pr://` protocol)
+
+### URL shapes to support
+
+```
+issue://              — list recent issues (default repo from cwd)
+issue://owner/repo    — list issues for repo
+issue://123           — single issue (repo from cwd)
+issue://owner/repo/123 — fully qualified
+issue://owner/repo/123?comments=0 — suppress comments
+
+pr://                 — list recent PRs
+pr://owner/repo       — list PRs for repo
+pr://owner/repo/456  — single PR
+pr://owner/repo/456/diff — PR diff
+```
+
+### Files to create/modify
+
+**Create:** `src/internal-urls/issue-pr-protocol.ts` (port from oh-my-pi, ~577 lines)
+
+Key exports:
+- `IssuePrProtocol` class implementing `ProtocolHandler`
+- `parseIssueUrl(url)` → `ParsedIssue`
+- `parsePrUrl(url)` → `ParsedPr`
+- `fetchIssue(parsed)` → `string` (markdown)
+- `fetchPr(parsed)` → `string` (markdown)
+- `fetchPrDiff(parsed)` → `string` (unified diff)
+
+**Modify:** `src/internal-urls/router.ts`
+
+Register `issue://` and `pr://` handlers.
+
+**Create:** `src/tools/gh-cache.ts` (fork from oh-my-pi `tools/github-cache.ts`)
+
+SQLite-backed cache for GitHub API responses. Shared across sessions.
+
+### Dependencies
+
+1. **GitHub CLI (`gh`)** — oh-my-pi uses `gh issue list`, `gh pr list`, `gh api`
+2. **SQLite** — via `better-sqlite3` or similar
+3. **Git config** — Need to resolve default repo from `git remote get-url origin`
+
+### Implementation details
+
+```typescript
+interface ParsedIssue {
+  kind: "single" | "list";
+  repo?: string;  // undefined = derive from cwd
+  number?: number;
+  state?: "open" | "closed" | "all";
+  limit?: number;
+  comments?: boolean;
+}
+
+interface ParsedPr {
+  kind: "single" | "list" | "diff";
+  repo?: string;
+  number?: number;
+  state?: "open" | "closed" | "merged" | "all";
+  limit?: number;
+  diffMode?: "list" | "all";
+}
+```
+
+**Fetching:**
+- List: `gh issue list --repo owner/repo --state open --limit 30`
+- Single: `gh issue view 123 --repo owner/repo --comments`
+- PR: `gh pr view 456 --repo owner/repo --comments`
+- Diff: `gh pr diff 456 --repo owner/repo`
+
+**Caching:**
+- Cache key: `{repo, number, type}` hash
+- TTL: 5 minutes for list, 1 hour for single items
+- Invalidate on write operations (create/close/reopen)
+
+### Integration with pi-crew
+
+**New tool:** `read-issue` / `read-pr`
+```typescript
+// agents có thể gọi:
+// read({ path: "issue://123" }) → markdown của issue
+// read({ path: "pr://456" }) → markdown của PR
+```
+
+**New slash command:** `/issue` hoặc dùng existing `/crew`:
+```
+/crew create-issue "Task failed: fix memory leak in cache" --labels=bug --assignee=me
+/crew link-issue TICKET-123 --task=explorer-1
+```
+
+### Effort: MEDIUM-HIGH (8-12 hours)
+
+---
+
+## Summary
+
+| Feature | Effort | Risk | Priority |
+|---------|--------|------|----------|
+| Typed Crew Errors | LOW | None | 1 |
+| Conflict Detection | MEDIUM | Git operations, large file handling | 2 |
+| Issue-PR Protocol | MEDIUM-HIGH | GitHub auth, gh CLI dependency | 3 |
+
+## Recommended execution order
+
+1. **Day 1:** Typed Crew Errors (quick win)
+2. **Day 2-3:** Conflict Detection
+3. **Day 4-5:** Issue-PR Protocol (if time permits)

package/docs/live-mailbox-runtime.md

@@ -1,36 +1,36 @@
-# Live Mailbox Runtime Direction
-
-`pi-crew` currently uses workflow child-process orchestration: a run materializes tasks, executes them through the scheduler, writes artifacts/events, and optionally launches child Pi workers.
-
-A full live mailbox runtime is intentionally out of scope for the current stable surface. Current foundational mailbox files are intentionally simple and local:
-
-```text
-{stateRoot}/mailbox/inbox.jsonl
-{stateRoot}/mailbox/outbox.jsonl
-{stateRoot}/mailbox/delivery.json
-{stateRoot}/mailbox/tasks/{taskId}/inbox.jsonl
-{stateRoot}/mailbox/tasks/{taskId}/outbox.jsonl
-```
-
-They are exposed through safe API operations (`read-mailbox`, `send-message`, `ack-message`, `read-delivery`, `validate-mailbox`) but do not yet imply always-on long-lived workers. If a full runtime is added later, it should build on the foundations already present:
-
-- `src/state/contracts.ts` for status/event contracts
-- `src/state/task-claims.ts` for claim/lease safety
-- `src/runtime/worker-heartbeat.ts` for liveness
-- `src/state/locks.ts` for run-level mutation safety
-- `action: "api"` for safe interop boundaries
-
-## Proposed phases
-
-1. **Read-only interop** — already started with `api` operations.
-2. **Heartbeat writers** — allow workers to update heartbeat/progress safely.
-3. **Claim-safe task lifecycle** — expose claim/release/transition operations with tokens.
-4. **Mailbox** — add worker inbox/leader inbox files and delivery state.
-5. **Live workers** — only after the above contracts are stable.
-
-## Non-goals for now
-
-- No always-on background worker pool.
-- No automatic destructive cleanup of dirty worktrees.
-- No recursive team spawning by workers.
-- No mailbox mutation without locks and schema validation.
+# Live Mailbox Runtime Direction
+
+`pi-crew` currently uses workflow child-process orchestration: a run materializes tasks, executes them through the scheduler, writes artifacts/events, and optionally launches child Pi workers.
+
+A full live mailbox runtime is intentionally out of scope for the current stable surface. Current foundational mailbox files are intentionally simple and local:
+
+```text
+{stateRoot}/mailbox/inbox.jsonl
+{stateRoot}/mailbox/outbox.jsonl
+{stateRoot}/mailbox/delivery.json
+{stateRoot}/mailbox/tasks/{taskId}/inbox.jsonl
+{stateRoot}/mailbox/tasks/{taskId}/outbox.jsonl
+```
+
+They are exposed through safe API operations (`read-mailbox`, `send-message`, `ack-message`, `read-delivery`, `validate-mailbox`) but do not yet imply always-on long-lived workers. If a full runtime is added later, it should build on the foundations already present:
+
+- `src/state/contracts.ts` for status/event contracts
+- `src/state/task-claims.ts` for claim/lease safety
+- `src/runtime/worker-heartbeat.ts` for liveness
+- `src/state/locks.ts` for run-level mutation safety
+- `action: "api"` for safe interop boundaries
+
+## Proposed phases
+
+1. **Read-only interop** — already started with `api` operations.
+2. **Heartbeat writers** — allow workers to update heartbeat/progress safely.
+3. **Claim-safe task lifecycle** — expose claim/release/transition operations with tokens.
+4. **Mailbox** — add worker inbox/leader inbox files and delivery state.
+5. **Live workers** — only after the above contracts are stable.
+
+## Non-goals for now
+
+- No always-on background worker pool.
+- No automatic destructive cleanup of dirty worktrees.
+- No recursive team spawning by workers.
+- No mailbox mutation without locks and schema validation.