@animalabs/agent-framework 0.6.3 → 0.6.5

package/dist/src/framework.js

@@ -21,6 +21,7 @@ import { CheckpointManager } from './mcpl/checkpoint-manager.js';
 import { isToolAllowed } from './mcpl/tool-policy.js';
 import { EventGate } from './gate/event-gate.js';
 import { UsageTracker } from './usage/usage-tracker.js';
+import { formatZonedDateTime, resolveTimeZone } from './timezone.js';
 const FRAMEWORK_STATE_ID = 'framework/state';
 const CONVERSATION_ROUTER_STATE_ID = 'framework/conversation-router';
 const INFERENCE_LOG_ID = 'framework/inference-log';
@@ -146,6 +147,17 @@ export class AgentFramework {
     processLoggingBroadcast;
     activeStreams = 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();
@@ -174,6 +186,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. */
@@ -234,7 +253,9 @@ export class AgentFramework {
     eventGate = null;
     // Session-level token usage tracking (always-on)
     usageTracker;
-    constructor(store, ownsStore, membrane, inferencePolicy, errorPolicy, syncIntervalMs, maintenanceIntervalMs, processLoggingPersist, processLoggingBroadcast) {
+    /** Presentation-only wall-clock zone; persistence remains UTC/epoch. */
+    timeZone;
+    constructor(store, ownsStore, membrane, inferencePolicy, errorPolicy, syncIntervalMs, maintenanceIntervalMs, processLoggingPersist, processLoggingBroadcast, timeZone) {
         this.store = store;
         this.ownsStore = ownsStore;
         this.membrane = membrane;
@@ -244,6 +265,7 @@ export class AgentFramework {
         this.maintenanceIntervalMs = maintenanceIntervalMs;
         this.processLoggingPersist = processLoggingPersist;
         this.processLoggingBroadcast = processLoggingBroadcast;
+        this.timeZone = timeZone;
         this.queue = new ProcessQueueImpl();
         this.usageTracker = new UsageTracker({
             emitTrace: (e) => this.emitTrace({ ...e }),
@@ -323,7 +345,7 @@ export class AgentFramework {
                 // Already registered
             }
         }
-        const framework = new AgentFramework(store, ownsStore, config.membrane, config.inferencePolicy ?? new DefaultInferencePolicy(), config.errorPolicy ?? new DefaultErrorPolicy(), config.syncIntervalMs ?? DEFAULT_SYNC_INTERVAL_MS, config.maintenanceIntervalMs ?? DEFAULT_MAINTENANCE_INTERVAL_MS, processLoggingPersist, processLoggingBroadcast);
+        const framework = new AgentFramework(store, ownsStore, config.membrane, config.inferencePolicy ?? new DefaultInferencePolicy(), config.errorPolicy ?? new DefaultErrorPolicy(), config.syncIntervalMs ?? DEFAULT_SYNC_INTERVAL_MS, config.maintenanceIntervalMs ?? DEFAULT_MAINTENANCE_INTERVAL_MS, processLoggingPersist, processLoggingBroadcast, resolveTimeZone(config.timeZone));
         // Restore persisted usage data (if any) from prior session
         framework.restoreUsageState();
         // Create agents
@@ -533,7 +555,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(() => {
@@ -584,6 +608,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;
@@ -930,6 +961,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.
      *
@@ -940,139 +1015,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.
@@ -2192,6 +2201,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.`);
@@ -2256,13 +2268,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',
@@ -2821,6 +2849,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() });
@@ -2876,17 +2905,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) {
@@ -2909,6 +2944,7 @@ export class AgentFramework {
             this.channelRegistry.startTyping(typingChannel);
         try {
             for await (const event of stream) {
+                this.touchEphemeralRun(agent.name, true);
                 switch (event.type) {
                     case 'tokens':
                         this.emitTrace({
@@ -2932,6 +2968,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,
@@ -3017,14 +3054,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) {
@@ -3076,17 +3115,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,
@@ -3297,9 +3339,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;
                     }
@@ -3331,16 +3372,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) {
@@ -3350,12 +3395,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,
@@ -3425,10 +3486,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.
@@ -3458,6 +3525,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
@@ -3975,6 +4043,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);
@@ -4002,6 +4091,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 ` +
@@ -4885,7 +5010,16 @@ export class AgentFramework {
         }
         console.error(`[sleep] agent=${agentName} seconds=${seconds} announce=${announce} until=${new Date(until).toISOString()}`);
         // endTurn: the agent stops here and goes idle for the duration.
-        finish({ success: true, data: { sleepingFor: human, until }, endTurn: true });
+        finish({
+            success: true,
+            data: {
+                sleepingFor: human,
+                until,
+                untilLocal: formatZonedDateTime(until, this.timeZone),
+                timeZone: this.timeZone,
+            },
+            endTurn: true,
+        });
     }
     /** Aggregate the event-tag vocabulary: reserved chat:* core + each connected
      *  server's declared tag ontology + gate.js status. */