@bakery-framework/cli 1.0.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Kyle Cyrus Santos Obille
+
+The Software is provided subject to the standard MIT License, as detailed below, with the addition of the Commons Clause v1.0.
+
+The Commons Clause v1.0
+
+The Software is provided to you by the Licensor under the License, as defined below, subject to the following condition.
+
+Without limiting other conditions in the License, the grant of rights under the License will not include, and the License does not grant to you, the right to Sell the Software.
+
+For purposes of the foregoing, “Sell” means practicing any or all of the rights granted to you under the License to provide to third parties, for a fee or other consideration (including without limitation fees for hosting or consulting/support services related to the Software), a product or service whose value derives, entirely or substantially, from the functionality of the Software. Any license notice or attribution required by the License must also include this Commons Clause License Condition notice.
+
+Standard MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software (subject to the Commons Clause condition above), and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @bakery-framework/cli
+
+The `bakery` binary: process-mode dispatch, the dev watcher, and clustering for
+[Bakery](https://github.com/obillekyle/bakery).
+
+**Bun only.** Ships TypeScript source with no build step.
+
+```bash
+bun add @bakery-framework/cli
+```
+
+## Usage
+
+```json
+{
+  "scripts": {
+    "dev": "bakery --dev",
+    "start": "bakery"
+  }
+}
+```
+
+| Command | Mode |
+| --- | --- |
+| `bakery --dev` | Dev server: file watcher, live reload, on-demand compile |
+| `bakery` | Production |
+| `bakery --threads 4` | Production cluster of 4 workers (ignored under `--dev`) |
+| `bakery --sync` | Run schema sync, **then boot**. Not a standalone sync |
+
+There is no `--port` flag. The port resolves as `PORT` → `port` in
+`server.config.ts` → `3000`. A malformed `PORT` is a boot error rather than a
+fallback: `PORT=3000x` exits 1 instead of binding somewhere random.
+
+For a standalone schema sync in a deploy step, drive `SyncService` from
+`@bakery-framework/orm/sync` directly — `--sync` starts a server afterwards.
+
+## License
+
+MIT with the Commons Clause v1.0 — see [LICENSE](./LICENSE).
+
+**Not an OSI-approved licence.** The Commons Clause removes the right to *sell*
+the software — meaning to charge for a product or service whose value derives
+substantially from it, hosting and support included. Everything else the MIT
+licence grants is unchanged: use it, modify it, ship it inside your own product.
+If your organisation only permits OSI-approved dependencies, this will not pass
+that check.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@bakery-framework/cli",
+  "version": "1.0.0",
+  "description": "Bakery entry point and process supervision: mode dispatch, dev watcher, cluster.",
+  "keywords": [
+    "bakery",
+    "bun",
+    "cli",
+    "dev-server",
+    "hot-reload",
+    "cluster"
+  ],
+  "author": "obillekyle",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/obillekyle/bakery.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/obillekyle/bakery#readme",
+  "bugs": "https://github.com/obillekyle/bakery/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "bin": {
+    "bakery": "./src/index.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/tests"
+  ],
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "dependencies": {
+    "@bakery-framework/core": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@bakery-framework/orm": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@bakery-framework/orm": {
+      "optional": true
+    }
+  }
+}

package/src/dev.ts

