@fungi.computer/truffle 0.1.1 → 0.2.0

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

@@ -1,6 +1,6 @@
 import type { BirdDogMail } from "@fungi.computer/bird-dog";
-import type { Accepted, CommandSettlement, VerifiedAgentReply } from "@fungi.computer/shiitake";
-import type { AgentControlDirectory, AgentDelegationInput, AgentDelegationInvocation } from "@fungi.computer/shiitake/agent-control";
+import type { Accepted, CancelResult, CommandSettlement, VerifiedAgentReply } from "@fungi.computer/shiitake";
+import type { AgentControlDirectory, AgentDelegationInput, AgentDelegationInvocation, AgentRecallInput } from "@fungi.computer/shiitake/agent-control";
 import { createFleetDelegation } from "@fungi.computer/shiitake/fleet";
 /**
  * The Local service's project mail routing, shared by every Agent it owns.
@@ -20,10 +20,17 @@ export type PrivateLocalMailRouting = Readonly<{
 export declare function createPrivateLocalDelegation(input: Readonly<{
     agentId: string;
     storage: Parameters<typeof createFleetDelegation>[0]["storage"];
-    directory: AgentControlDirectory;
+    directory: Pick<AgentControlDirectory, "list" | "open">;
     routing: PrivateLocalMailRouting;
+    /** Current Team role of this physical store, projected by its enrolled link. */
+    meshAdmission?: ((recipientAgentId: string) => Promise<readonly {
+        agentId: string;
+        name: string;
+    }[] | undefined>) | undefined;
     accept: (mail: BirdDogMail, meta?: BirdDogMail["meta"], reply?: VerifiedAgentReply) => Promise<Accepted>;
 }>): {
     send: (task: AgentDelegationInput, sourceSessionId: string, signal: AbortSignal, invocation?: AgentDelegationInvocation) => Promise<Accepted>;
+    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,4 +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";
 /** How long one Local delegation grant stays valid while it is admitted. */
 const grantLifetimeMs = 60_000;
@@ -21,22 +22,50 @@ export function createPrivateLocalDelegation(input) {
             name,
         }));
     }
