@kici-dev/orchestrator 0.17.0 → 0.18.0

package/dist/scaler/container-backend.d.ts

@@ -1,10 +1,7 @@
 /**
- * Container scaler backend implementation.
- *
- * Manages ephemeral agent containers using Docker or Podman via dockerode.
- * Supports auto-detection of container runtime socket.
- * Handles full container lifecycle: pull, create, start, stop, remove.
- * Supports container socket sharing, resource limits, and orphan cleanup.
+ * Container scaler backend: ephemeral agent containers on Docker or Podman via
+ * dockerode, with runtime-socket auto-detection, socket sharing, resource
+ * limits and orphan cleanup.
  */
 import Docker from 'dockerode';
 import { type ToolRequirement } from '@kici-dev/shared';
@@ -14,9 +11,6 @@ import type { ScalerBackend, ScalerDestroyContext, ManagedAgent, LabelSetConfig,
 export declare const ISOLATED_NETWORK_NAME = "kici-agent-net";
 /** Gateway IP for the isolated agent network (host-side). */
 export declare const ISOLATED_NETWORK_GATEWAY = "172.30.0.1";
-/**
- * Result of runtime detection.
- */
 export interface DetectedRuntime {
     socketPath: string;
     runtime: 'docker' | 'podman';
@@ -41,9 +35,12 @@ export interface ContainerScalerBackendOptions {
     runtime?: 'docker' | 'podman' | 'auto';
     /** Default resource limits applied when label set has none */
     defaultResources?: ResourceRequest;
-    /** Extra host:IP mappings injected into spawned containers (e.g. ["registry.local:host-gateway"]) */
+    /** Extra host:IP mappings for spawned containers (e.g. ["registry.local:host-gateway"]). */
     extraHosts?: string[];
-    /** Disable nftables-based network isolation (default: true). Set to false when nft is unavailable (e.g. rootless containers without NET_ADMIN). */
+    /**
+     * Enables nftables-based network isolation (default: true). Set to false when nft is
+     * unavailable (e.g. rootless containers without NET_ADMIN).
+     */
     networkIsolation?: boolean;
     /**
      * Extra `hostAccess` entries the orchestrator itself directed agents at —
@@ -51,7 +48,7 @@ export interface ContainerScalerBackendOptions {
      * narrowing does not cut off a host-local object store.
      */
     hostServices?: string[];
-    /** Token store for creating ephemeral agent auth tokens. Optional -- when undefined, no token is injected. */
+    /** Token store for ephemeral agent auth tokens; when undefined, no token is injected. */
     tokenStore?: AgentTokenStore;
     /** TTL for ephemeral agent tokens in ms. Default: 1 hour. */
     tokenTtlMs?: number;
@@ -138,13 +135,10 @@ export declare class ContainerScalerBackend implements ScalerBackend {
     /**
      * Declare required tools for a container scaler entry.
      *
-     * For the auto-detect case (no explicit socketPath / remote host) the
-     * orchestrator must have a local container runtime — docker OR podman — on
-     * PATH, otherwise the scaler cannot spawn agent containers. Declaring it
-     * here lets the startup tool-validation gate fail fast with a clear error
-     * instead of the first job hanging. When a socketPath or remote host is
-     * configured the binary need not be on PATH (the runtime may be remote), so
-     * reachability is validated later in create().
+     * Auto-detect (no socketPath / remote host) needs docker OR podman on PATH;
+     * declaring it lets the startup tool-validation gate fail fast instead of the
+     * first job hanging. With a socketPath or remote host the runtime may be
+     * remote, so create() validates reachability instead.
      */
     static getRequiredTools(entry: ScalerEntry): ToolRequirement[];
     /**
@@ -179,9 +173,7 @@ export declare class ContainerScalerBackend implements ScalerBackend {
     spawn(labelSet: string[], agentId: string, orchestratorUrl: string, onEvent?: ScalerEventCallback, effectiveLimits?: EffectiveLimits, spawnContext?: SpawnContext, signal?: AbortSignal): Promise<ManagedAgent>;
     getScalerContext(agentId: string): Record<string, unknown> | undefined;
     destroy(managedId: string, _context?: ScalerDestroyContext): Promise<void>;
-    /**
-     * Get the LogCapture for a managed agent (used by ScalerManager for log forwarding).
-     */
+    /** Used by ScalerManager for log forwarding. */
     getLogCapture(managedId: string): LogCapture | undefined;
     shutdownAll(): Promise<void>;
     reload(labelSets: LabelSetConfig[], opts?: {
@@ -191,14 +183,11 @@ export declare class ContainerScalerBackend implements ScalerBackend {
     /**
      * Clean up this scaler's orphaned containers and stale isolation rules.
      *
-     * Every filter below exists because the sweep used to list every
-     * `kici-managed=true` container on the host and force-remove it, running at
-     * orchestrator boot, at worker-peer start, on a live config reload that adds
-     * a scaler, and from `kici-admin scaler reap-orphans`. Two orchestrators
-     * sharing one docker host therefore killed each other's running agents on
-     * every boot, and adding a second container scaler removed the first one's
-     * agents mid-job — every in-flight job failing as "agent disconnected" on a
-     * healthy system.
+     * Runs at orchestrator boot, at worker-peer start, on a live config reload
+     * that adds a scaler, and from `kici-admin scaler reap-orphans`. Without the
+     * filters below, two orchestrators sharing one docker host kill each other's
+     * running agents on every boot, and adding a second container scaler removes
+     * the first one's agents mid-job ("agent disconnected" on a healthy system).
      *
      * A container is removed only when all of these hold:
      *  - it carries this scaler's own `kici-scaler-name`, so a backend can only
@@ -216,11 +205,9 @@ export declare class ContainerScalerBackend implements ScalerBackend {
     /**
      * Remove containers this backend spawned for one agent id.
      *
-     * Implements the optional `ScalerBackend.reapUnowned` hook. It is what
-     * reclaims a container whose registration the orchestrator refused — the
-     * case `cleanupOrphans` used to cover by removing every `kici-managed`
-     * container on the host, which is exactly the breadth that killed other
-     * orchestrators' live agents.
+     * Implements the optional `ScalerBackend.reapUnowned` hook: it reclaims a
+     * container whose registration the orchestrator refused, so `cleanupOrphans`
+     * need not reap host-wide and kill other orchestrators' live agents.
      *
      * @returns true when a container was found and removed
      */

package/dist/scaler/container-hostconfig.d.ts

@@ -1,12 +1,9 @@
 /**
  * The `HostConfig` every KiCI agent container is created with.
  *
- * Two backends spawn an agent container — `ContainerScalerBackend` and the
- * bare-metal backend's container mode — and they had diverged into two
- * postures for one threat: the first applied resource limits, the second
- * applied none and dropped the limits the operator configured on the floor.
- * One builder is what keeps them from diverging again the next time either is
- * touched.
+ * Shared by both agent-container spawners — `ContainerScalerBackend` and the
+ * bare-metal backend's container mode — so they cannot diverge into two
+ * postures (one silently dropping the operator's resource limits).
  */
 import type Docker from 'dockerode';
 import type { EffectiveLimits } from './types.js';
@@ -25,18 +22,15 @@ export declare const AGENT_CONTAINER_PIDS_LIMIT = 4096;
  * Both spawn paths set `KICI_EXECUTION_MODE=bare-metal`, and bare-metal
  * container mode also sets `KICI_JOB_IMAGE_AGENT=1` — so unless the job
  * declares its own image, the workflow's steps run as host processes INSIDE
- * this container. It is a build execution environment, not a supervisor.
- * `CapDrop: ['ALL']` here would therefore land on customer build steps:
+ * this container. `CapDrop: ['ALL']` here would land on customer build steps:
  * `apt-get` and `dpkg` need CHOWN, DAC_OVERRIDE, FOWNER, SETUID and SETGID,
- * and `no-new-privileges` breaks `sudo` and every setuid binary. There is no
- * opt-out, so the break would be silent and total for `type: container`
- * scalers.
+ * and `no-new-privileges` breaks `sudo` and every setuid binary. With no
+ * opt-out, the break would be silent and total for `type: container` scalers.
  *
- * The hardening the operator docs promise already exists, one boundary in:
- * the agent applies `CapDrop: ['ALL']`, `no-new-privileges` and a tighter
- * `PidsLimit` to each nested JOB container
- * (`packages/agent/src/execution/sandbox/container-hardening.ts`). That is the
- * boundary that confines customer code; this one hosts it.
+ * The promised hardening lives one boundary in: the agent applies
+ * `CapDrop: ['ALL']`, `no-new-privileges` and a tighter `PidsLimit` to each
+ * nested JOB container (`packages/agent/src/execution/sandbox/container-hardening.ts`).
+ * That boundary confines customer code; this one hosts it.
  *
  * `PidsLimit` is the exception and stays: a fork-bomb ceiling costs a build
  * nothing at 4096.

package/dist/scaler/container-routing.d.ts

@@ -1,20 +1,17 @@
 /**
  * Label for hosts that can run containers.
  *
- * The agent reports it itself at registration when it finds a Docker socket,
- * alongside `kici:runtime:podman` for a Podman one and the `kici:os:*` /
- * `kici:arch:*` facts: whether a machine has a container runtime is that
- * machine's fact, not the orchestrator's. Probing the orchestrator's own
- * filesystem answers a different question — it was tried, and it stranded
- * container jobs that had been running fine, because the probe and the job ran
- * in different places.
+ * The agent reports it at registration when it finds a Docker socket (and
+ * `kici:runtime:podman` for a Podman one): a container runtime is the agent
+ * machine's fact. Probing the orchestrator's own filesystem was tried and
+ * stranded working container jobs, because the probe and the job ran in
+ * different places.
  *
- * Routing gates on the reported label (`canAgentRunJob`): a `container:` job
- * reaches an agent only when that agent was started for it, or reports
- * `kici:runtime:docker` or `kici:runtime:podman`. For an operator's own agent
- * the gate applies from the release that reports runtime labels at all; an
- * older agent reports none, so its silence proves nothing and a job it cannot
- * run fails on it with a message that names the missing runtime.
+ * Routing (`canAgentRunJob`): a `container:` job reaches an agent only when that
+ * agent was started for it, or reports `kici:runtime:docker` or
+ * `kici:runtime:podman`. An older agent reports no runtime labels, so its
+ * silence proves nothing; a job it cannot run fails with a message that names
+ * the missing runtime.
  *
  * An operator may still put the label on a pool's label sets and on a container
  * job's `runsOn` to steer container work at hosts with a runtime.

package/dist/scaler/disk-guard.d.ts

@@ -18,9 +18,8 @@ interface DiskGuardOpts {
     reapFn?: (cfg: ScalerConfig) => Promise<ReapCounts>;
 }
 /**
- * Run the disk guard. Returns reaped/recovered status; the caller decides
- * whether to proceed or exit with backoff. No-ops (recovered=true) when there
- * is no FC scaler or free space is already above threshold.
+ * The caller decides whether to proceed or exit with backoff. No-ops
+ * (recovered=true) when there is no FC scaler or free space is above threshold.
  */
 export declare function runDiskGuard(opts: DiskGuardOpts): Promise<DiskGuardResult>;
 export {};

package/dist/scaler/event-backend.d.ts

@@ -1,33 +1,25 @@
 /**
  * Event scaler backend — workflow-driven autoscaling.
  *
- * Unlike the local backends (container / bare-metal / firecracker), this backend
- * performs NO local compute. Its `spawn()` emits a `kici.scaler.scale-up` event
- * and its `destroy()` emits a `kici.scaler.scale-down` event; a customer-authored
- * provisioning / teardown workflow (subscribed via `kiciEvent()`) consumes those
- * events to boot and tear down an ephemeral cloud instance. The provisioned
- * instance's agent registers back with the scaler-chosen `agentId` and the
- * existing bound-job dispatch runs the pending job — reusing the whole scaling
- * engine (demand detection, caps, reservations, spawn timeout, teardown).
+ * No local compute: `spawn()` emits `kici.scaler.scale-up` and `destroy()` emits
+ * `kici.scaler.scale-down`, which a customer workflow (via `kiciEvent()`) consumes
+ * to boot and tear down an ephemeral cloud instance. Its agent registers with the
+ * scaler-chosen `agentId` and bound-job dispatch runs the pending job, so the
+ * whole scaling engine (caps, reservations, spawn timeout, teardown) applies.
  */
 import type { EffectiveLimits, LabelSetConfig, ManagedAgent, ScalerBackend, ScalerDestroyContext, ScalerEntry, ScalerEventCallback, SpawnContext, ValidationResult } from './types.js';
 import type { ClaimStore } from './claim-store.js';
 import type { ScalerScaleUpPayload, ScalerScaleDownPayload } from './scaler-events.js';
-/**
- * Subset of `EventEmitter` the backend needs. Injected so the backend is unit
- * testable without a real event router.
- */
+/** Subset of `EventEmitter` the backend needs; injected for unit tests. */
 export interface ScalerEventEmitterLike {
     emitScalerScaleUp(payload: ScalerScaleUpPayload, targets: string[]): Promise<string>;
     emitScalerScaleDown(payload: ScalerScaleDownPayload, targets: string[]): Promise<string>;
 }
 export interface EventScalerBackendOptions {
-    /** The parsed scaler entry (`type: 'event'`). */
+    /** `type: 'event'`. */
     entry: ScalerEntry;
-    /** Emits the reserved scale-up / scale-down events. */
     emitter: ScalerEventEmitterLike;
-    /** Mints ephemeral credentials when a claim code is redeemed — normally by
-     * the provisioned agent self-bootstrapping, or by a provisioning workflow. */
+    /** Redeemed by the self-bootstrapping agent, or by a provisioning workflow. */
     claimStore: ClaimStore;
     /** Correlation-id generator for scale-up / scale-down requests. */
     requestId: () => string;
@@ -48,40 +40,29 @@ export declare class EventScalerBackend implements ScalerBackend {
     /** The entry this backend is serving; the reload rollback restores it. */
     get currentEntry(): ScalerEntry;
     getActiveCount(): number;
-    /**
-     * Register a pending claim, emit a scale-up event to the provisioning targets,
-     * and track the agent as provisioning. Performs no local compute.
-     */
     spawn(labelSet: string[], agentId: string, orchestratorUrl: string, _onEvent?: ScalerEventCallback, effectiveLimits?: EffectiveLimits, spawnContext?: SpawnContext, signal?: AbortSignal): Promise<ManagedAgent>;
     /**
-     * Drop the tracked agent, emit a scale-down event (carrying the teardown
-     * reason), then invalidate the pending claim. Idempotent: a repeat destroy of
-     * an already-torn-down agent is a no-op (no duplicate scale-down).
+     * Drop the tracked agent, emit a scale-down with the reason, then invalidate
+     * the pending claim. Idempotent: a repeat destroy emits nothing.
      *
-     * The tracking entry is dropped before the first `await` so a concurrent
-     * destroy of the same agent returns at the guard above and cannot emit a
-     * second scale-down.
+     * The entry is dropped before the first `await`, so a concurrent destroy
+     * returns at the guard and cannot emit a second scale-down.
      *
-     * The claim invalidation is last and fails open. It is a DB delete, and the
-     * scale-down is the only thing that tears down the customer's cloud instance:
-     * running the delete first lets a DB error suppress the teardown for good,
-     * because the agent is already out of `this.agents` and a retried destroy
-     * returns at the guard. A claim left behind instead is inert — the row is
-     * single-use and TTL-bounded, so it can mint at most one token for an agent
-     * id that is being torn down.
+     * The claim invalidation is last and fails open. The scale-down is the only
+     * teardown of the customer's instance, so a DB error before it would suppress
+     * the teardown for good (a retried destroy returns at the guard). A leftover
+     * claim is single-use and TTL-bounded: at most one token for a dying agent id.
      */
     destroy(managedId: string, context?: ScalerDestroyContext): Promise<void>;
     /**
      * Drop the tracked agent without emitting anything.
      *
-     * The counterpart to `adopt()` on the other side of a cross-instance
-     * registration: the spawning coordinator is never told that a peer adopted
-     * its provision, so its entry would otherwise live until the process exits —
-     * inflating `getActiveCount()` against the global cap forever, and handing
-     * `shutdownAll()` a peer's live agent to tear down. Forgetting says "this
-     * coordinator no longer tracks the provision", which is exactly true and says
-     * nothing about whether the customer's instance is still running; the adopter
-     * emits the teardown, and the leader-gated reaper is the backstop.
+     * The spawning side of a cross-instance `adopt()`. The spawner is never told
+     * a peer adopted its provision, so its entry would otherwise inflate
+     * `getActiveCount()` against the global cap until exit, and hand
+     * `shutdownAll()` a peer's live agent. It says nothing about whether the
+     * instance runs: the adopter emits the teardown, the leader-gated reaper is
+     * the backstop.
      */
     forget(agentId: string): void;
     /**
@@ -92,29 +73,23 @@ export declare class EventScalerBackend implements ScalerBackend {
     adopt(agentId: string, labelSet: string[]): void;
     /** Mark a provisioned agent active once its instance registers over WS. */
     markActive(agentId: string): void;
-    /** Delegate a credential claim to the backend's claim store. */
     claim(code: string): Promise<import("./claim-store.js").ClaimedCredentials>;
     /**
-     * Emits nothing. An event provision is a customer cloud instance whose
-     * lifetime spans the cluster, not this process: the coordinator holding the
-     * agent emits its teardown from the WS-close path, and the leader-gated
-     * reaper is the backstop for one that reaches nobody. This map also carries
-     * provisions a peer has already adopted — the spawning coordinator is never
-     * told — so emitting here would make a routine restart tear down a peer's
-     * running agents.
+     * Emits nothing. A provision's lifetime spans the cluster, not this process:
+     * the coordinator holding the agent emits teardown on WS close, and the
+     * leader-gated reaper is the backstop. The map may hold provisions a peer
+     * adopted, so emitting here would make a routine restart tear down a peer's
+     * agents.
      *
-     * The map is deliberately left intact rather than cleared: a WS close landing
-     * during the remaining shutdown steps then still emits its own teardown.
+     * The map is left intact so a WS close during the remaining shutdown steps
+     * still emits its own teardown.
      */
     shutdownAll(): Promise<void>;
     /**
-     * Apply the new config. The backend reads `roles`, `agentTokenTtlSeconds`
-     * and `provisioningTargets` off its entry at every spawn (and
-     * `mandatoryLabels` only when a spawn reaches it without a context), so the
-     * entry is replaced here — otherwise a reload that retargets the
-     * provisioning workflow, or changes the scaler's roles, would keep emitting
-     * scale-up events to the old workflow refs and minting agent labels from the
-     * old roles, while the manager's own routing gate used the new ones.
+     * Replace the entry: each spawn reads `roles`, `agentTokenTtlSeconds`,
+     * `provisioningTargets` (and, without a context, `mandatoryLabels`) from it.
+     * Otherwise a reload would keep emitting to the old workflow refs and minting
+     * labels from the old roles while the manager's routing gate uses the new ones.
      */
     reload(labelSets: LabelSetConfig[], opts?: {
         maxAgents?: number;

package/dist/scaler/event-provision-reaper.d.ts

@@ -3,19 +3,16 @@ import type { ReapCandidate } from './scaler-state-store.js';
 /**
  * How long a provision outcome is kept once its spawn row is gone.
  *
- * Deliberately a constant rather than a `cluster_settings` knob: unlike the
- * claim retention beside it, there is no operational decision here. The only
- * reader is the stale-spawn prune, and the interval the row must survive is
- * derived from windows the reaper already resolves — so a knob would be surface
- * with nothing behind it. The purge floors this against twice the spawn
- * deadline, so raising `KICI_SCALER_SPAWN_TIMEOUT_MS` for a slow cloud widens
- * the retention with it.
+ * A constant, not a `cluster_settings` knob: unlike the claim retention, it
+ * carries no operational decision. Its only reader is the stale-spawn prune,
+ * and the interval the row must survive derives from windows the reaper already
+ * resolves. The purge floors it at twice the spawn deadline, so raising
+ * `KICI_SCALER_SPAWN_TIMEOUT_MS` for a slow cloud widens the retention with it.
  */
 export declare const PROVISION_OUTCOME_RETENTION_MS = 86400000;
 /**
- * The live values one sweep runs against. Read together at the top of each tick
- * so a sweep is internally consistent even if an operator changes a knob
- * halfway through.
+ * The live values one sweep runs against, read together at the top of each tick
+ * so a knob changed mid-sweep cannot make the sweep inconsistent.
  */
 export interface ReaperWindows {
     /** How often the leader sweeps. A change reschedules the timer after this tick. */
@@ -39,21 +36,17 @@ export interface ReaperWindows {
 /**
  * The flap grace the reaper actually runs on.
  *
- * `reroute_flap_grace_ms` is shared with the rerouted-job guard, and the two
- * consumers do not carry the same risk: the reroute guard force-fails a run it
- * could have waited for, while this one deletes a customer's running instance.
- * An operator lowering the knob for reroute reasons must not silently collapse
- * that protection to two consecutive sweeps.
+ * `reroute_flap_grace_ms` is shared with the rerouted-job guard, which only
+ * force-fails a run it could have waited for; this consumer deletes a
+ * customer's running instance. Lowering the knob for reroute reasons must not
+ * silently collapse that protection to two consecutive sweeps.
  *
- * The floor is two peer-stale-timeout windows — the very derivation the knob's
- * own default (`DEFAULT_REROUTE_FLAP_GRACE_MS`) comes from, applied as a floor
- * rather than a default. It has to cover the worst honest gap between an agent
- * being alive and being visible here: an agent reconnect backing off to its cap
- * (60s), plus the peer heartbeat interval (30s) during which a freshly
- * reconnected peer advertises no agents at all. Two stale windows (120s at the
- * defaults) covers that 90s; one (60s) would not.
- *
- * A raised knob is honoured as-is: the floor only ever raises.
+ * The floor is two peer-stale-timeout windows, the derivation of the knob's own
+ * default (`DEFAULT_REROUTE_FLAP_GRACE_MS`) applied as a floor. It covers the
+ * worst honest gap between an agent being alive and visible here: a reconnect
+ * backing off to its cap (60s) plus the peer heartbeat interval (30s) in which a
+ * freshly reconnected peer advertises no agents. Two windows (120s at the
+ * defaults) cover that 90s; one (60s) would not. The floor only ever raises.
  */
 export declare function reaperFlapGraceMs(flapGraceMs: number, peerStaleTimeoutMs: number): number;
 /** The slice of the peer registry the cluster-view guard reads. */
@@ -67,28 +60,25 @@ export interface ReaperPeerView {
  * The reaper's `canReap` predicate, over static config plus the live peer
  * registry.
  *
- * Extracted and exported so the wiring itself is testable. The bug this closes
- * lived in exactly this expression — `clusterViewSufficient` was unit-tested
- * throughout, while the call site that fed it the wrong count was not, so the
- * guard read permissive on a Platform-mode HA pair through two review rounds.
- * A component whose false positive deletes a customer's running instances
- * cannot have an untested load-bearing line.
+ * Exported so the wiring itself is tested, not only `clusterViewSufficient`: a
+ * call site feeding it the wrong count reads permissive on a Platform-mode HA
+ * pair, and a component whose false positive deletes a customer's running
+ * instances cannot have an untested load-bearing line.
  *
- * The peer count is the max of the two sources because neither alone covers
- * both modes: `KICI_CLUSTER_PEERS` is set only in independent mode, while a
- * Platform-mode cluster learns its peers from the matchmaker and leaves that
- * array empty. `getCoordinatorPeers()` filters on role, not on connectivity, so
- * a peer lost to a partition stays counted and the guard stays armed.
+ * The peer count is the max of two sources because neither covers both modes:
+ * `KICI_CLUSTER_PEERS` is set only in independent mode, while a Platform-mode
+ * cluster learns its peers from the matchmaker and leaves that array empty.
+ * `getCoordinatorPeers()` filters on role, not connectivity, so a peer lost to
+ * a partition stays counted and the guard stays armed.
  */
 export declare function canReapForCluster(configuredPeerCount: number, peers: ReaperPeerView): boolean;
 /**
  * Whether an adopting coordinator should still be treated as live.
  *
- * Mirrors `shouldDeferReroutedJob`, and for the same reason: `PeerRegistry`
- * flips `connected` the instant a peer WS closes, with no grace of its own, so
- * sampling it alone cannot tell a link blip between two healthy processes from
- * a dead coordinator — while the agent is still attached to that peer running a
- * customer job. A peer we have never heard of is genuinely gone.
+ * Mirrors `shouldDeferReroutedJob`: `PeerRegistry` flips `connected` the
+ * instant a peer WS closes, with no grace, so sampling it alone cannot tell a
+ * link blip between two healthy processes (whose agent still runs a customer
+ * job) from a dead coordinator. A peer never heard of is genuinely gone.
  */
 export declare function adopterIsLive(peer: {
     connected: boolean;
@@ -106,13 +96,11 @@ export declare function adopterIsLive(peer: {
  * backstop; not standing down costs the customer their fleet.
  *
  * `knownCoordinatorPeerCount` must count peers this coordinator has *ever*
- * handshaken with, not the ones named in static config. `KICI_CLUSTER_PEERS` is
- * set only in multi-orchestrator independent mode: the documented HA-pair recipe
- * runs Platform mode and joins by token, so peers arrive through the Platform
- * matchmaker and the static array stays empty. Keying on it left the guard inert
- * on precisely the topology it exists to protect. A known peer survives a
- * partition because `evictStalePeers` only marks it disconnected, so the guard
- * stays armed for as long as the partition lasts.
+ * handshaken with, not the ones in static config: `KICI_CLUSTER_PEERS` is set
+ * only in independent mode, and the documented HA-pair recipe runs Platform mode
+ * with peers from the matchmaker, so keying on it leaves the guard inert on the
+ * topology it exists to protect. `evictStalePeers` only marks a known peer
+ * disconnected, so the guard stays armed for the whole partition.
  *
  * A coordinator that has never met a peer is a single-coordinator deployment,
  * not a partitioned one, so it is never blocked.
@@ -123,21 +111,17 @@ export interface EventProvisionReaperOptions {
     listCandidates: (spawnCutoff: Date) => Promise<ReapCandidate[]>;
     /**
      * Whether an instance id is still a live cluster member (self counts as live).
-     * `flapGraceMs` is passed in so the implementation can treat a peer that
-     * disconnected moments ago as live — `peer.connected` alone flips on WS close
-     * with no grace at all.
+     * `flapGraceMs` lets a peer that disconnected moments ago count as live:
+     * `peer.connected` flips on WS close with no grace.
      */
     isPeerLive: (instanceId: string, flapGraceMs: number) => boolean;
     /** Whether an agent id is registered anywhere in the cluster we can see. */
     isAgentRegistered: (agentId: string) => boolean;
     /**
-     * Whether this coordinator can see enough of the cluster to act on its
-     * behalf. False on a node that *knows* coordinator peers but is connected to
-     * none of them, which is exactly the shape a network partition produces.
-     *
-     * "Knows" spans both modes: peers named in static config, plus peers this
-     * instance has handshaken with. Keying on static config alone is what left
-     * this guard inert on a Platform-mode HA pair, which configures none.
+     * Whether this coordinator sees enough of the cluster to act for it: false on
+     * a node that *knows* coordinator peers (static config plus every peer it
+     * handshook with) but is connected to none, the shape a partition produces.
+     * Static config alone leaves the guard inert on a Platform-mode HA pair.
      */
     canReap: () => boolean;
     /** Emit the teardown and drop the row. */
@@ -146,21 +130,19 @@ export interface EventProvisionReaperOptions {
     purgeExpiredClaims: (cutoff: Date) => Promise<number>;
     /**
      * Delete provision outcomes older than the cutoff whose spawn row is gone;
-     * returns rows deleted. Runs on the same leader-gated sweep as the claim
-     * purge, which is the orchestrator's one precedent for a timer-driven purge
-     * of scaler bookkeeping.
+     * returns rows deleted. Runs on the leader-gated sweep beside the claim purge,
+     * the orchestrator's one precedent for a timer-driven scaler-bookkeeping purge.
      */
     purgeProvisionOutcomes: (cutoff: Date) => Promise<number>;
     /**
-     * Read the live windows for one sweep. Backed by `cluster_settings`, so an
-     * operator retunes the reaper on a running cluster; each read falls back to
-     * the orchestrator's configured default when the column is NULL.
+     * The live windows for one sweep, from `cluster_settings` so an operator
+     * retunes a running cluster; a NULL column falls back to the configured default.
      */
     resolveWindows: () => Promise<ReaperWindows>;
     /**
-     * Interval used for the very first schedule, before any knob has been read.
-     * `onBecomeLeader` is synchronous (it is a Raft callback), so the timer starts
-     * at the configured default and the first tick reconciles it to the live value.
+     * The first schedule's interval. `onBecomeLeader` is a synchronous Raft
+     * callback, so the timer starts at the configured default and the first tick
+     * reconciles it to the live value.
      */
     bootIntervalMs: number;
 }
@@ -229,25 +211,21 @@ export declare class EventProvisionReaper {
     /**
      * agentId → when this reaper first observed the agent registered nowhere.
      *
-     * This is the debounce that makes "unseen" mean sustained absence rather than
-     * one unlucky sample. It is leader-local observation, deliberately not a
-     * database column: `adopted_at` is refreshed by a coordinator re-adopting its
-     * own agent, so a restart loop on the adopter would keep resetting the clock
-     * on its own stranded provision.
+     * The debounce that makes "unseen" mean sustained absence, not one unlucky
+     * sample. Leader-local, deliberately not a database column: a coordinator
+     * re-adopting its own agent refreshes `adopted_at`, so a restart loop on the
+     * adopter would keep resetting the clock on its own stranded provision.
      */
     private readonly strandedSince;
     /**
      * How many entries of `strandedSince` the last sweep found absent for at
      * least the flap grace.
      *
-     * The gauge publishes this rather than `strandedSince.size`, because the two
-     * answer different questions. `size` counts every agent currently observed
-     * absent, and an agent transits that set on every ordinary reconnect — a 30s
-     * peer heartbeat against a 60s sweep, and `PeerRegistry` emptying a peer's
-     * agent list on any disconnect, mean one flap enrols every peer-adopted agent
-     * at once. So `size` is routinely non-zero on a healthy cluster, while
-     * `verdict()` refuses to act on anything below the flap grace. Publishing the
-     * past-grace count makes the gauge measure the same thing the reaper does.
+     * The gauge publishes this, not `strandedSince.size`: an agent transits that
+     * set on every ordinary reconnect (a 30s peer heartbeat against a 60s sweep,
+     * and `PeerRegistry` empties a peer's agent list on any disconnect, so one
+     * flap enrols every peer-adopted agent), so `size` is routinely non-zero on a
+     * healthy cluster. The past-grace count measures what `verdict()` acts on.
      */
     private unseenPastGrace;
     /**
@@ -306,11 +284,10 @@ export declare class EventProvisionReaper {
     /**
      * Adopt a changed sweep interval by rebuilding the timer.
      *
-     * Re-read every sweep rather than only at a leadership transition: a knob an
-     * operator can set but that is silently ignored until the next election is
-     * worse than no knob at all. A value that is not a usable interval is ignored
-     * — a zero or negative `setInterval` period would spin the sweep as fast as
-     * the event loop allows.
+     * Re-read every sweep, not only at a leadership transition: a knob silently
+     * ignored until the next election is worse than none. An unusable value is
+     * ignored, since a zero or negative `setInterval` period spins the sweep as
+     * fast as the event loop allows.
      */
     private reconcileInterval;
     /** Replace the timer with one running at `intervalMs`. */