@animalabs/agent-framework 0.22.0 → 0.22.1

package/dist/src/framework.js

@@ -1,6 +1,6 @@
 import { ToolPresentation, presentationTools, isPresentationTool, renderCatalogue } from "./tool-presentation.js";
 import { dirname, join } from 'node:path';
-import { INLINE_WITHHELD_TEXT, classifyBlock, isInlineContradiction, referenceRegistry, referenceStubOrNull } from './mcpl/references.js';
+import { EXPIRY_REASON, INLINE_WITHHELD_TEXT, REFERENCE_LIMITS, classifyBlock, isInlineContradiction, isReferenceExpired, referenceExpiry, referenceRegistry, referenceStubOrNull, referenceTypeLabel, sanitizeLabel } from './mcpl/references.js';
 import { ReferenceFetcher, DEFAULT_FETCH_MAX_BYTES, EAGER_FETCH_TIMEOUT_MS } from './mcpl/reference-fetcher.js';
 import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { JsStore } from '@animalabs/chronicle';
@@ -10,7 +10,7 @@ import { SUBCONSCIOUS_TOOLS, SUBCONSCIOUS_TOOL_NAMES } from './tune-out/tools.js
 import { TuneOutCoordinator, TUNE_OUT_DEFAULTS } from './tune-out/coordinator.js';
 import { ProcessQueueImpl } from './queue.js';
 import { DEFAULT_SHUTDOWN_TIMEOUT_MS, validateShutdownTimeout, shutdownErrorMessage } from './shutdown.js';
-import { REFUSAL_REACTIONS, REFUSAL_REACTION_FALLBACK } from './refusal-reactions.js';
+import { REFUSAL_REACTIONS, REFUSAL_REACTION_FALLBACK, REFUSAL_REACTION_BASELINE } from './refusal-reactions.js';
 import { Agent } from './agent.js';
 import { ModuleRegistry, checkedToolResult, isStateExistsError, storableToolResult, thrownResult } from './module-registry.js';
 import { McplServerRegistry } from './mcpl/server-registry.js';
@@ -31,6 +31,7 @@ import { InferenceRouter } from './mcpl/inference-router.js';
 import { ChannelRegistry } from './mcpl/channel-registry.js';
 import { ConversationRouter, CONVERSATION_ROUTING_DEPRECATION_NOTICE } from './mcpl/conversation-router.js';
 import { safeSlice } from './safe-slice.js';
+import { ProviderWaits, EVERY_MODEL, isReleaseModel, withoutControls } from './provider-waits.js';
 import { nonErrorResultText, toolResultDataToHistoryString, truncateForHistory, DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS, } from './tool-result-history.js';
 import { TOOL_IMAGE_REF_RE, ToolImageLedger, formatPreservedImageSlots, parseImagePlaceholders, sha256Hex, splitPreservingImageSlots, } from './tool-image-ledger.js';
 import { randomUUID, createHash } from 'node:crypto';
@@ -290,6 +291,7 @@ import { CheckpointManager } from './mcpl/checkpoint-manager.js';
 import { isToolAllowed } from './mcpl/tool-policy.js';
 import { EventGate, formatShadowWarning } from './gate/event-gate.js';
 import { UsageTracker } from './usage/usage-tracker.js';
+import { isWebSocketTransport } from './mcpl/transport.js';
 import { formatZonedDateTime, resolveTimeZone } from './timezone.js';
 import { DEFAULT_DISCORD_AWARENESS_EMOJI, DiscordAwarenessOutbox, defaultDiscordAwarenessOutboxPath, extractDiscordAwarenessRefs, } from './recovery/discord-awareness-outbox.js';
 import { OperatorActionError, OperatorLog, capIds, defaultOperatorLogPath, } from './operator-log.js';
@@ -361,6 +363,20 @@ const MAX_TURN_CHECKPOINTS = 20;
 const DEFAULT_DISCORD_AWARENESS_DEADLINE_MS = 10_000;
 const MIN_DISCORD_AWARENESS_DEADLINE_MS = 50;
 const MAX_DISCORD_AWARENESS_DEADLINE_MS = 60_000;
