pi-crew 0.9.53 → 0.9.55

package/src/extension/run-index.ts

@@ -0,0 +1,131 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { DEFAULT_PATHS } from "../config/defaults.ts";
+import { createCancellationToken } from "../runtime/cancellation-token.ts";
+import { activeRunEntries } from "../state/active-run-registry.ts";
+import type { TeamRunManifest } from "../state/types.ts";
+import { findRepoRoot, projectCrewRoot, userCrewRoot } from "../utils/paths.ts";
+import { isSafePathId, resolveRealContainedPath } from "../utils/safe-paths.ts";
+import { sharedScanCache } from "../utils/scan-cache.ts";
+
+function readManifest(filePath: string): TeamRunManifest | undefined {
+	const cached = sharedScanCache.readAndCache("manifests", filePath, filePath);
+	if (cached) return cached.raw as TeamRunManifest;
+	try {
+		return JSON.parse(fs.readFileSync(filePath, "utf-8")) as TeamRunManifest;
+	} catch {
+		return undefined;
+	}
+}
+
+function collectRuns(root: string, maxEntries?: number, signal?: AbortSignal): TeamRunManifest[] {
+	const runsRoot = path.join(root, DEFAULT_PATHS.state.runsSubdir);
+	if (!fs.existsSync(runsRoot)) return [];
+	if (signal?.aborted) return [];
+	// 2.19 — skip temp directories to avoid phantom runs from test/isolated workspaces.
+	// Runs in /tmp/ are typically from tests or isolated worktrees and should not
+	// appear in production dashboards unless the process is actually alive.
+	const tempDirs = [os.tmpdir(), "/var/tmp", "/tmp"];
+	const isTempRoot = tempDirs.some((t) => root.startsWith(t + path.sep));
+	const token = createCancellationToken({ signal });
+	const entries = fs
+		.readdirSync(runsRoot, { withFileTypes: true })
+		.filter((entry) => entry.isDirectory() && isSafePathId(entry.name))
+		.map((entry) => entry.name)
+		.sort((a, b) => (b ?? "").localeCompare(a ?? ""));
+	const selected = maxEntries !== undefined ? entries.slice(0, Math.max(0, maxEntries)) : entries;
+	const results: TeamRunManifest[] = [];
+	for (let i = 0; i < selected.length; i++) {
+		if (i % 10 === 0) token.heartbeat(`collectRuns:${i}/${selected.length}`);
+		try {
+			const manifest = readManifest(path.join(resolveRealContainedPath(runsRoot, selected[i]), DEFAULT_PATHS.state.manifestFile));
+			if (!manifest) continue;
+			// Filter out ghost runs: active status but CWD no longer exists.
+			// These are deadletter/replay/temp runs whose temp dirs were cleaned up.
+			if (
+				(manifest.status === "queued" || manifest.status === "running" || manifest.status === "planning") &&
+				manifest.cwd &&
+				!fs.existsSync(manifest.cwd)
+			)
+				continue;
+			// 2.19 — for runs in temp directories, verify the background process is alive.
+			// Without this, runs that completed/crashed but left stale manifests will still show.
+			if (isTempRoot && (manifest.status === "running" || manifest.status === "queued" || manifest.status === "planning")) {
+				const asyncPidPath = path.join(path.dirname(manifest.stateRoot), "async.pid");
+				try {
+					const pidData = JSON.parse(fs.readFileSync(asyncPidPath, "utf-8"));
+					const pid = pidData?.pid;
+					if (pid && typeof pid === "number") {
+						try {
+							process.kill(pid, 0);
+						} catch {
+							continue;
+						} // PID dead, skip this run
+					}
+				} catch {
+					/* no async.pid or parse error — keep the run */
+				}
+			}
+			results.push(manifest);
+		} catch {
+			/* skip unreadable manifests */
+		}
+	}
+	return results;
+}
+
+function mergeRuns(runSets: TeamRunManifest[][], max?: number): TeamRunManifest[] {
+	const byId = new Map<string, TeamRunManifest>();
+	for (const runs of runSets) for (const run of runs) byId.set(run.runId, run);
+	const sorted = [...byId.values()].sort((a, b) => (b.createdAt ?? "").localeCompare(a.createdAt ?? ""));
+	return max !== undefined ? sorted.slice(0, Math.max(0, max)) : sorted;
+}
+
+function scopedRunRoots(cwd: string): string[] {
+	const roots = new Set<string>();
+	roots.add(userCrewRoot());
+	const projectRoot = findRepoRoot(cwd);
+	if (projectRoot) roots.add(projectCrewRoot(cwd));
+	return [...roots];
+}
+
+function collectActiveRuns(cwd?: string): TeamRunManifest[] {
+	return activeRunEntries()
+		.map((entry) => readManifest(entry.manifestPath))
+		.filter((manifest): manifest is TeamRunManifest => manifest !== undefined);
+}
+
+export function listRuns(cwd: string, signal?: AbortSignal): TeamRunManifest[] {
+	const roots = scopedRunRoots(cwd);
+	return mergeRuns([...roots.map((root) => collectRuns(root, undefined, signal)), collectActiveRuns()]);
+}
+
+export function listRecentRuns(cwd: string, max = 20, signal?: AbortSignal): TeamRunManifest[] {
+	const roots = scopedRunRoots(cwd);
+	return mergeRuns([...roots.map((root) => collectRuns(root, max, signal)), collectActiveRuns()], max);
+}
+
+/**
+ * List runs filtered to a specific scope.
+ * - "project": only runs in the project crew root
+ * - "user": only runs in the user crew root
+ * - "all" (default): merge both scopes (current behavior)
+ */
+export function listRunsByScope(
+	cwd: string,
+	scope: "project" | "user" | "all" = "all",
+	max?: number,
+	signal?: AbortSignal,
+): TeamRunManifest[] {
+	const projectRoot = findRepoRoot(cwd);
+	switch (scope) {
+		case "project":
+			return projectRoot ? collectRuns(projectCrewRoot(cwd), max, signal) : [];
+		case "user":
+			return collectRuns(userCrewRoot(), max, signal);
+		case "all":
+		default:
+			return max !== undefined ? listRecentRuns(cwd, max, signal) : listRuns(cwd, signal);
+	}
+}

