@stratusagent/gateway 0.9.2 → 0.11.0

package/dist/index.js

@@ -10,13 +10,14 @@ 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, SkillRegistry, ToolRegistry, createSkillReadTool, missingSkillRequirements, readPendingApproval, } from '@stratusagent/core';
-import { createDelegateTool, createForgetTool, createMessageSendTool, createRecallTool, createRememberTool, createScheduleTools, } from '@stratusagent/agents';
+import { abortErrorFor, AgentRegistry, AgentRunner, EventBus, RunAbortedError, SkillRegistry, ToolRegistry, createSkillReadTool, missingSkillRequirements, PENDING_APPROVAL_METADATA_KEY, latestTurnReply, readPendingApproval, } from '@stratusagent/core';
+import { createDelegateTool, createForgetTool, createMessageSendTool, createRecallTool, createRememberTool, createScheduleTools, DELEGATED_BY_METADATA_KEY, DELEGATION_DEPTH_METADATA_KEY, delegatingSessionIdOf, isDelegatedSession, outstandingDelegationFor, ROOT_SESSION_ID_METADATA_KEY, SCHEDULE_ID_METADATA_KEY, SCHEDULED_TURN_METADATA_KEY, withoutDelegation, } from '@stratusagent/agents';
 import { createSchedulerRuntime, isScheduleSessionId, SqliteScheduleStore, SCHEDULE_SESSION_ID_PREFIX, } from "./schedules.js";
-export { SqliteScheduleStore, createSchedulerRuntime, } from "./schedules.js";
+export { claimHome, homeLockPath, HomeClaimedError, } from "./lock.js";
+export { SqliteScheduleStore, createSchedulerRuntime, isScheduleSessionId, SCHEDULE_SESSION_ID_PREFIX, } from "./schedules.js";
 import { createLocalCommandExecutor } from '@stratusagent/executor-local';
 import { loadPlugins, } from '@stratusagent/plugins';
