jeo-code 0.12.13 → 0.12.15

package/src/agent/sandbox/authority.ts

@@ -0,0 +1,295 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { canonicalSandboxPath, createSandboxPolicy, sandboxPathContains } from "./policy";
+import type { SandboxConfig, SandboxMount, SandboxSupervisor, SandboxTermination } from "./types";
+
+/** Constructed by trusted parent entry points, never from model/tool arguments. */
+export interface SandboxActor {
+  readonly origin: "terminal" | "discord" | "model";
+  readonly sessionKey: string;
+  readonly userId?: string;
+}
+
+export interface GrantRequest {
+  readonly id: string;
+  readonly sessionKey: string;
+  readonly revision: number;
+  readonly host: string;
+  readonly mode: "ro" | "rw";
+  readonly status: "pending" | "approved" | "denied" | "stale";
+}
+
+export interface GrantAuthoritySnapshot {
+  readonly sessionKey: string;
+  readonly revision: number;
+  readonly grants: readonly SandboxMount[];
+  readonly requests: readonly GrantRequest[];
+  readonly blocked: boolean;
+  readonly stateDirectory: string;
+}
+
+export interface GrantAuthority {
+  requestAccess(host: string, mode: "ro" | "rw"): Promise<GrantRequest>;
+  approve(requestId: string, actor: SandboxActor): Promise<GrantRequest>;
+  reject(requestId: string, actor: SandboxActor): Promise<GrantRequest>;
+  revoke(actor: SandboxActor): Promise<SandboxTermination>;
+  snapshot(actor?: SandboxActor): GrantAuthoritySnapshot;
+  awaitDecision(requestId: string, signal?: AbortSignal): Promise<GrantRequest>;
+}
+
+export interface GrantAuthorityOptions {
+  sessionKey: string;
+  cwd: string;
+  config: SandboxConfig;
+  supervisor: SandboxSupervisor;
+  allowedUserIds: readonly string[];
+  stateDirectory: string;
+  privateRoots?: readonly string[];
+}
+
+type DecisionWaiter = { resolve(value: GrantRequest): void; reject(reason: Error): void };
+
+/** Create app-private state, or verify existing state without widening its ACL. */
+export async function ensurePrivateSandboxDirectory(directory: string): Promise<string> {
+  const canonical = await canonicalSandboxPath(directory, false);
+  if (process.platform === "win32") {
+    const systemRoot = process.env.SystemRoot ?? process.env.SYSTEMROOT;
+    if (!systemRoot || !path.isAbsolute(systemRoot)) throw new Error("SANDBOX_STATE: Windows system directory is unavailable");
+    await fs.mkdir(path.dirname(canonical), { recursive: true });
+    // Fixed parent-owned program; paths are data, never interpolated into code.
+    // Windows PowerShell 5.1 provides .NET Framework's atomic ACL creation API.
+    const script = `
+$ErrorActionPreference = 'Stop'
+try {
+  $directory = $env:JEO_SANDBOX_PRIVATE_DIRECTORY
+  $sid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
+  $inherit = [System.Security.AccessControl.InheritanceFlags]'ContainerInherit, ObjectInherit'
+  if (-not [System.IO.Directory]::Exists($directory)) {
+    $security = New-Object System.Security.AccessControl.DirectorySecurity
+    $security.SetAccessRuleProtection($true, $false)
+    $security.SetOwner($sid)
+    $rule = New-Object System.Security.AccessControl.FileSystemAccessRule($sid, 'FullControl', $inherit, 'None', 'Allow')
+    $security.AddAccessRule($rule)
+    [void][System.IO.Directory]::CreateDirectory($directory, $security)
+  }
+  if (([System.IO.File]::GetAttributes($directory) -band [System.IO.FileAttributes]::ReparsePoint) -ne 0) { throw 'reparse point' }
+  $actual = [System.IO.Directory]::GetAccessControl($directory)
+  if (-not $actual.AreAccessRulesProtected -or $actual.GetOwner([System.Security.Principal.SecurityIdentifier]).Value -ne $sid.Value) { throw 'owner or inheritance' }
+  $rules = $actual.GetAccessRules($true, $true, [System.Security.Principal.SecurityIdentifier])
+  if ($rules.Count -ne 1) { throw 'unexpected access rules' }
+  $rule = $rules[0]
+  if ($rule.IdentityReference.Value -ne $sid.Value -or $rule.IsInherited -or $rule.AccessControlType -ne 'Allow' -or $rule.FileSystemRights -ne 'FullControl' -or $rule.InheritanceFlags -ne $inherit -or $rule.PropagationFlags -ne 'None') { throw 'non-private rule' }
+  [Console]::Out.Write('JEO_PRIVATE_DIRECTORY_VERIFIED')
+  exit 0
+} catch { exit 1 }
+`;
+    const executable = path.join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+    const child = Bun.spawn([executable, "-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], {
+      env: { SystemRoot: systemRoot, JEO_SANDBOX_PRIVATE_DIRECTORY: canonical },
+      stdin: "ignore", stdout: "pipe", stderr: "ignore",
+    });
+    const timer = setTimeout(() => child.kill(), 30_000);
+    try {
+      const [exitCode, output] = await Promise.all([child.exited, new Response(child.stdout).text()]);
+      if (exitCode !== 0 || output !== "JEO_PRIVATE_DIRECTORY_VERIFIED") {
+        throw new Error("SANDBOX_STATE: private Windows owner-only ACL could not be verified");
+      }
+    } finally { clearTimeout(timer); }
+  } else {
+    await fs.mkdir(canonical, { recursive: true, mode: 0o700 });
+  }
+  const stat = await fs.lstat(canonical);
+  if (!stat.isDirectory() || stat.isSymbolicLink() ||
+      (process.platform !== "win32" && ((stat.mode & 0o077) !== 0 || stat.uid !== process.getuid?.()))) {
+    throw new Error("SANDBOX_STATE: authority state must be a private owner-only directory");
+  }
+  return canonical;
+}
+
+/** All mutable authority remains in this parent closure, outside worker mounts. */
+export async function createGrantAuthority(options: GrantAuthorityOptions): Promise<GrantAuthority> {
+  const sessionKey = options.sessionKey;
+  const supervisor = options.supervisor;
+  const allowedUserIds = new Set(options.allowedUserIds);
+  const cwd = await canonicalSandboxPath(options.cwd);
+  const stateDirectory = await canonicalSandboxPath(options.stateDirectory, false);
+  const privatePaths = await Promise.all([stateDirectory, ...(options.privateRoots ?? [])]
+    .map(value => canonicalSandboxPath(value, false)));
+  if (sandboxPathContains(cwd, stateDirectory) || sandboxPathContains(stateDirectory, cwd)) {
+    throw new Error("SANDBOX_STATE: authority state must be outside workspace mounts");
+  }
+  const initialPolicy = await createSandboxPolicy({
+    sessionKey, revision: 0, cwd, config: options.config, privatePaths,
+  });
+  await ensurePrivateSandboxDirectory(stateDirectory);
+  const config = initialPolicy.config;
+  let revision = initialPolicy.revision;
+  let grants: readonly SandboxMount[] = Object.freeze([]);
+  const requests = new Map<string, GrantRequest>();
+  const waiters = new Map<string, Set<DecisionWaiter>>();
+  let failed = false;
+  let transitioning = false;
+  let queue: Promise<unknown> = Promise.resolve();
+
+  function serialize<T>(operation: () => Promise<T> | T): Promise<T> {
+    const next = queue.then(operation);
+    queue = next.catch(() => undefined);
+    return next;
+  }
+
+  function authorize(actor: SandboxActor): void {
+    if (!actor || actor.origin === "model" ||
+        (actor.origin !== "terminal" && actor.origin !== "discord") ||
+        (actor.origin === "discord" && (!actor.userId || !allowedUserIds.has(actor.userId)))) {
+      throw new Error("UNAUTHORIZED: sandbox decisions require an authenticated human");
+    }
+    if (actor.sessionKey !== sessionKey) throw new Error("SESSION_MISMATCH: sandbox actor belongs to another session");
+  }
+
+  function requireAvailable(): void {
+    if (failed) throw new Error("REVOKE_INCOMPLETE: sandbox authority is blocked after an unconfirmed transition");
+  }
+
+  function pendingRequest(id: string): GrantRequest {
+    const request = requests.get(id);
+    if (!request) throw new Error("UNKNOWN_REQUEST: sandbox request does not exist in this session");
+    if (request.revision !== revision || request.status !== "pending") {
+      throw new Error("STALE_REQUEST: sandbox request is no longer pending at the current revision");
+    }
+    return request;
+  }
+
+  function decide(request: GrantRequest, status: GrantRequest["status"]): GrantRequest {
+    const decided = Object.freeze({ ...request, status });
+    requests.set(request.id, decided);
+    const listeners = waiters.get(request.id);
+    waiters.delete(request.id);
+    for (const waiter of listeners ?? []) waiter.resolve(decided);
+    return decided;
+  }
+
+  function stalePending(): void {
+    for (const request of requests.values()) {
+      if (request.status === "pending") decide(request, "stale");
+    }
+  }
+
+  function block(error: unknown): never {
+    failed = true;
+    stalePending();
+    throw new Error("REVOKE_INCOMPLETE: sandbox transition could not confirm removal of old authority", { cause: error });
+  }
+
+  return Object.freeze({
+    async requestAccess(host: string, mode: "ro" | "rw"): Promise<GrantRequest> {
+      return serialize(async () => {
+        requireAvailable();
+        if (mode !== "ro" && mode !== "rw") throw new Error("SANDBOX_POLICY: invalid access mode");
+        if (typeof host !== "string" || !host.trim()) throw new Error("SANDBOX_PATH: invalid host path");
+        const canonical = await canonicalSandboxPath(host, true, cwd);
+        // Reuse the policy validator for every private-path and mount restriction.
+        await createSandboxPolicy({ sessionKey, revision, cwd, config, grants: [...grants, { host: canonical, mode }], privatePaths });
+        const request: GrantRequest = Object.freeze({
+          id: randomUUID(), sessionKey, revision, host: canonical, mode, status: "pending",
+        });
+        requests.set(request.id, request);
+        return request;
+      });
+    },
+
+    async approve(requestId: string, actor: SandboxActor): Promise<GrantRequest> {
+      authorize(actor);
+      return serialize(async () => {
+        requireAvailable();
+        const request = pendingRequest(requestId);
+        try {
+          if (await canonicalSandboxPath(request.host) !== request.host) {
+            throw new Error("Requested resource changed its canonical path");
+          }
+        } catch (error) {
+          decide(request, "stale");
+          throw new Error("STALE_REQUEST: requested resource no longer has its original canonical path", { cause: error });
+        }
+        const policy = await createSandboxPolicy({
+          sessionKey, revision: revision + 1, cwd, config,
+          grants: [...grants, { host: request.host, mode: request.mode }], privatePaths,
+        });
+        transitioning = true;
+        try {
+          await supervisor.replacePolicy(policy);
+          revision = policy.revision;
+          grants = Object.freeze(policy.mounts.filter(mount => mount.host !== cwd));
+          const approved = decide(request, "approved");
+          stalePending();
+          return approved;
+        } catch (error) {
+          return block(error);
+        } finally {
+          transitioning = false;
+        }
+      });
+    },
+
+    async reject(requestId: string, actor: SandboxActor): Promise<GrantRequest> {
+      authorize(actor);
+      return serialize(() => {
+        requireAvailable();
+        return decide(pendingRequest(requestId), "denied");
+      });
+    },
+
+    async revoke(actor: SandboxActor): Promise<SandboxTermination> {
+      authorize(actor);
+      return serialize(async () => {
+        transitioning = true;
+        try {
+          const termination = await supervisor.revoke();
+          if (termination.gone !== true || termination.residual.length !== 0) {
+            throw new Error("REVOKE_INCOMPLETE: owned sandbox processes remain");
+          }
+          grants = Object.freeze([]);
+          revision++;
+          stalePending();
+          return Object.freeze({ gone: true, residual: Object.freeze([]) });
+        } catch (error) {
+          return block(error);
+        } finally {
+          transitioning = false;
+        }
+      });
+    },
+
+    snapshot(actor?: SandboxActor): GrantAuthoritySnapshot {
+      if (actor !== undefined) authorize(actor);
+      return Object.freeze({
+        sessionKey, revision, grants,
+        requests: Object.freeze([...requests.values()]),
+        blocked: failed || transitioning, stateDirectory,
+      });
+    },
+
+    async awaitDecision(requestId: string, signal?: AbortSignal): Promise<GrantRequest> {
+      const request = requests.get(requestId);
+      if (!request) throw new Error("UNKNOWN_REQUEST: sandbox request does not exist in this session");
+      if (signal?.aborted) throw new Error("ABORTED: waiting for sandbox decision was cancelled");
+      if (request.status !== "pending") return request;
+      return new Promise<GrantRequest>((resolve, reject) => {
+        const listeners = waiters.get(requestId) ?? new Set<DecisionWaiter>();
+        const cleanup = () => {
+          signal?.removeEventListener("abort", abort);
+          listeners.delete(waiter);
+          if (listeners.size === 0) waiters.delete(requestId);
+        };
+        const waiter: DecisionWaiter = {
+          resolve(value) { cleanup(); resolve(value); },
+          reject(error) { cleanup(); reject(error); },
+        };
+        const abort = () => waiter.reject(new Error("ABORTED: waiting for sandbox decision was cancelled"));
+        listeners.add(waiter);
+        waiters.set(requestId, listeners);
+        signal?.addEventListener("abort", abort, { once: true });
+      });
+    },
+  });
+}

