@phi-code-admin/phi-code 0.91.0 → 0.92.1

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## [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
+
+The measured head-to-head (baseline 7/13 vs /debug 6/13, official harness) traced
+/debug's two lost points to concrete, reparable defects — both fixed here.
+
+- **Hasty BLOCKED (sympy-11897, halted at 51s).** The generic /debug//build
+  driver now routes phase completion through the same pure decision machine as
+  /plan (`decidePhaseTransition`), gaining what it measurably lacked: a fatal
+  401 stops the run, a transient provider error (timeout / 5xx / 429 / broken
+  stream) retries the SAME phase once on the fallback model instead of being
+  swallowed, and — new — a BLOCKED verdict gets ONE second chance on the
+  fallback model (a different family re-checks the reproduction) before the
+  halt. A confirmed second BLOCKED still halts honestly: no fabricated fix.
+  REPRODUCE's instructions now state BLOCKED is a last resort — adjust and
+  retry once before concluding.
+- **Timeout-blind VERIFY (sympy-11870, fix passed its repro but hung the real
+  suite for 900s).** VERIFY's instructions now treat a TIMEOUT of the
+  reproduction or the suite as a FAILURE of the candidate — a massive slowdown
+  or infinite loop IS a regression — with verdict BLOCKED, never FIXED. A
+  dramatic duration increase below the timeout is flagged as a red flag too.
+
+8 integration tests cover the new behaviours (BLOCKED retry → honest halt,
+BLOCKED retry → proceed on success, transient-error retry); full suite green
+(1439).
+
 ## [0.91.0] - 2026-07-11
 
 ### Added — Alibaba Cloud Coding Plan, first-class and one-command

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,59 @@ 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 |
+|---|---|---|
+| `/plan <spec>` | Plan AND build a project | EXPLORE → PLAN → CODE → TEST → REVIEW |
+| `/debug <failing test \| repro \| description>` | Turn a REAL failure green | REPRODUCE → LOCALIZE → FIX → 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. These modes are
+shipped as *tools with honest failure modes*, not as a claimed benchmark win;
+the measurement lives in the repo and is re-runnable.
+
+---
+
 ## Interactive Mode
 
 <p align="center"><img src="docs/images/interactive-mode.png" alt="Interactive Mode" width="600"></p>

package/extensions/phi/orchestrator.ts

@@ -284,6 +284,11 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 		// Set true once this phase has been retried once (transient proxy failure /
 		// timeout / 0-tool-call). Hard cap of one retry per phase.
 		retried?: boolean;
+		// Generic driver (/debug, /build) only: set true once this phase was re-run
+		// after a BLOCKED verdict. One second chance on the fallback model — a hasty
+		// BLOCKED (measured: 51s on sympy-11897) is cheaper to re-check than to
+		// trust — then the halt is honest.
+		blockedRetried?: boolean;
 		// 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;
@@ -1323,13 +1328,63 @@ Tag the note with relevant keywords for vector search.
 			phaseTimeoutId = null;
 		}
 
-		// A BLOCKED verdict (REPRODUCE cannot reproduce / VERIFY could not confirm)
-		// halts the pipeline honestly — no fabricated success.
+		// Route through the SAME pure decision machine as /plan so the generic
+		// driver gets the protections it was measured to lack (sympy-11897, a 51s
+		// hasty halt): fatal 401 stop, one retry on a transient provider error.
 		const structuredForThisPhase = currentPhaseResultKey === (currentPhase?.key ?? null) ? currentPhaseResult : null;
 		const outcome = resolvePhaseOutcome(structuredForThisPhase, null);
