@stratusagent/gateway 0.12.0 → 0.12.2

package/dist/index.js

@@ -9,7 +9,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { createHash, randomBytes, randomUUID } from 'node:crypto';
 import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-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, matchesToolAllowlist, } from '@stratusagent/core';
+import { filePathsOf, isUnaddressedTurn, carriesKey, leastTrusted, senderTrustOf, SENDER_TRUST_METADATA_KEY, 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, imagesWithinReplayBudget, matchesToolAllowlist, } from '@stratusagent/core';
 import { CREDENTIAL_REQUEST_TOOL_NAME, createCredentialRequestTool, createDelegateTool, createForgetTool, createPinTool, createMessageSendTool, createMessageReadTool, 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";
@@ -44,12 +44,23 @@ const MAX_TIMER_DELAY_MS = 2_147_483_647;
 export { applySoulPins } from '@stratusagent/state';
 /** What a turn cut short by an announced restart records as its failure. */
 export const RESTARTING_TURN_ERROR = 'Run aborted: stratusd is restarting';
+/** The error a turn still running when a stop's drain window closes is aborted with. */
+export const STOPPING_TURN_ERROR = 'Run aborted: stratusd is stopping';
 /**
  * How long an announced restart lets in-flight turns finish before aborting
- * them. Matches the systemd unit's `TimeoutStopSec`, so the two windows an
- * operator can hit agree.
+ * them. The same as a stop's window (`DEFAULT_STOP_DRAIN_TIMEOUT_MS`), so the
+ * two windows an operator can hit agree.
  */
 export const DEFAULT_RESTART_DRAIN_TIMEOUT_MS = 30_000;
+/**
+ * How long a stop lets in-flight turns finish before aborting them. The
+ * daemon's documented drain ("up to 30 seconds"), and shorter than the
+ * service units' stop timeouts, so the abort happens in this process
+ * rather than as the manager's SIGKILL. That matters beyond the turn's
+ * record: a shell command runs in its own process group, which launchd's
+ * kill of the job does not reach, so only the turn's abort stops it.
+ */
+export const DEFAULT_STOP_DRAIN_TIMEOUT_MS = 30_000;
 /** What a paused daemon says when nobody gave it a sentence of its own. */
 export const DEFAULT_PAUSED_MESSAGE = "I'm paused right now and not taking new work. Please try again later.";
 /** What a held gateway answers a dispatch with, before it is promoted. */
@@ -148,6 +159,38 @@ export class RestartUnsupportedError extends Error {
         this.name = 'RestartUnsupportedError';
     }
 }
+/**
+ * The most text one merged user message may hold (card 423). The runner's
+ * overflow recovery can drop earlier transcript but never part of the
+ * newest message, so a batch must not grow that message past what one
+ * message could be on its own: this is Slack's own message-length limit.
+ * A single message longer than this still runs, alone, as it would have
+ * without merging.
+ */
+const MERGED_TEXT_BUDGET_CHARS = 40_000;
+/** Separator between merged messages; counted against the text budget. */
+const MERGED_SEPARATOR = '\n\n';
+/**
+ * Whether `images` all fit the replay budget together. A merged turn's
+ * images are one message's, and the runner empties whatever falls outside
+ * the budget before the provider sees it, so a batch that would overflow
+ * must not take the message that overflows it (card 423).
+ */
+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 controller = new AbortController();
+    const check = () => {
+        if (!controller.signal.aborted && signals.every((signal) => signal.aborted)) {
+            controller.abort(signals[signals.length - 1]?.reason);
+        }
+    };
+    for (const signal of signals) {
+        signal.addEventListener('abort', check, { once: true });
+    }
+    check();
+    return controller.signal;
+};
 /**
  * Recorded on a turn the previous process was still running when it died.
  *
@@ -1562,8 +1605,8 @@ export const createGateway = (options = {}) => {
             // announced restart must be able to cut short at the window.
             const idle = new AbortController();
             turnControllers.add(idle);
-            if (abortingTurns) {
-                idle.abort(new RunAbortedError(RESTARTING_TURN_ERROR));
+            if (abortingWith !== undefined) {
+                idle.abort(new RunAbortedError(abortingWith));
             }
             try {
                 return await run(idle.signal);
@@ -1574,8 +1617,8 @@ export const createGateway = (options = {}) => {
         }
         const controller = new AbortController();
         turnControllers.add(controller);
-        if (abortingTurns) {
-            controller.abort(new RunAbortedError(RESTARTING_TURN_ERROR));
+        if (abortingWith !== undefined) {
+            controller.abort(new RunAbortedError(abortingWith));
         }
         // The external reason travels: a caller that aborted with its own
         // `RunAbortedError` gets it recorded on the session, like the watchdog's.
@@ -1773,14 +1816,15 @@ export const createGateway = (options = {}) => {
      */
     const turnControllers = new Set();
     /**
-     * Set once a restart's window has closed and the turns in it were
-     * aborted. A turn that starts after that — one queued behind the
-     * aborted turn on the same session, accepted before the announcement —
-     * is aborted the moment it gets its controller, with the same reason,
-     * rather than running unseen until the shutdown closes the store under
-     * it and leaves it recorded as nothing at all.
+     * Set once a restart's or a stop's window has closed and the turns in it
+     * were aborted, to the reason they were aborted with. A turn that starts
+     * after that — one queued behind the aborted turn on the same session,
+     * accepted before the announcement — is aborted the moment it gets its
+     * controller, with the same reason, rather than running unseen until the
+     * shutdown closes the store under it and leaves it recorded as nothing
+     * at all.
      */
