@fungi.computer/truffle 0.2.1 → 0.3.0

package/dist/private-invocation-files.js

@@ -7,6 +7,15 @@ import { RE2JS } from "re2js";
 import { createPrivateFilesPatch } from "./private-files-patch.js";
 import { fitLocalImage, maximumLocalImageInputBytes, } from "./local-image-fit.js";
 import writeFileAtomic from "write-file-atomic";
+const readOnlyFilesMessage = "Read-only mode: switch to Workspace to edit";
+/** An expected Files refusal, not a proposal for an approval. */
+class ReadOnlyFilesRefusal extends FilesEditError {
+    constructor(path) {
+        super("read-only", path, readOnlyFilesMessage);
+        this.name = "ReadOnlyFilesRefusal";
+        this.message = readOnlyFilesMessage;
+    }
+}
 const maximumFileBytes = 128 * 1_024;
 const defaultScanBounds = {
     candidates: 50_000,
@@ -472,10 +481,14 @@ function createWriteQueue() {
  * in-root symlinks. This is trusted same-user containment, not protection from
  * a same-user process racing pathname resolution.
  */
-export async function createPrivateInvocationFilesPort(path, scanBounds = defaultScanBounds, sandbox) {
+export async function createPrivateInvocationFilesPort(path, scanBounds = defaultScanBounds, sandbox, mode = () => "full-access") {
     const root = await InvocationRoot.capture(path);
     const write = createWriteQueue();
     const port = {
+        assertEditable(requested) {
+            if (mode() === "read-only")
+                throw new ReadOnlyFilesRefusal(requested);
+        },
         async read(input, context) {
             return await readPage(await root.existing(input.path, context), input.offset, input.limit, context);
         },
@@ -491,6 +504,7 @@ export async function createPrivateInvocationFilesPort(path, scanBounds = defaul
         async replace(input, context) {
             return await write(async () => {
                 checkCancellation(context);
+                port.assertEditable?.(input.path);
                 const path = await root.existing(input.path, context);
                 const current = await readBoundedText(path, context);
                 if (current !== input.expectedContent)
@@ -500,7 +514,7 @@ export async function createPrivateInvocationFilesPort(path, scanBounds = defaul
                     throw new FilesEditError("file-too-large", input.path, `Result exceeds ${String(maximumFileBytes)} bytes; use files.patch for a small change`);
                 }
                 checkCancellation(context);
-                sandbox?.assertWrite(path.resolved);
+                sandbox?.assertWrite([path.resolved]);
                 await writeFileAtomic(path.resolved, input.content, {
                     encoding: "utf8",
                 });
@@ -515,6 +529,11 @@ export async function createPrivateInvocationFilesPort(path, scanBounds = defaul
         return Object.freeze(port);
     return Object.freeze({
         ...port,
-        patch: (input, context) => write(() => patch(input, context)),
+        patch: (input, context) => write(async () => {
+            checkCancellation(context);
+            if (mode() === "read-only")
+                throw new ReadOnlyFilesRefusal(root.canonicalPath);
+            return patch(input, context);
+        }),
     });
 }

package/dist/private-local-agent-control.d.ts

@@ -70,7 +70,7 @@ export declare function createPrivateLocalAgentControl(input: Readonly<{
         list: (signal: AbortSignal, options?: Readonly<{
             archived?: boolean;
         }>) => Promise<readonly AgentControlAgent[]>;
-        send?: (input: import("@fungi.computer/shiitake/agent-control").AgentDelegationInput, sourceSessionId: string, signal: AbortSignal, invocation?: import("@fungi.computer/shiitake/agent-control").AgentDelegationInvocation) => Promise<import("@fungi.computer/shiitake").Accepted>;
+        send?: (input: import("@fungi.computer/shiitake/agent-control").AgentDelegationInput, sourceSessionId: string, signal: AbortSignal, invocation?: import("@fungi.computer/shiitake/agent-control").AgentDelegationInvocation) => Promise<import("@fungi.computer/shiitake").Accepted | import("@fungi.computer/shiitake").Held>;
         recall?: (input: import("@fungi.computer/shiitake/agent-control").AgentRecallInput, sourceSessionId: string, signal: AbortSignal) => Promise<import("@fungi.computer/shiitake").CancelResult>;
         create?: (input: Readonly<{
             requestId: string;
@@ -91,7 +91,7 @@ export declare function createPrivateLocalAgentControl(input: Readonly<{
         models?: (signal: AbortSignal) => Promise<readonly import("@fungi.computer/shiitake/agent-control").AgentControlModel[]>;
         checkModel?: (input: Readonly<{
             agentId: string;
-            sessionId: string;
+            sessionId?: string;
         }>, signal: AbortSignal) => Promise<void>;
         open: (agentId: string, signal: AbortSignal) => Promise<Readonly<{
             agent: import("@fungi.computer/shiitake").ShiitakeAgent;

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

@@ -1,13 +1,23 @@
 export declare class LocalBwrapUnavailable extends Error {
-    readonly reason: "missing" | "invalid-digest" | "digest-mismatch" | "not-executable";
+    readonly reason: "install";
     readonly name = "LocalBwrapUnavailable";
-    constructor(reason: "missing" | "invalid-digest" | "digest-mismatch" | "not-executable", message: string, options?: ErrorOptions);
+    constructor(reason: "install", message: string, options?: ErrorOptions);
 }
 export type LinuxSandboxPayload = {
-    readonly executable: string;
-    readonly seccompFilter: Uint8Array;
+    readonly sourcePath: string;
+    readonly executableBytes: Uint8Array;
+    readonly seccomp: Uint8Array;
+    readonly seccompWorkspace: Uint8Array;
 };
-/** Check both packaged artifacts on every use; never cache verification. */
-export declare function verifyLocalLinuxSandboxPayload(executable: string): LinuxSandboxPayload;
+export type LinuxSandboxDigests = Readonly<{
+    bwrap: string;
+    seccomp: string;
+    seccompWorkspace: string;
+}>;
+/** Packaged patch has no sidecar; the built module owns its digest. */
+export type NativeSourceReader = (path: string) => Buffer;
+export declare function verifiedNativePatchHelper(path: string, project: string, readNativeSource?: NativeSourceReader): Uint8Array;
+/** Verify the three packaged Linux files once before copying into service-owned staging. */
+export declare function verifyLocalLinuxSandboxPayload(executable: string, project: string, expected: LinuxSandboxDigests, readNativeSource?: NativeSourceReader): LinuxSandboxPayload;
 /** Same optional native-package lookup as apply_patch, with no PATH fallback. */
-export declare function localLinuxSandboxPayload(): LinuxSandboxPayload;
+export declare function localLinuxSandboxPayload(project: string, readNativeSource?: NativeSourceReader): LinuxSandboxPayload;

package/dist/private-local-bwrap.js

@@ -1,13 +1,10 @@
 import { createHash } from "node:crypto";
-import { accessSync, constants, readFileSync, statSync } from "node:fs";
+import { lstatSync, 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);
+import { nativeDigests } from "./private-local-native-digests.js";
+import { assertHostOwnedNativeFile, UnsafeNativePayload, } from "./private-local-sandbox-policy.js";
 export class LocalBwrapUnavailable extends Error {
     reason;
     name = "LocalBwrapUnavailable";
@@ -16,55 +13,98 @@ export class LocalBwrapUnavailable extends Error {
         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 });
-    }
+export function verifiedNativePatchHelper(path, project, readNativeSource = readFileSync) {
+    const expected = nativeDigests[`${process.platform}-${process.arch}`]?.patch;
+    if (expected === undefined)
+        throw new LocalBwrapUnavailable("install", "No built native patch digest for this platform; reinstall Fungi.");
+    return verifiedBytes(path, "fungi-apply-patch", project, expected, readNativeSource);
+}
+/** Verify the three packaged Linux files once before copying into service-owned staging. */
+export function verifyLocalLinuxSandboxPayload(executable, project, expected, readNativeSource = readFileSync) {
+    const executableBytes = verifiedBytes(executable, "fungi-bwrap", project, expected.bwrap, readNativeSource);
     return {
-        executable,
-        seccompFilter: verifiedBytes(join(dirname(executable), "fungi-seccomp.bpf"), "fungi-seccomp.bpf"),
+        sourcePath: executable,
+        executableBytes,
+        seccomp: verifiedBytes(join(dirname(executable), "fungi-seccomp.bpf"), "fungi-seccomp.bpf", project, expected.seccomp, readNativeSource),
+        seccompWorkspace: verifiedBytes(join(dirname(executable), "fungi-seccomp-workspace.bpf"), "fungi-seccomp-workspace.bpf", project, expected.seccompWorkspace, readNativeSource),
     };
 }
-function verifiedBytes(path, label) {
+function verifiedBytes(path, label, project, expected, readNativeSource = readFileSync) {
     let bytes;
-    let digest;
     try {
+        assertHostOwnedNativeFile(project, path);
         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");
+            throw new LocalBwrapUnavailable("install", `Packaged ${label} is not a regular file; reinstall Fungi.`);
+        bytes = readNativeSource(path);
     }
     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;
+            throw new LocalBwrapUnavailable("install", `Packaged ${label} is missing; reinstall Fungi with optional dependencies enabled.`, { cause });
+        if (cause instanceof UnsafeNativePayload ||
+            cause instanceof LocalBwrapUnavailable)
+            throw cause;
+        throw new LocalBwrapUnavailable("install", `Packaged ${label} cannot be read; reinstall Fungi. No command was started.`, { 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.`);
+    if (createHash("sha256").update(bytes).digest("hex") !== expected)
+        throw new LocalBwrapUnavailable("install", `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() {
+export function localLinuxSandboxPayload(project, readNativeSource = readFileSync) {
+    const digest = nativeDigests[`${process.platform}-${process.arch}`];
+    if (digest?.bwrap === undefined ||
+        digest.seccomp === undefined ||
+        digest.seccompWorkspace === undefined)
+        throw new LocalBwrapUnavailable("install", "No built native Linux payload digest for this platform; reinstall Fungi.");
     let executable;
     if (process.env.FUNGI_BUNDLED_CLI) {
         const name = `@fungi.computer/spore-native-${process.platform}-${process.arch}`;
+        const message = `Packaged ${name}/bin/fungi-bwrap cannot be read; reinstall Fungi.`;
+        let directories;
+        try {
+            directories = createRequire(process.env.FUNGI_BUNDLED_CLI).resolve.paths(name);
+        }
+        catch (cause) {
+            throw new LocalBwrapUnavailable("install", message, { cause });
+        }
+        if (directories === null)
+            throw new LocalBwrapUnavailable("install", message);
+        let packageRoot;
+        for (const directory of directories) {
+            const candidate = join(directory, name);
+            try {
+                if (lstatSync(candidate, { throwIfNoEntry: false }) !== undefined) {
+                    packageRoot = candidate;
+                    break;
+                }
+            }
+            catch (cause) {
+                throw new LocalBwrapUnavailable("install", message, { cause });
+            }
+        }
+        if (packageRoot === undefined)
+            throw new LocalBwrapUnavailable("install", `Missing ${name}; reinstall Fungi with optional dependencies enabled.`);
+        // Package metadata (including exports) is not an authority for whether
+        // native bytes are absent. Check the package's location before its bin.
         try {
-            executable = createRequire(process.env.FUNGI_BUNDLED_CLI).resolve(`${name}/bin/fungi-bwrap`);
+            assertHostOwnedNativeFile(project, packageRoot);
+            if (!statSync(packageRoot).isDirectory())
+                throw new LocalBwrapUnavailable("install", message);
         }
         catch (cause) {
-            throw new LocalBwrapUnavailable("missing", `Missing ${name}/bin/fungi-bwrap; reinstall Fungi with optional dependencies enabled.`, { cause });
+            if (cause instanceof UnsafeNativePayload ||
+                cause instanceof LocalBwrapUnavailable)
+                throw cause;
+            throw new LocalBwrapUnavailable("install", message, { cause });
         }
+        executable = join(packageRoot, "bin", "fungi-bwrap");
     }
     else {
         executable = fileURLToPath(new URL("../native/bin/fungi-bwrap", import.meta.url));
     }
-    return verifyLocalLinuxSandboxPayload(executable);
+    return verifyLocalLinuxSandboxPayload(executable, project, {
+        bwrap: digest.bwrap,
+        seccomp: digest.seccomp,
+        seccompWorkspace: digest.seccompWorkspace,
+    }, readNativeSource);
 }

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

@@ -128,11 +128,17 @@ export declare function createPrivateLocalComputerProcesses(root: string, home?:
  */
 export declare const backgroundExecInput: z.ZodUnion<readonly [z.ZodObject<{
     operation: z.ZodLiteral<"start">;
+    escape: z.ZodOptional<z.ZodObject<{
+        justification: z.ZodString;
+    }, z.core.$strict>>;
     command: z.ZodString;
     stdin: z.ZodOptional<z.ZodString>;
     cwd: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>, z.ZodObject<{
     operation: z.ZodLiteral<"start">;
+    escape: z.ZodOptional<z.ZodObject<{
+        justification: z.ZodString;
+    }, z.core.$strict>>;
     executable: z.ZodString;
     args: z.ZodDefault<z.ZodArray<z.ZodString>>;
     stdin: z.ZodOptional<z.ZodString>;
@@ -178,6 +184,15 @@ export declare const backgroundExecOutput: z.ZodUnion<readonly [z.ZodObject<{
     complete: z.ZodBoolean;
     timedOut: z.ZodBoolean;
     signalled: z.ZodOptional<z.ZodBoolean>;
+    sandbox: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            "read-only": "read-only";
+            workspace: "workspace";
+            "full-access": "full-access";
+        }>;
+        likelyDenied: z.ZodBoolean;
+        ranOutsideSandbox: z.ZodBoolean;
+    }, z.core.$strict>>;
 }, z.core.$strict>, z.ZodObject<{
     processes: z.ZodArray<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>>;

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

@@ -65,6 +65,9 @@ const processSchema = z.strictObject({
 /** The intentional shell form of background `start`. */
 const shellStartInput = z.strictObject({
     operation: z.literal("start"),
+    escape: z
+        .strictObject({ justification: z.string().min(1).max(2048) })
+        .optional(),
     command: z.string().min(1).max(maximumLaunchTextLength),
     stdin: launchStdinSchema.optional(),
     cwd: launchCwdSchema.optional(),
@@ -73,6 +76,9 @@ const shellStartInput = z.strictObject({
 const directStartInput = z
     .strictObject({
     operation: z.literal("start"),
+    escape: z
+        .strictObject({ justification: z.string().min(1).max(2048) })
+        .optional(),
     executable: z.string().min(1),
     args: z.array(z.string()).default([]),
     stdin: launchStdinSchema.optional(),
@@ -573,6 +579,13 @@ export const backgroundExecInput = z.union([
 const backgroundResult = readOutput.extend({
     timedOut: z.boolean(),
     signalled: z.boolean().optional(),
+    sandbox: z
+        .strictObject({
+        mode: z.enum(["full-access", "workspace", "read-only"]),
+        likelyDenied: z.boolean(),
+        ranOutsideSandbox: z.boolean(),
+    })
+        .optional(),
 });
 export const backgroundExecOutput = z.union([backgroundResult, listOutput]);
 /** Reuse Session ownership and logs; a wait deadline never cancels the command. */

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

@@ -1,13 +1,12 @@
+import { type NativePayloadStaging } from "./private-local-native-staging.js";
 import { z } from "zod";
+import type { LocalPermissionMode } from "./private-local-permission-mode.js";
 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";
+        install: "install";
+        unsupported: "unsupported";
+        folder: "folder";
+        "startup-refused": "startup-refused";
     }>;
     message: z.ZodString;
 }, z.core.$strict>;
@@ -22,13 +21,14 @@ export type SandboxCommand = Readonly<{
     args: readonly string[];
     environment: Readonly<{
         TMPDIR: string;
+        SSH_AUTH_SOCK?: 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;
+    command(cwd: string, argv: readonly [string, ...string[]], readOnlyHelperFile?: string): SandboxCommand;
     close(): void;
 }>;
 export type SandboxAdmission = Readonly<{
@@ -38,6 +38,7 @@ export type SandboxAdmission = Readonly<{
     state: "unavailable";
     reason: SandboxUnavailableReason;
 }>;
+export declare function sandboxUnavailableReason(cause: unknown): 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.
@@ -47,5 +48,14 @@ export declare function establishLocalSandbox(input: Readonly<{
     project: string;
     /** Absolute folder selected by the Local owner. */
     folder: string;
+    mode: Exclude<LocalPermissionMode, "full-access">;
+    temporaryDirectory: string;
     platform?: string;
+}>, staging?: NativePayloadStaging, 
+/** Host startup probe; a Linux command-generation test can supply its own runner. */
+runProbe?: (command: SandboxCommand) => Readonly<{
+    status: number | null;
+    stderr: string;
+    signal: string | null;
+    error?: Error;
 }>): SandboxAdmission;

package/dist/private-local-containment.js

@@ -1,22 +1,14 @@
 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 { closeSync, openSync, realpathSync } from "node:fs";
+import { userInfo } from "node:os";
+import { LocalBwrapUnavailable } from "./private-local-bwrap.js";
+import { createNativePayloadStaging, } from "./private-local-native-staging.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 { seatbeltCommand, UnsafeSeatbeltFolder, } from "./private-local-seatbelt.js";
+import { sandboxPolicy, linuxSandboxProfile, UnsafeGitMarker, UnsafeHostCode, UnsafeNativePayload, } 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",
-    ]),
+    kind: z.enum(["unsupported", "install", "folder", "startup-refused"]),
     message: z.string(),
 });
 export class LocalSandboxUnavailable extends Error {
@@ -27,11 +19,19 @@ export class LocalSandboxUnavailable extends Error {
         this.reason = reason;
     }
 }
-function unavailable(cause) {
+export function sandboxUnavailableReason(cause) {
+    if (cause instanceof UnsafeGitMarker)
+        return { kind: "folder", message: cause.message };
+    if (cause instanceof UnsafeSeatbeltFolder)
+        return { kind: "folder", message: cause.message };
+    if (cause instanceof UnsafeHostCode)
+        return { kind: "install", message: cause.message };
+    if (cause instanceof UnsafeNativePayload)
+        return { kind: "install", message: cause.message };
     if (cause instanceof LocalBwrapUnavailable)
         return { kind: cause.reason, message: cause.message };
     return {
-        kind: "backend-refused",
+        kind: "startup-refused",
         message: cause instanceof Error ? cause.message : "Sandbox preparation failed.",
     };
 }
@@ -40,7 +40,9 @@ function unavailable(cause) {
  * 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) {
+export function establishLocalSandbox(input, staging, 
+/** Host startup probe; a Linux command-generation test can supply its own runner. */
+runProbe) {
     try {
         sandboxPolicy(input.project, input.folder);
     }
@@ -48,7 +50,7 @@ export function establishLocalSandbox(input) {
         return {
             state: "unavailable",
             reason: {
-                kind: "invalid-folder",
+                kind: "folder",
                 message: cause instanceof Error ? cause.message : "Invalid sandbox folder.",
             },
         };
@@ -58,44 +60,66 @@ export function establishLocalSandbox(input) {
         return {
             state: "unavailable",
             reason: {
-                kind: "unsupported-platform",
-                message: `Local sandbox is unavailable on ${platform}.`,
+                kind: "unsupported",
+                message: `${input.mode === "workspace" ? "Workspace" : "Read-only"} on ${platform} needs a supported OS sandbox; use --yolo or run on macOS/Linux.`,
             },
         };
-    let temporaryDirectory;
+    let native;
     try {
-        // A sandbox owns only its own temporary directory, never the host's HOME.
-        temporaryDirectory = realpathSync(mkdtempSync(join(tmpdir(), "fungi-sandbox-")));
-        const temporary = temporaryDirectory;
+        native =
+            staging ??
+                (platform === "linux"
+                    ? createNativePayloadStaging(input.project)
+                    : undefined);
+        const environmentTmp = platform === "linux" ? "/tmp" : input.temporaryDirectory;
         let closed = false;
         const sandbox = {
-            command: (cwd, argv) => {
+            command: (cwd, argv, readOnlyHelperFile) => {
                 if (closed)
                     throw new LocalSandboxUnavailable({
-                        kind: "backend-refused",
+                        kind: "startup-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 },
+                    const profile = linuxSandboxProfile(policy, input.mode, input.temporaryDirectory, process.env, userInfo().homedir, platform);
+                    const linuxPayload = platform === "linux" ? native?.linux(profile) : undefined;
+                    const stagedHelper = readOnlyHelperFile === undefined
+                        ? undefined
+                        : native?.patch(readOnlyHelperFile);
+                    const stagedArgv = stagedHelper === undefined
+                        ? argv
+                        : [
+                            argv[0] === readOnlyHelperFile ? stagedHelper : argv[0],
+                            ...argv
+                                .slice(1)
+                                .map((argument) => argument === readOnlyHelperFile ? stagedHelper : argument),
+                        ];
+                    const launch = linuxPayload !== undefined
+                        ? linuxSandboxCommand(profile, linuxPayload, cwd, stagedArgv, undefined, stagedHelper)
+                        : seatbeltCommand(profile, stagedArgv);
+                    let environment = {
+                        TMPDIR: environmentTmp,
                     };
+                    if (platform === "linux" && profile.sshAgentSocket !== undefined)
+                        environment = {
+                            TMPDIR: environmentTmp,
+                            SSH_AUTH_SOCK: profile.sshAgentSocket,
+                        };
+                    return { ...launch, environment };
                 }
                 catch (cause) {
-                    throw new LocalSandboxUnavailable(unavailable(cause));
+                    throw new LocalSandboxUnavailable(sandboxUnavailableReason(cause));
                 }
             },
             close: () => {
                 if (closed)
                     return;
                 closed = true;
-                rmSync(temporary, { recursive: true });
+                if (staging === undefined)
+                    native?.close();
             },
         };
         const command = sandbox.command(realpathSync(input.folder), [
@@ -104,8 +128,9 @@ export function establishLocalSandbox(input) {
         let filterDescriptor;
         const probe = () => {
             if (command.seccompFilter !== undefined) {
-                const path = join(temporary, "seccomp.bpf");
-                writeFileSync(path, command.seccompFilter, { mode: 0o600 });
+                const path = native?.probeFilter(command.seccompFilter);
+                if (path === undefined)
+                    throw new Error("No Linux filter staging owner");
                 filterDescriptor = openSync(path, "r");
             }
             return spawnSync(command.executable, [...command.args], {
@@ -125,7 +150,7 @@ export function establishLocalSandbox(input) {
         };
         const result = (() => {
             try {
-                return probe();
+                return runProbe?.(command) ?? probe();
             }
             finally {
                 if (filterDescriptor !== undefined)
@@ -134,28 +159,28 @@ export function establishLocalSandbox(input) {
         })();
         if (result.status !== 0) {
             sandbox.close();
-            const stderr = result.stderr.trim();
+            const stderr = result.error === undefined ? result.stderr.trim() : "";
             return {
                 state: "unavailable",
                 reason: {
-                    kind: "backend-refused",
-                    message: result.error?.message ??
+                    kind: "startup-refused",
+                    message: `${input.mode === "workspace" ? "Workspace" : "Read-only"} on this ${platform === "darwin" ? "Mac" : "Linux host"} needs a working ${platform === "darwin" ? "sandbox-exec profile probe" : "bwrap installation"}; use --yolo or ${platform === "darwin" ? "check the failed Seatbelt profile probe" : "fix the sandbox installation"}. ${result.error?.message ??
                         (stderr.length > 0
                             ? stderr
-                            : `Sandbox startup exited ${String(result.status)} (${String(result.signal)}).`),
+                            : `Sandbox startup exited ${String(result.status)} (${String(result.signal)}).`)}`,
                 },
             };
         }
         return { state: "ready", sandbox };
     }
     catch (cause) {
-        if (temporaryDirectory !== undefined)
-            rmSync(temporaryDirectory, { recursive: true });
+        if (staging === undefined)
+            native?.close();
         return {
             state: "unavailable",
             reason: cause instanceof LocalSandboxUnavailable
                 ? cause.reason
-                : unavailable(cause),
+                : sandboxUnavailableReason(cause),
         };
     }
 }

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

@@ -1,5 +1,5 @@
 import type { BirdDogMail } from "@fungi.computer/bird-dog";
-import type { Accepted, CancelResult, CommandSettlement, VerifiedAgentReply } from "@fungi.computer/shiitake";
+import type { Accepted, CancelResult, CommandSettlement, DelegationReceipt, VerifiedAgentReply } from "@fungi.computer/shiitake";
 import type { AgentControlDirectory, AgentDelegationInput, AgentDelegationInvocation, AgentRecallInput } from "@fungi.computer/shiitake/agent-control";
 import { createFleetDelegation } from "@fungi.computer/shiitake/fleet";
 /**
@@ -8,7 +8,7 @@ import { createFleetDelegation } from "@fungi.computer/shiitake/fleet";
  * owner when it is idle; `readSettlement` reads one exact command there.
  */
 export type PrivateLocalMailRouting = Readonly<{
-    deliver: (mail: BirdDogMail) => Promise<Accepted>;
+    deliver: (mail: BirdDogMail) => Promise<DelegationReceipt>;
     readSettlement: (agentId: string, sessionId: string, commandId: string) => Promise<CommandSettlement | undefined>;
 }>;
 /**
@@ -29,7 +29,7 @@ export declare function createPrivateLocalDelegation(input: Readonly<{
     }[] | undefined>) | undefined;
     accept: (mail: BirdDogMail, meta?: BirdDogMail["meta"], reply?: VerifiedAgentReply) => Promise<Accepted>;
 }>): {
-    send: (task: AgentDelegationInput, sourceSessionId: string, signal: AbortSignal, invocation?: AgentDelegationInvocation) => Promise<Accepted>;
+    send: (task: AgentDelegationInput, sourceSessionId: string, signal: AbortSignal, invocation?: AgentDelegationInvocation) => Promise<DelegationReceipt>;
     recall: (task: AgentRecallInput, sourceSessionId: string, signal: AbortSignal) => Promise<CancelResult>;
     receive: (mail: BirdDogMail) => Promise<Accepted>;
     outstanding: () => Promise<import("@fungi.computer/shiitake/fleet").OutstandingDelegation | undefined>;