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

package/dist/services/lifecycle.js

@@ -0,0 +1,1391 @@
+/**
+ * Process Lifecycle Service
+ * Handles start, stop, restart, and monitoring of processes
+ */
+import * as z from 'zod/v4';
+import { processLaunchDeclaration } from "../helpers/launch-identity.js";
+import { prepareProcessLaunch } from "../launch-preparation.js";
+import { redactCredentials, redactedExcerpt } from '@vibesdotdev/shared/utils';
+import { CapabilityError, getRuntimeHostCommands, isCapabilityError, requireRuntimeCwd, valueFreeFailure } from '@vibesdotdev/kernel';
+import { getRuntimePath } from '@vibesdotdev/paths';
+import { resolveFileSystemAdapter } from '@vibesdotdev/filesystem/client/resolve-adapter';
+import { readByteRange } from "../helpers/runtime-files.js";
+import { getRuntimeExecution } from '@vibesdotdev/kernel/execution';
+import { attempt, failureText } from "../utils/attempt.js";
+import { hasErrnoCode } from "../utils/errno-failure.js";
+import { runCapture, whichCommand } from "../utils/exec.js";
+import { toolFailure } from "../resources/providers/tool-env.js";
+import { ProcessConfigSchema, ProcessLaunchInputsSchema, ProcessRunSchema, isSameRun, isProcessExited } from "../schemas/process.js";
+import { getLogger } from '@vibesdotdev/logging';
+import { killProcessTree, gracefulKillProcessTree, isProcessRunning, verifyProcessOwnership, getDescendantPids, waitForProcessExit } from "../utils/process-tree.js";
+import { isWaitTimeout, pollUntil } from "../utils/bounded-wait.js";
+import { scanAndKillOrphans, checkOrphanedByState } from "./orphans.js";
+import { removeSocket, testSocketConnectivity } from "../utils/socket.js";
+import { extractMonitoredPorts, findPortConflicts, findProcessOnPort } from "../utils/ports.js";
+import { composePMChildEnv } from "../helpers/process-env.js";
+import { mayRestart, processRestartPolicy, readSupervision, restartDelayMs } from "./supervision-policy.js";
+import { processLogRedactions, resolveProcessCredentials } from "../helpers/process-credentials.js";
+import { PM_CAPTURE_ROTATION_POLICY } from "../utils/logging.js";
+import { applyLivenessOverrides } from "./liveness-state.js";
+import { resolveProcessCommand } from "./process-command.js";
+import { isWithinStartupWarmup } from "./startup-warmup.js";
+import { launchCustodyNeedsPersist } from "../helpers/launch-custody.js";
+import { formatRunStartMarker } from "./process-log-archive.js";
+/** The runaway guard's window; its limit is the declared `supervision.maxSpawnsPerMinute`. */
+const SPAWN_WINDOW_MS = 60 * 1000;
+// Log rotation: the logging owner's `rotateAppendedFile` under the declared
+// `pm.process-capture` policy, at start and in the daemon's steady-state sweep.
+/**
+ * Cap on bytes read from a stderr log for crash details: only the last few
+ * lines are kept, so reading more than this from a file that may sit at the
+ * 100MB rotation threshold is pure memory churn.
+ */
+const CRASH_DETAIL_TAIL_BYTES = 64 * 1024;
+const PidFileTextSchema = z.string();
+/**
+ * The last `maxBytes` of a file. Crash-detail extraction needs the last few
+ * lines only, so only that range is read, through the filesystem kind's ranged
+ * read.
+ */
+async function readTail(files, path, maxBytes) {
+    const { size } = await files.stat(path);
+    return new TextDecoder().decode(await readByteRange(files, path, Math.max(0, size - maxBytes), size));
+}
+/** The most of a hook's output a failure message or log carries. */
+const HOOK_OUTPUT_MAX_CHARS = 4_000;
+/** The reason of the typed error a hook that overran its deadline raises. */
+const HOOK_TIMEOUT_REASON = 'pm-hook-timeout';
+/**
+ * EX_TEMPFAIL (sysexits.h): the child says the machine failed, not the
+ * program, for example a full descriptor or memory table. Kiln exits 75 when
+ * ENFILE stops it opening its weights. On the crash schedule those exits spent
+ * `maxRestarts: 2` in seconds and left Kiln down after the machine recovered
+ * (2026-09-25). They back off on their own schedule instead, from
+ * max(restartDelay, 5s) doubling to 5 minutes, and never count toward
+ * `maxRestarts`.
+ */
+export const EX_TEMPFAIL = 75;
+export const TEMPFAIL_MIN_DELAY_MS = 5_000;
+export const TEMPFAIL_MAX_DELAY_MS = 5 * 60_000;
+/** How long a restart waits for the stopped run's pid to exit before it refuses `pm-process-stop-failed`. */
+export const RESTART_EXIT_TIMEOUT_MS = 5_000;
+function exitOf(exit) {
+    return { code: exit.code ?? -1, signal: exit.signal ?? undefined };
+}
+/** The delay before EX_TEMPFAIL retry `attempt` (1-based): max(restartDelay, floor) doubling, capped at five minutes. */
+export function tempfailRestartDelay(attempt, restartDelay, minDelayMs = TEMPFAIL_MIN_DELAY_MS) {
+    const base = Math.max(restartDelay || 0, minDelayMs);
+    return Math.min(base * Math.pow(2, Math.max(0, attempt - 1)), TEMPFAIL_MAX_DELAY_MS);
+}
+/**
+ * Process Lifecycle Service manages process start/stop/restart
+ */
+export class LifecycleService {
+    store;
+    getRuntime;
+    logDir;
+    resourceManager;
+    graphIdentity;
+    daemonScope;
+    livenessProfile;
+    processes = new Map();
+    spawnTimes = new Map();
+    configuredIds = null;
+    /**
+     * Timers that reset a process's `consecutiveCrashRestarts` to 0 once
+     * it's been running stably for `config.restartSettleMs`. Cleared
+     * whenever the process exits, is stopped, or is re-started. See the
+     * `restartSettleMs` field in process.ts for the semantics.
+     */
+    settleTimers = new Map();
+    healthSettleRuns = new Map();
+    healthSettleUnsubscribe;
+    /** The credential values injected at each process's last spawn by this daemon (RC05), for log redaction. */
+    credentialRedactions = new Map();
+    /** Consecutive EX_TEMPFAIL exits per process; cleared by any other exit or an operator start. */
+    tempfailAttempts = new Map();
+    tempfailMinDelayMs;
+    restartExitTimeoutMs;
+    /** The exit handling of each child PM holds a handle for, by process id: `stop()` awaits it. */
+    exits = new Map();
+    /** The handed runtime's Logging, read per entry so it follows hot-reload generations (C083a). */
+    get log() {
+        return getLogger('pm:lifecycle', this.getRuntime());
+    }
+    /** `store` holds both state and each process's registered/launched config (pm.md K8). */
+    constructor(store, config) {
+        this.tempfailMinDelayMs = config.tempfailMinDelayMs ?? TEMPFAIL_MIN_DELAY_MS;
+        this.restartExitTimeoutMs = config.restartExitTimeoutMs ?? RESTART_EXIT_TIMEOUT_MS;
+        this.store = store;
+        this.logDir = config.logDir;
+        this.resourceManager = config.resourceManager;
+        this.graphIdentity = config.graphIdentity;
+        this.daemonScope = config.daemonScope;
+        this.livenessProfile = config.livenessProfile;
+        this.getRuntime = config.getRuntime;
+    }
+    /**
+     * The values `processId`'s log read surfaces redact: those this daemon
+     * injected at its last spawn, else its declared credentials resolved now
+     * (an adopted process). A reference that does not resolve fails the read.
+     */
+    async logRedactions(processId) {
+        const injected = this.credentialRedactions.get(processId);
+        if (injected)
+            return injected;
+        return processLogRedactions(this.getRuntime(), await this.store.getConfig(processId), undefined);
+    }
+    /**
+     * Get subprocess reference
+     */
+    getProcess(processId) {
+        return this.processes.get(processId);
+    }
+    /**
+     * Remove subprocess reference
+     */
+    removeProcess(processId) {
+        this.processes.delete(processId);
+    }
+    /**
+     * Clear any pending settle timer for a process. Called whenever
+     * the process exits, is stopped, or is about to be (re)started.
+     */
+    clearSettleTimer(processId) {
+        const cancel = this.settleTimers.get(processId);
+        if (cancel) {
+            cancel();
+            this.settleTimers.delete(processId);
+        }
+    }
+    /** Committed health transitions start or cancel the same-PID settlement window. */
+    observeSettleHealth() {
+        if (this.healthSettleUnsubscribe)
+            return;
+        this.healthSettleUnsubscribe = this.store.onStateChange((state) => {
+            const run = this.healthSettleRuns.get(state.id);
+            if (!run)
+                return;
+            if (state.status !== 'running' || state.pid !== run.pid) {
+                this.healthSettleRuns.delete(state.id);
+                this.clearSettleTimer(state.id);
+                return;
+            }
+            const healthy = state.healthStatus === 'healthy';
+            if (healthy === run.healthy)
+                return;
+            run.healthy = healthy;
+            this.clearSettleTimer(state.id);
+            if (healthy)
+                this.armSettleReset(run.config, run.pid);
+        });
+        this.getRuntime().lifecycle.signal.addEventListener('abort', () => {
+            this.healthSettleUnsubscribe?.();
+            this.healthSettleUnsubscribe = undefined;
+            this.healthSettleRuns.clear();
+            for (const id of this.settleTimers.keys())
+                this.clearSettleTimer(id);
+        }, { once: true });
+    }
+    /** Health-configured runs wait for their first healthy state; others settle on uptime. */
+    scheduleSettleReset(config, pid) {
+        this.clearSettleTimer(config.id);
+        this.healthSettleRuns.delete(config.id);
+        if (config.restartSettleMs <= 0)
+            return;
+        if (config.healthCheck) {
+            this.observeSettleHealth();
+            this.healthSettleRuns.set(config.id, { config, pid, healthy: false });
+        }
+        else {
+            this.armSettleReset(config, pid);
+        }
+    }
+    /** A lifecycle-owned deadline; cancellation also invalidates any in-flight state read. */
+    armSettleReset(config, pid) {
+        const settleMs = config.restartSettleMs;
+        let active = true;
+        const settle = async () => {
+            const settled = await attempt(async () => {
+                const state = await this.store.get(config.id);
+                if (!active || !state || state.status !== 'running' || state.pid !== pid)
+                    return;
+                if (config.healthCheck && state.healthStatus !== 'healthy')
+                    return;
+                if (state.consecutiveCrashRestarts > 0) {
+                    await this.store.update(config.id, { consecutiveCrashRestarts: 0 });
+                    this.log.debug('consecutive crash restart counter reset after settle window', { processId: config.id, settleMs });
+                }
+            });
+            if (this.settleTimers.get(config.id) === cancel)
+                this.settleTimers.delete(config.id);
+            if (!settled.ok) {
+                this.log.warn('settle timer store update failed', { processId: config.id, failure: valueFreeFailure(settled.failure) });
+            }
+        };
+        const deadline = this.getRuntime().lifecycle.timeout(() => void settle(), settleMs);
+        const cancel = () => { active = false; deadline(); };
+        this.settleTimers.set(config.id, cancel);
+    }
+    /** This process's captured log files, joined with the handed runtime's path mechanics. */
+    async getLogPaths(processId) {
+        const path = await getRuntimePath(this.getRuntime());
+        return {
+            stdout: path.join(this.logDir, `${processId}.stdout`),
+            stderr: path.join(this.logDir, `${processId}.stderr`)
+        };
+    }
+    /** The host filesystem the handed runtime resolves (PM's files are host facts at absolute paths). */
+    hostFiles() {
+        return resolveFileSystemAdapter(this.getRuntime(), { binding: false });
+    }
+    async ensureLogDir() {
+        await (await this.hostFiles()).mkdir(this.logDir, { recursive: true });
+    }
+    /** Rotate one of this process's logs through the logging owner under the declared policy. */
+    async rotateLogIfNeeded(logPath) {
+        // The logging owner's Node file rotation, loaded where a spawn first rotates.
+        const { readRotationPolicy, rotateAppendedFile } = await import('@vibesdotdev/logging');
+        const policy = await readRotationPolicy(this.getRuntime(), PM_CAPTURE_ROTATION_POLICY);
+        const result = await rotateAppendedFile(this.getRuntime(), logPath, policy);
+        if (result.rotated)
+            this.log.info('Rotated log file', { logPath, previousSize: result.previousSize });
+    }
+    /**
+     * Record a terminal 'fail' state for a process that never spawned (build
+     * failure, missing cwd, missing command). Shared by the pre-spawn
+     * preflight failure paths so they cannot drift apart.
+     */
+    async markSpawnFailure(processId, lastError) {
+        await this.store.set({
+            id: processId,
+            status: 'fail',
+            restartCount: 0,
+            consecutiveCrashRestarts: 0,
+            retryCount: 0,
+            stoppedAt: new Date(),
+            lastActivity: new Date(),
+            lastError
+        });
+    }
+    /** Idempotent start still records launch cwd/workspace when the stored config omitted them. */
+    async persistLaunchCustody(config) {
+        if (!config.cwd && !config.env?.VIBES_WORKSPACE_PATH)
+            return;
+        const registered = await this.store.getConfig(config.id);
+        if (!launchCustodyNeedsPersist(registered, config))
+            return;
+        const persisted = { ...(registered ?? config) };
+        if (config.cwd)
+            persisted.cwd = config.cwd;
+        persisted.env = { ...registered?.env, ...config.env };
+        await this.store.setConfig(persisted);
+    }
+    async truncateLogs(processId) {
+        const logPaths = await this.getLogPaths(processId);
+        const timestamp = new Date().toISOString();
+        const marker = formatRunStartMarker(timestamp);
+        // Rotate logs past the declared size first (logging owner, L1). A
+        // rotation failure is reported and never costs the new run its logs.
+        const rotated = await attempt(async () => {
+            await this.rotateLogIfNeeded(logPaths.stdout);
+            await this.rotateLogIfNeeded(logPaths.stderr);
+        });
+        if (!rotated.ok) {
+            this.log.warn('Failed to rotate process logs before start', {
+                processId,
+                failure: valueFreeFailure(rotated.failure)
+            });
+        }
+        const files = await this.hostFiles();
+        const truncated = await attempt(async () => {
+            await files.writeFile(logPaths.stdout, marker);
+            await files.writeFile(logPaths.stderr, marker);
+        });
+        if (!truncated.ok) {
+            // A full disk (or any fs failure) silently yielding NO logs is
+            // worse than a failed start: every crash then debugs blind. Match
+            // the rest of this file and surface it.
+            this.log.warn('Failed to truncate/rotate process logs', {
+                processId,
+                failure: valueFreeFailure(truncated.failure)
+            });
+        }
+    }
+    checkRunawaySpawns(config, maxSpawnsPerMinute) {
+        if (config.dangerouslyDisableRunawayChecks) {
+            this.log.warn('Runaway checks disabled', { processId: config.id });
+            return;
+        }
+        const now = Date.now();
+        let times = this.spawnTimes.get(config.id) || [];
+        times = times.filter((t) => t > now - SPAWN_WINDOW_MS);
+        if (times.length >= maxSpawnsPerMinute) {
+            const msg = `RUNAWAY PROCESS: ${times.length + 1} spawns of "${config.id}" in 1 minute (limit: ${maxSpawnsPerMinute})`;
+            this.log.error(msg, { processId: config.id, spawnsInWindow: times.length });
+            throw new CapabilityError(msg, 'RATE_LIMITED', {
+                reason: 'pm-runaway-spawns',
+                retryable: false,
+                details: { processId: config.id, spawnsInWindow: times.length + 1, limit: maxSpawnsPerMinute }
+            });
+        }
+        times.push(now);
+        this.spawnTimes.set(config.id, times);
+    }
+    async waitForSocketReady(socketPath, timeoutMs, processId) {
+        // Poll, bounded by the runtime lifecycle (RC07): the child (owner of the
+        // socket) publishes no cross-process "listening" event.
+        const runtime = this.getRuntime();
+        const ready = await pollUntil(runtime, () => testSocketConnectivity(runtime, socketPath, 500), {
+            timeoutMs,
+            intervalMs: 50,
+            reason: 'pm-process-socket-ready'
+        });
+        if (ready)
+            return;
+        const processInfo = processId ? ` for '${processId}'` : '';
+        throw new CapabilityError(`Socket${processInfo} not ready within ${timeoutMs}ms: endpoint is not accepting connections`, 'TIMEOUT', { reason: 'pm-socket-not-ready', details: { socketPath, timeoutMs } });
+    }
+    decodeHookOutput(output) {
+        return new TextDecoder().decode(output).trim();
+    }
+    formatHookFailureOutput(stdout, stderr) {
+        const stderrTail = this.decodeHookOutput(stderr)
+            .split('\n')
+            .filter(Boolean)
+            .slice(-8)
+            .join('\n');
+        const stdoutTail = this.decodeHookOutput(stdout)
+            .split('\n')
+            .filter(Boolean)
+            .slice(-8)
+            .join('\n');
+        const sections = [
+            stderrTail ? `stderr:\n${stderrTail}` : '',
+            stdoutTail ? `stdout:\n${stdoutTail}` : ''
+        ].filter(Boolean);
+        // Hook output reaches messages, logs and stored state: credentials out, bounded.
+        return redactCredentials(sections.join('\n')).slice(0, HOOK_OUTPUT_MAX_CHARS);
+    }
+    async runPreBuildHook(config) {
+        if (!config.preBuild)
+            return null;
+        const { preBuild } = config;
+        const preBuildCwd = preBuild.cwd || config.cwd || requireRuntimeCwd(this.getRuntime());
+        // A hook is a PM child (C15): the process's declarations and its own.
+        const preBuildEnv = await composePMChildEnv(this.getRuntime(), {
+            env: { ...config.env, ...preBuild.env },
+            inheritEnv: [...(config.inheritEnv ?? []), ...(preBuild.inheritEnv ?? [])],
+            cwd: preBuildCwd
+        });
+        this.log.info('Running pre-build', { processId: config.id, cwd: preBuildCwd });
+        // Async spawn — a sync spawn here blocks the daemon's whole event loop
+        // (RPCs, health checks) for the duration of the hook, and a hung hook
+        // wedges the daemon permanently. The config's timeout is honored
+        // (BuildHookSchema defaults it to 600_000 during parse in start()).
+        const ran = await attempt(() => this.runHookProcess([preBuild.command, ...(preBuild.args || [])], { cwd: preBuildCwd, env: preBuildEnv }, preBuild.timeout, `pre-build for '${config.id}'`));
+        if (!ran.ok) {
+            this.log.error('Pre-build error', { processId: config.id, failure: valueFreeFailure(ran.failure) });
+            throw ran.failure;
+        }
+        const result = ran.value;
+        if (result.exitCode !== 0) {
+            const output = this.formatHookFailureOutput(result.stdout, result.stderr);
+            const cmdStr = [preBuild.command, ...(preBuild.args || [])].join(' ');
+            const detail = output || `command: ${cmdStr}`;
+            this.log.error('Pre-build failed', {
+                processId: config.id,
+                exitCode: result.exitCode,
+                command: cmdStr,
+                output,
+                detail
+            });
+            return result;
+        }
+        this.log.info('Pre-build complete', { processId: config.id });
+        return null;
+    }
+    /**
+     * Run a lifecycle hook command asynchronously with a hard timeout.
+     * On timeout the process gets SIGTERM, then SIGKILL after 2s grace.
+     */
+    async runHookProcess(cmd, opts, timeoutMs, label) {
+        const [command, ...args] = cmd;
+        if (command === undefined) {
+            throw new CapabilityError(`${label} has no command`, 'INVALID_INPUT', { reason: 'pm-hook-command-missing' });
+        }
+        const execution = await getRuntimeExecution(this.getRuntime());
+        const executed = await attempt(() => execution.execute({ command, args, cwd: opts.cwd, env: opts.env, envMode: 'replace', timeout: timeoutMs, killTree: true }));
+        if (!executed.ok) {
+            // The owner refuses a command it cannot start (a missing binary) as a
+            // typed failure; the hook names itself in that rejection.
+            throw new CapabilityError(`${label} failed to start: ${failureText(executed.failure)}`, 'UNAVAILABLE', {
+                reason: 'pm-hook-start-failed',
+                cause: executed.failure
+            });
+        }
+        const result = executed.value;
+        if (result.timedOut) {
+            throw new CapabilityError(`${label} timed out after ${timeoutMs}ms`, 'TIMEOUT', {
+                reason: HOOK_TIMEOUT_REASON,
+                details: { timeoutMs }
+            });
+        }
+        if (result.exitCode === 127) {
+            throw new CapabilityError(`${label} failed to start or could not find its command (exit 127)`, 'UNAVAILABLE', {
+                reason: 'pm-hook-command-not-found'
+            });
+        }
+        return {
+            exitCode: result.exitCode ?? -1,
+            stdout: new TextEncoder().encode(result.stdout),
+            stderr: new TextEncoder().encode(result.stderr)
+        };
+    }
+    async runBuildHook(config) {
+        if (!config.build)
+            return;
+        const { build } = config;
+        const buildCwd = build.cwd || config.cwd || requireRuntimeCwd(this.getRuntime());
+        const buildEnv = await composePMChildEnv(this.getRuntime(), {
+            env: build.env,
+            inheritEnv: [...(config.inheritEnv ?? []), ...(build.inheritEnv ?? [])],
+            cwd: buildCwd
+        });
+        this.log.info('Running build', { processId: config.id, cwd: buildCwd });
+        const ran = await attempt(() => this.runHookProcess([build.command, ...(build.args || [])], { cwd: buildCwd, env: buildEnv }, build.timeout, `build for '${config.id}'`));
+        if (!ran.ok) {
+            this.log.error('Build error', { processId: config.id, failure: valueFreeFailure(ran.failure) });
+            throw ran.failure;
+        }
+        const result = ran.value;
+        if (result.exitCode !== 0) {
+            const output = this.formatHookFailureOutput(result.stdout, result.stderr);
+            const message = `Build failed for '${config.id}' (exit code ${result.exitCode})${output ? `\n${output}` : ''}`;
+            this.log.error('Build failed', { processId: config.id, exitCode: result.exitCode, output });
+            throw new CapabilityError(message, 'UNAVAILABLE', {
+                reason: 'pm-build-failed',
+                details: { processId: config.id, exitCode: result.exitCode }
+            });
+        }
+        this.log.info('Build complete', { processId: config.id });
+    }
+    async ensureLaunchReady(plan, config) {
+        if (!plan.readiness)
+            return;
+        const result = await runCapture(this.getRuntime(), plan.readiness.command, plan.readiness.args, {
+            inheritEnv: plan.readiness.inheritEnv ?? config.inheritEnv,
+            env: config.env, cwd: config.cwd, signal: this.getRuntime().lifecycle.signal
+        });
+        if (result.exitCode !== 0) {
+            throw toolFailure({ tool: plan.readiness.command, action: 'launch readiness', outcome: result });
+        }
+    }
+    async loadConfiguredProcessIds() {
+        if (this.configuredIds)
+            return this.configuredIds;
+        // An unreadable config is an error for the caller, never "nothing is configured".
+        const { readPMGraph } = await import("../graph.js");
+        const graph = await readPMGraph(this.getRuntime());
+        this.configuredIds = new Set(graph.configs.map((c) => c.id));
+        return this.configuredIds;
+    }
+    invalidateConfigCache() {
+        this.configuredIds = null;
+    }
+    /**
+     * The pre-build hook of one start: a failing exit records the failure (and,
+     * under `autoRestart` with attempts left, schedules the retry like a crash)
+     * and refuses the start `pm-prebuild-failed`; `ignoreFailure` only warns.
+     */
+    async runPreBuildStep(config, preBuild) {
+        const preBuildResult = await this.runPreBuildHook(config);
+        if (!preBuildResult || preBuildResult.exitCode === 0)
+            return;
+        const output = this.formatHookFailureOutput(preBuildResult.stdout, preBuildResult.stderr);
+        const cmdStr = [preBuild.command, ...(preBuild.args || [])].join(' ');
+        const detail = output || `command: ${cmdStr}`;
+        const message = `Pre-build failed for '${config.id}' (exit code ${preBuildResult.exitCode})\n${detail}`;
+        const refusal = () => new CapabilityError(message, 'UNAVAILABLE', {
+            reason: 'pm-prebuild-failed',
+            details: { processId: config.id, exitCode: preBuildResult.exitCode }
+        });
+        if (preBuild.ignoreFailure) {
+            this.log.warn(`Pre-build failed but ignoreFailure=true for ${config.id}`, { message });
+            return;
+        }
+        // If autoRestart is enabled, schedule a retry with backoff like a crash
+        if (config.autoRestart) {
+            const existing = await this.store.get(config.id);
+            const policy = processRestartPolicy(await readSupervision(this.getRuntime()), config);
+            const nextAttempt = (existing?.consecutiveCrashRestarts ?? 0) + 1;
+            if (existing && mayRestart(policy, nextAttempt)) {
+                const delay = restartDelayMs(policy, nextAttempt);
+                this.log.info(`preBuild failed, scheduling restart for ${config.id}`, {
+                    attempt: nextAttempt,
+                    maxRestarts: policy.maxConsecutive,
+                    delayMs: delay,
+                    exitCode: preBuildResult.exitCode
+                });
+                await this.store.update(config.id, {
+                    status: 'fail',
+                    consecutiveCrashRestarts: nextAttempt,
+                    lastActivity: new Date(),
+                    lastError: message,
+                    exitCode: preBuildResult.exitCode,
+                    signal: preBuildResult.signal
+                });
+                // Supervision (RC11 class: the daemon restarting its own child),
+                // on the declared policy and a lifecycle one-shot (RC07).
+                this.getRuntime().lifecycle.timeout(() => {
+                    void this.retryAfterPreBuildFailure(config);
+                }, delay);
+                throw refusal();
+            }
+        }
+        // No autoRestart or maxRestarts exceeded. A first start has no row yet.
+        await this.store.upsert(config.id, {
+            status: 'fail',
+            stoppedAt: new Date(),
+            lastActivity: new Date(),
+            lastError: message,
+            exitCode: preBuildResult.exitCode,
+            signal: preBuildResult.signal
+        });
+        throw refusal();
+    }
+    /** The scheduled start after a failed pre-build: its own failure is reported and recorded, nothing awaits it. */
+    async retryAfterPreBuildFailure(config) {
+        const retried = await attempt(() => this.start(config, { resetRestartCount: false }));
+        if (retried.ok)
+            return;
+        this.log.error(`preBuild retry failed for ${config.id}`, { failure: valueFreeFailure(retried.failure) });
+        await this.store.update(config.id, { lastError: `preBuild retry failed: ${failureText(retried.failure)}` });
+    }
+    /**
+     * Start a process
+     */
+    async start(input, options) {
+        const parsed = ProcessConfigSchema.safeParse(input);
+        if (!parsed.success) {
+            throw new CapabilityError('Process configuration is invalid', 'INVALID_INPUT', {
+                reason: 'pm-process-config-invalid',
+                details: { issueCount: parsed.error.issues.length }
+            });
+        }
+        const config = parsed.data;
+        return this.store.withProcessAdmission(config.id, () => this.startAdmitted(config, options));
+    }
+    async startAdmitted(input, options) {
+        // Liveness profile overrides (pm-infra-liveness-fleet): the single choke
+        // point — start, restart, and watch-triggered rebuilds all funnel here.
+        // Only descriptors that declare the active local profile in
+        // livenessProfiles AND ship livenessConfig[profile] overrides change;
+        // everything else spawns exactly as before. The stored config keeps the
+        // canonical (un-overridden) config.
+        const config = applyLivenessOverrides(this.getRuntime(), processLaunchDeclaration(input), this.livenessProfile?.('local'));
+        this.checkRunawaySpawns(config, (await readSupervision(this.getRuntime())).maxSpawnsPerMinute);
+        const existing = await this.store.get(config.id);
+        // CRITICAL: Check if process is already properly running BEFORE orphan scan
+        // This prevents killing our own running process when start is called idempotently
+        if (existing?.pid && (await isProcessRunning(this.getRuntime(), existing.pid))) {
+            if (existing.status === 'running') {
+                // Verify the process is actually on the expected ports (not a recycled PID)
+                const monitoredPorts = await extractMonitoredPorts(this.getRuntime(), config);
+                let processOnExpectedPort = monitoredPorts.length === 0; // No ports = assume OK
+                // Launcher commands (bun, node, npm) never bind the port directly —
+                // their child does (e.g. `bun run vite` → node → vite listens on 8423).
+                // Treat any descendant of the recorded PID as "on expected port" so
+                // healthy launcher-style processes aren't misidentified as PID reuse.
+                const descendants = new Set(await getDescendantPids(this.getRuntime(), existing.pid));
+                for (const port of monitoredPorts) {
+                    const pidOnPort = await findProcessOnPort(this.getRuntime(), port);
+                    if (pidOnPort && (pidOnPort === existing.pid || descendants.has(pidOnPort))) {
+                        processOnExpectedPort = true;
+                        break;
+                    }
+                }
+                if (processOnExpectedPort) {
+                    // Process is healthy - idempotent start, return existing state
+                    this.log.debug('Process already running, returning existing state', {
+                        processId: config.id,
+                        pid: existing.pid
+                    });
+                    await this.persistLaunchCustody(config);
+                    return existing;
+                }
+                // A live pid that has not bound yet is BOOTING while it is inside the
+                // health warmup the config itself declares. Restarting it here made
+                // the orphan scan kill the daemon's own child the moment it bound
+                // (2026-09-05: 48 such kills of mcp-server-dev, boot 32-43 s).
+                if (isWithinStartupWarmup({
+                    startedAt: existing.startedAt,
+                    warmupMs: config.healthCheck?.warmupMs,
+                    now: Date.now()
+                })) {
+                    this.log.info('Process alive and still inside its health warmup; not on its port yet', {
+                        processId: config.id,
+                        pid: existing.pid,
+                        monitoredPorts,
+                        warmupMs: config.healthCheck?.warmupMs ?? null
+                    });
+                    return existing;
+                }
+                // PID is alive but not on expected port - likely PID reuse, continue to orphan scan
+                this.log.warn('Process PID alive but not on expected port, will restart', {
+                    processId: config.id,
+                    pid: existing.pid,
+                    monitoredPorts
+                });
+            }
+            else {
+                // Process has PID but status is not 'running' - it's orphaned in state, kill it
+                await this.store.assertTaskLaunchAvailable(config.id);
+                const orphan = await checkOrphanedByState(this.getRuntime(), config, existing);
+                if (orphan.shouldKill && orphan.pid) {
+                    this.log.warn('Killing orphaned process (state mismatch)', {
+                        processId: config.id,
+                        pid: orphan.pid,
+                        status: existing.status
+                    });
+                    await killProcessTree(this.getRuntime(), orphan.pid, config.id);
+                }
+            }
+        }
+        await this.store.assertTaskLaunchAvailable(config.id);
+        // Reconciliation and persisted custody use the provider's executable identity,
+        // while the declaration retains its request for preparation on every start.
+        const launchPlan = await prepareProcessLaunch(this.getRuntime(), config);
+        const launchConfig = launchPlan ? { ...config, ...launchPlan.process } : config;
+        // NOW it's safe to scan for orphaned processes on ports
+        // This will only kill processes that are NOT our currently running process
+        const orphanResult = await scanAndKillOrphans(this.getRuntime(), launchConfig, existing, this.daemonScope);
+        if (orphanResult.foundOrphans) {
+            this.log.info('Killed orphaned processes on ports', { processId: config.id });
+            // Wait (bounded, RC07) for the ports to report free instead of a fixed
+            // sleep. Poll: the OS offers no port-release event to this process.
+            const runtime = this.getRuntime();
+            const freed = await pollUntil(runtime, async () => (await findPortConflicts(runtime, launchConfig, existing?.pid ?? null)).length === 0, { timeoutMs: 2_000, intervalMs: 50, reason: 'pm-port-release' });
+            if (!freed)
+                this.log.warn('Ports still held after orphan kill; starting anyway', { processId: config.id });
+        }
+        // Check resource dependencies
+        if (this.resourceManager && config.dependencies) {
+            for (const depId of config.dependencies) {
+                const resourceState = await this.resourceManager.getState(depId);
+                if (resourceState && resourceState.status !== 'ready') {
+                    throw new CapabilityError(`Resource '${depId}' not ready (status: ${resourceState.status})`, 'UNAVAILABLE', {
+                        reason: 'pm-resource-not-ready',
+                        details: { resourceId: depId, status: resourceState.status }
+                    });
+                }
+            }
+        }
+        // Check requiresPass dependencies
+        if (config.requiresPass) {
+            for (const depId of config.requiresPass) {
+                const depState = await this.store.get(depId);
+                if (!depState || depState.status !== 'pass') {
+                    const lastError = depState?.lastError;
+                    await this.store.set({
+                        id: config.id,
+                        status: 'waiting',
+                        restartCount: 0,
+                        consecutiveCrashRestarts: 0,
+                        retryCount: 0,
+                        lastError: `Dependency '${depId}' not in pass state${lastError ? `: ${lastError}` : ''}`,
+                        stoppedAt: new Date(),
+                        lastActivity: new Date()
+                    });
+                    throw new CapabilityError(`Dependency '${depId}' not in pass state`, 'CONFLICT', {
+                        reason: 'pm-dependency-not-passed',
+                        details: { processId: config.id, dependency: depId }
+                    });
+                }
+            }
+        }
+        if (!config.socket && existing?.socketPath) {
+            await this.store.update(config.id, { socketPath: undefined });
+        }
+        await this.ensureLogDir();
+        await this.truncateLogs(config.id);
+        // The native owner refuses to remove a live endpoint. A listening process
+        // must be reconciled by identity, never killed just for using this path:
+        // when the socket's serve-lock holder is alive and is this process's own
+        // command, PM adopts it instead of spawning a duplicate the holder refuses.
+        if (config.socket) {
+            const adopted = await this.adoptServeHolder(config);
+            if (adopted)
+                return adopted;
+        }
+        const previousSocket = config.socket || existing?.socketPath;
+        if (previousSocket)
+            await removeSocket(this.getRuntime(), previousSocket);
+        if (launchPlan)
+            await this.ensureLaunchReady(launchPlan, config);
+        // Run pre-build hook if configured
+        const { preBuild } = config;
+        if (preBuild) {
+            const prebuilt = await attempt(() => this.runPreBuildStep(config, preBuild));
+            if (!prebuilt.ok) {
+                // A hook that overran its deadline (typed, never read from message text) is a recorded failure.
+                if (isCapabilityError(prebuilt.failure) && prebuilt.failure.reason === HOOK_TIMEOUT_REASON) {
+                    await this.store.upsert(config.id, {
+                        status: 'fail',
+                        stoppedAt: new Date(),
+                        lastActivity: new Date(),
+                        lastError: failureText(prebuilt.failure),
+                        signal: 'SIGTERM'
+                    });
+                }
+                throw prebuilt.failure;
+            }
+        }
+        if (config.build) {
+            const built = await attempt(() => this.runBuildHook(config));
+            if (!built.ok) {
+                const message = failureText(built.failure);
+                if (!config.build.ignoreFailure) {
+                    await this.markSpawnFailure(config.id, message);
+                    throw built.failure;
+                }
+                this.log.warn(`Build failed but ignoreFailure=true for ${config.id}`, { message });
+            }
+        }
+        const logPaths = await this.getLogPaths(config.id);
+        const runtime = this.getRuntime();
+        const processCwd = config.cwd || requireRuntimeCwd(runtime);
+        // Preflight: verify cwd exists. Without this, posix_spawn fails with
+        // ENOENT and Bun attributes the error to the binary name, which is
+        // misleading ("posix_spawn 'bun'" when the real problem is the cwd).
+        const cwdPresent = await attempt(async () => (await this.hostFiles()).exists(processCwd));
+        if (!cwdPresent.ok || !cwdPresent.value) {
+            const code = cwdPresent.ok ? 'ENOENT' : hasErrnoCode(cwdPresent.failure) ? cwdPresent.failure.code : undefined;
+            const message = code === 'ENOENT'
+                ? `cwd does not exist: '${processCwd}' for '${config.id}'`
+                : `cwd is not accessible (${code ?? 'unknown'}): '${processCwd}' for '${config.id}'`;
+            this.log.error(message, { processId: config.id });
+            await this.markSpawnFailure(config.id, message);
+            throw new CapabilityError(message, code === 'ENOENT' ? 'NOT_FOUND' : 'UNAVAILABLE', {
+                reason: code === 'ENOENT' ? 'pm-cwd-missing' : 'pm-cwd-inaccessible',
+                details: { processId: config.id, cwd: processCwd }
+            });
+        }
+        // C15: PM's base set, the host's re-entry facts and roots, the names the
+        // process inherits, its cwd's `.env`, and its declared env; nothing else.
+        const processEnv = await composePMChildEnv(runtime, {
+            env: config.env,
+            inheritEnv: config.inheritEnv,
+            cwd: processCwd
+        });
+        processEnv.VIBES_PM_MANAGED = config.id;
+        // Stamp the MODULE GRAPH this child is about to import, so the
+        // executable-freshness reconciler's second predicate compares against
+        // what this child actually loaded rather than a wall-clock guess: a
+        // `bun install` that rewrites an identical lock must not roll the fleet,
+        // and a genuine `vibes update` must roll every body spawned before it.
+        // `VIBES_HOST_ROOT` may already be in `processEnv` (inherited, or set by
+        // the process config) — the child's own root wins over the daemon's.
+        {
+            const childHostRoot = processEnv.VIBES_HOST_ROOT?.trim() || this.graphIdentity?.()?.root || undefined;
+            if (childHostRoot) {
+                processEnv.VIBES_HOST_ROOT = childHostRoot;
+                const digest = this.graphIdentity?.(childHostRoot)?.digest;
+                if (digest)
+                    processEnv.VIBES_HOST_GRAPH_LOCK = digest;
+            }
+        }
+        const processCommand = launchPlan?.process ?? resolveProcessCommand(config, config.selfSpawn ? await getRuntimeHostCommands(runtime) : undefined);
+        // Preflight: verify command exists before spawning to prevent crash-loops.
+        // Async capture (sync spawn blocks the daemon's event loop); resolves the
+        // absolute path so spawn cannot disagree with the preflight.
+        const resolvedCommand = await whichCommand(runtime, processCommand.command, {
+            env: processEnv,
+            cwd: processCwd
+        });
+        if (!resolvedCommand) {
+            const message = `Command '${processCommand.command}' not found in PATH for '${config.id}'`;
+            this.log.error(message, { processId: config.id });
+            await this.markSpawnFailure(config.id, message);
+            throw new CapabilityError(message, 'NOT_FOUND', {
+                reason: 'pm-command-not-found',
+                details: { processId: config.id, command: processCommand.command }
+            });
+        }
+        // RC05: the declared credentials resolve through `resolveCredentialEnv`
+        // before anything spawns; a reference that does not resolve fails the
+        // start typed. Only the credential variables layer onto the C15 env
+        // (they win over a same-named declared or inherited value). Values stay
+        // out of argv and out of the stored config (stamped from `config.env`).
+        const resolvedCredentials = await attempt(() => resolveProcessCredentials(runtime, config));
+        if (!resolvedCredentials.ok) {
+            await this.markSpawnFailure(config.id, failureText(resolvedCredentials.failure));
+            throw resolvedCredentials.failure;
+        }
+        const credentials = resolvedCredentials.value;
+        const childEnv = credentials ? { ...processEnv, ...credentials.values } : processEnv;
+        // Pass the preflight-resolved absolute path so spawn cannot disagree
+        // with the preflight about which binary (or whether any) is on PATH.
+        const spawned = await attempt(async () => (await getRuntimeExecution(runtime)).spawn({
+            command: resolvedCommand, args: processCommand.args,
+            cwd: processCwd, env: childEnv, envMode: 'replace',
+            stdoutFile: logPaths.stdout, stderrFile: logPaths.stderr
+        }));
+        if (!spawned.ok) {
+            credentials?.audit('failure');
+            throw spawned.failure;
+        }
+        const proc = spawned.value;
+        if (proc.pid <= 0) {
+            credentials?.audit('failure');
+            const message = `Failed to spawn '${config.id}'`;
+            await this.markSpawnFailure(config.id, message);
+            throw new CapabilityError(message, 'UNAVAILABLE', {
+                reason: 'pm-spawn-failed',
+                details: { processId: config.id }
+            });
+        }
+        if (credentials) {
+            credentials.audit('success');
+            this.credentialRedactions.set(config.id, credentials.redact);
+        }
+        else {
+            this.credentialRedactions.delete(config.id);
+        }
+        proc.unref?.();
+        const exitPromise = proc.exited.then(exitOf);
+        // Persist config only after successful spawn to avoid config write storms
+        // during repeated failed starts (e.g. dependency preflight failures).
+        // Stamp the config with VIBES_HOST_ROOT and VIBES_HOST_GRAPH_LOCK so the
+        // executable-freshness reconciler can detect when the graph has changed.
+        // Merge onto the DECLARED config.env (never the resolved processEnv,
+        // which may hold resolved secret values) so other env keys the config
+        // declared survive registration.
+        const stampedEnv = { ...config.env };
+        if (processEnv.VIBES_HOST_ROOT)
+            stampedEnv.VIBES_HOST_ROOT = processEnv.VIBES_HOST_ROOT;
+        if (processEnv.VIBES_HOST_GRAPH_LOCK)
+            stampedEnv.VIBES_HOST_GRAPH_LOCK = processEnv.VIBES_HOST_GRAPH_LOCK;
+        // The child's workspace is its launch custody (the admitted root PM bound
+        // as its cwd), never a value this daemon inherited.
+        if (!stampedEnv.VIBES_WORKSPACE_PATH)
+            stampedEnv.VIBES_WORKSPACE_PATH = processCwd;
+        const stampedConfig = { ...launchConfig, cwd: config.cwd ?? processCwd, env: stampedEnv };
+        await this.store.setConfig({
+            ...stampedConfig,
+            launchProvenance: {
+                declaration: ProcessLaunchInputsSchema.parse(config),
+                prepared: ProcessLaunchInputsSchema.parse(stampedConfig)
+            }
+        });
+        const configured = await this.loadConfiguredProcessIds();
+        const isEphemeral = !configured.has(config.id);
+        const now = new Date();
+        const shouldResetCount = options?.resetRestartCount ?? true;
+        if (shouldResetCount)
+            this.tempfailAttempts.delete(config.id);
+        const state = {
+            id: config.id,
+            pid: proc.pid,
+            status: 'running',
+            startedAt: now,
+            lastActivity: now,
+            restartCount: (existing?.restartCount ?? 0) + 1,
+            consecutiveCrashRestarts: shouldResetCount ? 0 : (existing?.consecutiveCrashRestarts ?? 0),
+            retryCount: existing?.retryCount || 0,
+            healthStatus: 'unknown',
+            socketPath: config.socket || undefined,
+            idleTimeoutMs: config.idleTimeoutMs,
+            ephemeral: isEphemeral || undefined
+        };
+        await this.store.set(state);
+        this.processes.set(config.id, proc);
+        this.monitorProcess(config, proc, exitPromise);
+        // Schedule the settle timer so the restart counter resets after
+        // the process has been running stably. If the process exits
+        // before the timer fires, monitorProcess() clears the timer.
+        this.scheduleSettleReset(config, proc.pid);
+        if (options?.wait && config.socket) {
+            await this.waitForSocketReady(config.socket, options.timeout || 30000, config.id);
+        }
+        return state;
+    }
+    /**
+     * Monitor process for exit and handle auto-restart
+     */
+    monitorProcess(config, proc, exitPromise = proc.exited.then(exitOf)) {
+        const settled = this.settleExit(config, proc, exitPromise);
+        const exit = { pid: proc.pid, settled };
+        this.exits.set(config.id, exit);
+        void settled.then(() => {
+            if (this.exits.get(config.id) === exit)
+                this.exits.delete(config.id);
+        });
+    }
+    /**
+     * Wait for the process to exit and handle it. The exit handler's own
+     * failures must never surface as an unhandledRejection: daemon.ts treats
+     * those as fatal (handleFatalError → process.exit(1)), so a transient SQLite
+     * error during exit handling would take down every managed process, the
+     * exact single-failure shape the 2026-09-02 incident hardening exists to
+     * prevent. They are reported, and a best-effort state marker is left.
+     */
+    async settleExit(config, proc, exitPromise) {
+        const handled = await attempt(async () => this.handleExit(config, proc, await exitPromise));
+        if (handled.ok)
+            return;
+        const facts = valueFreeFailure(handled.failure);
+        // The report and the marker are the last channels this failure has: the
+        // runtime's logging or store may be gone (disposal), and nothing further
+        // may reject, so a failure of either is dropped here and nowhere else.
+        await attempt(async () => this.log.error('exit handler failed', { processId: config.id, exitedPid: proc.pid, failure: facts }));
+        // Guarded like every terminal write: a record another writer already
+        // committed for this run (stop(), or the handler before it threw) stands.
+        const marked = await attempt(() => this.store.updateWhen(config.id, {
+            status: 'crashed',
+            stoppedAt: new Date(),
+            lastActivity: new Date(),
+            pid: undefined,
+            lastError: `Exit handler error: ${failureText(handled.failure)}`
+        }, (current) => !isProcessExited(current) && current.pid === proc.pid));
+        if (!marked.ok) {
+            await attempt(async () => this.log.error('exit handler best-effort state write also failed', {
+                processId: config.id,
+                failure: valueFreeFailure(marked.failure)
+            }));
+        }
+    }
+    /**
+     * Commit this exit's terminal record, deciding its branch from the row as
+     * read. The row can change between that read and the write (`stop()` writes
+     * `stopping`, or commits `stopped` itself when its bounded wait for this
+     * handler expired), so every terminal write is guarded on the row it was
+     * decided from: same status, same pid. A refused write wrote nothing; the
+     * handler re-reads and decides again, so the run gets exactly one truthful
+     * record and a run an operator stopped is never recorded `crashed`.
+     *
+     * Returns the row a service's own record landed over, with the error it
+     * recorded, for restart supervision; `undefined` when nothing is left to
+     * supervise (stale handle, a stop's record, a task's record, or a record
+     * another writer already committed).
+     */
+    async commitExitRecord(config, proc, exit) {
+        const { code: exitCode, signal } = exit;
+        const crashed = exitCode !== 0;
+        let errorMessage;
+        let crashDetailRead = false;
+        let refused = false;
+        for (let state = await this.store.get(config.id); state; state = await this.store.get(config.id)) {
+            // Ignore exits from stale subprocess handles after a restart.
+            // Without this guard, an older PID exiting can overwrite state for a newer running PID
+            // and trigger unintended auto-restart loops.
+            if (state.pid && proc.pid && state.pid !== proc.pid) {
+                this.log.debug('Ignoring stale subprocess exit', {
+                    processId: config.id,
+                    exitedPid: proc.pid,
+                    activePid: state.pid,
+                    exitCode
+                });
+                return undefined;
+            }
+            if ((state.status === 'stopped' && state.pid === undefined) || (refused && isProcessExited(state))) {
+                // Another writer already committed this run's terminal record:
+                // stop(), when this exit was not observed within its bound. The
+                // record stays the only one; the late exit only clears a socket
+                // the child left behind.
+                this.log.debug('Late exit of a run whose stop is already committed', { processId: config.id, exitCode });
+                if (exitCode !== 0 && state.socketPath) {
+                    await removeSocket(this.getRuntime(), state.socketPath);
+                    await this.store.update(config.id, { staleSocket: true });
+                }
+                this.processes.delete(config.id);
+                return undefined;
+            }
+            const read = state;
+            const unchanged = (current) => current.status === read.status && current.pid === read.pid;
+            if (read.status === 'stopping') {
+                // An operator stop is ending this run: it awaits this record. A
+                // child that did not exit cleanly left its socket behind; clear it
+                // before the record commits, so an awaiter never sees a stale path.
+                const staleSocket = exitCode !== 0 && read.socketPath ? read.socketPath : undefined;
+                if (staleSocket)
+                    await removeSocket(this.getRuntime(), staleSocket);
+                const landed = await this.store.updateWhen(config.id, {
+                    status: 'stopped',
+                    stoppedAt: new Date(),
+                    lastActivity: new Date(),
+                    exitCode,
+                    signal,
+                    pid: undefined,
+                    staleSocket: staleSocket ? true : undefined
+                }, unchanged);
+                if (landed) {
+                    this.processes.delete(config.id);
+                    return undefined;
+                }
+            }
+            else if (config.task) {
+                const landed = await this.store.updateWhen(config.id, {
+                    status: exitCode === 0 ? 'pass' : 'fail',
+                    stoppedAt: new Date(),
+                    lastActivity: new Date(),
+                    exitCode,
+                    signal,
+                    lastError: exitCode !== 0 ? `Exit code ${exitCode}` : undefined
+                }, unchanged);
+                if (landed) {
+                    this.processes.delete(config.id);
+                    return undefined;
+                }
+            }
+            else {
+                if (crashed && !crashDetailRead) {
+                    crashDetailRead = true;
+                    errorMessage = await this.crashDetail(config.id, exitCode);
+                }
+                const landed = await this.store.updateWhen(config.id, {
+                    status: config.runOnce && !crashed ? 'completed' : crashed ? 'crashed' : 'stopped',
+                    stoppedAt: new Date(),
+                    lastActivity: new Date(),
+                    exitCode,
+                    signal,
+                    pid: undefined,
+                    lastError: errorMessage
+                }, unchanged);
+                if (landed)
+                    return { state: read, errorMessage };
+            }
+            // The row changed after this handler read it: decide again from the row as it stands.
+            refused = true;
+        }
+        return undefined;
+    }
+    /** `Exit code N`, with a bounded, redacted excerpt of the child's last stderr lines when readable. */
+    async crashDetail(processId, exitCode) {
+        const tail = await attempt(async () => {
+            const logPaths = await this.getLogPaths(processId);
+            return readTail(await this.hostFiles(), logPaths.stderr, CRASH_DETAIL_TAIL_BYTES);
+        });
+        if (!tail.ok) {
+            this.log.debug('Failed to read stderr log for crash details', {
+                processId,
+                failure: valueFreeFailure(tail.failure)
+            });
+            return `Exit code ${exitCode}`;
+        }
+        const lastLines = tail.value
+            .trim()
+            .split('\n')
+            .slice(-5)
+            .filter((l) => l.trim());
+        if (lastLines.length === 0)
+            return `Exit code ${exitCode}`;
+        // Persisted and printed by `pm list`: a bounded excerpt with the
+        // credentials this daemon injected (and credential shapes) removed.
+        const excerpt = redactedExcerpt(lastLines.join(' | '), {
+            maxChars: 400,
+            secrets: this.credentialRedactions.get(processId) ?? []
+        });
+        return `Exit code ${exitCode}: ${excerpt}`;
+    }
+    /**
+     * One process exit: stale-handle guard, state write, socket cleanup, and
+     * the restart supervision. While PM holds the child's handle this is the
+     * single writer of the run's terminal record: a run `stop()` put in
+     * `stopping` commits exactly one record here, `stopped` with the real exit.
+     */
+    async handleExit(config, proc, exit) {
+        // Always clear the settle timer for this process id on exit —
+        // a stale timer from a previous incarnation could otherwise
+        // reset the restart counter of the new one mid-crash-loop.
+        this.clearSettleTimer(config.id);
+        const committed = await this.commitExitRecord(config, proc, exit);
+        if (!committed)
+            return;
+        const { state, errorMessage } = committed;
+        const { code: exitCode } = exit;
+        const crashed = exitCode !== 0;
+        // CRITICAL FIX (Issue 4.4): Port-forward processes now use same restart logic as others
+        // Previously they had special 2s sleep here that didn't participate in auto-restart backoff
+        // Now they rely on the auto-restart loop below which applies proper exponential backoff
+        this.processes.delete(config.id);
+        if (crashed && state.socketPath) {
+            await removeSocket(this.getRuntime(), state.socketPath);
+            await this.store.update(config.id, { staleSocket: true });
+        }
+        const tempfail = exitCode === EX_TEMPFAIL;
+        if (!tempfail)
+            this.tempfailAttempts.delete(config.id);
+        if (config.autoRestart && tempfail) {
+            if (state.status === 'stopped')
+                return;
+            const retryAttempt = (this.tempfailAttempts.get(config.id) ?? 0) + 1;
+            this.tempfailAttempts.set(config.id, retryAttempt);
+            const delay = tempfailRestartDelay(retryAttempt, config.restartDelay, this.tempfailMinDelayMs);
+            this.log.warn(`${config.id} exited EX_TEMPFAIL; retrying without counting toward maxRestarts`, {
+                attempt: retryAttempt,
+                delayMs: delay
+            });
+            await this.store.update(config.id, {
+                lastError: `${errorMessage} (EX_TEMPFAIL: retry ${retryAttempt} in ${Math.round(delay / 1000)}s)`
+            });
+            await this.restartAfterBackoff(config, proc.pid, delay);
+            return;
+        }
+        if (config.autoRestart && crashed) {
+            if (state.status === 'stopped') {
+                this.log.debug('Process intentionally stopped, skipping auto-restart', {
+                    processId: config.id
+                });
+                return;
+            }
+            // Supervision (RC11 class: the daemon restarting a child it owns):
+            // the declared policy (`config.plugins.pm.supervision`, the
+            // process's own `restartDelay`/`maxRestarts` winning), paused on
+            // a tracked, disposal-aborted lifecycle delay (RC07).
+            const policy = processRestartPolicy(await readSupervision(this.getRuntime()), config);
+            const nextAttempt = state.consecutiveCrashRestarts + 1;
+            const maxRestarts = policy.maxConsecutive;
+            if (mayRestart(policy, nextAttempt)) {
+                const delay = restartDelayMs(policy, nextAttempt);
+                this.log.info(`Auto-restarting ${config.id}`, {
+                    attempt: nextAttempt,
+                    maxRestarts,
+                    delayMs: delay
+                });
+                await this.restartAfterBackoff(config, proc.pid, delay, async () => {
+                    await this.store.update(config.id, { consecutiveCrashRestarts: nextAttempt });
+                });
+            }
+            else {
+                this.log.warn(`${config.id} exceeded max restarts`, { maxRestarts });
+                await this.store.update(config.id, {
+                    lastError: `${errorMessage} (max restarts exceeded)`
+                });
+            }
+        }
+    }
+    /**
+     * Stop a process
+     */
+    /**
+     * Adopt a live process already serving `config.socket`: the serve singleton
+     * records its holder in `<socket>.pid`. Only a live holder whose command line
+     * is this config's own (PM's ownership check) is adopted; anything else is
+     * left for the socket owner to refuse.
+     */
+    async adoptServeHolder(config) {
+        const socket = config.socket;
+        if (!socket)
+            return null;
+        const holderFile = await attempt(async () => PidFileTextSchema.parse(await (await this.hostFiles()).readFile(`${socket}.pid`, 'utf-8')));
+        if (!holderFile.ok) {
+            if (hasErrnoCode(holderFile.failure) && holderFile.failure.code === 'ENOENT')
+                return null;
+            throw holderFile.failure;
+        }
+        const pid = Number.parseInt(holderFile.value.trim(), 10);
+        if (!Number.isFinite(pid) || pid <= 0)
+            return null;
+        if (!(await isProcessRunning(this.getRuntime(), pid)))
+            return null;
+        const tokens = [config.command, ...(config.args || [])].filter(Boolean);
+        const ownership = await verifyProcessOwnership(this.getRuntime(), pid, config.id, tokens);
+        if (!ownership.owned)
+            return null;
+        this.log.warn('Adopting the live serve holder instead of spawning a duplicate', {
+            processId: config.id,
+            pid,
+            socket
+        });
+        // The holder may have no state row (stale cleanup removes a terminal row
+        // and its config; config reload re-registers only the config): upsert.
+        await this.store.upsert(config.id, {
+            status: 'running',
+            pid,
+            socketPath: socket,
+            startedAt: new Date(),
+            lastActivity: new Date()
+        });
+        return (await this.store.get(config.id)) ?? null;
+    }
+    async stop(processId, options) {
+        const requested = options?.run ? ProcessRunSchema.parse(options.run) : undefined;
+        const assertRequestedRun = (current) => {
+            if (requested && (!current || !isSameRun(current, requested)))
+                throw new CapabilityError('The requested process run was superseded.', 'CONFLICT', {
+                    reason: 'pm-stop-run-superseded', details: { processId }
+                });
+        };
+        const state = await this.store.get(processId);
+        assertRequestedRun(state);
+        // Only the admitted run may lose its settle timer.
+        this.clearSettleTimer(processId);
+        if (!state?.pid) {
+            throw new CapabilityError(`Process ${processId} is not running`, 'CONFLICT', {
+                reason: 'process-not-running',
+                details: { processId }
+            });
+        }
+        // Every write below is guarded against the row as it stands at the write:
+        // the child may exit on its own while stop() awaits (the liveness probe,
+        // the ownership check, the kill), and its exit handler's terminal record
+        // is then the run's one record. stop() never writes over it.
+        const sameRun = (current) => current.pid === state.pid && (!state.startedAt || isSameRun(current, { startedAt: state.startedAt }));
+        const live = (current) => sameRun(current) && !isProcessExited(current);
+        const handle = this.processes.get(processId);
+        const forget = () => { if (this.processes.get(processId) === handle)
+            this.processes.delete(processId); };
+        // PM's handle on this run's child, captured before any await: the entry
+        // leaves the map once its exit handling settles. While it is held, that
+        // handler is the single writer of the run's terminal record, so every
+        // branch below awaits it before its own guarded write.
+        const held = this.exits.get(processId);
+        const exit = held && held.pid === state.pid ? held : undefined;
+        const running = await isProcessRunning(this.getRuntime(), state.pid);
+        if (requested)
+            assertRequestedRun(await this.store.get(processId));
+        if (!running) {
+            // A dead pid PM holds a handle for: its exit handler may be in flight
+            // (its read or write not yet landed). It commits the real record.
+            if (exit)
+                await this.awaitExitHandled(processId, exit.settled);
+            await this.store.updateWhen(processId, { status: 'stopped', stoppedAt: new Date(), lastActivity: new Date(), pid: undefined }, live);
+            forget();
+            return;
+        }
+        const config = await this.store.getConfig(processId);
+        if (requested)
+            assertRequestedRun(await this.store.get(processId));
+        const tokens = config ? [config.command, ...(config.args || [])].filter(Boolean) : [processId];
+        const ownership = await verifyProcessOwnership(this.getRuntime(), state.pid, processId, tokens);
+        if (!ownership.owned) {
+            this.log.warn('PID no longer belongs to process', { processId, pid: state.pid });
+            // A dead pid fails the ownership check too: an in-flight exit handler
+            // still commits this run's record first.
+            if (exit)
+                await this.awaitExitHandled(processId, exit.settled);
+            await this.store.updateWhen(processId, {
+                status: 'stopped',
+                stoppedAt: new Date(),
+                lastActivity: new Date(),
+                pid: undefined,
+                lastError: `PID ${state.pid} reused`
+            }, live);
+            forget();
+            return;
+        }
+        // A run whose terminal record landed while stop() awaited stays ended.
+        const stopping = await this.store.updateWhen(processId, { status: 'stopping' }, live);
+        if (!stopping) {
+            const current = await this.store.get(processId);
+            if (current && !sameRun(current) && !isProcessExited(current)) {
+                throw new CapabilityError('The requested process run was superseded.', 'CONFLICT', {
+                    reason: 'pm-stop-run-superseded', details: { processId }
+                });
+            }
+            forget();
+            return;
+        }
+        const timeout = options?.timeout || 5000;
+        if (options?.force) {
+            await killProcessTree(this.getRuntime(), state.pid, processId);
+        }
+        else {
+            // Graceful path must reap the whole tree — spawn'd grandchildren
+            // (e.g. typescript-language-server, tsserver.js under the LSP runtime)
+            // don't die when the parent gets SIGTERM and are reparented to init.
+            await gracefulKillProcessTree(this.getRuntime(), state.pid, processId, timeout);
+        }
+        // PM holds this child's handle: its exit handler is the single writer of
+        // the run's terminal record (`stopped` with the real exit code). When it
+        // settled without committing one (it ignored the exit as stale), or there
+        // is no handle (an adopted process), or its exit was not observed within
+        // the bound, stop() commits `stopped` itself, still only over a live row.
+        if (exit)
+            await this.awaitExitHandled(processId, exit.settled);
+        await this.store.updateWhen(processId, { status: 'stopped', stoppedAt: new Date(), lastActivity: new Date(), pid: undefined }, live);
+        forget();
+    }
+    /**
+     * Await the killed child's exit handling, at most the restart exit bound:
+     * a kill the child survived must not hang its stop forever.
+     */
+    async awaitExitHandled(processId, settled) {
+        const waited = await attempt(() => this.getRuntime().lifecycle.wait(() => settled, {
+            timeoutMs: this.restartExitTimeoutMs,
+            reason: 'pm-stop-exit-handled'
+        }));
+        if (waited.ok)
+            return;
+        if (!isWaitTimeout(waited.failure))
+            throw waited.failure;
+        this.log.warn('Stopped child exit was not observed within the bound; recording the stop', {
+            processId,
+            timeoutMs: this.restartExitTimeoutMs
+        });
+    }
+    /**
+     * Pause `delay` on the handed runtime's lifecycle (RC07: tracked, aborted
+     * at disposal), then start `config` again unless a newer instance already
+     * runs. `beforeStart` records the attempt only when the restart proceeds.
+     *
+     * Another starter (an operator's `pm start`, a preset, the health
+     * monitor's kill of the previous incarnation) may have brought a NEW
+     * instance up while this waited. Starting again would kill it as a port
+     * orphan, and its exit would schedule yet another restart, so two loops
+     * ping-pong (pm log 2026-08-28: mcp-server-dev attempts 1,2,3 interleaved
+     * with 1,4,2,3,5,4,6,5,7,6, each killing the other's child on port 3000).
+     * The exited pid is ours; a different live pid is someone else's success.
+     */
+    async restartAfterBackoff(config, exitedPid, delay, beforeStart) {
+        await this.getRuntime().lifecycle.delay(delay);
+        const latest = await this.store.get(config.id);
+        if (latest?.status === 'running' &&
+            latest.pid !== undefined &&
+            latest.pid !== exitedPid &&
+            (await isProcessRunning(this.getRuntime(), latest.pid))) {
+            this.log.info(`Skipping auto-restart of ${config.id}: a newer instance is already running`, {
+                pid: latest.pid,
+                exitedPid
+            });
+            return;
+        }
+        await beforeStart?.();
+        const restarted = await attempt(() => this.start(config, { resetRestartCount: false }));
+        if (!restarted.ok) {
+            this.log.error(`Auto-restart failed for ${config.id}`, { failure: valueFreeFailure(restarted.failure) });
+            await this.store.update(config.id, { lastError: `Restart failed: ${failureText(restarted.failure)}` });
+        }
+    }
+    /**
+     * Restart a process
+     */
+    async restart(processId, options) {
+        return this.store.withProcessAdmission(processId, async () => {
+            await this.store.assertTaskReleaseAvailable(processId);
+            return this.restartAdmitted(processId, options);
+        });
+    }
+    async restartAdmitted(processId, options) {
+        const config = await this.store.getConfig(processId);
+        if (!config) {
+            throw new CapabilityError(`Process config not found: ${processId}`, 'NOT_FOUND', {
+                reason: 'pm-process-not-registered',
+                details: { processId }
+            });
+        }
+        const state = await this.store.get(processId);
+        if (state?.pid && (await isProcessRunning(this.getRuntime(), state.pid))) {
+            await this.stop(processId);
+            if (!(await waitForProcessExit(this.getRuntime(), state.pid, this.restartExitTimeoutMs))) {
+                throw new CapabilityError(`Failed to stop ${processId} (PID ${state.pid}) before restart`, 'UNAVAILABLE', {
+                    reason: 'pm-process-stop-failed',
+                    details: { processId, pid: state.pid }
+                });
+            }
+        }
+        return this.start(config, options);
+    }
+}
+//# sourceMappingURL=lifecycle.js.map