@dimina-kit/devkit 0.1.2-dev.20260703101348 → 0.1.2

package/dist/compile-worker-standby.js

@@ -0,0 +1,283 @@
+/**
+ * Warm-standby manager for the forked compile worker.
+ *
+ * A host (devtools) keeps ONE project-agnostic spare compile worker forked and
+ * prewarmed while no project is open; `openProject` adopts it so the first
+ * compile skips fork + compiler import + toolchain load. The spare never
+ * chdirs and never builds (see compile-worker-entry's prewarm contract), so it
+ * can be handed to ANY next-opened project.
+ *
+ * The manager is a PURE ACCELERATOR — every failure mode degrades to "no
+ * spare" and the caller's normal cold-fork path:
+ *  - adopt() health-checks the spare (ping/pong with a timeout) and kills a
+ *    wedged one rather than handing it over.
+ *  - an unexpected spare death auto-refills, but through a circuit breaker:
+ *    `breakerMaxDeaths` deaths inside `breakerWindowMs` trip the manager into
+ *    'degraded' — permanently cold, no fork storm on a broken install.
+ *  - dispose() (host quit) kills the spare and is terminal; ensure()/adopt()
+ *    afterwards are no-ops, so a teardown racing a refill cannot leak a fork.
+ *
+ * State machine: empty → (ensure) warming → ready → (adopt) empty; an
+ * unexpected death keeps the refill obligation ('warming' with the respawn
+ * scheduled after a short delay); 'degraded' and 'disposed' are terminal.
+ */
+import { fork } from 'node:child_process';
+import { resolveWorkerEntry, workerExecArgv } from './compile-worker.js';
+// Delay between an unexpected spare death and the refill fork. Long enough
+// that an adopt() racing the death observes "obligation but no spare" (and
+// reports a failed hand-off) instead of adopting a just-born replacement the
+// caller never warmed; short enough that the refill is imperceptible.
+const REFILL_DELAY_MS = 500;
+export function createCompileWorkerStandby(opts = {}) {
+    const { onEvent, breakerWindowMs = 30_000, breakerMaxDeaths = 3, healthCheckTimeoutMs = 1000, disposeGraceMs = 5000, } = opts;
+    let state = 'empty';
+    let spare = null;
+    // The manager's own listeners on the current spare — removed on hand-off /
+    // deliberate kill so only UNEXPECTED deaths flow into the breaker.
+    let detachSpareListeners = null;
+    let refillTimer = null;
+    let deathTimestamps = [];
+    let msgSeq = 0;
+    function emit(ev) {
+        try {
+            onEvent?.(ev);
+        }
+        catch {
+            // telemetry must never break the manager
+        }
+    }
+    function cancelRefill() {
+        if (refillTimer) {
+            clearTimeout(refillTimer);
+            refillTimer = null;
+        }
+    }
+    /** Take the spare out of the manager without killing it (hand-off / deliberate kill). */
+    function releaseSpare(child) {
+        if (spare !== child)
+            return;
+        detachSpareListeners?.();
+        detachSpareListeners = null;
+        spare = null;
+    }
+    /**
+     * Single death-accounting authority: emits `died`, feeds the breaker, and
+     * either trips 'degraded' or keeps the refill obligation ('warming' with the
+     * respawn scheduled after REFILL_DELAY_MS). Both an unexpected spare death
+     * and a synchronous fork failure flow through here — one breaker, one refill
+     * policy.
+     */
+    function recordDeathAndScheduleRefill(pid, reason) {
+        emit({ type: 'died', pid, reason });
+        const now = Date.now();
+        deathTimestamps = deathTimestamps.filter(t => now - t < breakerWindowMs);
+        deathTimestamps.push(now);
+        if (deathTimestamps.length >= breakerMaxDeaths) {
+            state = 'degraded';
+            cancelRefill();
+            emit({
+                type: 'degraded',
+                reason: `${deathTimestamps.length} spare deaths within ${breakerWindowMs}ms — standby disabled for this session`,
+            });
+            return;
+        }
+        state = 'warming';
+        cancelRefill();
+        refillTimer = setTimeout(() => {
+            refillTimer = null;
+            if (state !== 'warming' || spare !== null)
+                return;
+            spawnSpare();
+        }, REFILL_DELAY_MS);
+        refillTimer.unref?.();
+    }
+    function onSpareDeath(child, reason) {
+        if (spare !== child)
+            return;
+        releaseSpare(child);
+        if (state === 'disposed' || state === 'degraded')
+            return;
+        recordDeathAndScheduleRefill(child.pid, reason);
+    }
+    function spawnSpare() {
+        const entry = opts.entry ?? resolveWorkerEntry();
+        let child;
+        try {
+            // Same fork shape as compile-worker's own spawnWorker — piped stdio,
+            // explicit execArgv — so the adopter can't tell the difference.
+            child = fork(entry, [], { silent: true, execArgv: workerExecArgv(entry) });
+        }
+        catch (err) {
+            // A synchronous fork failure is a death for breaker purposes: a broken
+            // install must trip 'degraded', not retry forever.
+            recordDeathAndScheduleRefill(undefined, `spare fork failed: ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        spare = child;
+        state = 'warming';
+        emit({ type: 'spawned', pid: child.pid });
+        const onExit = () => onSpareDeath(child, 'spare exited');
+        const onError = (err) => onSpareDeath(child, `spare errored: ${err.message}`);
+        const onMessage = (msg) => {
+            if (spare !== child)
+                return;
+            const reply = msg;
+            if (reply && reply.type === 'prewarm-result' && reply.id === prewarmId) {
+                if (reply.ok) {
+                    if (state === 'warming') {
+                        state = 'ready';
+                        emit({ type: 'prewarmed', pid: child.pid });
+                    }
+                }
+                else {
+                    // A spare that cannot prewarm is useless — kill it deliberately
+                    // and let the death path decide between refill and breaker.
+                    const failed = child;
+                    try {
+                        failed.kill('SIGKILL');
+                    }
+                    catch {
+                        // already dying
+                    }
+                }
+            }
+        };
+        child.on('exit', onExit);
+        child.on('error', onError);
+        child.on('message', onMessage);
+        detachSpareListeners = () => {
+            child.off('exit', onExit);
+            child.off('error', onError);
+            child.off('message', onMessage);
+        };
+        const prewarmId = `standby-prewarm-${++msgSeq}`;
+        try {
+            child.send({ cmd: 'prewarm', id: prewarmId });
+        }
+        catch {
+            // channel already gone — the exit listener owns this death
+        }
+    }
+    /** ping→pong round-trip with a deadline; false on timeout, death or a closed channel. */
+    function pingCheck(child) {
+        return new Promise((resolve) => {
+            if (child.exitCode !== null || child.signalCode !== null || !child.connected) {
+                resolve(false);
+                return;
+            }
+            const id = `standby-ping-${++msgSeq}`;
+            const onMsg = (msg) => {
+                const reply = msg;
+                if (reply && reply.type === 'pong' && reply.id === id)
+                    settle(true);
+            };
+            const onGone = () => settle(false);
+            const timer = setTimeout(() => settle(false), healthCheckTimeoutMs);
+            timer.unref?.();
+            const settle = (ok) => {
+                clearTimeout(timer);
+                child.off('message', onMsg);
+                child.off('exit', onGone);
+                child.off('error', onGone);
+                resolve(ok);
+            };
+            child.on('message', onMsg);
+            child.on('exit', onGone);
+            child.on('error', onGone);
+            try {
+                child.send({ cmd: 'ping', id });
+            }
+            catch {
+                settle(false);
+            }
+        });
+    }
+    return {
+        get state() {
+            return state;
+        },
+        ensure() {
+            if (state !== 'empty')
+                return;
+            spawnSpare();
+        },
+        async adopt() {
+            if (state !== 'ready' && state !== 'warming')
+                return null;
+            const child = spare;
+            if (!child) {
+                // The manager owes a spare (a refill is pending after a death) but
+                // has nothing healthy to hand over right now.
+                emit({ type: 'health-check-failed', reason: 'spare died before adoption' });
+                return null;
+            }
+            // Only a spare whose prewarm has COMPLETED is proven usable. A still-warming
+            // spare stays with the manager — its prewarm-result (including a failure,
+            // which the manager must kill and account for) needs the manager's own
+            // listener. The caller simply cold-forks this once.
+            if (state !== 'ready')
+                return null;
+            const healthy = await pingCheck(child);
+            if (spare !== child) {
+                // Died during the check — the death path already took over.
+                emit({ type: 'health-check-failed', pid: child.pid, reason: 'spare died during health check' });
+                return null;
+            }
+            if (!healthy) {
+                emit({ type: 'health-check-failed', pid: child.pid, reason: 'no pong within the health-check window' });
+                // Deliberate kill: detach FIRST so this never counts as an
+                // unexpected death (no refill, no breaker hit). The caller is about
+                // to cold-fork; it re-arms the standby explicitly via ensure().
+                releaseSpare(child);
+                state = 'empty';
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch {
+                    // already gone
+                }
+                return null;
+            }
+            releaseSpare(child);
+            cancelRefill();
+            state = 'empty';
+            emit({ type: 'adopted', pid: child.pid });
+            return child;
+        },
+        async dispose() {
+            if (state === 'disposed')
+                return;
+            state = 'disposed';
+            cancelRefill();
+            const child = spare;
+            if (child)
+                releaseSpare(child);
+            if (!child || child.exitCode !== null || child.signalCode !== null)
+                return;
+            await new Promise((resolve) => {
+                const done = () => resolve();
+                child.once('exit', done);
+                child.once('error', done);
+                // Bounded AND final: a spare that ignores the polite kill for the whole
+                // grace period is force-killed so it cannot outlive the host, and the
+                // quit path is never wedged waiting for a graceful exit.
+                const guard = setTimeout(() => {
+                    try {
+                        child.kill('SIGKILL');
+                    }
+                    catch {
+                        // already gone
+                    }
+                    done();
+                }, disposeGraceMs);
+                guard.unref?.();
+                try {
+                    child.kill();
+                }
+                catch {
+                    resolve();
+                }
+            });
+        },
+    };
+}

package/dist/compile-worker-standby.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=compile-worker-standby.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compile-worker-standby.test.d.ts","sourceRoot":"","sources":["../src/compile-worker-standby.test.ts"],"names":[],"mappings":""}

package/dist/compile-worker-standby.test.js

@@ -0,0 +1,356 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { createCompileWorkerStandby, } from './compile-worker-standby.js';
+/**
+ * Contract for the warm-standby MANAGER: devtools forks a project-agnostic
+ * "spare" compile worker while no project is open and pre-loads its compiler
+ * (see `compile-worker-entry-warmpool.test.ts` for the ping/prewarm protocol
+ * the spare speaks). `createCompileWorkerStandby` owns exactly one spare at a
+ * time and must be a pure accelerator: any failure of the spare degrades to
+ * "no spare" — it must never make opening a project fail or hang.
+ *
+ * These are REAL-fork tests (no `child_process` mock): a fixture entry script
+ * is forked via the `entry` test hook and its behavior (answer ping/prewarm,
+ * stay silent, or crash immediately) is scripted per test. Every check on
+ * "the spare died" or "the spare was killed" is a real OS PID check —
+ * `process.kill(pid, 0)` — not a spy on an intent to kill.
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function waitForPidDeath(pid, timeoutMs = 8000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!pidAlive(pid))
+            return true;
+        await sleep(100);
+    }
+    return !pidAlive(pid);
+}
+/** Bounded poll for an arbitrary condition — never throws/hangs past the deadline. */
+async function pollUntil(fn, timeoutMs, intervalMs = 50) {
+    const deadline = Date.now() + timeoutMs;
+    let last = fn();
+    while (!last && Date.now() < deadline) {
+        await sleep(intervalMs);
+        last = fn();
+    }
+    return last;
+}
+async function waitForState(standby, target, timeoutMs = 5000) {
+    await pollUntil(() => standby.state === target, timeoutMs);
+    return standby.state;
+}
+/**
+ * Direct children of THIS test process whose command line contains `tag`
+ * (the fixture's own unique tmp-dir path) — mirrors the ps-scan technique
+ * `compile-worker-leak.test.ts` uses for real PID discovery, scoped by a
+ * per-test unique tag instead of a shared module name.
+ */
+function findChildPidsByCommand(tag) {
+    const out = execFileSync('ps', ['-axo', 'pid=,ppid=,command='], { encoding: 'utf8' });
+    const pids = [];
+    for (const line of out.split('\n')) {
+        const match = line.trim().match(/^(\d+)\s+(\d+)\s+(.*)$/);
+        if (!match)
+            continue;
+        const [, pid, ppid, command] = match;
+        if (Number(ppid) !== process.pid)
+            continue;
+        if (!command.includes(tag))
+            continue;
+        pids.push(Number(pid));
+    }
+    return pids;
+}
+// ── fixture entries: scripted IPC children, no compiler involved ───────────
+/** Answers both ping and prewarm normally — the happy-path spare. */
+const FIXTURE_HAPPY = `
+process.on('message', (msg) => {
+	if (!msg) return
+	if (msg.cmd === 'ping') process.send({ type: 'pong', id: msg.id })
+	else if (msg.cmd === 'prewarm') process.send({ type: 'prewarm-result', id: msg.id, ok: true })
+})
+`;
+/** Prewarms fine but never answers ping — simulates a wedged-but-alive spare. */
+const FIXTURE_SILENT_PING = `
+process.on('message', (msg) => {
+	if (!msg) return
+	if (msg.cmd === 'prewarm') process.send({ type: 'prewarm-result', id: msg.id, ok: true })
+})
+`;
+/** Dies immediately on load — drives the circuit-breaker crash-loop scenario. */
+const FIXTURE_CRASH_IMMEDIATELY = `
+process.exit(1)
+`;
+/**
+ * First spawn answers prewarm with ok:false (the process itself stays alive
+ * and still answers ping); every later spawn prewarms normally. The spawn
+ * counter lives in a file next to the fixture, so the SECOND process the
+ * manager forks (the refill) sees n=2 and behaves healthy — modelling a
+ * transient toolchain-load failure that a fresh process recovers from.
+ */
+const FIXTURE_PREWARM_FAIL_ONCE = `
+import fs from 'node:fs'
+import { fileURLToPath } from 'node:url'
+const counter = fileURLToPath(new URL('./spawn-count.txt', import.meta.url))
+let n = 0
+try { n = Number(fs.readFileSync(counter, 'utf8')) || 0 } catch {}
+n += 1
+fs.writeFileSync(counter, String(n))
+const failPrewarm = n === 1
+process.on('message', (msg) => {
+	if (!msg) return
+	if (msg.cmd === 'ping') process.send({ type: 'pong', id: msg.id })
+	else if (msg.cmd === 'prewarm') {
+		if (failPrewarm) process.send({ type: 'prewarm-result', id: msg.id, ok: false, error: 'toolchain load failed (scripted)' })
+		else process.send({ type: 'prewarm-result', id: msg.id, ok: true })
+	}
+})
+`;
+const cleanupDirs = [];
+const doomedPids = [];
+const openStandbys = [];
+function mkTmp() {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'devkit-standby-'));
+    cleanupDirs.push(dir);
+    return dir;
+}
+function writeFixture(dir, body) {
+    const file = path.join(dir, 'entry.mjs');
+    fs.writeFileSync(file, body);
+    return file;
+}
+afterEach(async () => {
+    for (const standby of openStandbys.splice(0)) {
+        try {
+            await standby.dispose();
+        }
+        catch {
+            // best-effort teardown
+        }
+    }
+    for (const pid of doomedPids.splice(0)) {
+        if (pidAlive(pid)) {
+            try {
+                process.kill(pid, 'SIGKILL');
+            }
+            catch {
+                // already gone
+            }
+        }
+    }
+    for (const dir of cleanupDirs.splice(0)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+describe('createCompileWorkerStandby — ensure() forks + prewarms exactly one spare (idempotent)', () => {
+    it('ensure() transitions empty → warming → ready; spawned (with pid) fires before prewarmed; repeated ensure() forks nothing new', async () => {
+        const dir = mkTmp();
+        const entry = writeFixture(dir, FIXTURE_HAPPY);
+        const events = [];
+        const standby = createCompileWorkerStandby({ entry, onEvent: (ev) => events.push(ev) });
+        openStandbys.push(standby);
+        expect(standby.state).toBe('empty');
+        standby.ensure();
+        const readyState = await waitForState(standby, 'ready', 8000);
+        expect(readyState, `standby never reached ready (stuck at ${standby.state})`).toBe('ready');
+        const spawned = events.filter(ev => ev.type === 'spawned');
+        expect(spawned).toHaveLength(1);
+        expect(typeof spawned[0].pid).toBe('number');
+        doomedPids.push(spawned[0].pid);
+        const spawnedIdx = events.findIndex(ev => ev.type === 'spawned');
+        const prewarmedIdx = events.findIndex(ev => ev.type === 'prewarmed');
+        expect(prewarmedIdx, 'a prewarmed event must fire').toBeGreaterThanOrEqual(0);
+        expect(spawnedIdx).toBeLessThan(prewarmedIdx);
+        standby.ensure();
+        standby.ensure();
+        await sleep(200);
+        expect(events.filter(ev => ev.type === 'spawned'), 'repeated ensure() while warming/ready must be a no-op — exactly one spare, ever').toHaveLength(1);
+        expect(findChildPidsByCommand(dir)).toHaveLength(1);
+    }, 20_000);
+});
+describe('createCompileWorkerStandby — adopt() hands the spare over', () => {
+    it('adopt() after ready returns the live ChildProcess (matching pid, connected), fires adopted, resets to empty; a second adopt() is null; dispose() afterwards leaves the handed-over process ALIVE', async () => {
+        const dir = mkTmp();
+        const entry = writeFixture(dir, FIXTURE_HAPPY);
+        const events = [];
+        const standby = createCompileWorkerStandby({ entry, onEvent: (ev) => events.push(ev) });
+        openStandbys.push(standby);
+        standby.ensure();
+        await waitForState(standby, 'ready', 8000);
+        const spawnedPid = events.find(ev => ev.type === 'spawned').pid;
+        const adopted = await standby.adopt();
+        expect(adopted, 'adopt() on a ready spare must hand over a ChildProcess').not.toBeNull();
+        expect(adopted.pid).toBe(spawnedPid);
+        expect(adopted.connected).toBe(true);
+        expect(standby.state).toBe('empty');
+        expect(events.some(ev => ev.type === 'adopted' && ev.pid === spawnedPid)).toBe(true);
+        const second = await standby.adopt();
+        expect(second, 'adopt() with no spare left must return null, not resurrect one').toBeNull();
+        await standby.dispose();
+        expect(pidAlive(spawnedPid), 'dispose() must never kill a process the manager already handed off — the CALLER owns it now').toBe(true);
+        // test-owned cleanup of the handed-over process
+        process.kill(spawnedPid, 'SIGKILL');
+        await waitForPidDeath(spawnedPid);
+    }, 20_000);
+});
+describe('createCompileWorkerStandby — adopt() health check', () => {
+    it('a spare externally SIGKILLed before adopt() fails the health check: adopt() → null, health-check-failed fires', async () => {
+        const dir = mkTmp();
+        const entry = writeFixture(dir, FIXTURE_HAPPY);
+        const events = [];
+        const standby = createCompileWorkerStandby({ entry, onEvent: (ev) => events.push(ev) });
+        openStandbys.push(standby);
+        standby.ensure();
+        await waitForState(standby, 'ready', 8000);
+        const pid = events.find(ev => ev.type === 'spawned').pid;
+        process.kill(pid, 'SIGKILL');
+        await waitForPidDeath(pid);
+        const adopted = await standby.adopt();
+        expect(adopted).toBeNull();
+        expect(events.some(ev => ev.type === 'health-check-failed')).toBe(true);
+    }, 20_000);
+    it('a spare that never answers ping times out the health check: adopt() → null, health-check-failed fires, and the wedged spare is ACTUALLY killed', async () => {
+        const dir = mkTmp();
+        const entry = writeFixture(dir, FIXTURE_SILENT_PING);
+        const events = [];
+        const standby = createCompileWorkerStandby({
+            entry,
+            onEvent: (ev) => events.push(ev),
+            healthCheckTimeoutMs: 300,
+        });
+        openStandbys.push(standby);
+        standby.ensure();
+        await waitForState(standby, 'ready', 8000);
+        const pid = events.find(ev => ev.type === 'spawned').pid;
+        expect(pidAlive(pid)).toBe(true);
+        doomedPids.push(pid);
+        const adopted = await standby.adopt();
+        expect(adopted).toBeNull();
+        expect(events.some(ev => ev.type === 'health-check-failed')).toBe(true);
+        expect(await waitForPidDeath(pid, 5000), 'a spare that fails its own health check must be killed, not left running unmonitored').toBe(true);
+    }, 20_000);
+});
+describe('createCompileWorkerStandby — unexpected death auto-refills', () => {
+    it('an unexpected death of the READY spare fires died and auto-refills a NEW spare (different pid), returning to ready', async () => {
+        const dir = mkTmp();
+        const entry = writeFixture(dir, FIXTURE_HAPPY);
+        const events = [];
+        const standby = createCompileWorkerStandby({ entry, onEvent: (ev) => events.push(ev) });
+        openStandbys.push(standby);
+        standby.ensure();
+        await waitForState(standby, 'ready', 8000);
+        const firstPid = events.find(ev => ev.type === 'spawned').pid;
+        process.kill(firstPid, 'SIGKILL');
+        const diedFired = await pollUntil(() => events.some(ev => ev.type === 'died'), 5000);
+        expect(diedFired, 'an unexpected spare death must fire a died event').toBe(true);
+        const readyAgain = await waitForState(standby, 'ready', 8000);
+        expect(readyAgain, 'the manager must auto-refill after an unexpected death').toBe('ready');
+        const spawnedPids = events.filter(ev => ev.type === 'spawned').map(ev => ev.pid);
+        expect(spawnedPids).toHaveLength(2);
+        expect(spawnedPids[1]).not.toBe(firstPid);
+        doomedPids.push(spawnedPids[1]);
+    }, 20_000);
+});
+describe('createCompileWorkerStandby — a spare whose prewarm FAILED is unusable', () => {
+    it('a prewarm-result ok:false spare is never handed out as ready: the manager kills it (real PID death), fires died with its pid, and refills to ready on a fresh pid', async () => {
+        const dir = mkTmp();
+        const entry = writeFixture(dir, FIXTURE_PREWARM_FAIL_ONCE);
+        const events = [];
+        const standby = createCompileWorkerStandby({ entry, onEvent: (ev) => events.push(ev) });
+        openStandbys.push(standby);
+        standby.ensure();
+        // The first spawn's prewarm fails; the manager must recover through the
+        // normal died→refill path and end ready on the SECOND (healthy) spawn.
+        const readyState = await waitForState(standby, 'ready', 10_000);
+        expect(readyState, `the manager must reach ready via a refill after the failed prewarm (stuck at ${standby.state})`).toBe('ready');
+        const spawnedPids = events.filter(ev => ev.type === 'spawned').map(ev => ev.pid);
+        expect(spawnedPids.length, 'a failed prewarm must trigger a SECOND spawn — the broken spare is not retried in place').toBeGreaterThanOrEqual(2);
+        const firstPid = spawnedPids[0];
+        const currentPid = spawnedPids.at(-1);
+        expect(currentPid).not.toBe(firstPid);
+        doomedPids.push(...spawnedPids);
+        // The un-prewarmed process was alive and answering ping — only the
+        // manager itself can have killed it. It must be REALLY dead, not idling
+        // unowned next to the refill.
+        expect(await waitForPidDeath(firstPid, 5000), 'the spare whose prewarm failed must be killed by the manager — a live-but-cold process handed out later would silently lose the whole warm-up').toBe(true);
+        expect(events.some(ev => ev.type === 'died' && ev.pid === firstPid), 'the failed-prewarm teardown must surface as a died event carrying the broken spare\'s pid').toBe(true);
+        // No prewarmed event may reference the broken first pid: ready was
+        // reached by the refill, never by the ok:false spare.
+        expect(events.some(ev => ev.type === 'prewarmed' && ev.pid === firstPid), 'a spare that answered prewarm-result ok:false must never be reported prewarmed').toBe(false);
+        expect(pidAlive(currentPid)).toBe(true);
+    }, 30_000);
+});
+describe('createCompileWorkerStandby — circuit breaker', () => {
+    it('3 deaths within the window trip state=degraded, fire degraded exactly once, and permanently stop forking — ensure()/adopt() become no-ops', async () => {
+        const dir = mkTmp();
+        const entry = writeFixture(dir, FIXTURE_CRASH_IMMEDIATELY);
+        const events = [];
+        const standby = createCompileWorkerStandby({
+            entry,
+            onEvent: (ev) => events.push(ev),
+            breakerWindowMs: 60_000,
+            breakerMaxDeaths: 3,
+            healthCheckTimeoutMs: 300,
+        });
+        openStandbys.push(standby);
+        standby.ensure();
+        const degraded = await pollUntil(() => standby.state === 'degraded', 10_000);
+        expect(degraded, `standby never degraded (stuck at ${standby.state})`).toBe(true);
+        expect(events.filter(ev => ev.type === 'degraded')).toHaveLength(1);
+        expect(events.filter(ev => ev.type === 'spawned')).toHaveLength(3);
+        // quiet period: no further fork attempts once tripped
+        await sleep(1000);
+        expect(events.filter(ev => ev.type === 'spawned')).toHaveLength(3);
+        expect(findChildPidsByCommand(dir).filter(pidAlive), 'a tripped breaker must leave no live spare process behind').toHaveLength(0);
+        standby.ensure();
+        await sleep(200);
+        expect(events.filter(ev => ev.type === 'spawned'), 'ensure() while degraded is a no-op').toHaveLength(3);
+        const adopted = await standby.adopt();
+        expect(adopted, 'adopt() while degraded must return null, never resurrect the crash-loop').toBeNull();
+    }, 30_000);
+});
+describe('createCompileWorkerStandby — dispose()', () => {
+    it('dispose() while ready kills the spare (real PID death), moves state to disposed, and is idempotent; ensure()/adopt() afterwards are no-ops', async () => {
+        const dir = mkTmp();
+        const entry = writeFixture(dir, FIXTURE_HAPPY);
+        const events = [];
+        const standby = createCompileWorkerStandby({ entry, onEvent: (ev) => events.push(ev) });
+        openStandbys.push(standby);
+        standby.ensure();
+        await waitForState(standby, 'ready', 8000);
+        const pid = events.find(ev => ev.type === 'spawned').pid;
+        await standby.dispose();
+        expect(standby.state).toBe('disposed');
+        expect(await waitForPidDeath(pid, 5000), 'dispose() must leave the spare actually dead, not merely requested to die').toBe(true);
+        await expect(standby.dispose()).resolves.toBeUndefined();
+        standby.ensure();
+        await sleep(200);
+        expect(standby.state, 'a disposed standby is terminal — ensure() must not resurrect it').toBe('disposed');
+        const adopted = await standby.adopt();
+        expect(adopted).toBeNull();
+    }, 20_000);
+});
+describe('createCompileWorkerStandby — empty state', () => {
+    it('adopt() with no ensure() ever called returns null and forks nothing', async () => {
+        const standby = createCompileWorkerStandby({});
+        openStandbys.push(standby);
+        expect(standby.state).toBe('empty');
+        const adopted = await standby.adopt();
+        expect(adopted).toBeNull();
+        expect(standby.state).toBe('empty');
+    });
+});