[decision] a kernel with gracefulShutdown: false still calls process.exit(1) when its teardown times out, ending every other kernel in a multi-kernel host; the docs say such a kernel stays out of process management

Ruled: 6070759640 · letter B · 2026-10-08T23:04Z

Filing gate: ② a decision only the maintainer can make. It is the family item of #22286 (the repo:cloud seat's card), which the card asked to "fold in, or record why not". PR #22334 recorded why not: folding it reverses a landed pin and gives an existing option a second meaning. Filed by domain:engine seat 1 (seat post #6367) · session_01EUBvqtauTDmHi2ZgY759p2, from the dev report on #22286 (6066371231). ⛔ Not graded or routed here; ⛔ not a claim.

Who acts on it: the maintainer answers one letter; triage grades it; the domain:engine seat claims and dispatches the answer. PR #22334 (#22286) does not wait for it.

维护者速读

一个进程可以同时跑多个 ObjectStack 内核。 cloud 的托管运行时就是这样，每个环境一个内核，每个都设了 gracefulShutdown: false，意思是"进程归宿主管，内核别插手"。文档也这么写：设成 false 的内核"不碰进程管理"。
但有一条路例外。 宿主关掉其中一个内核时，如果它的清理卡住超过超时（默认 60 秒），这个内核会直接 process.exit(1)，整个进程退出，同一进程里其他正常运行的环境一起被带走。dev 已在进程内实测（退出函数打桩）：两个内核，停一个，另一个还在运行时进程就退出了。
推荐 B： 设了 false 的内核在清理超时后只记错误、把自己标成已停止，把控制权交还宿主，由宿主决定退不退出。回一个字母：A / B / C / D。

一句话问题

宿主明确说过"进程归我管"的内核，清理卡住时该不该自己把整个进程关掉？

Background (measured and read)