-import { createDemoTool, createFileMemoryStore, createRuntimeProvider, DEFAULT_STRATUS_AGENT, loadOperatorSkills, loadRosterSouls, FALLBACK_ACTIVE_METADATA_KEY, loadSoulFile, memoryFilePath, migrateLegacyMemory, ConfigFileError, loadConfigFile, resolveConfigLocation, resolveConfiguredSoul, resolveRuntimeConfig, applySoulPins, stratusHomePath, workspacesDirPath, withLegacyDefaultMemories, } from '@stratusagent/state';
+import { createDemoTool, createFileCredentialResolver, createFileMemoryStore, createRuntimeProvider, DEFAULT_STRATUS_AGENT, loadOperatorSkills, 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';
 /**
  * Where a daemon with no explicit `sessionDbPath` keeps its database — the
@@ -221,6 +222,26 @@ export class SqliteSessionStore {
  * question even when the rule answering it is not gateway code.
  */
 export { applySoulPins } from '@stratusagent/state';
+/** What a turn cut short by an announced restart records as its failure. */
+export const RESTARTING_TURN_ERROR = 'Run aborted: stratusd is restarting';
+/**
+ * How long an announced restart lets in-flight turns finish before aborting
+ * them. Matches the systemd unit's `TimeoutStopSec`, so the two windows an
+ * operator can hit agree.
+ */
+export const DEFAULT_RESTART_DRAIN_TIMEOUT_MS = 30_000;
+/**
+ * `restart()` on a gateway whose host gave it no way back. Exported so the
+ * control API can answer it as "not supported here" rather than as a
+ * failure of the daemon.
+ */
+export class RestartUnsupportedError extends Error {
+    constructor() {
+        super('This daemon cannot restart itself: the host that started it did not say how. '
+            + 'Restart it from the service manager (stratus service stop, then start) or from the terminal it runs in.');
+        this.name = 'RestartUnsupportedError';
+    }
+}
 /**
  * Recorded on a turn the previous process was still running when it died.
  *
@@ -231,6 +252,51 @@ export { applySoulPins } from '@stratusagent/state';
  * 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.';
+/**
+ * Recorded on a delegated sub-session that was parked on a human when the
+ * previous process died.
+ *
+ * Its parent — the turn whose `agent.delegate` call was awaiting the reply
+ * — was running, so the restart fails it as abandoned (above). Recovering
+ * the child anyway would re-ask a person to approve a call whose result no
+ * turn will ever read, and then run it: a command executed, tokens spent,
+ * and a reply delivered to nobody. Distinguishable from the parent's error
+ * because the remedy differs — there is no message to send again here;
+ * the parent's is the one to repeat.
+ */
+/**
+ * Session metadata keys the daemon writes for itself, which no external
+ * dispatch may supply.
+ *
+ * Metadata is one bag: the keys a channel attaches to say where a turn is
+ * happening sit beside the ones the kernel, the scheduler, the fallback
+ * wrapper, and `agent.delegate` write to remember what a session *is* —
+ * and the control API forwards a caller's `metadata` into a new session as
+ * given. A caller who can write `delegatedBy` can have the restart sweep
+ * fail its own parked turn as an orphan; one who can write `fallbackActive`
+ * bills its conversation to the fallback model from the first turn. The
+ * scheduler already refused to trust its own keys for exactly this reason
+ * (see `activeFirings`); the durable ones cannot be re-derived in memory,
+ * so they are refused at the door instead.
+ */
+export const RESERVED_SESSION_METADATA_KEYS = [
+    PENDING_APPROVAL_METADATA_KEY,
+    FALLBACK_ACTIVE_METADATA_KEY,
+    DELEGATED_BY_METADATA_KEY,
+    ROOT_SESSION_ID_METADATA_KEY,
+    DELEGATION_DEPTH_METADATA_KEY,
+    SCHEDULED_TURN_METADATA_KEY,
+    SCHEDULE_ID_METADATA_KEY,
+];
+/**
+ * The first reserved key `metadata` carries, or undefined when it carries
+ * none. Exported so the control API can refuse the request where the
+ * caller can see it, with the same rule the gateway applies at dispatch.
+ */
+export const reservedSessionMetadataKey = (metadata) => metadata === undefined
+    ? undefined
+    : RESERVED_SESSION_METADATA_KEYS.find((key) => Object.prototype.hasOwnProperty.call(metadata, key));
+export const ORPHANED_DELEGATION_ERROR = 'stratusd stopped while the turn that delegated this one was still running; the delegation was not resumed. Send the original 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
@@ -414,6 +480,8 @@ export const createGateway = (options = {}) => {
                 agentId: request.session.agent.id,
                 call: request.call,
                 risk: request.risk,
+                ...(request.origin !== undefined ? { origin: request.origin } : {}),
+                ...(request.oneShot ? { oneShot: true } : {}),
                 parkedAt: request.parkedAt ?? new Date().toISOString(),
                 ...(expiresAt ? { expiresAt } : {}),
                 ...(request.session.metadata ? { metadata: request.session.metadata } : {}),
@@ -459,6 +527,8 @@ export const createGateway = (options = {}) => {
             requestId,
             call: request.call,
             risk: request.risk,
+            ...(request.origin !== undefined ? { origin: request.origin } : {}),
+            ...(request.oneShot ? { oneShot: true } : {}),
             ...(request.session.metadata ? { metadata: request.session.metadata } : {}),
             ...(expiresAt ? { expiresAt } : {}),
         });
@@ -686,22 +756,73 @@ export const createGateway = (options = {}) => {
         }
     };
     /**
-     * Roster rebuilds, one at a time.
+     * Rebuild the skill catalog from what is on disk right now, into a fresh
+     * registry, and swap it in whole. See `Gateway.reloadSkills`.
+     *
+     * Strict on the operator directory: the previous set is still serving,
+     * so a file that will not load is a reason to keep it, not to serve the
+     * rest. The plugins' skills are re-registered from the load records, in
+     * load order, after the operator's — the order `start()` used, which is
+     * what makes an operator's bare id win its alias and a bare id two
+     * plugins want stay contested. Nothing is imported again: a plugin is
+     * code, and code gets a restart.
+     */
+    const loadSkills = async () => {
+        const next = new SkillRegistry();
+        const operator = await loadOperatorSkills(env, next, warn, { strict: true });
+        for (const plugin of loadedPlugins) {
+            for (const record of plugin.skills) {
+                // The live catalog holds the very `Skill` the loader staged, under
+                // its canonical id; a rebuild re-registers that object rather than
+                // re-reading the plugin's file, so a plugin's skills are exactly
+                // what loaded with it until it is loaded again.
+                const skill = skillCatalog.resolve(record.id);
+                if (!skill) {
+                    throw new Error(`Plugin ${plugin.package} lists skill ${record.id}, but the catalog no longer holds it. Restart the daemon.`);
+                }
+                next.register(skill);
+                next.registerAlias(record.bareId, skill.id);
+            }
+        }
+        const before = new Set(operatorSkills.map((skill) => skill.id));
+        const after = new Set(operator.map((skill) => skill.id));
+        skillCatalog.replaceWith(next);
+        operatorSkills = operator;
+        const added = operator.filter((skill) => !before.has(skill.id)).map((skill) => skill.id);
+        const removed = [...before].filter((id) => !after.has(id));
+        const change = [
+            ...(added.length > 0 ? [`added ${added.join(', ')}`] : []),
+            ...(removed.length > 0 ? [`removed ${removed.join(', ')}`] : []),
+        ];
+        log(`skills reloaded — ${skillCatalog.list().length} skill(s)${change.length > 0 ? `: ${change.join('; ')}` : ' (no change)'}`);
+        // The same advisory check the roster load runs: a removed skill an
+        // agent still lists, or a new one whose `requires:` the agent's tools
+        // do not cover, is worth a line now rather than at the next restart.
+        for (const agent of registry.list()) {
+            for (const { skill, missing } of missingSkillRequirements(agent, skillCatalog)) {
+                warn(`agent ${agent.id} enables skill ${skill.id}, which expects tools the agent is not allowed: ${missing.join(', ')}`);
+            }
+        }
+    };
+    /**
+     * Roster and skill 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.
+     * 201 for an agent that is no longer dispatchable. Skill reloads share the
+     * chain: each is a whole-catalog swap, and the roster load reads the
+     * catalog for its advisory warnings.
      *
      * 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);
+    const reloadsInOrder = async (work) => {
+        const next = reloads.then(work, work);
         // 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);
@@ -891,13 +1012,30 @@ export const createGateway = (options = {}) => {
     const withWatchdog = async (sessionId, external, idleEnabled, fallbackStreams, run) => {
         const effectiveIdleMs = idleEnabled || fallbackStreams ? idleTimeoutMs : 0;
         if (effectiveIdleMs <= 0 && !external) {
-            return run(new AbortController().signal);
+            // No watchdog and nobody outside to cancel it — but still a turn an
+            // announced restart must be able to cut short at the window.
+            const idle = new AbortController();
+            turnControllers.add(idle);
+            if (abortingTurns) {
+                idle.abort(new RunAbortedError(RESTARTING_TURN_ERROR));
+            }
+            try {
+                return await run(idle.signal);
+            }
+            finally {
+                turnControllers.delete(idle);
+            }
         }
         const controller = new AbortController();
-        let timedOut = false;
-        const onExternalAbort = () => controller.abort();
+        turnControllers.add(controller);
+        if (abortingTurns) {
+            controller.abort(new RunAbortedError(RESTARTING_TURN_ERROR));
+        }
+        // The external reason travels: a caller that aborted with its own
+        // `RunAbortedError` gets it recorded on the session, like the watchdog's.
+        const onExternalAbort = () => controller.abort(external?.reason);
         if (external?.aborted) {
-            controller.abort();
+            controller.abort(external.reason);
         }
         else {
             external?.addEventListener('abort', onExternalAbort, { once: true });
@@ -936,9 +1074,14 @@ export const createGateway = (options = {}) => {
             // Deliberately not unref'd: while a provider await is in flight, this
             // timer is what guarantees the process can always make progress on it.
             timer = setTimeout(() => {
-                timedOut = true;
                 warn(`watchdog: no activity on session ${sessionId} for ${effectiveIdleMs}ms; aborting the turn`);
-                controller.abort();
+                // The reason rides on the signal, because the runner is what fails
+                // the session: it writes `lastError` and emits `session.failed`
+                // before this wrapper ever sees the rejection. Rethrowing a better
+                // message from here reached the dispatcher and nobody else — the
+                // record and the event both said "Run aborted", which is also what
+                // a person cancelling looks like.
+                controller.abort(new RunAbortedError(`Run aborted: no activity for ${effectiveIdleMs}ms`));
             }, effectiveIdleMs);
         };
         // Two subscriptions bracket every event's fan-out. The PREPENDED
@@ -1019,17 +1162,12 @@ export const createGateway = (options = {}) => {
         try {
             return await run(controller.signal);
         }
-        catch (error) {
-            if (timedOut && error instanceof RunAbortedError) {
-                throw new RunAbortedError(`Run aborted: no activity for ${effectiveIdleMs}ms`);
-            }
-            throw error;
-        }
         finally {
             suspendTimer();
             unsubscribeObserver();
             unsubscribeDrain();
             suspendWatchdog.delete(sessionId);
+            turnControllers.delete(controller);
             external?.removeEventListener('abort', onExternalAbort);
         }
     };
@@ -1040,6 +1178,37 @@ export const createGateway = (options = {}) => {
     const sessionChains = new Map();
     const inflight = new Set();
     let stopping = false;
+    /**
+     * The abort handle of every turn running right now. A restart's drain
+     * window ends by aborting these — the same signal the watchdog fires —
+     * so a turn that outlives the window fails as aborted, its session
+     * saved, instead of being cut off by a process exit and found as
+     * abandoned by the next one.
+     */
+    const turnControllers = new Set();
+    /**
+     * Set once a restart's window has closed and the turns in it were
+     * aborted. A turn that starts after that — one queued behind the
+     * aborted turn on the same session, accepted before the announcement —
+     * is aborted the moment it gets its controller, with the same reason,
+     * rather than running unseen until the shutdown closes the store under
+     * it and leaves it recorded as nothing at all.
+     */
+    let abortingTurns = false;
+    /**
+     * Set once `start()` has finished. A restart before that would stop the
+     * channels started so far and close the stores while the rest of
+     * startup is still running — reachable, since the control API can be
+     * up and answering `POST /restart` while a later channel is still
+     * connecting — and the startup then fails on a closed store instead of
+     * the daemon coming back.
+     */
+    let serving = false;
+    /** Set once `restart()` announced; the refusal a caller reads says why. */
+    let restartStatus;
+    const refusal = () => new Error(restartStatus
+        ? 'stratusd is restarting and will accept new work once it is back up.'
+        : 'The gateway is stopping and no longer accepts new work.');
     /**
      * The turn id running on each session, for callers that named one.
      *
@@ -1126,7 +1295,7 @@ export const createGateway = (options = {}) => {
         // 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();
+            throw abortErrorFor(input.signal);
         }
         // A session pins its agent: when the caller names none, an existing
         // conversation keeps the agent it was created with even if the
@@ -1161,12 +1330,20 @@ export const createGateway = (options = {}) => {
             // Recheck before the runner touches durable state, or a dispatch
             // cancelled mid-preflight would still persist its user message.
             if (signal.aborted) {
-                throw new RunAbortedError();
+                throw abortErrorFor(signal);
             }
             if (existing) {
                 // Refresh the stored definition before resuming, so the turn runs
                 // with the current instructions, tools, and credentials.
                 existing.agent = agent;
+                // A sub-session reached here is being continued from outside — a
+                // delegation never resumes its own child; its ids are minted once.
+                // The delegating turn is over, so the markers come off: what is
+                // now an ordinary conversation must not be closed as an orphan if
+                // a later turn of it parks and the daemon dies.
+                if (isDelegatedSession(existing) && existing.metadata) {
+                    existing.metadata = withoutDelegation(existing.metadata);
+                }
                 await store.save(existing);
                 return runner.resume({ sessionId: input.sessionId, userMessage: input.userMessage, signal });
             }
@@ -1192,7 +1369,7 @@ export const createGateway = (options = {}) => {
      * one unrecoverable turn must not stop the daemon from serving, or from
      * recovering the others.
      */
