@stratusagent/gateway 0.14.1 → 0.14.3

package/dist/index.js

@@ -9,9 +9,10 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { createHash, randomBytes, randomUUID } from 'node:crypto';
 import { mkdir, readFile, rename, rm } from 'node:fs/promises';
 import path from 'node:path';
-import { filePathsOf, isUnaddressedTurn, carriesKey, leastTrusted, senderTrustOf, SENDER_TRUST_METADATA_KEY, workItemState, leftForNextStart, lastResponseIsAnswer, MAX_IDEMPOTENCY_KEY_LENGTH, recordTurnFailure, completeAnsweredTurn, abortErrorFor, sessionTrustOf, sessionWriteTrust, 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, imagesWithinReplayBudget, matchesToolAllowlist, } from '@stratusagent/core';
-import { CREDENTIAL_REQUEST_TOOL_NAME, createCredentialRequestTool, createDelegateTool, DELEGATE_TOOL_NAME, createForgetTool, createPinTool, createMessageSendTool, createMessageReadTool, createChannelArchiveTool, createChannelCreateTool, createChannelInviteTool, createChannelJoinTool, directMessageReadRefusal, createRecallTool, createRememberTool, createScheduleTools, DELEGATED_BY_METADATA_KEY, DELEGATED_SESSION_ID_MARKER, DEFAULT_MAX_DELEGATION_DEPTH, 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, credentialVariableProblem, } from '@stratusagent/agents';
+import { filePathsOf, isUnaddressedTurn, carriesKey, leastTrusted, senderTrustOf, SENDER_TRUST_METADATA_KEY, workItemState, turnMessageOf, turnKeyOf, leftForNextStart, lastResponseIsAnswer, MAX_IDEMPOTENCY_KEY_LENGTH, recordTurnFailure, completeAnsweredTurn, abortErrorFor, sessionTrustOf, sessionWriteTrust, AgentRegistry, AgentRunner, InMemorySessionStore, MEMORY_PASS_MAX_MODEL_CALLS, MEMORY_PASS_RULES, ChannelRegistry, ContributionRegistry, createRoutedMemoryStore, EventBus, RunAbortedError, SkillRegistry, ToolRegistry, createSkillReadTool, missingSkillRequirements, describeToolAllowlistFinding, unmatchedToolAllowlist, CONTEXT_FLOOR_METADATA_KEY, CONTEXT_SUMMARY_METADATA_KEY, PENDING_APPROVAL_METADATA_KEY, SESSION_TAINTED_BY_METADATA_KEY, SESSION_TRUST_METADATA_KEY, latestTurnReply, readPendingApproval, conversationContextFrom, CONVERSATION_METADATA_KEY, STRATUS_SKILL_ID, imagesWithinReplayBudget, matchesToolAllowlist, resolveToolRisk, } from '@stratusagent/core';
+import { CREDENTIAL_REQUEST_TOOL_NAME, createCredentialRequestTool, createDelegateTool, DELEGATE_TOOL_NAME, createForgetTool, createPinTool, createMessageSendTool, createMessageSayTool, createMessageReadTool, createChannelArchiveTool, createChannelCreateTool, createChannelInviteTool, createChannelJoinTool, directMessageReadRefusal, createRecallTool, createRememberTool, createScheduleTools, DELEGATED_BY_METADATA_KEY, DELEGATED_SESSION_ID_MARKER, DEFAULT_MAX_DELEGATION_DEPTH, 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, credentialVariableProblem, } from '@stratusagent/agents';
 import { createFleetReader } from "./fleet.js";
+import { createMemoryPassHost } from "./memory-passes.js";
 import { createEventIntake, summarizeEvents, } from "./event-intake.js";
 import { SqliteEventStore } from "./events.js";
 import { createSchedulerRuntime, isScheduleSessionId, SqliteScheduleStore, SCHEDULE_SESSION_ID_PREFIX, } from "./schedules.js";
