@stixxert/pi-docker-sandbox 1.1.1 → 1.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stixxert/pi-docker-sandbox",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "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/failure.ts

@@ -0,0 +1,155 @@
+/**
+ * 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 — specifically, long enough that a *user command's* own
+ * stderr cannot plausibly collide with them. That specificity is load-bearing:
+ * a false positive REPLACES the command's real exit status with a
+ * `SandboxUnavailableError`, and the caller then reports that the command's
+ * effects are unknown — which is exactly the ambiguity that tempts an agent to
+ * re-run a side-effecting command. So every pattern anchors on the runtime's
+ * actual wrapper phrasing, never on a short phrase a project script, CI helper
+ * or test wrapper might print about its OWN docker/CI runtime:
+ *
+ *  1. `failed to start sandbox: start runtime:` — the CLI's own wrapper chained
+ *     to the runtime start, e.g. the reproduced
+ *     `failed to start sandbox: start runtime: request failed: 500 ...`. BOTH
+ *     halves must appear together; the bare `failed to start sandbox` alone is
+ *     the kind of line a user's own launcher could emit, so it is not used.
+ *  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 inside the sandbox` — the in-VM cause, as
+ *     the FULL phrase the runtime reports. The short `docker daemon failed to
+ *     start` alone is NOT enough: a user command or CI wrapper that manages its
+ *     own docker could print exactly that about a local daemon.
+ *
+ * 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:\s*start runtime:/i,
+	/start runtime: request failed:\s*5\d\d\b/i,
+	/docker daemon failed to start inside the sandbox\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 this is not the ` +
+				`command's own exit status and the command's effects cannot be assumed to have happened.\n` +
+				`The command was not run on the host and was not retried. 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;
+	}
+}
+
+/**
+ * Per-episode state for the runtime-failure notification.
+ *
+ * `withSandboxFailureHandling` (see `sandbox/index.ts`) wraps every routed tool
+ * call. A runtime failure should tell the user ONCE — not once per tool call in
+ * an otherwise broken session — and then tell them AGAIN if a later call
+ * succeeds and a new, distinct outage begins.
+ *
+ * The subtlety the caller cannot express on its own: a tool call may arrive
+ * without a UI context, so a failure cannot always be surfaced. A failure that
+ * cannot be surfaced must NOT consume the episode's single notification, or an
+ * early headless failure would suppress the one notification the user needs for
+ * the whole episode. Hence `claimNotification(canNotify)`: the claim is only
+ * used up when the notification is actually deliverable.
+ *
+ * Pure and dependency-free (like the rest of this module) so the episode's
+ * behaviour can be unit-tested without the pi packages.
+ */
+export class SandboxFailureEpisode {
+	/** Has this episode's one notification already been delivered? */
+	private notified = false;
+
+	/**
+	 * Claim this episode's single notification.
+	 *
+	 * @param canNotify Whether the caller can actually deliver a notification
+	 *   right now (i.e. it has a UI context). When false the claim is left
+	 *   untouched, so a later, deliverable failure in the same episode still
+	 *   notifies.
+	 * @returns true only for the first *deliverable* failure of the episode.
+	 */
+	claimNotification(canNotify: boolean): boolean {
+		if (this.notified || !canNotify) return false;
+		this.notified = true;
+		return true;
+	}
+
+	/** A successful sandbox round-trip ends the episode. */
+	succeeded(): void {
+		this.notified = false;
+	}
+}

package/sandbox/index.ts

@@ -41,6 +41,7 @@ import {
 	createWriteToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { armSessionLifecycle, debugEnabled, envAllowlist, teardownSandbox } from "../index.ts";
+import { SandboxFailureEpisode, SandboxUnavailableError } from "./failure.ts";
 import {
 	createBashOps,
 	createEditOps,
@@ -78,6 +79,69 @@ export default function (pi: ExtensionAPI) {
 	let transport: ExecTransport | undefined;
 	let starting: Promise<ExecTransport | undefined> | undefined;
 	let lastError: string | undefined;
+	/**
+	 * Notification state for the CURRENT run of runtime failures. One message per
+	 * episode, reset by a successful round-trip — see `SandboxFailureEpisode`.
+	 */
+	const sandboxEpisode = new SandboxFailureEpisode();
+
+	/**
+	 * 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.
+	 *
+	 * `starting` is deliberately NOT reset here. It is non-undefined only while a
+	 * `resolveTransport()` is genuinely in flight, and that in-flight resolution
+	 * will itself publish a fresh transport when it settles — so the next
+	 * `ensureTransport()` awaits it, which is exactly the recovery we want.
+	 * Clearing it here would instead let a concurrent caller launch a SECOND
+	 * resolution, and each resolution can boot/create a VM. The resulting race is
+	 * benign today only because every resolution targets the same per-project
+	 * sandbox name and therefore reuses one VM; there is no reason to open it up.
+	 */
+	function invalidateTransport(): void {
+		transport = 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();
+			sandboxEpisode.succeeded(); // a success ends the episode
+			return result;
+		} catch (err) {
+			if (!(err instanceof SandboxUnavailableError)) throw err;
+			invalidateTransport();
+			// Tell the user ONCE per episode. The claim is only taken when a
+			// notification is actually deliverable (`ctx` present) — a failure we
+			// cannot surface must not swallow the episode's one message.
+			if (sandboxEpisode.claimNotification(ctx !== undefined)) {
+				ctx?.ui.notify(
+					`sbx sandbox "${err.target}" is unavailable — the sandbox runtime failed to start, so this ` +
+						`result is not the command's own exit status and the command's effects cannot be assumed ` +
+						`to have happened. The command 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 +193,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;
 	}
@@ -205,7 +271,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 };
 		},
 	};