@kici-dev/orchestrator 0.17.0 → 0.19.0

package/dist/scaler/host-access.d.ts

@@ -3,11 +3,10 @@
  *
  * An agent container or Firecracker VM sends its packets to one of the host's
  * addresses — a bridge gateway, the host's LAN address — and those are
- * delivered on the netfilter input hook. The `forward` rules the backends
- * already write never see them, so until the `input` chain existed a sandbox
- * reached every port on the host. These helpers resolve the narrow set it
- * actually needs, expressed in the same `hostAccess` vocabulary an operator
- * writes in `scalers.yaml`.
+ * delivered on the netfilter input hook, which the backends' `forward` rules
+ * never see: without an `input` chain a sandbox reaches every port on the host.
+ * These helpers resolve the narrow set it needs, in the `hostAccess`
+ * vocabulary an operator writes in `scalers.yaml`.
  */
 import type { NetworkPolicy } from '@kici-dev/shared/net';
 import type { AppConfig } from '../config.js';
@@ -20,13 +19,11 @@ import type { AppConfig } from '../config.js';
  * orchestrator-port-only default would cut off every deployment running its own
  * object store beside the orchestrator.
  *
- * Two shapes are recognised, and nothing else:
+ * Only two shapes are recognised:
  *
- *  - **An IP literal.** The entry is scoped to that exact address and port, the
- *    narrowest rule that can work.
+ *  - **An IP literal.** The entry is scoped to that exact address and port.
  *  - **A name with an explicit port.** No address rule can be built for a name
- *    that may move, so the entry names the port on any host address. It is
- *    still one port rather than the whole host.
+ *    that may move, so the entry names the port on any host address.
  *
  * A name with no port is a public endpoint (`https://…`), which the agent
  * reaches through the host over the `forward` hook and which no input rule

package/dist/scaler/index.d.ts

@@ -1,9 +1,6 @@
 /**
- * Agent auto-scaler module.
- *
- * Provides pluggable backend-agnostic agent provisioning for the orchestrator.
- * Supports Docker, bare-metal, and Firecracker backends with YAML configuration,
- * label-set matching, and warm pool management.
+ * Agent auto-scaler: pluggable Docker, bare-metal and Firecracker backends with
+ * YAML configuration, label-set matching and warm pool management.
  */
 export type { ResourceLimits, LabelSetConfig, ManagedAgent, ScaleResult, ValidationResult, ScalerBackend, ScalerConfig, ScalerEntry, ScalerEvent, ScalerRedispatchTrigger, WarmPoolConfig, FirecrackerNetworkConfig, } from './types.js';
 export { loadScalerConfig, scalerFileSchema, firecrackerNetworkSchema, parseMemoryString, } from './config.js';
@@ -14,7 +11,7 @@ export { BareMetalScalerBackend } from './bare-metal-backend.js';
 export type { BareMetalScalerBackendOptions } from './bare-metal-backend.js';
 export { FirecrackerScalerBackend } from './firecracker-backend.js';
 export type { FirecrackerScalerBackendOptions, FirecrackerManagedAgent, } from './firecracker-backend.js';
-export { createScalerBackend, requiredToolsFor } from './backend-factory.js';
+export { createScalerBackend } from './backend-factory.js';
 export type { BackendFactoryContext, IpAllocatorParams } from './backend-factory.js';
 export { resolveAgentHostAccess, storageHostAccessEntries } from './host-access.js';
 export { EventScalerBackend } from './event-backend.js';

package/dist/scaler/ip-allocator.d.ts