@@ -0,0 +1,158 @@
+import '@bakery-framework/core/core/init'
+import { errorMsg, log, serveLog } from '@bakery-framework/core/logger'
+import { hasORM } from './orm'
+
+log({
+  by: 'process',
+  msg: `Starting server (PID: ${process.pid})...`,
+})
+serveLog.STARTING({ mode: 'development' })
+
+let config: unknown
+
+try {
+  const { initConfig } = await import('@bakery-framework/core/core/config')
+  const { initImportMap, initHostImportMaps } = await import(
+    '@bakery-framework/core/utils/http'
+  )
+  const { setupPlugins } = await import('@bakery-framework/core/startup')
+  const { syncTSConfigPaths } = await import(
+    '@bakery-framework/core/compiler/tsconfig-sync'
+  )
+
+  config = await initConfig()
+  // Still before initImportMap(): a plugin's setup() may contribute entries.
+  // setupPlugins() memoises, so setupServer()'s later call is a no-op here.
+  await setupPlugins()
+  await initImportMap()
+  initHostImportMaps()
+  await syncTSConfigPaths()
+} catch (error: any) {
+  // errorMsg() already yields the stack, so the structured line below carries
+  // everything the raw console.error used to duplicate.
+  serveLog.UNHANDLED_ERR({ error: `Config init failed: ${errorMsg(error)}` })
+  process.exit(1)
+}
+
+/**
+ * Hash everything the boot-time schema sync reads: the schema source files
+ * (resolved with the same probe order as orm/sync/load.ts — configured path,
+ * then the `orm/` folder layout, then a root `schema.ts`) plus the DB target,
+ * since switching `DB_URL` changes what "synced" means.
+ *
+ * Returns `null` for any indeterminate state — a configured path that does not
+ * exist, an unreadable file — so `classifySchemaSync` fails closed into
+ * re-syncing. Total absence of a schema is *not* indeterminate (it is a
+ * supported state for the defaults) and hashes to a stable value.
+ */
+async function computeSchemaHash(
+  configured: string | undefined,
+): Promise<string | null> {
+  const { fs, Try } = await import('@bakery-framework/core/utils')
+
+  const files: string[] = []
+  const scanDir = async (dir: string) => {
+    for await (const file of new Bun.Glob('*.ts').scan({
+      cwd: dir,
+      absolute: true,
+    })) {
+      files.push(file)
+    }
+  }
+
+  const [error] = await Try.catch(
+    (async () => {
+      if (configured) {
+        const path = fs.resolve(fs.cwd, configured)
+        if (await fs.isDir(path)) {
+          await scanDir(path)
+        } else if (await Bun.file(path).exists()) {
+          files.push(path)
+        } else {
+          // Configured-but-missing is SyncService's SCHEMA_NOT_FOUND case:
+          // let the sync run and produce its proper error.
+          throw new Error(`configured schema path not found: ${path}`)
+        }
+      } else if (await Bun.file(`${fs.cwd}/orm/index.ts`).exists()) {
+        await scanDir(`${fs.cwd}/orm`)
+      } else if (await Bun.file(`${fs.cwd}/schema.ts`).exists()) {
+        files.push(`${fs.cwd}/schema.ts`)
+      }
+    })(),
+  )
+  if (error) return null
+
+  files.sort()
+  const hasher = new Bun.CryptoHasher('sha256')
+  hasher.update(process.env.DB_URL || process.env.DATABASE_URL || '')
+  for (const file of files) {
+    hasher.update(`\0${file}\0`)
+    const [readError, content] = await Try.catch(Bun.file(file).text())
+    if (readError) return null
+    hasher.update(content)
+  }
+  return hasher.digest('hex')
+}
+
+// The entire block is schema sync, so with no ORM there is nothing here to do.
+// Silently: a dev boot of an app that never had a database should not report
+// the absence of one on every reload.
+if (hasORM()) {
+  try {
+    const { Bakery } = await import('@bakery-framework/core')
+    const { classifySchemaSync } = await import(
+      '@bakery-framework/core/compiler'
+    )
+    const { schemaFromConfig } = await import('@bakery-framework/orm/sync/load')
+    const { Try } = await import('@bakery-framework/core/utils')
+
+    const hashFile = `${Bakery.cacheDir}/schema-sync.hash`
+    const currentHash = await computeSchemaHash(schemaFromConfig(config))
+    const [, stored] = await Try.catch(Bun.file(hashFile).text())
+
+    const decision = classifySchemaSync({
+      force: process.argv.includes('--sync') || process.argv.includes('-s'),
+      currentHash,
+      storedHash: stored?.trim() || null,
+      // Only meaningful for the default SQLite target; with a DB_URL there is
+      // no local file to stat, and the hash (which covers DB_URL) plus `--sync`
+      // are the levers for an externally reset database.
+      dbMissing:
+        !process.env.DB_URL &&
+        !process.env.DATABASE_URL &&
+        !(await Bun.file(`${Bakery.dataDir}/server.db`).exists()),
+    })
+
+    if (decision === 'skip') {
+      serveLog.SCHEMA_SYNC_SKIP()
+      // Only on the skip path. When a sync runs it reports drift itself, from
+      // the plan it just built; here nothing else would ever look. Measured at
+      // 2.7ms median against apps/example (4 tables) — it is one introspection
+      // pass, so it grows with table count, which is why it is not on the path
+      // that is about to introspect anyway.
+      const { initDB, connection } = await import(
+        '@bakery-framework/orm/connection'
+      )
+      const { detectDrift } = await import('@bakery-framework/orm/sync/ledger')
+      await initDB()
+      const drift = await detectDrift(connection)
+      if (drift) serveLog.SCHEMA_DRIFT({ reason: drift.reason })
+    } else {
+      const { SyncService } = await import('@bakery-framework/orm/sync')
+      await SyncService.run()
+      // Recorded only after run() resolves: a failed or aborted sync must leave
+      // the previous hash (or none) behind so the next boot re-syncs.
+      if (currentHash) {
+        const [writeError] = await Try.catch(Bun.write(hashFile, currentHash))
+        // A failed record is tolerated silently: its only consequence is that
+        // the next boot syncs again, which is the safe direction.
+        void writeError
+      }
+    }
+  } catch (error: any) {
+    serveLog.UNHANDLED_ERR({ error: `Startup failed: ${errorMsg(error)}` })
+    process.exit(1)
+  }
+}
+
+await import('./worker')

package/src/index.ts

@@ -0,0 +1,68 @@
+#!/usr/bin/env bun
+
+import '@bakery-framework/core/core/init'
+
+const isDev = import.meta.env.DEV
+const isDevWorker = import.meta.env.DEV_WORKER
+const isThreadWorker = import.meta.env.THREAD_WORKER
+
+function getThreadsOption(): number | null {
+  const args = process.argv.slice(2)
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === '--threads' || arg === '-t') {
+      const next = args[i + 1]
+      if (next && /^\d+$/.test(next)) {
+        return Math.max(1, parseInt(next, 10))
+      }
+      return Math.min(Math.max(1, navigator.hardwareConcurrency || 4), 8)
+    }
+    if (arg.startsWith('--threads=') || arg.startsWith('-t=')) {
+      const val = arg.split('=')[1]
+      if (val && /^\d+$/.test(val)) {
+        return Math.max(1, parseInt(val, 10))
+      }
+      return Math.min(Math.max(1, navigator.hardwareConcurrency || 4), 8)
+    }
+  }
+  return null
+}
+
+const threadsOption = getThreadsOption()
+
+if (
+  (process.argv.includes('--sync') || process.argv.includes('-s')) &&
+  !isDevWorker &&
+  !isThreadWorker
+) {
+  // The one place absence is an *error* rather than a skip. Everywhere else the
+  // ORM is missing because the app never wanted one; here the user typed
+  // `--sync`, which is a request to sync a database, and quietly doing nothing
+  // would look like it worked.
+  const { hasORM, ORM_MISSING } = await import('./orm')
+  if (!hasORM()) {
+    const { serveLog } = await import('@bakery-framework/core/logger')
+    serveLog.UNHANDLED_ERR({ error: `--sync: ${ORM_MISSING}` })
+    process.exit(1)
+  }
+  const { SyncService } = await import('@bakery-framework/orm/sync')
+  await SyncService.run()
+}
+try {
+  if (threadsOption !== null && !isDevWorker && !isThreadWorker && !isDev) {
+    const { handleThreadsMaster } = await import('./threads')
+    await handleThreadsMaster(threadsOption)
+  } else if (!isDev) {
+    await import('./prod')
+  } else if (isDevWorker || isThreadWorker) {
+    await import('./dev')
+  } else {
+    await import('./watcher')
+  }
+} catch (error: any) {
+  // Deliberately console.error and not the structured logger: this is the
+  // last-resort handler around the very imports that load the logger, so
+  // reaching for it here could throw and mask the original failure.
+  console.error('Fatal unhandled error during startup:', error?.stack || error)
+  process.exit(1)
+}

package/src/orm.ts

