pi-crew 0.11.35 → 0.11.37

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-crew",
-	"version": "0.11.35",
+	"version": "0.11.37",
 	"description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
 	"author": "baphuongna",
 	"license": "MIT",

package/src/config/env-allowlist-registry.ts

@@ -216,6 +216,15 @@ const CREW_ENV_FORWARDING_DECL: Record<string, CrewEnvForwardDecision> = {
 	},
 	PI_CREW_INFERENCE_UPSTREAM_ANTHROPIC: { kind: "test-only", reason: "v0.11.34 anthropic-only broker upstream override — TESTS ONLY" },
 	PI_CREW_INFERENCE_UPSTREAM_OPENAI: { kind: "test-only", reason: "v0.11.34 openai-only broker upstream override — TESTS ONLY" },
+	PI_CREW_INFERENCE_UPSTREAM_GOOGLE: { kind: "test-only", reason: "v0.11.36 google-only broker upstream override — TESTS ONLY" },
+	PI_CREW_SANDBOX: {
+		kind: "gap",
+		reason: "v0.11.36 OS-boundary knob read in the PARENT spawn path only (bwrap wrap decision) — deliberately never forwarded to children",
+	},
+	PI_CREW_SANDBOX_NET: {
+		kind: "gap",
+		reason: "v0.11.36 sandbox network profile (share|off) read in the PARENT spawn path only — deliberately never forwarded to children",
+	},
 	PI_CREW_STEERING_FILE: { kind: "child-write", reason: "child-pi-spawn per-run steering JSONL" },
 	PI_CREW_MAX_OUTPUT: { kind: "child-write", reason: "pi-args emits agent.maxTokens into built.env" },
 	PI_CREW_RPC_SECRET: { kind: "child-write", reason: "shared HMAC secret handed to the child at spawn — secret name, never allowlisted" },

package/src/config/env-vars.ts

@@ -520,6 +520,18 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 		name: "PI_CREW_INFERENCE_UPSTREAM_OPENAI",
 		doc: "v0.11.34 openai-only broker upstream override (beats PI_CREW_INFERENCE_UPSTREAM). TESTS ONLY — local mock; production must never set it",
 	},
