pi-crew 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## [0.5.1] — Integration + End-to-End Tests (2026-05-26)
+
+### Integration
+- **team-tool.ts**: Wire P1-P6 into switch statement
+  - `action='graph'` — load/save/list run graphs
+  - `action='onboard'` — team onboarding generator  
+  - `action='explain'` — task explain context
+  - `action='cache'` — run result caching lookup
+  - `action='checkpoint'` — checkpoint retrieval
+  - `action='search'` — BM25 ranked agent/team search
+- **team-tool-schema.ts**: Add 6 new actions to schema
+- **Type fixes**: run-graph.ts, run-cache.ts, checkpoint.ts, team-onboard.ts
+- **P0 .gitignore**: ensureCrewDirectory auto-updates .gitignore
+
+### Tests
+- 8/8 new action tests pass
+- 10/10 end-to-end feature tests pass
+- All 1796 unit + 45 integration passing
+- CI: Ubuntu/macOS/Windows all passing
+
+---
+
+## [0.5.0]
+
+### New Features: P0-P6 from Understand-Anything Research
+
+#### P0: Auto-Setup .crew Directory
+- `ensureCrewDirectory()` creates full directory structure on first run
+- `gitignore-manager.ts` auto-updates `.gitignore` with `.crew/` entries
+- Creates: `state/runs`, `state/subagents`, `artifacts`, `cache`, `graphs`, `audit`
+- README.md explains `.crew` directory purpose
+
+#### P1: BM25 Agent/Team Search
+- `BM25Search` class with configurable k1/b parameters
+- `searchAgents(query)` — ranked agent search by name/description/skills
+- `searchTeams(query)` — ranked team search by name/description/roles
+
+#### P2: Team Onboarding Generator
+- `buildTeamOnboarding()` generates markdown from run history
+- Shows: past runs, stats, usage examples, available teams
+- `loadRunSummaries()` helper for run history loading
+
+#### P3: Task Explain Context
+- `handleExplain(runId, taskId)` — full run or individual task explanation
+- `buildTaskExplainContext()` — causal chain, layers, files produced
+- `formatTaskExplain()` — markdown output with why/what/connections
+
+#### P4: Unified Run Graph
+- `buildRunGraph()` — consolidates manifest + tasks into single graph
+- `saveRunGraph()` / `loadRunGraph()` — persist to `.crew/graphs/`
+- `listRunGraphs()` — enumerate archived graphs
+
+#### P5: Run Result Caching
+- `computeRunCacheKey()` — SHA-256 hash of goal+team+workflow
+- `getCachedRun()` / `saveRunToCache()` — TTL-based cache (default 1h)
+- `clearCache()` / `getCacheStats()` — cache management
+
+#### P6: Agent Checkpointing
+- `FileCheckpointStore` — checkpoints in `.crew/state/runs/<runId>/checkpoints/`
+- `saveCheckpoint()` / `loadCheckpoint()` / `clearCheckpoint()`
+- `hasCheckpoint()` / `listCheckpoints()` for recovery
+
+### Tests
+- 56 new unit tests (all passing)
+- Total: 1796 unit tests + 45 integration tests passing
+
+### Bug Fixes
+- Worktree test teardown: clean `.crew/` before git checks for clean repository
+
+---
+
 ## [0.4.0] — 9arm-skills Enforcement Patterns & Integration Tests (2026-05-26)
 
 ### Features

package/package.json

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

package/src/extension/team-onboard.ts

