@kici-dev/orchestrator 0.16.0 → 0.18.0

package/dist/scaler/manager.d.ts

@@ -1,10 +1,8 @@
 /**
- * ScalerManager: central coordinator for all scaler backends.
- *
- * Sits between the orchestrator's Dispatcher and individual scaler backends.
- * Receives "no agent available" signals, routes to the correct backend,
- * enforces global limits, tracks spawning agents to prevent over-provisioning,
- * and manages the agent lifecycle from spawn to destroy.
+ * ScalerManager: coordinator between the Dispatcher and the scaler backends.
+ * Routes "no agent available" signals to a backend, enforces global limits,
+ * tracks spawning agents against over-provisioning, and owns the agent
+ * lifecycle from spawn to destroy.
  */
 import { ScalerVmTracker } from '@kici-dev/engine';
 import type { ResourceRequest, ScalerCapacitySummary, ScalerLiveVm, ScalerReloadPlan, ScalerVmStopResult } from '@kici-dev/engine';
@@ -14,17 +12,15 @@ import type { ScalerEventEmitterLike } from './event-backend.js';
 import type { ClaimStore, ClaimedCredentials } from './claim-store.js';
 /**
  * How long a graceful shutdown waits for the scaler backends to stop their
- * agents. It is the first window inside the coordinator's 30 s shutdown limit,
- * and every later step (the HTTP stop grace, the database drain) still has to
- * fit after it.
+ * agents: the first window inside the coordinator's 30 s shutdown limit, so the
+ * later steps (HTTP stop grace, database drain) still fit after it.
  *
- * A container stop normally takes at most its own 10 s stop timeout, but the
- * container runtime can take far longer: a Docker daemon that misses a
- * container's exit waits out the stop timeout and then another 10 s for its
- * kill, and one such container held the whole step for 29.7 s. Past this
- * window the orchestrator logs each backend still stopping and continues. The
- * runtime finishes the stop on its own, and the next start's orphan cleanup
- * removes any agent container that is still there.
+ * A container stop normally takes at most its own 10 s stop timeout, but a
+ * Docker daemon that misses a container's exit waits out that timeout plus
+ * another 10 s for its kill; one such container held the step for 29.7 s. Past
+ * this window the orchestrator logs each backend still stopping and continues:
+ * the runtime finishes the stop, and the next start's orphan cleanup removes
+ * any agent container left behind.
  */
 export declare const SCALER_SHUTDOWN_GRACE_MS = 15000;
 import type { BackendFailureSummary } from './failure-tracker.js';
