pi-crew 0.11.1 → 0.11.2

package/src/extension/run-maintenance.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { DEFAULT_PATHS } from "../config/defaults.ts";
+import { getCrewEnv } from "../config/env-vars.ts";
 import { createCancellationToken } from "../runtime/process/cancellation-token.ts";
 import type { TeamRunManifest } from "../state/types.ts";
 import { logInternalError } from "../utils/internal-error.ts";
@@ -22,6 +23,95 @@ export interface PruneRunsOptions {
 	/** When true, compute the removal list WITHOUT deleting any state/artifacts,
 	 *  running worktree cleanup, or writing an audit. Non-destructive preview. */
 	dryRun?: boolean;
+	/** DP-01: never remove a finished run younger than this, even beyond
+	 *  top-keep. Evidence/incident runs must survive a session restart (the
+	 *  2026-09-21 battery lost a morning of evidence to the next session start).
+	 *  0 disables the floor. Defaults to the PI_CREW_AUTO_PRUNE_AGE_FLOOR_HOURS
+	 *  value (24h) for auto-prune callers; manual prune passes 0 explicitly. */
+	ageFloorMs?: number;
+}
+
+/**
+ * DP-01: resolve the auto-prune keep count from PI_CREW_AUTO_PRUNE_KEEP.
+ * Invalid/negative/non-finite values fall back to 10 (the historical hard-coded
+ * value) with a logged warning — never a crash and never an infinite keep.
+ */
+export function resolveAutoPruneKeep(env: (name: string) => string | undefined = getCrewEnv): number {
+	const raw = env("PI_CREW_AUTO_PRUNE_KEEP")?.trim();
+	if (raw === undefined || raw === "") return 10;
+	const parsed = Number.parseInt(raw, 10);
+	if (!Number.isFinite(parsed) || parsed < 0) {
+		logInternalError(
+			"prune.auto-keep-invalid",
+			new Error(`PI_CREW_AUTO_PRUNE_KEEP=${JSON.stringify(raw)} is not a non-negative integer; using 10`),
+		);
+		return 10;
+	}
+	return parsed;
+}
+
+/**
+ * DP-01: resolve the auto-prune age floor (ms) from
+ * PI_CREW_AUTO_PRUNE_AGE_FLOOR_HOURS (default 24h; 0 disables).
+ */
+export function resolveAutoPruneAgeFloorMs(env: (name: string) => string | undefined = getCrewEnv): number {
+	const raw = env("PI_CREW_AUTO_PRUNE_AGE_FLOOR_HOURS")?.trim();
+	if (raw === undefined || raw === "") return 24 * 60 * 60 * 1000;
+	const hours = Number.parseFloat(raw);
+	if (!Number.isFinite(hours) || hours < 0) {
+		logInternalError(
+			"prune.auto-age-floor-invalid",
+			new Error(`PI_CREW_AUTO_PRUNE_AGE_FLOOR_HOURS=${JSON.stringify(raw)} is not a non-negative number; using 24`),
+		);
+		return 24 * 60 * 60 * 1000;
+	}
+	return hours * 60 * 60 * 1000;
+}
+
+/** DP-01: rotate prune.jsonl when it exceeds this size (one generation kept). */
+export const PRUNE_AUDIT_MAX_BYTES = 512 * 1024;
+
+/**
+ * DP-01: size-based rotation for the prune audit log. Best-effort: a rotation
+ * failure must never break the prune path (the audit is observability, not
+ * correctness). One generation is enough — the audit is for recent forensics
+ * (the 2026-09-21 storm RCA read exactly the current window).
+ */
+function rotatePruneAuditIfNeeded(filePath: string): void {
+	try {
+		if (!fs.existsSync(filePath)) return;
+		if (fs.statSync(filePath).size < PRUNE_AUDIT_MAX_BYTES) return;
+		fs.renameSync(filePath, `${filePath}.1`);
+	} catch (error) {
+		logInternalError("prune.audit-rotate", error, `path=${filePath}`);
+	}
+}
+
+/**
+ * DP-01: record a pruned FAILED/BLOCKED run's reason in a durable index that
+ * survives run-dir pruning. Turn-run dirs are aggressively pruned (keep=10 at
+ * session start); without this, a failure reason becomes unrecoverable (live
+ * incident goal_20260921111305 — see docs/specs/DP-01.md). Best-effort.
+ */
+function appendPrunedFailureIndex(cwd: string, run: TeamRunManifest): void {
+	try {
+		const crewRoot = projectCrewRoot(cwd);
+		if (!fs.existsSync(crewRoot)) return;
+		const filePath = path.join(crewRoot, "state", "pruned-failures.jsonl");
+		fs.mkdirSync(path.dirname(filePath), { recursive: true });
+		const entry = {
+			runId: run.runId,
+			status: run.status,
+			summary: (run.summary ?? "").split("\n")[0]?.slice(0, 500),
+			goal: (run.goal ?? "").split("\n")[0]?.slice(0, 200),
+			team: run.team,
+			createdAt: run.createdAt,
+			prunedAt: new Date().toISOString(),
+		};
+		fs.appendFileSync(filePath, `${JSON.stringify(redactSecrets(entry))}\n`, "utf-8");
+	} catch (error) {
+		logInternalError("prune.failure-index-write", error, `runId=${run.runId}`);
+	}
 }
 
 /**
@@ -98,8 +188,19 @@ function isSafeToPrune(cwd: string, run: TeamRunManifest): boolean {
 
 function appendPruneAudit(cwd: string, payload: Record<string, unknown>): string | undefined {
 	try {
-		const filePath = path.join(projectCrewRoot(cwd), "audit", "prune.jsonl");
+		// RR-020 Fix 2: a no-op prune must NOT materialize the project crew
+		// root. `<crewRoot>/audit/` only exists because a real prune removed
+		// runs, and a real prune implies the crew root (+ state/runs) exists —
+		// so bail out instead of mkdir-ing a `<crewRoot>/audit/` tree on
+		// session start for a project that never ran a team.
+		const crewRoot = projectCrewRoot(cwd);
+		if (!fs.existsSync(crewRoot)) return undefined;
+		const filePath = path.join(crewRoot, "audit", "prune.jsonl");
 		fs.mkdirSync(path.dirname(filePath), { recursive: true });
+		// DP-01: rotate the audit log before it grows unbounded (it reached
+		// 720 KB / 1,436 entries with no cap). Keep the current file under
+		// PRUNE_AUDIT_MAX_BYTES; older entries rotate to .1 (one generation).
+		rotatePruneAuditIfNeeded(filePath);
 		fs.appendFileSync(filePath, `${JSON.stringify(redactSecrets({ ...payload, auditedAt: new Date().toISOString() }))}\n`, "utf-8");
 		return filePath;
 	} catch (error) {
@@ -115,7 +216,18 @@ export function pruneFinishedRuns(cwd: string, keep: number, options: PruneRunsO
 		.sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""));
 	const kept = finished.slice(0, keep).map((run) => run.runId);
 	const removed: string[] = [];
-	const toRemove = finished.slice(keep);
+	// DP-01: age floor — a finished run younger than the floor is NEVER removed
+	// by auto-prune, even beyond top-keep. Manual prune passes 0 (no floor).
+	const ageFloorMs = options.ageFloorMs ?? 0;
+	const floorCutoff = ageFloorMs > 0 ? Date.now() - ageFloorMs : 0;
+	const toRemove = finished.slice(keep).filter((run) => {
+		if (floorCutoff === 0) return true;
+		const ts = Date.parse(run.updatedAt ?? run.createdAt ?? "");
+		// Unparseable timestamps are treated as OLD (removable) to preserve
+		// pre-DP-01 behavior for malformed manifests.
+		if (!Number.isFinite(ts)) return true;
+		return ts < floorCutoff;
+	});
 	for (let i = 0; i < toRemove.length; i++) {
 		if (i % 5 === 0) token.heartbeat(`prune:${i}/${toRemove.length}`);
 		const run = toRemove[i];
@@ -158,6 +270,9 @@ export function pruneFinishedRuns(cwd: string, keep: number, options: PruneRunsO
 		}
 		fs.rmSync(run.stateRoot, { recursive: true, force: true });
 		fs.rmSync(run.artifactsRoot, { recursive: true, force: true });
+		// DP-01: preserve the reason of a pruned failed/blocked run in a durable
+		// index (the run dir that held it is gone now).
+		if (run.status === "failed" || run.status === "blocked") appendPrunedFailureIndex(cwd, run);
 		removed.push(run.runId);
 	}
 	// ST-6: Sweep stale .corrupt-* quarantine files to prevent unbounded growth.
@@ -165,6 +280,11 @@ export function pruneFinishedRuns(cwd: string, keep: number, options: PruneRunsO
 		sweepStaleCorruptFiles(path.join(projectCrewRoot(cwd), DEFAULT_PATHS.state.runsSubdir));
 	}
 
+	// RR-020 Fix 2 note: appendPruneAudit itself bails when the crew root does
+	// not exist, so a no-op prune on a fresh project writes nothing. When the
+	// crew root DOES exist, HEAD parity is preserved — a zero-candidate prune
+	// still records its `kept:[] removed:[]` audit line (cold-verify correction:
+	// the earlier `finished.length === 0` bail suppressed that line).
 	const auditPath = options.dryRun
 		? undefined
 		: appendPruneAudit(cwd, {
@@ -186,7 +306,7 @@ export function pruneFinishedRuns(cwd: string, keep: number, options: PruneRunsO
  * @param keep Number of most recent finished runs to retain
  * @returns kept and removed run IDs
  */
