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

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## [0.91.0] - 2026-07-11
+
+### Added — Alibaba Cloud Coding Plan, first-class and one-command
+
+The Alibaba Coding Plan support (endpoints, live catalog, ping, wizard) already
+existed but was only reachable through the interactive `/setup` wizard — a user
+could not simply add the provider. Verified against the official docs
+(https://www.alibabacloud.com/help/en/model-studio/coding-plan) and a live API
+round-trip (catalog listing + a real `qwen3.7-plus` completion).
+
+- **`/keys set` now bootstraps known providers.** `providers/provider-bootstrap.ts`
+  (pure, 11 tests) builds a complete first-time models.json entry — baseUrl, api
+  protocol, bundled model list — from a single API key, with each provider's own
+  key-format validation applied up front (`sk-sp-` prefix for Alibaba). One
+  command configures the provider end to end:
+  `/keys set alibaba-codingplan sk-sp-…` — then the session-start refresh
+  replaces the bundled list with the live catalog. Bootstrappable ids:
+  `alibaba-codingplan`, `alibaba-codingplan-anthropic`, `opencode-go`,
+  `opencode-go-anthropic`. Unknown providers keep the previous /setup guidance.
+- **`/keys test` now actually works.** `registerProviderPing` existed but nothing
+  ever called it; keys.ts now registers the built-in pings (Alibaba, OpenCode Go)
+  at load, so `/keys test alibaba-codingplan` validates the key against the real
+  `/v1/models` endpoint.
+- **Provider display names.** `alibaba-codingplan`, `alibaba-codingplan-anthropic`
+  and `opencode-go-anthropic` now render with proper names in the /model picker
+  (they fell back to raw ids).
+
+## [0.90.0] - 2026-07-11
+
+### Added — the execution sandbox (the guaranteed oracle)
+
+This is the infrastructure the 0.89.0 design (`docs/design/plan-debug-build.md`)
+called its "real investment": it turns `/debug` and `/build` from prompt-enforced
+discipline into a **guaranteed oracle**. The agent can no longer merely claim it
+ran the test — a real container runs it and returns the true exit code.
+
+- **`providers/sandbox-plan.ts` (pure, 29 tests)** — detects the project toolchain
+  (node / python / go / rust / ruby / Dockerfile), builds an environment recipe
+  (base image, dependency-install, test command, env), decides the backend
+  **honestly**, and constructs the `docker run` argv. The Windows path/quoting
+  pitfalls that defeated the earlier SWE-bench harness (bind-mount mangling,
+  stdlib shadowing) are handled here and unit-tested: `-v C:/…:/work`,
+  `PYTHONSAFEPATH=1`.
+- **`providers/sandbox.ts` (IO shell, 8 tests incl. a real-Docker smoke)** — the
+  `Sandbox` interface with three backends: `docker` (guaranteed environment),
+  `local` (real runs, but not dependency-guaranteed), and `unavailable` (honest —
+  every exec reports `SANDBOX UNAVAILABLE` so the modes emit `BLOCKED`, never a
+  fabricated pass). Ephemeral container, host bind-mount, so a `/debug` fix lands
+  on disk and the next run sees it. Docker is demanded-but-absent → `unavailable`,
+  never a silent downgrade.
+- **`sandbox_run` tool** — exposed to the `/debug` and `/build` phase agents. The
+  reproduction, the suite, and acceptance/red-team checks run through it; the
+  verdict is tied to its structured result (`passed`, real `exitCode`), not to the
+  model's prose. `execution.ts` gained `runArgv` (no-shell argv spawn) for safe
+  `docker` invocation.
+- **`/sandbox` command** — `status` (detected toolchain, backend, recipe),
+  `prepare` (pull image / build Dockerfile / install deps), `run <cmd>` (one-off).
+  A `.phi/sandbox.json` overrides everything (image, setup, test, backend, memory,
+  cpus, network).
+
+50 new tests (1425 total, green). The `/debug` and `/build` phase instructions now
+route every oracle run through `sandbox_run` and downgrade to `BLOCKED` when the
+sandbox is unavailable.
+
+### Still honest
+
+The sandbox makes the thesis **measurable** — it is the missing piece that let the
+model self-grade before. It does not by itself prove `/debug` beats a single shot;
+that is now a runnable measurement (containerized SWE-bench-lite with `sandbox_run`
+as the oracle), and it is the next step, not a claim made here.
+
 ## [0.89.0] - 2026-07-11
 
 ### Added

package/dist/core/provider-display-names.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider-display-names.d.ts","sourceRoot":"","sources":["../../src/core/provider-display-names.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,+BAA+B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA+BlE,CAAC","sourcesContent":["export const BUILT_IN_PROVIDER_DISPLAY_NAMES: Record<string, string> = {\n\tanthropic: \"Anthropic\",\n\t\"amazon-bedrock\": \"Amazon Bedrock\",\n\t\"azure-openai-responses\": \"Azure OpenAI Responses\",\n\tcerebras: \"Cerebras\",\n\t\"cloudflare-ai-gateway\": \"Cloudflare AI Gateway\",\n\t\"cloudflare-workers-ai\": \"Cloudflare Workers AI\",\n\tdeepseek: \"DeepSeek\",\n\tfireworks: \"Fireworks\",\n\tgoogle: \"Google Gemini\",\n\t\"google-vertex\": \"Google Vertex AI\",\n\tgroq: \"Groq\",\n\thuggingface: \"Hugging Face\",\n\t\"kimi-coding\": \"Kimi For Coding\",\n\tmistral: \"Mistral\",\n\tminimax: \"MiniMax\",\n\t\"minimax-cn\": \"MiniMax (China)\",\n\tmoonshotai: \"Moonshot AI\",\n\t\"moonshotai-cn\": \"Moonshot AI (China)\",\n\topencode: \"OpenCode Zen\",\n\t\"opencode-go\": \"OpenCode Go\",\n\topenai: \"OpenAI\",\n\topenrouter: \"OpenRouter\",\n\ttogether: \"Together AI\",\n\t\"vercel-ai-gateway\": \"Vercel AI Gateway\",\n\txai: \"xAI\",\n\tzai: \"ZAI\",\n\txiaomi: \"Xiaomi MiMo\",\n\t\"xiaomi-token-plan-cn\": \"Xiaomi MiMo Token Plan (China)\",\n\t\"xiaomi-token-plan-ams\": \"Xiaomi MiMo Token Plan (Amsterdam)\",\n\t\"xiaomi-token-plan-sgp\": \"Xiaomi MiMo Token Plan (Singapore)\",\n};\n"]}
+{"version":3,"file":"provider-display-names.d.ts","sourceRoot":"","sources":["../../src/core/provider-display-names.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,+BAA+B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAkClE,CAAC","sourcesContent":["export const BUILT_IN_PROVIDER_DISPLAY_NAMES: Record<string, string> = {\n\t\"alibaba-codingplan\": \"Alibaba Coding Plan\",\n\t\"alibaba-codingplan-anthropic\": \"Alibaba Coding Plan (Anthropic-compat)\",\n\tanthropic: \"Anthropic\",\n\t\"amazon-bedrock\": \"Amazon Bedrock\",\n\t\"azure-openai-responses\": \"Azure OpenAI Responses\",\n\tcerebras: \"Cerebras\",\n\t\"cloudflare-ai-gateway\": \"Cloudflare AI Gateway\",\n\t\"cloudflare-workers-ai\": \"Cloudflare Workers AI\",\n\tdeepseek: \"DeepSeek\",\n\tfireworks: \"Fireworks\",\n\tgoogle: \"Google Gemini\",\n\t\"google-vertex\": \"Google Vertex AI\",\n\tgroq: \"Groq\",\n\thuggingface: \"Hugging Face\",\n\t\"kimi-coding\": \"Kimi For Coding\",\n\tmistral: \"Mistral\",\n\tminimax: \"MiniMax\",\n\t\"minimax-cn\": \"MiniMax (China)\",\n\tmoonshotai: \"Moonshot AI\",\n\t\"moonshotai-cn\": \"Moonshot AI (China)\",\n\topencode: \"OpenCode Zen\",\n\t\"opencode-go\": \"OpenCode Go\",\n\t\"opencode-go-anthropic\": \"OpenCode Go (Anthropic-compat)\",\n\topenai: \"OpenAI\",\n\topenrouter: \"OpenRouter\",\n\ttogether: \"Together AI\",\n\t\"vercel-ai-gateway\": \"Vercel AI Gateway\",\n\txai: \"xAI\",\n\tzai: \"ZAI\",\n\txiaomi: \"Xiaomi MiMo\",\n\t\"xiaomi-token-plan-cn\": \"Xiaomi MiMo Token Plan (China)\",\n\t\"xiaomi-token-plan-ams\": \"Xiaomi MiMo Token Plan (Amsterdam)\",\n\t\"xiaomi-token-plan-sgp\": \"Xiaomi MiMo Token Plan (Singapore)\",\n};\n"]}

package/dist/core/provider-display-names.js

@@ -1,4 +1,6 @@
 export const BUILT_IN_PROVIDER_DISPLAY_NAMES = {
+    "alibaba-codingplan": "Alibaba Coding Plan",
+    "alibaba-codingplan-anthropic": "Alibaba Coding Plan (Anthropic-compat)",
     anthropic: "Anthropic",
     "amazon-bedrock": "Amazon Bedrock",
     "azure-openai-responses": "Azure OpenAI Responses",
@@ -19,6 +21,7 @@ export const BUILT_IN_PROVIDER_DISPLAY_NAMES = {
     "moonshotai-cn": "Moonshot AI (China)",
     opencode: "OpenCode Zen",
     "opencode-go": "OpenCode Go",
+    "opencode-go-anthropic": "OpenCode Go (Anthropic-compat)",
     openai: "OpenAI",
     openrouter: "OpenRouter",
     together: "Together AI",

package/dist/core/provider-display-names.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider-display-names.js","sourceRoot":"","sources":["../../src/core/provider-display-names.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,+BAA+B,GAA2B;IACtE,SAAS,EAAE,WAAW;IACtB,gBAAgB,EAAE,gBAAgB;IAClC,wBAAwB,EAAE,wBAAwB;IAClD,QAAQ,EAAE,UAAU;IACpB,uBAAuB,EAAE,uBAAuB;IAChD,uBAAuB,EAAE,uBAAuB;IAChD,QAAQ,EAAE,UAAU;IACpB,SAAS,EAAE,WAAW;IACtB,MAAM,EAAE,eAAe;IACvB,eAAe,EAAE,kBAAkB;IACnC,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,cAAc;IAC3B,aAAa,EAAE,iBAAiB;IAChC,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,YAAY,EAAE,iBAAiB;IAC/B,UAAU,EAAE,aAAa;IACzB,eAAe,EAAE,qBAAqB;IACtC,QAAQ,EAAE,cAAc;IACxB,aAAa,EAAE,aAAa;IAC5B,MAAM,EAAE,QAAQ;IAChB,UAAU,EAAE,YAAY;IACxB,QAAQ,EAAE,aAAa;IACvB,mBAAmB,EAAE,mBAAmB;IACxC,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,MAAM,EAAE,aAAa;IACrB,sBAAsB,EAAE,gCAAgC;IACxD,uBAAuB,EAAE,oCAAoC;IAC7D,uBAAuB,EAAE,oCAAoC;CAC7D,CAAC","sourcesContent":["export const BUILT_IN_PROVIDER_DISPLAY_NAMES: Record<string, string> = {\n\tanthropic: \"Anthropic\",\n\t\"amazon-bedrock\": \"Amazon Bedrock\",\n\t\"azure-openai-responses\": \"Azure OpenAI Responses\",\n\tcerebras: \"Cerebras\",\n\t\"cloudflare-ai-gateway\": \"Cloudflare AI Gateway\",\n\t\"cloudflare-workers-ai\": \"Cloudflare Workers AI\",\n\tdeepseek: \"DeepSeek\",\n\tfireworks: \"Fireworks\",\n\tgoogle: \"Google Gemini\",\n\t\"google-vertex\": \"Google Vertex AI\",\n\tgroq: \"Groq\",\n\thuggingface: \"Hugging Face\",\n\t\"kimi-coding\": \"Kimi For Coding\",\n\tmistral: \"Mistral\",\n\tminimax: \"MiniMax\",\n\t\"minimax-cn\": \"MiniMax (China)\",\n\tmoonshotai: \"Moonshot AI\",\n\t\"moonshotai-cn\": \"Moonshot AI (China)\",\n\topencode: \"OpenCode Zen\",\n\t\"opencode-go\": \"OpenCode Go\",\n\topenai: \"OpenAI\",\n\topenrouter: \"OpenRouter\",\n\ttogether: \"Together AI\",\n\t\"vercel-ai-gateway\": \"Vercel AI Gateway\",\n\txai: \"xAI\",\n\tzai: \"ZAI\",\n\txiaomi: \"Xiaomi MiMo\",\n\t\"xiaomi-token-plan-cn\": \"Xiaomi MiMo Token Plan (China)\",\n\t\"xiaomi-token-plan-ams\": \"Xiaomi MiMo Token Plan (Amsterdam)\",\n\t\"xiaomi-token-plan-sgp\": \"Xiaomi MiMo Token Plan (Singapore)\",\n};\n"]}
+{"version":3,"file":"provider-display-names.js","sourceRoot":"","sources":["../../src/core/provider-display-names.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,+BAA+B,GAA2B;IACtE,oBAAoB,EAAE,qBAAqB;IAC3C,8BAA8B,EAAE,wCAAwC;IACxE,SAAS,EAAE,WAAW;IACtB,gBAAgB,EAAE,gBAAgB;IAClC,wBAAwB,EAAE,wBAAwB;IAClD,QAAQ,EAAE,UAAU;IACpB,uBAAuB,EAAE,uBAAuB;IAChD,uBAAuB,EAAE,uBAAuB;IAChD,QAAQ,EAAE,UAAU;IACpB,SAAS,EAAE,WAAW;IACtB,MAAM,EAAE,eAAe;IACvB,eAAe,EAAE,kBAAkB;IACnC,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,cAAc;IAC3B,aAAa,EAAE,iBAAiB;IAChC,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,YAAY,EAAE,iBAAiB;IAC/B,UAAU,EAAE,aAAa;IACzB,eAAe,EAAE,qBAAqB;IACtC,QAAQ,EAAE,cAAc;IACxB,aAAa,EAAE,aAAa;IAC5B,uBAAuB,EAAE,gCAAgC;IACzD,MAAM,EAAE,QAAQ;IAChB,UAAU,EAAE,YAAY;IACxB,QAAQ,EAAE,aAAa;IACvB,mBAAmB,EAAE,mBAAmB;IACxC,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,MAAM,EAAE,aAAa;IACrB,sBAAsB,EAAE,gCAAgC;IACxD,uBAAuB,EAAE,oCAAoC;IAC7D,uBAAuB,EAAE,oCAAoC;CAC7D,CAAC","sourcesContent":["export const BUILT_IN_PROVIDER_DISPLAY_NAMES: Record<string, string> = {\n\t\"alibaba-codingplan\": \"Alibaba Coding Plan\",\n\t\"alibaba-codingplan-anthropic\": \"Alibaba Coding Plan (Anthropic-compat)\",\n\tanthropic: \"Anthropic\",\n\t\"amazon-bedrock\": \"Amazon Bedrock\",\n\t\"azure-openai-responses\": \"Azure OpenAI Responses\",\n\tcerebras: \"Cerebras\",\n\t\"cloudflare-ai-gateway\": \"Cloudflare AI Gateway\",\n\t\"cloudflare-workers-ai\": \"Cloudflare Workers AI\",\n\tdeepseek: \"DeepSeek\",\n\tfireworks: \"Fireworks\",\n\tgoogle: \"Google Gemini\",\n\t\"google-vertex\": \"Google Vertex AI\",\n\tgroq: \"Groq\",\n\thuggingface: \"Hugging Face\",\n\t\"kimi-coding\": \"Kimi For Coding\",\n\tmistral: \"Mistral\",\n\tminimax: \"MiniMax\",\n\t\"minimax-cn\": \"MiniMax (China)\",\n\tmoonshotai: \"Moonshot AI\",\n\t\"moonshotai-cn\": \"Moonshot AI (China)\",\n\topencode: \"OpenCode Zen\",\n\t\"opencode-go\": \"OpenCode Go\",\n\t\"opencode-go-anthropic\": \"OpenCode Go (Anthropic-compat)\",\n\topenai: \"OpenAI\",\n\topenrouter: \"OpenRouter\",\n\ttogether: \"Together AI\",\n\t\"vercel-ai-gateway\": \"Vercel AI Gateway\",\n\txai: \"xAI\",\n\tzai: \"ZAI\",\n\txiaomi: \"Xiaomi MiMo\",\n\t\"xiaomi-token-plan-cn\": \"Xiaomi MiMo Token Plan (China)\",\n\t\"xiaomi-token-plan-ams\": \"Xiaomi MiMo Token Plan (Amsterdam)\",\n\t\"xiaomi-token-plan-sgp\": \"Xiaomi MiMo Token Plan (Singapore)\",\n};\n"]}

package/docs/design/plan-debug-build.md

@@ -200,6 +200,18 @@ too-new Python — exactly what defeated the 3362 measurement), the modes must:
 Reusing phi's `run` / `verify` skills for local projects is the first target;
 a per-project container is the general solution.
 
+**Status (2026-07-11): implemented.** `providers/sandbox-plan.ts` (pure: toolchain
+detection → recipe → backend decision → `docker run` argv) and `providers/sandbox.ts`
+(the `Sandbox` IO shell: `docker` | `local` | `unavailable`) provide the guaranteed
+environment. The `sandbox_run` tool exposes it to the /debug and /build phase agents
+— the reproduction, the suite, and acceptance/red-team checks now run in a real
+container and return its true exit code, so a PASS cannot be asserted, only earned.
+When Docker is absent and nothing is containerizable, the backend is `unavailable`
+and every `sandbox_run` returns `SANDBOX UNAVAILABLE`, which the phase instructions
+turn into `BLOCKED` — never a fabricated pass. The `/sandbox` command
+(`status` | `prepare` | `run`) inspects and provisions it. A `.phi/sandbox.json`
+overrides detection (image, setup, test, backend, resource caps).
+
 ---
 
 ## Triage / adaptive depth (cost discipline)
@@ -244,6 +256,11 @@ contract above; (2) make `acceptance[]` + `runRecipe` first-class /plan outputs;
 the real-run verify path. Items 1–4 are prompt/orchestration changes on existing
 machinery; item 5 is the real infrastructure investment.
 
+Status: (1)–(4) shipped in 0.89.0; (5) the execution sandbox shipped in 0.90.0
+(`providers/sandbox*.ts`, the `sandbox_run` tool, `/sandbox`). What remains is the
+*measurement*: running /debug against a containerized SWE-bench-lite with the
+sandbox as the oracle, to get the number.
+
 ## How we will know it worked (this must be measured, not shipped on faith)
 
 - `/debug`: on SWE-bench-lite (bug-fixing), with a real executable environment,

package/extensions/phi/keys.ts

@@ -21,6 +21,9 @@
  */
 
 import { ApiKeyStore, type ExtensionAPI, getApiKeyStore, getConfigWatcher } from "phi-code";
+import { pingAlibaba } from "./providers/alibaba.js";
+import { pingOpenCodeGo } from "./providers/opencode-go.js";
+import { bootstrapProviderConfig, isBootstrappableProvider } from "./providers/provider-bootstrap.js";
 
 type ProviderPingFn = (key: string, timeoutMs?: number) => Promise<{ ok: boolean; error?: string }>;
 
@@ -38,6 +41,13 @@ export default function keysExtension(pi: ExtensionAPI) {
 	const store = getApiKeyStore();
 	const watcher = getConfigWatcher();
 
+	// Built-in pings so `/keys test <id>` works out of the box for the providers
+	// phi ships builders for (previously nothing ever registered a ping).
+	registerProviderPing("alibaba-codingplan", pingAlibaba);
+	registerProviderPing("alibaba-codingplan-anthropic", pingAlibaba);
+	registerProviderPing("opencode-go", pingOpenCodeGo);
+	registerProviderPing("opencode-go-anthropic", pingOpenCodeGo);
+
 	pi.registerCommand("keys", {
 		description: "Manage API keys (list / set / remove / test / reload)",
 		handler: async (args, ctx) => {
@@ -75,15 +85,35 @@ export default function keysExtension(pi: ExtensionAPI) {
 						return;
 					}
 					// A bare `set` only updates the key; it cannot supply baseUrl/api/models.
-					// For a never-configured id this would persist an unusable provider
-					// (apiKey but no endpoint), so require an existing entry with a baseUrl.
+					// For a never-configured id: bootstrap the full entry when phi ships a
+					// builder for it (Alibaba Coding Plan, OpenCode Go); otherwise keep the
+					// old behaviour and point at /setup.
 					const existing = store.getProvider(id);
 					if (!existing?.baseUrl) {
+						if (!isBootstrappableProvider(id)) {
+							ctx.ui.notify(
+								`\`${id}\` is not a configured provider (no baseUrl on file). ` +
+									`Run \`/setup\` to add it with an endpoint and models first; ` +
+									`\`/keys set\` only updates the key of an already-configured provider.`,
+								"warning",
+							);
+							return;
+						}
+						const boot = bootstrapProviderConfig(id, key);
+						if (!boot.ok) {
+							ctx.ui.notify(`Cannot configure \`${id}\`: ${boot.error}`, "warning");
+							return;
+						}
+						watcher.muteForWrite("models_json_changed");
+						store.setKey(id, key, {
+							baseUrl: boot.config.baseUrl,
+							api: boot.config.api,
+							models: boot.config.models,
+						});
 						ctx.ui.notify(
-							`\`${id}\` is not a configured provider (no baseUrl on file). ` +
-								`Run \`/setup\` to add it with an endpoint and models first; ` +
-								`\`/keys set\` only updates the key of an already-configured provider.`,
-							"warning",
+							`Configured \`${id}\` (\`${ApiKeyStore.maskKey(key)}\`) — ${boot.note}\n` +
+								`Stored in ${store.configPath}. Use \`/keys test ${id}\` to validate, then pick a model with \`/model\`.`,
+							"info",
 						);
 						return;
 					}

package/extensions/phi/orchestrator.ts

@@ -25,6 +25,7 @@ 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,
@@ -33,6 +34,7 @@ import {
 	resolvePhaseOutcome,
 	type StructuredPhaseResult,
 } from "./providers/phase-machine.js";
+import { resolveSandbox, type Sandbox } from "./providers/sandbox.js";
 import { triage } from "./providers/triage.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────
@@ -390,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.
@@ -940,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;
@@ -1867,4 +1930,69 @@ It reports SUCCESS only when a real run meets the acceptance criteria — otherw
 			);
 		},
 	});
+
+	// ─── /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/debug-build-commands.ts

@@ -33,7 +33,8 @@ const DEBUG_RULES = `
 ---
 ## /debug operating rules (non-negotiable)
 - **Execution is the only oracle.** No verdict without a real run whose output you paste. Never write FIXED because the code "looks right".
-- **No fabricated PASS.** If you cannot run the reproduction (missing env/deps), emit \`BLOCKED: no executable environment\` — do NOT reconstruct a mock and grade your own reconstruction.
+- **Use the \`sandbox_run\` tool for every oracle run** (reproduction, suite, acceptance). It runs in the project's guaranteed environment and returns the REAL exit code — a PASS means \`sandbox_run\` returned exit 0, nothing less.
+- **No fabricated PASS.** If \`sandbox_run\` reports \`SANDBOX UNAVAILABLE\` (or you otherwise cannot run the reproduction), emit \`BLOCKED: no executable environment\` — do NOT reconstruct a mock and grade your own reconstruction.
 - **Minimal fix wins.** Prefer the smallest change; every added guard/condition is a liability that can hide the bug (an over-clever guard is exactly how these fixes go wrong).
 - **Root cause, not workaround.** No skipped tests, no \`--no-verify\`, no mock that hides the failure.
 - The user does NOT answer during these phases. Act autonomously; do not end with a question.`;
@@ -51,12 +52,12 @@ export function debugPhaseInstructions(state: FailingState): DebugInstructions {
 ${failing}
 
 **Do exactly this:**
-1. Run the reproduction on the CURRENT, unmodified code: \`${repro}\`.
+1. Run the reproduction on the CURRENT, unmodified code with the \`sandbox_run\` tool: \`sandbox_run ${repro}\`.
 2. Paste the exact command and its full output.
-3. Decide:
+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.
    - If it PASSES → STOP. Write \`BLOCKED: cannot reproduce — passes on current code\` with the run pasted. Do not invent a bug.
-   - If it cannot be run at all (missing deps/env) → STOP. Write \`BLOCKED: no executable environment\` with what failed.
+   - 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.` +
 			DEBUG_RULES,
@@ -90,9 +91,9 @@ ${failing}
 ${failing}
 
 **Do exactly this, pasting every command's output:**
-1. Re-run the reproduction: \`${repro}\`. It MUST now pass.
-2. Run the existing test suite (the project's test command). It MUST NOT regress.
-3. Verdict:
+1. Re-run the reproduction with \`sandbox_run ${repro}\`. It MUST now return exit 0.
+2. Run the existing test suite with \`sandbox_run <test command>\`. It MUST NOT regress.
+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.
 4. Write the final verdict block, then call \`phase_result\` with \`verdict: PASS\` (FIXED) or \`verdict: BLOCKED\`, plus a one-line handoff:
@@ -113,10 +114,12 @@ export function buildVerifyInstruction(spec: string): string {
 
 **Original spec:** ${spec}
 
+**Every run below goes through the \`sandbox_run\` tool** (the project's guaranteed environment). If it reports \`SANDBOX UNAVAILABLE\`, do not fabricate results — mark the affected criteria ❔ and say the environment was unavailable.
+
 **Do exactly this, pasting every command's output:**
-1. **Run recipe.** From the brief's \`## Run Recipe\` (or package.json / Makefile / Dockerfile), build and start the app. Distinguish a real failure from a stale launch recipe.
-2. **Acceptance.** For each acceptance criterion derived from the SPEC (not the code), run a concrete check that exits 0 iff it holds. Mark each ✅ (ran+passed), ❌ (ran+failed), or ❔ (could not be executed — NEVER count ❔ as passing).
-3. **Executable red-team.** Attack the specific input regimes the change touched (empty, null, boundary, wrong-type, and buffered-vs-streaming / malformed / auth as relevant). Each attack must be a RUNNABLE test that goes RED if it breaks the code — an opinion is not a finding.
+1. **Run recipe.** From the brief's \`## Run Recipe\` (or package.json / Makefile / Dockerfile), build and start the app via \`sandbox_run\`. Distinguish a real failure from a stale launch recipe.
+2. **Acceptance.** For each acceptance criterion derived from the SPEC (not the code), \`sandbox_run\` a concrete check that exits 0 iff it holds. Mark each ✅ (sandbox_run returned 0), ❌ (non-zero), or ❔ (could not be executed — NEVER count ❔ as passing).
+3. **Executable red-team.** Attack the specific input regimes the change touched (empty, null, boundary, wrong-type, and buffered-vs-streaming / malformed / auth as relevant). Each attack must be a RUNNABLE test \`sandbox_run\` can execute and that goes RED if it breaks the code — an opinion is not a finding.
 4. **Route real failures.** For every ❌ criterion and every red-team break, treat it as a concrete failing state (failing test / repro command / expected) and fix it with the /debug protocol: REPRODUCE → LOCALIZE → minimal FIX → VERIFY (re-run the reproduction AND the suite).
 5. **Honest verdict.** When all checkable criteria pass and the red-team finds no break, write \`BUILD: SUCCESS\`. If rounds/budget run out with failures open, write \`BUILD: PARTIAL\` and LIST exactly which criteria still fail — never a confident-wrong SUCCESS. Then call \`phase_result\` with \`verdict: PASS\` (SUCCESS) or \`verdict: FAIL\`/\`BLOCKED\` and the handoff.
 \`\`\`

package/extensions/phi/providers/execution.ts

@@ -10,6 +10,8 @@
 
 import { spawnSync } from "node:child_process";
 
+const DEFAULT_MAX_BUFFER = 32 * 1024 * 1024;
+
 export interface CommandResult {
 	command: string;
 	exitCode: number | null;
@@ -58,7 +60,7 @@ export function runCommand(command: string, options: RunOptions = {}): CommandRe
 		env: options.env ?? process.env,
 		shell: true,
 		encoding: "utf-8",
-		maxBuffer: 32 * 1024 * 1024,
+		maxBuffer: DEFAULT_MAX_BUFFER,
 	});
 	const durationMs = Date.now() - start;
 	// spawnSync sets error with code "ETIMEDOUT" on timeout, and signal SIGTERM.
@@ -73,3 +75,33 @@ export function runCommand(command: string, options: RunOptions = {}): CommandRe
 		timedOut,
 	};
 }
+
+/**
+ * Run a program by ARGV with NO shell. This is what the Docker sandbox uses:
+ * passing `docker` + its arguments directly avoids shell quoting and — on
+ * Windows Git Bash — the MSYS path mangling that corrupts `-v C:\x:/work` and
+ * `//var/run/docker.sock`. `label` is the human-readable command echoed back in
+ * the result (the argv itself is not a shell string). Never throws.
+ */
+export function runArgv(file: string, args: string[], options: RunOptions & { label?: string } = {}): CommandResult {
+	const start = Date.now();
+	const res = spawnSync(file, args, {
+		cwd: options.cwd,
+		timeout: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+		env: options.env ?? process.env,
+		shell: false,
+		encoding: "utf-8",
+		maxBuffer: DEFAULT_MAX_BUFFER,
+	});
+	const durationMs = Date.now() - start;
+	const timedOut = res.error !== undefined && (res.error as NodeJS.ErrnoException).code === "ETIMEDOUT";
+	const spawnFailed = res.error !== undefined && !timedOut;
+	return {
+		command: options.label ?? `${file} ${args.join(" ")}`.trim(),
+		exitCode: spawnFailed ? null : (res.status ?? null),
+		stdout: res.stdout ?? "",
+		stderr: spawnFailed ? `${(res.error as Error).message}\n${res.stderr ?? ""}` : (res.stderr ?? ""),
+		durationMs,
+		timedOut,
+	};
+}

package/extensions/phi/providers/provider-bootstrap.ts

@@ -0,0 +1,98 @@
+/**
+ * Provider bootstrap — first-time, non-interactive provider configuration.
+ *
+ * `/keys set <id> <key>` used to refuse a provider that had no models.json
+ * entry yet ("run /setup first"), which made adding a known provider (e.g. the
+ * Alibaba Coding Plan) impossible outside the interactive wizard. This module
+ * closes that gap: for providers phi ships a config builder for, it produces a
+ * complete models.json entry (baseUrl + api + model list) from a single API
+ * key, with the provider's own key-format validation applied first.
+ *
+ * Pure (no fs, no network) so every branch is unit-tested; keys.ts is the only
+ * call site.
+ */
+
+import { ALIBABA_PROVIDERS, buildAlibabaProviderConfig, validateAlibabaApiKey } from "./alibaba.js";
+import {
+	buildOpenCodeGoAnthropicProviderConfig,
+	buildOpenCodeGoProviderConfig,
+	OPENCODE_GO_FALLBACK_MODELS,
+	type OpenCodeGoModel,
+	validateOpenCodeGoApiKey,
+} from "./opencode-go.js";
+
+export interface BootstrapModel {
+	id: string;
+	name: string;
+	reasoning: boolean;
+	input: readonly ("text" | "image")[];
+	contextWindow: number;
+	maxTokens: number;
+	compat?: Record<string, unknown>;
+}
+
+export interface BootstrapConfig {
+	baseUrl: string;
+	api: string;
+	apiKey: string;
+	models: BootstrapModel[];
+}
+
+export type BootstrapResult = { ok: true; config: BootstrapConfig; note: string } | { ok: false; error: string };
+
+/** Provider ids `/keys set` can fully configure from just an API key. */
+export const BOOTSTRAPPABLE_PROVIDERS = [
+	"alibaba-codingplan",
+	"alibaba-codingplan-anthropic",
+	"opencode-go",
+	"opencode-go-anthropic",
+] as const;
+
+export function isBootstrappableProvider(id: string): boolean {
+	return (BOOTSTRAPPABLE_PROVIDERS as readonly string[]).includes(id);
+}
+
+/**
+ * Build a complete first-time provider config from an API key. Validates the
+ * key FORMAT (prefix/length) per provider; liveness is `/keys test`'s job.
+ * The bundled model list seeds the entry — the session-start refresh and
+ * `/models refresh` replace it with the live catalog afterwards.
+ */
+export function bootstrapProviderConfig(id: string, apiKey: string): BootstrapResult {
+	const key = apiKey.trim();
+
+	switch (id) {
+		case "alibaba-codingplan":
+		case "alibaba-codingplan-anthropic": {
+			const invalid = validateAlibabaApiKey(key);
+			if (invalid) return { ok: false, error: invalid };
+			const variant = id === "alibaba-codingplan-anthropic" ? "anthropic" : "openai";
+			const config: BootstrapConfig = buildAlibabaProviderConfig(variant, key);
+			return {
+				ok: true,
+				config,
+				note: `${ALIBABA_PROVIDERS[variant].displayName} — ${config.models.length} bundled model(s); a live refresh follows on next session start (or run /models refresh ${id}).`,
+			};
+		}
+		case "opencode-go":
+		case "opencode-go-anthropic": {
+			const invalid = validateOpenCodeGoApiKey(key);
+			if (invalid) return { ok: false, error: invalid };
+			const models: OpenCodeGoModel[] = [...OPENCODE_GO_FALLBACK_MODELS];
+			const config: BootstrapConfig =
+				id === "opencode-go-anthropic"
+					? buildOpenCodeGoAnthropicProviderConfig(key, models)
+					: buildOpenCodeGoProviderConfig(key, models);
+			return {
+				ok: true,
+				config,
+				note: `OpenCode Go — ${config.models.length} bundled model(s); a live refresh follows on next session start (or run /models refresh ${id}).`,
+			};
+		}
+		default:
+			return {
+				ok: false,
+				error: `\`${id}\` has no bootstrap builder. Run \`/setup\` to configure it interactively, or add it to ~/.phi/agent/models.json. Bootstrappable ids: ${BOOTSTRAPPABLE_PROVIDERS.join(", ")}.`,
+			};
+	}
+}

package/extensions/phi/providers/sandbox-plan.ts

@@ -0,0 +1,273 @@
+/**
+ * Sandbox planning — the pure core that turns "what project is this?" into "how
+ * do I run its code in a guaranteed environment?" (docs/design/plan-debug-build.md,
+ * §Execution grounding).
+ *
+ * The SWE-bench measurement was defeated because the host Python was too new to
+ * run the target library, so the model reconstructed a mock and graded itself.
+ * A per-project container fixes that: run the real reproduction/suite with the
+ * project's real toolchain. Everything here is pure (no fs, no spawn) so the
+ * toolchain detection, the recipe, the backend decision, and — critically — the
+ * `docker run` argv (where the Windows path/quoting bugs live) are all unit-tested.
+ */
+
+export type ToolchainKind = "node" | "python" | "go" | "rust" | "ruby" | "unknown";
+
+export interface Toolchain {
+	kind: ToolchainKind;
+	/** The marker file that determined it (e.g. "package.json"). */
+	marker: string | null;
+	hasDockerfile: boolean;
+	hasCompose: boolean;
+}
+
+/** `.phi/sandbox.json` — explicit project override, always wins over detection. */
+export interface SandboxConfig {
+	backend?: "docker" | "local" | "auto";
+	image?: string;
+	setup?: string;
+	test?: string;
+	workdir?: string;
+	env?: Record<string, string>;
+	/** Allow network inside the container (default true — deps often need it). */
+	network?: boolean;
+	memory?: string;
+	cpus?: string;
+}
+
+export type RecipeSource = "detected" | "dockerfile" | "config";
+
+export interface SandboxRecipe {
+	image: string;
+	/** One-off dependency install, run against the mounted project. */
+	setup?: string;
+	/** Best-guess suite command (a floor; the caller may override). */
+	test?: string;
+	workdir: string;
+	env: Record<string, string>;
+	network: boolean;
+	memory?: string;
+	cpus?: string;
+	source: RecipeSource;
+}
+
+const MOUNT_WORKDIR = "/work";
+
+const BASE_IMAGES: Record<Exclude<ToolchainKind, "unknown">, string> = {
+	node: "node:20-slim",
+	python: "python:3.12-slim",
+	go: "golang:1.22-bookworm",
+	rust: "rust:1-slim",
+	ruby: "ruby:3-slim",
+};
+
+const DEFAULT_ENV: Record<ToolchainKind, Record<string, string>> = {
+	node: { CI: "1" },
+	// PYTHONSAFEPATH stops a stray local module from shadowing the stdlib (the
+	// `select.py`/`resource` class of failures seen in the SWE-bench harness).
+	python: { PYTHONSAFEPATH: "1", PYTHONDONTWRITEBYTECODE: "1" },
+	go: {},
+	rust: {},
+	ruby: {},
+	unknown: {},
+};
+
+/** Detect the toolchain from a project's top-level file names. Order = priority. */
+export function detectToolchain(files: string[]): Toolchain {
+	const set = new Set(files.map((f) => f.trim()).filter(Boolean));
+	const has = (name: string) => set.has(name);
+	const hasDockerfile = has("Dockerfile");
+	const hasCompose = has("docker-compose.yml") || has("compose.yml") || has("docker-compose.yaml");
+
+	let kind: ToolchainKind = "unknown";
+	let marker: string | null = null;
+	if (has("package.json")) {
+		kind = "node";
+		marker = "package.json";
+	} else if (has("pyproject.toml") || has("requirements.txt") || has("setup.py")) {
+		kind = "python";
+		marker = has("pyproject.toml") ? "pyproject.toml" : has("requirements.txt") ? "requirements.txt" : "setup.py";
+	} else if (has("go.mod")) {
+		kind = "go";
+		marker = "go.mod";
+	} else if (has("Cargo.toml")) {
+		kind = "rust";
+		marker = "Cargo.toml";
+	} else if (has("Gemfile")) {
+		kind = "ruby";
+		marker = "Gemfile";
+	}
+	return { kind, marker, hasDockerfile, hasCompose };
+}
+
+function detectedSetup(tc: Toolchain, files: Set<string>): string | undefined {
+	switch (tc.kind) {
+		case "node":
+			return files.has("package-lock.json") ? "npm ci || npm install" : "npm install";
+		case "python":
+			if (files.has("pyproject.toml") || files.has("setup.py")) return "pip install -e . || pip install .";
+			if (files.has("requirements.txt")) return "pip install -r requirements.txt";
+			return undefined;
+		case "go":
+			return "go mod download";
+		case "rust":
+			return "cargo fetch";
+		case "ruby":
+			return "bundle install";
+		default:
+			return undefined;
+	}
+}
+
+function detectedTest(tc: Toolchain): string | undefined {
+	switch (tc.kind) {
+		case "node":
+			return "npm test";
+		case "python":
+			return "pytest";
+		case "go":
+			return "go test ./...";
+		case "rust":
+			return "cargo test";
+		case "ruby":
+			return "bundle exec rake test";
+		default:
+			return undefined;
+	}
+}
+
+/**
+ * Build the environment recipe from detected toolchain + files. A project
+ * Dockerfile is honored (source "dockerfile"); otherwise a base image is chosen.
+ */
+export function defaultRecipe(tc: Toolchain, files: string[] = []): SandboxRecipe {
+	const set = new Set(files);
+	const base: SandboxRecipe = {
+		image: tc.kind === "unknown" ? "debian:bookworm-slim" : BASE_IMAGES[tc.kind],
+		setup: detectedSetup(tc, set),
+		test: detectedTest(tc),
+		workdir: MOUNT_WORKDIR,
+		env: { ...DEFAULT_ENV[tc.kind] },
+		network: true,
+		source: tc.hasDockerfile ? "dockerfile" : "detected",
+	};
+	return base;
+}
+
+/** Merge an explicit `.phi/sandbox.json` over a detected recipe (config wins). */
+export function applyConfig(recipe: SandboxRecipe, config?: SandboxConfig): SandboxRecipe {
+	if (!config) return recipe;
+	return {
+		image: config.image ?? recipe.image,
+		setup: config.setup ?? recipe.setup,
+		test: config.test ?? recipe.test,
+		workdir: config.workdir ?? recipe.workdir,
+		env: { ...recipe.env, ...(config.env ?? {}) },
+		network: config.network ?? recipe.network,
+		memory: config.memory ?? recipe.memory,
+		cpus: config.cpus ?? recipe.cpus,
+		source: config.image || config.setup ? "config" : recipe.source,
+	};
+}
+
+export type Backend = "docker" | "local" | "unavailable";
+
+export interface BackendSignals {
+	dockerAvailable: boolean;
+	requested?: "docker" | "local" | "auto";
+	toolchainKnown: boolean;
+	hasDockerfile: boolean;
+}
+
+export interface BackendDecision {
+	backend: Backend;
+	reason: string;
+}
+
+/**
+ * Choose the execution backend, honestly. Docker is the guaranteed oracle but
+ * only helps when we can containerize (a known toolchain or a Dockerfile). When
+ * the caller explicitly demanded docker and it is absent, the answer is
+ * `unavailable` — NOT a silent downgrade to a non-guaranteed local run.
+ */
+export function decideBackend(s: BackendSignals): BackendDecision {
+	const req = s.requested ?? "auto";
+	if (req === "local") return { backend: "local", reason: "backend: local (requested)" };
+	if (req === "docker") {
+		return s.dockerAvailable
+			? { backend: "docker", reason: "backend: docker (requested, available)" }
+			: { backend: "unavailable", reason: "docker requested but the daemon is not available" };
+	}
+	// auto
+	if (s.dockerAvailable && (s.toolchainKnown || s.hasDockerfile)) {
+		return { backend: "docker", reason: "backend: docker (guaranteed environment)" };
+	}
+	if (!s.dockerAvailable)
+		return {
+			backend: "local",
+			reason: "backend: local (docker unavailable — runs are real but not dependency-guaranteed)",
+		};
+	return { backend: "local", reason: "backend: local (unknown toolchain, no Dockerfile — nothing to containerize)" };
+}
+
+/**
+ * Normalize a host path into a Docker bind source. On Windows, forward-slash the
+ * path but keep the drive colon (`C:/Users/…`) — the form Docker Desktop accepts
+ * and, crucially, one that survives argv passing without MSYS mangling.
+ */
+export function toBindSource(hostPath: string, platform: NodeJS.Platform = process.platform): string {
+	if (platform === "win32") return hostPath.replace(/\\/g, "/");
+	return hostPath;
+}
+
+export interface DockerRunSpec {
+	image: string;
+	/** The command run inside the container via `sh -c`. */
+	command: string;
+	/** Host path to bind-mount as the workdir. */
+	mountSource: string;
+	workdir: string;
+	env: Record<string, string>;
+	network: boolean;
+	memory?: string;
+	cpus?: string;
+	platform?: NodeJS.Platform;
+}
+
+/**
+ * Build the argv passed to `docker` (after the program name). Pure and total, so
+ * the exact invocation — mount, workdir, env, network isolation, resource caps —
+ * is asserted in tests instead of discovered in production.
+ */
+export function buildDockerRunArgs(spec: DockerRunSpec): string[] {
+	const bind = `${toBindSource(spec.mountSource, spec.platform)}:${spec.workdir}`;
+	const args: string[] = ["run", "--rm", "-v", bind, "-w", spec.workdir];
+	for (const [k, v] of Object.entries(spec.env)) {
+		args.push("-e", `${k}=${v}`);
+	}
+	if (!spec.network) args.push("--network", "none");
+	if (spec.memory) args.push("--memory", spec.memory);
+	if (spec.cpus) args.push("--cpus", spec.cpus);
+	args.push(spec.image, "sh", "-c", spec.command);
+	return args;
+}
+
+/** A small, dependency-free deterministic hash (djb2) for cache tags. */
+function djb2(input: string): string {
+	let h = 5381;
+	for (let i = 0; i < input.length; i++) {
+		h = ((h << 5) + h + input.charCodeAt(i)) >>> 0;
+	}
+	return h.toString(16).padStart(8, "0");
+}
+
+/** Deterministic image tag for a built recipe (project Dockerfile / config). */
+export function imageTagFor(recipe: SandboxRecipe): string {
+	return `phi-sandbox:${djb2(`${recipe.image}|${recipe.setup ?? ""}|${recipe.workdir}`)}`;
+}
+
+/** Generate a minimal Dockerfile for a detected recipe (utility / persistence). */
+export function generatedDockerfile(recipe: SandboxRecipe): string {
+	const envLines = Object.entries(recipe.env).map(([k, v]) => `ENV ${k}=${v}`);
+	return [`FROM ${recipe.image}`, `WORKDIR ${recipe.workdir}`, ...envLines, ""].join("\n");
+}

package/extensions/phi/providers/sandbox.ts

@@ -0,0 +1,215 @@
+/**
+ * Sandbox — the thin IO shell over the pure planner (sandbox-plan.ts). It turns
+ * a project directory into a runnable environment and executes commands in it,
+ * returning the same CommandResult the oracle cores already consume. Three
+ * backends: `docker` (the guaranteed environment), `local` (real runs, but not
+ * dependency-guaranteed), and `unavailable` (honest — every exec reports it
+ * could not run, so /debug and /build emit BLOCKED instead of a fabricated pass).
+ *
+ * The fs reads and spawns are injectable so the routing/interpretation is
+ * unit-tested without a Docker daemon; a separate docker-gated smoke test does
+ * one real container run.
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+	type CommandResult,
+	passed,
+	type RunOptions,
+	runArgv as realRunArgv,
+	runCommand as realRunCommand,
+} from "./execution.js";
+import {
+	applyConfig,
+	type Backend,
+	buildDockerRunArgs,
+	decideBackend,
+	defaultRecipe,
+	detectToolchain,
+	imageTagFor,
+	type SandboxConfig,
+	type SandboxRecipe,
+} from "./sandbox-plan.js";
+
+export interface PrepareResult {
+	ok: boolean;
+	backend: Backend;
+	detail: string;
+	result?: CommandResult;
+}
+
+export interface Sandbox {
+	readonly backend: Backend;
+	readonly recipe: SandboxRecipe;
+	readonly reason: string;
+	describe(): string;
+	available(): boolean;
+	/** Run a command in the environment. Never throws (see execution.ts). */
+	exec(command: string, options?: RunOptions): CommandResult;
+	/** Build the image / install deps. Idempotent, best-effort. */
+	prepare(): PrepareResult;
+}
+
+type RunCommandFn = (command: string, options?: RunOptions) => CommandResult;
+type RunArgvFn = (file: string, args: string[], options?: RunOptions & { label?: string }) => CommandResult;
+
+/** Injectable seams — real fs/spawn by default, fakes in tests. */
+export interface SandboxDeps {
+	runCommand?: RunCommandFn;
+	runArgv?: RunArgvFn;
+	listFiles?: (cwd: string) => string[];
+	readConfig?: (cwd: string) => SandboxConfig | undefined;
+	/** Force docker availability in tests; otherwise probed via `docker version`. */
+	dockerAvailable?: boolean;
+}
+
+export interface ResolveOptions {
+	cwd: string;
+	requested?: "docker" | "local" | "auto";
+	deps?: SandboxDeps;
+}
+
+/** List a project's top-level entries (best-effort; empty on error). */
+export function listProjectFiles(cwd: string): string[] {
+	try {
+		return readdirSync(cwd);
+	} catch {
+		return [];
+	}
+}
+
+/** Read and parse `.phi/sandbox.json` if present. */
+export function readSandboxConfig(cwd: string): SandboxConfig | undefined {
+	try {
+		const raw = readFileSync(join(cwd, ".phi", "sandbox.json"), "utf-8");
+		const parsed = JSON.parse(raw);
+		return parsed && typeof parsed === "object" ? (parsed as SandboxConfig) : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Probe the Docker daemon (server version reachable). Cheap, capped timeout. */
+export function probeDocker(ra: RunArgvFn): boolean {
+	const r = ra("docker", ["version", "--format", "{{.Server.Version}}"], { timeoutMs: 8000, label: "docker version" });
+	return passed(r) && r.stdout.trim().length > 0;
+}
+
+const UNAVAILABLE_MESSAGE = "SANDBOX UNAVAILABLE — no executable environment; do not fabricate a result, emit BLOCKED.";
+
+function unavailableResult(command: string): CommandResult {
+	return { command, exitCode: null, stdout: "", stderr: UNAVAILABLE_MESSAGE, durationMs: 0, timedOut: false };
+}
+
+/**
+ * Resolve the sandbox for a project directory: detect toolchain, merge config,
+ * decide the backend honestly, and return an executor. Docker exec runs
+ * `docker run --rm -v <cwd>:/work …`; edits land on the host mount, so /debug's
+ * fix-then-rerun works and the container stays ephemeral.
+ */
+export function resolveSandbox(opts: ResolveOptions): Sandbox {
+	const deps = opts.deps ?? {};
+	const rc = deps.runCommand ?? realRunCommand;
+	const ra = deps.runArgv ?? realRunArgv;
+	const files = (deps.listFiles ?? listProjectFiles)(opts.cwd);
+	const config = (deps.readConfig ?? readSandboxConfig)(opts.cwd);
+	const tc = detectToolchain(files);
+	const recipe = applyConfig(defaultRecipe(tc, files), config);
+	const requested = opts.requested ?? config?.backend ?? "auto";
+	const dockerAvailable = deps.dockerAvailable ?? probeDocker(ra);
+	const decision = decideBackend({
+		dockerAvailable,
+		requested,
+		toolchainKnown: tc.kind !== "unknown",
+		hasDockerfile: tc.hasDockerfile,
+	});
+
+	// Effective image can change after prepare() builds a project Dockerfile.
+	const state = { image: recipe.image };
+
+	const dockerExec = (command: string, options?: RunOptions): CommandResult => {
+		const args = buildDockerRunArgs({
+			image: state.image,
+			command,
+			mountSource: opts.cwd,
+			workdir: recipe.workdir,
+			env: recipe.env,
+			network: recipe.network,
+			memory: recipe.memory,
+			cpus: recipe.cpus,
+		});
+		return ra("docker", args, {
+			cwd: opts.cwd,
+			timeoutMs: options?.timeoutMs,
+			label: `docker[${state.image}] ${command}`,
+		});
+	};
+
+	const base = { backend: decision.backend, recipe, reason: decision.reason };
+
+	if (decision.backend === "unavailable") {
+		return {
+			...base,
+			describe: () => `unavailable — ${decision.reason}`,
+			available: () => false,
+			exec: (command) => unavailableResult(command),
+			prepare: () => ({ ok: false, backend: "unavailable", detail: decision.reason }),
+		};
+	}
+
+	if (decision.backend === "local") {
+		return {
+			...base,
+			describe: () => `local host (${opts.cwd})`,
+			available: () => true,
+			exec: (command, options) => rc(command, { cwd: opts.cwd, ...options }),
+			// Deliberately no host-side dependency install — running `npm install`
+			// etc. on the user's host is intrusive; local is best-effort as-is.
+			prepare: () => ({ ok: true, backend: "local", detail: "local host — no preparation performed" }),
+		};
+	}
+
+	// docker
+	return {
+		...base,
+		describe: () => `docker (${state.image})`,
+		available: () => true,
+		exec: dockerExec,
+		prepare: () => {
+			if (recipe.source === "dockerfile") {
+				const tag = imageTagFor(recipe);
+				const built = ra("docker", ["build", "-t", tag, "-f", "Dockerfile", "."], {
+					cwd: opts.cwd,
+					label: `docker build ${tag}`,
+				});
+				if (passed(built)) state.image = tag;
+				return {
+					ok: passed(built),
+					backend: "docker",
+					detail: passed(built) ? `built image ${tag} from Dockerfile` : "docker build failed",
+					result: built,
+				};
+			}
+			// Base image: pull it, then run the dependency setup against the mount.
+			const pulled = ra("docker", ["pull", state.image], { cwd: opts.cwd, label: `docker pull ${state.image}` });
+			if (!recipe.setup) {
+				return {
+					ok: passed(pulled),
+					backend: "docker",
+					detail: `pulled ${state.image} (no setup step)`,
+					result: pulled,
+				};
+			}
+			const setup = dockerExec(recipe.setup);
+			return {
+				ok: passed(setup),
+				backend: "docker",
+				detail: passed(setup)
+					? `pulled ${state.image}; ran setup \`${recipe.setup}\``
+					: `setup failed: \`${recipe.setup}\``,
+				result: setup,
+			};
+		},
+	};
+}

package/package.json

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