-    const recoverParkedTurns = async () => {
+    const recoverParkedTurns = async (orphaned) => {
         if (!store.listIdsByStatus) {
             return;
         }
@@ -1207,9 +1384,56 @@ export const createGateway = (options = {}) => {
         // 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)));
+        await Promise.allSettled(parked.map((sessionId) => recoverOne(sessionId, orphaned.has(sessionId))));
+    };
+    /**
+     * The parked sub-sessions whose delegating turn the last process was
+     * still inside — read BEFORE the channels start, for the same reason the
+     * abandoned list is.
+     *
+     * The proof is the parent's transcript: only the runner writes an
+     * assistant `agent.delegate` call, and only a delegation in flight leaves
+     * one with no result behind it. That evidence does not survive contact
+     * with a channel, though — a message for the parent arriving once the
+     * adapters are up resumes it, and the resume closes the dangling call as
+     * interrupted. Read live from the sweep, the parent would then look as if
+     * it awaited nothing and the child would be re-asked after all, which is
+     * the bug this exists to stop. So it is read while nothing can dispatch,
+     * and the sweep judges from the snapshot; a child whose parent is missing
+     * or not inside such a call is left to ordinary recovery.
+     *
+     * Matched call by call, not parent by parent: the call that awaits a
+     * child names it (see `outstandingDelegationFor`), and a call can await
+     * only one. Two parked children claiming the same call — one of them a
+     * sub-session continued from outside under a version that kept its
+     * markers, parked again on something of its own — is an ambiguity this
+     * cannot settle, and both are left to ordinary recovery rather than one
+     * of them being failed for a delegation that was never its.
+     */
+    const listOrphanedDelegations = async () => {
+        const claimants = new Map();
+        if (!store.listIdsByStatus) {
+            return new Set();
+        }
+        for (const sessionId of await store.listIdsByStatus('pending_approval')) {
+            const parentId = delegatingSessionIdOf(sessionId);
+            if (parentId === undefined) {
+                continue;
+            }
+            const session = await store.get(sessionId);
+            if (!session || !isDelegatedSession(session)) {
+                continue;
+            }
+            const parent = await store.get(parentId);
+            const callId = parent ? outstandingDelegationFor(parent, session) : undefined;
+            if (callId !== undefined) {
+                const key = `${parentId}\u0000${callId}`;
+                claimants.set(key, [...(claimants.get(key) ?? []), sessionId]);
+            }
+        }
+        return new Set([...claimants.values()].filter((ids) => ids.length === 1).map(([id]) => id));
     };
-    const recoverOne = (sessionId) => onSessionChain(sessionId, async () => {
+    const recoverOne = (sessionId, orphaned) => onSessionChain(sessionId, async () => {
         if (stopping) {
             return;
         }
@@ -1219,6 +1443,27 @@ export const createGateway = (options = {}) => {
                 return;
             }
             const record = readPendingApproval(session);
+            // A delegated sub-session is only ever awaited by its parent's
+            // `agent.delegate` call, and that parent was running when the last
+            // process died — it is in the abandoned sweep, not in this one.
+            // Nothing will read the reply, so the parked call is not re-asked:
+            // a person would be approving a command that runs for no one.
+            //
+            // Judged on the re-read, on the chain: the channels are up before
+            // this sweep starts, so a message for this id can have taken the
+            // chain first and moved the session on — and a turn that finished
+            // normally must not be rewritten as failed. The delegation metadata
+            // is durable, so it proves what the session is, not what state it
+            // is in; the status and the checkpoint say that.
+            //
+            // Whether it IS an orphan was decided before the channels started
+            // (`listOrphanedDelegations`), from the parent's transcript, which
+            // a message arriving since may already have rewritten.
+            if (orphaned && isDelegatedSession(session) && session.status === 'pending_approval' && record) {
+                log(`${sessionId}: parked on ${record.call.toolName} for a delegating turn the last stratusd was still running; failing it`);
+                await failOrphanedDelegation(session);
+                return;
+            }
             // 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
@@ -1248,12 +1493,51 @@ export const createGateway = (options = {}) => {
             session.agent = source.definition;
             await store.save(session);
             const runner = runnerFor(await runtimeForAgent(source));
-            await runner.recoverPendingApproval(sessionId, { denyPending: expired });
+            // Tracked like a dispatched turn's controller: a recovered turn
+            // that runs on past its approval is a turn like any other, and a
+            // restart's window has to be able to cut it short with the same
+            // reason — or it runs unseen to the second window and the restart
+            // reports undrained for a turn it could have finished cleanly.
+            const controller = new AbortController();
+            turnControllers.add(controller);
+            if (abortingTurns) {
+                controller.abort(new RunAbortedError(RESTARTING_TURN_ERROR));
+            }
+            try {
+                await runner.recoverPendingApproval(sessionId, { denyPending: expired, signal: controller.signal });
+            }
+            finally {
+                turnControllers.delete(controller);
+                // A recovered firing's row outlived the process that would have
+                // retired it, and the firing is over either way — a recovery that
+                // failed has durably failed its session, which is as finished as
+                // completing. The scheduler decides whether there is a row to
+                // retire, and only this firing's own.
+                const scheduleId = session.metadata?.[SCHEDULE_ID_METADATA_KEY];
+                if (typeof scheduleId === 'string') {
+                    scheduler.retireSpentOneShot(scheduleId, sessionId);
+                }
+            }
         }
         catch (error) {
             warn(`could not recover parked session ${sessionId}: ${error instanceof Error ? error.message : String(error)}`);
         }
     });
+    /**
+     * Closes an orphaned sub-session the way the abandoned sweep closes its
+     * parent: durably failed, with the checkpoint retired so no later sweep
+     * can find a call to re-enter, and announced where surfaces can hear it.
+     */
+    const failOrphanedDelegation = async (session) => {
+        const metadata = { ...(session.metadata ?? {}) };
+        delete metadata[PENDING_APPROVAL_METADATA_KEY];
+        session.metadata = metadata;
+        session.status = 'failed';
+        session.lastError = ORPHANED_DELEGATION_ERROR;
+        await store.save(session);
+        await bus.emit({ type: 'session.updated', sessionId: session.id, status: 'failed' });
+        await bus.emit({ type: 'session.failed', sessionId: session.id, error: ORPHANED_DELEGATION_ERROR });
+    };
     /**
      * Turns the last process was still running when it stopped being able to
      * finish them.
@@ -1371,13 +1655,13 @@ export const createGateway = (options = {}) => {
      */
     const dispatchScheduledFiring = (input) => {
         if (stopping) {
-            throw new Error('The gateway is stopping and no longer accepts new work.');
+            throw refusal();
         }
         return onSessionChain(input.sessionId, () => dispatchInternal(input));
     };
     const dispatch = async (input) => {
         if (stopping) {
-            throw new Error('The gateway is stopping and no longer accepts new work.');
+            throw refusal();
         }
         // The reserved namespace is the scheduler's alone. A caller that could
         // name a firing's session id — derivable from `GET /schedules` — would
@@ -1388,6 +1672,13 @@ export const createGateway = (options = {}) => {
         if (isScheduleSessionId(input.sessionId)) {
             throw new Error(`Session ids beginning with "${SCHEDULE_SESSION_ID_PREFIX}" are reserved for scheduled firings and cannot be dispatched externally.`);
         }
+        // The daemon's own bookkeeping keys, by the same logic as the reserved
+        // id namespace above: what the runner, the scheduler, and delegation
+        // record about a session must be something only they can have written.
+        const reserved = reservedSessionMetadataKey(input.metadata);
+        if (reserved !== undefined) {
+            throw new Error(`Session metadata key "${reserved}" is reserved for the daemon's own records and cannot be supplied by a dispatch. Reserved keys: ${RESERVED_SESSION_METADATA_KEYS.join(', ')}.`);
+        }
         const { turnId } = input;
         if (turnId === undefined) {
             return onSessionChain(input.sessionId, () => dispatchInternal(input));
@@ -1429,7 +1720,16 @@ export const createGateway = (options = {}) => {
             tools,
             skills: skillCatalog,
             bus,
+            // The file-backed resolver, so a plugin needing a key reaches the
+            // *calling* agent's — its allowlist checked, its own entry before the
+            // fleet's shared one.
+            credentials: createFileCredentialResolver(env),
             workspaceRoot: workspacesDirPath(env),
+            // The structured log, so a plugin's lifecycle lines — an MCP server
+            // that dropped, a reconnect that failed — are in `stratus logs` and
+            // not only on a stderr the service manager owns.
+            log,
+            warn,
         });
         loadedPlugins = result.loaded;
         pluginFailures = result.failures;
@@ -1470,6 +1770,10 @@ export const createGateway = (options = {}) => {
         // Applied further down, once there is somewhere for the failure to
         // be heard.
         const abandoned = await listAbandonedTurns();
+        // Likewise: which parked sub-sessions have a parent still inside its
+        // agent.delegate call is only answerable while nothing can resume that
+        // parent. See listOrphanedDelegations.
+        const orphaned = await listOrphanedDelegations();
         // 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.
@@ -1479,7 +1783,10 @@ export const createGateway = (options = {}) => {
                 startedChannels.push(adapter);
             }
             catch (error) {
-                warn(`channel ${adapter.name} failed to start: ${error instanceof Error ? error.message : String(error)}`);
+                const reason = error instanceof Error ? error.message : String(error);
+                if (!adapter.required) {
+                    warn(`channel ${adapter.name} failed to start: ${reason}`);
+                }
                 // A start() that rejected may still hold sockets or listeners it
                 // acquired before failing; it never reaches startedChannels, so
                 // this is its only cleanup.
@@ -1489,6 +1796,17 @@ export const createGateway = (options = {}) => {
                 catch (stopError) {
                     warn(`channel ${adapter.name} cleanup after failed start also failed: ${stopError instanceof Error ? stopError.message : String(stopError)}`);
                 }
+                if (adapter.required) {
+                    // Before the scheduler and the sweeps below, deliberately: a
+                    // daemon that is not going to serve must not fire a catch-up
+                    // slot or re-ask a parked approval on its way out. The channels
+                    // already up are left to the shutdown this throw becomes, which
+                    // denies what they parked and lets those denials reach them
+                    // BEFORE it stops them — stopped here, a channel that had parked
+                    // a gated turn in the window would never learn to retract its
+                    // buttons.
+                    throw new Error(`${adapter.name} could not start, and the gateway cannot serve without it: ${reason}`);
+                }
             }
         }
         // After the channels, so a catch-up firing has somewhere to report and
@@ -1500,7 +1818,7 @@ export const createGateway = (options = {}) => {
         // 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) => {
+        void recoverParkedTurns(orphaned).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
@@ -1510,100 +1828,295 @@ export const createGateway = (options = {}) => {
             warn(`failing abandoned turns failed: ${error instanceof Error ? error.message : String(error)}`);
         });
     };
-    /** Release what the plugins acquired, reporting rather than throwing. */
+    /**
+     * Both stores, once. Reached from `stop()` and from a `start()` that
+     * failed, and a host may call the one after the other; node:sqlite
+     * refuses a second close, so this remembers.
+     */
+    let storesClosed = false;
+    const closeStores = () => {
+        if (storesClosed) {
+            return;
+        }
+        storesClosed = true;
+        scheduleStore.close();
+        store.close();
+    };
+    /**
+     * Release what the plugins acquired, reporting rather than throwing.
+     * Resolves with whether every plugin let go: a dispose that rejected may
+     * still hold the browser or socket it was closing, which a restart has
+     * to know before it starts a daemon beside it.
+     */
     const disposePlugins = async () => {
+        let released = true;
         await Promise.allSettled(loadedPlugins.map(async (plugin) => {
             try {
                 await plugin.instance.dispose?.();
             }
             catch (error) {
+                released = false;
                 warn(`plugin ${plugin.package} failed to shut down: ${error instanceof Error ? error.message : String(error)}`);
             }
         }));
         loadedPlugins = [];
+        return released;
     };
     const startedChannels = [];
+    /** Resolves with `true` when `work` settles before `ms` elapse. */
+    const settlesWithin = (work, ms) => new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(false), ms);
+        void work.then(() => { clearTimeout(timer); resolve(true); }, () => { clearTimeout(timer); resolve(true); });
+    });
+    let stopped;
+    /**
+     * The one shutdown sequence — for a stop, for a restart, and for a
+     * start() that failed, whose caller never reaches stop().
+     *
+     * `abortAfterMs` is the difference: a stop waits for every in-flight
+     * turn however long it takes (the service manager's own timeout is the
+     * bound there), while a restart waits that long and then aborts what is
+     * still running, so the daemon can come back instead of waiting on one
+     * stuck turn. Resolves with whether everything finished — after an abort,
+     * a turn that still ignores its signal for a second window is shut down
+     * around, and the host is told so it can exit rather than start a new
+     * daemon beside it. Every wait after the window opens is bounded by it,
+     * the scheduler's own drain included: that drain tracks the same firing
+     * the turn drain gave up on, and an unbounded wait there would hold the
+     * restart forever on exactly the turn the window exists for.
+     */
+    const shutdown = async (abortAfterMs) => {
+        // Refuse new work first; then let channels finish rendering their
+        // in-flight turns (already-started dispatches keep running), drain,
+        // and close.
+        stopping = true;
+        // No new firings from here: the tick stops before anything drains,
+        // so the drain below is over a set that can only shrink. A tick
+        // already past its `stopping` check loses to `dispatch`'s own
+        // refusal — the second gate is why this needs no handshake.
+        scheduler.stop();
+        // 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');
+        }
+        // Everything a restart's window has to cover, in the order a stop
+        // does it. The approval 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; the channels' stop awaits
+        // the rendering they have in flight, which is a running turn's output.
+        // All three inside the window: a subscriber or a channel stalled on a
+        // stuck turn would otherwise hold the restart outside it.
+        // A channel whose stop rejected may still hold its connection — and a
+        // replacement daemon opening another would be two of them answering
+        // the same messages. Reported, and for a restart, counted as not
+        // drained; a plain stop goes on closing either way.
+        let channelsReleased = true;
+        const drain = (async () => {
+            await Promise.allSettled([...approvalEmissions]);
+            const stopping = [...startedChannels];
+            const stops = await Promise.allSettled(stopping.map((adapter) => adapter.stop()));
+            stops.forEach((result, index) => {
+                if (result.status === 'rejected') {
+                    channelsReleased = false;
+                    warn(`channel ${stopping[index]?.name} failed to stop: ${result.reason instanceof Error ? result.reason.message : String(result.reason)}`);
+                }
+            });
+            startedChannels.length = 0;
+            await Promise.allSettled([...inflight]);
+        })();
+        let drained = true;
+        if (abortAfterMs === undefined) {
+            await drain;
+        }
+        else if (await settlesWithin(drain, abortAfterMs)) {
+            drained = channelsReleased;
+        }
+        else {
+            warn(`restart: ${inflight.size} turn(s) still running after ${abortAfterMs}ms; aborting them`);
+            // The watchdog's own mechanism: the runner fails each session with
+            // the reason on the signal, saves it, and emits session.failed —
+            // so the next daemon finds a finished turn, not an abandoned one.
+            // Before the loop, so a turn queued behind one aborted here, which
+            // starts as soon as that one settles, is aborted the same way.
+            abortingTurns = true;
+            for (const controller of turnControllers) {
+                controller.abort(new RunAbortedError(RESTARTING_TURN_ERROR));
+            }
+            drained = await settlesWithin(drain, abortAfterMs);
+            if (!drained) {
+                warn(`restart: ${inflight.size} turn(s) did not stop after being aborted; shutting down around them`);
+            }
+            drained = drained && channelsReleased;
+        }
+        // After the turn drain: a firing's wrapper settles after its
+        // dispatch does (it retires spent one-shots), so this is the last
+        // writer of the schedule table. Bounded once the turn drain has given
+        // up: the wrapper it would wait for is around the very turn that
+        // ignored its abort.
+        const schedulerDrain = scheduler.drain();
+        if (drained || abortAfterMs === undefined) {
+            await schedulerDrain;
+        }
+        else if (!(await settlesWithin(schedulerDrain, abortAfterMs))) {
+            warn('restart: a scheduled firing did not stop after being aborted; shutting down around it');
+        }
+        // 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. Bounded
+        // for a restart, whose likeliest reason is a plugin that misbehaves:
+        // a dispose that never settles must not be what keeps the daemon from
+        // coming back, and a plugin still holding on is one more thing the
+        // host should not start a new daemon beside.
+        const disposal = disposePlugins();
+        if (abortAfterMs === undefined) {
+            await disposal;
+        }
+        else if (await settlesWithin(disposal, abortAfterMs)) {
+            // A dispose that rejected has already been named; what it may still
+            // hold is the same problem as one that never answered.
+            drained = drained && await disposal;
+        }
+        else {
+            warn(`restart: a plugin did not release what it holds within ${abortAfterMs}ms; shutting down around it`);
+            drained = false;
+        }
+        closeStores();
+        log('stratusd stopped');
+        return drained;
+    };
     const gateway = {
         bus,
         store,
         async start() {
-            await migrateLegacyMemory(env);
-            // 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.
-            // Skills first for the same reason — and before the plugins, so the
-            // operator's bare ids win their aliases (see startSkills).
-            await startSkills();
-            await startPlugins();
             try {
+                await migrateLegacyMemory(env);
+                // 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. Skills first for the same reason — and before
+                // the plugins, so the operator's bare ids win their aliases (see
+                // startSkills).
+                await startSkills();
+                await startPlugins();
                 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();
+                // A `start()` that rejects never reaches its caller's shutdown path
+                // — `stratus serve` awaits it *before* the try/finally that calls
+                // `stop()` — so it is the shutdown, in full: a duplicate agent id
+                // in the roster would otherwise leave a plugin's browser, socket,
+                // or subscription held for the life of a process that is on its
+                // way out; the two stores opened before any of this ran would keep
+                // their descriptors, four more per attempt in a host that retries
+                // a port it cannot bind; and a turn a channel that did come up had
+                // already accepted must finish and save before the store it saves
+                // to is closed, exactly as it would under a stop().
+                await shutdown(undefined);
                 throw error;
             }
+            serving = true;
         },
         // Drain: channels stop taking messages, in-flight turns finish, new
         // dispatches are refused, then the database closes. SIGTERM handling
-        // in `stratus serve` calls this.
-        async stop() {
-            // Refuse new work first; then let channels finish rendering their
-            // in-flight turns (already-started dispatches keep running), drain,
-            // and close.
-            stopping = true;
-            // No new firings from here: the tick stops before anything drains,
-            // so the drain below is over a set that can only shrink. A tick
-            // already past its `stopping` check loses to `dispatch`'s own
-            // refusal — the second gate is why this needs no handshake.
-            scheduler.stop();
-            // 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 turn drain: a firing's wrapper settles after its
-            // dispatch does (it retires spent one-shots), so this is the last
-            // writer of the schedule table.
-            await scheduler.drain();
-            // 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();
-            scheduleStore.close();
-            store.close();
-            log('stratusd stopped');
+        // in `stratus serve` calls this. Idempotent: a restart stops the
+        // gateway itself before handing the process to the host, whose own
+        // shutdown path then calls this again and must find nothing to do —
+        // and a start() that failed has already run the same sequence.
+        stop() {
+            stopped ??= shutdown(undefined).then(() => undefined);
+            return stopped;
         },
         dispatch,
         async sessionRouting(sessionId) {
             const session = await store.get(sessionId);
-            return session
-                ? { agentId: session.agent.id, metadata: session.metadata ?? {} }
-                : undefined;
+            if (!session) {
+                return undefined;
+            }
+            // The reply, not the record: a channel that finishes a turn it did
+            // not start needs the one message to post, and the transcript stays
+            // the session's own. The latest turn's text only — a turn that
+            // produced none has no reply, and an earlier turn's answer is not it.
+            const reply = latestTurnReply(session);
+            return {
+                agentId: session.agent.id,
+                metadata: session.metadata ?? {},
+                ...(reply !== undefined ? { reply } : {}),
+            };
         },
         agents() {
             return registry.list();
         },
         async reloadRoster() {
-            await reloadsInOrder();
+            await reloadsInOrder(loadRoster);
             const roster = registry.list();
             log(`roster reloaded — ${roster.length} agent(s): ${roster.map((agent) => agent.name).join(', ')}`);
             return roster;
         },
+        async reloadSkills() {
+            try {
+                await reloadsInOrder(loadSkills);
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                warn(`skills reload refused — ${reason}; the previously loaded skills are still serving`);
+                throw new Error(`Skills were not reloaded: ${reason} The previously loaded skills are still serving; fix the file and reload again.`);
+            }
+            return gateway.skills();
+        },
+        restart(request = {}) {
+            if (!options.onRestart) {
+                throw new RestartUnsupportedError();
+            }
+            if (restartStatus) {
+                return restartStatus;
+            }
+            if (stopping) {
+                throw new Error('The gateway is already stopping, and a stop does not come back on its own.');
+            }
+            if (!serving) {
+                throw new Error('stratusd is still starting; ask for a restart again once it is serving.');
+            }
+            const requested = request.drainTimeoutMs ?? options.restartDrainTimeoutMs ?? DEFAULT_RESTART_DRAIN_TIMEOUT_MS;
+            // Checked here and not only at the HTTP route: a host calling this
+            // directly with a negative or NaN window would get a timer that
+            // fires at once, aborting every turn it meant to let finish. Refused
+            // before anything is announced, so a bad argument is not a restart.
+            if (!Number.isFinite(requested) || requested < 0) {
+                throw new Error(`The restart drain window must be a non-negative number of milliseconds, not ${String(requested)}.`);
+            }
+            // Above Node's maximum timer delay a setTimeout fires at once, so a
+            // window asked for as "very long" would abort every turn immediately
+            // — the same clamp the approval timeout gets, for the same reason.
+            const drainTimeoutMs = Math.min(requested, MAX_TIMER_DELAY_MS);
+            if (requested > MAX_TIMER_DELAY_MS) {
+                warn(`restart drain window ${requested}ms is above Node's maximum timer delay; using ${MAX_TIMER_DELAY_MS}ms (~24.8 days)`);
+            }
+            const status = {
+                ...(request.reason !== undefined ? { reason: request.reason } : {}),
+                drainTimeoutMs,
+                inflight: inflight.size,
+            };
+            restartStatus = status;
+            // Said now, while stdout and the structured log both still work: a
+            // process on its way down is the one whose last lines matter, and
+            // the one least able to write them.
+            log(`restart requested${status.reason ? ` (${status.reason})` : ''} — refusing new turns; `
+                + `${status.inflight} turn(s) in flight, draining for up to ${drainTimeoutMs}ms`);
+            const onRestart = options.onRestart;
+            const draining = shutdown(drainTimeoutMs);
+            // The host's own shutdown path calls stop() next; it must find this
+            // one rather than start a second.
+            stopped = draining.then(() => undefined);
+            void draining
+                .then((drained) => onRestart({ ...(status.reason !== undefined ? { reason: status.reason } : {}), drained }))
+                .catch((error) => {
+                warn(`restart failed: ${error instanceof Error ? error.message : String(error)}`);
+            });
+            return status;
+        },
         activeTurnId(sessionId) {
             return activeTurns.get(sessionId);
         },