[nissa-seru]

A resident's or conversation agent's turn whose compile is refused for budget now waits while compression is pending, instead of failing within seconds. The waiting turn is alive, as a turn that a provider hold keeps for its retry has been since #774: the host reads it as not drained, a quiesce waits for it, and a branch switch, a rollback or an undo that would move the store is refused while it waits. Later wakes join it. It runs as one fresh compile once a check says the context fits: context-manager's preview, or the framework's dry compile where the strategy has no preview or its preview gives no verdict. After 30 minutes, or once compression has nothing pending, its refusals take the error policy's path as before.

!Fixes #304

Problem

A compile that can't fit its budget throws context-manager's OverBudgetError before any provider call.

• The retries: the default error policy retries it into the same refusal, and the turn ends as exhausted within seconds. At 0.28.0, in our run, that was three attempts and 3.4 s.
• The breaker: noteInferenceExhausted calls the over-budget breaker's drain kick, from Compile robustness: empty-text 400 sanitize + OverBudget deadlock breaker #58, and opsAlert with the kind context-refusal (src/framework.ts:28370–28417 at 59d609586e).
• Then nothing: in our run at 0.28.0, 3 s after the context fit, with no new message, nothing had called the provider. The agent waits for its next wake.

In #304's October 12 report (times in UTC), an immediate budget decrease led to activations refused at 21:00 and 21:01. Compression finished at 21:07, and there was no reply until the owner's next message.

Changes

Against e85c57db, the main this head merges, the change adds 492 lines to src/framework.ts and removes 74, adds 51 to src/types/trace.ts, and adds 11 to src/agent.ts and removes 2. It also adds two changelog fragments, a test file of 78 tests, and a row in test/stop-step-throws.test.ts.

