pi-crew 0.7.5 → 0.7.6

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

@@ -24,6 +24,7 @@ import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { locateRunCwd } from "../team-tool.ts";
 import { configRecord, result, type TeamContext } from "./context.ts";
+import { RUN_NOT_FOUND_HINT } from "./run-not-found.ts";
 
 export function globMatch(value: string, pattern: string): boolean {
 	// Prevent ReDoS: reject excessively long patterns
@@ -91,9 +92,9 @@ export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext):
 	}
 	if (!params.runId) return result("API requires runId.", { action: "api", status: "error" }, true);
 	const runCwd = locateRunCwd(params.runId, ctx.cwd);
-	if (!runCwd) return result(`Run '${params.runId}' not found.`, { action: "api", status: "error" }, true);
+	if (!runCwd) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "api", status: "error" }, true);
 	const loaded = loadRunManifestById(runCwd, params.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
-	if (!loaded) return result(`Run '${params.runId}' not found.`, { action: "api", status: "error" }, true);
+	if (!loaded) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "api", status: "error" }, true);
 	if (operation === "read-manifest") {
 		return result(JSON.stringify(loaded.manifest, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
 	}

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

@@ -12,6 +12,7 @@ import { executeHook, appendHookEvent } from "../../hooks/registry.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { locateRunCwd } from "../team-tool.ts";
 import { result, type TeamContext } from "./context.ts";
+import { RUN_NOT_FOUND_HINT } from "./run-not-found.ts";
 import { enforceDestructiveIntent, intentFromConfig } from "./intent-policy.ts";
 import { invalidateSnapshot, type CacheControlDeps } from "./cache-control.ts";
 
@@ -80,9 +81,9 @@ function cancelReasonFromParams(params: TeamToolParamsValue): CancellationReason
 export async function handleRetry(params: TeamToolParamsValue, ctx: TeamContext, deps?: CacheControlDeps): Promise<PiTeamsToolResult> {
 	if (!params.runId) return result("Retry requires runId.", { action: "retry", status: "error" }, true);
 	const runCwd = locateRunCwd(params.runId, ctx.cwd);
-	if (!runCwd) return result(`Run '${params.runId}' not found.`, { action: "retry", status: "error" }, true);
+	if (!runCwd) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "retry", status: "error" }, true);
 	const loaded = loadRunManifestById(runCwd, params.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
-	if (!loaded) return result(`Run '${params.runId}' not found.`, { action: "retry", status: "error" }, true);
+	if (!loaded) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "retry", status: "error" }, true);
 
 	// Pre-lock ownership check: reject foreign-owned runs unless force is set
 	const foreignRun = typeof loaded.manifest.ownerSessionId === "string" && loaded.manifest.ownerSessionId !== ctx.sessionId;
@@ -145,9 +146,9 @@ export async function handleCancel(params: TeamToolParamsValue, ctx: TeamContext
 	if (intentError) return intentError;
 	if (!params.runId) return result("Cancel requires runId.", { action: "cancel", status: "error" }, true);
 	const runCwd = locateRunCwd(params.runId, ctx.cwd);
-	if (!runCwd) return result(`Run '${params.runId}' not found.`, { action: "cancel", status: "error" }, true);
+	if (!runCwd) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "cancel", status: "error" }, true);
 	const loaded = loadRunManifestById(runCwd, params.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
-	if (!loaded) return result(`Run '${params.runId}' not found.`, { action: "cancel", status: "error" }, true);
+	if (!loaded) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "cancel", status: "error" }, true);
 
 	// Pre-lock ownership check: reject foreign-owned runs unless force is set
 	const preCheck = abortOwned(loaded.manifest.runId, undefined, ctx, params.force);

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

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { RUN_NOT_FOUND_HINT } from "./run-not-found.ts";
 import * as path from "node:path";
 import { loadRunManifestById } from "../../state/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