@@ -0,0 +1,63 @@
+/**
+ * Is `@bakery-framework/orm` installed?
+ *
+ * The CLI declares it as an **optional peer**, so an app scaffolded with
+ * `--no-orm` never downloads it. Every use of it in this package is already an
+ * `await import()`, so its absence is not a module-graph problem — it is a
+ * question this file answers once, before anything tries.
+ *
+ * **Absence and breakage must not be conflated, and telling them apart is the
+ * only reason this file exists.** The obvious implementation is to wrap the
+ * `await import()` in a try and treat a throw as "not installed", and it is
+ * wrong in the direction that costs data: a database that is configured but
+ * unreachable, a `DB_URL` with a typo, a schema module that throws at import —
+ * all of those would be swallowed as "no ORM here" and the server would boot
+ * happily with no database and no complaint. `initDB` failing has always been
+ * fatal and stays fatal. Only *resolution* failing is soft.
+ *
+ * So the question is asked of the resolver, which cannot be answered wrongly by
+ * a broken database: either the specifier resolves to a file on disk or it does
+ * not.
+ */
+
+let resolved: boolean | null = null
+
+/**
+ * True when `@bakery-framework/orm` can be resolved from this package.
+ *
+ * Memoised: it is asked on the boot path and once more per shutdown, the answer
+ * cannot change within a process, and the filesystem walk is not free.
+ *
+ * `import.meta.dir` is the resolution base on purpose — it is what a real
+ * `import` from this module would use, so the answer matches what the `await
+ * import()` calls below it will actually do. Resolving from `process.cwd()`
+ * would ask a different question (does the *app* see it) and could disagree,
+ * which is the kind of near-miss that produces a "sometimes it works" report.
+ */
+export function hasORM(): boolean {
+  if (resolved !== null) return resolved
+  try {
+    // The subpath, not the package root: `exports` can name one and not the
+    // other, and this is the one every caller here actually imports.
+    Bun.resolveSync('@bakery-framework/orm/connection', import.meta.dir)
+    resolved = true
+  } catch {
+    // Not installed. The only expected outcome of this catch, and the reason
+    // it is allowed to be silent — see the note above about what is *not*
+    // routed through here.
+    resolved = false
+  }
+  return resolved
+}
+
+/**
+ * What to print when something needs the ORM and it is not there.
+ *
+ * One string, so the instruction is identical wherever it surfaces. It names
+ * the package rather than describing it: the fix is a single `bun add` and the
+ * message should be copy-pasteable.
+ */
+export const ORM_MISSING =
+  'This needs @bakery-framework/orm, which is not installed. It is an optional peer ' +
+  'dependency of the CLI, so an app scaffolded without a database does not ' +
+  'carry it. Add it with `bun add @bakery-framework/orm`.'

package/src/prod.ts

@@ -0,0 +1,49 @@
+import '@bakery-framework/core/core/init'
+import { errorMsg, log, serveLog } from '@bakery-framework/core/logger'
+import { hasORM } from './orm'
+
+log({
+  by: 'process',
+  msg: `Starting server (PID: ${process.pid})...`,
+})
+serveLog.STARTING({ mode: 'production' })
+
+try {
+  const { initConfig } = await import('@bakery-framework/core/core/config')
+  const { setupPlugins } = await import('@bakery-framework/core/startup')
+  const { initImportMap, initHostImportMaps } = await import(
+    '@bakery-framework/core/utils/http'
+  )
+
+  await initConfig()
+  // Before initImportMap() so plugin-contributed entries land in it; memoised,
+  // so the later setupServer() call inside worker.ts does not repeat it.
+  await setupPlugins()
+  await initImportMap()
+  initHostImportMaps()
+} catch (error: any) {
+  serveLog.UNHANDLED_ERR({ error: `Config init failed: ${errorMsg(error)}` })
+  process.exit(1)
+}
+
+// See the same guard in worker.ts: absent is fine, present-and-broken is fatal.
+if (hasORM()) {
+  try {
+    const { initDB } = await import('@bakery-framework/orm/connection')
+    await initDB()
+  } catch (error: any) {
+    serveLog.UNHANDLED_ERR({
+      error: `Database initialization failed: ${errorMsg(error)}`,
+    })
+    process.exit(1)
+  }
+}
+
+try {
+  await import('./worker')
+} catch (err: any) {
+  serveLog.UNHANDLED_ERR({
+    error: `Worker initialization failed: ${errorMsg(err)}`,
+  })
+  process.exit(1)
+}

package/src/rate-limit.ts