@@ -1,96 +1,63 @@
 /**
  * CIDR IP allocator for Firecracker VM networking.
  *
- * Two implementations behind a shared interface:
+ * - `DbIpAllocator` persists to PostgreSQL (coordinators), so a long-lived VM
+ *   keeps its IP across coordinator restarts.
+ * - `InMemoryIpAllocator` has no persistence (worker peers, no cluster DB). A
+ *   worker restart starts it empty, and the backend's `cleanupOrphans()`
+ *   Pass-2/Pass-3 walk of jailer chroots and host TAPs (on every spawn and in
+ *   the leak sweep) reaps the leftovers, so the allocator holds no recovery state.
  *
- * - `DbIpAllocator` — persists allocations to PostgreSQL. Used by
- *   coordinators where the cluster Postgres is reachable. Allocations
- *   survive orchestrator restarts so a long-lived VM keeps its IP across
- *   coord bounces.
- *
- * - `InMemoryIpAllocator` — Map-backed, no persistence. Used by worker
- *   peers where the cluster DB is not reachable. The firecracker backend's
- *   existing `cleanupOrphans()` Pass-2/Pass-3 walks the jailer chroot
- *   tree + host TAP devices on every spawn and during the leak sweep, so
- *   any worker-orch restart starts the allocator empty and the next
- *   cleanup pass reaps the leftover chroots and TAPs naturally — no
- *   recovery state needs to live in the allocator itself.
- *
- * Each orch has its own bridge with its own subnet (coord A: `kici`,
- * coord B: `kici_b`, Pi worker: `kici-br0`), so allocator state is
- * per-orch by design. No two orchs share an IP space.
+ * Each orch has its own bridge and subnet (coord A: `kici`, coord B: `kici_b`,
+ * Pi worker: `kici-br0`), so allocator state is per-orch; no two orchs share
+ * an IP space.
  */
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
-/**
- * Result of a successful IP allocation.
- */
 export interface IpAllocationResult {
-    /** Allocated IP address */
     ip: string;
-    /** Gateway IP for guest networking */
     gateway: string;
-    /** Subnet mask for guest networking */
     netmask: string;
-    /** Deterministic MAC address derived from IP */
+    /** Deterministic, derived from the IP. */
     mac: string;
-    /** TAP device name on the host */
+    /** TAP device name on the host. */
     tapDevice: string;
 }
-/**
- * Parsed CIDR range.
- */
+/** IPv4 addresses are 32-bit unsigned numbers. */
 export interface CidrRange {
-    /** Network address as a 32-bit number */
     networkAddress: number;
-    /** Prefix length (e.g. 24 for /24) */
     prefixLength: number;
-    /** First usable IP (network address + 1) as a 32-bit number */
+    /** First usable IP (network address + 1). */
     startIp: number;
-    /** Last usable IP (broadcast - 1) as a 32-bit number */
+    /** Last usable IP (broadcast - 1). */
     endIp: number;
 }
-/**
- * Parse an IPv4 address string to a 32-bit unsigned integer.
- */
+/** Parse an IPv4 address string to a 32-bit unsigned integer. */
 export declare function ipToNumber(ip: string): number;