@@ -211,7 +212,7 @@ export function handleExplain(params: {
 
   const loaded = loadRunManifestById(cwd, params.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
   if (!loaded) {
-    return result(`Run '${params.runId}' not found.`, { action: "explain", status: "error" }, true);
+    return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "explain", status: "error" }, true);
   }
 
   const { manifest, tasks } = loaded;

package/src/extension/team-tool/failure-patterns.ts

@@ -0,0 +1,124 @@
+/**
+ * failure-patterns.ts — Group failed tasks by error similarity (Round 17 BS-4).
+ *
+ * Before this, a run with 8 failed tasks surfaced 8 separate raw error
+ * strings. The user had to mentally group them ("5 of these say 'model
+ * routing fallback failed'"). This module detects common failure patterns
+ * so `summary` can say "5 of 8 failures share root cause: X".
+ *
+ * Grouping strategy (cheap, deterministic, no ML):
+ *   1. Normalize: lowercase, collapse whitespace, strip task ids / run ids /
+ *      absolute paths / numbers → a canonical "signature".
+ *   2. Bucket by signature. Buckets with >1 member are "common patterns".
+ *   3. Sort by frequency desc.
+ *
+ * Conservative: only buckets with >=2 members count as a pattern (a single
+ * failure is just itself). Returns [] when there are no repeated signatures.
+ */
+
+export interface FailurePattern {
+	/** Canonical error signature used for grouping. */
+	signature: string;
+	/** A representative original error (the shortest variant) for display. */
+	representative: string;
+	/** Task ids that hit this pattern. */
+	taskIds: string[];
+	/** Count of failures in this bucket (== taskIds.length). */
+	count: number;
+}
+
+export interface FailurePatternInput {
+	id: string;
+	status: string;
+	error?: string;
+}
+
+/**
+ * Normalize an error string into a grouping signature.
+ * Exported for unit testing.
+ */
+export function normalizeErrorSignature(error: string | undefined): string {
+	if (!error) return "(no error detail)";
+	let s = error.toLowerCase();
+	// Strip run ids (team_YYYYMMDDHHMMSS_xxxxxxxxxxxxxxxx)
+	s = s.replace(/team_\d{8,}_[a-z0-9]{12,}/g, "<run>");
+	// Strip task ids (01_explore, adaptive-03-executor, etc.)
+	s = s.replace(/\b(adaptive-)?\d{2,}[a-z0-9_-]+/g, "<task>");
+	// Strip absolute paths
+	s = s.replace(/\/(?:home|users|tmp|var|opt|root)[^\s'"]*/g, "<path>");
+	// Strip numbers (line numbers, counts, pids, ms durations)
+	s = s.replace(/\b\d+\b/g, "N");
+	// Collapse whitespace
+	s = s.replace(/\s+/g, " ").trim();
+	return s || "(no error detail)";
+}
+
+/**
+ * Group failed tasks by error-pattern similarity. Only groups with >=2
+ * members are returned (singletons are not "patterns"). Sorted by count desc.
+ *
+ * @param tasks  the run's tasks (any with status 'failed'/'cancelled' are
+ *               considered failures for aggregation purposes).
+ */
+export function aggregateFailurePatterns(tasks: FailurePatternInput[]): FailurePattern[] {
+	const failed = tasks.filter(
+		(t) => t.status === "failed" || t.status === "cancelled",
+	);
+	if (failed.length === 0) return [];
+	const buckets = new Map<string, FailurePattern>();
+	for (const t of failed) {
+		const signature = normalizeErrorSignature(t.error);
+		const existing = buckets.get(signature);
+		if (existing) {
+			existing.taskIds.push(t.id);
+			existing.count += 1;
+			// Keep the shortest non-empty variant as representative (most readable).
+			if (t.error && (!existing.representative || t.error.length < existing.representative.length)) {
+				existing.representative = t.error;
+			}
+		} else {
+			buckets.set(signature, {
+				signature,
+				representative: t.error ?? "(no error detail)",
+				taskIds: [t.id],
+				count: 1,
+			});
+		}
+	}
+	// Only patterns with >=2 members (repeated root causes).
+	return [...buckets.values()]
+		.filter((b) => b.count >= 2)
+		.sort((a, b) => b.count - a.count);
+}
+
+/**
+ * Render failure patterns as human-readable lines for the `summary` action.
+ * Returns [] when there are no repeated patterns (so the caller can omit the
+ * section entirely).
+ *
+ * Example output:
+ *   Common failure patterns (3 of 5 failures share 2 root causes):
+ *   - [×3] model routing fallback failed: all 2 candidates exhausted
+ *       tasks: 02_exec, 03_exec, 04_exec
+ *   - [×2] EPERM: operation not permitted, rename
+ *       tasks: 05_exec, 06_exec
+ */
+export function formatFailurePatterns(tasks: FailurePatternInput[]): string[] {
+	const patterns = aggregateFailurePatterns(tasks);
+	if (patterns.length === 0) return [];
+	const failedCount = tasks.filter(
+		(t) => t.status === "failed" || t.status === "cancelled",
+	).length;
+	const groupedCount = patterns.reduce((sum, p) => sum + p.count, 0);
+	const lines = [
+		`Common failure patterns (${groupedCount} of ${failedCount} failures share ${patterns.length} root cause${patterns.length === 1 ? "" : "s"}):`,
+	];
+	for (const p of patterns) {
+		const rep = p.representative.length > 100 ? `${p.representative.slice(0, 99)}…` : p.representative;
+		lines.push(`- [×${p.count}] ${rep}`);
+		const shown = p.taskIds.slice(0, 6);
+		const more = p.taskIds.length > 6 ? `, +${p.taskIds.length - 6} more` : "";
+		lines.push(`    tasks: ${shown.join(", ")}${more}`);
+	}
+	return lines;
+}

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

@@ -5,13 +5,15 @@ import { aggregateUsage, formatUsage, formatCostReport } from "../../state/usage
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { locateRunCwd } from "../team-tool.ts";
 import { result, type TeamContext } from "./context.ts";
+import { RUN_NOT_FOUND_HINT } from "./run-not-found.ts";
+import { formatFailurePatterns } from "./failure-patterns.ts";
 
 export function handleEvents(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
 	if (!params.runId) return result("Events requires runId.", { action: "events", status: "error" }, true);
 	const runCwd = locateRunCwd(params.runId, ctx.cwd);
-	if (!runCwd) return result(`Run '${params.runId}' not found.`, { action: "events", status: "error" }, true);
+	if (!runCwd) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "events", status: "error" }, true);
 	const loaded = loadRunManifestById(runCwd, params.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
-	if (!loaded) return result(`Run '${params.runId}' not found.`, { action: "events", status: "error" }, true);
+	if (!loaded) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "events", status: "error" }, true);
 	const events = readEvents(loaded.manifest.eventsPath);
 	const lines = [`Events for ${loaded.manifest.runId}:`, ...(events.length ? events.map((event) => `${event.time} ${event.type}${event.taskId ? ` ${event.taskId}` : ""}${event.message ? `: ${event.message}` : ""}${event.data ? ` ${JSON.stringify(event.data)}` : ""}`) : ["(none)"])];
 	return result(lines.join("\n"), { action: "events", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
@@ -20,9 +22,9 @@ export function handleEvents(params: TeamToolParamsValue, ctx: TeamContext): PiT
 export function handleArtifacts(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
 	if (!params.runId) return result("Artifacts requires runId.", { action: "artifacts", status: "error" }, true);
 	const runCwd = locateRunCwd(params.runId, ctx.cwd);
-	if (!runCwd) return result(`Run '${params.runId}' not found.`, { action: "artifacts", status: "error" }, true);
+	if (!runCwd) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "artifacts", status: "error" }, true);
 	const loaded = loadRunManifestById(runCwd, params.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
-	if (!loaded) return result(`Run '${params.runId}' not found.`, { action: "artifacts", status: "error" }, true);
+	if (!loaded) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "artifacts", status: "error" }, true);
 	const lines = [`Artifacts for ${loaded.manifest.runId}:`, ...(loaded.manifest.artifacts.length ? loaded.manifest.artifacts.map((artifact) => `- ${artifact.kind}: ${artifact.path}${artifact.sizeBytes !== undefined ? ` (${artifact.sizeBytes} bytes)` : ""}${artifact.contentHash ? ` sha256=${artifact.contentHash.slice(0, 12)}` : ""}`) : ["- (none)"])];
 	return result(lines.join("\n"), { action: "artifacts", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
 }
@@ -30,10 +32,11 @@ export function handleArtifacts(params: TeamToolParamsValue, ctx: TeamContext):
 export function handleSummary(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
 	if (!params.runId) return result("Summary requires runId.", { action: "summary", status: "error" }, true);
 	const runCwd = locateRunCwd(params.runId, ctx.cwd);
-	if (!runCwd) return result(`Run '${params.runId}' not found.`, { action: "summary", status: "error" }, true);
+	if (!runCwd) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "summary", status: "error" }, true);
 	const loaded = loadRunManifestById(runCwd, params.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
-	if (!loaded) return result(`Run '${params.runId}' not found.`, { action: "summary", status: "error" }, true);
+	if (!loaded) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "summary", status: "error" }, true);
 	const usage = aggregateUsage(loaded.tasks);
