Graceful shutdown doesn't await scope 'close' cleanup — app teardown races process.exit #1912

Summary

The supported pattern for application shutdown cleanup is a 'close' listener on the plugin-API Scope:

export function handleApplication(scope) {
	const service = startService();
	scope.once('close', async () => {
		await service.close();
	});
}

But nothing in the shutdown path waits for that cleanup. Async 'close' listeners race process.exit, and on an idle server the cleanup may not even start before the process exits. This came up as a support question from an app developer; the recommended answer only works best-effort today.

Mechanics (all on the worker thread, triggered by the SHUTDOWN ITC message)

1. scope.close() is fire-and-forget. componentLoader.ts:472 registers onMessageByType(ITC_EVENT_TYPES.SHUTDOWN, () => scope.close()), and notifyMessageListeners (server/threads/manageThreads.js:610-616) invokes typed listeners synchronously, dropping returned promises.
2. Async 'close' listener promises are dropped. Scope.close() (components/Scope.ts:181-187) awaits entry-handler and options teardown, then calls plain this.emit('close') — EventEmitter.emit does not await listener promises.
3. Exit is sequenced only on HTTP drain. threadServer.js:175-177 does closeServers().then(() => realExit(0)), where realExit is the original process.exit. closeServers() resolves when every server's close() callback fires (or a 5s per-server cap) — on an idle server that's near-immediate.
4. Because scope.close() awaits entry-handler/options teardown before emitting 'close', on a fast drain the 'close' event may fire after realExit(0) has been queued — cleanup never starts.
5. The backstop timers (threadTerminationTimeout = 10s worker-side at manageThreads.js:655-663, 2× on the main thread before worker.terminate() at manageThreads.js:296-306) are upper bounds only — nothing ever waits for scope cleanup, so finishing under the timeout doesn't help.

Note this affects graceful restarts too (dev watch, restart operation) — same SHUTDOWN message path via restartWorkers.

Impact

Apps that flush buffers, drain queues, or close connections to external services in a 'close' listener can be cut off mid-flight (or never run) on shutdown/restart. Typical symptoms: lost telemetry/batches, unclean client disconnects, external resources left open.

Suggested direction

• Make the worker's exit condition Promise.allSettled([closeServers(), allScopeCloses]) (bounded by threadTerminationTimeout) instead of closeServers() alone.
• Have Scope.close() await async 'close' listener results — emit can't do this, so either iterate rawListeners('close') and await returned promises, or add an explicit registration API (e.g. scope.onClose(async () => ...)) and document 'close' listeners as sync-only.

Docs follow-up (documenting the cleanup pattern + this caveat) tracked separately in the documentation repo.

Remaining loading/disposal liveness variant

The TypeStrip integration now awaits scope cleanup and separates load-verdict reporting from admission. A retained variant remains when SHUTDOWN unrefs the parent port while pending component loading or disposal completes only through an unreferenced callback: the worker's event loop can end before teardown finishes. This pass code-traced the variant at server/threads/manageThreads.ts:3226 and server/threads/threadServer.ts:278-292 on f3f3d9af630c8e41d57415da8c5b49f0374d4575; it did not reproduce it afresh. The current held-scope fixture uses referenced disposal timers, so it does not establish this case. A discriminating follow-up should require disposal to precede exit with an unreferenced completion source in both runtimes. Admission itself no longer blocks teardown.

Review-Deferral: c8fea45aee59d5a7 severity=minor category=reliability

_{🤖 Generated by OpenAI Codex; posted via @kriszyp.}

Main-thread component loading during process exit

Review of Add opt-in native full-text analytics #3946 identified a separate, code-traced residual in the graceful shutdown code merged by Drain in-flight work and close cleanly on SIGTERM/SIGINT/SIGQUIT, bounded by threads.shutdownTimeout #3943. In multi-worker mode (threads.count > 0), main awaits loadRootComponents() in server/threads/socketRouter.ts, while shutdownForExit() in server/threads/threadServer.ts waits a componentsLoading promise assigned by the worker/single-thread startup route. If main receives a signal while component loading is unresolved, shutdown can sweep deferred scope closes before loading creates its last scope. A close registered after that sweep has no subsequent sweep before process exit.

This is a code-traced possibility, not a reproduced failure or an analytics regression. Add a deterministic main/multi-worker fixture that pauses component loading, initiates signal shutdown, creates a final scope, and requires that scope's async disposal to settle before exit under the existing deadline. Confirm the loading promise and disposal boundary share ownership before choosing a fix; preserve the already-correct worker and single-thread routes. No production incident or data loss is established.

Review-Deferral: e00b38df16d81c48 severity=nit category=reliability

Comment generated by kAIle (GPT-6)