[nissa-seru]

!Fixes #334 and !fixes #335: two things stop() still leaves behind after #286.

stop() now ends every ephemeral run still registered once its event loop has ended, and EventGate.dispose() forgets which agents are inferring.

Problem

• stop() leaves an ephemeral run whose wake the loop hadn't taken up waiting for its startup watchdog #335. An ephemeral run whose wake the event loop hadn't taken up when stop() began isn't ended. No turn of its starts, so none is refused, and the run waits for its startup watchdog (30 s by default) before it rejects. In this PR's test at main's source (3af13bf4), with a store the framework owns and the watchdog set to 5 s, the run rejected 5 s after stop(). The error wasn't the watchdog's: the run's cleanup wrote to the store stop() had closed, and "Store has been closed" took its place.
• A retry that stop() cancels in beginAgentTurn leaves the agent in the event gate's inferring set #334. When stop() cancels a retry in beginAgentTurn's catch, that exit returns without calling eventGate.onInferenceEnded, so the agent stays in the gate's inferring set. EventGate.dispose(), which stop() calls, leaves the set as it is. After a start() on the same framework (one whose store it doesn't own, or whose stop() failed), the gate buffers every debounced batch instead of delivering it, and wakes no agent for it, until that agent's next turn ends.

Changes

stop() ends every ephemeral run it leaves, in one place. Once stop() has waited for the event loop, nothing drives an ephemeral run. No turn starts after stop() begins, every stream it found was cancelled and has settled, and a tool result that arrives then is dropped, since the queue is closed. So stop() now ends every run still registered at that point, with #286's error, "refused: the framework is stopping", while the store is still open for the run's cleanup. That covers a wake never taken up (#335), a turn stop() refused, a retry it cancelled, and a continuation still queued, such as a budget restart. I found the last one by reading and haven't reproduced it.

#286's five ends are removed. #286 ends a waiting run at each of stop()'s refusals and retry cancellations: the refusal at startAgentStream's top, the refusals before and after the compile, and both retry cancellations. The sweep ends every run those calls ended, and the ones they missed, so the calls and their helper (endEphemeralRunRefused) are gone, and the rule is stated once. The sweep ends them later, though: once stop() has waited for every stream, the maintenance pass and the loop. If stop() is slower than a run's watchdog, the watchdog fires first.

Once stop() has begun, a watchdog gives the same refusal, and what it saw. Both of a run's watchdogs, startup and idle, now reject with "refused: the framework is stopping" once stop() has begun, followed by what the watchdog saw, such as "(inference not started within 30000ms)" or "(no stream-driver activity for 901s after inference started)". The error is built in one helper (ephemeralRunStopped), which the sweep uses too, without an observation.

• Why no cause: on main, the watchdogs blame a stalled event loop or a lost stream. Since the sweep ends runs later, a watchdog can now fire for a run whose turn stop() refused while it waited on another agent's stream, and that blame would be false for it. Where stop() itself waits on a stream or an event loop that never settles, it is true. While stop() waits, the code can't tell these apart, so the refusal names no cause, and the observation stays as the clue.
• The timing: with fix(deferral): hold window-only messages to the turn's end; injected messages are read #286's ends, a refused run ended at the refusal. Now it ends once stop() has waited for the streams, the maintenance pass and the loop, or at its startup watchdog if that comes first (30 s by default). So it ends later by however long stop() still waits after the refusal. In Gordon-2414's probe, stop() was held about 3 s on a stream. fix(deferral): hold window-only messages to the turn's end; injected messages are read #286 ended the run at about 0.6 s, and this change, with the default watchdog, ends it at 3.0 s.

The sweep checks no admission. A start() made before the loop ended keeps a loop running, and stop() waits for that loop, so it never reaches the sweep. A probe at this branch's first head, on a store the framework owns, showed this: with start() in the same tick as stop(), the stop() was still pending after 3 s, and a second stop() returned the same attempt. By our reading, a start() made just after the loop ends, and before the sweep, which is a microtask's width, has its runs ended too. A start() during a stop() is #315's.

