@animalabs/agent-framework 0.6.5 → 0.6.7

package/dist/src/framework.js

@@ -1,5 +1,6 @@
 import { join } from 'node:path';
 import { appendFileSync, mkdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { JsStore } from '@animalabs/chronicle';
 import { MembraneError } from '@animalabs/membrane';
 import { ContextManager, PassthroughStrategy } from '@animalabs/context-manager';
@@ -17,19 +18,65 @@ import { ConversationRouter } from './mcpl/conversation-router.js';
 import { safeSlice } from './safe-slice.js';
 import { toolResultDataToHistoryString } from './tool-result-history.js';
 import { splitProseSegments } from './prose-segments.js';
+import { canonicalJsonStringify } from './canonical-json.js';
+/**
+ * Tools whose presence suppresses auto-routing of the surrounding prose,
+ * for two distinct reasons:
+ *   - `skip_reply` — the agent EXPLICITLY chose not to reply (the deliberate
+ *     "stay silent" signal).
+ *   - explicit delivery tools (channel_publish / *send_message /
+ *     *reply_message / *send_dm) — already sent the message, so routing the
+ *     prose again would double-post.
+ * `think` is deliberately NOT here: it is silent *reasoning*, and same-round
+ * prose beside it is governed separately by same_round_think_text_policy.
+ *
+ * Scope: an explicit delivery suppresses prose from that round onward until
+ * another external message is injected. The suppression prevents a
+ * `send_message` followed by "sent it" from double-posting, but a new message
+ * starts a new conversational round and must be answerable with plain prose.
+ * `skip_reply` ends the turn at the tool-result boundary.
+ */
+const SILENCING_TOOLS = new Set([
+    'skip_reply', 'channel_publish', 'send_message', 'reply_message', 'send_dm',
+]);
+/** Strip the `server--` MCPL prefix from a tool name. */
+const bareToolName = (n) => n.split('--').pop();
 import { CheckpointManager } from './mcpl/checkpoint-manager.js';
 import { isToolAllowed } from './mcpl/tool-policy.js';
 import { EventGate } from './gate/event-gate.js';
 import { UsageTracker } from './usage/usage-tracker.js';
 import { formatZonedDateTime, resolveTimeZone } from './timezone.js';
+import { DEFAULT_DISCORD_AWARENESS_EMOJI, DiscordAwarenessOutbox, defaultDiscordAwarenessOutboxPath, extractDiscordAwarenessRefs, } from './recovery/discord-awareness-outbox.js';
 const FRAMEWORK_STATE_ID = 'framework/state';
 const CONVERSATION_ROUTER_STATE_ID = 'framework/conversation-router';
 const INFERENCE_LOG_ID = 'framework/inference-log';
 const PROCESS_LOG_ID = 'framework/process-log';
+const PRIMARY_SUMMARY_FALLBACK_STATE_ID = 'framework/primary-summary-fallback';
+const PRIMARY_SUMMARY_SETTLEMENT_METADATA_KEY = 'primarySummarySettlement';
+const PRIMARY_SUMMARY_SETTLEMENT_VERSION = 1;
+const PRIMARY_SUMMARY_SETTLEMENT_MAX_ID_LENGTH = 1024;
+const PRIMARY_SUMMARY_SETTLEMENT_MAX_NAME_LENGTH = 256;
+const PRIMARY_SUMMARY_SETTLEMENT_MAX_REASON_LENGTH = 256;
 const TURN_CHECKPOINTS_ID = 'framework/turn-checkpoints'; // legacy single-map layout, read-only fallback
 const TURN_CHECKPOINTS_TREE_ID = 'framework/turn-checkpoints/tree';
 /** Maximum number of turn checkpoints to keep per agent. */
 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;
+function normalizeDiscordAwarenessDeadline(value) {
+    if (value === undefined || !Number.isFinite(value) || value <= 0) {
+        return DEFAULT_DISCORD_AWARENESS_DEADLINE_MS;
+    }
+    return Math.max(MIN_DISCORD_AWARENESS_DEADLINE_MS, Math.min(MAX_DISCORD_AWARENESS_DEADLINE_MS, Math.floor(value)));
+}
+class DiscordAwarenessAccountingError extends Error {
+    constructor(operation, cause) {
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        super(`Discord awareness accounting failed during ${operation}: ${detail}`, { cause });
+        this.name = 'DiscordAwarenessAccountingError';
+    }
+}
 /**
  * Default inference policy - infer if any request exists for the agent.
  */
@@ -38,6 +85,10 @@ class DefaultInferencePolicy {
         return requests.some((r) => r.agentName === agentName);
     }
 }
+function isPermanentDiscordReactionFailure(message) {
+    return /unknown message|unknown channel|missing access|missing permissions|missing permission|cannot access|channel .* not found|message .* not found/i
+        .test(message);
+}
 /**
  * Default error policy - retry with exponential backoff.
  *
@@ -139,13 +190,29 @@ export class AgentFramework {
     maintenanceRunId = 0;
     currentMaintenanceRun = null;
     maintenanceHistory = [];
-    /** Last time we console-warned about stale (busy-requeued) inference requests, per agent. */
+    /** Last time we reported stale (busy-requeued) inference requests, per agent. */
     staleWarnAt = new Map();
     /** Per-agent last inference activity (epoch ms), for /healthz + doctor tooling. */
     lastInferenceAt = new Map();
     processLoggingPersist;
     processLoggingBroadcast;
     activeStreams = new Map();
+    activeStreamContexts = new Map();
+    primarySummaryStateLock = Promise.resolve();
+    /** Per-agent output locus pinned for the CURRENT logical turn (see
+     *  resolveTurnLocus in driveStream). Lives here — not in driveStream
+     *  locals — so the pin survives a context-budget stream restart, which
+     *  continues the same logical turn in a fresh driveStream. A mid-turn
+     *  injected channel message replaces the pin for the next conversational
+     *  round; otherwise it remains stable. Cleared at the start of every
+     *  non-restart turn. */
+    turnLocusPins = new Map();
+    /** A tool boundary injected fresh external input into the live stream.
+     *  Presence (including a null value) tells driveStream to clear sticky
+     *  explicit-send suppression before handling the next model round. A
+     *  string also moves that round's reply locus to the newest injected
+     *  channel. */
+    midTurnRoutingResets = new Map();
     pendingAssistantBlocks = new Map();
     /** Streams the FRAMEWORK cancelled for non-terminal reasons, keyed
      *  `${agentName}:${streamId}`: an endTurn tool result or a context-budget
@@ -249,13 +316,22 @@ export class AgentFramework {
      *  subsystem can be lazily initialized by connectMcplServer when the
      *  framework started with zero configured servers. */
     mcplInferenceRoutingConfig = null;
+    /** Durable, non-Chronicle projection queue for messages removed by a branch. */
+    discordAwarenessOutbox = null;
+    discordAwarenessEmoji = DEFAULT_DISCORD_AWARENESS_EMOJI;
+    discordAwarenessDeadlineMs = DEFAULT_DISCORD_AWARENESS_DEADLINE_MS;
+    /** Serialize per-server drains so reconnect and an online undo cannot race. */
+    discordAwarenessDrains = new Map();
+    /** Framework-global inference gate; older generations cannot release it. */
+    discordAwarenessBarrier = null;
+    discordAwarenessBarrierGeneration = 0;
     // EventGate (null when FrameworkConfig.gate is omitted)
     eventGate = null;
     // Session-level token usage tracking (always-on)
     usageTracker;
     /** Presentation-only wall-clock zone; persistence remains UTC/epoch. */
     timeZone;
