pi-crew 0.8.11 → 0.8.13

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # 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
@@ -2546,3 +2590,41 @@ correctness+error-handling, and performance+architecture audits across 77 source
 - TypeScript: 0 errors
 - Skills: 37/37 PASS
 - New modules: 11 files, 2,267 LOC
+
+## [0.8.13] — user-scope cleanup + install side-effects warning (Issue #35) (2026-06-18)
+
+Follow-up to issue #35's latest comment ("pi-crew leaves behind user-level
+junk"). Two of the three points raised were valid; both addressed.
+
+### `team action=cleanup scope=user` — new user-level cleanup mode
+Removes pi-crew user-scope state that `pi uninstall npm:pi-crew` leaves behind:
+- `~/.pi/agent/extensions/pi-crew/` — pi-crew runtime state (artifacts, state,
+  config.json). Regenerable, always removed.
+- `~/.pi/agent/agents/*.md.bak-<timestamp>-<hex>` — smoke-test backup junk
+  pi-crew's own tests leave behind. NEVER touches real `*.md` agent files
+  (pi-crew can't tell user-authored vs test-copied — only the timestamped
+  `.bak-*` pattern is removed).
+- `~/.pi/agent/pi-crew.json` — global config. Gated on `force=true` (may hold
+  your customized settings).
+
+`dryRun=true` previews; safe by default. Routes via the new `scope=user` flag
+on `team action=cleanup`.
+
+### Install side-effects warning (install.mjs)
+The postinstall script now prints an explicit "What pi-crew writes (and how to
+undo it)" block: AGENTS.md injection (marker-delimited, on `init` only),
+`.crew/` runtime dir, the global config created at install, and the full
+uninstall command sequence (project + user + `pi uninstall`). Nothing is hidden
+behind install — be upfront about side effects.
+
+### README Uninstall section expanded
+Split into Project scope + User scope subsections, with the full 6-step
+uninstall flow and a note that authored agent files are never touched.
+
+### On the third claim (hijacks pi-intercom)
+Still not reproduced. Verified a third time: `grep -rni pi-intercom src/` → 0
+references. `crew-input-router.ts:11` passes slash commands through unchanged.
+The reply on the issue asks again for a concrete repro.
+
+typecheck clean; +6 user-scope cleanup tests + 1 routing test update; full
+suite 2963/0.

package/README.md

@@ -107,6 +107,56 @@ node ./pi-crew/install.mjs   # from local clone
 > 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 several things pi-crew created are left behind.
+Reverse them explicitly with `team action=cleanup`. There are **two scopes**:
+
+#### Project scope (reverse `team action=init`)
+
+```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
+```
+
+The guidance block is wrapped in `<!-- PI-CREW:GUIDANCE:START -->` /
+`<!-- PI-CREW:GUIDANCE:END -->` markers, so 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).
+
+#### User scope (remove user-level state `pi uninstall` leaves behind)
+
+```bash
+# 4. Preview + remove pi-crew user-scope junk:
+team action=cleanup scope=user dryRun=true   # preview
+team action=cleanup scope=user               # remove ~/.pi/agent/extensions/pi-crew/
+                                              #   + pi-crew smoke-test *.bak files
+
+# 5. (Optional) Also remove the global config (holds your settings):
+team action=cleanup scope=user force=true    # also removes ~/.pi/agent/pi-crew.json
+```
+
+This removes the pi-crew state dir (`~/.pi/agent/extensions/pi-crew/`, which
+holds run artifacts + state), the global config (with `force=true`), and the
+`*.md.bak-<timestamp>` smoke-test backup files pi-crew's own tests may leave in
+`~/.pi/agent/agents/`. **Your authored agent files (`*.md`) are never touched**
+— pi-crew can't tell which were user-created vs test-copied, so only the
+clearly-pi-crew `.bak-*` backups are removed.
+
+#### Final step
+
+```bash
+# 6. Remove the package itself:
+pi uninstall npm:pi-crew
+```
+
 
 ---
 

package/install.mjs

@@ -63,3 +63,24 @@ console.log("\nFor local development from a cloned repo:");
 console.log("  pi install .");
 console.log("\nChild workers are enabled by default. For dry runs, set runtime.mode=scaffold or executeWorkers=false.");
 console.log("To force-disable or force-enable workers in a shell, use PI_TEAMS_EXECUTE_WORKERS=0/1.");
