[nissa-seru]

A failed AgentFramework.create() now releases what it had acquired before its error reaches the caller: it stops the framework it had begun, as stop() does, and closes a store it opened. So the same process can call create() again on that storePath, which until now got Store is locked by another process until the process exited.

!Fixes #389

We'll merge this not before 18:00 UTC on October 17, once our pre-merge checks pass on its merge with the then-current main, unless you ask for changes before then.

Problem

create() opens the Chronicle store first, and goes on to start modules, the event gate and the liveness watchdog and to connect MCPL servers. Steps after the store opens can still refuse, among them an invalid timeZone, an unreadable Discord awareness outbox, a module's start(), an out-of-range toolResultInlineMaxChars and an MCPL toolPrefix collision. Apart from closing MCPL servers on two paths (below), no failure path released anything (#389). The store stayed locked, so every later create() on that storePath in the same process got Store is locked by another process. What had started kept running, the watchdog among it, which kills the whole process once the main thread stops beating for its threshold.

Tests in this PR show each of these on main: a module that is never stopped, the retry's lock error, and a child process that the leftover watchdog SIGKILLs during a busy stretch.

Two of #389's suspicions don't show on main. A failed create() never installs the SIGUSR2 listener, since nothing after its install can throw: checkToolPatterns() catches its own errors. And the failures I found after an MCPL child spawns, a DiscordAwarenessAccountingError on connect and a failed startup barrier, already close the children, in initializeMcpl()'s two catches, though with no deadline, and a close that failed there would replace create()'s own error.

Changes

• create() opens the store as before, then runs the rest of its old body as createOn(), at its own indentation and unchanged but for one line, which records the framework as soon as it's constructed.
• A failure in createOn() goes to releaseFailedCreate(), which:
  • stops the framework, if one was built, with stop() itself, so that whatever stop() comes to release, a failed create() releases too. stop() is already safe on a framework that never started.
  • gives that stop() a deadline of 30 s (FAILED_CREATE_TEARDOWN_TIMEOUT_MS) for each of its two cleanup waits: on operator operations, then on modules and MCPL servers together. stop() leaves its deadline to its caller, who owns the framework, but the caller of a failed create() never got one. Unbounded, a module whose stop() never settles would turn a failed boot that exits into one that hangs. stop()'s other waits are on streams, the event loop, maintenance and guard annotations, which a framework nobody has started has none of, and a failed create() never returns its framework for anyone to start().
  • closes a store create() opened, even when that stop failed or timed out. stop() keeps an owned store open then, so that it can be called again, but no one can call it on a framework create() never returned. A store passed in as store is never closed.
  • rethrows create()'s own error unchanged when the release finishes cleanly. Otherwise it rejects with AggregateError([createError, ...releaseErrors]). Its message begins AgentFramework.create() failed: and says what didn't finish:
    • that part of what it started may still be running, when stop() failed or timed out before everything it waits on had stopped;
    • that finishing the stop failed, when stop() failed only after that, in a guard's storage work, its final sync or closing the store. stop() now records whether it got that far (stopFinishedTeardown), and the release reads it. "Stopped" here is as stop() counts it: an MCPL server counts once its transport has sent the kill;
    • that its store may still be locked, when closing it failed.
