@smthrs/platform-node 0.0.0-stage → 1.0.0-rc.4

package/dist/esm/ProcessReaper.js

@@ -0,0 +1,711 @@
+/**
+ * Reaping the processes a dead host incarnation abandoned.
+ *
+ * Scope closure cleans up work a live host still owns. On POSIX, a prepared
+ * supervisor also receives private-channel EOF when its host disappears and
+ * independently requests group cleanup. The durable ledger remains the fallback
+ * when that cleanup is incomplete or cannot be verified; the next incarnation
+ * uses this module to examine the recorded process identities before acting.
+ *
+ * The rules are narrow on purpose, because the input is a durable record that
+ * outlived the process that wrote it and a pid is reused. A record is signalled
+ * only when ALL of these hold:
+ *
+ * - it belongs to a DIFFERENT incarnation of the SAME `hostId`
+ *   ({@link ProcessLedger.Service.orphans} already filters that);
+ * - its owner is gone. A pid that exists but belongs to another user counts as
+ *   alive, exactly as {@link HostLiveness} counts it, so only `ESRCH` reads as
+ *   dead and every other answer keeps the record;
+ * - it names a target the platform can actually signal. On POSIX that is a
+ *   process group the child leads itself, so `pgid` has to be a safe integer
+ *   above 1 and equal to `pid`; on Windows it is a pid, so `pgid` has to be
+ *   absent. The check is made against the DURABLE record rather than trusted
+ *   from it: `process.kill(-0, "SIGKILL")` signals this host's own process
+ *   group, and `@smthrs/kernel`'s ledger schema admits zero;
+ * - that group is not THIS process's group, and its pid is not this process's
+ *   pid. The host's real process group is read from the operating system,
+ *   because a stored number can claim anything and the shell that started this
+ *   host shares its group. A host that cannot read its own group keeps the
+ *   record rather than signalling it on a guard that did not run;
+ * - the number still names the process the record describes. A record written
+ *   before this machine booted names a pid from a pid space that no longer
+ *   exists, and within one boot the recorded start time has to match the start
+ *   time the operating system reports for that pid. A host that cannot ASK the
+ *   question answers {@link StartTime} `unavailable`, which refuses the kill
+ *   and keeps the record; no evidence never authorizes a signal.
+ *
+ * The outcome of the signal is part of the record. A kill that succeeds, or
+ * that reports the group is already gone, retires the record through
+ * {@link ProcessLedger.Service.reaped}; a kill that FAILS for any other reason
+ * leaves the record inherited so the next incarnation tries again. A record
+ * refused on grounds the operating system will not revisit — a number no
+ * platform can signal, a pid that is gone, a start time that does not match — is
+ * retired through {@link ProcessLedger.Service.skipped}, which says in the
+ * journal that nothing was signalled and stops every later incarnation
+ * re-examining a number the operating system has moved on from. The three
+ * refusals a later incarnation CAN answer differently — `owner-alive`,
+ * `identity-unverified`, and `own-group-unknown` — retire nothing.
+ *
+ * @since 0.1.0
+ */
+import * as ContainedSpawner from "@smthrs/kernel/ContainedSpawner";
+import * as ProcessLedger from "@smthrs/kernel/ProcessLedger";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Metric from "effect/Metric";
+import { ChildProcessSpawner, make as makeSpawner } from "effect/unstable/process/ChildProcessSpawner";
+import { spawnSync } from "node:child_process";
+import { uptime } from "node:os";
+import { parse, win32 } from "node:path";
+import { packageRoot, resolveDefaultExecutable } from "./internal/AtomicFileSystemExecutable.js";
+import { usableExecutable } from "./internal/AtomicFileSystemTransport.js";
+import * as PipedProcess from "./internal/PipedProcess.js";
+import * as ProcessCleanup from "./internal/ProcessCleanup.js";
+import * as ProcSnapshot from "./internal/ProcSnapshot.js";
+const errorCode = (cause) => cause?.code;
+const liveness = (pid) => {
+    try {
+        // Signal 0 delivers nothing; it only asks whether the pid is signalable.
+        process.kill(pid, 0);
+        return "alive";
+    }
+    catch (cause) {
+        // ESRCH is the only answer that means gone. EPERM means the process
+        // exists and belongs to another user; anything else is a question this
+        // host could not ask, and both keep the record rather than kill on it.
+        return errorCode(cause) === "ESRCH" ? "dead" : "unknown";
+    }
+};
+const bootedAtMs = () => Date.now() - Math.round(uptime() * 1000);
+/**
+ * The start time `ps` reports for a pid.
+ *
+ * `lstart` is the one start-time column both BSD (macOS) and procps (Linux)
+ * spell the same way, and it prints an absolute time rather than an elapsed
+ * one, so the answer does not drift between reading it and comparing it. It is
+ * also a LOCALIZED column, so the probe pins `LC_ALL=C` and `TZ=UTC`.
+ * Its text has no zone; parsing explicitly as UTC keeps the identity independent
+ * of the host runtime's timezone.
+ */
+const startedAtMs = (executable) => (pid) => {
+    const answer = ps(executable, "lstart", pid);
+    if (answer._tag === "gone") {
+        // A nonzero exit is `ps` saying the pid does not exist, but it is also what
+        // a `ps` that rejected the column, or one that is not the `ps` this probe
+        // expects, says about a pid that is very much alive. The kernel is asked
+        // directly before a live process is retired as gone.
+        return liveness(pid) === "dead" ? answer : { _tag: "unavailable" };
+    }
+    if (answer._tag !== "printed")
+        return answer;
+    const parsed = Date.parse(`${answer.text} UTC`);
+    return Number.isNaN(parsed) ? { _tag: "unavailable" } : { _tag: "started", startedAtMs: parsed };
+};
+/**
+ * The absolute path the process probe is run from.
+ *
+ * Never a `PATH` lookup. The inherited environment belongs to whoever started
+ * this host, and a planted `ps` that prints a fabricated start time — or none
+ * at all — would decide whether a `SIGKILL` is authorized.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const defaultPsExecutable = "/bin/ps";
+/** How long the probe may take before it counts as an answer nobody gave. */
+const psTimeoutMs = 5000;
+/**
+ * The Windows directory the host was started with, when it names one.
+ */
+const windowsRoot = () => {
+    const systemRoot = process.env.SystemRoot;
+    return systemRoot !== undefined && win32.isAbsolute(systemRoot) ? systemRoot : "C:\\Windows";
+};
+/**
+ * The system `taskkill`, by absolute path. Windows resolves a bare name from
+ * the current directory before `PATH`, so a flow that wrote `taskkill.exe`
+ * into the host's working directory would otherwise run as the host.
+ */
+const taskkillExecutable = () => win32.join(windowsRoot(), "System32", "taskkill.exe");
+/** A live-release probe has its own short bound within the shutdown deadline. */
+const cleanupProbeTimeoutMs = 2000;
+/**
+ * One fixed-path snapshot supplies group membership, start identities and our
+ * own group together. Only numeric fields and C-locale lstart are read; command
+ * text and the caller's PATH never influence signal authority.
+ */
+const psGroupSnapshot = (pgid) => {
+    const result = spawnSync(defaultPsExecutable, ["-A", "-o", "pid=,pgid=,stat=,lstart="], {
+        encoding: "utf8",
+        timeout: cleanupProbeTimeoutMs,
+        killSignal: "SIGKILL",
+        env: { LC_ALL: "C", TZ: "UTC", PATH: "/usr/bin:/bin" }
+    });
+    if (result.error !== undefined || result.signal !== null || result.status !== 0)
+        return undefined;
+    let own;
+    const members = [];
+    for (const line of result.stdout.trim().split("\n")) {
+        const match = /^\s*([0-9]+)\s+([0-9]+)\s+(\S+)\s+(.+)$/.exec(line);
+        if (match === null)
+            return undefined;
+        const pid = Number(match[1]);
+        const group = Number(match[2]);
+        if (!Number.isSafeInteger(pid) || !Number.isSafeInteger(group))
+            return undefined;
+        if (pid === process.pid)
+            own = group;
+        if (group !== pgid)
+            continue;
+        const started = Date.parse(`${match[4]} UTC`);
+        if (Number.isNaN(started))
+            return undefined;
+        members.push({ pid, startedAtMs: started, zombie: match[3].startsWith("Z") });
+    }
+    return own === undefined || own <= 0 ? undefined : { ownGroup: own, members };
+};
+/**
+ * The observation the supervisor polls, from the source that platform has.
+ *
+ * Linux publishes the whole process table as files under `/proc`, which is
+ * where `ps` itself reads it, so the kernel is asked directly. That needs no
+ * `procps` in the image, cannot be answered by a planted binary, and costs no
+ * fork on a poll that runs every 10ms. A missing `/bin/ps` is not a
+ * hypothetical: `procps` is not in `debian:bookworm-slim`, and on Cloud CI run
+ * 11727 every spawned target in every task finished its work and then failed
+ * cleanup verification with `Unknown: ChildProcess.kill`, because this
+ * observation could not be made.
+ *
+ * Every other POSIX host keeps the `ps` reading, which is the only portable
+ * spelling of this question off Linux.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const groupSnapshotFor = (platform) => platform === "linux" ? ProcSnapshot.snapshot(ProcSnapshot.defaultProcRoot) : psGroupSnapshot;
+/**
+ * Whether the kernel reports no process at all in a group.
+ *
+ * Signal 0 delivers nothing; it only asks the kernel whether the group has a
+ * member. `ESRCH` is the one answer that proves the group empty, with no fork
+ * and no process table to parse, so it still answers on a loaded host where a
+ * `ps` snapshot cannot be taken. A live member, a zombie (macOS answers
+ * `EPERM`, Linux succeeds), another user's member or any other error answers
+ * `false`, which leaves the question to the snapshot.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const groupVacant = (pgid) => {
+    // kill(0) and kill(-1) address the caller's group and every process.
+    if (!Number.isSafeInteger(pgid) || pgid <= 1)
+        return false;
+    try {
+        process.kill(-pgid, 0);
+        return false;
+    }
+    catch (cause) {
+        return errorCode(cause) === "ESRCH";
+    }
+};
+/**
+ * Live cleanup for Node and Bun contained spawners.
+ *
+ * A trusted supervisor remains the group owner after the target exits. It
+ * enforces cleanup on target completion, parent loss and explicit release; the
+ * target starts only after its owner is durably recorded. Host observations
+ * never signal a pid: they only shorten the owner's deadline or verify an empty
+ * group before retiring its record. Failed verification retains the record.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const processLifecycle = ProcessCleanup.lifecycle({
+    platform: process.platform,
+    snapshot: groupSnapshotFor(process.platform),
+    vacant: groupVacant
+});
+/**
+ * Provides a ledger-backed spawner with this platform's prepared cleanup.
+ *
+ * Native pipe listeners live until their descriptors close, including writes
+ * interrupted by owner loss. The kernel expands pipelines before this private
+ * standard-command adapter is called. Windows owners join a native job before
+ * activation; POSIX owners enforce their process-group cleanup deadline.
+ *
+ * The caller supplies the durable or in-memory ledger. This layer records new
+ * owners; {@link layer} separately reaps
+ * records inherited from a previous host incarnation.
+ * @category layers
+ * @since 1.0.0
+ */
+export const layerSpawner = (options) => {
+    const contained = ContainedSpawner.layer({ graceMs: options?.graceMs, platform: process.platform }, processLifecycle);
+    const standard = makeSpawner((command) => PipedProcess.spawn(command, undefined, true));
+    return Layer.provide(contained, Layer.succeed(ChildProcessSpawner)(standard));
+};
+/** A whole number and nothing else, which is all a `pgid` column may be. */
+const decimal = /^[0-9]+$/;
+/**
+ * One `ps` column for one pid.
+ *
+ * `printed` is an answer; every other tag is the absence of one. A nonzero exit
+ * with no error is `ps` saying the pid does not exist, which is evidence; a
+ * spawn that failed, a signal, or a timeout is not.
+ */
+const ps = (executable, column, pid) => {
+    const result = spawnSync(executable, ["-o", `${column}=`, "-p", String(pid)], {
+        encoding: "utf8",
+        timeout: psTimeoutMs,
+        // `SIGKILL` rather than the default `SIGTERM`, because this call blocks the
+        // event loop while a host is being built: `spawnSync` keeps waiting past
+        // the deadline for a process that ignores the signal, so a `TERM` the probe
+        // can decline is not a deadline at all.
+        killSignal: "SIGKILL",
+        // An empty-ish environment for the same reason the helper in
+        // `AtomicFileSystem` gets one: nothing the caller exported may change what
+        // this answers. Pin both the column's spelling and its timezone; the parser
+        // supplies UTC explicitly because `lstart` does not print a zone.
+        env: { LC_ALL: "C", TZ: "UTC", PATH: "/usr/bin:/bin" }
+    });
+    if (result.error !== undefined || result.signal !== null || result.status === null) {
+        return { _tag: "unavailable" };
+    }
+    if (result.status !== 0)
+        return { _tag: "gone" };
+    const printed = result.stdout.trim();
+    return printed === "" ? { _tag: "unavailable" } : { _tag: "printed", text: printed };
+};
+/**
+ * This process's own process group.
+ *
+ * Node exposes no `getpgrp`, so the answer comes from `ps`, which both BSD and
+ * procps spell `pgid`. A host that cannot read it answers `null` and loses one
+ * guard, which is why the pid comparison below is kept as well.
+ *
+ * The text is required to be one run of decimal digits naming a real group,
+ * rather than run through `Number.parseInt`, which reads a PREFIX: `"12 34"`,
+ * `"12abc"`, and `"0x10"` all become a number that is not this host's group. A
+ * wrong number is worse here than no number at all. It silently passes the
+ * own-group comparison in {@link refuse}, and because it is not `null` it also
+ * suppresses the `own-group-unknown` refusal that exists to say the comparison
+ * could not be made, so the guard neither runs nor reports that it did not run
+ * and a `SIGKILL` goes out on it. Anything else answers `null`, which refuses.
+ */
+const ownGroup = (executable) => () => {
+    const answer = ps(executable, "pgid", process.pid);
+    if (answer._tag !== "printed")
+        return null;
+    if (!decimal.test(answer.text))
+        return null;
+    const parsed = Number(answer.text);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+};
+/**
+ * Whether a durable record names a POSIX process group this host may signal.
+ *
+ * `process.kill(-pgid, ...)` turns the stored number into a target directly, so
+ * every value that is not a real foreign group has to be refused before it gets
+ * there: `0` signals THIS process's group, a negative value stops naming a
+ * group at all and names a single pid, and a `pgid` that differs from `pid`
+ * describes a child that does not lead the group it claims —
+ * `ContainedSpawner.groupOf` writes `pgid === pid` for every detached POSIX
+ * child, so anything else is a record no writer in this repository produced.
+ */
+const refusePosixTarget = (record) => {
+    if (record.pgid === null)
+        return "no-group";
+    if (!Number.isSafeInteger(record.pid) || record.pid <= 1)
+        return "invalid-record";
+    if (!Number.isSafeInteger(record.pgid) || record.pgid <= 1)
+        return "invalid-record";
+    return record.pgid === record.pid ? undefined : "invalid-record";
+};
+/**
+ * Whether a durable record names a Windows process tree this host may signal.
+ *
+ * Windows has no process groups, so `ContainedSpawner.groupOf` records `null`
+ * there and `taskkill /T` walks the tree from the pid instead. A win32 record
+ * carrying a number is therefore a record some other platform wrote.
+ */
+const refuseWindowsTarget = (record) => {
+    if (record.pgid !== null)
+        return "invalid-record";
+    return Number.isSafeInteger(record.pid) && record.pid > 1 && record.pid <= 0xffff_ffff ? undefined : "invalid-record";
+};
+/**
+ * Reaping on a POSIX host, with the identity probe configured.
+ *
+ * The group is killed outright rather than asked politely first. `SIGTERM`
+ * buys a graceful shutdown only when someone is left to wait for it, and the
+ * incarnation that owned these processes is by definition gone.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const posixSystemWith = (options) => posixSystemFrom({
+    startedAtMs: startedAtMs(options?.psExecutable ?? defaultPsExecutable),
+    ownGroup: ownGroup(options?.psExecutable ?? defaultPsExecutable),
+    bootedAtMs
+}, options?.ownerPid ?? process.pid);
+/**
+ * Reaping on Linux, with every identity question read from `/proc` rather
+ * than from `ps`.
+ *
+ * `procps` is not in `debian:bookworm-slim` (Cloud CI run 11727), and a
+ * `ps`-based reaper on such a host can read neither its own group nor any
+ * start time, so it refuses every orphan as `own-group-unknown` on every
+ * restart. The live-cleanup observation ({@link groupSnapshotFor}) already
+ * reads `/proc` for the same reason; this is the crash-recovery half.
+ *
+ * A pid with no `/proc/<pid>/stat` is `gone` only when the kernel also says so,
+ * because a `hidepid` mount hides another user's live process the same way.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.1
+ */
+export const procSystemWith = (options) => {
+    const root = options?.procRoot ?? ProcSnapshot.defaultProcRoot;
+    const readStart = ProcSnapshot.startedAtMs(root);
+    return posixSystemFrom({
+        startedAtMs: (pid) => {
+            const answer = readStart(pid);
+            return answer._tag === "gone" && liveness(pid) !== "dead" ? { _tag: "unavailable" } : answer;
+        },
+        ownGroup: ProcSnapshot.ownGroup(root),
+        bootedAtMs: () => ProcSnapshot.bootMs(root) ?? bootedAtMs()
+    }, options?.ownerPid ?? process.pid);
+};
+/** The POSIX kill path over whichever probes the platform answers with. */
+const posixSystemFrom = (probes, ownerPid) => {
+    const readOwnGroup = probes.ownGroup;
+    return {
+        isAlive: liveness,
+        startedAtMs: probes.startedAtMs,
+        ownGroup: readOwnGroup,
+        bootedAtMs: probes.bootedAtMs,
+        refuseTarget: refusePosixTarget,
+        killTree: (record) => {
+            // Repeated here and not only in `refuse`: this function is exported, and
+            // the negation below is the one place a stored number becomes a signal.
+            if (refusePosixTarget(record) !== undefined)
+                return "failed";
+            // The host's own identity, repeated for the same reason. `refuse` holds
+            // one `ownGroup` reading for the whole sweep; a caller that reaches this
+            // function directly has made no such reading, and `process.kill(-pgid)`
+            // does not care which way the number arrived. A group that cannot be
+            // read is a comparison that did not happen, so nothing is signalled.
+            if (record.pid === ownerPid || record.pgid === ownerPid)
+                return "failed";
+            const group = readOwnGroup();
+            if (group === null || record.pid === group || record.pgid === group)
+                return "failed";
+            try {
+                process.kill(-record.pgid, "SIGKILL");
+                return "signalled";
+            }
+            catch (cause) {
+                // The group settled between the liveness check and the signal: the end
+                // state is the one that was wanted. Anything else is a kill that did NOT
+                // happen, and saying so is what gets the record tried again.
+                return errorCode(cause) === "ESRCH" ? "already-gone" : "failed";
+            }
+        }
+    };
+};
+/**
+ * Reaping on a POSIX host: one `SIGKILL` to the abandoned process group, with
+ * the identity probe at {@link defaultPsExecutable}.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const posixSystem = posixSystemWith();
+/**
+ * Reaping on Windows, with the identity the sweep must never signal
+ * configured.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const windowsSystemWith = (options) => {
+    const ownerPid = options?.ownerPid ?? process.pid;
+    const startedAtMs = (pid) => {
+        if (!Number.isSafeInteger(pid) || pid <= 1 || pid > 0xffff_ffff)
+            return { _tag: "unavailable" };
+        try {
+            const configured = options?.processExecutable ?? process.env.SMITHERS_WORKSPACE_JJ_EXPORT_BINARY;
+            const executable = configured === undefined
+                ? resolveDefaultExecutable(packageRoot, undefined)
+                : usableExecutable(configured, undefined);
+            const result = spawnSync(executable, ["--process-info", String(pid)], {
+                cwd: parse(process.execPath).root,
+                env: {},
+                encoding: "utf8",
+                timeout: psTimeoutMs,
+                killSignal: "SIGKILL",
+                maxBuffer: 4096
+            });
+            if (result.error !== undefined || result.signal !== null || result.status !== 0)
+                return { _tag: "unavailable" };
+            const value = JSON.parse(result.stdout);
+            if (value?.status === "gone")
+                return { _tag: "gone" };
+            return value?.status === "started" && typeof value.startedAtMs === "number" &&
+                Number.isSafeInteger(value.startedAtMs) && value.startedAtMs >= 0
+                ? { _tag: "started", startedAtMs: value.startedAtMs }
+                : { _tag: "unavailable" };
+        }
+        catch {
+            return { _tag: "unavailable" };
+        }
+    };
+    return {
+        isAlive: liveness,
+        startedAtMs,
+        ownGroup: () => null,
+        bootedAtMs,
+        refuseTarget: (record) => record.pid === ownerPid ? "own-group" : refuseWindowsTarget(record),
+        killTree: (record) => {
+            if (refuseWindowsTarget(record) !== undefined)
+                return "failed";
+            // `taskkill /T` walks the tree DOWN from the pid it is given, so a record
+            // naming this host takes the host and everything it started with it.
+            if (record.pid === ownerPid)
+                return "failed";
+            const result = spawnSync(taskkillExecutable(), ["/pid", String(record.pid), "/T", "/F"], {
+                // An inert cwd and only the variable Windows system binaries need.
+                cwd: parse(process.execPath).root,
+                env: { SystemRoot: windowsRoot() },
+                stdio: "ignore"
+            });
+            if (result.error !== undefined)
+                return "failed";
+            // 128 is `taskkill`'s "no such process", which is the same end state a
+            // successful kill produces.
+            if (result.status === 0)
+                return "signalled";
+            return result.status === 128 ? "already-gone" : "failed";
+        }
+    };
+};
+/**
+ * Reaping on Windows, which has no process groups: `taskkill /T /F` by pid.
+ *
+ * **Windows is outside the 1.0.0-rc.0 support contract**
+ * (`docs/pages/installation.md`). Full Windows process containment remains
+ * under verification. It is kept — and reachable through {@link reap} rather than only
+ * by calling it directly — because a reaper that silently retired every win32
+ * record would be the "excluded feature that appears to work partially" the
+ * release policy forbids. Treat it as unsupported best-effort.
+ *
+ * The packaged native helper reads creation time from a pinned process handle.
+ * A missing helper, malformed reply, or denied query keeps the durable record
+ * for retry. Windows has no process groups, so own-group refusal uses the pid.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const windowsSystem = windowsSystemWith();
+/**
+ * Reaping on Linux from the kernel's own `/proc`.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.1
+ */
+export const procSystem = procSystemWith();
+/**
+ * Selects the reaping implementation a platform needs.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const systemFor = (platform) => platform === "win32" ? windowsSystem : platform === "linux" ? procSystem : posixSystem;
+/**
+ * How far apart a recorded start time and the operating system's may be and
+ * still describe the same process.
+ *
+ * `lstart` has one-second granularity and the ledger writes its record just
+ * after the spawn returns, so the two never agree exactly. Two seconds covers
+ * the gap; a pid the operating system handed to somebody else is minutes or
+ * hours away from it, not milliseconds.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const identityToleranceMs = 2000;
+/**
+ * The refusals that leave a record inherited instead of retiring it.
+ *
+ * A refusal is final when the operating system has moved on from the number:
+ * saying so in the journal is what stops every later incarnation re-examining
+ * it. These three are not final. `owner-alive` means the incarnation that owns
+ * the record will contain its own children; `identity-unverified` and
+ * `own-group-unknown` mean this host could not ask a question at all — a host
+ * that CAN ask has to get the chance.
+ */
+const retained = new Set([
+    "owner-alive",
+    "identity-unverified",
+    "own-group-unknown"
+]);
+/** The identity half of the decision, split out because it reads as a list. */
+const refuseOnIdentity = (system, record, bootMs) => {
+    // A record older than this boot names a pid from a pid space that no longer
+    // exists. The tolerance points BACKWARDS from the boot instant on purpose:
+    // `uptime` is second-granular, so a record written moments after boot could
+    // otherwise be read as predating it, and refusing to kill is the safe way to
+    // be wrong.
+    //
+    // The consequence is a narrow, deliberate leak, and it is a leak rather than
+    // a retry: `reap` retires a `pre-boot` refusal through `ledger.skipped`, so a
+    // group spawned within `identityToleranceMs` of the computed boot instant is
+    // never reaped by any later incarnation either. That is the price of refusing
+    // to kill on an instant `uptime` can only place to the nearest second.
+    if (record.startedAtMs < bootMs + identityToleranceMs)
+        return "pre-boot";
+    const started = system.startedAtMs(record.pid);
+    // A platform with no start-time column at all has already been checked
+    // against this boot, which is the whole of its documented weaker guarantee.
+    if (started._tag === "unsupported")
+        return undefined;
+    if (started._tag === "gone")
+        return "process-gone";
+    if (started._tag === "unavailable")
+        return "identity-unverified";
+    return Math.abs(started.startedAtMs - record.startedAtMs) <= identityToleranceMs
+        ? undefined
+        : "identity-mismatch";
+};
+/** Everything the reaper checks before it is willing to signal a record. */
+const refuse = (system, record, ownerPid, ownGroup, bootMs) => {
+    // The host's own identity comes first, before the platform is consulted at
+    // all: a record naming this process is refused on every platform, whatever
+    // shape its numbers have.
+    if (record.pgid === ownerPid || record.pid === ownerPid)
+        return "own-group";
+    if (ownGroup !== null && (record.pgid === ownGroup || record.pid === ownGroup))
+        return "own-group";
+    const target = system.refuseTarget(record);
+    if (target !== undefined)
+        return target;
+    // A record naming a group can only be cleared of naming THIS host's group by
+    // reading that group. When the probe cannot answer, the comparison above was
+    // not made rather than made and passed, so the record is kept instead of
+    // signalled on a guard that did not run.
+    if (record.pgid !== null && ownGroup === null)
+        return "own-group-unknown";
+    if (system.isAlive(record.ownerPid) !== "dead")
+        return "owner-alive";
+    return refuseOnIdentity(system, record, bootMs);
+};
+/**
+ * Kills the process groups a previous incarnation of this host abandoned.
+ *
+ * Returns one entry per inherited record so a caller can log what it decided;
+ * `killed: false` carries the {@link Refusal} that produced it. Fails with
+ * {@link ProcessLedger.ProcessLedgerReplayError} when the inherited history
+ * cannot be read to its end: nothing is signalled or retired, so the next
+ * sweep inherits every record again.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const reap = (options) => Effect.gen(function* () {
+    const ledger = yield* ProcessLedger.ProcessLedger;
+    const system = options?.system ?? systemFor(process.platform);
+    const ownerPid = options?.ownerPid ?? process.pid;
+    const ownGroup = system.ownGroup();
+    const bootMs = system.bootedAtMs();
+    const orphans = yield* ledger.orphans;
+    const decided = [];
+    for (const record of orphans) {
+        const refusal = refuse(system, record, ownerPid, ownGroup, bootMs);
+        if (refusal === undefined) {
+            const outcome = system.killTree(record);
+            if (outcome === "failed") {
+                // Nothing was killed, so nothing is retired: leaving the record
+                // inherited is what makes the next incarnation try again.
+                decided.push({ record, killed: false, refusal: "kill-failed" });
+                continue;
+            }
+            yield* retire(ledger.reaped(record), record.pid, "reaped");
+            decided.push({ record, killed: true });
+            continue;
+        }
+        // A retained refusal is not this host's to retire; every other refusal is
+        // final and says so in the journal.
+        if (!retained.has(refusal)) {
+            yield* retire(ledger.skipped(record, refusal), record.pid, "reap-skipped");
+        }
+        decided.push({ record, killed: false, refusal });
+    }
+    return decided;
+});
+/**
+ * Writes one ledger retirement, logging rather than failing the sweep.
+ *
+ * A retirement that does not commit is not a lost kill: the process is already
+ * dead and the record stays inherited, so the next incarnation reads it, finds
+ * the pid gone, and retires it then. Failing the whole sweep over it would
+ * take the host down for a bookkeeping write.
+ */
+const retire = (write, pid, what) => write.pipe(Effect.catch((error) => Effect.logWarning(`process reaper could not journal ${what} for ${pid}`, error)));
+/**
+ * Refusals that leave a dead incarnation's process running with no live owner
+ * to contain it: the host could not ask, or its signal failed.
+ */
+const unreaped = new Set(["identity-unverified", "own-group-unknown", "kill-failed"]);
+/**
+ * Counter over inherited records the reaper did not kill, with a `refusal`
+ * attribute naming why.
+ *
+ * @category metrics
+ * @since 1.0.0-rc.1
+ */
+export const refusals = Metric.counter("flows_process_reaper_refusals", {
+    description: "Inherited process records the reaper did not kill, by refusal"
+});
+/**
+ * Reports one sweep: a counter update per refusal and one summary line. The
+ * line is a warning when a record stays inherited (a retained refusal) or a
+ * signal failed, because either leaves a crashed incarnation's processes
+ * running with nothing else to say so.
+ *
+ * @category layers
+ * @since 1.0.0-rc.1
+ */
+export const report = (decided) => Effect.gen(function* () {
+    if (decided.length === 0)
+        return;
+    const counts = {};
+    let killed = 0;
+    for (const entry of decided) {
+        if (entry.killed) {
+            killed += 1;
+            continue;
+        }
+        counts[entry.refusal] = (counts[entry.refusal] ?? 0) + 1;
+    }
+    for (const [refusal, count] of Object.entries(counts)) {
+        yield* Metric.update(Metric.withAttributes(refusals, { refusal }), count);
+    }
+    const annotations = { killed, ...counts };
+    const alarming = decided.some((entry) => !entry.killed && unreaped.has(entry.refusal));
+    const line = "process reaper swept inherited records";
+    yield* (alarming ? Effect.logWarning(line) : Effect.logInfo(line)).pipe(Effect.annotateLogs(annotations));
+});
+/**
+ * Runs {@link reap} once while the layer is built.
+ *
+ * Compose it into a host layer so standing a host up is also what cleans up
+ * after the incarnation that crashed. A history that cannot be read refuses
+ * the sweep with an error log and leaves every record inherited; the host
+ * still starts, because the processes it will spawn are recorded and
+ * contained regardless. Every decision is {@link report}ed.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = (options) => Layer.effectDiscard(reap(options).pipe(Effect.flatMap(report), Effect.catchTag("@smthrs/kernel/ProcessLedgerReplayError", (error) => Effect.logError("process reaper refused to sweep: the ledger history is incomplete", error))));
+//# sourceMappingURL=ProcessReaper.js.map