-export function pruneUserLevelRuns(keep: number): PruneRunsResult {
+export function pruneUserLevelRuns(keep: number, options: PruneRunsOptions = {}): PruneRunsResult {
 	const crewRoot = userCrewRoot();
 	const runsRoot = path.join(crewRoot, DEFAULT_PATHS.state.runsSubdir);
 	if (!fs.existsSync(runsRoot)) return { kept: [], removed: [] };
@@ -195,7 +315,12 @@ export function pruneUserLevelRuns(keep: number): PruneRunsResult {
 	const MAX_DIRS = 500;
 	const finished: Array<{
 		runId: string;
-		updatedAt: string;
+		updatedAt?: string;
+		createdAt?: string;
+		status?: string;
+		summary?: string;
+		goal?: string;
+		team?: string;
 		stateRoot: string;
 		artifactsRoot: string;
 	}> = [];
@@ -240,18 +365,43 @@ export function pruneUserLevelRuns(keep: number): PruneRunsResult {
 		finished.push({
 			runId: manifest.runId,
 			updatedAt: manifest.updatedAt,
+			createdAt: manifest.createdAt,
+			status: manifest.status,
+			summary: manifest.summary,
+			goal: manifest.goal,
+			team: manifest.team,
 			stateRoot: manifest.stateRoot,
 			artifactsRoot: manifest.artifactsRoot,
 		});
 	}
 
-	// Sort newest first, keep top N, remove the rest
+	// Sort newest first, keep top N, remove the rest.
 	finished.sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""));
 	const kept = finished.slice(0, keep).map((r) => r.runId);
 	const removed: string[] = [];
+	// DP-01: same age floor as the project-level prune (user-level runs are
+	// equally easy to lose — the 2026-09-21 incident evidence lived here too).
+	const ageFloorMs = options.ageFloorMs ?? 0;
+	const floorCutoff = ageFloorMs > 0 ? Date.now() - ageFloorMs : 0;
 	for (const run of finished.slice(keep)) {
+		if (floorCutoff > 0) {
+			const ts = Date.parse(run.updatedAt ?? run.createdAt ?? "");
+			if (Number.isFinite(ts) && ts >= floorCutoff) continue; // too young — protect
+		}
 		fs.rmSync(run.stateRoot, { recursive: true, force: true });
 		fs.rmSync(run.artifactsRoot, { recursive: true, force: true });
+		// DP-01: preserve a pruned failed/blocked run's reason (the user-level
+		// index lives under the user crew root).
+		if (run.status === "failed" || run.status === "blocked") {
+			appendPrunedFailureIndex(crewRoot, {
+				runId: run.runId,
+				status: run.status,
+				summary: run.summary,
+				goal: run.goal,
+				team: run.team,
+				createdAt: run.createdAt,
+			} as TeamRunManifest);
+		}
 		removed.push(run.runId);
 	}
 

package/src/extension/team-tool/dispatch/index.ts

@@ -10,8 +10,8 @@
  *   status  (16): status, list, get, events, artifacts, summary, graph, search,
  *                 health, worktrees, checkpoint, cache, explain, onboard, recommend, help
  *   control (7):  cancel, invalidate, respond, cleanup, prune, forget, doctor
- *   manage  (16): create, update, delete, init, config, validate, autonomy, settings,
- *                 workflow-create/get/list/save/delete, import, imports, export
+ *   manage  (17): create, update, delete, init, config, validate, autonomy, settings,
+ *                 workflow-create/get/list/save/delete, import, imports, export, compare
  *   automate(6):  schedule, scheduled, anchor, auto-summarize, auto_boomerang, api
  */
 import type { TeamDomain } from "../../../schema/team-tool-schema.ts";
@@ -80,6 +80,7 @@ const ACTION_TO_DOMAIN: Record<string, TeamDomain> = {
 	import: "manage",
 	imports: "manage",
 	export: "manage",
+	compare: "manage",
 
 	// automate domain (6)
 	schedule: "automate",

package/src/extension/team-tool/dispatch/manage.ts

@@ -3,7 +3,7 @@
  *
  * Actions: create, update, delete, init, config, validate, autonomy, settings,
  * workflow-create, workflow-get, workflow-list, workflow-save, workflow-delete,
- * import, imports, export.
+ * import, imports, export, compare.
  *
  * Inline cases (init, autonomy, config, validate) are moved verbatim from the
  * former handleTeamTool switch.
@@ -18,7 +18,7 @@ import { formatValidationReport, validateResources } from "../../validate-resour
 import { autonomousPatchFromConfig, configPatchFromConfig, formatAutonomyStatus } from "../config-patch.ts";
 import { configRecord, result, type TeamContext } from "../context.ts";
 import { handleSettings } from "../handle-settings.ts";
-import { handleExport, handleImport, handleImports } from "../lifecycle-actions.ts";
+import { handleCompare, handleExport, handleImport, handleImports } from "../lifecycle-actions.ts";
 import {
 	handleWorkflowCreate,
 	handleWorkflowDelete,
@@ -51,6 +51,7 @@ export const MANAGE_DOMAIN_ACTIONS = [
 	"import",
 	"imports",
 	"export",
+	"compare",
 ] as const;
 type ManageDomainAction = (typeof MANAGE_DOMAIN_ACTIONS)[number];
 
@@ -161,6 +162,8 @@ export async function handleManageDomain(params: TeamToolParamsValue, ctx: TeamC
 		}
 		case "export":
 			return handleExport(params, ctx);
+		case "compare":
+			return handleCompare(params, ctx);
 		case "import":
 			return handleImport(params, ctx);
 		case "imports":

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

@@ -23,6 +23,7 @@ import { appendEventAsync } from "../../state/event-log/event-log.ts";
 import { createRunPaths, saveRunManifestAsync } from "../../state/stores/state-store.ts";
 import type { GoalLoopState, GoalLoopStatus, TeamRunManifest } from "../../state/types.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
+import { projectCrewRoot } from "../../utils/paths.ts";
 import { result, type TeamContext } from "./context.ts";
 import { paramRequired } from "./param-error.ts";
 
@@ -200,7 +201,9 @@ async function handleStart(input: GoalSubActionInput): Promise<ReturnType<typeof
 				goalId,
 				objective,
 				maxTurns,
-				statePath: `${cwd}/.crew/state/goals/${goalId}.json`,
+				// RR-020 Fix 4: resolve the layout (`<crewRoot>/state/goals/...`) instead
+				// of hardcoding `.crew` — GoalStore writes to projectCrewRoot(cwd).
+				statePath: `${projectCrewRoot(cwd)}/state/goals/${goalId}.json`,
 			},
 		});
 

