@fungi.computer/truffle 0.1.1 → 0.2.1

package/dist/private-local-service.js

@@ -1,77 +1,134 @@
 import { FungiMcpSelectionConflict } from "./private-fungi-mcp-selection.js";
-import { LocalSessionPathConflict } from "./private-local-service-owner.js";
-export { LocalSessionPathConflict } from "./private-local-service-owner.js";
+import { logEvent } from "./log-event.js";
+import { readBoundedResponse } from "./private-bounded-response.js";
+import { LocalSandboxUnavailable, sandboxUnavailableReasonSchema, } from "./private-local-containment.js";
+export { LocalSandboxUnavailable } from "./private-local-containment.js";
+import { capturePrivateLocalConfigRoot } from "./private-local-config-root.js";
+import { stopAllResultSchema } from "./private-local-stop-all.js";
+import { LocalAgentSelectionAmbiguous, LocalSessionPathConflict, } from "./private-local-service-owner.js";
+export { LocalAgentSelectionAmbiguous, LocalSessionPathConflict, } from "./private-local-service-owner.js";
 import { EventSource } from "eventsource";
+import { AgentArchiveRefused } from "@fungi.computer/shiitake/agent-control";
+export { AgentArchiveRefused } from "@fungi.computer/shiitake/agent-control";
 import { newWebSocketRpcSession } from "@fungi.computer/capnweb";
 import { runPrivateLocalAuthRemote, } from "./private-local-auth-rpc.js";
 import { spawn } from "node:child_process";
-import { stat } from "node:fs/promises";
-import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { setTimeout as delay } from "node:timers/promises";
+import { readInstalledLocalClientBuildId } from "./private-local-client-version.js";
+export { readInstalledLocalClientBuildId } from "./private-local-client-version.js";
+export { privateLocalServiceVersion } from "./private-local-service-discovery.js";
 import { createShiitakeClient, parseSessionSnapshot, } from "@fungi.computer/shiitake/client";
-import { acquireServiceLock, assertNoUntrackedServiceOwner, handshake, modelChoicesSchema, readLiveServiceStatus, readServiceRecord, removeOwnedServiceRecord, selectedSchema, sessionDiscoverySchema, sessionInspectionSchema, serviceDirectory, serviceOwnerIsLive, } from "./private-local-service-discovery.js";
+import { acquireServiceLock, assertNoUntrackedServiceOwner, clearAbandonedServiceOwner, modelChoicesSchema, privateLocalServiceVersion, readLiveServiceStatus, readServiceRegistration, removeOwnedServiceRecord, removeUnidentifiedServiceRecord, selectedSchema, sandboxStatusSchema, sessionDiscoverySchema, archiveRefusalSchema, archiveRequestSchema, discoverRequestSchema, sessionInspectionSchema, serviceDirectory, serviceDirectoryPath, serviceOwnerIsLive, } from "./private-local-service-discovery.js";
+import { terminatePrivateLocalService } from "./private-local-service-termination.js";
+import { readServiceLeaseOwner } from "./private-local-service-lease.js";
 import { privateLocalEffectiveModelSchema } from "./private-local-effective-model.js";
-import { projectPrivateLocalSessionDiscovery } from "./private-local-session-discovery.js";
+import { LocalStoreSchemaError, projectPrivateLocalSessionDiscovery, } from "./private-local-session-discovery.js";
+export { LocalStoreSchemaError } from "./private-local-session-discovery.js";
 import { capturePrivateLocalExecPath, parsePrivateLocalExecPath, } from "./private-local-exec-path.js";
 import { z } from "zod";
+import { serviceDiagnosticsStatusSchema } from "./private-local-service-log.js";
 export { runPrivateLocalWorkerServer, } from "./private-local-worker-server.js";