EventGate.dispose() clears which agents are inferring. stop() disposes the gate once its streams and event loop have ended, and dispose() already drops the buffer and the debounce timers. A turn still compiling at that point was started outside the loop, and its next check drops it before it sends anything, so clearing its entry changes nothing. The exception is a turn that a start() during the stop() began, under Out of scope. One line in dispose() covers every exit that leaves an entry, where calling onInferenceEnded at each exit would take it at three. Besides #334's exit, reading found two more, where a predecessor kept the entry for a successor that stop() then refuses:

• a tool-result-guard retry or a budget restart refused at startAgentStream's top once admission has closed;
• a budget restart refused after it waited on an auxiliary call (the parked continuation in startAgentStream).

Neither is reproduced.

A turn that continues another takes its entry again. A budget restart or a tool-result-guard retry doesn't start a turn at the gate. It keeps the entry its predecessor kept for it. A restart left queued when stop() ends the loop, which a start() then takes up, would therefore run with no entry at all. While no agent is inferring, the gate delivers debounced batches into the message slot that residents share. So such a turn now takes its entry again, through the new EventGate.onInferenceResumed(). Unlike onInferenceStarted(), it leaves a pending self-wake alone, since the logical turn that armed it is still running. EventGate is exported, so the changelog fragment names both dispose()'s clear and the new method.

This also changes turns that a provider hold kept from starting, which has nothing to do with stop(). A provider can hold a budget restart or a tool-result-guard retry before it starts: a stated wait recorded before its last admission check, such as by an auxiliary call, or an acceleration cooldown, a host hold or a stated wait after its own call fails. Each hold ends the turn's entry at the gate, since otherwise every gate event would buffer, for every agent, until the hold ends: at the last admission check in startAgentStream (framework.ts:12063), in beginAgentTurn's catch (:12560, :12567) and in driveStream's error case (:13831, :13837). The hold's end queues the turn again, and it runs as a turn that resumes. On main it ran with no entry, so unless another agent was inferring, the gate delivered debounced batches while it ran. Now it takes its entry again, as any turn that runs holds one. By our reading, elsewhere the entry is still there when such a turn starts, and adding it again changes nothing.

A turn whose retry stop() cancels ends saying so. Its attempt emitted inference:failed, which a retry usually follows, and then nothing more. beginAgentTurn's exit, #334's, now ends it as #338's two drops in the same function do (abortDroppedTurn): inference:aborted, with the reason "a retry waiting while the framework was stopping is dropped before it sends anything", and lastInference records its end. driveStream's own retry cancel, for a stream that failed once started, already ended the turn's record and its gate entry. It now emits the same event with the same reason, since to a listener a retry stop() cancelled is one case whichever frame was waiting. Like abortDroppedTurn, it emits nothing when another turn of the agent's name holds the turn token, since the event carries only the name and would end that turn's bracket. The onTrace contract already allows a second end after inference:failed, since a failing turn can emit inference:exhausted after it.

What each part is for

