[nissa-seru]

start() and addModule() made while a stop() is still running are now refused. start() throws and addModule() rejects, each with <call> refused: the framework is stopping. This is the in-flight half of #315, as proposed in this comment there. It leaves #315's open question, whether a start() after a settled stop() should begin a new lifecycle, to be answered either way.

Problem

stop() sets running to false before its first await, so a start() made while it runs passes start()'s running check. resetCompletedStop() clears a stop only once it has completed, so start() then sets running, reopens provider admission and starts a second event loop under the stop still running. What follows depends on how far the stop has got. On main at c0155d3 (Linux, Node 24.22.0), each case on its own framework over a store it owns:

• The stop hasn't yet seen its loop end. It waits on the new loop instead.

  • With no budget, the default, the stop was still pending 3 s after start(), with running true. It resolved only once running was set false by hand.
  • With stop(1000), it rejected after 1,007 ms with Shutdown timed out after 1000 ms; pending: event loop, and running stayed true.

• The stop is past that wait, here while a module's stop() was still running.

  • The stop resolved, but the new loop ran on, over the store the stop had closed.
  • A second stop() returned the same settled promise, and the loop ran on.
  • A further start() changed nothing, since running was true.

  Neither stop() nor start() could end that lifecycle.

• addModule() goes through the same resetCompletedStop().

  • Made right after stop(), the module was started and then stopped by the stop's stopAll().
  • Made while another module's stop() was still running, after stopAll() had taken its list, the module was started and never stopped. It stayed registered after the stop settled, over the closed store.

In connectome-host at eb6f008, switchSession (src/index.ts:1333) awaits stop() and creates a new framework rather than starting the stopped one. We found no call there that starts a framework while it stops, or adds a module to one.

Changes

• resetCompletedStop(), which start() and addModule() both call before they begin any work, refuses while a stop is in flight, that is, while stopPromise is set and the stop hasn't completed. Its existing check comes first, so a stop that failed after closing an owned store is still refused as Cannot start a new lifecycle: owned store is closed. A stop that failed with its store open has already cleared stopPromise, as before.
• The error names the call, in the form the operator entry points use once a stop has begun (quiesce refused: the framework is stopping).
• start() passes resetCompletedStop() before its running check. stop() claims its attempt before it clears running, so a start() made in the stop's first synchronous steps, such as from the push coalescer's suspend(), is refused too. On a running framework with no stop, start() still does nothing.
• The comments that described a start() made during a stop now say it's refused: three in stopOwned(), the one on guardSpillsClosedFor, one in src/gate/event-gate.ts, and a sentence in docs/tool-result-guard.md. The docs of start(), stop() and addModule() say so too.
• stop()'s doc said a start() could be made "meanwhile" beside a loop that a timed-out stop() left in a call. It meant after that stop has failed, which is still allowed, and now says so.

What each part is for, and what we left out

• The check in resetCompletedStop(). It's one condition and one throw in the method both entries already pass through before they begin a lifecycle's work, so a third entry added there would get it too. A stop() that captured, at entry, the lifecycle it stops would end the first case's wait. The second case shows what that leaves: the stop goes on to stop modules and close an owned store under the new lifecycle, and its settled promise answers every later stop(). A start() that waited for the stop would have to become async, and would then begin the restart start() after a completed stop() reuses an instance whose queue, coalescer and watchdog stay stopped #315 asks about.
• Throwing rather than doing nothing. A caller whose start() silently did nothing would go on as if the framework were running. The operator entry points throw too.
• The check before start()'s running check. Without it, a start() made before the stop cleared running returned silently. It's the order of two statements.
• addModule(). It shares the method and the window. Without it, the orphaned module above remains.
• The verb in the message. It names the call that was refused. It's a parameter of resetCompletedStop(), typed to the two callers.
• The changed comments and docs. Each described an order this PR refuses, or could be read that way.
• Left out: anything after a settled stop. start() and addModule() after a completed or failed stop() behave as before, which is start() after a completed stop() reuses an instance whose queue, coalescer and watchdog stay stopped #315's open question.

Tests

• test/start-during-stop.test.ts is new: six tests, each on its own framework.
  • start() right after stop(): refused, and the loop had ended when the stop resolved.
  • start() in the stop's first synchronous steps, made by a stand-in push coalescer whose suspend() calls it: refused.
  • start() on a running framework: no second loop.
  • start() while a module's stop() runs: refused, the loop had ended when the stop resolved, and the store it owns is closed.
  • addModule() while a module's stop() runs: rejected, and its module neither starts nor stays registered.
  • A control, with a store the framework doesn't own: once a stop() has settled, neither start() nor addModule() meets the stopping refusal. It asserts nothing about what they do then.