-		if (outcome.verdict === "BLOCKED" && currentPhase) {
+		const decision = decidePhaseTransition({
+			analysis,
+			phase: currentPhase ? { key: currentPhase.key, retried: currentPhase.retried } : null,
+			verdict: outcome.verdict,
+			// The generic driver has no review-fix cycle; pass the cap as spent.
+			reviewFixRounds: 1,
+			maxToolCallsPerPhase: MAX_TOOL_CALLS_PER_PHASE,
+		});
+
+		if (decision.action === "stop") {
+			ctx.ui.notify(
+				`\n❌ **/${orchestrationMode} aborted:** API authentication error (401). Check your API key.`,
+				"error",
+			);
+			finishGenericOrchestration(ctx, `❌ **/${orchestrationMode} aborted (auth error).**`);
+			return;
+		}
+
+		if (decision.action === "retry-fallback" && currentPhase) {
+			// Transient provider failure (timeout / 5xx / 429 / broken stream): retry
+			// the SAME phase once on the fallback model before treating any of its
+			// output as a real outcome.
+			currentPhase.retried = true;
+			currentPhase.useFallback = true;
+			phaseQueue.unshift(currentPhase);
+			phasePending = false;
+			ctx.ui.notify(
+				`\n🔁 **Transient provider error** in ${currentPhase.label} — retrying once on the fallback model.`,
+				"warning",
+			);
+			sendNextGenericPhase(ctx);
+			return;
+		}
+
+		// BLOCKED (REPRODUCE cannot reproduce / VERIFY could not confirm): give the
+		// phase ONE second chance on the fallback model — a hasty BLOCKED is cheaper
+		// to re-check than to trust — then halt honestly. No fabricated success.
+		if (decision.action === "pause-blocked" && currentPhase) {
+			if (!currentPhase.blockedRetried) {
+				currentPhase.blockedRetried = true;
+				currentPhase.useFallback = true;
+				phaseQueue.unshift(currentPhase);
+				phasePending = false;
+				ctx.ui.notify(
+					`\n🔁 **${currentPhase.label} reported BLOCKED on the first attempt** — retrying once on the fallback model before halting. ${outcome.handoff || ""}`,
+					"warning",
+				);
+				sendNextGenericPhase(ctx);
+				return;
+			}
 			ctx.ui.notify(
-				`\n⏸️ **${currentPhase.label} reported BLOCKED.** ${outcome.handoff || "No reproducible/verifiable result."}`,
+				`\n⏸️ **${currentPhase.label} reported BLOCKED (confirmed on retry).** ${outcome.handoff || "No reproducible/verifiable result."}`,
 				"warning",
 			);
 			finishGenericOrchestration(ctx, `⏸️ **/${orchestrationMode} stopped: BLOCKED at ${currentPhase.label}.**`);

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

@@ -59,7 +59,8 @@ ${failing}
    - If it PASSES → STOP. Write \`BLOCKED: cannot reproduce — passes on current code\` with the run pasted. Do not invent a bug.
    - If \`sandbox_run\` reports \`SANDBOX UNAVAILABLE\` → STOP. Write \`BLOCKED: no executable environment\`.
 4. Do NOT edit any source yet. This phase only observes.
-5. **Last action:** call \`phase_result\` — \`verdict: PASS\` if it reproduced (proceed to LOCALIZE), or \`verdict: BLOCKED\` with the reason if you stopped.` +
+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,
 
 		localize: `You are the LOCALIZE agent (phase 2 of /debug). Drive from the REAL symptom the previous phase captured.
@@ -96,6 +97,7 @@ ${failing}
 3. Verdict (from what \`sandbox_run\` returned, not from inspection):
    - Both green → \`FIXED\`, and paste the before(fail)/after(pass) reproduction runs and the green suite as evidence.
    - Reproduction still fails, or the suite regresses → \`BLOCKED\` with the closest diagnostic. Do NOT ship the least-bad patch; a wrong fix is worse than an honest BLOCKED.
+   - **A TIMEOUT counts as a FAILURE.** If the reproduction or the suite TIMES OUT with the fix applied (\`sandbox_run\` verdict TIMEOUT), the fix has introduced a massive slowdown or an infinite loop — that IS a regression (measured: a fix that passed its repro but made the real test suite hang for 900s). Verdict \`BLOCKED\`, never \`FIXED\`. Compare rough durations before/after: a check that got dramatically slower is a red flag even below the timeout.
 4. Write the final verdict block, then call \`phase_result\` with \`verdict: PASS\` (FIXED) or \`verdict: BLOCKED\`, plus a one-line handoff:
 \`\`\`
 VERDICT: FIXED | BLOCKED

package/package.json

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