-    let abortingTurns = false;
+    let abortingWith;
     /**
      * Set once `start()` has finished. A restart before that would stop the
      * channels started so far and close the stores while the rest of
@@ -1819,6 +1863,13 @@ export const createGateway = (options = {}) => {
     // 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 merged turn still taking messages, per session (card 423): led by
+     * the first opted-in dispatch that queued behind a running turn, closed
+     * the moment that dispatch reaches the head of the chain. See
+     * `DispatchInput.onAbsorbed`.
+     */
+    const openBatches = new Map();
     /** The start-up snapshot `recoverParkedTurns` judges orphans from, for a repeat that gets there first. */
     let orphanedAtStart = new Set();
     /**
@@ -1918,7 +1969,7 @@ export const createGateway = (options = {}) => {
             ? runsOnHarness(fallback)
             : runsOnHarness(config) || (fallback !== undefined && runsOnHarness(fallback));
     };
-    const dispatchInternal = async (input) => {
+    const dispatchInternal = async (input, absorbedKeys = []) => {
         // 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
@@ -2028,6 +2079,7 @@ export const createGateway = (options = {}) => {
                     ...(input.images !== undefined ? { images: input.images } : {}),
                     ...(input.addressed !== undefined ? { addressed: input.addressed } : {}),
                     ...(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),
@@ -2041,6 +2093,7 @@ export const createGateway = (options = {}) => {
                 ...(input.images !== undefined ? { images: input.images } : {}),
                 ...(input.addressed !== undefined ? { addressed: input.addressed } : {}),
                 ...(input.idempotencyKey !== undefined ? { idempotencyKey: input.idempotencyKey } : {}),
+                ...(absorbedKeys.length > 0 ? { absorbedKeys: [...absorbedKeys] } : {}),
                 ...(hostedLoop ? { hostedLoop } : {}),
                 ...(input.earlier !== undefined && input.earlier.length > 0 ? { earlier: input.earlier } : {}),
                 metadata,
@@ -2200,8 +2253,8 @@ export const createGateway = (options = {}) => {
             // reports undrained for a turn it could have finished cleanly.
             const controller = new AbortController();
             turnControllers.add(controller);
-            if (abortingTurns) {
-                controller.abort(new RunAbortedError(RESTARTING_TURN_ERROR));
+            if (abortingWith !== undefined) {
+                controller.abort(new RunAbortedError(abortingWith));
             }
             try {
                 await runner.recoverPendingApproval(sessionId, {
@@ -2684,6 +2737,55 @@ export const createGateway = (options = {}) => {
             };
             return attach();
         }
+        // Merged turns (card 423): an opted-in message behind a running turn
+        // joins the batch already waiting, if there is one for the same agent.
+        const mergeable = input.onAbsorbed !== undefined && input.addressed !== false;
+        const open = openBatches.get(input.sessionId);
+        if (mergeable &&
+            open !== undefined &&
+            open.agentId === input.agentId &&
+            fitsReplayBudget([...open.images, ...(input.images ?? [])]) &&
+            open.chars + MERGED_SEPARATOR.length + input.userMessage.length <= MERGED_TEXT_BUDGET_CHARS) {
+            open.images.push(...(input.images ?? []));
+            open.chars += MERGED_SEPARATOR.length + input.userMessage.length;
+            waitingDispatches.set(input.sessionId, (waitingDispatches.get(input.sessionId) ?? 0) + 1);
+            const joined = new Promise((resolve, reject) => {
+                open.absorbed.push({ input, resolve, reject });
+            });
+            if (idempotencyKey !== undefined) {
+                // Provisional, like a queued dispatch's: a redelivery while it waits
+                // attaches here; the merged turn confirms it once it owns the key.
+                const items = liveWorkItems.get(input.sessionId) ?? new Map();
+                if (!items.has(idempotencyKey)) {
+                    items.set(idempotencyKey, { turn: joined, agentId: input.agentId, confirmed: false, addressed: true });
+                    liveWorkItems.set(input.sessionId, items);
+                }
+                void joined.catch(() => { }).finally(() => {
+                    const current = liveWorkItems.get(input.sessionId);
+                    if (current?.get(idempotencyKey)?.turn === joined) {
+                        current.delete(idempotencyKey);
+                        if (current.size === 0) {
+                            liveWorkItems.delete(input.sessionId);
+                        }
+                    }
+                });
+            }
+            return joined;
+        }
+        // It cannot join (or its images or text would overflow the batch's
+        // budget), so the open batch takes no more: a message arriving
+        // after this one must not be answered ahead of it.
+        if (open !== undefined) {
+            openBatches.delete(input.sessionId);
+        }
+        // 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 }
+            : undefined;
+        if (batch !== undefined) {
+            openBatches.set(input.sessionId, batch);
+        }
         // 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) => {
@@ -2691,16 +2793,149 @@ export const createGateway = (options = {}) => {
             items.set(key, { turn, agentId: input.agentId, confirmed, addressed: input.addressed !== false });
             liveWorkItems.set(input.sessionId, items);
         };
+        /**
+         * This dispatch's turn with the messages it absorbed (card 423). Each
+         * part is judged on its own first, as it would have been alone: one
+         * cancelled while it waited is refused, one that repeats a turn the
+         * session already holds is that turn. What is left runs as one turn.
+         */
+        const runMerged = async (absorbed) => {
+            const parts = [{ input }, ...absorbed.map((joiner) => ({ input: joiner.input, joiner }))];
+            let leader;
+            const settle = (part, outcome) => {
+                if (part.joiner === undefined) {
+                    // Settled the moment it is known, not when the chain moves on: a
+                    // leader cancelled or repeated while it waited must leave its
+                    // caller's queue before the turn it handed over starts rendering.
+                    leader = outcome;
+                    settleLeader(outcome);
+                }
+                else if ('session' in outcome) {
+                    part.joiner.resolve(outcome.session);
+                }
+                else {
+                    part.joiner.reject(outcome.error);
+                }
+            };
+            const runnable = [];
+            for (const part of parts) {
+                const own = part.input;
+                if (own.signal?.aborted) {
+                    settle(part, { error: abortErrorFor(own.signal) });
+                    continue;
+                }
+                if (own.idempotencyKey !== undefined) {
+                    try {
+                        const repeated = await settleRepeat(input.sessionId, own.idempotencyKey, own.agentId, own.turnId, own.onRepeat);
+                        if (repeated !== undefined) {
+                            settle(part, { session: repeated });
+                            continue;
+                        }
+                    }
+                    catch (error) {
+                        settle(part, { error });
+                        continue;
+                    }
+                }
+                runnable.push(part);
+            }
+            const head = runnable[0];
+            if (head === undefined) {
+                return finish(leader);
+            }
+            // Every runnable key now belongs to this turn.
+            const keys = runnable.flatMap((part) => (part.input.idempotencyKey !== undefined ? [part.input.idempotencyKey] : []));
+            const items = liveWorkItems.get(input.sessionId);
+            for (const key of keys) {
+                const item = items?.get(key);
+                if (item !== undefined) {
+                    item.confirmed = true;
+                }
+            }
+            // The turn runs at the least trusted sender in it: everyone's words
+            // are in its one message.
+            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 newest = runnable[runnable.length - 1].input;
+            const metadata = labelled ? { ...newest.metadata, [SENDER_TRUST_METADATA_KEY]: lowest } : newest.metadata;
+            const images = runnable.flatMap((part) => part.input.images ?? []);
+            const signals = runnable.map((part) => part.input.signal);
+            // Cancelled only when every caller in it is: one caller giving up
+            // must not take the others' answer with it.
+            const signal = signals.every((candidate) => candidate !== undefined)
+                ? allAborted(signals)
+                : undefined;
+            const [primaryKey, ...absorbedKeys] = keys;
+            const merged = {
+                sessionId: input.sessionId,
+                ...(head.input.agentId !== undefined ? { agentId: head.input.agentId } : {}),
+                userMessage: runnable.map((part) => part.input.userMessage).join(MERGED_SEPARATOR),
+                ...(images.length > 0 ? { images } : {}),
+                ...(head.input.earlier !== undefined ? { earlier: head.input.earlier } : {}),
+                ...(metadata !== undefined ? { metadata } : {}),
+                ...(signal !== undefined ? { signal } : {}),
+                ...(head.input.turnId !== undefined ? { turnId: head.input.turnId } : {}),
+                ...(primaryKey !== undefined ? { idempotencyKey: primaryKey } : {}),
+            };
+            await settleOrphanedItem(input.sessionId);
+            let outcome;
+            if (merged.turnId !== undefined) {
+                activeTurns.set(input.sessionId, merged.turnId);
+            }
+            try {
+                outcome = { session: await dispatchInternal(merged, absorbedKeys) };
+            }
+            catch (error) {
+                outcome = { error };
+            }
+            finally {
+                if (merged.turnId !== undefined) {
+                    activeTurns.delete(input.sessionId);
+                }
+            }
+            for (const part of runnable) {
+                if (part !== head) {
+                    part.input.onAbsorbed?.();
+                }
+                settle(part, outcome);
+            }
+            return finish(leader);
+        };
+        const finish = (outcome) => {
+            if (outcome === undefined) {
+                throw new Error('A merged turn settled without an outcome for its leader.');
+            }
+            if ('error' in outcome) {
+                throw outcome.error;
+            }
+            return outcome.session;
+        };
+        // What this caller is handed. It follows the chain's work, except that a
+        // batch leader settles it early (`settle` in `runMerged`).
+        let settleLeader = () => { };
+        const turn = new Promise((resolve, reject) => {
+            settleLeader = (outcome) => ('error' in outcome ? reject(outcome.error) : resolve(outcome.session));
+        });
         waitingDispatches.set(input.sessionId, (waitingDispatches.get(input.sessionId) ?? 0) + 1);