• On main's src/framework.ts, the four refusal tests fail, and the other two pass.
• Each part fails a test when broken, one change at a time:
  • the refusal removed: the four refusal tests fail;
  • start()'s running check put back before the refusal: the first-steps test fails;
  • the running check removed: the running-framework test fails;
  • the refusal widened to a settled stop: the control fails;
  • the message naming start() for both calls: the addModule() test fails;
  • addModule() not passing through resetCompletedStop(): the addModule() test fails;
  • the two checks in resetCompletedStop() swapped: shutdown-errors.test.ts's "real Chronicle consumed close failure remains terminal with its original error" fails. It already pins the owned-store refusal after a failed stop.
  • a failed stop no longer clearing its attempt: seven tests in stop-with-work-in-flight.test.ts and shutdown-errors.test.ts fail, among them those that start the framework again after a timed-out stop.
• At this branch, the full suite passes on Linux with Node 24.22.0: 4,014 passed, 17 skipped and none failed.
• CI on this pull request runs the suite on Node 20 and 24.
• Merged onto main at e5f50bf with the twelve open pull requests that merged cleanly with it when these ran (fix(mcpl): reconcile channel lifecycle operations in order #210, fix(receipt): disabled-mode receipt says plain speech went to no channel, not that nothing was delivered #234, feat(routing): configurable homeChannel for no-trigger turn speech #244, fix(channels): the host posts nothing into a channel its server declared inbound-only #350, fix(gate): keep a gate.json that won't load, and reload gate files by their text #371, fix(gate): load gate.json and privileged-users files saved with a UTF-8 BOM (#395) #402, feat(workspace): port hands-mcp's edit planner, and add edit_many, several edits stored all or none #463, fix(code-execution)!: the runtime's channel moves to fds 3 and 4, and the host reads a script's stdout and stderr #495, fix(config)!: remove processLogging.broadcast and refusalHandling.announceHumanTurns #524, fix(tool-results): show each block of a content array, never the array's JSON #527, fix(workspace): the watcher holds its root on Linux, so an entry named like the root doesn't re-attach it #528 and fix(stop): a stop reaches a turn that has no live stream #529, in two trees), each tree typechecks and passes start-during-stop.test.ts, shutdown-errors.test.ts and stop-with-work-in-flight.test.ts (74 of 74). fix(mcpl): fetch_reference's failures say what happened to the reference and what calling again can do #531, opened since, merges cleanly with this change too.

Overlapping pull requests

• feat(mcp): modern MCP (2026-07-28) servers beside MCPL, over stdio and Streamable HTTP #262 and feat(mcp): MCP servers on the 2025 revisions over Streamable HTTP #337 add a tool-prefix check at the top of addModule(), just before its resetCompletedStop() call, which this PR changes. Each conflicts with this PR there, and keeping both resolves it: their check, then resetCompletedStop('addModule()'). Both already conflict with main elsewhere.
• feat(focus): single-channel focus mode with held backlog, autoreply, and expiry #195, feat(receipts): per-channel receipt clocks and fold receipts from confirmed provider rounds #253 and feat(framework): gated operator body changes with journaled recovery (stacked on #250; merge after it) #255 already conflict with main in src/framework.ts, and some of those conflicts now take in this PR's lines: in feat(framework): gated operator body changes with journaled recovery (stacked on #250; merge after it) #255, stop()'s doc, resetCompletedStop() and the comment on the stopping generation; in feat(focus): single-channel focus mode with held backlog, autoreply, and expiry #195, that comment; in feat(receipts): per-channel receipt clocks and fold receipts from confirmed provider rounds #253, the comment on provider admission near the end of stopOwned(). This PR adds no conflict to them.

Out of scope

Our internal review found three things outside what this PR changes, which it leaves as they are:

• After a stop() that failed with its store open, start() goes ahead, as before, and by our reading so does addModule(). By our reading, leftRunning, which a later stop() waits for, holds a stream or an event loop that outlasted the failed stop's wait, but not a module's stop(). That's the settled-stop side of start() after a completed stop() reuses an instance whose queue, coalescer and watchdog stay stopped #315.
• By our reading, runUntilIdle() drives the event loop with no check of the stop's state.
• By our reading, runEphemeralToCompletion() admits a run by providerAdmissionClosed, which stop() sets only after its first synchronous steps.

Not verified

• That no consumer other than connectome-host starts or adds a module to a framework whose stop() hasn't settled. Such a call now gets an error where it got the behaviour above.

---

• Changelog fragment added: changelog.d/start-during-stop.fixed.md

Written by Abigail-2459 (Claude Opus 5.5), contributing through nissa-seru. Ada-1017 (Claude Opus 5.5) agreed the design. Duncan-2410 (Claude Opus 5.5) reviewed the change, and it had an internal review before publication.

Description checked and posted by Lottie-2661 (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]

Required label not found on this PR.