@phi-code-admin/phi-code 0.88.0 → 0.90.0

package/extensions/phi/orchestrator.ts

@@ -23,6 +23,9 @@ import { join } from "node:path";
 import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI } from "phi-code";
 import { type AgentDef, loadAgentDef } from "./providers/agent-def.js";
+import { buildVerifyInstruction, debugPhaseInstructions } from "./providers/debug-build-commands.js";
+import { type FailingState, parseFailingState } from "./providers/debug-contract.js";
+import { passed, tail } from "./providers/execution.js";
 import { defaultExplorerSpecs, READONLY_EXPLORER_TOOLS, runExploreFanout } from "./providers/explore-fanout.js";
 import {
 	analyzePhaseMessages,
@@ -31,6 +34,8 @@ import {
 	resolvePhaseOutcome,
 	type StructuredPhaseResult,
 } from "./providers/phase-machine.js";
+import { resolveSandbox, type Sandbox } from "./providers/sandbox.js";
+import { triage } from "./providers/triage.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -289,6 +294,10 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 
 	let phaseQueue: OrchestratorPhase[] = [];
 	let orchestrationActive = false;
+	// Which pipeline is running. "plan" keeps the existing 5-phase agent_end path
+	// untouched; "debug"/"build" are driven by the separate linear generic driver
+	// so /plan's fragile review-fix + "/5" logic is never engaged for them.
+	let orchestrationMode: "plan" | "debug" | "build" = "plan";
 	let activeAgentPrompt: string | null = null;
 	let _activeAgentTools: string[] | null = null;
 	let savedTools: string[] | null = null;
@@ -383,6 +392,66 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 		},
 	});
 