-        const turn = onSessionChain(input.sessionId, async () => {
-            // No longer waiting once it reaches the head of the chain.
-            const left = (waitingDispatches.get(input.sessionId) ?? 1) - 1;
+        const chained = onSessionChain(input.sessionId, async () => {
+            // 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) {
+                openBatches.delete(input.sessionId);
+            }
+            const absorbed = batch?.absorbed ?? [];
+            // No longer waiting once it reaches the head of the chain — nor is
+            // anything it absorbed.
+            const left = (waitingDispatches.get(input.sessionId) ?? 1) - 1 - absorbed.length;
             if (left > 0) {
                 waitingDispatches.set(input.sessionId, left);
             }
             else {
                 waitingDispatches.delete(input.sessionId);
             }
+            if (absorbed.length > 0) {
+                return runMerged(absorbed);
+            }
             // 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;
@@ -2730,6 +2965,8 @@ export const createGateway = (options = {}) => {
                 activeTurns.delete(input.sessionId);
             }
         });
+        // A second settle (a leader already settled early) is a no-op.
+        chained.then((session) => settleLeader({ session }), (error) => settleLeader({ error }));
         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.
@@ -2765,6 +3002,10 @@ 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 an observe. Reserved keys: ${RESERVED_SESSION_METADATA_KEYS.join(', ')}.`);
         }
+        // Heard after the batch waiting on this session opened, so anything
+        // said after it must not be answered ahead of it: the batch takes no
+        // more, and a later message leads the next one (card 423).
+        openBatches.delete(input.sessionId);
         return onSessionChain(input.sessionId, async () => {
             assertStateCompatible(env);
             const existing = await store.get(input.sessionId);
@@ -3108,6 +3349,15 @@ export const createGateway = (options = {}) => {
             deferredStart = undefined;
             heldState = false;
             log('stratusd promoted: channels connected, schedules running');
+            if (options.onPromoted) {
+                // Synchronous throws too: the promotion has happened either way.
+                try {
+                    await options.onPromoted();
+                }
+                catch (error) {
+                    warn(`recording the promotion failed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
         })().finally(() => {
             promoting = undefined;
         });
