@fungi.computer/truffle 0.1.1 → 0.2.1

package/dist/private-local-bwrap.js

@@ -0,0 +1,70 @@
+import { createHash } from "node:crypto";
+import { accessSync, constants, readFileSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+const digestSchema = z
+    .string()
+    .trim()
+    .regex(/^[a-f0-9]{64}$/u);
+export class LocalBwrapUnavailable extends Error {
+    reason;
+    name = "LocalBwrapUnavailable";
+    constructor(reason, message, options) {
+        super(message, options);
+        this.reason = reason;
+    }
+}
+/** Check both packaged artifacts on every use; never cache verification. */
+export function verifyLocalLinuxSandboxPayload(executable) {
+    verifiedBytes(executable, "fungi-bwrap");
+    try {
+        accessSync(executable, constants.X_OK);
+    }
+    catch (cause) {
+        throw new LocalBwrapUnavailable("not-executable", "Packaged fungi-bwrap cannot be executed; reinstall Fungi.", { cause });
+    }
+    return {
+        executable,
+        seccompFilter: verifiedBytes(join(dirname(executable), "fungi-seccomp.bpf"), "fungi-seccomp.bpf"),
+    };
+}
+function verifiedBytes(path, label) {
+    let bytes;
+    let digest;
+    try {
+        if (!statSync(path).isFile())
+            throw new LocalBwrapUnavailable("not-executable", `Packaged ${label} is not a regular file; reinstall Fungi.`);
+        bytes = readFileSync(path);
+        digest = readFileSync(`${path}.sha256`, "utf8");
+    }
+    catch (cause) {
+        if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+            throw new LocalBwrapUnavailable("missing", `Packaged ${label} or its digest is missing; reinstall Fungi with optional dependencies enabled.`, { cause });
+        throw cause;
+    }
+    const expected = digestSchema.safeParse(digest);
+    if (!expected.success)
+        throw new LocalBwrapUnavailable("invalid-digest", `Packaged ${label} has an invalid SHA-256 record; reinstall Fungi.`);
+    if (createHash("sha256").update(bytes).digest("hex") !== expected.data)
+        throw new LocalBwrapUnavailable("digest-mismatch", `Packaged ${label} digest mismatch; reinstall Fungi. No command was started.`);
+    return bytes;
+}
+/** Same optional native-package lookup as apply_patch, with no PATH fallback. */
+export function localLinuxSandboxPayload() {
+    let executable;
+    if (process.env.FUNGI_BUNDLED_CLI) {
+        const name = `@fungi.computer/spore-native-${process.platform}-${process.arch}`;
+        try {
+            executable = createRequire(process.env.FUNGI_BUNDLED_CLI).resolve(`${name}/bin/fungi-bwrap`);
+        }
+        catch (cause) {
+            throw new LocalBwrapUnavailable("missing", `Missing ${name}/bin/fungi-bwrap; reinstall Fungi with optional dependencies enabled.`, { cause });
+        }
+    }
+    else {
+        executable = fileURLToPath(new URL("../native/bin/fungi-bwrap", import.meta.url));
+    }
+    return verifyLocalLinuxSandboxPayload(executable);
+}

package/dist/private-local-client-version.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Read the installed producer, never the calling window's frozen environment.
+ * Undefined means no fungi is installed on PATH, so no client is current.
+ */
+export declare function readInstalledLocalClientBuildId(launcher?: string): Promise<string | undefined>;

package/dist/private-local-client-version.js

@@ -0,0 +1,43 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFile, realpath } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { promisify } from "node:util";
+import { z } from "zod";
+const execute = promisify(execFile);
+const queryOptions = { timeout: 2_000, maxBuffer: 4_096 };
+const buildId = z.string().regex(/^[a-f0-9]{64}$/u);
+function installedLauncherOnPath() {
+    return new Promise((resolve, reject) => {
+        execFile("which", ["fungi"], queryOptions, (error, stdout) => {
+            if (error === null)
+                resolve(stdout.trim());
+            // which exits 1 when nothing named fungi is installed on PATH.
+            else if (error.code === 1)
+                resolve(undefined);
+            else
+                reject(new Error("Could not look up the installed fungi launcher", {
+                    cause: error,
+                }));
+        });
+    });
+}
+/**
+ * Read the installed producer, never the calling window's frozen environment.
+ * Undefined means no fungi is installed on PATH, so no client is current.
+ */
+export async function readInstalledLocalClientBuildId(launcher) {
+    const found = launcher ?? (await installedLauncherOnPath());
+    if (found === undefined)
+        return undefined;
+    const installed = await realpath(found);
+    if (basename(installed) === "fungi.cjs") {
+        // npm replaces cli.js in place. This is the launcher's own identity rule.
+        return createHash("sha256")
+            .update(await readFile(join(dirname(installed), "cli.js")))
+            .digest("hex");
+    }
+    // Compiled launchers identify their embedded archive, not executable bytes.
+    const { stdout } = await execute(installed, ["--internal-build-id"], queryOptions);
+    return buildId.parse(JSON.parse(stdout));
+}