+	const failurePatternLines = formatFailurePatterns(loaded.tasks);
 	const lines = [
 		`Summary for ${loaded.manifest.runId}`,
 		`Status: ${loaded.manifest.status}`,
@@ -43,6 +46,7 @@ export function handleSummary(params: TeamToolParamsValue, ctx: TeamContext): Pi
 		`Usage: ${formatUsage(usage)}`,
 		"",
 		formatCostReport(loaded.tasks),
+		...(failurePatternLines.length > 0 ? ["", ...failurePatternLines] : []),
 		"",
 		"Tasks:",
 		...loaded.tasks.map((task) => `- ${task.id}: ${task.status} (${task.role} -> ${task.agent})${task.error ? ` - ${task.error}` : ""}`),

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

@@ -9,6 +9,7 @@ import { importRunBundle } from "../run-import.ts";
 import { pruneFinishedRuns } from "../run-maintenance.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { configRecord, result, type TeamContext } from "./context.ts";
+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";
@@ -18,7 +19,7 @@ import * as path from "node:path";
 export function handleWorktrees(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
 	if (!params.runId) return result("Worktrees requires runId.", { action: "worktrees", 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.`, { action: "worktrees", status: "error" }, true);
+	if (!loaded) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "worktrees", status: "error" }, true);
 	const withWorktrees = loaded.tasks.filter((task) => task.worktree);
 	const lines = [`Worktrees for ${loaded.manifest.runId}:`, ...(withWorktrees.length ? withWorktrees.map((task) => `- ${task.id}: ${task.worktree!.path} branch=${task.worktree!.branch} reused=${task.worktree!.reused ? "true" : "false"}`) : ["- (none)"])];
 	return result(lines.join("\n"), { action: "worktrees", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
@@ -47,7 +48,7 @@ export function handleImport(params: TeamToolParamsValue, ctx: TeamContext): PiT
 export async function handleExport(params: TeamToolParamsValue, ctx: TeamContext): Promise<PiTeamsToolResult> {
 	if (!params.runId) return result("Export requires runId.", { action: "export", 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.`, { action: "export", status: "error" }, true);
+	if (!loaded) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "export", status: "error" }, true);
 
 	// SECURITY: Ownership check — only the owner session may export a run.
 	// Foreign-run export requires confirm: true (explicit user intent).
@@ -96,7 +97,7 @@ export async function handleForget(params: TeamToolParamsValue, ctx: TeamContext
 	if (!params.runId) return result("Forget requires runId.", { action: "forget", status: "error" }, true);
 	if (!params.confirm) return result("forget requires confirm: true.", { action: "forget", 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.`, { action: "forget", status: "error" }, true);
+	if (!loaded) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "forget", status: "error" }, true);
 
 	// Ownership check — prevent cross-session deletion unless force is set
 	const foreignRun = typeof loaded.manifest.ownerSessionId === "string" && loaded.manifest.ownerSessionId !== ctx.sessionId;
@@ -126,7 +127,7 @@ export async function handleCleanup(params: TeamToolParamsValue, ctx: TeamContex
 	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.`, { action: "cleanup", status: "error" }, true);
+	if (!loaded) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "cleanup", status: "error" }, true);
 
 	// Ownership check — prevent cross-session worktree cleanup unless force is set
 	const foreignRun = typeof loaded.manifest.ownerSessionId === "string" && loaded.manifest.ownerSessionId !== ctx.sessionId;

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

@@ -8,6 +8,7 @@ import { logInternalError } from "../../utils/internal-error.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { locateRunCwd } from "../team-tool.ts";
 import { result, type TeamContext } from "./context.ts";
+import { RUN_NOT_FOUND_HINT } from "./run-not-found.ts";
 
 /**
  * Handle `respond` action: send a message to a waiting (interactive) task.
@@ -19,13 +20,13 @@ export function handleRespond(params: TeamToolParamsValue, ctx: TeamContext): Pi
 	if (!params.message && !params.taskId) return result("Respond requires taskId and/or message.", { action: "respond", status: "error" }, true);
 
 	const runCwd = locateRunCwd(params.runId, ctx.cwd);
-	if (!runCwd) return result(`Run '${params.runId}' not found.`, { action: "respond", status: "error" }, true);
+	if (!runCwd) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "respond", status: "error" }, true);
 	const loaded = loadRunManifestById(runCwd, params.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
-	if (!loaded) return result(`Run '${params.runId}' not found.`, { action: "respond", status: "error" }, true);
+	if (!loaded) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "respond", status: "error" }, true);
 
 	return withRunLockSync(loaded.manifest, () => {
 		const fresh = loadRunManifestById(loaded.manifest.cwd, params.runId!); // NOTE: inside withRunLockSync - consistent read
-		if (!fresh) return result(`Run '${params.runId}' not found.`, { action: "respond", status: "error" }, true);
+		if (!fresh) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "respond", status: "error" }, true);
 		const foreignRun = typeof fresh.manifest.ownerSessionId === "string" && fresh.manifest.ownerSessionId !== ctx.sessionId;
 		if (foreignRun && !params.force) return result(`Run ${fresh.manifest.runId} belongs to another session. Use force: true to override.`, { action: "respond", status: "error", runId: fresh.manifest.runId }, true);
 

package/src/extension/team-tool/run-not-found.ts

@@ -0,0 +1,54 @@
+/**
+ * run-not-found.ts — Centralized "Run not found" error helper (DX: F2).
+ *
+ * Round 16 DX audit found that a stale/typo'd runId hits a blank
+ * "Run '<id>' not found." wall in 8+ handlers (status, resume, steer, export,
+ * forget, cleanup, invalidate, worktrees, events, artifacts). The run IDs are
+ * long (`team_20260615173318_b9c8fe49a74e0760`), so typos/truncation are
+ * near-certain for new users — yet `team list` (which shows recent runs) is
+ * never suggested.
+ *
+ * This module centralizes the message + recovery hint so every handler stays
+ * consistent and the hint never drifts.
+ */
+
+import { result, type TeamContext } from "./context.ts";
+import type { TeamToolDetails } from "../team-tool-types.ts";
+
+/** Recovery hint appended to every "Run not found" message. */
+export const RUN_NOT_FOUND_HINT =
+	"\n\nTip: run action='list' to see recent runs and their IDs.";
+
+/**
+ * Build the standard "Run not found" error result with a recovery hint.
+ *
+ * @param runId  the (missing/typo'd) run id the caller passed
+ * @param action the action that was attempted (for the details.action field)
+ */
+export function runNotFound(runId: string, action: string): ReturnType<typeof result> {
+	return result(
+		`Run '${runId}' not found.${RUN_NOT_FOUND_HINT}`,
+		{ action, status: "error" } satisfies TeamToolDetails,
+		true,
+	);
+}
+
+/**
+ * Helper: resolve a runId to its cwd, returning a runNotFound() result when
+ * missing. Reduces the boilerplate `locateRunCwd → if (!runCwd) return ...`
+ * duplicated across handlers.
+ */
+export function resolveRunOrNotFound(
+	runId: string,
+	action: string,
+	cwd: string,
+	locate: (runId: string, cwd: string) => string | undefined,
+): { kind: "found"; runCwd: string } | { kind: "notfound"; result: ReturnType<typeof result> } {
+	const runCwd = locate(runId, cwd);
+	if (!runCwd) return { kind: "notfound", result: runNotFound(runId, action) };
+	return { kind: "found", runCwd };
+}
+
+// Re-export TeamContext so callers importing this helper don't need a second
+// import line — keeps the diff in each handler to a single import swap.
+export type { TeamContext };

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

@@ -184,13 +184,17 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 		// connecting PipelineRunner to the actual team execution system
 		const stageInfo = pipelineWorkflow.stages.map((s) => `- ${s.name} (${s.team})`).join("\n");
 		return result([
-			`Pipeline workflow: ${workflow.name}`,
+			`Pipeline workflow '${workflow.name}' is not yet wired into the team execution system.`,
 			`Goal: ${goal}`,
-			`Stages (${pipelineWorkflow.stages.length}):`,
+			`Defined stages (${pipelineWorkflow.stages.length}):`,
 			stageInfo,
 			"",
-			"Pipeline execution is available via the PipelineRunner API.",
-			"Full CLI integration requires connecting to the team execution system.",
+			"To actually run work right now, use a supported workflow instead:",
+			"  - action='run' workflow='default'  (explore → plan → execute → verify)",
+			"  - action='run' workflow='implementation'  (adaptive, parallel specialists)",
+			"  - action='run' workflow='research'  (explore → analyze → write)",
+			"",
+			"Run action='list' resource='workflow' to see all available workflows.",
 		].join("\n"), { action: "run", status: "ok" }, false);
 	}
 