@@ -3158,11 +3408,14 @@ export const createGateway = (options = {}) => {
      * The one shutdown sequence — for a stop, for a restart, and for a
      * start() that failed, whose caller never reaches stop().
      *
-     * `abortAfterMs` is the difference: a stop waits for every in-flight
-     * turn however long it takes (the service manager's own timeout is the
-     * bound there), while a restart waits that long and then aborts what is
-     * still running, so the daemon can come back instead of waiting on one
-     * stuck turn. Resolves with whether everything finished — after an abort,
+     * `abortAfterMs` is how long in-flight turns get before what is still
+     * running is aborted, with `kind` as the reason: a restart so the daemon
+     * can come back instead of waiting on one stuck turn, a stop so the
+     * abort happens here and not as the service manager's SIGKILL, which
+     * would leave the turn unrecorded and its shell commands' process groups
+     * running after the daemon. Undefined waits however long it takes: only
+     * a start() that failed, whose turns are the few a channel accepted in
+     * the moment before. Resolves with whether everything finished — after an abort,
      * a turn that still ignores its signal for a second window is shut down
      * around, and the host is told so it can exit rather than start a new
      * daemon beside it. Every wait after the window opens is bounded by it,
@@ -3170,7 +3423,7 @@ export const createGateway = (options = {}) => {
      * the turn drain gave up on, and an unbounded wait there would hold the
      * restart forever on exactly the turn the window exists for.
      */
-    const shutdown = async (abortAfterMs) => {
+    const shutdown = async (abortAfterMs, kind = 'restart') => {
         // Refuse new work first; then let channels finish rendering their
         // in-flight turns (already-started dispatches keep running), drain,
         // and close.
@@ -3216,6 +3469,14 @@ export const createGateway = (options = {}) => {
             startedChannels.length = 0;
             await Promise.allSettled([...inflight]);
         })();
+        // One deadline for the whole bounded shutdown: the drain window, then
+        // one more window that everything after it shares (the aborted turns'
+        // record, the scheduler's drain, the plugins' dispose). A service
+        // manager's stop timeout is sized for exactly that (see the CLI's
+        // SERVICE_STOP_TIMEOUT_SECONDS); a window per phase would add up past
+        // it and land its SIGKILL mid-cleanup.
+        const deadline = abortAfterMs === undefined ? undefined : Date.now() + 2 * abortAfterMs;
+        const remaining = () => deadline === undefined || abortAfterMs === undefined ? 0 : Math.min(abortAfterMs, Math.max(0, deadline - Date.now()));
         let drained = true;
         if (abortAfterMs === undefined) {
             await drain;
@@ -3224,19 +3485,19 @@ export const createGateway = (options = {}) => {
             drained = channelsReleased;
         }
         else {
-            warn(`restart: ${inflight.size} turn(s) still running after ${abortAfterMs}ms; aborting them`);
+            warn(`${kind}: ${inflight.size} turn(s) still running after ${abortAfterMs}ms; aborting them`);
             // The watchdog's own mechanism: the runner fails each session with
             // the reason on the signal, saves it, and emits session.failed —
             // so the next daemon finds a finished turn, not an abandoned one.
             // Before the loop, so a turn queued behind one aborted here, which
             // starts as soon as that one settles, is aborted the same way.
-            abortingTurns = true;
+            abortingWith = kind === 'stop' ? STOPPING_TURN_ERROR : RESTARTING_TURN_ERROR;
             for (const controller of turnControllers) {
-                controller.abort(new RunAbortedError(RESTARTING_TURN_ERROR));
+                controller.abort(new RunAbortedError(abortingWith));
             }
-            drained = await settlesWithin(drain, abortAfterMs);
+            drained = await settlesWithin(drain, remaining());
             if (!drained) {
-                warn(`restart: ${inflight.size} turn(s) did not stop after being aborted; shutting down around them`);
+                warn(`${kind}: ${inflight.size} turn(s) did not stop after being aborted; shutting down around them`);
             }
             drained = drained && channelsReleased;
         }
@@ -3249,8 +3510,8 @@ export const createGateway = (options = {}) => {
         if (drained || abortAfterMs === undefined) {
             await schedulerDrain;
         }
-        else if (!(await settlesWithin(schedulerDrain, abortAfterMs))) {
-            warn('restart: a scheduled firing did not stop after being aborted; shutting down around it');
+        else if (!(await settlesWithin(schedulerDrain, remaining()))) {
+            warn(`${kind}: a scheduled firing did not stop after being aborted; shutting down around it`);
         }
         // After the turns that might still be using them. A plugin holding a
         // browser is the reason this exists, and closing it out from under a
@@ -3260,16 +3521,17 @@ export const createGateway = (options = {}) => {
         // coming back, and a plugin still holding on is one more thing the
         // host should not start a new daemon beside.
         const disposal = disposePlugins();
+        const disposalWindow = remaining();
         if (abortAfterMs === undefined) {
             await disposal;
         }
-        else if (await settlesWithin(disposal, abortAfterMs)) {
+        else if (await settlesWithin(disposal, disposalWindow)) {
             // A dispose that rejected has already been named; what it may still
             // hold is the same problem as one that never answered.
             drained = drained && await disposal;
         }
         else {
-            warn(`restart: a plugin did not release what it holds within ${abortAfterMs}ms; shutting down around it`);
+            warn(`${kind}: a plugin did not release what it holds within ${disposalWindow}ms; shutting down around it`);
             drained = false;
         }
         closeStores();
@@ -3316,14 +3578,25 @@ export const createGateway = (options = {}) => {
             }
             serving = true;
         },
-        // Drain: channels stop taking messages, in-flight turns finish, new
-        // dispatches are refused, then the database closes. SIGTERM handling
-        // in `stratus serve` calls this. Idempotent: a restart stops the
-        // gateway itself before handing the process to the host, whose own
-        // shutdown path then calls this again and must find nothing to do —
-        // and a start() that failed has already run the same sequence.
+        // Drain: channels stop taking messages, in-flight turns get the stop
+        // window to finish and are aborted after it, new dispatches are
+        // refused, then the database closes. SIGTERM handling in `stratus
+        // serve` calls this. Idempotent: a restart stops the gateway itself
+        // before handing the process to the host, whose own shutdown path then
+        // calls this again and must find nothing to do — and a start() that
+        // failed has already run the same sequence.
         stop() {
-            stopped ??= shutdown(undefined).then(() => undefined);
+            if (stopped === undefined) {
+                const requested = options.stopDrainTimeoutMs ?? DEFAULT_STOP_DRAIN_TIMEOUT_MS;
+                // A stop cannot refuse to happen over its own setting, so a window
+                // that would misfire (negative, NaN, or past Node's timer limit,
+                // where setTimeout fires at once) falls back rather than throwing.
+                const usable = Number.isFinite(requested) && requested >= 0 && requested <= MAX_TIMER_DELAY_MS;
+                if (!usable) {
+                    warn(`stop drain window ${String(requested)}ms is not usable; using ${DEFAULT_STOP_DRAIN_TIMEOUT_MS}ms`);
+                }
+                stopped = shutdown(usable ? requested : DEFAULT_STOP_DRAIN_TIMEOUT_MS, 'stop').then(() => undefined);
+            }
             return stopped;
         },
         dispatch,
@@ -3343,7 +3616,7 @@ export const createGateway = (options = {}) => {
             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);
+            const keyed = transcript?.messages.findLast((message) => carriesKey(message, idempotencyKey));
             return keyed !== undefined && keyed.overheard !== true;
         },
         async sessionRouting(sessionId) {
@@ -3370,8 +3643,12 @@ export const createGateway = (options = {}) => {
             // said, for text and file alike, not what the channel delivered: a
             // post Slack refused or an upload that failed reads as spoken here.
             // The channel's own record has the delivery, and this is the
-            // reconstruction for a process that lost it; a delivery record
-            // written back into the session is the open item in roadmap 31.
+            // reconstruction for a process that lost it. Still open: a delivery
+            // record the channel writes back into the session would make this
+            // exact (a refused post, a failed upload, a line streamed into a
+            // placeholder by a process that died before saving its reply). It is
+            // a new gateway seam, and it has to be ordered against the overhears
+            // queued on the same session chain, so it is not built yet.
             const spoken = (message) => (message.role === 'assistant' && message.content.trim().length > 0)
                 || (message.role === 'tool' && message.toolResult !== undefined && filePathsOf(message.toolResult).length > 0);
             const spokeIndex = session.messages.findLastIndex(spoken);