@fungi.computer/truffle 0.1.1 → 0.2.0

package/dist/private-local-service-owner.js

@@ -1,45 +1,280 @@
+import * as Effect from "effect/Effect";
 import { logEvent } from "./log-event.js";
-import { readFungiMcpSelection, sameFungiMcpConnection, FungiMcpSelectionConflict, } from "./private-fungi-mcp-selection.js";
+import { createPrivateModels } from "./local-models.js";
+import { capturePrivateLocalConfigRoot, } from "./private-local-config-root.js";
+import { AdmissionGate } from "./private-local-admission-gate.js";
+import { readFungiMcpSelection, readProjectFungiMcpSelection, sameFungiMcpConnection, FungiMcpSelectionConflict, } from "./private-fungi-mcp-selection.js";
 import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { AgentCreateRefused, AgentArchiveRefused, } from "@fungi.computer/shiitake/agent-control";
+import { localExtensions, LocalExtensionError, } from "./local-extensions.js";
 import { readFile, realpath } from "node:fs/promises";
 import writeFileAtomic from "write-file-atomic";
 import { z } from "zod";
 import * as Schema from "effect/Schema";
 import { selectionSchema } from "./private-local-service-discovery.js";
 import { createShiitakeHttpRoutes } from "@fungi.computer/shiitake/http";
-import { listPrivateLocalAgentStores, readPrivateLocalSessionSummaries, } from "./private-local-session-discovery.js";
+import { listPrivateLocalAgentStores, LocalStoreSchemaError, readPrivateLocalAgentProfile, readPrivateLocalSessionSummaries, isArchivedStore, unreadableStoreReason, } from "./private-local-session-discovery.js";
 import { createPrivateLocalSessionRequestId, openPrivateLocalRuntimeHost, resolvePrivateLocalCreateStore, } from "./private-local-runtime-host.js";
+import { parsePrivateLocalExecPath } from "./private-local-exec-path.js";
+import { createLocalMeshLinks, localMeshLinkKey, } from "./private-local-mesh-links.js";
+import { agentMailAddressSchema, machineAgentRequestSchema, machineDirectorySchema, } from "@fungi.computer/seam/machine-link-protocol";
+import { parseAccepted } from "@fungi.computer/shiitake/client";
+import { commandSettlementSchema } from "@fungi.computer/shiitake/fleet";
+import { BirdDogMailSchema } from "@fungi.computer/bird-dog/effect";
 export class LocalSessionPathConflict extends Error {
     name = "LocalSessionPathConflict";
     constructor() {
         super("PATH differs for this live session; close its clients and restart the Local service before reconnecting from another toolchain");
     }
 }
+/**
+ * A folder holds several Agent stores and the request chose none of them.
+ * The service never picks one for the caller; --agent, --db or the
+ * landing screen does.
+ */
+export class LocalAgentSelectionAmbiguous extends Error {
+    name = "LocalAgentSelectionAmbiguous";
+    agentIds;
+    constructor(agentIds) {
+        super(`Several Agents in this folder (${agentIds.join(", ")}); choose one with --agent <id> or --db <path>`);
+        this.agentIds = agentIds;
+    }
+}
 // Reopen inputs only. Credentials remain with Local's account custodian.
 const recoveryOwnerSchema = selectionSchema
-    .omit({ clientPath: true, sessionId: true })
+    .omit({ clientPath: true, sessionId: true, uiAttachmentLifetime: true })
     .extend({ databasePath: z.string().min(1) });
 const decodeRecoveryFile = Schema.decodeUnknownResult(Schema.fromJsonString(Schema.Array(Schema.Unknown)));
+class LocalRecoveryPersistenceDisabled extends Error {
+    reason;
+    name = "LocalRecoveryPersistenceDisabled";
+    constructor(reason, cause) {
+        super("Recovery persistence is disabled: the manifest could not be loaded", {
+            cause,
+        });
+        this.reason = reason;
+    }
+}
 /** One service owns each store, independently of how many clients select it. */
