fix: a turn whose compile is refused for budget waits for compression, then runs

changelog.d/budget-refusal-holds-turn.fixed.md

@@ -0,0 +1,65 @@
+- A turn whose compile is refused for budget waits for compression and then
+  runs, instead of ending (#304). The refusal comes before any provider call,
+  for example after an immediate budget decrease. Before, the error policy
+  retried it into the same refusal within seconds and ended the turn, and once
+  compression had made the context fit, nothing ran it again, so the agent
+  stayed silent until its next wake. Now a resident's or a conversation
+  agent's turn is held while its context manager has compression pending.
+  Later wakes join it. The hold leaves the provider gate open, so compression
+  keeps running. An ephemeral run, a turn in a framework that `start()`
+  hasn't started (only `runUntilIdle()` runs its turns, so nothing would run
+  a released one), and a refusal with nothing pending fail as before.
+  - **When it runs:** as one fresh compile, once context-manager's preview of
+    that compile says it fits. A dry compile can't say so, since it can
+    resolve a plan the turn's compile refuses. A refusal the preview rethrows,
+    such as a context refusal, counts as a refusal. A strategy with no preview
+    gets the dry compile. The hierarchical strategy's preview reports a
+    context that doesn't fit, and for one that does, the dry compile decides.
+    The hold looks after every maintenance pass, every drain kick it starts,
+    and every surgery, undo and redo. It takes a fresh verdict only once
+    something that could make the context fit has changed: compression's
+    progress or whether it still has compression pending, a message added,
+    edited or removed, the agent's runtime settings, or a surgery on the
+    store. A turn released and refused again is held again with its first
+    deadline, and isn't released again until one of those changes.
+  - **When it ends without a fit:** 30 minutes after the refusal that
+    started it, or at once when compression has nothing pending. The turn
+    then runs if its context fits by then, and otherwise fails as a refused
+    compile did, its reason saying when it was first held. The 30 minutes
+    also bound a compression that is pending but doesn't move. The hold lives
+    in memory: a restart drops it, and the agent's next wake compiles afresh.
+  - **What the agent sees:** the held turn's compile carries a note saying
+    why it waited, for that compile alone: "[budget-hold] Your context didn't
+    fit its budget (100,201 tokens against 48,568), so this turn waited
+    7 min. It fits now." It's never stored. One held turn is one undo step,
+    which keeps the messages that arrived while it waited. The refused start
+    gives back the checkpoint it recorded, with the oldest one it evicted at
+    the limit of 20, and the redo its new work invalidated stays invalidated,
+    as at any turn's first start. An undo while a turn is held rewinds past
+    that turn's messages, and the held turn then runs on what the undo left
+    (#381 is that for every pending wake).
+  - **What hosts see:** the refused attempt emits `inference:failed`, and the
+    turn's next start emits `inference:started` again. The turn's terminal
+    event comes when the held turn ends, after a hold of up to 30 minutes,
+    rather than as an exhaustion within seconds. New traces `inference:held`
+    and `inference:hold_ended`, and `healthSnapshot()` gives each agent's
+    `budgetHold` (or null). The `context-refusal` ops alert goes out when the
+    hold starts (its `ops:alert` trace each time, its webhook post at most
+    once per 15 minutes for an agent), and says the turn is held until its
+    deadline. A hold's drain kicks log as `[budget-hold]`. While the host is
+    quiesced, a turn a hold releases waits for resume as a parked wake does,
+    a continuation included, whether it's still queued or already waiting
+    on provider admission, so no such turn starts while the host is
+    quiesced. `getHostModeStatus()` counts it among `gatedRequests`, and its
+    new `heldTurns` counts the turns still held, as quiesce's log line does.
+    A budget restart a hold releases waits, as a wake does, for a turn token
+    another holds, such as a puppeted tool call's.
+- A deferred batch's wake that waited behind a turn which then restarted for
+  its context budget was consumed by the restarted turn, which continues the
+  same logical turn and skips batch assembly, so the batch never rendered
+  until some later turn, or was dropped with it when the inference policy
+  declined the restart. It now stays queued, with its own policy decision,
+  and wakes a fresh turn of its own once the restarted turn ends. A wake
+  that joins a held continuation (above) is kept out of it the same way,
+  and a guard retry a hold releases is its turn's trigger wherever it was
+  queued, as a budget restart already was.

src/agent.ts

@@ -24,6 +24,9 @@ import {
   DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS,
 } from './tool-result-history.js';
 
+/** ContextManager.compile's own budget when it is given none. */
+const CONTEXT_MANAGER_DEFAULT_BUDGET: TokenBudget = { maxTokens: 100_000, reserveForResponse: 4_000 };
+
 export interface ActivationRequestOptions {
   /** The silent heartbeat tick this request answers, if any. */
   silentHeartbeat?: SilentHeartbeatTick;
@@ -384,11 +387,17 @@ export class Agent {
     const resolved = this.resolveBudget(budget);
     const reserve = this.toolResultGuard.pendingWireReserveTokens;
     if (reserve === 0) return resolved;
-    // Mirrors ContextManager.compile's own default when no budget is set.
-    const base = resolved ?? { maxTokens: 100_000, reserveForResponse: 4_000 };
+    const base = resolved ?? CONTEXT_MANAGER_DEFAULT_BUDGET;
     return { ...base, reserveForResponse: base.reserveForResponse + reserve };
   }
 
+  /** The budget the agent's next compile plans at (compileBudget), for a
+   *  preview of that compile: context-manager's own default when the agent
+   *  sets none, as its compile then gets. */
+  nextCompileBudget(): TokenBudget {
+    return this.compileBudget(undefined) ?? CONTEXT_MANAGER_DEFAULT_BUDGET;
+  }
+
   /** Structural compatibility keeps lightweight test/host ContextManager
    * doubles working while making the new capability optional at runtime. */
   private getHotContextSettings(): HotContextSettingsStatus | null {