@phi-code-admin/phi-code 0.78.0 → 0.80.0

package/extensions/phi/commit.ts

@@ -0,0 +1,253 @@
+/**
+ * Commit Extension - /commit command for deterministic, LLM-free git commits.
+ *
+ * Inspired by examples/extensions/auto-commit-on-exit.ts, but exposed as an
+ * explicit user command and hardened with a strict safety protocol. There is
+ * NO model call anywhere in this file: the commit message is derived purely
+ * from git state and the local session, so the result is fully reproducible
+ * and never depends on a flaky structured-output proxy.
+ *
+ * Usage:
+ *   /commit                  : commit what is already staged (no auto-staging)
+ *   /commit <message>        : commit already-staged changes with that message
+ *   /commit --all            : stage everything (git add -A) then commit
+ *   /commit --all <message>  : stage everything then commit with that message
+ *
+ * Message format: always prefixed with "[phi] ". When the user passes a
+ * message it is used verbatim after the prefix. Otherwise the message is
+ * derived deterministically from the staged files (git diff --staged --stat /
+ * git status) plus the first line of the last assistant message when present.
+ *
+ * Safety protocol (strict):
+ *   - Refuses to commit if a sensitive file is staged (.env, *.pem, *secret*,
+ *     id_rsa). The user is warned and nothing is committed.
+ *   - Never uses --amend.
+ *   - Only stages with `git add -A` when --all is passed; otherwise it commits
+ *     strictly what is already in the index.
+ *   - The message is passed via a single pi.exec("git", ["commit", "-m", msg])
+ *     call: no shell string interpolation, robust cross-OS.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "phi-code";
+
+/** Max length of the derived subject line (without the "[phi] " prefix). */
+const MAX_SUBJECT_LENGTH = 60;
+
+/** Max number of file names listed in an auto-derived commit message. */
+const MAX_LISTED_FILES = 3;
+
+/**
+ * Patterns for files that must never be committed by this command.
+ * Matched against the path of each staged file (case-insensitive on basename).
+ */
+const SENSITIVE_PATTERNS: { label: string; test: (path: string) => boolean }[] = [
+	{
+		label: ".env file",
+		test: (p) => {
+			const base = basename(p).toLowerCase();
+			return base === ".env" || base.startsWith(".env.");
+		},
+	},
+	{ label: "PEM/key file", test: (p) => p.toLowerCase().endsWith(".pem") },
+	{ label: "secret-named file", test: (p) => basename(p).toLowerCase().includes("secret") },
+	{ label: "SSH private key", test: (p) => basename(p).toLowerCase() === "id_rsa" },
+];
+
+/** Return the last path segment, tolerating both / and \ separators. */
+function basename(path: string): string {
+	const normalized = path.replace(/\\/g, "/");
+	const idx = normalized.lastIndexOf("/");
+	return idx === -1 ? normalized : normalized.slice(idx + 1);
+}
+
+/**
+ * Parse `git status --porcelain` output into staged file paths.
+ *
+ * Porcelain v1 lines are "XY <path>" where X is the index (staged) status.
+ * A file is considered staged when X is not a space and not "?" (untracked).
+ * Rename entries use "orig -> dest"; we keep the destination path.
+ */
+function parseStagedFiles(porcelain: string): string[] {
+	const files: string[] = [];
+	for (const rawLine of porcelain.split("\n")) {
+		const line = rawLine.replace(/\r$/, "");
+		if (line.length < 4) {
+			continue;
+		}
+		const indexStatus = line[0];
+		if (indexStatus === " " || indexStatus === "?") {
+			continue;
+		}
+		let pathPart = line.slice(3).trim();
+		const renameSep = pathPart.indexOf(" -> ");
+		if (renameSep !== -1) {
+			pathPart = pathPart.slice(renameSep + 4).trim();
+		}
+		// Porcelain quotes paths containing special chars; strip surrounding quotes.
+		if (pathPart.startsWith('"') && pathPart.endsWith('"')) {
+			pathPart = pathPart.slice(1, -1);
+		}
+		if (pathPart.length > 0) {
+			files.push(pathPart);
+		}
+	}
+	return files;
+}
+
+/** Find the first sensitive file among the staged paths, if any. */
+function findSensitiveFile(stagedFiles: string[]): { path: string; label: string } | undefined {
+	for (const path of stagedFiles) {
+		for (const pattern of SENSITIVE_PATTERNS) {
+			if (pattern.test(path)) {
+				return { path, label: pattern.label };
+			}
+		}
+	}
+	return undefined;
+}
+
+/** Extract the first line of the last assistant message from the session. */
+function lastAssistantFirstLine(ctx: ExtensionCommandContext): string {
+	const entries = ctx.sessionManager.getEntries();
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i];
+		if (entry.type !== "message" || entry.message.role !== "assistant") {
+			continue;
+		}
+		const content = entry.message.content;
+		let text = "";
+		if (typeof content === "string") {
+			text = content;
+		} else if (Array.isArray(content)) {
+			text = content
+				.filter((c): c is { type: "text"; text: string } => c?.type === "text" && typeof c.text === "string")
+				.map((c) => c.text)
+				.join("\n");
+		}
+		const firstLine = text.split("\n").find((l) => l.trim().length > 0);
+		return firstLine ? firstLine.trim() : "";
+	}
+	return "";
+}
+
+/** Collapse whitespace and clamp to MAX_SUBJECT_LENGTH with an ellipsis. */
+function clampSubject(text: string): string {
+	const collapsed = text.replace(/\s+/g, " ").trim();
+	if (collapsed.length <= MAX_SUBJECT_LENGTH) {
+		return collapsed;
+	}
+	return `${collapsed.slice(0, MAX_SUBJECT_LENGTH - 3)}...`;
+}
+
+/**
+ * Build a deterministic subject derived from the staged files plus the first
+ * line of the last assistant message. No LLM involved.
+ */
+function deriveSubject(stagedFiles: string[], assistantHint: string): string {
+	const names = stagedFiles.map(basename);
+	let filesPart: string;
+	if (names.length === 0) {
+		filesPart = "changes";
+	} else if (names.length <= MAX_LISTED_FILES) {
+		filesPart = names.join(", ");
+	} else {
+		const shown = names.slice(0, MAX_LISTED_FILES).join(", ");
+		filesPart = `${shown} (+${names.length - MAX_LISTED_FILES} more)`;
+	}
+
+	const hint = assistantHint.trim();
+	const subject = hint.length > 0 ? `update ${filesPart}: ${hint}` : `update ${filesPart}`;
+	return clampSubject(subject);
+}
+
+export default function commitExtension(pi: ExtensionAPI) {
+	pi.registerCommand("commit", {
+		description: "Deterministically commit staged changes ([phi] prefix, no LLM). Use --all to stage everything first.",
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			try {
+				// 1. Parse args: extract the --all flag, keep the rest as the message.
+				const tokens = args.trim().split(/\s+/).filter(Boolean);
+				const stageAll = tokens.includes("--all");
+				const userMessage = tokens.filter((t) => t !== "--all").join(" ").trim();
+
+				// 2. Confirm we are inside a git repo with changes.
+				const status = await pi.exec("git", ["status", "--porcelain"], { cwd: ctx.cwd });
+				if (status.code !== 0) {
+					ctx.ui.notify(
+						"Not a git repository (or git unavailable). Nothing to commit.",
+						"warning",
+					);
+					return;
+				}
+				if (status.stdout.trim().length === 0) {
+					ctx.ui.notify("Working tree clean: nothing to commit.", "info");
+					return;
+				}
+
+				// 3. Optionally stage everything (only when explicitly requested).
+				if (stageAll) {
+					const add = await pi.exec("git", ["add", "-A"], { cwd: ctx.cwd });
+					if (add.code !== 0) {
+						ctx.ui.notify(`git add -A failed: ${add.stderr.trim() || "unknown error"}`, "error");
+						return;
+					}
+				}
+
+				// 4. Re-read status to know exactly what is staged after any add.
+				const afterStatus = await pi.exec("git", ["status", "--porcelain"], { cwd: ctx.cwd });
+				const stagedFiles = parseStagedFiles(afterStatus.stdout);
+				if (stagedFiles.length === 0) {
+					ctx.ui.notify(
+						"No staged changes to commit. Stage files first, or run `/commit --all`.",
+						"warning",
+					);
+					return;
+				}
+
+				// 5. Safety protocol: refuse if a sensitive file is staged.
+				const sensitive = findSensitiveFile(stagedFiles);
+				if (sensitive) {
+					ctx.ui.notify(
+						`Refusing to commit: sensitive ${sensitive.label} is staged (\`${sensitive.path}\`). ` +
+							`Unstage it with \`git restore --staged ${sensitive.path}\` before committing.`,
+						"error",
+					);
+					return;
+				}
+
+				// 6. Build the deterministic message.
+				let subject: string;
+				if (userMessage.length > 0) {
+					subject = userMessage;
+				} else {
+					const hint = lastAssistantFirstLine(ctx);
+					subject = deriveSubject(stagedFiles, hint);
+				}
+				const message = `[phi] ${subject}`;
+
+				// 7. Commit via a single exec call (no shell, no --amend).
+				const commit = await pi.exec("git", ["commit", "-m", message], { cwd: ctx.cwd });
+				if (commit.code !== 0) {
+					ctx.ui.notify(
+						`git commit failed: ${commit.stderr.trim() || commit.stdout.trim() || "unknown error"}`,
+						"error",
+					);
+					return;
+				}
+
+				// 8. Report the result with the short hash.
+				const rev = await pi.exec("git", ["rev-parse", "--short", "HEAD"], { cwd: ctx.cwd });
+				const shortHash = rev.code === 0 ? rev.stdout.trim() : "(unknown)";
+				ctx.ui.notify(
+					`Committed ${shortHash}: ${message} (${stagedFiles.length} file${stagedFiles.length === 1 ? "" : "s"}).`,
+					"info",
+				);
+			} catch (err) {
+				ctx.ui.notify(
+					`/commit error: ${err instanceof Error ? err.message : String(err)}`,
+					"error",
+				);
+			}
+		},
+	});
+}

