@fungi.computer/truffle 0.2.2 → 0.3.0

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

@@ -1,21 +1,23 @@
-import { type LocalSandboxPolicy } from "./private-local-sandbox-policy.js";
 export declare class LocalBwrapUnavailable extends Error {
-    readonly reason: "missing" | "missing-artifact" | "invalid-digest" | "digest-mismatch" | "unreadable" | "not-executable" | "staging-failed";
+    readonly reason: "install";
     readonly name = "LocalBwrapUnavailable";
-    constructor(reason: "missing" | "missing-artifact" | "invalid-digest" | "digest-mismatch" | "unreadable" | "not-executable" | "staging-failed", message: string, options?: ErrorOptions);
+    constructor(reason: "install", message: string, options?: ErrorOptions);
 }
 export type LinuxSandboxPayload = {
+    readonly sourcePath: string;
     readonly executableBytes: Uint8Array;
-    readonly seccompFilter: Uint8Array;
+    readonly seccomp: Uint8Array;
+    readonly seccompWorkspace: Uint8Array;
 };
 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;
-/** Check both packaged artifacts on every use; never cache verification. */
-export declare function verifyLocalLinuxSandboxPayload(executable: string, policy: LocalSandboxPolicy, expected: LinuxSandboxDigests): LinuxSandboxPayload;
+/** 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(policy: LocalSandboxPolicy): LinuxSandboxPayload;
+export declare function localLinuxSandboxPayload(project: string, readNativeSource?: NativeSourceReader): LinuxSandboxPayload;

package/dist/private-local-bwrap.js

@@ -16,15 +16,17 @@ export class LocalBwrapUnavailable extends Error {
 export function verifiedNativePatchHelper(path, project, readNativeSource = readFileSync) {
     const expected = nativeDigests[`${process.platform}-${process.arch}`]?.patch;
     if (expected === undefined)
-        throw new LocalBwrapUnavailable("invalid-digest", "No built native patch digest for this platform; reinstall Fungi.");
+        throw new LocalBwrapUnavailable("install", "No built native patch digest for this platform; reinstall Fungi.");
     return verifiedBytes(path, "fungi-apply-patch", project, expected, readNativeSource);
 }
-/** Check both packaged artifacts on every use; never cache verification. */
-export function verifyLocalLinuxSandboxPayload(executable, policy, expected) {
-    const executableBytes = verifiedBytes(executable, "fungi-bwrap", policy.projectRoot, expected.bwrap);
+/** 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 {
+        sourcePath: executable,
         executableBytes,
-        seccompFilter: verifiedBytes(join(dirname(executable), "fungi-seccomp.bpf"), "fungi-seccomp.bpf", policy.projectRoot, expected.seccomp),
+        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, project, expected, readNativeSource = readFileSync) {
@@ -32,26 +34,28 @@ function verifiedBytes(path, label, project, expected, readNativeSource = readFi
     try {
         assertHostOwnedNativeFile(project, path);
         if (!statSync(path).isFile())
-            throw new LocalBwrapUnavailable("not-executable", `Packaged ${label} is not a regular file; reinstall Fungi.`);
+            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-artifact", `Packaged ${label} is missing; reinstall Fungi with optional dependencies enabled.`, { 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("unreadable", `Packaged ${label} cannot be read; reinstall Fungi. No command was started.`, { cause });
+        throw new LocalBwrapUnavailable("install", `Packaged ${label} cannot be read; reinstall Fungi. No command was started.`, { cause });
     }
     if (createHash("sha256").update(bytes).digest("hex") !== expected)
-        throw new LocalBwrapUnavailable("digest-mismatch", `Packaged ${label} digest mismatch; reinstall Fungi. No command was started.`);
+        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(policy) {
+export function localLinuxSandboxPayload(project, readNativeSource = readFileSync) {
     const digest = nativeDigests[`${process.platform}-${process.arch}`];
-    if (digest?.bwrap === undefined || digest.seccomp === undefined)
-        throw new LocalBwrapUnavailable("invalid-digest", "No built native Linux payload digest for this platform; reinstall Fungi.");
+    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}`;
@@ -61,10 +65,10 @@ export function localLinuxSandboxPayload(policy) {
             directories = createRequire(process.env.FUNGI_BUNDLED_CLI).resolve.paths(name);
         }
         catch (cause) {
-            throw new LocalBwrapUnavailable("missing-artifact", message, { cause });
+            throw new LocalBwrapUnavailable("install", message, { cause });
         }
         if (directories === null)
-            throw new LocalBwrapUnavailable("missing-artifact", message);
+            throw new LocalBwrapUnavailable("install", message);
         let packageRoot;
         for (const directory of directories) {
             const candidate = join(directory, name);
@@ -75,31 +79,32 @@ export function localLinuxSandboxPayload(policy) {
                 }
             }
             catch (cause) {
-                throw new LocalBwrapUnavailable("missing-artifact", message, { cause });
+                throw new LocalBwrapUnavailable("install", message, { cause });
             }
         }
         if (packageRoot === undefined)
-            throw new LocalBwrapUnavailable("missing", `Missing ${name}; reinstall Fungi with optional dependencies enabled.`);
+            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 {
-            assertHostOwnedNativeFile(policy.projectRoot, packageRoot);
+            assertHostOwnedNativeFile(project, packageRoot);
             if (!statSync(packageRoot).isDirectory())
-                throw new LocalBwrapUnavailable("missing-artifact", message);
+                throw new LocalBwrapUnavailable("install", message);
         }
         catch (cause) {
             if (cause instanceof UnsafeNativePayload ||
                 cause instanceof LocalBwrapUnavailable)
                 throw cause;
-            throw new LocalBwrapUnavailable("missing-artifact", message, { 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, policy, {
+    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,20 +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";
-        "missing-artifact": "missing-artifact";
-        "invalid-digest": "invalid-digest";
-        "digest-mismatch": "digest-mismatch";
-        unreadable: "unreadable";
-        "not-executable": "not-executable";
-        "staging-failed": "staging-failed";
-        "unsupported-platform": "unsupported-platform";
-        "invalid-folder": "invalid-folder";
-        "unsafe-native-payload": "unsafe-native-payload";
-        "unsafe-host-code": "unsafe-host-code";
+        install: "install";
+        unsupported: "unsupported";
+        folder: "folder";
         "startup-refused": "startup-refused";
-        "backend-refused": "backend-refused";
     }>;
     message: z.ZodString;
 }, z.core.$strict>;
@@ -29,6 +21,7 @@ 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;
@@ -55,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): SandboxAdmission;
+}>, 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,29 +1,14 @@
 import { spawnSync } from "node:child_process";
-import { closeSync, mkdtempSync, openSync, realpathSync, rmSync, } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
+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, UnsafeHostCode, UnsafeNativePayload, } 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",
-        "missing-artifact",
-        "invalid-digest",
-        "digest-mismatch",
-        "unreadable",
-        "not-executable",
-        "staging-failed",
-        "unsafe-native-payload",
-        "unsafe-host-code",
-        "startup-refused",
-        "backend-refused",
-    ]),
+    kind: z.enum(["unsupported", "install", "folder", "startup-refused"]),
     message: z.string(),
 });
 export class LocalSandboxUnavailable extends Error {
@@ -35,14 +20,18 @@ export class LocalSandboxUnavailable extends Error {
     }
 }
 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: "unsafe-host-code", message: cause.message };
+        return { kind: "install", message: cause.message };
     if (cause instanceof UnsafeNativePayload)
-        return { kind: "unsafe-native-payload", message: cause.message };
+        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.",
     };
 }
@@ -51,7 +40,9 @@ export function sandboxUnavailableReason(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, staging) {
+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);
     }
@@ -59,7 +50,7 @@ export function establishLocalSandbox(input, staging) {
         return {
             state: "unavailable",
             reason: {
-                kind: "invalid-folder",
+                kind: "folder",
                 message: cause instanceof Error ? cause.message : "Invalid sandbox folder.",
             },
         };
@@ -69,34 +60,35 @@ export function establishLocalSandbox(input, staging) {
         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.`,
             },
         };
-    const native = staging ?? createNativePayloadStaging(input.project);
-    let agentTemporaryDirectory;
+    let native;
     try {
-        // Native staging is never granted as an Agent-writable temporary root.
-        if (platform === "darwin")
-            agentTemporaryDirectory = realpathSync(mkdtempSync(join(tmpdir(), "fungi-sandbox-")));
-        const agentTemporary = agentTemporaryDirectory;
-        const environmentTmp = agentTemporary ?? "/tmp";
+        native =
+            staging ??
+                (platform === "linux"
+                    ? createNativePayloadStaging(input.project)
+                    : undefined);
+        const environmentTmp = platform === "linux" ? "/tmp" : input.temporaryDirectory;
         let closed = false;
         const sandbox = {
             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 linuxPayload = platform === "linux" ? native.linux(policy) : undefined;
+                    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);
+                        : native?.patch(readOnlyHelperFile);
                     const stagedArgv = stagedHelper === undefined
                         ? argv
                         : [
@@ -106,15 +98,17 @@ export function establishLocalSandbox(input, staging) {
                                 .map((argument) => argument === readOnlyHelperFile ? stagedHelper : argument),
                         ];
                     const launch = linuxPayload !== undefined
-                        ? linuxSandboxCommand(policy, linuxPayload, cwd, stagedArgv, undefined, stagedHelper)
-                        : seatbeltCommand({
-                            ...policy,
-                            temporaryDirectory: environmentTmp,
-                        }, stagedArgv);
-                    return {
-                        ...launch,
-                        environment: { TMPDIR: environmentTmp },
+                        ? 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(sandboxUnavailableReason(cause));
@@ -124,14 +118,8 @@ export function establishLocalSandbox(input, staging) {
                 if (closed)
                     return;
                 closed = true;
-                try {
-                    if (staging === undefined)
-                        native.close();
-                }
-                finally {
-                    if (agentTemporary !== undefined)
-                        rmSync(agentTemporary, { recursive: true });
-                }
+                if (staging === undefined)
+                    native?.close();
             },
         };
         const command = sandbox.command(realpathSync(input.folder), [
@@ -140,7 +128,9 @@ export function establishLocalSandbox(input, staging) {
         let filterDescriptor;
         const probe = () => {
             if (command.seccompFilter !== undefined) {
-                const path = native.probeFilter(command.seccompFilter);
+                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], {
@@ -160,7 +150,7 @@ export function establishLocalSandbox(input, staging) {
         };
         const result = (() => {
             try {
-                return probe();
+                return runProbe?.(command) ?? probe();
             }
             finally {
                 if (filterDescriptor !== undefined)
@@ -174,24 +164,18 @@ export function establishLocalSandbox(input, staging) {
                 state: "unavailable",
                 reason: {
                     kind: "startup-refused",
-                    message: result.error?.message ??
+                    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) {
-        try {
-            if (staging === undefined)
-                native.close();
-        }
-        finally {
-            if (agentTemporaryDirectory !== undefined)
-                rmSync(agentTemporaryDirectory, { recursive: true });
-        }
+        if (staging === undefined)
+            native?.close();
         return {
             state: "unavailable",
             reason: cause instanceof LocalSandboxUnavailable

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>;

package/dist/private-local-delegation.js

@@ -1,6 +1,5 @@
-import { deterministicReplayKey } from "@fungi.computer/cairn";
 import { AgentArchiveRefused } from "@fungi.computer/shiitake/agent-control";
-import { createFleetDelegation, delegationProvenance, delegationReplyMeta, delegationSendMeta, } from "@fungi.computer/shiitake/fleet";
+import { agentDelegationRequestKey, createFleetDelegation, delegationProvenance, delegationReplyMeta, delegationSendMeta, } from "@fungi.computer/shiitake/fleet";
 /** How long one Local delegation grant stays valid while it is admitted. */
 const grantLifetimeMs = 60_000;
 /**
@@ -32,21 +31,17 @@ export function createPrivateLocalDelegation(input) {
         }
         return agents;
     }
-    function requestKey(task, sourceSessionId) {
-        return deterministicReplayKey("local-agent-delegation", [
-            input.agentId,
-            sourceSessionId,
-            task.agentId,
-            task.sessionId,
-            task.requestId,
-        ]);
-    }
     /** Send with one caller-owned identity; follow-up replies return here. */
     async function send(task, sourceSessionId, signal, invocation) {
         if (invocation === undefined)
             throw new Error("Delegation requires a tool invocation");
         const agents = await authorizedMembers(task.agentId, signal);
-        const requestId = await requestKey(task, sourceSessionId);
+        const requestId = await agentDelegationRequestKey({
+            owner: { kind: "local", agentId: input.agentId },
+            sourceSessionId,
+            targetAgentId: task.agentId,
+            requestId: task.requestId,
+        });
         signal.throwIfAborted();
         if (task.delivery === "steer") {
             const opened = await input.directory.open(task.agentId, signal);
@@ -83,12 +78,21 @@ export function createPrivateLocalDelegation(input) {
     /** Resolve only this sender's receipt, then let the target own the pending guard. */
     async function recall(task, sourceSessionId, signal) {
         await authorizedMembers(task.agentId, signal);
-        const requestId = await requestKey(task, sourceSessionId);
+        const requestId = await agentDelegationRequestKey({
+            owner: { kind: "local", agentId: input.agentId },
+            sourceSessionId,
+            targetAgentId: task.agentId,
+            requestId: task.requestId,
+        });
         signal.throwIfAborted();
         const opened = await input.directory.open(task.agentId, signal);
         try {
-            const session = opened.agent.session(task.sessionId);
-            const admitted = fleet.receipt(requestId) ?? (await session.withdraw(requestId));
+            const receipt = fleet.receipt(requestId);
+            if (receipt?.sessionId !== undefined &&
+                receipt.sessionId !== task.sessionId)
+                return { status: "unknown" };
+            const session = opened.agent.session(receipt?.sessionId ?? task.sessionId);
+            const admitted = receipt ?? (await session.withdraw(requestId));
             return admitted.status === "accepted"
                 ? await session.cancel({
                     commandId: admitted.commandId,
@@ -110,7 +114,11 @@ export function createPrivateLocalDelegation(input) {
         if (mail.to.agentId !== input.agentId && mesh === undefined)
             throw new Error("Local addressed mail recipient is not authorized");
         const agents = mesh ?? (await members(new AbortController().signal));
-        if (!agents.some(({ agentId }) => agentId === mail.from.agentId))
+        const delegation = mail.replyTo.length === 0 ? fleet.authenticateReply(mail) : undefined;
+        const frozenUndeliverable = delegation?.reply.outcome === "undeliverable" &&
+            delegation.reply.agentId === mail.from.agentId;
+        if (!agents.some(({ agentId }) => agentId === mail.from.agentId) &&
+            !frozenUndeliverable)
             throw new Error("Local mail sender is outside this project");
         if (mail.replyTo.length > 0) {
             const [destination] = mail.replyTo;
@@ -120,13 +128,18 @@ export function createPrivateLocalDelegation(input) {
                 throw new Error("Local delegated work must reply to its sender");
             return input.accept(mail, mail.meta);
         }
-        const delegation = fleet.authenticateReply(mail);
+        if (mail.reply?.outcome === "accepted") {
+            const receipt = fleet.recordAcceptedNotice(mail);
+            if (receipt === undefined)
+                throw new Error("Local acceptance notice does not match sent work");
+            return receipt;
+        }
         if (delegation === undefined)
             throw new Error("Local reply does not match work this Agent sent");
         const replier = agents.find(({ agentId }) => agentId === delegation.reply.agentId);
-        if (replier === undefined)
+        if (replier === undefined && !frozenUndeliverable)
             throw new Error("Local reply sender is outside this project");
-        const meta = delegationReplyMeta(delegation, replier.name);
+        const meta = delegationReplyMeta(delegation, replier?.name ?? delegation.reply.agentId);
         return input.accept({ ...mail, meta }, meta, delegation.reply);
     }
     return { send, recall, receive, outstanding: fleet.outstanding };

package/dist/private-local-exec-review.d.ts

@@ -0,0 +1,10 @@
+import type { LocalApprovalReview } from "./private-mcp-form-session.js";
+/** Build the host's review before the approval record is staged or displayed. */
+export declare function localExecEscapeReview(request: {
+    command?: string | undefined;
+    executable?: string | undefined;
+    args?: string[] | undefined;
+    escape?: {
+        justification: string;
+    } | undefined;
+}, cwd: string): LocalApprovalReview;