+	PI_CREW_INFERENCE_UPSTREAM_GOOGLE: {
+		name: "PI_CREW_INFERENCE_UPSTREAM_GOOGLE",
+		doc: "v0.11.36 google-only broker upstream override (beats PI_CREW_INFERENCE_UPSTREAM; default https://generativelanguage.googleapis.com, native google-generative-ai wire, x-goog-api-key auth). TESTS ONLY — local mock; production must never set it",
+	},
+	PI_CREW_SANDBOX: {
+		name: "PI_CREW_SANDBOX",
+		doc: "v0.11.36 OS-boundary sandbox, Linux opt-in: 'bwrap' wraps every headless child-pi worker in bubblewrap — the worker sees ONLY the project cwd (rw), the scoped inference agent dir, explicitly handed-in temp/scratch paths, and read-only OS runtime; ~/.pi (auth.json!), ~/.ssh and every other host path are NOT MOUNTED (fail-closed: forgotten paths yield ENOENT inside, never host access). Fail-closed knob: unsupported value / non-Linux / missing bwrap binary / net=off+broker all THROW before any spawn (never silently unsandboxed). Pass-1 boundary: TUI surface panes and the rpc transport are SKIPPED while on (fail-closed branch selection); PI_CREW_SANDBOX_NET=share keeps host networking — egress is NOT isolated unless net=off. Sandbox+broker-off = workers have no credentials at all (by isolation) — pair with PI_CREW_INFERENCE_BROKER=1 for sandboxed inference (sandbox.ts)",
+	},
+	PI_CREW_SANDBOX_NET: {
+		name: "PI_CREW_SANDBOX_NET",
+		doc: "v0.11.36 sandbox network profile: 'share' (default — host networking, loopback inference broker reachable, egress NOT isolated) or 'off' (unshare the net stack entirely: no egress, no loopback — REJECTED while the inference broker is active because broker-token workers would be keyless AND netless) (sandbox.ts)",
+	},
 	PI_CREW_CLASSIFIER_ENABLED: {
 		name: "PI_CREW_CLASSIFIER_ENABLED",
 		parser: "boolean",

package/src/runtime/child-pi/child-pi-spawn.ts

@@ -31,6 +31,7 @@ import type { ChildPiRunInput, ChildPiRunResult } from "./child-pi.ts";
 import {
 	getInferenceBrokerSnapshot,
 	INFERENCE_TOKEN_ENV,
+	inferenceWorkerKeyForAgent,
 	PI_AGENT_DIR_ENV,
 	registerInferenceWorker,
 	requireInferenceBrokerIfEnabled,
@@ -344,7 +345,12 @@ export function prepareSpawnContext(
 	const inferenceSnapshot = requireInferenceBrokerIfEnabled();
 	let inferenceWorkerKey: string | undefined;
 	if (inferenceSnapshot.active) {
-		inferenceWorkerKey = input.agentId ? `inference:${input.agentId}` : `inference:spawn:${process.pid}:${Date.now().toString(36)}`;
+		// v0.11.36: the agentId derivation is SHARED with the exit-revoke wrapper
+		// (runChildPi finally) via inferenceWorkerKeyForAgent — both sides must
+		// compute the SAME key or revoke-on-exit silently misses.
+		inferenceWorkerKey = input.agentId
+			? inferenceWorkerKeyForAgent(input.agentId)
+			: `inference:spawn:${process.pid}:${Date.now().toString(36)}`;
 		built.env[INFERENCE_TOKEN_ENV] = registerInferenceWorker(inferenceWorkerKey);
 	}
 	// Pass steering file path to child for real-time steer injection

package/src/runtime/child-pi/child-pi.ts

@@ -36,8 +36,9 @@ import { ChildPiSteeringController } from "./child-pi-steering.ts";
 import { ChildPiLineObserver, isFinalAssistantEvent } from "./child-pi-streams.ts";
 // Phase 2.3: the six timer constructs moved to child-pi-timers.ts (pure motion).
 import { createChildPiTimers } from "./child-pi-timers.ts";
-import { maybeStartInferenceBroker } from "./inference-broker.ts";
+import { getInferenceBrokerSnapshot, maybeStartInferenceBroker, revokeInferenceWorkerForAgent } from "./inference-broker.ts";
 import { runMockChildPi } from "./mock-fixtures.ts";
+import { applySandboxToSpawnSpec, assertSandboxAvailable, resolveSandboxConfig, type SandboxConfig } from "./sandbox.ts";
 // W2 (session-file recovery): deterministic worker session flags + crash-path
 // tail-replay of the session JSONL (see session-recovery.ts header).
 import {
@@ -703,6 +704,21 @@ async function trySurfaceBranch(
 export const __test__trySurfaceBranch = trySurfaceBranch;
 
 export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResult> {
+	// v0.11.36 exit-revoke WRAPPER: whatever the inner run does — normal exit,
+	// crash, B5 pre-spawn abort, surface/rpc branch, even a thrown error — the
+	// task's inference token dies with the run. prepareSpawnContext registers
+	// `inference:<agentId>` BEFORE its B5 abort check, so an aborted run that
+	// never spawned still leaves a token behind unless revoked HERE. Retries
+	// are safe: they call runChildPi again and re-register a FRESH token
+	// (register-replace semantics) after this revoke already ran.
+	try {
+		return await runChildPiInner(input);
+	} finally {
+		revokeInferenceWorkerForAgent(input.agentId);
+	}
+}
+
+async function runChildPiInner(input: ChildPiRunInput): Promise<ChildPiRunResult> {
 	// Phase 1 (live-session parity): prepend parent context when inheritContext is true.
 	// This mirrors the effectivePrompt logic in live-session-runtime.ts so that
 	// child-process workers receive the same inherited-context treatment.
@@ -781,6 +797,14 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 	// v0.11.31: start the inference broker (flag-gated, fail-closed) BEFORE the
 	// sync spawn-prep path — http listen needs an event-loop turn.
 	await maybeStartInferenceBroker();
+	// v0.11.36 OS boundary (bwrap, Linux opt-in): resolve + VALIDATE + probe
+	// BEFORE any spawn. Every misconfiguration throws here (fail-closed — a
+	// sandbox that cannot start must never degrade to an unsandboxed spawn).
+	const sandbox: SandboxConfig = resolveSandboxConfig(process.env, {
+		platform: process.platform,
+		brokerActive: getInferenceBrokerSnapshot().active,
+	});
+	assertSandboxAvailable(sandbox);
 	const spawnPrep = prepareSpawnContext(brokerSpawn ? { ...versionedInput, brokerSpawn } : versionedInput, effectiveTask, depthEnv);
 	if (spawnPrep.kind === "aborted") return spawnPrep.result;
 	const { spawnSpec, mergedEnv, tempDir, builtEnv, builtArgs } = spawnPrep.ctx;
@@ -805,7 +829,10 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 	// MuxSurface A1 (spec §13.1): attempt booting the worker in a mux pane BEFORE
 	// spawning a stdio pipe. Returns a finished result in surface mode (pane exit
 	// awaited) or null → fall through to the classic headless spawn below.
-	const surfaceResult = await trySurfaceBranch(input, depthEnv, builtArgs, mergedEnv, builtEnv, tempDir);
+	// v0.11.36: TUI panes are NOT sandboxed (pass 1) — when the sandbox is on
+	// the branch is SKIPPED so a sandboxed request can never land in an
+	// unsandboxed pane (fail-closed branch selection).
+	const surfaceResult = sandbox.enabled ? null : await trySurfaceBranch(input, depthEnv, builtArgs, mergedEnv, builtEnv, tempDir);
 	if (surfaceResult) return surfaceResult;
 	// U14 (child-pi protocol v2 — upgrade-spec 2026-10-09): `--mode rpc`
 	// transport, opt-in via PI_CREW_CHILD_PI_MODE=rpc (json remains the
@@ -814,7 +841,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 	// json branch below stays the fail-safe path. Surface TUI panes are
 	// unaffected — trySurfaceBranch consumed builtArgs above and never
 	// reaches this point in surface mode.
-	if (resolveChildPiRpcMode()) {
+	if (!sandbox.enabled && resolveChildPiRpcMode()) {
 		const rpcResult = await tryChildPiRpcRun({ input, effectiveTask, ctx: spawnPrep.ctx, workerSession, sessionRecoveryEnabled });
 		if (rpcResult) return rpcResult;
 	}
@@ -824,7 +851,38 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			// owned by buildFinalChildPiSpawnOptions (see child-pi-spawn.ts, BLOCKER 2 / S5).
 			// R6-8: modelChain threads the candidate chain for provider-key scoping.
 			const spawnOptions = buildFinalChildPiSpawnOptions(input.cwd, mergedEnv, builtEnv, input.model, input.modelChain);
-			const child = spawn(spawnSpec.command, spawnSpec.args, spawnOptions);
+			// v0.11.36 OS boundary: when the sandbox is on, the headless spawn is
+			// wrapped in bwrap. Mounts: cwd RW (the worker edits the project), the
+			// scoped inference agent dir RW (pi writes session state under it), and
+			// the parent-side paths this run handed the worker via env/argv
+			// (task.md tempDir, scratchpad snapshot/restore, steering file) READ-ONLY
+			// plus the inter-pi broker socket RW (connect() needs write perm). A
+			// forgotten path fails CLOSED inside the namespace (ENOENT) — it never
+			// silently reaches the host.
+			let spawnCommand = spawnSpec.command;
+			let spawnArgs = spawnSpec.args;
+			if (sandbox.enabled) {
+				const inferenceSnap = getInferenceBrokerSnapshot();
+				const wrapped = applySandboxToSpawnSpec(
+					{ command: spawnSpec.command, args: spawnSpec.args },
+					{
+						cwd: input.cwd,
+						net: sandbox.net,
+						agentDir: inferenceSnap.active ? inferenceSnap.scopedAgentDir : undefined,
+						roBindPaths: [
+							tempDir,
+							builtEnv.PI_CREW_SCRATCHPAD_SNAPSHOT,
+							builtEnv.PI_CREW_SCRATCHPAD_RESTORE,
+							builtEnv.PI_CREW_STEERING_FILE,
+						].filter((p): p is string => typeof p === "string" && p.length > 0),
+						rwBindPaths: [input.brokerSpawn?.socketPath].filter((p): p is string => typeof p === "string" && p.length > 0),
+					},
+				);
+				spawnCommand = wrapped.command;
+				spawnArgs = wrapped.args;
+				spawnOptions.env = { ...spawnOptions.env, ...wrapped.envOverrides };
+			}
+			const child = spawn(spawnCommand, spawnArgs, spawnOptions);
 			if (child.pid) {
 				registerActiveChild(child.pid, child);
 				input.onSpawn?.(child.pid);

package/src/runtime/child-pi/inference-broker.ts

@@ -106,11 +106,15 @@ export interface InferenceBrokerSnapshot {
 	providers: string[];
 }
 
-/** One provider's upstream route: base URL + substituted auth header. */
+/** One provider's upstream route: base URL + substituted auth header. The
+ * upstream DEFAULT carries the provider's version path (openai …/v1, google
+ * …/v1beta) exactly like the built-in models' baseUrls do — the scoped
+ * models.json replaces the WHOLE baseUrl with a bare /<provider> prefix, so
+ * the version path must never be duplicated on the broker side. */
 interface ProviderRoute {
-	name: "anthropic" | "openai";
+	name: "anthropic" | "openai" | "google";
 	upstream: string;
-	auth: { header: "x-api-key" | "authorization"; value: string };
+	auth: { header: "x-api-key" | "authorization" | "x-goog-api-key"; value: string };
 }
 
 interface BrokerState {
@@ -186,6 +190,29 @@ function resolveProviderRoutes(env: NodeJS.ProcessEnv): { routes: ProviderRoute[
 		routes.push({ name: "openai", upstream: openaiUpstream, auth: { header: "authorization", value: `Bearer ${openaiStored.key}` } });
 	}
 
+	// v0.11.36 google (native google-generative-ai wire): the built-in google
+	// provider speaks `x-goog-api-key` and paths under /v1beta (verified against
+	// the pi catalog: ids like "gemini-2.5-pro", baseUrl ...
+	// /v1beta). Credential precedence mirrors the others: env FIRST
+	// (GOOGLE_API_KEY, then GEMINI_API_KEY — both conventional), then auth.json:google.
+	const googleUpstream =
+		getCrewEnv("PI_CREW_INFERENCE_UPSTREAM_GOOGLE", env) || genericUpstream || "https://generativelanguage.googleapis.com/v1beta";
+	const googleApiKey = env.GOOGLE_API_KEY;
+	const geminiApiKey = env.GEMINI_API_KEY;
+	const googleStored = authJson.google;
+	consulted.push("env GOOGLE_API_KEY", "env GEMINI_API_KEY", "auth.json:google");
+	const googleCredential =
+		googleApiKey && googleApiKey.length > 0
+			? googleApiKey
+			: geminiApiKey && geminiApiKey.length > 0
+				? geminiApiKey
+				: googleStored?.type === "api_key" && typeof googleStored.key === "string" && googleStored.key.length > 0
+					? googleStored.key
+					: undefined;
+	if (googleCredential) {
+		routes.push({ name: "google", upstream: googleUpstream, auth: { header: "x-goog-api-key", value: googleCredential } });
+	}
+
 	return { routes, trace: consulted.join(", ") };
 }
 
@@ -212,7 +239,7 @@ export async function maybeStartInferenceBroker(env: NodeJS.ProcessEnv = process
 	const { routes, trace } = resolveProviderRoutes(env);
 	if (routes.length === 0) {
 		throw new Error(
-			`${INFERENCE_BROKER_ENABLE_ENV}=1 but no provider credential resolved for the inference broker (consulted: ${trace}) — fail-closed: workers would otherwise receive no usable credential, or worse, fall back to real provider keys. Provide ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN / OPENAI_API_KEY in the parent env, an api_key entry for anthropic/openai in the parent's auth.json, or unset ${INFERENCE_BROKER_ENABLE_ENV}.`,
+			`${INFERENCE_BROKER_ENABLE_ENV}=1 but no provider credential resolved for the inference broker (consulted: ${trace}) — fail-closed: workers would otherwise receive no usable credential, or worse, fall back to real provider keys. Provide ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN / OPENAI_API_KEY / GOOGLE_API_KEY / GEMINI_API_KEY in the parent env, an api_key entry for anthropic/openai/google in the parent's auth.json, or unset ${INFERENCE_BROKER_ENABLE_ENV}.`,
 		);
 	}
 	broker = await createBrokerServer(routes);
@@ -312,10 +339,12 @@ function buildScopedAgentDir(port: number, routes: ProviderRoute[]): string {
 	return dir;
 }
 
-/** Extract the caller token from x-api-key or Authorization: Bearer. */
+/** Extract the caller token from x-api-key, x-goog-api-key, or Authorization: Bearer. */
 function extractToken(req: http.IncomingMessage): string | undefined {
 	const apiKey = req.headers["x-api-key"];
 	if (typeof apiKey === "string" && apiKey.length > 0) return apiKey;
+	const googKey = req.headers["x-goog-api-key"];
+	if (typeof googKey === "string" && googKey.length > 0) return googKey;
 	const auth = req.headers.authorization;
 	if (typeof auth === "string" && auth.startsWith("Bearer ")) return auth.slice("Bearer ".length);
 	return undefined;
@@ -347,7 +376,7 @@ async function handleRequest(
 			}
 		}
 		if (!route) {
-			deny(res, 404, "unknown provider route (expected /anthropic/... or /openai/...)");
+			deny(res, 404, "unknown provider route (expected /anthropic/..., /openai/..., or /google/...)");
 			return;
 		}
 		// (1) Auth — fail-closed, generic errors (never echo tokens).
@@ -458,9 +487,23 @@ class UsageCounter {
 				// SSE message_delta: evt.usage.output_tokens is CUMULATIVE (take max).
 				// Non-stream JSON body: top-level evt.usage, both absolute.
 				const usage = evt?.message?.usage ?? evt?.usage;
+				// Google native (google-generative-ai): usageMetadata with
+				// promptTokenCount / candidatesTokenCount (+ thoughtsTokenCount) —
+				// CUMULATIVE per stream, so max() below lands on the final totals.
+				const meta = evt?.usageMetadata;
+				if (meta && typeof meta === "object") {
+					const prompt = typeof meta.promptTokenCount === "number" ? meta.promptTokenCount : 0;
+					const candidates = typeof meta.candidatesTokenCount === "number" ? meta.candidatesTokenCount : 0;
+					const thoughts = typeof meta.thoughtsTokenCount === "number" ? meta.thoughtsTokenCount : 0;
+					this.input = Math.max(this.input, prompt);
+					this.output = Math.max(this.output, candidates + thoughts);
+				}
 				if (!usage || typeof usage !== "object") continue;
 				// Anthropic: input_tokens / output_tokens. OpenAI chat-completions:
 				// prompt_tokens / completion_tokens (final usage chunk, absolute).
+				// Google native (google-generative-ai): usageMetadata with
+				// promptTokenCount / candidatesTokenCount (+ thoughtsTokenCount) —
+				// CUMULATIVE per stream, so max() below lands on the final totals.
 				const inTok =
 					typeof usage.input_tokens === "number"
 						? usage.input_tokens
@@ -503,6 +546,28 @@ export function registerInferenceWorker(workerKey: string): string {
 	return token;
 }
 
+/** Deterministic worker key for a task-owned worker — SHARED by the spawn side (prepareSpawnContext) and the exit-revoke wrapper (runChildPi finally). */
+export function inferenceWorkerKeyForAgent(agentId: string): string {
+	return `inference:${agentId}`;
+}
+
+/**
+ * Non-throwing exit hook (v0.11.36): revoke a task worker's inference token
+ * when its runChildPi call settles — normal exit, crash, or abort. Anonymous
+ * (agentId-less) spawns use per-spawn unique keys that only the spawn path
+ * knows; their tokens die at register-replacement or broker stop. Broker off
+ * → no-op. NEVER throws (must not mask a worker result).
+ */
+export function revokeInferenceWorkerForAgent(agentId: string | undefined): boolean {
+	if (!agentId) return false;
+	try {
+		if (!getInferenceBrokerSnapshot().active) return false;
+		return revokeInferenceWorker(inferenceWorkerKeyForAgent(agentId));
+	} catch {
+		return false;
+	}
+}
+
 /** Kill-switch for one worker: its token dies on the NEXT request. */
 export function revokeInferenceWorker(workerKey: string): boolean {
 	if (!broker) return false;

package/src/runtime/child-pi/sandbox.ts

@@ -0,0 +1,224 @@
+/**
+ * v0.11.36 OS-boundary sandbox (Linux opt-in, bubblewrap).
+ *
+ * WHAT IT IS: an optional bwrap (bubblewrap) wrapper around headless child-pi
+ * workers that closes the HOST-FILE hole the env layer cannot — a sandboxed
+ * worker sees ONLY: the project cwd (read-write — it must edit files), its
+ * scoped inference agent dir, explicitly handed-in temp/scratch paths, and
+ * the OS runtime (/usr, /etc, /dev, /proc as read-only mounts + tmpfs /tmp,
+ * /run). Everything else on the host — ~/.pi/auth.json, ~/.ssh, dotfiles,
+ * browser profiles — is simply NOT MOUNTED into the namespace. Fail-closed:
+ * a path we forgot to bind yields ENOENT inside the sandbox, never silent
+ * host access.
+ *
+ * WHAT IT IS NOT (honest boundary, pass 1):
+ * - Egress isolation: `PI_CREW_SANDBOX_NET=off` unshares the network stack
+ *   entirely (nothing reachable — including the loopback inference broker),
+ *   which is why net=off is REJECTED while the inference broker is active.
+ *   The default `share` profile keeps host networking: a worker with a
+ *   broker token can still open outbound connections to the internet.
+ * - TUI surface panes and the rpc transport are NOT sandboxed (pass 1): when
+ *   the sandbox is enabled both branches are skipped so every worker takes
+ *   the sandboxed headless path (fail-closed, never fail-open).
+ *
+ * FAIL-CLOSED CONTRACT: every misconfiguration throws BEFORE any spawn —
+ * unsupported value, non-Linux platform, missing bwrap binary, or the
+ * net=off + broker contradiction. A sandbox that cannot start must never
+ * silently degrade to an unsandboxed spawn.
+ */
+import { type SpawnSyncOptions, type SpawnSyncReturns, spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export const SANDBOX_ENV = "PI_CREW_SANDBOX";
+export const SANDBOX_NET_ENV = "PI_CREW_SANDBOX_NET";
+
+export interface SandboxConfig {
+	enabled: boolean;
+	mode: "off" | "bwrap";
+	/** "share" keeps host networking (inference broker reachable); "off" unshares the net stack entirely. */
+	net: "share" | "off";
+}
+
+/** Resolve + VALIDATE the sandbox knobs. Throws fail-closed on any misconfiguration (never silently unsandboxed). */
+export function resolveSandboxConfig(env: NodeJS.ProcessEnv, opts: { platform: NodeJS.Platform; brokerActive: boolean }): SandboxConfig {
+	const raw = (env[SANDBOX_ENV] ?? "").trim();
+	if (raw === "" || raw === "0") return { enabled: false, mode: "off", net: "share" };
+	if (raw !== "bwrap") {
+		throw new Error(
+			`${SANDBOX_ENV}: unsupported value '${raw}' (supported: 'bwrap') — fail-closed: refusing to spawn with an unrecognized sandbox mode`,
+		);
+	}
+	const netRaw = (env[SANDBOX_NET_ENV] ?? "share").trim().toLowerCase();
+	if (netRaw !== "share" && netRaw !== "off") {
+		throw new Error(
+			`${SANDBOX_NET_ENV}: unsupported value '${netRaw}' (supported: 'share' | 'off') — fail-closed: refusing to spawn with an unrecognized network profile`,
+		);
+	}
+	if (netRaw === "off" && opts.brokerActive) {
+		throw new Error(
+			`${SANDBOX_NET_ENV}=off is incompatible with the inference broker: a new network namespace has no loopback route to the 127.0.0.1 broker, so broker-token workers would be keyless AND netless. Either keep ${SANDBOX_NET_ENV}=share or unset ${SANDBOX_ENV}/PI_CREW_INFERENCE_BROKER.`,
+		);
+	}
+	return { enabled: true, mode: "bwrap", net: netRaw };
+}
+
+/** Binary/platform gate. Throws when a bwrap sandbox cannot be honored (fail-closed). */
+export function assertSandboxAvailable(
+	config: SandboxConfig,
+	deps: {
+		platform: NodeJS.Platform;
+		spawnSync: (cmd: string, args: string[], opts?: SpawnSyncOptions) => SpawnSyncReturns<string> | { error: unknown; status: null };
+	} = {
+		platform: process.platform,
+		spawnSync: (cmd, args, opts) => spawnSync(cmd, args, opts) as SpawnSyncReturns<string>,
+	},
+): void {
+	if (!config.enabled) return;
+	if (deps.platform !== "linux") {
+		throw new Error(
+			`${SANDBOX_ENV}=bwrap is Linux-only (bubblewrap user namespaces); current platform is ${deps.platform} — fail-closed: refusing to spawn unsandboxed`,
+		);
+	}
+	const probe = deps.spawnSync("bwrap", ["--version"], { timeout: 5000 });
+	if (probe.error || probe.status !== 0) {
+		throw new Error(
+			`${SANDBOX_ENV}=bwrap requires the 'bwrap' binary (bubblewrap) on PATH — not runnable here (fail-closed: refusing to spawn unsandboxed). Install bubblewrap or unset ${SANDBOX_ENV}.`,
+		);
+	}
+}
+
+export interface SandboxWrapInput {
+	/** Project dir — mounted read-write (the worker's whole job is editing it). */
+	cwd: string;
+	/** "share" keeps host networking (inference broker reachable); "off" unshares the net stack entirely. */
+	net: "share" | "off";
+	/** Scoped inference agent dir (models.json only) — mounted read-write (pi may write session state under it). */
+	agentDir?: string;
+	/** Parent-side paths the worker must READ (task.md tempDir, scratchpad snapshot/restore, steering file). */
+	roBindPaths?: string[];
+	/** Parent-side paths the worker must reach read-write (inter-pi broker socket — connect() needs write permission). */
+	rwBindPaths?: string[];
+	/** Package-root detector for resource walks (injectable to keep applySandboxToSpawnSpec pure in tests). */
+	isPackageRoot?: (dir: string) => boolean;
+}
+
+/** Toolchain mounts a wrapped spec needs (deduped):
+ * - the runtime bin dir (nvm/homebrew node lives outside /usr),
+ * - for the entry script (.js arg 0): its dir + every ancestor `node_modules`
+ *   (ESM/CJS resolution walks them for the SDK's external deps),
+ * - for every `--extension`/`--skill` value: the value + ancestor dirs up to
+ *   and including the nearest package root (extensions import siblings
+ *   across their package: prompt-runtime.ts reaches ../config, ../state …).
+ */
+function toolchainBinds(spec: { command: string; args: string[] }, isPackageRoot: (dir: string) => boolean): string[] {
+	const binds = new Set<string>();
+	if (path.isAbsolute(spec.command)) binds.add(path.dirname(spec.command));
+	const entry = spec.args[0];
+	if (entry && path.isAbsolute(entry) && entry.endsWith(".js")) {
+		binds.add(path.dirname(entry));
+		for (let dir = path.dirname(path.dirname(entry)); dir !== path.dirname(dir); dir = path.dirname(dir)) {
+			if (path.basename(dir) === "node_modules") binds.add(dir);
+		}
+	}
+	// --extension / --skill resources: bind the value + ancestors up to the
+	// nearest package root (extensions import across their package tree).
+	for (let i = 0; i < spec.args.length - 1; i++) {
+		const flag = spec.args[i];
+		if (flag !== "--extension" && flag !== "--skill") continue;
+		const value = spec.args[i + 1];
+		if (!value || !path.isAbsolute(value)) continue;
+		binds.add(value);
+		for (let dir = path.dirname(value); dir !== path.dirname(dir); dir = path.dirname(dir)) {
+			binds.add(dir);
+			if (isPackageRoot(dir)) break;
+		}
+	}
+	return [...binds];
+}
+
+/** Default package-root probe: a directory carrying package.json (extensions import across their package tree). */
+function defaultIsPackageRoot(dir: string): boolean {
+	try {
+		return fs.statSync(path.join(dir, "package.json")).isFile();
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Wrap a spawn spec in a bwrap invocation. Unit-testable on every platform
+ * (inject isPackageRoot to avoid IO); ordering matters: --tmpfs /tmp precedes
+ * any bind under /tmp so parent temp paths surface at their REAL paths.
+ */
+export function applySandboxToSpawnSpec(
+	spec: { command: string; args: string[] },
+	wrap: SandboxWrapInput,
+): { command: string; args: string[]; envOverrides: Record<string, string> } {
+	const args: string[] = [
+		"--unshare-all",
+		// net=share: re-share host networking AFTER --unshare-all (the
+		// inference broker lives on host loopback). net=off leaves the new
+		// netns fully isolated — nothing reachable, broker included.
+		...(wrap.net === "share" ? ["--share-net"] : []),
+		"--die-with-parent",
+		"--new-session",
+		"--ro-bind",
+		"/usr",
+		"/usr",
+		"--ro-bind-try",
+		"/etc",
+		"/etc",
+		"--ro-bind-try",
+		"/bin",
+		"/bin",
+		"--ro-bind-try",
+		"/lib",
+		"/lib",
+		"--ro-bind-try",
+		"/lib64",
+		"/lib64",
+		"--ro-bind-try",
+		"/sbin",
+		"/sbin",
+		// TOOLCHAIN: the wrapped command is usually process.execPath — which on
+		// developer machines lives OUTSIDE /usr (nvm: ~/.nvm/.../bin/node,
+		// homebrew: /opt/homebrew/...). Without mounting its directory the
+		// sandbox cannot even exec the runtime (bwrap: execvp ENOENT — found by
+		// the real-smoke test on this very machine). The node bin dir is
+		// toolchain, not user data — same class as /usr.
+		//
+		// The pi bundle entry (spec.args[0] when an absolute .js file) brings its
+		// OWN tree: the bundle dir has sibling chunks/runtime files, and ESM/CJS
+		// resolution walks every ancestor `node_modules` for the SDK's external
+		// deps (jiti/yaml/...). Bind the entry DIR + each ancestor named
+		// node_modules, READ-ONLY — dependency trees are toolchain, not user data.
+		...toolchainBinds(spec, wrap.isPackageRoot ?? defaultIsPackageRoot).flatMap((p) => ["--ro-bind-try", p, p]),
+		"--proc",
+		"/proc",
+		"--dev",
+		"/dev",
+		"--tmpfs",
+		"/tmp",
+		"--tmpfs",
+		"/run",
+		// Project dir read-write at its real path (mount order guarantees this
+		// wins over any ancestor tmpfs).
+		"--bind",
+		wrap.cwd,
+		wrap.cwd,
+	];
+	if (wrap.agentDir) {
+		args.push("--bind", wrap.agentDir, wrap.agentDir);
+	}
+	for (const p of wrap.roBindPaths ?? []) {
+		args.push("--ro-bind-try", p, p);
+	}
+	for (const p of wrap.rwBindPaths ?? []) {
+		args.push("--bind-try", p, p);
+	}
+	args.push("--chdir", wrap.cwd, "--", spec.command, ...spec.args);
+	// HOME/TMPDIR point at the sandbox tmpfs: the worker's writes land in
+	// scratch space, and ~/.pi (auth.json!) simply does not exist inside.
+	return { command: "bwrap", args, envOverrides: { HOME: "/tmp", TMPDIR: "/tmp" } };
+}