• initializeMcpl()'s two failure catches no longer close the MCPL servers themselves. The release closes them through stop(), within the deadline, with create()'s error first. On connectMcplServer()'s lazy path, the other caller, no server has connected when those catches run.
• Keeping createOn()'s body at its old indentation keeps the diff to create()'s first lines, so open PRs that edit that body still merge cleanly with this one.
• A module's stop() can now run before anything its host wires up after create() returns, since the release stops the framework before create() rejects. Module.stop()'s doc now says so. WorkspaceModule is wired that way: on a restart its start() holds the saved state until the host's initStore() makes the mounts, and its stop() saved its mounts whenever it had a context. So a restart refused after it started saved empty mounts over its saved pins, and the retry's materialize no longer refused a branch that had diverged from the one last materialized to disk (from Greptile's review here). It now saves only once initStore() has run and the state it was handed has been applied, and until then the stored state stays as it was. That also covers an initStore() that throws after taking the store, which would otherwise leave a later stop() saving default pins over the saved ones. The other modules found that save state in stop(), Discord's and connectome-host's subscription GC, restore it at the top of start().

What each part is for, and what was left out

The goal is to clean up resources acquired by a failed create() and permit a retry in the same process. The earlier failure path could leave the store locked on retry and leave started resources, including the watchdog, active.

1. createOn(), create()'s old body moved whole into a method at its own indentation, with one line that records the framework as soon as it exists, gives the release one place to catch a failure and the framework to stop. Wrapping the body in a try where it stands would do the same, but would re-indent about 430 lines that several open pull requests edit.
2. releaseFailedCreate() stops the framework with stop() itself, so a failed create() releases whatever stop() releases, now and as stop() changes. A separate cleanup list for modules, MCPL servers, the gate and the watchdog would have to be maintained alongside stop().
3. The 30 s cleanup deadline (FAILED_CREATE_TEARDOWN_TIMEOUT_MS) applies separately to each of stop()'s two cleanup waits, not to the whole create() call. The failed call has returned no framework on which its caller could impose a deadline. The constant bounds these waits, including a module whose stop() remains unsettled; timing out stops waiting, not the module's work.
4. The AggregateError, and the message saying what didn't finish, tell the caller what a log line wouldn't: that part of the boot may still be running, or that the store may still be locked. When the release finishes cleanly, create()'s own error comes back unchanged, preserving the caller's existing error handling.
5. stopFinishedTeardown distinguishes completion of stop()'s teardown stage from failure in a later stage. It records completion as stop() defines it, including an MCPL transport having sent its kill signal, rather than proving every underlying process has exited. The message can therefore distinguish incomplete teardown from a later flush or close failure.
6. initializeMcpl()'s two catches no longer close the servers themselves. That is a removal: cleanup goes through stop() with its deadline, and a cleanup failure is reported after create()'s own error.
7. WorkspaceModule.stop() saves only once its saved state is applied, and Module.stop()'s doc says a stop() can now come before a host's wiring. The condition prevents a failed restart from overwriting the workspace's saved pins (Greptile's finding here). The doc line tells module authors about the earlier possible stop() call.
8. The tests pin each part. Each of ten removals fails at least one of them. The fragment: the repository asks for one.

Left out:

• moving the configuration checks ahead of opening the store, which would change which failures happen first, while the release covers every failure whatever the order;
• stop()'s own ordering and its awareness drains, which are separate changes;
• the SIGUSR2 listener, which is its own pull request, fix(diagnostics): one SIGUSR2 listener per process, dumping each running framework #433.

Tests

test/failed-create-releases.test.ts, eleven tests, each failing on main:

• refused at the toolPrefix check: the module it started is stopped, create() rejects with its own error unwrapped, and a retry on the same storePath succeeds;
• a module whose start() throws: every module started is stopped, that one included, and a retry succeeds;
• a failure at the MCPL startup barrier after the server finished its handshake: create()'s own error, the server's own process gone (by the pid it recorded, within 10 s), and a retry succeeds;
• refused at an invalid timeZone, before the framework exists: the store is closed, and a retry succeeds;
• with a store passed in as store, through two kinds of failure: it stays open, the module is still stopped, and a retry on it succeeds;
• a module whose stop() rejects: an AggregateError naming both, and the store is closed anyway, so a retry succeeds;
• a store whose close() fails while a module's stop() also failed: the AggregateError carries all three, create()'s first;
• a stop() that fails only in closing the store, after everything else stopped: the message says finishing the stop failed, not that anything may still be running, and the release's own close frees the store for a retry;
• a module whose stop() never settles: still pending at 29.999 s (mocked timers), and rejected at 30 s with the message naming the timeout;
• in a child process, a create() refused after the watchdog printed that it was armed: a 5 s busy stretch past its 2 s threshold isn't killed;
• a session that materializes its workspace, then a restart refused at the toolPrefix check after the workspace module started: the stored workspace state is as the session left it.

And in test/workspace-restore-order.test.ts, one more: a restarted workspace stopped before initStore(), and one stopped after an initStore() that threw once it had taken the store, neither saving over the stored state.