package/src/extension/team-tool/handle-settings.ts

@@ -1,5 +1,6 @@
 import { loadConfig, updateConfig } from "../../config/config.ts";
 import { suggestConfigKey } from "../../config/suggestions.ts";
+import { collectSensitiveConfigPaths } from "../../schema/sensitive-config-paths.ts";
 import { discoverPiThemes, formatThemesListing, setPiTheme } from "../../ui/theme-discovery.ts";
 import { configPatchFromConfig } from "../team-tool/config-patch.ts";
 import type { TeamContext } from "../team-tool/context.ts";
@@ -214,6 +215,12 @@ const KNOWN_KEYS = new Set([
 	"notifications.enabled",
 	"notifications.severityFilter",
 	"notifications.dedupWindowMs",
+	"notifications.quietHours",
+	"notifications.webhook",
+	"notifications.webhook.url",
+	"notifications.webhook.enabled",
+	"notifications.webhook.secret",
+	"notifications.webhook.allowLocalhost",
 	"notifications.batchWindowMs",
 	"notifications.quietHours",
 	"notifications.sinkRetentionDays",
@@ -459,10 +466,19 @@ export function handleSettings(params: { config?: Record<string, unknown> }, ctx
 			if (suggestion) note = `\n(did you mean '${suggestion}'?)`;
 			else note = "\n(unknown key — may not take effect)";
 		}
-		return result(`${key} = ${formatValue(value, key)}${note}`, {
+		// US-030 security review: a value whose dotted path is schema-marked
+		// sensitive (webhook.secret, otlp.headers, …) must not be echoed into
+		// the session transcript — any in-session agent can read tool output.
+		const sensitive = collectSensitiveConfigPaths().some((path) => key === path || key.startsWith(`${path}.`));
+		const rendered = sensitive
+			? value === undefined || value === null
+				? "<not set>"
+				: "***(redacted — sensitive)"
+			: formatValue(value, key);
+		return result(`${key} = ${rendered}${note}`, {
 			...OK,
 			key,
-			value,
+			value: sensitive ? undefined : value,
 		} as never);
 	}
 
@@ -516,6 +532,7 @@ export function handleSettings(params: { config?: Record<string, unknown> }, ctx
 			// Check if project config would sanitize this key
 			if (scope === "project") {
 				const sensitiveKeys = [
+					"notifications.webhook",
 					"executeWorkers",
 					"asyncByDefault",
 					"runtime.mode",

package/src/extension/team-tool/health-monitor.ts

@@ -9,6 +9,7 @@ import { hasStaleAsyncProcess, isActiveRunStatus, isLikelyOrphanedActiveRun } fr
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
 import { loadTasksWithRecovery } from "../../state/stores/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
+import { findRunStateDir } from "../../utils/paths.ts";
 import { listRuns } from "../run-index.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { result, type TeamContext } from "./context.ts";
@@ -115,7 +116,8 @@ export function detectStuckTasks(run: { runId: string; stateRoot: string }, now:
 
 /**
  * Scan a directory for "pi-crew-*" subdirs that contain
- * .crew/state/runs/ with at least one valid run manifest.
+ * `.crew/state/runs/` OR `.pi/teams/state/runs/` with at least one valid run
+ * manifest (both supported layouts — RR-020 Fix 3).
  * Read-only — does NOT mutate anything.
  * Pattern adapted from stale-reconciler.ts:reconcileOrphanedTempWorkspaces().
  */
@@ -128,12 +130,19 @@ export function scanZombieTempWorkspaces(tmpDir: string, now: number): ZombieWor
 		for (const entry of entries) {
 			if (!entry.isDirectory() || !entry.name.startsWith("pi-crew-")) continue;
 			const workspaceDir = path.join(tmpDir, entry.name);
-			const stateRunsDir = path.join(workspaceDir, ".crew", "state", "runs");
-			if (!fs.existsSync(stateRunsDir)) continue;
+			// RR-020 Fix 3: both layouts (`.crew` and `.pi/teams`) are recognised —
+			// checking only `.crew` made a `.pi/teams` workspace invisible as a
+			// zombie (and eligible for debris deletion).
+			const stateRunsDir = findRunStateDir(workspaceDir);
+			if (!stateRunsDir) continue;
 
 			let runCount = 0;
 			try {
-				for (const runDir of fs.readdirSync(stateRunsDir)) {
+				// Cold-verify F-2: Dirent.isDirectory() is FALSE for a symlink-to-dir,
+				// so a planted `runs/<runId>` symlink is skipped (no out-of-tree read).
+				for (const entry of fs.readdirSync(stateRunsDir, { withFileTypes: true })) {
+					if (!entry.isDirectory()) continue;
+					const runDir = entry.name;
 					const manifestPath = path.join(stateRunsDir, runDir, "manifest.json");
 					if (fs.existsSync(manifestPath)) {
 						try {
@@ -194,11 +203,16 @@ export function collectTempWorkspaceRuns(
 		const entries = fs.readdirSync(tmpDir, { withFileTypes: true });
 		for (const entry of entries) {
 			if (!entry.isDirectory() || !entry.name.startsWith("pi-crew-")) continue;
-			const stateRunsDir = path.join(tmpDir, entry.name, ".crew", "state", "runs");
-			if (!fs.existsSync(stateRunsDir)) continue;
+			// RR-020 Fix 3: both layouts (`.crew` and `.pi/teams`).
+			const stateRunsDir = findRunStateDir(path.join(tmpDir, entry.name));
+			if (!stateRunsDir) continue;
 
 			try {
-				for (const runDir of fs.readdirSync(stateRunsDir)) {
+				// Cold-verify F-2: symlinked `runs/<runId>` entries are not directories
+				// per Dirent (withFileTypes does not follow) — skipped.
+				for (const entry of fs.readdirSync(stateRunsDir, { withFileTypes: true })) {
+					if (!entry.isDirectory()) continue;
+					const runDir = entry.name;
 					const manifestPath = path.join(stateRunsDir, runDir, "manifest.json");
 					if (!fs.existsSync(manifestPath)) continue;
 					try {

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

@@ -13,6 +13,7 @@ import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
 import { sleep } from "../../utils/sleep.ts";
 import { cleanupRunWorktrees } from "../../worktree/cleanup.ts";
 import { listImportedRuns } from "../import-index.ts";
+import { runCompareBundle } from "../run-compare.ts";
 import { exportRunBundle } from "../run-export.ts";
 import { importRunBundle } from "../run-import.ts";
 import { pruneFinishedRuns } from "../run-maintenance.ts";
@@ -144,6 +145,49 @@ export async function handleExport(params: TeamToolParamsValue, ctx: TeamContext
 	);
 }
 
+// US-021 (2026-09-22): compare two runs (before/after a fix, two attempts at
+// the same goal). Pure diff logic lives in run-compare.ts; this handler owns
+// param validation, ownership security (mirrors handleExport) and the
+// no-partial-artifact guarantee (both runs load BEFORE anything is written).
+export function handleCompare(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+	const raw = params.runIds ?? [];
+	const runIds = Array.isArray(raw) ? raw.filter((id): id is string => typeof id === "string" && id !== "") : [];
+	if (runIds.length !== 2)
+		return result(
+			paramRequired("compare", "runIds", "{ action: 'compare', runIds: ['team_a', 'team_b'] }"),
+			{ action: "compare", status: "error" },
+			true,
+		);
+	const a = loadRunManifestById(ctx.cwd, runIds[0]);
+	if (!a) return result(`Run '${runIds[0]}' not found.${RUN_NOT_FOUND_HINT}`, { action: "compare", status: "error" }, true);
+	const b = loadRunManifestById(ctx.cwd, runIds[1]);
+	if (!b) return result(`Run '${runIds[1]}' not found.${RUN_NOT_FOUND_HINT}`, { action: "compare", status: "error" }, true);
+
+	// SECURITY: Ownership check — mirrors handleExport. A comparison reveals
+	// another session's task statuses, costs and event types; foreign-run
+	// comparison therefore requires confirm: true (explicit user intent).
+	for (const loaded of [a, b]) {
+		const foreignRun = typeof loaded.manifest.ownerSessionId === "string" && loaded.manifest.ownerSessionId !== ctx.sessionId;
+		if (foreignRun && !params.confirm)
+			return result(
+				`Run ${loaded.manifest.runId} belongs to another session. Use confirm: true to compare anyway.`,
+				{ action: "compare", status: "error", runId: loaded.manifest.runId },
+				true,
+			);
+	}
+
+	const { comparison, markdownPath } = runCompareBundle(a.manifest, a.tasks, b.manifest, b.tasks);
+	return result(
+		[
+			`Compared ${a.manifest.runId} vs ${b.manifest.runId}: ${comparison.identical ? "identical" : "different"}.`,
+			`Tasks: ${comparison.tasks.length} compared, ${comparison.tasksOnlyInA.length} only in a, ${comparison.tasksOnlyInB.length} only in b.`,
+			`Tokens Δ: ${comparison.usage.tokensDelta >= 0 ? "+" : ""}${comparison.usage.tokensDelta}, Cost Δ: ${comparison.usage.costDelta >= 0 ? "+" : ""}${comparison.usage.costDelta.toFixed(4)}`,
+			`Markdown: ${markdownPath}`,
+		].join("\n"),
+		{ action: "compare", status: "ok", runId: a.manifest.runId },
+	);
+}
+
 // Note: handlePrune has no ownership check — intentionally cross-session.
 // Prune is a maintenance-level operation that removes ALL finished runs
 // regardless of which session created them. Requires confirm: true.
@@ -425,7 +469,11 @@ function handleProjectCleanup(params: TeamToolParamsValue, ctx: TeamContext): Pi
 			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") {
+		// RR-020 A0-4 (round-4 sweep): `"/teams"` hardcoded the POSIX separator,
+		// so on Windows the `.pi\teams` layout never matched and cleanup REFUSED
+		// to remove it (fail-closed, but the feature was broken there).
+		// `path.sep + "teams"` is identical on POSIX and correct on Windows.
+		if (!resolved.endsWith(path.sep + ".crew") && !resolved.endsWith(path.sep + "teams") && path.basename(resolved) !== ".crew") {
 			lines.push(`  - ERROR: refused to remove ${resolved} (does not look like a .crew dir) — skipped`);
 		} else {
 			if (!dryRun) {

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

@@ -5,6 +5,7 @@ import { allWorkflows, discoverWorkflows } from "../../workflows/discover-workfl
 import { validateWorkflowForTeam } from "../../workflows/validate-workflow.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { result, type TeamContext } from "./context.ts";
+import { resolveRoutingHint } from "./routing-hint.ts";
 
 export function handlePlan(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
 	const teamName = params.team ?? "default";
@@ -21,6 +22,12 @@ export function handlePlan(params: TeamToolParamsValue, ctx: TeamContext): PiTea
 			true,
 		);
 	const goal = params.goal ?? params.task ?? "(not provided)";
+	// DP-04: small-goal routing hint (suggest-only by default; never overrides
+	// an explicit team/workflow choice). See routing-hint.ts for the rationale.
+	const routingHint = resolveRoutingHint({
+		goal,
+		explicitOverride: params.team !== undefined || params.workflow !== undefined,
+	});
 	// ROADMAP T2.2: single-agent composition mode (cliff hedge).
 	if (params.singleAgent) {
 		const composed = composeSingleAgentPrompt(workflow, goal);
@@ -46,5 +53,8 @@ export function handlePlan(params: TeamToolParamsValue, ctx: TeamContext): PiTea
 				`${index + 1}. ${step.id} [${step.role}]${step.dependsOn?.length ? ` after ${step.dependsOn.join(", ")}` : ""}`,
 		),
 	];
+	if (routingHint.suggested && routingHint.message) {
+		lines.push("", routingHint.message);
+	}
 	return result(lines.join("\n"), { action: "plan", status: "ok" });
 }

package/src/extension/team-tool/routing-hint.ts

@@ -0,0 +1,63 @@
+/**
+ * DP-04 (2026-09-22): small-goal routing hint.
+ *
+ * Measured: a trivial goal through the default team burns 7.6–9k tokens just on
+ * the 3 context-setup steps (assess → execute → verify). The engine ALREADY
+ * supports `singleAgent: true` (handlePlan → composeSingleAgentPrompt); nothing
+ * suggested it for small goals.
+ *
+ * This module decides the hint. It is deliberately PURE and explainable — no
+ * ML, no hidden state — so the routing decision can be asserted in tests and
+ * audited from the plan output. Default mode is "suggest" (visible nudge, the
+ * caller/agent still decides), NOT a silent switch: this project has been
+ * burned by silent routing changes before (the auto-boomerang aliasing trap),
+ * so the decision must be visible.
+ */
+
+export type SmallGoalRoutingMode = "off" | "suggest" | "auto";
+
+/** Goals at or below this many whitespace tokens are considered "small". */
+export const SMALL_GOAL_TOKEN_THRESHOLD = 40;
+
+export interface RoutingHintInput {
+	goal: string;
+	/** True when the caller supplied an explicit team and/or workflow override. */
+	explicitOverride: boolean;
+	/** Configured mode; defaults to "suggest". */
+	mode?: SmallGoalRoutingMode;
+}
+
+export interface RoutingHint {
+	/** Whether a cheaper single-agent composition is advised. */
+	suggested: boolean;
+	/** Machine-readable reason (empty when not suggested). */
+	reason?: string;
+	/** Human-readable, shown in the plan output. */
+	message?: string;
+	/** Rough token saving estimate for the plan text (informational). */
+	estimatedSavings?: string;
+}
+
+/** Cheap, deterministic token count (whitespace split) — no tokenizer dep. */
+export function goalTokenCount(goal: string): number {
+	const trimmed = goal.trim();
+	if (trimmed.length === 0) return 0;
+	return trimmed.split(/\s+/).length;
+}
+
+export function resolveRoutingHint(input: RoutingHintInput): RoutingHint {
+	const mode = input.mode ?? "suggest";
+	if (mode === "off") return { suggested: false };
+	// Never second-guess an explicit team/workflow choice.
+	if (input.explicitOverride) return { suggested: false };
+	const tokens = goalTokenCount(input.goal);
+	if (tokens === 0 || tokens > SMALL_GOAL_TOKEN_THRESHOLD) return { suggested: false };
+	return {
+		suggested: true,
+		reason: `goal is small (${tokens} tokens ≤ ${SMALL_GOAL_TOKEN_THRESHOLD})`,
+		message:
+			`Hint: this goal is small (${tokens} tokens). The default team runs 3 context-setup phases ` +
+			`(~8k tokens overhead) before real work — consider \`singleAgent: true\` (or a 2-step chain) to skip them.`,
+		estimatedSavings: "~5-6k tokens",
+	};
+}

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

@@ -2,6 +2,7 @@ import { loadConfig } from "../../config/config.ts";
 import { applyAttentionState, formatActivityAge, resolveCrewControlConfig } from "../../runtime/agent-control.ts";
 import { extractCommandTrace } from "../../runtime/command-trace.ts";
 import { readCrewAgents } from "../../runtime/crew-agent-records.ts";
+import { deadletterStatusLine } from "../../runtime/deadletter.ts";
 import { evaluateRunEffectiveness } from "../../runtime/effectiveness.ts";
 import { computePhaseProgress } from "../../runtime/phase-progress.ts";
 import { checkProcessLiveness, isActiveRunStatus } from "../../runtime/process-status.ts";
@@ -150,6 +151,7 @@ export function handleStatus(params: TeamToolParamsValue, ctx: TeamContext): PiT
 	}
 	const counts = new Map<string, number>();
 	for (const task of tasks) counts.set(task.status, (counts.get(task.status) ?? 0) + 1);
+	const deadletterLine = deadletterStatusLine(manifest);
 	const phaseProgress = computePhaseProgress(tasks);
 	// PERF (2026-08-24): intentionally NOT passing `limit` here — readEventsCursor's
 	// limit is a HEAD cap (oldest-first slice for streaming pagination), not a tail
@@ -267,6 +269,8 @@ export function handleStatus(params: TeamToolParamsValue, ctx: TeamContext): PiT
 				)
 			: ["- (none)"]),
 		`Task counts: ${[...counts.entries()].map(([status, count]) => `${status}=${count}`).join(", ") || "none"}`,
+		// US-003 AC-3: surface exhausted-retry failures — only when entries exist.
+		...(deadletterLine ? [deadletterLine] : []),
 		"Effectiveness:",
 		`- observable=${effectiveness.observable}/${Math.max(1, effectiveness.completed)} completed tasks`,
 		`- workerExecution=${effectiveness.workerExecution} guard=${effectiveness.guardMode} severity=${effectiveness.severity}`,