+/** Several drains' outcomes as one: unavailable only if every one was. */
+function combineDrainOutcomes(outcomes) {
+    if (outcomes.every((outcome) => outcome.status === 'unavailable')) {
+        return {
+            status: 'unavailable',
+            accounted: outcomes.reduce((count, outcome) => count + (outcome.status === 'unavailable' ? outcome.accounted : 0), 0),
+        };
+    }
+    return {
+        status: 'delivered',
+        delivered: outcomes.reduce((count, outcome) => count + (outcome.status === 'delivered' ? outcome.delivered : 0), 0),
+        failed: outcomes.reduce((count, outcome) => count + (outcome.status === 'delivered' ? outcome.failed : 0), 0),
+    };
+}
 function normalizeDiscordAwarenessDeadline(value) {
     if (value === undefined || !Number.isFinite(value) || value <= 0) {
         return DEFAULT_DISCORD_AWARENESS_DEADLINE_MS;
@@ -459,11 +475,35 @@ function bodyGroupRun(cm, index) {
         group: win.messages[0].bodyGroupId !== undefined,
     };
 }
+function describeMarkers(m) {
+    if (m.status === 'queued')
+        return `queued:${m.queued}`;
+    if (m.status === 'not-scheduled')
+        return 'not-scheduled(batch retired)';
+    if (m.status === 'unresolved')
+        return `unresolved(batch ${m.batchId} may still be delivered)`;
+    return 'none';
+}
 function describeRequester(r) {
     if (!r)
         return 'unknown';
     return `${r.name ?? r.id ?? 'unknown'} (${r.via})`;
 }
+/** What a held call or turn says of the wait that holds it: no call was
+ *  made. The refusal of an auxiliary call and the trace of a turn held once
+ *  compiled say it the same way. */
+function providerWaitText(agentName, model, wait) {
+    return `Provider wait: ${model} is held for ${agentName} ` +
+        `${wait.until === null ? 'until an operator releases it' : `until ${new Date(wait.until).toISOString()}`} ` +
+        `(recorded ${new Date(wait.setAt).toISOString()}: ${wait.reason}); no call was made`;
+}
+/** Who asked for an operator act, as a durable record and a log line carry
+ *  it. The name comes from a caller, so a control character (a forged log
+ *  line) becomes a space, and it is bounded. */
+function operatorLabel(by) {
+    const label = safeSlice(withoutControls(by).trim(), 0, 120);
+    return label === '' ? 'operator' : label;
+}
 function hostCommandRequester(serverId, params) {
     return {
         via: `host-command:${serverId}`,
@@ -490,11 +530,11 @@ function isPermanentDiscordReactionFailure(message) {
 class DefaultErrorPolicy {
     maxRetries = 3;
     onInferenceError(error, _agentName, attempt) {
-        if (error instanceof MembraneError && !error.retryable) {
+        if (isMembraneError(error) && error.retryable === false) {
             return { retry: false };
         }
         if (attempt < this.maxRetries) {
-            const delayMs = error instanceof MembraneError && error.retryAfterMs !== undefined
+            const delayMs = isMembraneError(error) && typeof error.retryAfterMs === 'number'
                 ? error.retryAfterMs
                 : Math.pow(2, attempt) * 1000;
             return { retry: true, delayMs };
@@ -513,10 +553,32 @@ const DEFAULT_MAINTENANCE_INTERVAL_MS = 5000;
 /** Bound one pass so a large backlog yields to inference and other agents. */
 const MAINTENANCE_TICKS_PER_PASS = 8;
 const PROVIDER_ACCELERATION_DEFAULT_COOLDOWN_MS = 65_000;
+/** Cap on waits the framework chooses itself. A provider's stated wait is
+ *  never capped: it is a lower bound (see ProviderWaits). It is also the
+ *  longest stated wait an ephemeral run sleeps in its turn: a longer one ends
+ *  the run instead (nonOwningProviderWait). */
 const PROVIDER_ACCELERATION_MAX_COOLDOWN_MS = 10 * 60_000;
 const PROVIDER_ACCELERATION_JITTER_MS = 5_000;
+/** Longest delay one setTimeout can represent (2^31-1 ms, about 24.8 days);
+ *  a longer timer fires almost at once, so longer waits re-arm in steps. */
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/** A stated wait recorded to hold a model longer than this, or until
+ *  released, raises an ops alert. It is honoured in full either way: a hold
+ *  that long is a quota-scale event or a provider's mistake, and a person
+ *  decides which (release-provider-wait). Shorter waits are pacing. */
+const PROVIDER_WAIT_ALERT_MS = 60 * 60_000;
+/**
+ * A MembraneError, from this framework's copy of membrane or from another: the
+ * host supplies the Membrane instance (config.membrane), so with two copies
+ * installed its errors are instances of a class this framework's `instanceof`
+ * doesn't match. Recognised by name as well, as context-manager's errors are;
+ * its fields are the same, so callers still check each one's type.
+ */
+function isMembraneError(error) {
+    return error instanceof MembraneError || (error instanceof Error && error.name === 'MembraneError');
+}
 function isOrganizationAccelerationRateLimit(error) {
-    if (!(error instanceof MembraneError) || error.type !== 'rate_limit')
+    if (!isMembraneError(error) || error.type !== 'rate_limit')
         return false;
     return (/organization(?:'s)?[^\n]{0,120}maximum(?:\s+usage)?\s+increase\s+rate/i.test(error.message) ||
         /organization(?:'s)?[^\n]{0,120}acceleration(?:\s+limit)?/i.test(error.message));
@@ -552,11 +614,267 @@ function extractGateFields(event) {
         : undefined;
     return { content, metadata, mount, paths };
 }
-/** Cap an API error message for inline use in a rewind marker: keep enough to
- *  identify the failure class without pasting a wall of provider JSON into the
- *  agent's context. */
-function truncateReason(reason, max = 160) {
-    return reason.length <= max ? reason : reason.slice(0, max) + '…';
+/**
+ * Longest failure text the inference-failure pipeline writes to one sink: the
+ * reason in the exhaustion stderr line, a field of a logs/failures.log record,
+ * an ops alert's message, the inference log's `error`, and a trace event's
+ * `error` and `stack`. A failure's text is whatever its source put in
+ * `Error.message`, and a provider can echo the entire rejected request there
+ * (one OpenAI-compatible 400 echoed ~1.7 MB). The sinks with shorter bounds
+ * name them below, and every cut goes through boundFailureText. This bound
+ * doesn't depend on membrane bounding its own errors.
+ */
+const FAILURE_TEXT_MAX_CHARS = 2_000;
+/** Longest failure reason written into an agent's own context (the
+ *  `[inference-failed]` marker): enough for a provider's explanation, not a
+ *  self-dump the agent then carries in every later request. */
+const FAILURE_MARKER_REASON_MAX_CHARS = 600;
+/** Longest failure reason in the rewind marker, also the agent's own context:
+ *  enough to identify the failure class without a wall of provider JSON. */
+const REWIND_MARKER_REASON_MAX_CHARS = 160;
+/** Longest failure reason in an agent's status (`lastInference.lastError`) and
+ *  in the compile-refused ops alert. */
+const FAILURE_SUMMARY_MAX_CHARS = 300;
+/** Longest alert message posted to the ops webhook. */
+const OPS_WEBHOOK_MESSAGE_MAX_CHARS = 500;
+/** Longest provider error code recorded verbatim; real codes are short tokens.
+ *  A failure's name and type are bounded the same way. */
+const PROVIDER_ERROR_CODE_MAX_CHARS = 128;
+const isHighSurrogate = (text, index) => {
+    const code = text.charCodeAt(index);
+    return code >= 0xd800 && code <= 0xdbff;
+};
+const isLowSurrogate = (text, index) => {
+    const code = text.charCodeAt(index);
+    return code >= 0xdc00 && code <= 0xdfff;
+};
+/** Whether a cut before `index` would separate the halves of a surrogate pair. */
+const splitsPair = (text, index) => index > 0 && index < text.length && isHighSurrogate(text, index - 1) && isLowSurrogate(text, index);
+/**
+ * `text` when it fits within `max` characters; otherwise its head and tail
+ * around a marker stating how many of how many characters were omitted, the
+ * whole within `max`. A cut that would separate a surrogate pair moves toward
+ * omission, so the result never holds half of a pair the text held whole, and
+ * bounding bounded text returns it as is. Each sink cuts the whole text, so
+ * its marker states the whole length.
+ */
+function boundFailureText(text, max = FAILURE_TEXT_MAX_CHARS) {
+    if (text.length <= max)
+        return text;
+    const markerLength = ` …[${text.length} of ${text.length} characters omitted]… `.length;
+    const budget = Math.max(0, max - markerLength);
+    const tailLength = Math.floor(budget / 4);
+    let headEnd = budget - tailLength;
+    if (splitsPair(text, headEnd))
+        headEnd--;
+    let tailStart = text.length - tailLength;
+    if (splitsPair(text, tailStart))
+        tailStart++;
+    return `${text.slice(0, headEnd)} …[${tailStart - headEnd} of ${text.length} characters omitted]… ${text.slice(tailStart)}`;
+}
+/** A provider error code, verbatim when token-sized; otherwise bounded. */
+function boundProviderErrorCode(code) {
+    if (typeof code !== 'string')
+        return undefined;
+    return boundFailureText(code, PROVIDER_ERROR_CODE_MAX_CHARS);
+}
+/**
+ * A value's JSON for a failure sink, with every Error inside it written as its
+ * whole projection (failureDescription): serialising an Error writes its own
+ * fields, a MembraneError's whole `rawRequest` among them. The projection is
+ * left uncut, as a nested string is, so the sink's one cut of the JSON states
+ * its whole length. An Error is recognised by instanceof, so one from another
+ * realm (a vm context) is written as its own JSON, as any object is. Throws,
+ * or returns undefined, as JSON.stringify does.
+ */
+function failureJson(value) {
+    return JSON.stringify(value, (_key, nested) => (nested instanceof Error ? failureDescription(nested) : nested));
+}
+/**
+ * The whole text describeFailure cuts. For an Error, its head (name,
+ * classification, status, provider code, each bounded) and its whole
+ * message. For a primitive, its String. For another object, its String when
+ * that's text of its own (a Buffer, an Error from another realm, a class
+ * with its own toString). An array, or an object whose String is empty or
+ * only its tag, such as `[object Object]`, is its JSON instead
+ * (failureJson), so its fields and elements are kept; its tag stands when
+ * JSON can't write it or finds nothing in it.
+ */
+function failureDescription(error) {
+    try {
+        if (!(error instanceof Error)) {
+            if (typeof error !== 'object' || error === null)
+                return String(error);
+            if (!Array.isArray(error)) {
+                let text;
+                try {
+                    text = String(error);
+                }
+                catch { /* no String of its own: its JSON, below */ }
+                if (text && !/^\[object [^\]]*\]$/.test(text))
+                    return text;
+            }
+            try {
+                const json = failureJson(error);
+                if (json !== undefined && json !== '{}')
+                    return json;
+            }
+            catch { /* its tag, below */ }
+            return Object.prototype.toString.call(error);
+        }
+        const fields = error;
+        // Every component is remote or caller-supplied text, the name included.
+        const classification = [
+            typeof fields.type === 'string' ? boundFailureText(fields.type, PROVIDER_ERROR_CODE_MAX_CHARS) : undefined,
+            typeof fields.httpStatus === 'number' ? `HTTP ${fields.httpStatus}` : undefined,
+            boundProviderErrorCode(fields.providerErrorCode),
+            typeof fields.retryable === 'boolean' ? `retryable=${fields.retryable}` : undefined,
+        ].filter((part) => part !== undefined);
+        const name = boundFailureText(String(error.name), PROVIDER_ERROR_CODE_MAX_CHARS);
+        const head = classification.length > 0 ? `${name} (${classification.join(', ')})` : name;
+        return `${head}: ${String(error.message)}`;
+    }
+    catch {
+        return '[failure could not be described]';
+    }
+}
+/**
+ * A bounded string describing a failure, for logs that would otherwise print
+ * the error object; it is one line unless one of its parts has newlines, as a
+ * message can. Printing the object prints its message whole, in the stack,
+ * and every own field: a MembraneError's `rawRequest` is the whole request
+ * that failed, and Node's console prints each of its strings, a long system
+ * prompt among them, up to 10,000 characters. The projection keeps what a
+ * reader needs (name, classification, status, provider code, message) and
+ * nothing else. The head's parts are bounded each, and the whole
+ * (failureDescription) is cut once, so its marker states the length of the
+ * head and the whole message.
+ */
+function describeFailure(error) {
+    return boundFailureText(failureDescription(error));
+}
+/** A stack frame's line: an indent of spaces or tabs, then `at `. The indent
+ *  never crosses a line break, so a run of blank lines isn't rescanned from
+ *  each line's start. */
+const FRAME_LINE = /^[ \t]+at /m;
+/**
+ * describeFailure, then the error's stack frames, bounded, on the lines
+ * below: for a log of a failure the framework's own code may have thrown,
+ * where the frames say where. The stack opens with the message, and a
+ * message's own lines can look like frames (an echoed request quoting a stack
+ * trace), so when the message is the stack's header, before its first frame
+ * line, the frames are the stack from its first frame line after the
+ * message. Otherwise (a stack without its header, a message that isn't in
+ * the stack or is empty) they are the stack from its first frame line. The
+ * leak the projection closes was the object's own fields, not its stack.
+ */
+function describeFailureWithFrames(error) {
+    let frames;
+    try {
+        const stack = error instanceof Error ? error.stack : undefined;
+        if (typeof stack === 'string') {
+            const message = String(error.message);
+            // The message is the stack's header only before its first frame: a
+            // stack without its header (copied, or frames only) can hold the
+            // message's text inside a frame's name.
+            const firstFrame = stack.search(FRAME_LINE);
+            const at = message ? stack.indexOf(message) : -1;
+            const frameLine = new RegExp(FRAME_LINE.source, 'gm');
+            frameLine.lastIndex = at >= 0 && (firstFrame < 0 || at < firstFrame) ? at + message.length : 0;
+            const found = frameLine.exec(stack);
+            if (found)
+                frames = boundFailureText(stack.slice(found.index));
+        }
+    }
+    catch { /* the projection alone */ }
+    const described = describeFailure(error);
+    return frames === undefined ? described : `${described}\n${frames}`;
+}
+/**
+ * A failure record's fields, each bounded, for logs/failures.log and the
+ * ops:alert trace: a string to FAILURE_TEXT_MAX_CHARS; an Error to its
+ * projection, since serialising one writes its own fields, a MembraneError's
+ * whole `rawRequest` among them; any other value to its JSON, with each Error
+ * inside it as its projection (failureJson), as the plain data that JSON
+ * describes when it fits FAILURE_TEXT_MAX_CHARS and as the JSON text,
+ * bounded, when it doesn't. So the trace's data is what failures.log writes:
+ * a Map or an object with toJSON whose JSON is small never hands a listener
+ * the value itself.
+ */
+function boundFailureFields(record) {
+    const bounded = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (typeof value === 'string')
+            bounded[key] = boundFailureText(value);
+        else if (value instanceof Error)
+            bounded[key] = describeFailure(value);
+        else {
+            let json;
+            try {
+                json = failureJson(value);
+            }
+            catch {
+                bounded[key] = describeFailure(value);
+                continue;
+            }
+            // A value JSON writes nothing for (a function, undefined) is left out,
+            // as the log's JSON leaves it out.
+            if (json === undefined)
+                continue;
+            bounded[key] = json.length <= FAILURE_TEXT_MAX_CHARS ? JSON.parse(json) : boundFailureText(json);
+        }
+    }
+    return bounded;
+}
+/**
+ * Whether the poison-history breaker may shed the newest exchange for a
+ * failure: an `invalid_request` at HTTP 400, 413 or 422 or with no status, or
+ * a `context_length` at 413. The status is a heuristic for when a shed may
+ * help, not proof that the history is at fault.
+ *
+ * 400 and 422 are how a provider answers a request that fails its
+ * validation, as a history it can't accept does, but other refusals come
+ * back the same way, such as Anthropic's 400 for a credit balance that's too
+ * low. A 413 is the request's size. When the newest exchange made it too
+ * large, as an oversized attachment does, shedding that exchange may bring
+ * the request back under the limit, and nothing else in the framework
+ * recovers a 413; when the history as a whole is too large, the shed doesn't
+ * help, and the breaker stops at its rewind cap. The 413 arm takes both
+ * labels a 413 arrives under, invalid_request and context_length, because
+ * membrane's label for a 413 differs by version and adapter. Other statuses
+ * keep the history, since shed history can't be got back and the status
+ * gives no sign that a shed would help: a 404 is a model or an endpoint that
+ * doesn't exist, and 405, 409, 410 and 415 are about the HTTP request or the
+ * resource, as a rule, rather than the conversation.
+ *
+ * The table test in test/inference-exhaustion-rewind.test.ts is this
+ * predicate's contract. The notes below on which membrane version gives which
+ * label are its history, and will go stale as hosts move to newer releases.
+ *
+ * Which failures reach the gate with which label depends on the membrane:
+ * - As membrane 0.5.86 classifies them: Anthropic files a 400 as
+ *   invalid_request (after its context check) and its other 4xx as unknown.
+ *   The chat adapters never file one as invalid_request, since they classify
+ *   by the error's message text, and a context_length they file that way
+ *   carries status 400 whatever the response's was. The raw-fetch Responses
+ *   adapter files every status it doesn't list (404, 405, 409, 410, 413,
+ *   415, 422 …) as invalid_request, so it alone produces an invalid_request
+ *   at 413 or 422, and no 0.5.86 adapter produces a context_length at 413.
+ * - From membrane #56 (merged, not yet in a release), one table serves every
+ *   adapter. Auth codes and context overflow are checked on a 400 or 422
+ *   first, a 404 is invalid_request, a 413 is context_length, and other 4xx
+ *   are invalid_request. So a 413 still sheds, an Anthropic one included,
+ *   while a context_length at 400 or 422, a token overflow, keeps the
+ *   history. The 422 arm then also covers an OpenAI-compatible server, such
+ *   as a FastAPI one, that answers a validation failure with 422.
+ *
+ * An error with no status, from a membrane that reports none, keeps the rule
+ * the breaker had before: the type alone.
+ */
+export function shedMayHelp(errorType, httpStatus) {
+    if (httpStatus === 413)
+        return errorType === 'invalid_request' || errorType === 'context_length';
+    return errorType === 'invalid_request' && (httpStatus === undefined || httpStatus === 400 || httpStatus === 422);
 }
 /** The most of a thrown value's or a tool error's text that reaches a log line or a server's error answer. */
 const THROWN_TEXT_LIMIT = 500;
@@ -688,6 +1006,10 @@ export class AgentFramework {
     providerAccelerationDefaultCooldownMs = PROVIDER_ACCELERATION_DEFAULT_COOLDOWN_MS;
     providerAccelerationJitterMs = PROVIDER_ACCELERATION_JITTER_MS;
     providerHoldHook;
+    /** Provider waits (stated retry-after) per (agent, model), kept across restarts. */
+    providerWaits;
+    /** Wakers for error-policy retry waits in progress: stop() ends them. */
+    retryWaitWakers = new Set();
     providerAdmissionClosed = false;
     /** Invalidates framework turns still assembling when stop begins. */
     lifecycleGeneration = 0;
@@ -1069,6 +1391,13 @@ export class AgentFramework {
         this.operatorLog = operatorLog;
         this.store = store;
         this.ownsStore = ownsStore;
+        // Unreadable recorded waits hold every agent's provider calls, and a
+        // persistent cause never reads again: a person has to hear of it.
+        this.providerWaits = new ProviderWaits(store, {
+            onUnreadable: (error) => this.opsAlert('provider-wait', 'framework', `recorded provider waits could not be read (${error}): no provider call is admitted for any agent ` +
+                'until they read again (re-read every 30 s) or an operator releases an agent\'s waits with ' +
+                'release-provider-wait; such a release lasts for this process only', { data: { model: EVERY_MODEL, until: null } }),
+        });
         this.membrane = membrane;
         this.inferencePolicy = inferencePolicy;
         this.errorPolicy = errorPolicy;
@@ -1085,14 +1414,16 @@ export class AgentFramework {
             emitTrace: (e) => this.emitTrace({ ...e }),
         });
         // Initialize module registry with callbacks
-        this.moduleRegistry = new ModuleRegistry(store, this.queue, {
+        // A module's events, through pushEvent() or its deprecated queue handle,
+        // go through pushModuleEvent(), which names the module.
+        this.moduleRegistry = new ModuleRegistry(store, { push: (event, moduleName) => this.pushModuleEvent(event, moduleName, false) }, {
             getAgents: () => Array.from(this.agents.values()),
             addMessage: (p, c, m) => this.addMessage(p, c, m),
             editMessage: (id, c) => this.editMessage(id, c),
             removeMessage: (id) => this.removeMessage(id),
             getMessage: (id) => this.getMessage(id),
             queryMessages: (filter) => this.queryMessages(filter),
-            pushEvent: (event) => this.pushEvent(event),
+            pushEvent: (event, moduleName) => this.pushModuleEvent(event, moduleName, true),
             onTrace: (listener) => this.onTrace(listener),
             // The ONLY entry that confers module origin — a private closure the
             // framework hands to its own module registry. The public
@@ -1565,6 +1896,8 @@ export class AgentFramework {
         // store is still open, rather than leaving them to a reboot replay.
         this.ackDeferredWrites();
         this.providerAdmissionClosed = true;
+        for (const wake of [...this.retryWaitWakers])
+            wake();
         this.lifecycleGeneration++;
         // The generation this stop ends; withheld spills close for it alone, so a
         // start() made before this stop finishes reopens them for its own.
@@ -1716,7 +2049,13 @@ export class AgentFramework {
     providerGateBlocked(agentName) {
         const gate = this.providerGates.get(agentName);
         return (gate?.primaryDepth ?? 0) > 0 || (gate?.primaryPending ?? false) ||
-            this.providerAccelerationCooldowns.has(agentName);
+            this.cooldownBlocksAuxiliary(agentName);
+    }
+    /** Acceleration and host holds park the whole agent; a provider wait holds
+     *  only its own model, which auxiliary admission checks per call. */
+    cooldownBlocksAuxiliary(agentName) {
+        const cooldown = this.providerAccelerationCooldowns.get(agentName);
+        return cooldown !== undefined && cooldown.waitModel === undefined;
     }
     acquirePrimaryProviderGate(agentName) {
         const gate = this.providerGate(agentName);
@@ -1730,7 +2069,7 @@ export class AgentFramework {
     }
     flushAuxiliaryAdmission(agentName) {
         const gate = this.providerGate(agentName);
-        if (gate.primaryDepth > 0 || gate.primaryPending || this.providerAccelerationCooldowns.has(agentName))
+        if (gate.primaryDepth > 0 || gate.primaryPending || this.cooldownBlocksAuxiliary(agentName))
             return;
         for (const resolve of gate.auxiliaryWaiters.splice(0))
             resolve();
@@ -1741,8 +2080,9 @@ export class AgentFramework {
             return;
         await new Promise((resolve) => gate.idleWaiters.push(resolve));
     }
-    async withAuxiliaryAdmission(agentName, run) {
+    async withAuxiliaryAdmission(agentName, run, model) {
         const gate = this.providerGate(agentName);
+        this.refuseHeldProviderModel(agentName, model);
         if (this.providerGateBlocked(agentName)) {
             gate.deferredAuxiliary++;
             try {
@@ -1755,17 +2095,23 @@ export class AgentFramework {
         if (this.providerAdmissionClosed) {
             throw new Error(`Provider admission closed while stopping (${agentName})`);
         }
+        // A wait recorded while this call was parked binds it too.
+        this.refuseHeldProviderModel(agentName, model);
         gate.auxiliaryInFlight++;
         try {
             return await run();
         }
         catch (error) {
             // Compression can be the first call to find a spent quota (idle agent,
-            // scheduled maintenance). Arm the host hold so later passes wait at the
-            // gate instead of retrying into it; this pass still fails to its caller.
+            // scheduled maintenance). Record a stated wait for this call's model,
+            // and arm the host hold so later passes wait at the gate instead of
+            // retrying into it; this pass still fails to its caller.
             const agent = this.agents.get(agentName);
-            if (agent && error instanceof Error)
+            if (agent && error instanceof Error) {
+                if (model !== undefined)
+                    this.recordProviderWait(agentName, model, error);
                 this.holdProviderAcceleration(agent, error, undefined, true);
+            }
             throw error;
         }
         finally {
@@ -1776,22 +2122,62 @@ export class AgentFramework {
         }
     }
     auxiliaryMembraneFor(agentName) {
+        return this.membraneAdmitting((run, model) => this.withAuxiliaryAdmission(agentName, run, model));
+    }
+    /**
+     * A conversation agent's auxiliary calls (its context manager's
+     * compression). A conversation agent takes no provider gate: admission
+     * belongs to the persistent resident, and a generation-unique fork must not
+     * leave a gate behind. But its stated waits are recorded for (agent, model)
+     * as a resident's are, so they bind its auxiliary calls too: a held model
+     * is refused without a call, and an auxiliary call's own stated wait is
+     * recorded for it. (An ephemeral run records nothing, its name being
+     * single-use, so its context manager keeps the plain membrane.)
+     */
+    conversationAuxiliaryMembraneFor(agentName) {
+        return this.membraneAdmitting(async (run, model) => {
+            this.refuseHeldProviderModel(agentName, model);
+            try {
+                return await run();
+            }
+            catch (error) {
+                if (model !== undefined && error instanceof Error)
+                    this.recordProviderWait(agentName, model, error);
+                throw error;
+            }
+        });
+    }
+    /** The framework's membrane, with each complete() call passed through
+     *  `admit` along with the model it names. */
+    membraneAdmitting(admit) {
         const target = this.membrane;
         return new Proxy(target, { get: (obj, prop, receiver) => {
                 const value = Reflect.get(obj, prop, receiver);
                 if (prop === 'complete' && typeof value === 'function') {
-                    return (...args) => this.withAuxiliaryAdmission(agentName, () => Reflect.apply(value, this.membrane, args));
+                    return (...args) => {
+                        const model = args[0]?.config?.model;
+                        return admit(() => Reflect.apply(value, this.membrane, args), typeof model === 'string' ? model : undefined);
+                    };
                 }
                 return typeof value === 'function' ? value.bind(this.membrane) : value;
             } });
     }
+    /** An acceleration hold's length: AF's own pacing (`ownMs`: its default
+     *  plus jitter, capped), or the provider's stated wait in its place
+     *  (`stated`). The stated wait is a lower bound: jitter only adds to it,
+     *  and the cap applies only to AF's own default. A negative stated wait is
+     *  a stated 0, as in ProviderWaits: the 1 s floor, plus jitter. */
     accelerationCooldownMs(agentName, error) {
-        const base = error.retryAfterMs ?? this.providerAccelerationDefaultCooldownMs;
         let hash = 0;
         for (const ch of agentName)
             hash = ((hash * 31) + ch.charCodeAt(0)) >>> 0;
         const jitter = this.providerAccelerationJitterMs > 0 ? hash % (this.providerAccelerationJitterMs + 1) : 0;
-        return Math.min(PROVIDER_ACCELERATION_MAX_COOLDOWN_MS, Math.max(1_000, base) + jitter);
+        const ownMs = Math.min(PROVIDER_ACCELERATION_MAX_COOLDOWN_MS, Math.max(1_000, this.providerAccelerationDefaultCooldownMs) + jitter);
+        const stated = error.retryAfterMs;
+        if (typeof stated === 'number' && Number.isFinite(stated)) {
+            return { delayMs: Math.max(1_000, stated) + jitter, ownMs, stated: true };
+        }
+        return { delayMs: ownMs, ownMs, stated: false };
     }
     sameInferenceRequest(a, b) {
         return a.agentName === b.agentName && a.reason === b.reason && a.source === b.source &&
@@ -1804,11 +2190,15 @@ export class AgentFramework {
             const hold = this.providerHoldHook(error, agentName, { model: this.agents.get(agentName)?.model });
             if (!hold || !Number.isFinite(hold.holdMs) || hold.holdMs <= 0)
                 return undefined;
+            // The reason is printed, kept in the cooldown and shown in the status
+            // snapshot (cooldownReason); without the host's own, it is the error's
+            // message, which can echo the whole request.
             return { holdMs: Math.min(PROVIDER_ACCELERATION_MAX_COOLDOWN_MS, Math.max(1_000, hold.holdMs)),
-                reason: typeof hold.reason === 'string' && hold.reason ? hold.reason : error.message };
+                reason: boundFailureText(typeof hold.reason === 'string' && hold.reason ? hold.reason : String(error.message)) };
         }
         catch (err) {
-            console.error(`[provider-cooldown] providerHold hook threw for ${agentName}; treating as no hold:`, err);
+            // The hook is handed the model's error, and may throw it back.
+            console.error(`[provider-cooldown] providerHold hook threw for ${agentName}; treating as no hold: ${describeFailureWithFrames(err)}`);
             return undefined;
         }
     }
@@ -1822,7 +2212,7 @@ export class AgentFramework {
             return false;
         clearTimeout(cooldown.timer);
         cooldown.until = Date.now() + hold.holdMs;
-        cooldown.timer = setTimeout(() => this.releaseProviderAccelerationCooldown(agentName), hold.holdMs);
+        cooldown.timer = setTimeout(() => this.releaseProviderAccelerationCooldown(agentName), Math.min(hold.holdMs, MAX_TIMER_DELAY_MS));
         cooldown.timer.unref?.();
         if (hold.reason !== cooldown.reason) {
             cooldown.reason = hold.reason;
@@ -1833,26 +2223,42 @@ export class AgentFramework {
     holdProviderAcceleration(agent, error, trigger, auxiliary = false) {
         if (this.ephemeralRuns.has(agent.name) || this.conversationAgentHomes.has(agent.name))
             return false;
+        // A provider's stated wait binds later calls to the primary model, across
+        // restarts. (An auxiliary call records its own model's wait at the gate.)
+        const wait = auxiliary ? undefined : this.recordProviderWait(agent.name, agent.model, error);
         // The host knows more than the message wording does: ask it first. An
         // auxiliary failure arms host holds only — the built-in acceleration
         // cooldown stays a primary-path mechanism.
         const hostHold = this.consultProviderHold(error, agent.name);
-        const acceleration = !hostHold && !auxiliary && isOrganizationAccelerationRateLimit(error);
-        if (!acceleration && !hostHold)
-            return false;
+        // A failure the provider says may not be retried keeps its terminal
+        // disposition, whatever its wording (a stated wait still binds after it).
+        const acceleration = !hostHold && !auxiliary && error.retryable !== false
+            && isOrganizationAccelerationRateLimit(error);
+        // The stated wait binds later calls whatever the failure was. Retaining
+        // and retrying THIS request is for a failure the provider says may be
+        // retried: a non-retryable one keeps its terminal disposition (marker,
+        // failure streak), and the wait applies to the calls that follow it.
+        if (!acceleration && !hostHold) {
+            return wait !== undefined && isMembraneError(error) && error.retryable === true
+                && this.holdForProviderWait(agent, wait, trigger ? [trigger] : [], true);
+        }
         const now = Date.now();
-        const delayMs = hostHold ? hostHold.holdMs : this.accelerationCooldownMs(agent.name, error);
+        const pacing = hostHold ? undefined : this.accelerationCooldownMs(agent.name, error);
+        const delayMs = hostHold ? hostHold.holdMs : pacing.delayMs;
         const existing = this.providerAccelerationCooldowns.get(agent.name);
         const held = existing?.heldRequests ?? [];
         if (trigger && !held.some((r) => this.sameInferenceRequest(r, trigger)))
             held.push(trigger);
         if (existing)
             clearTimeout(existing.timer);
-        const timer = setTimeout(() => this.releaseProviderAccelerationCooldown(agent.name), delayMs);
+        const timer = setTimeout(() => this.releaseProviderAccelerationCooldown(agent.name), Math.min(delayMs, MAX_TIMER_DELAY_MS));
         timer.unref?.();
         this.providerAccelerationCooldowns.set(agent.name, { startedAt: existing?.startedAt ?? now,
-            until: now + delayMs, timer, heldRequests: held, reason: hostHold?.reason ?? error.message,
+            until: now + delayMs, timer, heldRequests: held, reason: hostHold?.reason ?? boundFailureText(String(error.message)),
             failures: (existing?.failures ?? 0) + 1, ...(hostHold ? { hostHoldError: error } : {}),
+            // The stated wait (recorded above for agent.model) set this hold's
+            // length: an operator release of it returns the hold to AF's own pacing.
+            ...(pacing?.stated ? { statedWait: { model: agent.model, ownUntil: now + pacing.ownMs } } : {}),
             ...(auxiliary && (!existing || existing.auxiliaryOrigin) ? { auxiliaryOrigin: true } : {}) });
         if (auxiliary && !existing) {
             console.error(`[provider-cooldown] agent=${agent.name} host hold (${hostHold.reason}) from an auxiliary call — ` +
@@ -1862,20 +2268,101 @@ export class AgentFramework {
         const gate = this.providerGate(agent.name);
         gate.primaryPending = true;
         this.providerAccelerationRecoveries.set(agent.name, { startedAt: existing?.startedAt ?? now,
-            failures: (existing?.failures ?? 0) + 1, heldRequests: held.length, reason: error.message });
+            failures: (existing?.failures ?? 0) + 1, heldRequests: held.length, reason: boundFailureText(String(error.message)) });
         console.error(`[provider-cooldown] agent=${agent.name} ` +
             `${hostHold ? `host hold (${hostHold.reason})` : 'organization acceleration 429'} — ` +
             `holding primary/auxiliary for ${delayMs}ms; ${held.length} request(s) retained`);
         return true;
     }
+    /**
+     * A provider's stated wait on a turn that doesn't own provider admission:
+     * a conversation agent's or an ephemeral run's. Left to the error policy,
+     * which returns a stated wait as it is, a 429 stating two hours would hold
+     * the turn asleep two hours, up to three times, with nothing recorded and
+     * nothing raised (membrane #56 review, M3). So:
+     * - A conversation agent's turns come through the scheduler as a resident's
+     *   do, so it treats the wait as a resident does: recorded for (agent,
+     *   model), alerted past PROVIDER_WAIT_ALERT_MS, and the turn held until the
+     *   wait passes or an operator releases it ('held'). A non-retryable failure
+     *   records the wait for the calls after it and keeps its own disposition.
+     * - An ephemeral run's name is single-use, so a wait recorded for it would
+     *   bind nothing, and its caller is waiting on it. A retryable stated wait
+     *   up to PROVIDER_ACCELERATION_MAX_COOLDOWN_MS is left to the error policy,
+     *   slept and retried. A longer one, or one that can't be represented, ends
+     *   the run now ('fail'): it is never retried before the provider's time,
+     *   and the caller hears why at once.
+     * Anything else is the error policy's.
+     */
+    nonOwningProviderWait(agent, error, trigger) {
+        // From either copy of membrane (isMembraneError), a wait is stated only
+        // as a number, as the default error policy reads it.
+        if (!isMembraneError(error) || typeof error.retryAfterMs !== 'number')
+            return undefined;
+        if (this.conversationAgentHomes.has(agent.name)) {
+            const wait = this.recordProviderWait(agent.name, agent.model, error);
+            return error.retryable === true && wait !== undefined && this.holdForProviderWait(agent, wait, trigger ? [trigger] : [], true)
+                ? 'held'
+                : undefined;
+        }
+        if (this.ephemeralRuns.has(agent.name) && error.retryable === true
+            && !(error.retryAfterMs <= PROVIDER_ACCELERATION_MAX_COOLDOWN_MS)) {
+            return 'fail';
+        }
+        return undefined;
+    }
+    /** Why an ephemeral run ended instead of sleeping a provider's stated wait,
+     *  for its caller. */
+    statedWaitNotSlept(error) {
+        const stated = isMembraneError(error) ? error.retryAfterMs : undefined;
+        const cap = `${PROVIDER_ACCELERATION_MAX_COOLDOWN_MS / 1000} s`;
+        if (typeof stated !== 'number' || Number.isNaN(stated)) {
+            return `${error.message} (the provider's stated wait is not a number, and an ephemeral run sleeps only a ` +
+                `stated wait of ${cap} or less, so it ends now)`;
+        }
+        const asked = Number.isFinite(stated) ? `${Math.ceil(stated / 1000)} s` : 'longer than can be represented';
+        return `${error.message} (the provider asked to wait ${asked}; an ephemeral run doesn't sleep a stated wait ` +
+            `longer than ${cap}, so it ends now)`;
+    }
+    /** When a hold's timer next fires: at its deadline, stepped past what one
+     *  timer can hold. A hold with no deadline (a wait held until released, or
+     *  the stand-in for unreadable records) asks again as often as unreadable
+     *  records are read again: records that read again end it, and nothing
+     *  announces that. */
+    providerHoldTimerMs(remaining) {
+        return Number.isFinite(remaining)
+            ? Math.min(remaining, MAX_TIMER_DELAY_MS)
+            : this.providerWaits?.retryReadMs ?? MAX_TIMER_DELAY_MS;
+    }
     releaseProviderAccelerationCooldown(agentName) {
         const cooldown = this.providerAccelerationCooldowns.get(agentName);
         if (!cooldown)
             return;
+        // A wait hold lasts exactly as long as its wait binds: longer once the
+        // wait is extended, while it is indefinite, and over once no wait binds
+        // (passed, released, or the stand-in for unreadable records lifted because
+        // they read again). A different primary model now is not bound by it.
+        if (cooldown.waitModel !== undefined && this.agents.get(agentName)?.model === cooldown.waitModel) {
+            const wait = this.providerWaits?.active(agentName, cooldown.waitModel);
+            cooldown.until = wait ? (wait.until ?? Number.POSITIVE_INFINITY) : Date.now();
+        }
+        const remaining = cooldown.until - Date.now();
+        if (remaining > 0 && (cooldown.waitModel === undefined || this.agents.get(agentName)?.model === cooldown.waitModel)) {
+            clearTimeout(cooldown.timer);
+            cooldown.timer = setTimeout(() => this.releaseProviderAccelerationCooldown(agentName), this.providerHoldTimerMs(remaining));
+            cooldown.timer.unref?.();
+            return;
+        }
         if (this.extendHostProviderHold(agentName, cooldown))
             return;
         clearTimeout(cooldown.timer);
         this.providerAccelerationCooldowns.delete(agentName);
+        if (cooldown.waitModel !== undefined) {
+            const model = this.agents.get(agentName)?.model;
+            console.error(`[provider-wait] agent=${agentName} model=${cooldown.waitModel} ` +
+                (model !== undefined && model !== cooldown.waitModel
+                    ? `no longer holds primary turns: the primary model is now ${model} (the wait stays recorded)`
+                    : `primary hold ended after ${Date.now() - cooldown.startedAt}ms`));
+        }
         if (cooldown.auxiliaryOrigin && cooldown.heldRequests.length === 0) {
             // Nobody asked for an inference while parked: just reopen the gate.
             console.error(`[provider-cooldown] agent=${agentName} auxiliary hold released after ${Date.now() - cooldown.startedAt}ms`);
@@ -1893,6 +2380,199 @@ export class AgentFramework {
         console.error(`[provider-cooldown] agent=${agentName} released after ${Date.now() - cooldown.startedAt}ms — ` +
             `fresh compile queued with ${requests.length} retained request(s)`);
     }
+    /**
+     * Wait an error policy's retry delay, all of it: the delay can be a
+     * provider's retry-after, and a single timer past 2^31-1 ms fires almost at
+     * once. Steps through longer waits; stop() wakes it so a shutting-down
+     * framework is never left with a wait parked for days.
+     */
+    async waitForRetry(ms) {
+        // An infinite delay waits until stop(), like any wait too long to end; a
+        // delay that isn't a number, or is 0 or less, waits none.
+        let remaining = ms > 0 ? ms : 0;
+        while (remaining > 0 && !this.providerAdmissionClosed) {
+            const step = Math.min(remaining, MAX_TIMER_DELAY_MS);
+            remaining -= step;
+            await new Promise((resolve) => {
+                const wakers = this.retryWaitWakers;
+                const done = () => { clearTimeout(timer); wakers.delete(done); resolve(); };
+                const timer = setTimeout(done, step);
+                wakers.add(done);
+            });
+        }
+    }
+    /**
+     * Record a provider's stated wait (a classified error carrying
+     * `retryAfterMs`) for (agent, model). Returns the wait that binds now,
+     * which is the longer of this one and any outstanding one. A wait that
+     * newly binds past PROVIDER_WAIT_ALERT_MS, or until released, raises an
+     * ops alert.
+     */
+    recordProviderWait(agentName, model, error) {
+        // From either copy of membrane: the host supplies the Membrane instance,
+        // and a wait is stated only as a number, as the default policy reads it.
+        if (!isMembraneError(error) || typeof error.retryAfterMs !== 'number' || !this.providerWaits)
+            return undefined;
+        // The provider's words, bounded; a line break in them must not start a
+        // line that reads as the framework's own where the reason is logged.
+        const reason = safeSlice(withoutControls(error.message), 0, 300);
+        const { wait, changed } = this.providerWaits.set(agentName, model, error.retryAfterMs, reason);
+        // A wait already over (0, or a negative "retry now") holds nothing to report.
+        const remaining = wait.until === null ? Number.POSITIVE_INFINITY : wait.until - Date.now();
+        if (changed && remaining > 0) {
+            const until = wait.until === null
+                ? 'until an operator releases it (the stated wait cannot be represented as an instant)'
+                : `until ${new Date(wait.until).toISOString()}`;
+            const stated = `${error.type}${error.httpStatus !== undefined ? ` HTTP ${error.httpStatus}` : ''}, retry-after ${String(error.retryAfterMs)}ms`;
+            console.error(`[provider-wait] agent=${agentName} model=${model} holds ${until}: ${stated}`);
+            if (remaining > PROVIDER_WAIT_ALERT_MS) {
+                this.opsAlert('provider-wait', agentName, `provider wait on ${model} holds ${until} (${stated}: ${reason}); ` +
+                    'if the provider did not mean that, release it with release-provider-wait', { data: { model, until: wait.until === null ? null : new Date(wait.until).toISOString() } });
+            }
+        }
+        return wait;
+    }
+    /**
+     * Hold this agent's primary turns for a provider wait on its model. The
+     * requests are kept and released together, into one fresh compile, when
+     * the wait ends: the same path an acceleration cooldown takes, without
+     * parking auxiliary calls to other models.
+     */
+    holdForProviderWait(agent, wait, requests, failed = false) {
+        const now = Date.now();
+        const until = wait.until ?? Number.POSITIVE_INFINITY;
+        if (until <= now)
+            return false;
+        const existing = this.providerAccelerationCooldowns.get(agent.name);
+        const held = existing?.heldRequests ?? [];
+        for (const request of requests) {
+            if (!held.some((r) => this.sameInferenceRequest(r, request)))
+                held.push(request);
+        }
+        // An acceleration or host hold already parks the whole agent; its release
+        // re-checks this wait at admission.
+        if (existing && existing.waitModel === undefined)
+            return true;
+        if (existing)
+            clearTimeout(existing.timer);
+        const timer = setTimeout(() => this.releaseProviderAccelerationCooldown(agent.name), this.providerHoldTimerMs(until - now));
+        timer.unref?.();
+        this.providerAccelerationCooldowns.set(agent.name, {
+            startedAt: existing?.startedAt ?? now, until, timer, heldRequests: held,
+            // A failed call counts; a turn arriving at a wait recorded earlier doesn't.
+            reason: wait.reason, failures: (existing?.failures ?? 0) + (failed ? 1 : 0), waitModel: wait.model,
+        });
+        if (!existing) {
+            console.error(`[provider-wait] agent=${agent.name} model=${wait.model} holding primary turns ` +
+                `${wait.until === null ? 'until released' : `until ${new Date(wait.until).toISOString()}`}; ${held.length} request(s) retained`);
+        }
+        return true;
+    }
+    /**
+     * Refuse an auxiliary call to a model the provider asked this agent to wait
+     * on, without calling it. The refusal is a retryable rate limit carrying
+     * the remaining wait, so a caller that paces (context-manager's compression
+     * lane, from its corrective round #138 on) waits it out instead of spending
+     * a call. It is marked
+     * `providerAdmission: 'deferred'`: no call was made, so a caller can keep
+     * the wait without counting a failed call (room-225 #47927).
+     */
+    refuseHeldProviderModel(agentName, model) {
+        // A call that names no model can't be matched to a model's wait, but the
+        // hold that stands for unreadable records binds every model, so it binds
+        // that call too (EVERY_MODEL: only that hold, or a release of it, says so).
+        const wait = this.providerWaits?.active(agentName, model ?? EVERY_MODEL);
+        if (!wait)
+            return;
+        const now = Date.now();
+        throw Object.assign(new MembraneError({
+            type: 'rate_limit',
+            retryable: true,
+            ...(wait.until !== null ? { retryAfterMs: Math.max(0, wait.until - now) } : {}),
+            message: providerWaitText(agentName, model ?? EVERY_MODEL, wait),
+            rawError: undefined,
+        }), { providerAdmission: 'deferred' });
+    }
+    /**
+     * Release provider waits: one model's for an agent, or every model's. The
+     * explicit operator override for a wait that should not be honoured (the
+     * passing of time needs no call). Recorded, so a restart does not bring the
+     * wait back; held primary turns are released into one fresh compile. An
+     * acceleration hold the released wait lengthened keeps only AF's own pacing
+     * for its failure; a host hold stays the host's.
+     */
+    releaseProviderWait(agentName, model, by = 'operator') {
+        // A release names one of this framework's agents, or the agent of a wait
+        // the listing shows (a disposed conversation fork's wait stays recorded):
+        // an operator can release anything the listing shows. Any other name (a
+        // typo, or '*' and 'framework', which stand for the hold on unreadable
+        // records in its listing and its alert) is refused before anything is
+        // recorded: it would lift nothing and still read as a success. That hold
+        // is lifted one agent at a time.
+        if (!this.agents.has(agentName) && !this.providerWaits?.recorded(agentName)) {
+            throw new Error(`Unknown agent: ${safeSlice(JSON.stringify(agentName), 0, 120)}. A release names one of this ` +
+                "framework's agents or an agent with a recorded wait, and the hold on unreadable provider waits is lifted " +
+                'one agent at a time');
+        }
+        by = operatorLabel(String(by));
+        // '*' (EVERY_MODEL, as providerWaits lists the unreadable-records hold)
+        // names every model, the same as omitting it, everywhere below.
+        if (model === EVERY_MODEL)
+            model = undefined;
+        const released = this.providerWaits?.release(agentName, model, by) ?? [];
+        for (const { wait, release } of released) {
+            console.error(`[provider-wait] agent=${agentName} model=${wait.model} released by ${by} (${release})`);
+        }
+        // The agent's context strategy may pace its own provider calls by the
+        // same stated wait (context-manager's compression lane, from its
+        // corrective round #138 on; 0.14.0 has no releaseCompressionPause, so this
+        // calls nothing there). The release is the operator's word on that wait
+        // too, so it is offered to the lane with its scope even when no wait
+        // binds here: the lane can hold a pause after
+        // this framework's own wait is gone (the records read again, the wait
+        // passed, or it was released in another process). The strategy's own
+        // backoff stays, and the receipt still lists only waits released here.
+        // Read inside the try: the release is already recorded, so a strategy
+        // that throws must not keep the hold below from being released.
+        try {
+            const strategy = this.agents.get(agentName)?.getContextManager().getStrategy();
+            if (strategy?.releaseCompressionPause?.(model)) {
+                console.error(`[provider-wait] agent=${agentName} model=${model ?? '*'} compression lane's provider wait released`);
+            }
+        }
+        catch (error) {
+            console.error(`[provider-wait] agent=${agentName} could not offer the release to the compression lane: ${safeSlice(error instanceof Error ? error.message : String(error), 0, 300)}`);
+        }
+        const cooldown = this.providerAccelerationCooldowns.get(agentName);
+        const covers = (held) => held !== undefined && (model === undefined || held === model);
+        if (cooldown && covers(cooldown.waitModel)) {
+            // A wait hold asks its wait again: released, the hold ends.
+            this.releaseProviderAccelerationCooldown(agentName);
+        }
+        else if (cooldown?.statedWait && covers(cooldown.statedWait.model)) {
+            // An acceleration hold the stated wait lengthened keeps only AF's own
+            // pacing for that failure, and is never lengthened by a release. A host
+            // hold carries no stated wait: its length stays the host's.
+            cooldown.until = Math.min(cooldown.until, cooldown.statedWait.ownUntil);
+            console.error(`[provider-wait] agent=${agentName} model=${cooldown.statedWait.model} acceleration hold keeps AF's own pacing only, ` +
+                (cooldown.until > Date.now() ? `until ${new Date(cooldown.until).toISOString()}` : 'which has passed'));
+            delete cooldown.statedWait;
+            this.releaseProviderAccelerationCooldown(agentName);
+        }
+        return released.map(({ wait, release }) => ({
+            model: wait.model, until: wait.until === null ? null : new Date(wait.until).toISOString(), release,
+        }));
+    }
+    /** Provider waits binding now, for health and doctor tooling. */
+    providerWaitSnapshot(agentName) {
+        return (this.providerWaits?.list(agentName) ?? []).map((wait) => ({
+            agent: wait.agent,
+            model: wait.model,
+            until: wait.until === null ? null : new Date(wait.until).toISOString(),
+            reason: wait.reason,
+            setAt: new Date(wait.setAt).toISOString(),
+        }));
+    }
     recordProviderAccelerationRecovery(agent, request, stopReason) {
         const recovery = this.providerAccelerationRecoveries.get(agent.name);
         if (!recovery?.releasedAt)
@@ -1934,9 +2614,12 @@ export class AgentFramework {
         if (this.maintenancePass || !this.running)
             return;
         const pass = this.runQueuedMaintenance().catch((error) => {
-            const reason = error instanceof Error ? error.message : String(error);
+            // The alert cuts its own copies from the whole message, so the
+            // webhook's states the whole length.
+            const wholeReason = error instanceof Error ? String(error.message) : failureDescription(error);
+            const reason = boundFailureText(wholeReason);
             console.error('[context-maintenance] pass failed:', reason);
-            this.opsAlert('context-maintenance-failed', 'framework', reason, { data: { scope: 'pass' } });
+            this.opsAlert('context-maintenance-failed', 'framework', wholeReason, { data: { scope: 'pass' } });
         });
         this.maintenancePass = pass;
         void pass.finally(() => {
@@ -2005,9 +2688,10 @@ export class AgentFramework {
                     }
                 }
                 catch (error) {
-                    record.error = error instanceof Error ? error.message : String(error);
+                    const wholeError = error instanceof Error ? String(error.message) : failureDescription(error);
+                    record.error = boundFailureText(wholeError);
                     console.error(`[context-maintenance] agent=${agent.name} failed:`, record.error);
-                    this.opsAlert('context-maintenance-failed', agent.name, record.error, {
+                    this.opsAlert('context-maintenance-failed', agent.name, wholeError, {
                         data: {
                             scope: 'agent',
                             ...(record.pendingBefore ? { pending: record.pendingBefore } : {}),
@@ -2111,19 +2795,41 @@ export class AgentFramework {
         this.queue.push(event);
         this.emitTrace({ type: 'process:received', processEvent: event });
     }
+    /**
+     * A module's event. stop() closes the queue before it stops modules, so a
+     * module's event can arrive after that: from a listener that fires while
+     * stop() runs, or from the module's own stop(). Nothing will process it,
+     * and a throw there can go unhandled or fail stop(), so it's dropped with a
+     * log line naming the module. Otherwise it's queued as pushEvent() queues
+     * it, or, through the deprecated queue handle, without the trace.
+     */
+    pushModuleEvent(event, moduleName, traced) {
+        if (this.queue.isClosed) {
+            // A tool result takes pushEvent()'s own drop, whose line names the
+            // call, the tool and its outcome.
+            if (event.type === 'tool-result') {
+                this.pushEvent(event);
+                return;
+            }
+            console.error(`[framework] a '${event.type}' event from module ${moduleName ?? '(unnamed)'} arrived after stop() began — dropped`);
+            return;
+        }
+        if (traced)
+            this.pushEvent(event);
+        else
+            this.queue.push(event);
+    }
     /**
      * Add a trace event listener for observability.
      */
     onTrace(listener) {
-        this.traceListeners.push(listener);
+        const registration = { listener, active: true };
+        this.traceListeners.push(registration);
         // Return an unsubscribe so callers with a bounded lifetime (e.g. modules
         // that get torn down and recreated on session switch) don't leak
         // listeners. Existing callers that ignore the return value are unaffected.
-        return () => {
-            const idx = this.traceListeners.indexOf(listener);
-            if (idx >= 0)
-                this.traceListeners.splice(idx, 1);
-        };
+        // It removes this subscription, whatever else the same function holds.
+        return () => this.removeTraceRegistration(registration);
     }
     /**
      * Public accessor for the MCPL channel registry.
@@ -2135,13 +2841,19 @@ export class AgentFramework {
         return this.channelRegistry;
     }
     /**
-     * Remove a trace event listener.
+     * Remove a trace event listener: its first subscription, if it holds more
+     * than one.
      */
     offTrace(listener) {
-        const index = this.traceListeners.indexOf(listener);
-        if (index >= 0) {
+        const registration = this.traceListeners.find((r) => r.listener === listener);
+        if (registration)
+            this.removeTraceRegistration(registration);
+    }
+    removeTraceRegistration(registration) {
+        registration.active = false;
+        const index = this.traceListeners.indexOf(registration);
+        if (index >= 0)
             this.traceListeners.splice(index, 1);
-        }
     }
     /**
      * Add a module at runtime.
@@ -2280,16 +2992,29 @@ export class AgentFramework {
     async autoFetchReferences(content, serverId, eager) {
         if (!content)
             return;
-        const fetcher = this.getReferenceFetcher();
-        const eligible = [];
+        // Register every block first, then judge each uri once, by its latest
+        // record. The registry keys records by uri and evicts the one registered
+        // least recently, so a uri this result mentions keeps its record through
+        // the result's later blocks, short of more distinct references in one
+        // result than the registry holds; past that, a uri can get a second
+        // record here, hence the key by uri. A uri that any of this result's
+        // blocks calls expired takes no slot, whichever block registered last. A
+        // later result's fresh expiry still supersedes, through register().
+        const byUri = new Map();
         for (const block of content) {
             const c = classifyBlock(block);
             if (c.kind !== 'reference')
                 continue;
             const record = referenceRegistry.register(c.testimony, serverId);
-            if (eager && fetcher.isEagerEligible(record))
-                eligible.push(record);
+            const expiredHere = byUri.get(c.testimony.uri)?.expiredHere === true || isReferenceExpired(c.testimony);
+            byUri.set(c.testimony.uri, { record, expiredHere });
         }
+        if (!eager)
+            return;
+        const fetcher = this.getReferenceFetcher();
+        const eligible = [...byUri.values()]
+            .filter(({ record, expiredHere }) => !expiredHere && fetcher.isEagerEligible(record))
+            .map(({ record }) => record);
         // Parallel with a count cap: N small fetches cost one round-trip of
         // wall-clock, and anything past the cap stays lazy (stub says so).
         const MAX_EAGER_PER_RESULT = 8;
@@ -3885,7 +4610,8 @@ export class AgentFramework {
             return;
         run.lastActivity = Date.now();
         if (outcome.stopReason === 'exhausted') {
-            run.settle.reject(new Error(outcome.error ?? 'Unknown error'));
+            // The caller may log or relay the message, which can echo the whole request.
+            run.settle.reject(new Error(boundFailureText(outcome.error ?? 'Unknown error')));
             return;
         }
         run.settle.resolve({
@@ -4415,7 +5141,8 @@ export class AgentFramework {
             if (parts[0] !== 'discord')
                 return;
             const channelId = parts[parts.length - 1];
-            const emoji = REFUSAL_REACTIONS[category] ?? REFUSAL_REACTION_FALLBACK;
+            // Own names only: an inherited one such as 'constructor' takes the fallback.
+            const emoji = Object.hasOwn(REFUSAL_REACTIONS, category) ? REFUSAL_REACTIONS[category] : REFUSAL_REACTION_FALLBACK;
             // Resolve the MCPL server that owns the locus channel and call
             // tools/call directly on its connection (bare tool name — no prefix
             // games), bypassing the agent event queue so no synthetic tool-result
@@ -4528,9 +5255,10 @@ export class AgentFramework {
             ? `the model refused on them (content filter: ${category}). Their content is ` +
                 `not reproduced here (so this note can't re-trigger the filter); the ` +
                 `originals remain in the raw record`
-            : `the model API kept rejecting the conversation on them (${category}). ` +
-                `Their content is not reproduced here (so this note can't re-trigger the ` +
-                `rejection); the originals remain in the raw record`;
+            : `the model API kept refusing the requests that carried them (${category}), ` +
+                `so that the conversation could go on. Their content is not reproduced ` +
+                `here (so this note can't trigger the same refusal); the originals remain ` +
+                `in the raw record`;
         const text = `[refusal-rewind] The ${count} most recent turn(s) were set aside because ` +
             `${why}. You are clear to continue — if you ` +
             `were mid-task, take a different approach; otherwise carry on with whatever ` +
@@ -4675,6 +5403,10 @@ export class AgentFramework {
      *
      *   host-status — report the quiesce state (drained / parked wakes /
      *   running background scripts).
+     *
+     *   release-provider-wait — end an agent's provider wait (a provider's
+     *   stated retry-after, kept across restarts) for one `model` or all, as an
+     *   explicit, recorded operator override.
      */
     async handleHostCommand(serverId, params) {
         if (params.command !== 'undo' &&
@@ -4684,7 +5416,8 @@ export class AgentFramework {
             params.command !== 'quiesce' &&
             params.command !== 'resume' &&
             params.command !== 'maintain' &&
-            params.command !== 'host-status') {
+            params.command !== 'host-status' &&
+            params.command !== 'release-provider-wait') {
             return { ok: false, error: `Unknown host command: ${String(params.command)}` };
         }
         // Host-scoped verbs (issue #122) — no agent resolution.
@@ -4720,6 +5453,31 @@ export class AgentFramework {
         if (params.command === 'host-status') {
             return { ok: true, hostMode: this.getHostModeStatus() };
         }
+        // A release names its agent, as host.releaseProviderWait does: the first
+        // agent by default could lift the wrong agent's waits. The name may be an
+        // agent the framework no longer has whose wait the listing still shows
+        // (a disposed conversation fork); releaseProviderWait decides that.
+        if (params.command === 'release-provider-wait') {
+            if (typeof params.agentName !== 'string' || params.agentName === '') {
+                return { ok: false, error: 'release-provider-wait: agentName must name the agent whose waits to release' };
+            }
+            // Only an omitted model, or '*', releases every model: a malformed one
+            // is refused here, before anything changes, never widened.
+            if (!isReleaseModel(params.model)) {
+                return { ok: false, error: "release-provider-wait: model must be a model name, or '*' (or omitted) for every model" };
+            }
+            const by = operatorLabel(String(requester));
+            let released;
+            try {
+                released = this.releaseProviderWait(params.agentName, params.model, by);
+            }
+            catch (error) {
+                return { ok: false, error: error instanceof Error ? error.message : String(error) };
+            }
+            console.error(`[host-command] release-provider-wait agent=${params.agentName} model=${params.model ?? '*'} by=${by} ` +
+                `(server=${serverId}): ${released.length} wait(s) lifted`);
+            return { ok: true, released };
+        }
         const agentName = params.agentName ?? [...this.agents.keys()][0];
         if (!agentName || !this.agents.has(agentName)) {
             return { ok: false, error: `Unknown agent: ${String(agentName)}` };
@@ -4884,6 +5642,7 @@ export class AgentFramework {
                     ok: true,
                     messagesRemoved: r.messagesRemoved,
                     removedRefs: r.removedRefs,
+                    markers: r.markers,
                     lastVisible: r.lastVisible,
                 };
             }
@@ -4918,7 +5677,9 @@ export class AgentFramework {
         if (undone === 0) {
             return { ok: true, undone: 0, requested, lastVisible: null };
         }
-        await this.syncDiscordAwarenessMarkers();
+        // The branch has moved: delivery of the marks it changes starts behind
+        // the data-plane gate, and the command doesn't wait for Discord.
+        this.startDiscordAwarenessDelivery('turn undo', agentName);
         return { ok: true, undone, requested, lastVisible: await this.lastVisiblePreview(agentName) };
     }
     /**
@@ -5434,6 +6195,12 @@ export class AgentFramework {
      * Discord messages that left the live context get awareness markers via the
      * durable outbox, exactly as message-granular `undo` does.
      *
+     * Returns once the switch has landed: the body is applied, with a
+     * marker-scheduling receipt (`markers`). It does not wait for Discord to
+     * accept the reactions: delivery is started, behind the MCPL data-plane
+     * gate, and continues without the caller or the store reservation waiting
+     * on it; its per-message outcomes stay in the outbox ledger.
+     *
      * Throws `OperatorActionError` (`agent-busy`, `unknown-message`, …) — the
      * agent must be idle; nothing is queued.
      */
@@ -5473,9 +6240,12 @@ export class AgentFramework {
                 throw new OperatorActionError('invalid', 'Rollback branch name must differ from the active branch');
             }
             // Gate + reserve the whole store (see reserveStoreForSurgery); held
-            // until the switch has landed or been rolled back.
+            // until the switch has landed and its marker scheduling has been
+            // recorded or reported, or the switch has been rolled back. Remote
+            // delivery is not waited on.
             const release = this.reserveStoreForSurgery('roll back', agentName);
             let branchName;
+            let markers;
             try {
                 // Prepare the external side effect before switching Chronicle. If the
                 // process dies after the switch but before activate(), startup
@@ -5503,9 +6273,14 @@ export class AgentFramework {
                     const restored = await this.restoreSourceBranch(cm, sourceBranch, targetBranch, agentName);
                     throw new OperatorActionError('failed', `Rollback failed; ${restored}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
                 }
-                if (markerBatch)
-                    this.discordAwarenessOutbox.activate(markerBatch.id);
-                await this.syncDiscordAwarenessMarkers();
+                // The body change has landed. Nothing after this point turns the
+                // rollback into a failure: marks are an outbox outcome, reported
+                // apart from the body (`markers`).
+                markers = this.activateSurgeryMarkers(markerBatch, 'rollback', agentName);
+                // Installs the MCPL data-plane gate synchronously, before the store is
+                // released, and starts delivery without awaiting it (the first
+                // reaction request may already be on the wire when this returns).
+                this.startDiscordAwarenessDelivery('rollback', agentName);
                 this.materializeConfigMountAfterBranchSwitch();
             }
             finally {
@@ -5513,7 +6288,8 @@ export class AgentFramework {
             }
             console.error(`[operator] rollback agent=${agentName} to=${tailMessageId}` +
                 `${tailMessageId !== opts.messageId ? ` (requested ${opts.messageId}, snapped to end of body group)` : ''}` +
-                ` removed=${messagesRemoved} branch=${branchName} by=${describeRequester(opts.requester)}`);
+                ` removed=${messagesRemoved} branch=${branchName} marks=${describeMarkers(markers)}` +
+                ` by=${describeRequester(opts.requester)}`);
             this.recordOperatorAction({
                 ...logBase,
                 result: {
@@ -5522,6 +6298,7 @@ export class AgentFramework {
                     tailMessageId,
                     messagesRemoved,
                     discordRefs: removedRefs.length,
+                    markers,
                 },
             });
             return {
@@ -5531,6 +6308,7 @@ export class AgentFramework {
                 messagesRemoved,
                 tailMessageId,
                 removedRefs,
+                markers,
                 lastVisible: await this.lastVisiblePreview(agentName),
             };
         }
@@ -5546,6 +6324,9 @@ export class AgentFramework {
      * removed together. Discord originals get awareness markers via the outbox;
      * the batch is `explicit`-activated only after every removal succeeded, and
      * a crash mid-way is finished at next boot (resumePreparedDiscordSuppressions).
+     * Like rollbackToMessage, it returns once the body change has landed, with
+     * a marker-scheduling receipt (`markers`); delivery continues without the
+     * caller waiting on it.
      *
      * Not retroactive over derived state: a message already folded into an
      * autobiographical summary stays in that summary — roll back to before it
@@ -5596,9 +6377,12 @@ export class AgentFramework {
                 throw new OperatorActionError('invalid', 'Suppression branch name must differ from the active branch');
             }
             // Gate + reserve the whole store (see reserveStoreForSurgery); held
-            // until the fork is fully redacted or the source is restored.
+            // until the fork is fully redacted and its marker scheduling has been
+            // recorded or reported, or the source is restored. Remote delivery is
+            // not waited on.
             const release = this.reserveStoreForSurgery('suppress', agentName);
             let createdBranch;
+            let markers;
             try {
                 const markerBatch = this.discordAwarenessOutbox?.prepare({
                     agentName,
@@ -5638,8 +6422,6 @@ export class AgentFramework {
                         else
                             cm.removeMessage(iv.fromId);
                     }
-                    if (markerBatch)
-                        this.discordAwarenessOutbox.activate(markerBatch.id);
                 }
                 catch (error) {
                     // A partially suppressed branch is not safe to serve from. Keep it
@@ -5649,14 +6431,26 @@ export class AgentFramework {
                     const restored = await this.restoreSourceBranch(cm, sourceBranch, createdBranch, agentName);
                     throw new OperatorActionError('failed', `Suppression failed on ${createdBranch}; ${restored}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
                 }
-                await this.syncDiscordAwarenessMarkers();
+                // Every redaction committed: the body change has landed and the fork
+                // is safe to serve from. Activating the marker batch is bookkeeping
+                // about a world-side effect; if it fails, the suppression still
+                // stands, and the receipt says what became of the marks: not
+                // scheduled once the batch is retired, or unresolved if it can't be.
+                // (The batch's resume journal has nothing left to do, since every
+                // interval has committed, so retiring the batch gives up only the
+                // marks.)
+                markers = this.activateSurgeryMarkers(markerBatch, 'suppress', agentName);
+                // Installs the MCPL data-plane gate synchronously, before the store is
+                // released, and starts delivery without awaiting it (the first
+                // reaction request may already be on the wire when this returns).
+                this.startDiscordAwarenessDelivery('suppress', agentName);
                 this.materializeConfigMountAfterBranchSwitch();
             }
             finally {
                 release();
             }
             console.error(`[operator] suppress agent=${agentName} removed=${messagesRemoved} branch=${createdBranch} ` +
-                `by=${describeRequester(opts.requester)}`);
+                `marks=${describeMarkers(markers)} by=${describeRequester(opts.requester)}`);
             const loggedIds = capIds(removedIds);
             this.recordOperatorAction({
                 ...logBase,
@@ -5667,6 +6461,7 @@ export class AgentFramework {
                     removedIds: loggedIds.ids,
                     ...(loggedIds.truncated ? { removedIdsTruncated: true } : {}),
                     discordRefs: removedRefs.length,
+                    markers,
                 },
             });
             return {
@@ -5676,6 +6471,7 @@ export class AgentFramework {
                 messagesRemoved,
                 removedIds,
                 removedRefs,
+                markers,
                 lastVisible: await this.lastVisiblePreview(agentName),
             };
         }
@@ -5684,6 +6480,97 @@ export class AgentFramework {
             throw error;
         }
     }
+    /**
+     * Record a surgery's prepared marker batch as active once its body change
+     * has landed, and say what happened. Never throws: the body is already
+     * applied, so a ledger failure here is reported in the receipt rather than
+     * as a failed surgery an operator might retry. A batch that could not be
+     * activated is retired, so no later reconciliation can deliver it behind a
+     * receipt saying it was not scheduled (`not-scheduled`). If retiring fails
+     * too, the receipt says only that the outcome is `unresolved`: the batch is
+     * retained, and it may still be delivered. A rollback's batch
+     * (activated by target branch) may be promoted by the very next
+     * reconciliation, the one the delivery it starts runs; a suppression's
+     * (activated explicitly) waits for the next start.
+     *
+     * A batch with no refs (a suppression journal with nothing addressable) is
+     * still activated, which closes its resume journal. It schedules no marks,
+     * so it reports `none` whatever the ledger does. If it can be neither
+     * activated nor retired, its journal is left prepared and closes at the
+     * next start: every interval it names has already committed, so the resume
+     * skips them all and activates it.
+     */
+    activateSurgeryMarkers(batch, verb, agentName) {
+        if (!batch)
+            return { status: 'none', queued: 0 };
+        try {
+            this.discordAwarenessOutbox.activate(batch.id);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            let retired = false;
+            let retireDetail = '';
+            try {
+                retired = this.discordAwarenessOutbox.discard(batch.id);
+            }
+            catch (discardError) {
+                retireDetail = discardError instanceof Error ? discardError.message : String(discardError);
+            }
+            console.error(`[discord-awareness] ${verb} agent=${agentName}: body applied, but marker batch ${batch.id} ` +
+                `could not be activated (${detail}); ` +
+                (retired ? 'batch retired' : `batch retained${retireDetail ? ` (retire failed: ${retireDetail})` : ''}`));
+            if (batch.refs.length === 0)
+                return { status: 'none', queued: 0 };
+            this.opsAlert(retired ? 'discord-awareness-not-scheduled' : 'discord-awareness-unresolved', agentName, retired
+                ? `${verb} applied, but its ${batch.refs.length} awareness mark(s) were not scheduled ` +
+                    `(batch ${batch.id} retired): ${detail}`
+                : `${verb} applied, but awareness batch ${batch.id} (${batch.refs.length} mark(s)) could be ` +
+                    `neither activated nor retired; it may still be delivered: ${detail}`, { data: { batchId: batch.id, retired } });
+            return retired
+                ? { status: 'not-scheduled', queued: 0, error: detail }
+                : { status: 'unresolved', queued: 0, batchId: batch.id, error: detail };
+        }
+        if (batch.refs.length === 0)
+            return { status: 'none', queued: 0 };
+        return { status: 'queued', queued: batch.refs.length, batchId: batch.id };
+    }
+    /**
+     * Start awareness delivery after a branch move (a surgery, a switch, an
+     * undo or redo) without the caller awaiting it. No operator response waits
+     * for Discord to accept marks: the MCPL data-plane gate alone holds channel
+     * traffic that arrives after it until they are attempted.
+     * `syncDiscordAwarenessMarkers` installs that gate synchronously, before
+     * its first await, so calling this while a surgery still holds the store
+     * puts the gate up before the store is released. With no drain running, the
+     * drain starts in the same synchronous run (the first reaction request can
+     * be written before this returns); with one running, this generation's pass
+     * follows it (drainForGeneration). Either way delivery continues
+     * independently: the caller's response and any store reservation stop
+     * waiting on remote reactions. A turn may run during delivery when its wake
+     * carries no channel traffic (a scheduler timer, a provider admission), and
+     * also when its channel traffic was admitted before the gate went up
+     * (queued when a surgery began, or arriving during its switch or fork): the
+     * surgery's store reservation, which used to hold such a turn through the
+     * drain, now ends once the gate is up. A failure is accounted by the gate
+     * itself: the current generation's failure recycles the connections, and a
+     * superseded one leaves that to the newer generation, whose own pass meets
+     * the same ledger. Here it is logged and raised as an ops alert, and the
+     * next sync, reconnect or start delivers what is still pending.
+     *
+     * @param after What moved the branch, for the log and the alert
+     *   ("rollback", "branch switch", "undo" …).
+     * @param agentName The agent the move was for, or "framework" for a
+     *   branch switch that names none.
+     */
+    startDiscordAwarenessDelivery(after, agentName = 'framework') {
+        if (!this.discordAwarenessOutbox)
+            return;
+        this.syncDiscordAwarenessMarkers().catch((error) => {
+            const detail = error instanceof Error ? error.message : String(error);
+            console.error(`[discord-awareness] delivery after ${after} agent=${agentName} failed: ${detail}`);
+            this.opsAlert('discord-awareness-delivery', agentName, `Awareness mark delivery after ${after} failed: ${detail}`);
+        });
+    }
     /** Re-materialize config files from the (new) active branch — fire and
      *  forget; the gate picks changes up via mtime. Mirrors undoLastTurn. */
     materializeConfigMountAfterBranchSwitch() {
@@ -6068,7 +6955,7 @@ export class AgentFramework {
                     // divergence breaks the compile prefix).
                     const { blocks: toolResultContent, spilled } = await this.buildStoredToolResultContent(agent.name, currentState.toolResults, maxChars);
                     const membraneResults = currentState.toolResults.map(tc => this.toMembraneToolResult(tc.id, tc.result, maxChars, spilled.get(tc.id)));
-                    agent.toolResultGuard.storeResults(toolResultContent, membraneResults, currentState.toolResults, turnRowMetadata);
+                    agent.toolResultGuard.storeResults(toolResultContent, membraneResults, currentState.toolResults, turnRowMetadata, maxChars);
                     // Flush any messages that were deferred while this turn was in
                     // flight. Route to the PRIMARY agent — deferred messages are
                     // framework-level (module messages, push events, subagent return
@@ -6675,10 +7562,10 @@ export class AgentFramework {
                 isolate: true,
                 // Strategy instances are stateful — never share the template's.
                 strategy: router.strategyFactory?.() ?? new PassthroughStrategy(),
-                // Dynamic conversation forks retain the established provider policy in
-                // this bounded first slice. Provider cooldown ownership belongs to the
-                // persistent resident only; generation-unique forks must not leak gates.
-                membrane: this.membrane,
+                // Provider cooldown ownership belongs to the persistent resident only;
+                // generation-unique forks must not leak gates. A fork's own recorded
+                // provider waits still bind its compression calls.
+                membrane: this.conversationAuxiliaryMembraneFor(name),
                 debugLogContext: !!process.env.DEBUG_CONTEXT,
             });
             // Seed with the template's compiled context, renaming the template
@@ -6745,6 +7632,18 @@ export class AgentFramework {
         this.evictTurnCheckpoints(agentName);
         if (agent)
             this.logicalTurnToolCalls.delete(agent);
+        // A provider-wait hold (nonOwningProviderWait) goes with the agent: left,
+        // its timer would requeue held wakes for an agent that is gone, and a wait
+        // held until released would re-arm for the name indefinitely. The recorded
+        // wait stays, and binds the name if its channel binds again.
+        const cooldown = this.providerAccelerationCooldowns.get(agentName);
+        if (cooldown) {
+            clearTimeout(cooldown.timer);
+            this.providerAccelerationCooldowns.delete(agentName);
+            console.error(`[provider-wait] agent=${agentName} disposed while held` +
+                `${cooldown.waitModel !== undefined ? ` on ${cooldown.waitModel}` : ''}: ` +
+                `${cooldown.heldRequests.length} held request(s) dropped with it (the recorded wait stays)`);
+        }
         this.emitTrace({
             type: 'mcpl:conversation-disposed',
             agentName,
@@ -7587,7 +8486,10 @@ export class AgentFramework {
             }
             const providerCooldown = this.providerAccelerationCooldowns?.get(agentName);
             if (providerCooldown) {
-                if (now < providerCooldown.until || this.extendHostProviderHold(agentName, providerCooldown)) {
+                // A provider wait binds its own model; with a different primary model
+                // selected now, the turn proceeds (the wait stays recorded).
+                const otherModel = providerCooldown.waitModel !== undefined && providerCooldown.waitModel !== agent.model;
+                if (!otherModel && (now < providerCooldown.until || this.extendHostProviderHold(agentName, providerCooldown))) {
                     for (const req of requests) {
                         if (!providerCooldown.heldRequests.some((r) => this.sameInferenceRequest(r, req))) {
                             providerCooldown.heldRequests.push(req);
@@ -7608,6 +8510,13 @@ export class AgentFramework {
                     recovery.releasedAt = now;
                 requests = [...providerCooldown.heldRequests, ...requests];
             }
+            // A provider's stated wait on this agent's primary model, including one
+            // recorded before a restart, holds the turn until it passes. An
+            // ephemeral run records nothing, its name being single-use, so no wait,
+            // known or unreadable, binds it (as at the last boundary).
+            const providerWait = this.providerWaits?.active(agentName, agent.model);
+            if (providerWait && !this.ephemeralRuns.has(agentName) && this.holdForProviderWait(agent, providerWait, requests))
+                continue;
             // Skip if agent is busy (inferring, streaming, or waiting for tools) —
             // or if a turn is alive at all (activeTurnTokens): the state machine
             // goes idle at endTurn's reset while driveStream teardown is still
@@ -8325,6 +9234,13 @@ export class AgentFramework {
     }
     async startAgentStream(agent, trigger, attempt = 0, providerGateAlreadyHeld = false) {
         const ownsProviderGate = !this.ephemeralRuns.has(agent.name) && !this.conversationAgentHomes.has(agent.name);
+        // A stopping framework starts no turn, whoever owns provider admission
+        // (conversation agents and ephemeral runs do not take the gate).
+        if (this.providerAdmissionClosed) {
+            if (ownsProviderGate && providerGateAlreadyHeld)
+                this.releasePrimaryProviderGate(agent.name);
+            return;
+        }
         if (ownsProviderGate && !providerGateAlreadyHeld) {
             this.acquirePrimaryProviderGate(agent.name);
             const gate = this.providerGate(agent.name);
@@ -8371,7 +9287,7 @@ export class AgentFramework {
                     await this.startAgentStream(agent, trigger, attempt, true);
                 }).catch((error) => {
                     this.releasePrimaryProviderGate(agent.name);
-                    console.error(`[provider-cooldown] failed to resume primary for ${agent.name}:`, error);
+                    console.error(`[provider-cooldown] failed to resume primary for ${agent.name}: ${describeFailureWithFrames(error)}`);
                 });
                 return;
             }
@@ -8380,6 +9296,36 @@ export class AgentFramework {
                 return;
             }
         }
+        // The last admission boundary before this primary call. With the gate
+        // held and no auxiliary call in flight, no new provider wait can be
+        // recorded for this agent before the call (auxiliary admission waits on
+        // the gate). But one may have been recorded since the scheduler's check:
+        // an auxiliary call this wake parked behind can fail with a stated wait
+        // on the primary model. That wait binds this wake too: hold it, don't call.
+        // A conversation agent's waits are recorded and held as a resident's are
+        // (nonOwningProviderWait), and its retries and in-turn restarts reach this
+        // boundary without the scheduler: a wait recorded meanwhile, by its own
+        // auxiliary call or a non-retryable failure, binds them here too. An
+        // ephemeral run records nothing, so nothing binds it here. A frame whose
+        // agent was replaced or removed (a fork disposed while its retry slept)
+        // installs no hold: its turn is dropped after the compile, as main drops
+        // any such turn.
+        if (!this.ephemeralRuns.has(agent.name) && this.agents.get(agent.name) === agent) {
+            const wait = this.providerWaits?.active(agent.name, agent.model);
+            if (wait && this.holdForProviderWait(agent, wait, trigger ? [trigger] : [])) {
+                if (ownsProviderGate)
+                    this.releasePrimaryProviderGate(agent.name);
+                // A retry or an in-turn restart arrives with its turn still open at
+                // the event gate: the failed attempt, or the predecessor that kept
+                // liveness for it, leaves closing it to this frame. Held here, no
+                // frame would close it, and while it is open every gate event
+                // buffers, for every agent, until the wait ends.
+                this.eventGate?.onInferenceEnded(agent.name);
+                console.error(`[provider-wait] agent=${agent.name} model=${agent.model} binds at admission ` +
+                    `(recorded after the wake was scheduled); wake held, not started`);
+                return;
+            }
+        }
         // Mark the turn alive before ANYTHING awaits (hooks, compile, stream
         // setup): from here until this turn's teardown, cross-turn writers defer
         // (addMessage guard) instead of appending — nothing may enter the window
@@ -8728,6 +9674,28 @@ export class AgentFramework {
                 this.eventGate?.onInferenceEnded(agent.name);
                 return false;
             }
+            // A conversation agent takes no provider gate, so its own compression
+            // can record a wait while this turn compiles, after the last boundary
+            // checked. Check its waits again here, where nothing has been sent, and
+            // hold the turn as the boundary would rather than send it into the wait.
+            if (this.conversationAgentHomes.has(agent.name)) {
+                const wait = this.providerWaits?.active(agent.name, agent.model);
+                if (wait && this.holdForProviderWait(agent, wait, trigger ? [trigger] : [])) {
+                    console.error(`[provider-wait] agent=${agent.name} model=${agent.model} binds after the compile ` +
+                        `(recorded while the turn compiled); turn held, nothing sent`);
+                    // The turn emitted inference:started before its compile; every turn
+                    // that does gets one terminal event, which listeners (a typing loop)
+                    // rely on, as the failure sites' holds emit inference:failed.
+                    this.emitTrace({ type: 'inference:failed', agentName: agent.name, error: providerWaitText(agent.name, agent.model, wait) });
+                    stream.cancel();
+                    agent.cancelStream();
+                    this.activeStreams.delete(agent.name);
+                    this.pendingAssistantBlocks.delete(agent.name);
+                    this.channelRegistry?.stopTyping();
+                    this.eventGate?.onInferenceEnded(agent.name);
+                    return false;
+                }
+            }
             const handle = this.driveStream(agent, stream, requestSnapshot, trigger, attempt, compiledRequest, ownsProviderGate, takeKvSubmission, drainKvSubmissionIds, new Set(tools.map((tool) => tool.name)));
             this.activeStreams.set(agent.name, handle);
             // Handoff: driveStream captured the token in its synchronous prefix;
@@ -8753,9 +9721,27 @@ export class AgentFramework {
                 this.eventGate?.onInferenceEnded(agent.name);
                 return false;
             }
-            const action = this.errorPolicy.onInferenceError(err, agent.name, attempt);
+            const statedWait = ownsProviderGate ? undefined : this.nonOwningProviderWait(agent, err, trigger);
+            if (statedWait === 'held') {
+                // A conversation agent held by the provider's stated wait, as a
+                // resident is: the hold's release owns the later compile.
+                this.eventGate?.onInferenceEnded(agent.name);
+                return false;
+            }
+            const action = statedWait === 'fail' ? { retry: false } : this.errorPolicy.onInferenceError(err, agent.name, attempt);
             if (action.retry) {
-                await new Promise((resolve) => setTimeout(resolve, action.delayMs));
+                // A policy's delay can be a provider's retry-after: wait all of it.
+                await this.waitForRetry(action.delayMs);
+                if (this.providerAdmissionClosed) {
+                    // stop() ended the wait: that cancels the retry, it does not hasten
+                    // it. Nothing is written (the store is closing); this frame still
+                    // owns its token, since no retry frame replaced it.
+                    if (this.activeTurnTokens.get(agent.name) === turnToken) {
+                        this.activeTurnTokens.delete(agent.name);
+                        this.activeTurnTriggers.delete(agent.name);
+                    }
+                    return false;
+                }
                 // The retry re-enters startAgentStream, which replaces this frame's
                 // turn token with its own; cleanup belongs to the innermost frame.
                 await this.startAgentStream(agent, trigger, attempt + 1);
@@ -8773,16 +9759,18 @@ export class AgentFramework {
                 this.settleAgent(agent.name, {
                     stopReason: 'exhausted',
                     speech: '',
-                    error: err.message,
+                    error: statedWait === 'fail' ? this.statedWaitNotSlept(err) : err.message,
                 }, startLogical);
                 this.emitTrace({
                     type: 'inference:exhausted',
                     agentName: agent.name,
                     error: err.message,
-                    // Drives the poison-history breaker (`invalid_request`: a 400-class
-                    // rejection of the history itself — retrying the same context can
-                    // never succeed; auth/abort/context_length are also non-retryable
-                    // but must NOT cost history) and the OverBudget drain breaker
+                    // Drives the poison-history breaker (shedMayHelp: an
+                    // `invalid_request` at HTTP 400, 413 or 422 or with no status, or a
+                    // `context_length` at 413, suggests the provider refused the
+                    // request's content or size, which a shed of the newest exchange may
+                    // fix; auth/abort and other context_length failures are also
+                    // non-retryable but must NOT cost history) and the OverBudget drain breaker
                     // (`over_budget`: compile refused to fit the hard budget — this is
                     // the site that sees it, since compile runs before the stream
                     // exists). `retryable` is kept for observability.
@@ -9374,7 +10362,7 @@ export class AgentFramework {
                             if (readyState.status === 'ready') {
                                 const cap = this.resolveToolResultInlineCap(agent).cap;
                                 const { blocks: toolResultContent, spilled } = await this.buildStoredToolResultContent(agent.name, readyState.toolResults, cap);
-                                agent.toolResultGuard.storeResults(toolResultContent, readyState.toolResults.map((tc) => this.toMembraneToolResult(tc.id, tc.result, cap, spilled.get(tc.id))), readyState.toolResults, this.silentTurnRowMetadata(agent.name));
+                                agent.toolResultGuard.storeResults(toolResultContent, readyState.toolResults.map((tc) => this.toMembraneToolResult(tc.id, tc.result, cap, spilled.get(tc.id))), readyState.toolResults, this.silentTurnRowMetadata(agent.name), cap);
                                 // The response is already complete: this batch is never
                                 // submitted in this turn, so it cannot be refused. Admit it.
                                 agent.toolResultGuard.settleTurnEnded();
@@ -9597,7 +10585,7 @@ export class AgentFramework {
                             // border is close, rather than noise on every near-threshold
                             // flip. (It must not re-enter any agent's context — the emoji
                             // is suppressed at the surface via
-                            // DISCORD_SUPPRESS_REACTION_EMOJIS; without that, marking a
+                            // DISCORD_SUPPRESSED_REACTIONS_BASELINE; without that, marking a
                             // refusal feeds the next one.)
                             if (!handledByRewind) {
                                 void this.reactToRefusal(agent.name, category);
@@ -9869,25 +10857,39 @@ export class AgentFramework {
                                 this.eventGate?.onInferenceEnded(agent.name);
                             break;
                         }
-                        const action = this.errorPolicy.onInferenceError(err, agent.name, attempt);
+                        const statedWait = ownsProviderGate ? undefined : this.nonOwningProviderWait(agent, err, trigger);
+                        if (statedWait === 'held') {
+                            lifecyclePhase = 'failed';
+                            if (this.agents.get(agent.name) === agent && agent.streamId === myStreamId)
+                                this.eventGate?.onInferenceEnded(agent.name);
+                            break;
+                        }
+                        const action = statedWait === 'fail' ? { retry: false } : this.errorPolicy.onInferenceError(err, agent.name, attempt);
                         if (action.retry) {
-                            await new Promise((resolve) => setTimeout(resolve, action.delayMs));
-                            await this.startAgentStream(agent, trigger, attempt + 1);
+                            // A policy's delay can be a provider's retry-after: wait all of it.
+                            await this.waitForRetry(action.delayMs);
+                            // stop() ending the wait cancels the retry (this frame's finally
+                            // clears the token); it is never permission to retry at once.
+                            if (!this.providerAdmissionClosed)
+                                await this.startAgentStream(agent, trigger, attempt + 1);
                         }
                         else {
                             this.settleAgent(agent.name, {
                                 stopReason: 'exhausted',
                                 speech: '',
-                                error: err.message,
+                                error: statedWait === 'fail' ? this.statedWaitNotSlept(err) : err.message,
                             }, this.agents.get(agent.name) === agent && agent.streamId === myStreamId ? streamRouting.logical : undefined);
                             this.emitTrace({
                                 type: 'inference:exhausted',
                                 agentName: agent.name,
                                 error: err.message,
                                 // Drives the poison-history breaker. `retryable` is kept for
-                                // observability, but the breakers gate on `errorType` — only an
-                                // `invalid_request` (a 400-class rejection of the history
-                                // itself) means retrying the same context can never succeed.
+                                // observability, but the breaker gates on
+                                // shedMayHelp(errorType, httpStatus): only an `invalid_request`
+                                // at HTTP 400, 413 or 422 or with no status, or a
+                                // `context_length` at 413, suggests the provider refused the
+                                // request's content or size, which a shed of the newest
+                                // exchange may fix.
                                 ...this.classifyInferenceError(err),
                             });
                             if (this.agents.get(agent.name) === agent && agent.streamId === myStreamId)
@@ -10102,6 +11104,23 @@ export class AgentFramework {
                     this.eventGate?.onInferenceEnded(agent.name);
                 return;
             }
+            // The same rule for a turn that doesn't own provider admission as at
+            // the other two failure sites: a conversation agent's stated wait is
+            // recorded and its turn held; an ephemeral run whose wait it won't sleep
+            // says why it ends.
+            const statedWait = ownsProviderGate ? undefined : this.nonOwningProviderWait(agent, err, trigger);
+            if (statedWait === 'held') {
+                this.emitTrace({ type: 'inference:failed', agentName: agent.name, error: err.message, stack: err.stack });
+                this.logInference({ timestamp: startTime, agentName: agent.name, requestId, success: false,
+                    error: `Provider wait: ${err.message}`,
+                    request: compiledRequest ?? { note: 'streaming request rate-limited' }, durationMs });
+                this.abortAgentScript(agent.name, 'provider wait');
+                lifecyclePhase = 'failed';
+                agent.reset();
+                if (this.agents.get(agent.name) === agent && agent.streamId === myStreamId)
+                    this.eventGate?.onInferenceEnded(agent.name);
+                return;
+            }
             this.emitTrace({
                 type: 'inference:failed',
                 agentName: agent.name,
@@ -10111,7 +11130,7 @@ export class AgentFramework {
             this.settleAgent(agent.name, {
                 stopReason: 'exhausted',
                 speech: '',
-                error: err.message,
+                error: statedWait === 'fail' ? this.statedWaitNotSlept(err) : err.message,
             }, streamRouting.logical);
             this.emitTrace({
                 type: 'inference:exhausted',
@@ -11428,6 +12447,10 @@ export class AgentFramework {
     logInference(entry) {
         // Store large request/response as blobs
         const entryToStore = { ...entry };
+        // The failure text is stored inline in every record; the request that
+        // produced it is already stored separately as a blob.
+        if (typeof entryToStore.error === 'string')
+            entryToStore.error = boundFailureText(entryToStore.error);
         // Blob threshold: 10KB - typical context-heavy requests exceed this
         const BLOB_THRESHOLD = 10000;
         // Both branches persist the JSON view, never the live object: a compiled
@@ -11931,7 +12954,10 @@ export class AgentFramework {
         // without this the only durable record of a failed inference is a field in
         // llm-calls.jsonl — invisible to operator, agent, and monitoring.
         if (event.type === 'inference:exhausted') {
-            this.noteInferenceExhausted(event.agentName ?? 'unknown', event.error ?? 'unknown error', event.retryable, event.errorType);
+            this.noteInferenceExhausted(event.agentName ?? 'unknown', event.error ?? 'unknown error', event.retryable, event.errorType, {
+                httpStatus: event.httpStatus,
+                providerErrorCode: event.providerErrorCode,
+            });
         }
         else if (event.type === 'inference:completed') {
             // A successful response — even mid-turn between tool calls — proves the
@@ -11949,7 +12975,28 @@ export class AgentFramework {
             ...event,
             timestamp: Date.now(),
         };
-        for (const listener of this.traceListeners) {
+        // Listeners (web UI, subagent observers, host loggers) receive bounded
+        // failure text. An event's `error` and `stack` strings are whatever its
+        // source's Error carried, which for a provider failure can be an echo of
+        // the whole request.
+        const bounded = traceEvent;
+        if (typeof bounded.error === 'string')
+            bounded.error = boundFailureText(bounded.error);
+        if (typeof bounded.stack === 'string')
+            bounded.stack = boundFailureText(bounded.stack);
+        // An event goes to the subscriptions present when its delivery starts,
+        // each one only if it is still active when its turn comes, as the DOM's
+        // EventTarget delivers: a subscription made during delivery waits for the
+        // next event, and one removed during delivery is skipped if its turn
+        // hasn't come. Each onTrace call is a subscription of its own, so a
+        // function subscribed twice is called twice. Iterating the live array let
+        // an unsubscribe during delivery make the listener after the one being
+        // called miss the event, since splice shifts the rest under the iterator.
+        for (const registration of [...this.traceListeners]) {
+            if (!registration.active)
+                continue;
+            // Called as a plain function, as before, so the registration isn't its `this`.
+            const { listener } = registration;
             try {
                 listener(traceEvent);
             }
@@ -11972,15 +13019,18 @@ export class AgentFramework {
      *      inference, so this never causes a retry/wake loop.
      *   3. escalation — after N consecutive failures the agent is hard-down;
      *      log that loudly (a repeated identical failure is the textbook signal).
-     *   4. breaker — when the failures are an `invalid_request` (a 400-class
-     *      rejection of the history itself, e.g. corrupted tool_use/tool_result
-     *      pairing or an oversized attachment), retrying the same context can
-     *      never succeed: every new push event wakes the agent onto the same
-     *      poisoned history forever. At the hard-down threshold, automatically
-     *      quarantine: shed the newest complete exchange (the same forced-rewind
-     *      primitive `/unstick` uses — shedNewestTurn never orphans a
-     *      tool_use/thinking block) and retry, bounded by the same rewind cap so
-     *      the breaker can never eat the whole history.
+     *   4. breaker — when a failure at or past the hard-down threshold suggests
+     *      the provider refused the request's content or size (shedMayHelp:
+     *      an `invalid_request` at HTTP 400, 413 or 422 or with no status, or a
+     *      `context_length` at 413, such as a provider's answer to a corrupted
+     *      tool_use/tool_result pairing or an oversized attachment), retrying
+     *      the same context is likely to fail the same way, and every new push
+     *      event would wake the agent onto that same history. At the hard-down
+     *      threshold, automatically quarantine: shed the newest complete
+     *      exchange (the same forced-rewind primitive `/unstick` uses —
+     *      shedNewestTurn never orphans a tool_use/thinking block) and retry,
+     *      bounded by the same rewind cap so the breaker can never eat the
+     *      whole history.
      */
     /**
      * Live health snapshot for /healthz and doctor tooling: gate state, queued
@@ -12005,11 +13055,14 @@ export class AgentFramework {
                         primaryPending: gate?.primaryPending ?? false,
                         auxiliaryInFlight: gate?.auxiliaryInFlight ?? 0,
                         auxiliaryDeferred: gate?.deferredAuxiliary ?? 0,
-                        cooldownUntil: cooldown?.until ?? null,
+                        // Null while none, and while a provider wait holds until released.
+                        cooldownUntil: cooldown !== undefined && Number.isFinite(cooldown.until) ? cooldown.until : null,
                         cooldownReason: cooldown?.reason ?? null,
                         hostHold: cooldown?.hostHoldError !== undefined,
                         heldRequests: cooldown?.heldRequests.length ?? 0,
                         lastRecovery: this.providerAccelerationLastRecovery?.get(name) ?? null,
+                        /** Provider waits (stated retry-after) binding this agent now, per model. */
+                        providerWaits: this.providerWaitSnapshot(name).map(({ agent: _agent, ...wait }) => wait),
                     };
                 })(),
                 lastInference: this.lastInferenceAt.get(name) ?? null,
@@ -12024,8 +13077,12 @@ export class AgentFramework {
      *  and kind-specific fields (additive only — doctor parses by regex). */
     logFailure(record) {
         try {
+            // Every field is bounded: `reason` is conventionally free text, and any
+            // caller's field may carry an error message, or an Error whose own
+            // fields include the whole request.
+            const bounded = boundFailureFields(record);
             mkdirSync('logs', { recursive: true });
-            appendFileSync('logs/failures.log', JSON.stringify({ at: new Date().toISOString(), ...record }) + '\n');
+            appendFileSync('logs/failures.log', JSON.stringify({ at: new Date().toISOString(), ...bounded }) + '\n');
         }
         catch { /* best-effort */ }
     }
@@ -12048,11 +13105,25 @@ export class AgentFramework {
     notifyOps(kind, agentName, message, data) {
         this.opsAlert(kind, agentName, message, { data });
     }
-    opsAlert(kind, agentName, message, opts) {
+    opsAlert(kind, agentName, rawMessage, opts) {
+        // A JavaScript caller of notifyOps or notifyOpsAlert can pass a message
+        // that isn't a string; it's described as a thrown value is, rather than
+        // thrown on (a string is its own description).
+        const wholeMessage = failureDescription(rawMessage);
+        const message = boundFailureText(wholeMessage);
+        // The caller's data goes to failures.log and to trace listeners, bounded
+        // the same way for both. A JavaScript caller's null is no data, and data
+        // that isn't a plain object (a string, an array, a Buffer) is kept as one
+        // field, `data`, rather than spread into a field per character or element.
+        const rawData = opts?.data;
+        const plain = typeof rawData === 'object' && rawData !== null &&
+            [Object.prototype, null].includes(Object.getPrototypeOf(rawData));
+        const data = rawData == null ? undefined
+            : boundFailureFields(plain ? rawData : { data: rawData });
         if (!opts?.skipLog) {
-            this.logFailure({ agent: agentName, kind, reason: message, ...opts?.data });
+            this.logFailure({ agent: agentName, kind, reason: message, ...data });
         }
-        this.emitTrace({ type: 'ops:alert', kind, agentName, message, data: opts?.data });
+        this.emitTrace({ type: 'ops:alert', kind, agentName, message, data });
         const hook = process.env.CONNECTOME_OPS_WEBHOOK;
         if (!hook)
             return;
@@ -12066,7 +13137,7 @@ export class AgentFramework {
             method: 'POST',
             headers: { 'content-type': 'application/json' },
             body: JSON.stringify({
-                content: `\u{1F6A8} **${agentName}** ${kind}: ${message.slice(0, 500)}`,
+                content: `\u{1F6A8} **${agentName}** ${kind}: ${boundFailureText(wholeMessage, OPS_WEBHOOK_MESSAGE_MAX_CHARS)}`,
             }),
         }).catch((err) => console.error(`[ops-alert] webhook post failed (${key}):`, err instanceof Error ? err.message : err));
     }
@@ -12103,9 +13174,12 @@ export class AgentFramework {
     }
     /**
      * Classify a terminal inference error for the `inference:exhausted` trace.
-     * Single-sourced for every emit site: the downstream breakers (poison-history
-     * quarantine, OverBudget drain kick) gate on `errorType`, so classification
-     * drift between sites would silently disable a safety net.
+     * Single-sourced for every emit site that has an error to classify (a
+     * stream the framework aborted has none): the downstream breakers gate on
+     * what it returns (the poison-history quarantine on `errorType` and
+     * `httpStatus`, through shedMayHelp; the OverBudget drain kick on
+     * `errorType`), so classification drift between sites would silently
+     * change when a safety net acts.
      *
      * context-manager's refusal errors are matched by a real `instanceof` since
      * CM exports them from its package root (context-manager#41 / #71; floor
@@ -12117,8 +13191,18 @@ export class AgentFramework {
      * can be reworded without warning.
      */
     classifyInferenceError(err) {
-        if (err instanceof MembraneError) {
-            return { retryable: err.retryable, errorType: err.type };
+        // From either copy of membrane (isMembraneError). The fields are read as
+        // data, and the type is bounded like describeFailure's, for every sink the
+        // classification reaches (the trace, the marker, the logs).
+        if (isMembraneError(err)) {
+            const fields = err;
+            const providerErrorCode = boundProviderErrorCode(fields.providerErrorCode);
+            return {
+                ...(typeof fields.retryable === 'boolean' ? { retryable: fields.retryable } : {}),
+                ...(typeof fields.type === 'string' ? { errorType: boundFailureText(fields.type, PROVIDER_ERROR_CODE_MAX_CHARS) } : {}),
+                ...(typeof fields.httpStatus === 'number' ? { httpStatus: fields.httpStatus } : {}),
+                ...(providerErrorCode !== undefined ? { providerErrorCode } : {}),
+            };
         }
         if (err instanceof OverBudgetError || err.name === 'OverBudgetError') {
             return { errorType: 'over_budget' };
@@ -12142,31 +13226,72 @@ export class AgentFramework {
     notifyOpsAlert(kind, agentName, message, data) {
         this.opsAlert(kind, agentName, message, { data });
     }
-    noteInferenceExhausted(agentName, reason, retryable, errorType) {
+    noteInferenceExhausted(agentName, rawReason, retryable, rawErrorType, detail) {
+        // The reason is the failure's own message, and a provider can echo the
+        // whole rejected request in it: one household's [inference-failed]
+        // marker carried ~1.7 MB of its own request back into its context. Every
+        // sink below gets an excerpt cut from the whole reason at its own bound
+        // (boundFailureText, so its marker states the whole length): the stderr
+        // line, failures.log and the hard-down alert FAILURE_TEXT_MAX_CHARS, the
+        // [inference-failed] marker FAILURE_MARKER_REASON_MAX_CHARS, the status's
+        // lastError and the compile-refused alert FAILURE_SUMMARY_MAX_CHARS, and
+        // the rewind marker REWIND_MARKER_REASON_MAX_CHARS. The classification
+        // travels as structured fields beside the text.
+        //
+        // A reason that isn't a string (the stream paths always pass a message)
+        // is described rather than allowed to throw before anything is recorded.
+        // Its whole description is the whole reason, cut once by each sink.
+        const wholeReason = typeof rawReason === 'string' ? rawReason : failureDescription(rawReason);
+        // The type is bounded wherever it's written, as classifyInferenceError
+        // bounds the types it reads, since a caller can pass one it didn't classify.
+        const errorType = typeof rawErrorType === 'string'
+            ? boundFailureText(rawErrorType, PROVIDER_ERROR_CODE_MAX_CHARS) : rawErrorType;
+        const reason = boundFailureText(wholeReason);
+        const markerReason = boundFailureText(wholeReason, FAILURE_MARKER_REASON_MAX_CHARS);
+        const httpStatus = typeof detail?.httpStatus === 'number' ? detail.httpStatus : undefined;
+        const providerErrorCode = boundProviderErrorCode(detail?.providerErrorCode);
+        const classification = {
+            ...(errorType !== undefined ? { errorType } : {}),
+            ...(retryable !== undefined ? { retryable } : {}),
+            ...(httpStatus !== undefined ? { httpStatus } : {}),
+            ...(providerErrorCode !== undefined ? { providerErrorCode } : {}),
+        };
+        // Each excerpt says how long the whole was when it was cut.
+        const cutAt = (excerpt) => excerpt === wholeReason ? {} : { reasonChars: wholeReason.length };
         const streak = (this.consecutiveInferenceFailures.get(agentName) ?? 0) + 1;
         this.consecutiveInferenceFailures.set(agentName, streak);
-        this.lastInferenceAt.set(agentName, { ...this.lastInferenceAt.get(agentName), failedAt: Date.now(), lastError: reason.slice(0, 300) });
+        this.lastInferenceAt.set(agentName, { ...this.lastInferenceAt.get(agentName), failedAt: Date.now(), lastError: boundFailureText(wholeReason, FAILURE_SUMMARY_MAX_CHARS) });
         // (1) Durable stderr line — works in headless/daemon mode with no client.
-        console.error(`[inference-failed] agent=${agentName} consecutive=${streak}: ${reason}`);
+        const labels = [
+            errorType !== undefined ? `type=${errorType}` : undefined,
+            httpStatus !== undefined ? `status=${httpStatus}` : undefined,
+            providerErrorCode !== undefined ? `code=${providerErrorCode}` : undefined,
+        ].filter((label) => label !== undefined);
+        console.error(`[inference-failed] agent=${agentName} consecutive=${streak}` +
+            `${labels.length > 0 ? ` ${labels.join(' ')}` : ''}: ${reason}`);
         // (1b) Machine-greppable durable record, independent of journald/unit log
         // redirects: logs/failures.log under the host's working directory. This is
-        // what connectome-doctor reads. Legacy fields kept; `kind` is additive.
-        this.logFailure({ agent: agentName, consecutive: streak, reason, kind: 'inference-exhausted' });
+        // what connectome-doctor reads. Legacy fields kept; `kind` and the
+        // classification fields are additive.
+        this.logFailure({ agent: agentName, consecutive: streak, reason, kind: 'inference-exhausted', ...classification, ...cutAt(reason) });
         // (2) Agent-facing chronicle marker (no inference triggered → no loop).
         const agent = this.agents.get(agentName);
         if (agent && process.env.SUPPRESS_INFERENCE_FAILED_MARKER !== '1') {
+            const cause = [errorType, httpStatus !== undefined ? `HTTP ${httpStatus}` : undefined]
+                .filter((part) => part !== undefined)
+                .join(', ');
             try {
                 agent.getContextManager().addMessage('user', [{
                         type: 'text',
                         text: `[inference-failed] Your previous turn did not complete: the model ` +
-                            `call failed and produced no response, so nothing was sent. Reason: ` +
-                            `${reason}. If this recurs with the same cause, change approach ` +
+                            `call failed${cause ? ` (${cause})` : ''} and produced no response, so nothing was sent. Reason: ` +
+                            `${markerReason}. If this recurs with the same cause, change approach ` +
                             `rather than retrying identically (e.g. drop an oversized attachment ` +
                             `or an unsupported setting).`,
-                    }], { system: true, kind: 'inference-failed', reason, consecutive: streak });
+                    }], { system: true, kind: 'inference-failed', reason: markerReason, consecutive: streak, ...classification, ...cutAt(markerReason) });
             }
             catch (err) {
-                console.error(`[inference-failed] could not record chronicle marker for ${agentName}:`, err);
+                console.error(`[inference-failed] could not record chronicle marker for ${agentName}: ${describeFailureWithFrames(err)}`);
             }
         }
         // (2b) OverBudget deadlock breaker. When compile fails with
@@ -12184,16 +13309,22 @@ export class AgentFramework {
         // (e.g. a reason string that crossed a serialization boundary). It matches
         // CM's current OverBudgetError wording and MAY rot if CM rewords it — the
         // errorType gate is the one that's load-bearing.
+        //
+        // The fallback applies only to an unclassified reason. A classified
+        // failure (a provider's 400, say) already says what it is, and its
+        // message is the provider's text, which can quote anything, including
+        // these phrases from the agent's own context.
         const overBudget = errorType === 'over_budget' ||
             errorType === 'context_refusal' ||
-            /exceed hard budget|no summary covers/i.test(reason);
+            // Decided on the whole reason: presentation bounds never change it.
+            (errorType === undefined && /exceed hard budget|no summary covers/i.test(wholeReason));
         // Observability: a refused compile means the agent cannot think AT ALL
         // this turn — surface it on the ops-alert pipeline (ops:alert trace +
         // webhook → fleet-watch) immediately, not only at the hard-down streak.
         // The per-(agent,kind) cooldown throttles repeats; failures.log already
         // has the per-exhaustion record from logFailure above.
         if (overBudget) {
-            this.opsAlert('context-refusal', agentName, `compile refused (${errorType ?? 'unclassified'}): ${reason.slice(0, 300)} — ` +
+            this.opsAlert('context-refusal', agentName, `compile refused (${errorType ?? 'unclassified'}): ${boundFailureText(wholeReason, FAILURE_SUMMARY_MAX_CHARS)} — ` +
                 `drain breaker ${agent ? 'kicking' : 'unavailable (no agent handle)'}; ` +
                 `if this persists, raise contextBudgetTokens or overBudgetGraceRatio.`, { skipLog: true });
         }
@@ -12210,7 +13341,7 @@ export class AgentFramework {
                     console.error(`[inference-failed] drain kicked for ${agentName} (OverBudget breaker, ${ticks} ticks)`);
                 }
                 catch (err) {
-                    console.error(`[inference-failed] drain kick failed for ${agentName} after ${ticks} ticks:`, err);
+                    console.error(`[inference-failed] drain kick failed for ${agentName} after ${ticks} ticks: ${describeFailureWithFrames(err)}`);
                 }
                 finally {
                     this.overBudgetDrainInFlight.delete(agentName);
@@ -12224,18 +13355,26 @@ export class AgentFramework {
             // Ops alert (webhook + ops:alert trace), throttled per (agent, kind) —
             // a hard-down agent re-posts every ~15 min, not on every failed retry.
             // failures.log already got the per-exhaustion record above.
-            this.opsAlert('hard-down', agentName, `${streak} consecutive inference failures. Last reason: ${reason}`, { skipLog: true });
-            // (4) Poison-history breaker: ONLY for `invalid_request` — a 400-class
-            // rejection of the history itself. Deliberately NOT keyed on
-            // `retryable === false`, which membrane also returns for auth (expired
-            // key), abort (deliberate cancel), context_length (compression's job,
-            // and shedding newest is the wrong direction), safety and unsupported —
-            // none of which mean the history is poisoned, and all of which would
-            // otherwise shed good exchanges and stamp a false "the API kept
-            // rejecting your history" marker. `retryable` is kept only for the trace.
+            // The excerpt leaves room for the prefix, so the alert's own bound
+            // never cuts it a second time.
+            const hardDown = `${streak} consecutive inference failures. Last reason: `;
+            this.opsAlert('hard-down', agentName, hardDown + boundFailureText(wholeReason, FAILURE_TEXT_MAX_CHARS - hardDown.length), { skipLog: true });
+            // (4) Poison-history breaker: ONLY when shedMayHelp(errorType,
+            // httpStatus) holds, for an `invalid_request` at HTTP 400, 413 or 422 or
+            // with no status, or a `context_length` at 413, which suggests the
+            // provider refused the request's content or size. The current failure
+            // decides, whatever failed before it in the streak. Deliberately NOT
+            // keyed on `retryable === false`, which membrane also returns for auth
+            // (expired key), abort (deliberate cancel), a context_length at 400 or
+            // 422 (a token overflow, which the context budget exists to prevent;
+            // shedding the newest exchange is the wrong direction for it), safety
+            // and unsupported. For none of them is shedding the newest exchange
+            // likely to help, and each would otherwise shed good exchanges and
+            // stamp a rewind marker saying the API kept refusing them.
+            // `retryable` is kept only for the trace.
             void retryable;
-            if (errorType === 'invalid_request' && agent) {
-                this.quarantinePoisonedHistory(agent, reason);
+            if (agent && shedMayHelp(errorType, httpStatus)) {
+                this.quarantinePoisonedHistory(agent, wholeReason);
             }
         }
     }
@@ -12245,14 +13384,14 @@ export class AgentFramework {
      * primitives as the refusal auto-rewind / `/unstick` (shedNewestTurn +
      * the single consolidated episode marker) — and queues a retry so the
      * rewound history is verified immediately instead of waiting for the next
-     * push event to wake the agent onto the same poisoned context.
+     * push event to wake the agent onto the same context.
      *
      * Bounded: at most `refusalHandling.maxRewinds` (default 3, hard cap 10)
      * sheds per failure episode; the budget resets on any successful inference.
      * At the cap (or with nothing left to shed) it stops — the agent stays up
      * and hard-down logging continues, but no further history is consumed.
      */
-    quarantinePoisonedHistory(agent, reason) {
+    quarantinePoisonedHistory(agent, wholeReason) {
         const cap = Math.max(1, Math.min(10, agent.refusalHandling?.maxRewinds ?? 3));
         const used = this.exhaustionRewinds.get(agent.name) ?? 0;
         if (used >= cap) {
@@ -12267,7 +13406,7 @@ export class AgentFramework {
             return;
         }
         this.exhaustionRewinds.set(agent.name, used + 1);
-        const count = this.updateRewindMarker(agent, truncateReason(reason), 'inference-failure');
+        const count = this.updateRewindMarker(agent, boundFailureText(wholeReason, REWIND_MARKER_REASON_MAX_CHARS), 'inference-failure');
         console.error(`[inference-rewind] agent=${agent.name} auto-quarantined ${rec.descriptor} ` +
             `(${count} turn(s) shed this episode, cap ${cap}) after non-retryable ` +
             `inference failures — retrying on the rewound history.`);
@@ -12461,7 +13600,11 @@ export class AgentFramework {
         // Discover tools from all connected servers
         await this.refreshMcplTools();
     }
-    /** Reconcile the durable ledger with Chronicle, then deliver every server's work. */
+    /**
+     * Reconcile the durable ledger with Chronicle, then deliver every server's
+     * work. A drain still running is waited for and then followed by a fresh
+     * pass (drainForGeneration).
+     */
     async syncDiscordAwarenessMarkers(_onlyServerId) {
         if (!this.discordAwarenessOutbox)
             return;
@@ -12629,34 +13772,66 @@ export class AgentFramework {
             throw new DiscordAwarenessAccountingError('branch reconciliation', error);
         }
         const pending = this.readDiscordAwarenessPending();
-        if (pending.length === 0) {
+        // A drain that is still running holds operations it read before this
+        // reconciliation, and it sends them whatever the ledger now says. A branch
+        // move can hide them from `pending`: restoring a rollback's source makes
+        // its marks undesired, and an add whose reply has not arrived is not yet
+        // present, so the ledger shows nothing to do while the drain goes on to
+        // send its saved adds and then the removals they need. So a generation
+        // accounts for every running drain as well as for every pending
+        // operation, and waits for those drains instead of releasing the data
+        // planes beside them (drainForGeneration).
+        const serverIds = [...new Set([
+                ...pending.map((operation) => operation.ref.serverId),
+                ...this.discordAwarenessDrains.keys(),
+            ])];
+        if (serverIds.length === 0) {
             return {
                 requiresBarrier: false,
                 promise: Promise.resolve({ status: 'delivered', delivered: 0, failed: 0 }),
             };
         }
-        const serverIds = [...new Set(pending.map((operation) => operation.ref.serverId))];
-        const promise = Promise.all(serverIds.map((serverId) => this.drainDiscordAwarenessOutbox(serverId))).then((outcomes) => {
-            if (outcomes.every((outcome) => outcome.status === 'unavailable')) {
-                return {
-                    status: 'unavailable',
-                    accounted: outcomes.reduce((count, outcome) => count + (outcome.status === 'unavailable' ? outcome.accounted : 0), 0),
-                };
-            }
-            return {
-                status: 'delivered',
-                delivered: outcomes.reduce((count, outcome) => count + (outcome.status === 'delivered' ? outcome.delivered : 0), 0),
-                failed: outcomes.reduce((count, outcome) => count + (outcome.status === 'delivered' ? outcome.failed : 0), 0),
-            };
-        });
+        const promise = Promise.all(serverIds.map((serverId) => this.drainForGeneration(serverId))).then(combineDrainOutcomes);
         return { requiresBarrier: true, promise };
     }
+    /**
+     * One server's drain for a new generation: a gate completes only after
+     * every operation pending when it was armed has been attempted. A drain
+     * already running can't promise that. It never re-sends a key it has
+     * attempted, so an operation re-pended while it runs (a rollback, its undo,
+     * then a redo, all mid-drain) stays pending, and it may already have made
+     * its last read of the ledger, missing a batch activated since. So a
+     * generation that finds a drain running waits for it, then drains again
+     * with a fresh pass that reads the ledger anew. Two generations waiting on
+     * the same drain share the fresh pass that follows it.
+     */
+    drainForGeneration(serverId) {
+        const running = this.discordAwarenessDrains.get(serverId);
+        if (!running)
+            return this.drainDiscordAwarenessOutbox(serverId);
+        return running.then((first) => this.drainDiscordAwarenessOutbox(serverId)
+            .then((fresh) => combineDrainOutcomes([first, fresh])));
+    }
+    /**
+     * Wait out the awareness gate for an inbound event: the generation current
+     * now, and any generation installed while waiting, until none is current
+     * or the current one is one already waited for. A handler that waited only
+     * for the generation it first saw would go on behind a newer one armed
+     * meanwhile. Rejects as the generation it waited for rejects.
+     */
+    async awaitDiscordAwarenessBarriers() {
+        let waited = null;
+        for (let barrier = this.discordAwarenessBarrier; barrier && barrier !== waited; barrier = this.discordAwarenessBarrier) {
+            waited = barrier;
+            await barrier.promise;
+        }
+    }
     /**
      * Install one framework-global Discord-awareness generation before releasing
-     * any inference-bearing event. With pending work, every MCPL data plane is
-     * paused while all control planes remain live. With no pending work, ready()
-     * runs synchronously so request responders preserve their historical
-     * same-stack behavior.
+     * any inference-bearing event. With pending work or a drain still running,
+     * every MCPL data plane is paused while all control planes remain live.
+     * With neither, ready() runs synchronously so request responders preserve
+     * their historical same-stack behavior.
      */
     installMcplDataPlaneGate() {
         for (const connection of this.mcplServerRegistry?.getAllServers() ?? []) {
@@ -12744,6 +13919,13 @@ export class AgentFramework {
         if (!this.mcplServerRegistry || !this.mcplHostCapabilities) {
             throw new Error('MCPL subsystem is not initialized');
         }
+        // Every connect needs a readable awareness ledger: a runtime connect's
+        // awareness barrier reconciles it, and a stdio child taking the
+        // protective default derives that from it. Read it first, so an
+        // unreadable ledger refuses the connect before anything is registered
+        // under its id or spawned (a reconnecting server would otherwise be left
+        // registered as a closed stub). With no outbox configured nothing is read.
+        this.getPlacedReactionBaseline();
         // Register prefix + config for tool dispatch routing (idempotent with
         // the pre-registration pass in initializeMcpl).
         const prefix = config.toolPrefix ?? `mcpl--${config.id}`;
@@ -12754,7 +13936,31 @@ export class AgentFramework {
         if (this.channelRegistry) {
             this.channelRegistry.setSubscriptionPolicy(config.id, config.channelSubscription ?? 'manual');
         }
-        const connection = await this.mcplServerRegistry.addServer(config, this.mcplHostCapabilities);
+        // A stdio child's protective reaction default, DISCORD_SUPPRESSED_REACTIONS_BASELINE
+        // (WebSocket servers own their environment outside this process). The
+        // caller's config stays unchanged, so a runtime restart derives afresh.
+        // The default is derived at each spawn: the env below is a getter, which
+        // the transport reads at first connect, at every automatic reconnect and
+        // at a stub's retry, so retained markers added since the last spawn are
+        // covered.
+        let connectionConfig = config;
+        if (!isWebSocketTransport(config)) {
+            const declared = this.declaredReactionBaseline(config);
+            if (declared) {
+                console.error(`[mcpl] ${config.id}: DISCORD_SUPPRESSED_REACTIONS_BASELINE ${declared.source === 'env' ? 'from its env' : 'inherited from the host'} ` +
+                    `replaces the framework's protective default`);
+            }
+            connectionConfig = { ...config };
+            Object.defineProperty(connectionConfig, 'env', {
+                enumerable: true,
+                configurable: true,
+                get: () => ({
+                    ...config.env,
+                    DISCORD_SUPPRESSED_REACTIONS_BASELINE: declared?.value ?? this.getPlacedReactionBaseline().join(','),
+                }),
+            });
+        }
+        const connection = await this.mcplServerRegistry.addServer(connectionConfig, this.mcplHostCapabilities);
         // Wire listeners before either startup staging or the runtime global gate
         // releases control traffic needed for registration and marker service.
         this.wireMcplEvents(connection);
@@ -13076,6 +14282,91 @@ export class AgentFramework {
     // ==========================================================================
     // Runtime MCPL server lifecycle (agent-facing hot deploy/restart/unload)
     // ==========================================================================
+    /**
+     * Snapshot the protective Discord reaction default for this deployment, as
+     * suppression tokens: the forms the Discord adapter's suppression matcher
+     * reads, not marker payloads for an add, a remove or a replay. It covers
+     * the reactions the framework places: refusal markers, the adapter's own
+     * default awareness marker, the configured awareness marker, and retained
+     * outbox markers (including offline recovery choices and marks that can
+     * later be removed or replayed). A custom emoji appears as its bare ID,
+     * which suppression matches even after a rename; stored markers and the
+     * actual add/remove payloads stay unchanged. Explicit adapter or operator
+     * suppression settings still take precedence. Throws on an unreadable
+     * ledger rather than reporting a partial baseline.
+     */
+    getPlacedReactionBaseline() {
+        let retained;
+        try {
+            retained = this.discordAwarenessOutbox?.batches().map((batch) => batch.emoji) ?? [];
+        }
+        catch (error) {
+            throw new DiscordAwarenessAccountingError('reaction-baseline ledger read', error);
+        }
+        // Discord events carry the custom emoji's name and ID separately. Full
+        // marker forms belong in add/remove calls, but suppression matches their
+        // stable ID (including after a rename), rather than the composite token.
+        const suppressionToken = (emoji) => {
+            const custom = /^(?:<a?:\w+:(\d{17,20})>|(?:a:)?\w+:(\d{17,20}))$/.exec(emoji.trim());
+            return custom?.[1] ?? custom?.[2] ?? emoji;
+        };
+        return [...new Set([
+                ...REFUSAL_REACTION_BASELINE,
+                DEFAULT_DISCORD_AWARENESS_EMOJI,
+                this.discordAwarenessEmoji,
+                ...retained,
+            ].map(suppressionToken))].filter((emoji) => emoji.length > 0);
+    }
+    /**
+     * The reaction baseline an operator chose for a stdio server, if any: a
+     * value declared in its env, or one inherited from the host with
+     * `inheritEnv`, the declared one first. A value with no tokens, as
+     * discord-mcpl's parser reads them, counts as unset: the adapter splits on
+     * commas and keeps a token only when its normalizer leaves something of it
+     * (blank, `:`, `::` and a lone U+FE0F leave nothing), so such a value (an
+     * empty systemd `Environment=`, say, or `${A},${B}` or `:${NAME}:` with the
+     * variables empty) would otherwise turn the protective default off without
+     * anyone choosing that.
+     *
+     * Windows names are matched in both sources: Workers expose a case-
+     * sensitive `process.env` copy. Within one source, Node's spawn keeps the
+     * first spelling in sorted order, so each source is resolved that way.
+     *
+     * A value is read as the child will see it. A config loaded from JSON can
+     * carry a non-string there despite the type, and spawn writes every
+     * defined value as its string form, so a number is a declared value, not a
+     * failed connect. A null counts as unset, like a blank: written in JSON it
+     * means no value, and read as spawn's "null" it would replace the
+     * protective default with a list that suppresses nothing.
+     */
+    declaredReactionBaseline(config) {
+        // A token as discord-mcpl's parser keeps one: `parseSuppressionEnvTokens`
+        // trims each comma-separated token and keeps it when
+        // `normalizeReactionEmoji` (discord-mcpl `src/filters.ts`) leaves
+        // something, after it strips U+FE0F, trims, and strips one leading and one
+        // trailing colon. The same steps in the same order, so the two can be
+        // compared when either changes.
+        const isToken = (token) => token.trim().replace(/\uFE0F/g, '').trim().replace(/^:|:$/g, '') !== '';
+        const valueIn = (env) => {
+            let raw;
+            if (process.platform !== 'win32')
+                raw = env?.DISCORD_SUPPRESSED_REACTIONS_BASELINE;
+            else {
+                const key = Object.keys(env ?? {}).sort()
+                    .find((name) => name.toUpperCase() === 'DISCORD_SUPPRESSED_REACTIONS_BASELINE');
+                raw = key === undefined ? undefined : env?.[key];
+            }
+            if (raw === undefined || raw === null)
+                return undefined;
+            const value = String(raw);
+            return value.split(',').some(isToken) ? value : undefined;
+        };
+        const declared = valueIn(config.env);
+        if (declared !== undefined)
+            return { value: declared, source: 'env' };
+        const inherited = config.inheritEnv ? valueIn(process.env) : undefined;
+        return inherited !== undefined ? { value: inherited, source: 'inherited' } : undefined;
+    }
     /**
      * Connect a new MCPL server at runtime. Refreshes the tool list and
      * notifies the agent of newly available tools. Throws if the MCPL
@@ -13141,6 +14432,12 @@ export class AgentFramework {
         if (!config) {
             throw new Error(`MCPL server "${id}" is not configured`);
         }
+        // Every connect reads the awareness ledger: its awareness barrier
+        // reconciles it, and a stdio child taking the protective default derives
+        // that from it. Read it before disconnecting, so an unreadable ledger
+        // refuses the restart and leaves the running child up, whatever the
+        // server's baseline or transport. (No outbox configured: nothing to read.)
+        this.getPlacedReactionBaseline();
         await this.disconnectMcplServer(id);
         await this.connectMcplServer(config);
     }
@@ -13207,9 +14504,11 @@ export class AgentFramework {
         connection.on('push-event', async (params, responder) => {
             const answer = answerOnce(responder, 'push/event', connection.id);
             try {
-                const barrier = this.discordAwarenessBarrier;
-                if (barrier)
-                    await barrier.promise;
+                // Only when a generation is current: with none, the event is handled in
+                // the turn it arrives, as it always was (the push coalescer's ordering of
+                // a push against its retraction depends on that).
+                if (this.discordAwarenessBarrier)
+                    await this.awaitDiscordAwarenessBarriers();
                 // Checked here, after the barrier and before anything records the
                 // push as accepted: a stopped host refuses it.
                 if (this.queue?.isClosed) {
@@ -13237,9 +14536,8 @@ export class AgentFramework {
             if (this.inferenceRouter && responder) {
                 const answer = answerOnce(responder, 'inference/request', connection.id);
                 try {
-                    const barrier = this.discordAwarenessBarrier;
-                    if (barrier)
-                        await barrier.promise;
+                    if (this.discordAwarenessBarrier)
+                        await this.awaitDiscordAwarenessBarriers();
                     // A stopping host starts no inference for a server: refused, like a
                     // push, before the router runs.
                     if (this.queue?.isClosed) {
@@ -13331,9 +14629,8 @@ export class AgentFramework {
         connection.on('channels-incoming', async (params, responder) => {
             const answer = answerOnce(responder, 'channels/incoming', connection.id);
             try {
-                const barrier = this.discordAwarenessBarrier;
-                if (barrier)
-                    await barrier.promise;
+                if (this.discordAwarenessBarrier)
+                    await this.awaitDiscordAwarenessBarriers();
                 if (this.queue?.isClosed) {
                     this.refuseServerItem('channels/incoming', connection.id, answer, { kind: 'refused' });
                     return;
@@ -13350,9 +14647,8 @@ export class AgentFramework {
                 return;
             const answer = answerOnce(responder, 'host/command', connection.id);
             try {
-                const barrier = this.discordAwarenessBarrier;
-                if (barrier)
-                    await barrier.promise;
+                if (this.discordAwarenessBarrier)
+                    await this.awaitDiscordAwarenessBarriers();
                 // A stopping host runs no host command: refused like the requests
                 // above, before its handler runs.
                 if (this.queue?.isClosed) {
@@ -13394,7 +14690,7 @@ export class AgentFramework {
             // grant) before the data-plane barrier releases — otherwise the first
             // post-reconnect events land while the grant is still empty and are
             // rejected fail-closed instead of delivered.
-            void (async () => {
+            const reregistered = (async () => {
                 try {
                     const config = this.mcplServerConfigs.get(connection.id);
                     if (config) {
@@ -13407,7 +14703,11 @@ export class AgentFramework {
                 this.releaseMcplDataPlaneGate(awarenessBarrier);
                 this.handleToolsListChanged(connection.id);
             })();
-            void awarenessBarrier.promise.then(() => {
+            // The gate completes, and the data planes go ready, only once both the
+            // awareness drain and the re-registration have finished. A drain can
+            // settle first (one already running, or little to send), and the grant
+            // must exist before the first data-plane event flows.
+            void Promise.all([awarenessBarrier.promise, reregistered]).then(() => {
                 if (awarenessBarrier.requiresBarrier
                     && !this.completeMcplDataPlaneGate(awarenessBarrier))
                     return;
@@ -14466,9 +15766,21 @@ export class AgentFramework {
                         };
                     }
                     if (candidate.kind === 'reference') {
+                        // Point at fetch_reference only where it can deliver: not for a
+                        // reference this process holds no record of (fetch_reference
+                        // looks the id up in the same registry), nor, as the stub does,
+                        // for an unfetched one the fetcher would refuse as expired.
+                        const record = referenceRegistry.get(candidate.refId);
+                        const expiry = record && !record.fetchedPath ? referenceExpiry(record.testimony) : null;
                         throw new Error(`save_recent_image: image at index ${position} is a reference (${candidate.refId}, ${candidate.mediaType}, ` +
                             `from ${describeTool(candidate)}) — its bytes are not held here. Nothing written. ` +
-                            'Fetch it with fetch_reference and save the materialized file instead.');
+                            (!record
+                                ? 'This process holds no record of it (a restart or an eviction drops records, and a stub quoted ' +
+                                    "from elsewhere never had one), so fetch_reference can't fetch it either. If its tool can produce " +
+                                    'it again, re-run that tool for a fresh reference.'
+                                : expiry
+                                    ? `It can't be fetched either — ${EXPIRY_REASON[expiry]}.`
+                                    : 'Fetch it with fetch_reference and save the materialized file instead.'));
                     }
                     if (candidate.ref === null) {
                         throw new Error(`save_recent_image: image at index ${position} is a tool-result image from ${describeTool(candidate)} ` +
@@ -14568,14 +15880,16 @@ export class AgentFramework {
                             consider({ kind: 'tool', ref: ph.ref, toolCallId, toolName, mediaType: ph.mediaType, messagesBack });
                             continue;
                         }
-                        // Reference stub: the registry's testimony (when this process
-                        // still has the record) says whether it was an image; the
-                        // sniffed stub text is the fallback. Non-image references
-                        // are not slots.
-                        const testimony = referenceRegistry.get(ph.refId)?.testimony.mimeType?.toLowerCase() ?? ph.mediaType;
-                        if (!testimony || !testimony.startsWith('image/'))
+                        // Reference stub: the registry's claimed type (when this process
+                        // still has the record), else the first image/ token in the
+                        // stub's text, which can come from its name, says whether it was
+                        // an image. Either is read as the stub shows a type, sanitized
+                        // and bounded. Non-image references are not slots.
+                        const claimed = referenceRegistry.get(ph.refId)?.testimony.mimeType ?? ph.mediaType ?? undefined;
+                        const mediaType = referenceTypeLabel(claimed).toLowerCase();
+                        if (!mediaType.startsWith('image/'))
                             continue;
-                        consider({ kind: 'reference', refId: ph.refId, mediaType: testimony, toolCallId, toolName, messagesBack });
+                        consider({ kind: 'reference', refId: ph.refId, mediaType, toolCallId, toolName, messagesBack });
                     }
                 };
                 // Same-batch results (e.g. a snapshot dispatched alongside the save)
@@ -14622,10 +15936,14 @@ export class AgentFramework {
                             const block = content[b];
                             if (block?.type === 'image') {
                                 const inline = block.source?.type === 'base64' && typeof block.source.data === 'string';
+                                // The sender's word, shown in the receipt and stored with the
+                                // file, so it's taken as a label; with nothing left of it, it
+                                // counts as absent.
+                                const claimed = block.source?.mediaType;
                                 consider({
                                     kind: 'attachment',
                                     data: inline ? block.source.data : null,
-                                    mediaType: block.source?.mediaType ?? 'image/png',
+                                    mediaType: (typeof claimed === 'string' ? sanitizeLabel(claimed, REFERENCE_LIMITS.mimeType) : '') || 'image/png',
                                     messagesBack,
                                 });
                             }