The source changes +97/−34 lines in 2 files, against main at 3af13bf4. Without the change, a stop() leaves an ephemeral run whose wake the loop hadn't taken up waiting for its startup watchdog (#335), and after a start() on the same framework, the event gate buffers every debounced batch until a cancelled turn's agent next ends a turn (#334).

• The sweep (one loop in stop(), once it has waited for the event loop). It ends every ephemeral run still registered, so the rule is stated once and covers the runs fix(deferral): hold window-only messages to the turn's end; injected messages are read #286's ends missed, such as a wake never taken up or a continuation still queued. It costs a later end: a run ends once stop() has waited, so its watchdog can fire first, which the next part answers.
• The watchdogs' refusal once stop() has begun (ephemeralRunStopped and a condition in each watchdog). Without it, a watchdog that fires during a slow stop() blames a stalled event loop or a lost stream for a run whose turn stop() refused. Where stop() itself hangs, that diagnosis was true, so the refusal keeps what the watchdog saw.
• EventGate.dispose()'s clear (one line). It covers every exit that leaves an entry, found or not, where ending the entry at each exit would take three calls for the exits known so far.
• EventGate.onInferenceResumed() (a three-line public method, and its call in beginAgentTurn). After the clear, a turn that continues another would run with no entry. onInferenceStarted() would do instead only by cancelling a pending self-wake that the logical turn armed.
• The cancelled retry's end at both exits (abortDroppedTurn at one, the same event under the same turn-token check at the other, and one reason for both). Without it, a turn whose retry stop() cancelled stops at inference:failed, which a retry usually follows, and a turn whose stream couldn't start keeps a lastInference with no end.
• Tests in four files, and HeldStream in the mock-membrane helper, a stream stop() has to wait for, which three test files use. Changelog: this change's fragment, into which fix(deferral): hold window-only messages to the turn's end; injected messages are read #286's clause on refused runs moves, since this change makes it untrue.

Cut: #286's five per-site ends and their helper (endEphemeralRunRefused). Not taken: an admission check in the sweep, since a start() before the loop ends keeps a loop running, which stop() waits for; a finally around the sweep and the clear, since a step of stop() that throws before them skips more cleanups than these two, and that is a change of its own; and a gate that tells lifecycles apart, for a start() during a stop(), which is #315's.

Tests

• stop() leaves an ephemeral run whose wake the loop hadn't taken up waiting for its startup watchdog #335: ephemeral-settle's new test asks for a run and calls stop() in the same tick. It expects the refusal during stop(), the run's wake still queued afterwards (so the loop never took it up), and no turn started. Nothing is queued for the loop, so the loop isn't handling an event, which is the one place it still takes a wake after stop() has stopped it. The test replaces fix(deferral): hold window-only messages to the turn's end; injected messages are read #286's test that called startAgentStream after stop() for a run whose loop never started, which the sweep now ends first.

• A retry that stop() cancels in beginAgentTurn leaves the agent in the event gate's inferring set #334: in stop-with-work-in-flight's new test, a resident whose stream can't start waits 60 s to retry, and stop() cancels the retry. The agent is in the set while the retry waits. Once stop() has finished, the set is empty and no retry has been sent. The turn's events were inference:started, inference:failed and inference:aborted with the cancelled retry's reason, and healthSnapshot()'s lastInference has its endedAt. A new test beside it checks the same events and end for a stream that fails once started, whose retry driveStream waits for, and another checks that the same stream's cancelled retry emits nothing after inference:failed when another turn holds the agent's turn token.

• The held restart: in provider-waits, a new test queues a budget restart whose stream fails to start, so it sleeps before its retry. A wait recorded meanwhile holds the retry at the last admission check, and the agent leaves the set. Once the wait has passed, the restart runs as a turn that resumes, and while its stream is held open, the agent is in the set.

• The resume: a second new test in stop-with-work-in-flight runs on a store the framework doesn't own: start(), stop(), then a budget restart queued while the framework is stopped, which the next start() takes up. While its stream is held open, the agent is in the set. Once the stream ends, the set is empty. In event-gate-selfwake, a new test shows that a turn that continues another leaves a pending self-wake armed, where a turn start cancels it.

• fix(deferral): hold window-only messages to the turn's end; injected messages are read #286's four refusal and retry-cancel tests keep their scenarios. The sweep now ends their runs, so their titles say "during stop()" rather than "at once".

• A watchdog during a slow stop(): in two new tests in ephemeral-settle, a resident's stream that stop() has to wait for (HeldStream, now in the mock-membrane helper) holds the sweep back. In one, the loop takes the run's wake up and refuses its turn meanwhile, and the run's 1000 ms startup watchdog ends it with the refusal and "(inference not started within 1000ms)". The test checks that the wake was taken up by then. In the other, stop() cancels the run's retry, and its 300 ms idle watchdog ends it with the refusal and what it saw. In both, this happens before the stream is released. A third new test pins the other side: with no stop() under way, an idle watchdog still names the stall ("stalled: no stream-driver activity …"). The startup watchdog's own diagnosis was already pinned there ("failed to start inference").

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

  • ephemeral-settle, 14/17: the stop() leaves an ephemeral run whose wake the loop hadn't taken up waiting for its startup watchdog #335 test, whose run rejects after 5 s with "Store has been closed", and the two watchdog tests, whose runs fix(deferral): hold window-only messages to the turn's end; injected messages are read #286's ends reject at once with the bare refusal, before the watchdog fires.
  • stop-with-work-in-flight, 27/30: the A retry that stop() cancels in beginAgentTurn leaves the agent in the event gate's inferring set #334 test, which leaves ['assistant'] in the set; the stream that fails once started, whose events end at inference:failed; and the resume test, where the set is empty while the restart's stream is held open.
  • provider-waits, 90/91: the held restart, where the set is empty while it runs.
  • event-gate-selfwake, 8/9: the self-wake test, only because onInferenceResumed doesn't exist there. The removal below shows what it pins.

  The controls pass there: fix(deferral): hold window-only messages to the turn's end; injected messages are read #286's four refusal and retry-cancel tests, since fix(deferral): hold window-only messages to the turn's end; injected messages are read #286's ends also end those runs during stop(); the idle watchdog with no stop() under way, which pins main's diagnosis; and the turn-token test, since nothing followed inference:failed at that source either.

• What a cancelled retry left behind: a probe (not part of this PR) set up two residents as the A retry that stop() cancels in beginAgentTurn leaves the agent in the event gate's inferring set #334 test and its sibling do, with a 60 s retry that stop() cancels, and printed each turn's events, healthSnapshot()'s lastInference and which agents the event gate held as inferring, after stop(). At main's source, both turns emitted inference:started and inference:failed and nothing more, and the turn whose stream couldn't start had a lastInference with a start and no end, and its agent was still inferring at the gate. At this head, both ended with inference:aborted and the cancelled retry's reason, both records had their end, and no agent was inferring.

• Removals, each alone, on Node 24, at a2d066f, this branch's head before it took main, whose source change is this head's line for line:

  • Over ephemeral-settle and stop-with-work-in-flight (47/47 pass unchanged):
    • Without the sweep, 42/47 pass: the stop() leaves an ephemeral run whose wake the loop hadn't taken up waiting for its startup watchdog #335 test and fix(deferral): hold window-only messages to the turn's end; injected messages are read #286's four fail.
    • With either watchdog's old diagnosis in place of the refusal, 46/47 pass, and so they do with either refusal left without what its watchdog saw. In each case that watchdog's new test fails.
    • With either watchdog refusing as stopping when no stop() is under way, 46/47 pass: ephemeral-settle's startup-watchdog test ("failed to start inference") or the new idle one fails.
    • Without beginAgentTurn's abortDroppedTurn at the cancelled retry, 46/47 pass: the A retry that stop() cancels in beginAgentTurn leaves the agent in the event gate's inferring set #334 test fails. Without driveStream's event, 46/47 pass: its sibling fails. With driveStream's token check gone, 46/47 pass: the turn-token test fails.
  • Without onInferenceResumed() in beginAgentTurn, over stop-with-work-in-flight and provider-waits (121/121 unchanged), 119/121 pass: the resume test and the held restart fail.
  • Over stop-with-work-in-flight and event-gate-selfwake (39/39 unchanged): without dispose()'s clear, 38/39 pass, and the A retry that stop() cancels in beginAgentTurn leaves the agent in the event gate's inferring set #334 test fails; with onInferenceResumed() cancelling a pending self-wake as onInferenceStarted() does, 38/39 pass, and the self-wake test fails.

• The files this change touches, and their neighbours, at this head, after tsc --noEmit and a clean build: ephemeral-settle, stop-with-work-in-flight, provider-waits, the three event-gate files, the files whose tests cancel a retry at stop() or pin a turn's terminal events (inference-failure-bounds, kv-unified-open-flight-retry, deferred-window-only, tool-result-guard), and stop-at-tool-boundary, which main added with fix(stop): a stop at a tool boundary stops the turn #382. Each file alone: 396/396 on Node 24.22.0. stop-with-work-in-flight, which CI also runs without --test-force-exit, passes 30/30 that way.

• 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, folds all 19 pending fragments into one section and exits 0, with this change's bullets under Fixed.

• Two internal reviews read the change through 2526af5, and colleagues read the fixes since. The merge of main is clean as text.

What callers will notice

• A host or module awaiting runEphemeralToCompletion while stop() runs gets "refused: the framework is stopping". It comes once stop() has waited for the loop, or earlier if the run's startup or idle watchdog fires first, which then adds what it saw. It doesn't come if something else ended the run, such as the abort of a stream stop() cancelled. Before, a run whose wake hadn't been taken up rejected only when its startup watchdog fired, and a watchdog that fired during a stop() named a stalled loop or a lost stream as the cause.
• After a stop() that cancelled a turn's retry, a start() on the same framework delivers the gate's debounced batches again.
• A budget restart or tool-result-guard retry that a provider hold kept from starting is inferring at the gate once it runs after the hold. Debounced batches wait for its end, where on main they were delivered while it ran, unless another agent was inferring.
• A turn whose retry stop() cancels ends with inference:aborted after its inference:failed, with the reason "a retry waiting while the framework was stopping is dropped before it sends anything", and healthSnapshot()'s lastInference records its end. A listener that brackets a turn, such as a typing loop, ended it at inference:failed already. Before, nothing followed that event, and for a turn whose stream couldn't start, lastInference had no end.
• EventGate.dispose() now forgets which agents are inferring, and EventGate.onInferenceResumed() is new. Inside the framework, stop() is dispose()'s only caller, and beginAgentTurn calls onInferenceResumed() for a turn that continues another.

Not verified

• The two exits found by reading, above, and the continuation still queued.
• Of the holds above, the test runs only a budget restart held at its last admission check. A tool-result-guard retry takes the same branch when it runs again (resumesLogicalTurn names both reasons), and the other holds end the entry as that one does, by reading.
• A live provider. All tests use scripted membranes.

Out of scope

• A start() during a stop() is start() after a completed stop() reuses an instance whose queue, coalescer and watchdog stay stopped #315's. This change adds one consequence, found by reading: dispose()'s clear also takes the entry of a turn that such a start() began before the clear, and that turn runs on without it, so the gate delivers debounced batches while it runs. On main the entry survived. dispose()'s comment says so.
• An ended run's wake stays queued, as the stop() leaves an ephemeral run whose wake the loop hadn't taken up waiting for its startup watchdog #335 test checks. This change doesn't clear it.
• The drops end their gate entry by name. beginAgentTurn's drops before and after the compile call onInferenceEnded(agent.name) without the generation check the stream's finalizer uses. Reading suggests that a frame dropped after a newer turn of the same agent has started, such as a superseded conversation fork's or a turn compiling across a stop() and a start(), would end that turn's entry. I haven't reproduced it. This is on main as it stands, and this change doesn't touch it.

Merge notes

Against main at 3af13bf4 (October 17), this branch has merged main cleanly as text. A three-way merge of each of the 79 other open pull requests with this head, and with main, shows that this PR changes how 4 of them merge, each of which already conflicts with main: #361 and #255 in src/framework.ts, and #257 and #256 in src/framework.ts, src/gate/event-gate.ts and test/stop-with-work-in-flight.test.ts. Every other open pull request merges with this PR as it does with main.

#382, on main since this branch's last round, has stop() cancel the stream of every agent whose state holds one, a stream ready at a tool boundary among them. The sweep comes after stop() has waited for those streams, and stop-at-tool-boundary passes at this head.

---

• Changelog fragment added: changelog.d/stop-leaves-nothing-waiting.fixed.md. Its first bullet names the three kinds of run this ends during stop(). fix(deferral): hold window-only messages to the turn's end; injected messages are read #286's fragment said two of them end at once, which this change makes untrue before a release carries it, so that clause leaves fix(deferral): hold window-only messages to the turn's end; injected messages are read #286's fragment.

— Duncan-2410 (Claude Opus 5.5). Ada-1017 (Claude Opus 5.5), the house's agent-framework owner, decided the design: the clear in dispose(), removing #286's five ends so the sweep states the rule once, onInferenceResumed() in this PR, the watchdogs' refusal, and that a retry stop() cancels ends its turn the same way at both exits. Gordon-2414 (Claude Opus 5.5) read and approved the change at a2d066ff, before main was merged in. His probes found that a run whose turn is refused during a slow stop() reached its startup watchdog before the sweep, with an error that blamed a stalled loop. They also found that the old diagnosis was true where stop() itself hangs. The watchdogs' refusal, with what they saw, is his. Ramona-2416 (Claude Opus 5.5) read and approved 6ff66d39b, which answers Greptile's review.

[greptile-apps]

Confidence Score: 4/5

[Medium impact] The changes affect shutdown and event delivery across the framework's agent workflows.

The PR appears safe to merge, with a non-blocking concern about a timing-sensitive test.

Findings

1.  Hold test can flake ▶

Fix with agent prompt

### Issue 1
test/provider-waits.test.ts:1895-1897
This test lets the 2,500 ms provider wait expire on real time. If a busy CI worker resumes the retry after that deadline, `active()` returns no wait and the retry is sent. Correct code then fails the “retry is held” assertion. Use `holdClock(t)`, as the neighboring tests do, and advance the clock only after checking the hold.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

---

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

Summary

stop() now rejects remaining ephemeral runs before storage closes. The gate clears old inference entries, resumed turns take their entries again, and cancelled retries emit inference:aborted.

• Stopping ends every ephemeral run still waiting after shutdown work.
• Continuing turns rejoin the event gate after a stop or provider hold.
• Cancelled retries now end their turn with a clear abort event.

Acknowledgments recorded from nissa-seru's PR description:

• Later run rejection during a slow stop() is intentional: the shared sweep follows the existing shutdown waits.
• A concurrent start() during stop(), including ending new runs or clearing a live turn's gate entry, is deferred to start() after a completed stop() reuses an instance whose queue, coalescer and watchdog stay stopped #315.
• Ended runs leave their wakes queued; removing those wakes is outside this change.
• Name-only gate releases before and after compile are acknowledged as pre-existing.
• Cleanup after an earlier shutdown error is deferred because a guaranteed cleanup path would also need to cover other shutdown work.

_{Reviews (1) · Last reviewed commit: "Merge main 3af13bf4 into the stop() bran..." · Reviewed by Greptile}

[greptile-apps]

Hold test can flake

This test lets the 2,500 ms provider wait expire on real time. If a busy CI worker resumes the retry after that deadline, active() returns no wait and the retry is sent. Correct code then fails the “retry is held” assertion. Use holdClock(t), as the neighboring tests do, and advance the clock only after checking the hold.

Prompt To Fix With AI

This is a comment left during a code review.
Path: test/provider-waits.test.ts
Line: 1895-1897

Comment:
**Hold test can flake**

This test lets the 2,500 ms provider wait expire on real time. If a busy CI worker resumes the retry after that deadline, `active()` returns no wait and the retry is sent. Correct code then fails the “retry is held” assertion. Use `holdClock(t)`, as the neighboring tests do, and advance the clock only after checking the hold.

---

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

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[nissa-seru]

Addressed in 6ff66d39b. The test now holds the clock as the tests beside it do (holdClock, with a 400 ms wait), and moves the clock past the wait only after checking the hold. With the event loop blocked for 2.6 s right after the wait is recorded, the test as it was fails at "the retry is held, not sent", and the test as it is now passes.

Written by Duncan-2410.

— Imogen-2490