package/dist/private-local-computer-attach.d.ts

@@ -18,7 +18,7 @@ export declare function attachPrivateLocalComputer(rawEndpoint: string | URL, in
     computer: string;
     folderPath: string;
     hostLabel?: string;
-}>, options?: ControlOptions): Promise<PrivateLocalComputerAttachResult>;
+}>, controlOptions?: ControlOptions): Promise<PrivateLocalComputerAttachResult>;
 export type PrivateLocalComputerDetachResult = Readonly<{
     kind: "detached" | "not-attached" | "uncertain" | "denied";
 }>;
@@ -26,7 +26,7 @@ export type PrivateLocalComputerDetachResult = Readonly<{
  * Detach a Computer's attachment on the Hub, then forget it here. A pending
  * attach is replayed first so the Hub never keeps an attachment Local forgot.
  */
-export declare function detachPrivateLocalComputer(rawEndpoint: string | URL, computer: string, options?: ControlOptions): Promise<PrivateLocalComputerDetachResult>;
+export declare function detachPrivateLocalComputer(rawEndpoint: string | URL, computer: string, input?: ControlOptions): Promise<PrivateLocalComputerDetachResult>;
 /** What `fungi computer status` shows: never a key. */
 export declare function listPrivateLocalComputers(options?: Readonly<{
     credentialPath?: string;
@@ -46,4 +46,4 @@ export type PrivateLocalComputerRunOptions = {
  * Serve one attached folder until `signal` aborts or the Hub refuses the
  * machine (it was detached elsewhere), in which case Local forgets it.
  */
-export declare function runPrivateLocalComputer(rawEndpoint: string | URL, computer: string, options: PrivateLocalComputerRunOptions): Promise<"stopped" | "detached">;
+export declare function runPrivateLocalComputer(rawEndpoint: string | URL, computer: string, input: PrivateLocalComputerRunOptions): Promise<"stopped" | "detached">;

package/dist/private-local-computer-attach.js

@@ -4,6 +4,7 @@ import { hostname } from "node:os";
 import { basename, resolve } from "node:path";
 import { defineIdFamily } from "@fungi.computer/cairn/id";
 import { z } from "zod";
+import { capturePrivateLocalConfigRoot } from "./private-local-config-root.js";
 import { callFungiMcpTeamControl, fungiMcpTeamEndpoint, readFungiMcpLocalBackends, writeFungiMcpLocalBackends, } from "./private-fungi-account.js";
 import { runLocalComputerBackend, startLocalComputerd, } from "./private-local-computer-backend.js";
 /**
@@ -76,7 +77,12 @@ function deviceKey() {
     };
 }
 /** Attach `folderPath` to a Team Computer, or return the existing attachment. */
-export async function attachPrivateLocalComputer(rawEndpoint, input, options = {}) {
+export async function attachPrivateLocalComputer(rawEndpoint, input, controlOptions = {}) {
+    const options = {
+        ...controlOptions,
+        credentialPath: controlOptions.credentialPath ??
+            capturePrivateLocalConfigRoot().credentialPath,
+    };
     const { endpoint, teamId } = fungiMcpTeamEndpoint(rawEndpoint);
     const rootPath = await realpath(resolve(input.folderPath));
     if (!(await stat(rootPath)).isDirectory())
@@ -142,7 +148,11 @@ export async function attachPrivateLocalComputer(rawEndpoint, input, options = {
  * Detach a Computer's attachment on the Hub, then forget it here. A pending
  * attach is replayed first so the Hub never keeps an attachment Local forgot.
  */
-export async function detachPrivateLocalComputer(rawEndpoint, computer, options = {}) {
+export async function detachPrivateLocalComputer(rawEndpoint, computer, input = {}) {
+    const options = {
+        ...input,
+        credentialPath: input.credentialPath ?? capturePrivateLocalConfigRoot().credentialPath,
+    };
     const { endpoint, teamId } = fungiMcpTeamEndpoint(rawEndpoint);
     const saved = await readFungiMcpLocalBackends(options);
     const record = saved.backends.find((candidate) => candidate.teamId === teamId && sameComputer(candidate, computer));
@@ -183,7 +193,11 @@ export async function listPrivateLocalComputers(options = {}) {
  * Serve one attached folder until `signal` aborts or the Hub refuses the
  * machine (it was detached elsewhere), in which case Local forgets it.
  */
-export async function runPrivateLocalComputer(rawEndpoint, computer, options) {
+export async function runPrivateLocalComputer(rawEndpoint, computer, input) {
+    const options = {
+        ...input,
+        credentialPath: input.credentialPath ?? capturePrivateLocalConfigRoot().credentialPath,
+    };
     const { endpoint, teamId } = fungiMcpTeamEndpoint(rawEndpoint);
     const saved = await readFungiMcpLocalBackends(options);
     const record = saved.backends.find((candidate) => candidate.teamId === teamId && sameComputer(candidate, computer));

package/dist/private-local-computer-processes.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import type { LocalSandboxLaunch } from "./private-invocation-computer.js";
 declare const processSchema: z.ZodObject<{
     id: z.ZodString & z.ZodType<import("@fungi.computer/cairn").CairnId<"local-computer-process", "process", 1>, string, z.core.$ZodTypeInternals<import("@fungi.computer/cairn").CairnId<"local-computer-process", "process", 1>, string>>;
     command: z.ZodString;
@@ -99,7 +100,7 @@ export type PrivateLocalProcessCommandSpec = Readonly<{
 }>;
 /** One Session's (or invocation's) view of the host's background processes. */
 export type PrivateLocalProcessScope = Readonly<{
-    start: (spec: PrivateLocalProcessCommandSpec, cwd: string, executionPath: string) => Promise<PrivateLocalProcess>;
+    start: (spec: PrivateLocalProcessCommandSpec, cwd: string, executionPath: string, sandbox?: LocalSandboxLaunch) => Promise<PrivateLocalProcess>;
     status: (id: string) => PrivateLocalProcess;
     list: () => readonly PrivateLocalProcess[];
     read: (id: string, offset: number, maxBytes: number) => Promise<z.output<typeof readOutput>>;
@@ -111,11 +112,13 @@ export type PrivateLocalComputerProcesses = Readonly<{
     scope: (key: string) => PrivateLocalProcessScope;
     /** Stop every process of one scope and remove its logs (Session ended). */
     disposeScope: (key: string) => Promise<void>;
+    /** Whether any background process of any scope is still running. */
+    running: () => boolean;
     /** Stop every process, remove every log, and refuse new starts. */
     close: () => Promise<void>;
 }>;
 /** Open the background-process owner for one invocation root. */
-export declare function createPrivateLocalComputerProcesses(root: string): PrivateLocalComputerProcesses;
+export declare function createPrivateLocalComputerProcesses(root: string, home?: string): PrivateLocalComputerProcesses;
 /**
  * Background operations share the Computer's one shell/exec surface; a
  * plain (not discriminated) union, since `start`'s shell and direct branches
@@ -195,5 +198,5 @@ export declare const backgroundExecOutput: z.ZodUnion<readonly [z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>]>;
 /** Reuse Session ownership and logs; a wait deadline never cancels the command. */
-export declare function callBackgroundExec(scope: PrivateLocalProcessScope, request: z.output<typeof backgroundExecInput>, resolveCwd: (requested: string | undefined) => Promise<string>, executionPath: string, signal: AbortSignal): Promise<z.output<typeof backgroundExecOutput>>;
+export declare function callBackgroundExec(scope: PrivateLocalProcessScope, request: z.output<typeof backgroundExecInput>, resolveCwd: (requested: string | undefined) => Promise<string>, executionPath: string, signal: AbortSignal, sandbox?: LocalSandboxLaunch): Promise<z.output<typeof backgroundExecOutput>>;
 export {};

package/dist/private-local-computer-processes.js

@@ -1,13 +1,15 @@
-import { spawn } from "node:child_process";
+import { spawn, } from "node:child_process";
 import { closeSync, openSync, readSync, writeSync } from "node:fs";
 import { mkdir, rm } from "node:fs/promises";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import process from "node:process";
 import { setTimeout as delay } from "node:timers/promises";
 import { defineIdFamily } from "@fungi.computer/cairn";
 import { z } from "zod";
 import { combinedArgvBytes, launchCwdSchema, launchStdinSchema, maximumLaunchTextLength, } from "./private-local-exec-launch.js";
+import { privateLocalExecEnvironment } from "./private-local-exec-environment.js";
+import { capturePrivateLocalConfigRoot } from "./private-local-config-root.js";
+import { Writable } from "node:stream";
 /**
  * Background processes of the local Computer: the one owner of "a command that
  * outlives a single exec call".
@@ -214,7 +216,7 @@ class ManagedProcess {
     #endedAt = null;
     #leaderExited = false;
     command;
-    constructor(spec, cwd, logDirectory, executionPath) {
+    constructor(spec, cwd, logDirectory, executionPath, home, launch) {
         this.spec = spec;
         this.cwd = cwd;
         this.command = describeCommandSpec(spec);
@@ -222,32 +224,49 @@ class ManagedProcess {
         this.#fd = openSync(this.logPath, "wx+", 0o600);
         const closed = Promise.withResolvers();
         this.closed = closed.promise;
-        const env = { PATH: executionPath, HOME: process.env.HOME ?? homedir() };
+        const env = privateLocalExecEnvironment(executionPath, {
+            HOME: home,
+            XDG_RUNTIME_DIR: process.env.XDG_RUNTIME_DIR,
+            DBUS_SESSION_BUS_ADDRESS: process.env.DBUS_SESSION_BUS_ADDRESS,
+        });
+        if (launch !== undefined) {
+            delete env.XDG_RUNTIME_DIR;
+            delete env.DBUS_SESSION_BUS_ADDRESS;
+            Object.assign(env, launch.environment);
+        }
         try {
             // Its own process group, so neither exec's finalizer nor this host's
             // terminal signals reach it; kill() owns ending the whole group.
-            this.#child =
-                spec.kind === "shell"
-                    ? spawn("sh", ["-c", spec.command], {
-                        cwd,
-                        env,
-                        detached: true,
-                        stdio: [
-                            spec.stdin === undefined ? "ignore" : "pipe",
-                            "pipe",
-                            "pipe",
-                        ],
-                    })
-                    : spawn(spec.executable, spec.args, {
-                        cwd,
-                        env,
-                        detached: true,
-                        stdio: [
-                            spec.stdin === undefined ? "ignore" : "pipe",
-                            "pipe",
-                            "pipe",
-                        ],
-                    });
+            const argv = spec.kind === "shell"
+                ? ["sh", "-c", spec.command]
+                : [spec.executable, ...spec.args];
+            const stdio = [
+                spec.stdin === undefined ? "ignore" : "pipe",
+                "pipe",
+                "pipe",
+            ];
+            if (launch?.seccompFilter !== undefined)
+                stdio.push("pipe");
+            this.#child = spawn(launch?.executable ?? argv[0], launch?.args ?? argv.slice(1), {
+                cwd,
+                env,
+                detached: true,
+                stdio,
+            });
+            if (launch?.seccompFilter !== undefined) {
+                const filter = this.#child.stdio[3];
+                if (!(filter instanceof Writable)) {
+                    this.#child.kill("SIGKILL");
+                    throw new Error("Local sandbox filter input fd3 is unavailable");
+                }
+                // A failed filter delivery cannot become a bare retry or an unhandled
+                // stream error. The existing process owner records and reaps failure.
+                filter.on("error", (error) => {
+                    this.#append(Buffer.from(`\n[fungi: sandbox filter failed: ${error.message}]\n`));
+                    this.killNow();
+                });
+                filter.end(launch.seccompFilter);
+            }
             // Finite stdin, delivered once and closed; never an interactive
             // protocol. `end()` writes the bytes and closes the write side. A
             // child that exits or closes its own stdin before the payload drains
@@ -414,7 +433,7 @@ class ManagedProcess {
     }
 }
 /** Open the background-process owner for one invocation root. */
-export function createPrivateLocalComputerProcesses(root) {
+export function createPrivateLocalComputerProcesses(root, home = capturePrivateLocalConfigRoot().home) {
     const logDirectory = join(root, ".fungi", "processes");
     const scopes = new Map();
     let closed = false;
@@ -446,7 +465,7 @@ export function createPrivateLocalComputerProcesses(root) {
             return record;
         };
         return Object.freeze({
-            start: async (spec, cwd, executionPath) => {
+            start: async (spec, cwd, executionPath, sandbox) => {
                 if (closed)
                     throw new Error("Local Computer processes are closed");
                 const records = owned();
@@ -468,7 +487,11 @@ export function createPrivateLocalComputerProcesses(root) {
                     process.on("exit", killAllNow);
                     exitHook = true;
                 }
-                const started = new ManagedProcess(spec, cwd, logDirectory, executionPath);
+                const argv = spec.kind === "shell"
+                    ? ["sh", "-c", spec.command]
+                    : [spec.executable, ...spec.args];
+                const launch = sandbox?.(cwd, argv);
+                const started = new ManagedProcess(spec, cwd, logDirectory, executionPath, home, launch);
                 records.set(started.id, started);
                 return started.snapshot();
             },
@@ -509,6 +532,7 @@ export function createPrivateLocalComputerProcesses(root) {
             if (owned !== undefined)
                 await dispose(owned);
         },
+        running: () => all().some((record) => record.running),
         close: async () => {
             closed = true;
             const owned = [...scopes.values()];
@@ -552,7 +576,7 @@ const backgroundResult = readOutput.extend({
 });
 export const backgroundExecOutput = z.union([backgroundResult, listOutput]);
 /** Reuse Session ownership and logs; a wait deadline never cancels the command. */
-export async function callBackgroundExec(scope, request, resolveCwd, executionPath, signal) {
+export async function callBackgroundExec(scope, request, resolveCwd, executionPath, signal, sandbox) {
     signal.throwIfAborted();
     if (request.operation === "list")
         return { processes: [...scope.list()] };
@@ -563,7 +587,7 @@ export async function callBackgroundExec(scope, request, resolveCwd, executionPa
         case "start": {
             const cwd = await resolveCwd(request.cwd);
             signal.throwIfAborted();
-            id = (await scope.start(toCommandSpec(request), cwd, executionPath)).id;
+            id = (await scope.start(toCommandSpec(request), cwd, executionPath, sandbox)).id;
             break;
         }
         case "wait":

package/dist/private-local-config-root.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The host's selected user home, not an Agent Home or an invocation Files jail.
+ * Pass these values through the existing home/path parameters. Capture once at
+ * the outer host/client boundary, before awaiting or constructing lazy owners;
+ * later opens, reloads and exec launches must not select ambient HOME again.
+ *
+ * PATH remains the existing per-client/per-Session choice. Neither this value
+ * nor an exec child inherits the rest of the host environment.
+ */
+export type PrivateLocalConfigRoot = Readonly<{
+    home: string;
+    credentialPath: string;
+    serviceDirectory: string;
+}>;
+/**
+ * Select paths without reading credentials, creating directories or starting a
+ * service. Keep this capture independent of service/discovery owners, which
+ * consume its paths. Explicit path overrides remain the caller's responsibility;
+ * there is no settings registry, fallback chain or alternate storage format.
+ */
+export declare function capturePrivateLocalConfigRoot(home?: string): PrivateLocalConfigRoot;

package/dist/private-local-config-root.js

@@ -0,0 +1,19 @@
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { resolveDefaultCredentialPath } from "./private-file-credential-store.js";
+/**
+ * Select paths without reading credentials, creating directories or starting a
+ * service. Keep this capture independent of service/discovery owners, which
+ * consume its paths. Explicit path overrides remain the caller's responsibility;
+ * there is no settings registry, fallback chain or alternate storage format.
+ */
+export function capturePrivateLocalConfigRoot(home = homedir()) {
+    if (!isAbsolute(home))
+        throw new Error("Local configuration home must be absolute");
+    const selected = resolve(home);
+    return Object.freeze({
+        home: selected,
+        credentialPath: resolveDefaultCredentialPath(selected),
+        serviceDirectory: join(selected, ".fungi", "service"),
+    });
+}

package/dist/private-local-containment.d.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+export declare const sandboxUnavailableReasonSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        missing: "missing";
+        "invalid-digest": "invalid-digest";
+        "digest-mismatch": "digest-mismatch";
+        "not-executable": "not-executable";
+        "unsupported-platform": "unsupported-platform";
+        "invalid-folder": "invalid-folder";
+        "backend-refused": "backend-refused";
+    }>;
+    message: z.ZodString;
+}, z.core.$strict>;
+export type SandboxUnavailableReason = z.output<typeof sandboxUnavailableReasonSchema>;
+export declare class LocalSandboxUnavailable extends Error {
+    readonly reason: SandboxUnavailableReason;
+    readonly name = "LocalSandboxUnavailable";
+    constructor(reason: SandboxUnavailableReason);
+}
+export type SandboxCommand = Readonly<{
+    executable: string;
+    args: readonly string[];
+    environment: Readonly<{
+        TMPDIR: string;
+    }>;
+    /** Linux only: feed these verified bytes to fd3; never inherit arbitrary fds. */
+    seccompFilter?: Uint8Array;
+}>;
+/** Existing foreground/background owners retain process and cancellation lifetime. */
+export type LocalSandbox = Readonly<{
+    command(cwd: string, argv: readonly [string, ...string[]]): SandboxCommand;
+    close(): void;
+}>;
+export type SandboxAdmission = Readonly<{
+    state: "ready";
+    sandbox: LocalSandbox;
+}> | Readonly<{
+    state: "unavailable";
+    reason: SandboxUnavailableReason;
+}>;
+/**
+ * The caller already owns the person's auto-approve choice. This module has no
+ * mode, setting, bare-command branch, PATH fallback or permission to widen it.
+ * A ready result proves only that the backend can start, not the escape matrix.
+ */
+export declare function establishLocalSandbox(input: Readonly<{
+    project: string;
+    /** Absolute folder selected by the Local owner. */
+    folder: string;
+    platform?: string;
+}>): SandboxAdmission;

package/dist/private-local-containment.js

@@ -0,0 +1,161 @@
+import { spawnSync } from "node:child_process";
+import { closeSync, mkdtempSync, openSync, realpathSync, rmSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { LocalBwrapUnavailable, localLinuxSandboxPayload, } from "./private-local-bwrap.js";
+import { linuxSandboxCommand } from "./private-local-linux-sandbox.js";
+import { seatbeltCommand } from "./private-local-seatbelt.js";
+import { sandboxPolicy } from "./private-local-sandbox-policy.js";
+import { z } from "zod";
+export const sandboxUnavailableReasonSchema = z.strictObject({
+    kind: z.enum([
+        "unsupported-platform",
+        "invalid-folder",
+        "missing",
+        "invalid-digest",
+        "digest-mismatch",
+        "not-executable",
+        "backend-refused",
+    ]),
+    message: z.string(),
+});
+export class LocalSandboxUnavailable extends Error {
+    reason;
+    name = "LocalSandboxUnavailable";
+    constructor(reason) {
+        super(`Local sandbox unavailable: ${reason.message}`);
+        this.reason = reason;
+    }
+}
+function unavailable(cause) {
+    if (cause instanceof LocalBwrapUnavailable)
+        return { kind: cause.reason, message: cause.message };
+    return {
+        kind: "backend-refused",
+        message: cause instanceof Error ? cause.message : "Sandbox preparation failed.",
+    };
+}
+/**
+ * The caller already owns the person's auto-approve choice. This module has no
+ * mode, setting, bare-command branch, PATH fallback or permission to widen it.
+ * A ready result proves only that the backend can start, not the escape matrix.
+ */
+export function establishLocalSandbox(input) {
+    try {
+        sandboxPolicy(input.project, input.folder);
+    }
+    catch (cause) {
+        return {
+            state: "unavailable",
+            reason: {
+                kind: "invalid-folder",
+                message: cause instanceof Error ? cause.message : "Invalid sandbox folder.",
+            },
+        };
+    }
+    const platform = input.platform ?? process.platform;
+    if (platform !== "linux" && platform !== "darwin")
+        return {
+            state: "unavailable",
+            reason: {
+                kind: "unsupported-platform",
+                message: `Local sandbox is unavailable on ${platform}.`,
+            },
+        };
+    let temporaryDirectory;
+    try {
+        // A sandbox owns only its own temporary directory, never the host's HOME.
+        temporaryDirectory = realpathSync(mkdtempSync(join(tmpdir(), "fungi-sandbox-")));
+        const temporary = temporaryDirectory;
+        let closed = false;
+        const sandbox = {
+            command: (cwd, argv) => {
+                if (closed)
+                    throw new LocalSandboxUnavailable({
+                        kind: "backend-refused",
+                        message: "Sandbox has been closed.",
+                    });
+                // Failed/incomplete authority discovery is not an unavailable backend:
+                // it must not turn into an authorized unsandboxed retry.
+                const policy = sandboxPolicy(input.project, input.folder);
+                try {
+                    const launch = platform === "linux"
+                        ? linuxSandboxCommand(policy, localLinuxSandboxPayload(), cwd, argv)
+                        : seatbeltCommand({ ...policy, temporaryDirectory: temporary }, argv);
+                    return {
+                        ...launch,
+                        environment: { TMPDIR: platform === "linux" ? "/tmp" : temporary },
+                    };
+                }
+                catch (cause) {
+                    throw new LocalSandboxUnavailable(unavailable(cause));
+                }
+            },
+            close: () => {
+                if (closed)
+                    return;
+                closed = true;
+                rmSync(temporary, { recursive: true });
+            },
+        };
+        const command = sandbox.command(realpathSync(input.folder), [
+            "/usr/bin/true",
+        ]);
+        let filterDescriptor;
+        const probe = () => {
+            if (command.seccompFilter !== undefined) {
+                const path = join(temporary, "seccomp.bpf");
+                writeFileSync(path, command.seccompFilter, { mode: 0o600 });
+                filterDescriptor = openSync(path, "r");
+            }
+            return spawnSync(command.executable, [...command.args], {
+                cwd: input.folder,
+                env: { ...command.environment },
+                encoding: "utf8",
+                timeout: 5_000,
+                // Node's maintained spawn allowlist closes every other inherited fd.
+                // bwrap loads and closes fd3 before exec (seccomp_program_new).
+                stdio: [
+                    "ignore",
+                    "pipe",
+                    "pipe",
+                    ...(filterDescriptor === undefined ? [] : [filterDescriptor]),
+                ],
+            });
+        };
+        const result = (() => {
+            try {
+                return probe();
+            }
+            finally {
+                if (filterDescriptor !== undefined)
+                    closeSync(filterDescriptor);
+            }
+        })();
+        if (result.status !== 0) {
+            sandbox.close();
+            const stderr = result.stderr.trim();
+            return {
+                state: "unavailable",
+                reason: {
+                    kind: "backend-refused",
+                    message: result.error?.message ??
+                        (stderr.length > 0
+                            ? stderr
+                            : `Sandbox startup exited ${String(result.status)} (${String(result.signal)}).`),
+                },
+            };
+        }
+        return { state: "ready", sandbox };
+    }
+    catch (cause) {
+        if (temporaryDirectory !== undefined)
+            rmSync(temporaryDirectory, { recursive: true });
+        return {
+            state: "unavailable",
+            reason: cause instanceof LocalSandboxUnavailable
+                ? cause.reason
+                : unavailable(cause),
+        };
+    }
+}