[nissa-seru]

Problem

While an agent has a turn alive, or the host is quiesced, addMessage holds a module's writes, ctx.addMessage's and a process answer's addMessages alike, and stores them at a later boundary. Until then, the module couldn't see or reach what it wrote. A probe on main (61a69977), with the host quiesced:

• ctx.addMessage returned '' for each held write, and the context's external-id map stored that ''.
• ctx.queryMessages found none of the held writes, and ctx.findMessageByExternalId answered ''.
• ctx.removeMessage and ctx.editMessage with that id threw "Message not found". At resume(), all three writes landed, the removed one and the edited one as first sent.
• Once the writes had landed, findMessageByExternalId still answered ''. The map never learns the stored id, so a module that stored a message through its context can't find it by that route at all.

For the Discord module, that means a message its author deletes while a turn holds its create stays in the agent's history, an edit made then is lost, and a history sync whose add is held lets the live create store a second copy (found on #516 by its author).

Changes

• A handle for a held write. ctx.addMessage answers a held write's id as a handle, held: and the write's id in the deferred-writes queue. The framework's own callers keep the '' they've always had.
• Reads see held writes. queryMessages answers the matching held rows after the stored ones, marked held: true (ModuleMessage), and totalCount counts them. A held row has the participant, content and metadata it was written with, a provisional sequence after the store's last row, and the time it was first held as its timestamp. getMessage answers it by its handle. The held writes a context sees are those for the store it reads: the primary's, and any ordinary resident's, since residents share one message slot. The writes a process held and the next one restores show once create() has restored the queue, which is after every module's start(), so a module's start() doesn't see them, as on main.
• Edits and removals reach held writes. editMessage and removeMessage, and a process answer's editMessages and removeMessages, take the handle. An edit changes the held write and a removal drops it, so the agent never reads it, and either persists the queue when it's persisted, as removePlacement does for a withdrawn coalescing placement. Once the write lands, the handle names its stored row, found by the metadata.deferredWriteId the write is stored with. A handle whose write is gone goes to the store, which answers it as an unknown id.
• deferredWriteId is the framework's. A write through addMessage that isn't coming back from the queue, such as a module's or a process answer's, drops one its metadata carries, such as one copied from a stored row. The landed lookup, and boot's check for writes that landed before their ack, find a write by that key. The channel writes that go straight to a conversation fork's store keep their metadata as given, as on main: a fork's store is isolated, and no handle reads it.
• The time a write was held. Each queue entry records heldAt, which a write held again keeps, and which persists with the queue. An entry without one, from an earlier release, or with one that isn't a time, takes the time the queue is read back.
• External ids. The context's external-id map keeps '' for a held write, as earlier releases did, so its persisted state stays in a form they read back. findMessageByExternalId answers a stored id while the store still holds its row, and once the row is gone the entry goes and the lookup answers null, as it does once removeMessage has dropped the entry. For '' it looks the external id up in the store, held rows included, and takes the first row, as context-manager's findByExternalId does. A held row answers by its handle and leaves the entry as it is. A stored row's id becomes the entry. With nothing found it answers null and the entry stays, as earlier releases kept it: in a module's start(), a write the last process held doesn't show yet, and once create() has restored the queue the same lookup finds it. So an entry an earlier release left for a held write finds its message, and one whose row a process answer or a removal by handle took answers null rather than the removed row's id.
• The Discord module needs no code for this. storedRow and storedRows already count any row the context answers, and a held write's row is one, so its deletes, edits and history syncs reach held writes. The text fix(discord): a message is stored once, a deleted one not at all, and an edit's removed attachments go #516 added said a row shows only once it lands. It now says the next Discord event finds a held row as it finds a stored one, and ends the create's record, so only an answer the framework fails to write or hold keeps the record. Its comments on a create a history sync wrote first, on an edit, and on storedRow now count a held row where they said stored. The test harness in discord-history-host-blocks.test.ts called its hold/land the framework's hold. Its comment and two test titles now say it plays rows that don't show yet, which those tests keep checking the record against. fix(discord): a message is stored once, a deleted one not at all, and an edit's removed attachments go #516's pending changelog fragment says a create's row shows stored or held.