@@ -0,0 +1,96 @@
+import { LRUCache } from '@bakery-framework/core/cache/lru'
+
+/**
+ * Number of token buckets in `SharedMemoryPool`'s rate-limit region.
+ *
+ * Must match `RATE_LIMIT_SLOT_COUNT` there: `consumeToken()` fails closed on an
+ * out-of-range slot, so a value that is too large would deny every request that
+ * hashed past the end of the region. `rate-limit.test.ts` cross-checks this
+ * against a real pool rather than trusting the two constants to stay in step.
+ */
+export const RATE_LIMIT_SLOTS = 1024
+
+/**
+ * Map a rate-limit key (client IP, or whatever `rateLimit.keyBy` returns) onto
+ * one of the shared pool's token buckets.
+ *
+ * `Bun.hash` returns a **u64 bigint**. The original
+ * `Number(Bun.hash(key)) % 1024` converted first, so every bit below 2^53 was
+ * rounded away before the modulo ever ran: measured over 20k client IPs that
+ * left 100 reachable buckets out of 1024 with **83% of all keys in bucket 0**.
+ * Rate limiting is on by default at `{max: 100, refill: 10}`, so in practice
+ * most clients shared one bucket with a sustained ceiling of 10 requests per
+ * second — one busy client 429'd everyone else, and an ordinary page load
+ * (many requests inside a single refill tick) tripped it on its own.
+ *
+ * Taking the modulo in bigint space and converting the small result keeps the
+ * low bits, which are the only ones that matter here. `wyhash` is what plain
+ * `Bun.hash` already calls; naming it is what makes the return type `bigint`
+ * instead of `number | bigint`.
+ */
+export function rateLimitSlot(key: string): number {
+  return Number(Bun.hash.wyhash(key) % BigInt(RATE_LIMIT_SLOTS))
+}
+
+/**
+ * How long one RATE_LIMITED log line covers for a key. The "30s" in
+ * `RATE_LIMITED_SUPPRESSED`'s message text states this value; keep them in
+ * step.
+ */
+export const RATE_LIMIT_LOG_WINDOW_MS = 30_000
+
+/**
+ * Bound for the log-sampling state below. A few hundred concurrently-flooding
+ * keys is plenty; past it the LRU evicts and the evicted key logs again.
+ */
+export const RATE_LIMIT_LOG_KEYS = 512
+
+/** Per-key `{last logged, suppressed since}` for `sampleRateLimitLog`. */
+const logState = new LRUCache<string, { last: number; suppressed: number }>(
+  RATE_LIMIT_LOG_KEYS,
+)
+
+/**
+ * Whether this rejection's RATE_LIMITED line should be written at all.
+ *
+ * The constraint is availability under flood: stdout writes are effectively
+ * synchronous on Windows, so one log line per rejected request hands the flood
+ * the limiter just absorbed straight to the logger — the 429 path becomes as
+ * expensive as the work it was refusing. At most one line per key per
+ * `RATE_LIMIT_LOG_WINDOW_MS` instead.
+ *
+ * Returns `null` when the line must be suppressed, otherwise the number of
+ * rejections suppressed since the key's previous line (0 for a first
+ * offender). Bounded per convention 6 — the key derives from client-controlled
+ * data (IP, or `rateLimit.keyBy`), so the state lives in an LRU and an evicted
+ * key simply logs again as if new. Over-logging is the safe direction to be
+ * wrong in.
+ */
+export function sampleRateLimitLog(
+  key: string,
+  now: number = Date.now(),
+): number | null {
+  const entry = logState.get(key)
+  if (entry && now - entry.last < RATE_LIMIT_LOG_WINDOW_MS) {
+    entry.suppressed++
+    return null
+  }
+
+  const suppressed = entry?.suppressed ?? 0
+  logState.set(key, { last: now, suppressed: 0 })
+  return suppressed
+}
+
+/** Test seam, in the family of `__resetTestConfig` / `__resetTestDb`. */
+export function __resetRateLimitLogState(): void {
+  logState.clear()
+}
+
+/**
+ * Seconds until the bucket holds a token again, for the 429's `Retry-After`
+ * header. Whole seconds per RFC 9110, and never less than 1 — "0" would tell
+ * the client to retry immediately, which is the opposite of the point.
+ */
+export function retryAfterSeconds(refill: number): number {
+  return Math.max(1, Math.ceil(1 / refill))
+}

package/src/shutdown.ts

@@ -0,0 +1,152 @@
+import { Bakery } from '@bakery-framework/core/core/bakery'
+import { errorMsg, log, serveLog } from '@bakery-framework/core/logger'
+import { Try } from '@bakery-framework/core/utils/common'
+import { hasORM } from './orm'
+import { FLUSH_TIMEOUT_MS } from './threads'
+
+let running: Promise<void> | null = null
+
+/**
+ * How long this process gives its own teardown before giving up on it.
+ *
+ * The same bound the cluster master applies to a worker's pre-terminate flush,
+ * for the same reason it states: *a wedged worker must delay shutdown, not
+ * prevent it*. The standalone path did not honour that — `runShutdownSequence()`
+ * gated `process.exit(0)` with no deadline, so one hook that never settled meant
+ * SIGINT never terminated the process and Ctrl-C appeared to do nothing.
+ */
+export const SHUTDOWN_TIMEOUT_MS = FLUSH_TIMEOUT_MS
+
+/**
+ * The two teardown steps that close process-wide resources. Behind a seam
+ * because a test that ran the real ones would close the cache database and the
+ * ORM connection for every test file scheduled after it — see `__setTestDb` in
+ * `orm/connection.ts` for the same pattern and the same reason.
+ */
+export interface ShutdownTeardown {
+  closeCache: () => Promise<void> | void
+  closeDatabase: () => Promise<void> | void
+}
+
+const defaultTeardown: ShutdownTeardown = {
+  closeCache: async () => {
+    const { closeCacheDb } = await import('@bakery-framework/core/cache/tiered')
+    closeCacheDb()
+  },
+  closeDatabase: async () => {
+    // Nothing was ever opened, so there is nothing to close.
+    if (!hasORM()) return
+    const { closeDB } = await import('@bakery-framework/orm/connection')
+    await closeDB()
+  },
+}
+
+let testTeardown: ShutdownTeardown | null = null
+
+/** Test seam — see `ShutdownTeardown`. */
+export function __setTestTeardown(teardown: ShutdownTeardown): void {
+  testTeardown = teardown
+}
+
+export function __resetTestTeardown(): void {
+  testTeardown = null
+}
+
+/**
+ * Run every teardown step this process owns, once.
+ *
+ * Memoised rather than guarded by a boolean: a cluster worker can be asked to
+ * flush by the master *and* receive a signal, and the second caller has to wait
+ * for the first run to finish rather than race it or skip it.
+ *
+ * ## Order
+ *
+ * 1. `Bakery.config.onShutdown()` — the application's own hook.
+ * 2. `Bakery.shutdownHooks` — framework internals (tiered-cache flush, session
+ *    prune timer).
+ * 3. `PluginHooks.onShutdown()` — plugins.
+ * 4. Resource close — the shared cache database, then the ORM connection.
+ *
+ * The app goes first because it is the only participant that can still need the
+ * framework intact: step 2 flushes the session/cache tier, so an app hook that
+ * wants to write a last session value has to run before it, not after. That is
+ * also the exact reverse of startup, where `runStartupBanner()` calls
+ * `PluginHooks.onStart()` and then `config.onStart()` last — last up, first down.
+ *
+ * Step 4 exists because steps 1–3 all still write. `cache/tiered.ts` used to
+ * close the shared cache database inside its own step-2 hook, which is
+ * registered at module-evaluation time and so runs *first* of all the framework
+ * hooks — before every plugin. The analytics plugin's shutdown flush binds that
+ * same handle, so its statements threw and its page-hit and history deltas were
+ * dropped on every clean stop. The ORM connection was closed by nothing at all:
+ * `closeDB()` had exactly one caller, the `db:sync` CLI, so a SIGINT abandoned
+ * a MySQL or Postgres pool mid-flight.
+ *
+ * Every step is isolated: a throwing hook is reported and the rest still run.
+ * A shutdown that aborts halfway loses precisely the data this sequence exists
+ * to save. The whole sequence is bounded by `timeoutMs` for the same reason —
+ * losing the tail of a flush beats never exiting.
+ */
+export function runShutdownSequence(
+  timeoutMs: number = SHUTDOWN_TIMEOUT_MS,
+): Promise<void> {
+  running ??= withDeadline(shutdown(), timeoutMs)
+  return running
+}
+
+/** Test seam — see `__setTestConfig`. Clears the once-per-process memo. */
+export function __resetShutdownSequence(): void {
+  running = null
+}
+
+async function step(what: string, fn: () => unknown): Promise<void> {
+  const [err] = await Try.catch(fn)
+  if (err) {
+    serveLog.UNHANDLED_ERR({ error: `Error in ${what}: ${errorMsg(err)}` })
+  }
+}
+
+async function withDeadline(
+  work: Promise<void>,
+  timeoutMs: number,
+): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const deadline = new Promise<'timeout'>(resolve => {
+    timer = setTimeout(() => resolve('timeout'), timeoutMs)
+  })
+
+  // `shutdown()` isolates every step, so it settles rather than rejects; the
+  // catch is belt-and-braces against a future step escaping `step()`.
+  const outcome = await Promise.race([
+    work.then(() => 'done' as const).catch(() => 'done' as const),
+    deadline,
+  ])
+  clearTimeout(timer)
+
+  if (outcome === 'timeout') {
+    log({
+      level: 'warn',
+      msg: `[Shutdown] Teardown did not finish within ${timeoutMs}ms; exiting anyway.`,
+    })
+  }
+}
+
+async function shutdown(): Promise<void> {
+  await step('config.onShutdown', () => Bakery.config.onShutdown())
+
+  for (const hook of Bakery.shutdownHooks) {
+    await step('shutdown hook', hook)
+  }
+
+  // Inside the step, not above it: an `await import()` that fails throws, and
+  // out here that rejection escaped the sequence entirely — taking the resource
+  // close below with it and, in `worker.ts`, the `process.exit(0)` that follows.
+  await step('plugin onShutdown', async () => {
+    const { PluginHooks } = await import('@bakery-framework/core/core/plugins')
+    await PluginHooks.onShutdown()
+  })
+
+  const teardown = testTeardown ?? defaultTeardown
+  await step('cache database close', () => teardown.closeCache())
+  await step('database close', () => teardown.closeDatabase())
+}

