@stixxert/pi-docker-sandbox 1.1.3 → 1.1.5

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

@@ -44,6 +44,7 @@ import path from "node:path";
 import fs from "node:fs";
 import type { AgentToolResult, ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "@earendil-works/pi-ai";
+import { claimLifecycleOwnership } from "./sandbox/session-scope.ts";
 
 // Host pi cwd is the root that the agent's VM mounts at /workspace.
 const hostRoot = process.cwd();
@@ -1691,9 +1692,15 @@ async function armSessionLifecycle(): Promise<void> {
 }
 
 export default function (pi: ExtensionAPI) {
+	// The sandbox execution backend (`sandbox/`) shares this lifecycle, and the
+	// auto-discovered `sbx-backend` bridge loads that backend into subagent
+	// sessions so their built-in tools run in the same sandbox. Only the
+	// top-level session — the first to load either entry — may tear it down.
+	const ownsLifecycle = claimLifecycleOwnership();
 	// Lifecycle: tear down this session's sandbox when the session ends
 	// (exit / Ctrl+C / Ctrl+D / SIGHUP / SIGTERM, /new, /resume, /fork).
 	pi.on("session_shutdown", async () => {
+		if (!ownsLifecycle) return;
 		await teardownSandbox("session_shutdown");
 	});
 

package/package.json

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

@@ -29,6 +29,7 @@
  *   DOCKER_SANDBOX / DOCKER_SANDBOX_*                see the docker_* extension
  */
 
+import path from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
 	type GrepToolInput,
@@ -41,7 +42,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,
@@ -52,8 +59,15 @@ import {
 	executeSandboxGrep,
 } from "./operations.ts";
 import { type ExecTransport, defaultProjectSandbox, resolveTransport } from "./transport.ts";
+import { claimLifecycleOwnership } from "./session-scope.ts";
 
 export default function (pi: ExtensionAPI) {
+	// Subagent sessions (pi-subagents) load this router too, through the
+	// auto-discovered `sbx-backend` bridge, so a subagent's built-in tools run in
+	// the same sandbox as the main agent's instead of on the host. Only the
+	// top-level session may tear the shared (per-process) sandbox down; child
+	// sessions share it.
+	const ownsLifecycle = claimLifecycleOwnership();
 	const localCwd = process.cwd();
 
 	// Settle the sandbox NAME synchronously, before any session event can compute
@@ -105,6 +119,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 +172,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 +200,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,21 +217,53 @@ export default function (pi: ExtensionAPI) {
 	}
 
 	/**
-	 * Route a tool to the sandbox, falling back to the local tool on failure.
+	 * The working directory a session's routed tools must operate in.
+	 *
+	 * The backend mounts the process working directory (`localCwd`) into the
+	 * sandbox, while pi builds a session's tools with that SESSION's cwd. They
+	 * coincide for the top-level session, but not necessarily for a subagent — a
+	 * pi-subagents git worktree lives under the host tmpdir, outside the mount.
+	 * Routing now happens for subagents too, so the cwd is resolved per call: a
+	 * directory inside the mount is used as-is, one outside it is refused rather
+	 * than silently executed against (or written to) the wrong tree.
+	 */
+	function sessionCwd(ctx?: ExtensionContext): string {
+		const cwd = ctx?.cwd;
+		if (!cwd || cwd === localCwd) return localCwd;
+		const rel = path.relative(localCwd, cwd);
+		if (rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel)) return cwd;
+		throw new Error(
+			`sbx sandbox mounts only ${localCwd}, but this session's working directory is ${cwd}. ` +
+				`Its tools cannot be routed into the sandbox; nothing was executed. ` +
+				`Do not use worktree isolation (\`isolation: "worktree"\`) under the sbx backend, ` +
+				`or re-run the session without it.`,
+		);
+	}
+
+	/**
+	 * 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.
 	 */
 	function routed<T extends { execute: (...args: never[]) => unknown }>(
 		local: T,
-		build: (t: ExecTransport) => T,
+		build: (t: ExecTransport, cwd: string) => T,
 	): T {
 		return {
 			...local,
 			async execute(id: unknown, params: unknown, signal: unknown, onUpdate: unknown, ctx?: ExtensionContext) {
+				// Resolved before the transport: an unroutable cwd must fail closed
+				// whether or not a sandbox happens to be available.
+				const cwd = sessionCwd(ctx);
 				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),
+					(build(t, cwd).execute as Function)(id, params, signal, onUpdate, ctx),
 				);
 			},
 		} as T;
@@ -224,13 +293,17 @@ 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)}`);
 			});
 	});
 
 	pi.on("session_shutdown", async () => {
+		// Child (subagent) sessions share the parent's per-process sandbox;
+		// tearing it down from one would kill the VM out from under the parent.
+		if (!ownsLifecycle) return;
 		// Only an sbx sandbox is ours to reclaim; a container backend is a
 		// caller-supplied environment (docker_* owns its own sandbox lifecycle).
 		if (transport?.kind === "sbx") await teardownSandbox("session_shutdown");
@@ -250,18 +323,22 @@ 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",
 			);
 		},
 	});
 
-	pi.registerTool(routed(localRead, (t) => createReadToolDefinition(localCwd, { operations: createReadOps(t) })));
-	pi.registerTool(routed(localWrite, (t) => createWriteToolDefinition(localCwd, { operations: createWriteOps(t) })));
-	pi.registerTool(routed(localEdit, (t) => createEditToolDefinition(localCwd, { operations: createEditOps(t) })));
-	pi.registerTool(routed(localBash, (t) => createBashToolDefinition(localCwd, { operations: createBashOps(t, { allowEnv: bashAllowEnv }) })));
-	pi.registerTool(routed(localLs, (t) => createLsToolDefinition(localCwd, { operations: createLsOps(t) })));
-	pi.registerTool(routed(localFind, (t) => createFindToolDefinition(localCwd, { operations: createFindOps(t) })));
+	pi.registerTool(routed(localRead, (t, cwd) => createReadToolDefinition(cwd, { operations: createReadOps(t) })));
+	pi.registerTool(routed(localWrite, (t, cwd) => createWriteToolDefinition(cwd, { operations: createWriteOps(t) })));
+	pi.registerTool(routed(localEdit, (t, cwd) => createEditToolDefinition(cwd, { operations: createEditOps(t) })));
+	pi.registerTool(routed(localBash, (t, cwd) => createBashToolDefinition(cwd, { operations: createBashOps(t, { allowEnv: bashAllowEnv }) })));
+	pi.registerTool(routed(localLs, (t, cwd) => createLsToolDefinition(cwd, { operations: createLsOps(t) })));
+	pi.registerTool(routed(localFind, (t, cwd) => createFindToolDefinition(cwd, { operations: createFindOps(t) })));
 	// grep is replaced wholesale, not merely re-pointed: pi's grep tool spawns
 	// host ripgrep for match discovery regardless of custom operations, which
 	// would scan the host filesystem and require rg on the host. The sandbox
@@ -269,27 +346,47 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		...localGrep,
 		async execute(id, params, signal, onUpdate, ctx) {
+			const cwd = sessionCwd(ctx);
 			const t = await ensureTransport(ctx);
-			if (!t) return localGrep.execute(id, params, signal, onUpdate, ctx);
-			return withSandboxFailureHandling(ctx, () => executeSandboxGrep(t, localCwd, params as GrepToolInput));
+			if (!t) {
+				assertLocalFallbackAllowed();
+				return localGrep.execute(id, params, signal, onUpdate, ctx);
+			}
+			return withSandboxFailureHandling(ctx, () => executeSandboxGrep(t, cwd, 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}`;