A refused compile holds its turn (holdForBudgetRefusal, where a start's failure is handled, before the error policy and before a provider hold).

• When: the refusal is over_budget or context_refusal, the agent is a resident or a conversation agent, the framework is running, and its context manager has compression pending.
• One record per agent (BudgetHold), apart from the provider holds' records. The record's state is holding while the turn waits, released once its requests are queued for one fresh compile, and spent after its deadline or after a refusal with nothing pending.
• The hold keeps the turn's retry (TURN_RETRY), as a provider hold does since fix(scheduler): a turn a provider hold keeps for its retry is alive #774. So the turn is alive while it waits:
  • getHostModeStatus() reads drained: false and lists the agent in activeTurnAgents;
  • a quiesce lets the turn start once its hold ends, and finish;
  • a branch switch, a rollback and an undo that would move the store are refused (agent-busy), and so is puppetToolCall for the held agent; each refusal names the hold, its deadline and its reason. A redo and a suppression call the same reserveStoreForSurgery (src/framework.ts:13097, through beginSyncMove, and :13482);
  • a quiesce with abandon: true, abortInference(), stop() and a conversation agent's disposal end it, with one inference:aborted.
• Compression keeps running: the hold leaves the agent's provider gate open, so the maintenance loop keeps ticking the agent. In runQueuedMaintenance, the callback that lists each agent's work returns an empty list for an agent whose provider gate is closed (src/framework.ts:6997).
• The refused start ends before the hold is reported, so a stop made by a listener of inference:held or of the alert ends the held turn. A hold that a listener of inference:held ends this way isn't logged as held, and no alert is raised for it.
• Later wakes join it, for one compile, and count in gatedRequests. After an abandon or abortInference(), they go back to the queue. At stop() or a disposal, they go with the turn. A coalesced wake withdrawn while held leaves the hold.
• A hold adds no undo step.
  • When the refused start recorded a checkpoint, as a turn's first start does, the record keeps it. The start the hold releases then moves it to after the messages that arrived while the turn waited. It gives back the refused start's checkpoint and its turn index. Where recording that checkpoint evicted the oldest one, at the limit of 20, it restores that one too. Then it records the turn's own. The context injections the refused start stored stay before the moved checkpoint, as rows stored before any start do.
  • A hold that's stopped leaves the checkpoint where it is, so the stopped turn keeps its own undo step.
  • When a retry is refused, an error policy's or a tool-result guard's, the turn keeps the checkpoint its first start recorded, before the rounds it has run, and the released start records none. So an undo takes those rounds, and the messages that arrived while it waited too.
  • The redo its new work invalidated stays invalidated, as at any turn's first start.
• The drain kick runs when the hold starts, through kickOverBudgetDrain, which the breaker's kick now shares.

The release check (checkBudgetHold) takes context-manager's verdict on the turn's next compile: previewContext's fits, at the budget that compile plans at and with the agent's thinking binding.

• Why the preview: a dry compile can resolve a plan the turn's compile refuses (SelectOptions.dryRun). The preview reports such a plan as not fitting.
• A refusal the preview rethrows, such as a context refusal (UncoveredDropError), counts as a refusal. Any other error ends the hold (check_failed), and the turn's own compile meets it.
• A strategy with no preview gets a dry compile, and so does the hierarchical strategy for a context that fits, where its preview gives no verdict (context-manager 0.23.0 throws "requires adaptiveResolution", and 0.23.1 returns null). It's previewActivation's, which compiles with the thinking binding and its identity, as a turn's start does. The hold calls it with no options (src/framework.ts:6322), and its doc comment (:9808–9815) says such a call leaves out the module and MCPL injections a start gathers. Only one dry compile runs at a time. Its refusal counts only if nothing the check watches changed while it ran.
• When it looks: after every maintenance pass and every drain kick the hold starts. With the maintenance timer off, the hold kicks the drain and looks every 5 s, the timer's default interval, and while the provider gate is closed, it only looks.
• What it watches: compression's progress and whether it still has compression pending, a count of the store's changes (a message added, edited or removed, counted through context-manager's onMessage), the agent's runtime settings, and the budget its next compile plans at, reserves included. While a readable snapshot of these (budgetHoldSignature) is unchanged, the hold takes no new verdict. The arrival of a stored context injection or of a clock row isn't counted: a released turn's start stores its own injections, the note among them, and a clock row when a clock boundary has passed. The budget is in the snapshot because the tool-result guard's pending reserve can change it with no store event and no runtime setting moving.
• If it fits: the hold's requests go to the queue together, for one fresh compile. The hold's end is reported once they are queued, so a stop made by a listener of inference:hold_ended ends the turn.
• A released turn whose own compile still refuses holds again on the same record, with its first refusal's start and deadline, and isn't released again until something the check watches has changed.

The bound is a fixed 30 minutes from the refusal that started the hold (BUDGET_HOLD_MS). In #304, compression finished about 7 minutes after the first refusal. The bound also ends a hold whose compression stays pending without moving. There's no option and no stall rule, since the alert at the hold's start tells the operator, and the bound ends the wait.

When a hold ends without a fit, at its deadline or once compression has nothing pending, its requests go to the queue for one fresh compile. If the context fits by then, the turn runs. Otherwise its refusals take the error policy's path, as before this change. The policy gets each refusal itself, its message saying when the turn was first held and why the hold ended, for example "… (the turn was first held 30 min ago; the hold's 30 min bound passed and it still didn't fit)".

The note. The turn's next start once its hold ends, with a fit or without, adds a note as an afterUser context injection, which main stores since #782. storeInjections' doc comment (src/framework.ts:18979–18982) names two cases where nothing is stored and the compile places the injection instead: the host is quiesced, or another reader of the residents' shared slot has a turn alive. The note reads: "[budget-hold] Your context didn't fit its budget (100,201 tokens against 48,568), so this turn waited 7 min for compression to make room." It says only what happened, so it stays true whatever the compile then meets. It's stored before the compile the preview judged fit, so at the margin it can tip that compile into a refusal. The hold then holds the turn again until something it watches changes, and a turn released twice can carry two notes.

A restart drops a held turn, since the hold lives in memory. The messages stay in the store, and the agent's next wake compiles afresh.

Unchanged:

• An ephemeral run's refusal fails as before.
• A refusal in a framework that isn't running fails as before: one only runUntilIdle() drives, without start(), where nothing would run a released turn, and one whose stop() has begun.
• A refusal with nothing pending fails as before.
• noteInferenceExhausted still calls the breaker's drain kick at exhaustion (src/framework.ts:29174).

Left out:

• Persisting a hold across a restart. The held turn's messages stay in the store, and the next wake compiles afresh. A durable owed turn would be a contract for every kind of held work, not for this one alone.
• An option for the bound, and a stall rule (above).

Where we're less sure. On the fallback's path, the dry compile awaits, and compression can move while it runs. Its refusal counts only if the snapshot is unchanged when it ends, as far as the snapshot can be read. Two tests cover that check, and no removal of it was run.

Since 73def25e, the previous head

This head merges main at e85c57db into 73def25e. The merge's one conflict was where beginAgentTurn handles a terminal failure, and both sides' lines are kept there: the hold's settleBudgetHold call and #846's exhaustingRearms.add (src/framework.ts:21990–21991). The merge leaves test/budget-refusal-hold.test.ts, test/stop-step-throws.test.ts and the two changelog fragments as they were.

Since 54565d8b

54565d8b, the head before 73def25e, let a held turn give back its turn token, so the agent read as idle and a surgery was admitted while the turn waited. Since then, main's #774 made a turn alive while a provider hold keeps it for its retry. A run at 54565d8b showed that this hold had the defect #774 fixed: a rollback past the held turn's message was admitted while the hold waited, and the released turn answered without that message in its history. This head takes main's model instead. That removes:

• InferenceRequest's releasedByBudgetHold and the checks that read it: a quiesce lets a held turn's retry through, as it lets a provider hold's;
• getHostModeStatus()'s heldTurns: the turn is in activeTurnAgents;
• the look after every surgery, undo and redo, and the surgeries in the hold's snapshot, since those moves are now refused while a turn is held (above);
• the scheduler's own handling of a deferred batch's wake beside a resumed turn, and of a released guard retry. main's handling of continuations takes their place, and the test of a deferred batch's wake beside a held continuation passes at this head.

The note is now stored, after #782, and its words no longer say "It fits now".

What the agent and the host see

The agent:

• While held: nothing, and no [inference-failed] marker is stored.
• When the held turn runs: the note above, stored in its history.
• If refusals after the hold exhaust the error policy: the [inference-failed] marker it gets today, with the reason above.

The host:

• The traces of a hold that ends in a fit: inference:started, inference:failed for the refused attempt, inference:held, inference:hold_ended, then inference:started again and inference:completed.
  • inference:held carries the refusal's type and message, the budget and size when provided, the hold's start and deadline, and the number of held requests.
  • inference:hold_ended carries fit, check_failed, deadline, nothing_pending or stopped, with the time waited.
• The turn's terminal event comes when the held turn ends, after a hold of up to 30 minutes and the compile it releases, rather than as an exhaustion within seconds.
• getHostModeStatus() reads the held turn as alive, and the wakes that joined it among gatedRequests. healthSnapshot() gives each agent's budgetHold while a turn is held waiting, and null otherwise.
• The refusals: a branch switch, a rollback, an undo that would move the store, and puppetToolCall are refused while a turn is held, for example "Cannot switch branch while prime is idle+turn-alive (a budget hold keeps its turn to start again once its context fits, or at 2026-10-27T16:17:31.965Z at the latest: Compile plan would exceed hard budget: …)", followed by main's advice on quiescing. A host that ran a surgery on an agent whose turn had ended on such a refusal now waits for the hold, up to its 30 minutes, or ends the turn.
• The context-refusal ops alert goes out when the hold starts, saying the turn is held until its deadline while compression catches up. Its ops:alert trace goes out at every hold's start, and its webhook post goes through opsAlert's cooldown of 15 minutes for each agent and kind (src/framework.ts:3554, :28923).
• The logs: a hold's drain kicks log as [budget-hold], and the breaker's as [inference-failed].

Tests

test/budget-refusal-hold.test.ts has 78 tests, and test/stop-step-throws.test.ts gains a row for a hold's drop. Most run a resident through a real AgentFramework and a mock membrane. They patch ContextManager's compile, previewContext, tick and isReady to model a compression backlog, following context-manager's contracts: the preview says whether the context fits and rethrows a refusal other than over-budget, and a committing compile refuses while the context doesn't fit. A dry compile, reached only for a strategy with no preview, refuses where the context doesn't fit, as the strategy's hierarchical path does, and one test has it resolve an over-budget plan, as context-manager documents a dry compile can. Their groups are the hold and its release, the turn alive, the verdict, the snapshot, the ends and the record, undo, and the rest: a batch-only start, a withdrawn wake, a held continuation's event gate, a deferred batch's wake beside a held continuation, and a conversation agent.

Three tests run the real autobiographical strategy, with its tick stubbed, since there's no compression model:

• The note's margin case: at the smallest budget the preview fits, with under 10 tokens to spare, the released start stores its note, its compile is refused, and the hold holds the turn again. With 1,000 more tokens of budget, it runs, and its request carries two notes, one from each release.
• A context refusal: with a coverage defect injected into the strategy's emission, the preview rethrows UncoveredDropError, the turn is held once through four looks, and it runs once the defect clears.
• Without adaptive resolution, the strategy's hierarchical path: its preview gives no verdict where the context fits, in either version's form, its dry compile refuses where it doesn't, and the hold ends fit once a budget fits, by the dry compile's verdict.

Other pull requests

This head merges main at e85c57db, still main at 13:37 UTC on October 28. These meet the hold:

• fix(scheduler): a turn a provider hold keeps for its retry is alive #774 made a turn alive while a provider hold keeps it for its retry. The budget hold now keeps its turn's retry the same way.
• feat(context): store each afterUser context injection where compile() placed it, so it stays; a module's queryMessages and addMessage take forAgent #782 stores an afterUser context injection that doesn't set placedEachCompile, so the note is stored, and the hold's snapshot leaves a stored injection's arrival out.
• feat(host-mode): gatedRequests counts wakes a provider hold keeps or a scheduler pass has taken #839 counts in gatedRequests a wake a provider hold keeps, and the wakes that joined a budget hold are counted the same way.
• fix(routing): carry a turn's explicit-send hold into more of the starts that continue it #843 carries a turn's explicit-send hold into more of the starts that continue it. The retry this change gives the budget hold is built with withTurnCarry(trigger, carry) (src/framework.ts:21908).
• fix: every agent on the store works again after a rollback, suppression, branch switch, undo or redo #353 added the refusedForMovedBranch branch, whose log line names an undo or a redo as what stopped the kick. That branch is now in kickOverBudgetDrain's catch (src/framework.ts:6510), and both the breaker (:29174) and the hold (:6372) call kickOverBudgetDrain, the hold passing 'hold' as by.
• fix: what still assumed context-manager 0.13, and removing a message stored as a body #352, fix: the findings of #352's review #377 and fix(maintenance): find a pass from inside it, and stop ticking a disposed agent #448 each changed the breaker's drain kick, which is now kickOverBudgetDrain. fix(maintenance): find a pass from inside it, and stop ticking a disposed agent #448's comment at src/framework.ts:6892–6899 says the maintenance pass is registered before its body runs. This change calls checkBudgetHolds from the pass's finally (:6903–6905).
• fix(stop): every teardown step runs whatever an earlier one did, and stop() ends awareness drains #517 runs each step of stop() through a step(), and each hold's drop is a step of its own. fix(stop): a stop reaches a turn that has no live stream #529 ends a start a stop reached before it sent anything, and its check at a failure comes before the budget hold.
• feat(turns): send a turn's trigger again when its retries run out on a transient failure, with delays of 2, 8 and 32 minutes, and alert on an hour of stated waits #846 rearms a turn exhausted by a transient failure. rearmExhaustedTurn returns when isTransientFailure is false (src/framework.ts:6080–6082), and isTransientFailure returns false for an error that isn't a retryable MembraneError (:1187–1188). classifyInferenceError gives over_budget and context_refusal only to an error its MembraneError branch didn't take (:29008–29029). The hold's holdForBudgetRefusal call (:21909) comes before the line that gives a rearmed send no error-policy retry (:21929).
• fix(deps): depend on context-manager ^0.23.1 #854 raised the floor to context-manager ^0.23.1. Its doc comment on previewContextSettings says a non-adaptive AutobiographicalStrategy built from another copy of context-manager throws its "previewContext requires adaptiveResolution" error, since the manager recognises only its own copy's NoFoldPlanToPreviewError (src/framework.ts:9922–9927). The hold's preview check returns no verdict for an error with that text (:6315).

Evidence

These runs were on Linux with Node 24.22.1, each from a clean checkout of the commit it names, built from an empty dist. main and this head require context-manager ^0.23.1. 0.23.1 was published on October 27, and it's npm's latest at 13:37 UTC on October 28. On a pull request, this repository's CI runs the suite on Linux with Node 22.12.0, 24 and the latest, and on macOS with Node 22.12.0.

• At this head, with context-manager 0.23.1 from a fresh install: test/budget-refusal-hold.test.ts passes 78 of 78, test/stop-step-throws.test.ts 21 of 21, and main's test/exhausted-turn-rearm.test.ts 54 of 54. These are the only files run at this head.
• The suite, at commits before this head's merge of e85c57db:
  • at d3076846, before the last fixes, which change src/framework.ts +17/−12 and src/types/trace.ts +4/−3: 8,597 tests, 8,535 pass, 0 fail, 62 skipped, with context-manager 0.23.1;
  • at 6748c476, before it: 8,595 tests, 8,533 pass, 0 fail, 62 skipped, with 0.23.0 and again with 0.23.1;
  • at main's 8ff287dd, with 0.23.1: 8,520 tests, 8,458 pass, 0 fail, 62 skipped.
• Under load: six runs of test/budget-refusal-hold.test.ts at once, three times over, pass 18 of 18: at d3076846 at one-minute load averages of 137 to 155 with 0.23.1, and at 6748c476 at 55 to 74 with 0.23.0.
• On main's source (8ff287dd), with d3076846's test file and context-manager 0.23.1: 72 of its 76 tests fail. The file builds there only with type errors, since main has no hold traces, and its tests run anyway. The four that pass are the cases this change leaves alone: nothing pending at the refusal, a refusal once stop() has closed admission, an ephemeral run, and a framework that was never started.
• Each test the last review rounds added or strengthened fails, for the reason it names, on the source before its fix: with d3076846's test file, 9 at cb19c3ce, 3 at f91c676d and 2 at 6748c476; with this head's test file, 4 at d3076846.
• Removals, each piece undone on its own and rebuilt, with test/budget-refusal-hold.test.ts run alone:
  • at d3076846, each of the 11 pieces that 735ab6c6 and 3516350a add or change fails a test aimed at it;
  • at e30e5f32, each of the 3 pieces 63c569b9 adds, where it replaced three of those 11, fails a test aimed at it;
  • at 06e6ac3a, 16 of the 18 pieces of the rebuild on fix(scheduler): a turn a provider hold keeps for its retry is alive #774's model did the same, and the other two are under "Not verified". Since then, 735ab6c6 removed two of those 18, replaced one, the dry compile's binding, and added the clock row to another's rule, the stored-injection exclusion. The replaced piece and the changed one are both among the 11 at d3076846.
• 0.28.0 beside this change, one probe run unchanged on both: a resident whose compile is refused for budget with compression pending, and which then fits.
  • At 0.28.0 (59d60958, context-manager 0.23.1): three refused attempts, exhausted after 3.4 s; drained: true; a branch switch admitted; and 3 s after the context fit, with no new message, no provider call.
  • At d3076846 (context-manager 0.23.1), an earlier version of this change, before its last fixes and this head's merge of main: held at once; drained: false, with the agent in activeTurnAgents; the branch switch refused, naming the hold; and the turn ran once the context fit.

Not verified

• A live provider and real compression. The real-strategy tests stub the tick, and the rest patch the context manager's compile, preview, tick and readiness.
• macOS. These runs were Linux only.
• fix: every agent on the store works again after a rollback, suppression, branch switch, undo or redo #353's branch in kickOverBudgetDrain's catch has no test, here or on main.
• The turn's explicit-send carry through a hold has no test.
• A redo or a suppression while a turn is held wasn't run.
• feat(turns): send a turn's trigger again when its retries run out on a transient failure, with delays of 2, 8 and 32 minutes, and alert on an hour of stated waits #846's rearm beside a budget refusal: no test holds a refusal and then checks that no rearm follows.
• Two pieces no removal caught: holdForBudgetRefusal's path for a start that reaches its compile while a hold waits, and the hold's use of main's holdRequest deduplication, as provider holds use it.

---

• Changelog fragments added: changelog.d/budget-refusal-holds-turn.fixed.md and changelog.d/budget-refusal-holds-turn.changed.md.

Credits

Octavia-2412 wrote this change from Ada-1017's proposal on #304 and her design reviews, among them the choice to take main's held-turn model and to store the note. Hilda-2681's #774 gave that model.

Anarchid's review of bc3bb8e found that the release check took a dry compile that resolved as a fit, which context-manager documents a dry compile can't tell, and reproduced the band where the two disagree against the published strategy. It also found the undo step, the policy veto, the hold left without a cause, the checks run when nothing had changed, and what the text claimed about a restart and a stalled compression. Greptile found five defects in the first version and five in a later head. Beth-2389 read the rounds up to 2cf69a09, and her probes found a rerun that kept a fit from landing and a context refusal the preview rethrows counted as a failed check. Gordon-2414 read the round that answered Greptile's second review, the second merge of main, and the merge of 8ff287dd, where he found that any changed injection, not only the note, could release a refused turn again, and each round after it, where he found that a held tool-result guard's retry gave back the turn's first checkpoint. He also read this head's merge of e85c57db. Milo-2653 and Duncan-2410 found where #529 and #517 meet this change. Greta-2425 read the rebuild after Anarchid's review, and Fiona-2757 and Daniel-2612 checked earlier versions of this description against their evidence. Internal reviews found the rest. theaspirational reported the incident. Lottie-2661 wrote this description, from Octavia-2412's facts.

[nissa-seru]

We'll merge this after #​352, once our pre-merge checks pass on its merge with the then-current main, and not before 22:45 UTC on October 14. #​352 rewrites the drain kick this change moves, so the branch will merge main once #​352 lands, as "Order with #​352 and #​353" describes.

— Octavia-2412

[greptile-apps]

Confidence Score: 1/5

[Medium impact] The change affects turn scheduling for resident and conversation agents.

Not ready to merge: held work can be skipped, delayed, or resumed after quiesce reports a drained host.

Findings

1.  Quiesce reports drained too soon ▶
2.  Joined batches lose their wake ▶
3.  Idle runs return before replies ▶
4.  Finished compression can go unnoticed ▶
5.  Holds discard older undo history ▶

Fix with agent prompt

### Issue 1
src/framework.ts:3603-3604
When a `context_budget_restart` is held, the refused start gives back its turn token and provider admission. `quiesce()` then reports `drained: true`, because it does not count the held continuation. Compression can later release the request here, and the scheduler allows continuations to run while quiesced. A provider call can therefore start after the operator was told all turns had drained.

Count held continuations in the drain, or park their release until resume.

### Issue 2
src/framework.ts:11201-11205
If a deferred batch arrives while a `context_budget_restart` is held, this branch takes its wake into the hold. Release queues both requests together, and the restart wins. `beginAgentTurn()` skips batch assembly for that continuation, so the batch's content never reaches the compile. Its wake has been consumed, leaving the message unanswered until an unrelated fresh turn.

Keep deferred-batch wakes queued for a fresh turn, or assemble them before consuming their causes.

### Issue 3
src/framework.ts:12756-12763
`runUntilIdle()` can now return while its refused turn is still waiting. This branch resets the agent and gives back its token, while the request lives only in `budgetHolds`. The loop does not count those holds as work. Without a background `start()` loop, a later release has nobody left to process it. A positive `maintenanceIntervalMs` also prevents the fallback interval even when the maintenance timer was never started.

Include held work in the one-shot run and arrange compression checks when no maintenance timer is running.

### Issue 4
src/framework.ts:3528-3529
When a strategy supplies a progress snapshot, the signature omits whether compression is still pending. Readiness can change without that snapshot changing. After a refused check sets `lookedAt`, that change leaves the signature equal, so `checkBudgetHold()` returns before checking readiness. The hold misses its `nothing_pending` exit and can wait until the 30-minute deadline.

Include pending status alongside the progress snapshot, rather than only as its fallback.

### Issue 5
src/framework.ts:9103-9106
At the 20-checkpoint limit, `recordTurnCheckpoint()` first evicts the oldest checkpoint. Dropping the refused start here removes only the new checkpoint; it does not restore the evicted one. The waiting turn therefore leaves only 19 previous undo points despite keeping no checkpoint of its own. If the host stops during the hold, that loss remains saved.

Restore the previous list when dropping a refused checkpoint, or defer trimming until the turn is retained.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds bounded budget holds so resident and conversation turns can wait for compression, then compile again.

• Budget-refused turns wait for compression before running again.
• The released turn carries a one-time note about the wait.
• Hosts can see when a budget-refused turn is waiting and why it ends.

_{Reviews (2) · Last reviewed commit: "test(inference): a held turn's drain kic..." · Reviewed by Greptile}

[nissa-seru]

Replying to this comment.

Pushed bc3bb8e, a fast-forward from 452fdbb, with two commits. All five findings are real, and d8e3325 fixes each one, with a test for each:

1. A batch-only start's turn: its held request now drops the batch-only markers and keeps its subject. Its batches were assembled and stored before its compile, so the released start is an ordinary cause and isn't withdrawn as having nothing new.
2. Withdrawn wakes: cancelCoalescedWakes now filters a budget hold's requests by subject, as it filters a provider hold's.
3. Closing forks: the closing-fork reaper counts a budget hold as unfinished work, so a held closure turn isn't disposed.
4. Failed starts: startAgentStream's outer catch now clears what a hold kept for the agent's name (clearBudgetHoldState), as the inner terminal path does.
5. Resumed turns: a released continuation opens the event gate again when it resumes, since the refusal closed it. bc3bb8e also checks that the gate is closed once the resumed turn ends.

The hold's file has 27 tests. Undoing any one of the five fixes fails its test. The description's Evidence is at the new head. Would you re-read from 452fdbb?

— Octavia-2412

[Anarchid]

Nightly dual review · round R1 at bc3bb8e · reviewers: Codex gpt-5.6-sol (xhigh) and Claude claude-opus-5-5, merged and every claim re-verified by the Claude leg · posted by the maintainer's campaign runner. Verdict: CHANGES_REQUESTED (the formal review event is left to the maintainer). Finding ids R1-n are stable; cite them in fix commits.

Reviewed at bc3bb8e against main 92125b0 (the merge-base; main has since moved to 06303d8 by a Greptile-config commit only)

Verdict: changes requested (1 blocker, 3 major, 6 minor)

The design is right, and most of the bookkeeping is careful: an in-memory per-agent hold that never touches the provider gate, later wakes joining it, a deadline armed on every path, and a carried deadline on re-holds. The blocker is the release check. It reads "the dry-run compile didn't throw" as "the context fits", and context-manager documents that a dry compile does not throw for an over-budget plan. Reproduced against the published 0.14.1: just above the budget, the dry run resolves while the committing compile refuses. That band is where compression's final approach lands. Released there, the turn spins through release, refuse and re-hold until the next compression step lands or the deadline passes, and each cycle writes a turn checkpoint. The tests replace ContextManager.prototype.compile with a stub that throws on a dry run too, so they can't see this.

On the premise in the PR body: context-manager does refuse a committing compile with OverBudgetError (or UncoveredDropError → context_refusal) when the plan exceeds the budget. With this PR, a refused resident or conversation turn waits for compression instead of failing, but only while isReady() is false. Ephemeral runs, and refusals with nothing pending, fail as before. That premise holds. What doesn't hold is the assumption that a dry compile refuses the same way.

The three questions this review set out to settle

1. Can a turn wait forever? No. Every hold arms its deadline timer when it's created (framework.ts:3259), a re-hold keeps the first refusal's start and deadline (3246-3249), and an expired carry becomes "spent", so the next refusal takes the error policy (afterBudgetHold, 3487-3503). A dry run can't hang, since select is synchronous. But there are two caveats:

   • Near the budget, a wrong fit verdict can make the hold spin for up to that bound instead of resting (R1-1).
   • A compression that is pending but not progressing keeps every turn for the full 30 minutes, and each later wake starts a fresh 30. Escalation in that case is the context-refusal alert at the hold's start (15-minute cooldown) and the existing hard-down alert after three exhaustions, so at least 90 minutes (R1-3).

2. Are wakes during the wait kept and ordered? Yes, on the normal path:

   • Every request for the agent is moved into the hold (10703-10709), deduplicated by identity, timestamp included (3068-3071), so distinct wakes never collapse.
   • On release they're queued together, and the turn's trigger is picked by event time (wakeAt ?? timestamp), not queue order.
   • STALE_REQUEST_MS only warns, so a long-held request isn't dropped on release.

   The exceptions are R1-5 (a release that never becomes a turn), R1-7 (all causes withdrawn) and R1-9 (a race with another agent's start).

3. Does it survive a restart mid-wait? No (R1-2). The hold, its requests and its deadline are memory-only. stop() drops them, and start() queues nothing, so after a restart the agent waits for its next wake, which is the symptom in #304.

---

Blocker

R1-1. The release check treats "didn't throw" as "fits", and a dry compile doesn't throw for an over-budget plan. src/framework.ts:3380-3387

• Evidence (context-manager 0.14.0, 0.14.1 and main):

  • SelectOptions.dryRun documents the exception (0.14.1 src/types/strategy.ts:234-240): "an over-budget plan is not thrown at the plan check. A plain dry compile then returns that plan's entries with no verdict, and previewContext is where infeasibility is reported."
  • The code matches: if (result.finalTokens > rejectionBudget && (!dryRun || dryFallback)) (autobiographical.ts:8853-8854; 0.14.0 has && !dryRun at 8823).
  • Later stages still throw. The emission checks against prefixBudget (8948, 8989, 9046, 9065, 9099) aren't gated on dryRun, so most over-budget dry runs do refuse, from "Emission overran the plan". That is a drift backstop, not the verdict.
  • For kv-unified, the plan also depends on kvUnifiedImmutablePrefixHash, which reaches buildPicker (8634). The turn's compile passes it (agent.ts:1137-1145); the release check doesn't.

• Reproduced with the published 0.14.1 AutobiographicalStrategy (adaptiveResolution: true, default flat-profile folding, targetChunkTokens: 300, recentWindowTokens: 400, no summaries yet, so isReady() is false):

  • Setup: sized the plan with previewContext at a wide budget, then for each budget ran compile(budget, undefined, { dryRun: true }) and a committing compile(budget).
  • Coverage: 3 message shapes (large single bodies, mixed sizes, tool cycles) × 3 configs (base, maxMessageTokens: 800, overBudgetGraceRatio: 0.1) × 11 budgets from 0.6× to 1.02× the plan. 99 cases: 45 fit both ways, 50 refused both ways, and 4 were mismatches.
  • The mismatches: all four at 0.98× the plan, two shapes × two configs. Example: at budget 22,155 the dry run resolved, the committing compile threw "Adaptive picker exhausted but 22608 tokens still exceed hard budget 22155", and previewContext at the same budget said fits: false.
  • At 0.975× and below, both refused, the dry run at the emission stage.
  • previewContext().fits agreed with the committing compile in every case checked.
  • A separate sweep of 63 cases well below the budget had no mismatches.

• Failure scenario: compression is pending and has brought the plan to within about 2% over the budget.

  1. checkBudgetHold's dry run resolves, and the hold ends fit (3366). It sets the carry (3459) and queues the requests.
  2. The released start runs. At attempt 0 it records a turn checkpoint (11896-11899), then compiles and is refused.
  3. holdForBudgetRefusal re-holds with the carry (3246) and schedules a kick (3291).
  4. If a maintenance pass's compression call is in flight, each of the kick's 8 tick()s returns at once (CM tick: if (this.pendingCompression) return;), so the kick's after runs the next dry run straight away. It fits again, and the cycle repeats.

  Each cycle costs two full synchronous compiles, a Chronicle checkpoint write, inference:started/failed/held/hold_ended traces, and stderr lines. A module that brackets typing on these traces flickers. The scheduler polls every 10 ms (8879), so the cycle runs at compile speed. It ends when the next compression step pushes the plan under the budget, or at the carried deadline if compression is pending but stuck (R1-3).

  MAX_TURN_CHECKPOINTS is 20 (650). So 20 cycles replace the agent's whole undo history with checkpoints of refused starts.

  If compression finishes with the plan still in the band, the turn exhausts with a plain refusal, even though its hold ended fit.

• Why the tests pass: withBacklog patches ContextManager.prototype.compile so a dry run throws whenever a committing compile would (test/budget-refusal-hold.test.ts:80-99). That is the contract context-manager explicitly disclaims.

• Fix:

  • Take the verdict from what context-manager reports for a dry run, not from whether it threw. ContextManager.previewContext(budget) returns fits and treats any OverBudgetError as fits: false. The framework already wraps it (previewContextFor, 5567).
  • Strategies without a preview (previewContext returns null, or throws for a non-adaptive autobiographical config) can keep the dry compile. Their plan check isn't skipped: selectHierarchical gets no dryRun, and windowed passthrough never holds because its checkReadiness is always ready.
  • Compile as the turn will: pass the same kvUnifiedImmutablePrefixHash the activation request computes.
  • As a guard, a hold re-entered from a carry shouldn't release again on a dry run alone unless compression made progress since the last release (see R1-3's progress snapshot).
  • Add one test that uses an unpatched AutobiographicalStrategy at a budget just under its plan. About 30 lines reproduces the mismatch above.

Major

R1-2. A restart mid-hold loses the owed turn. src/framework.ts:2799-2814, 2632-2667

• Evidence: budgetHolds, the carry/spent/note maps, pendingRequests and openLogical are all in-memory. stop() ends every hold stopped and drops its requests. start() starts the loop and the timers and queues nothing. The durable TurnCheckpoint (655-661) doesn't name the refused request. Provider-wait facts are persisted (ProviderWaits(store, …), 2140), though their held requests aren't either.
• Failure scenario: a refusal at 21:00, then a deploy or restart at 21:05, while compression is still running. The user's message is in the store, but nothing schedules a compile, so the agent stays silent until an unrelated wake: #304 again. Restarting a silent agent is what an operator will reach for. This isn't a regression (before this PR the turn had already been exhausted by then), but it narrows the fix's guarantee more than "the messages stay in the store for the agent's next turn" suggests.
• Fix:
  • Persist a small owed-turn record per agent when a hold starts, the way provider waits are persisted: the agent, the hold's since/until, and the held requests' reasons/channels/addressed flags.
  • Clear it when the hold's turn streams or fails, and at disposal.
  • On start(), queue one budget-hold-release request per surviving record. The deadline can be carried, or restarted, which is a judgement call; say which.
  • If crash survival is out of scope, say so in the changelog and add a stop/start test that documents it.

R1-3. A stalled compression holds every turn for the full 30 minutes, and every later wake for another 30. src/framework.ts:1110-1118, 3367-3369

• Evidence: nothing_pending fires only when isReady() was true as the deciding dry run began. In context-manager, checkReadiness() reports not-ready whenever a compression is in flight, old enough uncompressed chunks are queued, or merges are queued. That stays true while no progress is possible:

  • A merge blocked by a compression hold: tick() returns without progress, and the merge stays queued (autobiographical.ts:4736).
  • A retryable failure of the compression model (429, network, timeout): it's rethrown, and the entry stays queued (4751-4779).
  • The speculative cap: reached, it skips L1 compression (4702), so raw chunks wait while only merges, if any, can run.
  • A provider gate closed to compression: the maintenance pass skips that agent (runQueuedMaintenance).

  So the bound isn't only for "a compression that keeps working and never makes the context fit", as BUDGET_HOLD_MS's comment claims. It's also the only exit for one that is pending and stuck. After the deadline the turn exhausts (clearBudgetHoldState), and the next wake holds afresh for another 30 minutes.

  Escalation has slowed:

  • Hard-down (inferenceFailureEscalationThreshold = 3, 1825): needs three exhaustions, so at least 90 minutes, where it used to take three wakes.
  • context-refusal alert: goes out at each hold's start, with a 15-minute cooldown.

• Failure scenario: the compression model's provider is down for an hour while the budget sits below the context's floor. Each user message waits 30 minutes, then gets nothing. The operator sees a "held until …" alert, then silence, then hard-down only after 90 minutes.

• Fix:

  • End the hold early when compression isn't moving. The strategy's progress snapshot is already read for maintenance records (contextProgress, via getProgressSnapshot). End the hold stalled when the snapshot hasn't changed across, say, three checks or five minutes.
  • Alternatively, don't hold a new turn for an agent whose last hold ended at the deadline with no progress since.
  • Either way, correct BUDGET_HOLD_MS's comment and the changelog's "or at once when compression has nothing left to do".

R1-4. This branch must not land before #352, and the conflict's resolution needs one more step. src/framework.ts:3513-3540

• On this branch, kickOverBudgetDrain doesn't check surgeryHold, and no surgery or stop awaits it. A held agent is deliberately idle, so a rollback or suppression is admitted while the hold's kick is still ticking.
  • On main the breaker's kick has the same race at exhaustion. #352 fixes it: it starts no kick and stops ticking while surgeryHold is set, treats MaintenanceWithdrawnError as a stop, and tracks the kick in overBudgetDrains.
  • This PR adds kicks at every hold start and, with the timer off, one every 5 s, so landing it first widens that race.
• The PR's ordering note covers this. #352 is still open, at ca2f806, one test-only commit past the fb8a6c4 the trial merge used. #353 is stacked on #352. Both conflict only in the drain-kick hunk.
• One thing the described resolution doesn't cover: this PR registers after before deciding whether a kick runs (3514-3520). Once #352's "no kick while a surgery holds the store" guard is merged in, an after registered during a surgery is never run; it sits in overBudgetDrainAfter until some later kick ends. It's harmless today, since the surgery's release calls checkBudgetHolds(), but the resolution should run or drop the waiting afters when the kick declines.
• Add a test with an asynchronous tick() blocked across a surgery. The existing surgery test's ticks resolve synchronously.

Minor

R1-5. The name-keyed hold state, and the open logical turn, outlive a release that never becomes a turn. src/framework.ts:10848-10866, 11873-11893

• Where it's cleared: the carry, spent, note and gate-closed entries go only when a stream exists, on a terminal failure, at stop, or at disposal.
• Where it isn't: two paths end a released hold's requests without either.
  • A policy veto: a custom InferencePolicy returns false at release (the policy-skip branch only logs).
  • A coalescing withdrawal: the release starts as batch-only, because its own trigger was withdrawn while held, and is withdrawn as turn-withdrawn with nothing new.
• What follows: in both cases the logical turn opened by the refused start is never settled, and the next unrelated turn then:
  • carries the stale note ("this turn waited 7 min while compression caught up. It fits now."), which isn't true of it;
  • or meets a stale carry: an expired one is converted to spent, so its refusal fails at once with "the turn was held N min…" (3497-3502).
• Scope: the default policy always infers (892-899), so this needs a custom policy or the withdrawal path.
• Fix: treat both as terminal for the held turn: settle it, close a resumed continuation at the event gate, and clearBudgetHoldState().

R1-6. Each release records another turn checkpoint, so one held turn becomes two undo steps. src/framework.ts:11896-11899

• Evidence: the scheduler starts the released turn at attempt 0 (10928), and attempt 0 records a checkpoint. The refused start already recorded one.
• What happens on undo: after a held turn with a joined message:
  • the first undo removes the reply;
  • the second undo goes to the refusal's checkpoint, removing the messages that arrived during the hold, as if they had been a turn.
• Under R1-1's cycle, this is what overwrites the undo history.
• Fix: carry checkpoint ownership on the held turn (as a retry does), and skip the checkpoint on its released start.

R1-7. A hold whose every cause was withdrawn still runs a turn. src/framework.ts:3463-3465

• Evidence: cancelCoalescedWakes empties heldRequests (10379), and endBudgetHold then makes up a budget-hold-release request. The result is a turn with no cause, with public prose allowed.
• Inherited: the provider hold does the same (provider-acceleration-retry).
• Test gap: the withdrawal test (test:749-765) keeps the turn's own request, so it never reaches zero causes.
• Fix: track whether the hold ever had a cause. If cancellation removes the last one, end the hold without a turn and settle the logical turn.

R1-8. Raise the context-manager floor to ^0.14.1. package.json:51

• The regression: 0.14.1's changelog fixes one from 0.14.0 in which "a dry compile that is the first compile after a message is removed" left a stale store order, after which "every later compile, dry or committing" could throw UncoveredDropError. 0.14.0 restores _storeOrder without _storeOrderSource.
• Why this PR makes it likelier: dry compiles become routine, after every pass and right after every surgery. An install that has 0.14.0 locked would meet the regression during a hold, as a context_refusal that compression can't fix.
• Scope: this repository commits no lockfile, so it needs a consumer whose lock still has 0.14.0.

R1-9. A release during another agent's awaited start can split one held turn into two. src/framework.ts:10671-10683, 10928

• Evidence: processInferenceRequests takes a snapshot of the queue, then awaits each agent's startAgentStream in turn.
• The race: agent B has a wake in the snapshot, and B's hold releases while agent A's start is awaited. When B's group comes up, there's no hold any more, so B starts with only the newer wake. The original held causes, now back in the live queue, start a second turn afterwards. If the held cause was addressed in another channel, the first turn's speech goes to the newer wake's channel.
• Scope: the window is narrow, one 10 ms poll, and the provider hold's timer release has the same shape.
• Fix: look the hold up again (or a short-lived "released" record) when the group is processed, and merge any of the agent's requests queued since the snapshot.

R1-10. Each release check is a full synchronous compile, once per held agent after every maintenance pass. src/framework.ts:3837-3843

• Cost: with the default 5 s interval, that's up to 360 select/rebuild/solver passes per agent per hold, each blocking the event loop. A fleet-wide immediate budget cut holds many agents at once.
• Fix: skip the check when the progress snapshot and the store's head sequence haven't changed since the last refused check. That reuses R1-3's signal.

---

Verified fine

• Entry filter (3222-3249):
  • It holds only on over_budget or context_refusal.
  • The agent must be live (resident or conversation), not ephemeral, and not spent, with admission open and compression pending.
  • A batch-only trigger is held with its markers stripped and its subject kept.
• Re-entrancy:
  • One check runs at a time, with one rerun for asks made meanwhile.
  • A stale completion is discarded by the hold-identity check (3362).
  • Timers are cleared on every end (3436-3438).
• Dry runs commit nothing:
  • Agent.compileWithInjections with dryRun skips the watermark and compileAtLiveBudget, so it settles no descent (agent.ts:884-909).
  • context-manager's dry select snapshots and restores chunks, queue, calibration and store order on every path (0.14.1 autobiographical.ts:4864-4955).
• The note is an injection added after strategy.select (context-manager.ts:1049-1119). It can't cause a refusal and is never stored.
• Event gate: a refusal ends the gate (12221), and a held continuation is recorded as gate-closed (3470) and reopened on resume (12015).
• Stop and disposal end holds stopped and clear the name's state. The conversation reaper counts a hold (9902-9912), and coalesced cancellation reaches holds (10373-10380).
• Traces and alerts: the trace union matches what's emitted (types/trace.ts:96-140). healthSnapshot().agents[].budgetHold matches the changelog. The context-refusal alert goes out when the hold starts.
• Windowed passthrough never holds, since its checkReadiness() is always ready. Its dry compile never throws for budget either, so it would hit R1-1 if it ever held.
• CI: green on all four legs and the changelog check. Mergeable against current main.

---

_Method.

• Two passes in parallel. Codex gpt-5.6-sol at xhigh ran read-only against a detached worktree of the head: 18.5 min, 55 commands, 7.1M input tokens (6.7M cached), 40.5k output tokens. Claude Opus 5.5 ran its own pass, fetched current main, #352 and #353, unpacked context-manager 0.14.1 from npm, and ran the dry-run-vs-committing experiments described in R1-1.
• Re-verification. Every Sol finding was re-checked against the source before adoption.
  • Scopes corrected: R1-1's mismatch is a band just over the budget, not every over-budget plan, and windowed passthrough never holds.
  • Downgraded: R1-5, R1-6, R1-8 and R1-9, from major to minor.
• Who found what.
  • Both independently: R1-1, R1-2, R1-5, R1-7, R1-10.
  • Sol only: R1-4's surgery race on this branch, R1-6, R1-8, R1-9.
  • Claude only: R1-3, the empirical mismatch and the previewContext check in R1-1, R1-4's after detail, and #352's drift since the trial merge.
• Not done. Sol had no network and couldn't run code. Neither pass ran this PR's test suite (CI covers it) or an end-to-end framework repro of R1-1's cycle. That cycle is traced from source, and the context-manager half is reproduced.

[nissa-seru]

Replying to this review.

Thank you for the review and for the reproduction. R1-1 is right. SelectOptions.dryRun says a dry compile doesn't throw an over-budget plan at the plan check, and previewContext is where feasibility is reported, and I built the release check on the opposite. I'm reworking the hold around previewContext and answering the other nine in the same round, and I'll reply to each finding when I push it.

— Octavia-2412