pi-crew 0.5.14 → 0.5.16

package/CHANGELOG.md

@@ -1,5 +1,122 @@
 # Changelog
 
+## [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.16",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/skills/iterative-audit/SKILL.md

@@ -0,0 +1,330 @@
+---
+name: iterative-audit
+description: "Iterative multi-round codebase audit with diminishing-returns detection. Run 5-20+ rounds, each focusing on one specific area. Built from 19 rounds of dogfooding pi-crew on itself."
+triggers:
+  - "audit this codebase"
+  - "review everything"
+  - "find all bugs"
+  - "deep audit"
+  - "harden this"
+  - "iterate audit rounds"
+  - "multi-round review"
+---
+
+# Iterative Audit
+
+> Distilled from 19 rounds of auditing pi-crew on itself (v0.5.5 → v0.5.14):
+> ~70 issues fixed, 286 tests added, 9 security improvements, 2 performance improvements.
+
+The core insight: **a single round of audit finds the easy 30% of bugs**. The remaining 70% only surfaces through 5-20+ targeted rounds, each with a specific focus. After round 5+ you find HIGH severity bugs that round 1 missed. After round 10+ you find issues that no human reviewer would catch in a single pass.
+
+## Operating Stance
+
+- **One focus per round.** Each round targets one of the 7 patterns below. Don't try to fix everything in one pass.
+- **Source verification is mandatory.** Never trust audit docs or previous round reports — always read the actual code. ~30% of issues from prior rounds are false positives or already fixed.
+- **Document every finding with file:line.** "Sandbox env allow-list" is useless. "src/runtime/sandbox.ts:70 — process.env full leak" is actionable.
+- **Verify the team actually applied changes.** After any team run, run `git diff` and inspect. ~20% of team runs silently fail to apply changes.
+- **Don't publish without explicit user confirmation.** Audit work compounds; releasing in the middle of a round leaves the codebase in a half-hardened state.
+
+## The 7 Patterns (rotate through these)
+
+After 19 rounds, every issue found falls into one of these 7 categories. Use this to plan each round's focus.
+
+### 1. L1 Cleanup (decoration, low value, easy)
+**What**: Replace `console.error` / `console.warn` / `process.stderr.write` with `logInternalError()` from `utils/internal-error.ts`.
+
+**Why**: `console.error` may not be visible in JSON-RPC mode or when stderr is redirected. `logInternalError` is the project-wide pattern; missing it means errors are silently dropped.
+
+**How to find them**:
+```bash
+rg -n 'console\.(error|warn|log)' src/
+rg -n 'process\.stderr\.write' src/
+```
+
+**Rule**: Skip `internal-error.ts:5` itself (it's the implementation). Skip `background-runner.ts:146` (overrides `console.error` for testing). Skip `parent-guard.ts:37` (exit-time log must fire synchronously).
+
+**Time per round**: 30 min for 5-10 callsites. Diminishing returns after round 1.
+
+### 2. Defensive Caps (memory safety, medium value, medium effort)
+**What**: Find Maps, Sets, Arrays, and Queues that grow unboundedly. Add `MAX_*` constants and eviction logic.
+
+**Why**: Long-running processes (background runners, extension reloads) accumulate state. Without caps, a busy period causes OOM.
+
+**How to find them**:
+```bash
+rg -n 'new Map\(' src/  # look for ones that are .set() repeatedly
+rg -n 'new Set\(' src/
+rg -n 'this\.\w+\.push\(' src/  # look for unbounded arrays
+```
+
+**Common patterns**:
+- `Semaphore.#queue` → add `MAX_QUEUE` cap (pi-crew: 10,000)
+- `liveAgentManager.liveAgents` Map → add `MAX_LIVE_AGENTS` cap (pi-crew: 5,000)
+- `OverflowRecoveryTracker.states` Map → add `MAX_TRACKED_STATES` cap (pi-crew: 5,000)
+- `NotificationRouter.seen` Map → add `SEEN_MAP_MAX_SIZE` cap (pi-crew: 10,000)
+
+**Eviction strategies** (in order of preference):
+1. **LRU by access time** — track `lastAccessAt` per entry
+2. **Oldest insertion** — Map's natural insertion order works (delete first key)
+3. **Terminal-state priority** — protect live entries, evict completed/failed/cancelled first
+
+**Test pattern**: Verify cap by inserting 1.5× the max, confirm old entries are gone.
+
+### 3. Test Coverage Gaps (good value, low effort)
+**What**: Find source files with zero direct unit tests.
+
+**How to find them**:
+```bash
+# For each src file, check if any test file imports it
+for f in src/runtime/*.ts src/extension/*.ts; do
+  basename=$(basename "$f" .ts)
+  count=$(ls test/unit/${basename}*.test.ts 2>/dev/null | wc -l)
+  [ "$count" = "0" ] && echo "NO TEST: $f"
+done
+```
+
+**Prioritize**:
+- Security-critical: `sandbox.ts`, `child-pi.ts`, `pi-spawn.ts`, `crew-cleanup.ts`
+- Resource-management: `live-agent-manager.ts`, `semaphore.ts`, `overflow-recovery.ts`
+- Public APIs: anything with `export class` or `export function`
+
+**Don't test**: internal helpers, generated code, pure re-exports.
+
+**Test categories** (in order of importance):
+1. **Path validation** (security) — `assertSafePathId`, path traversal rejection
+2. **Resource cleanup** — `dispose()` clears everything, listeners don't stack
+3. **Boundary conditions** — empty input, max-size, overflow
+4. **Callback lifecycle** — sync/async error handling, `resultConsumed` flag
+
+### 4. Security Hardening (high value, high effort)
+**What**: Find places where untrusted input reaches dangerous sinks.
+
+**Common sinks to audit**:
+- `execSync(command)` → switch to `execFileSync(program, args[])`
+- `eval()` / `Function()` / `vm.runInNewContext()` → avoid entirely
+- `path.join(base, userInput)` → use `assertSafePathId(userInput)` first
+- `process.env` access → use sanitized env with allow-list
+- File writes to user-controlled paths → validate path is within allowed roots
+- Child process spawn → use `cwd: knownDir`, sanitize env
+
+**How to find them**:
+```bash
+rg -n 'execSync\(' src/
+rg -n 'exec\(' src/
+rg -n 'eval\(|Function\(' src/
+rg -n 'spawn\(' src/
+rg -n 'path\.join\(' src/ | rg 'record\.|task\.|runId|agent\.'
+```
+
+**Round 1**: Find all `execSync` and `exec`. Switch to `execFileSync(program, args)` (no shell).
+**Round 2**: Audit env handling. Look for `process.env` access in hot paths. Add allow-list.
+**Round 3**: Path traversal. For every `path.join(base, userInput)`, add `assertSafePathId()`.
+**Round 4**: Subprocess safety. Verify all `spawn()` calls have: validated args, sanitized env, `cwd` set, signal handling, timeout.
+
+### 5. Performance (medium value, medium effort)
+**What**: Find O(N²) or worse algorithms, especially in hot paths.
+
+**Common patterns**:
+- Recomputing document frequency in search loops → precompute at construction
+- `array.filter().map().filter()` in a loop → fuse into one pass
+- `JSON.parse` of the same file repeatedly → cache
+- `fs.statSync` per file in a directory scan → batch with `Dirent.isDirectory()`
+- `setTimeout` busy-polling for state changes → use `fs.watch` or events
+
+**How to find them**:
+```bash
+# Look for nested loops over the same data
+rg -nB 1 -A 5 'for.*of.*for' src/
+# Look for polls
+rg -n 'setTimeout.*poll' src/
+rg -n 'pollIntervalMs' src/
+```
+
+**Test pattern**: For precomputation fixes, write a perf test that creates 1000 docs, runs search, and asserts completion under 100ms.
+
+### 6. Code Quality (low value, easy)
+**What**: Remove dead code, fix type misuse, add missing JSDoc.
+
+**Common patterns**:
+- Fields declared but never used (e.g., `seenCleanupCounter`)
+- Unused imports
+- Type assertions (`as any`, `as unknown as T`) that hide real issues
+- Functions that always return the same value
+- Catch blocks that swallow errors silently
+
+**How to find them**:
+```bash
+# Find fields/methods declared but never used
+rg -n 'private \w+\s*=\s*' src/ | while read line; do
+  field=$(echo "$line" | grep -oP 'private \K\w+')
+  count=$(rg -c "\b$field\b" src/ 2>/dev/null | head -1)
+  [ "$count" = "1" ] && echo "DEAD: $line"
+done
+```
+
+### 7. Resource Cleanup (medium value, medium effort)
+**What**: Find places where listeners, timers, file handles, or other resources can leak.
+
+**Common patterns**:
+- `process.on('SIGTERM', ...)` registered multiple times → use module-level flag
+- `setInterval` / `setTimeout` not cleared on shutdown → `dispose()` method
+- `AbortController` not aborted in cleanup
+- File watchers (`fs.watch`) not closed
+- Event listeners (`emitter.on`) not removed
+
+**How to find them**:
+```bash
+rg -n 'process\.on\(' src/
+rg -n 'setInterval\(' src/
+rg -n 'setTimeout\(' src/ | rg -v 'setTimeout.*resolve'  # filter out poll sleeps
+rg -n 'fs\.watch\(' src/
+```
+
+**Test pattern**: Call the registration function N times, verify listener count is 1.
+
+## Round Workflow (use this for EVERY round)
+
+### Step 1: Pick a focus
+Choose ONE of the 7 patterns above. Don't try to do multiple patterns in one round.
+
+### Step 2: Explore (read 3-5 files)
+Read the actual source for the focus area. Don't trust prior audit docs.
+
+### Step 3: Verify from source
+For each candidate issue:
+- Read the file at the cited line
+- Check if the issue is real (not a false positive)
+- Check if it's already fixed
+- Note the exact file:line and code snippet
+
+### Step 4: Create a plan doc
+```markdown
+# Round N Audit Fix Plan
+## Findings
+### Issue 1: <file>:<line> — <title> (severity)
+<File path and line numbers>
+<Code snippet showing the issue>
+<Rationale>
+
+## Plan (5 phases)
+### Phase 1: <action>
+### Phase 2: <action>
+...
+```
+
+### Step 5: Implement
+- Make the fix
+- Add tests (if applicable)
+- Run typecheck: `npx tsc --noEmit`
+- Run tests: `npm test`
+
+### Step 6: Commit + Release
+- Commit with conventional message: `fix: round N - <summary>`
+- Update CHANGELOG.md
+- Bump version (patch)
+- Push + npm publish
+- Create GitHub release
+
+### Step 7: Decide: continue or stop?
+After 5-10 rounds, evaluate:
+
+**Continue if**:
+- Last 2 rounds found HIGH or MEDIUM severity issues
+- Test coverage is < 80% of modules
+- User explicitly wants more
+
+**Stop if**:
+- Last 2 rounds found only LOW severity or L1 cleanup
+- All patterns exhausted (you've done each at least once)
+- Diminishing returns: more time spent planning than implementing
+
+## When to Use Teams vs. Do It Yourself
+
+**Use teams** (via `team action='run', team='review'`) for:
+- Initial broad audit (round 1)
+- Security reviews (specialized `security-reviewer` agent)
+- When you need 3+ perspectives (multi-explorer)
+
+**Do it yourself** for:
+- Round 2+ (you have context from prior rounds)
+- Focused single-pattern work (L1 cleanup, test coverage)
+- Small fixes (< 5 file edits)
+
+**Teams often fail because**:
+- 5-min heartbeat timeout for long-running runs (add `startTeamRunHeartbeat` if needed)
+- Agent cancellations
+- Hallucinated file:line references (always verify from source)
+
+## Common False Positives (audit findings to reject)
+
+After 19 rounds, ~30% of audit findings are false positives. Common patterns:
+
+1. **"Double-merge in config"** — looks like a bug, but project config + user config merge is intentional
+2. **"as unknown as T in error handling"** — necessary for TypeScript's strict mode
+3. **"Auto-repair timer race"** — there's a guard like `cleanedUp || !currentCtx` you missed
+4. **"Already-validated input"** — validation is in the caller, not the callee
+5. **"Redundant null check"** — TypeScript narrowing doesn't always work for closures
+
+**Always verify against source** before acting. If you're not sure, write a test that exercises the alleged bug path. If the test passes, it's a false positive.
+
+## Success Metrics
+
+After each round, record:
+- Issues found (real vs. false positive)
+- Tests added
+- Typecheck clean?
+- Total test count delta
+
+**Healthy round**: 3-8 real issues found, +20 to +50 tests added, all pass.
+
+**Exhausted round**: 0-1 real issues found, 0 tests added, mostly L1 cleanup.
+
+When you hit 2+ exhausted rounds in a row, **stop**.
+
+## Real Examples from 19 Rounds
+
+| Round | Focus | Issues Found | Severity Range |
+|-------|-------|--------------|----------------|
+| 1-3 | Broad security audit | 11 | CRITICAL, HIGH |
+| 4-6 | Race conditions, locks | 5 | HIGH |
+| 7-9 | L1 cleanup, dead code | 12 | LOW |
+| 10-12 | Defensive caps | 3 | MEDIUM |
+| 13-15 | Security: execSync, sandbox | 9 | CRITICAL, HIGH |
+| 16-18 | Test coverage, L1 | 30+ | LOW |
+| 19 | Path validation, tests | 5 | MEDIUM |
+
+**Pattern**: First 3 rounds find the most impactful issues. Rounds 4-15 find the rest. Rounds 16+ are diminishing returns (mostly test coverage and L1 cleanup).
+
+## Anti-Patterns to Avoid
+
+- **Mega-rounds** (10+ files, 5+ categories) — too broad, low quality findings
+- **Trusting audit docs** — always verify from source
+- **Skipping typecheck** — type errors compound and become hard to debug later
+- **Releasing mid-round** — leaves the codebase in a half-hardened state
+- **No test for the fix** — every fix needs a test that would have caught the bug
+- **Committing too late** — commit after each phase, not at the end of the round
+
+## Enforcement — Iterative Audit Gate
+
+**Before reporting round findings, verify:**
+
+- [ ] Round focus is ONE of the 7 patterns (not multiple)
+- [ ] Each finding has a verified `file:line` reference (read the actual source)
+- [ ] False positives filtered out (consult "Common False Positives" section)
+- [ ] Severity assigned using the standard scale (CRITICAL / HIGH / MEDIUM / LOW)
+- [ ] Plan doc created with phases and file:line evidence
+- [ ] Typecheck clean: `npx tsc --noEmit` returns 0 errors
+- [ ] All tests pass: `npm test` shows 0 failures
+- [ ] Tests added for the fix (if applicable)
+- [ ] Round results recorded: issues found, tests added, delta
+- [ ] Decision logged: continue to next round or stop (with reason)
+
+**If ANY answer is NO → Stop. Complete audit requirements before reporting round results.**
+
+## Related Skills
+
+- `scrutinize` — Quick outsider-perspective review of a single change
+- `multi-perspective-review` — 8-pass deep review for a single change
+- `security-review` — Security-focused audit with detection authoring
+- `verification-before-done` — Evidence before claim (use per round)
+- `systematic-debugging` — When a finding reveals a real bug that needs deeper investigation

package/src/extension/management.ts

@@ -3,7 +3,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentConfig, ResourceSource, RoutingMetadata } from "../agents/agent-config.ts";
 import { serializeAgent } from "../agents/agent-serializer.ts";
-import { allAgents, discoverAgents } from "../agents/discover-agents.ts";
+import { discoverAgents } from "../agents/discover-agents.ts";
 import type { TeamToolDetails } from "./team-tool-types.ts";
 import { toolResult, type PiTeamsToolResult } from "./tool-result.ts";
 import type { TeamToolParamsValue } from "../schema/team-tool-schema.ts";

package/src/extension/plan-orchestrate.ts

@@ -6,7 +6,6 @@
  */
 
 import * as fs from "node:fs";
-import * as path from "node:path";
 
 /**
  * Tag → Agent chain mapping from ECC recommendations.