@stixxert/pi-docker-sandbox 1.1.0 → 1.1.2

package/README.md

@@ -184,6 +184,11 @@ persistent name (e.g. a shared sandbox reused across restarts), pin
 - `DOCKER_SANDBOX_TEMPLATE=<name>` — use a pre-baked `sbx template` for
   auto-created sandboxes (avoids re-pulling common images every session;
   create with `sbx template save <name>` from a prepared sandbox).
+- `DOCKER_SANDBOX_DEBUG=1` — emit the extension's lifecycle/GC diagnostics
+  (watchdog armed, teardown, startup sweep) to stderr. **Off by default**: the
+  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.
 
 ## Ports (verified rules)
 

package/index.ts

@@ -124,9 +124,9 @@ async function teardownSandbox(reason: string): Promise<void> {
 		].join("\n");
 		const child = spawn("/bin/sh", ["-c", script], { detached: true, stdio: "ignore", env: scrubbedEnv() });
 		child.unref();
-		console.error(`[docker-sandbox] session ${reason}: ${action} sandbox "${name}" (detached, retrying)`);
+		note(`session ${reason}: ${action} sandbox "${name}" (detached, retrying)`);
 	} catch (e) {
-		console.error(`[docker-sandbox] session ${reason}: teardown of "${name}" failed: ${(e as Error).message}`);
+		note(`session ${reason}: teardown of "${name}" failed: ${(e as Error).message}`);
 	}
 }
 
@@ -141,6 +141,22 @@ function findSbxCli(): string {
 	return "sbx";
 }
 
+/**
+ * Diagnostics are OFF by default on purpose: the extension runs inside the pi
+ * process, so a raw console write lands on the terminal the TUI is drawing and
+ * corrupts the chat transcript. Set DOCKER_SANDBOX_DEBUG=1 (or SBX_PI_DEBUG=1 /
+ * SBX_DEBUG=1) to get the lifecycle/GC lines on stderr — useful in `pi -p`, a
+ * plain shell or when diagnosing, harmless in the TUI because it is opt-in.
+ */
+function debugEnabled(): boolean {
+	return /^(1|true|yes|on)$/i.test((env.DOCKER_SANDBOX_DEBUG ?? env.SBX_PI_DEBUG ?? env.SBX_DEBUG ?? "").trim());
+}
+
+/** Diagnostic line — silent unless debug logging is enabled (see debugEnabled). */
+function note(message: string): void {
+	if (debugEnabled()) console.error(`[docker-sandbox] ${message}`);
+}
+
 /**
  * Non-secret vars always forwarded to children (the sbx CLI and shells need
  * them to function; they are not credentials).
@@ -1486,9 +1502,9 @@ function spawnWatchdog(): void {
 	try {
 		const child = spawn("/bin/sh", ["-c", script], { detached: true, stdio: "ignore", env: scrubbedEnv() });
 		child.unref();
-		console.error(`[docker-sandbox] watchdog armed for sandbox "${name}" (pid ${pid}, teardown=${mode}, keepalive=${keep})`);
+		note(`watchdog armed for sandbox "${name}" (pid ${pid}, teardown=${mode}, keepalive=${keep})`);
 	} catch (e) {
-		console.error(`[docker-sandbox] failed to arm watchdog: ${(e as Error).message}`);
+		note(`failed to arm watchdog: ${(e as Error).message}`);
 	}
 }
 
@@ -1670,8 +1686,8 @@ async function armSessionLifecycle(): Promise<void> {
 	// sandboxes from crashed sessions, and session start must not wait on
 	// `sbx ls` (and any sandboxd round trip) to get there.
 	void gcSweep(raw)
-		.then((summary) => console.error(`[docker-sandbox] ${summary}`))
-		.catch((e) => console.error(`[docker-sandbox] gc at startup failed: ${(e as Error).message}`));
+		.then((summary) => note(summary))
+		.catch((e) => note(`gc at startup failed: ${(e as Error).message}`));
 }
 
 export default function (pi: ExtensionAPI) {
@@ -1973,4 +1989,5 @@ export {
 	ensureSandbox,
 	teardownSandbox,
 	armSessionLifecycle,
+	debugEnabled,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stixxert/pi-docker-sandbox",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "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/e2e.mjs

@@ -375,6 +375,7 @@ try {
 	process.env.DOCKER_SANDBOX_KEEPALIVE = "1";
 	process.env.DOCKER_SANDBOX_TEARDOWN = "none"; // no stray teardown attempt
 	process.env.DOCKER_SANDBOX_GC_HOURS = "0"; // skip the startup sweep
+	process.env.DOCKER_SANDBOX_DEBUG = "1"; // lifecycle notes are debug-gated (silent in the TUI by default)
 	const { armSessionLifecycle } = await loadTs("index.ts");
 	const lifecycleLog = [];
 	const realError = console.error;
@@ -389,6 +390,7 @@ try {
 	);
 	delete process.env.DOCKER_SANDBOX_TEARDOWN;
 	delete process.env.DOCKER_SANDBOX_GC_HOURS;
+	delete process.env.DOCKER_SANDBOX_DEBUG;
 
 	/* --- lightweight template handshake -------------------------------- */
 	console.log("\nlightweight template handshake");