@@ -219,6 +223,24 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 	registerActiveRun(updatedManifest);
 
 	const loadedConfig = loadConfig(resolvedCtx.cwd);
+	// DX (Round 16 F4): surface config errors/warnings instead of silently
+	// proceeding with defaults. Non-blocking: emit a config.warning event so
+	// it shows in the run timeline and status, and log it. A malformed config
+	// (bad JSON / wrong types) should not be a silent no-op — doctor/config
+	// actions already surface these; run should too.
+	const configIssues = [
+		...(loadedConfig.error ? [`Config error: ${loadedConfig.error}`] : []),
+		...(loadedConfig.warnings ?? []),
+	];
+	if (configIssues.length > 0) {
+		void appendEventAsync(updatedManifest.eventsPath, {
+			type: "config.warning",
+			runId: updatedManifest.runId,
+			message: `Loaded config from ${loadedConfig.path || "(defaults)"} with ${configIssues.length} issue(s): ${configIssues.join("; ")}`,
+			data: { error: loadedConfig.error, warnings: loadedConfig.warnings, path: loadedConfig.path },
+		}).catch((error) => logInternalError("team-tool.run.configWarning", error, `runId=${updatedManifest.runId}`));
+		logInternalError("team-tool.run.configWarning", new Error(`config issues: ${configIssues.join("; ")}`), `runId=${updatedManifest.runId} path=${loadedConfig.path ?? "(defaults)"}`);
+	}
 	const executedConfig = effectiveRunConfig(loadedConfig.config, params.config);
 	const runtime = await resolveCrewRuntime(executedConfig);
 	const runtimeResolution = runtimeResolutionState(runtime);

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

