@animalabs/agent-framework 0.6.4 → 0.6.6

package/src/framework.ts

@@ -32,6 +32,7 @@ import type {
   ProcessEvent,
   EventResponse,
   ModuleProcessResponse,
+  AgentSettleResult,
   ToolCall,
   ToolCallEvent,
   ToolResult,
@@ -43,6 +44,9 @@ import type {
   ContextMaintenanceRun,
   ContextMaintenanceAgentRun,
   ContextMaintenanceSnapshot,
+  AgentRuntimeSettingsPatch,
+  AgentRuntimeSettingsOverrides,
+  AgentRuntimeSettingsSnapshot,
 } from './types/index.js';
 import { ProcessQueueImpl } from './queue.js';
 import { Agent } from './agent.js';
@@ -58,6 +62,30 @@ 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: string): string => n.split('--').pop()!;
 import { CheckpointManager } from './mcpl/checkpoint-manager.js';
 import { isToolAllowed } from './mcpl/tool-policy.js';
 import { EventGate } from './gate/event-gate.js';
@@ -229,6 +257,23 @@ interface RewindRecord {
   discordRef?: { channelId: string; messageId: string };
 }
 
+interface Deferred<T> {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: (reason?: unknown) => void;
+}
+
+/** Per-run state for a framework-driven ephemeral agent: the settle signal
+ *  the caller awaits plus the liveness/progress bookkeeping the watchdogs and
+ *  the stream driver share. One map entry per run — created and torn down in
+ *  runEphemeralToCompletion — so the pieces cannot desync. */
+interface EphemeralRun {
+  settle: Deferred<AgentSettleResult>;
+  inferenceStarted: boolean;
+  lastActivity: number;
+  toolCallsCount: number;
+}
+
 /** Cap an API error message for inline use in a rewind marker: keep enough to
  *  identify the failure class without pasting a wall of provider JSON into the
  *  agent's context. */
@@ -274,7 +319,25 @@ export class AgentFramework {
   private processLoggingPersist: boolean;
   private processLoggingBroadcast: boolean;
   private activeStreams: Map<string, Promise<void>> = 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. */
+  private turnLocusPins: Map<string, string> = new Map();
   private pendingAssistantBlocks: Map<string, ContentBlock[]> = 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. */
+  private frameworkCancelledStreams: Map<string, 'turn_ended' | 'budget_restart'> = new Map();
+  /** Active runEphemeralToCompletion runs, keyed by agent name. */
+  private ephemeralRuns: Map<string, EphemeralRun> = new Map();
   /** Per-agent count of consecutive exhausted inferences (reset on any success).
    *  Drives hard-down escalation — see noteInferenceExhausted. */
   private consecutiveInferenceFailures: Map<string, number> = new Map();
@@ -303,6 +366,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. */
   private exhaustionRewinds: Map<string, number> = 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). */
