cabloy 5.1.206 → 5.1.208

package/.cabloy-version

@@ -1 +1 @@
-5.1.206
+5.1.208

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 5.1.208
+
+### Improvements
+
+- Update the README and quickstart documentation.
+- Update the changelog for version 5.1.207.
+
+## 5.1.207
+
+### Features
+
+- Add update functionality.
+
+### Bug Fixes
+
+- Fix database reset behavior.
+
+### Improvements
+
+- Enhance and refactor database reset functionality.
+
 ## 5.1.206
 
 ### Features

package/README.md

@@ -134,6 +134,7 @@ Use the root [package.json](https://github.com/cabloy/cabloy/blob/main/package.j
 
 ```bash
 npm run init
+npm run db:reset
 npm run dev
 npm run tsc
 npm run test

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.206",
+  "version": "5.1.208",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

package/repo-agent-governance/managed-assets.json

@@ -683,7 +683,7 @@
     {
       "adapter": "cursor",
       "category": "policy",
-      "sha256": "539fa24fc49fa8402ea0d9ab89c058762c441d5b3ed87af34a16235d1f8251a0",
+      "sha256": "e2784a08d355455da0da0cfb7c83ff1df4db69566012a1b4a33a5d591764f730",
       "source": "policies/repository.md",
       "target": ".cursor/rules/cabloy-governance.mdc"
     },
@@ -1005,14 +1005,14 @@
     {
       "adapter": "codex",
       "category": "policy",
-      "sha256": "f8172d4e80dc8b84bf99a0e926184eb78af5bd1fdfcdeebe63b02160f459afce",
+      "sha256": "d5f4d8fb331147baa92aa68d8579ac604d2a34bf872efc594393ff1e52e8cd79",
       "source": "policies/repository.md",
       "target": "AGENTS.md"
     },
     {
       "adapter": "claude",
       "category": "policy",
-      "sha256": "f8172d4e80dc8b84bf99a0e926184eb78af5bd1fdfcdeebe63b02160f459afce",
+      "sha256": "d5f4d8fb331147baa92aa68d8579ac604d2a34bf872efc594393ff1e52e8cd79",
       "source": "policies/repository.md",
       "target": "CLAUDE.md"
     }

package/repo-agent-governance/policies/repository.md

@@ -96,7 +96,7 @@ Before inventing a custom implementation path:
 - Do not set `TEST_CONCURRENCY=false` for normal `npm run test` or CI runs: an unset value defaults to concurrent execution. For stateful `node:test` suites, declare `{ concurrency: false }` explicitly. Prove business contention by explicitly launching competing operations and asserting their combined durable outcome, never through runner parallelism or scheduling.
 - Unit tests must not temporarily mutate process-global origin or proxy configuration, including `app.config.server.serve.protocol`, `app.config.server.serve.host`, and `app.proxy`. Model request-origin cases with an explicit `req` fixture, and use the established `AppUtil` loopback fallback for requestless local URLs. Do not introduce a broad origin lock to serialize such tests; retain narrowly scoped locks only for genuinely shared domain state.
 - Unit tests must delete every test-owned persisted resource in `finally`, using precise owned identities and reverse dependency order.
-- Shared durable test or local-development fixtures must be created through the owning module's `meta.version.ts` `seed()` hook and treated as read-only by tests; seeds run on isolated test-mode startup or after an explicit dev-mode `npm run db:reset` against a newly recreated disposable database, not on ordinary dev startup or repeatedly against one database.
+- Shared durable test or local-development fixtures must be created through the owning module's `meta.version.ts` `seed()` hook and treated as read-only by tests; seeds run on isolated test-mode startup or after an explicit dev-mode `npm run db:reset` against newly recreated disposable databases. In Cabloy Basic and Cabloy Start, `npm run dev` and `npm run dev:one` only reuse existing managed disposable databases; any missing required shared or static isolate target must fail promptly with an instruction to run `npm run db:reset`, without database creation, creation-time Redis cleanup, or seeding. Reset is explicitly destructive: one process clears validated application-owned Redis prefixes, drops/recreates managed databases, migrates, initializes, and seeds. Failures remain visible; investigate and explicitly rerun reset, with no preparation journal or automatic recovery. There is no file-based preparation lock; concurrent dev/dev or dev/reset against the same database and Redis namespace is unsupported. Do not run reset without explicit user approval; never seed repeatedly against one database.
 
 ## Verification expectations
 

package/repo-docs/backend/migration-and-changes.md

@@ -94,11 +94,11 @@ export class MetaVersion extends BeanBase {}
 
 Three migration scenarios are defined:
 
-| Scenario | Purpose                                             |
-| -------- | --------------------------------------------------- |
-| `update` | schema evolution such as tables and fields          |
-| `init`   | instance- or tenant-specific initialization data    |
-| `seed`   | baseline data for test runs and explicit dev resets |
+| Scenario | Purpose                                                      |
+| -------- | ------------------------------------------------------------ |
+| `update` | schema evolution such as tables and fields                   |
+| `init`   | instance- or tenant-specific initialization data             |
+| `seed`   | baseline data for test runs and newly prepared dev databases |
 
 This split is one of the most important Vona migration ideas because it separates:
 
@@ -110,7 +110,7 @@ A practical generated-thread interpretation is:
 
 - `update` follows schema and entity/model evolution
 - `init` follows instance-aware initialization needs introduced by the backend feature
-- `seed` provides shared baseline data during test-mode startup or an explicit development database reset
+- `seed` provides shared baseline data during test-mode startup or an explicit development database reset; ordinary dev startup never seeds (see the shared lifecycle below)
 
 ## Update: schema migration
 
@@ -153,7 +153,7 @@ export class MetaVersion extends BeanBase implements IMetaVersionInit {
 
 The important point is that initialization can run per instance or tenant, which keeps tenant data isolated.
 
-## Seed: test and reset baseline data
+## Seed: test and development baseline data
 
 Representative pattern:
 
@@ -171,7 +171,7 @@ export class MetaVersion extends BeanBase implements IMetaVersionSeed {
 
 This is valuable because shared baseline data becomes part of the structured version lifecycle instead of being scattered across unrelated setup code.
 
-Vona invokes `seed()` while the application starts in test mode (`npm run test` or managed E2E), and during an explicit `npm run db:reset` in dev mode. Ordinary development startup and framework upgrades do not seed or reset development data automatically. Use `seed()` for durable baseline fixtures shared by tests or for freshly prepared local development data. Both paths seed after instance initialization on a newly recreated disposable database; `seed()` is not a repeatable, same-database data-import mechanism.
+Vona invokes `seed()` while the application starts in test mode (`npm run test` or managed E2E), and during an explicit `npm run db:reset` in dev mode. In **Cabloy Basic and Cabloy Start**, ordinary `npm run dev` and `npm run dev:one` only reuse existing managed disposable databases and never seed; a missing required database makes startup fail with an instruction to run `npm run db:reset`. Framework upgrades do not reset existing development data or repeat its seeds. Use `seed()` for durable baseline fixtures shared by tests or for freshly prepared local development data. Seeding follows instance initialization on a newly created or recreated disposable database; `seed()` is not a repeatable, same-database data-import mechanism. See [Managed development database preparation](#managed-development-database-preparation) for the explicit reset lifecycle.
 
 Treat shared `seed()` records as read-only in ordinary tests. A scenario that needs different state must create independent, test-owned data and clean it up in `finally`; it must not mutate or delete the shared baseline. `seed()` remains distinct from `init()`: use `init()` for instance-aware initialization data and reserve `seed()` for baseline data in test runs or explicit development resets.
 
@@ -208,6 +208,25 @@ A practical decision rule is:
 - `db:reset` requires `database.testDatabase: true` in dev config and a connection outside the disposable database; it refuses to reset a configured non-disposable database
 - use `test` when you need **test-mode** verification of migration, controller behavior, and the broader generated contract thread; E2E also remains test-mode
 
+### Managed development database preparation
+
+**Cabloy Basic and Cabloy Start** share this explicit preparation lifecycle for framework-managed disposable development databases.
+
+When `database.testDatabase: true` enables framework-managed disposable dev databases, `npm run dev` and `npm run dev:one` only reuse existing databases:
+
+1. **Check every required target:** both shared and statically configured isolate database targets must exist. If any required target is missing, startup fails promptly with an instruction to run `npm run db:reset`; it does not create the target, perform creation-time Redis cleanup, or seed as a fallback.
+2. **Reuse existing databases:** keep their data without database creation, creation-time Redis cleanup, or module seeding. Ordinary startup is not a fixture refresh, an implicit reset, or recovery for a partial reset. Non-disposable databases are outside this managed reset path.
+
+An explicit `npm run db:reset` owns preparation in a single process. It requires `database.testDatabase: true` and a connection outside the disposable database. It clears validated application-owned Redis state with `clearAllData()`, drops and recreates the managed disposable dev databases, runs migrations and instance initialization, then invokes the owning modules' `seed()` hooks.
+
+**Stop the development server and any other processes using the same database and Redis namespace first.** There is no file-based preparation lock; concurrent dev/dev and dev/reset against the same database and Redis namespace are unsupported. The reset command disables its own listener, but that does not protect a concurrently running server or queue worker. Never reset development data you need to keep.
+
+If reset fails, the failure remains visible. There is no preparation journal or automatic recovery: investigate and resolve the cause, then explicitly rerun `npm run db:reset`. Database existence alone does not prove migrations, initialization, or seeding completed after an interruption. A subsequent dev startup must not be used to repair or complete the failed preparation.
+
+The Redis cleanup is prefix-scoped, not a Redis-wide flush: `clearAllData()` validates application-owned prefixes and deletes matching Bull queue, redlock, worker, and cache keys. It does not use `FLUSHDB` or `FLUSHALL`, delete unrelated namespaces, or clear broadcast subscriptions. Only explicit reset performs this destructive preparation cleanup; ordinary dev startup does not. Prefix scoping is not permission to clear a live shared namespace manually.
+
+See [Development database preparation](/reference/repo-scripts#development-database-preparation) for the root-command summary.
+
 ## Implementation checks for migration-sensitive changes
 
 When changing backend schema or module initialization behavior, do not only edit entities and models.

package/repo-docs/fullstack/quickstart.md

@@ -63,12 +63,22 @@ pnpm_config_minimum_release_age=0 npm create cabloy
 
 ## 3. Start Vona integrated SSR
 
-Run the root CLI command to start the Vona server:
+Before the first start, run the root command below to prepare the development databases and seed data:
+
+```bash
+npm run db:reset
+```
+
+`npm run db:reset` is destructive: it clears application-owned Redis prefixes and drops and recreates the managed development databases, then runs migrations, initialization, and seeds. Use it only when you intend to reset those resources. Do not run it while a development server is using the same databases and Redis namespace.
+
+Then start the Vona server:
 
 ```bash
 npm run dev
 ```
 
+For subsequent starts, run `npm run dev` directly. It reuses existing databases and does not create or seed missing databases; if a required database is missing, run `npm run db:reset` explicitly before starting again.
+
 In the Cabloy Basic default environment, Vona listens on `7102` and serves the following SSR sites:
 
 | SSR Site       | URL                                   |

package/repo-docs/reference/repo-scripts.md

@@ -67,7 +67,7 @@ Builds, generated artifacts, dependency installation/generation, and other share
 
 For Vona integrated SSR, the allocated E2E origin is supplied to Zova at runtime as server `SSR_API_BASE_URL` and browser `API_BASE_URL`. Do not edit Zova `.env` files or rebuild solely to match the test port. The current root `npm run test:e2e` consumes prebuilt frontend artifacts; refresh affected SSR/REST output and synchronize dependencies when their inputs change. See [Runtime API origins in Vona integrated SSR](/fullstack/ssr-entry-modes#runtime-api-origins-in-vona-integrated-ssr) for configuration overrides and scope.
 
-For a deliberate **dev-mode** database recreation, `npm run db:reset` is a separate, destructive command: it drops matching disposable development databases, reruns migrations and instance initialization, then runs module `seed()` hooks. It requires `database.testDatabase: true` in the dev configuration and a connection outside the disposable database. Ordinary `npm run dev` does not seed or reset; never run `db:reset` against development data you need to retain. Upgrades no longer initialize development test data automatically. See [Migration and Changes](/backend/migration-and-changes#local-development-workflow).
+For deliberate **dev-mode** database preparation, `npm run db:reset` is a separate, destructive command: in a single process, it clears validated application-owned Redis keys, drops and recreates managed disposable development databases, reruns migrations and instance initialization, then runs module `seed()` hooks. It requires `database.testDatabase: true` in the dev configuration and a connection outside the disposable database. Ordinary `npm run dev` and `npm run dev:one` only reuse existing managed databases; if any required target is missing, startup fails promptly with an instruction to run `npm run db:reset`. They do not create databases, perform creation-time Redis cleanup, or seed. Never run `db:reset` against development data you need to retain. Upgrades do not reset existing development data or repeat its seeds. See [Development database preparation](#development-database-preparation) and [Migration and Changes](/backend/migration-and-changes#local-development-workflow).
 
 ## Specification planning and derived charts
 
@@ -140,6 +140,25 @@ Cabloy Start exposes the equivalent Start repository surface:
 
 Cabloy Start does not expose Basic Commerce or root documentation wrappers.
 
+## Development database preparation
+
+**Cabloy Basic and Cabloy Start** share this explicit development-preparation lifecycle. Use the active repository's commands and configuration; sharing the lifecycle does not make the editions' flavors or frontend outputs interchangeable.
+
+With `database.testDatabase: true`, `npm run dev` and `npm run dev:one` only reuse existing framework-managed disposable development databases:
+
+- **All required databases exist:** startup reuses them without database creation, creation-time Redis cleanup, or module seeding. Ordinary startup is not a reset or a repeatable fixture-import path.
+- **Any required database is missing:** startup fails promptly with an instruction to run `npm run db:reset`. This check covers both shared and statically configured isolate database targets; the presence of the shared database alone is not sufficient. Startup does not create the missing target or clear Redis or seed as a fallback.
+
+`npm run db:reset` is the explicit, destructive preparation command. It requires `database.testDatabase: true` and a connection outside the disposable database. In a single process, it clears validated application-owned Redis state with `clearAllData()`, drops and recreates the managed disposable dev databases, then runs migrations, instance initialization, and module `seed()` hooks.
+
+**Stop the development server and any other processes using the same database and Redis namespace before running reset.** There is no file-based preparation lock: concurrent dev/dev and dev/reset processes against the same database and Redis namespace are unsupported. Disabling the reset command's own listener does not make reset safe alongside a live server or queue worker. Do not reset data you need to retain.
+
+Reset failures remain visible. There is no preparation journal or automatic recovery; investigate and resolve the failure, then explicitly rerun `npm run db:reset`. Do not use ordinary dev startup to repair or finish a partial reset.
+
+Here, `clearAllData()` deletes only keys in the validated application-owned Redis prefixes, covering Bull queue, redlock, worker, and cache keys. It does not use `FLUSHDB` or `FLUSHALL`, clear unrelated namespaces, or treat broadcast subscriptions as cleanup keys. Prefix scoping still makes reset destructive to the application's own Redis state; it is not permission to clean a shared live namespace manually.
+
+See [Managed development database preparation](/backend/migration-and-changes#managed-development-database-preparation) for the seed lifecycle and safety boundary.
+
 ## Upgrade
 
 Run `npm run upgrade:dry-run` before `npm run upgrade` to inspect framework files and root manifest entries that an upgrade would synchronize. The upgrader replaces the framework-owned `repo-agent-governance/` source, reconciles only its named package scripts, and uses ownership-aware adapter adoption. It preserves locally modified or legacy adapter outputs as conflicts for explicit review instead of blindly overwriting root Claude, Codex, or Cursor files.

package/scripts/init.ts

@@ -310,3 +310,18 @@ initRepoDocs();
 writeVersionMarker();
 // eslint-disable-next-line
 console.log('[init] Done!');
+// eslint-disable-next-line
+console.log(
+  [
+    '',
+    '=== Before your first development startup ===',
+    'Prepare the development database before running npm run dev:',
+    '',
+    '  npm run db:reset',
+    '',
+    'Warning: db:reset deletes managed development data and application-owned Redis state.',
+    'Stop processes using the same database and Redis namespace before running it.',
+    'If your development database is already prepared, skip reset to keep existing data.',
+    '',
+  ].join('\n'),
+);

package/vona/packages-cli/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli",
-  "version": "1.1.160",
+  "version": "1.1.161",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli",
   "keywords": [

package/vona/packages-cli/cli-set-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli-set-api",
-  "version": "1.1.158",
+  "version": "1.1.159",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli-set-api",
   "keywords": [

package/vona/packages-cli/cli-set-api/src/lib/bean/cli.bin.dev.ts

@@ -97,7 +97,8 @@ export class CliBinDev extends BeanCliBase {
 
   async _run(projectPath: string, _modulesMeta: Awaited<ReturnType<typeof glob>>) {
     let closed = false;
-    return new Promise((resolve, _reject) => {
+    let crashError: Error | undefined;
+    return new Promise((resolve, reject) => {
       (nodemon as any)({
         script: '.vona/bootstrap.ts',
         cwd: projectPath,
@@ -127,9 +128,23 @@ export class CliBinDev extends BeanCliBase {
         ],
       });
       nodemon
+        .on('crash', () => {
+          if (closed) return;
+          closed = true;
+          // nodemon emits crash without an error payload; the child already logged the cause.
+          crashError = new Error('Development server crashed; see the startup error above');
+          // Let nodemon finish processing the child exit before stopping its watchers.
+          setImmediate(() => nodemon.emit('quit'));
+        })
         .on('quit', () => {
           closed = true;
-          resolve(undefined);
+          if (crashError) {
+            // The programmatic quit event does not close watchers; reset before propagating
+            // the failure to the CLI's error handler, which exits the process immediately.
+            nodemon.reset(() => reject(crashError));
+          } else {
+            resolve(undefined);
+          }
         })
         .on('restart', files => {
           if (closed) {

package/vona/packages-cli/cli-set-api/test/binDevLifecycle.test.ts

@@ -0,0 +1,100 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { test } from 'node:test';
+
+const devUrl = new URL('../src/lib/bean/cli.bin.dev.ts', import.meta.url).href;
+const source = `
+  import assert from 'node:assert/strict';
+  import { EventEmitter } from 'node:events';
+  import { registerHooks } from 'node:module';
+  import { setImmediate as nextTurn } from 'node:timers/promises';
+  const devUrl = ${JSON.stringify(devUrl)};
+  const events = new EventEmitter();
+  let options;
+  let resetCount = 0;
+  let watchersActive = true;
+  const nodemon = globalThis.nodemonMock = opts => { options = opts; };
+  nodemon.reset = done => {
+    resetCount++;
+    watchersActive = false;
+    events.removeAllListeners();
+    done();
+  };
+  nodemon.on = (event, handler) => { events.on(event, handler); return nodemon; };
+  nodemon.emit = (event, ...args) => { events.emit(event, ...args); return nodemon; };
+  const mocks = {
+    '@cabloy/cli': 'export class BeanCliBase {}',
+    'nodemon': 'export default globalThis.nodemonMock;',
+    'rimraf': 'export function rimraf() { throw new Error("Unexpected cleanup"); }',
+    'vona-core': 'export function resolveVonaLocalPaths() { throw new Error("Unexpected app access"); }',
+    '../utils.ts': 'export function getImportEsm() { return "--import=./.vona/register.js"; }',
+    './toolsBin/generateVonaMeta.ts': 'export function generateVonaMeta() { throw new Error("Unexpected generation"); }',
+  };
+  registerHooks({
+    resolve(specifier, context, nextResolve) {
+      if (context.parentURL === devUrl && mocks[specifier]) {
+        return { url: 'data:text/javascript,' + encodeURIComponent(mocks[specifier]), shortCircuit: true };
+      }
+      return nextResolve(specifier, context);
+    },
+  });
+  const { CliBinDev } = await import(devUrl);
+  const cli = Object.create(CliBinDev.prototype);
+  let settled = false;
+  const result = cli._run('/mock-project', {});
+  result.then(() => { settled = true; }, () => {
+    assert.equal(watchersActive, false, 'close watchers before propagating failure');
+    settled = true;
+  });
+  assert.equal(options.cwd, '/mock-project');
+  assert.equal(options.script, '.vona/bootstrap.ts');
+  // Leave nodemon's default stdout/stderr forwarding intact, including the original failure log.
+  assert.equal(options.stdout, undefined);
+  assert.equal(options.stderr, undefined);
+  const scenario = process.argv[1];
+  let quits = 0;
+  events.on('quit', () => { quits++; });
+  if (scenario === 'crash') {
+    console.error('Database cabloy_dev is missing. Create the disposable database first.');
+    nodemon.emit('crash'); // nodemon provides no crash payload
+    // Duplicate crashes must not request duplicate shutdowns.
+    nodemon.emit('crash');
+    await assert.rejects(result, /Development server crashed; see the startup error above/);
+    await nextTurn();
+    assert.equal(quits, 1);
+    assert.equal(settled, true);
+    assert.equal(resetCount, 1);
+    assert.equal(watchersActive, false);
+  } else {
+    nodemon.emit('start');
+    nodemon.emit('restart', ['src/example.ts']);
+    nodemon.emit('exit');
+    await nextTurn();
+    assert.equal(settled, false, 'ordinary restart/clean exit must keep supervision running');
+    assert.equal(quits, 0);
+    assert.equal(resetCount, 0);
+    assert.equal(watchersActive, true);
+    nodemon.emit('quit');
+    assert.equal(await result, undefined);
+    assert.equal(quits, 1);
+  }
+  console.log('verified');
+`;
+
+for (const scenario of ['crash', 'restart-and-quit']) {
+  test(`dev nodemon lifecycle: ${scenario}`, () => {
+    const result = spawnSync(
+      process.execPath,
+      ['--input-type=module', '--eval', source, scenario],
+      {
+        encoding: 'utf8',
+        timeout: 3_000,
+      },
+    );
+    assert.ifError(result.error);
+    assert.equal(result.signal, null, result.stderr);
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(result.stdout, /verified/);
+    if (scenario === 'crash') assert.match(result.stderr, /Database cabloy_dev is missing/);
+  });
+}

package/vona/packages-vona/vona/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona",
-  "version": "5.1.105",
+  "version": "5.1.106",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "Vona is an intuitive, elegant and powerful Node.js framework for rapidly developing enterprise applications of any size",
   "keywords": [

package/vona/packages-vona/vona-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-core",
-  "version": "5.1.44",
+  "version": "5.1.45",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona",
   "keywords": [

package/vona/packages-vona/vona-core/src/lib/framework/cluster.ts

@@ -8,8 +8,8 @@ import { handleProcessWork } from './processWorker.ts';
 
 export async function startCluster(workers: number, bootstrapOptions: BootstrapOptions) {
   if (cluster.isPrimary) {
+    await createAppMaster(bootstrapOptions);
     handleProcessMaster(workers);
-    createAppMaster(bootstrapOptions);
   } else {
     await startWorker(bootstrapOptions);
   }

package/vona/packages-vona/vona-core/src/lib/framework/processMaster.test.ts

@@ -0,0 +1,185 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { test } from 'node:test';
+
+const masterUrl = new URL('./processMaster.ts', import.meta.url).href;
+const clusterUrl = new URL('./cluster.ts', import.meta.url).href;
+
+// Import only the real master handler into a subprocess. Cluster workers and useApp are mocks;
+// process.exit and the shutdown timeout remain real, without loading an app or opening listeners.
+const masterSource = `
+  import assert from 'node:assert/strict';
+  import { EventEmitter } from 'node:events';
+  import { registerHooks } from 'node:module';
+  const masterUrl = ${JSON.stringify(masterUrl)};
+  const cluster = globalThis.clusterMock = new EventEmitter();
+  cluster.workers = {};
+  let forks = 0;
+  const kills = [];
+  const exited = [];
+  function exit(worker, code, signal = null) {
+    delete cluster.workers[worker.id];
+    exited.push({ id: worker.id, code, signal });
+    cluster.emit('exit', worker, code, signal);
+  }
+  cluster.fork = () => {
+    assert.equal(cluster.listenerCount('message'), 1, 'message handler must precede fork');
+    assert.equal(cluster.listenerCount('exit'), 1, 'exit handler must precede fork');
+    assert.ok(process.listenerCount('SIGINT'));
+    assert.ok(process.listenerCount('SIGUSR2'));
+    const worker = { id: ++forks, process: { kill(signal) {
+      kills.push({ id: worker.id, signal });
+      // Synchronous exit also proves reload intent is recorded before kill.
+      exit(worker, globalThis.reloadFailure ? 1 : null, globalThis.reloadFailure ? null : signal);
+    } } };
+    cluster.workers[worker.id] = worker;
+    return worker;
+  };
+  registerHooks({
+    resolve(specifier, context, nextResolve) {
+      if (context.parentURL === masterUrl) {
+        const source = {
+          'node:cluster': 'export default globalThis.clusterMock;',
+          'chalk': 'export default { cyan: message => message };',
+          './useApp.ts': 'export function useApp() { return { meta: { env: { LOGGER_DUMMY: "true" } } }; }',
+        }[specifier];
+        if (source) return { url: 'data:text/javascript,' + encodeURIComponent(source), shortCircuit: true };
+      }
+      return nextResolve(specifier, context);
+    },
+  });
+  process.on('exit', code => console.log(JSON.stringify({ code, forks, kills, exited })));
+  const { handleProcessMaster } = await import(masterUrl);
+  handleProcessMaster(2);
+  const [first, second] = Object.values(cluster.workers);
+  const scenario = process.argv[1];
+  switch (scenario) {
+    case 'all-clean':
+      exit(first, 0);
+      assert.equal(Object.keys(cluster.workers).length, 1);
+      exit(second, 0);
+      break;
+    case 'failure-then-clean':
+      exit(first, 7);
+      assert.equal(Object.keys(cluster.workers).length, 1);
+      exit(second, 0);
+      break;
+    case 'unexpected-signal':
+      exit(first, null, 'SIGTERM');
+      exit(second, 0);
+      break;
+    case 'shutdown-SIGINT':
+    case 'shutdown-SIGUSR2': {
+      const signal = scenario.slice('shutdown-'.length);
+      process.emit(signal);
+      exit(first, null, signal);
+      exit(second, 0);
+      break;
+    }
+    case 'reload':
+    case 'reload-failure': {
+      globalThis.reloadFailure = scenario === 'reload-failure';
+      cluster.emit('message', first, 'reload-worker');
+      assert.equal(forks, 3);
+      const replacement = cluster.workers[3];
+      assert.ok(replacement);
+      exit(second, 0);
+      exit(replacement, 0);
+      break;
+    }
+    case 'reload-during-shutdown':
+      process.emit('SIGUSR2');
+      cluster.emit('message', first, 'reload-worker');
+      assert.equal(forks, 2, 'shutdown must not create a replacement');
+      exit(second, 0);
+      break;
+    case 'failure-then-shutdown':
+      exit(first, 1);
+      process.emit('SIGINT');
+      exit(second, null, 'SIGINT');
+      break;
+    case 'failure-during-shutdown':
+      process.emit('SIGINT');
+      exit(first, 1);
+      exit(second, 0);
+      break;
+    case 'unexpected-signal-during-shutdown':
+      process.emit('SIGINT');
+      exit(first, null, 'SIGKILL');
+      exit(second, 0);
+      break;
+    default:
+      throw new Error('Unknown scenario: ' + scenario);
+  }
+  throw new Error('Final worker exit must terminate the master');
+`;
+
+test('cluster creates the master app before installing handlers and forking workers', () => {
+  const source = `
+    import assert from 'node:assert/strict';
+    import { registerHooks } from 'node:module';
+    const clusterUrl = ${JSON.stringify(clusterUrl)};
+    const calls = globalThis.calls = [];
+    const mocks = {
+      'node:cluster': 'export default { isPrimary: true };',
+      './createApp.ts': 'export async function createAppMaster(options) { globalThis.calls.push("create"); await Promise.resolve(); globalThis.masterOptions = options; } export function createApp() { throw new Error("Unexpected worker"); }',
+      './processMaster.ts': 'export function handleProcessMaster(workers) { if (!globalThis.masterOptions) throw new Error("Master app not ready"); globalThis.calls.push(["handle", workers]); }',
+      './processWorker.ts': 'export function handleProcessWork() { throw new Error("Unexpected worker"); }',
+    };
+    registerHooks({
+      resolve(specifier, context, nextResolve) {
+        if (context.parentURL === clusterUrl && mocks[specifier]) {
+          return { url: 'data:text/javascript,' + encodeURIComponent(mocks[specifier]), shortCircuit: true };
+        }
+        return nextResolve(specifier, context);
+      },
+    });
+    const { startCluster } = await import(clusterUrl);
+    const options = {};
+    await startCluster(2, options);
+    assert.equal(globalThis.masterOptions, options);
+    assert.deepEqual(calls, ['create', ['handle', 2]]);
+  `;
+  const result = spawnSync(process.execPath, ['--input-type=module', '--eval', source], {
+    encoding: 'utf8',
+    timeout: 3_000,
+  });
+  assert.ifError(result.error);
+  assert.equal(result.signal, null, result.stderr);
+  assert.equal(result.status, 0, result.stderr);
+});
+
+const scenarios = [
+  { name: 'all-clean', code: 0 },
+  { name: 'failure-then-clean', code: 1 },
+  { name: 'unexpected-signal', code: 1 },
+  { name: 'shutdown-SIGINT', code: 0 },
+  { name: 'shutdown-SIGUSR2', code: 0 },
+  { name: 'reload', code: 0, reload: true },
+  { name: 'reload-failure', code: 1, reload: true },
+  { name: 'reload-during-shutdown', code: 0 },
+  { name: 'failure-then-shutdown', code: 1 },
+  { name: 'failure-during-shutdown', code: 1 },
+  { name: 'unexpected-signal-during-shutdown', code: 1 },
+];
+
+for (const scenario of scenarios) {
+  test(`process master: ${scenario.name}`, () => {
+    const result = spawnSync(
+      process.execPath,
+      ['--input-type=module', '--eval', masterSource, scenario.name],
+      { encoding: 'utf8', timeout: 3_000 },
+    );
+    assert.ifError(result.error);
+    assert.equal(result.signal, null, result.stderr);
+    assert.equal(result.status, scenario.code, result.stderr);
+    const summary = JSON.parse(result.stdout);
+    assert.equal(summary.code, scenario.code);
+    assert.equal(summary.forks, scenario.reload ? 3 : 2);
+    assert.equal(summary.exited.length, summary.forks);
+    assert.deepEqual(
+      summary.kills,
+      scenario.name.startsWith('reload') ? [{ id: 1, signal: 'SIGTERM' }] : [],
+    );
+  });
+}