@phi-code-admin/phi-code 0.92.0 → 0.93.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## [0.93.0] - 2026-07-12
+
+### Added — the escalation architecture the n=13 measurement demanded
+
+- **`/fix` — single-shot first, oracle next, escalate only on red.** One direct
+  attempt at baseline cost, then the DRIVER runs the reproduction and the
+  project suite in the real sandbox (deterministic, zero model tokens): green →
+  done; red → the full /debug pipeline takes over, seeded with the exact red
+  run (command + trace, never a paraphrase). Nothing runnable → honestly
+  labelled UNVERIFIED. By construction never worse than the single shot
+  (measured: baseline 7/13 vs pipeline 6/13 at ~2.5×).
+- **`/debug --candidates N` — diversity proposes, the oracle disposes.** N
+  independent FIX attempts on DIVERSE model families (routing-derived), each
+  patch captured and the tree reset between attempts; then deterministic
+  arbitration applies each candidate and runs the reproduction (from the input
+  or the REPRODUCE handoff's machine-readable REPRO-CMD line) + suite in the
+  sandbox; the minimal passing candidate wins (candidate-select). This is the
+  adversarial review that works — the one we measured (opinion panels rubber-
+  stamp shared misconceptions; a red run does not). Refuses to run over a dirty
+  tree (non-deletion policy) and falls back to single-candidate.
+- **Never a blank page (lesson sympy-11870).** When no candidate passes
+  arbitration, the smallest non-empty candidate stays applied, clearly labelled
+  UNVERIFIED; a confirmed-BLOCKED halt now reports any draft left in the tree
+  (git diff --stat) instead of silently discarding work.
+- **Literal reproductions (lesson requests-2148).** REPRODUCE must build the
+  repro from the EXACT snippets/values quoted in the issue (a reproduction of
+  your interpretation validates your interpretation, not the bug) and must
+  emit a REPRO-CMD: line for deterministic re-runs. LOCALIZE now consults and
+  feeds project memory (memory_search/memory_write).
+- **Run telemetry.** Every /fix //debug //build run appends one JSONL line to
+  .phi/runs.jsonl (mode, phases with model+verdict+retries, sandbox exec count,
+  duration, outcome) — continuous measurement instead of campaigns.
+
+30 new tests (escalation core 13, telemetry 6, instructions 5, integration 6 —
+including a real-git multi-candidate arbitration that applies the minimal
+passing patch and a real-run /fix escalation); full suite green (1469).
+
+## [0.92.1] - 2026-07-12
+
+### Docs
+
+- README: document the execution-grounded modes (/plan, /debug, /build, /sandbox,
+  the sandbox_run oracle, per-phase model routing, the honest n=13 measurement)
+  and the one-command Alibaba Cloud Coding Plan setup — three releases of
+  features were undocumented.
+
 ## [0.92.0] - 2026-07-11
 
 ### Fixed — the two defects the n=13 SWE-bench measurement exposed

package/README.md

@@ -16,6 +16,7 @@ phi-code runs in four modes: interactive, print or JSON, RPC for process integra
 
 - [Quick Start](#quick-start)
 - [Providers & Models](#providers--models)
+- [Execution-Grounded Modes (/plan, /debug, /build, /sandbox)](#execution-grounded-modes)
 - [Interactive Mode](#interactive-mode)
   - [Editor](#editor)
   - [Commands](#commands)
@@ -103,13 +104,62 @@ For each built-in provider, phi maintains a list of tool-capable models, updated
 - Xiaomi MiMo Token Plan (China)
 - Xiaomi MiMo Token Plan (Amsterdam)
 - Xiaomi MiMo Token Plan (Singapore)
+- Alibaba Cloud Coding Plan (`qwen3.7-plus`, GLM, Kimi, MiniMax — subscription quota)
 
 See [docs/providers.md](docs/providers.md) for detailed setup instructions.
 
+**One-command setup for known providers:** `/keys set alibaba-codingplan sk-sp-…` (or `opencode-go <key>`) bootstraps the full provider entry — endpoint, protocol, model list — from just the API key, then validates it with `/keys test <id>`. The live catalog refreshes on session start.
+
 **Custom providers & models:** Add providers via `~/.phi/agent/models.json` if they speak a supported API (OpenAI, Anthropic, Google). For custom APIs or OAuth, use extensions. See [docs/models.md](docs/models.md) and [docs/custom-provider.md](docs/custom-provider.md).
 
 ---
 
+## Execution-Grounded Modes
+
+Phi's multi-phase modes share one principle, learned the hard way on SWE-bench:
+**execution is the only oracle**. A verdict must come from running real code —
+never from a model reviewing its own output (which we measured approving wrong
+code, even across model families). Full design:
+[docs/design/plan-debug-build.md](docs/design/plan-debug-build.md).
+
+| Command | Job | Pipeline |
+|---|---|---|
+| `/fix <failing test \| repro \| description>` | Fix at single-shot cost, verified | SINGLE SHOT → sandbox oracle → green: done / red: escalate to /debug |
+| `/plan <spec>` | Plan AND build a project | EXPLORE → PLAN → CODE → TEST → REVIEW |
+| `/debug <…> [--candidates N]` | Turn a REAL failure green | REPRODUCE → LOCALIZE → FIX (×N diverse models) → real-run arbitration / VERIFY |
+| `/build <spec>` | Build until it runs | EXPLORE → PLAN → CODE → BUILD-VERIFY (run recipe + acceptance + executable red-team) |
+| `/sandbox [status\|prepare\|run <cmd>]` | Inspect the guaranteed environment | — |
+
+**The execution sandbox.** Every oracle run goes through the `sandbox_run` tool:
+a per-project Docker container (toolchain auto-detected — node/python/go/rust/ruby
+or your `Dockerfile`; override anything in `.phi/sandbox.json`) that returns the
+REAL exit code. No Docker and nothing to containerize → runs fall back to the
+host; if an environment is demanded but unavailable, phases report `BLOCKED`
+rather than fabricate a pass.
+
+**Honesty guarantees** (each one exists because we measured its absence losing):
+- `/debug` refuses to "fix" a failure it cannot reproduce — and a BLOCKED verdict
+  gets one second chance on a different model family before the halt.
+- VERIFY requires the reproduction to pass AND the suite not to regress; a
+  TIMEOUT counts as a regression (a fix that hangs the suite is worse than none).
+- `/build` reports `SUCCESS` only when a real run meets the acceptance criteria,
+  otherwise an honest `PARTIAL` listing what still fails.
+
+**Per-phase model routing.** Each phase can run on its own model via
+`~/.phi/agent/routing.json` (e.g. code on `alibaba-codingplan/qwen3.7-plus`,
+verification on a different family so it does not share the coder's blind spot),
+with automatic fallback on transient provider errors.
+
+**Measured, honestly:** on a 13-instance SWE-bench-lite slice (official harness),
+a strong single-shot baseline resolved 7/13 vs `/debug` 6/13 at ~2.5× the time —
+with `/debug` producing smaller patches and zero toxic ones. `/fix` is the
+composition that measurement demanded: by construction never worse than the
+single shot, escalating exactly where a real red run proves the shot failed.
+Every run appends a telemetry line to `.phi/runs.jsonl` (phases, models,
+verdicts, sandbox executions, duration) so behaviour is measured continuously.
+
+---
+
 ## Interactive Mode
 
 <p align="center"><img src="docs/images/interactive-mode.png" alt="Interactive Mode" width="600"></p>

package/extensions/phi/orchestrator.ts

@@ -23,9 +23,20 @@ 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 { diffChangedLines } from "./providers/candidate-select.js";
+import {
+	buildVerifyInstruction,
+	debugPhaseInstructions,
+	singleShotInstruction,
+} from "./providers/debug-build-commands.js";
+import {
+	decideVerify,
+	type FailingState,
+	parseFailingState,
+	type VerifiedCandidate,
+} from "./providers/debug-contract.js";
+import { decideEscalation, parseReproCmd, pickCandidateModels, type RoutingLike } from "./providers/escalation.js";
+import { passed, runCommand, tail } from "./providers/execution.js";
 import { defaultExplorerSpecs, READONLY_EXPLORER_TOOLS, runExploreFanout } from "./providers/explore-fanout.js";
 import {
 	analyzePhaseMessages,
@@ -35,6 +46,7 @@ import {
 	type StructuredPhaseResult,
 } from "./providers/phase-machine.js";
 import { resolveSandbox, type Sandbox } from "./providers/sandbox.js";
+import { appendRunRecord, buildRunRecord, type PhaseRecord } from "./providers/telemetry.js";
 import { triage } from "./providers/triage.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────
@@ -300,9 +312,32 @@ 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";
+	// untouched; "debug"/"build"/"fix" 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" | "fix" = "plan";
+	// /fix escalation state: the failing state the command started from, and
+	// whether the driver-level oracle already ran (it must run exactly once,
+	// after the single-shot phase, before the run can finish).
+	let fixContext: { state: FailingState; oracleRan: boolean } | null = null;
+	// /debug --candidates N state: each FIX candidate's captured patch, the
+	// reproduction command used for deterministic arbitration (from the input or
+	// the REPRODUCE handoff's REPRO-CMD line), and whether arbitration ran.
+	let candidateContext: {
+		total: number;
+		reproCmd?: string;
+		list: { source: string; patch: string }[];
+		arbitrated: boolean;
+	} | null = null;
+	// Telemetry: per-phase records for the current generic run + sandbox_run
+	// invocation count (reset at orchestration start, flushed at finish).
+	let runPhaseRecords: PhaseRecord[] = [];
+	let sandboxExecCount = 0;
+
+	/** Run a git command in cwd; returns stdout ("" on any failure). */
+	function gitIn(cwd: string, args: string): string {
+		const r = runCommand(`git ${args}`, { cwd, timeoutMs: 60_000 });
+		return passed(r) ? r.stdout : "";
+	}
 	let activeAgentPrompt: string | null = null;
 	let _activeAgentTools: string[] | null = null;
 	let savedTools: string[] | null = null;
@@ -430,6 +465,7 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			const p = params as { command: string; timeoutSeconds?: number };
 			const cwd = ctx?.cwd || process.cwd();
+			if (orchestrationActive) sandboxExecCount++;
 			const sandbox = getSessionSandbox(cwd);
 			const result = sandbox.exec(p.command, {
 				timeoutMs: Math.max(1, Math.min(1800, p.timeoutSeconds ?? 300)) * 1000,
@@ -1211,16 +1247,50 @@ Tag the note with relevant keywords for vector search.
 
 	// /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[] {
+	function buildDebugPhases(state: FailingState, candidates = 1): OrchestratorPhase[] {
 		const ins = debugPhaseInstructions(state);
+		if (candidates <= 1) {
+			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),
+			];
+		}
+		// Multi-candidate: N independent FIX attempts on DIVERSE model families
+		// (diversity proposes), then the driver arbitrates each candidate with a
+		// REAL run (the oracle disposes) — no VERIFY agent phase, no vote.
+		const models = pickCandidateModels(readRoutingConfig(), candidates);
+		const codeRoute = routeFor("code");
+		const fixPhases = Array.from({ length: candidates }, (_, i) => {
+			const ref = models[i % Math.max(1, models.length)] ?? codeRoute.preferred;
+			const phase = genericPhase(
+				"fix-cand",
+				`🔧 Phase ${3 + i} — FIX candidate ${i + 1}/${candidates}`,
+				"code",
+				"code",
+				`${ins.fix}\n\n**Candidate protocol:** you are INDEPENDENT candidate ${i + 1} of ${candidates}. Other candidates attempt the same fault separately; a REAL run of the reproduction and the suite arbitrates between the resulting patches. Make your own best minimal fix — do not hedge for the others.`,
+			);
+			phase.model = ref;
+			phase.fallback = codeRoute.fallback;
+			return phase;
+		});
 		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),
+			...fixPhases,
 		];
 	}
 
+	/** Read ~/.phi/agent/routing.json (shape shared with routeFor). */
+	function readRoutingConfig(): RoutingLike {
+		try {
+			return JSON.parse(readFileSync(join(homedir(), ".phi", "agent", "routing.json"), "utf-8")) as RoutingLike;
+		} catch {
+			return {};
+		}
+	}
+
 	// /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.
@@ -1241,9 +1311,25 @@ Tag the note with relevant keywords for vector search.
 		const minutes = Math.floor(elapsed / 60);
 		const seconds = elapsed % 60;
 		const mode = orchestrationMode;
+		// Telemetry: one JSONL line per run — continuous measurement for free.
+		appendRunRecord(
+			ctx.cwd || process.cwd(),
+			buildRunRecord({
+				mode,
+				startedAtMs: phaseStartTime,
+				endedAtMs: Date.now(),
+				phases: runPhaseRecords,
+				completedPhases,
+				skippedPhases,
+				sandboxExecs: sandboxExecCount,
+				outcome: headline,
+			}),
+		);
 		setOrchestrationActive(false);
 		phasePending = false;
 		orchestrationMode = "plan";
+		fixContext = null;
+		candidateContext = null;
 		deactivateAgent();
 		if (phaseTimeoutId) {
 			clearTimeout(phaseTimeoutId);
@@ -1264,10 +1350,148 @@ Tag the note with relevant keywords for vector search.
 		);
 	}
 
+	// /fix driver-level oracle: after the single shot, run the reproduction and
+	// the project suite in the REAL sandbox. Green → finish at baseline cost.
+	// Red → escalate: enqueue the full /debug pipeline seeded with the red run.
+	// Deterministic — zero model tokens; the verdict comes from exit codes.
+	function runFixOracleAndMaybeEscalate(ctx: any): boolean {
+		if (orchestrationMode !== "fix" || !fixContext || fixContext.oracleRan) return false;
+		fixContext.oracleRan = true;
+		const cwd = ctx.cwd || process.cwd();
+		const sandbox = getSessionSandbox(cwd);
+		const reproCmd = fixContext.state.failingTest?.trim() || fixContext.state.reproCommand?.trim();
+		const suiteCmd = sandbox.recipe.test?.trim();
+
+		if (!sandbox.available() && (reproCmd || suiteCmd)) {
+			ctx.ui.notify(
+				`\n⚠️ **/fix oracle: sandbox unavailable** (${sandbox.reason}) — the single shot cannot be verified. Treating it as UNVERIFIED.`,
+				"warning",
+			);
+			finishGenericOrchestration(ctx, `⚠️ **/fix finished UNVERIFIED — no executable environment for the oracle.**`);
+			return true;
+		}
+
+		ctx.ui.notify(
+			`\n🧪 **/fix oracle** — running ${[reproCmd && "the reproduction", suiteCmd && "the suite"].filter(Boolean).join(" and ") || "nothing (no runnable check)"} in ${sandbox.describe()}…`,
+			"info",
+		);
+		const repro = reproCmd ? sandbox.exec(reproCmd, { timeoutMs: 10 * 60 * 1000 }) : null;
+		const suite = suiteCmd ? sandbox.exec(suiteCmd, { timeoutMs: 20 * 60 * 1000 }) : null;
+		const decision = decideEscalation(fixContext.state, { repro, suite });
+
+		if (decision.action === "done-green") {
+			finishGenericOrchestration(
+				ctx,
+				`✅ **/fix finished GREEN at single-shot cost** — oracle evidence: ${decision.evidence}.`,
+			);
+			return true;
+		}
+		if (decision.action === "done-unverified") {
+			finishGenericOrchestration(
+				ctx,
+				`⚠️ **/fix finished UNVERIFIED** — ${decision.reason}. Provide a failing test or a repro command for a guaranteed verdict.`,
+			);
+			return true;
+		}
+		// escalate: the pipeline inherits the RED run as its concrete failing state.
+		ctx.ui.notify(
+			`\n🔺 **/fix escalating to the full /debug pipeline** — ${decision.diagnostic}. The single shot was not enough; the pipeline inherits the red run as its reproduction.`,
+			"warning",
+		);
+		phaseQueue.push(...buildDebugPhases(decision.failing));
+		return false; // fall through: sendNextGenericPhase will dispatch REPRODUCE
+	}
+
+	// Multi-candidate arbitration — the oracle disposes. Apply each captured
+	// candidate in turn, run the reproduction (and the suite when known) in the
+	// REAL sandbox, select the minimal passing candidate (candidate-select), and
+	// leave the WINNER applied. If none passes: never a blank page — the smallest
+	// non-empty candidate is left applied, clearly labelled UNVERIFIED.
+	function runCandidateArbitration(ctx: any): boolean {
+		if (!candidateContext || candidateContext.arbitrated) return false;
+		candidateContext.arbitrated = true;
+		const cc = candidateContext;
+		const cwd = ctx.cwd || process.cwd();
+		const sandbox = getSessionSandbox(cwd);
+		const suiteCmd = sandbox.recipe.test?.trim();
+		const nonEmpty = cc.list.filter((c) => c.patch.trim());
+
+		if (nonEmpty.length === 0) {
+			finishGenericOrchestration(ctx, `⏸️ **/${orchestrationMode} BLOCKED — no candidate produced a patch.**`);
+			return true;
+		}
+
+		const applyPatch = (patch: string): boolean => {
+			try {
+				const f = join(cwd, ".phi", "candidate.patch");
+				writeFileSync(f, patch, "utf-8");
+				const r = runCommand(`git apply --whitespace=nowarn "${f}"`, { cwd, timeoutMs: 60_000 });
+				try {
+					unlinkSync(f);
+				} catch {
+					/* best effort */
+				}
+				return passed(r);
+			} catch {
+				return false;
+			}
+		};
+
+		ctx.ui.notify(
+			`\n⚖️ **Arbitrating ${nonEmpty.length} candidate(s)** with real runs${cc.reproCmd ? ` — repro \`${cc.reproCmd}\`` : ""}${suiteCmd ? `, suite \`${suiteCmd}\`` : ""} in ${sandbox.describe()}…`,
+			"info",
+		);
+
+		const verified: VerifiedCandidate[] = [];
+		for (const cand of nonEmpty) {
+			if (!applyPatch(cand.patch)) {
+				verified.push({ source: cand.source, patch: cand.patch, reproAfter: null, suite: null });
+				continue;
+			}
+			const reproAfter =
+				cc.reproCmd && sandbox.available() ? sandbox.exec(cc.reproCmd, { timeoutMs: 10 * 60 * 1000 }) : null;
+			const suite = suiteCmd && sandbox.available() ? sandbox.exec(suiteCmd, { timeoutMs: 20 * 60 * 1000 }) : null;
+			verified.push({ source: cand.source, patch: cand.patch, reproAfter, suite });
+			gitIn(cwd, "checkout -- .");
+			const rp = reproAfter
+				? `repro exit ${reproAfter.exitCode}${reproAfter.timedOut ? " TIMEOUT" : ""}`
+				: "repro n/a";
+			const st = suite ? `suite exit ${suite.exitCode}${suite.timedOut ? " TIMEOUT" : ""}` : "suite n/a";
+			ctx.ui.notify(`  ${cand.source}: ${rp}, ${st}`, "info");
+		}
+
+		const outcome = decideVerify(verified, Boolean(suiteCmd));
+		if (outcome.verdict === "FIXED" && outcome.patch) {
+			applyPatch(outcome.patch);
+			finishGenericOrchestration(
+				ctx,
+				`✅ **/${orchestrationMode} FIXED by candidate arbitration** — ${outcome.reason}. Evidence: repro passes${suiteCmd ? ", suite green" : ""} (real runs above). The winning patch is applied.`,
+			);
+			return true;
+		}
+
+		// Honest failure — but never a blank page: leave the smallest non-empty
+		// candidate applied, clearly labelled unverified (lesson: sympy-11870).
+		const smallest = [...nonEmpty].sort((a, b) => diffChangedLines(a.patch) - diffChangedLines(b.patch))[0];
+		const draftApplied = applyPatch(smallest.patch);
+		finishGenericOrchestration(
+			ctx,
+			`⏸️ **/${orchestrationMode} BLOCKED — no candidate passed arbitration** (${outcome.reason ?? "see runs above"}).` +
+				(draftApplied
+					? ` An **UNVERIFIED draft** (smallest candidate, ${smallest.source}) is left in the working tree — \`git diff\` to inspect, \`git checkout -- .\` to discard.`
+					: ""),
+		);
+		return true;
+	}
+
 	function sendNextGenericPhase(ctx: any) {
 		if (phaseQueue.length === 0) {
-			finishGenericOrchestration(ctx, `✅ **/${orchestrationMode} finished.**`);
-			return;
+			if (runCandidateArbitration(ctx)) return;
+			if (runFixOracleAndMaybeEscalate(ctx)) return;
+			if (phaseQueue.length === 0) {
+				finishGenericOrchestration(ctx, `✅ **/${orchestrationMode} finished.**`);
+				return;
+			}
 		}
 		const phase = phaseQueue.shift()!;
 		phasePending = true;
@@ -1320,7 +1544,9 @@ Tag the note with relevant keywords for vector search.
 		}
 
 		if (!phasePending) {
-			if (phaseQueue.length === 0) finishGenericOrchestration(ctx, `✅ **/${orchestrationMode} finished.**`);
+			// Route through sendNextGenericPhase so the /fix oracle still runs on
+			// this (duplicate-event) completion path instead of being bypassed.
+			if (phaseQueue.length === 0) sendNextGenericPhase(ctx);
 			return;
 		}
 		if (phaseTimeoutId) {
@@ -1342,6 +1568,18 @@ Tag the note with relevant keywords for vector search.
 			maxToolCallsPerPhase: MAX_TOOL_CALLS_PER_PHASE,
 		});
 
+		// Telemetry: one record per phase attempt (retries appear as extra rows).
+		if (currentPhase) {
+			runPhaseRecords.push({
+				key: currentPhase.key,
+				label: currentPhase.label,
+				model: currentPhase.useFallback ? currentPhase.fallback : currentPhase.model,
+				verdict: outcome.verdict,
+				retried: Boolean(currentPhase.retried),
+				blockedRetried: Boolean(currentPhase.blockedRetried),
+			});
+		}
+
 		if (decision.action === "stop") {
 			ctx.ui.notify(
 				`\n❌ **/${orchestrationMode} aborted:** API authentication error (401). Check your API key.`,
@@ -1387,10 +1625,46 @@ Tag the note with relevant keywords for vector search.
 				`\n⏸️ **${currentPhase.label} reported BLOCKED (confirmed on retry).** ${outcome.handoff || "No reproducible/verifiable result."}`,
 				"warning",
 			);
-			finishGenericOrchestration(ctx, `⏸️ **/${orchestrationMode} stopped: BLOCKED at ${currentPhase.label}.**`);
+			// Never a silent blank page: if the run left changes in the tree (an
+			// unverified FIX attempt), say so instead of pretending nothing exists.
+			const draft = gitIn(ctx.cwd || process.cwd(), "diff --stat").trim();
+			finishGenericOrchestration(
+				ctx,
+				`⏸️ **/${orchestrationMode} stopped: BLOCKED at ${currentPhase.label}.**` +
+					(draft
+						? `\n📝 An **UNVERIFIED draft** remains in the working tree (\`git diff\` to inspect, \`git checkout -- .\` to discard):\n\`\`\`\n${draft.slice(0, 600)}\n\`\`\``
+						: ""),
+			);
 			return;
 		}
 
+		// Multi-candidate bookkeeping (mode debug, --candidates N):
+		// - after REPRODUCE: learn the exact repro command from the REPRO-CMD
+		//   handoff line (used later for deterministic arbitration);
+		// - after each FIX candidate: capture its patch (git diff of tracked
+		//   files) and RESET the tree so the next candidate starts clean.
+		if (candidateContext && currentPhase) {
+			const cwd = ctx.cwd || process.cwd();
+			if (currentPhase.key === "reproduce" && !candidateContext.reproCmd) {
+				candidateContext.reproCmd = parseReproCmd(outcome.handoff);
+				if (candidateContext.reproCmd) {
+					ctx.ui.notify(`\n🧷 Arbitration reproduction registered: \`${candidateContext.reproCmd}\``, "info");
+				}
+			}
+			if (currentPhase.key === "fix-cand") {
+				const patch = gitIn(cwd, "diff").trim();
+				candidateContext.list.push({
+					source: `${currentPhase.label} (${currentPhase.useFallback ? currentPhase.fallback : currentPhase.model})`,
+					patch: patch ? `${patch}\n` : "",
+				});
+				gitIn(cwd, "checkout -- .");
+				ctx.ui.notify(
+					`\n📦 Candidate ${candidateContext.list.length}/${candidateContext.total} captured (${patch ? `${patch.length} bytes` : "EMPTY"}) — tree reset for the next candidate.`,
+					"info",
+				);
+			}
+		}
+
 		// Propagate a concise handoff to the next phase, like /plan does.
 		const nextBrief = buildNextBrief(
 			analysis,
@@ -1408,13 +1682,18 @@ Tag the note with relevant keywords for vector search.
 	}
 
 	function startGenericOrchestration(
-		mode: "debug" | "build",
+		mode: "debug" | "build" | "fix",
 		phases: OrchestratorPhase[],
 		ctx: any,
 		headline: string,
 	) {
 		phaseQueue = phases.slice(1);
 		orchestrationMode = mode;
+		// Defensive: stale /fix or candidate state must never leak across runs.
+		if (mode !== "fix") fixContext = null;
+		if (mode !== "debug") candidateContext = null;
+		runPhaseRecords = [];
+		sandboxExecCount = 0;
 		setOrchestrationActive(true);
 		phasePending = true;
 		originalModel = ctx.model || null;
@@ -1911,7 +2190,15 @@ It runs REPRODUCE → LOCALIZE → FIX → VERIFY and only reports FIXED with a
 				return;
 			}
 
-			const state: FailingState = parseFailingState(raw, { cwd: ctx.cwd || process.cwd() });
+			// Opt-in multi-candidate FIX: `--candidates N` (2..4). Diversity
+			// proposes (N model families patch independently), the oracle disposes
+			// (a real run arbitrates). Cost-disciplined: default stays 1.
+			const candMatch = raw.match(/(^|\s)--candidates[= ](\d)\b/);
+			let candidates = candMatch ? Math.max(1, Math.min(4, Number(candMatch[2]))) : 1;
+			const cleaned = raw.replace(/(^|\s)--candidates[= ]\d\b/g, " ").trim();
+			const cwd = ctx.cwd || process.cwd();
+
+			const state: FailingState = parseFailingState(cleaned, { 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.
@@ -1922,13 +2209,96 @@ It runs REPRODUCE → LOCALIZE → FIX → VERIFY and only reports FIXED with a
 				);
 			}
 
+			if (candidates > 1) {
+				// Candidate capture RESETS the tree between attempts — refuse to do
+				// that over a user's uncommitted work (non-deletion policy).
+				const porcelain = runCommand("git status --porcelain", { cwd, timeoutMs: 30_000 });
+				if (!passed(porcelain)) {
+					ctx.ui.notify(
+						"⚠️ `--candidates` needs a git repository (candidate patches are captured and arbitrated via git). Falling back to the single-candidate pipeline.",
+						"warning",
+					);
+					candidates = 1;
+				} else if (porcelain.stdout.trim()) {
+					ctx.ui.notify(
+						"⚠️ Your working tree has uncommitted changes — candidate arbitration resets the tree between attempts and will NOT run over them. Commit/stash first for multi-candidate. Falling back to the single-candidate pipeline.",
+						"warning",
+					);
+					candidates = 1;
+				}
+			}
+
 			await ensurePlansDir();
-			const phases = buildDebugPhases(state);
+			const phases = buildDebugPhases(state, candidates);
+			if (candidates > 1) {
+				candidateContext = {
+					total: candidates,
+					reproCmd: state.failingTest?.trim() || state.reproCommand?.trim() || undefined,
+					list: [],
+					arbitrated: false,
+				};
+			}
 			startGenericOrchestration(
 				"debug",
 				phases,
 				ctx,
-				`🐛 **/debug started** — 4 execution-grounded phases (verdict requires a real run)\n`,
+				candidates > 1
+					? `🐛 **/debug started (multi-candidate ×${candidates})** — REPRODUCE → LOCALIZE → ${candidates} independent FIXes → real-run arbitration\n`
+					: `🐛 **/debug started** — 4 execution-grounded phases (verdict requires a real run)\n`,
+			);
+		},
+	});
+
+	// ─── /fix Command — single-shot first, oracle next, escalate on red ──
+	// Measured (n=13, official SWE-bench harness): the single shot resolved 7/13
+	// vs the full pipeline's 6/13 at ~2.5× the time, and both arms converged on
+	// 11/13. /fix is the composition: by construction never worse than the
+	// single shot, and it inherits the pipeline exactly where a REAL red run
+	// proves the shot failed.
+
+	pi.registerCommand("fix", {
+		description:
+			"Fix at single-shot cost, verified by the sandbox oracle — escalates to the full /debug pipeline only if a real run stays red",
+		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:** \`/fix <failing test | repro command | description>\`
+
+/fix = one direct attempt, then the ORACLE (reproduction + suite in the sandbox):
+  green → done at single-shot cost;
+  red   → the full /debug pipeline takes over, seeded with the red run.
+**Examples:**
+  /fix pytest tests/test_auth.py::test_login_returns_jwt
+  /fix node repro.js  (crashes on empty input, should return [])
+  /fix the /login route 500s when the body is missing
+
+With no runnable check at all, the result is honestly labelled UNVERIFIED.`,
+					"info",
+				);
+				return;
+			}
+
+			const state: FailingState = parseFailingState(raw, { cwd: ctx.cwd || process.cwd() });
+			if (!state.failingTest && !state.reproCommand) {
+				ctx.ui.notify(
+					`⚠️ No failing test or repro command detected — the /fix oracle will rely on the project suite alone (or report UNVERIFIED if none is known). A concrete repro gives a guaranteed verdict.`,
+					"warning",
+				);
+			}
+
+			await ensurePlansDir();
+			fixContext = { state, oracleRan: false };
+			const shot = genericPhase("shot", "🎯 Phase 1 — SINGLE SHOT", "code", "code", singleShotInstruction(state));
+			startGenericOrchestration(
+				"fix",
+				[shot],
+				ctx,
+				`🎯 **/fix started** — single shot, then the sandbox oracle decides (green = done, red = full pipeline)\n`,
 			);
 		},
 	});