@@ -3,24 +3,31 @@ import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
 import { appendEvent, readEvents } from "../../state/event-log.ts";
 import { readDeliveryState, readMailbox } from "../../state/mailbox.ts";
 import { loadRunManifestById, updateRunStatus, saveRunTasks } from "../../state/state-store.ts";
-import { aggregateUsage, formatUsage } from "../../state/usage.ts";
+import { aggregateUsage, formatUsage, formatCost } from "../../state/usage.ts";
 import { applyAttentionState, formatActivityAge, resolveCrewControlConfig } from "../../runtime/agent-control.ts";
 import { readCrewAgents } from "../../runtime/crew-agent-records.ts";
 import { checkProcessLiveness, isActiveRunStatus } from "../../runtime/process-status.ts";
 import { formatTaskGraphLines, waitingReason } from "../../runtime/task-display.ts";
+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 type { PiTeamsToolResult } from "../tool-result.ts";
 import { locateRunCwd } from "../team-tool.ts";
 import { result, type TeamContext } from "./context.ts";
+import { RUN_NOT_FOUND_HINT } from "./run-not-found.ts";
 
 export function handleStatus(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
 	if (!params.runId) return result("Status requires runId.", { action: "status", status: "error" }, true);
 	const runCwd = locateRunCwd(params.runId, ctx.cwd);
-	if (!runCwd) return result(`Run '${params.runId}' not found.`, { action: "status", status: "error" }, true);
+	if (!runCwd) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "status", status: "error" }, true);
 	const loaded = loadRunManifestById(runCwd, params.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
-	if (!loaded) return result(`Run '${params.runId}' not found.`, { action: "status", status: "error" }, true);
+	if (!loaded) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "status", status: "error" }, true);
 	let { manifest, tasks } = loaded;
