@fungi.computer/truffle 0.2.1 → 0.3.0

package/dist/private-local-sandbox-policy.d.ts

@@ -8,14 +8,54 @@ export declare function resolveAgentFolder(project: string, folder: string): {
 };
 /** Containment authority, not an approval setting or an execution mode. */
 export type LocalSandboxPolicy = Readonly<{
+    projectRoot: string;
     writableRoot: string;
+    /** Whole Git administration and Agent state, read-only in Workspace. */
     readOnly: readonly string[];
-    immovable: readonly string[];
 }>;
-/** One logical/resolved authority for Files, bwrap and Seatbelt. */
-export declare function protectedSandboxPaths(paths: readonly string[]): string[];
+/** The host, never project configuration, chooses every writable cache grant. */
+export type LinuxSandboxProfile = LocalSandboxPolicy & Readonly<{
+    mode: "workspace" | "read-only";
+    writable: readonly string[];
+    hidden: readonly string[];
+    temporaryDirectory: string;
+    /** Host-selected cache carve-out to prepare before rendering bwrap mounts. */
+    fungiCache: string | undefined;
+    sshAgentSocket: string | undefined;
+    sshAgentMask: string | undefined;
+}>;
+export declare function linuxSandboxProfile(policy: LocalSandboxPolicy, mode: "workspace" | "read-only", temporaryDirectory: string, host: NodeJS.ProcessEnv, 
+/** Pass the real passwd home in production; fixtures supply their own. */
+osHome: string, platform?: "linux" | "darwin"): LinuxSandboxProfile;
+/** Private persistent Agent temp, not the staging directory or host /tmp. */
+export declare function agentSandboxTemporaryDirectory(agentId: string, project: string): string;
+export declare class UnsafeNativePayload extends Error {
+    readonly name = "UnsafeNativePayload";
+}
+export declare class UnsafeHostCode extends Error {
+    readonly name = "UnsafeHostCode";
+}
+/** A symlinked Git marker cannot be protected by a bind on its logical name. */
+export declare class UnsafeGitMarker extends Error {
+    readonly name = "UnsafeGitMarker";
+}
 /**
- * Recompute for every command: the previous command may have initialized Git.
- * An internal caller may tighten the directory budget, never widen the ceiling.
+ * Packed CLI identity is supplied by the Node bin wrapper, which loaded both
+ * paths before spawning Bun. This is an admission check, not an integrity
+ * check on JS that might already have been rewritten.
  */
-export declare function sandboxPolicy(project: string, folder: string, directoryLimit?: number): LocalSandboxPolicy;
+export declare function assertHostCodeOutsideAgent(project: string, cli: string, launcher: string): void;
+/** Refuse both logical and resolved native source locations in the whole
+ * Agent project or Git administration before verifying source bytes. */
+export declare function assertHostOwnedNativeFile(project: string, path: string): void;
+/** One logical/resolved authority for Files, bwrap and Seatbelt. */
+export declare function protectedSandboxPaths(paths: readonly string[]): string[];
+/** Git owns the representation of the selected folder's worktree and common dir. */
+export declare function gitDirectories(project: string, root: string, path?: string): {
+    common: string;
+    worktree: string;
+} | undefined;
+/** Remote names from the protected common config only, never a racy worktree path. */
+export declare function protectedGitRemoteNames(project: string, common: string, path: string): ReadonlySet<string> | undefined;
+/** Recompute for each command: the prior command may have initialized Git. */
+export declare function sandboxPolicy(project: string, folder: string): LocalSandboxPolicy;

package/dist/private-local-sandbox-policy.js

@@ -1,4 +1,7 @@
-import { lstatSync, readdirSync, realpathSync } from "node:fs";
+import { isUtf8 } from "node:buffer";
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, lstatSync, mkdirSync, realpathSync, statSync, } from "node:fs";
+import { userInfo } from "node:os";
 import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep, } from "node:path";
 import { z } from "zod";
 /** Retained POSIX folder grammar; no separate safe/YOLO representation. */