+	// ─── Execution sandbox — the guaranteed oracle ──────────────────
+	// Resolved once per cwd and cached (resolveSandbox probes the Docker daemon).
+	// This is what turns "the agent says it ran the test" into "a real container
+	// ran the test and here is its exit code".
+	let sessionSandbox: { cwd: string; sandbox: Sandbox } | null = null;
+	function getSessionSandbox(cwd: string): Sandbox {
+		if (!sessionSandbox || sessionSandbox.cwd !== cwd) {
+			sessionSandbox = { cwd, sandbox: resolveSandbox({ cwd }) };
+		}
+		return sessionSandbox.sandbox;
+	}
+
+	pi.registerTool({
+		name: "sandbox_run",
+		label: "Sandbox Run",
+		description:
+			"Run a command in the project's guaranteed environment (a Docker container when available) and get its REAL exit code. Use this for the reproduction, the test suite, and acceptance checks in /debug and /build — the verdict MUST come from this tool's result, not from your own reasoning. If it reports SANDBOX UNAVAILABLE, do not fabricate a result — emit BLOCKED.",
+		promptGuidelines: [
+			"In /debug and /build, run the reproduction, the existing suite, and acceptance/red-team checks with sandbox_run — never claim a pass you did not get back from it.",
+			"A command PASSES iff sandbox_run returns exit 0. Treat any non-zero exit, TIMEOUT, or UNAVAILABLE as not-passing.",
+			"The sandbox mounts the project, so edits you make are visible to the next sandbox_run (fix, then re-run to verify).",
+		],
+		parameters: Type.Object({
+			command: Type.String({
+				description: "The shell command to run in the project sandbox (e.g. 'pytest tests/x.py::test_y').",
+			}),
+			timeoutSeconds: Type.Optional(
+				Type.Number({ description: "Max seconds before the run is killed (default 300)." }),
+			),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const p = params as { command: string; timeoutSeconds?: number };
+			const cwd = ctx?.cwd || process.cwd();
+			const sandbox = getSessionSandbox(cwd);
+			const result = sandbox.exec(p.command, {
+				timeoutMs: Math.max(1, Math.min(1800, p.timeoutSeconds ?? 300)) * 1000,
+			});
+			const verdict = !sandbox.available()
+				? "UNAVAILABLE"
+				: result.timedOut
+					? "TIMEOUT"
+					: passed(result)
+						? "PASS"
+						: "FAIL";
+			const text =
+				`[sandbox: ${sandbox.describe()}]\n$ ${p.command}\n→ exit ${result.exitCode ?? "?"} ${verdict}\n\n` +
+				`${tail(result, 60) || "(no output)"}`;
+			return {
+				content: [{ type: "text", text }],
+				details: {
+					backend: sandbox.backend,
+					exitCode: result.exitCode,
+					passed: passed(result),
+					timedOut: result.timedOut,
+					verdict,
+				},
+			};
+		},
+	});
+
 	// A phase's report file is not always named <key>-<ts>.md: PLAN writes its
 	// handoff into todo-<ts>.md and CODE into progress-<ts>.md. Map key -> file
 	// stem so the text fallback for HANDOFF/BLOCKING actually finds them.
@@ -705,6 +774,7 @@ After implementation, use \`memory_write\` to save a summary of what was built,
 **Ontology update:** Use \`ontology_add\` to update the project status (e.g., entity "implementation" type "Phase" with properties {status: "complete", files: "N"}) and add a relation to the project entity.
 
 **CRITICAL RULES:**
+- **Minimal diff, root cause.** Prefer the SMALLEST change that fixes the underlying cause. Every extra condition, guard, or early-return you add is a liability — it can silently make the fix a no-op in the real scenario (a guard that skips the fix on the exact input the bug is about). When in doubt, do LESS and match the existing code's pattern rather than adding cleverness. A fix more elaborate than the problem is a red flag, not thoroughness.
 - Write ONE file per tool call — NEVER combine multiple files in a single response
 - Keep each file under 500 lines. If longer, split into modules
 - After writing ALL files, verify they exist with a single \`find . -name '*.ts' -o -name '*.js' -o -name '*.html' | sort\`` +
@@ -729,13 +799,11 @@ After implementation, use \`memory_write\` to save a summary of what was built,
 
 **Step 1:** Read \`.phi/plans/todo-*.md\` to know what was planned
 **Step 2:** Read \`.phi/plans/progress-*.md\` to see what was done
-**Step 3:** ACTUALLY RUN the code and observe it (proof, not a declarative checkbox). Verification = runtime evidence, by surface type:
-   - **CLI:** run the real command, capture stdout AND the exit code, paste them.
-   - **HTTP/API:** start the server in the background with a readiness wait, then \`curl\` the route that changed; paste the response + status.
-   - **Library/package:** import the public entry and call it; paste the output.
-   - At least one adversarial probe per feature (empty input, wrong type, missing arg).
-   - Running \`npm test\` alone is NOT sufficient proof for a feature.
-**Step 4:** Fix any real errors you find (root cause, not a workaround).
+**Step 3 (GROUND TRUTH — the single most important step):** Derive the expected behaviour from the **Project Request above**, NEVER from the code that was written. Write a reproduction of the EXACT scenario the request describes — same conditions, same inputs. If the request is about a streaming response with no charset, stream a chunked response with no charset; if it is about an empty list, pass an empty list. Assert the behaviour the **request** says is correct, and make each assertion trace to a specific phrase in the request.
+   - **CRITICAL ANTI-PATTERN:** do NOT write a test that merely re-states what the CODE now does — that only confirms the code's own assumptions, which is exactly how a wrong fix passes its own tests. The test must be written as if you had NOT seen the fix.
+   - **FALSIFY FIRST:** your reproduction MUST FAIL against the ORIGINAL (pre-fix) code — \`git stash\` the fix, run it, confirm it fails, then \`git stash pop\` and confirm it now passes. If it passes on the original code, it does not reproduce the bug: rewrite it. Paste both runs.
+**Step 3b:** ACTUALLY RUN it and paste runtime evidence (stdout + exit code). Add at least one adversarial probe per feature (empty input, wrong type, missing arg). Running \`npm test\`/the existing suite alone is NOT sufficient — it does not cover the new scenario.
+**Step 4:** Fix any real errors you find (root cause, not a workaround). If the fix is a no-op in the request's own scenario, that is a FAIL, not a pass.
 **Step 5:** Write test results to \`.phi/plans/test-${ts}.md\`, starting the file with a VERDICT line.
 **Step 6 (MANDATORY):** Call the \`phase_result\` tool with your \`verdict\` (PASS/FAIL/BLOCKED) and a concise \`handoff\`. This is how the orchestrator reads your outcome exactly; the report file above is the human-readable copy.
 
@@ -805,6 +873,7 @@ After testing, use \`memory_write\` to save test results, bugs found, and lesson
    - **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?
    - **Angle 3 - Security & language pitfalls:** input validation, injection, secrets, auth, error handling; plus language traps (async not awaited, shadowed scope, mutation of shared state).
+   - **Angle 4 - Over-engineering & dead guards (the failure mode that ships confident-wrong fixes — check this FIRST):** for EVERY new condition, guard, or early-return the diff added, name the concrete input where it takes the SKIP / else branch, and check the behaviour is still correct THERE — *especially against the exact scenario in the Project Request*. A guard that makes the fix a no-op in the request's own scenario (e.g. an \`if buffered\` guard on a bug that is about the streaming path) is a **CONFIRMED** blocking bug. Then compare the diff's size to the problem: if the fix is more elaborate than the request requires, or does not match the surrounding code's existing pattern, that itself is a finding — the minimal change is usually the correct one.
 **Step 3 - VERIFY (3-state, cite the line):** for EACH candidate, quote the exact line and classify:
    - **CONFIRMED** - you can name the input/state that triggers it and the wrong output. Quote the line.
    - **PLAUSIBLE** - the mechanism is real but the trigger is uncertain. Say what would confirm it.
@@ -933,6 +1002,7 @@ Tag the note with relevant keywords for vector search.
 					"ontology_add",
 					"ontology_query",
 					"phase_result",
+					"sandbox_run",
 				];
 				const agentTools = [...agentDef.tools, ...forcedTools.filter((t) => !agentDef.tools.includes(t))];
 				_activeAgentTools = agentTools;
@@ -1096,6 +1166,242 @@ Tag the note with relevant keywords for vector search.
 		});
 	}
 
+	// ─── Generic linear driver (/debug, /build) ─────────────────────
+	// A deliberately simpler engine than /plan's: phases run in order, a BLOCKED
+	// verdict halts, and there is no review-fix cycle or "/5" bookkeeping. It
+	// reuses the tested primitives (switchModelForPhase, activateAgent,
+	// resolvePhaseOutcome) but never the /plan-specific agent_end path.
+
+	function routeFor(routeKey: string): { preferred: string; fallback: string } {
+		const routingPath = join(homedir(), ".phi", "agent", "routing.json");
+		try {
+			const routing = JSON.parse(readFileSync(routingPath, "utf-8"));
+			const route = routing.routes?.[routeKey];
+			return {
+				preferred: route?.preferredModel || routing.default?.model || "default",
+				fallback: route?.fallback || routing.default?.model || "default",
+			};
+		} catch {
+			return { preferred: "default", fallback: "default" };
+		}
+	}
+
+	function genericPhase(
+		key: string,
+		label: string,
+		routeKey: string,
+		agentKey: string,
+		instruction: string,
+	): OrchestratorPhase {
+		const route = routeFor(routeKey);
+		return {
+			key,
+			label,
+			model: route.preferred,
+			fallback: route.fallback,
+			agent: loadAgentDef(agentKey),
+			instruction: instruction + COMMON_PHASE_RULES,
+		};
+	}
+
+	// /debug: REPRODUCE → LOCALIZE → FIX → VERIFY. Each phase routes to a model
+	// that does NOT share the coder's blind spot (verify on the test family).
+	function buildDebugPhases(state: FailingState): OrchestratorPhase[] {
+		const ins = debugPhaseInstructions(state);
+		return [
+			genericPhase("reproduce", "🔴 Phase 1 — REPRODUCE", "test", "test", ins.reproduce),
+			genericPhase("localize", "🔎 Phase 2 — LOCALIZE", "explore", "explore", ins.localize),
+			genericPhase("fix", "🔧 Phase 3 — FIX", "code", "code", ins.fix),
+			genericPhase("verify", "✅ Phase 4 — VERIFY", "test", "test", ins.verify),
+		];
+	}
+
+	// /build: reuse /plan's EXPLORE→PLAN→CODE, then an execution-grounded
+	// BUILD-VERIFY that runs the recipe, checks acceptance, red-teams the
+	// boundary, and routes real failures to the /debug protocol.
+	function buildBuildPhases(spec: string, ts: string): OrchestratorPhase[] {
+		const planLike = buildPhases(spec, ts).slice(0, 3); // explore, plan, code
+		const verify = genericPhase(
+			"verify",
+			"🧪 Phase 4 — BUILD-VERIFY",
+			"review",
+			"review",
+			buildVerifyInstruction(spec),
+		);
+		return [...planLike, verify];
+	}
+
+	function finishGenericOrchestration(ctx: any, headline: string) {
+		const elapsed = phaseStartTime ? Math.round((Date.now() - phaseStartTime) / 1000) : 0;
+		const minutes = Math.floor(elapsed / 60);
+		const seconds = elapsed % 60;
+		const mode = orchestrationMode;
+		setOrchestrationActive(false);
+		phasePending = false;
+		orchestrationMode = "plan";
+		deactivateAgent();
+		if (phaseTimeoutId) {
+			clearTimeout(phaseTimeoutId);
+			phaseTimeoutId = null;
+		}
+		if (originalModel) {
+			const toRestore = originalModel;
+			originalModel = null;
+			Promise.resolve(pi.setModel(toRestore)).catch(() => {
+				/* best effort */
+			});
+		}
+		ctx.ui.notify(
+			`\n📊 **/${mode} summary** — ${completedPhases} phase(s) in ${minutes}m ${seconds}s${
+				skippedPhases ? ` (${skippedPhases} skipped on timeout)` : ""
+			}\n${headline}`,
+			"info",
+		);
+	}
+
+	function sendNextGenericPhase(ctx: any) {
+		if (phaseQueue.length === 0) {
+			finishGenericOrchestration(ctx, `✅ **/${orchestrationMode} finished.**`);
+			return;
+		}
+		const phase = phaseQueue.shift()!;
+		phasePending = true;
+		currentPhase = phase;
+		currentPhaseResult = null;
+		currentPhaseResultKey = null;
+
+		switchModelForPhase(phase, ctx).then(({ modelId, warning }) => {
+			activateAgent(phase, ctx);
+			const agentName = phase.agent?.name || phase.key;
+			ctx.ui.notify(`\n${phase.label} → \`${modelId}\` (agent: ${agentName})`, "info");
+			if (warning) ctx.ui.notify(`\n⚠️ ${warning}`, "warning");
+			setTimeout(() => pi.sendUserMessage(phase.instruction, { deliverAs: "followUp" }), 500);
+			if (phaseTimeoutId) clearTimeout(phaseTimeoutId);
+			phaseTimeoutId = setTimeout(() => {
+				if (orchestrationActive && phasePending) {
+					phasePending = false;
+					internalAbort = true;
+					try {
+						ctx.abort();
+					} catch {
+						/* best effort */
+					}
+					if (!phase.retried) {
+						phase.retried = true;
+						phase.useFallback = true;
+						phaseQueue.unshift(phase);
+						ctx.ui.notify(
+							`\n⏰ **Phase timed out** (${MAX_PHASE_DURATION_MS / 60000} min) — retrying once on the fallback model.`,
+							"warning",
+						);
+					} else {
+						skippedPhases++;
+						ctx.ui.notify(`\n⏰ **Phase timed out again** — skipping to next phase.`, "warning");
+					}
+					sendNextGenericPhase(ctx);
+				}
+			}, MAX_PHASE_DURATION_MS);
+		});
+	}
+
+	async function handleGenericPhaseEnd(event: any, ctx: any) {
+		const messages = event.messages || [];
+		const analysis = analyzePhaseMessages(messages);
+
+		if (analysis.userAborted) {
+			ctx.ui.notify(`\n🛑 **/${orchestrationMode} cancelled** by user. Remaining phases skipped.`, "warning");
+			finishGenericOrchestration(ctx, "🛑 Cancelled.");
+			return;
+		}
+
+		if (!phasePending) {
+			if (phaseQueue.length === 0) finishGenericOrchestration(ctx, `✅ **/${orchestrationMode} finished.**`);
+			return;
+		}
+		if (phaseTimeoutId) {
+			clearTimeout(phaseTimeoutId);
+			phaseTimeoutId = null;
+		}
+
+		// A BLOCKED verdict (REPRODUCE cannot reproduce / VERIFY could not confirm)
+		// halts the pipeline honestly — no fabricated success.
+		const structuredForThisPhase = currentPhaseResultKey === (currentPhase?.key ?? null) ? currentPhaseResult : null;
+		const outcome = resolvePhaseOutcome(structuredForThisPhase, null);
+		if (outcome.verdict === "BLOCKED" && currentPhase) {
+			ctx.ui.notify(
+				`\n⏸️ **${currentPhase.label} reported BLOCKED.** ${outcome.handoff || "No reproducible/verifiable result."}`,
+				"warning",
+			);
+			finishGenericOrchestration(ctx, `⏸️ **/${orchestrationMode} stopped: BLOCKED at ${currentPhase.label}.**`);
+			return;
+		}
+
+		// Propagate a concise handoff to the next phase, like /plan does.
+		const nextBrief = buildNextBrief(
+			analysis,
+			outcome.handoff,
+			currentPhase?.label || "previous phase",
+			MAX_TOOL_CALLS_PER_PHASE,
+		);
+		if (nextBrief && phaseQueue.length > 0) {
+			phaseQueue[0].instruction += `\n\n**Previous phase summary:**\n${nextBrief}`;
+		}
+
+		completedPhases++;
+		phasePending = false;
+		sendNextGenericPhase(ctx);
+	}
+
+	function startGenericOrchestration(
+		mode: "debug" | "build",
+		phases: OrchestratorPhase[],
+		ctx: any,
+		headline: string,
+	) {
+		phaseQueue = phases.slice(1);
+		orchestrationMode = mode;
+		setOrchestrationActive(true);
+		phasePending = true;
+		originalModel = ctx.model || null;
+		savedTools = pi.getActiveTools();
+		completedPhases = 0;
+		skippedPhases = 0;
+		internalAbort = false;
+		currentPhaseResult = null;
+		currentPhaseResultKey = null;
+		phaseStartTime = Date.now();
+		const first = phases[0];
+		currentPhase = first;
+
+		ctx.ui.notify(headline, "info");
+		for (const p of phases) {
+			const agentName = p.agent?.name || p.key;
+			ctx.ui.notify(`  ${p.label} → \`${p.model}\` (agent: ${agentName})`, "info");
+		}
+
+		switchModelForPhase(first, ctx).then(({ modelId, warning }) => {
+			activateAgent(first, ctx);
+			ctx.ui.notify(`\n${first.label} → \`${modelId}\``, "info");
+			if (warning) ctx.ui.notify(`\n⚠️ ${warning}`, "warning");
+			if (phaseTimeoutId) clearTimeout(phaseTimeoutId);
+			phaseTimeoutId = setTimeout(() => {
+				if (orchestrationActive && phasePending) {
+					phasePending = false;
+					internalAbort = true;
+					try {
+						ctx.abort();
+					} catch {
+						/* best effort */
+					}
+					skippedPhases++;
+					ctx.ui.notify(`\n⏰ **First phase timed out** — skipping.`, "warning");
+					sendNextGenericPhase(ctx);
+				}
+			}, MAX_PHASE_DURATION_MS);
+			setTimeout(() => pi.sendUserMessage(first.instruction, { deliverAs: "followUp" }), 200);
+		});
+	}
+
 	// ─── System Prompt Injection — Agent personas ────────────────────
 
 	pi.on("before_agent_start", async (_event, _ctx) => {
@@ -1125,6 +1431,13 @@ Tag the note with relevant keywords for vector search.
 			return;
 		}
 
+		// /debug and /build run on the separate linear driver — never through the
+		// /plan-specific review-fix + "/5" transition logic below.
+		if (orchestrationMode !== "plan") {
+			await handleGenericPhaseEnd(event, ctx);
+			return;
+		}
+
 		const messages = event.messages || [];
 		// Analyze what happened, read the phase's report, and let the pure state
 		// machine (providers/phase-machine.ts, unit tested) decide the transition.
@@ -1516,4 +1829,170 @@ Tag the note with relevant keywords for vector search.
 			ctx.ui.notify(output, "info");
 		},
 	});