+	// DX (Round 16 F3): compact status mode. Default = full (backward compatible).
+	// details=false gives a tight summary (status, goal, counts, failed/attention
+	// errors) for quick checks without 40 lines of dense key=value noise.
+	const fullDetails = params.details !== false;
 	let asyncLivenessLine: string | undefined;
 	if (manifest.async) {
 		const asyncState = manifest.async;
@@ -35,6 +42,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 phaseProgress = computePhaseProgress(tasks);
 	const allEvents = readEvents(manifest.eventsPath);
 	const events = allEvents.slice(-8);
 	const attentionByTask = new Map(allEvents.filter((event) => event.type === "task.attention" && event.taskId).map((event) => [event.taskId!, event]));
@@ -62,12 +70,13 @@ export function handleStatus(params: TeamToolParamsValue, ctx: TeamContext): PiT
 	const activeAgents = crewAgents.filter((agent) => agent.status === "running");
 	const completedAgents = crewAgents.filter((agent) => agent.status !== "running");
 	const waitingTasks = tasks.filter((task) => task.status === "queued" || task.status === "waiting");
-	const agentLine = (agent: typeof crewAgents[number]): string => `- ${agent.id} [${agent.status}] ${agent.role} -> ${agent.agent} runtime=${agent.runtime}${agent.model ? ` model=${agent.model}` : ""}${agent.usage ? ` usage=${formatUsage(agent.usage)}` : ""}${agent.progress?.activityState ? ` activityState=${agent.progress.activityState}` : ""}${formatActivityAge(agent) ? ` activity=${formatActivityAge(agent)}` : ""}${agent.progress?.currentTool ? ` tool=${agent.progress.currentTool}` : ""}${agent.toolUses ? ` tools=${agent.toolUses}` : ""}${!agent.usage && agent.progress?.tokens ? ` tokens=${agent.progress.tokens}` : ""}${agent.progress?.turns ? ` turns=${agent.progress.turns}` : ""}${agent.jsonEvents !== undefined ? ` jsonEvents=${agent.jsonEvents}` : ""}${agent.outputPath ? ` output=${agent.outputPath}` : ""}${agent.transcriptPath ? ` transcript=${agent.transcriptPath}` : ""}${agent.statusPath ? ` status=${agent.statusPath}` : ""}${agent.error ? ` error=${agent.error}` : ""}`;
+	const agentLine = (agent: typeof crewAgents[number]): string => `- ${agent.id} [${agent.status}] ${agent.role} -> ${agent.agent} runtime=${agent.runtime}${agent.model ? ` model=${agent.model}` : ""}${agent.usage ? ` usage=${formatUsage(agent.usage)}` : ""}${agent.usage?.cost ? ` cost=${formatCost(agent.usage.cost)}` : ""}${agent.progress?.activityState ? ` activityState=${agent.progress.activityState}` : ""}${formatActivityAge(agent) ? ` activity=${formatActivityAge(agent)}` : ""}${agent.progress?.currentTool ? ` tool=${agent.progress.currentTool}` : ""}${agent.toolUses ? ` tools=${agent.toolUses}` : ""}${!agent.usage && agent.progress?.tokens ? ` tokens=${agent.progress.tokens}` : ""}${agent.progress?.turns ? ` turns=${agent.progress.turns}` : ""}${agent.jsonEvents !== undefined ? ` jsonEvents=${agent.jsonEvents}` : ""}${agent.outputPath ? ` output=${agent.outputPath}` : ""}${agent.transcriptPath ? ` transcript=${agent.transcriptPath}` : ""}${agent.statusPath ? ` status=${agent.statusPath}` : ""}${agent.error ? ` error=${agent.error}` : ""}`;
 	const lines = [
 		`Run: ${manifest.runId}`,
 		`Team: ${manifest.team}`,
 		`Workflow: ${manifest.workflow ?? "(none)"}`,
 		`Status: ${manifest.status}`,
+		`Progress: ${phaseProgress.overallPercentage}% (~${formatDuration(phaseProgress.estimatedRemainingMs)} remaining)`,
 		`Workspace mode: ${manifest.workspaceMode}`,
 		...(manifest.runtimeResolution ? [`Runtime: ${manifest.runtimeResolution.kind}`, `Runtime safety: ${manifest.runtimeResolution.safety}`, `Runtime requested: ${manifest.runtimeResolution.requestedMode}${manifest.runtimeResolution.reason ? ` (${manifest.runtimeResolution.reason})` : ""}`] : []),
 		`Goal: ${manifest.goal}`,
@@ -109,5 +118,50 @@ export function handleStatus(params: TeamToolParamsValue, ctx: TeamContext): PiT
 		"Recent events:",
 		...(events.length ? events.map((event) => `- ${event.time} ${event.type}${event.taskId ? ` ${event.taskId}` : ""}${event.message ? `: ${event.message}` : ""}`) : ["- (none)"]),
 	];
+	if (!fullDetails) {
+		return result(
+			buildCompactStatus(manifest, tasks, counts, asyncLivenessLine, phaseProgress).join("\n"),
+			{ action: "status", status: "ok", runId: manifest.runId, artifactsRoot: manifest.artifactsRoot, intent: `status ${manifest.runId}: ${manifest.status} (compact)` },
+		);
+	}
 	return result(lines.join("\n"), { action: "status", status: "ok", runId: manifest.runId, artifactsRoot: manifest.artifactsRoot, intent: `status ${manifest.runId}: ${manifest.status}` });
 }