+  private overBudgetDrainInFlight: Set<string> = 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. */
@@ -732,9 +802,16 @@ export class AgentFramework {
   private startQueuedMaintenance(): void {
     if (this.maintenancePass || !this.running) return;
     const pass = this.runQueuedMaintenance().catch((error) => {
+      const reason = error instanceof Error ? error.message : String(error);
       console.error(
         '[context-maintenance] pass failed:',
-        error instanceof Error ? error.message : error,
+        reason,
+      );
+      this.opsAlert(
+        'context-maintenance-failed',
+        'framework',
+        reason,
+        { data: { scope: 'pass' } },
       );
     });
     this.maintenancePass = pass;
@@ -789,6 +866,18 @@ 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;
           record.finishedAt = Date.now();
@@ -934,10 +1023,49 @@ 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: string): AgentRuntimeSettingsSnapshot {
+    const agent = this.agents.get(agentName);
+    if (!agent) throw new Error(`Unknown agent: ${agentName}`);
+    return agent.getRuntimeSettings();
+  }
+
+  updateAgentRuntimeSettings(
+    agentName: string,
+    patch: AgentRuntimeSettingsPatch,
+  ): AgentRuntimeSettingsSnapshot {
+    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: string,
+    keys?: Array<keyof AgentRuntimeSettingsPatch>,
+  ): AgentRuntimeSettingsSnapshot {
+    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: string): AgentRuntimeSettingsSnapshot {
+    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. */
@@ -1139,6 +1267,33 @@ export class AgentFramework {
     }
   }
 
+  private readAgentRuntimeSettings(agentName: string): AgentRuntimeSettingsOverrides | null {
+    try {
+      const data = this.store.getStateJson(FRAMEWORK_STATE_ID) as {
+        agentRuntimeSettings?: Record<string, AgentRuntimeSettingsOverrides>;
+      } | null;
+      const stored = data?.agentRuntimeSettings?.[agentName];
+      return stored ? { ...stored } : null;
+    } catch {
+      return null;
+    }
+  }
+
+  private persistAgentRuntimeSettings(
+    agentName: string,
+    overrides: AgentRuntimeSettingsOverrides,
+  ): void {
+    const data = this.store.getStateJson(FRAMEWORK_STATE_ID);
+    const state = (data && typeof data === 'object' ? data : {}) as Record<string, unknown>;
+    const all = {
+      ...((state.agentRuntimeSettings as Record<string, AgentRuntimeSettingsOverrides> | undefined) ?? {}),
+    };
+    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.
    *
@@ -1177,6 +1332,54 @@ export class AgentFramework {
     return { agent, contextManager, cleanup };
   }
 
+  private createDeferred<T>(): Deferred<T> {
+    let resolve!: (value: T) => void;
+    let reject!: (reason?: unknown) => void;
+    const promise = new Promise<T>((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    return { promise, resolve, reject };
+  }
+
+  /** Liveness ping for an active ephemeral run (no-op otherwise). */
+  private touchEphemeralRun(agentName: string, inferenceStarted = false): void {
+    const run = this.ephemeralRuns.get(agentName);
+    if (!run) return;
+    if (inferenceStarted) {
+      run.inferenceStarted = true;
+    }
+    run.lastActivity = Date.now();
+  }
+
+  private recordEphemeralToolCalls(agentName: string, count: number): void {
+    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. */
+  private settleAgent(
+    agentName: string,
+    outcome: { stopReason: AgentSettleResult['stopReason']; speech: string; error?: string },
+  ): void {
+    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.
    *
@@ -1190,42 +1393,31 @@ export class AgentFramework {
   async runEphemeralToCompletion(
     agent: Agent,
     contextManager: ContextManager,
+    watchdogs?: { startupTimeoutMs?: number; idleTimeoutMs?: number; idlePollMs?: number },
   ): Promise<{ speech: string; toolCallsCount: number }> {
     // Register temporarily so the event loop can drive it
     this.agents.set(agent.name, agent);
+    const run: EphemeralRun = {
+      settle: this.createDeferred<AgentSettleResult>(),
+      inferenceStarted: false,
+      lastActivity: Date.now(),
+      toolCallsCount: 0,
+    };
+    this.ephemeralRuns.set(agent.name, run);
 
-    return new Promise<{ speech: string; toolCallsCount: number }>((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);
-      };
+    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;
 
-      // 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();
+    let startupWatchdog: ReturnType<typeof setTimeout> | null = null;
+    let completionWatchdog: ReturnType<typeof setInterval> | null = null;
+
+    const startupTimeout = new Promise<never>((_, 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 ` +
@@ -1233,104 +1425,48 @@ export class AgentFramework {
           ));
         }
       }, 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) return;
-        const idle = Date.now() - lastActivity;
+    const completionIdleTimeout = new Promise<never>((_, reject) => {
+      completionWatchdog = setInterval(() => {
+        if (!run.inferenceStarted) return;
+        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 ` +
+            `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: TraceEvent) => {
-        if (settled) return;
-        // Only track events for our ephemeral agent
-        const agentName = 'agentName' in event ? (event as { agentName: string }).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 as { content?: string }).content;
-            if (content) speech += content;
-            break;
-          }
-          case 'inference:tool_calls_yielded': {
-            const calls = (event as { calls?: Array<unknown> }).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 as { error?: string }).error ?? 'Unknown error';
-            cleanup();
-            reject(new Error(error));
-            break;
-          }
-        }
-      };
-
-      this.onTrace(traceListener);
+      }, IDLE_POLL_MS);
+    });
 
-      // Trigger inference
+    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);
+    }
   }
 
   /**
@@ -1497,6 +1633,31 @@ export class AgentFramework {
     inputSchema: { type: 'object' },
   };
 
+  private static readonly AGENT_SETTINGS_TOOL: import('./types/index.js').ToolDefinition = {
+    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. */
   private static readonly CHAT_CORE_TAGS: Record<string, string> = {
@@ -2565,6 +2726,8 @@ export class AgentFramework {
     });
 
     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);
 
@@ -2619,6 +2782,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}). ` +
@@ -2669,16 +2835,51 @@ export class AgentFramework {
           }));
           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: Array<{ participant: string; content: ContentBlock[]; metadata?: MessageMetadata }> = [];
           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 } : {}),
+                  });
+                }
+              }
             }
           }
 