+
+// Side-effects warning (Issue #35): be upfront about what pi-crew writes and
+// how to fully uninstall it. Nothing runs on install/registration itself; the
+// writes below only happen when you explicitly invoke `team action=init`.
+console.log("\n--- What pi-crew writes (and how to undo it) ---");
+console.log("pi-crew itself writes nothing on install. The following only happens when you");
+console.log("explicitly run `team action=init` in a project:");
+console.log("  - A marker-delimited block is injected into the project's AGENTS.md.");
+console.log("    (Wrapped in <!-- PI-CREW:GUIDANCE:START/END --> — your content is never touched.)");
+console.log("  - A `.crew/` runtime state dir is created in the project (run history + artifacts).");
+console.log("  - With --copy-builtins: bundled agents/teams/workflows are copied into the project.");
+console.log("This install also created the global config above (`~/.pi/agent/pi-crew.json`).");
+console.log("\nFull uninstall (in order):");
+console.log("  team action=cleanup dryRun=true       # preview what would be removed (project)");
+console.log("  team action=cleanup                    # remove the AGENTS.md guidance block");
+console.log("  team action=cleanup force=true         # also remove the .crew/ project state dir");
+console.log("  team action=cleanup scope=user         # remove pi-crew user-scope junk");
+console.log("                                          #   (~/.pi/agent/extensions/pi-crew/ + test .bak files)");
+console.log("  team action=cleanup scope=user force=true  # also remove ~/.pi/agent/pi-crew.json");
+console.log("  pi uninstall npm:pi-crew               # remove the package itself");
+console.log("See the README 'Uninstall' section for details.");

package/package.json

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

package/src/extension/help.ts

@@ -22,10 +22,10 @@ export function piTeamsHelp(): string {
 		"- /team-mascot",
 		"- /team-transcript <runId> [taskId]",
 		"- /team-result <runId> [taskId]",
-		"- /team-manager",
+		"- /team-manager — interactive menu (alias: /team-cleanup-menu)",
 		"",
 		"Maintenance:",
-		"- /team-cleanup <runId> [--force]",
+		"- /team-cleanup <runId> [--force]  (or scope=project/user for uninstall cleanup)",
 		"- /team-forget <runId> --confirm [--force]",
 		"- /team-prune --keep=20 --confirm",
 		"",

package/src/extension/register.ts

@@ -123,6 +123,7 @@ import { registerContextStatusInjection } from "./context-status-injection.ts";
 import { registerTeamTool } from "./registration/team-tool.ts";
 import { handleTeamTool } from "./team-tool.ts";
 import { persistScheduledJobUpdate } from "./team-tool/handle-schedule.ts";
+import { shouldBlockDestructiveTeamAction } from "./team-tool/destructive-gate.ts";
 
 let _cachedOTLPExporter: typeof OTLPExporterType | undefined;
 async function importOTLPExporter(): Promise<typeof OTLPExporterType> {
@@ -1992,13 +1993,11 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 		const input = asRecord(rawInput);
 		if (!input) return;
 		const action = typeof input.action === "string" ? input.action : undefined;
-		const destructiveActions = new Set(["delete", "forget", "prune", "cleanup"]);
-		if (!action || !destructiveActions.has(action)) return;
-		const forceBypassesReferenceChecks = action === "delete" && input.force === true;
-		if (input.confirm === true || forceBypassesReferenceChecks) return;
+		const reason = shouldBlockDestructiveTeamAction(action, input);
+		if (!reason) return;
 		return {
-			block: true,
-			reason: `Destructive action '${action}' requires confirm=true${action === "delete" ? " (or force=true to bypass reference checks)" : ""}.`,
+			block: true as const,
+			reason,
 		};
 	});
 

package/src/extension/registration/commands.ts

@@ -439,7 +439,11 @@ export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommand
 	},
 })
 
