/** Public-clean canonical LaunchAgent label. Deliberately generic — NEVER a
 *  private/persona name (a stranger's machine gets this). */
export declare const CANONICAL_LABEL = "com.bot-relay.daemon";
export interface PlistOptions {
    label: string;
    nodePath: string;
    distEntry: string;
    workingDir: string;
    port: number;
    transport: string;
    logPath: string;
}
/** Build a launchd LaunchAgent plist (RunAtLoad + KeepAlive) — pure. */
export declare function buildLaunchdPlist(o: PlistOptions): string;
/** `~/Library/LaunchAgents/<label>.plist` (home overridable for tests). */
export declare function plistPathFor(label: string, home?: string): string;
/**
 * Parse `launchctl list` output → labels of loaded bot-relay agents (any
 * label containing "bot-relay"). Columns are: PID  Status  Label.
 */
export declare function parseLoadedRelayLabels(launchctlListOutput: string): string[];
export type HealthClass = "relay" | "foreign" | "none" | "unreadable";
/**
 * The outcome of probing :port/health, DISCRIMINATED so the caller can tell
 * "nothing is on the port" apart from "something answered but we could not read
 * it." Collapsing those (the fail-open bug) treats an unreadable daemon as a
 * free port and installs a COMPETING one.
 */
export interface HealthProbe {
    /** An HTTP response came back at all (fetch resolved). false = connection
     *  refused / network error / timeout ⇒ the port is genuinely free. */
    reachable: boolean;
    /** The response status was 2xx. */
    ok: boolean;
    /** The body parsed as JSON. false = empty / non-JSON body (the `curl -s`
     *  empty-200-after-a-bounce case that `res.json()` throws on). */
    parseable: boolean;
    /** The parsed JSON body (null when unreachable or unparseable). */
    body: unknown;
}
/**
 * Classify a /health probe:
 *   - "none"       — UNREACHABLE (fetch rejected): the port is genuinely free.
 *   - "relay"      — reachable, 2xx, parseable, our relay's health shape.
 *   - "foreign"    — reachable, 2xx, parseable, but NOT relay-shaped.
 *   - "unreadable" — reachable but the health could NOT be read (empty body,
 *                    non-JSON, or non-2xx). Something is there we cannot
 *                    identify → the caller must FAIL CLOSED (never install a
 *                    competing daemon on an occupied port). An unreadable probe
 *                    is NOT "none" — that conflation was the fail-open bug.
 */
export declare function classifyHealthProbe(probe: HealthProbe): HealthClass;
export type DaemonAction = "install" | "skip-relay-present" | "skip-foreign-port" | "skip-agent-loaded" | "skip-unreadable";
export interface DaemonDecision {
    action: DaemonAction;
    /** Human-readable reason for stdout / audit. */
    reason: string;
    /** Loaded relay labels observed (for operator visibility). */
    existingLabels: string[];
    /** Set when a relay daemon IS on the port but reports a DIFFERENT version
     *  than the installed package — an upgrade that has NOT taken effect. The
     *  action stays skip (we NEVER auto-bounce a daemon the whole fleet depends
     *  on — ADR-0005: report drift loudly, let a human run `relay restart`), but
     *  this signals the caller to warn LOUDLY instead of reassuring. */
    versionDrift?: {
        running: string;
        installed: string;
    };
}
/**
 * Pure collision decision. install ONLY when the port is free AND no bot-relay
 * LaunchAgent is already loaded. Every other case SKIPS (never double-loads).
 *
 * When a relay IS on the port, compare its reported version to the installed
 * package: a mismatch means `npm update` landed new code but the OLD daemon is
 * still serving it (launchd KeepAlive has no WatchPaths, so it never restarts
 * on a dist change). We surface that as `versionDrift` so the installer stops
 * printing "leaving the existing supervisor in place" as if all were well.
 */
export declare function decideDaemonAction(input: {
    healthClass: HealthClass;
    loadedRelayLabels: string[];
    port: number;
    installedVersion?: string;
    runningVersion?: string | null;
}): DaemonDecision;
export interface RestartTarget {
    /** The launchd label to kickstart, or null when there's nothing safe to restart. */
    label: string | null;
    /** True when the canonical plist exists but the label isn't loaded yet — the
     *  caller must `bootstrap` it before `kickstart`. */
    needsBootstrap: boolean;
    /** Operator-facing explanation on the null / ambiguous paths (empty on success). */
    reason: string;
}
/**
 * Pure selection of which daemon `relay restart` should bounce, from the loaded
 * relay labels + whether the canonical plist exists on disk. Prefers the
 * canonical label; falls back to a SOLE hand-authored relay label; REFUSES to
 * guess among several (never restart an arbitrary one). Kept pure so the harm
 * cases (nothing to restart / ambiguous) are tested without launchctl.
 */
export declare function chooseRestartTarget(input: {
    loadedRelayLabels: string[];
    canonicalPlistExists: boolean;
}): RestartTarget;
export interface InstallDeps {
    /** Probe the health endpoint, discriminating unreachable vs reachable-but-
     *  unreadable (see HealthProbe). Must NOT collapse the two — that is the
     *  fail-open bug. Should not throw; installDaemon fails closed if it does. */
    fetchHealth: (port: number) => Promise<HealthProbe>;
    /** Run `launchctl list` and return stdout (or "" on failure). */
    launchctlList: () => string;
    /** Run `launchctl bootstrap gui/<uid> <plistPath>` (or kickstart). */
    bootstrap: (plistPath: string, label: string) => void;
    /** Write the plist file (atomic). */
    writePlist: (plistPath: string, contents: string) => void;
    /** Diagnostic sink. */
    log: (line: string) => void;
}
export interface InstallResult {
    decision: DaemonDecision;
    installed: boolean;
    plistPath: string | null;
}
/**
 * Probe → decide → (maybe) install. The ONLY path that writes a plist or calls
 * bootstrap is `action === "install"`. Every skip path touches nothing.
 */
export declare function installDaemon(opts: Omit<PlistOptions, "label">, deps: InstallDeps, home?: string, label?: string): Promise<InstallResult>;
//# sourceMappingURL=launchd.d.ts.map