[nissa-seru]

After this change, start() throws and addModule() rejects once a stop() is admitted, for good, whether that stop completes or fails, so a stop ends its AgentFramework instance.

Before, a start() after a settled stop() could begin a second lifecycle on the same instance, and that lifecycle didn't work (#315). @rergards supported ending the instance instead, as an explicit breaking change (comment on #315), and this is that change, with a breaking changelog entry. A host that wants to go on after a stop creates a new AgentFramework on the store. After a failed stop, it first calls stop() again, until a call resolves, unless that stop left its owned store closed, so that stop() can't be tried again. The refusal's text says which applies. The second commit, a02f169c69, removes EventGate.resumeSleep(), whose documented purpose was that restart, as a second breaking change. On Linux with Node 24.22.1, the 15 test files this change touches pass at its head, c3cb848994. At a02f169c69, before main at 0.30.0 was merged in, 9 of their tests failed on the source of e85c57db9a, the base then.

Problem

At e85c57db9a, start() and addModule() are refused while a stop() runs (#532). They're also refused after a stop that closed a store the framework owns, or that closed its context managers and then failed to close that store. In every other case, once a stop() has settled, start() begins a new lifecycle on the same instance. 0.22.0's changelog says so ("A start() after a finished stop() starts a new lifecycle"), and 0.24.0's leaves what it should do as #315's open question.

Our runs at that commit show that this lifecycle doesn't work. After a completed stop() on a store the framework doesn't own, and a start():

• The event queue stays closed. pushEvent() of an external message or a module's event throws Queue is closed.
• The maintenance tick, an operator operation, is refused. It throws maintain refused: the framework is stopping.
• The push coalescer, the liveness watchdog and the MCPL servers stay stopped.
• Events the queue held when the stop closed it are processed in the new lifecycle, by a new module of the same name.

Turns woken outside the queue did reach the model, in our runs or the base's tests: a sleep's wake, a heartbeat's, a budget restart left pending and a nudge. The nudge's turn then failed at its model's call of a module's tool, with Queue is closed. After a failed stop(), start() is allowed too, and its lifecycle has the same closed queue.

!Closes #315.

Changes

Line numbers are in src/framework.ts at a02f169c69 unless another file is named.

• The refusal. start() (:4763) and addModule() (:6913) each first call refuseOnceStopped (:4877), which reads the instance's stop state (stopState, :3287). A stop() sets that state when it's admitted, and nothing sets it back to 'none'. A stop() whose budget argument is refused rejects with a RangeError (:4853) and isn't admitted, so it changes nothing. The refusal's text depends on that stop:

  • while it runs: start() refused: the framework is stopping, as before;
  • after it completed: start() refused: this framework has stopped, and a stopped framework doesn't start again. Create a new AgentFramework on its store to go on, with its storePath if it opened the store itself.;
  • after it failed: that a failed stop() may have left its cleanup or final persistence unfinished, and to call stop() again, since only once a stop() of this instance resolves should a new AgentFramework use its store, with its storePath if this one opened the store itself, or another instance use anything this one shares;
  • after it failed and left its owned store closed: that stop() can't be tried again, with that stop's failure as the error's cause.

  addModule()'s texts are the same, with its own name. They replace Cannot start a new lifecycle: owned store is closed and Cannot start a new lifecycle: stop() closed its context managers, and then failed to close its owned store.

• addModule() refuses before it checks the module's name against MCPL servers' tool prefixes (:6914), so a stopped framework's addModule() says it has stopped even for a name a server's prefix holds.

• stop() keeps its cleanup and its retry. Its doc (:4801) now says it ends the instance.

• Removed, since each existed only for a later lifecycle on the same instance:

  • the clearing of a completed stop in resetCompletedStop(), which refuseOnceStopped replaces, so a completed stop() keeps its settled promise;
  • the ownedStoreManagersClosed flag and closeOpenManagers()'s return value, which only fed one of the two refusals refuseOnceStopped replaces. That case is now refused as after any failed stop();
  • start()'s reopening of provider admission;
  • the lifecycle generation, which the event loop and a turn's checks compared, and with it the texts of turns dropped because "the framework was stopped and started again". One behaviour changes with it. A turn that runUntilIdle() began before the first start(), and that's still being assembled when that start() comes, now goes on, where before it was dropped;
  • start()'s call to EventGate.resumeSleep().

• The withheld-spill gate was closed for the lifecycle generation a stop ended. It's now a flag (guardSpillsClosed, :7779) that stop() clears as it begins (:5028) and sets at its drain (:5296), so a stop() tried again after a failed one reopens it until its own drain.

• Kept: start()'s loop that puts its MCPL servers' addresses in force (:4773), since it makes this framework's entries the ones in force where another framework has configured the same server id since.

• start()'s doc (:4742) says what a new instance on the store keeps: what the store holds, and, with the heartbeat on and the same heartbeat state file, the heartbeat's schedule, so a tick or a reminder that fell due meanwhile fires once, shortly after it starts. It says what's lost with the old instance, as on a process restart: an agent's sleep and its wake, a self-wake, the inference requests still queued, a re-armed turn's wait and count, and the redo stack. It names A wake_in_seconds self-wake and a sleep don't survive a restart #627, which is about keeping a sleep and a self-wake across a restart, and quiesce() and resume() for pausing one framework in place.

• Docs and comments. docs/tool-result-guard.md's paragraph on stop now says that a stopped framework doesn't start again. The comments that described a restart of the same instance no longer do.

• The changelog entry, changelog.d/315-stop-ends-its-instance.breaking.md, names who needs to act and how to migrate, what a new instance keeps and loses, and what's unchanged.

EventGate.resumeSleep() removed, in a02f169c69

resumeSleep()'s doc gave its purpose as arming a disposed gate's timers again "for a lifecycle that starts after a stop()". At e85c57db9a the framework's start() called it, and with this change nothing in src does. It's a public method of an exported class, so removing it is a breaking change of its own, with its own changelog line. The reset of the gate's disposed mark, which only it made, goes with it, so nothing arms a disposed gate's sleep or self-wake timer again. Its tests go too. We found no call of it on the main branches of connectome-host (0db863c), connectome-smoke (14b7c55) and antra-tess/chapterx, fetched on Oct 28.

Since a02f169c69

• e20be12455 merges main at 0.30.0 (630e2a3a07), which includes feat(dendrite): one registry, lifecycle and fork primitive for agents; admission, reader forks, the all-except scope and speech.locus (#232, #77, #270) #546. One hunk conflicted, in start(), where feat(dendrite): one registry, lifecycle and fork primitive for agents; admission, reader forks, the all-except scope and speech.locus (#232, #77, #270) #546 added this.earlyTraces = null; among lines this change removes. The merge keeps that line and removes the others. git diff 630e2a3a07 e20be12455 changes the same lines as git diff e85c57db9a a02f169c69.
• c3cb848994 adds "with its storePath if this one opened the store itself" to the failed stop's refusal. The completed stop's refusal already named storePath.

Who needs to act

• A host that calls start() or addModule() after stop() creates a new AgentFramework on the store instead, with the same borrowed store or the same storePath. After a failed stop(), it calls stop() again first, until a call resolves. Where the failed stop left its owned store closed, stop() can't be tried again, and the refusal carries that stop's failure as its cause.
• Code that calls EventGate.resumeSleep() creates a new AgentFramework, whose gate is its own.

With other open pull requests

By git merge-tree on Oct 29, this head contains main at 0.30.0 (630e2a3a07). Of the open pull requests that merge clean onto 630e2a3a07, one conflicts with this head: #844, which has its own section below. Of those that already conflict with 630e2a3a07, this head adds conflicting regions to four:

• feat(mcpl): require provider credentials for opt-in WebSocket dials #870 (0fdee5bc0c) and fix: a turn whose compile is refused for budget waits for compression, then runs #361 (5e41150d0a), from one region to two in src/framework.ts;
• fix(routing): a turn from a non-channel surface pins no inferred locus #190 (b2f6b4adbf), one region in src/gate/event-gate.ts;
• fix(gate): persist sleep and self-wake intent across restarts; re-arm on backward clock step #194 (e91cfb6852), from three regions to four in src/framework.ts, and from four to seven in src/gate/event-gate.ts.

With #844

@tel-0s, by git merge-tree on Oct 29, #844 (219a23706e), a draft, conflicts with this head in four files:

• src/framework.ts, in two comments in stopOwned() that this change rewords. feat(presentation): one record, a presentation index per agent — the deferral queue replaced (#291 step 3) #844 rewords the first too, and removes the second with the code after it.
• test/reinit-after-branch-move.test.ts, in a test where this change replaces starting the stopped framework again with a new AgentFramework on its store. feat(presentation): one record, a presentation index per agent — the deferral queue replaced (#291 step 3) #844 adds a presentAtEndOf() call there.
• test/route-failure-targeting.test.ts and test/stop-with-work-in-flight.test.ts, in their imports.

Tests

• test/stop-ends-its-instance.test.ts, new, with eight tests:

  • after a completed stop(), start() and addModule() are refused, and stop() stays settled without tearing down again;
  • a stop() of a framework never started ends it too, with an owned store and with a borrowed one;
  • after a failed stop(), both are refused through each retry, until one resolves, and then for good;
  • after a stop() whose wait on the event loop timed out, start() is refused, and the retry waits for that loop before it resolves;
  • after a failed stop() that closed its owned store, the refusal carries that stop's failure, which stop() rejects with again;
  • a stop() whose budget is refused leaves the lifecycle as it was, so a running framework still adds modules, and one never started starts;
  • a new AgentFramework on a stopped one's borrowed store takes an event and runs a tool call;
  • a turn that runUntilIdle() began before the first start(), held in a module's gatherContext() until after that start(), reaches the model.

  The first four also check addModule() with a module whose name a server's tool prefix holds.

• test/start-during-stop.test.ts: a call made in stop()'s first synchronous steps is refused for addModule() as well as start().

• test/tool-result-guard.test.ts: a stop() tried again lets withheld spills write until its own drain. test/tool-result-blocks.test.ts: start() puts its servers' addresses in force over another framework's for the same id.

• The restart's working cases, as tests at the base pinned them:

  • A sleep across a stop. In test/event-gate-sleep.test.ts, "a framework stopped while its agent sleeps wakes nothing until it's started again, then wakes the agent" now checks only that it wakes nothing once stopped, and "a sleep that ended while stopped wakes the agent in one turn with a request already pending at start" is removed.
  • A budget restart. In test/stop-with-work-in-flight.test.ts, "a budget restart taken up after a stop() and a start() marks its agent inferring again" is removed.

• test/shutdown-errors.test.ts's "borrowed-store lifecycle changes invalidate a successful stop memo" (ea7e0435) is removed. After a completed stop(), it added a module, stopped the framework, started it and stopped it again. The new file's first test checks that a completed stop() stays settled.

• The other tests that started a stopped instance again now check their property within one stop, or on a new AgentFramework on the stopped one's store. Those that tested what a restart itself did, by running one or by advancing the lifecycle generation as one did, are removed, in test/start-during-stop.test.ts, test/stop-without-stream.test.ts, test/present-while-acting.test.ts, test/tool-result-guard.test.ts and test/turn-continuation.test.ts.

• a02f169c69 removes resumeSleep()'s three tests in test/event-gate-sleep.test.ts, and the halves of two others that armed a timer after it.

On Linux with Node 24.22.1, npm 11.19.1 and TypeScript 7.0.2, each tree installed with npm install, which resolved chronicle 0.4.0, context-manager 0.23.1, mcpl-core 0.4.0, membrane 0.8.0, @modelcontextprotocol/client and @modelcontextprotocol/server 2.4.0, discord.js 14.27.0, ws 8.22.0 and chokidar 4.0.3:

• At a02f169c69, in a copy of a clean checkout, the build exits 0, and the 15 test files this change touches pass 840 of 840.
• Red first: with e85c57db9a's src and a02f169c69's test files, the build exits 0, and 9 of the 840 tests fail. They're the new file's five tests of the refusal and its test of the turn runUntilIdle() began, and one test each in test/reinit-after-branch-move.test.ts, test/compression-after-release.test.ts and test/shutdown-errors.test.ts whose expectations this change updates.

On Linux with Node 24.22.1, npm 11.19.1 and TypeScript 7.0.2, after main at 0.30.0 was merged in, npm install resolved chronicle 0.5.0, context-manager 0.24.0, mcpl-core 0.4.0, membrane 0.8.0, @modelcontextprotocol/client and @modelcontextprotocol/server 2.4.0, discord.js 14.27.0, ws 8.22.0 and chokidar 4.0.3. With those:

• At c3cb848994, in a copy of a clean checkout, the build exits 0, and the 15 test files this change touches pass 846 of 846. main added 6 of those tests.
• At e20be12455, in a copy of a clean checkout, the build exits 0, and those 15 files pass 846 of 846. So do 16 more test files, 475 of 475: those that main added or changed since e85c57db9a and in which a call of .stop() comes before a call of .start(), found by a text match.
• Red first for c3cb848994: with e20be12455's src and c3cb848994's test/stop-ends-its-instance.test.ts, the build exits 0, and 2 of that file's 8 tests fail, the two that expect the failed stop's refusal.

What a new instance keeps, in runs of probes outside this pull request, each in a copy of a clean checkout, at a02f169c69 and again at c3cb848994, with the same outcomes:

• The heartbeat's schedule. A framework with the heartbeat on was started and stopped, and the next tick in its saved state was moved into the past. A new framework on the same store and heartbeat state file, configured with another heartbeat message, ticked about 10 s after it started, and the state still held the first framework's message.
• Not a sleep. An agent was put to sleep for 1 s, its framework was stopped, and 1.5 s passed. A new framework on the same store held no sleep for it before it started, and in the 3 s after its start it made no model call and traced no sleep:expired. With a nudge for the agent before the new framework's start, it made one model call, the nudge's.

Not verified

• The whole suite at the head. We ran the 15 test files this change touches, and at e20be12455 the 16 more above.
• What a new instance loses, beyond a sleep. For the rest of start()'s list we ran nothing, and have only what lines of the code at a02f169c69 say: src/gate/event-gate.ts:2135 declares selfWakeDue as a field of the event gate, src/framework.ts:3316 and src/framework.ts:3713 declare pendingRequests and redoStacks as fields of the framework, and src/types/framework.ts:259 says a re-armed turn's wait and count "are kept in memory".
• Node 22 and macOS. Every run was on Linux with Node 24.22.1.

What this leaves

• stop() resolves while an addModule()'s start() is pending, and module:added follows it #882: an addModule() made before a stop() can still be running its module's start() when that stop() runs. stop() doesn't wait for that start(). It stops the module, removes it from the registry and resolves, and once the start() finishes, the framework emits module:added for it and addModule() resolves. Our internal review of this pull request found it, and this pull request doesn't change it.

---

• Changelog fragment added: changelog.d/315-stop-ends-its-instance.breaking.md.

Gideon-2613 made the change and ran its probes. Cordelia-2434 proposed ending the instance, and Ada-1017 made the design calls. Ezra-2423 weighed what each part is worth, and read the fixes that followed until the last test was added. Stanley-2495 read that test, and Humphrey-2407 the comment fix after it. Stanley-2495 also read the merge of main at 0.30.0, and Ezra-2423 the clause on storePath. Oscar-1808 set its scope. Laurel-2386 wrote this description.