@@ -23,7 +24,7 @@ export { SqliteEventStore, EVENT_BLOCK_MAX_BYTES, EVENT_DEDUP_WINDOW_MS, EVENT_D
 export { createEventIntake, mapGithubDelivery, parseStandardWebhookEvent, verifyGithubSignature, verifyStandardWebhookSignature, DEFAULT_EVENT_MAX_BODY_BYTES, EVENT_SOURCE_REQUESTS_PER_MINUTE, } from "./event-intake.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, resolveDaemonCredential, createHomeMemoryStore, drainSharedMemory, hasBracketedLegacyStateIn, createRuntimeProvider, describeServingModel, DEFAULT_STRATUS_AGENT, isRegisteredProviderName, loadChannelTransportSecrets, registeredProviderNameOf, loadOperatorSkills, loadRosterSouls, FALLBACK_ACTIVE_METADATA_KEY, loadSoulFile, grantSoulCredential, withSoulFileLock, addNamedCredential, appendCredentialAudit, replaceNamedCredential, NamedCredentialMissingError, namedCredentialSource, NamedCredentialExistsError, CREDENTIAL_NAME_PATTERN, quoteShellArg, migrateLegacyMemory, PROVIDER_STATE_METADATA_KEYS, ConfigFileError, loadConfigFile, resolveConfigLocation, resolveConfiguredSoul, resolveRuntimeConfig, runsOnHarness, applySoulPins, assertStateCompatible, stratusHomePath, intakeStatePath, fleetDbIn, createAgentWorkspaces, createPluginStateDirectories, createHostProtectedPaths, foldedAgentId, syncDirectory, writeFileSynced, } from '@stratusagent/state';
+import { BUILTIN_EXECUTOR_NAME, BUILTIN_MEMORY_STORE_NAME, BUILTIN_PROVIDER_NAMES, createDemoTool, createFileCredentialResolver, resolveDaemonCredential, createHomeMemoryStore, drainSharedMemory, hasBracketedLegacyStateIn, createRuntimeProvider, describeServingModel, DEFAULT_STRATUS_AGENT, isRegisteredProviderName, loadChannelTransportSecrets, registeredProviderNameOf, loadOperatorSkills, loadRosterSouls, FALLBACK_ACTIVE_METADATA_KEY, loadSoulFile, grantSoulCredential, withSoulFileLock, addNamedCredential, appendCredentialAudit, replaceNamedCredential, NamedCredentialMissingError, namedCredentialSource, NamedCredentialExistsError, CREDENTIAL_NAME_PATTERN, quoteShellArg, migrateLegacyMemory, PROVIDER_STATE_METADATA_KEYS, ConfigFileError, loadConfigFile, resolveConfigLocation, resolveConfiguredSoul, resolveRuntimeConfig, runsOnHarness, applySoulPins, assertStateCompatible, unlistedToolsFor, stratusHomePath, intakeStatePath, fleetDbIn, createAgentWorkspaces, createPluginStateDirectories, createHostProtectedPaths, foldedAgentId, syncDirectory, writeFileSynced, } from '@stratusagent/state';
 const DEFAULT_IDLE_TIMEOUT_MS = 120_000;
 /**
  * How long a parked call waits for a person. Long enough to survive a
@@ -202,10 +203,19 @@ const MERGED_SEPARATOR = '\n\n';
  */
 const fitsReplayBudget = (images) => images.length === 0 || imagesWithinReplayBudget([{ id: '', createdAt: '', role: 'user', content: '', images: [...images] }]).size === images.length;
 /** A signal that aborts once every one of `signals` has. */
-const allAborted = (signals) => {
+const allAborted = (signals) => joinableSignal(signals).signal;
+/**
+ * `allAborted` for callers that keep joining: a turn that takes in messages
+ * at its tool steps (card 948) is cancelled only once every caller in it
+ * is, the ones who joined late included. A caller joining with no signal
+ * can never cancel, so from then on neither can the turn.
+ */
+const joinableSignal = (initial) => {
     const controller = new AbortController();
+    const signals = [...initial];
+    let uncancellable = false;
     const check = () => {
-        if (!controller.signal.aborted && signals.every((signal) => signal.aborted)) {
+        if (!uncancellable && !controller.signal.aborted && signals.every((signal) => signal.aborted)) {
             controller.abort(signals[signals.length - 1]?.reason);
         }
     };
@@ -213,7 +223,17 @@ const allAborted = (signals) => {
         signal.addEventListener('abort', check, { once: true });
     }
     check();
-    return controller.signal;
+    return {
+        signal: controller.signal,
+        join: (signal) => {
+            if (signal === undefined) {
+                uncancellable = true;
+                return;
+            }
+            signals.push(signal);
+            signal.addEventListener('abort', check, { once: true });
+        },
+    };
 };
 /**
  * A value from a form, without the line breaks around it.
@@ -355,6 +375,10 @@ export const RESERVED_SESSION_METADATA_KEYS = [
     // no messages and, once it grows past that index, silently stops sending
     // its own earliest turns, with no overflow and no trim event to say so.
     CONTEXT_FLOOR_METADATA_KEY,
+    // The summary that stands in below that floor, for both of the same
+    // reasons, and one more: the model reads it as something it wrote itself,
+    // so a caller who could seed it could put words in the agent's mouth.
+    CONTEXT_SUMMARY_METADATA_KEY,
     SUB_AGENT_METADATA_KEY,
 ];
 /**
@@ -396,6 +420,8 @@ export const createGateway = (options = {}) => {
     // process-global.
     const fileMemory = createHomeMemoryStore(env);
     let selectedMemory = fileMemory;
+    // The built-in store takes a list in `supersedes`; a plugin's says so.
+    let selectedMemorySupersedesMany = true;
     const memory = createRoutedMemoryStore(() => selectedMemory);
     let selectedExecutor;
     // What loaded plugins contributed besides tools and skills. The loader
@@ -962,15 +988,27 @@ export const createGateway = (options = {}) => {
     // the file on disk is temporarily broken (an operator mid-edit).
     let lastGoodConfigSnapshot;
     /**
-     * Said at load, because the allowlist fails open: `tools` omitted is
-     * every registered tool, the opposite of what `skills` and `credentials`
-     * do when omitted, and a soul that never wrote the key holds `shell.run`
-     * the moment that plugin is enabled. The built-in agent is exempt — it
-     * has no file to add the key to.
+     * Read from the home once, on first use, which is after the migrations
+     * `serve` runs before it starts the gateway. It changes only when 0005
+     * first records it, and that happens before a daemon of this build runs.
+     */
+    let unlistedToolsRead;
+    const unlistedTools = () => options.unlistedTools ?? (unlistedToolsRead ??= unlistedToolsFor(env));
+    /**
+     * Said at load, because an omitted `tools` list is a quiet downgrade on a
+     * home this build set up: it is only the tools registered as safe, so an
+     * agent whose soul never wrote the key cannot run a shell, write a file
+     * or send a message, and nothing else says why. On a home an older build
+     * set up it is every tool, as it always was there, and the line says so
+     * the way it always did. The built-in agent is exempt: it has no file,
+     * and says `tools: ["*"]` in code.
      */
     const warnNoToolsList = (agentId, soulPath) => {
-        warn(`agent ${agentId} has no tools: list, so it may call every tool this daemon loads — `
-            + `add tools: [...] to ${soulPath} to say which`);
+        warn(unlistedTools() === 'every'
+            ? `agent ${agentId} has no tools: list, so it may call every tool this daemon loads — `
+                + `add tools: [...] to ${soulPath} to say which`
+            : `agent ${agentId} has no tools: list, so it gets only safe tools (reads and memory) — `
+                + `add tools: [...] to ${soulPath} to give it more, or tools: ["*"] for every tool`);
     };
     const defaultAgentId = async () => {
         // Identity only — never full runtime resolution: credential checks do
@@ -1409,6 +1447,23 @@ export const createGateway = (options = {}) => {
         const ts = typeof posted === 'object' && posted !== null ? posted.ts : undefined;
         return typeof ts === 'string' && ts.length > 0 ? { id: ts } : {};
     }, { defaultThread: (session, destination) => scheduler.reportThreadFor(session, destination) }));
+    // A mid-task message goes where the conversation is, through the channel
+    // carrying this agent there, and nowhere else (card 1009). A session no
+    // channel started (a terminal run, a schedule nobody watches) has nobody
+    // to say it to before the reply.
+    tools.register(createMessageSayTool(async ({ session, text }) => {
+        const agentId = session.agent.id;
+        const kind = session.metadata?.channel;
+        const { adapter } = typeof kind === 'string'
+            ? channelCarrying(kind, agentId, (candidate) => candidate.say !== undefined)
+            : { adapter: undefined };
+        if (!adapter?.say) {
+            throw new Error(typeof kind === 'string'
+                ? `This conversation's channel (${kind}) cannot take a mid-task message. Say it in your reply.`
+                : 'This conversation is not in a channel that can take a mid-task message. Say it in your reply.');
+        }
+        await adapter.say({ sessionId: session.id, agentId, text });
+    }));
     // The same carrying rule again: a channel is created by the asking
     // agent's own app, whose token never leaves the adapter, and so becomes
     // that app's to post in and read.
@@ -1699,7 +1754,13 @@ export const createGateway = (options = {}) => {
         // bearer credential the model is handed, and whoever it reaches can
         // store a key and amend the soul. That is the operator's to allow.
         const allowlist = session.agent.tools ?? registry.get(agentId)?.tools;
-        const linkAllowed = allowlist === undefined || matchesToolAllowlist(CREDENTIAL_REQUEST_TOOL_NAME, allowlist);
+        // An omitted list grants the safe tools, this one among them, but a
+        // link is the operator's to allow by naming it, so only a list says yes.
+        // On a home an older build set up an omitted list is every tool, and
+        // has always allowed a link there.
+        const linkAllowed = allowlist === undefined
+            ? unlistedTools() === 'every'
+            : matchesToolAllowlist(CREDENTIAL_REQUEST_TOOL_NAME, allowlist);
         // 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;
@@ -2102,7 +2163,9 @@ export const createGateway = (options = {}) => {
         if (!Array.isArray(requested) || requested.some((name) => typeof name !== 'string' || name.length === 0)) {
             return 'A sub-agent\'s tools are a list of tool names.';
         }
-        const allowlist = parent.agent.tools;
+        // Read the way the runner reads it for the parent's own calls: the
+        // session's copy, else the registered agent's.
+        const allowlist = parent.agent.tools ?? registry.get(parent.agent.id)?.tools;
         for (const name of requested) {
             if (/[*?]/.test(name)) {
                 return `A sub-agent's tools are exact names, and ${name} is a pattern.`;
@@ -2110,12 +2173,21 @@ export const createGateway = (options = {}) => {
             if (subAgentNeverGets(name)) {
                 return `${name} is never given to a sub-agent, even by an agent that holds it.`;
             }
-            if (!tools.get(name)) {
+            const tool = tools.get(name);
+            if (!tool) {
                 return `There is no tool named ${name}.`;
             }
             // The parent's allowlist as its running turn holds it: a slice can
-            // only narrow what that turn may already do.
-            if (allowlist !== undefined && !matchesToolAllowlist(name, allowlist)) {
+            // only narrow what that turn may already do. With no list, that is
+            // the tools registered as safe (every tool on a home an older build
+            // set up), and the slice is held to the same rule: naming a gated
+            // tool must not hand it to the sub-agent.
+            if (allowlist === undefined) {
+                if (unlistedTools() !== 'every' && resolveToolRisk(tool) !== 'safe') {
+                    return `${name} is not a safe tool, and ${parent.agent.id}'s soul has no tools: list, so it gets only safe tools and a sub-agent of it cannot have ${name}.`;
+                }
+            }
+            else if (!matchesToolAllowlist(name, allowlist)) {
                 return `${name} is not one of ${parent.agent.id}'s tools, so a sub-agent of it cannot have it.`;
             }
         }
@@ -2296,6 +2368,7 @@ export const createGateway = (options = {}) => {
             // Asking a person for a key is harmless to grant: they decide
             // everything after the question, so no soul has to list it.
             grantedToEveryAgent: subAgent ? [] : [CREDENTIAL_REQUEST_TOOL_NAME],
+            unlistedTools: unlistedTools(),
             ...(subAgent ? {} : { skills: skillCatalog, memory }),
             streaming: true,
             ...(maxTurns !== undefined ? { maxTurns } : {}),
@@ -2565,6 +2638,23 @@ export const createGateway = (options = {}) => {
     // behind the in-flight turn instead of interleaving with it. Sessions
     // are independent — different conversations run concurrently.
     const sessionChains = new Map();
+    /**
+     * Work queued on each session's chain that has not started, of every
+     * kind (a dispatch, an overheard message, a recovery). What says whether
+     * a merged-turn batch is first in line behind the running turn, which
+     * steering needs (card 948): a batch with anything ahead of it would be
+     * answered before what was said first.
+     */
+    const queuedWork = new Map();
+    const releaseQueued = (sessionId) => {
+        const left = (queuedWork.get(sessionId) ?? 1) - 1;
+        if (left > 0) {
+            queuedWork.set(sessionId, left);
+        }
+        else {
+            queuedWork.delete(sessionId);
+        }
+    };
     /**
      * Dispatches queued behind a session's running turn, per session: what
      * tells an auto-continuing turn that somebody wrote meanwhile, so it
@@ -2802,9 +2892,13 @@ export const createGateway = (options = {}) => {
             return await turn;
         }
         catch (error) {
-            if (input.idempotencyKey !== undefined && error instanceof RunAbortedError && error.resumable) {
+            if (error instanceof RunAbortedError && error.resumable) {
                 const left = await store.get(input.sessionId).catch(() => undefined);
-                if (left !== undefined && workItemState(left, input.idempotencyKey) === 'unfinished' && leftForNextStart(left, error)) {
+                // The dispatch's own key, or, for an unkeyed one whose turn took
+                // keyed messages in at a tool step (card 948), the key the turn has
+                // from them: its steered callers are told what a keyed caller is.
+                const key = input.idempotencyKey ?? (left === undefined ? undefined : turnKeyOf(turnMessageOf(left)));
+                if (left !== undefined && key !== undefined && workItemState(left, key) === 'unfinished' && leftForNextStart(left, error)) {
                     throw leftForNext();
                 }
             }
@@ -2816,7 +2910,15 @@ export const createGateway = (options = {}) => {
      * runs as that, on the parent's resolved provider, with no memory and no
      * soul. Only that path passes it.
      */
-    const dispatchInternal = async (input, absorbedKeys = [], subAgent) => {
+    const dispatchInternal = async (input, absorbedKeys = [], subAgent, 
+    /**
+     * See `RunInput.steer`; passed by `dispatch` for an opted-in caller.
+     * Handed the turn's own signal — the one the runner was given, which
+     * the watchdog, `abortTurns` and a restart's window abort as well as
+     * the callers — so it takes nothing into a turn that is already
+     * stopping (card 959).
+     */
+    steer) => {
         // 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
         // understand, and a daemon that kept writing into them would be the
@@ -2936,11 +3038,13 @@ export const createGateway = (options = {}) => {
                     userMessage: input.userMessage,
                     ...(input.images !== undefined ? { images: input.images } : {}),
                     ...(input.addressed !== undefined ? { addressed: input.addressed } : {}),
+                    ...(input.replyOptional === true ? { replyOptional: true } : {}),
                     ...(input.idempotencyKey !== undefined ? { idempotencyKey: input.idempotencyKey } : {}),
                     ...(absorbedKeys.length > 0 ? { absorbedKeys: [...absorbedKeys] } : {}),
                     ...(hostedLoop ? { hostedLoop } : {}),
                     ...(input.metadata ? { metadata: input.metadata } : {}),
                     runtime: runtimeContextFor(source, config, switchedToFallback, input.metadata),
+                    ...(steer !== undefined ? { steer: () => steer(signal) } : {}),
                     signal,
                 });
             }
@@ -2950,12 +3054,14 @@ export const createGateway = (options = {}) => {
                 userMessage: input.userMessage,
                 ...(input.images !== undefined ? { images: input.images } : {}),
                 ...(input.addressed !== undefined ? { addressed: input.addressed } : {}),
+                ...(input.replyOptional === true ? { replyOptional: true } : {}),
                 ...(input.idempotencyKey !== undefined ? { idempotencyKey: input.idempotencyKey } : {}),
                 ...(absorbedKeys.length > 0 ? { absorbedKeys: [...absorbedKeys] } : {}),
                 ...(hostedLoop ? { hostedLoop } : {}),
                 ...(input.earlier !== undefined && input.earlier.length > 0 ? { earlier: input.earlier } : {}),
                 metadata,
                 runtime: runtimeContextFor(source, config, switchedToFallback, input.metadata, subAgent !== undefined),
+                ...(steer !== undefined ? { steer: () => steer(signal) } : {}),
                 signal,
             });
         }));
@@ -3155,7 +3261,7 @@ export const createGateway = (options = {}) => {
             // 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;
+            const key = after === undefined ? undefined : turnKeyOf(turnMessageOf(after));
             if (after !== undefined && key !== undefined && after.status === 'pending_approval' && workItemState(after, key) === 'unfinished') {
                 await failParked(after, ABANDONED_TURN_ERROR).catch(() => { });
             }
@@ -3266,8 +3372,8 @@ export const createGateway = (options = {}) => {
      * 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) {
+        const message = turnMessageOf(session);
+        if (message === undefined || turnKeyOf(message) === undefined) {
             return failAbandoned(session);
         }
         // An answer already in the transcript is completed whatever came before
@@ -3419,6 +3525,100 @@ export const createGateway = (options = {}) => {
         }
         return settleAbandonedTurn(session);
     };
+    /**
+     * What a running turn takes in at its next tool step (card 948): the
+     * merged-turn batch waiting behind it, whole — leader and absorbed alike
+     * — when it is for the same agent. The dispatches it takes join `into`,
+     * which the running turn settles with its own outcome (`runSteerable`).
+     *
+     * A part cancelled while it waited is refused, as `runMerged` refuses it.
+     * A part whose key this session (or the archive it rolled over from)
+     * already holds is a repeat, and judging a repeat can mean settling a
+     * turn — never something to do from inside one — so such a batch is not
+     * taken: it waits and runs next, merged, where that is judged. Nor while
+     * the gateway is stopping, when the batch is what the drain refuses.
+     */
+    const takeSteered = async (sessionId, agentId, into, 
+    /**
+     * Asked last, with nothing awaited after it: whether the running turn
+     * still takes these callers, joining them to its cancellation if so. A
+     * turn cancelled while the store was read takes nothing, and the batch
+     * waits and runs next, as it would have.
+     */
+    admit) => {
+        const batch = openBatches.get(sessionId);
+        if (stopping || batch === undefined || !batch.firstInLine || batch.agentId !== agentId) {
+            return undefined;
+        }
+        // Until every key in it is checked with nothing awaited since: a message
+        // can join while the store is read, and is checked on the next pass; a
+        // batch closed meanwhile is no longer this turn's to take.
+        const checked = new Set();
+        let session;
+        for (;;) {
+            if (stopping || openBatches.get(sessionId) !== batch) {
+                return undefined;
+            }
+            const unchecked = [batch.leader, ...batch.absorbed].flatMap((part) => (part.input.idempotencyKey !== undefined && !checked.has(part.input.idempotencyKey) ? [part.input.idempotencyKey] : []));
+            if (unchecked.length === 0) {
+                break;
+            }
+            session ??= await store.get(sessionId);
+            for (const key of unchecked) {
+                checked.add(key);
+                if (session !== undefined && (workItemState(session, key) !== undefined || await archivedRepeat(session, key) !== undefined)) {
+                    return undefined;
+                }
+            }
+        }
+        const all = [batch.leader, ...batch.absorbed];
+        if (!admit(all.filter((part) => part.input.signal?.aborted !== true))) {
+            return undefined;
+        }
+        openBatches.delete(sessionId);
+        batch.steered = true;
+        // Its place on the chain runs nothing now, so it is not ahead of a batch
+        // opening behind it, which can then be steered at a later step.
+        releaseQueued(sessionId);
+        // Not waiting any more; the leader's place on the chain does not count it again.
+        const left = (waitingDispatches.get(sessionId) ?? all.length) - all.length;
+        if (left > 0) {
+            waitingDispatches.set(sessionId, left);
+        }
+        else {
+            waitingDispatches.delete(sessionId);
+        }
+        const runnable = [];
+        for (const part of all) {
+            if (part.input.signal?.aborted) {
+                part.reject(abortErrorFor(part.input.signal));
+                continue;
+            }
+            runnable.push(part);
+        }
+        if (runnable.length === 0) {
+            return undefined;
+        }
+        const keys = runnable.flatMap((part) => (part.input.idempotencyKey !== undefined ? [part.input.idempotencyKey] : []));
+        const items = liveWorkItems.get(sessionId);
+        for (const key of keys) {
+            const item = items?.get(key);
+            if (item !== undefined) {
+                item.confirmed = true;
+            }
+        }
+        into.push(...runnable);
+        const labelled = runnable.some((part) => part.input.metadata !== undefined && SENDER_TRUST_METADATA_KEY in part.input.metadata);
+        const lowest = leastTrusted(...runnable.map((part) => senderTrustOf(part.input.metadata)));
+        const images = runnable.flatMap((part) => part.input.images ?? []);
+        log(`${sessionId}: ${runnable.length} message(s) sent during the running turn reached it at its next step`);
+        return {
+            userMessage: runnable.map((part) => part.input.userMessage).join(MERGED_SEPARATOR),
+            ...(images.length > 0 ? { images } : {}),
+            ...(labelled ? { metadata: { [SENDER_TRUST_METADATA_KEY]: lowest } } : {}),
+            ...(keys.length > 0 ? { keys } : {}),
+        };
+    };
     /**
      * Settles a keyed item the last process left unfinished before any other
      * message joins its session. Channels are up before the sweeps reach it,
@@ -3431,7 +3631,7 @@ export const createGateway = (options = {}) => {
      */
     const settleOrphanedItem = async (sessionId) => {
         const session = await store.get(sessionId);
-        const key = session?.messages.findLast((candidate) => candidate.role === 'user')?.idempotencyKey;
+        const key = session === undefined ? undefined : turnKeyOf(turnMessageOf(session));
         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.
@@ -3462,9 +3662,18 @@ export const createGateway = (options = {}) => {
      * stops that, and it only holds if everything that writes a session goes
      * through it.
      */
-    const onSessionChain = (sessionId, work) => {
+    const onSessionChain = (sessionId, work, 
+    /** True once this work no longer counts as queued: a batch steered into the turn ahead (`takeSteered` released it). */
+    released) => {
         const previous = sessionChains.get(sessionId) ?? Promise.resolve();
-        const turn = previous.then(work, work);
+        queuedWork.set(sessionId, (queuedWork.get(sessionId) ?? 0) + 1);
+        const start = () => {
+            if (released?.() !== true) {
+                releaseQueued(sessionId);
+            }
+            return work();
+        };
+        const turn = previous.then(start, start);
         const settled = turn.catch(() => { });
         sessionChains.set(sessionId, settled);
         inflight.add(settled);
@@ -3476,6 +3685,88 @@ export const createGateway = (options = {}) => {
         });
         return turn;
     };
+    // ---- memory passes (spec 962) -------------------------------------------
+    /**
+     * A pass's one model turn: the agent's provider and credentials, exactly
+     * the model asked for and never the fallback (cost stays what the
+     * operator chose), only the pass's two tools, no persona, skills, memory
+     * injection or delegates, and a session that is never stored. Its calls
+     * go through the same provider-call guards as every turn, and its events
+     * through the same bus, so a budget sees and counts them.
+     */
+    const runMemoryPassModel = async (run) => {
+        const source = await refreshAgent(run.agentId);
+        const resolved = await runtimeForAgent(source);
+        const { fallback: _fallback, ...primary } = resolved;
+        const config = (run.model !== undefined ? { ...primary, model: run.model } : primary);
+        const tools = new ToolRegistry();
+        for (const tool of run.tools) {
+            tools.register(tool);
+        }
+        // A step budget of n is n tool steps and one wrap-up, so this is the
+        // pass's model-call cap.
+        const maxTurns = MEMORY_PASS_MAX_MODEL_CALLS - 1;
+        let passRunner;
+        const provider = createRuntimeProvider(config, () => { }, async (session, call, context) => {
+            if (!passRunner) {
+                throw new Error('The Stratus runtime is not ready to execute tools yet.');
+            }
+            return passRunner.executeHostedToolCall(session, call, context);
+        }, maxTurns, async () => { }, providerContributions);
+        passRunner = new AgentRunner({
+            provider,
+            tools,
+            store: new InMemorySessionStore(),
+            bus,
+            maxTurns,
+            providerCallGuards,
+        });
+        const definition = {
+            id: source.definition.id,
+            name: source.definition.name,
+            instructions: MEMORY_PASS_RULES,
+            tools: run.tools.map((tool) => tool.name),
+            skills: [],
+            delegates: [],
+            ...(source.definition.credentials !== undefined ? { credentials: [...source.definition.credentials] } : {}),
+        };
+        await passRunner.run({
+            sessionId: run.sessionId,
+            agent: definition,
+            userMessage: run.prompt,
+            metadata: {
+                provider: config.provider,
+                ...(config.provider !== 'demo' && config.model !== undefined ? { model: config.model } : {}),
+                // The slice's label: the pass reads at the conversation's trust.
+                [SENDER_TRUST_METADATA_KEY]: run.trust,
+            },
+            signal: run.signal,
+        });
+    };
+    const memoryPassHost = createMemoryPassHost({
+        // Beside each agent's memory.jsonl, under the home the memory store uses.
+        stateDir: stratusHomePath(env),
+        stateHome: stratusHomePath(env),
+        run: randomUUID(),
+        memory,
+        supersedesMany: () => selectedMemorySupersedesMany,
+        sessions: store,
+        chain: {
+            idle: (sessionId) => !sessionChains.has(sessionId),
+            queue: (sessionId, work) => onSessionChain(sessionId, work),
+        },
+        hasAgent: (agentId) => sources.has(agentId),
+        isSubAgentSession: (session) => isSubAgentSession(session),
+        defaultModel: async (agentId) => {
+            const config = await runtimeForAgent(await refreshAgent(agentId));
+            return config.provider !== 'demo' ? config.model : undefined;
+        },
+        runModel: runMemoryPassModel,
+        emit: (event) => {
+            void bus.emit(event);
+        },
+        log,
+    });
     /**
      * A scheduled firing's own dispatch — single-flight and stopping-aware
      * like the public one, but permitted into the reserved `schedule:`
@@ -3673,7 +3964,16 @@ export const createGateway = (options = {}) => {
         // Otherwise it leads a new batch, if it is waiting behind a turn at all:
         // a message to an idle session runs at once, alone.
         const batch = mergeable && sessionChains.has(input.sessionId)
-            ? { agentId: input.agentId, absorbed: [], images: [...(input.images ?? [])], chars: input.userMessage.length }
+            ? {
+                agentId: input.agentId,
+                // Settled through `settleLeader`, read when called: it is assigned below.
+                leader: { input, resolve: (session) => settleLeader({ session }), reject: (error) => settleLeader({ error }) },
+                firstInLine: (queuedWork.get(input.sessionId) ?? 0) === 0,
+                absorbed: [],
+                steered: false,
+                images: [...(input.images ?? [])],
+                chars: input.userMessage.length,
+            }
             : undefined;
         if (batch !== undefined) {
             openBatches.set(input.sessionId, batch);
@@ -3763,6 +4063,7 @@ export const createGateway = (options = {}) => {
                 ...(head.input.agentId !== undefined ? { agentId: head.input.agentId } : {}),
                 userMessage: runnable.map((part) => part.input.userMessage).join(MERGED_SEPARATOR),
                 ...(images.length > 0 ? { images } : {}),
+                ...(runnable.every((part) => part.input.replyOptional === true) ? { replyOptional: true } : {}),
                 ...(head.input.earlier !== undefined ? { earlier: head.input.earlier } : {}),
                 ...(metadata !== undefined ? { metadata } : {}),
                 ...(signal !== undefined ? { signal } : {}),
@@ -3775,7 +4076,7 @@ export const createGateway = (options = {}) => {
                 activeTurns.set(input.sessionId, merged.turnId);
             }
             try {
-                outcome = { session: await dispatchInternal(merged, absorbedKeys) };
+                outcome = { session: await runSteerable(merged, absorbedKeys) };
             }
             catch (error) {
                 outcome = { error };
@@ -3809,7 +4110,65 @@ export const createGateway = (options = {}) => {
             settleLeader = (outcome) => ('error' in outcome ? reject(outcome.error) : resolve(outcome.session));
         });
         waitingDispatches.set(input.sessionId, (waitingDispatches.get(input.sessionId) ?? 0) + 1);
+        /**
+         * Runs this dispatch's turn, handing it whatever queues behind it at
+         * each tool step (`takeSteered`), then settles every dispatch it took
+         * with the turn's outcome — the outcome they joined. Only for a caller
+         * that opted into merged turns: it is the one that renders an answer
+         * covering messages other than its own.
+         */
+        const runSteerable = async (turnInput, absorbedKeys = []) => {
+            const steered = [];
+            // Cancelled only when every caller in it is, as a merged turn is, the
+            // ones steered in later included: one caller giving up must not take
+            // the others' answer with it. A turn with a caller who cannot cancel
+            // has no signal to join.
+            const joint = turnInput.signal !== undefined ? joinableSignal([turnInput.signal]) : undefined;
+            // Admitted on the turn's own signal, not only the callers' joint one:
+            // the watchdog, `abortTurns` and a restart's window stop the turn
+            // without touching its callers, and a batch taken into a turn stopped
+            // while the store was read would share its failure instead of running
+            // next (card 959). The turn's signal follows the joint one, so this
+            // covers every caller giving up too.
+            const steer = mergeable
+                ? (turnSignal) => takeSteered(input.sessionId, input.agentId, steered, (parts) => {
+                    if (turnSignal.aborted) {
+                        return false;
+                    }
+                    for (const part of parts) {
+                        joint?.join(part.input.signal);
+                    }
+                    return true;
+                })
+                : undefined;
+            const running = joint !== undefined ? { ...turnInput, signal: joint.signal } : turnInput;
+            let outcome;
+            try {
+                outcome = { session: await dispatchInternal(running, absorbedKeys, undefined, steer) };
+            }
+            catch (error) {
+                outcome = { error };
+            }
+            for (const part of steered) {
+                part.input.onAbsorbed?.();
+                if ('session' in outcome) {
+                    part.resolve(outcome.session);
+                }
+                else {
+                    part.reject(outcome.error);
+                }
+            }
+            if ('error' in outcome) {
+                throw outcome.error;
+            }
+            return outcome.session;
+        };
         const chained = onSessionChain(input.sessionId, async () => {
+            // Steered into the turn that ran ahead of it, which has answered and
+            // settled everyone in the batch already — this caller included.
+            if (batch?.steered === true) {
+                return turn;
+            }
             // The batch closes here: anything arriving from now on waits behind
             // this turn and leads the next one.
             if (batch !== undefined && openBatches.get(input.sessionId) === batch) {
@@ -3844,11 +4203,11 @@ export const createGateway = (options = {}) => {
             }
             await settleOrphanedItem(input.sessionId);
             if (turnId === undefined) {
-                return dispatchInternal(input);
+                return runSteerable(input);
             }
             activeTurns.set(input.sessionId, turnId);
             try {
-                return await dispatchInternal(input);
+                return await runSteerable(input);
             }
             finally {
                 // Unconditional, and safe to be: the chain guarantees no other turn
@@ -3856,7 +4215,7 @@ export const createGateway = (options = {}) => {
                 // only ever be clearing its own entry.
                 activeTurns.delete(input.sessionId);
             }
-        });
+        }, () => batch?.steered === true);
         // A second settle (a leader already settled early) is a no-op.
         chained.then((session) => settleLeader({ session }), (error) => settleLeader({ error }));
         if (idempotencyKey !== undefined) {
@@ -3979,6 +4338,7 @@ export const createGateway = (options = {}) => {
             log,
             warn,
             subAgents,
+            memoryPasses: memoryPassHost.handle,
             // Metadata only, from the reads the control API makes, with a log
             // line per read naming the plugin. See `createFleetReader`.
             fleet: (packageName) => createFleetReader({
@@ -4078,6 +4438,7 @@ export const createGateway = (options = {}) => {
                     + `. Enable the plugin that contributes it, or set memoryStore to ${BUILTIN_MEMORY_STORE_NAME}.`);
             }
             selectedMemory = contribution.store;
+            selectedMemorySupersedesMany = contribution.supersedesMany === true;
             log(`memory store ${memoryName} selected, from ${contributorOf('memory', memoryName) ?? 'a plugin'}`);
         }
     };
@@ -4149,6 +4510,10 @@ export const createGateway = (options = {}) => {
                 + `${reconciled.released.length} claim(s) released`);
         }
         await loadRoster();
+        // Agents loaded and the memory store chosen: a plugin that turned memory
+        // passes on in its setup had neither, so the claims a crash left open
+        // are settled now, before any turn can end and ask for a pass.
+        await memoryPassHost.ready();
         intakeState = await readIntakeState(env, warn);
         if (intakeState.paused) {
             log(`intake is paused (since ${intakeState.since ?? 'unknown'}); new work will be refused until it resumes`);
@@ -4392,6 +4757,12 @@ export const createGateway = (options = {}) => {
         // already past its `stopping` check loses to `dispatch`'s own
         // refusal — the second gate is why this needs no handshake.
         scheduler.stop();
+        // Memory passes are low priority: aborted at once rather than drained,
+        // settled from what they wrote, then the stop records. Awaited before
+        // the stores close, since a settle reads the memory store.
+        const passesClosed = memoryPassHost.close().catch((error) => {
+            warn(`memory passes did not close cleanly: ${error instanceof Error ? error.message : String(error)}`);
+        });
         // 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
@@ -4430,6 +4801,7 @@ export const createGateway = (options = {}) => {
             return channelsStopping;
         };
         const drain = (async () => {
+            await passesClosed;
             // A promotion still connecting channels finishes first, so every
             // channel it started is in the list stopped below; seeing `stopping`,
             // it starts nothing after that.
@@ -4852,6 +5224,12 @@ export const createGateway = (options = {}) => {
         eventDeliveries(options = {}) {
             return eventStore?.deliveries(options) ?? [];
         },
+        memoryPasses(agentId) {
+            return memoryPassHost.passes(agentId);
+        },
+        memoryPass(agentId, passId) {
+            return memoryPassHost.pass(agentId, passId);
+        },
         tools() {
             // From the registry, not from the load records: the risk reported is
             // the one a call will actually be judged at, floor applied, and a