-export function createLocalServiceOwners(openRuntime = openPrivateLocalRuntimeHost, recoveryDirectory) {
+export function createLocalServiceOwners(openRuntime = (input) => openPrivateLocalRuntimeHost(input, createPrivateModels(input.configRoot.credentialPath)), recoveryDirectory, 
+/** The installed-extension owner that decides what each Agent holds. */
+suppliedExtensions, 
+/** How often idle Agents are checked; one is released on its second idle check. */
+idleSweepMs = 60_000, 
+/** Read the recovery manifest; tests can hold this I/O independently of opens. */
+readRecoveryManifest = (path) => readFile(path, "utf8"), 
+/** Report only the classification, never the manifest or exception text. */
+onRecoveryDisabled = () => undefined, configRoot = capturePrivateLocalConfigRoot()) {
+    const extensions = suppliedExtensions ?? localExtensions({ home: configRoot.home });
     const recoveryPath = recoveryDirectory === undefined
         ? undefined
         : resolve(recoveryDirectory, "owners.json");
     const recovery = new Map();
+    let loadingRecovery;
     let saving = Promise.resolve();
     const emptySessions = new Map();
     const owners = new Map();
-    const opening = new Set();
+    const roots = new Map();
+    const meshDirectories = new Map();
+    async function meshAdmission(localAgentId, recipientAgentId) {
+        for (const { record, agents } of meshDirectories.values()) {
+            const binding = record.bindings.find((candidate) => candidate.agentId === recipientAgentId);
+            if (binding !== undefined &&
+                record.agents[binding.selection]?.localAgentId === localAgentId &&
+                (await mesh.isCurrent(record)))
+                return agents;
+        }
+        return undefined;
+    }
+    const mesh = createLocalMeshLinks({
+        credentialPath: configRoot.credentialPath,
+        receive: async (record, envelope) => {
+            if (envelope.kind === "machineDirectory") {
+                const address = z
+                    .strictObject({ teamId: z.string(), deviceId: z.string() })
+                    .parse(envelope.address);
+                if (address.teamId !== record.scopeId ||
+                    address.deviceId !== record.deviceId)
+                    return "refused";
+                const projection = Schema.decodeUnknownSync(machineDirectorySchema, {
+                    onExcessProperty: "error",
+                })(envelope.event);
+                meshDirectories.set(localMeshLinkKey(record), {
+                    record,
+                    agents: projection.agents,
+                });
+                return "accepted";
+            }
+            const address = Schema.decodeUnknownSync(agentMailAddressSchema, {
+                onExcessProperty: "error",
+            })(envelope.address);
+            const binding = record.bindings.find((candidate) => candidate.agentId === address.agentId);
+            const selected = binding === undefined ? undefined : record.agents[binding.selection];
+            if (address.scopeId !== record.scopeId || selected === undefined)
+                return "refused";
+            const { owner, release } = await directory(record.invocationRoot).owner(selected.localAgentId, new AbortController().signal);
+            try {
+                if (owner.databasePath !== selected.databasePath)
+                    return "refused";
+                if (envelope.kind === "machineAgent") {
+                    const { actorAgentId, operation } = Schema.decodeUnknownSync(machineAgentRequestSchema, {
+                        onExcessProperty: "error",
+                    })(envelope.event);
+                    if (operation.type === "createSession") {
+                        const sessionId = await admitted(owner, () => owner.createSession(operation.requestId));
+                        return { status: "accepted", receipt: { sessionId } };
+                    }
+                    const facts = await admitted(owner, () => owner.readSettlement(operation.sessionId, operation.commandId));
+                    if (facts !== undefined && facts.acceptedSender !== actorAgentId)
+                        return "refused";
+                    return {
+                        status: "accepted",
+                        receipt: {
+                            settlement: facts === undefined
+                                ? null
+                                : Schema.encodeSync(Schema.fromJsonString(commandSettlementSchema))(facts),
+                        },
+                    };
+                }
+                const mail = Schema.decodeUnknownSync(BirdDogMailSchema, {
+                    onExcessProperty: "error",
+                })(envelope.event);
+                if (envelope.kind !== "agentMail" ||
+                    envelope.key !== mail.key ||
+                    mail.to.agentId !== address.agentId ||
+                    new TextEncoder().encode(JSON.stringify(mail)).byteLength > 256 * 1024)
+                    return "refused";
+                // Only select the physical store here. Never rewrite frozen addresses
+                // or bypass that runtime's own recipient/sender admission.
+                const receipt = await admitted(owner, () => owner.acceptMail(mail));
+                return { status: "accepted", receipt };
+            }
+            finally {
+                release();
+            }
+        },
+    });
+    let configuration;
+    let reloading;
+    const pendingReload = () => reloading;
+    async function loadConfiguration(captured, invocationRoot, storeDirectory) {
+        const installed = await captured.load(storeDirectory, invocationRoot);
+        if (installed.diagnostics.length > 0)
+            throw new Error(installed.diagnostics
+                .map(({ extensionId, error }) => `${extensionId}: ${error.message}`)
+                .join("\n"));
+        const selected = captured.mcp.has(invocationRoot)
+            ? captured.mcp.get(invocationRoot)
+            : await readProjectFungiMcpSelection(invocationRoot);
+        return {
+            installed,
+            fungiMcp: selected === undefined
+                ? undefined
+                : readFungiMcpSelection(selected, {
+                    credentialPath: configRoot.credentialPath,
+                }),
+            clientPath: captured.clientPath,
+        };
+    }
+    function reload(invocationRoot, clientPath) {
+        if (reloading !== undefined)
+            return Promise.reject(new Error("A configuration reload is already in progress"));
+        const operation = (async () => {
+            ensureRunning();
+            const path = parsePrivateLocalExecPath(clientPath);
+            await Promise.all(pendingOpenings);
+            const projects = new Set([
+                ...roots.values(),
+                await realpath(invocationRoot),
+            ]);
+            const selections = new Map();
+            for (const project of projects)
+                selections.set(project, await readProjectFungiMcpSelection(project));
+            const candidate = {
+                load: await localExtensions({ home: configRoot.home }).captureAgent(),
+                mcp: selections,
+                clientPath: path,
+            };
+            const prepared = [];
+            const releases = [];
+            try {
+                for (const pending of new Set(owners.values())) {
+                    const { runtime } = await pending;
+                    releases.push(await gateFor(runtime.databasePath).lease());
+                    const root = roots.get(runtime.databasePath);
+                    if (root === undefined)
+                        throw new Error("Agent configuration root is unavailable");
+                    prepared.push(await runtime.prepareReload(await loadConfiguration(candidate, root, dirname(runtime.databasePath))));
+                }
+                ensureRunning();
+                for (const staged of prepared)
+                    staged.commit();
+                configuration = candidate;
+            }
+            catch (cause) {
+                const discarded = await Promise.allSettled(prepared.map((staged) => staged.discard()));
+                const failures = [];
+                for (const result of discarded)
+                    if (result.status === "rejected")
+                        failures.push(result.reason);
+                if (failures.length > 0)
+                    throw new AggregateError([cause, ...failures], "Configuration reload failed; candidate cleanup also failed", { cause });
+                throw cause;
+            }
+            finally {
+                for (const release of releases)
+                    release();
+                // A reload's leases end here; an unused gate must not pin its Agent.
+                for (const databasePath of gates.keys())
+                    pruneGate(databasePath);
+            }
+        })();
+        reloading = operation;
+        return operation.finally(() => {
+            reloading = undefined;
+        });
+    }
+    const gates = new Map();
+    const opening = new Map();
     const pendingOpenings = new Set();
     let stopping = false;
     let closing;
+    let restoring;
+    /** Requests, streams and operations currently using each open store. */
+    const uses = new Map();
+    /** Live event responses are observers, not work that survives orderly stop. */
+    const eventResponses = new Set();
+    /** Stores found idle by the previous sweep. */
+    const idleCandidates = new Set();
+    /** Released stores whose runtime is still closing; a reopen waits for it. */
+    const releasing = new Map();
+    const released = new WeakSet();
+    const openedByStore = new Map();
+    const routesByRuntime = new WeakMap();
+    let sweeping;
+    const sweepTimer = setInterval(() => {
+        void sweepIdle().catch((cause) => {
+            logEvent("service-owner.sweep-idle", cause);
+        });
+    }, idleSweepMs);
+    sweepTimer.unref();
     function saveRecovery() {
         if (recoveryPath === undefined)
             return Promise.resolve();
         const path = recoveryPath;
-        const next = saving.then(() => writeFileAtomic(path, JSON.stringify([...recovery.values()]), {
-            mode: 0o600,
-        }));
+        const next = saving.then(async () => {
+            // A ready listener may admit a new Agent during the initial read. Merge
+            // saved references before capturing any replacement list.
+            const loaded = await loadRecovery();
+            if (loaded.kind === "disabled") {
+                logEvent("service-owner.save-recovery-disabled", loaded.error);
+                return;
+            }
+            await writeFileAtomic(path, JSON.stringify([...recovery.values()]), {
+                mode: 0o600,
+            });
+        });
         // A recovery hint write must not hide a live owner or poison later saves.
         saving = next.catch((cause) => {
             logEvent("service-owner.save-recovery", cause);
@@ -50,12 +285,16 @@ export function createLocalServiceOwners(openRuntime = openPrivateLocalRuntimeHo
         const opened = pending;
         // Runtime ownership survives a failed recovery-reference write. Shutdown
         // must still drain it before the service can release its owner lock.
-        opening.add(opened);
-        void opened.catch((cause) => {
+        opening.set(opened, key);
+        void opened.then((owner) => {
+            opening.set(opened, owner.runtime.agentId);
+            openedByStore.set(owner.runtime.databasePath, opened);
+        }, (cause) => {
             opening.delete(opened);
             logEvent("service-owner.open-runtime", cause);
         });
         pending = pending.then(async (owner) => {
+            roots.set(owner.runtime.databasePath, invocationRoot);
             if (recoveryPath !== undefined) {
                 const reference = {
                     invocationRoot,
@@ -83,18 +322,278 @@ export function createLocalServiceOwners(openRuntime = openPrivateLocalRuntimeHo
         });
         return pending;
     }
+    function gateFor(databasePath) {
+        let gate = gates.get(databasePath);
+        if (gate === undefined) {
+            gate = new AdmissionGate();
+            gates.set(databasePath, gate);
+        }
+        return gate;
+    }
+    /** Admit one piece of work to an Agent, refusing it if the Agent is archived by then. */
+    async function admitted(owner, admit) {
+        const release = await gateFor(owner.databasePath).lease();
+        try {
+            if (isArchivedStore(owner.databasePath))
+                throw new AgentArchiveRefused("archived", `Agent ${owner.agentId} is archived; unarchive it to work with it`);
+            return await admit();
+        }
+        finally {
+            release();
+            pruneGate(owner.databasePath);
+        }
+    }
+    /** The gate of an Agent whose last admission just ended is forgotten. */
+    function pruneGate(databasePath) {
+        if (gates.get(databasePath)?.idle === true)
+            gates.delete(databasePath);
+    }
+    /**
+     * One Session as a client may use it: work starts (a prompt, a compaction, a
+     * send) only through an admission that finds the Agent in use.
+     */
+    function gatedSession(owner, sessionId, attachment) {
+        const session = owner.getSession(sessionId, attachment);
+        function command(input) {
+            return input.type === "prompt" || input.type === "compact"
+                ? admitted(owner, () => session.command(input))
+                : session.command(input);
+        }
+        return {
+            ...session,
+            command,
+            send: (...args) => admitted(owner, () => session.send(...args)),
+        };
+    }
     function ensureRunning() {
         if (stopping)
             throw new Error("Local service is stopping");
     }
-    function selected(owner, sessionId) {
+    /** Count one use of an open store until its release; any use resets idleness. */
+    function hold(databasePath) {
+        uses.set(databasePath, (uses.get(databasePath) ?? 0) + 1);
+        idleCandidates.delete(databasePath);
+        let held = true;
+        return () => {
+            if (!held)
+                return;
+            held = false;
+            const remaining = (uses.get(databasePath) ?? 1) - 1;
+            if (remaining > 0)
+                uses.set(databasePath, remaining);
+            else
+                uses.delete(databasePath);
+        };
+    }
+    /** An open runtime held for one use; a store released meanwhile is reopened. */
+    async function acquire(selection) {
+        for (;;) {
+            const runtime = await ownerFor(selection);
+            if (!released.has(runtime))
+                return { runtime, release: hold(runtime.databasePath) };
+        }
+    }
+    function routesFor(owner, attachment) {
+        const createRoutes = () => createShiitakeHttpRoutes((id) => gatedSession(owner, id, attachment), owner.listSessions, (requestId) => admitted(owner, () => owner.createSession(requestId)), owner.deleteSession, () => owner.extensions);
+        if (attachment !== undefined)
+            return createRoutes();
+        let routes = routesByRuntime.get(owner);
+        if (routes === undefined) {
+            routes = createRoutes();
+            routesByRuntime.set(owner, routes);
+        }
+        return routes;
+    }
+    /**
+     * Serve one client request on an Agent's mounted route, reopening a released
+     * Agent. A streamed body (a Session watch) keeps the Agent in use until it
+     * ends or the client disconnects.
+     */
+    async function serve(selection, request, attachment) {
+        const { runtime, release } = await acquire(selection);
+        const streamAbort = new AbortController();
+        let response;
+        try {
+            response = await routesFor(runtime, attachment).fetch(new Request(request, {
+                signal: AbortSignal.any([request.signal, streamAbort.signal]),
+            }));
+        }
+        catch (cause) {
+            release();
+            throw cause;
+        }
+        const body = response.body;
+        if (body === null) {
+            release();
+            return response;
+        }
+        const reader = body.getReader();
+        let finish = release;
+        let cancelling;
+        const cancelBody = (reason) => {
+            cancelling ??= reader.cancel(reason).finally(() => {
+                finish();
+            });
+            return cancelling;
+        };
+        if (response.headers.get("content-type")?.startsWith("text/event-stream")) {
+            const stop = () => {
+                streamAbort.abort();
+                // Hono on current Bun observes response cancellation, not just the
+                // Request signal. Join cancellation before releasing this stream's use.
+                return cancelBody(streamAbort.signal.reason);
+            };
+            finish = () => {
+                eventResponses.delete(stop);
+                release();
+            };
+            eventResponses.add(stop);
+            // An already-admitted route may finish opening its response during stop.
+            if (stopping)
+                await stop();
+        }
+        return new Response(new ReadableStream({
+            async pull(controller) {
+                try {
+                    const chunk = await reader.read();
+                    if (chunk.done) {
+                        finish();
+                        controller.close();
+                    }
+                    else if (chunk.value instanceof Uint8Array)
+                        controller.enqueue(chunk.value);
+                    else
+                        throw new TypeError("A Local route streamed a non-byte chunk");
+                }
+                catch (cause) {
+                    finish();
+                    controller.error(cause);
+                }
+            },
+            cancel(reason) {
+                return cancelBody(reason);
+            },
+        }), response);
+    }
+    async function effectiveModel(selection, sessionId, signal) {
+        const { runtime, release } = await acquire(selection);
+        try {
+            return await runtime.effectiveModel(sessionId, signal);
+        }
+        finally {
+            release();
+        }
+    }
+    async function sandboxStatus(selection, signal) {
+        signal.throwIfAborted();
+        const { runtime, release } = await acquire(selection);
+        try {
+            signal.throwIfAborted();
+            return runtime.sandboxStatus();
+        }
+        finally {
+            release();
+        }
+    }
+    /**
+     * Close Agents nothing uses that hold no work a reopen could not resume,
+     * on their second consecutive idle check, and forget them for restart.
+     */
+    function sweepIdle() {
+        sweeping ??= (async () => {
+            const closed = [];
+            const stores = new Map();
+            for (const [key, pending] of owners)
+                if (key.startsWith("store:"))
+                    stores.set(key.slice(6), pending);
+            for (const databasePath of idleCandidates)
+                if (!stores.has(databasePath))
+                    idleCandidates.delete(databasePath);
+            for (const [databasePath, pending] of stores) {
+                // A configuration reload holds every open Agent it snapshotted until
+                // it commits; releasing one beneath it would strand that reload.
+                const busy = () => stopping ||
+                    reloading !== undefined ||
+                    uses.has(databasePath) ||
+                    gates.has(databasePath) ||
+                    owners.get(`store:${databasePath}`) !== pending;
+                if (busy()) {
+                    idleCandidates.delete(databasePath);
+                    continue;
+                }
+                let runtime;
+                let idle;
+                try {
+                    ({ runtime } = await pending);
+                    idle = await runtime.idle();
+                }
+                catch (cause) {
+                    // One unreadable Agent stays open; the sweep still checks the rest.
+                    logEvent("service-owner.read-idle", cause);
+                    idleCandidates.delete(databasePath);
+                    continue;
+                }
+                // Anything that started while idleness was read keeps the Agent open.
+                if (!idle || busy()) {
+                    idleCandidates.delete(databasePath);
+                    continue;
+                }
+                if (!idleCandidates.has(databasePath)) {
+                    idleCandidates.add(databasePath);
+                    continue;
+                }
+                closed.push(releaseStore(databasePath, pending, runtime));
+            }
+            await Promise.all(closed);
+        })().finally(() => {
+            sweeping = undefined;
+        });
+        return sweeping;
+    }
+    function releaseStore(databasePath, pending, runtime) {
+        idleCandidates.delete(databasePath);
+        released.add(runtime);
+        for (const [key, value] of owners)
+            if (value === pending)
+                owners.delete(key);
+        emptySessions.delete(databasePath);
+        roots.delete(databasePath);
+        recovery.delete(databasePath);
+        const opened = openedByStore.get(databasePath);
+        openedByStore.delete(databasePath);
+        if (opened !== undefined)
+            opening.delete(opened);
+        const closed = (async () => {
+            try {
+                await runtime.close();
+            }
+            catch (cause) {
+                logEvent("service-owner.release-runtime", cause);
+            }
+            await saveRecovery();
+        })();
+        releasing.set(databasePath, closed);
+        return closed.finally(() => {
+            if (releasing.get(databasePath) === closed)
+                releasing.delete(databasePath);
+        });
+    }
+    /** Settle every pending release of this store, then continue synchronously. */
+    async function releasedClosed(databasePath) {
+        for (let closed = releasing.get(databasePath); closed !== undefined; closed = releasing.get(databasePath)) {
+            await closed;
+            ensureRunning();
+        }
+    }
+    function selected(owner, sessionId, invocationRoot, release) {
         return {
             agentId: owner.agentId,
             databasePath: owner.databasePath,
+            invocationRoot,
             sessionId,
-            session: owner.getSession(sessionId),
-            effectiveModel: owner.effectiveModel,
-            routes: createShiitakeHttpRoutes(owner.getSession, owner.listSessions, owner.createSession, owner.deleteSession, () => owner.extensions),
+            session: gatedSession(owner, sessionId),
+            /** End this selection's use; the mounted route reopens the Agent later. */
+            release,
         };
     }
     async function createSession(creation) {
@@ -108,57 +607,97 @@ export function createLocalServiceOwners(openRuntime = openPrivateLocalRuntimeHo
         const databasePath = requested === undefined
             ? undefined
             : await realpath(resolve(invocationRoot, requested));
-        if (databasePath !== undefined || owners.has(`project:${invocationRoot}`))
+        if (databasePath !== undefined)
             return databasePath;
+        // Name the project's open Agent by its store, so a reopen after an idle
+        // release waits for that close like any other store selection.
+        const projectOwner = owners.get(`project:${invocationRoot}`);
+        if (projectOwner !== undefined)
+            return (await projectOwner).runtime.databasePath;
         const stores = await listPrivateLocalAgentStores(invocationRoot);
         ensureRunning();
         if (stores.length > 1)
-            throw new Error("Multiple Agent stores in this folder; select a saved conversation with fungi resume or specify --database");
+            throw new LocalAgentSelectionAmbiguous(stores.map((store) => basename(dirname(store))));
         return stores[0];
     }
     async function ownerFor(selection) {
+        while (pendingReload() !== undefined)
+            await pendingReload();
         ensureRunning();
         const invocationRoot = await realpath(selection.invocationRoot);
         const databasePath = await selectedDatabasePath(invocationRoot, selection.databasePath);
         ensureRunning();
         const fungiMcp = selection.fungiMcp === undefined
             ? undefined
-            : readFungiMcpSelection(selection.fungiMcp);
+            : readFungiMcpSelection(selection.fungiMcp, {
+                credentialPath: configRoot.credentialPath,
+            });
         ensureRunning();
         // A new project selection shares its in-flight owner; explicit resume keys the store.
         const key = databasePath === undefined
             ? `project:${invocationRoot}`
             : `store:${databasePath}`;
+        while (pendingReload() !== undefined)
+            await pendingReload();
+        ensureRunning();
+        // One process owns a store once: a reopen waits for its released close.
+        if (databasePath !== undefined)
+            await releasedClosed(databasePath);
         let pending = owners.get(key);
         if (pending === undefined && pendingOpenings.size > 0) {
             // A fresh project does not reveal its canonical store path until opening.
             // Let current openings install both project and store aliases, then recheck.
             await Promise.allSettled(pendingOpenings);
+            while (pendingReload() !== undefined)
+                await pendingReload();
             ensureRunning();
             pending = owners.get(key);
         }
+        const openingHere = pending === undefined;
         if (pending === undefined) {
             const projectControl = databasePath === undefined ||
                 belongsToProject(invocationRoot, databasePath);
             let options = {
+                configRoot,
                 invocationRoot,
                 databasePath,
+                // The host must persist/admit this BEFORE Shiitake can recover work.
+                requireSandbox: selection.requireSandbox,
                 agentControl: projectControl ? directory(invocationRoot) : undefined,
                 mail: projectControl ? mailRouting(invocationRoot) : undefined,
+                meshAdmission,
             };
             if (fungiMcp !== undefined)
                 options = { ...options, fungiMcp };
+            const captured = configuration;
+            if (captured !== undefined)
+                options = {
+                    ...options,
+                    configuration: (store) => loadConfiguration(captured, invocationRoot, store),
+                };
             pending = trackOpening(openRuntime(options).then((runtime) => ({ runtime, fungiMcp })), invocationRoot, key);
         }
         const owner = await pending;
         ensureRunning();
-        if (fungiMcp !== undefined &&
+        if (configuration === undefined &&
+            fungiMcp !== undefined &&
             !sameFungiMcpConnection(owner.fungiMcp, fungiMcp))
             throw new FungiMcpSelectionConflict();
+        if (!openingHere && selection.requireSandbox !== undefined)
+            owner.runtime.setRequireSandbox(selection.requireSandbox);
         return owner.runtime;
     }
     async function select(selection, createRequestId) {
-        const owner = await ownerFor(selection);
+        const { runtime: owner, release } = await acquire(selection);
+        try {
+            return selected(owner, await selectedSession(owner, selection, createRequestId), await realpath(selection.invocationRoot), release);
+        }
+        catch (cause) {
+            release();
+            throw cause;
+        }
+    }
+    async function selectedSession(owner, selection, createRequestId) {
         let sessionId = selection.sessionId;
         if (createRequestId !== undefined) {
             sessionId = await owner.createSession(createRequestId);
@@ -180,7 +719,7 @@ export function createLocalServiceOwners(openRuntime = openPrivateLocalRuntimeHo
         if (selection.clientPath !== undefined &&
             !owner.bindSessionPath(sessionId, selection.clientPath))
             throw new LocalSessionPathConflict();
-        return selected(owner, sessionId);
+        return sessionId;
     }
     /**
      * Project mail routing for every Agent this service owns in one project.
@@ -190,15 +729,54 @@ export function createLocalServiceOwners(openRuntime = openPrivateLocalRuntimeHo
     function mailRouting(invocationRoot) {
         const control = directory(invocationRoot);
         return {
-            deliver: async (mail) => (await control.owner(mail.to.agentId, new AbortController().signal)).acceptMail(mail),
-            readSettlement: async (agentId, sessionId, commandId) => (await control.owner(agentId, new AbortController().signal)).readSettlement(sessionId, commandId),
+            deliver: async (mail) => {
+                const remote = [...meshDirectories.values()].find(({ record }) => record.invocationRoot === invocationRoot &&
+                    record.bindings.some((binding) => binding.agentId === mail.from.agentId));
+                if (remote !== undefined) {
+                    if (!remote.agents.some((agent) => agent.agentId === mail.to.agentId))
+                        throw new Error("Mesh mail recipient is outside this Team");
+                    const result = await mesh.deliver(remote.record, {
+                        key: mail.key,
+                        kind: "agentMail",
+                        address: {
+                            scopeId: remote.record.scopeId,
+                            agentId: mail.to.agentId,
+                        },
+                        event: mail,
+                    });
+                    if (result === "accepted" ||
+                        result === "duplicate" ||
+                        result === "refused" ||
+                        !("receipt" in result) ||
+                        result.status === "refused")
+                        throw new Error("Mesh recipient did not return command acceptance");
+                    return parseAccepted(JSON.stringify(result.receipt));
+                }
+                const { owner, release } = await control.owner(mail.to.agentId, new AbortController().signal);
+                try {
+                    return await admitted(owner, () => owner.acceptMail(mail));
+                }
+                finally {
+                    release();
+                }
+            },
+            // A settled command stays readable once its Agent is archived.
+            readSettlement: async (agentId, sessionId, commandId) => {
+                const { owner, release } = await control.owner(agentId, new AbortController().signal, true);
+                try {
+                    return await owner.readSettlement(sessionId, commandId);
+                }
+                finally {
+                    release();
+                }
+            },
         };
     }
     function directory(invocationRoot) {
-        async function targets(signal) {
+        async function targets(signal, visibility = "active") {
             ensureRunning();
             signal.throwIfAborted();
-            const paths = await listPrivateLocalAgentStores(invocationRoot);
+            const paths = await listPrivateLocalAgentStores(invocationRoot, visibility);
             signal.throwIfAborted();
             const result = new Map();
             for (const databasePath of paths) {
@@ -213,38 +791,187 @@ export function createLocalServiceOwners(openRuntime = openPrivateLocalRuntimeHo
             }
             return result;
         }
-        async function admittedOwner(agentId, signal) {
-            const databasePath = (await targets(signal)).get(agentId);
+        async function admittedOwner(agentId, signal, includeArchived = false) {
+            const visibility = includeArchived ? "all" : "active";
+            const databasePath = (await targets(signal, visibility)).get(agentId);
+            if (databasePath === undefined)
+                return outsideOrArchived(agentId, signal);
+            const { runtime, release } = await acquire({
+                invocationRoot,
+                databasePath,
+            });
+            try {
+                // Archived while the owner opened: the Agent is no longer in use.
+                if ((await targets(signal, visibility)).get(agentId) !== databasePath)
+                    return await outsideOrArchived(agentId, signal);
+                signal.throwIfAborted();
+                ensureRunning();
+                return { owner: runtime, release };
+            }
+            catch (cause) {
+                release();
+                throw cause;
+            }
+        }
+        async function outsideOrArchived(agentId, signal) {
+            if ((await targets(signal, "archived")).has(agentId))
+                throw new AgentArchiveRefused("archived", `Agent ${agentId} is archived; unarchive it to work with it`);
+            throw new Error("Agent is outside this Local project");
+        }
+        /**
+         * The first command still queued or running on any of an Agent's Sessions,
+         * so an archive can name it rather than cancel it.
+         */
+        async function runningCommand(owner) {
+            let after;
+            do {
+                const page = await owner.listSessions(after);
+                for (const row of page.sessions) {
+                    if (row.state !== "running" && row.state !== "needs_you")
+                        continue;
+                    const { activity } = await owner
+                        .getSession(row.sessionId)
+                        .read({ limit: 1 });
+                    if (activity.queue.state !== "idle")
+                        return {
+                            sessionId: row.sessionId,
+                            commandId: activity.queue.commandId,
+                        };
+                }
+                after = page.next;
+            } while (after !== undefined);
+            return undefined;
+        }
+        /**
+         * Archive or restore one Agent by flipping the flag its store owns. A
+         * person may do it to any Agent; an Agent only to one it created, never
+         * itself. Archiving never cancels work, so it refuses while a command runs.
+         */
+        async function setArchived({ agentId, by }, archived, signal) {
+            const databasePath = (await targets(signal, "all")).get(agentId);
             if (databasePath === undefined)
                 throw new Error("Agent is outside this Local project");
-            const owner = await ownerFor({ invocationRoot, databasePath });
-            if ((await targets(signal)).get(agentId) !== databasePath)
-                throw new Error("Agent is outside this Local project");
-            signal.throwIfAborted();
-            ensureRunning();
-            return owner;
+            let createdBy;
+            try {
+                ({ createdBy } = readPrivateLocalAgentProfile(databasePath));
+            }
+            catch (error) {
+                if (!(error instanceof LocalStoreSchemaError))
+                    throw error;
+                throw new AgentArchiveRefused("unreadable", `Agent ${agentId}'s store ${unreadableStoreReason(agentId)}`);
+            }
+            if (by.kind === "agent") {
+                if (by.agentId === agentId)
+                    throw new AgentArchiveRefused("self", "an Agent cannot archive or restore itself");
+                if (createdBy !== by.agentId)
+                    throw new AgentArchiveRefused("not_creator", "an Agent can archive or restore only an Agent it created");
+            }
+            const { runtime: owner, release } = await acquire({
+                invocationRoot,
+                databasePath,
+            });
+            // Alone with the Agent: no work is admitted between the checks and the flag.
+            try {
+                await gateFor(databasePath).exclusive(async () => {
+                    if (archived) {
+                        const running = await runningCommand(owner);
+                        if (running !== undefined)
+                            throw new AgentArchiveRefused("running", `command ${running.commandId} is running in Session ${running.sessionId}; cancel it first`);
+                        const waiting = await owner.pendingDelegation();
+                        if (waiting !== undefined)
+                            throw new AgentArchiveRefused("pending", waiting.unreadable === undefined
+                                ? `it still waits for command ${waiting.commandId} it delegated to Agent ${waiting.agentId} (Session ${waiting.sessionId}); wait for it or cancel it first`
+                                : `it delegated command ${waiting.commandId} to Agent ${waiting.agentId} (Session ${waiting.sessionId}) and that work cannot be read (${waiting.unreadable}); wait for it or cancel it first`);
+                    }
+                    signal.throwIfAborted();
+                    owner.setArchived(archived);
+                });
+            }
+            finally {
+                release();
+                pruneGate(databasePath);
+            }
         }
         return {
             owner: admittedOwner,
-            list: async (signal) => [...(await targets(signal)).keys()].map((agentId) => ({
-                agentId,
-                name: agentId,
-            })),
-            create: async ({ requestId, model }, signal) => {
+            archive: (request, signal) => setArchived(request, true, signal),
+            unarchive: (request, signal) => setArchived(request, false, signal),
+            list: async (signal, options) => {
+                const stores = await targets(signal, options?.archived === true ? "archived" : "active");
+                return [...stores].map(([agentId, databasePath]) => {
+                    let profile;
+                    try {
+                        profile = readPrivateLocalAgentProfile(databasePath);
+                    }
+                    catch (error) {
+                        // One store written before the current schema fails its own row,
+                        // loudly; the other Agents still list.
+                        if (!(error instanceof LocalStoreSchemaError))
+                            throw error;
+                        logEvent("list-agent-store", error);
+                        return {
+                            agentId,
+                            name: agentId,
+                            workingDirectory: invocationRoot,
+                            unreadable: unreadableStoreReason(agentId),
+                        };
+                    }
+                    const { name, model, createdBy } = profile;
+                    let agent = {
+                        agentId,
+                        name: name ?? agentId,
+                        workingDirectory: invocationRoot,
+                    };
+                    agent = { ...agent, createdBy };
+                    return model === null ? agent : { ...agent, model };
+                });
+            },
+            create: async ({ requestId, name, model, extensions: requested = [], createdBy }, signal) => {
                 ensureRunning();
                 signal.throwIfAborted();
+                // An Agent creating an Agent cannot give it more than it holds. Refuse
+                // before anything exists; never trim the request.
+                const creatorDatabase = (await targets(signal)).get(createdBy);
+                if (creatorDatabase === undefined)
+                    throw new AgentCreateRefused("no_creator", "the creating Agent is not in this Local project");
+                const creatorStore = dirname(creatorDatabase);
+                const sandbox = readPrivateLocalAgentProfile(creatorDatabase);
+                try {
+                    await extensions.assertHeldByAgent(creatorStore, requested);
+                }
+                catch (error) {
+                    if (error instanceof LocalExtensionError &&
+                        error.reason === "not-held")
+                        throw new AgentCreateRefused("exceeds_creator", error.message);
+                    throw error;
+                }
                 const key = `create:${JSON.stringify([invocationRoot, requestId])}`;
                 const createStore = await resolvePrivateLocalCreateStore(invocationRoot, requestId);
                 signal.throwIfAborted();
                 ensureRunning();
                 const databasePath = createStore.databasePath;
+                for (const id of requested)
+                    await extensions.enableAgent(dirname(databasePath), id, {
+                        agentStoreDirectory: creatorStore,
+                    });
+                signal.throwIfAborted();
+                while (pendingReload() !== undefined)
+                    await pendingReload();
+                ensureRunning();
+                await releasedClosed(databasePath);
+                ensureRunning();
                 let pending = owners.get(key);
                 if (pending === undefined) {
                     pending = owners.get(`store:${databasePath}`);
                     if (pending === undefined) {
                         let options = {
+                            configRoot,
                             invocationRoot,
                             createRequestId: requestId,
+                            name,
+                            createdBy,
+                            requireSandbox: sandbox.requireSandbox,
+                            folder: sandbox.folder,
                             agentControl: directory(invocationRoot),
                             mail: mailRouting(invocationRoot),
                         };
@@ -255,6 +982,12 @@ export function createLocalServiceOwners(openRuntime = openPrivateLocalRuntimeHo
                                 modelId: model.modelId,
                                 reasoning: model.reasoning,
                             };
+                        const captured = configuration;
+                        if (captured !== undefined)
+                            options = {
+                                ...options,
+                                configuration: (store) => loadConfiguration(captured, invocationRoot, store),
+                            };
                         pending = trackOpening(openRuntime(options).then((runtime) => ({
                             runtime,
                             fungiMcp: undefined,
@@ -267,27 +1000,54 @@ export function createLocalServiceOwners(openRuntime = openPrivateLocalRuntimeHo
                 if (owner.runtime.databasePath !== databasePath)
                     throw new Error("Local Agent create identity does not match its store");
                 owners.set(key, pending);
-                await owner.runtime.assertModelReady("main", signal);
+                const release = hold(databasePath);
+                try {
+                    await owner.runtime.assertModelReady("main", signal);
+                }
+                finally {
+                    release();
+                }
                 const agentId = createStore.agentId;
-                return Object.freeze({ agentId, name: agentId });
+                const created = {
+                    agentId,
+                    name: owner.runtime.name,
+                    createdBy,
+                    workingDirectory: invocationRoot,
+                };
+                return Object.freeze(model === undefined ? created : { ...created, model });
             },
             setModel: async ({ agentId, model }, signal) => {
-                const owner = await admittedOwner(agentId, signal);
-                await owner.setModel(model, signal);
+                const { owner, release } = await admittedOwner(agentId, signal);
+                try {
+                    await owner.setModel(model, signal);
+                }
+                finally {
+                    release();
+                }
             },
             checkModel: async ({ agentId, sessionId }, signal) => {
-                const owner = await admittedOwner(agentId, signal);
-                await owner.assertModelReady(sessionId, signal);
+                const { owner, release } = await admittedOwner(agentId, signal);
+                try {
+                    await owner.assertModelReady(sessionId, signal);
+                }
+                finally {
+                    release();
+                }
             },
             open: async (agentId, signal) => {
-                const owner = await admittedOwner(agentId, signal);
-                // The service retains runtime ownership; an operation leases access only.
-                const release = () => Promise.resolve();
+                const held = await admittedOwner(agentId, signal);
+                const owner = held.owner;
+                // The service retains runtime ownership; an operation holds a use of it.
+                const release = () => {
+                    held.release();
+                    return Promise.resolve();
+                };
                 return {
                     agent: {
-                        session: owner.getSession,
+                        // Work starts only through an admission that finds the Agent in use.
+                        session: (sessionId) => gatedSession(owner, sessionId),
                         listSessions: owner.listSessions,
-                        createSession: owner.createSession,
+                        createSession: (requestId) => admitted(owner, () => owner.createSession(requestId)),
                         deleteSession: owner.deleteSession,
                         extensions: owner.extensions,
                         close: release,
@@ -299,21 +1059,68 @@ export function createLocalServiceOwners(openRuntime = openPrivateLocalRuntimeHo
     }
     function close() {
         stopping = true;
+        clearInterval(sweepTimer);
         closing ??= (async () => {
+            const meshResults = await Promise.allSettled([mesh.close()]);
+            // End our observers before deciding which Agents have work to resume.
+            // Their client disconnect may not have reached the server yet.
+            await Promise.all([...eventResponses].map((stop) => stop()));
+            // Restoration may still be reading references or opening one Agent.
+            // It stops scheduling at shutdown; join it before saving or closing.
+            await restoring;
+            // Reload owns staged activation scopes until it publishes or discards.
+            // Its caller receives validation failures; shutdown waits for cleanup.
+            await Promise.allSettled(reloading === undefined ? [] : [reloading]);
             await Promise.allSettled(pendingOpenings);
-            const settled = await Promise.allSettled(opening);
+            await Promise.allSettled([
+                ...(sweeping === undefined ? [] : [sweeping]),
+                ...releasing.values(),
+            ]);
+            // Close up to four independent stores concurrently within the listener's
+            // single overall budget. One hung close must not block every other Agent.
+            const settled = await Promise.allSettled([...opening.keys()].map(async (pending) => ({
+                pending,
+                owner: await pending,
+            })));
             const failures = [];
-            for (const result of settled) {
-                if (result.status === "fulfilled") {
-                    try {
-                        await result.value.runtime.close();
-                    }
-                    catch (cause) {
-                        logEvent("service-owner.close-runtime", cause);
-                        failures.push(cause);
-                    }
+            for (const result of meshResults)
+                if (result.status === "rejected")
+                    failures.push(result.reason);
+            // The next service reopens only Agents with work to resume. Decide and
+            // save that list before closing anything: if the listener's overall
+            // drain budget ends a slow close, the saved list is already right.
+            await Effect.runPromise(Effect.forEach(settled, (result) => Effect.promise(async () => {
+                if (result.status !== "fulfilled")
+                    return;
+                const { owner } = result.value;
+                // A request still draining may yet commit work, so an Agent in
+                // use or admitting work keeps its entry, before or after the read.
+                const databasePath = owner.runtime.databasePath;
+                const unused = () => !uses.has(databasePath) && !gates.has(databasePath);
+                try {
+                    if (unused() && (await owner.runtime.idle()) && unused())
+                        recovery.delete(databasePath);
                 }
-            }
+                catch (cause) {
+                    logEvent("service-owner.read-idle", cause);
+                }
+            }), { concurrency: 4, discard: true }));
+            await saveRecovery();
+            await Effect.runPromise(Effect.forEach(settled, (result) => Effect.promise(async () => {
+                if (result.status !== "fulfilled")
+                    return;
+                const { pending, owner } = result.value;
+                try {
+                    await owner.runtime.close();
+                }
+                catch (cause) {
+                    logEvent("service-owner.close-runtime", cause);
+                    failures.push(cause);
+                }
+                finally {
+                    opening.delete(pending);
+                }
+            }), { concurrency: 4, discard: true }));
             owners.clear();
             opening.clear();
             pendingOpenings.clear();
@@ -322,24 +1129,37 @@ export function createLocalServiceOwners(openRuntime = openPrivateLocalRuntimeHo
         })();
         return closing;
     }
-    async function restore() {
+    function restore() {
+        restoring ??= restoreSaved();
+        return restoring;
+    }
+    function loadRecovery() {
+        loadingRecovery ??= readRecovery();
+        return loadingRecovery;
+    }
+    function disableRecovery(reason, cause) {
+        const error = new LocalRecoveryPersistenceDisabled(reason, cause);
+        onRecoveryDisabled(reason === "read" ? "read-failed" : "decode-failed");
+        logEvent(`service-owner.recovery-disabled.${error.reason}`, error);
+        return { kind: "disabled", error };
+    }
+    async function readRecovery() {
         if (recoveryPath === undefined)
-            return;
+            return { kind: "loaded", references: [] };
         let content;
         try {
-            content = await readFile(recoveryPath, "utf8");
+            content = await readRecoveryManifest(recoveryPath);
         }
         catch (cause) {
             if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
-                return;
-            logEvent("service-owner.read-recovery", cause);
-            return;
+                return { kind: "loaded", references: [] };
+            // Unknown contents are not an empty manifest. Keep the file untouched
+            // for this service lifetime while still admitting on-demand Agents.
+            return disableRecovery("read", cause);
         }
         const decoded = decodeRecoveryFile(content);
         if (decoded._tag === "Failure") {
-            logEvent("service-owner.decode-recovery", decoded.failure);
-            await saveRecovery();
-            return;
+            return disableRecovery("decode", decoded.failure);
         }
         const saved = [];
         for (const entry of decoded.success) {
@@ -349,15 +1169,29 @@ export function createLocalServiceOwners(openRuntime = openPrivateLocalRuntimeHo
                 continue;
             }
             saved.push(selection.data);
-            recovery.set(selection.data.databasePath, selection.data);
+            // A concurrent client may already have installed the current reference.
+            if (!recovery.has(selection.data.databasePath))
+                recovery.set(selection.data.databasePath, selection.data);
         }
+        return { kind: "loaded", references: saved };
+    }
+    async function restoreSaved() {
+        const loaded = await loadRecovery();
+        if (loaded.kind === "disabled")
+            return;
         // Preload valid references before opening, then isolate and prune each
         // failed owner so an unavailable project cannot prevent service startup.
-        for (const selection of saved) {
+        for (const selection of loaded.references) {
+            if (stopping)
+                break;
             try {
                 await ownerFor(selection);
             }
             catch (cause) {
+                // A completed open remains owned and is drained by close(). Keep its
+                // recovery reference, and all not-yet-opened references, for next time.
+                if (closing !== undefined)
+                    break;
                 logEvent("service-owner.restore-entry", cause);
                 // A good owner may already have replaced another stale reference to
                 // this store. Prune only the failing reference, never that live owner.
@@ -367,5 +1201,169 @@ export function createLocalServiceOwners(openRuntime = openPrivateLocalRuntimeHo
         }
         await saveRecovery();
     }
-    return { createSession, select, restore, close };
+    /** A person archives or restores any Agent of one project folder. */
+    async function archive(request, signal) {
+        const control = directory(await realpath(request.invocationRoot));
+        const target = {
+            agentId: request.agentId,
+            by: { kind: "human" },
+        };
+        await (request.archived
+            ? control.archive(target, signal)
+            : control.unarchive(target, signal));
+    }
+    /**
+     * This is Agent lifetime ancestry, not turn ancestry: a stopped parent still
+     * owns its helpers. Snapshot once, visit descendants before their creator,
+     * and never delete or archive their conversations.
+     */
+    async function stopAll(request) {
+        ensureRunning();
+        const invocationRoot = await realpath(request.invocationRoot);
+        const paths = await listPrivateLocalAgentStores(invocationRoot, "all");
+        if (paths.length > 4_096)
+            throw new Error("Too many Agent stores to stop safely in one request; no cascade was started");
+        const result = {
+            rootAgentId: request.agentId,
+            agents: [],
+            discoveryFailures: [],
+        };
+        const agents = new Map();
+        for (const databasePath of paths) {
+            const agentId = basename(dirname(databasePath));
+            try {
+                if (!belongsToProject(invocationRoot, databasePath))
+                    throw new Error("Agent is outside this Local project; it was not stopped");
+                const profile = readPrivateLocalAgentProfile(databasePath);
+                agents.set(agentId, {
+                    databasePath,
+                    name: profile.name ?? agentId,
+                    createdBy: profile.createdBy,
+                });
+            }
+            catch (cause) {
+                result.discoveryFailures.push({
+                    agentId,
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                });
+            }
+        }
+        if (!agents.has(request.agentId))
+            throw new Error("The selected Agent could not be read; no cascade was started");
+        // Iterative postorder is bounded by the discovered stores, including cycles.
+        const seen = new Set();
+        const stack = [{ agentId: request.agentId, visited: false }];
+        const ordered = [];
+        while (stack.length > 0) {
+            const entry = stack.pop();
+            if (entry === undefined)
+                break;
+            if (entry.visited) {
+                ordered.push(entry.agentId);
+                continue;
+            }
+            if (seen.has(entry.agentId))
+                continue;
+            seen.add(entry.agentId);
+            stack.push({ ...entry, visited: true });
+            const children = [...agents].filter(([, agent]) => agent.createdBy === entry.agentId);
+            for (const [agentId] of children.reverse())
+                stack.push({ agentId, visited: false });
+        }
+        for (const agentId of ordered) {
+            const agent = agents.get(agentId);
+            if (agent === undefined)
+                continue;
+            let timer;
+            const deadline = new AbortController();
+            try {
+                const stopped = await Promise.race([
+                    (async () => {
+                        const { runtime: owner, release } = await acquire({
+                            invocationRoot,
+                            databasePath: agent.databasePath,
+                        });
+                        try {
+                            deadline.signal.throwIfAborted();
+                            let after;
+                            let stopped = false;
+                            do {
+                                const page = await owner.listSessions(after);
+                                deadline.signal.throwIfAborted();
+                                for (const row of page.sessions) {
+                                    const session = owner.getSession(row.sessionId);
+                                    const snapshot = await session.read({ limit: 1 });
+                                    deadline.signal.throwIfAborted();
+                                    if (snapshot.activity.queue.state !== "running" &&
+                                        snapshot.pending.total === 0)
+                                        continue;
+                                    if (!snapshot.activity.cancellationRequested ||
+                                        snapshot.pending.total > 0)
+                                        await session.abort();
+                                    // An accepted cancellation is not a completed stop. In particular,
+                                    // first Esc may already have requested cancellation of this turn.
+                                    // Keep the existing per-Agent deadline while awaiting durable idle.
+                                    let settled = await session.read({ limit: 1 });
+                                    while (settled.activity.queue.state === "running" ||
+                                        settled.pending.total > 0) {
+                                        await delay(20, undefined, { signal: deadline.signal });
+                                        settled = await session.read({ limit: 1 });
+                                    }
+                                    deadline.signal.throwIfAborted();
+                                    stopped = true;
+                                }
+                                after = page.next;
+                            } while (after !== undefined);
+                            return stopped;
+                        }
+                        finally {
+                            release();
+                        }
+                    })(),
+                    new Promise((_resolve, reject) => {
+                        timer = setTimeout(() => {
+                            const error = new Error("Agent did not answer within 5 seconds; stop is unconfirmed");
+                            deadline.abort(error);
+                            reject(error);
+                        }, 5_000);
+                    }),
+                ]);
+                result.agents.push({
+                    agentId,
+                    name: agent.name,
+                    outcome: stopped ? "stopped" : "idle",
+                });
+            }
+            catch (cause) {
+                result.agents.push({
+                    agentId,
+                    name: agent.name,
+                    outcome: "failed",
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        return result;
+    }
+    return {
+        refreshMesh: mesh.refresh,
+        createSession,
+        select,
+        serve,
+        effectiveModel,
+        sandboxStatus,
+        sweepIdle,
+        archive,
+        stopAll,
+        restore,
+        close,
+        reload,
+        unfinishedOwners: () => [
+            ...(reloading === undefined ? [] : ["configuration reload"]),
+            ...opening.values(),
+        ],
+    };
 }