@dimina-kit/devkit 0.1.2-dev.20260703051110 → 0.1.2-dev.20260706064107

package/dist/compile-worker.d.ts

@@ -1,3 +1,23 @@
+/**
+ * Parent-side orchestration of the forked compile worker.
+ *
+ * One long-lived worker per `openProject` session: the first compile and
+ * every watcher rebuild are `{ cmd: 'build' }` IPC messages to the SAME
+ * child, so the compiler's module/worker caches stay warm. The parent never
+ * calls `process.chdir` — the worker chdirs in its own process (the root
+ * motive of this architecture).
+ *
+ * Crash handling: an unexpected worker death ('exit', 'close' or a lone
+ * 'error' event — Node does NOT guarantee an 'exit' after 'error') rejects
+ * the in-flight build (so the rebuild scheduler settles instead of hanging)
+ * and the NEXT build lazily re-forks a fresh worker. The death handler is
+ * idempotent and generation-guarded: a dead child's late 'exit' can never
+ * settle a build that belongs to a fresh worker. `close()` kills, rejects
+ * the in-flight build itself, and resolves on the child's first death event
+ * ('exit'/'close', or a lone 'error') — it never re-forks
+ * (refill-on-graceful-close would wedge process teardown).
+ */
+import { type ChildProcess } from 'node:child_process';
 import type { WorkerAppInfo, WorkerBuildOptions } from './compile-worker-entry.js';
 export interface CompileLogEntry {
     stream: 'stdout' | 'stderr';
@@ -6,6 +26,16 @@ export interface CompileLogEntry {
 export interface CompileWorkerOptions {
     /** Filtered dmcc log lines (already through `filterDmccLogLine`). */
     onLog?: (entry: CompileLogEntry) => void;
+    /**
+     * An already-forked compile-worker-entry process to reuse for the first
+     * build (a warm-standby hand-off) instead of paying a fresh fork + compiler
+     * import. Must be an IPC fork with piped stdio — the same shape spawnWorker
+     * produces. Pure accelerator: an adoptee that is already dead (or dies
+     * before the first build) is simply skipped and the next build forks fresh.
+     * Once adopted, the process is owned by this worker exactly like a
+     * self-forked one — close() kills it, its death rejects in-flight builds.
+     */
+    adopt?: ChildProcess;
 }
 export interface BuildRequest {
     projectPath: string;
@@ -29,5 +59,28 @@ export interface CompileWorker {
      */
     close: () => Promise<void>;
 }
+/**
+ * Resolve the fork target. In the published build this is the compiled
+ * `dist/compile-worker-entry.js` sibling; under vitest/dev the module runs
+ * from `src/`, where only the `.ts` source exists — the entry is a
+ * zero-dependency, erasable-syntax-only shell by design, so Node can run it
+ * with type stripping (default since 22.18; behind `--experimental-strip-types`
+ * on 22.6–22.17, which `workerExecArgv` passes for a `.ts` entry).
+ *
+ * Exported (with `workerExecArgv`) as the single authority on the fork shape:
+ * the warm-standby manager forks the SAME entry with the SAME execArgv, so a
+ * spare is indistinguishable from a worker this module forks itself.
+ */
+export declare function resolveWorkerEntry(): string;
+/**
+ * execArgv for the fork. A compiled `.js` entry (the published build, engines
+ * `node >=20`) needs nothing. A `.ts` entry (vitest/dev only) needs Node type
+ * stripping: `--experimental-strip-types` exists since 22.6 — on older Node
+ * the child would die at startup with an opaque ERR_UNKNOWN_FILE_EXTENSION /
+ * bad-option crash, so fail HERE with an actionable message instead. The
+ * ExperimentalWarning is silenced because the child's stderr is the dmcc log
+ * transport. On ≥22.18 (stripping on by default) the flag is still accepted.
+ */
+export declare function workerExecArgv(entry: string): string[];
 export declare function createCompileWorker(opts?: CompileWorkerOptions): CompileWorker;
 //# sourceMappingURL=compile-worker.d.ts.map

package/dist/compile-worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compile-worker.d.ts","sourceRoot":"","sources":["../src/compile-worker.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAuB,MAAM,2BAA2B,CAAA;AAIvG,MAAM,WAAW,eAAe;IAC/B,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC3B,IAAI,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,oBAAoB;IACpC,qEAAqE;IACrE,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAA;CACxC;AAED,MAAM,WAAW,YAAY;IAC5B,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,kBAAkB,CAAA;CAC3B;AAED,MAAM,WAAW,aAAa;IAC7B;;;;;OAKG;IACH,KAAK,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAA;IAC3D;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAsCD,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,oBAAyB,GAAG,aAAa,CA6KlF"}
+{"version":3,"file":"compile-worker.d.ts","sourceRoot":"","sources":["../src/compile-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAQ,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAM5D,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAuB,MAAM,2BAA2B,CAAA;AAIvG,MAAM,WAAW,eAAe;IAC/B,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC3B,IAAI,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,oBAAoB;IACpC,qEAAqE;IACrE,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,YAAY,CAAA;CACpB;AAED,MAAM,WAAW,YAAY;IAC5B,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,kBAAkB,CAAA;CAC3B;AAED,MAAM,WAAW,aAAa;IAC7B;;;;;OAKG;IACH,KAAK,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAA;IAC3D;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAI3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAWtD;AAED,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,oBAAyB,GAAG,aAAa,CA8LlF"}

package/dist/compile-worker.js

@@ -30,8 +30,12 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
  * zero-dependency, erasable-syntax-only shell by design, so Node can run it
  * with type stripping (default since 22.18; behind `--experimental-strip-types`
  * on 22.6–22.17, which `workerExecArgv` passes for a `.ts` entry).
+ *
+ * Exported (with `workerExecArgv`) as the single authority on the fork shape:
+ * the warm-standby manager forks the SAME entry with the SAME execArgv, so a
+ * spare is indistinguishable from a worker this module forks itself.
  */
-function resolveWorkerEntry() {
+export function resolveWorkerEntry() {
     const js = path.join(__dirname, 'compile-worker-entry.js');
     if (fs.existsSync(js))
         return js;
@@ -46,7 +50,7 @@ function resolveWorkerEntry() {
  * ExperimentalWarning is silenced because the child's stderr is the dmcc log
  * transport. On ≥22.18 (stripping on by default) the flag is still accepted.
  */
-function workerExecArgv(entry) {
+export function workerExecArgv(entry) {
     if (!entry.endsWith('.ts'))
         return [];
     const [major = 0, minor = 0] = process.versions.node.split('.').map(Number);
@@ -112,15 +116,10 @@ export function createCompileWorker(opts = {}) {
         stream.on('end', flush);
         stream.on('close', flush);
     }
-    function spawnWorker() {
-        const entry = resolveWorkerEntry();
-        const worker = fork(entry, [], {
-            // Pipe stdout/stderr back to the parent — the dmcc log transport.
-            silent: true,
-            // Explicit execArgv, NOT the parent's (vitest/electron loaders would
-            // leak into a plain Node child).
-            execArgv: workerExecArgv(entry),
-        });
+    // Attach the log pipes, result routing and death handling to a worker
+    // process — the SAME wiring whether the process was self-forked or adopted
+    // from a warm standby (an inline copy for one of the two would drift).
+    function wireWorker(worker) {
         attachLineReader(worker.stdout, 'stdout');
         attachLineReader(worker.stderr, 'stderr');
         // Shared, idempotent death handler for 'exit' / 'close' / 'error': the
@@ -177,6 +176,26 @@ export function createCompileWorker(opts = {}) {
         worker.on('error', (err) => settleDeath(`compile worker errored: ${err.message}`));
         return worker;
     }
+    function spawnWorker() {
+        const entry = resolveWorkerEntry();
+        return wireWorker(fork(entry, [], {
+            // Pipe stdout/stderr back to the parent — the dmcc log transport.
+            silent: true,
+            // Explicit execArgv, NOT the parent's (vitest/electron loaders would
+            // leak into a plain Node child).
+            execArgv: workerExecArgv(entry),
+        }));
+    }
+    // Adopt the warm-standby hand-off, if any, at creation time — wiring
+    // immediately (not at the first build) so a spare that dies in the gap is
+    // handled by the normal death path (child cleared → next build re-forks)
+    // instead of being discovered as a broken pipe mid-build. An adoptee that
+    // is ALREADY dead is skipped outright: its death events fired before any
+    // listener could attach, so wiring it would leave a permanently wedged
+    // child slot.
+    if (opts.adopt && opts.adopt.exitCode === null && opts.adopt.signalCode === null && opts.adopt.connected) {
+        child = wireWorker(opts.adopt);
+    }
     function runBuild(req) {
         if (closed) {
             return Promise.reject(new Error('compile worker is closed'));

package/dist/index.d.ts

@@ -1,9 +1,21 @@
 import type { CompileLogEntry } from './compile-worker.js';
+import type { CompileWorkerStandby, CompileWorkerStandbyOptions } from './compile-worker-standby.js';
 export { createRebuildScheduler } from './rebuild-scheduler.js';
 export type { RebuildScheduler } from './rebuild-scheduler.js';
 export { filterDmccLogLine } from './compile-log.js';
 export { createCompileWorker } from './compile-worker.js';
 export type { CompileLogEntry, CompileWorker } from './compile-worker.js';
+export { createCompileWorkerStandby } from './compile-worker-standby.js';
+export type { CompileWorkerStandby, CompileWorkerStandbyOptions, StandbyEvent, StandbyState, } from './compile-worker-standby.js';
+/**
+ * Turn on the warm-standby accelerator and start warming the first spare
+ * immediately. Idempotent while the returned manager is live — repeat calls
+ * return the SAME manager (their opts are ignored). After `dispose()` (host
+ * shutdown, or a test tearing down) a new call builds a fresh manager. The
+ * caller owns disposal; a disposed manager makes every openProject fall back
+ * to cold forks and never spawns again.
+ */
+export declare function enableCompileWorkerStandby(opts?: CompileWorkerStandbyOptions): CompileWorkerStandby;
 export interface AppInfo {
     appId: string;
     name: string;
@@ -41,6 +53,14 @@ export interface OpenProjectOptions {
      * worker's piped stdout/stderr, tagged with their source stream.
      */
     onLog?: (entry: CompileLogEntry) => void;
+    /**
+     * Fired when the file watcher emits `'error'` (EMFILE, permission loss, …)
+     * AFTER its initial scan already resolved `ready` — i.e. the session is
+     * live and auto-rebuild-on-save has silently stopped working. A pre-ready
+     * error instead rejects `openProject` itself (see `createProjectWatcher`),
+     * so this only ever fires once per session, at most.
+     */
+    onWatcherError?: (err: unknown) => void;
 }
 export declare function openProject(opts: OpenProjectOptions): Promise<ProjectSession>;
 /**
@@ -49,7 +69,7 @@ export declare function openProject(opts: OpenProjectOptions): Promise<ProjectSe
  * watcher and whose `ready` resolves once the initial scan is complete (only
  * changes made after that point are guaranteed to surface).
  */
-export declare function createProjectWatcher(projectPath: string, onChange: () => void | Promise<void>): {
+export declare function createProjectWatcher(projectPath: string, onChange: () => void | Promise<void>, onWatcherError?: (err: unknown) => void): {
     close: () => Promise<void>;
     ready: Promise<void>;
 };

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAgB,eAAe,EAAiB,MAAM,qBAAqB,CAAA;AAEvF,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAC/D,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACzD,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAyCzE,MAAM,WAAW,OAAO;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAED,MAAM,WAAW,kBAAkB;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oFAAoF;IACpF,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,IAAI,CAAA;IACtB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAA;IACrC;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAA;CACxC;AAuFD,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAqInF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CACnC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAClC;IAAE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CA+CtD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAgB,eAAe,EAAiB,MAAM,qBAAqB,CAAA;AAEvF,OAAO,KAAK,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAA;AAEpG,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAC/D,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACzD,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACzE,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAA;AACxE,YAAY,EACX,oBAAoB,EACpB,2BAA2B,EAC3B,YAAY,EACZ,YAAY,GACZ,MAAM,6BAA6B,CAAA;AAYpC;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACzC,IAAI,CAAC,EAAE,2BAA2B,GAChC,oBAAoB,CAKtB;AAqDD,MAAM,WAAW,OAAO;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAED,MAAM,WAAW,kBAAkB;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oFAAoF;IACpF,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,IAAI,CAAA;IACtB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAA;IACrC;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAA;CACvC;AAuFD,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAoJnF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CACnC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EACpC,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GACrC;IAAE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CA2DtD"}

package/dist/index.js

@@ -8,9 +8,46 @@ import { createRequire } from 'node:module';
 import chokidar from 'chokidar';
 import { createRebuildScheduler } from './rebuild-scheduler.js';
 import { createCompileWorker } from './compile-worker.js';
+import { createCompileWorkerStandby } from './compile-worker-standby.js';
 export { createRebuildScheduler } from './rebuild-scheduler.js';
 export { filterDmccLogLine } from './compile-log.js';
 export { createCompileWorker } from './compile-worker.js';
+export { createCompileWorkerStandby } from './compile-worker-standby.js';
+// ── warm standby (opt-in) ──────────────────────────────────────────────────
+//
+// One module-level spare compile worker shared by every `openProject` in this
+// process. While no project is open the spare sits forked + prewarmed
+// (project-agnostic — it never chdirs, see compile-worker-entry); openProject
+// adopts it for the first compile and each session close refills it. Purely
+// additive: hosts that never call `enableCompileWorkerStandby` get exactly the
+// cold-fork behavior they had before.
+let standbyManager = null;
+/**
+ * Turn on the warm-standby accelerator and start warming the first spare
+ * immediately. Idempotent while the returned manager is live — repeat calls
+ * return the SAME manager (their opts are ignored). After `dispose()` (host
+ * shutdown, or a test tearing down) a new call builds a fresh manager. The
+ * caller owns disposal; a disposed manager makes every openProject fall back
+ * to cold forks and never spawns again.
+ */
+export function enableCompileWorkerStandby(opts) {
+    if (standbyManager && standbyManager.state !== 'disposed')
+        return standbyManager;
+    standbyManager = createCompileWorkerStandby(opts);
+    standbyManager.ensure();
+    return standbyManager;
+}
+/**
+ * Refill the spare after a compile worker has been consumed and fully closed.
+ * Fire-and-forget BY DESIGN: the fork happens asynchronously inside the
+ * manager, so a session close never waits on (and can never be wedged by)
+ * standby work — the refill-on-graceful-close deadlock class stays
+ * structurally impossible. No-ops when the standby is off, already warming,
+ * or disposed.
+ */
+function refillStandby() {
+    standbyManager?.ensure();
+}
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
 // esbuild's native binary is shipped inside node_modules, but when packaged
@@ -114,7 +151,7 @@ async function cleanupFailedOpen(watcher, compileWorker, server) {
     }
 }
 export async function openProject(opts) {
-    const { projectPath: rawProjectPath, port = 0, sourcemap = false, fileTypes, simulatorDir, containerDir: overrideContainerDir, outputDir, watch = true, onRebuild, onBuildError, onLog, } = opts;
+    const { projectPath: rawProjectPath, port = 0, sourcemap = false, fileTypes, simulatorDir, containerDir: overrideContainerDir, outputDir, watch = true, onRebuild, onBuildError, onLog, onWatcherError, } = opts;
     const projectPath = path.resolve(rawProjectPath);
     const buildOptions = { sourcemap, fileTypes };
     const resolvedPort = port === 0 ? await getRandomPort() : port;
@@ -125,8 +162,12 @@ export async function openProject(opts) {
     // Compilation runs in a long-lived forked worker — the worker chdirs in
     // its OWN process, so this (host) process never mutates its cwd, and dmcc
     // terminal output arrives on the worker's piped streams (delivered to
-    // `onLog` line-by-line after `filterDmccLogLine`).
-    const compileWorker = createCompileWorker({ onLog });
+    // `onLog` line-by-line after `filterDmccLogLine`). When the warm standby is
+    // enabled and holds a healthy spare, adopt it: the first compile then runs
+    // on an already-forked, toolchain-warm process. adopt() degrades to null on
+    // every failure path, which lands in the normal cold-fork behavior.
+    const adopted = standbyManager ? await standbyManager.adopt() : null;
+    const compileWorker = createCompileWorker({ onLog, ...(adopted ? { adopt: adopted } : {}) });
     const buildRequest = {
         projectPath,
         outputDir: resolvedOutputDir,
@@ -138,6 +179,9 @@ export async function openProject(opts) {
     }
     catch (err) {
         await compileWorker.close();
+        // A failed open consumed the spare too — refill (fire-and-forget) so the
+        // NEXT open attempt still starts warm.
+        refillStandby();
         throw err;
     }
     // When the compiler is racing (e.g. opening a project that was just
@@ -194,7 +238,9 @@ export async function openProject(opts) {
         // a build is in flight is never dropped: it coalesces into exactly one
         // trailing rebuild once the current run settles.
         const rebuildScheduler = createRebuildScheduler(() => runRebuild(compileWorker, buildRequest, sessionApps, () => reload, onRebuild, onBuildError));
-        watcher = watch ? createProjectWatcher(projectPath, () => rebuildScheduler.schedule()) : null;
+        watcher = watch
+            ? createProjectWatcher(projectPath, () => rebuildScheduler.schedule(), onWatcherError)
+            : null;
         // Don't resolve until the watcher's initial scan is done: a save landing
         // in the gap between `openProject` resolving and chokidar going live
         // (fsevents stream not yet active on macOS) would otherwise be silently
@@ -205,6 +251,7 @@ export async function openProject(opts) {
     }
     catch (err) {
         await cleanupFailedOpen(watcher, compileWorker, server);
+        refillStandby();
         throw err;
     }
     // `server` is always assigned when the try block completes without throwing
@@ -218,9 +265,13 @@ export async function openProject(opts) {
         close: async () => {
             await watcher?.close();
             // Kill the long-lived compile worker and WAIT for the child to be
-            // actually dead — only kill, never re-fork on a graceful close (a
-            // refill here would wedge process teardown).
+            // actually dead — THIS worker is never re-forked on a graceful close
+            // (an awaited refill here would wedge process teardown).
             await compileWorker.close();
+            // The standby refill is different: fire-and-forget into the manager
+            // (nothing here waits on it), sequenced after the old worker's death
+            // so spare + dying worker never hold memory simultaneously.
+            refillStandby();
             liveServer.closeAllConnections?.();
             await new Promise(resolve => liveServer.close(() => resolve()));
         },
@@ -232,7 +283,7 @@ export async function openProject(opts) {
  * watcher and whose `ready` resolves once the initial scan is complete (only
  * changes made after that point are guaranteed to surface).
  */
-export function createProjectWatcher(projectPath, onChange) {
+export function createProjectWatcher(projectPath, onChange, onWatcherError) {
     // Ignore dotfiles/dot-directories that live *inside* the project (.git,
     // .DS_Store, editor scratch, etc.) without nuking the whole watch when the
     // project itself sits under a dotted ancestor path. A regex like
@@ -267,12 +318,24 @@ export function createProjectWatcher(projectPath, onChange) {
     // A watcher 'error' before the initial scan completes (EMFILE, permission
     // loss, …) must REJECT `ready`: resolving only on 'ready' would leave
     // `await watcher.ready` — and the whole openProject — hung forever. The
-    // listener also doubles as the EventEmitter unhandled-'error' guard. A
-    // post-ready 'error' makes the reject a settled-promise no-op.
+    // listener also doubles as the EventEmitter unhandled-'error' guard. Once
+    // `ready` has settled, the reject above is a no-op — that's the live-session
+    // case (watcher died mid-session, not at open time) and is instead surfaced
+    // through `onWatcherError`, the only remaining signal that auto-rebuild has
+    // silently stopped.
+    let readySettled = false;
     const ready = new Promise((resolve, reject) => {
-        watcher.once('ready', () => resolve());
+        watcher.once('ready', () => {
+            readySettled = true;
+            resolve();
+        });
         watcher.on('error', (err) => {
-            reject(err instanceof Error ? err : new Error(String(err)));
+            if (!readySettled) {
+                readySettled = true;
+                reject(err instanceof Error ? err : new Error(String(err)));
+                return;
+            }
+            onWatcherError?.(err);
         });
     });
     return {

package/dist/open-project-watcher-error-callback.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=open-project-watcher-error-callback.test.d.ts.map

package/dist/open-project-watcher-error-callback.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-project-watcher-error-callback.test.d.ts","sourceRoot":"","sources":["../src/open-project-watcher-error-callback.test.ts"],"names":[],"mappings":""}

package/dist/open-project-watcher-error-callback.test.js

@@ -0,0 +1,191 @@
+import { EventEmitter } from 'node:events';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { PassThrough } from 'node:stream';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import * as devkit from './index.js';
+/**
+ * Contract: `openProject` gains an `onWatcherError?: (err: unknown) => void`
+ * option. A watcher 'error' BEFORE the initial scan completes must keep
+ * rejecting `openProject` exactly as today (see open-project-cleanup.test.ts)
+ * — `onWatcherError` must NOT be called for that pre-ready path, so callers
+ * don't get a double signal for the same failure.
+ *
+ * A watcher 'error' AFTER 'ready' (EMFILE, permission loss mid-session, …) is
+ * TODAY silently dropped: `createProjectWatcher`'s `watcher.on('error', ...)`
+ * only rejects the (long-since-settled) `ready` promise, a no-op once ready
+ * has already resolved. The project keeps "running" with a dead watcher and
+ * nothing downstream ever finds out — a save after that point compiles
+ * nothing, forever, with no diagnostic. The fix: `openProject` must forward a
+ * post-ready watcher 'error' to `onWatcherError` so a caller (devtools'
+ * workspace-service) can surface "auto-rebuild stopped working" instead of
+ * silently going stale.
+ *
+ * Harness: verbatim copy of open-project-cleanup.test.ts's fake-fork +
+ * fake-watcher setup (fork/fe/chokidar all mocked so the failure point is
+ * injectable), plus a FakeWatcher that can fire 'error' AFTER 'ready'.
+ */
+const mocks = vi.hoisted(() => ({
+    fork: vi.fn(),
+    feStart: vi.fn(),
+    watch: vi.fn(),
+}));
+vi.mock('node:child_process', async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, fork: mocks.fork, default: { ...actual, fork: mocks.fork } };
+});
+vi.mock('child_process', async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, fork: mocks.fork, default: { ...actual, fork: mocks.fork } };
+});
+vi.mock('../fe/index.js', () => ({ start: mocks.feStart }));
+vi.mock('chokidar', () => ({
+    default: { watch: mocks.watch },
+    watch: mocks.watch,
+}));
+class FakeChild extends EventEmitter {
+    stdout = new PassThrough();
+    stderr = new PassThrough();
+    connected = true;
+    pid = 4343;
+    send = vi.fn((msg) => {
+        const m = msg;
+        if (m && m.cmd === 'build') {
+            queueMicrotask(() => {
+                if (!this.connected)
+                    return;
+                this.emit('message', {
+                    type: 'result',
+                    appInfo: { appId: 'watcher_err_app_001', name: 'watcher-err-app', path: String(m.projectPath ?? '') },
+                });
+            });
+        }
+        return true;
+    });
+    kill = vi.fn(() => {
+        this.connected = false;
+        queueMicrotask(() => this.emit('exit', null, 'SIGTERM'));
+        return true;
+    });
+}
+class FakeWatcher extends EventEmitter {
+    close = vi.fn(async () => { });
+}
+function makeFakeFe() {
+    const server = {
+        close: vi.fn((cb) => {
+            cb?.();
+            return server;
+        }),
+        closeAllConnections: vi.fn(),
+    };
+    return { server, reload: vi.fn() };
+}
+const children = [];
+const watchers = [];
+const feInstances = [];
+const cleanupRoots = [];
+beforeEach(() => {
+    children.length = 0;
+    watchers.length = 0;
+    feInstances.length = 0;
+    mocks.fork.mockReset();
+    mocks.fork.mockImplementation(() => {
+        const child = new FakeChild();
+        children.push(child);
+        return child;
+    });
+    mocks.feStart.mockReset();
+    mocks.feStart.mockImplementation(async () => {
+        const fe = makeFakeFe();
+        feInstances.push(fe);
+        return fe;
+    });
+    mocks.watch.mockReset();
+});
+afterEach(() => {
+    for (const root of cleanupRoots.splice(0)) {
+        fs.rmSync(root, { recursive: true, force: true });
+    }
+});
+function makeFixture() {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'devkit-watcher-err-'));
+    cleanupRoots.push(root);
+    fs.writeFileSync(path.join(root, 'project.config.json'), JSON.stringify({ appid: 'watcher_err_app_001', projectname: 'watcher-err-app' }));
+    return root;
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+describe('openProject onWatcherError — post-ready watcher errors are surfaced, pre-ready path is unchanged', () => {
+    it('does NOT call onWatcherError for a watcher error BEFORE ready (openProject still rejects, same as today)', async () => {
+        const root = makeFixture();
+        mocks.watch.mockImplementation(() => {
+            const watcher = new FakeWatcher();
+            watchers.push(watcher);
+            setTimeout(() => {
+                try {
+                    watcher.emit('error', new Error('EMFILE: too many open files, watch'));
+                }
+                catch {
+                    // no 'error' listener path — matches open-project-cleanup.test.ts
+                }
+            }, 10);
+            return watcher;
+        });
+        const onWatcherError = vi.fn();
+        await expect(devkit.openProject({
+            projectPath: root,
+            watch: true,
+            outputDir: path.join(root, '.out'),
+            onWatcherError,
+        })).rejects.toThrow();
+        expect(onWatcherError, 'a pre-ready watcher error must keep rejecting openProject WITHOUT also invoking onWatcherError — '
+            + 'the caller already gets the failure via the rejected promise').not.toHaveBeenCalled();
+    }, 15_000);
+    it('calls onWatcherError with the error when the watcher fails AFTER ready — openProject has already resolved by then', async () => {
+        const root = makeFixture();
+        let capturedWatcher = null;
+        mocks.watch.mockImplementation(() => {
+            const watcher = new FakeWatcher();
+            watchers.push(watcher);
+            capturedWatcher = watcher;
+            queueMicrotask(() => watcher.emit('ready'));
+            return watcher;
+        });
+        const onWatcherError = vi.fn();
+        const session = await devkit.openProject({
+            projectPath: root,
+            watch: true,
+            outputDir: path.join(root, '.out'),
+            onWatcherError,
+        });
+        const postReadyError = new Error('EMFILE: too many open files, watch (post-ready)');
+        capturedWatcher.emit('error', postReadyError);
+        await sleep(20);
+        expect(onWatcherError, 'today nothing listens for a post-ready watcher error beyond the already-settled ready promise — '
+            + 'the project silently stops auto-rebuilding forever with no signal').toHaveBeenCalledWith(postReadyError);
+        await session.close();
+    }, 15_000);
+    it('a post-ready watcher error does not crash the process (no unhandled "error" event) even without onWatcherError supplied', async () => {
+        const root = makeFixture();
+        let capturedWatcher = null;
+        mocks.watch.mockImplementation(() => {
+            const watcher = new FakeWatcher();
+            watchers.push(watcher);
+            capturedWatcher = watcher;
+            queueMicrotask(() => watcher.emit('ready'));
+            return watcher;
+        });
+        const session = await devkit.openProject({
+            projectPath: root,
+            watch: true,
+            outputDir: path.join(root, '.out'),
+        });
+        expect(() => {
+            capturedWatcher.emit('error', new Error('EMFILE (no onWatcherError supplied)'));
+        }).not.toThrow();
+        await session.close();
+    }, 15_000);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dimina-kit/devkit",
-  "version": "0.1.2-dev.20260703051110",
+  "version": "0.1.2-dev.20260706064107",
   "description": "Development toolkit for Dimina mini-apps with H5 container preview",
   "keywords": [
     "dimina",
@@ -62,7 +62,7 @@
     "cors": "^2.8.6",
     "express": "^5.2.1",
     "open": "^11.0.0",
-    "@dimina-kit/compiler": "0.0.1-dev.20260703051110"
+    "@dimina-kit/compiler": "0.0.1-dev.20260706064107"
   },
   "publishConfig": {
     "access": "public"
@@ -71,7 +71,7 @@
     "build": "tsc",
     "check-types": "tsc --noEmit",
     "lint": "eslint . --max-warnings 0",
-    "test": "vitest run",
+    "test": "vitest run --reporter=default --reporter=json --outputFile.json=test-report.json --coverage.enabled --coverage.reporter=json-summary --coverage.reportsDirectory=coverage",
     "test:dev": "vitest",
     "test:coverage": "vitest run --coverage"
   }