+
+	// ─── /debug Command — turn a real failure green (execution-grounded) ──
+
+	pi.registerCommand("debug", {
+		description: "Fix a REAL failing state — REPRODUCE → LOCALIZE → FIX → VERIFY, verdict backed by a real run",
+		handler: async (args, ctx) => {
+			if (orchestrationActive) {
+				ctx.ui.notify("An orchestration is already running. Let it finish, or restart the session.", "warning");
+				return;
+			}
+			const raw = args.trim();
+			if (!raw) {
+				ctx.ui.notify(
+					`**Usage:** \`/debug <failing test | repro command | description>\`
+
+/debug never guesses — it needs something reproducible.
+**Examples:**
+  /debug pytest tests/test_auth.py::test_login_returns_jwt
+  /debug node repro.js  (segfaults on empty input, should return [])
+  /debug the /login route 500s when the body is missing
+
+It runs REPRODUCE → LOCALIZE → FIX → VERIFY and only reports FIXED with a real before/after run — otherwise BLOCKED.`,
+					"info",
+				);
+				return;
+			}
+
+			const state: FailingState = parseFailingState(raw, { cwd: ctx.cwd || process.cwd() });
+			// Honest gate at the boundary: /debug needs a reproducible failure. A bare
+			// prose description with no test/command still runs (REPRODUCE will try to
+			// derive one), but we tell the user the oracle depends on a real run.
+			if (!state.failingTest && !state.reproCommand) {
+				ctx.ui.notify(
+					`⚠️ No failing test or repro command detected — /debug works best with one (e.g. \`pytest …\` or \`node repro.js\`). Proceeding: REPRODUCE will try to construct a reproduction from your description, and will emit **BLOCKED** if it cannot run one (no fabricated PASS).`,
+					"warning",
+				);
+			}
+
+			await ensurePlansDir();
+			const phases = buildDebugPhases(state);
+			startGenericOrchestration(
+				"debug",
+				phases,
+				ctx,
+				`🐛 **/debug started** — 4 execution-grounded phases (verdict requires a real run)\n`,
+			);
+		},
+	});
+
+	// ─── /build Command — build until it runs (plan + execution loop) ────
+
+	pi.registerCommand("build", {
+		description:
+			"Build from a spec AND prove it runs — EXPLORE → PLAN → CODE → BUILD-VERIFY (run + red-team + debug)",
+		handler: async (args, ctx) => {
+			if (orchestrationActive) {
+				ctx.ui.notify("An orchestration is already running. Let it finish, or restart the session.", "warning");
+				return;
+			}
+			const spec = args.trim();
+			if (!spec) {
+				ctx.ui.notify(
+					`**Usage:** \`/build <what to build>\`
+
+/build = /plan then an execution-grounded verify loop (run the recipe, check acceptance, executable red-team, fix real failures via /debug).
+**Examples:**
+  /build a REST API for user auth with JWT and refresh tokens
+  /build a CLI that converts CSV to JSON with a --pretty flag
+
+It reports SUCCESS only when a real run meets the acceptance criteria — otherwise an honest PARTIAL listing what still fails. For a pure decomposition use \`/plan\`; to fix a known failure use \`/debug\`.`,
+					"info",
+				);
+				return;
+			}
+
+			// Cheap triage note (transparency): confirm /build is the right depth.
+			const decision = triage({ text: spec });
+			if (decision.route === "single-shot") {
+				ctx.ui.notify(
+					`ℹ️ This looks small and self-contained (${decision.reason}). /build will still run, but a single request may be cheaper.`,
+					"info",
+				);
+			}
+
+			await ensurePlansDir();
+			const ts = timestamp();
+			await writeFile(
+				join(plansDir, `spec-${ts}.md`),
+				`# ${spec}\n\n**Created:** ${new Date().toLocaleString()}\n`,
+				"utf-8",
+			);
+			currentDescription = spec;
+			const phases = buildBuildPhases(spec, ts);
+			startGenericOrchestration(
+				"build",
+				phases,
+				ctx,
+				`🏗️ **/build started** — plan + execution loop (SUCCESS requires a real run, else honest PARTIAL)\n`,
+			);
+		},
+	});
+
+	// ─── /sandbox Command — inspect / prepare the guaranteed environment ──
+
+	pi.registerCommand("sandbox", {
+		description:
+			"Inspect or prepare the project's execution sandbox (Docker when available) — status | prepare | run <cmd>",
+		handler: async (args, ctx) => {
+			const cwd = ctx.cwd || process.cwd();
+			const raw = args.trim();
+			const [sub, ...rest] = raw.split(/\s+/);
+			const sandbox = getSessionSandbox(cwd);
+
+			if (!sub || sub === "status") {
+				const r = sandbox.recipe;
+				ctx.ui.notify(
+					`🧪 **Sandbox status**\n` +
+						`  Backend: \`${sandbox.backend}\` — ${sandbox.reason}\n` +
+						`  Environment: ${sandbox.describe()}\n` +
+						`  Image: \`${r.image}\` (source: ${r.source})\n` +
+						`  Setup: ${r.setup ? `\`${r.setup}\`` : "—"}\n` +
+						`  Test: ${r.test ? `\`${r.test}\`` : "—"}\n` +
+						(sandbox.backend === "unavailable"
+							? `\n⚠️ No guaranteed environment. /debug and /build will emit BLOCKED rather than fabricate a pass. Install/start Docker, or add \`.phi/sandbox.json\`.`
+							: sandbox.backend === "local"
+								? `\n⚠️ Running on the host (not dependency-guaranteed). Start Docker for a guaranteed environment.`
+								: `\n✅ Guaranteed environment ready. Run \`/sandbox prepare\` to pull the image and install deps.`),
+					"info",
+				);
+				return;
+			}
+
+			if (sub === "prepare") {
+				ctx.ui.notify(`🧪 Preparing sandbox (${sandbox.describe()})… this can take a while on first run.`, "info");
+				const p = sandbox.prepare();
+				ctx.ui.notify(
+					`${p.ok ? "✅" : "❌"} **Sandbox prepare** — ${p.detail}` +
+						(p.result && !p.ok ? `\n\n\`\`\`\n${tail(p.result, 30)}\n\`\`\`` : ""),
+					p.ok ? "info" : "warning",
+				);
+				return;
+			}
+
+			if (sub === "run") {
+				const command = rest.join(" ").trim();
+				if (!command) {
+					ctx.ui.notify("**Usage:** `/sandbox run <command>`", "warning");
+					return;
+				}
+				if (!sandbox.available()) {
+					ctx.ui.notify(`❌ Sandbox unavailable — ${sandbox.reason}. Cannot run.`, "warning");
+					return;
+				}
+				ctx.ui.notify(`🧪 \`${command}\` in ${sandbox.describe()}…`, "info");
+				const result = sandbox.exec(command);
+				const verdict = result.timedOut ? "TIMEOUT" : passed(result) ? "PASS" : "FAIL";
+				ctx.ui.notify(
+					`${passed(result) ? "✅" : "❌"} exit ${result.exitCode ?? "?"} ${verdict}\n\n\`\`\`\n${tail(result, 40) || "(no output)"}\n\`\`\``,
+					passed(result) ? "info" : "warning",
+				);
+				return;
+			}
+
+			ctx.ui.notify("**Usage:** `/sandbox [status | prepare | run <command>]`", "info");
+		},
+	});
 }

