@fungi.computer/truffle 0.3.1 → 0.5.0

package/dist/local-upgrade.js

@@ -0,0 +1,358 @@
+import { lstat, mkdir, readFile, rename, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import lockfile from "proper-lockfile";
+import semver from "semver";
+import writeFileAtomic from "write-file-atomic";
+import { z } from "zod";
+import { logEvent } from "./log-event.js";
+import { incompatibleLocalExtensionActivations } from "./private-local-extension-records.js";
+import { createPrivateLocalServiceManager, LocalServiceUpdated, } from "./private-local-service.js";
+import { readInstalledLocalClientBuildId } from "./private-local-client-version.js";
+import { LocalStoreSchemaError, probePrivateLocalAgentStoreEntries, readPrivateLocalAgentProfile, } from "./private-local-session-discovery.js";
+import { assertNoUntrackedServiceOwner, privateLocalServiceVersion, readServiceRegistration, serviceOwnerIsLive, } from "./private-local-service-discovery.js";
+const version = z
+    .string()
+    .refine((value) => semver.valid(value) !== null, "Invalid semver version");
+const versionMarkerSchema = z.strictObject({
+    version: z.literal(1),
+    release: version,
+    spore: version,
+    build: z.union([z.literal("source"), z.string().regex(/^[a-f0-9]{64}$/u)]),
+});
+const newsSchema = z.strictObject({
+    release: versionMarkerSchema.shape.release,
+    lines: z.array(z.string().max(120)).max(3),
+});
+const markerPath = (home) => join(home, ".fungi", "version.json");
+const pendingPath = (home) => join(home, ".fungi", ".upgrade-in-progress.json");
+const pendingSchema = z.strictObject({
+    version: z.literal(1),
+    prior: z.discriminatedUnion("kind", [
+        z.strictObject({
+            kind: z.literal("recorded"),
+            release: version,
+            spore: version,
+        }),
+        z.strictObject({
+            kind: z.literal("protocol"),
+            protocol: z.number().int().nonnegative(),
+            build: z.string().min(1),
+        }),
+        z.strictObject({ kind: z.literal("unrecorded") }),
+    ]),
+});
+/** Persist prior identity before stop removes the only protocol-3 record. */
+async function readPendingUpgrade(home) {
+    const path = pendingPath(home);
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (cause) {
+        if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+            return undefined;
+        throw new Error(`Cannot read the in-progress Fungi upgrade at ${path}`, {
+            cause,
+        });
+    }
+    try {
+        return pendingSchema.parse(JSON.parse(text)).prior;
+    }
+    catch (cause) {
+        throw new Error(`Cannot resume the Fungi upgrade at ${path}: inspect or move this marker aside before retrying`, { cause });
+    }
+}
+async function writePendingUpgrade(home, prior) {
+    await writeFileAtomic(pendingPath(home), `${JSON.stringify(pendingSchema.parse({ version: 1, prior }))}\n`, { mode: 0o600 });
+}
+/** A completed version marker supersedes a pending pass left after its write. */
+function pendingIsComplete(recorded, pending) {
+    return (recorded.kind === "recorded" &&
+        (pending.kind !== "recorded" ||
+            recorded.release !== pending.release ||
+            recorded.spore !== pending.spore));
+}
+/** Version marker is a label, not permission to accept an older store schema. */
+export async function readPriorInstall(home) {
+    const path = markerPath(home);
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (cause) {
+        if (!(cause instanceof Error && "code" in cause && cause.code === "ENOENT"))
+            throw cause;
+    }
+    if (text !== undefined) {
+        try {
+            const marker = versionMarkerSchema.parse(JSON.parse(text));
+            return { kind: "recorded", release: marker.release, spore: marker.spore };
+        }
+        catch (cause) {
+            throw new Error(`Cannot read ${path}: unsupported Fungi version marker`, {
+                cause,
+            });
+        }
+    }
+    const registration = await readServiceRegistration(join(home, ".fungi", "service"));
+    if (registration?.kind === "other-protocol")
+        return {
+            kind: "protocol",
+            protocol: registration.lifecycle.protocol,
+            build: registration.lifecycle.version,
+        };
+    return { kind: "unrecorded" };
+}
+/** Only the completed upgrade pass calls this writer; never write it early. */
+export async function writeLocalVersionMarker(home, marker) {
+    const path = markerPath(home);
+    const record = versionMarkerSchema.parse({ version: 1, ...marker });
+    await mkdir(join(home, ".fungi"), { recursive: true, mode: 0o700 });
+    await writeFileAtomic(path, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+}
+/** Invalid news lines are optional; a missing release label is not safe to mark current. */
+export async function readLocalUpgradeNews(path) {
+    const value = JSON.parse(await readFile(path, "utf8"));
+    const release = z
+        .looseObject({ release: versionMarkerSchema.shape.release })
+        .parse(value).release;
+    return {
+        release,
+        lines: newsSchema.safeParse(value).data?.lines ?? [],
+    };
+}
+async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (cause) {
+        if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+            return false;
+        throw cause;
+    }
+}
+function archiveSlug(prior) {
+    if (prior.kind === "recorded")
+        return prior.release;
+    if (prior.kind === "unrecorded")
+        return "unversioned";
+    const build = prior.build.slice(0, 12);
+    return `protocol-${String(prior.protocol)}-${/^[a-f0-9]{12}$/u.test(build) ? build : "source"}`;
+}
+async function surveyIncompatibleLocalHome(home) {
+    const incompatible = [];
+    for (const store of await probePrivateLocalAgentStoreEntries(home)) {
+        try {
+            readPrivateLocalAgentProfile(store.databasePath);
+        }
+        catch (cause) {
+            if (cause instanceof LocalStoreSchemaError)
+                incompatible.push({
+                    kind: "agent-store",
+                    from: store.entry,
+                    name: store.agentId,
+                    folder: "agents",
+                });
+            else
+                logEvent("upgrade-agent-store-survey", cause);
+        }
+    }
+    for (const path of await incompatibleLocalExtensionActivations(home))
+        incompatible.push({
+            kind: "extension-activations",
+            from: path,
+            name: "activations.json",
+            folder: "extensions",
+        });
+    return incompatible;
+}
+/** Upgrade → service startup → extensions owner: this lock is always first. */
+export async function upgradeLocalHome(options) {
+    const home = options.home ?? homedir();
+    const spore = versionMarkerSchema.shape.spore.parse(options.spore);
+    // A new empty home has no need to read a release artifact to use ordinary
+    // commands. A recorded or running older installation needs its label.
+    const recorded = await readPriorInstall(home);
+    let news = recorded.kind === "unrecorded"
+        ? undefined
+        : await readLocalUpgradeNews(options.newsPath);
+    const current = (prior, release) => prior.kind === "recorded" &&
+        release !== undefined &&
+        (semver.gt(prior.release, release) ||
+            (semver.eq(prior.release, release) && semver.gte(prior.spore, spore)));
+    if (current(recorded, news?.release))
+        return { kind: "current" };
+    const root = join(home, ".fungi");
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    const release = await lockfile.lock(root, {
+        lockfilePath: join(root, ".upgrade.lock"),
+        realpath: false,
+        stale: 30_000,
+        update: 10_000,
+        retries: { retries: 60, factor: 1.2, minTimeout: 25, maxTimeout: 250 },
+    });
+    try {
+        options.signal?.throwIfAborted();
+        const observed = await readPriorInstall(home);
+        const pending = await readPendingUpgrade(home);
+        const prior = pending !== undefined && !pendingIsComplete(observed, pending)
+            ? pending
+            : observed;
+        if (prior.kind === "recorded") {
+            news ??= await readLocalUpgradeNews(options.newsPath);
+        }
+        if (current(prior, news?.release))
+            return { kind: "current" };
+        const directory = options.directory ?? join(root, "service");
+        const registration = await readServiceRegistration(directory);
+        if (prior.kind === "unrecorded" &&
+            registration?.kind === "current" &&
+            registration.record.version === privateLocalServiceVersion() &&
+            (await surveyIncompatibleLocalHome(home)).length === 0)
+            return { kind: "current" };
+        if (prior.kind === "unrecorded" && registration === undefined) {
+            const archive = join(root, "archive", archiveSlug(prior));
+            if ((await surveyIncompatibleLocalHome(home)).length === 0 &&
+                !(await exists(join(archive, "agents"))) &&
+                !(await exists(join(archive, "extensions", "activations.json"))))
+                return { kind: "current" };
+        }
+        // The service stop removes service.json. Record its prior identity while
+        // the upgrade lock still holds it, before any stop or archive rename.
+        await writePendingUpgrade(home, prior);
+        let service = "absent";
+        if (registration !== undefined) {
+            // The upgrade is no bypass around the service's installed-client check.
+            // An uninstalled or stale window cannot signal a different live build.
+            if ((await exists(join(directory, "owner.sqlite"))) &&
+                (await serviceOwnerIsLive(directory)) &&
+                privateLocalServiceVersion() !==
+                    (await (options.installedClientBuildId ?? readInstalledLocalClientBuildId)()))
+                throw new LocalServiceUpdated();
+            const expectedId = registration.kind === "current"
+                ? registration.record.serviceId
+                : registration.kind === "other-protocol"
+                    ? registration.lifecycle.serviceId
+                    : undefined;
+            const stop = options.stopService ??
+                createPrivateLocalServiceManager({ home, directory }).stop;
+            const stopped = await stop(expectedId);
+            if (stopped.kind === "replaced")
+                throw new Error(`The Fungi service in ${directory} changed during upgrade; retry before archiving`);
+            if (stopped.kind === "stopped" || stopped.kind === "killed")
+                service = stopped.kind;
+        }
+        if ((await readServiceRegistration(directory)) !== undefined ||
+            ((await exists(join(directory, "owner.sqlite"))) &&
+                (await serviceOwnerIsLive(directory))))
+            throw new Error(`A Fungi service still owns ${directory}; no files were archived`);
+        await assertNoUntrackedServiceOwner(directory);
+        const archive = join(root, "archive", archiveSlug(prior));
+        const incompatible = await surveyIncompatibleLocalHome(home);
+        // The installed-registry owner also uses archive/unversioned. Only our
+        // own entries indicate an interrupted home upgrade to resume.
+        const existingArchive = (await exists(join(archive, "agents"))) ||
+            (await exists(join(archive, "extensions", "activations.json")));
+        if (incompatible.length === 0 &&
+            !existingArchive &&
+            service === "absent" &&
+            prior.kind === "unrecorded") {
+            await unlink(pendingPath(home));
+            return { kind: "current" };
+        }
+        news ??= await readLocalUpgradeNews(options.newsPath);
+        if (incompatible.length > 0) {
+            await mkdir(join(archive, "agents"), { recursive: true, mode: 0o700 });
+            await mkdir(join(archive, "extensions"), {
+                recursive: true,
+                mode: 0o700,
+            });
+        }
+        const archived = [];
+        for (const item of incompatible) {
+            options.signal?.throwIfAborted();
+            let destination;
+            for (const suffix of [
+                "",
+                "-2",
+                "-3",
+                "-4",
+                "-5",
+                "-6",
+                "-7",
+                "-8",
+                "-9",
+            ]) {
+                const candidate = join(archive, item.folder, `${item.name}${suffix}`);
+                if (!(await exists(candidate))) {
+                    destination = candidate;
+                    break;
+                }
+            }
+            if (destination === undefined)
+                throw new Error(`Cannot archive ${item.from} under ${join(archive, item.folder)}: all destinations exist`);
+            try {
+                await rename(item.from, destination);
+            }
+            catch (cause) {
+                throw new Error(`Cannot archive ${item.from} to ${destination}`, {
+                    cause,
+                });
+            }
+            archived.push({ kind: item.kind, from: item.from, to: destination });
+        }
+        await writeLocalVersionMarker(home, {
+            release: news.release,
+            spore,
+            build: privateLocalServiceVersion(),
+        });
+        await unlink(pendingPath(home));
+        return {
+            kind: "upgraded",
+            report: {
+                from: prior,
+                to: news.release,
+                service,
+                archive: incompatible.length > 0 || existingArchive ? archive : undefined,
+                archived,
+                whatsNew: news.lines,
+            },
+        };
+    }
+    finally {
+        await release();
+    }
+}
+export function formatLocalUpgradeNotice(report) {
+    const from = report.from.kind === "recorded"
+        ? report.from.release
+        : report.from.kind === "protocol"
+            ? `an earlier Fungi (protocol ${String(report.from.protocol)})`
+            : "an earlier Fungi";
+    const lines = [`Upgraded ${from} → ${report.to}`];
+    if (report.service === "stopped")
+        lines.push("Stopped the old Fungi service.");
+    if (report.service === "killed")
+        lines.push("Stopped the old Fungi service after its exit deadline.");
+    if (report.archive !== undefined) {
+        const agents = report.archived.filter((item) => item.kind === "agent-store").length;
+        const activations = report.archived.find((item) => item.kind === "extension-activations");
+        const contents = [
+            ...(agents > 0
+                ? [`${String(agents)} Agent ${agents === 1 ? "store" : "stores"}`]
+                : []),
+            ...(activations !== undefined ? ["extension activations"] : []),
+        ].join(" and ");
+        lines.push(report.archived.length === 0
+            ? "The earlier archive is still at"
+            : `Archived ${contents} to`, `  ${report.archive} (nothing was deleted)`);
+        if (activations !== undefined)
+            lines.push(`  Extension activations: ${activations.to}`);
+    }
+    const news = report.whatsNew.slice(0, 3);
+    if (news.length > 0)
+        lines.push("What's new:", ...news.map((line) => `  • ${line}`));
+    return lines;
+}

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

@@ -4,6 +4,8 @@ import { createConversationAgents } from "@fungi.computer/shiitake-extensions/ro
 export type LocalCreateRequest = Parameters<NonNullable<AgentControlDirectory["create"]>>[0] & Readonly<{
     /** The Agent creating, resolved by the creator's own host, never by the caller. */
     createdBy: string;
+    /** The creating Session, captured by the Local Agent-control host. */
+    createdBySessionId: string;
 }>;
 /**
  * One ordinary Agent as the project's directory lists it. `unreadable` is
@@ -34,11 +36,13 @@ export type LocalArchiveRequest = Readonly<{
  * creating Agent, so the directory owner can hold the created Agent to what
  * the creator holds; its archive names who archives.
  */
-export type LocalAgentControlDirectory = Omit<AgentControlDirectory, "create" | "list" | "archive" | "unarchive"> & Readonly<{
+export type LocalAgentControlDirectory = Omit<AgentControlDirectory, "create" | "list" | "archive" | "unarchive" | "answer" | "escalate"> & Readonly<{
     list: (signal: AbortSignal, options?: Readonly<{
         archived?: boolean;
     }>) => Promise<readonly LocalAgentControlAgent[]>;
     create: (input: LocalCreateRequest, signal: AbortSignal) => Promise<AgentControlAgent>;
+    answer: (input: Parameters<NonNullable<AgentControlDirectory["answer"]>>[0], senderAgentId: string, senderSessionId: string, signal: AbortSignal) => ReturnType<NonNullable<AgentControlDirectory["answer"]>>;
+    escalate: (input: Parameters<NonNullable<AgentControlDirectory["escalate"]>>[0], senderAgentId: string, senderSessionId: string, signal: AbortSignal) => ReturnType<NonNullable<AgentControlDirectory["escalate"]>>;
     archive: (input: LocalArchiveRequest, signal: AbortSignal) => Promise<void>;
     unarchive: (input: LocalArchiveRequest, signal: AbortSignal) => Promise<void>;
 }>;
@@ -57,6 +61,7 @@ export declare function createPrivateLocalAgentControl(input: Readonly<{
         acquire: (context: import("@fungi.computer/mycelium").CapabilitySourceContext) => Promise<import("@fungi.computer/mycelium").CapabilitySourceAcquisition>;
     }>;
     source: Readonly<{
+        hasLiveChildCommand: (sessionId: string) => boolean;
         read: (sessionId: string, limit: number) => Promise<Readonly<{
             agents: readonly import("@fungi.computer/shiitake-extensions/subagents/host").SubagentRecord[];
             more: number;
@@ -72,6 +77,8 @@ export declare function createPrivateLocalAgentControl(input: Readonly<{
         }>) => Promise<readonly AgentControlAgent[]>;
         send?: (input: import("@fungi.computer/shiitake/agent-control").AgentDelegationInput, sourceSessionId: string, signal: AbortSignal, invocation?: import("@fungi.computer/shiitake/agent-control").AgentDelegationInvocation) => Promise<import("@fungi.computer/shiitake").Accepted | import("@fungi.computer/shiitake").Held>;
         recall?: (input: import("@fungi.computer/shiitake/agent-control").AgentRecallInput, sourceSessionId: string, signal: AbortSignal) => Promise<import("@fungi.computer/shiitake").CancelResult>;
+        answer?: (input: import("@fungi.computer/shiitake/agent-control").AgentControlAnswerInput, senderSessionId: string, signal: AbortSignal) => Promise<import("@fungi.computer/shiitake/agent-control").AgentControlAnswerOutput>;
+        escalate?: (input: import("@fungi.computer/shiitake/agent-control").AgentControlEscalateInput, senderSessionId: string, signal: AbortSignal) => Promise<import("@fungi.computer/shiitake/agent-control").AgentControlEscalateOutput>;
         create?: (input: Readonly<{
             requestId: string;
             name?: string;

package/dist/private-local-agent-control.js

@@ -8,7 +8,7 @@ import { createConversationAgents } from "@fungi.computer/shiitake-extensions/ro
 export function createPrivateLocalAgentControl(input) {
     const conversations = createConversationAgents(input.storage);
     function bound(parentSessionId) {
-        const { create, archive, unarchive } = input.directory;
+        const { create, archive, unarchive, answer, escalate } = input.directory;
         const by = { kind: "agent", agentId: input.agentId };
         return {
             ...input.directory,
@@ -17,8 +17,22 @@ export function createPrivateLocalAgentControl(input) {
             create: async (request, signal) => {
                 if (parentSessionId === undefined)
                     throw new AgentCreateRefused("no_creator", "creation requires an invoking Session");
-                return create({ ...request, createdBy: input.agentId }, signal);
+                return create({
+                    ...request,
+                    createdBy: input.agentId,
+                    createdBySessionId: parentSessionId,
+                }, signal);
             },
+            answer: (request, sourceSessionId, signal) => parentSessionId === undefined
+                ? Promise.resolve({ status: "refused", reason: "no_provenance" })
+                : sourceSessionId !== parentSessionId
+                    ? Promise.resolve({ status: "refused", reason: "not_sender" })
+                    : answer(request, input.agentId, parentSessionId, signal),
+            escalate: (request, sourceSessionId, signal) => parentSessionId === undefined
+                ? Promise.resolve({ status: "refused", reason: "no_provenance" })
+                : sourceSessionId !== parentSessionId
+                    ? Promise.resolve({ status: "refused", reason: "not_sender" })
+                    : escalate(request, input.agentId, parentSessionId, signal),
         };
     }
     const control = conversations.control(bound);

package/dist/private-local-auth-rpc.d.ts

@@ -87,8 +87,13 @@ declare const wireResultSchema: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.
         category: z.ZodLiteral<"cancelled">;
     }, z.core.$strict>, z.ZodObject<{
         category: z.ZodLiteral<"no-key-entered">;
+    }, z.core.$strict>, z.ZodObject<{
+        category: z.ZodLiteral<"prompt-failed">;
+    }, z.core.$strict>, z.ZodObject<{
+        category: z.ZodLiteral<"missing-authorization-code">;
     }, z.core.$strict>, z.ZodObject<{
         category: z.ZodLiteral<"unknown">;
+        errorName: z.ZodString;
     }, z.core.$strict>], "category">;
 }, z.core.$strict>]>;
 declare class AuthPromptTarget extends RpcTarget {

package/dist/private-local-auth-rpc.js

@@ -80,6 +80,24 @@ const eventSchema = z.discriminatedUnion("type", [
     }),
 ]);
 const answerSchema = z.string().max(localAuthInputLimit);
+const errorNameSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9_]{0,63}$/u);
+/** A class name only: anything else (or a non-Error) is named generically. */
+function errorNameOf(cause) {
+    if (!(cause instanceof Error))
+        return "NonError";
+    const name = errorNameSchema.safeParse(cause.name);
+    return name.success ? name.data : "Error";
+}
+/**
+ * The person's own dialog could not show or answer a provider question (for
+ * example the prompt failed the renderer's contract). Fixed text, no cause.
+ */
+class LocalAuthPromptFailed extends Error {
+    constructor() {
+        super("Authentication prompt failed");
+        this.name = "LocalAuthPromptFailed";
+    }
+}
 /**
  * The closed set of failures that cross the service. Provider errors can
  * contain credential material, so no free text, cause or provider message
@@ -98,7 +116,13 @@ const localAuthFailureSchema = z.discriminatedUnion("category", [
     }),
     z.strictObject({ category: z.literal("cancelled") }),
     z.strictObject({ category: z.literal("no-key-entered") }),
-    z.strictObject({ category: z.literal("unknown") }),
+    z.strictObject({ category: z.literal("prompt-failed") }),
+    z.strictObject({ category: z.literal("missing-authorization-code") }),
+    z.strictObject({
+        category: z.literal("unknown"),
+        /** The thrown value's class name only, e.g. `TypeError`; never its message. */
+        errorName: errorNameSchema,
+    }),
 ]);
 const wireResultSchema = z.union([
     authResultSchema,
@@ -110,6 +134,7 @@ const wireResultSchema = z.union([
 /** Pi 1.3.0's fixed error prefixes; never retain a provider body suffix. */
 const callbackPortInUse = /^Port \d+ is in use\b/u;
 const oauthStateMismatch = "OAuth state mismatch";
+const missingAuthorizationCode = "Missing authorization code";
 const openAITokenRequestFailed = /^OpenAI OAuth token request failed \(([1-5]\d{2})\)/u;
 function classifyFailure(cause, aborted) {
     if (aborted)
@@ -133,7 +158,14 @@ function classifyFailure(cause, aborted) {
         return { category: "callback-port-in-use" };
     if (cause instanceof Error && cause.message === oauthStateMismatch)
         return { category: "oauth-state-mismatch" };
-    return { category: "unknown" };
+    if (cause instanceof LocalAuthPromptFailed)
+        return { category: "prompt-failed" };
+    if (cause instanceof Error && cause.message === missingAuthorizationCode)
+        return { category: "missing-authorization-code" };
+    return {
+        category: "unknown",
+        errorName: errorNameOf(cause),
+    };
 }
 /** Fixed wording per category; the dialog shows exactly this. */
 function failureText(failure) {
@@ -164,8 +196,12 @@ function failureText(failure) {
             return "Authentication cancelled";
         case "no-key-entered":
             return new LocalAuthRefusal().message;
+        case "prompt-failed":
+            return "The sign-in dialog could not show the provider's question (prompt-failed). Nothing was saved.";
+        case "missing-authorization-code":
+            return "No authorization code was found in what was pasted. Paste the code or the full redirect URL.";
         case "unknown":
-            return "Local authentication failed";
+            return `Local authentication failed (unknown: ${failure.errorName}). Nothing was saved.`;
     }
 }
 /** The client-side error for one typed failure; its message is fixed text. */
@@ -333,7 +369,13 @@ export class PrivateLocalAuthTarget extends RpcTarget {
                         try {
                             if (promptSignal.aborted)
                                 cancel();
-                            return answerSchema.parse(await pending.result());
+                            const answer = await pending.result().then((value) => ({ value }), (cause) => ({ cause }));
+                            if ("cause" in answer) {
+                                promptSignal.throwIfAborted();
+                                // The presenter's error text is not trusted to be secret-free.
+                                throw new LocalAuthPromptFailed();
+                            }
+                            return answerSchema.parse(answer.value);
                         }
                         finally {
                             promptSignal.removeEventListener("abort", cancel);

package/dist/private-local-client-version.js

@@ -5,7 +5,9 @@ import { basename, dirname, join } from "node:path";
 import { promisify } from "node:util";
 import { z } from "zod";
 const execute = promisify(execFile);
-const queryOptions = { timeout: 2_000, maxBuffer: 4_096 };
+// A compiled launcher cold-starts a Bun process; 2s sat at twice its quiet-box
+// time and killed the query on a loaded box.
+const queryOptions = { timeout: 10_000, maxBuffer: 4_096 };
 const buildId = z.string().regex(/^[a-f0-9]{64}$/u);
 function installedLauncherOnPath() {
     return new Promise((resolve, reject) => {

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

@@ -28,9 +28,27 @@ export declare function createPrivateLocalDelegation(input: Readonly<{
         name: string;
     }[] | undefined>) | undefined;
     accept: (mail: BirdDogMail, meta?: BirdDogMail["meta"], reply?: VerifiedAgentReply) => Promise<Accepted>;
+    /**
+     * What happens to items a child left waiting on this Agent when the work
+     * that was told about them ends. Without it a host leaves them to expire.
+     */
+    unattended?: Readonly<{
+        /** Exact settled facts of one command of this Agent's own Sessions. */
+        readSettlement: (sessionId: string, commandId: string) => Promise<CommandSettlement | undefined>;
+        /**
+         * Pass one child item on to a person, as this Agent's Session that was
+         * told about it. A child that already moved on answers that and nothing changes.
+         */
+        escalate: (item: Readonly<{
+            agentId: string;
+            sessionId: string;
+            itemId: string;
+        }>, receiverSessionId: string) => Promise<void>;
+    }>;
 }>): {
     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>;
+    close: () => Promise<void>;
     outstanding: () => Promise<import("@fungi.computer/shiitake/fleet").OutstandingDelegation | undefined>;
 };