+/** The 409 answers a select can give; each is one case of a closed union. */
+const selectionConflictSchema = z.discriminatedUnion("code", [
+    z.strictObject({
+        code: z.literal("sandbox_unavailable"),
+        reason: sandboxUnavailableReasonSchema,
+    }),
+    z.object({ code: z.literal("session_path_conflict") }),
+    z.object({ code: z.literal("store_in_use") }),
+    z.object({
+        code: z.literal("store_schema_incompatible"),
+        databasePath: z.string().min(1),
+        error: z.string().min(1),
+    }),
+    z.object({
+        code: z.literal("agent_selection_ambiguous"),
+        agentIds: z.array(z.string()),
+    }),
+]);
+/** Selection, creation and inspection share the listener's typed refusals. */
+async function rejectSelectionConflict(response) {
+    const body = await response.json().catch((cause) => {
+        console.error("Local service response unavailable", cause);
+        return undefined;
+    });
+    const conflict = selectionConflictSchema.safeParse(body);
+    if (conflict.success) {
+        if (conflict.data.code === "store_schema_incompatible")
+            throw new LocalStoreSchemaError(conflict.data.databasePath);
+        if (conflict.data.code === "sandbox_unavailable")
+            throw new LocalSandboxUnavailable(conflict.data.reason);
+        if (conflict.data.code === "session_path_conflict")
+            throw new LocalSessionPathConflict();
+        if (conflict.data.code === "agent_selection_ambiguous")
+            throw new LocalAgentSelectionAmbiguous(conflict.data.agentIds);
+        throw new Error("This Agent store is held by another Fungi service. Stop the older service process, then retry; keep the Agent store files.");
+    }
+    // An Agent-selection answer without its Agents is a broken service, not
+    // an MCP connection conflict.
+    if (z.object({ code: z.literal("agent_selection_ambiguous") }).safeParse(body)
+        .success)
+        throw new Error("Local service sent an unreadable Agent selection");
+    throw new FungiMcpSelectionConflict();
+}
+/** The listener's body for a failure it did not expect. */
+const serviceFailureSchema = z.object({
+    code: z.literal("internal_error"),
+    error: z.string(),
+});
+/** The service answered a selection with a failure status and no readable failure body. */
+export class LocalServiceUnreadableResponse extends Error {
+    name = "LocalServiceUnreadableResponse";
+    status;
+    constructor(status, cause) {
+        super(`Local service selection failed (${String(status)}) without a readable failure body`, { cause });
+        this.status = status;
+    }
+}
+/**
+ * A newer client replaced the service this running client reached with one
+ * that speaks another protocol. Only restarting the window can reconnect it.
+ */
+export class LocalServiceUpdated extends Error {
+    name = "LocalServiceUpdated";
+    constructor() {
+        super("The Fungi service was updated. Restart this window.");
+    }
+}
 /** Construction does not start a service or open a store. Call start/connect explicitly. */
 export function createPrivateLocalServiceManager(options = {}) {
+    const root = capturePrivateLocalConfigRoot(options.home);
+    const selectedDirectory = serviceDirectoryPath(options.directory ?? root.serviceDirectory);
+    const reportCleanupFailure = options.reportCleanupFailure ??
+        ((cause) => {
+            process.stderr.write(`Local service cleanup failed (${cause instanceof Error ? cause.name : "NonError"}).\n`);
+        });
     const clientPath = options.executionPath === undefined
         ? capturePrivateLocalExecPath(process.env.PATH ?? "/usr/bin:/bin", process.cwd())
         : parsePrivateLocalExecPath(options.executionPath);
-    const expectedBuildId = z
-        .string()
-        .regex(/^[a-f0-9]{64}$/u)
-        .optional()
-        .parse(process.env.FUNGI_BUNDLED_BUILD_ID);
-    function acceptBuild(ready) {
-        if (ready.buildId !== expectedBuildId)
-            throw new Error("The running service belongs to a different Fungi build. Finish active turns, run fungi stop, then reopen Fungi. Saved Sessions are preserved.");
-        return ready;
+    const expectedVersion = privateLocalServiceVersion();
+    /**
+     * Set once this client has reached a service. Only a starting client
+     * replaces a service speaking another protocol. Same-protocol build changes
+     * still require the installed-client check; reaching a service is not proof
+     * that this window remains the installed client.
+     */
+    let reachedService = false;
+    function accept(service) {
+        reachedService = true;
+        return service;
     }
     const maximumInspectionResponseBytes = 2_097_152;
-    async function readBoundedResponse(response) {
-        const declared = response.headers.get("content-length");
-        if (declared !== null) {
-            const declaredBytes = Number(declared);
-            if (!Number.isSafeInteger(declaredBytes) ||
-                declaredBytes < 0 ||
-                declaredBytes > maximumInspectionResponseBytes)
-                throw new Error("Local Session inspection response is too large");
-        }
-        if (response.body === null)
-            throw new Error("Local Session inspection returned no body");
-        const stream = response.body.pipeThrough(new TransformStream());
-        const reader = stream.getReader();
-        const chunks = [];
-        let size = 0;
-        for (;;) {
-            const next = await reader.read();
-            if (next.done)
-                break;
-            const bytes = next.value;
-            size += bytes.byteLength;
-            if (size > maximumInspectionResponseBytes) {
-                await reader.cancel();
-                throw new Error("Local Session inspection response is too large");
-            }
-            chunks.push(bytes);
-        }
-        const joined = new Uint8Array(size);
-        let offset = 0;
-        for (const chunk of chunks) {
-            joined.set(chunk, offset);
-            offset += chunk.byteLength;
-        }
-        return new TextDecoder().decode(joined);
-    }
     async function status(timeoutMs) {
-        const record = await readServiceRecord(await serviceDirectory(options.directory));
-        if (record === undefined)
+        const directory = selectedDirectory;
+        const registration = await readServiceRegistration(directory);
+        if (registration?.kind === "other-protocol" &&
+            (await serviceOwnerIsLive(directory)))
+            throw new LocalServiceUpdated();
+        if (registration?.kind !== "current")
             return undefined;
-        const probe = await readLiveServiceStatus(record, timeoutMs);
+        const probe = await readLiveServiceStatus(registration.record, timeoutMs);
         return probe.kind === "running" ? probe.service : undefined;
     }
     /**
@@ -85,38 +142,94 @@ export function createPrivateLocalServiceManager(options = {}) {
         while (Date.now() < deadline) {
             request.signal?.throwIfAborted();
             const ready = await status(Math.min(10_000, waitMs));
-            if (ready)
-                return acceptBuild(ready);
+            if (ready) {
+                if (ready.version === expectedVersion)
+                    return accept(ready);
+                // It answered at last, as another version: replace it under the lock.
+                const started = await startUnderLock(request);
+                if (started !== "busy")
+                    return started;
+            }
             await delay(250, undefined, { signal: request.signal });
         }
         throw new Error(`The Fungi service is running but has not answered for ${String(Math.round(waitMs / 1000))} seconds; the machine may be overloaded. Retry, or run fungi stop after its turns finish.`);
     }
-    async function ownerLockReleased(directory) {
-        try {
-            await stat(join(directory, "owner.lock"));
-            return false;
-        }
-        catch (cause) {
-            if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
-                return true;
-            throw cause;
-        }
-    }
     async function start(request = {}) {
         const started = await startUnderLock(request);
         return started === "busy" ? awaitBusyService(request) : started;
     }
+    /** `fungi stop`'s work, under the startup lock that serializes it with starts. */
+    async function stopUnderLock(directory, expectedServiceId) {
+        const registration = await readServiceRegistration(directory);
+        if (registration === undefined)
+            return { kind: "not-running", recordCleaned: false };
+        if (registration.kind === "unidentified") {
+            if (await serviceOwnerIsLive(directory))
+                throw new Error(`A Fungi service this client cannot identify owns ${directory}. End that Fungi service process, then retry; saved Sessions are kept.`);
+            await removeUnidentifiedServiceRecord(directory);
+            return { kind: "not-running", recordCleaned: true };
+        }
+        const lifecycle = registration.kind === "current"
+            ? registration.record
+            : registration.lifecycle;
+        if (expectedServiceId !== undefined &&
+            lifecycle.serviceId !== expectedServiceId)
+            return { kind: "replaced" };
+        const owner = await readServiceLeaseOwner(directory);
+        if (owner === undefined) {
+            await removeOwnedServiceRecord(directory, lifecycle.serviceId);
+            return { kind: "not-running", recordCleaned: true };
+        }
+        // The file points at a claim; it cannot supply signal authority itself.
+        if (owner.pid !== lifecycle.pid || owner.startedAt !== lifecycle.startedAt)
+            throw new Error(`The Fungi lease owner in ${directory} does not match service.json; retry after the owner registers itself. No process was signalled.`);
+        const outcome = await terminatePrivateLocalService(directory, owner);
+        // A killed process cannot remove its own record or lifetime lock.
+        await removeOwnedServiceRecord(directory, lifecycle.serviceId);
+        await clearAbandonedServiceOwner(directory);
+        return { kind: outcome };
+    }
+    /**
+     * Reuse the registered service when this client can, otherwise stop it so a
+     * service of this version can start; undefined means start one.
+     */
+    async function reuseOrReplace(directory, registration) {
+        if (registration.kind === "current") {
+            const probe = await readLiveServiceStatus(registration.record);
+            // Not answering: the lifetime lease decides between busy and gone.
+            if (probe.kind !== "running")
+                return undefined;
+            if (probe.service.version === expectedVersion)
+                return probe.service;
+            // Replace only for the installed client. A stale window (or an
+            // uninstalled source run) must not stop the service; it restarts.
+            if (expectedVersion !== (await readInstalledLocalClientBuildId()))
+                throw new LocalServiceUpdated();
+        }
+        else if (registration.kind === "other-protocol" && reachedService) {
+            if (await serviceOwnerIsLive(directory))
+                throw new LocalServiceUpdated();
+        }
+        if (registration.kind === "other-protocol" &&
+            expectedVersion !== (await readInstalledLocalClientBuildId()))
+            throw new LocalServiceUpdated();
+        await stopUnderLock(directory);
+        return undefined;
+    }
     async function startUnderLock(request) {
         request.signal?.throwIfAborted();
-        const directory = await serviceDirectory(options.directory);
+        const directory = await serviceDirectory(selectedDirectory);
         const release = await acquireServiceLock(directory, "startup");
         try {
-            const existing = await status();
+            const registration = await readServiceRegistration(directory);
+            const existing = registration === undefined
+                ? undefined
+                : await reuseOrReplace(directory, registration);
             request.signal?.throwIfAborted();
             if (existing)
-                return acceptBuild(existing);
+                return accept(existing);
             await assertNoUntrackedServiceOwner(directory);
-            if (serviceOwnerIsLive(directory))
+            if (await serviceOwnerIsLive(directory))
                 return "busy";
             const bundledCli = process.env.FUNGI_BUNDLED_CLI;
             const child = spawn(options.executable ?? process.execPath, bundledCli === undefined
@@ -124,7 +237,13 @@ export function createPrivateLocalServiceManager(options = {}) {
                     fileURLToPath(new URL("./private-local-service-process.js", import.meta.url)),
                     directory,
                 ]
-                : [bundledCli, "--internal-service", directory], { detached: true, stdio: "ignore" });
+                : [bundledCli, "--internal-service", directory], {
+                detached: true,
+                stdio: "ignore",
+                // Service startup retains its existing inherited inputs. This is
+                // not a Computer exec child: only its selected host HOME is pinned.
+                env: { ...process.env, HOME: root.home },
+            });
             let failure;
             let exited = false;
             const readFailure = () => failure;
@@ -141,8 +260,11 @@ export function createPrivateLocalServiceManager(options = {}) {
                 if (childFailure !== undefined)
                     throw childFailure;
                 const ready = await status();
-                if (ready)
-                    return acceptBuild(ready);
+                if (ready) {
+                    if (ready.version !== expectedVersion)
+                        throw new Error(`The started Local service reports version ${ready.version}, not this client's ${expectedVersion}`);
+                    return accept(ready);
+                }
                 if (hasExited())
                     throw new Error("Local service exited before its handshake");
                 await delay(100, undefined, { signal: request.signal });
@@ -158,59 +280,183 @@ export function createPrivateLocalServiceManager(options = {}) {
             await release();
         }
     }
-    const openConnection = async (endpoint, input, request = {}) => {
-        request.signal?.throwIfAborted();
-        const service = await start(request);
+    /** POST one selection to `service`; every refusal is a typed failure. */
+    const postSelection = async (endpoint, input, service, signal) => {
         const init = {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ ...input, clientPath }),
             redirect: "error",
         };
-        if (request.signal !== undefined)
-            init.signal = request.signal;
+        if (signal !== undefined)
+            init.signal = signal;
         const response = await fetch(`${service.baseUrl}/service/${service.serviceId}/${endpoint}`, init);
-        if (response.status === 409) {
-            const conflict = z.object({ code: z.string() }).safeParse(await response.json().catch((cause) => {
-                console.error("Local service response unavailable", cause);
-                return undefined;
+        if (response.status === 409)
+            await rejectSelectionConflict(response);
+        if (!response.ok) {
+            // The service names its own failure in a JSON body; one without it is
+            // a broken response, not a status to guess from.
+            const failure = serviceFailureSchema.safeParse(await response.json().catch((cause) => {
+                throw new LocalServiceUnreadableResponse(response.status, cause);
             }));
-            if (conflict.success && conflict.data.code === "session_path_conflict")
-                throw new LocalSessionPathConflict();
-            if (conflict.success && conflict.data.code === "store_in_use")
-                throw new Error("This Agent store is held by another Fungi service. Stop the older service process, then retry; keep the Agent store files.");
-            throw new FungiMcpSelectionConflict();
+            if (!failure.success)
+                throw new LocalServiceUnreadableResponse(response.status, failure.error);
+            throw new Error(`Local service selection failed (${String(response.status)}): ${failure.data.error}`);
+        }
+        return selectedSchema.parse(await response.json());
+    };
+    const routeBase = (service, selected) => `${service.baseUrl}/service/${service.serviceId}${selected.routePath}`;
+    const openConnection = async (endpoint, input, request = {}) => {
+        request.signal?.throwIfAborted();
+        const service = await start(request);
+        const selected = await postSelection(endpoint, input, service, request.signal);
+        const firstBase = routeBase(service, selected);
+        /**
+         * Where this connection's client currently talks. A restarted service
+         * comes back on a new port with a new id, so the client's requests are
+         * redirected here rather than the client rebuilt: its Session address
+         * and everything the TUI keyed on it stay the same.
+         */
+        let route = { service, base: firstBase };
+        let closing;
+        const isClosing = () => closing !== undefined;
+        const reroute = (url) => url === firstBase || url.startsWith(`${firstBase}/`)
+            ? route.base + url.slice(firstBase.length)
+            : url;
+        const transport = globalThis.fetch;
+        const releaseRoute = async (base) => {
+            try {
+                const response = await transport(`${base}/`, {
+                    method: "DELETE",
+                    redirect: "error",
+                    signal: AbortSignal.timeout(5_000),
+                });
+                if (!response.ok && response.status !== 404)
+                    throw new Error(`Local client release failed (${String(response.status)})`);
+            }
+            catch (error) {
+                if (options.reportCleanupFailure === undefined)
+                    logEvent("service-client.release", error);
+                else
+                    options.reportCleanupFailure(error);
+            }
+        };
+        const reroutedFetch = Object.assign((target, init) => {
+            if (target instanceof Request)
+                throw new TypeError("A Local service connection fetches by URL");
+            return transport(reroute(String(target)), init);
+        }, { preconnect: transport.preconnect });
+        const Source = options.eventSource ?? EventSource;
+        class ReroutedEventSource extends Source {
+            constructor(url) {
+                super(reroute(url));
+                // The library would retry the address it was built with, forever and
+                // silently. A dropped stream is surfaced instead, so the owner of the
+                // connection can rebind it and reopen the observation.
+                this.addEventListener("error", () => {
+                    this.close();
+                });
+            }
         }
-        if (!response.ok)
-            throw new Error(`Local service selection failed (${String(response.status)})`);
-        const selected = selectedSchema.parse(await response.json());
-        const baseUrl = `${service.baseUrl}/service/${service.serviceId}${selected.routePath}`;
         const client = createShiitakeClient({
-            baseUrl,
-            eventSource: options.eventSource ?? EventSource,
+            baseUrl: firstBase,
+            fetch: reroutedFetch,
+            eventSource: ReroutedEventSource,
         });
         return {
-            service,
+            get service() {
+                return route.service;
+            },
             agentId: selected.agentId,
             databasePath: selected.databasePath,
             sessionId: selected.sessionId,
             client,
             session: client.session(selected.sessionId),
+            sandboxStatus: async (request = {}) => {
+                request.signal?.throwIfAborted();
+                const init = { redirect: "error" };
+                if (request.signal !== undefined)
+                    init.signal = request.signal;
+                const response = await transport(`${route.base}/sandbox`, init);
+                if (!response.ok)
+                    throw new Error(`Local sandbox status read failed (${String(response.status)})`);
+                return sandboxStatusSchema.parse(await response.json());
+            },
+            stopAll: async () => {
+                const response = await fetch(`${route.service.baseUrl}/service/${route.service.serviceId}/stop-all`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({
+                        invocationRoot: input.invocationRoot,
+                        agentId: selected.agentId,
+                    }),
+                    redirect: "error",
+                });
+                if (!response.ok)
+                    throw new Error(`Stop all failed (${String(response.status)})`);
+                return stopAllResultSchema.parse(await response.json());
+            },
             effectiveModel: async (request = {}) => {
                 request.signal?.throwIfAborted();
                 const init = { redirect: "error" };
                 if (request.signal !== undefined)
                     init.signal = request.signal;
-                const response = await fetch(`${baseUrl}/sessions/${encodeURIComponent(selected.sessionId)}/effective-model`, init);
+                const response = await transport(`${route.base}/sessions/${encodeURIComponent(selected.sessionId)}/effective-model`, init);
                 if (!response.ok)
                     throw new Error(`Local effective model read failed (${String(response.status)})`);
                 return privateLocalEffectiveModelSchema.parse(await response.json());
             },
-            close: () => client.close(),
+            rebind: async (rebindRequest = {}) => {
+                if (isClosing())
+                    throw new Error("Local service connection is closed");
+                rebindRequest.signal?.throwIfAborted();
+                // A healthy probe does not guarantee that selection will answer.
+                // Bound each attempt independently of the pane's lifetime.
+                const deadline = AbortSignal.timeout(5_000);
+                const signal = rebindRequest.signal === undefined
+                    ? deadline
+                    : AbortSignal.any([rebindRequest.signal, deadline]);
+                // Read service.json again, and never start a service: whoever
+                // stopped it decides when it returns.
+                const ready = await status();
+                if (ready === undefined)
+                    return { kind: "unavailable" };
+                accept(ready);
+                const again = await postSelection("select", {
+                    invocationRoot: input.invocationRoot,
+                    databasePath: selected.databasePath,
+                    sessionId: selected.sessionId,
+                    fungiMcp: input.fungiMcp,
+                    uiAttachmentLifetime: input.uiAttachmentLifetime,
+                }, ready, signal);
+                if (again.agentId !== selected.agentId ||
+                    again.sessionId !== selected.sessionId)
+                    throw new Error("The restarted Local service selected a different Session");
+                const nextBase = routeBase(ready, again);
+                if (isClosing()) {
+                    await releaseRoute(nextBase);
+                    throw new Error("Local service connection is closed");
+                }
+                const previous = route;
+                route = { service: ready, base: nextBase };
+                if (previous.service.serviceId === ready.serviceId)
+                    await releaseRoute(previous.base);
+                return { kind: "rebound", service: ready };
+            },
+            close: () => {
+                closing ??= (async () => {
+                    const base = route.base;
+                    // Stop local observations first, including when the service is gone.
+                    await client.close();
+                    await releaseRoute(base);
+                })();
+                return closing;
+            },
         };
     };
     const connect = (selection, request) => openConnection("select", selection, request);
     const inspectResponseSchema = z.strictObject({
+        diagnostics: serviceDiagnosticsStatusSchema,
         selected: selectedSchema,
         snapshot: z.unknown(),
     });
@@ -225,7 +471,10 @@ export function createPrivateLocalServiceManager(options = {}) {
             const init = {
                 method: "POST",
                 headers: { "Content-Type": "application/json" },
-                body: JSON.stringify({ invocationRoot }),
+                body: JSON.stringify(discoverRequestSchema.parse({
+                    invocationRoot,
+                    archived: request.archived,
+                })),
                 redirect: "error",
             };
             if (request.signal !== undefined)
@@ -235,6 +484,32 @@ export function createPrivateLocalServiceManager(options = {}) {
                 throw new Error(`Local session discovery failed (${String(response.status)})`);
             return projectPrivateLocalSessionDiscovery(sessionDiscoverySchema.parse(await response.json()), connect);
         },
+        async archive(archival, request = {}) {
+            request.signal?.throwIfAborted();
+            const service = await start(request);
+            const init = {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(archiveRequestSchema.parse(archival)),
+                redirect: "error",
+            };
+            if (request.signal !== undefined)
+                init.signal = request.signal;
+            const response = await fetch(`${service.baseUrl}/service/${service.serviceId}/archive`, init);
+            if (response.status === 409) {
+                const refusal = archiveRefusalSchema.safeParse(await response.json().catch((cause) => {
+                    throw new LocalServiceUnreadableResponse(response.status, cause);
+                }));
+                if (refusal.success)
+                    throw new AgentArchiveRefused(refusal.data.reason, refusal.data.error);
+            }
+            if (!response.ok) {
+                const failure = serviceFailureSchema.safeParse(await response.json().catch((cause) => {
+                    throw new LocalServiceUnreadableResponse(response.status, cause);
+                }));
+                throw new Error(`Local Agent archive failed (${String(response.status)})${failure.success ? `: ${failure.data.error}` : ""}`);
+            }
+        },
         async inspect(selection, request = {}) {
             request.signal?.throwIfAborted();
             const service = await start(request);
@@ -251,15 +526,18 @@ export function createPrivateLocalServiceManager(options = {}) {
             if (request.signal !== undefined)
                 init.signal = request.signal;
             const response = await fetch(`${service.baseUrl}/service/${service.serviceId}/inspect`, init);
+            if (response.status === 409)
+                await rejectSelectionConflict(response);
             if (!response.ok)
                 throw new Error(`Local Session inspection failed (${String(response.status)})`);
-            const decoded = inspectResponseSchema.parse(JSON.parse(await readBoundedResponse(response)));
+            const decoded = inspectResponseSchema.parse(JSON.parse(await readBoundedResponse(response, maximumInspectionResponseBytes, "Local Session inspection")));
             const baseUrl = `${service.baseUrl}/service/${service.serviceId}${decoded.selected.routePath}`;
             const client = createShiitakeClient({
                 baseUrl,
                 eventSource: options.eventSource ?? EventSource,
             });
             return {
+                diagnostics: decoded.diagnostics,
                 session: client.session(decoded.selected.sessionId),
                 snapshot: parseSessionSnapshot(JSON.stringify(decoded.snapshot)),
                 close: () => client.close(),
@@ -274,7 +552,7 @@ export function createPrivateLocalServiceManager(options = {}) {
             const socket = new WebSocket(url);
             const remote = newWebSocketRpcSession(socket);
             try {
-                return await runPrivateLocalAuthRemote(remote, request, interaction);
+                return await runPrivateLocalAuthRemote(remote, request, interaction, reportCleanupFailure);
             }
             finally {
                 socket.close();
@@ -291,36 +569,34 @@ export function createPrivateLocalServiceManager(options = {}) {
                 throw new Error(`Local service model catalogue failed (${String(response.status)})`);
             return modelChoicesSchema.parse(await response.json());
         },
+        async reload(invocationRoot) {
+            const service = await status();
+            if (service === undefined)
+                throw new Error("Local service is not running");
+            const response = await fetch(`${service.baseUrl}/service/${service.serviceId}/reload`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ invocationRoot, clientPath }),
+                redirect: "error",
+                signal: AbortSignal.timeout(30_000),
+            });
+            const result = z
+                .union([
+                z.strictObject({ message: z.string() }),
+                z.strictObject({ error: z.string() }),
+            ])
+                .parse(await response.json());
+            if ("error" in result)
+                throw new Error(result.error);
+            if (!response.ok)
+                throw new Error(`Configuration reload failed (${String(response.status)})`);
+            return result.message;
+        },
         async stop(expectedServiceId) {
-            const directory = await serviceDirectory(options.directory);
+            const directory = await serviceDirectory(selectedDirectory);
             const release = await acquireServiceLock(directory, "startup");
             try {
-                const service = await readServiceRecord(directory);
-                if (service === undefined)
-                    return { kind: "not-running", recordCleaned: false };
-                if (expectedServiceId !== undefined &&
-                    service.serviceId !== expectedServiceId)
-                    return { kind: "replaced" };
-                const probe = await readLiveServiceStatus(service);
-                if (probe.kind === "not-running" && !serviceOwnerIsLive(directory)) {
-                    await removeOwnedServiceRecord(directory, service.serviceId);
-                    return { kind: "not-running", recordCleaned: true };
-                }
-                if (probe.kind !== "running")
-                    throw new Error("Local service is not answering; retry after its active turns finish.");
-                const response = await fetch(`${service.baseUrl}/service/${service.serviceId}/stop`, {
-                    method: "POST",
-                    redirect: "error",
-                });
-                if (!response.ok)
-                    throw new Error("Local service refused shutdown");
-                for (let attempt = 0; attempt < 100; attempt += 1) {
-                    if (!(await handshake(service)) &&
-                        (await ownerLockReleased(directory)))
-                        return { kind: "stopped" };
-                    await delay(100);
-                }
-                throw new Error("Local service shutdown has not released its owner lock");
+                return await stopUnderLock(directory, expectedServiceId);
             }
             finally {
                 await release();