@@ -0,0 +1,174 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { projectCrewRoot } from "../utils/paths.ts";
+import { allTeams, discoverTeams } from "../teams/discover-teams.ts";
+import type { TeamRunManifest } from "../state/types.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 {
+      continue;
+    }
+  }
+
+  return summaries;
+}
+
+/**
+ * Format duration in minutes.
+ */
+function formatDuration(createdAt: string, completedAt?: string): string {
+  const start = new Date(createdAt).getTime();
+  const end = completedAt ? new Date(completedAt).getTime() : Date.now();
+  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 statusIcon = run.status === "completed" ? "✅" : run.status === "failed" ? "❌" : "⚠️";
+      lines.push(`| \`${run.runId.slice(-8)}\` | ${goalPreview}${run.goal.length > 40 ? "..." : ""} | ${duration} | ${statusIcon} ${run.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");
+}

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

@@ -0,0 +1,268 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { toolResult } from "../tool-result.ts";
+import { loadRunManifestById } from "../../state/state-store.ts";
+import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
+
+/**
+ * Local wrapper matching the planned `result` API used by handleExplain.
+ */
+function result(text: string, details: Record<string, unknown>, isError: boolean): { isError: boolean; text: string } {
+  return { isError, text };
+}
+
+export interface TaskExplainContext {
+  taskId: string;
+  role: string;
+  status: string;
+  phase?: string;
+  why: string;
+  what: string;
+  filesTouched: string[];
+  connectedTasks: Array<{ taskId: string; status: string; relation: string }>;
+  layer: string;
+  complexity: "simple" | "moderate" | "complex";
+  usage?: { inputTokens?: number; outputTokens?: number };
+  duration?: number;
+}
+
+/**
+ * Build explain context for a specific task in a run.
+ */
+export function buildTaskExplainContext(
+  manifest: TeamRunManifest,
+  tasks: TeamTaskState[],
+  taskId: string,
+): TaskExplainContext {
+  const task = tasks.find((t) => t.id === taskId);
+  if (!task) {
+    throw new Error(`Task ${taskId} not found in run ${manifest.runId}`);
+  }
+
+  const dependsOn = task.dependsOn ?? [];
+  const dependents = tasks.filter((t) => (t.dependsOn ?? []).includes(taskId));
+
+  // Layer from phase
+  const layerMap: Record<string, string> = {
+    explore: "exploration",
+    plan: "planning",
+    assess: "assessment",
+    execute: "execution",
+    verify: "verification",
+    analyze: "analysis",
+    write: "documentation",
+    "": "unknown",
+  };
+  const layer = layerMap[task.adaptive?.phase ?? ""] ?? "unknown";
+
+  // Why it exists
+  let why = `Part of ${manifest.team ?? "unknown"} team workflow.`;
+  if (dependsOn.length > 0) {
+    const depTasks = dependsOn.map((d) => {
+      const dep = tasks.find((t) => t.id === d);
+      return dep ? `\`${d}\` (${dep.status})` : `\`${d}\``;
+    }).join(", ");
+    why += ` Depends on ${depTasks}.`;
+  }
+  if (dependents.length > 0) {
+    why += ` ${dependents.length} task(s) depend on this.`;
+  }
+
+  // What it did
+  let what = `Ran agent: ${task.role}`;
+  if (task.model) {
+    what += ` (${task.model})`;
+  }
+  if (task.usage) {
+    const inputTokens = task.usage.input ?? 0;
+    const outputTokens = task.usage.output ?? 0;
+    what += `. Usage: input=${inputTokens}, output=${outputTokens}`;
+  }
+  if (task.status === "failed") {
+    what += `. Status: FAILED`;
+    if (task.error) {
+      what += ` — ${task.error}`;
+    }
+  }
+
+  // Files from artifacts
+  const artifactsPath = manifest.artifactsRoot;
+  const filesTouched: string[] = [];
+  if (fs.existsSync(artifactsPath)) {
+    try {
+      const entries = fs.readdirSync(artifactsPath);
+      for (const entry of entries) {
+        const fullPath = path.join(artifactsPath, entry);
+        try {
+          if (fs.statSync(fullPath).isFile()) {
+            filesTouched.push(entry);
+          }
+        } catch { /* ignore */ }
+      }
+    } catch { /* ignore */ }
+  }
+
+  // Duration
+  let duration: number | undefined;
+  if (task.startedAt && task.finishedAt) {
+    duration = (new Date(task.finishedAt).getTime() - new Date(task.startedAt).getTime()) / 1000;
+  }
+
+  // Complexity
+  const complexity = tasks.length <= 3 ? "simple" : tasks.length <= 8 ? "moderate" : "complex";
+
+  return {
+    taskId,
+    role: task.role,
+    status: task.status,
+    phase: task.adaptive?.phase,
+    why,
+    what,
+    filesTouched,
+    connectedTasks: [
+      ...dependsOn.map((d) => {
+        const dep = tasks.find((t) => t.id === d);
+        return {
+          taskId: d,
+          status: dep?.status ?? "unknown",
+          relation: "depends on",
+        };
+      }),
+      ...dependents.map((d) => ({
+        taskId: d.id,
+        status: d.status,
+        relation: "depended on by",
+      })),
+    ],
+    layer,
+    complexity,
+    usage: task.usage ? { inputTokens: task.usage.input, outputTokens: task.usage.output } : undefined,
+    duration,
+  };
+}
+
+/**
+ * Format task explain context as markdown.
+ */
+export function formatTaskExplain(ctx: TaskExplainContext): string {
+  const lines: string[] = [];
+
+  lines.push(`# Task: ${ctx.taskId} (${ctx.role})`);
+  lines.push("");
+  lines.push(`| | |`);
+  lines.push(`|---|---|`);
+  lines.push(`| **Status** | ${ctx.status} |`);
+  if (ctx.phase) lines.push(`| **Phase** | ${ctx.phase} |`);
+  lines.push(`| **Layer** | ${ctx.layer} |`);
+  lines.push(`| **Complexity** | ${ctx.complexity} |`);
+
+  if (ctx.duration) {
+    const minutes = Math.round(ctx.duration / 60);
+    lines.push(`| **Duration** | ${minutes} min |`);
+  }
+
+  if (ctx.usage) {
+    const input = ctx.usage.inputTokens ?? 0;
+    const output = ctx.usage.outputTokens ?? 0;
+    lines.push(`| **Usage** | ↑${input} ↓${output} tokens |`);
+  }
+
+  lines.push("");
+  lines.push(`## Why it exists`);
+  lines.push("");
+  lines.push(ctx.why);
+  lines.push("");
+  lines.push(`## What it did`);
+  lines.push("");
+  lines.push(ctx.what);
+  lines.push("");
+
+  if (ctx.filesTouched.length > 0) {
+    lines.push("## Files produced");
+    lines.push("");
+    for (const file of ctx.filesTouched) {
+      lines.push(`- \`${file}\``);
+    }
+    lines.push("");
+  }
+
+  if (ctx.connectedTasks.length > 0) {
+    lines.push("## Connected tasks");
+    lines.push("");
+    for (const conn of ctx.connectedTasks) {
+      lines.push(`- ${conn.relation} \`${conn.taskId}\` (${conn.status})`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Handle team action='explain'.
+ */
+export function handleExplain(params: {
+  runId?: string;
+  taskId?: string;
+  cwd?: string;
+}, cwd: string): { isError: boolean; text: string } {
+  if (!params.runId) {
+    return result("explain requires runId", { action: "explain", status: "error" }, true);
+  }
+
+  const loaded = loadRunManifestById(cwd, params.runId);
+  if (!loaded) {
+    return result(`Run '${params.runId}' not found.`, { action: "explain", status: "error" }, true);
+  }
+
+  const { manifest, tasks } = loaded;
+
+  if (params.taskId) {
+    try {
+      const ctx = buildTaskExplainContext(manifest, tasks, params.taskId);
+      const output = formatTaskExplain(ctx);
+      return result(output, { action: "explain", runId: params.runId }, false);
+    } catch (err) {
+      return result(`Task '${params.taskId}' not found: ${err instanceof Error ? err.message : String(err)}`, { action: "explain", status: "error" }, true);
+    }
+  }
+
+  // Explain entire run
+  const lines: string[] = [];
+  lines.push(`# Run: ${params.runId}`);
+  lines.push("");
+  lines.push(`| | |`);
+  lines.push(`|---|---|`);
+
+  const start = new Date(manifest.createdAt).getTime();
+  const end = manifest.updatedAt ? new Date(manifest.updatedAt).getTime() : Date.now();
+  const duration = Math.round((end - start) / 1000 / 60);
+
+  lines.push(`| **Team** | ${manifest.team} |`);
+  lines.push(`| **Workflow** | ${manifest.workflow ?? "default"} |`);
+  lines.push(`| **Status** | ${manifest.status} |`);
+  lines.push(`| **Duration** | ${duration} min |`);
+  lines.push(`| **Tasks** | ${tasks.length} |`);
+  lines.push("");
+
+  lines.push("## Tasks");
+  lines.push("");
+  lines.push("| Task | Role | Status | Layer |");
+  lines.push("|------|------|--------|-------|");
+
+  for (const task of tasks) {
+    const layerMap: Record<string, string> = {
+      explore: "exploration", plan: "planning", assess: "assessment",
+      execute: "execution", verify: "verification", analyze: "analysis", write: "documentation",
+    };
+    const layer = layerMap[task.adaptive?.phase ?? ""] ?? "unknown";
+    const statusIcon = task.status === "completed" ? "✅" : task.status === "failed" ? "❌" : "⏳";
+    lines.push(`| \`${task.id}\` | ${task.role} | ${statusIcon} ${task.status} | ${layer} |`);
+  }
+  lines.push("");
+
+  lines.push("---");
+  lines.push(`*Use \`team action='explain' runId=${params.runId} taskId=<taskId>\` for task detail.*`);
+
+  return result(lines.join("\n"), { action: "explain", runId: params.runId }, false);
+}

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

@@ -1,4 +1,5 @@
 import { allAgents, discoverAgents } from "../../agents/discover-agents.ts";
+import { ensureCrewDirectory } from "../../state/crew-init.ts";
 import { allTeams, discoverTeams } from "../../teams/discover-teams.ts";
 import { allWorkflows, discoverWorkflows } from "../../workflows/discover-workflows.ts";
 import { loadConfig } from "../../config/config.ts";
@@ -74,6 +75,9 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 	if (!goal) return result("Run requires goal or task.", { action: "run", status: "error" }, true);
 	const intentPrefix = goal.length > 60 ? `${goal.slice(0, 57)}...` : goal;
 
+	// P0: Ensure .crew directory structure exists before creating any manifests.
+	await ensureCrewDirectory(ctx.cwd);
+
 	const teams = allTeams(discoverTeams(ctx.cwd));
 	const workflows = allWorkflows(discoverWorkflows(ctx.cwd));
 	const agents = allAgents(discoverAgents(ctx.cwd));

package/src/extension/team-tool.ts

@@ -129,12 +129,15 @@ async function handleRun(
 import { waitForRun } from "../runtime/run-tracker.ts";
 import { normalizeSkillOverride } from "../runtime/skill-instructions.ts";
 import { logInternalError } from "../utils/internal-error.ts";
+import { searchAgents, searchTeams } from "../utils/bm25-search.ts";
+import { projectCrewRoot } from "../utils/paths.ts";
 import {
 	type CacheControlDeps,
 	invalidateSnapshot,
 } from "./team-tool/cache-control.ts";
 import { handleCancel, handleRetry } from "./team-tool/cancel.ts";
 import { handleDoctor } from "./team-tool/doctor.ts";
+import { handleExplain } from "./team-tool/explain.ts";
 import { handleHealthMonitor } from "./team-tool/health-monitor.ts";
 import {
 	handleArtifacts,
@@ -150,6 +153,17 @@ import {
 	handlePrune,
 	handleWorktrees,
 } from "./team-tool/lifecycle-actions.ts";
+import {
+	getCachedRun,
+	computeRunCacheKey,
+	getCacheStats,
+} from "../state/run-cache.ts";
+import {
+	loadRunGraph,
+	listRunGraphs,
+} from "../state/run-graph.ts";
+import { FileCheckpointStore } from "../runtime/checkpoint.ts";
+import { buildTeamOnboarding } from "./team-onboard.ts";
 import { handleParallel } from "./team-tool/parallel-dispatch.ts";
 import { handlePlan } from "./team-tool/plan.ts";
 import { handleRespond } from "./team-tool/respond.ts";
@@ -1089,6 +1103,97 @@ export async function handleTeamTool(
 			return handleHealthMonitor(ctx, params);
 		case "wait":
 			return handleWait(params, ctx);
+		case "graph": {
+			if (params.runId) {
+				const graph = loadRunGraph(ctx.cwd, params.runId);
+				return result(
+					graph ? JSON.stringify(graph, null, 2) : "No graph found for this run.",
+					{ action: "graph", status: graph ? "ok" : "error" },
+					!graph,
+				);
+			}
+			const graphs = listRunGraphs(ctx.cwd);
+			return result(
+				graphs.length ? `Available graphs:\n${graphs.join("\n")}` : "No graphs available.",
+				{ action: "graph", status: "ok" },
+			);
+		}
+		case "search": {
+			const query = params.goal ?? params.task ?? "";
+			if (!query) {
+				return result("Search requires goal or task query.", { action: "search", status: "error" }, true);
+			}
+			try {
+				const [agentResults, teamResults] = await Promise.all([
+					searchAgents(query, { limit: 5 }),
+					searchTeams(query, { limit: 3 }),
+				]);
+				const lines: string[] = [];
+				if (teamResults.length) {
+					lines.push("## Teams");
+					for (const r of teamResults) {
+						lines.push(`- [${r.team.name}] score=${r.score.toFixed(2)}: ${r.team.description ?? "(no description)"}`);
+					}
+				}
+				if (agentResults.length) {
+					lines.push("## Agents");
+					for (const r of agentResults) {
+						lines.push(`- [${r.agent.name}] score=${r.score.toFixed(2)}: ${r.agent.description ?? "(no description)"}`);
+					}
+				}
+				return result(lines.length ? lines.join("\n") : "No results found.", { action: "search", status: "ok" });
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				return result(`Search failed: ${msg}`, { action: "search", status: "error" }, true);
+			}
+		}
+		case "onboard": {
+			const team = params.team ?? "default";
+			const onboarding = buildTeamOnboarding(team, ctx.cwd);
+			return result(onboarding, { action: "onboard", status: "ok" });
+		}
+		case "explain": {
+			const explainResult = handleExplain(params, ctx.cwd);
+			return result(explainResult.text, { action: "explain", status: explainResult.isError ? "error" : "ok" }, explainResult.isError);
+		}
+		case "cache": {
+			if (params.goal) {
+				const key = computeRunCacheKey(
+					params.goal,
+					params.team ?? "default",
+					params.workflow ?? "default",
+					ctx.cwd,
+				);
+				const cached = getCachedRun(ctx.cwd, key);
+				if (cached) {
+					return result(
+						`Cached run found (${new Date(cached.cachedAt).toISOString()}): runId=${cached.runId}, status=${cached.status}, ${cached.tasks.length} tasks`,
+						{ action: "cache", status: "ok", data: { cacheKey: key, cacheHit: true, runId: cached.runId, status: cached.status, taskCount: cached.tasks.length } },
+					);
+				}
+				return result(`No cached result for key: ${key}`, { action: "cache", status: "ok", data: { cacheKey: key, cacheHit: false } });
+			}
+			const stats = getCacheStats(ctx.cwd);
+			return result(
+				`Cache stats: ${stats.entries} entries, ${stats.sizeBytes} bytes`,
+				{ action: "cache", status: "ok" },
+			);
+		}
+		case "checkpoint": {
+			if (!params.runId || !params.taskId) {
+				return result("Checkpoint requires runId and taskId.", { action: "checkpoint", status: "error" }, true);
+			}
+			const stateRoot = path.join(projectCrewRoot(ctx.cwd), "state", "runs", params.runId);
+			const store = new FileCheckpointStore(stateRoot);
+			const checkpoint = store.load(params.runId, params.taskId);
+			if (!checkpoint) {
+				return result("No checkpoint found.", { action: "checkpoint", status: "error" }, true);
+			}
+			return result(
+				`Checkpoint: step=${checkpoint.step}, progress=${checkpoint.progress}, savedAt=${new Date(checkpoint.savedAt).toISOString()}`,
+				{ action: "checkpoint", status: "ok", data: { checkpoint } },
+			);
+		}
 		default:
 			return result(
 				`Unknown action: ${action}`,