package/extensions/phi/providers/debug-build-commands.ts

@@ -53,6 +53,7 @@ ${failing}
 
 **Do exactly this:**
 1. Run the reproduction on the CURRENT, unmodified code with the \`sandbox_run\` tool: \`sandbox_run ${repro}\`.
+   - If you must CONSTRUCT the reproduction (only a description was given): build it **literally from the issue** — copy the exact code snippets, inputs and expected values QUOTED in the issue text into a runnable script/test. Do NOT paraphrase the issue into your own interpretation; a reproduction of your interpretation validates your interpretation, not the bug (measured failure mode).
 2. Paste the exact command and its full output.
 3. Decide from what \`sandbox_run\` returned:
    - If it FAILS as reported → capture the precise symptom (assertion, exception, exit code) and hand off to LOCALIZE.
@@ -60,8 +61,10 @@ ${failing}
    - If \`sandbox_run\` reports \`SANDBOX UNAVAILABLE\` → STOP. Write \`BLOCKED: no executable environment\`.
 4. Do NOT edit any source yet. This phase only observes.
 5. **BLOCKED is a last resort, not a first reaction.** If a run fails for an infrastructure-looking reason (tool error, missing file you guessed wrong, transient failure), adjust and retry at least once — e.g. locate the real test paths, try an alternative reproduction — before concluding. Only report BLOCKED after a genuine attempt showed the state is not reproducible or not runnable.
-6. **Last action:** call \`phase_result\` — \`verdict: PASS\` if it reproduced (proceed to LOCALIZE), or \`verdict: BLOCKED\` with the reason if you stopped.` +
-			DEBUG_RULES,
+6. **Last action:** call \`phase_result\` — \`verdict: PASS\` if it reproduced (proceed to LOCALIZE), or \`verdict: BLOCKED\` with the reason if you stopped. Your handoff MUST contain a line with the EXACT command that reproduces the failure, in this machine-readable form (the orchestrator re-runs it to arbitrate candidate fixes):
+\`\`\`
+REPRO-CMD: <the exact command, e.g. python /testbed/repro_issue.py>
+\`\`\`` + DEBUG_RULES,
 
 		localize: `You are the LOCALIZE agent (phase 2 of /debug). Drive from the REAL symptom the previous phase captured.
 
@@ -69,10 +72,11 @@ ${failing}
 ${failing}
 
 **Do exactly this:**
-1. Read the traceback / error from the reproduction. Follow it to the exact frame.
-2. Read the implicated source and the symbols it touches (grep the nearby/changed identifiers).
-3. Name the fault site precisely — file:line and the wrong assumption. Localization, not more review, is the lever here.
-4. Hand off a crisp fault description; do NOT fix yet.${DEBUG_RULES}`,
+1. Call \`memory_search\` with the failing symbol/module names — a previous run may have already localized this area or a related failure.
+2. Read the traceback / error from the reproduction. Follow it to the exact frame.
+3. Read the implicated source and the symbols it touches (grep the nearby/changed identifiers).
+4. Name the fault site precisely — file:line and the wrong assumption. Localization, not more review, is the lever here.
+5. Hand off a crisp fault description; do NOT fix yet. Call \`memory_write\` with the fault site so future runs on this project start ahead.${DEBUG_RULES}`,
 
 		fix:
 			`You are the FIX agent (phase 3 of /debug). Produce the MINIMAL change that addresses the located root cause.
@@ -107,6 +111,29 @@ Reason: <only when BLOCKED>
 	};
 }
 
+/**
+ * The /fix single-shot phase — the measured-cheapest first attempt. One agent
+ * fixes directly (baseline cost); the DRIVER then oracle-checks the result
+ * deterministically (sandbox repro + suite) and escalates to the full /debug
+ * pipeline only if a real run is red. Measured rationale: the single shot
+ * resolved 7/13 vs the full pipeline's 6/13 at ~2.5× the time — so pay the
+ * pipeline only when a real run proves the shot failed.
+ */
+export function singleShotInstruction(state: FailingState): string {
+	const failing = formatFailingState(state);
+	return `You are the FIX agent (single shot — /fix phase 1). Fix the problem directly, with the MINIMAL change.
+
+**The problem:**
+${failing}
+
+**Do exactly this:**
+1. Read the relevant code and locate the root cause.
+2. Make the smallest change that addresses it. Do NOT edit tests. Every added guard/branch is a liability.
+3. You MAY use \`sandbox_run\` to check your work (the project's real environment) — recommended when a command is available.
+4. After your change, the orchestrator will run the reproduction and the project suite in the sandbox itself: your work is judged by those REAL runs, not by your confidence. If they are red, a full diagnostic pipeline takes over from your change.
+5. **Last action:** call \`phase_result\` with \`verdict: PASS\` and a one-line handoff describing what you changed and why.${DEBUG_RULES}`;
+}
+
 /**
  * The /build execution-grounded verify phase: run the recipe, check acceptance,
  * red-team the boundary the change touched, and route real failures to /debug.

package/extensions/phi/providers/escalation.ts

@@ -0,0 +1,117 @@
+/**
+ * Escalation core — the pure decisions behind /fix (single-shot first, oracle
+ * next, escalate to /debug only on red).
+ *
+ * Measured rationale (n=13, official SWE-bench harness): the single-shot
+ * baseline resolved 7/13 while the full /debug pipeline resolved 6/13 at ~2.5×
+ * the time — and on 11/13 instances both arms converged to the same verdict.
+ * So the right architecture is neither: pay the single-shot price always, pay
+ * the pipeline price only when a REAL run says the single shot failed. By
+ * construction /fix is never worse than the baseline, and inherits /debug's
+ * upside exactly where it can matter.
+ */
+
+import type { FailingState } from "./debug-contract.js";
+import { type CommandResult, passed, tail } from "./execution.js";
+
+export type EscalationDecision =
+	| { action: "done-green"; evidence: string }
+	| { action: "escalate"; failing: FailingState; diagnostic: string }
+	| { action: "done-unverified"; reason: string };
+
+export interface OracleRuns {
+	/** The reproduction run (null = no runnable reproduction was available). */
+	repro: CommandResult | null;
+	/** The project suite run (null = no suite command known). */
+	suite: CommandResult | null;
+}
+
+/**
+ * Decide after the single shot: green oracle → done at baseline cost; any red
+ * run → escalate to /debug with the red run as the concrete failing state
+ * (never a paraphrase — the exact command and its tail). Nothing runnable →
+ * done, honestly labelled unverified.
+ */
+export function decideEscalation(state: FailingState, runs: OracleRuns): EscalationDecision {
+	const { repro, suite } = runs;
+
+	if (repro !== null && !passed(repro)) {
+		return {
+			action: "escalate",
+			failing: {
+				...state,
+				reproCommand: state.failingTest?.trim() || state.reproCommand?.trim() || repro.command,
+				trace: tail(repro, 30),
+			},
+			diagnostic: `reproduction still red after the single shot: \`${repro.command}\` → exit ${repro.exitCode ?? "?"}${repro.timedOut ? " (TIMEOUT)" : ""}`,
+		};
+	}
+
+	if (suite !== null && !passed(suite)) {
+		return {
+			action: "escalate",
+			failing: {
+				...state,
+				failingTest: suite.command,
+				trace: tail(suite, 30),
+			},
+			diagnostic: `the suite is red after the single shot: \`${suite.command}\` → exit ${suite.exitCode ?? "?"}${suite.timedOut ? " (TIMEOUT)" : ""}`,
+		};
+	}
+
+	if (repro === null && suite === null) {
+		return {
+			action: "done-unverified",
+			reason: "no runnable reproduction and no known suite command — the single shot could not be oracle-checked",
+		};
+	}
+
+	const parts: string[] = [];
+	if (repro) parts.push(`repro \`${repro.command}\` → exit 0`);
+	if (suite) parts.push(`suite \`${suite.command}\` → exit 0`);
+	return { action: "done-green", evidence: parts.join("; ") };
+}
+
+/**
+ * Parse the `REPRO-CMD: <command>` line the REPRODUCE phase is instructed to
+ * put in its handoff, so the driver can re-run the exact reproduction
+ * deterministically (multi-candidate arbitration, /fix oracle). Returns
+ * undefined when absent/malformed — callers must degrade gracefully.
+ */
+export function parseReproCmd(handoff: string | null | undefined): string | undefined {
+	if (!handoff) return undefined;
+	const m = handoff.match(/^\s*REPRO-CMD:\s*(.+)\s*$/im);
+	const cmd = m?.[1]?.trim();
+	return cmd && cmd.length > 1 ? cmd : undefined;
+}
+
+/** Minimal shape of routing.json this module needs (kept structural). */
+export interface RoutingLike {
+	routes?: Record<string, { preferredModel?: string; fallback?: string } | undefined>;
+	default?: { model?: string };
+}
+
+/**
+ * Pick up to `n` DISTINCT model refs for candidate generation, favouring family
+ * diversity: the coder first (it knows the task), then reviewer/test/explore
+ * families, then fallbacks. Diversity proposes — the oracle disposes.
+ */
+export function pickCandidateModels(routing: RoutingLike, n: number): string[] {
+	const routes = routing.routes ?? {};
+	const ordered = [
+		routes.code?.preferredModel,
+		routes.review?.preferredModel,
+		routes.test?.preferredModel,
+		routes.explore?.preferredModel,
+		routes.code?.fallback,
+		routes.review?.fallback,
+		routes.test?.fallback,
+		routing.default?.model,
+	];
+	const out: string[] = [];
+	for (const ref of ordered) {
+		if (typeof ref === "string" && ref.trim() && !out.includes(ref)) out.push(ref);
+		if (out.length >= n) break;
+	}
+	return out.slice(0, Math.max(1, n));
+}

