pi-crew 0.8.10 → 0.8.12

package/CHANGELOG.md

@@ -1,5 +1,188 @@
 # Changelog
 
+## [0.8.12] — `team action=cleanup` now reverses `init` (Issue #35) (2026-06-17)
+
+`team action=cleanup` gained a **project-level mode** that reverses what
+`team action=init` writes. This closes the legitimate complaint in
+[Issue #35](https://github.com/baphuongna/pi-crew/issues/35): pi-crew injects
+a guidance block into `AGENTS.md` on `init`, but `pi uninstall` has no
+extension hook to remove it — so the block (and `.crew/`) were left behind.
+
+### New `cleanup` modes
+
+| Call | What it does |
+|---|---|
+| `team action=cleanup runId=<id>` | Per-run worktree cleanup (existing behavior, unchanged) |
+| `team action=cleanup` (no runId) | **NEW**: removes the AGENTS.md guidance block |
+| `team action=cleanup force=true` | NEW: also removes the `.crew/` state directory |
+| `team action=cleanup dryRun=true` | NEW: preview without writing |
+
+### Safety guarantees
+
+- The AGENTS.md guidance block is **marker-delimited**
+  (`<!-- PI-CREW:GUIDANCE:START/END -->`), so `removeGuidance` removes **only**
+  that block — user content is never touched (pinned by a test).
+- `.crew/` removal requires explicit `force=true` (irreversible — holds run
+  history, artifacts, worktrees). Default preserves it.
+- A `realpathSync` + basename guard refuses to `rmSync` anything that isn't a
+  `.crew` dir, so a crafted cwd can't trick us into deleting an arbitrary path.
+- The user-scope dir (`~/.pi/agent/extensions/pi-crew/`) is owned by
+  `pi uninstall` and is never touched by `team action=cleanup`.
+
+### Files
+
+- `src/extension/team-tool/lifecycle-actions.ts` — `handleCleanup` dispatcher
+  + new `handleProjectCleanup` (no-runId path). Intent policy now checked once
+  in the dispatcher (applies to both modes). Per-run path preserved verbatim.
+- `src/extension/team-tool-types.ts` — `TeamToolDetails.scope?`.
+- `README.md` — new **Uninstall** section documenting the full flow.
+- `test/unit/cleanup-project-mode.test.ts` — NEW, 9 tests (removal, user-content
+  preservation, idempotency, force-gating, dry-run, scope rejection, runId
+  routing).
+- `test/unit/team-tool-dispatch.test.ts` — updated the no-runId test to the
+  new contract (project cleanup, not error).
+
+typecheck clean; full suite 2964/0.
+
+## [0.8.11] — Split-scope install fix + transient-provider fallback (2026-06-17)
+
+Bundle of two independent fixes that were triaged from real user reports on
+2026-06-17. Both are robustness fixes for failure modes that previously
+killed team runs silently.
+
+### 1. `Cannot find module '@earendil-works/pi-coding-agent'` on Windows / global installs
+
+**Symptom:** every `team` action (run / parallel / plan) crashed ~1 minute
+after spawn, leaving all tasks permanently `queued`. The detached
+background team-runner child threw:
+```
+Error: Cannot find module '@earendil-works/pi-coding-agent'
+Require stack:
+- .../.pi/agent/npm/node_modules/pi-crew/src/runtime/skill-instructions.ts
+```
+
+**Root cause:** pi-crew (an extension) is installed under
+`~/.pi/agent/npm/node_modules/<ext>/`, but pi itself (the
+`@earendil-works/pi-coding-agent` package extensions import from) lives in a
+**separate** node_modules tree (nvm / `%APPDATA%\npm` / Volta / fnm /
+pnpm-global). Node's resolver only walks UP ancestor `node_modules`, so a
+static `import { getAgentDir } from "@earendil-works/pi-coding-agent"` in a
+file loaded by the spawned child crashes. This is the **default** layout for
+anyone who installs pi-crew via `pi install` — not a user misconfiguration.
+
+**Additional constraint:** pi-coding-agent ships as **ESM-only**
+(`type:module`, exports map with only an `import` condition). CJS
+`createRequire(dir)(name)` / `require.resolve("<pkg>/package.json")` both
+fail with `ERR_PACKAGE_PATH_NOT_EXPORTED` under node AND jiti/tsx (verified).
+The ONLY working load mechanism is a dynamic `import()` of the resolved ESM
+entry file URL.
+
+**Fix — NEW `src/runtime/peer-dep.ts`:**
+- `resolvePeerDep()` (sync): walks `node_modules` **manually** (bypasses the
+  restrictive exports map) across 6 strategies — env hint
+  (`PI_CREW_PEER_DEP_DIR`), this file, `process.argv[1]`, the node binary's
+  global node_modules (covers nvm/Volta/fnm), `npm root -g`, and
+  `%APPDATA%\npm`. Memoized.
+- `primePeerDep()` (async): dynamic `import(fileURL)` the resolved ESM entry,
+  cache the module namespace. Memoized + retryable on failure.
+- `getAgentDir()` (sync): reads the REAL fork-aware `getAgentDir` from the
+  primed cache; falls back to a computed default (`~/.pi/agent`, respecting
+  `PI_CODING_AGENT_DIR`) if not primed — **NEVER throws**.
+
+**Rewired:**
+- `skill-instructions.ts`, `discover-skills.ts` — static peer-dep import →
+  lazy `getAgentDir()` from `peer-dep.ts` (this is the crash site).
+- `background-runner.ts` — `primePeerDep()` before importing `team-runner`
+  (child process).
+- `register.ts` — `primePeerDep()` at extension entry (main process).
+- `async-runner.ts` — propagate `PI_CREW_PEER_DEP_DIR` to children so they
+  skip the ~200ms `npm root -g` probe.
+
+**Tests:** NEW `test/unit/peer-dep-resolver.test.ts` (9 cases) — env-hint
+resolution, manual node_modules walk past exports map, ESM dynamic-import
+loading, memoization, graceful fallback, `PI_CODING_AGENT_DIR` override,
+loadable fileURL under the child's loader.
+
+### 2. `500 api_error "unknown error, 999 (1000)"` aborted the run instead of falling back
+
+**Symptom:** when the model provider went hard-down with
+`500 {"type":"error","error":{"type":"api_error","message":"unknown
+error, 999 (1000)"}}`, the run died even when the user had configured a
+fallback model that would have worked.
+
+**Root cause:** pi has two safety layers. (1) pi-core provider-retry retries
+3× with exponential backoff — its regex already matches `500`. (2) pi-crew's
+`model-fallback` layer is the last safety net: when all 3 retries fail, it
+tries the next configured model. But `isRetryableModelFailure`'s pattern
+list covered 429 / rate-limit / 502-504 / overloaded / timeout and **MISSED**
+generic `500`, `api_error`, `unknown error`, and internal/server-error
+phrasings. So a transient provider outage was retried 3× then **aborted**
+instead of failing over.
+
+**Fix:** added to `RETRYABLE_MODEL_FAILURE_PATTERNS` —
+`\b500\b`, `\b501\b`, `api_error`, `unknown error`,
+`internal(?:_server)?[ _]error`, `server error`, `bad gateway`.
+
+`NON_RETRYABLE` (auth/billing/key) still wins — checked first in
+`isRetryableModelFailure` — so a transient-looking 500 wrapping an auth
+failure won't loop the chain.
+
+**Tests:** 4 regression tests in `test/unit/model-fallback.test.ts` covering
+the exact reported error, generic 5xx, auth-still-blocked, and undefined/empty.
+
+### Verification
+
+typecheck clean; peer-dep suite 9/9; model-* suite 57/57; full suite 0 real
+failures (1 known `result-watcher` fs.watch 10s timeout flake passes 7/7 in
+isolation — unrelated).
+
+## [0.8.10] — Pre-warm 3 repro-observed cold-start crash-variant modules (2026-06-17)
+
+The post-v0.8.9-restart 6-subagent repro surfaced 3 cold-start crash variants
+in one batch: `existsSync` (peer-dep, latched v0.8.1 + warmup v0.8.6),
+`effectiveRunConfig` (`team-tool/config-patch.ts`), `CREW_README`
+(`state/crew-init.ts`, latched v0.8.9). v0.8.6's warmup covered `team-tool.ts`
+transitively but not these specific modules explicitly — static-graph
+reachability isn't reliable under tsx/jiti interop + concurrent fanout (the
+`handleRun` latch serializes the CALL but not module-body instantiation of
+`run.ts`'s static deps).
+
+**Fix:** add the 3 repro-observed modules to `HOT_MODULE_SPECIFIERS` so their
+module bodies instantiate at single-threaded registration:
+`team-tool/run.ts`, `team-tool/config-patch.ts`, `workflows/validate-workflow.ts`.
+
+Repro verification: 6/6 subagents clean (was 1/6) under loaded code.
+
+## [0.8.9] — crew-init dynamic-import latch (kills CREW_README TDZ race) (2026-06-17)
+
+Module-scoped `loadCrewInit()` latch in `team-tool/run.ts` — concurrent `team`
+tool calls share ONE in-flight import promise. Added `crew-init.ts` to
+`HOT_MODULE_SPECIFIERS`. Targets the `CREW_README` TDZ variant observed in the
+post-v0.8.8 repro.
+
+## [0.8.8] — Cross-project leak cwd-scope barrier (2026-06-17)
+
+`collectInFlightRuns` filtered by STATUS only (queued/planning/running), not
+by project scope. Multiple Pi sessions in the same project shared
+`.crew/state/runs/`, so Session B's compaction picked up Session A's runs in
+OTHER projects and injected them into Session B's continuation prompt.
+
+The v0.8.8 (4bd6f5b) `ownerSessionId` filter was **unreliable** —
+`ctx.sessionId` is absent on pi 0.79.6 `ExtensionContext`.
+
+**Fix:** `isInProjectScope(run, queryCwd)` in `collectInFlightRuns` — keeps a
+run only if `findRepoRoot(run.cwd) === findRepoRoot(queryCwd)`. Reliable,
+version-independent. Filter at the consumption site, NOT in
+`listRecentRuns`/`collectActiveRuns` (the cross-project dashboard view stays
+unfiltered — 2 run-index tests pin that). Empirically verified: ambient
+status shows only current-project runs, zero foreign-project bleed.
+
+## [0.8.7] — Doctor runtime-warmup status (2026-06-17)
+
+`getRuntimeWarmupStatus()` diagnostic + a "Runtime warmup" section in
+`team doctor` showing started/completed/duration/error. "Not started" is NOT
+a doctor error (normal for direct unit-test calls).
+
 ## [0.8.6] — General cold-start race fix (runtime module-graph warmup) (2026-06-17)
 
 Fixes the `validateWorkflowForTeam` cold-start crash that v0.8.1 did NOT

package/README.md

@@ -9,50 +9,48 @@ npm: pi-crew
 repo: https://github.com/baphuongna/pi-crew
 ```
 
-**v0.6.4**: See [CHANGELOG.md](CHANGELOG.md).
-
-### Highlights (v0.6.4 → v0.7.0)
-
-This release implements **Phase 0 + Phase 1** of the long-term roadmap (synthesized from a 10-round research process), plus the **single-agent cliff hedge**. Principle: *build trust and cliff-resilience, stay lean, delete before adding.*
-
-- **🛡️ Compaction resilience (O10)** — the #1 user pain ("after auto-compact, the task stops midway") is fixed. In-flight crew runs are detected, a resume directive is injected into the compaction summary, and tasks re-attach after compaction.
-- **💰 Cost visibility (O1)** — `team summary <runId>` now shows a full cost report with per-role attribution and token breakdown (`$0.77 — executor 79%, reviewer 14%...`).
-- **✋ Plan-level HITL for any workflow (O5)** — set `runtime.requirePlanApproval = true` to gate any workflow at the plan→execute boundary; approve via `team api op=approve-plan`.
-- **🧠 Cross-run memory (O4)** — `.crew/knowledge.md` is auto-injected into every run's system prompt. pi-crew remembers project context across runs.
-- **🎯 Single-agent cliff hedge** — `team plan singleAgent=true` composes any workflow into one sequential prompt, so pi-crew's mission survives even if multi-agent is obsoleted by large-context models.
-- **🧹 2,335 LOC of dead code removed** + **Pi-api seam** centralizing the coupling surface.
-
-### Highlights (v0.6.3 → v0.6.4)
-
-- **Visually rich tool rendering** — `team` and `Agent` tool calls now render as framed cards in the Pi TUI with box-drawing borders, colored status badges, and structured layouts
-- **Merged call+result into ONE connected frame** — the call header and result body now form a single seamless frame instead of two disconnected boxes
-- **Animated live progress bar during runs** — real-time `████░░░░ N/M` task progress with elapsed time, rendered DURING the run; indeterminate "starting" phase uses an animated scanning bar
-- **Compact completion summary** — collapsed cards show `✓ crew run  3/3 done · 1m2s · 26k tok · $0.068` with expand hint and per-agent briefs
-- **Critical crash fix on session resume** — `renderCall` was returning a `string` instead of a `Text` component, causing `TypeError: child.render is not a function` when Pi re-rendered stored tool calls
-- **Disabled brief tool overrides** — reverted the experimental brief mode that replaced Pi's superior native renderers (syntax highlighting, diff views, full content)
-- **Flaky test fix** — `AnimatedMascot` timing tests made CI-load-robust via polling loops
-- **CI green** — 0 failures on Ubuntu, macOS, and Windows
-
-### 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
+**v0.8.11**: See [CHANGELOG.md](CHANGELOG.md).
+
+### Highlights (v0.6.4 → v0.8.11)
+
+A long arc of **trust, cliff-resilience, and robustness** work. Principle: *build
+trust and cliff-resilience, stay lean, delete before adding.*
+
+#### v0.8.x — hardening & reliability (2026-06-17)
+- **🛠️ Split-scope install fix (v0.8.11)** — `team` runs no longer crash with
+  `Cannot find module '@earendil-works/pi-coding-agent'` when pi-crew and pi
+  live in separate node_modules trees (the default for `pi install`). New
+  `src/runtime/peer-dep.ts` resolves the ESM-only peer dep across 6 strategies.
+- **🔄 Model fallback on transient 5xx (v0.8.11)** — a hard-down provider
+  (`500 api_error "unknown error"`) now triggers the configured fallback
+  model instead of aborting the run. `isRetryableModelFailure` extended.
+- **🧊 Cold-start race eliminated (v0.8.6 → v0.8.10)** — under tsx, concurrent
+  subagent spawns raced module instantiation (`existsSync` / `CREW_README` /
+  `effectiveRunConfig` / `validateWorkflowForTeam`). Fixed graph-wide: warm at
+  registration + gate at spawn boundaries + per-site latches. 6/6 repro clean.
+- **🔒 Cross-project leak fixed (v0.8.8)** — ambient status / compaction no
+  longer bleed foreign-project runs into the current session. Cwd-scope
+  barrier (`isInProjectScope`), version-independent.
+- **🩺 Doctor runtime-warmup status (v0.8.7)** — `team doctor` shows whether
+  the module-graph warmup fired.
+- **🔍 Cold-verifier agent (v0.8.4)** — adversarial cross-check that re-derives
+  claims WITHOUT trusting prior analysis, catching confirmation bias.
+- **⚡ Per-write validator (v0.8.5)** — zero-cost `JSON.parse` on every
+  `write`/`edit`, appends a `🔴` blocker on malformed files.
+- **🎨 Terminal status (v0.8.3)** — tab title + Ghostty native progress bar.
+- **🧠 Skill confidence revived (v0.8.2)** — `adjustConfidence()` was dead
+  code; the effectiveness system now actually learns.
+- **🔧 Tool-restriction unification (v0.8.0)** — single `resolveToolPolicy`
+  across both spawn paths.
+- **🎯 F6/F1 interop granularity (v0.7.9)** — 7 skill roots, `.pi/agents/`
+  tier, tool wildcards, `excludeExtensions` denylist.
+
+#### v0.7.0 — Phase 0 + Phase 1 roadmap
+- **🛡️ Compaction resilience (O10)** — in-flight runs survive auto-compact.
+- **💰 Cost visibility (O1)** — per-role token + cost attribution.
+- **✋ Plan-level HITL (O5)** — `requirePlanApproval` gates any workflow.
+- **🧠 Cross-run memory (O4)** — `.crew/knowledge.md` injected every run.
+- **🎯 Single-agent cliff hedge** — `team plan singleAgent=true`.
 
 ---
 
@@ -99,6 +97,46 @@ pi-crew          # after npm install
 node ./pi-crew/install.mjs   # from local clone
 ```
 
+> **Split-scope install note (v0.8.11+):** pi installs extensions under
+> `~/.pi/agent/npm/node_modules/<ext>/`, separate from pi's own
+> node_modules tree (nvm / `%APPDATA%\npm` / Volta / fnm). Since v0.8.11
+> pi-crew resolves the `@earendil-works/pi-coding-agent` peer dep robustly
+> across these layouts — no symlink/NODE_PATH workaround needed. If you ever
+> do hit `Cannot find module '@earendil-works/pi-coding-agent'`, set
+> `PI_CREW_PEER_DEP_DIR=<path to the pi-coding-agent package dir>` as a
+> one-line workaround (or install pi-crew in pi's own scope:
+> `npm install -g @earendil-works/pi-crew`).
+
+### Uninstall
+
+`pi uninstall npm:pi-crew` removes the package, but pi doesn't fire an
+extension uninstall hook, so two things `team action=init` created are left
+behind: the **marker-delimited guidance block in AGENTS.md** and the **`.crew/`
+runtime state directory** (run history, artifacts, worktrees). Reverse them
+explicitly:
+
+```bash
+# 1. (Optional) Preview what would be removed, without writing:
+team action=cleanup dryRun=true
+
+# 2. Remove the AGENTS.md guidance block only (.crew/ preserved):
+team action=cleanup
+
+# 3. Remove BOTH the guidance block AND the .crew/ state directory (force):
+team action=cleanup force=true
+
+# 4. Finally, remove the package itself:
+pi uninstall npm:pi-crew
+```
+
+The guidance block is wrapped in `<!-- PI-CREW:GUIDANCE:START -->` /
+`<!-- PI-CREW:GUIDANCE:END -->` markers, so `team action=cleanup` removes
+**only** that block — your own AGENTS.md content is never touched. The
+`.crew/` directory is removed **only** with `force=true` (it's irreversible).
+The user-scope dir (`~/.pi/agent/extensions/pi-crew/`) is owned by
+`pi uninstall` and is never touched by `team action=cleanup`.
+
+
 ---
 
 ## Quick Start

package/package.json

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

package/src/extension/register.ts

@@ -84,6 +84,7 @@ import { runEventBus } from "../ui/run-event-bus.ts";
 import { createTerminalStatusController, type TerminalStatusController } from "../ui/terminal-status.ts";
 import { extractPathFromInput, validateWrittenFile, buildValidationBlocker } from "../runtime/per-write-validator.ts";
 import { startRuntimeWarmup } from "../runtime/runtime-warmup.ts";
+import { primePeerDep } from "../runtime/peer-dep.ts";
 import { createRunSnapshotCache } from "../ui/run-snapshot-cache.ts";
 import { closeWatcher } from "../utils/fs-watch.ts";
 import { RunWatcherRegistry } from "../utils/run-watcher-registry.ts";
@@ -207,6 +208,11 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 	// Warming the graph here + awaiting it at spawn boundaries eliminates the
 	// race window. See src/runtime/runtime-warmup.ts.
 	startRuntimeWarmup();
+	// FIX (split-scope install): preload the ESM peer dep so discover-skills /
+	// skill-instructions can read the REAL getAgentDir (fork-aware) from cache.
+	// Fire-and-forget: getAgentDir() falls back to a safe computed default until
+	// this resolves. See src/runtime/peer-dep.ts.
+	primePeerDep().catch(() => {});
 	// Deploy bundled themes (crew-dark, crew-dracula, etc.) to ~/.pi/agent/themes/
 	// so Pi's theme loader discovers them. Best-effort, idempotent.
 	deployBundledThemes();

package/src/extension/team-tool/lifecycle-actions.ts

@@ -14,6 +14,7 @@ import { enforceDestructiveIntent, intentFromConfig } from "./intent-policy.ts";
 import { executeHook, appendHookEvent } from "../../hooks/registry.ts";
 import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
 import { projectCrewRoot, userCrewRoot } from "../../utils/paths.ts";
+import { removeGuidance } from "../../config/markers.ts";
 import * as path from "node:path";
 
 export function handleWorktrees(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
@@ -123,12 +124,128 @@ export async function handleForget(params: TeamToolParamsValue, ctx: TeamContext
 }
 
 export async function handleCleanup(params: TeamToolParamsValue, ctx: TeamContext): Promise<PiTeamsToolResult> {
+	// Intent policy applies to the cleanup action in BOTH modes (per-run and
+	// project-level). Checked once here so handleRunCleanup/handleProjectCleanup
+	// can stay focused on their own logic.
 	const intentError = enforceDestructiveIntent("cleanup", params, ctx.config);
 	if (intentError) return intentError;
-	if (!params.runId) return result("Cleanup requires runId.", { action: "cleanup", status: "error" }, true);
-	const loaded = loadRunManifestById(ctx.cwd, params.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
-	if (!loaded) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "cleanup", status: "error" }, true);
+	// Two cleanup modes:
+	//  1. WITH runId    → per-run worktree cleanup (existing behavior).
+	//  2. WITHOUT runId → PROJECT-LEVEL uninstall cleanup: removes the
+	//     AGENTS.md guidance block pi-crew injected (`team action=init`) and
+	//     optionally the `.crew/` state dir. Use this before/after
+	//     `pi uninstall npm:pi-crew` to leave the project pristine.
+	//     Issue #35: pi doesn't fire an uninstall hook for extensions, so this
+	//     mode is the documented way to reverse an init.
+	if (params.runId) {
+		return handleRunCleanup(params, ctx);
+	}
+	return handleProjectCleanup(params, ctx);
+}
+
+/**
+ * Project-level uninstall cleanup (no runId). Reverses `team action=init`:
+ * removes the pi-crew guidance block from AGENTS.md (marker-delimited, so
+ * user content is untouched) and, with `force: true`, removes the `.crew/`
+ * runtime state directory. `dryRun: true` previews without writing.
+ *
+ * Safety:
+ *  - `removeGuidance` only touches content between the PI-CREW markers.
+ *  - `.crew/` removal requires explicit `force: true` (it holds run history,
+ *    artifacts, and worktrees — irreversible). Default is guidance-only.
+ *  - The user pi-crew user dir (`~/.pi/agent/extensions/pi-crew/`) is NEVER
+ *    touched here — `pi uninstall` owns that; we only touch project state.
+ */
+function handleProjectCleanup(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+	const cwd = ctx.cwd;
+	const dryRun = params.dryRun === true;
+	const removeState = params.force === true;
+	const scope = typeof params.scope === "string" ? params.scope : "project";
+	if (scope !== "project") {
+		return result(
+			`Project cleanup operates on the project only (got scope='${scope}'). ` +
+				`User-scope files are owned by 'pi uninstall npm:pi-crew'.`,
+			{ action: "cleanup", status: "error", scope },
+			true,
+		);
+	}
+
+	const lines: string[] = ["Project cleanup for pi-crew:"];
+
+	// 1. Remove the AGENTS.md guidance block (marker-delimited → user content preserved).
+	const guidancePath = path.join(cwd, "AGENTS.md");
+	const guidanceResult = dryRun
+		? { path: guidancePath, modified: fs.existsSync(guidancePath), added: [], removed: dryRunRemovedIds(guidancePath) }
+		: removeGuidance(guidancePath);
+	lines.push("AGENTS.md guidance block:");
+	if (guidanceResult.modified) {
+		lines.push(`  - ${dryRun ? "would remove" : "removed"}: ${guidanceResult.removed.length ? guidanceResult.removed.join(", ") : "(marker section)"}`);
+	} else {
+		lines.push("  - (no pi-crew marker section found — nothing to do)");
+	}
+
+	// 2. Optionally remove the .crew/ runtime state directory (force: true).
+	const crewRoot = projectCrewRoot(cwd);
+	lines.push(".crew/ state directory:");
+	const crewExists = fs.existsSync(crewRoot);
+	if (!crewExists) {
+		lines.push(`  - (not present at ${crewRoot} — nothing to do)`);
+	} else if (!removeState) {
+		lines.push(`  - present at ${crewRoot} (preserved — use force: true to remove; contains run history/artifacts/worktrees and is irreversible)`);
+	} else {
+		// SAFETY: realpath + contain-check before rmSync, so a crafted cwd can't
+		// trick us into deleting an arbitrary directory.
+		let resolved: string;
+		try {
+			resolved = fs.realpathSync.native(crewRoot);
+		} catch {
+			lines.push(`  - ERROR: could not resolve ${crewRoot} (skipped)`);
+			return result(lines.join("\n"), { action: "cleanup", status: "ok", scope }, false);
+		}
+		if (!resolved.endsWith(path.sep + ".crew") && !resolved.endsWith("/teams") && path.basename(resolved) !== ".crew") {
+			lines.push(`  - ERROR: refused to remove ${resolved} (does not look like a .crew dir) — skipped`);
+		} else {
+			if (!dryRun) {
+				try {
+					fs.rmSync(resolved, { recursive: true, force: true });
+				} catch (e) {
+					lines.push(`  - ERROR removing ${resolved}: ${(e as Error).message}`);
+				}
+			}
+			lines.push(`  - ${dryRun ? "would remove" : "removed"}: ${resolved}`);
+		}
+	}
+
+	lines.push("");
+	lines.push(
+		dryRun
+			? "(dry-run preview — no files were changed. Re-run without dryRun to apply.)"
+			: "Done. To fully remove pi-crew, also run: pi uninstall npm:pi-crew",
+	);
+	return result(lines.join("\n"), { action: "cleanup", status: "ok", scope }, false);
+}
+
+/** Dry-run helper: read what removeGuidance WOULD remove without writing. */
+function dryRunRemovedIds(guidancePath: string): string[] {
+	try {
+		if (!fs.existsSync(guidancePath)) return [];
+		const content = fs.readFileSync(guidancePath, "utf-8");
+		const startIdx = content.indexOf("<!-- PI-CREW:GUIDANCE:START -->");
+		const endIdx = content.indexOf("<!-- PI-CREW:GUIDANCE:END -->");
+		if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) return [];
+		// Cheap approximation: report the marker section as a unit. Exact block
+		// IDs aren't needed for the dry-run summary; the non-dryRun path uses
+		// removeGuidance which returns the precise removed IDs.
+		return ["pi-crew-overview", "pi-crew-commands"];
+	} catch {
+		return [];
+	}
+}
 
+/** Per-run worktree cleanup (existing behavior, preserved). */
+async function handleRunCleanup(params: TeamToolParamsValue, ctx: TeamContext): Promise<PiTeamsToolResult> {
+	const loaded = loadRunManifestById(ctx.cwd, params.runId!); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
+	if (!loaded) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "cleanup", status: "error", runId: params.runId }, true);
 	// Ownership check — prevent cross-session worktree cleanup unless force is set
 	const foreignRun = typeof loaded.manifest.ownerSessionId === "string" && loaded.manifest.ownerSessionId !== ctx.sessionId;
 	if (foreignRun && !params.force) return result(`Run ${params.runId} belongs to another session. Use force: true to override.`, { action: "cleanup", status: "error", runId: loaded.manifest.runId }, true);