package/src/agent/sandbox/bundle.ts

@@ -0,0 +1,37 @@
+import * as fs from "node:fs/promises";
+import { constants } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import * as path from "node:path";
+import { jeoHomeDir } from "../notify/paths";
+import { ensurePrivateSandboxDirectory } from "./authority";
+import source from "./hands-source.text";
+
+/** The text asset is embedded by Bun's standalone compiler, not read from a release source tree. */
+export async function prepareHandsBundle(): Promise<string> {
+  const directory = await ensurePrivateSandboxDirectory(path.join(jeoHomeDir(), "sandbox", "runtime"));
+  const digest = new Bun.CryptoHasher("sha256").update(source).digest("hex");
+  const file = path.join(await fs.realpath(directory), `${digest}.js`);
+  let existing: FileHandle;
+  try { existing = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    const staging = await fs.mkdtemp(path.join(directory, ".bundle-"));
+    const temporary = path.join(staging, "hands.js");
+    try {
+      const output = await fs.open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+      try { await output.writeFile(source); await output.sync(); await output.chmod(0o400); }
+      finally { await output.close(); }
+      try { await fs.link(temporary, file); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+    } finally { await fs.rm(staging, { recursive: true, force: true }); }
+    existing = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  }
+  try {
+    const stat = await existing.stat();
+    if (!stat.isFile() || (process.platform !== "win32" && ((stat.mode & 0o022) !== 0 || stat.uid !== process.getuid?.())) ||
+        new Bun.CryptoHasher("sha256").update(await existing.readFile()).digest("hex") !== digest) {
+      throw new Error("SANDBOX_BUNDLE: trusted runtime content or ownership changed");
+    }
+  } finally { await existing.close(); }
+  return file;
+}

package/src/agent/sandbox/control.ts

@@ -0,0 +1,49 @@
+import type { GrantAuthority, SandboxActor } from "./authority";
+
+export interface SandboxControlResult {
+  handled: boolean;
+  output: string;
+}
+
+const USAGE = "Usage: /sandbox approve <requestId> | /sandbox deny <requestId> | /sandbox revoke | /sandbox status";
+
+/** Only standalone, directly submitted parent controls can make human decisions. */
+export async function handleSandboxControl(
+  text: string,
+  actor: SandboxActor,
+  authority: GrantAuthority,
+): Promise<SandboxControlResult> {
+  // Multiline prompts, quotations, and embedded examples belong to conversation.
+  if (/[\r\n]/.test(text) || !/^\/sandbox(?:[\t ]|$)/.test(text)) {
+    return { handled: false, output: "" };
+  }
+  const parts = text.trim().split(/[\t ]+/);
+  const command = parts[1];
+  try {
+    if ((command === "approve" || command === "deny") && parts.length === 3) {
+      const request = command === "approve"
+        ? await authority.approve(parts[2]!, actor)
+        : await authority.reject(parts[2]!, actor);
+      return { handled: true, output: `Sandbox request ${request.id}: ${request.status} (${request.mode} ${request.host}).` };
+    }
+    if (command === "revoke" && parts.length === 2) {
+      await authority.revoke(actor);
+      return { handled: true, output: "Sandbox access revoked; owned containers confirmed removed." };
+    }
+    if (command === "status" && parts.length === 2) {
+      const state = authority.snapshot(actor);
+      const pending = state.requests.filter(request => request.status === "pending");
+      const details = pending.map(request => `${request.id}: ${request.mode} ${request.host}`);
+      return {
+        handled: true,
+        output: [
+          `Sandbox session ${state.sessionKey}, revision ${state.revision}: ${state.blocked ? "blocked" : "ready"}; ${state.grants.length} grants, ${pending.length} pending requests.`,
+          ...details,
+        ].join("\n"),
+      };
+    }
+    return { handled: true, output: `Invalid sandbox control. ${USAGE}` };
+  } catch (error) {
+    return { handled: true, output: `Sandbox control error: ${error instanceof Error ? error.message : "Unknown error"}` };
+  }
+}

package/src/agent/sandbox/docker.ts

@@ -0,0 +1,283 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { ensurePrivateSandboxDirectory } from "./authority";
+import { canonicalSandboxPath, nativeSandboxHome, sandboxPathContains, validateSandboxConfig, validateSandboxMountSource } from "./policy";
+import type { SandboxBackend, SandboxConfig, SandboxPolicy, SandboxProcess, SandboxTermination } from "./types";
+
+export interface DockerCommandResult { exitCode: number; stdout: string; stderr: string }
+interface DockerChild {
+  stdin: SandboxProcess["stdin"];
+  stdout: ReadableStream<Uint8Array>;
+  stderr: ReadableStream<Uint8Array>;
+  exited: Promise<number>;
+  kill(signal?: number | NodeJS.Signals): void;
+}
+export interface DockerBackendOptions {
+  dockerPath?: string;
+  env?: Record<string, string | undefined>;
+  platform?: NodeJS.Platform;
+  run?: (argv: readonly string[]) => Promise<DockerCommandResult>;
+  spawn?: (argv: readonly string[]) => DockerChild;
+}
+
+/** Launch failed, but the exact owned container still requires verified removal. */
+export class SandboxLaunchError extends Error {
+  readonly residual: readonly string[];
+  readonly #retry: () => Promise<SandboxTermination>;
+
+  constructor(message: string, residual: readonly string[], cleanup: () => Promise<SandboxTermination>, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "SandboxLaunchError";
+    this.residual = Object.freeze([...residual]);
+    this.#retry = cleanup;
+  }
+
+  cleanup(): Promise<SandboxTermination> { return this.#retry(); }
+}
+
+const OWNER = "dev.jeo.sandbox.owner";
+const SESSION = "dev.jeo.sandbox.session";
+const REVISION = "dev.jeo.sandbox.revision";
+const CLI_OUTPUT_BYTES = 1_000_000; // Same transport ceiling as messenger workers.
+
+export function createDockerBackend(options: DockerBackendOptions = {}): SandboxBackend {
+  const executable = options.dockerPath ?? Bun.which("docker") ?? "docker";
+  const platform = options.platform ?? process.platform;
+  const suppliedEnv = options.env ?? process.env;
+  const environment: Record<string, string> = {};
+  for (const key of ["PATH", "HOME", "USER", "LOGNAME", "TMPDIR", "TEMP", "TMP", "SystemRoot", "SYSTEMROOT", "USERPROFILE", "APPDATA", "LOCALAPPDATA", "PATHEXT", "DOCKER_HOST", "DOCKER_CONTEXT", "DOCKER_CONFIG", "DOCKER_API_VERSION"]) {
+    if (suppliedEnv[key] !== undefined) environment[key] = suppliedEnv[key]!;
+  }
+  const owner = crypto.randomUUID();
+  const run = options.run ?? (async (argv: readonly string[]): Promise<DockerCommandResult> => {
+    const child = Bun.spawn([...argv], { env: environment, stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+    const timer = setTimeout(() => child.kill(), 30_000);
+    const collect = async (stream: ReadableStream<Uint8Array>): Promise<string> => {
+      const reader = stream.getReader();
+      const chunks: Uint8Array[] = [];
+      let bytes = 0;
+      try {
+        for (;;) {
+          const next = await reader.read();
+          if (next.done) break;
+          bytes += next.value.byteLength;
+          if (bytes > CLI_OUTPUT_BYTES) { child.kill(); throw new Error("Docker control output exceeded its bound"); }
+          chunks.push(next.value);
+        }
+      } finally { reader.releaseLock(); }
+      return Buffer.concat(chunks).toString("utf8");
+    };
+    try {
+      const [exitCode, stdout, stderr] = await Promise.all([child.exited, collect(child.stdout), collect(child.stderr)]);
+      return { exitCode, stdout, stderr };
+    } finally { clearTimeout(timer); }
+  });
+  const spawn = options.spawn ?? ((argv: readonly string[]): DockerChild =>
+    Bun.spawn([...argv], { env: environment, stdin: "pipe", stdout: "pipe", stderr: "pipe" }) as unknown as DockerChild);
+  const command = (args: readonly string[]) => run([executable, ...args]);
+
+  async function checked(args: readonly string[], context: string): Promise<string> {
+    let result: DockerCommandResult;
+    try { result = await command(args); }
+    catch { throw new Error(`SANDBOX_UNAVAILABLE: Docker ${context} could not run`); }
+    if (result.exitCode !== 0) throw new Error(`SANDBOX_UNAVAILABLE: Docker ${context} failed; check the local daemon and existing image`);
+    return result.stdout.trim();
+  }
+
+  async function preflight(config: SandboxConfig): Promise<{ imageId: string; platform: string }> {
+    validateSandboxConfig(config);
+    const explicit = environment.DOCKER_CONTEXT ? undefined : environment.DOCKER_HOST;
+    if (explicit && !/^(unix:\/\/\/|npipe:\/\/)/i.test(explicit)) throw new Error("SANDBOX_UNAVAILABLE: only local Docker endpoints are authorized");
+    const context = await checked(["context", "show"], "context discovery");
+    const endpointText = await checked(["context", "inspect", context, "--format", "{{json .Endpoints.docker.Host}}"], "context inspection");
+    let endpoint: unknown;
+    try { endpoint = JSON.parse(endpointText); } catch { throw new Error("SANDBOX_UNAVAILABLE: malformed Docker endpoint"); }
+    const effective = explicit ?? endpoint;
+    if (typeof effective !== "string" || !/^(unix:\/\/\/|npipe:\/\/)/i.test(effective)) throw new Error("SANDBOX_UNAVAILABLE: remote Docker context is not authorized");
+    environment.DOCKER_HOST = effective;
+    delete environment.DOCKER_CONTEXT; // Pin the verified local endpoint for every later command.
+    let info: { OSType?: string };
+    let image: { Id?: string; Os?: string; Architecture?: string };
+    try {
+      info = JSON.parse(await checked(["info", "--format", "{{json .}}"], "daemon inspection"));
+      image = JSON.parse(await checked(["image", "inspect", config.image, "--format", "{{json .}}"], "local image inspection"));
+    } catch (error) {
+      if (error instanceof Error && error.message.startsWith("SANDBOX_")) throw error;
+      throw new Error("SANDBOX_UNAVAILABLE: malformed Docker daemon or image response");
+    }
+    if (info.OSType !== "linux" || image.Os !== "linux") throw new Error("SANDBOX_UNAVAILABLE: a Linux Docker daemon and Linux Bun image are required");
+    if (!image.Id || !/^sha256:[a-f0-9]{64}$/.test(image.Id) || !image.Architecture) throw new Error("SANDBOX_UNAVAILABLE: local image has no immutable identity");
+    return { imageId: image.Id, platform: `linux/${image.Architecture}` };
+  }
+
+  async function acquireLaunchLock(sources: readonly string[]): Promise<() => Promise<void>> {
+    // One lock per native user, independent of session/config/backend instance.
+    const directory = await ensurePrivateSandboxDirectory(path.join(await nativeSandboxHome(), ".jeo", "sandbox-launch"));
+    if (sources.some(source => sandboxPathContains(source, directory) || sandboxPathContains(directory, source))) {
+      throw new Error("SANDBOX_POLICY: mount overlaps the parent launch lock");
+    }
+    const lock = path.join(directory, "launch.lock");
+    const deadline = Date.now() + 30_000;
+    for (;;) {
+      try {
+        await fs.mkdir(lock, { mode: 0o700 });
+        const owned = await fs.lstat(lock, { bigint: true });
+        return async () => {
+          let current;
+          try { current = await fs.lstat(lock, { bigint: true }); }
+          catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return; throw error; }
+          if (!current.isDirectory() || current.isSymbolicLink() || current.dev !== owned.dev || current.ino !== owned.ino) throw new Error("SANDBOX_UNAVAILABLE: launch lock ownership changed");
+          await fs.rmdir(lock);
+        };
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST" || Date.now() >= deadline) throw new Error("SANDBOX_UNAVAILABLE: managed launch lock unavailable", { cause: error });
+        try {
+          const stat = await fs.lstat(lock);
+          if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("SANDBOX_UNAVAILABLE: invalid managed launch lock");
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+          throw error;
+        }
+        await Bun.sleep(25);
+      }
+    }
+  }
+
+  // Every managed launch holds the same native-user lock. Identical/disjoint bind
+  // roots keep hands from renaming another source or its ancestors. Inspect Source
+  // is admission metadata, not physical host/guest inode attestation; native host
+  // and Docker operators are outside this model-execution boundary.
+  async function validateManagedRoots(sources: readonly string[]): Promise<void> {
+    const ids = (await checked(["container", "ls", "--all", "--filter", `label=${OWNER}`, "--format", "{{.ID}}"], "managed container discovery")).split(/\r?\n/).filter(Boolean);
+    for (const id of ids) {
+      if (!/^[A-Za-z0-9_-]+$/.test(id)) throw new Error("SANDBOX_UNAVAILABLE: invalid managed container identity");
+      let record: { Config?: { Labels?: Record<string, string> }; Mounts?: { Type?: string; Source?: string; Destination?: string }[] };
+      try { record = JSON.parse(await checked(["inspect", "--format", "{{json .}}", id], "managed mount inspection")); }
+      catch { throw new Error("SANDBOX_UNAVAILABLE: managed mount metadata unavailable"); }
+      const labels = record.Config?.Labels;
+      if (!labels?.[OWNER] || !labels[SESSION] || !/^\d+$/.test(labels[REVISION] ?? "") || !Array.isArray(record.Mounts)) throw new Error("SANDBOX_UNAVAILABLE: unknown managed ownership or mounts");
+      for (const mount of record.Mounts) {
+        if (mount.Type === "tmpfs" && mount.Destination === "/tmp") continue;
+        if (mount.Type !== "bind" || typeof mount.Source !== "string" || !path.isAbsolute(mount.Source)) throw new Error("SANDBOX_UNAVAILABLE: unknown managed mount metadata");
+        const source = await canonicalSandboxPath(mount.Source);
+        if (sources.some(candidate => candidate !== source && (sandboxPathContains(candidate, source) || sandboxPathContains(source, candidate)))) {
+          throw new Error("SANDBOX_MOUNT_OVERLAP: managed mount roots must be identical or disjoint");
+        }
+      }
+    }
+  }
+
+  async function launch(policy: SandboxPolicy, bundlePath: string): Promise<SandboxProcess> {
+    const qualified = await preflight(policy.config);
+    const bundle = await canonicalSandboxPath(bundlePath);
+    if (!(await fs.stat(bundle)).isFile()) throw new Error("SANDBOX_POLICY: hands bundle is not a regular file");
+    const sources = [...policy.mounts.map(mount => mount.host), bundle];
+    for (let index = 0; index < sources.length; index++) {
+      for (const other of sources.slice(index + 1)) {
+        if (other !== sources[index] && (sandboxPathContains(other, sources[index]!) || sandboxPathContains(sources[index]!, other))) throw new Error("SANDBOX_MOUNT_OVERLAP: mount roots must be identical or disjoint");
+      }
+    }
+    const sourceIdentity = await Promise.all(sources.map(source => fs.stat(source, { bigint: true })));
+    const validateSources = async (): Promise<void> => {
+      for (let index = 0; index < sources.length; index++) {
+        const source = sources[index]!;
+        const stat = await fs.stat(source, { bigint: true });
+        if (await canonicalSandboxPath(source) !== source || stat.dev !== sourceIdentity[index]!.dev || stat.ino !== sourceIdentity[index]!.ino) throw new Error("SANDBOX_MOUNT_IDENTITY: host mount source changed during launch");
+      }
+      for (const mount of policy.mounts) await validateSandboxMountSource(mount.host, policy.privatePaths ?? [], [environment.DOCKER_HOST!.startsWith("unix://") ? environment.DOCKER_HOST!.slice(7) : "", suppliedEnv.SSH_AUTH_SOCK ?? ""].filter(Boolean));
+    };
+    const mounts: string[] = [];
+    for (const mount of policy.mounts) {
+      if (await canonicalSandboxPath(mount.host) !== mount.host || sandboxPathContains(mount.host, bundle)) {
+        throw new Error("SANDBOX_POLICY: mount changed or exposes the trusted hands bundle");
+      }
+      // Docker's --mount grammar is CSV, not shell syntax. Refuse ambiguous source names.
+      if (/[,\r\n\0]/.test(mount.host) || !/^\/(workspace|grants\/[a-f0-9]{64})$/.test(mount.guest)) throw new Error("SANDBOX_POLICY: unsupported mount path");
+      mounts.push("--mount", `type=bind,source=${mount.host},target=${mount.guest}${mount.mode === "ro" ? ",readonly" : ""}`);
+    }
+    if (/[,\r\n\0]/.test(bundle)) throw new Error("SANDBOX_POLICY: unsupported bundle path");
+    const name = `jeo-sbx-${new Bun.CryptoHasher("sha256").update(policy.sessionKey).digest("hex").slice(0, 20)}-r${policy.revision}-${crypto.randomUUID()}`;
+    const uid = platform === "win32" ? undefined : process.getuid?.();
+    const gid = platform === "win32" ? undefined : process.getgid?.();
+    if (uid === 0) throw new Error("SANDBOX_UNAVAILABLE: run the host controller as a non-root user");
+    const user = uid === undefined || gid === undefined ? "bun" : `${uid}:${gid}`;
+    const createArgs = [
+      "create", "--pull=never", "--name", name,
+      "--label", `${OWNER}=${owner}`, "--label", `${SESSION}=${policy.sessionKey}`, "--label", `${REVISION}=${policy.revision}`,
+      "--init", "--interactive", "--network", "none", "--read-only", "--cap-drop", "ALL", "--security-opt", "no-new-privileges",
+      "--pids-limit", String(policy.config.limits.pids), "--memory", String(policy.config.limits.memoryBytes), "--cpus", String(policy.config.limits.cpus),
+      "--user", user, "--tmpfs", "/tmp:rw,nosuid,nodev,mode=1777", "--workdir", "/workspace",
+      "--env", "HOME=/tmp/jeo-home", "--env", "JEO_CONFIG_DIR=/tmp/jeo-home", "--env", "JEO_SANDBOX_HANDS=1",
+      ...mounts, "--mount", `type=bind,source=${bundle},target=/jeo/hands.js,readonly`,
+      "--entrypoint", "/usr/local/bin/bun", qualified.imageId, "/jeo/hands.js",
+    ];
+    let stopping: Promise<SandboxTermination> | undefined;
+    const stop = (): Promise<SandboxTermination> => {
+      stopping ??= (async () => {
+        try {
+          const before = await command(["inspect", "--format", "{{json .}}", name]);
+          if (before.exitCode === 0) {
+            const record = JSON.parse(before.stdout) as { Config?: { Labels?: Record<string, string> } };
+            const labels = record.Config?.Labels;
+            if (labels?.[OWNER] !== owner || labels[SESSION] !== policy.sessionKey || labels[REVISION] !== String(policy.revision)) {
+              return { gone: false, residual: [name] };
+            }
+            await command(["rm", "--force", name]);
+          }
+          const remaining = await command(["container", "ls", "--all", "--filter", `name=^/${name}$`, "--format", "{{.ID}}"]);
+          if (remaining.exitCode !== 0 || remaining.stdout.trim()) return { gone: false, residual: [name] };
+          const revision = await command(["container", "ls", "--all", "--filter", `label=${OWNER}=${owner}`, "--filter", `label=${SESSION}=${policy.sessionKey}`, "--filter", `label=${REVISION}=${policy.revision}`, "--format", "{{.Names}}"]);
+          if (revision.exitCode !== 0) return { gone: false, residual: [name] };
+          const residual = revision.stdout.trim().split(/\r?\n/).filter(Boolean);
+          return { gone: residual.length === 0, residual };
+        } catch { return { gone: false, residual: [name] }; }
+      })();
+      const attempt = stopping;
+      void attempt.then(result => { if (!result.gone && stopping === attempt) stopping = undefined; });
+      return attempt;
+    };
+    const unlock = await acquireLaunchLock(sources);
+    let released = false;
+    const cleanupOwned = async (): Promise<SandboxTermination> => {
+      const result = await stop();
+      if (!released) {
+        try { await unlock(); released = true; }
+        catch { return { gone: false, residual: [...result.residual, "managed launch lock"] }; }
+      }
+      return result;
+    };
+    try {
+      await validateManagedRoots(sources);
+      await validateSources();
+      await checked(createArgs, "container creation");
+      await validateSources();
+      const child = spawn([executable, "start", "--attach", "--interactive", name]);
+      const deadline = Date.now() + 30_000;
+      for (;;) {
+        const record = JSON.parse(await checked(["inspect", "--format", "{{json .}}", name], "container start verification")) as { Config?: { Labels?: Record<string, string> }; State?: { Running?: boolean }; Mounts?: { Type?: string; Source?: string; Destination?: string; RW?: boolean }[] };
+        const labels = record.Config?.Labels;
+        if (labels?.[OWNER] !== owner || labels[SESSION] !== policy.sessionKey || labels[REVISION] !== String(policy.revision) || !Array.isArray(record.Mounts)) throw new Error("SANDBOX_UNAVAILABLE: started container ownership or mount metadata changed");
+        const actual = record.Mounts.filter(mount => mount.Type === "bind");
+        const expected = [...policy.mounts.map(mount => ({ source: mount.host, guest: mount.guest, writable: mount.mode === "rw" })), { source: bundle, guest: "/jeo/hands.js", writable: false }];
+        if (actual.length !== expected.length) throw new Error("SANDBOX_UNAVAILABLE: unexpected container bind mounts");
+        for (const mount of expected) {
+          const observed = actual.find(candidate => candidate.Destination === mount.guest);
+          if (!observed?.Source || await canonicalSandboxPath(observed.Source) !== mount.source || observed.RW !== mount.writable) throw new Error("SANDBOX_UNAVAILABLE: actual container bind configuration changed");
+        }
+        if (record.State?.Running === true) break;
+        if (Date.now() >= deadline) throw new Error("SANDBOX_UNAVAILABLE: container did not start");
+        await Bun.sleep(25);
+      }
+      await validateSources();
+      await unlock();
+      released = true;
+      return { name, stdin: child.stdin, stdout: child.stdout, stderr: child.stderr, exited: child.exited, stop };
+    } catch (error) {
+      const cleanup = await cleanupOwned();
+      if (!cleanup.gone) throw new SandboxLaunchError(`REVOKE_INCOMPLETE: failed sandbox launch left owned resources for ${name}`, cleanup.residual, cleanupOwned, { cause: error });
+      throw error;
+    }
+  }
+
+  return { preflight, launch };
+}