@animalabs/agent-framework 0.6.4 → 0.6.6

package/dist/src/framework.js

@@ -17,6 +17,29 @@ 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';
+/**
+ * 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*, but prose
+ * written around a think is the agent's actual voice and must be delivered.
+ *
+ * Scope: mid-turn rounds apply this PER ROUND (a round's prose is suppressed
+ * only by a silencing tool in that same round — live delivery can't be
+ * retracted by a later round's skip_reply); the turn's TRAILING prose keeps
+ * the historical turn-wide rule (any silencing tool anywhere in the turn
+ * suppresses it), preserving the "send_message then 'sent it.' postscript"
+ * double-post guard.
+ */
+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';
@@ -146,7 +169,24 @@ export class AgentFramework {
     processLoggingPersist;
     processLoggingBroadcast;
     activeStreams = new Map();
+    /** 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. Cleared at the
+     *  start of every non-restart turn. */
+    turnLocusPins = new Map();
     pendingAssistantBlocks = new Map();
+    /** Streams the FRAMEWORK cancelled for non-terminal reasons, keyed
+     *  `${agentName}:${streamId}`: an endTurn tool result or a context-budget
+     *  restart. The membrane still delivers an `aborted` event for these, and
+     *  without the marker the abort handler would treat it as a terminal
+     *  failure — settling ephemerals with a rejection and emitting a spurious
+     *  `inference:exhausted` (which also pollutes the failure streak). Kept
+     *  separate from ephemeralRuns deliberately: endTurn/budget cancels happen
+     *  for resident agents too, and the key is per-stream, not per-agent. */
+    frameworkCancelledStreams = new Map();
+    /** Active runEphemeralToCompletion runs, keyed by agent name. */
+    ephemeralRuns = new Map();
     /** Per-agent count of consecutive exhausted inferences (reset on any success).
      *  Drives hard-down escalation — see noteInferenceExhausted. */
     consecutiveInferenceFailures = new Map();
@@ -175,6 +215,13 @@ export class AgentFramework {
      *  Bounds the automatic quarantine loop the same way refusalRewinds bounds
      *  the refusal loop, so the breaker can never shed the whole history. */
     exhaustionRewinds = new Map();
+    /** Agents with an OverBudget drain kick currently in flight. The breaker in
+     *  noteInferenceExhausted fires on EVERY matching failure and the scenario it
+     *  exists for is "every activation fails, repeatedly" — without this guard,
+     *  overlapping kicks race the strategy's own pendingCompression gate and the
+     *  tick counts in the success log stop meaning anything. One kick per agent
+     *  at a time; cleared when the kick settles (success or failure). */
+    overBudgetDrainInFlight = new Set();
     /** Per-agent current rewind episode: the single consolidated marker's id and
      *  how many turns have been shed so far. One marker per episode, updated in
      *  place (see updateRewindMarker); cleared when the episode ends. */
@@ -537,7 +584,9 @@ export class AgentFramework {
         if (this.maintenancePass || !this.running)
             return;
         const pass = this.runQueuedMaintenance().catch((error) => {
-            console.error('[context-maintenance] pass failed:', error instanceof Error ? error.message : error);
+            const reason = error instanceof Error ? error.message : String(error);
+            console.error('[context-maintenance] pass failed:', reason);
+            this.opsAlert('context-maintenance-failed', 'framework', reason, { data: { scope: 'pass' } });
         });
         this.maintenancePass = pass;
         void pass.finally(() => {
@@ -588,6 +637,13 @@ export class AgentFramework {
                 catch (error) {
                     record.error = error instanceof Error ? error.message : String(error);
                     console.error(`[context-maintenance] agent=${agent.name} failed:`, record.error);
+                    this.opsAlert('context-maintenance-failed', agent.name, record.error, {
+                        data: {
+                            scope: 'agent',
+                            ...(record.pendingBefore ? { pending: record.pendingBefore } : {}),
+                            ...(record.progressBefore ? { progress: record.progressBefore } : {}),
+                        },
+                    });
                 }
                 finally {
                     const pending = cm.getPendingWork()?.description;
@@ -725,10 +781,43 @@ 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];
+        return [
+            ...moduleTools,
+            ...this.mcplTools,
+            ...channelTools,
+            ...gateTools,
+            AgentFramework.AGENT_SETTINGS_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() {
@@ -905,6 +994,29 @@ 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;
+        }
+    }
+    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.
      *
@@ -934,6 +1046,50 @@ export class AgentFramework {
         };
         return { agent, contextManager, cleanup };
     }
+    createDeferred() {
+        let resolve;
+        let reject;
+        const promise = new Promise((res, rej) => {
+            resolve = res;
+            reject = rej;
+        });
+        return { promise, resolve, reject };
+    }
+    /** Liveness ping for an active ephemeral run (no-op otherwise). */
+    touchEphemeralRun(agentName, inferenceStarted = false) {
+        const run = this.ephemeralRuns.get(agentName);
+        if (!run)
+            return;
+        if (inferenceStarted) {
+            run.inferenceStarted = true;
+        }
+        run.lastActivity = Date.now();
+    }
+    recordEphemeralToolCalls(agentName, count) {
+        const run = this.ephemeralRuns.get(agentName);
+        if (!run)
+            return;
+        run.toolCallsCount += count;
+        run.lastActivity = Date.now();
+    }
+    /** Settle an active ephemeral run (no-op for resident agents). The tool-call
+     *  count comes from the run's own counter — the single source of truth,
+     *  which unlike a per-stream local survives budget restarts. */
+    settleAgent(agentName, outcome) {
+        const run = this.ephemeralRuns.get(agentName);
+        if (!run)
+            return;
+        run.lastActivity = Date.now();
+        if (outcome.stopReason === 'exhausted') {
+            run.settle.reject(new Error(outcome.error ?? 'Unknown error'));
+            return;
+        }
+        run.settle.resolve({
+            stopReason: outcome.stopReason,
+            speech: outcome.speech,
+            toolCallsCount: run.toolCallsCount,
+        });
+    }
     /**
      * Run an ephemeral agent to completion through the framework's event loop.
      *
@@ -944,139 +1100,73 @@ export class AgentFramework {
      * The caller provides a pre-created agent + contextManager (from createEphemeralAgent).
      * The task message should already be in the context manager.
      */
-    async runEphemeralToCompletion(agent, contextManager) {
+    async runEphemeralToCompletion(agent, contextManager, watchdogs) {
         // Register temporarily so the event loop can drive it
         this.agents.set(agent.name, agent);
-        return new Promise((resolve, reject) => {
-            let speech = '';
-            let toolCallsCount = 0;
-            let settled = false;
-            let inferenceStarted = false;
-            let lastActivity = Date.now();
-            const STARTUP_TIMEOUT_MS = 30_000;
-            // After inference has started, give it 15 minutes of activity-bounded
-            // life. Each addressed trace event refreshes the deadline; only
-            // sustained silence trips it. Subagents that legitimately stream for
-            // 10+ minutes (e.g. long fork investigations) get the extra slack but
-            // stalled streams that emit `inference:completed` and then go quiet —
-            // the exact zombie shape we saw in production — are caught here.
-            const COMPLETION_IDLE_TIMEOUT_MS = 15 * 60_000;
-            const cleanup = () => {
-                if (settled)
-                    return;
-                settled = true;
-                clearTimeout(startupWatchdog);
-                clearInterval(completionWatchdog);
-                this.offTrace(traceListener);
-                this.agents.delete(agent.name);
-                this.evictTurnCheckpoints(agent.name);
-            };
-            // Watchdog: if inference never starts within 30s, the agent is a zombie.
-            // This catches cases where the event loop stalled, the agent was
-            // deregistered, or processInferenceRequests() skipped the request.
-            const startupWatchdog = setTimeout(() => {
-                if (!inferenceStarted && !settled) {
-                    cleanup();
+        const run = {
+            settle: this.createDeferred(),
+            inferenceStarted: false,
+            lastActivity: Date.now(),
+            toolCallsCount: 0,
+        };
+        this.ephemeralRuns.set(agent.name, run);
+        const STARTUP_TIMEOUT_MS = watchdogs?.startupTimeoutMs ?? 30_000;
+        // After inference has started, give it 15 minutes of activity-bounded
+        // life. The stream driver refreshes the deadline as it makes progress;
+        // sustained silence trips it.
+        const COMPLETION_IDLE_TIMEOUT_MS = watchdogs?.idleTimeoutMs ?? 15 * 60_000;
+        const IDLE_POLL_MS = watchdogs?.idlePollMs ?? 30_000;
+        let startupWatchdog = null;
+        let completionWatchdog = null;
+        const startupTimeout = new Promise((_, reject) => {
+            startupWatchdog = setTimeout(() => {
+                if (!run.inferenceStarted) {
                     reject(new Error(`Ephemeral agent "${agent.name}" failed to start inference within ` +
                         `${STARTUP_TIMEOUT_MS}ms — zombie detected. The event loop may have ` +
                         `stalled or the inference request was dropped.`));
                 }
             }, STARTUP_TIMEOUT_MS);
-            // Completion watchdog: once inference has started, reject if no trace
-            // activity for COMPLETION_IDLE_TIMEOUT_MS. Polls every 30s. Without
-            // this, an ephemeral that loses its terminal event (e.g. due to a
-            // future ordering regression or an upstream stream drop) hangs forever
-            // and keeps its concurrency slot pinned.
-            const completionWatchdog = setInterval(() => {
-                if (settled || !inferenceStarted)
+        });
+        const completionIdleTimeout = new Promise((_, reject) => {
+            completionWatchdog = setInterval(() => {
+                if (!run.inferenceStarted)
                     return;
-                const idle = Date.now() - lastActivity;
+                const idle = Date.now() - run.lastActivity;
                 if (idle > COMPLETION_IDLE_TIMEOUT_MS) {
-                    cleanup();
-                    reject(new Error(`Ephemeral agent "${agent.name}" stalled: no trace activity for ` +
+                    reject(new Error(`Ephemeral agent "${agent.name}" stalled: no stream-driver activity for ` +
                         `${Math.round(idle / 1000)}s after inference started (threshold ` +
                         `${Math.round(COMPLETION_IDLE_TIMEOUT_MS / 1000)}s). Stream likely ` +
                         `dropped or terminal event was lost.`));
                 }
-            }, 30_000);
-            const traceListener = (event) => {
-                if (settled)
-                    return;
-                // Only track events for our ephemeral agent
-                const agentName = 'agentName' in event ? event.agentName : null;
-                if (agentName !== agent.name)
-                    return;
-                // Any addressed event counts as liveness for the completion watchdog.
-                lastActivity = Date.now();
-                switch (event.type) {
-                    case 'inference:started':
-                        inferenceStarted = true;
-                        break;
-                    case 'inference:tokens': {
-                        inferenceStarted = true;
-                        const content = event.content;
-                        if (content)
-                            speech += content;
-                        break;
-                    }
-                    case 'inference:tool_calls_yielded': {
-                        const calls = event.calls;
-                        if (calls)
-                            toolCallsCount += calls.length;
-                        // Reset speech buffer — tool calls break the text
-                        speech = '';
-                        break;
-                    }
-                    case 'inference:stream_resumed':
-                        speech = '';
-                        break;
-                    case 'inference:completed': {
-                        // `inference:completed` is terminal — driveStream only emits it
-                        // from `case 'complete'`, which fires after the full tool
-                        // round-trip has finished and the model has stopped. Intermediate
-                        // tool-cycle transitions use `inference:stream_resumed`, not
-                        // `inference:completed`. So we resolve unconditionally here.
-                        //
-                        // Previously this branch gated on `agent.state.status === 'idle'`,
-                        // which was correct in intent but order-fragile: the framework
-                        // emitted `inference:completed` BEFORE calling `agent.reset()`,
-                        // so synchronous listeners observed status === 'streaming' at
-                        // the trace boundary. The gate failed silently and the promise
-                        // hung forever — every production zombie subagent originated
-                        // here. The reset+emit order has been fixed in driveStream's
-                        // `case 'complete'` handler; the gate is dropped here as
-                        // belt-and-suspenders.
-                        cleanup();
-                        resolve({ speech, toolCallsCount });
-                        break;
-                    }
-                    case 'inference:turn_ended': {
-                        // endTurn from a tool result — agent is done
-                        cleanup();
-                        resolve({ speech, toolCallsCount });
-                        break;
-                    }
-                    case 'inference:exhausted': {
-                        // Retries exhausted — reject only after the error policy gives up.
-                        // Earlier inference:failed events are left alone so the framework
-                        // retry path in driveStream/startAgentStream can restart the stream
-                        // while this listener stays alive.
-                        const error = event.error ?? 'Unknown error';
-                        cleanup();
-                        reject(new Error(error));
-                        break;
-                    }
-                }
-            };
-            this.onTrace(traceListener);
-            // Trigger inference
+            }, IDLE_POLL_MS);
+        });
+        try {
+            // Trigger inference after the settle promise is registered.
             this.pendingRequests.push({
                 agentName: agent.name,
                 reason: 'ephemeral',
                 source: 'subagent',
                 timestamp: Date.now(),
             });
-        });
+            const result = await Promise.race([
+                run.settle.promise,
+                startupTimeout,
+                completionIdleTimeout,
+            ]);
+            return { speech: result.speech, toolCallsCount: result.toolCallsCount };
+        }
+        finally {
+            if (startupWatchdog)
+                clearTimeout(startupWatchdog);
+            if (completionWatchdog)
+                clearInterval(completionWatchdog);
+            this.ephemeralRuns.delete(agent.name);
+            this.agents.delete(agent.name);
+            // Spawn-and-dispose bookkeeping (main, d453165/fee96a7): without this,
+            // ephemeral agents leave checkpoint-tree keys and diagnostics map
+            // entries behind for the life of the store/session.
+            this.evictTurnCheckpoints(agent.name);
+        }
     }
     /**
      * Get queue depth.
@@ -1233,6 +1323,29 @@ export class AgentFramework {
             'tagsAll / tagsNone) or in gate.js.',
         inputSchema: { type: 'object' },
     };
+    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, and transition pace; 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.' },
+                settings: {
+                    type: 'array',
+                    items: { type: 'string', enum: ['context_budget_tokens', 'tail_tokens', 'transition_pace_tokens'] },
+                    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 = {
@@ -2150,6 +2263,9 @@ 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(restoredSettings);
         this.agents.set(config.name, agent);
         this.agentConfigs.set(config.name, config);
         // First non-ephemeral agent becomes the primary for message routing
@@ -2196,6 +2312,9 @@ export class AgentFramework {
         // messages between tool_use and tool_result, causing a 400 error.
         if (event.type === 'tool-result') {
             const agent = this.agents.get(event.agentName);
+            if (agent) {
+                this.touchEphemeralRun(event.agentName, true);
+            }
             if (!agent) {
                 console.warn(`[framework] Dropping tool-result for unknown agent '${event.agentName}' (callId=${event.callId}). ` +
                     `Agent may have been destroyed while tool was executing.`);
@@ -2239,16 +2358,49 @@ 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 } : {}),
+                                    });
+                                }
+                            }
                         }
                     }
                     // Check if any tool result requested endTurn
@@ -2260,13 +2412,29 @@ export class AgentFramework {
                     if (shouldEndTurn) {
                         // endTurn: messages already stored above, cancel stream, reset to idle.
                         if (currentState.stream) {
-                            agent.cancelStream();
+                            this.frameworkCancelledStreams.set(`${agent.name}:${agent.streamId}`, 'turn_ended');
+                            currentState.stream.cancel();
                         }
                         agent.reset();
+                        // The turn is over — release the gate here, not just in the abort
+                        // handler: the membrane's aborted event is asynchronous and the
+                        // agent must be wakeable the moment it goes idle. (Idempotent;
+                        // driveStream's finally is the backstop.)
+                        this.eventGate?.onInferenceEnded(agent.name);
+                        this.settleAgent(agent.name, { stopReason: 'turn_ended', speech: '' });
                         this.emitTrace({ type: 'inference:turn_ended', agentName: agent.name });
                     }
                     else if (overBudget) {
-                        // Context budget exceeded: break the stream, let compile() compress
+                        // Context budget exceeded: break the stream, let compile() compress.
+                        // Mark the cancel as framework-initiated BEFORE cancelling: the
+                        // membrane delivers `aborted` before the restart bumps streamId,
+                        // and without the marker the abort handler treats the restart as
+                        // a terminal failure — rejecting an ephemeral's promise mid-run
+                        // and emitting a spurious inference:exhausted (same race shape as
+                        // endTurn above).
+                        if (currentState.stream) {
+                            this.frameworkCancelledStreams.set(`${agent.name}:${agent.streamId}`, 'budget_restart');
+                        }
                         agent.cancelStream();
                         this.emitTrace({
                             type: 'inference:stream_restarted',
@@ -2283,11 +2451,18 @@ export class AgentFramework {
                         });
                     }
                     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
@@ -2665,6 +2840,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,
@@ -2672,17 +2851,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
@@ -2825,6 +3023,7 @@ export class AgentFramework {
         else {
             this.activeTriggerChannels.delete(agent.name);
         }
+        this.touchEphemeralRun(agent.name, true);
         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() });
@@ -2880,17 +3079,23 @@ export class AgentFramework {
                 await this.startAgentStream(agent, trigger, attempt + 1);
             }
             else {
+                this.settleAgent(agent.name, {
+                    stopReason: 'exhausted',
+                    speech: '',
+                    error: err.message,
+                });
                 this.emitTrace({
                     type: 'inference:exhausted',
                     agentName: agent.name,
                     error: err.message,
-                    // Drives the poison-history breaker. `retryable` is kept for
-                    // observability, but the breaker gates on `errorType` — only an
-                    // `invalid_request` (a 400-class rejection of the history itself)
-                    // means retrying the same context can never succeed. auth/abort/
-                    // context_length are also non-retryable but must NOT cost history.
-                    retryable: err instanceof MembraneError ? err.retryable : undefined,
-                    errorType: err instanceof MembraneError ? err.type : undefined,
+                    // Drives the poison-history breaker (`invalid_request`: a 400-class
+                    // rejection of the history itself — retrying the same context can
+                    // never succeed; auth/abort/context_length are also non-retryable
+                    // but must NOT cost history) and the OverBudget drain breaker
+                    // (`over_budget`: compile refused to fit the hard budget — this is
+                    // the site that sees it, since compile runs before the stream
+                    // exists). `retryable` is kept for observability.
+                    ...this.classifyInferenceError(err),
                 });
                 this.eventGate?.onInferenceEnded(agent.name);
                 if (action.emit) {
@@ -2904,15 +3109,69 @@ export class AgentFramework {
         const requestId = `${agent.name}-${startTime}-${Math.random().toString(36).slice(2, 8)}`;
         const myStreamId = agent.streamId;
         let hadToolCalls = false;
+        // ---- Present-while-acting turn state ---------------------------------
+        // Output locus for THIS turn: resolved lazily at the first routed prose
+        // segment and pinned for the rest of the turn (mid-turn rounds AND the
+        // trailing prose at 'complete'), so one turn's voice stays in one channel
+        // even when a queued inbound from another channel overwrites the
+        // per-agent triggering channel between segments (PR #32). The pin lives
+        // in `turnLocusPins` so it survives a context-budget stream restart. A
+        // null resolution is NOT pinned — a turn whose locus is unresolvable
+        // early (e.g. heartbeat-triggered) may still resolve a channel by the
+        // time later prose routes.
+        if (trigger?.reason !== 'context_budget_restart') {
+            this.turnLocusPins.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 silencing: once any round uses a SILENCING_TOOLS member,
+        // prose from that round ONWARD is suppressed — skip_reply means "stay
+        // silent", an explicit send means "I deliver my own words". Earlier
+        // rounds' prose was already delivered live and cannot be retracted.
+        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();
+        const typingChannel = this.channelRegistry
+            ? trigger?.channelId ?? this.channelRegistry.getDefaultPublishChannel()
+            : null;
         if (typingChannel)
             this.channelRegistry.startTyping(typingChannel);
         try {
             for await (const event of stream) {
+                this.touchEphemeralRun(agent.name, true);
                 switch (event.type) {
                     case 'tokens':
                         this.emitTrace({
@@ -2936,6 +3195,7 @@ export class AgentFramework {
                     }
                     case 'tool-calls': {
                         hadToolCalls = true;
+                        this.recordEphemeralToolCalls(agent.name, event.calls.length);
                         this.emitTrace({
                             type: 'inference:tool_calls_yielded',
                             agentName: agent.name,
@@ -2972,6 +3232,39 @@ export class AgentFramework {
                         for (const call of event.calls) {
                             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);
+                            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 {
+                                        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;
                     }
@@ -3021,14 +3314,16 @@ export class AgentFramework {
                         // 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) {
-                            const trailingContent = response.content.slice(lastToolIdx + 1);
-                            if (trailingContent.length > 0) {
-                                agent.addAssistantResponse(trailingContent);
+                            if (terminalContent.length > 0) {
+                                agent.addAssistantResponse(terminalContent);
                             }
                         }
                         else {
-                            agent.addAssistantResponse(response.content);
+                            agent.addAssistantResponse(terminalContent);
                         }
                         // Run afterInference hooks (no-op if no MCPL servers)
                         if (this.hookOrchestrator) {
@@ -3063,10 +3358,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;
@@ -3080,17 +3378,20 @@ export class AgentFramework {
                                 cacheRead: du.cacheReadTokens,
                             }
                             : undefined;
-                        // Reset agent state BEFORE emitting inference:completed so that
-                        // synchronous listeners (e.g. runEphemeralToCompletion) observe
-                        // status === 'idle' the moment the event fires. Previously
-                        // agent.reset() ran after `await dispatchSpeech`, which meant the
-                        // ephemeral-completion listener saw status === 'streaming' at the
-                        // trace boundary, failed its idle gate, and the promise hung
-                        // forever — every "zombie subagent" in production tracked back
-                        // here. Speech dispatch happens after but doesn't depend on the
-                        // status field.
+                        // 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.
+                        // Speech dispatch happens after but doesn't depend on the status
+                        // field.
                         agent.reset();
                         this.eventGate?.onInferenceEnded(agent.name);
+                        this.settleAgent(agent.name, {
+                            stopReason: 'completed',
+                            speech: terminalContent
+                                .filter((block) => block.type === 'text')
+                                .map((block) => block.text)
+                                .join('\n'),
+                        });
                         this.emitTrace({
                             type: 'inference:completed',
                             agentName: agent.name,
@@ -3235,65 +3536,48 @@ 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.
+                            //
+                            // Silencing here is the sticky flag ∪ turn-wide scan: the scan
+                            // (over the whole turn's tool_use blocks) covers the fallback
+                            // path and the "send_message then a 'sent it.' postscript"
+                            // double-post guard; the sticky flag is its live-rounds twin.
                             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 = 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);
@@ -3301,9 +3585,8 @@ export class AgentFramework {
                                 }
                             }
                         }
-                        // NOTE: agent.reset() + onInferenceEnded() already ran above, BEFORE
-                        // dispatchSpeech (main's zombie-subagent fix, PR #32 — sync listeners
-                        // must see status === 'idle'). Locus routing is speech dispatch and
+                        // NOTE: agent.reset() + onInferenceEnded() already ran above,
+                        // BEFORE dispatchSpeech. Locus routing is speech dispatch and
                         // doesn't depend on the status field, so it correctly runs after.
                         break;
                     }
@@ -3335,16 +3618,20 @@ export class AgentFramework {
                             await this.startAgentStream(agent, trigger, attempt + 1);
                         }
                         else {
+                            this.settleAgent(agent.name, {
+                                stopReason: 'exhausted',
+                                speech: '',
+                                error: err.message,
+                            });
                             this.emitTrace({
                                 type: 'inference:exhausted',
                                 agentName: agent.name,
                                 error: err.message,
                                 // Drives the poison-history breaker. `retryable` is kept for
-                                // observability, but the breaker gates on `errorType` — only an
+                                // observability, but the breakers gate on `errorType` — only an
                                 // `invalid_request` (a 400-class rejection of the history
                                 // itself) means retrying the same context can never succeed.
-                                retryable: err instanceof MembraneError ? err.retryable : undefined,
-                                errorType: err instanceof MembraneError ? err.type : undefined,
+                                ...this.classifyInferenceError(err),
                             });
                             this.eventGate?.onInferenceEnded(agent.name);
                             if (action.emit) {
@@ -3354,12 +3641,28 @@ export class AgentFramework {
                         break;
                     }
                     case 'aborted': {
+                        // Framework-initiated, non-terminal cancels (endTurn tool result,
+                        // context-budget restart) also surface here as `aborted` — but
+                        // the turn either already settled (endTurn) or a replacement
+                        // stream is queued (budget restart). Neither is a failure: no
+                        // reset, no settle, no spurious inference:exhausted (which would
+                        // 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}`)) {
+                            this.eventGate?.onInferenceEnded(agent.name);
+                            return;
+                        }
                         const reason = event.reason ?? 'unknown';
                         // Only reset if this is still the active stream (a budget restart
                         // may have already started a new stream, bumping streamId)
                         if (agent.streamId === myStreamId) {
                             const durationMs = Date.now() - startTime;
                             agent.reset();
+                            this.settleAgent(agent.name, {
+                                stopReason: 'exhausted',
+                                speech: '',
+                                error: `Stream aborted: ${reason}`,
+                            });
                             this.emitTrace({
                                 type: 'inference:exhausted',
                                 agentName: agent.name,
@@ -3429,10 +3732,16 @@ export class AgentFramework {
                 error: err.message,
                 stack: err.stack,
             });
+            this.settleAgent(agent.name, {
+                stopReason: 'exhausted',
+                speech: '',
+                error: err.message,
+            });
             this.emitTrace({
                 type: 'inference:exhausted',
                 agentName: agent.name,
                 error: err.message,
+                ...this.classifyInferenceError(err),
             });
             // Postmortem 2026-05-28 P2 #7: catch-path failures (stream itself
             // threw) were previously only visible via in-memory trace listeners.
@@ -3462,6 +3771,7 @@ export class AgentFramework {
             // Stop the typing indicator on every exit path (complete, error,
             // exhausted, abort) so it never sticks after the turn ends.
             this.channelRegistry?.stopTyping();
+            this.frameworkCancelledStreams.delete(`${agent.name}:${myStreamId}`);
             this.activeStreams.delete(agent.name);
             this.pendingAssistantBlocks.delete(agent.name);
             // A conversation fork whose TTL closure turn just finished is done for
@@ -3665,6 +3975,11 @@ 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;
+        }
         // Route gate_status tool
         if (enrichedCall.name === 'gate_status' && this.eventGate) {
             this.dispatchGateToolCall(agentName, enrichedCall);
@@ -3765,12 +4080,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);
     }
@@ -3979,6 +4301,27 @@ export class AgentFramework {
         }
         return streak;
     }
+    /**
+     * Classify a terminal inference error for the `inference:exhausted` trace.
+     * Single-sourced for every emit site: the downstream breakers (poison-history
+     * quarantine, OverBudget drain kick) gate on `errorType`, so classification
+     * drift between sites would silently disable a safety net.
+     *
+     * context-manager's OverBudgetError is recognized by `err.name`: CM does not
+     * export the class from its package root, so a cross-package `instanceof` is
+     * unavailable — but `name` is set in its constructor and survives the package
+     * boundary. Deliberately NOT a message match: the message wording belongs to
+     * CM and can be reworded without warning.
+     */
+    classifyInferenceError(err) {
+        if (err instanceof MembraneError) {
+            return { retryable: err.retryable, errorType: err.type };
+        }
+        if (err.name === 'OverBudgetError') {
+            return { errorType: 'over_budget' };
+        }
+        return {};
+    }
     noteInferenceExhausted(agentName, reason, retryable, errorType) {
         const streak = (this.consecutiveInferenceFailures.get(agentName) ?? 0) + 1;
         this.consecutiveInferenceFailures.set(agentName, streak);
@@ -4006,6 +4349,42 @@ export class AgentFramework {
                 console.error(`[inference-failed] could not record chronicle marker for ${agentName}:`, err);
             }
         }
+        // (2b) OverBudget deadlock breaker. When compile fails with
+        // OverBudgetError, the normal compression drain never runs: it is driven
+        // by successful activity, which the over-budget state prevents - a closed
+        // loop with no internal exit. Field data (2026-07-10, resident agent):
+        // 36 minutes hard-down, zero self-rescue; only an operator raising the
+        // budget externally could break the loop. Break it here instead: kick the
+        // strategy drain directly so folding/merging frees space for the next
+        // compile. Bounded ticks, best-effort, never throws, one kick per agent
+        // at a time (see overBudgetDrainInFlight).
+        //
+        // Gates on the classified errorType (see classifyInferenceError); the
+        // message match is only a fallback for paths that lost the Error object
+        // (e.g. a reason string that crossed a serialization boundary). It matches
+        // CM's current OverBudgetError wording and MAY rot if CM rewords it — the
+        // errorType gate is the one that's load-bearing.
+        const overBudget = errorType === 'over_budget' || /exceed hard budget/i.test(reason);
+        if (agent && overBudget && !this.overBudgetDrainInFlight.has(agentName)) {
+            this.overBudgetDrainInFlight.add(agentName);
+            void (async () => {
+                let ticks = 0;
+                try {
+                    const cm = agent.getContextManager();
+                    while (ticks < 8) {
+                        await cm.tick();
+                        ticks++;
+                    }
+                    console.error(`[inference-failed] drain kicked for ${agentName} (OverBudget breaker, ${ticks} ticks)`);
+                }
+                catch (err) {
+                    console.error(`[inference-failed] drain kick failed for ${agentName} after ${ticks} ticks:`, err);
+                }
+                finally {
+                    this.overBudgetDrainInFlight.delete(agentName);
+                }
+            })();
+        }
         // (3) Hard-down escalation on repeated identical failure.
         if (streak >= this.inferenceFailureEscalationThreshold) {
             console.error(`[inference-hard-down] agent=${agentName} has FAILED ${streak} consecutive ` +
@@ -4101,6 +4480,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) {
@@ -4193,8 +4573,8 @@ 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
@@ -4900,6 +5280,84 @@ export class AgentFramework {
             endTurn: 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 ?? {});
+            switch (input.action) {
+                case 'get':
+                    result = { success: true, data: this.getAgentRuntimeSettings(agentName) };
+                    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);
+                    }
+                    result = { success: true, data: this.updateAgentRuntimeSettings(agentName, patch) };
+                    break;
+                }
+                case 'reset': {
+                    let keys;
+                    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',
+                        };
+                        keys = input.settings.map((name) => {
+                            if (typeof name !== 'string' || !names[name]) {
+                                throw new Error(`Unknown reset setting: ${String(name)}`);
+                            }
+                            return names[name];
+                        });
+                    }
+                    result = { success: true, data: this.resetAgentRuntimeSettings(agentName, keys) };
+                    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() {