@stixxert/pi-docker-sandbox 1.1.2 → 1.1.3

package/package.json

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

@@ -33,20 +33,29 @@ function asText(value: Uint8Array | string | undefined): string {
 /**
  * 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:
+ * 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` — 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 ...`.
+ *  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` — the in-VM cause the runtime reports
- *     (`docker daemon failed to start inside the sandbox`).
+ *  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
@@ -54,9 +63,9 @@ function asText(value: Uint8Array | string | undefined): string {
  * A signal kill (exitCode null — our own abort/timeout) is never classified.
  */
 const RUNTIME_FAILURE_SIGNATURES: readonly RegExp[] = [
-	/failed to start sandbox\b/i,
+	/failed to start sandbox:\s*start runtime:/i,
 	/start runtime: request failed:\s*5\d\d\b/i,
-	/docker daemon failed to start\b/i,
+	/docker daemon failed to start inside the sandbox\b/i,
 ];
 
 /**
@@ -89,10 +98,11 @@ export class SandboxUnavailableError extends Error {
 	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.` +
+			`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";
@@ -100,3 +110,46 @@ export class SandboxUnavailableError extends Error {
 		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,7 +41,7 @@ import {
 	createWriteToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { armSessionLifecycle, debugEnabled, envAllowlist, teardownSandbox } from "../index.ts";
-import { SandboxUnavailableError } from "./failure.ts";
+import { SandboxFailureEpisode, SandboxUnavailableError } from "./failure.ts";
 import {
 	createBashOps,
 	createEditOps,
@@ -79,8 +79,11 @@ 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;
+	/**
+	 * 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.
@@ -88,10 +91,18 @@ export default function (pi: ExtensionAPI) {
 	 * 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;
-		starting = undefined;
 	}
 
 	/**
@@ -110,18 +121,21 @@ export default function (pi: ExtensionAPI) {
 	): Promise<T> {
 		try {
 			const result = await run();
-			sandboxFailureReported = false; // a success ends the episode
+			sandboxEpisode.succeeded(); // a success ends the episode
 			return result;
 		} catch (err) {
 			if (!(err instanceof SandboxUnavailableError)) throw err;
 			invalidateTransport();
-			if (!sandboxFailureReported) {
-				sandboxFailureReported = true;
+			// 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 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}\`).`,
+					`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",
 				);
 			}