export { MANAGED_WEB_LOG_MAINTENANCE_ENV } from "./managed-web-maintenance-environment.js"; /** * Thin, side-effect-light helpers around macOS launchd. The `launchctl` runner * is injectable so orchestration can be unit tested without touching the real * service domain. Everything here is pure except `makeLaunchctlRunner`. */ export interface LaunchctlResult { readonly code: number; readonly stdout: string; readonly stderr: string; } export type LaunchctlRunner = (args: readonly string[]) => Promise; export interface LaunchdPaths { readonly plistPath: string; readonly stdoutPath: string; readonly stderrPath: string; readonly logDir: string; readonly launchAgentsDir: string; } export interface LaunchdMaintenancePaths { readonly label: string; readonly plistPath: string; } export interface PlistInput { readonly label: string; readonly nodePath: string; readonly cliPath: string; readonly configPath: string; readonly cwd: string; readonly envFile?: string; /** Secret-free approved input identity, encoded for the internal worker. */ readonly expectedBackgroundSnapshot: string; /** Path-free finalized managed-runtime proof for the internal worker. */ readonly expectedManagedRuntimeLaunch: string; readonly stdoutPath: string; readonly stderrPath: string; /** Deliberately allowlisted, non-secret worker environment. */ readonly environment: Readonly>; } export interface MaintenancePlistInput { readonly label: string; readonly nodePath: string; /** Attested lightweight executable in the immutable managed closure. */ readonly cliPath: string; readonly configPath: string; readonly cwd: string; /** Original controller CLI used only as managed-runtime installation input. */ readonly controllerCliPath: string; readonly agentCwd: string; readonly agentPath: string; /** Path-free proof covering the managed marker, main CLI, and helper entry. */ readonly expectedManagedRuntimeLaunch: string; readonly envFile?: string; /** Deliberately allowlisted, non-secret maintenance environment. */ readonly environment: Readonly>; /** Minute in each hour derived from the canonical main LaunchAgent label. */ readonly calendarMinute: number; } export interface WebMaintenancePlistInput { readonly label: typeof WEB_MAINTENANCE_LAUNCHD_LABEL; readonly nodePath: string; /** The same attested lightweight entry used by agent maintenance. */ readonly cliPath: string; readonly cwd: string; readonly expectedManagedRuntimeLaunch: string; /** Fresh dev:ino:size:sha256 identity of the paired main web plist. */ readonly expectedWebPlistIdentity: string; readonly environment: Readonly>; readonly calendarMinute: number; } export interface WebPlistInput { readonly label: string; readonly nodePath: string; readonly cliPath: string; readonly cwd: string; readonly host: string; readonly port: number; readonly theme: string; readonly stdoutPath: string; readonly stderrPath: string; /** Deliberately allowlisted, non-secret worker environment. */ readonly environment: Readonly>; } export interface LaunchdServiceInfo { readonly loaded: boolean; readonly pid?: number; } export interface LaunchdManagedWorkerDefinition { readonly plistPath: string; readonly nodePath: string; readonly cliPath: string; readonly configPath: string; readonly cwd: string; readonly envFile?: string; readonly expectedBackgroundSnapshot: string; readonly expectedManagedRuntimeLaunch: string; readonly stdoutPath: string; readonly stderrPath: string; readonly environment: Readonly>; } export interface LaunchdManagedWorkerInfo extends LaunchdServiceInfo { /** Present only when launchctl exposes the exact current producer shape. */ readonly definition?: LaunchdManagedWorkerDefinition; } export interface LaunchdWebMaintenanceDefinition { readonly plistPath: string; readonly nodePath: string; readonly cliPath: string; readonly cwd: string; readonly expectedManagedRuntimeLaunch: string; readonly expectedWebPlistIdentity: string; } export interface LaunchdWebMaintenanceInfo extends LaunchdServiceInfo { /** Present only when launchctl exposes the exact cached helper definition. */ readonly definition?: LaunchdWebMaintenanceDefinition; } export declare const INTERNAL_LAUNCHD_LOG_MAINTENANCE_COMMAND = "__launchd-log-maintenance"; export declare const MANAGED_LAUNCHD_LOG_MAINTENANCE_ENV = "MONO_AGENT_MANAGED_LOG_MAINTENANCE"; export declare const WEB_LAUNCHD_LABEL = "com.mono-agent-web"; export declare const WEB_MAINTENANCE_LAUNCHD_LABEL = "com.mono-agent-web-maintenance"; export declare const INTERNAL_WEB_LOG_MAINTENANCE_COMMAND = "__web-log-maintenance"; /** * A stable, launchd-legal label derived from the resolved config path. The * folder name keeps it human-readable; an 8-char hash of the absolute config * path disambiguates same-named folders and keeps the label deterministic so * `start`/`stop`/`status` all address the same service. */ export declare function deriveLaunchdLabel(configPath: string): string; export declare function launchdPathsFor(label: string, home?: string): LaunchdPaths; /** * The maintenance label deliberately does not begin with `com.mono-agent.`: * fleet discovery treats that namespace as serving agent instances and must * not mistake a scheduled one-shot helper for an extra agent. */ export declare function deriveLaunchdMaintenanceLabel(mainLabel: string): string; /** Deterministically stagger recurring helpers by the canonical main label. */ export declare function launchdMaintenanceCalendarMinute(canonicalMainLabel: string): number; export declare const LAUNCHD_MAINTENANCE_DISPERSION_SECONDS = 120; /** Spread login helpers before PID authentication, locking, or heavy import. */ export declare function launchdMaintenanceDispersionSeconds(canonicalMainLabel: string): number; /** Web has a fixed label and therefore a distinct exact-label schedule validator. */ export declare function webMaintenanceCalendarMinute(label?: string): number; /** Mirror agent RunAtLoad dispersion without admitting the web label to agent grammar. */ export declare function webMaintenanceDispersionSeconds(label?: string): number; export declare function launchdMaintenancePathsFor(mainLabel: string, home?: string): LaunchdMaintenancePaths; /** Canonical lightweight helper next to the attested managed-runtime CLI. */ export declare function launchdMaintenanceEntrypointPathForCli(cliPath: string): string; export declare function escapeXml(value: string): string; /** * The plist runs the blocking worker through `/usr/bin/env -i`. Clearing the * launchd job's inherited environment before Node starts is important: Node * startup variables such as NODE_OPTIONS execute before cli.ts can sanitise * process.env. Only the explicit, non-secret operational allowlist is restored. */ export declare function buildPlistXml(input: PlistInput): string; /** Scheduled one-shot recovery controller. It owns no logs and never KeepAlives. */ export declare function buildLaunchdMaintenancePlistXml(input: MaintenancePlistInput): string; /** Scheduled one-shot web log controller. It never owns a KeepAlive or log stream. */ export declare function buildWebMaintenancePlistXml(input: WebMaintenancePlistInput): string; /** Always-on web-console LaunchAgent. It runs the public blocking `web run` worker. */ export declare function buildWebPlistXml(input: WebPlistInput): string; /** Exact argv persisted by the managed LaunchAgent producer. */ export declare function buildLaunchdProgramArguments(input: PlistInput): readonly string[]; /** Exact argv persisted by the private scheduled maintenance LaunchAgent. */ export declare function buildLaunchdMaintenanceProgramArguments(input: MaintenancePlistInput): readonly string[]; /** Exact argv persisted by the private scheduled web-maintenance LaunchAgent. */ export declare function buildWebMaintenanceProgramArguments(input: WebMaintenancePlistInput): readonly string[]; /** Exact argv persisted for the always-on web console. */ export declare function buildWebLaunchdProgramArguments(input: WebPlistInput): readonly string[]; export declare function buildEnvironmentArguments(environment: Readonly>): string[]; export declare function assertWebPlistIdentity(value: string): void; /** * PATH for the background worker: the launching shell's PATH (so the user's * toolchain is reachable) plus Homebrew/usr-local in case launchd started from * a bare login. Never includes anything secret. */ export declare function defaultPathEnv(env?: Record): string; export declare function domainTarget(uid: number): string; export declare function serviceTarget(label: string, uid: number): string; export declare function makeLaunchctlRunner(): LaunchctlRunner; /** True when the service is bootstrapped in the user's gui domain. */ export declare function isLoaded(runner: LaunchctlRunner, label: string, uid: number): Promise; /** Read the launchd-owned process identity from `launchctl print`. */ export declare function launchdServiceInfo(runner: LaunchctlRunner, label: string, uid: number): Promise; /** * Read and strictly parse the definition launchd currently owns. This does not * trust the on-disk plist: launchd can retain an older definition after that * file is replaced, which is exactly the state the recovery controller must * distinguish during upgrades. */ export declare function launchdManagedWorkerInfo(runner: LaunchctlRunner, label: string, uid: number): Promise; /** Read the cached definition, not merely the mutable helper plist on disk. */ export declare function launchdWebMaintenanceInfo(runner: LaunchctlRunner, uid: number): Promise; /** Parse only the exact cached web-helper definition emitted by this producer. */ export declare function parseLaunchdWebMaintenanceDefinition(output: string): LaunchdWebMaintenanceDefinition | undefined; /** Parse only the exact managed-worker launchctl-print shape emitted here. */ export declare function parseLaunchdManagedWorkerDefinition(output: string): LaunchdManagedWorkerDefinition | undefined; /** Parse only launchd's top-level `pid = N` field; never infer a pid from noise. */ export declare function parseLaunchdServicePid(output: string): number | undefined; /** Bootstrap (load + RunAtLoad-launch) the plist. Caller tolerates "already bootstrapped". */ export declare function bootstrap(runner: LaunchctlRunner, plistPath: string, uid: number): Promise; /** Ask launchd to start a loaded one-shot service without replacing a running instance. */ export declare function kickstart(runner: LaunchctlRunner, label: string, uid: number): Promise; /** * Remove the service from the domain. Sends SIGTERM and — unlike a plain kill — * prevents KeepAlive from relaunching it. Caller tolerates "not loaded". */ export declare function bootout(runner: LaunchctlRunner, label: string, uid: number): Promise; //# sourceMappingURL=launchd.d.ts.map