-    constructor(store, ownsStore, membrane, inferencePolicy, errorPolicy, syncIntervalMs, maintenanceIntervalMs, processLoggingPersist, processLoggingBroadcast, timeZone) {
+    constructor(store, ownsStore, membrane, inferencePolicy, errorPolicy, syncIntervalMs, maintenanceIntervalMs, processLoggingPersist, processLoggingBroadcast, timeZone, discordAwarenessOutbox, discordAwarenessEmoji, discordAwarenessDeadlineMs) {
         this.store = store;
         this.ownsStore = ownsStore;
         this.membrane = membrane;
@@ -266,6 +342,9 @@ export class AgentFramework {
         this.processLoggingPersist = processLoggingPersist;
         this.processLoggingBroadcast = processLoggingBroadcast;
         this.timeZone = timeZone;
+        this.discordAwarenessOutbox = discordAwarenessOutbox;
+        this.discordAwarenessEmoji = discordAwarenessEmoji;
+        this.discordAwarenessDeadlineMs = discordAwarenessDeadlineMs;
         this.queue = new ProcessQueueImpl();
         this.usageTracker = new UsageTracker({
             emitTrace: (e) => this.emitTrace({ ...e }),
@@ -345,13 +424,45 @@ export class AgentFramework {
                 // Already registered
             }
         }
-        const framework = new AgentFramework(store, ownsStore, config.membrane, config.inferencePolicy ?? new DefaultInferencePolicy(), config.errorPolicy ?? new DefaultErrorPolicy(), config.syncIntervalMs ?? DEFAULT_SYNC_INTERVAL_MS, config.maintenanceIntervalMs ?? DEFAULT_MAINTENANCE_INTERVAL_MS, processLoggingPersist, processLoggingBroadcast, resolveTimeZone(config.timeZone));
-        // Restore persisted usage data (if any) from prior session
-        framework.restoreUsageState();
+        try {
+            store.registerState({ id: PRIMARY_SUMMARY_FALLBACK_STATE_ID, strategy: 'snapshot' });
+        }
+        catch {
+            // Already registered
+        }
+        const discordAwarenessOutboxPath = config.discordAwarenessOutboxPath
+            ?? (config.storePath ? defaultDiscordAwarenessOutboxPath(config.storePath) : undefined);
+        const discordAwarenessOutbox = discordAwarenessOutboxPath
+            ? new DiscordAwarenessOutbox(discordAwarenessOutboxPath)
+            : null;
+        const framework = new AgentFramework(store, ownsStore, config.membrane, config.inferencePolicy ?? new DefaultInferencePolicy(), config.errorPolicy ?? new DefaultErrorPolicy(), config.syncIntervalMs ?? DEFAULT_SYNC_INTERVAL_MS, config.maintenanceIntervalMs ?? DEFAULT_MAINTENANCE_INTERVAL_MS, processLoggingPersist, processLoggingBroadcast, resolveTimeZone(config.timeZone), discordAwarenessOutbox, config.discordAwarenessEmoji ?? DEFAULT_DISCORD_AWARENESS_EMOJI, normalizeDiscordAwarenessDeadline(config.discordAwarenessDeadlineMs));
+        // If an offline recovery process crashed after switching Chronicle but
+        // before committing its prepared marker batch, the active branch is the
+        // commit record. Promote it now; no quarantined content is read.
+        if (discordAwarenessOutbox) {
+            try {
+                const activated = discordAwarenessOutbox.activatePreparedForBranch(store.currentBranch().name, store.listBranches());
+                if (activated > 0) {
+                    console.error(`[discord-awareness] recovered ${activated} prepared batch(es) for active branch ${store.currentBranch().name}`);
+                }
+            }
+            catch (error) {
+                // The branch may be safe, but reporting the framework ready while its
+                // durable awareness projection is unreadable creates a half-ready
+                // host whose data plane can never be released safely.
+                throw new DiscordAwarenessAccountingError('startup reconciliation', error);
+            }
+        }
         // Create agents
         for (const agentConfig of config.agents) {
             await framework.createAgent(agentConfig);
         }
+        // Restore persisted usage data (if any) from prior session
+        framework.restoreUsageState();
+        await framework.reconcilePrimarySummaryFallbackStateOnStartup();
+        // Finish any branch-local suppression interrupted after Chronicle switched
+        // branches. This runs before modules, MCPL connections, or inbound traffic.
+        await framework.resumePreparedDiscordSuppressions();
         // Add modules
         for (const module of config.modules) {
             await framework.addModule(module);
@@ -566,11 +677,10 @@ export class AgentFramework {
         });
     }
     async runQueuedMaintenance() {
-        const allTools = this.getAllTools();
         const queued = [...this.agents.values()].flatMap((agent) => {
             const cm = agent.getContextManager();
-            const tools = allTools.filter((tool) => agent.canUseTool(tool.name));
-            cm.setToolDefinitions(tools);
+            const tools = this.getToolsForAgent(agent.name).filter((tool) => agent.canUseTool(tool.name));
+            cm.setToolDefinitions?.(tools);
             if (cm.isReady())
                 return [];
             const pending = cm.getPendingWork()?.description;
@@ -752,10 +862,150 @@ export class AgentFramework {
                 AgentFramework.EVENT_TAGS_TOOL,
             ]
             : [];
-        if (this.mcplTools.length === 0 && channelTools.length === 0 && gateTools.length === 0) {
-            return moduleTools;
+        return [
+            ...moduleTools,
+            ...this.mcplTools,
+            ...channelTools,
+            ...gateTools,
+            this.buildAgentSettingsTool(),
+            ...(this.getWorkspaceModule() ? [AgentFramework.SAVE_IMAGE_TOOL] : []),
+        ];
+    }
+    /** The registered workspace module, if any (used by save_image). */
+    getWorkspaceModule() {
+        const module = this.moduleRegistry.getAllModules().find((m) => m.name === 'workspace');
+        return module && typeof module.writeBinary === 'function'
+            ? module
+            : undefined;
+    }
+    /** Core agent_settings keys — extension keys must not collide with these. */
+    static AGENT_SETTINGS_CORE_KEYS = [
+        'context_budget_tokens',
+        'tail_tokens',
+        'transition_pace_tokens',
+        'same_round_think_text_policy',
+    ];
+    /**
+     * Collect module-declared agent_settings extensions (Module.getAgentSettingsExtension),
+     * keyed by owning module name. Extensions whose keys collide with the core
+     * settings or an earlier extension are skipped loudly — silent shadowing
+     * would make updates route to the wrong owner.
+     */
+    collectAgentSettingsExtensions() {
+        const result = new Map();
+        const taken = new Set(AgentFramework.AGENT_SETTINGS_CORE_KEYS);
+        for (const module of this.moduleRegistry.getAllModules()) {
+            const ext = module.getAgentSettingsExtension?.();
+            if (!ext)
+                continue;
+            const collision = ext.keys.find((k) => taken.has(k));
+            if (collision) {
+                console.error(`[agent-settings] extension from module '${module.name}' skipped: key '${collision}' already taken`);
+                continue;
+            }
+            ext.keys.forEach((k) => taken.add(k));
+            result.set(module.name, ext);
         }
-        return [...moduleTools, ...this.mcplTools, ...channelTools, ...gateTools];
+        return result;
+    }
+    captureInferenceToolSnapshot(agent) {
+        return {
+            sameRoundThinkTextPolicy: agent.getEffectiveSameRoundThinkTextPolicy(),
+        };
+    }
+    buildThinkTool(policy) {
+        return {
+            name: 'think',
+            description: 'Reason privately. The think({content}) argument stays in your own context and is NOT sent ' +
+                'to channels or other surfaces. ' +
+                (policy === 'private'
+                    ? 'Your current same_round_think_text_policy is private, so ordinary text emitted in the SAME native assistant round as think() is withheld from channel routing. Later rounds without think() route normally.'
+                    : 'Your current same_round_think_text_policy is public, so ordinary text emitted in the SAME native assistant round as think() may still be routed publicly as your speech. Later rounds without think() route normally.') +
+                ' Use think() to work things out privately. To inspect or change this policy, use agent_settings get/update on same_round_think_text_policy. To deliberately not reply this turn, call skip_reply instead.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    content: {
+                        type: 'string',
+                        description: 'Your private thought / reasoning (optional; not sent anywhere).',
+                    },
+                },
+                required: [],
+            },
+        };
+    }
+    /** agent_settings tool definition with module extension fields merged in. */
+    buildAgentSettingsTool() {
+        const base = AgentFramework.AGENT_SETTINGS_TOOL;
+        const extensions = this.collectAgentSettingsExtensions();
+        if (extensions.size === 0)
+            return base;
+        const baseSchema = base.inputSchema;
+        const extProperties = {};
+        const extKeys = [];
+        for (const ext of extensions.values()) {
+            Object.assign(extProperties, ext.properties);
+            extKeys.push(...ext.keys);
+        }
+        const settingsProp = baseSchema.properties.settings;
+        return {
+            ...base,
+            description: base.description +
+                ` Additional host-managed settings also live here: ${extKeys.join(', ')}.`,
+            inputSchema: {
+                ...baseSchema,
+                properties: {
+                    ...baseSchema.properties,
+                    ...extProperties,
+                    settings: {
+                        ...baseSchema.properties.settings,
+                        items: {
+                            ...settingsProp.items,
+                            enum: [...(settingsProp.items?.enum ?? []), ...extKeys],
+                        },
+                    },
+                },
+            },
+        };
+    }
+    getToolsForAgent(agentName, snapshot) {
+        return this.getAllTools().map((tool) => {
+            if (tool.name === 'think') {
+                return this.buildThinkTool(snapshot?.sameRoundThinkTextPolicy
+                    ?? this.getAgentRuntimeSettings(agentName).sameRoundThinkTextPolicy);
+            }
+            return tool;
+        });
+    }
+    getAgentRuntimeSettings(agentName) {
+        const agent = this.agents.get(agentName);
+        if (!agent)
+            throw new Error(`Unknown agent: ${agentName}`);
+        return agent.getRuntimeSettings();
+    }
+    updateAgentRuntimeSettings(agentName, patch) {
+        const agent = this.agents.get(agentName);
+        if (!agent)
+            throw new Error(`Unknown agent: ${agentName}`);
+        const result = agent.updateRuntimeSettings(patch);
+        this.persistAgentRuntimeSettings(agentName, agent.getRuntimeSettingsOverrides());
+        return result;
+    }
+    resetAgentRuntimeSettings(agentName, keys) {
+        const agent = this.agents.get(agentName);
+        if (!agent)
+            throw new Error(`Unknown agent: ${agentName}`);
+        const result = agent.resetRuntimeSettings(keys);
+        this.persistAgentRuntimeSettings(agentName, agent.getRuntimeSettingsOverrides());
+        return result;
+    }
+    cancelAgentRuntimeSettingsTransition(agentName) {
+        const agent = this.agents.get(agentName);
+        if (!agent)
+            throw new Error(`Unknown agent: ${agentName}`);
+        const result = agent.cancelRuntimeSettingsTransition();
+        this.persistAgentRuntimeSettings(agentName, agent.getRuntimeSettingsOverrides());
+        return result;
     }
     /** Counts-only context-maintenance diagnostics for authenticated debug UIs. */
     getContextMaintenanceSnapshot() {
@@ -808,7 +1058,7 @@ export class AgentFramework {
         if (!agent) {
             throw new Error(`Agent not found: ${agentName}`);
         }
-        const tools = this.getAllTools().filter((t) => agent.canUseTool(t.name));
+        const tools = this.getToolsForAgent(agentName).filter((t) => agent.canUseTool(t.name));
         // Default: no dynamic injection gathering → fully transparent (no
         // inference, no Chronicle writes, no external RPC). Opt in explicitly.
         if (!opts?.injections) {
@@ -932,6 +1182,37 @@ export class AgentFramework {
             // Non-fatal — usage tracking is best-effort
         }
     }
+    readAgentRuntimeSettings(agentName) {
+        try {
+            const data = this.store.getStateJson(FRAMEWORK_STATE_ID);
+            const stored = data?.agentRuntimeSettings?.[agentName];
+            return stored ? { ...stored } : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    validatePersistedAgentRuntimeSettings(agentName, overrides) {
+        if (overrides.sameRoundThinkTextPolicy !== undefined &&
+            overrides.sameRoundThinkTextPolicy !== 'public' &&
+            overrides.sameRoundThinkTextPolicy !== 'private') {
+            throw new Error(`Invalid persisted sameRoundThinkTextPolicy for agent "${agentName}": ${JSON.stringify(overrides.sameRoundThinkTextPolicy)}`);
+        }
+        return overrides;
+    }
+    persistAgentRuntimeSettings(agentName, overrides) {
+        const data = this.store.getStateJson(FRAMEWORK_STATE_ID);
+        const state = (data && typeof data === 'object' ? data : {});
+        const all = {
+            ...(state.agentRuntimeSettings ?? {}),
+        };
+        if (Object.keys(overrides).length === 0)
+            delete all[agentName];
+        else
+            all[agentName] = { ...overrides };
+        state.agentRuntimeSettings = all;
+        this.store.setStateJson(FRAMEWORK_STATE_ID, state);
+    }
     /**
      * Create an ephemeral agent that is NOT registered in the main event loop.
      *
@@ -970,6 +1251,1091 @@ export class AgentFramework {
         });
         return { promise, resolve, reject };
     }
+    hashJson(value) {
+        return createHash('sha256').update(canonicalJsonStringify(value), 'utf8').digest('hex');
+    }
+    estimateStringTokens(text, overhead = 0) {
+        return Math.ceil(Buffer.byteLength(text, 'utf8') / 4) + overhead;
+    }
+    estimateUnknownTokens(value, overhead = 0) {
+        return this.estimateStringTokens(JSON.stringify(value) ?? 'null', overhead);
+    }
+    estimateRequestInputBoundTokens(request) {
+        let total = 96;
+        total += this.estimateStringTokens(request.system ?? '', 48);
+        for (const message of request.messages) {
+            total += 24;
+            total += this.estimateStringTokens(message.participant, 8);
+            if (message.cacheBreakpoint)
+                total += 8;
+            for (const block of message.content) {
+                switch (block.type) {
+                    case 'text':
+                        total += this.estimateStringTokens(block.text, 24);
+                        break;
+                    case 'thinking':
+                        total += this.estimateStringTokens(block.thinking, 32);
+                        total += block.signature ? this.estimateStringTokens(block.signature, 8) : 0;
+                        break;
+                    case 'redacted_thinking':
+                        total += this.estimateUnknownTokens(block, 32);
+                        break;
+                    default:
+                        total += this.estimateUnknownTokens(block, 32);
+                        break;
+                }
+            }
+        }
+        if (request.tools && request.tools.length > 0) {
+            total += 32;
+            for (const tool of request.tools) {
+                total += this.estimateUnknownTokens({
+                    name: tool.name,
+                    description: tool.description,
+                    inputSchema: tool.inputSchema,
+                }, 48);
+            }
+        }
+        total += this.estimateUnknownTokens(request.config, 48);
+        if (request.providerParams !== undefined) {
+            total += this.estimateUnknownTokens(request.providerParams, 32);
+        }
+        total += request.promptCaching ? 16 : 0;
+        total += request.cacheTtl ? this.estimateStringTokens(request.cacheTtl, 8) : 0;
+        total += request.assistantParticipant
+            ? this.estimateStringTokens(request.assistantParticipant, 8)
+            : 0;
+        return total;
+    }
+    estimateRequestCompleteBoundTokens(request) {
+        const reserve = typeof request.config.maxTokens === 'number' && Number.isFinite(request.config.maxTokens)
+            ? request.config.maxTokens
+            : 0;
+        return this.estimateRequestInputBoundTokens(request) + reserve + 96;
+    }
+    primarySummaryAdmissionBoundTokens(originalRequestInputTokens, expandedRequest, originalProviderInputTokens) {
+        const expandedInput = this.estimateRequestInputBoundTokens(expandedRequest);
+        const expandedComplete = this.estimateRequestCompleteBoundTokens(expandedRequest);
+        if (originalProviderInputTokens === undefined)
+            return expandedComplete;
+        const reserve = typeof expandedRequest.config.maxTokens === 'number' && Number.isFinite(expandedRequest.config.maxTokens)
+            ? expandedRequest.config.maxTokens
+            : 0;
+        const positiveDelta = Math.max(0, expandedInput - originalRequestInputTokens);
+        return Math.max(expandedComplete, originalProviderInputTokens + positiveDelta + reserve + 96);
+    }
+    readPrimarySummaryFallbackState() {
+        const raw = this.store
+            ?.getStateJson?.(PRIMARY_SUMMARY_FALLBACK_STATE_ID);
+        if (!raw || typeof raw !== 'object')
+            return { requests: [] };
+        const requests = Array.isArray(raw.requests)
+            ? (raw.requests)
+            : [];
+        return { requests };
+    }
+    writePrimarySummaryFallbackState(state) {
+        this.store.setStateJson(PRIMARY_SUMMARY_FALLBACK_STATE_ID, state);
+    }
+    async withPrimarySummaryStateLock(work) {
+        const previous = this.primarySummaryStateLock;
+        let release;
+        this.primarySummaryStateLock = new Promise((resolve) => { release = resolve; });
+        await previous;
+        try {
+            return await work();
+        }
+        finally {
+            release();
+        }
+    }
+    async reconcilePrimarySummaryFallbackStateOnStartup() {
+        const alerts = [];
+        const unsettledRequests = (await this.withPrimarySummaryStateLock(() => this.readPrimarySummaryFallbackState().requests
+            .filter((record) => record.finalStatus === 'pending'
+            || record.finalStatus === 'refusal'
+            || record.fallbackStatus === 'pending')
+            .map((record) => structuredClone(record))));
+        const resolvedRequestIds = new Set();
+        for (const record of unsettledRequests) {
+            const result = await this.finalizePrimarySummarySettlementOnStartup(record);
+            if (result === 'finalized') {
+                resolvedRequestIds.add(record.requestId);
+                continue;
+            }
+            if (result && typeof result === 'object' && 'invalidReason' in result) {
+                resolvedRequestIds.add(record.requestId);
+                alerts.push({ agentName: record.agentName, requestId: record.requestId, reason: result.invalidReason });
+                await this.markPrimarySummaryRequestRestartFailure(record, result.invalidReason);
+            }
+        }
+        await this.withPrimarySummaryStateLock(() => {
+            const state = this.readPrimarySummaryFallbackState();
+            let changed = false;
+            state.requests = state.requests.map((record) => {
+                if (resolvedRequestIds.has(record.requestId))
+                    return record;
+                if (record.dispatchKind === 'primary_summary_fallback_retry' && (record.finalStatus === 'pending' || record.finalStatus === 'refusal')) {
+                    changed = true;
+                    const reason = 'primary_summary_fallback_unresolved_on_restart';
+                    alerts.push({ agentName: record.agentName, requestId: record.requestId, reason });
+                    return {
+                        ...record,
+                        finalStatus: 'held',
+                        fallbackHeldReason: reason,
+                    };
+                }
+                if (record.fallbackIntent && record.fallbackStatus === 'pending') {
+                    changed = true;
+                    const reason = 'primary_summary_fallback_unresolved_on_restart';
+                    alerts.push({ agentName: record.agentName, requestId: record.requestId, reason });
+                    return {
+                        ...record,
+                        fallbackStatus: 'held',
+                        fallbackHeldReason: reason,
+                    };
+                }
+                if (record.finalStatus === 'refusal') {
+                    changed = true;
+                    const reason = 'primary_summary_request_unresolved_on_restart';
+                    alerts.push({ agentName: record.agentName, requestId: record.requestId, reason });
+                    return {
+                        ...record,
+                        finalStatus: 'held',
+                        fallbackStatus: 'held',
+                        fallbackHeldReason: reason,
+                    };
+                }
+                if (record.finalStatus === 'pending') {
+                    changed = true;
+                    const reason = 'primary_summary_request_unresolved_on_restart';
+                    alerts.push({ agentName: record.agentName, requestId: record.requestId, reason });
+                    return {
+                        ...record,
+                        finalStatus: 'timeout_unknown',
+                        fallbackHeldReason: reason,
+                    };
+                }
+                return record;
+            });
+            if (changed)
+                this.writePrimarySummaryFallbackState({ requests: state.requests.slice(-256) });
+        });
+        for (const alert of alerts) {
+            this.opsAlert('refusal-held', alert.agentName, alert.reason, {
+                data: { requestId: alert.requestId },
+            });
+        }
+    }
+    primarySummaryIdentityKey(identity) {
+        return [
+            identity.id,
+            identity.contentHash,
+            identity.carrierHash,
+            identity.sourceLeafHash,
+        ].join('\u0000');
+    }
+    primarySummaryProjectionKeys(projection) {
+        return projection?.selectedSummaries.map((selection) => this.primarySummaryIdentityKey(selection.identity)) ?? [];
+    }
+    primarySummaryFallbackConfig(agent) {
+        const raw = agent.refusalHandling?.primarySummaryFallback;
+        const fallbackBudgetBase = agent.contextBudgetTokens ?? 100_000;
+        return {
+            enabled: raw?.enabled === true,
+            maxNewSummaries: typeof raw?.maxNewSummaries === 'number' && Number.isSafeInteger(raw.maxNewSummaries)
+                ? Math.max(0, raw.maxNewSummaries)
+                : 4,
+            requestBudgetTokens: typeof raw?.requestBudgetTokens === 'number' && Number.isFinite(raw.requestBudgetTokens) && raw.requestBudgetTokens > 0
+                ? raw.requestBudgetTokens
+                : fallbackBudgetBase + agent.maxTokens,
+        };
+    }
+    latestCompatibleHealthyPrimaryRequest(current, state) {
+        for (let i = state.requests.length - 1; i >= 0; i--) {
+            const candidate = state.requests[i];
+            if (candidate.requestId === current.requestId)
+                continue;
+            if (candidate.agentName !== current.agentName)
+                continue;
+            if (candidate.namespace !== current.namespace)
+                continue;
+            if (candidate.branch.id !== current.branch.id)
+                continue;
+            if (candidate.branch.generation !== current.branch.generation)
+                continue;
+            if (candidate.systemHash !== current.systemHash)
+                continue;
+            if (candidate.modelConfigHash !== current.modelConfigHash)
+                continue;
+            if (candidate.toolContractHash !== current.toolContractHash)
+                continue;
+            if (candidate.dispatchKind !== 'primary')
+                continue;
+            if (candidate.fallbackIntent || candidate.fallbackStatus)
+                continue;
+            if (candidate.finalStatus !== 'success')
+                continue;
+            return candidate;
+        }
+        return null;
+    }
+    async persistPrimarySummaryRequestRecord(record) {
+        await this.withPrimarySummaryStateLock(() => {
+            const state = this.readPrimarySummaryFallbackState();
+            const requests = state.requests.filter((entry) => entry.requestId !== record.requestId);
+            requests.push(record);
+            this.writePrimarySummaryFallbackState({ requests: requests.slice(-256) });
+        });
+    }
+    async updatePrimarySummaryRequestRecord(requestId, update) {
+        return this.withPrimarySummaryStateLock(() => {
+            const state = this.readPrimarySummaryFallbackState();
+            const index = state.requests.findIndex((entry) => entry.requestId === requestId);
+            if (index < 0)
+                return null;
+            state.requests[index] = update(state.requests[index]);
+            this.writePrimarySummaryFallbackState({ requests: state.requests.slice(-256) });
+            return state.requests[index];
+        });
+    }
+    async getPrimarySummaryRequestRecord(requestId) {
+        return this.withPrimarySummaryStateLock(() => {
+            const state = this.readPrimarySummaryFallbackState();
+            return state.requests.find((entry) => entry.requestId === requestId) ?? null;
+        });
+    }
+    primarySummaryContractsMatch(left, right) {
+        return left.systemHash === right.systemHash
+            && left.modelConfigHash === right.modelConfigHash
+            && left.toolContractHash === right.toolContractHash;
+    }
+    primarySummaryFallbackOutputPhaseHash(blocks) {
+        return this.hashJson(blocks);
+    }
+    primarySummaryFallbackBlockTypes(blocks) {
+        return blocks.map((block) => block.type);
+    }
+    static NON_EXECUTED_TOOL_RESULT_TEXT = '[tool not executed]';
+    buildNonExecutedToolResults(blocks) {
+        const seenToolUseIds = new Set();
+        return blocks
+            .filter((block) => block.type === 'tool_use')
+            .filter((block) => {
+            if (seenToolUseIds.has(block.id))
+                return false;
+            seenToolUseIds.add(block.id);
+            return true;
+        })
+            .map((block) => ({
+            type: 'tool_result',
+            toolUseId: block.id,
+            content: AgentFramework.NON_EXECUTED_TOOL_RESULT_TEXT,
+            isError: true,
+        }));
+    }
+    buildPrimarySummarySettlementId(record, outcome) {
+        return `${record.dispatchKind}:${outcome}:terminal:v${PRIMARY_SUMMARY_SETTLEMENT_VERSION}`;
+    }
+    buildPrimarySummarySettlementMetadata(record, options) {
+        const settlementId = options.settlementId ?? this.buildPrimarySummarySettlementId(record, options.outcome);
+        return {
+            [PRIMARY_SUMMARY_SETTLEMENT_METADATA_KEY]: {
+                version: PRIMARY_SUMMARY_SETTLEMENT_VERSION,
+                requestId: record.requestId,
+                settlementId,
+                agentName: record.agentName,
+                dispatchKind: record.dispatchKind,
+                outcome: options.outcome,
+                ...(options.stopReason ? { stopReason: options.stopReason } : {}),
+                ...(options.holdReason ? { holdReason: options.holdReason } : {}),
+                ...(options.providerInputTokens !== undefined
+                    ? { providerInputTokens: options.providerInputTokens }
+                    : {}),
+                visibleAssistantOutput: options.visibleAssistantOutput,
+                executedToolCalls: options.executedToolCalls,
+                branch: {
+                    id: record.branch.id,
+                    name: record.branch.name,
+                    generation: record.branch.generation,
+                },
+                role: options.role,
+                kind: options.kind,
+                entryIndex: options.entryIndex,
+                entryCount: options.entryCount,
+            },
+        };
+    }
+    isBoundedNonEmptyString(value, maxLength) {
+        return typeof value === 'string' && value.length > 0 && value.length <= maxLength;
+    }
+    isSafeNonNegativeInteger(value) {
+        return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+    }
+    primarySummarySettlementRequestId(message) {
+        const raw = message.metadata?.[PRIMARY_SUMMARY_SETTLEMENT_METADATA_KEY];
+        if (!raw || typeof raw !== 'object')
+            return null;
+        const requestId = raw.requestId;
+        return typeof requestId === 'string' ? requestId : null;
+    }
+    parsePrimarySummarySettlementMetadata(message) {
+        const raw = message.metadata?.[PRIMARY_SUMMARY_SETTLEMENT_METADATA_KEY];
+        if (!raw || typeof raw !== 'object')
+            return null;
+        const candidate = raw;
+        if (candidate.version !== PRIMARY_SUMMARY_SETTLEMENT_VERSION ||
+            !this.isBoundedNonEmptyString(candidate.requestId, PRIMARY_SUMMARY_SETTLEMENT_MAX_ID_LENGTH) ||
+            !this.isBoundedNonEmptyString(candidate.settlementId, PRIMARY_SUMMARY_SETTLEMENT_MAX_ID_LENGTH) ||
+            !this.isBoundedNonEmptyString(candidate.agentName, PRIMARY_SUMMARY_SETTLEMENT_MAX_NAME_LENGTH) ||
+            (candidate.dispatchKind !== 'primary' && candidate.dispatchKind !== 'primary_summary_fallback_retry') ||
+            (candidate.outcome !== 'success' && candidate.outcome !== 'held') ||
+            typeof candidate.visibleAssistantOutput !== 'boolean' ||
+            !this.isSafeNonNegativeInteger(candidate.executedToolCalls) ||
+            !this.isSafeNonNegativeInteger(candidate.entryIndex) ||
+            !this.isSafeNonNegativeInteger(candidate.entryCount) ||
+            (candidate.role !== 'assistant' && candidate.role !== 'user') ||
+            (candidate.kind !== 'assistant_output' && candidate.kind !== 'generated_tool_result') ||
+            !candidate.branch ||
+            !this.isBoundedNonEmptyString(candidate.branch.id, PRIMARY_SUMMARY_SETTLEMENT_MAX_ID_LENGTH) ||
+            !this.isBoundedNonEmptyString(candidate.branch.name, PRIMARY_SUMMARY_SETTLEMENT_MAX_NAME_LENGTH) ||
+            !this.isSafeNonNegativeInteger(candidate.branch.generation) ||
+            candidate.entryCount < 1 ||
+            candidate.entryIndex >= candidate.entryCount ||
+            (candidate.stopReason !== undefined
+                && !this.isBoundedNonEmptyString(candidate.stopReason, PRIMARY_SUMMARY_SETTLEMENT_MAX_REASON_LENGTH)) ||
+            (candidate.holdReason !== undefined
+                && !this.isBoundedNonEmptyString(candidate.holdReason, PRIMARY_SUMMARY_SETTLEMENT_MAX_REASON_LENGTH)) ||
+            (candidate.providerInputTokens !== undefined
+                && !this.isSafeNonNegativeInteger(candidate.providerInputTokens)) ||
+            (candidate.outcome === 'held' && candidate.holdReason === undefined) ||
+            (candidate.outcome === 'success' && candidate.holdReason !== undefined)) {
+            return { invalidReason: 'primary_summary_settlement_metadata_invalid_on_restart' };
+        }
+        return candidate;
+    }
+    primarySummarySettlementMetadataConsistent(left, right) {
+        return left.version === right.version
+            && left.requestId === right.requestId
+            && left.settlementId === right.settlementId
+            && left.agentName === right.agentName
+            && left.dispatchKind === right.dispatchKind
+            && left.outcome === right.outcome
+            && left.stopReason === right.stopReason
+            && left.holdReason === right.holdReason
+            && left.providerInputTokens === right.providerInputTokens
+            && left.visibleAssistantOutput === right.visibleAssistantOutput
+            && left.executedToolCalls === right.executedToolCalls
+            && left.branch.id === right.branch.id
+            && left.branch.name === right.branch.name
+            && left.branch.generation === right.branch.generation
+            && left.entryCount === right.entryCount;
+    }
+    primarySummaryShardEnvelopeConsistent(participant, left, candidateParticipant, right) {
+        return participant === candidateParticipant
+            && this.primarySummarySettlementMetadataConsistent(left, right)
+            && left.role === right.role
+            && left.kind === right.kind
+            && left.entryIndex === right.entryIndex;
+    }
+    primarySummaryLogicalSettlementEntries(agent, requestId) {
+        const allMessages = agent.getContextManager().getAllMessages()
+            .slice()
+            .sort((left, right) => left.sequence - right.sequence);
+        const entries = [];
+        for (let index = 0; index < allMessages.length;) {
+            const message = allMessages[index];
+            if (this.primarySummarySettlementRequestId(message) !== requestId) {
+                index++;
+                continue;
+            }
+            const parsed = this.parsePrimarySummarySettlementMetadata(message);
+            if (!parsed) {
+                index++;
+                continue;
+            }
+            if ('invalidReason' in parsed)
+                return parsed;
+            if (message.bodyGroupId === undefined) {
+                if (message.shardIndex !== undefined) {
+                    return { invalidReason: 'primary_summary_settlement_shard_group_invalid_on_restart' };
+                }
+                entries.push({
+                    messages: [message],
+                    settlement: parsed,
+                    participant: message.participant,
+                    content: message.content,
+                });
+                index++;
+                continue;
+            }
+            const groupId = message.bodyGroupId;
+            if (!this.isBoundedNonEmptyString(groupId, PRIMARY_SUMMARY_SETTLEMENT_MAX_ID_LENGTH)) {
+                return { invalidReason: 'primary_summary_settlement_shard_group_invalid_on_restart' };
+            }
+            if (index > 0 && allMessages[index - 1]?.bodyGroupId === groupId) {
+                return { invalidReason: 'primary_summary_settlement_shard_group_invalid_on_restart' };
+            }
+            const groupMessages = [];
+            while (index < allMessages.length && allMessages[index].bodyGroupId === groupId) {
+                groupMessages.push(allMessages[index]);
+                index++;
+            }
+            if (allMessages.slice(index).some((candidate) => candidate.bodyGroupId === groupId)) {
+                return { invalidReason: 'primary_summary_settlement_shard_group_invalid_on_restart' };
+            }
+            const orderedGroupMessages = [];
+            let expectedShardIndex = 0;
+            for (const groupMessage of groupMessages) {
+                if (this.primarySummarySettlementRequestId(groupMessage) !== requestId) {
+                    return { invalidReason: 'primary_summary_settlement_shard_group_invalid_on_restart' };
+                }
+                const groupParsed = this.parsePrimarySummarySettlementMetadata(groupMessage);
+                if (!groupParsed) {
+                    return { invalidReason: 'primary_summary_settlement_shard_group_invalid_on_restart' };
+                }
+                if ('invalidReason' in groupParsed)
+                    return groupParsed;
+                if (!this.primarySummaryShardEnvelopeConsistent(message.participant, parsed, groupMessage.participant, groupParsed)) {
+                    return { invalidReason: 'primary_summary_settlement_shard_group_invalid_on_restart' };
+                }
+                if (groupMessage.shardIndex !== expectedShardIndex) {
+                    return { invalidReason: 'primary_summary_settlement_shard_group_invalid_on_restart' };
+                }
+                orderedGroupMessages.push(groupMessage);
+                expectedShardIndex++;
+            }
+            entries.push({
+                messages: orderedGroupMessages,
+                settlement: parsed,
+                participant: message.participant,
+                content: orderedGroupMessages.flatMap((groupMessage) => groupMessage.content),
+                bodyGroupId: groupId,
+            });
+        }
+        return entries;
+    }
+    primarySummaryContentMatches(left, right) {
+        return this.primarySummaryFallbackOutputPhaseHash(left) === this.primarySummaryFallbackOutputPhaseHash(right);
+    }
+    async persistPrimarySummaryChronicleEntries(agent, entries) {
+        const messageIds = [];
+        for (const entry of entries) {
+            if (entry.content.length === 0)
+                continue;
+            messageIds.push(agent.getContextManager().addMessage(entry.participant, entry.content, entry.metadata));
+        }
+        return messageIds;
+    }
+    async markPrimarySummaryRequestRestartFailure(record, reason) {
+        if (record.dispatchKind === 'primary_summary_fallback_retry') {
+            const parent = await this.findPrimarySummaryRetryParent(record.requestId);
+            await this.updatePrimarySummaryRequestRecord(record.requestId, (entry) => ({
+                ...entry,
+                finalStatus: 'held',
+                fallbackHeldReason: reason,
+            }));
+            if (parent) {
+                await this.updatePrimarySummaryRequestRecord(parent.originalRequestId, (entry) => ({
+                    ...entry,
+                    finalStatus: 'held',
+                    fallbackStatus: 'held',
+                    fallbackHeldReason: reason,
+                }));
+            }
+            return;
+        }
+        await this.updatePrimarySummaryRequestRecord(record.requestId, (current) => ({
+            ...current,
+            finalStatus: 'held',
+            fallbackStatus: 'held',
+            fallbackHeldReason: reason,
+        }));
+    }
+    async persistPrimarySummaryHeldOutput(agent, requestId, holdReason, options) {
+        const record = await this.getPrimarySummaryRequestRecord(requestId);
+        if (!record) {
+            throw new Error(`Primary summary request '${requestId}' disappeared before held-output persistence`);
+        }
+        const placeholderBlocks = this.buildNonExecutedToolResults(options.assistantBlocks);
+        const entryCount = placeholderBlocks.length > 0 ? 2 : 1;
+        const assistantMetadata = this.buildPrimarySummarySettlementMetadata(record, {
+            outcome: 'held',
+            stopReason: options.stopReason,
+            holdReason,
+            providerInputTokens: options.providerInputTokens,
+            visibleAssistantOutput: options.visibleAssistantOutput,
+            executedToolCalls: options.executedToolCalls,
+            entryIndex: 0,
+            entryCount,
+            role: 'assistant',
+            kind: 'assistant_output',
+        });
+        const settlementId = assistantMetadata[PRIMARY_SUMMARY_SETTLEMENT_METADATA_KEY].settlementId;
+        const placeholderMetadata = placeholderBlocks.length > 0
+            ? this.buildPrimarySummarySettlementMetadata(record, {
+                outcome: 'held',
+                settlementId,
+                stopReason: options.stopReason,
+                holdReason,
+                providerInputTokens: options.providerInputTokens,
+                visibleAssistantOutput: options.visibleAssistantOutput,
+                executedToolCalls: options.executedToolCalls,
+                entryIndex: 1,
+                entryCount,
+                role: 'user',
+                kind: 'generated_tool_result',
+            })
+            : undefined;
+        const messageIds = await this.persistPrimarySummaryChronicleEntries(agent, [
+            { participant: agent.name, content: options.assistantBlocks, metadata: assistantMetadata },
+            ...(placeholderBlocks.length > 0 && placeholderMetadata
+                ? [{ participant: 'user', content: placeholderBlocks, metadata: placeholderMetadata }]
+                : []),
+        ]);
+        if (options.retryDispatch && options.retryPhase && options.assistantBlocks.length > 0) {
+            await this.recordPrimarySummaryRetryOutput(options.retryDispatch.originalRequestId, options.retryDispatch.intentId, {
+                phase: options.retryPhase,
+                contentHash: this.primarySummaryFallbackOutputPhaseHash(options.assistantBlocks),
+                messageId: messageIds[0] ?? '',
+                blockTypes: this.primarySummaryFallbackBlockTypes(options.assistantBlocks),
+                persistedAt: Date.now(),
+            });
+        }
+        if (options.retryDispatch) {
+            await this.holdPrimarySummaryRetryFamily(agent, requestId, options.retryDispatch, holdReason, options.holdData);
+            return;
+        }
+        await this.holdPrimarySummaryRequest(agent, requestId, holdReason, options.holdData);
+    }
+    async findPrimarySummaryRetryParent(retryRequestId) {
+        return this.withPrimarySummaryStateLock(() => {
+            const state = this.readPrimarySummaryFallbackState();
+            for (const record of state.requests) {
+                const intent = record.fallbackIntent;
+                if (intent?.retryRequestId === retryRequestId) {
+                    return { originalRequestId: record.requestId, intentId: intent.intentId };
+                }
+            }
+            return null;
+        });
+    }
+    async finalizePrimarySummarySettlementOnStartup(record) {
+        const agent = this.agents.get(record.agentName);
+        if (!agent)
+            return false;
+        const settlementEntries = this.primarySummaryLogicalSettlementEntries(agent, record.requestId);
+        if ('invalidReason' in settlementEntries)
+            return settlementEntries;
+        if (settlementEntries.length === 0) {
+            return false;
+        }
+        const currentBranch = agent.getCurrentBranchGeneration();
+        const assistantEntry = settlementEntries[0];
+        const settlement = assistantEntry.settlement;
+        if (assistantEntry.participant !== record.agentName ||
+            settlement.agentName !== record.agentName ||
+            settlement.dispatchKind !== record.dispatchKind ||
+            settlement.entryIndex !== 0 ||
+            settlement.role !== 'assistant' ||
+            settlement.kind !== 'assistant_output') {
+            return { invalidReason: 'primary_summary_settlement_invalid_assistant_marker_on_restart' };
+        }
+        if (!currentBranch) {
+            return { invalidReason: 'primary_summary_settlement_branch_unknown_on_restart' };
+        }
+        if (settlement.branch.id !== record.branch.id ||
+            settlement.branch.name !== record.branch.name ||
+            settlement.branch.generation !== record.branch.generation ||
+            settlement.branch.id !== currentBranch.id ||
+            settlement.branch.name !== currentBranch.name ||
+            settlement.branch.generation !== currentBranch.generation) {
+            return { invalidReason: 'primary_summary_settlement_branch_mismatch_on_restart' };
+        }
+        if (settlement.entryCount < 1 || settlement.entryCount > 2) {
+            return { invalidReason: 'primary_summary_settlement_entry_count_invalid_on_restart' };
+        }
+        const entriesByIndex = new Map();
+        for (const entry of settlementEntries) {
+            if (!this.primarySummarySettlementMetadataConsistent(settlement, entry.settlement)) {
+                return { invalidReason: 'primary_summary_settlement_marker_conflict_on_restart' };
+            }
+            if (entriesByIndex.has(entry.settlement.entryIndex)) {
+                return { invalidReason: 'primary_summary_settlement_duplicate_entry_on_restart' };
+            }
+            entriesByIndex.set(entry.settlement.entryIndex, entry);
+        }
+        const placeholderEntry = entriesByIndex.get(1);
+        if (placeholderEntry
+            && (placeholderEntry.participant !== 'user'
+                || placeholderEntry.settlement.role !== 'user'
+                || placeholderEntry.settlement.kind !== 'generated_tool_result')) {
+            return { invalidReason: 'primary_summary_settlement_placeholder_marker_invalid_on_restart' };
+        }
+        if ([...entriesByIndex.keys()].some((index) => index !== 0 && index !== 1)) {
+            return { invalidReason: 'primary_summary_settlement_out_of_order_entries_on_restart' };
+        }
+        const expectedPlaceholder = settlement.outcome === 'held'
+            ? this.buildNonExecutedToolResults(assistantEntry.content)
+            : [];
+        if (settlement.outcome === 'success') {
+            if (settlement.entryCount !== 1 || placeholderEntry) {
+                return { invalidReason: 'primary_summary_success_settlement_shape_invalid_on_restart' };
+            }
+        }
+        else {
+            const expectedEntryCount = expectedPlaceholder.length > 0 ? 2 : 1;
+            if (settlement.entryCount !== expectedEntryCount) {
+                return { invalidReason: 'primary_summary_held_settlement_shape_invalid_on_restart' };
+            }
+            if (placeholderEntry) {
+                if (!this.primarySummaryContentMatches(placeholderEntry.content, expectedPlaceholder)) {
+                    return { invalidReason: 'primary_summary_settlement_placeholder_content_mismatch_on_restart' };
+                }
+            }
+            else if (expectedPlaceholder.length > 0) {
+                const placeholderMetadata = this.buildPrimarySummarySettlementMetadata(record, {
+                    outcome: 'held',
+                    settlementId: settlement.settlementId,
+                    stopReason: settlement.stopReason,
+                    holdReason: settlement.holdReason,
+                    providerInputTokens: settlement.providerInputTokens,
+                    visibleAssistantOutput: settlement.visibleAssistantOutput,
+                    executedToolCalls: settlement.executedToolCalls,
+                    entryIndex: 1,
+                    entryCount: settlement.entryCount,
+                    role: 'user',
+                    kind: 'generated_tool_result',
+                });
+                await this.persistPrimarySummaryChronicleEntries(agent, [
+                    { participant: 'user', content: expectedPlaceholder, metadata: placeholderMetadata },
+                ]);
+            }
+        }
+        if (record.dispatchKind === 'primary_summary_fallback_retry') {
+            const parent = await this.findPrimarySummaryRetryParent(record.requestId);
+            if (!parent)
+                return { invalidReason: 'primary_summary_fallback_parent_missing_on_restart' };
+            if (settlement.outcome === 'success') {
+                await this.updatePrimarySummaryRequestRecord(record.requestId, (entry) => ({
+                    ...entry,
+                    stopReason: settlement.stopReason ?? entry.stopReason,
+                    providerInputTokens: settlement.providerInputTokens ?? entry.providerInputTokens,
+                    visibleAssistantOutput: settlement.visibleAssistantOutput,
+                    executedToolCalls: settlement.executedToolCalls,
+                    finalStatus: 'success',
+                    fallbackHeldReason: undefined,
+                }));
+                await this.updatePrimarySummaryRequestRecord(parent.originalRequestId, (entry) => {
+                    const intent = entry.fallbackIntent;
+                    return {
+                        ...entry,
+                        finalStatus: 'success',
+                        fallbackStatus: 'success',
+                        fallbackHeldReason: undefined,
+                        fallbackIntent: intent && intent.intentId === parent.intentId
+                            ? { ...intent, finalizedAt: intent.finalizedAt ?? Date.now() }
+                            : intent,
+                    };
+                });
+                return 'finalized';
+            }
+            await this.updatePrimarySummaryRequestRecord(record.requestId, (entry) => ({
+                ...entry,
+                stopReason: settlement.stopReason ?? entry.stopReason,
+                providerInputTokens: settlement.providerInputTokens ?? entry.providerInputTokens,
+                visibleAssistantOutput: settlement.visibleAssistantOutput,
+                executedToolCalls: settlement.executedToolCalls,
+                finalStatus: 'held',
+                fallbackHeldReason: settlement.holdReason,
+            }));
+            await this.updatePrimarySummaryRequestRecord(parent.originalRequestId, (entry) => ({
+                ...entry,
+                finalStatus: 'held',
+                fallbackStatus: 'held',
+                fallbackHeldReason: settlement.holdReason,
+            }));
+            return 'finalized';
+        }
+        await this.updatePrimarySummaryRequestRecord(record.requestId, (entry) => ({
+            ...entry,
+            stopReason: settlement.stopReason ?? entry.stopReason,
+            providerInputTokens: settlement.providerInputTokens ?? entry.providerInputTokens,
+            visibleAssistantOutput: settlement.visibleAssistantOutput,
+            executedToolCalls: settlement.executedToolCalls,
+            finalStatus: settlement.outcome === 'success' ? 'success' : 'held',
+            fallbackStatus: settlement.outcome === 'success' ? entry.fallbackStatus : 'held',
+            fallbackHeldReason: settlement.outcome === 'held' ? settlement.holdReason : undefined,
+        }));
+        return 'finalized';
+    }
+    summarizePrimarySummaryRetryRequest(request) {
+        const blockCounts = new Map();
+        for (const message of request.messages) {
+            for (const block of message.content) {
+                blockCounts.set(block.type, (blockCounts.get(block.type) ?? 0) + 1);
+            }
+        }
+        return {
+            kind: 'primary_summary_fallback_retry',
+            requestHash: this.hashJson(request),
+            systemHash: this.hashJson(request.system ?? ''),
+            messageCount: request.messages.length,
+            toolCount: request.tools?.length ?? 0,
+            participantCount: [...new Set(request.messages.map((message) => message.participant))].length,
+            blockCounts: Object.fromEntries([...blockCounts.entries()].sort(([left], [right]) => left.localeCompare(right))),
+            promptCaching: request.promptCaching === true,
+            cacheTtl: request.cacheTtl,
+            assistantParticipant: request.assistantParticipant,
+            requestCompleteBoundTokens: this.estimateRequestCompleteBoundTokens(request),
+        };
+    }
+    summarizePrimarySummaryRetryResponse(response) {
+        const blockCounts = new Map();
+        for (const block of response.content) {
+            blockCounts.set(block.type, (blockCounts.get(block.type) ?? 0) + 1);
+        }
+        return {
+            kind: 'primary_summary_fallback_retry',
+            stopReason: response.stopReason,
+            rawAssistantTextHash: response.rawAssistantText
+                ? this.hashJson(response.rawAssistantText)
+                : undefined,
+            blockCounts: Object.fromEntries([...blockCounts.entries()].sort(([left], [right]) => left.localeCompare(right))),
+            toolCallIds: response.toolCalls.map((call) => call.id),
+            usage: response.usage
+                ? {
+                    inputTokens: response.usage.inputTokens,
+                    outputTokens: response.usage.outputTokens,
+                }
+                : undefined,
+        };
+    }
+    async claimPrimarySummaryRetryIntent(originalRequestId, intentId, retryRequestId) {
+        let outcome = 'missing';
+        await this.updatePrimarySummaryRequestRecord(originalRequestId, (record) => {
+            const intent = record.fallbackIntent;
+            if (!intent || intent.intentId !== intentId || record.fallbackStatus !== 'pending') {
+                return record;
+            }
+            if (intent.retryRequestId && intent.retryRequestId !== retryRequestId) {
+                outcome = 'duplicate';
+                return record;
+            }
+            outcome = 'claimed';
+            return {
+                ...record,
+                fallbackIntent: {
+                    ...intent,
+                    retryRequestId,
+                    dispatchedAt: intent.dispatchedAt ?? Date.now(),
+                },
+            };
+        });
+        return outcome;
+    }
+    async validatePrimarySummaryRetryMutation(agent, requestId, retryDispatch, compiledRequest, artifacts, phase) {
+        const branch = agent.getCurrentBranchGeneration();
+        if (!branch || branch.id !== retryDispatch.branch.id || branch.generation !== retryDispatch.branch.generation) {
+            return {
+                ok: false,
+                reason: `primary_summary_fallback_branch_changed_${phase}`,
+                data: {
+                    expectedBranchId: retryDispatch.branch.id,
+                    expectedGeneration: retryDispatch.branch.generation,
+                    actualBranchId: branch?.id,
+                    actualGeneration: branch?.generation,
+                },
+            };
+        }
+        const requestHash = this.hashJson(compiledRequest);
+        if (requestHash !== retryDispatch.expectedRetryRequestHash) {
+            return {
+                ok: false,
+                reason: `primary_summary_fallback_request_changed_${phase}`,
+                data: {
+                    expectedRetryRequestHash: retryDispatch.expectedRetryRequestHash,
+                    actualRetryRequestHash: requestHash,
+                },
+            };
+        }
+        if (this.primarySummaryProjectionKeys(artifacts.compileResult.primarySummaryProjection ?? null).join('\u0000') !==
+            retryDispatch.originalProjectionKeys.join('\u0000')) {
+            return {
+                ok: false,
+                reason: `primary_summary_fallback_projection_changed_${phase}`,
+                data: {
+                    expectedProjectionKeys: retryDispatch.originalProjectionKeys,
+                    actualProjectionKeys: this.primarySummaryProjectionKeys(artifacts.compileResult.primarySummaryProjection ?? null),
+                },
+            };
+        }
+        if (!this.primarySummaryContractsMatch(artifacts.contract, retryDispatch.originalArtifacts.contract)) {
+            return {
+                ok: false,
+                reason: `primary_summary_fallback_contract_changed_${phase}`,
+                data: {
+                    expectedContract: retryDispatch.originalArtifacts.contract,
+                    actualContract: artifacts.contract,
+                },
+            };
+        }
+        const original = await this.getPrimarySummaryRequestRecord(retryDispatch.originalRequestId);
+        if (!original?.fallbackIntent ||
+            original.fallbackIntent.intentId !== retryDispatch.intentId ||
+            original.fallbackIntent.retryRequestId !== requestId ||
+            original.fallbackStatus !== 'pending') {
+            return {
+                ok: false,
+                reason: `primary_summary_fallback_intent_changed_${phase}`,
+                data: {
+                    expectedIntentId: retryDispatch.intentId,
+                    actualIntentId: original?.fallbackIntent?.intentId,
+                    retryRequestId: original?.fallbackIntent?.retryRequestId,
+                    fallbackStatus: original?.fallbackStatus,
+                },
+            };
+        }
+        return { ok: true };
+    }
+    async recordPrimarySummaryRetryQuarantine(originalRequestId, intentId) {
+        await this.updatePrimarySummaryRequestRecord(originalRequestId, (record) => {
+            const intent = record.fallbackIntent;
+            if (!intent || intent.intentId !== intentId || intent.quarantinePersistedAt)
+                return record;
+            return {
+                ...record,
+                fallbackIntent: {
+                    ...intent,
+                    quarantinePersistedAt: Date.now(),
+                },
+            };
+        });
+    }
+    async recordPrimarySummaryRetryOutput(originalRequestId, intentId, output) {
+        await this.updatePrimarySummaryRequestRecord(originalRequestId, (record) => {
+            const intent = record.fallbackIntent;
+            if (!intent || intent.intentId !== intentId)
+                return record;
+            const existing = intent.outputs?.find((entry) => entry.phase === output.phase);
+            if (existing &&
+                existing.contentHash === output.contentHash &&
+                existing.messageId === output.messageId) {
+                return record;
+            }
+            if (existing) {
+                throw new Error(`Primary summary fallback output phase '${output.phase}' changed after persistence`);
+            }
+            return {
+                ...record,
+                fallbackIntent: {
+                    ...intent,
+                    outputs: [...(intent.outputs ?? []), output],
+                },
+            };
+        });
+    }
+    async recordPrimarySummaryRetryToolDispatch(originalRequestId, intentId, call) {
+        await this.updatePrimarySummaryRequestRecord(originalRequestId, (record) => {
+            const intent = record.fallbackIntent;
+            if (!intent || intent.intentId !== intentId)
+                return record;
+            const inputHash = this.hashJson(call.input);
+            const existing = intent.toolDispatches?.find((entry) => entry.callId === call.id);
+            if (existing?.inputHash === inputHash)
+                return record;
+            if (existing) {
+                throw new Error(`Primary summary fallback tool dispatch '${call.id}' changed after persistence`);
+            }
+            return {
+                ...record,
+                fallbackIntent: {
+                    ...intent,
+                    toolDispatches: [
+                        ...(intent.toolDispatches ?? []),
+                        {
+                            callId: call.id,
+                            inputHash,
+                            recordedAt: Date.now(),
+                        },
+                    ],
+                },
+            };
+        });
+    }
+    async resolveContextBudgetRestartDispatch(requestId, retryDispatch) {
+        const retryIdentity = retryDispatch
+            ? {
+                requestId,
+                dispatchKind: 'primary_summary_fallback_retry',
+                originalRequestId: retryDispatch.originalRequestId,
+                intentId: retryDispatch.intentId,
+            }
+            : null;
+        const record = await this.getPrimarySummaryRequestRecord(requestId);
+        if (record?.dispatchKind === 'primary_summary_fallback_retry' && retryIdentity) {
+            return retryIdentity;
+        }
+        if (retryIdentity) {
+            const original = await this.getPrimarySummaryRequestRecord(retryIdentity.originalRequestId);
+            if (original?.fallbackIntent?.intentId === retryIdentity.intentId
+                && original.fallbackIntent.retryRequestId === requestId) {
+                return retryIdentity;
+            }
+        }
+        return {
+            requestId,
+            dispatchKind: 'primary',
+        };
+    }
+    contextBudgetRestartMatchesIdentity(request, identity) {
+        if (request.reason !== 'context_budget_restart')
+            return false;
+        const restart = request.contextBudgetRestart;
+        if (!restart)
+            return false;
+        if (restart.dispatchKind !== identity.dispatchKind)
+            return false;
+        if (restart.requestId !== identity.requestId)
+            return false;
+        if (identity.dispatchKind !== 'primary_summary_fallback_retry')
+            return true;
+        return restart.originalRequestId === identity.originalRequestId
+            && restart.intentId === identity.intentId;
+    }
+    clearQueuedContextBudgetRestart(identity) {
+        const before = this.pendingRequests.length;
+        this.pendingRequests = this.pendingRequests.filter((request) => !this.contextBudgetRestartMatchesIdentity(request, identity));
+        return before - this.pendingRequests.length;
+    }
+    async markPrimarySummaryRetrySuccess(requestId, retryDispatch, stopReason, providerInputTokens, visibleAssistantOutput, executedToolCalls) {
+        await this.updatePrimarySummaryRequestRecord(requestId, (record) => ({
+            ...record,
+            stopReason,
+            providerInputTokens,
+            visibleAssistantOutput,
+            executedToolCalls,
+            finalStatus: 'success',
+            fallbackHeldReason: undefined,
+        }));
+        await this.updatePrimarySummaryRequestRecord(retryDispatch.originalRequestId, (record) => {
+            const intent = record.fallbackIntent;
+            return {
+                ...record,
+                finalStatus: 'success',
+                fallbackStatus: 'success',
+                fallbackHeldReason: undefined,
+                fallbackIntent: intent && intent.intentId === retryDispatch.intentId
+                    ? { ...intent, finalizedAt: Date.now() }
+                    : intent,
+            };
+        });
+    }
+    async holdPrimarySummaryRetryFamily(agent, requestId, retryDispatch, reason, data, options) {
+        const clearedQueuedContextBudgetRestarts = this.clearQueuedContextBudgetRestart({
+            requestId,
+            dispatchKind: 'primary_summary_fallback_retry',
+            originalRequestId: retryDispatch.originalRequestId,
+            intentId: retryDispatch.intentId,
+        });
+        const holdData = clearedQueuedContextBudgetRestarts > 0
+            ? { ...(data ?? {}), clearedQueuedContextBudgetRestarts }
+            : data;
+        await this.updatePrimarySummaryRequestRecord(requestId, (record) => ({
+            ...record,
+            ...(options?.stopReason ? { stopReason: options.stopReason } : {}),
+            finalStatus: 'held',
+            fallbackHeldReason: reason,
+        }));
+        await this.updatePrimarySummaryRequestRecord(retryDispatch.originalRequestId, (record) => ({
+            ...record,
+            finalStatus: 'held',
+            fallbackStatus: 'held',
+            fallbackHeldReason: reason,
+        }));
+        this.opsAlert('refusal-held', agent.name, reason, { data: holdData });
+        if (options?.emitChronicleMarker === false)
+            return;
+        try {
+            agent.getContextManager().addMessage('user', [{
+                    type: 'text',
+                    text: `[refusal-held] Your previous turn was refused by the provider and ` +
+                        `is being held for operator review rather than silently retried. ` +
+                        `Automatic raw-expansion recovery was either unsafe or unsuccessful.`,
+                }], { system: true, kind: 'refusal-held', reason });
+        }
+        catch (error) {
+            console.error('[refusal-held] could not record chronicle marker:', error);
+        }
+    }
+    async primarySummaryRetryAlreadySucceeded(requestId, retryDispatch) {
+        const [retryRecord, originalRecord] = await Promise.all([
+            this.getPrimarySummaryRequestRecord(requestId),
+            this.getPrimarySummaryRequestRecord(retryDispatch.originalRequestId),
+        ]);
+        return retryRecord?.finalStatus === 'success'
+            || originalRecord?.fallbackStatus === 'success'
+            || originalRecord?.finalStatus === 'success';
+    }
+    async primarySummaryRetryFamilyAlreadySettled(requestId, retryDispatch) {
+        const [retryRecord, originalRecord] = await Promise.all([
+            this.getPrimarySummaryRequestRecord(requestId),
+            this.getPrimarySummaryRequestRecord(retryDispatch.originalRequestId),
+        ]);
+        return retryRecord?.finalStatus === 'held'
+            || retryRecord?.finalStatus === 'success'
+            || originalRecord?.fallbackStatus === 'held'
+            || originalRecord?.fallbackStatus === 'success'
+            || originalRecord?.finalStatus === 'held'
+            || originalRecord?.finalStatus === 'success';
+    }
+    async holdPrimarySummaryRequest(agent, requestId, reason, data) {
+        await this.updatePrimarySummaryRequestRecord(requestId, (record) => ({
+            ...record,
+            finalStatus: 'held',
+            fallbackStatus: 'held',
+            fallbackHeldReason: reason,
+        }));
+        this.opsAlert('refusal-held', agent.name, reason, { data });
+        try {
+            agent.getContextManager().addMessage('user', [{
+                    type: 'text',
+                    text: `[refusal-held] Your previous turn was refused by the provider and ` +
+                        `is being held for operator review rather than silently retried. ` +
+                        `Automatic raw-expansion recovery was either unsafe or unsuccessful.`,
+                }], { system: true, kind: 'refusal-held', reason });
+        }
+        catch (error) {
+            console.error('[refusal-held] could not record chronicle marker:', error);
+        }
+    }
+    hasVisibleAssistantOutput(blocks) {
+        return blocks.some((block) => block.type !== 'thinking' && block.type !== 'redacted_thinking');
+    }
+    buildPrimarySummaryRequestRecord(agent, requestId, dispatchKind, request, artifacts, branch, stopReason, visibleAssistantOutput, executedToolCalls, providerInputTokens, finalStatus) {
+        const projection = artifacts?.compileResult.primarySummaryProjection ?? null;
+        return {
+            requestId,
+            agentName: agent.name,
+            namespace: projection?.namespace ?? `agents/${agent.name}`,
+            timestamp: Date.now(),
+            dispatchKind,
+            branch: branch
+                ? { id: branch.id, name: branch.name, generation: branch.generation }
+                : { id: 'unknown', name: 'unknown', generation: -1 },
+            projection,
+            requestInputBoundTokens: this.estimateRequestInputBoundTokens(request),
+            requestCompleteBoundTokens: this.estimateRequestCompleteBoundTokens(request),
+            providerInputTokens,
+            systemHash: artifacts?.contract.systemHash ?? this.hashJson(request.system ?? ''),
+            modelConfigHash: artifacts?.contract.modelConfigHash ?? this.hashJson({ request: request.config }),
+            toolContractHash: artifacts?.contract.toolContractHash ?? this.hashJson(request.tools ?? []),
+            stopReason,
+            visibleAssistantOutput,
+            executedToolCalls,
+            finalStatus,
+        };
+    }
     /** Liveness ping for an active ephemeral run (no-op otherwise). */
     touchEphemeralRun(agentName, inferenceStarted = false) {
         const run = this.ephemeralRuns.get(agentName);
@@ -1238,6 +2604,66 @@ export class AgentFramework {
             'tagsAll / tagsNone) or in gate.js.',
         inputSchema: { type: 'object' },
     };
+    /** Synthesized save_image tool — present when a workspace module is
+     *  registered. Lets the agent persist an image it has already seen in its
+     *  own context (Discord attachments arrive inlined as base64 and are
+     *  otherwise unreachable as files). */
+    static SAVE_IMAGE_TOOL = {
+        name: 'save_recent_image',
+        description: 'Save one or more recent images from your own context to workspace files. ' +
+            'Images are counted back from the most recent (index 0). A single image is ' +
+            'written to `path` as given (e.g. "project/photos/cat.png"); when `count` > 1 ' +
+            'the range index..index+count-1 is saved with numeric suffixes ' +
+            '("cat-0.png", "cat-1.png", …; 0 = the newest of the range). Saved files are ' +
+            'visible via workspace tools and the /files/ endpoint.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Mount-prefixed destination path, e.g. "project/photos/name.png".',
+                },
+                index: {
+                    type: 'number',
+                    description: 'Which image, counting back from the most recent (0 = most recent). Default 0.',
+                },
+                count: {
+                    type: 'number',
+                    description: 'How many images to save, starting at `index` and going further back. Default 1.',
+                },
+            },
+            required: ['path'],
+        },
+    };
+    static AGENT_SETTINGS_TOOL = {
+        name: 'agent_settings',
+        description: 'Read or change your hot runtime settings. This intentionally exposes only ' +
+            'context budget, recent raw tail size, transition pace, and same-round think text routing; model, prompts, ' +
+            'folding strategy, and other restart-bound configuration are not mutable here. ' +
+            'Lower context budgets converge gradually under the transition pace before ' +
+            'becoming the hard live limit; increases take effect immediately.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['get', 'update', 'reset', 'cancel'] },
+                context_budget_tokens: { type: 'number', description: 'Total input context budget, including the reserved response allowance.' },
+                tail_tokens: { type: 'number', description: 'Recent raw context retained verbatim.' },
+                transition_pace_tokens: { type: 'number', description: 'Maximum ordinary KV re-read/perturbation per compile while converging.' },
+                same_round_think_text_policy: {
+                    type: 'string',
+                    enum: ['public', 'private'],
+                    description: 'Routing policy for ordinary text emitted in the same native assistant round as think(). ' +
+                        "Omitted in the recipe preserves the compatibility carry-forward: public.",
+                },
+                settings: {
+                    type: 'array',
+                    items: { type: 'string', enum: ['context_budget_tokens', 'tail_tokens', 'transition_pace_tokens', 'same_round_think_text_policy'] },
+                    description: 'For reset: settings to restore to recipe values. Omit to reset all.',
+                },
+            },
+            required: ['action'],
+        },
+    };
     /** Reserved chat:* core vocabulary (MCPL RFC-001 §4) — short descriptions so
      *  the agent can author rules without reading the spec. */
     static CHAT_CORE_TAGS = {
@@ -1619,8 +3045,25 @@ export class AgentFramework {
                 };
             }
             const target = allMessages[allMessages.length - 1 - n];
-            const branchName = cm.branchAt(target.id, `undo-msgs/${agentName}/${Date.now()}`);
+            const discarded = allMessages.slice(allMessages.length - n);
+            const removedRefs = extractDiscordAwarenessRefs(discarded);
+            const sourceBranch = this.store.currentBranch().name;
+            const targetBranch = `undo-msgs/${agentName}/${Date.now()}`;
+            // Prepare the external side effect before switching Chronicle. If the
+            // process dies after the switch but before activate(), startup promotes
+            // this batch by matching targetBranch to the active branch.
+            const markerBatch = this.discordAwarenessOutbox?.prepare({
+                agentName,
+                sourceBranch,
+                targetBranch,
+                refs: removedRefs,
+                emoji: this.discordAwarenessEmoji,
+            }) ?? null;
+            const branchName = cm.branchAt(target.id, targetBranch);
             await cm.switchBranch(branchName);
+            if (markerBatch)
+                this.discordAwarenessOutbox.activate(markerBatch.id);
+            await this.syncDiscordAwarenessMarkers();
             // Materialize config files from the new branch (fire-and-forget; gate
             // picks up via mtime) — mirrors undoLastTurn.
             const wsUndo = this.moduleRegistry.getModule('workspace');
@@ -1634,6 +3077,7 @@ export class AgentFramework {
             return {
                 ok: true,
                 messagesRemoved: n,
+                removedRefs,
                 lastVisible: await this.lastVisiblePreview(agentName),
             };
         }
@@ -1660,6 +3104,7 @@ export class AgentFramework {
         if (undone === 0) {
             return { ok: true, undone: 0, requested, lastVisible: null };
         }
+        await this.syncDiscordAwarenessMarkers();
         return { ok: true, undone, requested, lastVisible: await this.lastVisiblePreview(agentName) };
     }
     /**
@@ -2155,6 +3600,10 @@ export class AgentFramework {
             debugLogContext: !!process.env.DEBUG_CONTEXT,
         });
         const agent = new Agent(config, contextManager, this.membrane);
+        const restoredSettings = this.readAgentRuntimeSettings(config.name);
+        if (restoredSettings) {
+            agent.restoreRuntimeSettings(this.validatePersistedAgentRuntimeSettings(config.name, restoredSettings));
+        }
         this.agents.set(config.name, agent);
         this.agentConfigs.set(config.name, config);
         // First non-ephemeral agent becomes the primary for message routing
@@ -2183,13 +3632,22 @@ export class AgentFramework {
         this.sweepExpiredConversations();
         // Check for inference requests
         await this.processInferenceRequests();
-        // Yield to the event loop between iterations.
-        // Full 10ms sleep when truly idle; minimal yield when streams are active
-        // (needed to let stream microtasks and tool-call callbacks execute).
-        if (!event && this.pendingRequests.length === 0) {
+        // Yield to the event loop between iterations. A pending inference request
+        // is not necessarily runnable: while its agent is streaming or waiting for
+        // tools, processInferenceRequests() deliberately requeues it. Treating that
+        // requeued request as "work made progress" creates a microtask-only polling
+        // loop. If activeStreams bookkeeping is absent/stale at the same time, the
+        // old code had no await at all and starved the tool-result and HTTP I/O that
+        // could make the agent runnable again (the Sol outage, 2026-07-15).
+        //
+        // No queue event means no foreground progress, so always take the normal
+        // polling backoff. After an event, retain the low-latency macrotask yield
+        // while background work remains. Both paths give Bun/Node a real event-loop
+        // turn; neither can recurse forever through already-resolved promises.
+        if (!event) {
             await new Promise((resolve) => setTimeout(resolve, 10));
         }
-        else if (this.activeStreams.size > 0) {
+        else if (this.pendingRequests.length > 0 || this.activeStreams.size > 0) {
             await new Promise((resolve) => setTimeout(resolve, 0));
         }
     }
@@ -2226,6 +3684,7 @@ export class AgentFramework {
                 // Cast to AgentState to bypass TypeScript's control flow narrowing
                 const currentState = agent.state;
                 if (currentState.status === 'ready') {
+                    const activeStreamContext = this.activeStreamContexts.get(agent.name);
                     // Flush pending assistant blocks (tool_use + preamble text) to context
                     const pendingBlocks = this.pendingAssistantBlocks.get(agent.name);
                     if (pendingBlocks) {
@@ -2247,18 +3706,66 @@ export class AgentFramework {
                         isError: tc.result.isError,
                     }));
                     agent.getContextManager().addMessage('user', toolResultContent);
-                    // Flush any messages that were deferred while waiting for tool results.
-                    // Route to the PRIMARY agent — deferred messages are framework-level
-                    // (e.g. subagent return notifications) meant for the main conversation.
+                    // 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
+                    // notifications) meant for the main conversation.
+                    //
+                    // Hear-while-acting: messages flushed into THIS agent's own window
+                    // are also collected for mid-turn injection — passed to the membrane
+                    // with the tool results below, so the NEXT inference round of the
+                    // live turn sees them instead of the agent staying deaf until the
+                    // turn ends. The window stores them here, right after the
+                    // tool_result message, which is exactly where the membrane appends
+                    // them in the live conversation — same participant, same content
+                    // blocks, same metadata, and compile() emits recent messages
+                    // verbatim, so the next turn's compiled prefix byte-matches the
+                    // live request (prompt-cache safe).
+                    //
+                    // The queue is drained ONLY at the target agent's own boundary:
+                    // draining at another agent's boundary would store the messages
+                    // mid-turn in the target's window without injecting them into the
+                    // target's live stream (deaf agent + window/live divergence). Left
+                    // queued, they flush at the target's own next boundary — with
+                    // injection — or in driveStream's finally when its turn ends.
+                    const midTurnInjections = [];
                     if (this.deferredMessages.length > 0) {
-                        const deferred = this.deferredMessages.splice(0);
-                        const primary = this.primaryAgentName
-                            ? this.agents.get(this.primaryAgentName)
-                            : agent;
-                        for (const msg of deferred) {
-                            (primary ?? agent).getContextManager().addMessage(msg.participant, msg.content, msg.metadata);
+                        const target = (this.primaryAgentName ? this.agents.get(this.primaryAgentName) : undefined) ?? agent;
+                        if (target === agent) {
+                            const deferred = this.deferredMessages.splice(0);
+                            for (const msg of deferred) {
+                                target.getContextManager().addMessage(msg.participant, msg.content, msg.metadata);
+                                // Injection guards: tool blocks would corrupt the tool-cycle
+                                // structure the membrane enforces, and a message named as the
+                                // agent itself would render as an ASSISTANT turn on the wire
+                                // (an unintended prefill the model would continue). Such
+                                // messages stay window-only — visible next turn.
+                                const hasToolBlocks = msg.content.some((b) => b.type === 'tool_use' || b.type === 'tool_result');
+                                if (!hasToolBlocks && msg.participant !== agent.name) {
+                                    midTurnInjections.push({
+                                        participant: msg.participant,
+                                        content: msg.content,
+                                        ...(msg.metadata ? { metadata: msg.metadata } : {}),
+                                    });
+                                }
+                            }
                         }
                     }
+                    // A newly injected message begins a new conversational round inside
+                    // the same provider inference. Remember that boundary for
+                    // driveStream: an explicit send in the preceding round must not
+                    // silence the reply, and the newest channel-bearing injection is
+                    // now the reply locus. Map presence matters even without a channel
+                    // (CLI/module input): it still clears the prior send suppression.
+                    if (midTurnInjections.length > 0) {
+                        const injectedChannelId = midTurnInjections.reduce((latest, injection) => {
+                            const candidate = injection.metadata?.channelId;
+                            return typeof candidate === 'string' && candidate.length > 0
+                                ? candidate
+                                : latest;
+                        }, null);
+                        this.midTurnRoutingResets.set(agent.name, injectedChannelId);
+                    }
                     // Check if any tool result requested endTurn
                     const shouldEndTurn = currentState.toolResults.some(tc => tc.result.endTurn);
                     // Check if accumulated input tokens exceed the agent's budget
@@ -2288,6 +3795,34 @@ export class AgentFramework {
                         // a terminal failure — rejecting an ephemeral's promise mid-run
                         // and emitting a spurious inference:exhausted (same race shape as
                         // endTurn above).
+                        const requestId = activeStreamContext?.requestId;
+                        const primarySummaryRetry = activeStreamContext?.trigger?.primarySummaryFallbackRetry;
+                        const compiledRequest = activeStreamContext?.compiledRequest;
+                        const artifacts = activeStreamContext?.artifacts;
+                        const restartDispatch = await this.resolveContextBudgetRestartDispatch(requestId ?? `${agent.name}:context_budget_restart`, primarySummaryRetry);
+                        if (restartDispatch.dispatchKind === 'primary_summary_fallback_retry'
+                            && requestId
+                            && primarySummaryRetry
+                            && compiledRequest
+                            && artifacts) {
+                            const validation = await this.validatePrimarySummaryRetryMutation(agent, requestId, primarySummaryRetry, compiledRequest, artifacts, 'before_context_budget_restart_hold');
+                            if (!validation.ok) {
+                                await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, validation.reason, validation.data, { emitChronicleMarker: false, stopReason: 'abort' });
+                            }
+                            else {
+                                await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, 'primary_summary_fallback_context_budget_restart_required', {
+                                    inputTokens: agent.lastStreamInputTokens,
+                                    budget: agent.maxStreamTokens,
+                                    originalRequestId: primarySummaryRetry.originalRequestId,
+                                    intentId: primarySummaryRetry.intentId,
+                                }, { emitChronicleMarker: false, stopReason: 'abort' });
+                            }
+                            this.frameworkCancelledStreams.set(`${agent.name}:${agent.streamId}`, 'budget_restart');
+                            currentState.stream?.cancel();
+                            agent.reset();
+                            this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
+                            return;
+                        }
                         if (currentState.stream) {
                             this.frameworkCancelledStreams.set(`${agent.name}:${agent.streamId}`, 'budget_restart');
                         }
@@ -2304,14 +3839,23 @@ export class AgentFramework {
                             reason: 'context_budget_restart',
                             source: 'framework',
                             timestamp: Date.now(),
+                            channelId: activeStreamContext?.trigger?.channelId,
+                            contextBudgetRestart: restartDispatch,
                         });
                     }
                     else if (currentState.stream) {
-                        // Streaming path: convert results and resume the stream
+                        // Streaming path: convert results and resume the stream.
+                        // Mid-turn messages collected above ride along as injected user
+                        // messages (membrane ≥0.5.72) — appended after the tool_result
+                        // envelope so the next round of THIS turn hears them.
                         const membraneResults = currentState.toolResults.map(tc => this.toMembraneToolResult(tc.id, tc.result, maxChars));
-                        currentState.stream.provideToolResults(membraneResults);
+                        currentState.stream.provideToolResults(membraneResults, midTurnInjections.length > 0 ? { injectedMessages: midTurnInjections } : undefined);
                         agent.setStreaming(currentState.stream);
-                        this.emitTrace({ type: 'inference:stream_resumed', agentName: agent.name });
+                        this.emitTrace({
+                            type: 'inference:stream_resumed',
+                            agentName: agent.name,
+                            ...(midTurnInjections.length > 0 ? { injectedMessages: midTurnInjections.length } : {}),
+                        });
                     }
                     else {
                         // Non-streaming fallback: schedule re-inference
@@ -2689,6 +4233,10 @@ export class AgentFramework {
      * Convert an MCPL push event to a context message.
      */
     handleMcplPushEvent(event) {
+        const triggerChannel = this.derivePushEventChannel(event.origin);
+        if (triggerChannel && this.channelRegistry) {
+            this.channelRegistry.ensureChannelRegistered(event.serverId, triggerChannel.channelId, triggerChannel.label);
+        }
         const metadata = {
             ...event.origin,
             serverId: event.serverId,
@@ -2696,17 +4244,36 @@ export class AgentFramework {
             eventId: event.eventId,
             triggered: event.triggerInference ?? false,
         };
-        const id = this.addMessage('user', event.content, metadata);
-        this.emitTrace({ type: 'message:added', messageId: id, source: 'mcpl:push-event' });
-        // Some push events carry a channel of origin (Discord DMs arrive here, not
-        // via channels/incoming, because discord-mcpl forwards them with the channel
-        // closed). Register + open that channel so routeSpeech can resolve it, and
-        // thread it onto the wake request so the reply routes back to it instead of
-        // the global locus (item-3 redux, DM sub-case).
-        const triggerChannel = this.derivePushEventChannel(event.origin);
-        if (triggerChannel && this.channelRegistry) {
-            this.channelRegistry.ensureChannelRegistered(event.serverId, triggerChannel.channelId, triggerChannel.label);
+        const content = [...event.content];
+        const addressedWhileClosed = triggerChannel &&
+            event.tags?.includes('chat:addressed') &&
+            this.channelRegistry &&
+            !this.channelRegistry.isChannelOpen(triggerChannel.channelId);
+        if (addressedWhileClosed) {
+            const descriptor = this.channelRegistry.getDescriptor(triggerChannel.channelId);
+            const messageId = typeof event.origin?.messageId === 'string'
+                ? event.origin.messageId
+                : event.eventId;
+            const maxBackscroll = descriptor?.capabilities?.history?.maxMessages ?? 0;
+            content.push({
+                type: 'text',
+                text: `\n[Channel invitation] You were addressed in closed channel ` +
+                    `"${triggerChannel.label ?? triggerChannel.channelId}" (${triggerChannel.channelId}, server ${event.serverId}). ` +
+                    `You received this one message without subscribing. ` +
+                    (maxBackscroll > 0
+                        ? `To subscribe, call channel_open with channelId, serverId "${event.serverId}", backscroll (0-${maxBackscroll}), and beforeMessageId "${messageId}". `
+                        : `To subscribe, call channel_open with this channelId and serverId "${event.serverId}". `) +
+                    `You may reply once without subscribing. To remain closed, call channel_decline ` +
+                    `with channelId, serverId "${event.serverId}", and messageId "${messageId}"; ` +
+                    `optionally set acknowledge to a surface value such as 👀.`,
+            });
+            metadata.channelInvitation = true;
+            metadata.channelOpen = false;
+            metadata.channelId = triggerChannel.channelId;
+            metadata.invitationMessageId = messageId;
         }
+        const id = this.addMessage('user', content, metadata);
+        this.emitTrace({ type: 'message:added', messageId: id, source: 'mcpl:push-event' });
         if (event.triggerInference) {
             // Default broadcast excludes conversation forks (channel-driven).
             const targetAgents = event.targetAgents
@@ -2771,7 +4338,8 @@ export class AgentFramework {
         // Clear pending (we'll re-add if inference doesn't run)
         this.pendingRequests = [];
         // Check each agent
-        for (const [agentName, requests] of requestsByAgent) {
+        for (const [agentName, queuedRequests] of requestsByAgent) {
+            let requests = queuedRequests;
             const agent = this.agents.get(agentName);
             if (!agent) {
                 // Agent not found — request is orphaned. Emit warning and drop.
@@ -2790,7 +4358,13 @@ export class AgentFramework {
             if (agent.state.status === 'inferring' || agent.state.status === 'streaming' || agent.state.status === 'waiting_for_tools') {
                 // Re-queue requests, but warn if they've been pending too long
                 const oldest = Math.min(...requests.map(r => r.timestamp));
-                if (now - oldest > STALE_REQUEST_MS) {
+                if (now - oldest > STALE_REQUEST_MS &&
+                    (this.staleWarnAt.get(agentName) ?? 0) < now - 60_000) {
+                    // Trace and stderr share the throttle. The old code throttled only
+                    // stderr, so a long-running tool call generated one trace per poll
+                    // (up to 100/sec after the scheduler backoff), adding avoidable work
+                    // precisely while the agent was already under pressure.
+                    this.staleWarnAt.set(agentName, now);
                     this.emitTrace({
                         type: 'inference:request_stale',
                         agentName,
@@ -2798,16 +4372,21 @@ export class AgentFramework {
                         requestCount: requests.length,
                         oldestRequestAge: now - oldest,
                     });
-                    // Loud (but throttled) note that requests are waiting on a busy agent.
-                    if ((this.staleWarnAt.get(agentName) ?? 0) < now - 60_000) {
-                        this.staleWarnAt.set(agentName, now);
-                        console.error(`[inference-stale] agent=${agentName} busy (${agent.state.status}) — ` +
-                            `${requests.length} request(s) waiting ${Math.round((now - oldest) / 1000)}s`);
-                    }
+                    console.error(`[inference-stale] agent=${agentName} busy (${agent.state.status}) — ` +
+                        `${requests.length} request(s) waiting ${Math.round((now - oldest) / 1000)}s`);
                 }
                 this.pendingRequests.push(...requests);
                 continue;
             }
+            if (this.discordAwarenessBarrier) {
+                this.pendingRequests.push(...requests);
+                continue;
+            }
+            requests = requests.filter((request) => request.reason !== 'context_budget_restart'
+                || request.contextBudgetRestart?.dispatchKind !== 'primary_summary_fallback_retry');
+            if (requests.length === 0) {
+                continue;
+            }
             // Check policy
             if (!this.inferencePolicy.shouldInfer(agentName, requests, state)) {
                 // Loud drop: a queued request that dies here is otherwise invisible —
@@ -2818,7 +4397,13 @@ export class AgentFramework {
                 continue;
             }
             // Start streaming inference (non-blocking — driveStream runs in background)
-            const trigger = requests[0];
+            const trigger = requests.find((request) => request.primarySummaryFallbackRetry) ?? requests[0];
+            if (trigger.primarySummaryFallbackRetry) {
+                for (const request of requests) {
+                    if (request !== trigger)
+                        this.pendingRequests.push(request);
+                }
+            }
             // Route this turn's auto-published speech to the channel that triggered
             // it (item-3 redux). A batched wake may carry several triggering channels
             // (messages arrived in >1 channel while the agent was busy/idle) — reply
@@ -2833,7 +4418,7 @@ export class AgentFramework {
     }
     async startAgentStream(agent, trigger, attempt = 0) {
         // Record turn checkpoint before inference (only on first attempt, not retries)
-        if (attempt === 0) {
+        if (attempt === 0 && trigger?.reason !== 'primary-summary-fallback-retry') {
             this.recordTurnCheckpoint(agent.name);
             this.redoStacks.delete(agent.name); // new work invalidates redo
         }
@@ -2853,45 +4438,180 @@ export class AgentFramework {
         this.emitTrace({ type: 'inference:started', agentName: agent.name });
         this.eventGate?.onInferenceStarted(agent.name);
         this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), startedAt: Date.now() });
+        const requestId = `${agent.name}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
         try {
-            const allTools = this.getAllTools();
+            const requestSnapshot = this.captureInferenceToolSnapshot(agent);
+            const allTools = this.getToolsForAgent(agent.name, requestSnapshot);
             const tools = allTools.filter((t) => agent.canUseTool(t.name));
-            // Gather context from modules (pull-based) and MCPL hooks (push-based)
-            // Both produce ContextInjection[] that get merged before inference.
-            let injections;
-            // Module gatherContext (fail-open, per-module timeout — the module's
-            // contextTimeoutMs, else the registry default). Injections are
-            // channel-scoped via scopeInjectionsForAgent, matching the MCPL hook
-            // injections below, so conversation forks don't see cross-channel
-            // content.
-            try {
-                const moduleInjections = this.scopeInjectionsForAgent(agent.name, await this.moduleRegistry.gatherContext(agent.name));
-                if (moduleInjections.length > 0) {
-                    injections = moduleInjections;
+            const fallbackConfig = this.primarySummaryFallbackConfig(agent);
+            const retryDispatch = trigger?.primarySummaryFallbackRetry;
+            let compiledRequest;
+            let artifacts;
+            let branch = agent.getCurrentBranchGeneration();
+            if (retryDispatch) {
+                if (!fallbackConfig.enabled) {
+                    await this.holdPrimarySummaryRequest(agent, retryDispatch.originalRequestId, 'primary_summary_fallback_disabled_before_retry');
+                    agent.reset();
+                    this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
+                    this.eventGate?.onInferenceEnded(agent.name);
+                    this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), endedAt: Date.now() });
+                    return;
+                }
+                const claim = await this.claimPrimarySummaryRetryIntent(retryDispatch.originalRequestId, retryDispatch.intentId, requestId);
+                if (claim !== 'claimed') {
+                    await this.holdPrimarySummaryRequest(agent, retryDispatch.originalRequestId, claim === 'duplicate'
+                        ? 'primary_summary_fallback_duplicate_retry_blocked'
+                        : 'primary_summary_fallback_retry_intent_missing', { intentId: retryDispatch.intentId, retryRequestId: requestId });
+                    agent.reset();
+                    this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
+                    this.eventGate?.onInferenceEnded(agent.name);
+                    this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), endedAt: Date.now() });
+                    return;
+                }
+                if (!branch ||
+                    branch.id !== retryDispatch.branch.id ||
+                    branch.generation !== retryDispatch.branch.generation) {
+                    await this.holdPrimarySummaryRequest(agent, retryDispatch.originalRequestId, 'primary_summary_fallback_branch_changed_before_retry', {
+                        expectedBranchId: retryDispatch.branch.id,
+                        expectedGeneration: retryDispatch.branch.generation,
+                        actualBranchId: branch?.id,
+                        actualGeneration: branch?.generation,
+                    });
+                    agent.reset();
+                    this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
+                    this.eventGate?.onInferenceEnded(agent.name);
+                    this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), endedAt: Date.now() });
+                    return;
+                }
+                const rebuilt = agent.buildPrimarySummaryRawExpansionRequest(retryDispatch.originalArtifacts, retryDispatch.candidateSummaries, tools);
+                compiledRequest = rebuilt.request;
+                artifacts = rebuilt.artifacts;
+                const rebuiltHash = this.hashJson(compiledRequest);
+                if (rebuiltHash !== retryDispatch.expectedRetryRequestHash ||
+                    this.primarySummaryProjectionKeys(artifacts.compileResult.primarySummaryProjection ?? null).join('\u0000') !==
+                        retryDispatch.originalProjectionKeys.join('\u0000')) {
+                    await this.holdPrimarySummaryRequest(agent, retryDispatch.originalRequestId, 'primary_summary_fallback_revalidation_failed_before_retry', {
+                        expectedRetryRequestHash: retryDispatch.expectedRetryRequestHash,
+                        actualRetryRequestHash: rebuiltHash,
+                    });
+                    agent.reset();
+                    this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
+                    this.eventGate?.onInferenceEnded(agent.name);
+                    this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), endedAt: Date.now() });
+                    return;
+                }
+                const retryRecord = this.buildPrimarySummaryRequestRecord(agent, requestId, 'primary_summary_fallback_retry', compiledRequest, artifacts, branch, undefined, false, 0, undefined, 'pending');
+                await this.persistPrimarySummaryRequestRecord(retryRecord);
+                const admittedTokens = this.primarySummaryAdmissionBoundTokens(retryDispatch.originalRequestInputBoundTokens, compiledRequest, retryDispatch.originalProviderInputTokens);
+                if (admittedTokens > retryDispatch.requestBudgetTokens) {
+                    await this.holdPrimarySummaryRequest(agent, requestId, 'primary_summary_fallback_retry_over_budget', {
+                        admittedTokens,
+                        requestBudgetTokens: retryDispatch.requestBudgetTokens,
+                        retryRequestHash: rebuiltHash,
+                    });
+                    await this.updatePrimarySummaryRequestRecord(retryDispatch.originalRequestId, (record) => ({
+                        ...record,
+                        fallbackStatus: 'held',
+                        fallbackHeldReason: 'primary_summary_fallback_retry_over_budget',
+                    }));
+                    agent.reset();
+                    this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
+                    this.eventGate?.onInferenceEnded(agent.name);
+                    this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), endedAt: Date.now() });
+                    return;
                 }
             }
-            catch (error) {
-                console.error('Module gatherContext error:', error);
-            }
-            // MCPL beforeInference hooks (fail-open)
-            if (this.hookOrchestrator) {
+            else {
+                // Gather context from modules (pull-based) and MCPL hooks (push-based)
+                // Both produce ContextInjection[] that get merged before inference.
+                let injections;
+                // Module gatherContext (fail-open, per-module timeout — the module's
+                // contextTimeoutMs, else the registry default). Injections are
+                // channel-scoped via scopeInjectionsForAgent, matching the MCPL hook
+                // injections below, so conversation forks don't see cross-channel
+                // content.
                 try {
-                    const hookParams = this.buildBeforeInferenceParams(agent, trigger);
-                    const hookInjections = this.scopeInjectionsForAgent(agent.name, await this.hookOrchestrator.beforeInference(hookParams));
-                    if (hookInjections.length > 0) {
-                        injections = injections ? [...injections, ...hookInjections] : hookInjections;
+                    const moduleInjections = this.scopeInjectionsForAgent(agent.name, await this.moduleRegistry.gatherContext(agent.name));
+                    if (moduleInjections.length > 0) {
+                        injections = moduleInjections;
                     }
                 }
                 catch (error) {
-                    console.error('beforeInference hook error:', error);
+                    console.error('Module gatherContext error:', error);
+                }
+                // MCPL beforeInference hooks (fail-open)
+                if (this.hookOrchestrator) {
+                    try {
+                        const hookParams = this.buildBeforeInferenceParams(agent, trigger);
+                        const hookInjections = this.scopeInjectionsForAgent(agent.name, await this.hookOrchestrator.beforeInference(hookParams));
+                        if (hookInjections.length > 0) {
+                            injections = injections ? [...injections, ...hookInjections] : hookInjections;
+                        }
+                    }
+                    catch (error) {
+                        console.error('beforeInference hook error:', error);
+                    }
+                }
+                const prepared = await agent.prepareActivationRequest(tools, injections);
+                compiledRequest = prepared.request;
+                artifacts = prepared.artifacts;
+                branch = agent.getCurrentBranchGeneration();
+                if (fallbackConfig.enabled) {
+                    const record = this.buildPrimarySummaryRequestRecord(agent, requestId, 'primary', compiledRequest, artifacts, branch, undefined, false, 0, undefined, 'pending');
+                    await this.persistPrimarySummaryRequestRecord(record);
+                    const expandedByQuarantine = artifacts.compileResult.primarySummaryProjection?.selectedSummaries.some((selection) => selection.renderedAs === 'raw_expansion') ?? false;
+                    if (expandedByQuarantine) {
+                        const admittedTokens = this.estimateRequestCompleteBoundTokens(compiledRequest);
+                        if (admittedTokens > fallbackConfig.requestBudgetTokens) {
+                            await this.holdPrimarySummaryRequest(agent, requestId, 'primary_summary_quarantine_over_budget', {
+                                admittedTokens,
+                                requestBudgetTokens: fallbackConfig.requestBudgetTokens,
+                            });
+                            agent.reset();
+                            this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
+                            this.eventGate?.onInferenceEnded(agent.name);
+                            this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), endedAt: Date.now() });
+                            return;
+                        }
+                    }
                 }
             }
-            const { stream, request: compiledRequest } = await agent.startStreamWithInjections(tools, injections);
-            const handle = this.driveStream(agent, stream, trigger, attempt, compiledRequest);
+            const { stream } = agent.startStreamFromRequest(compiledRequest, artifacts);
+            this.activeStreamContexts.set(agent.name, {
+                requestId,
+                trigger,
+                compiledRequest,
+                artifacts,
+            });
+            const handle = this.driveStream(agent, stream, requestSnapshot, requestId, trigger, attempt, compiledRequest, artifacts);
             this.activeStreams.set(agent.name, handle);
         }
         catch (error) {
             const err = error instanceof Error ? error : new Error(String(error));
+            if (trigger?.primarySummaryFallbackRetry) {
+                await this.updatePrimarySummaryRequestRecord(requestId, (record) => ({
+                    ...record,
+                    finalStatus: 'held',
+                    fallbackHeldReason: err.message,
+                }));
+                await this.updatePrimarySummaryRequestRecord(trigger.primarySummaryFallbackRetry.originalRequestId, (record) => ({
+                    ...record,
+                    finalStatus: 'held',
+                    fallbackStatus: 'held',
+                    fallbackHeldReason: err.message,
+                }));
+                this.opsAlert('refusal-held', agent.name, err.message, {
+                    data: { requestId, originalRequestId: trigger.primarySummaryFallbackRetry.originalRequestId },
+                });
+                agent.reset();
+                this.settleAgent(agent.name, {
+                    stopReason: 'completed',
+                    speech: '',
+                });
+                this.eventGate?.onInferenceEnded(agent.name);
+                this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), endedAt: Date.now() });
+                return;
+            }
             this.emitTrace({
                 type: 'inference:failed',
                 agentName: agent.name,
@@ -2930,18 +4650,147 @@ export class AgentFramework {
             }
         }
     }
-    async driveStream(agent, stream, trigger, attempt = 0, compiledRequest) {
+    async driveStream(agent, stream, requestSnapshot, requestId, trigger, attempt = 0, compiledRequest, artifacts) {
         const startTime = Date.now();
-        const requestId = `${agent.name}-${startTime}-${Math.random().toString(36).slice(2, 8)}`;
         const myStreamId = agent.streamId;
         let hadToolCalls = false;
+        let executedToolCalls = 0;
+        const primarySummaryConfig = this.primarySummaryFallbackConfig(agent);
+        const primarySummaryRetry = trigger?.primarySummaryFallbackRetry;
+        let primarySummaryQuarantinePersisted = false;
+        const fallbackRetryRequestForLog = primarySummaryRetry && compiledRequest
+            ? this.summarizePrimarySummaryRetryRequest(compiledRequest)
+            : compiledRequest ?? { note: 'streaming request' };
+        // ---- Present-while-acting turn state ---------------------------------
+        // Output locus for the current CONVERSATIONAL ROUND: resolved lazily and
+        // kept stable across tool-only rounds. A channel message injected at a
+        // tool boundary replaces the pin before the next model round, because a
+        // single provider inference can now contain several conversations. The
+        // pin lives in `turnLocusPins` so it survives a context-budget restart. A
+        // null resolution is not pinned.
+        if (trigger?.reason !== 'context_budget_restart' && trigger?.reason !== 'primary-summary-fallback-retry') {
+            this.turnLocusPins.delete(agent.name);
+            this.midTurnRoutingResets.delete(agent.name);
+        }
+        const resolveTurnLocus = () => {
+            let locus = this.turnLocusPins.get(agent.name) ?? null;
+            if (locus === null && this.channelRegistry) {
+                locus = this.channelRegistry.resolveLocus(agent.name);
+                if (locus !== null)
+                    this.turnLocusPins.set(agent.name, locus);
+            }
+            return locus;
+        };
+        // Ordered delivery chain for live-routed prose. Links are enqueued
+        // WITHOUT awaiting in the stream-event loop — an awaited network post
+        // here would stall consumption of the next round's events by
+        // segments × RTT on every prose-bearing round. The 'complete' case
+        // awaits the chain before routing trailing prose, so in-channel ordering
+        // is preserved end-to-end. Each link catches its own error: one failed
+        // post must not silence the rest of the turn.
+        let turnSpeechChain = Promise.resolve();
+        const enqueueSpeech = (text, locus) => {
+            turnSpeechChain = turnSpeechChain
+                .then(async () => {
+                await this.channelRegistry.routeSpeech(agent.name, text, locus);
+            })
+                .catch((err) => console.error('mid-turn speech routing failed:', err));
+        };
+        // Sticky explicit-send suppression: prose after send_message stays quiet
+        // to prevent a redundant "sent it" postscript. Fresh injected input
+        // clears it, because the following prose is a reply to a new message.
+        let turnSilenced = false;
+        // Live routing is only trusted when the membrane provides verbatim
+        // round-scoped blocks (roundContent, native tool mode, membrane ≥0.5.64).
+        // The fallback `preamble` is CUMULATIVE in XML mode (assistant prefill +
+        // all earlier rounds' prose and raw tool/thinking XML) — live-routing it
+        // would repost the transcript and leak thinking every round. When no
+        // round was live-routed, the 'complete' case falls back to the
+        // historical whole-turn routing so fallback-mode prose is still
+        // delivered exactly once, at turn end.
+        let liveProseRouting = false;
         // Typing indicator: show "<agent> is typing…" in the channel she's
         // responding to, for the whole duration of this turn. Started here (paired
         // with the finally below, so it can never leak) and refreshed on a 7s
         // interval by the ChannelRegistry until stopped on any exit path.
-        const typingChannel = this.channelRegistry?.getDefaultPublishChannel();
+        let typingChannel = this.channelRegistry
+            ? trigger?.channelId ?? this.channelRegistry.getDefaultPublishChannel()
+            : null;
         if (typingChannel)
             this.channelRegistry.startTyping(typingChannel);
+        const adoptInjectedRound = () => {
+            if (!this.midTurnRoutingResets.has(agent.name))
+                return;
+            const nextLocus = this.midTurnRoutingResets.get(agent.name) ?? null;
+            this.midTurnRoutingResets.delete(agent.name);
+            // A new human/agent message, not merely a tool result, means any earlier
+            // explicit delivery has completed its conversational job.
+            turnSilenced = false;
+            if (nextLocus) {
+                this.turnLocusPins.set(agent.name, nextLocus);
+                if (typingChannel !== nextLocus) {
+                    if (typingChannel)
+                        this.channelRegistry?.stopTyping(typingChannel);
+                    typingChannel = nextLocus;
+                    this.channelRegistry?.startTyping(nextLocus);
+                }
+            }
+        };
+        const persistPrimarySummaryRetryQuarantine = async () => {
+            if (!primarySummaryRetry || primarySummaryQuarantinePersisted || !artifacts)
+                return true;
+            const validation = await this.validatePrimarySummaryRetryMutation(agent, requestId, primarySummaryRetry, compiledRequest, artifacts, 'before_quarantine');
+            if (!validation.ok) {
+                await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, validation.reason, validation.data, { emitChronicleMarker: false });
+                stream.cancel();
+                agent.reset();
+                this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
+                return false;
+            }
+            try {
+                const quarantinePrimarySummaryForPrimaryLane = agent.getContextManager().quarantinePrimarySummaryForPrimaryLane;
+                if (typeof quarantinePrimarySummaryForPrimaryLane !== 'function') {
+                    throw new Error('Primary summary quarantine is unavailable in the active context strategy');
+                }
+                await quarantinePrimarySummaryForPrimaryLane.call(agent.getContextManager(), artifacts.contract, primarySummaryRetry.candidateSummaries);
+                primarySummaryQuarantinePersisted = true;
+                await this.recordPrimarySummaryRetryQuarantine(primarySummaryRetry.originalRequestId, primarySummaryRetry.intentId);
+                return true;
+            }
+            catch (error) {
+                const reason = 'primary_summary_fallback_quarantine_failed';
+                await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, reason, {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                stream.cancel();
+                agent.reset();
+                this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
+                return false;
+            }
+        };
+        const persistPrimarySummaryRetryOutput = async (phase, blocks, participant = agent.name, metadata) => {
+            if (!primarySummaryRetry || !artifacts)
+                return true;
+            if (blocks.length === 0)
+                return true;
+            const validation = await this.validatePrimarySummaryRetryMutation(agent, requestId, primarySummaryRetry, compiledRequest, artifacts, `before_${phase}`);
+            if (!validation.ok) {
+                await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, validation.reason, validation.data, { emitChronicleMarker: false });
+                stream.cancel();
+                agent.reset();
+                this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
+                return false;
+            }
+            const messageId = agent.getContextManager().addMessage(participant, blocks, metadata);
+            await this.recordPrimarySummaryRetryOutput(primarySummaryRetry.originalRequestId, primarySummaryRetry.intentId, {
+                phase,
+                contentHash: this.primarySummaryFallbackOutputPhaseHash(blocks),
+                messageId,
+                blockTypes: this.primarySummaryFallbackBlockTypes(blocks),
+                persistedAt: Date.now(),
+            });
+            return true;
+        };
         try {
             for await (const event of stream) {
                 this.touchEphemeralRun(agent.name, true);
@@ -2967,8 +4816,8 @@ export class AgentFramework {
                         break;
                     }
                     case 'tool-calls': {
+                        adoptInjectedRound();
                         hadToolCalls = true;
-                        this.recordEphemeralToolCalls(agent.name, event.calls.length);
                         this.emitTrace({
                             type: 'inference:tool_calls_yielded',
                             agentName: agent.name,
@@ -3002,13 +4851,75 @@ export class AgentFramework {
                         // Truncated responses yield 'complete' with stop_reason 'max_tokens' directly.
                         // So all calls here have valid input — {} is legitimate for parameterless tools.
                         agent.enterWaitingForTools(event.calls, stream);
+                        if (!(await persistPrimarySummaryRetryQuarantine())) {
+                            return;
+                        }
+                        if (primarySummaryRetry) {
+                            const phase = `tool_round_${event.context.depth ?? 0}`;
+                            if (!(await persistPrimarySummaryRetryOutput(phase, assistantBlocks))) {
+                                return;
+                            }
+                            this.pendingAssistantBlocks.delete(agent.name);
+                        }
+                        executedToolCalls += event.calls.length;
+                        this.recordEphemeralToolCalls(agent.name, event.calls.length);
                         for (const call of event.calls) {
+                            if (primarySummaryRetry) {
+                                const validation = await this.validatePrimarySummaryRetryMutation(agent, requestId, primarySummaryRetry, compiledRequest, artifacts, `before_tool_dispatch_${call.id}`);
+                                if (!validation.ok) {
+                                    await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, validation.reason, validation.data, { emitChronicleMarker: false });
+                                    stream.cancel();
+                                    agent.reset();
+                                    this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
+                                    return;
+                                }
+                                await this.recordPrimarySummaryRetryToolDispatch(primarySummaryRetry.originalRequestId, primarySummaryRetry.intentId, call);
+                            }
                             this.dispatchToolCall(agent.name, call);
                         }
+                        // Speak-while-acting: route THIS round's prose to the locus NOW
+                        // instead of batching every segment to the end of the turn. Long
+                        // tool-using turns (robot control, live sessions) otherwise dump
+                        // the whole narration in one blob when the turn finally settles —
+                        // and, worse, make "talking" and "acting" feel mutually exclusive
+                        // to the agent. Mid-turn prose is speech (delivered live, in
+                        // order, via the turn's speech chain — never awaited here); the
+                        // `think` tool remains the private channel. Silencing is STICKY
+                        // from the round it occurs (see SILENCING_TOOLS). Only rounds
+                        // with verbatim roundContent are live-routed (see liveProseRouting
+                        // note above — the fallback preamble is cumulative in XML mode).
+                        if (this.channelRegistry) {
+                            const roundToolNames = event.calls.map((c) => c.name);
+                            const hasSameRoundPrivateThink = roundToolNames.includes('think') &&
+                                requestSnapshot.sameRoundThinkTextPolicy === 'private';
+                            if (roundToolNames.some((n) => SILENCING_TOOLS.has(bareToolName(n)))) {
+                                turnSilenced = true;
+                            }
+                            if (roundContent && roundContent.length > 0) {
+                                liveProseRouting = true;
+                                const roundSegments = splitProseSegments(assistantBlocks);
+                                if (roundSegments.length > 0) {
+                                    if (turnSilenced) {
+                                        console.error(`[routing] ${agent.name}: mid-turn round [${roundToolNames.join(', ')}] -> prose NOT routed (turn silenced)`);
+                                    }
+                                    else if (hasSameRoundPrivateThink) {
+                                        console.error(`[routing] ${agent.name}: mid-turn round [${roundToolNames.join(', ')}] -> prose NOT routed (same_round_think_text_policy=private)`);
+                                    }
+                                    else {
+                                        const locus = resolveTurnLocus();
+                                        console.error(`[routing] ${agent.name}: mid-turn round [${roundToolNames.join(', ')}] -> routing ${roundSegments.length} prose segment(s) live -> ${locus ?? '(default)'}`);
+                                        for (const seg of roundSegments) {
+                                            enqueueSpeech(seg, locus);
+                                        }
+                                    }
+                                }
+                            }
+                        }
                         // Stream's async iterator blocks on next() until provideToolResults() is called
                         break;
                     }
                     case 'complete': {
+                        adoptInjectedRound();
                         const durationMs = Date.now() - startTime;
                         const response = event.response;
                         // If the agent is still waiting_for_tools when 'complete' fires
@@ -3045,6 +4956,167 @@ export class AgentFramework {
                                 agent.getContextManager().addMessage('user', toolResultContent);
                             }
                         }
+                        const lastToolIdx = response.content.reduce((last, b, i) => b.type === 'tool_use' || b.type === 'tool_result' ? i : last, -1);
+                        const terminalContent = lastToolIdx >= 0
+                            ? response.content.slice(lastToolIdx + 1)
+                            : response.content;
+                        const heldAssistantContent = response.content;
+                        const visibleAssistantOutput = this.hasVisibleAssistantOutput(response.content);
+                        const providerInputTokens = response.usage?.inputTokens ??
+                            response.details?.usage?.inputTokens;
+                        if (primarySummaryConfig.enabled && compiledRequest && artifacts && response.stopReason === 'refusal') {
+                            const stopDetails = response.raw?.response?.stop_details;
+                            const category = stopDetails?.category ?? 'unknown';
+                            console.error(`[inference-refusal] agent=${agent.name} category=${category}` +
+                                (stopDetails?.explanation ? ` explanation=${stopDetails.explanation}` : ''));
+                            this.noteRefusal(agent.name, category, response.details?.usage
+                                ? {
+                                    input: response.details.usage.inputTokens,
+                                    output: response.details.usage.outputTokens,
+                                }
+                                : undefined);
+                            const currentRecord = await this.updatePrimarySummaryRequestRecord(requestId, (record) => ({
+                                ...record,
+                                stopReason: response.stopReason,
+                                providerInputTokens,
+                                visibleAssistantOutput,
+                                executedToolCalls,
+                                finalStatus: 'refusal',
+                            }));
+                            const holdReasonData = {
+                                category,
+                                visibleAssistantOutput,
+                                executedToolCalls,
+                                candidateLimit: primarySummaryConfig.maxNewSummaries,
+                            };
+                            if (primarySummaryRetry) {
+                                const reason = visibleAssistantOutput
+                                    ? 'primary_summary_fallback_retry_partial_output'
+                                    : executedToolCalls > 0
+                                        ? 'primary_summary_fallback_retry_tool_already_executed'
+                                        : 'primary_summary_fallback_retry_refusal';
+                                if (visibleAssistantOutput || executedToolCalls > 0) {
+                                    await this.persistPrimarySummaryHeldOutput(agent, requestId, reason, {
+                                        stopReason: response.stopReason,
+                                        providerInputTokens,
+                                        visibleAssistantOutput,
+                                        executedToolCalls,
+                                        assistantBlocks: heldAssistantContent,
+                                        retryDispatch: primarySummaryRetry,
+                                        retryPhase: 'refusal_visible_output',
+                                        holdData: holdReasonData,
+                                    });
+                                }
+                                else {
+                                    await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, reason, holdReasonData);
+                                }
+                            }
+                            else if (visibleAssistantOutput || executedToolCalls > 0 || !currentRecord?.projection) {
+                                const reason = visibleAssistantOutput
+                                    ? 'primary_summary_refusal_partial_output'
+                                    : executedToolCalls > 0
+                                        ? 'primary_summary_refusal_tool_already_executed'
+                                        : 'primary_summary_refusal_no_projection';
+                                if (visibleAssistantOutput || executedToolCalls > 0) {
+                                    await this.persistPrimarySummaryHeldOutput(agent, requestId, reason, {
+                                        stopReason: response.stopReason,
+                                        providerInputTokens,
+                                        visibleAssistantOutput,
+                                        executedToolCalls,
+                                        assistantBlocks: heldAssistantContent,
+                                        holdData: holdReasonData,
+                                    });
+                                }
+                                else {
+                                    await this.holdPrimarySummaryRequest(agent, requestId, reason, holdReasonData);
+                                }
+                            }
+                            else {
+                                const state = this.readPrimarySummaryFallbackState();
+                                const baseline = this.latestCompatibleHealthyPrimaryRequest(currentRecord, state);
+                                if (!baseline?.projection) {
+                                    await this.holdPrimarySummaryRequest(agent, requestId, 'primary_summary_refusal_no_compatible_healthy_baseline', holdReasonData);
+                                }
+                                else {
+                                    const baselineKeys = new Set(this.primarySummaryProjectionKeys(baseline.projection));
+                                    const candidates = currentRecord.projection.selectedSummaries
+                                        .filter((selection) => !baselineKeys.has(this.primarySummaryIdentityKey(selection.identity)))
+                                        .map((selection) => selection.identity);
+                                    if (candidates.length === 0) {
+                                        await this.holdPrimarySummaryRequest(agent, requestId, 'primary_summary_refusal_no_newly_admitted_candidates', holdReasonData);
+                                    }
+                                    else if (candidates.length > primarySummaryConfig.maxNewSummaries) {
+                                        await this.holdPrimarySummaryRequest(agent, requestId, 'primary_summary_refusal_too_many_candidates', { ...holdReasonData, candidateCount: candidates.length });
+                                    }
+                                    else {
+                                        try {
+                                            const retry = agent.buildPrimarySummaryRawExpansionRequest(artifacts, candidates, compiledRequest.tools ?? []);
+                                            const retryRequestHash = this.hashJson(retry.request);
+                                            const admittedTokens = this.primarySummaryAdmissionBoundTokens(currentRecord.requestInputBoundTokens, retry.request, providerInputTokens);
+                                            if (admittedTokens > primarySummaryConfig.requestBudgetTokens) {
+                                                await this.holdPrimarySummaryRequest(agent, requestId, 'primary_summary_refusal_retry_over_budget', {
+                                                    ...holdReasonData,
+                                                    admittedTokens,
+                                                    requestBudgetTokens: primarySummaryConfig.requestBudgetTokens,
+                                                });
+                                            }
+                                            else {
+                                                const intentId = `${requestId}:fallback:${Math.random().toString(36).slice(2, 8)}`;
+                                                await this.updatePrimarySummaryRequestRecord(requestId, (record) => ({
+                                                    ...record,
+                                                    fallbackIntent: {
+                                                        intentId,
+                                                        createdAt: Date.now(),
+                                                        baselineRequestId: baseline.requestId,
+                                                        candidateSummaries: candidates,
+                                                        retryRequestHash,
+                                                        retryCompleteBoundTokens: admittedTokens,
+                                                        requestBudgetTokens: primarySummaryConfig.requestBudgetTokens,
+                                                    },
+                                                    fallbackStatus: 'pending',
+                                                }));
+                                                this.pendingRequests.push({
+                                                    agentName: agent.name,
+                                                    reason: 'primary-summary-fallback-retry',
+                                                    source: 'framework',
+                                                    timestamp: Date.now(),
+                                                    channelId: trigger?.channelId,
+                                                    primarySummaryFallbackRetry: {
+                                                        originalRequestId: requestId,
+                                                        baselineRequestId: baseline.requestId,
+                                                        intentId,
+                                                        branch: {
+                                                            id: currentRecord.branch.id,
+                                                            generation: currentRecord.branch.generation,
+                                                        },
+                                                        candidateSummaries: candidates,
+                                                        originalArtifacts: artifacts,
+                                                        originalProjectionKeys: this.primarySummaryProjectionKeys(currentRecord.projection),
+                                                        expectedRetryRequestHash: retryRequestHash,
+                                                        requestBudgetTokens: primarySummaryConfig.requestBudgetTokens,
+                                                        originalRequestInputBoundTokens: currentRecord.requestInputBoundTokens,
+                                                        originalProviderInputTokens: providerInputTokens,
+                                                    },
+                                                });
+                                            }
+                                        }
+                                        catch (error) {
+                                            await this.holdPrimarySummaryRequest(agent, requestId, 'primary_summary_refusal_retry_build_failed', {
+                                                ...holdReasonData,
+                                                error: error instanceof Error ? error.message : String(error),
+                                            });
+                                        }
+                                    }
+                                }
+                            }
+                            agent.reset();
+                            this.eventGate?.onInferenceEnded(agent.name);
+                            this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
+                            continue;
+                        }
+                        if (!(await persistPrimarySummaryRetryQuarantine())) {
+                            return;
+                        }
                         // Add assistant response to context.
                         // If we had tool calls, each round's blocks (thinking + text +
                         // tool_use) were already stored as pendingAssistantBlocks and
@@ -3053,17 +5125,55 @@ export class AgentFramework {
                         // double-store earlier rounds' text/thinking AND detach signed
                         // thinking blocks from their tool_use turn (the API requires
                         // thinking to precede tool_use in the same assistant turn).
-                        const lastToolIdx = response.content.reduce((last, b, i) => b.type === 'tool_use' || b.type === 'tool_result' ? i : last, -1);
-                        const terminalContent = lastToolIdx >= 0
-                            ? response.content.slice(lastToolIdx + 1)
-                            : response.content;
                         if (lastToolIdx >= 0) {
                             if (terminalContent.length > 0) {
-                                agent.addAssistantResponse(terminalContent);
+                                if (primarySummaryRetry) {
+                                    const retryRecord = await this.getPrimarySummaryRequestRecord(requestId);
+                                    const terminalMetadata = retryRecord
+                                        ? this.buildPrimarySummarySettlementMetadata(retryRecord, {
+                                            outcome: 'success',
+                                            stopReason: response.stopReason,
+                                            providerInputTokens,
+                                            visibleAssistantOutput,
+                                            executedToolCalls,
+                                            entryIndex: 0,
+                                            entryCount: 1,
+                                            role: 'assistant',
+                                            kind: 'assistant_output',
+                                        })
+                                        : undefined;
+                                    if (!(await persistPrimarySummaryRetryOutput('terminal', terminalContent, agent.name, terminalMetadata))) {
+                                        return;
+                                    }
+                                }
+                                else {
+                                    agent.addAssistantResponse(terminalContent);
+                                }
                             }
                         }
                         else {
-                            agent.addAssistantResponse(terminalContent);
+                            if (primarySummaryRetry) {
+                                const retryRecord = await this.getPrimarySummaryRequestRecord(requestId);
+                                const terminalMetadata = retryRecord && terminalContent.length > 0
+                                    ? this.buildPrimarySummarySettlementMetadata(retryRecord, {
+                                        outcome: 'success',
+                                        stopReason: response.stopReason,
+                                        providerInputTokens,
+                                        visibleAssistantOutput,
+                                        executedToolCalls,
+                                        entryIndex: 0,
+                                        entryCount: 1,
+                                        role: 'assistant',
+                                        kind: 'assistant_output',
+                                    })
+                                    : undefined;
+                                if (!(await persistPrimarySummaryRetryOutput('terminal', terminalContent, agent.name, terminalMetadata))) {
+                                    return;
+                                }
+                            }
+                            else {
+                                agent.addAssistantResponse(terminalContent);
+                            }
                         }
                         // Run afterInference hooks (no-op if no MCPL servers)
                         if (this.hookOrchestrator) {
@@ -3098,10 +5208,13 @@ export class AgentFramework {
                                 console.error('afterInference hook error:', error);
                             }
                         }
-                        // Separate speech from thoughts.
-                        // When tools were used, ALL text is thoughts (the tools themselves are
-                        // the agent's actions — surrounding text is just reasoning).
-                        // When no tools were used, all text is speech.
+                        // Separate speech from thoughts — for MODULE dispatch only
+                        // (dispatchSpeech / TUI rendering below). This split does NOT
+                        // decide what reaches the channel: mid-turn prose is routed live
+                        // per round (see the 'tool-calls' case) and trailing prose is
+                        // routed after this block. On a tool-using turn the module-level
+                        // convention remains "text is thoughts"; on a text-only turn all
+                        // text is speech.
                         const isTextBlock = (block) => block.type === 'text';
                         const allText = response.content.filter(isTextBlock);
                         const speechContent = hadToolCalls ? [] : allText;
@@ -3115,6 +5228,28 @@ export class AgentFramework {
                                 cacheRead: du.cacheReadTokens,
                             }
                             : undefined;
+                        if (primarySummaryRetry && artifacts) {
+                            const validation = await this.validatePrimarySummaryRetryMutation(agent, requestId, primarySummaryRetry, compiledRequest, artifacts, 'before_success_markers');
+                            if (!validation.ok) {
+                                await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, validation.reason, validation.data, { emitChronicleMarker: false });
+                                return;
+                            }
+                        }
+                        if (primarySummaryConfig.enabled) {
+                            if (primarySummaryRetry) {
+                                await this.markPrimarySummaryRetrySuccess(requestId, primarySummaryRetry, response.stopReason, providerInputTokens, visibleAssistantOutput, executedToolCalls);
+                            }
+                            else {
+                                await this.updatePrimarySummaryRequestRecord(requestId, (record) => ({
+                                    ...record,
+                                    stopReason: response.stopReason,
+                                    providerInputTokens,
+                                    visibleAssistantOutput,
+                                    executedToolCalls,
+                                    finalStatus: 'success',
+                                }));
+                            }
+                        }
                         // Reset agent state before emitting inference:completed. Traces are
                         // observability-only, but external synchronous listeners should
                         // still see the terminal state at the terminal trace boundary.
@@ -3150,8 +5285,10 @@ export class AgentFramework {
                             agentName: agent.name,
                             requestId,
                             success: true,
-                            request: compiledRequest ?? { note: 'streaming request' },
-                            response: response.raw ?? { note: 'streaming response' },
+                            request: fallbackRetryRequestForLog,
+                            response: primarySummaryRetry
+                                ? this.summarizePrimarySummaryRetryResponse(response)
+                                : response.raw ?? { note: 'streaming response' },
                             durationMs,
                             tokenUsage,
                             stopReason: response.stopReason,
@@ -3273,65 +5410,50 @@ export class AgentFramework {
                             }
                         }
                         else if (this.channelRegistry && hadToolCalls && allText.length > 0) {
-                            // Tool-call turn that also produced prose. Per design, route the
-                            // prose to the locus as a reply UNLESS the turn used an explicit
-                            // send/publish tool (channel_publish, *--send_message,
-                            // *--reply_message, *--send_dm) — already delivered, so routing
-                            // again would double-post. `think` and other non-sending tools
-                            // (shell, workspace, etc.) still let the agent speak in the same
-                            // turn. The global speech/thoughts split is left untouched
-                            // (module/TUI rendering unaffected) — this only governs what
-                            // reaches the channel.
-                            // Tools whose presence suppresses the trailing prose, for two
-                            // distinct reasons:
-                            //   - `skip_reply` — the agent EXPLICITLY chose not to reply this
-                            //     turn (the deliberate "stay silent" signal).
-                            //   - explicit delivery tools (channel_publish / *send_message /
-                            //     *reply_message / *send_dm) — already sent the message, so
-                            //     routing it again would double-post.
-                            // `think` is deliberately NOT here: it is silent *reasoning*, but
-                            // prose written after a think is the agent's actual reply and must
-                            // be delivered. (A think-only turn has no trailing prose and stays
-                            // silent via the `!t` check below.)
-                            const SILENCING = new Set([
-                                'skip_reply', 'channel_publish', 'send_message', 'reply_message', 'send_dm',
-                            ]);
-                            const bare = (n) => (n.includes('--') ? n.split('--').pop() : n);
+                            // Tool-call turn that also produced prose. When live routing was
+                            // active (native roundContent), each mid-turn round's prose was
+                            // already delivered when that round yielded — only the TRAILING
+                            // prose (blocks after the last tool round) remains here. On the
+                            // fallback path (XML tool mode / older membrane: no roundContent,
+                            // so nothing was live-routed) the historical behavior applies:
+                            // route the whole turn's parsed segments, once, now. The global
+                            // speech/thoughts split is left untouched (module/TUI rendering
+                            // unaffected) — this only governs what reaches the channel.
+                            //
+                            // Native round routing uses the live sticky flag, which a fresh
+                            // injected message can reset. The legacy/fallback path has no
+                            // reliable round boundaries, so retain its historical turn-wide
+                            // scan to avoid double-posting.
                             const toolNames = response.content
                                 .filter((b) => b.type === 'tool_use')
                                 .map((b) => b.name)
                                 .filter((n) => typeof n === 'string');
-                            const silenced = toolNames.some((n) => SILENCING.has(bare(n)));
-                            // Split the turn's content into ordered prose segments, broken at
-                            // each tool_use / tool_result boundary. `response.content` holds the
-                            // WHOLE turn's blocks in provider order — earlier tool rounds
-                            // included (see the trailing-slice note above, which slices exactly
-                            // because the full turn is present) — so a left-to-right walk
-                            // reconstructs the emission order. Interleaved prose
-                            // ("msgA → [tool] → msgB → [tool] → msgC") is then delivered as
-                            // separate messages IN ORDER instead of being collapsed into one
-                            // trailing post (item 4). The silencing rule stays turn-wide: an
-                            // explicit send / skip suppresses ALL auto-routed prose this turn,
-                            // preserving the double-post guard.
-                            const segments = splitProseSegments(response.content);
+                            const silenced = liveProseRouting
+                                ? turnSilenced
+                                : turnSilenced || toolNames.some((n) => SILENCING_TOOLS.has(bareToolName(n)));
+                            const segments = splitProseSegments(liveProseRouting ? terminalContent : response.content);
+                            // Preserve in-channel ordering: everything enqueued live must
+                            // land before the trailing prose. Awaited even when silenced —
+                            // the chain may still be flushing earlier rounds' posts.
+                            await turnSpeechChain;
                             if (silenced || segments.length === 0) {
-                                console.error(`[routing] ${agent.name}: tool-call turn [${toolNames.join(', ') || 'none'}] -> NOT routed ` +
-                                    `(${silenced ? 'silencing tool / explicit send' : 'no prose'})`);
+                                console.error(`[routing] ${agent.name}: tool-call turn [${toolNames.join(', ') || 'none'}] -> trailing prose NOT routed ` +
+                                    `(${silenced ? 'silencing tool / explicit send' : 'no trailing prose'})`);
                             }
                             else {
-                                // Snapshot the locus ONCE. This loop dispatches AFTER the agent
-                                // is idle (see PR #32 note below), so a queued inbound from
-                                // another channel can start a NEW turn and overwrite the per-agent
-                                // triggering channel (`activeTriggerChannels`) BETWEEN segments —
-                                // splitting one turn's reply across channels (the residual
-                                // multi-segment race left by 83dedf8's per-agent locus). Pin every
-                                // segment of THIS turn to the channel resolved right now.
-                                const turnLocus = this.channelRegistry.resolveLocus(agent.name);
-                                console.error(`[routing] ${agent.name}: tool-call turn [${toolNames.join(', ')}] -> routing ${segments.length} prose segment(s) in order -> ${turnLocus ?? '(default)'}`);
+                                // Reuse the locus pinned at the turn's first live-routed
+                                // segment (or resolve it now for a turn whose only prose is
+                                // trailing). This dispatch runs AFTER the agent is idle (see
+                                // PR #32 note below), so a queued inbound from another channel
+                                // could otherwise overwrite the per-agent triggering channel
+                                // between segments — and a turn that narrated live into one
+                                // channel must not land its postscript in another.
+                                const locus = resolveTurnLocus();
+                                console.error(`[routing] ${agent.name}: tool-call turn [${toolNames.join(', ')}] -> routing ${segments.length} ${liveProseRouting ? 'trailing ' : ''}prose segment(s) -> ${locus ?? '(default)'}`);
                                 // Deliver sequentially (await each) so the segments land in order.
                                 for (const seg of segments) {
                                     try {
-                                        await this.channelRegistry.routeSpeech(agent.name, seg, turnLocus);
+                                        await this.channelRegistry.routeSpeech(agent.name, seg, locus);
                                     }
                                     catch (err) {
                                         console.error('speech routing failed:', err);
@@ -3359,12 +5481,22 @@ export class AgentFramework {
                             requestId,
                             success: false,
                             error: err.message,
-                            request: compiledRequest ?? { note: 'streaming request failed' },
+                            request: fallbackRetryRequestForLog,
                             durationMs,
                         });
                         // Only reset + retry if this is still the active stream
                         if (agent.streamId !== myStreamId)
                             break;
+                        if (primarySummaryRetry) {
+                            await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, 'primary_summary_fallback_retry_stream_error', { error: err.message });
+                            agent.reset();
+                            this.eventGate?.onInferenceEnded(agent.name);
+                            this.settleAgent(agent.name, {
+                                stopReason: 'completed',
+                                speech: '',
+                            });
+                            return;
+                        }
                         agent.reset();
                         const action = this.errorPolicy.onInferenceError(err, agent.name, attempt);
                         if (action.retry) {
@@ -3403,6 +5535,11 @@ export class AgentFramework {
                         // reject an ephemeral's promise mid-run and bump the failure
                         // streak). Gate release + stream teardown happen in `finally`.
                         if (this.frameworkCancelledStreams.delete(`${agent.name}:${myStreamId}`)) {
+                            if (primarySummaryRetry) {
+                                if (!(await this.primarySummaryRetryFamilyAlreadySettled(requestId, primarySummaryRetry))) {
+                                    await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, 'primary_summary_fallback_retry_cancelled_before_success', { frameworkCancelled: true });
+                                }
+                            }
                             this.eventGate?.onInferenceEnded(agent.name);
                             return;
                         }
@@ -3411,6 +5548,33 @@ export class AgentFramework {
                         // may have already started a new stream, bumping streamId)
                         if (agent.streamId === myStreamId) {
                             const durationMs = Date.now() - startTime;
+                            if (primarySummaryRetry) {
+                                await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, `stream_aborted:${reason}`, { reason }, { stopReason: 'abort' });
+                                agent.reset();
+                                this.eventGate?.onInferenceEnded(agent.name);
+                                this.logInference({
+                                    timestamp: startTime,
+                                    agentName: agent.name,
+                                    requestId,
+                                    success: false,
+                                    error: `Stream aborted: ${reason}`,
+                                    request: fallbackRetryRequestForLog,
+                                    durationMs,
+                                });
+                                this.settleAgent(agent.name, {
+                                    stopReason: 'completed',
+                                    speech: '',
+                                });
+                                return;
+                            }
+                            if (primarySummaryConfig.enabled) {
+                                await this.updatePrimarySummaryRequestRecord(requestId, (record) => ({
+                                    ...record,
+                                    stopReason: 'abort',
+                                    finalStatus: 'error',
+                                    fallbackHeldReason: `stream_aborted:${reason}`,
+                                }));
+                            }
                             agent.reset();
                             this.settleAgent(agent.name, {
                                 stopReason: 'exhausted',
@@ -3434,7 +5598,7 @@ export class AgentFramework {
                                 requestId,
                                 success: false,
                                 error: `Stream aborted: ${reason}`,
-                                request: compiledRequest ?? { note: 'streaming request aborted' },
+                                request: fallbackRetryRequestForLog,
                                 durationMs,
                             });
                             this.eventGate?.onInferenceEnded(agent.name);
@@ -3480,12 +5644,58 @@ export class AgentFramework {
             // inference:exhausted so ephemeral agent promises can settle.
             const err = error instanceof Error ? error : new Error(String(error));
             const durationMs = Date.now() - startTime;
+            if (primarySummaryRetry) {
+                if (await this.primarySummaryRetryAlreadySucceeded(requestId, primarySummaryRetry)) {
+                    this.logInference({
+                        timestamp: startTime,
+                        agentName: agent.name,
+                        requestId,
+                        success: true,
+                        request: fallbackRetryRequestForLog,
+                        response: { kind: 'primary_summary_fallback_retry', postSuccessError: err.message },
+                        durationMs,
+                    });
+                    agent.reset();
+                    this.eventGate?.onInferenceEnded(agent.name);
+                    this.settleAgent(agent.name, {
+                        stopReason: 'completed',
+                        speech: '',
+                    });
+                    return;
+                }
+                await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, 'primary_summary_fallback_retry_stream_threw', { error: err.message });
+            }
+            else if (primarySummaryConfig.enabled) {
+                await this.updatePrimarySummaryRequestRecord(requestId, (record) => ({
+                    ...record,
+                    finalStatus: 'error',
+                    fallbackHeldReason: err.message,
+                }));
+            }
             this.emitTrace({
                 type: 'inference:failed',
                 agentName: agent.name,
                 error: err.message,
                 stack: err.stack,
             });
+            if (primarySummaryRetry) {
+                this.logInference({
+                    timestamp: startTime,
+                    agentName: agent.name,
+                    requestId,
+                    success: false,
+                    error: `Stream threw: ${err.message}`,
+                    request: fallbackRetryRequestForLog,
+                    durationMs,
+                });
+                agent.reset();
+                this.eventGate?.onInferenceEnded(agent.name);
+                this.settleAgent(agent.name, {
+                    stopReason: 'completed',
+                    speech: '',
+                });
+                return;
+            }
             this.settleAgent(agent.name, {
                 stopReason: 'exhausted',
                 speech: '',
@@ -3506,7 +5716,7 @@ export class AgentFramework {
                 requestId,
                 success: false,
                 error: `Stream threw: ${err.message}`,
-                request: compiledRequest ?? { note: 'streaming request threw' },
+                request: fallbackRetryRequestForLog,
                 durationMs,
             });
             agent.reset();
@@ -3527,6 +5737,7 @@ export class AgentFramework {
             this.channelRegistry?.stopTyping();
             this.frameworkCancelledStreams.delete(`${agent.name}:${myStreamId}`);
             this.activeStreams.delete(agent.name);
+            this.activeStreamContexts.delete(agent.name);
             this.pendingAssistantBlocks.delete(agent.name);
             // A conversation fork whose TTL closure turn just finished is done for
             // good — dispose it so the agent map doesn't grow monotonically.
@@ -3661,6 +5872,49 @@ export class AgentFramework {
             return maxTokens * 4;
         return undefined;
     }
+    approximateDecodedBase64Bytes(base64) {
+        const padding = base64.endsWith('==') ? 2 : base64.endsWith('=') ? 1 : 0;
+        return Math.max(0, Math.floor(base64.length * 3 / 4) - padding);
+    }
+    sanitizeProcessLogValue(value, seen = new WeakMap()) {
+        if (value && typeof value === 'object') {
+            const seenValue = seen.get(value);
+            if (seenValue)
+                return seenValue;
+        }
+        if (Array.isArray(value)) {
+            const clone = [];
+            seen.set(value, clone);
+            for (const item of value) {
+                clone.push(this.sanitizeProcessLogValue(item, seen));
+            }
+            return clone;
+        }
+        if (!value || typeof value !== 'object') {
+            return value;
+        }
+        const record = value;
+        if (record.type === 'image' && typeof record.data === 'string' && typeof record.mimeType === 'string') {
+            const clone = {};
+            seen.set(value, clone);
+            for (const [key, child] of Object.entries(record)) {
+                if (key === 'data' || key === 'mimeType')
+                    continue;
+                clone[key] = this.sanitizeProcessLogValue(child, seen);
+            }
+            clone.type = 'image';
+            clone.mimeType = record.mimeType;
+            clone.approxByteLength = this.approximateDecodedBase64Bytes(record.data);
+            clone.redacted = true;
+            return clone;
+        }
+        const clone = {};
+        seen.set(value, clone);
+        for (const [key, child] of Object.entries(record)) {
+            clone[key] = this.sanitizeProcessLogValue(child, seen);
+        }
+        return clone;
+    }
     logInference(entry) {
         // Store large request/response as blobs
         const entryToStore = { ...entry };
@@ -3689,13 +5943,13 @@ export class AgentFramework {
     logProcessEvent(event, responses) {
         const entry = {
             timestamp: Date.now(),
-            processEvent: event,
-            responses,
+            processEvent: this.sanitizeProcessLogValue(event),
+            responses: this.sanitizeProcessLogValue(responses),
         };
         // Blob threshold: 10KB
         const BLOB_THRESHOLD = 10000;
         const entryToStore = { ...entry };
-        const responsesJson = JSON.stringify(responses);
+        const responsesJson = JSON.stringify(entry.responses);
         if (responsesJson.length > BLOB_THRESHOLD) {
             const blobId = this.store.storeBlob(Buffer.from(responsesJson), 'application/json');
             entryToStore.responses = { blobId };
@@ -3729,6 +5983,15 @@ export class AgentFramework {
             this.dispatchChannelToolCall(agentName, enrichedCall);
             return;
         }
+        // Route the agent's typed, allowlisted hot-settings surface.
+        if (enrichedCall.name === 'agent_settings') {
+            this.dispatchAgentSettingsToolCall(agentName, enrichedCall);
+            return;
+        }
+        if (enrichedCall.name === 'save_recent_image') {
+            this.dispatchSaveImageToolCall(agentName, enrichedCall);
+            return;
+        }
         // Route gate_status tool
         if (enrichedCall.name === 'gate_status' && this.eventGate) {
             this.dispatchGateToolCall(agentName, enrichedCall);
@@ -3829,12 +6092,19 @@ export class AgentFramework {
         if (!agent) {
             throw new Error('No agents configured');
         }
-        // If any agent has pending assistant blocks (tool_use not yet flushed),
-        // defer non-tool_result messages to preserve tool_use → tool_result adjacency.
+        // Defer non-tool_result messages while a tool cycle is mid-flight
+        // (pendingAssistantBlocks: preserves tool_use → tool_result adjacency)
+        // OR while the target agent has a live stream at all. A message stored
+        // mid-stream lands BEFORE the turn's assistant blocks in the window even
+        // though the live conversation never saw it — so the next compile
+        // diverges from the live prefix (prompt-cache bust) and the message
+        // misses mid-turn injection. Deferred messages flush at the agent's next
+        // tool boundary (where they are ALSO injected into the live stream —
+        // hear-while-acting) or in driveStream's finally when the turn ends.
         const hasToolResult = content.some(b => b.type === 'tool_result');
-        if (!hasToolResult && this.pendingAssistantBlocks.size > 0) {
+        if (!hasToolResult && (this.pendingAssistantBlocks.size > 0 || this.activeStreams.has(agent.name))) {
             this.deferredMessages.push({ participant, content, metadata });
-            return ''; // Deferred — will be added after tool_result flush
+            return ''; // Deferred — flushed at the next boundary
         }
         return agent.getContextManager().addMessage(participant, content, metadata);
     }
@@ -3954,12 +6224,22 @@ export class AgentFramework {
      * work, per-agent status + last inference activity. Cheap and read-only.
      */
     healthSnapshot() {
+        const primarySummary = this.readPrimarySummaryFallbackState();
         return {
             at: new Date().toISOString(),
             uptimeSec: Math.round(process.uptime()),
             gate: this.eventGate?.inferenceDiagnostics() ?? null,
             pendingRequests: this.pendingRequests.length,
             activeStreams: [...this.activeStreams.keys()],
+            primarySummaryFallback: {
+                requests: primarySummary.requests.length,
+                pendingDispatches: primarySummary.requests.filter((record) => record.finalStatus === 'pending').length,
+                unresolvedIntents: primarySummary.requests.filter((record) => record.fallbackStatus === 'pending').length,
+                held: primarySummary.requests.filter((record) => record.finalStatus === 'held' ||
+                    record.finalStatus === 'timeout_unknown' ||
+                    record.fallbackStatus === 'held' ||
+                    record.fallbackStatus === 'timeout_unknown').length,
+            },
             agents: [...this.agents.entries()].map(([name, agent]) => ({
                 name,
                 status: agent.state.status,
@@ -3990,6 +6270,16 @@ export class AgentFramework {
      *     every ~15 min instead of flooding the channel on every occurrence.
      * See connectome docs/observability.md.
      */
+    /**
+     * Public ops-alert entry point for host-wired alarms that originate
+     * OUTSIDE the framework (e.g. context-manager's repeating
+     * compression-quarantine klaxon, wired in the host at strategy
+     * construction). Same sinks and cooldown as internal alerts:
+     * failures.log + ops:alert trace + CONNECTOME_OPS_WEBHOOK.
+     */
+    notifyOps(kind, agentName, message, data) {
+        this.opsAlert(kind, agentName, message, { data });
+    }
     opsAlert(kind, agentName, message, opts) {
         if (!opts?.skipLog) {
             this.logFailure({ agent: agentName, kind, reason: message, ...opts?.data });
@@ -4064,6 +6354,16 @@ export class AgentFramework {
         }
         return {};
     }
+    /**
+     * Public entry to the ops-alert pipeline (failures.log + ops:alert trace +
+     * throttled webhook) for host-level detectors OUTSIDE the framework's own
+     * inference driver — e.g. the host's logging adapter catching refusals on
+     * off-path calls (compression/summarizer, maintenance) that noteRefusal
+     * never sees. Same per-(agent,kind) cooldown as everything else.
+     */
+    notifyOpsAlert(kind, agentName, message, data) {
+        this.opsAlert(kind, agentName, message, { data });
+    }
     noteInferenceExhausted(agentName, reason, retryable, errorType) {
         const streak = (this.consecutiveInferenceFailures.get(agentName) ?? 0) + 1;
         this.consecutiveInferenceFailures.set(agentName, streak);
@@ -4222,6 +6522,7 @@ export class AgentFramework {
         this.checkpointManager = new CheckpointManager(this.store, (event) => this.emitTrace(event));
         // Channel registry (Step 7)
         this.channelRegistry = new ChannelRegistry(this.mcplServerRegistry, this.featureSetManager, (event) => this.pushEvent(event), (event) => this.emitTrace(event), {
+            store: this.store,
             sendTypingFn: (serverId, channelId, metadata, op) => {
                 const server = this.mcplServerRegistry.getServer(serverId);
                 if (server) {
@@ -4275,9 +6576,17 @@ export class AgentFramework {
         };
         for (const config of serverConfigs) {
             try {
-                await this.connectMcplServerInternal(config);
+                // Stage every startup connection with both planes closed. This removes
+                // server-order dependence: no early heartbeat/shell push can become
+                // model-visible before a later Discord connection has joined the same
+                // awareness generation.
+                await this.connectMcplServerInternal(config, true);
             }
             catch (error) {
+                if (error instanceof DiscordAwarenessAccountingError) {
+                    await this.mcplServerRegistry.closeAll();
+                    throw error;
+                }
                 // Fail-open: log and continue with remaining servers
                 const err = error instanceof Error ? error : new Error(String(error));
                 console.error(`Failed to connect MCPL server "${config.id}":`, err.message);
@@ -4294,16 +6603,289 @@ export class AgentFramework {
                 });
             }
         }
+        // Start the durable drain only after all startup connections are staged.
+        // The awareness tools/call is written before control-plane registration is
+        // flushed, preserving the server-side queue -> registration -> call order.
+        const startupBarrier = this.installMcplDataPlaneGate();
+        this.releaseMcplDataPlaneGate(startupBarrier);
+        try {
+            await startupBarrier.promise;
+            this.completeMcplDataPlaneGate(startupBarrier);
+        }
+        catch (error) {
+            await this.mcplServerRegistry.closeAll();
+            throw error;
+        }
         // Discover tools from all connected servers
         await this.refreshMcplTools();
     }
+    /** Reconcile the durable ledger with Chronicle, then deliver every server's work. */
+    async syncDiscordAwarenessMarkers(_onlyServerId) {
+        if (!this.discordAwarenessOutbox)
+            return;
+        // A targeted retry may discover pending work for other Discord servers
+        // during reconciliation. Safety is global, so one generation accounts for
+        // all pending operations before releasing any MCPL data plane.
+        const barrier = this.installMcplDataPlaneGate();
+        this.releaseMcplDataPlaneGate(barrier);
+        try {
+            await barrier.promise;
+            this.completeMcplDataPlaneGate(barrier);
+        }
+        catch (error) {
+            await this.failMcplDataPlaneGate(barrier, 'explicit synchronization', error);
+            throw error;
+        }
+    }
+    async resumePreparedDiscordSuppressions() {
+        if (!this.discordAwarenessOutbox)
+            return;
+        const batches = this.discordAwarenessOutbox.preparedSuppressionsForBranch(this.store.currentBranch().name, this.store.listBranches());
+        for (const batch of batches) {
+            const agent = this.agents.get(batch.agentName);
+            if (!agent) {
+                throw new Error(`Cannot resume Discord suppression ${batch.id}: agent ${batch.agentName} is not configured`);
+            }
+            const cm = agent.getContextManager();
+            for (const interval of [...(batch.suppressionIntervals ?? [])].reverse()) {
+                const from = cm.getMessage(interval.fromId);
+                const to = cm.getMessage(interval.toId);
+                if (!from && !to)
+                    continue; // This interval committed before the crash.
+                if (!from || !to) {
+                    throw new Error(`Cannot safely resume Discord suppression ${batch.id}: interval ` +
+                        `${interval.fromId}..${interval.toId} is only partially present`);
+                }
+                if (interval.fromId === interval.toId)
+                    cm.removeMessage(from.id);
+                else
+                    cm.removeMessages(from.id, to.id);
+            }
+            this.discordAwarenessOutbox.activate(batch.id);
+            console.error(`[discord-awareness] resumed suppression batch ${batch.id}`);
+        }
+    }
+    /**
+     * Deliver every due ref independently. Permanent Discord failures are kept
+     * in the ledger for audit but do not block later operations; retryable
+     * failures remain pending for the next reconnect/list-change attempt.
+     */
+    drainDiscordAwarenessOutbox(serverId) {
+        if (!this.discordAwarenessOutbox) {
+            return Promise.resolve({ status: 'delivered', delivered: 0, failed: 0 });
+        }
+        const existing = this.discordAwarenessDrains.get(serverId);
+        if (existing)
+            return existing;
+        const drain = (async () => {
+            const connection = this.mcplServerRegistry?.getServer(serverId);
+            if (!connection?.isConnected) {
+                const operations = this.readDiscordAwarenessPending(serverId);
+                for (const operation of operations) {
+                    this.writeDiscordAwarenessFailure(operation.batchId, operation.ref, operation.action, 'Awareness delivery not attempted: MCPL connection unavailable', false);
+                }
+                if (operations.length > 0) {
+                    console.error(`[discord-awareness] ${serverId}: connection unavailable; ` +
+                        `durably deferred=${operations.length}`);
+                }
+                return { status: 'unavailable', accounted: operations.length };
+            }
+            let delivered = 0;
+            let failed = 0;
+            const attempted = new Set();
+            while (true) {
+                const operations = this.readDiscordAwarenessPending(serverId).filter((operation) => {
+                    const key = `${operation.batchId}\0${operation.ref.channelId}\0${operation.ref.messageId}\0${operation.action}`;
+                    if (attempted.has(key))
+                        return false;
+                    attempted.add(key);
+                    return true;
+                });
+                if (operations.length === 0)
+                    break;
+                for (const operation of operations) {
+                    const ref = operation.ref;
+                    const channelId = ref.channelId.startsWith('discord:')
+                        ? ref.channelId.split(':').at(-1)
+                        : ref.channelId;
+                    let deliveryError;
+                    try {
+                        const tool = operation.action === 'add' ? 'add_reaction' : 'remove_reaction';
+                        const result = await connection.sendToolsCallWithDeadline(tool, {
+                            channelId,
+                            messageId: ref.messageId,
+                            emoji: operation.emoji,
+                        }, this.discordAwarenessDeadlineMs);
+                        if (result.isError) {
+                            deliveryError = result.content
+                                .map((content) => content.text ?? '')
+                                .filter(Boolean)
+                                .join('; ') || `Discord ${tool} returned an error`;
+                        }
+                    }
+                    catch (error) {
+                        deliveryError = error instanceof Error ? error.message : String(error);
+                    }
+                    if (deliveryError !== undefined) {
+                        const permanent = isPermanentDiscordReactionFailure(deliveryError);
+                        this.writeDiscordAwarenessFailure(operation.batchId, ref, operation.action, deliveryError, permanent);
+                        failed++;
+                        console.error(`[discord-awareness] ${operation.action} failed for ${ref.channelId}/${ref.messageId}` +
+                            ` (${permanent ? 'permanent' : 'retryable'}): ${deliveryError}`);
+                    }
+                    else {
+                        this.writeDiscordAwarenessSuccess(operation.batchId, ref, operation.action);
+                        delivered++;
+                    }
+                }
+            }
+            if (delivered > 0 || failed > 0) {
+                console.error(`[discord-awareness] ${serverId}: delivered=${delivered} failed=${failed}`);
+            }
+            return { status: 'delivered', delivered, failed };
+        })().finally(() => {
+            this.discordAwarenessDrains.delete(serverId);
+        });
+        this.discordAwarenessDrains.set(serverId, drain);
+        return drain;
+    }
+    readDiscordAwarenessPending(serverId) {
+        try {
+            return this.discordAwarenessOutbox.pending(serverId);
+        }
+        catch (error) {
+            throw new DiscordAwarenessAccountingError(`ledger read${serverId ? ` for ${serverId}` : ''}`, error);
+        }
+    }
+    writeDiscordAwarenessSuccess(batchId, ref, action) {
+        try {
+            this.discordAwarenessOutbox.recordSuccess(batchId, ref, action);
+        }
+        catch (error) {
+            throw new DiscordAwarenessAccountingError('recordSuccess ledger write', error);
+        }
+    }
+    writeDiscordAwarenessFailure(batchId, ref, action, errorMessage, permanent) {
+        try {
+            this.discordAwarenessOutbox.recordFailure(batchId, ref, action, errorMessage, permanent);
+        }
+        catch (error) {
+            throw new DiscordAwarenessAccountingError('recordFailure ledger write', error);
+        }
+    }
+    beginDiscordAwarenessBarrier() {
+        if (!this.discordAwarenessOutbox) {
+            return {
+                requiresBarrier: false,
+                promise: Promise.resolve({ status: 'delivered', delivered: 0, failed: 0 }),
+            };
+        }
+        try {
+            this.discordAwarenessOutbox.reconcileForBranch(this.store.currentBranch().name, this.store.listBranches());
+        }
+        catch (error) {
+            throw new DiscordAwarenessAccountingError('branch reconciliation', error);
+        }
+        const pending = this.readDiscordAwarenessPending();
+        if (pending.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),
+            };
+        });
+        return { requiresBarrier: true, 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.
+     */
+    installMcplDataPlaneGate() {
+        for (const connection of this.mcplServerRegistry?.getAllServers() ?? []) {
+            connection.pauseDataPlane();
+        }
+        const generation = ++this.discordAwarenessBarrierGeneration;
+        let begun;
+        try {
+            begun = this.beginDiscordAwarenessBarrier();
+        }
+        catch (error) {
+            begun = {
+                requiresBarrier: true,
+                promise: Promise.reject(error),
+            };
+        }
+        const barrier = { generation, ...begun };
+        this.discordAwarenessBarrier = barrier;
+        return barrier;
+    }
+    releaseMcplDataPlaneGate(barrier) {
+        if (this.discordAwarenessBarrier !== barrier)
+            return;
+        if (barrier.requiresBarrier) {
+            for (const connection of this.mcplServerRegistry?.getAllServers() ?? []) {
+                connection.readyControlPlane();
+            }
+            return;
+        }
+        this.completeMcplDataPlaneGate(barrier);
+    }
+    completeMcplDataPlaneGate(barrier) {
+        if (this.discordAwarenessBarrier !== barrier)
+            return false;
+        this.discordAwarenessBarrier = null;
+        for (const connection of this.mcplServerRegistry?.getAllServers() ?? []) {
+            // ready() can synchronously flush a nested list-change notification that
+            // installs a newer global generation. Never let this older completion
+            // release any remaining server behind that newer gate.
+            if (this.discordAwarenessBarrier !== null)
+                return false;
+            connection.ready();
+        }
+        return this.discordAwarenessBarrier === null;
+    }
+    async failMcplDataPlaneGate(barrier, context, error) {
+        if (this.discordAwarenessBarrier !== barrier)
+            return;
+        const err = error instanceof Error ? error : new Error(String(error));
+        console.error(`[discord-awareness] ${context} failed globally:`, err.message);
+        const connections = this.mcplServerRegistry?.getAllServers() ?? [];
+        for (const connection of connections) {
+            this.emitTrace({
+                type: 'mcpl:server-error',
+                serverId: connection.id,
+                error: `Discord awareness accounting unhealthy: ${err.message}`,
+            });
+        }
+        await Promise.all(connections.map(async (connection) => {
+            await connection.reconnectAfterFailure().catch((closeError) => {
+                console.error(`[discord-awareness] could not recycle unhealthy connection ${connection.id}:`, closeError instanceof Error ? closeError.message : closeError);
+            });
+        }));
+    }
     /**
      * Connect a single MCPL server: register routing entries, open the
      * connection, wire events, and initialize feature sets / scopes /
      * checkpoints. Shared by startup (initializeMcpl) and the runtime
      * lifecycle API (connectMcplServer). Throws on connection failure.
      */
-    async connectMcplServerInternal(config) {
+    async connectMcplServerInternal(config, deferAwareness = false) {
         if (!this.mcplServerRegistry || !this.mcplHostCapabilities) {
             throw new Error('MCPL subsystem is not initialized');
         }
@@ -4314,16 +6896,32 @@ export class AgentFramework {
         this.mcplServerConfigs.set(config.id, config);
         // Record per-server channel subscription policy before the server
         // registers channels — handleRegister fires during the handshake.
-        if (config.channelSubscription !== undefined && this.channelRegistry) {
-            this.channelRegistry.setSubscriptionPolicy(config.id, config.channelSubscription);
+        if (this.channelRegistry) {
+            this.channelRegistry.setSubscriptionPolicy(config.id, config.channelSubscription ?? 'manual');
         }
         const connection = await this.mcplServerRegistry.addServer(config, this.mcplHostCapabilities);
-        // Wire event listeners then flush any events that arrived during the
-        // handshake window (between setupMessageRouting and now).
+        // Wire listeners before either startup staging or the runtime global gate
+        // releases control traffic needed for registration and marker service.
         this.wireMcplEvents(connection);
-        connection.ready();
         // Initialize feature sets if server advertises MCPL capabilities
         this.registerMcplServerFeatures(config, connection);
+        if (deferAwareness) {
+            this.emitTrace({ type: 'module:added', moduleName: `mcpl:${config.id}` });
+            return;
+        }
+        const awarenessBarrier = this.installMcplDataPlaneGate();
+        this.releaseMcplDataPlaneGate(awarenessBarrier);
+        try {
+            await awarenessBarrier.promise;
+            this.completeMcplDataPlaneGate(awarenessBarrier);
+        }
+        catch (error) {
+            // Startup cannot fail open on a broken awareness ledger. Disable the
+            // reconnecting stub/connection before propagating the distinct error to
+            // initializeMcpl, which tears down any other servers and aborts create().
+            await connection.close().catch(() => { });
+            throw error;
+        }
         this.emitTrace({ type: 'module:added', moduleName: `mcpl:${config.id}` });
     }
     /**
@@ -4490,12 +7088,18 @@ export class AgentFramework {
             }
         });
         // Handle push events (Step 6)
-        connection.on('push-event', (params, responder) => {
+        connection.on('push-event', async (params, responder) => {
+            const barrier = this.discordAwarenessBarrier;
+            if (barrier)
+                await barrier.promise;
             this.pushHandler?.handlePushEvent(connection.id, params, responder);
         });
         // Handle server-initiated inference requests (Step 6)
         connection.on('inference-request', async (params, responder) => {
             if (this.inferenceRouter && responder) {
+                const barrier = this.discordAwarenessBarrier;
+                if (barrier)
+                    await barrier.promise;
                 await this.inferenceRouter.handleInferenceRequest(connection.id, params, {
                     respond: responder.respond,
                     respondError: responder.respondError,
@@ -4512,7 +7116,10 @@ export class AgentFramework {
             await this.channelRegistry?.handleChanged(connection.id, params);
         });
         // Handle incoming channel messages (Step 7)
-        connection.on('channels-incoming', (params, responder) => {
+        connection.on('channels-incoming', async (params, responder) => {
+            const barrier = this.discordAwarenessBarrier;
+            if (barrier)
+                await barrier.promise;
             this.channelRegistry?.handleIncoming(connection.id, params, responder);
         });
         // Handle host-level admin commands from a surface (e.g. Discord /undo)
@@ -4520,6 +7127,9 @@ export class AgentFramework {
             if (!responder)
                 return;
             try {
+                const barrier = this.discordAwarenessBarrier;
+                if (barrier)
+                    await barrier.promise;
                 const result = await this.handleHostCommand(connection.id, params ?? {});
                 responder.respond(result);
             }
@@ -4530,7 +7140,15 @@ export class AgentFramework {
         });
         // Handle dynamic tool list changes (notifications/tools/list_changed)
         connection.on('tools-list-changed', () => {
+            // Pause before starting any async refresh. This listener runs
+            // synchronously in the transport line callback, so a following inbound
+            // data event cannot pass before the new barrier exists.
+            const awarenessBarrier = this.installMcplDataPlaneGate();
+            this.releaseMcplDataPlaneGate(awarenessBarrier);
             this.handleToolsListChanged(connection.id);
+            void awarenessBarrier.promise.then(() => {
+                this.completeMcplDataPlaneGate(awarenessBarrier);
+            }).catch((error) => this.failMcplDataPlaneGate(awarenessBarrier, 'tools-list reconciliation', error));
         });
         // Re-establish full server registration on reconnect. The 'close' handler
         // removed the feature-set state, so pushes / inference requests from the
@@ -4540,6 +7158,10 @@ export class AgentFramework {
         // preserved across the transient close are resumed by idempotent
         // registration. Then refresh tools (server may have different tools).
         connection.on('reconnect', (info) => {
+            // Install the barrier synchronously so any inbound event emitted after
+            // reconnect observes it before doing work that could wake an agent. The
+            // connection paused its data plane before wiring the fresh transport.
+            const awarenessBarrier = this.installMcplDataPlaneGate();
             try {
                 const config = this.mcplServerConfigs.get(connection.id);
                 if (config) {
@@ -4549,15 +7171,21 @@ export class AgentFramework {
             catch (error) {
                 console.error(`MCPL server "${connection.id}" re-registration after reconnect failed:`, error instanceof Error ? error.message : error);
             }
+            this.releaseMcplDataPlaneGate(awarenessBarrier);
             this.handleToolsListChanged(connection.id);
-            this.emitTrace({
-                type: 'mcpl:server-reconnected',
-                serverId: connection.id,
-                attempts: info?.attempts ?? 0,
-            });
-            // Mirror the module:removed emitted on 'close' so module-lifecycle
-            // consumers see the server come back, not just vanish.
-            this.emitTrace({ type: 'module:added', moduleName: `mcpl:${connection.id}` });
+            void awarenessBarrier.promise.then(() => {
+                if (awarenessBarrier.requiresBarrier
+                    && !this.completeMcplDataPlaneGate(awarenessBarrier))
+                    return;
+                this.emitTrace({
+                    type: 'mcpl:server-reconnected',
+                    serverId: connection.id,
+                    attempts: info?.attempts ?? 0,
+                });
+                // Mirror the module:removed emitted on 'close' so module-lifecycle
+                // consumers see the server come back, not just vanish.
+                this.emitTrace({ type: 'module:added', moduleName: `mcpl:${connection.id}` });
+            }).catch((error) => this.failMcplDataPlaneGate(awarenessBarrier, 'reconnect reconciliation', error));
         });
         // Surface connect/reconnect failures. Before these traces existed the
         // only receipt was a console.error on the host's own stderr — invisible
@@ -4596,6 +7224,7 @@ export class AgentFramework {
                 type: 'mcpl:orphaned-response',
                 serverId: connection.id,
                 responseId: info.id,
+                method: info.method,
                 hadState: info.hadState,
                 hadCheckpoint: info.hadCheckpoint,
             });
@@ -5021,6 +7650,308 @@ export class AgentFramework {
             endTurn: true,
         });
     }
+    /**
+     * Handle the synthesized `save_recent_image` tool: locate the requested
+     * image blocks in the calling agent's context (blobs re-inlined, counted
+     * back from the most recent) and write their bytes to a workspace mount
+     * via WorkspaceModule.writeBinary.
+     */
+    dispatchSaveImageToolCall(agentName, call) {
+        this.emitTrace({ type: 'tool:started', module: 'workspace', tool: call.name, callId: call.id, input: call.input });
+        const finish = (result) => {
+            this.emitTrace({
+                type: result.isError ? 'tool:failed' : 'tool:completed',
+                module: 'workspace',
+                tool: call.name,
+                callId: call.id,
+                durationMs: 0,
+                ...(result.isError ? { error: result.error } : {}),
+            });
+            this.pushEvent({ type: 'tool-result', callId: call.id, agentName, moduleName: 'workspace', result });
+        };
+        void (async () => {
+            try {
+                const workspace = this.getWorkspaceModule();
+                if (!workspace)
+                    throw new Error('save_recent_image requires a workspace module');
+                const agent = this.agents.get(agentName);
+                if (!agent)
+                    throw new Error(`Unknown agent: ${agentName}`);
+                const input = (call.input ?? {});
+                if (typeof input.path !== 'string' || input.path.length === 0) {
+                    throw new Error('save_recent_image: `path` (mount-prefixed) is required');
+                }
+                const index = input.index === undefined ? 0 : Number(input.index);
+                if (!Number.isInteger(index) || index < 0) {
+                    throw new Error('save_recent_image: `index` must be a non-negative integer');
+                }
+                const count = input.count === undefined ? 1 : Number(input.count);
+                const MAX_COUNT = 20;
+                if (!Number.isInteger(count) || count < 1 || count > MAX_COUNT) {
+                    throw new Error(`save_recent_image: \`count\` must be an integer in 1..${MAX_COUNT}`);
+                }
+                const lastWanted = index + count - 1;
+                // Walk the message store tail-first in bounded windows, re-inlining
+                // blob media, until we've collected the requested range. Scanning is
+                // capped so a pathological index can't drag the whole store through
+                // blob resolution.
+                const MAX_SCAN = 500;
+                const WINDOW = 25;
+                const cm = agent.getContextManager();
+                const total = cm.getMessageCount();
+                let seen = 0;
+                let scanned = 0;
+                const found = [];
+                for (let end = total; end > 0 && scanned < MAX_SCAN && found.length < count; end -= WINDOW) {
+                    const start = Math.max(0, end - WINDOW);
+                    const { messages } = cm.getMessageWindow(start, end - start, { resolveBlobs: true });
+                    scanned += end - start;
+                    for (let i = messages.length - 1; i >= 0 && found.length < count; i--) {
+                        const content = messages[i]?.content;
+                        if (!Array.isArray(content))
+                            continue;
+                        for (let b = content.length - 1; b >= 0 && found.length < count; b--) {
+                            const block = content[b];
+                            if (block?.type !== 'image')
+                                continue;
+                            if (seen >= index && seen <= lastWanted) {
+                                if (block.source?.type !== 'base64' || typeof block.source.data !== 'string') {
+                                    throw new Error(`save_recent_image: image at index ${seen} is not stored inline (base64) — cannot save it`);
+                                }
+                                found.push({
+                                    rangeOffset: seen - index,
+                                    data: block.source.data,
+                                    mediaType: block.source.mediaType ?? 'image/png',
+                                    messagesBack: total - (start + i),
+                                });
+                            }
+                            seen++;
+                        }
+                    }
+                }
+                if (found.length === 0) {
+                    throw new Error(seen === 0
+                        ? `save_recent_image: no images found in the most recent ${Math.min(scanned, MAX_SCAN)} messages`
+                        : `save_recent_image: only ${seen} image(s) found in the most recent ${Math.min(scanned, MAX_SCAN)} messages (asked for index ${index})`);
+                }
+                // Single image → path as given. Range → numeric suffix before the
+                // extension ("cat.png" → "cat-0.png"), 0 = newest of the range.
+                const pathFor = (rangeOffset) => {
+                    if (count === 1)
+                        return input.path;
+                    const p = input.path;
+                    const dot = p.lastIndexOf('.');
+                    const slash = p.lastIndexOf('/');
+                    return dot > slash
+                        ? `${p.slice(0, dot)}-${rangeOffset}${p.slice(dot)}`
+                        : `${p}-${rangeOffset}`;
+                };
+                const savedFiles = [];
+                for (const image of found) {
+                    const destination = pathFor(image.rangeOffset);
+                    const bytes = Buffer.from(image.data, 'base64');
+                    const result = await workspace.writeBinary(destination, bytes, image.mediaType);
+                    if (!result.success) {
+                        finish({
+                            success: false,
+                            error: `save_recent_image: failed writing "${destination}": ${result.error}` +
+                                (savedFiles.length > 0
+                                    ? ` (already saved: ${savedFiles.map((f) => f.path).join(', ')})`
+                                    : ''),
+                            isError: true,
+                        });
+                        return;
+                    }
+                    savedFiles.push({
+                        ...result.data,
+                        imageIndex: index + image.rangeOffset,
+                        messagesBack: image.messagesBack,
+                    });
+                }
+                finish({
+                    success: true,
+                    data: {
+                        saved: savedFiles,
+                        ...(found.length < count
+                            ? { note: `only ${found.length} of ${count} requested images exist in the scanned window` }
+                            : {}),
+                    },
+                });
+            }
+            catch (error) {
+                finish({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                    isError: true,
+                });
+            }
+        })();
+    }
+    dispatchAgentSettingsToolCall(agentName, call) {
+        this.emitTrace({
+            type: 'tool:started',
+            module: 'agent',
+            tool: call.name,
+            callId: call.id,
+            input: call.input,
+        });
+        let result;
+        try {
+            const input = (call.input ?? {});
+            const extensions = this.collectAgentSettingsExtensions();
+            /** Extension values merged flat alongside the core snapshot. */
+            const extGet = () => {
+                const out = {};
+                for (const ext of extensions.values())
+                    Object.assign(out, ext.get(agentName));
+                return out;
+            };
+            switch (input.action) {
+                case 'get':
+                    result = {
+                        success: true,
+                        data: { ...this.getAgentRuntimeSettings(agentName), ...extGet() },
+                    };
+                    break;
+                case 'cancel':
+                    result = { success: true, data: this.cancelAgentRuntimeSettingsTransition(agentName) };
+                    break;
+                case 'update': {
+                    const patch = {};
+                    if (input.context_budget_tokens !== undefined) {
+                        patch.contextBudgetTokens = Number(input.context_budget_tokens);
+                    }
+                    if (input.tail_tokens !== undefined)
+                        patch.tailTokens = Number(input.tail_tokens);
+                    if (input.transition_pace_tokens !== undefined) {
+                        patch.transitionPaceTokens = Number(input.transition_pace_tokens);
+                    }
+                    if (input.same_round_think_text_policy !== undefined) {
+                        patch.sameRoundThinkTextPolicy = input.same_round_think_text_policy;
+                    }
+                    // Route extension-owned keys to their modules; apply the core patch
+                    // only when it touches core keys (an extension-only update must not
+                    // disturb a converging budget transition).
+                    const extResults = {};
+                    for (const ext of extensions.values()) {
+                        const slice = {};
+                        for (const key of ext.keys) {
+                            if (input[key] !== undefined)
+                                slice[key] = input[key];
+                        }
+                        if (Object.keys(slice).length > 0) {
+                            Object.assign(extResults, ext.update(agentName, slice));
+                        }
+                    }
+                    const coreTouched = Object.keys(patch).length > 0;
+                    const core = coreTouched
+                        ? this.updateAgentRuntimeSettings(agentName, patch)
+                        : this.getAgentRuntimeSettings(agentName);
+                    result = {
+                        success: true,
+                        data: {
+                            ...core,
+                            ...extGet(),
+                            ...extResults,
+                            ...(patch.sameRoundThinkTextPolicy !== undefined
+                                ? {
+                                    sameRoundThinkTextPolicyUpdateNote: 'Stored now; applies to provider think routing and description beginning with the next inference.',
+                                }
+                                : {}),
+                        },
+                    };
+                    break;
+                }
+                case 'reset': {
+                    let keys;
+                    const extResetKeys = new Map();
+                    const resetsAllSettings = input.settings === undefined;
+                    if (input.settings !== undefined) {
+                        if (!Array.isArray(input.settings))
+                            throw new Error('reset `settings` must be an array');
+                        const names = {
+                            context_budget_tokens: 'contextBudgetTokens',
+                            tail_tokens: 'tailTokens',
+                            transition_pace_tokens: 'transitionPaceTokens',
+                            same_round_think_text_policy: 'sameRoundThinkTextPolicy',
+                        };
+                        keys = [];
+                        for (const name of input.settings) {
+                            if (typeof name === 'string' && names[name]) {
+                                keys.push(names[name]);
+                                continue;
+                            }
+                            const owner = [...extensions.values()].find((ext) => typeof name === 'string' && ext.keys.includes(name));
+                            if (!owner)
+                                throw new Error(`Unknown reset setting: ${String(name)}`);
+                            const list = extResetKeys.get(owner) ?? [];
+                            list.push(name);
+                            extResetKeys.set(owner, list);
+                        }
+                        if (keys.length === 0)
+                            keys = undefined;
+                    }
+                    const touchedSameRoundThinkTextPolicy = resetsAllSettings || keys?.includes('sameRoundThinkTextPolicy') === true;
+                    const extResults = {};
+                    if (input.settings === undefined) {
+                        // Reset-all covers extensions too.
+                        for (const ext of extensions.values()) {
+                            if (ext.reset)
+                                Object.assign(extResults, ext.reset(agentName));
+                        }
+                    }
+                    else {
+                        for (const [ext, list] of extResetKeys) {
+                            if (ext.reset)
+                                Object.assign(extResults, ext.reset(agentName, list));
+                        }
+                    }
+                    const coreTouched = input.settings === undefined || keys !== undefined;
+                    const core = coreTouched
+                        ? this.resetAgentRuntimeSettings(agentName, keys)
+                        : this.getAgentRuntimeSettings(agentName);
+                    result = {
+                        success: true,
+                        data: {
+                            ...core,
+                            ...extGet(),
+                            ...extResults,
+                            ...(touchedSameRoundThinkTextPolicy
+                                ? {
+                                    sameRoundThinkTextPolicyUpdateNote: 'Reset now; restored provider think routing and description apply beginning with the next inference.',
+                                }
+                                : {}),
+                        },
+                    };
+                    break;
+                }
+                default:
+                    throw new Error('agent_settings: action must be get, update, reset, or cancel');
+            }
+        }
+        catch (error) {
+            result = {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+                isError: true,
+            };
+        }
+        this.emitTrace({
+            type: result.isError ? 'tool:failed' : 'tool:completed',
+            module: 'agent',
+            tool: call.name,
+            callId: call.id,
+            durationMs: 0,
+            ...(result.isError ? { error: result.error } : {}),
+        });
+        this.pushEvent({
+            type: 'tool-result',
+            callId: call.id,
+            agentName,
+            moduleName: 'agent',
+            result,
+        });
+    }
     /** Aggregate the event-tag vocabulary: reserved chat:* core + each connected
      *  server's declared tag ontology + gate.js status. */
     buildEventTagsResult() {