@animalabs/agent-framework 0.6.4 → 0.6.5

package/src/framework.ts

@@ -32,6 +32,7 @@ import type {
   ProcessEvent,
   EventResponse,
   ModuleProcessResponse,
+  AgentSettleResult,
   ToolCall,
   ToolCallEvent,
   ToolResult,
@@ -229,6 +230,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. */
@@ -275,6 +293,17 @@ export class AgentFramework {
   private processLoggingBroadcast: boolean;
   private activeStreams: Map<string, Promise<void>> = 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 +332,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 +768,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 +832,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();
@@ -1177,6 +1232,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 +1293,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 +1325,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);
+    }
   }
 
   /**
@@ -2619,6 +2655,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}). ` +
@@ -2693,12 +2732,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',
@@ -3364,6 +3419,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 +3484,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) {
@@ -3469,6 +3531,7 @@ export class AgentFramework {
 
     try {
       for await (const event of stream) {
+        this.touchEphemeralRun(agent.name, true);
         switch (event.type) {
           case 'tokens':
             this.emitTrace({
@@ -3494,6 +3557,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,
@@ -3593,13 +3657,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)
@@ -3658,17 +3724,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',
@@ -3907,9 +3976,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;
@@ -3945,16 +4013,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 +4037,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 +4134,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 +4173,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);
 
@@ -4667,6 +4762,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 +4824,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(

package/src/types/framework.ts

@@ -181,6 +181,16 @@ export type ErrorAction =
   | { retry: true; delayMs: number }
   | { retry: false; emit?: ProcessEvent };
 
+/**
+ * Terminal result for a framework-driven ephemeral agent run.
+ */
+export interface AgentSettleResult {
+  stopReason: 'completed' | 'turn_ended' | 'exhausted';
+  speech: string;
+  toolCallsCount: number;
+  error?: string;
+}
+
 /**
  * Framework state exposed to policies.
  */