@stratusagent/gateway 0.3.0 → 0.6.0

package/dist/index.js

@@ -1,13 +1,26 @@
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { chmodSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
-import { AgentRegistry, AgentRunner, EventBus, RunAbortedError, ToolRegistry, } from '@stratusagent/core';
+import { AgentRegistry, AgentRunner, EventBus, RunAbortedError, ToolRegistry, readPendingApproval, } from '@stratusagent/core';
 import { createDelegateTool, createRememberTool, } from '@stratusagent/agents';
 import { createLocalCommandExecutor } from '@stratusagent/executor-local';
-import { createDemoTool, createFileMemoryStore, createRuntimeProvider, DEFAULT_STRATUS_AGENT, loadRosterSouls, FALLBACK_ACTIVE_METADATA_KEY, loadSoulFile, memoryFilePath, migrateLegacyMemory, ConfigFileError, loadConfigFile, readNonEmptyString, resolveConfigLocation, resolveConfiguredSoul, resolveRuntimeConfig, stratusHomePath, withLegacyDefaultMemories, } from '@stratusagent/state';
+import { loadPlugins, } from '@stratusagent/plugins';
+import { createDemoTool, createFileMemoryStore, createRuntimeProvider, DEFAULT_STRATUS_AGENT, loadRosterSouls, FALLBACK_ACTIVE_METADATA_KEY, loadSoulFile, memoryFilePath, migrateLegacyMemory, ConfigFileError, loadConfigFile, resolveConfigLocation, resolveConfiguredSoul, resolveRuntimeConfig, applySoulPins, stratusHomePath, workspacesDirPath, withLegacyDefaultMemories, } from '@stratusagent/state';
 const SESSIONS_DB_FILENAME = 'sessions.db';
 const DEFAULT_IDLE_TIMEOUT_MS = 120_000;
+/**
+ * How long a parked call waits for a person. Long enough to survive a
+ * meeting, short enough that a request nobody saw does not hold a turn (and
+ * the Slack thread it is answering) open indefinitely.
+ */
+const DEFAULT_APPROVAL_TIMEOUT_MS = 900_000;
+/**
+ * Node's largest `setTimeout` delay. Anything above it does not become a
+ * long wait — it silently becomes a 1ms one, so a config asking for a
+ * 30-day approval window would expire every request almost immediately.
+ */
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
 export class SqliteSessionStore {
     db;
     constructor(filePath, options = {}) {
@@ -84,11 +97,85 @@ export class SqliteSessionStore {
             .prepare('INSERT OR REPLACE INTO sessions (id, agent_id, status, body, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)')
             .run(updated.id, updated.agent.id, updated.status, JSON.stringify(updated), updated.createdAt, updated.updatedAt);
     }
-    /** Newest-first session listing for one agent (or all agents). */
-    list(agentId) {
+    /**
+     * Session ids in a state, oldest first — the index a restarting daemon
+     * sweeps for turns parked on a human. The `status` column carries it, so
+     * no conversation body is deserialized to answer the question.
+     */
+    async listIdsByStatus(status) {
+        const rows = this.db
+            .prepare('SELECT id FROM sessions WHERE status = ? ORDER BY updated_at ASC')
+            .all(status);
+        return rows.map((row) => row.id);
+    }
+    /**
+     * When each agent last did anything, and how many of its sessions are live
+     * right now.
+     *
+     * One aggregate over the indexed columns — no conversation body is
+     * deserialized, for the same reason `listIdsByStatus` returns ids: a
+     * roster view asks this on every load, and it must not cost a JSON parse
+     * per session to answer.
+     *
+     * Both halves are needed and neither is sufficient. `lastActiveAt` alone
+     * reads a turn parked on a human as idle, because the save that recorded
+     * the park is the last thing that touched the row — and a turn waiting
+     * twenty minutes on an approval is exactly when someone wants to see the
+     * agent lit. `activeSessions` alone loses an agent that finished a moment
+     * ago. The caller decides what window counts as "recent"; a daemon that
+     * baked one in would need upgrading to change it.
+     */
+    /**
+     * How many sessions are in each state.
+     *
+     * A grouped count, not a listing that gets counted. The table grows for the
+     * life of an install and a health endpoint is polled, so materialising one
+     * object per historical session to produce five numbers gets steadily
+     * slower at exactly the thing meant to report that the daemon is fine.
+     */
+    countByStatus() {
+        const rows = this.db
+            .prepare('SELECT status, COUNT(*) AS total FROM sessions GROUP BY status')
+            .all();
+        const counts = {};
+        for (const row of rows) {
+            counts[row.status] = Number(row.total);
+        }
+        return counts;
+    }
+    lastActivityByAgent() {
+        const rows = this.db
+            .prepare(`
+        SELECT agent_id,
+               MAX(updated_at) AS last_active_at,
+               SUM(CASE WHEN status IN ('running', 'pending_approval') THEN 1 ELSE 0 END) AS active_sessions
+        FROM sessions
+        GROUP BY agent_id
+      `)
+            .all();
+        const activity = {};
+        for (const row of rows) {
+            activity[row.agent_id] = {
+                lastActiveAt: row.last_active_at,
+                activeSessions: Number(row.active_sessions),
+            };
+        }
+        return activity;
+    }
+    /**
+     * Newest-first session listing for one agent (or all agents).
+     *
+     * `limit` is not decoration: this table grows for the life of an install,
+     * and a surface that renders "recent conversations" would otherwise pull
+     * every session anyone has ever had to show ten of them.
+     */
+    list(agentId, limit) {
+        // -1 is SQLite's "no limit", so one prepared statement serves both cases
+        // rather than four.
+        const bound = limit !== undefined && Number.isInteger(limit) && limit >= 0 ? limit : -1;
         const rows = (agentId
-            ? this.db.prepare('SELECT id, agent_id, status, created_at, updated_at FROM sessions WHERE agent_id = ? ORDER BY updated_at DESC').all(agentId)
-            : this.db.prepare('SELECT id, agent_id, status, created_at, updated_at FROM sessions ORDER BY updated_at DESC').all());
+            ? this.db.prepare('SELECT id, agent_id, status, created_at, updated_at FROM sessions WHERE agent_id = ? ORDER BY updated_at DESC LIMIT ?').all(agentId, bound)
+            : this.db.prepare('SELECT id, agent_id, status, created_at, updated_at FROM sessions ORDER BY updated_at DESC LIMIT ?').all(bound));
         return rows.map((row) => ({
             id: row.id,
             agentId: row.agent_id,
@@ -102,64 +189,25 @@ export class SqliteSessionStore {
     }
 }
 /**
- * Apply a soul's provider/model pins to a selection, demoting the
- * daemon-wide defaults the pins outrank.
+ * A soul's provider/model pins, and the daemon-wide defaults they demote.
  *
- * Exported because this is not only dispatch logic: anything that wants to
- * know what a served agent will actually resolve to — a startup billing
- * check, a diagnostic — has to normalize the same way, and a second copy
- * of these rules drifts from this one.
+ * The implementation lives in `@stratusagent/state`, beside the resolver
+ * whose precedence it manipulates — it never had a gateway dependency. It is
+ * re-exported here because this is where callers were told to import it from,
+ * and because "what will a served agent actually resolve to" is a gateway
+ * question even when the rule answering it is not gateway code.
  */
-export const applySoulPins = (pins, selection, env, context) => {
-    selection.presetSoul = pins;
-    if (!pins.provider && !pins.model) {
-        return { selection, env };
-    }
-    const processEnv = { ...(env.processEnv ?? process.env) };
-    // The daemon-wide default can come from the selection, the environment,
-    // or the config file. A config with no provider key predates the
-    // anthropic option and is openai-specific (the resolver treats it that
-    // way), so a real file without the key still names openai as the
-    // default. Env values normalize exactly as the resolver normalizes
-    // them: an empty or whitespace-padded STRATUS_PROVIDER is no default at
-    // all, not a mismatching one.
-    const defaultProvider = context.selectionProvider
-        ?? readNonEmptyString(processEnv.STRATUS_PROVIDER)
-        ?? readNonEmptyString(processEnv.STRATUSCLAW_PROVIDER)
-        ?? context.configProvider
-        ?? (context.configPresent ? 'openai' : undefined);
-    if (pins.provider) {
-        delete selection.provider;
-        delete processEnv.STRATUS_PROVIDER;
-        delete processEnv.STRATUSCLAW_PROVIDER;
-        if (defaultProvider !== undefined && defaultProvider !== 'demo' && pins.provider !== defaultProvider) {
-            // The default model, endpoint, and generic credentials were all
-            // chosen for the default provider — none may ride along to the
-            // soul's: a base URL would point the pinned provider at the wrong
-            // service, and a generic API key would be sent to it. With NO
-            // default selected anywhere — or the credential-less demo provider
-            // as the default — there is nothing those values could have been
-            // chosen for except whatever provider the soul selects — exactly
-            // the resolver's own reading of a generic credential — so they stay.
-            delete selection.model;
-            delete processEnv.STRATUS_MODEL;
-            delete processEnv.STRATUSCLAW_MODEL;
-            delete selection.baseUrl;
-            delete processEnv.STRATUS_BASE_URL;
-            delete processEnv.STRATUSCLAW_BASE_URL;
-            delete processEnv.STRATUS_API_KEY;
-            delete processEnv.STRATUSCLAW_API_KEY;
-            delete processEnv.STRATUS_API_KEY_ENV;
-            delete processEnv.STRATUSCLAW_API_KEY_ENV;
-        }
-    }
-    if (pins.model) {
-        delete selection.model;
-        delete processEnv.STRATUS_MODEL;
-        delete processEnv.STRATUSCLAW_MODEL;
-    }
-    return { selection, env: { ...env, processEnv } };
-};
+export { applySoulPins } from '@stratusagent/state';
+/**
+ * Recorded on a turn the previous process was still running when it died.
+ *
+ * Exported because "distinguishable" is the whole point: a surface, a
+ * test, or an operator reading `lastError` has to be able to tell a turn
+ * nobody finished apart from one a provider or a tool actually failed, and
+ * matching on prose that lives in one place beats each caller inventing
+ * its own guess at the wording.
+ */
+export const ABANDONED_TURN_ERROR = 'stratusd stopped while this turn was still running; it was not resumed. Send the message again.';
 /**
  * The always-on Stratus process. One gateway holds the roster, the durable
  * session store, the shared event bus, and a pool of runners keyed by
@@ -181,6 +229,269 @@ export const createGateway = (options = {}) => {
         ? new SqliteSessionStore(options.sessionDbPath)
         : new SqliteSessionStore(path.join(stratusHomePath(env), SESSIONS_DB_FILENAME), { ownedDirectory: true });
     const memory = withLegacyDefaultMemories(createFileMemoryStore(memoryFilePath(env)));
+    // ---- approval brokering -------------------------------------------------
+    const approvalTimeoutMs = options.approvalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS;
+    // Refused at construction, not absorbed: a negative or NaN timeout fails
+    // the `> 0` test below and quietly means "never expire" — the one
+    // behavior documented for an explicit 0, and the last one a caller who
+    // typed a bad number wants. Config-file values are already rejected with
+    // a better message; this catches the programmatic path.
+    if (!Number.isFinite(approvalTimeoutMs) || approvalTimeoutMs < 0) {
+        throw new Error(`approvalTimeoutMs must be a non-negative number of milliseconds (0 to wait indefinitely); received ${String(options.approvalTimeoutMs)}.`);
+    }
+    // Clamped, not trusted: a delay past Node's timer range is not a long
+    // wait, it is a 1ms one, so an over-large value would turn every approval
+    // into an instant expiry — the opposite of what it asked for. The CLI
+    // rejects these at config load with a better message; this is the
+    // backstop for a programmatic caller.
+    const effectiveApprovalTimeoutMs = Math.min(approvalTimeoutMs, MAX_TIMER_DELAY_MS);
+    if (approvalTimeoutMs > MAX_TIMER_DELAY_MS) {
+        warn(`approval timeout ${approvalTimeoutMs}ms is above Node's maximum timer delay; using ${MAX_TIMER_DELAY_MS}ms (~24.8 days)`);
+    }
+    const pendingApprovals = new Map();
+    /**
+     * In-flight `tool.approval-resolved` emissions. `EventBus.emit` awaits its
+     * subscribers in order, so one async handler ahead of a channel adapter
+     * suspends the emission before the adapter ever sees it. Nothing today is
+     * async in front of one — which is exactly the problem: the shutdown
+     * guarantee below would rest on that staying true, and the first async
+     * subscriber anyone adds would silently leave live-looking buttons in a
+     * workspace the daemon has left.
+     */
+    const approvalEmissions = new Set();
+    /**
+     * Publishes one parked call and settles when somebody answers it, the
+     * request expires, or the turn is cancelled.
+     *
+     * All three endings run through the same `settle`, which removes the
+     * request from the registry BEFORE resolving. That ordering is the whole
+     * point: a request that is no longer pending cannot be resolved twice,
+     * so a click racing the timeout — or arriving after an abort — is refused
+     * rather than executing a tool for a turn that has already moved on.
+     */
+    const requestApproval = (request) => new Promise((resolve) => {
+        // A shutdown denies what is parked once, at the top of stop(). Turns
+        // already running keep going through the drain, though, and one of them
+        // can reach a gated tool AFTER that snapshot — finishing a provider
+        // call, or moving to the next call in the same response. Parking it
+        // would deadlock the drain against a question nobody is left to answer:
+        // stop() waits for the turn, the turn waits for the approval, and the
+        // approval waits out its timeout — forever when there is none.
+        if (stopping) {
+            resolve('deny');
+            void bus.emit({
+                type: 'tool.approval-resolved',
+                sessionId: request.session.id,
+                requestId: randomUUID(),
+                answer: 'deny',
+                reason: 'cancelled',
+            });
+            return;
+        }
+        const requestId = randomUUID();
+        let timer;
+        const onAbort = () => settle('deny', 'cancelled');
+        /**
+         * Settles once the request has finished being announced.
+         *
+         * Both emissions go through the same subscriber list, in order, and
+         * `EventBus.emit` awaits each one — so an async subscriber ahead of a
+         * channel can hold the announcement while a timeout or abort fires
+         * behind it, and the channel would hear that a request it has never
+         * heard of was resolved. It drops that, then renders the announcement
+         * when it finally arrives, leaving buttons for a settled request that
+         * nothing will ever retract.
+         *
+         * Chaining is the fix rather than remembering orphaned resolutions in
+         * the channel: a resolution that arrives before its request is not
+         * something a consumer can act on, so it should not be able to happen.
+         * Starts resolved, because a turn already aborted never announces at
+         * all and its denial should not wait on an emission that never runs.
+         */
+        let announced = Promise.resolve();
+        const settle = (answer, reason, actor) => {
+            // Identity, not presence: a request that already settled is gone from
+            // the registry, and comparing against this exact function is what
+            // makes every ending — click, timeout, abort, shutdown — idempotent.
+            if (pendingApprovals.get(requestId)?.settle !== settle) {
+                return;
+            }
+            pendingApprovals.delete(requestId);
+            if (timer) {
+                clearTimeout(timer);
+            }
+            request.signal?.removeEventListener('abort', onAbort);
+            resolve(answer);
+            const emitted = announced.then(() => bus.emit({
+                type: 'tool.approval-resolved',
+                sessionId: request.session.id,
+                requestId,
+                answer,
+                reason,
+                ...(actor ? { actor } : {}),
+            }));
+            approvalEmissions.add(emitted);
+            void emitted.finally(() => approvalEmissions.delete(emitted));
+        };
+        // What is left of the window, not a fresh one: a re-asked request
+        // carries when it originally parked, and the elapsed time counts.
+        // Computed before registration because the summary below quotes the
+        // deadline, and a listing that disagreed with the announcing event about
+        // when a request expires would be worse than one that said nothing.
+        const alreadyWaitedMs = request.parkedAt ? Date.now() - Date.parse(request.parkedAt) : 0;
+        const remainingTimeoutMs = effectiveApprovalTimeoutMs > 0
+            ? effectiveApprovalTimeoutMs - (Number.isFinite(alreadyWaitedMs) ? Math.max(0, alreadyWaitedMs) : 0)
+            : 0;
+        const expiresAt = remainingTimeoutMs > 0
+            ? new Date(Date.now() + remainingTimeoutMs).toISOString()
+            : undefined;
+        pendingApprovals.set(requestId, {
+            settle,
+            pending: {
+                requestId,
+                sessionId: request.session.id,
+                agentId: request.session.agent.id,
+                call: request.call,
+                risk: request.risk,
+                parkedAt: request.parkedAt ?? new Date().toISOString(),
+                ...(expiresAt ? { expiresAt } : {}),
+                ...(request.session.metadata ? { metadata: request.session.metadata } : {}),
+            },
+        });
+        if (effectiveApprovalTimeoutMs > 0 && remainingTimeoutMs <= 0) {
+            // Nothing left to wait with. Settled here rather than armed with a
+            // zero timer, which `setTimeout` would still run a tick later — long
+            // enough to announce a request that is already over.
+            settle('deny', 'timeout');
+            return;
+        }
+        if (remainingTimeoutMs > 0) {
+            // Deliberately NOT unref'd. A parked turn is real outstanding work,
+            // and its timer is the only thing that will ever finish it — letting
+            // the process exit out from under one would abandon the turn instead
+            // of denying it. Shutdown is handled where it belongs, in stop(),
+            // which settles every outstanding request before draining.
+            timer = setTimeout(() => settle('deny', 'timeout'), remainingTimeoutMs);
+        }
+        // The abort listener is attached before the request is announced, so a
+        // turn cancelled while the event is still being delivered still ends
+        // the request rather than leaving it pending forever.
+        if (request.signal) {
+            if (request.signal.aborted) {
+                settle('deny', 'cancelled');
+                return;
+            }
+            request.signal.addEventListener('abort', onAbort, { once: true });
+        }
+        // `announced` is assigned BEFORE the emission starts, because emit runs
+        // its first subscribers synchronously — one of them settling the
+        // request inline would otherwise chain onto the already-resolved
+        // placeholder and race the very announcement it is answering.
+        let markAnnounced = () => { };
+        announced = new Promise((resolveAnnounced) => {
+            markAnnounced = resolveAnnounced;
+        });
+        const announcing = bus.emit({
+            type: 'tool.approval-requested',
+            sessionId: request.session.id,
+            agentId: request.session.agent.id,
+            requestId,
+            call: request.call,
+            risk: request.risk,
+            ...(request.session.metadata ? { metadata: request.session.metadata } : {}),
+            ...(expiresAt ? { expiresAt } : {}),
+        });
+        // Drained at shutdown alongside the resolutions: a channel that has not
+        // yet been told a request exists cannot be told it was denied either.
+        approvalEmissions.add(announcing);
+        void announcing.finally(() => {
+            approvalEmissions.delete(announcing);
+            markAnnounced();
+        });
+    });
+    const resolveApproval = (input) => {
+        const parked = pendingApprovals.get(input.requestId);
+        if (!parked) {
+            return false;
+        }
+        parked.settle(input.answer, input.reason ?? 'decided', input.actor);
+        return true;
+    };
+    /**
+     * How a turn's watchdog stops its own clock, registered while it runs.
+     *
+     * Recording that a tool phase is open is not enough on its own: the
+     * timer is only re-evaluated when an event arrives, so a phase opened by
+     * something that emits nothing — an approval policy handed straight to
+     * the gateway — would leave an already-armed timer running to fire
+     * mid-wait.
+     */
+    const suspendWatchdog = new Map();
+    /**
+     * Approval waits in progress, per session.
+     *
+     * Deliberately a balanced counter and not a set of call ids. An earlier
+     * shape had the approval wrapper *open* a phase that the watchdog's
+     * event observer was expected to close, and that handoff was wrong in
+     * every way it could be: the observer does not exist when no watchdog is
+     * armed, so nothing closed it; a policy that threw closed nothing; and a
+     * stale entry did not merely leak, it suppressed the watchdog for the
+     * next turn on that session. Four separate exits, each patched in turn.
+     *
+     * A counter incremented and decremented in one `finally` cannot have any
+     * of those bugs, because the thing that opens the phase is the thing
+     * that closes it, in the same scope, on every path out.
+     */
+    const approvalWaits = new Map();
+    const holdApprovalWait = (sessionId) => {
+        approvalWaits.set(sessionId, (approvalWaits.get(sessionId) ?? 0) + 1);
+        // Stop any clock already running: this wait produces no events, so
+        // nothing else would.
+        suspendWatchdog.get(sessionId)?.();
+        let released = false;
+        return () => {
+            if (released) {
+                return;
+            }
+            released = true;
+            const remaining = (approvalWaits.get(sessionId) ?? 1) - 1;
+            if (remaining > 0) {
+                approvalWaits.set(sessionId, remaining);
+            }
+            else {
+                approvalWaits.delete(sessionId);
+            }
+        };
+    };
+    const configuredApprovals = typeof options.approvals === 'function'
+        ? options.approvals({ request: requestApproval })
+        : options.approvals;
+    /**
+     * Every approval opens a tool phase, whatever policy answers it.
+     *
+     * `tool.approval-requested` is the broker's event, so it exists only for
+     * the remote path; a policy handed straight to the gateway emits nothing
+     * at all, and `tool.called` comes only *after* the answer. Without this,
+     * a slow custom policy on a streaming provider that hosts its own loop
+     * would be indistinguishable from a stalled turn — the case this
+     * watchdog work exists to stop, arriving through a different door.
+     */
+    const approvals = configuredApprovals
+        ? {
+            async approve(context) {
+                const release = holdApprovalWait(context.session.id);
+                try {
+                    return await configuredApprovals.approve(context);
+                }
+                finally {
+                    // Every path out, including a policy that throws. What happens
+                    // after the answer is the tool events' business, and they are
+                    // observed by the watchdog itself.
+                    release();
+                }
+            },
+        }
+        : undefined;
     const registry = new AgentRegistry();
     const sources = new Map();
     // ---- roster -------------------------------------------------------------
@@ -245,26 +556,79 @@ export const createGateway = (options = {}) => {
         lastDefaultAgentId = id;
         return id;
     };
+    /**
+     * Build the roster from what is on disk right now.
+     *
+     * Runs at start and again on every `reloadRoster()`, which is why it
+     * tracks what it registered rather than only adding: a soul file deleted
+     * since the last pass has to stop being dispatchable, and re-registering
+     * the survivors over a map nothing removes from would leave it addressable
+     * — by id, and from every channel — for the rest of the daemon's life.
+     */
     const loadRoster = async () => {
+        const seen = new Set();
+        const registerFresh = (source) => {
+            registerSource(source);
+            seen.add(source.definition.id);
+        };
         // The built-in id is reserved BEFORE ordinary roster entries load: a
         // roster file that happens to declare id "stratus" must not hijack
         // the documented built-in fallback for agentId-less dispatches — the
-        // duplicate guard below skips it with a warning. Only the explicitly
+        // guard below skips it with a warning. Only the explicitly
         // configured default soul may take the id over (defaultAgentId
         // replaces a pathless source).
-        registerSource({ definition: { ...DEFAULT_STRATUS_AGENT } });
+        registerFresh({ definition: { ...DEFAULT_STRATUS_AGENT } });
+        // Throws on two roster files claiming one id: that is a collision with
+        // no correct winner, and refusing to serve beats letting sort order
+        // decide whose sessions, memory, and credentials an agent inherits.
         const entries = await loadRosterSouls(env, warn);
         for (const entry of entries) {
-            if (sources.has(entry.soul.agent.id)) {
-                const existing = sources.get(entry.soul.agent.id);
-                warn(`duplicate agent id ${entry.soul.agent.id} (${existing?.soulPath ?? 'built-in'} vs ${entry.path}); keeping the first`);
+            // Against ids claimed by THIS pass, not by any earlier one: a reload
+            // must be free to re-register the agent it just re-read, and only the
+            // built-in above can legitimately block a roster file.
+            if (seen.has(entry.soul.agent.id)) {
+                // Only reachable for the reserved built-in id now — roster-vs-
+                // roster duplicates never get this far. Reserved is not the same
+                // failure as duplicated: a soul may not take the fallback over,
+                // and must not be able to take the daemon down by trying.
+                warn(`agent id ${entry.soul.agent.id} is reserved for the built-in agent; ignoring ${entry.path}`);
                 continue;
             }
-            registerSource({ definition: entry.soul.agent, soulPath: entry.path, soul: entry.soul });
+            registerFresh({ definition: entry.soul.agent, soulPath: entry.path, soul: entry.soul });
         }
         // The configured default soul is part of the roster too — it is what
-        // an agentId-less dispatch answers as.
-        await defaultAgentId();
+        // an agentId-less dispatch answers as. It may live outside the agents
+        // directory, and it survives a read failure by name, so what it
+        // resolves to is kept whether or not this pass re-registered it.
+        seen.add(await defaultAgentId());
+        for (const id of [...sources.keys()]) {
+            if (!seen.has(id)) {
+                sources.delete(id);
+                registry.unregister(id);
+            }
+        }
+    };
+    /**
+     * Roster rebuilds, one at a time.
+     *
+     * `loadRoster` prunes by comparing the registry against the ids *this pass*
+     * saw, so two overlapping passes destroy each other's work: the older one
+     * snapshots a roster without agent B, the newer one registers B and
+     * finishes, and then the older one reaches its prune and unregisters B —
+     * which two clients creating agents at once will do, each having been told
+     * 201 for an agent that is no longer dispatchable.
+     *
+     * A chain rather than a lock: a reload is idempotent, so a caller arriving
+     * mid-rebuild wants the *next* complete one, and waiting for it is exactly
+     * what this gives them.
+     */
+    let reloads = Promise.resolve();
+    const reloadsInOrder = async () => {
+        const next = reloads.then(loadRoster, loadRoster);
+        // Swallowed for the chain only — the caller still sees the rejection, but
+        // a roster that failed to load must not block every reload after it.
+        reloads = next.catch(() => undefined);
+        await next;
     };
     /**
      * A session pins its agent id, never a snapshot of the agent: the soul
@@ -306,6 +670,11 @@ export const createGateway = (options = {}) => {
     };
     // ---- runner pool --------------------------------------------------------
     const tools = new ToolRegistry();
+    // Which package each tool came from. Kernel tools are absent from this
+    // map, which is how `tools()` reports them as the kernel's.
+    const toolProvenance = new Map();
+    let loadedPlugins = [];
+    let pluginFailures = [];
     tools.register(createDemoTool());
     tools.register(createRememberTool(memory));
     // Delegation is dispatcher-backed, not runner-capturing: the target agent
@@ -357,7 +726,7 @@ export const createGateway = (options = {}) => {
             provider,
             tools,
             executor: createLocalCommandExecutor(),
-            ...(options.approvals ? { approvals: options.approvals } : {}),
+            ...(approvals ? { approvals } : {}),
             store,
             bus,
             agents: registry,
@@ -379,8 +748,16 @@ export const createGateway = (options = {}) => {
      * that kills slow-but-healthy turns, so it stays off for them (their
      * tool phases are covered by executor timeouts regardless).
      */
-    const fallbackStreamsDeltas = (fallback) => fallback.provider === 'anthropic' && Boolean(fallback.apiKey);
-    const streamsDeltas = (config) => config.provider === 'anthropic' && Boolean(config.apiKey);
+    const fallbackStreamsDeltas = (fallback) => 
+    // The same two modes as a primary. A subscription fallback that is not
+    // recognised as streaming gets no watchdog at all once a session
+    // switches to it, so a stall there would run to the provider's own
+    // ten-minute timer instead of the idle timeout the operator set.
+    fallback.provider === 'anthropic' && Boolean(fallback.apiKey || fallback.authToken);
+    const streamsDeltas = (config) => 
+    // Both Anthropic modes stream now: an API key through the Messages
+    // API, a subscription token through the Agent SDK's partial messages.
+    config.provider === 'anthropic' && Boolean(config.apiKey || config.authToken);
     /**
      * Progress-based abort, armed only while the turn is actually awaiting a
      * streaming provider — the one phase where silence means a stall. Tool
@@ -413,6 +790,18 @@ export const createGateway = (options = {}) => {
         // the primary until a reset delta announces the sticky fallback switch.
         let streamingActive = idleEnabled;
         let pendingTools = 0;
+        /**
+         * Tool calls this turn has started and not finished.
+         *
+         * `pendingTools` above reads a count off `provider.response`, which
+         * only a provider that hands its calls back to the kernel loop emits.
+         * A provider hosting its own loop dispatches inside `generate`, so that
+         * count is zero for the whole of a hosted tool. These are the kernel's
+         * own tool events, which every path emits because every path runs its
+         * tools through the same executor — and they are turn-local, so an
+         * aborted turn takes them with it rather than leaving anything behind.
+         */
+        const openToolCalls = new Set();
         // Set at a text-only provider.response: the turn is wrapping up
         // (saves, completion events); nothing left for the timer to guard.
         let turnSettling = false;
@@ -450,9 +839,13 @@ export const createGateway = (options = {}) => {
             }
             switch (event.type) {
                 case 'provider.delta':
-                    // A reset marks the mid-turn, session-sticky fallback switch:
-                    // the timer follows whether the now-active provider streams.
-                    if (event.delta.type === 'reset') {
+                    // Only a *fallback* reset marks the mid-turn, session-sticky
+                    // switch that the timer follows. A provider retrying its own
+                    // attempt abandons its partial output too, but nothing about
+                    // who is serving the turn changed — reading that as a switch
+                    // would disarm the watchdog for the rest of a turn that is
+                    // still running on the provider it started on.
+                    if (event.delta.type === 'reset' && event.delta.reason === 'fallback') {
                         streamingActive = fallbackStreams;
                     }
                     break;
@@ -466,8 +859,23 @@ export const createGateway = (options = {}) => {
                         turnSettling = true;
                     }
                     break;
+                case 'tool.approval-requested':
+                    // Redundant with the approval wrapper for a gateway-owned
+                    // transport, and not redundant for a recovered turn, whose
+                    // request is re-announced without going through a policy again.
+                    openToolCalls.add(event.call.id);
+                    break;
+                case 'tool.called':
+                    openToolCalls.add(event.call.id);
+                    break;
                 case 'tool.completed':
+                    // Completion names the call through its result; denial carries
+                    // the call itself. Both settle it.
+                    openToolCalls.delete(event.result.callId);
+                    pendingTools = Math.max(0, pendingTools - 1);
+                    break;
                 case 'tool.denied':
+                    openToolCalls.delete(event.call.id);
                     pendingTools = Math.max(0, pendingTools - 1);
                     break;
                 default:
@@ -479,10 +887,15 @@ export const createGateway = (options = {}) => {
             if (!('sessionId' in event) || event.sessionId !== sessionId) {
                 return;
             }
-            if (streamingActive && pendingTools === 0 && !turnSettling) {
+            if (streamingActive
+                && pendingTools === 0
+                && openToolCalls.size === 0
+                && (approvalWaits.get(sessionId) ?? 0) === 0
+                && !turnSettling) {
                 armTimer();
             }
         });
+        suspendWatchdog.set(sessionId, suspendTimer);
         if (streamingActive) {
             armTimer();
         }
@@ -499,6 +912,7 @@ export const createGateway = (options = {}) => {
             suspendTimer();
             unsubscribeObserver();
             unsubscribeDrain();
+            suspendWatchdog.delete(sessionId);
             external?.removeEventListener('abort', onExternalAbort);
         }
     };
@@ -509,23 +923,26 @@ export const createGateway = (options = {}) => {
     const sessionChains = new Map();
     const inflight = new Set();
     let stopping = false;
-    const dispatchInternal = async (input) => {
-        // A dispatch whose signal fired while it queued behind another turn
-        // must not touch durable state: without this check, the runner would
-        // load the session, append the cancelled user message, and save it as
-        // failed — polluting future model history with input never processed.
-        if (input.signal?.aborted) {
-            throw new RunAbortedError();
-        }
-        // A session pins its agent: when the caller names none, an existing
-        // conversation keeps the agent it was created with even if the
-        // configured default soul has changed since — only a brand-new session
-        // takes the current default. (Loaded here, before the watchdog, also
-        // because whether this turn streams depends on durable session state.)
-        const existing = await store.get(input.sessionId);
-        const agentId = input.agentId ?? existing?.agent.id ?? await defaultAgentId();
-        const source = await refreshAgent(agentId);
-        const agent = source.definition;
+    /**
+     * The turn id running on each session, for callers that named one.
+     *
+     * Set when the chained work actually starts — not when the dispatch was
+     * queued — because a message waiting behind another turn has not begun,
+     * and stamping events with it would attribute the running turn's output to
+     * the queued one. Single-flight per session is what makes one entry per
+     * session sufficient.
+     */
+    const activeTurns = new Map();
+    /**
+     * The runtime one agent would run on right now — config snapshot, soul
+     * pins, degradation and all.
+     *
+     * Extracted so recovery resolves it exactly as a dispatch does. A second
+     * copy of this chain is the difference between a recovered turn finishing
+     * on its agent's provider and finishing on the daemon's default, and it
+     * would drift the first time either side gained a rule.
+     */
+    const runtimeForAgent = async (source) => {
         // Config re-resolves per dispatch, so a changed model, credential, or
         // soul pin applies without a restart. The pool dedupes runners by the
         // resolved configuration. The gateway-wide selection and the daemon's
@@ -584,7 +1001,26 @@ export const createGateway = (options = {}) => {
         }
         // The preset snapshot means resolution reads no config file — every
         // failure from here is a credential or provider problem and surfaces.
-        const config = await resolveRuntimeConfig(selection, resolveEnv);
+        return resolveRuntimeConfig(selection, resolveEnv);
+    };
+    const dispatchInternal = async (input) => {
+        // A dispatch whose signal fired while it queued behind another turn
+        // must not touch durable state: without this check, the runner would
+        // load the session, append the cancelled user message, and save it as
+        // failed — polluting future model history with input never processed.
+        if (input.signal?.aborted) {
+            throw new RunAbortedError();
+        }
+        // A session pins its agent: when the caller names none, an existing
+        // conversation keeps the agent it was created with even if the
+        // configured default soul has changed since — only a brand-new session
+        // takes the current default. (Loaded here, before the watchdog, also
+        // because whether this turn streams depends on durable session state.)
+        const existing = await store.get(input.sessionId);
+        const agentId = input.agentId ?? existing?.agent.id ?? await defaultAgentId();
+        const source = await refreshAgent(agentId);
+        const agent = source.definition;
+        const config = await runtimeForAgent(source);
         const runner = runnerFor(config);
         const metadata = {
             ...(config.provider === 'demo'
@@ -626,52 +1062,328 @@ export const createGateway = (options = {}) => {
             });
         });
     };
-    const dispatch = async (input) => {
+    /**
+     * Finishes the turns that were parked on a human when this daemon last
+     * went down.
+     *
+     * Run after the channels are up, deliberately: recovery re-asks, and a
+     * request emitted into a gateway with no live adapter would be declined
+     * for want of anywhere to put it — turning "your approval survived the
+     * restart" into "your approval was denied by the restart".
+     *
+     * Each session is recovered independently and failures are per-session:
+     * one unrecoverable turn must not stop the daemon from serving, or from
+     * recovering the others.
+     */
+    const recoverParkedTurns = async () => {
+        if (!store.listIdsByStatus) {
+            return;
+        }
+        const parked = await store.listIdsByStatus('pending_approval');
+        if (parked.length === 0) {
+            return;
+        }
+        log(`recovering ${parked.length} turn(s) parked on approval`);
+        // Started together, not one after another. Each recovery re-asks and
+        // then waits on a human, so awaiting them in sequence would mean the
+        // second parked turn is not even *announced* until the first is
+        // answered — fifteen minutes later by default, and never at all with a
+        // zero timeout. They are independent turns; only same-session work is
+        // ordered, and onSessionChain already guarantees that.
+        await Promise.allSettled(parked.map((sessionId) => recoverOne(sessionId)));
+    };
+    const recoverOne = (sessionId) => onSessionChain(sessionId, async () => {
         if (stopping) {
-            throw new Error('The gateway is stopping and no longer accepts new work.');
+            return;
+        }
+        try {
+            const session = await store.get(sessionId);
+            if (!session) {
+                return;
+            }
+            const record = readPendingApproval(session);
+            // A wait that outlived its window while the daemon was down is
+            // honoured, not restarted: the request really did go unanswered for
+            // the whole time it was configured to wait, and downtime is not a
+            // reason to extend a security decision. Measured from when the turn
+            // parked against this daemon's timeout — the transport's original
+            // deadline was chosen after the checkpoint was written and is gone
+            // with the process that chose it. Denying goes through the same
+            // recovery path, so the queue behind it still drains.
+            const parkedAt = record ? Date.parse(record.parkedAt) : Number.NaN;
+            const expired = effectiveApprovalTimeoutMs > 0
+                && Number.isFinite(parkedAt)
+                && Date.now() - parkedAt >= effectiveApprovalTimeoutMs;
+            if (expired) {
+                log(`${sessionId}: the approval for ${record?.call.toolName} outlived its window while the daemon was down; denying it`);
+            }
+            // Resolved the way a dispatch for this agent would resolve it, so a
+            // recovered turn finishes on the same provider, model, and
+            // credentials it was parked on.
+            const source = await refreshAgent(session.agent.id);
+            // And on the CURRENT definition, saved before recovery reads the
+            // session back. An allowlist is a permission boundary: a soul that
+            // dropped a tool while the daemon was down must not have that tool
+            // executed by the turn that outlived the change, and
+            // `allowedToolsFor` reads the definition frozen into the session
+            // ahead of the registry. Dispatch refreshes it the same way before
+            // resuming.
+            session.agent = source.definition;
+            await store.save(session);
+            const runner = runnerFor(await runtimeForAgent(source));
+            await runner.recoverPendingApproval(sessionId, { denyPending: expired });
+        }
+        catch (error) {
+            warn(`could not recover parked session ${sessionId}: ${error instanceof Error ? error.message : String(error)}`);
         }
-        const previous = sessionChains.get(input.sessionId) ?? Promise.resolve();
-        const turn = previous.then(() => dispatchInternal(input), () => dispatchInternal(input));
+    });
+    /**
+     * Turns the last process was still running when it stopped being able to
+     * finish them.
+     *
+     * `pending_approval` is the one window a turn can be picked up from, and
+     * it has its own sweep above. Everything else a turn does is saved as
+     * `running`: the provider call, the executor, and — on a provider that
+     * hosts its own loop — the approval wait too, since a hosted call is
+     * deliberately not checkpointed (`executeHostedToolCall` passes
+     * `recoverable: false`, because the SDK's inner loop is not something a
+     * restart can rebuild). None of those can be resumed, and nothing else
+     * sweeps them, so the record goes on claiming the turn is running for as
+     * long as the session exists.
+     *
+     * Note what this is *not* for. A graceful stop denies everything parked
+     * and drains the turns those denials release, so an operator restarting
+     * the daemon normally has nothing here. These are the turns a crash, a
+     * SIGKILL, or a lost machine left behind.
+     */
+    const listAbandonedTurns = async () => {
+        if (!store.listIdsByStatus) {
+            return [];
+        }
+        return store.listIdsByStatus('running');
+    };
+    /**
+     * Marks each of them failed, with a reason that says what happened.
+     *
+     * Read BEFORE the channels start and applied after, which is the only
+     * ordering that is both honest and safe. Reading first means the list is
+     * exactly what the last process left, with no chance of a turn this
+     * process started being in it. Applying after means the failure is
+     * emitted into a gateway whose surfaces are listening, rather than into
+     * one where nothing is.
+     *
+     * The gap between the two is real, though: an inbound message for one of
+     * these sessions can arrive as soon as the channels are up. What makes
+     * that safe is single-flight — every writer of a session goes through
+     * `onSessionChain`, so this runs either wholly before that turn (it
+     * fails, and `resume()` then clears `lastError` and starts fresh) or
+     * wholly after it (the status has moved off `running`, and the re-read
+     * below leaves it alone). There is no interleaving in which this
+     * overwrites a live turn.
+     *
+     * What that invariant does NOT cover is a second daemon on the same
+     * database, whose turns are running with no chain of ours in front of
+     * them. Two processes sharing a session store is already unsupported —
+     * the parked sweep above would re-ask that daemon's approvals for the
+     * same reason — and no check here would make it supported.
+     */
+    const failAbandonedTurns = async (abandoned) => {
+        if (abandoned.length === 0) {
+            return;
+        }
+        log(`failing ${abandoned.length} turn(s) left running by the last stratusd`);
+        await Promise.allSettled(abandoned.map((id) => failAbandonedTurn(id)));
+    };
+    const failAbandonedTurn = (id) => onSessionChain(id, async () => {
+        if (stopping) {
+            return;
+        }
+        try {
+            const session = await store.get(id);
+            // Re-read on the chain, because the snapshot is from before the
+            // channels came up: a message that arrived since has already taken
+            // this session somewhere else, and that turn owns it now.
+            if (!session || session.status !== 'running') {
+                return;
+            }
+            session.status = 'failed';
+            session.lastError = ABANDONED_TURN_ERROR;
+            await store.save(session);
+            await bus.emit({ type: 'session.updated', sessionId: id, status: 'failed' });
+            await bus.emit({ type: 'session.failed', sessionId: id, error: ABANDONED_TURN_ERROR });
+        }
+        catch (error) {
+            warn(`could not fail abandoned turn ${id}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
+    /**
+     * Runs `work` as the session's next turn: queued behind whatever that
+     * session is already doing, and tracked so shutdown drains it.
+     *
+     * Recovery goes through here as well as dispatch, and must. Channels are
+     * live before a sweep finishes, so an inbound message for a parked
+     * session could otherwise `resume()` alongside `recoverPendingApproval()`
+     * — one closing the parked call as interrupted while the other re-enters
+     * it, both saving divergent copies of the same transcript, and the tool
+     * possibly running twice. Single-flight per session is the invariant that
+     * stops that, and it only holds if everything that writes a session goes
+     * through it.
+     */
+    const onSessionChain = (sessionId, work) => {
+        const previous = sessionChains.get(sessionId) ?? Promise.resolve();
+        const turn = previous.then(work, work);
         const settled = turn.catch(() => { });
-        sessionChains.set(input.sessionId, settled);
+        sessionChains.set(sessionId, settled);
         inflight.add(settled);
         void settled.finally(() => {
             inflight.delete(settled);
-            if (sessionChains.get(input.sessionId) === settled) {
-                sessionChains.delete(input.sessionId);
+            if (sessionChains.get(sessionId) === settled) {
+                sessionChains.delete(sessionId);
             }
         });
         return turn;
     };
+    const dispatch = async (input) => {
+        if (stopping) {
+            throw new Error('The gateway is stopping and no longer accepts new work.');
+        }
+        const { turnId } = input;
+        if (turnId === undefined) {
+            return onSessionChain(input.sessionId, () => dispatchInternal(input));
+        }
+        return onSessionChain(input.sessionId, async () => {
+            activeTurns.set(input.sessionId, turnId);
+            try {
+                return await dispatchInternal(input);
+            }
+            finally {
+                // Unconditional, and safe to be: the chain guarantees no other turn
+                // for this session ran between the set above and here, so this can
+                // only ever be clearing its own entry.
+                activeTurns.delete(input.sessionId);
+            }
+        });
+    };
+    /**
+     * Load what the config asked for, and say what did not load.
+     *
+     * A plugin that fails is a warning rather than a refusal to start: a
+     * daemon that will not boot because of a mistyped package name takes the
+     * whole fleet down over one line of config, and the agents whose tools
+     * did load are still worth serving. What is never degraded is the
+     * security half — an undeclared name or a collision refuses that plugin
+     * whole, inside the loader.
+     */
+    const startPlugins = async () => {
+        const configured = options.plugins ?? {};
+        if (Object.keys(configured).length === 0) {
+            return;
+        }
+        const result = await loadPlugins({
+            config: configured,
+            host: options.pluginHost ?? {
+                resolve: (specifier) => import.meta.resolve(specifier),
+                import: (specifier) => import(specifier),
+            },
+            tools,
+            bus,
+            workspaceRoot: workspacesDirPath(env),
+        });
+        loadedPlugins = result.loaded;
+        pluginFailures = result.failures;
+        for (const plugin of result.loaded) {
+            for (const tool of plugin.tools) {
+                toolProvenance.set(tool.name, { package: plugin.package, trusted: plugin.trusted });
+            }
+            log(`plugin ${plugin.package} loaded — ${plugin.tools.map((tool) => `${tool.name} (${tool.risk})`).join(', ') || 'no tools'}`);
+        }
+        for (const failure of result.failures) {
+            warn(`plugin ${failure.package} did not load: ${failure.reason}`);
+        }
+    };
+    /**
+     * Everything after the plugins: the roster, the channels, and the sweeps
+     * that need both. Split out so `start()` can wrap it in the cleanup a
+     * failure here requires — see the call site.
+     */
+    const startServing = async () => {
+        await loadRoster();
+        const named = registry.list().map((agent) => agent.name).join(', ');
+        log(`stratusd ready — ${registry.list().length} agent(s): ${named}`);
+        // Read before anything can dispatch, so this is exactly what the
+        // last process left running and not a turn of ours caught in flight.
+        // Applied further down, once there is somewhere for the failure to
+        // be heard.
+        const abandoned = await listAbandonedTurns();
+        // Channels come up after the roster so their first inbound message
+        // already has agents to dispatch to. One failing adapter must not
+        // keep the rest (or the gateway) down.
+        for (const adapter of options.channels ?? []) {
+            try {
+                await adapter.start(gateway);
+                startedChannels.push(adapter);
+            }
+            catch (error) {
+                warn(`channel ${adapter.name} failed to start: ${error instanceof Error ? error.message : String(error)}`);
+                // A start() that rejected may still hold sockets or listeners it
+                // acquired before failing; it never reaches startedChannels, so
+                // this is its only cleanup.
+                try {
+                    await adapter.stop();
+                }
+                catch (stopError) {
+                    warn(`channel ${adapter.name} cleanup after failed start also failed: ${stopError instanceof Error ? stopError.message : String(stopError)}`);
+                }
+            }
+        }
+        // Last, and not awaited: recovery re-asks, so it needs the channels
+        // above already listening — but a turn parked behind a slow approver
+        // must not hold up start(), or a daemon with one outstanding request
+        // would refuse to finish booting.
+        void recoverParkedTurns().catch((error) => {
+            warn(`recovering parked turns failed: ${error instanceof Error ? error.message : String(error)}`);
+        });
+        // Not awaited for the same reason, and independent of the sweep
+        // above: these sessions are not parked, so the two never touch the
+        // same one.
+        void failAbandonedTurns(abandoned).catch((error) => {
+            warn(`failing abandoned turns failed: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    };
+    /** Release what the plugins acquired, reporting rather than throwing. */
+    const disposePlugins = async () => {
+        await Promise.allSettled(loadedPlugins.map(async (plugin) => {
+            try {
+                await plugin.instance.dispose?.();
+            }
+            catch (error) {
+                warn(`plugin ${plugin.package} failed to shut down: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }));
+        loadedPlugins = [];
+    };
     const startedChannels = [];
     const gateway = {
         bus,
         store,
         async start() {
             await migrateLegacyMemory(env);
-            await loadRoster();
-            const named = registry.list().map((agent) => agent.name).join(', ');
-            log(`stratusd ready — ${registry.list().length} agent(s): ${named}`);
-            // Channels come up after the roster so their first inbound message
-            // already has agents to dispatch to. One failing adapter must not
-            // keep the rest (or the gateway) down.
-            for (const adapter of options.channels ?? []) {
-                try {
-                    await adapter.start(gateway);
-                    startedChannels.push(adapter);
-                }
-                catch (error) {
-                    warn(`channel ${adapter.name} failed to start: ${error instanceof Error ? error.message : String(error)}`);
-                    // A start() that rejected may still hold sockets or listeners it
-                    // acquired before failing; it never reaches startedChannels, so
-                    // this is its only cleanup.
-                    try {
-                        await adapter.stop();
-                    }
-                    catch (stopError) {
-                        warn(`channel ${adapter.name} cleanup after failed start also failed: ${stopError instanceof Error ? stopError.message : String(stopError)}`);
-                    }
-                }
+            // Before the roster and before channels: a turn must never arrive for
+            // an agent whose soul lists a tool the daemon has not registered yet,
+            // which would refuse the call as "not permitted" and blame the soul.
+            await startPlugins();
+            try {
+                await startServing();
+            }
+            catch (error) {
+                // Everything after the plugins loaded is inside that try for one
+                // reason: a `start()` that rejects never reaches its caller's
+                // shutdown path — `stratus serve` awaits it *before* the try/finally
+                // that calls `stop()` — so a duplicate agent id in the roster would
+                // leave a plugin's browser, socket, or subscription held for the
+                // life of a process that is on its way out.
+                await disposePlugins();
+                throw error;
             }
         },
         // Drain: channels stop taking messages, in-flight turns finish, new
@@ -682,16 +1394,112 @@ export const createGateway = (options = {}) => {
             // in-flight turns (already-started dispatches keep running), drain,
             // and close.
             stopping = true;
+            // Deny what is parked before draining, or the drain waits out every
+            // outstanding approval timeout — a shutdown would hang for as long as
+            // the longest request had left. Each denial is a real decision the
+            // turn continues from, so the drain below still finishes those turns.
+            for (const parked of [...pendingApprovals.values()]) {
+                parked.settle('deny', 'cancelled');
+            }
+            // Let those resolutions reach their subscribers before the channels
+            // go down, or a channel that renders approvals never learns to
+            // retract the buttons it is still showing.
+            await Promise.allSettled([...approvalEmissions]);
             await Promise.allSettled(startedChannels.map((adapter) => adapter.stop()));
             startedChannels.length = 0;
             await Promise.allSettled([...inflight]);
+            // After the turns that might still be using them. A plugin holding a
+            // browser is the reason this exists, and closing it out from under a
+            // running screenshot would fail that turn rather than tidy up.
+            await disposePlugins();
             store.close();
             log('stratusd stopped');
         },
         dispatch,
+        async sessionRouting(sessionId) {
+            const session = await store.get(sessionId);
+            return session
+                ? { agentId: session.agent.id, metadata: session.metadata ?? {} }
+                : undefined;
+        },
         agents() {
             return registry.list();
         },
+        async reloadRoster() {
+            await reloadsInOrder();
+            const roster = registry.list();
+            log(`roster reloaded — ${roster.length} agent(s): ${roster.map((agent) => agent.name).join(', ')}`);
+            return roster;
+        },
+        activeTurnId(sessionId) {
+            return activeTurns.get(sessionId);
+        },
+        pendingApprovals() {
+            return [...pendingApprovals.values()]
+                .map((parked) => parked.pending)
+                .sort((a, b) => a.parkedAt.localeCompare(b.parkedAt));
+        },
+        tools() {
+            // From the registry, not from the load records: the risk reported is
+            // the one a call will actually be judged at, floor applied, and a
+            // second list assembled from manifests would drift from it the first
+            // time a floor was raised.
+            return tools.describe().map((descriptor) => {
+                const provenance = toolProvenance.get(descriptor.name);
+                return {
+                    name: descriptor.name,
+                    ...(descriptor.description ? { description: descriptor.description } : {}),
+                    risk: descriptor.risk ?? 'gated',
+                    ...(provenance ? { package: provenance.package, trusted: provenance.trusted } : {}),
+                };
+            });
+        },
+        plugins() {
+            const loaded = loadedPlugins.map((plugin) => ({
+                package: plugin.package,
+                name: plugin.name,
+                trusted: plugin.trusted,
+                tools: plugin.tools.map((tool) => ({
+                    name: tool.name,
+                    ...(tool.description ? { description: tool.description } : {}),
+                    risk: tool.risk,
+                    package: plugin.package,
+                    trusted: plugin.trusted,
+                })),
+            }));
+            const failed = pluginFailures.map((failure) => ({
+                package: failure.package,
+                error: failure.reason,
+            }));
+            return [...loaded, ...failed];
+        },
+        async servedSouls() {
+            // From the registry rather than `sources` directly, so the order and
+            // the membership are the roster's own — one entry per agent `agents()`
+            // reports, and no entry for a source the registry no longer serves.
+            return Promise.all(registry.list().map(async (agent) => {
+                const source = sources.get(agent.id);
+                // Re-read, not re-registered: this is a read, and a caller asking
+                // what the daemon would bill must not reshape the roster as a side
+                // effect. `refreshAgent` still owns that on the dispatch path.
+                const fresh = source?.soulPath
+                    ? await loadSoulFile(source.soulPath).catch(() => undefined)
+                    : undefined;
+                if (fresh && fresh.agent.id !== agent.id) {
+                    // The file was given to another agent. `refreshAgent` refuses every
+                    // dispatch for this id until the roster reloads, so there is no
+                    // runtime being served under it — reporting the cached pins would
+                    // claim billing for turns that cannot run, and reporting no soul at
+                    // all would claim the daemon-wide default instead. It is omitted.
+                    return undefined;
+                }
+                // Unreadable is the one case the cache answers for: the gateway goes
+                // on dispatching from the soul it loaded, so those pins are live.
+                const soul = fresh ?? source?.soul;
+                return { id: agent.id, ...(soul ? { soul } : {}) };
+            })).then((entries) => entries.filter((entry) => entry !== undefined));
+        },
+        resolveApproval,
     };
     return gateway;
 };