The code. packages/core/src/kernel.ts: in shutdown(), a GENUINE teardown timeout calls process.exit(1). gracefulShutdown is not consulted. The reason the pin states is that "performShutdown() is still running and has stopped making progress, so the process would hang holding whatever it failed to release".
The pin. packages/core/src/kernel.test.ts, "still logs the timeout and still forces exit(1) when shutdown genuinely times out (core: ObjectKernel 上一个抛错的 kernel:shutdown handler 会跳过所有插件 destroy() 并 process.exit(1),日志还谎报「Shutdown timed out」 #5274)". Its fixture kernel is gracefulShutdown: false. core: ObjectKernel 上一个抛错的 kernel:shutdown handler 会跳过所有插件 destroy() 并 process.exit(1),日志还谎报「Shutdown timed out」 #5274 itself was about telling a throwing handler apart from a timeout; the exit was kept as-is.
The docs. content/docs/protocol/kernel/lifecycle.mdx: "The host process is responsible for signal handling. ObjectStack ships the listeners only when gracefulShutdown: true; otherwise it stays out of the process-management business so adapters (Express, Fastify, Hono, Vercel, …) can install their own."
Measured reach (PR fix(core): a stopped ObjectKernel removes its signal listeners and never exits the process #22334's dev, probe R7, in process with a stubbed exit). A host holds two gracefulShutdown: false kernels and stops one of them. That kernel's teardown hangs past shutdownTimeout, and exit(1) fires while the other kernel is still running.
- Producer: objectstack-ai/cloud's hosted runtime, which builds one kernel per environment and set gracefulShutdown: false on them in cloud PR fix(mcp): SKILL.md documents the business-action tools (#2714 Phase 0) #2715.
Related, same question: two LIVE gracefulShutdown: true kernels in one process each drain and exit on one signal (probe R8). This is unchanged by fix(core): a stopped ObjectKernel removes its signal listeners and never exits the process #22334.

Governing text

The docs sentence above is the only written statement of what gracefulShutdown: false means for process ownership. The code and the pin say otherwise for the timeout path.
Prior rulings: check-prior-rulings --terms gracefulShutdown,shutdownTimeout,process.exit,safeExit → 0 hits. No ADR decides it.
No protocol change and no packages/spec edit under A, B or D. C widens ObjectKernelConfig.

选项 × 真实代价

选项	做什么	客户感受到的后果
A	保持现状：任何内核清理超时都退出进程；把文档那句改成"超时仍会退出进程"	不改代码。cloud 这类多环境宿主：一个环境清理卡住 60 秒，整个宿主连同其他所有环境一起退出
B	`gracefulShutdown: false` 一并表示"不拥有进程"：超时后记错误、标记已停止、返回，不退出；`true`（默认，内核自己装了信号监听）照旧退出	多环境宿主里，一个环境卡住只影响它自己，宿主自己决定后续。依赖"`false` 也会在超时时退出"的宿主得自己退出（它本来就自己管信号）。#5274 的那个 pin 改用 `true` 的内核做夹具，测的东西不变
C	新增一个显式选项，把"装信号监听"和"可以退出进程"拆开	最明确，但多一个公开开关，可能被设错；目前没有任何实测用户需要把两者分开
D	只有内核自己的信号处理路径在超时时退出；宿主调用的 `shutdown()` 改为把超时以类型化错误抛回给调用方	最精确，但改掉 `shutdown()`"从不抛错"的既有行为，每个宿主都受影响；CLI 的迁移后退出路径也要跟着改

业务含义直译:

A：合租房里一个房客关门卡住了，房东直接把整栋楼断电。
B：签了"物业归房东管"的房客，卡住就报修、交钥匙，断不断电由房东定。
C：合同里再加一条"能不能拉总闸"的单独条款。
D：只有自己拉过警报的人能拉总闸，别人叫他关门时卡住了就把问题交回给叫他的人。

os-decision-facets

① 项目长远合理性：B 让一个既有选项只有一种含义，而且正是文档写的那种；A 让文档迁就代码，保留"非进程所有者也能结束进程"的特例；C 新增开关、扩大公开面；D 改动 shutdown() 对所有宿主的既有契约。
② 实际业务拉动：有实测生产者。cloud 的托管运行时每个环境一个 false 内核，任一环境清理超时就会带走整个宿主。仓库内其余 false 用户是测试夹具。
③ 防 AI 犯错：B 下文档、JSDoc、行为三者一致，AI 照文档写宿主不会被意外退出坑；A 也一致，但一致在"会退出"上，AI 照 Express/Fastify 的习惯以为宿主自己管退出时会踩坑；C 多一个可设错的开关。
④ 创业阶段不扩散：A、B、D 不加键（B 改一个 pin 的夹具并新增一个"不退出"的 pin）；C 加一个公开选项（Clause-②: yes，契约复审档）。

Prior rulings read: gracefulShutdown, shutdownTimeout, process.exit, safeExit → 0 hits; ADR none; thread: #22286 (dev report 6066371231), #5274 (closed, the timeout pin's origin).

裁后执行

**选 B：**分诊定级后，本席认领派发。
- 落点 packages/core/src/kernel.ts 的超时分支：false 时记错误、标记 stopped、返回。
- core: ObjectKernel 上一个抛错的 kernel:shutdown handler 会跳过所有插件 destroy() 并 process.exit(1),日志还谎报「Shutdown timed out」 #5274 的 pin 改用 true 夹具，测的东西不变；新增一个"false 超时不退出"的 pin。
- JSDoc 写明 gracefulShutdown 的两层含义。
- changeset 写明宿主须自己退出的形态。
- 与 ObjectKernel: a public option to bootstrap without dispatching the boot-phase hooks (kernel:ready / kernel:bootstrapped / kernel:listening), so a host can build a definitions-only repair kernel without patching context.hook #22272 同文件，串行。
**选 A：**本席派一张小卡改 lifecycle.mdx 那句文档和 gracefulShutdown 的 JSDoc，写明超时仍退出。
**选 C：**本卡转 domain:spec 车道（扩大公开面）。
**选 D：**本席先测所有调用 shutdown() 的宿主（CLI、runtime、cloud），再派发；changeset 写明契约变化。

Dedupe: MCP search_issues, repo-scoped, open and closed: 「ObjectKernel shutdown timeout process.exit gracefulShutdown false process owner multi-kernel host」 → 4 results. #22286 (this card's source); #22272 (open, a bootstrap option, a different question); #5274 (closed, the timeout pin's origin, which discriminated a throw from a timeout and kept the exit); #13027 (closed, os migrate never exiting, the opposite symptom). None decides this.

Dedupe words: gracefulShutdown process owner timeout exit · multi-kernel host process.exit · kernel teardown timeout ends host

Generated by Claude Code

Triage: graded `priority:p2` · `domain:engine` (`needs-user-decision` kept)

Triage seat (objectstack-wide, seat post #6015) · session_01AavokzJ5DndAwitDXvKy4U · 2026-10-08T20:12Z. ⛔ Not a claim, ⛔ not a dispatch.

Triage: lands in packages/core (kernel.ts's shutdown() timeout branch) ⇒ domain:engine. Rationale: packages/core belongs to that lane (lanes/engine.md).

Why p2: it is measured in process. In a multi-environment host, one environment's teardown that hangs past the timeout ends the whole host. That host is cloud's hosted runtime, with one gracefulShutdown: false kernel per environment. It happens only when a teardown hangs, so it is not p1.
A real fork, so it stays a decision card:
- The only written statement, the lifecycle docs, disagrees with the code and its pin.
- No ADR or ruling decides it. check-prior-rulings finds 0 hits, re-read for this grade.
Lane after the answer: under C (a new public option) the card moves to domain:spec. Under A, B or D it stays here.

Ruling: batch #294 item 4 · letter B · maintainer 「其他同意」 2026-10-08T23:02Z

Director seat, summon #35, session_01VYToj6PQehTEKNrjGM9akg (GitHub os-zhuang; written as objectstack-fleet[bot] via the relay). Presented in batch #294 from the domain:engine seat's decision card (the body; triage grade 6068196632): A keep the exit and rewrite the docs, B a gracefulShutdown: false kernel never exits the process, C a new explicit option, D shutdown() throws a typed timeout error. The seat recommended B; the maintainer answered 「其他同意」. Thread-read: 6068196632. Freshness: no comment since the presentation. Premises re-read on origin/main 43fc50051c: process.exit(1) in the teardown-timeout branch (kernel.ts:608); the hosted runtime builds every environment kernel with gracefulShutdown: false (packages/objectos-runtime/src/artifact-kernel-factory.ts:808).

The ruling

B. gracefulShutdown: false means the kernel does not own the process: when its teardown times out it logs the error, marks itself stopped, and returns to the host, which decides whether the process exits. gracefulShutdown: true (the default; the kernel installed the signal listeners itself) keeps today's exit(1) on a genuine timeout. The #5274 pin keeps what it tests, on a true fixture; a new pin holds "false does not exit on timeout"; the JSDoc states both meanings of the option; the changeset names the host that relied on the old exit and what it must do (exit itself, as it already handles signals). ⛔ Not taken: A (the docs bent to the code, and one hung environment ends every environment in the hosted runtime), C (a second public switch for a split no measured user needs), D (a change to shutdown()'s never-throws contract for every host).

Prior rulings read: gracefulShutdown, shutdownTimeout, process.exit, safeExit → 0 hits; #5274 (closed, the pin's origin), #22286 (the family source), #22272 (open, same file, a different question) → 3 hits; ADR none; thread: 1 comment. 自检: 只看①选 B;②③④ 是否翻转:否。置信缺口:仓外设了 false 却依赖超时退出的宿主测不到;卡住的清理在后台继续跑,资源能否释放未测。

State

needs-user-decision → pm:queue (domain:engine, priority:p2) in this act; the Ruled: line added to the body. The engine seat claims and dispatches: the timeout branch split on the option, the two pins, the JSDoc, the changeset; serial with ObjectKernel: a public option to bootstrap without dispatching the boot-phase hooks (kernel:ready / kernel:bootstrapped / kernel:listening), so a host can build a definitions-only repair kernel without patching context.hook #22272 on the same file.

Generated by Claude Code

Claim: PM loop round 67 · 2026-10-09T00:25Z
Session: session_01EUBvqtauTDmHi2ZgY759p2
Account: os-litant (the seat's linked user, as GET /user answers it; always the card's assignee)
Branch: claude/issue-22335-graceful-false-no-exit
Worktree: objectstack-issue-22335
Domain: domain:engine
Seat: domain:engine#1
Provenance:

Filed by this seat from core: ObjectKernel.shutdown() never removes the SIGINT/SIGTERM/SIGQUIT listeners its constructor registers, so every kernel built in a process leaves three handlers that each run shutdown and process.exit on a later signal #22286's dev report (6066371231).
Triage graded it p2 (6068196632).
The maintainer ruled B through the director seat's batch 🔗 Broken links detected in documentation #294 (6070759640).
Batch 3: feat(metadata-core,metadata-protocol,objectql,plugin-security): the sys_metadata family goes tenant-less; the per-organization overlay axis retires; managed content is sealed (ADR-0131 D6/D7/D13) #15206 S2's dev holds one slot. objectql: cascade delete trips a restrict on a record the same cascade was about to delete (registry-order, depth-first walk) #22305's and [decision] cold boot admits a package whose permission set or position name the environment catalog already holds (package registration runs before sys_metadata hydration), while a hot install of the same package is refused #22307's PRs are in contract review, with no dev running.
File surface (at origin/main 8311650228+, per ruling 6070759640):
Measure first:
- Reproduce probe R7 from core: ObjectKernel.shutdown() never removes the SIGINT/SIGTERM/SIGQUIT listeners its constructor registers, so every kernel built in a process leaves three handlers that each run shutdown and process.exit on a later signal #22286's report in process, with exit stubbed: two gracefulShutdown: false kernels in one process; stop one whose teardown hangs past shutdownTimeout. Today exit(1) fires while the other kernel is still running.
- List every in-repo host that builds a kernel with gracefulShutdown: false (CLI commands, runtime, objectos-runtime's artifact-kernel-factory.ts, test fixtures). For each, say whether anything after shutdown() relies on the timeout exit, especially the CLI's paths that exit after a command (os migrate plan/apply never exit once a host config is composed — the process outlives its own "Graceful shutdown complete" (78 min, measured) #13027's shape).
The fix: packages/core/src/kernel.ts, in shutdown()'s GENUINE-timeout branch (identity-matched shutdownTimeoutError). Under gracefulShutdown: false:
- log the error;
- stay stopped with the signal listeners released (core: ObjectKernel.shutdown() never removes the SIGINT/SIGTERM/SIGQUIT listeners its constructor registers, so every kernel built in a process leaves three handlers that each run shutdown and process.exit on a later signal #22286), as the branch already does;
- return without process.exit.
- Under true (the default, the kernel installed the listeners itself), the exit(1) is unchanged.
- The non-timeout branch is unchanged. shutdown() still never rejects. The hung performShutdown() keeps running in the background; say so in the log line and the JSDoc.
JSDoc: ObjectKernelConfig.gracefulShutdown states both meanings: who installs the signal listeners, and who owns the process exit on a teardown timeout.
Pins:
- core: ObjectKernel 上一个抛错的 kernel:shutdown handler 会跳过所有插件 destroy() 并 process.exit(1),日志还谎报「Shutdown timed out」 #5274's pin ("still logs the timeout and still forces exit(1) when shutdown genuinely times out", kernel.test.ts) keeps what it tests, on a gracefulShutdown: true fixture.
- A new pin: false + a genuine timeout → no exit, state stopped, shutdown() resolves, the error is logged.
- A two-kernel pin (R7's shape): stopping one hung false kernel leaves the other running and the process alive.
- Reverse-verify.
Docs: content/docs/protocol/kernel/lifecycle.mdx already says a false kernel "stays out of the process-management business". Edit it only if a sentence there becomes false. This is domain:devx's page; declare it if touched.
.changeset/22335-*.md (@objectstack/core). A host that relied on the old exit must exit itself, as it already handles signals; the changeset names that shape and that remedy. The level follows the repo's rules for a behaviour a host relied on: the launch-window minor with the BREAKING banner, in pre mode (.changeset/pre.json, tag next). ⛔ No sentence claims pre mode is absent.
⛔ Not C (no new option) and not D (shutdown() does not start throwing).
Container & model: M, mode:subagent, model: default (dispatch-gates --tier: no path-derived mandate).
Clause-②: no
No key, export or option is added. The change brings gracefulShutdown: false in line with its only published statement, content/docs/protocol/kernel/lifecycle.mdx: such a kernel "stays out of the process-management business". The ruling holds it to that.
It changes behaviour a host may rely on, so it owes one contract-tier review before the queue.
Responsibility: shutdown()'s timeout branch exits the process without consulting gracefulShutdown | the hard-exit kept by core: ObjectKernel 上一个抛错的 kernel:shutdown handler 会跳过所有插件 destroy() 并 process.exit(1),日志还谎报「Shutdown timed out」 #5274 for every kernel | a multi-environment host loses every environment when one teardown hangs (cloud's hosted runtime, measured in process by core: ObjectKernel.shutdown() never removes the SIGINT/SIGTERM/SIGQUIT listeners its constructor registers, so every kernel built in a process leaves three handlers that each run shutdown and process.exit on a later signal #22286's R7)
Thread-read: 6070759640
Serial constraints cleared: at 2026-10-09T00:25Z, the one open PR on packages/core/src/kernel.ts is feat(core): ObjectKernelConfig.bootPhaseHooks, a declared option to bootstrap without dispatching kernel:ready / kernel:bootstrapped / kernel:listening #22354 (ObjectKernel: a public option to bootstrap without dispatching the boot-phase hooks (kernel:ready / kernel:bootstrapped / kernel:listening), so a host can build a definitions-only repair kernel without patching context.hook #22272, domain:spec). Its hunks are in ObjectKernelConfig after skipSystemValidation, in bootstrap(), and in a new private method; it does not touch shutdown(). This seat reviewed it (6071691975, no objection). It is enqueued before this lands, and the dev merges origin/main before opening its PR.

os-dev-report

{
"issue": 22335,
"status": "done",
"branch": "claude/issue-22335-graceful-false-no-exit",
"pr": "#22389",
"session": "session_01EUBvqtauTDmHi2ZgY759p2 (mode:subagent, the dispatching PM session; identity is the branch)",
"premise_still_valid": true,
"summary": "Ruling B is implemented. In shutdown()'s genuine-timeout branch (packages/core/src/kernel.ts), a kernel exits the process only when it owns it: the branch reads this.config.gracefulShutdown, the same test the constructor uses to install the signal listeners. Under true (the default) the old exit(1) and its log line are unchanged. Under false the kernel logs at error (naming the timeout, that the teardown keeps running in the background, and that the host decides), stays stopped, and shutdown() resolves. The gracefulShutdown JSDoc states both meanings. The #5274 timeout pin keeps its title and assertions on a true fixture. A new test file pins the false half, R7's two-kernel shape, the abandoned teardown resuming without the kernel acting on it, and two non-timeout controls. The changeset is core minor with the BREAKING banner and ADR-0087 not-required (no-migration-prescription); it names the false host and its remedy.",
"tests": "Probe in process with exit stubbed, two kernels per row, shutdownTimeout 20. Before, at base 16096e8: false hung exits [1] with the other kernel running; true hung exits [1] with the other running; false throwing exits []. After, at 030a795: false hung exits [] with the other running and the process alive; true hung exits [1] with the other running; false throwing exits []. Suites at final head 77e21f8: @objectstack/core test gives 82 files, 2223 passed (CORE_TEST_EXIT=0); core test:repo gives 3 files, 48 passed; core typecheck exits 0, check:test-typecheck OK with the debt held at 4, and tsc -p tsconfig.test.json --listFiles compiles both touched test files. @objectstack/runtime, after building its closure (32 projects): vitest --project local gives 341 files, 4787 passed, 19 skipped; --project repo gives 3 files, 751 passed. Ablation on committed 030a795 through scripts/ablation-replace.mjs: the anchor hit 1 to 0 and the blob moved 0bf80b6dc7ce to 638270e80124 (leg A) and to dae9a3276502 (leg B); each restore was proven by blob == HEAD 0bf80b6dc7ce and an empty git diff HEAD, with a second trap-side proof in the wrapper script. The tests import ./kernel from source, so there is no dist and no build leg. Leg A, if (true): both false pins red ('expected [ [ 1 ] ] to deeply equal []'); the controls and the #5274 pins stay green. Leg B, if (false): only the #5274 timeout pin red ("expected [ Array(1) ] to include 'Shutdown timed out — forcing exit'"). Lint, a declared narrowing: eslint --no-inline-config --format json on the 3 touched TS files gives 3 files, 0 errors, 0 warnings; --print-config resolves a config for each; eslint.config.mjs enables no type-aware linting (0 hits for parserOptions.project or projectService, and its prose says so), so no untouched file's verdict can move. Full pnpm lint is CI's.",
"mcp_calls": "0 GitHub MCP calls. 1 non-GitHub MCP call: mcp__claude-code-remote__add_repo objectstack-ai/cloud (access: read), to read the cloud host's shutdown() call site for M2. Refused: no access.",
"api_writes": "3 REST writes, all through scripts/pm and the fleet-write relay: (1) pr_create via scripts/pm/fleet-write/dispatch.mjs, POST /repos/objectstack-ai/objectstack/dispatches (HTTP 204), run 37869664696 success, POST /repos/objectstack-ai/objectstack/pulls (draft) = PR #22389, body read back identical (12716 bytes); (2) label-write --issue 22389 --assign os-litant, POST /dispatches (HTTP 204), run 37869723997 success, assignee read back os-litant; (3) this os-dev-report comment, POST /repos//issues/22335/comments via scripts/pm/post-stamped.mjs. git push (not REST): 3 pushes to the feature branch (empty branch probe, the code commit, the changeset commit). Reads: gh api GET on issue 22335, its comments, comment 6066371231, pulls/22389, and check-runs for 77e21f8.",
"open_questions": [],
"out_of_scope_findings": [
"carrier: none · noted, not filed. content/docs/kernel/events.mdx:39 says process.exit(1) 'is reserved for a genuine shutdownTimeout overrun'. That is still true as an exclusivity statement, but a reader could take it to mean every overrun exits; after this PR only a gracefulShutdown: true kernel does. It is not in this card's file surface, and the sentence did not become false. Dedupe words: events.mdx shutdown exit reserved · kernel:shutdown docs timeout exit",
"carrier: none · noted, not filed. The pending note .changeset/22286-kernel-signal-listeners.md lists under 'Unchanged' that 'A genuine shutdown timeout still calls process.exit(1)'. That is true of the change it describes, and this PR's changeset states the false exception for the same release. Not edited: correcting another card's pending note is the deliberate-correction class, which keeps Check Changeset red pending a written confirmation. Optional one-clause qualification for the seat: 'With gracefulShutdown: true, a genuine shutdown timeout still calls process.exit(1).'",
"carrier: none · noted, not filed. new ObjectKernel({ gracefulShutdown: undefined }), an explicit undefined, overrides the spread default, so such a kernel installs no listeners and, after this PR, does not exit on a timeout either. That is consistent by construction, because one predicate drives both. No producer in this repo passes a possibly-undefined value. Read, not a defect.",
"carrier: none · noted, not filed. shutdown() resolves the same way whether the teardown finished or timed out; the timeout reaches the host only through the error log line. A host that wants exit status 1 after a hung teardown has no return-value signal, since D was not taken. Recorded in the PR's acceptance notes.",
"carrier: none · read, not measured. With a logger file configured, a plugin that logs through a child logger after a false timeout writes to the file stream the parent closed in finally. The logger's own error handler disables file logging with one notice, which is not fatal. Under true this was unreachable, because the process exited."
],
"pr_body_full": {
"body": "Fixes #22335\nClause-②: no\n\nA kernel built with gracefulShutdown: false no longer calls process.exit(1) when its teardown overruns shutdownTimeout. It logs the timeout at error, marks itself stopped, and shutdown() resolves, so the host decides whether the process exits. A kernel with gracefulShutdown: true (the default) keeps the hard exit(1), with the same log line as before.\n\nThis implements the maintainer's ruling of record on #22335 (comment 6070759640, letter B):\n\n> B. gracefulShutdown: false means the kernel does not own the process: when its teardown times out it logs the error, marks itself stopped, and returns to the host, which decides whether the process exits. gracefulShutdown: true (the default; the kernel installed the signal listeners itself) keeps today's exit(1) on a genuine timeout. The #5274 pin keeps what it tests, on a true fixture; a new pin holds "false does not exit on timeout"; the JSDoc states both meanings of the option; the changeset names the host that relied on the old exit and what it must do (exit itself, as it already handles signals). ⛔ Not taken: A (the docs bent to the code, and one hung environment ends every environment in the hosted runtime), C (a second public switch for a split no measured user needs), D (a change to shutdown()'s never-throws contract for every host).\n\nNo option, key or export is added, and shutdown() still never rejects.\n\n## What changed\n\n- packages/core/src/kernel.ts, shutdown()'s genuine-timeout branch. The branch is still reached only by the identity-matched timeout error. It now reads this.config.gracefulShutdown, the same test the constructor uses to install the signal listeners, so a kernel exits on a timeout exactly when it took the signals itself.\n - true: the old code, unchanged. It logs Shutdown timed out — forcing exit, destroys the logger and calls process.exit(1).\n - false: it logs at error and falls through to the finally. The log line names the timeout in ms and says that the teardown is still running in the background, that gracefulShutdown is false, that the process is NOT being exited, and that the host decides.\n - The non-timeout branch is unchanged.\n- ObjectKernelConfig.gracefulShutdown JSDoc now states both meanings: who installs the signal listeners, and who exits the process when a teardown times out. It also says that the hung teardown is not cancelled and keeps holding what it has not released.\n- packages/core/src/kernel.test.ts. The #5274 timeout pin ("still logs the timeout and still forces exit(1) when shutdown genuinely times out") keeps its title and assertions; only its fixture moves to gracefulShutdown: true. Because a true kernel listens on the worker's own process, the pin now removes any signal listener it added in its finally.\n- New packages/core/src/kernel-shutdown-timeout-ownership.test.ts (4 tests):\n - false plus a genuine timeout: no exit, stopped, shutdown() resolves, exactly one error-level timeout line carrying an Error, and no forcing exit line. The hung teardown is then released: it resumes in the background (teardown-resumed, destroy), the kernel stays stopped, there is still no exit, and a second shutdown() is the already-stopped no-op.\n - R7's shape: two false kernels in one process; stopping the hung one leaves the sibling running with no exit, and the sibling still stops normally.\n - Two controls under false: a throwing destroy() (isolated inside the teardown), and an error escaping the teardown (the catch's non-timeout branch). Neither exits, and neither is reported as a timeout.\n- .changeset/22335-graceful-shutdown-false-no-exit.md: @objectstack/core minor with the BREAKING banner, under the launch-window convention, with ADR-0087 disposition not-required (no-migration-prescription). It names the host that relied on the old exit (a gracefulShutdown: false host: a server framework with its own signal handlers, or one kernel per environment in one process) and the remedy: exit the process yourself once await kernel.shutdown() returns, as you already do for signals.\n\n## Before and after (in process, process.exit stubbed)\n\nProbe: two kernels of the same setting per row, shutdownTimeout: 20. The first kernel's teardown either hangs (a kernel:shutdown subscriber that never settles) or throws an error that escapes the teardown. The host stops the first kernel. "Other kernel" is the second kernel's state when exit was called, or after shutdown() returned if it was not.\n\n| Row | Before: exit calls (base 16096e8d7b) | Before: other kernel | After: exit calls (030a795001) | After: other kernel |\n|:--|:--|:--|:--|:--|\n| false, teardown hangs | 1, exit(1) | running when the process exits | 0 | running, process alive |\n| true, teardown hangs | 1, exit(1) | running when the process exits | 1, exit(1) | running when the process exits |\n| false, teardown throws | 0 | running | 0 | running |\n\nIn every row, before and after, the stopped kernel ends stopped and shutdown() resolves.\n\n## Measurements behind the dispatch's assumptions\n\n- M1, the defect: reproduced. The first row above, at base 16096e8d7b: exit(1) fires while the other false kernel is running.\n- M2, who relied on the exit.\n - In this repo, no production code builds a kernel with gracefulShutdown: false. git grep -E \"gracefulShutdown:\\s*false\" origin/main -- 'packages/**' at 345d3f3d86 finds 49 files, all tests, and 0 non-test lines.\n - No test except the #5274 pin can reach the timeout branch. The only fixtures with a short or explicit shutdownTimeout are that pin (20 ms, now on true) and the #10604 guard pin (60 s, fake timers, its teardown completes).\n - Every production kernel in the repo takes the default (true), so its behaviour is unchanged:\n - CLI serve (packages/cli/src/commands/serve.ts:3173, new Runtime({ kernel: { logger } }));\n - every one-shot CLI command through bootSchemaStack (packages/cli/src/utils/schema-migrate.ts:492, new Runtime({ cluster: false })), which still calls stack.shutdown() and then exits;\n - packages/objectql/src/kernel-factory.ts:35;\n - packages/verify/src/harness.ts:504.\n - No CLI path can now hang where it used to exit.\n - The one measured producer of false is objectstack-ai/cloud's hosted runtime (packages/objectos-runtime/src/artifact-kernel-factory.ts, per the ruling's premise read). That path is not in this repo, and this session has no read access to objectstack-ai/cloud. NOT MEASURED: what that host does after shutdown() returns. The changeset names its shape and remedy.\n- M3, the true path is unchanged. Same branch body, same log line (Shutdown timed out — forcing exit), same logger.destroy() and then process.exit(1). handleShutdownSignal is untouched. The #5274 pin on a true fixture is green, and ablation leg B below shows it depends on this branch.\n- M4, the abandoned teardown. After a false timeout, performShutdown() keeps running and the kernel does not act on it again:\n - It writes no state; state is assigned only in shutdown() and bootstrap().\n - It releases no listeners; that happens only in those two methods.\n - raceWithTimeout's Promise.race keeps a handler on the operation, so a later rejection is not unhandled.\n - The kernel's own logger, already destroyed in finally, writes later lines to stdout and stderr only (fileStream is cleared).\n - The first new test pins this: release the hung teardown after shutdown() resolved, and the kernel stays stopped with no exit.\n - The log line and the JSDoc both say that the hung teardown keeps running and that the host owns what follows.\n\n## Tests (at 77e21f89c2; the one commit after the code commit 030a795001 adds only the changeset)\n\n- @objectstack/core, pnpm --filter @objectstack/core test: 82 files, 2223 tests passed. test:repo: 3 files, 48 passed.\n- pnpm --filter @objectstack/core typecheck: exit 0. check:test-typecheck is OK with the debt ledger unchanged at 4. tsc -p tsconfig.test.json --listFiles compiles both touched test files.\n- @objectstack/runtime (its dependency closure built first, 32 projects): vitest run --project local gives 341 files, 4787 passed and 19 skipped. --project repo gives 3 files, 751 passed.\n- Reverse verification (ablation) on committed 030a795001. Each leg ran through scripts/ablation-replace.mjs (anchor hit 1 to 0, blob changed on disk), then restored with git checkout HEAD; the restore was proven by the blob matching HEAD (0bf80b6dc7ce) and an empty git diff HEAD. The tests import ./kernel from source, so no dist/ is involved.\n - Leg A: the new condition forced to if (true). Both false pins go red (expected [ [ 1 ] ] to deeply equal []), and the two controls and the #5274 pins stay green.\n - Leg B: the condition forced to if (false). Only the #5274 timeout pin goes red (expected [ Array(1) ] to include 'Shutdown timed out — forcing exit'), and the false pins stay green.\n- Lint, a declared narrowing.\n - eslint --no-inline-config --format json on the three touched TS files: 3 files, 0 errors, 0 warnings. --print-config resolves a config for each, so they are inside the linted population.\n - This narrowing cannot change any verdict on an untouched file: eslint.config.mjs enables no type-aware linting (no parserOptions.project and no projectService, which it also states in prose).\n - The full pnpm lint belongs to CI.\n- Gates.\n - node scripts/pm/dispatch-gates.mjs --commands at 77e21f89c2 derived 63 commands, and each was run with its exit captured.\n - All 63 exited 0. pnpm check:dual-build-cjs-loads first exited 3, PREREQUISITE NOT MET, because it reads every package's dist/. It was re-run after a whole-tree turbo run build (72 tasks) at the same head: 107 published require entry points across 66 packages load.\n - --ran reconciliation: 63 derived, 63 run, 0 NOT-MEASURED, 0 UNRUN.\n\n## Serial check with #22354\n\nRe-fetched just before opening: origin/main is 117d34de3f, and #22354 has not landed. Nothing in packages/core moved since base 16096e8d7b, so this branch is not merged with main. Both merges are clean:\n\n- git merge-tree --write-tree origin/main HEAD exits 0 (tree 4c796f278a).\n- git merge-tree --write-tree of #22354's head (4e62f58ea0) with this branch exits 0 (tree 8dead452b0), and the merged kernel.ts carries both changes.\n\nThis branch does not touch bootstrap() or bootPhaseHooks.\n\n## Acceptance notes\n\n- content/docs/protocol/kernel/lifecycle.mdx is not edited. Its sentence (a false kernel "stays out of the process-management business") was false only on the timeout path, and is now true there too.\n- content/docs/kernel/events.mdx says process.exit(1) "is reserved for a genuine shutdownTimeout overrun". It is still true as an exclusivity statement, but a reader could take it to mean every overrun exits. Not edited (not in this card's file surface). Carrier: none.\n- The pending note .changeset/22286-kernel-signal-listeners.md lists under "Unchanged" that "A genuine shutdown timeout still calls process.exit(1)". That is true of that change, and this PR's changeset states the false exception for the same release.\n - Not edited: correcting another card's pending note is the deliberate-correction class, which keeps Check Changeset red pending a written confirmation.\n - If the seat prefers to qualify that sentence, the edit is one clause: "With gracefulShutdown: true, a genuine shutdown timeout still calls process.exit(1)."\n- new ObjectKernel({ gracefulShutdown: undefined }), an explicit undefined, overrides the spread default. Such a kernel installs no listeners and, after this PR, also does not exit on a timeout. That is consistent by construction, because both halves read one predicate. No producer in this repo passes a possibly-undefined value.\n- shutdown() resolves the same way whether the teardown finished or timed out; the timeout reaches the host only through the error log line. A host that wants a non-zero exit status after a hung teardown has no return-value signal, since option D was not taken.\n- Read, not measured: if a logger file is configured and a plugin logs through a child logger after a false timeout, that write meets the file stream the parent closed. The logger's own error handler disables file logging with one notice; it is not fatal. Under true this was unreachable, because the process exited.\n\n---\n_Generated by Claude Code_\n",
"note": "The body stored on PR #22389 differs from this one in two places, both stale-by-the-time-of-report: the Tests heading said 'the two commits after the code commit' (it is one commit, 77e21f8), and the Gates bullets recorded check:dual-build-cjs-loads as NOT MEASURED (exit 3), which was then measured green after a whole-tree build. This is the corrected full body for the seat to write; the dev did not PATCH the PR body."
},
"gates": "node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack at 77e21f8 (final head; nothing in packages/core moved on origin/main since base 16096e8, re-fetched origin/main 117d34d) derived 63 commands. Each was run with $? captured before any pipe. All 63 exit 0. pnpm check:dual-build-cjs-loads exited 3 (PREREQUISITE NOT MET, no whole-tree dist) on the first pass. It was re-run under the verify lock after pnpm exec turbo run build --filter=!@objectstack/docs --concurrency=2 (72 tasks successful) at the same head: '107 published require entry point(s) across 66 package(s) load', exit 0. dispatch-gates --ran with exit-coded record: '63 derived famil(ies) accounted for — 63 run, 0 NOT-MEASURED (a DERIVED zero)'. Notable verdicts: check-adr-0087-registration '1 declared-breaking changeset(s), each carrying an ADR-0087 disposition' (BREAKING+bang, not-required (no-migration-prescription)); check-changeset-no-major 'introduces no major bump' (its LEVEL axis is NOT APPLICABLE locally: no pull_request payload; CI's Check Changeset is already success); check-empty-changeset OK; check:nul-bytes, check:kernel-hook-pairs, check:test-source-alias, check:cross-package-test-inputs, check:doc-authoring, check:type-check-coverage and check:type-check-debt OK. A manual control-byte scan of the 4 touched files plus the PR body found 0 hits. Merge checks: git merge-tree --write-tree origin/main(117d34d) HEAD exits 0, tree 4c796f278a. git merge-tree against #22354's head 4e62f58 exits 0, tree 8dead452b0, and the merged kernel.ts carries both changes. #22354 had not landed, so no merge was made. CI on 77e21f8 at report time: 13 completed, all success or skipped (Check Changeset, Governed Surface Queue Guard, PR Size, the claim and branch checks among them); 18 in_progress (Lint & Repo Gates, TypeScript Type Check, Test Core and the rest), not awaited per contract.",
"line_budget": "4 files, +239 / -12 (251 changed lines) vs the 5000 human-merge threshold: under. kernel.ts +51/-11 (the JSDoc and the timeout branch only), kernel.test.ts +15/-1 (the #5274 pin's fixture and listener cleanup), kernel-shutdown-timeout-ownership.test.ts +157 (new), .changeset/22335-graceful-shutdown-false-no-exit.md +16. No governed surface and no skills/** (Tier: none).",
"deviations": [
"Predicate: the timeout branch tests this.config.gracefulShutdown for truthiness, the constructor's own listener test, instead of the suggested '=== false'. This is the ruling's intent (the kernel exits only if it installed the listeners itself): with '=== false', an explicit gracefulShutdown: undefined would install no listeners yet still exit. For true and false the behaviour is identical.",
"Controls: two non-timeout controls instead of one. A throwing destroy() is isolated inside the teardown and takes the normal path; an error escaping performShutdown (a spy on the private method) takes the catch's non-timeout branch, which no existing test reached. Both: no exit, stopped, not reported as a timeout.",
"M2's cloud half is NOT MEASURED. packages/objectos-runtime/src/artifact-kernel-factory.ts is not in this repo, and add_repo for objectstack-ai/cloud was refused (no access), so what that host does after shutdown() returns was not read. The changeset names the shape and the remedy without claiming the host's current code.",
"The core suite was run as 'pnpm --filter @objectstack/core test -- --maxWorkers=2'. The bare '--' made vitest drop --maxWorkers=2, so the whole package (the intended population: 82 files, 2223 tests) ran with default workers, not the declared cap. Its lock call chained three parts with ';'; each part's exit was captured separately in its own log, and all were 0.",
"PR body stored on #22389 is stale in two places: the Tests heading's commit count, and dual-build-cjs-loads recorded as NOT MEASURED before it was measured. Not PATCHed, per os-dev; the corrected body is in pr_body_full.body.",
"Not taken: an edit to .changeset/22286-kernel-signal-listeners.md, which would mean correcting another card's pending note (Check Changeset kept red pending confirmation). See out_of_scope_findings.",
"Labels: none named by the dispatch, and skip-changeset does not apply (core publishes), so label-write carried only --assign os-litant. The labeler added documentation, size/m, tests and tooling; the read-back says they were never in this write's target."
],
"files_changed": [
".changeset/22335-graceful-shutdown-false-no-exit.md",
"packages/core/src/kernel-shutdown-timeout-ownership.test.ts",
"packages/core/src/kernel.test.ts",
"packages/core/src/kernel.ts"
],
"cross_lane_paths": []
}

Generated by Claude Code

os-dev-report

{
"issue": 22335,
"status": "done",
"round": "patch round 1 (text only), from head 77e21f8 to c6c4351",
"branch": "claude/issue-22335-graceful-false-no-exit",
"pr": "#22389",
"session": "session_01EUBvqtauTDmHi2ZgY759p2 (mode:subagent, the dispatching PM session; identity is the branch)",
"premise_still_valid": true,
"summary": "Patch round 1 is done as ordered, in commit c6c4351. In .changeset/22286-kernel-signal-listeners.md the 'Unchanged' bullet's last sentence changes from 'A genuine shutdown timeout still calls process.exit(1).' to 'With gracefulShutdown: true, a genuine shutdown timeout still calls process.exit(1); a gracefulShutdown: false kernel no longer exits (#22335).' (the coordinator's wording, verbatim). Nothing else in that file changes, and there is no code, test or events.mdx change. Re-measured on origin/main c8c803c: pre.json is still {mode: pre, tag: next} with no consumed changesets, and the 22286 note is still pending at blob c91c506d19, so both notes ship in the same release. check-empty-changeset exits 1 by design (deliberate-correction class), and CI's Check Changeset is red on c6c4351 for the same reason.",
"tests": "No code or test change in this round, so the suites were not re-run; the round-0 readings at 77e21f8 stand (core 82 files / 2223 passed, plus repo 3 / 48; core typecheck exit 0; runtime local 341 files / 4787 passed / 19 skipped, plus repo 3 / 751; ablation legs A and B as in round 0). git diff 77e21f8 c6c4351 touches only .changeset/22286-kernel-signal-listeners.md, 1 line (+1/-1). CI on c6c4351 at report time: TypeScript Type Check, Lint & Repo Gates, Build Core, Test Core 2/6 to 6/6, Dogfood Regression Gate (all three shards), Temporal Conformance and Type Check (workspace, consumer gates, debt ledger) completed success; Test Core (1/6) in_progress; Check Changeset failure (expected, the foreign-correction rule).",
"mcp_calls": "0",
"api_writes": "1 REST write: this os-dev-report comment, POST /repos//issues/22335/comments via scripts/pm/post-stamped.mjs through the fleet-write relay. git push (not REST): 1 push, 77e21f8..c6c4351. No PR body, label or assignee write. Reads: gh api GET check-runs for c6c4351; git fetch of the branch and main.",
"open_questions": [],
"out_of_scope_findings": [
"carrier: none · noted, not filed. content/docs/kernel/events.mdx:39 says process.exit(1) 'is reserved for a genuine shutdownTimeout overrun'. That is still true as an exclusivity statement, but a reader could take it to mean every overrun exits; after this PR only a gracefulShutdown: true kernel does. It is not in this card's file surface, and the sentence did not become false. Dedupe words: events.mdx shutdown exit reserved · kernel:shutdown docs timeout exit",
"carrier: none · noted, not filed. new ObjectKernel({ gracefulShutdown: undefined }), an explicit undefined, overrides the spread default, so such a kernel installs no listeners and, after this PR, does not exit on a timeout either. That is consistent by construction, because one predicate drives both. No producer in this repo passes a possibly-undefined value. Read, not a defect.",
"carrier: none · noted, not filed. shutdown() resolves the same way whether the teardown finished or timed out; the timeout reaches the host only through the error log line. A host that wants exit status 1 after a hung teardown has no return-value signal, since D was not taken. Recorded in the PR's acceptance notes.",
"carrier: none · read, not measured. With a logger file configured, a plugin that logs through a child logger after a false timeout writes to the file stream the parent closed in finally. The logger's own error handler disables file logging with one notice, which is not fatal. Under true this was unreachable, because the process exited."
],
"pr_body_full": {
"body": "Fixes #22335\nClause-②: no\n\nA kernel built with gracefulShutdown: false no longer calls process.exit(1) when its teardown overruns shutdownTimeout. It logs the timeout at error, marks itself stopped, and shutdown() resolves, so the host decides whether the process exits. A kernel with gracefulShutdown: true (the default) keeps the hard exit(1), with the same log line as before.\n\nThis implements the maintainer's ruling of record on #22335 (comment 6070759640, letter B):\n\n> B. gracefulShutdown: false means the kernel does not own the process: when its teardown times out it logs the error, marks itself stopped, and returns to the host, which decides whether the process exits. gracefulShutdown: true (the default; the kernel installed the signal listeners itself) keeps today's exit(1) on a genuine timeout. The #5274 pin keeps what it tests, on a true fixture; a new pin holds "false does not exit on timeout"; the JSDoc states both meanings of the option; the changeset names the host that relied on the old exit and what it must do (exit itself, as it already handles signals). ⛔ Not taken: A (the docs bent to the code, and one hung environment ends every environment in the hosted runtime), C (a second public switch for a split no measured user needs), D (a change to shutdown()'s never-throws contract for every host).\n\nNo option, key or export is added, and shutdown() still never rejects.\n\n## What changed\n\n- packages/core/src/kernel.ts, shutdown()'s genuine-timeout branch. The branch is still reached only by the identity-matched timeout error. It now reads this.config.gracefulShutdown, the same test the constructor uses to install the signal listeners, so a kernel exits on a timeout exactly when it took the signals itself.\n - true: the old code, unchanged. It logs Shutdown timed out — forcing exit, destroys the logger and calls process.exit(1).\n - false: it logs at error and falls through to the finally. The log line names the timeout in ms and says that the teardown is still running in the background, that gracefulShutdown is false, that the process is NOT being exited, and that the host decides.\n - The non-timeout branch is unchanged.\n- ObjectKernelConfig.gracefulShutdown JSDoc now states both meanings: who installs the signal listeners, and who exits the process when a teardown times out. It also says that the hung teardown is not cancelled and keeps holding what it has not released.\n- packages/core/src/kernel.test.ts. The #5274 timeout pin ("still logs the timeout and still forces exit(1) when shutdown genuinely times out") keeps its title and assertions; only its fixture moves to gracefulShutdown: true. Because a true kernel listens on the worker's own process, the pin now removes any signal listener it added in its finally.\n- New packages/core/src/kernel-shutdown-timeout-ownership.test.ts (4 tests):\n - false plus a genuine timeout: no exit, stopped, shutdown() resolves, exactly one error-level timeout line carrying an Error, and no forcing exit line. The hung teardown is then released: it resumes in the background (teardown-resumed, destroy), the kernel stays stopped, there is still no exit, and a second shutdown() is the already-stopped no-op.\n - R7's shape: two false kernels in one process; stopping the hung one leaves the sibling running with no exit, and the sibling still stops normally.\n - Two controls under false: a throwing destroy() (isolated inside the teardown), and an error escaping the teardown (the catch's non-timeout branch). Neither exits, and neither is reported as a timeout.\n- .changeset/22335-graceful-shutdown-false-no-exit.md: @objectstack/core minor with the BREAKING banner, under the launch-window convention, with ADR-0087 disposition not-required (no-migration-prescription). It names the host that relied on the old exit (a gracefulShutdown: false host: a server framework with its own signal handlers, or one kernel per environment in one process) and the remedy: exit the process yourself once await kernel.shutdown() returns, as you already do for signals.\n\n## Before and after (in process, process.exit stubbed)\n\nProbe: two kernels of the same setting per row, shutdownTimeout: 20. The first kernel's teardown either hangs (a kernel:shutdown subscriber that never settles) or throws an error that escapes the teardown. The host stops the first kernel. "Other kernel" is the second kernel's state when exit was called, or after shutdown() returned if it was not.\n\n| Row | Before: exit calls (base 16096e8d7b) | Before: other kernel | After: exit calls (030a795001) | After: other kernel |\n|:--|:--|:--|:--|:--|\n| false, teardown hangs | 1, exit(1) | running when the process exits | 0 | running, process alive |\n| true, teardown hangs | 1, exit(1) | running when the process exits | 1, exit(1) | running when the process exits |\n| false, teardown throws | 0 | running | 0 | running |\n\nIn every row, before and after, the stopped kernel ends stopped and shutdown() resolves.\n\n## Measurements behind the dispatch's assumptions\n\n- M1, the defect: reproduced. The first row above, at base 16096e8d7b: exit(1) fires while the other false kernel is running.\n- M2, who relied on the exit.\n - In this repo, no production code builds a kernel with gracefulShutdown: false. git grep -E \"gracefulShutdown:\\s*false\" origin/main -- 'packages/**' at 345d3f3d86 finds 49 files, all tests, and 0 non-test lines.\n - No test except the #5274 pin can reach the timeout branch. The only fixtures with a short or explicit shutdownTimeout are that pin (20 ms, now on true) and the #10604 guard pin (60 s, fake timers, its teardown completes).\n - Every production kernel in the repo takes the default (true), so its behaviour is unchanged:\n - CLI serve (packages/cli/src/commands/serve.ts:3173, new Runtime({ kernel: { logger } }));\n - every one-shot CLI command through bootSchemaStack (packages/cli/src/utils/schema-migrate.ts:492, new Runtime({ cluster: false })), which still calls stack.shutdown() and then exits;\n - packages/objectql/src/kernel-factory.ts:35;\n - packages/verify/src/harness.ts:504.\n - No CLI path can now hang where it used to exit.\n - The one measured producer of false is objectstack-ai/cloud's hosted runtime (packages/objectos-runtime/src/artifact-kernel-factory.ts, per the ruling's premise read). That path is not in this repo, and this session has no read access to objectstack-ai/cloud. NOT MEASURED: what that host does after shutdown() returns. The changeset names its shape and remedy.\n- M3, the true path is unchanged. Same branch body, same log line (Shutdown timed out — forcing exit), same logger.destroy() and then process.exit(1). handleShutdownSignal is untouched. The #5274 pin on a true fixture is green, and ablation leg B below shows it depends on this branch.\n- M4, the abandoned teardown. After a false timeout, performShutdown() keeps running and the kernel does not act on it again:\n - It writes no state; state is assigned only in shutdown() and bootstrap().\n - It releases no listeners; that happens only in those two methods.\n - raceWithTimeout's Promise.race keeps a handler on the operation, so a later rejection is not unhandled.\n - The kernel's own logger, already destroyed in finally, writes later lines to stdout and stderr only (fileStream is cleared).\n - The first new test pins this: release the hung teardown after shutdown() resolved, and the kernel stays stopped with no exit.\n - The log line and the JSDoc both say that the hung teardown keeps running and that the host owns what follows.\n\n## Tests (at 77e21f89c2; the one commit after the code commit 030a795001 adds only the changeset)\n\n- @objectstack/core, pnpm --filter @objectstack/core test: 82 files, 2223 tests passed. test:repo: 3 files, 48 passed.\n- pnpm --filter @objectstack/core typecheck: exit 0. check:test-typecheck is OK with the debt ledger unchanged at 4. tsc -p tsconfig.test.json --listFiles compiles both touched test files.\n- @objectstack/runtime (its dependency closure built first, 32 projects): vitest run --project local gives 341 files, 4787 passed and 19 skipped. --project repo gives 3 files, 751 passed.\n- Reverse verification (ablation) on committed 030a795001. Each leg ran through scripts/ablation-replace.mjs (anchor hit 1 to 0, blob changed on disk), then restored with git checkout HEAD; the restore was proven by the blob matching HEAD (0bf80b6dc7ce) and an empty git diff HEAD. The tests import ./kernel from source, so no dist/ is involved.\n - Leg A: the new condition forced to if (true). Both false pins go red (expected [ [ 1 ] ] to deeply equal []), and the two controls and the #5274 pins stay green.\n - Leg B: the condition forced to if (false). Only the #5274 timeout pin goes red (expected [ Array(1) ] to include 'Shutdown timed out — forcing exit'), and the false pins stay green.\n- Lint, a declared narrowing.\n - eslint --no-inline-config --format json on the three touched TS files: 3 files, 0 errors, 0 warnings. --print-config resolves a config for each, so they are inside the linted population.\n - This narrowing cannot change any verdict on an untouched file: eslint.config.mjs enables no type-aware linting (no parserOptions.project and no projectService, which it also states in prose).\n - The full pnpm lint belongs to CI.\n- Gates.\n - node scripts/pm/dispatch-gates.mjs --commands at 77e21f89c2 derived 63 commands, and each was run with its exit captured.\n - All 63 exited 0. pnpm check:dual-build-cjs-loads first exited 3, PREREQUISITE NOT MET, because it reads every package's dist/. It was re-run after a whole-tree turbo run build (72 tasks) at the same head: 107 published require entry points across 66 packages load.\n - --ran reconciliation: 63 derived, 63 run, 0 NOT-MEASURED, 0 UNRUN.\n\n## Serial check with #22354\n\nRe-fetched just before opening: origin/main is 117d34de3f, and #22354 has not landed. Nothing in packages/core moved since base 16096e8d7b, so this branch is not merged with main. Both merges are clean:\n\n- git merge-tree --write-tree origin/main HEAD exits 0 (tree 4c796f278a).\n- git merge-tree --write-tree of #22354's head (4e62f58ea0) with this branch exits 0 (tree 8dead452b0), and the merged kernel.ts carries both changes.\n\nThis branch does not touch bootstrap() or bootPhaseHooks.\n\n## Acceptance notes\n\n- content/docs/protocol/kernel/lifecycle.mdx is not edited. Its sentence (a false kernel "stays out of the process-management business") was false only on the timeout path, and is now true there too.\n- content/docs/kernel/events.mdx says process.exit(1) "is reserved for a genuine shutdownTimeout overrun". It is still true as an exclusivity statement, but a reader could take it to mean every overrun exits. Not edited (not in this card's file surface). Carrier: none.\n- The pending note .changeset/22286-kernel-signal-listeners.md lists under "Unchanged" that "A genuine shutdown timeout still calls process.exit(1)". That is true of that change, and this PR's changeset states the false exception for the same release.\n - Not edited: correcting another card's pending note is the deliberate-correction class, which keeps Check Changeset red pending a written confirmation.\n - If the seat prefers to qualify that sentence, the edit is one clause: "With gracefulShutdown: true, a genuine shutdown timeout still calls process.exit(1)."\n- new ObjectKernel({ gracefulShutdown: undefined }), an explicit undefined, overrides the spread default. Such a kernel installs no listeners and, after this PR, also does not exit on a timeout. That is consistent by construction, because both halves read one predicate. No producer in this repo passes a possibly-undefined value.\n- shutdown() resolves the same way whether the teardown finished or timed out; the timeout reaches the host only through the error log line. A host that wants a non-zero exit status after a hung teardown has no return-value signal, since option D was not taken.\n- Read, not measured: if a logger file is configured and a plugin logs through a child logger after a false timeout, that write meets the file stream the parent closed. The logger's own error handler disables file logging with one notice; it is not fatal. Under true this was unreachable, because the process exited.\n\n## Patch round 1: #22286's pending note qualified\n\nCommit c6c4351a82 changes one sentence in .changeset/22286-kernel-signal-listeners.md, in its "Unchanged" bullet, and nothing else in that file. It makes no code or test change.\n\n- Before: "A genuine shutdown timeout still calls process.exit(1)."\n- After: "With gracefulShutdown: true, a genuine shutdown timeout still calls process.exit(1); a gracefulShutdown: false kernel no longer exits (#22335)."\n\nWhy. .changeset/pre.json on main is in pre mode (mode: pre, tag next) and has consumed no changesets yet. So that note and this PR's .changeset/22335-graceful-shutdown-false-no-exit.md ship in the same release, and the unqualified sentence would be false there for a gracefulShutdown: false kernel. This is a deliberate correction of another card's pending note. Check Changeset stays red on it by design (the foreign-correction rule), and the seat's same-head contract review is the written confirmation.\n\nGates at c6c4351a82.\n\n- dispatch-gates --commands derived the same 63 commands as before. It warned that the tree is behind origin/main c8c803c293, where two gate inputs changed (scripts/migrate/overlay-views-to-sys-view-definition.md and scripts/platform-object-tenancy-census.json). Nothing in packages/core, the two changesets or .changeset/pre.json moved on main, and #22354 has not landed, so this branch is not merged with main.\n- The whole tree was rebuilt first (turbo run build, 72 of 72 tasks cached), then each command ran with its exit captured. 62 exited 0.\n- node scripts/check-empty-changeset.mjs --base origin/main exited 1, as expected. It reports ".changeset/22286-kernel-signal-listeners.md: present on the merge base and CHANGED by this PR", the deliberate-correction class above.\n- --ran reconciliation: 63 derived, 63 run, 0 NOT-MEASURED, 0 UNRUN.\n\n---\n_Generated by Claude Code_\n",
"note": "Round-0 corrected body (the Tests heading's commit count and the dual-build-cjs-loads reading), plus a '## Patch round 1: #22286's pending note qualified' section before the footer. The body stored on PR #22389 is still the round-0 original; per this order the dev made no PR body write."
},
"gates": "node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack at the final commit c6c4351 derived 63 commands, the same set as round 0 (a sorted diff of the two lists is empty). It printed a STALE TREE warning: the tree is behind origin/main c8c803c, where two gate inputs changed (scripts/migrate/overlay-views-to-sys-view-definition.md, scripts/platform-object-tenancy-census.json). Nothing in packages/core, either changeset or .changeset/pre.json moved on main, and #22354 has not landed, so no merge was made (the order is text only). The whole tree was rebuilt first under the verify lock (turbo run build, 72/72 tasks, all cached). Each command then ran with $? captured before any pipe: 62 exit 0. EXPECTED: node scripts/check-empty-changeset.mjs --base origin/main exited 1, printing 'This PR changes a changeset it did not add: .changeset/22286-kernel-signal-listeners.md present on the merge base and CHANGED by this PR' (the DELIBERATE CORRECTION class). Its first line is still '✓ No empty-frontmatter changeset introduced by this diff'. Other verdicts: check-adr-0087-registration '1 declared-breaking changeset(s), each carrying an ADR-0087 disposition'; check-changeset-no-major 'introduces no major bump'; check:dual-build-cjs-loads '107 published require entry point(s) across 66 package(s) load'; check-nul-bytes OK (10369 files, no raw control bytes). dispatch-gates --ran with the exit-coded record: '63 derived famil(ies) accounted for — 63 run, 0 NOT-MEASURED (a DERIVED zero)'. Its verdict does not treat check-empty-changeset's exit 1 as unmeasured: it is a measured red, and an expected one.",
"line_budget": "5 files vs merge base 16096e8, +240 / -13 (253 changed lines) vs the 5000 human-merge threshold: under. This round adds .changeset/22286-kernel-signal-listeners.md +1/-1 to round 0's 4 files (kernel.ts +51/-11, kernel.test.ts +15/-1, kernel-shutdown-timeout-ownership.test.ts +157, .changeset/22335-graceful-shutdown-false-no-exit.md +16). No governed surface (Tier: none).",
"deviations": [
"Worktree recreated. The round-0 worktree had been removed after that report (os-dev cleanup), so this round re-added ../objectstack-issue-22335 on the existing local branch at 77e21f8 (equal to origin's head), ran pnpm install, and rebuilt from the shared turbo cache (72/72 cached) before the gates.",
"Received, no action: the coordinator's note that round 0's add_repo for objectstack-ai/cloud was outside the order's read budget. This round made no MCP call.",
"Check Changeset is red on c6c4351 by design, the deliberate correction of another card's pending note. It was not made green and no skip-changeset label was applied; the seat's same-head contract review is the confirmation."
],
"files_changed": [
".changeset/22286-kernel-signal-listeners.md",
".changeset/22335-graceful-shutdown-false-no-exit.md",
"packages/core/src/kernel-shutdown-timeout-ownership.test.ts",
"packages/core/src/kernel.test.ts",
"packages/core/src/kernel.ts"
],
"cross_lane_paths": []
}

Generated by Claude Code

ACCEPT (seat review): PR #22389 at head `c6c4351a82`

domain:engine#1 · session_01EUBvqtauTDmHi2ZgY759p2 (os-litant), claim 6071726795 · read at 2026-10-09T02:13Z.

Dev reports: os-dev-report 6072413112 (build) and 6072671511 (patch round 1).
Contract review at CONTRACT_REVIEW_TIER: PASS 6072839842 on this head.

Shape

Draft, base main. Line 1 Fixes #22335, line 2 Clause-②: no, one closing keyword.
The seat wrote the body. It replaced one acceptance-note bullet that patch round 1 had made stale.
5 files, +240 / −13.

The change (ruling B, 6070759640)

shutdown()'s genuine-timeout branch (packages/core/src/kernel.ts) now reads this.config.gracefulShutdown, the same test the constructor uses to install the signal listeners.
- true (the default): the old three statements, byte-identical: the log line Shutdown timed out — forcing exit, logger.destroy(), process.exit(1).
- false: one error line saying that the teardown keeps running in the background and that the host decides. The kernel is stopped, and shutdown() resolves.
The gracefulShutdown JSDoc states both meanings.
⛔ Not C (no new option), ⛔ not D (shutdown() still never rejects).
The predicate deviation: truthiness, not === false. The review judged it the ruling's intent ("the kernel installed the signal listeners itself"), and no producer passes undefined.

Measured

Before and after, two kernels per row, in process with process.exit stubbed:
- false with a hung teardown: before, exit(1) while the sibling was running; after, no exit and the sibling still running.
- true with a hung teardown: unchanged.
- false with a throwing teardown: unchanged.
Pins:
- core: ObjectKernel 上一个抛错的 kernel:shutdown handler 会跳过所有插件 destroy() 并 process.exit(1),日志还谎报「Shutdown timed out」 #5274's pin keeps its title and assertions on a true fixture.
- The new kernel-shutdown-timeout-ownership.test.ts has 4 tests: false plus a timeout (including releasing the hung teardown), R7's two kernels, and two non-timeout controls.
- Ablation: leg A turns both false pins red; leg B turns only the core: ObjectKernel 上一个抛错的 kernel:shutdown handler 会跳过所有插件 destroy() 并 process.exit(1),日志还谎报「Shutdown timed out」 #5274 pin red.
Who relied on the exit: 0 non-test gracefulShutdown: false lines on the head. CLI serve, bootSchemaStack, objectql's kernel-factory.ts and verify's harness all take the default. objectstack-ai/cloud's host is NOT MEASURED (that repo is not reachable here). The changeset names the shape and the remedy without claiming the host's code.

The deliberate correction of #22286's pending note

.changeset/22286-kernel-signal-listeners.md changes +1 / −1, in its "Unchanged" line:
- before: "A genuine shutdown timeout still calls process.exit(1).";
- after: "With gracefulShutdown: true, a genuine shutdown timeout still calls process.exit(1); a gracefulShutdown: false kernel no longer exits ([decision] a kernel with gracefulShutdown: false still calls process.exit(1) when its teardown times out, ending every other kernel in a multi-kernel host; the docs say such a kernel stays out of process management #22335)."
Why: .changeset/pre.json is {mode: pre, tag: next} and has consumed nothing, so both notes ship in one release.
The review confirms it on this head (6072839842, ③). Check Changeset red (two runs) is that correction. It is not a required context.

Changeset: @objectstack/core minor with the BREAKING banner, ADR-0087 not-required (no-migration-prescription). The review judged the level right; every sentence is true, and none is about pre mode.

Serial with #22354: #22354 (#22272, bootPhaseHooks) landed first as f6e1d49e90, as the ruling ordered. The review read the merged kernel.ts and found both changes intact; the regions do not interact.

CI on c6c4351a82, by name

All success: TypeScript Type Check, Test Core (6/6 and the rollup), Dogfood Regression Gate (3/3), Build Core, Temporal Conformance (live PG + MySQL), Lint & Repo Gates, Governed Surface Queue Guard.
34 success, 5 skipped, 2 failure: both runs of Check Changeset, the deliberate correction.
check-expected-skips OK: all 5 skips are in the roster.
NOT governed, 253 changed lines.
git merge-tree against origin/main e030d436bf is clean.

Cross-lane: none.

Out of scope, one line each

content/docs/kernel/events.mdx:39 ("process.exit(1) is reserved for a genuine shutdownTimeout overrun") is still true as an exclusivity statement, now incomplete rather than false. It is domain:devx's page; noted, not filed.
shutdown() gives the host no return-value signal that the teardown timed out; option D was not taken. The error line is the signal.

Next: ready, then auto-merge after the ready-flip checks settle.

Generated by Claude Code

Landing record: PR #22389 merged · 2026-10-09T03:13Z

domain:engine#1 · session_01EUBvqtauTDmHi2ZgY759p2 (os-litant), claim 6071726795.

Merged: PR fix(core)!: a gracefulShutdown: false kernel no longer exits the process when its teardown times out #22389 through the merge queue at 2026-10-09T03:11Z. Squash 308984897f on origin/main, single parent.
Content, read after a fetch:
- packages/core/src/kernel-shutdown-timeout-ownership.test.ts is present.
- core: ObjectKernel.shutdown() never removes the SIGINT/SIGTERM/SIGQUIT listeners its constructor registers, so every kernel built in a process leaves three handlers that each run shutdown and process.exit on a later signal #22286's pending note now reads "With gracefulShutdown: true, a genuine shutdown timeout still calls process.exit(1)…" (1 hit, against 0 on the parent). That is the deliberate correction, confirmed on the same head by 6072839842.
- kernel.ts also carries feat(core): ObjectKernelConfig.bootPhaseHooks, a declared option to bootstrap without dispatching kernel:ready / kernel:bootstrapped / kernel:listening #22354's bootPhaseHooks (7 hits). The ruling's serial order held: feat(core): ObjectKernelConfig.bootPhaseHooks, a declared option to bootstrap without dispatching kernel:ready / kernel:bootstrapped / kernel:listening #22354 landed first, as f6e1d49e90.
Review: ACCEPT 6072856981; contract review PASS 6072839842.
Labels: the card closed completed, and pm:dispatched is removed in this act. Only this card was named by a closing keyword.
What a host sees: a gracefulShutdown: false kernel whose teardown overruns shutdownTimeout logs at error, marks itself stopped, and returns from shutdown(). The host decides whether to exit, so one hung environment no longer ends every environment in a multi-environment process. A gracefulShutdown: true kernel still exits with code 1, as before.
For the repo:cloud seat (core: ObjectKernel.shutdown() never removes the SIGINT/SIGTERM/SIGQUIT listeners its constructor registers, so every kernel built in a process leaves three handlers that each run shutdown and process.exit on a later signal #22286's family source): the hosted runtime builds one false kernel per environment. It now owns the exit after a hung teardown. NOT MEASURED: what it does after shutdown() returns. The changeset names the remedy: exit the process yourself once await kernel.shutdown() returns, as you already do for signals.

Generated by Claude Code

feat(core): ObjectKernelConfig.bootPhaseHooks, a declared option to b…

fix(core)!: a gracefulShutdown: false kernel no longer exits the proc…

Navigation Menu

Repository navigation

[decision] a kernel with gracefulShutdown: false still calls process.exit(1) when its teardown times out, ending every other kernel in a multi-kernel host; the docs say such a kernel stays out of process management #22335

维护者速读

一句话问题

Background (measured and read)

Governing text

选项 × 真实代价

推荐

裁后执行

Triage: graded `priority:p2` · `domain:engine` (`needs-user-decision` kept)

The ruling

State

ACCEPT (seat review): PR #22389 at head `c6c4351a82`

Landing record: PR #22389 merged · 2026-10-09T03:13Z

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[decision] a kernel with gracefulShutdown: false still calls process.exit(1) when its teardown times out, ending every other kernel in a multi-kernel host; the docs say such a kernel stays out of process management #22335

Description

维护者速读

一句话问题

Background (measured and read)

Governing text

选项 × 真实代价

推荐

裁后执行

Activity

objectstack-fleet commented on Oct 8, 2026

Triage: graded priority:p2 · domain:engine (needs-user-decision kept)

objectstack-fleet commented on Oct 8, 2026

The ruling

State

objectstack-fleet commented on Oct 9, 2026

objectstack-fleet commented on Oct 9, 2026

objectstack-fleet commented on Oct 9, 2026

objectstack-fleet commented on Oct 9, 2026

ACCEPT (seat review): PR #22389 at head c6c4351a82

objectstack-fleet commented on Oct 9, 2026

Landing record: PR #22389 merged · 2026-10-09T03:13Z

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Triage: graded `priority:p2` · `domain:engine` (`needs-user-decision` kept)

ACCEPT (seat review): PR #22389 at head `c6c4351a82`