package/sandbox/failure.ts

@@ -0,0 +1,102 @@
+/**
+ * Classification of a *sandbox-runtime* failure.
+ *
+ * `sbx exec` normally exits non-zero when the command inside the sandbox exits
+ * non-zero — but it ALSO exits non-zero when it never managed to reach the
+ * command at all, because the sandbox VM's runtime failed to come up. Those two
+ * cases look identical from the transport's point of view (a non-zero exit and
+ * some text on stderr), and confusing them is actively harmful:
+ *
+ *   - reporting "not readable: <path>" / "Path not found" for a dead VM sends
+ *     the agent chasing a file that is perfectly fine, and
+ *   - treating it as a normal command result means nothing ever invalidates the
+ *     memoised transport, so the backend never recovers.
+ *
+ * This module is deliberately tiny and has ZERO imports (not even node
+ * builtins) so the classifier can be unit-tested without the pi packages —
+ * see the consumer in `operations.ts`.
+ */
+
+/** The `ExecOutcome` shape, structurally: an exit code plus its output. */
+export interface ExecLike {
+	/** null when the process was killed by a signal. */
+	exitCode: number | null;
+	stdout?: Uint8Array | string;
+	stderr?: Uint8Array | string;
+}
+
+function asText(value: Uint8Array | string | undefined): string {
+	if (value === undefined) return "";
+	return typeof value === "string" ? value : new TextDecoder().decode(value);
+}
+
+/**
+ * The characteristic signatures of "the sandbox runtime could not start".
+ *
+ * Chosen to be NARROW. Each one is a phrase the `sbx` CLI or its in-VM runtime
+ * emits about the sandbox itself, not something a user command would plausibly
+ * print as its own output:
+ *
+ *  1. `failed to start sandbox` — the CLI's own wrapper line for "I could not
+ *     bring this sandbox up", e.g. the reproduced
+ *     `failed to start sandbox: start runtime: request failed: 500 ...`.
+ *  2. `start runtime: request failed: 5xx` — sandboxd's runtime API rejecting
+ *     the start with an HTTP 5xx. Anchored on `start runtime: request failed:`
+ *     rather than a bare `request failed: 500`, because the bare form could
+ *     come from any command's stderr (a curl wrapper, an API client, ...) and
+ *     would then misclassify an ordinary failing command.
+ *  3. `docker daemon failed to start` — the in-VM cause the runtime reports
+ *     (`docker daemon failed to start inside the sandbox`).
+ *
+ * Matching deliberately requires BOTH a non-zero exit AND a signature on
+ * *stderr* (diagnostics live there; stdout is the command's own output, where a
+ * phrase like "request failed: 500" is far more likely to be a false match).
+ * A signal kill (exitCode null — our own abort/timeout) is never classified.
+ */
+const RUNTIME_FAILURE_SIGNATURES: readonly RegExp[] = [
+	/failed to start sandbox\b/i,
+	/start runtime: request failed:\s*5\d\d\b/i,
+	/docker daemon failed to start\b/i,
+];
+
+/**
+ * Is this outcome "the sandbox runtime failed", rather than "the command
+ * exited non-zero"? Conservative on purpose: a plain `exitCode 1` with ordinary
+ * stderr (e.g. `grep: no match`) must NOT match.
+ */
+export function isSandboxUnavailableFailure(outcome: ExecLike): boolean {
+	if (outcome.exitCode === 0 || outcome.exitCode === null) return false;
+	const stderr = asText(outcome.stderr);
+	if (!stderr) return false;
+	return RUNTIME_FAILURE_SIGNATURES.some((signature) => signature.test(stderr));
+}
+
+/**
+ * The typed error for a dead sandbox runtime.
+ *
+ * Carries the sandbox target and the raw stderr, and its message names the
+ * sandbox explicitly so it is actionable wherever it surfaces — the caller
+ * (see `sandbox/index.ts`) turns it into a one-per-episode user notification
+ * and invalidates the memoised transport, so the NEXT tool call can start the
+ * VM again. It is never a licence to retry the command or to fall back to the
+ * host: re-running arbitrary work is unsafe, and the host is not the execution
+ * environment.
+ */
+export class SandboxUnavailableError extends Error {
+	readonly target: string;
+	readonly stderr: string;
+
+	constructor(target: string, stderr: string) {
+		const detail = stderr.trim();
+		super(
+			`sbx sandbox "${target}" is unavailable: the sandbox runtime failed to start, so the command ` +
+				`never ran inside it (this is not the command's own exit status).\n` +
+				`The VM may need recreating (check \`sbx ls\`, \`sbx stop ${target}\`, or recreate it) — ` +
+				`the next tool call will try to start the sandbox again.` +
+				(detail ? `\n\n${detail}` : ""),
+		);
+		this.name = "SandboxUnavailableError";
+		this.target = target;
+		this.stderr = detail;
+	}
+}

