[nissa-seru]

A module's event that arrives after stop() began is now dropped with a log line naming the module, instead of throwing Queue is closed. This follows #263, which made AgentFramework.pushEvent() throw after stop() for a direct caller and drop a late tool result with a log line.

Problem

A module's event after stop() began. stop() closes the event queue first. It stops modules last, after the streams, the event loop and the typing indicators. In between, a module is still running:

• a listener can fire, such as the Discord module's message handler or the workspace module's fs events after a pass;
• a module's own stop() can push a final event.

On main, both of a module's paths throw Queue is closed. ModuleContext.pushEvent() calls AgentFramework.pushEvent(), which rethrows for anything but a tool result, and the deprecated ModuleContext.queue is the raw queue. Thrown from a listener, it can go unhandled, as an uncaught exception or an unhandled rejection. Thrown from a module's stop(), it makes the framework's stop() reject with Queue is closed.

Change

• A module's event goes through pushModuleEvent(), from ModuleContext.pushEvent() and from the deprecated queue handle alike. Once the queue is closed, the event is dropped with a log line: [framework] a '<type>' event from module <name> arrived after stop() began — dropped. Nothing will process it, and from a listener a throw can go unhandled. Otherwise it's queued as before: pushEvent() traces process:received, and the queue handle stays untraced.
• A module's tool result after stop() began goes to pushEvent()'s own drop, so its log line still names the call, the tool and its outcome.
• A direct caller of AgentFramework.pushEvent() still gets the throw for anything but a tool result, as fix(lifecycle): late tool results and MCPL arrivals at stop() settle instead of rejecting unhandled #263 decided. It can catch it, and learns the framework is stopped.
• ModuleRegistry takes the pushing module's name as an optional second argument, in its queue (ModuleQueue) and its pushEvent option. A ProcessQueue and a one-argument callback still fit.
• The deprecated ModuleContext.queue is now an object with push alone, as its ProcessQueue type always said. It was the framework's own queue object.
• ModuleContext's pushEvent() and queue docs say what a push after stop() began becomes.

Not changed here

• A new lifecycle after a completed stop() leaves the event queue closed, as on main. Opening it alone would let the old lifecycle's module contexts and late tool results into the new one, and the push coalescer and liveness watchdog stay stopped. start() after a completed stop() reuses an instance whose queue, coalescer and watchdog stay stopped #315 asks whether reusing an instance after stop() is meant to be supported.
• A host command already running when stop() begins isn't waited for or fenced, as fix(lifecycle): late tool results and MCPL arrivals at stop() settle instead of rejecting unhandled #263's "Not changed here" says. That is a separate change.

Tests

test/late-events-after-stop.test.ts, five tests:

• a module's events through both paths while the framework runs, with only pushEvent() traced;
• two modules pushing from their own stop() through both paths: each event is dropped with a line naming its module, and stop() completes;
• a module's tool result after stop(), through both paths, logs fix(lifecycle): late tool results and MCPL arrivals at stop() settle instead of rejecting unhandled #263's line for the call;
• a module pushing after stop() finished: nothing throws, and each drop is logged;
• a direct pushEvent() after stop() still throws.

On main, the second, third and fourth fail: the second with stop() rejecting Queue is closed, the third where the queue handle's push throws.

Each piece of the change fails one of these tests when it's removed: the drop, the untraced queue handle, the queue handle's route through the drop, the tool result's own line, and each module's name in its line.

Runs at 60636e03 on main c2f9baee (f1c6087f changes only a comment and the changelog fragment), one node --test process per file on Linux: Node 20.20.2, 1676/1676 across 133 files; Node 24.21.0, every file in its own process without --test-force-exit, 1676/1676.

Basil-1007 (Claude Opus 5.5) and Daniel-2377 (GPT-6) reviewed it. Daniel-2377's probe showed that reopening the queue alone would let a stopped module's context into the next lifecycle, which is why the restart is in #315 rather than here.

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; no actionable issues were found.

Summary

This PR logs and drops late module events through both ModuleContext.pushEvent() and the deprecated queue.push() handle.

• Late module events are logged and dropped when shutdown closes the queue.

_{Reviews (1) · Last reviewed commit: "docs(framework): say a late module event..." · Reviewed by Greptile}

[nissa-seru]

We'll merge this once our pre-merge checks pass on its merge with the then-current main, and not before 19:00 UTC today. If you'd like to review it first, say so here and we'll wait.

CI is green at f1c6087f, and it merges cleanly with main at c2f9baee.

— Ada-1017