package/src/extension/run-maintenance.ts

@@ -0,0 +1,190 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { DEFAULT_PATHS } from "../config/defaults.ts";
+import { createCancellationToken } from "../runtime/cancellation-token.ts";
+import type { TeamRunManifest } from "../state/types.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+import { projectCrewRoot, userCrewRoot } from "../utils/paths.ts";
+import { redactSecrets } from "../utils/redaction.ts";
+import { isSafePathId, resolveRealContainedPath } from "../utils/safe-paths.ts";
+import { cleanupRunWorktrees } from "../worktree/cleanup.ts";
+import { listRuns } from "./run-index.ts";
+
+export interface PruneRunsResult {
+	kept: string[];
+	removed: string[];
+	auditPath?: string;
+}
+
+export interface PruneRunsOptions {
+	intent?: string;
+	signal?: AbortSignal;
+}
+
+function isFinished(run: TeamRunManifest): boolean {
+	// P3: "blocked" is NOT a terminal status — the run is waiting on something
+	// (plan approval, mailbox reply, scheduler stall) and can transition to
+	// running/cancelled/failed (per TEAM_RUN_STATUS_TRANSITIONS). Pruning a
+	// blocked run destroys recoverable state (e.g. a plan the user needs to
+	// approve, or a mailbox wait the user needs to answer). Truly stuck
+	// blocked runs are handled by the stale-reconciler/crash-recovery, not
+	// by prune.
+	return run.status === "completed" || run.status === "failed" || run.status === "cancelled";
+}
+
+function isSafeToPrune(cwd: string, run: TeamRunManifest): boolean {
+	try {
+		const crewRoot = run.stateRoot.startsWith(userCrewRoot() + path.sep) ? userCrewRoot() : projectCrewRoot(cwd);
+		resolveRealContainedPath(crewRoot, run.stateRoot);
+		resolveRealContainedPath(crewRoot, run.artifactsRoot);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function appendPruneAudit(cwd: string, payload: Record<string, unknown>): string | undefined {
+	try {
+		const filePath = path.join(projectCrewRoot(cwd), "audit", "prune.jsonl");
+		fs.mkdirSync(path.dirname(filePath), { recursive: true });
+		fs.appendFileSync(filePath, `${JSON.stringify(redactSecrets({ ...payload, auditedAt: new Date().toISOString() }))}\n`, "utf-8");
+		return filePath;
+	} catch (error) {
+		logInternalError("prune.audit-write", error, `cwd=${cwd}`);
+		return undefined;
+	}
+}
+
+export function pruneFinishedRuns(cwd: string, keep: number, options: PruneRunsOptions = {}): PruneRunsResult {
+	const token = createCancellationToken({ signal: options.signal });
+	const finished = listRuns(cwd, options.signal)
+		.filter((run) => run.cwd === cwd && isFinished(run))
+		.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);
+	for (let i = 0; i < toRemove.length; i++) {
+		if (i % 5 === 0) token.heartbeat(`prune:${i}/${toRemove.length}`);
+		const run = toRemove[i];
+		if (!isSafeToPrune(cwd, run)) {
+			logInternalError(
+				"prune.path-unsafe",
+				new Error(`Skipping unsafe prune: stateRoot=${run.stateRoot}, artifactsRoot=${run.artifactsRoot}`),
+				`runId=${run.runId}`,
+			);
+			continue;
+		}
+		// P2: clean up git worktrees BEFORE deleting state. Worktrees live at
+		// <crewRoot>/state/worktrees/<runId>/ — a separate path from stateRoot
+		// (<crewRoot>/state/runs/<runId>/) and artifactsRoot, so fs.rmSync below
+		// does NOT touch them. Without this, every pruned worktree-using run
+		// leaks its worktree dir + git branch. cleanupRunWorktrees (no force)
+		// preserves dirty worktrees by writing a diff artifact and skipping
+		// the removal — in that case we skip the whole prune of this run so
+		// the user can recover (no silent data loss). Compare handleForget
+		// which calls cleanupRunWorktrees.
+		const worktreeCleanup = cleanupRunWorktrees(run, { signal: options.signal });
+		if (worktreeCleanup.preserved.length > 0) {
+			logInternalError(
+				"prune.worktree-preserved",
+				new Error(
+					`Skipping prune: ${worktreeCleanup.preserved.length} dirty worktree(s) preserved for recovery: ${worktreeCleanup.preserved.map((p) => p.path).join(", ")}`,
+				),
+				`runId=${run.runId}`,
+			);
+			continue;
+		}
+		fs.rmSync(run.stateRoot, { recursive: true, force: true });
+		fs.rmSync(run.artifactsRoot, { recursive: true, force: true });
+		removed.push(run.runId);
+	}
+	const auditPath = appendPruneAudit(cwd, {
+		action: "prune",
+		keep,
+		intent: options.intent,
+		kept,
+		removed,
+	});
+	return { kept, removed, auditPath };
+}
+
+/**
+ * Prune finished run directories at the user level (~/.pi/agent/extensions/pi-crew/state/runs/).
+ *
+ * This handles runs created without a project root (e.g. `team action='run'` from home directory)
+ * that would otherwise accumulate forever.
+ *
+ * @param keep Number of most recent finished runs to retain
+ * @returns kept and removed run IDs
+ */
+export function pruneUserLevelRuns(keep: number): PruneRunsResult {
+	const crewRoot = userCrewRoot();
+	const runsRoot = path.join(crewRoot, DEFAULT_PATHS.state.runsSubdir);
+	if (!fs.existsSync(runsRoot)) return { kept: [], removed: [] };
+
+	// Read all run directories, parse manifests, filter to finished
+	const MAX_DIRS = 500;
+	const finished: Array<{
+		runId: string;
+		updatedAt: string;
+		stateRoot: string;
+		artifactsRoot: string;
+	}> = [];
+	const ghostRemoved: string[] = [];
+	const dirs = fs
+		.readdirSync(runsRoot, { withFileTypes: true })
+		.filter((entry) => entry.isDirectory() && isSafePathId(entry.name))
+		.slice(0, MAX_DIRS)
+		.map((entry) => entry.name);
+
+	for (const dir of dirs) {
+		const manifestPath = path.join(runsRoot, dir, DEFAULT_PATHS.state.manifestFile);
+		let manifest: TeamRunManifest | undefined;
+		try {
+			manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8")) as TeamRunManifest;
+		} catch {
+			continue;
+		}
+
+		// Ghost run cleanup: active status but CWD no longer exists.
+		// These are deadletter/replay/temp runs from dead Pi sessions.
+		const isActive = manifest.status === "queued" || manifest.status === "running" || manifest.status === "planning";
+		if (isActive && manifest.cwd && !fs.existsSync(manifest.cwd)) {
+			fs.rmSync(path.join(runsRoot, dir), {
+				recursive: true,
+				force: true,
+			});
+			ghostRemoved.push(manifest.runId);
+			continue;
+		}
+
+		if (!isFinished(manifest)) continue;
+
+		// Safety check: ensure stateRoot and artifactsRoot are contained within user crew root
+		try {
+			resolveRealContainedPath(crewRoot, manifest.stateRoot);
+			resolveRealContainedPath(crewRoot, manifest.artifactsRoot);
+		} catch {
+			continue;
+		}
+
+		finished.push({
+			runId: manifest.runId,
+			updatedAt: manifest.updatedAt,
+			stateRoot: manifest.stateRoot,
+			artifactsRoot: manifest.artifactsRoot,
+		});
+	}
+
+	// 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[] = [];
+	for (const run of finished.slice(keep)) {
+		fs.rmSync(run.stateRoot, { recursive: true, force: true });
+		fs.rmSync(run.artifactsRoot, { recursive: true, force: true });
+		removed.push(run.runId);
+	}
+
+	return { kept, removed: [...removed, ...ghostRemoved] };
+}

package/src/extension/session-summary.ts

@@ -0,0 +1,18 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { readCrewAgents } from "../runtime/crew-agent-records.ts";
+import { isDisplayActiveRun } from "../runtime/process-status.ts";
+import { listRuns } from "./run-index.ts";
+
+export function notifyActiveRuns(ctx: ExtensionContext): void {
+	const active = listRuns(ctx.cwd)
+		.filter((run) => {
+			if (run.status !== "queued" && run.status !== "planning" && run.status !== "running") return false;
+			// Use the same display filter as the widget/powerbar — runs without
+			// real agent evidence (e.g. integration test fixtures) must not appear.
+			const agents = readCrewAgents(run);
+			return isDisplayActiveRun(run, agents);
+		})
+		.slice(0, 5);
+	if (active.length === 0) return;
+	ctx.ui.notify(`pi-crew active runs: ${active.map((run) => `${run.runId} [${run.status}]`).join(", ")}`, "info");
+}

package/src/extension/team-manager-command.ts

@@ -0,0 +1,153 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { listRuns } from "./run-index.ts";
+// Lazy-loaded: team-tool.ts pulls in entire runtime chain.
+import type { handleTeamTool as HandleTeamToolFn } from "./team-tool.ts";
+
+let _cachedHandleTeamTool: typeof HandleTeamToolFn | undefined;
+async function handleTeamTool(
+	params: Parameters<typeof HandleTeamToolFn>[0],
+	ctx: Parameters<typeof HandleTeamToolFn>[1],
+): Promise<Awaited<ReturnType<typeof HandleTeamToolFn>>> {
+	if (!_cachedHandleTeamTool) {
+		// LAZY: team-tool.ts pulls in the entire runtime chain.
+		const mod = await import("./team-tool.ts");
+		_cachedHandleTeamTool = mod.handleTeamTool;
+	}
+	return _cachedHandleTeamTool(params, ctx);
+}
+
+import { isToolError, textFromToolResult } from "./tool-result.ts";
+
+async function notifyResult(ctx: ExtensionCommandContext, result: Awaited<ReturnType<typeof handleTeamTool>>): Promise<void> {
+	const text = textFromToolResult(result);
+	ctx.ui.notify(text.length > 1000 ? `${text.slice(0, 997)}...` : text, isToolError(result) ? "error" : "info");
+}
+
+export async function handleTeamManagerCommand(_args: string, ctx: ExtensionCommandContext): Promise<void> {
+	const action = await ctx.ui.select("pi-crew", [
+		"List teams/workflows/agents/runs",
+		"Run team",
+		"Show run status",
+		"Cleanup run worktrees",
+		"Create routed resource",
+		"Update routed resource",
+		"Doctor",
+	]);
+	if (!action) return;
+
+	if (action.startsWith("List")) {
+		await notifyResult(ctx, await handleTeamTool({ action: "list" }, ctx));
+		return;
+	}
+
+	if (action === "Doctor") {
+		await notifyResult(ctx, await handleTeamTool({ action: "doctor" }, ctx));
+		return;
+	}
+
+	if (action === "Create routed resource" || action === "Update routed resource") {
+		const isUpdate = action === "Update routed resource";
+		const resource = await ctx.ui.select("Resource type", ["agent", "team"]);
+		if (resource !== "agent" && resource !== "team") return;
+		const name = await ctx.ui.input("Name", resource === "agent" ? "custom-agent" : "custom-team");
+		if (!name) return;
+		const description = await ctx.ui.input("Description", "When to use this resource");
+		if (!description) return;
+		const triggers = await ctx.ui.input("Triggers (comma-separated)", "");
+		const useWhen = await ctx.ui.input("Use when (comma-separated)", "");
+		const avoidWhen = await ctx.ui.input("Avoid when (comma-separated)", "");
+		const cost = await ctx.ui.select("Cost", ["cheap", "free", "expensive"]);
+		const category = await ctx.ui.input("Category", "custom");
+		const baseConfig = {
+			name,
+			description,
+			scope: "project",
+			triggers,
+			useWhen,
+			avoidWhen,
+			cost,
+			category,
+		};
+		if (resource === "agent") {
+			const systemPrompt = isUpdate ? undefined : `You are ${name}.`;
+			await notifyResult(
+				ctx,
+				await handleTeamTool(
+					{
+						action: isUpdate ? "update" : "create",
+						resource,
+						agent: name,
+						config: { ...baseConfig, systemPrompt },
+					},
+					ctx,
+				),
+			);
+			return;
+		}
+		const agent = await ctx.ui.input("Role agent", "executor");
+		await notifyResult(
+			ctx,
+			await handleTeamTool(
+				{
+					action: isUpdate ? "update" : "create",
+					resource,
+					team: name,
+					config: {
+						...baseConfig,
+						roles: [{ name: "executor", agent: agent || "executor" }],
+					},
+				},
+				ctx,
+			),
+		);
+		return;
+	}
+
+	if (action === "Run team") {
+		const team = await ctx.ui.input("Team name", "default");
+		if (team === undefined) return;
+		const goal = await ctx.ui.input("Goal", "Describe the team objective");
+		if (!goal) return;
+		const asyncRun = await ctx.ui.confirm("Async run?", "Run in detached background mode?");
+		const worktree = await ctx.ui.confirm("Worktree mode?", "Use git worktrees for task workspaces? Requires a clean repo by default.");
+		await notifyResult(
+			ctx,
+			await handleTeamTool(
+				{
+					action: "run",
+					team: team || "default",
+					goal,
+					async: asyncRun,
+					workspaceMode: worktree ? "worktree" : "single",
+				},
+				ctx,
+			),
+		);
+		return;
+	}
+
+	const runs = listRuns(ctx.cwd).slice(0, 20);
+	if (runs.length === 0) {
+		ctx.ui.notify("No pi-crew runs found.", "info");
+		return;
+	}
+	const selected = await ctx.ui.select(
+		"Select run",
+		runs.map((run) => `${run.runId} [${run.status}] ${run.team}/${run.workflow ?? "none"}`),
+	);
+	if (!selected) return;
+	const runId = selected.split(" ")[0];
+	if (!runId) return;
+
+	if (action === "Show run status") {
+		await notifyResult(ctx, await handleTeamTool({ action: "status", runId }, ctx));
+		return;
+	}
+	if (action === "Cleanup run worktrees") {
+		const force = await ctx.ui.confirm(
+			"Force cleanup?",
+			"Force may remove dirty worktrees. Choose false to preserve dirty worktrees and capture cleanup diffs.",
+		);
+		await notifyResult(ctx, await handleTeamTool({ action: "cleanup", runId, force }, ctx));
+	}
+}

package/src/extension/team-onboard.ts

@@ -0,0 +1,180 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { TeamRunManifest } from "../state/types.ts";
+import { allTeams, discoverTeams } from "../teams/discover-teams.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+import { projectCrewRoot } from "../utils/paths.ts";
+
+export interface OnboardingOptions {
+	team?: string;
+	limit?: number;
+	cwd?: string;
+}
+
+interface RunSummary {
+	runId: string;
+	status: string;
+	goal: string;
+	team: string;
+	createdAt: string;
+	completedAt?: string;
+	taskCount: number;
+}
+
+/**
+ * Load run summaries from the state directory.
+ */
+function loadRunSummaries(cwd: string, options: OnboardingOptions = {}): RunSummary[] {
+	const crewRoot = projectCrewRoot(cwd);
+	const runsRoot = path.join(crewRoot, "state", "runs");
+
+	if (!fs.existsSync(runsRoot)) return [];
+
+	const limit = options.limit ?? 5;
+	const teamFilter = options.team;
+
+	const entries = fs
+		.readdirSync(runsRoot)
+		.filter((e) => {
+			try {
+				return fs.statSync(path.join(runsRoot, e)).isDirectory();
+			} catch {
+				return false;
+			}
+		})
+		.sort()
+		.reverse()
+		.slice(0, 100);
+
+	const summaries: RunSummary[] = [];
+
+	for (const runId of entries) {
+		if (summaries.length >= limit) break;
+
+		const manifestPath = path.join(runsRoot, runId, "manifest.json");
+		if (!fs.existsSync(manifestPath)) continue;
+
+		try {
+			const raw = JSON.parse(fs.readFileSync(manifestPath, "utf-8")) as TeamRunManifest & { completedAt?: string };
+
+			if (teamFilter && raw.team !== teamFilter) continue;
+
+			summaries.push({
+				runId,
+				status: raw.status,
+				goal: raw.goal ?? "",
+				team: raw.team,
+				createdAt: raw.createdAt,
+				completedAt: raw.completedAt ?? raw.updatedAt,
+				taskCount: 0, // tasks stored separately, not in manifest
+			});
+		} catch (error) {
+			logInternalError("team-onboard.load-manifest", error, undefined, "debug");
+		}
+	}
+
+	return summaries;
+}
+
+/**
+ * Format duration in minutes. Defensive against missing/invalid timestamps
+ * (e.g. legacy test runs) — returns "?" instead of "NaNm".
+ */
+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`;
+	return `${minutes}m`;
+}
+
+/**
+ * Build markdown onboarding guide for a team.
+ */
+export function buildTeamOnboarding(team: string, cwd: string, options: OnboardingOptions = {}): string {
+	const runs = loadRunSummaries(cwd, { ...options, team });
+
+	const lines: string[] = [];
+
+	// Header
+	lines.push(`# Team: ${team}`);
+	lines.push("");
+	lines.push(`> Multi-agent ${team} team for pi-crew.`);
+	lines.push("");
+
+	// Overview stats
+	const completed = runs.filter((r) => r.status === "completed");
+	const failed = runs.filter((r) => r.status === "failed" || r.status === "cancelled");
+
+	let avgDuration = 0;
+	if (completed.length > 0) {
+		const totalMs = completed.reduce((sum, r) => {
+			const start = new Date(r.createdAt).getTime();
+			const end = r.completedAt ? new Date(r.completedAt).getTime() : Date.now();
+			return sum + (end - start);
+		}, 0);
+		avgDuration = totalMs / completed.length / 1000 / 60;
+	}
+
+	lines.push("## Overview");
+	lines.push("");
+	lines.push(`| Metric | Value |`);
+	lines.push(`|--------|-------|`);
+	lines.push(`| Total runs | ${runs.length} |`);
+	lines.push(`| Completed | ${completed.length} |`);
+	lines.push(`| Failed/Cancelled | ${failed.length} |`);
+	if (avgDuration > 0) {
+		lines.push(`| Avg duration | ${avgDuration.toFixed(1)} min |`);
+	}
+	lines.push("");
+
+	// Past runs table
+	if (runs.length > 0) {
+		lines.push("## Past Runs");
+		lines.push("");
+		lines.push("| Run | Goal | Duration | Status |");
+		lines.push("|-----|------|----------|--------|");
+
+		for (const run of runs) {
+			const duration = formatDuration(run.createdAt, run.completedAt);
+			const goalPreview = run.goal ? run.goal.slice(0, 40) : "N/A";
+			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("");
+	}
+
+	// How to run
+	lines.push("## How to Run");
+	lines.push("");
+	lines.push("```bash");
+	lines.push(`team action='run' team='${team}' goal="<your goal>"`);
+	lines.push("```");
+	lines.push("");
+	lines.push("See `team action='help'` for more options.");
+	lines.push("");
+
+	// Teams
+	lines.push("## Available Teams");
+	lines.push("");
+	try {
+		const discovery = discoverTeams(cwd);
+		const teams = allTeams(discovery);
+		for (const t of teams) {
+			lines.push(`- \`${t.name}\` — ${t.description ?? "No description"}`);
+		}
+	} catch {
+		lines.push("- *(team discovery unavailable)*");
+	}
+	lines.push("");
+
+	// Footer
+	lines.push("---");
+	lines.push("*Generated by pi-crew. For up-to-date info, check recent run history.*");
+
+	return lines.join("\n");
+}