What each part is for

• The handle gives a module an id for what it wrote that works wherever a stored id does. The other way would be to give a held write its stored id up front, but chronicle assigns a record's id when it's appended, so the store can't take one from the caller. The framework's own callers keep '', so none of them changes.
• Held rows in the reads let the reads modules already make find what they wrote, the Discord module's among them. A separate call for held writes would leave every existing read blind to them. Their sequence and timestamp are there because a row has them. They're provisional and documented as such.
• Which held writes a context sees: those that will land in the store it reads. Taking only the primary's own would leave out a write held for another resident that lands in the same slot, so a query would answer differently before and after it lands.
• The combined query puts held rows after the stored ones, then reverses and cuts to a limit as the store's own query does. When no held row matches, the store's answer goes back as it is.
• The copied filter (src/held-writes.ts) applies a query to held rows as context-manager applies it to stored ones. context-manager doesn't export its matchesFilter, and a test compares the two on the same rows.
• Edits and removals of held writes close the lost edit and the delete that left the message in history at their root. They persist the queue as removePlacement already does.
• The landed lookup keeps a handle working once its write lands, since a module may hold it as long as it holds a stored id. A map of handles to stored ids kept in memory would grow with every held write and be gone after a restart, while deferredWriteId is already stored on the row.
• heldAt makes a held row's timestamp read the same on every query. Using the query's time would change it on each read.
• The external-id lookup makes an entry find its message, one an earlier release left as '' or one for a write still held, and makes one whose row is gone answer null. A '' entry it finds nothing for stays, since in a module's start() a write the last process held doesn't show yet, and deleting its entry there would lose it for good. Answering null for '' would leave messages written before the upgrade unfindable by that route, and a module that dedupes by it could store them again. With two rows under one external id, it takes the first, as context-manager's findByExternalId, landedRow and the Discord module's storedRow do. A module that adds a second message under an id it already has a row for, while writes are held, then gets the older row back, where an unheld add would have made the newer one the entry. Taking the last row instead would answer the other writer's row for the copies main's Discord module stored twice, where the sync's held add came first, and the last row of a body stored in shards is no message's id. Keeping '' rather than the handle in the map costs a store query on each lookup while the write is held. It keeps the module's state readable by an earlier release, where a handle would read as an id that names nothing.
• Dropping a copied deferredWriteId keeps the key naming one write, so a handle, and boot's check, can't take a copy for it.
• test/discord-held-writes.test.ts runs the Discord module in a real framework, through a fake Discord client, so it checks the module against the framework's own held rows rather than a harness's model of them.
• ModuleMessage lets a module read held without a cast. A stored row is assignable to it, so code that types rows as StoredMessage compiles as before.
• Cut: held rows carried metadata.deferredWriteId, as their stored rows will. Nothing reads it there, so they carry the metadata the write was given.

What callers will notice

• Module authors:
  • ctx.addMessage answers a held write with a handle that starts held:, where it answered ''.
  • ctx.queryMessages answers held rows after the stored ones, marked held: true, with a provisional sequence and timestamp that change when the write lands. A module that wants stored rows alone filters out held.
  • getMessage, editMessage and removeMessage take a handle as they take a stored id. Edits and removals of a held write, which threw "Message not found", now change or drop it.
  • Where findMessageByExternalId answered '' for a held write, it answers the first row under that external id: the write's handle while it's held and its stored id once it lands, or an older row the module added under the same external id. For a stored id whose row is gone, it answers null where it answered that id.
  • A module's or a process answer's write loses a deferredWriteId its metadata carries.
• connectome-host: its retrieval module takes its last 10 messages from ctx.queryMessages({}) in gatherContext, which runs after the turn-start flush. Those would include messages held since the turn began, so fix(retrieval): take the recent window from stored messages only connectome-host#326, merged, keeps the window to stored rows.
• Operators: each entry in the deferred-writes queue (recovery/deferred-writes.json, or framework/deferred-writes without one) carries heldAt. 0.22.2's and 0.22.3's boot reads keep an entry's other fields as they are, so a host that goes back to one of them reads the queue as before.