@@ -33,11 +29,10 @@ import type { ScalerStateStore, ScalerStateRecovery, ReapCandidate } from './sca
 /** The `skipped` reason for a job whose agent is already provisioning or registered. */
 export declare const PROVISION_IN_FLIGHT = "provision-in-flight";
 /**
- * Raised when a registering agent presents a scaler-minted id that the
- * orchestrator cannot back with a spawn record — either because the lookup
- * could not be completed (`cause` set) or because no record exists at all
- * (`cause` omitted). The WS handler answers it by refusing the registration, so
- * the agent reconnects rather than registering with no `mandatoryLabels` gate.
+ * Raised when a registering agent presents a scaler-minted id with no spawn
+ * record behind it: the lookup failed (`cause` set) or no record exists
+ * (`cause` omitted). The WS handler refuses the registration, so the agent
+ * reconnects rather than registering with no `mandatoryLabels` gate.
  */
 export declare class ScalerAdoptionLookupError extends Error {
     readonly agentId: string;
@@ -45,17 +40,14 @@ export declare class ScalerAdoptionLookupError extends Error {
     constructor(agentId: string, cause?: unknown);
 }
 /**
- * Counting semaphore that throttles the number of concurrent async operations.
- *
- * Used to bound how many `backend.spawn` provisioning operations (image pull +
+ * Counting semaphore bounding how many `backend.spawn` operations (image pull +
  * container create + start) run at once per backend, so a burst of in-cap jobs
  * cannot storm the container socket / registry.
  *
- * Slots are handed directly to the next waiter on release (rather than bumping a
+ * Release hands the slot directly to the next waiter (rather than bumping a
  * counter the woken task re-decrements), so a task arriving in the microtask gap
- * between a release and a woken waiter cannot jump the queue and transiently
- * exceed the cap. The slot is always released in `run`'s `finally`, so a failed
- * or throwing operation never leaks a slot and wedges the queue.
+ * cannot jump the queue and transiently exceed the cap. `run` releases in
+ * `finally`, so a throwing operation never leaks a slot and wedges the queue.
  */
 export declare class SpawnSemaphore {
     private available;
@@ -66,13 +58,7 @@ export declare class SpawnSemaphore {
     run<T>(fn: () => Promise<T>): Promise<T>;
 }
 /**
- * Resolved per-job resource amounts (cpus + bytes) for both `requests` and
- * `limits`. The scaler manager produces this from the job's declared resources
- * combined with the scaler's `defaults.resources`, applying the request<->limit
- * mirroring rule. Caps aggregate `requests`; backends use `limits`.
- */
-/**
- * Resolve the orchestrator WebSocket URL a scaler-spawned agent should dial.
+ * Resolve the orchestrator WebSocket URL a scaler-spawned agent dials.
  *
  * 1. Per-scaler `orchestratorUrl` (scalers.yaml) wins — required for container
  *    agents (host.docker.internal / LAN IP) and Firecracker VMs (bridge gateway
@@ -84,6 +70,11 @@ export declare class SpawnSemaphore {
  *    agents at 8080 leaves them unable to reach the orchestrator.
  */
 export declare function resolveScalerOrchestratorUrl(configUrl: string | undefined, envUrl: string | undefined, port: string | number | undefined): string;
+/**
+ * Resolved per-job `requests` and `limits` (cpus + bytes): the job's declared
+ * resources over the scaler's `defaults.resources`, with request<->limit
+ * mirroring applied. Caps aggregate `requests`; backends use `limits`.
+ */
 export interface ResolvedResources {
     requests: {
         cpus: number;
@@ -111,9 +102,7 @@ export declare function buildScalerUsageRows(perScalerUsage: ReadonlyMap<string,
     cpus: number;
     memBytes: number;
 }>;
-/**
- * Status summary for metrics and health endpoints.
- */
+/** Status summary for metrics and health endpoints. */
 export interface ScalerStatus {
     globalMaxAgents: number;
     globalActiveCount: number;
@@ -206,16 +195,13 @@ export interface ScalerManagerDeps {
         backend: ScalerBackend;
     }>;
     /**
-     * Read-only view of the agent registry, for the warm pool's deficit
-     * calculation. Structural on purpose — the scaler must not depend on the
-     * agent layer's concrete class.
+     * Read-only agent-registry view for the warm pool's deficit. Structural on
+     * purpose: the scaler must not depend on the agent layer's concrete class.
      *
-     * Both hosts pass one, and a host that skips it does not get an inert warm
-     * pool: the readiness count falls back to 0, so a configured pool never sees
-     * the agents it started and keeps filling until `warmCapacityRemaining`
-     * clamps it at `maxAgents` — starving the job-bound spawns that share the
-     * cap. Optional only because the unit tests drive the spawn path without a
-     * registry.
+     * Both hosts pass one. Without it the readiness count falls back to 0, so a
+     * configured pool never sees its own agents and fills until
+     * `warmCapacityRemaining` clamps it at `maxAgents`, starving the job-bound
+     * spawns that share the cap. Optional only for unit tests.
      */
     agentRegistry?: {
         findAvailable(requiredLabels: string[]): Array<{
@@ -238,10 +224,7 @@ export interface ScalerManagerDeps {
     instanceId: string;
     /** Callback for relaying scaler events with runId/jobId context. */
     onScalerEvent?: (runId: string, jobId: string, event: ScalerEvent) => void;
-    /**
-     * Optional DB-backed state store. Tests omit it; production wires it
-     * up via the orchestrator-core bootstrap.
-     */
+    /** DB-backed state store, wired by the orchestrator-core bootstrap; tests omit it. */
     stateStore?: ScalerStateStore;
     /**
      * Late-bound reserved-event emitter, resolved per call because the event
@@ -256,10 +239,9 @@ export interface ScalerManagerDeps {
      */
     claimStore?: ClaimStore;
     /**
-     * Optional machine-ledger options. When `machinePools` are configured,
-     * the manager initializes a `MachineLedger` keyed off this directory and
-     * the orchestrator's instance id; reservations sum across orchestrators
-     * on the same host.
+     * Machine-ledger options. With `machinePools` configured, the manager builds a
+     * `MachineLedger` keyed off this directory and the instance id; reservations
+     * sum across orchestrators on the same host.
      */
     machineLedger?: {
         /** Override the on-disk ledger directory. Falls back to `KICI_MACHINE_LEDGER_DIR`. */
@@ -277,11 +259,10 @@ export interface ScalerManagerDeps {
      */
     spawnTimeoutMs: number;
     /**
-     * Optional per-org resolver for the spawn deadline: given the job's org
-     * (jobConfig.cacheOrgId, undefined for warm-pool spawns), returns the
-     * effective timeout, falling back to the cluster default internally. Wired
-     * in orchestrator-core (has DB); omitted by the worker + unit tests → the
-     * cluster default spawnTimeoutMs is used.
+     * Per-org spawn-deadline resolver, keyed by the job's org
+     * (jobConfig.cacheOrgId, undefined for warm-pool spawns); falls back to the
+     * cluster default internally. Wired in orchestrator-core (has DB); the worker
+     * and unit tests omit it and use spawnTimeoutMs.
      */
     resolveSpawnTimeoutMs?: (orgId: string | undefined) => Promise<number>;
     /**
@@ -301,15 +282,15 @@ export interface ScalerManagerDeps {
      */
     readJobStatuses?: (jobs: readonly BoundJobRef[]) => Promise<ReadonlyMap<string, string>>;
     /**
-     * Constructs a backend for a scaler added by a config reload. Supplied by
-     * both hosts from the shared backend factory, so a reload can only build
-     * what startup already exercises. When omitted (unit tests), a reload that
-     * adds a scaler is rejected rather than silently ignored.
+     * Builds a backend for a scaler a config reload adds. Both hosts supply it
+     * from the shared backend factory, so a reload builds only what startup
+     * exercises. When omitted (unit tests), a reload that adds a scaler is
+     * rejected rather than silently ignored.
      *
-     * `config` is the config being reloaded, not the boot-time one. The factory
-     * reads `defaults.resources` and the whole `firecracker` network block off
-     * it, so an added scaler built from a stale config would allocate IPs from
-     * the old CIDR and attach TAPs to the old bridge — silently unreachable.
+     * `config` is the reloaded config, not the boot-time one: the factory reads
+     * `defaults.resources` and the `firecracker` network block off it, and a
+     * stale one would allocate IPs from the old CIDR and attach TAPs to the old
+     * bridge, silently unreachable.
      */
     createBackend?: (entry: ScalerEntry, config: ScalerConfig) => Promise<ScalerBackend | null>;
 }
@@ -331,17 +312,16 @@ export declare class ScalerManager {
     private readonly failureTracker;
     /**
      * Consecutive provisioning failures per scaler NAME, and the deferral they
-     * earned: an event scaler's external provision that never registered an
-     * agent, or a local launch that produced no agent (refused outright, or the
-     * agent stopped before it registered).
+     * earned: an event provision that never registered an agent, or a local
+     * launch that produced none (refused, or the agent stopped before
+     * registering).
      *
-     * Keyed by name rather than by backend type so one failing scaler never
-     * defers spawns for an unrelated one — two event scalers routinely drive two
-     * different providers, and an outage at one says nothing about the other.
+     * Keyed by name, not backend type, so one failing scaler never defers an
+     * unrelated one: two event scalers often drive two different providers.
      *
-     * In-memory and leader-local, like `ScalerFailureTracker`: the state resets on
-     * restart, which is the conservative direction (a fresh coordinator retries
-     * once immediately rather than inheriting a deferral it never observed).
+     * In-memory and leader-local, like `ScalerFailureTracker`: a restart resets
+     * it, the conservative direction (a fresh coordinator retries once at once
+     * rather than inheriting a deferral it never observed).
      */
     private readonly provisionFailures;
     private readonly resolveProvisionBackoff;
@@ -405,81 +385,54 @@ export declare class ScalerManager {
      * teardown workflow when the agent it adopted disconnects.
      */
     private readonly scalerProvisioningTargets;
-    /**
-     * Tracks agents being spawned but not yet registered via WS.
-     * Keyed by pre-generated agentId.
-     */
+    /** Agents spawned but not yet registered via WS, keyed by pre-generated agentId. */
     private readonly spawningAgents;
-    /**
-     * Maps registered agentId to backendName for lifecycle events.
-     */
+    /** Registered agentId → backendName, for lifecycle events. */
     private readonly managedAgentIndex;
     /**
-     * Agents this instance pre-spawned to wait for work, rather than for a
-     * specific queued job. The agent registry tracks readiness (`activeJobs`,
-     * `registeredAt`) and has never tracked provenance — it cannot derive this,
-     * and the spawning entry that carries it is deleted at registration.
-     *
-     * This is not a second copy of the pool's readiness. It is provenance, which
-     * nothing else knows, and only the reaper reads it: it may destroy an agent
-     * the pool itself created, never one that registered for a bound job whose
-     * dispatch has not yet arrived.
+     * Agents this instance pre-spawned to wait for work rather than for a queued
+     * job. This is provenance, not readiness: the agent registry cannot derive it,
+     * and the spawning entry that carries it is deleted at registration. Only the
+     * reaper reads it, so it destroys agents the pool created, never one that
+     * registered for a bound job whose dispatch has not arrived.
      */
     private readonly warmAgents;
     /**
-     * Registered agents this instance started for a specific queued job, keyed
-     * by agent id. The spawning entry that carries the binding is deleted at
-     * registration, so this is where {@link agentView} reads it: the agent always
-     * runs its own job, and an agent started inside a job's image runs nothing
-     * else.
+     * Registered agents this instance started for a queued job, keyed by agent
+     * id. The spawning entry is deleted at registration, so {@link agentView}
+     * reads the binding here: the agent always runs its own job, and one started
+     * inside a job's image runs nothing else.
      */
     private readonly boundAgents;
     /** Jobs a `requestScale` call is provisioning right now, before its spawning entry exists. */
     private readonly jobsBeingProvisioned;
     /**
-     * Warm agents whose destroy is issued but has not settled yet.
-     *
-     * An agent leaves `warmAgents` only once its destroy resolves, so until then
-     * `listIdle` keeps returning it and the next reap pass — 30 seconds later,
-     * or a reload that lowers the target — selects the very same agent again. A
-     * backend whose teardown outlives a tick would be handed a second destroy for
-     * an agent it is already destroying, and every extra pass would count another
-     * `kici_orch_scaler_warm_pool_reaped_total`. One entry per agent, cleared
-     * when the destroy settles either way.
+     * Warm agents whose destroy is issued but not settled. Until it resolves the
+     * agent stays in `warmAgents` and `listIdle`, so the next reap pass (30 s
+     * later, or a reload lowering the target) would hand the backend a second
+     * destroy and count another `kici_orch_scaler_warm_pool_reaped_total`.
+     * Cleared when the destroy settles either way.
      */
     private readonly warmDestroying;
     /** Agents this instance adopted from another instance's spawn record. */
     private readonly adoptedAgents;
-    /**
-     * Active log forwarders for scaler-managed agents (container/bare-metal).
-     * Keyed by agentId. Each forwarder consumes a LogCapture stream.
-     */
+    /** Log forwarders for scaler-managed agents (container/bare-metal), keyed by agentId. */
     private readonly logForwarders;
-    /**
-     * Correlation map: agentId -> { runId, jobId }.
-     * Populated by correlateAgentToJob() after job dispatch to a scaler-managed agent.
-     */
+    /** agentId → { runId, jobId }, set by correlateAgentToJob() after dispatch. */
     private readonly agentJobCorrelation;
-    /**
-     * Buffer for scaler events emitted before job correlation is established.
-     * Keyed by agentId. Flushed when correlateAgentToJob() is called.
-     */
+    /** Events emitted before job correlation, by agentId; flushed by correlateAgentToJob(). */
     private readonly eventBuffer;
-    /**
-     * External callback for relaying correlated scaler events (e.g. to execution tracker).
-     */
+    /** Relays correlated scaler events (e.g. to the execution tracker). */
     private readonly onScalerEvent?;
     /** Coordinator drain predicate; when true, requestScale() no-ops (no fresh
      *  agents spawned for the held Pending backlog). Defaults to never-draining. */
     private readonly isDraining;
     /**
-     * Optional callback fired (debounced) whenever scaler capacity frees — an
-     * ephemeral agent released its reservation on disconnect, a spawn failed, or a
-     * managed agent completed its job. Wired by the composition roots to the
-     * dispatcher's capacity-freed re-drive so jobs that got an `at-capacity`
-     * verdict get re-offered to the scaler the moment a slot opens, instead of
-     * sitting pending until they time out. Assigned after construction because it
-     * references the dispatcher, which is built after the manager.
+     * Fired (debounced) when scaler capacity frees: a reservation released on
+     * disconnect, a failed spawn, or a managed agent finishing its job. Wired to
+     * the dispatcher's capacity-freed re-drive, so `at-capacity` jobs are
+     * re-offered the moment a slot opens instead of pending until timeout.
+     * Assigned after construction: the dispatcher is built after the manager.
      */
     onCapacityFreed?: () => void;
     /** Trailing-debounce timer coalescing a burst of releases into one re-drive. */
@@ -493,11 +446,10 @@ export declare class ScalerManager {
      */
     private readonly warmPoolCallbacks;
     /**
-     * Optional DB-backed state store. When wired (production path), every
-     * mutation to `spawningAgents` / `agentJobCorrelation` / `reservations`
-     * is write-through-cached to Postgres so a coord crash mid-spawn no
-     * longer orphans agents, strands reservations, or loses correlation.
-     * Unit tests can omit the store and operate from in-memory Maps only.
+     * DB-backed state store. When wired (production), every mutation to
+     * `spawningAgents` / `agentJobCorrelation` / `reservations` writes through
+     * to Postgres, so a coordinator crash mid-spawn does not orphan agents,
+     * strand reservations or lose correlation. Unit tests omit it.
      */
     private readonly stateStore?;
     /** Id of the orchestrator instance this manager runs on. */
@@ -518,46 +470,35 @@ export declare class ScalerManager {
     private readonly resolveSpawnTimeoutMs?;
     constructor(deps: ScalerManagerDeps);
     /**
-     * Pre-spawn one warm agent for a pool's label set.
-     *
-     * The pool's counterpart of `requestScale`, with the job term of every
-     * resolution absent: no bound job, no run, and resources resolved
-     * from the label set (then the scaler defaults) alone. It takes the same
-     * reservations through the same {@link reserveForSpawn} helper — a warm
-     * agent occupies the same cpu and memory as a job-bound one, and on an event
-     * backend it claims a cluster slot too, so a pool can no longer carry a
-     * scaler past `maxAgents` fleet-wide.
+     * Pre-spawn one warm agent for a pool's label set: `requestScale` with no
+     * job term (no bound job, no run, resources from the label set then the
+     * scaler defaults). It reserves through the same {@link reserveForSpawn}: a
+     * warm agent occupies the same cpu and memory, and on an event backend claims
+     * a cluster slot, so a pool cannot carry a scaler past `maxAgents` fleet-wide.
      *
-     * A refused reservation is reported back to the pool as a failed spawn, so
-     * the in-flight slot it holds is released and the deficit is retried on the
-     * next tick rather than the pool stalling below target.
+     * A refused reservation reports a failed spawn to the pool, releasing its
+     * in-flight slot so the deficit retries next tick instead of stalling.
      */
     private spawnWarmAgent;
     /**
      * Whether a warm pool for this label set can count its own agents.
      *
-     * The pool measures readiness with `AgentRegistry.findAvailable(labels)`, and
-     * that query applies the agent's `mandatoryLabels` gate: an agent is dropped
-     * unless every label in its gate also appears in the query. A scaler-spawned
-     * agent's gate is `mandatoryGate()`, which unions the configured gate with
-     * the pool's platform taints. `warmPoolQueryLabels` puts the structured
-     * taints into the query, so that part of the gate is satisfied by
-     * construction.
+     * Readiness is `AgentRegistry.findAvailable(labels)`, which drops an agent
+     * unless its whole `mandatoryLabels` gate appears in the query. The gate is
+     * `mandatoryGate()` (configured gate ∪ platform taints), and
+     * `warmPoolQueryLabels` puts the taints into the query by construction.
      *
-     * That leaves one residual case: a configured `mandatoryLabels` entry absent
-     * from the label set, which `scaler/config.ts` validation already rejects.
-     * The check stays as the fail-safe — without it a pool in that state would
-     * spawn to `maxAgents` with `ready` stuck at 0, starving the on-demand spawns
-     * that share the cap. A refused pool is inert, exactly as it is before it
-     * fills at all — never partially filled.
+     * The residual case is a configured `mandatoryLabels` entry absent from the
+     * label set, which `scaler/config.ts` validation already rejects. This check
+     * is the fail-safe: such a pool would spawn to `maxAgents` with `ready` stuck
+     * at 0, starving the on-demand spawns sharing the cap. A refused pool is
+     * inert, never partially filled.
      *
-     * The gate is compared against `queryLabels`: comparing it against
-     * `declaredLabels` alone would refuse every structurally-tainted pool.
+     * The gate is compared against `queryLabels`: against `declaredLabels` alone
+     * it would refuse every structurally-tainted pool.
      */
     private warmPoolLabelSetFillable;
-    /**
-     * Whether this scaler pre-spawned (warm-filled) the agent.
-     */
+    /** Whether this scaler pre-spawned (warm-filled) the agent. */
     isPrespawnedAgent(agentId: string): boolean;
     /** Every local Firecracker backend, under its scaler name. */
     private firecrackerBackends;
@@ -588,99 +529,69 @@ export declare class ScalerManager {
     /**
      * Whether a pre-spawned (warm) agent's shape fits the shape a job declares.
      *
-     * A warm agent is generic by construction: it was started before the job
-     * existed, at the pool's declared shape. The shape is applied when the agent
-     * starts and cannot be changed afterwards — nothing in the agent reads a
-     * job's `resources`. So a job that needs another shape must get its own
-     * agent instead of silently running with the pool's.
-     *
-     * Returns true for any agent this scaler did not pre-spawn: a job-bound agent
-     * was started at its job's shape.
-     *
-     * Only the fields the job actually declares are compared. `resolveEffective`
-     * layers a job's declaration over the label set and the scaler defaults field
-     * by field, and the warm agent's own reservation is what those two layers
-     * resolve to — so a field the job leaves out already matches whatever the
-     * agent was started at, and comparing it would refuse a job that fits.
-     *
-     * A field the job DOES declare must match exactly, in both directions. A
-     * bigger ready agent is not a superset: limits are what the kernel enforces
-     * on the running agent, so a job asking to be capped at 2 cpus, served by an
-     * agent started at 4, runs uncapped. That is the same wrong execution
-     * environment as the under-provisioned case, in the other direction, so `>=`
-     * is not a safe relaxation.
-     *
-     * Both sides of the shape are compared, not just `requests`. The two answer
-     * different questions — `requests` is what the agent bills against the caps,
-     * `limits` is what the kernel enforces — and a declaration may legally set
-     * them apart, so a job matched on `requests` alone can still land on an agent
-     * capped somewhere else entirely.
+     * A warm agent starts before the job exists, at the pool's declared shape,
+     * and nothing in the agent reads a job's `resources` afterwards. So a job
+     * needing another shape gets its own agent instead of silently running with
+     * the pool's. True for any agent this scaler did not pre-spawn: a job-bound
+     * agent started at its job's shape.
+     *
+     * Only fields the job declares are compared: `resolveEffective` layers the
+     * job over the label set and scaler defaults field by field, so an omitted
+     * field already matches the warm agent's reservation.
+     *
+     * A declared field must match exactly. A bigger agent is not a superset:
+     * limits are kernel-enforced, so a job capped at 2 cpus on an agent started
+     * at 4 runs uncapped, so `>=` is not a safe relaxation.
+     *
+     * Both `requests` (billed against the caps) and `limits` (kernel-enforced)
+     * are compared: a declaration may set them apart, so matching `requests`
+     * alone can land a job on an agent capped elsewhere.
      */
     private prespawnedShapeFits;
     /**
      * Whether one side (`requests` or `limits`) of a job's declared shape leaves
-     * the agent's resolved side unchanged.
-     *
-     * True when the job declares nothing on this side, and true when `resolved`
-     * is absent — both mean "this cannot be told", and the predicate's rule is to
-     * fail open rather than strand a job.
+     * the agent's resolved side unchanged. Fails open (true) when the job declares
+     * nothing on this side or `resolved` is absent, rather than strand a job.
      */
     private shapeSideMatches;
     /**
      * Whether a warm pool for this label set has a declared agent shape.
      *
-     * A warm agent starts before any job exists, so its cpu and memory come from
-     * the label set (or the scaler defaults) and from nowhere else. Both are
-     * applied when the agent starts and cannot be changed afterwards, so an
-     * undeclared shape means the pool reserves a guess and no job can be tested
-     * for fit against it. Refusing is the fail-safe reading, and it is what makes
-     * a pool predictable — on a cloud backend it is what lets an operator reason
-     * about instance size and cost at all.
-     *
-     * Limits alone count as a declaration: `resolveEffective` mirrors limits into
-     * requests, so a label set naming only `limits` still resolves to a concrete
-     * shape.
-     *
-     * A refused pool is inert, exactly as it was before it filled at all — never
-     * partially filled.
+     * A warm agent's cpu and memory come only from the label set (or the scaler
+     * defaults) and are fixed at start, so an undeclared shape reserves a guess
+     * no job can be tested against. Refusing is the fail-safe, and on a cloud
+     * backend it is what lets an operator reason about instance size and cost.
+     * Limits alone count: `resolveEffective` mirrors limits into requests. A
+     * refused pool is inert, never partially filled.
      *
-     * A declaration this cannot resolve is refused the same way, and must never
-     * throw: the config schema types `resources.*.memory` as a plain string, so
-     * an unparseable value such as `4Gi` reaches `resolveEffective` and
-     * `parseMemoryString` rejects it. This runs inside the constructor and inside
-     * the commit block of {@link reload}, where an exception would abort
-     * orchestrator startup or leave a half-applied config behind.
+     * An unresolvable declaration is refused the same way and must never throw:
+     * the schema types `resources.*.memory` as a plain string, so a value such as
+     * `4Gi` reaches `parseMemoryString` and is rejected. This runs in the
+     * constructor and in {@link reload}'s commit block, where an exception would
+     * abort startup or leave a half-applied config.
      */
     private warmPoolShapeDeclared;
     /**
      * Agents this backend may still start before it reaches the scaler's
      * `maxAgents` or the orchestrator's `globalMaxAgents`, whichever binds first.
      *
-     * The warm pool clamps its deficit to this, so a pool that has reached a
-     * count cap asks for nothing at all rather than `size` spawns on every tick.
-     * Only the count caps are visible here: a pool with count headroom but no
-     * cpu/memory headroom still asks, and {@link reserveForSpawn} refuses each
-     * request under the reservation lock. Those refusals cost a log line and a
-     * `spawn_refusals` increment per tick, never a spawned agent.
-     *
-     * It is a best-effort read, not a reservation: the authority is
-     * {@link reserveForSpawn}, which every warm pre-spawn goes through and which
-     * re-checks both count caps under the reservation lock. The two backend
-     * families read differently here. A local backend (container, bare-metal,
-     * Firecracker) pins its compute to this host, so `getActiveCount()` is the
-     * whole population and the room it reports is exact. An **event** backend is
-     * capped cluster-wide — the reserve sequence claims a spawn row under
-     * `withScalerCapLock` — while `getActiveCount()` sees only the provisions
-     * this coordinator tracks, so the room reported here counts slots a peer may
-     * already hold. The cluster-wide cap is still enforced, by that claim rather
-     * than by this clamp.
+     * The warm pool clamps its deficit to this, so a pool at a count cap asks for
+     * nothing rather than `size` spawns every tick. Cpu/memory caps are not seen
+     * here: {@link reserveForSpawn} refuses those under the reservation lock, at
+     * the cost of a log line and a `spawn_refusals` increment per tick.
+     *
+     * A best-effort read, not a reservation: {@link reserveForSpawn} re-checks both
+     * count caps under the lock. For a local backend (container, bare-metal,
+     * Firecracker) `getActiveCount()` is the whole population, so the room is
+     * exact. An **event** backend is capped cluster-wide (a spawn row claimed
+     * under `withScalerCapLock`) while `getActiveCount()` sees only this
+     * coordinator's provisions, so the room here may count slots a peer holds;
+     * the claim, not this clamp, enforces the cluster-wide cap.
      */
     private warmCapacityRemaining;
     /**
-     * Publish the warm-pool gauges from the pool's current fill state.
-     *
-     * Called after each pool tick and after a config reload, so an operator sees
-     * a newly configured target immediately rather than at the next tick.
+     * Publish the warm-pool gauges. Called after each pool tick and after a
+     * reload, so a newly configured target shows immediately.
      */
     private publishWarmPoolGauges;
     /** Per-scaler mandatoryLabels (taint-style opt-in gate). */
@@ -690,26 +601,24 @@ export declare class ScalerManager {
     /**
      * Resolve the pool's platform for label + taint derivation. Precedence:
      *   1. A declared `platform` field always wins (even on a linux host).
-     *   2. Otherwise a bare-metal pool derives its platform from the host OS/arch.
-     *   3. Otherwise (container / firecracker, undeclared) returns null — those
-     *      pools run linux agents and are not auto-tainted; only an explicit
-     *      declared platform taints them.
-     * Returns null when a bare-metal host's OS/arch is not a supported enum value
-     * (the caller falls back to the raw host-label derivation for labels).
+     *   2. Otherwise a bare-metal pool derives it from the host OS/arch.
+     *   3. Otherwise (container / firecracker) null: linux agents, not
+     *      auto-tainted unless a platform is declared.
+     * Also null for a bare-metal host whose OS/arch is not a supported enum value
+     * (the caller falls back to raw host labels).
      */
     private resolveScalerPlatform;
     /**
      * The plain platform-taint tokens (`windows`, `macos`, `arm64`) for a scaler,
      * derived from the same resolved platform `mandatoryGate` gates on.
      *
-     * This is the single source for the taint: it feeds the matcher's view of the
-     * label sets, the taint gate, the labels the spawned agent registers with, and
-     * the warm-pool readiness query. Deriving it anywhere else — in a backend, say
-     * — is what let the gate and the agent's labels disagree, so a tainted pool
-     * spawned agents `AgentRegistry.findAvailable` could never return.
+     * The single source for the taint: the matcher's label sets, the taint gate,
+     * the agent's registered labels and the warm-pool readiness query. Deriving it
+     * elsewhere (in a backend, say) lets the gate and the agent's labels disagree,
+     * so a tainted pool spawns agents `AgentRegistry.findAvailable` never returns.
      *
-     * `backendType` is passed rather than looked up because the constructor
-     * configures warm pools from config entries whose backend may not be indexed.
+     * `backendType` is passed, not looked up: the constructor configures warm
+     * pools from config entries whose backend may not be indexed.
      */
     private platformTaintsFor;
     /**
@@ -717,41 +626,34 @@ export declare class ScalerManager {
      * plus the pool's platform taints.
      *
      * `AgentRegistry.findAvailable` drops an agent unless its whole
-     * `mandatoryLabels` gate appears in the query, and a tainted pool's gate
-     * carries the taints — so a query built from the declared labels alone counts
-     * none of the pool's own agents and the pool fills to `maxAgents` with `ready`
-     * stuck at 0. Both construction sites (the constructor and the reload path)
-     * call this so the two can never diverge.
-     *
-     * These labels are for the QUERY only. The pool is keyed by, and spawns with,
-     * the DECLARED label set: a backend matches the requested set against its own
-     * `labelSets` to resolve the image / binary / VM config and throws on a set it
-     * does not have, and every in-flight release path normalizes the spawn labels
-     * back to the map key.
+     * `mandatoryLabels` gate (taints included) appears in the query, so declared
+     * labels alone count none of the pool's agents and it fills to `maxAgents`
+     * with `ready` stuck at 0. The constructor and the reload path both call this
+     * so they never diverge.
+     *
+     * QUERY only. The pool is keyed by, and spawns with, the DECLARED set: a
+     * backend resolves its image / binary / VM config by matching its own
+     * `labelSets` and throws on any other set, and every in-flight release path
+     * normalizes the spawn labels back to the map key.
      */
     private warmPoolQueryLabels;
     /**
      * Taint gate for a scaler's label sets: the configured `mandatoryLabels` plus
      * the platform taints derived from the pool's resolved structured platform.
      *
-     * This is the gate every routing and stamping decision uses. `backend`
-     * carries only `type`, so a caller that holds one label set never has to
-     * reach for the whole backend.
+     * Every routing and stamping decision uses it. `backend` needs only `type`,
+     * so a caller holding one label set never reaches for the whole backend.
      */
     private mandatoryGate;
     /**
-     * Build enriched scaler entries with auto-labels injected into each label set.
-     * This ensures label matching accounts for auto-injected labels (kici:role:*,
-     * kici:os:*, kici:arch:*, kici:agent:*, kici:scaler:*) that agents receive
-     * at spawn time.
-     *
-     * The os/arch labels derive from the pool's resolved structured platform
-     * (declared field wins, else host-derive for bare-metal, else linux), and the
-     * mandatory labels combine the per-scaler config gate with the platform taint,
-     * so the label matcher applies the gate alongside subset matching.
+     * Scaler entries with the auto-labels agents receive at spawn (kici:role:*,
+     * kici:os:*, kici:arch:*, kici:agent:*, kici:scaler:*) injected into each
+     * label set, so label matching accounts for them.
      *
-     * Retiring scalers are skipped: they were removed from the config and must
-     * take no new work while their remaining agents finish.
+     * os/arch derive from the resolved structured platform, and the mandatory
+     * labels combine the config gate with the platform taint, so the matcher
+     * applies the gate alongside subset matching. Retiring scalers are skipped:
+     * they take no new work while their remaining agents finish.
      */
     private getEnrichedScalerEntries;
     /**
@@ -768,35 +670,30 @@ export declare class ScalerManager {
     private sweepRetiredBackends;
     /**
      * True while any spawn this manager started for `name` has neither registered
-     * nor failed — including one still queued behind the spawn semaphore, which
-     * has not reached `backend.spawn` at all. Such a spawn counts toward the
-     * scaler's drain even though the backend reports no active agent.
+     * nor failed, including one still queued behind the spawn semaphore. Such a
+     * spawn holds the drain open though the backend reports no active agent.
      */
     private hasSpawnInFlight;
     /** Drop every trace of a scaler: the backend and all its per-scaler metadata. */
     private forgetScaler;
     /**
-     * Main entry point: called by the Dispatcher when no agent is available.
-     *
-     * `resources` is the per-job request/limit declaration (or `undefined` to fall
-     * back to scaler defaults). Used by per-scaler / per-orchestrator / per-machine
-     * resource caps; the cap math is wired up by ScalerManager itself.
+     * Run one backend spawn under the resolved spawn deadline. On deadline it
+     * aborts the signal (so the backend's container-runtime/HTTP calls cancel and
+     * its own catch cleans up) AND rejects, so the caller's semaphore `run()`
+     * releases the slot even if the backend's unwind stalls somewhere
+     * non-abortable.
      */
+    private runSpawnWithTimeout;
     /**
-     * Run a single backend spawn under the resolved spawn deadline. Returns the
-     * ManagedAgent on success. On deadline: aborts the signal (so the backend's
-     * threaded container-runtime/HTTP calls cancel and its own catch cleans up)
-     * AND rejects, so the caller's semaphore `run()` finally releases the slot
-     * even if the backend's unwind stalls in a non-abortable spot. The backing
-     * spawn promise gets a no-op catch attached so a late abort-rejection doesn't
-     * surface as an unhandled rejection.
+     * Main entry point: called by the Dispatcher when no agent is available.
+     * `resources` is the per-job request/limit declaration (`undefined` falls
+     * back to scaler defaults), billed against the per-scaler, per-orchestrator
+     * and per-machine resource caps.
      */
-    private runSpawnWithTimeout;
     requestScale(labels: string[], jobId: string, runId: string, excludeLabels?: string[], resources?: ResourceRequest, orgId?: string, 
     /**
-     * The job's resolved container image + registry credentials, when it
-     * declared one. Threaded to the backend so it can spawn the job's own
-     * image instead of the pool's fixed agent image.
+     * The job's resolved container image + registry credentials, when declared,
+     * so the backend can spawn the job's own image instead of the pool's.
      */
     containerSpawn?: ResolvedContainerSpawn): Promise<ScaleResult>;
     /** Whether this coordinator already provisions, or holds an agent bound to, `jobId`. */
@@ -804,210 +701,160 @@ export declare class ScalerManager {
     /** `requestScale` past its drain and per-job checks: match, reserve, spawn. */
     private provisionForJob;
     /**
-     * Take every reservation one spawn needs, or take none at all.
-     *
-     * The single reserve sequence both spawn paths share — the job-bound
-     * `requestScale` and the warm pool's pre-spawn. The only difference between
-     * them is `boundJobId`, which is `undefined` for a pre-spawn; a warm agent
-     * costs the same host resources as a job-bound one, so it takes the same
-     * reservations.
+     * Take every reservation one spawn needs, or none. Shared by `requestScale`
+     * and the warm pre-spawn (`boundJobId` `undefined`): a warm agent costs the
+     * same host resources, so it takes the same reservations.
      *
      * Ordering, and why:
      * - Count caps and the in-memory resource reservation run under the
-     *   in-process reservation lock, so the check and the reserve are atomic
-     *   against a concurrent caller. A local backend counts its own host's
-     *   agents in process, which is what its cap means: the compute is pinned to
-     *   this machine. An event backend provisions cloud instances any
-     *   coordinator can start, so its cap is counted — and its slot claimed —
-     *   cluster-wide, inside one advisory-locked transaction. The in-process
-     *   lock stays the outer guard so the two never contend.
-     * - The cross-process machine-pool ledger is taken outside that lock,
-     *   because the ledger has its own cross-process mutex; holding both at once
-     *   buys nothing.
-     *
-     * Every refusal rolls back exactly what it already took, so a `false` return
-     * leaves no reservation behind. On success the caller owns the release,
-     * which is always `releaseAll(agentId)`.
+     *   in-process reservation lock, so check and reserve are atomic. A local
+     *   backend counts its own host's agents in process (its compute is pinned
+     *   here). An event backend's cloud instances can be started by any
+     *   coordinator, so its cap is counted, and its slot claimed, cluster-wide in
+     *   one advisory-locked transaction; the in-process lock stays the outer
+     *   guard so the two never contend.
+     * - The machine-pool ledger is taken outside that lock: it has its own
+     *   cross-process mutex, and holding both buys nothing.
+     *
+     * Every refusal rolls back what it took, so `false` leaves no reservation.
+     * On success the caller owns the release: `releaseAll(agentId)`.
      */
     private reserveForSpawn;
     /**
-     * How many reservations one scaler currently holds.
-     *
-     * Derived from `this.reservations` rather than kept as a counter beside it:
-     * the map IS the admitted set, so a derived count cannot drift out of step
-     * with it — including on the boot/leader-switch rehydrate path, which
-     * repopulates the map directly.
-     */
-    /**
-     * Record a refusal taken on one of the two agent-count caps.
+     * Record a refusal on one of the two agent-count caps.
      *
-     * The refusal itself is returned to the dispatcher as `at-capacity`, which
-     * leaves the job queued and logs nothing — correct while agents are genuinely
-     * busy, and indistinguishable from a scaler that has stopped spawning
-     * altogether. So the counter the metric's own help text promises
-     * (`maxAgents`, `globalMaxAgents`) is incremented here, beside the resource
-     * caps that already increment it.
+     * The dispatcher gets `at-capacity`, which queues the job and logs nothing,
+     * indistinguishable from a scaler that stopped spawning. So the counter the
+     * metric's help text promises (`maxAgents`, `globalMaxAgents`) is
+     * incremented here, beside the resource caps.
      *
-     * The warning is narrower than the counter on purpose. Ordinary saturation
-     * refuses with live agents holding the cap, and warning on that would emit a
-     * line per queued job for as long as the cluster is busy. A refusal where the
-     * reservation ledger outruns every backend's active count is the other shape:
-     * capacity billed to agents that are not running, which does not resolve on
-     * its own.
+     * The warning is narrower on purpose: ordinary saturation would warn per
+     * queued job while busy. It fires only when the reservation ledger outruns
+     * every backend's active count: capacity billed to agents not running, which
+     * does not resolve on its own.
      */
     private reportCountCapRefusal;
-    private reservedCountForScaler;
     /**
-     * Run a critical section under the reservation lock. Serializes concurrent
-     * `requestScale()` calls so the check+reserve sequence is atomic.
+     * Reservations one scaler holds, derived from `this.reservations` rather than
+     * a separate counter: the map IS the admitted set, so the count cannot drift,
+     * even on the boot/leader-switch rehydrate path that repopulates the map.
      */
+    private reservedCountForScaler;
+    /** Serializes concurrent `requestScale()` calls so check+reserve is atomic. */
     private runWithReservationLock;
     /**
-     * Lazily resolve the per-backend spawn throttle, sized by the scaler's
-     * `maxConcurrentSpawns` (falling back to the cluster default). One semaphore
-     * per backend name, since each backend has its own container socket.
+     * Lazily resolve the per-backend spawn throttle, sized by `maxConcurrentSpawns`
+     * (else the cluster default). One per backend: each has its own container socket.
      */
     private spawnSemaphoreFor;
     /**
      * Resolve the effective `{ requests, limits }` for a job at this scaler.
      *
-     * Layered defaults (highest priority first):
+     * Layered per field, highest priority first:
      * 1. Job's own `resources` (after request<->limit mirroring).
      * 2. Label-set's `resources`.
      * 3. Scaler's `defaults.resources` (already merged from global defaults at construction).
-     * 4. Zero (`{ cpus: 0, memBytes: 0 }`).
-     *
-     * Returns both sides fully resolved as numeric `{ cpus, memBytes }` pairs.
+     * 4. Zero.
      */
     private resolveEffective;
     /**
-     * Attempt to reserve `requests` against the per-scaler and per-orchestrator
-     * caps. Returns false (no state change) if any cap would be exceeded.
-     *
-     * Caller must hold the reservation lock.
+     * Reserve `requests` against the per-scaler and per-orchestrator caps, or
+     * return false with no state change. Caller must hold the reservation lock.
      */
     private tryReserveAll;
     /**
-     * Push the current `perScalerUsage` and `globalUsage` snapshot into the
-     * Prometheus observable gauges. Called on every successful reservation /
-     * release so the gauge callback always reflects the latest state without
-     * doing any work itself (gauge callbacks are synchronous and MUST NOT
-     * touch this map directly — they just read whatever was last published).
+     * Push the `perScalerUsage` / `globalUsage` snapshot into the observable
+     * gauges on every reservation / release. Gauge callbacks are synchronous and
+     * MUST NOT touch this map; they read whatever was last published.
      *
-     * Note: pool-level usage is intentionally not emitted here. The on-disk
-     * machine-pool ledger requires async I/O + a file lock to read accurately,
-     * and OTel observable-gauge callbacks must be synchronous. Operators
-     * dashboarding pool utilization can derive a lower bound from the sum of
-     * `kici_orch_scaler_cpus_used` rows whose scaler belongs to the pool.
+     * Pool-level usage is deliberately not emitted: reading the on-disk ledger
+     * needs async I/O + a file lock, and OTel gauge callbacks are synchronous. A
+     * lower bound is the sum of `kici_orch_scaler_cpus_used` over the pool's
+     * scalers.
      */
     private publishUsageMetrics;
     /**
-     * Release the reservation tracked for an agent. Idempotent. Also releases
-     * the cross-process pool reservation (best-effort) when the scaler
-     * references a pool.
+     * Release an agent's reservation, and (best-effort) its cross-process pool
+     * reservation. Idempotent.
      */
     private releaseAll;
     /**
      * Signal that scaler capacity freed. Trailing-debounced by
-     * {@link CAPACITY_FREED_DEBOUNCE_MS} so a burst of simultaneous releases (and
-     * the onJobComplete → onAgentDisconnect pair for a single-use agent) coalesces
-     * into one re-drive pass that runs after the last release settles. No-op when
-     * no callback is wired. The timer is `unref`'d so it never keeps the process
-     * alive, and cleared on shutdown.
+     * {@link CAPACITY_FREED_DEBOUNCE_MS} so a burst of releases (and a single-use
+     * agent's onJobComplete → onAgentDisconnect pair) coalesces into one re-drive
+     * after the last release. The timer is `unref`'d and cleared on shutdown.
      */
     private notifyCapacityFreed;
     /**
-     * Subtract the given `requests` from the per-scaler and global in-memory
-     * counters. Used both by `releaseAll()` and by the rollback path when a
-     * machine-pool reservation refuses after the in-memory reservation
-     * already succeeded.
+     * Subtract `requests` from the per-scaler and global in-memory counters; used
+     * by `releaseAll()` and by rollbacks after the in-memory reservation succeeded.
      */
     private releaseInMemory;
     /**
-     * Resolve the scaler-level default resources, merging the global
-     * `defaults.resources` underneath any scaler-specific override.
-     *
-     * Currently scaler entries themselves do not carry their own `defaults` (the
-     * label-set level does). The merged result is stored per-scaler so that
-     * future scaler-level defaults can be added without touching the resolver.
+     * Resolve a scaler's default resources. Scaler entries carry no `defaults` of
+     * their own (label sets do), so this is the global `defaults.resources`;
+     * storing it per scaler leaves room for scaler-level defaults.
      */
     private resolveScalerDefaults;
     /**
-     * Called from agent-handler.ts when an agent registers via WS.
-     * Correlates the registered agent to a spawned tracking entry.
+     * Called from agent-handler.ts when an agent registers via WS; correlates it to
+     * its spawning entry.
      *
      * Returns:
-     * - `boundJobId` (optional): the queued jobId this agent was spawned for.
-     *   Used by the caller to eagerly dispatch the bound job before the
-     *   agent's idle timer fires, skipping the generic queue drain race.
-     * - `mandatoryLabels` (always populated for scaler-managed agents): the
-     *   spawning scaler's effective `mandatoryLabels` gate — its configured
-     *   labels plus the platform taint derived from the pool's declared OS/arch.
-     *   Threaded into the
-     *   AgentRegistry so the queue-drain path (`onAgentAvailable` →
-     *   `dequeueForLabels`) and the eager-dispatch path
-     *   (`dispatchBoundJob` → `dequeueById`) both reject queued jobs whose
-     *   `runsOn` does not include every gate label.
-     *
-     * Returns `null` for a static agent — no spawning entry exists, and no other
-     * instance's spawn record claims the agent either. A warm-pool spawn is not
-     * that case: its spawning entry (and durable row) survives until it
+     * - `boundJobId` (optional): the queued job this agent was spawned for, which
+     *   the caller dispatches eagerly before the idle timer fires, skipping the
+     *   generic queue drain race.
+     * - `mandatoryLabels` (always set for scaler-managed agents): the scaler's
+     *   effective gate (configured labels plus the platform taint). Threaded into
+     *   the AgentRegistry so both the queue-drain path (`onAgentAvailable` →
+     *   `dequeueForLabels`) and the eager-dispatch path (`dispatchBoundJob` →
+     *   `dequeueById`) reject jobs whose `runsOn` lacks a gate label.
+     *
+     * Returns `null` for a static agent: no spawning entry and no peer spawn
+     * record. A warm-pool spawn keeps its entry (and durable row) until it
      * registers, so it resolves with `mandatoryLabels` and no `boundJobId`, which
-     * is exactly what marks the agent warm on `register.ack`.
+     * marks the agent warm on `register.ack`.
      *
-     * A local hit (this instance spawned the agent) is answered from memory. A
-     * miss falls back to the shared spawn record: on an HA cluster behind one
-     * endpoint the agent routinely reaches an instance that did not spawn it,
-     * and adopting is the normal path, not an exception. Adoption is a
-     * conditional UPDATE, so exactly one instance can win.
+     * A local hit is answered from memory; a miss falls back to the shared spawn
+     * record, since on an HA cluster behind one endpoint the agent routinely
+     * reaches an instance that did not spawn it. Adoption is a conditional
+     * UPDATE, so exactly one instance wins.
      */
     onAgentRegistered(agentId: string, labels: string[]): Promise<{
         boundJobId?: string;
         mandatoryLabels: string[];
     } | null>;
     /**
-     * Reclaim the host-local compute of a scaler-spawned agent this coordinator
-     * refused for want of a spawn record.
+     * Reclaim the host-local compute of a scaler-spawned agent refused for want of
+     * a spawn record.
      *
-     * Refusing closes the WS before registration completes, so `onAgentDisconnected`
-     * never runs for that agent, and `managedAgentIndex` never held it in the first
-     * place — the two writes that populate it (`completeLocalRegistration` and the
-     * adoption branch) both come after this point. So even the disconnect hook is a
-     * no-op here: it reads that index, finds nothing, and takes the static-agent
-     * exit. The agent keeps its VM or host process, reconnects, is refused again,
-     * and loops until an operator stops it by hand.
+     * Refusing closes the WS before registration completes, and
+     * `managedAgentIndex` is only populated after this point, so the disconnect
+     * hook takes the static-agent exit. Without this the agent keeps its VM or
+     * host process and loops reconnect-refuse until an operator stops it.
      *
      * **This force-destroys a live instance, so read what makes it safe.**
      *
-     * - **Local backends only.** An event agent's compute is a customer cloud
-     *   instance, reachable from any coordinator, and its missing adoption is
-     *   ambiguous: `adoptSpawningAgent` resolves `null` both when no row exists AND
-     *   when a peer coordinator already holds the row, so an event agent that is
-     *   alive and legitimately owned elsewhere reaches this exact branch. Tearing
-     *   it down there would destroy a peer's healthy provision. A local backend's
-     *   compute cannot be reached that way: it lives on the host that spawned it.
-     * - **Host-local evidence decides, not this verdict.** The verdict alone is NOT
-     *   evidence the agent is this host's: `adoptSpawningAgent` adopts `event` rows
-     *   only, so a `container` / `bare-metal` / `firecracker` agent that reconnects
-     *   to a peer behind a shared endpoint is refused here even though its spawn
-     *   row is intact and its compute is alive on the peer's host. What keeps that
-     *   harmless is that each backend reclaims only what its own tracking or its
-     *   own on-host artifacts name — never a shared database row, which on an HA
-     *   pair names an identically-configured scaler on both hosts. A wrongly-routed
-     *   agent id finds nothing here and nothing is touched.
+     * - **Local backends only.** `adoptSpawningAgent` resolves `null` both when no
+     *   row exists AND when a peer already holds it, so a live event agent owned
+     *   elsewhere reaches this branch; tearing down its cloud instance would
+     *   destroy a peer's healthy provision. Local compute lives on the host that
+     *   spawned it.
+     * - **Host-local evidence decides, not this verdict.** `adoptSpawningAgent`
+     *   adopts `event` rows only, so a `container` / `bare-metal` / `firecracker`
+     *   agent reconnecting to a peer behind a shared endpoint is refused here with
+     *   its row intact and compute alive on the peer's host. Each backend reclaims
+     *   only what its own tracking or on-host artifacts name, never a shared
+     *   database row (which on an HA pair names an identically-configured scaler
+     *   on both hosts), so a wrongly-routed id touches nothing.
      * - **Never on a transient failure.** The caller must have positive evidence
-     *   the agent is unowned. A store read that merely *failed* is not evidence —
-     *   the record may exist and be perfectly healthy.
+     *   the agent is unowned; a store read that merely *failed* is not evidence.
      *
-     * Fire-and-forget, matching `onAgentDisconnected`'s own teardown: the caller
-     * refuses the registration immediately rather than holding the agent's socket
-     * open for a VM shutdown.
+     * Fire-and-forget, like `onAgentDisconnected`'s teardown: the registration is
+     * refused immediately rather than holding the socket open for a VM shutdown.
      */
     private reclaimUnownedScalerAgent;
-    /**
-     * Finish registration for an agent this instance spawned itself, from the
-     * in-memory spawning entry.
-     */
+    /** Finish registration for an agent this instance spawned, from its spawning entry. */
     private completeLocalRegistration;
     /**
      * Called from agent-handler.ts when an agent disconnects. `reason` is what an
@@ -1020,105 +867,86 @@ export declare class ScalerManager {
      * Tear down a stranded provision the `EventProvisionReaper` found.
      *
      * Public because the reaper is leader-gated and lives outside the manager,
-     * while the emit and the row delete must stay in one place. The reason comes
-     * from the reaper's verdict — a provision whose agent never registered is a
-     * `spawn-timeout`, one whose agent went away is a `heartbeat-timeout` — so
-     * unlike the disconnect path this does not default to `shutdown`.
+     * while the emit and the row delete stay in one place. The reason is the
+     * reaper's verdict (never registered → `spawn-timeout`, went away →
+     * `heartbeat-timeout`), never a `shutdown` default.
      *
      * `kici_orch_scaler_external_provision_timeout_total` counts the spawn-timeout
-     * arm. Nothing else increments it in production: `runSpawnWithTimeout` bounds
-     * only the `spawn()` call, and an event backend's `spawn()` returns the moment
-     * the scale-up event is emitted.
+     * arm, and nothing else increments it in production: an event backend's
+     * `spawn()` returns once the scale-up is emitted, inside
+     * `runSpawnWithTimeout`'s bound.
      *
      * The spawn-timeout arm is also where an external provisioning failure enters
-     * the ordinary failure machinery. The local backends report a dead spawn
-     * through the `scaler.failed` event their `spawn()` emits; an event scaler's
-     * `spawn()` succeeds by definition (it only emits a scale-up), so the failure
-     * is not observable until the provision it asked for never registers — which
-     * is exactly this verdict. Synthesizing the event here gives the fleet
-     * counter, the operator's `diagnose scaler` view, and `last_provisioning_error`
-     * the same input every other backend already supplies, so a job whose external
-     * provisioning failed settles with the provisioning cause instead of a
-     * label-mismatch complaint that sends its operator to fix a correct `runsOn`.
+     * the failure machinery. Local backends emit `scaler.failed` from `spawn()`;
+     * an event scaler's `spawn()` always succeeds, so the failure shows only when
+     * the provision never registers. Synthesizing the event here feeds the fleet
+     * counter, `diagnose scaler` and `last_provisioning_error`, so the job
+     * settles with the provisioning cause instead of a label-mismatch complaint
+     * that sends its operator to fix a correct `runsOn`.
      */
     emitOrphanScaleDown(candidate: ReapCandidate, reason: ScaleDownReason): Promise<void>;
     /**
      * Refuse a spawn request while the scaler is inside its backoff window.
      *
-     * Returns the refusal to hand back, or null to proceed. The message names how
-     * many consecutive failures produced the deferral and when it lifts. It
-     * reaches the operator through this method's own log line: the dispatcher
-     * branches on `action` alone and discards `reason`, so a job deferred here
-     * carries no record of the deferral on its queue row. The job whose provision
-     * actually failed is the one that gets `last_provisioning_error`, written by
-     * the `scaler.failed` this backoff's own trigger emits.
+     * Returns the refusal, or null to proceed. The operator sees it only through
+     * this method's log line: the dispatcher branches on `action` and discards
+     * `reason`, so a deferred job's queue row records nothing. The job whose
+     * provision failed gets `last_provisioning_error` from the triggering
+     * `scaler.failed`.
      *
-     * The knobs are read here per request rather than per process, so an operator
-     * lowering the failure limit mid-outage sees the repeated-failure wording on
-     * the next refusal. The window itself was armed by `recordProvisionFailure`
-     * from the base and ceiling live at that moment, so a retuned window applies
-     * from the next recorded failure.
+     * The knobs are read per request, so a lowered failure limit changes the
+     * wording on the next refusal; the window itself was armed from the base and
+     * ceiling live at the last `recordProvisionFailure`, so a retuned window
+     * applies from the next failure.
      */
     private provisionBackoffRefusal;
     /**
-     * Record a consecutive provisioning failure for a scaler and arm its next
-     * deferral.
-     *
-     * The delay doubles per consecutive failure and is capped, so a provider
-     * outage settles into a steady retry cadence rather than either hammering the
-     * provider or growing without bound. `2 ** (n - 1)` is bounded by the cap
-     * before it is used, so a long outage cannot overflow the shift.
+     * Record a consecutive provisioning failure and arm the next deferral. The
+     * delay doubles per failure up to the cap, so an outage settles into a steady
+     * retry cadence. `2 ** (n - 1)` is capped before use, so it cannot overflow.
      */
     private recordProvisionFailure;
     /**
-     * Claim a dead provision as counted, or report that someone already did.
-     *
-     * The same provision is seen twice on the leader — once by its own
-     * stale-spawn prune, once by the leader-gated reaper — and every consequence
-     * of a failure is counted per provision, not per observer. The claim is
-     * synchronous and happens before any await, so two observers arriving in the
-     * same tick cannot both pass it.
+     * Claim a dead provision as counted, or report that someone already did. The
+     * leader sees one provision twice (its stale-spawn prune and the reaper), and
+     * a failure counts per provision, not per observer. Synchronous, before any
+     * await, so two observers in the same tick cannot both pass.
      */
     private claimFailedProvision;
     /**
      * Report one dead external provision, wherever this coordinator noticed it.
      *
-     * Everything a failed provision owes an operator happens here: the fleet
-     * spawn-failure counter, the structured warn, the `ScalerFailureTracker`
-     * record `kici-admin diagnose scaler` reads, the `last_provisioning_error`
-     * that tells the waiting job why it never ran, and the backoff.
+     * Everything a failed provision owes an operator: the fleet spawn-failure
+     * counter, the structured warn, the `ScalerFailureTracker` record
+     * `kici-admin diagnose scaler` reads, the job's `last_provisioning_error`,
+     * and the backoff.
      *
-     * It is deliberately reachable from BOTH observers rather than from the
-     * reaper alone. `ScalerFailureTracker` and `provisionFailures` are
-     * per-process, and the reaper is leader-gated — so a reaper-only report left
-     * every non-leader with an empty `diagnose scaler` for a scaler failing
-     * fleet-wide, and dispatching at the un-deferred cadence while only the
-     * leader backed off. The local prune is the observation every coordinator has
-     * of its own spawns.
+     * Reachable from BOTH observers, not the reaper alone: the tracker and
+     * `provisionFailures` are per-process and the reaper is leader-gated, so a
+     * reaper-only report leaves every non-leader with an empty `diagnose scaler`
+     * and an un-deferred cadence. The local prune is every coordinator's view of
+     * its own spawns.
      *
-     * Synchronous up to the backoff arm, so a caller that must clean up after the
-     * event (the prune drops the agent's event buffer) sees the effect
-     * immediately.
+     * Synchronous up to the backoff arm, so a caller cleaning up after the event
+     * (the prune drops the agent's event buffer) sees the effect at once.
      */
     private reportProvisionFailure;
     /**
      * Defer a scaler whose host refused to start an agent, then free the spawn's
      * reservation.
      *
-     * Arming comes first: the release notifies freed capacity, and the re-drive
-     * that follows 250 ms later must meet the deferral rather than spawn straight
-     * into the same refusal. The release still notifies, because a job waiting on
-     * another scaler, or on the global cap, is legitimately unblocked by it.
-     * Two failures come here: a `spawn()` that rejected with a
+     * Arm first: the release notifies freed capacity, and the re-drive 250 ms
+     * later must meet the deferral rather than spawn into the same refusal. The
+     * release still notifies, since it legitimately unblocks a job waiting on
+     * another scaler or the global cap. Callers: a `spawn()` rejected with a
      * `DeterministicSpawnError`, and a settled spawn whose compute stopped before
-     * its agent registered (`dropFailedSettledSpawn`). Every other spawn
-     * rejection is released at once and retried.
+     * its agent registered (`dropFailedSettledSpawn`). Any other rejection is
+     * released at once and retried.
      */
     private deferRefusedLaunch;
     /**
-     * Whether a bound job has ended. A read error, a missing row, an unknown
-     * run, or no reader wired all read as "not ended", so the caller keeps
-     * reporting the provision as it would without the check.
+     * Whether a bound job has ended. A read error, missing row, unknown run or
+     * missing reader all read as "not ended", so the caller reports as usual.
      */
     private boundJobEnded;
     /**
@@ -1127,62 +955,51 @@ export declare class ScalerManager {
      *
      * The job's row is the shared truth: a cancel reaches whichever coordinator
      * the Platform picks, while the spawning entry lives on the one that asked.
-     * A withdrawal is not a provisioning failure, so nothing is reported and no
-     * backoff is armed. Returns how many provisions were withdrawn.
+     * A withdrawal is not a failure: nothing is reported, no backoff armed.
+     * Returns the withdrawn count.
      */
     withdrawEndedBoundProvisions(): Promise<number>;
     /**
      * Forget one pending provision and tear it down as `job-complete` — unless a
      * peer adopted its agent, in which case the adopter owns the teardown.
      *
-     * The teardown goes through `emitScaleDownForSpec`, which drops the spawn
-     * row only once the scale-down is out: a failed emit keeps the row for the
-     * reaper, whose spawn-timeout verdict re-checks the job and sends
-     * `job-complete` too. `backend.destroy` is not used — a rehydrated entry is
-     * not tracked by the backend, so it would emit nothing.
+     * Via `emitScaleDownForSpec`, which drops the spawn row only once the
+     * scale-down is out; a failed emit leaves it for the reaper, whose
+     * spawn-timeout verdict re-checks the job and also sends `job-complete`. Not
+     * `backend.destroy`: the backend does not track a rehydrated entry, so it
+     * would emit nothing.
      */
     private withdrawProvision;
     /**
      * Report a pruned event spawn as a dead provision — unless a peer adopted it.
      *
-     * The prune is NOT proof of failure on an HA cluster. Nothing tells the
-     * spawning coordinator that its agent registered on a peer, so the entry
-     * survives adoption and lands in the prune the stale window later next to a
-     * perfectly live agent — the same asymmetry `deleteUnadoptedSpawningAgent`
-     * exists for. Reporting that as a dead provision writes a `scaler.failed` and
-     * a `last_provisioning_error` onto a job that is running, and backs a healthy
-     * scaler off, which is the misattribution this whole report exists to remove.
-     * The reaper already applies the same test: it returns `spawn-timeout` only
-     * for a candidate with no `adoptedBy`, so without this the two observers of
-     * one provision disagree.
-     *
-     * The question is "was this provision ever adopted?", and the spawn row alone
-     * cannot answer it: the row is deleted on teardown, so its absence is BOTH
-     * "never adopted" and "adopted, then torn down". `provisionAdopter` reads the
-     * live row first and the durable provision-outcome record second, which
-     * survives the delete — so an adopted provision the reaper has since
-     * condemned no longer reads as a dead one.
-     *
-     * The lookup is fire-and-forget so the prune stays off the request path, and
-     * it fails open. Both "the store errored" and "there is no verdict" leave the
-     * failure reported, deliberately: a provision with no positive evidence of
-     * adoption is what a single coordinator sees on a real provisioning outage,
-     * and suppressing there would disarm the per-coordinator backoff on every
-     * follower — an invisible missing report in place of a visible false one. The
-     * only rows with no verdict are those adopted before the outcome table
-     * existed, and they age out within one stale-prune window of the deploy.
+     * The prune is NOT proof of failure on an HA cluster: the spawning coordinator
+     * never learns its agent registered on a peer, so the entry reaches the prune
+     * next to a live agent (the asymmetry `deleteUnadoptedSpawningAgent` exists
+     * for). Reporting it would write `scaler.failed` and
+     * `last_provisioning_error` onto a running job and back off a healthy scaler.
+     * The reaper applies the same test (`spawn-timeout` only without
+     * `adoptedBy`), so the two observers agree.
+     *
+     * The spawn row alone cannot say "ever adopted?": it is deleted on teardown.
+     * `provisionAdopter` reads the live row, then the durable provision-outcome
+     * record that survives the delete, so an adopted provision the reaper has
+     * since condemned does not read as dead.
+     *
+     * The lookup is fire-and-forget (off the request path) and fails open: a
+     * store error or no verdict leaves the failure reported, because that is what
+     * a real outage looks like to one coordinator, and suppressing it would
+     * disarm every follower's backoff. The only rows with no verdict were adopted
+     * before the outcome table existed and age out within one stale-prune window
+     * of the deploy.
      */
     private reportPrunedProvisionFailure;
     /** The adoption half of {@link reportPrunedProvisionFailure}. */
     private reportPrunedUnlessAdopted;
     /**
-     * Clear a scaler's consecutive-failure state after a successful provision.
-     *
-     * Called from `onAgentRegistered`, which is the single entry point for BOTH a
-     * locally-spawned agent and one this coordinator adopted from a peer. An
-     * adopted agent is a successful provision — the instance that spawned it
-     * is not the one it reached — so counting only local registrations
-     * would leave a healthy scaler deferred on an HA cluster.
+     * Clear a scaler's consecutive-failure state after a successful provision,
+     * from both the local and the adopted registration paths (see
+     * `onAgentRegistered`).
      */
     private clearProvisionFailures;
     /**
@@ -1190,68 +1007,52 @@ export declare class ScalerManager {
      * drop the durable row.
      *
      * Used where the instance holding the agent has no local backend for its
-     * scaler — the ordinary shape on an HA cluster behind one shared endpoint,
-     * where the coordinator the agent reached may not configure the scaler that
-     * spawned it. The row's own targets are therefore primary, with local config
-     * as the fallback for a row that recorded none.
-     *
-     * A failed emit leaves the row in place: it is the only durable pointer at
-     * the customer's running instance, so the reaper needs it to retry from.
+     * scaler, the ordinary shape on an HA cluster behind one shared endpoint.
      *
-     * Returns whether the teardown was actually emitted, so a caller that counts
-     * teardowns counts deliveries rather than attempts.
+     * A failed emit leaves the row: it is the only durable pointer at the
+     * customer's running instance, and the reaper retries from it. Returns
+     * whether the teardown was emitted, so callers count deliveries, not attempts.
      */
     private emitScaleDownForSpec;
     /**
-     * Look up the scaler backend TYPE (a `ScalerBackendType` — `container`,
-     * `firecracker`, `bare-metal`, `event`, …) for a registered agent.
-     * Returns null if the agent is not scaler-managed (a static / stateful
-     * agent).
+     * The backend TYPE (`container`, `firecracker`, `bare-metal`, `event`, …) of
+     * a registered agent, or null for a static / stateful agent.
      *
-     * Used by AgentMetricsAggregator to stamp the `scaler` label on each
-     * kici_agent_* series. The label MUST be the backend type, not the
-     * operator-chosen scaler name: the Platform catalog filter constrains
-     * it to the ScalerBackendType set (plus `stateful`), so a free-form name is
-     * dropped as bad_label_value. `managedAgentIndex` stores the scaler
-     * name, so resolve it through `backends` to the type.
+     * AgentMetricsAggregator stamps it as the `scaler` label on each
+     * kici_agent_* series. It MUST be the type, not the operator-chosen name: the
+     * Platform catalog filter allows only the ScalerBackendType set (plus
+     * `stateful`) and drops anything else as bad_label_value.
      */
     getBackendType(agentId: string): string | null;
     /**
      * Exchange a provisioning claim code for freshly minted ephemeral credentials.
      *
-     * Reads the shared claim table directly rather than routing through the
-     * backend that minted the code: the mint needs only the agent-token store,
-     * which is already DB-backed, so redemption succeeds on an instance that has
-     * never heard of the emitting scaler. That is what lets an HA cluster front
-     * its coordinators with one shared endpoint — the provisioned agent reaches
-     * whichever coordinator the load balancer picks.
+     * Reads the shared claim table directly, not through the minting backend: the
+     * mint needs only the DB-backed agent-token store, so redemption works on an
+     * instance that never heard of the emitting scaler. That lets an HA cluster
+     * front its coordinators with one shared endpoint.
      *
-     * Returns `{ error }` when this instance has no claim store (no database), or
-     * when the redeem is rejected (unknown / consumed / expired / minting error).
-     * Called from the `scaler.claim-credentials` WS handler.
+     * Returns `{ error }` with no claim store (no database) or a rejected redeem
+     * (unknown / consumed / expired / minting error). Called from the
+     * `scaler.claim-credentials` WS handler.
      */
     claimScalerCredentials(code: string): Promise<{
         credentials?: ClaimedCredentials;
         error?: string;
     }>;
     /**
-     * Called from agent-handler.ts when an agent sends config.ack.
-     * For Firecracker agents, clears MMDS data (belt-and-suspenders with in-VM iptables).
-     * For non-Firecracker agents, this is a no-op.
+     * Called from agent-handler.ts on config.ack. Clears a Firecracker agent's MMDS
+     * data (belt-and-suspenders with in-VM iptables); a no-op for other agents.
      */
     onConfigAck(agentId: string): void;
-    /**
-     * Called when a scaler-managed agent completes a job.
-     */
+    /** Called when a scaler-managed agent completes a job. */
     onJobComplete(agentId: string): void;
     /**
-     * Correlate an agentId to a runId/jobId after the dispatcher assigns a job
-     * to a scaler-managed agent. Flushes any buffered pre-dispatch events.
+     * Correlate an agent to a runId/jobId after dispatch, flushing buffered
+     * pre-dispatch events.
      */
     correlateAgentToJob(agentId: string, runId: string, jobId: string): void;
-    /**
-     * Sum of all backends' active count + spawning agents.
-     */
+    /** Sum of all backends' active counts, which include spawning agents. */
     getGlobalActiveCount(): number;
     /**
      * Shut every backend down in parallel, waiting at most
@@ -1259,9 +1060,7 @@ export declare class ScalerManager {
      * when the window closes is logged by name and left to finish on its own.
      */
     private shutdownBackendsWithinGrace;
-    /**
-     * Stop warm pool, shutdown all backends, clear tracking maps.
-     */
+    /** Stop the warm pool, shut down all backends, clear tracking maps. */
     shutdownAll(): Promise<void>;
     /**
      * Classify every configured scaler against the currently loaded backends.
@@ -1272,22 +1071,18 @@ export declare class ScalerManager {
      * Validate the new config: label-set overlaps, backend type changes, and
      * each kept backend's own view of its label sets.
      *
-     * `backend.reload` validates and applies in one call, so a backend rejected
-     * late in the loop would otherwise leave the ones before it holding the new
-     * label sets and `maxAgents` while the commit never runs. Each successful
-     * call's previous state is therefore snapshotted and restored when any
-     * backend rejects — a rejected reload leaves every backend as it was.
-     *
-     * The snapshots are returned as well as used here: a later stage can still
-     * fail (an added scaler whose backend does not construct), and the same
-     * rollback is what keeps that rejection from half-applying too.
+     * `backend.reload` validates and applies in one call, so each successful
+     * call's previous state is snapshotted and restored if any backend rejects:
+     * a rejected reload leaves every backend as it was. The snapshots are also
+     * returned, so a later failing stage (an added backend that does not
+     * construct) can roll back the same way.
      */
     private validateReload;
     /** Put every backend a rejected reload had already mutated back as it was. */
     private restoreReloadedBackends;
     /**
-     * Construct every added backend into a staging list. On any failure the
-     * partially built set is torn down and the caller keeps the old config.
+     * Construct every added backend into a staging list; on any failure the
+     * partial set is torn down and the old config stays.
      */
     private buildAddedBackends;
     /**
@@ -1298,15 +1093,14 @@ export declare class ScalerManager {
      */
     private prepareAddedBackends;
     /**
-     * Refresh per-scaler metadata from the new config. Keys are deleted only for
-     * scalers that are neither configured nor retiring — a retiring scaler keeps
-     * its cap, URL, roles and defaults until its last agent is gone.
+     * Refresh per-scaler metadata. A retiring scaler keeps its cap, URL, roles and
+     * defaults until its last agent is gone.
      */
     private applyScalerMetadata;
     /**
-     * Register every configured machine pool with the ledger, building the
-     * ledger when this reload is the first config to declare a pool. `cap` is
-     * re-registered on every reload, so a changed cap applies without a restart.
+     * Register every configured machine pool, building the ledger when this reload
+     * first declares a pool. `cap` is re-registered every reload, so a changed cap
+     * applies without a restart.
      */
     private applyMachinePools;
     /** Rebuild the warm-pool config map from the new config (see WarmPoolManager.reload). */
@@ -1314,10 +1108,10 @@ export declare class ScalerManager {
     /**
      * Validate and reload configuration: plan → validate → build → commit.
      *
-     * Either the whole new config applies, or nothing does and the previous one
-     * keeps running. A scaler the new config no longer names is retired, not
-     * dropped: it stops taking work at once, its idle warm agents are destroyed,
-     * its job-bound agents finish, and its backend is torn down when it drains.
+     * All or nothing: a rejected config leaves the previous one running. A scaler
+     * the new config drops is retired: it stops taking work at once, its idle
+     * warm agents are destroyed, its job-bound agents finish, and its backend is
+     * torn down when it drains.
      */
     reload(newConfig: ScalerConfig): Promise<ScalerReloadResult>;
     /**
@@ -1325,199 +1119,149 @@ export declare class ScalerManager {
      * the commit, while the previous entries and global limits are still in place.
      */
     private describeReload;
-    /**
-     * Return status summary for metrics and health endpoints.
-     */
-    /**
-     * Recent scaler spawn failures grouped per backend instance, for the
-     * diagnose scaler check. `nowMs` is injected by the caller.
-     */
+    /** Recent spawn failures per backend instance, for the diagnose scaler check. */
     recentSpawnFailures(windowMs: number, nowMs: number): Map<string, BackendFailureSummary>;
+    /** Status summary for metrics and health endpoints. */
     getStatus(): ScalerStatus;
     /**
      * Scaler capacity advertised to peers in the cluster heartbeat.
      *
-     * Retiring backends are excluded: they accept no new work locally, so a peer
-     * that saw them would keep selecting this host for jobs it can no longer
-     * serve. Agents still draining on a retiring backend stay visible through the
-     * separate per-agent inventory, so in-flight work is unaffected.
+     * Retiring backends are excluded, or peers would keep selecting this host for
+     * jobs it can no longer serve. Their draining agents stay visible through the
+     * per-agent inventory, so in-flight work is unaffected.
      */
     getRoutableCapacity(): ScalerCapacitySummary[];
-    /**
-     * Get the backend name managing a specific agent.
-     * Returns null if the agent is not scaler-managed (standalone).
-     */
+    /** The scaler name managing an agent, or null for a standalone agent. */
     getBackendForAgent(agentId: string): string | null;
     /**
-     * Get a backend instance by scaler name. Returns undefined for an unknown
-     * name. Used by diagnostics to reach backend-specific accessors (e.g. the
-     * Firecracker backend's `getBridgeConfig()`).
+     * A backend by scaler name, for diagnostics reaching backend-specific
+     * accessors (e.g. the Firecracker backend's `getBridgeConfig()`).
      */
     getBackend(name: string): ScalerBackend | undefined;
     /**
-     * Whether some configured backend could spawn capacity for this label set —
-     * the same `findBackendForLabels` match `requestScale` makes, asked without
-     * spawning anything.
-     *
-     * Read by the queue-expiry sweep to tell a fleet/label problem apart from a
-     * capacity one: a job whose labels no agent AND no backend can serve could
-     * never have run (`unroutable`), while a job whose backend matched but whose
-     * spawn kept failing is a provisioning/capacity problem (`timed_out_stale`),
-     * and mislabelling the latter would tell an operator to fix a `runsOn` that
-     * is perfectly correct.
-     *
-     * Exact labels only — the scaler's own routing (`requestScale`) matches on
-     * exact labels, so a regex `runsOn` matcher is not expressible here. On a
-     * scaler-configured orchestrator that makes the answer conservative for a
-     * pattern-only `runsOn`: a backend whose labelSets carry no mandatory labels
-     * matches the empty exact set, so such a job is reported routable and settles
-     * `timed_out_stale` rather than `unroutable`. That loses precision, never
-     * safety — the job is still terminal and the run still fails, which is the
-     * invariant that matters. Tightening it means teaching scaler routing about
-     * patterns, which would change where jobs actually spawn.
+     * Whether some configured backend could spawn for this label set: the
+     * `findBackendForLabels` match `requestScale` makes, without spawning.
+     *
+     * The queue-expiry sweep uses it to separate a label problem (no agent AND no
+     * backend: `unroutable`) from a provisioning/capacity one (`timed_out_stale`),
+     * so an operator is not told to fix a correct `runsOn`.
+     *
+     * Exact labels only, as in `requestScale`, so a regex `runsOn` is not
+     * expressible. For a pattern-only `runsOn` a backend with no mandatory labels
+     * matches the empty set, so the job settles `timed_out_stale` instead of
+     * `unroutable`: less precise, never unsafe (the job is terminal and the run
+     * fails either way). Tightening it means teaching scaler routing about
+     * patterns, which would change where jobs spawn.
      */
     hasBackendForLabels(labels: string[], excludeLabels?: string[]): boolean;
     /**
-     * Get scaler-specific configuration metadata for a managed agent.
-     * Returns undefined for non-scaler-managed (static) agents.
-     * Used to enrich job.context before forwarding to Platform.
+     * Scaler-specific metadata for a managed agent (undefined for a static one),
+     * used to enrich job.context before forwarding to the Platform.
      */
     getScalerContextForAgent(agentId: string): Record<string, unknown> | undefined;
     /**
-     * Start the machine-pool ledger reaper and the retirement sweep that tears
-     * down drained retiring backends, and publish the warm-pool gauges so each
-     * pool's target is visible before its first fill.
-     *
-     * The warm pools themselves are NOT started here — see
-     * {@link startWarmPools}, which the host calls once every dependency a fill
-     * can reach is wired.
+     * Start the machine-pool ledger reaper and the retirement sweep, and publish
+     * the warm-pool gauges so each target is visible before its first fill. The
+     * warm pools themselves start in {@link startWarmPools}.
      */
     start(): void;
     /**
      * Run the warm pools' first deficit pass and arm their periodic tick.
-     *
-     * Separate from {@link start} because the first pass spawns immediately,
-     * and on an event backend a spawn emits through the event emitter — which
-     * the coordinator assigns after the scaler is built. The coordinator calls
-     * this once the emitter exists; the worker, which hosts no event backend,
-     * calls it right after `start()`.
+     * Separate from {@link start}: the first pass spawns at once, and an event
+     * backend's spawn needs the event emitter, which the coordinator assigns
+     * after building the scaler. The worker (no event backend) calls it right
+     * after `start()`.
      */
     startWarmPools(): void;
     /**
-     * Provision/heal every backend's host prerequisites before spawning starts.
-     * Awaits each backend's optional ensureHostReady, catching per-backend so one
-     * scaler's host-prep failure degrades only that scaler (its spawns will fail
-     * with clear errors + the firecracker-network diagnostic reports it) rather
-     * than aborting orchestrator startup.
+     * Provision/heal every backend's host prerequisites before spawning starts. A
+     * failure degrades only that scaler (its spawns fail with clear errors and
+     * the firecracker-network diagnostic reports it), never aborts startup.
      */
     ensureHostsReady(): Promise<void>;
     /**
      * The window a spawning entry may sit unregistered before it is pruned.
      *
-     * An entry cannot be stale before its own spawn deadline has passed, so the
-     * window is floored at the configured deadline: an operator raising
-     * `KICI_SCALER_SPAWN_TIMEOUT_MS` for a slow cloud must not have this prune
-     * fire first and drop the correlation a provision booting inside the raised
-     * deadline still needs. The floor only ever extends the window — a lowered
-     * deadline keeps the default five minutes, because a local backend's agent
-     * boots and registers well after `spawn()` itself returns.
+     * Floored at the configured spawn deadline, so raising
+     * `KICI_SCALER_SPAWN_TIMEOUT_MS` for a slow cloud never has the prune drop
+     * the correlation of a provision still booting inside it. A lowered deadline
+     * keeps the default five minutes: a local backend's agent registers well
+     * after `spawn()` returns.
      */
     private stalePruneWindowMs;
     /**
      * Remove spawning entries whose `backend.spawn` started longer ago than the
-     * stale window but never registered via WS (e.g., process/container crashed
-     * on startup). Without cleanup, these entries would leak in spawningAgents
-     * forever.
-     *
-     * The window is measured from `spawnStartedAt` (when the throttled spawn
-     * actually began), NOT from `spawnedAt` (enqueue time): a spawn still waiting
-     * behind the per-backend spawn semaphore has not started and must not be
-     * reaped mid-queue during a large burst. Recovered orphan entries carry
-     * `spawnStartedAt` set to their persisted enqueue time, so they are subject to
-     * the normal window.
-     *
-     * What happens to the durable row depends on the backend type the spawn
-     * recorded, which the entry carries so a scaler since removed from this
-     * coordinator's config still resolves. A local backend's
-     * compute is pinned to a host this process manages, so a pruned entry means
-     * the spawn is dead and the row goes. An event backend's row is the only
-     * durable pointer at a customer cloud instance, and it is precisely the
-     * reaper's `spawn-timeout` candidate — so the row STAYS, and the reaper
-     * decides. Deleting it here would beat the reaper by the flap grace on any
-     * coordinator serving jobs, so the teardown the row exists to trigger would
-     * never be emitted.
+     * stale window and never registered via WS (e.g. a crash on startup), which
+     * would otherwise leak forever.
+     *
+     * Measured from `spawnStartedAt`, NOT `spawnedAt` (enqueue): a spawn still
+     * queued behind the semaphore must not be reaped mid-burst. Recovered entries
+     * carry `spawnStartedAt` = their persisted enqueue time.
+     *
+     * The durable row's fate follows the backend type the spawn recorded. A local
+     * backend's pruned spawn is dead, so the row goes. An event backend's row is
+     * the only pointer at a customer cloud instance and is the reaper's
+     * `spawn-timeout` candidate, so it STAYS: deleting it would beat the reaper by
+     * the flap grace and the teardown would never be emitted.
      */
     private pruneStaleSpawningEntries;
     /**
      * The spawn row for one agent, as every writer of it must build it.
      *
-     * Ownership and self-describing columns are assembled only here.
-     * `backend_type` is what `adoptSpawningAgent`'s conditional UPDATE matches
-     * on, so a row without it can never be adopted by any instance — including
-     * the one that spawned it. `owner_instance_id` scopes recovery to that
-     * instance, and `mandatory_labels` carries the platform taint to a
-     * coordinator that has no config entry for this scaler and can therefore
-     * derive it from nothing else. `provisioning_targets` is the same story for
-     * teardown: it is the only address such a coordinator has for the customer's
-     * teardown workflow, and an emit to an empty target list reaches nobody, so
-     * the provision would bill forever. `roles` travels with it so the row stays
-     * a complete description of the spawn.
+     * Ownership and self-describing columns are assembled only here:
+     * `backend_type` is what `adoptSpawningAgent`'s conditional UPDATE matches, so
+     * a row without it is never adoptable; `owner_instance_id` scopes recovery;
+     * `mandatory_labels` and `provisioning_targets` give a coordinator with no
+     * config entry for the scaler its platform taint and its only teardown
+     * address (an empty target list reaches nobody, so the provision would bill
+     * forever); `roles` keeps the row a complete description of the spawn.
      */
     private spawningAgentSnapshot;
     /**
      * Claim one slot against an event scaler's cluster-wide `maxAgents`.
      *
-     * The count and the claim share a single advisory-locked transaction, so the
-     * row this writes is already visible to the next coordinator that takes the
-     * lock. A store failure is never an admission: returning false costs a job a
-     * queue wait, while admitting on a count nobody recorded provisions a cloud
-     * instance the cap cannot see. Failing closed is not silent — a refusal
-     * increments the spawn-refusal counter and a store failure its own counter,
-     * labelled so a database outage, a contended lock, and a full cluster are
-     * three distinguishable things rather than one.
-     *
-     * The failure arm bounds the admission, not the row: a transaction that
-     * commits and then loses its acknowledgement leaves `slotClaimed` false, so
-     * neither rollback path fires and the row counts against the cap for an
-     * agent that never spawned. Closing that window needs two-phase commit; the
-     * event-provision reaper is the backstop, clearing the row once the spawn
-     * deadline passes with nothing adopted.
+     * Count and claim share one advisory-locked transaction, so the row is visible
+     * to the next coordinator taking the lock. A store failure never admits:
+     * refusing costs a queue wait, admitting provisions an instance the cap
+     * cannot see. Refusals and store failures are counted, labelled so a database
+     * outage, a contended lock and a full cluster are distinguishable.
+     *
+     * A transaction that commits but loses its acknowledgement leaves
+     * `slotClaimed` false, so the row counts against the cap for an agent that
+     * never spawned. Closing that needs two-phase commit; the event-provision
+     * reaper is the backstop, clearing the row once the spawn deadline passes
+     * with nothing adopted.
      */
     private claimClusterSlot;
     private persistSpawningAgent;
     private deleteSpawningAgentFromStore;
     /**
-     * Stamp `adopted_by = this instance` on the spawning row of an agent that just
-     * registered here. Reuses the cross-instance conditional UPDATE, so a row some
-     * other instance already claimed is left exactly as it is.
+     * Stamp `adopted_by = this instance` on a just-registered agent's row, via the
+     * conditional UPDATE, so a row another instance claimed is left as it is.
      */
     private markSpawningAgentAdopted;
     /**
      * Record that `backend.spawn()` resolved for a spawn this instance started.
      *
-     * Returns false when the stale-spawn prune dropped the entry while
-     * `spawn()` was still running (a per-org spawn deadline can outlast the
-     * prune window). Nothing else would ever tear that compute down, so a local
-     * backend's is destroyed here. An event backend's provision is left to the
-     * reaper, as the prune leaves it.
+     * False when the prune dropped the entry while `spawn()` ran (a per-org
+     * deadline can outlast the prune window). Nothing else would tear that
+     * compute down, so a local backend's is destroyed here; an event provision is
+     * left to the reaper.
      */
     private onSpawnSettled;
     /**
      * Drop a settled local spawn whose backend reported it failed.
      *
-     * After `spawn()` resolved, a backend that finds its compute gone before the
-     * agent registered (a Firecracker guest that exited, a bare-metal agent
-     * process that exited) tears the compute down itself and emits
-     * `scaler.failed`. The agent will never register, so the spawning entry, its
-     * durable row and its reservation go now — waiting for the stale-spawn prune
-     * would hold the scaler's slot for minutes.
+     * A backend whose compute dies before registration (a Firecracker guest or a
+     * bare-metal agent process that exited) tears it down and emits
+     * `scaler.failed`. The entry, durable row and reservation go now; waiting
+     * for the prune would hold the slot for minutes.
      *
-     * A spawn that produced no agent is a refused launch, the same rule an event
-     * scaler's dead provision follows: the scaler is deferred before the
-     * reservation is freed, so an agent that dies at startup every time is not
-     * respawned at its own startup cadence. Only a spawn that has not registered
-     * reaches here — registration deletes the spawning entry — so an agent that
-     * registered and exits later never arms the backoff.
+     * Like an event scaler's dead provision, it is a refused launch: the scaler is
+     * deferred before the reservation is freed, so an agent dying at every
+     * startup is not respawned at its startup cadence. Only an unregistered spawn
+     * reaches here, so an agent that exits after registering never arms the
+     * backoff.
      */
     private dropFailedSettledSpawn;
     /** Store-side half of the stale prune: drops the row only if nobody adopted it. */
@@ -1527,75 +1271,61 @@ export declare class ScalerManager {
     private persistAgentJob;
     private deleteAgentJobFromStore;
     /**
-     * Hydrate the in-memory Maps from the DB-backed state store after a
-     * coord boot or Raft leader switch. Reconstructs:
+     * Hydrate the in-memory maps from the state store after a coordinator boot
+     * or Raft leader switch:
      *
-     *   - `spawningAgents` (with `boundJobId` preserved for eager-dispatch on register)
+     *   - `spawningAgents` (with `boundJobId` for eager-dispatch on register)
      *     — event-backend rows only; a local-backend row is dropped, see below
      *   - `agentJobCorrelation` (so scaler-lifecycle events route correctly)
-     *   - `reservations` + `perScalerUsage` (so the cap-check critical
-     *     section reflects the cluster-wide truth, not the local empty
-     *     starting state)
+     *   - `reservations` + `perScalerUsage` (so the cap check sees the real
+     *     state, not an empty start)
      *
-     * The `globalUsage` counter is recomputed from `perScalerUsage` to
-     * keep the cap math consistent. `eventBuffer` is NOT restored — events
-     * emitted by the previous coord before correlation are lost (they are
-     * observability, not correctness: nothing downstream waits on them).
+     * `globalUsage` is recomputed from `perScalerUsage`. `eventBuffer` is NOT
+     * restored: its events are observability, and nothing waits on them.
      *
-     * Both reads are scoped to this instance's own rows. An unscoped read
-     * hydrates a peer's in-flight spawns and reservations as our own, so our
-     * spawn-timeout reaper destroys agents that peer is still legitimately
-     * waiting on and our caps double-count its reservations. Rows owned by a
-     * dead instance are the leader-gated reaper's business, not ours.
-     *
-     * No-op when no store is wired (unit-test path).
+     * Both reads are scoped to this instance's own rows. An unscoped read would
+     * hydrate a peer's in-flight spawns as ours, so our spawn-timeout reaper
+     * destroys agents the peer still waits on and our caps double-count. A dead
+     * instance's rows belong to the leader-gated reaper. No-op with no store.
      */
     recoverState(): Promise<ScalerStateRecovery>;
     /**
-     * Mint a scaler-managed agent id.
-     *
-     * Built from {@link SCALER_AGENT_ID_PREFIX} rather than a second copy of the
-     * literal: the registration guard in `onAgentRegistered` recognises a
-     * scaler-managed agent by that prefix alone when the spawn-record lookup
-     * fails, so a minting prefix that drifts from the constant leaves the guard
-     * matching nothing and failing open.
+     * Mint a scaler-managed agent id from {@link SCALER_AGENT_ID_PREFIX}, never a
+     * copy of the literal: `onAgentRegistered`'s guard recognises scaler agents by
+     * that prefix alone when the spawn-record lookup fails, so a drifted prefix
+     * would fail open.
      */
     private generateAgentId;
     /**
-     * Start log forwarding for a scaler-managed agent if its backend supports LogCapture.
-     * Fire-and-forget: the forward() promise runs for the agent's lifetime.
+     * Start log forwarding if the backend supports LogCapture. Fire-and-forget:
+     * forward() runs for the agent's lifetime.
      */
     private startLogForwarding;
     private getOrchestratorUrl;
     /**
-     * Create a per-agent event emitter closure to pass to backend.spawn().
-     * The closure captures agentId and routes events through handleScalerEvent().
+     * Per-agent event emitter for backend.spawn(), routing through
+     * handleScalerEvent().
      */
     private createEventEmitter;
     /**
      * Handle a scaler event from a backend.
      *
-     * For spawn FAILURES the bound spawning entry is the usual resolver, since
-     * correlation isn't set until a job is dispatched post-registration. The
-     * correlation map wins only in the rarer post-registration failure window
-     * (e.g. a bare-metal child 'error' firing after the agent already
-     * registered, by which point the spawning entry is gone). Warm-pool /
-     * unbound spawns resolve to neither. When attributed, the event is relayed
-     * immediately; otherwise it is buffered until correlateAgentToJob() flushes
-     * it.
-     *
-     * Every `scaler.failed` also increments the fleet-wide spawn-failure counter
-     * and emits a structured warn, regardless of whether it could be attributed.
-     * The backend label is resolved from the spawning entry first, then the
-     * managed-agent index — so a late failure after the spawning entry is gone
-     * still buckets under the real backend instead of "unknown".
-     *
-     * `attribution` is the last resort for a failure this coordinator did not
-     * spawn and never registered: the reaper is leader-gated, so the instance that
-     * condemns a stranded external provision routinely has neither a spawning
-     * entry nor a managed-agent index row for it, and every in-memory resolver
-     * above comes back empty. It is read only where the maps are silent, so a live
-     * local entry always wins over a durable row that may be a sweep behind.
+     * A spawn FAILURE usually resolves through the bound spawning entry, since
+     * correlation is set only at dispatch. The correlation map wins in the rarer
+     * post-registration window (e.g. a bare-metal child 'error' after
+     * registration, when the spawning entry is gone). Unbound spawns resolve to
+     * neither. An attributed event is relayed at once; otherwise it is buffered
+     * until correlateAgentToJob() flushes it.
+     *
+     * Every `scaler.failed` increments the fleet-wide spawn-failure counter and
+     * warns, attributed or not. The backend label comes from the spawning entry,
+     * then the managed-agent index, so a late failure still buckets under the
+     * real backend, not "unknown".
+     *
+     * `attribution` is the last resort for a failure this coordinator neither
+     * spawned nor registered (typical for the leader-gated reaper). It is read
+     * only where the maps are silent, so a live local entry beats a durable row
+     * that may be a sweep behind.
      */
     private handleScalerEvent;
 }