@stratusagent/gateway 0.11.6 → 0.11.8

package/dist/index.js

@@ -7,8 +7,8 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { createHash, randomUUID } from 'node:crypto';
-import { filePathsOf, isUnaddressedTurn, abortErrorFor, AgentRegistry, AgentRunner, ChannelRegistry, ContributionRegistry, createRoutedMemoryStore, EventBus, RunAbortedError, SkillRegistry, ToolRegistry, createSkillReadTool, missingSkillRequirements, describeToolAllowlistFinding, unmatchedToolAllowlist, CONTEXT_FLOOR_METADATA_KEY, PENDING_APPROVAL_METADATA_KEY, SESSION_TAINTED_BY_METADATA_KEY, SESSION_TRUST_METADATA_KEY, latestTurnReply, readPendingApproval, } from '@stratusagent/core';
-import { createDelegateTool, createForgetTool, createPinTool, 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 { filePathsOf, isUnaddressedTurn, workItemState, lastResponseIsAnswer, MAX_IDEMPOTENCY_KEY_LENGTH, recordTurnFailure, completeAnsweredTurn, abortErrorFor, AgentRegistry, AgentRunner, ChannelRegistry, ContributionRegistry, createRoutedMemoryStore, EventBus, RunAbortedError, SkillRegistry, ToolRegistry, createSkillReadTool, missingSkillRequirements, describeToolAllowlistFinding, unmatchedToolAllowlist, CONTEXT_FLOOR_METADATA_KEY, PENDING_APPROVAL_METADATA_KEY, SESSION_TAINTED_BY_METADATA_KEY, SESSION_TRUST_METADATA_KEY, latestTurnReply, readPendingApproval, conversationContextFrom, CONVERSATION_METADATA_KEY, STRATUS_SKILL_ID, } from '@stratusagent/core';
+import { createCredentialRequestTool, createDelegateTool, createForgetTool, createPinTool, 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, loadStratusSkill, STRATUS_SKILL_PATH, } from '@stratusagent/agents';
 import { createSchedulerRuntime, isScheduleSessionId, SqliteScheduleStore, SCHEDULE_SESSION_ID_PREFIX, } from "./schedules.js";
 import { ShardedSessionStore } from "./sessions.js";
 export { claimHome, homeLockPath, HomeClaimedError, } from "./lock.js";
@@ -16,7 +16,7 @@ export { SqliteSessionStore, ShardedSessionStore, FleetSessionIndex, SessionIdTa
 export { SqliteScheduleStore, createSchedulerRuntime, isScheduleSessionId, SCHEDULE_SESSION_ID_PREFIX, } from "./schedules.js";
 import { createLocalCommandExecutor } from '@stratusagent/executor-local';
 import { loadPlugins, } from '@stratusagent/plugins';
-import { BUILTIN_EXECUTOR_NAME, BUILTIN_MEMORY_STORE_NAME, BUILTIN_PROVIDER_NAMES, createDemoTool, createFileCredentialResolver, createHomeMemoryStore, drainSharedMemory, hasBracketedLegacyStateIn, createRuntimeProvider, DEFAULT_STRATUS_AGENT, isRegisteredProviderName, loadChannelTransportSecrets, registeredProviderNameOf, loadOperatorSkills, loadRosterSouls, FALLBACK_ACTIVE_METADATA_KEY, loadSoulFile, migrateLegacyMemory, PROVIDER_STATE_METADATA_KEYS, ConfigFileError, loadConfigFile, resolveConfigLocation, resolveConfiguredSoul, resolveRuntimeConfig, applySoulPins, assertStateCompatible, stratusHomePath, fleetDbIn, createAgentWorkspaces, foldedAgentId, } from '@stratusagent/state';
+import { BUILTIN_EXECUTOR_NAME, BUILTIN_MEMORY_STORE_NAME, BUILTIN_PROVIDER_NAMES, createDemoTool, createFileCredentialResolver, createHomeMemoryStore, drainSharedMemory, hasBracketedLegacyStateIn, createRuntimeProvider, describeServingModel, DEFAULT_STRATUS_AGENT, isRegisteredProviderName, loadChannelTransportSecrets, registeredProviderNameOf, loadOperatorSkills, loadRosterSouls, FALLBACK_ACTIVE_METADATA_KEY, loadSoulFile, grantSoulCredential, withSoulFileLock, addNamedCredential, namedCredentialSource, NamedCredentialExistsError, CREDENTIAL_NAME_PATTERN, quoteShellArg, migrateLegacyMemory, PROVIDER_STATE_METADATA_KEYS, ConfigFileError, loadConfigFile, resolveConfigLocation, resolveConfiguredSoul, resolveRuntimeConfig, runsOnHarness, applySoulPins, assertStateCompatible, stratusHomePath, fleetDbIn, createAgentWorkspaces, createPluginStateDirectories, foldedAgentId, } from '@stratusagent/state';
 const DEFAULT_IDLE_TIMEOUT_MS = 120_000;
 /**
  * How long a parked call waits for a person. Long enough to survive a
@@ -70,12 +70,17 @@ export class RestartUnsupportedError extends Error {
  * 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 longest `DispatchInput.idempotencyKey` accepted. A platform message id
+ * is far shorter; the bound is so a key cannot be used to grow every row it
+ * is stored on.
+ */
 /**
  * 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
+ * — was running, so the restart settles 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
@@ -106,6 +111,29 @@ export const ROLLED_OVER_FROM_METADATA_KEY = 'rolledOverFrom';
 export const ROLLED_OVER_TO_METADATA_KEY = 'rolledOverTo';
 /** The segment a rollover mints into the archived transcript's id. */
 export const ROLLED_OVER_SESSION_ID_MARKER = ':rolledover:';
+/**
+ * How long after a rollover a repeated key is still looked for in the
+ * archived transcript. A rollover moves every keyed message out of the
+ * live row, so a redelivery arriving after one would otherwise read as a
+ * new message and run again. Platforms redeliver within minutes — Slack
+ * gives up after about five — and past the window the archive is not
+ * loaded at all, since every new message to the fresh row would pay for a
+ * read that can no longer find anything.
+ */
+const ROLLOVER_REPEAT_WINDOW_MS = 60 * 60 * 1000;
+/**
+ * The one refusal for a dispatch naming an agent other than its session's.
+ * Its own type so a repeat attached to a claimant can tell the claimant was
+ * refused for who it named — the item then still has no owner — from the
+ * claimant's turn failing. Internal: callers read the message.
+ */
+class CrossIdentityError extends Error {
+    constructor(sessionId, owner, claimed) {
+        super(`Session ${sessionId} belongs to agent ${owner}, not ${claimed} — sessions never cross agent identities.`);
+        this.name = 'CrossIdentityError';
+    }
+}
+const crossIdentityError = (sessionId, owner, claimed) => new CrossIdentityError(sessionId, owner, claimed);
 /** Where the session's tool calls ran: `local-command`, or a contributed executor's registered name. */
 export const EXECUTOR_METADATA_KEY = 'executor';
 export const RESERVED_SESSION_METADATA_KEYS = [
@@ -191,26 +219,26 @@ export const createGateway = (options = {}) => {
     // schedule store's own connection (see its docs for why).
     const scheduleStore = new SqliteScheduleStore(fleetDbIn(stateDir), { stateHome: stateDir });
     /**
-     * The write side of an addressable destination, through whichever
-     * started channel serves its kind. Resolution happens per call against
-     * the live adapter list, so a channel that failed to start is honestly
-     * "cannot address" rather than a stale reference — and rejecting is how
-     * both callers (schedule creation, `message.send`) hear why.
+     * The started adapter of one kind that speaks for an agent and has the
+     * capability asked for. `carriesOthers` says there were capable adapters
+     * of that kind, just none carrying this agent, which callers word
+     * differently from there being none at all.
+     *
+     * One kind may be served by several adapters carrying disjoint
+     * agents — two plugins, or the host's adapter beside a plugin's — and
+     * the one that speaks for this agent is the one whose claims include
+     * it: a contribution's agent list, or the host's declared claims for
+     * an adapter no plugin contributed. A host that declared no claims for
+     * the kind left its adapter unclaimed, and an unclaimed adapter speaks
+     * for anyone, as the single host adapter always did. A claim miss is
+     * a refusal, never the first adapter that happens to be running: that
+     * adapter posts under another agent's transport identity, and it is
+     * exactly what a failed start of the right adapter would leave behind.
      */
-    const outboundFor = async (agentId, destination) => {
-        const candidates = startedChannels.filter((candidate) => candidate.name === destination.channel && candidate.resolveOutbound);
-        // One kind may be served by several adapters carrying disjoint
-        // agents — two plugins, or the host's adapter beside a plugin's — and
-        // the one that speaks for this agent is the one whose claims include
-        // it: a contribution's agent list, or the host's declared claims for
-        // an adapter no plugin contributed. A host that declared no claims for
-        // the kind left its adapter unclaimed, and an unclaimed adapter speaks
-        // for anyone, as the single host adapter always did. A claim miss is
-        // a refusal, never the first adapter that happens to be running: that
-        // adapter posts under another agent's transport identity, and it is
-        // exactly what a failed start of the right adapter would leave behind.
+    const channelCarrying = (kind, agentId, capable) => {
+        const candidates = startedChannels.filter((candidate) => candidate.name === kind && capable(candidate));
         const contributed = channelContributions.list();
-        const hostClaims = (options.hostChannelClaims ?? []).filter((claim) => claim.kind === destination.channel);
+        const hostClaims = (options.hostChannelClaims ?? []).filter((claim) => claim.kind === kind);
         const carries = (candidate) => {
             const entry = contributed.find((contribution) => contribution.adapter === candidate);
             if (entry) {
@@ -219,7 +247,18 @@ export const createGateway = (options = {}) => {
             return hostClaims.length === 0 || hostClaims.some((claim) => claim.agents.includes(agentId));
         };
         const adapter = candidates.find(carries);
-        if (!adapter?.resolveOutbound && candidates.length > 0) {
+        return adapter ? { adapter, carriesOthers: false } : { carriesOthers: candidates.length > 0 };
+    };
+    /**
+     * The write side of an addressable destination, through whichever
+     * started channel serves its kind. Resolution happens per call against
+     * the live adapter list, so a channel that failed to start is honestly
+     * "cannot address" rather than a stale reference — and rejecting is how
+     * both callers (schedule creation, `message.send`) hear why.
+     */
+    const outboundFor = async (agentId, destination) => {
+        const { adapter, carriesOthers } = channelCarrying(destination.channel, agentId, (candidate) => candidate.resolveOutbound !== undefined);
+        if (!adapter?.resolveOutbound && carriesOthers) {
             throw new Error(`No running '${destination.channel}' channel carries agent ${agentId} — `
                 + `the running ${destination.channel} adapters carry other agents, so a message from ${agentId} has no transport identity to post under.`);
         }
@@ -765,6 +804,7 @@ export const createGateway = (options = {}) => {
      */
     const loadSkills = async () => {
         const next = new SkillRegistry();
+        await registerBuiltinSkills(next, true);
         const operator = await loadOperatorSkills(env, next, warn, { strict: true });
         for (const plugin of loadedPlugins) {
             for (const record of plugin.skills) {
@@ -862,6 +902,36 @@ export const createGateway = (options = {}) => {
         }
         return source;
     };
+    const agentWorkspaces = createAgentWorkspaces(env);
+    /**
+     * What an agent is told about how it runs, from the source this dispatch
+     * refreshed and never from `sources` again. The persona the turn runs on
+     * came from that snapshot, and a repointed default soul can replace the
+     * registered source while the turn is still in preflight: read afresh,
+     * the agent would be told a file it is not running on is its soul.
+     *
+     * `soulReloads` is true because `refreshAgent` re-reads the file on every
+     * dispatch. A refresh that failed serves from cache and carries no path,
+     * so the agent is told nothing about a soul file for that turn rather
+     * than something the daemon could not just read. The built-in agent has
+     * no file, so it is told only where its workspace is.
+     *
+     * The language and the model come from the config this same dispatch
+     * resolved for that source, for the same reason: the turn runs on it.
+     */
+    const runtimeContextFor = (source, config, onFallback, 
+    // The turn's own metadata, where a channel records who can read the
+    // conversation now; a recovered turn has none and passes the session's.
+    metadata) => {
+        const conversation = conversationContextFrom(metadata);
+        return {
+            ...(source.soulPath !== undefined ? { soulPath: source.soulPath, soulReloads: true } : {}),
+            workspace: agentWorkspaces.forAgent(source.definition.id),
+            ...(config.language !== undefined ? { language: config.language } : {}),
+            model: describeServingModel(config, onFallback),
+            ...(conversation !== undefined ? { conversation } : {}),
+        };
+    };
     // ---- runner pool --------------------------------------------------------
     const tools = new ToolRegistry();
     // Which package each tool came from. Kernel tools are absent from this
@@ -883,6 +953,23 @@ export const createGateway = (options = {}) => {
     let pluginFailures = [];
     const skillCatalog = new SkillRegistry();
     let operatorSkills = [];
+    /**
+     * The skills that ship with Stratus, first into every catalog, so the id
+     * is theirs before an operator directory or a plugin can claim it. A file
+     * missing from a broken install is said once and costs the agents their
+     * reference, never the daemon its start.
+     */
+    const registerBuiltinSkills = async (registry, reloading = false) => {
+        try {
+            registry.register(await loadStratusSkill());
+        }
+        catch (error) {
+            // On a reload the swap keeps the copy already serving
+            // (`SkillRegistry.replaceWith`), so only a start goes without it.
+            const consequence = reloading ? 'the copy loaded at start keeps serving' : 'agents will not have it';
+            warn(`the built-in stratus skill did not load (${error instanceof Error ? error.message : String(error)}); ${consequence}. Reinstall Stratus.`);
+        }
+    };
     tools.register(createDemoTool());
     tools.register(createRememberTool(memory));
     tools.register(createRecallTool(memory));
@@ -910,6 +997,259 @@ export const createGateway = (options = {}) => {
         const connection = await outboundFor(agentId, destination);
         await connection.post(text);
     }));
+    /**
+     * Credential requests waiting on a person, by request id.
+     *
+     * In memory on purpose: a request is a question somebody is being asked
+     * now, and a restart that forgot it only means the agent asks again. What
+     * matters is that the entry carries everything the answer needs, so a
+     * channel quoting the id back decides nothing about where the key goes.
+     */
+    const credentialRequests = new Map();
+    tools.register(createCredentialRequestTool(async (request, session) => {
+        const agentId = session.agent.id;
+        const soulPath = sources.get(agentId)?.soulPath;
+        if (soulPath === undefined) {
+            throw new Error(`${session.agent.name} is the built-in agent and has no soul file to grant a credential in. `
+                + `Your operator can store one on the machine with \`stratus credential set ${request.name}\`.`);
+        }
+        if (!CREDENTIAL_NAME_PATTERN.test(request.name)) {
+            throw new Error(`${JSON.stringify(request.name)} is not a credential name. Use letters, digits, dots, dashes, or underscores, `
+                + 'starting with a letter, the way the tool that needs it spells it: search.apiKey, github.token.');
+        }
+        // A key already stored is not something to ask a person for again: the
+        // form only adds, so it could only fail. Say what is actually missing.
+        const source = await namedCredentialSource(env, agentId, request.name);
+        const stored = source !== undefined;
+        const granted = session.agent.credentials?.includes(request.name) === true;
+        if (stored && granted) {
+            throw new Error(`You already hold ${request.name}; the tools that need it use it for you. There is nothing to ask for.`);
+        }
+        if (stored) {
+            throw new Error(`${request.name} is already ${source === 'environment' ? "supplied by the daemon's environment" : 'stored'} but not granted to you. `
+                + 'Ask your operator to add it to the credentials list in your soul; a form would only refuse to store it again.');
+        }
+        const onMachine = `\`stratus credential set ${request.name}${request.scope === 'agent' ? ` --agent ${quoteShellArg(agentId)}` : ''}\``;
+        const record = { agentId, sessionId: session.id, name: request.name, scope: request.scope, soulPath };
+        const announce = async (requestId, via) => {
+            await bus.emit({
+                type: 'credential.requested',
+                sessionId: session.id,
+                agentId,
+                requestId,
+                name: request.name,
+                scope: request.scope,
+                ...(request.reason !== undefined ? { reason: request.reason } : {}),
+                via,
+                ...(session.metadata ? { metadata: session.metadata } : {}),
+            });
+        };
+        // Why no form went up, said to the agent beside the link that replaces
+        // it, so it can tell the person why they are getting a link instead.
+        let formUnavailable;
+        if (request.via !== 'link') {
+            // Only a conversation a channel started has anywhere to show a form,
+            // and only a channel that renders one can show it: a scheduled or
+            // HTTP turn, or a channel with no form, would record a request nobody
+            // sees while the agent tells its user the operator was asked.
+            const kind = session.metadata?.channel;
+            const { adapter } = typeof kind === 'string'
+                ? channelCarrying(kind, agentId, (candidate) => candidate.requestCredential !== undefined)
+                : { adapter: undefined };
+            if (!adapter?.requestCredential || !session.metadata) {
+                formUnavailable = typeof kind === 'string'
+                    ? `This conversation's channel (${kind}) cannot show your operator a credential form here.`
+                    : 'This conversation is not in a channel that can show your operator a form.';
+            }
+            else {
+                const requestId = randomUUID();
+                credentialRequests.set(requestId, record);
+                // Delivered before it is announced, and dropped if delivery fails: a
+                // request whose post never landed has no button to answer it, so
+                // keeping it would leave it pending for good behind a tool result
+                // saying the operator was asked.
+                try {
+                    await adapter.requestCredential({
+                        sessionId: session.id,
+                        agentId,
+                        requestId,
+                        name: request.name,
+                        scope: request.scope,
+                        ...(request.reason !== undefined ? { reason: request.reason } : {}),
+                        metadata: session.metadata,
+                    });
+                    await announce(requestId, 'form');
+                    return { requestId, via: 'form' };
+                }
+                catch (error) {
+                    credentialRequests.delete(requestId);
+                    formUnavailable = `The form could not be shown here: ${error instanceof Error ? error.message : String(error)}`;
+                }
+            }
+            if (request.via === 'form') {
+                throw new Error(`${formUnavailable} Nothing is pending. Ask for a link instead (via: "link"), or ask your operator to store ${request.name} on the machine with ${onMachine} and grant it to you.`);
+            }
+        }
+        // A link where no form can go, from whichever adapter issues them: the
+        // control API, which is not tied to any one agent's transport.
+        const linker = startedChannels.find((candidate) => candidate.requestCredentialLink !== undefined);
+        if (!linker?.requestCredentialLink) {
+            throw new Error(`${formUnavailable !== undefined ? `${formUnavailable} ` : ''}No control API is running to issue a link either. `
+                + `Ask your operator to store ${request.name} on the machine with ${onMachine} and grant it to you.`);
+        }
+        const requestId = randomUUID();
+        credentialRequests.set(requestId, record);
+        let link;
+        try {
+            link = await linker.requestCredentialLink({
+                sessionId: session.id,
+                agentId,
+                agentName: session.agent.name,
+                requestId,
+                name: request.name,
+                scope: request.scope,
+                ...(request.reason !== undefined ? { reason: request.reason } : {}),
+            });
+        }
+        catch (error) {
+            credentialRequests.delete(requestId);
+            throw new Error(`A link for ${request.name} could not be issued: ${error instanceof Error ? error.message : String(error)} `
+                + `Nothing is pending. Ask your operator to store it on the machine with ${onMachine}.`);
+        }
+        await announce(requestId, 'link');
+        return {
+            requestId,
+            via: 'link',
+            url: link.url,
+            expiresAt: link.expiresAt,
+            ...(link.localOnly === true ? { localOnly: true } : {}),
+            ...(formUnavailable !== undefined ? { formUnavailable } : {}),
+        };
+    }));
+    /**
+     * Requests an answer is being stored for now. Claimed before the first
+     * await: two approvers submitting one form at once would otherwise both
+     * start storing, and the second's add-only conflict would retire a
+     * request the first was about to settle as added.
+     */
+    const answering = new Set();
+    const provideCredential = async (input) => {
+        const request = credentialRequests.get(input.requestId);
+        if (!request) {
+            return { ok: false, retired: true, message: 'That credential request is no longer pending. Ask the agent to request it again.' };
+        }
+        if (answering.has(input.requestId)) {
+            return { ok: false, message: 'Someone else\'s answer to this request is being stored right now. Wait a moment before trying again.' };
+        }
+        answering.add(input.requestId);
+        try {
+            return await answerCredentialRequest(input, request);
+        }
+        finally {
+            answering.delete(input.requestId);
+        }
+    };
+    const answerCredentialRequest = async (input, request) => {
+        // The agent must still be served from the file the request captured: a
+        // repointed default soul (same id, another file) replaces the source,
+        // and a grant landing in the old file would report a key the agent now
+        // running cannot use.
+        const served = sources.get(request.agentId)?.soulPath;
+        if (served !== request.soulPath) {
+            credentialRequests.delete(input.requestId);
+            return {
+                ok: false,
+                retired: true,
+                message: `${request.agentId} is no longer served from ${request.soulPath}, so nothing was stored. Ask ${request.agentId} to request it again.`,
+            };
+        }
+        // The soul the grant will land in must still be the requester's, and is
+        // checked before anything is stored: a file reassigned to another agent
+        // while the request waited would otherwise receive a key nobody meant
+        // to give it. `grantSoulCredential` checks again as it writes.
+        let owner;
+        try {
+            owner = (await loadSoulFile(request.soulPath)).agent.id;
+        }
+        catch (error) {
+            return {
+                ok: false,
+                message: `${request.agentId}'s soul could not be read (${error instanceof Error ? error.message : String(error)}), so nothing was stored.`,
+            };
+        }
+        if (owner !== request.agentId) {
+            credentialRequests.delete(input.requestId);
+            return {
+                ok: false,
+                retired: true,
+                message: `${request.soulPath} now belongs to ${owner}, not ${request.agentId}, so nothing was stored. Ask ${request.agentId} to request it again.`,
+            };
+        }
+        try {
+            await addNamedCredential(env, {
+                name: request.name,
+                value: input.value,
+                ...(request.scope === 'agent' ? { agentId: request.agentId } : {}),
+            });
+        }
+        catch (error) {
+            // A name stored since the request was made (another form for the
+            // same shared key, or the machine) is final under add-only: no value
+            // typed into this form can ever land, so the request is retired
+            // rather than left answering every submission with the same refusal.
+            if (error instanceof NamedCredentialExistsError) {
+                credentialRequests.delete(input.requestId);
+                return { ok: false, retired: true, message: error.message };
+            }
+            // Otherwise refused, not failed: the request stays pending, so a
+            // person who typed an empty value can try again from the same form.
+            return { ok: false, message: error instanceof Error ? error.message : String(error) };
+        }
+        credentialRequests.delete(input.requestId);
+        // Stored first, granted second: a key nobody may use is recoverable by
+        // editing the soul, while a soul naming a key that was never stored
+        // fails every call that reaches for it. Announced either way, because
+        // the store already changed and a shared key is already usable.
+        //
+        // The served path is checked again under the soul lock, which roster
+        // reloads take too: a default repointed while the key was being
+        // written, or while the grant queued behind another soul edit, would
+        // otherwise be granted in a file the running agent no longer reads.
+        let granted = false;
+        let grantError;
+        try {
+            granted = await grantSoulCredential(request.soulPath, request.name, request.agentId, {
+                check: () => {
+                    const servedNow = sources.get(request.agentId)?.soulPath;
+                    if (servedNow !== request.soulPath) {
+                        throw new Error(`${request.agentId} is now served from ${servedNow ?? 'no soul file'}, not ${request.soulPath}`);
+                    }
+                },
+            });
+        }
+        catch (error) {
+            grantError = error instanceof Error ? error.message : String(error);
+        }
+        await bus.emit({
+            type: 'credential.provided',
+            sessionId: request.sessionId,
+            agentId: request.agentId,
+            requestId: input.requestId,
+            name: request.name,
+            scope: request.scope,
+            ...(input.actor !== undefined ? { actor: input.actor } : {}),
+            ...(grantError !== undefined ? { grantError } : {}),
+        });
+        if (grantError !== undefined) {
+            return {
+                ok: false,
+                retired: true,
+                message: `${request.name} was stored, but could not be added to ${request.soulPath} `
+                    + `(${grantError}). Add it to the soul's credentials list by hand.`,
+            };
+        }
+        return { ok: true, name: request.name, scope: request.scope, agentId: request.agentId, granted };
+    };
     tools.register(createDelegateTool({
         registry,
         dispatch: (input) => dispatchInternal({
@@ -1095,6 +1435,16 @@ export const createGateway = (options = {}) => {
         // 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;
+        /**
+         * What the watchdog last heard, for the warning it logs when it fires.
+         *
+         * "No activity for 120000ms" alone could not tell a provider that went
+         * quiet mid-stream from one whose progress never reached the bus at
+         * all, and that is the first question every abort raised. Event and
+         * delta types only, never content: this lands in the daemon log.
+         */
+        let lastHeard = 'nothing since the turn began';
+        let deltasHeard = 0;
         const suspendTimer = () => {
             if (timer) {
                 clearTimeout(timer);
@@ -1109,7 +1459,8 @@ 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(() => {
-                warn(`watchdog: no activity on session ${sessionId} for ${effectiveIdleMs}ms; aborting the turn`);
+                warn(`watchdog: no activity on session ${sessionId} for ${effectiveIdleMs}ms; aborting the turn `
+                    + `(last heard: ${lastHeard}; ${deltasHeard} provider deltas this turn)`);
                 // 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
@@ -1132,6 +1483,13 @@ export const createGateway = (options = {}) => {
             if (!('sessionId' in event) || event.sessionId !== sessionId) {
                 return;
             }
+            if (event.type === 'provider.delta') {
+                deltasHeard += 1;
+                lastHeard = `provider.delta ${event.delta.type}`;
+            }
+            else {
+                lastHeard = event.type;
+            }
             switch (event.type) {
                 case 'provider.delta':
                     // Only a *fallback* reset marks the mid-turn, session-sticky
@@ -1254,6 +1612,22 @@ export const createGateway = (options = {}) => {
      * session sufficient.
      */
     const activeTurns = new Map();
+    /**
+     * Keyed dispatches not yet settled, by session and key — what a repeat
+     * attaches to. In memory on purpose: it only has to cover the turns this
+     * process is running, and the transcript covers the rest.
+     */
+    // Nested rather than one joined string: both halves are the caller's, and
+    // no separator is one a caller cannot also put inside a key. The agent
+    // the dispatch named rides along, so a repeat naming another is not
+    // handed a session that is not its agent's.
+    // `confirmed` once the chain has seen the dispatch past the identity
+    // check with a key the session had not seen (`claimLiveItem`); until
+    // then the entry is a claim that may yet be refused. `addressed` is false
+    // for a turn nobody asked for, which `holdsMessage` does not count.
+    const liveWorkItems = new Map();
+    /** The start-up snapshot `recoverParkedTurns` judges orphans from, for a repeat that gets there first. */
+    let orphanedAtStart = new Set();
     /**
      * The runtime one agent would run on right now — config snapshot, soul
      * pins, degradation and all.
@@ -1324,6 +1698,33 @@ export const createGateway = (options = {}) => {
         // failure from here is a credential or provider problem and surfaces.
         return resolveRuntimeConfig(selection, resolveEnv);
     };
+    /**
+     * Whether the turn about to run streams deltas, which arms the idle
+     * watchdog — on the sticky fallback when the session already switched to
+     * it, since that is the provider the turn will be served by.
+     */
+    const watchdogStreamsFor = (session, config) => {
+        const switchedToFallback = session?.metadata?.[FALLBACK_ACTIVE_METADATA_KEY] === true;
+        const fallbackStreams = config.provider !== 'demo' && config.fallback
+            ? fallbackStreamsDeltas(config.fallback)
+            : false;
+        const effectiveStreams = switchedToFallback && config.provider !== 'demo' && config.fallback
+            ? fallbackStreamsDeltas(config.fallback)
+            : streamsDeltas(config);
+        return { switchedToFallback, effectiveStreams, fallbackStreams };
+    };
+    /**
+     * Whether a turn on this config could be served by a harness
+     * (`runsOnHarness`): the primary or, since a turn can switch mid-run, the
+     * fallback. Once a session has switched for good the primary is never
+     * called again, and only the fallback counts.
+     */
+    const reachesHarness = (config, switchedToFallback) => {
+        const fallback = config.provider !== 'demo' ? config.fallback : undefined;
+        return switchedToFallback && fallback !== undefined
+            ? runsOnHarness(fallback)
+            : runsOnHarness(config) || (fallback !== undefined && runsOnHarness(fallback));
+    };
     const dispatchInternal = async (input) => {
         // Re-read on every turn, not once at start: a newer build that stamps
         // the home while this daemon is serving has formats this build does not
@@ -1374,15 +1775,15 @@ export const createGateway = (options = {}) => {
             [EXECUTOR_METADATA_KEY]: executorRecord,
         };
         if (existing && existing.agent.id !== agent.id) {
-            throw new Error(`Session ${input.sessionId} belongs to agent ${existing.agent.id}, not ${agent.id} — sessions never cross agent identities.`);
-        }
-        const switchedToFallback = existing?.metadata?.[FALLBACK_ACTIVE_METADATA_KEY] === true;
-        const fallbackStreams = config.provider !== 'demo' && config.fallback
-            ? fallbackStreamsDeltas(config.fallback)
-            : false;
-        const effectiveStreams = switchedToFallback && config.provider !== 'demo' && config.fallback
-            ? fallbackStreamsDeltas(config.fallback)
-            : streamsDeltas(config);
+            throw crossIdentityError(input.sessionId, existing.agent.id, agent.id);
+        }
+        const { switchedToFallback, effectiveStreams, fallbackStreams } = watchdogStreamsFor(existing, config);
+        // Recorded with a keyed message so a restart judges the turn by what it
+        // could have run on, not by whatever the config resolves to by then.
+        // The fallback counts: a turn can switch to it mid-run. Once a session
+        // has switched for good, the primary is never called again, and only
+        // the fallback counts.
+        const hostedLoop = input.idempotencyKey !== undefined && reachesHarness(config, switchedToFallback);
         return withWatchdog(input.sessionId, input.signal, effectiveStreams, fallbackStreams, async (signal) => {
             // The preflight above (agent refresh, config resolution, session
             // load) awaited filesystem work; the entry check has long passed.
@@ -1410,6 +1811,19 @@ export const createGateway = (options = {}) => {
                 if (existing.metadata?.[EXECUTOR_METADATA_KEY] !== executorRecord) {
                     existing.metadata = { ...existing.metadata, [EXECUTOR_METADATA_KEY]: executorRecord };
                 }
+                // The room rides on the turn, but two readers have only the
+                // session's: a turn parked on approval and recovered after a
+                // restart, and a turn that brings no room of its own (a schedule
+                // firing into the thread). Both get the latest room this way, not
+                // the first turn's, which a channel made public since would make
+                // read as more private than it is. A turn from a channel that
+                // could not tell the room (its lookup failed) clears it instead:
+                // no room is the generic line, and an old one is a claim.
+                if (typeof input.metadata?.channel === 'string') {
+                    const room = input.metadata[CONVERSATION_METADATA_KEY];
+                    const { [CONVERSATION_METADATA_KEY]: _stale, ...rest } = existing.metadata ?? {};
+                    existing.metadata = room !== undefined ? { ...rest, [CONVERSATION_METADATA_KEY]: room } : rest;
+                }
                 await store.save(existing);
                 // The turn's metadata rides along for the sender's trust: without
                 // it a resumed turn has no way to say who sent it, and a stranger
@@ -1420,7 +1834,10 @@ export const createGateway = (options = {}) => {
                     userMessage: input.userMessage,
                     ...(input.images !== undefined ? { images: input.images } : {}),
                     ...(input.addressed !== undefined ? { addressed: input.addressed } : {}),
+                    ...(input.idempotencyKey !== undefined ? { idempotencyKey: input.idempotencyKey } : {}),
+                    ...(hostedLoop ? { hostedLoop } : {}),
                     ...(input.metadata ? { metadata: input.metadata } : {}),
+                    runtime: runtimeContextFor(source, config, switchedToFallback, input.metadata),
                     signal,
                 });
             }
@@ -1430,7 +1847,10 @@ export const createGateway = (options = {}) => {
                 userMessage: input.userMessage,
                 ...(input.images !== undefined ? { images: input.images } : {}),
                 ...(input.addressed !== undefined ? { addressed: input.addressed } : {}),
+                ...(input.idempotencyKey !== undefined ? { idempotencyKey: input.idempotencyKey } : {}),
+                ...(hostedLoop ? { hostedLoop } : {}),
                 metadata,
+                runtime: runtimeContextFor(source, config, switchedToFallback, input.metadata),
                 signal,
             });
         });
@@ -1512,7 +1932,13 @@ export const createGateway = (options = {}) => {
         }
         return new Set([...claimants.values()].filter((ids) => ids.length === 1).map(([id]) => id));
     };
-    const recoverOne = (sessionId, orphaned) => onSessionChain(sessionId, async () => {
+    const recoverOne = (sessionId, orphaned) => onSessionChain(sessionId, () => recoverParked(sessionId, orphaned));
+    /**
+     * `recoverOne`'s work, for a caller already on the session's chain: a
+     * repeated idempotency key that reached the chain before the parked sweep
+     * did, and would otherwise wait on a turn nothing is running yet.
+     */
+    const recoverParked = async (sessionId, orphaned) => {
         if (stopping) {
             return;
         }
@@ -1571,7 +1997,8 @@ export const createGateway = (options = {}) => {
             // resuming.
             session.agent = source.definition;
             await store.save(session);
-            const runner = runnerFor(await runtimeForAgent(source));
+            const recoveredConfig = await runtimeForAgent(source);
+            const runner = runnerFor(recoveredConfig);
             // 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
@@ -1583,7 +2010,11 @@ export const createGateway = (options = {}) => {
                 controller.abort(new RunAbortedError(RESTARTING_TURN_ERROR));
             }
             try {
-                await runner.recoverPendingApproval(sessionId, { denyPending: expired, signal: controller.signal });
+                await runner.recoverPendingApproval(sessionId, {
+                    denyPending: expired,
+                    runtime: runtimeContextFor(source, recoveredConfig, session.metadata?.[FALLBACK_ACTIVE_METADATA_KEY] === true, session.metadata),
+                    signal: controller.signal,
+                });
             }
             finally {
                 turnControllers.delete(controller);
@@ -1600,22 +2031,31 @@ export const createGateway = (options = {}) => {
         }
         catch (error) {
             warn(`could not recover parked session ${sessionId}: ${error instanceof Error ? error.message : String(error)}`);
+            // A keyed item is a promise to its caller, and one whose recovery
+            // cannot even start (its agent gone, its provider unresolvable) would
+            // otherwise stay parked for every later start and redelivery to try
+            // again. An unkeyed one keeps waiting for a sweep that can, as before.
+            const after = await store.get(sessionId).catch(() => undefined);
+            const key = after?.messages.findLast((candidate) => candidate.role === 'user')?.idempotencyKey;
+            if (after !== undefined && key !== undefined && after.status === 'pending_approval' && workItemState(after, key) === 'unfinished') {
+                await failParked(after, ABANDONED_TURN_ERROR).catch(() => { });
+            }
         }
-    });
+    };
     /**
      * 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 failOrphanedDelegation = (session) => failParked(session, ORPHANED_DELEGATION_ERROR);
+    const failParked = async (session, error) => {
         const metadata = { ...(session.metadata ?? {}) };
         delete metadata[PENDING_APPROVAL_METADATA_KEY];
         session.metadata = metadata;
-        session.status = 'failed';
-        session.lastError = ORPHANED_DELEGATION_ERROR;
+        recordTurnFailure(session, 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 });
+        await bus.emit({ type: 'session.failed', sessionId: session.id, error });
     };
     /**
      * Turns the last process was still running when it stopped being able to
@@ -1627,9 +2067,12 @@ export const createGateway = (options = {}) => {
      * 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.
+     * restart can rebuild). None of those can be re-entered where they
+     * stopped, and nothing else sweeps them, so the record would go on
+     * claiming the turn is running for as long as the session exists. A turn
+     * whose caller gave it an idempotency key is continued from its
+     * transcript instead, with its dangling calls closed as interrupted
+     * (`settleAbandonedTurn`); the rest are failed.
      *
      * Note what this is *not* for. A graceful stop denies everything parked
      * and drains the turns those denials release, so an operator restarting
@@ -1643,7 +2086,8 @@ export const createGateway = (options = {}) => {
         return store.listIdsByStatus('running');
     };
     /**
-     * Marks each of them failed, with a reason that says what happened.
+     * Settles each of them — continued if keyed, otherwise marked 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
@@ -1671,7 +2115,7 @@ export const createGateway = (options = {}) => {
         if (abandoned.length === 0) {
             return;
         }
-        log(`failing ${abandoned.length} turn(s) left running by the last stratusd`);
+        log(`settling ${abandoned.length} turn(s) left running by the last stratusd`);
         await Promise.allSettled(abandoned.map((id) => failAbandonedTurn(id)));
     };
     const failAbandonedTurn = (id) => onSessionChain(id, async () => {
@@ -1686,16 +2130,200 @@ export const createGateway = (options = {}) => {
             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 });
+            await settleAbandonedTurn(session);
         }
         catch (error) {
-            warn(`could not fail abandoned turn ${id}: ${error instanceof Error ? error.message : String(error)}`);
+            warn(`could not settle abandoned turn ${id}: ${error instanceof Error ? error.message : String(error)}`);
         }
     });
+    /**
+     * A turn left `running` with nothing running it, read on its chain.
+     *
+     * One whose message carries an idempotency key is a work item its caller
+     * was promised would finish, so it is continued from the transcript
+     * (`AgentRunner.continueTurn`) — once. A turn that already was, and is
+     * here again, took the last process down with it, and continuing it again
+     * would do the same on every start; it is failed like an unkeyed one,
+     * whose caller was never promised anything and is told to send again.
+     */
+    const settleAbandonedTurn = async (session) => {
+        const message = session.messages.findLast((candidate) => candidate.role === 'user');
+        if (message?.idempotencyKey === undefined) {
+            return failAbandoned(session);
+        }
+        // An answer already in the transcript is completed whatever came before
+        // — a second crash, a harness, an agent or provider gone since —
+        // because completing it needs none of them and runs nothing again;
+        // failing it would throw away a finished reply.
+        if (lastResponseIsAnswer(session)) {
+            log(`${session.id}: a keyed turn the last stratusd was running had saved its answer; completing it`);
+            return completeAnsweredTurn(session, store, bus);
+        }
+        if (message.continuedAfterCrash === true) {
+            return failAbandoned(session);
+        }
+        if (message.hostedLoop === true) {
+            log(`${session.id}: a keyed turn the last stratusd was running could reach a harness, which cannot be continued; failing it`);
+            return failAbandoned(session);
+        }
+        return continueAbandonedTurn(session);
+    };
+    const failAbandoned = async (session) => {
+        recordTurnFailure(session, ABANDONED_TURN_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: ABANDONED_TURN_ERROR });
+        return session;
+    };
+    /**
+     * Continues an abandoned turn on the configuration a dispatch for its
+     * agent would resolve now, and under the same watchdog — it is a provider
+     * call like any turn's. The definition is refreshed and saved first, as
+     * `recoverOne` does and for the same reason: an allowlist is a permission
+     * boundary, and a tool dropped while the daemon was down must not run.
+     *
+     * Not on a harness (`runsOnHarness`) — neither one the turn could have
+     * run on (`Message.hostedLoop`, recorded when it was accepted) nor one it
+     * would continue on. A harness runs its own tool loop inside a single
+     * provider call and keeps its own conversation, so the prompt the dead
+     * turn sent may already have run tools there that the transcript never
+     * saw, and continuing would send it again. That turn is failed as an
+     * unkeyed one is — the same answer as before keys existed. (A turn whose
+     * answer is already saved never gets here: `settleAbandonedTurn`
+     * completes it first.)
+     */
+    const continueAbandonedTurn = async (session) => {
+        // Settled either way: a turn whose agent left the roster, or whose
+        // provider no longer resolves, must not stay `running` for every later
+        // start and every redelivery to find unfinished and trip over again.
+        let source;
+        let config;
+        try {
+            source = await refreshAgent(session.agent.id);
+            config = await runtimeForAgent(source);
+        }
+        catch (error) {
+            log(`${session.id}: a keyed turn the last stratusd was running cannot be continued (${error instanceof Error ? error.message : String(error)}); failing it`);
+            return failAbandoned(session);
+        }
+        const { switchedToFallback, effectiveStreams, fallbackStreams } = watchdogStreamsFor(session, config);
+        // The message's own record covers the runtimes the turn could have run
+        // on; this covers the ones it would continue on — a fallback included —
+        // which a changed config may make a harness.
+        if (reachesHarness(config, switchedToFallback)) {
+            log(`${session.id}: a keyed turn the last stratusd was running would continue on a harness; failing it`);
+            return failAbandoned(session);
+        }
+        log(`${session.id}: continuing a keyed turn the last stratusd was still running`);
+        session.agent = source.definition;
+        await store.save(session);
+        const runner = runnerFor(config);
+        return withWatchdog(session.id, undefined, effectiveStreams, fallbackStreams, async (signal) => await runner.continueTurn(session.id, {
+            runtime: runtimeContextFor(source, config, switchedToFallback, session.metadata),
+            signal,
+        }) ?? session);
+    };
+    /**
+     * A repeated idempotency key that reached the session's chain, so nothing
+     * else is running on the session. `undefined` means the key is new here
+     * and the dispatch runs as any other; otherwise this is the session to
+     * resolve with, and no new turn starts.
+     *
+     * An unfinished item here has no live turn — the live map would have
+     * answered first — so it is one the last process left, reached before
+     * the start-up sweep that would have settled it: settled now, the way
+     * that sweep would, which then finds it no longer needs anything.
+     */
+    const settleRepeat = async (sessionId, idempotencyKey, agentId, turnId, onRepeat) => {
+        const session = await store.get(sessionId);
+        if (session === undefined) {
+            return undefined;
+        }
+        // Before anything is returned: the turn a dispatch would run is refused
+        // for naming another agent, and the one it would repeat is no less that
+        // agent's — a repeat is not a way to read its transcript.
+        if (agentId !== undefined && session.agent.id !== agentId) {
+            throw crossIdentityError(sessionId, session.agent.id, agentId);
+        }
+        const state = workItemState(session, idempotencyKey);
+        if (state === undefined) {
+            const archived = await archivedRepeat(session, idempotencyKey);
+            if (archived !== undefined) {
+                onRepeat?.('finished');
+            }
+            return archived;
+        }
+        if (state === 'finished') {
+            onRepeat?.('finished');
+            return session;
+        }
+        // Run now, on this caller's behalf, so its events are this caller's
+        // turn — the adapter waiting on them has no other way to claim them.
+        if (turnId !== undefined) {
+            activeTurns.set(sessionId, turnId);
+        }
+        try {
+            return await settleUnfinished(session);
+        }
+        finally {
+            if (turnId !== undefined) {
+                activeTurns.delete(sessionId);
+            }
+        }
+    };
+    /**
+     * The archived transcript holding a key the live row does not, when the
+     * row is a rollover's fresh one made inside `ROLLOVER_REPEAT_WINDOW_MS`.
+     * Only the one rollover back: a second inside the window is a redelivery
+     * outliving two deliberate resets, and the chain is not walked for it.
+     * Always finished — a rollover refuses a session with a turn in flight.
+     */
+    const archivedRepeat = async (session, idempotencyKey) => {
+        const archivedAs = session.metadata?.[ROLLED_OVER_FROM_METADATA_KEY];
+        if (typeof archivedAs !== 'string' || Date.now() - Date.parse(session.createdAt) > ROLLOVER_REPEAT_WINDOW_MS) {
+            return undefined;
+        }
+        const archived = await store.get(archivedAs);
+        return archived !== undefined && workItemState(archived, idempotencyKey) !== undefined ? archived : undefined;
+    };
+    /** An unfinished item with no live turn, settled the way the start-up sweeps would. */
+    const settleUnfinished = async (session) => {
+        if (session.status === 'pending_approval') {
+            await recoverParked(session.id, orphanedAtStart.has(session.id));
+            return (await store.get(session.id)) ?? session;
+        }
+        return settleAbandonedTurn(session);
+    };
+    /**
+     * Settles a keyed item the last process left unfinished before any other
+     * message joins its session. Channels are up before the sweeps reach it,
+     * and a different message resumed onto it would become the session's
+     * newest, so `workItemState` would call the old item finished: its
+     * redelivery would then run nothing although its turn never finished.
+     *
+     * Keyed items only. An unkeyed turn's caller was promised nothing, and a
+     * message resuming it is the long-standing way such a session recovers.
+     */
+    const settleOrphanedItem = async (sessionId) => {
+        const session = await store.get(sessionId);
+        const key = session?.messages.findLast((candidate) => candidate.role === 'user')?.idempotencyKey;
+        if (session !== undefined && key !== undefined && workItemState(session, key) === 'unfinished') {
+            // A continuation that fails has failed its session, which is settled
+            // too; the message waiting behind it runs either way.
+            await settleUnfinished(session).catch((error) => {
+                warn(`could not settle ${sessionId}'s unfinished turn before the next message: ${error instanceof Error ? error.message : String(error)}`);
+            });
+            // Settling can leave it unfinished — a shutdown that began after this
+            // message was accepted skips recovery — and the message must not run
+            // over it then, or the old key reads finished with its turn never run.
+            const after = await store.get(sessionId);
+            if (after !== undefined && workItemState(after, key) === 'unfinished') {
+                throw stopping
+                    ? refusal()
+                    : new Error(`Session ${sessionId} has an unfinished turn that could not be settled, so this message was not added behind it. Send it again.`);
+            }
+        }
+    };
     /**
      * Runs `work` as the session's next turn: queued behind whatever that
      * session is already doing, and tracked so shutdown drains it.
@@ -1758,11 +2386,125 @@ export const createGateway = (options = {}) => {
         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));
+        const { turnId, idempotencyKey } = input;
+        if (idempotencyKey !== undefined && (idempotencyKey.length === 0 || idempotencyKey.length > MAX_IDEMPOTENCY_KEY_LENGTH)) {
+            throw new Error(`An idempotency key is 1 to ${MAX_IDEMPOTENCY_KEY_LENGTH} characters; this one is ${idempotencyKey.length}.`);
+        }
+        // A repeat of a dispatch still queued or running is that dispatch: it
+        // resolves with it rather than queueing behind it, which would let
+        // another caller's turn land in between and then find a finished item.
+        // Attached only when it names no other agent than the live dispatch
+        // did; otherwise it queues, and `settleRepeat` refuses it there.
+        const live = idempotencyKey !== undefined ? liveWorkItems.get(input.sessionId)?.get(idempotencyKey) : undefined;
+        // A claim naming an agent other than this delivery does, that the chain
+        // has not yet confirmed — this delivery naming nobody, or someone else.
+        // The claim may be refused for who it named, and then the item is still
+        // unowned: inheriting the refusal would drop a valid message, and
+        // queueing behind it would leave this delivery to find the turn that a
+        // later valid delivery runs `finished`, and answer it twice. So it
+        // waits for the claim to settle and decides then: a claim that stood
+        // is repeated, by a delivery naming its owner or nobody, and refuses
+        // anyone else; a claim that left the item unowned is dispatched again,
+        // where the first delivery to get there runs it and the rest attach.
+        if (live !== undefined && !live.confirmed && live.agentId !== undefined && input.agentId !== live.agentId) {
+            const claim = live.turn;
+            const claimedBy = input.agentId;
+            const repeatOf = (owner) => {
+                if (claimedBy !== undefined && claimedBy !== owner) {
+                    throw crossIdentityError(input.sessionId, owner, claimedBy);
+                }
+                input.onRepeat?.('live');
+            };
+            return claim.then((session) => {
+                repeatOf(session.agent.id);
+                return session;
+            }, async (error) => {
+                // Refused for who it named, or failed before its keyed message was
+                // ever written (an agent gone, a provider it could not build): the
+                // item is still unowned, and there is no turn to have repeated.
+                const stored = error instanceof CrossIdentityError || idempotencyKey === undefined ? undefined : await store.get(input.sessionId);
+                const owned = stored !== undefined && idempotencyKey !== undefined && workItemState(stored, idempotencyKey) !== undefined;
+                if (owned) {
+                    repeatOf(stored.agent.id);
+                    throw error;
+                }
+                // Its own cleanup runs a tick later; the dispatch below must not
+                // find the dead claim still standing and wait on it again.
+                const items = liveWorkItems.get(input.sessionId);
+                if (idempotencyKey !== undefined && items?.get(idempotencyKey)?.turn === claim) {
+                    items.delete(idempotencyKey);
+                    if (items.size === 0) {
+                        liveWorkItems.delete(input.sessionId);
+                    }
+                }
+                return dispatch(input);
+            });
         }
-        return onSessionChain(input.sessionId, async () => {
+        if (live !== undefined && (input.agentId === undefined || input.agentId === live.agentId)) {
+            input.onRepeat?.('live');
+            return live.turn;
+        }
+        // The live dispatch named no agent, so whose session it is is known
+        // only once its turn resolves. Queueing instead would make this a
+        // `finished` repeat of a turn the live caller is still rendering — two
+        // answers — so it attaches, and is held to the agent it named then:
+        // told it repeated only if that agent owns the session, refused if not.
+        const claimed = input.agentId;
+        if (live !== undefined && live.agentId === undefined && claimed !== undefined) {
+            const shared = live.turn;
+            // Whichever way the turn ends: a failed one is still that agent's,
+            // its owner read from the store, and a repeat of it is still told so
+            // — or refused, rather than handed another agent's error.
+            const attach = async () => {
+                let outcome;
+                try {
+                    outcome = { session: await shared };
+                }
+                catch (error) {
+                    outcome = { error };
+                }
+                const owner = 'session' in outcome ? outcome.session.agent.id : (await store.get(input.sessionId))?.agent.id;
+                if (owner !== undefined && owner !== claimed) {
+                    throw crossIdentityError(input.sessionId, owner, claimed);
+                }
+                // No owner means the dispatch failed before its session was ever
+                // written: there is no turn to have repeated, only its error.
+                if (owner !== undefined) {
+                    input.onRepeat?.('live');
+                }
+                if ('error' in outcome) {
+                    throw outcome.error;
+                }
+                return outcome.session;
+            };
+            return attach();
+        }
+        // Reads `turn` only once it is assigned: the registration below runs
+        // after it, and the chain's work runs in a later tick (`.then`).
+        const claimLiveItem = (key, confirmed) => {
+            const items = liveWorkItems.get(input.sessionId) ?? new Map();
+            items.set(key, { turn, agentId: input.agentId, confirmed, addressed: input.addressed !== false });
+            liveWorkItems.set(input.sessionId, items);
+        };
+        const turn = onSessionChain(input.sessionId, async () => {
+            // Before `activeTurns` is touched: a repeat that runs nothing must
+            // not claim the session's turn id, even for the instant it takes.
+            const repeated = idempotencyKey !== undefined ? await settleRepeat(input.sessionId, idempotencyKey, input.agentId, turnId, input.onRepeat) : undefined;
+            if (repeated !== undefined) {
+                return repeated;
+            }
+            // Past the identity check with a key the session has not seen, so this
+            // dispatch owns the item: it becomes the live entry even if a claimant
+            // that was then refused registered first, or a repeat arriving while
+            // this turn runs would find nothing to attach to, queue, and read the
+            // turn as finished — a second answer beside this caller's.
+            if (idempotencyKey !== undefined) {
+                claimLiveItem(idempotencyKey, true);
+            }
+            await settleOrphanedItem(input.sessionId);
+            if (turnId === undefined) {
+                return dispatchInternal(input);
+            }
             activeTurns.set(input.sessionId, turnId);
             try {
                 return await dispatchInternal(input);
@@ -1774,6 +2516,25 @@ export const createGateway = (options = {}) => {
                 activeTurns.delete(input.sessionId);
             }
         });
+        if (idempotencyKey !== undefined) {
+            // A repeat that queued instead of attaching — it named another agent,
+            // and is about to be refused — must not displace the turn it repeats.
+            // The first registration is provisional; the chain confirms it
+            // (`claimLiveItem` above) once the dispatch is known to own the item.
+            if (liveWorkItems.get(input.sessionId)?.has(idempotencyKey) !== true) {
+                claimLiveItem(idempotencyKey, false);
+            }
+            void turn.catch(() => { }).finally(() => {
+                const current = liveWorkItems.get(input.sessionId);
+                if (current?.get(idempotencyKey)?.turn === turn) {
+                    current.delete(idempotencyKey);
+                    if (current.size === 0) {
+                        liveWorkItems.delete(input.sessionId);
+                    }
+                }
+            });
+        }
+        return turn;
     };
     const observe = async (input) => {
         if (stopping) {
@@ -1802,7 +2563,7 @@ export const createGateway = (options = {}) => {
                 return undefined;
             }
             if (input.agentId !== undefined && existing.agent.id !== input.agentId) {
-                throw new Error(`Session ${input.sessionId} belongs to agent ${existing.agent.id}, not ${input.agentId} — sessions never cross agent identities.`);
+                throw crossIdentityError(input.sessionId, existing.agent.id, input.agentId);
             }
             const continuedAs = existing.metadata?.[ROLLED_OVER_TO_METADATA_KEY];
             if (typeof continuedAs === 'string') {
@@ -1852,7 +2613,8 @@ export const createGateway = (options = {}) => {
             // *calling* agent's — its allowlist checked, its own entry before the
             // fleet's shared one.
             credentials: createFileCredentialResolver(env),
-            workspaces: createAgentWorkspaces(env),
+            workspaces: agentWorkspaces,
+            stateDirectories: createPluginStateDirectories(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.
@@ -1920,6 +2682,7 @@ export const createGateway = (options = {}) => {
      * qualified `<package>:<skill>` form.
      */
     const startSkills = async () => {
+        await registerBuiltinSkills(skillCatalog);
         operatorSkills = await loadOperatorSkills(env, skillCatalog, warn);
         for (const skill of operatorSkills) {
             log(`skill ${skill.id} loaded from ${skill.path}`);
@@ -1991,6 +2754,7 @@ export const createGateway = (options = {}) => {
         // agent.delegate call is only answerable while nothing can resume that
         // parent. See listOrphanedDelegations.
         const orphaned = await listOrphanedDelegations();
+        orphanedAtStart = orphaned;
         // 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. The host's adapters first, then
@@ -2262,6 +3026,24 @@ export const createGateway = (options = {}) => {
         },
         dispatch,
         observe,
+        async holdsMessage(sessionId, idempotencyKey) {
+            // A dispatch still queued behind another turn holds the message too:
+            // its key reaches the transcript only when the chain gets to it. By
+            // the same rule as the transcript below — a judged turn still waiting
+            // to run did not take the message either.
+            if (liveWorkItems.get(sessionId)?.get(idempotencyKey)?.addressed === true) {
+                return true;
+            }
+            const session = await store.get(sessionId);
+            if (session === undefined) {
+                return false;
+            }
+            const transcript = workItemState(session, idempotencyKey) !== undefined ? session : await archivedRepeat(session, idempotencyKey);
+            // Accepted as addressed: a turn nobody asked for (`addressed: false`,
+            // stored overheard) was this agent hearing the message, not taking it.
+            const keyed = transcript?.messages.findLast((message) => message.role === 'user' && message.idempotencyKey === idempotencyKey);
+            return keyed !== undefined && keyed.overheard !== true;
+        },
         async sessionRouting(sessionId) {
             const session = await store.get(sessionId);
             if (!session) {
@@ -2392,7 +3174,9 @@ export const createGateway = (options = {}) => {
             return registry.list();
         },
         async reloadRoster() {
-            await reloadsInOrder(loadRoster);
+            // Under the soul lock, so a repoint cannot land between a credential
+            // grant's check of the served path and its write (`grantSoulCredential`).
+            await reloadsInOrder(() => withSoulFileLock(loadRoster));
             const roster = registry.list();
             log(`roster reloaded — ${roster.length} agent(s): ${roster.map((agent) => agent.name).join(', ')}`);
             return roster;
@@ -2459,6 +3243,9 @@ export const createGateway = (options = {}) => {
             });
             return status;
         },
+        async checkRestart() {
+            await options.restartPreflight?.();
+        },
         activeTurnId(sessionId) {
             return activeTurns.get(sessionId);
         },
@@ -2493,7 +3280,7 @@ export const createGateway = (options = {}) => {
             // From the registry, not from the load records: the registry is the
             // live answer for which bare aliases still resolve — a plugin loaded
             // later can have retired one a record still remembers.
-            const provenance = new Map();
+            const provenance = new Map([[STRATUS_SKILL_ID, { path: STRATUS_SKILL_PATH }]]);
             for (const info of operatorSkills) {
                 provenance.set(info.id, { path: info.path });
             }
@@ -2512,6 +3299,7 @@ export const createGateway = (options = {}) => {
                     ...(alias !== undefined ? { alias } : {}),
                     ...(from?.package !== undefined ? { package: from.package } : {}),
                     ...(from !== undefined ? { path: from.path } : {}),
+                    ...(skill.builtin === true ? { builtin: true } : {}),
                 };
             });
         },
@@ -2583,6 +3371,7 @@ export const createGateway = (options = {}) => {
             })).then((entries) => entries.filter((entry) => entry !== undefined));
         },
         resolveApproval,
+        provideCredential,
     };
     return gateway;
 };