@@ -2693,12 +2894,28 @@ 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',
@@ -2714,13 +2931,23 @@ export class AgentFramework {
               timestamp: Date.now(),
             });
           } 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
             this.pendingRequests.push({
@@ -3174,6 +3401,15 @@ export class AgentFramework {
    * Convert an MCPL push event to a context message.
    */
   private handleMcplPushEvent(event: McplPushEvent): void {
+    const triggerChannel = this.derivePushEventChannel(event.origin);
+    if (triggerChannel && this.channelRegistry) {
+      this.channelRegistry.ensureChannelRegistered(
+        event.serverId,
+        triggerChannel.channelId,
+        triggerChannel.label,
+      );
+    }
+
     const metadata: Record<string, unknown> = {
       ...event.origin,
       serverId: event.serverId,
@@ -3182,23 +3418,39 @@ export class AgentFramework {
       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
@@ -3364,6 +3616,7 @@ export class AgentFramework {
       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() });
@@ -3428,17 +3681,23 @@ export class AgentFramework {
         await new Promise((resolve) => setTimeout(resolve, action.delayMs));
         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) {
@@ -3460,15 +3719,72 @@ export class AgentFramework {
     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 = (): string | null => {
+      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<void> = Promise.resolve();
+    const enqueueSpeech = (text: string, locus: string | null): void => {
+      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({
@@ -3494,6 +3810,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,
@@ -3535,6 +3852,43 @@ 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;
           }
@@ -3593,13 +3947,15 @@ export class AgentFramework {
                 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)
@@ -3637,10 +3993,13 @@ export class AgentFramework {
               }
             }
 
-            // 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: ContentBlock): block is ContentBlock & { type: 'text' } =>
               block.type === 'text';
             const allText = response.content.filter(isTextBlock);
@@ -3658,17 +4017,20 @@ export class AgentFramework {
                 }
               : 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: ContentBlock): block is ContentBlock & { type: 'text' } => block.type === 'text')
+                .map((block) => block.text)
+                .join('\n'),
+            });
 
             this.emitTrace({
               type: 'inference:completed',
@@ -3837,79 +4199,62 @@ 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: string) => (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 as unknown as { name?: string }).name)
                 .filter((n): n is string => 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'})`,
+                  `[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);
+                // 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} prose segment(s) in order -> ${turnLocus ?? '(default)'}`,
+                  `[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);
                   }
                 }
               }
             }
-            // 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;
@@ -3945,16 +4290,20 @@ export class AgentFramework {
               await new Promise((resolve) => setTimeout(resolve, action.delayMs));
               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) {
@@ -3965,12 +4314,28 @@ export class AgentFramework {
           }
 
           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,
@@ -4046,10 +4411,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.
@@ -4079,6 +4450,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);
 
@@ -4298,6 +4670,12 @@ export class AgentFramework {
       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);
@@ -4416,12 +4794,19 @@ export class AgentFramework {
       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 '' as MessageId; // Deferred — will be added after tool_result flush
+      return '' as MessageId; // Deferred — flushed at the next boundary
     }
 
     return agent.getContextManager().addMessage(participant, content, metadata);
@@ -4667,6 +5052,28 @@ 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.
+   */
+  private classifyInferenceError(err: Error): { retryable?: boolean; errorType?: string } {
+    if (err instanceof MembraneError) {
+      return { retryable: err.retryable, errorType: err.type };
+    }
+    if (err.name === 'OverBudgetError') {
+      return { errorType: 'over_budget' };
+    }
+    return {};
+  }
+
   private noteInferenceExhausted(
     agentName: string,
     reason: string,
@@ -4707,6 +5114,41 @@ export class AgentFramework {
       }
     }
 
+    // (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(
@@ -4852,6 +5294,7 @@ export class AgentFramework {
       (event) => this.pushEvent(event),
       (event) => this.emitTrace(event as { type: TraceEvent['type']; [key: string]: unknown }),
       {
+        store: this.store,
         sendTypingFn: (serverId, channelId, metadata, op) => {
           const server = this.mcplServerRegistry!.getServer(serverId);
           if (server) {
@@ -4956,8 +5399,11 @@ export class AgentFramework {
 
     // 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);
@@ -5782,6 +6228,88 @@ export class AgentFramework {
     });
   }
 
+  private dispatchAgentSettingsToolCall(agentName: string, call: ToolCall): void {
+    this.emitTrace({
+      type: 'tool:started',
+      module: 'agent',
+      tool: call.name,
+      callId: call.id,
+      input: call.input,
+    });
+    let result: ToolResult;
+    try {
+      const input = (call.input ?? {}) as {
+        action?: unknown;
+        context_budget_tokens?: unknown;
+        tail_tokens?: unknown;
+        transition_pace_tokens?: unknown;
+        settings?: unknown;
+      };
+      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: AgentRuntimeSettingsPatch = {};
+          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: Array<keyof AgentRuntimeSettingsPatch> | undefined;
+          if (input.settings !== undefined) {
+            if (!Array.isArray(input.settings)) throw new Error('reset `settings` must be an array');
+            const names: Record<string, keyof AgentRuntimeSettingsPatch> = {
+              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. */
   private buildEventTagsResult(): Record<string, unknown> {