pi-crew 0.6.1 → 0.6.3

package/CHANGELOG.md

@@ -1,5 +1,165 @@
 # Changelog
 
+## [0.6.3] — Cross-Platform CI, 87 Test Fixes, Worktree Validation, Heartbeat & Crash Fixes (2026-06-12)
+
+### Highlights
+- **Cross-platform CI green** — 0 failures across Ubuntu, macOS, and Windows (4,725 unit + 113 integration tests)
+- **87 pre-existing test failures resolved** — 0 failures across 4,792 tests in 506 test files
+- **Heartbeat false-positive dead detection fixed** — `message_start` added to progress flush events; PID liveness gate uses `task.checkpoint.childPid` fallback
+- **ENOENT crash on prune/forget race fixed** — 4-layer defense in `persistSingleTaskUpdate`, `persistHeartbeat`, `saveRunTasks`, and `upsertCrewAgent`
+- **Scheduled job lifecycle completed** — spawned runs tracked via `spawnedRunIds[]`, auto-cancelled on job removal, manifests stamped with `schedulerJobId` for traceability
+- **Worktree precondition validation** — friendly error messages instead of crashes when cwd is not a git repo or repo has uncommitted changes
+- **Cross-platform path handling** — `canonicalizePath` with `realpathSync.native` for Windows short-name/long-name aliasing; macOS `/var` → `/private/var` symlink resolution
+- **Pipe buffer deadlock fix** — `spawnSync` with `stdio: 'pipe'` caused deadlock when OS pipe buffer (~64KB) filled at ~227 tests; switched to `stdio: 'inherit'`
+- **Stale lock recovery** — removed `readLockToken` guard so stale locks without 'token' field are properly deleted
+- **Full-feature smoke test** — 58 integration tests covering all pi-crew actions
+- **Pre-push review**: 56 unpushed commits reviewed (116 files, +9,599/−980 lines), 1 release blocker found and fixed
+
+### Bug Fixes
+- **`89ed975`** — Heartbeat watcher: added `message_start` to `shouldFlushProgressEvent()` so LLM stream start updates `lastActivityAt`. Previously, an 8m53s LLM response (365 file reads, no tool calls) triggered false `heartbeat_dead` at 300s threshold.
+- **`9c1bf1f`** — Heartbeat watcher: PID liveness gate uses `task.heartbeat?.pid ?? task.checkpoint?.childPid` fallback. Review team discovered the gate was dead code because `createWorkerHeartbeat(taskId)` never receives PID.
+- **`2bbbb99`** — ENOENT crash: `persistSingleTaskUpdate` recheck stat wrapped in try/catch; `persistHeartbeat` catches ENOENT; `saveRunTasks` guards with `statSync(stateRoot)`; `upsertCrewAgent` skips if stateRoot gone.
+- **`08df7ce`** — Release blocker: `src/errors.ts` enum→const object, `src/state/health-store.ts` parameter property — both incompatible with Node 22 `--experimental-strip-types`.
+- **`3e0b957`** — Sandbox constructor escape detection strengthened.
+- **`dd279bc`** — EBADF (missing O_WRONLY flag), re-entrant sync locks, worktree list parsing, env-filter provider keys.
+- **`38b8f5a`** — Create `transcripts/` directory before child-pi appends.
+- **`d893434`** — Child-pi: remove API key allowlist; child Pi uses same config as parent.
+- **`5cb9122`** — Cross-platform: `canonicalizePath` in `paths.ts` uses `realpathSync.native` for consistent long-name paths on Windows; all test temp dirs canonicalized through `.native`.
+- **`3b46556`** — Cross-platform: `resolvedWorktreeRoot` uses `.native` for git worktree compatibility on Windows; worktree list comparison normalizes through `.native`.
+- **`b2b7068`** — Worktree: precondition validation in `team-tool/run.ts` checks git repo existence and clean leader status before creating run manifest, returning friendly error messages instead of crashing.
+- **`8090fe2`** — Worktree: respect `requireCleanWorktreeLeader` config setting in precondition check.
+- **`2014739`** — Pipe buffer deadlock: `spawnSync` with `stdio: 'pipe'` caused deadlock when OS pipe buffer (~64KB) filled at ~227 tests; switched to `stdio: 'inherit'`.
+- **`d6920bf`** — Stale lock recovery: removed `readLockToken` guard so stale locks without 'token' field are properly deleted.
+- **`3897c1d`** — Mailbox: return paths as-is from `safeMailboxDir`, `safeMailboxFile`, `safeMailboxTasksRoot`, `taskMailboxDir` instead of re-resolving through `resolveRealContainedPath` which changed path forms on Windows.
+- **`f867d4d`** — macOS: `realpathSync(os.tmpdir())` in 3 test files to handle `/var` → `/private/var` symlink.
+- **`2fd0c1e`** — TypeScript: fix Property 'text' and Property 'taskId'→'id' errors for strict compiler checks.
+
+### Test Fixes (87 total)
+- **`1ab7926`** — 33 failures: state-store mtime CAS, locks race, discovery, atomic-write, config-schema, blob-store, env-filter, sandbox, security-hardening, worktree
+- **`bba0bed`** — 3 failures: blob dedup, auto-recovery cap, transcript append
+- **`03dd9b3`** — 14 failures: team-runner, retry-runner, hooks, stale-reconciler, resume-checkpoint, dynamic-script-runner, adaptive-implementation
+- **`a91c316`** — 5 failures: re-entrant sync locks (`withRunLockSync`), `registerWorker()` optional `registeredAt`, `phase8-smoke` PI_TEAMS_HOME isolation, `test-integration-check` PI_CREW_ALLOW_MOCK, `test-bugs-all.mjs` graceful skip
+- **`952c14d`** — 58 full-feature smoke tests added
+
+### Features
+- **`14269f0`** — Scheduler tracks spawned runs: `ScheduledJob.spawnedRunIds[]`, `CrewScheduler.recordSpawnedRun()`, `remove()` calls `runCancelFn` per spawned run, manifests stamped with `schedulerJobId`/`schedulerName`.
+- **`e499570`** — Plugin registry system for framework context injection (Next.js, Vite, Vitest).
+- **`84170c3`** — Team runner integrates plugin registry for framework-aware task context.
+- **`ee466a8`** — Health score system with penalty-based scoring and time-series snapshots.
+- **`daa53ab`** — Atomic write v2 with fsync + rename pattern for crash-safe state persistence.
+- **`6c01f2c`** — CrewError taxonomy: E001–E006 structured error codes.
+- **`2ce143f`** — State-store uses CrewError for structured errors.
+- **`0cd4853`** — Stable task IDs via `stableIdFromContent` for cross-run consistency.
+- **`ff3da92`** — Health snapshot saved on run completion.
+
+### Stats
+- 137 commits since v0.6.1
+- 200 files changed (+16,955 / −2,057 lines)
+- 366 source files, ~70K lines TypeScript
+- 506 test files, ~66K lines TypeScript
+- 4,792 tests, 0 failures
+- CI: Ubuntu ✅ macOS ✅ Windows ✅ (0 failures each)
+
+
+## [0.6.3] — Post-Release Hardening: Cleanup, Safe-Paths, State-Store Race (2026-06-08)
+
+### Highlights
+- **State-store manifest/tasks mtime race fixed** (commits `04fe0be`, `f15ee98`) — `loadRunManifestById` no longer throws on benign mtime skew between `manifest.json` and `tasks.json`. A previous user review (run `team_20260608082852_*`) hit a 4812-second hang because of this throw; the fix prevents the same hang from recurring.
+- **Orphan worker + temp dir cleanup hardened** (8 commits) — 4-layer defense (in-memory Set, per-session temp dir, user-root temp dir, legacy `/tmp` cleanup) with symlink guards, `O_NOFOLLOW` opens, and bounded batch sizes.
+- **`PI_CREW_PARENT_PID` restored to child env allow-list** (commit `e1f7dfe`) — silent regression from a previous round fixed; parent-guard now works again for orphan-worker detection.
+- **`safe-paths.resolveRealContainedPath` extended** (commits `ba0ce54`, `aa457a5`) — now supports creating new files (target does not have to exist) while keeping full symlink-ancestor protection.
+- **`blob-store` metadata race fixed** (commit `5819b18`) — per-hash in-memory lock + atomic write of content-then-metadata prevents concurrent writers from corrupting metadata.
+- **Behavior change: `parent-guard` no longer `.unref()`s its interval** — the guard timer now keeps the event loop alive by design so workers do not exit while their parent is still alive but the worker has no other pending work. See "Behavior Changes" below.
+
+### Security Fixes
+- **`e1f7dfe`** — Restored `PI_CREW_PARENT_PID` in `child-pi.ts` env allow-list. Previous round (`dbf7a48`) replaced `PI_CREW_*`/`PI_TEAMS_*` wildcards with an explicit list but omitted `PI_CREW_PARENT_PID`, silently breaking the parent-guard mechanism.
+- **`ba0ce54` / `aa457a5`** — `safe-paths.resolveRealContainedPath` now allows new-file creation while keeping symlink-ancestor protection. Documented the asymmetric ancestor policy in the function JSDoc.
+- **`e1f7dfe`** (sibling) — `worktree/cleanup.ts` no longer uses `PI_*` / `PI_CREW_*` wildcards in `GIT_SAFE_ENV` (could match secret vars like `PI_PASSWORD`).
+- **`2b8f27a` / `1bf67eb`** — Child env allow-list switched from dangerous wildcards (`*_API_KEY`, `*_TOKEN`, `*_SECRET`, `LC_*`, `XDG_*`, `NPM_*`) to an explicit list of 6 API keys + 12 essential env vars. Eliminates accidental secret leakage via matching name patterns.
+
+### Cleanup Hardening (8 commits)
+- **`5edcb18`** — Track temp dirs globally via in-memory `Set<string>`, cap `reconcileOrphanedTempWorkspaces` scan size, fix cleanup stub.
+- **`8ba270d`** — Move temp dirs from `/tmp` to `~/.pi/agent/pi-crew/tmp/` (uses `userPiRoot()` so `PI_TEAMS_HOME` / `PI_CODING_AGENT_DIR` are respected). Eliminates `/tmp` pollution and unifies state layout.
+- **`ceb1cb1`** — Layer 4 periodic cleanup for orphan prompt/task temp dirs older than 24h.
+- **`a76932d`** — Skip symlinks and in-use dirs during cleanup, plus a one-shot legacy `/tmp` sweep to clean up directories left behind by pre-`8ba270d` installations.
+- **`c9eb430`** — Kill orphan background workers and trigger temp cleanup on `session_start`.
+- **`a192509`** — 4 critical hardening fixes: never `rmSync` a symlink, double-check immediately before delete, skip dirs currently in use, and tear down the global tracker on process exit.
+- **`992231d`** — 24 new unit tests in `test/unit/cleanup-orphan-temp.test.ts` covering each cleanup layer and failure mode.
+- **`dbf7a48`** — UI: replace `console.log` cleanup messages with `notifyOperator` for proper user notification.
+
+### Bug Fixes
+- **`5819b18`** — `blob-store.writeBlob` race condition: per-hash lock + atomic write of content-then-metadata (previously metadata first, leaving orphans on blob write failure).
+- **`04fe0be`** — `state-store.loadRunManifestById` returned `undefined` (was: threw) on manifest/tasks mtime mismatch — the throw caused background runners to crash within 1s of startup.
+- **`f15ee98`** — `state-store.loadRunManifestById` removed the false-positive mtime check entirely. The `saveManifestAndTasksAtomicSync` writer intentionally writes manifest before tasks, so a manifest with newer mtime than tasks is a NORMAL post-write state, not corruption.
+- **`cd7ef89` / `a0c2ba3` / `098c8a9` / `b782424` / `e1ea7d4` / `de3f550` / `2b8f27a` / `1bf67eb`** — 8 deep-review auto-fix commits addressing 78+77+29+28+24+24+24+24 verified issues across the cleanup, state, runtime, and utils modules.
+- **`e1f7dfe`** — `parent-guard.ts` unref'd timers were silently causing worker exit while parent was still alive; restoring the allow-list entry brought the guard back into effect.
+
+### Behavior Changes
+- **`parent-guard.ts` no longer `.unref()`s the guard interval** (revert/restore series `0aed8b5` / `152ac80` / `ee0ddb4` / `81b9608`). The watchdog timer now keeps the event loop alive by design. If a worker has no other pending work (no I/O, no timers, no child processes), the guard interval is the only thing keeping the worker alive until either the parent dies or the worker is explicitly stopped. The previous revert-then-restore pattern ("to test if they cause pi hang") never conclusively identified a root cause; the current state was reached after manual testing. **Mitigation recommended**: add a max-worker-lifetime safety net in a future release.
+
+### New / Heavily Expanded Source Files
+- **`src/runtime/orphan-worker-registry.ts`** (NEW, 307 lines) — PID+start-time+parent-PID verification before SIGKILL; file-locked registry at `<userPiRoot>/state/orphan-workers.json`; honest about residual userspace TOCTOU window between start-time re-check and actual `process.kill`.
+- **`src/runtime/pi-args.ts`** (heavily expanded, 342 lines) — `createSafeTempDir` walks the full ancestor chain rejecting symlinks; `buildPiWorkerArgs` builds the child argv safely (no shell); `cleanupTempDir` / `cleanupAllTrackedTempDirs` / `cleanupOrphanTempDirs` / `cleanupLegacyOrphanTempDirs` provide 4 layers of defense with bounded work.
+
+### Test Coverage
+- **`test/unit/orphan-worker-registry.test.ts`** (NEW, 279 lines) — `registerWorker` / `unregisterWorker` / `cleanupOrphanWorkers` with `__test_setRegistryPath` for isolation; covers invalid PIDs, dedup, parent-PID tolerance, current-session protection, dead-PID pruning.
+- **`test/unit/cleanup-orphan-temp.test.ts`** (NEW, 242 lines) — covers `cleanupTempDir` / `cleanupAllTrackedTempDirs` / `cleanupOrphanTempDirs` / `cleanupLegacyOrphanTempDirs` with `utimesSync` to simulate aged dirs; tests symlink skip, in-use skip, and `/tmp` legacy cleanup.
+- **`test/integration/cleanup-full-flow.test.ts`** (NEW, 241 lines) — end-to-end integration of all cleanup layers, simulating a crashed session.
+
+### Documentation
+- **`src/runtime/parent-guard.ts`** — added a "Trust model" JSDoc section explaining why `PI_CREW_PARENT_PID` is safe to pass in env (PID is not a secret), what residual risks remain (child can spoof before guard starts), and why the guard is a self-termination signal, not a security boundary.
+- **`src/utils/safe-paths.ts:resolveRealContainedPath`** — added a "Security model — asymmetric ancestor handling" JSDoc section explaining why `baseDir` ancestors must exist (cannot validate otherwise) while target ancestors may be non-existent (for new-file creation).
+
+### Stats
+- 23 commits since v0.6.2: `0aed8b5`, `152ac80`, `ee0ddb4`, `81b9608`, `5edcb18`, `8ba270d`, `ceb1cb1`, `a76932d`, `c9eb430`, `a192509`, `992231d`, `dbf7a48`, `e1f7dfe`, `1bf67eb`, `2b8f27a`, `de3f550`, `e1ea7d4`, `5819b18`, `cd7ef89`, `b782424`, `a0c2ba3`, `098c8a9`, `ba0ce54`, `aa457a5`, `04fe0be`, `f15ee98`
+- 79 files changed (+3567 / -712)
+- 1 new state fix: manifest/tasks mtime false positive
+- 1 new file: `orphan-worker-registry.ts` (307 lines)
+- 3 new test files: 762 lines
+
+## [0.6.2] — Issue #28 + #29 Fixes + Post-Review Hardening (2026-06-05)
+
+### Highlights
+- **Issue #28 fixed**: `crew-init.ts` jiti namespace race — inline `parseRoot`/`safeJoin`/`safeDirname`/`safeResolve` helpers; jiti upgraded 2.6.1 → 2.7.0
+- **Issue #29 fixed**: 11 hardcoded `.crew/state/runs/...` sites now use `projectCrewRoot()` for `.pi/teams/` fallback
+- **Subagent defense-in-depth**: `record.promise` rejection can no longer crash pi via `unhandledRejection`
+- **2 new MEDIUM-severity path-traversal vulnerabilities fixed** in `decision-ledger.ts` (7 functions) and `run-graph.ts` (3 functions)
+- **F-8 safeJoin edge case** fixed (trailing separator handling)
+- **~100 new tests** across 7 files (5 e2e scripts + 18 regression tests for the new fixes)
+
+### Security Fixes (MEDIUM)
+- `decision-ledger.ts`: `initLedger`, `appendEntry`, `getLedger`, `getLatestDecision`, `summarizeLedger`, `promoteCandidate`, `decayCandidate` now call `assertSafePathId("runId", runId)` to prevent path-traversal
+- `run-graph.ts`: `saveRunGraph`, `loadRunGraph`, `listRunGraphs` use `projectCrewRoot()` and `assertSafePathId("runId", runId)` (same bug class as issue #29)
+
+### Bug Fixes
+- **F-1** (post-issue-#29 review): removed duplicate "Defense in depth" comment in `subagent-manager.ts`
+- **F-3** (post-issue-#29 review): added F-6 documentation in `test/unit/crew-init.test.ts` header
+- **F-8** (post-issue-#29 review): `safeJoin("/", "foo")` no longer produces `"//foo"`; trailing separator in parts is stripped (UNC paths preserved)
+- **`crew-init.ts safeJoin`**: collapse internal runs of separator while preserving leading UNC `\\\\` and POSIX `/`
+
+### Test Coverage
+- 9 new regression tests in `test/unit/issue-29-pi-paths.test.ts` (resolver precedence, `waitForRun` error message in both layouts, checkpoint/skill-effectiveness round-trip in `.pi/`-only project, decision-ledger path, defense-in-depth via real child process)
+- 13 new tests in `test/unit/crew-init.test.ts` (F-1 UNC preservation, F-2 jiti race via `path` Proxy, F-3 `safeResolve` graceful degradation, F-4 `__test__internals` export convention, F-5 stale docstring, F-6 async-runner rationale, F-8 trailing-separator)
+- 4 new tests in `test/unit/crew-init.test.ts` for `safeJoin` (F-8 regression coverage)
+- 7 new tests in `test/unit/decision-ledger.test.ts` (path-traversal rejection)
+- 3 new tests in `test/unit/run-graph.test.ts` (path-traversal rejection)
+- 14 new tests in `test/unit/skill-effectiveness.test.ts` (cwd parameter migration)
+- 5 new E2E scripts in `scripts/test-issue-29-*.ts`:
+  - `test-issue-29-e2e.ts` — unit-level integration
+  - `test-issue-29-crash.ts` — focused crash reproduction
+  - `test-issue-29-team-tool.ts` — slow-path early-exit error message
+  - `test-issue-29-real-tasks.ts` — full `executeTeamRun` pipeline in `.pi/`-only project (25 assertions)
+  - **`test-issue-29-real-runtime.ts`** — spawns REAL detached `background-runner.ts` process (most realistic)
+
+### Test Quality Improvements
+- **F-4** (post-issue-#29 review): `crew-init.ts findProjectRoot` now accepts optional `path` dep; test passes the `stubPath` Proxy directly to source code (not a copy)
+- **F-5** (post-issue-#29 review): defense-in-depth crash test now spawns a real child process so the host's `unhandledRejection` detector can actually fire (was previously a comment-only test)
+
+### Stats
+- 7 source files changed (3 fixes + 1 new path-resolver usage)
+- 7 test files changed (4 unit + 5 e2e scripts)
+- 9 commits since v0.6.1: `e95e055`, `cd8c3b8`, `a80fe6c`, `362789c`, `0c78307`, `083afaf`, `d33b86c`, `03c0a20`, `1bedd24`, `0ce3d5a`, `b17fb6b`, `f8731e6`, `105d31d`, `00c66a5`, `2d49910`, `6cbbafa`
+
 ## [0.6.1] — Post-v0.6.0 Security Hardening + Test Coverage (2026-06-04)
 
 ### Highlights

package/README.md

@@ -9,26 +9,28 @@ npm: pi-crew
 repo: https://github.com/baphuongna/pi-crew
 ```
 
-**v0.6.1**: See [CHANGELOG.md](CHANGELOG.md).
-
-### Security highlights (v0.6.1)
-
-- **42+ security issues fixed** — 7 CRITICAL, 10 HIGH, 11 MEDIUM, 14 post-restart findings
-- **Timing-safe token comparison** — constant-time compare for lock tokens and request IDs
-- **Environment leak prevention** — `sanitizeEnvSecrets()` on all child process spawns
-- **Shell injection hardened** — `execFileSync` with array args; blocked `String.fromCharCode` bypass
-- **ReDoS-free secret redaction** — linear-time scanning in `redaction.ts`
-- **Sandbox prototype isolation** — `Object.freeze` scoped to VM context; `constructor` pattern blocked
-- **Symlink traversal prevention** — `fs.realpathSync` before path containment checks
-- **Safe-bash line-continuation hardening** — `$\n(evil)` command substitution bypass blocked
-- **Path traversal mitigated** — `resolveContainedPath`/`resolveRealContainedPath` across all file ops
-- **Memory leaks capped** — Maps, Sets, arrays bounded with eviction across all modules
-- **Event log race conditions fixed** — sync/async queue unification
-- **Subagent record sanitization** — allow-listed field persistence
-- **~1,900 new tests**, 113 test files — total suite ~4,600 tests, 0 failures
-- **42+ audit rounds, 160+ issues fixed** across all severity levels
-
-See [SECURITY-ISSUES.md](SECURITY-ISSUES.md) for the full list (SEC-001 – SEC-007 all marked fixed).
+**v0.6.3**: See [CHANGELOG.md](CHANGELOG.md).
+
+### Highlights (v0.6.2 → v0.6.3)
+
+- **137 commits** since v0.6.1 — 200 files changed (+16,955 / −2,057 lines)
+- **4,792 tests**, 506 test files — **0 failures** across the entire suite
+- **Cross-platform CI green** — 0 failures on Ubuntu, macOS, and Windows
+- **366 source files**, ~70K lines of TypeScript
+- **Worktree precondition validation** — friendly errors instead of crashes when cwd is not a git repo or repo is dirty
+- **Cross-platform path handling** — `canonicalizePath` with `realpathSync.native` for Windows short-name/long-name aliasing; macOS symlink resolution
+- **Scheduled job lifecycle** — spawned runs are tracked, cancelling a job kills its runs
+- **Heartbeat false-positive fix** — PID liveness gate prevents dead detection during long LLM responses
+- **ENOENT crash fix** — prune/forget race no longer crashes pi when persisting to deleted runs
+- **Pipe buffer deadlock fix** — test runner no longer deadlocks when OS pipe buffer fills
+- **Plugin registry** — extensible framework context injection for Next.js, Vite, Vitest
+- **Health score system** — penalty-based scoring with time-series snapshots
+- **CrewError taxonomy** — E001–E006 structured error codes replacing raw throws
+- **Atomic write v2** — fsync + rename pattern for crash-safe state persistence
+- **Pre-push review**: 56 unpushed commits reviewed, 1 release blocker found and fixed
+- **Security**: sandbox constructor escape strengthened; env-filter provider key handling fixed
+- **State-store race fix** — manifest/tasks mtime false positive eliminated
+- **Orphan worker/temp cleanup** — 4-layer defense with session-scoped tracking
 
 ---
 
@@ -50,6 +52,9 @@ See [SECURITY-ISSUES.md](SECURITY-ISSUES.md) for the full list (SEC-001 – SEC-
 - **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
+- **Scheduled runs** — `schedule`/`scheduled` actions with cron, interval, and one-shot support; spawned runs tracked and auto-cancelled on job removal
+- **Plugin system** — framework-aware context injection (Next.js, Vite, Vitest) via plugin registry
+- **Health scoring** — penalty-based run health with time-series snapshots
 
 ---
 
@@ -120,13 +125,13 @@ When unsure which team/workflow fits:
 
 ## Builtin Teams
 
-| Team | Workflow | Mục đích |
+| Team | Workflow | Purpose |
 |------|----------|----------|
-| `default` | explore → plan → execute → verify | Cân bằng, đa năng |
-| `fast-fix` | explore → execute → verify | Sửa bug nhỏ nhanh |
-| `implementation` | Adaptive planner quyết fanout | Multi-file implementation |
+| `default` | explore → plan → execute → verify | Balanced, general-purpose |
+| `fast-fix` | explore → execute → verify | Quick bug fixes |
+| `implementation` | Adaptive planner decides fanout | Multi-file implementation |
 | `review` | explore → code-review → security-review → verify | Code review + security audit |
-| `research` | explore → analyze → write | Nghiên cứu và viết tài liệu |
+| `research` | explore → analyze → write | Research and documentation |
 | `parallel-research` | Parallel shards → synthesize → write | Multi-source research |
 
 ## Builtin Agents
@@ -180,7 +185,7 @@ Worktree mode creates an **isolated git worktree per task** — safe for paralle
   "action": "run",
   "team": "implementation",
   "goal": "Refactor auth",
-  "worktree": { "enabled": true }
+  "workspaceMode": "worktree"
 }
 ```
 
@@ -189,10 +194,13 @@ Worktree mode creates an **isolated git worktree per task** — safe for paralle
 ```
 
 Requirements:
-- Git repository
-- Clean working tree (no uncommitted changes in the main worktree)
+- Git repository (cwd must be inside a git repo)
+- Clean working tree (no uncommitted changes in the leader worktree)
+  - Can be disabled via config: `requireCleanWorktreeLeader: false`
 - Worktrees auto-cleanup on run completion/cancel
 
+If preconditions are not met, a friendly error message is returned instead of crashing.
+
 ---
 
 ## Configuration
@@ -255,11 +263,18 @@ Requirements:
 { "action": "artifacts", "runId": "team_..." }
 { "action": "cancel", "runId": "team_..." }
 { "action": "resume", "runId": "team_..." }
+{ "action": "retry", "runId": "team_..." }
+{ "action": "steer", "runId": "team_...", "taskId": "01_explore", "message": "Focus on src/ only" }
+{ "action": "respond", "runId": "team_...", "message": "Answer" }
+{ "action": "wait", "runId": "team_..." }
 
 // Discovery
 { "action": "list" }
-{ "action": "get", "resource": "team", "name": "default" }
+{ "action": "get", "resource": "team", "team": "default" }
+{ "action": "get", "resource": "agent", "agent": "explorer" }
+{ "action": "get", "resource": "workflow", "workflow": "review" }
 { "action": "recommend", "goal": "Refactor auth flow" }
+{ "action": "search", "goal": "heartbeat detection" }
 
 // Resource management
 { "action": "create", "resource": "agent", "config": { "name": "api-reviewer", ... } }
@@ -281,12 +296,34 @@ Requirements:
 { "action": "autonomy", "profile": "assisted" }
 
 // Advanced
-{ "action": "api", "runId": "team_...", "operation": "read-manifest" }
+{ "action": "api", "runId": "team_...", "config": { "operation": "read-manifest" } }
 { "action": "plan", "team": "default", "goal": "..." }
+{ "action": "orchestrate", "planPath": "plan.md", "team": "implementation", "goal": "..." }
+{ "action": "parallel", "config": { "tasks": [{"goal": "...", "agent": "explorer"}] } }
 { "action": "worktrees", "runId": "team_..." }
+{ "action": "graph", "runId": "team_..." }
+{ "action": "explain", "runId": "team_..." }
+{ "action": "health" }
+{ "action": "doctor" }
+{ "action": "cache" }
+{ "action": "invalidate", "runId": "team_..." }
+
+// Scheduled runs
+{ "action": "schedule", "team": "fast-fix", "goal": "Run tests", "cron": "0 9 * * MON" }
+{ "action": "schedule", "team": "default", "goal": "...", "interval": 3600000 }
+{ "action": "schedule", "team": "research", "goal": "...", "once": "+10m" }
+{ "action": "scheduled" }
+
+// Diagnostics & settings
+{ "action": "config" }
+{ "action": "settings" }
+{ "action": "autonomy" }
+{ "action": "anchor" }
+{ "action": "onboard" }
+{ "action": "auto-summarize" }
 ```
 
-📖 Full actions reference (28 actions): [docs/actions-reference.md](docs/actions-reference.md)
+📖 Full actions reference (40+ actions): [docs/actions-reference.md](docs/actions-reference.md)
 
 ---
 
@@ -381,13 +418,13 @@ Your system prompt here.
 ```bash
 cd pi-crew
 npm install          # dependencies
-npm test             # unit + integration tests
+npm test             # unit + integration tests (~4,800 tests)
 npm run typecheck    # tsc --noEmit
 npm run ci           # full CI-equivalent check
 npm pack --dry-run   # package verification
 ```
 
-CI runs on: `ubuntu-latest` · `windows-latest` · `macos-latest`
+Stats: **366 source files** (70K lines) · **506 test files** (66K lines) · **4,792 tests, 0 failures** · **CI: Ubuntu ✅ macOS ✅ Windows ✅**
 
 ---
 

package/docs/issue-29-analysis.md

@@ -0,0 +1,189 @@
+# Issue #29 Analysis: Hardcoded `.crew/state/runs` Path Crashes pi
+
+> **Status**: ANALYZED — no code changes applied (per user request).
+> **Reporter**: sethmorton (external, opened 2026-06-05)
+> **Affects**: pi-crew 0.6.0 / 0.6.1 (issue present in v0.6.1 too — not fixed in any post-v0.6.1 commit as of `e95e055`).
+> **Severity**: **CRITICAL** — full-harness uncaughtException, can crash pi.
+
+---
+
+## 1. Reporter's Claims — Verification Matrix
+
+| Claim | Verified? | Evidence |
+|---|---|---|
+| `waitForRun()` hardcodes `.crew/state/runs/<runId>` at `run-tracker.ts:82` | ✅ YES | `src/runtime/run-tracker.ts:82` — `const runDir = path.join(cwd, ".crew", "state", "runs", runId);` |
+| `projectCrewRoot()` correctly resolves to `.pi/teams/` for `.pi/`-only projects | ✅ YES | `src/utils/paths.ts:88-97` |
+| The throw escapes as an unhandled promise rejection | ✅ PARTIAL | Both direct call sites (`team-tool.ts:817`, `team-tool/run.ts:211,344`) wrap in `try/catch`. **However**, the issue is real when `waitForRun` is called indirectly through `subagent-manager.ts`. |
+| `subagent-manager.ts:250` re-throws via `record.promise` IIFE | ⚠️ LINE-DRIFT | Issue says `~line 250` — in current code (commit `e95e055`), `record.promise` IIFE starts at line 258 and the `throw error;` is at line 281. The mechanism is correct; line numbers drifted from prior code. |
+
+## 2. Root Cause Analysis
+
+### Why it crashes (in `.pi/`-only projects)
+
+`projectCrewRoot(cwd)` (in `src/utils/paths.ts:88-97`) returns:
+
+```
+1. .crew/  (if exists)
+2. .pi/teams/  (if .pi/ exists and .crew/ doesn't)
+3. .crew/  (default, would be created by ensureCrewDirectory)
+```
+
+In a `.pi/`-based project **without** `.crew/`, run state lives at:
+```
+.pi/teams/state/runs/<runId>/
+```
+
+But `waitForRun()` (line 82) hardcodes:
+```
+.crew/state/runs/<runId>/
+```
+
+The early-exit check `fs.existsSync(runDir)` returns `false`, throwing:
+```
+Error: Run <runId> not found. No run directory at <cwd>/.crew/state/runs/<runId>
+```
+
+### Why this becomes a `uncaughtException`
+
+The throw in `waitForRun` propagates differently depending on caller:
+
+| Caller | Wrapped in try/catch? | Result |
+|---|---|---|
+| `team-tool.ts:817` (wait action) | ✅ YES | Returns error to user — safe |
+| `team-tool/run.ts:211` (async.run) | ✅ YES | Returns error to user — safe |
+| `team-tool/run.ts:344` (foreground) | ✅ YES | Returns error to user — safe |
+| **`subagent-manager.ts:270` (pollRunToTerminal)** | ⚠️ **NO** | `record.promise` rejects → line 281 `throw error` re-throws → if no caller awaits → **unhandled rejection** |
+
+The `subagent-manager.ts` path is the actual crash site. Direct `waitForRun` calls in `team-tool.ts` are safe.
+
+### Why the run "exists" in `.pi/teams/...`
+
+The background worker process (`background-runner.ts`) correctly **reads/writes** to the right path **once it uses `projectCrewRoot()`** — but it does NOT. The same hardcoding is present in `background-runner.ts:139, 172`. So the **background worker itself is writing to `.crew/state/runs/...` (wrong path)**, while the **manifest claims it lives at `.pi/teams/state/runs/...`** (correct path).
+
+Wait — let me re-verify this. The manifest is created by which process?
+
+Actually, the **run manifest is created at the orchestrator** (using `projectCrewRoot`), and the **background worker reads/writes log/exit-code files using the same wrong path**. The manifest's `stateRoot` field is correct (`.pi/teams/...`), but the background worker writes its log to `<cwd>/.crew/state/runs/.../background.log`, which is the wrong path.
+
+Result: the manifest correctly points to `.pi/teams/...` but the background worker logs/exit-codes go to `.crew/.../background.log`. The manifest loader (`loadRunManifestById` → `scopeBaseRoot` → `projectCrewRoot`) reads from the correct path. So if the manifest is created and persists, polling SHOULD work. The early-exit `fs.existsSync` check fires only on the very first poll iteration before any manifest has been written.
+
+## 3. Affected Sites — Complete Inventory
+
+Hardcoded `.crew/state/runs/...` paths that ignore `projectCrewRoot()`:
+
+| File | Line | Code | Used for |
+|---|---|---|---|
+| `src/runtime/run-tracker.ts` | 82 | `path.join(cwd, ".crew", "state", "runs", runId)` | **CRASH SITE**: `waitForRun()` early-exit |
+| `src/runtime/background-runner.ts` | 139 | `path.join(_cwd, ".crew/state/runs", _runId, "background.log")` | Background worker log redirect |
+| `src/runtime/background-runner.ts` | 172 | `path.join(cwd, ".crew", "state", "runs", runId, "exit-code.txt")` | Exit code persistence |
+| `src/runtime/skill-effectiveness.ts` | 115 | `join(process.cwd(), ".crew/state/runs/${runId}/skill-metrics.jsonl")` | Skill metrics storage |
+| `src/runtime/skill-effectiveness.ts` | 125 | `join(process.cwd(), ".crew/state/runs/${runId}/skill-activations.jsonl")` | Skill activation storage |
+| `src/runtime/checkpoint.ts` | 166 | `path.join(process.cwd(), ".crew/state/runs", runId)` | `saveCheckpoint` |
+| `src/runtime/checkpoint.ts` | 177 | `path.join(process.cwd(), ".crew/state/runs", runId)` | `loadCheckpoint` |
+| `src/runtime/checkpoint.ts` | 188 | `path.join(process.cwd(), ".crew/state/runs", runId)` | `clearCheckpoint` |
+| `src/runtime/checkpoint.ts` | 199 | `path.join(process.cwd(), ".crew/state/runs", runId)` | `hasCheckpoint` |
+| `src/runtime/checkpoint.ts` | 209 | `path.join(process.cwd(), ".crew/state/runs", runId)` | `listCheckpoints` |
+| `src/state/decision-ledger.ts` | 29 | `stateRoot ?? \`.crew/state/runs/${runId}\`` | `getLedgerPath` fallback (always hit when called without `stateRoot`) |
+
+**11 sites across 5 files** confirmed affected.
+
+### Already correct (for reference)
+
+| File | Line | Why correct |
+|---|---|---|
+| `src/state/crew-init.ts` | 209 | `safeJoin(crewRoot, "state", "runs")` — uses `crewRoot` parameter |
+| `src/extension/team-tool.ts` | 1210 | `path.join(projectCrewRoot(ctx.cwd), "state", "runs", params.runId)` ✓ |
+| `src/extension/team-onboard.ts` | 28 | `path.join(crewRoot, "state", "runs")` — uses parameter |
+| `src/runtime/stale-reconciler.ts` | 389 | Inside `tmpDir` workspace scan — these are pi-crew's own zombie workspaces, not user `.pi/` projects, so this is acceptable (but inconsistent) |
+
+## 4. Why the Bug Survives (it should have been caught)
+
+- ✅ `loadRunManifestById` and `loadRunManifestByIdAsync` in `state-store.ts` correctly use `projectCrewRoot()` via `scopeBaseRoot` → `useProjectState`.
+- ❌ `waitForRun()` and the 10 other sites above bypass the resolver and hardcode the path.
+- The hardcoded path is **inconsistent** with the resolver — clearly a copy-paste/regression.
+- The issue is **only triggered in `.pi/`-only projects** (no `.crew/`). Standard `.crew/` projects (the original pi-crew use case) never hit it.
+
+## 5. Recommended Fix (NOT APPLIED per user request)
+
+### Phase 1 — Use the resolver everywhere
+
+Replace each hardcoded path with:
+
+```ts
+import { projectCrewRoot } from "../utils/paths.ts";
+// ...
+const stateRoot = path.join(projectCrewRoot(cwd), "state", "runs", runId);
+```
+
+For sites that take `process.cwd()`, switch to taking a `cwd` parameter (callers pass the real cwd). This is a small refactor for `skill-effectiveness.ts` and `checkpoint.ts` since their current API uses `process.cwd()`.
+
+### Phase 2 — Defense in depth (the reporter's second suggestion)
+
+The reporter's point about `subagent-manager.ts` is also valid: **a single run failure should never crash the harness**. The current pattern at line 281 `throw error; // H4: Propagate rejection` deliberately rejects the promise, but if no one awaits it, it becomes unhandled.
+
+Two options:
+
+**A) Add a safety net in `subagent-manager.ts` (recommended)**:
+
+```ts
+private start(record: SubagentRecord, ...) {
+  // ...
+  record.promise = (async () => { ... })();
+  // Defense in depth: a subagent failure should never crash pi.
+  // Attach a no-op catch so that even if no caller awaits, the rejection
+  // doesn't propagate to unhandledRejection → uncaughtException.
+  record.promise.catch((error) => {
+    logInternalError("subagent-manager.start.unhandled", error, `id=${record.id}`);
+  });
+}
+```
+
+This protects the harness against **any** future rejection path, not just the one fixed in Phase 1.
+
+**B) Remove the `throw error;` at line 281** — the record is already marked `error` status, the caller can read it. This is a deeper change to the API contract.
+
+Option (A) is the smaller, safer change.
+
+## 6. Test Coverage
+
+Tests exist for `checkpoint` (`checkpoint.test.ts`, `checkpoint-cov.test.ts`) and `skill-effectiveness` (`skill-effectiveness.test.ts`) but they likely use a `.crew/`-based temp project, so they wouldn't catch this bug. A regression test should:
+
+1. Create a temp project with `.pi/` (no `.crew/`)
+2. Call each affected function (`waitForRun`, `saveCheckpoint`, `getSkillMetricsPath`, etc.)
+3. Assert the result path is `.pi/teams/...` (not `.crew/...`)
+
+For the `subagent-manager.ts` defense-in-depth: spawn a subagent whose `runner` rejects, assert pi does not exit and the record is marked `error`.
+
+## 7. Impact Assessment
+
+- **Blast radius**: All pi-crew users with `.pi/`-only projects.
+- **Trigger frequency**: Low — requires the background worker to fail/die AND `waitForRun` to be called indirectly via `subagent-manager.ts`. The `team-tool` direct paths are safe.
+- **Severity**: CRITICAL — full-harness crash with misleading "Run not found" error pointing at a path that, by design, should never exist.
+
+## 8. Recommended PR Description (draft)
+
+> **Title**: fix(issue #29): use projectCrewRoot() for run-state paths in all 11 affected sites
+>
+> **Body**:
+>
+> The `.pi/`-based project layout (`.pi/teams/`) is not handled by the 11 hardcoded `.crew/state/runs/...` sites listed in the analysis. The most severe site is `waitForRun()` in `src/runtime/run-tracker.ts:82`, which throws on a non-existent path and (via `subagent-manager.ts:281`) can escape as an unhandled rejection that crashes pi.
+>
+> Fix:
+> 1. Replace all 11 hardcoded paths with `path.join(projectCrewRoot(cwd), "state", "runs", runId)`.
+> 2. For sites that use `process.cwd()` (`skill-effectiveness.ts`, `checkpoint.ts`), switch to taking a `cwd` parameter.
+> 3. Add `record.promise.catch(...)` in `subagent-manager.ts:start()` as defense in depth — a subagent failure should never crash the harness.
+> 4. Add regression tests using a `.pi/`-only temp project.
+>
+> Closes #29.
+
+---
+
+## Status
+
+- ✅ Issue reproduced in code (all 11 sites verified)
+- ✅ Root cause identified
+- ✅ Fix plan drafted
+- ❌ **Code changes NOT applied** (per user request: "chưa thực hiện sửa gì cả")
+- ❌ Tests NOT added
+- ❌ v0.6.2 NOT released
+
+Sẵn sàng apply khi user yêu cầu.