@stixxert/pi-docker-sandbox 1.1.3 → 1.1.4

package/README.md

@@ -189,6 +189,11 @@ persistent name (e.g. a shared sandbox reused across restarts), pin
   extension runs inside the pi process, so stray console output would land on
   the same terminal the TUI is drawing and corrupt the chat. Turn it on when
   running `pi -p`, in a plain shell, or when diagnosing lifecycle issues.
+- `DOCKER_SANDBOX_ALLOW_UNSANDBOXED=1` — allow tools to run directly on the
+  **host** when no sandbox can be resolved. **Off by default**: a missing `sbx`
+  CLI or an unstartable VM makes tool calls **fail closed** (refused with an
+  actionable error) rather than silently executing on the host, which is a
+  sandbox escape. Set this only if you accept unsandboxed execution.
 
 ## Ports (verified rules)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stixxert/pi-docker-sandbox",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "pi extension: a private docker sandbox (sbx microVM with its own daemon) as the agent's deploy target — the host's docker is never exposed.",
   "license": "Apache-2.0",
   "publishConfig": {

package/sandbox/README.md

@@ -87,10 +87,12 @@ entry; over `sbx exec` that would be N+3 sandbox round-trips per listing. A
 single POSIX-sh pass returns `d`/`f` + name and is memoised for the duration
 of that one tool call (verified: 25 entries => ≤ 4 round-trips).
 
-**It degrades instead of breaking.** If `sbx` is missing or the sandbox
-cannot be provisioned, the tools fall back to local execution, the user is
-notified, and the system prompt says so explicitly — the agent is never led
-to believe it is sandboxed when it is not.
+**It degrades instead of breaking.** If `sbx` is missing or the sandbox cannot
+be provisioned, the tools **fail closed** rather than silently running on the
+host: the call is refused with an actionable error naming the cause and the
+opt-in, the user is notified, and the system prompt says so explicitly — the
+agent is never led to believe it is sandboxed when it is not. Running directly
+on the host requires an explicit `DOCKER_SANDBOX_ALLOW_UNSANDBOXED=1`.
 
 ## Trying it out (before publishing)
 
@@ -129,8 +131,9 @@ bash sandbox/try.sh --docker -- -p --tools read "Read /opt/only-in-sandbox.txt"
 
 If the first reports the container's OS and the second returns the file, the
 routing works. If the extension failed to load you get a missing-tool error
-instead — never a silent fallback to the host (that case is reported in the
-system prompt and via `/sbx`).
+instead — and if no sandbox can be resolved, tool calls are **refused** by
+default rather than falling back to the host (the refusal and its opt-in are
+reported in the system prompt and via `/sbx`).
 
 ### On the host, with real sbx
 
@@ -171,6 +174,7 @@ edits go through pi's own tools.
 | `DOCKER_SANDBOX_KEEPALIVE` | **default `1` here** — keeps the VM running for the life of the pi process; set `0` to allow idle-stop |
 | `DOCKER_SANDBOX_ENV_ALLOWLIST` | additionally export these host vars into the sandbox shell (default: `PI_*` only) |
 | `DOCKER_SANDBOX` | pin the sandbox name (also disables per-project derivation) |
+| `DOCKER_SANDBOX_ALLOW_UNSANDBOXED=1` | **fail-closed default override** — permit tools to run directly on the host when no sandbox can be resolved (default: refuse) |
 | `SBX_EPHEMERAL` | `1` = throwaway per-session sandbox, removed at exit |
 | `SBX_PI_DEBUG` | `1` = log per-phase startup timings to stderr |
 | `DOCKER_SANDBOX_TEARDOWN` | `remove` / `stop` / `none` (a per-project sandbox defaults to `none`) |

package/sandbox/failure.ts

@@ -111,6 +111,91 @@ export class SandboxUnavailableError extends Error {
 	}
 }
 