package/src/threads.ts

@@ -0,0 +1,253 @@
+import { errorMsg, log, serveLog } from '@bakery-framework/core/logger'
+import { Try } from '@bakery-framework/core/utils/common'
+
+/**
+ * How long the master waits for every worker to acknowledge its pre-terminate
+ * flush. Bounded on purpose: a wedged worker must delay shutdown, not prevent
+ * it.
+ */
+export const FLUSH_TIMEOUT_MS = 5000
+
+/**
+ * The part of `Worker` this module needs. Narrow enough that a test can supply
+ * a plain object, which is the only practical way to exercise the timeout — a
+ * real Worker that never acknowledges means spawning a real server.
+ */
+export interface FlushTarget {
+  postMessage(message: any): void
+  addEventListener(type: 'message', listener: (event: any) => void): void
+  removeEventListener(type: 'message', listener: (event: any) => void): void
+}
+
+/**
+ * Ask every worker to flush, and resolve when they all have — or when
+ * `timeoutMs` elapses, whichever comes first.
+ *
+ * `worker.terminate()` is immediate: a worker's shutdown hooks never run, so
+ * the tiered cache's session buffer only reached disk on its own 30s interval.
+ * A cluster shutdown could therefore drop up to a full interval of session
+ * writes. Resolves `true` when every worker acknowledged, `false` when the
+ * deadline won; the caller terminates either way.
+ */
+export function requestWorkerFlush(
+  targets: Iterable<FlushTarget>,
+  timeoutMs: number = FLUSH_TIMEOUT_MS,
+): Promise<boolean> {
+  const pending = [...targets]
+  if (!pending.length) return Promise.resolve(true)
+
+  return new Promise<boolean>(resolve => {
+    const listeners = new Map<FlushTarget, (event: any) => void>()
+    let remaining = pending.length
+    let settled = false
+
+    const finish = (flushed: boolean) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      for (const [target, listener] of listeners) {
+        Try(() => target.removeEventListener('message', listener))
+      }
+      listeners.clear()
+      // `resolve` is the enclosing Promise executor's, not a call that returns
+      // one; the rule cannot tell the two apart.
+      // biome-ignore lint/nursery/noFloatingPromises: executor resolve, not a promise
+      resolve(flushed)
+    }
+
+    const timer = setTimeout(() => finish(false), timeoutMs)
+
+    for (const target of pending) {
+      const listener = (event: any) => {
+        if (event?.data?.type !== 'SHUTDOWN_DONE') return
+        Try(() => target.removeEventListener('message', listener))
+        listeners.delete(target)
+        if (--remaining === 0) finish(true)
+      }
+
+      listeners.set(target, listener)
+      target.addEventListener('message', listener)
+    }
+
+    for (const target of pending) {
+      // A worker that already died throws here; that is one fewer acknowledgement
+      // and the deadline covers it.
+      Try(() => target.postMessage({ type: 'SHUTDOWN' }))
+    }
+  })
+}
+
+export const RESPAWN_BASE_DELAY_MS = 100
+export const RESPAWN_MAX_DELAY_MS = 30_000
+/** A worker that survives this long is healthy; its failure streak resets. */
+export const RESPAWN_RESET_AFTER_MS = 60_000
+
+/**
+ * How long the master waits before respawning a crashed worker: exponential
+ * backoff, `RESPAWN_BASE_DELAY_MS` doubling per consecutive failure up to
+ * `RESPAWN_MAX_DELAY_MS`. A fixed 100ms meant a worker that died during boot
+ * (bad DB URL, port conflict) re-ran initDB/setupServer ~10 times a second
+ * indefinitely. Pure — delay = f(consecutiveFailures); the caller owns the
+ * count and resets it after `RESPAWN_RESET_AFTER_MS` of survival.
+ */
+export function respawnDelayMs(consecutiveFailures: number): number {
+  const failures = Math.max(1, Math.floor(consecutiveFailures))
+  // Clamp the exponent before the pow, not the product after it: 2 ** 1024 is
+  // already Infinity, and Math.min(Infinity, cap) would mask that.
+  const exponent = Math.min(failures - 1, 31)
+  return Math.min(RESPAWN_BASE_DELAY_MS * 2 ** exponent, RESPAWN_MAX_DELAY_MS)
+}
+
+/** Friendlier names for the platforms the clamp message will actually show. */
+const PLATFORM_NAMES: Record<string, string> = {
+  win32: 'Windows',
+  darwin: 'macOS',
+}
+
+export async function handleThreadsMaster(threadCount: number) {
+  if (process.platform !== 'linux' && threadCount > 1) {
+    // Not just Windows: the multi-worker model needs kernel-level SO_REUSEPORT
+    // load balancing, which only Linux provides. On macOS N sockets either
+    // fail to bind or never receive balanced traffic — and a bind failure
+    // feeds the respawn loop below.
+    serveLog.CLUSTER_CLAMPED({
+      platform: PLATFORM_NAMES[process.platform] ?? process.platform,
+      requested: threadCount,
+    })
+    threadCount = 1
+  }
+
+  let Bakery: any
+  try {
+    const configMod = await import('@bakery-framework/core/core/config')
+    const bakeryMod = await import('@bakery-framework/core')
+    await configMod.initConfig()
+    Bakery = bakeryMod.Bakery
+  } catch (error: any) {
+    serveLog.UNHANDLED_ERR({
+      error: `Fatal error during master startup: ${errorMsg(error)}`,
+    })
+    process.exit(1)
+  }
+
+  if (threadCount === 1) {
+    // Covers both an explicit `--threads 1` and every non-Linux clamp above.
+    //
+    // THREAD_ID feeds the startup banner; the assignment lands because
+    // `core/init.ts` defines it as an accessor on `process.env` (while it was
+    // getter-only the assignment threw, and a Try() swallow hid it).
+    //
+    // THREAD_WORKER is deliberately NOT set. It is the flag that scales caches
+    // *down* for N-way memory sharing — HandlerCache 500→50, HandlerMap
+    // routeCache 5000→500, the tiered cache's memory tier ÷4, the SQLite page
+    // caches ~10x smaller — and a single worker that owns the whole process
+    // would get all of that for zero benefit. Setting it here made
+    // `--threads 1` strictly worse than plain `bun run serve`; leaving it
+    // unset makes this path identical to plain prod.
+    ;(process.env as any).THREAD_ID = '0'
+    await import('./prod')
+    await new Promise(() => {})
+    return
+  }
+
+  serveLog.STARTING_THREADS({ count: threadCount })
+
+  const workers = new Map<number, Worker>()
+  const workerState = new Map<
+    number,
+    { isTerminated: boolean; consecutiveFailures: number; spawnedAt: number }
+  >()
+
+  const spawnWorker = (id: number) => {
+    workerState.set(id, {
+      isTerminated: false,
+      // The streak survives the respawn — that is what makes it a streak.
+      consecutiveFailures: workerState.get(id)?.consecutiveFailures ?? 0,
+      spawnedAt: Date.now(),
+    })
+
+    const worker = new Worker(new URL('./worker.ts', import.meta.url).href, {
+      env: {
+        ...process.env,
+        THREAD_WORKER: '1',
+        THREAD_ID: String(id),
+      },
+    })
+
+    workers.set(id, worker)
+
+    worker.postMessage({
+      type: 'INIT_SHARED_POOL',
+      buffer: Bakery.sharedPool.buffer,
+    })
+
+    worker.addEventListener('error', err => {
+      serveLog.UNHANDLED_ERR({
+        error: `Worker ${id} error: ${err.message || String(err)}`,
+      })
+    })
+
+    worker.addEventListener('close', () => {
+      const state = workerState.get(id)
+      if (state?.isTerminated) return
+
+      // A worker that ran long enough to be called healthy starts a fresh
+      // streak; a boot-loop crash keeps doubling.
+      const survivedMs = Date.now() - (state?.spawnedAt ?? 0)
+      const failures =
+        survivedMs >= RESPAWN_RESET_AFTER_MS
+          ? 1
+          : (state?.consecutiveFailures ?? 0) + 1
+      if (state) state.consecutiveFailures = failures
+
+      const delay = respawnDelayMs(failures)
+      serveLog.WORKER_RESPAWN({ id, delay, failures })
+      workers.delete(id)
+      // No give-up ceiling on purpose: a supervisor that stops retrying turns
+      // a transient fault into a permanent outage, and choosing that trade-off
+      // needs an operator-facing decision (exit code, flag, alerting) this
+      // codebase has not made. The 30s cap keeps the retry loop cheap forever.
+      setTimeout(() => spawnWorker(id), delay)
+    })
+  }
+
+  for (let i = 0; i < threadCount; i++) {
+    spawnWorker(i)
+  }
+
+  async function handleShutdown(signal: string) {
+    log({ level: 'info', msg: `Received ${signal}, shutting down cluster...` })
+    serveLog.SHUTTING_DOWN()
+
+    // Mark first: a worker that exits while we wait for its flush is exiting
+    // because we asked it to, and must not be respawned by the close listener.
+    for (const id of workers.keys()) {
+      const state = workerState.get(id)
+      if (state) state.isTerminated = true
+    }
+
+    const flushed = await requestWorkerFlush(workers.values())
+    if (!flushed) {
+      log({
+        level: 'warn',
+        msg: `[Cluster] Some workers did not acknowledge the flush within ${FLUSH_TIMEOUT_MS}ms; terminating anyway.`,
+      })
+    }
+
+    for (const worker of workers.values()) {
+      worker.terminate()
+    }
+    workers.clear()
+
+    // No PluginHooks.onShutdown() here: plugins are set up per-worker, and each
+    // worker's runShutdownSequence (triggered by the SHUTDOWN flush above) runs
+    // it where the plugin state actually lives. The master never ran setup().
+
+    process.exit(0)
+  }
+
+  process.on('SIGINT', () => handleShutdown('SIGINT'))
+  process.on('SIGTERM', () => handleShutdown('SIGTERM'))
+
+  await new Promise(() => {})
+}