package/extensions/phi/memory.ts

@@ -64,6 +64,113 @@ function withFrontmatter(content: string, name: string): string {
 	return `---\nname: "${name}"\ndescription: "${description}"\n---\n\n${content}`;
 }
 
+/** Hard caps for the deterministic recall manifest (no LLM involved). */
+const MANIFEST_MAX_ENTRIES = 40;
+const MANIFEST_MAX_CHARS = 2000;
+const MANIFEST_DESC_MAX = 100;
+// Chars reserved for the trailing "… (N notes total …)" overflow line so the
+// final manifest still respects MANIFEST_MAX_CHARS once it is appended.
+const MANIFEST_OVERFLOW_RESERVE = 96;
+
+/**
+ * Extract a one-line summary for a single note file, deterministically.
+ *
+ * Prefers the YAML frontmatter `description:` field (written by
+ * withFrontmatter). Falls back to the first non-empty, non-frontmatter line.
+ * Returns a trimmed, single-line string truncated to MANIFEST_DESC_MAX chars.
+ */
+function summarizeNote(content: string): string {
+	const text = content.replace(/\r\n/g, "\n");
+	let body = text;
+
+	// If a frontmatter block is present, scan it for a description first.
+	if (text.startsWith("---\n")) {
+		const end = text.indexOf("\n---", 4);
+		if (end !== -1) {
+			const fm = text.slice(4, end);
+			for (const rawLine of fm.split("\n")) {
+				const m = rawLine.match(/^\s*description\s*:\s*(.+?)\s*$/);
+				if (m) {
+					// Strip surrounding quotes if present.
+					const value = m[1].replace(/^["']|["']$/g, "").trim();
+					if (value) return collapseLine(value);
+				}
+			}
+			// No description in frontmatter: summarize the body that follows it.
+			body = text.slice(end + 4);
+		}
+	}
+
+	for (const rawLine of body.split("\n")) {
+		const line = rawLine.replace(/^#+\s*/, "").trim();
+		if (line && line !== "---") {
+			return collapseLine(line);
+		}
+	}
+	return "";
+}
+
+/** Collapse internal whitespace to single spaces and truncate cleanly. */
+function collapseLine(value: string): string {
+	const flat = value.replace(/\s+/g, " ").trim();
+	return flat.length > MANIFEST_DESC_MAX ? `${flat.slice(0, MANIFEST_DESC_MAX - 1).trimEnd()}…` : flat;
+}
+
+/**
+ * Build a deterministic one-line-per-file manifest of all memory notes.
+ *
+ * Purely local: lists note files and reads their frontmatter / first line.
+ * No LLM call, no vector search. Bounded to MANIFEST_MAX_ENTRIES entries and
+ * MANIFEST_MAX_CHARS characters so it stays cheap to inject every turn.
+ *
+ * Returns an empty string when there are no notes, so callers can skip
+ * injection entirely.
+ */
+function buildMemoryManifest(sigmaMemory: SigmaMemory): string {
+	let files: Array<{ name: string; size: number; date: string }>;
+	try {
+		files = sigmaMemory.notes.list();
+	} catch {
+		return "";
+	}
+	if (files.length === 0) {
+		return "";
+	}
+
+	const lines: string[] = [];
+	let total = 0;
+	let truncated = false;
+
+	for (const file of files) {
+		if (lines.length >= MANIFEST_MAX_ENTRIES) {
+			truncated = true;
+			break;
+		}
+		let summary = "";
+		try {
+			summary = summarizeNote(sigmaMemory.notes.read(file.name));
+		} catch {
+			// Unreadable note: still list its name so the model knows it exists.
+			summary = "";
+		}
+		const entry = summary ? `- ${file.name}: ${summary}` : `- ${file.name}`;
+		if (total + entry.length + 1 > MANIFEST_MAX_CHARS - MANIFEST_OVERFLOW_RESERVE) {
+			truncated = true;
+			break;
+		}
+		lines.push(entry);
+		total += entry.length + 1;
+	}
+
+	if (lines.length === 0) {
+		return "";
+	}
+	if (truncated || lines.length < files.length) {
+		lines.push(`- … (${files.length} notes total; use memory_read/memory_search for full content)`);
+	}
+	return lines.join("\n");
+}
+
 export default function memoryExtension(pi: ExtensionAPI) {
 	// Initialize sigma-memory with embedded vector store
 	const sigmaMemory = new SigmaMemory();
@@ -244,8 +351,19 @@ export default function memoryExtension(pi: ExtensionAPI) {
 						)
 						.join("\n");
 
+					// Lead with the deterministic recall manifest (file + summary)
+					// so a no-arg memory_read surfaces what each note contains, not
+					// just file names. Falls back gracefully when empty.
+					const manifest = buildMemoryManifest(sigmaMemory);
+					const manifestSection = manifest ? `## Memory index (summaries)\n\n${manifest}\n\n` : "";
+
 					return {
-						content: [{ type: "text", text: `Available memory files (${files.length}):\n\n${fileList}` }],
+						content: [
+							{
+								type: "text",
+								text: `${manifestSection}## Available memory files (${files.length})\n\n${fileList}`,
+							},
+						],
 						details: { action: "list", fileCount: files.length },
 					};
 				}
@@ -529,10 +647,19 @@ export default function memoryExtension(pi: ExtensionAPI) {
 		// Neutralize angle brackets so user content cannot close the
 		// <system-reminder> block early and inject trusted instructions.
 		const safe = truncated.replace(/[<>]/g, (c) => (c === "<" ? "&lt;" : "&gt;")).replace(/"/g, '\\"');
+
+		// Deterministic recall index: a one-line-per-file manifest of memory
+		// notes so the model ALWAYS sees which facts exist without having to
+		// guess and call memory_search blindly. Built locally (no LLM).
+		const manifest = buildMemoryManifest(sigmaMemory);
+		const manifestBlock = manifest
+			? `\nMEMORY INDEX (existing saved notes, read with \`memory_read <file>\`):\n${manifest}\n`
+			: "";
+
 		const reminder = `<system-reminder>
 You are about to respond to a new user message:
 "${safe}"
-
+${manifestBlock}
 REMINDER (project rule, applies every turn):
 1. Call \`memory_search\` FIRST with keywords from the user's intent. Recent
    project context, prior decisions, and saved learnings are accessible

package/extensions/phi/orchestrator.ts

@@ -20,14 +20,14 @@ import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI } from "phi-code";
 import { writeFile, mkdir, readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import {
 	extractBlockingFindings,
 	extractHandoff,
 	isTransientError,
 	parsePhaseVerdict,
-} from "./orchestrator-helpers.js";
+} from "./providers/orchestrator-helpers.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -152,6 +152,7 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 			if (orchestrationActive) {
 				return {
 					content: [{ type: "text", text: "⚠️ Orchestration is already active via /plan. Do NOT call orchestrate during /plan phases. Follow the phase instructions instead." }],
+					details: undefined,
 				};
 			}
 
@@ -229,6 +230,9 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 		// When true, switchModelForPhase resolves the fallback model first (used on retry
 		// to swap to a different model family rather than re-hit the one that just failed).
 		useFallback?: boolean;
+		// 0..4 for the five base phases (explore..review); undefined for synthetic
+		// phases (the review fix + re-review). Used to checkpoint resume position.
+		baseIndex?: number;
 	}
 
 	let phaseQueue: OrchestratorPhase[] = [];
@@ -251,6 +255,8 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 	let currentPhase: OrchestratorPhase | null = null;
 	// Timestamp shared by all phase report file names in the current run.
 	let currentRunTs = "";
+	// The original /plan description, kept so a checkpoint can be resumed.
+	let currentDescription = "";
 	// Hard cap: at most one REVIEW->fix->re-REVIEW cycle per run.
 	let reviewFixRounds = 0;
 	// Set true right before an INTERNAL ctx.abort() (phase timeout) so the
@@ -266,6 +272,41 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 		return null;
 	}
 
+	// ─── Resume checkpoint ───────────────────────────────────────────────
+	// A tiny JSON marker tracking POSITION in the 5 base phases, so a crashed /
+	// aborted orchestration can be resumed with `/plan --resume`. The handoff .md
+	// files hold the real content; this only records where to pick up.
+	function checkpointPath(): string {
+		return join(process.cwd(), ".phi", "plans", "orchestration-state.json");
+	}
+	function writeCheckpoint(nextBaseIndex: number): void {
+		try {
+			if (nextBaseIndex >= 5) { clearCheckpoint(); return; }
+			writeFileSync(
+				checkpointPath(),
+				JSON.stringify({ description: currentDescription, ts: currentRunTs, nextBaseIndex }, null, 2),
+				"utf-8",
+			);
+		} catch { /* best effort */ }
+	}
+	function readCheckpoint(): { description: string; ts: string; nextBaseIndex: number } | null {
+		try {
+			const p = checkpointPath();
+			if (!existsSync(p)) return null;
+			const c = JSON.parse(readFileSync(p, "utf-8"));
+			if (typeof c?.description === "string" && typeof c?.ts === "string" && typeof c?.nextBaseIndex === "number") {
+				return c;
+			}
+		} catch { /* ignore */ }
+		return null;
+	}
+	function clearCheckpoint(): void {
+		try {
+			const p = checkpointPath();
+			if (existsSync(p)) unlinkSync(p);
+		} catch { /* best effort */ }
+	}
+
 	/**
 	 * Common rules appended to every phase instruction. Pure prompt (zero latency,
 	 * robust to the proxy): honest reporting, autonomous operation, a canonical
@@ -321,7 +362,7 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 	 * Load routing config and build phase queue with model assignments + agent definitions.
 	 * Each phase now reads outputs from previous phases and writes structured outputs.
 	 */
-	function buildPhases(description: string): OrchestratorPhase[] {
+	function buildPhases(description: string, tsOverride?: string): OrchestratorPhase[] {
 		const routingPath = join(homedir(), ".phi", "agent", "routing.json");
 		let routing: any = { routes: {}, default: { model: "default" } };
 		try {
@@ -342,15 +383,15 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 		const test = getModel("test");
 		const review = getModel("review");
 
-		const ts = timestamp();
-		currentRunTs = ts; // shared by all phase report file names this run
+		const ts = tsOverride || timestamp();
+		currentRunTs = ts; // shared by all phase report file names this run (or resumed)
 		// Inject runtime info so agents can adapt to the host OS
 		const shellNote = process.platform === 'win32'
 			? `\nShell: bash (Git Bash), NOT cmd.exe. Always use Unix syntax: rm not del, test -f not if exist, / not \\\\`
 			: '';
 		const runtimeInfo = `\n\nRuntime: ${process.platform} (${process.arch})${shellNote}`;
 
-		return [
+		const phases: OrchestratorPhase[] = [
 			{
 				key: "explore", label: "🔍 Phase 1 — EXPLORE", model: explore.preferred, fallback: explore.fallback,
 				agent: loadAgentDef("explore"),
@@ -573,7 +614,7 @@ After testing, use \`memory_write\` to save test results, bugs found, and lesson
 
 **Project Request:** ${description}
 
-**Step 1:** Get the diff to review. Run \`git diff\` (and \`git status\`) if it is a git repo; otherwise read the files listed in the progress/handoff reports. Skip test/fixture hunks.
+**Step 1:** Get the diff to review. Run \`git diff\` and \`git diff --stat\` (and \`git status\`) if it is a git repo; otherwise read the files listed in the progress/handoff reports. Skip test/fixture hunks. **Scale your effort to the diff size:** a small diff (under ~50 changed lines) gets one focused precision pass, bias to high confidence, at most 4 findings; a large diff gets all three angles below plus the verification step. Never spend so long that you risk the phase time limit.
 **Step 2:** Review in SEQUENTIAL ANGLES (do all in this one turn, no sub-agents). Collect raw candidates first, judge after:
    - **Angle 1 - Correctness:** read the diff line by line. What behaviour did it change or remove? Off-by-one, null/undefined, wrong condition, broken invariant.
    - **Angle 2 - Cross-file:** grep the callers and callees of changed symbols. Did a signature/return/contract change break a caller elsewhere?
@@ -615,6 +656,8 @@ Tag the note with relevant keywords for vector search.
 - Save any new architectural decisions or patterns discovered` + runtimeInfo + COMMON_PHASE_RULES,
 			},
 		];
+		phases.forEach((p, i) => { p.baseIndex = i; });
+		return phases;
 	}
 
 	/**
@@ -684,13 +727,14 @@ Tag the note with relevant keywords for vector search.
 			savedTools = pi.getActiveTools();
 		}
 		if (phase.agent) {
+			const agentDef = phase.agent;
 			// Set agent's system prompt (will be injected via before_agent_start)
-			activeAgentPrompt = phase.agent.systemPrompt;
+			activeAgentPrompt = agentDef.systemPrompt;
 			// Restrict tools to agent's allowed tools
-			if (phase.agent.tools.length > 0) {
+			if (agentDef.tools.length > 0) {
 				// Always include memory tools in orchestration phases
 				const memoryTools = ['memory_search', 'memory_write', 'memory_read', 'ontology_add', 'ontology_query'];
-				const agentTools = [...phase.agent.tools, ...memoryTools.filter(t => !phase.agent.tools.includes(t))];
+				const agentTools = [...agentDef.tools, ...memoryTools.filter(t => !agentDef.tools.includes(t))];
 				activeAgentTools = agentTools;
 				pi.setActiveTools(agentTools);
 			} else if (savedTools) {
@@ -752,6 +796,7 @@ Tag the note with relevant keywords for vector search.
 			// All phases done — clean up and notify
 			setOrchestrationActive(false);
 			phasePending = false;
+			clearCheckpoint();
 			deactivateAgent();
 			// Restore the user's model so /plan does not overwrite their /model choice.
 			if (originalModel) {
@@ -883,14 +928,16 @@ Tag the note with relevant keywords for vector search.
 		const testResults: string[] = [];
 		let toolCallCount = 0;
 
-		for (const msg of messages) {
+		for (const rawMsg of messages) {
+			// Pi message variants are scanned dynamically; cast to a loose shape once.
+			const msg = rawMsg as { role?: string; content?: unknown; name?: string; toolName?: string; isError?: boolean };
 			// Pi uses role: "toolResult" instead of "tool"
 			if (msg.role === 'tool' || msg.role === 'function' || msg.role === 'toolResult') {
 				toolCallCount++;
 				const content = Array.isArray(msg.content)
 					? msg.content.map((c: any) => c.text || '').join('')
 					: String(msg.content || '');
-				const name = (msg as any).name || (msg as any).toolName || '';
+				const name = msg.name || msg.toolName || '';
 				// Track writes
 				if (name === 'write' && content.includes('Successfully wrote')) {
 					const match = content.match(/wrote \d+ bytes to (.+)/);
@@ -898,7 +945,7 @@ Tag the note with relevant keywords for vector search.
 				}
 				// Track edits — the edit tool returns "Successfully replaced N block(s) in <path>."
 				// Anchor the path capture so it does not over-capture unrelated text.
-				if (name === 'edit' && !content.includes('ERR') && !(msg as any).isError) {
+				if (name === 'edit' && !content.includes('ERR') && !msg.isError) {
 					const match = content.match(/replaced \d+ block\(s\) in (.+?)\.?$/m);
 					if (match) filesEdited.push(match[1]);
 				}
@@ -913,7 +960,7 @@ Tag the note with relevant keywords for vector search.
 				}
 				// Track test results
 				if (content.includes('PASS') || content.includes('✅') || content.includes('✗') || content.includes('❌')) {
-					const lines = content.split('\n').filter(l => /PASS|FAIL|✅|❌|✗/.test(l));
+					const lines = content.split('\n').filter((l: string) => /PASS|FAIL|✅|❌|✗/.test(l));
 					testResults.push(...lines.slice(0, 10));
 				}
 			}
@@ -1027,6 +1074,12 @@ Tag the note with relevant keywords for vector search.
 			}
 		} catch { /* verdict logic is best-effort */ }
 
+		// Checkpoint resume position after each base phase (synthetic fix/re-review
+		// phases have no baseIndex and do not advance it).
+		if (currentPhase && typeof currentPhase.baseIndex === "number") {
+			writeCheckpoint(currentPhase.baseIndex + 1);
+		}
+
 		// Phase complete — chain to next
 		completedPhases++;
 		phasePending = false;
@@ -1038,10 +1091,51 @@ Tag the note with relevant keywords for vector search.
 	pi.registerCommand("plan", {
 		description: "Plan AND execute a project — 5 phases, each with its own model from routing.json",
 		handler: async (args, ctx) => {
-			const description = args.trim();
+			const rawArgs = args.trim();
+
+			// Resume a crashed / aborted orchestration from its checkpoint.
+			if (/^(--resume|resume)\b/i.test(rawArgs)) {
+				const cp = readCheckpoint();
+				if (!cp) {
+					ctx.ui.notify("No orchestration checkpoint to resume. Start one with `/plan <description>`.", "warning");
+					return;
+				}
+				await ensurePlansDir();
+				currentDescription = cp.description;
+				// Reuse the saved timestamp so the rebuilt phases point at the same
+				// .phi/plans/*.md handoff files that the earlier run produced.
+				const rphases = buildPhases(cp.description, cp.ts);
+				const remaining = rphases.slice(Math.max(0, Math.min(5, cp.nextBaseIndex)));
+				if (remaining.length === 0) {
+					clearCheckpoint();
+					ctx.ui.notify("Checkpoint already complete — nothing to resume.", "info");
+					return;
+				}
+				setOrchestrationActive(true);
+				phasePending = true;
+				originalModel = ctx.model || null;
+				savedTools = pi.getActiveTools();
+				completedPhases = cp.nextBaseIndex;
+				skippedPhases = 0;
+				reviewFixRounds = 0;
+				internalAbort = false;
+				phaseStartTime = Date.now();
+				const firstResume = remaining[0];
+				currentPhase = firstResume;
+				phaseQueue = remaining.slice(1);
+				ctx.ui.notify(`📋 **Resuming orchestration** at ${firstResume.label} (${remaining.length} phase(s) left)\n`, "info");
+				const { modelId, warning } = await switchModelForPhase(firstResume, ctx);
+				activateAgent(firstResume, ctx);
+				ctx.ui.notify(`${firstResume.label} → \`${modelId}\``, "info");
+				if (warning) ctx.ui.notify(`\n⚠️ ${warning}`, "warning");
+				setTimeout(() => pi.sendUserMessage(firstResume.instruction, { deliverAs: "followUp" }), 200);
+				return;
+			}
+
+			const description = rawArgs;
 
 			if (!description) {
-				ctx.ui.notify(`**Usage:** \`/plan <project description>\`
+				ctx.ui.notify(`**Usage:** \`/plan <project description>\` (or \`/plan --resume\` to continue a checkpointed run)
 
 **Examples:**
   /plan Build a REST API for user authentication with JWT
@@ -1060,6 +1154,7 @@ Tag the note with relevant keywords for vector search.
 			await writeFile(join(plansDir, specFile), `# ${description}\n\n**Created:** ${new Date().toLocaleString()}\n`, "utf-8");
 
 			// Build phases with model assignments + agent definitions
+			currentDescription = description;
 			const phases = buildPhases(description);
 			phaseQueue = phases.slice(1); // Queue phases 2-5
 			setOrchestrationActive(true);
@@ -1072,9 +1167,9 @@ Tag the note with relevant keywords for vector search.
 			completedPhases = 0;
 			skippedPhases = 0;
 			reviewFixRounds = 0;
-			currentPhase = null;
 			internalAbort = false;
 			const firstPhase = phases[0];
+			currentPhase = firstPhase;
 
 			ctx.ui.notify(`📋 **Orchestrator started** — 5 phases with model routing + agent roles\n`, "info");