@@ -17,10 +20,198 @@ export function resolveAgentFolder(project, folder) {
     const within = relative(root, absolute);
     if (isAbsolute(within) || within === ".." || within.startsWith(`..${sep}`))
         throw new Error("Agent folder resolves outside the project");
+    if (within === ".fungi" || within.startsWith(`.fungi${sep}`))
+        throw new Error("Agent folder cannot be inside protected project .fungi");
     if (!lstatSync(absolute).isDirectory())
         throw new Error("Agent folder must be a directory");
     return { folder: within.split(sep).join("/") || ".", absolute };
 }
+function existingDirectory(path) {
+    if (!isAbsolute(path))
+        return [];
+    try {
+        return statSync(path).isDirectory() ? [realpathSync(path)] : [];
+    }
+    catch (cause) {
+        if (unreadableEntry(cause))
+            return [];
+        throw cause;
+    }
+}
+function covers(root, path) {
+    return within(root, path);
+}
+export function linuxSandboxProfile(policy, mode, temporaryDirectory, host, 
+/** Pass the real passwd home in production; fixtures supply their own. */
+osHome, platform = "linux") {
+    const home = host.HOME ?? osHome;
+    if (!isAbsolute(home))
+        throw new Error("Sandbox HOME must be absolute");
+    if (!isAbsolute(osHome))
+        throw new Error("Sandbox OS home must be absolute");
+    const cache = host.XDG_CACHE_HOME ?? join(home, ".cache");
+    const data = host.XDG_DATA_HOME ?? join(home, ".local", "share");
+    const cargo = host.CARGO_HOME ?? join(home, ".cargo");
+    const caches = [
+        cache,
+        join(home, ".npm"),
+        join(host.PNPM_HOME ?? join(data, "pnpm"), "store"),
+        join(home, ".bun", "install", "cache"),
+        join(cargo, "registry"),
+        join(cargo, "git"),
+        host.GOMODCACHE ?? join(home, "go", "pkg", "mod"),
+        host.GOCACHE ?? join(cache, "go-build"),
+    ];
+    const socket = host.SSH_AUTH_SOCK;
+    const selectedSocket = socket &&
+        isAbsolute(socket) &&
+        statSync(socket, { throwIfNoEntry: false })?.isSocket()
+        ? socket
+        : undefined;
+    const writableCaches = [...new Set(caches.flatMap(existingDirectory))].filter((path) => !covers(path, join(home, ".cargo", "bin")) &&
+        !covers(path, join(home, ".local", "bin")));
+    const fungiCache = canonicalPath(join(cache, "fungi"));
+    const protectedFungiCache = mode === "workspace" &&
+        writableCaches.some((path) => covers(path, fungiCache))
+        ? fungiCache
+        : undefined;
+    // A previous service can leave fallback Agent temp behind even when this
+    // Agent has moved to XDG_RUNTIME_DIR. Never expose either host candidate.
+    const fallbackTemporaryBases = [
+        ...new Set([home, osHome]
+            .map((root) => join(root, ".cache", "fungi", "tmp"))
+            .flatMap(existingDirectory)),
+    ];
+    return {
+        ...policy,
+        readOnly: protectedFungiCache === undefined
+            ? policy.readOnly
+            : [...policy.readOnly, protectedFungiCache],
+        mode,
+        temporaryDirectory,
+        fungiCache: protectedFungiCache,
+        writable: mode === "workspace"
+            ? [...new Set([policy.writableRoot, ...writableCaches])]
+            : [],
+        hidden: [
+            join(home, ".config", "fungi"),
+            join(home, ".fungi", "service"),
+            // Linux mounts a private tmpfs over siblings after re-binding our temp.
+            // Seatbelt's path denial would also hide the Agent's own fallback temp.
+            ...(platform === "linux" ? fallbackTemporaryBases : []),
+        ],
+        sshAgentSocket: mode === "workspace" ? selectedSocket : undefined,
+        sshAgentMask: mode === "read-only" ? selectedSocket : undefined,
+    };
+}
+/** Private persistent Agent temp, not the staging directory or host /tmp. */
+export function agentSandboxTemporaryDirectory(agentId, project) {
+    if (!/^[a-zA-Z0-9_-]+$/.test(agentId))
+        throw new Error("Invalid Local Agent ID for temporary directory");
+    const home = userInfo().homedir;
+    const runtime = process.env.XDG_RUNTIME_DIR;
+    const base = runtime && isAbsolute(runtime)
+        ? join(runtime, "fungi", "tmp")
+        : join(home, ".cache", "fungi", "tmp");
+    const projectRoot = realpathSync(project);
+    if ([resolve(base), canonicalPath(base)].some((path) => within(projectRoot, path) || inGitAdministration(path)))
+        throw new Error("Agent temporary directory cannot live in the Agent project or Git administration");
+    mkdirSync(base, { recursive: true, mode: 0o700 });
+    const directory = join(base, agentId);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    if (within(projectRoot, realpathSync(directory)))
+        throw new Error("Agent temporary directory resolved into the Agent project");
+    const metadata = lstatSync(directory);
+    if (!metadata.isDirectory() ||
+        metadata.isSymbolicLink() ||
+        metadata.uid !== process.getuid?.() ||
+        (metadata.mode & 0o077) !== 0)
+        throw new Error("Local Agent temporary directory must be private");
+    return realpathSync(directory);
+}
+export class UnsafeNativePayload extends Error {
+    name = "UnsafeNativePayload";
+}
+export class UnsafeHostCode extends Error {
+    name = "UnsafeHostCode";
+}
+/** A symlinked Git marker cannot be protected by a bind on its logical name. */
+export class UnsafeGitMarker extends Error {
+    name = "UnsafeGitMarker";
+}
+function within(root, path) {
+    const remainder = relative(root, path);
+    return (!isAbsolute(remainder) &&
+        remainder !== ".." &&
+        !remainder.startsWith(`..${sep}`));
+}
+function inGitAdministration(path) {
+    for (let directory = dirname(path);; directory = dirname(directory)) {
+        if (basename(directory) === ".git" ||
+            (lstatSync(join(directory, "HEAD"), {
+                throwIfNoEntry: false,
+            })?.isFile() &&
+                (lstatSync(join(directory, "objects"), {
+                    throwIfNoEntry: false,
+                })?.isDirectory() ||
+                    lstatSync(join(directory, "commondir"), {
+                        throwIfNoEntry: false,
+                    })?.isFile())))
+            return true;
+        if (directory === dirname(directory))
+            return false;
+    }
+}
+/**
+ * Packed CLI identity is supplied by the Node bin wrapper, which loaded both
+ * paths before spawning Bun. This is an admission check, not an integrity
+ * check on JS that might already have been rewritten.
+ */
+export function assertHostCodeOutsideAgent(project, cli, launcher) {
+    const root = realpathSync(project);
+    const paths = [
+        cli,
+        launcher,
+        dirname(cli),
+        dirname(dirname(cli)),
+        dirname(launcher),
+        dirname(dirname(launcher)),
+    ];
+    for (const path of paths) {
+        try {
+            const logical = resolve(path);
+            const actual = realpathSync(logical);
+            if ([logical, actual].some((candidate) => within(root, candidate) || inGitAdministration(candidate)))
+                throw new UnsafeHostCode("Fungi host JavaScript is inside the Agent project or Git administration; install Fungi outside the project.");
+        }
+        catch (cause) {
+            if (cause instanceof UnsafeHostCode)
+                throw cause;
+            throw new UnsafeHostCode("Fungi host JavaScript location cannot be verified; reinstall Fungi outside the project.", { cause });
+        }
+    }
+    for (const path of [cli, launcher]) {
+        try {
+            const file = statSync(path);
+            if (!file.isFile() || file.nlink > 1)
+                throw new UnsafeHostCode("Fungi host JavaScript is not an independent file (hardlinked or not regular); use a copying install outside the project (pnpm package-import-method=copy or npm global).");
+        }
+        catch (cause) {
+            if (cause instanceof UnsafeHostCode)
+                throw cause;
+            throw new UnsafeHostCode("Fungi host JavaScript cannot be inspected; reinstall Fungi using a copying install outside the project.", { cause });
+        }
+    }
+}
+/** Refuse both logical and resolved native source locations in the whole
+ * Agent project or Git administration before verifying source bytes. */
+export function assertHostOwnedNativeFile(project, path) {
+    const logical = resolve(path);
+    const actual = realpathSync(logical);
+    const gitAdmin = (candidate) => inGitAdministration(candidate);
+    if ([logical, actual].some((candidate) => within(project, candidate) || gitAdmin(candidate)))
+        throw new UnsafeNativePayload("Packaged native payload is inside the Agent project or a Git-admin folder; reinstall Fungi outside the project.");
+}
 /** Missing reserved names resolve through their nearest existing ancestor. */
 function canonicalPath(path) {
     if (lstatSync(path, { throwIfNoEntry: false }) !== undefined)
@@ -38,84 +229,172 @@ export function protectedSandboxPaths(paths) {
         })),
     ];
 }