-/**
- * Convert a 32-bit unsigned integer back to an IPv4 address string.
- */
 export declare function numberToIp(n: number): string;
 /**
- * Parse a CIDR notation string into a CidrRange.
- *
  * @example parseCidr('10.0.0.0/24')
  * // => { networkAddress: 167772160, prefixLength: 24, startIp: 167772161, endIp: 167772414 }
  */
 export declare function parseCidr(cidr: string): CidrRange;
 /**
- * Generate a deterministic MAC address from an IP address.
- *
- * Uses the locally-administered unicast prefix 06:00:AC followed by
- * the last 3 octets of the IP address encoded as hex.
+ * Deterministic MAC: the locally-administered unicast prefix 06:00:AC, then the
+ * last 3 octets of the IP as hex.
  *
  * @example generateMac('10.0.0.5')  // => '06:00:AC:00:00:05'
  * @example generateMac('10.0.1.42') // => '06:00:AC:00:01:2A'
  */
 export declare function generateMac(ip: string): string;
 /**
- * Generate a TAP device name from a VM ID.
- * Linux interface names are limited to 15 characters (IFNAMSIZ).
- * Format: kici-XXXXXXXX (5 + 8 = 13 chars, well within limit).
+ * `kici-XXXXXXXX` (13 chars): Linux interface names are limited to 15 (IFNAMSIZ).
  *
- * Uses the LAST 8 characters of the vmId to avoid collisions.
- * VM IDs have format "scaler-firecracker-XXXXXXXX" where the unique
- * random suffix is at the end. Using slice(0, 8) would always produce
- * "scaler-f" for all Firecracker VMs.
+ * Uses the LAST 8 chars of the vmId: VM IDs are "scaler-firecracker-XXXXXXXX"
+ * with the random suffix at the end, so slice(0, 8) would always be "scaler-f".
  */
 export declare function generateTapName(vmId: string): string;
 /**
- * Shape of one row returned by `IpAllocator.getAllocations()` /
- * `getAllocationForVm()`. Matches the `ip_allocations` table columns so
- * the firecracker-backend's `cleanupOrphans()` can read both impls
- * uniformly.
+ * Matches the `ip_allocations` table columns so the firecracker-backend's
+ * `cleanupOrphans()` reads both impls uniformly.
  */
 export interface IpAllocationRecord {
     ip: string;
@@ -100,12 +67,8 @@ export interface IpAllocationRecord {
     mac_address: string;
 }
 /**
- * Per-orch CIDR IP allocator interface.
- *
- * Two implementations: `DbIpAllocator` (Postgres, coordinator) and
- * `InMemoryIpAllocator` (Map-backed, worker). The firecracker-backend
- * depends only on this interface — never on the concrete class — so a
- * single backend implementation works in both deploy modes.
+ * The firecracker-backend depends only on this interface, never on a concrete
+ * class, so one backend implementation works in both deploy modes.
  */
 export interface IpAllocator {
     allocate(vmId: string, scalerName: string): Promise<IpAllocationResult>;
@@ -114,14 +77,7 @@ export interface IpAllocator {
     getAllocations(): Promise<IpAllocationRecord[]>;
     getAllocationForVm(vmId: string): Promise<IpAllocationRecord | null>;
 }
-/**
- * DB-backed CIDR IP allocator.
- *
- * Allocates IPs from a configurable range, skipping the gateway.
- * All allocations are persisted in PostgreSQL — used by coordinators
- * where the cluster DB is reachable. Allocations survive orch restarts
- * so a long-lived VM keeps its IP across coord bounces.
- */
+/** Coordinator allocator; allocations persist in PostgreSQL across restarts. */
 export declare class DbIpAllocator implements IpAllocator {
     private readonly db;
     private readonly range;
@@ -141,20 +97,12 @@ export declare class DbIpAllocator implements IpAllocator {
     getAllocationForVm(vmId: string): Promise<IpAllocationRecord | null>;
 }
 /**
- * In-memory CIDR IP allocator.
- *
- * Used by worker peers where the cluster Postgres is not reachable. State
- * lives in a `Map<vmId, IpAllocationRecord>` for the lifetime of the
- * orch process; on restart the allocator starts empty and the
- * firecracker-backend's existing `cleanupOrphans()` Pass-2/Pass-3 walks
- * the jailer chroot tree + host TAP devices (matching `VM_TAP_PATTERN`)
- * to reap any leftover state. No persistence and no chroot recovery
- * inside the allocator — the filesystem is the source of truth, and the
- * cleanup pass already consults it.
+ * Worker allocator, process-lifetime state only. After a restart,
+ * `cleanupOrphans()` reaps leftover chroots and TAPs (matching
+ * `VM_TAP_PATTERN`): the filesystem is the source of truth.
  *
- * Each orch has its own bridge with its own subnet, so per-process
- * state is by design. No locking needed: every method is synchronous on
- * the in-memory Map and only awaits to satisfy the async interface.
+ * No locking needed: every method is synchronous on the Map and only awaits
+ * to satisfy the async interface.
  */
 export declare class InMemoryIpAllocator implements IpAllocator {
     private readonly range;

package/dist/scaler/label-matcher.d.ts

@@ -1,19 +1,10 @@
 /**
- * Label-set matching and overlap detection for the scaler module.
- *
- * Label sets are normalized (sorted, deduplicated, lowercased) for
- * deterministic comparison.
- *
- * findBackendForLabels uses subset matching: a job requiring ['macos']
- * matches a scaler with ['macos', 'darwin', 'bare-metal']. This is
- * consistent with peer routing (findPeersWithCapacity) and allows
- * workflows to target broad labels like 'macos' without listing every
- * label the scaler defines.
+ * Scaler label-set matching and overlap detection. Subset matching lets a
+ * workflow target a broad label like 'macos' without listing every label the
+ * scaler defines.
  */
 /**
- * Normalize a label set for comparison.
- * Sorts alphabetically, deduplicates, and lowercases all labels.
- * Produces a deterministic string key for comparison.
+ * A label set as a deterministic comparison key: lowercased, deduplicated, sorted.
  *
  * @example
  * normalizeLabelSet(['Docker', 'linux', 'linux']) // => "docker,linux"
@@ -21,18 +12,13 @@
  */
 export declare function normalizeLabelSet(labels: string[]): string;
 /**
- * Check if two label sets are exactly equal after normalization.
- * Subsets do NOT match -- ["linux"] does not match ["linux", "docker"].
+ * Exact equality after normalization; a subset does NOT match.
  */
 export declare function labelSetsMatch(a: string[], b: string[]): boolean;
 /**
- * Detect overlapping label sets across different scalers.
- * Returns all pairs of scalers that share the same normalized label set.
- *
- * Intra-scaler duplicates are allowed (same scaler, duplicate label sets).
- * Only cross-scaler overlaps are flagged.
- *
- * Used at startup to reject configs with ambiguous routing.
+ * Every pair of scalers sharing a normalized label set. A duplicate within one
+ * scaler is allowed. Startup rejects a config with an overlap: its routing is
+ * ambiguous.
  */
 export declare function detectLabelSetOverlaps(scalers: Array<{
     name: string;
@@ -45,20 +31,13 @@ export declare function detectLabelSetOverlaps(scalers: Array<{
     scaler2: string;
 }>;
 /**
- * Find which scaler backend handles a given set of labels.
- * Returns the scaler name and label-set index, or null if no match.
- *
- * Uses subset matching: job labels must be a subset of the scaler's label set.
- * ['macos'] matches ['macos', 'darwin', 'bare-metal']. This is consistent
- * with peer routing (findPeersWithCapacity) which uses the same semantics.
- *
- * In addition, every label in the gate for the matched label set must be
- * present in the job's `runsOn`. This is the Kubernetes-taint-style opt-in
- * gate: a label set gated on `['gpu']` only accepts jobs that explicitly
- * include `gpu` in `runsOn`.
+ * The scaler and label-set index that handle a job's labels, or null.
  *
- * When multiple backends match, the one with the smallest label set wins
- * (most specific match).
+ * Subset matching: ['macos'] matches ['macos', 'darwin', 'bare-metal'], the same
+ * semantics as peer routing (findPeersWithCapacity). Every label in the
+ * matched set's gate must also be in `runsOn` (a Kubernetes-taint-style
+ * opt-in: a set gated on `['gpu']` accepts only jobs naming `gpu`). Among
+ * several matches the smallest label set wins.
  */
 export declare function findBackendForLabels(labels: string[], scalers: Array<{
     name: string;

package/dist/scaler/log-forwarder.d.ts

@@ -1,10 +1,7 @@
 /**
- * Agent log forwarding: enriches agent log lines with metadata and writes
- * them to a writable stream (typically orchestrator stdout for ELK ingestion).
- *
- * Handles both JSON and non-JSON log lines:
- * - JSON lines are parsed, enriched with agent/context metadata, and re-serialized.
- * - Non-JSON lines are wrapped as info-level JSON objects.
+ * Agent log forwarding: enriches agent log lines with metadata and writes them
+ * to a stream (typically orchestrator stdout for ELK ingestion). A non-JSON
+ * line, or JSON that is not an object, is wrapped as an info-level object.
  *
  * The `service` field identifies the originating tier for forwarded logs that flow
  * through orchestrator stdout (where `kici.service` from container name would say
@@ -12,27 +9,18 @@
  * purpose of identifying forwarded log origin for scaler-managed agents only.
  */
 import type { LogCapture } from './types.js';
-/** Context fields merged into each forwarded log line. */
 interface ForwardContext {
     runId?: string;
     requestId?: string;
     jobId?: string;
 }
 /**
- * Enrich and forward a single log line to an output stream.
- *
- * Standalone function for use in the WS agent.log path (agent-handler).
+ * Enrich and forward one log line; also used by the WS agent.log path (agent-handler).
  *
- * @param line - Raw log line from the agent
- * @param agentId - The agent that produced the line
- * @param output - Writable stream to write enriched JSON to
- * @param context - Optional trace context fields
- * @param logsSource - Optional log source identifier (e.g. 'docker', 'podman', 'bare-metal', 'firecracker-serial')
+ * @param logsSource - e.g. 'docker', 'podman', 'bare-metal', 'firecracker-serial'
  */
 export declare function forwardLine(line: string, agentId: string, output: NodeJS.WritableStream, context?: ForwardContext, logsSource?: string): void;
 /**
- * Consumes a LogCapture stream and forwards enriched log lines to an output stream.
- *
  * Used by scaler backends (container, bare-metal, Firecracker) to forward
  * agent stdout/stderr to orchestrator stdout for ELK ingestion.
  */
@@ -40,14 +28,7 @@ export declare class AgentLogForwarder {
     private readonly agentId;
     private readonly output;
     constructor(agentId: string, output?: NodeJS.WritableStream);
-    /**
-     * Forward all lines from a LogCapture to the output stream.
-     * Resolves when the capture's async iterable ends.
-     *
-     * @param capture - LogCapture to consume
-     * @param context - Optional trace context fields
-     * @param logsSource - Optional log source identifier (e.g. 'docker', 'podman', 'bare-metal')
-     */
+    /** Resolves when the capture's async iterable ends. */
     forward(capture: LogCapture, context?: ForwardContext, logsSource?: string): Promise<void>;
 }
 export {};

package/dist/scaler/machine-ledger.d.ts

@@ -1,35 +1,28 @@
 /**
  * File-backed, cross-process resource ledger for named machine pools.
  *
- * Multiple orchestrators on the same host that reference the same `machinePool`
- * name share a JSON file under `KICI_MACHINE_LEDGER_DIR ?? /var/lib/kici/scaler-ledger`.
- * Each scaler reservation appends a row; releases delete the matching row;
- * and a periodic reaper prunes rows whose `(pid, bootId)` no longer exists.
+ * Orchestrators on one host that name the same `machinePool` share a JSON file
+ * under `KICI_MACHINE_LEDGER_DIR ?? /var/lib/kici/scaler-ledger`. A reservation
+ * appends a row, a release deletes it, and a periodic reaper prunes rows whose
+ * `(pid, bootId)` no longer exists.
  *
  * ## Concurrency
  *
- * Every read-modify-write goes through `withLock(poolName, fn)`, which uses
- * an atomic POSIX `mkdir` on a sibling lockdir as the cross-process mutex.
- * `mkdir` succeeds for exactly one caller when the directory does not exist,
- * so it works as a portable `flock` substitute without any native dependency.
- *
- * Neither `proper-lockfile` nor `fs-ext` is a dependency, so this uses the
- * `mkdir` lock instead. This avoids adding a native binding for the sake of
- * a single locking primitive.
+ * Every read-modify-write runs under `withLock`: an atomic POSIX `mkdir` on a
+ * sibling lockdir succeeds for exactly one caller, a portable `flock`
+ * substitute. `proper-lockfile` / `fs-ext` are rejected to avoid a native
+ * binding for one primitive.
  *
  * ## Crash safety
  *
- * Reservations carry `{ pid, bootId, instanceId, agentId, cpus, memBytes }`.
- * `bootId` is read once at orchestrator startup from
- * `/proc/sys/kernel/random/boot_id`; combined with `pid`, it lets the reaper
- * detect "this PID is dead AND was on a previous boot" reliably:
+ * `bootId` is read once at startup from `/proc/sys/kernel/random/boot_id`; with
+ * `pid` it lets the reaper tell a dead process:
  *
  * - Same boot: `process.kill(pid, 0)` answers liveness.
  * - Different boot: any pre-reboot row is unconditionally stale.
  *
- * If an orchestrator dies without releasing, the next reservation request
- * from any orchestrator on the host calls `reapStale()` first, so there's
- * no leak window beyond the next spawn attempt.
+ * Each reservation reaps first, so a crashed orchestrator's rows leak no longer
+ * than the next spawn attempt.
  */
 import type { ResourceCap } from './types.js';
 /** Wire format for the per-pool ledger JSON file. */
@@ -38,103 +31,70 @@ export interface LedgerFile {
     cap: ResourceCap;
     reservations: ReservationRow[];
 }
-/** A single reservation row in the ledger. */
 export interface ReservationRow {
-    /** Orchestrator instance id (from `KICI_CLUSTER_INSTANCE_ID` or generated). */
+    /** From `KICI_CLUSTER_INSTANCE_ID`, or generated. */
     instanceId: string;
-    /** Process id that owns this reservation. */
     pid: number;
-    /** Linux boot id at the time the row was created. */
+    /** Linux boot id when the row was created. */
     bootId: string;
-    /** Agent id this reservation is associated with. */
     agentId: string;
-    /** Reserved cpus (cores). */
+    /** Cores. */
     cpus: number;
-    /** Reserved memory in bytes. */
     memBytes: number;
-    /** When the row was inserted (epoch ms). */
+    /** Epoch ms. */
     reservedAt: number;
 }
 /**
- * File-backed machine pool ledger.
- *
- * One instance is shared across all scaler entries that reference any pool
- * (the pool name is passed per-call). The ledger does not cache the JSON:
- * every operation goes through the lock, reads the file, applies the
- * mutation, and writes it back — keeping the wire format the only source
- * of truth across processes.
+ * One instance serves every pool (named per call). It never caches the JSON:
+ * every operation locks, reads, mutates and writes back, so the file is the
+ * only source of truth across processes.
  */
 export declare class MachineLedger {
     private readonly bootId;
     private dirPath;
     private readonly explicitDir;
     private readonly instanceId;
-    /** Per-process knownCaps cache; the on-disk file's `cap` must match the caller's expectation. */
+    /** The on-disk file's `cap` must match. */
     private readonly expectedCaps;
-    /** Reaper interval handle. */
     private reaperTimer;
     constructor(opts: {
         explicitDir?: string;
         instanceId: string;
     });
-    /**
-     * Lazy directory resolution so construction stays synchronous. Called from
-     * every operation; resolves once and caches.
-     */
+    /** Lazy, so construction stays synchronous; resolves once. */
     private ensureDir;
     /** Register the expected cap for a pool. The on-disk file's cap must match. */
     registerPool(name: string, cap: ResourceCap): void;
-    /**
-     * Path to the JSON file for `poolName`. Sibling lockdir is `<file>.lock`.
-     */
+    /** The pool's JSON file and its sibling lockdir. */
     private pathFor;
-    /**
-     * Atomic mkdir-based lock. Held for the duration of `fn`.
-     */
     private withLock;
     /**
-     * If the lock directory has been held for more than 30 seconds, assume the
-     * holder is dead and release it. Without this, an orchestrator that gets
-     * SIGKILL'd while holding the lock would leave it stuck forever.
+     * A lockdir older than 30 seconds is presumed dead and released; otherwise a
+     * holder SIGKILL'd mid-lock wedges the pool forever.
      */
     private maybeReleaseStaleLock;
-    /**
-     * Read the ledger file (or initialize an empty one when missing).
-     */
+    /** A missing file reads as an empty ledger. */
     private readLedger;
     /** Atomic write via temp-file + rename. */
     private writeLedger;
     /**
-     * Try to add a reservation. Returns true if the cap allowed it (and the row
-     * was persisted), false if any cap would be exceeded after summing.
-     *
-     * Reaps stale rows from dead processes before checking the cap so an
-     * orphaned reservation doesn't permanently squat capacity.
+     * Persist a reservation and return true, or false when any cap would be
+     * exceeded. Dead rows are reaped first, so an orphan never squats capacity.
      */
     tryReserve(poolName: string, agentId: string, cpus: number, memBytes: number): Promise<boolean>;
-    /**
-     * Release the reservation for `agentId`. Idempotent.
-     */
+    /** Idempotent. */
     release(poolName: string, agentId: string): Promise<void>;
-    /**
-     * Reap stale (dead-process) rows for the given pool. Called periodically.
-     */
+    /** Reap dead-process rows; called periodically. */
     reapStale(poolName: string): Promise<void>;
     /**
-     * Mutates `ledger.reservations` in place to drop rows that point at dead
-     * processes. Live-pid heuristic:
-     * - Different bootId → unconditionally dead (host rebooted since).
-     * - Same bootId, OWN instance: probe via `process.kill(pid, 0)` (always
-     *   works inside this process's PID namespace).
-     * - Same bootId, OTHER instance: keep the row. We cannot safely
-     *   `process.kill(pid, 0)` against a peer orchestrator's PID — when the
-     *   two orchestrators share a host but live in different PID namespaces
-     *   (e.g. one runs natively and the other in a container), `kill` returns
-     *   ESRCH for any peer pid and the reservation would be falsely reaped,
-     *   silently breaking the cross-process cap. Peer cleanup happens via
-     *   `releaseAllForInstance()` on graceful shutdown; SIGKILL'd peers leave
-     *   their rows in place until the host reboots (which the bootId check
-     *   then reaps unconditionally).
+     * Drop, in place, rows that point at dead processes:
+     * - Different bootId: dead (host rebooted since).
+     * - Same bootId, OWN instance: probe with `process.kill(pid, 0)`, which works
+     *   inside this PID namespace.
+     * - Same bootId, OTHER instance: keep. A peer in another PID namespace (native
+     *   vs container) gets ESRCH for every pid, so probing would falsely reap and
+     *   silently break the cap. Peers release on graceful shutdown; a SIGKILL'd
+     *   peer's rows stay until the next reboot.
      */
     private dropDeadReservations;
     /** Return current usage (sum of `requests` across all live rows). */
@@ -142,18 +102,11 @@ export declare class MachineLedger {
         cpus: number;
         memBytes: number;
     }>;
-    /**
-     * Start the periodic reaper. Idempotent. The reaper iterates every
-     * registered pool every 30s.
-     */
+    /** Start the periodic reaper over every registered pool. Idempotent. */
     start(intervalMs?: number): void;
-    /** Stop the periodic reaper. */
     stop(): void;
     private reapAllPools;
-    /**
-     * Best-effort: release every reservation owned by this instance across all
-     * registered pools. Called on graceful shutdown.
-     */
+    /** Best-effort release of this instance's rows in every pool, on graceful shutdown. */
     releaseAllForInstance(): Promise<void>;
 }
 //# sourceMappingURL=machine-ledger.d.ts.map