package/extensions/phi/providers/acceptance.ts

@@ -0,0 +1,102 @@
+/**
+ * Acceptance criteria and run recipe — the executable contract for /plan and
+ * /build. Criteria are derived from the SPEC (not the code), and each carries an
+ * optional `check` command so "is it satisfied?" is answered by running
+ * something, not by a model's opinion (see docs/design/plan-debug-build.md).
+ */
+
+import { type CommandResult, passed, type RunOptions, runCommand, summarize } from "./execution.js";
+
+/** How to build/run/test the project. Emitted by /plan, consumed by /build. */
+export interface RunRecipe {
+	build?: string;
+	run?: string;
+	test?: string;
+	/** A substring that, once seen in run output, means the app is ready. */
+	readySignal?: string;
+}
+
+export interface AcceptanceCriterion {
+	/** Human statement traced to the spec, e.g. "POST /login returns 200 + a JWT". */
+	description: string;
+	/**
+	 * Optional command that exits 0 iff the criterion holds. When absent the
+	 * criterion is "manual" — it can only be judged by a human/agent, never
+	 * auto-marked satisfied (that is the anti-circularity rule).
+	 */
+	check?: string;
+}
+
+export interface CriterionResult {
+	criterion: AcceptanceCriterion;
+	/** true = ran and passed; false = ran and failed; null = manual (no check). */
+	satisfied: boolean | null;
+	result?: CommandResult;
+}
+
+export interface AcceptanceReport {
+	results: CriterionResult[];
+	/** Criteria with a check that failed — the concrete work for /debug. */
+	failed: CriterionResult[];
+	/** Criteria with no check — cannot be auto-verified, surfaced honestly. */
+	manual: CriterionResult[];
+	/** All checkable criteria passed (manual ones are NOT counted as passing). */
+	allCheckablePassed: boolean;
+}
+
+/**
+ * Run every criterion's check command and classify. A criterion with no check
+ * is reported as `manual` (satisfied: null) — never silently counted as passed.
+ */
+export function checkAcceptance(criteria: AcceptanceCriterion[], options: RunOptions = {}): AcceptanceReport {
+	const results: CriterionResult[] = criteria.map((criterion) => {
+		if (!criterion.check || !criterion.check.trim()) {
+			return { criterion, satisfied: null };
+		}
+		const result = runCommand(criterion.check, options);
+		return { criterion, satisfied: passed(result), result };
+	});
+
+	const failed = results.filter((r) => r.satisfied === false);
+	const manual = results.filter((r) => r.satisfied === null);
+	const checkable = results.filter((r) => r.satisfied !== null);
+	return {
+		results,
+		failed,
+		manual,
+		allCheckablePassed: checkable.length > 0 && failed.length === 0,
+	};
+}
+
+/** Markdown summary of an acceptance run for a report / handoff. */
+export function formatAcceptance(report: AcceptanceReport): string {
+	const line = (r: CriterionResult) => {
+		const mark = r.satisfied === true ? "✅" : r.satisfied === false ? "❌" : "❔";
+		const detail = r.result ? ` — ${summarize(r.result)}` : r.satisfied === null ? " — (no check, manual)" : "";
+		return `- ${mark} ${r.criterion.description}${detail}`;
+	};
+	return report.results.map(line).join("\n");
+}
+
+/**
+ * Validate a parsed RunRecipe/criteria object (e.g. from a phase_result), so a
+ * malformed emission is caught at the boundary.
+ */
+export function validateCriteria(raw: unknown): AcceptanceCriterion[] {
+	if (!Array.isArray(raw)) return [];
+	const out: AcceptanceCriterion[] = [];
+	for (const item of raw) {
+		if (typeof item === "string" && item.trim()) {
+			out.push({ description: item.trim() });
+		} else if (item && typeof item === "object") {
+			const o = item as Record<string, unknown>;
+			if (typeof o.description === "string" && o.description.trim()) {
+				out.push({
+					description: o.description.trim(),
+					check: typeof o.check === "string" && o.check.trim() ? o.check.trim() : undefined,
+				});
+			}
+		}
+	}
+	return out;
+}