package/sandbox/index.ts

@@ -40,7 +40,8 @@ import {
 	createReadToolDefinition,
 	createWriteToolDefinition,
 } from "@earendil-works/pi-coding-agent";
-import { armSessionLifecycle, envAllowlist, teardownSandbox } from "../index.ts";
+import { armSessionLifecycle, debugEnabled, envAllowlist, teardownSandbox } from "../index.ts";
+import { SandboxUnavailableError } from "./failure.ts";
 import {
 	createBashOps,
 	createEditOps,
@@ -78,6 +79,55 @@ export default function (pi: ExtensionAPI) {
 	let transport: ExecTransport | undefined;
 	let starting: Promise<ExecTransport | undefined> | undefined;
 	let lastError: string | undefined;
+	/** Have we already told the user about the CURRENT run of runtime failures? */
+	let sandboxFailureReported = false;
+
+	/**
+	 * Forget the memoised transport so the next tool call re-resolves it.
+	 *
+	 * This is the whole recovery mechanism: `resolveTransport()` re-derives the
+	 * sandbox and (re)starts the VM, so a runtime failure is an episode rather
+	 * than a permanent bricking of every remaining tool call in the session.
+	 */
+	function invalidateTransport(): void {
+		transport = undefined;
+		starting = undefined;
+	}
+
+	/**
+	 * Run one sandbox round-trip, turning a dead sandbox into: invalidate +
+	 * notify (ONCE per episode) + rethrow.
+	 *
+	 * Deliberately NOT done here: retrying the command, or running it locally.
+	 * Re-running arbitrary work is unsafe (side effects), and the host is not the
+	 * execution environment — that would be a sandbox escape. The resolution-time
+	 * local fallback (see `ensureTransport`) is unchanged and only applies when no
+	 * transport can be resolved at all; it never triggers from here.
+	 */
+	async function withSandboxFailureHandling<T>(
+		ctx: ExtensionContext | undefined,
+		run: () => Promise<T>,
+	): Promise<T> {
+		try {
+			const result = await run();
+			sandboxFailureReported = false; // a success ends the episode
+			return result;
+		} catch (err) {
+			if (!(err instanceof SandboxUnavailableError)) throw err;
+			invalidateTransport();
+			if (!sandboxFailureReported) {
+				sandboxFailureReported = true;
+				ctx?.ui.notify(
+					`sbx sandbox "${err.target}" is unavailable — the sandbox runtime failed to start, so this tool ` +
+						`call did not run (it was NOT run on the host and was not retried). The next tool call will try ` +
+						`to start the sandbox again; if it keeps failing, the VM may need recreating (\`sbx ls\`, ` +
+						`then \`sbx stop ${err.target}\`).`,
+					"error",
+				);
+			}
+			throw err;
+		}
+	}
 
 	/**
 	 * Resolve (and memoize) the transport. Never throws: if sbx is missing or
@@ -129,7 +179,9 @@ export default function (pi: ExtensionAPI) {
 			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);
-				return (build(t).execute as Function)(id, params, signal, onUpdate, ctx);
+				return withSandboxFailureHandling(ctx, () =>
+					(build(t).execute as Function)(id, params, signal, onUpdate, ctx),
+				);
 			},
 		} as T;
 	}
@@ -157,7 +209,10 @@ export default function (pi: ExtensionAPI) {
 		void ensureTransport(ctx)
 			.then((active) => (active?.kind === "sbx" ? armSessionLifecycle() : undefined))
 			.catch((err) => {
-				console.error(`[sbx] session start failed: ${err instanceof Error ? err.message : String(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).
+				if (debugEnabled()) console.error(`[sbx] session start failed: ${err instanceof Error ? err.message : String(err)}`);
 			});
 	});
 
@@ -202,7 +257,7 @@ export default function (pi: ExtensionAPI) {
 		async execute(id, params, signal, onUpdate, ctx) {
 			const t = await ensureTransport(ctx);
 			if (!t) return localGrep.execute(id, params, signal, onUpdate, ctx);
-			return executeSandboxGrep(t, localCwd, params as GrepToolInput);
+			return withSandboxFailureHandling(ctx, () => executeSandboxGrep(t, localCwd, params as GrepToolInput));
 		},
 	});
 

package/sandbox/operations.ts

@@ -40,6 +40,7 @@ import type {
 	ReadOperations,
 	WriteOperations,
 } from "@earendil-works/pi-coding-agent";
+import { SandboxUnavailableError, isSandboxUnavailableFailure } from "./failure.ts";
 import { type ExecOptions, type ExecOutcome, type ExecTransport, shArgs, shQuote } from "./transport.ts";
 
 /** Files larger than this would exceed a comfortable argv budget when base64'd. */
@@ -77,19 +78,42 @@ function opOpts(extra?: ExecOptions): ExecOptions {
 	return { timeout: DEFAULT_OP_TIMEOUT, ...extra };
 }
 
+/**
+ * Throw if this outcome means the sandbox runtime itself failed to start.
+ *
+ * A non-zero exit from `sbx exec` is ambiguous: it is the inner command's
+ * status when the VM was reachable, and the CLI's own failure when it was not.
+ * This is the one place that ambiguity is resolved, so no call site below can
+ * mistake "the whole sandbox is down" for "this file does not exist".
+ */
+function throwIfSandboxUnavailable(t: ExecTransport, r: ExecOutcome): void {
+	if (isSandboxUnavailableFailure(r)) throw new SandboxUnavailableError(t.target, r.stderr.toString("utf8"));
+}
+
 async function must(t: ExecTransport, argv: string[], fallback: string, opts?: ExecOptions): Promise<ExecOutcome> {
 	const r = await t.exec(argv, opOpts(opts));
+	throwIfSandboxUnavailable(t, r);
 	if (r.exitCode !== 0) throw new Error(errText(r, fallback));
 	return r;
 }
 
+/**
+ * "Did this probe exit 0?" for the `test -e` / `test -r` style primitives.
+ *
+ * A transport-level rejection (spawn failure, abort, timeout) is still reported
+ * as `false` — that is what this helper is for. A sandbox-runtime failure is
+ * NOT: it propagates, so callers cannot silently turn a dead VM into "this path
+ * does not exist".
+ */
 async function ok(t: ExecTransport, argv: string[]): Promise<boolean> {
+	let r: ExecOutcome;
 	try {
-		const r = await t.exec(argv, opOpts());
-		return r.exitCode === 0;
+		r = await t.exec(argv, opOpts());
 	} catch {
 		return false;
 	}
+	throwIfSandboxUnavailable(t, r);
+	return r.exitCode === 0;
 }
 
 /* ------------------------------------------------------------------ */
@@ -215,7 +239,13 @@ export function createLsOps(t: ExecTransport): LsOperations {
 			if (knownHit !== undefined) return { isDirectory: () => knownHit };
 			const cached = listings.get(path.dirname(p));
 			if (cached) {
-				const entries = await cached.catch(() => undefined);
+				// A failed parent listing is normally "not there / unreadable", which
+				// just means "fall through to a direct probe". A sandbox-runtime
+				// failure is not that, and must not be swallowed.
+				const entries = await cached.catch((err) => {
+					if (err instanceof SandboxUnavailableError) throw err;
+					return undefined;
+				});
 				const hit = entries?.get(path.basename(p));
 				if (hit !== undefined) {
 					known.set(p, hit);
@@ -253,13 +283,16 @@ async function gitSearchableFiles(t: ExecTransport, root: string): Promise<strin
 			shArgs('git -c safe.directory=\'*\' -C "$1" ls-files -z --cached --others --exclude-standard', root),
 			opOpts(),
 		);
+		// Not a repo / git missing: fall back to the walk. A dead sandbox: throw.
+		throwIfSandboxUnavailable(t, r);
 		if (r.exitCode !== 0) return null;
 		const files: string[] = [];
 		for (const relative of r.stdout.toString("utf8").split("\0")) {
 			if (relative) files.push(path.join(root, relative));
 		}
 		return files;
-	} catch {
+	} catch (err) {
+		if (err instanceof SandboxUnavailableError) throw err;
 		return null;
 	}
 }
@@ -326,7 +359,8 @@ async function walkFiles(
 	let entries: Map<string, boolean>;
 	try {
 		entries = await listDirEntries(t, dir);
-	} catch {
+	} catch (err) {
+		if (err instanceof SandboxUnavailableError) throw err;
 		return true; // unreadable subtree: skip, like the built-in does
 	}
 	for (const [name, isDir] of entries) {
@@ -367,7 +401,8 @@ export async function executeSandboxGrep(
 		let content: string;
 		try {
 			content = (await readBytes(t, absolute)).toString("utf8");
-		} catch {
+		} catch (err) {
+			if (err instanceof SandboxUnavailableError) throw err;
 			return true; // binary/unreadable file
 		}
 		const lines = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
@@ -490,6 +525,13 @@ export function createBashOps(t: ExecTransport, options: BashOpsOptions = {}): B
 				.filter(Boolean)
 				.join("\n");
 			const r = await t.exec(["sh", "-lc", script], { onData, signal, timeout });
+			// A non-zero exit here is usually the command's OWN status (grep found
+			// nothing, a test failed, `false`) and must stay an exit code. But when
+			// the signature says the VM never started, the command did not run at
+			// all — surface that instead of a bogus status, so the caller can
+			// invalidate the transport. bash is the most common way to hit a dead
+			// sandbox, so it must not be the one path that never recovers.
+			throwIfSandboxUnavailable(t, r);
 			return { exitCode: r.exitCode };
 		},
 	};