@fungi.computer/truffle 0.2.2 → 0.3.0

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

@@ -1,25 +1,25 @@
-import { existsSync, mkdirSync, realpathSync, statSync, writeFileSync, } from "node:fs";
-import { isAbsolute, join } from "node:path";
+import { existsSync, mkdirSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, sep } from "node:path";
 import { protectedSandboxPaths, } from "./private-local-sandbox-policy.js";
 /** Ordinary upstream bwrap argv. There is no approval or bare-command path. */
 export function linuxSandboxCommand(policy, payload, cwd, argv, host = process.env, readOnlyHelperFile) {
     const root = policy.writableRoot;
     // Bind sources must exist. Only the trusted host prepares the reserved paths.
     mkdirSync(join(root, ".fungi"), { recursive: true });
-    const reserved = new Set(policy.readOnly);
-    for (const git of policy.immovable) {
-        if (reserved.has(join(git, "hooks")))
-            mkdirSync(join(git, "hooks"), { recursive: true });
-        for (const config of ["config", "config.worktree"])
-            if (reserved.has(join(git, config)) && !existsSync(join(git, config)))
-                writeFileSync(join(git, config), "", { flag: "wx" });
-        // Git reads a present commondir and rejects an empty one; "." names the
-        // Git directory itself, which is what an absent commondir means.
-        if (!existsSync(join(git, "commondir")))
-            writeFileSync(join(git, "commondir"), ".", { flag: "wx" });
-    }
+    // A missing carve-out would be skipped by the existing-path ro-bind loop,
+    // allowing Workspace to seed self-attested native-patch cache receipts.
+    if (policy.fungiCache !== undefined)
+        mkdirSync(policy.fungiCache, { recursive: true, mode: 0o700 });
     const args = [
-        "--unshare-all",
+        ...(policy.mode === "read-only"
+            ? ["--unshare-all"]
+            : [
+                "--unshare-user",
+                "--unshare-pid",
+                "--unshare-ipc",
+                "--unshare-uts",
+                "--unshare-cgroup-try",
+            ]),
         "--die-with-parent",
         "--new-session",
         "--seccomp",
@@ -28,27 +28,43 @@ export function linuxSandboxCommand(policy, payload, cwd, argv, host = process.e
         "/",
         "/",
         // Private system mounts precede the folder bind so /tmp projects survive.
-        "--tmpfs",
+        "--bind",
+        policy.temporaryDirectory,
         "/tmp",
         "--tmpfs",
         "/run",
+        ...(existsSync("/var/run") && realpathSync("/var/run") !== "/run"
+            ? ["--tmpfs", realpathSync("/var/run")]
+            : []),
         "--dev",
         "/dev",
         "--proc",
         "/proc",
-        "--bind",
-        root,
-        root,
     ];
-    for (const path of policy.immovable)
+    // A selected folder under /tmp disappears behind the private /tmp bind.
+    // Restore it read-only for Read-only; Workspace will bind it writable below.
+    if (policy.mode === "read-only")
+        args.push("--ro-bind", root, root);
+    // System masks precede every writable grant. Git is rebound read-only after.
+    for (const path of policy.writable)
         args.push("--bind", path, path);
-    for (const path of protectedSandboxPaths(policy.readOnly))
-        args.push("--ro-bind", path, path);
-    if (existsSync("/var/run") && realpathSync("/var/run") !== "/run")
-        args.push("--tmpfs", realpathSync("/var/run"));
+    // External Git metadata is never a writable grant. Missing paths do not
+    // become host-side bwrap mountpoints.
+    if (policy.mode === "workspace")
+        for (const path of protectedSandboxPaths(policy.readOnly))
+            if (existsSync(path))
+                args.push("--ro-bind", path, path);
     const runtime = host.XDG_RUNTIME_DIR;
     if (runtime && isAbsolute(runtime) && existsSync(runtime))
         args.push("--tmpfs", realpathSync(runtime));
+    // systemd's /etc/resolv.conf is often a symlink into the masked /run tree.
+    // Restore only its target file in networked Workspace, never the resolver's
+    // runtime directory or user bus.
+    if (policy.mode === "workspace" && existsSync("/etc/resolv.conf")) {
+        const resolver = realpathSync("/etc/resolv.conf");
+        if (resolver.startsWith("/run/"))
+            args.push("--ro-bind", resolver, resolver);
+    }
     // Stopgap masks, not an inventory of all possible host IPC. /run also
     // covers the usual /var/run alias. These follow folder/protected binds so
     // a selected socket inside the project is not exposed again by a later bind.
@@ -62,12 +78,23 @@ export function linuxSandboxCommand(policy, payload, cwd, argv, host = process.e
             if (existsSync(path) && statSync(path).isDirectory())
                 args.push("--tmpfs", realpathSync(path));
     }
-    const agentSocket = host.SSH_AUTH_SOCK;
-    if (agentSocket &&
-        isAbsolute(agentSocket) &&
-        existsSync(agentSocket) &&
-        statSync(agentSocket).isSocket())
-        args.push("--ro-bind", "/dev/null", realpathSync(agentSocket));
+    for (const path of policy.hidden) {
+        // Host /tmp is already replaced. An external fixture HOME beneath it has
+        // no mountpoint in the guest; restoring it would reveal host data.
+        const underTmp = relative("/tmp", path);
+        const underRoot = relative(root, path);
+        if (underTmp !== ".." &&
+            !underTmp.startsWith(`..${sep}`) &&
+            (underRoot === ".." || underRoot.startsWith(`..${sep}`)))
+            continue;
+        // Absent records cannot be read; never create a user's credential paths.
+        if (existsSync(path) && statSync(path).isDirectory())
+            args.push("--tmpfs", path);
+    }
+    if (policy.sshAgentSocket !== undefined)
+        args.push("--bind", policy.sshAgentSocket, policy.sshAgentSocket);
+    if (policy.sshAgentMask !== undefined)
+        args.push("--ro-bind", "/dev/null", policy.sshAgentMask);
     // Native Files passes its resolved helper, never an untrusted exec argv[0].
     // Re-expose only that file after private mounts; its siblings stay hidden.
     if (readOnlyHelperFile !== undefined) {
@@ -75,6 +102,12 @@ export function linuxSandboxCommand(policy, payload, cwd, argv, host = process.e
             throw new Error("Local native helper must be a regular file");
         args.push("--ro-bind", readOnlyHelperFile, readOnlyHelperFile);
     }
+    // R is a bind mount: let sandboxed Git reads discover a parent repository
+    // when the selected folder has no .git of its own.
+    args.push("--setenv", "GIT_DISCOVERY_ACROSS_FILESYSTEM", "1");
+    args.push("--setenv", "FUNGI_SANDBOX", policy.mode);
+    if (policy.mode === "read-only")
+        args.push("--setenv", "FUNGI_SANDBOX_NETWORK_DISABLED", "1");
     args.push("--chdir", cwd, "--", ...argv);
     return { ...payload, args };
 }

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

@@ -1,10 +1,10 @@
 import type { BirdDogMail } from "@fungi.computer/bird-dog";
 import { type BirdDogEffect } from "@fungi.computer/bird-dog/effect";
 import type { PrivateSqliteDatabase } from "./private-sqlite-owner.js";
-import type { Accepted } from "@fungi.computer/shiitake";
+import type { DelegationReceipt } from "@fungi.computer/shiitake";
 export type PrivateLocalMailOptions = Readonly<{
     /** Admit one reply at its addressed Agent; a rejection retries later. */
-    deliver: (mail: BirdDogMail) => Promise<Accepted>;
+    deliver: (mail: BirdDogMail) => Promise<DelegationReceipt>;
     scheduleWake?: (at: number) => void;
     now?: () => number;
 }>;

package/dist/private-local-mesh-links.d.ts

@@ -13,7 +13,10 @@ export declare const localMeshLinkKey: (record: EnrolledLocalMachine) => string;
 export declare function createLocalMeshLinks(options: {
     credentialPath: string;
     receive: (record: EnrolledLocalMachine, envelope: PostEnvelope) => Promise<PostDeliveryResult>;
-}): {
+}, timing?: Readonly<{
+    wait: (ms: number, signal: AbortSignal) => Promise<void>;
+    random: () => number;
+}>): {
     refresh: () => Promise<void>;
     isCurrent: (record: EnrolledLocalMachine) => Promise<boolean>;
     deliver: (record: EnrolledLocalMachine, envelope: PostEnvelope) => Promise<PostDeliveryResult>;

package/dist/private-local-mesh-links.js

@@ -14,7 +14,10 @@ export const localMeshLinkKey = (record) => JSON.stringify([
  * Service-owned native I/O only. The account owns pins, Carrier owns retry
  * custody, and the addressed runtime owns acceptance. No mail is queued here.
  */
-export function createLocalMeshLinks(options) {
+export function createLocalMeshLinks(options, timing = {
+    wait: (ms, signal) => delay(ms, undefined, { signal }),
+    random: Math.random,
+}) {
     const account = createLocalMachineEnrollmentAccount(options.credentialPath);
     const links = new Map();
     let stopping = false;
@@ -33,6 +36,31 @@ export function createLocalMeshLinks(options) {
             !link.stop.signal.aborted &&
             (await current(link.record)));
     }
+    // WebSocket's error event does not expose the HTTP upgrade response. A
+    // freshly signed plain GET can surface the receiver's upgrade hint. The
+    // response is NOT signed: this is diagnostic only, never authority to stop.
+    async function upgradeAdvertised(record, signal) {
+        try {
+            const url = machineLinkDialUrl(record.authority.origin, record.scopeId, record.deviceId);
+            const signer = await importSeamSigner(`${record.deviceId}:${record.privateKey}`);
+            const signature = await signSeamRequest(signer, machineLinkAudience(record.scopeId, record.deviceId), "GET", url.href, unsignedPayload);
+            const response = await fetch(url, {
+                headers: { [seamHeader]: signature },
+                signal: AbortSignal.any([signal, AbortSignal.timeout(10_000)]),
+            });
+            await response.body?.cancel();
+            return (response.status === 426 &&
+                response.headers.get("x-fungi-machine-link-action") === "upgrade fungi");
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Equal jitter avoids synchronized immediate retries even at the 15 s cap. */
+    const retryMs = (failures, random) => {
+        const ceiling = Math.min(15_000, 500 * 2 ** Math.min(failures, 5));
+        return Math.floor((ceiling * (1 + random)) / 2);
+    };
     async function connection(record, signal, publish) {
         const url = machineLinkDialUrl(record.authority.origin, record.scopeId, record.deviceId);
         const signer = await importSeamSigner(`${record.deviceId}:${record.privateKey}`);
@@ -161,21 +189,39 @@ export function createLocalMeshLinks(options) {
                     stop,
                     channel: undefined,
                     done: (async () => {
+                        let failures = 0;
+                        let upgradeNotified = false;
                         while (!stopped()) {
                             try {
                                 if (!(await current(record)))
                                     return "stopped";
                                 await connection(record, stop.signal, (channel) => {
                                     link.channel = channel;
+                                    if (channel !== undefined) {
+                                        failures = 0;
+                                        upgradeNotified = false;
+                                    }
                                 });
                             }
                             catch (cause) {
                                 if (stopped())
                                     return "stopped";
                                 logEvent("mesh-link.connection", cause);
+                                const advertised = await upgradeAdvertised(record, stop.signal);
+                                if (stopped())
+                                    return "stopped";
+                                if (advertised) {
+                                    // A forged refusal can delay a link, not permanently kill it.
+                                    // Emit once per outage and retry at the bounded cap.
+                                    if (!upgradeNotified)
+                                        console.error("upgrade fungi");
+                                    upgradeNotified = true;
+                                    failures = 5;
+                                }
                             }
                             try {
-                                await delay(1000, undefined, { signal: stop.signal });
+                                await timing.wait(retryMs(failures, timing.random()), stop.signal);
+                                failures = Math.min(failures + 1, 5);
                             }
                             catch (cause) {
                                 if (stopped())
@@ -204,7 +250,8 @@ export function createLocalMeshLinks(options) {
             const link = links.get(localMeshLinkKey(record));
             const channel = link?.channel;
             if (channel === undefined || !(await isCurrent(record))) {
-                link?.stop.abort();
+                // An unavailable send is Carrier's retry, not authority to retire a
+                // service-owned link while its redial is waiting.
                 throw new MachineLinkPostUnavailable({ reason: "closed" });
             }
             return await channel.deliver(envelope);

package/dist/private-local-native-digests.js

@@ -1,2 +1,2 @@
 // Generated from native build output; not a runtime sidecar.
-export const nativeDigests = Object.freeze({"linux-x64":{"patch":"df8cca6e61abec1438f96b74cf415a1609caef3868ad2e0ebe0a8c20bd571b87","bwrap":"035ac5ddfc70dd7d4a9b575b351944d47aa9d0bbafeb433fb72b2afb02cef7f4","seccomp":"38112f9cf994bed2ed962fae63e803c41874732ab032088b2c1ea3d713e51c11"}});
+export const nativeDigests = Object.freeze({"linux-x64":{"patch":"93d17ead57b33d2295cd3960603220b1c418084ab39bc8450a8fd90a258c7608","bwrap":"035ac5ddfc70dd7d4a9b575b351944d47aa9d0bbafeb433fb72b2afb02cef7f4","seccomp":"38112f9cf994bed2ed962fae63e803c41874732ab032088b2c1ea3d713e51c11","seccompWorkspace":"e46f1045f85fcf14f91fae8654bba6a0c87f57e3b92f60bfc16008dbf7dc87c8"}});

package/dist/private-local-native-install-error.d.ts

@@ -0,0 +1,2 @@
+/** The Spore caller owns the release version; Local cannot infer it from its own build ID. */
+export declare function nativePackageStartupError(cause?: unknown): Error;

package/dist/private-local-native-install-error.js

@@ -0,0 +1,10 @@
+import { z } from "zod";
+/** The Spore caller owns the release version; Local cannot infer it from its own build ID. */
+export function nativePackageStartupError(cause) {
+    const release = z.string().min(1).safeParse(process.env.FUNGI_SPORE_VERSION);
+    if (!release.success)
+        return new Error("Fungi CLI release version is unavailable; restart Fungi.", {
+            cause,
+        });
+    return new Error(`Fungi's native package for ${process.platform}-${process.arch} is missing or doesn't match this version. Reinstall: npm i -g @fungi.computer/spore@${release.data}`, { cause });
+}

package/dist/private-local-native-staging.d.ts

@@ -1,13 +1,12 @@
 import { type NativeSourceReader } from "./private-local-bwrap.js";
-import { type LocalSandboxPolicy, type NativeRunLivenessProbe } from "./private-local-sandbox-policy.js";
-/**
- * One invocation owner for pinned native bytes. Verify the installed source on
- * every admission, but execute/bind only the first private copy of those
- * verified bytes. The built digest pins each label to a single payload.
- */
-export declare function createNativePayloadStaging(project: string, readNativePatchSource?: NativeSourceReader, probeNativeRunLiveness?: NativeRunLivenessProbe): {
+import { type LinuxSandboxProfile } from "./private-local-sandbox-policy.js";
+/** The same metadata-independent package path selects the verified source and Files caller. */
+export declare function packagedPatchPath(): string;
+/** One verified private copy for the service's lifetime, not for each command. */
+export declare function createNativePayloadStaging(project: string, readNativeSource?: NativeSourceReader): {
+    admitProject: (nextProject: string) => void;
     patch: (path: string) => string;
-    linux: (policy: LocalSandboxPolicy) => {
+    linux: (profile: LinuxSandboxProfile) => {
         executable: string;
         seccompFilter: Uint8Array<ArrayBufferLike>;
     };

package/dist/private-local-native-staging.js

@@ -1,49 +1,138 @@
-import { rmSync } from "node:fs";
+import { lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync, } from "node:fs";
+import { createRequire } from "node:module";
+import { userInfo } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
 import { localLinuxSandboxPayload, verifiedNativePatchHelper, LocalBwrapUnavailable, } from "./private-local-bwrap.js";
-import { privateNativeDirectory, stageNativeBytes, UnsafeNativePayload, } from "./private-local-sandbox-policy.js";
-/**
- * One invocation owner for pinned native bytes. Verify the installed source on
- * every admission, but execute/bind only the first private copy of those
- * verified bytes. The built digest pins each label to a single payload.
- */
-export function createNativePayloadStaging(project, readNativePatchSource, probeNativeRunLiveness) {
-    let directory;
-    let closed = false;
-    const staged = new Map();
-    const stage = (label, bytes) => {
-        if (closed)
-            throw new Error("Native staging owner is closed");
-        const existing = staged.get(label);
-        if (existing !== undefined)
-            return existing;
+import { assertHostOwnedNativeFile, UnsafeNativePayload, } from "./private-local-sandbox-policy.js";
+function within(root, path) {
+    const tail = relative(root, path);
+    return !isAbsolute(tail) && tail !== ".." && !tail.startsWith(`..${sep}`);
+}
+/** The same metadata-independent package path selects the verified source and Files caller. */
+export function packagedPatchPath() {
+    if (process.env.FUNGI_BUNDLED_CLI) {
+        const name = `@fungi.computer/spore-native-${process.platform}-${process.arch}`;
         try {
-            directory ??= privateNativeDirectory(project, probeNativeRunLiveness);
-            const path = stageNativeBytes(directory, label, bytes);
-            staged.set(label, path);
-            return path;
+            const paths = createRequire(process.env.FUNGI_BUNDLED_CLI).resolve.paths(name);
+            const packageRoot = paths
+                ?.map((directory) => join(directory, name))
+                .find((candidate) => lstatSync(candidate, { throwIfNoEntry: false }));
+            if (packageRoot !== undefined)
+                return join(packageRoot, "bin", "fungi-apply-patch");
+            throw new Error("Native package not installed");
         }
         catch (cause) {
-            if (cause instanceof UnsafeNativePayload)
-                throw cause;
-            throw new LocalBwrapUnavailable("staging-failed", `Cannot stage verified ${label} in a private native directory; no command was started.`, { cause });
+            throw new LocalBwrapUnavailable("install", `Missing ${name}/bin/fungi-apply-patch; reinstall Fungi.`, { cause });
         }
-    };
-    return {
-        patch: (path) => stage("fungi-apply-patch", verifiedNativePatchHelper(path, project, readNativePatchSource)),
-        linux: (policy) => {
-            const payload = localLinuxSandboxPayload(policy);
-            return {
-                executable: stage("fungi-bwrap", payload.executableBytes),
-                seccompFilter: payload.seccompFilter,
-            };
-        },
-        probeFilter: (bytes) => stage("fungi-seccomp.bpf", bytes),
-        close: () => {
-            if (closed)
-                return;
-            closed = true;
-            if (directory !== undefined)
-                rmSync(directory, { recursive: true });
-        },
-    };
+    }
+    return fileURLToPath(new URL("../native/bin/fungi-apply-patch", import.meta.url));
+}
+/** One verified private copy for the service's lifetime, not for each command. */
+export function createNativePayloadStaging(project, readNativeSource = readFileSync) {
+    const patchSource = packagedPatchPath();
+    assertHostOwnedNativeFile(project, dirname(dirname(patchSource)));
+    const patchBytes = verifiedNativePatchHelper(patchSource, project, readNativeSource);
+    const linux = process.platform === "linux"
+        ? localLinuxSandboxPayload(project, readNativeSource)
+        : undefined;
+    const installDirectories = [
+        dirname(patchSource),
+        ...(linux === undefined ? [] : [dirname(linux.sourcePath)]),
+    ].flatMap((source) => [resolve(source), realpathSync(source)]);
+    const runtime = process.env.XDG_RUNTIME_DIR;
+    const base = runtime ?? join(userInfo().homedir, ".local", "state");
+    const uid = process.getuid?.();
+    if (uid === undefined || !isAbsolute(base))
+        throw new UnsafeNativePayload("Native staging needs an absolute runtime directory and POSIX user.");
+    if (runtime !== undefined) {
+        const metadata = lstatSync(runtime, { throwIfNoEntry: false });
+        if (metadata === undefined ||
+            !metadata.isDirectory() ||
+            metadata.uid !== uid ||
+            (metadata.mode & 0o077) !== 0)
+            throw new UnsafeNativePayload("XDG_RUNTIME_DIR must be a private directory owned by this user.");
+    }
+    const root = join(base, "fungi");
+    const projectRoot = realpathSync(project);
+    if (within(projectRoot, resolve(root)))
+        throw new UnsafeNativePayload("Host native staging cannot live inside the Agent project.");
+    let directory;
+    try {
+        mkdirSync(root, { recursive: true, mode: 0o700 });
+        const actual = realpathSync(root);
+        if (within(projectRoot, actual))
+            throw new UnsafeNativePayload("Host native staging resolves inside the Agent project.");
+        const metadata = lstatSync(actual);
+        if (!metadata.isDirectory() ||
+            metadata.uid !== uid ||
+            (metadata.mode & 0o077) !== 0)
+            throw new UnsafeNativePayload("Host native staging root must be private and owned by this user.");
+        const staged = mkdtempSync(join(actual, "native-"));
+        directory = staged;
+        const boundaries = [staged, ...installDirectories];
+        const stage = (label, bytes, mode) => {
+            const target = join(staged, label);
+            writeFileSync(target, bytes, { flag: "wx", mode });
+            return target;
+        };
+        const patch = stage("fungi-apply-patch", patchBytes, 0o500);
+        const bwrap = linux && stage("fungi-bwrap", linux.executableBytes, 0o500);
+        const seccomp = linux && stage("fungi-seccomp.bpf", linux.seccomp, 0o400);
+        const workspace = linux &&
+            stage("fungi-seccomp-workspace.bpf", linux.seccompWorkspace, 0o400);
+        let closed = false;
+        return {
+            admitProject: (nextProject) => {
+                if (closed)
+                    throw new Error("Native staging owner is closed");
+                const next = realpathSync(nextProject);
+                for (const source of boundaries)
+                    if (within(next, source))
+                        throw new UnsafeNativePayload("Native files must be outside the Agent project.");
+            },
+            patch: (path) => {
+                if (closed)
+                    throw new Error("Native staging owner is closed");
+                if (resolve(path) !== resolve(patchSource))
+                    throw new LocalBwrapUnavailable("install", "Native patch helper changed; restart Fungi.");
+                return patch;
+            },
+            linux: (profile) => {
+                if (closed)
+                    throw new Error("Native staging owner is closed");
+                if (linux === undefined || bwrap === undefined)
+                    throw new LocalBwrapUnavailable("install", "No packaged Linux sandbox; reinstall Fungi.");
+                return {
+                    executable: bwrap,
+                    seccompFilter: profile.mode === "workspace"
+                        ? linux.seccompWorkspace
+                        : linux.seccomp,
+                };
+            },
+            probeFilter: (bytes) => {
+                if (closed)
+                    throw new Error("Native staging owner is closed");
+                if (bytes === linux?.seccomp && seccomp !== undefined)
+                    return seccomp;
+                if (bytes === linux?.seccompWorkspace && workspace !== undefined)
+                    return workspace;
+                throw new LocalBwrapUnavailable("install", "Unknown native filter; restart Fungi.");
+            },
+            close: () => {
+                if (closed)
+                    return;
+                closed = true;
+                rmSync(staged, { recursive: true });
+            },
+        };
+    }
+    catch (cause) {
+        if (directory !== undefined)
+            rmSync(directory, { recursive: true });
+        if (cause instanceof UnsafeNativePayload ||
+            cause instanceof LocalBwrapUnavailable)
+            throw cause;
+        throw new LocalBwrapUnavailable("install", "Cannot copy verified native files into the private runtime directory; reinstall Fungi.", { cause });
+    }
 }

package/dist/private-local-permission-mode.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+export declare const localPermissionModeSchema: z.ZodEnum<{
+    "read-only": "read-only";
+    workspace: "workspace";
+    "full-access": "full-access";
+}>;
+export type LocalPermissionMode = z.output<typeof localPermissionModeSchema>;
+export declare function modeWithinCeiling(candidate: LocalPermissionMode, creator: LocalPermissionMode): boolean;
+/** Levi's 2026-10-25 Q1 decision: default Workspace when the host sandbox probe passes, else Full access. */
+export declare function defaultLocalPermissionMode(sandboxAvailable: boolean): LocalPermissionMode;

package/dist/private-local-permission-mode.js

@@ -0,0 +1,18 @@
+import { z } from "zod";
+export const localPermissionModeSchema = z.enum([
+    "read-only",
+    "workspace",
+    "full-access",
+]);
+const rank = {
+    "read-only": 0,
+    workspace: 1,
+    "full-access": 2,
+};
+export function modeWithinCeiling(candidate, creator) {
+    return rank[candidate] <= rank[creator];
+}
+/** Levi's 2026-10-25 Q1 decision: default Workspace when the host sandbox probe passes, else Full access. */
+export function defaultLocalPermissionMode(sandboxAvailable) {
+    return sandboxAvailable ? "workspace" : "full-access";
+}

package/dist/private-local-runtime-host.d.ts

@@ -2,6 +2,7 @@ import type { OutstandingDelegation } from "@fungi.computer/shiitake/fleet";
 import { createMcpFormSession } from "./private-mcp-form-session.js";
 import type { LocalUiAttachment } from "./private-local-ui-attachment.js";
 import { type LocalAgentExtensions } from "./local-extensions.js";
+import { type LocalPermissionMode } from "./private-local-permission-mode.js";
 import { type Models, type ThinkingLevel } from "@earendil-works/pi-ai";
 import type { CapabilitySource } from "@fungi.computer/mycelium";
 import type { BirdDogMail } from "@fungi.computer/bird-dog";
@@ -12,8 +13,10 @@ import type { ExtensionRosterV0 } from "@fungi.computer/shiitake/extensions";
 import { type InstructionSource, type ModelSource, Shiitake, type RuntimeHost, type ShiitakeAgent, type ShiitakeSession, type ShiitakeOptions } from "@fungi.computer/shiitake";
 import { type PrivateLocalConfigRoot } from "./private-local-config-root.js";
 import { type PrivateLocalEffectiveModel } from "./private-local-effective-model.js";
+import { type LocalExecEscapeStage, type LocalExecPolicyRun } from "./private-invocation-computer.js";
 import { type PrivateLocalComputerProcesses } from "./private-local-computer-processes.js";
 import { type LocalSandboxControls, type LocalSandboxStatus } from "./private-local-sandbox.js";
+import type { NativePayloadStaging } from "./private-local-native-staging.js";
 import { type NodeRuntimeHost, type NodeStoreLease } from "@fungi.computer/shiitake/node";
 import { createPrivateInvocationFilesPort, type LocalSandboxWrites } from "./private-invocation-files.js";
 import { type PrivateFungiMcpConnectionOptions } from "./private-fungi-mcp-connection.js";
@@ -49,9 +52,17 @@ export type PrivateLocalTools = Readonly<{
 export type PrivateLocalRuntimeHostOptions = Readonly<{
     /** Service-selected host configuration, independent of this Agent's Files root. */
     configRoot?: PrivateLocalConfigRoot;
+    /** Verified service copy; the service, not the Agent, closes it. */
+    native?: NativePayloadStaging | undefined;
     configuration?: (storeDirectory: string) => Promise<LocalRuntimeConfiguration>;
     /** Invocation root captured before selecting a fresh local database. */
     invocationRoot: string;
+    /** Service-owned nonsecret audit sink, never a command or environment logger. */
+    onExecRuleMatch?: (match: Readonly<{
+        agentId: string;
+        executable: string;
+        ruleId: string;
+    }>) => void;
     /** Existing Agent database to reopen instead of creating a fresh local store. */
     databasePath?: string | undefined;
     /** Stable Local store identity for replaying one Agent create request. */
@@ -63,7 +74,7 @@ export type PrivateLocalRuntimeHostOptions = Readonly<{
     /** Immutable project-relative folder authority, inherited by child Agents. */
     folder?: string | undefined;
     /** Persist before constructing the Agent, which can recover durable work. */
-    requireSandbox?: boolean | undefined;
+    mode?: LocalPermissionMode | undefined;
     /** Explicit Agent model; otherwise the Agent's stored default, then the available login. */
     providerId?: string | undefined;
     modelId?: string | undefined;
@@ -107,8 +118,8 @@ export type PrivateLocalRuntimeHost = Readonly<{
      * flag changes; the store, its Sessions and files stay.
      */
     setArchived: (archived: boolean) => void;
-    /** Persist the requirement before another affected launch is admitted. */
-    setRequireSandbox: (required: boolean) => void;
+    /** Persist a person's mode before another affected launch is admitted. */
+    setMode: (mode: LocalPermissionMode) => void;
     sandboxStatus: () => LocalSandboxStatus;
     /** Set the persistent Agent default, thinking level included, without changing Session overrides. */
     setModel: (model: ModelPreference, signal: AbortSignal) => Promise<void>;
@@ -135,7 +146,10 @@ export type PrivateLocalRuntimeHost = Readonly<{
      * owed a delivery attempt or running background process. Work it delegated
      * is owed by the child, whose reply mail reopens this Agent.
      */
-    idle: () => Promise<boolean>;
+    idle: () => Promise<{
+        idle: boolean;
+        wakeAt: number | null;
+    }>;
     close: () => Promise<void>;
 }>;
 export type LocalRuntimeConfiguration = Readonly<{
@@ -171,7 +185,7 @@ storeDirectory?: string,
 subagents?: Readonly<{
     control: CapabilitySource;
     source: SubagentSource;
-}>, configuration?: LocalRuntimeConfiguration, configRoot?: PrivateLocalConfigRoot, sandbox?: LocalSandboxWrites): Promise<PrivateLocalTools>;
+}>, configuration?: LocalRuntimeConfiguration, configRoot?: PrivateLocalConfigRoot, sandbox?: LocalSandboxWrites, currentMode?: () => LocalPermissionMode, escapeForSession?: (sessionId: string) => LocalExecEscapeStage, policyForSession?: (sessionId: string) => LocalExecPolicyRun): Promise<PrivateLocalTools>;
 /** Event-loop adaptation for the one local Shiitake owner; it has no queue policy. */
 export declare function createPrivateLocalRuntimeHost(): RuntimeHost;
 /**