-// A project tree is untrusted input. Refuse incomplete discovery rather than
-// silently protecting only a prefix or allowing a bare command to bypass it.
-// Bound directory traversal, not ordinary dependency-file payloads.
-const maximumDiscoveryDirectories = 100_000;
-const discoveryDirectoryLimit = z
-    .number()
-    .int()
-    .min(1)
-    .max(maximumDiscoveryDirectories);
-function gitProtection(root, directoryLimit) {
-    const pending = [
-        { path: root, kind: "tree" },
-    ];
-    const readOnly = [];
-    const immovable = [];
-    let discoveredDirectories = 1; // The writable root itself.
-    for (let directory = pending.pop(); directory !== undefined; directory = pending.pop()) {
-        const entries = readdirSync(directory.path, { withFileTypes: true });
-        const has = (name) => entries.some((entry) => entry.name === name);
-        const git = directory.kind === "git" ||
-            basename(directory.path) === ".git" ||
-            (has("HEAD") && (has("objects") || has("commondir"))) ||
-            (directory.kind === "modules" &&
-                (has("HEAD") || has("config") || has("hooks")));
-        // A nested Git-file checkout is a repository boundary, not another copy of
-        // the selected project's payload to walk. The normal root scan owns common
-        // administration; never follow the pointer. Never prune the selected root or
-        // directories already recognized as Git administration.
-        if (directory.path !== root &&
-            !git &&
-            entries.some((entry) => entry.name === ".git" && entry.isFile())) {
-            readOnly.push(join(directory.path, ".git"));
+// One bounded host Git query per writable folder, regardless of repository size.
+const maximumGitOutputBytes = 16 * 1024;
+const gitTimeoutMilliseconds = 30_000;
+/** Host Git from absolute PATH entries; never a binary the Agent can write. */
+function hostGit(project, path, strictPath) {
+    for (const directory of path.split(":")) {
+        if (!isAbsolute(directory))
             continue;
+        const candidate = join(directory, "git");
+        try {
+            accessSync(candidate, constants.X_OK);
+            const actual = realpathSync(candidate);
+            if (!statSync(actual).isFile())
+                continue;
+            // A grant must inspect the first executable on its command PATH. For
+            // sandbox discovery, keep looking for a trusted Git instead.
+            if ([candidate, actual].some((location) => within(project, location) || inGitAdministration(location))) {
+                if (strictPath)
+                    return undefined;
+                continue;
+            }
+            return candidate;
         }
-        if (git) {
-            immovable.push(directory.path);
-            readOnly.push(join(directory.path, "hooks"), join(directory.path, "config"), join(directory.path, "config.worktree"));
-        }
-        for (const entry of entries) {
-            const path = join(directory.path, entry.name);
-            if (entry.name === ".git" && !entry.isDirectory())
-                readOnly.push(path); // Never parse a Git pointer or grant an external dir.
-            if (!entry.isDirectory())
-                continue; // No symlink cycles or outside walks.
-            discoveredDirectories += 1;
-            if (discoveredDirectories > directoryLimit)
-                throw new Error(`Sandbox Git discovery exceeds ${String(directoryLimit)} directories`);
-            let kind = "tree";
-            if (git && entry.name === "modules")
-                kind = "modules";
-            else if (git && entry.name === "worktrees")
-                kind = "worktrees";
-            else if (!git && directory.kind === "modules")
-                kind = "modules";
-            else if (!git && directory.kind === "worktrees")
-                kind = "git";
-            pending.push({ path, kind });
+        catch (cause) {
+            // No usable Git on this PATH entry; any other fault refuses discovery.
+            if (!unreadableEntry(cause))
+                throw cause;
         }
     }
-    return { readOnly, immovable };
+    return undefined;
 }
-/**
- * Recompute for every command: the previous command may have initialized Git.
- * An internal caller may tighten the directory budget, never widen the ceiling.
- */
-export function sandboxPolicy(project, folder, directoryLimit = maximumDiscoveryDirectories) {
-    const limit = discoveryDirectoryLimit.parse(directoryLimit);
+function gitEnvironment() {
+    const environment = {};
+    for (const [name, value] of Object.entries(process.env))
+        if (!name.startsWith("GIT_"))
+            environment[name] = value;
+    return { ...environment, GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0" };
+}
+/** Missing, denied or looping PATH entry; never a reason to grant a Git path. */
+function unreadableEntry(cause) {
+    if (!(cause instanceof Error) || !("code" in cause))
+        return false;
+    switch (cause.code) {
+        case "ENOENT":
+        case "ENOTDIR":
+        case "ELOOP":
+        case "EACCES":
+        case "EISDIR":
+            return true;
+        default:
+            return false;
+    }
+}
+/** Git owns the representation of the selected folder's worktree and common dir. */
+export function gitDirectories(project, root, path) {
+    const git = hostGit(project, path ?? process.env.PATH ?? "", path !== undefined);
+    if (git === undefined)
+        return undefined;
+    // Configuration may be Agent-authored: no fsmonitor process, untracked
+    // cache, pager, inherited GIT_* override, or index write on the host.
+    const result = spawnSync(git, [
+        "--no-pager",
+        "-c",
+        "core.fsmonitor=false",
+        "-c",
+        "core.untrackedCache=false",
+        "-C",
+        root,
+        "rev-parse",
+        "--absolute-git-dir",
+        "--git-common-dir",
+    ], {
+        cwd: root,
+        env: gitEnvironment(),
+        maxBuffer: maximumGitOutputBytes,
+        timeout: gitTimeoutMilliseconds,
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+    if (result.error !== undefined ||
+        result.status !== 0 ||
+        !isUtf8(result.stdout))
+        return undefined;
+    // A newline in a reported path is ambiguous in rev-parse's line protocol;
+    // do not turn any partial answer into an external writable grant.
+    const locations = result.stdout.toString("utf8").split("\n");
+    if (locations.length !== 3 || locations[2] !== "")
+        return undefined;
+    const [gitDir, commonDir] = locations;
+    if (gitDir === undefined || !isAbsolute(gitDir) || !commonDir)
+        return undefined;
+    try {
+        const worktree = realpathSync(gitDir);
+        const common = realpathSync(resolve(root, commonDir));
+        if (!statSync(worktree).isDirectory() || !statSync(common).isDirectory())
+            return undefined;
+        return { common, worktree };
+    }
+    catch (cause) {
+        if (unreadableEntry(cause))
+            return undefined;
+        throw cause;
+    }
+}
+/** Remote names from the protected common config only, never a racy worktree path. */
+export function protectedGitRemoteNames(project, common, path) {
+    const git = hostGit(project, path, true);
+    if (git === undefined)
+        return undefined;
+    const config = join(common, "config");
+    const entry = lstatSync(config, { throwIfNoEntry: false });
+    if (entry === undefined || !entry.isFile() || entry.nlink !== 1)
+        return undefined;
+    // --file plus --no-includes excludes global and Agent-writable included
+    // config. Git, not a handwritten config reader, decodes its own format.
+    const result = spawnSync(git, [
+        "config",
+        "--no-includes",
+        "--file",
+        config,
+        "--null",
+        "--name-only",
+        "--get-regexp",
+        "^remote\\..*\\.url$",
+    ], {
+        cwd: project,
+        env: gitEnvironment(),
+        maxBuffer: maximumGitOutputBytes,
+        timeout: gitTimeoutMilliseconds,
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+    if (result.error !== undefined || !isUtf8(result.stdout))
+        return undefined;
+    if (result.status === 1 && result.stdout.length === 0)
+        return new Set();
+    if (result.status !== 0 || result.stdout.at(-1) !== 0)
+        return undefined;
+    const names = new Set();
+    for (const key of result.stdout.toString("utf8").slice(0, -1).split("\0")) {
+        const name = /^remote\.([A-Za-z][A-Za-z0-9_.-]*)\.url$/u.exec(key)?.[1];
+        if (name !== undefined)
+            names.add(name);
+    }
+    return names;
+}
+/** Recompute for each command: the prior command may have initialized Git. */
+export function sandboxPolicy(project, folder) {
     const root = realpathSync(project);
     const writableRoot = realpathSync(folder);
-    const within = relative(root, writableRoot);
-    if (isAbsolute(within) || within === ".." || within.startsWith(`..${sep}`))
+    const remainder = relative(root, writableRoot);
+    if (isAbsolute(remainder) ||
+        remainder === ".." ||
+        remainder.startsWith(`..${sep}`))
         throw new Error("Sandbox folder resolves outside the project.");
     if (!lstatSync(writableRoot).isDirectory())
         throw new Error("Sandbox folder must be a directory.");
-    const git = gitProtection(writableRoot, limit);
-    return {
-        writableRoot,
-        readOnly: [join(writableRoot, ".fungi"), ...git.readOnly],
-        immovable: git.immovable,
-    };
+    // Do not create a marker on the host for an absent .git.
+    const marker = join(writableRoot, ".git");
+    const readOnly = [join(writableRoot, ".fungi")];
+    const markerEntry = lstatSync(marker, { throwIfNoEntry: false });
+    if (markerEntry === undefined)
+        return { projectRoot: root, writableRoot, readOnly };
+    if (markerEntry.isSymbolicLink())
+        throw new UnsafeGitMarker(`Agent folder ${marker} is a symlink. Remove the .git symlink or select a different Agent folder before running sandboxed commands.`);
+    readOnly.push(marker);
+    const git = gitDirectories(root, writableRoot);
+    if (git !== undefined)
+        readOnly.push(git.worktree, git.common);
+    return { projectRoot: root, writableRoot, readOnly: [...new Set(readOnly)] };
 }

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

@@ -1,37 +1,53 @@
+import type { NativeSourceReader } from "./private-local-bwrap.js";
 import { z } from "zod";
+import { sandboxUnavailableReasonSchema, type SandboxUnavailableReason } from "./private-local-containment.js";
+import type { LocalPermissionMode } from "./private-local-permission-mode.js";
 import type { LocalSandboxWrites } from "./private-invocation-files.js";
+import type { NativePayloadStaging } from "./private-local-native-staging.js";
 /** Availability is not a hostile-program security or an approval status. */
-export declare const sandboxStatusSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    state: z.ZodLiteral<"available">;
-    requireSandbox: z.ZodBoolean;
-}, z.core.$strict>, z.ZodObject<{
-    state: z.ZodLiteral<"unavailable">;
-    requireSandbox: z.ZodBoolean;
-    reason: z.ZodObject<{
+export declare const sandboxStatusSchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        "read-only": "read-only";
+        workspace: "workspace";
+        "full-access": "full-access";
+    }>;
+    available: z.ZodBoolean;
+    reason: z.ZodOptional<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>;
-}, z.core.$strict>], "state">;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 export type LocalSandboxStatus = z.output<typeof sandboxStatusSchema>;
 export type LocalSandboxControls = LocalSandboxWrites & Readonly<{
     assertReady(): void;
+    assertModeReady(mode: LocalPermissionMode): void;
     status(): LocalSandboxStatus;
     close(): void;
 }>;
+/** Refusal before an Agent Files write can be staged or dispatched. */
+export declare class ProtectedLocalFilesPath extends Error {
+    readonly path: string;
+    readonly name = "ProtectedLocalFilesPath";
+    constructor(path: string);
+}
 /**
- * Native Local owns the live requirement; the adapter owns only preparation.
+ * Native Local owns the live mode; the adapter owns only preparation.
  * Every consumer calls this authority immediately before launching or writing.
  */
 export declare function createLocalSandboxControls(input: Readonly<{
     project: string;
     folder: string;
-    required(): boolean;
+    agentId?: string;
+    mode(): LocalPermissionMode;
+    defaultReason?: z.output<typeof sandboxUnavailableReasonSchema> | undefined;
+    platform?: string;
+    readNativePatchSource?: NativeSourceReader;
+    native?: NativePayloadStaging | undefined;
 }>): LocalSandboxControls;
+/** Probe a fresh Agent before deciding its mode; never treat an unavailable backend as a sandboxed run. */
+export declare function probeLocalSandbox(project: string, folder: string, native?: NativePayloadStaging): SandboxUnavailableReason | undefined;