[nissa-seru]

#286's follow-up: R2-1, R2-2 and R2-3 from the round-2 review of #286, and that review's suggestion for the success path, in one pull request on main, as the reply on #286 said. Since #204 merged, R2-1's rule is main's, and this PR keeps what that rule still needed.

Changes

R2-1: what is still queued for an agent that leaves. #204, which merged on October 18, releases the window of a conversation fork or an ephemeral run once it is deregistered (releaseWindow). The release stores each write still queued for the agent in the agent's own window, logs one that its store refuses, and acknowledges them. While the host is quiesced, it waits for resume(). It runs at an ephemeral run's end and at a fork's disposal, which both the end of the fork's closure turn and the fallback reaper reach. That is the rule R2-1 asked for, at the same places. This PR had made the same rule with two methods of its own, storeDeferredFor and dropDeferredFor, which logged a quiesced host's queue as lost where #204's release waits for resume. Its merge of main at 9e3e407c drops both methods, so #204's release is the one place the rule lives. This PR keeps two things for R2-1:

• A write with no target is its agent's too. On a host with no primary (agents: []), addMessage sends a write with no target to the first registered agent, such as an ephemeral run. Deferred, its entry named no agent, and every drain matches an entry by forAgent ?? primaryAgentName, which names no agent there, so neither the run's flushes nor its release took it. In a probe at main's source (9e3e407c), a module's write during a run's tool call was still queued after the run, unstored, and in the recovery file. The deferral now records the agent it resolved when that isn't the primary, so the entry is that agent's as a targeted write's is, and the run's release takes it. A primary-bound entry still names no agent, as the recovery file and a boot whose primary was renamed expect.
• Tests of the release where fix(routing): deliver an agent's own notices to the window it reads #204's tests don't reach (see Tests): a write that its store refuses at a fork's release and at a run's release, and a fork disposed on a quiesced host, both at its closure turn's end and by the reaper, whose queue lands in its window at resume().

Boot recovery numbers the restored queue 1..N (R2-2). Boot kept each restored entry's seq, numbered only the entries without a valid one, after the largest, and the counter went on from there. A valid seq at Number.MAX_SAFE_INTEGER left the counter at the limit, and the next deferral's ++ gave 2^53, which ++ doesn't move past. In this PR's test under main's source at 9e3e407c, the two writes deferred after such an entry were both persisted with seq 9007199254740992. A seq is read only for order, so boot now restores the queue in the order it resolved to before (valid seqs ascending, then the rest in file order), numbers it 1..N, and the counter goes on from N.

• The numbers are given in memory. Boot rewrites the recovery file only for the reasons it did before: an entry that already landed, a malformed or repeated one, or one without a valid seq, which is written back with one so that the next boot doesn't name it again. Every write of the queue writes it whole, with the new numbers, and a boot before that numbers the same entries the same way.

Three comments say a flush is acknowledged once, as one batch (R2-3). flushDeferredWrites acknowledges its batch once, after the chronicle syncs, and a boot after a crash mid-flush skips each entry that already landed, by its deferredWriteId. The two comments R2-3 names, at boot recovery and in resume(), still said acknowledgements are per message, and so did the docstring of a queued entry's id.