package/sandbox/session-scope.ts

@@ -0,0 +1,63 @@
+/**
+ * Session-scope guards for the sbx tool router.
+ *
+ * **Zero imports on purpose** (same discipline as `failure.ts`): the vendored
+ * repo's own suite cannot run from the config repo, but this module can be
+ * unit-tested by relative path from `agent/extensions/sbx-backend/`.
+ *
+ * Why these exist: `@tintinweb/pi-subagents` builds every subagent as a FRESH
+ * `AgentSession` **in the same process**, seeded from pi's *built-in* tool
+ * definitions and a fresh `DefaultResourceLoader`. It never sees the parent's
+ * CLI `-e <checkout>/sandbox` extension, so without help a subagent's `bash`
+ * runs on the HOST (measured: `uid=502(sas054)` / `Darwin`, CoreSimulator
+ * visible) while the main agent's runs in the VM.
+ *
+ * The bridge that fixes that (`agent/extensions/sbx-backend/`) is loaded into
+ * every subagent session, and it is the ONLY loader under `pidock` (the
+ * launcher no longer passes `-e`). Two invariants still need enforcing:
+ *
+ *  1. **Only the top-level session tears the sandbox down.** The sandbox name
+ *     is per-process (`pi-sbx-<pid>-<rand>`); every child session shares the
+ *     parent's VM. A child's `session_shutdown` would otherwise `sbx rm
+ *     --force` the sandbox out from under the running parent.
+ *
+ *  2. **One loader per session.** Normally this is by construction, but if a
+ *     caller ALSO loads the backend explicitly (`pi -e <checkout>/sandbox,
+ *     the vendored repo's standalone usage) while the bridge is active, pi
+ *     refuses the second registration (`Tool "read" conflicts with …`). There
+ *     is no way to dedupe that from here: pi gives each EXTENSION its own
+ *     `ExtensionAPI` object (measured — a marker stored on it did not dedupe),
+ *     so the two loaders cannot see each other. Documented, not guarded.
+ */
+
+/** Process-wide marker: which session owns sandbox teardown. */
+const LIFECYCLE_OWNER = Symbol.for("pi-docker-sandbox.lifecycle.owner");
+
+/**
+ * Claim process-wide lifecycle ownership.
+ *
+ * `true` only for the FIRST session to ask — the top-level one, which is
+ * necessarily the first to load the router. Child sessions get `false` and
+ * must skip teardown. The claim is intentionally never released: pi can create
+ * a new top-level session in the same process (`/new`), and that session must
+ * not tear down a sandbox other sessions may still be using; leaked sandboxes
+ * are reclaimed by the existing `gcSweep` safety net.
+ */
+export function claimLifecycleOwnership(): boolean {
+	const g = globalThis as unknown as Record<symbol, unknown>;
+	if (g[LIFECYCLE_OWNER]) return false;
+	g[LIFECYCLE_OWNER] = true;
+	return true;
+}
+
+/**
+ * Whether the launcher selected the sbx router for this process.
+ *
+ * `sbx/pidock` exports `PI_TOOL_ROUTER=sbx` to make the auto-discovered
+ * gondolin backend yield; this backend uses the same marker so the bridge is
+ * inert under bare `pi`, `pix` and `sbxpi` (none of which route host tools
+ * into an sbx sandbox).
+ */
+export function isSbxRouterSelected(env: Record<string, string | undefined>): boolean {
+	return (env.PI_TOOL_ROUTER ?? "").trim().toLowerCase() === "sbx";
+}