/**
 * Instance runtime lifecycle management for Iranti.
 *
 * Manages the runtime.json sidecar file that each managed Iranti instance
 * writes on startup and updates during its lifetime. The file records PID,
 * port, version, heartbeat timestamps, and lifecycle status so the CLI and
 * control plane can determine whether an instance is running, stale, or dead
 * without needing a live connection.
 *
 * Inspection pipeline:
 *   1. Read runtime.json → parse → verify PID alive → probe health URL/port
 *   2. Classify as: running | unhealthy | stale | stopped | missing | invalid
 *   3. Self-heal: discard corrupt or orphaned metadata files automatically
 *
 * Runtime authority resolution: discovers which runtime.json to use by checking
 * IRANTI_INSTANCE_DIR, IRANTI_INSTANCE_RUNTIME_FILE, and env path heuristics
 * (IRANTI_ESCALATION_DIR parent, IRANTI_REQUEST_LOG_FILE grandparent).
 *
 * Key exports:
 *   - inspectRuntimeState()               — full inspection with classification + health probe
 *   - readInstanceRuntime()               — parse runtime.json synchronously
 *   - writeInstanceRuntime()              — write locked runtime.json
 *   - updateInstanceRuntime()             — locked read-modify-write
 *   - markRuntimeStopped()               — record clean shutdown in runtime.json
 *   - resolveRuntimeAuthorityFromEnv()    — find runtime.json path from env vars
 *   - isPidAlive()                        — cross-platform PID liveness check (zombie-aware)
 */
export type InstanceRuntimeStatus = 'starting' | 'running' | 'stopping' | 'stopped';
export type InstanceRuntimeMetadata = {
    instanceName: string;
    instanceDir: string;
    envFile: string;
    runtimeFile: string;
    version: string;
    pid: number;
    ppid: number;
    port: number;
    startedAt: string;
    lastHeartbeatAt: string;
    updatedAt: string;
    status: InstanceRuntimeStatus;
    healthUrl?: string;
    exitCode?: number | null;
    exitSignal?: string | null;
    requestLogFile?: string;
    packageRoot?: string;
};
export type InstanceRuntimeState = InstanceRuntimeMetadata;
export type RuntimeHealthProbe = {
    checked: boolean;
    ok: boolean;
    source: 'health-url' | 'port-health' | 'none';
    detail: string;
};
export type RuntimeOperatorClassification = 'running' | 'unhealthy' | 'stale' | 'stopped' | 'missing' | 'invalid';
export type RuntimeInspection = {
    state: InstanceRuntimeState | null;
    processAlive: boolean;
    running: boolean;
    stale: boolean;
    classification: RuntimeOperatorClassification;
    detail: string;
    health: RuntimeHealthProbe;
};
export type RuntimeAuthorityResolution = {
    managed: boolean;
    source: 'explicit' | 'derived' | 'adhoc' | 'invalid';
    instanceDir: string | null;
    runtimeFile: string | null;
    detail: string;
};
export type InstanceRuntimeSnapshot = {
    runtimeFile: string;
    metadata: InstanceRuntimeMetadata | null;
    pid: number | null;
    processAlive: boolean;
    observedAt: string;
};
export declare function runtimeFileForInstance(instanceDir: string): string;
export declare function resolveInstanceDirFromRuntimeEnv(env: Record<string, string | undefined>): string | null;
export declare function resolveRuntimeFileFromRuntimeEnv(env: Record<string, string | undefined>): string | null;
export declare function resolveRuntimeAuthorityFromEnv(env: Record<string, string | undefined>): RuntimeAuthorityResolution;
export declare function isPidAlive(pid: number | null | undefined): boolean;
export declare function isPidRunning(pid: number | null | undefined): boolean;
export declare function waitForPidExit(pid: number, timeoutMs: number, pollMs?: number): Promise<boolean>;
export declare function readInstanceRuntime(runtimeFile: string): InstanceRuntimeMetadata | null;
export declare function readRuntimeState(runtimeFile: string): Promise<InstanceRuntimeState | null>;
export declare function probeRuntimeHealth(urlString: string, timeoutMs?: number): Promise<{
    ok: boolean;
    detail: string;
}>;
export declare function inspectRuntimeState(runtimeFile: string): Promise<RuntimeInspection>;
export declare function writeInstanceRuntime(runtimeFile: string, metadata: InstanceRuntimeMetadata): Promise<void>;
export declare function writeRuntimeState(runtimeFile: string, metadata: InstanceRuntimeState): Promise<void>;
export declare function updateInstanceRuntime(runtimeFile: string, updater: (current: InstanceRuntimeMetadata | null) => InstanceRuntimeMetadata | null): Promise<InstanceRuntimeMetadata | null>;
export declare function markRuntimeStopped(runtimeFile: string, signal?: string | null): Promise<InstanceRuntimeState | null>;
//# sourceMappingURL=runtimeLifecycle.d.ts.map