package/src/watcher.ts

@@ -0,0 +1,4 @@
+import '@bakery-framework/core/core/init'
+import { handleDevMaster } from '@bakery-framework/core/compiler'
+
+await handleDevMaster()

package/src/worker.ts

@@ -0,0 +1,278 @@
+import {
+  Bakery,
+  getHostname,
+  hostStore,
+} from '@bakery-framework/core/core/bakery'
+import {
+  initConfig,
+  resolveHostConfig,
+} from '@bakery-framework/core/core/config'
+import { isDevWorker } from '@bakery-framework/core/core/init'
+import { resolvePort } from '@bakery-framework/core/core/port'
+import type { Handler } from '@bakery-framework/core/handlers'
+import { errorMsg, log, serveLog } from '@bakery-framework/core/logger'
+import {
+  handleRequest,
+  handleRequestError,
+  processResponse,
+  serveWebSocket,
+} from '@bakery-framework/core/router'
+import { Session } from '@bakery-framework/core/session'
+import { runStartupBanner, setupServer } from '@bakery-framework/core/startup'
+import { deferredValue, is, Try } from '@bakery-framework/core/utils/common'
+import { getClientIp } from '@bakery-framework/core/utils/http'
+import { COUNTER_SLOTS } from '@bakery-framework/core/utils/shared-pool'
+import { hasORM } from './orm'
+import {
+  rateLimitSlot,
+  retryAfterSeconds,
+  sampleRateLimitLog,
+} from './rate-limit'
+import { runShutdownSequence } from './shutdown'
+
+/**
+ * How long a cluster worker holds `Bun.serve` waiting for the master's
+ * `INIT_SHARED_POOL` handover. Bounded because a master that never sends the
+ * pool must degrade the worker to its local pool, not deadlock it.
+ */
+const SHARED_POOL_WAIT_MS = 2000
+
+let signalSharedPoolBound: () => void = () => {}
+const sharedPoolBound = new Promise<void>(resolve => {
+  signalSharedPoolBound = resolve
+})
+
+if (typeof self !== 'undefined' && 'addEventListener' in self) {
+  self.addEventListener('message', (e: any) => {
+    if (e.data?.type === 'INIT_SHARED_POOL' && e.data.buffer) {
+      // Rebinds on every send on purpose — a late or repeated handover from
+      // the master must still land; resolving the promise twice is a no-op.
+      Bakery.sharedPool.bind(e.data.buffer)
+      signalSharedPoolBound()
+    }
+
+    if (e.data?.type === 'SHUTDOWN') {
+      // The cluster master asking for a flush before it calls terminate().
+      // Deliberately no process.exit() here: inside a Worker thread that would
+      // take the whole cluster down, master included. We flush, we acknowledge,
+      // and the master terminates us — or gives up waiting and does it anyway.
+      void (async () => {
+        Bakery.server?.stop(true)
+        await runShutdownSequence()
+        Try(() => (self as any).postMessage({ type: 'SHUTDOWN_DONE' }))
+      })()
+    }
+  })
+}
+
+try {
+  // Memoised no-op on the dev/prod entry paths, which already ran it (and
+  // exited there if it threw). A cluster worker is spawned straight into this
+  // file and passes through neither entry, so this is its first call — and in
+  // PROD a present-but-broken server.config.ts must fail the boot here rather
+  // than serve the built-in defaults.
+  await initConfig()
+} catch (error: any) {
+  serveLog.UNHANDLED_ERR({ error: `Config init failed: ${errorMsg(error)}` })
+  process.exit(1)
+}
+
+// Skipped entirely when the ORM is not installed — the app has no database and
+// asked for none. Note what is *inside* the guard rather than outside it: once
+// the ORM is present, a failure to initialise is still fatal, because at that
+// point the app does have a database and it does not work.
+if (hasORM()) {
+  try {
+    const { initDB } = await import('@bakery-framework/orm/connection')
+    await initDB()
+  } catch (error: any) {
+    serveLog.UNHANDLED_ERR({
+      error: `Database initialization failed: ${errorMsg(error)}`,
+    })
+    process.exit(1)
+  }
+}
+
+try {
+  await setupServer()
+} catch (error: any) {
+  serveLog.UNHANDLED_ERR({ error: `Server setup failed: ${errorMsg(error)}` })
+  process.exit(1)
+}
+
+if (import.meta.env.THREAD_WORKER) {
+  // The master posts INIT_SHARED_POOL immediately after constructing this
+  // Worker, but the message lands on a later event-loop turn than an immediate
+  // Bun.serve — early requests would hit a worker-local SharedMemoryPool whose
+  // counters and rate-limit state bind() then silently discards. So in
+  // thread-worker mode only, wait for the handover before serving. Plain
+  // prod/dev never set THREAD_WORKER and skip this entirely.
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const bound = await Promise.race([
+    sharedPoolBound.then(() => true),
+    new Promise<boolean>(resolve => {
+      timer = setTimeout(() => resolve(false), SHARED_POOL_WAIT_MS)
+    }),
+  ])
+  clearTimeout(timer)
+  if (!bound) {
+    serveLog.SHARED_POOL_TIMEOUT({ timeout: SHARED_POOL_WAIT_MS })
+  }
+}
+
+// Same resolver `startup.ts`'s banner and the dev master's URL use, so what we
+// bind and what they advertise cannot disagree. It throws on a malformed
+// `PORT` rather than handing `Bun.serve` a `NaN` it silently turns into a
+// random ephemeral port — which is how `PORT=3000x` used to produce a server
+// on 51570 under a banner reading `http://localhost:3000/`.
+let PORT: number
+try {
+  PORT = resolvePort(Bakery.config.port)
+} catch (error: any) {
+  serveLog.UNHANDLED_ERR({ error: errorMsg(error) })
+  process.exit(1)
+}
+
+try {
+  Bakery.server = Bun.serve({
+    port: PORT,
+    hostname: Bakery.config.host,
+    reusePort:
+      process.platform !== 'win32' && Boolean(import.meta.env.THREAD_WORKER),
+    maxRequestBodySize: Bakery.config.maxBodySize,
+
+    async fetch(req) {
+      // Parsed once here and attached: `new URL` measures ~1.7us and the
+      // router, body parser and proxy all want the same parse.
+      const url = new URL(req.url)
+      ;(req as any).__parsedUrl = url
+      const hostname = getHostname(req)
+      const hostConfig = resolveHostConfig(hostname)
+
+      return hostStore.run({ config: hostConfig, hostname }, async () => {
+        const path = url.pathname
+        req.startNs = Bun.nanoseconds()
+        req.__hostname = hostname
+        deferredValue(req, 'session', Session.from)
+
+        const rl = Bakery.config.rateLimit
+        if (rl) {
+          const key = (rl.keyBy ? rl.keyBy(req) : getClientIp(req)) || hostname
+          const slot = rateLimitSlot(key)
+          if (!Bakery.sharedPool.consumeToken(slot, rl.max, rl.refill)) {
+            // Sampled — availability under flood: stdout is effectively
+            // synchronous on Windows, so a line per rejection replays the
+            // flood the limiter just absorbed as a logging flood.
+            const suppressed = sampleRateLimitLog(key)
+            if (suppressed !== null) {
+              if (suppressed > 0) {
+                serveLog.RATE_LIMITED_SUPPRESSED({ ip: key, count: suppressed })
+              } else {
+                serveLog.RATE_LIMITED({ ip: key })
+              }
+            }
+            return new Response('Too Many Requests', {
+              status: 429,
+              headers: {
+                'Retry-After': String(retryAfterSeconds(rl.refill)),
+              },
+            })
+          }
+        }
+
+        Bakery.sharedPool.incrementCounter(COUNTER_SLOTS.TOTAL_REQUESTS, 1)
+
+        const resp: Handler.Response | symbol = await Try.return(
+          async function fetchHandler() {
+            const res = await handleRequest(req)
+
+            const isResError = res instanceof Response && res.status >= 400
+            const isObjError = is.object(res) && 'errorCode' in res
+
+            if (isResError || isObjError) {
+              Bakery.sharedPool.incrementCounter(COUNTER_SLOTS.TOTAL_ERRORS, 1)
+              return await handleRequestError(path, req, res)
+            }
+            return res
+          },
+
+          async function errorHandler(error) {
+            Bakery.sharedPool.incrementCounter(COUNTER_SLOTS.TOTAL_ERRORS, 1)
+            serveLog.UNHANDLED_ERR({ error: errorMsg(error) })
+            return await handleRequestError(path, req, error)
+          },
+        )
+
+        const elapsedMs = Math.round((Bun.nanoseconds() - req.startNs) / 1e6)
+        Bakery.sharedPool.incrementCounter(
+          COUNTER_SLOTS.LATENCY_SUM_MS,
+          elapsedMs,
+        )
+        return processResponse(resp, req)
+      })
+    },
+
+    websocket: serveWebSocket,
+
+    async error(error: Error, req?: Request): Promise<any> {
+      Bakery.sharedPool.incrementCounter(COUNTER_SLOTS.TOTAL_ERRORS, 1)
+      serveLog.UNHANDLED_ERR({ error: errorMsg(error) })
+      const hostname = req ? getHostname(req) : ''
+      const hostConfig = resolveHostConfig(hostname)
+      return hostStore.run({ config: hostConfig, hostname }, async () => {
+        return await handleRequestError('/', req, error)
+      })
+    },
+  })
+} catch (err: any) {
+  serveLog.UNHANDLED_ERR({ error: `Failed to start server: ${errorMsg(err)}` })
+  process.exit(1)
+}
+
+if (isDevWorker) {
+  // One `.catch` on the whole chain, not one nested inside the `.then`. The
+  // nested form covered `startCompileService` rejecting but left the dynamic
+  // `import()` itself unhandled — so a compiler module that failed to load
+  // produced an unhandled rejection rather than the WATCHER_ERR line that
+  // exists to report exactly that.
+  import('@bakery-framework/core/compiler')
+    .then(({ startCompileService }) => startCompileService(Bakery.server))
+    .catch(e => serveLog.WATCHER_ERR({ error: String(e) }))
+}
+
+try {
+  await runStartupBanner()
+} catch (e: any) {
+  serveLog.UNHANDLED_ERR({ error: `Startup banner failed: ${errorMsg(e)}` })
+}
+
+async function handleShutdown(signal: string) {
+  log({ level: 'info', msg: `Received ${signal}, shutting down...` })
+  serveLog.SHUTTING_DOWN()
+
+  Bakery.server?.stop(true)
+
+  // config.onShutdown, framework hooks, plugins, then resource close — see
+  // shutdown.ts for why that order. It used to run only the middle two, so an
+  // application's `onShutdown` was declared, defaulted to a no-op, and never
+  // called. The sequence carries its own deadline.
+  await runShutdownSequence()
+}
+
+/**
+ * `process.exit(0)` lives here, in a `finally`, because `handleShutdown` is
+ * async and the signal handler cannot await it: registered directly, its
+ * promise was neither awaited nor caught, so a rejection anywhere in teardown
+ * became an unhandled rejection *and* skipped the exit — the process kept
+ * running with its listener stopped, answering nothing.
+ */
+function onSignal(signal: string): void {
+  void handleShutdown(signal)
+    .catch(error => {
+      serveLog.UNHANDLED_ERR({ error: `Shutdown failed: ${errorMsg(error)}` })
+    })
+    .finally(() => process.exit(0))
+}
+
+process.on('SIGINT', () => onSignal('SIGINT'))
+process.on('SIGTERM', () => onSignal('SIGTERM'))