package/extensions/phi/providers/telemetry.ts

@@ -0,0 +1,75 @@
+/**
+ * Run telemetry — one JSONL line per orchestration run (.phi/runs.jsonl), so
+ * "how do /fix //debug //build actually behave over time?" is answered by
+ * appending to a file on every run instead of mounting a measurement campaign.
+ * Pure record building here; the single append call-site lives in the driver.
+ */
+
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export interface PhaseRecord {
+	key: string;
+	label: string;
+	model: string;
+	verdict: string | null;
+	retried: boolean;
+	blockedRetried: boolean;
+}
+
+export interface RunRecord {
+	mode: string;
+	startedAt: string;
+	durationMs: number;
+	phases: PhaseRecord[];
+	completedPhases: number;
+	skippedPhases: number;
+	sandboxExecs: number;
+	outcome: string;
+}
+
+/** Build the run record (pure — timestamps/durations are supplied). */
+export function buildRunRecord(input: {
+	mode: string;
+	startedAtMs: number | null;
+	endedAtMs: number;
+	phases: PhaseRecord[];
+	completedPhases: number;
+	skippedPhases: number;
+	sandboxExecs: number;
+	outcome: string;
+}): RunRecord {
+	const started = input.startedAtMs ?? input.endedAtMs;
+	return {
+		mode: input.mode,
+		startedAt: new Date(started).toISOString(),
+		durationMs: Math.max(0, input.endedAtMs - started),
+		phases: input.phases,
+		completedPhases: input.completedPhases,
+		skippedPhases: input.skippedPhases,
+		sandboxExecs: input.sandboxExecs,
+		// Strip markdown noise; keep the headline single-line and bounded.
+		outcome: input.outcome
+			.replace(/\*\*|`/g, "")
+			.replace(/\s+/g, " ")
+			.trim()
+			.slice(0, 300),
+	};
+}
+
+/** Serialize for JSONL (single line, newline-terminated). */
+export function toJsonlLine(record: RunRecord): string {
+	return `${JSON.stringify(record)}\n`;
+}
+
+/** Append a run record to <cwd>/.phi/runs.jsonl. Best-effort — never throws. */
+export function appendRunRecord(cwd: string, record: RunRecord): boolean {
+	try {
+		const file = join(cwd, ".phi", "runs.jsonl");
+		mkdirSync(dirname(file), { recursive: true });
+		appendFileSync(file, toJsonlLine(record), "utf-8");
+		return true;
+	} catch {
+		return false;
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@phi-code-admin/phi-code",
-	"version": "0.92.0",
+	"version": "0.93.0",
 	"description": "Coding agent CLI with persistent memory, sub-agents, intelligent routing, and orchestration",
 	"type": "module",
 	"piConfig": {