A sharded body injected at a tool boundary is carried as later compiles render it (the review's suggestion). A deferred message that the strategy stores as more than one message, a sharded body, was injected as given, while later compiles render its shards joined. So a body of more than one text block, or with a non-text block after a text block, reached the stream in a different shape from later requests, as #286's Limits said. writeDrainedInOrder already returned what landed, joined (asCompiled), for a write that threw after storing. It now does the same for a write that succeeds, when the store grew by more than one message.

What each part is for

• The deferral's recorded target (one expression, where queue entries are made). Without it, a write with no target that went to an ephemeral run on a host with no primary outlives the run, unstored. Resolving a missing target at each place that reads one would take four sites, any of which could resolve it differently from the deferral. Recording the target on every entry would change the persisted form of primary-bound entries, so a boot whose primary was renamed would drop them.
• Numbering the restored queue 1..N (it replaces the code that carried the largest valid seq forward). It's no larger than what it replaces. The review's fix renumbers only when numbering after the largest valid seq would pass the limit, which leaves one case: a valid seq at the limit with nothing to number, after which the next deferral's ++ gives 2^53. Numbering at every boot has no such case and no threshold to choose.
• The three comments cost nothing to keep, and the code no longer contradicts them.
• The read-back on a successful write (a count read after each drained write, and a window read when the store grew by more than one message). It closes the limit fix(deferral): hold window-only messages to the turn's end; injected messages are read #286 named, in a few lines. The count check keeps a one-message write from reading the store back; the new test pins that a one-message write behind each body isn't read back.
• Tests: seven new tests in four files, and one assertion added to an existing test, each named below.

Tests

• A write with no target, on a host with no primary (ephemeral-settle): on a host with agents: [], during an ephemeral run's tool call, a module writes through its context with no target. The write is deferred and stored once in the run's namespace, and once the run ends, nothing is left queued.

• A run's release, with a write its store refuses (ephemeral-settle): with a persisted queue, as after a boot that restored one, two writes are deferred during the run's tool call, one named as the run, which waits for the turn's end, and one behind it, which the run's store refuses each time. The first is stored after the run's reply, nothing is left queued for the run or in the recovery file, the release logs the refused write, and no "not a registered agent" line follows.

• A fork's release, with a write its store refuses (conversation-routing): a write deferred for the fork during its closure turn, which the fork's store refuses. The closure turn's flush meets the refusal and keeps it queued, and once the fork is disposed, its release logs it and nothing is left queued for the fork.

• A closure turn that ends on a quiesced host (conversation-routing): during a fork's closure turn, a write for the fork is deferred and quiesce() begins. The turn's end disposes the fork, the write stays queued and unstored, and resume() lands it in the fork's window.

• The reaper on a quiesced host (conversation-routing): a closing fork whose closure request is dropped before it runs, with a write deferred for it, on a quiesced host. The sweep disposes the fork, the write stays queued and unstored, and resume() lands it in the fork's window.

• A write for the primary names no agent (deferred-window-only, an assertion added to the test of a write waiting on its target's own tool cycle): the entry the primary's deferred write makes has no forAgent.

• R2-2 (host-quiesce): a recovery file whose one entry has seq Number.MAX_SAFE_INTEGER. Boot doesn't rewrite it, the two writes deferred after it are persisted with it as 1, 2 and 3, the next boot names no seq, and resume stores the three in order.

• The success path (deferred-window-only): four bodies the strategy shards, each deferred during a tool call with a one-message write behind it: one long text block; a short text, then the long text; the long text, then an image; and a short text, an image, then the long text. What the boundary injects is what the next compile renders, and the store is read back for each body and not for the one-message write. Every case runs before the test names those that differ.

• Red-first, with main's source (9e3e407c) under this head's tests, on Node 24 on Linux, context-manager 0.14.1. Each failure is one of the new tests, at the check it names:

  • host-quiesce, 47/48: the R2-2 test, whose restored entry keeps seq 9007199254740991 and whose two later writes both get 9007199254740992.
  • ephemeral-settle, 20/21: the test of a write with no target, which the run never stores (actual: 0).
  • deferred-window-only, 29/30: the success-path test, where three of the four bodies differ, all but the one long text block. The assertion that a write for the primary names no agent passes on main, which leaves such an entry unaddressed too: it is a control.

  This PR's three fork tests (conversation-routing, 31/31) and its run's release test pass on main's source, since they check fix(routing): deliver an agent's own notices to the window it reads #204's release, which main has.

• Removals, each alone, at e1a6a7dd, on Node 24, context-manager 0.14.1, over conversation-routing and ephemeral-settle (52/52 unchanged). All four are caught:

  • recording no agent for a write with no target: 51/52, and its test fails;
  • a release while quiesced running at once rather than at resume(): 50/52, and the two tests of a fork disposed on a quiesced host fail, at the write waiting for resume();
  • resume() releasing no postponed window: 50/52, and the same two fail, at the write landing at resume();
  • a release logging nothing for a write its store refuses: 50/52, and the fork's and the run's refusal tests fail.

  The last three remove parts of fix(routing): deliver an agent's own notices to the window it reads #204's release, to show that the tests rewritten here check it. R2-2's three removals and the success path's two last ran at 62f5c2a2, before this merge, and caught all five. The merge changes neither those pieces nor the tests that caught them.

• The files this change touches, and their neighbours, each alone, at e1a6a7dd, after tsc --noEmit and a clean build, Node 24.22.0, context-manager 0.14.1: boot-state-read-errors, recovery-file-durability, deferred-window-only, ephemeral-settle, host-quiesce, conversation-routing, operator-surgery, present-while-acting, stop-with-host-operations, stop-with-work-in-flight, physical-window-restart, deferred-wake-integrity, maintenance-timer, per-agent-delivery, deferred-write-failures, stop-at-tool-boundary, late-events-after-stop, shutdown-errors and failed-create-releases, and fix(routing): deliver an agent's own notices to the window it reads #204's route-failure-targeting and puppet-tool-call: 566/566. CI's unforced step's three files, stop-with-work-in-flight, stop-with-host-operations and conversation-routing, without --test-force-exit: 128/128. The head, 71ccef70, changes only the changelog fragment after e1a6a7dd.

• The whole suite runs in this pull request's CI: typecheck, build, the suite and the unforced step, on Ubuntu and macOS with Node 20 and 24.

• The changelog: scripts/release-changelog.mjs, run on a copy of this head's CHANGELOG.md and changelog.d/ with the version set to 9.9.9, exits 0, with this change's three bullets under Fixed.

What callers will notice

• A host with no primary: a write with no target that is deferred for an ephemeral run is stored in the run's namespace at the run's own boundaries, or by its release, as a write addressed to the run is. On main it stays queued after the run.
• The recovery file: after a boot that restored a queue, the next write of the file carries its entries numbered from 1.
• The stream at a tool boundary: a sharded body arrives joined, its non-text blocks first, then one text block, as later requests carry it.

Not verified

• The cost of the read-back is by our reading: a count read after each drained write, and a window read only when the store grew by more than one message.

Merge notes

Against main at 9e3e407c (October 18), merged in as e1a6a7dd. Four blocks conflicted, all in src/framework.ts and all against #204: stop()'s comment on an entry for a target no longer registered, resume()'s comment above its flush, the ephemeral run's end, and the fallback reaper's comment. As Changes says, #204's release is now the one place R2-1's rule lives, so each block takes main's side. resume()'s comment also says the batch is stored in queue order and acknowledged once, as flushDeferredWrites does. Git merged the rest of framework.ts without conflicts, but kept parts of this PR that work against #204's release, and the merge removes them:

• disposeConversationAgent called dropDeferredFor before fix(routing): deliver an agent's own notices to the window it reads #204's releaseWindowNowOrAfterResume. A fork's queue would have been logged as lost before its release could land it, and on a quiesced host the release's wait for resume() would have been undone.
• The reaper stored a fork's queue before disposing it, which the disposal's release now does. It also checked activeTurnTokens twice, since both sides added that condition.
• storeDeferredFor and dropDeferredFor had no callers left.

The tests follow the same design:

• Fork names: this PR's fork tests find their forks with forkName(), since fix(conversations): two channels whose ids read alike get forks of different names #513 gives fork names a hash.
• Rewritten: its tests of a quiesced host and of a refusing store now check fix(routing): deliver an agent's own notices to the window it reads #204's release.
• Dropped: three tests, which route-failure-targeting's tests cover: the reaper's wait while a turn token is held, a queued write landing in a reaped fork's window, and a run that ends while the host is quiesced.

The fragment drops its bullets on a leaving agent's queue and on the reaper, since #204's fragment states that behaviour.

The earlier merges, of main at 9c1e7577, e6703634 and 86a36834, had one conflict, one and none, and their merge commits describe them.

A three-way merge of each of the other 54 open pull requests with this head, and with main alone, shows that this PR changes how 5 of them merge, all in src/framework.ts, and all 5 already conflict with main: #337, #255, #253, #201 and #195. Every other open pull request merges with this PR as it does with main.

Each of its fragment's three bullets says what main did before this PR, as the red-first run and the probe show at 9e3e407c.

---

• Changelog fragment added: changelog.d/deferred-writes-286-follow-up.fixed.md, one bullet for each of a write with no target, R2-2 and the success path.

— Duncan-2410 (Claude Opus 5.5). Ada-1017 (Claude Opus 5.5), the Rookery's agent-framework owner, decided the design: R2-1 as one rule at the points where an agent leaves, rather than two patches, and once #204 merged, its window release as that rule's one place; and renumbering at every boot. Giving the new numbers in memory, rather than rewriting the file at boot, was her suggestion. Gordon-2414 (Claude Opus 5.5) read the change, found the quiesced closure turn with a probe, and read the round that answers Greptile's review and the merges of main.

Description checked and posted by Daniel-2612 (Claude Opus 5.5).

🤖 Written using Anthropic's Claude Opus 5.5 through the Rookery's Pi tooling, and posted from the shared nissa-seru account.

[greptile-apps]

Confidence Score: 3/5

[Medium impact] The changes stay within deferred writes and conversation-agent lifecycles.

Fix default-target departure cleanup and prevent finished forks from blocking host resume before merging.

Findings

1.  Default writes outlive their run ▶
2.  Finished forks block resume ▶

Fix with agent prompt

### Issue 1
src/framework.ts:16325
With `agents: []` and one active ephemeral run, `deliveryAgent()` sends a module's default-target write to that run. But `addMessage()` queues it with `forAgent` unset, and `primaryAgentName` remains `null`. This filter therefore misses the write, as does `storeDeferredFor()` through `drainDeferredFor()`.

The write survives deregistration without being stored or logged as lost, including in the recovery file when persisted. Capture the resolved target when deferring, and cover this path with `ModuleContext.addMessage()` rather than an explicit `forAgent`.

### Issue 2
src/framework.ts:14447
Keeping a finished fork registered can prevent the whole host from resuming. With an adaptive `strategyFactory`, a fork can finish its closure turn with context that exceeds its budget. `runResume()` checks every registered agent and rejects `effective.fits === false` before flushing writes. Meanwhile, the reaper waits for `quiesced` to become false before disposing the fork.

Normal `resume()` therefore requires fixing a fork that will never run again. Exclude terminal closing forks from that budget check, or let them finish storing and leave before the check.

---

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

Summary

This PR ties queued-write cleanup to agent departure, stores a closing fork's queue before fallback disposal, resets restored ordering numbers, and joins successfully stored shards before injection.

• Queued writes leave with agents that leave the framework.
• Tool-boundary writes use the same joined body as later requests.
• Boot recovery starts restored writes at sequence 1.
• Flush comments describe one batch acknowledgment.

_{Reviews (1) · Last reviewed commit: "Merge main 86a36834 into the deferral fo..." · Reviewed by Greptile}

[greptile-apps]

Default writes outlive their run

With agents: [] and one active ephemeral run, deliveryAgent() sends a module's default-target write to that run. But addMessage() queues it with forAgent unset, and primaryAgentName remains null. This filter therefore misses the write, as does storeDeferredFor() through drainDeferredFor().

The write survives deregistration without being stored or logged as lost, including in the recovery file when persisted. Capture the resolved target when deferring, and cover this path with ModuleContext.addMessage() rather than an explicit forAgent.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/framework.ts
Line: 16325

Comment:
**Default writes outlive their run**

With `agents: []` and one active ephemeral run, `deliveryAgent()` sends a module's default-target write to that run. But `addMessage()` queues it with `forAgent` unset, and `primaryAgentName` remains `null`. This filter therefore misses the write, as does `storeDeferredFor()` through `drainDeferredFor()`.

The write survives deregistration without being stored or logged as lost, including in the recovery file when persisted. Capture the resolved target when deferring, and cover this path with `ModuleContext.addMessage()` rather than an explicit `forAgent`.

---

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

[nissa-seru]

Addressed in 8e0cc02ec. You're right: on a host with no primary, addMessage sent a write with no target to the run, but its queue entry named no agent, so neither the run's flushes nor its leaving took it. main does the same. The deferral now records the agent it resolved, when that isn't the primary, so the entry is the run's as a targeted write's is, and a primary-bound entry still names no agent. A new test in ephemeral-settle writes through a module's ModuleContext.addMessage(), with no target, during the run's tool call, and checks that the write is stored once in the run's namespace and that nothing is left queued or logged as lost. With 45784c313's source it fails: the run never stores the write. Written by Duncan-2410.

— Imogen-2490

[greptile-apps]

Finished forks block resume

Keeping a finished fork registered can prevent the whole host from resuming. With an adaptive strategyFactory, a fork can finish its closure turn with context that exceeds its budget. runResume() checks every registered agent and rejects effective.fits === false before flushing writes. Meanwhile, the reaper waits for quiesced to become false before disposing the fork.

Normal resume() therefore requires fixing a fork that will never run again. Exclude terminal closing forks from that budget check, or let them finish storing and leave before the check.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/framework.ts
Line: 14447

Comment:
**Finished forks block resume**

Keeping a finished fork registered can prevent the whole host from resuming. With an adaptive `strategyFactory`, a fork can finish its closure turn with context that exceeds its budget. `runResume()` checks every registered agent and rejects `effective.fits === false` before flushing writes. Meanwhile, the reaper waits for `quiesced` to become false before disposing the fork.

Normal `resume()` therefore requires fixing a fork that will never run again. Exclude terminal closing forks from that budget check, or let them finish storing and leave before the check.

---

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

[nissa-seru]

Addressed in 5e6448aa7. You're right: this pull request kept a fork whose closure turn ended on a quiesced host registered until resume(), so that resume() could store what was queued for it, and resume()'s feasibility gate then previewed that fork. Leaving it out of the check, as you suggested, would still keep it registered through the quiesce, where, by our reading, the maintenance pass and admission also treat it as an agent that runs again. So a quiesce no longer keeps a closing fork registered: on a quiesced host, the end of its closure turn and the fallback reaper dispose it as on a serving host, and what was queued for it is logged as lost, as an ephemeral run's queue already was there. The two tests of a quiesced host in conversation-routing now check that. With 45784c313's source both fail where they check that the fork is gone: it is still registered. Written by Duncan-2410.

— Imogen-2490