+/* ------------------------------------------------------------------ */
+/* fail-closed policy when NO sandbox can be resolved at all           */
+/* ------------------------------------------------------------------ */
+
+/**
+ * The opt-in that permits running tools directly on the HOST when no sandbox
+ * can be resolved.
+ *
+ * The default is to REFUSE (fail closed): an unresolvable sandbox must never
+ * mean "silently run on the host" — that is a sandbox escape, and the host is
+ * not the execution environment. Named with the repo's own `DOCKER_SANDBOX_*`
+ * prefix and deliberately NOT tied to any launcher (e.g. pidock's separate
+ * `PIDOCK_ALLOW_UNSANDBOXED`), so the backend stays usable standalone.
+ */
+export const UNSANDBOXED_OPT_IN_ENV = "DOCKER_SANDBOX_ALLOW_UNSANDBOXED";
+
+/**
+ * True when the user has explicitly opted into unsandboxed operation via
+ * `UNSANDBOXED_OPT_IN_ENV`.
+ *
+ * Accepts `1`, `true`, `yes`, `on` (case-insensitive, surrounding whitespace
+ * ignored) — the same boolean vocabulary as the repo's other knobs
+ * (`DOCKER_SANDBOX_DEBUG`, `DOCKER_SANDBOX_ENV_PASSTHROUGH`, ...). Anything
+ * else, including unset and `0`/`false`/`no`/`off`, leaves the secure default:
+ * refuse.
+ */
+export function unsandboxedAllowed(env: Readonly<Record<string, string | undefined>>): boolean {
+	return /^(1|true|yes|on)$/i.test((env[UNSANDBOXED_OPT_IN_ENV] ?? "").trim());
+}
+
+/**
+ * The typed error for a tool call REFUSED because no sandbox could be resolved
+ * and the host fallback is disabled.
+ *
+ * Distinct from `SandboxUnavailableError`: that one is a sandbox that existed
+ * and failed mid-round-trip (transient — the next call re-resolves and may
+ * recover). This one means there was never a sandbox to fail in, and the
+ * fail-closed policy has refused to run the tool anywhere. It is actionable,
+ * not a stack trace: it names the cause, states in as many words that the
+ * command was NOT run on the host, and names the exact variable that would opt
+ * into unsandboxed operation.
+ */
+export class SandboxRequiredError extends Error {
+	/** The resolution failure that led here (may be empty). */
+	readonly failure: string;
+
+	constructor(failure?: string) {
+		const detail = (failure ?? "").trim();
+		super(
+			`sbx sandbox unavailable: ${
+				detail ||
+				"no sandbox transport could be resolved (is the `sbx` CLI installed and the VM runnable?)"
+			}.\n` +
+				`This tool was NOT run: it did not execute in the sandbox, and it was NOT run on the host either.\n` +
+				`Refusing to run unsandboxed by default. To allow tools to run directly on the host instead, set ` +
+				`${UNSANDBOXED_OPT_IN_ENV}=1 and retry.`,
+		);
+		this.name = "SandboxRequiredError";
+		this.failure = detail;
+	}
+}
+
+/**
+ * The fail-closed policy for a resolution failure: from an environment snapshot
+ * plus the resolution failure, decide whether the caller may fall back to the
+ * LOCAL (host) tool or must refuse.
+ *
+ * `{ allow: true }` only when the user has explicitly opted in with
+ * `DOCKER_SANDBOX_ALLOW_UNSANDBOXED=1` (see `unsandboxedAllowed`). Otherwise the
+ * decision carries a `SandboxRequiredError` whose message names the cause, says
+ * the command was not run on the host, and names the opt-in variable.
+ *
+ * Pure and dependency-free (like the rest of this module) so the policy can be
+ * unit-tested without the pi packages.
+ */
+export type LocalFallbackDecision = { allow: true } | { allow: false; error: SandboxRequiredError };
+
+export function decideLocalFallback(
+	env: Readonly<Record<string, string | undefined>>,
+	failure?: string,
+): LocalFallbackDecision {
+	if (unsandboxedAllowed(env)) return { allow: true };
+	return { allow: false, error: new SandboxRequiredError(failure) };
+}
+
 /**
  * Per-episode state for the runtime-failure notification.
  *

package/sandbox/index.ts

@@ -41,7 +41,13 @@ import {
 	createWriteToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { armSessionLifecycle, debugEnabled, envAllowlist, teardownSandbox } from "../index.ts";
-import { SandboxFailureEpisode, SandboxUnavailableError } from "./failure.ts";
+import {
+	SandboxFailureEpisode,
+	SandboxUnavailableError,
+	UNSANDBOXED_OPT_IN_ENV,
+	decideLocalFallback,
+	unsandboxedAllowed,
+} from "./failure.ts";
 import {
 	createBashOps,
 	createEditOps,
@@ -105,6 +111,20 @@ export default function (pi: ExtensionAPI) {
 		transport = undefined;
 	}
 
+	/**
+	 * The fail-closed gate for "there is no transport at all".
+	 *
+	 * Returns normally ONLY when the user has explicitly opted into unsandboxed
+	 * operation (`DOCKER_SANDBOX_ALLOW_UNSANDBOXED=1`); otherwise throws the
+	 * typed `SandboxRequiredError`, so the tool call is REFUSED instead of being
+	 * silently executed on the host. The decision itself lives in `failure.ts`,
+	 * which is import-free and unit-tested.
+	 */
+	function assertLocalFallbackAllowed(): void {
+		const decision = decideLocalFallback(process.env, lastError);
+		if (decision.allow === false) throw decision.error;
+	}
+
 	/**
 	 * Run one sandbox round-trip, turning a dead sandbox into: invalidate +
 	 * notify (ONCE per episode) + rethrow.
@@ -144,10 +164,13 @@ export default function (pi: ExtensionAPI) {
 	}
 
 	/**
-	 * Resolve (and memoize) the transport. Never throws: if sbx is missing or
-	 * the sandbox cannot be provisioned, pi keeps working with its LOCAL tools
-	 * and the degradation is reported — both to the user and in the system
-	 * prompt, so the agent never believes it is sandboxed when it is not.
+	 * Resolve (and memoize) the transport. Never throws: if sbx is missing or the
+	 * sandbox cannot be provisioned, `undefined` is returned and the degradation
+	 * is reported — both to the user and in the system prompt. The CALLER of a
+	 * tool call then decides what to do (see `assertLocalFallbackAllowed`): by
+	 * default it REFUSES, so the host is never silently used as the execution
+	 * environment; only an explicit `DOCKER_SANDBOX_ALLOW_UNSANDBOXED=1` opt-in
+	 * permits the local fallback.
 	 */
 	async function ensureTransport(ctx?: ExtensionContext): Promise<ExecTransport | undefined> {
 		if (transport) return transport;
@@ -169,7 +192,13 @@ export default function (pi: ExtensionAPI) {
 				} catch (err) {
 					lastError = err instanceof Error ? err.message : String(err);
 					ctx?.ui.setStatus("sbx", ctx.ui.theme.fg("error", "sbx: unavailable"));
-					ctx?.ui.notify(`sbx backend unavailable — running tools locally.\n${lastError}`, "warning");
+					ctx?.ui.notify(
+						unsandboxedAllowed(process.env)
+							? `sbx backend unavailable — ${UNSANDBOXED_OPT_IN_ENV}=1, so tools run directly on the host.\n${lastError}`
+							: `sbx backend unavailable — refusing tool calls; nothing will run on the host.\n` +
+									`Set ${UNSANDBOXED_OPT_IN_ENV}=1 to run tools directly on the host instead.\n${lastError}`,
+						"warning",
+					);
 					return undefined;
 				} finally {
 					starting = undefined;
@@ -180,7 +209,9 @@ export default function (pi: ExtensionAPI) {
 	}
 
 	/**
-	 * Route a tool to the sandbox, falling back to the local tool on failure.
+	 * Route a tool to the sandbox, refusing to run it on the host when no sandbox
+	 * can be had (fail closed) unless the user opted in.
+	 *
 	 * `ctx` is forwarded — the built-ins use it to inject PI_* session metadata
 	 * into the bash environment, and dropping it would silently change behaviour.
 	 */
@@ -192,7 +223,10 @@ export default function (pi: ExtensionAPI) {
 			...local,
 			async execute(id: unknown, params: unknown, signal: unknown, onUpdate: unknown, ctx?: ExtensionContext) {
 				const t = await ensureTransport(ctx);
-				if (!t) return (local.execute as Function)(id, params, signal, onUpdate, ctx);
+				if (!t) {
+					assertLocalFallbackAllowed();
+					return (local.execute as Function)(id, params, signal, onUpdate, ctx);
+				}
 				return withSandboxFailureHandling(ctx, () =>
 					(build(t).execute as Function)(id, params, signal, onUpdate, ctx),
 				);
@@ -224,8 +258,9 @@ export default function (pi: ExtensionAPI) {
 			.then((active) => (active?.kind === "sbx" ? armSessionLifecycle() : undefined))
 			.catch((err) => {
 				// Raw console writes land on the terminal the TUI is drawing, so cap
-				// the failure note behind the debug flag — the backend degrades to
-				// local tools either way (the `sbx` command reports live status).
+				// the failure note behind the debug flag — tool calls refuse by default
+				// or run on the host only under the explicit opt-in (the `sbx` command
+				// reports live status).
 				if (debugEnabled()) console.error(`[sbx] session start failed: ${err instanceof Error ? err.message : String(err)}`);
 			});
 	});
@@ -250,7 +285,11 @@ export default function (pi: ExtensionAPI) {
 							"",
 							"Tools routed into the sandbox: bash, read, write, edit, grep, find, ls",
 						].join("\n")
-					: `sbx backend unavailable — tools run locally.\n${lastError ?? ""}`,
+					: `sbx backend unavailable — ${
+							unsandboxedAllowed(process.env)
+								? `tools run directly on the host (${UNSANDBOXED_OPT_IN_ENV}=1)`
+								: `tool calls are refused; nothing runs on the host (set ${UNSANDBOXED_OPT_IN_ENV}=1 to allow unsandboxed execution)`
+						}.\n${lastError ?? ""}`,
 				t ? "info" : "warning",
 			);
 		},
@@ -270,26 +309,45 @@ export default function (pi: ExtensionAPI) {
 		...localGrep,
 		async execute(id, params, signal, onUpdate, ctx) {
 			const t = await ensureTransport(ctx);
-			if (!t) return localGrep.execute(id, params, signal, onUpdate, ctx);
+			if (!t) {
+				assertLocalFallbackAllowed();
+				return localGrep.execute(id, params, signal, onUpdate, ctx);
+			}
 			return withSandboxFailureHandling(ctx, () => executeSandboxGrep(t, localCwd, params as GrepToolInput));
 		},
 	});
 
 	// The user's own `!` commands belong in the sandbox too, exactly as gondolin
