@wildo-ai/platform-core-shared 1.1.10 → 1.1.12

package/dist/esm/dev-runtime/node-runtime-dev-supervisor.js

@@ -0,0 +1,578 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { BACKEND_START_OUTCOME_DIRECTORY, BackendStartFailureCause, BackendStartOutcome, BackendStartOutcomeRecord_Schema, } from '../runtime/backend-start-outcome.contracts.js';
+import { APPLICATION_RUNTIME_SIGNALS_RELATIVE_DIRECTORY, LOCAL_DEV_RUNTIME_SIGNALS_PROTOCOL_VERSION, LOCAL_DEV_SUPERVISOR_OBSERVATION_KIND, LocalDevCompileState, LocalDevSupervisorBlocker, LocalDevSupervisorState, } from '../runtime/local-dev-runtime-signals.contracts.js';
+import { compileObservationPath, isLiveCompileObservation, isLiveSupervisorObservation, readCompileObservation, readSupervisorObservation, runtimeRestartSignalPath, supervisorObservationPath, writeRuntimeSignalRecord, } from './dev-runtime-signals.js';
+import { identifyPortHolder, isProcessAlive, killProcessGroupNow, readProcessIdentity, terminateProcessGroup, usesProcessGroups } from './dev-runtime-processes.js';
+import { classifyDependencyInstall, decideRuntimeAfterDependencyInstall, readDependencyInstallRecord, RuntimeDependencyInstallDecision, } from './dependency-install-record.js';
+import { LocalDevDependencyInstallPhase } from '../runtime/local-dev-runtime-signals.contracts.js';
+/**
+ * The dev supervisor of one NODE RUNTIME of an app-creator install — the backend, a minion, a node worker (#3214, #3215,
+ * #3216, #3257).
+ *
+ * It owns the runtime's process the way the monorepo's `runtime-supervisor.mjs` does for a framework developer, and keeps
+ * the promises the old `tsc-watch --onSuccess "node dist/index.js"` could not. They are written about the backend, where
+ * every one of them was measured; each holds for any runtime it supervises, see below:
+ *
+ * 1. **It starts the backend only on PUBLISHED builds.** The backend's own package and every workspace package it
+ *    depends on must report `READY` (emitted, rewritten, verified — see `PackageCompileLoop`). A backend therefore never
+ *    starts between `tsc` and its alias pass, which is how `ERR_MODULE_NOT_FOUND` reached it (#3216).
+ * 2. **It restarts the backend when ANY package it loads publishes a newer build**, the shared library included. Before
+ *    this, only a change to the backend's own sources restarted it, and a fix landed in the shared library left the
+ *    backend down on a tree that already booted (#3215).
+ * 3. **It owns the backend's process group**: the child leads its own group, and a restart or a stop signals the whole
+ *    group. A second supervisor for the same package refuses to start, and a backend an earlier generation left behind
+ *    (its supervisor killed outright) is stopped before a new one starts (#3214).
+ * 4. **A port another process holds is named, not retried into the ground.** When a start fails binding its port, the
+ *    supervisor asks the operating system who listens there. The orphan of an earlier generation — `node <entry>` in this
+ *    package — is stopped and the backend restarted; anything else pauses the supervisor with
+ *    `PORT_HELD_BY_FOREIGN_PROCESS`, the holder's pid, parent, start time and working directory in its record and its
+ *    log, and the backend starts the moment the port is free.
+ * 5. **A crash recovers by itself on the next build, and a dependency outage by itself (#3365).** A failed start is
+ *    respawned with a bounded backoff. A spent budget pauses the supervisor only when the start record says the
+ *    backend's own startup refused; the next published build of any package it loads starts it again. Any other cause
+ *    (a dependency that did not answer, or no record) crash-loops: the delay keeps doubling up to
+ *    {@link CRASH_LOOP_MAX_DELAY_MS} and never stops, so a database that comes back brings the backend back. A child
+ *    resets the budget only once its own start record says it STARTED — or, for a runtime that writes no start record
+ *    at all, once it stayed up {@link DEFAULT_HEALTHY_UPTIME_WITHOUT_START_RECORD_MS}.
+ * 6. **Nothing outlives it.** A stop terminates the backend and the compiler in parallel; an exit without one (an
+ *    uncaught error, a forced stop) kills both groups synchronously on the way out.
+ *
+ * Its state is published at `<app>/.wildo-saas/runtime-signals/supervisors/<label>.json`, the record the dev companion's
+ * boot guard already reads, so a paused backend is visible to the build lane in this mode too.
+ *
+ * 7. **A restart can be ASKED for (#2134).** The supervisor creates `<app>/.wildo-saas/runtime-signals/<label>.signal`,
+ *    names it in its record (`signalFilePath`), and restarts the runtime when the file's modification time changes, on
+ *    the build it is already running, with a fresh crash budget. That is the door `wildo secrets set` uses: it regenerates
+ *    the runtime's `.env` and touches the signal of every runtime that reads the key and whose supervisor is live, so the
+ *    restarted process reads the new value. Before this the backend of a created application kept its boot-time value
+ *    until `wildo local dev` was restarted, because this supervisor honoured no request and the CLI found no signal.
+ *    A request arriving while a package it loads is not publishable waits for it, like any start (promise 1); one
+ *    arriving while paused or backing off starts the runtime now; one arriving while a foreign process holds the port
+ *    re-checks the port now. The same file the monorepo's `runtime-supervisor.mjs` honours under the same name, so the
+ *    CLI needs no branch per mode.
+ *
+ *    Rejected: a route per runtime that reloads its environment in place, as the companion has
+ *    (`POST /api/companion/runtime/env/apply`). The backend's configuration is read once into services built at boot
+ *    (provider clients, the mailer), so reloading `process.env` would change nothing they hold, and every runtime would
+ *    need its own. A restart is the one remedy that is right for every runtime.
+ *
+ * ## Why one supervisor for every node runtime (#3257)
+ *
+ * Promises 1, 2, 3, 5 and 6 say nothing about HTTP, so a minion and a node worker get them by construction rather than
+ * through a copy that would drift: they start only on published builds of every workspace package they load (the
+ * shared library, and the backend whose companion exports a minion imports), restart when one of them publishes, and
+ * own their process group, so `wildo local dev` stopping leaves none of them re-parented to init.
+ *
+ * Promise 4 is the one backend-shaped decision, and it is taken from the START RECORD the engine's
+ * `StartApplicationBackendService.initialize` writes for the process (`failureCause: port-in-use`, with the port),
+ * looked up by the child's pid. A runtime whose start writes no such record never enters the branch; nothing has to be
+ * switched off. A minion binds no port and so never writes that cause. A node worker listens on its declared port and
+ * records its start through the same writer since #3288 (`StartWorkerApplicationBackendService.initialize`, filed as
+ * `workers.<name>`), so a port another process holds is named for it exactly as for the backend. The orphan of a
+ * supervisor killed outright is also stopped at {@link NodeRuntimeDevSupervisor.start}, through the supervisor record.
+ *
+ * The crash budget's reset (promise 5) also keys on the start record. The backend, a minion and a node worker all write
+ * one, but none does when its environment carries no runtime-signals home (a `.env` generated before #3288, an
+ * environment that is not LOCAL), and a child that dies before its bootstrap reaches the writer leaves none. Such a
+ * runtime would otherwise never reset the budget: five crashes spread over a day would spend it.
+ * For a process that left NO record at all, staying up {@link DEFAULT_HEALTHY_UPTIME_WITHOUT_START_RECORD_MS}
+ * counts as having started. Uptime stays out of the decision whenever a record exists, which is the case the uptime
+ * rule was wrong for (a start refused after twenty seconds of registry initialization).
+ */
+export const CRASH_RESPAWN_MAX_ATTEMPTS = 5;
+/**
+ * How long a child that wrote NO start record must stay up before its exit counts as a fresh failure with a fresh
+ * budget. Only consulted when the process left no record at all; see the class JSDoc.
+ */
+export const DEFAULT_HEALTHY_UPTIME_WITHOUT_START_RECORD_MS = 60_000;
+const CRASH_RESPAWN_BASE_DELAY_MS = 1_000;
+const CRASH_RESPAWN_MAX_DELAY_MS = 30_000;
+/**
+ * The crash-loop cap (#3365): past the budget, a crash whose cause is a dependency (or cannot be told) keeps being
+ * restarted with the delay doubling up to five minutes, Kubernetes' CrashLoopBackOff ceiling, and never stops.
+ */
+export const CRASH_LOOP_MAX_DELAY_MS = 300_000;
+/** The cause a crash-loop log line names, from the crashed child's start record. */
+function describeCrashLoopCause(started) {
+    if (started?.failureCause === BackendStartFailureCause.DEPENDENCY_UNREACHABLE)
+        return 'a service it connects to did not answer or was not ready';
+    if (started?.failureCause === BackendStartFailureCause.PORT_IN_USE)
+        return 'its port was held and no holder could be identified';
+    return started === undefined ? 'it left no start record' : 'its start record names no cause';
+}
+/**
+ * Whether a spent crash budget may PAUSE the runtime (#3365): only when its own start record says its startup refused,
+ * which a new build is what fixes. A dependency that did not answer or was not ready yet (`dependency-unreachable`,
+ * #3377), and a crash that left
+ * no record or one from an engine that names no cause, crash-loop instead: a database that comes back must bring its
+ * runtime back by itself. A port held by another process is decided before the budget is read (promise 4).
+ */
+export function spentCrashBudgetPauses(started) {
+    return started?.outcome === BackendStartOutcome.FAILED && started.failureCause === BackendStartFailureCause.STARTUP_REFUSED;
+}
+/** Whether the packages a runtime loads are publishable, and the newest build among them. Pure. */
+export function assessRuntimeBuilds(input) {
+    let newestBuildAtMs = 0;
+    let waitingFor = null;
+    const consider = (packageName, observation) => {
+        const builtAtMs = observation.lastSuccessfulCompileAt ? Date.parse(observation.lastSuccessfulCompileAt) : 0;
+        if (builtAtMs > newestBuildAtMs)
+            newestBuildAtMs = builtAtMs;
+        if (waitingFor === null && observation.state !== LocalDevCompileState.READY)
+            waitingFor = `${packageName} (${observation.state})`;
+    };
+    consider(input.own.packageName, input.own);
+    for (const dependency of input.dependencies) {
+        if (dependency.observation)
+            consider(dependency.packageName, dependency.observation);
+        else if (!input.dependencyGraceElapsed && waitingFor === null)
+            waitingFor = `${dependency.packageName} (no compiler record yet)`;
+    }
+    return { ready: waitingFor === null, waitingFor, newestBuildAtMs };
+}
+/**
+ * Is the process on the port an orphaned runtime of THIS package — `node … <entry>` whose working directory is the
+ * package root — rather than something the supervisor must not touch? Pure.
+ */
+export function isOrphanedRuntimeOfPackage(holder, input) {
+    if (holder.cwd === null || resolve(holder.cwd) !== resolve(input.packageRoot))
+        return false;
+    const command = holder.command ?? '';
+    const entryRelative = relative(input.packageRoot, resolve(input.packageRoot, input.entry));
+    return /\bnode\b/u.test(command) && (command.includes(entryRelative) || command.includes(resolve(input.packageRoot, input.entry)));
+}
+/** The start record this runtime process wrote, if any (the supervisor reads it to learn why a start failed). */
+export function readBackendStartRecordOfProcess(appRoot, pid) {
+    const directory = join(appRoot, APPLICATION_RUNTIME_SIGNALS_RELATIVE_DIRECTORY, BACKEND_START_OUTCOME_DIRECTORY);
+    let entries;
+    try {
+        entries = readdirSync(directory).filter((name) => name.endsWith('.json'));
+    }
+    catch {
+        return undefined;
+    }
+    for (const entry of entries) {
+        try {
+            const parsed = BackendStartOutcomeRecord_Schema.safeParse(JSON.parse(readFileSync(join(directory, entry), 'utf8')));
+            if (parsed.success && parsed.data.pid === pid)
+                return parsed.data;
+        }
+        catch {
+            // A record mid-rename is the next poll's.
+        }
+    }
+    return undefined;
+}
+export class NodeRuntimeDevSupervisor {
+    options;
+    recordPath;
+    entryPath;
+    log;
+    startedAtMs = Date.now();
+    record;
+    child = null;
+    childStartedAtMs = 0;
+    expectedExit = new WeakSet();
+    stopping = false;
+    /**
+     * Held while ONE decision runs — a poll, or the handling of a child's exit. Both start children, so they must never
+     * interleave: a poll that spawned while an exit handler was stopping an orphan would put a second runtime on the port,
+     * and that one's failure would then name the first as the orphan.
+     */
+    busy = false;
+    pollTimer = null;
+    heartbeatTimer = null;
+    backoffTimer = null;
+    crashCount = 0;
+    /** The newest build the supervisor was paused against; a build newer than it lifts a crash pause. */
+    pausedAgainstBuildAtMs = null;
+    heldPort = null;
+    lastPortCheckAtMs = 0;
+    lastWaitingFor = null;
+    loggedAbsentDependencies = false;
+    /** The restart-request file (promise 7) and its modification time when last read; `null` while it cannot be read. */
+    signalPath;
+    lastSignalStamp = null;
+    /** A restart was asked for and is not served yet: the next start serves it. */
+    restartRequested = false;
+    /**
+     * The dependency install (#3552) this supervisor already acted on, by its key. Seeded at {@link start} with an install
+     * that had already ended, so a supervisor started after an install never relaunches onto it.
+     */
+    handledInstallKey = null;
+    /** Whether the current install hold has been logged, so a 16 s install logs once rather than every poll. */
+    loggedInstallHold = false;
+    constructor(options) {
+        this.options = options;
+        this.recordPath = supervisorObservationPath(options.appRoot, options.label);
+        this.signalPath = runtimeRestartSignalPath(options.appRoot, options.label);
+        this.entryPath = resolve(options.packageRoot, options.entry);
+        this.log = options.log ?? ((line) => process.stdout.write(`[wildo-dev-runtime] ${options.label}: ${line}\n`));
+        const now = new Date().toISOString();
+        this.record = {
+            kind: LOCAL_DEV_SUPERVISOR_OBSERVATION_KIND,
+            schemaVersion: LOCAL_DEV_RUNTIME_SIGNALS_PROTOCOL_VERSION,
+            producerKind: 'wildo-dev-runtime',
+            producerInstanceId: randomUUID(),
+            producerPid: process.pid,
+            frameworkRoot: null,
+            appRoot: options.appRoot,
+            label: options.label,
+            runtimeTarget: options.packageName,
+            workingDirectory: options.packageRoot,
+            state: LocalDevSupervisorState.STARTING,
+            childPid: null,
+            childStartedAt: null,
+            retryCount: 0,
+            blocker: null,
+            portHolder: null,
+            signalFilePath: this.signalPath,
+            heartbeatAt: now,
+            updatedAt: now,
+        };
+    }
+    get observation() {
+        return this.record;
+    }
+    /**
+     * Start supervising. REFUSES when another live supervisor already owns this runtime: two runtimes of one package is
+     * the defect this exists to prevent. A runtime left by a dead supervisor is stopped first.
+     */
+    async start() {
+        const previous = readSupervisorObservation(this.recordPath);
+        if (previous && previous.producerPid !== process.pid && isLiveSupervisorObservation(previous)) {
+            throw new Error(`A supervisor already runs ${this.options.label} (process ${previous.producerPid}, ${this.recordPath}). Stop that dev process first: a second one would start a second runtime.`);
+        }
+        if (previous?.childPid && isProcessAlive(previous.childPid)) {
+            const identity = readProcessIdentity(previous.childPid);
+            if (identity && isOrphanedRuntimeOfPackage(identity, { packageRoot: this.options.packageRoot, entry: this.options.entry })) {
+                this.log(`stopping the runtime an earlier dev run left behind (pid ${previous.childPid}, parent ${identity.ppid ?? 'unknown'}, started ${identity.startedAt ?? 'unknown'})`);
+                await terminateProcessGroup(previous.childPid);
+            }
+        }
+        this.prepareRestartSignal();
+        const installAtStart = classifyDependencyInstall(readDependencyInstallRecord(this.options.appRoot), Date.now());
+        if (installAtStart.phase === LocalDevDependencyInstallPhase.ENDED)
+            this.handledInstallKey = installAtStart.key;
+        this.publish({ state: LocalDevSupervisorState.STARTING, blocker: null });
+        this.heartbeatTimer = setInterval(() => this.publish({}), 5_000);
+        this.heartbeatTimer.unref();
+        await this.options.compileLoop.start();
+        // A stop that arrived while the compiler was starting wins: nothing more is started.
+        if (this.stopping)
+            return;
+        this.pollTimer = setInterval(() => void this.serialized(() => this.decide()), this.options.pollIntervalMs ?? 500);
+        await this.serialized(() => this.decide());
+    }
+    /** Stop the runtime and the compiler, IN PARALLEL so a caller's stop deadline covers both. */
+    async stop() {
+        if (this.stopping)
+            return;
+        this.stopping = true;
+        for (const timer of [this.pollTimer, this.heartbeatTimer, this.backoffTimer])
+            if (timer)
+                clearTimeout(timer);
+        await Promise.all([this.stopChild(3_000), this.options.compileLoop.stop()]);
+        this.publish({ state: LocalDevSupervisorState.STOPPED, childPid: null, blocker: null });
+    }
+    /**
+     * Kill the runtime and the compiler synchronously: the last act of a supervisor that is exiting without a clean stop
+     * (an uncaught error, a forced stop), so neither outlives it re-parented to init (#3214).
+     */
+    killChildrenNow() {
+        killProcessGroupNow(this.child?.pid);
+        this.options.compileLoop.killChildrenNow();
+    }
+    publish(updates) {
+        const now = new Date().toISOString();
+        const transition = Object.keys(updates).length > 0;
+        this.record = { ...this.record, ...updates, retryCount: this.crashCount, heartbeatAt: now, ...(transition ? { updatedAt: now } : {}) };
+        try {
+            writeRuntimeSignalRecord(this.recordPath, this.record);
+        }
+        catch (error) {
+            this.log(`could not publish the supervisor record (${error.message})`);
+        }
+    }
+    /** Run one decision at a time (see {@link busy}); a decision asked for while one runs is dropped, the next poll asks again. */
+    async serialized(work) {
+        if (this.stopping || this.busy)
+            return;
+        this.busy = true;
+        try {
+            await work();
+        }
+        finally {
+            this.busy = false;
+        }
+    }
+    /**
+     * Create the restart-request file when absent, and take its current modification time as the baseline, so only a
+     * change made AFTER this supervisor started is a request. A file the supervisor cannot create leaves the runtime
+     * supervised as before, with the reason logged: a missing door must never stop the runtime.
+     */
+    prepareRestartSignal() {
+        try {
+            if (!existsSync(this.signalPath)) {
+                mkdirSync(dirname(this.signalPath), { recursive: true, mode: 0o700 });
+                writeFileSync(this.signalPath, 'initial\n', { encoding: 'utf8', mode: 0o600 });
+            }
+        }
+        catch (error) {
+            this.log(`could not create the restart signal ${this.signalPath} (${error.message}); a restart cannot be requested`);
+        }
+        this.lastSignalStamp = this.readSignalStamp();
+    }
+    readSignalStamp() {
+        try {
+            return statSync(this.signalPath).mtimeMs;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Whether the restart-request file changed since it was last read (promise 7). A file that vanished asks nothing. */
+    takeRestartRequest() {
+        const stamp = this.readSignalStamp();
+        if (stamp === null || stamp === this.lastSignalStamp) {
+            if (stamp !== null)
+                this.lastSignalStamp = stamp;
+            return false;
+        }
+        this.lastSignalStamp = stamp;
+        return true;
+    }
+    /** The workspace dependencies' compile records, a record nobody live stands behind read as absent. */
+    readDependencyObservations(nowMs) {
+        return this.options.dependencyPackageNames.map((packageName) => {
+            const observation = readCompileObservation(compileObservationPath(this.options.appRoot, packageName));
+            return { packageName, observation: observation !== undefined && isLiveCompileObservation(observation, nowMs) ? observation : undefined };
+        });
+    }
+    async decide() {
+        const nowMs = Date.now();
+        const dependencyGraceElapsed = nowMs - this.startedAtMs >= (this.options.absentDependencyGraceMs ?? 30_000);
+        const dependencies = this.readDependencyObservations(nowMs);
+        if (dependencyGraceElapsed && !this.loggedAbsentDependencies) {
+            const absent = dependencies.filter((dependency) => dependency.observation === undefined).map((dependency) => dependency.packageName);
+            if (absent.length > 0) {
+                this.loggedAbsentDependencies = true;
+                this.log(`no live compiler reports for ${absent.join(', ')} (is its dev process running?); starting on the dist already on disk, and the runtime will not be restarted when it changes`);
+            }
+        }
+        const builds = assessRuntimeBuilds({ own: this.options.compileLoop.observation, dependencies, dependencyGraceElapsed });
+        if (this.applyDependencyInstall(nowMs) === RuntimeDependencyInstallDecision.HOLD)
+            return;
+        if (this.takeRestartRequest()) {
+            this.restartRequested = true;
+            this.log(`a restart was requested (${this.signalPath} changed); the next start serves it, so the runtime reads its environment again`);
+            // A request re-checks a held port now, and lifts a crash pause: whoever asked expects an attempt, not a wait.
+            this.lastPortCheckAtMs = 0;
+            if (this.pausedAgainstBuildAtMs !== null) {
+                this.pausedAgainstBuildAtMs = null;
+                this.crashCount = 0;
+            }
+        }
+        if (this.heldPort !== null) {
+            if (nowMs - this.lastPortCheckAtMs < (this.options.portRecheckIntervalMs ?? 5_000))
+                return;
+            this.lastPortCheckAtMs = nowMs;
+            const holder = await identifyPortHolder(this.heldPort);
+            if (holder !== null) {
+                this.publish({ state: LocalDevSupervisorState.PAUSED, blocker: LocalDevSupervisorBlocker.PORT_HELD_BY_FOREIGN_PROCESS, portHolder: holder });
+                return;
+            }
+            this.log(`port ${this.heldPort} is free again; starting the runtime`);
+            this.heldPort = null;
+            this.crashCount = 0;
+            this.publish({ portHolder: null, blocker: null });
+        }
+        if (this.pausedAgainstBuildAtMs !== null) {
+            if (builds.newestBuildAtMs <= this.pausedAgainstBuildAtMs)
+                return;
+            this.log('a newer build was published; starting the runtime again');
+            this.pausedAgainstBuildAtMs = null;
+            this.crashCount = 0;
+        }
+        if (!builds.ready) {
+            if (this.child === null && this.lastWaitingFor !== builds.waitingFor) {
+                this.lastWaitingFor = builds.waitingFor;
+                this.log(`waiting for ${builds.waitingFor} to publish before starting the runtime`);
+                this.publish({ state: LocalDevSupervisorState.STARTING, blocker: `WAITING_FOR_BUILD ${builds.waitingFor}` });
+            }
+            // A running runtime keeps serving its last good build until every package it loads is publishable again.
+            return;
+        }
+        this.lastWaitingFor = null;
+        if (this.child !== null) {
+            if (this.restartRequested) {
+                this.crashCount = 0;
+                await this.stopChild();
+                this.spawnChild();
+                return;
+            }
+            const settled = nowMs - builds.newestBuildAtMs >= (this.options.restartDebounceMs ?? 750);
+            if (builds.newestBuildAtMs > this.childStartedAtMs && settled) {
+                this.log('a package the runtime loads published a newer build; restarting the runtime');
+                this.crashCount = 0;
+                await this.stopChild();
+                this.spawnChild();
+            }
+            return;
+        }
+        if (this.backoffTimer !== null) {
+            // A build newer than the start that crashed is what a backoff waits for: start on it now, with a fresh budget.
+            // So is a requested restart (promise 7).
+            if (builds.newestBuildAtMs <= this.childStartedAtMs && !this.restartRequested)
+                return;
+            clearTimeout(this.backoffTimer);
+            this.backoffTimer = null;
+            this.crashCount = 0;
+        }
+        this.spawnChild();
+    }
+    /**
+     * A dependency install is a stack event (#3552). While one re-creates `node_modules`, nothing is started or restarted:
+     * a start would read a half-installed tree, and a running runtime keeps serving what it loaded. When it ends, the
+     * runtime is relaunched with a fresh crash budget — it loaded modules from the tree the install replaced, and a crash
+     * the install caused must not leave it paused. The relaunch waits, like every start, until every package it loads is
+     * publishable again (the compile loops recompile after an install too).
+     */
+    applyDependencyInstall(nowMs) {
+        const install = classifyDependencyInstall(readDependencyInstallRecord(this.options.appRoot), nowMs);
+        const decision = decideRuntimeAfterDependencyInstall({ install, runtimeStartedAtMs: this.childStartedAtMs, handledInstallKey: this.handledInstallKey });
+        if (decision === RuntimeDependencyInstallDecision.HOLD) {
+            if (!this.loggedInstallHold) {
+                this.loggedInstallHold = true;
+                this.log('a dependency install is re-creating node_modules; the runtime is held until it ends');
+            }
+            if (this.child === null)
+                this.publish({ state: LocalDevSupervisorState.PAUSED, childPid: null, blocker: LocalDevSupervisorBlocker.DEPENDENCY_INSTALL_IN_FLIGHT });
+            return decision;
+        }
+        this.loggedInstallHold = false;
+        if (install.phase === LocalDevDependencyInstallPhase.ENDED)
+            this.handledInstallKey = install.key;
+        if (decision === RuntimeDependencyInstallDecision.RELAUNCH) {
+            this.log('a dependency install ended after the runtime started; relaunching it on the installed tree with a fresh crash budget');
+            this.restartRequested = true;
+            this.crashCount = 0;
+            this.pausedAgainstBuildAtMs = null;
+            if (this.child === null)
+                this.publish({ state: LocalDevSupervisorState.STARTING, blocker: null });
+        }
+        return decision;
+    }
+    spawnChild() {
+        if (this.stopping)
+            return;
+        // Any start reads the environment afresh, so it serves a pending restart request.
+        this.restartRequested = false;
+        const child = spawn(process.execPath, [...(this.options.nodeArguments ?? []), this.entryPath], {
+            cwd: this.options.packageRoot,
+            detached: usesProcessGroups(),
+            stdio: ['ignore', 'inherit', 'inherit'],
+        });
+        this.child = child;
+        this.childStartedAtMs = Date.now();
+        const spawnedAtMs = this.childStartedAtMs;
+        this.publish({ state: LocalDevSupervisorState.RUNNING, childPid: child.pid ?? null, childStartedAt: new Date(spawnedAtMs).toISOString(), blocker: null });
+        // Uptime is taken when the child EXITS, not when the exit is handled: handling may wait out a decision that runs `lsof`
+        // or stops a process group, which would otherwise count as time the child stayed up.
+        child.once('exit', (code, signal) => void this.handleChildExitWhenFree(child, code, signal, Date.now() - spawnedAtMs));
+    }
+    async stopChild(graceMs) {
+        const child = this.child;
+        if (child === null)
+            return;
+        this.child = null;
+        this.expectedExit.add(child);
+        if (child.pid)
+            await terminateProcessGroup(child.pid, graceMs);
+    }
+    /** An exit is a decision too: it waits for a running poll to finish rather than interleave with it (see {@link busy}). */
+    async handleChildExitWhenFree(child, code, signal, uptimeMs) {
+        while (this.busy && !this.stopping)
+            await new Promise((resolve) => setTimeout(resolve, 20));
+        await this.serialized(() => this.handleChildExit(child, code, signal, uptimeMs));
+    }
+    async handleChildExit(child, code, signal, uptimeMs) {
+        if (this.expectedExit.has(child) || this.stopping)
+            return;
+        if (this.child === child)
+            this.child = null;
+        const started = child.pid ? readBackendStartRecordOfProcess(this.options.appRoot, child.pid) : undefined;
+        if (started?.outcome === BackendStartOutcome.FAILED && started.failureCause === BackendStartFailureCause.PORT_IN_USE && started.port) {
+            const holder = await identifyPortHolder(started.port);
+            // Never this supervisor's own current child: only a process it did not start can be an orphan or a foreigner.
+            const ownChild = holder !== null && holder.pid !== null && holder.pid === this.child?.pid;
+            if (holder !== null && !ownChild && holder.pid !== null && isOrphanedRuntimeOfPackage(holder, { packageRoot: this.options.packageRoot, entry: this.options.entry })) {
+                this.log(`port ${started.port} is held by a runtime an earlier dev run left behind (pid ${holder.pid}, parent ${holder.ppid ?? 'unknown'}, started ${holder.startedAt ?? 'unknown'}); stopping it and starting the current build`);
+                await terminateProcessGroup(holder.pid);
+                if (this.child === null)
+                    this.spawnChild();
+                return;
+            }
+            if (holder !== null && !ownChild) {
+                this.heldPort = started.port;
+                this.lastPortCheckAtMs = Date.now();
+                this.log(`a process this supervisor did not spawn holds port ${started.port}: pid ${holder.pid ?? 'unknown (lsof unavailable)'}, parent ${holder.ppid ?? 'unknown'}${holder.ppid === 1 ? ' (an orphan)' : ''}, `
+                    + `started ${holder.startedAt ?? 'unknown'}, cwd ${holder.cwd ?? 'unknown'}, command ${holder.command ?? 'unknown'}. `
+                    + 'The runtime is NOT running this tree. Stop that process (or restart `wildo local dev`); the runtime starts as soon as the port is free.');
+                this.publish({ state: LocalDevSupervisorState.PAUSED, childPid: null, blocker: LocalDevSupervisorBlocker.PORT_HELD_BY_FOREIGN_PROCESS, portHolder: holder });
+                return;
+            }
+        }
+        if (this.child !== null)
+            return;
+        // A crash while an install re-creates node_modules is the install's, not the runtime's (#3552): count nothing, and let
+        // the end of the install start it again with a fresh budget (see `applyDependencyInstall`).
+        if (classifyDependencyInstall(readDependencyInstallRecord(this.options.appRoot), Date.now()).phase === LocalDevDependencyInstallPhase.IN_FLIGHT) {
+            this.log(`the runtime exited (${signal ?? `code ${code}`}) while a dependency install is running; not counted, it starts again when the install ends`);
+            this.publish({ state: LocalDevSupervisorState.PAUSED, childPid: null, blocker: LocalDevSupervisorBlocker.DEPENDENCY_INSTALL_IN_FLIGHT });
+            return;
+        }
+        /*
+         * A child that STARTED (its own record says so) and later died is a fresh failure with a fresh budget. Uptime is not
+         * the test: a start refused after registry initialization takes twenty seconds, and counting that as healthy reset
+         * the budget at every attempt, so a backend that could never start was respawned forever. Uptime decides only for a
+         * child that left no record at all (#3257): a runtime with no runtime-signals home writes none, and would otherwise
+         * never reset its budget, so five crashes spread over a day would spend it.
+         */
+        const stayedUpWithoutStartRecord = started === undefined
+            && uptimeMs >= (this.options.healthyUptimeWithoutStartRecordMs ?? DEFAULT_HEALTHY_UPTIME_WITHOUT_START_RECORD_MS);
+        if (started?.outcome === BackendStartOutcome.STARTED || stayedUpWithoutStartRecord)
+            this.crashCount = 0;
+        this.crashCount += 1;
+        if (this.crashCount > CRASH_RESPAWN_MAX_ATTEMPTS && spentCrashBudgetPauses(started)) {
+            this.pausedAgainstBuildAtMs = assessRuntimeBuilds({
+                own: this.options.compileLoop.observation,
+                dependencies: this.readDependencyObservations(Date.now()),
+                dependencyGraceElapsed: true,
+            }).newestBuildAtMs;
+            this.log(`the runtime exited (${signal ?? `code ${code}`}) at ${this.crashCount} consecutive starts; paused until a package it loads publishes a newer build`);
+            this.publish({ state: LocalDevSupervisorState.PAUSED, childPid: null, blocker: LocalDevSupervisorBlocker.CRASH_RESPAWN_EXHAUSTED });
+            return;
+        }
+        const crashLoop = this.crashCount > CRASH_RESPAWN_MAX_ATTEMPTS;
+        const delayMs = Math.min(CRASH_RESPAWN_BASE_DELAY_MS * 2 ** (this.crashCount - 1), crashLoop ? CRASH_LOOP_MAX_DELAY_MS : CRASH_RESPAWN_MAX_DELAY_MS);
+        if (crashLoop) {
+            this.log(`the runtime exited (${signal ?? `code ${code}`}) at ${this.crashCount} consecutive starts, `
+                + `${describeCrashLoopCause(started)}; `
+                + `crash-loop backoff, restarting in ${Math.round(delayMs / 1000)}s (the delay doubles up to ${CRASH_LOOP_MAX_DELAY_MS / 60_000} min and never stops)`);
+            this.publish({ state: LocalDevSupervisorState.BACKOFF, childPid: null, blocker: LocalDevSupervisorBlocker.CRASH_LOOP_BACKOFF });
+        }
+        else {
+            this.log(`the runtime exited (${signal ?? `code ${code}`}); restarting in ${Math.round(delayMs / 1000)}s (${this.crashCount}/${CRASH_RESPAWN_MAX_ATTEMPTS})`);
+            this.publish({ state: LocalDevSupervisorState.BACKOFF, childPid: null, blocker: null });
+        }
+        this.backoffTimer = setTimeout(() => {
+            this.backoffTimer = null;
+            void this.serialized(() => this.decide());
+        }, delayMs);
+    }
+}
+//# sourceMappingURL=node-runtime-dev-supervisor.js.map