@stratusagent/gateway 0.2.5 → 0.4.0

package/dist/index.js

@@ -1,13 +1,25 @@
-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';
 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,6 +96,17 @@ 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);
     }
+    /**
+     * 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);
+    }
     /** Newest-first session listing for one agent (or all agents). */
     list(agentId) {
         const rows = (agentId
@@ -101,6 +124,75 @@ export class SqliteSessionStore {
         this.db.close();
     }
 }
+/**
+ * Apply a soul's provider/model pins to a selection, demoting the
+ * daemon-wide defaults the pins outrank.
+ *
+ * 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.
+ */
+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 } };
+};
+/**
+ * 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
@@ -122,6 +214,253 @@ 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) {
+                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));
+        };
+        pendingApprovals.set(requestId, settle);
+        // What is left of the window, not a fresh one: a re-asked request
+        // carries when it originally parked, and the elapsed time counts.
+        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;
+        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 } : {}),
+            ...(remainingTimeoutMs > 0
+                ? { expiresAt: new Date(Date.now() + remainingTimeoutMs).toISOString() }
+                : {}),
+        });
+        // 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 settle = pendingApprovals.get(input.requestId);
+        if (!settle) {
+            return false;
+        }
+        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 -------------------------------------------------------------
@@ -190,15 +529,21 @@ export const createGateway = (options = {}) => {
         // 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 } });
+        // 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`);
+                // 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 });
@@ -298,7 +643,7 @@ export const createGateway = (options = {}) => {
             provider,
             tools,
             executor: createLocalCommandExecutor(),
-            ...(options.approvals ? { approvals: options.approvals } : {}),
+            ...(approvals ? { approvals } : {}),
             store,
             bus,
             agents: registry,
@@ -320,8 +665,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
@@ -354,6 +707,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;
@@ -391,9 +756,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;
@@ -407,8 +776,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:
@@ -420,10 +804,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();
         }
@@ -440,6 +829,7 @@ export const createGateway = (options = {}) => {
             suspendTimer();
             unsubscribeObserver();
             unsubscribeDrain();
+            suspendWatchdog.delete(sessionId);
             external?.removeEventListener('abort', onExternalAbort);
         }
     };
@@ -450,23 +840,16 @@ 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 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
@@ -509,55 +892,12 @@ export const createGateway = (options = {}) => {
             // to resolveRuntimeConfig instead would read the file a second
             // time, racing a concurrent replacement — this turn could keep one
             // agent's definition while adopting another's provider pins.
-            selection.presetSoul = pins;
-            if (pins.provider || pins.model) {
-                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 = options.selection?.provider
-                    ?? readNonEmptyString(processEnv.STRATUS_PROVIDER)
-                    ?? readNonEmptyString(processEnv.STRATUSCLAW_PROVIDER)
-                    ?? configSnapshot.config.provider
-                    ?? (configSnapshot.path !== undefined ? '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;
-                }
-                resolveEnv = { ...env, processEnv };
-            }
+            const normalized = applySoulPins(pins, selection, env, {
+                ...(options.selection?.provider !== undefined ? { selectionProvider: options.selection.provider } : {}),
+                ...(configSnapshot.config.provider !== undefined ? { configProvider: configSnapshot.config.provider } : {}),
+                configPresent: configSnapshot.path !== undefined,
+            });
+            resolveEnv = normalized.env;
         }
         else {
             // A soul-less agent (the built-in default) resolves with no soul at
@@ -568,7 +908,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'
@@ -610,23 +969,193 @@ 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)}`);
+        }
+    });
+    /**
+     * 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 });
         }
-        const previous = sessionChains.get(input.sessionId) ?? Promise.resolve();
-        const turn = previous.then(() => dispatchInternal(input), () => dispatchInternal(input));
+        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.');
+        }
+        return onSessionChain(input.sessionId, () => dispatchInternal(input));
+    };
     const startedChannels = [];
     const gateway = {
         bus,
@@ -636,6 +1165,11 @@ export const createGateway = (options = {}) => {
             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.
@@ -657,6 +1191,19 @@ export const createGateway = (options = {}) => {
                     }
                 }
             }
+            // 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)}`);
+            });
         },
         // Drain: channels stop taking messages, in-flight turns finish, new
         // dispatches are refused, then the database closes. SIGTERM handling
@@ -666,6 +1213,17 @@ 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 settle of [...pendingApprovals.values()]) {
+                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]);
@@ -676,6 +1234,7 @@ export const createGateway = (options = {}) => {
         agents() {
             return registry.list();
         },
+        resolveApproval,
     };
     return gateway;
 };