@stixxert/pi-docker-sandbox 1.1.0 → 1.1.1

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.1",
   "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/index.ts

@@ -40,7 +40,7 @@ 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 {
 	createBashOps,
 	createEditOps,
@@ -157,7 +157,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)}`);
 			});
 	});