-	pi.registerCommand("team-cleanup", { description: "Open a simple pi-crew interactive manager", handler: handleTeamManagerCommand });
+	pi.registerCommand("team-manager", { description: "Open the pi-crew interactive menu (list/run/status/cleanup/manage resources/doctor)", handler: handleTeamManagerCommand });
+	// Backward-compat alias: this command was originally registered as "team-cleanup"
+	// (the interactive menu predates the runId-targeted cleanup action). Keep both so
+	// existing muscle memory + help docs both work.
+	pi.registerCommand("team-cleanup-menu", { description: "Alias for /team-manager (pi-crew interactive menu)", handler: handleTeamManagerCommand });
 
 	pi.registerCommand("team-result", { description: "Open a pi-crew agent result viewer: <runId> [taskId]", getArgumentCompletions: async (argumentPrefix: string) => { const parts = argumentPrefix.trim().split(/\s+/); return parts.length <= 1 ? suggestRunIds(parts[0] ?? "") : suggestTaskIds(parts[0] ?? "", parts[1] ?? ""); }, handler: async (args: string, ctx: ExtensionCommandContext) => {
 		const [runId, rawTaskId] = args.trim().split(/\s+/).filter(Boolean);

package/src/extension/team-onboard.ts

@@ -75,11 +75,13 @@ function loadRunSummaries(cwd: string, options: OnboardingOptions = {}): RunSumm
 }
 
 /**
- * Format duration in minutes.
+ * Format duration in minutes. Defensive against missing/invalid timestamps
+ * (e.g. legacy test runs) — returns "?" instead of "NaNm".
  */
-function formatDuration(createdAt: string, completedAt?: string): string {
+export function formatDuration(createdAt: string, completedAt?: string): string {
   const start = new Date(createdAt).getTime();
   const end = completedAt ? new Date(completedAt).getTime() : Date.now();
+  if (!Number.isFinite(start) || !Number.isFinite(end) || end < start) return "?";
   const minutes = Math.round((end - start) / 1000 / 60);
   if (minutes < 1) return "<1m";
   if (minutes >= 60) return `${Math.round(minutes / 60)}h`;
@@ -136,8 +138,10 @@ export function buildTeamOnboarding(team: string, cwd: string, options: Onboardi
     for (const run of runs) {
       const duration = formatDuration(run.createdAt, run.completedAt);
       const goalPreview = run.goal ? run.goal.slice(0, 40) : "N/A";
-      const statusIcon = run.status === "completed" ? "✅" : run.status === "failed" ? "❌" : "⚠️";
-      lines.push(`| \`${run.runId.slice(-8)}\` | ${goalPreview}${run.goal.length > 40 ? "..." : ""} | ${duration} | ${statusIcon} ${run.status} |`);
+      const goalSuffix = run.goal && run.goal.length > 40 ? "..." : "";
+      const status = run.status ?? "unknown";
+      const statusIcon = status === "completed" ? "✅" : status === "failed" ? "❌" : status === "cancelled" ? "⏹️" : "⚠️";
+      lines.push(`| \`${run.runId.slice(-8)}\` | ${goalPreview}${goalSuffix} | ${duration} | ${statusIcon} ${status} |`);
     }
     lines.push("");
   }

package/src/extension/team-tool/destructive-gate.ts

@@ -0,0 +1,47 @@
+/**
+ * Permission gate logic for destructive team actions (delete/forget/prune/cleanup).
+ *
+ * Extracted from register.ts `pi.on("tool_call")` handler into a pure function
+ * so the gate logic is unit-testable in isolation (the handler itself is hard
+ * to test because it's an async event listener on the Pi extension API).
+ *
+ * Returns `undefined` when the action is ALLOWED, or a block `reason` string
+ * when it should be blocked. The handler wraps this and emits the `{block, reason}`
+ * shape Pi expects.
+ *
+ * Rules (in order):
+ *  1. Non-team / non-destructive actions → allowed (caller pre-filters, but safe).
+ *  2. `cleanup` with `dryRun=true` → ALWAYS allowed (a preview writes nothing,
+ *     so gating it would block users from previewing what cleanup would do —
+ *     this was a UX bug: team action=cleanup dryRun=true returned "requires
+ *     confirm=true" even though it changed no files).
+ *  3. `confirm=true` on the input → allowed (explicit user intent).
+ *  4. `delete` with `force=true` → allowed (force bypasses reference checks).
+ *  5. Otherwise → blocked with a reason telling the user what to pass.
+ */
+
+export const DESTRUCTIVE_TEAM_ACTIONS = new Set(["delete", "forget", "prune", "cleanup"]);
+
+export interface TeamToolInputLike {
+	action?: unknown;
+	confirm?: unknown;
+	force?: unknown;
+	dryRun?: unknown;
+}
+
+/**
+ * Decide whether a destructive team action should be blocked.
+ * @returns block reason string, or `undefined` to allow.
+ */
+export function shouldBlockDestructiveTeamAction(
+	action: string | undefined,
+	input: TeamToolInputLike,
+): string | undefined {
+	if (!action || !DESTRUCTIVE_TEAM_ACTIONS.has(action)) return undefined;
+	// dryRun cleanup is a PREVIEW (no writes) — never needs confirm.
+	if (action === "cleanup" && input.dryRun === true) return undefined;
+	if (input.confirm === true) return undefined;
+	const forceBypassesReferenceChecks = action === "delete" && input.force === true;
+	if (forceBypassesReferenceChecks) return undefined;
+	return `Destructive action '${action}' requires confirm=true${action === "delete" ? " (or force=true to bypass reference checks)" : ""}.`;
+}

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

@@ -13,7 +13,8 @@ import { RUN_NOT_FOUND_HINT } from "./run-not-found.ts";
 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 { projectCrewRoot, userCrewRoot, userPiRoot } 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,261 @@ 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);
+	// Three cleanup modes:
+	//  1. WITH runId              → per-run worktree cleanup (existing behavior).
+	//  2. WITHOUT runId, scope=project (default) → PROJECT-LEVEL uninstall:
+	//     removes the AGENTS.md guidance block + optionally `.crew/`. Reverses
+	//     `team action=init`.
+	//  3. WITHOUT runId, scope=user → USER-LEVEL cleanup: removes pi-crew
+	//     user-scope state that `pi uninstall` leaves behind (config.json,
+	//     `~/.pi/agent/extensions/pi-crew/` state, junk `.bak` agent files
+	//     from pi-crew smoke tests). Issue #35 comment: "pi-crew leaves behind
+	//     user-level junk" — this closes that gap.
+	if (params.runId) {
+		return handleRunCleanup(params, ctx);
+	}
+	if (params.scope === "user") {
+		return handleUserCleanup(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.
+ *  - User-scope cleanup (`scope=user`) is a SEPARATE handler — see
+ *    `handleUserCleanup`.
+ */
+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 [];
+	}
+}
+
+/**
+ * User-level cleanup (`scope=user`, no runId). Removes pi-crew user-scope
+ * state that `pi uninstall npm:pi-crew` leaves behind (Issue #35 comment:
+ * "pi-crew leaves behind user-level junk"). Targets ONLY pi-crew-owned paths:
+ *
+ *  1. `~/.pi/agent/extensions/pi-crew/` — pi-crew state dir (artifacts,
+ *     state, config.json). Owned by pi-crew, safe to remove.
+ *  2. `~/.pi/agent/pi-crew.json` — pi-crew global config (only with force).
+ *  3. `~/.pi/agent/agents/*.bak-*` junk files from pi-crew smoke tests
+ *     (pattern: `*.md.bak-<timestamp>-<hex>` — these are pi-crew test
+ *     leftovers, never user data).
+ *
+ * Safety:
+ *  - NEVER removes user-authored agent files (`~/.pi/agent/agents/*.md`)
+ *    because pi-crew cannot tell which were user-created vs test-copied —
+ *    only the timestamped `.bak-*` backups (clearly pi-crew test junk).
+ *  - The state dir removal requires force=true by default is NOT required
+ *    (it's pi-crew's own runtime cache, regenerable), but config.json removal
+ *    IS gated on force=true (it may hold user-customized settings).
+ *  - dryRun=true previews without writing.
+ */
+function handleUserCleanup(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+	const dryRun = params.dryRun === true;
+	const force = params.force === true;
+	const lines: string[] = ["User-scope cleanup for pi-crew:"];
+
+	// 1. pi-crew user state dir (~/.pi/agent/extensions/pi-crew/) — always safe
+	//    to remove (regenerable runtime cache: artifacts + state). This is the
+	//    bulk of the "user-level junk".
+	const crewStateDir = userCrewRoot();
+	lines.push(`pi-crew user state dir (${crewStateDir}):`);
+	let crewStateBytes = 0;
+	if (fs.existsSync(crewStateDir)) {
+		try {
+			crewStateBytes = dirSize(crewStateDir);
+		} catch { /* best-effort size */ }
+		if (!dryRun) {
+			try { fs.rmSync(crewStateDir, { recursive: true, force: true }); }
+			catch (e) { lines.push(`  - ERROR removing: ${(e as Error).message}`); }
+		}
+		lines.push(`  - ${dryRun ? "would remove" : "removed"}: ${crewStateDir} (${formatBytes(crewStateBytes)})`);
+	} else {
+		lines.push("  - (not present — nothing to do)");
+	}
+
+	// 2. pi-crew global config (~/.pi/agent/pi-crew.json) — gated on force=true
+	//    because it may hold user-customized settings (autonomous profile, model
+	//    overrides, etc.). Default preserves it.
+	const userConfigPath = path.join(userPiRoot(), "pi-crew.json");
+	lines.push("pi-crew global config:");
+	if (!fs.existsSync(userConfigPath)) {
+		lines.push(`  - (not present at ${userConfigPath} — nothing to do)`);
+	} else if (!force) {
+		lines.push(`  - present at ${userConfigPath} (preserved — use force: true to remove; may hold your customized settings)`);
+	} else {
+		if (!dryRun) {
+			try { fs.rmSync(userConfigPath, { force: true }); }
+			catch (e) { lines.push(`  - ERROR removing: ${(e as Error).message}`); }
+		}
+		lines.push(`  - ${dryRun ? "would remove" : "removed"}: ${userConfigPath}`);
+	}
+
+	// 3. pi-crew smoke-test `.bak-*` junk in ~/.pi/agent/agents/. These are
+	//    leftover backups from pi-crew's own smoke tests (pattern:
+	//    `<name>.md.bak-<timestamp>-<hex>`). NEVER touch real `.md` agent files
+	//    (can't tell user-authored vs test-copied).
+	const agentsDir = path.join(userPiRoot(), "agents");
+	lines.push("pi-crew test junk in agents dir:");
+	const bakJunk: string[] = [];
+	if (fs.existsSync(agentsDir)) {
+		try {
+			for (const entry of fs.readdirSync(agentsDir)) {
+				// Only the pi-crew smoke-test backup pattern. Real agent files end in `.md`.
+				if (/^.*\.md\.bak-\d{17,}-[0-9a-f]+$/i.test(entry)) {
+					bakJunk.push(path.join(agentsDir, entry));
+				}
+			}
+		} catch { /* best-effort scan */ }
+	}
+	if (bakJunk.length === 0) {
+		lines.push("  - (no `*.md.bak-*` test backups found — nothing to do)");
+	} else {
+		for (const junk of bakJunk) {
+			if (!dryRun) {
+				try { fs.rmSync(junk, { force: true }); }
+				catch (e) { lines.push(`  - ERROR removing ${path.basename(junk)}: ${(e as Error).message}`); }
+			}
+		}
+		lines.push(`  - ${dryRun ? "would remove" : "removed"}: ${bakJunk.length} backup file(s) (pattern *.md.bak-<timestamp>-<hex>)`);
+	}
+
+	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 `team action=cleanup force=true` (project .crew/) + `pi uninstall npm:pi-crew`.",
+	);
+	return result(lines.join("\n"), { action: "cleanup", status: "ok", scope: "user" }, false);
+}
+
+/** Recursively compute a directory's size in bytes (best-effort). */
+function dirSize(dir: string): number {
+	let total = 0;
+	const stack = [dir];
+	while (stack.length > 0) {
+		const cur = stack.pop()!;
+		let entries: string[];
+		try { entries = fs.readdirSync(cur); }
+		catch { continue; }
+		for (const entry of entries) {
+			const full = path.join(cur, entry);
+			try {
+				const stat = fs.statSync(full);
+				if (stat.isDirectory()) stack.push(full);
+				else total += stat.size;
+			} catch { /* skip unreadable */ }
+		}
+	}
+	return total;
+}
+
+function formatBytes(n: number): string {
+	if (n < 1024) return `${n}B`;
+	if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)}KB`;
+	if (n < 1024 * 1024 * 1024) return `${(n / (1024 * 1024)).toFixed(1)}MB`;
+	return `${(n / (1024 * 1024 * 1024)).toFixed(1)}GB`;
+}
 
+/** 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/status.ts

@@ -12,6 +12,7 @@ import { computePhaseProgress } from "../../runtime/phase-progress.ts";
 import { formatDuration } from "../../ui/tool-render.ts";
 import { verifyTaskCompletion } from "../../runtime/completion-guard.ts";
 import { evaluateRunEffectiveness } from "../../runtime/effectiveness.ts";
+import { extractCommandTrace } from "../../runtime/command-trace.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { locateRunCwd } from "../team-tool.ts";
 import { result, type TeamContext } from "./context.ts";
@@ -88,7 +89,7 @@ export function handleStatus(params: TeamToolParamsValue, ctx: TeamContext): PiT
 		"Task graph:",
 		...formatTaskGraphLines(tasks),
 		"Tasks:",
-		...(tasks.length ? tasks.map((task) => `- ${task.id} [${task.status}] ${task.role} -> ${task.agent}${task.taskPacket ? ` scope=${task.taskPacket.scope}` : ""}${task.verification ? ` green=${task.verification.observedGreenLevel}/${task.verification.requiredGreenLevel}` : ""}${task.modelAttempts?.length ? ` attempts=${task.modelAttempts.length}` : ""}${task.modelRouting ? ` modelRouting=${task.modelRouting.requested ? `${task.modelRouting.requested}->` : ""}${task.modelRouting.resolved}${task.modelRouting.usedAttempt ? ` attempt=${task.modelRouting.usedAttempt + 1}` : ""}` : ""}${task.agentProgress?.activityState ? ` activityState=${task.agentProgress.activityState}` : ""}${attentionByTask.get(task.id)?.data?.reason ? ` attention=${String(attentionByTask.get(task.id)?.data?.reason)}` : ""}${task.jsonEvents !== undefined ? ` jsonEvents=${task.jsonEvents}` : ""}${task.usage ? ` usage=${JSON.stringify(task.usage)}` : ""}${task.resultArtifact ? ` result=${task.resultArtifact.path}` : ""}${task.transcriptArtifact ? ` transcript=${task.transcriptArtifact.path}` : ""}${task.worktree ? ` worktree=${task.worktree.path}` : ""}${task.error ? ` error=${task.error}` : ""}`) : ["- (none)"]),
+		...(tasks.length ? tasks.map((task) => `- ${task.id} [${task.status}] ${task.role} -> ${task.agent}${task.taskPacket ? ` scope=${task.taskPacket.scope}` : ""}${task.verification ? ` green=${task.verification.observedGreenLevel}/${task.verification.requiredGreenLevel}` : ""}${task.modelAttempts?.length ? ` attempts=${task.modelAttempts.length}` : ""}${task.modelRouting ? ` modelRouting=${task.modelRouting.requested ? `${task.modelRouting.requested}->` : ""}${task.modelRouting.resolved}${task.modelRouting.usedAttempt ? ` attempt=${task.modelRouting.usedAttempt + 1}` : ""}` : ""}${task.agentProgress?.activityState ? ` activityState=${task.agentProgress.activityState}` : ""}${(() => { const t = extractCommandTrace(task.agentProgress?.recentTools); return t.summary ? ` ${t.summary}` : ""; })()}${attentionByTask.get(task.id)?.data?.reason ? ` attention=${String(attentionByTask.get(task.id)?.data?.reason)}` : ""}${task.jsonEvents !== undefined ? ` jsonEvents=${task.jsonEvents}` : ""}${task.usage ? ` usage=${JSON.stringify(task.usage)}` : ""}${task.resultArtifact ? ` result=${task.resultArtifact.path}` : ""}${task.transcriptArtifact ? ` transcript=${task.transcriptArtifact.path}` : ""}${task.worktree ? ` worktree=${task.worktree.path}` : ""}${task.error ? ` error=${task.error}` : ""}`) : ["- (none)"]),
 		`Task counts: ${[...counts.entries()].map(([status, count]) => `${status}=${count}`).join(", ") || "none"}`,
 		"Effectiveness:",
 		`- observable=${effectiveness.observable}/${Math.max(1, effectiveness.completed)} completed tasks`,

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/command-trace.ts

@@ -0,0 +1,105 @@
+/**
+ * T10 — Verbatim command-trace extraction from tool-call history.
+ *
+ * Ported from pi-agent-flow's `generateCommandsFromHistory` technique (see
+ * `research-findings/pi-ecosystem-distillation.md` T10): workers routinely
+ * PARAPHRASE commands in their self-reports ("I ran the tests" instead of the
+ * exact `npm test -- --grep foo`). The orchestrator/user wants the VERBATIM
+ * command trace. pi-crew already records each executed tool in
+ * `CrewAgentProgress.recentTools` (capped at 25, args previewed at ≤240 chars),
+ * so the factual trace is available — this module distills it.
+ *
+ * Design notes:
+ *  - Reads only the recorded `{tool, args, endedAt}` tuples — never trusts any
+ *    LLM-emitted command string. This is the whole point: mechanical, factual.
+ *  - Recognizes bash/shell tools and extracts their `command` arg, sanitized to
+ *    a single line (newlines → ⏎) so a multi-line script shows as one trace row.
+ *  - Non-shell tools (write/edit/read) are counted but not inlined (their args
+ *    are file paths, not commands; the task result already lists changed files).
+ *  - Caps the returned command list to keep the status line / summary bounded.
+ */
+
+export interface ToolCallRecord {
+	tool: string;
+	args?: string;
+	endedAt?: string;
+}
+
+export interface CommandTrace {
+	/** Total number of recorded tool calls (all tool kinds). */
+	totalTools: number;
+	/** Count of recognized command-executing tools (bash/shell). */
+	commandTools: number;
+	/** Verbatim command strings (sanitized to one line), most-recent-last. */
+	commands: string[];
+	/** One-line summary suitable for a status/dashboard row, e.g. "cmd=8 (3 bash)". */
+	summary: string;
+}
+
+const COMMAND_TOOL_NAMES = new Set(["bash", "shell", "execute_bash", "run_command", "terminal"]);
+const MAX_COMMANDS = 12;
+const MAX_COMMAND_LEN = 160;
+
+/**
+ * Extract a verbatim command trace from recorded tool calls. Pure function —
+ * safe to call with any subset of recentTools. Returns an empty trace for
+ * empty/missing input.
+ */
+export function extractCommandTrace(recentTools: readonly ToolCallRecord[] | undefined | null): CommandTrace {
+	const tools = Array.isArray(recentTools) ? recentTools : [];
+	// Only count well-formed records (string tool name) — malformed entries
+	// are skipped entirely so a corrupt/transient record can't inflate totals.
+	const valid = tools.filter((call) => call && typeof call.tool === "string");
+	const totalTools = valid.length;
+	const commands: string[] = [];
+	let commandTools = 0;
+	for (const call of valid) {
+		const toolName = call.tool.toLowerCase();
+		if (!COMMAND_TOOL_NAMES.has(toolName)) continue;
+		commandTools += 1;
+		const cmd = extractCommandArg(call.args);
+		if (cmd) commands.push(sanitizeCommand(cmd));
+	}
+	const trimmed = commands.slice(-MAX_COMMANDS);
+	return {
+		totalTools,
+		commandTools,
+		commands: trimmed,
+		summary: formatSummary(totalTools, commandTools),
+	};
+}
+
+/** Pull the `command` field out of an args preview (JSON string or raw). */
+function extractCommandArg(args: string | undefined): string | undefined {
+	if (!args) return undefined;
+	const raw = args.trim();
+	if (!raw) return undefined;
+	// Args is a JSON-stringified object like {"command":"ls -la"} (previewArgs
+	// JSON.stringifies objects). Try to parse and read .command / .cmd.
+	if (raw.startsWith("{")) {
+		try {
+			const parsed = JSON.parse(raw) as Record<string, unknown>;
+			const cmd = parsed.command ?? parsed.cmd ?? parsed.script ?? parsed.input;
+			if (typeof cmd === "string" && cmd.trim()) return cmd;
+		} catch {
+			// Not valid JSON — fall through to treat raw as the command.
+		}
+	}
+	// Otherwise treat the whole preview as the command text.
+	return raw;
+}
+
+/** Sanitize a command to a single bounded line for compact display. */
+function sanitizeCommand(cmd: string): string {
+	const oneLine = cmd.replace(/\s*\r?\n\s*/g, " ⏎ ").trim();
+	if (oneLine.length <= MAX_COMMAND_LEN) return oneLine;
+	return `${oneLine.slice(0, MAX_COMMAND_LEN - 1)}…`;
+}
+
+function formatSummary(totalTools: number, commandTools: number): string {
+	if (totalTools === 0) return "";
+	// "cmd=8" always; append "(3 bash)" only when there's a mix worth showing.
+	if (commandTools === 0) return `cmd=${totalTools}`;
+	if (commandTools === totalTools) return `cmd=${totalTools}`;
+	return `cmd=${totalTools} (${commandTools} bash)`;
+}

package/src/runtime/pi-json-output.ts

@@ -14,6 +14,10 @@ export interface ParsedPiJsonOutput {
 	usage?: ParsedPiUsage;
 	/** Unified patches extracted from tool_result events (edit tool patch field) */
 	patches?: string[];
+	/** Model/provider error messages extracted from message_end events (e.g.
+	 * "429 ... overloaded"). Used to detect runs that exited 0 but produced
+	 * nothing because the model was rate-limited — see task-runner 429 fix. */
+	errorMessages?: string[];
 }
 
 function asRecord(value: unknown): Record<string, unknown> | undefined {
@@ -90,6 +94,7 @@ export function parsePiJsonOutput(stdout: string): ParsedPiJsonOutput {
 	let jsonEvents = 0;
 	const textEvents: string[] = [];
 	const patches: string[] = [];
+	const errorMessages: string[] = [];
 	let usage: ParsedPiUsage | undefined;
 	for (const line of stdout.split("\n")) {
 		const trimmed = line.trim();
@@ -104,6 +109,9 @@ export function parsePiJsonOutput(stdout: string): ParsedPiJsonOutput {
 		textEvents.push(...extractText(event));
 		// Extract unified patches from tool_result events
 		extractPatch(event, patches);
+		// Extract provider/model error messages from message_end events (429 fix).
+		const errMsg = extractErrorMessage(event);
+		if (errMsg) errorMessages.push(errMsg);
 		const eventUsage = extractUsage(event);
 		if (eventUsage) usage = mergeUsage(usage ?? {}, eventUsage);
 	}
@@ -113,9 +121,24 @@ export function parsePiJsonOutput(stdout: string): ParsedPiJsonOutput {
 		finalText: textEvents.length > 0 ? textEvents[textEvents.length - 1] : undefined,
 		usage,
 		patches: patches.length > 0 ? patches : undefined,
+		errorMessages: errorMessages.length > 0 ? errorMessages : undefined,
 	};
 }
 
+/**
+ * Pull the provider/model error message out of a `message_end` event. The shape
+ * is `{type:"message_end", message:{role:"assistant", content:[], errorMessage:"429 ...", stopReason:"error"}}`.
+ * Returns undefined for events without an errorMessage.
+ */
+function extractErrorMessage(event: unknown): string | undefined {
+	const obj = asRecord(event);
+	if (!obj) return undefined;
+	// message_end events carry the error on the nested message object.
+	const message = asRecord(obj.message) ?? obj;
+	const errorMessage = message.errorMessage;
+	return typeof errorMessage === "string" && errorMessage.trim() ? errorMessage.trim() : undefined;
+}
+
 /**
  * Extract unified patches from a tool_result event.
  * pi's edit tool now includes a `patch` field (standard unified diff format).

package/src/runtime/skill-instructions.ts

@@ -333,6 +333,13 @@ export function renderSkillInstructions(
 				? `Description: ${description}${confidenceNote}`
 				: undefined,
 			`Source: ${source}`,
+			// Path: pointer to the skill directory so the agent can deterministically
+			// `ls <Path>/references/` and `read` a co-located reference corpus.
+			// Without this, skills that defer to a local corpus (the Agent Skills
+			// spec "small instruction + large local reference" pattern, e.g.
+			// effective-html's `references/html-effectiveness/`) leave the agent
+			// guessing the skill dir. No behavior change for corpus-less skills.
+			`Path: ${path.dirname(loaded.path)}`,
 		]
 			.filter(Boolean)
 			.join("\n");

package/src/runtime/task-runner.ts

@@ -83,6 +83,7 @@ import {
 	progressEventSummary,
 	shouldFlushProgressEvent,
 } from "./task-runner/progress.ts";
+import { extractCommandTrace } from "./command-trace.ts";
 import {
 	checkpointTask,
 	persistSingleTaskUpdate,
@@ -729,6 +730,18 @@ export async function runTeamTask(
 						stderr: childResult.stderr,
 					}).message;
 				}
+				// 429/rate-limit fix (PI_CREW_TOOLING_429_NOTE.md): a worker can exit
+				// code 0 with NO hard error, but the transcript is full of
+				// `message_end` events with `errorMessage: "429 ... overloaded"` and
+				// empty content. The model never produced a tool call, so the worker
+				// "completed" without doing anything. Detect this: if no error was set
+				// above AND the parsed output carries a retryable model-failure message
+				// AND there is no real output text, surface it as an error so the
+				// model-fallback chain can retry on another model.
+				if (!error && parsedOutput) {
+					const rateLimitErr = detectRetryableModelFailureFromOutput(parsedOutput);
+					if (rateLimitErr) error = rateLimitErr;
+				}
 				persistHeartbeat(true);
 				persistChildProgress({ type: "attempt_finished" }, true);
 				const attempt: ModelAttemptSummary = {
@@ -1206,12 +1219,16 @@ export async function runTeamTask(
 
 		// Emit task completion hooks (100% reliable, fire-and-forget)
 		const hookType = task.status === "completed" ? "task_completed" : task.status === "failed" ? "task_failed" : "task_started";
+		// T10: attach the VERBATIM command trace (mechanically derived from
+		// recorded tool-call history, never from the worker's self-report) so
+		// event viewers + the orchestrator see exactly which commands ran.
+		const commandTrace = extractCommandTrace(task.agentProgress?.recentTools);
 		crewHooks.emit({
 			type: hookType,
 			timestamp: task.finishedAt ?? new Date().toISOString(),
 			runId: manifest.runId,
 			taskId: task.id,
-			data: { status: task.status, role: task.role, error: task.error, exitCode: task.exitCode, usage: task.usage },
+			data: { status: task.status, role: task.role, error: task.error, exitCode: task.exitCode, usage: task.usage, commandTrace },
 		});
 
 		const packetArtifact = writeArtifact(manifest.artifactsRoot, {
@@ -1332,3 +1349,36 @@ async function resolveTaskScopeModelsPatterns(cwd: string): Promise<string[]> {
 	if (!scopeModels) return [];
 	return readEnabledModelsPatterns(cwd);
 }
+
+/**
+ * 429/rate-limit detection (PI_CREW_TOOLING_429_NOTE.md).
+ *
+ * A worker can exit code 0 with no hard error, yet the transcript is full of
+ * `message_end` events carrying `errorMessage: "429 ... overloaded"` (or any
+ * retryable model-failure pattern) and empty content arrays. The model never
+ * produced a tool call, so the worker "completed" without doing anything.
+ *
+ * This helper inspects a ParsedPiJsonOutput and, if the run produced only
+ * retryable model-failure messages AND no real output text (no finalText, no
+ * text events, no patches), returns a surfaced error string so the
+ * model-fallback chain (isRetryableModelFailure) can retry on another model.
+ * Returns undefined when the run has real output (the 429s were recovered from)
+ * or when there are no retryable error messages.
+ */
+export function detectRetryableModelFailureFromOutput(parsed: ParsedPiJsonOutput): string | undefined {
+	const messages = parsed.errorMessages;
+	if (!messages || messages.length === 0) return undefined;
+	// Find the first retryable model-failure message (429 / rate-limit / overloaded / 5xx / ...).
+	const retryable = messages.find((m) => isRetryableModelFailure(m));
+	if (!retryable) return undefined;
+	// Did the run actually produce real output despite the transient errors?
+	// If finalText / textEvents / patches exist, the model recovered and we
+	// should NOT mark the run as failed — only flag it when the worker yielded
+	// nothing (the 429-only case from the bug report).
+	const hasRealOutput =
+		(parsed.finalText?.trim().length ?? 0) > 0 ||
+		parsed.textEvents.some((t) => t.trim().length > 0) ||
+		(parsed.patches?.length ?? 0) > 0;
+	if (hasRealOutput) return undefined;
+	return `Model returned only retryable errors and no output: ${retryable}`;
+}