@bitkyc08/opencodex 2.52.0-preview.20260912 → 2.53.0-preview.20260913

package/src/remote-control/workspace-command-runner.ts

@@ -0,0 +1,748 @@
+import { createHash } from "node:crypto";
+import {
+  accessSync,
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  lstatSync,
+  opendirSync,
+  openSync,
+  readSync,
+  realpathSync,
+  statSync,
+} from "node:fs";
+import { arch } from "node:os";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import type {
+  RemoteWorkspaceCommandRequest,
+  RemoteWorkspaceCommandResult,
+  RemoteWorkspaceCommandRunner,
+} from "./workspace-executor";
+
+const DEFAULT_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+const NATIVE_HELPER_PROTOCOL_VERSION = 1;
+const MAX_NATIVE_HELPER_BYTES = 64 * 1024 * 1024;
+const MAX_NATIVE_HELPER_ERROR_CHARS = 512;
+const MAX_NATIVE_HELPER_STDERR_BYTES = 16 * 1024;
+const MAX_WORKSPACE_PREFLIGHT_ENTRIES = 250_000;
+const SANDBOX_BUN_PATH = "/ocx-runtime/bin/bun";
+const READABLE_SYSTEM_PATHS = [
+  "/usr",
+  "/bin",
+  "/sbin",
+  "/lib",
+  "/lib64",
+] as const;
+const READABLE_ETC_PATHS = [
+  "/etc/alternatives",
+  "/etc/ca-certificates",
+  "/etc/ssl",
+  "/etc/hosts",
+  "/etc/nsswitch.conf",
+  "/etc/passwd",
+  "/etc/group",
+  "/etc/localtime",
+  "/etc/resolv.conf",
+] as const;
+
+export interface LinuxRemoteWorkspaceCommandRunnerOptions {
+  bubblewrapPath?: string;
+  networkAccess?: boolean;
+  /** Additional read-only toolchain trees explicitly approved by the device owner. */
+  toolchainRoots?: readonly string[];
+  /** Exact Bun executable used by OCX; mounted as one file rather than exposing its host directory. */
+  runtimeExecutablePath?: string;
+  /** Writable roots inspected before command capability is advertised. */
+  writableRoots?: readonly string[];
+  spawn?: typeof Bun.spawn;
+  /** Cross-platform test seam for the real namespace capability probe. */
+  probe?: (argv: readonly string[]) => boolean;
+}
+
+export interface RemoteWorkspaceNativeHelperDescriptor {
+  path: string;
+  sha256: string;
+}
+
+interface NativeHelperRequest {
+  version: typeof NATIVE_HELPER_PROTOCOL_VERSION;
+  operation: "probe" | "run";
+  root?: string;
+  cwd?: string;
+  command?: string[];
+  toolchainRoots?: string[];
+  timeoutMs?: number;
+  maxOutputBytes?: number;
+  networkAccess?: boolean;
+}
+
+interface NativeHelperProbeResponse {
+  version: typeof NATIVE_HELPER_PROTOCOL_VERSION;
+  ok: true;
+  probe: true;
+}
+
+export interface NativeRemoteWorkspaceCommandRunnerOptions {
+  helper: RemoteWorkspaceNativeHelperDescriptor;
+  toolchainRoots?: readonly string[];
+  /** Writable workspace roots that must never contain the executable enforcing their sandbox. */
+  writableRoots: readonly string[];
+  networkAccess?: boolean;
+  platform?: NodeJS.Platform;
+  spawn?: typeof Bun.spawn;
+  spawnSync?: typeof Bun.spawnSync;
+  /** Pure test seam. Production always executes the digest-pinned helper's real probe. */
+  probe?: (request: NativeHelperRequest) => unknown;
+}
+
+const availabilityCache = new Map<string, boolean>();
+
+function exactObject(value: unknown, keys: readonly string[]): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("remote workspace native helper returned an invalid response");
+  }
+  const record = value as Record<string, unknown>;
+  const allowed = new Set(keys);
+  if (Object.keys(record).some(key => !allowed.has(key))) {
+    throw new Error("remote workspace native helper returned an invalid response");
+  }
+  return record;
+}
+
+function parseNativeHelperProbeResponse(value: unknown): NativeHelperProbeResponse {
+  const raw = exactObject(value, ["version", "ok", "probe"]);
+  if (raw.version !== NATIVE_HELPER_PROTOCOL_VERSION || raw.ok !== true || raw.probe !== true) {
+    throw new Error("remote workspace native helper failed its confinement probe");
+  }
+  return { version: NATIVE_HELPER_PROTOCOL_VERSION, ok: true, probe: true };
+}
+
+function boundedBase64(value: unknown, label: string, maximum: number): Buffer {
+  if (typeof value !== "string" || value.length > Math.ceil(maximum / 3) * 4 + 4
+    || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+    throw new Error(`remote workspace native helper returned invalid ${label}`);
+  }
+  const decoded = Buffer.from(value, "base64");
+  if (decoded.byteLength > maximum || decoded.toString("base64") !== value) {
+    throw new Error(`remote workspace native helper returned invalid ${label}`);
+  }
+  return decoded;
+}
+
+function parseNativeHelperCommandResponse(value: unknown, maximum: number): RemoteWorkspaceCommandResult {
+  const raw = exactObject(value, ["version", "ok", "exitCode", "stdoutBase64", "stderrBase64"]);
+  if (raw.version !== NATIVE_HELPER_PROTOCOL_VERSION || raw.ok !== true
+    || typeof raw.exitCode !== "number" || !Number.isSafeInteger(raw.exitCode)
+    || raw.exitCode < -2_147_483_648 || raw.exitCode > 4_294_967_295) {
+    throw new Error("remote workspace native helper returned an invalid command result");
+  }
+  const stdout = boundedBase64(raw.stdoutBase64, "stdout", maximum);
+  const stderr = boundedBase64(raw.stderrBase64, "stderr", maximum);
+  if (stdout.byteLength + stderr.byteLength > maximum) {
+    throw new Error("remote workspace native helper exceeded its output contract");
+  }
+  const decoder = new TextDecoder("utf-8", { fatal: false });
+  return {
+    exitCode: raw.exitCode,
+    stdout: decoder.decode(stdout),
+    stderr: decoder.decode(stderr),
+  };
+}
+
+function parseNativeHelperJson(value: Uint8Array): unknown {
+  try {
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(value));
+  } catch {
+    throw new Error("remote workspace native helper returned malformed JSON");
+  }
+}
+
+function sha256File(path: string): string {
+  const descriptor = openSync(path, constants.O_RDONLY);
+  try {
+    const metadata = fstatSync(descriptor);
+    if (!metadata.isFile() || metadata.size < 1 || metadata.size > MAX_NATIVE_HELPER_BYTES) {
+      throw new Error("remote workspace native helper has an invalid size");
+    }
+    const hash = createHash("sha256");
+    const chunk = Buffer.allocUnsafe(64 * 1024);
+    let offset = 0;
+    while (offset < metadata.size) {
+      const count = readSync(descriptor, chunk, 0, Math.min(chunk.byteLength, metadata.size - offset), offset);
+      if (count === 0) throw new Error("remote workspace native helper changed while hashing");
+      hash.update(chunk.subarray(0, count));
+      offset += count;
+    }
+    const after = fstatSync(descriptor);
+    if (after.size !== metadata.size || after.mtimeMs !== metadata.mtimeMs
+      || after.dev !== metadata.dev || after.ino !== metadata.ino) {
+      throw new Error("remote workspace native helper changed while hashing");
+    }
+    return hash.digest("hex");
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+export function pinRemoteWorkspaceNativeHelper(path: string): RemoteWorkspaceNativeHelperDescriptor {
+  if (!isAbsolute(path) || path.includes("\0")) {
+    throw new Error("remote workspace native helper must be an absolute path");
+  }
+  const linked = lstatSync(path);
+  if (!linked.isFile() || linked.isSymbolicLink()) {
+    throw new Error("remote workspace native helper must remain a real file");
+  }
+  const canonical = realpathSync(path);
+  accessSync(canonical, process.platform === "win32" ? constants.F_OK : constants.X_OK);
+  if (process.platform !== "win32" && (statSync(canonical).mode & 0o022) !== 0) {
+    throw new Error("remote workspace native helper must not be group or world writable");
+  }
+  return { path: canonical, sha256: sha256File(canonical) };
+}
+
+export function discoverRemoteWorkspaceNativeHelper(options: {
+  platform?: NodeJS.Platform;
+  architecture?: string;
+} = {}): RemoteWorkspaceNativeHelperDescriptor | undefined {
+  const platform = options.platform ?? process.platform;
+  if (platform !== "darwin" && platform !== "win32") return undefined;
+  const architecture = options.architecture ?? arch();
+  const executable = platform === "win32"
+    ? "opencodex-remote-workspace-helper.exe"
+    : "opencodex-remote-workspace-helper";
+  const candidates = [
+    // Signed release bundles place the helper here.
+    `${import.meta.dir}/../../native-bin/${platform}-${architecture}/${executable}`,
+    // Source/private-dogfood builds produced by `bun run build:remote-workspace-helper`.
+    `${import.meta.dir}/../../native/remote-workspace-helper/target/release/${executable}`,
+  ];
+  for (const candidate of candidates) {
+    if (!existsSync(candidate)) continue;
+    try {
+      return pinRemoteWorkspaceNativeHelper(candidate);
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+export function parseRemoteWorkspaceNativeHelperDescriptor(value: unknown): RemoteWorkspaceNativeHelperDescriptor {
+  const raw = exactObject(value, ["path", "sha256"]);
+  if (typeof raw.path !== "string" || !isAbsolute(raw.path) || raw.path.includes("\0") || raw.path.length > 4096
+    || typeof raw.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(raw.sha256)) {
+    throw new Error("invalid remote workspace native helper descriptor");
+  }
+  return { path: raw.path, sha256: raw.sha256 };
+}
+
+function assertNativeHelperIntegrity(value: RemoteWorkspaceNativeHelperDescriptor): RemoteWorkspaceNativeHelperDescriptor {
+  const helper = parseRemoteWorkspaceNativeHelperDescriptor(value);
+  const linked = lstatSync(helper.path);
+  if (!linked.isFile() || linked.isSymbolicLink() || realpathSync(helper.path) !== helper.path) {
+    throw new Error("remote workspace native helper identity changed; pair it again");
+  }
+  accessSync(helper.path, process.platform === "win32" ? constants.F_OK : constants.X_OK);
+  if (process.platform !== "win32" && (linked.mode & 0o022) !== 0) {
+    throw new Error("remote workspace native helper permissions are unsafe");
+  }
+  if (sha256File(helper.path) !== helper.sha256) {
+    throw new Error("remote workspace native helper digest changed; pair it again");
+  }
+  return helper;
+}
+
+function assertNativeHelperOutsideWritableRoots(
+  helper: RemoteWorkspaceNativeHelperDescriptor,
+  roots: readonly string[],
+): string[] {
+  if (roots.length < 1 || roots.length > 32) {
+    throw new Error("remote workspace native runner needs one to 32 writable roots");
+  }
+  const canonicalRoots: string[] = [];
+  for (const root of roots) {
+    if (!isAbsolute(root) || root.includes("\0")) {
+      throw new Error("remote workspace writable root must be an absolute path");
+    }
+    const canonicalRoot = realpathSync(root);
+    if (canonicalRoots.includes(canonicalRoot)) {
+      throw new Error("remote workspace native runner received a duplicate writable root");
+    }
+    if (inside(canonicalRoot, helper.path)) {
+      // A sandboxed command can write anywhere below its approved root. Executing the sandbox
+      // helper from that same tree would turn the hash-then-spawn pathname into a writable trust
+      // anchor that a workspace command can replace before a later invocation.
+      throw new Error("remote workspace native helper must be outside every writable workspace root");
+    }
+    canonicalRoots.push(canonicalRoot);
+  }
+  return canonicalRoots;
+}
+
+function nativeHelperEnvironment(platform: NodeJS.Platform): Record<string, string> {
+  const result: Record<string, string> = {};
+  const names = platform === "win32"
+    ? ["SystemRoot", "WINDIR", "TEMP", "TMP"]
+    : ["TMPDIR"];
+  for (const name of names) {
+    const value = process.env[name];
+    if (value) result[name] = value;
+  }
+  return result;
+}
+
+function inside(root: string, candidate: string): boolean {
+  const rel = relative(root, candidate);
+  return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+
+function assertWorkspaceHasNoExternalHardlinkAliases(root: string): void {
+  const canonicalRoot = realpathSync(root);
+  const pending = [canonicalRoot];
+  let entries = 0;
+  while (pending.length > 0) {
+    const current = pending.pop()!;
+    const directory = opendirSync(current);
+    try {
+      for (;;) {
+        const entry = directory.readSync();
+        if (!entry) break;
+        entries += 1;
+        if (entries > MAX_WORKSPACE_PREFLIGHT_ENTRIES) {
+          throw new Error("remote workspace is too large for safe command preflight");
+        }
+        const target = join(current, entry.name);
+        const metadata = lstatSync(target);
+        if (metadata.isDirectory() && !metadata.isSymbolicLink()) {
+          pending.push(target);
+        } else if (!metadata.isDirectory() && metadata.nlink > 1) {
+          // A bind mount or Seatbelt path rule cannot distinguish two names for one inode. Reject
+          // rather than let a workspace alias read or mutate a file whose other name is outside.
+          throw new Error("remote workspace command root contains a hard-linked file");
+        }
+      }
+    } finally {
+      directory.closeSync();
+    }
+  }
+}
+
+function assertCommandRootsSafe(roots: readonly string[]): void {
+  for (const root of roots) assertWorkspaceHasNoExternalHardlinkAliases(root);
+}
+
+function sandboxPath(root: string, cwd: string): string {
+  if (!inside(root, cwd)) throw new Error("remote workspace command cwd escaped its root");
+  const rel = relative(root, cwd);
+  return rel ? `/workspace/${rel.split(sep).join("/")}` : "/workspace";
+}
+
+function bindArgs(flag: "--ro-bind" | "--ro-bind-try", paths: readonly string[]): string[] {
+  const result: string[] = [];
+  for (const path of paths) {
+    if (flag === "--ro-bind-try" || existsSync(path)) result.push(flag, path, path);
+  }
+  return result;
+}
+
+function approvedToolchainRoots(values: readonly string[]): string[] {
+  const result: string[] = [];
+  for (const value of values) {
+    if (!isAbsolute(value) || !existsSync(value) || value.includes("\0")) {
+      throw new Error("remote workspace toolchain root must be an existing absolute path");
+    }
+    const metadata = lstatSync(value);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+      throw new Error("remote workspace toolchain root must remain a real directory");
+    }
+    result.push(realpathSync(value));
+  }
+  return [...new Set(result)];
+}
+
+function approvedRuntimeExecutable(value: string | undefined): string | null {
+  if (value === undefined) return null;
+  if (!isAbsolute(value) || value.includes("\0")) {
+    throw new Error("remote workspace runtime executable must be an absolute path");
+  }
+  const canonical = realpathSync(value);
+  if (!statSync(canonical).isFile()) throw new Error("remote workspace runtime executable must be a file");
+  accessSync(canonical, constants.X_OK);
+  return canonical;
+}
+
+function trustedBubblewrap(path: string, roots: readonly string[]): string {
+  if (!isAbsolute(path)) throw new Error("bubblewrap must be an absolute executable path");
+  const canonical = realpathSync(path);
+  const file = lstatSync(canonical);
+  if (!file.isFile() || file.nlink !== 1) throw new Error("bubblewrap must be a private executable file");
+  for (const root of roots) {
+    if (inside(realpathSync(root), canonical)) {
+      throw new Error("bubblewrap must be outside every writable workspace root");
+    }
+  }
+  accessSync(canonical, constants.X_OK);
+  let current = canonical;
+  for (;;) {
+    const metadata = lstatSync(current);
+    if (process.platform !== "win32" && (metadata.mode & 0o022) !== 0) {
+      throw new Error("bubblewrap executable and parent directories must not be group or world writable");
+    }
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return canonical;
+}
+
+export function linuxRemoteWorkspaceCommandArgv(
+  request: RemoteWorkspaceCommandRequest,
+  options: LinuxRemoteWorkspaceCommandRunnerOptions = {},
+): string[] {
+  const bubblewrap = trustedBubblewrap(options.bubblewrapPath ?? "/usr/bin/bwrap", [...(options.writableRoots ?? []), request.root]);
+  const toolchains = approvedToolchainRoots(options.toolchainRoots ?? []);
+  const runtimeExecutable = approvedRuntimeExecutable(options.runtimeExecutablePath);
+  const commandPath = [...(runtimeExecutable ? ["/ocx-runtime/bin"] : []), ...toolchains, DEFAULT_PATH].join(":");
+  return [
+    bubblewrap,
+    "--die-with-parent",
+    "--new-session",
+    "--unshare-pid",
+    "--unshare-ipc",
+    "--unshare-uts",
+    ...(options.networkAccess === true ? [] : ["--unshare-net"]),
+    "--proc", "/proc",
+    "--dev", "/dev",
+    "--tmpfs", "/tmp",
+    ...(runtimeExecutable ? [
+      "--dir", "/ocx-runtime",
+      "--dir", "/ocx-runtime/bin",
+      "--ro-bind", runtimeExecutable, SANDBOX_BUN_PATH,
+    ] : []),
+    ...bindArgs("--ro-bind", READABLE_SYSTEM_PATHS),
+    ...bindArgs("--ro-bind-try", READABLE_ETC_PATHS),
+    ...toolchains.flatMap(path => ["--ro-bind", path, path]),
+    "--bind", request.root, "/workspace",
+    "--chdir", sandboxPath(request.root, request.cwd),
+    "--clearenv",
+    "--setenv", "HOME", "/workspace",
+    "--setenv", "PATH", commandPath,
+    "--setenv", "LANG", "C.UTF-8",
+    "--setenv", "LC_ALL", "C.UTF-8",
+    "--",
+    ...request.command,
+  ];
+}
+
+async function collectBoundedOutput(
+  stream: ReadableStream<Uint8Array>,
+  reserve: (bytes: number) => boolean,
+  onOverflow: () => void,
+): Promise<string> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    while (true) {
+      const next = await reader.read();
+      if (next.done) break;
+      if (!reserve(next.value.byteLength)) {
+        onOverflow();
+        throw new Error("remote workspace command output limit exceeded");
+      }
+      chunks.push(next.value);
+      total += next.value.byteLength;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const body = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder("utf-8", { fatal: false }).decode(body);
+}
+
+export function createLinuxRemoteWorkspaceCommandRunner(
+  options: LinuxRemoteWorkspaceCommandRunnerOptions = {},
+): RemoteWorkspaceCommandRunner {
+  const spawn = options.spawn ?? Bun.spawn;
+  return {
+    async run(request): Promise<RemoteWorkspaceCommandResult> {
+      assertWorkspaceHasNoExternalHardlinkAliases(request.root);
+      const argv = linuxRemoteWorkspaceCommandArgv(request, options);
+      const child = spawn(argv, {
+        cwd: request.root,
+        env: { PATH: DEFAULT_PATH, LANG: "C.UTF-8", LC_ALL: "C.UTF-8" },
+        stdin: "ignore",
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+      let retained = 0;
+      let timedOut = false;
+      let overflowed = false;
+      let cancelled = false;
+      const stop = () => {
+        try { child.kill(); } catch { /* process already exited */ }
+      };
+      const cancel = () => {
+        cancelled = true;
+        stop();
+      };
+      request.signal?.addEventListener("abort", cancel, { once: true });
+      if (request.signal?.aborted) cancel();
+      const reserve = (bytes: number): boolean => {
+        if (retained + bytes > request.maxOutputBytes) {
+          overflowed = true;
+          return false;
+        }
+        retained += bytes;
+        return true;
+      };
+      const timer = setTimeout(() => {
+        timedOut = true;
+        stop();
+      }, request.timeoutMs);
+      try {
+        const [stdoutResult, stderrResult, exitCode] = await Promise.allSettled([
+          collectBoundedOutput(child.stdout, reserve, stop),
+          collectBoundedOutput(child.stderr, reserve, stop),
+          child.exited,
+        ]);
+        if (cancelled) throw new Error("remote workspace command was cancelled");
+        if (timedOut) throw new Error("remote workspace command timed out");
+        if (overflowed) throw new Error("remote workspace command output limit exceeded");
+        if (stdoutResult.status === "rejected") throw stdoutResult.reason;
+        if (stderrResult.status === "rejected") throw stderrResult.reason;
+        if (exitCode.status === "rejected") throw exitCode.reason;
+        return { exitCode: exitCode.value, stdout: stdoutResult.value, stderr: stderrResult.value };
+      } finally {
+        clearTimeout(timer);
+        request.signal?.removeEventListener("abort", cancel);
+      }
+    },
+  };
+}
+
+function nativeHelperFailure(value: unknown): Error {
+  const raw = exactObject(value, ["version", "ok", "error"]);
+  if (raw.version !== NATIVE_HELPER_PROTOCOL_VERSION || raw.ok !== false
+    || typeof raw.error !== "string" || raw.error.length < 1
+    || [...raw.error].length > MAX_NATIVE_HELPER_ERROR_CHARS || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(raw.error)) {
+    return new Error("remote workspace native helper returned an invalid failure");
+  }
+  return new Error(raw.error);
+}
+
+function nativeHelperRequest(options: NativeRemoteWorkspaceCommandRunnerOptions, request: RemoteWorkspaceCommandRequest): NativeHelperRequest {
+  return {
+    version: NATIVE_HELPER_PROTOCOL_VERSION,
+    operation: "run",
+    root: request.root,
+    cwd: request.cwd,
+    command: [...request.command],
+    toolchainRoots: approvedToolchainRoots(options.toolchainRoots ?? []),
+    timeoutMs: request.timeoutMs,
+    maxOutputBytes: request.maxOutputBytes,
+    networkAccess: options.networkAccess === true,
+  };
+}
+
+export function createNativeRemoteWorkspaceCommandRunner(
+  options: NativeRemoteWorkspaceCommandRunnerOptions,
+): RemoteWorkspaceCommandRunner {
+  const platform = options.platform ?? process.platform;
+  if (platform !== "darwin" && platform !== "win32") {
+    throw new Error("remote workspace native command helper is supported only on macOS and Windows");
+  }
+  if (!nativeRemoteWorkspaceCommandRunnerAvailable(options)) {
+    throw new Error("remote workspace native command helper failed its confinement probe");
+  }
+  const spawn = options.spawn ?? Bun.spawn;
+  return {
+    async run(request): Promise<RemoteWorkspaceCommandResult> {
+      const helper = assertNativeHelperIntegrity(options.helper);
+      const writableRoots = assertNativeHelperOutsideWritableRoots(helper, options.writableRoots);
+      const requestRoot = realpathSync(request.root);
+      if (!writableRoots.includes(requestRoot)) {
+        throw new Error("remote workspace command root is outside the native runner grant");
+      }
+      assertWorkspaceHasNoExternalHardlinkAliases(requestRoot);
+      const body = JSON.stringify(nativeHelperRequest(options, request));
+      if (Buffer.byteLength(body, "utf8") > 64 * 1024) {
+        throw new Error("remote workspace native helper request is too large");
+      }
+      const child = spawn([helper.path], {
+        cwd: request.root,
+        env: nativeHelperEnvironment(platform),
+        stdin: "pipe",
+        stdout: "pipe",
+        stderr: "pipe",
+        windowsHide: true,
+      });
+      let retained = 0;
+      let overflowed = false;
+      let cancelled = false;
+      let timedOut = false;
+      const stop = () => {
+        try { child.kill(); } catch { /* helper already exited */ }
+      };
+      const cancel = () => {
+        cancelled = true;
+        stop();
+      };
+      request.signal?.addEventListener("abort", cancel, { once: true });
+      if (request.signal?.aborted) cancel();
+      const maximumResponseBytes = Math.ceil(request.maxOutputBytes / 3) * 4 + 4_096;
+      const reserve = (bytes: number): boolean => {
+        if (retained + bytes > maximumResponseBytes + MAX_NATIVE_HELPER_STDERR_BYTES) {
+          overflowed = true;
+          return false;
+        }
+        retained += bytes;
+        return true;
+      };
+      const timer = setTimeout(() => {
+        timedOut = true;
+        stop();
+      }, request.timeoutMs + 2_000);
+      try {
+        if (!cancelled) {
+          child.stdin.write(body);
+          child.stdin.end();
+        }
+        const [stdoutResult, stderrResult, exitResult] = await Promise.allSettled([
+          collectBoundedOutput(child.stdout, reserve, stop),
+          collectBoundedOutput(child.stderr, reserve, stop),
+          child.exited,
+        ]);
+        if (cancelled) throw new Error("remote workspace command was cancelled");
+        if (timedOut) throw new Error("remote workspace native helper timed out");
+        if (overflowed) throw new Error("remote workspace native helper output limit exceeded");
+        if (stdoutResult.status === "rejected" || stderrResult.status === "rejected" || exitResult.status === "rejected") {
+          throw new Error("remote workspace native helper failed");
+        }
+        if (Buffer.byteLength(stdoutResult.value, "utf8") > maximumResponseBytes
+          || Buffer.byteLength(stderrResult.value, "utf8") > MAX_NATIVE_HELPER_STDERR_BYTES
+          || exitResult.value !== 0) {
+          throw new Error("remote workspace native helper failed");
+        }
+        const response = parseNativeHelperJson(Buffer.from(stdoutResult.value, "utf8"));
+        if (response && typeof response === "object" && !Array.isArray(response)
+          && (response as Record<string, unknown>).ok === false) {
+          throw nativeHelperFailure(response);
+        }
+        return parseNativeHelperCommandResponse(response, request.maxOutputBytes);
+      } finally {
+        clearTimeout(timer);
+        request.signal?.removeEventListener("abort", cancel);
+        try { child.stdin.end(); } catch { /* helper already closed stdin */ }
+      }
+    },
+  };
+}
+
+export function nativeRemoteWorkspaceCommandRunnerAvailable(
+  options: NativeRemoteWorkspaceCommandRunnerOptions,
+): boolean {
+  const platform = options.platform ?? process.platform;
+  if (platform !== "darwin") return false; // Windows awaits a surviving native cleanup owner.
+  try {
+    const helper = assertNativeHelperIntegrity(options.helper);
+    const writableRoots = assertNativeHelperOutsideWritableRoots(helper, options.writableRoots);
+    assertCommandRootsSafe(writableRoots);
+    const request: NativeHelperRequest = { version: NATIVE_HELPER_PROTOCOL_VERSION, operation: "probe" };
+    const raw = options.probe
+      ? options.probe(request)
+      : (() => {
+        const result = (options.spawnSync ?? Bun.spawnSync)([helper.path], {
+          cwd: dirname(helper.path),
+          env: nativeHelperEnvironment(platform),
+          stdin: Buffer.from(JSON.stringify(request), "utf8"),
+          stdout: "pipe",
+          stderr: "ignore",
+          timeout: 8_000,
+          windowsHide: true,
+        });
+        if (!result.success || result.stdout.byteLength > 4_096) {
+          throw new Error("remote workspace native helper probe failed");
+        }
+        return parseNativeHelperJson(result.stdout);
+      })();
+    parseNativeHelperProbeResponse(raw);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function createPlatformRemoteWorkspaceCommandRunner(options: {
+  platform?: NodeJS.Platform;
+  linux?: LinuxRemoteWorkspaceCommandRunnerOptions;
+  native?: Omit<NativeRemoteWorkspaceCommandRunnerOptions, "platform">;
+} = {}): RemoteWorkspaceCommandRunner | undefined {
+  const platform = options.platform ?? process.platform;
+  if (platform === "linux" && linuxRemoteWorkspaceCommandRunnerAvailable(options.linux)) {
+    const linux = {
+      ...options.linux,
+      runtimeExecutablePath: options.linux?.runtimeExecutablePath ?? process.execPath,
+    };
+    return createLinuxRemoteWorkspaceCommandRunner(linux);
+  }
+  if ((platform === "darwin" || platform === "win32") && options.native) {
+    const native = { ...options.native, platform };
+    try {
+      return createNativeRemoteWorkspaceCommandRunner(native);
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+export function linuxRemoteWorkspaceCommandRunnerAvailable(
+  options: LinuxRemoteWorkspaceCommandRunnerOptions = {},
+): boolean {
+  let path: string;
+  try {
+    path = trustedBubblewrap(options.bubblewrapPath ?? "/usr/bin/bwrap", options.writableRoots ?? []);
+    if (options.writableRoots) assertCommandRootsSafe(options.writableRoots);
+  } catch {
+    return false;
+  }
+  const argv = [
+    path,
+    "--die-with-parent",
+    "--new-session",
+    "--unshare-pid",
+    "--unshare-ipc",
+    "--unshare-uts",
+    ...(options.networkAccess === true ? [] : ["--unshare-net"]),
+    "--proc", "/proc",
+    "--dev", "/dev",
+    ...bindArgs("--ro-bind", READABLE_SYSTEM_PATHS),
+    "--",
+    "/bin/true",
+  ];
+  if (options.probe) return options.probe(argv);
+  const cacheKey = `${path}\0${options.networkAccess === true ? "network" : "isolated"}`;
+  const cached = availabilityCache.get(cacheKey);
+  if (cached !== undefined) return cached;
+  let available = false;
+  try {
+    available = Bun.spawnSync(argv, {
+      env: { PATH: DEFAULT_PATH, LANG: "C.UTF-8", LC_ALL: "C.UTF-8" },
+      stdin: "ignore",
+      stdout: "ignore",
+      stderr: "ignore",
+      timeout: 2_000,
+    }).success;
+  } catch {
+    available = false;
+  }
+  availabilityCache.set(cacheKey, available);
+  return available;
+}