+
+/**
+ * Compact status builder (DX: Round 16 F3). A tight summary for quick checks:
+ * identity, status, goal, task counts, and ONLY failed / attention task
+ * errors — not the 40-line dense dump. Invoked when params.details === false.
+ *
+ * Exported for unit testing.
+ */
+export function buildCompactStatus(
+	manifest: { runId: string; team: string; workflow?: string; status: string; goal: string; workspaceMode?: string },
+	tasks: Array<{ id: string; status: string; role: string; agent: string; error?: string }>,
+	counts: Map<string, number>,
+	asyncLivenessLine?: string,
+	progress?: { overallPercentage: number; estimatedRemainingMs: number },
+): string[] {
+	const failedOrAttention = tasks.filter(
+		(t) =>
+			t.status === "failed" ||
+			t.status === "needs_attention" ||
+			t.status === "cancelled",
+	);
+	const lines = [
+		`Run: ${manifest.runId}`,
+		`Team: ${manifest.team}${manifest.workflow ? ` (${manifest.workflow})` : ""}`,
+		`Status: ${manifest.status}`,
+		...(progress ? [`Progress: ${progress.overallPercentage}% (~${formatDuration(progress.estimatedRemainingMs)} remaining)`] : []),
+		`Goal: ${manifest.goal}`,
+		...(asyncLivenessLine ? [asyncLivenessLine] : []),
+		`Tasks: ${[...counts.entries()].map(([s, c]) => `${s}=${c}`).join(", ") || "none"}`,
+	];
+	if (failedOrAttention.length > 0) {
+		lines.push("Issues:");
+		for (const t of failedOrAttention) {
+			lines.push(`- ${t.id} [${t.status}] ${t.role}: ${t.error ?? "(no error detail)"}`);
+		}
+	}
+	lines.push("Tip: pass details=true for full output (task graph, agents, effectiveness, events).");
+	return lines;
+}