package/src/extension/team-tool-types.ts

@@ -10,6 +10,8 @@ export interface TeamToolDetails {
 	resumedIds?: string[];
 	retriedTaskIds?: string[];
 	mailboxIds?: string[];
+	/** Resource scope affected by the action (e.g. cleanup: "project"). */
+	scope?: string;
 	/** Run metrics for compact display in TUI tool result rendering. */
 	metrics?: { taskCount?: number; completedCount?: number; totalTokens?: number; totalCost?: number; durationMs?: number; consistencyScore?: number };
 	/** Structured data for programmatic consumption (e.g. TUI widgets). */

package/src/runtime/async-runner.ts

@@ -6,6 +6,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { logInternalError } from "../utils/internal-error.ts";
 import { appendEvent } from "../state/event-log.ts";
 import { sanitizeEnvSecrets } from "../utils/env-filter.ts";
+import { resolvePeerDepDir, PEER_DEP_DIR_ENV } from "./peer-dep.ts";
 import {
 	registerWorker,
 	unregisterWorker,
@@ -202,6 +203,15 @@ export async function spawnBackgroundTeamRun(manifest: TeamRunManifest): Promise
 	// FIX: removed delete workarounds — with explicit allowlist, these vars
 	// are no longer auto-leaked. Matches child-pi.ts.
 
+	// FIX (split-scope install): pass the resolved peer-dep dir to the child so
+	// it can resolve @earendil-works/pi-coding-agent WITHOUT the ~200ms
+	// `npm root -g` probe. No-op when pi-crew and pi are co-located. See
+	// src/runtime/peer-dep.ts.
+	const peerDepDir = resolvePeerDepDir();
+	const childEnv = peerDepDir
+		? { ...filteredEnv, [PEER_DEP_DIR_ENV]: peerDepDir }
+		: filteredEnv;
+
 	const loader = resolveTypeScriptLoader();
 	if (!loader) {
 		const message = buildLoaderUnavailableMessage(packageRootFromRuntime());
@@ -227,7 +237,7 @@ export async function spawnBackgroundTeamRun(manifest: TeamRunManifest): Promise
 		detached: true,
 		setsid: true,
 		stdio: ["ignore", "pipe", "pipe"],
-		env: filteredEnv,
+		env: childEnv,
 		windowsHide: true,
 	} as unknown as Parameters<typeof spawn>[2];
 	const child = spawn(process.execPath, command.args, spawnOpts);

package/src/runtime/background-runner.ts

@@ -19,6 +19,7 @@ import {
 } from "../workflows/discover-workflows.ts";
 // Heavy runtime — lazy-loaded to avoid pulling team-runner into background-runner
 // at module load time. Only needed when a background run actually starts.
+import { primePeerDep } from "./peer-dep.ts";
 import type { executeTeamRun as ExecuteTeamRunFn } from "./team-runner.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 
@@ -27,6 +28,10 @@ async function executeTeamRun(
 	...args: Parameters<typeof ExecuteTeamRunFn>
 ): Promise<Awaited<ReturnType<typeof ExecuteTeamRunFn>>> {
 	if (!_cachedExecuteTeamRun) {
+		// FIX (split-scope install): prime the ESM peer dep BEFORE team-runner is
+		// imported, so its transitive skill-instructions.ts can read getAgentDir()
+		// from the primed cache instead of crashing on `Cannot find module`.
+		await primePeerDep().catch(() => {});
 		// LAZY: avoid pulling team-runner into background-runner at module load time.
 		const mod = await import("./team-runner.ts");
 		_cachedExecuteTeamRun = mod.executeTeamRun;

package/src/runtime/model-fallback.ts

@@ -186,6 +186,29 @@ const RETRYABLE_MODEL_FAILURE_PATTERNS = [
 	/\b502\b/,
 	/\b503\b/,
 	/\b504\b/,
+	//
+	// Provider-side 5xx / generic api_error. The pi-core retry layer already
+	// retries these (agent-session.ts matches `500|server error|internal error`),
+	// but the pi-crew MODEL FALLBACK layer must ALSO treat them as retryable so
+	// that when the provider is hard-down across all 3 provider retries, we fail
+	// over to the next configured model instead of giving up. Reported case
+	// (2026-06-17): `500 {"type":"error","error":{"type":"api_error",
+	// "message":"unknown error, 999 (1000)"}}` — a transient provider outage that
+	// should trigger the fallback chain, not abort.
+	//
+	// `api_error` is the OpenAI-compatible generic error type (vs rate_limit_error
+	// / overloaded_error / etc.) and almost always means a transient server fault.
+	//
+	// `unknown error` is the body of the generic message; `internal`/`server`
+	// catch the common phrasings. `\b500\b`/`\b501\b` catch the HTTP status in
+	// the rendered error string.
+	/\b500\b/,
+	/\b501\b/,
+	/api_error/i,
+	/unknown error/i,
+	/internal(?:_server)?[ _]error/i,
+	/server error/i,
+	/bad gateway/i,
 ];
 
 // These patterns indicate auth/key/billing issues that will never succeed on retry.

package/src/runtime/peer-dep.ts

@@ -0,0 +1,296 @@
+/**
+ * Robust resolution + async loading of the @earendil-works/pi-coding-agent
+ * peer dependency. Fixes the "Cannot find module '@earendil-works/pi-coding-agent'"
+ * crash that blocks ALL team runs when pi-crew and pi are installed in
+ * SEPARATE node_modules trees.
+ *
+ * PROBLEM (Windows / global installs — reported 2026-06-17)
+ * pi-crew is a pi EXTENSION. pi installs extensions under
+ * `~/.pi/agent/npm/node_modules/<ext>/`, but pi itself (the
+ * @earendil-works/pi-coding-agent package that extensions import from)
+ * usually lives in a DIFFERENT node_modules tree — a global one (nvm,
+ * %APPDATA%\npm, Volta, fnm, pnpm-global). Node's resolver only walks UP
+ * through ancestor `node_modules` of the importing file, so a file under
+ * `~/.pi/agent/npm/node_modules/pi-crew/...` CANNOT resolve a peer dep
+ * installed under `~/.nvm/.../lib/node_modules/`. Every static
+ * `import { X } from "@earendil-works/pi-coding-agent"` that executes inside
+ * a SPAWNED CHILD PROCESS (the detached background team runner started by
+ * async-runner.spawnBackgroundTeamRun) therefore crashes at module load,
+ * leaving all team runs permanently `queued`.
+ *
+ * ADDITIONAL CONSTRAINT (verified empirically 2026-06-17)
+ * pi-coding-agent ships as ESM-only (`"type":"module"`, exports map has only
+ * an `import` condition). CJS `require()` / `createRequire(dir)(name)` fails
+ * with ERR_PACKAGE_PATH_NOT_EXPORTED under plain node AND under jiti/tsx. The
+ * ONLY working load mechanism is a dynamic `import()` of the resolved ESM
+ * entry file URL. Hence: sync resolution of the DIR, async load of the MODULE.
+ *
+ * APPROACH
+ *  - resolvePeerDep()     (sync)  — find the install dir across many layouts.
+ *  - primePeerDep()       (async) — dynamic-import the resolved entry, cache
+ *                                   the module namespace. Memoized. Called
+ *                                   once per process during bootstrap.
+ *  - getAgentDir()        (sync)  — read the cached module's getAgentDir.
+ *                                   Falls back to a computed default if the
+ *                                   cache was never primed, so it NEVER throws.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { resolveNpmGlobalRoot } from "./pi-spawn.ts";
+
+/**
+ * The pi-coding-agent peer dependency package name(s) we can be loaded by.
+ * @earendil-works is the canonical scope; @mariozechner is the historical fork.
+ */
+export const PEER_DEP_NAMES = [
+	"@earendil-works/pi-coding-agent",
+	"@mariozechner/pi-coding-agent",
+] as const;
+
+/**
+ * Env var a parent pi-crew process sets on spawned children so they can resolve
+ * the peer dep WITHOUT running `npm root -g` (~200ms probe). The resolver
+ * checks this FIRST. Absent (older parent, direct invocation, tests) → falls
+ * through to the probing strategies. Also lets users override the resolution
+ * explicitly as a last-resort fix.
+ */
+export const PEER_DEP_DIR_ENV = "PI_CREW_PEER_DEP_DIR";
+
+type PeerDepModule = typeof import("@earendil-works/pi-coding-agent");
+
+interface ResolvedPeerDep {
+	dir: string;
+	name: string;
+	/** file:// URL of the ESM entry (exports["."].import || main). */
+	mainUrl: string;
+}
+
+let cachedResolve: ResolvedPeerDep | undefined | null = null;
+let cachedModule: PeerDepModule | undefined;
+let primingPromise: Promise<PeerDepModule> | undefined;
+
+/**
+ * Build the ordered list of "resolution bases" — paths to seed
+ * `createRequire(...).resolve()` from. Node walks UP `node_modules` from each
+ * base's directory, so any base inside (or beside) the peer dep's package
+ * tree will find it. Pure given env/process inputs; exported for unit tests.
+ */
+export function peerDepResolutionBases(): string[] {
+	const bases: string[] = [];
+
+	// 0. Parent-provided hint (fastest — no probe). Set by async-runner.
+	const envHint = process.env[PEER_DEP_DIR_ENV]?.trim();
+	if (envHint) bases.push(path.resolve(envHint));
+
+	// 1. This file's location — works when pi-crew and pi-coding-agent share a
+	//    node_modules ancestor (the common co-located install).
+	bases.push(fileURLToPath(import.meta.url));
+
+	// 2. The entry script. In the PARENT (main pi process) argv[1] is pi's CLI
+	//    script, which lives INSIDE pi-coding-agent's package → resolves. In a
+	//    SPAWNED CHILD argv[1] is a pi-crew script → cheap miss, falls through.
+	const argv1 = process.argv[1];
+	if (argv1) bases.push(path.resolve(argv1));
+
+	// 3. The Node binary's global node_modules. Covers nvm / nvm-windows /
+	//    Volta / fnm where pi-coding-agent is `npm i -g`'d: node is at
+	//    <prefix>/bin/node and globals live at <prefix>/lib/node_modules.
+	try {
+		const execDir = path.dirname(fs.realpathSync.native(process.execPath));
+		bases.push(path.join(path.dirname(execDir), "lib", "node_modules"));
+		// Some layouts (Windows global, or a bare node_modules sibling of bin).
+		bases.push(path.join(execDir, "node_modules"));
+	} catch {
+		/* realpath best-effort */
+	}
+
+	// 4. `npm root -g` — the canonical cross-layout global root (memoized in
+	//    pi-spawn.ts, ~200ms once). Derive the scoped package dirs from it.
+	const npmRoot = resolveNpmGlobalRoot();
+	if (npmRoot) {
+		for (const pkgName of PEER_DEP_NAMES) {
+			bases.push(path.join(npmRoot, ...pkgName.split("/")));
+		}
+	}
+
+	// 5. Windows %APPDATA%\npm static layout (legacy npm-global, pre-npm-root-g).
+	if (process.env.APPDATA) {
+		bases.push(path.join(process.env.APPDATA, "npm", "node_modules"));
+	}
+
+	return bases;
+}
+
+/** Pull the ESM entry path out of package.json (exports import || main). */
+function extractEsmMain(pkg: unknown): string | undefined {
+	if (!pkg || typeof pkg !== "object") return undefined;
+	const p = pkg as Record<string, unknown>;
+	const exp = p.exports;
+	if (exp && typeof exp === "object") {
+		const dot = (exp as Record<string, unknown>)["."];
+		if (dot && typeof dot === "object") {
+			const d = dot as Record<string, unknown>;
+			const rel = d.import ?? d.default ?? d.module;
+			if (typeof rel === "string") return rel;
+		} else if (typeof dot === "string") {
+			return dot;
+		}
+	}
+	const main = p.main;
+	return typeof main === "string" ? main : undefined;
+}
+
+/**
+ * Walk the node_modules resolution algorithm MANUALLY from `start` looking for
+ * any of `names`. We do NOT use createRequire/require.resolve here because
+ * pi-coding-agent ships an ESM-only package with a restrictive exports map
+ * (only the `.` import condition) — `require.resolve("<pkg>/package.json")`
+ * and `require.resolve("<pkg>")` both throw ERR_PACKAGE_PATH_NOT_EXPORTED.
+ * Reading package.json directly from the walked dir sidesteps the exports map
+ * entirely (exports only governs subpath IMPORTS, not raw file reads).
+ *
+ * At each directory we check BOTH `<dir>/node_modules/<pkg>` (the standard
+ * container case) AND `<dir>/<pkg>` (handles a base that IS a node_modules
+ * dir, e.g. the output of `npm root -g`), then walk up to root.
+ */
+function findPackageDir(
+	start: string,
+	names: readonly string[],
+): { dir: string; name: string } | undefined {
+	let dir = path.resolve(start);
+	try {
+		if (fs.statSync(dir).isFile()) dir = path.dirname(dir);
+	} catch {
+		/* treat as directory */
+	}
+	while (true) {
+		for (const name of names) {
+			const segs = name.split("/");
+			const candidates = [
+				path.join(dir, "node_modules", ...segs, "package.json"),
+				path.join(dir, ...segs, "package.json"),
+			];
+			for (const pkgJson of candidates) {
+				try {
+					const pkg = JSON.parse(fs.readFileSync(pkgJson, "utf-8"));
+					if (pkg?.name === name) {
+						return { dir: path.dirname(pkgJson), name };
+					}
+				} catch {
+					/* not present at this candidate */
+				}
+			}
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) break; // reached filesystem root
+		dir = parent;
+	}
+	return undefined;
+}
+
+function tryResolveFrom(base: string): ResolvedPeerDep | undefined {
+	const found = findPackageDir(base, PEER_DEP_NAMES);
+	if (!found) return undefined;
+	try {
+		const pkg = JSON.parse(
+			fs.readFileSync(path.join(found.dir, "package.json"), "utf-8"),
+		);
+		const mainRel = extractEsmMain(pkg);
+		if (!mainRel) return undefined;
+		const mainAbs = path.resolve(found.dir, mainRel);
+		if (!fs.existsSync(mainAbs)) return undefined;
+		return { dir: found.dir, name: found.name, mainUrl: pathToFileURL(mainAbs).href };
+	} catch {
+		return undefined;
+	}
+}
+
+/** Resolve the peer dep install dir + ESM entry URL. Memoized (sync). */
+export function resolvePeerDep(): ResolvedPeerDep | undefined {
+	if (cachedResolve !== null) return cachedResolve ?? undefined;
+	for (const base of peerDepResolutionBases()) {
+		const found = tryResolveFrom(base);
+		if (found) {
+			cachedResolve = found;
+			return found;
+		}
+	}
+	cachedResolve = null; // mark attempted-and-failed; don't re-probe per call
+	return undefined;
+}
+
+/** Just the install directory (for env-hint propagation to children). */
+export function resolvePeerDepDir(): string | undefined {
+	return resolvePeerDep()?.dir;
+}
+
+/**
+ * Dynamic-import the peer dep module, caching the namespace. Memoized via a
+ * shared promise so concurrent callers share one load. On failure the promise
+ * is cleared so a later caller can retry. Safe to call repeatedly.
+ */
+export function primePeerDep(): Promise<PeerDepModule> {
+	if (cachedModule) return Promise.resolve(cachedModule);
+	if (primingPromise) return primingPromise;
+	primingPromise = (async () => {
+		const resolved = resolvePeerDep();
+		if (!resolved) {
+			throw new Error(buildMissingMessage());
+		}
+		cachedModule = (await import(resolved.mainUrl)) as PeerDepModule;
+		return cachedModule;
+	})();
+	// Clear on failure so a later caller can retry (e.g. after env fix).
+	primingPromise.catch(() => {
+		primingPromise = undefined;
+	});
+	return primingPromise;
+}
+
+/** Async module accessor (primes if needed). */
+export async function loadPeerDep(): Promise<PeerDepModule> {
+	return primePeerDep();
+}
+
+function buildMissingMessage(): string {
+	return (
+		`pi-crew could not resolve the @earendil-works/pi-coding-agent peer dependency.\n` +
+		`This usually means pi-crew and pi are installed in separate node_modules trees\n` +
+		`(e.g. pi-crew under ~/.pi/agent/npm/ but pi under an nvm/Volta/fnm global scope).\n` +
+		`Resolution bases tried:\n` +
+		peerDepResolutionBases().map((b) => `  - ${b}`).join("\n") +
+		`\nFix: install pi-crew in the SAME scope as pi, e.g.\n` +
+		`  npm install -g @earendil-works/pi-crew\n` +
+		`or set the env var ${PEER_DEP_DIR_ENV}=<path to the pi-coding-agent package dir>.`
+	);
+}
+
+/**
+ * Read the user agent dir via the REAL peer-dep getAgentDir (fork-aware:
+ * correct for pi, tau, and renamed forks). Sync; reads the primed cache.
+ *
+ * If the cache was never primed (e.g. called before bootstrap completes, or
+ * prime failed), falls back to a computed default so it NEVER throws. The
+ * default matches standard pi (`~/.pi/agent`) and respects the
+ * `PI_CODING_AGENT_DIR` override — correct for the overwhelmingly common
+ * case. Forks rely on the primed real function (register.ts primes at startup).
+ */
+export function getAgentDir(): string {
+	if (cachedModule?.getAgentDir) {
+		try {
+			return cachedModule.getAgentDir();
+		} catch {
+			/* fall through to computed default */
+		}
+	}
+	return process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
+}
+
+/** @internal — reset all caches for unit tests. */
+export function __resetPeerDepCacheForTest(): void {
+	cachedResolve = null;
+	cachedModule = undefined;
+	primingPromise = undefined;
+}

package/src/runtime/skill-instructions.ts

@@ -22,7 +22,11 @@ const PACKAGE_SKILLS_DIR = path.resolve(
 	"skills",
 );
 import * as os from "node:os";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
+// peer-dep.ts resolves @earendil-works/pi-coding-agent robustly across install
+// layouts (extension-under-~/.pi + pi-under-global). A static `import { getAgentDir }`
+// here crashes detached child processes when pi-crew and pi live in separate
+// node_modules trees. See src/runtime/peer-dep.ts.
+import { getAgentDir } from "../runtime/peer-dep.ts";
 const MAX_SKILL_CHARS = 1500;
 const MAX_TOTAL_CHARS = 6000;
 const MAX_SKILL_NAME_CHARS = 80;

package/src/skills/discover-skills.ts

@@ -2,7 +2,9 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
+// peer-dep.ts resolves @earendil-works/pi-coding-agent robustly across install
+// layouts. See src/runtime/peer-dep.ts (split-scope install fix).
+import { getAgentDir } from "../runtime/peer-dep.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { isSafePathId, resolveContainedPath, resolveRealContainedPath } from "../utils/safe-paths.ts";