pi-crew 0.5.14 → 0.5.17

package/CHANGELOG.md

@@ -1,5 +1,176 @@
 # Changelog
 
+## [0.5.17] — Security Hardening + ECC Patterns + Skill Review (2026-06-03)
+
+### Highlights
+- **3 CRITICAL security fixes**: path traversal, sandbox escape, executeUnchecked bypass
+- **3 HIGH security fixes**: allowPatterns bypass, safe-bash fallback message, mock mode
+- **3 MEDIUM security fixes**: home hooks visibility, API keys documentation, sync lock deprecation
+- **2 new features** from ECC/dmux patterns: seedPaths overlay + structured handoff template
+- **2 gap fills**: handoff parser + per-step seedPaths
+- **36 skills reviewed**: origin fields, broken refs fixed, verify-skill.ts updated
+- **1 bug fix**: adaptive-plan parser strips markdown code fences
+- **1 regression fix**: mock mode NODE_ENV gate reverted
+- **41 new tests** across 6 test files
+
+### Security Fixes
+
+#### CRITICAL
+1. `orchestrate.ts`: Path traversal — planPath validated with `resolveContainedPath()`
+2. `sandbox.ts`: Prototype pollution — `Object.freeze` on prototypes, `globalThis`/`global` in FORBIDDEN_PATTERNS
+3. `dynamic-script-runner.ts`: `executeUnchecked` → private, `__test_executeUnchecked` test-only export
+
+#### HIGH
+4. `safe-bash.ts`: allowPatterns validation rejects `/.*/` and permissive catch-all patterns
+5. `safe-bash-extension.ts`: Error message no longer suggests bypassing safe-bash
+6. `child-pi.ts`: Mock mode requires `PI_CREW_ALLOW_MOCK=1` (set in parent process only)
+
+#### MEDIUM
+7. `worktree-manager.ts`: `logInternalError` warning when home directory hooks accepted
+8. `child-pi.ts`: SECURITY WARNING JSDoc on API key allow-list trade-off
+9. `event-log.ts`: Expanded deprecation notice on `withEventLogLockSync` blocking behavior
+
+### Features (ECC/dmux patterns)
+
+- **seedPaths**: Overlay local/uncommitted files into worktrees via config (`worktree.seedPaths`) or per-step (`WorkflowStep.seedPaths`). Path traversal validation, dedup, recursive copy.
+- **Structured Handoff Template**: `HANDOFF_TEMPLATE` constant + `parseHandoffFromOutput()` parser. Agents receive handoff format instructions automatically.
+
+### Skill Review
+- All 36 skills: added `origin` YAML frontmatter field
+- Fixed `widget-rendering` wrong file path
+- Fixed `orchestration` + `detection-pipeline-design` broken cross-skill references
+- Fixed 4 skills with wrong `source/pi-mono/` paths
+- `verify-skill.ts` now validates `origin` field
+
+### Bug Fixes
+- `adaptive-plan.ts`: `stripCodeFence()` strips markdown code fences inside ADAPTIVE_PLAN markers — fixes planner output parsing for non-frontier models
+- Mock mode regression: reverted NODE_ENV gate, uses PI_CREW_ALLOW_MOCK only (child processes don't inherit NODE_ENV)
+
+### Stats
+- Test suite: 2698 pass + 1 skip, 0 fail (was 2657 in v0.5.16; +41 net)
+- TypeScript: 0 errors
+- New test files: 6 (worktree-seed-paths, task-handoff-template, task-handoff-parser, adaptive-plan +3 safe-bash tests)
+- Files touched: 50+
+- Security issues fixed: 9 (3 CRITICAL + 3 HIGH + 3 MEDIUM)
+- False positives verified: 2
+
+## [0.5.16] — Rounds 22–31 Audit Fixes (2026-06-02)
+
+### Highlights
+- **1 bug fix**: OTLP exporter `dispose()` now awaits in-flight push (bounded by 10s timeout)
+- **269 new unit tests** across 16 previously-untested modules (Pattern #3)
+- **72 unused imports removed** across 28 source files (Pattern #6)
+- **2 defensive caps** for unbounded Maps (Pattern #2)
+- **1 L1 fix**: `console.warn` → `logInternalError` in crew-hooks
+
+### Round 22: Defensive Caps (commit 85b3be6)
+- Bounded `autoRecoveryLast` and `agentEventSeqCache` Maps to 1000 entries
+- Eviction uses insertion-order oldest-first pattern
+
+### Round 23: Resource Cleanup (commit 4be2c4e)
+- OTLP exporter `dispose()` now async, awaits in-flight push with 10s timeout
+- Surveyed all setInterval/setTimeout, process.on, file watchers, event listeners, AbortControllers — all clean
+
+### Round 24: Test Coverage — discover-agents, markers, tiered-eval (commit cfe5242)
+- 50 new tests: `sanitizeAgentSystemPrompt` (6 rules), `sanitizeGuidanceContent` (5 rules), `TieredEvalRunner` class
+
+### Round 25: Test Coverage — adaptive-plan, group-join (commit 89e1cf1)
+- 42 new tests: `slug`, `extractAdaptivePlanJson`, `parseAdaptivePlan`, `repairAdaptivePlan`, `GroupJoinManager`
+
+### Round 26: Test Coverage — pi-args, i18n (commit 3669f24)
+- 38 new tests: `applyThinkingSuffix`, `resolveCrewMaxDepth`, `t()`, `addTranslations`, `listLocales`
+
+### Round 27: Test Coverage — validation-types, live-extension-bridge (commit 44a2366)
+- 36 new tests: `validateWithSeverity` strict/lenient modes, `buildExtensionBridge` mock session
+
+### Round 28: Test Coverage — direct-run, live-session-health (commit 339ac7d)
+- 17 new tests: `isDirectRun`, `directTeamAndWorkflowFromRun`, `collectLiveSessionHealth`
+
+### Round 29: Test Coverage — process-status, task-claims (commit 405e05d)
+- 43 new tests: `checkProcessLiveness`, `isActiveRunStatus`, full claim lifecycle
+
+### Round 30: Test Coverage — task-display, green-contract, session-utils (commit 7d065ca)
+- 43 new tests: `shouldMaterializeAgent`, `taskById`, `waitingReason`, `greenLevelSatisfies`, `assertValidSessionId`
+
+### Round 31: Code Quality — unused imports + L1 fix (commit 35cc0e7)
+- 72 unused imports removed across 28 source files
+- `crew-hooks.ts`: `console.warn` → `logInternalError` for unknown event types
+
+### Stats
+- Test suite: 2657 pass + 1 skip, 0 fail (was 2370 in v0.5.14; +287 net)
+- TypeScript: 0 errors
+- New test files: 13
+- Files touched: 58
+
+## [0.5.15] — Round 20 + 21 Audit Fixes (2026-06-02)
+
+### Source tour
+- Pulled latest `can1357/oh-my-pi` (1751 new commits since 2026-05-11) to working copy
+- Surveyed extensibility, skill system, and security/performance changes via 3 parallel explorer agents
+- Distilled 2 high-impact, immediately applicable patterns (Round 20)
+- Identified 5 more upgrade opportunities; applied 5 in Round 21
+
+### Round 20: Lock token guard + tool-error sanitization (commit f448d7d)
+
+#### 1. Per-process lock tokens (src/state/locks.ts)
+- **Pattern source**: oh-my-pi commit `cd578a86d` (`file-lock.ts:13-152`)
+- **Bug fixed**: "Losing contender wipes winner's lock" race when one process times out and steals a stale lock that the original holder is about to release
+- Lock file now carries a UUID token. `releaseLock` refuses to `fs.rm` unless the stored token matches.
+- 3 new tests in `test/unit/locks-race.test.ts`
+
+#### 2. Tool-error sanitization (src/ui/tool-render.ts)
+- **Pattern source**: oh-my-pi `render-utils.ts:177-185` (`replaceTabs(truncateToWidth(clean, LINE_CAP))`)
+- **Bug fixed**: Embedded tabs/newlines/long strings in tool errors break TUI border alignment
+- Applied to `renderAgentProgress` and `renderAgentToolResult` (2 places)
+- `replaceTabs` is now exported from `src/ui/render-diff.ts` for reuse
+- 2 new tests in `test/unit/tool-render.test.ts`
+
+### Round 21: L1 cleanup, lock kind, JSONL per-line cap, in-place loader test (commit 1bf120b)
+
+#### 1. L1 cleanup in src/state/schedule.ts
+- `console.warn` → `logInternalError` (consistency with rest of codebase)
+- `require("node:fs")` → top-level `fs`/`path` imports
+- 3 new tests in `test/unit/schedule-store.test.ts`
+
+#### 2. Dead code sweep in src/state/locks.ts
+- Removed misleadingly-named `readLockStateAsync` (sync I/O, called from async path) and its redundant call site
+- Async path now mirrors sync path exactly: stale-check + release + sleep
+
+#### 3. Lock file `kind` discriminator (forward compat)
+- Lock JSON now includes `kind: "run" | "file"`
+- `withRunLock` writes `kind="run"`; `withFileLockSync` writes `kind="file"`
+- Old locks (no `kind` field) still work — `releaseLock` only reads `token`, so the discriminator is purely additive
+- 3 new tests (kind for run, kind for file, back-compat with legacy locks)
+
+#### 4. JSONL per-line cap (defensive, src/state/jsonl-writer.ts)
+- Single huge line could exhaust memory during `redactJsonLine`
+- New `DEFAULT_MAX_LINE_BYTES = 1MB`. Lines exceeding the cap are dropped and counted
+- `logInternalError` fires on the first drop and every 100th drop thereafter
+- 2 new tests in `test/unit/jsonl-writer.test.ts`
+
+#### 5. In-place extension loader integration test
+- **Pattern source**: oh-my-pi commit `c5e3698f4` (changed how extensions are loaded)
+- This test verifies pi-crew's `import.meta.url`-based skill path resolution still works with the new in-place loader
+- 2 new tests in `test/integration/extension-skill-resolution.test.ts`
+
+### Summary
+- **2 rounds** (Round 20 + 21)
+- **2 commits**: `f448d7d` (Round 20) + `1bf120b` (Round 21)
+- **10 new tests** across 4 test files
+- **Total tests**: 50 pass + 1 skip, **0 fail** (was 49 in v0.5.14)
+- **TypeScript**: 0 errors
+- **Patterns adopted**: 5 from `can1357/oh-my-pi` post-2026-05-11
+
+### Patterns surveyed but not applied (low applicability for pi-crew)
+- **Streaming JSON throttle** (3a733c480) — pi-crew has no streaming JSON parser
+- **In-place state mutation** (3a733c480) — pi-crew's spreads are bounded (small N), not hot paths
+- **Bounded row probing** (b522fde56) — pi-crew has no SQL queries
+- **MCP reconnect storm circuit breaker** — pi-crew has no MCP reconnect logic
+- **Drop `args` global from eval** (4ab40764d) — pi-crew's `dynamic-script-runner.ts` already safe
+- **Shell-injection rejection in git specs** (22e564a85) — pi-crew has no plugin install path
+- **NPM registry pinning** (9abce6e97) — pi-crew's `install.mjs` is config-only; user runs `pi install npm:pi-crew`
+- **Extension flag shadow** (1fbc2cbd7) — pi-crew has no `registerFlag` calls
+
 ## [0.5.14] — Round 19 Audit Fixes (2026-06-02)
 
 ### Phase 1: Path validation in checkpoint.ts (MEDIUM security)

package/README.md

@@ -9,7 +9,7 @@ npm: pi-crew
 repo: https://github.com/baphuongna/pi-crew
 ```
 
-**v0.5.14**: See [CHANGELOG.md](CHANGELOG.md).
+**v0.5.15**: See [CHANGELOG.md](CHANGELOG.md).
 
 ### Security highlights (v0.5.5)
 

package/docs/pi-crew-v0.5.16-audit-fix-plan.md

@@ -0,0 +1,35 @@
+# Round 22 Audit Fix Plan (Defensive Caps)
+
+## Findings
+
+### Issue 1: `autoRecoveryLast` Map grows unboundedly (MEDIUM, MEMORY)
+- **File**: `src/extension/register.ts:484`
+- **What**: Module-level `Map<string, number>` keyed by `${kind}_${runId}`. Holds cooldown timestamps for "recovery notifications" (5-minute gate per key).
+- **Bug**: Entries are NEVER removed during a session. Each run contributes up to 4 keys (one per `maybeNotifyHealth` kind). Long-running pi sessions that run 1000+ teams accumulate 4000+ entries (~32KB).
+- **Severity**: MEDIUM — silent memory growth in long-running process. Not a security issue.
+- **Fix**: Add `AUTO_RECOVERY_LAST_MAX_ENTRIES` cap. Evict oldest insertion (matches the 5-min cooldown gate semantics — once the gate has expired, the entry is irrelevant). The eviction loop runs on each `set()` to amortize the cost.
+
+### Issue 2: `agentEventSeqCache` Map grows unboundedly (MEDIUM, MEMORY)
+- **File**: `src/runtime/crew-agent-records.ts:265`
+- **What**: Module-level `Map<string, { size, mtimeMs, seq }>` keyed by `filePath` (each agent event log). Caches the `.seq` sidecar value.
+- **Bug**: Entries are NEVER removed. Each new agent task creates a new event log file, adding a cache entry. A long-running pi-crew process that spawns 1000s of agents accumulates 1000s of entries.
+- **Severity**: MEDIUM — silent memory growth. Plus, stale entries mask filesystem changes (mtime/size won't reflect a re-created file).
+- **Fix**: Add `AGENT_EVENT_SEQ_CACHE_MAX_ENTRIES` cap. Evict oldest insertion first (mirrors the `asyncAgentReaderCache` pattern at line 134-136 in the same file).
+
+## Plan (2 phases)
+
+### Phase 1: `autoRecoveryLast` defensive cap
+- `src/extension/register.ts:484` — add `AUTO_RECOVERY_LAST_MAX_ENTRIES = 1000` constant
+- Modify the `set()` site at line 1534 to evict oldest entries before inserting when size > cap
+- Add test in `test/unit/auto-recovery-cap.test.ts`
+
+### Phase 2: `agentEventSeqCache` defensive cap
+- `src/runtime/crew-agent-records.ts:265` — add `AGENT_EVENT_SEQ_CACHE_MAX_ENTRIES = 1000` constant
+- Add helper function `setAgentEventSeqCache()` that wraps the `.set()` and evicts oldest entries
+- Add test in `test/unit/crew-agent-records.test.ts` (or new file)
+
+## Expected impact
+- 2 new tests, 0 regressions
+- Total: 2 MEDIUM memory-leak fixes
+- No public API changes
+- Pattern: follows existing `NotificationRouter.SEEN_MAP_MAX_SIZE` and `asyncAgentReaderCache` patterns in the codebase

package/docs/pi-crew-v0.5.17-audit-fix-plan.md

@@ -0,0 +1,80 @@
+# Round 23 Audit Findings (Resource Cleanup)
+
+## Skill: iterative-audit (Pattern #7: Resource Cleanup)
+
+## Findings
+
+### Issue 1: OTLP exporter `inFlight` push not awaited on dispose (LOW)
+- **File**: `src/observability/exporters/otlp-exporter.ts:80-86, 127-130`
+- **What**: When `dispose()` is called, the interval timer is cleared but the in-flight `push()` continues to run until the 10s fetch timeout. The result is lost (not awaited).
+- **Severity**: LOW — bounded by 10s fetch timeout. Not a real leak, just orphaned work.
+- **Fix**: Make `dispose()` async. Await the in-flight push before returning.
+- **Test**: 1 new test verifies `dispose()` waits for the in-flight push.
+
+## Patterns surveyed (all VERIFIED clean from source)
+
+### setInterval / setTimeout cleanup
+| File | Resource | Cleanup | Status |
+|------|----------|---------|--------|
+| `register.ts:411` | `autoRepairTimer` | cleared on line 308, 402, 1102 | OK |
+| `register.ts:442` | `tempReconcileTimer` | cleared on line 308, 402, 1102 | OK |
+| `result-watcher.ts:80` | `pollTimer` | cleared in `stopPolling()` | OK |
+| `result-watcher.ts:96` | `restartTimer` | cleared in `scheduleRestart()` and `stop()` | OK |
+| `async-notifier.ts:101` | `state.interval` | cleared in `stopAsyncRunNotifier()` | OK |
+| `subagent-tools.ts:228` | `timer` | cleanup function returned to caller | OK |
+| `team-tool.ts:160` | `timer` | `stop()` method clears it | OK |
+| `live-conversation-overlay.ts:55` | `pollTimer` | cleared in `close()` / `dispose()` | OK |
+| `loaders.ts:127` | `timer` | cleared in `dispose()` | OK |
+| `theme-adapter.ts:145` | `pollTimer` | cleared in unsubscribe (line 169) | OK |
+| `delivery-coordinator.ts:169` | `ttlTimer` | cleared in `dispose()` | OK |
+| `parent-guard.ts:61` | `guardInterval` | cleared in `stopParentGuard()` | OK |
+| `scheduler.ts:88` | `t` (timer) | cleared on job removal | OK |
+| `otlp-exporter.ts:80` | `timer` | cleared in `dispose()` (Round 23: also awaits inFlight) | OK |
+| `team-runner.ts:67` | `interval` | local scope (per-run) | OK |
+| `metric-sink.ts:68` | `timer` | cleared in `dispose()` (also closes fd) | OK |
+| `handoff-manager.ts:203` | `cleanupTimer` | cleared in `dispose()` (also clears Maps) | OK |
+| `live-session-runtime.ts:487` | `controlTimer` | cleared in `finally` block | OK |
+| `budget-tracker.ts:231` | `abortInterval` | cleared on abort/exhausted | OK |
+| `background-runner.ts:52, 74` | `interval` | local scope (process entry point) | OK |
+
+### process.on() signal handler registration
+| File | Handlers | Guard | Status |
+|------|----------|-------|--------|
+| `crew-cleanup.ts:79, 84` | SIGTERM, SIGHUP | `signalHandlersRegistered` flag (Round 16) | OK |
+| `background-runner.ts:107, 148, 175, 181, 194, 198` | many | process entry point (registered once per process) | OK |
+| `event-log.ts:490-492` | exit, SIGTERM, SIGINT | module-level (ESM caches) | OK |
+| `atomic-write.ts:265-267` | exit, SIGTERM, SIGINT | module-level (ESM caches) | OK |
+
+### File watchers
+| File | Watcher | Cleanup | Status |
+|------|---------|---------|--------|
+| `register.ts:682, 686` | `crewWatcher`, `userCrewWatcher` | `closeWatcher()` in cleanup paths | OK |
+| `result-watcher.ts` | `watcher` | `closeWatcher()` in `stop()` | OK |
+
+### Event listeners
+| File | Listener | Cleanup | Status |
+|------|----------|---------|--------|
+| `event-bus.ts:on()` | deduped via Set | cleanup function returned | OK |
+| `run-event-bus.ts:onAny()` etc. | deduped via Sets | cleanup function returned | OK |
+| `phase-tracker.ts:dispose()` | EventEmitter | `removeAllListeners()` | OK |
+| `team-tool.ts:72` | signal listener | `removeEventListener` in `finally` | OK |
+
+### AbortController
+| File | Controller | Cleanup | Status |
+|------|-----------|---------|--------|
+| `team-tool.ts:68` | per-tool | aborted via signal listener, removed in `finally` | OK |
+| `subagent-manager.ts:290` | per-run | cleaned in `cleanupRunSignal()` | OK |
+| `cancellation-token.ts:17` | per-token | aborted via `#controller.abort()` | OK |
+| `otlp-exporter.ts:106` | per-push | cleared in `finally` block | OK (also: dispose awaits inFlight) |
+
+## Plan (1 phase)
+
+### Phase 1: OTLP exporter `dispose()` awaits inFlight
+- `src/observability/exporters/otlp-exporter.ts:127-130` — make `dispose()` async, await `this.inFlight`
+- 1 new test in `test/unit/otlp-exporter.test.ts`
+
+## Expected impact
+- 1 new test, 0 regressions
+- Total: 1 LOW severity improvement
+- No public API change (callers that don't await still get synchronous timer clear)
+- Pattern: matches the existing `await` patterns elsewhere in the codebase

package/docs/skills/REFERENCE.md

@@ -38,6 +38,16 @@ multi-perspective-review (8-pass deep review)
 secure-agent-orchestration-review (security focus)
 ```
 
+### Multi-Round Audit (5-20 rounds)
+
+```
+iterative-audit (round planning, 7 patterns, diminishing-returns)
+    ↓
+multi-perspective-review (per round, optional)
+    ↓
+verification-before-done (per round)
+```
+
 ---
 
 ## When to Invoke
@@ -48,6 +58,7 @@ secure-agent-orchestration-review (security focus)
 | Before claiming done | `verification-before-done` |
 | Code review (quick) | `scrutinize` |
 | Code review (deep) | `multi-perspective-review` |
+| Multi-round audit (5-20 rounds) | `iterative-audit` |
 | Task delegation | `delegation-patterns` |
 | Complex multi-phase work | `orchestration` |
 | After bug is fixed | `post-mortem` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.5.14",
+  "version": "0.5.17",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/skills/artifact-analysis-loop/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: artifact-analysis-loop
 description: "Systematic artifact examination for code, files, and binaries."
+origin: distilled:anthropic-cybersecurity-skills
 triggers:
   - "analyze this artifact"
   - "examine file"

package/skills/async-worker-recovery/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: async-worker-recovery
 description: Background worker, heartbeat, stale-run, crash-recovery, and deadletter workflow. Use when debugging stuck/dead workers or changing async run reliability.
+origin: pi-crew
 triggers:
   - "worker crashed"
   - "stale run"

package/skills/child-pi-spawning/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: child-pi-spawning
 description: "Child Pi worker spawning, lifecycle callbacks, and failure modes."
+origin: pi-crew
 triggers:
   - "worker crashed"
   - "worker blink"

package/skills/context-artifact-hygiene/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: context-artifact-hygiene
 description: "Use when constructing worker prompts, reading artifacts/logs, summarizing runs, compacting context, or handing work between agents."
+origin: pi-crew
 triggers:
   - "construct prompt"
   - "read artifact"

package/skills/delegation-patterns/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: delegation-patterns
 description: "Subagent/team delegation workflow."
+origin: pi-crew
 triggers:
   - "delegate this"
   - "split this task"

package/skills/detection-pipeline-design/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: detection-pipeline-design
 description: "Design data pipelines for security monitoring and threat intelligence."
+origin: distilled:anthropic-cybersecurity-skills
 triggers:
   - "build pipeline"
   - "design detection"
@@ -282,4 +283,4 @@ npx tsc --noEmit
 node --experimental-strip-types --test test/unit/detection-pipeline.test.ts
 ```
 
-*See also: `detection-signature-authoring` (in security-review) for detection rule patterns.*
+*See also: `security-review` skill for detection rule patterns and signature authoring guidance.*

package/skills/event-log-tracing/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: event-log-tracing
 description: "Structured event logging for worker lifecycle, live agents, crash recovery."
+origin: pi-crew
 triggers:
   - "event log"
   - "trace events"

package/skills/git-master/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: git-master
 description: "Commit and release hygiene for safe version-control work."
+origin: pi-crew
 triggers:
   - "commit this"
   - "tag release"

package/skills/hunting-investigation-loop/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: hunting-investigation-loop
 description: "Active hypothesis-driven investigation and threat hunting."
+origin: distilled:anthropic-cybersecurity-skills
 triggers:
   - "hunt for"
   - "find evidence of"

package/skills/incident-playbook-construction/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: incident-playbook-construction
 description: "Build structured incident response playbooks and runbooks."
+origin: distilled:anthropic-cybersecurity-skills
 triggers:
   - "build playbook"
   - "create runbook"