package/src/extension/team-tool.ts

@@ -156,6 +156,8 @@ import { handleParallel } from "./team-tool/parallel-dispatch.ts";
 import { handlePlan } from "./team-tool/plan.ts";
 import { handleRespond } from "./team-tool/respond.ts";
 import { handleStatus } from "./team-tool/status.ts";
+import { RUN_NOT_FOUND_HINT } from "./team-tool/run-not-found.ts";
+import { formatActionSuggestion } from "./action-suggestions.ts";
 
 export { handleApi } from "./team-tool/api.ts";
 export { handleRetry } from "./team-tool/cancel.ts";
@@ -459,14 +461,14 @@ export async function handleResume(
 	const runCwd = locateRunCwd(params.runId, ctx.cwd);
 	if (!runCwd)
 		return result(
-			`Run '${params.runId}' not found.`,
+			`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`,
 			{ action: "resume", status: "error" },
 			true,
 		);
 	const loaded = loadRunManifestById(runCwd, params.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
 	if (!loaded)
 		return result(
-			`Run '${params.runId}' not found.`,
+			`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`,
 			{ action: "resume", status: "error" },
 			true,
 		);
@@ -1347,7 +1349,7 @@ export async function handleTeamTool(
 		}
 		default:
 			return result(
-				`Unknown action: ${action}`,
+				`Unknown action: ${action}${formatActionSuggestion(String(action))}`,
 				{ action: "unknown", status: "error" },
 				true,
 			);

package/src/runtime/async-runner.ts

@@ -231,6 +231,13 @@ export async function spawnBackgroundTeamRun(manifest: TeamRunManifest): Promise
 		windowsHide: true,
 	} as unknown as Parameters<typeof spawn>[2];
 	const child = spawn(process.execPath, command.args, spawnOpts);
+	// Round 27 (BUG 3): the piped stdout/stderr are NEVER read or destroyed →
+	// 2 FDs leak per background spawn, and if the child writes >64KB (pipe
+	// buffer) it blocks forever (nobody drains the pipe) → background runner
+	// hangs. The background runner redirects its own console to a file, so we
+	// don't need this output — destroy the read ends immediately.
+	child.stdout?.destroy();
+	child.stderr?.destroy();
 	child.on("error", (error: Error) => {
 		logInternalError("async-runner.spawn", error, `pid=${child.pid ?? "unknown"}`);
 	});

package/src/runtime/background-runner.ts

@@ -525,7 +525,13 @@ async function main(): Promise<void> {
 		const agents = allAgents(discoverAgents(cwd));
 		debugLog(`[background-runner] discoverAgents done, ${agents.length} agents`,
 		);
-		try { fs.fsyncSync(fs.openSync(manifest.eventsPath, "a")); } catch { /* best-effort */ } // FORCE flush so we see this before death
+		// Round 27 (BUG 2): openSync returned an fd that was never closed → FD
+		// leak per background runner startup. Close it in a finally (matches the
+		// canonical pattern in checkpoint.ts:83 and event-log.ts:582).
+		try {
+			const fd = fs.openSync(manifest.eventsPath, "a");
+			try { fs.fsyncSync(fd); } finally { try { fs.closeSync(fd); } catch { /* best-effort */ } }
+		} catch { /* best-effort */ } // FORCE flush so we see this before death
 		debugLog(`[background-runner] calling directTeamAndWorkflowFromRun`,
 		);
 		const direct = directTeamAndWorkflowFromRun(manifest, tasks, agents);