@@ -9,4 +9,4 @@ Clause-②: no
 - **What was wrong.** With `gracefulShutdown: true` (the default) the constructor added one listener per signal and kept no handle, so `shutdown()` never removed them. Every kernel a process built left three listeners behind, and each one called `process.exit(0)` on the next signal. A process that had built and stopped five kernels and still ran a sixth exited six times on one SIGTERM, and the first exit landed before the live kernel had drained. Eleven built-and-stopped kernels also tripped Node's `MaxListenersExceededWarning`.
 - **What a kernel does now.** It holds its listeners from construction until it reaches `stopped`, and removes them at that point, whichever way it got there: `shutdown()` completing, the shutdown timeout, or a failed `bootstrap()`. A stopped kernel has no listener, so it cannot handle a signal. While a kernel is `stopping` its listener stays installed, so a repeated signal is absorbed and does not trigger Node's default action mid-drain.
 - **Who exits the process.** Only the handler whose signal started the drain, and only once. A signal that arrives while the host is already stopping the kernel through `shutdown()` is logged and left to the host. The kernel no longer exits the process in that case.
-- **Unchanged.** A running kernel still drains and exits with code 0 on SIGINT, SIGTERM or SIGQUIT (code 1 if `shutdown()` throws). `gracefulShutdown: false` still installs nothing. A genuine shutdown timeout still calls `process.exit(1)`.
+- **Unchanged.** A running kernel still drains and exits with code 0 on SIGINT, SIGTERM or SIGQUIT (code 1 if `shutdown()` throws). `gracefulShutdown: false` still installs nothing. With `gracefulShutdown: true`, a genuine shutdown timeout still calls `process.exit(1)`; a `gracefulShutdown: false` kernel no longer exits (#22335).
@@ -0,0 +1,16 @@
+---
+'@objectstack/core': minor
+---
+
+fix(core)!: a `gracefulShutdown: false` kernel no longer exits the process when its teardown times out
+
+Clause-②: no
+
+<!-- adr-0087: not-required (no-migration-prescription) No metadata moves: no spec key, authorable spelling, export, option, type or stored shape is added, removed, renamed or re-shaped, and no stored row is read, rewritten or converted, so there is nothing for `objectstack migrate meta` to rewrite. What changes is a runtime behaviour of `ObjectKernel.shutdown()` under an existing option: on a teardown timeout a `gracefulShutdown: false` kernel returns to its host instead of calling `process.exit(1)`. The other categories are closed on facts: `@objectstack/core` publishes (not unpublished); no ADR-0087 id is named or touched (not registered or already-registered); and no TypeScript declaration moves, only a JSDoc comment (not runtime-interface-only or type-surface-only). -->
+
+**BREAKING** for a host that builds `ObjectKernel` with `gracefulShutdown: false` and counted on the kernel to end the process when a teardown hung: a behaviour change, shipped as `minor` under the launch-window convention for breaking changes.
+
+- **What changes.** When `shutdown()` overruns `shutdownTimeout`, a kernel built with `gracefulShutdown: false` no longer calls `process.exit(1)`. It logs the timeout at `error`, marks itself `stopped`, and `shutdown()` resolves, so the host decides whether the process exits. The hung teardown is not cancelled: it keeps running in the background and holds whatever it has not released until it finishes or the process ends.
+- **Why.** `gracefulShutdown: false` already meant that the host, not the kernel, handles the process signals, and the kernel lifecycle docs say such a kernel stays out of the process-management business. The timeout branch did not read the option. So a host that runs several `false` kernels in one process, one per environment, lost all of them when one environment's teardown hung.
+- **Unchanged.** With `gracefulShutdown: true` (the default; the kernel installs its own SIGINT, SIGTERM and SIGQUIT listeners) a genuine timeout still logs `Shutdown timed out — forcing exit` and calls `process.exit(1)`. A teardown that throws instead of hanging still never exits the process, under either setting. `shutdown()` still never rejects, and no option, key or export is added. Every kernel `@objectstack/cli` builds takes the default, so its commands behave as before.
+- **Who must act.** A host that sets `gracefulShutdown: false` (a server framework with its own signal handlers, or a host running one kernel per environment in one process) and relied on that exit to end a process whose teardown hung. Such a host already handles the signals itself; it now also ends the process itself. Call `process.exit()` in that host once `await kernel.shutdown()` returns, instead of waiting for the event loop to drain: `shutdown()` returns within `shutdownTimeout` whether or not the teardown finished, but a hung teardown can keep the loop alive after it. The timeout is reported in the kernel's `error` log line.
@@ -0,0 +1,157 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * A kernel whose teardown times out exits the process only if it OWNS the
+ * process (#22335, ruling B): `gracefulShutdown` true — the default, the kernel
+ * installed the signal listeners itself — keeps the hard `exit(1)` (pinned in
+ * kernel.test.ts, the #5274 timeout pin). `gracefulShutdown` false means the
+ * host owns the process: the kernel logs the timeout, marks itself `stopped`,
+ * and `shutdown()` returns to the host, which decides whether the process ends.
+ *
+ * Before this, the timeout branch called `process.exit(1)` without reading the
+ * option, so a host running several `false` kernels in one process (one per
+ * environment) lost every one of them when one teardown hung.
+ *
+ * `process.exit` is stubbed in every test here: the behaviour under test is
+ * whether the kernel ends the process, and a real `exit(1)` would end the
+ * vitest worker with it.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { ObjectKernel } from './kernel';
+import type { Plugin } from './types';
+
+type ExitSpy = { mock: { calls: unknown[][] }; mockRestore: () => void };
+type LogMethod = (message: string, ...rest: unknown[]) => void;
+
+const SHUTDOWN_TIMEOUT_MS = 20;
+
+describe('ObjectKernel shutdown timeout under gracefulShutdown: false', () => {
+    let exitSpy: ExitSpy;
+
+    beforeEach(() => {
+        exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as never) as unknown as ExitSpy;
+    });
+
+    afterEach(() => {
+        exitSpy.mockRestore();
+    });
+
+    const hostOwnedKernel = () =>
+        new ObjectKernel({
+            logger: { level: 'silent' },
+            gracefulShutdown: false,
+            skipSystemValidation: true,
+            shutdownTimeout: SHUTDOWN_TIMEOUT_MS,
+        });
+
+    const spyOnError = (kernel: ObjectKernel) =>
+        vi.spyOn((kernel as unknown as { logger: { error: LogMethod } }).logger, 'error');
+
+    /** A plugin whose `kernel:shutdown` subscriber holds teardown open until released. */
+    const hungTeardown = (reached: string[]) => {
+        let release!: () => void;
+        const gate = new Promise<void>((resolve) => { release = resolve; });
+        const plugin: Plugin = {
+            name: 'hung-teardown',
+            version: '1.0.0',
+            init: async (ctx) => {
+                ctx.hook('kernel:shutdown', async () => {
+                    await gate;
+                    reached.push('teardown-resumed');
+                });
+            },
+            destroy: async () => { reached.push('destroy'); },
+        };
+        return { plugin, release: () => release() };
+    };
+
+    it('logs the timeout at error, ends stopped, resolves and does NOT exit the process', async () => {
+        const reached: string[] = [];
+        const { plugin, release } = hungTeardown(reached);
+        const kernel = hostOwnedKernel();
+        const errorSpy = spyOnError(kernel);
+        await kernel.use(plugin);
+        await kernel.bootstrap();
+
+        try {
+            await expect(kernel.shutdown()).resolves.toBeUndefined();
+
+            expect(exitSpy.mock.calls).toEqual([]);
+            expect(kernel.getState()).toBe('stopped');
+            const timeoutLines = errorSpy.mock.calls.filter((c) => String(c[0]).startsWith('Shutdown timed out'));
+            expect(timeoutLines).toHaveLength(1);
+            expect(timeoutLines[0][1]).toBeInstanceOf(Error);
+            // The `true` line says an exit is being forced; under `false` none is.
+            expect(errorSpy.mock.calls.map((c) => String(c[0]))).not.toContain('Shutdown timed out — forcing exit');
+            // The teardown was abandoned, not finished.
+            expect(reached).toEqual([]);
+        } finally {
+            release();
+        }
+
+        // The hung teardown keeps running in the background. When it finishes,
+        // the kernel does not act on it: still `stopped`, still no exit, and a
+        // second `shutdown()` is the already-stopped no-op.
+        await vi.waitFor(() => expect(reached).toEqual(['teardown-resumed', 'destroy']));
+        expect(kernel.getState()).toBe('stopped');
+        await expect(kernel.shutdown()).resolves.toBeUndefined();
+        expect(exitSpy.mock.calls).toEqual([]);
+        errorSpy.mockRestore();
+    });
+
+    it('two host-owned kernels in one process: stopping the hung one leaves the other running and the process alive', async () => {
+        const reached: string[] = [];
+        const { plugin, release } = hungTeardown(reached);
+        const hung = hostOwnedKernel();
+        const sibling = hostOwnedKernel();
+        await hung.use(plugin);
+        await hung.bootstrap();
+        await sibling.bootstrap();
+
+        try {
+            await hung.shutdown();
+
+            expect(hung.getState()).toBe('stopped');
+            expect(sibling.getState()).toBe('running');
+            expect(exitSpy.mock.calls).toEqual([]);
+
+            // The sibling is untouched: the host can still stop it normally.
+            await sibling.shutdown();
+            expect(sibling.getState()).toBe('stopped');
+            expect(exitSpy.mock.calls).toEqual([]);
+        } finally {
+            release();
+        }
+    });
+
+    // Control: a teardown that FAILS rather than hangs never exited the process
+    // under `false`, before this change or after it. Both shapes: a throwing
+    // `destroy()` (isolated inside the teardown) and an error escaping the
+    // teardown altogether (the non-timeout branch of `shutdown()`'s catch).
+    it.each([
+        ['a throwing destroy()', (kernel: ObjectKernel) =>
+            kernel.use({
+                name: 'throwing-destroy',
+                version: '1.0.0',
+                init: async () => {},
+                destroy: async () => { throw new Error('destroy boom'); },
+            })],
+        ['an error escaping the teardown', async (kernel: ObjectKernel) => {
+            vi.spyOn(kernel as unknown as { performShutdown: () => Promise<void> }, 'performShutdown')
+                .mockRejectedValue(new Error('teardown boom'));
+        }],
+    ] as const)('control: %s does not exit the process and is not reported as a timeout', async (_label, arrange) => {
+        const kernel = hostOwnedKernel();
+        const errorSpy = spyOnError(kernel);
+        await arrange(kernel);
+        await kernel.bootstrap();
+
+        await expect(kernel.shutdown()).resolves.toBeUndefined();
+
+        expect(exitSpy.mock.calls).toEqual([]);
+        expect(kernel.getState()).toBe('stopped');
+        expect(errorSpy.mock.calls.some((c) => String(c[0]).startsWith('Shutdown timed out'))).toBe(false);
+        errorSpy.mockRestore();
+    });
+});
@@ -966,10 +966,17 @@ describe('ObjectKernel', () => {
         // making progress, so the process would hang holding whatever it failed
         // to release. This behaviour is unchanged by #5274 — pinned so the
         // narrowing of the catch cannot quietly take it along.
+        //
+        // The fixture owns the process (`gracefulShutdown: true`, the default):
+        // only a kernel that installed the signal listeners itself exits on a
+        // timeout (#22335). The `false` half — no exit, the host decides — is
+        // pinned in kernel-shutdown-timeout-ownership.test.ts.
         it('still logs the timeout and still forces exit(1) when shutdown genuinely times out (#5274)', async () => {
+            const signals = ['SIGINT', 'SIGTERM', 'SIGQUIT'] as const;
+            const listenersBefore = new Map(signals.map((s) => [s, process.listeners(s)]));
             const slowKernel = new ObjectKernel({
                 logger: { level: 'error' },
-                gracefulShutdown: false,
+                gracefulShutdown: true,
                 skipSystemValidation: true,
                 shutdownTimeout: 20,
             });
@@ -1000,6 +1007,13 @@ describe('ObjectKernel', () => {
             } finally {
                 exitSpy.mockRestore();
                 errorSpy.mockRestore();
+                // A `true` kernel listens on the worker's own process; never
+                // leave its listeners behind, whatever the test did.
+                for (const s of signals) {
+                    for (const l of process.listeners(s)) {
+                        if (!listenersBefore.get(s)!.includes(l)) process.removeListener(s, l);
+                    }
+                }
             }
         }, 5000);
 
 
@@ -80,10 +80,29 @@ export interface ObjectKernelConfig {
     defaultStartupTimeout?: number;
 
     /**
-     * Whether to enable graceful shutdown. When true (the default) the kernel
-     * listens for SIGINT, SIGTERM and SIGQUIT from construction until it stops:
-     * a signal drains it and then exits the process. Its listeners are removed
-     * when it reaches `stopped`, so a stopped kernel never handles a signal.
+     * Whether this kernel owns the process. It decides two things, always
+     * together:
+     *
+     * - **Who installs the signal listeners.** When true (the default) the
+     *   kernel listens for SIGINT, SIGTERM and SIGQUIT from construction until
+     *   it stops: a signal drains it and then exits the process. Its listeners
+     *   are removed when it reaches `stopped`, so a stopped kernel never
+     *   handles a signal. When false the kernel installs none, and the host
+     *   handles signals itself.
+     * - **Who exits the process when a teardown times out.** When `shutdown()`
+     *   overruns `shutdownTimeout`, a kernel with this option true logs the
+     *   timeout and calls `process.exit(1)`. A kernel with it false does NOT
+     *   exit the process: it logs the timeout at `error`, marks itself
+     *   `stopped`, and `shutdown()` returns to the host, which decides whether
+     *   the process exits. The hung teardown is not cancelled — it keeps
+     *   running in the background and holds whatever it has not released yet,
+     *   until it finishes or the host ends the process.
+     *
+     * Set it false when something else owns the process: a server framework
+     * that installs its own signal handlers, or a host that runs several
+     * kernels in one process and must not lose all of them when one teardown
+     * hangs. Such a host exits the process itself when it decides to.
+     * `shutdown()` never rejects under either setting.
      */
     gracefulShutdown?: boolean;
 
@@ -688,13 +707,34 @@ export class ObjectKernel {
 
             if (error === shutdownTimeoutError) {
                 // GENUINE timeout: `performShutdown()` is still running and has
-                // stopped making progress, so the process would otherwise hang
-                // holding whatever it failed to release. Hard-exit stays — it
-                // is the only branch it was ever right for.
-                this.logger.error('Shutdown timed out — forcing exit', error as Error);
-                // Flush logger then hard-exit; the process would otherwise hang
-                await this.logger.destroy();
-                process.exit(1);
+                // stopped making progress. Whether that ends the process
+                // depends on who owns it, and the test is the one the
+                // constructor uses to install the signal listeners, so a kernel
+                // exits on a timeout exactly when it took the signals itself
+                // (`ObjectKernelConfig.gracefulShutdown`).
+                if (this.config.gracefulShutdown) {
+                    // The kernel owns the process, which would otherwise hang
+                    // holding whatever the teardown failed to release.
+                    // Hard-exit stays — it is the only branch it was ever
+                    // right for.
+                    this.logger.error('Shutdown timed out — forcing exit', error as Error);
+                    // Flush logger then hard-exit; the process would otherwise hang
+                    await this.logger.destroy();
+                    process.exit(1);
+                } else {
+                    // The host owns the process. Exiting here would end every
+                    // other kernel and workload it runs over one hung
+                    // teardown, so the kernel reports, stays `stopped` and
+                    // returns. Nothing here acts on the abandoned teardown
+                    // again: `performShutdown()` changes no state when it
+                    // finishes, and the kernel's own later log lines from it
+                    // reach the console only, the file stream having been
+                    // closed in `finally`.
+                    this.logger.error(
+                        `Shutdown timed out after ${this.config.shutdownTimeout}ms — the kernel is stopped but its teardown is still running in the background and may still hold what it has not released; gracefulShutdown is false, so the host owns the process and it is NOT being exited — the host decides whether it exits`,
+                        error as Error,
+                    );
+                }
             } else {
                 // NOT a timeout. `performShutdown()` isolates every teardown
                 // step it owns (hook dispatch, each destroy(), each shutdown