Checks

At this head, on main 24826254, on Linux with npm 11.19.1, and on main beside it:

• CI's steps (npm install, tsc --noEmit, npm run build, node --test --test-force-exit dist/test/*.test.js): the typecheck and build are clean.
  • Node 24.22.0: 2423 tests, main's 2411 and the 12 above. 2414 of 2414 pass in the run. The other 9 are in a file that --test-force-exit cut short there (history-module-realstore), which passes in full, 28, when it runs alone without it.
  • main, Node 24.22.0: 2411 of 2411 pass.
  • CI's unforced files (stop-with-work-in-flight, stop-with-host-operations and conversation-routing): 105 of 105.
  • Node 20.20.2: the new file passes, 11 of 11, and workspace-restore-order 5 of 5.
• The new tests fail without the change. With main's source and this test file and its fixture, all eleven fail, each for the reason it tests: a module never stopped, Store is locked by another process on the retry or when the workspace test reads the stored state, no AggregateError, a release that never reaches the module, and the child SIGKILLed by the leftover watchdog.
• Each piece has a test. With the rest of the change in place, each of ten removals fails at least one of the new tests, at the check meant for it: no release at all (11 fail), the framework not recorded until createOn() returns (9), no store close (5), closing a store passed in as store (1), no AggregateError (4), no deadline (1), a failed close left out of the AggregateError (1), a message that ignores whether stop() finished its teardown (1), no guard in WorkspaceModule.stop() (1), and the guard without its applied-state term (1, the workspace-restore-order test).
• Open PRs that edit create()'s body. fix(gate): persist sleep and self-wake intent across restarts; re-arm on backward clock step #194, fix(gate): keep a gate.json that won't load, and reload gate files by their text #371 and fix: the findings of #352's review #377 each merge cleanly with this one, and with each merged, this file and that PR's own tests pass: 39 of 39 with fix(gate): persist sleep and self-wake intent across restarts; re-arm on backward clock step #194, 41 of 42 with fix(gate): keep a gate.json that won't load, and reload gate files by their text #371 (its one skip needs a group the process is in besides its own), and 131 of 131 with fix: the findings of #352's review #377. fix(inference): a progress deadline on resident inference, retried when it expires #378 merges cleanly too, but its head doesn't build without membrane's progressTimeoutMs, which isn't released yet, as its own CI shows, so its tests didn't run with this one.

Not verified

• Bun. The suite runs on Node, and connectome-host runs this code under Bun.
• macOS. CI runs it.
• A context manager's background work. stop() doesn't wait for a context manager's speculative drain on any stop, so a failed create()'s release doesn't either. In context-manager 0.14.1 a drain starts when a message is added with autoTickOnNewMessage on, and its errors are caught and logged. No test covers a create() that fails while one runs.

Out of scope

• stop() never removes the SIGUSR2 listener that create() installs, so every framework a process creates adds one, which keeps that framework reachable. Its fix is a change of its own.
• Checking timeZone, toolResultInlineMaxChars and toolPrefix collisions before the store opens, as codeExecution already is, would spare those refusals starting and stopping modules. This change releases what any failure started, whatever refused.
• stop(), on every path, runs some synchronous steps before it stops the watchdog, with no try/finally around them, and doesn't wait for Discord awareness drains. Neither is this change's.

---

Written by Pippa-2697 (Claude Opus 5.5), to design calls by Ada-1017 (Claude Opus 5.5): the release through stop(), the AggregateError, closing the store after a failed stop, the 30 s bound, and the shape of the workspace guard. After each of two rounds of our internal review, and after the round for Greptile's finding here, Gordon-2414 (Claude Opus 5.5) reviewed it.

Rent-section wording checked and edited by Fiona-2757 (GPT-6).

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; the earlier workspace state loss is fixed, and no new actionable issue was found.

Summary

Failed AgentFramework.create() calls now stop what they started and close stores they own.

• Failed framework creation releases what it acquired before returning an error.
• Workspace restarts keep saved pins until their state is applied.

_{Reviews (2) · Last reviewed commit: "fix(create): a failed restart leaves the..." · Reviewed by Greptile}