@vibesdotdev/pm 0.0.0-stage → 1.0.0-rc.2

package/dist/daemon.js

@@ -0,0 +1,1654 @@
+/**
+ * PM Daemon
+ * Long-lived process that manages all child processes via Unix socket IPC.
+ *
+ * Transport: the daemon is served by `runtime-rpc-unix` (three-verb protocol:
+ * invoke / release / stream). The legacy HTTP-over-unix `pm-command` wire is
+ * gone. Each pm-command maps to a method on the RPC root returned by
+ * `createPMRpcRoot()`; the PM client calls them via `connectUnix` + `wireConsumer`.
+ */
+import * as z from 'zod/v4';
+import { resolveFileSystemAdapter } from '@vibesdotdev/filesystem/client/resolve-adapter';
+import { chmodChecked } from '@vibesdotdev/filesystem/core';
+import { getRuntimeSocketService } from '@vibesdotdev/kernel/socket';
+import { ProcessManager } from "./manager.js";
+import { PmTaskScopeSchema, processExitOf } from "./schemas/process.js";
+import { getPMDaemonLogger, getPMDaemonStderrLogPath, getPMDaemonStdoutLogPath, PM_CAPTURE_ROTATION_POLICY, readPMDaemonLogTail } from "./utils/logging.js";
+import { isManagedProcessId } from "./helpers/managed-process-id.js";
+import { createProcessRunArchiver } from "./services/process-log-archive.js";
+import { MIN_ACCEPTABLE_NOFILE, RECOMMENDED_NOFILE, fileDescriptorLimitRemediation, readFileDescriptorLimit } from "./helpers/rlimits.js";
+import { ResourceManager } from "./managers/resource-manager.js";
+import { PresetExecutor } from "./managers/preset-executor.js";
+import { ResourceProviderRegistry } from "./resources/index.js";
+import { ProcessStore } from "./store.impl.consumer.js";
+import { getPMSocketPath, getSocketBasePath } from "./utils/socket-paths.js";
+import { getPathRoots, getRuntimePath } from '@vibesdotdev/paths';
+import { checkProcessLiveness } from "./utils/liveness.js";
+import { isProcessRunning } from "./utils/process-tree.js";
+import { removeSocket } from "./utils/socket.js";
+import { getVibesDir } from "./utils/vibes-home.js";
+import { ConfigWatcher } from "./daemon/config-watcher.js";
+import { OrphanScanner } from "./daemon/orphan-scanner.js";
+import { HealthMonitor } from "./daemon/health-monitor.js";
+import { ExecutableFreshnessReconciler } from "./daemon/executable-freshness-reconciler.js";
+import { LivenessChecker } from "./daemon/liveness-checker.js";
+import { LivenessProfiles } from "./services/liveness-state.js";
+import { FleetAttachState } from "./daemon/fleet-attach-state.js";
+import { mayRestart, readSupervision, restartDelayMs } from "./services/supervision-policy.js";
+import { CapabilityError, CaughtFailureSchema, DefaultInvokePipeline, getRuntimeHostSignals, getRuntimeHostIdentity, isCapabilityError, valueFreeFailure } from '@vibesdotdev/kernel';
+import { pmRpcResult } from "./daemon/rpc-result.js";
+import { attempt, attemptSync, failureText } from "./utils/attempt.js";
+import { hasErrnoCode } from "./utils/errno-failure.js";
+import { listenUnix } from '@vibesdotdev/kernel-rpc/unix';
+import { ResourceHealthMonitor } from "./daemon/resource-health-monitor.js";
+import { CommandDispatcher } from "./daemon/command-handler.js";
+import { readPMRole } from "./daemon/role.js";
+import { createPMDaemonModuleContext } from "./daemon/daemon-module-context.js";
+import { startRuntimeHostHotReload } from "./kinds/runtime-daemon-endpoint.js";
+import { PM_COMMAND_IDS } from "./daemon/command-ids.js";
+import { admittedWorkspaceIdentity } from "./admission.js";
+// The PID file has ONE owner (`./utils/daemon-pid.ts`), so a surface that needs
+// only the daemon's pid — `vibes update`'s roll census — can read it without
+// importing this module's process manager, RPC transport and resource registry.
+import { getDaemonPidPath, readDaemonPid } from "./utils/daemon-pid.js";
+import { readRotationMaxAge, readRotationPolicy, rotateAppendedFile } from '@vibesdotdev/logging';
+import { canConnectToPMSocket } from "./utils/daemon-reachability.js";
+export { getDaemonPidPath, readDaemonPid } from "./utils/daemon-pid.js";
+export { isDaemonReachable, isDaemonRunning, probeDaemon } from "./utils/daemon-reachability.js";
+/**
+ * Statuses that record a finished run rather than assert a live process.
+ * Boot reconcile must leave these alone — see `reconcileState`.
+ */
+const TERMINAL_STATUSES = new Set([
+    'pass',
+    'fail',
+    'completed'
+]);
+async function rotateEach(runtime, entries, policy) {
+    const result = { rotated: [], failed: [] };
+    for (const { processId, path } of entries) {
+        const rotation = await attempt(() => rotateAppendedFile(runtime, path, policy));
+        if (!rotation.ok) {
+            result.failed.push({ processId, path, error: rotation.failure });
+        }
+        else if (rotation.value.rotated) {
+            result.rotated.push({ processId, path, previousSize: rotation.value.previousSize ?? 0 });
+        }
+    }
+    return result;
+}
+/**
+ * Process log rotation for LIVE writers: every running child's
+ * `<id>.stdout` / `<id>.stderr` and the daemon's own stdio logs, by the
+ * logging owner's `rotateAppendedFile` (copy+truncate, because each writer
+ * holds an O_APPEND fd) under the declared `pm.process-capture` policy.
+ * Start-time rotation uses the same call and policy, so the two can never
+ * drift apart on threshold or generation count (L1).
+ */
+export async function rotateOversizedProcessLogs(options) {
+    const runtimePath = await getRuntimePath(options.runtime);
+    const entries = [];
+    for (const processId of options.processIds) {
+        for (const stream of ['stdout', 'stderr']) {
+            entries.push({ processId, path: runtimePath.join(options.logDir, `${processId}.${stream}`) });
+        }
+    }
+    return rotateEach(options.runtime, entries, options.policy);
+}
+/**
+ * The daemon's own stdio logs, rotated in steady state (pm.md D17): the
+ * paths `getPMDaemon{Stdout,Stderr}LogPath` name under the daemon's roots,
+ * never its process log dir (which never held them). `pm-daemon.log` is the
+ * `pm-daemon` logging output and is rotated by its owner, not here.
+ */
+export async function rotateOversizedDaemonLogs(options) {
+    const pathOptions = { roots: options.roots, runtimePath: await getRuntimePath(options.runtime) };
+    return rotateEach(options.runtime, [
+        { processId: 'pm-daemon', path: getPMDaemonStdoutLogPath(options.workspace, pathOptions) },
+        { processId: 'pm-daemon', path: getPMDaemonStderrLogPath(options.workspace, pathOptions) }
+    ], options.policy);
+}
+/**
+ * The version of THIS loaded module's package (its `package.json` beside
+ * the module's own directory), read once on first use. Genuinely module-scoped: it is
+ * an immutable fact of the module instance, identical for every runtime that
+ * loaded it, and a hot-reload generation loads a new module instance with its
+ * own. A later rewrite of the file on disk does not change the code running
+ * here, so the first read stays the true answer.
+ */
+let cachedVersion;
+const FileTextSchema = z.string();
+/** A file's content, or null when it does not exist (ENOENT); any other read failure propagates. */
+async function readIfPresent(files, path) {
+    const read = await attempt(async () => FileTextSchema.parse(await files.readFile(path, 'utf-8')));
+    if (read.ok)
+        return read.value;
+    if (hasErrnoCode(read.failure) && read.failure.code === 'ENOENT')
+        return null;
+    throw read.failure;
+}
+/** The package manifest fields PM reads: its version. */
+const PackageVersionSchema = z.object({ version: z.string().optional() });
+async function getPMVersion(runtime) {
+    if (cachedVersion)
+        return cachedVersion;
+    // A compiled host carries no package.json beside the module (ENOENT): its
+    // version is reported as 0.0.0. Any other read or parse failure propagates.
+    const runtimePath = await getRuntimePath(runtime);
+    const packageJsonPath = runtimePath.fileURLToPath(new URL('../package.json', import.meta.url));
+    const content = await readIfPresent(await resolveFileSystemAdapter(runtime, { binding: false }), packageJsonPath);
+    if (content === null) {
+        cachedVersion = '0.0.0';
+        return cachedVersion;
+    }
+    cachedVersion = PackageVersionSchema.parse(JSON.parse(content)).version ?? '0.0.0';
+    return cachedVersion;
+}
+const RpcMethodNameSchema = z.string();
+/**
+ * One connection's PM RPC root. Each command carries the connection's close
+ * signal, so an observation command (`await-exit`) whose caller left ends
+ * instead of waiting on (runtime-rpc rule 19).
+ */
+function createPMRpcRoot(dispatcher, connection) {
+    const target = {};
+    // A dynamic Proxy that catches any method name and routes it through the
+    // CommandDispatcher — we don't enumerate the 40+ commands here; the registry
+    // owns the method set.
+    return new Proxy(target, {
+        get(_target, prop) {
+            return async (params) => {
+                return pmRpcResult(async () => {
+                    const result = await dispatcher.handleCommand({
+                        type: 'pm-command',
+                        command: prop,
+                        ...params
+                    }, { signal: connection.signal });
+                    return { success: true, ...result };
+                });
+            };
+        },
+        has(_target, prop) {
+            // Report all string properties as present so the socket listener doesn't
+            // throw "root has no method" for any registered command.
+            return RpcMethodNameSchema.safeParse(prop).success;
+        }
+    });
+}
+/**
+ * The PM daemon runs only on its own serve host: the host the CLI booted for
+ * `pm daemon serve`, which declared `qualifiers.serve = 'pm.daemon.serve'` and
+ * so answers `pm/role = 'daemon'`. That declaration is the recursion guard
+ * (D13): every in-process PM client of the host has `autoStartDaemon: false`,
+ * so nothing the daemon serves can launch another daemon. A host without it
+ * would hand the daemon's own commands clients that auto-start a daemon, so
+ * it is refused before the daemon touches anything.
+ */
+export async function assertPMDaemonServeHost(runtime) {
+    if ((await readPMRole(runtime)) === 'daemon')
+        return;
+    throw new CapabilityError("The PM daemon runs only on the host booted for 'pm daemon serve' " +
+        "(qualifiers.serve 'pm.daemon.serve'); this host's PM clients could auto-start a daemon.", 'INVALID_INPUT', {
+        reason: 'pm-daemon-host-undeclared',
+        recoveryHint: "Start it with 'vibes pm daemon start' or 'vibes pm daemon serve'."
+    });
+}
+/** How long a managed child gets to exit on SIGTERM when the daemon stops, before SIGKILL. */
+const MANAGED_STOP_GRACE_MS = 3000;
+export class PMDaemon {
+    pm;
+    rm;
+    executor;
+    store;
+    liveness;
+    /** This daemon's attached fleet receivers (never a module singleton). */
+    fleet = new FleetAttachState();
+    rpcListener;
+    socketPath;
+    runtimePath;
+    /** The serve host runtime; replaced by hot reload's stable dispatch handle once armed. */
+    runtime;
+    /** `getPathRoots(runtime)` of the serve host, captured at construction. */
+    roots;
+    pidFile;
+    cleanupTimer;
+    healthCheckTimer;
+    livenessCheckTimer;
+    idleSweepIntervalMs;
+    healthCheckIntervalMs;
+    livenessCheckIntervalMs;
+    maxHealthCheckRetries;
+    initialBackoffDelay;
+    maxBackoffDelay;
+    minHealthFailuresBeforeKill = 3;
+    logger;
+    workspaceRoot;
+    // Where the 'global' ProcessManager writes `<id>.stdout` / `<id>.stderr`;
+    // the periodic sweep rotates live processes' logs here (see
+    // rotateOversizedProcessLogs). Same resolver ProcessManager('global') uses.
+    processLogDir;
+    // Track daemon start time for uptime calculation
+    startTime;
+    // Extracted modules
+    configWatcher;
+    orphanScanner;
+    healthMonitor;
+    livenessChecker;
+    executableFreshnessReconciler;
+    executableFreshnessTimer;
+    resourceHealthMonitor;
+    commandDispatcher;
+    hotReload;
+    /** Releases the generation-publication subscription (see start()). */
+    unsubscribeGeneration;
+    // Resource health check timer
+    resourceHealthCheckTimer;
+    orphanScanTimer;
+    resourceHealthCheckIntervalMs = 10000; // 10 seconds
+    // Pid-file heartbeat + supersession self-check (daemon-leak fix, work item
+    // c74e83a7-44bc-4281-8481-a76642ff5752). See start() for why both exist.
+    pidHeartbeatTimer;
+    supersessionTimer;
+    supersessionStrikes = 0;
+    pidHeartbeatIntervalMs = 60_000;
+    supersessionCheckIntervalMs = 15_000;
+    // Resolves start()'s keep-alive promise from stop() so programmatic
+    // callers of start() get control back instead of parking forever.
+    keepAliveResolve;
+    stopping;
+    stopFailed = false;
+    /**
+     * A supervisor tick owned by the serve host's lifecycle (RC07): disposed
+     * by `stop()` and by the runtime's disposal. The daemon host is not
+     * `finite`, so a lifecycle interval is admitted.
+     */
+    tick(name, intervalMs, run) {
+        return this.runtime.lifecycle.interval(() => {
+            void this.runTick(name, run);
+        }, intervalMs);
+    }
+    /** One supervisor tick: a failure is reported, never thrown (nothing awaits a tick). */
+    async runTick(name, run) {
+        const ran = await attempt(run);
+        if (!ran.ok)
+            this.logger.error(`${name} failed`, { failure: valueFreeFailure(ran.failure) });
+    }
+    /** Remove a stale socket file during reconcile; a failure is reported and reconcile continues. */
+    /**
+     * Remove a dead process's socket through the runtime socket service. True
+     * only when the socket was there and is now removed; a refused removal (a
+     * listener still bound, a non-socket inode, an unreadable owner) is logged
+     * and reported false, never counted as removed.
+     */
+    async removeStaleSocket(processId, socketPath) {
+        const socketService = await getRuntimeSocketService(this.runtime);
+        const removal = await attempt(async () => {
+            if (!(await socketService.inspectLocal(socketPath)).exists)
+                return false;
+            await socketService.removeLocal(socketPath);
+            return true;
+        });
+        if (!removal.ok) {
+            this.logger.warn('stale socket removal failed', { processId, socketPath, failure: valueFreeFailure(removal.failure) });
+            return false;
+        }
+        if (!removal.value)
+            return false;
+        return !(await socketService.inspectLocal(socketPath)).exists;
+    }
+    /** Dispose every supervisor tick. */
+    stopTicks() {
+        const failures = [];
+        for (const dispose of [
+            this.cleanupTimer,
+            this.healthCheckTimer,
+            this.livenessCheckTimer,
+            this.executableFreshnessTimer,
+            this.resourceHealthCheckTimer,
+            this.orphanScanTimer,
+            this.pidHeartbeatTimer,
+            this.supersessionTimer
+        ]) {
+            const stopped = attemptSync(() => dispose?.());
+            if (!stopped.ok)
+                failures.push(stopped.failure);
+        }
+        this.cleanupTimer = undefined;
+        this.healthCheckTimer = undefined;
+        this.livenessCheckTimer = undefined;
+        this.executableFreshnessTimer = undefined;
+        this.resourceHealthCheckTimer = undefined;
+        this.orphanScanTimer = undefined;
+        this.pidHeartbeatTimer = undefined;
+        this.supersessionTimer = undefined;
+        if (failures.length === 1)
+            throw failures[0];
+        if (failures.length > 1)
+            throw new AggregateError(failures, 'PM supervisor timer disposal failed.');
+    }
+    waitForStop() {
+        return new Promise((resolve) => {
+            this.keepAliveResolve = resolve;
+        });
+    }
+    // Agent-ops daemon modules — resolved at boot via runtime.query('pm/daemon-module')
+    // rather than hardcoded. Feature packages (e.g. @vibesdotdev/os) register tick/watch
+    // sources here; PM owns the surface, not the modules.
+    daemonModules = [];
+    // Track required modules that fail to start, with retry state
+    degradedModules = new Map();
+    // Reconcile runtime state with reality on boot
+    async reconcileState() {
+        const states = await this.store.getAll();
+        const summary = {
+            scanned: states.length,
+            updated: 0,
+            stopped: 0,
+            clearedSocketPath: 0,
+            removedSocketFiles: 0
+        };
+        for (const state of states) {
+            const sameObservation = (current) => current.status === state.status && current.pid === state.pid &&
+                current.startedAt?.getTime() === state.startedAt?.getTime();
+            // An owed terminal receipt is exact evidence, including its PID and time.
+            // Boot liveness reconciliation may not rewrite the admitted generation.
+            const generation = state.startedAt?.getTime();
+            if (generation !== undefined && processExitOf(state) && (await this.store.taskObligations(state.id)).some(entry => entry.startedAt === generation))
+                continue;
+            const config = await this.pm.getConfig(state.id);
+            const updates = {};
+            // A finite task's outcome is a RECORD, not a liveness claim. `pass`,
+            // `fail` and `completed` are terminal: the process is *supposed* to be
+            // gone. Reconciling them against "is the pid alive?" stomped every
+            // task result to `stopped` on each daemon boot, which silently broke
+            // `requiresPass` — an already-applied migration looked never-run, so
+            // its dependents refused to start until someone re-ran it by hand.
+            if (TERMINAL_STATUSES.has(state.status)) {
+                if (state.socketPath) {
+                    if (await this.removeStaleSocket(state.id, state.socketPath))
+                        summary.removedSocketFiles += 1;
+                    updates.socketPath = undefined;
+                    summary.clearedSocketPath += 1;
+                }
+                if (state.pid !== undefined && !(await isProcessRunning(this.runtime, state.pid))) {
+                    updates.pid = undefined;
+                }
+                if (Object.keys(updates).length > 0) {
+                    await this.store.withProcessAdmission(state.id, async () => {
+                        if (generation !== undefined && (await this.store.taskObligations(state.id)).some(entry => entry.startedAt === generation))
+                            return;
+                        if (await this.store.updateWhen(state.id, updates, sameObservation))
+                            summary.updated += 1;
+                    });
+                }
+                continue;
+            }
+            // If config no longer declares a socket, clear any stale socketPath
+            if (!config?.socket && state.socketPath) {
+                updates.socketPath = undefined;
+                summary.clearedSocketPath += 1;
+            }
+            // Verify the process is really alive; if not, clean up and mark stopped
+            const livenessResult = await checkProcessLiveness(this.runtime, state);
+            const alive = livenessResult.alive;
+            if (!alive) {
+                // The liveness strategy for socket-backed processes requires BOTH
+                // PID and socket. A missing/unreachable socket flips `alive=false`
+                // even when the PID (and its entire subprocess tree) is still
+                // running. Killing the tree and deleting the socket on that false
+                // negative destroys a genuinely live process — e.g. an orphaned
+                // runtime daemon whose projection socket hasn't been (re)created
+                // yet. `checkProcessLiveness` already probed the pid directly
+                // (`isPIDAlive`), so reuse that verdict: only reap and clean up
+                // when the pid itself is confirmed dead. A live-but-socketless
+                // process is left alone here — repair (autostart, health
+                // monitor), never delete — instead of us destroying its state.
+                if (livenessResult.details.pidAlive === true) {
+                    this.logger.warn('reconcile: liveness failed but pid is still alive (socket unreachable or missing) — leaving state and socket alone for repair, not killing', { processId: state.id, pid: state.pid, socketPath: state.socketPath });
+                }
+                else {
+                    if (state.socketPath && (await this.removeStaleSocket(state.id, state.socketPath))) {
+                        summary.removedSocketFiles += 1;
+                    }
+                    updates.status = 'stopped';
+                    updates.pid = undefined;
+                    updates.stoppedAt = new Date();
+                    updates.lastError = 'Reconciled: process not running';
+                }
+            }
+            if (Object.keys(updates).length > 0) {
+                if (await this.store.updateWhen(state.id, updates, sameObservation)) {
+                    summary.updated += 1;
+                    if (updates.status === 'stopped')
+                        summary.stopped += 1;
+                }
+            }
+        }
+        return summary;
+    }
+    constructor(config) {
+        this.startTime = Date.now();
+        const workspaceIdentity = admittedWorkspaceIdentity(config.workspaceRoot);
+        this.workspaceRoot = workspaceIdentity.workspacePath;
+        const toolingId = workspaceIdentity.toolingId;
+        this.runtimePath = config.runtimePath;
+        this.runtime = config.runtime;
+        this.roots = getPathRoots(config.runtime);
+        this.socketPath =
+            config.socketPath ||
+                getPMSocketPath(toolingId, { roots: this.roots, runtimePath: config.runtimePath });
+        this.pidFile = config.pidFile || getDaemonPidPath(toolingId, { roots: this.roots, runtimePath: config.runtimePath });
+        this.idleSweepIntervalMs = config.idleSweepInterval || 60 * 1000;
+        this.healthCheckIntervalMs = config.healthCheckInterval || 30 * 1000;
+        this.livenessCheckIntervalMs = config.livenessCheckInterval || 10 * 1000;
+        this.maxHealthCheckRetries = config.maxHealthCheckRetries || 10;
+        this.initialBackoffDelay = config.initialBackoffDelay || 1000;
+        this.maxBackoffDelay = config.maxBackoffDelay || 30 * 1000;
+        // Initialize descriptor-driven daemon logger
+        this.logger = getPMDaemonLogger(this.runtime, 'global');
+        // Create shared store, partitioned by the daemon's ADMITTED workspace
+        // identity rather than ambient re-derivation — see
+        // store.impl.consumer.ts getBasePath / ProcessStoreOptions.workspaceToolingId.
+        this.store = new ProcessStore({ scope: 'global', roots: this.roots, workspaceToolingId: toolingId }, this.runtime);
+        // The admitted workspace's active liveness profiles, persisted in its
+        // pm-state.db; loaded in start() before the daemon serves (U-RC03-1).
+        this.liveness = new LivenessProfiles(this.store, () => this.runtime);
+        // Create resource manager
+        // Providers resolve from this daemon's runtime (`pm/resource-provider`:
+        // PM's builtins from the pm plugin, a workspace's or feature's own).
+        this.rm = new ResourceManager(this.store, new ResourceProviderRegistry(() => this.runtime), () => this.runtime);
+        // The scope this daemon declares (framework-M8): its admitted workspace
+        // and the host runtime's homes. It alone proves a port holder ours before
+        // PM signals anything; nothing reads this process's env or cwd for it.
+        const roots = this.roots;
+        const daemonScope = {
+            workspaceRoot: this.workspaceRoot,
+            vibesHome: roots.vibesHome,
+            userHome: roots.userHome
+        };
+        // Create process manager with resource manager
+        // Share the daemon's store so one run-end archive (below) sees the health
+        // monitor's and liveness checker's writes, not only lifecycle's.
+        this.pm = new ProcessManager('global', this.rm, {
+            getRuntime: () => this.runtime,
+            workspaceRoot: this.workspaceRoot,
+            store: this.store,
+            runtimePath: config.runtimePath,
+            daemonScope,
+            livenessProfile: (scopeKey) => this.liveness.get(scopeKey)
+        });
+        // The manager owns the (workspace-keyed) directory its processes write to.
+        this.processLogDir = this.pm.processLogDir;
+        // Lifecycle truncates `<id>.stdout`/`<id>.stderr` on every start; keep
+        // the run that just ended (its tail plus an exit banner) in `.1`.
+        this.store.onRunEnd(createProcessRunArchiver({
+            getRuntime: () => this.runtime,
+            logDir: this.processLogDir,
+            pendingInitiator: (processId) => this.pm.pendingRunEndInitiator(processId),
+            onArchived: (info) => this.logger.info('archived previous run logs', { ...info }),
+            onFailed: (info) => this.logger.warn('previous run log archive failed', {
+                processId: info.processId,
+                failed: info.failed.map((entry) => ({
+                    path: entry.path,
+                    failure: valueFreeFailure(entry.failure)
+                }))
+            })
+        }));
+        // Create preset executor
+        this.executor = new PresetExecutor(this.pm, this.rm, () => this.runtime);
+        // Create config watcher
+        this.configWatcher = new ConfigWatcher({
+            pm: this.pm,
+            rm: this.rm,
+            getCwd: () => this.workspaceRoot,
+            getRuntime: () => this.runtime,
+            getLivenessProfile: (scopeKey) => this.liveness.get(scopeKey),
+            getFleetProxy: (scope) => this.fleet.get(scope)
+        });
+        // Create orphan scanner
+        this.orphanScanner = new OrphanScanner({
+            getRuntime: () => this.runtime,
+            store: this.store,
+            pm: this.pm,
+            daemonScope
+        });
+        // Create health monitor
+        this.healthMonitor = new HealthMonitor({
+            getRuntime: () => this.runtime,
+            pm: this.pm,
+            store: this.store,
+            minHealthFailuresBeforeKill: this.minHealthFailuresBeforeKill
+        });
+        // Create liveness checker
+        this.livenessChecker = new LivenessChecker({
+            getRuntime: () => this.runtime,
+            pm: this.pm,
+            store: this.store
+        });
+        // Roll managed processes (and hand this daemon off) when the vibes
+        // executable on disk is replaced after they started — otherwise every
+        // daemon keeps executing a deleted inode until something kills it.
+        this.executableFreshnessReconciler = new ExecutableFreshnessReconciler({
+            getRuntime: () => this.runtime,
+            pm: this.pm,
+            selfStartedAtMs: this.startTime
+        });
+        // Create resource health monitor
+        this.resourceHealthMonitor = new ResourceHealthMonitor({
+            pm: this.pm,
+            rm: this.rm,
+            getRuntime: () => this.runtime
+        });
+        // Create command dispatcher
+        this.commandDispatcher = new CommandDispatcher({
+            liveness: this.liveness,
+            fleet: this.fleet,
+            pm: this.pm,
+            rm: this.rm,
+            executor: this.executor,
+            configWatcher: this.configWatcher,
+            getHealth: () => this.getHealth(),
+            reconcileState: () => this.reconcileState(),
+            requestHandoff: () => {
+                this.runtime.lifecycle.timeout(() => {
+                    void this.requestStop('rpc-handoff', 'handoff');
+                }, 0);
+            },
+            requestShutdown: config.requestShutdown ??
+                (() => {
+                    // Let runtime-rpc-unix finish the accepted response before
+                    // PM drains children, persists state, and removes daemon
+                    // artifacts. Do not bounce through a process signal here:
+                    // compiled CLI hosts may still own a fast-exit signal
+                    // handler that bypasses PM's asynchronous cleanup.
+                    this.runtime.lifecycle.timeout(() => {
+                        void this.requestStop('rpc');
+                    }, 0);
+                })
+        }, config.runtime);
+        // Agent-ops daemon modules are NOT constructed here. They are resolved
+        // from the runtime in start() so PM stays decoupled from the feature
+        // packages that register them (RESOLVE, DON'T IMPORT).
+    }
+    /**
+     * Start the daemon
+     */
+    async start() {
+        const runtime = this.runtime;
+        await assertPMDaemonServeHost(runtime);
+        await this.hostPid();
+        const executable = (await getRuntimeHostIdentity(this.runtime)).captureExecutableIdentity();
+        const executablePath = executable === null ? null : z.object({ path: z.string().min(1) }).safeParse(executable);
+        if (executablePath !== null && !executablePath.success) {
+            throw new CapabilityError('The selected host supplied an invalid executable identity.', 'INVALID_INPUT', {
+                reason: 'host-identity-invalid', retryable: false
+            });
+        }
+        this.logger.info('starting');
+        // Liveness profiles are read synchronously by every spawn; load them
+        // before anything below (a generation reconcile included) can start a
+        // process or accept a command.
+        await this.liveness.load();
+        // Hot reload is armed on the serve host itself. Its `runtime` is a stable
+        // dispatch handle that follows every published generation, so the daemon
+        // holds it from here on.
+        // Optional: a runtime that composes no runtime daemon endpoint (or one
+        // without host hot reload) serves without it, and says so once.
+        const hot = await startRuntimeHostHotReload(runtime, { installedUpdates: true, log: this.logger });
+        if (!hot) {
+            this.logger.info('host hot reload not started: no runtime daemon endpoint with hot reload is registered');
+        }
+        else if (hot.enabled) {
+            this.hotReload = hot;
+            this.runtime = hot.runtime;
+            this.commandDispatcher.setRuntime(hot.runtime);
+            // Each published generation re-ran the kernel's discovery pass
+            // (rc02-rc03 §2.5); reconcile PM's registrations from it. PM runs
+            // no discovery of its own.
+            this.unsubscribeGeneration = hot.runtime.onGenerationChange(() => {
+                // A waiting observation must not pin the retired generation: it
+                // answers `interrupted` and its client re-issues on this one.
+                this.commandDispatcher.interruptObservations('generation');
+                return this.configWatcher.reconcileOnGeneration();
+            });
+        }
+        // Ensure directories exist and have sane perms before PID/socket
+        await this.ensurePathPermissions();
+        await this.cleanupStalePidIfNeeded();
+        await this.cleanupStaleSocketIfNeeded();
+        // A daemon signals only processes it started (SPEC hard rule; pm.md D3):
+        // other workspaces' daemons are never reaped here. Strays are reported by
+        // `vibes pm daemon reconcile` (daemon/stray-daemons.ts) and stopped through
+        // their own daemon's RPC.
+        await this.reconcileState();
+        // Scan for and cleanup orphaned sockets from previous daemon sessions
+        await this.orphanScanner.scanForOrphanedSockets();
+        // A reachable PM socket must already own the workspace's discovered
+        // process registry. Native consumers use typed RPC directly and cannot
+        // be required to replay CLI-only config registration before `start`.
+        //
+        // Resilient by design: one malformed descriptor (e.g. an app's
+        // *.pm.process.ts that omits `command`) must not take the whole daemon —
+        // and every other app — down with it. reconcileConfig already logs and
+        // skips each rejected config; startup proceeds with the ones that
+        // validated. Strict validation is `vibes pm validate`, not a startup crash.
+        const startupReconciliation = await this.configWatcher.reconcileConfig();
+        if (startupReconciliation.failed.length > 0) {
+            this.logger.warn('daemon started with rejected process configs (skipped)', {
+                rejected: startupReconciliation.failed
+            });
+        }
+        // The orphan scanner matches observed processes against registered
+        // configs (adoption, port ownership). Give it the registry now that
+        // startup reconciliation has populated it; every scan tick re-syncs.
+        await this.syncOrphanScannerConfigs();
+        // Required feature modules are part of startup truth. Their process
+        // admission must succeed before PM publishes a reachable RPC socket.
+        await this.startDaemonModules('required');
+        // Write PID file
+        await this.writePidFile();
+        // Wire the runtime-rpc-unix LISTEN side.
+        // The PM RPC root wraps every pm-command handler; arriving RpcInvoke frames
+        // are routed by method name to the CommandDispatcher (no named-command registry
+        // string; each method IS the command name).
+        const dispatcher = this.commandDispatcher;
+        const listening = await attempt(() => listenUnix(this.socketPath, {
+            connectionRoot: (connection) => createPMRpcRoot(dispatcher, connection),
+            // The PM root serves exactly its stable wire commands (the client's list).
+            rootMethods: PM_COMMAND_IDS,
+            pipeline: new DefaultInvokePipeline(),
+            classifyResult: () => ({ mode: 'inline' }),
+            bindChannel: () => null,
+            kindOf: () => 'pm/daemon'
+        }, { runtime: this.runtime }));
+        if (!listening.ok) {
+            // listenUnix throws when the socket path is already bound (EADDRINUSE).
+            // This is a fatal singleton violation — the socket check above should
+            // have caught it, but if it didn't, die loudly instead of silently.
+            const message = failureText(listening.failure);
+            this.logger.error('failed to bind daemon socket', {
+                socketPath: this.socketPath,
+                failure: valueFreeFailure(listening.failure)
+            });
+            // Clean up the PID file we just wrote so the next launcher doesn't
+            // think *this* process is the incumbent.
+            // The bind failure below stays the error; a failed pid cleanup is reported beside it.
+            const cleaned = await attempt(() => this.removePidFile());
+            if (!cleaned.ok) {
+                this.logger.warn('pid file cleanup after bind failure failed', { failure: valueFreeFailure(cleaned.failure) });
+            }
+            throw new CapabilityError(`Cannot bind PM daemon socket ${this.socketPath}: ${message}. ` +
+                `Another daemon may already be running. ` +
+                `Use 'vibes pm daemon restart' if you need to replace it.`, 'CONFLICT', { reason: 'pm-daemon-socket-bind-failed', details: { socketPath: this.socketPath }, cause: listening.failure });
+        }
+        this.rpcListener = listening.value;
+        // Set socket permissions (owner-only, same as before)
+        this.logger.info('listening (rpc-unix)', { socketPath: this.socketPath });
+        // Start idle process cleanup timer
+        this.cleanupTimer = this.tick('scheduled cleanup', this.idleSweepIntervalMs, () => this.runScheduledCleanup());
+        // Start health check timer (runs every 1s, but respects per-process intervals)
+        this.healthCheckTimer = this.tick('health check tick', 1000, () => this.healthMonitor.runHealthChecks());
+        this.logger.info('health check loop enabled', { tickIntervalMs: 1000 });
+        // Start liveness check timer
+        this.livenessCheckTimer = this.tick('liveness check', this.livenessCheckIntervalMs, () => this.livenessChecker.runLivenessChecks());
+        this.logger.info('liveness monitoring enabled', {
+            intervalMs: this.livenessCheckIntervalMs
+        });
+        // Executable freshness: one stale child rolled per tick, daemon handoff last.
+        const executableFreshnessIntervalMs = 30_000;
+        this.executableFreshnessTimer = this.tick('executable freshness tick', executableFreshnessIntervalMs, () => this.executableFreshnessReconciler.tick());
+        this.logger.info('executable freshness reconciler enabled', {
+            intervalMs: executableFreshnessIntervalMs,
+            executable: executablePath?.data.path ?? null,
+            optOut: 'VIBES_PM_EXECUTABLE_FRESHNESS=0'
+        });
+        // Pid-file heartbeat. The client's staleness heuristic
+        // (client.ts cleanupStaleDaemonArtifacts) treats a pid file older than
+        // 5 minutes as evidence the unreachable daemon is dead. The pid file
+        // used to be written once at startup, so after 5 minutes of UPTIME any
+        // daemon that missed a single 750ms reachability probe on a busy
+        // machine was culled-by-unlink and replaced — while the old process
+        // lived on. Refreshing mtime makes age measure LIVENESS, not uptime.
+        // A failed heartbeat is logged at error (not debug): a pid file that
+        // stops refreshing gets this daemon culled as dead.
+        this.pidHeartbeatTimer = this.tick('pid heartbeat', this.pidHeartbeatIntervalMs, () => this.heartbeatPidFile());
+        // Supersession self-check. If the pid file no longer names this process
+        // or the socket file is gone, another daemon has taken over (or an
+        // operator culled our artifacts). Exit instead of looping forever as an
+        // orphan — this is the backstop that makes daemon zombies structurally
+        // impossible regardless of who unlinks what (340 leaked daemons were
+        // found doing exactly that, all PID-1-parented with live timers).
+        this.supersessionTimer = this.tick('supersession check', this.supersessionCheckIntervalMs, async () => {
+            if (await this.tickSupersession())
+                await this.exitSuperseded();
+        });
+        // Start orphan scanner - runs every 30 seconds initially, then 60s during steady-state
+        // CRITICAL FIX (Issue 4.3): Reduce scan frequency after warmup to save CPU
+        const warmupOrphanScanInterval = 30000; // 30 seconds during first 5 minutes
+        const steadyStateOrphanScanInterval = 60000; // 60 seconds during steady-state
+        const currentOrphanScanInterval = warmupOrphanScanInterval;
+        this.orphanScanTimer = this.tick('orphan scan', warmupOrphanScanInterval, () => this.runOrphanScan());
+        // After the 5-minute warmup the warmup tick is replaced by the steady-state one.
+        const switchToSteadyState = this.runtime.lifecycle.timeout(() => {
+            this.orphanScanTimer?.();
+            this.orphanScanTimer = this.tick('orphan scan', steadyStateOrphanScanInterval, () => this.runOrphanScan());
+            this.logger.info('orphan scanner switched to steady-state interval', {
+                intervalMs: steadyStateOrphanScanInterval
+            });
+        }, 5 * 60 * 1000);
+        const warmupTick = this.orphanScanTimer;
+        this.orphanScanTimer = () => {
+            switchToSteadyState();
+            warmupTick();
+        };
+        this.logger.info('orphan scanner enabled', { intervalMs: currentOrphanScanInterval });
+        // Start resource health check timer
+        this.resourceHealthCheckTimer = this.tick('resource health check', this.resourceHealthCheckIntervalMs, () => this.resourceHealthMonitor.runResourceHealthChecks());
+        this.logger.info('resource health monitoring enabled', {
+            intervalMs: this.resourceHealthCheckIntervalMs
+        });
+        // PM watches no config file (pm.md D2): each published runtime generation
+        // reconciles the graph (`reconcileOnGeneration`, subscribed above).
+        // Resolve and start agent-ops daemon modules registered as
+        // `pm/daemon-module` descriptors (e.g. @vibesdotdev/os channel
+        // scheduler, surface watcher, platform channel sync). PM owns the
+        // surface; feature packages register the modules. Optional modules stay
+        // isolated from each other and from daemon availability.
+        await this.startDaemonModules('optional');
+        // Keep the daemon alive until stop() resolves this. main() never
+        // calls stop() (process exit is its terminator), but a programmatic
+        // caller of start() now gets control back on stop() instead of
+        // parking on a never-resolving promise.
+        await this.waitForStop();
+    }
+    /**
+     * Resolve every enabled `pm/daemon-module` from the runtime and start it.
+     * Tolerates an unbootstrapped runtime (tests, isolated construction) by
+     * starting zero modules — mirroring mountRegisteredEndpoints() in
+     * pm.daemon.serve.impl.ts. Modules are sorted by `priority` (higher first)
+     * so ordering-sensitive tick sources can declare a start order.
+     *
+     * Required modules that fail to start are added to degradedModules and
+     * restarted on the declared `supervision.daemonModule` policy (RC11 class:
+     * supervision of what the daemon owns; default 15s doubling to 5m, never
+     * giving up). The daemon continues starting; it does NOT throw for
+     * required module failures.
+     */
+    async startDaemonModules(mode) {
+        const started = await attempt(() => this.startResolvedModules(mode));
+        if (started.ok)
+            return;
+        if (mode === 'required')
+            throw started.failure;
+        // Runtime not bootstrapped (e.g. direct PMDaemon construction in
+        // tests) — no modules to start.
+        this.logger.debug('daemon module resolution skipped', { failure: valueFreeFailure(started.failure) });
+    }
+    async startResolvedModules(mode) {
+        const runtime = this.runtime;
+        if (!runtime.hasKind('pm/daemon-module'))
+            return;
+        const descriptors = runtime
+            .query('pm/daemon-module')
+            .enabled()
+            .descriptors();
+        const sorted = [...descriptors]
+            .filter((descriptor) => Boolean(descriptor.required) === (mode === 'required'))
+            .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+        for (const descriptor of sorted) {
+            const id = descriptor.id;
+            const started = await attempt(async () => {
+                const module = await runtime
+                    .query('pm/daemon-module')
+                    .withId(id)
+                    .resolve();
+                // Built through the least-authority factory rather than inline: it
+                // narrows ProcessManager to its registered-process calls, so a daemon module
+                // can ensure its OWN registered process exists without gaining the
+                // authority to register commands or read unrelated configs.
+                const ctx = createPMDaemonModuleContext(this.pm, this.logger.child(`module:${id}`), this.runtime);
+                await module.start(ctx);
+                this.daemonModules.push({ id, module });
+                this.logger.info('daemon module started', { moduleId: id });
+                // If this module was previously degraded, remove it now that it started
+                const degraded = this.degradedModules.get(id);
+                if (degraded) {
+                    degraded.retryTimer?.();
+                    this.degradedModules.delete(id);
+                    this.logger.info('degraded module recovered', { moduleId: id });
+                }
+            });
+            if (!started.ok) {
+                this.logger.error('daemon module failed to start', {
+                    moduleId: id,
+                    failure: valueFreeFailure(started.failure)
+                });
+                if (descriptor.required) {
+                    const attempts = (this.degradedModules.get(id)?.attempts ?? 0) + 1;
+                    await this.scheduleModuleRestart(descriptor, attempts, started.failure);
+                }
+            }
+        }
+    }
+    /**
+     * Retry starting a degraded required daemon module.
+     * Called by the retry timer scheduled in startDaemonModules.
+     */
+    async retryDaemonModule(descriptor) {
+        const id = descriptor.id;
+        const degraded = this.degradedModules.get(id);
+        if (!degraded)
+            return; // Was already recovered or removed
+        const retried = await attempt(async () => {
+            const runtime = this.runtime;
+            if (!runtime.hasKind('pm/daemon-module'))
+                return;
+            const module = await runtime
+                .query('pm/daemon-module')
+                .withId(id)
+                .resolve();
+            // `.resolve()` returns the runtime's cached singleton for this id (asset
+            // kinds default to `cacheValue: true`), not a fresh instance — the SAME
+            // object as the failed attempt. If that attempt partially initialized
+            // internal state (a timer, a watcher, a listener) before throwing, calling
+            // `start()` again without an intervening `stop()` would run two live copies
+            // of whatever it allocated. Best-effort teardown first, exactly like
+            // `stopDaemonModules()` does for a normal shutdown.
+            const stopped = await attempt(async () => {
+                await module.stop?.();
+            });
+            if (!stopped.ok) {
+                this.logger.debug('degraded module pre-retry stop failed', {
+                    moduleId: id,
+                    failure: valueFreeFailure(stopped.failure)
+                });
+            }
+            const ctx = createPMDaemonModuleContext(this.pm, this.logger.child(`module:${id}`), this.runtime);
+            await module.start(ctx);
+            this.daemonModules.push({ id, module });
+            this.degradedModules.delete(id);
+            this.logger.info('degraded daemon module recovered on retry', { moduleId: id });
+        });
+        if (!retried.ok) {
+            this.logger.error('daemon module retry failed', {
+                moduleId: id,
+                failure: valueFreeFailure(retried.failure)
+            });
+            await this.scheduleModuleRestart(descriptor, degraded.attempts + 1, retried.failure);
+        }
+    }
+    /**
+     * Record a required module's failure and, within the declared
+     * `supervision.daemonModule` budget, schedule its restart on a lifecycle
+     * one-shot (disposed with the daemon's runtime). Past the budget it stays
+     * degraded, visible in the daemon's health, with no timer.
+     */
+    async scheduleModuleRestart(descriptor, attempts, failure) {
+        const id = descriptor.id;
+        this.degradedModules.get(id)?.retryTimer?.();
+        const policy = (await readSupervision(this.runtime)).daemonModule;
+        // `attempts` is the attempt that just failed; the retry this would
+        // schedule is attempt `attempts + 1`, and the budget caps failed
+        // starts (`maxConsecutive`: consecutive failures before the
+        // supervisor gives up). A next attempt past the cap degrades the
+        // module for good, its record naming the attempt that was refused,
+        // with no timer armed.
+        if (!mayRestart(policy, attempts + 1)) {
+            const refusedAttempt = attempts + 1;
+            this.degradedModules.set(id, { id, error: failure, attempts: refusedAttempt, descriptor });
+            this.logger.error('required daemon module restart budget spent', {
+                moduleId: id,
+                attempts: refusedAttempt,
+                maxConsecutive: policy.maxConsecutive
+            });
+            return;
+        }
+        const backoffMs = restartDelayMs(policy, attempts);
+        const nextRetryAt = new Date(Date.now() + backoffMs);
+        this.degradedModules.set(id, {
+            id,
+            error: failure,
+            attempts,
+            nextRetryAt,
+            descriptor,
+            retryTimer: this.runtime.lifecycle.timeout(() => {
+                void this.retryDaemonModule(descriptor);
+            }, backoffMs)
+        });
+        this.logger.info('required daemon module scheduled for restart', {
+            moduleId: id,
+            attempt: attempts,
+            nextRetryAt: nextRetryAt.toISOString(),
+            backoffMs
+        });
+    }
+    /**
+     * Stop every started daemon module (graceful shutdown + supersession).
+     * Best-effort: one module's stop failure never blocks the rest.
+     */
+    async stopDaemonModules() {
+        const modules = this.daemonModules;
+        this.daemonModules = [];
+        const outcomes = await Promise.all(modules.map(({ module }) => attempt(async () => { await module.stop?.(); })));
+        const failures = outcomes.flatMap((outcome) => outcome.ok ? [] : [outcome.failure]);
+        if (failures.length === 1)
+            throw failures[0];
+        if (failures.length > 1)
+            throw new AggregateError(failures, 'PM daemon module disposal failed.');
+    }
+    /**
+     * Stop the daemon
+     * CRITICAL FIX: Kill all managed processes on shutdown to prevent orphans
+     */
+    /**
+     * Stop once, whoever asks (shutdown, handoff, SIGTERM, SIGINT): a second
+     * request joins the first. A failed stop is logged once and recorded, so
+     * the serve host exits non-zero (`exitCode`).
+     */
+    requestStop(reason, mode = 'shutdown') {
+        if (this.stopping) {
+            attemptSync(() => this.logger.warn('shutdown already in progress', { reason }));
+            return this.stopping;
+        }
+        attemptSync(() => this.logger.info('received daemon exit request', { reason, mode }));
+        this.stopping = this.stopReportingFailure(mode);
+        return this.stopping;
+    }
+    /** `stop()` for a requester with no caller to throw to: the failure is recorded (exit status) and reported once. */
+    async stopReportingFailure(mode) {
+        const stopped = await attempt(() => this.stop(mode));
+        if (!stopped.ok) {
+            this.stopFailed = true;
+            attemptSync(() => this.logger.error('error during shutdown', { failure: valueFreeFailure(stopped.failure) }));
+        }
+    }
+    /** The serve host's exit status once `start()` has returned: 1 when the stop failed. */
+    get exitCode() {
+        return this.stopFailed ? 1 : 0;
+    }
+    async stop(mode = 'shutdown') {
+        try {
+            if (mode === 'handoff') {
+                await this.teardownWithoutStoppingManagedProcesses({ persistState: true, releaseLockFiles: true });
+            }
+            else {
+                await this.stopServingAndChildren();
+            }
+        }
+        catch (error) {
+            this.stopFailed = true;
+            throw error;
+        }
+        finally {
+            // The serve host exits only after the selected teardown completes.
+            // Shutdown drains children; handoff leaves their tracked runs live.
+            // Both release daemon identity before releasing start()'s keep-alive.
+            this.keepAliveResolve?.();
+            this.keepAliveResolve = undefined;
+        }
+    }
+    async stopServingAndChildren() {
+        attemptSync(() => this.logger.info('stopping'));
+        const failures = [];
+        const release = async (run) => {
+            const released = await attempt(async () => { await run(); });
+            if (!released.ok)
+                failures.push(released.failure);
+        };
+        // Close the RPC admission boundary before taking any process snapshot.
+        // This is idempotent with the explicit shutdown command and also makes
+        // signal/supersession teardown wait for already-accepted mutations.
+        await release(() => this.commandDispatcher.closeAndDrain());
+        await release(() => this.unsubscribeGeneration?.());
+        this.unsubscribeGeneration = undefined;
+        await release(() => this.rpcListener?.stop());
+        this.rpcListener = undefined;
+        // Stop the supervisor ticks (lifecycle disposers; idempotent).
+        await release(() => this.stopTicks());
+        // Clear all monitor tracking maps to prevent memory leaks
+        await release(() => this.healthMonitor.clearTracking());
+        await release(() => this.resourceHealthMonitor.clearTracking());
+        await release(() => this.livenessChecker.clearTracking());
+        // Stop config watcher and process file watchers
+        await release(() => this.configWatcher.stop());
+        await release(() => this.configWatcher.cleanupAllProcessWatchers());
+        // Cancel any pending module retry timers
+        for (const degraded of this.degradedModules.values()) {
+            await release(() => degraded.retryTimer?.());
+        }
+        this.degradedModules.clear();
+        // Stop daemon modules (channel scheduler, surface watcher, platform sync, …)
+        await release(() => this.stopDaemonModules());
+        // CRITICAL FIX: Stop all managed processes before shutting down
+        // This prevents orphans when daemon crashes or is killed
+        attemptSync(() => this.logger.info('stopping managed processes'));
+        const snapshot = await attempt(() => this.store.getAll());
+        if (!snapshot.ok)
+            failures.push(snapshot.failure);
+        const states = snapshot.ok ? snapshot.value : [];
+        // Each child's own stop failure is the cause of the one typed refusal below.
+        const childFailures = [];
+        // Every child at once, so the daemon's stop fits its caller's grace
+        // however many children it supervises.
+        const outcomes = await Promise.all(states
+            .filter((state) => state.status === 'running' || state.status === 'starting')
+            .map(async (state) => {
+            attemptSync(() => this.logger.debug('stopping managed process', { processId: state.id }));
+            // Graceful first (SIGTERM to the tree, SIGKILL after the grace), so a
+            // child can unlink its own sockets; then remove the socket PM declared
+            // for it if the child left it behind.
+            const stopped = await attempt(async () => {
+                await this.pm.stop(state.id, { timeout: MANAGED_STOP_GRACE_MS });
+                if (state.socketPath)
+                    await this.removeStaleSocket(state.id, state.socketPath);
+            });
+            if (!stopped.ok) {
+                childFailures.push(stopped.failure);
+                attemptSync(() => this.logger.error('failed to stop managed process', {
+                    processId: state.id,
+                    failure: valueFreeFailure(stopped.failure)
+                }));
+            }
+            return { processId: state.id, stopped: stopped.ok };
+        }));
+        const stoppedCount = outcomes.filter((outcome) => outcome.stopped).length;
+        const notStopped = outcomes.filter((outcome) => !outcome.stopped).map((outcome) => outcome.processId);
+        if (stoppedCount > 0) {
+            attemptSync(() => this.logger.info('managed processes stopped', { count: stoppedCount }));
+        }
+        // Remove PID file
+        const identityReleased = await attempt(() => this.releaseIdentityFiles());
+        if (!identityReleased.ok)
+            failures.push(identityReleased.failure);
+        // Hot reload last: `this.runtime` is its generation-following handle, and
+        // stopping it disposes that handle. Stopped first, every child stop and
+        // the identity-file release above failed "Cannot acquire a disposed
+        // runtime generation", and the children outlived the daemon.
+        const reloadStopped = await attempt(async () => { await this.hotReload?.stop(); });
+        if (!reloadStopped.ok)
+            failures.push(reloadStopped.failure);
+        if (notStopped.length > 0) {
+            // Partial success is a failure: the serve host exits non-zero.
+            failures.push(new CapabilityError('The PM daemon stopped, but some managed processes did not.', 'INTERNAL', {
+                reason: 'pm-daemon-children-not-stopped',
+                details: { processIds: notStopped },
+                cause: childFailures.length === 1 ? childFailures[0] : new AggregateError(childFailures, 'Managed process stops failed.')
+            }));
+        }
+        if (failures.length === 1)
+            throw failures[0];
+        if (failures.length > 1)
+            throw new AggregateError(failures, 'PM daemon shutdown failed.');
+        attemptSync(() => this.logger.info('stopped'));
+    }
+    /**
+     * Write PID file
+     * Simple PID file creation - daemon lock enforcement happens via socket binding
+     */
+    /**
+     * Refresh the pid file's mtime so the client's 5-minute staleness window
+     * measures liveness. Never resurrects or overwrites a pid file this daemon
+     * no longer owns — if it's gone or names another pid, a takeover is in
+     * progress and the supersession check owns the response.
+     */
+    async heartbeatPidFile() {
+        const pid = await this.hostPid();
+        const files = await this.hostFiles();
+        const current = await readIfPresent(files, this.pidFile);
+        if (current === null || current.trim() !== pid.toString())
+            return;
+        await files.writeFile(this.pidFile, pid.toString(), { mode: 0o600 });
+    }
+    /** The supplied host's PID, admitted before PM uses it as ownership evidence. */
+    async hostPid() {
+        const pid = (await getRuntimeHostIdentity(this.runtime)).currentPid();
+        if (!Number.isSafeInteger(pid) || pid <= 0) {
+            throw new CapabilityError('The selected host supplied an invalid process identity.', 'INVALID_INPUT', {
+                reason: 'pm-host-pid-invalid', retryable: false
+            });
+        }
+        return pid;
+    }
+    /** The host filesystem the daemon's runtime resolves: the pid file and its directories are host facts at absolute paths. */
+    hostFiles() {
+        return resolveFileSystemAdapter(this.runtime, { binding: false });
+    }
+    /**
+     * One supersession check: do the pid file and listening endpoint still belong to
+     * this process? Two consecutive failures are required before exiting so a
+     * transient mid-rewrite read can't kill a healthy daemon.
+     *
+     * @returns true when the daemon should exit (superseded/culled).
+     */
+    async tickSupersession() {
+        const pid = await this.hostPid();
+        // A removed pid file (ENOENT) is a cull: not owned.
+        const probed = await attempt(async () => {
+            const pidText = await readIfPresent(await this.hostFiles(), this.pidFile);
+            return pidText?.trim() === pid.toString() && (await canConnectToPMSocket(this.runtime, this.socketPath, 500));
+        });
+        // An unreadable pid file or a failing socket probe counts as a strike,
+        // and is reported: two in a row end this daemon as superseded.
+        if (!probed.ok)
+            this.logger.warn('daemon ownership probe failed', { failure: valueFreeFailure(probed.failure) });
+        const owned = probed.ok && probed.value;
+        if (owned) {
+            this.supersessionStrikes = 0;
+            return false;
+        }
+        this.supersessionStrikes += 1;
+        this.logger.warn('daemon ownership check failed', {
+            strikes: this.supersessionStrikes,
+            pidFile: this.pidFile,
+            socketPath: this.socketPath
+        });
+        return this.supersessionStrikes >= 2;
+    }
+    /**
+     * Stop everything EXCEPT managed processes: timers, config watcher,
+     * daemon modules, the RPC listener. Optionally persist store state and
+     * release the pid file/socket. Shared by exitSuperseded() (never
+     * persists or releases — the incumbent daemon owns that world) and
+     * handleFatalError() (a genuine crash with no incumbent, so state and
+     * the pid file/socket must be released or nothing else ever will).
+     */
+    async teardownWithoutStoppingManagedProcesses(options) {
+        const failures = [];
+        // Supersession/fatal teardown releases infrastructure without stopping managed children.
+        for (const release of [
+            () => this.commandDispatcher.closeAndDrain(),
+            async () => {
+                await this.unsubscribeGeneration?.();
+                this.unsubscribeGeneration = undefined;
+            },
+            () => this.stopTicks(),
+            () => this.configWatcher.stop(),
+            () => this.configWatcher.cleanupAllProcessWatchers(),
+            () => this.stopDaemonModules(),
+            () => this.rpcListener?.stop()
+        ]) {
+            const released = await attempt(async () => { await release(); });
+            if (!released.ok)
+                failures.push(released.failure);
+        }
+        if (options.persistState) {
+            // State is persisted immediately on every SQLite write; there is
+            // no buffered snapshot left to flush here.
+            attemptSync(() => this.logger.debug('state persistence is immediate (SQLite); nothing to flush'));
+        }
+        if (options.releaseLockFiles) {
+            // Socket first: removeSocketFile()'s ownership check reads the pid
+            // file and compares its contents to the supplied host PID — reversing this
+            // order would have removePidFile() truncate the pid file first,
+            // so the socket check would read an empty string, treat it as
+            // "owned by another process", and leave the socket behind.
+            const released = await attempt(() => this.releaseIdentityFiles());
+            if (!released.ok)
+                failures.push(released.failure);
+        }
+        if (failures.length === 1)
+            throw failures[0];
+        if (failures.length > 1)
+            throw new AggregateError(failures, 'PM daemon infrastructure teardown failed.');
+    }
+    /**
+     * Minimal teardown + exit for a superseded daemon. Deliberately NOT
+     * `stop()`: the incumbent daemon now owns the managed processes (adopted
+     * via the persisted store on its reconcileState), the pid file, and the
+     * socket path. Killing children, saving state, or removing the pid file
+     * here would corrupt the incumbent's world — the exact zombie-vs-incumbent
+     * fight this check exists to end.
+     */
+    async exitSuperseded() {
+        const pid = await this.hostPid();
+        attemptSync(() => this.logger.warn('superseded by another daemon (pid file / socket no longer ours) — exiting without touching managed processes', { pid, pidFile: this.pidFile, socketPath: this.socketPath }));
+        try {
+            await this.teardownWithoutStoppingManagedProcesses({ persistState: false, releaseLockFiles: false });
+        }
+        finally {
+            this.keepAliveResolve?.();
+            this.keepAliveResolve = undefined;
+        }
+    }
+    /**
+     * Handle an uncaughtException/unhandledRejection: log with the stack,
+     * persist state, release the pid file/socket, and tear down WITHOUT
+     * stopping managed processes. UNIT-013/#325 established that policy for
+     * daemon supersession (exitSuperseded above); a fatal error in this
+     * process is not a reason to take Drew's whole dev stack down with it —
+     * that was the 2026-09-02 incident: an uncaught ENOENT from a preBuild
+     * hook reached daemon.ts's uncaughtException handler, which called the
+     * full `stop()` and killed every managed process. Unlike exitSuperseded,
+     * there is no incumbent here, so state and the pid file/socket ARE
+     * released — nothing else will. It does not end the process; the host
+     * (its fatal-failure behaviour) owns that, so this stays testable.
+     */
+    async handleFatalError(reason, error) {
+        attemptSync(() => this.logger.error(`fatal error (${reason})`, { failure: valueFreeFailure(error) }));
+        await this.teardownWithoutStoppingManagedProcesses({
+            persistState: true,
+            releaseLockFiles: true
+        });
+    }
+    async writePidFile() {
+        const pid = await this.hostPid();
+        const written = await attempt(async () => {
+            // UNIT-020-C (root cause): a losing daemon start() must never clobber a
+            // still-alive winner's pid file. cleanupStaleSocketIfNeeded() only guards
+            // this early, before descriptor discovery, so a racing daemon can still
+            // reach here after the winner already wrote and bound. Refuse to
+            // overwrite a pid file naming a different, still-running pid; let
+            // start() fail loudly instead of corrupting the incumbent's identity
+            // (the failure this guards against: the loser used to overwrite the
+            // winner's pid file here, then its own bind-failure cleanup truncated
+            // that entry to empty, which the winner's tickSupersession read as
+            // "superseded" and exited on).
+            const files = await this.hostFiles();
+            const existing = await readIfPresent(files, this.pidFile);
+            if (existing !== null) {
+                const existingPid = Number(existing.trim());
+                if (Number.isInteger(existingPid) &&
+                    existingPid !== pid &&
+                    (await isProcessRunning(this.runtime, existingPid))) {
+                    throw new CapabilityError(`PID file ${this.pidFile} is owned by a live process (PID ${existingPid}); refusing to overwrite. ` +
+                        `Another daemon may already be running.`, 'CONFLICT', { reason: 'pm-daemon-pid-file-owned', details: { pidFile: this.pidFile, pid: existingPid } });
+                }
+            }
+            await files.writeFile(this.pidFile, pid.toString(), { mode: 0o600 });
+            this.logger.debug('pid file written', { pidFile: this.pidFile });
+        });
+        if (!written.ok) {
+            this.logger.error('failed to write pid file', {
+                pidFile: this.pidFile,
+                failure: valueFreeFailure(written.failure)
+            });
+            throw written.failure;
+        }
+    }
+    /**
+     * Remove PID file
+     * Note: Web Locks API automatically releases lock when process exits
+     *
+     * UNIT-020-C: Only remove/truncate the pid file if it contains this process's pid.
+     * When concurrent launchers race, the loser must not corrupt the winner's pid file.
+     */
+    /**
+     * Release the daemon's identity files in the only safe order: the socket
+     * first, then the pid file. removeSocketFile()'s ownership check reads the
+     * pid file, so removing the pid file first left the socket behind and the
+     * next daemon failed to bind it ("Failed to listen at …"). Shared by stop()
+     * and the managed-process-safe teardown.
+     */
+    async releaseIdentityFiles() {
+        // Both run even when the first fails; each failure is reported.
+        const failures = [];
+        for (const [name, release] of [
+            ['socket', () => this.removeSocketFile()],
+            ['pid file', () => this.removePidFile()]
+        ]) {
+            const released = await attempt(release);
+            if (!released.ok) {
+                failures.push(released.failure);
+                attemptSync(() => this.logger.warn(`daemon ${name} release failed`, { failure: valueFreeFailure(released.failure) }));
+            }
+        }
+        if (failures.length === 1)
+            throw failures[0];
+        if (failures.length > 1)
+            throw new AggregateError(failures, 'Daemon identity release failed.');
+    }
+    /** Truncate this daemon's pid file (never another's). A write failure propagates to the caller. */
+    async removePidFile() {
+        const pid = await this.hostPid();
+        const files = await this.hostFiles();
+        const pidContent = await readIfPresent(files, this.pidFile);
+        if (pidContent !== null && Number(pidContent.trim()) !== pid) {
+            // Pid file is owned by another process; leave it untouched
+            return;
+        }
+        // Truncate the PID file (lock auto-released on process exit)
+        await files.writeFile(this.pidFile, '', { mode: 0o600 });
+        attemptSync(() => this.logger.debug('pid file removed', { pidFile: this.pidFile }));
+    }
+    async removeSocketFile() {
+        const pid = await this.hostPid();
+        // No pid file: this daemon no longer owns the socket name.
+        const pidContent = await readIfPresent(await this.hostFiles(), this.pidFile);
+        if (pidContent === null)
+            return;
+        if (pidContent.trim() !== pid.toString())
+            return;
+        await removeSocket(this.runtime, this.socketPath);
+    }
+    /**
+     * Ensure ~/.vibes paths exist and are user-writable
+     */
+    async ensurePathPermissions() {
+        const base = getVibesDir({ roots: this.roots });
+        const sockDir = this.runtimePath.join(base, 'pm', 'sock');
+        const logsDir = this.runtimePath.join(base, 'logs');
+        const pmDir = this.runtimePath.join(base, 'pm');
+        const runtimeSocketDir = getSocketBasePath({ roots: this.roots, runtimePath: this.runtimePath });
+        const files = await this.hostFiles();
+        // A directory the daemon cannot create fails its start here, by name. A
+        // new directory is created owner-only, and one that already exists is
+        // tightened to owner-only through the filesystem kind's `chmod` (a host
+        // without POSIX modes, Windows, has none to pin).
+        const pinsModes = this.runtime.localEnvironment.getPlatform?.() !== 'win32';
+        for (const dir of [base, sockDir, logsDir, pmDir, runtimeSocketDir]) {
+            await files.mkdir(dir, { recursive: true, mode: 0o700 });
+            if (pinsModes)
+                await chmodChecked(files, dir, 0o700);
+        }
+    }
+    /**
+     * Get daemon health information
+     * Lightweight check for monitoring and status display
+     *
+     * CRITICAL FIX: If the store is throwing (e.g. SQLite disk I/O error),
+     * return healthy:false so callers know the daemon is alive but sick.
+     * A 200 response with healthy:false lets canConnectToPMSocket() decide
+     * whether to treat the daemon as reachable.
+     */
+    async getHealth() {
+        const pid = await this.hostPid();
+        const counted = await attempt(async () => {
+            // `__`-prefixed rows are store bookkeeping (e.g. __lastStoreCleanup),
+            // not processes. `pm status` / `pm list` already hide them; the
+            // daemon's own count disagreed with those surfaces by exactly that
+            // many (measured 2026-09-06: 45 here vs 44 there).
+            const states = (await this.store.getAll()).filter((s) => isManagedProcessId(s.id));
+            return { total: states.length, running: states.filter((s) => s.status === 'running').length };
+        });
+        const version = await getPMVersion(this.runtime);
+        const { workspacePath, toolingId } = admittedWorkspaceIdentity(this.workspaceRoot);
+        if (!counted.ok) {
+            this.logger.error('health check failed: store unreachable', { failure: valueFreeFailure(counted.failure) });
+            return {
+                healthy: false,
+                uptime: Date.now() - this.startTime,
+                version,
+                processCount: 0,
+                runningCount: 0,
+                timestamp: new Date(),
+                pid,
+                error: failureText(counted.failure)
+            };
+        }
+        const health = {
+            healthy: true,
+            uptime: Date.now() - this.startTime,
+            version,
+            processCount: counted.value.total,
+            runningCount: counted.value.running,
+            timestamp: new Date(),
+            pid,
+            commands: this.commandDispatcher.commandCounts(),
+            taskSupervision: { version: 1, scope: PmTaskScopeSchema.parse({ workspacePath, toolingId }) }
+        };
+        if (this.degradedModules.size > 0) {
+            health.degradedModules = Array.from(this.degradedModules.values()).map((d) => ({
+                id: d.id,
+                error: failureText(d.error),
+                attempts: d.attempts,
+                nextRetryAt: d.nextRetryAt
+            }));
+        }
+        return health;
+    }
+    /**
+     * A PID file naming a live process stays; a stale or unparseable one is
+     * removed. Liveness is the host process service's answer; a PID file that
+     * cannot be read or removed, or a process table that cannot be read, fails
+     * the start instead of being overwritten blind.
+     */
+    async cleanupStalePidIfNeeded() {
+        const files = await this.hostFiles();
+        const content = await readIfPresent(files, this.pidFile);
+        if (content === null)
+            return;
+        const pid = parseInt(content.trim(), 10);
+        if (Number.isInteger(pid) && (await isProcessRunning(this.runtime, pid)))
+            return;
+        // Gone already (ENOENT) is the goal; any other removal failure fails the start.
+        const removed = await attempt(() => files.remove(this.pidFile));
+        if (!removed.ok && !(hasErrnoCode(removed.failure) && removed.failure.code === 'ENOENT'))
+            throw removed.failure;
+    }
+    /**
+     * Do NOT delete a socket that is actively bound by a running daemon: a
+     * second launcher that races to the same socket must fail fast, not stomp
+     * on the incumbent. The probe answers "no" only for confirmed absence or a
+     * daemon that did not answer (and the socket service refuses to remove an
+     * endpoint that is still listening); a non-socket file at the path, a
+     * permission refusal, or a removal failure fails the start typed.
+     */
+    async cleanupStaleSocketIfNeeded() {
+        if (await canConnectToPMSocket(this.runtime, this.socketPath, 500)) {
+            const incumbentPid = await readDaemonPid(this.runtime, this.pidFile);
+            const detail = incumbentPid ? ` (PID ${incumbentPid})` : '';
+            throw new CapabilityError(`PM daemon already running on socket ${this.socketPath}${detail}. ` +
+                `Use 'vibes pm daemon restart' if you need to replace it.`, 'CONFLICT', { reason: 'pm-daemon-already-running', details: { socketPath: this.socketPath, pid: incumbentPid ?? null } });
+        }
+        await removeSocket(this.runtime, this.socketPath);
+    }
+    /**
+     * Run scheduled cleanup of idle and ephemeral processes
+     */
+    async runScheduledCleanup() {
+        // Clean up idle processes (configured with idleTimeoutMs)
+        const stopped = await this.pm.cleanupIdleProcesses();
+        if (stopped.length > 0) {
+            this.logger.info('idle cleanup removed processes', { processIds: stopped });
+        }
+        // Clean up ephemeral processes (ad-hoc processes not in vibes.pm.ts)
+        const cleaned = await this.pm.cleanupEphemeralProcesses();
+        if (cleaned.length > 0) {
+            this.logger.info('ephemeral cleanup removed processes', { processIds: cleaned });
+        }
+        // CRITICAL FIX (Issue 3.2): Clean up old state entries (run once per day)
+        // Track last cleanup time to avoid running too frequently. The
+        // timestamp lives in the store's pm_kv table — it used to be a fake
+        // `__lastStoreCleanup` process_states row, which every consumer had
+        // to remember to filter out of counts and listings.
+        const now = Date.now();
+        const lastStoreCleanup = Number((await this.store.getMeta('lastStoreCleanup')) ?? 0) || 0;
+        const oneDayMs = 24 * 60 * 60 * 1000;
+        if (now - lastStoreCleanup > oneDayMs) {
+            const swept = await attempt(async () => {
+                const cleaned = await this.store.cleanupOldEntries(30); // 30 day retention
+                if (cleaned.processes > 0 || cleaned.resources > 0) {
+                    this.logger.info('cleaned up old state entries', {
+                        processes: cleaned.processes,
+                        resources: cleaned.resources
+                    });
+                }
+                // Update last cleanup timestamp
+                await this.store.setMeta('lastStoreCleanup', String(now));
+                // Retire the legacy fake-row sentinel from pre-kv databases so
+                // it stops haunting counts.
+                await this.store.delete('__lastStoreCleanup');
+            });
+            if (!swept.ok) {
+                this.logger.error('failed to clean up old state entries', { failure: valueFreeFailure(swept.failure) });
+            }
+            // Process logs past the declared retention (`pm.process-capture` maxAge) age out:
+            // archives whether or not a row exists, a current log only when none holds it.
+            const aged = await attempt(async () => {
+                const maxAgeMs = await readRotationMaxAge(this.runtime, PM_CAPTURE_ROTATION_POLICY);
+                if (maxAgeMs === undefined)
+                    return;
+                const expired = await this.pm.cleanupExpiredLogs(maxAgeMs);
+                if (expired.cleaned.length > 0 || expired.errors.length > 0) {
+                    this.logger.info('aged out process logs', { removed: expired.cleaned.length, failed: expired.errors.map((error) => error.id) });
+                }
+            });
+            if (!aged.ok) {
+                this.logger.error('failed to age out process logs', { failure: valueFreeFailure(aged.failure) });
+            }
+        }
+        // Rotate oversized logs of live processes. LifecycleService only rotates
+        // at start(), so without this a long-running child's log grew unbounded
+        // until its next restart.
+        const rotated = await attempt(() => this.rotateLiveProcessLogs());
+        if (!rotated.ok) {
+            this.logger.error('process log rotation sweep failed', { failure: valueFreeFailure(rotated.failure) });
+        }
+    }
+    /**
+     * Rotate `<id>.stdout` / `<id>.stderr` of every running or starting
+     * process that crossed the size threshold, and the daemon's own stdio
+     * logs, through the logging owner under the declared policy (L1).
+     */
+    /** The declared `pm.process-capture` rotation policy, read from the logging config on each sweep. */
+    captureRotationPolicy() {
+        return readRotationPolicy(this.runtime, PM_CAPTURE_ROTATION_POLICY);
+    }
+    async rotateLiveProcessLogs() {
+        const states = await this.store.getAll();
+        const liveIds = states
+            .filter((state) => state.status === 'running' || state.status === 'starting')
+            .map((state) => state.id);
+        if (liveIds.length === 0)
+            return;
+        const policy = await this.captureRotationPolicy();
+        const { rotated, failed } = await rotateOversizedProcessLogs({
+            runtime: this.runtime,
+            logDir: this.processLogDir,
+            processIds: liveIds,
+            policy
+        });
+        // The daemon's own stdio logs are not `<id>.stdout` files; rotate them at
+        // their real paths under this daemon's roots (D17).
+        const daemonRotation = await rotateOversizedDaemonLogs({ runtime: this.runtime, workspace: this.workspaceRoot, roots: this.roots, policy });
+        rotated.push(...daemonRotation.rotated);
+        failed.push(...daemonRotation.failed);
+        for (const entry of rotated) {
+            this.logger.info('rotated oversized process log', entry);
+        }
+        for (const entry of failed) {
+            this.logger.warn('process log rotation failed', {
+                processId: entry.processId,
+                path: entry.path,
+                failure: valueFreeFailure(entry.error)
+            });
+        }
+    }
+    /**
+     * Hand the orphan scanner the current registry. `OrphanScannerDeps.configs`
+     * is a plain Map behind a `setConfigs` setter (no live accessor), and the
+     * daemon constructed the scanner without it and never called the setter —
+     * so `enableAdoption: true` matched against an empty Map forever.
+     */
+    async syncOrphanScannerConfigs() {
+        const configs = await this.pm.getAllConfigs();
+        this.orphanScanner.setConfigs(new Map(configs.map((config) => [config.id, config])));
+    }
+    /** One orphan-scan tick: refresh configs from the registry, then scan. */
+    async runOrphanScan() {
+        await this.syncOrphanScannerConfigs();
+        await this.orphanScanner.scanAndKillOrphans();
+    }
+}
+/**
+ * Check if daemon socket is connectable via HTTP health check.
+ *
+ * Validates the response body to ensure the daemon is not merely alive but
+ * actually healthy (store is operational).  A daemon with a corrupted SQLite
+ * file will respond 200 but with { healthy: false }, so surface-level
+ * `response.ok` is not enough.
+ */
+/**
+ * Get daemon log file contents
+ * Reads from the handed Runtime's output and preserves read failures.
+ */
+export async function getDaemonLogs(runtime, options = {}) {
+    const lines = await readPMDaemonLogTail(runtime, options.lines ?? 50);
+    if (lines.length === 0) {
+        return 'No daemon logs available';
+    }
+    return lines.join('\n');
+}
+/**
+ * Entry point for daemon. `workspaceRoot` is the admitted workspace the serve
+ * body resolved (`pm/admitted-workspace`); the daemon supervises exactly it.
+ */
+async function main(options) {
+    // The serve host the command was handed registered the host's
+    // paths/runtime-path; resolve it from that runtime and hand both to the daemon.
+    const daemon = new PMDaemon({
+        runtime: options.runtime,
+        runtimePath: await getRuntimePath(options.runtime),
+        workspaceRoot: options.workspaceRoot
+    });
+    const logger = getPMDaemonLogger(options.runtime, 'global');
+    // Report the inherited RLIMIT_NOFILE so low limits surface in one obvious
+    // place instead of leaking out later as cryptic ENFILE errors from vite
+    // or svelte-check. pm.daemon.start wraps this process with a raised
+    // ulimit; if we still see a low number here, something stripped the wrap.
+    // Null: the host has no descriptor limit to report (win32). A probe that
+    // cannot run is reported as such and does not stop the daemon.
+    let nofile = null;
+    const limit = await attempt(() => readFileDescriptorLimit(options.runtime));
+    if (limit.ok) {
+        nofile = limit.value;
+    }
+    else if (isCapabilityError(limit.failure) && limit.failure.reason === 'process-table-unavailable') {
+        logger.warn('file descriptor limit unreadable on this host', { reason: limit.failure.reason });
+    }
+    else {
+        throw limit.failure;
+    }
+    if (nofile !== null && Number.isFinite(nofile)) {
+        if (nofile < MIN_ACCEPTABLE_NOFILE) {
+            logger.warn('file descriptor limit below threshold', {
+                current: nofile,
+                recommended: RECOMMENDED_NOFILE,
+                remediation: fileDescriptorLimitRemediation(nofile)
+            });
+        }
+        else {
+            logger.info('file descriptor limit', { current: nofile });
+        }
+    }
+    // Termination signals and fatal failures arrive through the serve host's
+    // declared host signals (runtime/host signals), never process listeners;
+    // the exit status returns to the `pm daemon serve` host, which owns exit.
+    const signals = await getRuntimeHostSignals(options.runtime);
+    const subscriptions = [
+        signals.subscribe('SIGTERM', () => void daemon.requestStop('SIGTERM')),
+        signals.subscribe('SIGINT', () => void daemon.requestStop('SIGINT'))
+    ];
+    // Report-only (the host still prints and exits non-zero): a fatal error
+    // persists state and releases the pid file/socket WITHOUT stopping managed
+    // processes — a fatal error in this process is not a reason to take the
+    // whole dev stack down with it (2026-09-02, see PMDaemon.handleFatalError).
+    const fatal = signals.subscribeFatal?.((kind, error) => {
+        void (async () => {
+            const tornDown = await attempt(() => daemon.handleFatalError(kind, CaughtFailureSchema.parse(error)));
+            if (!tornDown.ok)
+                logger.error('fatal teardown failed', { failure: valueFreeFailure(tornDown.failure) });
+        })();
+    });
+    if (fatal)
+        subscriptions.push(fatal);
+    else {
+        // Typed absence: this host declares no fatal-failure reports, so a crash
+        // still exits through the host's default, but PM cannot persist state or
+        // release its pid file/socket first.
+        logger.warn('host declares no fatal-failure reports; a crash will not release the pid file or socket', {
+            reason: 'host-fatal-signals-unavailable'
+        });
+    }
+    const started = await attempt(() => daemon.start());
+    for (const unsubscribe of subscriptions)
+        unsubscribe();
+    if (!started.ok) {
+        logger.error('failed to start', { failure: valueFreeFailure(started.failure) });
+        return 1;
+    }
+    logger.info('shutdown complete', { exitCode: daemon.exitCode });
+    return daemon.exitCode;
+}
+export { main as startDaemon };
+//# sourceMappingURL=daemon.js.map