/** * singleton-policy: the ONE decision behind "exactly one daemon runs here". * * WHY IT IS A SEPARATE, PURE FILE * ------------------------------- * `daemon.lock` cannot enforce the singleton it exists to enforce. It is a * FILE, and every way it fails is a way two daemons end up alive: * * - `isExpired(startedAt)` declares a lock abandoned after 24h, so a daemon * that has been up for a day is invisible to the next `acquireDaemonLock()`; * - the lock is cleared by a half-written `npm i -g`, a cleanup sweep, a * restore-from-backup, or `stopAllDaemons()` clearing it while a survivor * was still running; * - `readLiveDaemonLock()` clears it whenever `pidAlive(lock.pid)` is false, * and a pid we cannot signal reads as dead. * * Each of those leaves a LIVE daemon holding no lock. The next `start` (human * or watchdog) sees a free machine, spawns, and now there are two. On this * machine there were three at once — one serving, two wedged or stale — which * is what made `npm i -g` fail with EBUSY on a mapped native DLL and left the * install half-written. * * So the authority for "is a daemon already running" is PROCESS ENUMERATION * (`listOurDaemonPids`, command-line verified), and the lock is demoted to what * it is actually good for: naming WHICH of the live pids is the incumbent. * * THE RULE * -------- * Of every verified daemon process on this machine, AT MOST ONE survives: * * 1. none alive -> `start` (spawn one) * 2. alive but nothing answers /ping -> `replace` (all of them are wedged; * stop every one, spawn one) * 3. alive and something answers /ping -> `keep` (exactly one pid survives; * every other one is stopped) * * Rule 3 is the load-bearing one: it is what a file-based lock cannot express, * because "several processes match, one of them is real" is not a state any * file can represent. * * WHICH PID SURVIVES (rule 3) — deterministic, never "whoever won the race": * 1. the pid `daemon.lock` names, if it is still alive (the incumbent); * 2. else the pid `runtime.json` names, if it is still alive; * 3. else the LOWEST pid, i.e. the oldest process — on a machine that briefly * held two, the older one has the live socket and the agent state. * * A `blocked` outcome covers the one case where spawning is worse than doing * nothing: a bridge answers /ping but NO pid of ours is identifiable (it runs * from a dev checkout, or its files were wiped under it). Starting then only * produces a loser that exits on the port-occupant check, once per tick. * * No I/O here on purpose: `tests/daemon-singleton.test.mjs` drives this with * plain arrays, and the real machine work lives in `daemon-instance.ts`. */ /** What the caller must do to converge on one daemon. */ export type SingletonAction = /** No daemon is alive: spawn one. */ 'start' /** Exactly `keep` survives; every pid in `stop` must be terminated. */ | 'keep' /** Every live daemon is wedged: terminate all of them, then spawn one. */ | 'replace' /** A bridge answers but is not identifiable: do nothing, say why. */ | 'blocked'; export interface SingletonInput { /** Pids VERIFIABLY running `…/index.js daemon`, ascending, no duplicates. */ live: readonly number[]; /** The pid `daemon.lock` names, or null when it names nothing/already dead. */ lockPid: number | null; /** The pid `runtime.json` names, or null. */ runtimePid: number | null; /** True when some daemon answers `/ping` with ok:true on a candidate port. */ anyAnswering: boolean; } export interface SingletonDecision { action: SingletonAction; /** The one pid allowed to keep running; null for `start`/`replace`/`blocked`. */ keep: number | null; /** Verified daemon pids that must be terminated, ascending. */ stop: number[]; /** Human-readable justification for the log line. Never empty. */ reason: string; } /** * Which witness identifies the running daemon, for READ-ONLY commands. * * Same three witnesses as `decideSingleton`, ranked, and the rule is the same in * both: a FILE may only speak for a process that still exists. That is the whole * point of `live` being the first input — `status` once printed `stopped` for a * healthy daemon because it trusted `daemon.lock`, and the same reasoning in the * other direction (trusting a stale `runtime.json`) prints `running` for a * machine with nothing running. */ export interface EvidenceInput { /** Pids verified (command line + alive) as bridge daemons, ascending. */ live: readonly number[]; /** `daemon.lock`'s pid, if the lock names a verified live daemon. */ lockPid: number | null; /** `runtime.json`'s pid, if it names a verified live daemon. */ runtimePid: number | null; /** `daemon.lock`'s pid when it names something that is NOT the live daemon. */ staleLockPid: number | null; } export interface DaemonEvidence { pid: number | null; source: 'lock' | 'runtime' | 'process' | 'none'; staleLockPid: number | null; /** * The stale lock's pid is itself a verified live daemon (2026-10). * * A lock goes stale TWO ways - its pid died, or it aged past the 24h TTL * while the daemon kept serving. `status` used to report both as "names pid * N, which is not running", which sent the reader to restart a healthy * daemon. When this is true the lock expired under a live incumbent: * harmless, reclaimed on the next start, and definitely not a dead daemon. */ staleLockAlive: boolean; daemonCount: number; } export declare function pickDaemonEvidence(input: EvidenceInput): DaemonEvidence; export declare function decideSingleton(input: SingletonInput): SingletonDecision;