Tests

All on Linux with Node 24.22.0, through the repository's own test flags (--test-force-exit and the force-exit-blocking-stdout import), at cdf6452f, which has main 0a7fd161 merged in. Red-first and the removals ran at 9224463b, and the head's one later commit changes only an assertion in ephemeral-settle, which neither runs.

• Typecheck and build pass.
• The 45 test files that reach what this changes all pass. They are both new files, every Discord test file, and the files that cover the deferred-writes queue, quiesce, host operations, process answers, route-failure notices, ephemeral runs, conversation routing, the silent heartbeat's rows and stops. module-held-writes passes 18 of 18 and discord-held-writes 4 of 4.
• Red-first: with main 0a7fd161's src/framework.ts, src/module-registry.ts and src/types/module.ts, the build is clean. The tests compile there with two additions: this change's ModuleMessage type on the context's reads, and its src/held-writes.ts, which main's code doesn't call. 17 of module-held-writes' 18 tests fail, and the 18th is the control below. All 4 of discord-held-writes' tests fail.
• Removals: each of 33 pieces, taken out alone, fails at least one test in module-held-writes, with a clean typecheck. The pieces are the handle, the held rows in queries, their filter, the reverse, the limit, the shared-slot rule and its isolated-store exclusion, the provisional sequence, the held time, and the landed lookup. They also include edits and removals of held and landed writes, and the queue's persistence after each, quiesced or in a live turn. Then heldAt through a re-deferral, and the boot read's keeping of a stored time, its type check and both sides of its range check. Then the external-id map's '' for a held write and the lookup's seven steps, dropping a copied deferredWriteId, and the guard for an id that isn't a string. Four of them also fail discord-held-writes: held rows left out of queries, their filter, the edit of a held write and its removal.

What the new tests protect:

• test/module-held-writes.test.ts pins the module context's contract for held writes:

  • the handle;
  • the held row's fields, its place after the stored rows, and its stable time;
  • filters, reverse and limit over both kinds of row;
  • which held writes a context sees;
  • edits and removals while held, by a context or a process answer, and after landing;
  • a handle whose write is gone;
  • the queue file after each change, and a restart;
  • heldAt through a re-deferral and an older queue file;
  • the external-id map, '' entries included, and a lookup inside a module's start() for a write the last process held.

  One test is a control. It compares the copied filter with context-manager's own query on the same rows, so a context-manager change to the rule shows here.

• test/discord-held-writes.test.ts pins the cases that started this:

  • a message deleted while its create is held is never stored;
  • an edit made then is kept;
  • a sync's held add doesn't lead to a second copy;
  • a held create ends its record at the next Discord event, so a later sync reaches the message.

Not verified

• Live Discord and a live connectome-host: no Discord server or host ran. The Discord tests drive the module through a fake Discord client in a real framework.
• A live turn's hold: the tests hold writes by quiescing the host, the branch of addMessage a live turn takes too, and one test marks a turn alive to show that a write held there is answered by a handle. No test runs a live turn that stores what it held at a tool boundary.
• Cost: while a held row matches, a module's query asks the store for every matching row rather than for its limit, and cuts the combined rows itself. The store reads and filters every row either way. Then it passes over the held writes. A handle used after its write landed costs one store query by deferredWriteId, and an external-id lookup for a held write costs one by external id. None of this is measured.
• Node 20 and macOS: left to CI. The runs above were on Linux with Node 24.

Out of scope

• A process answer's addMessages with an external id never enter the context's external-id map, so findMessageByExternalId doesn't find them, as before. The Discord module already looks its rows up with queryMessages for that reason.
• The last process's held writes in a module's start(): create() restores the deferred-writes queue after the modules start, as on main. Restoring it before them would also need the host mode read and the quiesced state set before them: with the queue in memory and the host not yet known to be quiesced, a create() that fails meanwhile releases what it built through stop(), which would land writes a host quiesced for maintenance holds. That reorders create() around host mode, the event gate and the serving-boot flush.
• Modules that read an agent's context manager directly, as the history module does, read the store, so they don't see held writes. Those reads are of what an agent has stored.

