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

package/dist/services/lifecycle.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Process Lifecycle Service
+ * Handles start, stop, restart, and monitoring of processes
+ */
+import { type VibesRuntime } from '@vibesdotdev/kernel';
+import type { DaemonScope } from '../utils/port-ownership.ts';
+import { type ProcessHandle } from '@vibesdotdev/kernel/execution';
+import { type ProcessConfig, type ProcessState } from '../schemas/process.ts';
+import type { ProcessStore } from '../store.impl.consumer.ts';
+import type { ResourceManager } from '../managers/resource-manager.ts';
+import { type ActiveLivenessProfile } from './liveness-state.ts';
+export interface LifecycleConfig {
+    logDir: string;
+    /**
+     * The runtime the owning manager was handed, as a getter so registry reads
+     * follow hot-reload generations: PM config reads and spawn cwds use it.
+     */
+    getRuntime: () => VibesRuntime;
+    resourceManager?: ResourceManager;
+    graphIdentity?: (root?: string) => {
+        root: string;
+        digest: string | null;
+    } | null;
+    /**
+     * The declared scope of the daemon this lifecycle runs in, which proves a
+     * port holder ours (utils/port-ownership.ts). Absent, no holder is.
+     */
+    daemonScope?: DaemonScope;
+    /**
+     * The daemon's active liveness profile (`LivenessProfiles.get`). Absent
+     * (a manager outside a daemon), no profile overrides apply.
+     */
+    livenessProfile?: ActiveLivenessProfile;
+    /** Floor of the EX_TEMPFAIL backoff (default {@link TEMPFAIL_MIN_DELAY_MS}; tests shorten it). */
+    tempfailMinDelayMs?: number;
+    /** How long a restart waits for the stopped run's pid to exit (default {@link RESTART_EXIT_TIMEOUT_MS}; tests shorten it). */
+    restartExitTimeoutMs?: number;
+}
+/**
+ * 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 declare const EX_TEMPFAIL = 75;
+export declare const TEMPFAIL_MIN_DELAY_MS = 5000;
+export declare const TEMPFAIL_MAX_DELAY_MS: number;
+/** How long a restart waits for the stopped run's pid to exit before it refuses `pm-process-stop-failed`. */
+export declare const RESTART_EXIT_TIMEOUT_MS = 5000;
+/** The delay before EX_TEMPFAIL retry `attempt` (1-based): max(restartDelay, floor) doubling, capped at five minutes. */
+export declare function tempfailRestartDelay(attempt: number, restartDelay: number | undefined, minDelayMs?: number): number;
+export interface StartOptions {
+    wait?: boolean;
+    timeout?: number;
+    resetRestartCount?: boolean;
+}
+export type { StopOptions } from '../interface.ts';
+import type { StopOptions } from '../interface.ts';
+/**
+ * Process Lifecycle Service manages process start/stop/restart
+ */
+export declare class LifecycleService {
+    private store;
+    private readonly getRuntime;
+    private logDir;
+    private resourceManager?;
+    private graphIdentity?;
+    private daemonScope?;
+    private livenessProfile?;
+    private processes;
+    private spawnTimes;
+    private configuredIds;
+    /**
+     * 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.
+     */
+    private settleTimers;
+    private readonly healthSettleRuns;
+    private healthSettleUnsubscribe?;
+    /** The credential values injected at each process's last spawn by this daemon (RC05), for log redaction. */
+    private readonly credentialRedactions;
+    /** Consecutive EX_TEMPFAIL exits per process; cleared by any other exit or an operator start. */
+    private readonly tempfailAttempts;
+    private readonly tempfailMinDelayMs;
+    private readonly restartExitTimeoutMs;
+    /** The exit handling of each child PM holds a handle for, by process id: `stop()` awaits it. */
+    private readonly exits;
+    /** The handed runtime's Logging, read per entry so it follows hot-reload generations (C083a). */
+    private get log();
+    /** `store` holds both state and each process's registered/launched config (pm.md K8). */
+    constructor(store: ProcessStore, config: LifecycleConfig);
+    /**
+     * 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.
+     */
+    logRedactions(processId: string): Promise<readonly string[]>;
+    /**
+     * Get subprocess reference
+     */
+    getProcess(processId: string): ProcessHandle | undefined;
+    /**
+     * Remove subprocess reference
+     */
+    removeProcess(processId: string): void;
+    /**
+     * Clear any pending settle timer for a process. Called whenever
+     * the process exits, is stopped, or is about to be (re)started.
+     */
+    private clearSettleTimer;
+    /** Committed health transitions start or cancel the same-PID settlement window. */
+    private observeSettleHealth;
+    /** Health-configured runs wait for their first healthy state; others settle on uptime. */
+    private scheduleSettleReset;
+    /** A lifecycle-owned deadline; cancellation also invalidates any in-flight state read. */
+    private armSettleReset;
+    /** This process's captured log files, joined with the handed runtime's path mechanics. */
+    private getLogPaths;
+    /** The host filesystem the handed runtime resolves (PM's files are host facts at absolute paths). */
+    private hostFiles;
+    private ensureLogDir;
+    /** Rotate one of this process's logs through the logging owner under the declared policy. */
+    private rotateLogIfNeeded;
+    /**
+     * 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.
+     */
+    private markSpawnFailure;
+    /** Idempotent start still records launch cwd/workspace when the stored config omitted them. */
+    private persistLaunchCustody;
+    private truncateLogs;
+    private checkRunawaySpawns;
+    private waitForSocketReady;
+    private decodeHookOutput;
+    private formatHookFailureOutput;
+    private runPreBuildHook;
+    /**
+     * Run a lifecycle hook command asynchronously with a hard timeout.
+     * On timeout the process gets SIGTERM, then SIGKILL after 2s grace.
+     */
+    private runHookProcess;
+    private runBuildHook;
+    private ensureLaunchReady;
+    loadConfiguredProcessIds(): Promise<Set<string>>;
+    invalidateConfigCache(): void;
+    /**
+     * 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.
+     */
+    private runPreBuildStep;
+    /** The scheduled start after a failed pre-build: its own failure is reported and recorded, nothing awaits it. */
+    private retryAfterPreBuildFailure;
+    /**
+     * Start a process
+     */
+    start(input: ProcessConfig, options?: StartOptions): Promise<ProcessState>;
+    private startAdmitted;
+    /**
+     * Monitor process for exit and handle auto-restart
+     */
+    private monitorProcess;
+    /**
+     * 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.
+     */
+    private settleExit;
+    /**
+     * 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).
+     */
+    private commitExitRecord;
+    /** `Exit code N`, with a bounded, redacted excerpt of the child's last stderr lines when readable. */
+    private crashDetail;
+    /**
+     * 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.
+     */
+    private handleExit;
+    /**
+     * 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.
+     */
+    private adoptServeHolder;
+    stop(processId: string, options?: StopOptions): Promise<void>;
+    /**
+     * Await the killed child's exit handling, at most the restart exit bound:
+     * a kill the child survived must not hang its stop forever.
+     */
+    private awaitExitHandled;
+    /**
+     * 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.
+     */
+    private restartAfterBackoff;
+    /**
+     * Restart a process
+     */
+    restart(processId: string, options?: StartOptions): Promise<ProcessState>;
+    private restartAdmitted;
+}
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/services/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/services/lifecycle.ts"],"names":[],"mappings":"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"}