pi-microsandbox 0.1.0 → 0.2.0

package/extensions/pi-msb/config.ts

@@ -1,6 +1,6 @@
 import { promises as fs } from "node:fs";
 import { homedir as osHomedir } from "node:os";
-import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
 import type {
   Config,
   ConfigLayerInput,
@@ -19,6 +19,37 @@ const CONTROL_KEYS = new Set(["removeSecrets", "removeMounts", "removeRouteTools
 const SECRET_FIELDS = new Set(["env", "value", "allowHosts"]);
 const MOUNT_FIELDS = new Set(["type", "hostPath", "guestPath", "readonly", "options"]);
 const FORBIDDEN_CONFIG_KEYS = new Set(["__proto__", "prototype", "constructor"]);
+const PROTECTED_GUEST_ENV = new Set([
+  "BASH_ENV",
+  "CDPATH",
+  "DOCKER_CERT_PATH",
+  "DOCKER_CONFIG",
+  "DOCKER_CONTEXT",
+  "DOCKER_HOST",
+  "DOCKER_TLS",
+  "DOCKER_TLS_VERIFY",
+  "ENV",
+  "GLOBIGNORE",
+  "LD_LIBRARY_PATH",
+  "LD_PRELOAD",
+  "PATH",
+  "SHELLOPTS",
+]);
+const PROTECTED_GUEST_PATHS = [
+  "/bin",
+  "/dev",
+  "/etc/ld.so.cache",
+  "/etc/ld.so.preload",
+  "/lib",
+  "/lib64",
+  "/proc",
+  "/sbin",
+  "/sys",
+  "/usr",
+  "/run",
+  "/var/run",
+  "/var/lib/docker",
+] as const;
 
 function deepFreeze<T>(value: T): DeepReadonly<T> {
   if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
@@ -30,11 +61,11 @@ function deepFreeze<T>(value: T): DeepReadonly<T> {
 
 /** Defaults from PLAN §11.2. Values containing credentials are deliberately absent. */
 export const DEFAULT_CONFIG = deepFreeze<Config>({
-  image: "ghcr.io/hcohe/pi-microsandbox:1.0.0@sha256:00ea1e0911189815614e8a8eee36d1fd64f0f1edb39492e0bda9f273c834e59f",
+  image: "ghcr.io/hcohe/pi-microsandbox:1.1.0@sha256:ab4e99d4232f827b3f295ff3210437e01446dbb672ef0d0c78358566170ac86c",
   pullPolicy: "if-missing",
   bootstrapTools: "auto",
-  cpus: 1,
-  memoryMiB: 512,
+  cpus: 4,
+  memoryMiB: 8_192,
   idleTimeoutSec: 600,
   stopTimeoutMs: 10_000,
   detached: true,
@@ -47,6 +78,7 @@ export const DEFAULT_CONFIG = deepFreeze<Config>({
   shallowArchive: false,
   volumeQuotaMiB: 2_048,
   network: { mode: "default", allowHosts: [], allowDns: true, publishPorts: [] },
+  docker: { mode: "auto", startupTimeoutMs: 15_000 },
   secrets: [],
   mounts: [],
   blockThirdParty: true,
@@ -76,6 +108,7 @@ export interface ResolveConfigInput {
   readFile?: (path: string) => Promise<string | null>;
   exists?: (path: string) => Promise<boolean>;
   realpath?: (path: string) => Promise<string>;
+  stat?: (path: string) => Promise<{ isSocket(): boolean }>;
 }
 
 export class ConfigError extends Error {
@@ -299,6 +332,7 @@ function knownPath(path: string): boolean {
     return parts.length === 1 && CONTROL_KEYS.has(parts[0]) && !nestedNetworkRemoval;
   }
   if (parts[0] === "network") return parts.length === 1 || (parts.length === 2 && ["mode", "allowHosts", "allowDns", "publishPorts", "removeAllowHosts", "removePublishPorts"].includes(parts[1]));
+  if (parts[0] === "docker") return parts.length === 1 || (parts.length === 2 && ["mode", "startupTimeoutMs"].includes(parts[1]));
   if (parts[0] === "secrets") return parts.length === 1 || (parts.length === 2 && SECRET_FIELDS.has(parts[1]));
   if (parts[0] === "mounts") return parts.length === 1 || (parts.length === 2 && MOUNT_FIELDS.has(parts[1]));
   return ["image", "pullPolicy", "bootstrapTools", "cpus", "memoryMiB", "idleTimeoutSec", "stopTimeoutMs", "detached", "replace", "replaceTimeoutMs", "sandboxName", "mode", "cloneBranch", "cloneDepth", "shallowArchive", "volumeQuotaMiB", "blockThirdParty", "routeTools", "passThroughTools", "allowHostExecution", "allowSkillReads", "fallbackMode", "exposeSessionEnvironment", "hostEnv", "autoStart", "pruneOnStart", "showFooter", "lockDir", "hostRoAllowlist"].includes(parts[0]);
@@ -495,6 +529,9 @@ export function validateConfig(raw: DeepPartial<Config>): Config {
   if (!n(config.replaceTimeoutMs) || config.replaceTimeoutMs < 1) issues.push(issueForPath("replaceTimeoutMs", "must be positive"));
   if (!n(config.volumeQuotaMiB) || config.volumeQuotaMiB < 1) issues.push(issueForPath("volumeQuotaMiB", "must be positive"));
   if (!["auto", "git", "direct", "none"].includes(config.mode)) issues.push(issueForPath("mode", "unknown storage mode"));
+  const docker = isPlainObject(config.docker) ? config.docker : null;
+  if (!docker || !["auto", "require", "disabled"].includes(docker.mode as string)) issues.push(issueForPath("docker.mode", "must be auto, require, or disabled"));
+  if (!docker || !n(docker.startupTimeoutMs) || !Number.isInteger(docker.startupTimeoutMs) || (docker.startupTimeoutMs as number) < 1 || (docker.startupTimeoutMs as number) > 300_000) issues.push(issueForPath("docker.startupTimeoutMs", "must be an integer between 1 and 300000"));
   if (!["auto", true, false].includes(config.bootstrapTools)) issues.push(issueForPath("bootstrapTools", "must be auto, true, or false"));
   if (!["block", "host"].includes(config.fallbackMode)) issues.push(issueForPath("fallbackMode", "must be block or host"));
   const booleanFields = ["detached", "replace", "shallowArchive", "blockThirdParty", "allowHostExecution", "allowSkillReads", "exposeSessionEnvironment", "autoStart", "pruneOnStart", "showFooter"] as const;
@@ -509,7 +546,7 @@ export function validateConfig(raw: DeepPartial<Config>): Config {
   };
   if (stringArray("routeTools", config.routeTools)) for (const tool of config.routeTools) if (!ROUTED_TOOLS.includes(tool)) issues.push(issueForPath("routeTools", `unknown routed tool ${tool}`));
   stringArray("passThroughTools", config.passThroughTools);
-  stringArray("hostEnv", config.hostEnv);
+  if (stringArray("hostEnv", config.hostEnv)) for (const name of config.hostEnv) if (PROTECTED_GUEST_ENV.has(name)) issues.push(issueForPath("hostEnv", `must not forward protected process environment variable ${name}`));
   stringArray("hostRoAllowlist", config.hostRoAllowlist);
   const network = isPlainObject(config.network) ? config.network : null;
   if (!network || !["default", "open", "allowlist", "deny"].includes(network.mode as string)) issues.push(issueForPath("network.mode", "unknown network mode"));
@@ -521,6 +558,7 @@ export function validateConfig(raw: DeepPartial<Config>): Config {
   if (!Array.isArray(config.secrets)) issues.push(issueForPath("secrets", "must be an array"));
   for (const [index, secret] of (Array.isArray(config.secrets) ? config.secrets : []).entries()) {
     if (!secret || typeof secret.env !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(secret.env)) issues.push(issueForPath(`secrets[${index}]`, "env must be a valid host environment name"));
+    else if (PROTECTED_GUEST_ENV.has(secret.env)) issues.push(issueForPath(`secrets[${index}].env`, `must not set protected process environment variable ${secret.env}`));
     if (typeof secret?.value !== "string") issues.push(issueForPath(`secrets[${index}].value`, "must be a string"));
     if (!Array.isArray(secret?.allowHosts) || !secret.allowHosts.length || secret.allowHosts.some((host: unknown) => typeof host !== "string" || !host)) issues.push(issueForPath(`secrets[${index}]`, "allowHosts must be a non-empty string array"));
   }
@@ -542,6 +580,7 @@ export function validateConfig(raw: DeepPartial<Config>): Config {
     if (typeof guest === "string" && isAbsolute(guest)) {
       const canonical = String(canonicalGuestPath(guest));
       if (isInside(canonical, "/tmp") || isInside("/tmp", canonical)) issues.push(issueForPath(`mounts[${index}].guestPath`, "must not shadow reserved /tmp paths"));
+      if (PROTECTED_GUEST_PATHS.some((reserved) => isInside(canonical, reserved) || isInside(reserved, canonical))) issues.push(issueForPath(`mounts[${index}].guestPath`, "must not shadow protected guest system or Docker runtime paths"));
     }
   }
   if (issues.length) throw new ConfigError(issues);
@@ -599,7 +638,7 @@ export async function resolveConfig(input: ResolveConfigInput): Promise<Resolved
   const canonicalPath = async (path: string, failClosed = false): Promise<string> => {
     try { return await realpath(path); }
     catch {
-      if (failClosed) throw new ConfigError(["trusted project path could not be canonicalized"]);
+      if (failClosed) throw new ConfigError(["mount or trusted project path could not be canonicalized"]);
       return resolve(path);
     }
   };
@@ -629,6 +668,12 @@ export async function resolveConfig(input: ResolveConfigInput): Promise<Resolved
   config = normalizeLegacy(config, warnings);
   // Legacy mounts participate in the same overlap/type checks as native mounts.
   config = validateConfig(config);
+  config = {
+    ...config,
+    mounts: await Promise.all(config.mounts.map(async (mount) => mount.type === "named" || mount.type === "tmpfs"
+      ? mount
+      : { ...mount, hostPath: await canonicalPath(mount.hostPath!, true) })),
+  };
 
   const projectGuestPath = String(canonicalGuestPath(resolve(input.repoRoot ?? input.cwd)));
   const projectShadowIssues = config.mounts.flatMap((mount, index) => {
@@ -649,6 +694,20 @@ export async function resolveConfig(input: ResolveConfigInput): Promise<Resolved
     .filter((mount) => mount && mount.readonly === false)
     .map((mount) => String(canonicalGuestPath(mount.guestPath ?? "")));
   const policyIssues: string[] = [];
+  const mountStat = input.stat ?? fs.stat;
+  const knownHostDockerSockets = ["/var/run/docker.sock", "/run/docker.sock"];
+  if (input.homedir ?? env.HOME) knownHostDockerSockets.push(join(String(input.homedir ?? env.HOME), ".docker", "run", "docker.sock"));
+  if (env.XDG_RUNTIME_DIR) knownHostDockerSockets.push(join(env.XDG_RUNTIME_DIR, "docker.sock"));
+  for (const [index, mount] of config.mounts.entries()) {
+    if (mount.type === "named" || mount.type === "tmpfs" || typeof mount.hostPath !== "string") continue;
+    const host = resolve(mount.hostPath);
+    let unsafe = basename(host) === "docker.sock" || knownHostDockerSockets.some((socket) => isInside(socket, host));
+    if (!unsafe) {
+      try { unsafe = (await mountStat(host)).isSocket(); }
+      catch { policyIssues.push(issueForPath(`mounts[${index}].hostPath`, "could not be safely inspected")); continue; }
+    }
+    if (unsafe) policyIssues.push(issueForPath(`mounts[${index}].hostPath`, "must not mount a host socket or Docker socket path"));
+  }
   const projectSecretFiles = new Map<string, { reference: string; canonical: string }>();
   if (Array.isArray(projectMounts)) for (const mount of projectMounts as any[]) {
     if (!mount || typeof mount.hostPath !== "string" || mount.type === "named" || mount.type === "tmpfs") continue;

package/extensions/pi-msb/control.ts

@@ -37,6 +37,7 @@ import {
   type PersistedSandboxState,
   type ResolvedConfig,
   type RuntimeExecution,
+  type RuntimePreparation,
   type RuntimeState,
   type StoragePlan,
   type ToolOperations,
@@ -267,7 +268,7 @@ function parsePort(value: string): { bind: string; host: number; guest: number }
   const numbers = parts.slice(-2).map((item) => Number(item));
   if (parts.length === 1) return { bind: "127.0.0.1", host: numbers[0], guest: numbers[0] };
   if (parts.length === 2) return { bind: "127.0.0.1", host: numbers[0], guest: numbers[1] };
-  return { bind: parts[0], host: numbers[1], guest: numbers[2] };
+  return { bind: parts[0], host: numbers[0], guest: numbers[1] };
 }
 
 function applyMount(builder: AnyRecord, mount: Config["mounts"][number]): void {
@@ -306,7 +307,7 @@ function applyNetwork(builder: AnyRecord, config: Config, sdk: MicrosandboxModul
           return destination.domain(host);
         }));
       }
-      if (network.allowDns) policy.egress((rule: AnyRecord) => rule.allowDns());
+      if (network.allowDns) policy.egress((rule: AnyRecord) => rule.udp().tcp().port(53).allowHost());
       builder.network((n: AnyRecord) => n.policy(policy));
     }
   }
@@ -347,7 +348,7 @@ function sanitizeOverride(key: string, value: unknown): unknown {
 }
 
 export function createMsbIntegration(options: MsbControlOptions): MsbIntegration {
-  const configRef = { value: { ...DEFAULT_CONFIG, network: { ...DEFAULT_CONFIG.network } } as Config };
+  const configRef = { value: { ...DEFAULT_CONFIG, network: { ...DEFAULT_CONFIG.network }, docker: { ...DEFAULT_CONFIG.docker } } as Config };
   let sessionId = options.sessionId;
   let cwd = options.cwd;
   let repoRoot: string | null = null;
@@ -531,21 +532,100 @@ export function createMsbIntegration(options: MsbControlOptions): MsbIntegration
         bash: createBashOps({ withRuntime: async (callback) => callback({ transport, operations: undefined as never }) }),
       } as ToolOperations;
     },
-    probeAndBootstrap: async (runtime, config) => {
-      const missing = async () => {
-        const result = await Promise.all(REQUIRED_GUEST_COMMANDS.map(async (command) => ({ command, result: await runtime.transport.exec("sh", ["-lc", `command -v ${command}`]) })));
+    prepareRuntime: async (runtime, config): Promise<RuntimePreparation> => {
+      const commandsMissing = async (commandNames: readonly string[]) => {
+        const result = await Promise.all(commandNames.map(async (command) => ({
+          command,
+          result: await runtime.transport.exec("sh", ["-c", 'command -v "$1" >/dev/null 2>&1', "pi-msb-probe", command]),
+        })));
         return result.filter((item) => item.result.exitCode !== 0).map((item) => item.command);
       };
-      let commands = await missing();
+      let commands = await commandsMissing(REQUIRED_GUEST_COMMANDS);
       if (commands.length && config.bootstrapTools !== false) {
-        const apt = await runtime.transport.exec("sh", ["-lc", "command -v apt-get"]);
+        const apt = await runtime.transport.exec("sh", ["-c", 'command -v "$1" >/dev/null 2>&1', "pi-msb-probe", "apt-get"]);
         if (apt.exitCode === 0) {
           await runtime.transport.exec("apt-get", ["update", "-y"]);
           await runtime.transport.exec("apt-get", ["install", "-y", "--no-install-recommends", "bash", "git", "ripgrep", "file", "coreutils", "ca-certificates"]);
-          commands = await missing();
+          commands = await commandsMissing(REQUIRED_GUEST_COMMANDS);
         }
       }
       if (commands.length) throw new Error(`sandbox is missing required commands: ${commands.join(", ")}; install them or use bootstrapTools=true`);
+
+      const mode = config.docker.mode;
+      if (mode === "disabled") return { docker: { mode, readiness: "disabled" } };
+
+      const dockerComponents = [
+        { name: "docker", path: "/usr/local/bin/docker" },
+        { name: "dockerd", path: "/usr/local/bin/dockerd" },
+        { name: "pi-msb-docker-start", path: "/usr/local/sbin/pi-msb-docker-start" },
+      ] as const;
+      const dockerChecks = await Promise.all(dockerComponents.map(async (component) => ({
+        ...component,
+        result: await runtime.transport.exec("/usr/bin/test", ["-x", component.path]),
+      })));
+      const missingDocker = dockerChecks.filter((item) => item.result.exitCode !== 0).map((item) => item.name);
+      if (missingDocker.length) {
+        const reason = `image is missing Docker components: ${missingDocker.join(", ")}`;
+        if (mode === "require") throw new Error(reason);
+        return { docker: { mode, readiness: "missing", reason } };
+      }
+
+      let started = false;
+      try {
+        const result = await runtime.transport.exec(
+          "/usr/bin/env",
+          [
+            "-i",
+            "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+            "HOME=/root",
+            "/usr/local/sbin/pi-msb-docker-start",
+            String(config.docker.startupTimeoutMs),
+          ],
+          { timeoutMs: config.docker.startupTimeoutMs + 2_000 },
+        );
+        started = result.exitCode === 0;
+      } catch {
+        // Keep host-visible status bounded so transport errors cannot expose
+        // environment or secret values.
+      }
+      if (!started) {
+        const reason = "Docker daemon did not become ready; inspect /var/log/pi-msb-dockerd.log inside the sandbox";
+        if (mode === "require") throw new Error(reason);
+        return { docker: { mode, readiness: "unavailable", reason } };
+      }
+
+      const inspectLocalDocker = (args: string[]) => runtime.transport.exec(
+        "/usr/bin/env",
+        [
+          "-i",
+          "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+          "HOME=/root",
+          "/usr/local/bin/docker",
+          "--host=unix:///var/run/docker.sock",
+          ...args,
+        ],
+        { timeoutMs: 5_000 },
+      );
+      let version: string | undefined;
+      let storageDriver: string | undefined;
+      try {
+        const [versionResult, driverResult] = await Promise.all([
+          inspectLocalDocker(["version", "--format", "{{.Server.Version}}"]),
+          inspectLocalDocker(["info", "--format", "{{.Driver}}"]),
+        ]);
+        if (versionResult.exitCode === 0 && driverResult.exitCode === 0) {
+          version = versionResult.stdout.toString("utf8").trim().split(/\r?\n/, 1)[0]?.slice(0, 128);
+          storageDriver = driverResult.stdout.toString("utf8").trim().split(/\r?\n/, 1)[0]?.slice(0, 128);
+        }
+      } catch {
+        // Report a bounded capability error below.
+      }
+      if (!version || !storageDriver) {
+        const reason = "Docker daemon became reachable but capability inspection failed";
+        if (mode === "require") throw new Error(reason);
+        return { docker: { mode, readiness: "unavailable", reason } };
+      }
+      return { docker: { mode, readiness: "ready", version, storageDriver } };
     },
     seed: async (runtime, prepared) => seedGitVolume(runtime.transport, prepared.plan as any, prepared.bundle ?? null),
     persist: (state) => options.appendEntry?.(STATE_ENTRY, encodeSessionState(state)),
@@ -564,6 +644,7 @@ export function createMsbIntegration(options: MsbControlOptions): MsbIntegration
     withRuntime: (callback) => manager.withRuntime(callback),
   };
   const effective = (): ResolvedConfig => resolved;
+  const configSnapshot = (): Config => structuredClone(configRef.value);
   const overrideEntries = (entries: readonly unknown[]): DeepPartial<Config> => {
     let result: DeepPartial<Config> = {};
     for (const entry of entries) {
@@ -608,7 +689,7 @@ export function createMsbIntegration(options: MsbControlOptions): MsbIntegration
     }
     resolved = next;
     configReady = true;
-    Object.assign(configRef.value, next.config, { network: { ...next.config.network }, secrets: [...next.config.secrets], mounts: [...next.config.mounts] });
+    Object.assign(configRef.value, next.config, { network: { ...next.config.network }, docker: { ...next.config.docker }, secrets: [...next.config.secrets], mounts: [...next.config.mounts] });
     const state = setup.restored ?? persistenceState(options.entries?.() ?? [], sessionId);
     explicitOff = isDisabledByEnv(options.env ?? process.env);
     failureState = explicitOff ? { status: "off", info: null } : null;
@@ -616,7 +697,7 @@ export function createMsbIntegration(options: MsbControlOptions): MsbIntegration
       if (!explicitOff) { await manager.setEnabled(false); failureState = { status: "off", info: null }; }
       return visibleState();
     }
-    const result = await manager.boot({ sessionId, cwd, config: configRef.value, restored: state });
+    const result = await manager.boot({ sessionId, cwd, config: configSnapshot(), restored: state });
     if (result.status === "unavailable") failureState = result;
     notifyState(visibleState());
     return visibleState();
@@ -644,7 +725,7 @@ export function createMsbIntegration(options: MsbControlOptions): MsbIntegration
         await manager.setEnabled(false);
         failureState = { status: "off", info: null };
       } else {
-        const result = await manager.boot({ sessionId, cwd, config: configRef.value, restored: persistenceState(options.entries?.() ?? [], sessionId) });
+        const result = await manager.boot({ sessionId, cwd, config: configSnapshot(), restored: persistenceState(options.entries?.() ?? [], sessionId) });
         if (result.status === "unavailable") failureState = result;
       }
       notifyState(visibleState());
@@ -667,10 +748,10 @@ export function createMsbIntegration(options: MsbControlOptions): MsbIntegration
       }
       resolved = next;
       configReady = true;
-      Object.assign(configRef.value, next.config, { network: { ...next.config.network }, secrets: [...next.config.secrets], mounts: [...next.config.mounts] });
+      Object.assign(configRef.value, next.config, { network: { ...next.config.network }, docker: { ...next.config.docker }, secrets: [...next.config.secrets], mounts: [...next.config.mounts] });
       failureState = null;
       if (!explicitOff && configRef.value.autoStart) {
-        const result = await manager.boot({ sessionId, cwd, config: configRef.value, restored: persistenceState(options.entries?.() ?? [], sessionId) });
+        const result = await manager.boot({ sessionId, cwd, config: configSnapshot(), restored: persistenceState(options.entries?.() ?? [], sessionId) });
         if (result.status === "unavailable") failureState = result;
       }
       notifyState(visibleState());

package/extensions/pi-msb/flock.ts

@@ -0,0 +1,94 @@
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+export type FlockOperation = "exnb" | "un";
+export type FlockTarget = "darwin-arm64" | "linux-x64-gnu" | "linux-arm64-gnu";
+
+export interface FlockRuntime {
+  platform: string;
+  arch: string;
+  glibcVersionRuntime?: unknown;
+}
+
+interface NativeFlockBinding {
+  flock(fd: number, operation: FlockOperation): undefined;
+}
+
+export interface LoadFlockOptions {
+  runtime?: FlockRuntime;
+  requireAddon?: (absolutePath: string) => unknown;
+}
+
+const SUPPORTED_TARGETS = "darwin-arm64, linux-x64-gnu, linux-arm64-gnu";
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function currentRuntime(): FlockRuntime {
+  const report = process.platform === "linux"
+    ? process.report?.getReport() as { header?: { glibcVersionRuntime?: unknown } } | undefined
+    : undefined;
+  return {
+    platform: process.platform,
+    arch: process.arch,
+    glibcVersionRuntime: report?.header?.glibcVersionRuntime,
+  };
+}
+
+export function flockTarget(runtime: FlockRuntime): FlockTarget {
+  if (runtime.platform === "darwin" && runtime.arch === "arm64") return "darwin-arm64";
+  if (runtime.platform === "linux" && (runtime.arch === "x64" || runtime.arch === "arm64")) {
+    if (typeof runtime.glibcVersionRuntime !== "string" || runtime.glibcVersionRuntime.length === 0) {
+      throw new Error(
+        `Bundled owner-lock addon requires glibc on Linux; libc is musl or indeterminate for linux-${runtime.arch}; `
+        + `supported targets: ${SUPPORTED_TARGETS}; refusing to use an unsafe fallback`,
+      );
+    }
+    return `linux-${runtime.arch}-gnu`;
+  }
+  throw new Error(
+    `Bundled owner-lock addon does not support ${runtime.platform}-${runtime.arch}; `
+    + `supported targets: ${SUPPORTED_TARGETS}; refusing to use an unsafe fallback`,
+  );
+}
+
+export function flockBinaryPath(target: FlockTarget): string {
+  return fileURLToPath(new URL(`../../native/flock/prebuilds/${target}/flock.node`, import.meta.url));
+}
+
+export function loadFlockBinding(options: LoadFlockOptions = {}): NativeFlockBinding {
+  const target = flockTarget(options.runtime ?? currentRuntime());
+  const relativePath = `native/flock/prebuilds/${target}/flock.node`;
+  const absolutePath = flockBinaryPath(target);
+  const requireAddon = options.requireAddon ?? ((path: string) => createRequire(import.meta.url)(path));
+
+  try {
+    const candidate = requireAddon(absolutePath);
+    if (typeof candidate !== "object" || candidate === null
+      || Object.keys(candidate).length !== 1
+      || typeof (candidate as { flock?: unknown }).flock !== "function") {
+      throw new TypeError("native binding must export only flock() as a callable property");
+    }
+    return candidate as NativeFlockBinding;
+  } catch (error) {
+    throw new Error(
+      `Unable to load bundled owner-lock addon for ${target} from ${relativePath}; `
+      + `refusing to use an unsafe fallback: ${errorMessage(error)}`,
+      { cause: error },
+    );
+  }
+}
+
+let binding: NativeFlockBinding | undefined;
+
+export async function flock(fd: number, operation: FlockOperation): Promise<void> {
+  if (!Number.isInteger(fd) || fd < 0 || fd > 0x7fff_ffff) {
+    throw new TypeError("file descriptor must be a non-negative integer");
+  }
+  if (operation !== "exnb" && operation !== "un") {
+    throw new TypeError('operation must be "exnb" or "un"');
+  }
+  binding ??= loadFlockBinding();
+  binding.flock(fd, operation);
+}

package/extensions/pi-msb/locks.ts

@@ -1,13 +1,14 @@
 import { chmod, mkdir, open, readFile } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
 
+import { flock as bundledFlock } from "./flock.ts";
 import { LOCKFILE_VERSION, resourceId } from "./types.ts";
 import type { LockHandle, LockInfo, LocksPort } from "./types.ts";
 
 /**
  * The hooks are deliberately part of the options shape so unit tests can exercise
  * the lifecycle without loading the native addon. Production callers leave them
- * unset and use fs-ext below.
+ * unset and use the lazy bundled binding.
  */
 export type FlockFn = (fd: number, operation: "exnb" | "un") => Promise<void>;
 
@@ -18,25 +19,6 @@ export interface LocksOptions {
   unlock?: (fd: number) => Promise<void>;
 }
 
-type FsExtCallback = (
-  fd: number,
-  operation: string,
-  callback: (error?: unknown) => void,
-) => void;
-type FsExtUnlockCallback = (fd: number, callback: (error?: unknown) => void) => void;
-type FsExtModule = {
-  flock?: FsExtCallback;
-  unlock?: FsExtUnlockCallback;
-};
-
-let fsExtPromise: Promise<FsExtModule> | undefined;
-
-// Keep the native dependency genuinely lazy and let extension-load/type-only
-// environments operate without resolving the optional native module.
-function importNativeModule(specifier: string): Promise<unknown> {
-  return import(specifier);
-}
-
 function errorCode(error: unknown): string | undefined {
   if (typeof error === "object" && error !== null && "code" in error) {
     const code = (error as { code?: unknown }).code;
@@ -49,77 +31,16 @@ function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
-function unsupportedPlatformError(): Error {
-  return new Error(
-    "pi-microsandbox owner locks require POSIX flock(2) via fs-ext; this platform is unsupported (Windows LockFileEx is not implemented)",
-  );
-}
-
-async function loadFsExt(): Promise<FsExtModule> {
-  if (process.platform === "win32") throw unsupportedPlatformError();
-  fsExtPromise ??= importNativeModule("fs-ext").then((module) => {
-    const defaultExport = (module as unknown as { default?: unknown }).default;
-    const candidate = (defaultExport ?? module) as FsExtModule;
-    if (typeof candidate.flock !== "function") {
-      throw new Error("fs-ext loaded without flock(); refusing to use a racy PID fallback");
-    }
-    return candidate;
-  });
-  return fsExtPromise;
-}
-
-function callbackFlock(flock: FsExtCallback, fd: number, operation: string): Promise<void> {
-  return new Promise((resolve, reject) => {
-    try {
-      flock(fd, operation, (error) => (error ? reject(error) : resolve()));
-    } catch (error) {
-      reject(error);
-    }
-  });
-}
-
-function callbackUnlock(unlock: FsExtUnlockCallback, fd: number): Promise<void> {
-  return new Promise((resolve, reject) => {
-    try {
-      unlock(fd, (error) => (error ? reject(error) : resolve()));
-    } catch (error) {
-      reject(error);
-    }
-  });
-}
-
 interface LockOperations {
   flock(fd: number): Promise<void>;
   unlock(fd: number): Promise<void>;
 }
 
 async function lockOperations(opts: LocksOptions): Promise<LockOperations> {
-  if (opts.flock) {
-    return {
-      flock: (fd) => opts.flock!(fd, "exnb"),
-      unlock: (fd) => opts.unlock ? opts.unlock(fd) : opts.flock!(fd, "un"),
-    };
-  }
-
-  let module: FsExtModule;
-  try {
-    module = await loadFsExt();
-  } catch (error) {
-    throw new Error(
-      `Unable to load fs-ext for owner locks; refusing to use a racy PID fallback: ${errorMessage(error)}`,
-      { cause: error },
-    );
-  }
-  const flock = module.flock;
-  if (!flock) {
-    throw new Error("fs-ext does not provide flock(); refusing to use a racy PID fallback");
-  }
-  const unlock = module.unlock;
+  const flock = opts.flock ?? bundledFlock;
   return {
-    flock: (fd) => callbackFlock(flock, fd, "exnb"),
-    unlock: (fd) => unlock
-      ? callbackUnlock(unlock, fd)
-      : callbackFlock(flock, fd, "un"),
+    flock: (fd) => flock(fd, "exnb"),
+    unlock: (fd) => opts.unlock ? opts.unlock(fd) : flock(fd, "un"),
   };
 }