-	// routes them — otherwise `!` would silently execute on the host.
+	// routes them — otherwise `!` would silently execute on the host. When no
+	// sandbox can be had, the same fail-closed policy applies: refuse (throw)
+	// unless the user opted into unsandboxed operation.
 	pi.on("user_bash", async (_event, ctx) => {
 		const t = await ensureTransport(ctx);
-		if (!t) return undefined;
+		if (!t) {
+			assertLocalFallbackAllowed();
+			return undefined; // opt-in set: run on the host, as explicitly requested
+		}
 		return { operations: createBashOps(t, { allowEnv: bashAllowEnv }) };
 	});
 
 	pi.on("before_agent_start", async (event, ctx) => {
 		const t = await ensureTransport(ctx);
 		const localLine = `Current working directory: ${localCwd}`;
-		const replacement = t
-			? `Current working directory: ${localCwd} — commands run inside the ${t.kind} sandbox "${t.target}" ` +
-				`(the same absolute paths exist there; the host is not the execution environment)`
-			: `${localLine} (WARNING: the sbx sandbox is unavailable, so commands run directly on the host)`;
+		let replacement: string;
+		if (t) {
+			replacement =
+				`Current working directory: ${localCwd} — commands run inside the ${t.kind} sandbox "${t.target}" ` +
+				`(the same absolute paths exist there; the host is not the execution environment)`;
+		} else if (unsandboxedAllowed(process.env)) {
+			replacement =
+				`${localLine} (WARNING: the sbx sandbox is unavailable and ${UNSANDBOXED_OPT_IN_ENV} is set, ` +
+				`so commands run directly on the host — not in the sandbox)`;
+		} else {
+			replacement =
+				`${localLine} (WARNING: the sbx sandbox is unavailable and ${UNSANDBOXED_OPT_IN_ENV} is not set, ` +
+				`so tool calls are REFUSED and will NOT run — neither in the sandbox nor on the host. ` +
+				`Set ${UNSANDBOXED_OPT_IN_ENV}=1 to run tools directly on the host instead.)`;
+		}
 		const systemPrompt = event.systemPrompt.includes(localLine)
 			? event.systemPrompt.replace(localLine, replacement)
 			: `${event.systemPrompt}\n\n${replacement}`;