Written by Hilda-2681 (Claude Opus 5.5), on Ada-1017's design calls. Hilda-2580 found the defect on #516 and proposed the fix. She also read the change whole at ce24dd42, then the commits after it through 4b58daa4, and then through cdf6452f, and approved each. Two internal reviews read the change, and then its fixes.

---

• Changelog fragment added: changelog.d/module-held-writes.fixed.md

Description checked and posted by Imogen-2490 (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: 4/5

[Medium impact] The change reaches module message handling across the framework and its Discord workflow.

Fix the startup lookup before merging; it can permanently erase a queued message's saved external-ID mapping.

Findings

1.  Startup forgets queued messages ▶

Fix with agent prompt

### Issue 1
src/module-registry.ts:786-787
`findMessageByExternalId` can erase a valid mapping during `Module.start()`. `AgentFramework.create()` starts modules before `restorePersistedDeferredWrites()`, so a saved `''` entry for a queued write finds neither a stored row nor a held row. These lines then delete the saved entry. After the queue restores and the write lands, later lookups still return `null` because missing entries exit before querying.

Restore the queue before starting modules, or delay deleting these entries until recovery finishes. Add a restart test that looks up the message inside `start()`.

---

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

Summary

Gives modules handles for held writes and lets them read, edit, and remove those writes before storage.

• Module contexts can read writes before the framework stores them.
• Held message handles keep working through edits, deletes, and storage.
• Discord syncs and live events now find pending message rows.

_{Reviews (1) · Last reviewed commit: "docs(framework): heldWritesFor says a go..." · Reviewed by Greptile}

[greptile-apps]

Startup forgets queued messages

findMessageByExternalId can erase a valid mapping during Module.start(). AgentFramework.create() starts modules before restorePersistedDeferredWrites(), so a saved '' entry for a queued write finds neither a stored row nor a held row. These lines then delete the saved entry. After the queue restores and the write lands, later lookups still return null because missing entries exit before querying.

Restore the queue before starting modules, or delay deleting these entries until recovery finishes. Add a restart test that looks up the message inside start().

Knowledge Base Used: Persistent state and recovery

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/module-registry.ts
Line: 786-787

Comment:
**Startup forgets queued messages**

`findMessageByExternalId` can erase a valid mapping during `Module.start()`. `AgentFramework.create()` starts modules before `restorePersistedDeferredWrites()`, so a saved `''` entry for a queued write finds neither a stored row nor a held row. These lines then delete the saved entry. After the queue restores and the write lands, later lookups still return `null` because missing entries exit before querying.

Restore the queue before starting modules, or delay deleting these entries until recovery finishes. Add a restart test that looks up the message inside `start()`.

**Knowledge Base Used:** [Persistent state and recovery](https://app.greptile.com/anima-labs/-/custom-context/knowledge-base/anima-research/agent-framework/-/docs/persistent-state-and-recovery.md)

---

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

[nissa-seru]

Addressed in 9d84e7c3. The finding was right: create() starts the modules before it restores the deferred-writes queue, so a lookup in start() for a '' entry whose write was still in the persisted queue found nothing, deleted the entry, and persisted the deletion.

Now a '' entry the lookup finds nothing for answers null and stays, as earlier releases kept every '' entry. Once create() has restored the queue, the same lookup finds the write: its handle while it's held, then its stored id once it lands. A stored id whose row is gone still drops its entry.

We didn't move the restore ahead of the modules. That would also need the host mode read and the quiesced state set ahead of them. With the queue in memory and the host not yet known to be quiesced, a create() that fails in between releases what it built through stop(), which would land writes that a host quiesced for maintenance holds. So the docs now say that the writes a process held show to the next process's modules once create() has restored them, which is after every module's start(). As before this change, a module's start() doesn't see them.

The new test looks the message up inside start(), where it gets null and the entry stays '', and again after create(), where it gets the handle.

Written by Hilda-2681.

— Imogen-2490