-    /** Delegate follow-up work; its reply returns to the invoking Session. */
-    async function send(task, sourceSessionId, signal, invocation) {
-        if (invocation === undefined)
-            throw new Error("Delegation requires a tool invocation");
+    async function authorizedMembers(agentId, signal) {
         const agents = await members(signal);
-        if (!agents.some(({ agentId }) => agentId === task.agentId))
+        if (!agents.some(({ agentId: memberId }) => memberId === agentId)) {
+            const archived = await input.directory.list(signal, { archived: true });
+            if (archived.some(({ agentId: memberId }) => memberId === agentId))
+                throw new AgentArchiveRefused("archived", `Agent ${agentId} is archived; unarchive it to send it work`);
             throw new Error("Agent is outside this Local project");
-        const meta = delegationSendMeta({ id: input.agentId, name: input.agentId }, invocation.meta);
-        const provenance = await delegationProvenance({ agentId: input.agentId, sessionId: sourceSessionId }, invocation.toolCallCode);
-        const requestId = await deterministicReplayKey("local-agent-delegation", [
+        }
+        return agents;
+    }
+    function requestKey(task, sourceSessionId) {
+        return deterministicReplayKey("local-agent-delegation", [
             input.agentId,
             sourceSessionId,
-            invocation.commandId ?? "",
-            invocation.toolCallId,
-            String(invocation.sendIndex),
+            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);
+        signal.throwIfAborted();
+        if (task.delivery === "steer") {
+            const opened = await input.directory.open(task.agentId, signal);
+            try {
+                return await opened.agent.session(task.sessionId).send(task.text, {
+                    requestId,
+                    delivery: "steer",
+                });
+            }
+            finally {
+                await opened.release();
+            }
+        }
+        const meta = delegationSendMeta({ id: input.agentId, name: input.agentId }, invocation.meta);
+        // The caller's request key owns replay, not the current model program's bytes.
+        const provenance = await delegationProvenance({
+            agentId: input.agentId,
+            sessionId: sourceSessionId,
+        });
         signal.throwIfAborted();
         return fleet.start({
             agents: agents.map(({ agentId }) => agentId),
@@ -44,7 +73,32 @@ export function createPrivateLocalDelegation(input) {
             expiresAt: Date.now() + grantLifetimeMs,
             provenance,
             meta,
-        }, { ...task, requestId });
+        }, {
+            agentId: task.agentId,
+            sessionId: task.sessionId,
+            text: task.text,
+            requestId,
+        });
+    }
+    /** 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);
+        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));
+            return admitted.status === "accepted"
+                ? await session.cancel({
+                    commandId: admitted.commandId,
+                    onlyIfPending: true,
+                })
+                : admitted;
+        }
+        finally {
+            await opened.release();
+        }
     }
     /**
      * Admit one mail addressed to this Agent. New work must name its sender as
@@ -52,9 +106,10 @@ export function createPrivateLocalDelegation(input) {
      * authenticated reply. Everything else is refused.
      */
     async function receive(mail) {
-        if (mail.to.agentId !== input.agentId)
+        const mesh = await input.meshAdmission?.(mail.to.agentId);
+        if (mail.to.agentId !== input.agentId && mesh === undefined)
             throw new Error("Local addressed mail recipient is not authorized");
-        const agents = await members(new AbortController().signal);
+        const agents = mesh ?? (await members(new AbortController().signal));
         if (!agents.some(({ agentId }) => agentId === mail.from.agentId))
             throw new Error("Local mail sender is outside this project");
         if (mail.replyTo.length > 0) {
@@ -74,5 +129,5 @@ export function createPrivateLocalDelegation(input) {
         const meta = delegationReplyMeta(delegation, replier.name);
         return input.accept({ ...mail, meta }, meta, delegation.reply);
     }
-    return { send, receive };
+    return { send, recall, receive, outstanding: fleet.outstanding };
 }

package/dist/private-local-effective-model.d.ts

@@ -8,12 +8,20 @@ export declare const privateLocalEffectiveModelSchema: z.ZodObject<{
     modelName: z.ZodString;
     credential: z.ZodObject<{
         kind: z.ZodEnum<{
-            api_key: "api_key";
             oauth: "oauth";
+            api_key: "api_key";
             missing: "missing";
         }>;
         source: z.ZodString;
     }, z.core.$strict>;
+    reasoning: z.ZodOptional<z.ZodEnum<{
+        minimal: "minimal";
+        low: "low";
+        medium: "medium";
+        high: "high";
+        xhigh: "xhigh";
+        max: "max";
+    }>>;
     label: z.ZodString;
 }, z.core.$strict>;
 export type PrivateLocalEffectiveModel = z.output<typeof privateLocalEffectiveModelSchema>;

package/dist/private-local-effective-model.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { thinkingLevelSchema } from "./private-fungi-model-catalog.js";
 /** Secret-free model status published by the Local owner for one Session. */
 export const privateLocalEffectiveModelSchema = z.strictObject({
     agentName: z.literal("Shiitake"),
@@ -10,5 +11,7 @@ export const privateLocalEffectiveModelSchema = z.strictObject({
         kind: z.enum(["oauth", "api_key", "missing"]),
         source: z.string().min(1).max(160),
     }),
+    /** The resolved thinking level a run would use; absent when the model has none. */
+    reasoning: thinkingLevelSchema.optional(),
     label: z.string().min(1).max(640),
 });

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

@@ -0,0 +1,16 @@
+/**
+ * The only host variables a Local exec child receives besides its selected
+ * PATH and HOME. Exec runs as the host's own user, so that user's session
+ * locator variables are not a secret and are what `systemd-run --user`,
+ * `loginctl` and other user-service tools need to find the user manager.
+ * Every other host variable, credentials included, stays out.
+ */
+export type PrivateLocalExecEnvironment = {
+    PATH: string;
+    HOME: string;
+    XDG_RUNTIME_DIR?: string;
+    DBUS_SESSION_BUS_ADDRESS?: string;
+};
+export declare function privateLocalExecEnvironment(executionPath: string, host: NodeJS.ProcessEnv & {
+    HOME: string;
+}): PrivateLocalExecEnvironment;

package/dist/private-local-exec-environment.js

@@ -0,0 +1,11 @@
+export function privateLocalExecEnvironment(executionPath, host) {
+    const environment = {
+        PATH: executionPath,
+        HOME: host.HOME,
+    };
+    if (host.XDG_RUNTIME_DIR)
+        environment.XDG_RUNTIME_DIR = host.XDG_RUNTIME_DIR;
+    if (host.DBUS_SESSION_BUS_ADDRESS)
+        environment.DBUS_SESSION_BUS_ADDRESS = host.DBUS_SESSION_BUS_ADDRESS;
+    return environment;
+}

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

@@ -0,0 +1,8 @@
+import { type LocalSandboxPolicy } from "./private-local-sandbox-policy.js";
+import type { LinuxSandboxPayload } from "./private-local-bwrap.js";
+/** Ordinary upstream bwrap argv. There is no approval or bare-command path. */
+export declare function linuxSandboxCommand(policy: LocalSandboxPolicy, payload: LinuxSandboxPayload, cwd: string, argv: readonly [string, ...string[]], host?: NodeJS.ProcessEnv): {
+    args: string[];
+    executable: string;
+    seccompFilter: Uint8Array;
+};

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

@@ -0,0 +1,67 @@
+import { existsSync, mkdirSync, realpathSync, statSync, writeFileSync, } from "node:fs";
+import { isAbsolute, join } 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) {
+    const root = policy.writableRoot;
+    // Bind sources must exist. Only the trusted host prepares the reserved paths.
+    mkdirSync(join(root, ".fungi"), { recursive: true });
+    for (const git of policy.immovable) {
+        mkdirSync(join(git, "hooks"), { recursive: true });
+        for (const config of ["config", "config.worktree"])
+            if (!existsSync(join(git, config)))
+                writeFileSync(join(git, config), "", { flag: "wx" });
+    }
+    const args = [
+        "--unshare-all",
+        "--die-with-parent",
+        "--new-session",
+        "--seccomp",
+        "3",
+        "--ro-bind",
+        "/",
+        "/",
+        // Private system mounts precede the folder bind so /tmp projects survive.
+        "--tmpfs",
+        "/tmp",
+        "--tmpfs",
+        "/run",
+        "--dev",
+        "/dev",
+        "--proc",
+        "/proc",
+        "--bind",
+        root,
+        root,
+    ];
+    for (const path of policy.immovable)
+        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"));
+    const runtime = host.XDG_RUNTIME_DIR;
+    if (runtime && isAbsolute(runtime) && existsSync(runtime))
+        args.push("--tmpfs", realpathSync(runtime));
+    // 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.
+    // Keep unusual selected SSH-agent paths
+    // and Docker Desktop sockets out without masking all of the user's HOME.
+    if (host.HOME && isAbsolute(host.HOME)) {
+        for (const path of [
+            join(host.HOME, ".docker", "run"),
+            join(host.HOME, ".docker", "desktop"),
+        ])
+            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));
+    args.push("--chdir", cwd, "--", ...argv);
+    return { ...payload, args };
+}

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

@@ -1,6 +1,6 @@
 import type { BirdDogMail } from "@fungi.computer/bird-dog";
 import { type BirdDogEffect } from "@fungi.computer/bird-dog/effect";
-import type { DatabaseSync } from "node:sqlite";
+import type { PrivateSqliteDatabase } from "./private-sqlite-owner.js";
 import type { Accepted } from "@fungi.computer/shiitake";
 export type PrivateLocalMailOptions = Readonly<{
     /** Admit one reply at its addressed Agent; a rejection retries later. */
@@ -8,4 +8,6 @@ export type PrivateLocalMailOptions = Readonly<{
     scheduleWake?: (at: number) => void;
     now?: () => number;
 }>;
-export declare function createPrivateLocalMailRoom(database: DatabaseSync, options: PrivateLocalMailOptions): BirdDogEffect;
+/** Whether this Agent's outbox still owes any reply a delivery attempt. */
+export declare function hasPrivateLocalPendingMail(database: PrivateSqliteDatabase): Promise<boolean>;
+export declare function createPrivateLocalMailRoom(database: PrivateSqliteDatabase, options: PrivateLocalMailOptions): BirdDogEffect;

package/dist/private-local-mail.js

@@ -1,4 +1,4 @@
-import { BirdDogError, make as makeBirdDog, } from "@fungi.computer/bird-dog/effect";
+import { BirdDogError, hasPendingDelivery, make as makeBirdDog, } from "@fungi.computer/bird-dog/effect";
 import * as Effect from "effect/Effect";
 import { messageAuthor } from "@fungi.computer/agar/agents";
 import { z } from "zod";
@@ -7,41 +7,49 @@ const outboxRows = z.array(z.object({ key: z.string(), value: z.string() }).read
 function storeFailure(cause) {
     return new BirdDogError("local mail store is unavailable", { cause });
 }
+/** The Agent store's BirdDog outbox rows. */
+function localOutbox(database) {
+    return {
+        read: (key) => Effect.try({
+            try: () => {
+                const statement = database.prepare("SELECT value FROM local_birddog_outbox WHERE key = ?");
+                const row = outboxValue.safeParse(statement.get(key));
+                return row.success ? row.data.value : undefined;
+            },
+            catch: storeFailure,
+        }),
+        put: (key, value) => Effect.try({
+            try: () => {
+                database
+                    .prepare("INSERT INTO local_birddog_outbox (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value")
+                    .run(key, value);
+            },
+            catch: storeFailure,
+        }),
+        list: (limit, afterKey) => Effect.try({
+            try: () => outboxRows.parse(database
+                .prepare("SELECT key, value FROM local_birddog_outbox WHERE (? IS NULL OR key > ?) ORDER BY key LIMIT ?")
+                .all(afterKey ?? null, afterKey ?? null, limit)),
+            catch: storeFailure,
+        }),
+        delete: (key) => Effect.try({
+            try: () => {
+                database
+                    .prepare("DELETE FROM local_birddog_outbox WHERE key = ?")
+                    .run(key);
+            },
+            catch: storeFailure,
+        }),
+    };
+}
+/** Whether this Agent's outbox still owes any reply a delivery attempt. */
+export function hasPrivateLocalPendingMail(database) {
+    return Effect.runPromise(hasPendingDelivery(localOutbox(database)));
+}
 export function createPrivateLocalMailRoom(database, options) {
     database.exec("CREATE TABLE IF NOT EXISTS local_birddog_outbox (key TEXT PRIMARY KEY NOT NULL, value TEXT NOT NULL)");
     const room = Effect.runSync(makeBirdDog({
-        outbox: {
-            read: (key) => Effect.try({
-                try: () => {
-                    const statement = database.prepare("SELECT value FROM local_birddog_outbox WHERE key = ?");
-                    const row = outboxValue.safeParse(statement.get(key));
-                    return row.success ? row.data.value : undefined;
-                },
-                catch: storeFailure,
-            }),
-            put: (key, value) => Effect.try({
-                try: () => {
-                    database
-                        .prepare("INSERT INTO local_birddog_outbox (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value")
-                        .run(key, value);
-                },
-                catch: storeFailure,
-            }),
-            list: (limit, afterKey) => Effect.try({
-                try: () => outboxRows.parse(database
-                    .prepare("SELECT key, value FROM local_birddog_outbox WHERE (? IS NULL OR key > ?) ORDER BY key LIMIT ?")
-                    .all(afterKey ?? null, afterKey ?? null, limit)),
-                catch: storeFailure,
-            }),
-            delete: (key) => Effect.try({
-                try: () => {
-                    database
-                        .prepare("DELETE FROM local_birddog_outbox WHERE key = ?")
-                        .run(key);
-                },
-                catch: storeFailure,
-            }),
-        },
+        outbox: localOutbox(database),
         post: (mail) => Effect.tryPromise({
             try: async () => {
                 await options.deliver(mail);

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

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { type LocalMachineEnrollmentAccount } from "./private-local-mesh-record.js";
+export declare const localMeshJoinSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    origin: z.ZodURL;
+    invocationRoot: z.ZodString;
+    machineLabel: z.ZodString;
+    agents: z.ZodArray<z.ZodString>;
+    kind: z.ZodLiteral<"oauth">;
+    teamId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    origin: z.ZodURL;
+    invocationRoot: z.ZodString;
+    machineLabel: z.ZodString;
+    agents: z.ZodArray<z.ZodString>;
+    kind: z.ZodLiteral<"oyster-key">;
+    key: z.ZodString;
+}, z.core.$strict>], "kind">;
+/**
+ * Persist the device pin before authenticated enrollment I/O. This is enrollment
+ * only: it does not report a socket, command Accepted or connected mesh.
+ */
+export declare function enrollPrivateLocalMesh(raw: z.infer<typeof localMeshJoinSchema>, options: {
+    account: LocalMachineEnrollmentAccount;
+    credentialPath: string;
+    fetch?: typeof globalThis.fetch;
+    signal?: AbortSignal;
+}): Promise<{
+    state: string;
+    deviceId: string;
+    agents: {
+        selection: number;
+        agentId: string;
+    }[];
+}>;

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

@@ -0,0 +1,188 @@
+import { Buffer } from "node:buffer";
+import { generateKeyPairSync } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { basename, dirname, relative, isAbsolute, resolve } from "node:path";
+import { defineIdFamily } from "@fungi.computer/cairn/id";
+import { z } from "zod";
+import { readBoundedResponse } from "./private-bounded-response.js";
+import { fungiAccountFetch } from "./private-fungi-account.js";
+import { parseFungiMcpEndpoint } from "./private-fungi-mcp-endpoint.js";
+import { listPrivateLocalAgentStores, readPrivateLocalAgentProfile, } from "./private-local-session-discovery.js";
+import { machineBindingSchema, localMachineEnrollmentSchema, } from "./private-local-mesh-record.js";
+const id = z.string().min(1).max(256);
+const joinCommon = z.strictObject({
+    origin: z.url(),
+    invocationRoot: z.string().min(1).max(4096),
+    machineLabel: z.string().trim().min(1).max(256),
+    agents: z
+        .array(id)
+        .max(256)
+        .refine((agents) => new Set(agents).size === agents.length),
+});
+export const localMeshJoinSchema = z.discriminatedUnion("kind", [
+    joinCommon.extend({ kind: z.literal("oauth"), teamId: id }),
+    joinCommon.extend({
+        kind: z.literal("oyster-key"),
+        key: z.string().startsWith("oyk_").min(5).max(4096),
+    }),
+]);
+const responseSchema = z.strictObject({
+    kind: z.literal("joined"),
+    deviceId: id,
+    agents: z.array(machineBindingSchema).max(256),
+});
+const oysterResponseSchema = responseSchema.extend({ scopeId: id });
+const requests = defineIdFamily({
+    family: "local-machine-enrollment",
+    version: 1,
+    kinds: { join: { prefix: "machine_join" } },
+});
+function deviceKey() {
+    const pair = generateKeyPairSync("ed25519");
+    const jwk = z
+        .object({ x: z.string() })
+        .parse(pair.publicKey.export({ format: "jwk" }));
+    return {
+        publicKey: Buffer.from(jwk.x, "base64url").toString("base64"),
+        privateKey: pair.privateKey
+            .export({ format: "der", type: "pkcs8" })
+            .toString("base64"),
+    };
+}
+/**
+ * Persist the device pin before authenticated enrollment I/O. This is enrollment
+ * only: it does not report a socket, command Accepted or connected mesh.
+ */
+export async function enrollPrivateLocalMesh(raw, options) {
+    const input = localMeshJoinSchema.parse(raw);
+    const endpoint = parseFungiMcpEndpoint(input.origin);
+    if (endpoint.pathname !== "/")
+        throw new Error("Mesh enrollment needs an origin");
+    const origin = endpoint.origin;
+    const authority = {
+        kind: input.kind === "oauth" ? "oauth" : "oyster",
+        origin,
+    };
+    if (input.kind === "oauth") {
+        const saved = await options.account.read();
+        if (!saved.some((record) => record.kind === "oauth" && record.origin === origin))
+            throw new Error("Sign in to this Fungi issuer before joining a machine");
+    }
+    const invocationRoot = await realpath(resolve(input.invocationRoot));
+    const stores = await listPrivateLocalAgentStores(invocationRoot);
+    const selected = input.agents.map((localAgentId) => {
+        const databasePath = stores.find((path) => basename(dirname(path)) === localAgentId);
+        if (databasePath === undefined)
+            throw new Error("The selected Agent is not active in this project");
+        const within = relative(invocationRoot, databasePath);
+        if (isAbsolute(within) || within === ".." || within.startsWith("../"))
+            throw new Error("The selected Agent is outside this project");
+        const profile = readPrivateLocalAgentProfile(databasePath);
+        return { localAgentId, databasePath, name: profile.name ?? localAgentId };
+    });
+    const proposed = {
+        state: "pending",
+        requestId: requests.join.generate(),
+        target: input.kind === "oauth"
+            ? { kind: "oauth", teamId: input.teamId }
+            : { kind: "oyster" },
+        invocationRoot,
+        machineLabel: input.machineLabel,
+        ...deviceKey(),
+        agents: selected,
+    };
+    let chosen;
+    await options.account.update(authority, (current) => {
+        const prior = current.find((record) => JSON.stringify(record.target) === JSON.stringify(proposed.target));
+        if (prior !== undefined) {
+            if (prior.invocationRoot !== invocationRoot ||
+                prior.machineLabel !== input.machineLabel ||
+                JSON.stringify(prior.agents) !== JSON.stringify(selected))
+                throw new Error("This scope already has another machine enrollment intent");
+            chosen = prior;
+            return [...current];
+        }
+        chosen = proposed;
+        return [...current, proposed];
+    });
+    if (chosen === undefined)
+        throw new Error("The credential owner did not persist an enrollment");
+    const record = chosen;
+    if (record.state === "enrolled")
+        return {
+            state: "enrolled",
+            deviceId: record.deviceId,
+            agents: record.bindings,
+        };
+    const url = new URL(input.kind === "oauth"
+        ? `/api/teams/${encodeURIComponent(input.teamId)}/local/mesh/join`
+        : "/local/mesh/join", origin);
+    // Only OAuth owns refresh/retry. An Oyster key is ephemeral enrollment
+    // authority; neither the credential owner nor later Seam dials receive it.
+    const request = input.kind === "oauth"
+        ? fungiAccountFetch(origin, options)
+        : (options.fetch ?? globalThis.fetch);
+    const headers = new Headers({ "content-type": "application/json" });
+    if (input.kind === "oyster-key")
+        headers.set("Authorization", `Bearer ${input.key}`);
+    const init = {
+        method: "POST",
+        headers,
+        redirect: "error",
+        body: JSON.stringify({
+            requestId: record.requestId,
+            machineLabel: record.machineLabel,
+            publicKey: record.publicKey,
+            // Local directory selectors and database paths remain private.
+            agents: record.agents.map(({ name }) => ({ name })),
+        }),
+    };
+    if (options.signal !== undefined)
+        init.signal = options.signal;
+    let response;
+    try {
+        response = await request(url, init);
+    }
+    finally {
+        if (input.kind === "oyster-key") {
+            // Release Local-owned references before decoding/storing the response.
+            // This cannot erase immutable string bytes or caller/fetch-owned copies.
+            headers.delete("Authorization");
+            input.key = "";
+        }
+    }
+    if (!response.ok)
+        throw new Error(`Machine enrollment refused with HTTP ${String(response.status)}`);
+    const payload = JSON.parse(await readBoundedResponse(response, 64 * 1024, "Machine enrollment"));
+    const result = input.kind === "oauth"
+        ? { ...responseSchema.parse(payload), scopeId: input.teamId }
+        : oysterResponseSchema.parse(payload);
+    if (result.agents.length !== record.agents.length ||
+        result.agents.some((binding, index) => binding.selection !== index) ||
+        new Set(result.agents.map((binding) => binding.agentId)).size !==
+            result.agents.length)
+        throw new Error("Machine enrollment does not match the selected Agent set");
+    const enrolled = localMachineEnrollmentSchema.parse({
+        ...record,
+        state: "enrolled",
+        deviceId: result.deviceId,
+        scopeId: result.scopeId,
+        bindings: result.agents,
+    });
+    await options.account.update(authority, (current) => {
+        const matching = current.find((candidate) => candidate.requestId === record.requestId);
+        if (matching === undefined)
+            throw new Error("Machine enrollment was removed before acknowledgment");
+        if (matching.state === "enrolled" &&
+            (matching.deviceId !== result.deviceId ||
+                matching.scopeId !== result.scopeId ||
+                JSON.stringify(matching.bindings) !== JSON.stringify(result.agents)))
+            throw new Error("Home changed an acknowledged machine enrollment");
+        return current.map((candidate) => candidate.requestId === record.requestId ? enrolled : candidate);
+    });
+    return {
+        state: "enrolled",
+        deviceId: result.deviceId,
+        agents: result.agents,
+    };
+}

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

@@ -0,0 +1,21 @@
+import type { PostEnvelope, PostDeliveryResult } from "@fungi.computer/carrier/post";
+import type { LocalMachineEnrollment, MachineEnrollmentAuthority } from "./private-local-mesh-record.js";
+export type EnrolledLocalMachine = Extract<LocalMachineEnrollment, {
+    state: "enrolled";
+}> & {
+    authority: MachineEnrollmentAuthority;
+};
+export declare const localMeshLinkKey: (record: EnrolledLocalMachine) => string;
+/**
+ * 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 declare function createLocalMeshLinks(options: {
+    credentialPath: string;
+    receive: (record: EnrolledLocalMachine, envelope: PostEnvelope) => Promise<PostDeliveryResult>;
+}): {
+    refresh: () => Promise<void>;
+    isCurrent: (record: EnrolledLocalMachine) => Promise<boolean>;
+    deliver: (record: EnrolledLocalMachine, envelope: PostEnvelope) => Promise<PostDeliveryResult>;
+    close: () => Promise<void>;
+};